@sema-agent/core 7.3.0 → 7.4.0

package/dist/agents/send-message-tool.js

@@ -6,6 +6,8 @@ import { uuidv7 } from "../internal/harness.js";
 import { MAILBOX_TOMBSTONED_RECIPIENT_CODE, mailboxCrossProcessMountVerdict } from "../core/mailbox-store.js";
 import { peerSendVerdictSeverity } from "./cross-session-judge.js";
 import { parsePeerSessionAddress, peerSessionBoxHandle, resolvePeerSessions } from "./peer-directory.js";
+import { peerIdleMachineFor } from "./peer-idle.js";
+import { PEER_IDLE_OUTSTANDING_CAP, PEER_IDLE_SUBSCRIPTION_TTL_MS, peerIdleNoticeLabel } from "./peer-notices.js";
 import { escapeAttributeValue, escapeEnvelopeTag, isObserverTaskId, OBSERVER_SENDMESSAGE_SENDER_REFUSAL, OBSERVER_SENDMESSAGE_TARGET_REFUSAL, } from "./observer.js";
 import { inlineUntrusted } from "../core/untrusted-text.js";
 import { neutralizePeerBody } from "./cross-session-envelope.js";
@@ -50,6 +52,11 @@ function targetLaneKey(scope, targetId) {
 const OPERATOR_CONTINUATION_CTX = Symbol("sema.operator_continuation");
 export function createSendMessageTool(opts) {
     const tier3Capable = opts.agentStore !== undefined && opts.mailbox !== undefined && opts.reviveSpawn !== undefined;
+    const notifyWhenIdleParameter = {
+        notify_when_idle: Type.Optional(Type.Boolean({
+            description: "Ask a peer SESSION of this engine to send you ONE notice when it next goes idle (finishes its turn with nothing queued) or exits — opt-in, one-shot, no polling. With a message: deliver it now AND subscribe. Without a message (omit it): a pure subscription that costs the other session nothing. Peer sessions only (not agents or teammates), and only from the main conversation.",
+        })),
+    };
     const peerLane = (() => {
         if (opts.peerDirectory === undefined)
             return { active: false };
@@ -58,6 +65,14 @@ export function createSendMessageTool(opts) {
         const verdict = mailboxCrossProcessMountVerdict(opts.mailbox);
         return verdict.ok ? { active: true } : { active: false, reason: verdict.reason };
     })();
+    const baseParameters = Type.Object({
+        to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
+        message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
+        summary: Type.Optional(Type.String({ maxLength: 200, description: "A 5-10 word summary shown as a preview in the UI (required when message is a string)" })),
+    });
+    const sendMessageParameters = peerLane.active
+        ? Type.Object({ ...baseParameters.properties, message: Type.Optional(Type.String({ description: `${baseParameters.properties.message.description ?? ""} Optional only for a pure notify_when_idle subscription.`.trim() })), ...notifyWhenIdleParameter })
+        : baseParameters;
     const retrievalMounted = opts.retrievalToolMounted;
     const retrievalHedge = retrievalMounted === undefined ? " (where that tool is mounted)" : "";
     const RETRIEVE_NOW = retrievalMounted === false
@@ -144,19 +159,16 @@ export function createSendMessageTool(opts) {
             (peerLane.active
                 ? ` Peer SESSIONS — other sessions of this engine for the same user${opts.peerListingMounted === false ? "" : opts.peerListingMounted === true ? " (list them with ListAgents)" : " (list them with ListAgents where that tool is mounted)"} — are addressed by name, by \`name [ref]\` when a name is ambiguous, or by their \`session.<id>\` address. A message to a peer is parked durably in its session box and read at its next turn boundary (an offline peer reads it when it next runs); the receipt confirms the box accepted it, not that the peer acted on it.`
                 : ""),
-        parameters: Type.Object({
-            to: Type.String({ description: 'Recipient: the agent\'s name, or its task_id (a…) returned by the Agent tool with run_in_background. "main" is reserved for the spawning conversation.' }),
-            message: Type.String({ description: "The follow-up request. The agent continues from its full prior context." }),
-            summary: Type.Optional(Type.String({ maxLength: 200, description: "A 5-10 word summary shown as a preview in the UI (required when message is a string)" })),
-        }),
+        parameters: sendMessageParameters,
         execute: async (args, ctx) => {
             const a = args;
             const operatorUserInitiated = ctx[OPERATOR_CONTINUATION_CTX] === true;
             const to = String(a.to ?? "").trim();
             const message = String(a.message ?? "").trim();
+            const notifyWhenIdle = a.notify_when_idle === true;
             if (!to)
                 return { content: "Message not sent: 'to' was empty. Pass the agent's task_id (a…).", details: { error: "empty to" }, isError: true };
-            if (!message)
+            if (!message && !notifyWhenIdle)
                 return { content: "Message not sent: 'message' was empty.", details: { error: "empty message" }, isError: true };
             if (to === "*") {
                 return {
@@ -173,7 +185,7 @@ export function createSendMessageTool(opts) {
                 };
             }
             const summaryArg = typeof a.summary === "string" ? a.summary.trim() : "";
-            if (summaryArg === "") {
+            if (summaryArg === "" && message !== "") {
                 return {
                     content: "Message not sent: summary is required when message is a string — pass a 5-10 word summary of the follow-up.",
                     details: { error: "summary_required", to },
@@ -192,7 +204,7 @@ export function createSendMessageTool(opts) {
             if (isObserverTaskId(to)) {
                 return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to }, isError: true };
             }
-            const admissionConfig = resolvePeerAdmissionConfig(opts.admission);
+            const admissionConfig = resolvePeerAdmissionConfig(opts.admission, opts.onNotice);
             const guardScope = ctx.principal ?? opts.scope ?? opts.peerSelfSession?.scope;
             const selfRef = ctx.peerSelfRef ?? opts.peerSelf;
             const directMountSessionId = ctx.sessionId ?? opts.sessionId ?? opts.peerSelfSession?.sessionId;
@@ -244,11 +256,8 @@ export function createSendMessageTool(opts) {
                 if (record.inboundPosture === "unavailable") {
                     return peerRefusal("peer_send.recipient_refuses", `${peerLabel} advertises that it does not accept cross-session messages (its crossSessionInbound is "refuse"). Nothing was parked.`);
                 }
-                const recipientKey = peerAxisToken(peerScope, "s", record.sessionId);
-                const storedContent = `[${summary}] ${clipCarrierMessage(message)}`;
-                const sendVerdict = judgePeerAdmission(peerScope, recipientKey, { senderKey, body: storedContent, prospectiveChain, ownTokens: [recipientKey] }, admissionConfig, undefined, "send");
-                if (!sendVerdict.ok)
-                    return admissionRefusal(sendVerdict.reason, peerLabel);
+                const modeClass = opts.peerSelfSession?.modeClass?.();
+                const now = Date.now();
                 let boxFull = false;
                 try {
                     boxFull = (await opts.mailbox.peekCount(peerScope, handle)) >= admissionConfig.maxQueuedPeerMessages;
@@ -258,23 +267,56 @@ export function createSendMessageTool(opts) {
                 if (boxFull) {
                     return { content: `Message not sent: ${inlineUntrusted(peerLabel, 200)}'s session box is at its queued-message limit (${admissionConfig.maxQueuedPeerMessages.toFixed(0)}) — the message was NOT queued; it drains the box at its next turn. Resend later. ${DEDUP_RETRY_NOTE.slice(0, 200)}`, details: { error: "queue_full", code: "queue_full", to }, isError: true };
                 }
-                const modeClass = opts.peerSelfSession?.modeClass?.();
-                const peerMeta = {
-                    ...(peerSelfSessionId !== undefined ? { fromSession: peerSelfSessionId } : {}),
-                    ...(modeClass === "bypass" || modeClass === "prompting" ? { fromMode: modeClass } : {}),
-                    ...(senderKey !== undefined ? { senderKey } : {}),
-                    kind: "peer_message",
-                };
-                const now = Date.now();
                 let seq;
-                try {
-                    seq = await opts.mailbox.append(peerScope, handle, { from: ownRowName ?? opts.peerSelfSession?.name ?? senderLabel, content: storedContent, sentAt: now, hopChain: prospectiveChain, peerMeta });
+                if (message !== "") {
+                    const recipientKey = peerAxisToken(peerScope, "s", record.sessionId);
+                    const storedContent = `[${summary}] ${clipCarrierMessage(message)}`;
+                    const sendVerdict = judgePeerAdmission(peerScope, recipientKey, { senderKey, body: storedContent, prospectiveChain, ownTokens: [recipientKey] }, admissionConfig, undefined, "send");
+                    if (!sendVerdict.ok)
+                        return admissionRefusal(sendVerdict.reason, peerLabel);
+                    const peerMeta = {
+                        ...(peerSelfSessionId !== undefined ? { fromSession: peerSelfSessionId } : {}),
+                        ...(modeClass === "bypass" || modeClass === "prompting" ? { fromMode: modeClass } : {}),
+                        ...(senderKey !== undefined ? { senderKey } : {}),
+                        kind: "peer_message",
+                    };
+                    try {
+                        seq = await opts.mailbox.append(peerScope, handle, { from: ownRowName ?? opts.peerSelfSession?.name ?? senderLabel, content: storedContent, sentAt: now, hopChain: prospectiveChain, peerMeta });
+                    }
+                    catch (e) {
+                        if (e?.code === MAILBOX_TOMBSTONED_RECIPIENT_CODE) {
+                            return peerRefusal("peer_send.invalid_target", `${peerLabel} is being deleted — its box no longer accepts messages. Nothing was parked; do not retry.`);
+                        }
+                        return peerRefusal("peer_send.other", `the session box refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked. ${DEDUP_RETRY_NOTE}`);
+                    }
                 }
-                catch (e) {
-                    if (e?.code === MAILBOX_TOMBSTONED_RECIPIENT_CODE) {
-                        return peerRefusal("peer_send.invalid_target", `${peerLabel} is being deleted — its box no longer accepts messages. Nothing was parked; do not retry.`);
+                let subscription;
+                let subscriptionSeq;
+                if (notifyWhenIdle) {
+                    if (peerSelfSessionId === undefined) {
+                        subscription = { ok: false, code: "peer_send.other", severity: "error", message: "this mount has no session identity, so no idle notice could be addressed back to it — no subscription was made." };
+                    }
+                    else {
+                        const ask = peerIdleMachineFor(peerScope, peerSelfSessionId).requester.request(record.sessionId, peerIdleNoticeLabel(record.name) ?? handle);
+                        if (!ask.ok) {
+                            subscription = { ok: false, code: "peer_send.subscription_cap", severity: peerSendVerdictSeverity("peer_send.subscription_cap"), message: `you already hold ${PEER_IDLE_OUTSTANDING_CAP} outstanding idle subscriptions — no new one was made; wait for a notice or for one to expire.` };
+                        }
+                        else {
+                            const subMeta = {
+                                fromSession: peerSelfSessionId,
+                                ...(modeClass === "bypass" || modeClass === "prompting" ? { fromMode: modeClass } : {}),
+                                kind: "idle_subscription",
+                            };
+                            try {
+                                subscriptionSeq = await opts.mailbox.append(peerScope, handle, { from: ownRowName ?? opts.peerSelfSession?.name ?? senderLabel, content: `[idle subscription] ${ownRowName ?? opts.peerSelfSession?.name ?? senderLabel} asked to be told once when this session next goes idle`, sentAt: now, hopChain: [], peerMeta: subMeta });
+                                subscription = { ok: true, disposition: record.liveness !== "live" ? "parked_offline" : "queued", via: "store" };
+                            }
+                            catch (e) {
+                                peerIdleMachineFor(peerScope, peerSelfSessionId).requester.settle(record.sessionId, "unavailable");
+                                subscription = { ok: false, code: e?.code === MAILBOX_TOMBSTONED_RECIPIENT_CODE ? "peer_send.invalid_target" : "peer_send.other", severity: "error", message: `the session box refused the subscription record (${(e instanceof Error ? e.message : String(e)).slice(0, 200)}) — no subscription was made.` };
+                            }
+                        }
                     }
-                    return peerRefusal("peer_send.other", `the session box refused the message (${e instanceof Error ? e.message : String(e)}) — nothing was parked. ${DEDUP_RETRY_NOTE}`);
                 }
                 let rowRestored = "present";
                 try {
@@ -294,12 +336,26 @@ export function createSendMessageTool(opts) {
                         ? " Note: that session was DELETED while this message was being parked — its box is being retired and this message will not be read; do not resend to it."
                         : "";
                 const offline = record.liveness !== "live";
+                const subscriptionNote = subscription === undefined
+                    ? ""
+                    : subscription.ok
+                        ? ` Idle subscription recorded (one-shot, expires unheard after ${PEER_IDLE_SUBSCRIPTION_TTL_MS / 3_600_000} h): you will get ONE automated notice when that session next goes idle or exits${offline ? " — it is offline now, so the ask waits in its box with the message" : ""}. Do not poll for it.`
+                        : ` Idle subscription NOT made (${subscription.code}): ${subscription.message}`;
+                if (seq === undefined) {
+                    if (subscription === undefined || !subscription.ok) {
+                        return { content: `Subscription not made: ${subscription?.message ?? "nothing to do"}`, details: { error: subscription?.code ?? "peer_send.other", code: subscription?.code ?? "peer_send.other", to, ...(subscription !== undefined ? { subscription } : {}) }, isError: true };
+                    }
+                    return {
+                        content: `Idle subscription recorded for ${peerLabel} (record seq ${subscriptionSeq}): you will get ONE automated notice when that session next goes idle or exits (one-shot; it expires unheard after ${PEER_IDLE_SUBSCRIPTION_TTL_MS / 3_600_000} h). No message was sent. Do not poll for it; continue with your task.${rowNote}`,
+                        details: { type: "send-message", status: "peer_idle_subscribed", to, address: handle, subscription, ...(subscriptionSeq !== undefined ? { subscriptionSeq } : {}), ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}) },
+                    };
+                }
                 const verdict = { ok: true, disposition: offline ? "parked_offline" : "queued", via: "store" };
                 return {
                     content: offline
-                        ? `Message parked for ${peerLabel}: that session is offline, so the message was parked durably in its session box (seq ${seq}) and will be delivered when it next runs — subject to the deployment's mailbox retirement policy, which does not notify you. Continue with your task; do not resend the same content.${rowNote}`
-                        : `Message queued for ${peerLabel} (seq ${seq}): it is parked durably in that session's box and will be read at its next turn boundary. This receipt confirms acceptance into the box, not the peer's judgment of the message. Continue with your task; do not resend the same content.${rowNote}`,
-                    details: { type: "send-message", status: offline ? "peer_parked_offline" : "peer_queued", to, address: handle, seq, verdict, ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}) },
+                        ? `Message parked for ${peerLabel}: that session is offline, so the message was parked durably in its session box (seq ${seq}) and will be delivered when it next runs — subject to the deployment's mailbox retirement policy, which does not notify you. Continue with your task; do not resend the same content.${subscriptionNote}${rowNote}`
+                        : `Message queued for ${peerLabel} (seq ${seq}): it is parked durably in that session's box and will be read at its next turn boundary. This receipt confirms acceptance into the box, not the peer's judgment of the message. Continue with your task; do not resend the same content.${subscriptionNote}${rowNote}`,
+                    details: { type: "send-message", status: offline ? "peer_parked_offline" : "peer_queued", to, address: handle, seq, verdict, ...(subscription !== undefined ? { subscription } : {}), ...(subscriptionSeq !== undefined ? { subscriptionSeq } : {}), ...(rowRestored !== "present" ? { directoryRow: rowRestored } : {}) },
                 };
             };
             const settlePeerResolution = async (r) => {
@@ -329,6 +385,16 @@ export function createSendMessageTool(opts) {
                     }
                 }
             };
+            if (notifyWhenIdle) {
+                if (!peerLane.active) {
+                    return peerRefusal("peer_send.invalid_target", peerLane.reason !== undefined ? `notify_when_idle is only supported for peer sessions of this engine, and the cross-session lane is unavailable on this mount — ${peerLane.reason}. Nothing was sent.` : `notify_when_idle is only supported for peer sessions of this engine, and cross-session addressing is not mounted here (no peer-session directory). Nothing was sent.`);
+                }
+                if (senderIsChild) {
+                    return peerRefusal("peer_send.invalid_target", "notify_when_idle is only available from the main conversation of this session (not from a subagent or teammate). Nothing was sent.");
+                }
+                const settled = await settlePeerResolution(await resolvePeerTarget());
+                return settled ?? peerRefusal("peer_send.invalid_target", `notify_when_idle is only supported for peer sessions of this engine (not teammates, subagents or agents), and no peer session is registered as "${inlineUntrusted(to, 120)}". Nothing was sent.`);
+            }
             if (parsePeerSessionAddress(to) !== undefined) {
                 if (!peerLane.active) {
                     return peerRefusal("peer_send.invalid_target", peerLane.reason !== undefined ? `cross-session addressing is unavailable on this mount — ${peerLane.reason}. Nothing was sent.` : `cross-session addressing is not mounted here (no peer-session directory), so "${inlineUntrusted(to, 120)}" cannot be delivered.`);

package/dist/agents/subagent.js

@@ -2113,6 +2113,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : ctx.parentCwd !== undefined
                             ? { parentCwd: ctx.parentCwd }
                             : {}),
+                ...(reviveClaim === undefined && ctx.fileHistoryLineage !== undefined ? { fileHistoryLineage: ctx.fileHistoryLineage } : {}),
                 ...(ctx.onSubagentSpawn ? { onSubagentSpawn: ctx.onSubagentSpawn } : {}),
             };
             const childThinking = def?.thinking ?? ctx.thinkingLevel;

package/dist/brain/status-sink.d.ts

@@ -16,6 +16,16 @@ export declare function runWithStatusSink<T>(emit: (s: BrainStatus) => void, fn:
  * call site for this exact reason and states the contract ("an advisory frame must never break a settled
  * call"); the guard belongs HERE so every call site inherits it rather than each remembering.
  */
+/**
+ * #530 — bind the ACTIVE sink now, for an emit that will happen from a timer callback later. The
+ * async-local store propagates through Node's timers, but not through every timer implementation a
+ * process may run under (fake clocks in tests replace `setTimeout` outright and run callbacks from
+ * their own stack, where `getStore()` is empty). A frame scheduled inside the sink's scope must reach
+ * that sink whichever clock fires it, so the scheduler captures the store here and the callback emits
+ * through the bound function. Same swallow guard and the same retryAtMs stamp as {@link emitBrainStatus};
+ * a no-op function when no sink is active.
+ */
+export declare function bindBrainStatusEmitter(): (status: BrainStatus) => void;
 export declare function emitBrainStatus(status: BrainStatus): void;
 /**
  * Silent-fallback telemetry (C1/C4/C5/C6) — the brain→runner TELEMETRY channel, a

package/dist/brain/status-sink.js

@@ -3,16 +3,25 @@ const statusSinkStore = new AsyncLocalStorage();
 export function runWithStatusSink(emit, fn) {
     return statusSinkStore.run({ emit }, fn);
 }
-export function emitBrainStatus(status) {
+export function bindBrainStatusEmitter() {
+    const sink = statusSinkStore.getStore();
+    if (sink === undefined)
+        return () => undefined;
+    return (status) => deliverBrainStatus(sink, status);
+}
+function deliverBrainStatus(sink, status) {
     try {
-        const sink = statusSinkStore.getStore();
-        if (sink === undefined)
-            return;
         sink.emit(withRetryDeadline(status));
     }
     catch {
     }
 }
+export function emitBrainStatus(status) {
+    const sink = statusSinkStore.getStore();
+    if (sink === undefined)
+        return;
+    deliverBrainStatus(sink, status);
+}
 function withRetryDeadline(status) {
     if (status.retryAtMs !== undefined)
         return status;

package/dist/brain/stream-engine.d.ts

@@ -89,6 +89,17 @@ export declare function sameRequestModuloCap(original: SSERequest, rebuilt: SSER
  * Tolerates a `doFetch` (BYOM injection point) whose Response-shaped return has no usable `headers`.
  */
 export declare function shouldRetryHeaderVerdict(res: Response | undefined): boolean | undefined;
+/**
+ * #530 — the first-token WAIT disclosure. While a first-token watchdog is armed
+ * (`firstTokenTimeoutMs > 0`) and no content token has arrived, the engine says so on the status
+ * channel: the FIRST `waiting_first_token` frame goes out once the wait has lasted
+ * {@link WAITING_FIRST_TOKEN_AFTER_MS}, and one more every {@link WAITING_FIRST_TOKEN_EVERY_MS} after
+ * that, until the first token lands, the watchdog fires, or the attempt ends. A short wait (under the
+ * threshold) announces nothing — the frame exists for the unattended "no answer for a minute" case,
+ * not for every request. The same 30s slice the retry countdown re-announces on.
+ */
+export declare const WAITING_FIRST_TOKEN_AFTER_MS = 30000;
+export declare const WAITING_FIRST_TOKEN_EVERY_MS = 30000;
 export interface SSERequest {
     url: string;
     headers: Record<string, string>;

package/dist/brain/stream-engine.js

@@ -3,7 +3,7 @@ import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } fr
 import { BrainError, classifyConnectFailure, classifyHttp, describeNetworkError, namesTheFailure, readProviderRequestId } from "./errors.js";
 import { classifyInputTooLong } from "./input-too-long.js";
 import { FAST_MAX_BACKOFF_MS, providerWaitHint, retryBackoffMs } from "./retry.js";
-import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
+import { bindBrainStatusEmitter, emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
 const DEFAULT_MAX_RETRIES = 10;
 const MAX_RETRIES_ENV_CEILING = 15;
@@ -189,6 +189,8 @@ export function shouldRetryHeaderVerdict(res) {
     return undefined;
 }
 const RETRY_STATUS_SLICE_MS = 30_000;
+export const WAITING_FIRST_TOKEN_AFTER_MS = 30_000;
+export const WAITING_FIRST_TOKEN_EVERY_MS = 30_000;
 const THINKING_RETRY_BUDGET = 2;
 const EMPTY_USAGE = {
     input: 0,
@@ -249,6 +251,8 @@ export function runStreamingBrain(args) {
     const out = createAssistantMessageEventStream();
     let cleanup;
     let announcedRetry = false;
+    let announcedWait = false;
+    let terminalWaitDetail = "first token arrived";
     let terminalRetryPhase = "recovered";
     let terminalRetryDetail = "recovered after retrying";
     let requestIdSeen;
@@ -257,6 +261,7 @@ export function runStreamingBrain(args) {
         const aborted = signal?.aborted === true || isAbortError(err);
         terminalRetryPhase = "gave_up";
         terminalRetryDetail = aborted ? "cancelled while retrying" : "retries exhausted";
+        terminalWaitDetail = aborted ? "cancelled while waiting for the first token" : "the first-token wait ended in failure";
         const errorMsg = emptyAssistant(model);
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = err instanceof Error ? err.message : String(err);
@@ -278,10 +283,10 @@ export function runStreamingBrain(args) {
     })
         .finally(() => {
         cleanup?.();
-        if (!announcedRetry)
+        if (!announcedRetry && !announcedWait)
             return;
         try {
-            emitBrainStatus({ phase: terminalRetryPhase, detail: terminalRetryDetail });
+            emitBrainStatus({ phase: terminalRetryPhase, detail: announcedRetry ? terminalRetryDetail : terminalWaitDetail });
         }
         catch {
         }
@@ -468,11 +473,39 @@ export function runStreamingBrain(args) {
             let firstTokenSeen = false;
             let firstTokenTimedOut = false;
             let ftTimer;
+            let waitTimer;
+            const clearWaitTimer = () => {
+                if (waitTimer) {
+                    clearTimeout(waitTimer);
+                    waitTimer = undefined;
+                }
+            };
             if (firstTokenTimeoutMs && firstTokenTimeoutMs > 0) {
                 ftTimer = setTimeout(() => {
                     firstTokenTimedOut = true;
+                    clearWaitTimer();
                     void reader.cancel().catch(() => undefined);
                 }, firstTokenTimeoutMs);
+                if (firstTokenTimeoutMs > WAITING_FIRST_TOKEN_AFTER_MS) {
+                    const waitStartedAt = Date.now();
+                    const emitWaitFrame = bindBrainStatusEmitter();
+                    const scheduleWaitFrame = (delayMs) => {
+                        waitTimer = setTimeout(() => {
+                            waitTimer = undefined;
+                            if (firstTokenSeen || firstTokenTimedOut || Date.now() - waitStartedAt >= firstTokenTimeoutMs)
+                                return;
+                            announcedWait = true;
+                            emitWaitFrame({
+                                phase: "waiting_first_token",
+                                detail: "waiting for the first token",
+                                elapsedMs: Date.now() - waitStartedAt,
+                                timeoutMs: firstTokenTimeoutMs,
+                            });
+                            scheduleWaitFrame(WAITING_FIRST_TOKEN_EVERY_MS);
+                        }, delayMs);
+                    };
+                    scheduleWaitFrame(WAITING_FIRST_TOKEN_AFTER_MS);
+                }
             }
             let idleTimedOut = false;
             let idleTimer;
@@ -497,12 +530,14 @@ export function runStreamingBrain(args) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
+                clearWaitTimer();
             };
             cleanup = () => {
                 if (ftTimer) {
                     clearTimeout(ftTimer);
                     ftTimer = undefined;
                 }
+                clearWaitTimer();
                 if (idleTimer) {
                     clearTimeout(idleTimer);
                     idleTimer = undefined;
@@ -575,6 +610,7 @@ export function runStreamingBrain(args) {
                 clearTimeout(ftTimer);
                 ftTimer = undefined;
             }
+            clearWaitTimer();
             if (idleTimer) {
                 clearTimeout(idleTimer);
                 idleTimer = undefined;

package/dist/core/arg-summary.d.ts

@@ -71,9 +71,19 @@ export interface RedactionPass {
     /** A literal replacement (only `$1` substitution is used by these passes) or a replacer fn. */
     replace: string | ((match: string, ...groups: string[]) => string);
 }
-/** Run the declared passes in order, collecting findings (original-input spans) when a report is given.
- *  An idempotent no-op replacement (inserted === matched, e.g. re-scrubbing already-redacted text) is
- *  NOT a finding — nothing was removed. */
+/**
+ * Run the declared passes in order, collecting findings (original-input spans) when a report is given.
+ *
+ * FORMAT CHARACTERS (#532): the passes scan a VIEW of the input with every `\p{Cf}` removed, so a
+ * credential split by a zero-width character is one token to the scanner, not two fragments of which
+ * only the first (or neither) matches. The OUTPUT keeps every format character that sits OUTSIDE a
+ * replaced span — a joiner in an emoji sequence, a non-joiner in Persian text, a soft hyphen in a word
+ * — and drops only those INSIDE the span the marker replaces (they were part of the secret). A
+ * format-free input takes the exact historical path (byte-identical output). When the replacements
+ * cannot be mapped back exactly (a later pass matched across an earlier pass's inserted text), the
+ * output is the redacted view itself — every format character dropped: the failure direction is
+ * over-stripping, never a leak.
+ */
 export declare function runRedactionPasses(input: string, passes: readonly RedactionPass[], report?: RedactionReport): string;
 /** The credential-shape passes (the pre-channel SECRET_PATTERNS, now with declared kinds/confidence).
  *  Exported for {@link runRedactionPasses} composition (untrusted-egress chains its URL passes after

package/dist/core/arg-summary.js

@@ -25,10 +25,10 @@ function mapBackOnePass(edits, pos) {
     return pos - delta;
 }
 const PREEXISTING_MARKER_RE = /\[redacted(?:-[a-z]+)?\]/g;
-export function runRedactionPasses(input, passes, report) {
-    if (report !== undefined && report.preexistingMarkers === undefined) {
-        report.preexistingMarkers = input.match(PREEXISTING_MARKER_RE)?.length ?? 0;
-    }
+const FORMAT_CHAR_RE = /\p{Cf}/u;
+const MAX_FORMAT_SLOT_SCANS = 64;
+const REDACTED_WHOLE = "[redacted]";
+function applyPasses(input, passes, report, toOriginal) {
     const batches = [];
     let cur = input;
     for (const pass of passes) {
@@ -51,18 +51,149 @@ export function runRedactionPasses(input, passes, report) {
                     report.findings.push({
                         kind: pass.kind,
                         confidence: pass.confidence,
-                        span: [s0, e0],
+                        span: [toOriginal(s0), toOriginal(e0)],
                         marker: pass.marker,
                         source: pass.source,
                     });
                 }
-                edits.push({ at: offset, removedLen: match.length, insertedLen: inserted.length });
+                edits.push({ at: offset, removedLen: match.length, insertedLen: inserted.length, inserted });
             }
             return inserted;
         });
         batches.push(edits);
     }
-    return cur;
+    return { out: cur, batches };
+}
+function replacedSpans(batches) {
+    const spans = [];
+    for (let j = 0; j < batches.length; j++) {
+        for (const e of batches[j]) {
+            let s0 = e.at;
+            let e0 = e.at + e.removedLen;
+            for (let i = j - 1; i >= 0; i--) {
+                s0 = mapBackOnePass(batches[i], s0);
+                e0 = mapBackOnePass(batches[i], e0);
+            }
+            if (e0 - s0 !== e.removedLen)
+                return undefined;
+            spans.push({ start: s0, end: e0, inserted: e.inserted, pass: j });
+        }
+    }
+    spans.sort((a, b) => a.start - b.start);
+    for (let i = 1; i < spans.length; i++)
+        if (spans[i].start < spans[i - 1].end)
+            return undefined;
+    return spans;
+}
+export function runRedactionPasses(input, passes, report) {
+    if (report !== undefined && report.preexistingMarkers === undefined) {
+        report.preexistingMarkers = input.match(PREEXISTING_MARKER_RE)?.length ?? 0;
+    }
+    if (!FORMAT_CHAR_RE.test(input))
+        return applyPasses(input, passes, report, (pos) => pos).out;
+    const viewChars = [];
+    const viewToOriginal = [];
+    const formatAtSlot = [];
+    const charStartOffsets = [];
+    {
+        let orig = 0;
+        let viewOff = 0;
+        let slotBuf = "";
+        for (const ch of input) {
+            if (FORMAT_CHAR_RE.test(ch)) {
+                slotBuf += ch;
+            }
+            else {
+                formatAtSlot.push(slotBuf);
+                slotBuf = "";
+                viewToOriginal.push(orig);
+                charStartOffsets.push(viewOff);
+                viewChars.push(ch);
+                viewOff += ch.length;
+            }
+            orig += ch.length;
+        }
+        formatAtSlot.push(slotBuf);
+        viewToOriginal.push(input.length);
+        charStartOffsets.push(viewOff);
+    }
+    const view = viewChars.join("");
+    const offsetToCharIndex = new Map();
+    charStartOffsets.forEach((off, idx) => offsetToCharIndex.set(off, idx));
+    const toOriginal = (pos) => {
+        const idx = offsetToCharIndex.get(pos);
+        return idx === undefined ? input.length : viewToOriginal[idx];
+    };
+    const { out, batches } = applyPasses(view, passes, report, toOriginal);
+    const viewSpans = replacedSpans(batches);
+    if (viewSpans === undefined)
+        return out;
+    const spans = viewSpans.map((sp) => {
+        const startIdx = offsetToCharIndex.get(sp.start) ?? viewChars.length;
+        const endIdx = offsetToCharIndex.get(sp.end) ?? viewChars.length;
+        const lastIdx = endIdx - 1;
+        const endOrig = lastIdx >= startIdx && lastIdx < viewChars.length ? viewToOriginal[lastIdx] + viewChars[lastIdx].length : viewToOriginal[startIdx];
+        return { start: viewToOriginal[startIdx], end: endOrig, inserted: sp.inserted };
+    });
+    const viewOffsetToOriginal = (viewStart, viewEnd) => {
+        const startIdx = offsetToCharIndex.get(viewStart) ?? viewChars.length;
+        const endIdx = offsetToCharIndex.get(viewEnd) ?? viewChars.length;
+        const lastIdx = endIdx - 1;
+        const endOrig = lastIdx >= startIdx && lastIdx < viewChars.length ? viewToOriginal[lastIdx] + viewChars[lastIdx].length : viewToOriginal[startIdx];
+        return { start: viewToOriginal[startIdx], end: endOrig };
+    };
+    const cutOffsets = [];
+    for (let k = 1; k < viewChars.length; k++)
+        if (formatAtSlot[k] !== "")
+            cutOffsets.push(charStartOffsets[k]);
+    if (cutOffsets.length > MAX_FORMAT_SLOT_SCANS)
+        return REDACTED_WHOLE;
+    const extra = [];
+    const rawSpans = replacedSpans(applyPasses(input, passes, undefined, (pos) => pos).batches);
+    if (rawSpans !== undefined)
+        extra.push(...rawSpans);
+    for (const cut of cutOffsets) {
+        const cutSpans = replacedSpans(applyPasses(view.slice(cut), passes, undefined, (pos) => pos).batches);
+        if (cutSpans === undefined)
+            continue;
+        for (const c of cutSpans) {
+            const o = viewOffsetToOriginal(c.start + cut, c.end + cut);
+            extra.push({ start: o.start, end: o.end, inserted: c.inserted, pass: c.pass });
+        }
+    }
+    extra.sort((a, b) => a.start - b.start);
+    for (const r of extra) {
+        const overlapping = spans.find((v) => r.start < v.end && v.start < r.end);
+        if (overlapping !== undefined) {
+            if (r.start < overlapping.start)
+                overlapping.start = r.start;
+            if (r.end > overlapping.end)
+                overlapping.end = r.end;
+            continue;
+        }
+        spans.push({ start: r.start, end: r.end, inserted: r.inserted });
+        if (report !== undefined) {
+            const pass = passes[r.pass];
+            report.findings.push({ kind: pass.kind, confidence: pass.confidence, span: [r.start, r.end], marker: pass.marker, source: pass.source });
+        }
+        spans.sort((a, b) => a.start - b.start);
+    }
+    for (let i = 1; i < spans.length;) {
+        if (spans[i].start < spans[i - 1].end) {
+            spans[i - 1].end = Math.max(spans[i - 1].end, spans[i].end);
+            spans.splice(i, 1);
+        }
+        else
+            i++;
+    }
+    let result = "";
+    let cursor = 0;
+    for (const sp of spans) {
+        result += input.slice(cursor, sp.start) + sp.inserted;
+        cursor = sp.end;
+    }
+    result += input.slice(cursor);
+    return result;
 }
 export const SECRET_PASSES = [
     { kind: "prefixed-token", confidence: "high", marker: "[redacted]", source: "arg-summary", re: /(?<![A-Za-z0-9])(?:sk|pk|rk|gh[opsur])[-_][A-Za-z0-9_-]{8,}/g, replace: "[redacted]" },

package/dist/core/auto-mode-defaults.d.ts

@@ -11,3 +11,14 @@ export declare const AUTO_MODE_DEFAULT_WINDOW_MAX_CHARS = 2000;
  *  recipe canonicalizer needs its VALUE and must not load the assembly face (and its SHA-locked assets)
  *  to get it; `auto-mode-prompt.js` re-exports it, so the public name and its module face are unchanged. */
 export declare const AUTO_MODE_DEFAULTS_SENTINEL = "$defaults";
+/** CC 2.1.250 `FO = {maxConsecutive: 3, maxTotal: 20}` — the classifier DENIAL LIMITS applied when
+ *  `RunnerDeps.autoMode.denialLimit` omits a bound. Count-then-judge: the block that reaches a bound is
+ *  itself the one that falls back to a person (the 3rd consecutive block asks; the 20th total asks). */
+export declare const AUTO_MODE_DENIAL_LIMIT_DEFAULTS: Readonly<{
+    maxConsecutive: number;
+    maxTotal: number;
+}>;
+/** CC 2.1.250 `AKe = 120000` — the fallback ask's auto-deny window (ms) when `autoDenyAfterMs` is omitted.
+ *  `0` disarms the window (the ask waits on the approver alone — the upstream original "fall back to
+ *  prompting" shape). */
+export declare const AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS = 120000;

package/dist/core/auto-mode-defaults.js

@@ -3,3 +3,5 @@ export const AUTO_MODE_DEFAULT_FAILURE_THRESHOLD = 3;
 export const AUTO_MODE_DEFAULT_WINDOW_MAX_ENTRIES = 40;
 export const AUTO_MODE_DEFAULT_WINDOW_MAX_CHARS = 2_000;
 export const AUTO_MODE_DEFAULTS_SENTINEL = "$defaults";
+export const AUTO_MODE_DENIAL_LIMIT_DEFAULTS = Object.freeze({ maxConsecutive: 3, maxTotal: 20 });
+export const AUTO_MODE_DENIAL_AUTO_DENY_DEFAULT_MS = 120_000;