@sema-agent/core 5.47.0 → 5.49.0

package/dist/core/session.d.ts

@@ -7,8 +7,43 @@ export { SessionError } from "../internal/harness.js";
 export type { SessionWriteOptions } from "../internal/harness.js";
 import type { Session } from "../internal/harness.js";
 import type { SessionTreeEntry } from "../internal/harness.js";
+export type { SessionPlacementRecord } from "../internal/harness.js";
 /** True when `err` is a session optimistic-lock conflict (a concurrent writer won the branch leaf). */
 export declare function isSessionConflict(err: unknown): boolean;
+/**
+ * Subagent transcript persistence — the ACQUIRE-form placement declaration a trusted spawner passes
+ * when it creates a subagent's transcript session: the session is created INTO the store's subagent
+ * partition instead of the host lane. The minter reports the fact; the store never guesses residency
+ * from call shape. `placedAt` is stamped by the store at creation (see
+ * {@link SessionPlacementRecord}). Reaches stores ONLY through the engine's trusted internals chain
+ * (never a public TaskSpec key — a public key would let any caller push arbitrary sessions into the
+ * partition and poison store-side retention/enumeration).
+ */
+export interface SessionPlacement {
+    kind: "subagent";
+    /** Tenant key, same source as the durable agent row's `scope`. */
+    scope?: string;
+    /** The spawning host session (retrieval/partition metadata; authorization stays on the row predicate). */
+    parentSessionId?: string;
+    /** The delegation tree's root host session (fixed point). */
+    rootSessionId?: string;
+    /** The durable agent row key (`a…`) — the store-side join key for orphan GC. */
+    handle?: string;
+}
+/**
+ * One row of {@link SessionStore.listPlaced}. The row-store join key is the FULL `(scope, handle)`
+ * tuple — a listing that cannot supply both returns the discriminated `tupleIncomplete` variant
+ * instead (consumers fail closed on it: never age-reaped, reported honestly).
+ */
+export type PlacedSessionRow = {
+    sessionId: string;
+    placedAt: number;
+} & ({
+    scope: string;
+    handle: string;
+} | {
+    tupleIncomplete: true;
+});
 /** A session handed back by a {@link SessionStore}: the harness `Session` plus its resolved id. */
 export interface AcquiredSession {
     session: Session;
@@ -66,13 +101,47 @@ export interface SessionStore {
      * fact.
      */
     readonly durability?: import("./checkpoint-store.js").StoreDurability;
+    /**
+     * Subagent transcript persistence — the store's PER-PLACEMENT durability declaration: "this store
+     * understands and honors placement semantics (partitioning + the obligations below), and sessions
+     * placed into the `subagent` partition have THIS durability". Declaration, never duck-typing (the
+     * wiring manifest relays it verbatim). The store-level {@link durability} continues to describe
+     * only UN-placed sessions — a routing/composite store whose transient host lane and durable
+     * subagent partition differ can therefore be honest on both axes. ABSENT = the store does not
+     * understand placement: an `acquire` carrying one is legally IGNORED (the session is then an
+     * ordinary one, and the deployment's delegation-durability tier reads as rows-only).
+     *
+     * Declaring this commits the store to the placement obligations:
+     *  1. a placed session enjoys the declared durability (`acquire(id, {requireExisting:true})`
+     *     reaches it after a restart when `"durable"`);
+     *  2. placed sessions do NOT appear on host enumeration faces (`list()` and every deployment
+     *     listing path — restart-stable);
+     *  3. acquire semantics for sessions WITHOUT a placement are byte-unchanged;
+     *  4. `release(placedId)` is a REAL deletion (durable history included) — the joint reap's
+     *     "row and session both gone" depends on it;
+     *  5. placement is FIRST-WRITE IMMUTABLE — a re-open (`requireExisting`, with or without a
+     *     placement argument) returns the same session and never rewrites the tuple;
+     *  6. a placed id cannot be CLAIMED: a later claim-form acquire (no `requireExisting`, no
+     *     creation placement) of an existing placed id refuses loudly
+     *     (`SessionError("placement_refused")`) instead of attaching.
+     */
+    readonly placements?: {
+        subagent?: {
+            durability: "durable" | "process-local";
+        };
+    };
     /** Get an existing session by id, or create one (optionally with a caller-supplied id). design/114 Phase3:
      *  `opts.requireExisting` ⇒ a store MUST fail loud (throw a `not_found` {@link SessionError}) on a genuinely
      *  missing id rather than create-on-miss — so a reuse-style warm-resume of a gone session errors instead of
      *  silently starting a fresh empty run. A store that cannot honor it MUST still not silently create (either
-     *  implement the check or reject the option). */
+     *  implement the check or reject the option).
+     *  `opts.placement` (subagent transcript persistence): CREATE the session into the named placement
+     *  partition (see {@link SessionPlacement} — trusted-internals channel only). Ignored by stores
+     *  that do not declare {@link placements}; on a store that does, the creating call is exempt from
+     *  obligation 6 above and idempotent re-acquire by the same trusted chain stays legal. */
     acquire(sessionId?: string, opts?: {
         requireExisting?: boolean;
+        placement?: SessionPlacement;
     }): Promise<AcquiredSession>;
     /** Mark a session recently active (resets idle TTL where applicable). May be async for durable stores. */
     touch(sessionId: string): void | Promise<void>;
@@ -115,6 +184,19 @@ export interface SessionStore {
      * that cannot enumerate omits this (the shell then has no session-list affordance — honest degrade).
      */
     list?(): Promise<SessionStoreSummary[]>;
+    /**
+     * Subagent transcript persistence — enumerate the PLACED partition (the input to the joint reap's
+     * partition leg: sessions whose owning agent row is gone are the orphan shape it collects).
+     * **Optional**: absent = the partition-GC leg is simply unavailable on this store (documented,
+     * fail-closed — placed sessions then age out only through the row-joined reap path). `olderThanMs`
+     * filters by session AGE (last activity where knowable, else `placedAt`); `scope` narrows to one
+     * tenant. Rows return the FULL `(scope, handle)` join tuple or the honest `tupleIncomplete`
+     * variant (see {@link PlacedSessionRow}) — consumers must skip incomplete tuples, never guess.
+     */
+    listPlaced?(kind: "subagent", opts?: {
+        olderThanMs?: number;
+        scope?: string;
+    }): Promise<PlacedSessionRow[]>;
     /**
      * design/110 — FORK a session: copy `sourceId`'s durable history (root→leaf) into a NEW session and return its
      * id (or `null` if the source doesn't exist). The forked session is independent (writes to it don't touch the

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.d.ts

@@ -1,6 +1,17 @@
 import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
 import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import { type ToolResultStore } from "./tool-result-store.js";
+/**
+ * Subagent transcript persistence (delegation entry caps) — the ACTIVE handles of one delegation
+ * tree in THIS process's registry: `background_agent` handles whose status is running/pending
+ * (parked does not burn a concurrency slot — a suspension is not concurrency; terminal handles are
+ * not active) under the `(scope, rootSessionId)` key (full depth: a grandchild's row carries the
+ * tree's fixed-point root, so the whole tree shares one pool; a depth-1 row whose rootSessionId
+ * predates the floor falls back to its parentSessionId — same fallback the access predicate's root
+ * arm rides). SYNCHRONOUS by contract: the caps enforcement runs check→register in one synchronous
+ * segment, which is what makes the reservation race-free in-process.
+ */
+export declare function activeDelegationHandlesLane(core: DurableAgentCore, scope: string, rootSessionId: string): string[];
 export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
 /** design/151 S1a — enqueue one durable-row write (see {@link DurableAgentLane} for the lane
  *  contract). `patch` is captured at CALL time (the settle-site values), applied in chain order.
@@ -66,9 +77,25 @@ export declare function endDurableClaimLane(core: DurableAgentCore, id: string):
  *  transcript lives on unanchored — the exact strand this orchestration exists to prevent. */
 export declare function reapDurableAgentsLane(core: DurableAgentCore, scope: string, deps: {
     store: BackgroundAgentStore;
+    /** `listPlaced` (subagent transcript persistence, optional): arms the PARTITION leg below —
+     *  placed transcript sessions whose owning row is GONE (row never landed / deleted-but-release-
+     *  failed) are the orphan shape only a session-side enumeration can find. Absent = that leg is
+     *  unavailable (documented; the row-joined path still runs). */
     sessions?: {
         unpin?(sessionId: string): unknown;
         release(sessionId: string): Promise<void> | void;
+        listPlaced?(kind: "subagent", opts?: {
+            olderThanMs?: number;
+            scope?: string;
+        }): Promise<Array<{
+            sessionId: string;
+            placedAt: number;
+        } & ({
+            scope: string;
+            handle: string;
+        } | {
+            tupleIncomplete: true;
+        })>>;
     };
     /** design/151 §7.7 (F-13) — the row's mailbox dies with the row: a WINNING delete also drops
      *  the (scope, handle) mailbox (advisory — a mailbox fault never blocks the reap; an orphaned
@@ -86,6 +113,7 @@ export declare function reapDurableAgentsLane(core: DurableAgentCore, scope: str
     rowsReaped: number;
     sessionsReleased: number;
     skippedNoSessions: number;
+    orphanPlacedReleased: number;
 }>;
 /** codex 终审 C-4 half — after a probe-false RELEASE the row must stop claiming a transcript:
  *  the heartbeat's F-1 arm keeps re-driving a flush-failed lane, so a later successful flush