@sema-agent/core 5.48.0 → 5.50.0

package/dist/core/strategy-store.d.ts

@@ -6,8 +6,17 @@
  * while a missed strategy just falls back to asking the teacher (baseline). `scope` is a **mandatory
  * isolation boundary** (multi-tenant: one user's strategies must never leak to another).
  */
+/** How a strategy first entered its scope. `"earned"` (or absent — older data predates the field) =
+ *  stored by the escalation loop after a verified success; `"seeded"` = pre-installed via
+ *  {@link seedStrategies}. An audit trail, NOT a security property: the store cannot authenticate
+ *  its caller, so a direct `save` can claim either value — trust in seed material is the caller's
+ *  decision, this field only records what the caller declared. */
+export type StrategyOrigin = "earned" | "seeded";
 export interface StoredStrategy {
-    /** Stable id. */
+    /** Stable id. File-backed stores and {@link seedStrategies} require `[A-Za-z0-9_-]{1,64}` (the
+     *  escalation loop mints UUIDs, which conform). NOTE: ids flow into host telemetry
+     *  ({@link import("../agents/teacher.js").TeacherRunResult}`.strategiesInjected`) as join keys —
+     *  do not encode sensitive text into an id. */
     id: string;
     /** The raw task objective that triggered the teacher's help — matched against future objectives. */
     problem: string;
@@ -23,6 +32,23 @@ export interface StoredStrategy {
     teacherModel?: string;
     /** Reserved for a future generalized signature (v3 semantic matching). */
     signature?: string;
+    /** Provenance stamp (see {@link StrategyOrigin}). Absent = earned (backward compatible). */
+    origin?: StrategyOrigin;
+}
+/**
+ * One contained strategy-store incident, as disclosed by a persistent store's `onIncident` seat and by
+ * `TeacherConfig.onStrategyStoreIncident`. Phases are split so "the write never happened" (`save`) is
+ * distinguishable from "the write landed but housekeeping failed" (`evict`), and a quarantined corrupt
+ * entry (`parse`) from a retrieval that degraded (`find`).
+ */
+export interface StrategyStoreIncident {
+    op: "find" | "save" | "evict" | "parse";
+    /** What was observed and what the operation degraded to. */
+    error: string;
+    /** The strategy id involved, when one is known. */
+    id?: string;
+    /** Absolute path of the offending file, when the incident is file-level (e.g. a `parse` quarantine). */
+    path?: string;
 }
 export interface StrategyStore {
     /** Persist a strategy (implementations may merge an exact near-duplicate and cap per-scope size). */
@@ -43,10 +69,113 @@ export interface StrategyStore {
      * (ruled 2026-08-04): this is a capacity cap, and a capacity cap can be widened but never turned off.
      */
     prune?(scope: string, maxSize: number): Promise<void> | void;
+    /**
+     * Optional: how full a scope is (`used` entries out of `capacity`). {@link seedStrategies} uses it to
+     * refuse a batch that would not fit — silently evicting freshly seeded entries would be the most
+     * misleading possible "success". A store that cannot report usage simply omits this.
+     */
+    scopeUsage?(scope: string): Promise<{
+        used: number;
+        capacity: number;
+    }> | {
+        used: number;
+        capacity: number;
+    };
+    /**
+     * Optional: is a content-identical entry (same normalized problem+strategy — the save-side merge
+     * key) already stored in `scope`? {@link seedStrategies} uses it to count only NET-NEW rows against
+     * the remaining capacity, so REPLAYING a batch whose entries already landed is never refused for
+     * "not fitting" space it does not need. A store that omits it gets the conservative whole-batch
+     * check (sound, but a replay into a full scope is falsely refused).
+     */
+    hasStrategy?(scope: string, entry: Pick<StoredStrategy, "problem" | "strategy">): Promise<boolean> | boolean;
 }
 /**
- * Default in-memory store. Retrieval: a stored problem must contain **every significant** query token
- * (and there must be ≥1) — near-exact on the meaningful words, ignoring stopword noise. High precision
+ * Validate a retrieval cap fail-loud (ruled 2026-08-04, same posture as `WebFetchConfig.maxBytes` and
+ * the workflow resilience knobs). The cap was previously applied as
+ * `slice(0, Math.max(0, Number.isFinite(limit) ? limit : 0))`, which mapped NaN, `Infinity` and every
+ * negative onto the SAME value — 0 — so the two opposite intentions ("no cap" and "a fumbled unit")
+ * both came out as "return nothing", the most misleading possible answer for a high-precision store.
+ * `Infinity` is HONORED here (a query cap can legitimately be absent), unlike a capacity cap.
+ */
+export declare function resolveFindLimit(limit: number): number;
+/**
+ * Validate a per-scope CAPACITY cap fail-loud (ruled 2026-08-04). Two silent failures lived here: a
+ * negative `maxSize` was clamped to 0 and quietly wiped the whole scope, and a non-finite one made the
+ * `arr.length > cap` comparison permanently false — eviction disabled, unbounded growth, no signal.
+ * `Infinity` is refused by name (the "turn the cap off" misconception) rather than silently behaving
+ * like the unbounded store it would create. Shared by the in-memory and file-backed stores.
+ */
+export declare function resolveCapacityCap(name: string, cap: number): number;
+/** Id grammar for persisted/seeded strategies: filename-safe, no traversal, bounded. */
+export declare const STRATEGY_ID_RE: RegExp;
+/** Byte cap on `problem` (the matched objective text). */
+export declare const MAX_STRATEGY_PROBLEM_BYTES = 8192;
+/** Byte cap on `strategy` (the injected guidance — the teacher contract is 1-2 sentences). */
+export declare const MAX_STRATEGY_TEXT_BYTES = 4096;
+/** Byte caps on the remaining serialized string fields, so a legitimate save cannot mint an entry
+ *  whose on-disk record dwarfs the payload caps above (the file store also bounds what it will READ,
+ *  and these write-side caps are what make that read bound compatible with every honest record). */
+export declare const MAX_STRATEGY_SCOPE_BYTES = 4096;
+export declare const MAX_STRATEGY_TEACHER_MODEL_BYTES = 512;
+export declare const MAX_STRATEGY_SIGNATURE_BYTES = 4096;
+/** A real ISO-8601 timestamp is ~24-35 bytes; 64 leaves headroom for exotic offsets while keeping a
+ *  "string that happens to sit in the ts seat" from bloating a serialized record. */
+export declare const MAX_STRATEGY_TS_BYTES = 64;
+/** A stored `ts` may not sit further in the future than this — a far-future timestamp would pin the
+ *  entry at maximum recency forever (a rank-to-the-top vector). Small clock skew stays legal. */
+export declare const MAX_STRATEGY_TS_FUTURE_MS: number;
+/** Total byte budget across the strategy texts one retrieval hands to a prompt. Enforced by the file
+ *  store's `find` (close to the tamperable data) AND at the escalation loop's injection site (so the
+ *  bound holds for ANY backend — the in-memory store deliberately accepts legacy-shaped entries). */
+export declare const MAX_STRATEGY_INJECTION_TOTAL_BYTES = 16384;
+/**
+ * Structural validity of a (possibly untrusted, e.g. read-from-disk) value as a {@link StoredStrategy}:
+ * strings where strings are promised, id grammar (filename safety), byte caps, confidence domain
+ * (finite, 0-3 per the declared contract), scope non-emptiness, origin closed set. Returns a reason
+ * string when invalid, `null` when acceptable. Deliberately does NOT judge the timestamp's VALUE —
+ * that is a write-side rule only ({@link validateStrategyForWrite}): applying it on read would let a
+ * host clock stepping backwards mass-invalidate entries that were legal when written. A MALFORMED
+ * (unparseable) `ts` is also allowed through — read-side ranking clamps it to "oldest", so it
+ * self-buries instead of pinning.
+ */
+export declare function storedStrategyShapeIssue(v: unknown): string | null;
+/**
+ * The write-side door: refuse an entry a persistent store must not accept — the structural checks of
+ * {@link storedStrategyShapeIssue} PLUS the future-timestamp bound (a far-future `ts` would pin the
+ * entry at maximum recency; refusing it at write keeps the rank honest, while the read side merely
+ * clamps so a backwards clock step cannot invalidate history).
+ */
+export declare function validateStrategyForWrite(s: StoredStrategy): void;
+/**
+ * Compile a query into the shared high-precision match predicate. Returns `null` when the query has
+ * no significant terms (nothing meaningful to match on → don't inject random strategies). Single
+ * source for the in-memory and file-backed stores, so retrieval semantics cannot fork between
+ * backends.
+ *
+ * TWO acceptance arms, OR-combined, so the CJK upgrade can only ADD hits, never lose one:
+ *  - full arm — every significant term (alphanumeric AND CJK) present in the problem;
+ *  - legacy arm — every significant ALPHANUMERIC term present (and there is ≥1). This is exactly the
+ *    pre-CJK predicate: it used to DISCARD CJK from the query, so "请帮我 extract tables from
+ *    report.pdf" matched an English-only stored problem. Requiring the CJK boilerplate too would
+ *    have silently un-matched that pair — a recall regression hiding inside a recall fix. Keeping
+ *    the legacy arm costs precision only relative to a strictness nobody ever had.
+ *
+ * ACCEPTED COST (documented, pinned): via the legacy arm, a mixed query whose alphanumeric terms all
+ * match can hit a problem whose CJK terms CONFLICT (提取 X vs 删除 X) — exactly what the pre-CJK
+ * predicate always did, retained because losing old hits is the one regression this upgrade must not
+ * make. The mitigation is the surrounding depth (negation preamble, verify-before-use instruction,
+ * injection audit); tightening precision is a measured-recalibration change, not a retrieval patch.
+ */
+export declare function compileStrategyQuery(query: string): ((problem: string) => boolean) | null;
+export declare function normalizeStrategyText(s: string): string;
+/** Duplicate key for save-side merge and read-side dedup: same normalized problem AND strategy. */
+export declare function strategyDedupKey(s: Pick<StoredStrategy, "problem" | "strategy">): string;
+/** Ranking score: confidence weighted by recency (no `uses` — avoids a reinforcement feedback loop). */
+export declare function scoreStoredStrategy(s: StoredStrategy): number;
+/**
+ * Default in-memory store. Retrieval: a stored problem must contain **every significant** query term
+ * (and there must be ≥1) — near-exact on the meaningful terms, ignoring stopword noise. High precision
  * by design. Ranked by `confidence × recency`. Per-scope capacity cap with eviction on save.
  */
 export declare class InMemoryStrategyStore implements StrategyStore {
@@ -56,6 +185,54 @@ export declare class InMemoryStrategyStore implements StrategyStore {
     save(s: StoredStrategy): void;
     find(scope: string, query: string, limit: number): StoredStrategy[];
     prune(scope: string, maxSize: number): void;
+    scopeUsage(scope: string): {
+        used: number;
+        capacity: number;
+    };
+    hasStrategy(scope: string, entry: Pick<StoredStrategy, "problem" | "strategy">): boolean;
     /** Total stored strategies (across scopes); for tests/observability. */
     get size(): number;
 }
+/** One entry to seed: a {@link StoredStrategy} minus the fields the seeder stamps (`scope` comes from
+ *  the call, `origin` is forced to `"seeded"`, `ts` defaults to now). */
+export type SeedStrategyEntry = Omit<StoredStrategy, "scope" | "origin" | "ts"> & {
+    ts?: string;
+};
+/** Result of {@link seedStrategies}: how many entries landed, and where the write phase stopped if it
+ *  did. `failedAt` present = a PARTIAL seed (entries before it are in the store); the batch is
+ *  idempotent by content, so re-running the same call is the supported recovery. */
+export interface SeedStrategiesReport {
+    written: number;
+    failedAt?: {
+        id: string;
+        error: string;
+    };
+}
+/**
+ * Seed a batch of strategies into `scope`, in two phases:
+ *
+ *  1. **Validate the whole batch first** — any invalid entry (shape/id grammar/byte caps/timestamp
+ *     discipline, see {@link validateStrategyForWrite}), a duplicate id OR duplicate normalized
+ *     content within the batch (two content-identical entries would merge into one, making `written`
+ *     over-report and one seeded id unfindable), or a batch larger than the scope's remaining
+ *     capacity (when the store reports usage) refuses the WHOLE batch loudly with ZERO writes.
+ *     Silently evicting freshly seeded entries would be the most misleading possible "success", so a
+ *     batch that cannot fully fit does not start.
+ *  2. **Write one by one** — a mid-batch failure returns a `{written, failedAt}` report instead of
+ *     pretending to be a transaction; entries are idempotent (same id + content re-saves merge), so
+ *     replaying the same batch completes the remainder.
+ *
+ * HONEST LIMITS (cache-store posture — no locks, no reservations):
+ *  - the capacity preflight is a snapshot, not a reservation: with a CONCURRENT writer on the same
+ *    scope, entries can still be evicted between the check and the writes (single-writer deployments
+ *    — the aggregated backend under its boot lock — get the full guarantee);
+ *  - an entry content-identical to one ALREADY STORED merges into the existing entry — the STORED id
+ *    and the STORED `origin` stamp win (content earned before seeding stays `earned`; the requested
+ *    id is not created). This counts as written: the content IS in the store, and replaying a batch
+ *    relies on exactly that merge. Injection audit rows always carry the stored id, so joins hold.
+ *
+ * Every entry is stamped `origin: "seeded"`. That stamp is an AUDIT clue, not a security property —
+ * the store cannot authenticate the seeder, and a caller with store access can write anything; trust
+ * in the seed material is the caller's decision.
+ */
+export declare function seedStrategies(store: StrategyStore, scope: string, entries: readonly SeedStrategyEntry[]): Promise<SeedStrategiesReport>;

package/dist/core/strategy-store.js

@@ -1,9 +1,10 @@
+import { termSet } from "./memory-vector.js";
 function invalidKnob(message, code) {
     const e = new Error(message);
     e.code = code;
     return e;
 }
-function resolveFindLimit(limit) {
+export function resolveFindLimit(limit) {
     if (limit === Number.POSITIVE_INFINITY)
         return limit;
     if (!Number.isInteger(limit) || limit < 0) {
@@ -11,30 +12,109 @@ function resolveFindLimit(limit) {
     }
     return limit;
 }
-function resolveCapacityCap(name, cap) {
+export function resolveCapacityCap(name, cap) {
     if (cap === Number.POSITIVE_INFINITY) {
-        throw invalidKnob(`InMemoryStrategyStore ${name} cannot be Infinity — a per-scope capacity cap can be widened but not turned off; pass a large finite integer instead`, "config.strategy_max_size_invalid");
+        throw invalidKnob(`strategy store ${name} cannot be Infinity — a per-scope capacity cap can be widened but not turned off; pass a large finite integer instead`, "config.strategy_max_size_invalid");
     }
     if (!Number.isInteger(cap) || cap < 0) {
-        throw invalidKnob(`InMemoryStrategyStore ${name} must be a non-negative integer (got ${String(cap)})`, "config.strategy_max_size_invalid");
+        throw invalidKnob(`strategy store ${name} must be a non-negative integer (got ${String(cap)})`, "config.strategy_max_size_invalid");
     }
     return cap;
 }
+export const STRATEGY_ID_RE = /^[A-Za-z0-9_-]{1,64}$/;
+export const MAX_STRATEGY_PROBLEM_BYTES = 8192;
+export const MAX_STRATEGY_TEXT_BYTES = 4096;
+export const MAX_STRATEGY_SCOPE_BYTES = 4096;
+export const MAX_STRATEGY_TEACHER_MODEL_BYTES = 512;
+export const MAX_STRATEGY_SIGNATURE_BYTES = 4096;
+export const MAX_STRATEGY_TS_BYTES = 64;
+export const MAX_STRATEGY_TS_FUTURE_MS = 24 * 60 * 60 * 1000;
+export const MAX_STRATEGY_INJECTION_TOTAL_BYTES = 16384;
+function invalidEntry(message, id) {
+    const e = new Error(message);
+    e.code = "strategy.entry_invalid";
+    if (id !== undefined)
+        e.strategyId = id;
+    return e;
+}
+export function storedStrategyShapeIssue(v) {
+    if (v === null || typeof v !== "object")
+        return "not an object";
+    const s = v;
+    if (typeof s.id !== "string" || !STRATEGY_ID_RE.test(s.id)) {
+        return `id must match [A-Za-z0-9_-]{1,64} (got ${JSON.stringify(String(s.id).slice(0, 80))})`;
+    }
+    if (typeof s.scope !== "string" || s.scope.length === 0)
+        return "scope must be a non-empty string";
+    if (Buffer.byteLength(s.scope, "utf8") > MAX_STRATEGY_SCOPE_BYTES)
+        return `scope exceeds ${MAX_STRATEGY_SCOPE_BYTES} bytes`;
+    if (typeof s.problem !== "string" || typeof s.strategy !== "string")
+        return "problem/strategy must be strings";
+    if (Buffer.byteLength(s.problem, "utf8") > MAX_STRATEGY_PROBLEM_BYTES) {
+        return `problem exceeds ${MAX_STRATEGY_PROBLEM_BYTES} bytes`;
+    }
+    if (Buffer.byteLength(s.strategy, "utf8") > MAX_STRATEGY_TEXT_BYTES) {
+        return `strategy text exceeds ${MAX_STRATEGY_TEXT_BYTES} bytes`;
+    }
+    if (typeof s.confidence !== "number" || !Number.isFinite(s.confidence) || s.confidence < 0 || s.confidence > 3) {
+        return `confidence must be a finite number in [0,3] (got ${String(s.confidence)})`;
+    }
+    if (typeof s.ts !== "string")
+        return "ts must be an ISO timestamp string";
+    if (Buffer.byteLength(s.ts, "utf8") > MAX_STRATEGY_TS_BYTES)
+        return `ts exceeds ${MAX_STRATEGY_TS_BYTES} bytes`;
+    if (s.teacherModel !== undefined && (typeof s.teacherModel !== "string" || Buffer.byteLength(s.teacherModel, "utf8") > MAX_STRATEGY_TEACHER_MODEL_BYTES)) {
+        return `teacherModel must be a string of at most ${MAX_STRATEGY_TEACHER_MODEL_BYTES} bytes when present`;
+    }
+    if (s.signature !== undefined && (typeof s.signature !== "string" || Buffer.byteLength(s.signature, "utf8") > MAX_STRATEGY_SIGNATURE_BYTES)) {
+        return `signature must be a string of at most ${MAX_STRATEGY_SIGNATURE_BYTES} bytes when present`;
+    }
+    if (s.origin !== undefined && s.origin !== "earned" && s.origin !== "seeded") {
+        return `origin must be "earned" or "seeded" when present (got ${String(s.origin)})`;
+    }
+    return null;
+}
+export function validateStrategyForWrite(s) {
+    const issue = storedStrategyShapeIssue(s);
+    if (issue !== null) {
+        throw invalidEntry(`strategy ${issue}`, typeof s.id === "string" ? s.id : undefined);
+    }
+    const t = new Date(s.ts).getTime();
+    if (!Number.isNaN(t) && t > Date.now() + MAX_STRATEGY_TS_FUTURE_MS) {
+        throw invalidEntry(`strategy ts is in the future beyond the allowed skew (${s.ts})`, s.id);
+    }
+}
 const STOP = new Set([
     "the", "and", "for", "with", "from", "this", "that", "into", "your", "you", "are", "was", "were", "has",
     "have", "had", "not", "but", "all", "any", "can", "use", "using", "via", "then", "than", "out", "get",
     "got", "its", "it's", "their", "them", "they", "what", "when", "which", "who", "how", "why", "a", "an",
     "of", "to", "in", "on", "is", "it", "or", "as", "at", "by", "be", "do", "if", "so", "no", "up", "we",
 ]);
-function tokens(s) {
-    return s.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+const CJK_LEAD = /^[\u3040-\u30FF\u31F0-\u31FF\u3400-\u4DBF\u4E00-\u9FFF\uAC00-\uD7A3\uF900-\uFAFF]/;
+function terms(s) {
+    return termSet(s);
 }
 function significant(s) {
-    return tokens(s).filter((t) => t.length >= 3 && !STOP.has(t));
+    return [...terms(s)].filter((t) => (CJK_LEAD.test(t) ? true : t.length >= 3 && !STOP.has(t)));
+}
+export function compileStrategyQuery(query) {
+    const qSig = significant(query);
+    if (qSig.length === 0)
+        return null;
+    const qAlnum = qSig.filter((t) => !CJK_LEAD.test(t));
+    return (problem) => {
+        const probTerms = terms(problem);
+        if (qSig.every((t) => probTerms.has(t)))
+            return true;
+        return qAlnum.length > 0 && qAlnum.every((t) => probTerms.has(t));
+    };
 }
-function normalize(s) {
+export function normalizeStrategyText(s) {
     return s.trim().toLowerCase().replace(/\s+/g, " ");
 }
+export function strategyDedupKey(s) {
+    return `${normalizeStrategyText(s.problem)}\u0000${normalizeStrategyText(s.strategy)}`;
+}
 function ageDays(tsISO) {
     const t = new Date(tsISO).getTime();
     if (Number.isNaN(t)) {
@@ -42,7 +122,7 @@ function ageDays(tsISO) {
     }
     return Math.max(0, Date.now() - t) / 86_400_000;
 }
-function score(s) {
+export function scoreStoredStrategy(s) {
     return (s.confidence + 1) * (1 / (1 + ageDays(s.ts)));
 }
 export class InMemoryStrategyStore {
@@ -53,19 +133,21 @@ export class InMemoryStrategyStore {
     }
     save(s) {
         const arr = this.byScope.get(s.scope) ?? [];
-        const np = normalize(s.problem);
-        const ng = normalize(s.strategy);
-        const dup = arr.find((e) => normalize(e.problem) === np && normalize(e.strategy) === ng);
+        const key = strategyDedupKey(s);
+        const dup = arr.find((e) => strategyDedupKey(e) === key);
         if (dup) {
-            dup.confidence = Number.isFinite(s.confidence) ? Math.max(dup.confidence, s.confidence) : dup.confidence;
-            dup.ts = s.ts;
+            const incoming = Number.isFinite(s.confidence) ? s.confidence : undefined;
+            if (incoming !== undefined && incoming >= dup.confidence) {
+                dup.confidence = incoming;
+                dup.ts = s.ts;
+            }
             dup.teacherModel = s.teacherModel ?? dup.teacherModel;
         }
         else {
             arr.push(s);
         }
         if (arr.length > this.maxPerScope) {
-            arr.sort((a, b) => score(b) - score(a));
+            arr.sort((a, b) => scoreStoredStrategy(b) - scoreStoredStrategy(a));
             arr.length = this.maxPerScope;
         }
         this.byScope.set(s.scope, arr);
@@ -76,24 +158,30 @@ export class InMemoryStrategyStore {
         if (!arr || arr.length === 0) {
             return [];
         }
-        const qSig = significant(query);
-        if (qSig.length === 0) {
+        const matches = compileStrategyQuery(query);
+        if (matches === null) {
             return [];
         }
-        const matches = arr.filter((s) => {
-            const probTokens = new Set(tokens(s.problem));
-            return qSig.every((t) => probTokens.has(t));
-        });
-        return matches.sort((a, b) => score(b) - score(a)).slice(0, cap);
+        return arr
+            .filter((s) => matches(s.problem))
+            .sort((a, b) => scoreStoredStrategy(b) - scoreStoredStrategy(a))
+            .slice(0, cap);
     }
     prune(scope, maxSize) {
         const n = resolveCapacityCap("maxSize", maxSize);
         const arr = this.byScope.get(scope);
         if (arr && arr.length > n) {
-            arr.sort((a, b) => score(b) - score(a));
+            arr.sort((a, b) => scoreStoredStrategy(b) - scoreStoredStrategy(a));
             arr.length = n;
         }
     }
+    scopeUsage(scope) {
+        return { used: this.byScope.get(scope)?.length ?? 0, capacity: this.maxPerScope };
+    }
+    hasStrategy(scope, entry) {
+        const key = strategyDedupKey(entry);
+        return (this.byScope.get(scope) ?? []).some((e) => strategyDedupKey(e) === key);
+    }
     get size() {
         let n = 0;
         for (const arr of this.byScope.values())
@@ -101,3 +189,64 @@ export class InMemoryStrategyStore {
         return n;
     }
 }
+function seedRefused(message) {
+    const e = new Error(message);
+    e.code = "strategy.seed_refused";
+    return e;
+}
+export async function seedStrategies(store, scope, entries) {
+    if (typeof scope !== "string" || scope.length === 0) {
+        throw seedRefused("seedStrategies: scope must be a non-empty string");
+    }
+    const now = new Date().toISOString();
+    const full = [];
+    const ids = new Set();
+    const contentKeys = new Set();
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        const s = { ...e, ts: e.ts ?? now, scope, origin: "seeded" };
+        try {
+            validateStrategyForWrite(s);
+        }
+        catch (err) {
+            throw seedRefused(`seedStrategies: entry ${i} refused, zero entries written — ${err.message}`);
+        }
+        if (ids.has(s.id)) {
+            throw seedRefused(`seedStrategies: duplicate id ${JSON.stringify(s.id)} within the batch, zero entries written`);
+        }
+        ids.add(s.id);
+        const key = strategyDedupKey(s);
+        if (contentKeys.has(key)) {
+            throw seedRefused(`seedStrategies: entry ${i} (${JSON.stringify(s.id)}) duplicates another batch entry's content, zero entries written`);
+        }
+        contentKeys.add(key);
+        full.push(s);
+    }
+    if (store.scopeUsage) {
+        const usage = await store.scopeUsage(scope);
+        let netNew = full.length;
+        if (store.hasStrategy) {
+            netNew = 0;
+            for (const s of full) {
+                if (!(await store.hasStrategy(scope, s)))
+                    netNew++;
+            }
+        }
+        const remaining = Math.max(0, usage.capacity - usage.used);
+        if (netNew > remaining) {
+            throw seedRefused(`seedStrategies: ${netNew} net-new entries exceed the scope's remaining capacity ${remaining} ` +
+                `(${usage.used}/${usage.capacity} used), zero entries written — widen the capacity or trim the batch`);
+        }
+    }
+    let written = 0;
+    for (const s of full) {
+        try {
+            await store.save(s);
+        }
+        catch (err) {
+            return { written, failedAt: { id: s.id, error: String(err.message ?? err) } };
+        }
+        written++;
+    }
+    return { written };
+}

package/dist/core/task-registry-agent.js

@@ -233,6 +233,12 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
                 continue;
             }
             rowsReaped++;
+            {
+                const staleInProc = core.handles.get(r.handle);
+                if (staleInProc !== undefined && staleInProc.status !== "running" && staleInProc.status !== "pending" && staleInProc.status !== "parked") {
+                    core.handles.delete(r.handle);
+                }
+            }
             core.reapedHandles.add(r.handle);
             if (deps.mailbox !== undefined) {
                 try {

package/dist/core/types.d.ts

@@ -4730,6 +4730,15 @@ export interface EngineNotice {
      *    `detail: { total, stripped: [{ key, reason }], omitted? }`, the rendered key list bounded in count
      *    and length because the names come from the untrusted script. One aggregated notice per governed
      *    child build, not de-duplicated across builds: each spec is a distinct fact.
+     *  - `"mcp.revocation_probe_failed"` (design/338) — the deployment's `mcpRevocations.isRevoked`
+     *    probe threw; MCP dispatch FAILS OPEN (revocation is a tightening face) and this announces
+     *    once per run. `detail: { message }`. The refusal itself (`mcp.server_revoked`) is a tool
+     *    RESULT code, not a notice.
+     *  - `"config.models_swapped"` — `Runner.swapModels` replaced the model catalog generation
+     *    (zero-restart model switching). `detail: { models, tiers }` — key COUNTS only, never the
+     *    catalog itself. In-flight tasks finish on the models they resolved at prepare (natural
+     *    snapshot); every later prepare resolves against the new generation. A failed swap (illegal
+     *    tier binding) throws atomically and mints nothing.
      *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
      *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
      *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced
@@ -4833,7 +4842,8 @@ export interface EngineNotice {
      *  - `"delegation.transcript_integrity"` (subagent transcript persistence) — a durable agent row
      *    with a BOUND transcript sessionId met a session store that attests `not_found` for it: the
      *    deployment's declared transcript durability is being contradicted by reality. Announced at
-     *    most once per (handle, process) from the continuation read faces (SendMessage preflight /
+     *    most once per (scope, handle, process) — `detail: { handle, scope? }`, scope = the resolved
+     *    access scope of the read that found the gap — from the continuation read faces (SendMessage preflight /
      *    AgentTranscript's durable leg); the per-call honest refusals are unchanged, and the declared
      *    tier is NOT auto-downgraded (declaration-制 — observation reports, it never re-adjudicates);
      *    `detail: { handle }`.
@@ -4892,6 +4902,19 @@ export interface RunnerDeps {
     brain: Brain;
     /** Catalog used to resolve string ModelRefs to Model objects. */
     models?: Record<string, Model>;
+    /**
+     * design/338 (mid-turn MCP revocation) — the HOST's revocation ledger, probed synchronously at
+     * every MCP dispatch (tool call + the three resource tools) BEFORE the transport. The engine
+     * never caches the answer: the ledger's one authority lives on the host (a cached copy would be
+     * a split-state second authority). A revoked server's calls settle as the coded refusal
+     * `mcp.server_revoked` with known-not-executed wording; in-flight calls a revocation raced are
+     * deliberately not chased (the threat shape is "new calls after removal"). Absent seat = the
+     * pre-338 semantics. A THROWING probe fails open (revocation is a tightening face — a broken
+     * probe must not brick every MCP call) with a once-per-run `mcp.revocation_probe_failed` notice.
+     */
+    mcpRevocations?: {
+        isRevoked(serverName: string): boolean;
+    };
     /**
      * design/147 S1c (clay ruling 2026-07-18) — the DURABLE name→agent roster behind explicit-name
      * addressing, a storage-tier seam like the checkpoint store: core bundles `MemoryRosterStore`

package/dist/index.d.ts

@@ -40,7 +40,7 @@ export type { RepetitionEvent, RepetitionInspection } from "./brain/repetition.j
 export { computeCostMicroUsd, modelCostToPricing, type ModelPricing, type TokenCounts, } from "./core/pricing.js";
 export { cacheFamilyOf, promptTokensOf, uncachedInputTokensOf, type CacheFamily } from "./core/runner/usage-accounting.js";
 export { emitTrace, type ToolDisclosureManifest, type TraceEvent, type TracerHook } from "./core/trace.js";
-export { InMemoryStrategyStore, type StrategyStore, type StoredStrategy } from "./core/strategy-store.js";
+export { InMemoryStrategyStore, seedStrategies, type StrategyStore, type StoredStrategy, type StrategyOrigin, type StrategyStoreIncident, type SeedStrategyEntry, type SeedStrategiesReport, } from "./core/strategy-store.js";
 export { createSqlTool, validateReadOnlySql, type SqlToolOptions } from "./tools/sql.js";
 export { runWithTeacher, parseTeacherAdvice, TEACHER_PROMPT, type TeacherConfig, type TeacherAdvice, type EscalationRecord, type EscalationTrigger, type TeacherRunResult, } from "./agents/teacher.js";
 export { runWithVerification, resumeWithVerification, verifyCompleted, runDeveloperTask, VERIFICATION_PROMPT, STATIC_VERIFICATION_PROMPT, VerdictSchema, type Verdict, type VerifyConfig, type UnverifiedReason, type VerificationOutcome, type VerificationResult, type DeveloperTaskConfig, } from "./agents/verify.js";
@@ -102,7 +102,7 @@ export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./c
 export { InMemoryFileSnapshotStore, DEFAULT_SNAPSHOT_BOUNDS } from "./core/file-snapshot-store.js";
 export { captureManifest, applyManifest } from "./core/file-snapshot-store.js";
 export type { FileSnapshotStore, FileSnapshotResult, FileSnapshotError, FileSnapshotBounds } 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, type FileStorageBackendOptions, type FileStorageCorruptReadInfo, type FileSessionRepoOptions, type FileFileSnapshotStoreOptions, type FileCheckpointStoreOptions, } 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, type FileStorageBackendOptions, type FileStorageCorruptReadInfo, type FileStrategyStoreOptions, type FileSessionRepoOptions, type FileFileSnapshotStoreOptions, type FileCheckpointStoreOptions, } from "./stores/file/index.js";
 export { CacheBreakDetector, type CacheBreakFinding, type ToolFingerprintInput } from "./core/cache-break-detector.js";
 export { maybeCompact, type MaybeCompactOptions, type CompactionWindowSafetyInfo } from "./core/auto-compaction.js";
 export { brainToRuntime } from "./core/runtime.js";

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";

package/dist/orchestration/run-workflow-tool.d.ts

@@ -234,6 +234,18 @@ export interface RunWorkflowToolDeps {
     parentReadFace?: () => import("../core/types.js").TaskSpec["readFace"];
     /** Twin of the above for the deny-set additions (union, not replace). */
     parentReadDenyPatterns?: () => import("../core/types.js").TaskSpec["readDenyPatterns"];
+    /** #345 ③ — the HOST task's write-hands clamp, the read-face clamp's sibling on this lane (the
+     *  subagent delegation lane has carried it as `ToolExecuteContext.handsReadOnly` since its own
+     *  tighten-only ruling; the workflow lane was the remaining gap — a read-only host's workflow
+     *  children spawned with full write hands). Filled ONLY when the clamp is ON (`true`), exactly
+     *  like the ctx seat, so an unclamped deployment's mount gains no key. Known at prepare-time
+     *  (frozen TaskSpec snapshot — no lazy getter needed, the `parentCheckpointStoreDisabled` shape). */
+    parentHandsReadOnly?: true;
+    /** #345 ③ — the HOST task's hard-headless clamp (`interactiveTools: false`), same carriage rules
+     *  as `parentHandsReadOnly` above: only the DISABLING value travels, mirroring the subagent lane's
+     *  `ToolExecuteContext.interactiveTools` seat — without it a headless-clamped host's workflow
+     *  children could re-mount the interactive tool the host run disabled. */
+    parentInteractiveTools?: false;
     /** [1238](A) — call-time getter for the HOST task's RESOLVED Model object: a spawned agent whose
      *  fold chain produced no model inherits the parent's full object (baseUrl/key routing included),
      *  mirroring the subagent lane's ctx.model semantics. */

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

@@ -468,7 +468,7 @@ export async function createRunWorkflowTool(d) {
                 }
                 : governance;
             const scriptFn = (wfCtx) => {
-                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, d.parentThinking, principal, ctx.checkpointStoreDisabledForChildren === true || d.parentCheckpointStoreDisabled === true, d.parentReadFace, d.parentReadDenyPatterns);
+                const primitives = buildWorkflowPrimitives(wfCtx, runGovernance, d.onAgentSpawn, d.parentThinking, principal, ctx.checkpointStoreDisabledForChildren === true || d.parentCheckpointStoreDisabled === true, d.parentReadFace, d.parentReadDenyPatterns, ctx.handsReadOnly === true || d.parentHandsReadOnly === true, ctx.interactiveTools === false || d.parentInteractiveTools === false);
                 return d.scriptRunner.run({ scriptSource: script, primitives, scriptArgs: effectiveArgs, signal: wfCtx.signal }).then((r) => r.result);
             };
             if (ctx.signal?.aborted) {