Repository navigation
feat: background service, keychain, logs, doctor and release binaries - #15
Conversation
A bun build --compile binary carries no files beside it, so reading schemas/v1 from disk at run time crashed every command that validates a message. The schemas are now imported statically; the existing test that compiles every schema file keeps the list complete. The release workflow builds macOS, Linux and Windows binaries with checksums and keeps them as workflow artifacts. It publishes nothing. Proved by test/binary.test.ts: it failed in loadValidators before the change and passes after.
Credentials go in the macOS keychain (security, secret on stdin) or the Secret Service (secret-tool), named per Tether home so two homes never replace each other's items. When the keychain refuses, the credential stays in the 0600 file as before; a keychain that cannot be read says to unlock it rather than to pair again. start moves file credentials into the keychain. Proved by test/keychain.test.ts (each path, with fake security and secret-tool runners) and a connect test through the CLI.
The worker appends one line per finished task to tasks.jsonl (0600): app, the task's type, id, title, duration, reported cost and how it ended (complete, fail with its reason, left, or not reported). The log keeps its last 1000 tasks once it passes about 1 MB, and a line torn by a crash does not swallow the next one. tether logs prints it with app text cleaned. Proved by the tether logs tests in test/cli.test.ts and the task log tests in test/store.test.ts.
doctor checks that Claude Code is installed, signed in (claude auth status, reading only the yes or no) and accepts every flag the adapter passes, and that each connected app answers and still accepts this device: a GET for a task id no app issues returns 404 for a working credential and 401 for a revoked one. On the checked Claude Code version every flag passes; on another, a flag missing from claude --help fails and the one flag --help hides only warns. The adapter exports its flag list so the doctor cannot drift from it. Proved by the tether doctor tests, which run the fake claude as a missing binary, a signed-out install and an older version.
tether service install|uninstall|status runs tether start now and at every login: a launchd agent on macOS, a systemd user unit on Linux, and on Windows a Task Scheduler task with no time limit and restart on failure, started through a wrapper that sets the variables Task Scheduler cannot. The service carries PATH and Tether's own variables, never an Anthropic key, and is named per Tether home so a test or a second home cannot replace a real install. Proved by snapshot tests of the unit, plist, task XML and wrapper, the command sequences on each OS through a fake runner, and a real launchd install that completes a task and is removed again (run on the macOS CI runner; a Windows CI job installs and removes a real task).
The runner context is not available in a job's env, which made the whole release workflow invalid.
dryer found the two parsers identical in shape (score 1.00). The concurrency and logs usage tests still pass.
crapper put client/run.ts run at CRAP 20 (no test called it: the keychain and service tests inject fakes) and cli/main.ts service at 11.6. run now has a test of its stdin, status and outputs, and the install branch of service is its own function.
Mutation testing found gaps, now covered: - the task log could gain blank lines (an empty or new file) - a keychain record read or an app removed with no keychain at all - systemd failures that print only stdout or nothing - a newer Claude Code whose --help lists every flag - a logged duration counted wrong doctor now says it cannot tell when claude auth status gives no JSON answer (an older Claude Code), instead of reporting the user signed out. TaskResult.abandoned is gone: nothing read it, and ended carries the same fact. parseCount relies on parseArgs rejecting positionals.
|
Ready for review. CI and the release dry run pass on the last commit; the gate numbers and what I could not verify are in the description. |
parsilver
left a comment
There was a problem hiding this comment.
Verdict: no Blocker. Merging.
Verified: typecheck and lint are clean, and vitest gives 378 passed, 1 skipped (the opt-in real launchd test). The tether-binaries artifact matches SHA256SUMS for all 5 files. tether-darwin-arm64 runs here: apps exits 0, doctor prints a clear FAIL line and exits 1, logs exits 0. Secrets reach security -i and secret-tool on stdin, never in argv, and nothing goes through a shell. Unit, plist and .cmd files are 0600, per user, and hold no secret. The release workflow is workflow_dispatch plus pull_request with contents: read, it has no publish or npm step, and its action SHAs match their tags.
Suggestion (follow-up issue)
src/cli/doctor.ts:37:store.apps()throws when the keychain is locked, sodoctorstops before it reports anything. Catch the error and print a FAIL line.store.tssaveApp/moveToKeychain,main.tsconnect: falling back tocredentials.jsonis safe (0600), but it is silent, or not marked as a warning. Warn and give the reason.src/cli/service.ts:121-135,230:service.loghas no size limit or rotation, the service restarts every 30 s whenclaudeis missing, and an existing log keeps its old permissions.src/cli/service.ts:137-138: runningbootstrapright afterbootoutcan fail with "Bootstrap failed: 5" on reinstall. Retry or wait.- No test reads the keychain from inside the service: every CI and service test sets
TETHER_KEYCHAIN=off. A locked keyring at boot would turn into a restart loop. Run one manual check before the first release.
Nit
store.tslogTask: cap the storedtitlelength.worker.ts: iflogTaskthrows inside.then, the task is logged twice and the reservation release is skipped.service.ts:171-172:network-online.targetdoes nothing in a user unit.release.yml:19: setpersist-credentials: false.
Closes #4
Background service, keychain storage, task logs,
tether doctor, and a release workflow that builds the binaries. Following the scope comment on the issue, this round builds and proves things and publishes nothing.Acceptance
Release workflow produces all binaries and checksums.
.github/workflows/release.ymlruns onworkflow_dispatch. It also runs on pull requests that change it, so this PR carries the dry run. One Ubuntu job buildstether-darwin-arm64,tether-darwin-x64,tether-linux-x64,tether-linux-arm64andtether-windows-x64.exewithbun build --compile, smoke-runs the Linux x64 binary, writesSHA256SUMS, and uploads everything as thetether-binariesartifact. It creates no GitHub Release and publishes nothing to npm. A second job runs the Windows binary onwindows-latest(see below). Run 43588269246 passed (and again as 43591112218 on the last commit). The checksums from 43588269246:This needed one fix first. The binaries crashed on every command that validates a message, because
src/protocol/schemas.tsreadschemas/v1/from disk. The schemas are now imported statically.test/binary.test.tscompiles the CLI and runs it; it failed inloadValidatorsbefore the fix. The existing "compiles every schema file" test fails if a new schema is not imported.tether doctorreports a missing or signed-out agent CLI clearly (fake binary). The fakeclaudegained--helpandauth status, plus two variants picked by the name it runs under:claude-signed-outandclaude-old(2.0.9, whose--helplacks--restricted). The tests intether doctorcover:FAIL Claude Code was not found at ... Install it, then run: claude auth login, exit 1FAIL Claude Code is not signed in. Run: claude auth login, exit 1FAILon the missing flag, and only awarnfor--append-system-prompt-file, whichclaude --helphides in 2.1.325Pair again: tether connect ...The app check asks for a task id no app issues. A 404 means the credential works and a 401 means it was revoked, so it sends no heartbeat and changes nothing at the app. The signed-in check reads only
loggedInfromclaude auth status --jsonand never prints the account.Service install and uninstall tested on macOS; Linux unit file covered by a snapshot test.
test/service-real.test.tsruns on the macOS CI runner (TETHER_REAL_SERVICE=1). It pairs with the fake app, installs a real launchd agent and waits until that agent completes a task. That is the proof launchd really runstether start. It then checksservice statusandtether logs, uninstalls, and checks thatlaunchctl printfails and the plist is gone. I also ran it once on my Mac; it passed, and nothing was left in~/Library/LaunchAgents.windows-smokejob installs a real Task Scheduler task from the binary. The task's wrapper rantether startwithTETHER_HOMEandTETHER_CLAUDE_PATHcarried through, which shows inservice.log. It then uninstalls and checksnot installed.What changed
src/client/keychain.ts,src/client/store.ts: device credentials go in the macOS keychain (throughsecurity) or the Secret Service (throughsecret-tool). The secret goes on stdin, never in argv. When the keychain refuses, the credential falls back to the 0600credentials.jsonas before.startmoves file credentials into the keychain.tetherfor~/.tether,tether-<hash>otherwise. A test or a second home therefore never replaces a real install.TETHER_KEYCHAIN=offkeeps credentials in the file. The test suite sets it.src/cli/service.ts:tether service install|uninstall|status.KeepAliveon failure and a 30 s throttle. Its log isservice.login the Tether home, created 0600 before launchd opens it.Restart=on-failure..cmdwrapper sets the variables, because Task Scheduler cannot.PATH,TETHER_HOME,TETHER_CLAUDE_PATHandTETHER_KEYCHAIN, never an Anthropic key. Install warns when one is set.tether logs [--limit n]: the worker appends one line per finished task totasks.jsonl(0600). Each line has the app, the task'stype, id, title, duration, reported cost, and how the task ended:complete,fail: <reason>,left, or(not reported)when the report never reached the app.docs/claude-code-flags.md, which now says how doctor checks flags.Commands run
bun run lint: clean.bun run typecheck: clean.check (ubuntu-latest)378 passed and 1 skipped (the macOS-only real service test),check (macos-latest)379 passed. The local full run could not get one of this machine's shared heavy slots, so local runs were targeted at the changed areas.TETHER_REAL_SERVICE=1 npx vitest run test/service-real.test.tson macOS: 1 passed (4.6 s).check (ubuntu-latest)andcheck (macos-latest)pass; the Release run withbinariesandwindows-smokepasses.Quality gates
Run locally on the changed files. Coverage came from the tests that exercise them, because no heavy slot was free.
CRAP: every function this PR adds or changes is under 10. The highest are
must(9.7),finishandreportFor(9.0) andstart(8.3).runinclient/run.tswas at 20 because nothing called it; it now has its own test.serviceincli/main.tswas at 11.6; the install branch is now a separate function.sessionProblem,taskkillTreeandStreamParser.assistant. This PR does not touch them, and their tests were outside the subset.dryer: clean. It found one duplicate,
parseConcurrencyand the newparseLimit(score 1.00), now merged intoparseCount.mutator, on the new and changed code:
doctor.ts: 22 of 22 killed.service.ts: 15 of 16 killed.keychain.tsandrun.ts: all but the equivalents listed below.store.ts,worker.ts,run-task.tsandmain.ts(parseCount, logs): all killed except the equivalents.The mutants killed along the way exposed real gaps, now tested: blank lines in the task log, a keychain record with no keychain, an older Claude Code without
auth status(it was reported as signed out), and a duration counted wrong. They also showed thatTaskResult.abandonedwas dead code, so it is deleted.Survivors left, with reasons:
status ?? "timeout"→||inkeychain.ts:32,keychain.ts:66andservice.ts:59: equivalent. The status there is never 0, because those lines only run on a failure.?? ""→||inrun.ts:15andrun.ts:19: equivalent, since the empty string maps to the empty string either way.raw?.apps ?? [](store.ts:143): equivalent; the array is never falsy.> 1 MBversus>=(store.ts:226): the boundary byte does not matter.??fallbacks for the injected test seams inmain.ts(io.keychain,io.program,io.userHome,USERDOMAIN): equivalent for non-empty values.costUsd ?? null→||(worker.ts:297) differs only for a task that reports exactly $0. It would show-instead of$0.0000; I left it.makeHome, the reservation inworker.ts:303,localDate,usage) is covered by the CLI tests outside the subset.Risks
credential_in: keychainwould then fail to load under the old code and needtether connectagain. Revert before release, or pair again.ci.ymlgains a macOS job, a new release workflow is added, and both pin their actions by SHA withcontents: read. Worth a human look.securityandsecret-toolrather thanBun.secrets. That keepssrc/on Node APIs, which Vitest needs, and keeps the store synchronous. The cost is Windows Credential Manager: Windows keeps the 0600 file.Not verified
schtasks /Run.claudeis a Node script and Windows cannot spawn it directly. The Linux CI job runs that path for real ("claims a task, runs it in an isolated session and reports it complete with usage").