Repository navigation
fix: harden doctor, keychain fallback and service log - #17
Merged
Merged
Conversation
Reinstalling over a running agent failed: bootout returns before the old agent has stopped, and bootstrap refuses until it has. Bootstrap is now tried up to ten times, a second apart, and reports the last error. An existing service.log is set to 0600 on install, not only a new one. The systemd unit no longer orders itself after network-online.target, which a user unit cannot reach, and the release checkout drops the job token. Tested with the service tests: retry after bootout exit 36, give-up after ten tries, a 0644 log made 0600, the unit snapshot, and a check that every release checkout sets persist-credentials: false.
doctor now prints a FAIL line with the store's reason when the keychain holding a credential cannot be read, instead of exiting with a bare error. Keychain.set returns why it refused a secret, and connect and start warn with that reason when the credential stays in credentials.json. security -i reports only its exit status, since its stdin carries the secret. The task log keeps at most 200 characters of an app's title. A task log that cannot be written no longer skips releasing the task's slot and budget reservation: the outcome is settled first, the reservation released, and the log write fails on its own line, once. tether start cuts service.log to its last 1 MB once it passes 5 MB, at start and every ten minutes; not on Windows, where cmd's >> keeps its offset. Tested with new keychain, store and CLI tests, each seen failing first.
8 tasks
A mutation run showed the optional chain on the first stderr line was never needed and nothing checked that later lines are dropped. The reason now keeps the first line by replacing the rest, and a test pins both a multi-line and an empty stderr.
Mutation runs left two gaps: a log of exactly 5 MB was not checked to stay whole, and nothing checked that a finished task adds what it reported spending rather than its reserved budget. Both are pinned now; the mutants on those lines are killed.
start had grown two loops for the keychain warnings and the redactor. They move with the empty check into connectedApps, which brings start's CRAP score from 19.1 to 6.6 on the targeted coverage run. Behaviour is unchanged: the start and keychain tests pass as before.
parsilver
marked this pull request as ready for review
November 14, 2026 13:36
parsilver
commented
Nov 15, 2026
parsilver
left a comment
Contributor
Author
There was a problem hiding this comment.
Verdict: no Blocker. Merging.
Reviewed at 728addf, with a separate security review. CI is green on Linux, macOS and Windows.
- Secrets: for
security -i, only the exit status reaches a warning, and a test hassecurityecho its stdin to stderr.secret-toolgets the secret on stdin and doesn't echo it.startprints nothing before it adds the credentials to the redactor. - Fallback: a refused secret goes to
credentials.jsonthrough a 0600 temp file and a rename. Platforms where the file is the intended store get no warning. - Log trim: the
startprocess is the only writer toservice.log, so a synchronous trim from a line start cannot interleave with writes. Windows is skipped, with the reason. - Bootstrap retry: launchd allows one job per label, so two agents can't run at once.
- release.yml:
pull_requeston its own path only,contents: read, no secrets, and actions pinned by SHA.
Suggestions (filed as a follow-up)
store.ts:126viadoctor.ts:41: aJSON.parseerror can quote part of a corruptcredentials.json. Print only "could not be read (invalid JSON)".keychain.ts:60/93: whensecret-toolis missing, the warning says "exited timeout". Say "could not run".cli.test.ts:417: make the fake keychain's reason echo the secret, soexpectNoSecretsproves thatstartredacts.cli.test.ts:848: callexpectNoSecretsin the doctor FAIL test.store.ts:282,service.ts:141: open withO_NOFOLLOW, for aTETHER_HOMEset to a shared folder.
5 of 6 tasks
parsilver
added a commit
that referenced
this pull request
Nov 16, 2026
* test: pin doctor, keychain and symlink follow-ups from the #17 review Each test fails on main: doctor quotes the parser's text for a corrupt credentials.json, a tool that cannot start reads as exited timeout, and the credential temp file and service.log are written through a symlink. * fix: redact corrupt-JSON reads, name how a tool ended, refuse symlinks doctor now says credentials.json could not be read (invalid JSON) instead of the parser's text, which quotes part of a credential. Ran carries the spawn error and signal, so a keychain or service tool that cannot start says could not run, not exited timeout. Writes of the credential and state temp files, the service files and service.log, and the chmod of an existing service.log, go through one helper that never follows a symlink. * refactor: write private files whole with writeFileSync, test the edges Mutation testing showed the hand-rolled write loop added nothing over writeFileSync on a descriptor, and that a real spawn failure and a tail with no whole line were untested. AGENTS.md names the new module.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #16
Follow-ups from the review of #15.
Acceptance criteria
store.apps().doctorreads the apps inside a try and prints the store's own reason as aFAILline ("The credential for X is in the keychain, but the macOS keychain did not answer (36). Unlock the keychain..."), exit 1, nothing thrown. Test:tether doctor > fails, saying why, when the keychain that holds a credential cannot be read.Keychain.setnow returns why it refused (undefined once it holds the secret): a valuesecurity -icannot quote, the tool's exit status, or a write that does not read back. Forsecurity -ionly the exit status is used, because its stdin line carries the secret; forsecret-toolthe first line of stderr is added (the secret only goes to its stdin).Store.saveAppreturns{ where, warning? }andmoveToKeychainreturns its warnings;connectandstartprint them on stderr.startadds the credentials to the redactor before printing. With no keychain at all (Windows,TETHER_KEYCHAIN=off) nothing is printed: the file is the intended place there. Tests: keychain backend reasons (including one wheresecurityechoes its stdin to stderr), store warnings,connectandstartwarnings withexpectNoSecrets.tether startcutsservice.logto its last ~1 MB, from a line start, once it passes 5 MB: at start and every ten minutes. It is rewritten in place, not renamed, because launchd opens the log for appending and keeps writing at the new end. Not on Windows: cmd's>>seeks to the end once and keeps writing at its old offset, so a cut there would leave a gap; the Windows log has no limit yet. On macOS,service installnow runs chmod 0600 on an existing log. Tests: store trim (over, at and under the limit, missing file), start trims an oversized log, install fixes a 0644 log.bootoutreturns before the old agent stops, sobootstrapis retried up to 10 times, one second apart, on any failure, and the last error is reported. It retries even whenbootoutitself failed, becausebootoutcan exit 36 while the agent is still stopping. A first install that succeeds is unchanged. Tests: bootout 36 followed by two failed bootstraps then success; give up after ten tries with launchctl's message.logTaskcaps the title. At most 200 characters, cut on code points. Test with an emoji at the boundary.logTaskinworker.ts. The outcome is settled first; then the reservation, the running entry and the slot are released, the log is written once inside its own try (a failure prints one line), and usage and run state are updated. Before this change a throwing log ran the error path, which logged again, threw again and skipped the release. Test:tasks.jsonlmade a directory, two tasks at concurrency 1 both complete, the failure line appears once per task, and today's spend equals what the tasks reported.After=/Wants=network-online.targetdropped from the user unit (snapshot updated);persist-credentials: falseon the checkout inrelease.yml, with a test that every checkout step there sets it.Checks run
bun run lint:Checked 69 files ... No fixes applied.bun run typecheck: clean.bun run test(full suite, locally, before the last two test additions and the refactor):Test Files 14 passed | 1 skipped (15),Tests 394 passed | 1 skipped (395). The skipped file is the real-launchd test, which runs only in CI.728addf: two more local full runs got no slot in the shared heavy-job queue. Instead, a targeted local run of the keychain, store and service tests plus the CLI start, doctor, keychain, log and service tests:Tests 103 passed | 7 skipped (110). CI ran the full suite on this head: CI and Release green on Linux and macOS, including the real launchd install.Quality gates (changed code only)
macKeychain8.2,secretToolKeychain8.2,Worker.start7.0,cli start6.6 (was 19.1 beforeconnectedAppswas split out),doctor6.0,saveApp5.0,moveToKeychain5.1,trimServiceLog3.0 (store) and 4.2 (cli),logTask3.0.dryer src): no candidates.status ?? "timeout"turned into||atkeychain.ts:60andservice.ts:57, both inside a branch where status is never 0, andctx.io.platform ?? process.platformturned into||atmain.ts, where the platform is never an empty string. The mutation tool does not reach methods on thelaunchdobject literal, so the bootstrap retry loop is covered by its tests only.Risks
security -ireason leaves out stderr on purpose.StandardOutPathfor appending, which the code comment explains. Nothing checks this against a real running service yet.Not verified