@tangle-network/agent-profile-materialize 1.1.6 → 1.1.8

package/dist/index.d.ts

@@ -1,29 +1,1226 @@
-export { applyAgentCandidateWorkspacePlan, materializeCandidateProfile, } from "./candidate.js";
-export type { AgentCandidateWorkspacePlan, AgentCandidateWorkspacePlanReceipt, ApplyAgentCandidateWorkspacePlanOptions, MaterializeCandidateProfileOptions, } from "./candidate-types.js";
-export { OPENCODE_NATIVE_TOOL_IDS, openCodeNativeToolId, } from "./control-maps.js";
-export type { HarnessId } from "./harness.js";
-export { HARNESS_SKILL_DIRS, harnessAutoLoadsAgentContextFile, isMaterializerHarness, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, markMaterializerContextFile, skillDirForHarness, } from "./harness.js";
-export * from "./harness-prompt.js";
-export { type ConcurrentProfileRevision, ensurePublicConcurrentProfileRoots, type ManagedWorkspaceFileDigest, type ManagedWorkspaceManifest, preparePublicConcurrentProfileRevision, } from "./managed-workspace.js";
-export { isMaterializerMcpConfig } from "./mcp-config-ownership.js";
-export { type OpenCodeMcpConfig, openCodeMcpConfig } from "./mcp-opencode.js";
-export * from "./model-id.js";
-export { buildPiModelsConfig, buildPiModelsConfigFile, PI_MODELS_CONFIG_PATH, type PiModelsConfigFile, type PiModelsConfigInput, type PiRuntimePaths, resolvePiRuntimePaths, } from "./pi-models-config.js";
-export { applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, } from "./plan-application.js";
-export { agentCandidateProfilePlanMaterial, canonicalizeAgentCandidateProfilePlan, captureAgentCandidateProfilePlan, hashWorkspacePlan, } from "./plan-digest.js";
-export { takeSystemPromptBinding } from "./plan-prompt.js";
-export { assertWorkspacePlanSupported, enforceWorkspacePlanSupport, } from "./plan-support.js";
-export type { ApplyWorkspacePlanOptions, BindableLaunchControl, ExecutorSystemPromptBinding, PlanFile, PlanFileRoot, PlanFileSecretSlot, PlanRequirement, SkippableDimension, Unsupported, WorkspacePlan, WorkspacePlanApplication, WorkspacePlanArgument, WorkspacePlanArgumentTemplate, WorkspacePlanConfigValue, WorkspacePlanReceipt, WorkspacePlanSecretSegment, WorkspacePlanSpawnInputs, WorkspacePlanSystemPromptBinding, WorkspacePlanWrittenFile, } from "./plan-types.js";
-export { BINDABLE_LAUNCH_CONTROLS, EXECUTOR_SYSTEM_PROMPT_BINDINGS, isSkippableDimension, SKIPPABLE_DIMENSIONS, WorkspacePlanCleanupError, } from "./plan-types.js";
-export { materializePrimeProfileControls, type PrimeMaterializeOptions, primeHarnessStatePath, prunePrimeProfileMaterial, seedPrimeProfileSubagents, writePrimeAgentFile, } from "./prime-agent-dir.js";
-export type { PrimeProfileErrorKind, PrimeThinkingLevel, } from "./prime-fork.js";
-export { matchPrimeKernelDeadMarker, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, 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";
-export type { PrimeProfileControls, PrimeProfileSkill, PrimeProfileSubagent, } from "./prime-profile.js";
-export { assertPrimeModelAgreement, hasPrimeProfileMaterial, primeProfileNeedsAgentDir, primeSubagentEntryId, readPrimeProfileControls, } from "./prime-profile.js";
-export * from "./profile-bundle-cache.js";
-export { executionControlConflict, materializeProfile, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, } from "./profile-materializer.js";
-export type { ResolveAgentProfileResourcesOptions } from "./resource-resolution.js";
-export { normalizeSkillMd, resolveAgentProfileResources, } from "./resource-resolution.js";
-export { prepareSecretConcurrentProfileRevision } from "./secret-concurrent-revision.js";
-export * from "./secret-session-view.js";
-export * from "./tool-bin-path.js";
+import { AgentCandidateConfigValue, AgentCandidateProfile, AgentCandidateProfileActivation, AgentCandidateProfileApplication, AgentCandidateProfilePlanEvidence, AgentCandidateProfilePlanMaterial, AgentProfile, AgentProfileConfigValue, AgentProfileFileMount, AgentProfileMcpServer, AgentProfileSecretProvider, AgentProfileSecretRef, AgentRuntimeAttachments, Sha256Digest } from "@tangle-network/agent-interface";
+
+//#region src/harness.d.ts
+declare const MATERIALIZER_HARNESSES: readonly ["claude-code", "nanoclaw", "codex", "opencode", "kimi-code", "pi", "prime", "gemini", "hermes", "openclaw"];
+type HarnessId = (typeof MATERIALIZER_HARNESSES)[number];
+declare function isMaterializerHarness(harness: string): harness is HarnessId;
+/** Whether the shared materializer may place its context file in the harness agent directory. */
+declare function harnessAutoLoadsAgentContextFile(harness: HarnessId): boolean;
+/**
+ * The context files this package owns by MARKER rather than by name:
+ * `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `HERMES.md`.
+ *
+ * Each is a documented name a repository can already carry, so the name proves
+ * nothing. A generated one carries the line {@link markMaterializerContextFile}
+ * writes, and only that line lets the next materialization replace it.
+ *
+ * opencode's context file is absent because it is a RESERVED name this package
+ * invented, already owned by the name alone.
+ */
+declare const MATERIALIZER_CONTEXT_PATHS: ReadonlySet<string>;
+/**
+ * Mark one generated context file so the NEXT materialization can prove this
+ * package wrote the bytes it is about to replace.
+ *
+ * The marker is an HTML comment on line 1. CommonMark closes an HTML block at
+ * the line holding `-->`, so every instruction below it parses exactly as it
+ * did without the line, and the line itself states no instruction. It is one
+ * more line this package composes into a file it already composes: it goes on
+ * a context file, which carries `prompt.instructions`, and NEVER on a
+ * system-prompt REPLACEMENT, whose bytes are the caller's exact text
+ * (`.gemini/system.md`; `.codex/system-prompt.md` is a reserved name this
+ * package invented and needs no marker to be owned).
+ *
+ * It carries the digest of the generated body below it, which the subagent
+ * marker does not need. `CLAUDE.md` is claude-code's own memory file and the
+ * agent appends to it mid-session, so a bare marker would still sit on line 1
+ * of a file the agent has since rewritten. The digest tells which leading bytes
+ * are still this package's own: the next materialization replaces exactly
+ * those and keeps what the agent appended below them
+ * ({@link generatedContextAppendix}). The marker's wording is part of every
+ * marker already written into live workspaces, so it stays as it is.
+ *
+ * A reserved context path — opencode's invented instruction file — is returned
+ * unchanged: its NAME already proves the provenance, and nothing else may mount
+ * there.
+ */
+declare function markMaterializerContextFile(relPath: string, content: string): string;
+/**
+ * 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
+ * cannot reach). Public so consumers composing a profile can (a) render the
+ * exact path the platform will mount a skill at into their prompts instead
+ * of hardcoding `~/.claude/skills/...`, and (b) branch on skill support
+ * ahead of materialization instead of catching the materialize-time throw.
+ */
+declare const HARNESS_SKILL_DIRS: Readonly<Record<HarnessId, string | null>>;
+/**
+ * Resolve the cwd-relative directory `resources.skills` refs materialize
+ * into on `harness`. `null` means the harness cannot receive cwd skills, the
+ * same condition that surfaces as an `unsupported`
+ * "skills" entry (and an {@link assertWorkspacePlanSupported} throw) at
+ * materialize time, exposed here as branchable data.
+ */
+declare function skillDirForHarness(harness: HarnessId): string | null;
+//#endregion
+//#region src/plan-types.d.ts
+/** The executor-owned root that receives a materialized file. */
+type PlanFileRoot = "workspace" | "agent";
+interface PlanFile {
+  relPath: string;
+  content: string;
+  /** Defaults to the run workspace. `agent` is the harness's private agent directory. */
+  root?: PlanFileRoot;
+  /** chmod mode (e.g. 0o755 for hook scripts); default 0o644. */
+  mode?: number;
+  /**
+   * Provenance of this entry. `"generated"` = the materializer synthesized the
+   * content itself (native harness config, merged settings, lowered prompt/MCP/
+   * hooks/subagents). `"user"` = the exact bytes of a profile-declared resource
+   * ref (`resources.files`/`tools`/`agents`/`skills`/`commands`), passed through
+   * verbatim at the path the profile author chose.
+   *
+   * A consumer that needs to reinterpret a SPECIFIC generated file (e.g. parse
+   * `opencode.json` as the synthetic native config) MUST gate on
+   * `source === "generated"` at that relPath — matching by relPath alone cannot
+   * tell a harness-authored config apart from a user resource mount that
+   * happens to share the same conventional path, and treating arbitrary user
+   * content as trusted generated config is a fail-open bug, not a fallback.
+   *
+   * Optional: callers that hand-construct a {@link WorkspacePlan} directly for
+   * {@link applyWorkspacePlan} (tests, ad hoc writes) are not materializer
+   * output and have no provenance to report. `materializeProfile` always sets
+   * 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 whose generated content is wholly this
+   * package's output: a name this package invented, the generated context file
+   * (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `HERMES.md`), or `opencode.json`,
+   * which carries only the registrations generated from the profile. A file
+   * already there is this materializer's own output from an earlier application
+   * into the same workspace, and replacing it is how turn two of a resumed
+   * session — or the first turn of a branched one — gets the current profile
+   * instead of the previous one. Application replaces it only when the existing
+   * bytes prove that provenance — by the name for an invented path, by a marker
+   * line committing to the body digest for a context file, by the content for
+   * `opencode.json`.
+   *
+   * `"shared"` (the default, and every other file) = a path the user or the
+   * harness also owns. `.gemini/system.md` is a documented, user-authorable
+   * name whose content this package cannot tell from its own, and so is a
+   * context file mounted as an explicit profile resource rather than generated.
+   * 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
+   * public plan, its digest, and its receipt retain only these references.
+   */
+  secretSlots?: PlanFileSecretSlot[];
+}
+interface PlanFileSecretSlot {
+  path: Array<string | number>;
+  ref: AgentProfileSecretRef;
+}
+interface WorkspacePlanSecretSegment {
+  kind: "secret";
+  ref: AgentProfileSecretRef;
+  /** Encoding applied after private resolution. */
+  encoding: "raw" | "json-string";
+}
+/** A launch argument whose private leaves are resolved immediately before spawn. */
+interface WorkspacePlanArgumentTemplate {
+  kind: "workspace-plan-argument-template";
+  segments: Array<string | WorkspacePlanSecretSegment>;
+}
+type WorkspacePlanArgument = string | WorkspacePlanArgumentTemplate;
+/** Public bytes stay strings; secret references stay opaque until application. */
+type WorkspacePlanConfigValue = string | AgentProfileSecretRef;
+interface Unsupported {
+  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.
+ */
+declare const EXECUTOR_SYSTEM_PROMPT_BINDINGS: readonly ["opencode.agent-prompt"];
+type ExecutorSystemPromptBinding = (typeof EXECUTOR_SYSTEM_PROMPT_BINDINGS)[number];
+/**
+ * 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.
+ */
+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;
+}
+/** One file applied by a plan, with the executor root kept explicit. */
+interface WorkspacePlanWrittenFile {
+  root: PlanFileRoot;
+  relPath: string;
+}
+/**
+ * The dimensions `materializeProfile`'s `skip` option honors.
+ *
+ * Every other dimension is materialized unconditionally: generated plan files are pushed through
+ * a single site that carries no dimension tag, so there is nothing to gate them on. Naming the
+ * honored set keeps `skip: ["hooks"]` a loud rejection instead of a silent no-op.
+ */
+declare const SKIPPABLE_DIMENSIONS: readonly ["mcp", "extensions"];
+type SkippableDimension = (typeof SKIPPABLE_DIMENSIONS)[number];
+declare function isSkippableDimension(value: string): value is SkippableDimension;
+/**
+ * Launcher controls an executor can declare it OWNS via `materializeProfile`'s
+ * `binds` option.
+ *
+ * Some harness controls live outside any workspace: opencode's exact
+ * system-prompt replacement (`agent.<name>.prompt`) binds to the ONE agent
+ * whoever starts the process selects, which a plan-forwarding executor cannot
+ * guarantee — so the plan refuses the intent (harnessSystemPromptIntents in
+ * @tangle-network/agent-interface answers `replace: false` for opencode).
+ *
+ * The replacement declarations describe the executor shapes that can reach it;
+ * each gets the lowering it can apply. Codex launchers separately declare
+ * `codex.developer-instructions` to consume ordinary instructions as additive
+ * context; undeclared callers retain workspace files:
+ *
+ *   - `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.
+ *
+ * The replacement declarations are mutually exclusive: declaring both is a
+ * caller bug, not a broader capability.
+ */
+declare const BINDABLE_LAUNCH_CONTROLS: readonly ["systemPrompt", "codex.developer-instructions", "opencode.agent-prompt"];
+type BindableLaunchControl = (typeof BINDABLE_LAUNCH_CONTROLS)[number];
+/** The plan a caller writes into the run cwd, then applies to the spawn. */
+interface WorkspacePlan {
+  harness: HarnessId;
+  /** Files to write relative to the run workspace (cwd). */
+  files: PlanFile[];
+  /** Env vars to set on the spawned process (for harnesses needing them). */
+  env: Record<string, WorkspacePlanConfigValue>;
+  /** Extra CLI flags to pass (e.g. claude --mcp-config <path>). */
+  flags: WorkspacePlanArgument[];
+  /**
+   * 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;
+  /**
+   * Text added to the harness context; its own system prompt stays intact.
+   *
+   * Claude Code and Pi bind their additive system-prompt control. Codex binds
+   * ordinary profile instructions to developer_instructions, composed once
+   * with host context; this is not a privileged system-prompt append. Authored
+   * Codex appendSystemPrompt remains unsupported. Never fold this into an exact
+   * system-prompt replacement, which carries the caller's unchanged bytes.
+   */
+  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[];
+  /**
+   * Prerequisites the workspace files CANNOT establish on their own.
+   *
+   * A plan is a set of files, an env map, and flags. Some harness capabilities need more than
+   * that to actually function: pi's MCP support is not built in, it arrives from an extension
+   * that must be installed into the harness's own package directory and permitted to load. No
+   * file written into a run workspace can make either true.
+   *
+   * Writing the config anyway and hoping is the failure this field exists to prevent: the
+   * harness starts, silently has no MCP, and the agent runs without the tools it was configured
+   * with while nothing reports a problem. So the plan states the requirement and the executor —
+   * which knows where its harness is installed and how it spawns — verifies or refuses it.
+   *
+   * Optional because this is an additive field on a published type: a plan built before it
+   * existed, or by a caller that does not construct one, is still a valid plan with no
+   * prerequisites. Every plan this package builds sets it.
+   */
+  requires?: PlanRequirement[];
+}
+/**
+ * One prerequisite a {@link WorkspacePlan} depends on but cannot create.
+ *
+ * Declarative on purpose: this package builds plans and never probes a filesystem, spawns a
+ * process, or reaches the network. The executor holds that context and does the checking.
+ */
+interface PlanRequirement {
+  /** The only kind so far: a harness extension/plugin that must be loaded for a dimension to work. */
+  kind: "harness-extension";
+  /** Dimension that produced the requirement, so a refusal can name what will not work. */
+  dimension: Unsupported["dimension"];
+  /** Package spec in the harness's own vocabulary, e.g. `npm:pi-mcp-adapter`. */
+  id: string;
+  /** Why the plan needs it — goes verbatim into the executor's refusal message. */
+  reason: string;
+  /** The exact command that satisfies it, so a failure is actionable without a doc lookup. */
+  remedy: string;
+}
+/**
+ * Proof of the profile workspace inputs applied before a harness is spawned.
+ * `workspacePlanDigest` covers only the {@link WorkspacePlan}; it is not an
+ * execution-plan digest and does not attest unrelated files in `workspaceDir`.
+ */
+interface WorkspacePlanReceipt {
+  workspacePlanDigest: string;
+  /** Public launch identity only; secret values never enter this receipt. */
+  env: Record<string, WorkspacePlanConfigValue>;
+  /** Public launch identity only; templates retain opaque secret references. */
+  flags: WorkspacePlanArgument[];
+  systemPrompt?: string;
+  appendSystemPrompt?: string;
+  /** The launcher-bound intent, so a receipt says which control owed the work. */
+  systemPromptBinding?: WorkspacePlanSystemPromptBinding;
+  unsupported: Unsupported[];
+  /**
+   * Workspace-root paths, for consumers that mount the workspace only.
+   * Agent-root files are available in `writtenFiles` and are never encoded as
+   * an `agent:` path because that spelling is legal in the workspace root.
+   */
+  written: string[];
+  /** Every applied file, including its executor-owned root. */
+  writtenFiles: WorkspacePlanWrittenFile[];
+}
+/** Private values handed directly to the provider spawn, never to receipts. */
+interface WorkspacePlanSpawnInputs {
+  env: Record<string, string>;
+  flags: string[];
+  systemPrompt?: string;
+  appendSystemPrompt?: string;
+  /** Read it with {@link takeSystemPromptBinding}, which refuses a foreign control. */
+  systemPromptBinding?: WorkspacePlanSystemPromptBinding;
+  /**
+   * Absolute dirs of the profile's declared executable `reference/` tools in
+   * the immutable revision the launch runs from. The provider puts them on
+   * the launch PATH in place of the app's own tool dirs (bindLaunchToolBinDirs),
+   * so a profile names its CLI bare.
+   */
+  toolBinDirs?: string[];
+}
+/** Result of applying a public plan at the private executor boundary. */
+interface WorkspacePlanApplication {
+  receipt: WorkspacePlanReceipt;
+  spawn: WorkspacePlanSpawnInputs;
+  /** Resolved generated files intentionally consumed in memory by the runtime. */
+  runtimeOnlyFiles: Record<string, string>;
+}
+/** The plan was applied, but one or more private staging files remain. */
+declare class WorkspacePlanCleanupError extends AggregateError {
+  readonly receipt: WorkspacePlanReceipt;
+  readonly temporaryPaths: readonly string[];
+  constructor(errors: readonly unknown[], receipt: WorkspacePlanReceipt, temporaryPaths: readonly string[]);
+}
+interface ApplyWorkspacePlanOptions {
+  /** Plan files consumed in memory by the runtime and never persisted to cwd. */
+  runtimeOnlyFiles?: readonly string[];
+  /** Absolute private agent directory required by files whose root is `agent`. */
+  agentDir?: string;
+  /** Own newly written workspace files as the process that will read them. */
+  ownership?: {
+    uid: number;
+    gid: number;
+  };
+  /** Existing workspace paths are either exact idempotent inputs or forbidden. */
+  existingFiles?: "allow-identical" | "reject";
+  /**
+   * `workspacePlanDigest` of a plan a prior call already applied into this
+   * workspace. When it equals this plan's digest, application changes no file
+   * content. It can repair ownership on unchanged materializer-owned files.
+   * A file the agent edited or removed stays exactly as the agent left it.
+   * Env, flags, prompt intents, and the receipt are still produced. A different
+   * digest applies normally, so a changed plan still meets the existing-file
+   * refusal.
+   */
+  appliedPlanDigest?: string;
+  /**
+   * Write every JSON file secret slot as an `{env:NAME}` reference (OpenCode
+   * config substitution) and never its value, so file bytes and every digest
+   * over them stay identical when only a secret's value changes. The value
+   * lands here under NAME for the executor alone: never put it in the launch
+   * environment, argv or any file the native process reads, because that
+   * process hands everything it holds to every tool it runs. A value that
+   * could not be substituted safely is refused.
+   */
+  secretFileSlotReferences?: Record<string, string>;
+}
+//#endregion
+//#region src/candidate-types.d.ts
+interface AgentCandidateWorkspacePlan {
+  sourceProfileDigest: Sha256Digest;
+  harness: HarnessId;
+  files: PlanFile[];
+  env: Record<string, AgentCandidateConfigValue>;
+  flags: AgentCandidateConfigValue[];
+  systemPrompt?: AgentCandidateConfigValue;
+  appendSystemPrompt?: AgentCandidateConfigValue;
+  unsupported: Unsupported[];
+}
+interface AgentCandidateWorkspacePlanReceipt {
+  profileActivation: AgentCandidateProfileActivation;
+  application: AgentCandidateProfileApplication;
+  env: Record<string, AgentCandidateConfigValue>;
+  flags: AgentCandidateConfigValue[];
+  systemPrompt?: AgentCandidateConfigValue;
+  appendSystemPrompt?: AgentCandidateConfigValue;
+  unsupported: Unsupported[];
+}
+interface ApplyAgentCandidateWorkspacePlanOptions {
+  /** Absolute private agent directory required by agent-root plan files. */
+  agentDir?: string;
+}
+interface MaterializeCandidateProfileOptions {
+  /** Exact text fetched from pinned resource refs, keyed by declared SHA-256. */
+  resolvedResources?: ReadonlyMap<Sha256Digest, string>;
+  /**
+   * Launcher controls this caller owns and will bind itself. The declaration
+   * is forwarded to the classic materializer so candidate execution uses the
+   * same lowering as ordinary profile execution.
+   */
+  binds?: readonly BindableLaunchControl[];
+}
+//#endregion
+//#region src/candidate.d.ts
+declare function materializeCandidateProfile(profile: AgentCandidateProfile, harness: HarnessId, opts?: MaterializeCandidateProfileOptions): AgentCandidateWorkspacePlan;
+/**
+ * Apply a candidate plan and return its spawn values together with captured
+ * canonical evidence. No caller needs to re-serialize or reinterpret the plan.
+ */
+declare function applyAgentCandidateWorkspacePlan(plan: AgentCandidateWorkspacePlan, workspaceDir: string, targetWorkspace: AgentCandidateProfileApplication["targetWorkspace"], options?: ApplyAgentCandidateWorkspacePlanOptions): AgentCandidateWorkspacePlanReceipt;
+//#endregion
+//#region src/control-maps.d.ts
+/** Tool IDs reported by the OpenCode binary shipped in the Sandbox image. */
+declare const OPENCODE_NATIVE_TOOL_IDS: readonly ["apply_patch", "bash", "codesearch", "edit", "glob", "grep", "question", "read", "skill", "task", "todowrite", "webfetch", "websearch", "write"];
+/** Resolve portable and legacy profile names to current OpenCode tool IDs. */
+declare function openCodeNativeToolId(name: string): string | undefined;
+//#endregion
+//#region src/harness-prompt.d.ts
+/** Keep controlled Codex launches on declared tools, not account apps or plugins. */
+declare const CODEX_DISABLED_FEATURE_ARGS: readonly string[];
+/**
+ * Whether a run keeps the harness's own system prompt, so that a host's
+ * environment context joins the profile's addition instead of replacing the
+ * harness prompt.
+ *
+ * A profile that declares prompt intent (`prompt.instructions` or
+ * `prompt.appendSystemPrompt`) without `prompt.systemPrompt` asked for the
+ * harness prompt to stay in force: that is what `appendSystemPrompt` means.
+ * A host that replaced it with its own template would delete exactly what the
+ * profile kept. Every Discovery research director ran under the
+ * sandbox's app-builder template this way: claude-code through
+ * `--system-prompt`, opencode through a generated primary agent.
+ */
+declare function keepsHarnessSystemPrompt(profile: AgentProfile | undefined, harness: HarnessId | string | undefined): boolean;
+/** Join prompt additions in order, skipping empty ones. */
+declare function joinSystemPromptAdditions(...additions: Array<string | undefined>): string | undefined;
+/** Native inline context has a bounded argument; long context belongs in resources.files. */
+declare function codexDeveloperInstructionArgs(value: string | undefined, flags?: readonly string[]): string[];
+//#endregion
+//#region src/managed-workspace-types.d.ts
+interface ManagedWorkspaceFileDigest {
+  root: PlanFileRoot;
+  relPath: string;
+  source: PlanFile["source"];
+  ownership: PlanFile["ownership"];
+  size: number;
+  mode: number;
+  /** The host view exposes only visible entries for this pinned turn. */
+  visible: boolean;
+  /** A side copy of this original path, when a user file won the collision. */
+  relocatedFrom?: string;
+  /** Digest of the actual staged bytes, including resolved secret leaves. Private. */
+  sha256: string;
+}
+/** Private executor inventory; never expose hashes of resolved credentials. */
+interface ManagedWorkspaceManifest {
+  workspacePlanDigest: string;
+  /** Hashes the resolved stage inventory and launch inputs, not only public refs. */
+  materializedDigest: string;
+  files: ManagedWorkspaceFileDigest[];
+  /** User-owned path stays in place; profile bytes are staged beside it. */
+  conflicts: Array<{
+    relPath: string;
+    copyRelPath: string;
+    reason: "existing" | "symlink";
+  }>;
+  /** Resolved for the runtime but intentionally absent from the visible tree. */
+  runtimeOnlyFiles: Array<{
+    name: string;
+    size: number;
+    sha256: string;
+  }>;
+  /** Private digest of resolved spawn controls, including secret-bearing env. */
+  spawnDigest: string;
+  /** Exact native spawn controls after absolute revision paths are bound. */
+  launchDigest?: string;
+}
+//#endregion
+//#region src/managed-workspace.d.ts
+interface ConcurrentProfileRevision {
+  directory: string;
+  manifest: ManagedWorkspaceManifest;
+  application: WorkspacePlanApplication;
+}
+declare function ensurePublicConcurrentProfileRoots(base: string): {
+  managedRoot: string;
+  launchRoot: string;
+};
+declare function preparePublicConcurrentProfileRevision(input: {
+  plan: WorkspacePlan;
+  managedRoot: string;
+  launchRoot: string;
+  sharedWorkspaceDir: string;
+  ownerId: string;
+  secretProvider: AgentProfileSecretProvider;
+  options?: Pick<ApplyWorkspacePlanOptions, "ownership" | "runtimeOnlyFiles">;
+}): Promise<ConcurrentProfileRevision>;
+//#endregion
+//#region src/mcp-config-ownership.d.ts
+/**
+ * Harness MCP config files this package generates wholesale from
+ * `profile.mcp`: exactly one `mcpServers` object whose entries carry only
+ * the fields the generators write. Recognizable by that shape alone (no
+ * schema id to key on), so an existing file holding ONLY those registrations
+ * is this package's earlier output and a new plan replaces it — a per-turn
+ * profile changes these bytes routinely (physim's MCP env carries turn
+ * state). Anything else at the path (a user's own keys, extra fields) still
+ * refuses: the name alone proves nothing, same rule as `opencode.json`.
+ */
+/** Whether the existing file at `relPath` is this package's own earlier MCP
+ *  config output (shape rule above). `undefined` content = no regular file. */
+declare function isMaterializerMcpConfig(relPath: string, content: () => string | undefined): boolean;
+//#endregion
+//#region src/mcp-opencode.d.ts
+/** OpenCode-native MCP configuration used by workspace and startup paths. */
+type OpenCodeMcpConfig = Record<string, {
+  type: "remote";
+  url: string;
+  enabled: boolean;
+  headers?: Record<string, AgentProfileConfigValue>; /** Milliseconds; OpenCode bounds this server's connect, tool listing and tool calls by it. */
+  timeout?: number; /** `false` turns off OpenCode's OAuth discovery for this server. */
+  oauth?: false;
+} | {
+  type: "local";
+  command: Array<string | AgentProfileConfigValue>;
+  enabled: boolean;
+  environment?: Record<string, AgentProfileConfigValue>;
+  timeout?: number;
+}>;
+/**
+ * Lower canonical MCP definitions to OpenCode's native startup configuration.
+ * `toolTimeouts` holds the validated `metadata.toolTimeoutMs` of each server
+ * that declared one; without it OpenCode applies the MCP SDK's 60 s default to
+ * every tool call.
+ */
+declare function openCodeMcpConfig(mcp: Record<string, AgentProfileMcpServer>, toolTimeouts?: ReadonlyMap<string, number>): OpenCodeMcpConfig;
+//#endregion
+//#region src/model-id.d.ts
+/**
+ * The one canonicalization of a model id, shared by everything that writes a
+ * model id into an {@link AgentProfile} and everything that later compares one
+ * against it.
+ *
+ * A model id is qualified by prepending provider segments, and the same model
+ * is legitimately spelled at more than one qualification level as it travels:
+ * the caller sends `{ provider: "openai-compat", model: "deepseek/deepseek-v4-flash" }`,
+ * the profile records the qualified `openai-compat/deepseek/deepseek-v4-flash`,
+ * and the CLI is spawned with that qualified form. Two spellings, one model.
+ *
+ * Every writer and every reader must run both sides through here, so a
+ * comparison cannot mistake two spellings of one model for a conflict. Two
+ * independent copies of this rule are exactly how that bug arises.
+ */
+/**
+ * Qualify `modelId` with `provider` — the canonical form of a model id.
+ *
+ * The already-qualified check is prefix-SPECIFIC rather than "already contains
+ * a slash": a router slug legitimately carries an upstream segment of its own
+ * (`deepseek/deepseek-v4-flash`, `zai/glm-4.7`), so a generic slash test would
+ * leave those unqualified, while an unconditional prefix would double-qualify
+ * an id that has already been through here.
+ *
+ * Idempotent by construction:
+ * `qualifyModelId(p, qualifyModelId(p, m)) === qualifyModelId(p, m)`.
+ */
+declare function qualifyModelId<T extends string | undefined>(provider: string | undefined, modelId: T): T;
+/**
+ * Remove one exact `provider/` qualification from `modelId`.
+ *
+ * This is the inverse operation for a model id that was qualified by this
+ * provider. It removes only the known outer prefix and preserves upstream
+ * segments such as `zai/glm-4.7`.
+ *
+ * The helper removes one outer qualification per call. It leaves missing
+ * providers and model ids unchanged.
+ */
+declare function unqualifyModelId(provider: string | undefined, modelId: string): string;
+declare function unqualifyModelId(provider: string | undefined, modelId: undefined): undefined;
+declare function unqualifyModelId(provider: string | undefined, modelId: string | undefined): string | undefined;
+/**
+ * Do two model ids name the same model?
+ *
+ * Both operands are qualified by `provider` before comparison, so the
+ * qualification level a caller happened to use is not a difference. Two
+ * different model names are still different — this narrows a comparison to the
+ * model's identity, it does not make the comparison permissive.
+ *
+ * `provider` is optional because a profile may carry a `model.default` that was
+ * qualified by a writer which did not also record `model.provider`. With no
+ * provider to qualify by, a bare id and its single-segment-qualified spelling
+ * are still the same model, which is the only tolerance the undeclared case gets.
+ */
+declare function modelIdsMatch(a: string | undefined, b: string | undefined, provider?: string): boolean;
+//#endregion
+//#region src/pi-models-config.d.ts
+interface PiModelsConfigInput {
+  /** Provider key in models.json and the matching `--provider` value. */
+  providerName: string;
+  /** Model id in models.json and the matching `--model` value. */
+  modelId: string;
+  /** Provider endpoint. OpenAI-compatible endpoints include `/v1`. */
+  baseUrl: string;
+  /** Literal in-box credential or an environment reference. */
+  apiKey: string;
+  /** Pi wire protocol. */
+  api?: "anthropic-messages" | "google-generative-ai" | "openai-completions" | "openai-responses";
+  contextWindow?: number;
+  maxTokens?: number;
+  reasoning?: boolean;
+  /** OpenAI-compatible completions may reject the optional store field. */
+  supportsStore?: boolean;
+}
+interface PiModelsConfigFile {
+  path: string;
+  content: string;
+  mode: number;
+}
+declare const PI_MODELS_CONFIG_PATH = ".pi/agent/models.json";
+interface PiRuntimePaths {
+  agentDir: string;
+  sessionDir: string;
+}
+/** Resolve Pi's private roots from the one runtime HOME supplied to Pi. */
+declare function resolvePiRuntimePaths(runtimeHome: string): PiRuntimePaths;
+declare function buildPiModelsConfig(input: PiModelsConfigInput): Record<string, unknown>;
+/** Build the owner-only Pi file used by headless and interactive processes. */
+declare function buildPiModelsConfigFile(input: PiModelsConfigInput): PiModelsConfigFile;
+//#endregion
+//#region src/plan-application.d.ts
+declare function applyWorkspacePlan(plan: WorkspacePlan, workspaceDir: string, options?: ApplyWorkspacePlanOptions): WorkspacePlanReceipt;
+/**
+ * Resolve opaque profile references through an executor-owned provider, then
+ * apply the resulting private native files and launch inputs. Resolution
+ * completes before any workspace write, and resolved values never enter the
+ * public plan, digest, receipt, logs, or error messages.
+ */
+declare function applyWorkspacePlanWithSecretProvider(plan: WorkspacePlan, workspaceDir: string, secretProvider: AgentProfileSecretProvider, options?: ApplyWorkspacePlanOptions): Promise<WorkspacePlanApplication>;
+//#endregion
+//#region src/plan-digest.d.ts
+declare function hashWorkspacePlan(plan: WorkspacePlan): string;
+/** Build the exact digest-free identity document required by agent-interface. */
+declare function agentCandidateProfilePlanMaterial(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanMaterial;
+/**
+ * Return the RFC 8785 UTF-8 bytes and SHA-256 identity of a candidate profile
+ * plan. The returned bytes are the exact bytes embedded in receipt evidence.
+ */
+declare function canonicalizeAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): {
+  material: AgentCandidateProfilePlanMaterial;
+  bytes: Uint8Array;
+  digest: Sha256Digest;
+};
+/** Capture portable evidence of the exact canonical profile-plan bytes. */
+declare function captureAgentCandidateProfilePlan(plan: AgentCandidateWorkspacePlan): AgentCandidateProfilePlanEvidence;
+//#endregion
+//#region src/plan-prompt.d.ts
+/**
+ * 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.
+ */
+declare function takeSystemPromptBinding(spawn: Pick<WorkspacePlanSpawnInputs, "systemPromptBinding">, control: ExecutorSystemPromptBinding): string | undefined;
+//#endregion
+//#region src/plan-support.d.ts
+/** Fail when a profile asks for controls the chosen harness cannot execute. */
+declare function assertWorkspacePlanSupported(plan: Pick<WorkspacePlan, "unsupported">): void;
+/**
+ * Enforce supportability under the profile's failOnError policy.
+ * Strict mode throws; best-effort mode returns visible warnings.
+ */
+declare function enforceWorkspacePlanSupport(plan: Pick<WorkspacePlan, "unsupported">, failOnError: boolean | undefined): string[];
+//#endregion
+//#region src/prime-profile.d.ts
+interface PrimeProfileSkill {
+  name: string;
+  content: string;
+}
+interface PrimeProfileSubagent {
+  name: string;
+  description?: string;
+  prompt?: string;
+  metadata?: Record<string, unknown>;
+}
+/** Validated, materialization-ready view of the profile controls prime applies. */
+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. */
+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.
+ */
+declare function primeProfileNeedsAgentDir(controls: PrimeProfileControls): boolean;
+/**
+ * Validate and extract the profile controls the prime agent-dir lowering
+ * 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.
+ */
+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.
+ */
+declare function assertPrimeModelAgreement(profile: AgentProfile | undefined, selected: {
+  provider?: string;
+  model: string;
+}): void;
+/** Deterministic harness-state entry id for a profile subagent name. */
+declare function primeSubagentEntryId(name: string): string;
+//#endregion
+//#region src/prime-agent-dir.d.ts
+declare function writePrimeAgentFile(path: string, data: string, mode?: number): void;
+/**
+ * File access on a prime agent dir. The default reads and writes the local
+ * filesystem as the calling process. An executor whose agent dir belongs to
+ * another user (a root sidecar that demotes prime-agent) passes reads it took
+ * as that user and replays the writes as that user, so it never touches the
+ * agent's files with its own rights.
+ */
+interface PrimeAgentDirIo {
+  /** The file's text, or undefined when it does not exist. */
+  read(path: string): string | undefined;
+  /** Replace the whole file: atomic and owner-only. */
+  write(path: string, data: string): void;
+}
+/** The fork's continual-harness store, the only agent-dir file a materialization reads. */
+declare function primeHarnessStatePath(agentDir: string): string;
+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;
+  /** Agent-dir file access; the local filesystem when omitted. */
+  io?: PrimeAgentDirIo;
+}
+/**
+ * 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.
+ */
+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.
+ */
+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"`) — and every top-level
+ * key this lowering does not manage — are preserved untouched.
+ *
+ * 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.
+ */
+declare function seedPrimeProfileSubagents(agentDir: string, subagents: PrimeProfileSubagent[], warn?: (msg: string, meta?: Record<string, unknown>) => void, io?: PrimeAgentDirIo): void;
+//#endregion
+//#region src/prime-fork.d.ts
+/**
+ * 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 was read from PrimeIntellect-ai/prime-agent 0.7.0
+ * (be9e2fa0); a fork bump re-reads them against the new clone.
+ */
+/**
+ * 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.
+ */
+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). */
+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. */
+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).
+ */
+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.
+ */
+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").
+ */
+declare const PRIME_KERNEL_DEAD_MARKERS: readonly string[];
+/** The first kernel-death marker present in `text`, or undefined. */
+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.
+ */
+declare const PRIME_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+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.
+ */
+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.
+ */
+declare const PRIME_MCP_UNSUPPORTED_REASON: string;
+/** Which half of a profile refusal this is: a fork limit, or a bad declaration. */
+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.
+ */
+declare class PrimeProfileError extends Error {
+  readonly kind: PrimeProfileErrorKind;
+  readonly control: string;
+  readonly reason: string;
+  constructor(kind: PrimeProfileErrorKind, control: string, reason: string);
+}
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare function primeApiKeyEnvNames(modelsConfig: Record<string, unknown>): string[];
+//#endregion
+//#region src/profile-bundle-key.d.ts
+declare const PROFILE_BUNDLE_SCHEMA = "agent-profile-bundle/v1";
+declare const PROFILE_BUNDLE_MAX_FILES = 512;
+declare const PROFILE_BUNDLE_MAX_BYTES: number;
+declare const PROFILE_BUNDLE_MAX_FILE_BYTES: number;
+declare const PROFILE_BUNDLE_DEFAULT_MAX_BYTES: number;
+interface ProfileBundleFileEntry {
+  /** Logical workspace-relative mount path, exactly as declared on the profile. */
+  mountPath: string;
+  /** SHA-256 of the content bytes as lowercase hex, WITHOUT the `sha256:` prefix. */
+  sha256: string;
+  /** Full file mode (0o644 default, 0o755 for executable mounts). */
+  mode: number;
+}
+interface ProfileBundleManifest {
+  schema: string;
+  /** Raw bundle key (e.g. `sha256:<hex>`); also recoverable from the filename. */
+  bundle: string;
+  createdAt: string;
+  sizeBytes: number;
+  files: Array<ProfileBundleFileEntry & {
+    target: string;
+  }>;
+}
+interface ProfileBundleClaim {
+  bundle: string;
+  files: Array<{
+    mountPath: string;
+    sha256: string;
+  }>;
+}
+type ProfileBundleClaimResult = {
+  status: "hit";
+  linked: string[];
+} | {
+  status: "miss";
+  missing: string[];
+};
+interface ProfileBundleCache {
+  root: string;
+  maxBytes: number;
+  admit(manifest: ProfileBundleManifest, readObject: (sha256: string) => Promise<Uint8Array> | Uint8Array): Promise<void>;
+  evict(): Promise<void>;
+  sweep(): Promise<void>;
+}
+/**
+ * Derive the canonical bundle file entry for one inline mount. The sha256 is
+ * computed over the exact inline content bytes and the mode mirrors the SDK's
+ * `profileFileMode`/`isExecutableProfileFile`: `mount.executable` wins when
+ * present, otherwise a path under a `bin/` or `sbin/` directory is executable.
+ * A mount whose resource is not inline is a caller bug and throws, matching
+ * the fail-closed discipline of {@link resolveInlineRef}.
+ */
+declare function profileBundleFileEntry(mount: AgentProfileFileMount): ProfileBundleFileEntry;
+/**
+ * The canonical file table: one entry per mount, sorted by (mountPath, sha256)
+ * so any array order of the same mounts produces the same table.
+ */
+declare function profileBundleFileTable(mounts: readonly AgentProfileFileMount[]): ProfileBundleFileEntry[];
+/**
+ * The content-addressed bundle key. The digest covers EXACTLY the schema
+ * version and, per file, the logical mount path, the sha256 of the content
+ * bytes, and the full file mode — the same image-content-hash discipline as
+ * scripts/ci/image-content-hash.mjs: hash exactly the inputs that determine
+ * the cached bytes (and their placement semantics), nothing more. Any profile
+ * change — content, path, or mode — produces a new key; anything else
+ * (mount order, transport-only target paths, timestamps) does not.
+ */
+declare function profileFileBundleKey(mounts: readonly AgentProfileFileMount[]): string;
+//#endregion
+//#region src/profile-bundle-lru.d.ts
+/**
+ * Bundle keys come from `canonicalCandidateDigest` as `sha256:<hex>`; the `:`
+ * is encoded so the key is a safe single path segment on any host filesystem.
+ * The raw key is always recoverable from the manifest's `bundle` field.
+ */
+declare function profileBundleManifestPath(root: string, bundle: string): string;
+/** Sweep only while holding the per-root lock; active admissions own incoming/. */
+declare function sweepProfileBundleCache(root: string): Promise<void>;
+/**
+ * Evict least-recently-used objects until total object bytes are within
+ * `maxBytes`. Unreferenced objects go first (they reclaim space with no
+ * bundle impact); if the cap still does not hold, referenced objects are
+ * evicted oldest-first, which makes their bundles partial — claims then miss
+ * and re-deliver, so eviction can never serve wrong bytes. Bundle manifests
+ * referencing no existing objects are removed. Mid-admit `incoming/` dirs are
+ * never touched.
+ */
+declare function evictProfileBundles(root: string, maxBytes: number): Promise<void>;
+//#endregion
+//#region src/profile-bundle-cache.d.ts
+/**
+ * Admit a just-delivered bundle to the host cache, all-or-nothing. Every
+ * object's bytes are verified against its content hash BEFORE anything is
+ * renamed into place; a mismatch throws with nothing published. Objects
+ * already present are re-verified against the incoming bytes, then the temp
+ * copy is dropped — the existing object was verified when it was admitted.
+ * The manifest is written LAST as the commit point, followed by lru update
+ * and eviction down to the default cap.
+ */
+declare function admitProfileBundle(root: string, manifest: ProfileBundleManifest, readObject: (sha256: string) => Promise<Uint8Array> | Uint8Array): Promise<void>;
+/**
+ * Claim a bundle from a (possibly read-only mounted) cache. Verify-on-read:
+ * every object's bytes are re-hashed and compared to BOTH the manifest entry
+ * and the claim's expected sha256 before `linkFile` is called — a read-only
+ * mount must never serve unverified bytes. `linkFile` returning false sends
+ * the file to `missing` (the caller delivers it normally). Status is "hit"
+ * only when nothing is missing; a partial bundle is NEVER a hit. The only
+ * write is a best-effort lru touch, wrapped so EROFS on a read-only mount is
+ * harmless.
+ */
+declare function claimProfileBundle(root: string, claim: ProfileBundleClaim, linkFile: (objectPath: string, entry: {
+  mountPath: string;
+  target: string;
+  sha256: string;
+  mode: number;
+}) => Promise<boolean>): Promise<ProfileBundleClaimResult>;
+/**
+ * Open a host-side cache handle over `root`, creating the layout and sweeping
+ * stale `incoming/` residue synchronously when the root is idle. A busy root
+ * leaves cleanup to its serialized admissions and sweeps.
+ */
+declare function openProfileBundleCache(root: string, options?: {
+  maxBytes?: number;
+}): ProfileBundleCache;
+//#endregion
+//#region src/profile-materializer.d.ts
+declare const UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER: AgentProfileSecretProvider;
+/**
+ * Why a profile's tool and permission controls cannot reach one native policy
+ * on this harness, or undefined when they can.
+ *
+ * Admission boundaries (profile save, Sandbox create) call this so a
+ * contradictory control set is refused when it is submitted, not when a
+ * user's turn materializes it. Controls a harness cannot enforce are not
+ * contradictions: `resources.failOnError` decides those per turn.
+ */
+declare function executionControlConflict(profile: Pick<AgentProfile, "tools" | "permissions" | "mcp">, harness: HarnessId): string | undefined;
+/**
+ * Build a pure workspace plan for one canonical harness.
+ * The caller applies files, environment, and flags at its process boundary.
+ */
+declare function materializeProfile(inputProfile: AgentProfile, harness: HarnessId, opts?: {
+  skip?: SkippableDimension[];
+  binds?: readonly BindableLaunchControl[];
+  instructionsRoot?: PlanFileRoot;
+  runtimeAttachments?: AgentRuntimeAttachments;
+}): WorkspacePlan;
+//#endregion
+//#region src/resource-resolution.d.ts
+interface ResolveAgentProfileResourcesOptions {
+  /** Repository used when a GitHub resource omits its own `repository`. */
+  repository?: string;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+}
+/**
+ * Resolve every GitHub resource to exact inline bytes before materialization.
+ * The profile's default harness does not affect resource resolution.
+ */
+declare function resolveAgentProfileResources(inputProfile: AgentProfile, options?: ResolveAgentProfileResourcesOptions): Promise<AgentProfile>;
+/** Normalize any skill markdown (VB frontmatter `skill:`/`description:`, or raw) into a
+ *  harness SKILL.md with `name:`/`description:` frontmatter the harnesses require. */
+declare function normalizeSkillMd(name: string, raw: string): string;
+//#endregion
+//#region src/secret-concurrent-revision.d.ts
+/**
+ * Publish a resolved revision for exactly one native subprocess UID. The
+ * executor-owned naming key hides low-entropy credential guesses from paths;
+ * the resolved digest and manifest never leave this server-side result.
+ */
+declare function prepareSecretConcurrentProfileRevision(input: {
+  plan: WorkspacePlan; /** Trusted executor transport only; never read from the mutable native HOME. */
+  providerConfig?: Record<string, unknown>;
+  managedRoot: string;
+  launchRoot: string;
+  sharedWorkspaceDir: string;
+  ownerId: string;
+  subprocessUid: number;
+  namingKey: Uint8Array;
+  secretProvider: AgentProfileSecretProvider;
+  options?: Pick<ApplyWorkspacePlanOptions, "runtimeOnlyFiles">;
+}): Promise<ConcurrentProfileRevision & {
+  /**
+   * The value behind each `{env:NAME}` reference in the revision's config,
+   * for the executor alone: the launch never receives them. An executor
+   * that serves a referencing MCP server through its own loopback proxy
+   * resolves the server's headers here.
+   */
+  secretReferences: Readonly<Record<string, string>>;
+}>;
+//#endregion
+//#region src/secret-session-view.d.ts
+/** Stable native cwd binds workspace, session and UID across turn revisions. */
+declare function secretSessionViewWorkspace(input: {
+  launchRoot: string;
+  sharedWorkspaceDir: string;
+  sessionId: string;
+  subprocessUid: number;
+}): string;
+/** Bind published read-only resources at literal paths; generated config stays outside cwd.
+ * Callers serialize turns and bind before spawning, never while a native process reads it. */
+declare function bindSecretSessionView(input: {
+  launchRoot: string;
+  viewWorkspaceDir: string;
+  revisionWorkspaceDir: string;
+  subprocessUid: number;
+}): void;
+//#endregion
+//#region src/tool-bin-path.d.ts
+/** The colon-separated, absolute CLI bin dirs a sandbox app mounts for its tools. */
+declare const SANDBOX_TOOL_BIN_DIRS_ENV = "SANDBOX_TOOL_BIN_DIRS";
+/**
+ * The tool bin dirs a `SANDBOX_TOOL_BIN_DIRS` value names, or `[]` when it is
+ * unset or blank.
+ *
+ * Fail loud, never silently degrade: a malformed value (a relative segment,
+ * or an empty segment from a stray/leading/trailing colon) throws rather than
+ * silently dropping a tool dir from PATH or admitting a relative path that
+ * resolves against whatever the process cwd happens to be.
+ */
+declare function parseSandboxToolBinDirs(value: string | undefined): string[];
+/**
+ * A launch environment whose tool bin dirs are `toolBinDirs`, at the TAIL of
+ * PATH after every Nix, npm, image and system entry, so a tool never shadows
+ * a platform-owned binary of the same name.
+ *
+ * They replace `appToolBinDirs` (by default the dirs the environment's own
+ * `SANDBOX_TOOL_BIN_DIRS` names) wherever those sit in PATH, so an app's older
+ * copy of the same tool cannot win by PATH order. Relative PATH entries are
+ * dropped too: they resolve against whatever cwd the turn moves to.
+ */
+declare function bindLaunchToolBinDirs(env: Readonly<Record<string, string | undefined>>, toolBinDirs: readonly string[], appToolBinDirs?: readonly string[]): Record<string, string | undefined>;
+//#endregion
+export { type AgentCandidateWorkspacePlan, type AgentCandidateWorkspacePlanReceipt, type ApplyAgentCandidateWorkspacePlanOptions, type ApplyWorkspacePlanOptions, BINDABLE_LAUNCH_CONTROLS, type BindableLaunchControl, CODEX_DISABLED_FEATURE_ARGS, type ConcurrentProfileRevision, EXECUTOR_SYSTEM_PROMPT_BINDINGS, type ExecutorSystemPromptBinding, HARNESS_SKILL_DIRS, type HarnessId, MATERIALIZER_CONTEXT_PATHS, MATERIALIZER_HARNESSES, type ManagedWorkspaceFileDigest, type ManagedWorkspaceManifest, type MaterializeCandidateProfileOptions, OPENCODE_NATIVE_TOOL_IDS, type OpenCodeMcpConfig, PI_MODELS_CONFIG_PATH, PRIME_AGENT_DIR_ENV_VAR, PRIME_AGENT_DIR_ENV_VARS, PRIME_HARNESS_STATE_ENV_DENYLIST, PRIME_KERNEL_DEAD_MARKERS, PRIME_KERNEL_ENV_PASSTHROUGH, PRIME_MCP_UNSUPPORTED_REASON, PRIME_THINKING_LEVELS, PROFILE_BUNDLE_DEFAULT_MAX_BYTES, PROFILE_BUNDLE_MAX_BYTES, PROFILE_BUNDLE_MAX_FILES, PROFILE_BUNDLE_MAX_FILE_BYTES, PROFILE_BUNDLE_SCHEMA, type PiModelsConfigFile, type PiModelsConfigInput, type PiRuntimePaths, type PlanFile, type PlanFileRoot, type PlanFileSecretSlot, type PlanRequirement, PrimeHarnessStateError, type PrimeMaterializeOptions, type PrimeProfileControls, PrimeProfileError, type PrimeProfileErrorKind, type PrimeProfileSkill, type PrimeProfileSubagent, type PrimeThinkingLevel, ProfileBundleCache, ProfileBundleClaim, ProfileBundleClaimResult, ProfileBundleFileEntry, ProfileBundleManifest, type ResolveAgentProfileResourcesOptions, SANDBOX_TOOL_BIN_DIRS_ENV, SKIPPABLE_DIMENSIONS, type SkippableDimension, UNAVAILABLE_AGENT_PROFILE_SECRET_PROVIDER, type Unsupported, type WorkspacePlan, type WorkspacePlanApplication, type WorkspacePlanArgument, type WorkspacePlanArgumentTemplate, WorkspacePlanCleanupError, type WorkspacePlanConfigValue, type WorkspacePlanReceipt, type WorkspacePlanSecretSegment, type WorkspacePlanSpawnInputs, type WorkspacePlanSystemPromptBinding, type WorkspacePlanWrittenFile, admitProfileBundle, agentCandidateProfilePlanMaterial, applyAgentCandidateWorkspacePlan, applyWorkspacePlan, applyWorkspacePlanWithSecretProvider, assertPrimeModelAgreement, assertWorkspacePlanSupported, bindLaunchToolBinDirs, bindSecretSessionView, buildPiModelsConfig, buildPiModelsConfigFile, canonicalizeAgentCandidateProfilePlan, captureAgentCandidateProfilePlan, claimProfileBundle, codexDeveloperInstructionArgs, enforceWorkspacePlanSupport, ensurePublicConcurrentProfileRoots, evictProfileBundles, executionControlConflict, harnessAutoLoadsAgentContextFile, hasPrimeProfileMaterial, hashWorkspacePlan, isMaterializerHarness, isMaterializerMcpConfig, isSkippableDimension, joinSystemPromptAdditions, keepsHarnessSystemPrompt, markMaterializerContextFile, matchPrimeKernelDeadMarker, materializeCandidateProfile, materializePrimeProfileControls, materializeProfile, modelIdsMatch, normalizeSkillMd, openCodeMcpConfig, openCodeNativeToolId, openProfileBundleCache, parsePrimeModelsJson, parseSandboxToolBinDirs, preparePublicConcurrentProfileRevision, prepareSecretConcurrentProfileRevision, primeAgentDirEnv, primeApiKeyEnvNames, primeHarnessStatePath, primeProfileNeedsAgentDir, primeSubagentEntryId, primeThinkingLevel, profileBundleFileEntry, profileBundleFileTable, profileBundleManifestPath, profileFileBundleKey, prunePrimeProfileMaterial, qualifyModelId, readPrimeProfileControls, resolveAgentProfileResources, resolvePiRuntimePaths, secretSessionViewWorkspace, seedPrimeProfileSubagents, skillDirForHarness, stripPrimeJsonComments, sweepProfileBundleCache, takeSystemPromptBinding, unqualifyModelId, writePrimeAgentFile };