@sema-agent/core 5.57.0 → 5.59.0

package/dist/core/remote-env.d.ts

@@ -52,7 +52,7 @@ export interface WorkspaceHandle {
     snapshotId?: SnapshotId;
     /** Token for {@link RemoteExecutionEnv.reconnect} when the VM is still running (vs suspended to a snapshot). */
     sessionToken?: SessionToken;
-    /** How a checkpointed workspace is restored on resume (1.257.2 hardening, codex review of [500]②):
+    /** How a checkpointed workspace is restored on resume (1.257.2 hardening):
      *  `"park_only"` = durable-park-only suspend degrade (non-suspendable env; workspace persists on the
      *  target, resume skips `resumeVM`). Absent = legacy/snapshot handle — resume treats a MISSING
      *  `snapshotId` as corruption (fail-closed) unless the resumed env is itself non-suspendable
@@ -98,7 +98,7 @@ export interface VmLifecycleOptions {
     /** Abort a hung pause/restore. */
     abortSignal?: AbortSignal;
     /**
-     * [1461]④a (resume workspace-root fidelity) — the CHECKPOINTED {@link WorkspaceHandle} of the workspace
+     * (resume workspace-root fidelity) — the CHECKPOINTED {@link WorkspaceHandle} of the workspace
      * being restored, passed by the engine on the `resumeVM` leg. An adapter SHOULD bind the restored
      * workspace root (cwd / mount) to `priorHandle.mountPath` rather than its CURRENT deployment
      * configuration: across a config-knob change window (e.g. a mount-path rotation) the resumed task's
@@ -289,7 +289,7 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
          *
          *  ⚠️ LOAD-BEARING INVARIANT (opus review 1.257.2): `suspendable:false` on a remote env also asserts
          *  the workspace is EXTERNALLY DURABLE — it persists on the target across the env object's lifetime
-         *  (true for SSH hosts / ADB devices). The durable-park-only suspend degrade (service [500]②) rests
+         *  (true for SSH hosts / ADB devices). The durable-park-only suspend degrade rests
          *  on this: it skips `suspendVM` and trusts the factory to reconnect to the SAME workspace on resume.
          *  An adapter for a non-suspendable EPHEMERAL backend (e.g. a snapshot-less container torn down with
          *  the transport) must NOT be modeled as `suspendable:false` remote — it would silently take the
@@ -359,7 +359,7 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
      * expired while suspended). Any failed step → `Err("post_resume_failed")` and the caller MUST destroy the env.
      *
      * Note: a resumed guest's network/long-lived connections (git remote / API / registry) are NOT guaranteed to
-     * survive the snapshot (clay decision 2), so this is also where the VM-internal agent rebuilds those.
+     * survive the snapshot (decision 2), so this is also where the VM-internal agent rebuilds those.
      *
      * 🔴 Ordering red line (design/48 §5/#6): at-rest encryption of the memory snapshot must be ensured BEFORE
      * secrets are injected — never let plaintext credentials land in an unencrypted snapshot. That encryption is a
@@ -391,10 +391,10 @@ export interface RemoteExecutionEnv extends ExecutionEnv {
      * once on task end, and `prepareTask` calls it on a prepare-time throw; a remote impl may also be reaped,
      * so a defensive double-call must not error or double-bill.
      *
-     * 飞轮 [519] contract note: on a NON-isolated env (no `capabilities.isolation` — host lane, SSH host),
+     * contract note: on a NON-isolated env (no `capabilities.isolation` — host lane, SSH host),
      * destroy() is workspace/object-level cleanup and must NOT reap still-running background processes —
      * that is `disposeBackgroundShells`' job, which honours the timeout/session keep-alive except-list
-     * ([511]③ monitor timeout anchor). An isolated env (container/VM) naturally takes everything down;
+     * (monitor timeout anchor). An isolated env (container/VM) naturally takes everything down;
      * the Runner's envDying settle accounts for that with an accurate killed receipt beforehand.
      */
     destroy(): Promise<void>;
@@ -423,7 +423,7 @@ export interface ExecutionEnvFactoryContext {
      */
     isolation?: "worktree";
     /**
-     * Blackboard 2026-07-03 (clay dogfood — sub-agents landing in an EMPTY sandbox): the PARENT task's
+     * Field-reported (sub-agents landing in an EMPTY sandbox): the PARENT task's
      * effective working root, threaded (like `isolation`) via the TRUSTED `RunInternals` channel when this
      * task is a sub-agent (workflow `ctx.agent` / Task delegation). CC parity: a Task sub-agent inherits the
      * main session's cwd. A single-user/TOC factory SHOULD root the child env here (unless `isolation`
@@ -436,7 +436,7 @@ export interface ExecutionEnvFactoryContext {
 /**
  * A **trusted control-plane** factory that mints a per-task {@link ExecutionEnv} (design/48 §5 answers core
  * gap-a / §7 Q7). Lives on `RunnerDeps` (deployment-level) — NOT on `TaskSpec` — so an untrusted caller can
- * never inject its own env and escape the sandbox (design/44 §7 Q4 red line; clay decision 3: the Docker
+ * never inject its own env and escape the sandbox (design/44 §7 Q4 red line; decision 3: the Docker
  * fast-lane must be control-plane-assigned, never task-selectable).
  *
  * The remote model is "one container per task", so the factory is invoked once per task. The Runner owns the

package/dist/core/roles.d.ts

@@ -24,10 +24,10 @@ export declare const CC_MODEL_TIER_ALIASES: Readonly<Record<string, string>>;
  * - a binding may itself be a catalog name or a Model object (resolved through `resolveModel`);
  *   an unknown binding name throws at construction (config error surfaces at boot, not first use).
  */
-/** [1613] the DISPLAY face of a string model ref: a CC tier ALIAS (haiku/sonnet/…) resolves to its
+/** the DISPLAY face of a string model ref: a CC tier ALIAS (haiku/sonnet/…) resolves to its
  *  sema tier name (lite/flash/…) for labels — the alias verbatim reads as a strong claim about a
  *  specific vendor's model while the actual routing may land anywhere ("haiku" showing over a
- *  DeepSeek run, clay's field report). A non-alias string is the deployment's own model key — its
+ *  DeepSeek run, an operator field report). A non-alias string is the deployment's own model key — its
  *  honest name — and passes through unchanged. Display only; routing (`expandTiers`) is untouched. */
 export declare function resolveModelDisplayLabel(ref: string): string;
 export declare function expandTiers(models: Record<string, Model> | undefined, tiers: Record<string, ModelRef> | undefined): Record<string, Model> | undefined;
@@ -49,7 +49,7 @@ export interface ModelMention {
  */
 export declare function parseModelMention(text: string, allowedNames: Iterable<string>): ModelMention;
 /**
- * Role → 档位默认表(clay 拍 2026-07-11:「role 体系用户不感知」)。配了 `RunnerDeps.tiers` 的部署,
+ * Role → 档位默认表(裁定 2026-07-11:「role 体系用户不感知」)。配了 `RunnerDeps.tiers` 的部署,
  * 各 role 未显式配置时自动落到语义档位——用户/壳只感知档位,roles 降级为内部路由层:
  * - `default` → `pro`(主力档兜底;用户/部署 roles.default / TaskSpec.model 恒可覆盖);
  * - `summarize` → `flash`(压缩本该便宜;flash 未绑沿降档链到 lite);

package/dist/core/roles.js

@@ -102,6 +102,7 @@ const FALLBACK = {
     advisor: ["default"],
     verifier: ["default"],
     classifier: ["summarize", "default"],
+    consolidate: ["summarize"],
 };
 function specParts(s) {
     if (s == null) {

package/dist/core/runner/assemble-result.d.ts

@@ -42,7 +42,7 @@ export interface Stats {
             toolArg?: string;
         }>;
     };
-    /** TB telemetry B2 (service [397]): engine-mechanism engagement counters. Set by the run loop
+    /** TB telemetry B2: engine-mechanism engagement counters. Set by the run loop
      *  only when ≥1 engaged; flows straight through to `TaskResult.stats.mechanisms` via the
      *  public-stats spread. */
     mechanisms?: {
@@ -102,7 +102,7 @@ export interface ResultFlags {
     threw: unknown;
     /** design/99 MF-25: the EFFECTIVE (resolved) model id that served the task — echoed on `TaskResult.model`. */
     model?: string;
-    /** RB-368 ([2076]): some spend was accounted while the serving model had NO configured price table
+    /** RB-368: some spend was accounted while the serving model had NO configured price table
      *  (no `RunnerDeps.pricing` entry, no `Model.cost`). The numeric total is then a fabricated
      *  undercount — `stats.costMicroUsd`/`costBreakdown` are OMITTED from the public result instead of
      *  reporting a 0 indistinguishable from "declared free". The internal accumulator (budget gate's

package/dist/core/runner/compaction-call-options.d.ts

@@ -22,7 +22,7 @@ import type { Prepared } from "./prepare-task.js";
 /**
  * Opt-in working-file attachments (LONGRUN-2 / CC 198 post-compact restore parity).
  *
- * Blackboard 2026-07-03 (CC parity): post-compact file re-read is DEFAULT ON (CC hard-codes it;
+ * CC parity: post-compact file re-read is DEFAULT ON (CC hard-codes it;
  * LONGRUN-2 measured ≈2.3 extra read round-trips per compaction without it). `false` opts out; an
  * object customizes caps. Selection set = most recently READ (CC readFileState semantics) with a
  * modified-files fallback inside maybeCompact. Returns `undefined` when attachments are off or the
@@ -52,7 +52,7 @@ export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Pr
  */
 export declare function forkContextOption(prepared: Prepared, disable: boolean): Pick<MaybeCompactOptions, "forkContext">;
 /**
- * RB-31 ([1068]) — compaction-boundary center-candidate adoption. Absent (an empty object, NOT a
+ * RB-31 — compaction-boundary center-candidate adoption. Absent (an empty object, NOT a
  * `centerAdoption: undefined` key) = restate as before; a boundary re-pin hashes the same artifact
  * identity on every lane.
  */
@@ -106,7 +106,7 @@ export declare function projectStaleToolResults(context: Context, cfg: ResolvedS
  *  write-then-discard round-trip per stale result per turn. Caller owns the Set's lifetime. */
 writtenRefs: Set<string>): Promise<Context>;
 /**
- * MF-18 修② ([496]③) — fidelity disclosure: the summary INPUT was clipped to the compaction model's
+ * MF-18 修② — fidelity disclosure: the summary INPUT was clipped to the compaction model's
  * window. Fires pre-call, so the disclosure survives a failed attempt. All three lanes emit the SAME
  * frame; the end-of-task lane passes `spec.tracer ?? deps.tracer` / `spec.taskId ?? sessionId`
  * explicitly because `RunState.telemetry` (which holds exactly those two resolved values) is not in

package/dist/core/runner/memory-consolidation-driver.d.ts

@@ -0,0 +1,49 @@
+/**
+ * design/376 片② — the RUNNER convenience half of the consolidation driver: resolve the model
+ * seat out of a deployment's `RunnerDeps` (explicit chat seat wins; else the `consolidate` role
+ * chain) into the options `runMemoryConsolidationDriver` eats.
+ *
+ * Role resolution lives HERE and not in the engine-layer verb on purpose (design/339 §1.1 + the
+ * d2 ruling): the driver function's own seat is an explicit chat function — models, roles and
+ * tiers are runner vocabulary. The chain is `consolidate → summarize → coded refusal`, and the
+ * refusal is deliberate: one consolidation run reads the whole library (~10⁵ prompt tokens), so
+ * an unset role silently escalating to the most expensive `default` model would be the
+ * bad-value-silence family. A deployment that already declared a cheap `summarize` tier has made
+ * exactly the cost choice this role wants, so that hop stays; pointing `roles.consolidate` at the
+ * main model is a legal explicit choice.
+ */
+import type { Model } from "../../internal/llm.js";
+import type { Brain, ModelRoles, ModelRef, TaskSpec } from "../types.js";
+import { type DistillerChatFn } from "../memory-engine/distiller.js";
+import type { RunMemoryConsolidationOptions } from "../memory-engine/consolidation-driver.js";
+import type { MemoryConsolidationOptions } from "../memory-engine/consolidation.js";
+import type { LlmDistillerContract } from "../memory-engine/distiller.js";
+/** The slice of `RunnerDeps` this resolver reads (pass the deps object itself). */
+export interface MemoryConsolidationDriverDeps {
+    brain: Brain;
+    models?: Record<string, Model>;
+    tiers?: Record<string, ModelRef>;
+    roles?: ModelRoles;
+    memoryConsolidation?: MemoryConsolidationOptions;
+    memoryConsolidationDriver?: {
+        chat?: {
+            baseUrl: string;
+            apiKey: string;
+            model: string;
+        } | DistillerChatFn;
+        model?: string;
+        contract?: LlmDistillerContract;
+        maxCycles?: number;
+        mintRepairBudget?: number;
+    };
+    /** Optional per-model auth hook (the TaskSpec-shaped seat) for the role-resolved path. */
+    getApiKeyAndHeaders?: TaskSpec["getApiKeyAndHeaders"];
+}
+/**
+ * Resolve a deployment's driver options: `{ chat, model }` from the explicit seat or the role
+ * chain, plus the deployment knobs (contract / maxCycles / mintRepairBudget) and the protocol
+ * parameters (`memoryConsolidation`) threaded through verbatim. The result feeds
+ * `runMemoryConsolidationDriver(engine, scope, resolved)` directly; every bad value refuses
+ * coded here or in the verb's own screen (#123), never folds to a default.
+ */
+export declare function resolveMemoryConsolidationDriver(deps: MemoryConsolidationDriverDeps): RunMemoryConsolidationOptions;

package/dist/core/runner/memory-consolidation-driver.js

@@ -0,0 +1,60 @@
+import { brainToRuntime } from "../runtime.js";
+import { expandTiers, roleModelIfSet } from "../roles.js";
+import { isAliasModelId, openAiCompatChatSeat } from "../memory-engine/distiller.js";
+function seatRefusal(message) {
+    const e = new Error(message);
+    e.code = "config.memory_consolidation_driver";
+    return e;
+}
+export function resolveMemoryConsolidationDriver(deps) {
+    const seat = deps.memoryConsolidationDriver;
+    let chat;
+    let model;
+    if (typeof seat?.chat === "function") {
+        if (typeof seat.model !== "string" || seat.model.trim() === "" || isAliasModelId(seat.model)) {
+            throw seatRefusal(`memoryConsolidationDriver.chat is a bare function, so memoryConsolidationDriver.model must carry the EXPLICIT model id it serves (got ${JSON.stringify(seat.model)}).`);
+        }
+        chat = seat.chat;
+        model = seat.model;
+    }
+    else if (seat?.chat !== undefined) {
+        chat = openAiCompatChatSeat(seat.chat);
+        model = seat.chat.model;
+    }
+    else {
+        const models = expandTiers(deps.models, deps.tiers);
+        const resolved = roleModelIfSet("consolidate", {}, { models, roles: deps.roles }) ?? roleModelIfSet("summarize", {}, { models, roles: deps.roles });
+        if (resolved === undefined) {
+            throw seatRefusal('memory consolidation has no model seat: configure RunnerDeps.memoryConsolidationDriver.chat (an endpoint triple or a chat function), or declare roles.consolidate / roles.summarize (a tier-expanded catalog\'s "flash" binding also satisfies the summarize hop). The chain deliberately does NOT fall back to the default main model — a whole-library distillation must not silently ride the most expensive seat.');
+        }
+        if (isAliasModelId(resolved.id)) {
+            throw seatRefusal(`the resolved consolidation model id ${JSON.stringify(resolved.id)} is an alias spelling — an alias can be re-pointed upstream and would move the run with no trace in the archive; bind an explicit id.`);
+        }
+        model = resolved.id;
+        const runtime = brainToRuntime(deps.brain);
+        chat = async (req) => {
+            const auth = await deps.getApiKeyAndHeaders?.(resolved);
+            const message = await runtime.completeSimple(resolved, { systemPrompt: req.system, messages: [{ role: "user", content: req.user, timestamp: Date.now() }] }, { temperature: req.temperature, maxTokens: req.maxTokens, apiKey: auth?.apiKey, headers: auth?.headers });
+            if (message.stopReason === "error" || message.stopReason === "aborted") {
+                throw new Error(message.errorMessage ?? `model completion ${message.stopReason}`);
+            }
+            return {
+                content: message.content
+                    .filter((c) => c.type === "text")
+                    .map((c) => c.text)
+                    .join(""),
+                finishReason: message.stopReason,
+                usage: { promptTokens: message.usage.input, completionTokens: message.usage.output },
+                model: resolved.id,
+            };
+        };
+    }
+    return {
+        chat,
+        model,
+        ...(seat?.contract !== undefined ? { contract: seat.contract } : {}),
+        ...(seat?.maxCycles !== undefined ? { maxCycles: seat.maxCycles } : {}),
+        ...(seat?.mintRepairBudget !== undefined ? { mintRepairBudget: seat.mintRepairBudget } : {}),
+        ...(deps.memoryConsolidation !== undefined ? { consolidation: deps.memoryConsolidation } : {}),
+    };
+}

package/dist/core/runner/memory-consolidation.d.ts

@@ -27,7 +27,7 @@ export declare const DEFAULT_CONSOLIDATION_MAX_NOTES = 50;
 export declare const DEFAULT_CONSOLIDATION_TIMEOUT_SEC = 30;
 /** Normalize a note body for the EXACT-restatement check in the `<lo` near-dup cheap path. Case- + whitespace-
  *  insensitive ONLY (lower-case, collapse whitespace runs, trim); it PRESERVES every symbol/punctuation so it can
- *  NOT false-equate semantically-distinct facts. (service [365] falsification-style: the earlier `[^\p{L}\p{N}]`-stripping
+ *  NOT false-equate semantically-distinct facts. (falsification-style: the earlier `[^\p{L}\p{N}]`-stripping
  *  normalization made "C#"≡"C", "delta +5"≡"delta -5", "100%"≡"100" — and a textual-CONTAINMENT test on top of it
  *  also mis-judged "rate limit 1000" ⊇ "rate limit 100" (word boundary). A fire-on-every-note, no-LLM path must not
  *  make a semantic-subset call, so the cheap path now folds ONLY an exact restatement; every real near-dup defers

package/dist/core/runner/prepare-config-doors.d.ts

@@ -46,17 +46,17 @@ export declare function limitConfigError(code: string, message: string): Error &
  */
 export declare function resolveTaskLimits(limits: TaskLimits | undefined): TaskLimits | undefined;
 /**
- * R2 双形轴(clay 追加令 2026-07-18): CC 2.1.212's fable-variant prompt gate (b9e —
+ * R2 双形轴(追加令 2026-07-18): CC 2.1.212's fable-variant prompt gate (b9e —
  * `fable_5_mitigations` capability / claude-mythos-5), ORTHOGONAL to the simple/classic profile.
  * sema is BYOM, so the id may carry provider prefixes ("anthropic/claude-fable-5",
  * "openrouter/anthropic/claude-fable-5"): BOUNDARY-AWARE family match on the last path segment
- * (codex 统一复审 F3 — raw substring classified "vendor/not-claude-fable-5" and "claude-mythos-50"
+ * (统一复审 F3 — raw substring classified "vendor/not-claude-fable-5" and "claude-mythos-50"
  * as fable), case-normalized. Recognition set = CC's _Nr (startsWith "claude-fable-") + b9e
  * (mythos-5). R3 system sections fork on the resulting fact.
  */
 export declare function isFableFamilyModelId(id: string): boolean;
 /**
- * RB-50 (CC 2.1.220 启示①, clay 2026-07-25): the SINGLE decision point for the two prompt-shape axes.
+ * RB-50 (CC 2.1.220 启示①, 2026-07-25): the SINGLE decision point for the two prompt-shape axes.
  * Both were resolved in separate places with different mechanisms — `promptProfile` off a TaskSpec field,
  * `fableMitigations` off a raw model-id prefix test — so "which shape does this task speak" had no one
  * place to read. CC 2.1.220's counterpart is a model-registry `capabilities` array (one table drives

package/dist/core/runner/prepare-task.d.ts

@@ -329,13 +329,13 @@ export interface Prepared {
             chars: number;
             hash: string;
         }>;
-        /** Manifest v2 (campaign S1, additive): the compiled-IR section view (slot/carrier/cadence/
+        /** Manifest v2 (stage S1, additive): the compiled-IR section view (slot/carrier/cadence/
          *  cacheClass per section). `contentHash` is the
-         *  digest-tiering face ([1050]②/[1057]): present ONLY on operator-declared sections (the typed
+         *  digest-tiering face: present ONLY on operator-declared sections (the typed
          *  `stableBlocks` lane, owner "deployment") as an UNSALTED full sha256 of the section text —
          *  the center-publish ↔ manifest end-to-end reconciliation anchor. Core-native sections (env
          *  facts, memory tail, user role text) stay salted-only: a plain hash of a short guessable
-         *  block is a dictionary-preimage surface for trace readers (codex [E]). */
+         *  block is a dictionary-preimage surface for trace readers ([E]). */
         sections?: Array<{
             id: string;
             slot: string;
@@ -346,7 +346,7 @@ export interface Prepared {
             hash: string;
             contentHash?: string;
         }>;
-        /** Campaign S2 (additive): the mounted tools plane — contract identity, durable-replay aliases,
+        /** S2 (additive): the mounted tools plane — contract identity, durable-replay aliases,
          *  presentation-invariant shape digest and full wire digest per tool (initial mount face). */
         tools?: ToolManifestRow[];
         /** design/148 S3 (additive, §10.2): the nine-element cache identity — digests only, no prompt
@@ -363,7 +363,7 @@ export interface Prepared {
          *  seat chose it. Absent when nothing is deferred (there is no disclosure to describe). */
         toolDisclosure?: ToolDisclosureManifest;
     };
-    /** [1068] ruling a — this run's provider-declared prompt sections (epoch declaration axis),
+    /** This run's provider-declared prompt sections (epoch declaration axis),
      *  threaded to every compaction-boundary epoch selection so boundary re-pins hash the same
      *  artifact identity as the prepare-time pin. Empty on declaration-free runs. */
     epochDeclaredSections: import("../../prompt-assembly/epoch.js").EpochDeclaredSections;
@@ -690,7 +690,7 @@ export interface Prepared {
      *  RB-197: seeded entries are excluded — their content lives in the system-prompt lane, which
      *  compaction never touches, so re-attaching them into the summary would be a duplicate. */
     recentlyReadFiles?: () => string[];
-    /** RB-197②(独立复审 + codex 命中,已修) — canonicalizes a raw (often relative, model-typed) path the
+    /** RB-197②(独立复审 + 命中,已修) — canonicalizes a raw (often relative, model-typed) path the
      *  SAME way the hands toolkit does (`resolveKey` against the same containment root `readTaskFile`
      *  uses), so `maybeCompact`'s kept-tail/instruction-source exclusions compare paths in the SAME
      *  coordinate `recentlyReadFiles()` already uses — without this a plain string match silently never
@@ -698,7 +698,7 @@ export interface Prepared {
      *  readTaskFile); absent there is no containment root to resolve against, and every path source is
      *  already in the same raw coordinate anyway. */
     normalizeAttachmentPath?: (raw: string) => Promise<string>;
-    /** RB-197②(codex 交叉复审命中,已修) — recognizes the hands Read tool's own dedup-stub markers
+    /** RB-197②(交叉复审命中,已修) — recognizes the hands Read tool's own dedup-stub markers
      *  ({@link isReadDedupStubResult}), so `maybeCompact`'s kept-tail scan can tell a SUBSTANTIVE Read
      *  result from a stub hit whose original full transmission may already be summarized away. Present
      *  only with hands (same gate as readTaskFile). */
@@ -707,7 +707,7 @@ export interface Prepared {
      *  `MaybeCompactOptions.onApplied` by every compaction lane. Drops the non-seeded read-state entries
      *  (the summary just replaced the Read results the dedup stubs point at) and re-registers the files
      *  that were re-attached WHOLE. Present only with hands (same gate as readTaskFile).
-     *  RB-197②(codex 命中,已修): `preserveReadState` carries the kept-tail-visible files that were
+     *  RB-197②(命中,已修): `preserveReadState` carries the kept-tail-visible files that were
      *  deliberately skipped for re-attachment — their existing entry must survive the clear too (same
      *  reasoning as a seeded entry: the model's view of the file did not change). */
     onCompactionApplied?: (attachedComplete: ReadonlyArray<{
@@ -731,7 +731,7 @@ export interface Prepared {
     planModeRef: {
         active: boolean;
     };
-    /** [915] A1 (design/66 anchor revision) — the date-flip detector seam: `legDate` = the date frozen
+    /** A1 (design/66 anchor revision) — the date-flip detector seam: `legDate` = the date frozen
      *  into this leg's system prefix; `today()` = the boundary-time LOCAL date (user-zone-bound closure).
      *  The run loop feeds both to the `date_change` attachment producer; the prefix itself never
      *  re-renders mid-leg (cache preservation, CC parity). Present only when the prompt carries a date. */
@@ -953,7 +953,7 @@ export interface PrepareResume {
     /** Digest of that question's batch — the id alone can repeat, so the pairing is what keeps a LATER
      *  question from inheriting the claim that an operator approved it. */
     redeemedContentAskQuestionsHash?: string;
-    /** codex 1360 r6 — true iff this resume will EXECUTE an approved pending tool (`tool_approval`
+    /** true iff this resume will EXECUTE an approved pending tool (`tool_approval`
      *  checkpoint × an `allow` winner). The divergent-restore fail-closed guard keys on THIS, not on the
      *  batch being non-empty: a deny winner executes nothing, so a workspace-root divergence must not
      *  wedge the refusal (it proceeds under the path-state rebase and records the deny). */
@@ -1089,14 +1089,14 @@ export interface InheritedGate {
         /**
          * The environment this screening face was installed against — the source of the `HookEnvCapabilities`
          * handed to it, compared BY REFERENCE, `undefined` when the installation had no env face. Part of the
-         * installation's identity for the same reason the frozen approver is (codex review, HIGH): a face that
+         * installation's identity for the same reason the frozen approver is (HIGH): a face that
          * resolves paths through `ctx.env` answers a different question in a different environment, so an
          * ancestor running against the deployment's tree and a descendant running in an isolated worktree are
          * two screenings, not one. A deployment with a per-task `executionEnvFactory` therefore has its face
          * consulted once per environment on the chain rather than once overall — which is the point: the
          * ancestor's environment is the only place the ancestor's verdict can be reproduced.
          *
-         * ⚠️ RECORDED BOUNDARY (delegation provenance, codex review): the approver half of the key compares
+         * ⚠️ RECORDED BOUNDARY (delegation provenance): the approver half of the key compares
          * through {@link askApproverIdentity}, which by its own contract answers "the same decision-maker",
          * collapsing a `withDelegationProvenance` wrapper onto the approver it forwards to. Two installations
          * whose approvers differ ONLY in the provenance they attach therefore count as one. Raw reference
@@ -1270,7 +1270,7 @@ export interface RunInternals {
      */
     reminderMark?: string;
     /**
-     * RB-204 P1 (codex review) — set UNCONDITIONALLY by every core spawn path (`createSubagentTool`'s
+     * RB-204 P1 — set UNCONDITIONALLY by every core spawn path (`createSubagentTool`'s
      * `childInternals` — shared by all four spawn legs sync/steer/background/fork, its persisted
      * `internalsSnapshot` for revive, and the workflow orchestrator's `spawnAttribution`), regardless
      * of whether a NAMEABLE `parentTaskId`/`parentToolCallId` exists. A directly-started workflow (no
@@ -1310,7 +1310,7 @@ export interface RunInternals {
      * Why internal (not a public `TaskSpec.goalMode`): the guidance promises "declaring done STOPS iteration and
      * surfaces" — a promise only `runGoal`'s loop makes real. A public field would let a caller inject that
      * prompt with no loop behind it (§6.3 honesty violation). `runGoal` injects the `declare_done` tool itself;
-     * this flag only governs the PROMPT (codex r2 — injection-ownership split).
+     * this flag only governs the PROMPT (injection-ownership split).
      */
     goalMode?: boolean;
     /**
@@ -1353,7 +1353,7 @@ export interface RunInternals {
      */
     agentName?: string;
     /**
-     * design/147 S3 (codex R3 label-vs-identity): the EXPLICIT `Agent({name})` spawn identity — set
+     * design/147 S3 (label-vs-identity): the EXPLICIT `Agent({name})` spawn identity — set
      * ONLY when the spawn carried a `name` parameter, unlike {@link agentName} (a DISPLAY label:
      * description or agent-type, present on nearly every spawn). Teammate semantics (hierarchy clamp,
      * teammate addendum, uplink attribution) key on THIS field; keying on the display label made
@@ -1393,7 +1393,7 @@ export interface RunInternals {
      * {@link delegationTaskType} above. TRUSTED run-scoped channel (never a TaskSpec field).
      */
     cycleSeq?: number;
-    /** δ 批 [1498]⑦/A-3 — the ROOT host session of the whole delegation tree (fixed point: the
+    /** The ROOT host session of the whole delegation tree (fixed point: the
      *  spawner passes its own `ctx.rootSessionId ?? ctx.sessionId`, so depth 1 gets the host session
      *  and every deeper level inherits it verbatim). `parentSessionId` is the IMMEDIATE spawner —
      *  after a restart those intermediate sessions are dead ends, and a recovery face enumerating
@@ -1421,7 +1421,7 @@ export interface RunInternals {
      * delegation tool resolves this axis TO that principal.
      */
     registryScope?: string;
-    /** design/148 S1 (codex F2a) — the spawning run's ADOPTED center artifact, threaded down the
+    /** design/148 S1 — the spawning run's ADOPTED center artifact, threaded down the
      *  trusted internals chain so every child in the tree composes the SAME closure (a child must
      *  never spontaneously adopt the live candidate while its parent runs an older pin — that is the
      *  exact mixed-version state the epoch exists to prevent). Resolved by-digest through the
@@ -1482,7 +1482,7 @@ export interface RunInternals {
         priority?: import("../task-notification.js").SystemInjectionPriority;
     }) => void;
     /**
-     * design/147 S3a (codex F2) — the PARENT run's subagent-retain ledger, threaded to a CHILD so its
+     * design/147 S3a — the PARENT run's subagent-retain ledger, threaded to a CHILD so its
      * SendMessage can continue a RETAINED SIBLING (the sibling's retain entry lives on the parent's
      * ledger — without this, sibling resolution succeeds but delivery always reads not-retained).
      * TRUSTED chain; read-only use (the sibling leg resumes through the same fenced resume face).
@@ -1522,7 +1522,7 @@ export interface RunInternals {
      */
     parentCwd?: string;
     /**
-     * [c209-D] codex R3 — the EXPLICIT Agent.cwd request, distinct from the best-effort `parentCwd`
+     * [c209-D] — the EXPLICIT Agent.cwd request, distinct from the best-effort `parentCwd`
      * inheritance hint above: inheritance may be silently ignored by a factory (or absent without one),
      * but an explicit cwd the model asked for MUST either take effect or fail loud. prepareTask enforces
      * the contract: no `executionEnvFactory` ⇒ throw `config.cwd_unsupported`; after env creation the
@@ -1558,7 +1558,7 @@ export interface RunInternals {
      */
     onActivity?: (activity: ToolActivity) => void;
     /**
-     * RB-393① (黑板 [2107]②) — a TRUSTED run-scoped WORKSPACE-observation sink, filled ONLY by a core caller
+     * RB-393① — a TRUSTED run-scoped WORKSPACE-observation sink, filled ONLY by a core caller
      * (the workflow's `ctx.agent` / `ctx.agentStream`, to record an isolated agent's worktree directory on the
      * persisted run record). NEVER a {@link TaskSpec} field — same posture as {@link onActivity}.
      *
@@ -1566,7 +1566,7 @@ export interface RunInternals {
      * {@link RunnerDeps.executionEnvFactory} and lands only on the per-task env's `cwd`; no runner-outward face
      * (TaskEvent union / TaskStream / TaskResult) carries it back. An orchestrator therefore could not record
      * WHERE its isolated agent worked — the recovery path after an interrupted run had to enumerate the
-     * worktrees directory and guess, which is exactly the contradiction [2113] recorded against the
+     * worktrees directory and guess, which is exactly the contradiction recorded against the
      * "isolate-only, userland decides verify/merge" intent.
      *
      * Called at most ONCE per prepared run with the task's FINAL working root (see {@link ResolvedWorkspace}),

package/dist/core/runner/prepare-task.js

@@ -22,7 +22,7 @@ import { createSendMessageTool, SEND_MESSAGE_TOOL_NAME } from "../../agents/send
 import { SubagentRetainLedger } from "../../agents/retain-ledger.js";
 import { askApproverIdentity, checkToolPolicyProjection, combinePolicies, constraintChainDigest, constraintChainEntryOf, isApprovalSettledBy, isAskDenyResolution, screenApproverAttribution, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, describeThrown, refuseOutOfContractDecision, resolveAsk, toolPolicyNameSets, tryCloneArgs } from "../tool-policy.js";
 const PERSISTED_RULE_TOOL = "Bash";
-import { findAdmittingRule, suggestRulesForCommand } from "../permission-rule-model.js";
+import { findAdmittingRule, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
 import { ActiveSkillScope, createActiveSkillScopePolicy } from "./active-skill-scope.js";
 import { CHANGED_FILES_MTIME_EPS_MS, fenceMcpServerInstructions, renderAgentListingDelta } from "./turn-attachments.js";
 import { inlineUntrusted } from "../untrusted-text.js";
@@ -437,7 +437,9 @@ function orgRevisionEvidenceOf(resolution, onDefect) {
     return {};
 }
 function persistedRuleHitOf(admitting) {
-    return admitting === undefined ? undefined : { rule: admitting.rule, dots: admitting.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) };
+    return admitting === undefined
+        ? undefined
+        : { rules: admitting.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
 }
 function cwdConflictsRestoreError(requestedCwd) {
     const e = new Error(`RunInternals.requestedCwd ("${requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +
@@ -480,7 +482,7 @@ async function derivedRouteFallsBack(args) {
         const verdict = await adjudicateDerivedRoute({ brain: args.brain, model: args.derived, getApiKeyAndHeaders: args.getApiKeyAndHeaders });
         if (verdict === undefined || verdict.ok)
             return false;
-        deliverEngineNotice(args.onNotice, fallbackToPrimaryNotice({ seat: args.seat, from: args.derived.id, to: args.primary.id, verdict }));
+        deliverEngineNotice(args.onNotice, fallbackToPrimaryNotice({ seat: args.seat, from: args.derived.id, to: args.primary.id, verdict, ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}) }));
         return true;
     }
     catch {
@@ -507,7 +509,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     let effectiveCompModel = compModel;
     if (spec.compactionModel === undefined &&
         compModel !== undefined &&
-        (await derivedRouteFallsBack({ seat: "compaction-summary", derived: compModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice }))) {
+        (await derivedRouteFallsBack({ seat: "compaction-summary", derived: compModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId }))) {
         effectiveCompModel = undefined;
     }
     warnCompactionWindowHazard(deps.tracer, spec, model, effectiveCompModel, hostTaskId);
@@ -1094,7 +1096,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             catch {
                 classifierModel = model;
             }
-            if (await derivedRouteFallsBack({ seat: "auto-mode-classifier", derived: classifierModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice })) {
+            if (await derivedRouteFallsBack({ seat: "auto-mode-classifier", derived: classifierModel, primary: model, brain: deps.brain, getApiKeyAndHeaders: spec.getApiKeyAndHeaders, onNotice: deps.onNotice, sessionId })) {
                 classifierModel = model;
             }
             const classifierSystemPrompt = buildAutoModePrompt(am);
@@ -3019,7 +3021,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         }));
                         return { unreadable: true };
                     }
-                    return persistedRuleHitOf(findAdmittingRule(listed.rules, { tool: req.toolName, command, cwd: root }));
+                    const admitting = findAdmittingRule(listed.rules, { tool: req.toolName, command, cwd: root });
+                    if (admitting !== undefined)
+                        return persistedRuleHitOf(admitting);
+                    const coverage = segmentCoverageOf(command, { persisted: listed.rules }, { tool: req.toolName, cwd: root });
+                    return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
                 },
             };
         })();
@@ -3049,7 +3055,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 },
             };
         })();
-        const ruleSuggestionsOf = (toolName, args, ask) => {
+        const ruleOffersOf = (toolName, args, ask) => {
             if (permissionRuleLane === undefined || toolName !== PERSISTED_RULE_TOOL)
                 return {};
             if ((spec.principal === undefined || spec.principal === "") && deps.localOwnerRules !== true)
@@ -3071,8 +3077,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             const command = args?.command;
             if (typeof command !== "string")
                 return {};
-            const suggestions = suggestRulesForCommand(command);
-            return suggestions.length > 0 ? { ruleSuggestions: suggestions } : {};
+            const offers = suggestRulesForCommand(command, ask?.segmentCoverage !== undefined ? { coverage: ask.segmentCoverage } : undefined);
+            return offers.length > 0 ? { ruleOffers: offers } : {};
         };
         const frozenClassifierExcluded = (d) => d.decisionReason === "hook" || d.matchedAskRule !== undefined;
         const recheckApprovedEdit = async (pol, onAskOf, creq, edit, csignal, ancestorDecider) => {
@@ -3121,7 +3127,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     toolName: creq.toolName,
                     toolCallId: creq.toolCallId,
                     args: editArgs,
-                    ...ruleSuggestionsOf(creq.toolName, editArgs, { ...(re ?? {}), ancestorResolved: true }),
+                    ...ruleOffersOf(creq.toolName, editArgs, { ...(re ?? {}), ancestorResolved: true }),
                     message: re.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                     ...askSourceIdentity(),
                     ...riskAxesOf(creq.toolName),
@@ -3207,7 +3213,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: creq.toolName,
                             toolCallId: creq.toolCallId,
                             args: presentedArgs,
-                            ...ruleSuggestionsOf(creq.toolName, presentedArgs, { ...(first.action === "ask" ? first : {}), ancestorResolved: true }),
+                            ...ruleOffersOf(creq.toolName, presentedArgs, { ...(first.action === "ask" ? first : {}), ancestorResolved: true }),
                             message: first.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
@@ -3295,7 +3301,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: creq.toolName,
                             toolCallId: creq.toolCallId,
                             args: presentedArgs,
-                            ...ruleSuggestionsOf(creq.toolName, presentedArgs, { ...(decision.action === "ask" ? decision : {}), ancestorResolved: true }),
+                            ...ruleOffersOf(creq.toolName, presentedArgs, { ...(decision.action === "ask" ? decision : {}), ancestorResolved: true }),
                             message: decision.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
@@ -3587,7 +3593,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const preview = approvalPreviewOf(req.toolName, req.args);
                         return preview !== undefined ? { preview } : {};
                     })(),
-                    ...ruleSuggestionsOf(req.toolName, req.args, decision.action === "ask" ? decision : undefined),
+                    ...ruleOffersOf(req.toolName, req.args, decision.action === "ask" ? decision : undefined),
                     message: decision.message ?? `approval required for "${req.toolName}"`,
                     ...askSourceIdentity(),
                     ...riskAxesOf(req.toolName),
@@ -4064,7 +4070,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
             };
             const suspendAsk = parkLaneArmed && checkpointStore !== undefined
-                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule, askDecisionReason, probeReason, probeCause) => {
+                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule, askDecisionReason, probeReason, probeCause, segmentCoverage) => {
                     const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
                     if (syncFirstEligible &&
                         runtimeCaps?.forceDurableGate !== true &&
@@ -4225,11 +4231,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                     const preview = approvalPreviewOf(req.toolName, parkedArgs);
                                     return preview !== undefined ? { preview } : {};
                                 })(),
-                                ...ruleSuggestionsOf(req.toolName, parkedArgs, {
+                                ...ruleOffersOf(req.toolName, parkedArgs, {
                                     ...(realApproval !== undefined ? { requiresRealApproval: true } : {}),
                                     ...(shadowedRule !== undefined ? { persistedRuleShadowed: shadowedRule } : {}),
                                     ...(askDecisionReason !== undefined ? { decisionReason: askDecisionReason } : {}),
                                     ...(inheritedUnavailableAsks.has(req.toolCallId) ? { inheritedUnresolved: true } : {}),
+                                    ...(segmentCoverage !== undefined ? { segmentCoverage } : {}),
                                 }),
                                 boundInputHash: boundInputHashOf(parkedArgs),
                                 batchToolCallIds,
@@ -4355,11 +4362,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                         admits: permissionRuleLane.admits,
                                         onResolved: (info) => emitTrace(deps.tracer, () => ({
                                             kind: "permission.persisted_rule_allowed",
-                                            version: 1,
+                                            version: 2,
                                             taskId: spec.taskId ?? sessionId,
                                             toolName: info.toolName,
                                             toolCallId: info.toolCallId,
-                                            rule: info.rule,
+                                            rules: [...info.rules],
                                             ts: Date.now(),
                                         })),
                                     },