docs(coord): the session record has no branch field, and two rosters answer different questions - #259
Open
wshallwshall wants to merge 1 commit into
Open
docs(coord): the session record has no branch field, and two rosters answer different questions#259wshallwshall wants to merge 1 commit into
wshallwshall wants to merge 1 commit into
Conversation
…ee about one
A session was told a coordinator "might not be there" on the strength of the
session-list MCP tool's `isRunning: false`, and separately the two rosters
reported different branches for one checkout. Both readings were wrong the same
way -- a field answering a question adjacent to the one asked -- and neither trap
was written down anywhere a reader would look.
MEASURED 2026-08-06. A session record holds exactly cwd, entrypoint, kind, name,
nameSource, peerProtocol, pid, procStart, sessionId, startedAt, version. There is
NO branch field. So any branch printed beside a session came from elsewhere, and
the two sources answer different questions while both being labelled "branch":
presence.ps1 / occupancy.ps1 the WORKTREE's branch, live from
`git worktree list --porcelain`. Current.
session-list MCP tool a SESSION attribute captured at registration.
Does not follow a later `git switch`.
For one checkout they reported two different names -- the live roster the branch
that checkout had been switched onto, the session list the one it registered
with. Neither was wrong. A disagreement is not evidence that either roster is
broken, and a branch from the session list must never be quoted as a checkout's
current branch.
ALSO RECORDED, same family: `isRunning` means "currently EXECUTING A TURN", not
"alive". An idle session between turns reads false while being perfectly
reachable. It is not a liveness fence and must not be used as one --
Get-SessionLiveness is, subject to the rule already stated directly above it that
ONLY THE POSITIVE ANSWER IS SAFE TO ACT ON. That rule is why the original
inference was doubly wrong: it drew a negative conclusion from a signal that
cannot support one, using a field that answers a different question.
The concrete branch names are deliberately NOT quoted -- the leak gate refused
the first attempt because a real worktree slug is an internal project name, and
the lesson does not need them.
Documentation only; no behaviour change. Both files parse, presence.ps1 still
runs, 272 tests pass across the coord/presence/occupancy suites.
wshallwshall
enabled auto-merge (squash)
August 6, 2026 17:04
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.
Docs-only, 2 files, +30. No behaviour change.
TWO TRAPS, both walked into on 2026-08-06, neither written down where a reader would look.
peerProtocol, pid, procStart, sessionId, startedAt, version -- and never has. So any branch shown
beside a session came from somewhere else:
git worktree list --porcelain(Get-RepoWorktrees). CURRENT.follow a later
git switch.Both are labelled 'branch'. For one checkout they reported two different names and NEITHER WAS
WRONG -- they answer different questions. A disagreement between them is not evidence of a defect.
isRunningMEANS 'CURRENTLY EXECUTING A TURN', NOT 'ALIVE'. An idle session between turns readsfalse while being perfectly reachable. A session was reported as possibly gone on that basis and was
in fact live throughout.
⭐ AND session-registry.ps1 ALREADY SAID SO, two paragraphs above where the reader was looking:
'ONLY THE POSITIVE ANSWER IS SAFE TO ACT ON ... nothing here can PROVE a session is gone -- only that
it is present.' So the inference was wrong twice over: a NEGATIVE conclusion drawn from a signal that
cannot support one, using a field that answers a different question. Both traps are now documented in
session-registry.ps1's header and at Get-RepoWorktrees -- the two places a reader actually lands,
rather than only in the docstring that was already being skipped.
Concrete branch and worktree names are deliberately absent: the leak guard refused a first attempt
because a real worktree slug is an internal project name, and the lesson does not need them.
VERIFIED: both files parse; presence.ps1 still runs and still lists 5 live sessions; 272 tests pass
across the coord, presence and occupancy suites. Based on afdc5cb, merge-tree clean.
PROVENANCE: first committed onto a branch whose PR had ALREADY MERGED, so its parent was no longer an
ancestor of main. Caught with
git merge-base --is-ancestorbefore handover, re-cut off current main,cherry-picked. The pre-squash-base trap does not stop being available just because you know about it.