@tangle-network/agent-profile-materialize 0.10.3 → 0.12.0

package/dist/index.js

@@ -21,8 +21,9 @@
  * `node:fs` IO consumer. It was previously copied byte-for-byte into both
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
+export { modelIdsMatch, qualifyModelId } from "./model-id.js";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, 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, 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";
 export const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER = Object.freeze({
@@ -71,6 +72,7 @@ export const MATERIALIZER_HARNESSES = [
     "opencode",
     "kimi-code",
     "pi",
+    "prime",
     "gemini",
     "hermes",
     "openclaw",
@@ -84,6 +86,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.
  *
@@ -110,6 +134,53 @@ function assertSkippableDimensions(skip) {
     }
     return skip;
 }
+/**
+ * Launcher controls an executor can declare it OWNS via `materializeProfile`'s
+ * `binds` option.
+ *
+ * Some harness controls live outside any workspace: opencode's exact
+ * 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).
+ *
+ * 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",
+    ...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) {
+    if (!binds)
+        return new Set();
+    const unknown = binds.filter((control) => !BINDABLE_LAUNCH_CONTROL_SET.has(control));
+    if (unknown.length > 0) {
+        throw new Error(`materializeProfile: cannot bind ${unknown.join(", ")}. ` +
+            `Bindable launch controls are: ${BINDABLE_LAUNCH_CONTROLS.join(", ")}.`);
+    }
+    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 {
     receipt;
@@ -142,6 +213,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.
@@ -175,6 +306,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",
@@ -183,10 +369,43 @@ const CONTEXT_FILE = {
     opencode: ".opencode/profile-instructions.md",
     "kimi-code": "AGENTS.md",
     pi: "AGENTS.md",
+    // prime (PrimeIntellect-ai/prime-agent v0.7.0, be9e2fa0) walks cwd and its
+    // ancestors for AGENTS.md/CLAUDE.md, cwd first (fork resource-loader.ts:59
+    // candidates, :94-109 walk from cwd inside loadProjectContextFiles).
+    prime: "AGENTS.md",
     gemini: "GEMINI.md", // current default; AGENTS.md only via .gemini/settings.json context.fileName
     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
@@ -202,6 +421,12 @@ export const HARNESS_SKILL_DIRS = {
     opencode: ".opencode/skills",
     "kimi-code": ".kimi/skills",
     pi: ".pi/skills",
+    // prime auto-discovers project skills from <cwd>/<configDir>/skills where the
+    // fork ships configDir ".prime/agent" (fork package.json piConfig, config.ts:494;
+    // package-manager.ts:885 projectBaseDir, :2175-2180 projectDirs.skills,
+    // :2209-2213 collectAutoSkillEntries). The loader recurses into
+    // <name>/SKILL.md subdirs (skills.ts:328-372).
+    prime: ".prime/agent/skills",
     gemini: ".gemini/skills",
     hermes: null, // skills are ~/.hermes/skills (user) only — no cwd discovery
     openclaw: "skills", // <workspace>/skills/<name>/SKILL.md
@@ -226,6 +451,7 @@ const DEFAULT_FILE_MODE = 0o644;
 const PRIVATE_FILE_MODE = 0o600;
 const EXECUTABLE_FILE_MODE = 0o755;
 const DEFAULT_RESOURCE_FETCH_TIMEOUT_MS = 30_000;
+const OPENCODE_PRIMARY_AGENT_PREFIX = "tangle-profile-";
 const MAX_RESOURCE_BYTES = 10 * 1024 * 1024;
 const MAX_PROFILE_RESOURCE_BYTES = 32 * 1024 * 1024;
 const MAX_PROFILE_RESOURCE_REFS = 128;
@@ -575,6 +801,7 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
     const profile = agentProfileSchema.parse(inputProfile);
     const h = harness;
     const skip = new Set(assertSkippableDimensions(opts.skip));
+    const binds = assertBindableLaunchControls(opts.binds);
     const plan = {
         harness: h,
         files: [],
@@ -602,6 +829,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
                 ? {}
@@ -622,6 +855,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);
     };
@@ -682,21 +923,144 @@ export function materializeProfile(inputProfile, harness, opts = {}) {
             }
         }
     }
-    // 4) PROMPT. A system prompt is a replacement, while instructions are
-    // additive workspace context. Never lower one into the other.
+    // 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.
+    //
+    // `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 === "claude-code" ||
-            h === "codex" ||
-            h === "opencode" ||
-            h === "pi") {
+        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("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 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) {
+                    throw new Error(`opencode: subagent name "${primaryAgentName}" is reserved for the profile primary agent`);
+                }
+                plan.systemPrompt = systemPrompt;
+                add(primaryAgentPath, ["---", "mode: primary", "---", systemPrompt, ""].join("\n"));
+                plan.flags.push("--agent", primaryAgentName);
+            }
+            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 (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[]` 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_FILE);
+        }
+        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("appendSystemPrompt", appendSystemPromptRefusal(h));
         }
     }
     const instr = [];
@@ -711,15 +1075,25 @@ 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") {
-            add("opencode.json", serializeWorkspacePlanJson({
-                $schema: "https://opencode.ai/config.json",
-                instructions: [instructionPath],
-            }));
+        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[]");
         }
-        // gemini reads AGENTS.md only via settings; we write GEMINI.md so no extra step.
+        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",
+            instructions: openCodeInstructionFiles,
+        }));
     }
     // 5) ACTIVE EXECUTION CONTROLS. These alter the tools visible to the primary
     // process and its permission policy, so they must be lowered into native
@@ -833,9 +1207,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) }),
+        ...promptIntentFields(classicPlan, candidatePublicValue),
         unsupported: classicPlan.unsupported,
     };
 }
@@ -1152,6 +1524,7 @@ function normalizePlanFiles(files) {
             relPath,
             content: file.content,
             mode,
+            ownership: file.ownership ?? "shared",
             secretSlots,
         };
     })
@@ -1203,6 +1576,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
             ? {}
             : {
@@ -1226,9 +1603,10 @@ export function hashWorkspacePlan(plan) {
         files,
         env,
         flags: plan.flags.map(normalizeWorkspacePlanArgument),
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
+        ...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 }),
     });
@@ -1246,9 +1624,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 }),
+        ...promptIntentFields(plan, samePromptIntentValue),
         unsupported: [...plan.unsupported].sort((left, right) => compareStrings(`${left.dimension}\0${left.reason}`, `${right.dimension}\0${right.reason}`)),
     };
     return agentCandidateProfilePlanMaterialSchema.parse(material);
@@ -1308,9 +1684,7 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
             candidatePublicString(value),
         ])),
         flags: plan.flags.map(candidatePublicString),
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: candidatePublicString(plan.systemPrompt) }),
+        ...promptIntentFields(plan, candidatePublicString),
         unsupported: plan.unsupported,
     }, workspaceDir);
     return {
@@ -1322,9 +1696,7 @@ export function applyAgentCandidateWorkspacePlan(plan, workspaceDir, targetWorks
         },
         env: { ...plan.env },
         flags: [...plan.flags],
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
         unsupported: [...plan.unsupported],
     };
 }
@@ -1409,9 +1781,8 @@ function resolvePublicWorkspacePlan(plan) {
         files,
         env,
         flags,
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
     };
 }
 async function resolvePrivateWorkspacePlan(plan, secretProvider) {
@@ -1477,9 +1848,8 @@ async function resolvePrivateWorkspacePlan(plan, secretProvider) {
         files,
         env,
         flags,
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
     };
 }
 function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorkspacePlan(plan)) {
@@ -1490,9 +1860,8 @@ function safeWorkspacePlanReceipt(plan, written, workspacePlanDigest = hashWorks
             typeof value === "string" ? value : { ...value },
         ])),
         flags: plan.flags.map(normalizeWorkspacePlanArgument),
-        ...(plan.systemPrompt === undefined
-            ? {}
-            : { systemPrompt: plan.systemPrompt }),
+        ...promptIntentFields(plan, samePromptIntentValue),
+        ...systemPromptBindingField(plan),
         unsupported: plan.unsupported.map((entry) => ({ ...entry })),
         written: [...written],
     };
@@ -1514,11 +1883,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}`);
         }
@@ -1555,6 +1930,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 });
                 }
@@ -1610,9 +1999,8 @@ function applyResolvedWorkspacePlan(publicPlan, resolvedPlan, workspaceDir, opti
         spawn: {
             env: { ...resolvedPlan.env },
             flags: [...resolvedPlan.flags],
-            ...(resolvedPlan.systemPrompt === undefined
-                ? {}
-                : { systemPrompt: resolvedPlan.systemPrompt }),
+            ...promptIntentFields(resolvedPlan, samePromptIntentValue),
+            ...systemPromptBindingField(resolvedPlan),
         },
         runtimeOnlyFiles: privateRuntimeFiles,
     };
@@ -2214,6 +2602,19 @@ function materializeMcp(h, mcp, plan, add, unsupported) {
             });
             break;
         }
+        case "prime":
+            // The fork's MCP config surface (`mcpServers` in <agentDir>/settings.json,
+            // fork 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 (fork 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 — materializing profile.mcp would be a
+            // silently dropped control.
+            unsupported("mcp", "prime: settings.json mcpServers never becomes model-visible (fork mcp-manager.ts:62-124 " +
+                "registers OAuth providers only and skips stdio servers) — model-visible MCP is exactly " +
+                "the fork's built-in catalog skills");
+            break;
         case "hermes":
             unsupported("mcp", "hermes MCP is global config.yaml (mcp_servers), no cwd discovery — write to the hermes global config or pass a config flag");
             break;
@@ -2418,6 +2819,9 @@ function materializeHooks(h, hooks, add, unsupported, plan) {
         case "pi":
             unsupported("hooks", "pi hooks are TS extensions (.pi/extensions/*.ts) — build an extension");
             break;
+        case "prime":
+            unsupported("hooks", "prime hooks are TS extensions (fork core/extensions), not command hooks — build an extension");
+            break;
         case "hermes":
             unsupported("hooks", "hermes project plugins do not expose an exact command-hook mapping");
             break;
@@ -2678,6 +3082,16 @@ function materializeSubagent(h, name, sa, plan, add, unsupported) {
             registerCodexAgent(plan, name, relPath, sa.description ?? name);
             break;
         }
+        case "prime":
+            // Prime subagents ARE expressible — as entries in the continual-harness
+            // store at <agentDir>/harness/harness_state.json (fork refinement.ts:269-279,
+            // re-read on every system-prompt build: agent-session.ts:7548-7554) — but
+            // that store lives under the executor-owned agent dir, which no
+            // workspace-relative plan file can reach. Executors that own the agent
+            // dir seed it with seedPrimeProfileSubagents; the plan stays fail-closed
+            // so a plan-forwarding caller can never believe the roster is in force.
+            unsupported("subagents", `prime: subagents live in the agent-dir continual-harness store (<agentDir>/harness/harness_state.json), outside any workspace plan — seed "${name}" with seedPrimeProfileSubagents from the executor that owns the agent dir`);
+            break;
         default:
             unsupported("subagents", `${h}: subagents have no cwd file (config/flag/global only); "${name}" not mounted`);
     }
@@ -2721,6 +3135,12 @@ function materializeCommand(h, name, body, add, unsupported) {
         case "pi":
             add(`.pi/prompts/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
             break;
+        case "prime":
+            // Auto-discovered project prompt templates: <cwd>/.prime/agent/prompts
+            // (fork prompt-templates.ts:218 resolves CONFIG_DIR_NAME "prompts";
+            // package-manager.ts:2176-2180 auto-adds the same projectDirs.prompts).
+            add(`.prime/agent/prompts/${name}.md`, body.endsWith("\n") ? body : `${body}\n`);
+            break;
         case "kimi-code":
             unsupported("commands", "kimi commands ARE skills (/skill:<name>) — provide as a skill instead");
             break;
@@ -2731,3 +3151,347 @@ function materializeCommand(h, name, body, add, unsupported) {
             unsupported("commands", `${h}: no cwd command path`);
     }
 }
+// ─── Prime agent-dir lowering ────────────────────────────────────────────────
+//
+// Prime (PrimeIntellect-ai/prime-agent v0.7.0, be9e2fa0) reads several profile
+// dimensions from its AGENT DIR — a per-process config root the EXECUTOR owns
+// (env PRIME_AGENT_CODING_AGENT_DIR, fork config.ts:498,521-527), which no
+// workspace-relative plan file can reach. The helpers below are that lowering,
+// shared so cli-bridge's prime backend and sdk-provider-prime consume one
+// implementation instead of hand-rolling byte-divergent copies. Every control
+// accepted here is backed by a verified read path in the pinned fork; every
+// other control is rejected loudly so a caller can never believe a
+// behavior-relevant setting is in force when it is not. The verified paths:
+//
+// - `prompt.systemPrompt` / `prompt.appendSystemPrompt` → `--system-prompt` /
+//   `--append-system-prompt` (cli/args.ts:139-143). Both ride
+//   `AgentSessionRuntimeConfig` (main.ts:643-644) through BOTH acp spawn
+//   paths — the daemon-client create request (main.ts:1512-1520 →
+//   daemon-mode.ts:1310/1478) and the in-process fallback — into
+//   `resourceLoaderOptions` (main.ts:745-746), where the replacement DELETES
+//   the built-in prompt (resource-loader.ts:482-485, system-prompt.ts:72-73)
+//   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.
+//
+// - `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
+//   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
+//   through {@link normalizeSkillMd}, which guarantees one.
+//
+// - `subagents` → `subagent` entries in the fork's continual-harness store at
+//   `<agentDir>/harness/harness_state.json` (refinement.ts:269-279). The
+//   store is re-read on every system-prompt build (agent-session.ts:4288,
+//   7548-7554) and subagent entries render as a task-shaped roster the model
+//   spawns via `await rlm('<task>')` (refinement.ts:483-496); the kernel
+//   reaches the same store through the host-set RLM_GLOBAL_HARNESS_STATE_DIR
+//   (agent-session.ts:8805).
+//
+// Kept REJECTED with the fork evidence:
+//
+// - `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.)
+/** 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;
+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";
+/** 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";
+const PRIME_HARNESS_KINDS = ["prompt", "memory", "skill", "subagent"];
+/**
+ * Provenance marker for entries pinned from the profile. Stale removal keys on
+ * it, so agent-written (`source: "agent"`) and user-written entries are never
+ * touched.
+ */
+const PRIME_PROFILE_ENTRY_SOURCE = "profile";
+function rejectPrimeControl(control, reason) {
+    throw new Error(`prime does not support AgentProfile ${control}: ${reason}`);
+}
+/**
+ * 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.
+ */
+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}" — ` +
+            'only "prime" (or an unset harness preference) is accepted.');
+    }
+    if (profile.prompt) {
+        const { systemPrompt, appendSystemPrompt, instructions } = profile.prompt;
+        const knownPromptFields = new Set([
+            "systemPrompt",
+            "appendSystemPrompt",
+            "instructions",
+        ]);
+        const unknown = Object.entries(profile.prompt)
+            .filter(([key, value]) => !knownPromptFields.has(key) && value !== undefined)
+            .map(([key]) => key);
+        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 " +
+                    "install nothing.");
+            }
+            controls.systemPrompt = systemPrompt;
+        }
+        if (appendSystemPrompt !== undefined) {
+            if (typeof appendSystemPrompt !== "string" ||
+                appendSystemPrompt.trim() === "") {
+                rejectPrimeControl("prompt.appendSystemPrompt", "must be non-empty text.");
+            }
+            controls.appendSystemPrompt = appendSystemPrompt;
+        }
+    }
+    if (profile.resources) {
+        const { skills, 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).");
+        }
+        if (failOnError === false) {
+            rejectPrimeControl("resources.failOnError: false", "this adapter always fails loud on a resource it cannot " +
+                "materialize; lenient materialization is not implemented.");
+        }
+        const seen = new Set();
+        for (const ref of skills ?? []) {
+            if (ref.kind !== "inline") {
+                rejectPrimeControl(`resources.skills ref "${"path" in ref ? ref.path : ""}"`, "only inline skill refs are accepted — resolve GitHub refs " +
+                    "(resolveAgentProfileResources) before handing the profile to " +
+                    "this adapter.");
+            }
+            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).`);
+            }
+            if (seen.has(name)) {
+                rejectPrimeControl(`resources.skills name "${name}"`, "duplicate skill names collide in the fork's skill registry.");
+            }
+            seen.add(name);
+            if (ref.content.trim() === "") {
+                rejectPrimeControl(`resources.skills "${name}"`, "skill content is empty.");
+            }
+            controls.skills.push({ name, content: ref.content });
+        }
+    }
+    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.");
+            }
+            const inexpressible = [
+                ["model", spec.model],
+                ["tools", spec.tools],
+                ["permissions", spec.permissions],
+                ["maxSteps", spec.maxSteps],
+            ]
+                .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 " +
+                    "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.");
+            }
+            const id = primeSubagentEntryId(name);
+            const clash = usedIds.get(id);
+            if (clash !== undefined) {
+                rejectPrimeControl(`subagents["${name}"]`, `its id "${id}" collides with subagent "${clash}".`);
+            }
+            usedIds.set(id, name);
+            controls.subagents.push({
+                name,
+                description: spec.description,
+                prompt: spec.prompt,
+                metadata: spec.metadata,
+            });
+        }
+    }
+    return controls;
+}
+/** Deterministic harness-state entry id for a profile subagent name. */
+export function primeSubagentEntryId(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    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.
+ */
+export function materializePrimeProfileControls(agentDir, controls, warn) {
+    const args = [];
+    const profileDir = join(agentDir, 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");
+        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");
+        args.push("--append-system-prompt", appendPath);
+    }
+    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");
+        }
+        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: [] };
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
+    const statePath = join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
+    let state = emptyPrimeHarnessState();
+    if (existsSync(statePath)) {
+        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,
+                });
+            }
+        }
+        catch (err) {
+            warn("prime: existing harness_state.json is unparsable — reseeding", {
+                statePath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            state = emptyPrimeHarnessState();
+        }
+    }
+    else if (subagents.length === 0) {
+        // Nothing to pin and nothing stale to remove.
+        return;
+    }
+    const existing = state.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)) {
+            delete existing[id];
+            changed = true;
+        }
+    }
+    const now = new Date().toISOString();
+    for (const spec of subagents) {
+        const id = primeSubagentEntryId(spec.name);
+        const content = [spec.description?.trim(), spec.prompt?.trim()]
+            .filter((part) => !!part)
+            .join("\n\n");
+        const previous = existing[id];
+        if (previous &&
+            previous.source === PRIME_PROFILE_ENTRY_SOURCE &&
+            previous.title === spec.name &&
+            previous.content === content) {
+            continue;
+        }
+        existing[id] = {
+            id,
+            kind: "subagent",
+            title: spec.name,
+            content,
+            path: "profile",
+            scope: "global",
+            reference: {},
+            arguments: {},
+            metadata: spec.metadata ?? {},
+            source: PRIME_PROFILE_ENTRY_SOURCE,
+            created_at: previous?.created_at ?? now,
+            updated_at: now,
+            version: previous && typeof previous.version === "number"
+                ? previous.version + 1
+                : 1,
+        };
+        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");
+}