fix(#71): add session-onboard.sh --doctor diagnostic - #77
Merged
Conversation
throughline resolves its data location through three env vars, a .throughlineignore marker checked at two roots, sticky git-worktree migration logic, and a soft jq dependency that degrades capture silently when missing. Diagnosing "why isn't capture firing" meant reading _lib.sh and reasoning through the precedence by hand. --doctor prints the resolved root/data root (and whether worktree- sharing applies), activation state and reason, jq availability, live/archived buffer counts, and the three env vars' values. It is read-only - checked before the THROUGHLINE_DISABLE kill switch (that's exactly the state someone runs --doctor to discover), and never calls tl_active() so it never bootstraps a data directory as a side effect. Counts buffers via a plain glob-and-count loop rather than find | wc: this is a diagnostic meant to work in the degraded environments it exists to investigate, and neither find nor wc is a POSIX-sh-guaranteed dependency the way plain globbing and arithmetic are - caught by testing the --doctor jq-missing fixture, which stubs a minimal PATH. Closes #71 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019VuUKvqH3q511w8xVd4VFY
- The new worktree-sharing assertion matched the full absolute WT_MAIN
path, which is red on windows-latest: $WT_MAIN is in MSYS form while
the doctor's own "data root:" line resolves via `git worktree list`
in native C:/... form for the identical directory. Match a path
suffix instead, the convention every other worktree assertion in
this file already follows.
- --doctor collapsed tl_active()'s bootstrap-failed outcome into
would-bootstrap and asserted the next hook run "will" create the
data dir - exactly wrong in the one scenario ("why isn't capture
firing") this diagnostic exists to explain. Walk up to the nearest
existing ancestor and probe writability; report "LIKELY TO FAIL"
when it isn't writable.
- Add dedicated assertions for the "active" state and for an exact
seeded buffer count - both branches of the state machine had zero
regression coverage beyond incidentally passing through them.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019VuUKvqH3q511w8xVd4VFY
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
1 participant
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.
Summary
session-onboard.sh --doctor: a read-only diagnostic reporting resolved data root, activation state/reason,jqavailability, live/archived buffer counts, and the three env vars' values.THROUGHLINE_DISABLEkill switch (the disabled state is exactly what someone runs--doctorto discover). Never callstl_active(), so it never bootstraps a data directory as a side effect.find | wc— neither is a guaranteed dependency in the degraded environments this diagnostic exists to investigate (caught live via the jq-missing test fixture's restrictedPATHstub).docs/REFERENCE.md.Closes #71
Test plan
local-ci --strict— all checks pass (183/183 hook test assertions, shellcheck clean).throughlineignore), linked worktree (shared root), missingjq, never-activated project (would-bootstrap + no side effect)jqPATH stub, and a fresh scratch git repo confirming--doctorcreates no.claude/throughline/directory🤖 Generated with Claude Code
https://claude.ai/code/session_019VuUKvqH3q511w8xVd4VFY