Skip to content

fix(sidebar): nest federated workers under their remote conductor - #14907

Merged
iamwhatever merged 2 commits into
mainfrom
fix/peer-rows-carry-lineage
Sep 29, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
fix/peer-rows-carry-lineage

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Sessions a connected crew opened nest under that crew's conductor in the hub's sidebar, the way the crew's own sidebar shows them.

With sessions federated from a connected crew (the On worker-1 rows), the chat sidebar's conductor lane renders every remote worker at the top level as a stray. The crew's own sidebar nests the same workers under the conductor that opened them; the hub's sidebar shows a flat list of On worker-1 -- click to open here rows with no chevron and nothing to fold. On a hub attached to a busy crew this is dozens of rows.

Why it matters

The conductor lane exists to make a crew read as one unit of work: one row with a count, the workers behind a chevron. A remote crew is exactly the case where the person is not looking at the crew's own dashboard, so the hub view is the only view they have -- and it is the one that scatters the workers.

Not a goal

  • Changing how the lane nests, folds or draws rows. The lane is untouched; it already resolved parent.key within a row's own origin.
  • Nesting a peer row under a LOCAL row, or the reverse. Citations resolve within one peer_id only.
  • Rendering the peer's own conductor lane state (which crews the peer's user opened). The hub keeps its own fold state.

What changed (motivation → approach → change)

Symptom: every federated worker is a top-level row. Root cause: the citation never reached the lane. _clean_peer_slot (the hub's allowlist for GET /api/instances/{id}/chat-slots) forwarded key, title, agent, three timestamps and two booleans and dropped parent and lineage_pending; useInstanceSessions read the same fields and nothing else. The tree existed on the peer and was stripped one hop from the reader.

Change, at both hops, in the shape a local Slot carries:

  • Hub: _clean_peer_parent shapes parent to {slot, key}, each half through the same redact-then-clamp sink as key; a citation with neither half a string is no citation and is omitted. A citation with only slot is the orphan case (lineage_parents sends key: null when the creator closed) and crosses as {slot}. lineage_pending is forwarded only when literally True, omitted otherwise -- the local payload's presence semantics.
  • Hub: a citation naming a peer slot this hub itself DRIVES is dropped whole. The driven row is already filtered out of the listing precisely so its peer slot key never crosses to the browser; the citation would carry the same key by another route. PeerSlots now hands the shaper the driven set it already computed. The child ships as a root: its creator is on screen as the local row that drives it, which the lane could not hang a peer row from anyway.
  • Hook: keeps each half when it is a string and the object when at least one survived. key is what the lane nests on; slot feeds orphanCitation, citesParent and the citedCreatorRef move baseline, so a peer child flattened by search wears the same "opened by" glyph a local child does, and a peer-side re-parent auto-opens the destination like a local adopt.
  • docs/feature-map/README.md Sessions row: the sentence saying peer rows always render as roots is replaced by the new rule.
  • Capture harness website/capture/session-tree-peer-lineage.* + website/scripts/capture-session-tree-peer-lineage.mjs: the real ChatSidebar and real useInstanceSessions over a fetch shim answering /api/instances and the chat-slots route.

Backwards compatibility

Compatible: the route gains two optional keys on a row; every existing reader ignores unknown keys, and a peer on an older build that sends no parent produces exactly today's rows.

Tests

Backend test/test_remote_crew_peer_slots.py (49 passed):

  • the allowlist test now includes parent and asserts extra keys inside the citation are stripped
  • the whole-dict survival test carries parent + lineage_pending
  • new: a citation reaches the lane unrewritten and absence stays absent; a citation with neither half a string is no citation (six malformed shapes); the orphan citation keeps slot when key is null; a citation naming a hub-driven slot is dropped while a sibling citing another creator keeps its parent, and the driven key appears nowhere in the reply; lineage_pending only when literally true; parent.key is redacted and clamped like key

Frontend (71 passed across the two files):

  • useInstanceSessions.test.tsx: no citation -> no parent/lineage_pending property; both halves forwarded; malformed shapes dropped; {slot} alone kept
  • ChatSidebar.conductorLane.test.tsx: a peer conductor with two peer workers and a same-key local row renders two roots shut by default, count 2 on the peer conductor and none on the local twin, no orphan glyph; opening the chevron shows both workers at depth 1; a search flattens the peer child and it wears the cites-parent glyph

Mutation: reverting the hub forwarding reddens 4 backend tests; reverting the driven suppression reddens its pin; dropping slot from the hook reddens 2 hook tests. tsc --noEmit clean, eslint clean on the changed files, mypy clean on handlers_instances.py, ruff check clean.

Manual verification

node scripts/capture-session-tree-peer-lineage.mjs against the dev server: 21 checks, RESULT: ok. It asserts the before frame offers no lane (no row cites anyone), the after frame has the peer conductor shut with count 3, the awaiting-approval badge and the running badge, and the opened frame nests all three workers at depth 1 with the hub's local rows untouched.

Screenshots / video

Before -- the hub's list with the citation stripped at the hub hop. No row cites anyone, so the lane is not offered; three On worker-1 workers and their lead sit flat among the hub's own sessions:

before: federated workers stray

After, shut by default -- the peer lead is one row: count 3, one worker awaiting approval, one running:

after: peer conductor collapsed

After, opened -- the three workers nest one level under it; the hub's own two sessions are unchanged:

after: peer conductor opened

Related Issues

Follow-up to #14462 (the same symptom for a crew member's own thread on the local gateway).

Pattern harvest

Rule candidate: review-prompt
Pattern: an allowlist at a trust boundary silently drops a field a downstream consumer already reads; the consumer degrades (flat instead of nested) rather than failing, so nothing red points at the boundary. Pair every allowlist with a test that enumerates the consumer's reads.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

… nest

The conductor lane nests a row under the row whose key matches parent.key
within the same origin, and it already did so for peer rows -- but the hub's
peer-slot allowlist (_clean_peer_slot) dropped parent and lineage_pending,
and useInstanceSessions never read them. So every session a remote crew's
conductor opened rendered at the top level of this dashboard as a stray,
wearing no chevron, while the peer's own sidebar nested it.

Forward parent as {slot, key} through the same redact+clamp sink as key,
omit it when the citation has no string key, and forward lineage_pending
only when literally true. The hook keeps only parent.key, the one field the
lane resolves, so a peer row is read exactly like a local one.

Pins: hub forwards/omits/clamps the citation (5 backend tests); the hook
forwards it and drops malformed shapes (2); the lane nests peer workers
under their peer conductor, shut by default, with no stray glyph (1).
Reverting either the hub or the hook forwarding reddens its pin.
@chenmingwei23
chenmingwei23 requested a review from a team September 29, 2026 02:50
@chenmingwei23
chenmingwei23 requested a review from a team as a code owner September 29, 2026 02:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 28f6eca8c10417bd7b670dc8526d34376fa3d7c7 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 28f6eca

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

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

All verification ran against a fetch-shim harness; worth one pass on a real federated peer to confirm the live wire matches the shim's shape.

[DESIGN-REVIEWED] 28f6eca

Description read

[DESCRIPTION-READ] 5eac9db50b02b1cd547deb4ebb70b0d98165c57801ca97782ee0168d7fa9c888

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

Collapsed remote crews speak only through count badges a first-time user can just guess at; hover tooltips are the sole decode layer.

Watch

  • This PR makes one shut row + badges the hub's entire view of a remote crew, so the aggregate glyphs become load-bearing: the blind reader guessed all three counts right but said "a guess for all three, honestly close to no idea on the grey one" and hesitated near the "?1" badge fearing it would commit them. Frequency: every glance at a connected crew; impact: low (readings were correct, title tooltips exist at ChatSidebar.tsx:2107,2115); persistence: constant. The lane is explicitly out of this PR's goal, so the smallest fix is a follow-up giving the collapsed aggregates a visible word or richer affordance, not a change to this diff.

[UX-REVIEWED] 28f6eca

Description read

[DESCRIPTION-READ] cbb782b3adb85064a25f08dc9d79d5e7acc2ad8c5f1202f765768213b57d920b

That sha256 names everything this verdict read: the PR description, plus the 6 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 28f6eca8c10417bd7b670dc8526d34376fa3d7c7 — 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

Confirm the #12757 doc pin ("no lineage crosses that trust boundary") described a gap, not a deliberate withholding — the base frontend already consuming peer citations says gap.

Not justified as shipped

  • Item 6 — rides along: capture harness, script and three committed screenshots are verification tooling, not the fix; declared, and the committed PNGs follow .gitignore's documented fork-contributor exception.
  • Item 7 — undeclared: website/scripts/lib/session-tree-harness.mjs and the rewrite of capture-session-tree-member-anchor.mjs appear nowhere in the description; the extraction is mandated by the jscpd 0% pretest gate, so it is harm-free.

What this change ships

Inventory (7 items) — 5 justified

Intent: FIX — sessions a connected crew opened nest under that crew's conductor in the hub's sidebar; the citation was dropped at the hub's peer-slot allowlist and the hook.

  1. Federated workers nest under their remote conductor, shut by default with count and badges — justified
  2. Peer rows flattened by search wear the "opened by" glyph; a peer re-parent auto-opens the destination — justified
  3. A peer's provisional (lineage_pending) frame no longer poisons the move baseline — justified
  4. A citation naming a hub-driven slot is dropped; that child renders as a root — justified
  5. Feature-map Sessions row now states the new peer-nesting rule, replacing "always roots" — justified
  6. New peer-lineage capture harness plus three committed screenshots — rides along (declared verification tooling)
  7. Member-anchor capture script's boot extracted into a shared harness lib — undeclared (jscpd-mandated dedup)

Consumer counts run: parent.slot/lineage_pending on peer rows — real readers at ChatSidebar.tsx:6407-6409 and lib/sessionLineage.ts; PeerSlots.driven — 1 consumer (api_instances_chat_slots); openSessionTreeHarness — 2 callers. The base test (ChatSidebar.conductorLane.test.tsx:706) already fed a peer row a parent and pinned per-origin resolution, so the hub-side drop was the mechanism-level cause, and no reversed test pin exists.

[FIRST-PRINCIPLES-REVIEWED] 28f6eca

Description read

[DESCRIPTION-READ] fde45791de5127042503b1752e6b06a00ce1177c88bfe357396cc4c6916b0db4

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@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 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 28f6eca8c10417bd7b670dc8526d34376fa3d7c7 — this comment is updated in place on each push.

Review details

The hub-driven citation drop compares the raw peer value, while the value it forwards is the _cap_str-normalized one.

FINDING — src/kiro_crew/dashboard/handlers_instances.py:1954 — if isinstance(raw, str) and raw in driven tests the peer's raw string, but shaped = _cap_str(raw, limit) then runs sanitize_string (NFC → strip_hidden_unicode → .strip()), so a peer answering parent: {"slot": " chat-7", "key": " chat-7"} (leading space, tab, trailing newline or a ZWSP — all removed) fails the in driven test, gets normalized back to the driven key, and is forwarded: the worker row keeps a citation naming the hub-driven slot whose own row was filtered out, so it renders as a root wearing the opened_by_closed_session glyph (orphanCitation → parent.slot) naming a session that is on screen and live, the exact case this hunk's docstring and test_a_citation_naming_a_hub_driven_slot_is_dropped (assert "peer-chat-9" not in json.dumps(data)) claim cannot happen → Fix: compare the shaped value — hoist shaped = _cap_str(raw, limit) above the check and test shaped in driven.

[OPUS-REVIEWED] 28f6eca

Verdict parsed from the review's SHA-scoped output markers for commit 28f6eca8c10417bd7b670dc8526d34376fa3d7c7.

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

…dd capture harness

Review round 1 (Opus, First Principles):
- forward parent.slot alongside parent.key at both hops: three lane readers
  dereference it (orphanCitation, citesParent, the citedCreatorRef move
  baseline), so a peer child flattened by search now wears the same opened-by
  glyph a local child does, and a peer-side re-parent auto-opens; a citation
  with only slot (creator gone) is the orphan case and crosses as such
- suppress a citation naming a hub-driven peer slot: the driven row is already
  filtered so its key stays off the wire, and the citation would carry the same
  key by another route; PeerSlots now hands the driven set to the shaper
- feature-map Sessions row rewritten: peer rows nest, citation clamped and
  redacted, resolved within peer_id only
- capture harness (capture/session-tree-peer-lineage.*): before / shut / opened
  frames through the real ChatSidebar + useInstanceSessions with a fetch shim
  on the two federated routes; the after frame is a fresh load, not a payload
  swap, which the lane would read as an adopt
@chenmingwei23
chenmingwei23 force-pushed the fix/peer-rows-carry-lineage branch from 9a79367 to 28f6eca Compare September 29, 2026 04:14
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 29, 2026

@iamwhatever iamwhatever 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.

Reviewed. _clean_peer_parent runs both halves of parent through the same redact-then-clamp path as key, drops a citation with neither half, keeps the slot-only orphan case, and citations resolve only within one peer_id so a peer row cannot nest under a local row. Nothing reaches a non-owner. Tests cover malformed shapes, orphan, driven-citation drop, redaction and clamping.

Non-blocking: the driven-key check at handlers_instances.py:1954 compares the raw value before sanitizing, same as the existing row filter at :2193; comparing after _cap_str in both places would close a tiny gap. Also note temp-screenshots/ PNGs are committed.

@iamwhatever
iamwhatever enabled auto-merge (squash) September 29, 2026 06:31
@iamwhatever
iamwhatever merged commit 7088013 into main Sep 29, 2026
104 of 105 checks passed
@iamwhatever
iamwhatever deleted the fix/peer-rows-carry-lineage branch September 29, 2026 06:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants