Skip to content

feat(session-tree): adopt and release records so one conductor can take over another - #12962

Merged
bolichen97 merged 1 commit into
mainfrom
feat/session-tree-adopt
Sep 23, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/session-tree-adopt

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

On main, rebased onto 2fdadc71ac. #12757 merged as 616e0d43e7 and this PR was
re-targeted, so the diff here is its own two commits.

The rebase onto #13007 (18f9984b04) is the one that mattered. That commit establishes
that a retained traceback pins a crew-log handle through tb_frame.f_back, not only
through its own frame, and it de-listed record_opened and _schedule_checkpoint from
the exc_info allow-list for exactly that reason. The three sites this change adds sit
on the same path: record_adopted, record_released and _record_session_tree_decision
are all reached from the emitter's writer job, whose frame binds log. So they render
the traceback as text rather than being added to the list -- resolving that conflict the
other way would have re-opened the hole #13007 closed, one commit after it landed.

What landed in main is the version this PR was always built against, not the later
local revision of #12757 that carried a _debounced_write follow-up-write test. So
test_crew_log_session_tree_projection.py still reads 34 cases rather than 35, on main
as well as here -- nothing is missing from this branch.

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} on
session/opened, stamped once by the gateway when the session is created, and the
crew 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/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
of the log. session/released carries previous_parent alone and the target becomes
a root. Both are written into the TARGET session's log with src=gateway, which is
the side session/opened.parent already 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 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. 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_tree applies the newest decision per slot and then runs its existing
cycle colouring over the result.

The projection holds EVERY log's decision, keyed (slot, sid), and lets the fold
reduce 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 seq decides, and
it 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) key
fold_tree already sorts records by. That is deliberate: one log order places both the
decisions 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_adopt refuses
a 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;
  • that read walks the unit's segments newest-first and reads a segment whole when the
    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;
  • the tail replay reads every admitted unit rather than only the new names, since the
    unit a checkpoint already holds is exactly where a decision it missed will be;
  • with_edges is OFF by default -- the succession walk has no use for where a slot
    hangs, and this costs a stat and a bounded read per unit, worth paying once on the
    cold start that has no checkpoint;
  • 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.

One deliberate deviation from the plan I was given. It said to extend
_LIFECYCLE_TYPES in store.py so the window scan sees the new kinds. 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 instead; 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 --
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_target stays 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_adopt
re-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_create and keeps the collapsed default untouched, while a
row 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 placed
parent. 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 adopter
nested under a collapsed conductor of its own would otherwise be as invisible as
before.

No new wire field, no new control, and session_create is untouched: the lane
compares 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 parent
in 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 newest
decision 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's
decisions; 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 -- True only once the entry
is on disk, False for a session with no log to write to, and False without waiting
for 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 the
parent; 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 adopted
session 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_create
default; 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-attachments assets at the bottom) is one continuous clip of an adoption into a
collapsed 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.md prescribes and what
the review lanes read: the capture script still writes into gitignored
temp-screenshots/ locally, and nothing from there reaches this branch. It is a
HARNESS recording, not a live gateway: website/capture/session-tree-adopt.tsx mounts the real ChatSidebar with
the real global CSS and initI18n(), and
website/scripts/capture-session-tree-adopt.mjs drives it in a real browser.

The harness supplies only the OCCASION. session_adopt is called by an agent, so on a
live 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. parent in
the fixture is exactly what the fold above puts on the wire -- {slot, key} after an
adoption, null after a release -- and the frames arrive as ordinary slot updates that
the 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_tree 55,
test_crew_log_session_tree_projection 34 (the same count main itself reads, as the
note at the top explains), test_crew_log_types 200,
test_crew_log_retention 59, test_slot_payload_lineage 17,
test_mcp_dashboard_registration 23, test_session_control_doc 10,
test_channel_blocked_tools 21, test_mcp_dashboard_session_send 8. On the frontend
side the five lane suites run together green -- ChatSidebar.conductorLane,
ChatSidebar.laneCardParity, ChatSidebar.flatBoard, ChatSidebar.chevronGrammar and
sessionLineage, 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 adopt and release, their endpoints, and the refusals that bound
them.

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.md plus index.md document
the 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_released and _record_session_tree_decision render the
traceback as text under #13007's rule, and the two entries that rule de-listed stay out. website/scripts/restyle-baseline.json is NO LONGER in
this diff: an earlier round dropped the MembersPage.tsx entry the ratchet reported as
progress already made, and #13008 then landed the byte-identical edit on main, so the
rebase onto 21182a5e94 removed 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_target inside the lock. The pre-lock call is kept as the cheap refusal, so an
unauthorized caller never contends for the lock at all.

The config read ran on the event loop. authorize_target is synchronous and its
session_control_enabled() re-reads and validates the config file on the first call after
an 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 -- two
warms per verb, because the lock wait is itself the suspension that invalidates the first.

The cycle guard read the nodes without their completeness. TreeReading.incomplete
means 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() and
never saw the flag, which is the case TreeReading's own docstring warns a DECIDING reader
about. It now reads reading() and treats an incomplete fold as no tree, refusing
tree_not_ready.

An unreadable store answered "no decision". find_last_tree_edge swallowed an OSError
from its directory listing and returned None, contradicting its own docstring. Both
callers 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 OSError and 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 answers None
instead of raising; the warm count reads 1 instead of 2.

4c. Findings answered on b143f6aa2a

Four 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_slots
carries one entry per in-flight append, both verbs refuse tree_write_pending on a fenced
slot, and the wait is now shielded -- a timeout that cancelled the future would resolve
it and clear the fence at the one moment it is needed.

newest_segment reported an unlistable directory as no decision. It collapsed absent,
empty and unreadable into one None, and the scanner read all three as a complete "no
decision" with incomplete false. That leaves a stale cached edge standing as the tree's
answer, 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 incomplete with
no 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 in
session-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 incomplete false; the
replay'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 42c46ebc88

One 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 unchanged
dev/ino/size and checkpointed, so anywhere on that path a swallowed OSError turns "the
bytes 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, the
listing in newest_segment, and now the stat in _scan_whole_for_types, which the
bounded window reaches only for a rotated log. That last one also contradicted itself: the
open on the next statement already propagated, so one function answered two different
ways 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 stat of the
segment, 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) failed
in MembersPage.test.tsx, a file this PR does not touch -- and the two heads either side of
that 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_segment has exactly one caller in src/, the session tree) and the test passes
locally. Both are re-runs, not edits.

4e. Findings answered on d1f8ae00b6

Two, 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 led
with the header's created_at, so the rollback edge_supersedes documents as ordinary -- an
NTP 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_of now leads with the log's depth in the previous_sid succession chain, which is
what session/opened records about which session replaced which -- the store's own answer,
not a clock's. created_at stays behind it as the tiebreak for two logs the chain cannot
relate (two chain starts, a predecessor retention removed), which is the weakest answer and
is now confined to the case where nothing better exists. fold_tree sorts its records by the
SAME 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_tree promises the same tree for any input order. And
fold_tree reads its records twice now, so they are materialised first -- a caller handing
over a generator (reversed(...)) otherwise found it spent by the sort and folded an empty
tree, 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 expandConductorAncestors is 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 06ccb2ae28

One, 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:114 ignores that directory precisely to keep binaries out of
history, and docs/system-specs/modules/stt-streaming.md names force-adding there as one of
two 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-attachments URLs via
gh pr edit --attach, which is what docs/ci/ci-and-reviews.md prescribes and what both UX
passes 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 the
reproducible generator rather than its output: website/capture/session-tree-adopt.tsx and
website/scripts/capture-session-tree-adopt.mjs regenerate 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 1ba122f08c

Two, 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_sid naming another slot's log was walked as if it were this slot's history.
session/opened records which session a log replaced, and the depth of that chain is the
leading 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_json admits prev
from 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 way slot_chain already refused it
and reports as CHAIN_END_FOREIGN. One helper rather than two call sites, because two walks
that 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_edge re-reads the unit's decision from the segments that survive, and the store
calls 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 reconcile
is 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 the
decision 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 Readiness was red only because it counts the review lane's BLOCK-MERGE marker as a
blocking readiness item; its own two runs on that head both succeeded.

5. Any other suggestions on the work

crew_log/holders.py decides which session HOLDS a referenced pull request using the
same 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/opened retention removed, and
it is bounded by the same switch.

The two verbs refuse while the tree cannot be read (tree_not_ready) rather than
adopting 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.

Conductor lane at rest: two conductors, neither opened

The branch opened on the conductor that holds it

After the adoption: the branch moved under a conductor nobody had opened, which expanded itself

After the release: the row is back at the top level

session-tree-adopt-release.mp4

@chenmingwei23
chenmingwei23 requested review from a team and smeyffret and removed request for a team September 23, 2026 01:31
@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-adopt branch from 43a52aa to 541ec45 Compare September 23, 2026 01:42
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 09df9ae

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Adoption reshapes the sidebar tree but not PR-holder routing — holders.py still reads the creation shape, a user-visible split-brain on the primary flow.

Watch

  • One tree, two authoritative readings. An adoption moves a whole branch in the sidebar, but crew_log/holders.py "keeps reading the creating shape and is unaware of adoptions" (description §5, and its scanner asks for no edges) while adopt_target itself imports is_ancestor from that same module. So the conductor a user consolidated under is shown holding the workers, while PR-reference ownership and anything else routed through holders still answers with the conductor they replaced — the takeover looks total on screen and is partial in behavior, until the deferred follow-up lands. The deferral is a defensible scoping call, but it ships an interim inconsistency on the feature's headline flow that a human, not the diff, should accept.
    Clears when: the holders follow-up PR exists (or is tracked) and the interim divergence is stated in the feature map / session-control doc rather than only in this PR's description.

[DESIGN-REVIEWED] 09df9ae

@chenmingwei23 chenmingwei23 changed the title feat(session tree): session/adopted + session/released -- one conductor can take over another (stacked on #12757) feat(session-tree): adopt and release records so one conductor can take over another Sep 23, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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

  • Adoption while the conductor lane is inactive (flat/tree/board view, or the sidebar unmounted — collapse drops citedCreatorRef entirely) discards the moved list, so switching back later shows the branch under a collapsed conductor the user never collapsed — the PR's own named failure, deferred. Occasional frequency, friction-level impact (count badge remains), per adoption. Smallest fix: queue moved identities and expand on lane activation instead of dropping them.

[UX-REVIEWED] 09df9ae

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 ships

Inventory (10 items) — 10 justified

Intent: 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.

  1. New session_adopt verb: the calling session takes another (and its whole subtree) under itself — justified
  2. New session_release verb: returns a session to the top level; a session may release itself from a stopped holder — justified
  3. Two new crew-log record kinds (session/adopted, session/released) folded as a decisions layer over the creating edge — justified
  4. Sidebar's conductor lane auto-expands the chain a session moved under; new sessions stay collapsed — justified
  5. Both verbs require an approval prompt (not auto-granted) and are blocked for channel agents — justified
  6. Checkpoint format bumped: old checkpoints discarded, one full-store rebuild at first boot after upgrade — justified
  7. Checkpoint gains a persisted negative-verdict scan cache so later boots skip whole-log reads — justified
  8. New retryable refusals (tree_unavailable, tree_not_ready, tree_write_pending) when the tree cannot be read or a prior write is in flight — justified
  9. Refused adopt/release attempts are now audited as denials — justified
  10. Capture harness + assertion script for the adopt/release sidebar beats (353 sibling harnesses in website/capture/) — justified

[FIRST-PRINCIPLES-REVIEWED] 09df9ae

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68 — this comment is updated in place on each push.

Review details

Two 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 (_refuse_if_append_pending(slot.key, ...) / _tree_append_waiter(slot.key), never caller_key), so after _tree_append_landed exits on _TREE_APPEND_TIMEOUT with the fence still standing on the target, the reverse adoption issued from that fenced session passes the is_ancestor(...) / would_cycle check against a projection the queued edge has not reached yet, both appends land, and the log durably holds X.parent == A alongside A.parent == X, which fold_tree can only flatten via _cycle_members → Fix: register and check the fence on both endpoints (slot.key and caller_key) in adopt_target.

FINDING — src/kiro_crew/crew_log/session_tree_projection.py:1028 — _replay_tail's docstring states the cold reconcile costs "a listing, a stat and a bounded read per unit" and that it "Returns (records, edges, incomplete, over_cap)", while the decision pass 100 lines below calls find_last_tree_edge — commented in the same hunk as "The WHOLE log, not a tail window" and able to fall through to a full-log _scan_whole_for_types — and the function returns the 5-tuple records, edges, scans, incomplete or over_cap, over_cap, so the next reader sizes the cold-start cost and unpacks the result from a docstring that describes neither → Fix: correct both sentences to name the whole-log decision read and the 5-tuple.

[OPUS-REVIEWED] 09df9ae

Verdict parsed from the review's SHA-scoped output markers for commit 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 09df9ae8153f78bb89b2a20742b2eb70ce3b6a68: <one-sentence reason>

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for a8956d17e5a30f1c3f30d092f33197613ca4f700; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt a8956d17e5a30f1c3f30d092f33197613ca4f700: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 23, 2026
Base automatically changed from feat/sidebar-conductor-lane to main September 23, 2026 04:35
@bolichen97
bolichen97 requested a review from a team September 23, 2026 04:35
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for d8c0f89a26071e3648ad3c3ab4122339441e5b45; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d8c0f89a26071e3648ad3c3ab4122339441e5b45: <one-sentence reason>

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 23, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-adopt branch from 42c46eb to 9c4e632 Compare September 23, 2026 09:23
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 9c4e6329452568805f695a18ac35f70ddeee4dbd; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9c4e6329452568805f695a18ac35f70ddeee4dbd: <one-sentence reason>

1 similar comment
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 9c4e6329452568805f695a18ac35f70ddeee4dbd; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9c4e6329452568805f695a18ac35f70ddeee4dbd: <one-sentence reason>

@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-adopt branch from 9c4e632 to d1f8ae0 Compare September 23, 2026 10:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for d1f8ae00b6075c9d088f654ac52ea0eae4bc97b1; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d1f8ae00b6075c9d088f654ac52ea0eae4bc97b1: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-adopt branch from d1f8ae0 to 06ccb2a Compare September 23, 2026 13:11
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 23, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/session-tree-adopt branch from 06ccb2a to 1ba122f Compare September 23, 2026 13:57
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
…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 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approved after full readiness scan: readiness: passed, required check PR Readiness green on 09df9ae, no effective CHANGES_REQUESTED, no unresolved blocking threads.

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.

2 participants