@sema-agent/core 7.55.0 → 7.57.0

package/dist/prompt-assembly/turn-snapshot.d.ts

@@ -6,12 +6,9 @@ export interface RawPrefixInputs {
     provider: string;
     /** Model id (a switch is a new cache namespace). */
     modelId: string;
-    /** The run's prompt identity (`promptIdentityOf`: catalog, renderers, overlay layers, binding) — the manifest's
-     *  `identity.artifact`. */
+    /** The run's prompt identity (`promptIdentityOf`: catalog, renderers, overlay layers, binding — the binding element
+     *  digests the selector values, the prompt traits among them) — the manifest's `identity.artifact`. */
     artifactDigest: string;
-    /** Presentation/policy axis: promptProfile + fable mitigations (prose forks on these). */
-    promptProfile: string;
-    fableMitigations: boolean;
     /** Physical block layout as SERVED (derived from the composed system blocks; single-block default). */
     layoutGroups: ReadonlyArray<{
         groupId: string;
@@ -47,8 +44,6 @@ export declare const PREFIX_INPUT_CLASSIFICATION: {
     readonly provider: "cache-identity";
     readonly modelId: "cache-identity";
     readonly artifactDigest: "cache-identity";
-    readonly promptProfile: "cache-identity";
-    readonly fableMitigations: "cache-identity";
     readonly layoutGroups: "cache-identity";
     readonly stableSystemText: "cache-identity";
     readonly toolWire: "cache-identity";
@@ -68,12 +63,11 @@ export interface LoweringRecord {
 }
 export declare const LOWERING_VERSION = "sema-lowering@1";
 export declare function loweringRecordFor(api: string): LoweringRecord;
-/** The nine identity elements, individually digested (observable without shipping prompt text). */
+/** The eight identity elements, individually digested (observable without shipping prompt text). */
 export interface CacheIdentityElements {
     provider: string;
     modelId: string;
     artifactDigest: string;
-    policyDigest: string;
     layoutDigest: string;
     stableSystemDigest: string;
     toolWireDigest: string;
@@ -82,7 +76,7 @@ export interface CacheIdentityElements {
 }
 export interface TurnPromptSnapshot {
     elements: CacheIdentityElements;
-    /** sha256(canonical(elements)) — the ONE nine-element identity value. */
+    /** sha256(canonical(elements)) — the ONE eight-element identity value. */
     cacheIdentity: string;
     lowering: LoweringRecord;
     /** invoked after EVERY refresh so the run loop can emit the changed identity

package/dist/prompt-assembly/turn-snapshot.js

@@ -4,8 +4,6 @@ export const PREFIX_INPUT_CLASSIFICATION = {
     provider: "cache-identity",
     modelId: "cache-identity",
     artifactDigest: "cache-identity",
-    promptProfile: "cache-identity",
-    fableMitigations: "cache-identity",
     layoutGroups: "cache-identity",
     stableSystemText: "cache-identity",
     toolWire: "cache-identity",
@@ -53,7 +51,6 @@ export function buildTurnPromptSnapshot(raw, api, promptHasher) {
         provider: raw.provider,
         modelId: raw.modelId,
         artifactDigest: raw.artifactDigest,
-        policyDigest: sha(canonical({ promptProfile: raw.promptProfile, fableMitigations: raw.fableMitigations })),
         layoutDigest: sha(canonical(raw.layoutGroups)),
         stableSystemDigest: promptSha(raw.stableSystemText),
         toolWireDigest: sha(canonical(raw.toolWire.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })))),

package/dist/prompt-assembly/types.d.ts

@@ -32,11 +32,6 @@ export interface PromptRuntimeFacts {
     /** Orchestration is active but the Workflow tool is DEFERRED — the mode section serves the short pointer.
      *  Only meaningful when orchestrationEnabled. OPTIONAL — absence reads as false. */
     orchestrationDeferred?: boolean;
-    /** The run's resolved prompt profile ("simple" default). It becomes the `lean_prompt` trait; catalog
-     *  data reads the trait. OPTIONAL — absence reads as "simple". */
-    promptProfile?: "simple" | "classic";
-    /** The run's model is fable-family. It becomes the `fable_5_mitigations` trait. OPTIONAL — absence = false. */
-    fableMitigations?: boolean;
     awarenessEnabled: boolean;
     goalEnabled: boolean;
     worktreeIsolated: boolean;
@@ -59,8 +54,6 @@ export interface SectionRenderInputs {
     environmentBlock?: string;
     /** Pre-rendered volatile memory tail (engine injection + fenced project layer). */
     memoryBlock?: string;
-    /** model.promptGuidance joined text, if the model declares any. */
-    modelGuidance?: string;
 }
 /** One rendered (admitted, non-empty) section of a composition — the compiled IR unit. */
 export interface CompiledSection {

package/dist/scenarios/full-body.d.ts

@@ -10,9 +10,9 @@ import type { ToolSpec, RoleSpec } from "../core/types.js";
  * `prepareTask` when the trusted assembler wires those deps/flags. This bundle is only the caller-composed factories.
  */
 export interface CodeToolsConfig {
-    /** web_fetch policy. 🔴 `allowHosts` stays UNSET by default — passing `[]` would refuse ALL hosts (truthy empty,
-     *  `web.ts` `if (allowHosts && !allowlisted)`), breaking single-tenant TOC web fetch. A MULTI-TENANT deployment
-     *  MUST pass an explicit allowlist; the SSRF floor (`isPrivateHost`) applies regardless. */
+    /** web_fetch's factory options (fetch seam, byte / time caps, summarizer). Which hosts it may reach is NOT one of them: that is the
+     *  deployment's host floor (`RunnerDeps.hostFloor`, every structured egress, read from the run on every hop) — a MULTI-TENANT
+     *  deployment declares one there; the private-network floor applies regardless. */
     webFetch?: WebFetchConfig;
     /** WebSearch backend (BRAIN/model-service leg). Absent ⇒ WebSearch is not assembled (core ships no backend). */
     webSearch?: WebSearchConfig;
@@ -20,11 +20,11 @@ export interface CodeToolsConfig {
      *  surface as the leader's own instances (one `TaskListStore`), bounded by what the spawning run mounts and trimmed
      *  by the spawn tier (`SubagentToolOptions.inheritedTools`). Tools composed BESIDE the bundle are not inherited: a
      *  host hands those per spawn through `subagent.extraTools`, behind its own gates.
-     *  合车复审修③: when this carries NO explicit `systemPrompt`, the assembler defaults it to
-     *  `CODE_SYSTEM_PROMPT` — a code-scenario child holds Bash/Write side-effect tools, so it keeps the code
+     *  合车复审修③: when this names NO role base (neither `promptRole` nor `systemPrompt`), the assembler defaults it
+     *  to `promptRole: "code"` — a code-scenario child holds Bash/Write side-effect tools, so it keeps the code
      *  constitution (snapshot-before-mutate / destructive-op care / git discipline) instead of falling to the
      *  lean SUBAGENT_PROMPT (the G1 default, which is the right upstream-anchor shape only for bare
-     *  general-purpose delegation). Pass an explicit `systemPrompt` here to override. */
+     *  general-purpose delegation). Pass an explicit `promptRole` / `systemPrompt` here to override. */
     subagent?: SubagentToolOptions;
     /**
      * TodoWrite (CONTEXT leg). Default true, BUT mutually exclusive with the task-list family (
@@ -58,15 +58,15 @@ export interface CodeToolsConfig {
  * Single-source bundle of the `code` scenario's `spec.tools`-class tools, so each deployment doesn't re-wire it
  * (the single-source discipline: a scenario is data — a named bundle).
  * Profile-as-data — the engine iterates `spec.tools` branch-free; nothing keys off the scenario name. A trusted
- * assembler (service) calls this, sets `systemPrompt = CODE_SYSTEM_PROMPT` (or `role = CODE_ROLE`) +
+ * assembler (service) calls this, sets `promptRole = "code"` (or `roles.default = CODE_ROLE`) +
  * `enablePlanMode:true`, and wires the deps seams (executionEnv/onQuestion/lspManager/skillSpecs/memoryStore/
  * selfOrchestration) — that is what makes a run the `code` scenario. Returns ONLY the caller-composed tools.
  */
 export declare function assembleCodeTools(cfg?: CodeToolsConfig): ToolSpec[];
 /**
- * RoleSpec preset for the `code` scenario's coding role. Selected via the existing
- * `spec.systemPrompt ?? resolvedRole.systemPrompt` chain (no new field, no new conditional). `thinking:"high"` is a
- * sensible floor; the assembler/SDK can raise it (effort→thinking) per request. The global DEFAULT_SYSTEM_PROMPT
- * stays neutral.
+ * RoleSpec preset for the `code` scenario's coding role: the catalog's coding role base by word (`promptRole:
+ * "code"`), the role-base decision's second source — it applies when the task names no role base of its own.
+ * `thinking:"high"` is a sensible floor; the assembler/SDK can raise it (effort→thinking) per request. The global
+ * DEFAULT_SYSTEM_PROMPT stays neutral.
  */
 export declare const CODE_ROLE: RoleSpec;

package/dist/scenarios/full-body.js

@@ -2,7 +2,7 @@ import { webFetchToolSpec, createWebSearchTool } from "../tools/web.js";
 import { createTodoWriteTool } from "../tools/todo.js";
 import { createTaskListTools } from "../tools/task-list.js";
 import { createSubagentTool } from "../agents/subagent.js";
-import { CODE_SYSTEM_PROMPT } from "../prompts/default.js";
+import { namesRoleBase } from "../prompt-assembly/role-base.js";
 export function assembleCodeTools(cfg = {}) {
     const web = [webFetchToolSpec(cfg.webFetch ?? {})];
     if (cfg.webSearch)
@@ -19,13 +19,14 @@ export function assembleCodeTools(cfg = {}) {
     }
     const tools = [...web];
     if (cfg.subagent) {
+        const roleBase = namesRoleBase(cfg.subagent) ? {} : { promptRole: "code" };
         tools.push(createSubagentTool({
             ...cfg.subagent,
-            systemPrompt: cfg.subagent.systemPrompt ?? CODE_SYSTEM_PROMPT,
+            ...roleBase,
             inheritedTools: cfg.subagent.inheritedTools ?? [...web, ...scaffolds],
         }));
     }
     tools.push(...scaffolds);
     return tools;
 }
-export const CODE_ROLE = { systemPrompt: CODE_SYSTEM_PROMPT, thinking: "high" };
+export const CODE_ROLE = { promptRole: "code", thinking: "high" };

package/dist/shell/lex.js

@@ -1169,6 +1169,7 @@ function scan(source, connectorsAreText, segments, level, list) {
     let assignmentSeen = false;
     let subscriptsClosed = false;
     let commandWord;
+    let arithParens = 0;
     let w = new WordBuilder();
     const next = (j) => past(source, j + 1);
     const quotedBy = () => (inSingle || inDouble ? regionBy : undefined);
@@ -1503,7 +1504,7 @@ function scan(source, connectorsAreText, segments, level, list) {
             take(ch, i);
             continue;
         }
-        if (ch === "#" && !w.started) {
+        if (ch === "#" && !w.started && arithParens === 0) {
             const nl = source.indexOf("\n", i);
             i = nl < 0 ? source.length : nl - 1;
             continue;
@@ -1531,6 +1532,14 @@ function scan(source, connectorsAreText, segments, level, list) {
             const r = endWord() ?? operandOwed(i);
             if (r !== undefined)
                 return r;
+            if (ch === "(") {
+                if (arithParens > 0)
+                    arithParens++;
+                else if (split && source[next(i)] === "(")
+                    arithParens = 1;
+            }
+            else if (arithParens > 0)
+                arithParens--;
             current().tokens.push({ kind: "group", op: ch });
             resetPosition();
             continue;

package/dist/stores/file/adoption/adopt.js

@@ -8,6 +8,7 @@ import { SessionPolicyError } from "../../../core/session-policy-store.js";
 import { thrownText } from "../../../core/thrown-value.js";
 import { AdoptionError, NOT_MIGRATED_BY_DESIGN, readRootAdoptionFile, writeRootAdoptionFile, } from "./marker.js";
 import { readRuleOwner, ruleOwnerText, sameRuleOwner } from "../../../core/rule-owner.js";
+import { principalNameOf } from "../../../core/principal-name.js";
 const CONFIG_ACCOUNT_FILE = "adoption-configs.json";
 function baselineConfigs(toPrincipal) {
     return [
@@ -333,12 +334,12 @@ function answerFromExisting(root, existing, from, toPrincipal) {
     return undefined;
 }
 export async function adoptLocalDataRoot(opts) {
-    if (typeof opts.toPrincipal !== "string" || opts.toPrincipal === "") {
-        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires the adopting principal — adoption is the act of giving this data root an identity");
+    if (principalNameOf(opts.toPrincipal) === undefined) {
+        throw new AdoptionError("adoption_bad_request", "adoptLocalDataRoot requires the adopting principal, a principal name — adoption is the act of giving this data root an identity");
     }
     const from = readRuleOwner(opts.from);
     if (from === undefined) {
-        throw new AdoptionError("adoption_bad_request", "the adoption source must be the local-owner kind or a principal with a non-blank name — local-single-user identity is the local-owner kind, never a blank string");
+        throw new AdoptionError("adoption_bad_request", "the adoption source must be the local-owner kind or a principal owner whose principal is a principal name — local-single-user identity is the local-owner kind, never a blank string");
     }
     if (from.kind === "principal" && from.principal === opts.toPrincipal) {
         throw new AdoptionError("adoption_bad_request", `the data root already belongs to "${opts.toPrincipal}" — there is nothing to adopt`);

package/dist/stores/file/adoption/marker.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { readRuleOwner, sameRuleOwner } from "../../../core/rule-owner.js";
+import { principalNameOf } from "../../../core/principal-name.js";
 import { atomicWriteFile, ensureDir } from "../fs-atomic.js";
 export class AdoptionError extends Error {
     code;
@@ -39,7 +40,7 @@ function isRootAdoptionFileShape(v) {
             typeof m !== "object" ||
             typeof m.adoptionId !== "string" ||
             readRuleOwner(m.from) === undefined ||
-            typeof m.toPrincipal !== "string" ||
+            principalNameOf(m.toPrincipal) === undefined ||
             typeof m.phase !== "number" ||
             ![2, 3, 4, 5].includes(m.phase)) {
             return false;
@@ -88,7 +89,7 @@ function isRootAdoptionFileShape(v) {
         if (a === null ||
             typeof a !== "object" ||
             from === undefined ||
-            typeof a.toPrincipal !== "string" ||
+            principalNameOf(a.toPrincipal) === undefined ||
             typeof a.atMs !== "number" ||
             a.immutableReport === null ||
             typeof a.immutableReport !== "object") {

package/dist/stores/file/checkpoint-store.d.ts

@@ -1,6 +1,8 @@
 import { type ExecutionOutcomeRecordWord } from "../../core/checkpoint-execution-record.js";
+import { type HolderJudge } from "../../core/checkpoint-generation.js";
 import { type Checkpoint, type PendingSteerInput, type CheckpointFaultMode, type CheckpointStore, type CheckpointSummary, type CheckpointToken, type ReopenReason, type ResolveExpectation, type ResumeOutcome } from "../../core/checkpoint-store.js";
 import type { GateOutcome } from "../../core/gate-outcome.js";
+import { type CheckpointDeleteGuard, type CheckpointOverdueCursor, type CheckpointOverdueQuery, type CheckpointPage, type CheckpointRowRead, type CheckpointSessionCursor, type CheckpointSessionQuery } from "../../core/checkpoint-queries.js";
 import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 export interface FileCheckpointStoreOptions {
     /** This store's half of {@link import("./shared-ledger.js").LedgerPaths.onCorruptRead}. */
@@ -11,6 +13,13 @@ export interface FileCheckpointStoreOptions {
     fsync?: boolean;
     /** Compact the ledger into a snapshot once it exceeds this many events (then truncate). Default 1000. */
     compactEvery?: number;
+    /** The session head read (a session store's `headOf`) {@link FileCheckpointStore.deleteSessionCheckpoints} judges its guard by;
+     *  without it the store has no `deleteSessionCheckpoints` member. */
+    sessionHeadOf?: (sessionId: string) => Promise<{
+        readonly owner: string | null;
+    } | undefined>;
+    /** The judge of a resolve's claim holder ({@link HolderJudge}); with it the store declares `fence = { holder: true }`. */
+    holderIsCurrent?: HolderJudge;
 }
 export declare class FileCheckpointStore implements CheckpointStore {
     /** design/173 §2.3 — honest declaration on the restart-survival axis the vocabulary claims: rows
@@ -26,14 +35,15 @@ export declare class FileCheckpointStore implements CheckpointStore {
      *  same JSON reading as the ledger line); the declaration is what makes the loss visible to the mint BEFORE the
      *  row is filed. */
     readonly fidelity: "json";
-    /** F-012 L2: `reopen` here is a real resolved→pending CAS journaled to the ledger — declared, not sniffed. */
-    readonly redecision: {
-        readonly reopen: true;
-    };
     /** The execution-outcome record verb below is the contract's CAS (journaled), and `reopen` honours the record. */
     readonly execution: {
         readonly outcome: true;
     };
+    /** Declared exactly when the store was built with a `holderIsCurrent` judge. */
+    readonly fence?: {
+        readonly holder: true;
+    };
+    private readonly holderIsCurrent;
     private readonly fsyncEnabled;
     private readonly compactEvery;
     /** RB-134: the directory's ONE authority (map + token mutex + append log), joined not rebuilt. */
@@ -45,6 +55,8 @@ export declare class FileCheckpointStore implements CheckpointStore {
     /** The guarded {@link FileCheckpointStoreOptions.onCorruptRead} seat (the ledger's replay and this store's projection share it). */
     private readonly discloseCorrupt;
     private readonly ledgerPath;
+    /** Present exactly when the store was built with a session head read (`FileCheckpointStoreOptions.sessionHeadOf`). */
+    readonly deleteSessionCheckpoints?: (sessionId: string, guard: CheckpointDeleteGuard) => Promise<number>;
     constructor(root: string, opts?: FileCheckpointStoreOptions);
     /** Serialize an op behind any in-flight op on the same token (the in-process per-token async mutex). */
     private withLock;
@@ -69,6 +81,11 @@ export declare class FileCheckpointStore implements CheckpointStore {
     reap(scope: string, cutoff: number): Promise<number>;
     listByScope(scope: string): Promise<CheckpointSummary[]>;
     listScopes(): Promise<string[]>;
+    /** The listing faces' disclosure: a row read past a damage is reported through the corrupt-read seat, named by its non-secret
+     *  identity (never its token). */
+    private listingDisclose;
+    listOverdue(query: CheckpointOverdueQuery): Promise<CheckpointPage<CheckpointSummary, CheckpointOverdueCursor>>;
+    listBySession(query: CheckpointSessionQuery): Promise<CheckpointPage<CheckpointRowRead, CheckpointSessionCursor>>;
     /** Force a compaction now (test/inspection). The snapshot rewrite + RB-167 closeForSwap swap that
      *  makes `replay` read the full state from the snapshot alone is the base's {@link LedgerCore.compact}. */
     compactNow(): void;

package/dist/stores/file/checkpoint-store.js

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "../../core/checkpoint-execution-record.js";
-import { appendPendingSteer, CheckpointError, checkpointOccMatches, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
+import { checkpointHolderMatches, checkpointOccMatches, checkpointRevOf } from "../../core/checkpoint-generation.js";
+import { appendPendingSteer, CheckpointError, checkpointRowMatches, encodeAtFidelity, summarizeCheckpoint, validatePendingSteer, winnerFromOutcome, } from "../../core/checkpoint-store.js";
+import { checkpointDeadlinePassed, deleteSessionRowsAtStart, readCheckpointOverdueQuery, readCheckpointSessionQuery, selectOverduePage, selectSessionPage, } from "../../core/checkpoint-queries.js";
 import { SharedLedgerTable } from "./shared-ledger.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
@@ -10,6 +12,7 @@ const CHECKPOINT_LEDGER_EVENT_REGISTRY = {
     reopen: true,
     execution: true,
     expire: true,
+    delete: true,
     steer_append: true,
 };
 const KNOWN_CHECKPOINT_LEDGER_EVENTS = new Set(Object.keys(CHECKPOINT_LEDGER_EVENT_REGISTRY));
@@ -45,6 +48,9 @@ function applyCheckpointEvent(cps, ev) {
         case "expire":
             cp.status = "expired";
             break;
+        case "delete":
+            cps.delete(ev.token);
+            break;
         case "steer_append": {
             const queue = cp.state.pendingSteerQueue ?? [];
             if (!queue.some((e) => e.inputId === ev.entry.inputId))
@@ -82,8 +88,8 @@ const checkpointLedgers = new SharedLedgerTable({
 export class FileCheckpointStore {
     durability = "durable";
     fidelity = "json";
-    redecision = { reopen: true };
     execution = { outcome: true };
+    holderIsCurrent;
     fsyncEnabled;
     compactEvery;
     ledger;
@@ -97,6 +103,9 @@ export class FileCheckpointStore {
     constructor(root, opts = {}) {
         assertAdoptionBootGate(root, "FileCheckpointStore");
         this.fsyncEnabled = opts.fsync !== false;
+        this.holderIsCurrent = opts.holderIsCurrent;
+        if (opts.holderIsCurrent !== undefined)
+            this.fence = Object.freeze({ holder: true });
         this.compactEvery = opts.compactEvery ?? 1000;
         this.discloseCorrupt = guardCorruptSink(opts.onCorruptRead);
         const dir = join(root, "checkpoints");
@@ -108,6 +117,15 @@ export class FileCheckpointStore {
             ledgerPath: this.ledgerPath,
             snapshotPath: join(dir, "checkpoints.snapshot.jsonl"),
         });
+        const headOf = opts.sessionHeadOf;
+        if (headOf !== undefined) {
+            this.deleteSessionCheckpoints = (sessionId, guard) => deleteSessionRowsAtStart(this.cps, sessionId, guard, headOf, (token, row) => this.withLock(token, () => {
+                if (this.cps.get(token) !== row)
+                    return false;
+                this.commit({ t: "delete", token }, true);
+                return true;
+            }));
+        }
     }
     withLock(token, fn) {
         return this.ledger.withLock(token, fn);
@@ -144,8 +162,11 @@ export class FileCheckpointStore {
             if (!checkpointOccMatches(cp, expect)) {
                 return false;
             }
+            if (!checkpointHolderMatches(expect, this.holderIsCurrent)) {
+                return false;
+            }
             const winner = winnerFromOutcome(outcome);
-            const rev = (cp.rev ?? 0) + 1;
+            const rev = checkpointRevOf(cp) + 1;
             this.commit({ t: "resolve", token, rev, resolvedOutcome: winner }, true);
             if (this.fault === "resolve-after-commit") {
                 this.fault = null;
@@ -172,7 +193,7 @@ export class FileCheckpointStore {
             if (!checkpointRowMatches(cp, scope, "resolved") || checkpointExecutionRecorded(cp)) {
                 return false;
             }
-            const rev = (cp.rev ?? 0) + 1;
+            const rev = checkpointRevOf(cp) + 1;
             this.commit({ t: "reopen", token, rev, reason }, true);
             return true;
         });
@@ -204,7 +225,7 @@ export class FileCheckpointStore {
     }
     async reap(scope, cutoff) {
         let n = 0;
-        const deadlinePassed = (deadline) => deadline !== undefined && (Number.isFinite(deadline) ? deadline <= cutoff : true);
+        const deadlinePassed = (deadline) => checkpointDeadlinePassed(deadline, cutoff);
         const candidates = [...this.cps.values()].filter((cp) => cp.scope === scope && cp.status === "pending" && deadlinePassed(cp.deadline));
         for (const cp of candidates) {
             const won = await this.withLock(cp.token, () => {
@@ -222,8 +243,7 @@ export class FileCheckpointStore {
         return n;
     }
     async listByScope(scope) {
-        const sink = this.discloseCorrupt;
-        const disclose = sink === undefined ? undefined : (sentence) => sink({ kind: "file", path: this.ledgerPath, reason: sentence });
+        const disclose = this.listingDisclose();
         const out = [];
         for (const cp of this.cps.values()) {
             if (cp.scope === scope && cp.status === "pending")
@@ -238,6 +258,17 @@ export class FileCheckpointStore {
                 out.add(cp.scope);
         return [...out];
     }
+    listingDisclose() {
+        const sink = this.discloseCorrupt;
+        return sink === undefined ? undefined : (sentence) => sink({ kind: "file", path: this.ledgerPath, reason: sentence });
+    }
+    async listOverdue(query) {
+        const disclose = this.listingDisclose();
+        return selectOverduePage(this.cps.entries(), readCheckpointOverdueQuery(query), (cp) => summarizeCheckpoint(cp, disclose), disclose);
+    }
+    async listBySession(query) {
+        return selectSessionPage(this.cps.entries(), readCheckpointSessionQuery(query), (cp) => structuredClone(cp), this.listingDisclose());
+    }
     compactNow() {
         this.ledger.compact();
     }

package/dist/stores/file/file-history-store.js

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, closeSync, existsSync, fsyncSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { thrownText } from "../../core/thrown-value.js";
-import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, caughtFault, DAMAGED_RECORD, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
+import { applyFileRestoreViaEnv, boundaryPublishVerdict, worldStillMatchesMint, annulProofFailure, captureFileBackupViaEnv, modeProvenDifferent, previewFileDelta, describeTrackKey, fileHistoryExportDigest, caughtFault, DAMAGED_RECORD, resolveTrackKey, trackKeyOf, validateFileHistoryExport, } from "../../core/file-history-store.js";
 import { fileHistoryBoundariesToKeep, resolveFileHistoryRetention } from "../../core/file-history-retention.js";
 import { atomicWriteFile, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
@@ -481,9 +481,8 @@ export class FileFileHistoryStore {
                 return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} has since been served to another edit of the same path — it is that edit's baseline now, not a retractable mint` } };
             }
             const proof = verify === undefined ? undefined : await worldStillMatchesMint(verify.env, absPath, root, rec.baseAvailable, rec.versions[0]?.blobHash ?? null, verify.signal);
-            if (proof !== undefined && !proof.unchanged) {
-                return { ok: false, error: { code: "conflict", message: `first-touch record for ${absPath} is NOT retractable: ${proof.reason} — the write this retraction compensates for may have changed the file` } };
-            }
+            if (proof !== undefined && proof.verdict !== "unchanged")
+                return annulProofFailure(proof, absPath);
             const fresh = this.readTrackedState(scope);
             if (fresh.corrupt)
                 return { ok: false, error: { code: "track_failed", message: `file history for scope "${scope}" became unreadable — the record was left in place`, ...fresh.fault } };
@@ -723,7 +722,7 @@ export class FileFileHistoryStore {
                 let targetVersion = boundary.get(key);
                 if (targetVersion === undefined) {
                     if (!rec.baseAvailable) {
-                        ledger.refused.push({ path: key, reason: "base_unavailable" });
+                        ledger.refused.push({ path: key, reason: "base_unavailable", class: "base_unavailable" });
                         continue;
                     }
                     targetVersion = 1;
@@ -735,7 +734,7 @@ export class FileFileHistoryStore {
                 }
                 const resolved = resolveTrackKey(root, key, descriptorOf(rec));
                 if (!resolved.ok) {
-                    ledger.refused.push({ path: key, reason: resolved.reason });
+                    ledger.refused.push({ path: key, reason: resolved.reason, class: resolved.class });
                     continue;
                 }
                 let target;
@@ -777,7 +776,7 @@ export class FileFileHistoryStore {
                 else if (applied.outcome === "identical")
                     ledger.identicalSkipped.push(key);
                 else if (applied.outcome === "refused")
-                    ledger.refused.push({ path: key, reason: applied.reason });
+                    ledger.refused.push({ path: key, reason: applied.reason, class: applied.class });
                 else
                     ledger.failed.push({ path: key, reason: applied.reason });
                 if ((applied.outcome === "applied" || applied.outcome === "identical") && applied.modeNotPreserved === true)
@@ -1148,6 +1147,14 @@ export class FileFileHistoryStore {
             const shaped = validateFileHistoryExport(data);
             if (!shaped.ok)
                 return shaped;
+            for (const b of data.boundaries) {
+                try {
+                    historyPathComponent(b.entryId);
+                }
+                catch (err) {
+                    return { ok: false, error: { code: "unsupported_format", message: `importHistory refused a boundary entry id this backend cannot hold as a record name: ${thrownText(err)} — nothing was fetched or published` } };
+                }
+            }
             const target = await this.importTargetOf(scope, data, "before");
             if (typeof target === "object")
                 return target;
@@ -1165,7 +1172,7 @@ export class FileFileHistoryStore {
             return await this.runImport(scope, data, srcGetBlob, importJournal, identicalRepublish);
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
+            return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
     }
     async runImport(scope, data, srcGetBlob, importJournal, identicalRepublish) {
@@ -1192,12 +1199,12 @@ export class FileFileHistoryStore {
                         bytes = await srcGetBlob(v.blobHash);
                     }
                     catch (err) {
-                        return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
+                        return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} fetch failed: ${thrownText(err)}`, ...caughtFault(err) } };
                     }
                     if (bytes === undefined)
                         return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} is missing — the envelope's graph cannot be completed, so nothing is published` } };
                     if (createHash("sha256").update(bytes).digest("hex") !== v.blobHash) {
-                        return { ok: false, error: { code: "unsupported_format", message: `source blob ${v.blobHash} fails content-address integrity — refused, nothing published` } };
+                        return { ok: false, error: { code: "adopt_failed", message: `source blob ${v.blobHash} fails content-address integrity — refused, nothing published` } };
                     }
                     this.putBlob(v.blobHash, bytes);
                 }
@@ -1251,7 +1258,7 @@ export class FileFileHistoryStore {
             return { ok: true };
         }
         catch (err) {
-            return { ok: false, error: { code: "unsupported_format", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
+            return { ok: false, error: { code: "adopt_failed", message: `importHistory failed: ${thrownText(err)}`, ...caughtFault(err) } };
         }
         finally {
             safeRm(importJournal);

package/dist/stores/file/index.js

@@ -62,7 +62,8 @@ export class FileStorageBackend {
             this.fileSessions = repo;
             this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable", placements: { subagent: { durability: "durable" } } });
             this.sessionStore = this.ttl;
-            this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead });
+            const sessionHeadOf = this.ttl.headOf;
+            this.fileCheckpoints = new FileCheckpointStore(this.root, { ...opts.checkpoint, ...corruptRead, ...(sessionHeadOf !== undefined ? { sessionHeadOf } : {}) });
             built.push(() => this.fileCheckpoints.close());
             this.checkpointStore = this.fileCheckpoints;
             this.fileMemory = new FileMemoryStore(this.root, opts.embedder ? { embedder: opts.embedder } : {});

package/dist/stores/file/mailbox-store.d.ts

@@ -1,4 +1,4 @@
-import { type MailboxAckResult, type MailboxAppendMessage, type MailboxLease, type MailboxStore } from "../../core/mailbox-store.js";
+import { type MailboxAckResult, type MailboxAppendMessage, type MailboxLease, type MailboxDecisionOutcome, type MailboxDecision, type MailboxStore } from "../../core/mailbox-store.js";
 import { type CorruptReadInfo } from "./corrupt-read-sink.js";
 /** The waiter's refusal when a box lock stays held by a LIVE process past `lockWaitMs`. Carried as
  *  `.code` on a plain Error (consumers branch on the string); the message names the lock and the holder. */
@@ -113,6 +113,7 @@ export declare class FileMailboxStore implements MailboxStore {
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<MailboxAckResult>;
+    moveDecision(scope: string, handle: string, seq: number, expect: MailboxDecision | undefined, next: MailboxDecision): Promise<MailboxDecisionOutcome>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
     peekCount(scope: string, handle: string): Promise<number>;
     drop(scope: string, handle: string): Promise<void>;

package/dist/stores/file/mailbox-store.js

@@ -2,7 +2,7 @@ import { join, resolve, sep } from "node:path";
 import { createHash, randomBytes } from "node:crypto";
 import { assertRetentionPolicy } from "../../core/retention-policy.js";
 import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { detachMailboxMessage, newestSentAt, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
+import { assertMailboxDecisionMove, detachMailboxMessage, newestSentAt, readStoredMailboxDecision, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
 import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { physicalPathOf } from "../../core/physical-path.js";
@@ -478,6 +478,19 @@ export class FileMailboxStore {
             return { acked: true };
         });
     }
+    async moveDecision(scope, handle, seq, expect, next) {
+        assertMailboxDecisionMove(seq, expect, next);
+        return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
+            const b = this.load(scope, handle);
+            const m = b.messages.find((x) => x.seq === seq);
+            if (m === undefined)
+                return { ok: false, current: "gone" };
+            if (m.decision !== expect)
+                return { ok: false, current: m.decision ?? "unset" };
+            this.commit(b, this.boxPath(scope, handle), { t: "decision", seq, state: next });
+            return { ok: true };
+        });
+    }
     async releaseLease(scope, handle, owner) {
         return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
             const b = this.load(scope, handle);
@@ -592,12 +605,19 @@ const MAILBOX_EVENT_JUDGE = {
             return typeof ev.owner === "string" && num(ev.maxSeq) && num(ev.expiresAt);
         if (ev.t === "ack")
             return num(ev.upToSeq);
+        if (ev.t === "decision")
+            return num(r.seq) && typeof r.state === "string";
         return ev.t === "release" && typeof ev.owner === "string";
     },
     what: "a mailbox record is not one of this box's events — an unknown tag, or a known tag whose payload is missing",
 };
 function applyEvent(b, ev) {
     if (ev.t === "append") {
+        const decision = readStoredMailboxDecision(ev.m.decision);
+        if (decision === undefined)
+            delete ev.m.decision;
+        else
+            ev.m.decision = decision;
         b.messages.push(ev.m);
         if (ev.m.seq >= b.nextSeq)
             b.nextSeq = ev.m.seq + 1;
@@ -613,6 +633,11 @@ function applyEvent(b, ev) {
         if (b.lease !== undefined && b.lease.maxSeq <= ev.upToSeq)
             b.lease = undefined;
     }
+    else if (ev.t === "decision") {
+        const m = b.messages.find((x) => x.seq === ev.seq);
+        if (m !== undefined)
+            m.decision = readStoredMailboxDecision(ev.state) ?? "held";
+    }
     else if (b.lease?.owner === ev.owner) {
         b.lease = undefined;
     }