Skip to content

feat: background service, keychain, logs, doctor and release binaries - #15

Merged
parsilver merged 12 commits into
mainfrom
feat/4-background-service-keychain-logs
Nov 14, 2026
Merged

parsilver merged 12 commits into
mainfrom
feat/4-background-service-keychain-logs

Conversation

@parsilver

@parsilver parsilver commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

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.yml runs on workflow_dispatch. It also runs on pull requests that change it, so this PR carries the dry run. One Ubuntu job builds tether-darwin-arm64, tether-darwin-x64, tether-linux-x64, tether-linux-arm64 and tether-windows-x64.exe with bun build --compile, smoke-runs the Linux x64 binary, writes SHA256SUMS, and uploads everything as the tether-binaries artifact. It creates no GitHub Release and publishes nothing to npm. A second job runs the Windows binary on windows-latest (see below). Run 43588269246 passed (and again as 43591112218 on the last commit). The checksums from 43588269246:

    e4fa06f7a76943bf06617f8045bdb905c6911610fe94767f4036c80daeb6bae4  tether-darwin-arm64
    2a79c81f2e2eb18f8eef3655b31da12a87437a4f0ef03e9847927265851ffd37  tether-darwin-x64
    c11500868cdf5ed7b8d709a85e3e1b9f0e504e4fe289913431daf39d82e8d2f7  tether-linux-arm64
    397cda443485163e02d5742aa8343e0874fe4db343a0cd15466dfe816d9ff979  tether-linux-x64
    153b8b37c5d0dbc1fbcd5c29fff5e20d7ed9279eb60d30e4c06a01012bd2ad16  tether-windows-x64.exe
    

    This needed one fix first. The binaries crashed on every command that validates a message, because src/protocol/schemas.ts read schemas/v1/ from disk. The schemas are now imported statically. test/binary.test.ts compiles the CLI and runs it; it failed in loadValidators before the fix. The existing "compiles every schema file" test fails if a new schema is not imported.

  • tether doctor reports a missing or signed-out agent CLI clearly (fake binary). The fake claude gained --help and auth status, plus two variants picked by the name it runs under: claude-signed-out and claude-old (2.0.9, whose --help lacks --restricted). The tests in tether doctor cover:

    • a missing binary: FAIL Claude Code was not found at ... Install it, then run: claude auth login, exit 1
    • a signed-out install: FAIL Claude Code is not signed in. Run: claude auth login, exit 1
    • an older version: FAIL on the missing flag, and only a warn for --append-system-prompt-file, which claude --help hides in 2.1.325
    • a revoked device: Pair again: tether connect ...
    • an app that cannot be reached
    • a healthy run, exit 0

    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 loggedIn from claude auth status --json and never prints the account.

  • Service install and uninstall tested on macOS; Linux unit file covered by a snapshot test.

    • macOS: test/service-real.test.ts runs 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 runs tether start. It then checks service status and tether logs, uninstalls, and checks that launchctl print fails and the plist is gone. I also ran it once on my Mac; it passed, and nothing was left in ~/Library/LaunchAgents.
    • Linux: an inline snapshot of the systemd user unit, plus the install, status and uninstall command sequence through a fake runner.
    • Windows: the release workflow's windows-smoke job installs a real Task Scheduler task from the binary. The task's wrapper ran tether start with TETHER_HOME and TETHER_CLAUDE_PATH carried through, which shows in service.log. It then uninstalls and checks not installed.

What changed

  • src/client/keychain.ts, src/client/store.ts: device credentials go in the macOS keychain (through security) or the Secret Service (through secret-tool). The secret goes on stdin, never in argv. When the keychain refuses, the credential falls back to the 0600 credentials.json as before.
    • A keychain that cannot be read (locked, no session bus) says to unlock it, not to pair again.
    • start moves file credentials into the keychain.
    • Items and services are named per Tether home: tether for ~/.tether, tether-<hash> otherwise. A test or a second home therefore never replaces a real install.
    • TETHER_KEYCHAIN=off keeps credentials in the file. The test suite sets it.
  • src/cli/service.ts: tether service install|uninstall|status.
    • macOS: a launchd agent with KeepAlive on failure and a 30 s throttle. Its log is service.log in the Tether home, created 0600 before launchd opens it.
    • Linux: a systemd user unit with Restart=on-failure.
    • Windows: a Task Scheduler task created from XML, with no execution time limit (the default kills a task after 3 days), restart on failure and a logon trigger. A .cmd wrapper sets the variables, because Task Scheduler cannot.
    • The service carries PATH, TETHER_HOME, TETHER_CLAUDE_PATH and TETHER_KEYCHAIN, never an Anthropic key. Install warns when one is set.
    • Install refuses when no app is connected.
  • tether logs [--limit n]: the worker appends one line per finished task to tasks.jsonl (0600). Each line has the app, the task's type, id, title, duration, reported cost, and how the task ended: complete, fail: <reason>, left, or (not reported) when the report never reached the app.
    • Once the file passes about 1 MB it keeps the last 1000 tasks.
    • A line torn by a crash no longer swallows the next one; a test caught that bug.
    • App text is cleaned before it is printed.
  • CI runs on Ubuntu and macOS.
  • Docs: README, AGENTS.md, and docs/claude-code-flags.md, which now says how doctor checks flags.

Commands run

  • bun run lint: clean. bun run typecheck: clean.
  • Full suite: CI run 43591112247 on the last commit, 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.ts on macOS: 1 passed (4.6 s).
  • CI on this PR: check (ubuntu-latest) and check (macos-latest) pass; the Release run with binaries and windows-smoke passes.

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), finish and reportFor (9.0) and start (8.3).

    • Two were fixed along the way. run in client/run.ts was at 20 because nothing called it; it now has its own test. service in cli/main.ts was at 11.6; the install branch is now a separate function.
    • Three functions read above 10 in this partial coverage: sessionProblem, taskkillTree and StreamParser.assistant. This PR does not touch them, and their tests were outside the subset.
  • dryer: clean. It found one duplicate, parseConcurrency and the new parseLimit (score 1.00), now merged into parseCount.

  • mutator, on the new and changed code:

    • doctor.ts: 22 of 22 killed.
    • service.ts: 15 of 16 killed.
    • keychain.ts and run.ts: all but the equivalents listed below.
    • The changed lines in store.ts, worker.ts, run-task.ts and main.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 that TaskResult.abandoned was dead code, so it is deleted.

    Survivors left, with reasons:

    • status ?? "timeout" → || in keychain.ts:32, keychain.ts:66 and service.ts:59: equivalent. The status there is never 0, because those lines only run on a failure.
    • ?? "" → || in run.ts:15 and run.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.
    • The trim at > 1 MB versus >= (store.ts:226): the boundary byte does not matter.
    • The ?? fallbacks for the injected test seams in main.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.
    • Pre-existing code that moved or sits next to changed lines (makeHome, the reservation in worker.ts:303, localDate, usage) is covered by the CLI tests outside the subset.

Risks

  • Credential storage: this changes where device credentials live, so it is on the risk list.
    • To roll back, revert the PR. Records written as credential_in: keychain would then fail to load under the old code and need tether connect again. Revert before release, or pair again.
    • The keychain path was checked for real only through the macOS CLI probe, by hand. CI covers the Secret Service and macOS backends with a fake runner, not with a real keyring.
  • Shared surfaces: ci.yml gains a macOS job, a new release workflow is added, and both pin their actions by SHA with contents: read. Worth a human look.
  • Plan review choices:
    • I kept one PR, as the job asked, in commits per piece. The review suggested four PRs.
    • The keychain uses security and secret-tool rather than Bun.secrets. That keeps src/ on Node APIs, which Vitest needs, and keeps the store synchronous. The cost is Windows Credential Manager: Windows keeps the 0600 file.

Not verified

  • The Secret Service path on a real Linux keyring, and a systemd user unit actually started by systemd. The Ubuntu CI runner has no user session bus; Linux is covered by the snapshot and the command-sequence test.
  • On Windows: a logon in a desktop session, and whether the wrapper's console window shows. CI ran the task from schtasks /Run.
  • Running the macOS and Linux arm64 and x64 binaries other than Linux x64: they were built and checksummed, not run.
  • npm packaging and code signing: out of scope this round.
  • The Windows smoke task the owner asked for "if CI can". The full task path, claim and run against the fake app, did not get a Windows run: the fake claude is 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").

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.
@parsilver
parsilver marked this pull request as ready for review November 14, 2026 11:50
@parsilver

Copy link
Copy Markdown
Contributor Author

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 parsilver left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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, so doctor stops before it reports anything. Catch the error and print a FAIL line.
  • store.ts saveApp / moveToKeychain, main.ts connect: falling back to credentials.json is 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.log has no size limit or rotation, the service restarts every 30 s when claude is missing, and an existing log keeps its old permissions.
  • src/cli/service.ts:137-138: running bootstrap right after bootout can 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.ts logTask: cap the stored title length.
  • worker.ts: if logTask throws inside .then, the task is logged twice and the reservation release is skipped.
  • service.ts:171-172: network-online.target does nothing in a user unit.
  • release.yml:19: set persist-credentials: false.

@parsilver
parsilver merged commit 060fbe4 into main Nov 14, 2026
4 checks passed
@parsilver
parsilver deleted the feat/4-background-service-keychain-logs branch November 14, 2026 12:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

release: background service, keychain, logs, doctor and binaries

1 participant