Skip to content

feat(instances): add crew= scope to the session read MCP tools - #6874

Closed
cixuuz wants to merge 1 commit into
mainfrom
feat/crew-scoped-session-reads
Closed

cixuuz wants to merge 1 commit into
mainfrom
feat/crew-scoped-session-reads

Conversation

@cixuuz

@cixuuz cixuuz commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent can search, list and read a named peer crew's chat sessions with the three session read tools, under the same owner-only bar the dashboard's federated search already enforces.

An agent cannot read another crew's chat history. search_chat_history,
list_sessions and get_chat_session only ever see the local ConversationLog.

The dashboard can already do this — /api/instances/search-sessions searches
every connected crew. An agent has no equivalent, so "what did chick decide about
the retry budget?" is a question you answer by hand.

Teleport (#10288) does not cover it. Adopting a peer session copies its history
down, so local search finds that one conversation — but you must already know
which session you want and pick its row, and the peer row list is live sessions
only
. Discovery across sessions you cannot yet name, and any peer session not
currently open, stay unreachable.

Why it matters

Cross-crew consultation is the one thing a fleet of crews cannot do for itself.
Without it every peer lookup needs a human in the loop — exactly the work a second
crew was supposed to absorb.

Not a goal

What changed (motivation → approach → change)

Piece What it does
crew=<id|name> on the three read tools (validation.py, mcp_tools/sessions.py) Reads that crew instead of the local log. Selector is bounded at MAX_SHORT_STRING, control characters only barred.
/api/crew-sessions/search|list|read (server.py, handlers_instances.py) MCP-only GET routes on the local gateway, registered in _register_mcp_routes so a headless gateway has them too. search rides search_sessions_remote; list/read ride the generic proxy_request carrier.
_authorize_crew_read + rosters in src/kiro_crew/constants.py A positive two-tier caller roster: internal secret, no app claim, and a present X-Session-Key that is owner-minted (dashboard:) or delegated (subagent:/side:) with an ancestry walk that ends in an owner-minted, still-present, non-app-owned slot. Everything unresolvable refuses.
?exclude_incognito=1 on api_session_detail (handlers/sessions.py) The crew read leg sets it. The arm reads through ConversationLog.derive_messages, the same derivation seam the local get_chat_session uses: a restricted or unreadable line answers [], a busy lock answers 503 transcript_busy. The dashboard's own click-through is unchanged.
PEER_SESSIONS_REPLY_MAX_BYTES (instances/constants.py) An 8 MB cap sized for a whole transcript, read via read_capped_response.

The MCP process cannot touch the tunnel, so each tool asks the local gateway.
Each tool spells its route as a literal at the _get call site with only the
query dynamic, so test_every_transport_call_resolves_to_a_path can name the
endpoint every crew call reaches — no _KNOWN_UNRESOLVED entry.

Who may call is the load-bearing part: these routes disclose a peer's titles,
snippets and whole transcripts under the owner's credential. A namespace proves
the gateway minted a key, not for whom, so the roster names who MAY call rather
than who may not. A denylist admitted a channel-born session twice; a flat
allowlist admitted a Slack-parented subagent. A subagent's parent comes from the
live in-memory run record only (the persisted one is agent-writable); a side chat
resolves to its dashboard slot with the generation suffix dropped. cron,
secretary, the workflow family and taskrunner are deliberately NOT delegated
namespaces, and adding one without a resolver refuses. A key naming a vanished
slot is refused first (caller_session_missing), on both the caller and the
walk's terminal step.

Each tool resolves its key once through require_strict_session_key; that same
key is checked and put on the wire (a required positional on the three crew
helpers). A Crew Member session bound to its own memory store is refused
cross-crew reads before the tunnel, reading only its own binding via
private_memory_store_for_session; an unreadable binding refuses too.

Peer replies are untrusted: known keys only, types checked, text redacted before
clamping; search/list drop rows whose memory_mode is incognito/temporary
or malformed; read filters to RECALL_ROLES and tail-caps. Reads are bounded
by _CREW_PROXY_TIMEOUT (→ 504).

docs/system-specs/modules/instances.md §17 carries the contract.

Backwards compatibility

Compatible: crew is optional on every schema; without it the tools' local paths are unchanged. The three routes are new. api_session_detail without exclude_incognito is unchanged.

Tests

test/test_instances.py::TestCrewScopedSessionReads pins the routes: the
internal-secret gate, the unknown-crew 404, key vetting, proxy-error mapping and
reply reshaping; one refusal pin per route for channel-minted, app-minted and
non-owner callers; admission pins so a fail-closed guard cannot over-refuse. The
ancestry walk is pinned as a walk: control first (owner-spawned subagent
admitted), then the Slack-parented subagent refused, absent/done/reaped/blank
parent records, a raising lookup, a cycle (403, not a hang), a chain over
_ANCESTRY_MAX_HOPS, and a delegated namespace declared without a resolver. The
peer memory_mode guard is pinned end to end ([] drops the row, sibling still
listed). The exclude_incognito arm is pinned off the event loop on the thread,
and its seam arms are pinned: TranscriptWithheld → [], TranscriptBusy →
503, the plain read_messages never reached.

test/test_crew_scoped_session_reads.py (new) covers the tool-side crew
branches: error, empty and formatting paths, the query builder, the literal-path
property and the strict-identity and fail-closed arms.

test/test_member_memory_runtime.py pins the member-store fence on a real
binding and that the peer helper is never invoked for a fenced caller.

Manual verification

N/A — unit coverage sufficient. The routes have no UI, and the authorization arms
and reply reshaping are exercised directly at the handler.

Screenshots / video

N/A — no user-visible frontend surface is touched.

Related Issues

no linked issue for the capability itself: this adds one rather than fixing a
tracked defect.

Deferred from review, tracked rather than fixed here:
#11954 — the incognito
exclusion on the crew read path is peer-honored for an older peer that ignores
exclude_incognito, because a transcript array carries no memory_mode for the
hub to filter on. Linked from §17.3, which is that finding's own clearing condition.

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

@cixuuz
cixuuz requested review from a team and hoang-phan98 August 29, 2026 23:18
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Aug 29, 2026
@github-actions

github-actions Bot commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the live-record-only ancestry walk is acceptable ops-wise: owner-spawned subagents lose crew reads after gateway restart or run completion, by design.

Suggestions

  • The two-tier provenance walk (_authorize_crew_read + rosters) is the codebase's first positive owner-provenance predicate for internal-secret callers; consider a follow-up hoisting it out of handlers_instances.py into token_auth so the next owner-gated MCP route reuses it instead of reinventing or diverging from mcp_dashboard._DELEGATED_CALLER_PREFIXES.

[DESIGN-REVIEWED] c2f92ba

@github-actions

github-actions Bot commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of c2f92ba5dd88d9c8f63579753683ddeaf3480137 — 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: CONCERNS

The entire crew= surface rests on an asserted use case plus dashboard symmetry — no issue, user report, or recorded decision names the need.

Not justified as shipped

  • Item 1 — inherited: the capability's provenance is the description's own argument ("Cross-crew consultation is the one thing a fleet of crews cannot do for itself") plus symmetry with the dashboard's federated search ("The dashboard can already do this"), which is the symmetry form of an inherited requirement; the permanent cost — three endpoints, two exported rosters, and an ancestry-walk concept every future reader of session auth must learn — is carried by that assertion alone.
    Subtraction: defer the crew= scope (everything else in this PR exists only to serve it) until the need has a checkable record.
    Clears when: a linked issue, user request, or maintainer acceptance names who needs agent-side cross-crew reads.

The zero option is not free — a multi-crew operator answers peer questions by hand today, and teleport (#10288) genuinely does not cover discovery — so this stays advisory, not a block. Verified: _get's 10s default supports the 8s budget claim; search_sessions_remote, read_capped_response, and caller_names_a_missing_slot all exist as cited; the rosters' one consuming module is the guard itself, and no test or pin is deleted anywhere in the diff.

What this change ships

Inventory (10 items) — 9 justified

Intent: let an agent search, list, and read a connected peer crew's chat history without a human intermediary — an ADDITION.

  1. The three session-read MCP tools take optional crew=<id|name> to read a peer crew instead of local history — inherited: supported only by the description's argument and dashboard symmetry.
  2. Three new MCP-only gateway endpoints (/api/crew-sessions/search|list|read), present on headless gateways too — justified
  3. Crew reads are owner-only: app-minted, channel-born, cron, workflow, and unresolvable delegated callers get 403 via a two-tier roster plus bounded ancestry walk — justified
  4. Local session-detail route gains opt-in ?exclude_incognito=1; the dashboard's own reads are unchanged — justified
  5. Peer replies are redacted, clamped, incognito-filtered, and capped at a new 8 MiB bound — justified
  6. A session fenced to a private member store is refused any crew read — justified
  7. Every crew read emits a SEL audit event naming the calling session — justified
  8. A reachable-but-slow peer returns a clean 504 inside the MCP client's timeout — justified
  9. Spec section 16 documents the scope in the same commit — justified
  10. crew values are validated (control characters barred, length-bounded, exact registry match) — justified

[FIRST-PRINCIPLES-REVIEWED] c2f92ba

@github-actions

github-actions Bot commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — 🔴 changes requested (blocking)

GPT 5.6 found at least one blocking issue that must be resolved before merging c2f92ba5dd88d9c8f63579753683ddeaf3480137. 1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/dashboard/handlers_instances.py:1579 -- Older peers expose incognito transcripts
data = await _crew_proxy_json(mgr, iid, peer_path, {"exclude_incognito": "1"})
Known incognito key -> older peer ignores the parameter -> private transcript is returned.
Anchor: residual/security
Fix: Refuse direct reads unless the peer positively supports incognito enforcement.

FINDING -- src/kiro_crew/instances/constants.py:311 -- "8 * 1024 * 1024" rejects valid transcripts below the existing 10 MiB rotation threshold -> Fix: raise the bound above the maximum valid response size.

[BLOCK-MERGE] c2f92ba
[GPT-REVIEWED] c2f92ba

Adjudication (Opus 4.8) — is blocking on each finding proportionate?

The adjudicable block is empty; only the fenced finding F1 requires a ruling.

F1 — Harm rung: UNBOUNDED (cross-crew exposure of a session explicitly marked incognito/private; once the transcript enters the agent's context the disclosure is irreversible and silent). Conditions confirmed from code opened this run: the read proxy relies solely on the peer honoring exclude_incognito=1 (handlers_instances.py:1579); the peer honors it only from sessions.py:1412 onward, so an older peer returns the full array; the sole hub-side backstop is the discovery filter _peer_row_is_restricted, which returns False for an ABSENT memory_mode (handlers_instances.py:1024,1037-1038), so a peer old enough to ignore exclude_incognito and to omit memory_mode from its list rows also surfaces the incognito key via crew list/search (handlers_instances.py:1516). Recovery path: none — nothing reverses the read. Rarity: this is a routine version-skew the author's own doc tracks as an open residual (instances.md:2000-2005, #11954), not an extreme or self-contradicting combination — the same single old peer plausibly enables both the key-discovery and the ignored-parameter halves, so I cannot complete a rarity record that would justify FLAG. When torn on an unbounded-harm fenced finding, UPHOLD-FENCED.

[ADJUDICATION] c2f92ba5dd88d9c8f63579753683ddeaf3480137 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] c2f92ba5dd88d9c8f63579753683ddeaf3480137
[ADJUDICATION-FENCED] c2f92ba5dd88d9c8f63579753683ddeaf3480137 fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/dashboard/handlers_instances.py:1579 -- Unbounded, irreversible cross-crew exposure of an incognito transcript via a routine (not extreme) version-skew peer that ignores exclude_incognito and can also leak the key through its own list rows; no rarity record supports clearance.
[GPT-ADJUDICATED-FENCED] c2f92ba5dd88d9c8f63579753683ddeaf3480137

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c2f92ba5dd88d9c8f63579753683ddeaf3480137: <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 Aug 29, 2026
@github-actions

github-actions Bot commented Aug 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] c2f92ba

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

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

@cixuuz
cixuuz force-pushed the feat/crew-scoped-session-reads branch from 3e19c28 to 6137380 Compare August 29, 2026 23:41
@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 Aug 29, 2026
@bolichen97
bolichen97 enabled auto-merge August 29, 2026 23:43
@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 Aug 29, 2026
@cixuuz
cixuuz force-pushed the feat/crew-scoped-session-reads branch from 6137380 to 5091ee7 Compare August 30, 2026 00:00
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Aug 30, 2026

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

Description / code mismatch

The Description's checklist states existing tests pass, but the new transport wrapper in mcp_tools/sessions.py deterministically fails a pre-existing exhaustiveness gate on every shard that collects it.

1. Diff breaks the internal-secret call-site coverage gate, while the checklist claims existing tests pass

The Description says — > - [x] Existing tests pass and new tests added for new functionality

The code does — the new _crew_query wrapper (def at src/kiro_crew/mcp_tools/sessions.py:194) funnels all three crew tools through a single transport call whose path is a runtime-composed f-string, mcp_core._get(f"{path}?{qs}" if qs else path), at src/kiro_crew/mcp_tools/sessions.py:201. test_every_transport_call_resolves_to_a_path in test/test_mcp_call_site_auth_coverage.py:513 walks every mcp_core._get / transport call site and requires each to resolve to a literal /api head; this one does not resolve, and the site is not in the reviewed _KNOWN_UNRESOLVED exemption set, so the gate fails.

Risk — the failure is platform-independent and deterministic: any shard that collects test_mcp_call_site_auth_coverage.py goes red, which is consistent with the four red Backend Test shards on the head SHA (3.10 shard 2, 3.12 shard 2, Windows shards 1 and 2) plus the Coverage Gate — though the check-run payloads carry no summary text, so that attribution is circumstantial and the reproduced local failure is the blocking fact. The gate exists because registering a dashboard route and granting it internal access are two separate manual edits; its entire value is exhaustiveness. One stray unresolved call site means the suite can no longer vouch for any MCP call path, not just this one. Merging as-is either lands a red gate or invites silencing it by editing the ratchet the test explicitly says not to edit.

Required change — make the transport call resolvable to a literal /api head: build the query string at each call site and pass a concrete path, or drop the wrapper and call mcp_core._get("/api/crew-sessions/search?...") per tool, so test_every_transport_call_resolves_to_a_path passes. If the wrapper is kept, take the reviewed _KNOWN_UNRESOLVED exemption deliberately and state that choice. Either way, the Description's "Existing tests pass" box must reflect the real state.

@bolichen97

Copy link
Copy Markdown
Contributor

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

  • PR #7693 is OVERLAPPING relative to this PR. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #7693: MERGE_DISCUSSION. Thematically adjacent within the remote-crew work, materially different in scope and consumer; the two peer reads are independent. Files: src/kiro_crew/dashboard/handlers_instances.py. The two independent directions used different labels; the matrix conservatively retains OVERLAPPING for coordination.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.

@dwu96 dwu96 added the needs-pr-triage PR scanner: awaiting automated triage label Sep 7, 2026
@NicholasRBowers NicholasRBowers added needs-author-decision PR blocked on author input and removed needs-pr-triage PR scanner: awaiting automated triage labels Sep 7, 2026
@NicholasRBowers

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew [operator: NicholasRBowers#a942f9ca]: This PR has been inactive for 7+ days. I reviewed the blockers but they require your input:

  • bolichen97's CHANGES_REQUESTED (2026-09-02) is awaiting your response: the call-site auth coverage gate rejects _crew_query's runtime-composed path (sessions.py:194–201) — inline literal /api/crew-sessions/... paths per tool, or take an explicit _KNOWN_UNRESOLVED exemption. The choice shapes your wrapper design, so it's yours to make.
  • GPT's blocking finding at handlers_instances.py:920: the owner-guard doesn't reject messaging-channel callers carrying the internal secret with no app claim — the identity model for _require_internal_secret is a design decision.
  • A rebase onto main is needed, and the Design/First-Principles advisory CONCERNS lanes still need written dispositions.

When you've addressed these, the pipeline will re-assess on its next cycle.

@cixuuz

cixuuz commented Sep 19, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: keep the peer parameter, record the unenforced half as tracked debt and link it from the spec paragraph that claims it

Taken as written, including the version-skew case the finding names: an older
peer does not know exclude_incognito, ignores it, and serves the marked
transcript, so the guarantee on read is peer-honored rather than enforced here.

Removal is not the smaller option. The hub cannot filter locally on this path
because read receives a raw message array that carries no memory_mode —
unlike search/list, whose rows do, which is exactly why the discovery half IS
enforced locally and is the version-independent floor. Dropping the parameter
would lose the same-version peer's compliance and gain nothing, so the honest
disposition is to keep it and record what it does not cover.

#11954 carries both candidate shapes with their trade-off: a peer per-session
metadata endpoint (general, also serves any future per-session check on read)
or a peer-capability gate that refuses the crew read against a peer that cannot
confirm it understands the parameter (cheaper, fails closed against an old peer).
It names the three handler sites and the §16.3 paragraph, and carries the
deferred-finding label, an assignee and a Due: line.

§16.3 previously called this "a tracked follow-up" while linking nothing, which
is the gap this finding identified; the paragraph now links #11954 and states why
the discovery half is enforceable locally and the read half is not.

@cixuuz

cixuuz commented Sep 19, 2026

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: keep both authorities, state why their defaults differ, and accept the promote-on-second-consumer condition as written

  • accepted-and-deferred span=dff0cd0d8dbb — the promotion trigger is a second consumer, which does not exist yet; the divergence itself is now stated rather than left implicit

The observation is correct and worth recording: _DELEGATED_CALLER_PREFIXES
refuses subagent:/cron: outright, while DELEGATED_SESSION_NAMESPACES treats
the same two namespaces as permission to ask via the ancestry walk. Two
authorities, opposite defaults, same namespaces.

They are not in conflict, but the reason is not self-evident from either site, so
it is the part that needed writing down. mcp_dashboard's tools MUTATE dashboard
state on behalf of the caller, and its docstring's reasoning is that a delegated
caller's missing app claim "proves nothing about who it runs for, so it is refused
rather than granted the person's authority" — for a mutation, refusing is the only
safe default because there is nothing to verify against. A crew read is a read,
and it has a gateway-held record to verify against, so it can ask the question
that module could not. The same docstring names this resolution as "the sound
shape", so the walk implements what that comment points at rather than
contradicting it.

On the promotion: accepted as written, and deferred on the finding's own condition
— "when a second route needs the ancestry walk". There is exactly one consumer
today, and extracting a shared module for one caller would move the code without
reducing anything. Extraction is also the natural first step of the larger
construction this gate keeps pointing at (an owner-minted capability that removes
caller introspection altogether), so promoting it now would likely be the wrong
shape to promote.

One change landed in this round that reduces the count locally rather than
globally: the door and the ancestry walk's terminal step both apply
caller_names_a_missing_slot, and the walk's half is factored into
_owner_minted_and_attributable so a terminal step cannot skip the check the door
performs.

@cixuuz
cixuuz force-pushed the feat/crew-scoped-session-reads branch from b9c5d2f to 1ac57c6 Compare September 19, 2026 06:15
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 19, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

Maintainer note: PR #11780 (merged 2026-09-19, bc0d2b0cf, "simplify member memory to one SQLite store") removed the protected-binding / private-execution member memory model. Two PRs written against the old model merged after it with a textually clean merge and broke main at import time (#11947, #11960); both are now reverted. This PR carries the same hazard.

Already conflicting; when rebasing please also update test_crew_scoped_session_reads.py:384 and test_member_memory_runtime.py:893 (monkeypatch of _history_memory_scope, removed) and the docstring references in mcp_tools/sessions.py:246-247. The crew= scope will also need a replacement for the removed private_history_session_index.

An agent could only ever read the local ConversationLog. This adds an optional
crew=<id|name> to search_chat_history, list_sessions and get_chat_session so it
can read a named peer crew's sessions, which teleport does not cover: adopt needs
a session you can already name and lists live sessions only.

The MCP process cannot touch the tunnel, so it calls three MCP-only GET routes on
the local gateway (/api/crew-sessions/search|list|read), registered in
_register_mcp_routes so a headless gateway exposes them too. Search reuses
search_sessions_remote; list/read ride the generic proxy_request carrier, so the
credential never leaves the manager and no new peer-request method exists.

Authorization is a POSITIVE roster in two tiers, because a namespace proves the
gateway minted a key and not for whom. These routes disclose a peer's titles,
snippets and whole transcripts under the owner's credential, so
_authorize_crew_read requires the internal secret, refuses any app claim, and then
requires that a PRESENT X-Session-Key be owner-minted. Written as a denylist this
leaked twice, first admitting a channel-born session (which carries no app claim at
all, so a Slack participant arrived shaped like the owner) and then admitting the
legacy app-platform channel: prefix that CHANNEL_SESSION_NAMESPACES deliberately
omits and parse_session_key names as a shape the classifiers do not cover. A flat
allowlist then leaked on delegated work: spawn_run mints subagent:<id> identically
whether the parent is the person's tab or a Slack participant's thread, so
admitting that namespace by prefix handed a channel-parented child the owner's
authority.

OWNER_MINTED_SESSION_NAMESPACES is (dashboard,) alone - the only namespace whose
NAME settles who minted it. DELEGATED_SESSION_NAMESPACES (subagent, side) is
permission to ask: _delegated_caller_is_owner_minted walks parent pointers, bounded
and cycle-guarded, and admits only a chain ending in the terminal tier. Every
unresolvable step refuses, and which steps are unresolvable is the design. A
subagent's parent comes from the live in-memory record only, because
subagent_persistence writes parent_session into an agent-writable run folder, so a
child could name its own parent; a finished run loses the read, matching
has_live_shared_session's rule that run records are display state and not session
authority. A side chat resolves to the dashboard slot named in its own key with the
GENERATION SUFFIX DROPPED: side:<slot>:<gen> is the shape derive_caller_app
mishandles - it looks a slot up by everything after the first colon, so <slot>:<gen>
matches nothing, an app-owned side chat resolves to no app, and the key reads as the
person. Keeping the suffix would both miss the app claim and refuse every
legitimate side caller, so a control test pins the ordinary case first.

A listed namespace needs an ancestry record that is gateway-held AND outside the
agent's write reach. cron satisfies only the first: CronJob.session_key is read
from crons.json, which sandbox.py exposes to the crew sandbox as a visible leaf
that mcp_cron "both reads and rewrites", so an agent acting for a channel
participant can set a job's session_key to a dashboard: value and clear the walk,
and a tool-gate text matcher does not fence it because a plain open() write never
reaches the shell. That is the same objection that keeps the persisted subagent
parent_session out of the resolver, so it is applied to both record classes rather
than one. secretary is excluded because it has no construction site in src/ at all;
the session-address RFC records that absence and asks whether an external app can
mint it, and an app is exactly the minter that must not inherit owner authority, so
an unanswered provenance question cannot carry the terminal claim. The workflow
family and taskrunner are excluded for the first clause instead: a run's originating
key is derived from the request header at the workflow endpoints and documented as
spoofable there, so resolving ancestry through it would authorize against a value
the caller chose. Adding to the delegated roster without writing a resolver also
refuses, and a test pins that.

The walk's terminal step refuses an APP-OWNED parent as well as a vanished one.
Reaching an owner-minted namespace establishes that the gateway minted the key, not
that the person owns it, so a delegated caller whose own app claim is unreadable
would otherwise inherit authority from a slot an app owns - the disclosure the
door's request["app"] arm exists to stop, which by construction cannot fire for the
caller whose claim is the one that went missing. The check reads the slot registry
directly rather than through derive_caller_app, whose first-colon lookup is the
blind spot in question, and it lives in the shared predicate so it covers subagent
as well as side: a subagent record with no app whose parent tab IS app-owned is the
same shape, and no lane reported it.

Provenance keys on the X-Session-Key namespace, which the broker sets from the
calling session and _verify_unix_peer attests, not on the slot's agent-writable
channel_origin flag. An absent key stays admissible: that is the gateway, the CLI
and a loopback curl, which already hold the internal secret. The rosters are
deliberately not derived from messaging.link's telemetry prefixes, which contain
channel and would re-open the first hole; homing them in constants.py (stdlib-only)
also lets the import be module-level rather than deferred off the gateway boot
path. is_owner_dashboard_request cannot be used directly because it requires a
dashboard user claim this transport never sets.

A key naming a slot that is GONE is refused ahead of the roster on its own arm,
because it is the one case where every positive signal still reads as the owner: an
app-owned tab popped while a call is in flight loses the app claim that would have
refused it while its dashboard: namespace survives. caller_names_a_missing_slot is
the existing predicate for that class and now gates these routes with a distinct
caller_session_missing refusal, and the ancestry walk's terminal step applies the
same predicate through _owner_minted_and_attributable, so a delegated child cannot
inherit through a parent whose slot has vanished - a path the door's own check
cannot see, since the caller there is subagent:. The predicate is dashboard:-only
by its own design, which lines up exactly with the owner roster holding dashboard
alone.

An absent X-Session-Key stays admissible at the route and must, which is why the
caller side must not produce one by accident: _get omits the header entirely when
resolution yields empty, so a crew read whose identity degraded would arrive shaped
like the gateway itself. Each tool resolves through require_strict_session_key at
its entry and that same key is both checked and put on the wire, so no path checks
one identity and acts as another - what _get's own contract calls a check-then-use
split, since the lenient /proc walk resolves a subagent to its parent slot. The
verified key is a required positional parameter on all three crew helpers, so a
call site that omits it is a TypeError and not a silent return to lenient
resolution, and an end-to-end test drives the real tools rather than the helpers so
a dispatch site passing a leniently-resolved key cannot satisfy the signature and
pass.

The private-memory fence is local to the crew path and reads only the caller's own
binding, through private_memory_store_for_session: a non-empty store name is a Crew
Member fenced to a private V2 store, which cannot read another crew's history. No
local record could adjudicate a peer key - a remote crew's transcript carries no
local private-store provenance - so the refusal happens before the tunnel and a
test asserts the peer helper is never invoked. An unreadable binding refuses too,
since it is indistinguishable from a fenced member whose store could not be
confirmed and "unknown" on a cross-crew read has to fail closed.

get_chat_session's peer leg sets exclude_incognito=1 so a remote read cannot reach
a marked session the local tool also refuses, and that arm's get_metadata runs off
the event loop like the read_messages call beside it - it stats the transcript and
parses its first line, which was blocking the loop on the one path a remote agent
can reach. Each tool spells its own route path as a literal at the _get call site,
with only the query dynamic, so the transport-auth guard can resolve every crew
call to the endpoint it reaches.

The crew selector is bounded at MAX_SHORT_STRING, matching SELECT_CREW_SCHEMA's own
crew field, because Instance.validate caps no length at all: a 64-char bound
refused a display name the operator can see in the roster. The handlers clamp the
query value at the same bound rather than 64 characters, so a registered name
longer than that is not silently cut and answered crew_unknown.

Adds spec section 16, TestCrewScopedSessionReads, and
test_crew_scoped_session_reads.py covering the tool-side crew formatting, error and
empty-result paths plus the strict-identity and fail-closed arms. Spec 16.3 links
issue #11954 for the one half this does not enforce locally: a transcript array
carries no memory_mode, so the incognito exclusion on read is peer-honored while
the discovery-path exclusion is enforced here.
@cixuuz
cixuuz force-pushed the feat/crew-scoped-session-reads branch from 1ac57c6 to c2f92ba Compare September 20, 2026 18:53
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 20, 2026

Copy link
Copy Markdown
Contributor

Open-PR triage (2026-10-05): rebase needed, open security blocker, overlap coordination

Compared head c2f92ba5dd against origin/main af1eb612da (merge base 8169d3cf25). I read the full diff, not just the description.

Relationship to main: DISTINCT, not superseded. origin/main has no /api/crew-sessions/* routes, no _authorize_crew_read, no crew= on search_chat_history/list_sessions/get_chat_session, and no PEER_SESSIONS_REPLY_MAX_BYTES. Two merged PRs are next to this one but don't cover it:

Rebase needed. This branch is 2140 commits behind main. git merge-tree reports conflicts in 4 files:

  • docs/system-specs/modules/instances.md
  • dashboard/handlers/sessions.py
  • dashboard/handlers_instances.py
  • test/test_instances.py

The biggest semantic change since the merge base is in api_session_detail, now at handlers/sessions.py:2120 on main. It now starts with _app_transcript_refusal and has an app-owned read path that returns _app_transcript_busy (#16198). The exclude_incognito arm has to be re-placed relative to that gate, not just textually merged.

Security blocker is still open. This is the GPT 5.6 lane's fenced BLOCKING finding, so I'm not filing a separate request-changes. get_chat_session crew= relies on the peer honoring exclude_incognito=1 (handlers_instances.py crew read leg). An older peer ignores the parameter and returns an incognito transcript. On that path the hub-side _peer_row_is_restricted floor treats an absent memory_mode as unrestricted. Issue #11954 (an Issue, open) tracks this but doesn't fix it. Disclosure of a private transcript can't be undone, so this needs the fail-closed peer-capability gate (option 2 in #11954), or an equivalent, before merge rather than as follow-up.

Description vs. code mismatch. The description says the exclude_incognito arm reads through ConversationLog.derive_messages, returns [] on TranscriptWithheld and returns 503 transcript_busy on TranscriptBusy. The pushed diff does none of that. Its arm is get_metadata + is_incognito_transcript followed by the plain read_messages. No derive_messages, TranscriptWithheld, TranscriptBusy or transcript_busy appears anywhere in the diff, including tests. Please push the intended code or correct the description.

Merge discussion (OVERLAPPING, complementary, not duplicate):

Recommendation: CONTINUE-DEVELOPMENT + REBASE. Keep this PR open; it is not a closure candidate.

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

Requesting changes on head c2f92ba. The branch conflicts with main in 5 files (instances.md, handlers/sessions.py, handlers_instances.py, server.py, test_instances.py) and is about 2,840 commits behind; please rebase and re-run CI, as PR Readiness and the review lane are red on this head.
The earlier call-site coverage finding looks addressed on this head. The outstanding changes-requested review from the maintainer still needs a response before this can move forward.

@cixuuz

cixuuz commented Oct 22, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #23034, which is this same branch rebased onto current main (3,995 commits) and re-opened from a fork, because I no longer hold write access to this repository and cannot push to this PR's branch.

Everything raised here is carried into #23034:

  • Rebase and the fix(remote): seed an adopted slot's workspace from the peer row #12992 overlap (@bolichen97's 2026-10-05 triage): rebased onto 3d6cda4f3a; main had split every touched file into *_parts owner modules, so the crew reads now live in handlers_instances_crew_reads.py as an owner of the handlers_instances facade, with the exclude_incognito arm in sessions_parts/history_reads.py placed after the app-scope gate.
  • Description vs. code: the derive_messages / TranscriptWithheld / TranscriptBusy arm is in the code, with tests.
  • The GPT lane's security blocker, Crew read: the incognito exclusion on get_chat_session is peer-honored, not enforced #11954: enforced by the reader now. The peer's api_session_detail confirms it understood exclude_incognito=1 with X-KiroCrew-Incognito-Excluded: 1, and the hub refuses a reply without that header as crew_peer_too_old before reading its body.
  • Local review on the rebased head (Opus, GPT) found and fixed three more: the peer's 503 transcript_busy was collapsed into "malformed", a display name two crews share resolved to the first row, and the feature map lacked the row.

Closing this one so there is a single thread. Thank you @bolichen97, @chenmingwei23 and @iamwhatever for the reviews here.

@cixuuz cixuuz closed this Oct 22, 2026
auto-merge was automatically disabled October 22, 2026 06:06

Pull request was closed

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 22, 2026
bolichen97 pushed a commit that referenced this pull request Oct 29, 2026
Co-authored-by: Zejiang Guo <zejiangg@amazon.com>
@bolichen97
bolichen97 deleted the feat/crew-scoped-session-reads branch November 6, 2026 07:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge conflict Branch has merge conflicts with its base — author must resolve before merge needs-author-decision PR blocked on author input

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants