@cohortapp/agent-sdk 2.18.36 → 2.18.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -98,6 +98,20 @@ import {
98
98
  noticeRejection,
99
99
  fallbackNotice,
100
100
  } from "../../lib/assurance/notice-voice.mjs";
101
+ // WHERE A NOTICE GOES — and the answer is never "to a person". This is the
102
+ // decision the wording iterations kept skipping; `notice-plane.mjs` carries the
103
+ // argument and the table, and the table's default for an unregistered notice is
104
+ // the operator plane, so a new notice kind is silent to people until someone
105
+ // deliberately says otherwise under that header.
106
+ import { noticePlane, mayReachHuman, NOTICE_PLANE } from "../../lib/assurance/notice-plane.mjs";
107
+ // The SHAPE of a machine narrating itself, as ONE shared vocabulary with TWO
108
+ // thresholds. This file asks the inbound question ("is this peer's message a
109
+ // notice?") and needs only the predicate, because it has already established the
110
+ // sender is a seat; `deliver.mjs` asks the outbound one ("may this body leave?")
111
+ // and needs the apparatus subject too, because it does not know who wrote it.
112
+ // Both read the same lists, so a phrase added for one is live for both. The
113
+ // difference in thresholds is argued at `hasStatusPredicate`.
114
+ import { hasStatusPredicate } from "../../lib/comms/machine-status.mjs";
101
115
  import { isRetiredFirstReply, firstReplyShape, REACTIONS, statesNoReplyOwed } from "../../lib/assurance/first-reply.mjs";
102
116
  // The unit of acknowledgement is the CONVERSATION, not the message: four
103
117
  // messages in a row earn ONE first response that was written with all four in
@@ -507,7 +521,13 @@ export function looksLikePeerOutcomeNotice(item) {
507
521
  if (REQUEST_MARKER.test(content)) return false;
508
522
  if (IMPERATIVE_OPENER.test(content)) return false;
509
523
  if (!/\b(i|my|i'?ve|i'?m)\b/i.test(content)) return false;
510
- return /\b(didn'?t (get through|finish|complete)|never came back|ran out of time|outrun its time limit|broke before it finished|was cut off|stopped (trying|retrying)|flagged it|ended (with an error|unexpectedly)|my (machine|end) restarted)\b/i.test(content);
524
+ // ONE VOCABULARY, SHARED WITH THE OUTBOUND REFUSAL. This predicate list used
525
+ // to be a literal here, duplicating the one the outbound screen needs. The two
526
+ // now read `lib/comms/machine-status.mjs`, so the shape this seat REFUSES TO
527
+ // SEND and the shape it REFUSES TO ACK are the same shape by construction —
528
+ // the `narratorPatterns` convention: emitter and recogniser are edited
529
+ // together or not at all. A phrase added for one is live for both.
530
+ return hasStatusPredicate(content);
511
531
  }
512
532
 
513
533
  /**
@@ -596,10 +616,18 @@ export function narratorPatterns() {
596
616
  // rest — if this gate cannot recognise it, a peer's refusal notice arrives
597
617
  // as an ordinary ask, earns an ack and spawns a session behind it, which is
598
618
  // the loop that produced 142 of 188 notices on 2026-09-30.
599
- composeRefusedSend({}, { why: { code: CAUSE, permanent: true } }),
600
- composeRefusedSend({}, { why: { code: CAUSE, permanent: false } }),
601
- composeRefusedSend({}, { why: { code: CAUSE, permanent: true }, finalText: CAUSE }),
602
- composeRefusedSend({}, { why: { code: CAUSE, permanent: false }, finalText: CAUSE }),
619
+ // BOTH CAUSE SHAPES, because the cause clause is now a MAPPED phrase and an
620
+ // unmapped code yields no clause at all. A pattern derived only from the
621
+ // clause-bearing shape has a mandatory `\(…\)` in it and silently stops
622
+ // matching every refusal whose code this tree does not know — which is the
623
+ // half the self-echo gate most needs, since an unknown code is what an older
624
+ // or newer peer emits.
625
+ ...[true, false].flatMap((permanent) =>
626
+ [undefined, CAUSE].flatMap((finalText) =>
627
+ [CAUSE, ""].map((causePhrase) =>
628
+ composeRefusedSend({}, { why: { code: CAUSE, permanent }, finalText, causePhrase })),
629
+ ),
630
+ ),
603
631
  ];
604
632
  // GLOBAL, not first-occurrence. `String.prototype.replace` with a string
605
633
  // pattern substitutes once, so a template carrying the sentinel twice — a
@@ -1247,6 +1275,27 @@ export async function generateFailureNotice(rec, o = {}, opts = {}) {
1247
1275
 
1248
1276
  const run = typeof opts.runImpl === "function" ? opts.runImpl : runAckModel;
1249
1277
  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : NOTICE_GEN_TIMEOUT_MS;
1278
+ // NOBODY READS THIS, SO DO NOT PAY A MODEL TO WRITE IT.
1279
+ //
1280
+ // Every notice kind is operator-plane (`lib/assurance/notice-plane.mjs`), so
1281
+ // the destination of this text is a log line and a journal row — and a model
1282
+ // spawn to make a log line read nicely is a cold `claude --print` per dead
1283
+ // obligation per sweep, bounded at NOTICE_GEN_TIMEOUT_MS, for prose no person
1284
+ // will see. The deterministic sentence is the right artifact for the operator
1285
+ // plane and always was.
1286
+ //
1287
+ // `degraded` is FALSE: nothing is broken, this is the design. The counter
1288
+ // records the real reason so the `notice.generation_failed` rates stay
1289
+ // meaningful rather than being swamped by a path that was never going to run.
1290
+ //
1291
+ // The test seam still overrides, so `notice-emission.test.mjs` can keep
1292
+ // exercising the generator's guards (`claimsSuccess`, `inventsFacts`, the
1293
+ // register) against a stub — those guards remain the defence for any future
1294
+ // caller that is genuinely human-facing.
1295
+ if (typeof opts.runImpl !== "function" && !mayReachHuman(kind)) {
1296
+ counters.bump("notice.generation_skipped", { notice: kind, reason: "operator-plane" });
1297
+ return { text: degradedText(), generated: false, degraded: false, cause, plane: NOTICE_PLANE.OPERATOR };
1298
+ }
1250
1299
  if (typeof opts.runImpl !== "function" && !noticeGenEnabled()) {
1251
1300
  counters.bump("notice.generation_skipped", { notice: kind, reason: "disabled" });
1252
1301
  return { text: degradedText(), generated: false, degraded: true, cause };
@@ -1272,7 +1321,7 @@ export async function generateFailureNotice(rec, o = {}, opts = {}) {
1272
1321
  const verdict = noticeRejection(raw, { source: noticeSource(promptArgs) });
1273
1322
  if (verdict.ok) return { text: verdict.text, generated: true, degraded: false, cause };
1274
1323
  counters.bump("notice.generation_failed", { cause: `unusable:${verdict.reason}`, notice: kind });
1275
- console.warn(`[assurance] ${kind} notice generation produced nothing usable [${verdict.reason}] — sending the plain version (a dead ask is never left unsaid)`);
1324
+ console.warn(`[assurance] ${kind} notice generation produced nothing usable [${verdict.reason}] — falling back to the plain sentence (a dead ask is never left unrecorded)`);
1276
1325
  return { text: degradedText(), generated: false, degraded: true, cause, rejected: verdict.reason };
1277
1326
  } catch (err) {
1278
1327
  const msg = String((err && err.message) || "");
@@ -1280,7 +1329,7 @@ export async function generateFailureNotice(rec, o = {}, opts = {}) {
1280
1329
  : /spawn error|ENOENT|EACCES/i.test(msg) ? "spawn_failed"
1281
1330
  : "error";
1282
1331
  counters.bump("notice.generation_failed", { cause: why, notice: kind });
1283
- console.warn(`[assurance] ${kind} notice generation failed (${msg}) — sending the plain version [cause:${why}]`);
1332
+ console.warn(`[assurance] ${kind} notice generation failed (${msg}) — falling back to the plain sentence [cause:${why}]`);
1284
1333
  return { text: degradedText(), generated: false, degraded: true, cause };
1285
1334
  }
1286
1335
  }
@@ -1314,6 +1363,69 @@ export function composeSilentSuccess(rec, o = {}) {
1314
1363
  return `${head} I don't have a clean result to show you, though. Want me to run it again?`;
1315
1364
  }
1316
1365
 
1366
+ /**
1367
+ * A machine send-block code → the one clause a PERSON can do something with.
1368
+ *
1369
+ * ── WHY A TABLE AND NOT THE RAW REASON ──────────────────────────────────────
1370
+ *
1371
+ * The previous version interpolated `why.reason` — the no-send receipt's own
1372
+ * `frame.error` string — straight into a body a human reads. Two things are
1373
+ * wrong with that, and the second one only became visible once this branch
1374
+ * landed:
1375
+ *
1376
+ * 1. It is machine noise. "FORBIDDEN_SCOPE: blocked by send-gate" is the
1377
+ * exact register this subsystem keeps being told to stop writing in.
1378
+ * 2. THE GATES' OWN REFUSAL MESSAGES ARE NOW AMONG THOSE REASONS. `deliver`
1379
+ * records `code:"FORBIDDEN_SCOPE", error:'machine-status kind "failure"
1380
+ * may not be delivered to a conversation — route it to the operator
1381
+ * plane'`, and `noteNoSend` writes that verbatim into the receipt this
1382
+ * composer reads. So the fix for broken machine messages could compose a
1383
+ * broken machine message that quoted the gate which stopped it.
1384
+ *
1385
+ * The raw string is not lost and an operator never has to guess: it is in the
1386
+ * no-send receipt, in the `needs-attention` row and in the notice journal, which
1387
+ * is where it is read. The person gets what it means for them.
1388
+ *
1389
+ * THE DEFAULT IS NO CLAUSE AT ALL, not a fallback to the raw text. That is the
1390
+ * structural half: an unmapped or newly-invented code cannot reach a person as
1391
+ * machine prose, because this function has no path that returns `why.reason`.
1392
+ * Add a row here when a new code starts appearing in receipts.
1393
+ *
1394
+ * @type {Readonly<Record<string,string>>}
1395
+ */
1396
+ export const SEND_BLOCK_PHRASES = Object.freeze({
1397
+ FORBIDDEN_SCOPE: "I don't have permission to post there",
1398
+ HOOK_BLOCKED: "the wording got stopped by our own outbound rules",
1399
+ BANNED_PHRASE: "the wording got stopped by our own outbound rules",
1400
+ FORBIDDEN: "I don't have permission to post there",
1401
+ 403: "I don't have permission to post there",
1402
+ NOT_A_MEMBER: "I'm not in that conversation",
1403
+ CHANNEL_NOT_FOUND: "that conversation wasn't reachable from here",
1404
+ 404: "that conversation wasn't reachable from here",
1405
+ UNAUTHORIZED: "my access to that workspace wasn't accepted",
1406
+ 401: "my access to that workspace wasn't accepted",
1407
+ RATE_LIMITED: "the channel was rate-limiting me",
1408
+ 429: "the channel was rate-limiting me",
1409
+ NETWORK: "the network dropped on the way out",
1410
+ ETIMEDOUT: "the network dropped on the way out",
1411
+ ECONNRESET: "the network dropped on the way out",
1412
+ });
1413
+
1414
+ /**
1415
+ * The human-facing cause clause for a blocked send, or "" when there isn't one.
1416
+ *
1417
+ * @param {object} why a `noSendFor` verdict (`{code, reason, permanent, …}`)
1418
+ * @returns {string} a phrase, never a machine string, possibly empty
1419
+ */
1420
+ export function humanSendBlockPhrase(why = {}) {
1421
+ const code = why && why.code != null ? String(why.code).trim() : "";
1422
+ if (!code) return "";
1423
+ const key = code.toUpperCase();
1424
+ if (Object.prototype.hasOwnProperty.call(SEND_BLOCK_PHRASES, key)) return SEND_BLOCK_PHRASES[key];
1425
+ if (Object.prototype.hasOwnProperty.call(SEND_BLOCK_PHRASES, code)) return SEND_BLOCK_PHRASES[code];
1426
+ return "";
1427
+ }
1428
+
1317
1429
  /**
1318
1430
  * The case `composeSilentSuccess` was apologising for by mistake: a send that
1319
1431
  * WAS attempted and was STOPPED, with a recorded cause.
@@ -1347,11 +1459,14 @@ export function composeSilentSuccess(rec, o = {}) {
1347
1459
  */
1348
1460
  export function composeRefusedSend(rec, o = {}) {
1349
1461
  const why = o.why || {};
1350
- const code = why.code ? String(why.code).trim() : "";
1351
- const reason = why.reason ? String(why.reason).trim() : "";
1352
- // The code alone is machine noise to a human, and the reason alone loses the
1353
- // handle an operator greps for. Both when both exist, whichever when one does.
1354
- const cause = code && reason && !reason.startsWith(code) ? `${code}: ${reason}` : reason || code;
1462
+ // `o.causePhrase` is a PATTERN SEAM, not an escape hatch for a caller. The
1463
+ // cause slot is a MAPPED phrase now, and `narratorPatterns` has to derive a
1464
+ // template carrying its regex sentinel in that slot — otherwise the self-echo
1465
+ // gate stops recognising this seat's own refusal notices, a peer's refusal
1466
+ // arrives as an ordinary ask, and the 142-of-188 loop restarts. Nothing on the
1467
+ // delivery path passes it; `assurance-no-send-gate.test.mjs` pins that no raw
1468
+ // receipt string can reach the body through `why`.
1469
+ const cause = typeof o.causePhrase === "string" ? o.causePhrase : humanSendBlockPhrase(why);
1355
1470
  const head = `Couldn't get this out to you — the send was blocked${cause ? ` (${cause})` : ""}.`;
1356
1471
  // Never promise a retry this path does not perform. The silent-success branch
1357
1472
  // has no retry loop — that lives in the failure branch — so a permanent cause
@@ -1582,7 +1697,13 @@ export const NOTICE = Object.freeze({
1582
1697
  FAILURE_RETRYING: "failure:retrying",
1583
1698
  FAILURE_FINAL: "failure:final",
1584
1699
  INTERRUPTED: "interrupted",
1700
+ // The two answer-or-nothing ids. Both of these have a HUMAN shape (the one
1701
+ // that carries the session's result text, delivered as a `reply`) and an
1702
+ // OPERATOR shape (the same composer with no result text, which is a template
1703
+ // about this machine's own run). Only the operator shape reaches here, and
1704
+ // `notice-plane.NOTICE_PLANES` declares it operator like all the rest.
1585
1705
  SILENT_SUCCESS: "silent-success",
1706
+ SEND_REFUSED: "send-refused",
1586
1707
  });
1587
1708
 
1588
1709
  /**
@@ -1650,9 +1771,129 @@ export function markNoticeSaid(rec, notice, now) {
1650
1771
  * @param {function} [o.roomNoticeImpl] test seam for the room-scoped dedupe
1651
1772
  * @returns {Promise<{sent:boolean, reason:string}>}
1652
1773
  */
1774
+ /**
1775
+ * THE OPERATOR SINK — where a machine's status about itself actually goes.
1776
+ *
1777
+ * This replaces the send, it does not accompany it. The three things an operator
1778
+ * needs are all written here or beside it:
1779
+ *
1780
+ * THE ROW `escalate` writes `needs-attention/<key>.json` on every one of
1781
+ * these failures, carrying the key, the sender, the cause, the
1782
+ * trace id and the session id — strictly more than the DM ever
1783
+ * said. That is unchanged and is written by the caller.
1784
+ * THE JOURNAL this function appends one line per (obligation, notice) to
1785
+ * `state/obligations/notice-journal.jsonl`, so the sequence of
1786
+ * what a seat decided about a dead ask is readable in order
1787
+ * rather than reconstructed from a row that only holds the last
1788
+ * state. Append-only, one line, no prose a model wrote.
1789
+ * THE COUNTER `assurance.notice_to_operator`, broken out by notice and
1790
+ * reason, so the volume is a number on a health surface instead
1791
+ * of a thing a person notices in their DMs.
1792
+ *
1793
+ * ONCE-ONLY, DURABLY, AND IT IS THE LATCH THAT ALREADY EXISTED.
1794
+ * `noticeAlreadySaid` / `markNoticeSaid` are keyed on
1795
+ * (channel, obligationKey, notice) and INHERITED across a retry that reopens the
1796
+ * same key (`openAndAcknowledge`), so one dead ask yields one journal line
1797
+ * however many sweeps, retries and daemon restarts touch it. Checking it here
1798
+ * rather than only on the human path is what makes "the same thing twice" a
1799
+ * property of the sink too — the owner received the same sentence twice eleven
1800
+ * minutes apart, and a sink that appends twice would have reproduced that defect
1801
+ * in the log it replaced the DM with.
1802
+ *
1803
+ * THE TEXT IS KEPT, deliberately. It is the deterministic sentence (no model is
1804
+ * spawned for an operator line — see `generateFailureNotice`), and it is the
1805
+ * most readable one-line statement of what happened that this code can produce.
1806
+ * An operator reading the journal wants it. A person in a conversation does not,
1807
+ * which is the entire distinction this module draws.
1808
+ *
1809
+ * Never throws: a sink that can fail the sweep is worse than a sink that loses a
1810
+ * line, and the escalation row is written independently by the caller.
1811
+ *
1812
+ * @param {object} o {rec, notice, text, now, reason}
1813
+ * @returns {{sent:false, reason:string, plane:string, journalled:boolean}}
1814
+ */
1815
+ function recordOperatorNotice(o = {}) {
1816
+ const { rec, notice, text, now } = o;
1817
+ const already = noticeAlreadySaid(rec, notice);
1818
+ if (!already) {
1819
+ markNoticeSaid(rec, notice, now);
1820
+ // THE SINK PERSISTS ITS OWN LATCH. `markNoticeSaid` mutates `rec` and
1821
+ // documents that the caller writes it — which was true of the failure branch
1822
+ // (`writeRecord` immediately after `sayOutcomeNotice`) and NOT of the paths
1823
+ // that go straight to `closeObligation`, because `closeObligation` re-reads
1824
+ // the record from disk and the in-memory mark is lost. The once-only property
1825
+ // is this function's guarantee, so this function makes it durable rather than
1826
+ // depending on what each caller happens to do next.
1827
+ try { writeRecord(rec); } catch { /* best-effort: a lost latch is one extra row, not a lost debt */ }
1828
+ }
1829
+ counters.bump("assurance.notice_to_operator", {
1830
+ notice,
1831
+ reason: o.reason || "declared-operator",
1832
+ repeat: already ? "suppressed" : "first",
1833
+ });
1834
+ if (already) {
1835
+ return { sent: false, reason: "operator-plane-already-recorded", plane: NOTICE_PLANE.OPERATOR, journalled: false };
1836
+ }
1837
+ let journalled = false;
1838
+ try {
1839
+ const line = JSON.stringify({
1840
+ at: new Date(Number.isFinite(now) ? now : Date.now()).toISOString(),
1841
+ notice,
1842
+ key: rec && rec.key,
1843
+ service: rec && rec.service,
1844
+ channel: rec && rec.channel,
1845
+ sender: (rec && rec.sender) || null,
1846
+ cause: (rec && rec.lastError) || null,
1847
+ attempts: (rec && rec.attempts) || 0,
1848
+ sessionId: (rec && rec.sessionId) || null,
1849
+ traceId: (rec && rec.traceId) || null,
1850
+ // The plane, on every row, so a reader of the journal never has to wonder
1851
+ // whether this one also went to a person. None of them do.
1852
+ plane: NOTICE_PLANE.OPERATOR,
1853
+ requesterTold: false,
1854
+ statusLine: typeof text === "string" ? text.slice(0, 400) : null,
1855
+ });
1856
+ appendFileSync(join(obligationDir(), "notice-journal.jsonl"), `${line}\n`);
1857
+ journalled = true;
1858
+ } catch (err) {
1859
+ console.error(`[assurance] could not journal ${notice} for ${rec && rec.key}: ${err && err.message}`);
1860
+ }
1861
+ console.log(`[assurance] ${notice} for ${rec && rec.key} → operator plane (${o.reason || "declared-operator"}); no conversation was told. Cause: ${(rec && rec.lastError) || "unknown"}`);
1862
+ return { sent: false, reason: "operator-plane", plane: NOTICE_PLANE.OPERATOR, journalled };
1863
+ }
1864
+
1653
1865
  async function sayOutcomeNotice(o) {
1654
1866
  const { rec, notice, text, item, kind, now } = o;
1655
1867
 
1868
+ // ── THE PLANE DECISION, BEFORE EVERYTHING ELSE ───────────────────────────
1869
+ //
1870
+ // This is the question this subsystem never asked, and the reason the owner
1871
+ // received a new variant after each of three fixes. Everything below this
1872
+ // point — two dedupes, a document-surface test, a room claim — is about HOW
1873
+ // MANY copies of a message a person gets and WHAT WORDS it wears. The answer
1874
+ // is that they get none: status about this machine's own apparatus is not a
1875
+ // message to a person. The argument, the measured costs, and the narrow case
1876
+ // that does NOT survive are in `lib/assurance/notice-plane.mjs`. Read that
1877
+ // before changing this line.
1878
+ //
1879
+ // WHY HERE AND NOT ONLY AT THE TRANSPORT. `deliver()` refuses these kinds too,
1880
+ // and that is the backstop for a caller nobody has written yet. But a refusal
1881
+ // at the transport produces the DEBRIS of an attempted send: a no-send
1882
+ // receipt, a `{sent:false}` the caller reads as "the room heard nothing", and
1883
+ // an escalation row whose `requesterWasTold:false` is right by accident.
1884
+ // Deciding here writes the operator plane a deliberate record instead.
1885
+ //
1886
+ // WHY IT IS ABOVE THE DOCUMENT TEST. The document test is a SURFACE test, and
1887
+ // it was the last iteration of the old axis — withhold on one more surface. It
1888
+ // is kept below rather than deleted because it answers a different question
1889
+ // and would be the only guard still standing if anyone ever registers a
1890
+ // human-facing notice in `NOTICE_PLANES`. For every notice that exists today,
1891
+ // this block returns first.
1892
+ const plane = noticePlane(notice);
1893
+ if (!plane.human) {
1894
+ return recordOperatorNotice({ rec, notice, text, now, reason: plane.reason });
1895
+ }
1896
+
1656
1897
  // ── NO OUTCOME NOTICE REACHES A DOCUMENT, AT THE CHOKEPOINT ───────────────
1657
1898
  //
1658
1899
  // 2.18.30 put this test in `settleSession`, which covered the failed,
@@ -2157,7 +2398,37 @@ export async function settleSession(a = {}) {
2157
2398
  // shared room when nobody asked, and this is not narration — it is the
2158
2399
  // one line that says a message this seat owed was stopped, plus its cause.
2159
2400
  // Withholding it is how a blocked send lane stays invisible for days.
2401
+ //
2402
+ // ── BUT ONLY WHEN IT CARRIES THE ANSWER ────────────────────────────────
2403
+ //
2404
+ // That paragraph is true of the FAULT, not of the sentence. The fault has
2405
+ // to reach somebody; nothing says that somebody is the person in the
2406
+ // conversation. With the session's result text this message hands them the
2407
+ // work AND explains why it arrived late — a reply. Without it, all that is
2408
+ // left is "Couldn't get this out to you — the send was blocked (…). That
2409
+ // won't clear on its own": a template about this machine's own plumbing,
2410
+ // nothing the reader can do, and unactionable by the very reasoning in
2411
+ // `notice-plane.mjs` that silenced the failure notices. So the split is by
2412
+ // WHAT THE BODY CARRIES, not by which composer produced it — and the
2413
+ // operator sink gets strictly more than the sentence did, including the
2414
+ // raw code that no longer goes to a person.
2160
2415
  const finalText = safeResultText(a.stdout);
2416
+ if (!finalText) {
2417
+ const res = await sayOutcomeNotice({
2418
+ rec, notice: NOTICE.SEND_REFUSED, text: composeRefusedSend(rec, { why }),
2419
+ item, kind: "notice", idempotencySuffix: `refused-${rec.attempts || 0}`, now, send,
2420
+ roomNoticeImpl: a.deps && a.deps.roomNoticeImpl,
2421
+ });
2422
+ rec.lastError = `send refused: ${why.code || "no code"}${why.reason ? ` — ${String(why.reason).slice(0, 200)}` : ""}`;
2423
+ escalate(rec, { failure: { label: rec.lastError }, now, told: false });
2424
+ closeObligation(a.key, {
2425
+ outcome: "undeliverable",
2426
+ now,
2427
+ note: `send refused (${why.code || "no code"}${why.surface ? ` on ${why.surface}` : ""}) and the session produced no result text; recorded in the operator plane, no conversation told`,
2428
+ });
2429
+ counters.bump("assurance.no_send_refused", { service: rec.service, code: why.code || "none", plane: "operator" });
2430
+ return { spoke: false, text: null, verdict: "send-refused", willRetry: false, noSend: why, plane: res.plane };
2431
+ }
2161
2432
  const text = composeRefusedSend(rec, { why, finalText });
2162
2433
  const res = await send(item, text, {
2163
2434
  kind: "reply",
@@ -2170,7 +2441,7 @@ export async function settleSession(a = {}) {
2170
2441
  now,
2171
2442
  note: `send refused (${why.code || "no code"}${why.surface ? ` on ${why.surface}` : ""}); ${res && res.sent ? "cause reported to the room" : `cause also undeliverable: ${res && res.error}`}`,
2172
2443
  });
2173
- counters.bump("assurance.no_send_refused", { service: rec.service, code: why.code || "none" });
2444
+ counters.bump("assurance.no_send_refused", { service: rec.service, code: why.code || "none", plane: "human" });
2174
2445
  return { spoke: !!(res && res.sent), text, verdict: "send-refused", willRetry: false, noSend: why };
2175
2446
  }
2176
2447
 
@@ -2225,6 +2496,49 @@ export async function settleSession(a = {}) {
2225
2496
  return { spoke: false, text: null, verdict: "silent-success", willRetry: false };
2226
2497
  }
2227
2498
 
2499
+ // ── NO RESULT TEXT IS NOT AN ANSWER, SO IT IS NOT A REPLY ───────────────
2500
+ //
2501
+ // `composeSilentSuccess` has two shapes and only one of them is a reply.
2502
+ // WITH the session's result text it hands the asker the work their session
2503
+ // produced but never sent — that is the entire reason this rescue exists,
2504
+ // and it must go out. WITHOUT it, the whole message is:
2505
+ //
2506
+ // Finished this but didn't get a reply out to you — my fault. I don't
2507
+ // have a clean result to show you, though. Want me to run it again?
2508
+ //
2509
+ // which is "my session finished, you got nothing, shall I try again" — a
2510
+ // template about this machine's own run with no work product in it, i.e.
2511
+ // precisely the category the owner complained about twice. This repo's own
2512
+ // canonical recogniser agrees: `first-reply.isAgentStatusNotice` returns
2513
+ // true for it, and `STATUS_NOTICE_PATTERNS` lists its head as a frozen
2514
+ // literal of the status-notice family.
2515
+ //
2516
+ // WHY IT SURVIVED THE FIRST PASS OF THIS FIX, which is worth recording
2517
+ // because it is the same shape as every earlier miss: it is delivered with
2518
+ // `kind:"reply"`, so the origin gate (keyed on `kind`) never sees it, and it
2519
+ // names no apparatus noun, so the shape gate does not either. Both gates are
2520
+ // about machine STATUS and this is machine status wearing a reply's kind.
2521
+ // The first pass then PINNED it as a reply that must go out, on the reading
2522
+ // that `composeSilentSuccess` "carries the answer" — true of one of its two
2523
+ // shapes. The split is by what the body carries, never by which function
2524
+ // composed it.
2525
+ if (!finalText) {
2526
+ const res = await sayOutcomeNotice({
2527
+ rec, notice: NOTICE.SILENT_SUCCESS, text: composeSilentSuccess(rec, {}),
2528
+ item, kind: "notice", idempotencySuffix: `rescue-${rec.attempts || 0}`, now, send,
2529
+ roomNoticeImpl: a.deps && a.deps.roomNoticeImpl,
2530
+ });
2531
+ rec.lastError = rec.lastError || "session exited 0, sent nothing, produced no result text";
2532
+ escalate(rec, { failure: { label: "session exited 0 with no result text and nothing sent" }, now, told: false });
2533
+ closeObligation(a.key, {
2534
+ outcome: "undeliverable",
2535
+ now,
2536
+ note: "session exited 0 without speaking and produced no result text; recorded in the operator plane, no conversation told",
2537
+ });
2538
+ counters.bump("assurance.silent_success_to_operator", { service: rec.service });
2539
+ return { spoke: false, text: null, verdict: "silent-success", willRetry: false, plane: res.plane };
2540
+ }
2541
+
2228
2542
  const text = composeSilentSuccess(rec, { finalText });
2229
2543
  const res = await send(item, text, {
2230
2544
  kind: "reply",
@@ -2971,9 +3285,63 @@ async function _sweepObligations(a = {}) {
2971
3285
  }
2972
3286
 
2973
3287
  pruneObligations({ now });
3288
+ pruneNoticeJournal({ now });
2974
3289
  return stats;
2975
3290
  }
2976
3291
 
3292
+ /**
3293
+ * Trim the operator notice journal to the retention window.
3294
+ *
3295
+ * WHY THIS EXISTS AND WHY IT IS A REWRITE RATHER THAN A DELETE. The journal
3296
+ * replaced a message, so it had better not have the defect the message had: it
3297
+ * is append-only, one line per dead ask, deliberately NOT coalesced (an operator
3298
+ * who sees one row of twenty has been told nineteen lies by omission). That
3299
+ * makes it the only file in this subsystem that grows without bound, on every
3300
+ * seat, forever — and `pruneReceipts` and `pruneObligations` both exist because
3301
+ * an untrimmed log is the next thing someone deletes wholesale. A log nobody
3302
+ * reads and nobody trims gets truncated by a stranger.
3303
+ *
3304
+ * Retention is the OBLIGATION window (`CLOSED_RETENTION_MS`), not the receipts'
3305
+ * seven days: a journal line is about a debt, and once the debt itself has left
3306
+ * the ledger the line has nothing to join to.
3307
+ *
3308
+ * Rewrites in place, atomically, and never throws. A journal that can fail the
3309
+ * sweep is worse than a journal that keeps a few stale lines.
3310
+ *
3311
+ * @param {object} [o] `{now}`
3312
+ * @returns {number} lines dropped
3313
+ */
3314
+ export function pruneNoticeJournal(o = {}) {
3315
+ const now = Number.isFinite(o.now) ? o.now : Date.now();
3316
+ const p = join(obligationDir(), "notice-journal.jsonl");
3317
+ let raw;
3318
+ try { raw = readFileSync(p, "utf-8"); }
3319
+ catch { return 0; } // absent is the normal case on a seat that has had no failures
3320
+ const lines = raw.split("\n").filter((l) => l.trim());
3321
+ const keep = [];
3322
+ let dropped = 0;
3323
+ for (const line of lines) {
3324
+ let at = NaN;
3325
+ try { at = Date.parse(JSON.parse(line).at); } catch { at = NaN; }
3326
+ // A line whose stamp cannot be read is dropped, not kept forever: it is a
3327
+ // corrupt row in a file whose only purpose is chronology.
3328
+ if (!Number.isFinite(at)) { dropped++; continue; }
3329
+ if (now - at >= CLOSED_RETENTION_MS) { dropped++; continue; }
3330
+ keep.push(line);
3331
+ }
3332
+ if (!dropped) return 0;
3333
+ try {
3334
+ if (!keep.length) { unlinkSync(p); return dropped; }
3335
+ const tmp = `${p}.tmp`;
3336
+ writeFileSync(tmp, `${keep.join("\n")}\n`);
3337
+ renameSync(tmp, p);
3338
+ } catch (err) {
3339
+ console.error(`[assurance] could not prune the notice journal: ${err && err.message}`);
3340
+ return 0;
3341
+ }
3342
+ return dropped;
3343
+ }
3344
+
2977
3345
  /** Delete discharged debts past retention. Open debts are NEVER pruned — an
2978
3346
  * obligation may only leave the ledger by being discharged. */
2979
3347
  export function pruneObligations(o = {}) {
@@ -2995,16 +3363,21 @@ export function pruneObligations(o = {}) {
2995
3363
  return removed;
2996
3364
  }
2997
3365
 
2998
- /** Test seam: wipe the ledger — obligations, escalations AND the room budget.
3366
+ /** Test seam: wipe the ledger — obligations, escalations, the room budget AND
3367
+ * the operator notice journal.
2999
3368
  * The room budget lives in the same directory and is part of the same state:
3000
3369
  * a reset that leaves it behind makes the next test's first interim depend on
3001
- * which tests ran before it. */
3370
+ * which tests ran before it. The notice journal is append-only and keyed by
3371
+ * obligation, and every test in a file typically settles the SAME item, so a
3372
+ * reset that leaves it behind makes "exactly one row" depend on which tests ran
3373
+ * first — the same hazard, in the file that replaced the message. */
3002
3374
  export function _resetObligations() {
3003
3375
  _sweepInFlight = false; // a test that threw mid-sweep must not disable the next one
3004
3376
  for (const rec of listObligations()) {
3005
3377
  try { unlinkSync(pathFor(rec.key)); } catch { /* */ }
3006
3378
  }
3007
3379
  try { unlinkSync(roomBudgetPath(AGENT_REPO_DIR)); } catch { /* absent is the normal case */ }
3380
+ try { unlinkSync(join(obligationDir(), "notice-journal.jsonl")); } catch { /* absent is the normal case */ }
3008
3381
  try {
3009
3382
  const dir = join(obligationDir(), "needs-attention");
3010
3383
  for (const f of readdirSync(dir)) { try { unlinkSync(join(dir, f)); } catch { /* */ } }
@@ -3012,6 +3385,7 @@ export function _resetObligations() {
3012
3385
  }
3013
3386
 
3014
3387
  export default {
3388
+ pruneNoticeJournal,
3015
3389
  shouldAcknowledge,
3016
3390
  senderLooksLikeAgentSeat,
3017
3391
  looksLikePeerAckShape,
@@ -3025,6 +3399,8 @@ export default {
3025
3399
  _buildAckUserPromptForTest: buildAckUserPrompt,
3026
3400
  composeSilentSuccess,
3027
3401
  composeRefusedSend,
3402
+ SEND_BLOCK_PHRASES,
3403
+ humanSendBlockPhrase,
3028
3404
  composeInterrupted,
3029
3405
  looksLikePeerOutcomeNotice,
3030
3406
  classifyFailure,