Skip to content

feat: add portable project bundles - #7181

Closed
kyleseaman wants to merge 1 commit into
mainfrom
feat/project-bundles
Closed

kyleseaman wants to merge 1 commit into
mainfrom
feat/project-bundles

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A Crew session today is pointed at one directory. There is no first-class way to say "this session is about the Payments Platform" and have the agent get the whole picture: which repositories belong together, which agents, skills and MCP servers that body of work carries, and how to pick it all up again on a second machine. The Projects RFC (docs/request-for-change/rfc-crew-projects.md) describes that primitive; nothing on main implements it.

Why it matters

Without a portable Project, every session starts from one folder and the user re-explains the shape of the work each time. Team members cannot share a Crew setup for a body of work, and an agent cannot reason about work that spans more than one repository. Projects turn that into a small, syncable manifest.

What changed (motivation → approach → change)

A Project is a project.yaml bundle with a stable identity and no user identity, loaded from a local folder or a managed Git clone. It declares repositories, context selectors, agents, skills and MCP servers. Only the manifest is portable; clones, caches and materialized capabilities are derived state rebuilt per install.

Projects live under Agent Capabilities → Projects (website/src/pages/ProjectBundlesPage.tsx): list, detail, create, add-from-folder-or-Git, sync and remove. A Project can be picked when creating a session (ChatSidebar create menu) and the session shows the Project name while the agent resolves the full multi-repository workspace. Session-to-Project identity is a first-class slot field (project_id), persisted with the slot and restored on both restart paths.

Bundle content is inert until the owner reviews and trusts it. Trust binds to a content digest over repo declarations, context selectors, agent JSON, skill trees and MCP JSON; the review shows agent names and the exact MCP commands, arguments and URLs before a separate confirmation. A sync that changes that digest withdraws the active materialization until the owner re-reviews. Materialization is namespaced and Project MCP entries carry provenance, so removing a Project reclaims exactly what it installed and a configuration-equal entry the owner keeps loses only its Project provenance. Every Project authorization decision is SEL-audited (docs/system-specs/modules/sel.md).

Every failed Project request, manifest load or list load renders through ErrorNotice, so the structured error context and the agent hand-off survive; the hand-off is on everywhere except beside the create/add form's unsaved fields. In the sidebar's create menu a failed Project session create reports through the menu's shared new-chat notice, and a failed Project list read renders as the in-menu passive notice with its sibling hand-off row instead of silently dropping the Projects section.

One layout change rides along: SidePanelLayout.requestTab makes re-clicking the already-active Capabilities tab a no-op. setTab drops the pane's sub-selection when it rewrites the URL, and the Projects tab keeps the selected project in that sub-selection, so a re-click used to throw the user out of the project they were looking at. The guard applies to every tab of the layout.

flowchart LR
  subgraph Before
    A1[New session]:::ctx --> B1[one directory]:::ctx --> C1[agent turn]:::ctx
  end
  subgraph After
    A2[New session]:::ctx --> P[Project picker]:::added --> M[project.yaml]:::added
    M --> R[multi-repo workspace]:::added --> C2[agent turn]:::ctx
    M -. owner trust .-> K[agents · skills · MCP]:::added
  end
  classDef added fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px
  classDef changed fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px
  classDef removed fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D,stroke-dasharray:4 3
  classDef ctx fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E
Loading

🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged

A session can now start from a Project; the manifest resolves the repositories, and the owner's trust gate decides whether its agents, skills and MCP servers are installed.

Safety properties the diff pins:

  • Manifests reject credentials, embedded grants, sensitive Git paths, network file:// authorities, path escapes, links, hardlink aliases, recursive YAML and alias-amplified documents; relative repo paths resolve against the declaring bundle before both the security decision and the Git clone; a remote manifest's blob size is preflighted before buffering.
  • Manifest and bundle-owned executable JSON are read through descriptor-pinned or opened-handle-validated reads; skill trees are staged through pinned_fs under a byte ceiling that is fatal for Project activation.
  • Project briefs are redacted for credentials and exfiltration URLs before reaching model context, dropped and audited when they match prompt-injection screening, and have structural markers neutralized otherwise. The brief's own fence markers, [PROJECT BRIEF —] and [END PROJECT BRIEF], join the set of structural markers the context builder rewrites to [marker-removed] in every scanned user-supplied string, so no message or file can forge the fence that marks the brief as background reference. Project MCP revocation is reconciled inside the final rendered-config lock.
  • Attachment failures are redacted before dashboard JSON, logs and persisted session errors; only canonical persisted Project UUIDs are accepted; malformed persisted ids are rejected on both restore paths; corrupt activation state and registry path loops fail closed.
  • A workspace or project switch on an attached session clears the Project identity and marks the slot for the periodic flush, so a detach reaches disk before the next message.
  • No in-app manifest replacement endpoint ships until the filesystem destination can be updated with a true atomic compare-and-swap; editing stays a file-and-Git workflow applied by sync or remove/re-add.
  • The legacy Task Runner /api/projects contract is preserved; local credentials and install identity never enter the portable manifest.

Tests

  • Backend Project suites (test/test_project_*.py, test/test_chat_slot_project.py, test/test_pinned_staging.py, handler coverage): manifest validation and rejection classes, Git transport trust, trust digest and withdrawal-on-sync, namespaced materialization and provenance-aware removal, session attach/refresh/detach including the persisted project_id restore paths, redaction of briefs and failures, SEL audit-or-deny ordering, and the byte-bounded pinned skill copy.
  • Frontend (ProjectBundlesPage.test.tsx, CapabilitiesPage.projects.test.tsx, ChatSidebar.createMenu.test.tsx, ChatInput.projectBranch.test.tsx): list/detail/create/add/sync/remove flows, error surfaces, create-session-from-Project carrying the Project identity in the request, and the sidebar create menu.
  • Playwright (website/playwright/project-bundles.spec.ts): external Git edit → Project sync → trust → multi-repo session, offline against the stub ACP backend. The harness enables agent.sandbox_allow_unsandboxed_exec in its throwaway CI home (_allow_ephemeral_unsandboxed_exec in test/test_playwright_e2e.py) so the Git-backed flow can spawn git on a runner with no OS sandbox backend; the key pre-exists, and the opt-in is scope-pinned by its own test.
  • Local run at this head: full backend suite 98,647 passed with the only failures being host-environment tests that fail identically on origin/main (userns/ssh/jq-dependent); full frontend suite 2,024 files / 32,174 tests passed; mypy, black, isort, flake8, tsc, eslint, i18n check and render, jscpd, bundle-size, docs lint, feature-map, harness-parity and the policy gates passed.

Manual verification

Real-gateway Chromium run of the Project flow (create → trust → new session → multi-repo workspace) passed; the screenshots below are from that run.

Screenshots / video

Projects in Agent Capabilities Project details
Projects list Project details
Reviewed capabilities active Project attached to a session
Active Project capabilities Project session
More

New session from Project menu
Project removed

Related Issues

no linked issue: this feature implements the merged Projects RFC (#4941); #3551 (project-level .kiro/ config) is related context and is not closed by it.

This lands as one vertical feature PR on purpose: splitting the manifest, the trust boundary, the session contract and the UI would leave partial states that are not independently useful or safe to ship. CHANGELOG.md is intentionally untouched; release notes stay release-PR owned. The two open repository-wide Dependabot alerts are transitive development dependencies inherited from the base lockfile, handled in #7766 and #7767; this PR does not modify dependency manifests.

Checklist

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

@kyleseaman
kyleseaman requested review from a team and dwu96 August 31, 2026 02:37
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Aug 31, 2026
@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — 🔴 changes requested (blocking)

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

This comment is updated in place on each push.

BLOCKING -- src/kiro_crew/project_registry.py:72 -- Agent can rewrite Project attachment authority
registry_dir = registry_dir or home / "trust" / "project-registry"
Runtime-constructed write under sandbox-visible trust/ -> per-turn registry resolution -> session silently switches to an attacker-selected bundle/workspace.
Anchor: residual/security
Fix: Move the registry to a dedicated top-level leaf covered by _CREW_SECRET_LEAVES and _CREW_HIDDEN_LEAVES.
[BLOCK-MERGE] 944310c
[GPT-REVIEWED] 944310c

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

I've examined the code. Here is my ruling.

trust is a _CREW_SANDBOX_VISIBLE_LEAVES entry (sandbox.py:438) — deliberately NOT bind-masked at the OS layer, so in-sandbox readers (sel key, project-skills, cron store) work. It is also in _SENSITIVE_HOME_DIRS (paths.py:363), but per the keystone doctrine that only fences the tool gate, not a spawned open(). The new trust/project-registry/registry.json (project_registry.py:72) is a sub-leaf nested under the VISIBLE trust/ tree, so it carries no OS fence and a spawned shell can write it. The reader validates structure but a well-formed malicious registry passes.

For FLAG I must show the reaching conditions are so extreme a human would accept the residual. They are not: the required condition is an ordinary spawned-shell write to a VISIBLE leaf — precisely the primary bypass the doctrine treats as the baseline threat, not a mutually-contradicting or writer-impossible one. The suggested remedy (a dedicated hidden/secret top-level leaf) is bounded and standard. I cannot complete the rarity record, so the fenced verdict stands.

[ADJUDICATION] 944310c total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 944310c

[ADJUDICATION-FENCED] 944310c fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/project_registry.py:72 -- Registry nests under the VISIBLE trust/ tree with no OS fence, so an ordinary spawned-shell write (the doctrine's baseline threat, not an extreme condition) can repoint project attachments; rarity record cannot be completed.
[GPT-ADJUDICATED-FENCED] 944310c

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

@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — 🟡 CONCERNS

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

All evidence is reconciled: the blind read, all six screenshots, the diff, and the PR text. Both project-detail screenshots crop above the trust/sync/remove controls, which drives the verdict below.

UX-Verdict: CONCERNS

The flow reads well blind, but the feature's pivotal "Trust and activate" control and both confirm dialogs appear in no screenshot, and Add vs Create are indistinguishable.

Watch

  • "Add project" vs "Create project" (list header, ProjectBundlesPage.tsx): the blind reader said "from the buttons alone I could not tell which to press" — the disambiguating help lines render only after clicking into a form. Every first-time user's first decision on the page, recoverable but repeated until learned. Fix: rename to "Add existing project", or surface each button's help string as its title.
  • Inactive→Active capability states: the reader who saw both said "I'd be careful; I don't remember turning this on", and on the Inactive card "I don't see an obvious switch to click here" — capabilities_inactive_help says "Review the Project before activating" but never names the control. Fix: end it with "…then choose Trust and activate below."

Evidence gaps

  • "Trust and activate"/"Deactivate capabilities" button and the "Trust and activate this project?" dialog — shots 2 and 3 crop above them; add a screenshot of the button and the open dialog.
  • Create and Add forms (Project name, Project folder, Folder or Git URL fields) — no screenshot shows either form.
  • "Sync project"/"Project synced.", the unhealthy "Retry sync" state, and "Remove from KiroCrew" plus its confirm dialog — none screenshotted.

Suggestions

  • activate_project_body tells the user to review "the agent names and exact MCP commands or URLs shown on this page" while the modal occludes that page — put the names/commands summary in the dialog body itself.

[UX-REVIEWED] 944310c

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Aug 31, 2026
@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 944310c1722ebd4e0720dbbb55ccd29ef49af718 — 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.

All evidence is in. Every substantive item traces to the pre-existing RFC (a recorded decision), specs were updated in the same commit, no pins were deleted or loosened, and the security items each sit on a named boundary. Two small pieces of dead surface survive the kill-filter, both verified by my own reads: copy_file_pinned's new refusal= parameter is never used in the function body, and resolve_source's remote=None default is a permissive branch no production caller takes.

First-Principles-Verdict: CONCERNS

copy_file_pinned ships a refusal= parameter it never raises — dead surface with one passer that already raises for itself; delete it.

Not justified as shipped

  • Item 9 — rides along: the tab re-click guard is declared and its harm is named (a re-click dropped the selected project), but it is layout behavior, not Projects.
  • Item 10 — oversized: the staging ceilings are earned; the delta is the dead refusal= kwarg on copy_file_pinned (0 uses between pinned_fs.py:457–719; its 1 passer, stage_tree_pinned._file_skip, raises its own refusal).

What this change ships

Inventory (10 items) — 8 justified

Intent: let a user name a body of work as a portable Project bundle — repos, agents, skills, MCP servers — and start sessions from it anywhere. ADDITION, derived from the pre-existing rfc-crew-projects.md (doc-pr 4941, issue 3551).

  1. New Projects tab under Agent Capabilities: register, inspect, create, add from folder or Git, sync, remove — justified
  2. A session can be started from a Project; the composer chip shows the Project name and locks the workspace — justified
  3. Sessions remember their Project across restarts; a workspace switch detaches it and persists the detach — justified
  4. Bundle capabilities are inert until owner review; trust binds to a content digest, sync withdraws it, removal reclaims exactly what was installed, all SEL-audited — justified
  5. New kirocrew project CLI group (create/add/list/show/sync); deliberately no MCP twin — trust lifecycle stays operator-only per the agent-untrusted-of-its-own-ceiling boundary — justified
  6. New /api/project-bundles API (8 routes); legacy /api/projects task-runner routes preserved byte-compatible — justified
  7. A redacted, injection-screened Project brief joins first-turn model context; its fence markers join the neutralized-marker set — justified
  8. Windows Project Git resolves git.exe only from fixed trusted roots, never PATH, failing closed — justified
  9. Re-clicking the already-active Capabilities tab no longer discards the pane's sub-selection (applies to every tab) — rides along (declared, harm named)
  10. Project skill staging enforces byte/entry ceilings fatal to activation — oversized: dead refusal= param on copy_file_pinned

Capped at 10: omitted are the ConfirmDialog destructive-styling opt-out (1 consumer — the knob its own prior comment deferred until a consumer existed), the e2e harness's ephemeral sandbox opt-in (scope-pinned by its own test), spec updates, and i18n strings.

Watch

  • GitProjectStore.resolve_source(remote: str | None = None) (project_git.py:537): the None default skips provenance matching entirely, and the single production caller (project_sessions.py:119) always passes a str — a never-taken permissive branch. Clears when: remote is made required and the None branch deleted.

Subtractions

  • Delete refusal= from copy_file_pinned (pinned_fs.py:456) and the refusal=refusal pass-through in stage_tree_pinned's copy call — grep shows 0 uses inside the function; over-budget promotion already lives in _file_skip.
  • Make resolve_source's remote a required str (project_git.py:537) — 1 production caller, always a string; drop the unmatched-provenance None path.

[FIRST-PRINCIPLES-REVIEWED] 944310c

@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 944310c

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

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

@github-actions

github-actions Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

The RFC explicitly addresses my last candidate concern: "These activated entries are namespaced but install-global in v1... strict per-session capability scoping is a later capability-registry concern" — the install-global materialization is a documented, deliberate v1 decision, not a divergence. My review is complete.

The design holds up across every gate I ran: the manifest is a versioned public contract (apiVersion: crew.kiro/v1, strict rejection of unknown fields), trust binds to a content digest with withdrawal-on-change, materialization is provenance-namespaced for exact reclamation, the session project_id is an additive opt-in field with validated restore paths and detach-clears-identity semantics, session attach never touches the network, the source-provider SPI is deliberately deferred until a second source type proves it, and the owning specs (session, memory-skills-hooks, learn-cron-dashboard, sel) are updated in the same commit. Every candidate finding I raised was either line-level, explicitly documented as a deliberate v1 decision in the RFC, or proportionate to the problem.

Design-Verdict: PASS

A real portability gap, solved with a versioned manifest contract, digest-bound explicit trust, provenance-scoped materialization, and a deliberately narrowed v1 — every deferral is named in the RFC.

[DESIGN-REVIEWED] 944310c

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Aug 31, 2026
@kyleseaman
kyleseaman force-pushed the feat/project-bundles branch from f7c851a to f507017 Compare August 31, 2026 12:47
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Aug 31, 2026
@kyleseaman
kyleseaman force-pushed the feat/project-bundles branch from f507017 to d27d891 Compare August 31, 2026 13:07
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Aug 31, 2026
@kyleseaman
kyleseaman force-pushed the feat/project-bundles branch from d27d891 to 58b940a Compare August 31, 2026 13:43
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Aug 31, 2026
@kyleseaman
kyleseaman force-pushed the feat/project-bundles branch from 58b940a to 32c0682 Compare August 31, 2026 14:11
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Aug 31, 2026
@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Subtraction: drop on_stale from GitProjectStore.materialize_source (span=c6399026777f) — fixed

Fixed in 201cec3: the parameter and its branch are removed; the tests that used the callback now observe reuse-vs-replace through the tree itself (a planted file survives a reuse and disappears on a re-clone).

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Subtraction: drop the list-shaped agents fallback in _remove_materialized (span=a84bd6937860) — fixed

Fixed in 201cec3: only the dict shape is handled; _read_state already refuses any other shape and activation only ever writes the dict.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Duplicate mechanism: two namespaced provenance-tracked MCP installers target the rendered agent config (span=07c1546d20a9) — needs-a-decision

Routing Project MCP through the app-kit _register_mcp_servers path would merge two provenance schemes; the Project side needs withdrawal-on-digest-drift (a sync that changes reviewed content withdraws the install until re-review) and the app-kit path has no such lifecycle today. Whether to extend app-kit registration with a drift-withdrawal hook and move Project MCP onto it, or accept two installers with distinct key namespaces, is an architecture call for the author — not a change to make inside a babysit round.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • "Create project" vs "Add project" undifferentiated at the point of choice (span=6c4bf64863c6) — needs-a-decision

One-line hints on the two buttons (e.g. "Start a new bundle here" / "Use an existing folder or Git URL") — copy for the author to approve.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Capability rows lead with manifest selector paths instead of names (span=0dd22a68e8b7) — needs-a-decision

Leading each row with the resolved agent/skill/server names and demoting the selector to a secondary mono line is a detail-card layout change; proposing, not applying unilaterally.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • "Project" names three things (composer directory chip, Task Runner projects, bundles) (span=223a36419309) — needs-a-decision

Same vocabulary decision as the round-1 items (spans f86b6cc58171 / 78122bc6d612) and the Design lane's span 4f768c04fe4e: renaming the Task Runner's "Project" and/or the composer chip is a product wording call that spans surfaces this PR does not otherwise touch.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Bundle sessions disable the composer project chip with only a title explaining why (span=51bd970a2f6a) — needs-a-decision

The chip is disabled because a bundle-attached session's directory is owned by the Project; surfacing that inline (a short caption or a tooltip that works on touch) is a small change I can make if the author wants it on this PR rather than a follow-up.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • activate_project_body should state the stakes in the dialog (span=505fd429dd17) — needs-a-decision

Copy change ("Activates N agents, N skills, N MCP servers from this Project on this install") — counts are already in project.capabilities; awaiting the author's wording.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Spec ownership for the five project_*.py modules is unrouted in AGENTS.md (span=da530b4adf15) — needs-a-decision

The PR updates docs/system-specs/modules/* but adds no AGENTS.md routing row; adding one row pointing project_*.py at the owning spec section is a one-line change the author should place (which spec owns the trust digest and Git transport invariants is their call).

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • handlers_project.py hosts two domains with crosswise names (span=8d3345c1e88b) — needs-a-decision

Splitting the bundle handlers into their own module is a mechanical follow-up once the Task-Runner naming decision (span 4f768c04fe4e) settles; doing it now would re-arm every review lane on a rename-only diff.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • The user-facing "Projects" collision (Task Runner vs Capabilities tab) is documented, not resolved (span=4f768c04fe4e) — needs-a-decision

Agreed it is managed, not resolved; a follow-up renaming the Task Runner's "Project" vocabulary would retire the disambiguation prose. Product call for the author.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • Session attachment accepts a checkout from an obsolete repository declaration (src/kiro_crew/project_sessions.py:104) (span=d688802c2fab) — fixed

Fixed in 5a221a4: GitProjectStore.resolve_source now takes the current declaration (remote, default_branch, base_dir), normalizes it exactly as materialize_source does before recording, and answers None when the checkout's sources/<id>.source.json provenance record does not match — without cloning, and without ever running git in the checkout. _resolve_repo passes the manifest's current url/branch and the bundle dir for every repo source, so a sync that repointed a source after activation makes the old checkout unavailable to the session (required workspace source -> project_workspace_unavailable; optional source -> absent from the brief) until the owner re-activates.
This closes the sibling branch of the round-2 materialize_source fix: both readers of a derived checkout now consult the same record. Tests: test_resolve_source_refuses_a_checkout_the_declaration_no_longer_names (store; also asserts no git is run) and test_resolve_passes_the_current_declaration_to_the_checkout_lookup (sessions).

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: per-turn re-resolution of the Project attachment with a deferred provider reset when the workspace moved

  • Cached attachments survive Project sync and removal (src/kiro_crew/dashboard/chat_runner.py:6262) (span=db37e66c9e96) — fixed

Fixed in cca7263: _refresh_project_attachment no longer short-circuits on a cached brief. Every turn of a Project-attached slot re-resolves the attachment (resolve_project_attachment in a worker thread); when the resolved workspace differs from the slot's bound directory it arms slot._pending_reset_history_key = effective_session_key(slot), which _consume_pending_reset applies later in the same turn, so the provider cold-starts in the new directory instead of keeping the old cwd. A removed Project raises ProjectSessionError(code="project_not_found") from the resolver, which the turn's dedicated except ProjectSessionError handler surfaces as the terminal error — loud, never a silent turn in the old tree. Together with the provenance checks on both checkout readers, a sync that repoints a source now makes the old checkout unavailable to the very next turn.
Chosen over invalidating slots from the sync/remove handlers because storage can also change outside those handlers (a CLI sync, a manual project.yaml edit): re-resolving at the turn boundary is the one place every path converges. Tests: test_project_attachment_is_re_resolved_every_turn_and_a_moved_workspace_resets, test_project_attachment_of_a_removed_project_raises_instead_of_serving_the_cache; the restored-slot test now also pins that a first resolution arms no reset.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: registry-pinned Git coordinates (ProjectRegistration.remote/default_branch) + guard test forbidding checkout-derived coordinates in GitProjectStore

  • Sync trusts agent-writable Git source coordinates (src/kiro_crew/project_git.py:573) (span=63ce506e7b95) — fixed

Fixed in 1110a3f as a CLASS, after the retrospective this round's exit-30 called for: GitProjectStore never takes a coordinate from inside a checkout. ProjectRegistration gains default_branch; add() pins remote and branch from the STAGING clone it just made, before publish (the one sanctioned symbolic-ref, on a tree nothing else has reached), and the registry persists both through its hardened read. sync() refuses a registration without pinned coordinates, then runs fetch -- <pinned remote> <pinned branch> and verifies/merges FETCH_HEAD — origin, origin/<branch>, symbolic-ref HEAD and remote get-url no longer appear anywhere in the store; add()'s reuse decision compares the registry's pinned remote instead of get-url origin.
test/test_project_read_guards.py::test_git_store_never_takes_a_coordinate_from_inside_a_checkout scans every _run_git argv and fails the build on origin/origin/*/symbolic-ref/get-url outside that one add() site (mutation-verified: re-introducing fetch origin fails it). Behavioural pins: test_sync_ignores_an_origin_rewritten_inside_the_checkout (agent rewrites .git/config to an attacker remote; sync still pulls the pinned one and the payload never lands), test_add_pins_the_remote_and_branch_in_the_registry, test_sync_refuses_a_registration_without_pinned_coordinates. This ruling covers every finding whose premise is a Git coordinate read from a checkout.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: one hardened install/derived JSON reader (_read_install_json) + AST guard test forbidding raw reads in the Project modules

  • MCP configuration read can exhaust gateway memory (src/kiro_crew/project_capabilities.py:255) (span=aeacfc573e1f) — fixed

Fixed in 1110a3f as a CLASS: _read_json_object (the module's last by-name read_text) is replaced by _read_install_json, the ONE reader for every install-level or derived JSON file the agent could have written — open_file_no_reparse (link refused in the same operation as the open, on POSIX and Windows), fstat requiring one regular singly-linked file, _PROJECT_CAPABILITY_JSON_MAX_BYTES ceiling, then _decode_project_json_object. The install mcp.json (status/deactivation), the activated Project agent JSON in _verify_materialized (whose separate is_link_or_junction pre-check was a TOCTOU) and the installed agent config all route through it, and _read_state collapses onto the same function.
test/test_project_read_guards.py::test_every_install_or_derived_read_goes_through_a_hardened_reader AST-scans project_capabilities.py, project_git.py, project_registry.py, project_sessions.py and fails the build on any read_text/read_bytes/json.load(s)/yaml/open call outside the named hardened readers (mutation-verified: re-introducing mcp_path.read_text() fails it). The enumeration behind it found this the single remaining unsafe reader; the other five readers were already fd-pinned and bounded. This ruling covers every finding whose premise is an unbounded or link-following read of an install-level or derived file in these modules.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no

  • Project list failures are silently hidden (website/src/pages/ChatPage.tsx:3596) (span=fd89d98b48d2) — fixed

Fixed in c3527e2: the project-bundles query's isError renders ErrorNotice with askAgent in the page's pane-level notices block (beside upload-error / sid-error / action-error, which document why the hand-off is safe on this surface: the composer draft is persisted per slot and an in-chat hand-off opens a fresh slot). The chip keeps its generic label; the read failure is no longer hidden behind it. ChatPage.projectBundlesError.test.tsx pins both the notice (with its hand-off button) on a rejected read and its absence on a successful one.
The round-1 rebuttal for this site argued the rule governs rendered errors; the adjudicator ruled the blocking: true anchor authoritative, and the page already had the right surface for it, so fixing was cheaper than re-arguing.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Trust control is far from the Active/Inactive badge it changes (span=0223eea7024e) — needs-a-decision

Same layout decision as round-1 span ef0ea7d7206a: moving Trust and activate beside the badge in the card header is a detail-card redesign for the author to call; I can apply it on request.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • "Add project" vs "Create project" undifferentiated before the click (span=b3a55d89dbb7) — needs-a-decision

Same copy decision as round-3 span 6c4bf64863c6; the lane's concrete proposal ("Add existing project", or one split action) is recorded for the author.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Item 9 rides along (declared): SidePanelLayout re-click guard (span=f8fe054997f9) — rebutted

Inventory-only per the lane: declared in the description with the harm it removes; no action requested.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Item 10 rides along: ConfirmDialog danger opt-out with one consumer (span=fbdb1b2505b2) — rebutted

Inventory-only per the lane: the option has a consumer in this PR (the Project removal confirm) and the deleted pin invited the addition; no action requested.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • removal deletes only state/ while the spec requires deleting the managed bundle clone (src/kiro_crew/project_git.py:559) (span=2f79d28e3b18) — needs-a-decision

Advisory; recurs from round 1 with the same premise. The behaviour is deliberate and test-pinned (test_project_unregister_preserves_the_crew_owned_managed_clone: re-adding the same remote reuses the validated clone), and the spec sentence and remove_project_body copy read the other way. Author's call: delete managed/<id> after the registry commit and drop that test, or keep the clone and align the spec and copy. Not changed inside the babysit loop because either answer is a one-line product decision, not a defect fix.

@kyleseaman

Copy link
Copy Markdown
Contributor Author
  • Disabled bundle chip's aria-label should carry the project_bundle_locked explanation (span=e0f8f76baa4d) — fixed

Fixed in 15d13d1: the chip's accessible name is now the same projectChipTitle the tooltip shows — for a bundle-attached session that is project_bundle_locked ("Project: {name}. This session's Project sets the workspace."), so keyboard and assistive-technology users get the reason the control is disabled, not the bare label. ChatInput.projectBranch.test.tsx pins the accessible name. This also answers the round-1 watch item on the disabled chip being explained only by its title (span 51bd970a2f6a).

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: pre-materialization activation-record budget check (_require_recordable)

  • Agent payloads can exceed the activation-record ceiling (src/kiro_crew/project_capabilities.py:775) (span=aeacfc573e1f) — fixed

Fixed in d30f67c: activate now calls _require_recordable BEFORE removing a previous materialization and before the first write. It projects the record exactly as it will be written (rendered agent configs keyed by destination path, namespaced MCP specs with the provenance marker, the fixed-size fields) and refuses when the serialized size plus a 64 KiB headroom for the post-clone repository paths exceeds _PROJECT_CAPABILITY_JSON_MAX_BYTES — the same ceiling _read_install_json enforces on the way back in. The per-file ceiling bounds each input; this bounds their sum, so a record the reader would refuse is never written and no capability is left installed behind it.
This finding lives in code the round-1 fix added (the bounded reader) and is the interaction between two bounds; the budget check is the smaller of the two repairs (the alternative — raising the reader ceiling — would just move the pair). Tests: test_activation_refuses_agents_whose_record_would_exceed_the_reader_ceiling (two agents each under 1 MiB, together over; nothing installed, no state file) and test_activation_budget_refusal_keeps_a_previous_activation_intact (a re-activation that cannot be recorded leaves the working materialization untouched).

Add local and Git-backed Projects that bundle repositories, agents, skills, and MCP configuration. Integrate Projects with session creation and expose the experience under Agent Capabilities.
@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: replacement-before-discard ordering in materialize_source — the previous checkout survives until its replacement is in place AND recorded; every failure path restores it under its still-valid record
retrospective: round 9 — the recurring class in project_capabilities.py / project_git.py is ORDERING of a destructive step against the commit it depends on (round 8: a record written that the reader would refuse; round 9: the previous tree discarded before the new provenance was durable). Each earlier round added a bound or a record without stating the ordering rule those additions must obey, so each addition opened a fresh window. The rule now stated in code and pinned by failure-injection tests: a derived artifact is discarded only after its replacement is both published and recorded; a record is written only when it is guaranteed readable. The remaining destructive multi-step paths in the two modules were audited against it: activate (rollback already restores; the round-8 budget check runs before the first write), add (registry commit after the clone is published; the clone is retained on failure by design), sync (fetch + merge, git-atomic), remove_derived_state (pure deletion; its ordering is the author's pinned design, see the sibling disposition).

  • failed provenance write destroys the previous checkout (src/kiro_crew/project_git.py:434) (span=63ce506e7b95) — fixed

Fixed in 944310c: the backup of the previous checkout is retained until _write_source_record for the replacement succeeds. If the record write fails, the replacement is moved back out, the previous tree is restored under its own untouched record (the record write is an atomic replace, so a failure leaves the old record intact), and the error propagates; the backup is removed only after both steps succeed. On the first-clone path an unrecorded checkout is likewise withdrawn on record failure so it cannot be mistaken for a recorded one. Tests: test_materialize_source_keeps_the_previous_checkout_when_the_record_write_fails (local work in the old tree survives, record bytes unchanged, no staging/backup left behind) and test_materialize_source_leaves_nothing_when_the_first_record_write_fails.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

self-added: no

  • failed registry commit leaves a registered Project without its workspace (src/kiro_crew/project_capabilities.py:751) (span=aeacfc573e1f) — needs-a-decision

Held, not fixed: this ordering is the PR author's original design, not code this loop added. remove_derived_state is documented as "remove regenerable source checkouts before unregistering", and two tests in test/test_project_dashboard.py (test_project_unregister_preserves_registry_when_derived_cleanup_fails, test_project_remove_reports_derived_cleanup_failure_without_unregistering) pin the property the author chose: a removal that fails leaves the Project registered so the user can retry it. Committing the registry removal first would make a failed derived cleanup unreportable as a removal failure (the Project is already gone) and flip those two tests. Both orderings have a failure window; the author picked "retryable removal, regenerable checkouts" over "committed removal, orphaned checkouts". The residual is a registered Project whose source checkouts are re-cloned on the next attach (they are regenerable by construction); local edits inside a derived source checkout would be lost in that window, which is the data loss the finding names. Decision for the author: keep the retryable design (and note the window in the module spec), or commit the registry first and downgrade a failed derived cleanup to a logged warning. This round's attempt at the flip was reverted rather than override a pinned product choice.

@kyleseaman

Copy link
Copy Markdown
Contributor Author

Closing this PR: the design it implements is being superseded, not merged.

After twelve review rounds, all but two blocking findings were one class -- authority read back from state an agent shell can write -- and almost every instance lived in the capabilities layer (installing a bundle's agents, skills and MCP servers into the install's global state at activation). Main now provides that capability by another route (a session's project directory discovers its own .kiro/skills, project-local agents and .kiro/steering; kiro-cli reads a workspace-level .kiro/settings/mcp.json), so the layer is a second install path that only adds attack surface.

The recorded decision is #11564, "Projects revision 2 -- the thin Project": a fenced registry, a synced Git workspace, a memory store keyed to the Project (memory.mode), and MCP servers referenced by name. The implementation is being split into small PRs cut from this branch:

  • PR A -- the thin Project: registry moved to a gateway-only leaf on both fences, the hardened project_git.py from this branch carried forward unchanged, the manifest reduced, no capabilities module, no CLI group. Opens shortly from feat/project-thin.
  • PR B -- memory.mode, PR C -- MCP by name: follow, per the RFC's revised migration plan.

The branch feat/project-bundles stays as the carve source and is not deleted. Every review finding on this PR that survives into the thin shape has been carried into the split (provenance record, pinned Git coordinates, hardened reader, replacement-before-discard, the read-guard test); the ones that only applied to the capabilities layer close with it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants