switchroom 0.19.41 → 0.19.43

package/telegram-plugin/hooks/audience-classify.mjs

@@ -0,0 +1,364 @@
+/**
+ * Audience classification — "who is this text FOR?" (W1-d, issue #3865).
+ *
+ * THE FAILURE THIS EXISTS FOR
+ * ---------------------------
+ * Nothing in the capture → journal → sweep pipeline recorded who a piece of
+ * text was addressed to. Capture selects the terminal assistant-prose run
+ * STRUCTURALLY (`narration-classify.mjs` `selectBackstopDelivery`, substance
+ * floor at `silent-end-scan.mjs`), so when the reply tool throws (#3861) the
+ * agent's trailing working notes are the terminal prose run — they get
+ * journaled as if they were the answer, and the outbox sweep faithfully
+ * delivers internal orchestration prose into the operator's DM hours later.
+ * That is a private-data leak, not a cosmetic one.
+ *
+ * SHARED-PURE-MODULE, ON PURPOSE
+ * ------------------------------
+ * This is a plain `.mjs` with a sibling `.d.mts` (the same shape as
+ * `narration-classify.mjs`) because BOTH halves of the pipeline must run the
+ * IDENTICAL predicate and there is no build step between them:
+ *   - the Stop hooks (`silent-end-scan.mjs`, `silent-end-interrupt-stop.mjs`)
+ *     run unbundled under node and can only import sibling `.mjs`;
+ *   - the gateway (`outbox.ts`, `gateway/outbox-sweep.ts`) is bundled TS.
+ * A second hand-synced copy would drift, and a drift here is a leak.
+ *
+ * EVERYTHING HERE IS PURE. No fs, no env, no clock. The callers own their IO.
+ */
+
+/** Audience: the text is for the human on the other end of the chat. */
+export const AUDIENCE_USER = 'user'
+
+/**
+ * Audience: the text is the agent talking to itself (working notes,
+ * orchestration prose). It may be journaled and inspected, but it must never
+ * be delivered to a chat.
+ */
+export const AUDIENCE_INTERNAL = 'internal'
+
+/**
+ * Obligation state for the resolved chat, as seen at capture time.
+ *
+ * `'unknown'` is a first-class value and is NOT the same as `false`: an
+ * unreadable / malformed `obligations.json` means we could not establish that
+ * the user is NOT waiting on an answer, and the fail-safe direction is to
+ * assume they ARE (see `decideCaptureAudience`).
+ */
+/** @typedef {true | false | 'unknown'} OpenObligationState */
+
+/**
+ * THE classifier. Conservative by construction, and deliberately asymmetric.
+ *
+ * We mark `internal` ONLY on positive evidence:
+ *
+ *     replyToolThrewThisTurn === true  AND  openInboundObligation === false
+ *
+ * Both halves are load-bearing:
+ *   - "the reply tool threw" is what makes the trailing prose suspect at all.
+ *     Without a throw, terminal prose after a bypassed reply tool is the
+ *     ordinary #3513 backstop case and IS the answer.
+ *   - "no open inbound obligation" is what says nobody is waiting. If the user
+ *     asked something and we still owe them a reply, the least-bad move is to
+ *     deliver the prose we have; suppressing it would leave them with silence.
+ *
+ * The asymmetry is the whole safety argument. Getting it wrong in the
+ * `internal` direction produces a SILENT NO-OP (severity 3: the user asked and
+ * got nothing, with no signal). Getting it wrong in the `user` direction
+ * reproduces today's status quo, which is bad but is not a NEW failure class.
+ * So every uncertain input resolves to `user`.
+ *
+ * The narration classifier is deliberately NOT an input here. It is a VETO
+ * only: it already decides, upstream in `selectBackstopDelivery`, whether a
+ * prose run is capturable at all. Promoting it to a positive `internal` signal
+ * would let a heuristic prose-shape match silently swallow a real answer —
+ * exactly the severity-3 error this function is built to avoid.
+ *
+ * @param {{
+ *   replyToolThrewThisTurn?: boolean,
+ *   openInboundObligation?: true | false | 'unknown',
+ * }} signals
+ * @returns {'user' | 'internal'}
+ */
+export function decideCaptureAudience(signals) {
+  const threw = signals?.replyToolThrewThisTurn === true
+  if (!threw) return AUDIENCE_USER
+  // Only a POSITIVE, known-empty obligation state clears the second gate.
+  // `'unknown'`, `true`, and `undefined` all mean "someone may be waiting".
+  if (signals?.openInboundObligation !== false) return AUDIENCE_USER
+  return AUDIENCE_INTERNAL
+}
+
+/**
+ * Resolve the open-inbound-obligation state for a chat from the RAW text of the
+ * gateway's durable obligation snapshot (`<STATE_DIR>/obligations.json`, written
+ * by `persistObligations` on every ledger mutation — open AND close, see
+ * `obligation-ledger.ts:156`). Pure: the caller does the `readFileSync` and
+ * passes `null` when the file is absent or unreadable.
+ *
+ * The three-valued result is the point:
+ *
+ *   - `snapshotTrusted === false` → `'unknown'`, WITHOUT reading the bytes. See
+ *                                  the stale-snapshot note below (#4146).
+ *   - `null` snapshot            → `'unknown'`. An absent file is NOT proof that
+ *                                  nobody is waiting: it is equally the shape of
+ *                                  an agent running with `SWITCHROOM_OBLIGATION_
+ *                                  LEDGER=0`, or a STATIC gateway, where
+ *                                  obligations exist but are never persisted.
+ *                                  Reading it as "empty" would let us suppress on
+ *                                  an agent that simply doesn't track waiting
+ *                                  users — a manufactured silent no-op.
+ *
+ * ## The stale-snapshot hole (#4146) and why `snapshotTrusted` exists
+ *
+ * The bullet above used to be the WHOLE argument, and it was wrong: a leftover
+ * file is not an absent file. Turn the ledger off (or run STATIC) on an agent
+ * that previously ran with it on, and persistence stops while the old
+ * `obligations.json` lingers — so an empty (or merely out-of-date) snapshot
+ * reads as positive proof that nobody is waiting, while obligations are in fact
+ * going untracked. That is the one configuration where the asymmetric default
+ * inverts, and it is a direct path to swallowing a real answer.
+ *
+ * It is closed on BOTH sides, deterministically, with no freshness heuristic:
+ *
+ *   1. THE FILE IS REMOVED when it cannot be maintained. The gateway unlinks
+ *      the snapshot at boot whenever it is STATIC or the ledger is disabled
+ *      (`gateway.ts`, next to the hydrate branch) — the exact site that already
+ *      knows the condition. After that, "absent" genuinely does mean what the
+ *      bullet above claims.
+ *   2. THE READER DOES NOT TRUST IT ANYWAY when it knows persistence is off.
+ *      The hook passes `snapshotTrusted: SWITCHROOM_OBLIGATION_LEDGER !== '0'`,
+ *      which covers the window before that gateway boots, an older gateway
+ *      build that never cleaned up, and a gateway that is not running at all.
+ *
+ * Note the case that ISN'T staleness: with the ledger ON, the snapshot only
+ * ever mutates through the gateway, so a gateway that is merely stopped leaves
+ * a snapshot that is exactly correct rather than stale. That is why an mtime
+ * bound is the wrong instrument here — it would fail an idle-but-accurate
+ * snapshot (weakening #4140 for quiet agents) while still not proving liveness.
+ *   - unparseable / wrong shape  → `'unknown'` (same reasoning; a torn or
+ *                                  forward-incompatible snapshot proves nothing).
+ *   - `chatId == null` (the chat
+ *     could not be resolved) and
+ *     the open set is non-empty  → `'unknown'`. Someone is waiting and we cannot
+ *                                  rule out that it is this record's reader.
+ *   - `chatId == null` and the
+ *     open set is empty          → `false`. Nobody anywhere is waiting, so the
+ *                                  scoping question is moot.
+ *   - otherwise                  → `true` iff some open obligation names this chat.
+ *
+ * @param {{ snapshotRaw?: string | null, chatId?: string | null, snapshotTrusted?: boolean }} args
+ * @returns {true | false | 'unknown'}
+ */
+export function resolveOpenObligation(args) {
+  // #4146: an explicit "persistence is off" beats anything on disk. Only an
+  // exact `false` distrusts — absent/undefined keeps the pre-#4146 behaviour,
+  // so a caller that does not know cannot accidentally weaken the gate.
+  if (args?.snapshotTrusted === false) return 'unknown'
+  const raw = args?.snapshotRaw
+  if (typeof raw !== 'string' || raw.length === 0) return 'unknown'
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return 'unknown'
+  }
+  if (parsed == null || typeof parsed !== 'object') return 'unknown'
+  const rows = parsed.obligations
+  if (!Array.isArray(rows)) return 'unknown'
+  const open = rows.filter(
+    (r) => r != null && typeof r === 'object' && typeof r.chatId === 'string',
+  )
+  const chatId = args?.chatId == null ? null : String(args.chatId)
+  if (chatId == null) return open.length === 0 ? false : 'unknown'
+  return open.some((r) => r.chatId === chatId)
+}
+
+/**
+ * Read the audience off a persisted record or journal entry.
+ *
+ * LEGACY-ROW POLICY (decided in this PR, documented here because this function
+ * IS the policy): a record with no `audience` field — every record written
+ * before this change, plus any record written by a hook that predates it during
+ * a rolling upgrade — resolves to `'user'` and delivers exactly as it does
+ * today.
+ *
+ * Rationale: a legacy record carries no evidence either way, and the
+ * fail-safe direction for no-evidence is the one whose error mode is the
+ * status quo rather than a new silent no-op (see `decideCaptureAudience`). A
+ * legacy record's window is at most `OUTBOX_MAX_AGE_MS` wide, so the legacy
+ * population is bounded and drains within 30 minutes of deploy.
+ *
+ * Any value that is not the exact `'internal'` literal (unknown strings,
+ * numbers, objects, `null`) is also `'user'` — suppression requires an
+ * affirmative, exact tag.
+ *
+ * @param {unknown} value
+ * @returns {'user' | 'internal'}
+ */
+export function resolveRecordAudience(value) {
+  return value === AUDIENCE_INTERNAL ? AUDIENCE_INTERNAL : AUDIENCE_USER
+}
+
+/**
+ * Entry-selection predicate for the sweep. Placed here, shared, and pure so the
+ * gate is a property of the RECORD rather than of whatever send adapter happens
+ * to be wired underneath it — W1-b swaps that adapter out, and this gate must
+ * survive the swap untouched.
+ *
+ * `gateEnabled` is the kill-switch seam (the sweep reads
+ * `SWITCHROOM_TG_OUTBOX_AUDIENCE_GATE !== '0'`). It exists so the revert-check
+ * can run: with the gate off, the leak reproduces and the zero-send assertion
+ * must fail. A test that still passes with the gate off is not testing the gate.
+ *
+ * @param {{ audience?: unknown }} record
+ * @param {{ gateEnabled?: boolean }} [opts]
+ * @returns {boolean}
+ */
+export function shouldSuppressForAudience(record, opts) {
+  if (opts?.gateEnabled === false) return false
+  return resolveRecordAudience(record?.audience) === AUDIENCE_INTERNAL
+}
+
+/**
+ * ── W1-d follow-up (#4141): the FOREGROUND reply-throw case ──────────────────
+ *
+ * `decideCaptureAudience` can only mark `internal` when the reply tool threw
+ * AND nobody is waiting. On a FOREGROUND Telegram turn the inbound obligation
+ * is still OPEN at capture time (it only closes on a substantive DELIVERED
+ * reply — `gateway/obligation-ledger.ts:153-157`), so the record classifies
+ * `user` and the trailing prose still delivers, presented as if it were the
+ * answer. That is the residual leak #4141 tracks.
+ *
+ * WHY THIS IS FRAMING AND NOT SUPPRESSION
+ * ---------------------------------------
+ * There is no deterministic discriminator here. When the reply tool throws, a
+ * model that has been told "every turn MUST end with a reply tool call" very
+ * plausibly re-writes its ANSWER as plain prose — and that prose is selected by
+ * exactly the same structural rule as working notes are. Position does not
+ * separate them (both follow the errored `tool_result`), and wording heuristics
+ * are provably incomplete (`narration-classify.mjs` says so in its own header).
+ *
+ * So suppressing here would trade a VISIBLE wrong-content failure for an
+ * INVISIBLE no-answer failure, against a human who is provably still waiting.
+ * That is strictly worse and it is the exact severity-3 class #3865/#4140 exist
+ * to avoid. Replacing the prose with a fixed notice has the same defect in
+ * milder form: it destroys content that may be the answer.
+ *
+ * What we CAN assert deterministically is the provenance: the reply tool threw
+ * this turn, so this text was never delivered as an answer by the agent — the
+ * safety net scraped it off the end of the turn. Stating that, verbatim, in
+ * front of the text restores exactly the context that #3865 says late delivery
+ * strips ("delivery hours later strips the context that would have made the
+ * difference obvious"). The reader can then tell notes from an answer, which is
+ * something no classifier in this pipeline can do.
+ *
+ * Properties, deliberately:
+ *   - it can NEVER produce silence (something is always delivered);
+ *   - it triggers on a hard structural fact (`is_error: true` on a reply-tool
+ *     `tool_result`), never on prose shape or model discipline;
+ *   - a missing / non-`true` signal changes nothing at all.
+ */
+
+/**
+ * The fixed provenance banner. Plain text in the established sweep-prefix
+ * idiom (`(delayed) `, `(from background task) `) — no markdown specials, so
+ * it cannot parse-reject a rich send, and no emoji.
+ */
+export const REPLY_THROW_PROVENANCE_NOTICE =
+  '(my reply tool errored this turn, so this was never sent as an answer — ' +
+  'the safety net captured the last thing I wrote, which may be working notes)'
+
+/**
+ * Should this record's delivered text carry the provenance banner?
+ *
+ * POSITIVE evidence only: an exact `true` on the record's persisted
+ * `replyToolThrewThisTurn`. Missing, `undefined`, `'true'`, `1` — anything that
+ * is not the boolean — changes nothing, so a legacy record (written before the
+ * field existed) delivers byte-for-byte as it does today.
+ *
+ * `frameEnabled === false` is the kill switch, and it is the seam the
+ * revert-check flips.
+ *
+ * @param {{ replyToolThrewThisTurn?: unknown }} record
+ * @param {{ frameEnabled?: boolean }} [opts]
+ * @returns {boolean}
+ */
+export function shouldFrameReplyThrow(record, opts) {
+  if (opts?.frameEnabled === false) return false
+  return record?.replyToolThrewThisTurn === true
+}
+
+/**
+ * Compose the banner onto the delivered body. Pure; the caller owns the
+ * `(delayed) ` / `(from background task) ` prefixes, which stay OUTSIDE (they
+ * describe the delivery, this describes the text).
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function applyReplyThrowFraming(text) {
+  const body = typeof text === 'string' ? text : ''
+  // Empty body: the sweep's send adapter early-returns on empty text, and a
+  // banner with nothing under it would be a message about nothing. Leave it.
+  if (body.trim().length === 0) return body
+  return `${REPLY_THROW_PROVENANCE_NOTICE}\n\n${body}`
+}
+
+/**
+ * Structured telemetry for a framed delivery — the observability half of the
+ * rule, mirroring {@link formatInternalSuppression}. Framing changes what a
+ * human sees, so it must never be inferable only from the absence of a log
+ * line. Worded to match NONE of `GATEWAY_SIGNATURES` in
+ * `src/fleet-health/detect.ts`: a framed delivery IS a delivery, and must not
+ * page anyone.
+ *
+ * @param {{
+ *   turnNonce: string,
+ *   turnId?: string | null,
+ *   chatId?: string | null,
+ *   textSha256?: string,
+ *   source?: string,
+ * }} s
+ * @returns {string}
+ */
+export function formatReplyThrowFraming(s) {
+  return (
+    `telegram gateway: outbox provenance framing nonce=${s.turnNonce} ` +
+    `turnId=${s.turnId ?? 'unknown'} chatId=${s.chatId ?? 'unresolved'} ` +
+    `sha=${(s.textSha256 ?? '').slice(0, 12)} source=${s.source ?? 'unknown'} ` +
+    `audience=user replyToolThrew=true — captured prose delivered with its ` +
+    `provenance stated, not suppressed\n`
+  )
+}
+
+/**
+ * The structured telemetry line emitted when the sweep suppresses an
+ * `internal` record. Mirrors `formatOrphanEscalation` (#4104): an exported pure
+ * formatter plus an injected `writeLog`, so the line is greppable, unit-
+ * assertable, and CANNOT accidentally become a chat send.
+ *
+ * It carries `turnId=` in the gateway's `<chat>:<thread>#<message>` shape so
+ * `extractTurnId` in `src/fleet-health/detect.ts` can join it back to the turn,
+ * and it is worded so it matches NONE of that file's `GATEWAY_SIGNATURES`:
+ * suppression-by-design is telemetry, not a delivery failure, and must not page
+ * anyone.
+ *
+ * @param {{
+ *   turnNonce: string,
+ *   turnId?: string | null,
+ *   chatId?: string | null,
+ *   textSha256?: string,
+ *   ageMs?: number,
+ *   source?: string,
+ *   pastWindow?: boolean,
+ * }} s
+ * @returns {string}
+ */
+export function formatInternalSuppression(s) {
+  return (
+    `telegram gateway: outbox audience suppression nonce=${s.turnNonce} ` +
+    `turnId=${s.turnId ?? 'unknown'} chatId=${s.chatId ?? 'unresolved'} ` +
+    `sha=${(s.textSha256 ?? '').slice(0, 12)} ageMs=${s.ageMs ?? 0} ` +
+    `source=${s.source ?? 'unknown'} pastWindow=${s.pastWindow === true} ` +
+    `audience=internal — internal prose withheld from chat, journaled terminally\n`
+  )
+}

package/telegram-plugin/hooks/silent-end-interrupt-stop.mjs

@@ -69,6 +69,11 @@ import {
   isCapturedProseDeliveryEnabledEnv,
   isGatewayHeartbeatFresh,
 } from './silent-end-scan.mjs'
+import {
+  decideCaptureAudience,
+  resolveOpenObligation,
+  AUDIENCE_INTERNAL,
+} from './audience-classify.mjs'
 
 // MUST stay in sync with SILENT_END_MAX_RETRIES in telegram-plugin/silent-end.ts
 // (this hook is a standalone .mjs and can't import the TS module).
@@ -114,6 +119,16 @@ function buildNextState(base, decision, retryCount) {
   } else {
     delete next.pendingText
   }
+  // #4141: carry THIS turn's reply-throw signal through to the captured-prose
+  // bridge, which is the delivering machine on the ELECTED path and has no
+  // transcript of its own. Same stale-carryover discipline as `pendingText` /
+  // `turnId`: explicitly DELETED when this turn's scan saw no throw, so a
+  // spread of a prior turn's file can never mislabel a clean turn.
+  if (decision.replyToolThrewThisTurn === true) {
+    next.replyToolThrewThisTurn = true
+  } else {
+    delete next.replyToolThrewThisTurn
+  }
   return next
 }
 
@@ -156,13 +171,64 @@ function outboxAlreadyDelivered(outboxDir, nonce) {
   return false
 }
 
+/**
+ * W1-d (#3865): classify WHO the captured prose is for, at capture time — the
+ * only point in the pipeline that can still see the turn.
+ *
+ * The obligation snapshot is read here (impure) and the verdict is computed by
+ * the shared pure classifier, so the hook and the gateway run the identical
+ * predicate. Any failure resolves to `'user'` via `resolveOpenObligation`'s
+ * `'unknown'` → the record delivers exactly as it does today.
+ *
+ * @param {string} stateDir
+ * @param {{ chatId: string|null, originChatId?: string|null, replyToolThrewThisTurn?: boolean }} capture
+ * @returns {'user' | 'internal'}
+ */
+function classifyCaptureAudience(stateDir, capture) {
+  let snapshotRaw = null
+  try {
+    const p = join(stateDir, 'obligations.json')
+    if (existsSync(p)) snapshotRaw = readFileSync(p, 'utf8')
+  } catch {
+    /* unreadable ⇒ null ⇒ 'unknown' ⇒ 'user' (fail-safe toward delivering) */
+  }
+  // #4146: with the ledger disabled, obligations are going UNTRACKED and any
+  // file on disk is a leftover, not a fact. Distrust it outright rather than
+  // read a stale empty set as positive proof that nobody is waiting — that is
+  // the one configuration in which the asymmetric default would invert. (The
+  // gateway also unlinks the snapshot at boot in this mode; this is the
+  // reader-side half, covering the window before it does.)
+  // STATIC is the second persistence-off mode (`gateway.ts:1343` gates the same
+  // `onChange` wiring on it at `:2810`), so it must distrust the file for the
+  // same reason. Writer-side cleanup already covers it at boot; this leg covers
+  // the window the writer cannot — an unlink that failed (EACCES) or a gateway
+  // that has not restarted since the mode changed. Honest caveat:
+  // `TELEGRAM_ACCESS_MODE` is supplied by the host, not by this repo, so if it
+  // is not exported into the hook's environment this leg degrades to a no-op and
+  // the writer-side unlink remains the cover. It can only ever move the verdict
+  // toward DELIVER, so a degraded read is never worse than today.
+  const snapshotTrusted =
+    process.env.SWITCHROOM_OBLIGATION_LEDGER !== '0' &&
+    process.env.TELEGRAM_ACCESS_MODE !== 'static'
+  return decideCaptureAudience({
+    replyToolThrewThisTurn: capture.replyToolThrewThisTurn === true,
+    openInboundObligation: resolveOpenObligation({
+      snapshotRaw,
+      snapshotTrusted,
+      // Same chat the sweep will route to: the envelope chat when present,
+      // else this session's origin chat (`resolveOutboxChat`'s F2 fallback).
+      chatId: capture.chatId ?? capture.originChatId ?? null,
+    }),
+  })
+}
+
 /**
  * Write the durable outbox record for a captured undelivered final answer
  * (atomic tmp+rename), mirroring `writeOutboxRecordAtomic` in `../outbox.ts`.
  * The gateway heartbeat sweep is the single deliverer. Best-effort; never
  * throws. Returns true when a record exists on disk for the nonce afterward.
  */
-function writeOutboxRecord(stateDir, capture) {
+function writeOutboxRecord(stateDir, capture, audience) {
   const outboxDir = join(stateDir, 'outbox')
   try {
     mkdirSync(outboxDir, { recursive: true })
@@ -187,6 +253,18 @@ function writeOutboxRecord(stateDir, capture) {
       // journal alone. Driven by the SAME boolean that gates capture-vs-election
       // in main() — fix and telemetry cannot drift.
       replyAlreadyDeliveredThisTurn: capture.replyAlreadyDeliveredThisTurn === true,
+      // W1-d (#3865): WHO this text is for. Always stamped explicitly (never
+      // left implicit) so a post-change record is self-describing and the
+      // sweep's gate never has to infer. `'user'` is byte-for-byte the
+      // pre-change behaviour.
+      audience: audience === AUDIENCE_INTERNAL ? AUDIENCE_INTERNAL : 'user',
+      // W1-d follow-up (#4141): the RAW structural signal, persisted alongside
+      // the verdict it fed. `audience` collapses it with the obligation state
+      // and loses it; the sweep needs it on its own to decide provenance
+      // framing for the `'user'` records the audience gate deliberately does
+      // not catch (the foreground case). Stamped here because this is the last
+      // point in the pipeline that can still see the transcript.
+      replyToolThrewThisTurn: capture.replyToolThrewThisTurn === true,
     }
     const tmpPath = join(outboxDir, `.${capture.turnNonce}.${process.pid}.tmp`)
     writeFileSync(tmpPath, JSON.stringify(record), 'utf8')
@@ -267,11 +345,16 @@ function main() {
             `deferring to single-writer election (#3510)\n`,
         )
       } else {
-        writeOutboxRecord(stateDir, capture)
+        const audience = classifyCaptureAudience(stateDir, capture)
+        writeOutboxRecord(stateDir, capture, audience)
         process.stderr.write(
           `[silent-end-interrupt] captured undelivered final answer to outbox ` +
             `(nonce=${capture.turnNonce} source=${capture.source} chars=${capture.text.length} ` +
-            `replyAlreadyDeliveredThisTurn=false) — sweep will deliver; allowing stop\n`,
+            `replyAlreadyDeliveredThisTurn=false audience=${audience} ` +
+            `replyToolThrewThisTurn=${capture.replyToolThrewThisTurn === true}) — ` +
+            `${audience === AUDIENCE_INTERNAL
+              ? 'internal prose: journaled for inspection, sweep will NOT deliver'
+              : 'sweep will deliver'}; allowing stop\n`,
         )
         process.exit(0)
       }

package/telegram-plugin/hooks/silent-end-scan.mjs

@@ -248,9 +248,18 @@ function buildTurnId(chatId, threadId, messageId) {
  *   reply tool (Option A transcript-prose bridge). Only populated when it
  *   clears the substance floor, so the gateway never re-delivers a short
  *   trailing pleasantry. Omitted entirely otherwise.
+ * @param {boolean} [replyToolThrewThisTurn] W1-d follow-up (#4141): one of this
+ *   turn's reply-tool calls came back `is_error: true`. Carried on the BLOCK
+ *   result so the single-writer election can persist it onto the silent-end
+ *   state file — the captured-prose bridge (the machine that actually delivers
+ *   on the ELECTED path, where no outbox record is ever written) has no other
+ *   way to learn it. A raw SIGNAL, never a verdict: downstream it only ever
+ *   adds a provenance banner. Omitted rather than `false` when absent, so a
+ *   spread of a prior state file cannot be read as positive evidence.
  */
-function buildBlockResult(envelope, reason, pendingText, hasTrailingProse) {
+function buildBlockResult(envelope, reason, pendingText, hasTrailingProse, replyToolThrewThisTurn) {
   const block = { decided: 'block', reason }
+  if (replyToolThrewThisTurn === true) block.replyToolThrewThisTurn = true
   // Single-writer election input (#duplicate-message fix): does ANY
   // non-empty, non-silent trailing text block exist after the last
   // delivery event? The zero-reply election allows only when this is
@@ -381,6 +390,15 @@ export function scanTurnForFinalReply(jsonl) {
   //    whether emitted as plain text or as a reply-tool payload) or
   //    plain undelivered text.
   const blocks = []
+  // W1-d follow-up (#4141): the same reply-throw signal `scanForOutboxCapture`
+  // already derives, computed here too because the ELECTED path never reaches
+  // that scanner's capture branch (a thrown-but-qualifying reply sets
+  // `replyAlreadyDeliveredThisTurn`, so the hook defers to the election and
+  // writes NO outbox record). Collected as two id sets whose intersection is
+  // the signal. Read-only: nothing below branches on it, so no verdict of this
+  // scanner changes.
+  const replyToolUseIds = new Set()
+  const erroredToolUseIds = new Set()
   for (let i = startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
     if (!line || line[0] !== '{') continue
@@ -390,6 +408,20 @@ export function scanTurnForFinalReply(jsonl) {
     // be in a separate transcript file, but `isSidechain:true` is the
     // documented marker if they leak).
     if (obj?.isSidechain === true) continue
+    if (obj?.type === 'user') {
+      // Tool RESULT lines: `user`-type, content array carrying
+      // `{type:'tool_result', tool_use_id, is_error}`. Same shape read by
+      // `scanForOutboxCapture` (#3865).
+      const rc = obj?.message?.content
+      if (!Array.isArray(rc)) continue
+      for (const r of rc) {
+        if (r?.type !== 'tool_result') continue
+        if (r?.is_error !== true) continue
+        if (typeof r.tool_use_id !== 'string') continue
+        erroredToolUseIds.add(r.tool_use_id)
+      }
+      continue
+    }
     if (obj?.type !== 'assistant') continue
     const content = obj?.message?.content
     if (!Array.isArray(content)) continue
@@ -449,6 +481,9 @@ export function scanTurnForFinalReply(jsonl) {
         }
         continue
       }
+      // #4141: EVERY reply-tool call's id, qualifying or not — an interim ack
+      // that threw is still a reply-tool throw.
+      if (typeof c.id === 'string') replyToolUseIds.add(c.id)
       const input = c.input ?? {}
       const text = String(input.text ?? '')
       // Silent-marker carve-out: the operator explicitly signaled
@@ -555,6 +590,10 @@ export function scanTurnForFinalReply(jsonl) {
   // delivers the joined prose instead of dropping. A pure narration run still
   // yields `undefined` (the #3228 Finding 2 guard, now structural).
   const zeroReplyPendingText = backstopText
+  // #4141 — one of this turn's reply-tool calls errored. Derived here, consumed
+  // only by `buildBlockResult` below (and thence the elected state file); it
+  // gates nothing in this scanner.
+  const replyToolThrewThisTurn = [...replyToolUseIds].some((id) => erroredToolUseIds.has(id))
 
   if (lastAllowBlockIdx === -1) {
     // No qualifying delivery/silence event anywhere in the turn.
@@ -567,7 +606,9 @@ export function scanTurnForFinalReply(jsonl) {
     if (envelope.source === 'cron') {
       return { decided: 'allow', reason: 'cron-source' }
     }
-    return buildBlockResult(envelope, 'no-final-reply', zeroReplyPendingText, hasTrailingProse)
+    return buildBlockResult(
+      envelope, 'no-final-reply', zeroReplyPendingText, hasTrailingProse, replyToolThrewThisTurn,
+    )
   }
 
   if (sawUndeliveredTextAfterAllow) {
@@ -576,7 +617,9 @@ export function scanTurnForFinalReply(jsonl) {
     // sent through a delivery tool. This is the "at least once" bug:
     // an early ack (or any qualifying reply) must not amnesty
     // everything written afterward.
-    return buildBlockResult(envelope, 'trailing-text-after-reply', pendingText, hasTrailingProse)
+    return buildBlockResult(
+      envelope, 'trailing-text-after-reply', pendingText, hasTrailingProse, replyToolThrewThisTurn,
+    )
   }
 
   return { decided: 'allow', reason: lastAllowReason }
@@ -917,7 +960,7 @@ function resolveSessionOriginChat(lines) {
  *
  * @param {string} jsonl
  * @param {number} [now]
- * @returns {{ capture: false, reason: string } | { capture: true, text: string, turnNonce: string, chatId: string|null, threadId: number|null, source: string, anchorContent: string, replyAlreadyDeliveredThisTurn: boolean, deliveredReplySha256: string|null }}
+ * @returns {{ capture: false, reason: string } | { capture: true, text: string, turnNonce: string, chatId: string|null, threadId: number|null, source: string, anchorContent: string, replyAlreadyDeliveredThisTurn: boolean, deliveredReplySha256: string|null, replyToolThrewThisTurn: boolean }}
  */
 export function scanForOutboxCapture(jsonl, now = Date.now()) {
   const lines = jsonl.split('\n')
@@ -925,12 +968,34 @@ export function scanForOutboxCapture(jsonl, now = Date.now()) {
   const { envelope } = anchor
 
   const blocks = []
+  // W1-d (#3865): ids of reply-tool `tool_use` blocks seen this turn, and the
+  // ids whose `tool_result` came back `is_error: true`. Their intersection is
+  // the "did the reply tool throw this turn" signal.
+  const replyToolUseIds = new Set()
+  const erroredToolUseIds = new Set()
   for (let i = anchor.startIdx + 1; i < lines.length; i++) {
     const line = lines[i]
     if (!line || line[0] !== '{') continue
     let obj
     try { obj = JSON.parse(line) } catch { continue }
     if (obj?.isSidechain === true) continue
+    // W1-d (#3865): tool RESULT lines are how a reply-tool THROW becomes
+    // visible. Claude Code writes the result of a `tool_use` as a `user`-type
+    // line whose content array carries `{type:'tool_result', tool_use_id,
+    // is_error}`. Nothing in this scanner read those before, which is exactly
+    // why an errored reply was indistinguishable from a delivered one — the
+    // transcript shape is otherwise identical.
+    if (obj?.type === 'user') {
+      const rc = obj?.message?.content
+      if (!Array.isArray(rc)) continue
+      for (const r of rc) {
+        if (r?.type !== 'tool_result') continue
+        if (r?.is_error !== true) continue
+        if (typeof r.tool_use_id !== 'string') continue
+        erroredToolUseIds.add(r.tool_use_id)
+      }
+      continue
+    }
     if (obj?.type !== 'assistant') continue
     const content = obj?.message?.content
     if (!Array.isArray(content)) continue
@@ -971,6 +1036,12 @@ export function scanForOutboxCapture(jsonl, now = Date.now()) {
         }
         continue
       }
+      // W1-d (#3865): remember EVERY reply-tool call's id, not just the
+      // qualifying-final-answer ones. An interim ack that threw is still a
+      // reply-tool throw, and the #3861 shape (reply raises, agent then writes
+      // trailing working notes) does not require the errored call to have been
+      // a qualifying final answer.
+      if (typeof c.id === 'string') replyToolUseIds.add(c.id)
       const input = c.input ?? {}
       const text = String(input.text ?? '')
       if (SILENT_MARKER_RE.test(text.trim()) || endsWithSilentMarker(text)) {
@@ -1081,5 +1152,10 @@ export function scanForOutboxCapture(jsonl, now = Date.now()) {
     originThreadId: origin.threadId,
     replyAlreadyDeliveredThisTurn,
     deliveredReplySha256,
+    // W1-d (#3865): one of this turn's reply-tool calls came back an error.
+    // Reported as a raw SIGNAL, not a verdict — `decideCaptureAudience` in
+    // `audience-classify.mjs` combines it with the obligation state (which
+    // this pure transcript scanner cannot see) to decide the audience.
+    replyToolThrewThisTurn: [...replyToolUseIds].some((id) => erroredToolUseIds.has(id)),
   }
 }