[Workstream D] PR 17 of 17: Apply project-root ownership before initialization creates runtime state

[zaxbysauce]

Roadmap: D17 · Workstream D: SQLite and observability
Sequence: PR 17 of 17 (tracking slot; dependencies define execution order)
Roadmap rebaseline: 2026-09-09 · Execution group: W2

Apply project-root ownership before initialization creates runtime state

W2 independent execution group

Problem and outcome

Initialization and first writes can create .swarm state under an ordinary child directory even when the project root is an ancestor. The bootstrap decision must use the same project-boundary policy as tools and must happen before database, bundled-skill, or other runtime state writes. The outcome of this issue is a single reviewable implementation that makes the stated behavior observable in a supported host and leaves a bounded, operator-understandable result on failure.

Scope and ownership

The planned scope is:

Use the existing project-boundary API at bootstrap and first write for actual ctx.directory/--dir ordinary children with an ancestor .swarm, including DB and bundled-skill writers. Keep valid nested Git/.opencode roots, worktrees, and standalone roots independent; late optional writers must honor the same decision.

Apply the existing project-boundary API to actual ctx.directory and --dir during bootstrap and first write. An ordinary child with an ancestor .swarm must resolve to the parent and return an actionable bounded hint. A directly declared nested Git repository, nested .opencode root, linked worktree, or standalone root remains independent. Pass the resolved decision to DB, bundled-skill, and late optional writers.

The implementation should preserve existing public identities and contracts unless a criterion below requires a narrowly documented extension. Every changed write, state transition, or host boundary needs a named caller and an owned fixture. Keep unrelated roadmap work out of this PR.

Invariants and delivery contract

• 4 (.swarm containment): bootstrap and every writer use the resolved project root.
• 1 (bounded initialization): root resolution is bounded before optional work.
• 8 (session state): project-owned state does not cross roots.

One future implementation PR must deliver the production change, focused unit and host tests, the relevant documentation/release fragment, and retained fixture evidence together. No required acceptance criterion may be deferred to a telemetry-only, shared-harness, or separate documentation PR.

Required behavior

• AC1: An ordinary child cannot create child .swarm state and returns an actionable parent-root hint with bounded manifest behavior
• AC2: Direct nested Git, nested .opencode, worktree, and standalone-root controls remain independent
• AC3: Two actual plugin/host fixtures and late optional writers respect the resolved project-root decision

The following details make the acceptance testable:

Use two disposable actual host/plugin fixtures: an ordinary child under a project with existing .swarm, and a directly initialized nested Git root. Add nested .opencode, linked-worktree, and standalone-root controls. For each, inspect parent/child state before and after bootstrap, first tool, database access, bundled-skill sync, and a late optional writer; record the selected root and any bounded hint.

Malformed direct markers opt in only where the documented policy allows; inaccessible marker links and ancestor-depth exhaustion fail closed. A late optional writer must honor the bootstrap decision and never silently fall back to its own cwd.

Tests and runtime evidence

Assert that the ordinary child never creates child .swarm, emits the parent-root guidance, and still returns a bounded manifest. Assert that direct nested Git and .opencode declarations remain independent, worktrees preserve their repository identity, and standalone roots own their state. Include a first-write race and late-writer regression so policy is not checked only by a tool-level guard.

The report must include the exact command or host journey, runtime and host versions, fixture class, start/end status, and bounded logs or manifests needed to reproduce the result. A process exit, a banner, a synthetic response, or a unit-only result is insufficient where a registered host or real handler is named above. Tests must prove the negative and recovery paths as well as the happy path.

Documentation and operational contract

Define ordinary-child, nested-repository, worktree, .opencode, and standalone-root rules with examples for ctx.directory/--dir. Document that bootstrap root ownership is distinct from the separate process-global hydration eviction issue in #2667 (Workstream D PR 14 of 17).

Add or update the narrowest relevant documentation and release fragment for the behavior this PR introduces. Keep production behavior documentation owned by this PR; consolidation or roadmap documents may link to its evidence after merge.

Dependencies and coordination

• No active dependency edge is required; use the existing identity APIs and this row's fixtures.

Existing issue numbers in the plan retain their meaning. Conditional scenario prerequisites must not block the default path, and a downstream evaluation or documentation consumer must not become an implementation prerequisite. The row is independently implementable with existing identity APIs and its own disposable fixtures; no common new framework or repository-wide CI result is required before review.

Evidence boundary

Source references below are pinned to revision ec76aba5cff2536887a1c90e7bc1dfd8ce04690c. The audit's older executed host/runtime controls were run against the pre-refresh 55/9811 baseline and have not been rerun at this source revision; they are historical evidence only. Re-run the focused controls after implementation and report unavailable historical fields as unknown.

Source anchors:

• src/utils/project-boundary.ts
• src/index.ts
• src/db/project-db.ts
• src/config/bundled-skills.ts

Non-goals and limits

Do not change valid nested repository semantics, add a second tool-only guard, redesign hydration, or permit arbitrary state outside the resolved project root.

Do not include private workspace paths, live session identifiers, raw provider payloads, or unrelated trace content in the public issue. Keep fixtures disposable and keep any model or host limitation explicit in the evidence. Closure requires the measurable criteria above and the retained artifacts, not a restatement that the original acceptance was preserved.

[zaxbysauce]

Implementation PR: #2801

What changed: plugin bootstrap and mcp serve --dir now resolve the project root once, synchronously, before any init-path or first-write consumer touches a directory (resolveProjectRootDecision in src/utils/project-boundary.ts, sharing assertProjectRoot's ancestor walk). An ordinary child of a project root that owns .swarm/ state resolves to the owning root — all state, project config, telemetry, and bundled skills land there, with one always-visible hint naming the owning root plus a durable .swarm/advisories/bootstrap-root-redirect.json record; the manifest stays fail-open. Declared nested roots (.git file/dir, worktrees), .opencode roots, and standalone roots stay independent; indeterminable ownership fails closed for state writes. Concurrent boots cannot interleave a child write; the registered late writer (snapshot writer) honors the resolved root.

How to use it: nothing to enable — open the project root (or any marker-bearing directory) as before; if you open an ordinary subdirectory of an owning project, the boot now prints [opencode-swarm] project-root ownership: ... naming the root that owns your state.

Migration: no automatic migration. If a workspace previously booted from an ordinary subdirectory, move or delete that stray child .swarm/ tree manually; new boots write to the owning project root. Redirected boots inherit the parent project's .opencode/opencode-swarm.json flags — details in the PR's release fragment.

Verification: 8 frozen acceptance checks (RED at base 9ba5b41, GREEN at PR head 52588e1, independently replayed by an implementation reviewer and a final critic), 37 new/extended tests, measured repro-704 init latency unchanged, full invariant audit in the PR body. Merging stays human-gated.

[zaxbysauce]

Verified against the code. The behavior gap is real on this revision: the project-boundary API already exists (assertProjectRoot in src/utils/project-boundary.ts:144 — ancestor .swarm walk with a bounded 20-level depth, fail-closed on inaccessible state, direct .git/.opencode marker exemptions, marker symlinks rejected) and is applied at write-time sinks (plan/ledger, scope, evidence, evaluation, pre-check-batch, resolveWorkingDirectory). However, plugin bootstrap does not use it: src/index.ts hands raw ctx.directory to initTelemetry (which mkdirs <dir>/.swarm at src/telemetry.ts:404), the observability event sink, bundled-skill sync, git-exclude, and the project DB opener (src/db/project-db.ts:944), and mcp serve --dir only existence-checks the root (src/cli/mcp.ts:94). So booting from an ordinary child of a project that already owns .swarm/ does create child runtime state before any guard runs — exactly what this issue targets. Nothing named resolveProjectRootDecision or the bootstrap-root-redirect.json advisory exists in this checkout, consistent with the linked implementation PR #2801 not yet merged here; once it lands, review should focus on (1) the resolution happening synchronously before every init-path and first-write consumer, (2) the declared-root exemptions (.git file/dir, worktrees, .opencode, standalone) staying independent per the existing hasExplicitProjectBoundary semantics, (3) the late optional writer (snapshot writer in src/session/snapshot-writer.ts) honoring the resolved root rather than its own cwd, and (4) host-fixture evidence per AC1–AC3, with docs distinguishing this from the unrelated #2667 hydration-eviction issue. Not an easy win: it touches the startup-latency-constrained init path (#2670), DB/telemetry/skill writers, the CLI entry, and requires race and negative-path tests.