@sema-agent/core 7.4.0 → 7.5.1

package/dist/core/runner/contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/core/runner/denial-limit-arms.d.ts

@@ -1,7 +1,9 @@
-import { type AutoModeDecider, type AutoModeDenialLimitOptions, type AutoModeDenialTracker, type DenialLimitFallback } from "../auto-mode.js";
+import { type AutoModeDecider, type AutoModeDenialLimitOptions, type AutoModeDenialTracker, type DenialLimitFallback, type DenialLimitFallbackFace, type UnarmedDenialLimitFallback } from "../auto-mode.js";
+import { type AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import type { PermissionResult, ResolvedAsk, ToolCallRequest } from "../tool-policy.js";
 import { type EngineNotice } from "../types.js";
-import type { Prepared } from "./prepare-task.js";
+import { type AskOrigin } from "../ask-origin.js";
+import type { Prepared } from "./contracts.js";
 /**
  * #548 — the classifier DENIAL-LIMIT arms of the tool gate's inherited (delegation) lane, extracted
  * from `prepareTask` as a phase module (design/238 D-7: extract, don't accrete). The gate's OWN
@@ -11,28 +13,43 @@ import type { Prepared } from "./prepare-task.js";
  *  · the frozen classifier's judgment with the count-then-fallback step, shared by the two inherited
  *    wrapper arms and the approved-edit re-check ({@link judgeInheritedClassifier});
  *  · the post-resolution settlement of a fallback ask — a person's allow resets the streak, a deny
- *    nobody made stops the run ({@link settleDenialLimitFallback}).
+ *    nobody made stops the run ({@link settleDenialLimitFallback});
+ *  · the request-side carry of the ask's origin word and its fallback member, with the auto-deny window
+ *    armed at the hand-out to a live approver and nowhere else ({@link gateAskCarry} for the gate's own
+ *    station, {@link inheritedAskCarry} for the three inherited-lane ones).
  * Each helper is pure over what prepare hands it; the fold/ask seams themselves stay in the runner.
  */
-/** An ancestor chain entry's classifier half as the arms read it: the decider and, beside it, the
- *  per-run denial tracker (absent on an entry that counts nothing). */
+/** An ancestor chain entry's classifier half as the arms read it: the decider, the per-run denial
+ *  tracker beside it (absent on an entry that counts nothing), and — on a re-supplied entry — the
+ *  ancestor's recorded arming recipe, whose denial-limit bounds the fresh tracker is built under. */
 export interface InheritedAutoMode {
     decider: AutoModeDecider;
     denialTracking?: AutoModeDenialTracker;
+    arming?: AutoModeArmingRecipe;
 }
 /**
  * A re-supplied chain entry (a cross-process redemption rebuilt its ancestor's classifier from the
  * recorded recipe — `rebuildAutoModeDecider` hands back a decider and its arming, nothing live)
  * carries no denial tracker, and an entry with a decider but no tracker would count nothing: the
  * rebuilt classifier could block without bound on the redeemed leg, the exact gap the limit closes.
- * Attach a FRESH tracker under this deployment's own bounds (a fresh count is the documented
- * cross-process semantics — the breaker restarts the same way). Entries that already carry one (the
- * in-process chain from a live ancestor) are kept BY IDENTITY; only a tracker-less armed entry is
- * re-wrapped (its `policy`, the identity the fold and the pass-through compare, is untouched).
- * ONE tracker per DECIDER identity, not per entry: a parent attaches its one decider to both its
- * hook entry and its caller-policy entry, and a count split across two trackers could alternate
- * forever without either reaching the bound. The tracker is minted lazily, so a bad bound refuses
- * only a prepare that actually has such an entry (the armed leg's own mint screens the knob first).
+ * Attach a FRESH tracker (a fresh COUNT is the documented cross-process semantics — the breaker
+ * restarts the same way) under the ancestor's recorded BOUNDS tightened by this deployment's own
+ * (#556, `tightenDenialLimit` — the same rule and the same call the arming fold makes, so the
+ * recipe's account of the criteria and the tracker's actual bounds cannot drift). Before #556 the
+ * bounds came from this deployment alone, so an ancestor that allowed three consecutive blocks
+ * before a person had to look could be redeemed into a leg that allowed five. An entry with no
+ * READABLE recipe leaves the deployment's own bounds in force — there is no ancestor account to bind
+ * by, and manufacturing one would state criteria nobody chose.
+ *
+ * Entries that already carry a tracker (the in-process chain from a live ancestor) are kept BY
+ * IDENTITY; only a tracker-less armed entry is re-wrapped (its `policy`, the identity the fold and
+ * the pass-through compare, is untouched). ONE tracker per DECIDER identity, not per entry: a parent
+ * attaches its one decider to both its hook entry and its caller-policy entry, and a count split
+ * across two trackers could alternate forever without either reaching the bound. The bounds are
+ * therefore folded across EVERY entry naming that decider before any tracker is minted — two entries
+ * of one decider carrying different recipes get the strictest reading of the two rather than
+ * whichever the iteration happened to reach first. The mint stays lazy, so a bad bound refuses only a
+ * prepare that actually has such an entry (the armed leg's own mint screens the knob first).
  */
 export declare function attachRebuiltDenialTrackers<T extends {
     autoMode?: InheritedAutoMode;
@@ -41,7 +58,7 @@ export declare function attachRebuiltDenialTrackers<T extends {
 export type StopForDenialLimit = (info: {
     toolName: string;
     toolCallId: string;
-    fallback: DenialLimitFallback;
+    fallback: DenialLimitFallbackFace;
 }) => void;
 /**
  * The gate's typed stop seat (`Prepared.gateStopRef`) and the one closure that fills it — the headless
@@ -65,20 +82,24 @@ export declare function createDenialLimitStop(opts: {
 export type InheritedAsk = Extract<PermissionResult, {
     action: "ask";
 }>;
-/**
- * The delegation half of the two classifier exclusions the LIVE gate enforces: an ask raised by a hook
- * (`decisionReason:"hook"`, engine-stamped, never self-supplied) and an ask minted by an explicit `ask`
- * permission rule (`matchedAskRule`) are exactly as out of the FROZEN classifier's reach as the live
- * one's — the person's / hook's standing decision travels with the frozen entry, and a frozen decider
- * resolving it would re-open the same hole one process over. An ask that already IS a denial-limit
- * fallback (a deeper ancestor's) is not re-judged either. Excluded asks fall through to the frozen
- * approver chain, the delegation lane's original chain.
- */
-export declare function frozenClassifierExcluded(d: {
-    decisionReason?: string;
-    matchedAskRule?: string;
-    denialLimitFallback?: unknown;
-}): boolean;
+/** The members of a surviving ask that ride onto the approval request with a COMPUTED value — what the
+ *  four request mint stations (the gate's own and the three inherited-lane ones) spread after the seats
+ *  they spell themselves: the ask's origin word and its denial-limit fallback. */
+export interface AskRequestCarry {
+    origin?: AskOrigin;
+    denialLimitFallback?: DenialLimitFallback;
+}
+/** The GATE's own mint station: both members are read off the surviving decision, which is the gate's
+ *  OWN snapshot (its stamp point spreads the policy's object and stamps the word onto the copy), so the
+ *  origin is the engine-derived one and the member is the one the gate's classifier step minted. */
+export declare function gateAskCarry(decision: InheritedAsk, liveApprover: boolean, tracker: AutoModeDenialTracker | undefined): AskRequestCarry;
+/** An INHERITED-lane mint station (the two wrapper arms and the approved-edit re-check): the ask is an
+ *  ancestor policy's own decision, never engine-stamped, so BOTH members come from the judgment
+ *  {@link judgeInheritedClassifier} handed back — the word it derived under the station facts and the
+ *  fallback member it captured — each read ONCE there and threaded here, never re-read off the
+ *  caller-owned object (a stateful accessor could otherwise answer the card with one value and the
+ *  settlement with another; a self-declared `origin` on the ancestor's decision is never read). */
+export declare function inheritedAskCarry(origin: AskOrigin, fallback: UnarmedDenialLimitFallback | undefined, liveApprover: boolean, tracker: AutoModeDenialTracker | undefined): AskRequestCarry;
 /** What {@link judgeInheritedClassifier} hands back to the arm that called it. */
 export type InheritedClassifierJudgment<A extends InheritedAsk> = 
 /** The frozen classifier allowed — the arm returns its own allow shape (with or without the ask's rewrite). */
@@ -92,12 +113,17 @@ export type InheritedClassifierJudgment<A extends InheritedAsk> =
 }
 /** Proceed to the frozen approver with `ask`: the incoming ask unchanged (classifier unavailable,
  *  excluded, or not armed), or — at the bound — the fallback ask minted from it (`mintedHere`).
- *  `fallback` is the member riding the ask either way (an incoming one is a deeper ancestor's). */
+ *  `fallback` is the member riding the ask either way (an incoming one is a deeper ancestor's).
+ *  `origin` is the ask's word under the station facts, threaded to the request mint: on the two
+ *  unchanged-ask branches it is the SAME read the exclusion judged by (a caller-owned decision with a
+ *  stateful accessor cannot answer the exclusion with one word and the card with another); on the
+ *  bound branch it is derived from the re-spoken ask this station minted (its own object). */
  | {
     kind: "resolve";
     ask: A;
-    fallback: DenialLimitFallback | undefined;
+    fallback: UnarmedDenialLimitFallback | undefined;
     mintedHere: boolean;
+    origin: AskOrigin;
 };
 /**
  * The ancestor's frozen classifier, run BEFORE its frozen approver in the ancestor's own gate order,
@@ -138,7 +164,7 @@ export declare function headlessDenyAtRecheck(r: FallbackResolution): boolean;
  * when the ask was not a fallback.
  */
 export declare function settleDenialLimitFallback(opts: {
-    fallback: DenialLimitFallback | undefined;
+    fallback: UnarmedDenialLimitFallback | undefined;
     mintedHere: boolean;
     tracker: AutoModeDenialTracker | undefined;
     resolved: FallbackResolution;

package/dist/core/runner/denial-limit-arms.js

@@ -1,19 +1,38 @@
-import { createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence } from "../auto-mode.js";
+import { createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence, unarmedWindow } from "../auto-mode.js";
+import { sanitizeAutoModeArmingRecipe, tightenDenialLimit } from "../auto-mode-arming.js";
 import { deliverEngineNotice } from "../types.js";
 import { inlineUntrusted } from "../untrusted-text.js";
+import { askOriginOf, classifierMayAnswer } from "../ask-origin.js";
 export function attachRebuiltDenialTrackers(entries, denialLimit) {
-    const rebuiltTrackers = new Map();
+    if (entries === undefined)
+        return undefined;
+    const needsTracker = (pc) => pc.autoMode !== undefined && pc.autoMode.denialTracking === undefined;
+    const boundsFor = new Map();
+    const liveTrackers = new Map();
+    for (const pc of entries) {
+        if (pc.autoMode?.denialTracking !== undefined)
+            liveTrackers.set(pc.autoMode.decider, pc.autoMode.denialTracking);
+    }
+    for (const pc of entries) {
+        if (!needsTracker(pc) || liveTrackers.has(pc.autoMode.decider))
+            continue;
+        const recorded = sanitizeAutoModeArmingRecipe(pc.autoMode.arming);
+        if (recorded === undefined)
+            continue;
+        const merged = tightenDenialLimit(recorded.denialLimit, denialLimit);
+        const seen = boundsFor.get(pc.autoMode.decider);
+        boundsFor.set(pc.autoMode.decider, seen === undefined ? merged : tightenDenialLimit(seen, merged));
+    }
+    const rebuiltTrackers = new Map(liveTrackers);
     const trackerForRebuilt = (decider) => {
         let t = rebuiltTrackers.get(decider);
         if (t === undefined) {
-            t = createAutoModeDenialTracker(denialLimit);
+            t = createAutoModeDenialTracker(boundsFor.get(decider) ?? denialLimit);
             rebuiltTrackers.set(decider, t);
         }
         return t;
     };
-    return entries?.map((pc) => pc.autoMode !== undefined && pc.autoMode.denialTracking === undefined
-        ? { ...pc, autoMode: { ...pc.autoMode, denialTracking: trackerForRebuilt(pc.autoMode.decider) } }
-        : pc);
+    return entries.map((pc) => (needsTracker(pc) ? { ...pc, autoMode: { ...pc.autoMode, denialTracking: trackerForRebuilt(pc.autoMode.decider) } } : pc));
 }
 export function createDenialLimitStop(opts) {
     const gateStopRef = {};
@@ -34,13 +53,23 @@ export function createDenialLimitStop(opts) {
     };
     return { gateStopRef, stopForDenialLimit };
 }
-export function frozenClassifierExcluded(d) {
-    return d.decisionReason === "hook" || d.matchedAskRule !== undefined || d.denialLimitFallback !== undefined;
+const INHERITED_STATION_FACTS = { contentQuestion: false, markedUnresolvable: false, org: undefined };
+function fallbackCarry(fallback, liveApprover, tracker) {
+    if (fallback === undefined)
+        return {};
+    return { denialLimitFallback: liveApprover && tracker !== undefined ? tracker.armTimedWindow(fallback) : unarmedWindow(fallback) };
+}
+export function gateAskCarry(decision, liveApprover, tracker) {
+    return { ...(decision.origin !== undefined ? { origin: decision.origin } : {}), ...fallbackCarry(decision.denialLimitFallback, liveApprover, tracker) };
+}
+export function inheritedAskCarry(origin, fallback, liveApprover, tracker) {
+    return { origin, ...fallbackCarry(fallback, liveApprover, tracker) };
 }
 export async function judgeInheritedClassifier(opts) {
     const { autoMode, ask, req } = opts;
-    if (autoMode === undefined || frozenClassifierExcluded(ask))
-        return { kind: "resolve", ask, fallback: ask.denialLimitFallback, mintedHere: false };
+    const origin = askOriginOf(ask, INHERITED_STATION_FACTS);
+    if (autoMode === undefined || !classifierMayAnswer(origin))
+        return { kind: "resolve", ask, fallback: ask.denialLimitFallback, mintedHere: false, origin };
     const verdict = await autoMode.decider
         .decide({ req, ...(ask.message !== undefined ? { askMessage: ask.message } : {}) }, opts.signal)
         .catch(() => ({ kind: "unavailable", cause: "error" }));
@@ -49,7 +78,7 @@ export async function judgeInheritedClassifier(opts) {
         return { kind: "allow" };
     }
     if (verdict.kind !== "block")
-        return { kind: "resolve", ask, fallback: ask.denialLimitFallback, mintedHere: false };
+        return { kind: "resolve", ask, fallback: ask.denialLimitFallback, mintedHere: false, origin };
     const reason = verdict.reason ? inlineUntrusted(verdict.reason) : "";
     const category = verdict.category ? inlineUntrusted(verdict.category) : "";
     const tracked = autoMode.denialTracking?.recordBlock();
@@ -64,12 +93,8 @@ export async function judgeInheritedClassifier(opts) {
         };
     }
     const fallback = tracked.fallback;
-    return {
-        kind: "resolve",
-        ask: { ...ask, message: denialLimitFallbackMessage(fallback, reason || category || req.toolName), decisionReason: "classifier", requiresRealApproval: true, denialLimitFallback: fallback },
-        fallback,
-        mintedHere: true,
-    };
+    const minted = { ...ask, message: denialLimitFallbackMessage(fallback, reason || category || req.toolName), decisionReason: "classifier", requiresRealApproval: true, denialLimitFallback: fallback };
+    return { kind: "resolve", ask: minted, fallback, mintedHere: true, origin: askOriginOf(minted, INHERITED_STATION_FACTS) };
 }
 export function headlessDenyAtFold(r) {
     return r.resolution === "no_approver" || r.resolution === "blanket_allow_refused";

package/dist/core/runner/derived-route-fallback.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The derived-leg route pre-flight shared by prepareTask's two derived seats: the compaction-summary model (the
+ * driver's own seat, resolved before the offload prelude) and the auto-mode classifier model (the caps-and-workflow
+ * phase's arming). Moved whole out of the orchestrator so the phase reaches DOWN for it instead of the two callers
+ * spelling it twice. The judgment law itself lives in the brain's route adjudicator; this is the one guarded seat
+ * around it.
+ */
+import type { Model } from "../../internal/llm.js";
+import type { RunnerDeps, TaskSpec } from "../types.js";
+/**
+ * The derived-leg pairing pre-flight as ONE guarded seat: judge the derived model where its route
+ * differs from the primary's, announce the fallback on a broken pairing, and ABSTAIN (keep the
+ * derived model) on ANY throw. The pre-flight is advisory — the brain's request gate re-runs the
+ * same law — so neither a throwing judge face nor a garbage catalog value (the route-identity
+ * normalization throws a TypeError on a non-string baseUrl) may widen into "task preparation
+ * failed": at the compaction seat the session is already acquired and the throw-cleanup contract
+ * is not yet armed, so a throw here would leak the acquired session view, and the garbage value
+ * still earns its loud refusal at the request gate the moment the derived leg is actually used.
+ * Returns whether the seat should fall back to the primary model.
+ */
+export declare function derivedRouteFallsBack(args: {
+    seat: string;
+    derived: Model;
+    primary: Model;
+    brain: RunnerDeps["brain"];
+    getApiKeyAndHeaders: TaskSpec["getApiKeyAndHeaders"];
+    onNotice: RunnerDeps["onNotice"];
+    /** #433 — the run this seat resolution belongs to; carried onto the notice as its routing key
+     *  (the audience stays operator: correlation, not entitlement). Absent ⇒ nothing is fabricated. */
+    sessionId?: string;
+    /** #499 — the INVOCATION this seat resolution belongs to. The session cannot stand in for it: two
+     *  runs of one session that both fall back on the same seat mint otherwise byte-identical lines. */
+    runId?: string;
+}): Promise<boolean>;

package/dist/core/runner/derived-route-fallback.js

@@ -0,0 +1,16 @@
+import { adjudicateDerivedRoute, fallbackToPrimaryNotice, sameRouteIdentity } from "../../brain/route-adjudicator.js";
+import { deliverEngineNotice } from "../types.js";
+export async function derivedRouteFallsBack(args) {
+    try {
+        if (sameRouteIdentity(args.derived, args.primary))
+            return false;
+        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, ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}), ...(args.runId !== undefined ? { runId: args.runId } : {}) }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/core/runner/prepare-acquire-reconcile.d.ts

@@ -22,7 +22,7 @@ import { StoredSession } from "../session.js";
 import type { AcquiredSession, SessionStore } from "../session.js";
 import { type RecoveredOrphan } from "../session-reconcile.js";
 import type { TaskSpec, ToolEffect } from "../types.js";
-import type { PrepareResume } from "./prepare-task.js";
+import type { PrepareResume } from "./contracts.js";
 export interface PrepareAcquireReconcileInput {
     /** borrowed-mutable (service port) — the deployment's session store. This phase's verbs on it are
      *  the acquire/forget half of the session resource protocol: `acquire` per attempt, `forget` to

package/dist/core/runner/prepare-announce-once.d.ts

@@ -0,0 +1,83 @@
+import type { AnnouncedListingSnapshot, AnnouncedListingSnapshotInput, AnnouncedMcpFailure } from "../../internal/harness.js";
+import type { McpDroppedTool, McpServerStatus } from "../mcp.js";
+import type { RunnerDeps } from "../types.js";
+/** Upper bound on the advisory-digest arm kept in the record (oldest dropped past it). A digest is
+ *  64 hex chars; a session accumulates a handful of distinct advisories, never hundreds — the bound
+ *  keeps a pathological deployment (a warning whose text embeds a per-run value) from growing the
+ *  snapshot without limit while still holding every realistic set. */
+export declare const ANNOUNCE_ONCE_MAX_DIGESTS = 200;
+/** Stable digest of one announcement: `sha256(lane \n text)` as hex. Opaque on the wire; only ever
+ *  compared for equality. */
+export declare function announceDigest(lane: string, text: string): string;
+/** The digest of an operator-lane warning: its `code` (empty when uncoded) and message. The message is
+ *  passed through the secret-tier redaction FIRST: an advisory that embeds a credential (a misconfigured
+ *  header, a URL with userinfo) must be recognized as the same advisory when the credential rotates, and
+ *  the record must never persist a secret-bearing text's exact digest either — the digest is opaque, but
+ *  an equality oracle on a secret is still an oracle. The forwarded line itself is untouched (the sink
+ *  owns its own redaction posture); only the identity is judged on the redacted form. */
+export declare function warningDigest(err: unknown): string;
+/** The digest of one model-facing dropped-tool entry (server, tool, reason — the three fields the
+ *  frame prints). */
+export declare function droppedToolDigest(d: McpDroppedTool): string;
+/** `existing ∪ add`, insertion-ordered, bounded to {@link ANNOUNCE_ONCE_MAX_DIGESTS} (oldest first
+ *  out). Returns a NEW array; the input arrays are never mutated. */
+export declare function withAnnounceDigests(existing: readonly string[] | undefined, add: readonly string[]): string[];
+/** The session face this ledger needs: the nearest announced snapshot and the append. */
+export interface AnnounceOnceSession {
+    getAnnouncedListing(): Promise<AnnouncedListingSnapshot | undefined>;
+    appendAnnouncedListing(snapshot: AnnouncedListingSnapshotInput): Promise<string>;
+}
+/** The run-local ledger — see the module header for the two commit disciplines it serves. */
+export interface AnnounceOnceLedger {
+    /** The nearest announced snapshot on the branch as read at prepare (undefined = pre-entry
+     *  session). Exposed so the listing seed can reuse this ONE read instead of walking the branch again. */
+    readonly entry: AnnouncedListingSnapshot | undefined;
+    /** Whether the branch read SUCCEEDED (a pre-entry session reads as `undefined` and IS recovered; a
+     *  throwing read is not). While false, no whole-snapshot write may happen on this leg — the nearest
+     *  `announced_listing` has snapshot semantics, so a write seeded from a failed read would REPLACE
+     *  the branch's real record with the few arms this leg happens to know, hiding every other arm.
+     *  A skipped write degrades to a duplicate announcement next run, never a loss. The run loop
+     *  reads the same flag (`Prepared.announcedSnapshotRecovered`) before its own once-arm flush. */
+    readonly recovered: boolean;
+    /** The operator-lane sink, deduplicated: a warning whose `(code, message)` digest is already in
+     *  the record is dropped; a new one is forwarded to `deps.onError` and recorded. With no sink wired
+     *  nothing is recorded either — "announced" means delivered. Same signature as `RunnerDeps.onError`. */
+    onError: NonNullable<RunnerDeps["onError"]>;
+    /** The MODEL-face pending set for this run: the currently failed servers (name/error neutralized +
+     *  bounded at intake, the reminder's own bounds) MINUS the pairs already announced on this branch.
+     *  As a side effect the record's `mcpFailed` arm is pruned to the pairs that are STILL failing —
+     *  a recovered server leaves the record silently. Call once per prepare. */
+    mcpFailuresToAnnounce(statuses: ReadonlyArray<McpServerStatus>): AnnouncedMcpFailure[];
+    /** Remove, IN PLACE, the dropped-tool entries whose model-facing digest is already recorded (the
+     *  frame was delivered on an earlier run of this session). The operator line about each entry is a
+     *  separate digest — run that loop BEFORE pruning so both faces are judged on the full list. */
+    pruneDroppedTools(dropped: McpDroppedTool[]): void;
+    /** The whole announced snapshot as it stands — the seed for the run loop's `announcedListingsRef`
+     *  mirror. Listing arms (agents/skills/models) are copied from ONE source, the checkpoint mirror
+     *  when it carries any of them, else the entry (rung-pure: a roster and its catalog come from the
+     *  same commit); the once-per-session arms come from their own rung selection. Present-only: an
+     *  empty arm is omitted, so a session that never announced anything serializes no
+     *  `announcedListings` at all. The listing arms are a state-only carry: a commit of any ONE arm
+     *  rewrites the nearest snapshot whole, so the other arms must already be on the object or the
+     *  commit erases them from the branch's record. */
+    arms(): AnnouncedListingSnapshot;
+    /** End-of-prepare settlement: fold the operator-lane digests recorded during prepare into `ref`
+     *  (the mirror the run loop and the checkpoint serializer read) and, when the record advanced,
+     *  persist the whole snapshot — the listing arms as they stand on `ref` (or as read at prepare),
+     *  plus the two arms this module owns. Best-effort: an append failure degrades to a duplicate
+     *  announcement on the next run, never a lost one. */
+    settle(session: AnnounceOnceSession, ref: AnnouncedListingSnapshotInput): Promise<void>;
+}
+/**
+ * Load the ledger for this prepare. Read ladder for the two arms: the resume checkpoint's mirror
+ * first (cut atomically with the suspend; the entry is a best-effort write that can lag it), then
+ * the nearest `announced_listing` carrier on the branch. A snapshot without the arms (an entry
+ * written before they existed) reads as the empty set — additive schema, same posture as the
+ * checkpoint's own listing arms. A session read failure also reads as empty: the worst case of
+ * an unseeded ledger is a duplicate announcement, never a lost one.
+ */
+export declare function loadAnnounceOnceLedger(session: AnnounceOnceSession, checkpointMirror: AnnouncedListingSnapshot | undefined, onError: RunnerDeps["onError"]): Promise<AnnounceOnceLedger>;
+/** The suspend-time projection of the run loop's announced mirror onto the checkpoint field:
+ *  present-only arms, copied; `undefined` when nothing was announced on any face (the resume seed
+ *  then falls to the lower rungs — unchanged contract). */
+export declare function serializeAnnouncedListings(ref: AnnouncedListingSnapshotInput): AnnouncedListingSnapshot | undefined;

package/dist/core/runner/prepare-announce-once.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { redactSecrets } from "../untrusted-egress.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+export const ANNOUNCE_ONCE_MAX_DIGESTS = 200;
+const DROPPED_TOOL_MODEL_LANE = "mcp_dropped_tools";
+export function announceDigest(lane, text) {
+    return createHash("sha256").update(lane).update("\n").update(text).digest("hex");
+}
+export function warningDigest(err) {
+    const e = err;
+    const code = typeof e?.code === "string" ? e.code : "";
+    const message = err instanceof Error ? err.message : String(err);
+    return announceDigest(code, redactSecrets(message));
+}
+export function droppedToolDigest(d) {
+    return announceDigest(DROPPED_TOOL_MODEL_LANE, `${d.server}\n${d.tool}\n${d.reason}`);
+}
+export function withAnnounceDigests(existing, add) {
+    const out = [...(existing ?? [])];
+    const seen = new Set(out);
+    for (const d of add) {
+        if (seen.has(d))
+            continue;
+        seen.add(d);
+        out.push(d);
+    }
+    return out.length > ANNOUNCE_ONCE_MAX_DIGESTS ? out.slice(out.length - ANNOUNCE_ONCE_MAX_DIGESTS) : out;
+}
+function sameFailure(a, b) {
+    return a.name === b.name && a.error === b.error;
+}
+export async function loadAnnounceOnceLedger(session, checkpointMirror, onError) {
+    let recovered = true;
+    const entry = await session.getAnnouncedListing().catch(() => {
+        recovered = false;
+        return undefined;
+    });
+    const seed = checkpointMirror?.mcpFailed !== undefined || checkpointMirror?.advisories !== undefined ? checkpointMirror : entry;
+    const listingSrc = checkpointMirror?.agents !== undefined || checkpointMirror?.skills !== undefined || checkpointMirror?.models !== undefined ? checkpointMirror : entry;
+    let mcpFailed = (seed?.mcpFailed ?? []).map((f) => ({ ...f }));
+    const advisories = new Set(seed?.advisories ?? []);
+    let dirty = false;
+    return {
+        entry,
+        recovered,
+        onError: (err, ctx) => {
+            if (onError === undefined)
+                return;
+            const digest = warningDigest(err);
+            if (advisories.has(digest))
+                return;
+            onError(err, ctx);
+            advisories.add(digest);
+            dirty = true;
+        },
+        mcpFailuresToAnnounce: (statuses) => {
+            const current = statuses
+                .filter((s) => s.status === "failed")
+                .map((s) => ({ name: inlineUntrusted(s.name, 160), ...(s.error !== undefined ? { error: inlineUntrusted(s.error, 240) } : {}) }));
+            const carried = mcpFailed.filter((r) => current.some((c) => sameFailure(c, r)));
+            if (carried.length !== mcpFailed.length)
+                dirty = true;
+            mcpFailed = carried;
+            return current.filter((c) => !carried.some((r) => sameFailure(c, r)));
+        },
+        pruneDroppedTools: (dropped) => {
+            for (let i = dropped.length - 1; i >= 0; i--) {
+                if (advisories.has(droppedToolDigest(dropped[i])))
+                    dropped.splice(i, 1);
+            }
+        },
+        arms: () => ({
+            ...(listingSrc?.agents !== undefined ? { agents: [...listingSrc.agents] } : {}),
+            ...(listingSrc?.skills !== undefined ? { skills: [...listingSrc.skills] } : {}),
+            ...(listingSrc?.models !== undefined ? { models: [...listingSrc.models] } : {}),
+            ...(mcpFailed.length > 0 ? { mcpFailed: mcpFailed.map((f) => ({ ...f })) } : {}),
+            ...(advisories.size > 0 ? { advisories: withAnnounceDigests(undefined, [...advisories]) } : {}),
+        }),
+        settle: async (s, ref) => {
+            if (advisories.size > 0)
+                ref.advisories = withAnnounceDigests(undefined, [...advisories]);
+            if (!dirty || !recovered)
+                return;
+            await s
+                .appendAnnouncedListing({
+                ...(ref.agents !== undefined ? { agents: ref.agents } : {}),
+                ...(ref.skills !== undefined ? { skills: ref.skills } : {}),
+                ...(ref.models !== undefined ? { models: ref.models } : {}),
+                ...(ref.mcpFailed !== undefined && ref.mcpFailed.length > 0 ? { mcpFailed: ref.mcpFailed } : {}),
+                ...(ref.advisories !== undefined && ref.advisories.length > 0 ? { advisories: ref.advisories } : {}),
+            })
+                .catch(() => undefined);
+        },
+    };
+}
+export function serializeAnnouncedListings(ref) {
+    const out = {
+        ...(ref.agents !== undefined ? { agents: [...ref.agents] } : {}),
+        ...(ref.skills !== undefined ? { skills: [...ref.skills] } : {}),
+        ...(ref.models !== undefined ? { models: [...ref.models] } : {}),
+        ...(ref.mcpFailed !== undefined ? { mcpFailed: ref.mcpFailed.map((f) => ({ ...f })) } : {}),
+        ...(ref.advisories !== undefined ? { advisories: [...ref.advisories] } : {}),
+    };
+    return Object.keys(out).length > 0 ? out : undefined;
+}