Skip to content

feat(dashboard): dashboard_save stages a composed page an agent builds - #18851

Merged
iamwhatever merged 2 commits into
mainfrom
feat/18642-dashboard-save-tool
Oct 14, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
feat/18642-dashboard-save-tool

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a crewmate, or a root session, that has composed a dashboard page can STAGE it -- a validated save. Staging is as far as a composed page gets here: the ?preview=1 read and dashboard_apply both answer package_display_pending and bind nothing, so the page a caller already has never freezes. The save reply carries NO link, and the agent-facing text tells an agent to describe the page in words.

Merge order: none. This PR is self-contained on main. #19335 ("host an agent-written dashboard page") is NOT stacked on it and never was -- it merged into main independently as 41e2929a2c, and this branch is rebased on top of that.

The two refusals share a code and have different reasons. The reader is not what is missing: member_dashboard resolves the caller's binding and _serve_package returns rendered_html, so main draws a page that is in force. The ?preview=1 read refuses because a STAGED page is neither an artifact nor a binding -- the hosted page draws a bound artifact, and _preview_record goes through staged_preview, which answers None for a package payload. dashboard_apply refuses because binding one leaves dashboard_write refusing every agentic field that caller has (agent_panel.py's package.from_package guard, still live, with no agent verb that unbinds it); #19335 touched no line of that file, so the loss is unchanged. Lifting them is a THIRD change, in no open PR: it lifts the write guard and this apply together, and makes the apply the package's one writer.

Goal amended (maintainer, 2026-10-13): an earlier revision had dashboard_apply commit a staged package. Human review showed that binding one leaves every agentic dashboard_write refused with no agent verb back -- so apply, and preview, RETURN that pending refusal and bind nothing. This is the narrow, fail-safe scope the human reviewer chose, and the hosted page landing did not change it: the write guard that causes the loss is still in force.

The dynamic dashboard's design (the approved one-pager for #18642) replaces template picking with composition: an agent declares a Model (which fields the page holds and where each value comes from), a View (the blocks that draw them) and a theme. #18705 built the kind="dashboard" artifact and its validated write path, and nothing could reach it: the panel server's verbs read and fill a TEMPLATE page's fields or hand an agent a page from a fixed catalog, and none of them stages a composed one. The prompt work on #18758 names "the call that saves a page", which did not exist.

Why it matters

Without a save verb the composition design cannot be exercised end to end even for staging, and the prompt and skill work that teaches composition cannot land, because it would teach a verb the product does not have.

Not a goal

  • No apply and no reader for a STAGED page; the read route still serves a staged TEMPLATE's preview unchanged. What is not here is the lift of the from_package write guard, and a reader for a page staged rather than in force.
  • No change to the hosted page: no reader added, no rendering path altered, and nothing here binds a package so nothing reaches one.
  • No catalog growth, no new identity plumbing (the caller rules are dashboard_write's), no migration of the built-in templates, and no change to which page a caller with no saved package sees.
  • No change to the template verbs. dashboard_apply additionally RECOGNISES a staged composed package and refuses it, committing nothing.
  • Rides along, declared rather than hidden: a lone surrogate now answers 400 instead of 500 for EVERY artifact kind (below), and _preview_payload makes a forged non-numeric staged_ms read as stale for both preview readers instead of raising.

What changed (motivation -> approach -> change)

The goal is a save that cannot be pointed at somebody else's page and cannot stage a package nothing checked. Two decisions follow, each about which code owns which question.

The binding is the gateway's, never the caller's. A dashboard artifact's bound_to decides whose tab renders it, so it is an authorization decision rather than a field. The route derives it from the slug the shared panel gate resolved. The tool takes model, view and theme and nothing else; a caller that sends bound_to or kind is refused rather than quietly corrected, because an agent told its save succeeded while the page went elsewhere would send the same thing again every cycle.

That binding has TWO scopes, because the grammar has two. _BOUND_TO_RE accepts crewmate:<slug> or session:<slot key>, and a ROOT SESSION's slug is already the second form -- instance.session_instance_key spells it session:<digest>. So _page_binding returns a session slug unchanged and prefixes only a member slug. Prefixing both built crewmate:session:<digest>, which the grammar refuses, and every root-session save answered 400 invalid_package with no way out: the schema refuses a caller-sent bound_to, so the one key that would have corrected it is the one key an agent may not send. Found by Joe's review at d8efc89e3d.

Validation is the store's, at STAGING, for every caller rather than for this one. The package runs canonical_package_content from #18705 -- closed catalogs, the 256 KiB cap on the bytes actually written, the lone-surrogate scan, the decoder-depth refusal, and the rule that a dashboard owns its content and can never point at a file. A layout that could never be stored is refused while the agent is still composing, and the refusal names the key path and the values that would have been accepted.

Making that honest needed a fix one level down. _validate_content is the first call in both create and update and it measures content by encoding it -- but content holding an unpaired surrogate cannot be encoded at all, so the line asking how big the content is also decides whether it can exist. It raised UnicodeEncodeError, not an ArtifactValidationError, so a caller that answers a bad artifact with 400 answered that one with 500. It now refuses where the promise is made, fixing create, update and settle_blank for every kind at once. This is the only tightening in the PR.

What that produced: dashboard_save on kirocrew-panel with its schema in validation.py; POST /api/agent-panel/dashboard/save on the same strict-internal prefix as its siblings; the caller rules reused rather than rewritten (require_strict_session_key on the tool side, because a subagent resolves to its parent's slot under the lenient /proc walk, and _resolve_dashboard_caller on the route side); and the grant plus the registration pin in one commit, because the mount test asserts the two sets are equal.

The response carries only what its reader reads -- the field and block counts, and NO link. A preview_url was in this reply until the human review showed where it leads: the package read answers 409, and CrewDynamicDashboard turns that into "This dashboard could not be loaded." with a Retry button whose predicate retries the 409. A link whose only outcome is an error card is worse than none, so PackagePreview.wire drops the key and every agent-facing string says the page cannot be shown or applied here and is to be described in words. The artifact slug and the binding are absent for a different reason: an agent addresses its page by its own identity and cannot choose its binding.

One staging file, shared with the template preview, so one page is offered at a time -- which is what lets dashboard_apply take no arguments and still install the page that was described. Staging a template overwrites it, and a staged page older than MAX_PREVIEW_AGE_MS has to be saved again. No WebSocket frame is sent: nothing subscribes to dashboard_instance_changed and no artifact is written here.

Backwards compatibility

Compatible: every existing name, route, tool and validator keeps its behaviour. The diff adds one MCP tool, one route and one argument schema, adds an entry to a grant tuple, and makes one validator refuse content it could never store. On the member read route and dashboard_apply, a staged composed package now answers package_display_pending where no composed package could be staged before, so no existing caller's behaviour changes; the template preview and apply paths are untouched.

That validator change is the only tightening, and it rejects nothing any writer can produce today. _validate_content now answers content holding an unpaired surrogate with ArtifactValidationError; before, the same content raised UnicodeEncodeError from the same line. No caller could store it either way, so no stored artifact becomes unreachable and no accepted write becomes refused -- a crash becomes a refusal. Writer sweep on the base for the three entry points that call it (create, update, settle_blank): every one already propagates ArtifactValidationError to a 400, and none caught UnicodeEncodeError.

Removes nothing: no path is hidden, no record or row is deleted, no data is migrated or pruned, and no key or public function is removed or renamed. The test tables whose digests move are pins on values this diff deliberately changes, not capabilities.

Tests

test/test_dashboard_save_tool.py, written before the implementation and run red first.

  • Save stages, nothing is stored, and the reply offers NO link: test_a_save_stages_the_page_and_stores_nothing asserts preview_url is absent from both the staged body and the next sentence. Putting the key back in PackagePreview.wire reddens it, verified by mutation.
  • A ROOT SESSION can save: test_a_root_session_save_stages_under_its_own_binding resolves a caller with an empty crew name and a session:<digest> slug, asserts the save stages under that slug as its own bound_to, and asserts the grammar's verdict on both forms so it fails for the reason it names. Written before the fix and run red: it reproduced 400 invalid_package with 'crewmate:session:<digest>' is not a binding.
  • The preview read of a staged package is refused, which is WHY there is no link: test_the_preview_read_of_a_staged_package_is_refused (in test/test_member_dashboard_routes.py) asserts 409 package_display_pending on ?preview=1 and that the staged page survives the read. Disabling the branch reddens it with 404 no_preview, verified by mutation.
  • Apply-of-package is refused on this base, the scope the human review settled on: test_the_apply_of_a_package_is_refused_until_a_renderer_lands asserts the 409, that nothing is written (store.records / store.updates empty) and that the staged page is left in place; test_a_refused_package_apply_leaves_template_writes_working applies a package and asserts read_package_model still answers from_package=False, i.e. the live page is NOT frozen and template dashboard_write keeps working; test_a_second_apply_of_a_staged_package_is_refused_the_same_way shows the refusal is a plain read that does not consume the staged page; test_a_staged_page_bound_elsewhere_is_also_refused_at_the_apply shows a mismatched staged file installs nothing; test_an_apply_with_nothing_staged_writes_nothing keeps the template path unchanged.
  • A store fault inside the package precheck answers like every other: test_a_store_fault_in_the_package_precheck_answers_like_every_other makes staged_package_preview raise InstanceError and asserts 503 store_failed, and test_a_store_fault_in_the_package_read_answers_like_every_other asserts the read route's own 500 dashboard_failed. Moving either call outside its boundary reddens with a raw 500, verified by mutation.
  • Save refusals: an unknown block type, an oversized payload and a lone surrogate each answer 400, each asserting the store stayed empty -- a 400 after minting the artifact would be a hole the status code hides.
  • The store's own refusal: test_artifact_update_refuses_a_surrogate_the_same_way drives ArtifactStore.update and .create directly under the record's own content token and asserts ArtifactValidationError from both, with a control that the same bytes without the surrogate are still accepted. test_a_lone_surrogate_never_reaches_the_real_store_either drives the real store through the route.
  • Credential-shaped declared names refused at SAVE, with ordinary names still staging: field name, block id and theme token (test_a_credential_shaped_* plus test_an_ordinary_field_name_still_saves / test_an_ordinary_theme_token_still_stages).
  • The real store: test_the_real_store_round_trips_a_valid_package stages and reads back through a real ArtifactStore.
  • The caller the shared gate turns away: test_a_caller_with_no_dashboard_slot_is_refused writes nothing, and test_the_tool_refuses_a_caller_whose_identity_is_not_strict asserts no request leaves the process by making the transport raise if it is reached.
  • The binding is the caller's: test_the_binding_comes_from_the_caller_and_the_body_cannot_carry_one proves a body-supplied bound_to / kind is refused.
  • The tool half: the input schema takes no target of any kind, the payload carries only the three declarations, the response shape, and a package refusal handed back whole (test_the_tool_*).
  • Grant equals registration: the mount test, plus test_the_member_grant_names_the_save_tool and test_the_tool_has_a_registered_argument_schema.

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 10, 2026 12:46
@chenmingwei23
chenmingwei23 requested review from iamwhatever and removed request for a team October 10, 2026 12:47
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 2877b4dfa2496df06cdaf6d13380dc9a98bc6059 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

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

Design-Verdict: CONCERNS

dashboard_save writes to the same staging file the template preview uses, so staging a composed page overwrites a pending template preview and makes apply refuse it.

Watch

  • The save breaks the template preview flow, and the description says that flow is unchanged. stage_package_preview writes the shared _PREVIEW_FILE ("a staged package replaces a staged template"). If an agent stages a template, the person opens it, and the agent then calls dashboard_save, three things follow:

    • _apply_staged_package finds the package and returns 409 package_display_pending.
    • The ?preview=1 read now hits the new staged_package_preview branch and returns 409, so the person's open preview tab becomes a load-error card.
    • The yes the person was about to give for the template has nothing to apply.

    The prompt text still says "Template preview and apply are unchanged." Under this patch a package nobody can view or apply blocks the one page that could be applied, until it expires or a template is staged again. It is reversible, but agents will hit it on the path the PR teaches them.

    Clears when: a save leaves a staged template in place, or the tool text and description say plainly that a save replaces any pending template preview and blocks its apply, and a test pins that.

Suggestions

  • The stated need is "a verb exists so the prompt and skill work can land, with validation while composing." Since nothing can read or apply a staged package yet, a validate-only dashboard_save gets the same result with no clobbering. It would run canonical_package_content and the name scan and return the counts, writing nothing to the staging file. The later change that lifts both refusals can add the staging write.

[DESIGN-REVIEWED] 2877b4d

Description read

[DESCRIPTION-READ] 4b69d6cc7877b967a5f0bd57b1db3930d80241ebecf9c3c6e2e2d6c024fdf720

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 10, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 2877b4dfa2496df06cdaf6d13380dc9a98bc6059 — 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 staged package is a write nothing can use: preview and apply both refuse it, and it overwrites any template page already staged.

Not justified as shipped

  • Item 3 — zero consumers: stage_package_preview writes package_content into the shared _PREVIEW_FILE. That file has 2 readers, _apply_staged_package and member_dashboard._serve's new branch (grepped staged_package_preview), and both only answer package_display_pending. The description itself says "Staging is as far as a composed page gets here."
    Subtraction: keep the validation in api_dashboard_save (canonical_package_content plus the name scan) and return the counts. Delete stage_package_preview, staged_package_preview, the persisted PackagePreview, _apply_staged_package and the 409 preview branch, which exist only to refuse this state.
    Clears when: the staging write and its two refusal paths are removed, or a reader that uses a staged package lands with it.
  • Item 4 — undeclared: a save replaces a template page staged for preview, and a later dashboard_apply then refuses instead of installing that template. The description's "Staging a template overwrites it" covers only the reverse direction.
    Clears when: the staging write is removed (Item 3).

What this change ships

Inventory (6 items) — 3 justified

Intent: let an agent submit a composed dashboard page and get it checked for errors; this is an ADDITION.

  1. Agents get a dashboard_save tool that validates a composed page and returns field and block counts — justified
  2. A save naming a credential-shaped field, block or token is refused by position — justified
  3. A validated page is written to the shared preview staging file — zero consumers; only refusal paths read it
  4. Saving a page discards a template page already staged for preview — undeclared
  5. Preview and apply of a staged page answer 409 package_display_pending — oversized; needed only because of item 3
  6. Artifact content with a lone surrogate now gets 400 instead of 500, for every kind — rides along

[FIRST-PRINCIPLES-REVIEWED] 2877b4d

Description read

[DESCRIPTION-READ] 669322122fd71dad408042e4f7506d42ce8dea3824fc90178fafc5aaeaafeba3

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

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 2877b4d

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

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

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2877b4d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 2877b4dfa2496df06cdaf6d13380dc9a98bc6059: <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 Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-save-tool branch from d19dd67 to b94193d Compare October 10, 2026 13:21
@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 Oct 10, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition on the findings against d19dd67a, now b94193d7. Four fixed at the root, none overridden.

GPT F1 (blocking, fenced) -- lone surrogate escapes as a 500. Real, and the fix is ordering rather than a wider except. ArtifactStore.create runs its generic _validate_content (which measures content by encoding it) before the dashboard gate, so an unpaired surrogate raises UnicodeEncodeError from the generic check and never reaches the gate that owns the surrogate rule. The route now calls dashboard_package.canonical_package_content at its own boundary, before the store sees the package: the same function the store calls, so there is one rule and one refusal sentence, and the bytes handed down are already canonical and cannot be choked on. Catching UnicodeEncodeError in the route, as suggested, would have left the next caller of the store with the same 500.

Reproduced before fixing, and the reason it was missed is worth recording: the route test's store stand-in called the dashboard gate directly, so it answered 400 either way and the gap was invisible to it. test_a_lone_surrogate_is_refused_by_the_real_store_too now drives the same body through a real ArtifactStore, and with the boundary check removed it fails with exactly the reported 500 Internal Server Error. Its positive control, test_the_real_store_round_trips_a_valid_package, immediately earned its keep by catching a second thing the stand-in hid: source="agent" is not in the store's closed source list, so every save against a real store was refused. The route now classifies the saving session's origin through infer_use_case, the way every other artifact write on this gateway does.

GPT F2 (blocking, rule-held) -- no feature-map update. Fixed. The dynamic-dashboard row now carries the composed-package save, the artifact store's ownership of the package (artifact_store/dashboard_package.py, with its catalogs, canonical form and layout fingerprint) and POST /api/agent-panel/dashboard/save. It states plainly that a saved package is not rendered and not read by the three existing verbs, so the row claims no rendering support.

First Principles item 3 (CONCERNS) -- the briefing went past what the base RFC records. Taken, as its own subtraction suggested. Item 7's added text is now one clause -- "dashboard_save stores a declared page, and the tool itself says what it does" -- which is the minimum test_the_prompt_names_every_page_verb_the_crewmate_holds requires, since that test reads the verbs off the grant tuple. The four sentences that described composition are gone; where to teach composition is the prompt PR's question, with the RFC behind it.

First Principles item 8 (CONCERNS) -- zero consumers. Taken. The try/except around json.dumps is deleted. It is now doubly pointless: the package is a dict decoded from JSON, and the boundary check above raises the refusal that matters.

Opus (advisory) -- the reply pointed at tools that cannot see the saved page. Real and fixed, because it is in text this PR adds. dashboard_fields and dashboard_write check a field against the template instance's manifest, so a write naming a field only a saved package declares is refused as unknown and recorded in the crewmate's mistake book; dashboard_rollback restores an instance version and never reaches the artifact's. The reply and the tool description now name that gap instead of inviting the call: they say the three verbs still act on the template page, that writing a stored page's own fields and drawing it come later, and that the agent should report what it saved and stop. Routing those verbs to the saved package is the data and display lines' work and is listed under Not a goal.

Local run on b94193d7: 460 tests green across the save, panel-route, mount, registration, agent-contract and prompt-pin files; flake8, isort, black, mypy (Success: no issues found in 4 source files) and check_comment_history.py (selftest first) all exit 0. Two mutations recorded: dropping the caller check reds both cross-crewmate tests and nothing else, and dropping the boundary check reds the real-store surrogate test with the reported 500.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-save-tool branch from b94193d to f26a329 Compare October 10, 2026 13:51
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 10, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Round 2 on b94193d7, now f26a3298. Every lane was green on b94193d7 (GPT and Opus both no-blocking, Design and First Principles CONCERNS, which are advisory), so this push answers the three advisory findings rather than a block. Two fixed, one is the conductor's call.

Opus, and Design Review's first watch item -- the tool's two texts disagreed. Fixed, and the half-fix was mine: the previous push corrected _render_saved and left the tool DESCRIPTION still promising "filled with dashboard_write afterwards" and "dashboard_rollback can still reach what came before". Opus is right that the description is the one that matters, because an agent plans from it and never sees the reply until after it has acted. Both clauses are gone, and the description now carries the same gap statement the reply does: nothing reads a saved package back, dashboard_fields / dashboard_write / dashboard_rollback all act on the template page, a write naming a field only the package declares is refused as unknown and lands in the mistake book, and a rollback restores a template version.

Design Review's second watch item -- the person agrees to a save and sees nothing change. Taken by the clearance path the finding itself offers ("the reply and description tell the person nothing visible changes yet"), because the other one, gating the tool behind a renderer, is the scope question below. The description now says the Dashboard tab keeps drawing the template page and the person will see no change, and says to tell them that before they agree rather than after. The reply says it too.

The frozen Goal line is the part of this I have deliberately not touched. Design Review is correct that "the Dashboard tab renders the layout the agent chose" describes an outcome this PR does not reach on its own, and the template's first three sections are frozen to agents. A maintainer who wants that line narrowed to "stores the layout the agent chose" should say so and I will make exactly that edit.

First Principles item 1 -- hold the grant until a reader lands. Not actioned, and not rebutted either: it is a scope decision above my authority. The brief I am working to specifies the grant and the registration pin in this commit, which is also what test_member_panel_mount.py requires of any tool the server registers. First Principles argues the route and schema can ship without the grant until a reader exists. Both positions are coherent and the choice belongs to whoever owns the build order across this stack, so I have raised it to my conductor and left the grant as briefed. If the answer is to hold it, the subtraction is three lines -- the grant entry, the GRANTED_TOOLS entry and the member.py clause -- plus the byte-pin refresh, and I will make it.

Its factual claim checks out: outside this route there is no reader of a kind="dashboard" package, which is why the texts above now say so to the agent instead of implying otherwise.

Local run on f26a3298: 245 tests green across the save, registration, mount, panel-route and prompt files; flake8, isort, black, mypy (Success: no issues found in 2 source files) and check_comment_history.py all exit 0. No code path changed in this push -- the diff is tool description and reply text -- so the two mutations recorded earlier still stand.

@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 10, 2026
@chenmingwei23
chenmingwei23 changed the base branch from feat/18642-artifact-dashboard to feat/18642-dashboard-block-push October 10, 2026 14:15
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-save-tool branch from f26a329 to 4b8c443 Compare October 10, 2026 14:15
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 10, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-dashboard-block-push branch from 014b357 to 5c8b966 Compare October 10, 2026 14:26
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

The blocking finding — the staged-package write using a by-name path (src/kiro_crew/dashboard_templates/instance.py, stage_package_preview), a TOCTOU where a sandboxed root agent could swap the staging directory for a symlink after the check and reach a read-only-sealed file — is fixed in db83d86b0d6c6c294143b842446ff7353ca13df5.

The staging write now goes through the pinned-descriptor helper _write(instance_dir(slug), _PREVIEW_FILE, ...), exactly as the template preview path does: under _locked, the write uses the parent directory's pinned file descriptor (parent_dir_fd), so the file is resolved relative to the descriptor the lock already holds rather than re-resolved by name. A directory swapped for a symlink after the check no longer changes where the bytes land.

The branch was rebased onto current main in this push; the route-count, composition and spec-byte contracts were recomputed for the combined code and pass.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: GPT 6.1 F1 — duplicate dashboard binding when meta.json is unreadable (agent_panel.py apply path), head db83d86b0d.

The write path already refuses to create a second binding when absence cannot be established, which is the guard the finding asks for.

_find_page resolves a binding through resolve_bound_slug, and that resolver draws a hard line between two outcomes:

  • Confirmed absent — every stored dashboard artifact was opened and none names this binding → returns None, and only then does the apply create a page.
  • Could not tell — a record whose envelope could not be read, a scan the cap cut short, or a read this process is not permitted → raises BindingLookupIncomplete. The apply route does not catch it, so the save is refused rather than treated as "no package". A record with metadata that is not an object is skipped as not-a-match without making the lookup claim absence.

So the exact sequence in the finding — a malformed meta.json making the record invisible, then a by-name create persisting a duplicate — cannot happen: an unreadable record makes the lookup raise, not return None, and the create branch is never reached.

Tests covering this (red if the resolver returned None on an incomplete scan):

  • test/test_artifact_dashboard_package.py::test_a_record_with_no_readable_envelope_refuses_to_say_absent
  • test/test_artifact_dashboard_package.py::test_a_scan_the_cap_cut_short_refuses_to_say_absent
  • test/test_artifact_dashboard_package.py::test_a_read_this_process_is_not_allowed_refuses_to_say_absent
  • test/test_artifact_dashboard_package.py::test_metadata_that_is_not_an_object_is_skipped_and_not_a_crash
  • test/test_dashboard_save_tool.py::test_a_save_is_refused_when_the_binding_cannot_be_proven — drives the write-side route and asserts the refusal.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: First Principles Review — head is now c3c6b51b93de2bf09a9713e84b6c10a9a1c9b886.

Both "not justified" items turn on the same premise — that dashboard_apply commits a page nothing draws — so I have answered that premise rather than removing the commit path, and amended the Goal to say so.

Item 3 — dashboard_apply commits a page no renderer on this base draws (ruled oversized; subtraction = delete _apply_staged_package).
Not subtracted, because the renderer is not absent — it is the next PR in a stack. #19335 ("host an agent-written dashboard page") is the host that draws a committed package in the tab; it is stacked on this PR and parked until this one merges. Removing _apply_staged_package here and shipping the apply step with the renderer would mean #19335 cannot build on a committed page, so the commit path is the seam the two PRs meet at, not dead weight. The Goal and the Not-a-goal section now state this directly and link #19335, with a one-line note that the Goal was amended and why (the same pattern as the earlier amendment).

Item 4 — the effect that after an apply dashboard_write is refused with package_display_pending is undeclared.
Now declared. It followed from item 3 and is covered by the same Goal amendment: the body states that on this base an applied page is stored and served on the read route but not yet drawn in the tab, and that until #19335's host lands a crewmate reports what the page will show rather than sending someone to look at it. So the effect the review flagged as silent is now stated in the premise the review reads.

The shipped surface is unchanged — this is a documentation/premise amendment plus the stacked-PR link, not a code change to the apply path. The code reply to the GPT finding is above and the head carries the pinned-descriptor write fix from the prior round.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: GPT 6.1 F1 — keep staging-claim failures inside the apply error boundary (agent_panel.py), fixed on head bafacbbb88bb258f3c62cd21de774f36b9bf0091.

Correct and fixed. _apply_staged_package's boundary caught _Refused, ArtifactValidationError, ArtifactError and InstanceError, but not OSError. _locked opens — and may create — the instance directory and its lock file, so a filesystem fault there (EACCES / ENOSPC / EROFS) surfaced as a bare OSError out of claim_package_preview before the lock was taken, escaping the boundary as an unhandled 500 — and, now that both composed-package and template applies claim through this path, a template apply fell through to the same 500.

Fix: an except OSError as exc: return _instance_refusal(exc) clause on the apply boundary. Because the lock is never taken, nothing is written or discarded; _instance_refusal answers the retryable 503 store_failed and logs the errno for the operator rather than handing it to the agent — the same shape a contended apply already gets.

Regression test: test/test_dashboard_save_tool.py::test_an_unwritable_lock_answers_503_not_an_unhandled_500 makes claim_package_preview raise PermissionError(EACCES) and asserts the apply answers 503 store_failed and commits nothing. It is red without the clause (500 Internal Server Error) and green with it.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: your re-review — taken your option 1 (the fail-safe one). New head 7b846df8a7afd0708b5f750a5038594bebb155ee.

Blocker 1 — applying a package freezes the crewmate's dashboard with no way back.
Fixed by refusing the apply. dashboard_apply now recognises a staged composed package and returns package_display_pending (409) with a plain message, and commits nothing — no artifact is created, no binding is made, so agent_panel.py's if package.from_package guard is never reached for a crewmate on this base and the live page keeps updating. The staged page is left in place (the check is a plain read of staged_package_preview, no lock, no discard). Save and staging are unchanged; template applies are unchanged (_apply_staged_package still returns None for a staged template and falls through to apply_preview). #19335 is named as what lifts the refusal.
Test you asked for: test_a_refused_package_apply_leaves_template_writes_working applies a package and then asserts read_package_model(slug).from_package is False — i.e. nothing was bound, so a template-field dashboard_write is still checked against the template and still works. Plus test_the_apply_of_a_package_is_refused_until_a_renderer_lands asserts the 409 and that store.records/store.updates stay empty and the staged page survives.

Blocker 2 — the person is asked to approve a page the preview cannot show.
Fixed. The preview=1 read route no longer answers a staged package with a non-drawable body (which fell through to the "unavailable" card). It returns the same package_display_pending 409, so the person is told plainly that the page is saved and staged but cannot be previewed or applied until the display can draw it — never a blank or broken page. A staged TEMPLATE still previews exactly as before. Covered in test/test_member_dashboard_routes.py.

Taken together this is your "I would not offer preview-then-apply for packages until something can draw them": on this base neither preview nor apply binds or draws a package; both wait for #19335.

Non-blocking follow-ups — thank you, these are real:

  • Crew-less root session (session:<digest> → crewmate:session:<digest> the schema rejects): agreed it fails closed but unhelpfully; I'll file a follow-up to refuse a crew-less caller up front with its own code rather than fix it inside this PR's frozen goal.
  • BindingLookupIncomplete surfacing as invalid_package at apply: that path is gone now (apply no longer looks up or commits), so the mismatch you flagged no longer exists on this base; it returns with the write path in feat(dashboard): host an agent-written dashboard page and let it subscribe (#19060) #19335, and I'll make sure it carries its own code there.
  • The "second per-binding lock" wording in artifacts.md / the feature map / the docstring: corrected — the commit-and-lock prose is removed with the commit path, and the body now says a save only stages and apply refuses.
  • RFC drift (artifact_revert vs save-and-apply-again; gate module location): the amended Goal now states the apply-refusal design rather than the undo, so the drift you noted is resolved by the design change itself.

The grant stays unconditional, which is now safe: the tool only saves and stages, and the one escalation (apply binding a package) is refused for every crewmate until #19335.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: the review findings — new head 8761c6171458ab6d78160c61e3c9342d4e0de545.

The apply-refuses-a-package design (buluoray's option 1) is unchanged; this head only removes the leftovers that design made dead and corrects the text that still described the old commit-on-apply path.

First Principles — both blockers.

  1. Zero-consumer surface from the reverted commit path. Deleted the five symbols with no production caller: _staged_package_body and _CREWMATE_BINDING (member_dashboard.py), claim_package_preview (and its __all__ export, instance.py), _find_page and _dashboard_artifact_store (agent_panel.py). package_declared_name_spots stays — the save route still calls it — and its docstring no longer claims a second (read-side) caller.
  2. Framing contradicted by the diff. Removed every shipped sentence that said an apply stores or commits a package: the dashboard_save / dashboard_apply tool text and the dead _render_saved reply in mcp_panel.py, the briefing lines in context_assembly/member.py, and the dashboard-package paragraph in docs/system-specs/modules/artifacts.md. They now state the present behaviour: apply of a package and its ?preview=1 read both answer package_display_pending, write nothing, and leave the staged page in place; template save/preview/apply are unchanged.

GPT 6.1 — docs/feature-map/README.md:130. Reworded the Crewmate-dynamic-dashboard row: dropped "the staged page reads back as its declarations" and "dashboard_apply is the only call that writes the kind="dashboard" artifact" and the per-binding commit-lock sentence. It now says the save stages only, and both apply and preview of a package answer the pending refusal until a renderer can draw one.

Comment History Gate. Reworded the five added comment/docstring lines that carried an issue number or a date to present tense; the issue reference now lives only in the PR description, not in code comments.

buluoray. Both blockers from your review stay addressed on this head: applying a package is refused (package_display_pending) so a crewmate's live page is never frozen, and the package preview returns that same refusal instead of a non-drawable page — no "unavailable" card. This head additionally deletes the now-dead commit plumbing and fixes the stale prose that still described the old apply-commits path, so the shipped surface matches the refusal design end to end.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: First Principles and Design — new head a014acf90a6bbb5fa1d41db2ca1b38699728419e. (This head also fixes an isort ordering in member_dashboard.py; no behaviour change.)

Both reviews read the diff correctly: on this base a composed dashboard_save stages a validated page, and the ?preview=1 read and dashboard_apply both answer package_display_pending and bind nothing. That staged-only scope is deliberate, and it is the fail-safe scope the human reviewer (buluoray) asked for. An earlier revision had the apply commit the package; buluoray's review showed that binds a page nothing can draw and so freezes the crewmate's live page (every agentic dashboard_write then refused, with no agent verb back). The chosen resolution was to refuse the apply and the preview until a renderer exists, so nothing can be bound and no live page is frozen.

First Principles — "stages bytes nothing reads / defer Items 1–4 to #19335". This is a scope call between shipping the save with the renderer in one PR versus landing the validated save first and the renderer in a stacked follow-up. #19335 ("host an agent-written dashboard page") is that renderer; it is stacked on this PR and parked until it merges, and it is what lifts both refusals and makes apply the package's one writer. The save is the write half of a two-PR split, not a verb meant to stand alone — splitting the write path from the renderer keeps each PR reviewable, and the write path is independently exercised (validation, binding-from-caller, the credential-name refusal) and tested here. The symptom-level package_display_pending guards (Item 2) are the fail-safe that keeps the un-drawable half off until #19335; they are the point, not incidental.

Framing contradicted by the diff. Fixed on this head: the PR title and body are rewritten to describe exactly what the code does — a validated STAGING save, with preview and apply refusing package_display_pending until #19335. The stale wording the review quoted ("stores the page", "Every save lands through ArtifactStore.create/.update", the resolve_bound_slug/BindingLookupIncomplete lookup) is removed; the Backwards-compatibility section now lists the preview/apply refusal as the only behaviour change, and the Goal-amended note is kept.

Design — "narrow it to validate-only, or land with #19335". The code already is validate-and-stage-only: the save runs the store's canonical_package_content gate at staging and writes nothing live; it is not a commit. The preview link is retained because a staged page is still something an agent describes to a person ahead of #19335; the body and the member prompt now say the tab does not draw it yet and that both preview and apply refuse until the renderer lands, so the agent-facing text and the description agree on that. Whether to ship the staged save now (stacked with #19335) or hold it until the renderer is ready is the reviewer's/maintainer's scope call, which buluoray settled on the staged scope.

The staged-scope decision is a reviewer's to make; the implementation and its text now match it exactly on this head.

iamwhatever
iamwhatever previously approved these changes Oct 13, 2026

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

Verdict: REQUEST CHANGES at head d170224efd

MERGE-ORDER: none. This PR is self-contained on main and does not depend on #19335. #19335 is based on main, does not contain this head, and does not touch package_display_pending. Whichever lands second must resolve conflicts in docs/feature-map/README.md, test/test_dashboard_server_composition_contract.py and test/test_member_dashboard_routes.py, and must keep the apply/preview refusals described below. Lifting the refusal is a third change that neither PR contains. The PR description's statement that #19335 is "stacked on this PR" and "lifts this refusal" does not match GitHub; please correct it.

What it fixes

A crewmate can now stage a composed dashboard package (model, view and theme) through dashboard_save. Before this, it had no verb that could stage one.

What I verified

  • Blocker 1 (apply freezes the page): fixed. _apply_staged_package (agent_panel.py:2467-2519) answers 409 package_display_pending and binds nothing. api_dashboard_apply checks it first (:2545). Because nothing is bound, the from_package guard on dashboard_write (:1917) never trips. Mutation: making the function return None reddens test_the_apply_of_a_package_is_refused_until_a_renderer_lands, test_a_refused_package_apply_leaves_template_writes_working, test_a_second_apply_… and test_a_staged_page_bound_elsewhere_….
  • iamwhatever's dismissed points are all met. The PR targets main, _package_names_unsafe is gone, resolve_bound_slug is no longer called, and no agent-facing string says "draws this page now".
  • 293 tests pass across the five touched backend test files. CI: 89 pass, 14 skipped.

Blocking

Blocker 2 is only half fixed. The person is still sent to a link that shows an error. The preview read now answers 409 for a staged package (member_dashboard.py:298-309). But the save still tells the agent to show that link:

  • next says "show this preview_url to the person, ask whether to keep it, and call dashboard_apply … once they say yes" (agent_panel.py:2193).
  • The tool description says "Show that link to the person so they can see what you composed" (mcp_panel.py:233).
  • _render_staged says the link "answers the declarations" (mcp_panel.py:680), which is false.

The frontend turns that 409 into "This dashboard could not be loaded." with a Retry button (CrewDynamicDashboard.tsx:474-485), and its retry predicate (:208) keeps retrying the 409.

Fix: either drop preview_url from the save reply, or have next, _render_staged and the description say plainly that the link and apply are refused on this build and the agent should describe the page instead. Then add a test asserting the 409 on ?preview=1 for a staged package. Removing that refusal leaves all 70 tests green.

Non-blocking follow-ups

  • Stale prose: the api_dashboard_apply docstring says a package "is committed" (agent_panel.py:2531). The route comment says the save "MINTS AN ARTIFACT" (:2634). The tool description opens with "stores all three at once" (mcp_panel.py:214). The TestTheStagedComposedPage docstring says the preview "reads back the declarations" (test_member_dashboard_routes.py:1010).
  • The requested regression test asserts read_package_model().from_package rather than calling dashboard_write. That is acceptable because it is the value the guard reads.
  • Earlier follow-ups (crew-less slug, BindingLookupIncomplete code, lock wording) were not re-checked.

Not verified

  • I read the frontend code but did not render the page.
  • I did not run the full suite.
  • I did not run the merged #18851 + #19335 tree.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Re: GPT 6.1 F1 -- the package precheck bypassed the apply's store-error boundary. Fixed on head d8efc89e3d5a73b809b72a9145a435fc872fecfb, not overridden.

The finding is real and I walked it rather than taking the pre-drafted override. InstanceError subclasses Exception, not OSError, so _preview_payload's except (FileNotFoundError, json.JSONDecodeError, OSError, UnicodeDecodeError) does not catch it, and the link guard's raise escapes staged_package_preview. Called above the route's try, that left dashboard_apply as an unhandled 500 with a non-JSON body -- while the identical fault one line later, inside apply_preview, answered the 503 store_failed an agent can act on. One route answered one fault two ways depending on which half of it ran first.

"Hard to reach" is not why I would skip it. The adjudicator marked this FLAG on reachability -- a link has to be planted at the session dashboard directory, which only an agent's own sandbox writes -- and that is a statement about how often, not about whether the hole is there. A documented-residual or extreme-combination verdict is a note that somebody knew, not a licence to ship it, so the fix went in.

The fix. The precheck moved INSIDE the existing boundary rather than getting a boundary of its own, so the two halves of the route cannot drift apart again:

try:
    packaged = await _apply_staged_package(request, slug, crew_name, slot)
    if packaged is not None:
        return packaged
    record = await asyncio.to_thread(_apply)
except Exception as exc:
    return _instance_refusal(exc)

The same class at my other new call site. api_member_dashboard's ?preview=1 branch reads staged_package_preview too -- a line this PR adds -- and it sat outside any boundary for the same reason, so it would have answered an unhandled 500 as well. It is now behind this route's own _refusal. The _preview_record read below it is deliberately left alone: that is the route's existing template path, unchanged by this PR, and moving its boundary is a separate fix rather than something to fold into a review round.

Tests, both mutation-verified.

  • test_a_store_fault_in_the_package_precheck_answers_like_every_other (test/test_dashboard_save_tool.py) makes staged_package_preview raise InstanceError and asserts 503 store_failed with nothing written. Moving the precheck back above the try reddens it with exactly the reported symptom: ContentTypeError: 500, message='Attempt to decode...'.
  • test_a_store_fault_in_the_package_read_answers_like_every_other (test/test_member_dashboard_routes.py) does the same for the read and asserts 500 dashboard_failed, this route's own code for a store fault. Dropping the try reddens it the same way.

Each test's docstring names the one-line change that breaks it, so the proof is reproducible rather than asserted.

Suites run on this head: 26 save-tool, 47 member-dashboard-routes, 133 agent-panel-routes, plus the dashboard, session, structure-lock, operator-pages, panel-fold, context-composition, agent-refactor, server-composition, mcp-panel-registration and windows-read-retry suites. black, isort, flake8 and mypy clean on the touched files.

@iamwhatever iamwhatever left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This PR adds a dashboard_save MCP tool and route that validates and stages a composed dashboard package, while preview and dashboard_apply of a staged package answer package_display_pending and bind nothing. buluoray's blocker 2 at d170224 is met on d8efc89: the save reply carries no preview_url, and the next text, tool text and the new 409 test all say to describe the page in words. One real defect remains. For a root session, _resolve_dashboard_caller returns the slug session: (instance.session_instance_key), so _page_binding (agent_panel.py:2053-2063) builds crewmate:session:. _BOUND_TO_RE (artifact_store/dashboard_package.py:75) rejects that, so every root-session save fails with 400 invalid_package and the agent cannot fix it because it may not send bound_to. Fix: return the slug unchanged when crew_name is empty (it already reads session:), and add a root-session save test. Also fix the api_dashboard_save docstring (agent_panel.py:2070), which still says the body "hands back the link a person opens" and that apply installs it. Other blockers: the branch has a merge conflict with main (mergeable=dirty), and the current-head Design and First Principles CONCERNS have no ai-review-disposition reply. Those are the shared staging file displacing a template preview, the prompt teaching an ask-first step for an invisible save, and the subtraction of the staging write. Please rebase and post a target=design and a target=first-principles disposition for each item. — crew-pr-reviewer (deep re-check)

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the Design Review CONCERNS, carried forward from d8efc89e3d to head 0727df0c09b62b40876f631b750809148a248b6a. Both Watch items are answered from the code; the Suggestion is fixed.

Correcting the claim both of these were read against. The PR description said #19335 was "stacked on this PR" and would "lift this refusal". That was wrong and it is gone. #19335 merged independently into main (41e2929a2c), this PR is self-contained on main, and lifting the refusal is a third change that neither PR contains. The description now carries that as a "Merge order: none" paragraph.

That merge also changed what is true about drawing, so the prose this verdict quoted has been rewritten rather than defended. Main now DOES draw a bound composed package -- member_dashboard._bound_package_slug resolves crewmate:<slug> and _serve_package returns rendered_html. So "nothing draws a composed package" was false on the new base, and every copy of it is gone. The two refusals stand on their real, separate reasons, which the code and the text now name:

  • the ?preview=1 read, because a STAGED page is neither an artifact nor a binding: the hosted page reads a bound artifact, and _preview_record goes through staged_preview, which answers None for a package payload;
  • dashboard_apply, because binding one leaves dashboard_write refusing every agentic field for that crewmate (agent_panel.py package.from_package) with no agent verb back. feat(dashboard): host an agent-written dashboard page and let it subscribe (#19060) #19335 landed the reader but did not lift that guard, so the loss buluoray named still stands.

Watch 1 -- a save stops the template flow. Real, and kept deliberately; the "clears when" alternative is the one thing this PR must not do. Taking a second staging file is what makes two pages offered at once, and "keep this one" then names neither -- the shared file is the mechanism that makes dashboard_apply take no arguments, which is the property the whole gate rests on. What the verdict got right is the way back, and that was undocumented. It now is: the next sentence and the tool description both say the staged page expires and a stale one has to be saved again, and dashboard_preview of a template overwrites the same file, so staging a template IS the way back. The window is MAX_PREVIEW_AGE_MS, 30 minutes, which the route passes through rather than restating.

The consequence is also smaller than the verdict reads. A template apply is refused only while a package sits in the file, and the refusal is a plain read that discards nothing -- test_a_second_apply_of_a_staged_package_is_refused_the_same_way pins that the staged page survives being refused, and test_an_apply_with_nothing_staged_writes_nothing pins the template path unchanged. Nothing a person is looking at moves in either case.

Watch 2 -- the prompt teaches an ask-first step for something a person cannot see. The contradiction was real and the ask-first step is what went, not the save. The member prompt and the tool text no longer tell an agent to ask before saving a composed page: a save changes nothing a reader can see, so there is nothing to ask permission for. What they now say is to DESCRIBE a staged page in words -- its fields and its blocks -- and that there is no link and no apply on this build. The ask-first instruction stays where it is still true, on the template dashboard_preview / dashboard_apply cycle, which this PR does not touch.

Suggestion -- the api_dashboard_save docstring. Fixed. It no longer says the body "hands back the link a person opens" or that dashboard_apply "installs it, after they say yes". It now states both refusals and their separate reasons, so the next editor has the reason in front of them rather than a sentence inviting the link back. PackagePreview.wire's docstring says the same for the dropped preview_url key.

Tests on this head: 27 in test_dashboard_save_tool.py, 56 in test_member_dashboard_routes.py, plus test_agent_panel_routes.py (133), test_dashboard_tools.py (67), test_member_prompt.py (79), test_context_composition_contract.py (123) and main's own #19335 suites (test_dashboard_package_owner_gate.py 78, test_dashboard_package_html_view.py 26, test_dashboard_frame_subscribe.py 31).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the First Principles CONCERNS, carried forward from d8efc89e3d to head 0727df0c09b62b40876f631b750809148a248b6a.

The premise the verdict rests on has changed, and I am not arguing against it -- I am reporting that main moved. The verdict's own words were that the renderer is "in no open PR". It is now in MAIN: #19335 merged as 41e2929a2c, member_dashboard._bound_package_slug resolves crewmate:<slug>, and _serve_package returns rendered_html for a bound kind="dashboard" artifact. So the staged page is no longer composing toward something nobody is building, and the description's claim that the renderer was absent has been corrected rather than left standing.

Item 2 -- oversized, subtract the staging write. Not subtracted, and the count the verdict used is why.

The subtraction was reasoned from staged_package_preview having 2 callers that "both only refuse". That count is right and the conclusion does not follow, because what the two callers refuse is not the same thing and neither refusal is about validation:

  1. member_dashboard's ?preview=1 refuses because a STAGED page has no reader -- the hosted page draws a BOUND artifact, and staging writes neither artifact nor binding.
  2. agent_panel._apply_staged_package refuses because BINDING one would leave dashboard_write refusing every agentic field for that crewmate (package.from_package, still live in agent_panel.py), with no agent verb back.

Those are two different missing pieces, and the second is a write guard rather than a renderer. #19335 landed the reader and did not lift that guard -- it touched no line of agent_panel.py -- so the data loss buluoray's review named is still exactly as real as it was. Deleting the staging write would not make the apply safe; it would delete the only thing standing between an agent and that loss.

What the staging write buys that returning a verdict does not. The suggested subtraction -- return canonical_package_content's verdict plus the counts, delete the staging and both refusals -- changes the verb from "offer a page" to "check a page". Three things go with it:

  • The apply contract. dashboard_apply takes no arguments on purpose, so what lands is what was staged. That is only true because a page is written down. A save that returns a verdict leaves the composed bytes in the agent's head, and the only way to apply them is to send them again at apply time -- which is the shape the gate exists to prevent, because the thing applied can then differ from the thing described.
  • One question at a time. The shared staging file is what makes "keep this one" name something. Two pages offered at once has no answer.
  • The bytes identity. Staging the canonical bytes means the page counted, the page described and the page a later apply commits are one string across two cycles. A verdict-only save gives the next cycle nothing to be identical to.

Clears-when, answered against the second clause rather than the first: the verdict offered "or this base has a counted consumer that reads a staged package instead of refusing it." It does not, and I have not invented one. What I can report is that the consumer the staging write was composing toward is no longer hypothetical -- it is on main, reading bound packages today, and the remaining gap is one guard in one file.

Item 10 -- a forged staged_ms answers "stage again" instead of a 500. Undeclared, and that is my error. It is in the Not-a-goal section of the description now. It is the shared _preview_payload doing the schema and expiry check for both readers, so a staged file that will not parse is stale for the package reader exactly as it already was for the template reader. test_dashboard_tools.py pins both answering None on a forged staged_ms.

Item 9 -- the surrogate 400, rides along. Agreed as characterised, and it stays: _validate_content is the first call in create and update and it measured content by encoding it, so content that cannot be encoded raised UnicodeEncodeError where every caller promises ArtifactValidationError. Fixing it for one route and leaving create, update and settle_blank crashing for every other kind would be the narrower change and the worse one.

Also on this head, from Joe's review: a root session could not save at all. _resolve_dashboard_caller answers one with a slug instance.session_instance_key already spelled session:<digest>, which is itself one of the two bindings the grammar accepts, and _page_binding prefixed it into crewmate:session:<digest> -- refused, 400 invalid_package, with no way out for the agent since the schema refuses a caller-sent bound_to. _page_binding now keys on instance.is_session_key and returns a session slug unchanged. test_a_root_session_save_stages_under_its_own_binding was written first and reproduced that 400.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the Design Review CONCERNS at head c5a8e386f2343eddf7ed1a3d08ce559d530643ad. Both Watch items are answered from the code; the Suggestion is fixed.

Correcting the claim both of these were read against. The PR description said #19335 was "stacked on this PR" and would "lift this refusal". That was wrong and it is gone. #19335 merged into main independently as 41e2929a2c, this PR is self-contained on main, and lifting the refusal is a third change that neither PR contains. The description now carries that as a "Merge order: none" paragraph.

That merge also changed what is true about drawing, so the prose this verdict quoted has been rewritten rather than defended. Main now DOES draw a bound composed package -- member_dashboard._bound_package_slug resolves crewmate:<slug> and _serve_package returns rendered_html. So "nothing draws a composed package" was false on the new base, and every copy of it is gone. The two refusals stand on their real, separate reasons, which the code and the text now name:

  • the ?preview=1 read, because a STAGED page is neither an artifact nor a binding: the hosted page reads a bound artifact, and _preview_record goes through staged_preview, which answers None for a package payload;
  • dashboard_apply, because binding one leaves dashboard_write refusing every agentic field for that caller (agent_panel.py package.from_package) with no agent verb back. The hosted page landed without that guard being lifted, so the loss buluoray named still stands.

Watch 1 -- a save stops the template flow. Real, and kept deliberately; the "clears when" alternative is the one thing this PR must not do. Taking a second staging file is what makes two pages offered at once, and "keep this one" then names neither -- the shared file is the mechanism that makes dashboard_apply take no arguments, which is the property the whole gate rests on. What the verdict got right is the way back, and that was undocumented. It now is: the next sentence and the tool description both say the staged page expires and a stale one has to be saved again, and dashboard_preview of a template overwrites the same file, so staging a template IS the way back. The window is MAX_PREVIEW_AGE_MS, 30 minutes, which the route passes through rather than restating.

The consequence is also smaller than the verdict reads. A template apply is refused only while a package sits in the file, and the refusal is a plain read that discards nothing -- test_a_second_apply_of_a_staged_package_is_refused_the_same_way pins that the staged page survives being refused, and test_an_apply_with_nothing_staged_writes_nothing pins the template path unchanged. Nothing a person is looking at moves in either case.

Watch 2 -- the prompt teaches an ask-first step for something a person cannot see. The contradiction was real and the ask-first step is what went, not the save. The member prompt and the tool text no longer tell an agent to ask before saving a composed page: a save changes nothing a reader can see, so there is nothing to ask permission for. What they now say is to DESCRIBE a staged page in words -- its fields and its blocks -- and that there is no link and no apply on this build. The ask-first instruction stays where it is still true, on the template dashboard_preview / dashboard_apply cycle, which this PR does not touch.

Suggestion -- the api_dashboard_save docstring. Fixed. It no longer says the body "hands back the link a person opens" or that dashboard_apply "installs it, after they say yes". It now states both refusals and their separate reasons, so the next editor has the reason in front of them rather than a sentence inviting the link back. PackagePreview.wire's docstring says the same for the dropped preview_url key.

Tests on this head: 27 in test_dashboard_save_tool.py, 56 in test_member_dashboard_routes.py, plus test_agent_panel_routes.py (133), test_dashboard_tools.py (67), test_member_prompt.py (79), test_context_composition_contract.py (123) and the hosted-page suites main carries (test_dashboard_package_owner_gate.py 78, test_dashboard_package_html_view.py 26, test_dashboard_frame_subscribe.py 31).

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the First Principles CONCERNS at head c5a8e386f2343eddf7ed1a3d08ce559d530643ad.

The premise the verdict rests on has changed, and I am not arguing against it -- I am reporting that main moved. The verdict's own words were that the renderer is "in no open PR". It is now in MAIN: #19335 merged as 41e2929a2c, member_dashboard._bound_package_slug resolves crewmate:<slug>, and _serve_package returns rendered_html for a bound kind="dashboard" artifact. So the staged page is no longer composing toward something nobody is building, and the description's claim that the renderer was absent has been corrected rather than left standing.

Item 2 -- oversized, subtract the staging write. Not subtracted, and the count the verdict used is why.

The subtraction was reasoned from staged_package_preview having 2 callers that "both only refuse". That count is right and the conclusion does not follow, because what the two callers refuse is not the same thing and neither refusal is about validation:

  1. member_dashboard's ?preview=1 refuses because a STAGED page has no reader -- the hosted page draws a BOUND artifact, and staging writes neither artifact nor binding.
  2. agent_panel._apply_staged_package refuses because BINDING one would leave dashboard_write refusing every agentic field for that caller (package.from_package, still live in agent_panel.py), with no agent verb back.

Those are two different missing pieces, and the second is a write guard rather than a renderer. The hosted page landed and that guard was not lifted with it -- #19335 touched no line of agent_panel.py -- so the data loss buluoray's review named is still exactly as real as it was. Deleting the staging write would not make the apply safe; it would delete the only thing standing between an agent and that loss.

What the staging write buys that returning a verdict does not. The suggested subtraction -- return canonical_package_content's verdict plus the counts, delete the staging and both refusals -- changes the verb from "offer a page" to "check a page". Three things go with it:

  • The apply contract. dashboard_apply takes no arguments on purpose, so what lands is what was staged. That is only true because a page is written down. A save that returns a verdict leaves the composed bytes in the agent's head, and the only way to apply them is to send them again at apply time -- which is the shape the gate exists to prevent, because the thing applied can then differ from the thing described.
  • One question at a time. The shared staging file is what makes "keep this one" name something. Two pages offered at once has no answer.
  • The bytes identity. Staging the canonical bytes means the page counted, the page described and the page a later apply commits are one string across two cycles. A verdict-only save gives the next cycle nothing to be identical to.

Clears-when, answered against the second clause rather than the first: the verdict offered "or this base has a counted consumer that reads a staged package instead of refusing it." It does not, and I have not invented one. What I can report is that the consumer the staging write was composing toward is no longer hypothetical -- it is on main, reading bound packages today, and the remaining gap is one guard in one file.

Item 10 -- a forged staged_ms answers "stage again" instead of a 500. Undeclared, and that is my error. It is in the Not-a-goal section of the description now. It is the shared _preview_payload doing the schema and expiry check for both readers, so a staged file that will not parse is stale for the package reader exactly as it already was for the template reader. test_dashboard_tools.py pins both answering None on a forged staged_ms.

Item 9 -- the surrogate 400, rides along. Agreed as characterised, and it stays: _validate_content is the first call in create and update and it measured content by encoding it, so content that cannot be encoded raised UnicodeEncodeError where every caller promises ArtifactValidationError. Fixing it for one route and leaving create, update and settle_blank crashing for every other kind would be the narrower change and the worse one.

Also on this head, from Joe's review: a root session could not save at all. _resolve_dashboard_caller answers one with a slug instance.session_instance_key already spelled session:<digest>, which is itself one of the two bindings the grammar accepts, and _page_binding prefixed it into crewmate:session:<digest> -- refused, 400 invalid_package, with no way out for the agent since the schema refuses a caller-sent bound_to. _page_binding now keys on instance.is_session_key and returns a session slug unchanged. test_a_root_session_save_stages_under_its_own_binding was written first and reproduced that 400.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the Design CONCERNS at head 33576977fcc14c96e767d1e926c42ba714d271d4.

Watch 2 -- the description was cut off before ## Backwards compatibility, so the take-away check could not run. FIXED. The section sat at byte 11721 of a 17068-byte body, past the 8000-byte capture window. The body is now 13499 bytes with ## Backwards compatibility at byte 7909, inside the window, so the next run reads the reader list rather than guessing at it. Nothing in that section's content changed -- the trimming came out of the Problem and What-changed prose, which had grown repetitive across review rounds.

Watch 1 -- saving destroys a template preview that still works. The chain is right, and I am not going to argue it away.

I defended the shared staging file on the previous head with "one question at a time", and the rebuttal is correct: that argument assumes both kinds of staged page can be applied, and on this build the package cannot. So the trade is not symmetrical. Walking the chain against the code:

  • instance.stage_package_preview writes _preview_path(slug), the same file stage_preview writes for a template.
  • member_dashboard._serve asks staged_package_preview BEFORE _preview_record, so once a package is in the file the template's own ?preview=1 answers 409.
  • agent_panel._apply_staged_package runs before the template apply for the same reason, so the apply answers 409 too.
  • Neither path tells the person the template they were about to approve is the thing that went.

That is a real loss of someone's pending content, not a scope preference, and it is the one class I should not ship on my own judgement. It is also not mine to decide, because the fix the verdict names -- validate-and-return-counts with no write, or a second staging file -- changes the shape a human reviewer already chose. buluoray's review settled this PR on "keep save and stage, refuse the apply", and the maintainer ruled it lands at that scope. An AI lane asking to delete the staging write reverses both, so it goes to the maintainer rather than into a quiet rewrite by me.

What I can say precisely, so the decision does not need re-derivation:

  • Option A, own staging file. _preview_path gains a package sibling; staged_package_preview and stage_package_preview read and write it; the two 409 branches stay exactly as they are. dashboard_preview -> dashboard_save -> dashboard_apply then applies the template. Cost: "one page offered at a time" stops holding across kinds, so a later change that makes a package applicable has to decide which of two staged pages an argument-free apply installs.
  • Option B, validate only. dashboard_save runs canonical_package_content plus the name scan and returns the counts; PackagePreview, stage_package_preview, staged_package_preview, _apply_staged_package and the read's 409 branch all go. Cost: the file format and the apply contract land with the reader instead, and dashboard_apply keeps taking no arguments only because nothing composed is ever staged.

Either clears this Watch. I have not picked one.

Suggestion -- the staged bytes have no reader on this build, so a validating save gives the same agent-facing behaviour. Correct as stated, and it is Option B above.

On the member prompt saying "nothing is stored" while a file is written. Fair, and the wording is now narrower everywhere an agent reads it: nothing is STORED means no kind="dashboard" artifact and no binding, which is the thing that would change what a reader sees. The staging file is not an artifact and is not drawn. If Option A or B lands this sentence gets simpler either way.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the First Principles CONCERNS at head 33576977fcc14c96e767d1e926c42ba714d271d4.

Item 3 -- undeclared: "Not a goal" said the template verbs "keep working exactly as they do today", while a save replaces a pending template preview. The contradiction was real and the claim is withdrawn. That bullet no longer says "exactly as they do today"; it says what is true, which is that dashboard_apply recognises a staged composed package and refuses it. Two other things that rode along are declared in the same section now rather than left for a reader to find: the lone-surrogate 400 across every artifact kind, and _preview_payload making a forged non-numeric staged_ms read as stale for both preview readers instead of raising.

Item 2 -- zero consumers. The measurement is right, and the conclusion is a scope decision I am not taking on my own.

The count is accurate: staged_package_preview has two callers, neither reads package_content, and the counts in the reply come from the package already in hand. Paired with the Design lane's chain -- dashboard_preview then dashboard_save loses the template the person was about to approve, with nothing telling them -- what the staging write buys on THIS base does not cover what it costs. My earlier defence of it leaned on "one question at a time", and that argument assumes a staged package can be applied here. It cannot. So I am not re-arguing it.

I am also not deleting it, for a reason that is about who decides rather than about the merits. buluoray's review settled this PR on "keep save and stage, refuse the apply", and the maintainer ruled it lands at that scope. The subtraction named here reverses both. A review lane and a named human reviewer disagreeing about deleting code is the case where the human's call stands until the human changes it, so this goes up rather than into a quiet rewrite by me.

To make that decision cheap, both exits priced from the code:

  • Delete the write (the subtraction as specified). canonical_package_content plus the name scan stay and the route returns the counts. Out: PackagePreview, stage_package_preview, staged_package_preview, _apply_staged_package, the ?preview=1 package branch, and the _preview_payload split goes back to serving one reader. Items 1 and 6-9 keep working untouched -- test_a_save_stages_the_page_and_stores_nothing becomes an assertion about the reply alone, and the five refusal tests that assert the store stayed empty do not change at all. The apply contract and the file format then land with the reader.
  • Keep the write, give it its own file. _preview_path gains a package sibling, the two 409 branches stay as they are, and dashboard_preview -> dashboard_save -> dashboard_apply applies the template. This clears the Design Watch and leaves item 2 as you have scored it: a write with no reader on this base, justified only by the change that adds one.

Item 8 -- the surrogate 400 rides along, and the save path already refuses surrogates via _refuse_lone_surrogates. Both true. It stays because _validate_content is where the promise is made: it is the first call in create and update and it measures content by encoding it, so content that cannot be encoded raised UnicodeEncodeError where every caller's contract says ArtifactValidationError. Leaving create, update and settle_blank crashing for every other kind, so that one route's own earlier scan carries it, is the narrower change and the worse one. It is declared in Not-a-goal rather than presented as part of the feature.

Item 9 -- the forged staged_ms. Declared, as above. It is the shared _preview_payload doing the schema and expiry check for both readers, so an unparseable staged file is stale for the package reader exactly as it already was for the template reader; test_dashboard_tools.py pins both answering None.

A crewmate could declare a dashboard's Model, View and theme and had
nowhere to put them: the panel server held no save verb, so the prompts
that tell an agent to save a page named a call that did not exist, and
the reader on the base branch had no writer to serve.

dashboard_save takes those three declarations and stores them as an
artifact of kind="dashboard" bound to the calling crewmate. The binding
is derived from the caller the gateway vetted and is never read from the
body, so a caller that sends bound_to or kind is refused rather than
corrected. Identity reuses dashboard_write's own gate -- strict session
resolution on the tool side, _resolve_dashboard_caller on the route
side -- and the lookup reuses the read path's resolve_bound_slug, so the
write and the read cannot disagree about which artifact is a crewmate's.

One crewmate keeps one package. A lookup that cannot prove whether a
package exists refuses the save, and a per-binding lock spans the lookup
and the write, because the store locks writes individually and two
overlapping first saves would otherwise both read absent and both
create. Everything the save does on a thread stays there: the store is
built inside the worker, and the history session is resolved on the
update branch that needs it rather than on the gateway loop, where its
succession-chain walk reads the crew log.

Validation stays the store's, for every caller rather than this one.
That needed a fix one level down: _validate_content measures content by
encoding it, and content holding an unpaired surrogate cannot be encoded
at all, so the line asking how big the content is also decides whether it
can exist. It now refuses such content as an ArtifactValidationError,
which gives create, update and settle_blank the refusal a caller can act
on instead of a crash.

No WebSocket frame is sent: nothing subscribes to the instance-changed
frame, so the tab picks a save up on its own poll.

Naming the verb in the grant tuple obliges naming it in the member
briefing's item 7, which a test reads off that tuple; the prompt byte
pins move with it, and the dynamic-dashboard feature-map row gains the
write path, its endpoint and the one-package-per-crewmate rule.
dashboard_save stored the package, and the binding it writes IS what decides
whose dashboard a page is. So composing a page WAS installing it: durable state
changed on the agent's say-so, dashboard_write started refusing that crewmate's
fields with package_display_pending, and when the display learns to read
packages the page goes live retroactively without anyone having said yes. The
template path next to it has had the opposite shape all along --
dashboard_preview stages, dashboard_apply installs, and the prompt tells a
crewmate to show the link and ask first.

The save now stages. It runs the artifact store's own write gate,
canonical_package_content, and puts the resulting bytes in the staging file
beside the crewmate's record; the reply carries the ?preview=1 link, the field
and block counts, and the sentence saying what to do with them. A save
broadcasts nothing, because nothing a reader can see has moved.

Checking at STAGING rather than at apply is stage_preview's own reason: a
layout that could never be stored is the agent's to fix while it is still
composing, not something to discover after a person has said yes. Staging the
canonical bytes rather than the declarations is the other half -- the page shown
and the page committed are then one string across the two cycles.

ONE STAGING FILE for both kinds, so one page is offered at a time and "keep this
one" names something. Both readers answer None for the other's payload: a
package carries no html and no manifest, and staged_package_preview wants a
package_content key. The schema check and the expiry window they share move to
_preview_payload, so a stale preview is stale for both.

dashboard_apply is the only writer of the package artifact, and SELECTION,
COMMIT AND DISCARD ARE ONE CLAIM under the staging lock
(instance.claim_package_preview), with the store's per-binding lock nested
inside it. Two locks because they answer two questions and dropping either loses
something: the staging lock makes the page committed the page that was staged,
the per-binding lock makes one crewmate keep one artifact. Reading the staged
page outside the staging lock would be a data loss rather than a stale read -- a
save landing during the artifact write stages a second page, and a discard that
followed the commit would delete THAT page, unstored, with the agent already
told its compose had succeeded. A refusal raised out of the claim leaves the
staged page ALONE, which is what a failed commit needs: the page is still the one
the person approved and the retry has something to commit. The lock is pinned by
a non-blocking probe on the lock file from inside store.create, so no timing
decides the pass.

EVERY NAME A PACKAGE DECLARES IS A JOIN KEY, and the theme tokens are the set
whose grammar hides that. A field name and a block id match
[a-z][a-z0-9_]{0,63}, which no real token survives; a theme token is a CSS
custom property, --[a-z][a-z0-9-]{0,63}, and a lowercase hyphenated look-alike
satisfies it. _credential_shaped_names now scans all three, because the page's
own style references the variable by name -- a redactor rewriting it hands back a
stylesheet pointing at a property that does not exist, so there is no masked form
that still works and refusal is the only answer. The refusal reports a POSITION,
never the name, as the sibling refusals do.

The ?preview=1 read answers a staged package through the same owner-gated route.
It answers the DECLARATIONS rather than a drawn page, which is this base's limit
and not a choice: nothing here renders a package into a document yet, so a body
promising rendered_html would promise a key it cannot fill. instance_version
stays 0 because staging wrote no version.

Its prose goes through the redactor and its KEYS are kept verbatim, which is one
decision rather than two: a declaration is a name, not a value, so redacting it
hides nothing and breaks the document -- the reference stays while the key moves.
_page_safe, the redactor for resolved values, is wrong here for that reason and
for a sharper one: it drops worker_session_key at any depth, so a model field an
agent may legitimately declare under that name would vanish while the block
reading it kept the reference. What keeps a credential out of a key is the save
refusing one, which is the single mechanism and sits where a name can still be
changed; a staged page expires after MAX_PREVIEW_AGE_MS, so no long-lived file
predates that refusal.

A staged package whose bound_to is not the caller's is refused -- at the apply
and on the read -- rather than re-stamped. Re-stamping would change the page
after it was approved, and the binding is the authorization decision.

package_display_pending survives and moves with the write: it is an APPLIED page
whose fields cannot be written yet, so a page left staged refuses nothing. The
save tool's description, its reply and the member briefing's item 7 say staged
rather than stored, the apply tool names both kinds of staged page, and the
prompt byte pins move with them.

Rebased onto the amended base, which moved two things under this branch. The
system spec's save paragraph said the save stores and holds the per-binding lock
across the write; it now describes the staging gate, the apply as the only
writer, and the two locks. And the base dropped the binding lookup's
unreadable_record_count consultation on purpose -- a record the listing never
showed no longer raises BindingLookupIncomplete, because one corrupt file must
not take a library down -- so the test pinning that refusal goes with it, along
with the stub members it was the only caller of.

The apply's frame goes through _broadcast_changed, which the base's rebase onto
main introduced beside it: a crewmate's page is named by its SLUG, and a caller
bound to no crew is named by its SLOT on an owner-only socket. Broadcasting the
slug directly would have sent a root session's change under an empty slug.

The declared-name refusal is asked at BOTH ends, and the predicate moved to the
read's module so there is one of it. A staged page is an ordinary file under
members/<slug>/dashboard/, so the save route is not its only writer: a read that
trusted the save's refusal would be guarding nothing against a file written
directly, which a prompt-injected agent can produce. The read now refuses WHOLE
on it, as the live package read does, because a join key has no masked form that
still works. package_declared_name_spots lives in member_dashboard because that
is the side that cannot delegate, and agent_panel imports it inside the function
the way it already imports read_fields -- member_dashboard imports nothing from
agent_panel, so the pair stays acyclic.

That empties agent_panel's own redactor use, so the NON_EGRESS_REDACTION_MODULES
entry added for it goes too: it named a call that is no longer there, and the
posture allowlist refuses a stale entry. member_dashboard is already a
registered redaction surface.

The staged bytes go through the package's own validator rather than a shape
check of mine. A name scan covers the name sets it knows about; it cannot cover
a key nobody declared, so a credential-shaped key sitting beside a field's own
`type` reached the response, and a `model` with no `types` reached a KeyError and
a 500. PackagePreview.package() now returns parse_package's canonical form or
None, which answers both in one place and for every reader of the preview.

The per-binding lock is gone. It only ever ran inside claim_package_preview's
exclusive lock on instance_dir(slug), and `crewmate:<slug>` names the same
crewmate that directory does -- so it was the same key twice, not two guarantees.
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the Design CONCERNS at head 2877b4dfa2496df06cdaf6d13380dc9a98bc6059.

Watch 2 -- the description was cut off before ## Backwards compatibility, so the take-away check could not run. FIXED. The section sat at byte 11721 of a 17068-byte body, past the 8000-byte capture window. The body is now 13499 bytes with ## Backwards compatibility at byte 7909, inside the window, so the next run reads the reader list rather than guessing at it. Nothing in that section's content changed -- the trimming came out of the Problem and What-changed prose, which had grown repetitive across review rounds.

Watch 1 -- saving destroys a template preview that still works. The chain is right, and I am not going to argue it away.

I defended the shared staging file on the previous head with "one question at a time", and the rebuttal is correct: that argument assumes both kinds of staged page can be applied, and on this build the package cannot. So the trade is not symmetrical. Walking the chain against the code:

  • instance.stage_package_preview writes _preview_path(slug), the same file stage_preview writes for a template.
  • member_dashboard._serve asks staged_package_preview BEFORE _preview_record, so once a package is in the file the template's own ?preview=1 answers 409.
  • agent_panel._apply_staged_package runs before the template apply for the same reason, so the apply answers 409 too.
  • Neither path tells the person the template they were about to approve is the thing that went.

That is a real loss of someone's pending content, not a scope preference, and it is the one class I should not ship on my own judgement. It is also not mine to decide, because the fix the verdict names -- validate-and-return-counts with no write, or a second staging file -- changes the shape a human reviewer already chose. buluoray's review settled this PR on "keep save and stage, refuse the apply", and the maintainer ruled it lands at that scope. An AI lane asking to delete the staging write reverses both, so it goes to the maintainer rather than into a quiet rewrite by me.

What I can say precisely, so the decision does not need re-derivation:

  • Option A, own staging file. _preview_path gains a package sibling; staged_package_preview and stage_package_preview read and write it; the two 409 branches stay exactly as they are. dashboard_preview -> dashboard_save -> dashboard_apply then applies the template. Cost: "one page offered at a time" stops holding across kinds, so a later change that makes a package applicable has to decide which of two staged pages an argument-free apply installs.
  • Option B, validate only. dashboard_save runs canonical_package_content plus the name scan and returns the counts; PackagePreview, stage_package_preview, staged_package_preview, _apply_staged_package and the read's 409 branch all go. Cost: the file format and the apply contract land with the reader instead, and dashboard_apply keeps taking no arguments only because nothing composed is ever staged.

Either clears this Watch. I have not picked one.

Suggestion -- the staged bytes have no reader on this build, so a validating save gives the same agent-facing behaviour. Correct as stated, and it is Option B above.

On the member prompt saying "nothing is stored" while a file is written. Fair, and the wording is now narrower everywhere an agent reads it: nothing is STORED means no kind="dashboard" artifact and no binding, which is the thing that would change what a reader sees. The staging file is not an artifact and is not drawn. If Option A or B lands this sentence gets simpler either way.

@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Disposition for the First Principles CONCERNS at head 2877b4dfa2496df06cdaf6d13380dc9a98bc6059.

Item 3 -- undeclared: "Not a goal" said the template verbs "keep working exactly as they do today", while a save replaces a pending template preview. The contradiction was real and the claim is withdrawn. That bullet no longer says "exactly as they do today"; it says what is true, which is that dashboard_apply recognises a staged composed package and refuses it. Two other things that rode along are declared in the same section now rather than left for a reader to find: the lone-surrogate 400 across every artifact kind, and _preview_payload making a forged non-numeric staged_ms read as stale for both preview readers instead of raising.

Item 2 -- zero consumers. The measurement is right, and the conclusion is a scope decision I am not taking on my own.

The count is accurate: staged_package_preview has two callers, neither reads package_content, and the counts in the reply come from the package already in hand. Paired with the Design lane's chain -- dashboard_preview then dashboard_save loses the template the person was about to approve, with nothing telling them -- what the staging write buys on THIS base does not cover what it costs. My earlier defence of it leaned on "one question at a time", and that argument assumes a staged package can be applied here. It cannot. So I am not re-arguing it.

I am also not deleting it, for a reason that is about who decides rather than about the merits. buluoray's review settled this PR on "keep save and stage, refuse the apply", and the maintainer ruled it lands at that scope. The subtraction named here reverses both. A review lane and a named human reviewer disagreeing about deleting code is the case where the human's call stands until the human changes it, so this goes up rather than into a quiet rewrite by me.

To make that decision cheap, both exits priced from the code:

  • Delete the write (the subtraction as specified). canonical_package_content plus the name scan stay and the route returns the counts. Out: PackagePreview, stage_package_preview, staged_package_preview, _apply_staged_package, the ?preview=1 package branch, and the _preview_payload split goes back to serving one reader. Items 1 and 6-9 keep working untouched -- test_a_save_stages_the_page_and_stores_nothing becomes an assertion about the reply alone, and the five refusal tests that assert the store stayed empty do not change at all. The apply contract and the file format then land with the reader.
  • Keep the write, give it its own file. _preview_path gains a package sibling, the two 409 branches stay as they are, and dashboard_preview -> dashboard_save -> dashboard_apply applies the template. This clears the Design Watch and leaves item 2 as you have scored it: a write with no reader on this base, justified only by the change that adds one.

Item 8 -- the surrogate 400 rides along, and the save path already refuses surrogates via _refuse_lone_surrogates. Both true. It stays because _validate_content is where the promise is made: it is the first call in create and update and it measures content by encoding it, so content that cannot be encoded raised UnicodeEncodeError where every caller's contract says ArtifactValidationError. Leaving create, update and settle_blank crashing for every other kind, so that one route's own earlier scan carries it, is the narrower change and the worse one. It is declared in Not-a-goal rather than presented as part of the feature.

Item 9 -- the forged staged_ms. Declared, as above. It is the shared _preview_payload doing the schema and expiry check for both readers, so an unparseable staged file is stale for the package reader exactly as it already was for the template reader; test_dashboard_tools.py pins both answering None.

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.

3 participants