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

package/dist/index.d.ts

@@ -57,6 +57,25 @@ export interface PlanFile {
      * this on every file it emits.
      */
     source?: "user" | "generated";
+    /**
+     * Who owns the PATH — which decides whether an existing file there may be
+     * replaced.
+     *
+     * `"materializer"` = a path this package invented. No harness convention
+     * names it and no user authors it, so a file already there can only be this
+     * materializer's own output from an earlier application into the same
+     * workspace, and replacing it is how turn two of a resumed session gets the
+     * current profile instead of the previous one.
+     *
+     * `"shared"` (the default, and every other file) = a path the user or the
+     * harness also owns — `CLAUDE.md`, `AGENTS.md`, `opencode.json`,
+     * `.gemini/system.md` are all documented, user-authorable names. An existing
+     * file there may be the caller's own work, so it is never replaced.
+     *
+     * Optional because hand-constructed plans have no path provenance to report;
+     * absent reads as `"shared"`, the safe answer.
+     */
+    ownership?: "materializer" | "shared";
     /**
      * Secret leaves in a generated JSON document. `content` contains `null` at
      * each path until the private executor resolves the named reference. The
@@ -83,9 +102,47 @@ export type WorkspacePlanArgument = string | WorkspacePlanArgumentTemplate;
 /** Public bytes stay strings; secret references stay opaque until application. */
 export type WorkspacePlanConfigValue = string | AgentProfileSecretRef;
 export interface Unsupported {
-    dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
+    dimension: "files" | "skills" | "mcp" | "hooks" | "subagents" | "commands" | "instructions" | "systemPrompt" | "appendSystemPrompt" | "connections" | "confidential" | "permissions" | "tools" | "modes" | "extensions";
     reason: string;
 }
+/**
+ * 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 declare const EXECUTOR_SYSTEM_PROMPT_BINDINGS: readonly ["opencode.agent-prompt"];
+export type ExecutorSystemPromptBinding = (typeof EXECUTOR_SYSTEM_PROMPT_BINDINGS)[number];
+export declare function isExecutorSystemPromptBinding(value: string): value is ExecutorSystemPromptBinding;
+/**
+ * A system-prompt intent handed to the launcher that declared it owns the
+ * control, instead of being lowered into the workspace.
+ *
+ * Distinct from {@link WorkspacePlan.systemPrompt} — a launch ARGUMENT the
+ * executor hands to a harness flag — and from the file/flag/env lowerings the
+ * plan performs on its own. This names the exact control that must receive the
+ * text and which of the two intents it is, so the launcher cannot apply it to
+ * the wrong channel. Never written into an additive channel and never dropped:
+ * a caller that has not declared it owns `control` gets the plan's own lowering
+ * (or a refusal where the harness has no control at all) instead of this field.
+ */
+export interface WorkspacePlanSystemPromptBinding {
+    /** Which of the two prompt intents this is — never inferred from presence. */
+    intent: "replace";
+    /** The exact launcher control that must receive `systemPrompt`. */
+    control: ExecutorSystemPromptBinding;
+    /** Exact text the control receives. */
+    systemPrompt: string;
+}
 /**
  * The dimensions `materializeProfile`'s `skip` option honors.
  *
@@ -104,13 +161,23 @@ export declare function isSkippableDimension(value: string): value is SkippableD
  * 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 declare const BINDABLE_LAUNCH_CONTROLS: readonly ["systemPrompt"];
+export declare const BINDABLE_LAUNCH_CONTROLS: readonly ["systemPrompt", "opencode.agent-prompt"];
 export type BindableLaunchControl = (typeof BINDABLE_LAUNCH_CONTROLS)[number];
 /** The plan a caller writes into the run cwd, then applies to the spawn. */
 export interface WorkspacePlan {
@@ -121,18 +188,42 @@ export interface WorkspacePlan {
     env: Record<string, WorkspacePlanConfigValue>;
     /** Extra CLI flags to pass (e.g. kimi --mcp-config-file <path>). */
     flags: WorkspacePlanArgument[];
-    /** Exact system-prompt replacement supplied to the harness. */
+    /**
+     * Exact text that REPLACES the harness's own system prompt, for harnesses
+     * whose replacement control takes it as a launch argument the executor
+     * supplies (claude-code `--system-prompt`, pi `--system-prompt`).
+     *
+     * Absent does NOT mean "no replacement was requested": a harness whose
+     * control reads a file (codex, gemini) carries the replacement in
+     * {@link WorkspacePlan.files} plus a flag or env var instead. Present means
+     * the executor MUST bind it to that harness's replacement control — never to
+     * an additive one, which would leave the built-in prompt in force.
+     */
     systemPrompt?: string;
     /**
-     * Additive system-prompt text: the harness's own prompt stays in force and
-     * this text is added after it. The OPPOSITE intent of {@link systemPrompt} on
-     * the same channel — an executor must never bind one to the other's control
-     * (an addition on the replacement flag deletes the prompt the caller asked to
-     * keep; a replacement on the additive flag leaves the harness's prompt
-     * running). Set only for harnesses whose own control executes the addition
-     * (harnessSystemPromptIntents in @tangle-network/agent-interface).
+     * Exact text ADDED to the harness's own system prompt, which stays intact.
+     *
+     * Separate from {@link WorkspacePlan.systemPrompt} because the two are
+     * different intents against the same channel, and every harness that has one
+     * control may lack the other. An executor binds this ONLY to an additive
+     * control (claude-code `--append-system-prompt`, pi
+     * `--append-system-prompt`); there is no harness for which folding it into
+     * the replacement is correct, because that would delete the built-in prompt
+     * the caller asked to keep.
      */
     appendSystemPrompt?: string;
+    /**
+     * A prompt intent no workspace file, flag, or env var can execute, addressed
+     * to the launcher control that can — see
+     * {@link WorkspacePlanSystemPromptBinding}.
+     *
+     * Present ONLY when the caller declared it owns the named control, so a plan
+     * built by a caller that forwards it to someone else's launcher never carries
+     * one; that caller gets the intent in {@link WorkspacePlan.unsupported}
+     * instead. Whoever reads it must bind it or throw — {@link
+     * takeSystemPromptBinding} does both.
+     */
+    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
     /** Dimensions requested but with NO cwd path on this harness — fail-closed record. */
     unsupported: Unsupported[];
     /**
@@ -185,6 +276,8 @@ export interface WorkspacePlanReceipt {
     flags: WorkspacePlanArgument[];
     systemPrompt?: string;
     appendSystemPrompt?: string;
+    /** The launcher-bound intent, so a receipt says which control owed the work. */
+    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
     unsupported: Unsupported[];
     written: string[];
 }
@@ -194,6 +287,8 @@ export interface WorkspacePlanSpawnInputs {
     flags: string[];
     systemPrompt?: string;
     appendSystemPrompt?: string;
+    /** Read it with {@link takeSystemPromptBinding}, which refuses a foreign control. */
+    systemPromptBinding?: WorkspacePlanSystemPromptBinding;
 }
 /** Result of applying a public plan at the private executor boundary. */
 export interface WorkspacePlanApplication {
@@ -248,6 +343,18 @@ export interface AgentCandidateWorkspacePlanReceipt {
     appendSystemPrompt?: AgentCandidateConfigValue;
     unsupported: Unsupported[];
 }
+/**
+ * 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 declare function takeSystemPromptBinding(spawn: Pick<WorkspacePlanSpawnInputs, "systemPromptBinding">, control: ExecutorSystemPromptBinding): string | undefined;
 export interface MaterializeCandidateProfileOptions {
     /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
     resolvedResources?: ReadonlyMap<Sha256Digest, string>;
@@ -308,7 +415,17 @@ export declare function normalizeSkillMd(name: string, raw: string): string;
  */
 export declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
     skip?: SkippableDimension[];
-    /** Launcher controls the calling executor owns — see {@link BINDABLE_LAUNCH_CONTROLS}. */
+    /**
+     * Launcher controls THIS caller owns and will bind itself — see
+     * {@link BINDABLE_LAUNCH_CONTROLS}. Each names a control no workspace file,
+     * flag or env var reaches on its own, so declaring one turns a plan-time
+     * refusal into the lowering (or the hand-over) that control can execute.
+     *
+     * A promise, not a hint: declare a control only from the code that starts
+     * the harness and writes that control. A caller that hands the plan to
+     * someone else's launcher declares nothing and keeps the refusal, which is
+     * what it can actually deliver.
+     */
     binds?: readonly BindableLaunchControl[];
 }): WorkspacePlan;
 /**

package/dist/index.js

@@ -23,7 +23,7 @@
  */
 export { modelIdsMatch, qualifyModelId } from "./model-id.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, 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({
@@ -86,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.
  *
@@ -120,13 +142,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 +172,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 +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.
@@ -204,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",
@@ -220,6 +377,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 +457,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 +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
                 ? {}
@@ -665,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);
     };
@@ -725,36 +923,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 +1010,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 +1075,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 +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) }),
-        ...(classicPlan.appendSystemPrompt === undefined
-            ? {}
-            : {
-                appendSystemPrompt: candidatePublicValue(classicPlan.appendSystemPrompt),
-            }),
+        ...promptIntentFields(classicPlan, candidatePublicValue),
         unsupported: classicPlan.unsupported,
     };
 }
@@ -1281,6 +1524,7 @@ function normalizePlanFiles(files) {
             relPath,
             content: file.content,
             mode,
+            ownership: file.ownership ?? "shared",
             secretSlots,
         };
     })
@@ -1332,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
             ? {}
             : {
@@ -1355,12 +1603,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 +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 }),
-        ...(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 +1684,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 +1696,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 +1781,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 +1848,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 +1860,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 +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}`);
         }
@@ -1707,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 });
                 }
@@ -1762,12 +1999,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,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Materialize an AgentProfile into the native per-harness workspace files (the one shared materializer for cli-bridge, agent-dev-container, and VB).",
   "type": "module",
   "main": "./dist/index.js",