@sema-agent/core 7.51.2 → 7.53.0

package/dist/orchestration/goal.js

@@ -100,9 +100,10 @@ export async function runGoal(runner, spec) {
             verificationKind,
             accepted: false,
             cumulativeTokens,
-            checkpointToken: over?.checkpointToken,
+            checkpointToken: over?.paused?.token,
             errorCode: over?.errorCode,
             ...(status === "budget" && over?.budgetCause !== undefined ? { budgetCause: over.budgetCause } : {}),
+            ...(status === "suspended" && over?.paused !== undefined ? { suspendGate: over.paused.gate } : {}),
         };
         if (verificationKind === "mechanical" && status !== "suspended" && status !== "needs_review") {
             runner.emitTaskOutcome?.({
@@ -145,7 +146,7 @@ export async function runGoal(runner, spec) {
             spentCostMicroUsd += (result.stats.costMicroUsd ?? 0) + (result.stats.nested?.costMicroUsd ?? 0);
             spentTurns += (result.stats.turns ?? 0) + (result.stats.nested?.turns ?? 0);
             if (isDurablePause(result.terminal)) {
-                return mk(pauseFamily(result.terminal), iteration, { result, checkpointToken: result.terminal.token });
+                return mk(pauseFamily(result.terminal), iteration, { result, paused: result.terminal });
             }
             const midStop = classifyStop();
             if (midStop)

package/dist/orchestration/run-spec.d.ts

@@ -8,10 +8,8 @@
  *     (green→`spec.not_red`、error→`spec.oracle_error`,均 fail-loud);捕获 baseline 计数。
  *  2. frozen deny policy 经 {@link combinePolicies} 合入部署基线(deny 短路不可被顶);绝不裸赋顶掉
  *     `taskSpec.toolPolicy`(TRAP #1)。
- *  3. Hooks 多路复用:runSpec 的 stop gate 先跑(guard-restore → oracle 判)——red ⇒ block 短路(失败
- *     尾部经 `delimitUntrusted` 围栏后置入:oracle 输出是模型可影响面);green ⇒ **链式调用**用户 stop
- *     (不吞其否决权);error ⇒ block 一次并注明 oracle 基础设施故障,**连续 2 次 error 放弃把关**走终态
- *     判定(防 oracle 自坏死循环)。其它 hook 槽原样透传。
+ *  3. stop gate = 任务座位上的一条注册(在调用方注册之前):red ⇒ block(失败尾部经 `delimitUntrusted` 围栏);green ⇒
+ *     `next(e)` 交下游;error ⇒ block 一次,**连续 2 次 error 放弃把关**走终态判定。
  *  4. 收口:终态亲跑 oracle = 最终判定;`emitTaskOutcome`(mechanical):`oracleHadRedRun` = 任一
  *     「真跑过且判 red」的观察(preflight ∨ stop-gate ∨ 终态;error 永不置位)。durable pause
  *     (suspended/needs_review)非终态,不发射(同 goal.ts 先例:无半事实、resume 不重复计数)。
@@ -34,8 +32,8 @@ import { type OracleBaseline, type OracleGateResult, type OracleVerdict, type Sp
 export interface RunSpecOptions {
     /** Workcopy root — the containment root for frozenPaths, oracle cwd, and `spec.path` resolution. */
     rootDir: string;
-    /** Per-run base spec (model/tools/toolPolicy/hooks/limits/…). `objective` is owned by runSpec (the
-     *  spec framing); `toolPolicy` and `hooks` are COMPOSED with runSpec's, never replaced. */
+    /** Per-run base spec (model/tools/toolPolicy/mods/limits/…). `objective` is owned by runSpec (the
+     *  spec framing); `toolPolicy` and `mods` are COMPOSED with runSpec's, never replaced. */
     taskSpec: Omit<TaskSpec, "objective">;
     /** Receives the oracle gates' once-per-process `config.secret_env_scrubbed` notice (`runOracle`'s `onNotice`);
      *  absent ⇒ the console line. */

package/dist/orchestration/run-spec.js

@@ -9,6 +9,8 @@ import { writeTargetPath } from "../tools/fs/safety.js";
 import { callTargetViewsOf } from "../core/effective-path-target.js";
 import { captureBaseline, resolveFrozenPaths, restoreFrozenPaths, runOracle, snapshotFrozenPaths, specError, } from "../core/spec-contract.js";
 import { isProtectedWrite } from "../core/tool-registry.js";
+const RUN_SPEC_ORACLE_GATE = "run-spec-oracle-gate";
+const RUN_SPEC_ORACLE_GATE_BUDGET_MS = 600_000;
 const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
 const pathKey = (p) => {
     let n = p.replace(/\\/g, "/");
@@ -100,81 +102,55 @@ export async function runSpec(runner, contract, opts) {
     const frozenPolicy = frozenDenyPolicy(rootDir, frozenResolved);
     const policies = [deployBaseline?.toolPolicy, opts.taskSpec.toolPolicy, frozenPolicy].filter((p) => p !== undefined);
     const toolPolicy = policies.length === 1 ? policies[0] : combinePolicies(...policies);
-    const userHooks = opts.taskSpec.hooks && deployBaseline?.hooks
-        ? {
-            preToolUse: (opts.taskSpec.hooks.preToolUse ?? deployBaseline.hooks.preToolUse)?.bind(opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
-            ...((opts.taskSpec.hooks.preToolUse ? opts.taskSpec.hooks : deployBaseline.hooks).preToolUseObservational === true
-                ? { preToolUseObservational: true }
-                : {}),
-            postToolUse: (opts.taskSpec.hooks.postToolUse ?? deployBaseline.hooks.postToolUse)?.bind(opts.taskSpec.hooks.postToolUse ? opts.taskSpec.hooks : deployBaseline.hooks),
-            userPromptSubmit: (opts.taskSpec.hooks.userPromptSubmit ?? deployBaseline.hooks.userPromptSubmit)?.bind(opts.taskSpec.hooks.userPromptSubmit ? opts.taskSpec.hooks : deployBaseline.hooks),
-            stop: (opts.taskSpec.hooks.stop ?? deployBaseline.hooks.stop)?.bind(opts.taskSpec.hooks.stop ? opts.taskSpec.hooks : deployBaseline.hooks),
-            postToolUseFailure: (opts.taskSpec.hooks.postToolUseFailure ?? deployBaseline.hooks.postToolUseFailure)?.bind(opts.taskSpec.hooks.postToolUseFailure ? opts.taskSpec.hooks : deployBaseline.hooks),
-            postToolBatch: (opts.taskSpec.hooks.postToolBatch ?? deployBaseline.hooks.postToolBatch)?.bind(opts.taskSpec.hooks.postToolBatch ? opts.taskSpec.hooks : deployBaseline.hooks),
-            preCompact: (opts.taskSpec.hooks.preCompact ?? deployBaseline.hooks.preCompact)?.bind(opts.taskSpec.hooks.preCompact ? opts.taskSpec.hooks : deployBaseline.hooks),
-            postCompact: (opts.taskSpec.hooks.postCompact ?? deployBaseline.hooks.postCompact)?.bind(opts.taskSpec.hooks.postCompact ? opts.taskSpec.hooks : deployBaseline.hooks),
-            stopFailure: (opts.taskSpec.hooks.stopFailure ?? deployBaseline.hooks.stopFailure)?.bind(opts.taskSpec.hooks.stopFailure ? opts.taskSpec.hooks : deployBaseline.hooks),
-            permissionDenied: (opts.taskSpec.hooks.permissionDenied ?? deployBaseline.hooks.permissionDenied)?.bind(opts.taskSpec.hooks.permissionDenied ? opts.taskSpec.hooks : deployBaseline.hooks),
-            ...((opts.taskSpec.hooks.timeoutMs ?? deployBaseline.hooks.timeoutMs) !== undefined
-                ? { timeoutMs: opts.taskSpec.hooks.timeoutMs ?? deployBaseline.hooks.timeoutMs }
-                : {}),
-        }
-        : (opts.taskSpec.hooks ?? deployBaseline?.hooks);
     let guardRestores = 0;
     let consecutiveOracleErrors = 0;
     let gateAbandoned = false;
-    const hooks = {
-        ...(userHooks?.preToolUse && { preToolUse: userHooks.preToolUse.bind(userHooks) }),
-        ...(userHooks?.preToolUse && userHooks.preToolUseObservational === true ? { preToolUseObservational: true } : {}),
-        ...(userHooks?.postToolUse && { postToolUse: userHooks.postToolUse.bind(userHooks) }),
-        ...(userHooks?.userPromptSubmit && { userPromptSubmit: userHooks.userPromptSubmit.bind(userHooks) }),
-        ...(userHooks?.postToolUseFailure && { postToolUseFailure: userHooks.postToolUseFailure.bind(userHooks) }),
-        ...(userHooks?.postToolBatch && { postToolBatch: userHooks.postToolBatch.bind(userHooks) }),
-        ...(userHooks?.preCompact && { preCompact: userHooks.preCompact.bind(userHooks) }),
-        ...(userHooks?.postCompact && { postCompact: userHooks.postCompact.bind(userHooks) }),
-        ...(userHooks?.stopFailure && { stopFailure: userHooks.stopFailure.bind(userHooks) }),
-        ...(userHooks?.permissionDenied && { permissionDenied: userHooks.permissionDenied.bind(userHooks) }),
-        ...(userHooks?.timeoutMs !== undefined ? { timeoutMs: userHooks.timeoutMs } : {}),
-        async stop(ctx) {
-            guardRestores += restoreFrozenPaths(snapshot, rootDir);
-            if (!gateAbandoned) {
-                const gateSignal = ctx.signal !== undefined && opts.taskSpec.signal !== undefined ? AbortSignal.any([ctx.signal, opts.taskSpec.signal]) : (ctx.signal ?? opts.taskSpec.signal);
-                const report = await runOracle(contract.oracle, rootDir, { baseline, ...(gateSignal !== undefined ? { signal: gateSignal } : {}), ...noticeSeat });
-                if (ctx.signal?.aborted === true)
-                    return undefined;
-                oracleRuns++;
-                if (report.verdict === "red") {
-                    oracleHadRedRun = true;
-                    oracleRedRuns++;
-                    stopGateBlocks++;
-                    consecutiveOracleErrors = 0;
-                    return { block: redFeedback(report.gates) };
-                }
-                if (report.verdict === "error") {
-                    consecutiveOracleErrors++;
-                    if (consecutiveOracleErrors < 2) {
-                        const broken = report.gates.filter((g) => g.verdict === "error");
+    const oracleGate = {
+        name: RUN_SPEC_ORACLE_GATE,
+        uses: { events: ["classic.Stop"], calls: [] },
+        budgetMs: RUN_SPEC_ORACLE_GATE_BUDGET_MS,
+        register(on) {
+            on("classic.Stop", async (_$, e, next) => {
+                guardRestores += restoreFrozenPaths(snapshot, rootDir);
+                if (!gateAbandoned) {
+                    const gateSignal = opts.taskSpec.signal !== undefined ? AbortSignal.any([next.signal, opts.taskSpec.signal]) : next.signal;
+                    const report = await runOracle(contract.oracle, rootDir, { baseline, signal: gateSignal, ...noticeSeat });
+                    if (next.signal.aborted)
+                        return {};
+                    oracleRuns++;
+                    if (report.verdict === "red") {
+                        oracleHadRedRun = true;
+                        oracleRedRuns++;
                         stopGateBlocks++;
-                        return {
-                            block: `The verification oracle itself FAILED TO RUN (${broken.map((g) => `gate "${g.name}": ${g.reason}`).join("; ")}). ` +
-                                `This is an infrastructure error, not a test failure — you may have broken the build/test environment. ` +
-                                `Restore it so the oracle can run.`,
-                        };
+                        consecutiveOracleErrors = 0;
+                        return { block: redFeedback(report.gates) };
+                    }
+                    if (report.verdict === "error") {
+                        consecutiveOracleErrors++;
+                        if (consecutiveOracleErrors < 2) {
+                            const broken = report.gates.filter((g) => g.verdict === "error");
+                            stopGateBlocks++;
+                            return {
+                                block: `The verification oracle itself FAILED TO RUN (${broken.map((g) => `gate "${g.name}": ${g.reason}`).join("; ")}). ` +
+                                    `This is an infrastructure error, not a test failure — you may have broken the build/test environment. ` +
+                                    `Restore it so the oracle can run.`,
+                            };
+                        }
+                        gateAbandoned = true;
+                    }
+                    else {
+                        consecutiveOracleErrors = 0;
                     }
-                    gateAbandoned = true;
-                }
-                else {
-                    consecutiveOracleErrors = 0;
                 }
-            }
-            return userHooks?.stop ? userHooks.stop(ctx) : undefined;
+                return next(e);
+            });
         },
     };
     const result = await runner.runTask({
         ...opts.taskSpec,
         objective: buildObjective(specText, contract),
         toolPolicy,
-        hooks,
+        mods: [oracleGate, ...(opts.taskSpec.mods ?? [])],
     });
     guardRestores += restoreFrozenPaths(snapshot, rootDir);
     const final = await runOracle(contract.oracle, rootDir, { baseline, ...noticeSeat });

package/dist/orchestration/run-workflow-tool.js

@@ -539,9 +539,8 @@ async function mountRunWorkflowTool(d) {
                     ...((ctx.inheritedGateForChildren ?? d.inheritedGateForChildren) !== undefined
                         ? { inheritedGate: (ctx.inheritedGateForChildren ?? d.inheritedGateForChildren)() }
                         : {}),
-                    ...((ctx.toolSelector?.layers ?? d.parentToolCeiling) !== undefined ? { toolCeiling: (ctx.toolSelector?.layers ?? d.parentToolCeiling) } : {}),
                     ...(autoModeReview !== undefined ? { autoModeReview } : {}),
-                }, { workflowDepth: d.workflowDepth });
+                }, { workflowDepth: d.workflowDepth, ...((ctx.toolSelector?.layers ?? d.parentToolCeiling) !== undefined ? { toolCeiling: (ctx.toolSelector?.layers ?? d.parentToolCeiling) } : {}) });
             }
             catch (err) {
                 return structuredError(thrownText(err));

package/dist/orchestration/workflow.d.ts

@@ -153,6 +153,11 @@ export declare class WorkflowJournalAppendTimeoutError extends Error {
  */
 export interface WorkflowInternals {
     workflowDepth?: number;
+    /** The tool selector layers of the prepared run that launched this workflow (`ToolExecuteContext.toolSelector.layers`), threaded into
+     *  EVERY spawned agent as its ceiling (`RunInternals.toolCeiling`) on both spawn legs. The run that holds them judged them where it
+     *  wrote them, so they are not asked again here; a ceiling a host writes itself is {@link RunWorkflowOptions.toolCeiling}, which is.
+     *  Given both, both bound every agent (these layers first) and only the host-written one is judged. */
+    toolCeiling?: readonly import("../core/tool-face.js").ToolSelectorLayer[];
 }
 export interface WorkflowBudget {
     /** The token ceiling, or null when none was set (then `remaining()` is Infinity). */
@@ -565,9 +570,12 @@ export interface RunWorkflowOptions {
      *  `run_workflow` tool wiring; a directly-started workflow may pass its own. Absent ⇒ children run
      *  under only their own gates (pre-seam behavior). TRUSTED: never a script/model argument. */
     inheritedGate?: import("../core/runner/contracts.js").InheritedGate;
-    /** The HOST task's tool selector layers (`ToolExecuteContext.toolSelector.layers`), threaded into EVERY spawned agent's trusted
-     *  internals as its ceiling (`RunInternals.toolCeiling`) on both spawn legs: nothing a workflow agent's spec names can widen what
-     *  the host may use. Set by the `run_workflow` tool wiring; absent ⇒ the agents are bounded only by their own lists. TRUSTED. */
+    /** A tool selector ceiling the HOST writes, threaded into EVERY spawned agent's trusted internals as its ceiling
+     *  (`RunInternals.toolCeiling`) on both spawn legs: nothing a workflow agent's spec names can widen it. Nobody judged what the host
+     *  wrote, so each agent's spec is asked of it before it launches: another spelling of a tool the agent carries (a caller tool, the
+     *  catalog, a listable delegation pool) refuses that agent — `config.tool_face_control`, `detail.reason: "near_miss"`. The ceiling of the
+     *  prepared run that launched the workflow rides {@link WorkflowInternals.toolCeiling} instead; given both, both bound every agent and only
+     *  this one is judged. Absent ⇒ the agents are bounded only by their own lists. */
     toolCeiling?: readonly import("../core/tool-face.js").ToolSelectorLayer[];
     /** RB-201 FO-3 (workflow lane) — the session's auto-mode classifier, consulted BEFORE each script-spawned
      *  child starts (objective + toolset + output schema, finalized). The delegation-tool lane reviews its

package/dist/orchestration/workflow.js

@@ -20,7 +20,7 @@ import { boundInputHashOf } from "../core/canonical-json.js";
 import { boundedRedactedSummary, egressThrownText } from "../core/untrusted-egress.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
 import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
-import { deniedToolNamesOf } from "../core/runner/sub-agent-deny-lists.js";
+import { deniedToolNamesOf, judgeHostToolCeiling } from "../core/runner/sub-agent-deny-lists.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
@@ -705,6 +705,13 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
             o.close();
     };
     const sem = createSemaphore(concurrency);
+    const launchingCeiling = internals?.toolCeiling ?? undefined;
+    const hostCeiling = opts.toolCeiling ?? undefined;
+    const agentCeiling = launchingCeiling === undefined ? hostCeiling : hostCeiling === undefined ? launchingCeiling : [...launchingCeiling, ...hostCeiling];
+    const judgeHostCeiling = (spec) => {
+        if (hostCeiling !== undefined)
+            judgeHostToolCeiling(hostCeiling, spec, launchingCeiling);
+    };
     const spawnAttribution = {
         isDelegatedChild: true,
         ...(opts.questionFaceStripped === true ? { questionFaceStripped: true } : {}),
@@ -715,7 +722,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         ...(opts.parentCenterSourceRevision !== undefined ? { parentCenterSourceRevision: opts.parentCenterSourceRevision } : {}),
         ...(opts.onForwardEvent ? { onForwardEvent: opts.onForwardEvent } : {}),
         ...(opts.inheritedGate !== undefined ? { inheritedGate: opts.inheritedGate } : {}),
-        ...(opts.toolCeiling !== undefined ? { toolCeiling: opts.toolCeiling } : {}),
+        ...(agentCeiling !== undefined ? { toolCeiling: agentCeiling } : {}),
         ...((opts.rootSessionId ?? opts.originatingSessionId) !== undefined ? { rootSessionId: opts.rootSessionId ?? opts.originatingSessionId } : {}),
         ...(opts.placementRoot !== undefined ? { placementRoot: opts.placementRoot } : {}),
         ...(opts.originatingSessionId !== undefined ? { parentSessionId: opts.originatingSessionId } : {}),
@@ -1645,6 +1652,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                 const preReviewSpec = agentOpts.schema
                     ? { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
                     : { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
+                judgeHostCeiling(preReviewSpec);
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agent", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForward = opts.onForwardEvent !== undefined
                     ? (e) => {
@@ -2010,6 +2018,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                     ? { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal, outputSchema: agentOpts.schema }
                     : { ...seatedSpec, ...authInherit, ...parkInherit, signal: effectiveSignal };
                 const preReviewSpec = childSessionId !== undefined ? { ...baseRunSpec, sessionId: childSessionId } : baseRunSpec;
+                judgeHostCeiling(preReviewSpec);
                 const runSpec = await reviewSpawnBeforeLaunch("ctx.agentStream", label, callKey, preReviewSpec, effectiveSignal);
                 const enrichedForwardS = opts.onForwardEvent !== undefined
                     ? (e) => {

package/dist/prompt-assembly/artifact-store.d.ts

@@ -1,28 +1,46 @@
-import { type PromptEpochArtifact, type PublishedPromptArtifactEnvelope } from "./artifact.js";
+import type { RunnerDeps } from "../core/runner-deps.js";
+import { type ArtifactVerifyCode, type PromptArtifact, type PublishedPromptArtifact } from "./artifact.js";
+/** Why a copy a store holds could not be used: the verifier refused it (its code and reason — a retired schema's reason
+ *  names the republish rewrite), or the store could not read it back (`unreadable`, the reason naming the read error). */
+export interface StoredArtifactRefusal {
+    readonly code: ArtifactVerifyCode | "unreadable";
+    readonly reason: string;
+}
+/** What a read tells its caller when a copy was there and could not be used. */
+export type OnArtifactRefused = (refusal: StoredArtifactRefusal) => void;
+/** The clause every reader says of a copy that could not be used, by its cause — one wording, wherever it is said. */
+export declare function refusalClause(refusal: StoredArtifactRefusal): string;
+/**
+ * The operator line for a stored center artifact that could not be read back: which copy, why — refused or unreadable
+ * (the clause above), or no copy at all — and what follows from it. The one sentence a boot restore and a pinned resume
+ * say.
+ */
+export declare function storedArtifactLine(artifactDigest: string, refusal: StoredArtifactRefusal | undefined, consequence: string): string;
 export interface PromptArtifactStore {
-    /** Verified read by digest — undefined on miss OR on any verification failure of stored bytes. */
-    get(artifactDigest: string, opts: {
-        engineVersion: string;
-    }): Promise<PublishedPromptArtifactEnvelope | undefined>;
-    /** Idempotent immutable write (same digest ⇒ same bytes; the caller verified before putting). */
-    put(envelope: PublishedPromptArtifactEnvelope): Promise<void>;
+    /**
+     * Verified read by digest — undefined on a miss OR on a copy that cannot be used. When a copy was there and could not
+     * be used — the verifier refused its bytes, or the store could not read them — `onRefused` is told once before the
+     * read answers undefined, so a caller can tell a refused or unreadable copy (a retired schema, a corrupt file, a file
+     * the process may not read) from a missing one. A store that holds a copy it cannot use calls it.
+     */
+    get(artifactDigest: string, onRefused?: OnArtifactRefused): Promise<PublishedPromptArtifact | undefined>;
+    /** Write by digest (the caller verified before putting). */
+    put(artifact: PublishedPromptArtifact): Promise<void>;
 }
 export declare class MemoryPromptArtifactStore implements PromptArtifactStore {
     private readonly byDigest;
-    get(artifactDigest: string, opts: {
-        engineVersion: string;
-    }): Promise<PublishedPromptArtifactEnvelope | undefined>;
-    put(envelope: PublishedPromptArtifactEnvelope): Promise<void>;
+    get(artifactDigest: string, onRefused?: OnArtifactRefused): Promise<PublishedPromptArtifact | undefined>;
+    put(artifact: PublishedPromptArtifact): Promise<void>;
 }
-/** `artifacts/<hex>.json` under a caller-owned directory; atomic tmp+rename writes (§9.2). */
+/** `artifacts/<hex>.json` under a caller-owned directory; atomic tmp+rename writes. */
 export declare class FilePromptArtifactStore implements PromptArtifactStore {
     private readonly dir;
     constructor(dir: string);
     private fileFor;
-    get(artifactDigest: string, opts: {
-        engineVersion: string;
-    }): Promise<PublishedPromptArtifactEnvelope | undefined>;
-    put(envelope: PublishedPromptArtifactEnvelope): Promise<void>;
+    /** A file that is not there is a miss; one that is there and cannot be read (a directory in its place, a file the
+     *  process may not open, too many open files) is told to `onRefused` as `unreadable`, by its error code. */
+    get(artifactDigest: string, onRefused?: OnArtifactRefused): Promise<PublishedPromptArtifact | undefined>;
+    put(artifact: PublishedPromptArtifact): Promise<void>;
 }
 export type PromptSourceState = {
     state: "active";
@@ -49,60 +67,58 @@ export declare class FilePromptSourceStateStore implements PromptSourceStateStor
     load(): Promise<PromptSourceState | undefined>;
     save(state: PromptSourceState): Promise<void>;
 }
-/** The narrow face the Runner consumes (RunnerDeps.promptSource) — resolution only, no publish. */
+/** The narrow face the Runner consumes (`RunnerDeps.promptSource`) — resolution only, no publish. */
 export interface PromptArtifactSource {
-    /** The current validated candidate for NEW sessions, with its publish provenance
-     *  (undefined = bundled-only, today's shape). */
-    current(): {
-        artifact: PromptEpochArtifact;
-        sourceRevision: string;
-    } | undefined;
-    /** Resolve a PINNED digest (resume path). Undefined = unavailable — the caller fails loud. */
-    get(artifactDigest: string): Promise<PromptEpochArtifact | undefined>;
-    /** RB-31 — the tri-state the adoption boundary keys on: `"disabled"` = an EXPLICIT
-     *  validated revocation (applyDisabled) ⇒ pinned sessions roll back to bundled at the next
-     *  compaction; `"active"` = a validated candidate is live; `"unavailable"` = no verified state
-     *  (never-configured face, store-miss boot) ⇒ conservative restate — an outage must never strip
-     *  policy, only an explicit revocation does. Optional (older sources read as "unavailable"). */
-    sourceState?(): "active" | "disabled" | "unavailable";
+    /** The current verified candidate new sessions (and every top-level session at a compaction) adopt; undefined = none. */
+    current(): PublishedPromptArtifact | undefined;
+    /** Resolve a PINNED digest (the resume path). Undefined = unavailable — the caller fails loud. `onRefused` is the
+     *  store's (see {@link PromptArtifactStore.get}): told when a copy was there and could not be used, so the caller says
+     *  why. */
+    get(artifactDigest: string, onRefused?: OnArtifactRefused): Promise<PromptArtifact | undefined>;
+    /** The tri-state every adoption decision keys on: `"active"` = a verified candidate is live; `"disabled"` = an
+     *  EXPLICIT verified revocation (`applyDisabled`) — the one state that empties a pinned center layer;
+     *  `"unavailable"` = no verified state (never configured, or a store miss at boot) — an outage never strips policy,
+     *  only an explicit revocation does. */
+    sourceState(): "active" | "disabled" | "unavailable";
 }
 /**
- * The candidate state machine (§9.2 full pipeline). Publish-side entry points:
- *   - `applySnapshot(raw)` — a fetched effective-snapshot body: verify → store.put → persist
- *     active state → atomic in-memory swap. Any verification failure leaves EVERYTHING unchanged.
- *   - `applyDisabled(sourceRevision)` — an explicit, successful disable/delete response: persist
- *     disabled state + drop the candidate. (Network failure/304 = simply don't call anything.)
- *   - `restore()` — boot: re-resolve persisted active state through the verified store; a miss or
- *     verify failure boots stateless (no candidate) without touching the persisted record.
+ * The candidate state machine. Publish-side entry points:
+ *   - `applySnapshot(raw)` — a fetched published artifact: verify → store.put → persist active state → atomic
+ *     in-memory swap. Any verification failure leaves EVERYTHING unchanged.
+ *   - `applyDisabled(sourceRevision)` — an explicit, successful disable/delete response: persist disabled state +
+ *     drop the candidate. (Network failure/304 = simply don't call anything.)
+ *   - `restore()` — boot: re-resolve the persisted active state through the verified store; a miss, an unreadable copy
+ *     or a verify failure boots stateless (no candidate) without touching the persisted record, and says which on
+ *     `onError` (a refused copy — a retired schema's reason names the republish rewrite — and an unreadable one are told
+ *     apart from no copy at all).
  */
 export declare class CenterPromptSource implements PromptArtifactSource {
     private readonly store;
     private readonly stateStore;
-    private readonly engineVersion;
+    private readonly onError;
+    private readonly notifier;
     private candidate;
     private state;
-    /** Hardening 2026-07-31 — serialization tail for the three STATE-MUTATING entry points. Each of
-     *  them is a multi-await sequence ending in a synchronous swap of (candidate, state); with two in
-     *  flight, an interleaving where B's `stateStore.save` resolves and swaps before A's leaves the
-     *  persisted record naming B's digest while the in-memory candidate names A's — `current()` then
-     *  serves A to every new session until the next `restore()` silently switches to B. `CenterPromptSource`
-     *  is a public export driven by a caller's poll loop, so two overlapping applies are an ordinary
-     *  schedule, not an exotic race. Serializing costs nothing (these are publish-rate operations) and
-     *  makes the durable record and the in-memory candidate agree by construction. */
+    /** Serialization tail for the three STATE-MUTATING entry points. Each is a multi-await sequence ending in a
+     *  synchronous swap of (candidate, state); with two in flight, an interleaving where B's `stateStore.save`
+     *  resolves and swaps before A's would leave the persisted record naming B's digest while the in-memory candidate
+     *  names A's. `CenterPromptSource` is driven by a caller's poll loop, so overlapping applies are an ordinary
+     *  schedule. Serializing costs nothing (publish-rate operations) and makes the durable record and the in-memory
+     *  candidate agree by construction. */
     private tail;
-    /** Run `fn` after every previously-queued mutation settles (success OR failure — a failed apply
-     *  must not wedge the queue). */
+    /** Run `fn` after every previously-queued mutation settles (success OR failure — a failed apply must not wedge the queue). */
     private exclusive;
+    /** `onError` is the operator channel of the source's own acts (a boot restore that finds its persisted artifact
+     *  refused, unreadable or gone) — the Runner's sink, in its shape (`RunnerDeps.onError`): pass the Runner's. A boot
+     *  restore belongs to no session: its context is `{ phase: "prompt-constitution", sessionId: "", classification:
+     *  "center-source-restore" }`. Omitted = those acts are silent. */
     constructor(opts: {
         store: PromptArtifactStore;
         stateStore?: PromptSourceStateStore;
-        engineVersion: string;
+        onError?: RunnerDeps["onError"];
     });
-    current(): {
-        artifact: PromptEpochArtifact;
-        sourceRevision: string;
-    } | undefined;
-    get(artifactDigest: string): Promise<PromptEpochArtifact | undefined>;
+    current(): PublishedPromptArtifact | undefined;
+    get(artifactDigest: string, onRefused?: OnArtifactRefused): Promise<PromptArtifact | undefined>;
     restore(): Promise<void>;
     sourceState(): "active" | "disabled" | "unavailable";
     applySnapshot(raw: unknown): Promise<{
@@ -110,7 +126,7 @@ export declare class CenterPromptSource implements PromptArtifactSource {
         artifactDigest: string;
     } | {
         ok: false;
-        code: string;
+        code: ArtifactVerifyCode;
         reason: string;
     }>;
     applyDisabled(sourceRevision: string): Promise<void>;

package/dist/prompt-assembly/artifact-store.js

@@ -1,29 +1,40 @@
 import { mkdirSync, promises as fs } from "node:fs";
 import path from "node:path";
-import { verifyPromptArtifact, } from "./artifact.js";
-function normalizedEnvelope(parsed, artifact) {
-    return { ...parsed, artifact };
+import { createSafeNotifier, observeThenableRejection } from "../core/safe-notify.js";
+import { verifyPromptArtifact } from "./artifact.js";
+export function refusalClause(refusal) {
+    return refusal.code === "unreadable" ? `unreadable (${refusal.reason})` : `refused by this engine (${refusal.code}: ${refusal.reason})`;
+}
+export function storedArtifactLine(artifactDigest, refusal, consequence) {
+    return `center prompt artifact ${artifactDigest.slice(0, 23)}… ${refusal !== undefined ? `is ${refusalClause(refusal)}` : "has no stored copy"} — ${consequence}`;
+}
+function tellRefused(onRefused, refusal) {
+    const notifier = createSafeNotifier();
+    notifier.notify(() => observeThenableRejection(onRefused?.(refusal), notifier, "artifact-store.onRefused"), "artifact-store.onRefused");
+    return undefined;
+}
+function verifiedRead(bytes, artifactDigest, onRefused) {
+    const refuse = (refusal) => tellRefused(onRefused, refusal);
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes);
+    }
+    catch {
+        return refuse({ code: "shape", reason: "the stored bytes are not JSON" });
+    }
+    const v = verifyPromptArtifact(parsed);
+    if (!v.ok)
+        return refuse({ code: v.code, reason: v.reason });
+    return v.artifact.artifactDigest === artifactDigest ? v.artifact : refuse({ code: "digest", reason: "the stored artifact is not the one its digest names" });
 }
 export class MemoryPromptArtifactStore {
     byDigest = new Map();
-    async get(artifactDigest, opts) {
+    async get(artifactDigest, onRefused) {
         const bytes = this.byDigest.get(artifactDigest);
-        if (bytes === undefined)
-            return undefined;
-        let parsed;
-        try {
-            parsed = JSON.parse(bytes);
-        }
-        catch {
-            return undefined;
-        }
-        const v = verifyPromptArtifact(parsed, opts);
-        if (!v.ok || v.artifact.artifactDigest !== artifactDigest)
-            return undefined;
-        return normalizedEnvelope(parsed, v.artifact);
+        return bytes === undefined ? undefined : verifiedRead(bytes, artifactDigest, onRefused);
     }
-    async put(envelope) {
-        this.byDigest.set(envelope.artifact.artifactDigest, JSON.stringify(envelope));
+    async put(artifact) {
+        this.byDigest.set(artifact.artifactDigest, JSON.stringify(artifact));
     }
 }
 export class FilePromptArtifactStore {
@@ -36,7 +47,7 @@ export class FilePromptArtifactStore {
         const m = /^sha256:([0-9a-f]{64})$/.exec(artifactDigest);
         return m ? path.join(this.dir, "artifacts", `${m[1]}.json`) : undefined;
     }
-    async get(artifactDigest, opts) {
+    async get(artifactDigest, onRefused) {
         const file = this.fileFor(artifactDigest);
         if (file === undefined)
             return undefined;
@@ -44,27 +55,20 @@ export class FilePromptArtifactStore {
         try {
             bytes = await fs.readFile(file, "utf8");
         }
-        catch {
-            return undefined;
+        catch (err) {
+            const code = typeof err === "object" && err !== null ? err.code : undefined;
+            if (code === "ENOENT")
+                return undefined;
+            return tellRefused(onRefused, { code: "unreadable", reason: `the store could not read its file: ${typeof code === "string" ? code : "an error with no code"}` });
         }
-        let parsed;
-        try {
-            parsed = JSON.parse(bytes);
-        }
-        catch {
-            return undefined;
-        }
-        const v = verifyPromptArtifact(parsed, opts);
-        if (!v.ok || v.artifact.artifactDigest !== artifactDigest)
-            return undefined;
-        return normalizedEnvelope(parsed, v.artifact);
+        return verifiedRead(bytes, artifactDigest, onRefused);
     }
-    async put(envelope) {
-        const file = this.fileFor(envelope.artifact.artifactDigest);
+    async put(artifact) {
+        const file = this.fileFor(artifact.artifactDigest);
         if (file === undefined)
-            throw new Error(`prompt-artifact store: malformed digest ${JSON.stringify(envelope.artifact.artifactDigest).slice(0, 120)}`);
+            throw new Error(`prompt-artifact store: malformed digest ${JSON.stringify(artifact.artifactDigest).slice(0, 120)}`);
         const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
-        await fs.writeFile(tmp, JSON.stringify(envelope), "utf8");
+        await fs.writeFile(tmp, JSON.stringify(artifact), "utf8");
         await fs.rename(tmp, file);
     }
 }
@@ -113,7 +117,8 @@ export class FilePromptSourceStateStore {
 export class CenterPromptSource {
     store;
     stateStore;
-    engineVersion;
+    onError;
+    notifier = createSafeNotifier();
     candidate;
     state = "unavailable";
     tail = Promise.resolve();
@@ -125,16 +130,15 @@ export class CenterPromptSource {
     constructor(opts) {
         this.store = opts.store;
         this.stateStore = opts.stateStore ?? new MemoryPromptSourceStateStore();
-        this.engineVersion = opts.engineVersion;
+        this.onError = opts.onError;
     }
     current() {
         return this.candidate;
     }
-    async get(artifactDigest) {
-        if (this.candidate?.artifact.artifactDigest === artifactDigest)
-            return this.candidate.artifact;
-        const env = await this.store.get(artifactDigest, { engineVersion: this.engineVersion });
-        return env?.artifact;
+    async get(artifactDigest, onRefused) {
+        if (this.candidate?.artifactDigest === artifactDigest)
+            return this.candidate;
+        return this.store.get(artifactDigest, onRefused);
     }
     async restore() {
         return this.exclusive(async () => {
@@ -149,23 +153,27 @@ export class CenterPromptSource {
                 this.state = "unavailable";
                 return;
             }
-            const env = await this.store.get(state.artifactDigest, { engineVersion: this.engineVersion });
-            this.candidate = env !== undefined ? { artifact: env.artifact, sourceRevision: state.sourceRevision } : undefined;
-            this.state = env !== undefined ? "active" : "unavailable";
+            const refused = {};
+            const stored = await this.store.get(state.artifactDigest, (r) => void (refused.current = r));
+            this.candidate = stored !== undefined ? { ...stored, sourceRevision: state.sourceRevision } : undefined;
+            this.state = stored !== undefined ? "active" : "unavailable";
+            if (stored === undefined) {
+                const line = new Error(storedArtifactLine(state.artifactDigest, refused.current, "the source boots unavailable: a new session has no center layer until a verified artifact is applied"));
+                this.notifier.notify(() => observeThenableRejection(this.onError?.(line, { phase: "prompt-constitution", sessionId: "", classification: "center-source-restore" }), this.notifier, "center-source.onError"), "center-source.onError");
+            }
         });
     }
     sourceState() {
         return this.state;
     }
     async applySnapshot(raw) {
-        const v = verifyPromptArtifact(raw, { engineVersion: this.engineVersion });
+        const v = verifyPromptArtifact(raw);
         if (!v.ok)
             return v;
-        const envelope = raw;
         return this.exclusive(async () => {
-            await this.store.put(envelope);
-            await this.stateStore.save({ state: "active", artifactDigest: v.artifact.artifactDigest, sourceRevision: envelope.sourceRevision });
-            this.candidate = { artifact: v.artifact, sourceRevision: envelope.sourceRevision };
+            await this.store.put(v.artifact);
+            await this.stateStore.save({ state: "active", artifactDigest: v.artifact.artifactDigest, sourceRevision: v.artifact.sourceRevision });
+            this.candidate = v.artifact;
             this.state = "active";
             return { ok: true, artifactDigest: v.artifact.artifactDigest };
         });