Skip to content

feat(members): give every crew a configurable webview in its drawer - #8468

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/crew-webview
Sep 21, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/crew-webview

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

The crew's dashboard, docked in its drawer -- the crew decides what goes here:

Docked summary

Expanded to the full window:

Expanded dashboard

A crew that has published nothing says so, rather than showing an empty box:

Empty state

When the panel read fails, the drawer shows the error notice, an agent hand-off, and a "Try again" retry rather than an empty box:

Error state with Try again

While the read is in flight, a pulsing skeleton stands in for the dashboard:

Loading skeleton

The expanded view while a render is in flight, and the aged band when a
re-mint fails and an older document stays on screen:

Expanded rendering

Expanded mint error

The expanded view when the FIRST mint fails, so nothing has ever rendered: the band
carries the hard sentence, the frame below it holds nothing, and the retry stays:

Expanded first-mint failure

The expanded view when a NEWER version was published and its refresh failed: the bar's chip dates the new version, the band names the version still on screen, so the two ages are two different facts rather than one clock read twice:

Expanded republish error

Expand and collapse, recorded from the built SPA:

08-expand-collapse.webm

1. What is the problem

A crew has nowhere to show its own state.

The member drawer shows what KiroCrew knows about a crew -- session counts, wake sources, configuration. It shows nothing the crew itself wants to say. A conductor running a fleet of workers knows things no generic UI can guess: which item is blocked on a human ruling, which worker has been stuck for two cycles, what it intends to do next, and why a count does not add up. Today that exists only in chat scrollback, so it is gone by the next turn and invisible unless someone reads the transcript.

The obvious fix does not scale. A native panel per crew means every new crew shape needs a frontend change, a release, and a schema the crew must be taught. And a crew is an LLM: whatever it produces cannot be handed the dashboard's origin.

2. Why it matters to the user

Someone supervising a long-running crew has to read a transcript to answer the only question they actually have: does this need me? The drawer is where they already look, and it cannot tell them.

This also removes a per-crew frontend release from the loop. A crew that wants to surface something new publishes different data; nobody ships a UI change to make it visible.

3. How our fix solves it

The root cause is that presentation was coupled to the frontend release cycle, and the only party that knows what matters -- the crew -- had no way to influence it.

The fix splits the panel in two: a human-authored template and crew-published data. Only the data comes from the crew.

Records live in a gateway-only, sandbox-hidden subtree. This is the part worth reading closely, because two earlier placements were wrong and the reasons are the design. Storing under the crew's own member space failed because members/ is deliberately unfenced -- a crew owns its own published data -- so nothing stopped one crew writing another crew's panel.json directly, forging its state past both ownership resolution and the redactors in a single write. Moving to trust/ closed that route through the agent's file tools but not through a sandboxed shell, which can construct the path at runtime and so is never caught by command matching. The record now lives in a dedicated hidden leaf with a precreate disposition, so the directory exists before an agent can create it: a fence only fences a path that is there. All three write paths -- the MCP route, agent file tools, and a sandboxed shell -- are closed on the same location, and the module docstring records why each earlier placement was rejected so the next reader does not undo it.

Template selection needs no registry. A crew whose name matches an installed template gets that template; everything else gets default. No mapping table, no per-crew config, and a bespoke template activates by being installed. default renders any data object: scalars become a tile strip, sentences become their own section, arrays of objects become tables with derived headings, arrays of scalars become lists, objects become key/value blocks. Fields render in the order the crew published them, so a crew that puts its alert first gets it read first.

Rendering is bounded, not just the input. The data cap bounds what a crew can publish, but derived table headings take the union of keys across rows, so a payload well inside that cap could still expand to millions of cells and hang the browser. Rows and unique columns are capped independently, with an explicit truncation notice rather than a silent drop.

Two conventions come from the Issue Radar Pipeline dashboard, which solves the same legibility problem at a larger scale. A missing value renders as an explicit placeholder rather than vanishing, so "we do not know" is distinguishable from "none". And a <field>_note key renders as a caveat directly under the thing it qualifies, which is how a crew explains why a number does not reconcile.

Writes are MCP-only. A new opt-in server (kirocrew-panel) carries panel_publish and panel_templates, registered across every declaration surface the repo has -- the managed-server registries, the schema-posture view, the redaction sinks, the MCP call-site auth scan, the sandbox mask, the feature map, and the architecture specs -- and gated off for every agent by default. Neither tool takes a crew or session argument: the publishing crew is resolved from the vetted calling session through the shared strict-session gate, never from the request body, and never from the lenient resolver that would resolve a subagent to its parent's crew. The publish routes are strict-internal; the drawer's read route is cookie-authed and deliberately outside that prefix. The read route takes one snapshot and composes both halves from it, so the summary and the document can never disagree.

One shared theme reader. The webview frame is the seventh caller of the same theme-variable read. Rather than add a seventh local copy, widgetSrcdoc.readThemeVars becomes the single export and the other copies are deleted, mochi's included: its WidgetFrame now passes computed theme values through sanitizeCssValue like every other caller, which is the one behaviour change outside this feature's own surface. Section 5 has the detail.

The drawer has two states, and only one of them is a document. Docked is a native summary -- title, the crew's leading sentence, a few counters, and a labelled button. Expanded is the crew's document in a sandboxed frame. This is not cosmetic: a 250px column cannot host a dashboard, and trying put the most important line below the fold. It also means no document is minted until someone opens it, and the minted URL is single-use, so the frame is created on first expand and kept mounted across collapse.

Containment, stated precisely. The shared sandbox-document serve route sets one CSP header for every consumer and is unchanged here; it grants popups. What holds is that sandbox restrictions combine rather than union, so the frame's own sandbox="allow-scripts" is the binding constraint: no popups, a null origin, no cookies, no storage, no parent DOM, no top-level navigation. Egress is closed by the document's own CSP. Scripts do run, by design.

The sandbox is defence in depth, not the only defence. The untrusted half is data, not markup: it is escaped once in Python at a single boundary, redacted on the way into storage, and the template directory is read-only to the sandbox so an agent cannot author its own template. Templates reach the DOM only through text APIs, pinned by a test that greps the source for DOM sinks. The native docked summary renders crew strings as React text children, pinned by a test that a hostile string injects no element.

The sandbox dispositions are written down where the next reader looks. docs/system-specs/modules/security.md is the canonical registry of fenced leaves, and it now carries both of this change's: crew-panels/ as hidden and precreated, panel-templates/ as read-only and additionally write-protected rather than on the read-plus-write floor, so the operator who authored a template can still read it back while no agent can rewrite it. It also carries _CREW_NO_ALIAS_LEAVES, which refuses the spawn outright when either leaf is reachable under a second name, and why that differs from every other leaf's warn-and-continue: neither is a config file anyone has a reason to symlink, and a warning is what let the log claim a path was sealed while the writes went elsewhere.

The failure band and the empty state were rewritten after UX review. The expanded view's failure banner used to be one string in two states, laid over the frame as an absolute overlay: when a later mint failed while a document was still on screen, the reader was told the dashboard "could not be rendered" while looking at a rendered one, with the banner covering that document's own freshness line. There are now two strings -- a refresh failure names itself as one and says the last loaded version is showing -- and the band stacks between the Contained bar and the frame, so the document keeps every pixel. The empty state, which is the first state every operator meets while the server ships off, now states the task instead of naming a settings surface to go hunting for, and carries a control that opens the crew manager on that member through the page's own draft guard. Both are pinned, and both pins were mutation-checked: restoring the overlay, collapsing the two strings back into one, and suppressing the control each redden exactly the assertion that guards them. The copy also stops calling one thing by two names -- "member", matching the sibling copy in the same drawer, not "crew".

4. What tests we did

  • Store behaviour: caps, locking, ownership refusal inside the exclusive lock (not before it), the escaping boundary against hostile payloads, and published field order.
  • Route behaviour: publish identity resolved from the vetted session and never from the body, the strict-internal split, and the single-snapshot read.
  • Server behaviour: the two tools' runtime paths, the strict-session gate refusing a caller it must refuse, and the redaction of refusal prose -- the reasoning that justifies this module's redaction classification, so it is tested rather than asserted.
  • Frontend containment: the exact sandbox grants, the three never-conflated states, the expanded dialog's focus handling in both directions, and a hostile crew string rendering as text.
  • Declaration completeness: a test asserts the derived property -- every schema registry appears in the posture view, every fenced leaf has a sandbox disposition, and that disposition is not the writable one -- so the next managed server cannot repeat the omissions this change had to fix.
  • Mutation-verified the load-bearing tests rather than trusting green: disabling the template name-match, unmounting the frame on collapse, and putting raw HTML into the summary title each redden exactly the test that guards them.
  • Verified in a real browser, since the single-use minted URL is not something a unit test can prove: zero mints before the first expand, exactly one at first expand, and still one after expand, collapse and expand again, with the document still rendering.
  • The full backend suite was run sharded on this branch and on an untouched base, and the failure sets are identical -- the host-environment class that fails on both, with none unique to this branch.

5. Any other suggestions

  • This PR ships no consumer. The server is gated off for every agent, so every crew shows the empty state until one publishes. That is deliberate -- the mechanism should be reviewable on its own terms rather than alongside a specific crew's dashboard semantics -- but it does mean nothing exercises it end to end until the first consumer lands, which is the immediate follow-up. A reviewer is right to want that confirmed as imminent.
  • readThemeVars was duplicated seven times; this change extracts one shared export and deletes all seven local copies. That is scope beyond the feature, taken because a duplication that is merely disclosed is still a duplication. It carries one behaviour change that the earlier wording of this section did not name: mochi's WidgetFrame had the one local copy that read getPropertyValue(name).trim() raw, with no sanitizeCssValue and no SSR guard, so moving it onto the shared reader means that frame now sanitizes theme values it previously interpolated unchecked. Strictly safer, but a change to a surface this feature does not otherwise touch, and a reviewer is right to want it stated rather than inferred from the diff.
  • There is a genuine latent import cycle between the validation and artifact layers reachable through the members module. This change works around it by mirroring two constants locally with an anti-drift test rather than importing that module at scope. The cycle itself is untouched and will bite the next module that needs it early.
  • Review media is attached to the PR, not committed. An earlier revision of this branch committed the screenshots under temp-screenshots/, which .gitignore excludes precisely because review evidence belongs on the pull request; docs/ci/ci-and-reviews.md says the same. The files are now GitHub attachments and the directory is gone from the commit, so the images above no longer depend on repository history.
  • "Readable at a glance" depends on the crew publishing at least one sentence-length field. A crew that publishes only numbers gets a title, counters and a button, with no leading line to orient the reader.
  • The empty state hands off to Edit member by that page's own title, and the kirocrew-panel server row there does not yet say it is what enables this drawer's dashboard. That cue belongs to the crew manager's copy and is a follow-up on that page, not a change to this drawer.

@chenmingwei23
chenmingwei23 requested review from a team and dwu96 September 4, 2026 14:27
@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 4, 2026
@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Verify the first consumer PR is queued: until it lands, every drawer shows the empty state and nothing exercises publish-to-render end to end.

[DESIGN-REVIEWED] 6c636a3

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

"Published 3d ago" renders over a blank frame in the first-mint-failure state — the blind reader "cannot tell what was published or where it went."

Watch

  • First-mint failure (shot-08): the expanded bar's chip ({ago && ...} renders whenever meta.published_at exists, CrewWebview.tsx:697) dates a record the user has never seen, beside "could not be rendered" and an empty frame — reads as a contradiction. Rare state × confusion × every occurrence. Fix: suppress or relabel the chip when failed && !url.
  • Empty state (shot-03) is the first state every operator meets (the PR ships no consumer), and the reader was "hesitant — 'Edit member' sounds like changing settings… I'd rather not poke at settings by accident" about its only control. Correct reading, but hesitancy sits on the sole path to the feature's value. Consider naming the outcome ("Set up its dashboard in Edit member") over the destination.
  • "Ask the agent" (shots 04/07/08/09): reader across four states — "does it open a chat, send a message automatically, or try to fix the problem itself? I would not click it first." Shared ErrorNotice askAgent affordance, so the fix is upstream, but this PR quadruples its exposure on one surface; a human should weigh whether the link needs to state its effect.

[UX-REVIEWED] 6c636a3

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 6c636a3641bb9e23cec4c48950f268eb276e3f39 — 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

Template discovery and selection machinery ships against exactly one installed template — the bespoke-template path it exists for has zero instances yet.

Not justified as shipped

  • Item 5 — one consumer, generalized: panel_templates (tool + route), template_for_crew name-matching, and the template publish field all select among installed templates, but agent_panel_templates/ ships 1 file (default.html) and 0 bespoke templates (counted via glob); the description's "the conductor is the first consumer, not the schema" concedes the consumer is future.
    Subtraction: defer the panel_templates tool, template_for_crew, and the template schema field; publish always renders default, whose operator override still works through resolve_template's two-root lookup.
    Clears when: a bespoke template lands in-tree (the conductor's, per the description), or a counted operator-installed template consumer is named.

What this change ships

Inventory (10 items) — 9 justified

Intent: let an operator see a long-running crew's self-reported state in the drawer they already watch, without a per-crew frontend release — an ADDITION.

  1. Dashboard section in each member's drawer: docked summary with title, lead line, stats, plus empty/loading/error states — justified
  2. Expand to full window: sandboxed iframe document; collapse keeps the frame; aged-band and "new version" chip on failed refresh — justified
  3. New opt-in MCP server kirocrew-panel (panel_publish, panel_templates), off for every agent by default — justified
  4. New HTTP surface: strict-internal publish/templates routes, cookie-authed panel read, panel_published WebSocket push — justified
  5. Template selection: shipped default, operator override dir, crew-name matching, template field — one consumer, generalized (1 shipped template, 0 bespoke)
  6. crew-panels hidden + panel-templates read-only/write-protected store dispositions, precreated — justified
  7. A symlinked panel leaf now refuses the sandbox spawn instead of warning — justified
  8. One shared readThemeVars; five local copies deleted; mochi's frame now sanitizes theme CSS — justified
  9. _deferred route binder generalizing the session-control-only closure (two consumers) — justified
  10. Panel strings in 14 locales plus the app-sdk scope hint for panel_published — justified

[FIRST-PRINCIPLES-REVIEWED] 6c636a3

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings (all downgraded on adjudication)

GPT 5.6 flagged blocking issues on 6c636a3641bb9e23cec4c48950f268eb276e3f39; Opus 4.8 adjudication downgraded every one of them to advisory. Adjudication downgraded all 1 blocking finding(s) to advisory: the remedy each one requires is disproportionate to the harm it prevents. Read them as advice, not as merge conditions.

This comment is updated in place on each push.

Review details

BLOCKING -- src/kiro_crew/dashboard/handlers/agent_panel.py:424 -- valid crew names cannot read their published webview
if not member or not _AGENT_NAME_RE.match(member):
Crew named On call -> successful panel publish -> panel GET returns 400.
Anchor: feature-map-correctness
Fix: Require a non-empty member; rely on the stored crew-key ownership check.
[GPT-REVIEWED] 6c636a3
[BLOCK-MERGE-DOWNGRADED] 6c636a3

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

Harm rung: LOW. Conditions: read rejects any member outside _AGENT_NAME_RE (agent_panel.py:424), while publish only requires a non-empty crew name (agent_panel.py:775) — so a space-bearing name like "On call" can be stored. But the entire members subsystem already excludes such names: api_members skips every roster entry failing the same regex (members.py:205, members.py:117), and the sibling api_member_activity/api_member_rules routes apply the identical guard (members.py:752, members.py:845). Recovery: visible 400 that a crew rename clears; and such a crew never appears in the drawer roster to begin with, so no UI path reaches the failing GET. The proposed fix (drop the regex, lean on the crew-key ownership compare at agent_panel.py:446) is cheap — but the harm it prevents is a visible, self-evident 400 for names the members UI already can't surface. Blocking on this is disproportionate to a LOW, recoverable, near-unreachable degradation.

[ADJUDICATION] 6c636a3 total=1 uphold=0 downgrade=1
DOWNGRADE F1 src/kiro_crew/dashboard/handlers/agent_panel.py:424 reason=disproportionate-remedy
[GPT-ADJUDICATED] 6c636a3

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

@github-actions

github-actions Bot commented Sep 4, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6c636a3

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

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

@chenmingwei23 chenmingwei23 changed the title Give every crew a configurable webview in its drawer feat(members): give every crew a configurable webview in its drawer Sep 4, 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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 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: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 4, 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 4, 2026
@github-actions github-actions Bot added 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: checking Automated validation is still running labels Sep 4, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 55b309520606991d3d5dc4a17aea65d33c2adb48; 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 55b309520606991d3d5dc4a17aea65d33c2adb48: <one-sentence reason>

@chenmingwei23

chenmingwei23 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor Author
  • fixed span=7c4dbfb0006b -- test/test_sandbox_absent_ceiling_seal.py: the launcher-disposition ratchet no longer verifies readonly leaves

The finding holds: widening set(created) <= readonly into created - readonly - masked == {} plus a hidden-leaf loop dropped the positive binding for read-only leaves, so a precreated read-only ceiling relisted into SENSITIVE_DIRS would have passed.
Fixed in a3fed8361f: a symmetric loop derived from _CREW_PRECREATE_READONLY_DIR_LEAVES + _CREW_PRECREATE_READONLY_FILE_LEAVES asserts every created read-only leaf is in READONLY_DIRS and not in SENSITIVE_DIRS; the hidden-leaf loop and the final unaccounted check are unchanged. Mutation-verified: relisting computer_use.json as hidden fails the new assertion (computer_use.json is created to be read-only but is not in READONLY_DIRS).

@chenmingwei23

chenmingwei23 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor Author
  • rebutted span=d376e6f4be5f -- src/kiro_crew/dashboard/server.py: cold route imports block the event loop

The mechanism is real but bounded: import_module runs once per process on the first request to an optional route, sys.modules makes every later call a dict lookup, and the import is a sub-second one-off on a panel most installs never open. The adjudicator downgraded it for the same reason (disproportionate remedy).
The shape is not new to this PR: _deferred generalizes main's existing _deferred_session_control, which has bound the five session-control routes with the identical first-request import since it landed, deliberately, because the boot-path rule moves an optional subsystem's import off boot rather than onto a worker thread. A to_thread import would add thread-pooled import-lock semantics for a one-time millisecond stall, so the code stays as is.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=80721f21d331 -- src/kiro_crew/dashboard/handlers/agent_panel.py: the read route's _AGENT_NAME_RE pre-filter on member

The route-level asymmetry is real (create validates a crew name only for credential shape; the panel read applies the agent-name grammar), but the stated symptom is not reachable: api_members (handlers/members.py:205) skips every roster entry whose name fails _AGENT_NAME_RE, so a crew named On call never appears in the Crew Members page and CrewWebview is never mounted for it. client.ts memberPanel is the read route's only caller, and it is reached only from that drawer.
The check is also the shared shape, not a local invention: api_member_activity, api_member_rules_get and api_member_rules_put (members.py:752, :845, :939) apply the identical member pre-filter on main. Dropping it on one route would make the panel read the single member endpoint that accepts what its siblings refuse, and would rewrite a pinned refuse-hostile-input test into accept-and-ignore for a symptom nobody can trigger today.
The right fix is one decision across the roster filter and all four member routes, which is outside this PR. A verified patch for the panel route (fix plus regression tests, mutation-checked: restoring the grammar fails both new tests with the missing_member 400) is kept locally and will be filed with the follow-up issue when the roster filter is revisited.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=36a32149e151 -- empty-state hand-off reads as possibly costly and lands on the generic editor with no cue

Fixed in 02c62bf139: the button now reads "Open Edit member to set it up" (all 13 catalogs, each reusing its own existing edit_member wording). "Open" makes the click legibly a navigation rather than a job launch, and the label names the destination by the title the members page already uses for it, so the reader arrives where the button said they would. Shorter than the previous label, so the empty-state row keeps its measured height.
Not changed: a panel-specific anchor inside the crew editor. The enabling control is the kirocrew-panel server row under Tools & MCP, which is that page's existing surface; adding a dashboard cue there is a change to the editor, not to this feature, and is left for the editor's own review.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=0152b6fcdcc5 -- failed-refresh expanded view shows two ages with nothing tying them

Fixed in 02c62bf139: while a refresh has failed and an older document is still on screen, the expanded Contained bar's chip reads "New version published {ago}" (new key webview_published_ago_newer, 13 catalogs plus a translator-context entry) instead of "Published {ago}", so the chip names the newer record and the band below keeps dating the version shown. The docked chip is unchanged: it has no second age to disagree with. Pinned in CrewWebviewContainment.test.tsx (reads both stems from the catalog); mutation-verified by forcing the plain label, which fails the pin.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=68076e17d6aa -- the default template is unexercised until the first consumer publishes

The premise is stated by the PR itself and is the intended shipping order: the write path (panel_publish, redaction, caps) and the render path (default template, containment) have to exist before any crew can publish, and the first publisher is the crew conductor's own status panel, which follows this PR rather than preceding it. What this PR ships is validated where a consumer cannot help: the publish route's schema, cap and redaction tests, the renderer's shape inference tests over scalars, arrays and nested objects, and the containment tests on the composed document. A shape mismatch found by the first real publisher is a template change, not a contract change, because the default template infers presentation from the data shape rather than requiring a field list.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=576f7c6c62ed -- the readThemeVars consolidation changes mochi's WidgetFrame behaviour inside a feature PR

The consolidation is a prerequisite, not a ride-along: the crew webview is the seventh caller of the same theme-variable read, and adding a seventh local copy would have shipped the exact unsanitised pattern mochi's copy carried. Every caller now goes through widgetSrcdoc.readThemeVars, which passes each value through sanitizeCssValue; the only behaviour that changes for mochi is that a theme value which is not a valid CSS value is dropped instead of being interpolated raw into a style block, and a valid value is byte-identical. Mochi's own tests (mochiWidgetFramePromotion, mochiPetEvents) and WidgetFrame.cov80 run in this PR's frontend suite and pass on this head. Splitting it out would leave two PRs each half-correct until both land.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=33a9893f1145 -- reserve a version/kind discriminator in the publish body now

The publish body is validated by PANEL_PUBLISH_SCHEMA and the stored record is written and read by one process, the gateway, at one version: the MCP server posts to the gateway's route, the dashboard reads from it, and no out-of-process reader exists. A discriminator with a single writer and a single reader is a field nobody consults. When the first independent reader appears, adding version is a compatible change on this side of the contract, because a reader treats absence as the pre-version shape; the record's byte ceiling already leaves room for it. Reserving it now would fix a number that nothing yet compares against.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=71be67335827 -- the template picker (panel_templates, the template argument, crew-name matching) ships with one template

The selection mechanism already has a consumer that is not a second file in agent_panel_templates/: the operator override directory (panel-templates/, sealed read-only to agents and write-protected from agent tools) is documented as the way an operator restyles or adds a template, and the ONLY way an operator's file is ever chosen is the name-match resolver plus the template argument. Removing the picker would leave the override directory reachable by nothing, so the two ship together or not at all. panel_templates is the discoverability half of that seam: without it a crew cannot learn which ids the operator installed, so the template argument would be usable only by reading the operator's disk. Zero shipped templates beyond default is the intended starting state for a per-install customization point, not evidence the point is unused.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=e55703dc1dd3 -- "New version published {ago}" fired on failed && url alone, not on the record being newer

Fixed in fe3aa7716b: the chip now keys on the record being NEWER than the document on screen (meta.published_at later than shown.at, compared as instants), not on the failed flag. A theme change that re-mints the same record keeps the plain "Published {ago}" label, so the bar and the band agree on one age; "New version published" fires only when a republished record's mint failed over an older document, which is the one state where two versions exist.
Pins: the same-record test now asserts the plain label and rejects the newer stem (mutation-verified: restoring failed && url fails it), and the republished-record test asserts the newer stem carrying the new record's age and not the shown one's. Shot 07 was re-captured under the new rule (chip "Published 3d ago" above "Showing the version from 3d ago") and its capture script asserts the plain label for the same-record case, so the old behaviour cannot pass the harness again.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=c396ef9f423a -- "Open Edit member to set it up" should lead with the outcome rather than the surface

Not changed. The reader's own result was "a correct read"; the worry attached to it ("changing something I don't understand") is about the destination page, not the label. The outcome already leads this state: the heading "Dashboard" and the sentence "This member has not published a dashboard yet." sit directly above the button (shot 03), so the row reads outcome first, destination second. A label that leads with the outcome ("Set up its dashboard...") still has to name the destination, or the reader lands somewhere the button did not announce, which is what the first round flagged.
The current label reuses each locale's existing edit_member title across 13 catalogs. A third rewording of this one string in three rounds trades a stable, already-translated navigation label for a wording preference. Kept as is; a panel-specific cue inside the crew editor stays with that page's own review, as recorded on the earlier fixed disposition.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=0a927db4135f -- webview_heading "Dashboard" reads as one word for two things; rename to "Member dashboard"

Not changed. The heading sits inside a member's own drawer, under that member's name, where every heading describes that member; "Member dashboard" would repeat the drawer's subject on a row whose siblings do not. The two meanings the reader named (the panel vs the thing the member publishes) are one thing on this surface: the panel IS the published document, docked or expanded, and the empty state says so in its sentence ("has not published a dashboard yet"). Renaming touches 13 catalogs for a word the surrounding drawer already disambiguates. Noted for the members page's next copy pass rather than this PR.

A crew that runs unattended accumulates the state an operator actually wants:
how many workers it is holding, which one is stuck, what it is waiting on. The
drawer showed activity counts, a path list and config instead, none of which
answer those. This adds a free-form HTML webview that the crew fills in at
runtime.

The split that makes free-form HTML safe: a human authors the TEMPLATE --
versioned in the repository, or dropped on disk by the operator -- and the crew
publishes only DATA. The template directory is fenced from agent file tools, so
a crew cannot author its own markup; the only way it influences its webview is
by publishing a data object. The data lands as an inert application/json island,
escaped so a published string cannot close the script element early, and a
template reads it with JSON.parse and renders through textContent only. The
composed document is served behind a single-use minted URL into an iframe
sandboxed to allow-scripts and nothing else.

A crew whose name matches an installed template gets that template; a crew with
no template of its own falls back to a generic one that renders any data object.
That is the entire wiring mechanism -- installing <crew-name>.html is the act of
wiring a bespoke view up, so there is no registry, no mapping table and no
per-crew config to keep in sync.

The MCP server ships registered but gated off for every agent (opt_in), so a
default session pays nothing for the capability: not a tool-list entry, not a
line of context, not a spawned backend. An agent that should publish a panel is
granted the set in its own spec, and a refresh keeps an existing grant current
without ever minting one.

The publishing crew is derived from the vetted calling session and never from the
request body, so one crew cannot publish a webview that presents as another's. A
body field naming a crew is rejected by the schema rather than ignored, so a
caller is never left believing it retargeted the write. The drawer's read at GET
/api/members/{slug}/panel is cookie-authed; the /api/agent-panel writes sit
behind the MCP-only prefix.

Published field order is preserved end to end. Field order is presentation -- a
template renders a stat strip in key order -- so the record is dumped without
sorting keys instead of silently alphabetising the operator's dashboard.
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=e7e11808ea56 -- override_templates_dir() is evaluated outside the per-root try, so an aliased override directory fails every template read instead of falling back to the shipped directory

The mechanism is as described; the fall-through remedy contradicts a contract this PR pins on purpose. test_a_linked_template_dir_is_a_coded_refusal_not_a_500 (routes) asserts that with the override name symlinked elsewhere, GET /api/agent-panel/templates and a publish both answer 400 panel_dir_is_a_symlink: a linked override directory is a coded refusal the operator sees, not a directory that is quietly ignored while the shipped default renders in place of the template they installed. Falling back to the shipped root would invert that test and remove the only signal that the override is being refused. What the finding gets right is the read path's blast radius, and that half is fixed on this head by the GPT disposition: a refused directory no longer blanks every drawer silently; it answers 503 panel_render_failed, which the drawer shows as a retryable error with the agent hand-off, until the operator removes the link. The available_templates docstring sentence the finding relied on ("an unreadable directory yields what the other one has") described the OSError branch inside the loop, not the alias refusal; in head 6c636a3 it states the refusal and names the pinning test. No code path changed.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=20dbbfd3f3e4 -- render failures are treated as unpublished panels

Real and introduced by this PR. render_record swallowed PanelError, TypeError and ValueError and returned None, so a published record whose template failed to compose answered 200 {"panel": null, "html": null}, the same body as a crew that never published, and the drawer showed the empty state for a broken dashboard. In head 6c636a3 the store's render_record propagates composition failures; the handler's single-snapshot read catches them after the ownership check and answers 503 {"error": "could not render the panel", "code": "panel_render_failed"}, matching the write path's 503 and giving the drawer its retryable error state. An absent record still answers 200 with the empty body, and the 503 body carries no template text and no path. Pinned by test_a_broken_published_template_returns_retryable_error (routes) and test_render_raises_when_the_template_disappears (store); restoring the swallow reddens the route test on assert 200 == 503.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=20ba8ba22f44 -- nothing exercises the webview end to end until the first consumer lands, and every drawer shows the empty state meanwhile

Same disposition as span 68076e17d6aa on head a3fed83 (comment 5759911276), restated for this head. The shipping order is deliberate and stated in the description: the write path and the render path have to exist before any crew can publish, and the first publisher is the crew conductor's own status panel, which follows this PR. What a consumer cannot help validate is validated without one: the publish route's schema, cap and redaction tests, the renderer's shape-inference tests over scalars, arrays and nested objects, the containment tests on the composed document, and the capture harness that drives the drawer through every state shown in the description. The empty state is a designed state with its own copy and hand-off, not a placeholder. Gating the drawer section on the kirocrew-panel server being assigned would hide the one screen that tells an operator the feature exists and where it is turned on, which is the first-run problem the UX lane is working on from the other side.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=10a0f1730628 -- one consumer, generalized: agent_panel_templates/ ships only default.html and nothing outside the module passes a non-default template

Same disposition as span 71be67335827 on head a3fed83 (comment 5760012762), restated for this head. The selection mechanism already has a consumer that is not a second file in agent_panel_templates/: the operator override directory (panel-templates/, sealed read-only to agents and write-protected from agent tools) is the documented way an operator restyles or adds a template, and the only way an operator's file is ever chosen is the name-match resolver plus the template argument. Deleting the argument and panel_templates would leave that directory reachable by nothing, so the two ship together or not at all; panel_templates is the discoverability half of the seam, the way a crew learns which ids resolve. The clearing condition asks for a shipped consumer of a non-default template; that consumer is the operator, whose installed file is selected by exactly this argument, and the routes tests exercise that path with a non-default id.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • fixed span=6dda00da8718 -- item 9, undeclared: the seven-copy readThemeVars consolidation appears nowhere in the description's visible half

Correct as stated: it was named only in section 5. Section 3 of the description now carries a paragraph ("One shared theme reader") declaring the consolidation, the deletion of the seven local copies, and the one behaviour change outside this feature's surface (mochi's WidgetFrame now sanitizes computed theme values), with section 5 keeping the measured detail. Description-only change, made before head 6c636a3 was pushed so the lane judging that head reads it.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=b190c3da08c0 -- move the seven-site readThemeVars dedup, including mochi's sanitizeCssValue behaviour change, to its own PR

Same disposition as span 576f7c6c62ed (comments 5760012226 and 5747493249), restated for this head. The consolidation is a prerequisite, not a ride-along: the webview frame is the seventh caller of the same theme-variable read, and a seventh local copy would have shipped the exact unsanitised pattern mochi's copy carried. The behaviour change is measured rather than argued: the shared reader covers 21 colour variables, and every declared value of those names in the stylesheets (256 declarations) passes the sanitizer, so no rendered value changes on mochi or anywhere else; an invalid CSS value is dropped instead of being interpolated raw. On the revert story: reverting this PR returns mochi to the local copy main carries today, so it opens nothing main does not already have; an independent revert would only buy the ability to keep the sanitizer while removing the webview, a combination nothing needs. The consolidation is now also declared in section 3 of the description, where the First-Principles lane asked for it.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=4a4aba665026 -- the docked "Contained" chip carries no explanation; the claim lives only in title/aria-label, so a sighted touch user gets the bare word

Not changed. The chip is a compact status badge on a 250px column that has no room for the sentence, and the full claim is one tap away: expanding the card shows the same bar with the sentence printed in full ("filled in by this member, isolated from this page and blocked from sending data out", shots 07 to 09). Both surfaces render the same string from one key, so they cannot drift into claiming different things, and the docked chip's hover text and accessible name are that same sentence, which covers mouse, keyboard and screen-reader users. The sighted touch user the finding names is the one reader who has to expand to read it, and expanding is the drawer's primary action rather than a hidden one. A second visible clause in the docked bar would compete for the one line that also holds the published-age label the previous round asked for.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=b7512024d73d -- the empty-state flow loses scent at its destination: Edit member never says "dashboard", and the enabling control is an MCP server row named kirocrew-panel

Agreed on the fact, declined on the location. The scent is lost on the Edit member page, whose kirocrew-panel row does not say what it enables; that copy belongs to the crew manager, which this diff does not touch, and it is now recorded as a follow-up in section 5 of the description. Naming the row from inside the drawer would couple the drawer's copy, across 13 catalogs, to a server identifier and to the crew manager's current layout, and it would go stale the day that page gains the cue it should carry. The drawer hands off by the destination page's own title, which is the stable, already-translated half of the path.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=b8080ac0fdf6 -- webview_setup "Open Edit member to set it up" was rated a guess; "Set up the dashboard in Edit member" would front-load the outcome

Same disposition as span c396ef9f423a on head 26d9ac3 (comment 5760480321), restated for this head. The outcome already leads the row: the heading "Dashboard" and the sentence "This member has not published a dashboard yet." sit directly above the button (shot 03), so the state reads outcome first, destination second, and the button's one job is to name where it goes. The label reuses each locale's existing edit_member title across 13 catalogs; a fourth rewording of this one string trades a stable, already-translated navigation label for a wording preference. Kept as is.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=49084f99c748 -- first-mint failure (shot 08): the expanded bar's "Published {ago}" chip dates a record the reader has never seen, beside "could not be rendered" and an empty frame

Not changed. The chip dates the published record, and the reader has seen that record: the docked card they expanded from renders its title, leading sentence and counters under the same "Published {ago}" chip (shot 01). What failed is rendering this version as a document, which is what the band says; "published" and "could not be rendered" are two facts about two things, the same split shot 09's caption spells out for the newer-version case. Suppressing or relabelling the chip only in this state would make the docked card and the expanded bar disagree about the age, which is the drift an earlier UX round asked us to remove by keeping one label form on both surfaces. The one deliberate exception already exists where a second age can disagree (a failed refresh over an older document); here there is one age and it is the true one.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=ad202beb8d07 -- valid crew names cannot read their published webview

Same finding as the Opus member-grammar item on head a3fed83 (comment 5759385867), and this head's adjudication reached the same conclusion (LOW, recoverable, near-unreachable). The mechanism is confirmed: the read checks member against _AGENT_NAME_RE while publish accepts any non-empty crew name, so a crew named "On call" can publish and then read a 400. Why the code stays: the members roster (api_members, members.py:205) hides every roster entry that fails the same regex, so the drawer never mounts for such a crew and no UI path reaches the failing GET; and the sibling member routes (api_member_activity, api_member_rules) apply the identical guard, so this route matches its siblings rather than diverging from them. The proposed remedy (drop the regex here and lean on the ownership compare) would make this one route accept names the roster and its three siblings reject, and would rewrite a pinned hostile-slug test inside a feature PR. The right change is one decision for the roster and all four routes together, which is a follow-up outside this PR.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=475335443d45 -- item 5, one consumer generalized: panel_templates, template_for_crew name-matching and the template publish field select among installed templates while only default.html ships

Same disposition as spans 71be67335827 and 10a0f1730628 (comments 5760012762 and 5761301362), restated for this head. The counted consumer the clearing condition asks for is the operator: the override directory (panel-templates/, sealed read-only to agents and write-protected from agent tools) is the documented way an operator installs or restyles a template, and the only way an operator's file is ever chosen is the name-match resolver plus the template argument, with panel_templates as the discoverability half of that seam. Deleting the three surfaces would leave the override directory reachable by nothing, so they ship together or not at all. The bespoke in-tree template named in the description (the crew conductor's) follows this PR by design, for the reasons given on the no-consumer disposition (comment 5761298943).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=252e799ab23a -- "Ask the agent" (shots 04, 07, 08, 09): the reader could not tell whether the link opens a chat, sends a message, or tries to fix the problem itself

Not changed here, by the finding's own analysis: the affordance is the shared ErrorNotice hand-off used by every error notice in the product, and this PR uses the repository's standard notice instead of inventing a variant, which is what keeps the drawer's four failure states consistent with every other surface's. Restating the link's effect is a change to that shared component and its copy across every consumer, an upstream decision this PR should not make on one surface. The exposure argument cuts the other way: four states on one surface all showing the same standard control is the consistency the shared component exists for. Flagged to the maintainers as a product question about the shared notice, separate from this PR.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • rebutted span=7a9246dc2d38 -- empty state (shot 03): the reader was hesitant because "Edit member" sounds like changing settings; consider naming the outcome over the destination

Same disposition as spans c396ef9f423a and b8080ac0fdf6 (comments 5760480321 and 5761304021), restated for this head. The reader's own result is again "correct reading". The outcome already leads the row: the heading "Dashboard" and the sentence "This member has not published a dashboard yet." sit directly above the button, so the state reads outcome first, destination second, and the button's one job is to say where it goes. Setting up the dashboard IS a change to that member's settings (enabling a server for it), so a label that avoided the word would be less true, not more inviting. The label reuses each locale's existing edit_member title across 13 catalogs; this is the fourth wording round on the same string, and the cue the reader actually needs belongs on the destination page, recorded as a follow-up in section 5 of the description (comment 5761304012).

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

Re-verified at 6c636a36 after the force-push dismissed my earlier review. Went at the five load-bearing surfaces first rather than the whole 20-file diff.

sandbox.py — every hunk tightens, nothing widens. crew-panels joins _CREW_HIDDEN_LEAVES and the hidden-dir precreate set; panel-templates joins _CREW_READONLY_LEAVES and the readonly precreate set; the new _CREW_NO_ALIAS_LEAVES + _refuse_if_aliased_protected_leaf turns an aliased protected leaf from warn-and-continue into a hard spawn refusal (:1587, :1677, :2032). The one behaviour change — _sealable_absent_ceilings materializing hidden leaves too — is required, since an absent dir gives the bind-mask no target on a fresh install. No seal, mask, or no-follow pin is relaxed.

Publish surface is strict-internal and the crew is never taken from the body: request["internal_auth"] (constant-time secret), then awaited _deny_app_caller before slot.agent is read, then _recognize_session, then restricted-session refusal; the crew comes from the vetted session's get_agent_selection and only when namespace is member (_resolve_publishing_crew). Prefix is in server._STRICT_INTERNAL_API_PATHS (server.py:493). Read route is cookie-authed, requires an exact member param matched against the stored ownership digest, and fails closed on an unowned record.

No arbitrary-path serving: template ids go through TEMPLATE_ID_RE (^[a-z0-9-]{1,64}$, no separators) plus a second is_relative_to(root) symlink check (agent_panel.py:400); the record path is slug-validated, containment-checked and link-refused. Untrusted data is escaped once at a single boundary into an inert application/json island and rendered through DOM text APIs; the iframe is sandbox="allow-scripts" only — null origin, no same-origin, no popups — with egress closed by the CSP buildSrcdoc injects. Publish-time credential/exfil scrubbing covers keys as well as values.

panel_published is declared to the "panels" scope (not Tier-0) and carries {slug} only, deliberately withholding the ownership digest, so a client acting on it must re-read through the ownership-checked route. Same shape as artifact_update.

Packaging is right: agent_panel_templates/*.html is in both MANIFEST.in (sdist) and setup.cfg package_data (wheel), so the template ships on pip and DMG rather than the feature arriving broken.

MCP registration is mount-not-approve: kirocrew-panel is opt_in=True, in OPT_IN_BIN_MCP_SERVERS rather than ALWAYS_ON, and carries no autoApprove key, so calls reach hooks.on_tool_call and stay subject to trust mode. Publish identity requires require_strict_session_key, so a subagent is refused.

One imprecision, not worth a revision: _refuse_if_aliased_protected_leaf's docstring says it detects "a regular file with an extra hardlink," but the implementation refuses any non-directory/non-symlink entry and never reads st_nlink. The behaviour is stricter than the prose, so the effect is safe — only the sentence is wrong.

The "ships no consumer yet" note from Design/First Principles is real and acknowledged; the feature is opt-in and off by default, so it is a scope judgment rather than a defect. GPT's "valid crew names cannot read their panel" does not hold — crew_key digests the raw name before redaction/clamp (agent_panel.py:663), so a credential-shaped name still matches itself.

Did not line-read the ~15 locale JSONs, the website/capture/* harnesses, or onboarding_import.py.

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.

4 participants