@jini-ai/daemon 0.3.0 → 0.3.2

package/dist/agent-executor.js

@@ -94,7 +94,7 @@ import { promises as fsPromises } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { redactSecrets } from '@jini-ai/core';
-import { applyAgentLaunchEnv, createClaudeStreamHandler, createCopilotStreamHandler, createJsonEventStreamHandler, createQoderStreamHandler, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, checkPromptArgvBudget, checkWindowsCmdShimCommandLineBudget, checkWindowsDirectExeCommandLineBudget, prepareAgentLogFile, preparePromptFileForAgent, } from '@jini-ai/agent-runtime';
+import { agentCapabilities, applyAgentLaunchEnv, createClaudeStreamHandler, createCopilotStreamHandler, createJsonEventStreamHandler, createQoderStreamHandler, getAgentDef, resolveAgentLaunch, attachAcpSession, attachPiRpcSession, checkPromptArgvBudget, checkWindowsCmdShimCommandLineBudget, checkWindowsDirectExeCommandLineBudget, prepareAgentLogFile, preparePromptFileForAgent, } from '@jini-ai/agent-runtime';
 import { collectProcessTreePids, createCommandInvocation, listProcessSnapshots, stopProcesses, } from '@jini-ai/platform';
 import { classifyRunCloseStatus } from './close-status.js';
 import { resolveContinuationTransport } from './continuation/continuation-transport.js';
@@ -743,6 +743,60 @@ export function mergeEnvContentMcpConfig(existingRaw, entry) {
     };
     return JSON.stringify({ ...doc, mcp });
 }
+/**
+ * Merges a staged system-prompt overlay file's path into the `instructions` array of the same
+ * OpenCode-schema config document {@link mergeEnvContentMcpConfig} writes `mcp` into — for a
+ * `systemPromptDelivery: { strategy: 'config-instructions-file' }` def (`opencode` today).
+ *
+ * Confirmed live (2026-09-01, opencode-cli 1.17.10), not inferred from docs alone:
+ *   1. `instructions` is honored — a run configured with it visibly followed the file's directive
+ *      (a required exact-token prefix), while an identical run without it did not.
+ *   2. It appends, never replaces: the same run that followed the custom instruction ALSO still
+ *      answered correctly using opencode's own baked-in environment-context system prompt (asked
+ *      for its cwd, with nothing about cwd anywhere in the custom instructions file) — proof
+ *      opencode's own defaults survive alongside a custom `instructions` entry, not just proof the
+ *      file was read at all.
+ *   3. Adding this key alongside `mcp` in the same `OPENCODE_CONFIG_CONTENT` document disturbs
+ *      neither: in one combined run, the MCP bridge still got its connection attempt (logged
+ *      `key=jini type=local`) AND the custom instruction was still followed — same as running each
+ *      key alone.
+ *   4. `instructions` is re-read fresh from the env on every spawn, including a `-s <id>`-resumed
+ *      turn (proved by swapping in a second instructions file between two turns of one resumed
+ *      session and seeing the second turn immediately reflect it while still recalling
+ *      conversation memory from turn one) — so this mechanism is safe to redeliver every turn like
+ *      `'append-flag'`/`'env-var'`, exempt from the prompt-prefix fallback's create-only gating
+ *      (see {@link resolveSystemPromptOverlayDelivery}'s doc): nothing here is ever baked into
+ *      opencode's own persisted session state the way re-injecting fallback prompt text would be.
+ *
+ * @param existingRaw - Whatever the spawn env already held for this variable (already possibly
+ * carrying `mcp`, if `mergeEnvContentMcpConfig` ran first on the same value — order between the two
+ * doesn't matter, each only touches its own top-level key), or `undefined`.
+ * @param instructionsFilePath - The staged overlay file's absolute path (see
+ * {@link prepareSystemPromptOverlayFileIfNeeded}).
+ * @returns The full JSON string to set as the env var's value. Appends to, never clobbers, any
+ * `instructions` entries already present — the same "merge, never clobber" discipline
+ * {@link mergeEnvContentMcpConfig} applies to `mcp`, in case a host is already using this same
+ * config-content variable to carry the operator's own instruction files.
+ * @complexity O(1) plus `JSON.parse`/`JSON.stringify` over a small config document.
+ * @overallScore 100/100
+ */
+export function mergeEnvContentInstructions(existingRaw, instructionsFilePath) {
+    let doc = {};
+    if (existingRaw !== undefined && existingRaw.length > 0) {
+        try {
+            const parsed = JSON.parse(existingRaw);
+            if (isRecord(parsed))
+                doc = parsed;
+        }
+        catch {
+            doc = {};
+        }
+    }
+    const existingInstructions = Array.isArray(doc.instructions)
+        ? doc.instructions.filter((entry) => typeof entry === 'string')
+        : [];
+    return JSON.stringify({ ...doc, instructions: [...existingInstructions, instructionsFilePath] });
+}
 /**
  * TOML basic-string escaping for the narrow value shapes {@link buildCodexMcpServerToml} emits (a
  * command name, an argv token, an env var value — never multi-line or control-character-heavy
@@ -795,31 +849,61 @@ export function buildCodexMcpServerToml(entry) {
         return serverTable;
     return `${serverTable}\n[mcp_servers.${JINI_MCP_SERVER_KEY}.env]\n${envLines.join('\n')}\n`;
 }
+/**
+ * Removes any pre-existing `[mcp_servers.{@link JINI_MCP_SERVER_KEY}]` table — and its
+ * `[mcp_servers.{@link JINI_MCP_SERVER_KEY}.*]` subtables (e.g. `.env`) — from a real Codex
+ * `config.toml`'s raw text, so {@link buildCodexHomeConfigToml} can append this run's own table
+ * without producing the duplicate TOML key Codex's parser rejects at startup.
+ *
+ * Line-oriented, not a real TOML parser (matching {@link buildCodexMcpServerToml}'s own
+ * no-TOML-dependency constraint): a table header is any line that is, after trimming, exactly
+ * `[...]`. Once such a header's key matches the jini table or one of its subtables, every following
+ * line is dropped until the next table header (of any name) or EOF. Every other table, key, and
+ * blank line is passed through untouched.
+ * @param existingRaw - The real Codex home's `config.toml` content, already known to be defined
+ * (callers pass `''` for a missing file).
+ * @returns `existingRaw` with any jini table/subtable removed.
+ * @complexity O(n) in the number of lines.
+ */
+function stripExistingJiniMcpServerTable(existingRaw) {
+    const jiniTableKey = `mcp_servers.${JINI_MCP_SERVER_KEY}`;
+    const kept = [];
+    let skipping = false;
+    for (const line of existingRaw.split('\n')) {
+        const header = /^\s*\[([^[\]]+)\]\s*$/.exec(line);
+        if (header) {
+            const key = (header[1] ?? '').trim();
+            skipping = key === jiniTableKey || key.startsWith(`${jiniTableKey}.`);
+            if (skipping)
+                continue;
+        }
+        if (!skipping)
+            kept.push(line);
+    }
+    return kept.join('\n');
+}
 /**
  * Builds the full `config.toml` a run's scratch `CODEX_HOME` gets: the real Codex home's own
- * config, verbatim, with this run's `[mcp_servers.jini]` table appended.
+ * config, with any pre-existing `[mcp_servers.jini]` table removed (see
+ * {@link stripExistingJiniMcpServerTable}), then this run's own table appended.
  *
- * **Append-only by design, not a parse-and-merge.** `mergeMcpJsonContent`/`mergeEnvContentMcpConfig`
- * above can safely parse-merge-reserialize because their formats have a JS-native parser
- * (`JSON.parse`); this driver has no TOML parser in its dependency graph (see
- * `buildCodexMcpServerToml`'s doc), and every other setting a real Codex install carries — model
- * choice, sandbox policy, the trusted-project list, the operator's own other MCP servers — must
- * survive a spawn byte-for-byte. Appending preserves all of it; the one failure mode this trades
- * away is a PRE-EXISTING `[mcp_servers.jini]` table in the operator's own config, which would
- * produce a duplicate TOML key Codex rejects at startup. Accepted as vanishingly unlikely — `jini`
- * is this integration's own reserved server name (see {@link JINI_MCP_SERVER_KEY}), never suggested
- * to an operator for their own config — rather than solved with a full TOML parser for one
- * collision case.
+ * **Append-only by design, not a parse-and-merge, for everything but the jini table itself.**
+ * `mergeMcpJsonContent`/`mergeEnvContentMcpConfig` above can safely parse-merge-reserialize because
+ * their formats have a JS-native parser (`JSON.parse`); this driver has no general TOML parser in
+ * its dependency graph (see `buildCodexMcpServerToml`'s doc), and every other setting a real Codex
+ * install carries — model choice, sandbox policy, the trusted-project list, the operator's own
+ * other MCP servers — must survive a spawn byte-for-byte. Only the one table this driver itself
+ * owns (`jini` is this integration's own reserved server name — see {@link JINI_MCP_SERVER_KEY}) is
+ * ever removed, via the narrow line-oriented scan above, never a full TOML parse.
  * @param existingRaw - The real Codex home's `config.toml` content, or `undefined` when it does not
  * exist (a fresh Codex install — degrades to "start from just this run's block", matching
  * {@link mergeMcpJsonContent}'s own "missing file" handling).
  * @param entry - The shared bridge entry.
  * @returns The full text to write to the scratch `CODEX_HOME`'s `config.toml`.
  * @complexity O(n) in the existing config's length.
- * @overallScore 100/100
  */
 export function buildCodexHomeConfigToml(existingRaw, entry) {
-    const base = existingRaw ?? '';
+    const base = stripExistingJiniMcpServerTable(existingRaw ?? '');
     const separator = base.length === 0 ? '' : base.endsWith('\n') ? '\n' : '\n\n';
     return `${base}${separator}${buildCodexMcpServerToml(entry)}`;
 }
@@ -875,6 +959,8 @@ export function buildMcpBridgeDelivery(input) {
             return { kind: 'env-content', envVarName: ENV_CONTENT_VAR_BY_STRATEGY[strategy], serverEntry };
         case 'codex-toml':
             return { kind: 'codex-toml', serverEntry };
+        case 'env-passthrough':
+            return { kind: 'env-passthrough', serverEntry };
     }
 }
 function defaultReadMcpJsonFile(path) {
@@ -1810,28 +1896,47 @@ export async function resolveMcpBridgeForRun(input, deps) {
     }
 }
 /**
- * Phase 6a/10c: the subprocess environment every env-riding MCP mechanism uses — mechanism 3+4
+ * Phase 6a/10c: the subprocess environment every env-riding mechanism uses — mechanism 3+4
  * (`'opencode-env-content'`/`'mimo-env-content'`, merged into whatever the host already set there,
  * never a CLI argument: the config embeds `JINI_DAEMON_TOKEN`, and process arguments are readable
- * by any other local user through `ps`) and mechanism 5 (`'codex-toml'`, `CODEX_HOME` relocation).
- * Pure — `codexHomeDir` arrives already staged by {@link prepareCodexHomeIfNeeded}, which is the
- * one part of this mechanism that is NOT pure (a real `mkdtemp`).
+ * by any other local user through `ps`), mechanism 5 (`'codex-toml'`, `CODEX_HOME` relocation),
+ * mechanism 6 (`'env-passthrough'`, the bridge entry's flat env vars set directly with no carrier
+ * document — see {@link McpBridgeDelivery}'s own doc), a
+ * `systemPromptDelivery: 'env-var'` def's overlay (`reasonix`'s `REASONIX_ACP_SYSTEM_APPEND` today
+ * — see `resolveSystemPromptOverlayDelivery`'s own doc), and a `'config-instructions-file'` def's
+ * staged overlay file (`opencode` today — see {@link mergeEnvContentInstructions}'s own doc). Pure
+ * — `codexHomeDir` and `stagedInstructionsFile` arrive already staged by
+ * {@link prepareCodexHomeIfNeeded} and {@link prepareSystemPromptOverlayFileIfNeeded} respectively,
+ * the only parts of this mechanism that are NOT pure (real `mkdtemp`/`writeFile` calls).
  * @param spawnEnv - The env every other spawn-time step (launch-path resolution, `applyAgentLaunchEnv`) already computed.
  * @param mcpBridge - This run's resolved bridge delivery, or `null` for an unconfigured host / no-strategy def.
  * @param codexHomeDir - The staged scratch `CODEX_HOME` path for a `'codex-toml'` def, or `undefined` for every other run (including a `'codex-toml'` def when `mcpJsonInjection` was never configured — see `prepareCodexHomeIfNeeded`'s own gate).
- * @complexity O(1) plus `mergeEnvContentMcpConfig`'s own `JSON.parse`/`JSON.stringify` cost.
+ * @param systemPromptEnvOverrides - `resolveSystemPromptOverlayDelivery`'s `envOverrides` — `{}` (default) for every def but an `'env-var'`-strategy one with an overlay present, in which case it carries that one var. Applied after `codexHomeDir`, so it can never be shadowed by it — the two never share a key (`CODEX_HOME` vs. e.g. `REASONIX_ACP_SYSTEM_APPEND`), so the ordering is a documentation choice, not a correctness one.
+ * @param stagedInstructionsFile - `varName` (from the def's own `systemPromptDelivery` declaration) and the staged overlay file's `path`, or `undefined` for every def but a `'config-instructions-file'` one with an overlay present. Merged into `varName`'s value AFTER the `mcp` merge above (reading `envContentApplied`, not the original `spawnEnv`, for that same key) so both a `mcp` entry and an `instructions` entry from the two mechanisms survive together in one document — confirmed live this coexistence is safe (see {@link mergeEnvContentInstructions}'s doc).
+ * @complexity O(1) plus `mergeEnvContentMcpConfig`'s and `mergeEnvContentInstructions`'s own `JSON.parse`/`JSON.stringify` cost.
  * @overallScore 100/100
  */
-export function computeChildEnv(spawnEnv, mcpBridge, codexHomeDir) {
+export function computeChildEnv(spawnEnv, mcpBridge, codexHomeDir, systemPromptEnvOverrides, stagedInstructionsFile) {
     const envContentApplied = mcpBridge?.kind === 'env-content'
         ? {
             ...spawnEnv,
             [mcpBridge.envVarName]: mergeEnvContentMcpConfig(spawnEnv[mcpBridge.envVarName], mcpBridge.serverEntry),
         }
         : spawnEnv;
-    if (codexHomeDir === undefined)
-        return envContentApplied;
-    return { ...envContentApplied, CODEX_HOME: codexHomeDir };
+    // `'env-passthrough'` (antigravity): no document, no named carrier variable — the bridge
+    // entry's own `env` keys (`JINI_RUN_ID`/`JINI_DAEMON_URL`/`JINI_DAEMON_TOKEN`) are set directly
+    // on the child's environment, for the spawned CLI to inherit down to its own globally
+    // pre-registered MCP child in turn. See `McpBridgeDelivery`'s own doc for why this def has no
+    // config document to merge into at all.
+    const envPassthroughApplied = mcpBridge?.kind === 'env-passthrough' ? { ...envContentApplied, ...mcpBridge.serverEntry.env } : envContentApplied;
+    const instructionsApplied = stagedInstructionsFile === undefined
+        ? envPassthroughApplied
+        : {
+            ...envPassthroughApplied,
+            [stagedInstructionsFile.varName]: mergeEnvContentInstructions(envPassthroughApplied[stagedInstructionsFile.varName], stagedInstructionsFile.path),
+        };
+    const codexHomeApplied = codexHomeDir === undefined ? instructionsApplied : { ...instructionsApplied, CODEX_HOME: codexHomeDir };
+    return systemPromptEnvOverrides === undefined ? codexHomeApplied : { ...codexHomeApplied, ...systemPromptEnvOverrides };
 }
 /**
  * Phase 6b: the `RuntimeContext` `buildArgs` receives — `undefined` unless a file, bridge path, or
@@ -1898,10 +2003,130 @@ export function buildAgentBuildArgsOptions(input, systemPromptOverlay) {
         ...(hasOverlay ? { systemPromptOverlay } : {}),
     };
 }
-/** Phase 9b: calls the def's `buildArgs`, releasing staged resources and failing the run on a throw. */
+/**
+ * **The single dispatch point from a computed system-prompt overlay to its delivery mechanism** —
+ * see `RuntimeAgentDef.systemPromptDelivery`'s own doc for the declared shape. Pure and
+ * synchronous, mirroring {@link buildMcpBridgeDelivery}'s "keyed off the declared strategy, never
+ * off the def's id" contract: a def earns overlay delivery by declaring a strategy, not by being
+ * named in this file. That is what makes every def with no declaration work via the fallback
+ * without any of their own files being touched.
+ *
+ * The fallback (no declared strategy — every def but `claude` today) prefixes the overlay directly
+ * onto the composed prompt text, clearly delimited from the user's own request. It is gated on
+ * session state, not merely on whether an overlay exists: a def that carries its own conversation
+ * memory across spawns (`resumesSessionViaCli` / `resumesSessionViaAcpLoad`) persists whatever its
+ * session-creating turn sends it — see `RuntimeContext.resumeSessionId`'s own doc: its presence on
+ * a run means "continue a prior session", not "start one". Prefixing on every later turn of that
+ * same session would therefore bake the overlay into the CLI's own stored history again and again,
+ * compounding without bound turn over turn. So the fallback prefixes only when there is no resume
+ * target yet (the session's own first turn, or a def with no session memory at all, which never
+ * replays anything back at the CLI and so gets it on every turn).
+ *
+ * `'append-flag'` and `'env-var'` defs are the opposite case: the flag/env var is a fresh,
+ * un-stored per-spawn directive — never part of what a resumed session replays — so it is set on
+ * every turn unconditionally, exactly `claude`'s pre-existing (now-centralized) behavior before
+ * this function existed.
+ *
+ * @param input.defId - Looks up this def's probed capabilities for an `'append-flag'` strategy's
+ * `capabilityKey`. Otherwise unused — the dispatch itself is keyed off `systemPromptDelivery`, per
+ * this function's own doc above, never off the id.
+ * @param input.systemPromptDelivery - The def's declared strategy, or `undefined` for the fallback.
+ * @param input.resumesSessionViaCli - The def's own flag (see `RuntimeAgentDef`'s doc).
+ * @param input.resumesSessionViaAcpLoad - The def's own flag (see `RuntimeAgentDef`'s doc).
+ * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result. `null`/`undefined`/
+ * empty short-circuits to "no delivery" — byte-identical to no `PromptAugmenter` configured at all.
+ * @param input.prompt - The composed prompt `buildArgs` would otherwise receive verbatim.
+ * @param input.resumeSessionId - This run's `RuntimeContext.resumeSessionId`; presence means an
+ * existing session is being continued, not created.
+ * @returns A {@link SystemPromptOverlayDelivery}: the prefix this run's prompt text must carry
+ * (`''` unless the fallback applies), that prefix already applied to `input.prompt`, any extra argv
+ * to append to whatever `buildArgs` itself returns, and any env var overrides to merge into the
+ * spawn env (`{}` for every strategy but `'env-var'`). Every one of `run()`'s four prompt
+ * transports consumes this same result — see the interface's own no-double-delivery note.
+ * @complexity O(n) in the overlay/prompt lengths — string concatenation only, no I/O.
+ * @overallScore 100/100
+ */
+export function resolveSystemPromptOverlayDelivery(input) {
+    const { defId, systemPromptDelivery, resumesSessionViaCli, resumesSessionViaAcpLoad, overlay, prompt, resumeSessionId } = input;
+    if (typeof overlay !== 'string' || overlay.length === 0) {
+        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
+    }
+    if (systemPromptDelivery?.strategy === 'append-flag') {
+        const capabilityKey = systemPromptDelivery.capabilityKey;
+        // `!== false`, not a truthiness check: mirrors `claude.ts`'s own pre-existing
+        // `agentCapabilities.get('claude') || {}` gate exactly (moved here, not changed) — an
+        // undetected/never-probed capability defaults to allowed, and only an EXPLICIT `false` (the
+        // `--help` probe ran and did not find the flag) withholds it. `capabilityKey === undefined`
+        // (e.g. `pi`'s existing `--append-system-prompt`, trusted unconditionally) always passes, same
+        // as an absent key.
+        const capabilityOk = capabilityKey === undefined || agentCapabilities.get(defId)?.[capabilityKey] !== false;
+        return { promptPrefix: '', prompt, extraArgs: capabilityOk ? [systemPromptDelivery.flag, overlay] : [], envOverrides: {} };
+    }
+    if (systemPromptDelivery?.strategy === 'env-var') {
+        // No capability gate, unlike `'append-flag'`: an unrecognized env var is inert to a CLI (it
+        // simply never reads it), never a fatal "unknown option" exit — there is no equivalent hazard
+        // to probe-gate against here. Set verbatim, not merged with any existing value — a dedicated
+        // single-purpose var, not a shared config channel (see this field's own `types.ts` doc).
+        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: { [systemPromptDelivery.varName]: overlay } };
+    }
+    if (systemPromptDelivery?.strategy === 'config-instructions-file') {
+        // Delivered elsewhere, not here: unlike `'append-flag'`/`'env-var'`, this mechanism needs real
+        // filesystem I/O (staging the overlay to a temp file — `opencode`'s `instructions` array only
+        // accepts a file path or URL, confirmed live, never inline text), which this function's "pure
+        // and synchronous" contract cannot perform. `prepareSystemPromptOverlayFileIfNeeded` (a separate
+        // async phase in `run()`, gated on this same strategy check) stages the file, and
+        // `computeChildEnv` merges its path into the config document via `mergeEnvContentInstructions`.
+        // This branch's only job is to make sure the universal prefix fallback below does NOT ALSO run
+        // for a def that already has this strategy declared — the same "no double delivery" concern
+        // `imageDelivery`'s doc calls out for its own native-vs-fallback split.
+        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
+    }
+    const isContinuingExistingSession = (resumesSessionViaCli === true || resumesSessionViaAcpLoad === true) &&
+        typeof resumeSessionId === 'string' &&
+        resumeSessionId.length > 0;
+    if (isContinuingExistingSession) {
+        return { promptPrefix: '', prompt, extraArgs: [], envOverrides: {} };
+    }
+    // KNOWN TRADE-OFF, deliberate: for a resume-capable def with no `'append-flag'`/`'env-var'`
+    // mechanism yet (`codex`, `codebuddy`, `opencode`, `amr` — all four presently on this fallback),
+    // the overlay is therefore only injected on the SESSION-CREATING turn, not every turn. A host
+    // whose `PromptAugmenter.systemOverlay()` result can change mid-conversation (e.g. a host that
+    // lets an operator edit its own stored instructions and re-reads them before every run — see
+    // `prompt-augmenter.ts`'s own doc for the seam) will see NO effect from such an edit until a NEW
+    // session starts for one of these four defs specifically — a real, silent limitation, not a
+    // theoretical one. This is the correct
+    // trade against the alternative (re-injecting every turn would bake the overlay into that def's
+    // own CLI-persisted session history again and again, compounding without bound) — do not change
+    // this gating to "fix" the staleness. The actual fix is giving each of the four its own
+    // `'append-flag'`-equivalent `systemPromptDelivery` (an argv flag or an env var, neither of which
+    // is part of what a resumed session replays), which removes this limitation entirely for that
+    // def. See `reasonix.ts`'s and `opencode.ts`'s module docs for the two already-identified,
+    // not-yet-wired native mechanisms.
+    const promptPrefix = `${overlay}\n\n---\n\n`;
+    return { promptPrefix, prompt: `${promptPrefix}${prompt}`, extraArgs: [], envOverrides: {} };
+}
+/**
+ * Phase 9b: calls the def's `buildArgs`, releasing staged resources and failing the run on a throw.
+ *
+ * @param input.overlayDelivery - This run's already-resolved overlay decision, computed once in
+ * `run()` rather than here. It is resolved upstream because `buildArgs` is only ONE of the four
+ * channels that can carry the prompt: the staged prompt file is written *before* this function
+ * runs, and stdin/ACP/pi-rpc send theirs *after* spawn. A decision made inside this function could
+ * therefore only ever reach the 7 defs whose `buildArgs` reads its first argument at all — the
+ * other 17 declare it `_prompt` and discard it, which is exactly how the overlay used to go missing.
+ */
 export async function buildRunArgs(input, deps) {
     try {
-        return input.def.buildArgs(input.imageDelivery.prompt, [...(input.imagePaths ?? [])], input.imageDelivery.extraAllowedDirs === undefined ? undefined : [...input.imageDelivery.extraAllowedDirs], buildAgentBuildArgsOptions(input.runInput, input.systemPromptOverlay), input.runtimeContext);
+        const delivery = input.overlayDelivery;
+        const args = input.def.buildArgs(delivery.prompt, [...(input.imagePaths ?? [])], input.imageDelivery.extraAllowedDirs === undefined ? undefined : [...input.imageDelivery.extraAllowedDirs], buildAgentBuildArgsOptions(input.runInput, input.systemPromptOverlay), input.runtimeContext);
+        // `'append-flag'` delivery's extra argv (empty for every other def/strategy) is appended after
+        // whatever the def's own `buildArgs` returned — safe because it is only ever non-empty for a
+        // `promptViaStdin` def with no trailing positional argv (`claude`/`pi` today; see
+        // `resolveSystemPromptOverlayDelivery`'s doc for why a future 'append-flag' def must keep that
+        // property too). `envOverrides` (non-empty only for `'env-var'` — `reasonix` today) is handed
+        // back rather than applied here, since the spawn env isn't finalized until `computeChildEnv`
+        // runs, later in `run()`.
+        return { args: [...args, ...delivery.extraArgs], envOverrides: delivery.envOverrides };
     }
     catch (err) {
         await deps.releaseStagedResources();
@@ -1922,6 +2147,47 @@ export async function writeMcpJsonIfNeeded(input, deps) {
         return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not write .mcp.json for agent "${input.def.id}": ${errorMessage(err)}`);
     }
 }
+/**
+ * Phase 10b1: `systemPromptDelivery: { strategy: 'config-instructions-file' }`'s one effect —
+ * stages the computed overlay to a fresh, run-scoped temp file, so `computeChildEnv` has a real
+ * path to merge into that def's `instructions` config array (see
+ * {@link mergeEnvContentInstructions}'s own doc for the live verification this mechanism rests on).
+ * `null` for every other strategy, an unset `systemPromptDelivery`, or no overlay present at all —
+ * byte-identical to before this mechanism existed, matching {@link writeMcpJsonIfNeeded}'s and
+ * {@link prepareCodexHomeIfNeeded}'s identical no-op-when-inapplicable gate.
+ *
+ * `opencode`'s `instructions` field only accepts a file path or a remote URL — confirmed live
+ * (2026-09-01): a literal instruction string in the array is silently ignored (no error, just never
+ * honored), so an inline-text shortcut is not available and this staging step is load-bearing, not
+ * a defensive extra.
+ * @param input.def - Only used for its `id`, in the failure message, and its `systemPromptDelivery` declaration.
+ * @param input.overlay - The computed `PromptAugmenter.systemOverlay()` result for this run.
+ * @complexity O(1) plus one directory creation and one file write.
+ * @overallScore 100/100
+ */
+export async function prepareSystemPromptOverlayFileIfNeeded(input, deps) {
+    if (input.def.systemPromptDelivery?.strategy !== 'config-instructions-file' ||
+        typeof input.overlay !== 'string' ||
+        input.overlay.length === 0) {
+        return null;
+    }
+    try {
+        const safeRunId = input.runId.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 80) || 'run';
+        const dir = await fsPromises.mkdtemp(join(tmpdir(), `jini-system-prompt-overlay-${safeRunId}-`));
+        const filePath = join(dir, 'overlay.md');
+        await fsPromises.writeFile(filePath, input.overlay, { encoding: 'utf8', mode: 0o600 });
+        return {
+            path: filePath,
+            cleanup: async () => {
+                await fsPromises.rm(dir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        await deps.releaseStagedResources();
+        return deps.failBeforeSpawn(input.runId, 'AGENT_SPAWN_FAILED', `AgentExecutor: could not stage a system-prompt overlay file for agent "${input.def.id}": ${errorMessage(err)}`);
+    }
+}
 /**
  * Phase 10b: mechanism 5 of 5's one effect — stages this run's scratch `CODEX_HOME` directory,
  * returning the prepared handle `cleanupStagedFiles` should later release (`null` for every other
@@ -2125,13 +2391,46 @@ export function createAgentExecutor(options) {
         // defs' own native protocol already delivers the image and must never also get this
         // treatment (the double-delivery hazard this mechanism exists to avoid).
         const imageDelivery = await resolveImageDeliveryAndArgvBudget({ runId: input.runId, def, prompt: input.prompt, imagePaths: input.imagePaths, extraAllowedDirs: input.extraAllowedDirs }, { failBeforeSpawn });
+        // Phase 8, hoisted deliberately above EVERY step that writes or sends the prompt. Four
+        // different channels carry a prompt in this driver, and they do not all run at the same point:
+        // the `promptViaFile` staging below writes its file BEFORE `buildArgs`, `buildArgs` itself runs
+        // mid-`run()`, and stdin/ACP/pi-rpc all send theirs AFTER spawn. Resolving the overlay once,
+        // here, is what lets all four consume the same decision; resolving it later (as this used to,
+        // inside `buildRunArgs`) could only ever reach `buildArgs`, so the 17 defs that discard that
+        // argument, plus grok-build's staged file, silently received no overlay at all.
+        //
+        // `computeSystemPromptOverlay`'s third argument is the pre-staging `RuntimeContext`: it reads
+        // only `hasPriorAssistantTurn`, which `computeRuntimeContext` never populates from any of the
+        // staged-file/MCP inputs added to the fuller context built further down, so nothing between
+        // here and there can change the overlay this returns. Passing the narrower context makes that
+        // independence explicit rather than relying on the ordering staying lucky.
+        //
+        // `turnIndex` is a coarse 0/1 proxy (no exact turn counter exists on this driver) — sufficient
+        // because every `PromptAugmenter.systemOverlay()` implementation this seam has today wants the
+        // same overlay on every turn, not a first-turn-only one; a caller that needs finer-grained turn
+        // numbering can track it itself and ignore this arg.
+        const preStagingRuntimeContext = computeRuntimeContext(null, null, null, input.resumeSessionId, input.newSessionId);
+        const systemPromptOverlay = computeSystemPromptOverlay(promptAugmenter, def.id, preStagingRuntimeContext);
+        const overlayDelivery = resolveSystemPromptOverlayDelivery({
+            defId: def.id,
+            systemPromptDelivery: def.systemPromptDelivery,
+            resumesSessionViaCli: def.resumesSessionViaCli,
+            resumesSessionViaAcpLoad: def.resumesSessionViaAcpLoad,
+            overlay: systemPromptOverlay,
+            prompt: imageDelivery.prompt,
+            resumeSessionId: preStagingRuntimeContext?.resumeSessionId,
+        });
         const resolvedEnv = resolveRunEnv(input, process.env);
         const launch = await resolveLaunch({ runId: input.runId, def, resolvedEnv }, { resolveAgentLaunch: resolveAgentLaunchFn, failBeforeSpawn });
         const spawnEnv = applyAgentLaunchEnvFn({ ...resolvedEnv }, launch);
         // Stage a promptViaFile def's (grok-build) prompt to a temp file before buildArgs runs — its
         // buildArgs throws without runtimeContext.promptFilePath. A no-op (returns null) for every
         // def without promptViaFile: true (preparePromptFileForAgent's own guard).
-        const preparedPromptFile = await stagePromptFile({ runId: input.runId, def, prompt: imageDelivery.prompt }, { preparePromptFileForAgent: preparePromptFileForAgentFn, failBeforeSpawn });
+        //
+        // `overlayDelivery.prompt`, not `imageDelivery.prompt`: for a `promptViaFile` def this file IS
+        // the prompt transport — its `buildArgs` declares `_prompt` and passes only the path — so the
+        // overlay has to be in the bytes written here or the CLI never sees it at all.
+        const preparedPromptFile = await stagePromptFile({ runId: input.runId, def, prompt: overlayDelivery.prompt }, { preparePromptFileForAgent: preparePromptFileForAgentFn, failBeforeSpawn });
         // Stage a needsAgentLogFile def's (antigravity) diagnostic-log path, on the same terms and at
         // the same point as the prompt file above: before buildArgs, since buildArgs is what turns the
         // path into a `--log-file <path>` argument. A no-op (returns null) for every def without
@@ -2159,6 +2458,14 @@ export function createAgentExecutor(options) {
          * Only the `'codex-toml'` mechanism stages a directory at all.
          */
         let preparedCodexHome = null;
+        /**
+         * Set once `prepareSystemPromptOverlayFileIfNeeded` has actually staged this run's overlay file
+         * for a `'config-instructions-file'` def, so `cleanupStagedFiles` knows there is a temp
+         * directory to remove. Cleared as it is consumed, matching `preparedCodexHome`'s identical
+         * single-removal discipline. Only that one strategy stages a file this way — `null` for every
+         * other def/strategy/no-overlay run.
+         */
+        let preparedSystemPromptOverlayFile = null;
         const cleanupStagedFiles = async () => {
             if (preparedPromptFile)
                 await preparedPromptFile.cleanup();
@@ -2174,6 +2481,11 @@ export function createAgentExecutor(options) {
                 preparedCodexHome = null;
                 await codexHomeToRemove.cleanup();
             }
+            if (preparedSystemPromptOverlayFile) {
+                const overlayFileToRemove = preparedSystemPromptOverlayFile;
+                preparedSystemPromptOverlayFile = null;
+                await overlayFileToRemove.cleanup();
+            }
         };
         // Resolve this run's MCP bridge delivery once, before buildArgs — the `'claude-mcp-json'`
         // variant's path has to be in `runtimeContext` for that def's own `--mcp-config` argv, and
@@ -2205,12 +2517,6 @@ export function createAgentExecutor(options) {
             releaseRuntimeLock();
             await cleanupStagedFiles();
         };
-        // Computed once per `run()`, not per-token/per-event: a system-prompt overlay is a spawn-time
-        // CLI arg, not something that varies mid-run. `turnIndex` is a coarse 0/1 proxy (no exact turn
-        // counter exists on this driver) — sufficient because every `PromptAugmenter.systemOverlay()`
-        // implementation this seam has today wants the same overlay on every turn, not a first-turn-only
-        // one; a caller that needs finer-grained turn numbering can track it itself and ignore this arg.
-        const systemPromptOverlay = computeSystemPromptOverlay(promptAugmenter, def.id, runtimeContext);
         // Guarded, like every other step between staging and spawn: a `runtimeLock` def's `buildArgs` is
         // guarded precisely *because* it performs real filesystem writes (antigravity writes its model
         // choice into a shared settings file), so EACCES on a read-only home, ENOSPC, or a malformed
@@ -2218,7 +2524,7 @@ export function createAgentExecutor(options) {
         // `Error` — breaking this driver's "never a bare throw, always an `AgentExecutorError`" contract
         // — and left the run `'running'` forever while still holding the process-global mutex and both
         // staged files, so no later run of that def could ever acquire the lock either.
-        const args = await buildRunArgs({ runId: input.runId, def, imageDelivery, imagePaths: input.imagePaths, runInput: input, systemPromptOverlay, runtimeContext }, { releaseStagedResources, failBeforeSpawn });
+        const { args, envOverrides: systemPromptEnvOverrides } = await buildRunArgs({ runId: input.runId, def, imageDelivery, imagePaths: input.imagePaths, runInput: input, systemPromptOverlay, overlayDelivery, runtimeContext }, { releaseStagedResources, failBeforeSpawn });
         // Mechanism 1 of 5's one effect — stage this run's own MCP config file (run-scoped, see
         // `mcpJsonPathForRun`) before spawn so the `--mcp-config <path>` argv buildArgs just produced
         // points at a real file. Skipped entirely for the other four mechanisms and whenever no bridge
@@ -2231,12 +2537,21 @@ export function createAgentExecutor(options) {
         // so — unlike the `.mcp.json` staging above — this can run after `buildArgs` with no ordering
         // constraint of its own; it is placed here only to keep the two staging steps adjacent.
         preparedCodexHome = await prepareCodexHomeIfNeeded({ runId: input.runId, def, mcpBridge }, { mcpJsonInjection, hostEnv: process.env, releaseStagedResources, failBeforeSpawn });
+        // `'config-instructions-file'`'s one effect — stage the overlay to a temp file so
+        // `computeChildEnv` below has a real path to merge into that def's `instructions` array. A
+        // no-op (`null`) for every other def/strategy or a run with no overlay at all. Independent of
+        // `mcpBridge`/`preparedCodexHome` above (a different strategy field entirely), so placed here
+        // only to stay adjacent to the other pre-`computeChildEnv` staging steps, not for any ordering
+        // requirement between them.
+        preparedSystemPromptOverlayFile = await prepareSystemPromptOverlayFileIfNeeded({ runId: input.runId, def, overlay: systemPromptOverlay }, { releaseStagedResources, failBeforeSpawn });
         // Computed only now, not right after `mcpBridge` resolution: mechanism 5's directory path is
         // not known until the staging step directly above actually runs `mkdtemp` (see
         // `McpBridgeDelivery`'s `'codex-toml'` variant doc for why it cannot be pre-computed the way
         // `'claude-mcp-json'`'s deterministic path is). Nothing between the old, earlier call site and
         // here ever read `childEnv`, so moving the call cost nothing.
-        const childEnv = computeChildEnv(spawnEnv, mcpBridge, preparedCodexHome?.path);
+        const childEnv = computeChildEnv(spawnEnv, mcpBridge, preparedCodexHome?.path, systemPromptEnvOverrides, preparedSystemPromptOverlayFile && def.systemPromptDelivery?.strategy === 'config-instructions-file'
+            ? { varName: def.systemPromptDelivery.varName, path: preparedSystemPromptOverlayFile.path }
+            : undefined);
         // Post-buildArgs guard for argv-bound defs whose resolved binary is a
         // Windows .cmd/.bat shim or a direct .exe: a prompt under the raw byte
         // budget can still expand past CreateProcess's command-line cap once
@@ -2289,7 +2604,14 @@ export function createAgentExecutor(options) {
                 runId: input.runId,
                 agentId: def.id,
                 child,
-                prompt: input.prompt,
+                // `overlayDelivery.promptPrefix` applied to `input.prompt`, NOT `overlayDelivery.prompt`:
+                // this call site deliberately sends the raw input prompt rather than the image-delivery
+                // rewrite (see `resolveImageDeliveryAndArgvBudget`'s call site above — an ACP def delivers
+                // images natively and must never also get `'prompt-path'`'s appended paths), and the prefix
+                // is the part of the overlay decision that applies to whatever prompt text a transport was
+                // already sending. `''` for `reasonix` (env-var) and any resumed ACP session, so those keep
+                // sending byte-identical text and never receive the overlay twice.
+                prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
                 cwd: input.cwd,
                 model: input.model,
                 imagePaths: input.imagePaths ?? [],
@@ -2316,7 +2638,10 @@ export function createAgentExecutor(options) {
                 runId: input.runId,
                 agentId: def.id,
                 child,
-                prompt: input.prompt,
+                // Same reasoning as the ACP call site above. `pi` declares an `'append-flag'` strategy,
+                // so its prefix is `''` and this stays byte-identical to the raw prompt — the overlay
+                // rides `--append-system-prompt` instead, exactly once.
+                prompt: `${overlayDelivery.promptPrefix}${input.prompt}`,
                 cwd: input.cwd,
                 model: input.model,
                 imagePaths: input.imagePaths ?? [],
@@ -2336,7 +2661,17 @@ export function createAgentExecutor(options) {
             });
             return;
         }
-        writePromptToStdin(def, child, imageDelivery.prompt, stdinHandle);
+        // The overlay reaches stdin only for a def that declares stdin as its prompt transport. The
+        // four `plain`-format defs that do not (`aider`/`antigravity`/`deepseek` put the prompt in
+        // argv, `grok-build` in a staged file) are still written to and closed here exactly as before,
+        // because this driver always spawns with `stdio: ['pipe','pipe','pipe']` and their CLIs need
+        // the EOF — but their prompt already carried the overlay through argv or the staged file, so
+        // sending the overlaid text here too would deliver it twice. This is the one place the
+        // resolver's own `''`-prefix rule is not sufficient on its own: those four defs are on the
+        // fallback strategy, so their prefix is genuinely non-empty; what makes stdin the wrong
+        // channel for them is the def's declared transport, not the strategy.
+        const stdinPrompt = def.promptViaStdin === true ? overlayDelivery.prompt : imageDelivery.prompt;
+        writePromptToStdin(def, child, stdinPrompt, stdinHandle);
     }
     return { run };
 }