@sema-agent/core 7.3.1 → 7.4.0

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

@@ -35,11 +35,43 @@ export interface MailboxPeerMeta {
     fromScope?: string;
     /** Cross-principal delivery only — the delivery gate's receipt id (audit back-reference). */
     gateReceiptId?: string;
+    /** Notice-kind records only (design/385 §4.4 / §5.2): the typed notice the requester's drain renders
+     *  — a delivery receipt's state (`kind: "delivery_notice"`) or an idle notice's kind
+     *  (`kind: "idle_notice"`). The record's `content` is a human-readable mirror; THIS is the authority. */
+    notice?: MailboxPeerNoticeMeta;
+}
+/** design/385 — the typed body of a notice-kind record. `state` is drawn from the receipt states on a
+ *  `delivery_notice` (`held|denied|expired|delivered|refused|dropped`) and from the idle kinds on an
+ *  `idle_notice` (`idle|exited|unavailable|expired`); the validator admits the union, the drain checks
+ *  the pairing (a state that does not fit its kind is settled `notice_unrouted`, never rendered). */
+export interface MailboxPeerNoticeMeta {
+    state: string;
+    /** delivery_notice: the box seq of the SENDER'S message this receipt is about. */
+    refSeq?: number;
+    /** delivery_notice: the recipient's display label (as its directory row spells it). */
+    recipient?: string;
+    /** delivery_notice `dropped`: the ingress guard's reason. */
+    dropReason?: string;
+    /** idle_notice `idle`/`exited`: when the target finished its turn (epoch ms). */
+    finishedAt?: number;
+    /** idle_notice `idle`: the target's one-line detail (already bounded by the producer). */
+    detail?: string;
+    /** idle_notice `expired` (the requester answering ITSELF): the label the ask carried for the target
+     *  that never answered — the record's author is the requester, so the target must be named here. */
+    target?: string;
 }
 export declare const MAILBOX_PEER_FROM_MODES: readonly ["bypass", "prompting"];
 export type MailboxPeerFromMode = (typeof MAILBOX_PEER_FROM_MODES)[number];
-export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_notice", "delivery_notice"];
+/** design/385: `peer_message` runs the parity judgment; `idle_subscription` registers the sender as an
+ *  idle subscriber of the box owner (§5.2, the store form of CC's `notify_when_idle` frame);
+ *  `idle_notice` / `delivery_notice` land on the notice face (rendered, never enveloped as a peer's words). */
+export declare const MAILBOX_PEER_RECORD_KINDS: readonly ["peer_message", "idle_notice", "delivery_notice", "idle_subscription"];
 export type MailboxPeerRecordKind = (typeof MAILBOX_PEER_RECORD_KINDS)[number];
+/** The `notice.state` vocabulary the validator admits (the union of both notice families; the drain
+ *  checks the kind↔state pairing). Spelled here, beside the record kinds, so the store contract is
+ *  self-contained — the lane's own closed sets re-derive from these. */
+export declare const MAILBOX_PEER_NOTICE_STATES: readonly ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"];
+export type MailboxPeerNoticeState = (typeof MAILBOX_PEER_NOTICE_STATES)[number];
 /** The `append` refusal code for a malformed `peerMeta` (design/385): a garbage record is refused up
  *  front with this code, never silently stripped or stored — a drain that reads a half-typed record
  *  would judge on fabricated inputs. */

package/dist/core/mailbox-store.js

@@ -1,6 +1,7 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
 export const MAILBOX_PEER_FROM_MODES = ["bypass", "prompting"];
-export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delivery_notice"];
+export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delivery_notice", "idle_subscription"];
+export const MAILBOX_PEER_NOTICE_STATES = ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"];
 export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
 export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
 const PEER_META_STRING_KEYS = ["fromSession", "senderKey", "fromScope", "gateReceiptId"];
@@ -38,14 +39,53 @@ export function readMailboxPeerMeta(raw) {
                 return refuse(`${k} must be a non-empty string`);
             out[k] = v;
         }
+        else if (k === "notice") {
+            out.notice = readMailboxPeerNoticeMeta(v, refuse);
+        }
         else {
             return refuse(`carries an unknown key ${JSON.stringify(k)}`);
         }
     }
     return out;
 }
+function readMailboxPeerNoticeMeta(raw, refuse) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return refuse("notice must be a plain object");
+    const proto = Object.getPrototypeOf(raw);
+    if (proto !== Object.prototype && proto !== null)
+        return refuse("notice must be a plain object (a class instance, Date, Map or similar is not)");
+    const out = {};
+    for (const key of Reflect.ownKeys(raw)) {
+        if (typeof key !== "string")
+            return refuse("notice carries a symbol-keyed member");
+        const v = raw[key];
+        if (v === undefined)
+            continue;
+        if (key === "state") {
+            if (!MAILBOX_PEER_NOTICE_STATES.includes(v))
+                return refuse(`notice.state must be one of ${MAILBOX_PEER_NOTICE_STATES.join("|")}`);
+            out.state = v;
+        }
+        else if (key === "recipient" || key === "dropReason" || key === "detail" || key === "target") {
+            if (typeof v !== "string" || v === "")
+                return refuse(`notice.${key} must be a non-empty string`);
+            out[key] = v;
+        }
+        else if (key === "refSeq" || key === "finishedAt") {
+            if (typeof v !== "number" || !Number.isFinite(v) || v < 0)
+                return refuse(`notice.${key} must be a non-negative finite number`);
+            out[key] = v;
+        }
+        else {
+            return refuse(`notice carries an unknown key ${JSON.stringify(key)}`);
+        }
+    }
+    if (out.state === undefined)
+        return refuse("notice.state is required");
+    return out;
+}
 export function cloneMailboxPeerMeta(meta) {
-    return meta === undefined ? undefined : { ...meta };
+    return meta === undefined ? undefined : { ...meta, ...(meta.notice !== undefined ? { notice: { ...meta.notice } } : {}) };
 }
 export const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tombstoned";
 export class MailboxStoreError extends Error {

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

@@ -117,6 +117,11 @@ export interface ResultFlags {
      *  Pure pass-through — assembly neither adds nor filters (a rewind that FAILED never reaches here; it
      *  throws at prepare and lands in the `threw` slot as a terminal errorCode). */
     rewindNotes?: TaskResult["rewindNotes"];
+    /** The run's OWN edited-file ledger, echoed on `TaskResult.editedFiles`. Pure pass-through on
+     *  EVERY terminal — what this run's hands changed is a fact about the leg that ran, whatever
+     *  terminal it reached (a failed/aborted run that edited files is exactly the case a "restore the
+     *  code this message changed" affordance is for). Undefined ⇒ the key is omitted. */
+    editedFiles?: TaskResult["editedFiles"];
     /** The run's final turn was halted by a person's BARE rejection of a tool call (the parent-thread
      *  control-flow boundary) — echoed on `TaskResult.haltedOnUserRejection`. Pure pass-through on
      *  every terminal: the fact is about the leg that ran, whatever terminal it reached (on the normal

package/dist/core/runner/assemble-result.js

@@ -181,5 +181,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
     const stampHaltedByUser = flags.userHalted === true && status !== "suspended" && status !== "needs_review";
-    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, ...(checkpointId !== undefined ? { checkpointId } : {}), checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
+    return { taskId, ...(flags.runId !== undefined ? { runId: flags.runId } : {}), sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(apiFailure !== undefined ? { apiFailure } : {}), ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, ...(checkpointId !== undefined ? { checkpointId } : {}), checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.editedFiles !== undefined && flags.editedFiles.length > 0 ? { editedFiles: flags.editedFiles } : {}), ...(flags.haltedOnUserRejection === true ? { haltedOnUserRejection: true } : {}), ...(stampHaltedByUser ? { haltedByUser: true } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: [...flags.remoteEnvFailures] } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), ...(flags.effectiveReasoning !== undefined ? { effectiveReasoning: flags.effectiveReasoning } : {}), stats: publicStats };
 }

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

@@ -0,0 +1,149 @@
+import { type AutoModeDecider, type AutoModeDenialLimitOptions, type AutoModeDenialTracker, type DenialLimitFallback } from "../auto-mode.js";
+import type { PermissionResult, ResolvedAsk, ToolCallRequest } from "../tool-policy.js";
+import { type EngineNotice } from "../types.js";
+import type { Prepared } from "./prepare-task.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
+ * classifier block site lives in tool-policy; these are the pieces the runner threads around it:
+ *  · the tracker attached to a re-supplied chain entry ({@link attachRebuiltDenialTrackers});
+ *  · the run's ONE typed stop seat + the closure that fills it ({@link createDenialLimitStop});
+ *  · 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}).
+ * 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). */
+export interface InheritedAutoMode {
+    decider: AutoModeDecider;
+    denialTracking?: AutoModeDenialTracker;
+}
+/**
+ * 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).
+ */
+export declare function attachRebuiltDenialTrackers<T extends {
+    autoMode?: InheritedAutoMode;
+}>(entries: ReadonlyArray<T> | undefined, denialLimit: AutoModeDenialLimitOptions | undefined): T[] | undefined;
+/** The one closure that stops a run for a headless denial-limit fallback (see {@link createDenialLimitStop}). */
+export type StopForDenialLimit = (info: {
+    toolName: string;
+    toolCallId: string;
+    fallback: DenialLimitFallback;
+}) => void;
+/**
+ * The gate's typed stop seat (`Prepared.gateStopRef`) and the one closure that fills it — the headless
+ * arm of the denial-limit fallback: no approver to fall back to ⇒ stop the run with
+ * `classifier.denial_limit` (CC throws "Agent aborted: too many classifier denials in headless
+ * mode"). Once per run (the first headless fallback owns the terminal); the deny that triggered it
+ * stands as that call's result. Minted once so every mint site — the main gate's seat and the
+ * inherited-lane arms — stops the SAME run through the SAME seat. `abort` is the run's own abort
+ * (controller + harness), handed in because the harness is built after the seat is.
+ */
+export declare function createDenialLimitStop(opts: {
+    sessionId: string;
+    runId: string;
+    onNotice: ((notice: EngineNotice) => void) | undefined;
+    abort: () => void;
+}): {
+    gateStopRef: Prepared["gateStopRef"];
+    stopForDenialLimit: StopForDenialLimit;
+};
+/** The ask arm of a permission decision — what the inherited lane arbitrates. */
+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;
+/** 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). */
+{
+    kind: "allow";
+}
+/** A block below the bound — the exact deny the ancestor's own gate would have produced. */
+ | {
+    kind: "deny";
+    result: PermissionResult;
+}
+/** 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). */
+ | {
+    kind: "resolve";
+    ask: A;
+    fallback: DenialLimitFallback | undefined;
+    mintedHere: boolean;
+};
+/**
+ * The ancestor's frozen classifier, run BEFORE its frozen approver in the ancestor's own gate order,
+ * with the denial-limit count folded in (CC 2.1.250 count-then-judge): `allow` ⇒ the classifier's
+ * auto-allow (and the streak resets); `block` below the bound ⇒ deny, the exact verdict the ancestor's
+ * gate would have produced; `block` AT the bound ⇒ the ask is re-spoken in the classifier's voice as
+ * the fallback (`decisionReason:"classifier"`, `requiresRealApproval`, the member carrying counts +
+ * window) for the arm to resolve at the frozen approver; anything else (unavailable / parse error /
+ * excluded / no classifier) ⇒ the incoming ask, unchanged. The member may ALREADY be on the incoming
+ * ask (a deeper ancestor's fallback, minted inside the nested fold — the case the exclusion names):
+ * it rides to the approver and the headless arm unchanged, whichever tracker minted it; only a
+ * tracker that counted THIS streak is reset by the person's later allow (`mintedHere`).
+ * `req` is the request as the classifier must see it (the arm's presented / edited args);
+ * `subject` is the noun the deny names ("this call" on the wrapper arms, "the approved edit" on the
+ * re-check).
+ */
+export declare function judgeInheritedClassifier<A extends InheritedAsk>(opts: {
+    autoMode: InheritedAutoMode | undefined;
+    ask: A;
+    req: ToolCallRequest;
+    signal: AbortSignal;
+    subject: "this call" | "the approved edit";
+}): Promise<InheritedClassifierJudgment<A>>;
+/** The resolver's answer as the settlement reads it. */
+export type FallbackResolution = Pick<ResolvedAsk, "action" | "resolution" | "approverUnavailable">;
+/** A deny nobody made, at a wrapper arm: no approver wired, or a blanket `onAsk:"allow"` refused as
+ *  no approver. `approver_unavailable` is NOT headless here — it floats to the main gate, which owns
+ *  that arm (a park, or the fail-closed refusal). */
+export declare function headlessDenyAtFold(r: FallbackResolution): boolean;
+/** The re-check's reading: the approved-edit helper has NO park route (an approved edit is
+ *  re-adjudicated in place), so an approver that reports unavailable is as headless as none at all. */
+export declare function headlessDenyAtRecheck(r: FallbackResolution): boolean;
+/**
+ * After the frozen approver answered a fallback ask (CC `yR`): a person's allow ends the ancestor's
+ * streak — only on the tracker that counted it (`mintedHere`; a deeper ancestor's fallback leaves
+ * this entry's count alone); a deny nobody made (`headless`, the arm's own reading) is the headless
+ * arm — the run stops through the one seat (`stop`). Any other answer settles nothing here. A no-op
+ * when the ask was not a fallback.
+ */
+export declare function settleDenialLimitFallback(opts: {
+    fallback: DenialLimitFallback | undefined;
+    mintedHere: boolean;
+    tracker: AutoModeDenialTracker | undefined;
+    resolved: FallbackResolution;
+    headless: (r: FallbackResolution) => boolean;
+    stop: StopForDenialLimit;
+    toolName: string;
+    toolCallId: string;
+}): void;

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

@@ -0,0 +1,91 @@
+import { createAutoModeDenialTracker, denialLimitFallbackMessage, denialLimitSentence } from "../auto-mode.js";
+import { deliverEngineNotice } from "../types.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+export function attachRebuiltDenialTrackers(entries, denialLimit) {
+    const rebuiltTrackers = new Map();
+    const trackerForRebuilt = (decider) => {
+        let t = rebuiltTrackers.get(decider);
+        if (t === undefined) {
+            t = createAutoModeDenialTracker(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);
+}
+export function createDenialLimitStop(opts) {
+    const gateStopRef = {};
+    const stopForDenialLimit = (info) => {
+        if (gateStopRef.terminal !== undefined)
+            return;
+        const message = `too many classifier denials in headless mode — ${denialLimitSentence(info.fallback)} The run was stopped: ` +
+            `the auto-mode classifier's denial limit falls back to a person, and no approver is wired to fall back to ` +
+            `(latest blocked action: "${info.toolName}").`;
+        const terminal = Object.assign(new Error(message), { code: "classifier.denial_limit" });
+        gateStopRef.terminal = terminal;
+        deliverEngineNotice(opts.onNotice, {
+            code: "classifier.denial_limit",
+            message,
+            detail: { sessionId: opts.sessionId, runId: opts.runId, toolName: info.toolName, toolCallId: info.toolCallId, consecutive: info.fallback.consecutive, total: info.fallback.total, limit: info.fallback.limit },
+        });
+        opts.abort();
+    };
+    return { gateStopRef, stopForDenialLimit };
+}
+export function frozenClassifierExcluded(d) {
+    return d.decisionReason === "hook" || d.matchedAskRule !== undefined || d.denialLimitFallback !== undefined;
+}
+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 verdict = await autoMode.decider
+        .decide({ req, ...(ask.message !== undefined ? { askMessage: ask.message } : {}) }, opts.signal)
+        .catch(() => ({ kind: "unavailable", cause: "error" }));
+    if (verdict.kind === "allow") {
+        autoMode.denialTracking?.recordAllow();
+        return { kind: "allow" };
+    }
+    if (verdict.kind !== "block")
+        return { kind: "resolve", ask, fallback: ask.denialLimitFallback, mintedHere: false };
+    const reason = verdict.reason ? inlineUntrusted(verdict.reason) : "";
+    const category = verdict.category ? inlineUntrusted(verdict.category) : "";
+    const tracked = autoMode.denialTracking?.recordBlock();
+    if (tracked?.limitReached !== true) {
+        return {
+            kind: "deny",
+            result: {
+                action: "deny",
+                message: `auto-mode classifier blocked ${opts.subject} at an inherited ancestor layer${reason ? `: ${reason}` : category ? `: [${category}]` : ""}`,
+                decisionReason: "classifier",
+            },
+        };
+    }
+    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,
+    };
+}
+export function headlessDenyAtFold(r) {
+    return r.resolution === "no_approver" || r.resolution === "blanket_allow_refused";
+}
+export function headlessDenyAtRecheck(r) {
+    return headlessDenyAtFold(r) || r.resolution === "approver_unavailable" || r.approverUnavailable === true;
+}
+export function settleDenialLimitFallback(opts) {
+    const { fallback, resolved } = opts;
+    if (fallback === undefined)
+        return;
+    if (resolved.action === "allow") {
+        if (opts.mintedHere)
+            opts.tracker?.recordAllow();
+    }
+    else if (resolved.action === "deny" && opts.headless(resolved)) {
+        opts.stop({ toolName: opts.toolName, toolCallId: opts.toolCallId, fallback });
+    }
+}

package/dist/core/runner/edited-files-ledger.d.ts

@@ -0,0 +1,33 @@
+import type { FileEditedHook, TaskResult } from "../types.js";
+/** The ceiling on DISTINCT FILES in a run's edited-file ledger (`TaskResult.editedFiles`). A result
+ *  seat must be bounded by something other than how long the model keeps going; a single host-side
+ *  user message that touches a thousand distinct files is already past what that observation is for.
+ *  Far above the delegated-child projection's own cap, which bounds a NOTIFICATION preview rather
+ *  than a per-message ledger — different job, different ceiling. The field's contract states this
+ *  number and the saturation behaviour, so a consumer can tell a full list from a clipped one. */
+export declare const RUN_EDITED_FILES_CAP = 1000;
+/** A run's OWN edited-file ledger — the observation behind `TaskResult.editedFiles`. */
+export interface EditedFilesLedger {
+    /** The hands band's post-write seat feeds this (the other end of the same mutation lane the
+     *  first-touch hook sits at). */
+    note: FileEditedHook;
+    /** The read face: the ledger as `TaskResult.editedFiles`, or `undefined` when this run's hands
+     *  landed nothing (the key is ABSENT then, never an empty array). A LIVE reader, read at result
+     *  assembly — so the throw-path backstop terminal sees the same ledger the ordinary assembly does. */
+    snapshot: () => TaskResult["editedFiles"];
+}
+/**
+ * Build the ledger. Built UNCONDITIONALLY by prepare — unlike the first-touch history hook, which
+ * exists only when a history store is wired, this answers "what did this run change", a fact about
+ * the run and not about the store. Insertion order = order of first edit; the cap keeps a result seat
+ * bounded by something other than the model's persistence (past it, listed paths keep counting and
+ * new ones are dropped — see the field's own contract).
+ *
+ * Identity is the CANONICAL key, display is the model's own spelling. The two differ, and both halves
+ * matter: the band resolves a relative argument against the LIVE cwd, so one spelling can name two
+ * different files across a `cd` (keying on the spelling would merge them and drop a real file from
+ * the ledger), and two spellings can name one file (keying on the spelling would split one file into
+ * two rows). The first spelling that reached a given file is what the row shows — the coordinate the
+ * transcript used, which is the seat's stated path form.
+ */
+export declare function createEditedFilesLedger(cap?: number): EditedFilesLedger;

package/dist/core/runner/edited-files-ledger.js

@@ -0,0 +1,14 @@
+export const RUN_EDITED_FILES_CAP = 1000;
+export function createEditedFilesLedger(cap = RUN_EDITED_FILES_CAP) {
+    const counts = new Map();
+    return {
+        note: (n) => {
+            const seen = counts.get(n.key);
+            if (seen !== undefined)
+                seen.edits += 1;
+            else if (counts.size < cap)
+                counts.set(n.key, { path: n.path, edits: 1 });
+        },
+        snapshot: () => (counts.size > 0 ? [...counts.values()].map(({ path, edits }) => ({ path, edits })) : undefined),
+    };
+}

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -204,6 +204,11 @@ export interface PrepareHandsReadFaceInput {
     /** design/381 — the first-touch history hook prepare built (present iff a fileHistoryStore is
      *  wired and the run mounts a real fs env); threaded to the write band's trackFileEdit seat. */
     trackFileEdit?: import("../types.js").TrackFileEditHook;
+    /** borrowed — the mutation lane's LANDED observation seat (the accumulator behind
+     *  `TaskResult.editedFiles`); threaded to the write band's onFileEdited seat. Unlike
+     *  `trackFileEdit` it does NOT depend on a wired history store: it observes what this run's hands
+     *  did, so it is present on every run that mounts the band. */
+    onFileEdited?: import("../types.js").FileEditedHook;
 }
 /** The phase's outputs (相 API 规则件 four-class form) — ALL settled before the return; the driver
  *  binds them as fresh consts (R-5) except the inverted-closure trio and the two shellGated bits,

package/dist/core/runner/prepare-hands-readface.js

@@ -313,6 +313,7 @@ export async function prepareHandsMount(input) {
             reminderMark: input.reminderMark,
             reminderDisclosureCounts: input.reminderDisclosureCounts,
             ...(input.trackFileEdit !== undefined ? { trackFileEdit: input.trackFileEdit } : {}),
+            ...(input.onFileEdited !== undefined ? { onFileEdited: input.onFileEdited } : {}),
             includeShell: handsIncludeShell,
             readOnly: handsReadOnly,
             ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),

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

@@ -1,7 +1,7 @@
 import { AgentHarness, type ThinkingLevel } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
 import { type CompactionForkContext } from "../auto-compaction.js";
-import { type AutoModeDecider } from "../auto-mode.js";
+import { type AutoModeDecider, type AutoModeDenialTracker } from "../auto-mode.js";
 import { type AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import { type MaterializedMcp } from "../mcp.js";
 import { type MaterializedA2a } from "../a2a.js";
@@ -214,6 +214,24 @@ export interface FileHistoryBoundarySeat {
     begin(entryId: string): void;
     settle(): Promise<void>;
 }
+/** The ONE reading of {@link RunInternals.fileHistoryLineage} (see {@link resolveFileHistoryCoordinates}):
+ *  the lineage's scope iff BOTH tree coordinates match; otherwise the run's own session. */
+export declare function resolveFileHistoryScope(lineage: RunInternals["fileHistoryLineage"], historyRoot: string, historyFs: string, sessionId: string): string;
+/**
+ * WHICH filesystem an env is a view of — the second coordinate of tree identity for the file-history
+ * lineage, read from what the env's MINTER states rather than inferred from a path:
+ *  · a remote workspace names itself through its {@link WorkspaceHandle} (provider + sandbox, and the
+ *    device lane's id when stamped) — two runs on one sandbox share a tree, two sandboxes never do;
+ *  · an env that DECLARES its paths host-local (`hostLocalPaths: true`), or is the host adapter itself
+ *    (a {@link NodeExecutionEnv}, which the #211 seam names as the host-local default), is the
+ *    control-plane host's filesystem — every such env is one tree;
+ *  · anything else — an env declaring `hostLocalPaths: false`, or an undeclared custom adapter — is
+ *    attested to nothing, so it is its OWN tree: a per-instance token, which still matches when the
+ *    child literally holds the parent's env object and never matches a fresh per-task mint.
+ * A remote handle that cannot be read (an env not yet connected) falls to the per-instance arm for
+ * the same reason: unattested is not shared.
+ */
+export declare function fileHistoryFilesystemIdentity(env: ExecutionEnv): string;
 export interface Prepared {
     harness: AgentHarness;
     /** The CONCRETE built-in session (engine-internal: prepare constructs/acquires `StoredSession` itself,
@@ -320,6 +338,11 @@ export interface Prepared {
     /** RB-430-a: prepare-time rewind disclosures (conversation-only branch / no snapshot backend / no file
      *  env), echoed verbatim onto `TaskResult.rewindNotes`. Present only when there is something to say. */
     rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
+    /** The run's edited-file ledger read face — what its OWN hands landed, as `TaskResult.editedFiles`
+     *  (undefined when nothing landed: the key is absent, never an empty array). A LIVE reader rather
+     *  than a snapshot, so the throw-path backstop terminal reports the same ledger the ordinary
+     *  assembly would. Always present on Prepared; independent of whether a fileHistoryStore is wired. */
+    editedFilesSnapshot: () => TaskResult["editedFiles"];
     /** design/381 — the run's turn-start boundary seat (present iff a fileHistoryStore is wired and
      *  the run mounts a real fs env). runtask calls begin() at the first committed user entry and
      *  awaits settle() at the lease close + the finish tail. */
@@ -725,6 +748,19 @@ export interface Prepared {
      *  the task the typed terminal — the harness turns a loop throw into an error assistant message, so
      *  without this the cause would reach the caller only as the generic `provider.error`. */
     brainCallGuardrailRef: BrainCallGuardrailRef;
+    /**
+     * #548 — the tool gate's own TYPED STOP: set (once) when the classifier denial limit was reached with
+     * no approver to fall back to (headless), together with the run abort. The run loop adopts it as the
+     * terminal `threw` (`TaskResult.errorCode` = the error's `code`, `errorMessage` = its sentence) the
+     * same way it adopts the brain-call guardrail's — a loop that ended because THIS lane aborted it must
+     * report the cause, not the consequence. The abort-result details seam reads it too, so the aborted
+     * call's own `tool_end` carries the code. `undefined` ⇒ no gate stop happened.
+     */
+    gateStopRef: {
+        terminal?: Error & {
+            code: string;
+        };
+    };
     /** design/80 D-B — set by a tool calling `ctx.requestReview()` (the first-party `present_plan` tool, CC
      *  ExitPlanMode parity): the run loop honors it at the next CLEAN turn boundary by minting a `plan_review`
      *  checkpoint. `{ pending }` is set (with an optional reason) the moment a tool requests review; the boundary
@@ -1269,6 +1305,13 @@ export interface InheritedGate {
          */
         autoMode?: {
             decider: AutoModeDecider;
+            /**
+             * #548 — the ancestor's per-run DENIAL-LIMIT tracker, frozen beside its decider (same owner). The
+             * wrapper arms count the frozen classifier's blocks on it and, at a bound, resolve the fallback
+             * ask at the frozen approver instead of denying (`requiresRealApproval` set, sandbox admission
+             * excluded). Live-only, like the decider: a cross-process redemption starts a fresh count.
+             */
+            denialTracking?: AutoModeDenialTracker;
             /**
              * #503 — the SERIALIZABLE criteria half of this classifier (assembly inputs + knobs + the
              * deployment's settings epoch), present when the arming deployment opted in
@@ -1801,6 +1844,24 @@ export interface RunInternals {
      * parent's cwd instead of an empty per-task sandbox. `isolation: "worktree"` wins over this when both set.
      */
     parentCwd?: string;
+    /**
+     * The spawning run's file-history LINEAGE — the scope it records first-touch edits into and the
+     * TREE those records' keys are minted against (the canonical root spelling + the filesystem
+     * identity of {@link fileHistoryFilesystemIdentity}) — threaded VERBATIM by core delegation
+     * callers from {@link import("../types.js").ToolExecuteContext.fileHistoryLineage} (NEVER a
+     * {@link TaskSpec} field). {@link resolveFileHistoryScope} is the ONE reading: this run records
+     * into the lineage's scope iff its own tree coordinates BOTH equal the lineage's, and then
+     * re-exposes the SAME triple on its own ctx, so every same-tree descendant of a root session — at
+     * any depth — lands in the root session's scope (the fixed point), while a descendant on another
+     * tree (worktree isolation, explicit `cwd`, a fresh per-task sandbox) becomes the root of its own
+     * subtree's history. Absent on a top-level run, on a run with no live history store, and on a
+     * tier-3 revival (the reviver's lineage says nothing about the revived row's tree).
+     */
+    fileHistoryLineage?: {
+        scope: string;
+        root: string;
+        fs: string;
+    };
     /**
      * [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),