@sema-agent/core 7.2.0 → 7.3.1

package/dist/agents/send-message-tool.d.ts

@@ -3,6 +3,8 @@ import type { Runner } from "../core/runner/runtask.js";
 import type { TaskNotificationPayload } from "../core/task-notification.js";
 import { type ToolCtxEnricher } from "../core/tools.js";
 import { type TaskAccess } from "../core/task-registry.js";
+import type { PermissionModeClass } from "./cross-session-envelope.js";
+import { type PeerDirectory } from "./peer-directory.js";
 import { SubagentRetainLedger } from "./retain-ledger.js";
 import { type SubagentSteerHandle } from "./subagent.js";
 import { type PeerAdmissionConfig, type PeerInboundChainRef, type PeerSelfRef } from "./peer-admission.js";
@@ -164,6 +166,35 @@ export interface SendMessageToolOptions {
      * per-call honest refusal is the only loudness (unchanged behavior).
      */
     onTranscriptIntegrityGap?: (handle: string, scope: string | undefined) => void;
+    /**
+     * design/385 §2 — the peer-session DIRECTORY ({@link import("../core/types.js").RunnerDeps.peerDirectory}):
+     * opens the cross-session lane's two rungs on this face — the explicit `session.<id>` address arm
+     * (ranked beside the precise a* id) and the LAST name rung (`name [ref]` over the directory's full
+     * set, after every agent rung missed). Needs {@link mailbox} beside it AND that store's
+     * `crossProcessSafe: true` declaration: with the directory wired but either missing, the lane stays
+     * closed and every peer-addressed send refuses with the named reason (never a silent fall-through to
+     * "no agent matches"). Absent ⇒ byte-identical pre-385 behavior.
+     */
+    peerDirectory?: PeerDirectory;
+    /**
+     * design/385 — THIS session's own identity on the cross-session lane: its session id (the sender's
+     * `from-session` / reply address, and the self-target guard), the scope its directory rows live in,
+     * its display name (the `from-name` attestation), and the live fold of its own permission-mode class
+     * ({@link import("./cross-session-judge.js").foldPermissionModeClass} over the wiring manifest's
+     * `ask.effective`) — read at SEND time, attested on the parked record's typed `peerMeta.fromMode`.
+     * The Runner mount fills it; a direct mount without it sends with no session attestation (the
+     * recipient then judges it as "no class asserted").
+     */
+    peerSelfSession?: {
+        sessionId: string;
+        scope?: string;
+        name?: string;
+        modeClass?: () => PermissionModeClass | "unknown";
+    };
+    /** design/385 §5.1 — is `ListAgents` mounted beside this tool? Drives the "list them with ListAgents"
+     *  phrase (a face never names a tool the roster does not carry — an `excludeTools` may drop one of the
+     *  pair). Absent = unknown ⇒ the phrase is hedged. */
+    peerListingMounted?: boolean;
 }
 /** RB-382 — max chars of the `summary` arg (the short recap label, distinct from `message`'s much
  *  larger {@link UPLINK_RESULT_MAX}) before ITS OWN truncation. Exported for direct unit-testing only

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

@@ -3,7 +3,9 @@ import { defineTool } from "../core/tools.js";
 import { normalizeAgentName, DURABLE_AGENT_HANDLE_RE, DURABLE_AGENT_HEARTBEAT_MS } from "../core/task-registry.js";
 import { announceTranscriptIntegrityGapOnce, canAccessAgentRecord, clearRevivedRowTerminalPayload } from "../core/background-agent-store.js";
 import { uuidv7 } from "../internal/harness.js";
-import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../core/mailbox-store.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 { 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";
@@ -29,6 +31,7 @@ function frameTeammateMessage(args) {
     return `<${TEAMMATE_MESSAGE_TAG} teammate_id="${escapeAttributeValue(args.from)}"${summaryAttr}>\n${body}\n</${TEAMMATE_MESSAGE_TAG}>`;
 }
 const REVIVE_LEASE_TTL_MS = 5 * 60_000;
+const PEER_REFUSAL_TEXT_MAX = 1200;
 const sendMessageTargetLanes = new Map();
 function withTargetLane(key, fn) {
     const prev = sendMessageTargetLanes.get(key) ?? Promise.resolve();
@@ -47,6 +50,14 @@ 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 peerLane = (() => {
+        if (opts.peerDirectory === undefined)
+            return { active: false };
+        if (opts.mailbox === undefined)
+            return { active: false, reason: "a peer-session directory is wired but no mailbox store is (the lane parks messages in the recipient's durable session box)" };
+        const verdict = mailboxCrossProcessMountVerdict(opts.mailbox);
+        return verdict.ok ? { active: true } : { active: false, reason: verdict.reason };
+    })();
     const retrievalMounted = opts.retrievalToolMounted;
     const retrievalHedge = retrievalMounted === undefined ? " (where that tool is mounted)" : "";
     const RETRIEVE_NOW = retrievalMounted === false
@@ -129,7 +140,10 @@ export function createSendMessageTool(opts) {
             (tier3Capable
                 ? `Continuing a finished agent works for agents with a durable record — by name or task_id, even across restarts — and for runs that retain sub-agent sessions; when neither covers it you get an honest error and should launch a new agent with the needed context instead.`
                 : `Continuing a finished agent requires the run to retain sub-agent sessions; when the session was not ` +
-                    `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`),
+                    `retained (or is no longer held) you get an honest error and should launch a new agent with the needed context instead.`) +
+            (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." }),
@@ -179,9 +193,9 @@ export function createSendMessageTool(opts) {
                 return { content: OBSERVER_SENDMESSAGE_TARGET_REFUSAL, details: { error: "observer_target", to }, isError: true };
             }
             const admissionConfig = resolvePeerAdmissionConfig(opts.admission);
-            const guardScope = ctx.principal ?? opts.scope;
+            const guardScope = ctx.principal ?? opts.scope ?? opts.peerSelfSession?.scope;
             const selfRef = ctx.peerSelfRef ?? opts.peerSelf;
-            const directMountSessionId = ctx.sessionId ?? opts.sessionId;
+            const directMountSessionId = ctx.sessionId ?? opts.sessionId ?? opts.peerSelfSession?.sessionId;
             const directMountTaskId = ctx.taskId ?? opts.owner;
             const senderKey = selfRef?.current.key ??
                 (directMountSessionId !== undefined
@@ -203,6 +217,125 @@ export function createSendMessageTool(opts) {
                             : `this message's forwarding chain is too long (runaway relay) — stop relaying it; act on it or drop it.`;
                 return { content: `Message not sent: ${text}`, details: { error: reason, code: reason, to }, isError: true };
             };
+            const peerRefusal = (code, text, extra) => {
+                const verdict = { ok: false, code, severity: peerSendVerdictSeverity(code), message: text };
+                return { content: `Message not sent: ${text.slice(0, PEER_REFUSAL_TEXT_MAX)}`, details: { error: code, code, to, verdict, ...extra }, isError: true };
+            };
+            const peerSelfSessionId = opts.peerSelfSession?.sessionId ?? directMountSessionId;
+            const peerScope = guardScope ?? opts.peerSelfSession?.scope;
+            let ownRowName;
+            const resolvePeerTarget = async () => {
+                try {
+                    const rows = await opts.peerDirectory.listPeerSessions({ scope: peerScope ?? "" });
+                    if (peerSelfSessionId !== undefined)
+                        ownRowName = rows.find((r) => r.sessionId.toLowerCase() === peerSelfSessionId.toLowerCase())?.name;
+                    return resolvePeerSessions(rows, to, peerSelfSessionId !== undefined ? { sessionId: peerSelfSessionId } : undefined);
+                }
+                catch (e) {
+                    return { status: "directory_fault", message: e instanceof Error ? e.message : String(e) };
+                }
+            };
+            const deliverToPeerSession = async (c) => {
+                const record = c.record;
+                const handle = peerSessionBoxHandle(record.sessionId);
+                const peerLabel = `peer session "${inlineUntrusted(record.name, 64)}" (${handle})`;
+                if (peerScope === undefined)
+                    return peerRefusal("peer_send.other", `this mount has no scope axis, so ${peerLabel}'s box cannot be addressed.`);
+                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);
+                let boxFull = false;
+                try {
+                    boxFull = (await opts.mailbox.peekCount(peerScope, handle)) >= admissionConfig.maxQueuedPeerMessages;
+                }
+                catch {
+                }
+                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 });
+                }
+                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}`);
+                }
+                let rowRestored = "present";
+                try {
+                    const rowsNow = await opts.peerDirectory.listPeerSessions({ scope: peerScope });
+                    const nowRow = rowsNow.find((r) => r.sessionId.toLowerCase() === record.sessionId.toLowerCase());
+                    if (nowRow?.liveness === "deleted")
+                        rowRestored = "deleted_meanwhile";
+                    else if (nowRow === undefined) {
+                        rowRestored = opts.peerDirectory.restorePeerSession !== undefined && (await opts.peerDirectory.restorePeerSession(record)) ? "restored" : "unrestorable";
+                    }
+                }
+                catch {
+                }
+                const rowNote = rowRestored === "unrestorable"
+                    ? " Note: the peer's directory row disappeared while this message was being parked and this directory cannot restore it — the message is safe in the box (it drains by session id), but the name may not resolve until that session next registers; its session.<id> address still does."
+                    : rowRestored === "deleted_meanwhile"
+                        ? " 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 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 } : {}) },
+                };
+            };
+            const settlePeerResolution = async (r) => {
+                switch (r.status) {
+                    case "directory_fault":
+                        return peerRefusal("peer_send.other", `the peer-session directory could not be read (${r.message}) — nothing was sent.`);
+                    case "not_found":
+                        return undefined;
+                    case "self":
+                        return peerRefusal("peer_send.invalid_target", `"${inlineUntrusted(to, 120)}" is this session — a session cannot send a cross-session message to itself.`);
+                    case "deleted":
+                        return peerRefusal("peer_send.invalid_target", `peer session "${inlineUntrusted(r.candidate.record.name, 64)}" was deleted — its address no longer accepts messages. Nothing was parked.`);
+                    case "stale_ref":
+                        return peerRefusal("peer_send.invalid_target", `the ref [${r.ref}] no longer resolves (the peer set changed since you listed it) — re-run ListAgents and re-send with a current ref.`);
+                    case "ambiguous":
+                        return { content: `Message not sent: ${inlineUntrusted(r.message, 1000)}`, details: { error: "ambiguous", to, candidates: r.candidates.map((c) => ({ name: c.record.name, ref: c.ref, address: peerSessionBoxHandle(c.record.sessionId), liveness: c.record.liveness })) }, isError: true };
+                    case "found": {
+                        const guard = pinGuard(peerSessionBoxHandle(r.candidate.record.sessionId), r.candidate.record.name, r.rung === "name" ? "name" : "ref", to);
+                        if (guard !== undefined)
+                            return guard;
+                        return await withTargetLane(targetLaneKey(peerScope, peerSessionBoxHandle(r.candidate.record.sessionId)), () => deliverToPeerSession(r.candidate));
+                    }
+                    default: {
+                        const _exhaustive = r;
+                        void _exhaustive;
+                        return undefined;
+                    }
+                }
+            };
+            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.`);
+                }
+                const settled = await settlePeerResolution(await resolvePeerTarget());
+                return settled ?? peerRefusal("peer_send.invalid_target", `no session is registered at "${inlineUntrusted(to, 120)}" — nothing was parked (a message is only ever parked for a session that exists or existed).`);
+            }
             if (normalizeAgentName(to) === "main") {
                 if (opts.uplink && senderId !== undefined) {
                     const uplinkIdentity = opts.uplinkRecipient?.current;
@@ -618,6 +751,14 @@ export function createSendMessageTool(opts) {
                     const labels = parentAccess !== undefined
                         ? [...ownLabels, ...opts.registry.runningBackgroundAgentLabels(parentAccess).filter((l) => !ownLabels.includes(l))]
                         : ownLabels;
+                    if (peerLane.active) {
+                        const settled = await settlePeerResolution(await resolvePeerTarget());
+                        if (settled !== undefined)
+                            return settled;
+                    }
+                    else if (peerLane.reason !== undefined) {
+                        return peerRefusal("peer_send.other", `no agent matches "${inlineUntrusted(to, 120)}", and the cross-session lane that could reach a peer session by that name is unavailable on this mount — ${peerLane.reason}.`);
+                    }
                     if (DURABLE_AGENT_HANDLE_RE.test(to)) {
                         return {
                             content: `Message not sent: no transcript found for agent ${to} — launch a new agent with the needed context instead.`,

package/dist/agents/subagent-steps.d.ts

@@ -41,6 +41,17 @@ export interface SubagentEditedFile {
 }
 /** Keep the last N tool steps (CC's tail is ~this deep; older steps are rarely load-bearing for resume). */
 export declare const STEP_CAP = 10;
+/** Hard-bound a line to `max` UTF-16 units — a pure prefix, no marker appended. When the cut would split a
+ *  redaction marker, it moves back to the marker's start (the bound holds, and the output never shows a
+ *  marker fragment); when it would split a surrogate pair, it moves back one unit (never a lone surrogate). */
+export declare function cutAt(line: string, max: number): string;
+/**
+ * Redact, THEN bound — the order every display cut in this module (and the runner's `steering_injected`
+ * previews) uses. Exported so a preview minted elsewhere gets the same marker-aware cut rather than a
+ * raw `slice` that can leave a half marker at the bound. Keeps newlines: a multi-line body is the
+ * caller's shape; only the bound and the redaction are this function's.
+ */
+export declare function redactThenCut(s: string, max: number): string;
 /** The tool's primary argument as a single short line (best-effort; unknown shapes → a compact JSON head). */
 export declare function extractTarget(args: unknown): string;
 /**

package/dist/agents/subagent-steps.js

@@ -1,3 +1,4 @@
+import { redactSecrets } from "../core/untrusted-egress.js";
 export const STEP_CAP = 10;
 const FIELD_MAX = 80;
 const EDITED_FILES_CAP = 32;
@@ -6,9 +7,31 @@ function firstLine(s) {
     const nl = s.indexOf("\n");
     return nl === -1 ? s : s.slice(0, nl);
 }
+const REDACTION_MARKER_RE = /\[redacted(?:-[a-z]+)?\]/g;
+export function cutAt(line, max) {
+    if (line.length <= max)
+        return line;
+    let at = max;
+    for (const m of line.matchAll(REDACTION_MARKER_RE)) {
+        const start = m.index;
+        const end = start + m[0].length;
+        if (start < at && at < end) {
+            at = start;
+            break;
+        }
+        if (start >= at)
+            break;
+    }
+    const lead = line.charCodeAt(at - 1);
+    if (at > 0 && lead >= 0xd800 && lead <= 0xdbff)
+        at -= 1;
+    return line.slice(0, at);
+}
+export function redactThenCut(s, max) {
+    return cutAt(redactSecrets(s), max);
+}
 function clip(s) {
-    const line = firstLine(s).trim();
-    return line.length > FIELD_MAX ? line.slice(0, FIELD_MAX) : line;
+    return redactThenCut(firstLine(s).trim(), FIELD_MAX);
 }
 export function extractTarget(args) {
     if (args === null || typeof args !== "object")
@@ -109,7 +132,7 @@ export class SubagentStepRecorder {
                 const tool = start?.tool ?? e.label ?? e.toolName;
                 const target = start?.target ?? "";
                 const body = outputFirstLine(e.output);
-                const outcome = e.isError ? `error: ${body}`.slice(0, FIELD_MAX) : body;
+                const outcome = e.isError ? cutAt(`error: ${body}`, FIELD_MAX) : body;
                 this.steps.push({ tool, target, outcome });
                 if (this.steps.length > STEP_CAP)
                     this.steps.shift();
@@ -156,7 +179,7 @@ export function stepsFromMessages(messages, lastN) {
             if (b.type !== "toolCall" || typeof b.name !== "string")
                 continue;
             const res = typeof b.id === "string" ? results.get(b.id) : undefined;
-            const outcome = res ? (res.isError ? `error: ${res.body}`.slice(0, FIELD_MAX) : res.body) : "";
+            const outcome = res ? (res.isError ? cutAt(`error: ${res.body}`, FIELD_MAX) : res.body) : "";
             steps.push({ tool: b.name, target: extractTarget(b.arguments), outcome });
         }
     }

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