Repository navigation
Epic: shared reference source and governed worktrees #2390
Description
Outcome
Agents on both backends inspect centrally managed, read-only reference source and request governed writable worktrees through a supported tool, without acquisition consuming the brain's changed-path allowance or review space. Deterministic operations live in CLI/host code over the existing concrete storage, worker and hygiene owners; skills only select and orchestrate them.
Why now
A repository-inspection workflow refreshed a shallow source checkout under workspaces/ solely to read current source before filing an issue. On brain-kit 0.43.1, the turn journal recorded 5,332 paths under that checkout (5,067 content and 265 steering entries), plus one operational path. The 1,000 changed-path cap froze the turn; it eventually reached its independent 30-minute timeout without filing the requested issue. These are retained Activity/scope/journal observations, not an inference from Git status or a claim that files were committed.
The shared product problem is that disposable acquisition of reference source consumes the same changed-path allowance and review space as intentional work. The particular skill is user-owned; the product needs a supported workflow that skills can target.
Shared context
Current source:
journalPathScope,packages/ui-server/src/brain/native-journal-policy.ts:9-18, assigns workspace paths their own journal scope rather than excluding them through the brain's ignore rule.createNativeJournalCapture,packages/ui-server/src/brain/native-journal-capture.ts:10-137, retains observed workspace versions and feeds shared observations.createTurnScope,packages/ui-server/src/brain/turn-scope.ts:23-243, uses distinct observed paths for the cap.workerSandboxNote,packages/ui-sdk/src/server/worker-sandbox.ts:556-624, describes the writable areas and includes workspaces in scope accounting.referenceWorktrees,packages/ui-server/src/app.ts:457-459: the ui-server: govern managed reference worktree access and journal intentional edits #2430 worktree service, composed with journal coverage whenever a reference pool exists. The delivered backends: expose reference and worktree tools through Claude and Pi #2432 tools now call it through the host-bound referenceAccess bridge; both adapters register reference_source and reference_worktree with fixed schemas and call-time authority.
Binding records: docs/decisions/governed-writable-workers.md (workspaces, credentials, scope caps) and docs/decisions/native-brain-storage.md. Existing #1846 concerns presentation noise and explicitly preserves accounting; #2028 concerns configuration-input inventory. Neither supplies a reference-clone workflow. The durable policy record is docs/decisions/reference-worktrees.md (#2418, PR #2427); the lifecycle record is docs/decisions/managed-worktrees.md.
Constraints and non-goals
No blanket exclusion of workspaces/ from the journal or scope monitor, no higher global caps, no unbounded cache, no new extension interface, no credential exposure to a content-reading worker, and no edits to a user's custom skills. Intentional repository edits must remain governed and reviewable.
Binding rulings
Consolidated from the maintainer rulings of 2026-10-18 (Q1-Q15), 2026-10-22 and 2026-10-23; the individual rulings are in the comments. This supersedes earlier optional-volume, periodic-refresh and unconditional-purge wording.
Shared source, access and credentials
- Keep persistent application-managed reference source, read-only to agents, outside brain content, indexing, capture and sync. Ordinary inspection reads shared source without a full reference copy per agent or step. Cache snapshots/revisions may remain until capacity eviction or explicit removal; no idle-age expiry is selected.
- Public source is shared across the application host. Private source is isolated per brain and principal. Cached bytes alone never grant access.
- Ruling (2026-10-22, on ui-server: acquire authorized shared reference source with bounded refresh #2429): owner-managed repository grants. Private source requires a live covering grant managed by the owner; revocation withdraws uncovered source immediately and cancels in-flight private refreshes. Public source requires anonymous authority. Records:
docs/decisions/reference-source-grants.md,reference-source-acquisition.mdand the publication amendment inreference-pool-accounting.md. - Acquisition automatically uses a repository connection already authorized for the requesting principal, including private access, without an additional acquisition approval step. Existing profile, network and governance restrictions remain binding. Host credential availability alone is not authorization. Credentials stay in isolated transports and never reach processes evaluating repository-controlled inputs or source-reading workers.
- Successful authorization/public-visibility checks have a configurable five-minute lifetime. Checks cover the requested repository/revision; an accessible homepage is insufficient. Local revocation blocks new access immediately. After validation expires, a successful fresh check is required before a new mount; failure refuses. Reuse during an outage is allowed only within a still-valid authorization window. Handle public-to-private transitions without exposing private revisions through public cache authority. Checks cannot retract content already read.
Source freshness and reader consistency
- Refresh only on request, with a five-minute cooldown after the last successful source refresh. Requests within the interval reuse source; the first request afterward attempts refresh. No background periodic refresh or deferred timer is selected.
- Source-refresh and authorization/public-visibility checks have independent timestamps and purposes, despite the initially equal five-minute periods.
- Existing shared readers see refreshed source on subsequent reads. Multi-step reads may span commits; no per-agent/turn source pinning or waiting for all readers is selected. Report revision/freshness honestly. Publish only complete validated source, never partial staging. Active readers prevent capacity eviction, not refresh.
- Failed source refresh returns the previous usable authorized checkout with explicit stale status, exact commit, last successful refresh time and failure details. Failure does not advance freshness. Without a usable authorized checkout, refuse. Stale fallback never bypasses failed/expired authorization or public/private boundaries.
Managed writable worktrees and guidance
- Agents request an isolated writable worktree through a centrally managed tool call before editing reference source, or whenever stable multi-step reads are needed. The starting commit is fixed and reported; the working files are writable. Shared reference source remains read-only.
- The existing concrete host/storage/worker owners control allocation, authorization, identity/base commit, access/lifetime tracking, release and cleanup. Results identify the usable managed path/identity, starting commit, lifecycle/limits and release/renewal instructions. Exact tool names/schemas are implementation design. Requests do not widen the caller's principal/profile authority.
- Both backends receive actionable stable tool descriptions and appropriate worker guidance: when shared moving source is sufficient; when a worktree is required; how to request/resume/renew access; where to work; how to release it; and how expiry/refusal works. Do not rewrite user-owned custom skills, instruct unmanaged checkouts as the normal bypass, or mutate earlier provider-facing history.
- Intentional worktree edits remain governed, journaled and scope-accounted as editable workspace work. This is not an unjournaled writable cache exemption.
Activity, cleanup and hygiene
- Final ruling, Q15: only explicit worktree tool access/resumption or renewal resets the three-day inactivity clock. Reads, writes, commands and background maintenance do not implicitly renew it. Guidance makes renewal obligations explicit.
- Protect confirmed active workers from deletion even after the clock expires. Recover abandoned ownership after positively establishing that its worker is gone; uncertainty blocks deletion. Central release enables cleanup when the worktree is no longer needed.
- Automatically clean only managed worktrees with no unpreserved work, on release or after three days of inactivity. Retain unfinished/unpreserved files or local commits and request disposition through existing hygiene processes. Unknown cleanliness/preservation state blocks deletion. No automatic archive-then-purge policy is selected. Retained unfinished work remains capacity-accounted, and pressure does not authorize destroying it.
- Stale worktrees, retained unfinished work and cleanup failures join the existing human-started hygiene review. Reuse core's stable evidence-based finding identities and fingerprints and the review semantics of
docs/decisions/hygiene-review.md. Repeated scans do not duplicate findings. Dismissal/snooze does not approve deletion. Recheck identity, live ownership and current work/preservation state before applying cleanup. - Ruling (2026-10-23, on core: reconcile managed worktree retention and cleanup through hygiene #2431): host-only findings. Managed worktrees are volatile hosting state, not canonical brain data. Worktree findings and their dispositions live in the host database, are not written to
context/hygiene/Markdown and do not appear inbrain hygiene list. The Markdown source-of-truth rule covers brain content; this state is outside it. Cleanup is a typed host effect executed by the worktree service, neverresolveHygiene. - Ruling (2026-10-23, on core: reconcile managed worktree retention and cleanup through hygiene #2431): the owner principal is an authorized reader and reviewer of a delegated agent's private worktree findings. A private worktree's replicated card stays opaque; the owner reads details through ui-server: owner-only detail view for private managed-worktree hygiene findings #2734.
- These lifetimes apply to managed reference worktrees, not arbitrary user-owned workspace repositories. Never clean another worktree or shared source through a stale worktree identity.
Storage and actual disk accounting
- Require a separate logical reference-cache/worktree volume backed by Btrfs and optimized for worktree creation, safe source/object sharing, isolation and cleanup/reclamation. Separate physical storage or pre-reserved physical backing is not required.
- Integrate the volume into existing storage management where appropriate: qualification/status, usage/limits, reservations, shared-backing free-space/headroom checks, removal, interrupted-operation cleanup and crash recovery. Reuse concrete owners; add no storage-provider seam. Select and qualify concrete Btrfs layout/tuning and worktree mechanisms against source and offline evidence rather than assuming optimization from a configuration label.
- Use one combined finite allowance for reference source, managed worktrees and staging. Configurable defaults: 10 GiB total, 2 GiB per acquisition/snapshot/worktree.
- Charge actual allocated disk consumption, not summed apparent/logical file sizes or the advertised logical filesystem size. Count shared Btrfs allocations once in aggregate. This is not a percentage-of-disk sizing formula. Document and qualify per-worktree/acquisition attribution, allocation overhead and reservations, without double-counting allocated/reserved bytes. Existing independent backing-filesystem headroom safeguards remain binding. This reference/worktree policy does not change the brain-content retained-history accounting policy.
- Reserve acquisition capacity before starting work. Use capacity-driven least-recently-used eviction of unleased reference source; protect active users and worktree dependencies. If sufficient space cannot safely be reclaimed, refuse rather than deleting unfinished work or falling back to unbounded storage. Observe actual reclamation before reusing capacity.
Acquisition concurrency and failure
- Allow a configurable default of two active source acquisition/refresh operations across the host, each requiring capacity admission. Ordinary source readers are not limited to two.
- Same-source requests within the same authorized sharing domain join one in-progress operation. Deduplication does not disclose private activity across domains or allow concurrent writers to one published source.
- Central admission/waiting/cancellation and crash cleanup remain bounded and preserve admitted authority/lifetime. Resource, storage and existing turn limits remain binding. Failed/interrupted acquisition cannot publish partial source or silently free still-owned capacity. Concrete admission and lease mechanics are implementation design under these rules.
Breakdown
Delivered: #2432 (merged #2813, squash 1135899b5), #2723 (merged #2838, squash 77f35ef1b), #2418 (decision record), #2428 (allocated capacity, reclamation and recovery), #2429 (authorized acquisition and request-only refresh), #2430 (governed worktree lifecycle, worker access and journal/scope coverage), #2729, and #2431 (host-only hygiene findings, validated dispositions and cleanup, merged #2730 as dc5d3c73282c29a3f0098306d398743ee18ec791).
Remaining:
- ui-server: owner-only detail view for private managed-worktree hygiene findings #2734 — owner-only private finding details; its two-part inline disclosure design and recommended copy choices are approved, implementation/host/browser proof open.
- ui-react: the hygiene card's state copy describes a file edit for a managed-worktree finding #2837 — truthful managed-worktree state/post-check copy; optional caller display data (A) and corrected copy approved on 2026-10-24, implementation/browser proof open. Separate from the delivered Open-action fix.
- ui-server: reconcile every shared-reference and worktree criterion against the delivered children #2751 — final acceptance and integrated proof after its actual remaining prerequisites. Delivered backends: expose reference and worktree tools through Claude and Pi #2432/ui-react: the hygiene card opens a nonexistent file for a managed-worktree finding #2723 are no longer implementation gaps.
The independent native held-access proof correction #2819 remains below. Epic membership alone is not a blocker declaration.
Each layer starts from main containing its delivered parent, or from its qualified immediate parent under the project stack rules. Native storage/worker runs and final confirmation/merge windows are serialized by the campaign coordinator. No ungoverned write path ships before preservation, journal and scope controls exist.
Native held-access proof follow-up
#2819 directly verifies the delivered #2729 held-worktree release refusal. It corrects case 17's aggregate-allocation assertion so unrelated background reclamation cannot impersonate a change to the held worktree. The release semantics stay unchanged, and removing the guard must still fail its native assertion. It is an independent proof correction; attachment alone is not a blocker declaration.
Definition of done
Closing children does not close this epic; #2751 closes it once the integrated tree meets every criterion with its required proof.
- Implement the consolidated specification and record the durable rulings in the relevant decision records, including governed workers, native storage and hygiene review where applicable. The selected-policy record is delivered by docs: record shared reference-source and managed-worktree rulings #2418/docs: record shared reference and managed worktree rulings #2427; implementation must keep it and affected records aligned with the final behavior.
- An offline fictional repository with more than 1,000 files can be acquired and inspected without presenting acquisition as thousands of brain-content edits or consuming the content changed-path allowance. Real acquisition/storage/resource limits remain enforced and observable.
- Both backends can inspect shared source and request/resume/renew/release managed writable worktrees through the supported tool surface. Guidance and results report authority, base commit, path, moving-source/stable-worktree semantics, lifecycle and freshness honestly. Provider history remains append-only.
- Tests prove principal/private isolation, public-to-private handling, authorization expiry/refusal/local revocation, request-only five-minute source refresh, live-reader update behavior and explicit stale fallback without authority bypass. Partial acquisitions are never published.
- Tests prove Btrfs-backed volume qualification and worktree-efficient sharing/isolation/cleanup, actual allocation accounting including shared extents and changed/staged allocations, per-operation/aggregate limits/reservations, headroom refusal and observable reclamation. Apparent-size summation is not acceptable proof of allocated usage.
- Tests prove the two-operation default, same-domain single-flight behavior, independent parallel progress, cancellation/interrupted cleanup and crash recovery without private-activity disclosure.
- Worktree lifetime tests prove explicit-tool-only renewal, three-day inactivity, active-worker protection and safe release/ownership recovery. Unfinished/unknown-state work is retained, remains charged and enters idempotent hygiene review. Revalidate stale cleanup/disposition evidence before any deletion.
- Intentional managed worktree/normal workspace edits remain journaled, reviewable and scope-accounted. The reference cache is never an unjournaled writable bypass. Arbitrary user-owned workspaces are outside automatic cleanup.
Verification: Use keyless local fictional repositories and actual native worker/storage fixtures. Preserve meaningful failing-first/mutation receipts for accounting, authorization/containment, freshness, concurrency and cleanup. Prove actual Btrfs behavior and attribution rather than relying only on mocked predicates; keep affected package/type/contract checks. No external clone, model call or real credentials belongs in automated tests. Complete the repository's required PR proof; this decision review claims no implementation or runtime qualification.
Contract impact: Additive: the new managed-worktree tool and any new CLI JSON or supported configuration require same-commit updates to the relevant integration-contract components, a CONTRACT: commit and minor changeset. No breaking change is authorized. Exact names/schemas remain implementation design.
2026-10-24: restructured to the epic template; folded the 2026-10-23 host-only findings and owner-reader rulings into the hygiene rulings; recorded #2430 as closed and its service composition; added the final-acceptance task #2751 to the breakdown; refreshed source anchors to current main. The dated handoffs and triage notes are preserved in the comments.
2026-10-24 continued triage at main dc5d3c73282c29a3f0098306d398743ee18ec791: Folded verified #2431/#2730 delivery on this inspected main into the active breakdown and removed the obsolete draft/dependency wording. Refreshed worktree-service/note anchors; #2432/#2723/#2734 and #2751 remain open, with #2734’s actual design prerequisite explicit. No new worktree, private detail, native proof or epic completion is claimed.
2026-10-24 triage at main af6300478a07379178bd30221a31c0b917df2283: Refreshed moved current-source pointers by inspecting their named anchors. Historical receipts retain their source identities; scope, rulings, priorities and outstanding prerequisites are preserved. No runtime result or readiness is inferred from this navigation repair.
2026-10-24 triage at main 77f35ef1ba34e4fab7092ada5362ae799852ea24: Verified #2813/#2432 backend reference tools and #2838/#2723 no-file Open behavior on this main. Folded both into delivered context. #2837 directly advances truthful managed-worktree review and is attached here; #2734 and final integrated acceptance remain open. No complete epic qualification is claimed.
2026-10-24 maintainer reconciliation: #2837 approves optional inert caller-supplied HygieneCard copy with existing file defaults. Check again may automatically reclaim freshly verified clean, unheld worktrees; do not promise no removal. Confirmed removal and merely cleared/uncertain findings use distinct truthful copy, and no Undo is offered. No cleanup policy, private disclosure or server outcome change is authorized. #2734 remains independently awaiting its design and this epic is not complete.
2026-10-24 triage at main e1ab485669565554ca6cb61ce5d130303647230f: Updated the active #2734 handoff to its explicit approved inline-detail design. Earlier pending-design notes are historical; #2837 remains a distinct approved copy implementation and integrated final acceptance remains open. No owner detail or full worktree outcome is claimed delivered.
Activity
schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q1 selects option 1: a persistent application-managed reference cache. Immutable repository revisions may be reused across turns until eviction; workers receive read-only reference source outside brain content. Acquisition is recorded separately and has finite resource limits. Intentional workspace edits remain journaled.
The issue body and acceptance criteria now reflect this branch. Acquisition authority, private-repository authorization/access scope, concrete storage placement, capacity/retention/cleanup, refresh/concurrency and promotion still require decisions. Retain
needs: decision; no additional ephemeral mode, numerical defaults or implementation is selected by this ruling. The relevant decision record remains an explicit implementation deliverable of this issue.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q2 selects option 1: reference acquisition automatically uses a connection already authorized for the requesting principal, including private-repository access. There is no additional reference-acquisition approval step. Existing network and governance restrictions remain binding; available host credentials alone grant no authority. Credentials stay in the isolated transport and never reach source-reading workers.
The body and acceptance criteria incorporate this choice. Cache reuse/access scope and authorization revalidation are still open, alongside storage placement, finite limits/retention/cleanup, refresh/concurrency and workspace promotion. Keep
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q3 selects option 4: share public reference source across the application host; isolate private reference source per brain and principal. Cached bytes alone confer no private-source authority. Repositories becoming private must be handled, and anonymously inaccessible revisions must not be classified as public.
The body and acceptance criteria incorporate the sharing model. Authorization revalidation and visibility-change timing/mechanism are not yet selected. Concrete storage placement, finite limits/retention/cleanup, refresh/concurrency and workspace promotion also remain open. Keep
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q4 selects option 2: successful authorization and public-visibility checks can be reused for a bounded, configurable lifetime, initially five minutes. Checks cover the requested repository/revision. Local revocation blocks new access immediately. After expiry, a successful fresh check is required before a new mount; failure or inability to validate refuses that mount. Brief outages permit reuse only while the prior validation remains valid. This applies to public shared and private isolated snapshots and does not retract source already read by a running turn.
The body and acceptance criteria now incorporate this choice. Storage placement, capacity/retention/cleanup, refresh/concurrency and workspace promotion remain open. Keep
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q5 selects option 1: an application-managed cache directory, with a separate cache volume optional. Cache storage stays outside brain content and retained history. Independent finite capacity accounting/enforcement includes acquisition staging; capacity reservations and free-space safeguards preserve required application/recovery headroom when sharing a filesystem.
The body and acceptance criteria incorporate this choice. Numerical limits, retention/eviction/cleanup, directory provisioning/qualification, refresh/concurrency and workspace promotion remain open. Keep
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18), Q5 clarification: A separate logical reference-cache volume is required. Separate physical storage, reserved physical backing and a physically isolated capacity boundary are not required; the volume may share the underlying disk/filesystem. Storage stays application-managed and outside brain content/history, with independent finite capacity enforcement including acquisition staging, reservations and free-space safeguards.
This supersedes the earlier comment's optional-volume wording. The body and acceptance criteria are corrected. Concrete provisioning/qualification, capacity/retention/cleanup, refresh/concurrency and promotion remain open; retain
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q6 selects option 1: evict least-recently-used unleased snapshots only when capacity is needed. No automatic idle-age expiry is selected. Active readers protect their snapshots; if enough space cannot safely be reclaimed, new acquisition refuses. Unused source can remain stored indefinitely within the finite capacity limit, but reuse remains subject to Q4 authorization/public-visibility validation.
The body and acceptance criteria incorporate this choice. Numerical limits, volume provisioning/qualification, cleanup/removal and lease/crash recovery, refresh/concurrency and workspace promotion remain open. Keep
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Q7 selects option 1: ship configurable defaults of 10 GiB total reference-cache capacity and 2 GiB per acquisition/snapshot, including checkout, Git data and staging. Staging/reservations count within the total cache allowance. Preserve existing free-space safeguards and refuse acquisitions that cannot fit after safe eviction. The figures are selected initial defaults, not measured sizing guarantees; acquisition concurrency is not yet selected.
The body and acceptance criteria incorporate the limits. Source freshness/identity, concurrency and lease/crash cleanup, volume qualification/removal and editable-workspace promotion remain open. Keep
needs: decision.schlessera commentedon Oct 18, 2026
Decision (maintainer, 2026-10-18): Include the separate logical reference-cache volume in existing storage-management logic where appropriate. Reuse concrete storage/lifecycle owners for qualification/status, capacity accounting and reservations, shared-backing free-space/headroom checks, eviction/removal, interrupted cleanup and crash recovery. Appropriate management/status surfaces should report cache usage, limits, reservations and storage refusals.
Keep the cache's allowance/lifecycle distinct from brain content and retained history. Do not double-count shared physical free space, introduce a storage-provider seam, or require separate physical storage. The issue body and acceptance criteria incorporate this requirement. This is an addition to Q5, not an answer to the pending Q8 source-refresh question; retain
needs: decision.33 remaining items
schlessera commentedon Oct 24, 2026
History moved out of the body on 2026-10-24, when the body was restructured to the epic template. These sections were current at their dates and are superseded by the body's Breakdown.
Current implementation handoff — 2026-10-23
At inspected main
f3c6fdc9f9c6321fda5a384cf8cfd8bf2e4846da, #2428’s native storage foundation remains delivered through #2640. #2429 is now closed through merged #2661 (16b0dbadb54aac25eee39da7637da4911ff77071), #2662 (62cb35c7684c168a917b4aaac04d5d921cd1156b) and #2663 (f3c6fdc9f9c6321fda5a384cf8cfd8bf2e4846da). Owner-managed live grants, per-domain publication views and authorized request-only source acquisition/refresh are delivered at the service level. Records:docs/decisions/reference-source-grants.md,reference-source-acquisition.mdand the publication amendment inreference-pool-accounting.md. Credentials remain transport-only; public source requires anonymous authority, private source requires a live covering grant, and revocation withdraws uncovered source and cancels in-flight private work. Independent authorization/refresh clocks, bounded admission, explicit authorized stale fallback and capacity accounting remain binding.Three native implementation children remain open: #2430 → #2431 → #2432. #2430’s #2429 prerequisite is satisfied and its owner has claimed the worktree layer from this main. The merged service is constructed with the app when a reference pool exists, but no agent tool or HTTP acquisition route calls it yet. Ordinary-worker view exposure, managed writable worktrees, preservation-aware hygiene, worktree dependency protection and complete end-to-end backend/accounting proof remain in those children. Do not mistake the publication-view layer for #2430 or the acquisition layer for #2431.
The merged PRs attribute real offline transport, long-lived native-view readers, a 1,200-file acquisition and named mutation receipts to their recorded heads. This triage verifies source/merge/state only, not a new native run or complete programme delivery. Preserve existing ownership, P0 priorities, historical milestone attribution and the complete consolidated rulings below. Earlier dated inventories remain historical.
Declared implementation layers — 2026-10-19
The complete requirements and rulings above remain binding. This issue now serves as the umbrella outcome; implementation proceeds through these direct sub-issues without reducing acceptance scope:
#2418 is closed through merged #2427, squash
2f5f935484ad257d4cad0a07acb490bac0b1de19, verified as an ancestor of inspected main.docs/decisions/reference-worktrees.mdand its adjacent amendments supply the durable policy record. This delivers documentation, not reference/worktree runtime behavior or qualification.The declared implementation stack uses the order above. The first layer starts from verified main. Each upper layer starts from its qualified immediate parent, or main containing that delivered parent. An open blocker qualifies for stack selection only after its non-draft PR has complete passing current-candidate proof under the project stack rules; a draft, a branch name or an old receipt is insufficient. Native storage/worker operations and final confirmation/merge windows remain serialized by the campaign coordinator.
Disjoint offline fixture or static guidance preparation may overlap after the owning boundary stabilizes. Shared native manager, SDK contracts, host lifecycle and worker wiring retain a single implementation owner. No ungoverned write path may ship before preservation, journal and scope controls exist. A complete qualified storage-management deliverable may land independently with consumers disabled; scaffolding and incomplete upper layers stay draft. Closing children does not close this umbrella until the complete original acceptance and required integrated native/backend evidence are delivered.
2026-10-21 triage at main
c2f080f20a31224a1eeccde321c574292eaedb02: reconciled the delivered #2418/#2427 decision record against source and merge ancestry. All five implementation children remain open at their existing p0 ranking and dependency order; preserve the complete consolidated rulings and required native/backend acceptance. No implementation, Btrfs measurement or new policy choice is claimed.2026-10-22 triage at main
ca8842828ed8634a84c4e8aa4a88e487238721b4: refreshed verified current-source pointers by their named anchors. Scope, recorded decisions and remaining prerequisites are unchanged; source inspection supplies no new runtime or epic-completion evidence.2026-10-22 triage: reconciled #2428/#2640 foundation delivery, the four remaining native implementation layers and #2429’s later owner-managed-grant ruling. No source acquisition, new runtime proof, policy alternative, epic readiness or complete outcome is inferred.
2026-10-23 triage at main
f3c6fdc9f9c6321fda5a384cf8cfd8bf2e4846da: reconciled closed #2429 and merged #2661/#2662/#2663 with the active implementation handoff. #2430, #2431 and #2432 remain open in that order; #2430’s existing claim is preserved. Service/publication delivery does not expose agent tools, implement writable worktrees or qualify the full epic. Source/merge review only; no fresh runtime/CI result or epic readiness.schlessera commentedon Oct 24, 2026
2026-10-24 triage at main
dc5d3c73282c29a3f0098306d398743ee18ec791: Folded verified #2431/#2730 delivery on this inspected main into the active breakdown and removed the obsolete draft/dependency wording. Refreshed worktree-service/note anchors; #2432/#2723/#2734 and #2751 remain open, with #2734’s actual design prerequisite explicit. No new worktree, private detail, native proof or epic completion is claimed.schlessera commentedon Oct 24, 2026
2026-10-24 triage at main
af6300478a07379178bd30221a31c0b917df2283: Refreshed moved current-source pointers by inspecting their named anchors. Historical receipts retain their source identities; scope, rulings, priorities and outstanding prerequisites are preserved. Added the directly matching #2819 native held-access proof follow-up under this epic; attachment is not a prerequisite declaration. No runtime result, integrated completion or epic readiness is inferred.schlessera commentedon Oct 24, 2026
2026-10-24 triage at main
77f35ef1ba34e4fab7092ada5362ae799852ea24: Verified #2813/#2432 backend reference tools and #2838/#2723 no-file Open behavior on this main. Folded both into delivered context. #2837 directly advances truthful managed-worktree review and is attached here; #2734 and final integrated acceptance remain open. No complete epic qualification is claimed.schlessera commentedon Oct 24, 2026
2026-10-24 triage at main
e1ab485669565554ca6cb61ce5d130303647230f: Updated the active #2734 handoff to its explicit approved inline-detail design. Earlier pending-design notes are historical; #2837 remains a distinct approved copy implementation and integrated final acceptance remains open. No owner detail or full worktree outcome is claimed delivered.schlessera commentedon Oct 24, 2026
2026-10-24 final acceptance reconciliation (#2751), on main
5f5178cf85a529fa6207a269b369afceb0b0af41.All children named in the breakdown are merged. Native receipts were made on this host (kernel 6.18 WSL2, btrfs-progs 6.6.3, image
brain-kit-native-runtime:1), from a scratch worktree, under the shared native slot:bun scripts/prove-reference-pool.tson5f5178cfexited 0, cases 1–18.bun scripts/prove-reference-pool.ts --integratedexited 0 for Claude and Pi on test: prove shared reference source and managed worktrees end to end on both backends #2860, head9a9866867037f496a00dc8c688bfc3cd4503f257. That head is5f5178cfplus test and proof scripts only.renewalandfreshnessscenarios.#2860 is a draft that holds the harness, so the integrated and extended guard receipts are not on main until it merges.
2f5f9354(reference-worktrees.md). Implemented by: #2640477c8f72(pool), #266116b0dbad(grants), #266262cb35c7(views), #2663f3c6fdc9(acquisition), #2686c89045bb, #2687c3039932and #2688d6a07c41(worktrees), #27425e6446ae(held release), #2730dc5d3c73(hygiene), #28131135899b(tools), #283877f35ef1(Open action), #2849498a601f(owner details), #28525f5178cf(card copy). Records:managed-worktrees.md,reference-pool-accounting.md,reference-source-grants.mdandreference-source-acquisition.md, with dated amendments ingoverned-writable-workers.md,native-brain-storage.mdandhygiene-review.mdchangedPaths 0and no journal rows (INTEGRATED_*_ACQUISITION_CONSUMES_NO_CHANGED_PATH,…_ACQUISITION_NOT_JOURNALED). Native case 16:REFERENCE_ACQUISITION_WORKER_INSPECTS_THROUGH_VIEW. Native case 18:REFERENCE_TOOLS_NATIVE_READS_DO_NOT_COUNT. Limits:REFERENCE_POOL_OVER_ADMISSION_REFUSED,…_OPERATION_LIMIT_ENFORCED_AT_WRITE,…_CLI_STATUSstartingCommit, path, moving source with a fixed worktree, and fresh and then stale freshness (INTEGRATED_*_SOURCE_MOVED_ON_REQUEST,…_SOURCE_STALE_FALLBACK,…_RENEWAL_ADVANCES_CLOCK). Pi: 16 provider requests keep tools, system and history byte-identical. Guards:REFERENCE_TOOLS_{CLAUDE,PI}_*(#2813) and the newREFERENCE_{RENEWAL,FRESHNESS}_{CLAUDE,PI}_*. Resume: "only explicit access, resumption or renewal moves the inactivity clock" (#2687)REFERENCE_SOURCE_PRIVATE_DOMAIN_ISOLATED,…_PUBLIC_TO_PRIVATE_UNPUBLISHED,…_EXPIRED_VALIDATION_REFUSES,…_REVOCATION_CANCELS_REFRESH,…_COOLDOWN_REUSES,…_FAILED_REFRESH_KEEPS_TIMESTAMP,…_STALE_FALLBACK,…_FAILED_ACQUISITION_UNPUBLISHED. #2662, native case 15:REFERENCE_VIEW_EXISTING_READER_SEES_REFRESH,…_PARTIAL_PUBLISH_REFUSED. #2661: grantsREFERENCE_POOL_QUALIFIED,…_SNAPSHOT_SHARED_ONCE,…_COW_CHARGES_CHANGED_EXTENTS,…_CONCURRENT_ADMISSIONS_SERIALIZED,…_SHARED_BACKING_HEADROOM_REFUSES,…_RECLAIMED_CREDIT,…_NO_EARLY_CREDITREFERENCE_SOURCE_TWO_OPERATIONS,…_SINGLE_FLIGHT(public domain),…_RESERVATION_HELD_UNTIL_WORKER_STOPS,…_RECOVERY_*, and nativeREFERENCE_POOL_CRASH_*. Gap: collapsing every private domain into one single-flight key atreference-source.ts:486passes all 61 tests inreference-source.test.tsandreference-tools.test.ts. Independent progress (one operation finishing while another is stalled) is untestedREFERENCE_WORKTREE_IMPLICIT_ACTIVITY_DOES_NOT_RENEW,…_ACTIVE_HOLDER_PROTECTED_PAST_EXPIRY,…_UNKNOWN_LIVENESS_RETAINED. #2742:REFERENCE_ACCESS_HELD_NOT_RELEASED. #2730:REFERENCE_WORKTREE_HYGIENE_ONE_FINDING,…_STALE_APPROVAL_REFUSED_*,…_UNPRESERVED_RETAINED,…_CREDIT_AFTER_RECLAMATION. Native, #2860: retained work reaches the host-only review, is removed there (reclaimed,review), and the clean worktree is removed automatically (reclaimed,automatic)REFERENCE_WORKTREE_NATIVE_EDITS_JOURNALED,…_SCOPE_COUNTS. Native, #2860: exactly the two edits are journaled underreference_worktreewithchangedPaths 2on both backends, and a write to shared source is refused. A mutation that drops the journaling failsINTEGRATED_PI_WORKTREE_EDITS_SCOPE_COUNTED(2 → 0). A user-ownedworkspaces/argorepository is untouched (INTEGRATED_*_USER_WORKSPACE_UNTOUCHED), andREFERENCE_WORKTREE_WORKSPACE_JOURNALING_UNCHANGEDholdsRemaining under this epic:
agent-ready.Refs #2751.This epic stays open.
schlessera commentedon Oct 24, 2026
2026-10-24 final acceptance update (#2751), on main
6f3f65fd1.This updates the 2026-10-24 reconciliation (#2390 (comment)). The only unmet criterion there was 6. It is now met.
126f37456. The integrated native receipts and extended provider-history guards for criteria 2, 3, 7 and 8 were recorded on its head9a986686, and are now on main.6f3f65fd1. Two service-level tests inpackages/ui-server/tests/reference-source.test.tsclose criterion 6's gap:REFERENCE_SOURCE_PRIVATE_CONCURRENT_NOT_JOINED,…_PRIVATE_NOT_SETTLED_BY_OTHER_DOMAIN,…_PRIVATE_CONCURRENT_DOMAINS_ISOLATEDand…_PRIVATE_LEASE_IN_OWN_VIEW. Two principals request the same private repository while the first fetch is still in flight. That gives two fetches, each with its own principal's credential, two views and two roots, and neither request settles from the other's operation. The collapse mutation (sourceKey("private", …)atreference-source.ts:486) failsREFERENCE_SOURCE_PRIVATE_CONCURRENT_NOT_JOINED.REFERENCE_SOURCE_INDEPENDENT_PROGRESSand…_INDEPENDENT_PROGRESS_PUBLISHED. A newer admitted acquisition completes and publishes while the oldest is still stalled. Serializing completion behind older operations failsREFERENCE_SOURCE_INDEPENDENT_PROGRESS.REFERENCE_SOURCE_TWO_OPERATIONS,…_SINGLE_FLIGHT,…_RESERVATION_HELD_UNTIL_WORKER_STOPS,…_RECOVERY_*and nativeREFERENCE_POOL_CRASH_*Every criterion is met. No unmet criterion remains, so #2751 closes.
#2819 (native case 17 compares aggregate charge across background reclamation) is a native-proof assertion fix, not a gap in any criterion above. It is detached from this epic and stays open on its own, so this epic closes.