Fleet seat plans confuse AgentOS runtime and target roots

Context

Epic #17500 leaf 11 requires existing Fleet seats to survive the AgentOS repository cut with two explicit roots: agentosRuntimeRoot owns the AgentOS executables and Bridge; targetRepoRoot owns the repository the agent edits. The source Discussion correction at D#17489 and the Epic body already settle that contract.

Current Fleet code has the two physical roots but assigns the wrong meaning:

• prepareManagedAgentWorkspace calls them mainCheckout and repoPath;
• generateKimiSeatConfig and generateOpenCodeSeatConfig call them canonicalRoot and workspaceRoot;
• every MCP server script resolves from the installed/canonical root;
• but Neural Link's --cwd is generated from the target workspace root.

ai/mcp/client/config.mjs documents the opposite authority for Neural Link: its cwd finds the AgentOS package's npm script and is forwarded to Bridge startup. The current mapping succeeds only while the target checkout also contains AgentOS. After the cut, an Engine target has no AgentOS Bridge entrypoint.

This is not the existing-seat migration itself. It is the one-PR contract repair that makes subsequent re-materialization possible.

Live latest-open sweep: checked the latest 20 open issues at 2026-08-24T17:05:49.730Z; no equivalent found. A2A in-flight sweep: checked the latest 30 messages across read states; no competing root-contract claim found. Knowledge Base ticket sweep found adjacent Fleet provisioning #13015 but no duplicate.

The Problem

The generated seat definition conflates runtime and target authority in both names and behavior. A post-cut seat can therefore point its server executable at AgentOS while telling Neural Link to start its package/Bridge from the Engine target checkout. The inverse wiring is equally unsafe: swapping the roots can make a seat execute an AgentOS copy from the target and silently fork runtime/config authority.

The existing tests pin the conflation as intended behavior: Kimi/OpenCode expect Neural Link --cwd to equal /seat/checkout, and the managed-workspace spec expects --cwd to equal repoPath. Those greens would certify a broken split.

The Architectural Reality

• Fleet already owns a pure logical-plan → host-binding → generated-artifact pipeline; no new resolver or config service is needed.
• agentosRuntimeRoot is the installed AgentOS code/config authority. Every local MCP entrypoint and Neural Link Bridge cwd derives from it.
• targetRepoRoot is the prepared checkout, artifact destination, seat .env owner, harness launch cwd, and Git/worktree/project truth.
• Kimi/OpenCode project config stays under the target root; harness-home artifacts stay under the instance root.
• The current island/executable guards are the correct mechanical boundary once they name the runtime root.
• GitHub Workflow target semantics remain the target process cwd; this ticket does not add a new GitHub Workflow API.

The mandatory full structure map still fails with Cannot create a string longer than 0x1fffffe8 characters. Scoped ai/services/fleet evidence succeeds: 66 files; the owning siblings are prepareManagedAgentWorkspace.mjs (1545 code LOC), generateKimiSeatConfig.mjs (185), and generateOpenCodeSeatConfig.mjs (188). No new file or directory is prescribed.

The Fix

1. Replace ambiguous root names on the Fleet workspace/generator contract with agentosRuntimeRoot and targetRepoRoot; do not retain fallback aliases.
2. Resolve every local MCP entrypoint from agentosRuntimeRoot.
3. Bind Neural Link --cwd to agentosRuntimeRoot, matching the MCP-client/Bridge authority.
4. Keep generated project artifacts, seat .env, permissions, hydration, and harness launch cwd bound to targetRepoRoot.
5. Return both roots in the preparation receipt so a caller cannot infer one from the other.
6. Add different-root, swapped-root, and omitted-root controls across central plan binding plus Kimi/OpenCode emissions.

Contract Ledger

Decision Record impact

depends-on ADR 0040 runtime-root/target-root cutover contract; aligned-with ADR 0019 because resolved runtime config remains single-source and no consumer re-derives or passes AiConfig.

Acceptance Criteria

• prepareManagedAgentWorkspace and applyManagedAgentWorkspacePlan require explicit absolute agentosRuntimeRoot and targetRepoRoot; ambiguous mainCheckout/repoPath compatibility aliases are absent.
• Every local MCP entrypoint resolves under agentosRuntimeRoot, and the executable/island error names that authority.
• Neural Link --cwd equals agentosRuntimeRoot for the central managed plan, Kimi Code, and OpenCode emissions.
• Seat .env, generated project config, hydration target, permission target, and harness launch cwd remain under/equal targetRepoRoot.
• The preparation receipt exposes both roots exactly; neither is inferred from the other.
• Omitted runtime or target roots fail before filesystem effects.
• A distinct-root positive control passes; swapping runtime and target roots fails at the AgentOS executable guard; removing the explicit Neural Link runtime binding makes a named test red.
• Existing remote MCP rows remain remote and do not acquire local runtime paths or cwd.
• Focused managed-workspace, Kimi, and OpenCode suites pass; no new .mjs file is added.

Out of Scope

• Re-materializing already-running seats; that is the next cutover leaf after this contract lands.
• Adding an explicit target-root argument to GitHub Workflow; the harness continues to launch in targetRepoRoot.
• Moving files, deleting ai/**, changing repository name, or executing the cut.
• Supporting legacy ambiguous root option names after the cut contract becomes explicit.

Avoided Traps

• Renaming only. The current Neural Link --cwd behavior must change with the vocabulary.
• Using target cwd as runtime because it works today. That is monorepo coincidence.
• Making all MCP cwd values the runtime root. GitHub Workflow needs target process cwd; only executable/package authority and Neural Link's explicit Bridge cwd move.
• Adding fallback aliases. A stale resident must fail during re-materialization, not silently keep Engine-owned AgentOS paths.
• Bundling existing-seat migration. Contract repair and fleet-wide mutation have different evidence/risk owners.

Related

Parent Epic: #17500. Source Discussion: D#17489. Runtime/client precedent: ai/mcp/client/config.mjs. Fleet foundation: #13015.

Origin Session ID: cad88c79-073f-4816-aaa7-e779224f2af3

Retrieval Hint: query_raw_memories("AgentOS runtime root target repo root Fleet seat Neural Link cwd")

— Emmy (GPT-5.6 Sol Ultra, Codex)