Skip to content

feat(dashboard): host an agent-written dashboard page and let it subscribe - #19060

Merged
chenmingwei23 merged 2 commits into
feat/18642-tree-foldfrom
feat/18642-page-host
Oct 11, 2026
Merged

chenmingwei23 merged 2 commits into
feat/18642-tree-foldfrom
feat/18642-page-host

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a crewmate's dashboard can be a page its owner wrote, which redraws itself when a value moves, instead of a layout assembled from host-drawn blocks.

A kind="dashboard" package can only describe its page as view.blocks -- a list of block types out of a closed catalog that host code draws. The pages this surface exists for are not in that catalog and never will be: a dispatch tree, a chart over a fold, a scene. A catalog that grew a type per picture would be the host writing every page anyway.

A page also has no way to HEAR a change. A value reaches it either as a text binding the host fills or through window.kirocrew.fields, a snapshot read once. The only signal of a refill is a generic event that says something landed, leaving the page to diff a whole read.

Why it matters

The dashboard is where a person reads what a long-running crew is doing. A page that cannot draw the shape of the work -- who dispatched whom, what is blocked on what -- answers the question with a table of numbers instead of the picture. And a page that cannot tell which field moved either redraws everything on every push or polls, so the surface that exists to show live progress is the one that shows it late.

Not a goal

What changed (motivation -> approach -> change)

Goal: let the owner write the page, and let the page hear what moved. dashboard_frame already composes a page it did not write -- text-only bindings, connect-src 'none', allow-scripts over an opaque origin -- but had no way to tell the page's script that one field moved.

  • view.html in the package: either html or blocks, never both nor neither. Checked for the frame's own refusals and for bindings naming an undeclared field. Nothing looks for a dangerous construct -- containment is the CSP and the sandbox.
  • window.kirocrew.subscribe(name, cb), firing at subscribe time and on every push carrying that field; returns a disposer.
  • The field push: LivePage resolves values through the manifest built from model.types, sends only fields that changed, steps a version by one per frame, and a page that cannot place a patch asks for a whole read. Frames and the refetch name their package, so two pages for one crewmate cannot cross-feed.
  • The route: GET /api/members/{slug}/dashboard resolves the crewmate's binding, serves the page, arms the live page. It is the production caller of read_tree_projection: a tree fold has no bus scope, so it is read on arm and on refetch.
  • The owner gate on all three artifact write paths: 403 when the caller is not the crewmate or session the bound_to names, and an app refused outright; the write then lands under the token of the snapshot the gate judged, so a rebind arriving in between is refused rather than overwritten.
  • One optional gallery page to copy -- nothing loads it by id, no route falls back to it -- the first consumer of feat(crew-log): register a tree fold under a third key kind, so a block can bind a tree #18777's worktree fold, plus the array and object data types worktree.boards needed.

A dated maintainer amendment in docs/request-for-change/rfc-crewmate-dynamic-dashboard.md supersedes the recorded P2 precondition: only the owner agent writes the page; values reach it as text, so crew-log content cannot add code or a URL; the frame carries only the model's allowlist; and that agent already reaches the network through its own tools. Sandbox stays allow-scripts, pinned by test.

Backwards compatibility

Compatible: view.blocks is unchanged and every stored package still parses -- view admits a second key and requires exactly one of the two. read_payload, compose and compose_body keep their signatures. The route is unchanged for a crewmate whose binding resolves to no package.

Breaking: an agent or app write to a kind="dashboard" artifact bound to a different crewmate or session is refused 403 where it previously stored. Writer sweep on origin/feat/18642-tree-fold @ 554cfb300c: the three paths in dashboard/handlers/artifacts.py are the only ones reaching ArtifactStore.create / .update with caller-supplied content, and all three are gated; dashboard_save does not exist on this base. git grep 'kind="dashboard"' finds only the store's rules, the validator and tests, so no cron script, app bundle or skill writes one today. The sweep covers the write arriving over the API; bytes put straight into the stored file are outside it and outside any check this handler could make, that writer being our own OS user -- named at the parse site, bounded by the frame's missing network.

Reader: handlers/member_dashboard.py:api_member_dashboard -- crew page -- serves a template instance unchanged when no package is bound -- test_member_dashboard_package_route.py
Reader: artifact_store/dashboard_package.py:validate_package -- agent write via MCP -- a block view validates identically -- test_dashboard_package_html_view.py
Reader: dashboard_feed.py:DashboardFeed.subscribe -- crew page -- gains an optional extra_folds, default empty -- test_dynamic_dashboard.py::TestTheFeed
Reader: handlers/artifacts.py three write paths -- agent and app via MCP -- a non-package write is untouched -- test_dashboard_package_owner_gate.py

Tests

Each red-first unless noted. The five security fixes are re-proven by breaking each guard and requiring its tests to fail: escaped kind 4, app token 2, live source 2, lost update 1, cross-feed 5 failed; baseline and restored 50 passed.

  • test_dashboard_frame_subscribe.py (31): the bootstrap is EXECUTED in Node; one case breaks it and requires the probe to report the silence.
  • test_member_dashboard_package_route.py (46): end to end over the real route, store, bus and broadcast -- the tree read, the gallery page's subscriber, and the resolver arming a page on an ordinary GET.
  • test_dashboard_gallery_real_tree.py (5): plants real work entries and folds with the real read_tree_projection, pinning the page's read keys and their types. Found items is an integer count, which three fixtures had got wrong.
  • Plus the owner-gate (39), html-view (20), field-push (20) and dashboardFields.test.ts (13) suites.

658 passed; vitest 15; every gate exits 0 (black, flake8, isort, mypy, comment-history, docs-lint, feature-map, tsc, gen:ui --check).

Manual verification

Captures come from the real composed output of render_package_page; each asserts the rows the page's script drew. One drives a single patch through a live page and fails unless the row count rises.

Screenshots / video

The dispatch-tree gallery page, one example an owner may copy: five boards mid-run -- who dispatched whom, each goal and item count.

the dispatch tree rendered in the Dashboard tab

The stale-values band, raised when a gap recovery never arrives, with its own sentence and a Retry -- distinct from the kept-last-good band, which says a newer version did not load.

the stale-values band above the page

Light theme, empty state and a cycle: screenshots/18642-host.

Related Issues

Refs #18642. First consumer of #18777 (the worktree tree fold), which this PR is stacked on.

Checklist

  • At most two commits, Conventional Commits title
  • Existing tests pass and new tests added
  • Self-review completed; follows project style
  • Documentation updated
  • No secrets, credentials or internal references in the diff

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 11, 2026
@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — 🟡 CONCERNS

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

UX-Verdict: CONCERNS

The dispatch-tree gallery page hides what its numbers mean: the right-hand counts have no label, and "on a cycle" / "unresolved" are unexplained jargon.

Watch

  • The count on each row has no label. The gallery page prints each board's items count as a bare number. The blind reader asked whether it meant "messages, steps or minutes?", and then noticed that "41 isn't the sum of the rows under it". Owners copy this page, so the gap spreads to every page built from it. Severity: medium, because every reader of every copied page hits it.
  • The summary line uses words a reader doesn't know. For "1 root, 0 on a cycle, 0 unresolved" the reader said "no idea what 'on a cycle' or 'unresolved' mean". The line is meant to say whether the tree is broken, and that message doesn't get through. Severity: medium for the same reason: always visible and copied.
  • The stale band doesn't mark which values are stale. The red band explains itself, but the reader said "nothing in the tree itself is greyed out… can't tell which values are stale" and "it doesn't say when the values stopped". The host knows when the last read arrived and can't touch the page's own drawing. Severity: low, since this only shows after a failed refetch.

Suggestions

  • In dispatch-tree/package.json, label the count ("41 items") or add a column header.
  • Replace "on a cycle" / "unresolved" with "0 looped, 0 with a missing parent", or add a tooltip on each term.
  • In the stale band, show when the last values arrived, e.g. dashboard_values_stale: "Live values stopped updating at {{time}}; showing the last ones received."

[UX-REVIEWED] ea2a76a

Description read

[DESCRIPTION-READ] 004c7f7155810cc57c5c757973fa149d2bd5d445a90068faf4f6cb1a3cb02d16

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

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

The amendment that lets agent-written script run unwrapped depends on "only the owner agent writes the page", but that holds only for writes through the artifact API.

Watch

  • Premise 1 is weaker than the amendment says.
    • Cause: the amendment says "Only the owner agent writes the page HTML. A worker cannot."
    • Mechanism: the residual comment in the patch concedes that "a write made straight into the stored file -- around the artifact API and so around the owner gate -- is not detectable". Any worker with a shell runs as that same OS user. That comment also says the page "runs with no network". But the amendment itself grants that "a closed connect-src does not stop a page from navigating itself", and that navigation is what the P2 wrapper withheld.
    • Consequence: a worker steered by untrusted content can still plant a script that navigates the frame, carrying the fields the owner's page was sent. The three-path gate and its token checks narrow the API route only, not the boundary the amendment says they close.
    • Clears when: the amendment and the residual comment state the shell-write path and the navigation it allows. The maintainer named in the amendment confirms they accept that residual (the amendment is dated today and written inside this PR), in a PR comment.

Suggestions

  • Keep the owner gate as one store-level check that receives the caller, instead of three handler copies each with its own snapshot, absent and unreadable branches. That removes the "whichever went unasked is the spelling a worker would use" class.

[DESIGN-REVIEWED] ea2a76a

Description read

[DESCRIPTION-READ] b47e15e79437beca3a6ab3b6e1129f3c871736781f87fc2838cfc34c056d3495

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

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ human override accepted

@chenmingwei23 overrode this lane for ea2a76afd6edc1ff699c9fcb6be8817691c70a52 via /ai-review override (this commit only).

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

I checked all five candidates against the code. Only candidate 2 survived, as an advisory finding: candidate 1 is blocked by the store, 3 can't show a wrong page in practice, 4 is a documented locking trade-off with no measured stall, and 5 has no input that makes arm fail.

No blocking findings.

FINDING — website/src/pages/members/CrewDynamicDashboard.tsx:265 — the push listener runs in useEffect(..., [slug]) and reads livePackage from its first render. That value is '' before the route answers, so if (livePackage && fromPackage && fromPackage !== livePackage) return never drops a frame. A page still armed under an earlier package keeps pushing to every tab for that crewmate: it stays armed until the 32-page cap evicts it, because a re-read only replaces the page under the same key. The frame's generation check refuses each of those patches but asks for a refetch every time, and on a template page that refetch is sent with dashboard='', gets back missing_dashboard, and shows the stale-values band → Fix: read livePackageRef.current inside the listener, and drop any frame whose fromPackage is not the tab's current package, including when that package is empty.

[OPUS-REVIEWED] ea2a76a

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

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

@github-actions

github-actions Bot commented Oct 11, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ea2a76afd6edc1ff699c9fcb6be8817691c70a52 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ea2a76a

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

@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 11, 2026
…cribe

A kind=dashboard package can now carry view.html -- one page its owner wrote --
beside the block list, exactly one of the two. The frame gains
window.kirocrew.subscribe(name, cb), which fires on first load and on every push
that carries the field, so a page that draws a tree or a scene redraws from the
field that moved rather than diffing a whole read.

subscribed_fields reads the push allowlist off the model, and the save gate
refuses a binding the model does not declare.
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 11, 2026
@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 Oct 11, 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 Oct 11, 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 Oct 11, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 11, 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 Oct 11, 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 Oct 11, 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 Oct 11, 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 readiness: checking Automated validation is still running labels Oct 11, 2026
…r only

The controller resolves every value through the manifest it builds from the
package model, so a field the model does not declare has no path to the page.
A frame carries the fields whose value differs from the last one sent, each
patch stepping a version by one; a page that cannot place one asks for a whole
read.

GET /api/members/{slug}/dashboard?dashboard=<slug> serves the page through the
frame and arms the live page. It is also the production caller of
read_tree_projection: a tree-keyed fold has no bus scope, so the controller
reads it on arm and on refetch and resolves its fields out of that read, which
is how the dispatch-tree page gets a fleet's shape. The fold event reaches the
owner's socket as a dashboard_fields frame and the tab posts it into the iframe.

Writing a package is refused unless the caller is the crewmate or session its
bound_to names, and the refusal says to work_report instead.
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

/ai-review override first-principles ea2a76a: Maintainer decision by Mingwei on 2026-10-11 (option c): owner-written dashboard pages render in the opaque sandbox with no navigation wrapper, recorded as the dated RFC amendment in this PR that supersedes precondition P2; only the owner agent writes the page, pushed values are text-only, and the frame holds only the subscribed fields.

@github-actions

Copy link
Copy Markdown
Contributor

Human judgment recorded

@chenmingwei23 marked the first-principles AI finding as false positive, not applicable, or explicitly accepted for ea2a76afd6edc1ff699c9fcb6be8817691c70a52.

Maintainer decision by Mingwei on 2026-10-11 (option c): owner-written dashboard pages render in the opaque sandbox with no navigation wrapper, recorded as the dated RFC amendment in this PR that supersedes precondition P2; only the owner agent writes the page, pushed values are text-only, and the frame holds only the subscribed fields.

This decision applies only to this commit. A new push requires a new judgment.

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.

1 participant