@tangle-network/agent-profile-materialize 0.11.0 → 0.13.0

package/dist/index.js

@@ -22,10 +22,13 @@
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
 export { modelIdsMatch, qualifyModelId } from "./model-id.js";
+export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, existsSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
 import { agentCandidateProfileActivationSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, agentProfileSchema, agentProfileSecretRefSchema, canonicalCandidateBytes, canonicalCandidateDigest, resolveNativeWebTools, } from "@tangle-network/agent-interface";
+import { modelIdsMatch, qualifyModelId } from "./model-id.js";
+import { PRIME_MCP_UNSUPPORTED_REASON, PrimeHarnessStateError, rejectPrimeControl, rejectPrimeDeclaration, } from "./prime-fork.js";
 export const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER = Object.freeze({
     async get() {
         return undefined;
@@ -86,6 +89,28 @@ function assertMaterializerHarness(harness) {
         throw new Error(`Unsupported profile materialization harness "${harness}"`);
     }
 }
+/**
+ * The subset of {@link BINDABLE_LAUNCH_CONTROLS} the plan HANDS OVER rather than
+ * executes: controls a caller reaches only by composing the harness's own
+ * configuration, so no file, flag or env var the plan writes can touch them.
+ *
+ *   - `opencode.agent-prompt` — opencode's `agent.<name>.prompt` config field,
+ *     the one control that replaces its built-in provider prompt. It binds to a
+ *     SINGLE agent, and the agent is chosen at launch. A caller that builds
+ *     opencode's config itself and picks the agent there reads neither
+ *     `plan.files` nor `plan.flags`, so for that one the plan names the control
+ *     and hands over the text in {@link WorkspacePlan.systemPromptBinding}.
+ *
+ * Every other bindable control names a capability the plan still lowers itself
+ * once the caller has declared the plan's launch inputs really reach the spawn.
+ */
+export const EXECUTOR_SYSTEM_PROMPT_BINDINGS = [
+    "opencode.agent-prompt",
+];
+const EXECUTOR_SYSTEM_PROMPT_BINDING_SET = new Set(EXECUTOR_SYSTEM_PROMPT_BINDINGS);
+export function isExecutorSystemPromptBinding(value) {
+    return EXECUTOR_SYSTEM_PROMPT_BINDING_SET.has(value);
+}
 /**
  * The dimensions `materializeProfile`'s `skip` option honors.
  *
@@ -120,13 +145,26 @@ function assertSkippableDimensions(skip) {
  * system-prompt replacement (`agent.<name>.prompt`) binds to the ONE agent
  * whoever starts the process selects, which a plan-forwarding executor cannot
  * guarantee — so the plan refuses the intent (harnessSystemPromptIntents in
- * @tangle-network/agent-interface answers `replace: false` for opencode). An
- * executor that really applies the plan's launch flags to the spawn it owns
- * (selecting the generated primary agent via the plan's `--agent` flag) states
- * so with `binds: ["systemPrompt"]`, which turns that refusal into the
- * primary-agent lowering the executor must then apply.
+ * @tangle-network/agent-interface answers `replace: false` for opencode).
+ *
+ * The two declarations describe the two executor shapes that CAN reach it, and
+ * each gets the lowering it can actually apply:
+ *
+ *   - `systemPrompt` — the executor applies the plan's launch flags to the
+ *     spawn it owns, so the plan writes the generated `mode: primary` agent and
+ *     selects it with `--agent`.
+ *   - `opencode.agent-prompt` — the executor composes opencode's own config and
+ *     picks the agent there, reading neither plan files nor plan flags, so the
+ *     plan hands the text over in {@link WorkspacePlan.systemPromptBinding}
+ *     instead of writing a workspace agent that would never be selected.
+ *
+ * They are mutually exclusive claims about the same caller: declaring both is a
+ * caller bug, not a broader capability.
  */
-export const BINDABLE_LAUNCH_CONTROLS = ["systemPrompt"];
+export const BINDABLE_LAUNCH_CONTROLS = [
+    "systemPrompt",
+    ...EXECUTOR_SYSTEM_PROMPT_BINDINGS,
+];
 const BINDABLE_LAUNCH_CONTROL_SET = new Set(BINDABLE_LAUNCH_CONTROLS);
 /** Reject a binding declaration this materializer has no lowering for, rather than ignoring it. */
 function assertBindableLaunchControls(binds) {
@@ -137,7 +175,14 @@ function assertBindableLaunchControls(binds) {
         throw new Error(`materializeProfile: cannot bind ${unknown.join(", ")}. ` +
             `Bindable launch controls are: ${BINDABLE_LAUNCH_CONTROLS.join(", ")}.`);
     }
-    return new Set(binds);
+    const declared = new Set(binds);
+    const handedOver = [...EXECUTOR_SYSTEM_PROMPT_BINDINGS].filter((control) => declared.has(control));
+    if (declared.has("systemPrompt") && handedOver.length > 0) {
+        throw new Error(`materializeProfile: cannot bind systemPrompt together with ${handedOver.join(", ")}. ` +
+            "The first says the plan's launch flags reach the spawn; the second says " +
+            "the caller composes the harness config itself and reads neither.");
+    }
+    return declared;
 }
 /** The plan was applied, but one or more private staging files remain. */
 export class WorkspacePlanCleanupError extends AggregateError {
@@ -171,6 +216,66 @@ export function enforceWorkspacePlanSupport(plan, failOnError) {
     assertWorkspacePlanSupported(plan);
     return [];
 }
+/**
+ * The two prompt intents a plan carries, projected together onto an outgoing
+ * object with each field omitted when the source does not carry it.
+ *
+ * One helper instead of a pair of inline spreads at each of the digest,
+ * receipt, candidate, and spawn boundaries: the intents must travel as a pair,
+ * and a projection that copies the replacement and forgets the addition drops
+ * it silently — downstream cannot tell "the caller asked for nothing" from
+ * "this boundary lost it". Adding a third intent later is one edit here rather
+ * than nine.
+ */
+function promptIntentFields(source, project) {
+    return {
+        ...(source.systemPrompt === undefined
+            ? {}
+            : { systemPrompt: project(source.systemPrompt) }),
+        ...(source.appendSystemPrompt === undefined
+            ? {}
+            : { appendSystemPrompt: project(source.appendSystemPrompt) }),
+    };
+}
+/** Identity projection for boundaries that pass the prompt intents through. */
+const samePromptIntentValue = (value) => value;
+/**
+ * The launcher-bound intent, projected onto an outgoing object and omitted when
+ * the source does not carry one.
+ *
+ * Beside {@link promptIntentFields} rather than inside it, because the two
+ * disagree on both ends: the candidate boundaries that helper also serves have
+ * no field for a binding — an {@link AgentCandidateWorkspacePlan} is built by a
+ * caller that declares none, so it can never hold one — and a value projection
+ * such as `candidatePublicString` has nothing to do to a structured binding.
+ * Every boundary that carries the plan's own prompt intents calls both.
+ */
+function systemPromptBindingField(source) {
+    return source.systemPromptBinding === undefined
+        ? {}
+        : { systemPromptBinding: { ...source.systemPromptBinding } };
+}
+/**
+ * The replacement text this launcher must bind to `control`, or `undefined`
+ * when the plan carries no launcher-bound intent.
+ *
+ * Throws for a binding addressed to a DIFFERENT control: the reader cannot
+ * execute it, and answering `undefined` would start the agent with the
+ * harness's own prompt still in force while nothing reported a problem — the
+ * silent downgrade the binding exists to prevent. This is the seam where an
+ * executor that cannot bind an intent says so, by name, instead of running a
+ * profile whose prompt never took effect.
+ */
+export function takeSystemPromptBinding(spawn, control) {
+    const binding = spawn.systemPromptBinding;
+    if (!binding)
+        return undefined;
+    if (binding.control !== control) {
+        throw new Error(`Workspace plan carries a system-prompt ${binding.intent} bound to ` +
+            `${binding.control}, which this executor cannot apply; it binds ${control}`);
+    }
+    return binding.systemPrompt;
+}
 // ─── Verified per-harness conventions (capability matrix) ───────────────────
 /**
  * Whether the harness LOADS its {@link CONTEXT_FILE} from cwd on its own.
@@ -204,6 +309,61 @@ export function harnessContextFile(harness) {
     }
     return path;
 }
+/**
+ * File codex's `model_instructions_file` config key reads.
+ *
+ * cwd-relative on purpose: codex resolves the key against the process working
+ * directory, which is the same workspace root the plan is applied into, so the
+ * flag stays correct under an executor that binds the workspace at a different
+ * absolute path (docker, a jail, a remote box).
+ */
+const CODEX_SYSTEM_PROMPT_FILE = ".codex/system-prompt.md";
+/**
+ * File carrying opencode's ADDITION to its system prompt.
+ *
+ * Separate from opencode's instruction file rather than merged into it: the two
+ * are different privilege levels of the same request, and one file for both
+ * would leave the plan unable to say which intent produced which bytes.
+ */
+const OPENCODE_APPEND_SYSTEM_PROMPT_FILE = ".opencode/agent-system-prompt.md";
+/**
+ * Why a harness refuses a system-prompt REPLACEMENT.
+ *
+ * The reason names the control that does exist, so the refusal is actionable
+ * without a capability-matrix lookup — a bare "unsupported" sends the caller
+ * looking for a flag that was never there.
+ */
+function systemPromptRefusal(harness) {
+    switch (harness) {
+        case "opencode":
+            // The control exists, so the reason names the two declarations that reach
+            // it rather than claiming opencode has none.
+            return 'opencode: the only system-prompt replacement is per-agent (`agent.<name>.prompt`), which binds to the agent selected at launch and a workspace plan cannot guarantee; an executor that applies the plan\'s "--agent" flag to its own spawn declares binds: ["systemPrompt"], and one that composes opencode\'s config itself declares binds: ["opencode.agent-prompt"]';
+        default:
+            return `${harness}: no verified exact system-prompt replacement control`;
+    }
+}
+/**
+ * Why a harness refuses an ADDITION to the system prompt.
+ *
+ * gemini puts its context file in the system-prompt position, so the temptation
+ * is to lower an addition there. That is refused because GEMINI.md is the ONE
+ * file it auto-loads: an addition written there is byte-identical to the same
+ * text under `prompt.instructions`, and no consumer could tell which intent the
+ * caller expressed. opencode is not refused for the same situation, because it
+ * loads exactly the files its config names and can therefore carry the two
+ * intents in separate, separately-ordered files.
+ */
+function appendSystemPromptRefusal(harness) {
+    switch (harness) {
+        case "gemini":
+            return "gemini: the only additive system-prompt channel is GEMINI.md memory, the single context file it auto-loads, which `prompt.instructions` already materializes — use it instead";
+        case "codex":
+            return "codex: no verified additive system-prompt control — its AGENTS.md lands in a developer/user message, not the system channel";
+        default:
+            return `${harness}: no verified additive system-prompt control`;
+    }
+}
 /** Project context file each harness actually reads from cwd. NEVER a constant. */
 const CONTEXT_FILE = {
     "claude-code": "CLAUDE.md",
@@ -220,6 +380,35 @@ const CONTEXT_FILE = {
     hermes: "HERMES.md", // highest-priority native name; only ONE context loads (first match)
     openclaw: "AGENTS.md",
 };
+/**
+ * The paths whose only possible author is this package, per
+ * {@link PlanFile.ownership}.
+ *
+ * Codex names no system-prompt file of its own — `model_instructions_file`
+ * takes whatever path it is given — and opencode names none either, since it
+ * reads exactly the files its config lists. All three names below were chosen
+ * here, so a file already at one of them is this materializer's own output from
+ * an earlier application into the same workspace.
+ *
+ * That is an inference from the path name, not verified provenance: nothing
+ * checks the existing bytes are prior materializer output, so a workspace that
+ * carried a foreign file at one of these invented names is overwritten on the
+ * first application. Accepted cost of stateless multi-turn re-application,
+ * bounded by the names being ones no harness or user convention uses.
+ *
+ * Deliberately absent: `.gemini/system.md` (gemini's own documented name),
+ * `GEMINI.md`, `CLAUDE.md`, `AGENTS.md`, `opencode.json`. A user's repository
+ * can carry any of those, and clobbering one is worse than refusing the turn.
+ * For `opencode.json` this means a profile change that alters the
+ * `instructions[]` membership between turns of one workspace refuses loudly
+ * (the consolidated config no longer matches byte-for-byte) rather than
+ * replacing a possibly user-authored config.
+ */
+const MATERIALIZER_OWNED_PATHS = new Set([
+    CODEX_SYSTEM_PROMPT_FILE,
+    OPENCODE_APPEND_SYSTEM_PROMPT_FILE,
+    CONTEXT_FILE.opencode,
+]);
 /**
  * cwd-relative native skill dir per harness, or null if the harness has no
  * cwd skill primitive (skills live in a user/global dir the workspace plan
@@ -271,8 +460,6 @@ const MAX_PROFILE_RESOURCE_BYTES = 32 * 1024 * 1024;
 const MAX_PROFILE_RESOURCE_REFS = 128;
 const MAX_CONCURRENT_RESOURCE_FETCHES = 8;
 const CLAUDE_SETTINGS_PATH = ".tangle/claude-settings.json";
-const CODEX_SYSTEM_PROMPT_PATH = ".codex/system-prompt.md";
-const OPENCODE_APPEND_SYSTEM_PROMPT_PATH = ".opencode/agent-system-prompt.md";
 const SAFE_WRITE_FLAGS = fsConstants.O_WRONLY |
     fsConstants.O_CREAT |
     fsConstants.O_EXCL |
@@ -645,6 +832,12 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
             relPath: normalizedPath,
             content,
             source,
+            // Only a path this package invented AND generated here is its own to
+            // replace; the same path carrying a caller's `resources` mount is that
+            // caller's file, whatever its name.
+            ...(source === "generated" && MATERIALIZER_OWNED_PATHS.has(normalizedPath)
+                ? { ownership: "materializer" }
+                : {}),
             ...(fileMode === undefined ? {} : { mode: validateFileMode(fileMode) }),
             ...(secretSlots === undefined
                 ? {}
@@ -665,6 +858,14 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
         if (previousDimension) {
             throw new Error(`Duplicate profile resource path: ${normalizedPath} (${previousDimension}, ${dimension})`);
         }
+        // Refuse at plan time so {@link MATERIALIZER_OWNED_PATHS} stays true: those
+        // paths are replaced on every re-application, so a mount there would be
+        // silently overwritten by the next turn rather than kept.
+        if (MATERIALIZER_OWNED_PATHS.has(normalizedPath)) {
+            throw new Error(`Profile resource path is reserved by the materializer: ${normalizedPath} (${dimension}). ` +
+                "This package writes that path itself and replaces it on re-application, so a mount " +
+                "there cannot survive; choose another path.");
+        }
         explicitResourcePaths.set(normalizedPath, dimension);
         pushPlanFile(normalizedPath, content, "user", mode);
     };
@@ -725,36 +926,84 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
             }
         }
     }
-    // 4) PROMPT. A system prompt is a replacement, an appended system prompt is
-    // an addition on the SAME channel, and instructions are additive workspace
-    // context. Never lower one into another: substituting controls is a silent
-    // semantic change nothing in the run would reveal. Which harness owns which
-    // intent is the measured harnessSystemPromptIntents table in
-    // @tangle-network/agent-interface; the mechanics per owned cell live here.
+    // 4) PROMPT. Replacing the harness's own system prompt and adding to it are
+    // two intents against one channel, and a harness almost never has both. Each
+    // lowers ONLY to a control whose measured job is exactly that intent; the
+    // other is refused. Substituting one for the other is the silent downgrade
+    // this section exists to prevent — an addition standing in for a replacement
+    // leaves the instructions the caller asked to delete in force, and a
+    // replacement standing in for an addition deletes the harness's own prompt.
+    // Neither is visible in the result, which is why both fail closed instead.
     //
-    // opencode registers every additive prompt file in ONE generated
-    // opencode.json `instructions` array (top-level JSON merge is last-wins per
-    // key, so two writers would clobber each other). Order is privilege order:
-    // the profile's explicit addition leads, project instructions follow.
-    const openCodeInstructionFiles = [];
+    // `instructions` is a third, lower-privilege surface (the harness's
+    // AGENTS.md/CLAUDE.md-style context file). On gemini and opencode that surface
+    // does reach the model in the system-prompt position, so an addition can be
+    // lowered there ONLY where the plan can keep the two apart. opencode can: it
+    // loads exactly the files `opencode.json` `instructions[]` names, so the
+    // addition gets its own file registered ahead of the instruction file. gemini
+    // cannot: GEMINI.md is the one context file it auto-loads, so an addition
+    // lowered there would be byte-indistinguishable from `instructions`, which is
+    // one-channel-two-meanings recreated a level down.
+    //
+    // Which harness owns which intent is the measured harnessSystemPromptIntents
+    // table in @tangle-network/agent-interface; the mechanics per owned cell live
+    // here.
     if (profile.prompt?.systemPrompt !== undefined) {
-        if (h === "opencode") {
+        if (h === "claude-code" || h === "pi" || h === "prime") {
+            // claude-code `--system-prompt`, pi `--system-prompt`: both take the
+            // replacement as a launch argument the executor supplies, and both
+            // measurably drop the harness's built-in prompt from the wire request.
+            // prime inherits the same flag pair from its pi line (fork
+            // cli/args.ts:139-143 → resourceLoaderOptions main.ts:745-746, the
+            // replacement deletes the built-in prompt: resource-loader.ts:482-485,
+            // system-prompt.ts:72-73).
+            plan.systemPrompt = profile.prompt.systemPrompt;
+        }
+        else if (h === "codex") {
+            // codex has no replacement FLAG; its control is the config key
+            // `model_instructions_file`, which reads a cwd-relative file and becomes
+            // the request's entire `instructions` field. File + flag keeps the plan
+            // self-applying for every executor that already forwards plan.flags.
+            add(CODEX_SYSTEM_PROMPT_FILE, profile.prompt.systemPrompt);
+            plan.flags.push("-c", `model_instructions_file=${CODEX_SYSTEM_PROMPT_FILE}`);
+        }
+        else if (h === "gemini") {
+            add(".gemini/system.md", profile.prompt.systemPrompt);
+            plan.env.GEMINI_SYSTEM_MD = "1";
+        }
+        else if (h === "opencode") {
+            // opencode's replacement control is `agent.<name>.prompt`: it binds to
+            // ONE agent, and the agent is chosen at launch, so executing it means
+            // writing that agent AND selecting it. There are two shapes of executor
+            // that can promise one of those, and each gets the lowering it can apply;
+            // an executor that promises neither gets the refusal, because a plan
+            // written for an unknown launcher cannot deliver either half.
+            //
+            // No shape can express an EMPTY replacement — an agent `prompt` with no
+            // text falls back to the built-in prompt instead of deleting it — so the
+            // guard sits above the split and no path bypasses it.
             const systemPrompt = profile.prompt.systemPrompt;
             if (systemPrompt.trim().length === 0) {
                 throw new Error("opencode cannot express an empty exact system-prompt replacement");
             }
-            if (!binds.has("systemPrompt")) {
-                // opencode's exact replacement (`agent.<name>.prompt`) binds to the one
-                // agent selected at launch, which a plan-forwarding executor cannot
-                // guarantee — its only system-prompt replacement is per-agent. An
-                // executor that selects the plan's generated primary agent declares
-                // binds: ["systemPrompt"].
-                unsupported("systemPrompt", "opencode: only system-prompt replacement is per-agent (`agent.<name>.prompt` " +
-                    "binds to the agent selected at launch, which a workspace plan cannot " +
-                    'guarantee); an executor that applies the plan\'s "--agent" flag to its own ' +
-                    'spawn declares binds: ["systemPrompt"]');
+            if (binds.has("opencode.agent-prompt")) {
+                // A caller that composes opencode's own config and picks the agent
+                // itself owns the control outright; it does not read plan files or
+                // forward plan flags, so a workspace agent would never be selected.
+                // Hand it the intent named against the exact control it claimed.
+                plan.systemPromptBinding = {
+                    intent: "replace",
+                    control: "opencode.agent-prompt",
+                    systemPrompt,
+                };
             }
-            else {
+            else if (binds.has("systemPrompt")) {
+                // A caller that applies the plan's launch flags to the spawn it owns
+                // lets the plan execute the control itself: a `mode: primary` agent
+                // file holding the prompt, plus the `--agent` flag that selects it.
+                // Without the flag the file is inert and the built-in prompt the
+                // caller asked to delete stays in force, so the two are pushed
+                // together or not at all.
                 const primaryAgentName = `${OPENCODE_PRIMARY_AGENT_PREFIX}${sha256(systemPrompt).slice(0, 16)}`;
                 const primaryAgentPath = `.opencode/agents/${primaryAgentName}.md`;
                 if (profile.subagents?.[primaryAgentName] !== undefined) {
@@ -764,61 +1013,57 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
                 add(primaryAgentPath, ["---", "mode: primary", "---", systemPrompt, ""].join("\n"));
                 plan.flags.push("--agent", primaryAgentName);
             }
-        }
-        else if (h === "claude-code" || h === "pi" || h === "prime") {
-            // Launch-argument channel: claude-code/pi `--system-prompt`; prime
-            // inherits the same flag pair from its pi line (fork cli/args.ts:139-143
-            // → resourceLoaderOptions main.ts:745-746, replacement deletes the
-            // built-in prompt: resource-loader.ts:482-485, system-prompt.ts:72-73).
-            plan.systemPrompt = profile.prompt.systemPrompt;
-        }
-        else if (h === "codex") {
-            // codex's replacement is a config file, never a launch-argument string:
-            // `model_instructions_file` becomes the request's entire instructions
-            // text (measured against codex 0.146.0).
-            add(CODEX_SYSTEM_PROMPT_PATH, profile.prompt.systemPrompt);
-            plan.flags.push("-c", `model_instructions_file=${CODEX_SYSTEM_PROMPT_PATH}`);
-        }
-        else if (h === "gemini") {
-            add(".gemini/system.md", profile.prompt.systemPrompt);
-            plan.env.GEMINI_SYSTEM_MD = "1";
+            else {
+                unsupported("systemPrompt", systemPromptRefusal(h));
+            }
         }
         else {
-            unsupported("systemPrompt", `${h}: no verified exact system-prompt replacement control`);
+            unsupported("systemPrompt", systemPromptRefusal(h));
         }
     }
+    // Ordered registration list for opencode, whose TUI and headless runs read
+    // ONLY the files named here. Addition first so it frames the lower-privilege
+    // instruction file that follows, matching the order the model receives them.
+    const openCodeInstructionFiles = [];
+    // A launcher that declared `opencode.agent-prompt` composes opencode's config
+    // itself and reads neither plan files nor plan flags, so the workspace
+    // `opencode.json` that registers these additive files would never load.
+    // Lowering them anyway would be the silent drop this module refuses to
+    // perform, so each additive intent is refused by name instead: the launcher
+    // owns the `instructions[]` channel too and must compose it in the config it
+    // builds.
+    const openCodeConfigUnreachable = h === "opencode" && binds.has("opencode.agent-prompt");
     if (profile.prompt?.appendSystemPrompt !== undefined) {
         const appendSystemPrompt = profile.prompt.appendSystemPrompt;
         if (appendSystemPrompt.trim().length === 0) {
             throw new Error("prompt.appendSystemPrompt must be non-empty text");
         }
-        if (h === "claude-code" || h === "pi" || h === "prime") {
-            // `--append-system-prompt` leaves the harness's own prompt in place and
-            // adds this text after it (claude-code/pi measured; prime fork
-            // cli/args.ts:139-143, addition appends after the built-in prompt:
-            // system-prompt.ts:61,109-110).
-            plan.appendSystemPrompt = appendSystemPrompt;
+        if (openCodeConfigUnreachable) {
+            unsupported("appendSystemPrompt", "opencode: the launcher that binds opencode.agent-prompt composes opencode's config itself and loads no workspace opencode.json, so an addition registered there would never reach the model; compose it into the launcher's own instructions[]");
         }
         else if (h === "opencode") {
-            // opencode composes config-declared `instructions[]` files into the same
-            // single role:"system" message as its built-in prompt, which stays in
-            // place — a real additive channel, distinct from the instructions
-            // surface only by position (registered first, below).
-            add(OPENCODE_APPEND_SYSTEM_PROMPT_PATH, appendSystemPrompt.endsWith("\n")
+            // opencode composes config-declared `instructions[]` file contents into
+            // the same single role:"system" message as its built-in prompt, which
+            // stays in place (its replacement control is the separate per-agent
+            // `prompt` field). A dedicated file keeps this intent addressable on its
+            // own rather than merged into the instruction file.
+            add(OPENCODE_APPEND_SYSTEM_PROMPT_FILE, appendSystemPrompt.endsWith("\n")
                 ? appendSystemPrompt
                 : `${appendSystemPrompt}\n`);
-            openCodeInstructionFiles.push(OPENCODE_APPEND_SYSTEM_PROMPT_PATH);
-        }
-        else if (h === "codex") {
-            unsupported("systemPrompt", "codex: no verified additive system-prompt control — its AGENTS.md lands in a " +
-                "developer/user message, not the system channel");
+            openCodeInstructionFiles.push(OPENCODE_APPEND_SYSTEM_PROMPT_FILE);
         }
-        else if (h === "gemini") {
-            unsupported("systemPrompt", "gemini: the only additive system-prompt channel is GEMINI.md memory, which IS " +
-                "the instructions surface — use prompt.instructions");
+        else if (h === "claude-code" || h === "pi" || h === "prime") {
+            // claude-code `--append-system-prompt`, pi `--append-system-prompt`: both
+            // add the caller's text to the harness's own system prompt, which stays
+            // on the wire intact. prime inherits the same flag from its pi line (fork
+            // cli/args.ts:139-143, the addition appends after the built-in prompt:
+            // system-prompt.ts:61,109-110). Carried beside the replacement rather
+            // than merged into it, so an executor applies each through its own
+            // control and the plan's identity distinguishes the two intents.
+            plan.appendSystemPrompt = appendSystemPrompt;
         }
         else {
-            unsupported("systemPrompt", `${h}: no verified additive system-prompt control`);
+            unsupported("appendSystemPrompt", appendSystemPromptRefusal(h));
         }
     }
     const instr = [];
@@ -833,12 +1078,20 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
         unsupported("instructions", "instruction ref is not inline (github refs need async pre-resolution)");
     }
     if (instr.length) {
-        const instructionPath = CONTEXT_FILE[h];
-        add(instructionPath, `${instr.join("\n\n")}\n`);
-        if (h === "opencode")
-            openCodeInstructionFiles.push(instructionPath);
-        // gemini reads AGENTS.md only via settings; we write GEMINI.md so no extra step.
+        if (openCodeConfigUnreachable) {
+            unsupported("instructions", "opencode: the launcher that binds opencode.agent-prompt composes opencode's config itself and loads no workspace opencode.json, so an instruction file registered there would never reach the model; compose it into the launcher's own instructions[]");
+        }
+        else {
+            const instructionPath = CONTEXT_FILE[h];
+            add(instructionPath, `${instr.join("\n\n")}\n`);
+            if (h === "opencode")
+                openCodeInstructionFiles.push(instructionPath);
+            // gemini reads AGENTS.md only via settings; we write GEMINI.md so no extra step.
+        }
     }
+    // ONE opencode.json write for the whole prompt section: top-level JSON merge
+    // is last-wins per key, and two `add` calls at the same relPath are a
+    // duplicate-file error, so a second write would drop whichever lost.
     if (openCodeInstructionFiles.length > 0) {
         add("opencode.json", serializeWorkspacePlanJson({
             $schema: "https://opencode.ai/config.json",
@@ -957,14 +1210,7 @@ export function materializeCandidateProfile(profile, harness, opts = {}) {
         files: classicPlan.files,
         env: candidatePublicRecord(classicPlan.env),
         flags: classicPlan.flags.map(candidatePublicArgument),
-        ...(classicPlan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: candidatePublicValue(classicPlan.systemPrompt) }),
-        ...(classicPlan.appendSystemPrompt === undefined
-            ? {}
-            : {
-                appendSystemPrompt: candidatePublicValue(classicPlan.appendSystemPrompt),
-            }),
+        ...promptIntentFields(classicPlan, candidatePublicValue),
         unsupported: classicPlan.unsupported,
     };
 }
@@ -1281,6 +1527,7 @@ function normalizePlanFiles(files) {
             relPath,
             content: file.content,
             mode,
+            ownership: file.ownership ?? "shared",
             secretSlots,
         };
     })
@@ -1332,6 +1579,10 @@ export function hashWorkspacePlan(plan) {
         relPath: file.relPath,
         mode: file.mode,
         contentSha256: sha256(file.content),
+        // Ownership decides whether re-application may replace the file, so two
+        // plans identical in bytes but different here behave differently in the
+        // same workspace — the digest a receipt proves must say which one ran.
+        ownership: file.ownership,
         ...(file.secretSlots.length === 0
             ? {}
             : {
@@ -1355,12 +1606,10 @@ export function hashWorkspacePlan(plan) {
         files,
         env,
         flags: plan.flags.map(normalizeWorkspacePlanArgument),
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : { appendSystemPrompt: plan.appendSystemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        // A plan that owes a launcher a replacement is not the same plan as one
+        // that owes nothing, even when every byte it writes is identical.
+        ...systemPromptBindingField(plan),
         unsupported,
         ...(requires.length === 0 ? {} : { requires }),
     });
@@ -1378,12 +1627,7 @@ export function agentCandidateProfilePlanMaterial(plan) {
         })),
         env: Object.fromEntries(Object.entries(plan.env).sort(([left], [right]) => compareStrings(left, right))),
         flags: [...plan.flags],
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : { appendSystemPrompt: plan.appendSystemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
         unsupported: [...plan.unsupported].sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`)),
     };
     return agentCandidateProfilePlanMaterialSchema.parse(material);
@@ -1443,14 +1687,7 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
             candidatePublicString(value),
         ])),
         flags: plan.flags.map(candidatePublicString),
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: candidatePublicString(plan.systemPrompt) }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : {
-                appendSystemPrompt: candidatePublicString(plan.appendSystemPrompt),
-            }),
+        ...promptIntentFields(plan, candidatePublicString),
         unsupported: plan.unsupported,
     }, workspaceDir);
     return {
@@ -1462,12 +1699,7 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
         },
         env: { ...plan.env },
         flags: [...plan.flags],
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : { appendSystemPrompt: plan.appendSystemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
         unsupported: [...plan.unsupported],
     };
 }
@@ -1552,12 +1784,8 @@ function resolvePublicWorkspacePlan(plan) {
         files,
         env,
         flags,
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : { appendSystemPrompt: plan.appendSystemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
     };
 }
 async function resolvePrivateWorkspacePlan(plan, secretProvider) {
@@ -1623,12 +1851,8 @@ async function resolvePrivateWorkspacePlan(plan, secretProvider) {
         files,
         env,
         flags,
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : { appendSystemPrompt: plan.appendSystemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
     };
 }
 function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorkspacePlan(plan)) {
@@ -1639,12 +1863,8 @@ function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorks
             typeof value === "string" ? value : { ...value },
         ])),
         flags: plan.flags.map(normalizeWorkspacePlanArgument),
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
-        ...(plan.appendSystemPrompt === undefined
-            ? {}
-            : { appendSystemPrompt: plan.appendSystemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
         unsupported: plan.unsupported.map((entry) => ({ ...entry })),
         written: [...written],
     };
@@ -1666,11 +1886,17 @@ function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, opti
         ...file,
         absPath: resolveWorkspaceFilePath(workspaceRoot, file.relPath),
     }));
+    // A path this package invented can only hold this package's own earlier
+    // output, so re-applying into the same workspace replaces it rather than
+    // failing the turn. `reject` still refuses: that policy is "nothing may
+    // pre-exist here", which is a statement about the workspace, not authorship.
+    const mayReplace = (file) => existingFiles === "allow-identical" && file.ownership === "materializer";
     // Validate the complete plan before the first write so a late traversal or
     // existing symlink cannot leave a partially materialized workspace.
     for (const file of files) {
         assertNoSymlinkPathComponents(workspaceRoot, file.absPath);
         if (workspaceFileExists(file.absPath) &&
+            !mayReplace(file) &&
             (existingFiles === "reject" || !workspaceFileMatches(file))) {
             throw new Error(`Refusing to replace existing workspace file: ${file.relPath}`);
         }
@@ -1707,6 +1933,20 @@ function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, opti
                     workspaceFileMatches(entry.file)) {
                     continue;
                 }
+                if (isFsError(error, "EEXIST") && mayReplace(entry.file)) {
+                    // rename() replaces in one step, so no window exists in which the
+                    // path is missing and a concurrent spawn reads nothing. The staged
+                    // inode moves onto the path, which is what rollback identifies the
+                    // file by, so an abort still removes exactly what this call
+                    // published — leaving the path ABSENT rather than restored to the
+                    // superseded bytes. That is the fail-closed direction: the harness
+                    // whose flag names a missing file refuses to start, whereas silently
+                    // restored previous-turn bytes would run the wrong prompt.
+                    assertNoSymlinkPathComponents(workspaceRoot, entry.file.absPath);
+                    renameSync(entry.temporaryPath, entry.file.absPath);
+                    entry.published = true;
+                    continue;
+                }
                 if (isFsError(error, "EEXIST")) {
                     throw new Error(`Refusing to replace existing workspace file: ${entry.file.relPath}`, { cause: error });
                 }
@@ -1762,12 +2002,8 @@ function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, opti
         spawn: {
             env: { ...resolvedPlan.env },
             flags: [...resolvedPlan.flags],
-            ...(resolvedPlan.systemPrompt === undefined
-                ? {}
-                : { systemPrompt: resolvedPlan.systemPrompt }),
-            ...(resolvedPlan.appendSystemPrompt === undefined
-                ? {}
-                : { appendSystemPrompt: resolvedPlan.appendSystemPrompt }),
+            ...promptIntentFields(resolvedPlan, samePromptIntentValue),
+            ...systemPromptBindingField(resolvedPlan),
         },
         runtimeOnlyFiles: privateRuntimeFiles,
     };
@@ -2940,12 +3176,29 @@ function materializeCommand(h, name, body, add, unsupported) {
 //   and the addition appends after it (system-prompt.ts:61,109-110). Values
 //   are materialized as FILES under the agent dir because the flag value is
 //   read as a file when the path exists (resource-loader.ts:41-56), which
-//   keeps literal-vs-path resolution deterministic.
+//   keeps literal-vs-path resolution deterministic AND removes the argv size
+//   ceiling an inline flag value would run into (Linux MAX_ARG_STRLEN).
+//
+// - `prompt.instructions` / `resources.instructions` → `<agentDir>/AGENTS.md`.
+//   The agent dir IS an instruction surface: `loadProjectContextFiles`
+//   (resource-loader.ts:76) reads the agent dir's own AGENTS.md/CLAUDE.md as
+//   the GLOBAL context file (:86 `loadContextFileFromDir(resolvedAgentDir)`,
+//   candidates at :59) BEFORE walking the cwd ancestors (:94-112), and the
+//   result is loaded unless `--no-context-files` (:476). Writing it here
+//   touches no caller workspace content, which is what the agent-dir lowering
+//   exists to guarantee. (`materializeProfile(profile, "prime")` lowers the
+//   same intent to the cwd AGENTS.md for callers that own the workspace
+//   instead of the agent dir.)
 //
 // - `resources.skills` (inline refs) → `--skill <agentDir>/profile/skills`
 //   (cli/args.ts:207-209 → main.ts:652 → agent-session-config.ts:67 →
-//   additionalSkillPaths, resource-loader.ts:437-442). The loader recurses
-//   into `<name>/SKILL.md` subdirs (skills.ts:328-372) and loaded skills are
+//   additionalSkillPaths, resource-loader.ts:437-442). An explicit flag rather
+//   than the agent dir's auto-discovered `skills/` tree (package-manager.ts:884
+//   global base, :2171 skills dir, :2240-2246 discovery), which also loads but
+//   goes through the fork's global-vs-project dedupe (package-manager.ts:880,
+//   "project scope wins over global") — so an unrelated project-scope skill of
+//   the same name silently shadows the profile's. The loader recurses into
+//   `<name>/SKILL.md` subdirs (skills.ts:328-372) and loaded skills are
 //   rendered into the system prompt (agent-session.ts:4272-4291,
 //   system-prompt.ts:87-89). The fork silently DROPS a SKILL.md without a
 //   frontmatter description (skills.ts:416-419), so content is normalized
@@ -2959,25 +3212,17 @@ function materializeCommand(h, name, body, add, unsupported) {
 //   reaches the same store through the host-set RLM_GLOBAL_HARNESS_STATE_DIR
 //   (agent-session.ts:8805).
 //
-// Kept REJECTED with the fork evidence:
+// Kept REJECTED with the fork evidence — see {@link PRIME_MCP_UNSUPPORTED_REASON}
+// for `mcp`/`connections`, and the per-control reasons in
+// {@link readPrimeProfileControls} for permissions, tools, hooks, modes,
+// confidential, and the resource kinds with no agent-dir read path.
 //
-// - `mcp`: the fork's MCP config surface (`mcpServers` in
-//   `<agentDir>/settings.json`, settings-manager.ts:98-120,219) IS read at
-//   startup, but a user-declared server never becomes model-visible: the host
-//   McpManager only registers OAuth providers and serves mcp.config/refresh
-//   host-requests (core/mcp/mcp-manager.ts:62-124,156-181), skips stdio
-//   servers entirely (mcp-manager.ts:73), and nothing generates a skill or
-//   prompt section for it — model-visible MCP is exactly the built-in
-//   linear/notion catalog skills (packages/coding-agent/skills/…). Wiring
-//   `profile.mcp` into settings.json would materialize config the model can
-//   never discover: a silently dropped control.
-//
-// - `prompt.instructions`: the fork's caller-instruction surface is the
-//   workspace AGENTS.md/CLAUDE.md context file (resource-loader.ts:58-66),
-//   i.e. caller workspace content this agent-dir lowering must not write
-//   into. (`materializeProfile(profile, "prime")` lowers instructions to the
-//   cwd AGENTS.md instead, which the fork walks from cwd:
-//   resource-loader.ts:94-109.)
+// The store is AGENT-OWNED: it is written by the agent mid-session and rides
+// every later system prompt. A store that exists but no longer parses
+// therefore fails the turn ({@link PrimeHarnessStateError}) rather than being
+// reseeded from empty — the fork's own loader degrades to empty in-process
+// (refinement.ts:290-300), but an executor that OVERWRITES the file makes that
+// degradation permanent and destroys the evidence of what happened.
 /** Skill name rules enforced by the fork's Agent Skills loader (skills.ts:122-147). */
 const PRIME_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PRIME_MAX_SKILL_NAME_LENGTH = 64;
@@ -2985,6 +3230,8 @@ const PRIME_PROFILE_DIR_NAME = "profile";
 const PRIME_SKILLS_DIR_NAME = "skills";
 const PRIME_SYSTEM_PROMPT_FILE = "system-prompt.md";
 const PRIME_APPEND_SYSTEM_PROMPT_FILE = "append-system-prompt.md";
+/** Agent-dir global context file the fork reads (resource-loader.ts:59,86). */
+const PRIME_CONTEXT_FILE = "AGENTS.md";
 /** Fork continual-harness store location under the agent dir (refinement.ts:269-279). */
 const PRIME_HARNESS_DIR_NAME = "harness";
 const PRIME_HARNESS_STATE_FILE = "harness_state.json";
@@ -2995,22 +3242,101 @@ const PRIME_HARNESS_KINDS = ["prompt", "memory", "skill", "subagent"];
  * touched.
  */
 const PRIME_PROFILE_ENTRY_SOURCE = "profile";
-function rejectPrimeControl(control, reason) {
-    throw new Error(`prime does not support AgentProfile ${control}: ${reason}`);
+/**
+ * Provenance markers written by executors that predate this shared lowering.
+ *
+ * Pruning keys on the source tag, so an executor that switches to the shared
+ * implementation would otherwise leave its own earlier entries behind forever:
+ * they match no current profile and no current source, and the model's
+ * spawnable roster silently accumulates duplicates of every subagent. They are
+ * adopted (pruned or replaced) on the first shared run instead.
+ */
+const PRIME_LEGACY_PROFILE_ENTRY_SOURCES = [
+    "cli-bridge-profile",
+];
+/** True when the controls materialize anything at all. */
+export function hasPrimeProfileMaterial(controls) {
+    return (controls.systemPrompt !== undefined ||
+        controls.appendSystemPrompt !== undefined ||
+        primeProfileNeedsAgentDir(controls) ||
+        controls.skills.length > 0);
+}
+/**
+ * True when the controls must WRITE INTO the agent dir itself.
+ *
+ * Prompt files and skill dirs are named by a flag, so they can live anywhere
+ * the agent can read (`--system-prompt` / `--append-system-prompt` resolve a
+ * path when it exists, fork resource-loader.ts:41-56; `--skill` takes an
+ * arbitrary dir, :437-442). The context file and the continual-harness store
+ * are located BY the agent dir and have no flag, so they cannot move.
+ *
+ * An executor pointed at an agent dir it does not own (an operator's shared
+ * dir) uses this to refuse exactly the controls it would have to write there,
+ * while still binding the ones it can materialize elsewhere.
+ */
+export function primeProfileNeedsAgentDir(controls) {
+    return controls.instructions !== undefined || controls.subagents.length > 0;
+}
+/**
+ * Read one instruction block, which the profile may carry inline or as a
+ * resource ref. Only inline refs are accepted: resolving a GitHub-backed ref
+ * fetches remote content, which is `resolveAgentProfileResources`' job and
+ * must happen before a profile reaches an executor.
+ */
+function primeInstructionBlock(value, control) {
+    if (typeof value === "string")
+        return value;
+    if (value.kind === "inline")
+        return value.content;
+    rejectPrimeControl(control, "only inline resource refs are accepted — resolve GitHub-backed refs " +
+        "(resolveAgentProfileResources) before handing the profile to this lowering.");
 }
 /**
  * Validate and extract the profile controls the prime agent-dir lowering
- * materializes. Throws on any control (or control facet) the fork has no
- * verified read path for — partial acceptance would silently drop the rest.
+ * materializes. Throws {@link PrimeProfileError} on any control (or control
+ * facet) the fork has no verified read path for — partial acceptance would
+ * silently drop the rest.
  */
 export function readPrimeProfileControls(profile) {
     const controls = { skills: [], subagents: [] };
     if (!profile)
         return controls;
     if (profile.harness !== undefined && profile.harness !== "prime") {
-        throw new Error(`prime cannot run a profile pinned to harness "${profile.harness}" — ` +
+        rejectPrimeDeclaration("harness", `prime cannot run a profile pinned to harness "${profile.harness}" — ` +
             'only "prime" (or an unset harness preference) is accepted.');
     }
+    // An entry with `enabled: false` is OFF, not requested. A fully disabled map
+    // asks for nothing, so accepting it drops no control — which is the only
+    // thing this refusal exists to prevent.
+    const requestedMcp = Object.keys(activeMcpServers(profile.mcp));
+    if (requestedMcp.length > 0) {
+        rejectPrimeControl(`mcp: ${requestedMcp.join(", ")}`, PRIME_MCP_UNSUPPORTED_REASON);
+    }
+    if (profile.connections !== undefined) {
+        rejectPrimeControl("connections", `a hub connection grant resolves to MCP tools, and ${PRIME_MCP_UNSUPPORTED_REASON}`);
+    }
+    if (profile.permissions !== undefined) {
+        rejectPrimeControl("permissions", "prime-agent exposes no permission control at all (full flag scan of fork " +
+            "cli/args.ts:93-295; native tools run unconditionally), so a permission map " +
+            "would be accepted and never enforced.");
+    }
+    if (profile.tools !== undefined) {
+        rejectPrimeControl("tools", "the only per-run tool control is `--tools` over the single builtin `ipython` " +
+            "(fork cli/args.ts:63-64,156-167); bash/edit and the rest are extension-provided " +
+            "and not addressable per run, so a harness-neutral tool map cannot bind to it.");
+    }
+    if (profile.hooks !== undefined) {
+        rejectPrimeControl("hooks", "prime-agent has no hook mechanism (fork cli/args.ts flag scan; extensions are " +
+            "host-trusted JS modules loaded into the agent process, not caller command hooks).");
+    }
+    if (profile.modes !== undefined) {
+        rejectPrimeControl("modes", "prime-agent has no mode concept (fork cli/args.ts flag scan).");
+    }
+    if (profile.confidential !== undefined) {
+        rejectPrimeControl("confidential", "confidential execution is a property of the executor's isolation boundary, not " +
+            "of the agent dir; this lowering cannot establish it.");
+    }
+    const instructionBlocks = [];
     if (profile.prompt) {
         const { systemPrompt, appendSystemPrompt, instructions } = profile.prompt;
         const knownPromptFields = new Set([
@@ -3024,15 +3350,9 @@ export function readPrimeProfileControls(profile) {
         if (unknown.length > 0) {
             rejectPrimeControl(`prompt fields: ${unknown.join(", ")}`, "no verified prime-agent read path exists for them.");
         }
-        if (instructions !== undefined) {
-            rejectPrimeControl("prompt.instructions", "prime-agent's caller-instruction surface is the workspace " +
-                "AGENTS.md context file (fork resource-loader.ts:58-66), which is " +
-                "caller workspace content this adapter must not write into. Use " +
-                "prompt.appendSystemPrompt instead.");
-        }
         if (systemPrompt !== undefined) {
             if (typeof systemPrompt !== "string" || systemPrompt.trim() === "") {
-                rejectPrimeControl("prompt.systemPrompt", "an empty replacement would delete the built-in system prompt and " +
+                rejectPrimeDeclaration("prompt.systemPrompt", "an empty replacement would delete the built-in system prompt and " +
                     "install nothing.");
             }
             controls.systemPrompt = systemPrompt;
@@ -3040,52 +3360,69 @@ export function readPrimeProfileControls(profile) {
         if (appendSystemPrompt !== undefined) {
             if (typeof appendSystemPrompt !== "string" ||
                 appendSystemPrompt.trim() === "") {
-                rejectPrimeControl("prompt.appendSystemPrompt", "must be non-empty text.");
+                rejectPrimeDeclaration("prompt.appendSystemPrompt", "must be non-empty text.");
             }
             controls.appendSystemPrompt = appendSystemPrompt;
         }
+        for (const block of instructions ?? []) {
+            if (typeof block === "string" && block.trim() !== "")
+                instructionBlocks.push(block);
+        }
     }
     if (profile.resources) {
-        const { skills, failOnError, ...unsupported } = profile.resources;
+        const { skills, instructions, failOnError, ...unsupported } = profile.resources;
         const rejectedKeys = Object.entries(unsupported)
             .filter(([, value]) => value !== undefined)
             .map(([key]) => key);
         if (rejectedKeys.length > 0) {
-            rejectPrimeControl(`resources: ${rejectedKeys.join(", ")}`, "only resources.skills has a verified prime-agent read path " +
-                "(--skill dirs, fork resource-loader.ts:437-442).");
+            rejectPrimeControl(`resources: ${rejectedKeys.join(", ")}`, "only resources.skills (--skill dirs, fork resource-loader.ts:437-442) and " +
+                "resources.instructions (agent-dir AGENTS.md, resource-loader.ts:86) have a " +
+                "verified prime-agent read path. Generic workspace files, tool files, " +
+                "subagent-definition files and prompt templates either have no headless read " +
+                "path or would run caller-authored code inside the agent process.");
         }
         if (failOnError === false) {
-            rejectPrimeControl("resources.failOnError: false", "this adapter always fails loud on a resource it cannot " +
+            rejectPrimeControl("resources.failOnError: false", "this lowering always fails loud on a resource it cannot " +
                 "materialize; lenient materialization is not implemented.");
         }
+        if (instructions !== undefined) {
+            const block = primeInstructionBlock(instructions, "resources.instructions");
+            if (block.trim() !== "")
+                instructionBlocks.push(block);
+        }
         const seen = new Set();
-        for (const ref of skills ?? []) {
+        for (const [index, ref] of (skills ?? []).entries()) {
             if (ref.kind !== "inline") {
-                rejectPrimeControl(`resources.skills ref "${"path" in ref ? ref.path : ""}"`, "only inline skill refs are accepted — resolve GitHub refs " +
+                rejectPrimeControl(`resources.skills[${index}]`, "only inline skill refs are accepted — resolve GitHub-backed refs " +
                     "(resolveAgentProfileResources) before handing the profile to " +
-                    "this adapter.");
+                    "this lowering.");
             }
             const name = ref.name;
             if (!PRIME_SKILL_NAME_RE.test(name) ||
                 name.length > PRIME_MAX_SKILL_NAME_LENGTH) {
-                rejectPrimeControl(`resources.skills name "${name}"`, "prime-agent skill names must be lowercase a-z0-9 with single " +
-                    `hyphens, at most ${PRIME_MAX_SKILL_NAME_LENGTH} chars (fork skills.ts:122-147).`);
+                rejectPrimeDeclaration(`resources.skills[${index}]`, `name ${JSON.stringify(name)} is not a valid prime skill name — it becomes the ` +
+                    "skill directory name, so it must be lowercase a-z0-9 with single hyphens, at " +
+                    `most ${PRIME_MAX_SKILL_NAME_LENGTH} chars (fork skills.ts:122-147).`);
             }
             if (seen.has(name)) {
-                rejectPrimeControl(`resources.skills name "${name}"`, "duplicate skill names collide in the fork's skill registry.");
+                rejectPrimeDeclaration("resources.skills", `declares ${JSON.stringify(name)} twice; duplicate skill names collide in the ` +
+                    "fork's skill registry, which keeps only the first and warns.");
             }
             seen.add(name);
             if (ref.content.trim() === "") {
-                rejectPrimeControl(`resources.skills "${name}"`, "skill content is empty.");
+                rejectPrimeDeclaration(`resources.skills[${index}]`, `skill ${JSON.stringify(name)} declares no content.`);
             }
             controls.skills.push({ name, content: ref.content });
         }
     }
+    if (instructionBlocks.length > 0) {
+        controls.instructions = instructionBlocks.join("\n\n");
+    }
     if (profile.subagents) {
         const usedIds = new Map();
         for (const [name, spec] of Object.entries(profile.subagents)) {
             if (name.trim() === "") {
-                rejectPrimeControl("subagents", "a subagent name must be non-empty.");
+                rejectPrimeDeclaration("subagents", "a subagent name must be non-empty.");
             }
             const inexpressible = [
                 ["model", spec.model],
@@ -3096,19 +3433,20 @@ export function readPrimeProfileControls(profile) {
                 .filter(([, value]) => value !== undefined)
                 .map(([key]) => key);
             if (inexpressible.length > 0) {
-                rejectPrimeControl(`subagents["${name}"] fields: ${inexpressible.join(", ")}`, "a prime continual-harness subagent spec is prompt-roster " +
+                rejectPrimeControl(`subagents[${JSON.stringify(name)}] fields: ${inexpressible.join(", ")}`, "a prime continual-harness subagent spec is prompt-roster " +
                     "guidance for `await rlm('<task>')` (fork refinement.ts:483-496) " +
                     "and pins no model, tool set, permission, or step budget on the " +
                     "spawned child.");
             }
             if (!spec.description?.trim() && !spec.prompt?.trim()) {
-                rejectPrimeControl(`subagents["${name}"]`, "a spec needs a description and/or prompt — an empty entry gives " +
-                    "the model an empty roster line.");
+                rejectPrimeDeclaration(`subagents[${JSON.stringify(name)}]`, "declares no behavior — a spec needs a description and/or prompt, since an " +
+                    "empty entry gives the model an empty roster line.");
             }
             const id = primeSubagentEntryId(name);
             const clash = usedIds.get(id);
             if (clash !== undefined) {
-                rejectPrimeControl(`subagents["${name}"]`, `its id "${id}" collides with subagent "${clash}".`);
+                rejectPrimeDeclaration(`subagents[${JSON.stringify(name)}]`, `collides with subagent ${JSON.stringify(clash)} on harness-state id ` +
+                    `${JSON.stringify(id)}.`);
             }
             usedIds.set(id, name);
             controls.subagents.push({
@@ -3121,6 +3459,39 @@ export function readPrimeProfileControls(profile) {
     }
     return controls;
 }
+/**
+ * Refuse a run whose selected model disagrees with the profile's own.
+ *
+ * One authority per run: a profile names the model it was written and scored
+ * against, so running it on a different one silently scores a different agent.
+ * Both sides go through {@link modelIdsMatch}, so the qualification level a
+ * caller happened to use is not a conflict.
+ *
+ * `provider` is the executor's PROVIDER SELECTION, and is compared only when
+ * the executor's provider is part of model identity. An executor whose
+ * provider key is merely a namespace inside the agent dir passes it as
+ * undefined and gets the model-name comparison alone.
+ */
+export function assertPrimeModelAgreement(profile, selected) {
+    const declared = profile?.model?.default;
+    const declaredProvider = profile?.model?.provider;
+    if (declared !== undefined) {
+        const selectedId = qualifyModelId(selected.provider, selected.model);
+        const declaredId = qualifyModelId(declaredProvider, declared);
+        if (!modelIdsMatch(selectedId, declaredId, selected.provider)) {
+            rejectPrimeDeclaration("model.default", `the run selects ${JSON.stringify(selectedId)} but the profile names ` +
+                `${JSON.stringify(declaredId)}; a profile must not be scored against a model it ` +
+                "does not name.");
+        }
+        return;
+    }
+    if (selected.provider !== undefined &&
+        declaredProvider !== undefined &&
+        declaredProvider !== selected.provider) {
+        rejectPrimeDeclaration("model.provider", `the run selects provider ${JSON.stringify(selected.provider)} but the profile names ` +
+            `${JSON.stringify(declaredProvider)}.`);
+    }
+}
 /** Deterministic harness-state entry id for a profile subagent name. */
 export function primeSubagentEntryId(name) {
     const slug = name
@@ -3130,96 +3501,127 @@ export function primeSubagentEntryId(name) {
     return `profile-${slug || "subagent"}`;
 }
 /**
- * Materialize the validated controls into `agentDir` and return the extra
- * spawn args that bind them. Runs before every spawn (same place models.json
- * is materialized), so a continual agent dir is re-pinned to the current
- * profile on each fresh prime process.
+ * Write one agent-dir file atomically (temp + rename).
+ *
+ * Every file this lowering writes lands in a directory a LIVE agent may be
+ * reading: prime reloads models.json at model-resolution time and re-reads the
+ * harness store on every system-prompt build, so a partial write is observable.
+ * `mode` is applied to the temp file before the rename, so the final file is
+ * never briefly world-readable.
+ */
+export function writePrimeAgentFile(path, data, mode = 0o600) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, data, { mode });
+    renameSync(temp, path);
+}
+/**
+ * Materialize the validated controls and return the extra spawn args that bind
+ * them. Runs before every spawn (same place models.json is materialized), so a
+ * continual agent dir is re-pinned to the current profile on each fresh prime
+ * process.
  */
-export function materializePrimeProfileControls(agentDir, controls, warn) {
+export function materializePrimeProfileControls(agentDir, controls, options = {}) {
+    const { flagFileRoot = agentDir, warn } = options;
     const args = [];
-    const profileDir = join(agentDir, PRIME_PROFILE_DIR_NAME);
+    const profileDir = join(flagFileRoot, PRIME_PROFILE_DIR_NAME);
     if (controls.systemPrompt !== undefined) {
-        mkdirSync(profileDir, { recursive: true });
         const promptPath = join(profileDir, PRIME_SYSTEM_PROMPT_FILE);
-        writeFileSync(promptPath, controls.systemPrompt, "utf8");
+        writePrimeAgentFile(promptPath, controls.systemPrompt);
         args.push("--system-prompt", promptPath);
     }
     if (controls.appendSystemPrompt !== undefined) {
-        mkdirSync(profileDir, { recursive: true });
         const appendPath = join(profileDir, PRIME_APPEND_SYSTEM_PROMPT_FILE);
-        writeFileSync(appendPath, controls.appendSystemPrompt, "utf8");
+        writePrimeAgentFile(appendPath, controls.appendSystemPrompt);
         args.push("--append-system-prompt", appendPath);
     }
+    if (controls.instructions !== undefined) {
+        writePrimeAgentFile(join(agentDir, PRIME_CONTEXT_FILE), `${controls.instructions}\n`);
+    }
     if (controls.skills.length > 0) {
         const skillsRoot = join(profileDir, PRIME_SKILLS_DIR_NAME);
         for (const skill of controls.skills) {
-            const skillDir = join(skillsRoot, skill.name);
-            mkdirSync(skillDir, { recursive: true });
-            writeFileSync(join(skillDir, "SKILL.md"), normalizeSkillMd(skill.name, skill.content), "utf8");
+            writePrimeAgentFile(join(skillsRoot, skill.name, "SKILL.md"), normalizeSkillMd(skill.name, skill.content));
         }
         args.push("--skill", skillsRoot);
     }
     seedPrimeProfileSubagents(agentDir, controls.subagents, warn);
     return args;
 }
-function emptyPrimeHarnessState() {
-    const entries = {};
-    for (const kind of PRIME_HARNESS_KINDS)
-        entries[kind] = {};
-    return { schema: 1, entries, refinements: [] };
+/**
+ * Remove the files a PREVIOUS materialization of this lowering wrote, so a
+ * profile that shrank cannot leave a stale instruction file or skill behind for
+ * the next run against the same dirs.
+ *
+ * Only the paths this lowering NAMES are removed. There is deliberately no
+ * manifest: a manifest would live where the agent can write it, and reading a
+ * delete list out of agent-writable state turns pruning into an arbitrary-path
+ * delete.
+ */
+export function prunePrimeProfileMaterial(agentDir, options = {}) {
+    const { flagFileRoot = agentDir } = options;
+    rmSync(join(flagFileRoot, PRIME_PROFILE_DIR_NAME), {
+        recursive: true,
+        force: true,
+    });
+    rmSync(join(agentDir, PRIME_CONTEXT_FILE), { force: true });
 }
 /**
  * Upsert profile subagent specs into the fork's global continual-harness
  * store and remove profile-sourced entries the current profile no longer
- * declares. Agent-written entries (`source: "agent"`) are never touched.
+ * declares. Agent-written entries (`source: "agent"`) — and every top-level
+ * key this lowering does not manage — are preserved untouched.
  *
- * A pre-existing unparsable store degrades to empty exactly like the fork's
- * own loader (refinement.ts:290-300 — "a corrupt state file must degrade to
- * empty rather than throw"), with a warning so the reset is visible.
+ * A store that exists but no longer parses raises
+ * {@link PrimeHarnessStateError}: the file is the agent's own self-modification
+ * state, and overwriting it destroys what the run was supposed to observe.
  */
 export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
     const statePath = join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
-    let state = emptyPrimeHarnessState();
+    let state = {};
     if (existsSync(statePath)) {
+        let parsed;
         try {
-            const raw = JSON.parse(readFileSync(statePath, "utf8"));
-            if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-                const parsed = raw;
-                state.schema =
-                    typeof parsed.schema === "number" ? parsed.schema : state.schema;
-                for (const kind of PRIME_HARNESS_KINDS) {
-                    const records = parsed.entries?.[kind];
-                    if (records && typeof records === "object") {
-                        state.entries[kind] = { ...records };
-                    }
-                }
-                if (Array.isArray(parsed.refinements)) {
-                    state.refinements = parsed.refinements;
-                }
-            }
-            else {
-                warn("prime: existing harness_state.json is not an object — reseeding", {
-                    statePath,
-                });
-            }
+            parsed = JSON.parse(readFileSync(statePath, "utf8"));
         }
         catch (err) {
-            warn("prime: existing harness_state.json is unparsable — reseeding", {
-                statePath,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            state = emptyPrimeHarnessState();
+            throw new PrimeHarnessStateError(statePath, err instanceof Error ? err.message : String(err));
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new PrimeHarnessStateError(statePath, "the store is not a JSON object");
         }
+        state = parsed;
     }
     else if (subagents.length === 0) {
         // Nothing to pin and nothing stale to remove.
         return;
     }
-    const existing = state.entries.subagent ?? {};
+    const rawEntries = state.entries;
+    const entries = rawEntries && typeof rawEntries === "object" && !Array.isArray(rawEntries)
+        ? rawEntries
+        : {};
+    for (const kind of PRIME_HARNESS_KINDS) {
+        const records = entries[kind];
+        if (!records || typeof records !== "object" || Array.isArray(records)) {
+            entries[kind] = {};
+        }
+    }
+    const existing = entries.subagent;
     const desiredIds = new Set(subagents.map((s) => primeSubagentEntryId(s.name)));
     let changed = false;
     for (const [id, entry] of Object.entries(existing)) {
-        if (entry?.source === PRIME_PROFILE_ENTRY_SOURCE && !desiredIds.has(id)) {
+        const source = entry?.source;
+        const isLegacy = typeof source === "string" &&
+            PRIME_LEGACY_PROFILE_ENTRY_SOURCES.includes(source);
+        if (isLegacy) {
+            warn?.("prime: adopting a subagent entry left by a pre-shared executor", {
+                statePath,
+                id,
+                source,
+            });
+        }
+        if ((source === PRIME_PROFILE_ENTRY_SOURCE || isLegacy) &&
+            !desiredIds.has(id)) {
             delete existing[id];
             changed = true;
         }
@@ -3242,7 +3644,7 @@ export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
             kind: "subagent",
             title: spec.name,
             content,
-            path: "profile",
+            path: PRIME_PROFILE_ENTRY_SOURCE,
             scope: "global",
             reference: {},
             arguments: {},
@@ -3256,9 +3658,12 @@ export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
         };
         changed = true;
     }
-    state.entries.subagent = existing;
     if (!changed)
         return;
-    mkdirSync(join(agentDir, PRIME_HARNESS_DIR_NAME), { recursive: true });
-    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    writePrimeAgentFile(statePath, `${JSON.stringify({
+        ...state,
+        schema: typeof state.schema === "number" ? state.schema : 1,
+        entries,
+        refinements: Array.isArray(state.refinements) ? state.refinements : [],
+    }, null, 2)}\n`);
 }