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

package/dist/index.d.ts

@@ -22,6 +22,7 @@
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
 export { modelIdsMatch, qualifyModelId } from "./model-id.js";
+export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, type PrimeProfileErrorKind, type PrimeThinkingLevel, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 import type { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileConfigValue, AgentProfileMcpServer, AgentProfileSecretProvider, AgentProfileSecretRef, Sha256Digest } from "@tangle-network/agent-interface";
 export declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
 /**
@@ -503,31 +504,105 @@ export interface PrimeProfileSubagent {
 export interface PrimeProfileControls {
     systemPrompt?: string;
     appendSystemPrompt?: string;
+    /** Composed caller instructions, lowered to the agent dir's AGENTS.md. */
+    instructions?: string;
     skills: PrimeProfileSkill[];
     subagents: PrimeProfileSubagent[];
 }
+/** True when the controls materialize anything at all. */
+export declare function hasPrimeProfileMaterial(controls: PrimeProfileControls): boolean;
+/**
+ * True when the controls must WRITE INTO the agent dir itself.
+ *
+ * Prompt files and skill dirs are named by a flag, so they can live anywhere
+ * the agent can read (`--system-prompt` / `--append-system-prompt` resolve a
+ * path when it exists, fork resource-loader.ts:41-56; `--skill` takes an
+ * arbitrary dir, :437-442). The context file and the continual-harness store
+ * are located BY the agent dir and have no flag, so they cannot move.
+ *
+ * An executor pointed at an agent dir it does not own (an operator's shared
+ * dir) uses this to refuse exactly the controls it would have to write there,
+ * while still binding the ones it can materialize elsewhere.
+ */
+export declare function primeProfileNeedsAgentDir(controls: PrimeProfileControls): boolean;
 /**
  * Validate and extract the profile controls the prime agent-dir lowering
- * materializes. Throws on any control (or control facet) the fork has no
- * verified read path for — partial acceptance would silently drop the rest.
+ * materializes. Throws {@link PrimeProfileError} on any control (or control
+ * facet) the fork has no verified read path for — partial acceptance would
+ * silently drop the rest.
  */
 export declare function readPrimeProfileControls(profile: AgentProfile | undefined): PrimeProfileControls;
+/**
+ * Refuse a run whose selected model disagrees with the profile's own.
+ *
+ * One authority per run: a profile names the model it was written and scored
+ * against, so running it on a different one silently scores a different agent.
+ * Both sides go through {@link modelIdsMatch}, so the qualification level a
+ * caller happened to use is not a conflict.
+ *
+ * `provider` is the executor's PROVIDER SELECTION, and is compared only when
+ * the executor's provider is part of model identity. An executor whose
+ * provider key is merely a namespace inside the agent dir passes it as
+ * undefined and gets the model-name comparison alone.
+ */
+export declare function assertPrimeModelAgreement(profile: AgentProfile | undefined, selected: {
+    provider?: string;
+    model: string;
+}): void;
 /** Deterministic harness-state entry id for a profile subagent name. */
 export declare function primeSubagentEntryId(name: string): string;
 /**
- * Materialize the validated controls into `agentDir` and return the extra
- * spawn args that bind them. Runs before every spawn (same place models.json
- * is materialized), so a continual agent dir is re-pinned to the current
- * profile on each fresh prime process.
+ * Write one agent-dir file atomically (temp + rename).
+ *
+ * Every file this lowering writes lands in a directory a LIVE agent may be
+ * reading: prime reloads models.json at model-resolution time and re-reads the
+ * harness store on every system-prompt build, so a partial write is observable.
+ * `mode` is applied to the temp file before the rename, so the final file is
+ * never briefly world-readable.
+ */
+export declare function writePrimeAgentFile(path: string, data: string, mode?: number): void;
+export interface PrimeMaterializeOptions {
+    /**
+     * Where the FLAG-NAMED files go — the prompt files and the skills root.
+     * Defaults to `agentDir`. An executor that does not own the agent dir points
+     * this at a per-run directory of its own, so binding a profile's prompts and
+     * skills writes nothing into a dir it must not modify. The context file and
+     * the harness store have no flag and always land in `agentDir`; refuse those
+     * with {@link primeProfileNeedsAgentDir} instead.
+     */
+    flagFileRoot?: string;
+    /**
+     * Reports state the executor should see but that does not fail the run
+     * (currently: adopting entries a pre-shared executor left behind).
+     */
+    warn?: (msg: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Materialize the validated controls and return the extra spawn args that bind
+ * them. Runs before every spawn (same place models.json is materialized), so a
+ * continual agent dir is re-pinned to the current profile on each fresh prime
+ * process.
+ */
+export declare function materializePrimeProfileControls(agentDir: string, controls: PrimeProfileControls, options?: PrimeMaterializeOptions): string[];
+/**
+ * Remove the files a PREVIOUS materialization of this lowering wrote, so a
+ * profile that shrank cannot leave a stale instruction file or skill behind for
+ * the next run against the same dirs.
+ *
+ * Only the paths this lowering NAMES are removed. There is deliberately no
+ * manifest: a manifest would live where the agent can write it, and reading a
+ * delete list out of agent-writable state turns pruning into an arbitrary-path
+ * delete.
  */
-export declare function materializePrimeProfileControls(agentDir: string, controls: PrimeProfileControls, warn: (msg: string, meta?: Record<string, unknown>) => void): string[];
+export declare function prunePrimeProfileMaterial(agentDir: string, options?: Pick<PrimeMaterializeOptions, "flagFileRoot">): void;
 /**
  * Upsert profile subagent specs into the fork's global continual-harness
  * store and remove profile-sourced entries the current profile no longer
- * declares. Agent-written entries (`source: "agent"`) are never touched.
+ * declares. Agent-written entries (`source: "agent"`) — and every top-level
+ * key this lowering does not manage — are preserved untouched.
  *
- * A pre-existing unparsable store degrades to empty exactly like the fork's
- * own loader (refinement.ts:290-300 — "a corrupt state file must degrade to
- * empty rather than throw"), with a warning so the reset is visible.
+ * A store that exists but no longer parses raises
+ * {@link PrimeHarnessStateError}: the file is the agent's own self-modification
+ * state, and overwriting it destroys what the run was supposed to observe.
  */
-export declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn: (msg: string, meta?: Record<string, unknown>) => void): void;
+export declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn?: (msg: string, meta?: Record<string, unknown>) => void): void;

package/dist/index.js

@@ -22,10 +22,13 @@
  * cli-bridge and agent-dev-container — this is the single source those re-export.
  */
 export { modelIdsMatch, qualifyModelId } from "./model-id.js";
+export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_FORK_INSTALL, PRIME_FORK_PIN, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PrimeHarnessStateError, PrimeProfileError, parsePrimeModelsJson, primeAgentDirEnv, primeApiKeyEnvNames, primeThinkingLevel, stripPrimeJsonComments, } from "./prime-fork.js";
 import { createHash, randomUUID } from "node:crypto";
-import { closeSync, existsSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { closeSync, existsSync, fchmodSync, constants as fsConstants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync, } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep, win32, } from "node:path";
 import { agentCandidateProfileActivationSchema, agentCandidateProfilePlanEvidenceSchema, agentCandidateProfilePlanMaterialSchema, agentCandidateProfileSchema, agentProfileSchema, agentProfileSecretRefSchema, canonicalCandidateBytes, canonicalCandidateDigest, resolveNativeWebTools, } from "@tangle-network/agent-interface";
+import { modelIdsMatch, qualifyModelId } from "./model-id.js";
+import { PRIME_MCP_UNSUPPORTED_REASON, PrimeHarnessStateError, rejectPrimeControl, rejectPrimeDeclaration, } from "./prime-fork.js";
 export const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER = Object.freeze({
     async get() {
         return undefined;
@@ -3173,12 +3176,29 @@ function materializeCommand(h, name, body, add, unsupported) {
 //   and the addition appends after it (system-prompt.ts:61,109-110). Values
 //   are materialized as FILES under the agent dir because the flag value is
 //   read as a file when the path exists (resource-loader.ts:41-56), which
-//   keeps literal-vs-path resolution deterministic.
+//   keeps literal-vs-path resolution deterministic AND removes the argv size
+//   ceiling an inline flag value would run into (Linux MAX_ARG_STRLEN).
+//
+// - `prompt.instructions` / `resources.instructions` → `<agentDir>/AGENTS.md`.
+//   The agent dir IS an instruction surface: `loadProjectContextFiles`
+//   (resource-loader.ts:76) reads the agent dir's own AGENTS.md/CLAUDE.md as
+//   the GLOBAL context file (:86 `loadContextFileFromDir(resolvedAgentDir)`,
+//   candidates at :59) BEFORE walking the cwd ancestors (:94-112), and the
+//   result is loaded unless `--no-context-files` (:476). Writing it here
+//   touches no caller workspace content, which is what the agent-dir lowering
+//   exists to guarantee. (`materializeProfile(profile, "prime")` lowers the
+//   same intent to the cwd AGENTS.md for callers that own the workspace
+//   instead of the agent dir.)
 //
 // - `resources.skills` (inline refs) → `--skill <agentDir>/profile/skills`
 //   (cli/args.ts:207-209 → main.ts:652 → agent-session-config.ts:67 →
-//   additionalSkillPaths, resource-loader.ts:437-442). The loader recurses
-//   into `<name>/SKILL.md` subdirs (skills.ts:328-372) and loaded skills are
+//   additionalSkillPaths, resource-loader.ts:437-442). An explicit flag rather
+//   than the agent dir's auto-discovered `skills/` tree (package-manager.ts:884
+//   global base, :2171 skills dir, :2240-2246 discovery), which also loads but
+//   goes through the fork's global-vs-project dedupe (package-manager.ts:880,
+//   "project scope wins over global") — so an unrelated project-scope skill of
+//   the same name silently shadows the profile's. The loader recurses into
+//   `<name>/SKILL.md` subdirs (skills.ts:328-372) and loaded skills are
 //   rendered into the system prompt (agent-session.ts:4272-4291,
 //   system-prompt.ts:87-89). The fork silently DROPS a SKILL.md without a
 //   frontmatter description (skills.ts:416-419), so content is normalized
@@ -3192,25 +3212,17 @@ function materializeCommand(h, name, body, add, unsupported) {
 //   reaches the same store through the host-set RLM_GLOBAL_HARNESS_STATE_DIR
 //   (agent-session.ts:8805).
 //
-// Kept REJECTED with the fork evidence:
-//
-// - `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.
+// Kept REJECTED with the fork evidence — see {@link PRIME_MCP_UNSUPPORTED_REASON}
+// for `mcp`/`connections`, and the per-control reasons in
+// {@link readPrimeProfileControls} for permissions, tools, hooks, modes,
+// confidential, and the resource kinds with no agent-dir read path.
 //
-// - `prompt.instructions`: the fork's caller-instruction surface is the
-//   workspace AGENTS.md/CLAUDE.md context file (resource-loader.ts:58-66),
-//   i.e. caller workspace content this agent-dir lowering must not write
-//   into. (`materializeProfile(profile, "prime")` lowers instructions to the
-//   cwd AGENTS.md instead, which the fork walks from cwd:
-//   resource-loader.ts:94-109.)
+// The store is AGENT-OWNED: it is written by the agent mid-session and rides
+// every later system prompt. A store that exists but no longer parses
+// therefore fails the turn ({@link PrimeHarnessStateError}) rather than being
+// reseeded from empty — the fork's own loader degrades to empty in-process
+// (refinement.ts:290-300), but an executor that OVERWRITES the file makes that
+// degradation permanent and destroys the evidence of what happened.
 /** Skill name rules enforced by the fork's Agent Skills loader (skills.ts:122-147). */
 const PRIME_SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PRIME_MAX_SKILL_NAME_LENGTH = 64;
@@ -3218,6 +3230,8 @@ const PRIME_PROFILE_DIR_NAME = "profile";
 const PRIME_SKILLS_DIR_NAME = "skills";
 const PRIME_SYSTEM_PROMPT_FILE = "system-prompt.md";
 const PRIME_APPEND_SYSTEM_PROMPT_FILE = "append-system-prompt.md";
+/** Agent-dir global context file the fork reads (resource-loader.ts:59,86). */
+const PRIME_CONTEXT_FILE = "AGENTS.md";
 /** Fork continual-harness store location under the agent dir (refinement.ts:269-279). */
 const PRIME_HARNESS_DIR_NAME = "harness";
 const PRIME_HARNESS_STATE_FILE = "harness_state.json";
@@ -3228,22 +3242,101 @@ const PRIME_HARNESS_KINDS = ["prompt", "memory", "skill", "subagent"];
  * touched.
  */
 const PRIME_PROFILE_ENTRY_SOURCE = "profile";
-function rejectPrimeControl(control, reason) {
-    throw new Error(`prime does not support AgentProfile ${control}: ${reason}`);
+/**
+ * Provenance markers written by executors that predate this shared lowering.
+ *
+ * Pruning keys on the source tag, so an executor that switches to the shared
+ * implementation would otherwise leave its own earlier entries behind forever:
+ * they match no current profile and no current source, and the model's
+ * spawnable roster silently accumulates duplicates of every subagent. They are
+ * adopted (pruned or replaced) on the first shared run instead.
+ */
+const PRIME_LEGACY_PROFILE_ENTRY_SOURCES = [
+    "cli-bridge-profile",
+];
+/** True when the controls materialize anything at all. */
+export function hasPrimeProfileMaterial(controls) {
+    return (controls.systemPrompt !== undefined ||
+        controls.appendSystemPrompt !== undefined ||
+        primeProfileNeedsAgentDir(controls) ||
+        controls.skills.length > 0);
+}
+/**
+ * True when the controls must WRITE INTO the agent dir itself.
+ *
+ * Prompt files and skill dirs are named by a flag, so they can live anywhere
+ * the agent can read (`--system-prompt` / `--append-system-prompt` resolve a
+ * path when it exists, fork resource-loader.ts:41-56; `--skill` takes an
+ * arbitrary dir, :437-442). The context file and the continual-harness store
+ * are located BY the agent dir and have no flag, so they cannot move.
+ *
+ * An executor pointed at an agent dir it does not own (an operator's shared
+ * dir) uses this to refuse exactly the controls it would have to write there,
+ * while still binding the ones it can materialize elsewhere.
+ */
+export function primeProfileNeedsAgentDir(controls) {
+    return controls.instructions !== undefined || controls.subagents.length > 0;
+}
+/**
+ * Read one instruction block, which the profile may carry inline or as a
+ * resource ref. Only inline refs are accepted: resolving a GitHub-backed ref
+ * fetches remote content, which is `resolveAgentProfileResources`' job and
+ * must happen before a profile reaches an executor.
+ */
+function primeInstructionBlock(value, control) {
+    if (typeof value === "string")
+        return value;
+    if (value.kind === "inline")
+        return value.content;
+    rejectPrimeControl(control, "only inline resource refs are accepted — resolve GitHub-backed refs " +
+        "(resolveAgentProfileResources) before handing the profile to this lowering.");
 }
 /**
  * Validate and extract the profile controls the prime agent-dir lowering
- * materializes. Throws on any control (or control facet) the fork has no
- * verified read path for — partial acceptance would silently drop the rest.
+ * materializes. Throws {@link PrimeProfileError} on any control (or control
+ * facet) the fork has no verified read path for — partial acceptance would
+ * silently drop the rest.
  */
 export function readPrimeProfileControls(profile) {
     const controls = { skills: [], subagents: [] };
     if (!profile)
         return controls;
     if (profile.harness !== undefined && profile.harness !== "prime") {
-        throw new Error(`prime cannot run a profile pinned to harness "${profile.harness}" — ` +
+        rejectPrimeDeclaration("harness", `prime cannot run a profile pinned to harness "${profile.harness}" — ` +
             'only "prime" (or an unset harness preference) is accepted.');
     }
+    // An entry with `enabled: false` is OFF, not requested. A fully disabled map
+    // asks for nothing, so accepting it drops no control — which is the only
+    // thing this refusal exists to prevent.
+    const requestedMcp = Object.keys(activeMcpServers(profile.mcp));
+    if (requestedMcp.length > 0) {
+        rejectPrimeControl(`mcp: ${requestedMcp.join(", ")}`, PRIME_MCP_UNSUPPORTED_REASON);
+    }
+    if (profile.connections !== undefined) {
+        rejectPrimeControl("connections", `a hub connection grant resolves to MCP tools, and ${PRIME_MCP_UNSUPPORTED_REASON}`);
+    }
+    if (profile.permissions !== undefined) {
+        rejectPrimeControl("permissions", "prime-agent exposes no permission control at all (full flag scan of fork " +
+            "cli/args.ts:93-295; native tools run unconditionally), so a permission map " +
+            "would be accepted and never enforced.");
+    }
+    if (profile.tools !== undefined) {
+        rejectPrimeControl("tools", "the only per-run tool control is `--tools` over the single builtin `ipython` " +
+            "(fork cli/args.ts:63-64,156-167); bash/edit and the rest are extension-provided " +
+            "and not addressable per run, so a harness-neutral tool map cannot bind to it.");
+    }
+    if (profile.hooks !== undefined) {
+        rejectPrimeControl("hooks", "prime-agent has no hook mechanism (fork cli/args.ts flag scan; extensions are " +
+            "host-trusted JS modules loaded into the agent process, not caller command hooks).");
+    }
+    if (profile.modes !== undefined) {
+        rejectPrimeControl("modes", "prime-agent has no mode concept (fork cli/args.ts flag scan).");
+    }
+    if (profile.confidential !== undefined) {
+        rejectPrimeControl("confidential", "confidential execution is a property of the executor's isolation boundary, not " +
+            "of the agent dir; this lowering cannot establish it.");
+    }
+    const instructionBlocks = [];
     if (profile.prompt) {
         const { systemPrompt, appendSystemPrompt, instructions } = profile.prompt;
         const knownPromptFields = new Set([
@@ -3257,15 +3350,9 @@ export function readPrimeProfileControls(profile) {
         if (unknown.length > 0) {
             rejectPrimeControl(`prompt fields: ${unknown.join(", ")}`, "no verified prime-agent read path exists for them.");
         }
-        if (instructions !== undefined) {
-            rejectPrimeControl("prompt.instructions", "prime-agent's caller-instruction surface is the workspace " +
-                "AGENTS.md context file (fork resource-loader.ts:58-66), which is " +
-                "caller workspace content this adapter must not write into. Use " +
-                "prompt.appendSystemPrompt instead.");
-        }
         if (systemPrompt !== undefined) {
             if (typeof systemPrompt !== "string" || systemPrompt.trim() === "") {
-                rejectPrimeControl("prompt.systemPrompt", "an empty replacement would delete the built-in system prompt and " +
+                rejectPrimeDeclaration("prompt.systemPrompt", "an empty replacement would delete the built-in system prompt and " +
                     "install nothing.");
             }
             controls.systemPrompt = systemPrompt;
@@ -3273,52 +3360,69 @@ export function readPrimeProfileControls(profile) {
         if (appendSystemPrompt !== undefined) {
             if (typeof appendSystemPrompt !== "string" ||
                 appendSystemPrompt.trim() === "") {
-                rejectPrimeControl("prompt.appendSystemPrompt", "must be non-empty text.");
+                rejectPrimeDeclaration("prompt.appendSystemPrompt", "must be non-empty text.");
             }
             controls.appendSystemPrompt = appendSystemPrompt;
         }
+        for (const block of instructions ?? []) {
+            if (typeof block === "string" && block.trim() !== "")
+                instructionBlocks.push(block);
+        }
     }
     if (profile.resources) {
-        const { skills, failOnError, ...unsupported } = profile.resources;
+        const { skills, instructions, failOnError, ...unsupported } = profile.resources;
         const rejectedKeys = Object.entries(unsupported)
             .filter(([, value]) => value !== undefined)
             .map(([key]) => key);
         if (rejectedKeys.length > 0) {
-            rejectPrimeControl(`resources: ${rejectedKeys.join(", ")}`, "only resources.skills has a verified prime-agent read path " +
-                "(--skill dirs, fork resource-loader.ts:437-442).");
+            rejectPrimeControl(`resources: ${rejectedKeys.join(", ")}`, "only resources.skills (--skill dirs, fork resource-loader.ts:437-442) and " +
+                "resources.instructions (agent-dir AGENTS.md, resource-loader.ts:86) have a " +
+                "verified prime-agent read path. Generic workspace files, tool files, " +
+                "subagent-definition files and prompt templates either have no headless read " +
+                "path or would run caller-authored code inside the agent process.");
         }
         if (failOnError === false) {
-            rejectPrimeControl("resources.failOnError: false", "this adapter always fails loud on a resource it cannot " +
+            rejectPrimeControl("resources.failOnError: false", "this lowering always fails loud on a resource it cannot " +
                 "materialize; lenient materialization is not implemented.");
         }
+        if (instructions !== undefined) {
+            const block = primeInstructionBlock(instructions, "resources.instructions");
+            if (block.trim() !== "")
+                instructionBlocks.push(block);
+        }
         const seen = new Set();
-        for (const ref of skills ?? []) {
+        for (const [index, ref] of (skills ?? []).entries()) {
             if (ref.kind !== "inline") {
-                rejectPrimeControl(`resources.skills ref "${"path" in ref ? ref.path : ""}"`, "only inline skill refs are accepted — resolve GitHub refs " +
+                rejectPrimeControl(`resources.skills[${index}]`, "only inline skill refs are accepted — resolve GitHub-backed refs " +
                     "(resolveAgentProfileResources) before handing the profile to " +
-                    "this adapter.");
+                    "this lowering.");
             }
             const name = ref.name;
             if (!PRIME_SKILL_NAME_RE.test(name) ||
                 name.length > PRIME_MAX_SKILL_NAME_LENGTH) {
-                rejectPrimeControl(`resources.skills name "${name}"`, "prime-agent skill names must be lowercase a-z0-9 with single " +
-                    `hyphens, at most ${PRIME_MAX_SKILL_NAME_LENGTH} chars (fork skills.ts:122-147).`);
+                rejectPrimeDeclaration(`resources.skills[${index}]`, `name ${JSON.stringify(name)} is not a valid prime skill name — it becomes the ` +
+                    "skill directory name, so it must be lowercase a-z0-9 with single hyphens, at " +
+                    `most ${PRIME_MAX_SKILL_NAME_LENGTH} chars (fork skills.ts:122-147).`);
             }
             if (seen.has(name)) {
-                rejectPrimeControl(`resources.skills name "${name}"`, "duplicate skill names collide in the fork's skill registry.");
+                rejectPrimeDeclaration("resources.skills", `declares ${JSON.stringify(name)} twice; duplicate skill names collide in the ` +
+                    "fork's skill registry, which keeps only the first and warns.");
             }
             seen.add(name);
             if (ref.content.trim() === "") {
-                rejectPrimeControl(`resources.skills "${name}"`, "skill content is empty.");
+                rejectPrimeDeclaration(`resources.skills[${index}]`, `skill ${JSON.stringify(name)} declares no content.`);
             }
             controls.skills.push({ name, content: ref.content });
         }
     }
+    if (instructionBlocks.length > 0) {
+        controls.instructions = instructionBlocks.join("\n\n");
+    }
     if (profile.subagents) {
         const usedIds = new Map();
         for (const [name, spec] of Object.entries(profile.subagents)) {
             if (name.trim() === "") {
-                rejectPrimeControl("subagents", "a subagent name must be non-empty.");
+                rejectPrimeDeclaration("subagents", "a subagent name must be non-empty.");
             }
             const inexpressible = [
                 ["model", spec.model],
@@ -3329,19 +3433,20 @@ export function readPrimeProfileControls(profile) {
                 .filter(([, value]) => value !== undefined)
                 .map(([key]) => key);
             if (inexpressible.length > 0) {
-                rejectPrimeControl(`subagents["${name}"] fields: ${inexpressible.join(", ")}`, "a prime continual-harness subagent spec is prompt-roster " +
+                rejectPrimeControl(`subagents[${JSON.stringify(name)}] fields: ${inexpressible.join(", ")}`, "a prime continual-harness subagent spec is prompt-roster " +
                     "guidance for `await rlm('<task>')` (fork refinement.ts:483-496) " +
                     "and pins no model, tool set, permission, or step budget on the " +
                     "spawned child.");
             }
             if (!spec.description?.trim() && !spec.prompt?.trim()) {
-                rejectPrimeControl(`subagents["${name}"]`, "a spec needs a description and/or prompt — an empty entry gives " +
-                    "the model an empty roster line.");
+                rejectPrimeDeclaration(`subagents[${JSON.stringify(name)}]`, "declares no behavior — a spec needs a description and/or prompt, since an " +
+                    "empty entry gives the model an empty roster line.");
             }
             const id = primeSubagentEntryId(name);
             const clash = usedIds.get(id);
             if (clash !== undefined) {
-                rejectPrimeControl(`subagents["${name}"]`, `its id "${id}" collides with subagent "${clash}".`);
+                rejectPrimeDeclaration(`subagents[${JSON.stringify(name)}]`, `collides with subagent ${JSON.stringify(clash)} on harness-state id ` +
+                    `${JSON.stringify(id)}.`);
             }
             usedIds.set(id, name);
             controls.subagents.push({
@@ -3354,6 +3459,39 @@ export function readPrimeProfileControls(profile) {
     }
     return controls;
 }
+/**
+ * Refuse a run whose selected model disagrees with the profile's own.
+ *
+ * One authority per run: a profile names the model it was written and scored
+ * against, so running it on a different one silently scores a different agent.
+ * Both sides go through {@link modelIdsMatch}, so the qualification level a
+ * caller happened to use is not a conflict.
+ *
+ * `provider` is the executor's PROVIDER SELECTION, and is compared only when
+ * the executor's provider is part of model identity. An executor whose
+ * provider key is merely a namespace inside the agent dir passes it as
+ * undefined and gets the model-name comparison alone.
+ */
+export function assertPrimeModelAgreement(profile, selected) {
+    const declared = profile?.model?.default;
+    const declaredProvider = profile?.model?.provider;
+    if (declared !== undefined) {
+        const selectedId = qualifyModelId(selected.provider, selected.model);
+        const declaredId = qualifyModelId(declaredProvider, declared);
+        if (!modelIdsMatch(selectedId, declaredId, selected.provider)) {
+            rejectPrimeDeclaration("model.default", `the run selects ${JSON.stringify(selectedId)} but the profile names ` +
+                `${JSON.stringify(declaredId)}; a profile must not be scored against a model it ` +
+                "does not name.");
+        }
+        return;
+    }
+    if (selected.provider !== undefined &&
+        declaredProvider !== undefined &&
+        declaredProvider !== selected.provider) {
+        rejectPrimeDeclaration("model.provider", `the run selects provider ${JSON.stringify(selected.provider)} but the profile names ` +
+            `${JSON.stringify(declaredProvider)}.`);
+    }
+}
 /** Deterministic harness-state entry id for a profile subagent name. */
 export function primeSubagentEntryId(name) {
     const slug = name
@@ -3363,96 +3501,127 @@ export function primeSubagentEntryId(name) {
     return `profile-${slug || "subagent"}`;
 }
 /**
- * Materialize the validated controls into `agentDir` and return the extra
- * spawn args that bind them. Runs before every spawn (same place models.json
- * is materialized), so a continual agent dir is re-pinned to the current
- * profile on each fresh prime process.
+ * Write one agent-dir file atomically (temp + rename).
+ *
+ * Every file this lowering writes lands in a directory a LIVE agent may be
+ * reading: prime reloads models.json at model-resolution time and re-reads the
+ * harness store on every system-prompt build, so a partial write is observable.
+ * `mode` is applied to the temp file before the rename, so the final file is
+ * never briefly world-readable.
+ */
+export function writePrimeAgentFile(path, data, mode = 0o600) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, data, { mode });
+    renameSync(temp, path);
+}
+/**
+ * Materialize the validated controls and return the extra spawn args that bind
+ * them. Runs before every spawn (same place models.json is materialized), so a
+ * continual agent dir is re-pinned to the current profile on each fresh prime
+ * process.
  */
-export function materializePrimeProfileControls(agentDir, controls, warn) {
+export function materializePrimeProfileControls(agentDir, controls, options = {}) {
+    const { flagFileRoot = agentDir, warn } = options;
     const args = [];
-    const profileDir = join(agentDir, PRIME_PROFILE_DIR_NAME);
+    const profileDir = join(flagFileRoot, PRIME_PROFILE_DIR_NAME);
     if (controls.systemPrompt !== undefined) {
-        mkdirSync(profileDir, { recursive: true });
         const promptPath = join(profileDir, PRIME_SYSTEM_PROMPT_FILE);
-        writeFileSync(promptPath, controls.systemPrompt, "utf8");
+        writePrimeAgentFile(promptPath, controls.systemPrompt);
         args.push("--system-prompt", promptPath);
     }
     if (controls.appendSystemPrompt !== undefined) {
-        mkdirSync(profileDir, { recursive: true });
         const appendPath = join(profileDir, PRIME_APPEND_SYSTEM_PROMPT_FILE);
-        writeFileSync(appendPath, controls.appendSystemPrompt, "utf8");
+        writePrimeAgentFile(appendPath, controls.appendSystemPrompt);
         args.push("--append-system-prompt", appendPath);
     }
+    if (controls.instructions !== undefined) {
+        writePrimeAgentFile(join(agentDir, PRIME_CONTEXT_FILE), `${controls.instructions}\n`);
+    }
     if (controls.skills.length > 0) {
         const skillsRoot = join(profileDir, PRIME_SKILLS_DIR_NAME);
         for (const skill of controls.skills) {
-            const skillDir = join(skillsRoot, skill.name);
-            mkdirSync(skillDir, { recursive: true });
-            writeFileSync(join(skillDir, "SKILL.md"), normalizeSkillMd(skill.name, skill.content), "utf8");
+            writePrimeAgentFile(join(skillsRoot, skill.name, "SKILL.md"), normalizeSkillMd(skill.name, skill.content));
         }
         args.push("--skill", skillsRoot);
     }
     seedPrimeProfileSubagents(agentDir, controls.subagents, warn);
     return args;
 }
-function emptyPrimeHarnessState() {
-    const entries = {};
-    for (const kind of PRIME_HARNESS_KINDS)
-        entries[kind] = {};
-    return { schema: 1, entries, refinements: [] };
+/**
+ * Remove the files a PREVIOUS materialization of this lowering wrote, so a
+ * profile that shrank cannot leave a stale instruction file or skill behind for
+ * the next run against the same dirs.
+ *
+ * Only the paths this lowering NAMES are removed. There is deliberately no
+ * manifest: a manifest would live where the agent can write it, and reading a
+ * delete list out of agent-writable state turns pruning into an arbitrary-path
+ * delete.
+ */
+export function prunePrimeProfileMaterial(agentDir, options = {}) {
+    const { flagFileRoot = agentDir } = options;
+    rmSync(join(flagFileRoot, PRIME_PROFILE_DIR_NAME), {
+        recursive: true,
+        force: true,
+    });
+    rmSync(join(agentDir, PRIME_CONTEXT_FILE), { force: true });
 }
 /**
  * Upsert profile subagent specs into the fork's global continual-harness
  * store and remove profile-sourced entries the current profile no longer
- * declares. Agent-written entries (`source: "agent"`) are never touched.
+ * declares. Agent-written entries (`source: "agent"`) — and every top-level
+ * key this lowering does not manage — are preserved untouched.
  *
- * A pre-existing unparsable store degrades to empty exactly like the fork's
- * own loader (refinement.ts:290-300 — "a corrupt state file must degrade to
- * empty rather than throw"), with a warning so the reset is visible.
+ * A store that exists but no longer parses raises
+ * {@link PrimeHarnessStateError}: the file is the agent's own self-modification
+ * state, and overwriting it destroys what the run was supposed to observe.
  */
 export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
     const statePath = join(agentDir, PRIME_HARNESS_DIR_NAME, PRIME_HARNESS_STATE_FILE);
-    let state = emptyPrimeHarnessState();
+    let state = {};
     if (existsSync(statePath)) {
+        let parsed;
         try {
-            const raw = JSON.parse(readFileSync(statePath, "utf8"));
-            if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
-                const parsed = raw;
-                state.schema =
-                    typeof parsed.schema === "number" ? parsed.schema : state.schema;
-                for (const kind of PRIME_HARNESS_KINDS) {
-                    const records = parsed.entries?.[kind];
-                    if (records && typeof records === "object") {
-                        state.entries[kind] = { ...records };
-                    }
-                }
-                if (Array.isArray(parsed.refinements)) {
-                    state.refinements = parsed.refinements;
-                }
-            }
-            else {
-                warn("prime: existing harness_state.json is not an object — reseeding", {
-                    statePath,
-                });
-            }
+            parsed = JSON.parse(readFileSync(statePath, "utf8"));
         }
         catch (err) {
-            warn("prime: existing harness_state.json is unparsable — reseeding", {
-                statePath,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            state = emptyPrimeHarnessState();
+            throw new PrimeHarnessStateError(statePath, err instanceof Error ? err.message : String(err));
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new PrimeHarnessStateError(statePath, "the store is not a JSON object");
         }
+        state = parsed;
     }
     else if (subagents.length === 0) {
         // Nothing to pin and nothing stale to remove.
         return;
     }
-    const existing = state.entries.subagent ?? {};
+    const rawEntries = state.entries;
+    const entries = rawEntries && typeof rawEntries === "object" && !Array.isArray(rawEntries)
+        ? rawEntries
+        : {};
+    for (const kind of PRIME_HARNESS_KINDS) {
+        const records = entries[kind];
+        if (!records || typeof records !== "object" || Array.isArray(records)) {
+            entries[kind] = {};
+        }
+    }
+    const existing = entries.subagent;
     const desiredIds = new Set(subagents.map((s) => primeSubagentEntryId(s.name)));
     let changed = false;
     for (const [id, entry] of Object.entries(existing)) {
-        if (entry?.source === PRIME_PROFILE_ENTRY_SOURCE && !desiredIds.has(id)) {
+        const source = entry?.source;
+        const isLegacy = typeof source === "string" &&
+            PRIME_LEGACY_PROFILE_ENTRY_SOURCES.includes(source);
+        if (isLegacy) {
+            warn?.("prime: adopting a subagent entry left by a pre-shared executor", {
+                statePath,
+                id,
+                source,
+            });
+        }
+        if ((source === PRIME_PROFILE_ENTRY_SOURCE || isLegacy) &&
+            !desiredIds.has(id)) {
             delete existing[id];
             changed = true;
         }
@@ -3475,7 +3644,7 @@ export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
             kind: "subagent",
             title: spec.name,
             content,
-            path: "profile",
+            path: PRIME_PROFILE_ENTRY_SOURCE,
             scope: "global",
             reference: {},
             arguments: {},
@@ -3489,9 +3658,12 @@ export function seedPrimeProfileSubagents(agentDir, subagents, warn) {
         };
         changed = true;
     }
-    state.entries.subagent = existing;
     if (!changed)
         return;
-    mkdirSync(join(agentDir, PRIME_HARNESS_DIR_NAME), { recursive: true });
-    writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    writePrimeAgentFile(statePath, `${JSON.stringify({
+        ...state,
+        schema: typeof state.schema === "number" ? state.schema : 1,
+        entries,
+        refinements: Array.isArray(state.refinements) ? state.refinements : [],
+    }, null, 2)}\n`);
 }

package/dist/prime-fork.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Fork FACTS for prime-agent (PrimeIntellect-ai/prime-agent) — the constants,
+ * dialects and refusal reasons every executor that drives the fork needs, with
+ * no `node:fs` and no executor assumptions. The agent-dir MATERIALIZATION that
+ * consumes them lives in `./index.ts`; both consumers (cli-bridge's host-spawn
+ * backend on `--mode rpc`, sdk-provider-prime's in-sandbox adapter on
+ * `--mode acp`) read these instead of each keeping a private copy, because a
+ * fork bump must move one file, not two repositories.
+ *
+ * Every value here is verified against the pinned clone named by
+ * {@link PRIME_FORK_PIN}; `tests/prime-fork-pin.test.ts` re-asserts them
+ * against that clone when it is present, so a fork bump fails loudly in one
+ * place.
+ */
+/** The prime-agent clone every constant in this module was read from. */
+export declare const PRIME_FORK_PIN: {
+    readonly repo: "PrimeIntellect-ai/prime-agent";
+    readonly version: "0.7.0";
+    readonly commit: "be9e2fa0";
+    /** Local clone used by the fork-pin test when it exists. */
+    readonly clonePath: "/home/drew/bench-cache/prime-agent";
+    /** Package root inside the clone that the file:line citations are relative to. */
+    readonly packageRoot: "packages/coding-agent/src";
+};
+/**
+ * The fork's package identity, and why it cannot be installed from the npm
+ * registry.
+ *
+ * `@earendil-works/pi-coding-agent` on registry.npmjs.org serves the UPSTREAM
+ * pi line (0.84.x); the fork's 0.7.x versions were never published there. The
+ * two are wire-incompatible — different daemon schema revision, different
+ * config dir, different agent-dir env var (see
+ * {@link PRIME_AGENT_DIR_ENV_VARS}) — so `npm install -g` under that name
+ * yields an agent none of this lowering was verified against. The fork must be
+ * built from source and exposed under a `prime-agent` command name; its own
+ * `bin` entry is `pi` (fork package.json `bin`), which is exactly how the wrong
+ * binary ends up on `PATH` under the right-looking name.
+ */
+export declare const PRIME_FORK_INSTALL: {
+    readonly npmName: "@earendil-works/pi-coding-agent";
+    /** The fork's own bin name — deliberately NOT the command to install it as. */
+    readonly forkBinName: "pi";
+    /** Command name an executor's binary path is expected to resolve to. */
+    readonly expectedCommandName: "prime-agent";
+    readonly sourceRepo: "https://github.com/PrimeIntellect-ai/prime-agent";
+    /** Built entrypoint to expose as `prime-agent`. */
+    readonly sourceEntrypoint: "packages/coding-agent/dist/bundle/cli.js";
+    readonly reason: string;
+};
+/**
+ * Env vars the agent resolves its config dir from, most-specific first.
+ *
+ * The fork derives the name from its own package identity —
+ * `ENV_AGENT_DIR = \`${envPrefix}_CODING_AGENT_DIR\`` where `envPrefix` comes
+ * from `package.json` `piConfig.name` (config.ts:485-498) — so the fork reads
+ * `PRIME_AGENT_CODING_AGENT_DIR` and upstream pi reads `PI_CODING_AGENT_DIR`.
+ * An executor that sets only the fork's name has its isolation SILENTLY
+ * disabled when the binary on PATH turns out to be upstream pi: `getAgentDir()`
+ * falls back to `homedir()/<CONFIG_DIR_NAME>` (config.ts:520-527), one shared
+ * dir — and therefore one shared self-modifying `harness_state.json` — for
+ * every session on the box. Setting BOTH names costs nothing and keeps the
+ * isolation fail-closed under either binary.
+ */
+export declare const PRIME_AGENT_DIR_ENV_VARS: readonly ["PRIME_AGENT_CODING_AGENT_DIR", "PI_CODING_AGENT_DIR"];
+/** Canonical agent-dir env var for the fork itself (config.ts:498). */
+export declare const PRIME_AGENT_DIR_ENV_VAR: "PRIME_AGENT_CODING_AGENT_DIR";
+/** Pin `agentDir` under every name the agent could resolve its config dir from. */
+export declare function primeAgentDirEnv(agentDir: string): Record<string, string>;
+/**
+ * Operator knobs an executor forwards into the agent when they are set.
+ *
+ * `PRIME_AGENT_KERNEL_VENV` is load-bearing for any executor that also pins
+ * HOME: the kernel venv defaults under `homedir()/.prime/agent/kernel-venv`
+ * (kernel/bootstrap.ts:331-342), so a fresh HOME re-bootstraps it through uv on
+ * every run unless the operator's venv path is forwarded
+ * (bootstrap.ts:340 override, :358 branch).
+ */
+export declare const PRIME_KERNEL_ENV_PASSTHROUGH: readonly ["PRIME_AGENT_INSTALL_UV", "PRIME_AGENT_KERNEL_PYTHON", "PRIME_AGENT_KERNEL_VENV"];
+/**
+ * Env vars an executor must NEVER forward from its own environment.
+ *
+ * These re-point the self-modifying continual-harness store OUTSIDE the agent
+ * dir (agent-session.ts:8805 hands the kernel its store location), which
+ * defeats per-session isolation without changing anything an executor inspects.
+ * Isolation is the fail-closed default; sharing state is an explicit opt-in
+ * that names a directory, never an inherited env var.
+ */
+export declare const PRIME_HARNESS_STATE_ENV_DENYLIST: readonly ["RLM_GLOBAL_HARNESS_STATE_DIR", "RLM_HARNESS_STATE_DIR"];
+/**
+ * A prime-agent IPython kernel that dies is never re-provisioned headlessly —
+ * every later `ipython` call fails with one of these markers until the process
+ * is replaced. An executor that cannot recognize them either reports a generic
+ * turn failure or burns its whole timeout against a permanently dead tool.
+ *
+ * Verified in `core/kernel/index.ts`: :723 ("forked kernel exited
+ * unexpectedly"), :750 ("Kernel exited before resolving ports"), :779 ("Kernel
+ * exited during startup"), :820/:837/:1172/:1295 ("Kernel has been shut down").
+ */
+export declare const PRIME_KERNEL_DEAD_MARKERS: readonly string[];
+/** The first kernel-death marker present in `text`, or undefined. */
+export declare function matchPrimeKernelDeadMarker(text: string): string | undefined;
+/**
+ * `--thinking` rungs the fork's argument parser accepts
+ * (cli/args.ts:62 `VALID_THINKING_LEVELS`, rejected at :175). Read from the
+ * fork itself rather than borrowed from upstream pi's measured table: the two
+ * agreeing today is a coincidence this module must not depend on.
+ */
+export declare const PRIME_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type PrimeThinkingLevel = (typeof PRIME_THINKING_LEVELS)[number];
+/**
+ * Map the portable reasoning ladder onto the fork's `--thinking` value.
+ *
+ * Throws on an effort with no rung instead of returning undefined: omitting the
+ * flag runs the agent at its default thinking level while the caller believes
+ * the requested effort is in force, which is a silently dropped control.
+ */
+export declare function primeThinkingLevel(effort: string | null | undefined): PrimeThinkingLevel | undefined;
+/**
+ * Why `profile.mcp` (and any hub connection that resolves to MCP) is refused.
+ *
+ * The fork's `mcpServers` settings surface IS read at startup
+ * (settings-manager.ts:98-120,219) but a user-declared server never becomes
+ * model-visible: the host McpManager registers OAuth providers and serves
+ * mcp.config/refresh host-requests only (core/mcp/mcp-manager.ts:62-124),
+ * skips stdio servers entirely (mcp-manager.ts:73), and nothing generates a
+ * skill or prompt section for one. Model-visible MCP is exactly the built-in
+ * catalog skills, which are hand-written Python `McpIntegration` subclasses
+ * (prime-agent-runtime/src/rlm/mcp_base.py:112-125; only linear and notion
+ * ship). Materializing a per-run entry would run the agent WITHOUT the
+ * requested tools while the config on disk says otherwise.
+ */
+export declare const PRIME_MCP_UNSUPPORTED_REASON: string;
+/** Which half of a profile refusal this is: a fork limit, or a bad declaration. */
+export type PrimeProfileErrorKind = "unsupported" | "invalid";
+/**
+ * Refusal raised by the shared prime lowering, carrying the control and the
+ * reason separately so each executor can render them in its own error contract
+ * (an HTTP backend's typed `BackendError`, an SDK adapter's plain `Error`)
+ * without the reason text — which is where the fork evidence lives — being
+ * rewritten per repository.
+ */
+export declare class PrimeProfileError extends Error {
+    readonly kind: PrimeProfileErrorKind;
+    readonly control: string;
+    readonly reason: string;
+    constructor(kind: PrimeProfileErrorKind, control: string, reason: string);
+}
+/** Raise the "the fork cannot honor this control" half of the refusal. */
+export declare function rejectPrimeControl(control: string, reason: string): never;
+/** Raise the "this declaration is malformed" half of the refusal. */
+export declare function rejectPrimeDeclaration(control: string, reason: string): never;
+/**
+ * The fork's continual-harness store exists but no longer parses.
+ *
+ * The store is the agent's own self-modification state — refinements, learned
+ * prompts, subagents it created mid-session — so an executor that reseeds it
+ * from empty destroys evidence and silently mutates the thing under study. The
+ * turn is failed instead; the file is the operator's to repair or remove.
+ */
+export declare class PrimeHarnessStateError extends Error {
+    readonly statePath: string;
+    constructor(statePath: string, detail: string);
+}
+/**
+ * Strip `//` line comments and trailing commas, leaving string literals
+ * untouched — byte-for-byte the fork's own `stripJsonComments`
+ * (core/model-registry.ts), so a models.json the agent accepts is never refused
+ * by an executor and vice versa.
+ */
+export declare function stripPrimeJsonComments(input: string): string;
+/**
+ * Parse a models.json with the fork's own laxness and assert the one structural
+ * invariant it requires (a `providers` object). Throws naming `sourcePath`.
+ *
+ * This is the SHAPE and DIALECT only. Producing the file is deliberately not
+ * shared: an executor holding real operator credentials copies an
+ * operator-authored file and forwards only the env var names its `apiKey`
+ * entries reference, while an in-sandbox executor synthesizes a one-provider
+ * entry with a literal key that is a proxy dummy. Same schema, opposite threat
+ * models.
+ */
+export declare function parsePrimeModelsJson(text: string, sourcePath: string): Record<string, unknown>;
+/**
+ * Environment variables a models.json names as `apiKey` sources.
+ *
+ * prime resolves an `apiKey` value env-var first and LITERAL second
+ * (core/resolve-config-value.ts), so an executor that forwards exactly the
+ * named variables lets an operator keep secrets out of the file — and an
+ * executor that forwards NONE of them silently turns the variable name itself
+ * into the credential string.
+ */
+export declare function primeApiKeyEnvNames(modelsConfig: Record<string, unknown>): string[];

package/dist/prime-fork.js

@@ -0,0 +1,303 @@
+/**
+ * Fork FACTS for prime-agent (PrimeIntellect-ai/prime-agent) — the constants,
+ * dialects and refusal reasons every executor that drives the fork needs, with
+ * no `node:fs` and no executor assumptions. The agent-dir MATERIALIZATION that
+ * consumes them lives in `./index.ts`; both consumers (cli-bridge's host-spawn
+ * backend on `--mode rpc`, sdk-provider-prime's in-sandbox adapter on
+ * `--mode acp`) read these instead of each keeping a private copy, because a
+ * fork bump must move one file, not two repositories.
+ *
+ * Every value here is verified against the pinned clone named by
+ * {@link PRIME_FORK_PIN}; `tests/prime-fork-pin.test.ts` re-asserts them
+ * against that clone when it is present, so a fork bump fails loudly in one
+ * place.
+ */
+/** The prime-agent clone every constant in this module was read from. */
+export const PRIME_FORK_PIN = {
+    repo: "PrimeIntellect-ai/prime-agent",
+    version: "0.7.0",
+    commit: "be9e2fa0",
+    /** Local clone used by the fork-pin test when it exists. */
+    clonePath: "/home/drew/bench-cache/prime-agent",
+    /** Package root inside the clone that the file:line citations are relative to. */
+    packageRoot: "packages/coding-agent/src",
+};
+/**
+ * The fork's package identity, and why it cannot be installed from the npm
+ * registry.
+ *
+ * `@earendil-works/pi-coding-agent` on registry.npmjs.org serves the UPSTREAM
+ * pi line (0.84.x); the fork's 0.7.x versions were never published there. The
+ * two are wire-incompatible — different daemon schema revision, different
+ * config dir, different agent-dir env var (see
+ * {@link PRIME_AGENT_DIR_ENV_VARS}) — so `npm install -g` under that name
+ * yields an agent none of this lowering was verified against. The fork must be
+ * built from source and exposed under a `prime-agent` command name; its own
+ * `bin` entry is `pi` (fork package.json `bin`), which is exactly how the wrong
+ * binary ends up on `PATH` under the right-looking name.
+ */
+export const PRIME_FORK_INSTALL = {
+    npmName: "@earendil-works/pi-coding-agent",
+    /** The fork's own bin name — deliberately NOT the command to install it as. */
+    forkBinName: "pi",
+    /** Command name an executor's binary path is expected to resolve to. */
+    expectedCommandName: "prime-agent",
+    sourceRepo: "https://github.com/PrimeIntellect-ai/prime-agent",
+    /** Built entrypoint to expose as `prime-agent`. */
+    sourceEntrypoint: "packages/coding-agent/dist/bundle/cli.js",
+    reason: "registry.npmjs.org serves the upstream pi line under @earendil-works/pi-coding-agent " +
+        "(0.84.x); the prime-agent fork's 0.7.x versions do not exist there. Installing from " +
+        "the registry yields a wire-incompatible agent with a different daemon schema, a " +
+        "different config dir, and a different agent-dir env var. Build from source and expose " +
+        "packages/coding-agent/dist/bundle/cli.js as `prime-agent`.",
+};
+/**
+ * Env vars the agent resolves its config dir from, most-specific first.
+ *
+ * The fork derives the name from its own package identity —
+ * `ENV_AGENT_DIR = \`${envPrefix}_CODING_AGENT_DIR\`` where `envPrefix` comes
+ * from `package.json` `piConfig.name` (config.ts:485-498) — so the fork reads
+ * `PRIME_AGENT_CODING_AGENT_DIR` and upstream pi reads `PI_CODING_AGENT_DIR`.
+ * An executor that sets only the fork's name has its isolation SILENTLY
+ * disabled when the binary on PATH turns out to be upstream pi: `getAgentDir()`
+ * falls back to `homedir()/<CONFIG_DIR_NAME>` (config.ts:520-527), one shared
+ * dir — and therefore one shared self-modifying `harness_state.json` — for
+ * every session on the box. Setting BOTH names costs nothing and keeps the
+ * isolation fail-closed under either binary.
+ */
+export const PRIME_AGENT_DIR_ENV_VARS = [
+    "PRIME_AGENT_CODING_AGENT_DIR",
+    "PI_CODING_AGENT_DIR",
+];
+/** Canonical agent-dir env var for the fork itself (config.ts:498). */
+export const PRIME_AGENT_DIR_ENV_VAR = PRIME_AGENT_DIR_ENV_VARS[0];
+/** Pin `agentDir` under every name the agent could resolve its config dir from. */
+export function primeAgentDirEnv(agentDir) {
+    const env = {};
+    for (const name of PRIME_AGENT_DIR_ENV_VARS)
+        env[name] = agentDir;
+    return env;
+}
+/**
+ * Operator knobs an executor forwards into the agent when they are set.
+ *
+ * `PRIME_AGENT_KERNEL_VENV` is load-bearing for any executor that also pins
+ * HOME: the kernel venv defaults under `homedir()/.prime/agent/kernel-venv`
+ * (kernel/bootstrap.ts:331-342), so a fresh HOME re-bootstraps it through uv on
+ * every run unless the operator's venv path is forwarded
+ * (bootstrap.ts:340 override, :358 branch).
+ */
+export const PRIME_KERNEL_ENV_PASSTHROUGH = [
+    /** "1" lets a headless first run install uv itself; "0" forbids it. */
+    "PRIME_AGENT_INSTALL_UV",
+    /** Offline escape hatch: pin the kernel venv python instead of uv-provisioning. */
+    "PRIME_AGENT_KERNEL_PYTHON",
+    /** Reuse an operator-provisioned kernel venv instead of re-bootstrapping it. */
+    "PRIME_AGENT_KERNEL_VENV",
+];
+/**
+ * Env vars an executor must NEVER forward from its own environment.
+ *
+ * These re-point the self-modifying continual-harness store OUTSIDE the agent
+ * dir (agent-session.ts:8805 hands the kernel its store location), which
+ * defeats per-session isolation without changing anything an executor inspects.
+ * Isolation is the fail-closed default; sharing state is an explicit opt-in
+ * that names a directory, never an inherited env var.
+ */
+export const PRIME_HARNESS_STATE_ENV_DENYLIST = [
+    "RLM_GLOBAL_HARNESS_STATE_DIR",
+    "RLM_HARNESS_STATE_DIR",
+];
+/**
+ * A prime-agent IPython kernel that dies is never re-provisioned headlessly —
+ * every later `ipython` call fails with one of these markers until the process
+ * is replaced. An executor that cannot recognize them either reports a generic
+ * turn failure or burns its whole timeout against a permanently dead tool.
+ *
+ * Verified in `core/kernel/index.ts`: :723 ("forked kernel exited
+ * unexpectedly"), :750 ("Kernel exited before resolving ports"), :779 ("Kernel
+ * exited during startup"), :820/:837/:1172/:1295 ("Kernel has been shut down").
+ */
+export const PRIME_KERNEL_DEAD_MARKERS = [
+    "Kernel has been shut down",
+    "Kernel exited before resolving ports",
+    "Kernel exited during startup",
+    "forked kernel exited unexpectedly",
+];
+/** The first kernel-death marker present in `text`, or undefined. */
+export function matchPrimeKernelDeadMarker(text) {
+    return PRIME_KERNEL_DEAD_MARKERS.find((marker) => text.includes(marker));
+}
+/**
+ * `--thinking` rungs the fork's argument parser accepts
+ * (cli/args.ts:62 `VALID_THINKING_LEVELS`, rejected at :175). Read from the
+ * fork itself rather than borrowed from upstream pi's measured table: the two
+ * agreeing today is a coincidence this module must not depend on.
+ */
+export const PRIME_THINKING_LEVELS = [
+    "off",
+    "minimal",
+    "low",
+    "medium",
+    "high",
+    "xhigh",
+    "max",
+];
+/** Canonical portable effort → fork `--thinking` rung. */
+const PRIME_THINKING_BY_EFFORT = {
+    none: "off",
+    minimal: "minimal",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+    // The fork carries `max` above `xhigh`, so the ceiling level reaches it.
+    ultracode: "max",
+};
+/**
+ * Map the portable reasoning ladder onto the fork's `--thinking` value.
+ *
+ * Throws on an effort with no rung instead of returning undefined: omitting the
+ * flag runs the agent at its default thinking level while the caller believes
+ * the requested effort is in force, which is a silently dropped control.
+ */
+export function primeThinkingLevel(effort) {
+    if (effort === undefined || effort === null || effort === "")
+        return undefined;
+    const level = PRIME_THINKING_BY_EFFORT[effort];
+    if (level === undefined) {
+        throw new PrimeProfileError("invalid", "model.reasoningEffort", `prime-agent has no --thinking rung for ${JSON.stringify(effort)} ` +
+            `(fork cli/args.ts:62 accepts ${PRIME_THINKING_LEVELS.join(", ")}).`);
+    }
+    return level;
+}
+/**
+ * Why `profile.mcp` (and any hub connection that resolves to MCP) is refused.
+ *
+ * The fork's `mcpServers` settings surface IS read at startup
+ * (settings-manager.ts:98-120,219) but a user-declared server never becomes
+ * model-visible: the host McpManager registers OAuth providers and serves
+ * mcp.config/refresh host-requests only (core/mcp/mcp-manager.ts:62-124),
+ * skips stdio servers entirely (mcp-manager.ts:73), and nothing generates a
+ * skill or prompt section for one. Model-visible MCP is exactly the built-in
+ * catalog skills, which are hand-written Python `McpIntegration` subclasses
+ * (prime-agent-runtime/src/rlm/mcp_base.py:112-125; only linear and notion
+ * ship). Materializing a per-run entry would run the agent WITHOUT the
+ * requested tools while the config on disk says otherwise.
+ */
+export const PRIME_MCP_UNSUPPORTED_REASON = "a user-declared mcpServers entry is read from the fork's settings.json at startup but never " +
+    "becomes model-visible: the host only registers OAuth/config for it (fork core/mcp/" +
+    "mcp-manager.ts:62-124), skips stdio servers entirely (mcp-manager.ts:73), and generates no " +
+    "skill or prompt section for it. Model-visible MCP is exactly the built-in Python " +
+    "McpIntegration catalog skills (prime-agent-runtime/src/rlm/mcp_base.py:112-125), which no " +
+    "per-run configuration creates — so materializing it would be a silently dropped control.";
+/**
+ * Refusal raised by the shared prime lowering, carrying the control and the
+ * reason separately so each executor can render them in its own error contract
+ * (an HTTP backend's typed `BackendError`, an SDK adapter's plain `Error`)
+ * without the reason text — which is where the fork evidence lives — being
+ * rewritten per repository.
+ */
+export class PrimeProfileError extends Error {
+    kind;
+    control;
+    reason;
+    constructor(kind, control, reason) {
+        super(kind === "unsupported"
+            ? `prime does not support AgentProfile ${control}: ${reason}`
+            : `prime cannot accept AgentProfile ${control}: ${reason}`);
+        this.name = "PrimeProfileError";
+        this.kind = kind;
+        this.control = control;
+        this.reason = reason;
+    }
+}
+/** Raise the "the fork cannot honor this control" half of the refusal. */
+export function rejectPrimeControl(control, reason) {
+    throw new PrimeProfileError("unsupported", control, reason);
+}
+/** Raise the "this declaration is malformed" half of the refusal. */
+export function rejectPrimeDeclaration(control, reason) {
+    throw new PrimeProfileError("invalid", control, reason);
+}
+/**
+ * The fork's continual-harness store exists but no longer parses.
+ *
+ * The store is the agent's own self-modification state — refinements, learned
+ * prompts, subagents it created mid-session — so an executor that reseeds it
+ * from empty destroys evidence and silently mutates the thing under study. The
+ * turn is failed instead; the file is the operator's to repair or remove.
+ */
+export class PrimeHarnessStateError extends Error {
+    statePath;
+    constructor(statePath, detail) {
+        super(`prime harness state ${statePath} is not valid JSON and may hold agent self-modification ` +
+            `state; refusing to overwrite it — repair or remove the file to continue (${detail})`);
+        this.name = "PrimeHarnessStateError";
+        this.statePath = statePath;
+    }
+}
+/**
+ * Strip `//` line comments and trailing commas, leaving string literals
+ * untouched — byte-for-byte the fork's own `stripJsonComments`
+ * (core/model-registry.ts), so a models.json the agent accepts is never refused
+ * by an executor and vice versa.
+ */
+export function stripPrimeJsonComments(input) {
+    return input
+        .replace(/"(?:\\.|[^"\\])*"|\/\/[^\n]*/g, (m) => (m[0] === '"' ? m : ""))
+        .replace(/"(?:\\.|[^"\\])*"|,(\s*[}\]])/g, (m, tail) => tail !== undefined ? tail : m[0] === '"' ? m : "");
+}
+/**
+ * Parse a models.json with the fork's own laxness and assert the one structural
+ * invariant it requires (a `providers` object). Throws naming `sourcePath`.
+ *
+ * This is the SHAPE and DIALECT only. Producing the file is deliberately not
+ * shared: an executor holding real operator credentials copies an
+ * operator-authored file and forwards only the env var names its `apiKey`
+ * entries reference, while an in-sandbox executor synthesizes a one-provider
+ * entry with a literal key that is a proxy dummy. Same schema, opposite threat
+ * models.
+ */
+export function parsePrimeModelsJson(text, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripPrimeJsonComments(text));
+    }
+    catch (err) {
+        throw new Error(`prime models.json ${sourcePath} is not valid JSON: ${err.message}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`prime models.json ${sourcePath} must be a JSON object`);
+    }
+    const providers = parsed.providers;
+    if (!providers || typeof providers !== "object" || Array.isArray(providers)) {
+        throw new Error(`prime models.json ${sourcePath} must carry a "providers" object (prime's models.json schema)`);
+    }
+    return parsed;
+}
+/**
+ * Environment variables a models.json names as `apiKey` sources.
+ *
+ * prime resolves an `apiKey` value env-var first and LITERAL second
+ * (core/resolve-config-value.ts), so an executor that forwards exactly the
+ * named variables lets an operator keep secrets out of the file — and an
+ * executor that forwards NONE of them silently turns the variable name itself
+ * into the credential string.
+ */
+export function primeApiKeyEnvNames(modelsConfig) {
+    const names = [];
+    const providers = modelsConfig.providers;
+    if (!providers || typeof providers !== "object")
+        return names;
+    for (const provider of Object.values(providers)) {
+        if (!provider || typeof provider !== "object")
+            continue;
+        const key = provider.apiKey;
+        if (typeof key !== "string" || !/^[A-Z_][A-Z0-9_]*$/.test(key))
+            continue;
+        if (!names.includes(key))
+            names.push(key);
+    }
+    return names;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-profile-materialize",
-  "version": "0.12.0",
+  "version": "0.13.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",