@adhdev/daemon-core 0.9.82-rc.2 → 0.9.82-rc.200

package/src/mesh/coordinator-prompt.ts

@@ -8,8 +8,23 @@
  *   3. How to orchestrate work across nodes
  *
  * The prompt is generated dynamically from the current mesh state.
+ *
+ * User customization:
+ *   ~/.adhdev/coordinator-prompts/<cliType>.md         — full override
+ *   ~/.adhdev/coordinator-prompts/<cliType>.append.md  — appended to default
+ *   ~/.adhdev/coordinator-prompts/default.md           — full override (any CLI)
+ *   ~/.adhdev/coordinator-prompts/default.append.md    — appended to default (any CLI)
+ *
+ * CLI-specific files take precedence over default.* files. The override file
+ * still gets the node/policy facts substituted via the same {{placeholders}}
+ * the daemon understands; an override that doesn't reference them just gets
+ * a static prompt, which is also fine.
  */
 
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
 import type {
     LocalMeshEntry,
     RepoMeshPolicy,
@@ -27,8 +42,68 @@ export interface CoordinatorPromptContext {
     coordinatorCliType?: string;
 }
 
+/**
+ * Compose the final coordinator prompt from four layers, in this precedence:
+ *
+ *   1. Per-launch `extraSystemPrompt` (always appended, as "## Additional
+ *      Context"). Never wins as a base — it's launch-scope context.
+ *   2. Mesh-level append (`mesh.coordinator.systemPromptAppend` or the legacy
+ *      `systemPromptSuffix`). Stacks after whichever base won.
+ *   3. User-file append (`~/.adhdev/coordinator-prompts/<cli>.append.md` or
+ *      `default.append.md`). Also stacks; same placeholder expansion as the
+ *      override path.
+ *   4. Base prompt, picked in this order:
+ *      a. `mesh.coordinator.systemPromptOverride` (mesh-level override)
+ *      b. user-file override (`~/.adhdev/coordinator-prompts/<cli>.md` or
+ *         `default.md`)
+ *      c. daemon default (assembled from identity/nodes/policy/tools/…)
+ *
+ * That layering lets a user customize prompts at three increasing scopes
+ * (machine, mesh, single launch) without losing the daemon's stock rules.
+ */
 export function buildCoordinatorSystemPrompt(ctx: CoordinatorPromptContext): string {
-    const { mesh, status, userInstruction, coordinatorCliType } = ctx;
+    const { mesh, userInstruction, coordinatorCliType } = ctx;
+
+    // ── Pick the base prompt ──
+    const meshOverride = mesh.coordinator?.systemPromptOverride?.trim();
+    let base: string;
+    if (meshOverride) {
+        base = expandPromptPlaceholders(meshOverride, ctx);
+    } else {
+        const userOverride = readUserPromptFile(coordinatorCliType, 'md');
+        if (userOverride !== null) {
+            base = expandPromptPlaceholders(userOverride, ctx);
+        } else {
+            base = buildDefaultCoordinatorPrompt(ctx);
+        }
+    }
+
+    const sections: string[] = [base];
+
+    // ── User-level append runs after whichever base won ──
+    const userAppend = readUserPromptFile(coordinatorCliType, 'append.md');
+    if (userAppend !== null) {
+        sections.push(expandPromptPlaceholders(userAppend, ctx));
+    }
+
+    // ── Mesh-level append (prefer the new field, fall back to the legacy alias) ──
+    const meshAppend = (mesh.coordinator?.systemPromptAppend
+        ?? mesh.coordinator?.systemPromptSuffix)?.trim();
+    if (meshAppend) {
+        sections.push(expandPromptPlaceholders(meshAppend, ctx));
+    }
+
+    // ── Per-launch context lands last so it's the most recent thing the
+    //     agent reads. Marked as Additional Context, not a rule update. ──
+    if (userInstruction) {
+        sections.push(`## Additional Context\n${userInstruction}`);
+    }
+
+    return sections.join('\n\n');
+}
+
+function buildDefaultCoordinatorPrompt(ctx: CoordinatorPromptContext): string {
+    const { mesh, status, coordinatorCliType } = ctx;
     const sections: string[] = [];
 
     // ── Identity ──
@@ -61,22 +136,88 @@ Repository: \`${mesh.repoIdentity}\`${mesh.defaultBranch ? `\nDefault branch: \`
     // ── Rules ──
     sections.push(buildRulesSection(coordinatorCliType));
 
-    // ── User instruction ──
-    if (userInstruction) {
-        sections.push(`## Additional Context\n${userInstruction}`);
-    }
+    return sections.join('\n\n');
+}
 
-    if (mesh.coordinator?.systemPromptSuffix) {
-        sections.push(mesh.coordinator.systemPromptSuffix);
+/**
+ * Look up a user-customization file under ~/.adhdev/coordinator-prompts/.
+ *
+ * Lookup order:
+ *   1. <cliType>.<suffix>   — provider-specific
+ *   2. default.<suffix>     — shared across providers
+ *
+ * Returns null when neither exists; an empty/whitespace-only file is also
+ * treated as "no override" so users can drop in a stub without affecting
+ * behavior. Read errors (permission, IO) are swallowed and logged-as-null
+ * intentionally: a broken override file should never block coordinator
+ * launch, it should just behave as if the file weren't there.
+ */
+function readUserPromptFile(cliType: string | undefined, suffix: string): string | null {
+    const dir = path.join(os.homedir(), '.adhdev', 'coordinator-prompts');
+    const candidates: string[] = [];
+    if (cliType) candidates.push(path.join(dir, `${cliType}.${suffix}`));
+    candidates.push(path.join(dir, `default.${suffix}`));
+    for (const p of candidates) {
+        try {
+            const text = fs.readFileSync(p, 'utf8');
+            if (text.trim()) return text;
+        } catch { /* missing file is the common case — keep going */ }
     }
+    return null;
+}
 
-    return sections.join('\n\n');
+/**
+ * Expand `{{placeholder}}` tokens against current mesh state.
+ *
+ * Tokens we support today:
+ *   {{meshName}}        — mesh.name
+ *   {{repo}}            — mesh.repoIdentity
+ *   {{defaultBranch}}   — mesh.defaultBranch or empty
+ *   {{cliType}}         — coordinator CLI type or empty
+ *   {{nodes}}           — full node section (status if known, otherwise config)
+ *   {{policy}}          — full policy section
+ *   {{tools}}           — the canonical tools table
+ *   {{workflow}}        — the canonical orchestration workflow
+ *   {{rules}}           — the canonical rules section (with coordinatorNote)
+ *   {{toolExposurePreflight}} — the MCP-missing preflight reminder
+ *
+ * Unknown tokens are left as-is — that way typos are obvious in the rendered
+ * prompt instead of silently disappearing. Tokens are not recursive: an
+ * expanded value's own {{...}} content stays literal.
+ */
+function expandPromptPlaceholders(template: string, ctx: CoordinatorPromptContext): string {
+    const { mesh, status, coordinatorCliType } = ctx;
+    const nodesSection = status?.nodes?.length
+        ? buildNodeStatusSection(status.nodes)
+        : mesh.nodes.length
+            ? buildNodeConfigSection(mesh)
+            : '## Nodes\nNo nodes configured yet. Ask the user to add nodes with `adhdev mesh add-node`.';
+    const replacements: Record<string, string> = {
+        meshName: mesh.name,
+        repo: mesh.repoIdentity,
+        defaultBranch: mesh.defaultBranch || '',
+        cliType: coordinatorCliType || '',
+        nodes: nodesSection,
+        policy: buildPolicySection({ ...DEFAULT_MESH_POLICY, ...(mesh.policy || {}) }),
+        tools: TOOLS_SECTION,
+        workflow: WORKFLOW_SECTION,
+        rules: buildRulesSection(coordinatorCliType),
+        toolExposurePreflight: TOOL_EXPOSURE_PREFLIGHT_SECTION,
+    };
+    return template.replace(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, (m, key) => {
+        return Object.prototype.hasOwnProperty.call(replacements, key) ? replacements[key] : m;
+    });
 }
 
 // ─── Section Builders ───────────────────────────
 
 function buildNodeStatusSection(nodes: RepoMeshNodeStatus[]): string {
-    const lines = ['## Current Node Status', ''];
+    const lines = [
+        '## Current Node Status',
+        '',
+        'Node labels are display context, not aliases. Use exact `nodeId` values in mesh tool calls; do not invent shorthand names such as M1/M2 unless they are explicitly configured labels.',
+        '',
+    ];
     for (const n of nodes) {
         const healthIcon = n.health === 'online' ? '🟢' :
             n.health === 'dirty' ? '🟡' :
@@ -85,31 +226,65 @@ function buildNodeStatusSection(nodes: RepoMeshNodeStatus[]): string {
             ? `sessions: ${n.activeSessions.join(', ')}`
             : 'no active sessions';
         const branch = n.git?.branch ? `branch: \`${n.git.branch}\`` : '';
-        lines.push(`- ${healthIcon} **${n.machineLabel}** (${n.nodeId})`);
-        lines.push(`  workspace: \`${n.workspace}\` | ${branch} | ${sessions}`);
+        const context = [
+            n.daemonId ? `daemon: \`${n.daemonId}\`` : '',
+            n.providers?.length ? `providers: ${n.providers.join(', ')}` : '',
+        ].filter(Boolean).join(' | ');
+        lines.push(`- ${healthIcon} **${n.machineLabel}** (nodeId: \`${n.nodeId}\`)`);
+        lines.push(`  workspace: \`${n.workspace}\`${context ? ` | ${context}` : ''} | ${branch} | ${sessions}`);
         if (n.error) lines.push(`  ⚠️ ${n.error}`);
+        const nodePrompt = typeof (n as any).systemPrompt === 'string' ? (n as any).systemPrompt.trim() : '';
+        if (nodePrompt) {
+            lines.push(`  📌 Node instruction: ${indentFollowing(nodePrompt, '     ')}`);
+        }
     }
     return lines.join('\n');
 }
 
 function buildNodeConfigSection(mesh: LocalMeshEntry): string {
-    const lines = ['## Configured Nodes', ''];
+    const lines = [
+        '## Configured Nodes',
+        '',
+        'Node labels are display context, not aliases. Use exact `nodeId` values in mesh tool calls; do not invent shorthand names such as M1/M2 unless they are explicitly configured labels.',
+        '',
+    ];
     for (const n of mesh.nodes) {
         const labels: string[] = [];
         if (n.isLocalWorktree) labels.push('worktree');
         if (n.policy?.readOnly) labels.push('read-only');
         const suffix = labels.length ? ` [${labels.join(', ')}]` : '';
-        lines.push(`- **${n.workspace}** (${n.id})${suffix}`);
+        const explicitMachineLabel = typeof (n as any).machineLabel === 'string' ? (n as any).machineLabel : '';
+        const explicitLabel = explicitMachineLabel ? ` label: **${explicitMachineLabel}** |` : '';
+        const providerPriority = n.policy?.providerPriority?.length ? ` | providers: ${n.policy.providerPriority.join(', ')}` : '';
+        lines.push(`- ${explicitLabel} nodeId: \`${n.id}\` | workspace: \`${n.workspace}\`${n.daemonId ? ` | daemon: \`${n.daemonId}\`` : ''}${providerPriority}${suffix}`);
+        const nodePrompt = typeof (n as any).systemPrompt === 'string' ? (n as any).systemPrompt.trim() : '';
+        if (nodePrompt) {
+            lines.push(`  📌 Node instruction: ${indentFollowing(nodePrompt, '     ')}`);
+        }
     }
     lines.push('', '_Use `mesh_status` to probe live health before delegating work._');
     return lines.join('\n');
 }
 
+/**
+ * Indent every line after the first by `pad`. Used so multi-line node
+ * instructions still visually nest under the node bullet without the
+ * second line dangling at column zero.
+ */
+function indentFollowing(text: string, pad: string): string {
+    const lines = text.split('\n');
+    if (lines.length === 1) return lines[0];
+    return [lines[0], ...lines.slice(1).map(l => pad + l)].join('\n');
+}
+
 function buildPolicySection(policy: RepoMeshPolicy): string {
     const rules: string[] = [];
     if (policy.requirePreTaskCheckpoint) rules.push('- Create a git checkpoint **before** starting each task');
     if (policy.requirePostTaskCheckpoint) rules.push('- Create a git checkpoint **after** each task completes');
     if (policy.requireApprovalForPush) rules.push('- **Ask for user approval** before pushing to remote');
+    if (policy.allowAutoPublishSubmoduleMainCommits) {
+        rules.push('- Refinery may auto-publish unreachable submodule gitlink commits to submodule origin/main with non-force pushes after validation and patch-equivalence pass');
+    }
     if (policy.requireApprovalForDestructiveGit) rules.push('- **Ask for user approval** before destructive git operations (force push, reset, etc.)');
 
     const dirtyBehavior = {
@@ -140,6 +315,7 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_read_debug\` | Collect a daemon-side chat/parser debug bundle for a session |
 | \`mesh_task_history\` | Read the task ledger — dispatches, completions, failures. Use to understand what has been done before deciding next steps |
 | \`mesh_git_status\` | Check git status on a specific node |
+| \`mesh_fast_forward_node\` | Safely dry-run or explicitly execute an obvious clean fast-forward without launching an agent session |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
 | \`mesh_approve\` | Approve/reject a pending agent action |
 | \`mesh_clone_node\` | Create a worktree node for isolated parallel branch work |
@@ -161,10 +337,10 @@ const WORKFLOW_SECTION = `## Orchestration Workflow
    c. **Targeted Tasks**: Use \`mesh_send_task\` only when you need to bypass the queue and force a specific node to execute a task immediately.
    d. For the first dispatch of a new task, provide a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
    e. For a continuation of the same issue in an existing session, send a concise **delta instruction**: current verified state, the exact failed/blocked step, the newly approved action, and final reporting requirements. Do not resend the full original task or open a new chat solely to continue the same work; that wastes coordinator and worker context.
-4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Use \`mesh_view_queue\` to see the status of all pending, assigned, completed, and failed tasks. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal. Handle approvals via \`mesh_approve\`.
+4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Do **not** repeatedly call \`mesh_status\` or \`mesh_view_queue\` just to wait for assigned/generating work. After dispatching a direct or queued task, send one progress update with the task/session handle, then stop. Wait for \`pendingCoordinatorEvents\` or another completion/approval/status signal, an explicit user status request, or a real timeout/stall signal before reading status/chat/queue again. Use at most one compact \`mesh_read_chat\` check after a terminal signal. Handle approvals via \`mesh_approve\`.
 5. **Verify** — When a task reports completion or git work is visible, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
-7. **Converge branches** — Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary and \`mesh_refine_node\` for clean worktree branches when safe. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
+7. **Converge branches** — Before marking any task complete, classify every touched node/branch into exactly one final state: \`merged_to_main\`, \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\`. Use \`mesh_status\` branchConvergenceSummary. For obvious clean branch catch-up (ahead 0, behind > 0, upstream fresh, no dirty/stash/submodule issues), use \`mesh_fast_forward_node\` dry-run first and execute only when explicitly safe/approved; this avoids consuming an agent session. Use \`mesh_refine_node\` for clean worktree branches when safe. Before/refine merging root commits that contain submodule gitlink changes, require each submodule commit to be reachable from the configured submodule remote main branch, not merely present on a feature ref or local checkout. If \`mesh_refine_node\` returns \`submodule_reachability_failed\` or publish-required evidence, keep the public convergence bucket as \`blocked_review\`; unless \`allowAutoPublishSubmoduleMainCommits\` is explicitly enabled and Refinery reports successful non-force publish plus post-publish verification, ask the user for explicit approval to push/publish the unreachable submodule commit(s) to submodule main, then rerun \`mesh_refine_node\`. Do not merge the root branch until the submodule commit(s) are reachable from submodule origin/main. A task that remains on a non-main branch is not fully complete unless the final report names the follow-up state and next step.
 8. **Clean up** — Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
 9. **Report** — Summarize what was done, what changed, any issues, and the branch convergence state.
 
@@ -188,19 +364,17 @@ function buildRulesSection(coordinatorCliType?: string): string {
 
     return `## Rules
 
-- **Minimize coordinator context.** The coordinator's job is routing, not implementing. Do not read source files, run commands, or analyze code directly — delegate all of that to node agents. Your context should stay lean.
-- **Delegate analysis too.** If you need to understand a bug or explore the codebase, send that investigation as a task to the queue or a node. Do not do it yourself.
-- **Respect explicit provider requests.** If the user names an agent/provider, pass the matching provider type to \`mesh_launch_session\`: Hermes → \`hermes-cli\`, Claude Code/Claude → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`. Never substitute \`claude-cli\` just because the coordinator itself is Claude Code.
-- **Front-load new task messages.** When calling \`mesh_enqueue_task\` or \`mesh_send_task\` for a new task, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
-- **Avoid context-wasting restarts.** For follow-up, retry, commit/push, preview, or cleanup work on the same issue, prefer the existing idle session and send only the delta from its last verified state. Start a fresh chat/session only for genuinely independent work, explicit provider/user request, unsafe transcript contamination, or required branch/worktree isolation.
-- **Don't inspect code.** Treat delegated agent summaries as self-reports, not verification. Verify side effects via \`mesh_git_status\` (including related repo freshness when configured), not by reading source files.
-- **Don't over-parallelize.** Start with 1-2 concurrent tasks. Scale up if they succeed. Never launch a duplicate session or second worker solely because \`mesh_read_chat\` has no final assistant message while the delegated session is still showing tool/terminal activity.
-- **Handle failures with context.** If a task fails, check \`mesh_task_history\` first to see if this task was attempted before and how it failed. Read the chat to understand why, then decide: retry on the same node, reassign to a different node, or escalate to the user.
-- **Check history before starting.** At the beginning of a coordination session, call \`mesh_task_history\` to understand what was previously delegated and its outcomes. This prevents duplicate work and informs recovery decisions.
-- **Keep the user informed.** Report progress after each delegation round — one or two sentences, not a narration.
-- **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
-- **Never fabricate tool results.** Always call the actual tool; never pretend you did.
-- **Clean up worktree nodes.** After a worktree task completes and its changes are merged or checkpointed, call \`mesh_remove_node\` to free resources.
-- **Do not strand completed branches.** A checkpointed or clean feature/worktree branch is not done by itself. Merge/refine it to the mesh default branch, or explicitly report one of \`pushed_feature_branch_needs_merge\`, \`blocked_review\`, \`cleanup_candidate\`, or \`not_mergeable\` with the next action.
-- **Name worktree branches meaningfully.** Use descriptive names like \`feat/auth-refactor\` or \`fix/build-123\`.${coordinatorNote}`;
+- **Route, don't implement.** Delegate all code reading, analysis, and execution to node agents. Never read source files or run commands in the coordinator — keep context lean.
+- **Front-load task messages.** Include everything the agent needs (files, problem, expected fix) in \`mesh_enqueue_task\` / \`mesh_send_task\`. Append a structured result request at the end: ask the worker to conclude with a JSON block containing \`status\`, \`changedFiles\`, \`gitStatus\`, \`validationResults\`, \`errors\`, \`nextAction\`. The daemon parses this automatically; you can read it from \`mesh_task_history\`.
+- **Reuse idle sessions.** For follow-up, retry, commit/push, or cleanup on the same issue, send only the delta to the existing idle session. Start fresh only for independent work, provider mismatch, transcript contamination, or required worktree isolation.
+- **Respect explicit provider requests.** Map: Hermes → \`hermes-cli\`, Claude/Claude Code → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`, Antigravity → \`antigravity-cli\`. Never substitute the coordinator's own runtime.
+- **Verify via git, not source.** Use \`mesh_git_status\` to confirm side effects. Treat agent summaries as self-reports, not verification.
+- **Limit parallelism.** Start with 1–2 tasks; scale only on success. Never duplicate a session because \`mesh_read_chat\` shows no final message while tool/terminal activity is ongoing.
+- **Check history first.** Call \`mesh_task_history\` at session start to avoid duplicate work and inform recovery. On failure, read task history before retrying.
+- **Converge branches.** After worktree tasks: refine/fast-forward, or classify as \`pushed_feature_branch_needs_merge\` / \`blocked_review\` / \`cleanup_candidate\` / \`not_mergeable\`. Clean up with \`mesh_remove_node\`.
+- **Refinery is config-driven.** \`mesh_refine_node\` must run validation from \`.adhdev/refine.{json,yaml,yml}\` or \`repo-mesh.refine.*\`. Heuristics are scaffolding only.
+- **Submodule reachability = publish-needed.** \`submodule_reachability_failed\` → classify as \`blocked_review\`, request user approval to push to submodule main, then rerun \`mesh_refine_node\`.
+- **Honor per-node instructions.** When a node carries a 📌 Node instruction in the nodes section, include the relevant parts of that instruction in the task message you send to that node. Don't paraphrase the instruction into your own words — quote it verbatim so the worker agent sees exactly what the user wrote.
+- **Never fabricate tool results.** Always call the actual tool.
+- **Keep the user informed.** One or two sentences after each delegation round.${coordinatorNote}`;
 }

package/src/mesh/coordinator-registry.ts

@@ -0,0 +1,121 @@
+/**
+ * MeshCoordinatorRegistry — Persisted record of active mesh coordinator sessions.
+ *
+ * Survives daemon restarts: when a CLI coordinator session is re-attached after
+ * a daemon restart the in-memory `settings.meshCoordinatorFor` on the provider
+ * instance is gone, so the registry file fills the gap.
+ *
+ * Keyed by sessionId (the CLI instance key / runtimeKey).
+ */
+
+import { join } from 'path';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { getDaemonDataDir } from '../config/config.js';
+
+export interface CoordinatorRegistryEntry {
+    meshId: string;
+    sessionId: string;
+    workspace?: string;
+    startedAt: number;
+    /** CLI type used to launch the coordinator (claude-cli / codex-cli / …). */
+    cliType?: string;
+    /** Final system prompt sent to the coordinator after all overrides, appends,
+     *  and extraSystemPrompt have been applied. Surfaced via the session-info
+     *  endpoint so users can audit exactly what prompt the agent saw. */
+    systemPrompt?: string;
+    /** Per-launch extraSystemPrompt the caller passed in, if any. Stored
+     *  separately from `systemPrompt` so the UI can show what the user
+     *  added vs. what the daemon's default template produced. */
+    extraSystemPrompt?: string;
+    /** How the prompt was actually injected (cli_arg / context_file / …). */
+    injection?: { mode: string; target?: string };
+    /** Path of the MCP config file the daemon wrote for this session. */
+    mcpConfigPath?: string;
+}
+
+const _registry = new Map<string, CoordinatorRegistryEntry>();
+
+function getRegistryPath(): string {
+    return join(getDaemonDataDir(), 'mesh-coordinators.json');
+}
+
+/** Load persisted coordinator registry from disk into in-memory map. Called once on daemon boot. */
+export function loadMeshCoordinatorRegistry(): void {
+    const path = getRegistryPath();
+    if (!existsSync(path)) return;
+    try {
+        const raw = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!Array.isArray(raw)) return;
+        _registry.clear();
+        for (const entry of raw) {
+            if (typeof entry?.sessionId === 'string' && typeof entry?.meshId === 'string') {
+                _registry.set(entry.sessionId, entry as CoordinatorRegistryEntry);
+            }
+        }
+    } catch { /* ignore corrupt file */ }
+}
+
+function saveRegistry(): void {
+    try {
+        writeFileSync(
+            getRegistryPath(),
+            JSON.stringify([..._registry.values()], null, 2),
+            { encoding: 'utf-8', mode: 0o600 },
+        );
+    } catch { /* best-effort */ }
+}
+
+/** Register a coordinator session. Persists to disk immediately. */
+export function registerMeshCoordinator(entry: CoordinatorRegistryEntry): void {
+    _registry.set(entry.sessionId, entry);
+    saveRegistry();
+}
+
+/** Remove a coordinator session by sessionId. Persists to disk.
+ *
+ * Also best-effort strips any context_file wrapper block we wrote into
+ * the workspace at launch time (AGENTS.md / GEMINI.md), because those
+ * files are auto-loaded by their CLIs on every subsequent launch — and
+ * a wrapper block surviving the coordinator session would silently
+ * inject the coordinator system prompt into ordinary non-coordinator
+ * sessions in the same workspace, which is exactly the bug we're
+ * fixing here.
+ *
+ * Stripping rules:
+ *   - Look for the start sentinel anywhere in the file; if absent,
+ *     leave the file alone (user-authored content).
+ *   - If the wrapper block was the only thing in the file, delete the
+ *     file outright so we don't leave behind an empty AGENTS.md.
+ *   - Otherwise drop only the block between the sentinels and trim a
+ *     leading/trailing blank line so we don't leave dangling separators.
+ */
+export function unregisterMeshCoordinator(sessionId: string): void {
+    const entry = _registry.get(sessionId);
+    if (!_registry.delete(sessionId)) return;
+    saveRegistry();
+    if (!entry) return;
+    const workspace = entry.workspace;
+    const target = entry.injection?.mode === 'context_file' && typeof entry.injection.target === 'string'
+        ? entry.injection.target
+        : '';
+    if (!workspace || !target) return;
+    // injection.target is workspace-relative (AGENTS.md / GEMINI.md); we don't
+    // resolve absolute paths here because we never wrote one — applyMesh-
+    // CoordinatorSystemPromptInjection joins via path.join(workspace, …).
+    const filePath = `${workspace.replace(/\/$/, '')}/${target}`;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { stripCoordinatorWrapperFile } = require('../commands/mesh-coordinator.js');
+        stripCoordinatorWrapperFile(filePath);
+    } catch { /* best-effort cleanup; never throw out of unregister */ }
+}
+
+/** Look up a coordinator entry by session ID. Returns undefined if not registered. */
+export function getCoordinatorForSession(sessionId: string): CoordinatorRegistryEntry | undefined {
+    return _registry.get(sessionId);
+}
+
+/** List all coordinator entries for a given workspace path. */
+export function listCoordinatorsForWorkspace(workspace: string): CoordinatorRegistryEntry[] {
+    return [..._registry.values()].filter(e => e.workspace === workspace);
+}