Repository navigation
feat(session-tree): adopt and release records so one conductor can take over another - #12962
Conversation
43a52aa to
541ec45
Compare
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Design Review (Fable 5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS Adoption reshapes the sidebar tree but not PR-holder routing — Watch
[DESIGN-REVIEWED] 09df9ae |
UX Review (Fable 5) — ✅ PASSUX-level review of UX-Verdict: PASS Watch the attached clip to confirm the branch's move reads as one continuous glide; mechanism and recording verified here, playback needs a human. Watch
[UX-REVIEWED] 09df9ae |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the one-time upgrade cost: the checkpoint version bump discards every existing checkpoint, and the reseed then reads each session log whole — confirm that is acceptable on a large real store. What this change shipsInventory (10 items) — 10 justifiedIntent: Let a person consolidate running conductors — one session takes over sessions already running and the sidebar shows the new layer immediately, without recreating live conversations. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 09df9ae |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsTwo advisory findings; nothing blocks the merge. FINDING — src/kiro_crew/dashboard/session_control.py:2310 — the in-flight-append fence is registered and checked on the target slot only ( FINDING — src/kiro_crew/crew_log/session_tree_projection.py:1028 — [OPUS-REVIEWED] 09df9ae Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 5.6 Review —
|
GPT 5.6 Review —
|
42c46eb to
9c4e632
Compare
GPT 5.6 Review —
|
1 similar comment
GPT 5.6 Review —
|
9c4e632 to
d1f8ae0
Compare
GPT 5.6 Review —
|
d1f8ae0 to
06ccb2a
Compare
06ccb2a to
1ba122f
Compare
…or can take over another
The sidebar's conductor lane nests a session under the session that opened it, and
that edge was the only one the tree had: `parent {slot, sid}` on `session/opened`,
stamped once at creation, in an append-only log nothing rewrites. So the tree could
say who OPENED a session and nothing else. There was no record that moves a session
under a different parent and none that makes it a root again -- an opened entry
carrying no parent does not mean "no parent", it means that entry did not repeat a
creator, so even the absence of an edge could not be expressed.
**The records.** `session/adopted` carries `parent {slot, sid}` -- the caller,
resolved by the gateway from the MCP connection and never an argument, so no session
can nominate a parent for a tree it is not in -- plus `previous_parent` for a reader.
`session/released` carries `previous_parent` alone and the target becomes a root. Both
are written into the TARGET's log with `src=gateway`, the side `session/opened.parent`
already puts a creating edge on. That placement makes a takeover total as well as
cheap: descendants cite this session's SLOT, not a path through it, so one entry moves
a whole branch and no descendant needs a record of its own.
**The fold.** The decisions are a separate `EdgeRecord` layer beside the opened
records rather than another `OpenedRecord`, because `fold_tree` takes a slot's parent
from its OLDEST record carrying one and lets no later record retract it. Ordering
never rests on a clock: an `EdgeRecord` carries the writer-assigned `seq`, so two
decisions in ONE log are ordered by the store itself and an NTP correction or a VM
resume cannot invert them; across two logs of one slot, where seqs are not comparable,
the newer LOG decides, ranked by the same `(created_at, sid)` key `fold_tree` already
sorts records by. `at` is the audit reading and the last resort only.
Decisions are held per `(slot, sid)` -- every log's, not one winner per slot -- and
reduced at fold time by `latest_edges`, which the fold calls with that ranking. One
winner per slot would discard the loser on arrival, and then deleting the winning unit
would leave the slot with no decision rather than with the survivor's: the fold would
fall back to the OPENING edge and silently move a session that had been taken over.
The cold seed installs every decision for the same reason, and because reducing there
has no record order to rank logs with and would fall back to the clock.
**Cold-scan parity**, where most of the care went. A decision lands at the END of a
log, so the head read every scan already does cannot see it, and a stale edge here is
not a missing edge but a session shown under a parent that already let it go. So
`SessionTree.reading(with_edges=True)` also reads each admitted unit's decision, cached
on the newest segment's identity plus an exact size; that read walks segments
newest-first and reads one whole when the bounded window cannot prove it saw the start;
the tail replay reads every admitted unit rather than only new names, since a unit the
checkpoint already holds is exactly where a decision it missed will be; `with_edges` is
off by default, because the succession walk has no use for where a slot hangs; and the
checkpoint version is bumped rather than read additively, because a file without
`edges` would load as "no session has ever been adopted", which looks exactly like the
truth and is wrong.
`_LIFECYCLE_TYPES` is deliberately NOT extended. That set decides open-versus-closed
and therefore authorizes retention's DELETE, so a unit whose newest such entry was an
adoption would never expire. The tree kinds get their own set and share the window
walk; retention is untouched, and a test pins that an adoption after a close still
reads as closed.
**The verbs.** `session_adopt` and `session_release` route through `authorize_target`,
so a session that cannot be sent to cannot be adopted either. Adopting a session that
already has a parent is allowed, because that IS the takeover, and the parent it
replaces is recorded. A release admits the target's current parent and the target
ITSELF, so a session whose holder has stopped running is not stuck under it; that is
the one place the shared gate is relaxed, and it is relaxed exactly twice -- the
self-target refusal and, for that case only, the ownership fence, since the session a
caller IS was never another session's to protect. Neither verb is auto-granted to an
unattended conductor and both are blocked for channel agents: they MUTATE where an
existing session sits in the person's sidebar, which is the wrong side of the grant
invariant.
Both refuse while the tree cannot be read rather than adopting past their own cycle
guard. A guard handed no tree admits everything, and the loop it would admit is not
repaired by the fold -- that marks every slot on the cycle and nests none of them,
flattening the branch. The two tree refusals are ordered, permanent before retryable:
with no recorded tree there is nowhere to write the edge and no retry helps.
Each verb holds one lock across reading the tree and committing to it, and waits for
its own append to be durable before it answers. The emitter hands an entry to the
writer and returns, so without the wait a refused append -- or a target with no live
log -- would still have told the caller the takeover happened; without the lock, a
release authorized against the old parent could commit after an adoption and return the
session to a conductor that had already handed it on. A timeout is reported as
retryable rather than as a failure, because the writer may still land the entry.
**The lane.** Collapsed-by-default is what makes the lane worth having, and it is the
wrong default for a session that moves on its own: an adoption re-parents a session
already on screen, and the adopting conductor is collapsed because nobody has ever
opened it, so the rows the person was watching unmount and leave a child count behind.
The lane now opens the row a session MOVED under, on a CHANGED citation across two
consecutive slot frames -- a row absent from the previous frame was just created, which
keeps the collapsed default, and a cleared citation is a release, which lands at the
top level where nothing needs opening. The diff is kept on `parent.slot` rather than on
the placed parent, because the citation is a fact from the session's own crew log and
does not move when a search or folder filter changes which rows are in the payload.
No new wire field and no new control.
Tests: `test_crew_log_session_tree_adopt.py` (36) over the fold's ordering and cycle
colouring, the record builder's refusals, the projection's idempotence, out-of-order
guard, checkpoint round-trip and per-unit retention through a delete, the store's tail
and whole-log reads, cold-scan parity, and the emitter's entry plus its durable-outcome
report. `test_session_control_tree.py` (23) over both verbs' authorization, every
refusal writing nothing, the two durability refusals, and two concurrent takeovers
serializing. `ChatSidebar.conductorLane.test.tsx` (36) over the nesting an adoption
produces and the collapse transition in both directions. A real-browser harness,
`website/capture/session-tree-adopt.tsx` driven by
`website/scripts/capture-session-tree-adopt.mjs`, asserts thirteen readings across four
beats while it records the clip.
Three registry-style lists this change has to extend, and one of them was already
behind on main. `test_mcp_dashboard_folders.py`'s advertised set gains the two verbs.
`test_crew_log_exc_info_sites.py`'s vetted list gains twelve sites -- three are this
change's (`_record_session_tree_decision`, `record_adopted`, `record_released`) and nine
arrived with #12757's squash without being recorded, so that lane is red on main
independently; the list is completed rather than partly filled, because a partial one
keeps the lane red for everyone. And `website/scripts/restyle-baseline.json` drops the
`MembersPage.tsx` entry the ratchet reports as progress already made on main, which is
the remedy the gate itself prints.
bolichen97
left a comment
There was a problem hiding this comment.
Approved after full readiness scan: readiness: passed, required check PR Readiness green on 09df9ae, no effective CHANGES_REQUESTED, no unresolved blocking threads.
1. What is the problem?
The sidebar's conductor lane nests a session under the session that opened it, and
that edge is the only one the tree has. It is
parent {slot, sid}onsession/opened, stamped once by the gateway when the session is created, and thecrew log is append-only so nothing rewrites it.
So the tree can say who OPENED a session and nothing else. There is no record that
moves a session under a different parent, and none that makes a session a root again.
An opened entry that carries no parent does not mean "this session has no parent" --
it means that entry did not repeat a creator, which a reader must not read as a
retraction, so even the absence of an edge cannot be expressed.
2. Why this issue matters to the user
Raymond runs more conductors than he can hold in his head. What he wants is to open
ONE session, hand it the ones already running, and see that new layer in the sidebar
immediately. Today there is no way to say it: the lane can only show the shape the
sessions were created in, which stops describing the work the moment someone
reorganises it. The alternative is closing live conversations and re-creating them
under a new parent, which throws away their transcripts.
3. How our fix solves it
Two new crew-log record kinds, folded by the projection that is already there, and
two gateway MCP verbs that are the only way to write them.
The records.
session/adoptedcarriesparent {slot, sid}-- the caller,resolved by the gateway from the MCP connection and never an argument, so no session
can nominate a parent for a tree it is not in -- plus
previous_parentfor a readerof the log.
session/releasedcarriesprevious_parentalone and the target becomesa root. Both are written into the TARGET session's log with
src=gateway, which isthe side
session/opened.parentalready puts a creating edge on.That placement is what makes a takeover cheap and total: descendants cite this
session's SLOT, not a path through it, so one entry moves a whole branch and no
descendant needs a record of its own.
The fold. The decisions are a separate
EdgeRecordlayer beside the openedrecords rather than another
OpenedRecord, becausefold_treetakes a slot's parentfrom its OLDEST record carrying one and lets no later record retract it. An adoption
has to beat the creating citation, and it is a different kind of statement: the opened
entry says who opened the session, which stays true, while a decision says who holds
it now.
fold_treeapplies the newest decision per slot and then runs its existingcycle colouring over the result.
The projection holds EVERY log's decision, keyed
(slot, sid), and lets the foldreduce them. Holding one winner per slot instead would discard the loser the moment it
arrived, and then deleting the winning unit leaves the slot with no decision rather
than with the survivor's -- so the fold falls back to the OPENING edge and a session
that had been taken over silently returns to the conductor that opened it, on an
ordinary retention delete. The cold seed installs every decision for a second reason:
reducing there has no record order to rank two logs with, so it would fall back to the
timestamp and a clock rollback between the logs would seed the superseded lineage.
"Newest" asks the STORE, never a clock. Within one log the written
seqdecides, andit only increases, so a clock that steps backward between two appends -- an NTP
correction, a VM resume -- cannot make the later decision lose. Across two logs of one
slot seqs are not comparable, because the log that replaces one starts its own
sequence, so the newer LOG decides, ranked by the same
(created_at, sid)keyfold_treealready sorts records by. That is deliberate: one log order places both thedecisions and the creating citations, so the tree cannot disagree with itself about
which of its own records is newer.
The cycle guard runs in two places for two different reasons.
session_adoptrefusesa target that is already above the caller, reading the tree as it stands. The fold
guards again over the applied decisions, which is the case that reading cannot cover:
a checkpoint plus a replayed tail can deliver decisions in an order no writer ever
saw, and a cycle is a shape the tree cannot present -- it marks every session on the
loop and nests none of them, so an unguarded loop would silently flatten a branch.
Cold-scan parity, which is where most of the care went. A decision lands at the
END of a log, so the head read every scan already does cannot see it -- and the
checkpoint has to stay a shortcut that may be stale but never wrong. A stale edge here
is not a missing edge: it is a session shown under a parent that already let it go. So
SessionTree.reading(with_edges=True)also reads each admitted unit's DECISION,cached on the newest segment's identity plus an EXACT size, because a tail answer
moves with every append where a head's cannot;
bounded window cannot prove it saw the start, so a decision buried behind later
entries or left in a rotated segment is still found -- a cold rebuild that missed one
would not show a missing edge but a WRONG one, silently, with nothing to correct it;
unit a checkpoint already holds is exactly where a decision it missed will be;
with_edgesis OFF by default -- the succession walk has no use for where a slothangs, and this costs a
statand a bounded read per unit, worth paying once on thecold start that has no checkpoint;
edgeswould load as "no session has ever been adopted", which looks exactly likethe truth and is wrong.
One deliberate deviation from the plan I was given. It said to extend
_LIFECYCLE_TYPESinstore.pyso the window scan sees the new kinds. That setdecides open-versus-closed and therefore authorizes retention's DELETE, so a unit
whose newest such entry was an adoption would never expire. The tree kinds get their
own set and share the window walk instead; retention is untouched, and a test pins
that an adoption after a close still reads as closed.
The verbs.
session_adoptandsession_releaseroute throughauthorize_target, so a session that cannot be sent to cannot be adopted either --the unattended, ephemeral, app-scoped, channel-linked, mirrored, cross-workspace and
ownership-fence refusals all apply unchanged. Adopting a session that already has a
parent is allowed, because that IS the takeover, and the parent it replaces is
recorded. A release admits the target's current parent and the target ITSELF, so a
session whose holder has stopped running is not stuck under it; that is the one place
the shared gate is relaxed, and it is relaxed exactly twice -- the self-target refusal
and, for that same case only, the ownership fence, since the session a caller IS was
never another session's to protect.
Neither verb is auto-granted to an unattended conductor. Both MUTATE where an
existing session sits in the person's sidebar, which is the wrong side of the grant
invariant ("a granted verb may CREATE or READ, never MUTATE workspace state that
already exists and is not the agent's own"), and a takeover moves a subtree. Both are
blocked for channel agents on the same containment grounds as the other
session-control tools.
Each verb waits for its own write, and holds a lock while it does. The emitter
hands an entry to the crew-log writer and returns, so a verb that answered immediately
would have reported a takeover that the filesystem refused, or one aimed at a session
with no live log to write to -- and audited it as allowed. Both now wait for the durable
outcome and refuse when it did not land, with a timeout reported as retryable rather
than as a failure, because the writer may still land the entry.
The wait is what the lock has to cover. The verbs read the tree, decide from it, and
then write to it; unserialized, a release authorized against the old parent can commit
after an adoption and return the session to a conductor that had already handed it on --
both writes valid, the later one the one nobody asked for. One lock spans the tree read
through the awaited append, and because the append's completion is also what advances
the projection, the next verb through it reads the state the previous one committed. The
lock is per event loop rather than per process, so the test suite's many loops cannot
share one;
authorize_targetstays outside it, since it does not read the tree.One thing the lane did need. Collapsed-by-default is what makes the conductor
lane worth having: a conductor with fourteen workers reads as one row with a count
rather than fifteen rows to skim past. It is the right default for a session the
person opened, and the wrong one for a session that moves on its own.
session_adoptre-parents a session that is ALREADY on screen, and the adopting conductor is
collapsed because nobody has ever opened it -- so the adopted row and its whole branch
unmount and leave a child-count badge where the person's live sessions were. They
collapsed nothing, so nothing on screen says where those sessions went, and it happens
on this feature's primary flow rather than at an edge.
So the lane opens the row a session MOVED under. The signal is a CHANGED citation
across two consecutive slot frames: a row absent from the previous frame was just
created, which is
session_createand keeps the collapsed default untouched, while arow already listed under one creator that now names another was moved by something
other than the person looking at it. A citation cleared to null is a release, and the
row lands at the top level where nothing needs opening.
The diff is kept on
parent.slot, the child's own citation, rather than on the placedparent. The citation is a fact from that session's crew log, so it does not move when a
search or a folder filter changes which rows are in the payload; the placed parent
does, and diffing it would read a cleared search -- which restores every row's creator
at once -- as a whole sidebar's worth of moves. The whole ancestor chain is expanded
through
expandConductorAncestors, the walk a reveal already uses, because an adopternested under a collapsed conductor of its own would otherwise be as invisible as
before.
No new wire field, no new control, and
session_createis untouched: the lanecompares two frames it already receives and expands a disclosure it already has.
Everything else about the row is unchanged -- an adoption changes the value of
parentin the payload and nothing else.
4. What tests we did
New, in
test/test_crew_log_session_tree_adopt.py(36): the fold prefers the newestdecision over the creating citation and over an older decision in either arrival
order; the millisecond tie breaks on the citing log; an adoption that would close a
loop is coloured as a cycle; a decision for a slot with no log changes nothing; a
malformed adoption is refused rather than read as a release; over-long keys are
refused rather than truncated; the projection keeps the same object when a decision
repeats, refuses one that arrives out of order, round-trips its decisions through the
checkpoint, discards a payload missing
edges, and drops a forgotten unit'sdecisions; the store reads a decision sitting behind later entries and the newest of
two; an adoption is not a lifecycle entry, so retention still reads the unit as
closed; a cold scan with no checkpoint reaches the same tree as the fold; a scan
without edges answers where each slot was OPENED; a stale checkpoint is corrected by
the replay for a unit it already holds; a removed unit leaves the replay; and the
emitter writes the entry, advances the fold, records the replaced parent, and writes
nothing without both sides of the edge.
Five of those are this round's: forgetting the WINNING log leaves the surviving log's
decision deciding rather than falling back to the opening citation; a cold seed from a
real store keeps every log's decision, asserted through the delete that is the only way
to observe it; and the emitter reports its durable outcome --
Trueonly once the entryis on disk,
Falsefor a session with no log to write to, andFalsewithout waitingfor an entry it refuses outright. The first two fail on the old one-winner-per-slot
holding, with the slot reading its opening parent.
New, in
test/test_session_control_tree.py(23): the caller is recorded as theparent; a takeover records the parent it replaced; the cycle, self-target, not-found,
unattended-caller, cross-workspace, tree-unavailable and no-live-log refusals each
write nothing; a parent can release what it holds; a session can release itself,
including an agent-created one under the fence; a third session cannot release
someone else's child; an already-root release is refused; and the tool set, the
channel block list, the grant tuples and the internal-auth route set all agree.
Three more are this round's: an adoption and a release whose append the writer gave up
on are each refused rather than reported, with the emitter call still made -- a lost
entry is a different thing from a refusal that writes nothing -- and two concurrent
takeovers of one session serialize, so the second records the parent the first
committed. That last one fails without the lock, with both takeovers recording that
they took the session from nobody; making it fail took a stub that advances the
projection when the append SETTLES rather than when it is handed over, which is where
the real writer advances it and is why the WAIT is the part the lock has to cover.
Added to
website/src/test/ChatSidebar.conductorLane.test.tsx(36 total): an adoptedsession nests under its new parent and its children move with it at the right depth; a
released session returns to the top level keeping its own subtree; and a released
session is NOT marked as an orphan, because the orphan marker means "the session that
opened this one is gone" and conflating the two would tell the person a session they
deliberately detached had lost its opener.
Three more there pin the collapse fix in both directions, over two consecutive frames:
a row whose citation CHANGED opens its new parent and stays on screen one level
deeper; a row that is merely NEW stays collapsed, which is the
session_createdefault; and a RELEASE opens nothing, because the row lands where nothing is collapsed
in front of it. Neutering the expand fails exactly the first of those and neither of
the others, with the adopted row absent from the lane -- so the test discriminates
rather than passing on both sides.
A recording, and what kind it is. Attached to this description (the five
user-attachmentsassets at the bottom) is one continuous clip of an adoption into acollapsed parent and the release after it, plus the four still frames it passes through.
Attached and not committed, which is what
docs/ci/ci-and-reviews.mdprescribes and whatthe review lanes read: the capture script still writes into gitignored
temp-screenshots/locally, and nothing from there reaches this branch. It is aHARNESS recording, not a live gateway:
website/capture/session-tree-adopt.tsxmounts the realChatSidebarwiththe real global CSS and
initI18n(), andwebsite/scripts/capture-session-tree-adopt.mjsdrives it in a real browser.The harness supplies only the OCCASION.
session_adoptis called by an agent, so on alive gateway the frame that re-parents a branch lands whenever some conductor decides
to take one over, and both verbs refuse the session that calls them in most shapes, so
driving them from the dashboard being recorded would need a second gateway.
parentinthe fixture is exactly what the fold above puts on the wire --
{slot, key}after anadoption,
nullafter a release -- and the frames arrive as ordinary slot updates thatthe real component folds. Nothing stubs the nesting, the collapse state, or the expand.
The beats are: two conductors at rest, the person opening the branch they want to
watch, the adoption moving that branch under a conductor nobody has ever opened, and
the release returning it to the top level. The third is the one to watch -- every row
from the second is still on screen, one level deeper. The driver asserts all thirteen
readings WHILE it records, including the control that the new parent is absent from the
persisted expanded set before the adoption and present after it, so a blank or wrong
frame fails the run instead of shipping as evidence. It answers every boot fixture
itself rather than reading whichever gateway happens to be running, which is also what
keeps the clip's appearance from depending on the machine it was recorded on.
Existing suites re-run green:
test_crew_log_session_tree55,test_crew_log_session_tree_projection34 (the same count main itself reads, as thenote at the top explains),
test_crew_log_types200,test_crew_log_retention59,test_slot_payload_lineage17,test_mcp_dashboard_registration23,test_session_control_doc10,test_channel_blocked_tools21,test_mcp_dashboard_session_send8. On the frontendside the five lane suites run together green --
ChatSidebar.conductorLane,ChatSidebar.laneCardParity,ChatSidebar.flatBoard,ChatSidebar.chevronGrammarandsessionLineage, 69 cases.black(the baselined gate, not a bare check),isort,flake8,mypy src/kiro_crew/,tsc -b,eslint src/ --max-warnings 0,jscpd(0 clones), the i18n runner's eleven checks, the comment-history gate and the
feature-map gate all pass, each read from its own exit status.
The feature map's two affected rows are updated: Sessions no longer says the lane
nests opener-only, and records the auto-expand on a changed citation; Session
control carries
adoptandrelease, their endpoints, and the refusals that boundthem.
Three existing tests needed a change, each for a stated reason: the projection
suite's three scan doubles take the keyword the seed now passes; the type registry's
pinned count moves from 31 to 33; and
session-control.mdplusindex.mddocumentthe two new tools, which their own parity tests enforce.
Three registry-style lists also had to be extended, and one was already behind on main.
test_mcp_dashboard_folders.py's advertised tool set gains the two verbs.test_crew_log_exc_info_sites.py's vetted list gains the nine sites that arrived with#12757's squash without being recorded, which is why that lane is red on main
independently of this PR -- the list is completed rather than partly filled, because a
partial one keeps the lane red for everyone. This change adds NO site of its own:
record_adopted,record_releasedand_record_session_tree_decisionrender thetraceback as text under #13007's rule, and the two entries that rule de-listed stay out.
website/scripts/restyle-baseline.jsonis NO LONGER inthis diff: an earlier round dropped the
MembersPage.tsxentry the ratchet reported asprogress already made, and #13008 then landed the byte-identical edit on main, so the
rebase onto
21182a5e94removed it from here. The file is main's, not this PR's.4b. Findings answered on the previous head
Four review findings on
ca97dad6e6, all real, all fixed here. None was overridden.The gate was read before the wait, not where it acts. Both verbs authorized, then
waited for the tree mutation lock, and that wait is unbounded -- the verb ahead awaits its
own append. A target could stop being addressable, or a caller's grant be withdrawn, in
that gap, and the write would still land on the earlier answer. Each verb now re-runs
authorize_targetinside the lock. The pre-lock call is kept as the cheap refusal, so anunauthorized caller never contends for the lock at all.
The config read ran on the event loop.
authorize_targetis synchronous and itssession_control_enabled()re-reads and validates the config file on the first call afteran edit, which blocks the shared loop for every other session. Both gates in both verbs
are now preceded by
prewarm_enabled_check()with nothing suspending in between -- twowarms per verb, because the lock wait is itself the suspension that invalidates the first.
The cycle guard read the nodes without their completeness.
TreeReading.incompletemeans a unit's bytes could not be read or the population was capped, so an edge the guard
needs can be absent from an otherwise well-formed fold. The guard called
nodes()andnever saw the flag, which is the case
TreeReading's own docstring warns a DECIDING readerabout. It now reads
reading()and treats an incomplete fold as no tree, refusingtree_not_ready.An unreadable store answered "no decision".
find_last_tree_edgeswallowed anOSErrorfrom its directory listing and returned
None, contradicting its own docstring. Bothcallers CACHE that answer, so one moment's I/O fault became the tree's standing answer --
the seed would install the creating edge for a session that was moved. The listing now
raises; both callers already catch
OSErrorand mark their scan incomplete.Each fix carries a test, and each test was verified by restoring the old behaviour: the
in-lock authorization removed lets an adoption land on a target already gone; the guard
reverted to
nodes()admits the incomplete fold; the swallow restored answersNoneinstead of raising; the warm count reads 1 instead of 2.
4c. Findings answered on
b143f6aa2aFour more, all real, all fixed on this head. None was overridden. Two are the same class
of mistake as the previous round's, at sites that round did not reach -- which is the
useful thing about them.
A timed-out append left the slot open to the next verb. A verb that times out waiting
for its own append raises out of the mutation lock, which releases it -- and the append is
still queued. The next verb through the lock would read a tree the writer is about to
change and commit against it, so a release authorized against the outgoing parent could
land under an adoption that had not yet applied. Holding the lock until settlement instead
would pin the serialized region to a wedged filesystem, which is exactly what the timeout
exists to avoid. So the SLOT is fenced rather than the lock held:
_tree_pending_slotscarries one entry per in-flight append, both verbs refuse
tree_write_pendingon a fencedslot, and the wait is now
shielded -- a timeout that cancelled the future would resolveit and clear the fence at the one moment it is needed.
newest_segmentreported an unlistable directory as no decision. It collapsed absent,empty and unreadable into one
None, and the scanner read all three as a complete "nodecision" with
incompletefalse. That leaves a stale cached edge standing as the tree'sanswer, which is the wrong parent rather than a missing one. Absent and empty ARE answers;
a failed listing is not. The listing now raises and the scanner reports
incompletewithno verdict, leaving the cached entry alone. This is the same fix the previous round made in
find_last_tree_edge, at the site that round did not reach.The replay let a checkpoint edge outlive its removal from the log. A unit whose complete
read found no decision was skipped, which KEPT whatever the checkpoint had loaded -- so a
decision retention took out of the log pinned the slot under that parent on every restart,
with nothing on disk behind it. A complete read finding nothing is the only thing that can
contradict a checkpoint edge, so it now drops it. A read that RAISED still leaves the edge
alone, because that read established nothing.
The feature map claimed release refuses a cycle. It does not, and has nothing to
refuse -- it only removes an edge. Corrected, along with the two retryable refusals a
caller can now meet (
tree_not_ready,tree_write_pending), which are documented insession-control.md's refusal table.Each fix carries a test verified by restoring the old behaviour: the fence removed lets a
second append queue on the same slot; the swallow restored reports
incompletefalse; thereplay's drop removed leaves the stale parent standing. One earlier test had to change with
the third fix -- the checkpoint round-trip folded an edge it had never written to disk, and
the emitter never does that, so its decision is now on disk like production's.
4d. Findings answered on
42c46ebc88One finding, upheld behind the security fence, and it is the THIRD site of the mistake the
two rounds before it fixed at two other sites. Worth naming as one thing rather than three
incidents:
find_last_tree_edge's answer is CACHED against a segment's unchangeddev/ino/size and checkpointed, so anywhere on that path a swallowed
OSErrorturns "thebytes were not seen" into the durable verdict "this session was never moved" -- and nothing
re-reads it. The three sites were the directory listing in
find_last_tree_edge, thelisting in
newest_segment, and now thestatin_scan_whole_for_types, which thebounded window reaches only for a rotated log. That last one also contradicted itself: the
openon the next statement already propagated, so one function answered two differentways about the same file. All three now raise, and both callers' existing
except (OSError, ValueError)incomplete-scan handling is what receives it.Its test needed two attempts to be worth having. The first patched every
statof thesegment, which made the bounded window raise first -- so it passed with the swallow restored
and proved nothing. It now fails the scan's OWN stat, by count, and is checked both ways.
Two test lanes were red on that head and neither is this diff's.
Frontend Tests (4)failedin
MembersPage.test.tsx, a file this PR does not touch -- and the two heads either side ofthat red are byte-identical under
website/, with the previous one green on the same shard.Backend Tests (Windows) (4)failed on a work-ledger purge asserting a retention window,which is timing-sensitive on a slow runner; the work ledger reads nothing this PR changed
(
newest_segmenthas exactly one caller insrc/, the session tree) and the test passeslocally. Both are re-runs, not edits.
4e. Findings answered on
d1f8ae00b6Two, both upheld, both real, and both in the part of this change that was supposed to be
already settled.
The log ranking was itself a clock value. An earlier round made two decisions in ONE log
clock-free by ordering them on the written
seq. Across two logs of one slot the rank ledwith the header's
created_at, so the rollbackedge_supersedesdocuments as ordinary -- anNTP correction, a VM resume -- landing between one session closing and its successor opening
ranked the SUCCESSOR's log below its predecessor's. The release in the newer log then lost to
the adoption in the older one, the sidebar kept a parent that had let the session go, and the
losing decision went into the checkpoint with no path that re-reads it. The function's own
docstring claimed immunity.
log_rank_ofnow leads with the log's depth in theprevious_sidsuccession chain, which iswhat
session/openedrecords about which session replaced which -- the store's own answer,not a clock's.
created_atstays behind it as the tiebreak for two logs the chain cannotrelate (two chain starts, a predecessor retention removed), which is the weakest answer and
is now confined to the case where nothing better exists.
fold_treesorts its records by theSAME map, because the creating citation comes from a slot's oldest record and two different
orderings would let the tree contradict itself about which of its own logs is newer.
Two things that cost a round each. The chain walk is iterative and pre-detects cycles, giving
every log on one depth 0: breaking the loop at the first member visited makes the rank depend
on iteration order, and
fold_treepromises the same tree for any input order. Andfold_treereads its records twice now, so they are materialised first -- a caller handingover a generator (
reversed(...)) otherwise found it spent by the sort and folded an emptytree, which its own order-independence test caught.
The collapse fix did not cover the lane's own first frame. The citation map was cleared on
every frame while the lane was not rendering. A saved conductor view on a gateway whose tree
is not seeded yet suppresses the lane, so the FIRST adoption is the one frame that both
activates the lane and carries the move -- and with no baseline behind it the row read as
newly created, kept the collapsed default, and the session the person was looking at was
replaced by a child count on an action they did not take. That is the same defect the collapse
fix exists to prevent, surviving in the path the fix's own guard created. Bookkeeping now runs
on every frame and only
expandConductorAncestorsis gated on the lane being active.Both carry tests verified by restoring the old behaviour: the clock rank inverts the rollback
comparison and flips which log's citation stands; the inactive-lane clear hides the adopted
row on the activating frame.
4f. Findings answered on
06ccb2ae28One, and it was mine to get wrong in the first place. The First Principles lane BLOCKED on
the five media files force-added under gitignored
temp-screenshots/session-tree-adopt/.It is right, and the evidence it cites is decisive: commit
85b5362e3f(#12322, 2026-09-20)removed 167 such files with the rationale that review media now travels as GitHub
attachments,
.gitignore:114ignores that directory precisely to keep binaries out ofhistory, and
docs/system-specs/modules/stt-streaming.mdnames force-adding there as one oftwo approaches already tried and rejected.
My own reading of the history was the error. I checked that the directory had carried
committed clips before and concluded it was the convention, without checking whether a later
commit had reversed it -- and one had, three days earlier. A history search that stops at
"this used to happen" answers a different question from "is this how it is done now".
The five assets are now attached to this description as
user-attachmentsURLs viagh pr edit --attach, which is whatdocs/ci/ci-and-reviews.mdprescribes and what both UXpasses read, and the commit that added the binaries is gone -- this branch is a single commit
with nothing under
temp-screenshots/. The capture harness stays, because it is thereproducible generator rather than its output:
website/capture/session-tree-adopt.tsxandwebsite/scripts/capture-session-tree-adopt.mjsregenerate all five on demand.That also settles a disagreement between two lanes recorded earlier in this PR: Opus asked
for the clip to be dropped while the UX lane needed visual evidence to exist. The attachment
path satisfies both, and it is the one the specs already named.
4g. Findings answered on
1ba122f08cTwo, both upheld behind the review fence, both mine, and both about a decision outliving the
evidence for it. No override was posted or considered.
A
previous_sidnaming another slot's log was walked as if it were this slot's history.session/openedrecords which session a log replaced, and the depth of that chain is theleading term of the ranking that picks between two logs' decisions for one slot. The walk did
not check that a predecessor belonged to the same slot, so a link off the slot borrowed the
foreign chain's length: a log the chain cannot place at all then outranked one that was
genuinely newer, and the decision held in the loser became the fold's answer. The concrete
loss is an older adoption beating a newer release, which leaves a released session showing a
parent it was let go from.
The emitter does prove same-slot from the candidate's immutable header before writing an
edge, but that is not the only door into these records:
_record_from_jsonadmitsprevfrom the checkpoint, a plain JSON file under the data home, with no such check, and nothing
re-derives the rank once a wrong parent has been folded. Both walks now take one step through
_chain_step, which refuses a foreign predecessor the wayslot_chainalready refused itand reports as
CHAIN_END_FOREIGN. One helper rather than two call sites, because two walksthat take the step differently are two walks that can disagree about which log is newer.
A partial removal left a decision standing whose segment was deleted. Retention removes
segments before the rest of a unit, so a refusal partway through is an ordinary shape the
removal path is written to expect -- a Windows sharing violation is the reason for that
ordering. On that path the projection was told about the CREATING citation, which lives in
the first segment, and nothing was told about the decision, which is appended later and can
therefore be in any segment. The stale edge was then served as a complete reading and written
into the checkpoint. It did self-correct at the next cold start, but "until the process
restarts" is far too long for something a routine unlink refusal can cause.
reconcile_edgere-reads the unit's decision from the segments that survive, and the storecalls it on the partial-removal path. Three outcomes: a decision found replaces what was
held; a complete read finding none drops it, since that read is the only evidence which can
say a decision has been retained out of a log; a read that RAISES leaves the decision alone
and marks the reading incomplete, because dropping on a transient error discards a valid
takeover while keeping it silently serves a possibly-stale tree as authoritative.
Two details worth naming. The disk decides unconditionally here, which is the opposite of
apply_edge, where an arriving record must prove it is newer -- the argument to a reconcileis not an arrival, it is the current state of a log whose segments were just removed, so a
held decision that outranks it is exactly the stale one being corrected. And the reconcile
runs on both arms of the surviving-record test, not just the one the finding named: the
creating segment surviving says nothing about whether the decision's segment did.
Seven tests, four of them new proofs, each verified to fail when the old behaviour is
restored: the borrowed depth inverting the rank (
assert (0, 100, 's-later') > (1, 50, 's-borrower')), the decision outliving its segment, the unreadable re-read keeping thedecision and reporting incomplete, a unit holding no decision costing no file read, and the
store's call site on the arm where the record survives intact.
PR Readinesswas red only because it counts the review lane'sBLOCK-MERGEmarker as ablocking readiness item; its own two runs on that head both succeeded.
5. Any other suggestions on the work
crew_log/holders.pydecides which session HOLDS a referenced pull request using thesame tree plus an ancestor rule, and it builds its own scanner without asking for
edges -- so it keeps reading the creating shape and is unaware of adoptions. That is
deliberate here rather than overlooked: it changes who owns a PR reference, which is a
separate decision from what the sidebar shows, and it belongs in its own change with
its own tests.
One limit worth stating rather than discovering later: retention can remove the
segment a decision was written into, and then nothing on disk records it. That is the
same exposure the head read already has for a
session/openedretention removed, andit is bounded by the same switch.
The two verbs refuse while the tree cannot be read (
tree_not_ready) rather thanadopting past their own cycle guard, so a caller that arrives in a gateway's boot
window is told to retry. If that reads as noisy in practice, the fix is to have the
verb request the seed and wait for it rather than to widen the guard -- the guard is
the only thing between a takeover and a loop the fold cannot present.
session-tree-adopt-release.mp4