@adhdev/daemon-core 0.9.82-rc.160 → 0.9.82-rc.162

package/src/config/chat-history.ts

@@ -1421,6 +1421,8 @@ function callProviderNativeHistoryRead(
     historySessionId: string | undefined,
     workspace?: string,
     excludeInProgressTurn?: boolean,
+    sessionStartedAtMs?: number,
+    envOverrides?: Record<string, string>,
 ): ProviderNativeHistoryReadResult | null {
     const fn = getProviderNativeHistoryScript(scripts, canonicalHistory, 'readSession');
     if (!fn) return null;
@@ -1433,7 +1435,9 @@ function callProviderNativeHistoryRead(
         format: canonicalHistory?.format,
         watchPath: canonicalHistory?.watchPath,
         excludeInProgressTurn: excludeInProgressTurn === true,
-        args: { sessionId: normalizedSessionId, historySessionId: normalizedSessionId, workspace, excludeInProgressTurn: excludeInProgressTurn === true },
+        sessionStartedAtMs,
+        envOverrides,
+        args: { sessionId: normalizedSessionId, historySessionId: normalizedSessionId, workspace, excludeInProgressTurn: excludeInProgressTurn === true, sessionStartedAtMs, envOverrides },
     });
     if (!result || typeof result !== 'object') return null;
     const records = normalizeProviderNativeHistoryRecords(agentType, normalizedSessionId, (result as any).messages || (result as any).records);
@@ -1456,11 +1460,13 @@ function buildNativeHistoryReadResult(
     historySessionId: string | undefined,
     workspace?: string,
     excludeInProgressTurn?: boolean,
+    sessionStartedAtMs?: number,
+    envOverrides?: Record<string, string>,
 ): ProviderNativeHistoryReadResult | null {
     const normalizedSessionId = normalizeSavedHistorySessionId(historySessionId || '');
     const normalizedWorkspace = typeof workspace === 'string' ? workspace.trim() : '';
     if (!canonicalHistory || (!normalizedSessionId && !normalizedWorkspace) || !isNativeSourceCanonicalHistory(canonicalHistory)) return null;
-    return callProviderNativeHistoryRead(agentType, canonicalHistory, scripts, normalizedSessionId, workspace, excludeInProgressTurn);
+    return callProviderNativeHistoryRead(agentType, canonicalHistory, scripts, normalizedSessionId, workspace, excludeInProgressTurn, sessionStartedAtMs, envOverrides);
 }
 
 function materializeNativeHistoryToMirror(
@@ -1517,6 +1523,8 @@ export function readProviderChatHistory(
         historyBehavior?: ProviderHistoryBehavior;
         scripts?: ProviderNativeHistoryScripts;
         excludeInProgressTurn?: boolean;
+        sessionStartedAtMs?: number;
+        envOverrides?: Record<string, string>;
     } = {},
 ): {
     messages: HistoryMessage[];
@@ -1530,7 +1538,7 @@ export function readProviderChatHistory(
     unavailableReason?: string;
 } {
     if (isNativeSourceCanonicalHistory(options.canonicalHistory) && (options.historySessionId || options.workspace)) {
-        const nativeResult = buildNativeHistoryReadResult(agentType, options.canonicalHistory, options.scripts, options.historySessionId, options.workspace, options.excludeInProgressTurn);
+        const nativeResult = buildNativeHistoryReadResult(agentType, options.canonicalHistory, options.scripts, options.historySessionId, options.workspace, options.excludeInProgressTurn, options.sessionStartedAtMs, options.envOverrides);
         if (!nativeResult) return { messages: [], hasMore: false, source: 'native-unavailable' };
         return {
             ...pageHistoryRecords(agentType, nativeResult.records, options.offset || 0, options.limit || 30, options.excludeRecentCount || 0, options.historyBehavior),

package/src/config/mesh-config.ts

@@ -484,7 +484,14 @@ export function removeNode(meshId: string, nodeId: string): boolean {
 export function updateNode(
     meshId: string,
     nodeId: string,
-    opts: { userOverrides?: Partial<RepoMeshNodeCapabilities>; policy?: RepoMeshNodePolicy; worktreeBootstrap?: LocalMeshNodeEntry['worktreeBootstrap'] },
+    opts: {
+        userOverrides?: Partial<RepoMeshNodeCapabilities>;
+        policy?: RepoMeshNodePolicy;
+        worktreeBootstrap?: LocalMeshNodeEntry['worktreeBootstrap'];
+        /** Per-node instruction surfaced in the coordinator prompt. Pass an
+         *  empty string or undefined to clear it. */
+        systemPrompt?: string;
+    },
 ): LocalMeshNodeEntry | undefined {
     const config = loadMeshConfig();
     const mesh = config.meshes.find(m => m.id === meshId);
@@ -496,6 +503,14 @@ export function updateNode(
     if (opts.userOverrides) node.userOverrides = { ...node.userOverrides, ...opts.userOverrides };
     if (opts.policy) node.policy = { ...node.policy, ...opts.policy };
     if (opts.worktreeBootstrap) node.worktreeBootstrap = opts.worktreeBootstrap;
+    if (Object.prototype.hasOwnProperty.call(opts, 'systemPrompt')) {
+        // Honor explicit clears: { systemPrompt: undefined } drops the field.
+        if (opts.systemPrompt && opts.systemPrompt.trim()) {
+            node.systemPrompt = opts.systemPrompt;
+        } else {
+            delete node.systemPrompt;
+        }
+    }
     mesh.updatedAt = new Date().toISOString();
     saveMeshConfig(config);
     return node;

package/src/index.ts

@@ -467,6 +467,25 @@ export {
   type IpcStatusPayload,
 } from './ipc/local-ipc-server.js';
 
+// ── CLI Spec (adhdev:cli/spec@1) ──
+export { evaluate as evaluateSpec, evaluate } from './providers/spec/evaluator.js';
+export { loadSpec, resolveSpecPath } from './providers/spec/loader.js';
+export { createNativeHistoryDispatcher } from './providers/native-history/index.js';
+export type { ReaderId } from './providers/native-history/index.js';
+export {
+    readClaudeCliSession, readCodexCliSession,
+    readAntigravityCliSession, readHermesCliSession,
+} from './providers/native-history/index.js';
+export type {
+    CliSpec, SpecState, ControlAction, Control,
+    NotificationRule, DelegateTrigger, Section,
+} from './providers/spec/types.js';
+export type { SpecEvaluation, TraceEntry } from './providers/spec/evaluator.js';
+export { SpecDriver } from './providers/spec/driver.js';
+export type { DashboardEvent, DashboardCommand, SpecDriverOpts } from './providers/spec/driver.js';
+export { TerminalAdapter } from './providers/spec/adapter.js';
+export type { TerminalAdapterOpts, TerminalAdapterHandlers } from './providers/spec/adapter.js';
+
 // ── Provider SDK (v1) — selective re-exports for external tooling ──
 // Tooling (registry publish, dashboard validators, the e2e harness) needs
 // the manifest validator, the builder catalog, and the contract version.

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,16 +136,77 @@ 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 ───────────────────────────
@@ -97,6 +233,10 @@ function buildNodeStatusSection(nodes: RepoMeshNodeStatus[]): string {
         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');
 }
@@ -117,11 +257,26 @@ function buildNodeConfigSection(mesh: LocalMeshEntry): string {
         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');
@@ -219,6 +374,7 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **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

@@ -17,6 +17,20 @@ export interface CoordinatorRegistryEntry {
     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>();
@@ -57,11 +71,43 @@ export function registerMeshCoordinator(entry: CoordinatorRegistryEntry): void {
     saveRegistry();
 }
 
-/** Remove a coordinator session by sessionId. Persists to disk. */
+/** 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 {
-    if (_registry.delete(sessionId)) {
-        saveRegistry();
-    }
+    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. */

package/src/providers/cli-provider-instance.ts

@@ -15,6 +15,7 @@ import { assertProviderSupportsDeclaredInput, getEffectiveMessageInputSupport }
 import type { ProviderInstance, ProviderState, ProviderEvent, InstanceContext, ProviderErrorReason, HotChatSessionState, SessionModalState } from './provider-instance.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { CliProviderModule } from '../cli-adapters/provider-cli-adapter.js';
+import { createCliAdapter } from './spec/route.js';
 import type { PtyRuntimeMetadata, PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import { StatusMonitor } from './status-monitor.js';
 import { ChatHistoryWriter, isNativeSourceCanonicalHistory, materializeProviderNativeHistory, readChatHistory, readProviderChatHistory } from '../config/chat-history.js';
@@ -389,7 +390,7 @@ export class CliProviderInstance implements ProviderInstance {
         this.providerSessionId = options?.providerSessionId;
         this.launchMode = options?.launchMode || 'new';
         this.onProviderSessionResolved = options?.onProviderSessionResolved;
-        this.adapter = new ProviderCliAdapter(provider as CliProviderModule, workingDir, cliArgs, options?.extraEnv || {}, transportFactory);
+        this.adapter = createCliAdapter(provider as CliProviderModule, workingDir, cliArgs, options?.extraEnv || {}, transportFactory) as ProviderCliAdapter;
         if (this.providerSessionId) {
             this.adapter.updateRuntimeMeta({ providerSessionId: this.providerSessionId });
         }
@@ -727,13 +728,17 @@ export class CliProviderInstance implements ProviderInstance {
         };
     }
 
-    getSessionModalState(): SessionModalState {
+    getSessionModalState(sessionId?: string): SessionModalState {
         const adapterStatus = this.adapter.getStatus({ allowParse: false });
         const autoApproveActive = adapterStatus.status === 'waiting_approval' && this.shouldAutoApprove();
         const visibleStatus = autoApproveActive ? 'generating' : adapterStatus.status;
         const dirName = this.workingDir.split('/').filter(Boolean).pop() || 'session';
         return {
-            id: this.instanceId,
+            // Honor the caller-supplied sessionId — InstanceMgr rejects the
+            // projection when projected.id !== requested sessionId, and
+            // this.instanceId is the manager's internal key, not the public
+            // sessionId the dashboard subscribes by.
+            id: sessionId ?? this.instanceId,
             status: visibleStatus,
             title: dirName,
             activeModal: autoApproveActive ? null : adapterStatus.activeModal,

package/src/providers/contracts.ts

@@ -393,8 +393,61 @@ export interface ProviderMeshCoordinatorConfig {
     /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{workspace}}, {{serverName}}. */
     template?: string;
   };
+  /**
+   * How the coordinator system prompt reaches the launched CLI. Replaces the
+   * old hard-coded `if (cliType === 'claude-cli') push --append-system-prompt`
+   * branches in router.ts: a new CLI now ships its injection rule in its
+   * provider.v1.json, no daemon code change needed. Users can override the
+   * rendered prompt or the injection mechanism per-provider; if omitted, no
+   * system prompt is injected (safe default — won't crash spawn with a flag
+   * the CLI doesn't recognize).
+   */
+  systemPromptInjection?: MeshCoordinatorSystemPromptInjection;
 }
 
+/**
+ * Declarative description of how a CLI accepts a session-scoped system prompt.
+ *
+ * Modes:
+ *   - cli_arg          → push `flag` + prompt onto spawn args                (Claude)
+ *   - config_override  → push `flag` + a templated key=value config override (Codex)
+ *   - context_file     → write prompt into a workspace markdown the CLI
+ *                        auto-loads as project context                       (Gemini, Antigravity)
+ *   - env_var          → expose prompt to the spawned process as $name       (Hermes)
+ *
+ * The prompt text is templated with `{prompt}` (raw) or `{prompt_json}`
+ * (JSON-encoded for embedding inside config-override strings).
+ */
+export type MeshCoordinatorSystemPromptInjection =
+  | {
+      mode: 'cli_arg';
+      /** Spawn-args flag, e.g. '--append-system-prompt'. The prompt becomes the next argv. */
+      flag: string;
+    }
+  | {
+      mode: 'config_override';
+      /** Spawn-args flag, e.g. '-c'. Followed by `template` with placeholders rendered. */
+      flag: string;
+      /** Template using {prompt} or {prompt_json}, e.g. 'developer_instructions={prompt_json}'. */
+      template: string;
+    }
+  | {
+      mode: 'context_file';
+      /** Workspace-relative file path the CLI auto-loads, e.g. 'AGENTS.md' or 'GEMINI.md'. */
+      path: string;
+      /**
+       * Optional wrapper around the prompt. Use `{prompt}` placeholder. Existing
+       * wrapper-delimited blocks are replaced rather than duplicated, so re-launching
+       * a coordinator doesn't pile up copies. If omitted, the prompt is appended raw.
+       */
+      wrapper?: string;
+    }
+  | {
+      mode: 'env_var';
+      /** Env-var name, e.g. 'HERMES_EPHEMERAL_SYSTEM_PROMPT'. */
+      name: string;
+    };
+
 export interface ProviderCompatibilityEntry {
   ideVersion: string;
   scriptDir: string;

package/src/providers/native-history/antigravity-cli-transcript.ts

@@ -397,11 +397,11 @@ function parsePbFile(
  *
  * Returns `null` when the file is missing, empty, or yields no parseable messages.
  */
-export async function readSession(
+export function readSession(
   sessionPath: string,
   sessionId?: string,
   workspace?: string,
-): Promise<NativeHistorySession | null> {
+): NativeHistorySession | null {
   if (!sessionPath || !path.isAbsolute(sessionPath)) return null;
   if (!fs.existsSync(sessionPath)) return null;
 

package/src/providers/native-history/claude-cli-transcript.ts

@@ -296,7 +296,7 @@ function parseTranscriptFile(
  * `sessionPath` is the absolute path to a `<uuid>.jsonl` file.
  * Returns `null` when the file is missing, empty, or yields no parseable messages.
  */
-export async function readSession(sessionPath: string): Promise<NativeHistorySession | null> {
+export function readSession(sessionPath: string): NativeHistorySession | null {
   if (!sessionPath || !path.isAbsolute(sessionPath)) return null;
 
   const basename = path.basename(sessionPath, '.jsonl');

package/src/providers/native-history/codex-cli-transcript.ts

@@ -302,7 +302,7 @@ function parseSessionFile(
  * under ~/.codex/sessions/.
  * Returns `null` when the file is missing, empty, or yields no parseable messages.
  */
-export async function readSession(sessionPath: string): Promise<NativeHistorySession | null> {
+export function readSession(sessionPath: string): NativeHistorySession | null {
   if (!sessionPath || !path.isAbsolute(sessionPath)) return null;
   if (!fs.existsSync(sessionPath)) return null;