@sema-agent/core 5.47.0 → 5.49.0

package/dist/index.js

@@ -28,7 +28,7 @@ export { looksDegenerate, inspectDegenerate, trimDegenerateTail } from "./brain/
 export { computeCostMicroUsd, modelCostToPricing, } from "./core/pricing.js";
 export { cacheFamilyOf, promptTokensOf, uncachedInputTokensOf } from "./core/runner/usage-accounting.js";
 export { emitTrace } from "./core/trace.js";
-export { InMemoryStrategyStore } from "./core/strategy-store.js";
+export { InMemoryStrategyStore, seedStrategies, } from "./core/strategy-store.js";
 export { createSqlTool, validateReadOnlySql } from "./tools/sql.js";
 export { runWithTeacher, parseTeacherAdvice, TEACHER_PROMPT, } from "./agents/teacher.js";
 export { runWithVerification, resumeWithVerification, verifyCompleted, runDeveloperTask, VERIFICATION_PROMPT, STATIC_VERIFICATION_PROMPT, VerdictSchema, } from "./agents/verify.js";
@@ -81,7 +81,7 @@ export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
 export { captureManifest, applyManifest } from "./core/file-snapshot-store.js";
-export { FileStorageBackend, FileSessionRepo, FileCheckpointStore, FileMemoryStore, FileToolResultStore, FileSessionPolicyStore, FileFileSnapshotStore, FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult, resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock, atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog, } from "./stores/file/index.js";
+export { FileStorageBackend, FileSessionRepo, FileCheckpointStore, FileMemoryStore, FileToolResultStore, FileSessionPolicyStore, FileFileSnapshotStore, FileStrategyStore, FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult, resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock, atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog, } from "./stores/file/index.js";
 export { CacheBreakDetector } from "./core/cache-break-detector.js";
 export { maybeCompact } from "./core/auto-compaction.js";
 export { brainToRuntime } from "./core/runtime.js";
@@ -90,7 +90,7 @@ export { createFsWriteGatePolicy } from "./core/fs-write-gate-policy.js";
 export { RETIRED_TOOL_NAMES } from "./core/tool-name-aliases.js";
 export { DEFAULT_SUBAGENT_TOOL_NAME } from "./agents/subagent.js";
 export { renderTaskNotificationXml, taskNotificationDedupKey, isDelegatedAgentTerminal, SystemInjectionQueue, } from "./core/task-notification.js";
-export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, } from "./core/wiring-manifest.js";
+export { describeStaticWiring, deriveWiringManifest, deriveAskEffective, resolveDeclaredDurability, resolveSubagentTranscriptTier, resolveAskSeamForm, resolveQuestionSeam, countElicitOptIns, } from "./core/wiring-manifest.js";
 export { probeParkRoundTrip, durableParkGapOf, durableParkGapFor, PARK_SELFCHECK_SCOPE_PREFIX, } from "./core/park-selfcheck.js";
 export {} from "./core/checkpoint-store.js";
 export {} from "./core/checkpoint-store.js";
@@ -193,10 +193,11 @@ export { summarizeRedactions } from "./core/untrusted-egress.js";
 export { MemoryRosterStore, FileRosterStore } from "./agents/roster-store.js";
 export { CONFIG_CATALOG_VERSION, describeConfigCatalog, resolveEffectiveConfig, } from "./config/catalog.js";
 export { normalizeAgentName } from "./core/task-registry.js";
+export { DELEGATION_MAX_CONCURRENT_DEFAULT, DELEGATION_MAX_PER_SESSION_DEFAULT, ORPHAN_ADOPT_WINDOW_MS_DEFAULT, ORPHAN_ADOPT_MAX_DEFAULT, SUBAGENT_TRANSCRIPT_RETENTION_DAYS_DEFAULT, } from "./config/defaults.js";
 export { COORDINATOR_ROLE_PROMPT, TEAMMATE_COMMUNICATION_ADDENDUM, TEAMMATE_TASK_LIST_ADDENDUM } from "./prompts/coordinator.js";
-export { createSubagentTool, FORK_SUBAGENT_TYPE, GENERAL_PURPOSE_SUBAGENT_TYPE, agentWhenToUseText, FORK_DIRECTIVE_FRAME, SUBAGENT_SYSTEM_NOTE, } from "./agents/subagent.js";
+export { createSubagentTool, FORK_SUBAGENT_TYPE, GENERAL_PURPOSE_SUBAGENT_TYPE, agentWhenToUseText, FORK_DIRECTIVE_FRAME, SUBAGENT_SYSTEM_NOTE, resolveDelegationEntryCaps, } from "./agents/subagent.js";
 export { getSessionRetainLedger, releaseSessionRetainLedger, } from "./agents/retain-ledger.js";
-export { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "./agents/send-message-tool.js";
+export { createSendMessageTool, createAgentContinuationVerb, SEND_MESSAGE_TOOL_NAME } from "./agents/send-message-tool.js";
 export { createPeerAdmission, peerAdmissionFor, judgePeerAdmission, resolvePeerAdmissionConfig, PEER_ADMISSION_DEFAULTS, PEER_HOP_CHAIN_WINDOW, PEER_MESSAGE_NOTICE, createPeerSelfRef, createPeerInboundChainRef, peerAxisToken, appendHopToken, } from "./agents/peer-admission.js";
 export { createAgentTranscriptTool, AGENT_TRANSCRIPT_TOOL_NAME, } from "./agents/agent-transcript-tool.js";
 export { defineAgent } from "./agents/agent-definition.js";

package/dist/internal/harness-types.d.ts

@@ -14,3 +14,4 @@ export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/typ
 export type { ActiveWorktreeSession, WorkspaceState } from "../engine/harness/types.js";
 export type { GitAnnouncementKind, GitAnnouncementState } from "../engine/harness/types.js";
 export type { SessionForkOptions } from "../engine/harness/types.js";
+export type { SessionPlacementRecord, SessionCreateOptions } from "../engine/harness/types.js";

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

@@ -5,6 +5,12 @@ import { applyManifest, captureManifest, DEFAULT_SNAPSHOT_BOUNDS, } from "../../
 import { canonicalStoreKey, ensureDir, sanitizePathComponent, sanitizeScope, writeThenLink } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
 const sharedInFlight = new Map();
+function containSinkThenable(r) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, () => {
+        });
+    }
+}
 export class FileFileSnapshotStore {
     base;
     blobsDir;
@@ -37,7 +43,7 @@ export class FileFileSnapshotStore {
     }
     disclose(path, reason) {
         try {
-            this.onCorruptRead?.({ path, reason });
+            containSinkThenable(this.onCorruptRead?.({ path, reason }));
         }
         catch {
         }

package/dist/stores/file/index.d.ts

@@ -4,6 +4,10 @@ import type { ToolResultStore } from "../../core/tool-result-store.js";
 import { type EvictPolicy } from "../../core/session-store.js";
 import type { SessionStore } from "../../core/session.js";
 import { type FileCheckpointStoreOptions } from "./checkpoint-store.js";
+import type { StrategyStore } from "../../core/strategy-store.js";
+import type { BackgroundAgentStore } from "../../core/background-agent-store.js";
+import type { MailboxStore } from "../../core/mailbox-store.js";
+import type { RosterStore } from "../../agents/roster-store.js";
 import type { SessionPolicyStore } from "../../core/session-policy-store.js";
 import type { FileSnapshotStore } from "../../core/file-snapshot-store.js";
 import type { WorkflowJournalStore } from "../../core/workflow-journal-store.js";
@@ -16,6 +20,7 @@ export { FileSessionPolicyStore, type FileSessionPolicyStoreOptions, type Sessio
 export { FileFileSnapshotStore, type FileFileSnapshotStoreOptions } from "./file-snapshot-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
+export { FileStrategyStore, type FileStrategyStoreOptions } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, type AdoptionErrorCode, type AdoptionSource, type AdoptionReport, type AdoptionReceipt, type AdoptionLegReport, type AffectedDeploymentConfig, type RootAdoptionFile, } from "./adoption/marker.js";
@@ -76,9 +81,8 @@ export interface FileStorageBackendOptions {
      * Reach TODAY: {@link FileStorageBackend.sessionPolicyStore} (rules read as ABSENT ⇒ an unconstrained
      * task), {@link FileStorageBackend.sessionStore}'s repo (a session listing that silently omits what it
      * could not read) and {@link FileStorageBackend.fileSnapshotStore} (a snapshot/scope read as missing,
-     * and a blob GC that aborted). The roster and CC-mailbox stores also carry the seat, but a deployment
-     * builds those itself and passes the sink directly. A store that grows the seat later is wired here in
-     * the same constructor.
+     * and a blob GC that aborted). The aggregated roster and mailbox stores receive the same sink. A
+     * store that grows the seat later is wired here in the same constructor.
      *
      * The payload is the UNION shape ({@link FileStorageCorruptReadInfo}): `path` + `reason` always,
      * with the session-policy face's `sessionId`/`principal` present only when the reading store keys by
@@ -125,6 +129,24 @@ export declare class FileStorageBackend {
      *  `RunnerDeps.usageWindowStore` so a deployment's `usageWindows` survive a restart (an in-memory
      *  ledger silently re-grants every allowance on every boot). */
     readonly usageWindowStore: UsageWindowStore;
+    /** design/151 S1a / subagent transcript persistence — the durable background-agent execution
+     *  ledger over the same data root. Wire into BOTH `RunnerDeps.backgroundAgentStore` AND (for a
+     *  deployment-composed Agent tool) `SubagentToolOptions.background.agentStore` — SAME instance
+     *  (the RB-37 pairing discipline). Aggregated here so the TOC full-persistence assembly is one
+     *  constructor, the same reason the session/checkpoint/tool-result trio are. */
+    readonly backgroundAgentStore: BackgroundAgentStore;
+    /** design/151 §7 S3c — the durable SendMessage mailbox (tier-3 parking lane), same data root.
+     *  Wire into `RunnerDeps.mailboxStore` (single-instance pairing, same as above). */
+    readonly mailboxStore: MailboxStore;
+    /** File-backed teacher-mode strategy repository (`root/strategies`) — pass as
+     *  `TeacherConfig.strategyStore` (with a `scope`) so escalation strategies survive a restart;
+     *  the in-memory default forgets everything each process, which zeroes the cross-session reuse
+     *  the repository exists for. Aggregated here so the TOC full-persistence assembly stays one
+     *  constructor (the same half-wiring hazard as the delegation trio). */
+    readonly strategyStore: StrategyStore;
+    /** design/147 S1c — the durable name→agent roster (layer 0.5 resolution), `root/roster.json`.
+     *  Wire into `RunnerDeps.rosterStore` so name-addressing survives a restart alongside the rows. */
+    readonly rosterStore: RosterStore;
     /**
      * design/84 Seam B (TOC) — the per-scope consolidation lock for `consolidateScope`'s `acquire` injection
      * point: `consolidateScope(scope, { store: backend.memoryStore, llm, acquire: backend.consolidationLock })`.
@@ -133,6 +155,8 @@ export declare class FileStorageBackend {
      */
     readonly consolidationLock: (scope: string) => (() => void) | undefined;
     private readonly lock;
+    private readonly fileAgentRows;
+    private readonly fileMailbox;
     private readonly fileCheckpoints;
     private readonly fileMemory;
     private readonly ttl;

package/dist/stores/file/index.js

@@ -11,6 +11,10 @@ import { FileSessionPolicyStore } from "./session-policy-store.js";
 import { FileFileSnapshotStore } from "./file-snapshot-store.js";
 import { FileWorkflowJournalStore } from "./workflow-journal-store.js";
 import { FileUsageWindowStore } from "./usage-window-store.js";
+import { FileBackgroundAgentStore } from "./background-agent-store.js";
+import { FileMailboxStore } from "./mailbox-store.js";
+import { FileRosterStore } from "../../agents/roster-store.js";
+import { FileStrategyStore } from "./strategy-store.js";
 export { FileCheckpointStore } from "./checkpoint-store.js";
 export { FileMemoryStore } from "./memory-store.js";
 export { FileSessionRepo } from "./session-store.js";
@@ -19,6 +23,7 @@ export { FileSessionPolicyStore } from "./session-policy-store.js";
 export { FileFileSnapshotStore } from "./file-snapshot-store.js";
 export { FileWorkflowJournalStore, MAX_JOURNAL_RESULT_BYTES, oversizeJournalResult } from "./workflow-journal-store.js";
 export { FileUsageWindowStore } from "./usage-window-store.js";
+export { FileStrategyStore } from "./strategy-store.js";
 export { resolveDataRoot, sanitizeScope, sanitizePathComponent, createFileConsolidationLock } from "./fs-atomic.js";
 export { atomicWriteFile, writeThenLink, ensureDir, readJsonlRecords, AppendLog } from "./fs-atomic.js";
 export { AdoptionError, assertAdoptionBootGate, readRootAdoptionFile, writeRootAdoptionFile, ROOT_ADOPTION_FILE, } from "./adoption/marker.js";
@@ -33,8 +38,14 @@ export class FileStorageBackend {
     fileSnapshotStore;
     workflowJournalStore;
     usageWindowStore;
+    backgroundAgentStore;
+    mailboxStore;
+    strategyStore;
+    rosterStore;
     consolidationLock;
     lock;
+    fileAgentRows;
+    fileMailbox;
     fileCheckpoints;
     fileMemory;
     ttl;
@@ -49,7 +60,7 @@ export class FileStorageBackend {
             const corruptRead = opts.onCorruptRead !== undefined ? { onCorruptRead: opts.onCorruptRead } : undefined;
             const repo = new FileSessionRepo(this.root, corruptRead);
             this.fileSessions = repo;
-            this.ttl = new TtlSessionStore({ repo, evict: opts.evict ?? "forget", durability: "durable" });
+            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);
             this.checkpointStore = this.fileCheckpoints;
@@ -61,6 +72,20 @@ export class FileStorageBackend {
             this.fileWorkflowJournal = new FileWorkflowJournalStore(this.root);
             this.workflowJournalStore = this.fileWorkflowJournal;
             this.usageWindowStore = new FileUsageWindowStore(this.root);
+            this.fileAgentRows = new FileBackgroundAgentStore(this.root);
+            this.backgroundAgentStore = this.fileAgentRows;
+            this.fileMailbox = new FileMailboxStore(this.root, corruptRead ?? {});
+            this.mailboxStore = this.fileMailbox;
+            this.rosterStore = new FileRosterStore(join(this.root, "roster.json"), corruptRead ?? {});
+            const strategiesRoot = join(this.root, "strategies");
+            this.strategyStore = new FileStrategyStore({
+                root: strategiesRoot,
+                ...(opts.onCorruptRead !== undefined
+                    ? {
+                        onIncident: (i) => opts.onCorruptRead?.({ path: i.path ?? strategiesRoot, reason: `strategy ${i.op}: ${i.error}` }),
+                    }
+                    : {}),
+            });
             this.consolidationLock = createFileConsolidationLock(join(this.root, "consolidation-locks"));
         }
         catch (err) {
@@ -87,6 +112,16 @@ export class FileStorageBackend {
         }
         this.fileMemory.close();
         this.fileWorkflowJournal.dispose();
+        try {
+            this.fileAgentRows.close();
+        }
+        catch {
+        }
+        try {
+            this.fileMailbox.close();
+        }
+        catch {
+        }
         this.lock.release();
     }
 }

package/dist/stores/file/session-policy-store.d.ts

@@ -1,17 +1,4 @@
 import { type PutRulesOptions, type SessionPermissionRules, type SessionPolicyStore, type SessionRulesRecord, type StoredSessionRules } from "../../core/session-policy-store.js";
-/**
- * design/99 §E6 — file-backed {@link SessionPolicyStore} for the local (TOC) backend: ONE JSON file per
- * `(sessionId, principal)`, semantics **byte-for-byte identical to `InMemorySessionPolicyStore`** (the
- * cross-backend equivalence contract). CAS-rev OCC + tighten-only reuse the SAME pure helpers
- * (`loosenReasons`/`normalizeRules`/`stripRev`) as core — no re-implemented rule logic that could drift.
- *
- * Atomicity: the file backend is single-process (the `FileStorageBackend` boot lock guarantees ONE writer per
- * data dir), and `getRules`/`putRules` read-check-write SYNCHRONOUSLY (no await between the rev read and the
- * atomic write), so the read-modify-write is atomic in the one event loop — exactly the InMemory store's premise.
- * Cross-process CORRECT concurrency is the Pg/TiDB backend's job (a CAS WHERE clause), by design.
- */
-/** Coordinates of one corrupt-treated-as-absent policy read (the {@link FileSessionPolicyStoreOptions.onCorruptRead}
- *  payload). Named rather than inline so the backend option that forwards it names the SAME shape. */
 export interface SessionPolicyCorruptReadInfo {
     /** The session whose read observed the corrupt row. On the enumeration face this is the session being
      *  ENUMERATED — a corrupt row's own `__sid` is by definition unreadable, so it cannot be attributed. */

package/dist/stores/file/session-policy-store.js

@@ -3,6 +3,12 @@ import { join } from "node:path";
 import { loosenReasons, normalizeRules, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
 import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
+function containSinkThenable(r) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, () => {
+        });
+    }
+}
 export class FileSessionPolicyStore {
     dir;
     onCorruptRead;
@@ -18,7 +24,7 @@ export class FileSessionPolicyStore {
     }
     disclose(info) {
         try {
-            this.onCorruptRead?.(info);
+            containSinkThenable(this.onCorruptRead?.(info));
         }
         catch {
         }

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

@@ -1,4 +1,5 @@
-import type { Session, SessionForkOptions, SessionMetadata, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
+import type { Session, SessionCreateOptions, SessionForkOptions, SessionMetadata, SessionPlacementRecord, SessionRepo, SessionTreeEntry } from "../../internal/harness.js";
+import type { PlacedSessionRow } from "../../core/session.js";
 export interface FileSessionRepoOptions {
     /**
      * Disclosure sink for a durable read this repo treats as ABSENT (ruled 2026-08-03). Same name and
@@ -28,7 +29,10 @@ export declare class FileSessionRepo implements SessionRepo {
     private readonly joined;
     constructor(root: string, opts?: FileSessionRepoOptions);
     /** The one delivery point for {@link FileSessionRepoOptions.onCorruptRead}; swallow-guarded here so
-     *  no call site has to remember. */
+     *  no call site has to remember. The sink seat is void-typed but a host may hand it an async
+     *  function — an async sink's rejection is observed off its returned thenable (same containment
+     *  as the strategy store's incident sink), so neither a sync throw nor an async rejection can
+     *  re-introduce the failure mode the fail-open avoids. */
     private disclose;
     private pathFor;
     /** Read + torn-tail-recover a session file into (meta, entries); a missing file → not_found. */
@@ -47,11 +51,24 @@ export declare class FileSessionRepo implements SessionRepo {
      * means a stale holder can never revoke the rebuilt entry.
      */
     dispose(): Promise<void>;
-    create(options?: {
-        id?: string;
-    }): Promise<Session>;
+    create(options?: SessionCreateOptions): Promise<Session>;
     open(metadata: SessionMetadata): Promise<Session>;
     list(): Promise<SessionMetadata[]>;
+    /**
+     * Subagent transcript persistence — the PLACED partition's own enumeration (the joint reap's
+     * partition-leg input; `TtlSessionStore` re-exposes it verbatim). Age (`olderThanMs`) is judged on
+     * the session FILE's mtime — the transcript's last append — falling back to `placedAt` when the
+     * stat fails (mtime is also the CC orphan-adoption window's basis, so the two age reads agree).
+     * Rows missing either `(scope, handle)` join half return the honest `tupleIncomplete` variant
+     * (consumers fail closed on it — never age-reaped, see the SessionStore contract).
+     */
+    listPlaced(kind: "subagent", opts?: {
+        olderThanMs?: number;
+        scope?: string;
+    }): Promise<PlacedSessionRow[]>;
+    /** Cheap placement probe for one id (the TtlSessionStore's cold-cache release consults it so the
+     *  placed real-deletion obligation holds after a restart). `undefined` = missing file OR unplaced. */
+    placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
     delete(metadata: SessionMetadata): Promise<void>;
     fork(sourceMetadata: SessionMetadata, options?: SessionForkOptions): Promise<Session>;
     /** 2c session-sync ([275], the FILE half of [266]②): the FULL oldest-first log for export. The file backend

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

@@ -1,8 +1,14 @@
-import { existsSync, readdirSync, rmSync } from "node:fs";
+import { existsSync, readdirSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { BaseSessionStorage, StoredSession, SessionError, getEntriesToFork, uuidv7, validateEntriesForImport, } from "../../internal/harness.js";
 import { canonicalStoreKey, AppendLog, atomicWriteFile, ensureDir, readJsonlRecords, sanitizePathComponent } from "./fs-atomic.js";
 import { assertAdoptionBootGate } from "./adoption/marker.js";
+function containSinkThenable(r) {
+    if (typeof r?.then === "function") {
+        r.then(undefined, () => {
+        });
+    }
+}
 const SUFFIX = ".jsonl";
 const sharedSessionStorages = new Map();
 const sessionStorageFinalizer = new FinalizationRegistry(({ canonical, log }) => {
@@ -67,7 +73,7 @@ export class FileSessionRepo {
     }
     disclose(path, reason) {
         try {
-            this.onCorruptRead?.({ path, reason });
+            containSinkThenable(this.onCorruptRead?.({ path, reason }));
         }
         catch {
         }
@@ -83,18 +89,20 @@ export class FileSessionRepo {
         const lines = readJsonlRecords(path, (info) => this.disclose(info.path, info.reason));
         let createdAt = "";
         let forkedFrom;
+        let placement;
         const entries = [];
         for (const line of lines) {
             if (line.kind === "meta") {
                 createdAt = line.createdAt;
                 forkedFrom = line.forkedFrom;
+                placement = line.placement;
             }
             else
                 entries.push(line.entry);
         }
-        return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), entries };
+        return { createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}), entries };
     }
-    storage(id, createdAt, entries, forkedFrom) {
+    storage(id, createdAt, entries, forkedFrom, placement) {
         const canonical = canonicalStoreKey(this.pathFor(id));
         const live = sharedSessionStorages.get(canonical)?.deref();
         if (live !== undefined) {
@@ -103,7 +111,7 @@ export class FileSessionRepo {
             return live;
         }
         const log = new AppendLog(this.pathFor(id));
-        const created = new FileSessionStorage(log, { id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) }, entries, canonical);
+        const created = new FileSessionStorage(log, { id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}), ...(placement !== undefined ? { placement } : {}) }, entries, canonical);
         sharedSessionStorages.set(canonical, new WeakRef(created));
         created.addHolder(this);
         this.joined.set(canonical, new WeakRef(created));
@@ -128,15 +136,16 @@ export class FileSessionRepo {
         const path = this.pathFor(id);
         if (!existsSync(path)) {
             evictSharedSessionStorage(canonicalStoreKey(path));
-            atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", id, createdAt })}\n`);
-            return new StoredSession(this.storage(id, createdAt, []));
+            const placement = options.placement !== undefined ? { ...options.placement, placedAt: options.placement.placedAt ?? Date.now() } : undefined;
+            atomicWriteFile(this.tmpDir, path, `${JSON.stringify({ kind: "meta", id, createdAt, ...(placement !== undefined ? { placement } : {}) })}\n`);
+            return new StoredSession(this.storage(id, createdAt, [], undefined, placement));
         }
-        const { createdAt: existingCreatedAt, forkedFrom, entries } = this.read(id);
-        return new StoredSession(this.storage(id, existingCreatedAt || createdAt, entries, forkedFrom));
+        const { createdAt: existingCreatedAt, forkedFrom, placement, entries } = this.read(id);
+        return new StoredSession(this.storage(id, existingCreatedAt || createdAt, entries, forkedFrom, placement));
     }
     async open(metadata) {
-        const { createdAt, forkedFrom, entries } = this.read(metadata.id);
-        return new StoredSession(this.storage(metadata.id, createdAt, entries, forkedFrom));
+        const { createdAt, forkedFrom, placement, entries } = this.read(metadata.id);
+        return new StoredSession(this.storage(metadata.id, createdAt, entries, forkedFrom, placement));
     }
     async list() {
         let names;
@@ -155,7 +164,9 @@ export class FileSessionRepo {
                 continue;
             const id = name.slice(0, -SUFFIX.length);
             try {
-                const { createdAt, forkedFrom } = this.read(id);
+                const { createdAt, forkedFrom, placement } = this.read(id);
+                if (placement !== undefined)
+                    continue;
                 out.push({ id, createdAt, ...(forkedFrom !== undefined ? { forkedFrom } : {}) });
             }
             catch (err) {
@@ -166,12 +177,68 @@ export class FileSessionRepo {
         }
         return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
     }
+    async listPlaced(kind, opts) {
+        let names;
+        try {
+            names = readdirSync(this.dir);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT") {
+                this.disclose(this.dir, `session directory unreadable (${err.code ?? "unknown"}) — placed listing degraded to empty`);
+            }
+            return [];
+        }
+        const now = Date.now();
+        const out = [];
+        for (const name of names) {
+            if (!name.endsWith(SUFFIX))
+                continue;
+            const id = name.slice(0, -SUFFIX.length);
+            let placement;
+            try {
+                placement = this.read(id).placement;
+            }
+            catch (err) {
+                if (!(err instanceof SessionError && err.code === "not_found")) {
+                    this.disclose(this.pathFor(id), `session log unreadable (${err instanceof Error ? err.message : String(err)}) — skipped from the placed listing`);
+                }
+                continue;
+            }
+            if (placement === undefined || placement.kind !== kind)
+                continue;
+            if (opts?.scope !== undefined && placement.scope !== opts.scope)
+                continue;
+            if (opts?.olderThanMs !== undefined) {
+                let ageAnchor = placement.placedAt;
+                try {
+                    ageAnchor = statSync(this.pathFor(id)).mtimeMs;
+                }
+                catch {
+                }
+                if (now - ageAnchor <= opts.olderThanMs)
+                    continue;
+            }
+            out.push(placement.scope !== undefined && placement.handle !== undefined
+                ? { sessionId: id, placedAt: placement.placedAt, scope: placement.scope, handle: placement.handle }
+                : { sessionId: id, placedAt: placement.placedAt, tupleIncomplete: true });
+        }
+        return out;
+    }
+    async placementOf(sessionId) {
+        try {
+            return this.read(sessionId).placement;
+        }
+        catch {
+            return undefined;
+        }
+    }
     async delete(metadata) {
         evictSharedSessionStorage(canonicalStoreKey(this.pathFor(metadata.id)));
         try {
             rmSync(this.pathFor(metadata.id), { force: true });
         }
-        catch {
+        catch (err) {
+            throw new SessionError("storage", `session ${metadata.id} could not be deleted: ${err instanceof Error ? err.message : String(err)}`, err instanceof Error ? err : undefined);
         }
     }
     async fork(sourceMetadata, options = {}) {

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

@@ -0,0 +1,97 @@
+import { type StoredStrategy, type StrategyStore, type StrategyStoreIncident } from "../../core/strategy-store.js";
+/**
+ * File-backed {@link StrategyStore} — the persistence twin of `InMemoryStrategyStore`, so the teacher
+ * mode's cross-session reuse premise actually holds on a local (TOC) deployment where every session is
+ * a fresh process (an in-memory strategy repository there re-learns everything, every time).
+ *
+ * DESIGN STANCE — this is a **cache, not an authority store**: every entry is regenerable (worst case:
+ * ask the teacher again), so losing one never loses correctness. It therefore deliberately skips the
+ * journal/shadow armor of the memory file backend and does NOT fsync-harden beyond the shared
+ * atomic-write primitive, does NOT take a cross-process lock, and accepts a narrow multi-process race
+ * on save-side dedup (two processes can each write one copy of the same normalized entry — the read
+ * side dedups, and a lost max-confidence merge is cache-grade). What it does NOT relax: scope
+ * isolation and loud-refusal discipline, which are held to the same standard as the durable stores.
+ *
+ * Layout: `<root>/<scopeDir>/<id>.json`, one strategy per file, whole-file atomic replace on write.
+ * `scopeDir = slug(scope) + "-" + sha256(scope).slice(0,24)` — the slug is a strict `[a-z0-9-]`
+ * whitelist purely for readability; IDENTITY lives in the 96-bit hash, so no scope value, however
+ * hostile, can traverse out of the root or collide another scope's directory. Ids are gated to
+ * `[A-Za-z0-9_-]{1,64}` at save (the escalation loop mints UUIDs; the interface is public, so a
+ * hand-rolled id must not be able to name a path).
+ *
+ * `scope` is a NAMESPACE, not an authorization boundary — the store cannot authenticate its caller;
+ * whoever holds the instance can address any scope (same posture as the memory store). Authorization
+ * is the host's obligation.
+ */
+export interface FileStrategyStoreOptions {
+    /** Directory to keep strategies under (created `0o700` if absent; a non-directory or unwritable
+     *  path is refused loudly at construction — a store that cannot persist must not pretend to). */
+    root: string;
+    /** Per-scope capacity cap (entries), evicting the lowest-scoring on overflow. Default 100. */
+    maxPerScope?: number;
+    /**
+     * Disclosure sink for contained store incidents (a corrupt entry quarantined, an eviction that
+     * failed after a successful save, a degraded read). Absent ⇒ `console.warn`, once per op kind —
+     * a contained fault must be loud somewhere, but must never flood.
+     */
+    onIncident?: (i: StrategyStoreIncident) => void;
+}
+export declare class FileStrategyStore implements StrategyStore {
+    private readonly root;
+    private readonly maxPerScope;
+    private readonly onIncident?;
+    /** Ops that already warned on the absent-sink fallback (bounded disclosure — never flood). */
+    private readonly warnedOps;
+    /** Isolation scope for the host incident sink (sync throw AND async rejection contained). */
+    private readonly sinkNotifier;
+    /** Scope dirs whose stale temps this instance already swept (once per scope per instance). */
+    private readonly sweptTemps;
+    constructor(opts: FileStrategyStoreOptions);
+    /** `slug(scope)-sha256(scope)[0..24]` — slug is readability only; the hash is the injective key. */
+    private scopeDirName;
+    private scopeDirPath;
+    /** The scope dir must be a REAL directory — a symlink here means the store's namespace was tampered
+     *  with (a link could point retrieval at another scope's data, or writes out of the root). The
+     *  check-then-use window against a same-uid local attacker is out of the threat model: such an
+     *  attacker already holds the same rights as the store itself. */
+    private assertScopeDirSafe;
+    private incident;
+    /** Sweep crashed writers' stale temps (once per scope per instance). Fresh temps are left alone —
+     *  they may belong to a live concurrent writer. */
+    private sweepStaleTemps;
+    /** Load every VALID entry of a scope dir. Corrupt files are quarantined (`.bad` rename) with one
+     *  disclosure; entries that violate the read-side invariants (foreign scope / id≠filename) are
+     *  skipped with disclosure but NOT quarantined (a copied-in file may be someone's valid data);
+     *  normalized duplicates collapse to the best-scoring copy. */
+    private loadScope;
+    /** Rename a corrupt file to `<name>.bad` — one disclosure now, zero parse cost on every later read
+     *  (the suffix no longer matches the entry-file grammar). Never faults the calling operation. */
+    private quarantine;
+    /** Serialize + write one entry, refusing a record whose SERIALIZED form exceeds the read bound.
+     *  The field caps bound RAW string bytes, but JSON escaping expands control characters up to 6x —
+     *  without this door a save could succeed and then self-quarantine on the very next read (the
+     *  worst possible shape: an accepted write the store itself later refuses to serve). */
+    private writeEntry;
+    save(s: StoredStrategy): void;
+    private evict;
+    find(scope: string, query: string, limit: number): StoredStrategy[];
+    /** Bounded candidate view for the RETRIEVAL-adjacent paths (find/hasStrategy/save): an externally
+     *  inflated directory must not make a hot operation unbounded. MAINTENANCE passes Infinity — see
+     *  {@link prune}. */
+    private retrievalReadCap;
+    /**
+     * Trims to `maxSize` over an UNCAPPED enumeration: prune is the reconciliation verb, so it must see
+     * every entry file — under the bounded retrieval view, a capacity SHRINK across restarts (or
+     * `maxPerScope: 0`) left files beyond the window untouched, reporting success while the "removed"
+     * strategies sat on disk ready to resurrect under a later, larger capacity. Host-invoked
+     * maintenance accepts the O(all files) cost the retrieval path refuses.
+     */
+    prune(scope: string, maxSize: number): void;
+    /** Uncapped for the same reason as {@link prune}: this face feeds the seed capacity door, and an
+     *  under-count there turns "refuse what cannot fit" into silent eviction of fresh seeds. */
+    scopeUsage(scope: string): {
+        used: number;
+        capacity: number;
+    };
+    hasStrategy(scope: string, entry: Pick<StoredStrategy, "problem" | "strategy">): boolean;
+}