[nissa-seru]

A turn's [delivered] receipt now names what kept its plain speech private, where it listed every possible cause. With one cause it names that one: 1 plain-speech segment(s) kept private (skip_reply), or (>>>skip_reply), (a drafts call) or (a private think). With two or more it gives each with its count, in that order: 2 plain-speech segment(s) kept private (1 by skip_reply, 1 by a private think).

@antra-tess, we're asking you to review this before it's merged, since it changes what an agent reads in its turn's receipt.

Closes #317.

Problem

At a64cfc010f, the receipt counts the plain-speech segments kept private in one number, and gives all three possible causes for it: ${kept} plain-speech segment(s) kept private (skip_reply, a drafts call or a private think) (src/framework.ts:21092). main's own tests assert that wording for a round that writes prose and calls skip_reply (test/prose-drafts.test.ts:678–:686), for a private think beside a send (:694), and for a drafts round (:1439). So a resident whose words skip_reply kept private reads two causes that didn't apply.

#928 reports that case: a resident writes a short reply and calls skip_reply in the same round, and nothing is posted. Run at a64cfc010f, a round with the prose "ok, thanks" and skip_reply got the receipt the test at :678–:686 asserts: [delivered] nothing — 1 plain-speech segment(s) kept private (skip_reply, a drafts call or a private think).

Changes

Line numbers are this head's.

• The count by cause. TurnRouting.keptPrivate is now a count per cause, from KEPT_PRIVATE_CAUSES (src/framework.ts:1541), whose order is the receipt's.
  • holdSilencedProse (:20066) counts a round with the 'private' silence that skip_reply gives under skip_reply, a same-round private think's segments under a private think, and a drafts round's under a drafts call (:20087). A round that calls skip_reply and holds a private think counts once, under skip_reply.
  • Hybrid prose held after a >>>skip_reply line counts under >>>skip_reply, in routeSilencedHybrid (:20192) and deliverHybridEnvelope (:22769). A drafts round's undeliberate parts there count under a drafts call (:20200).
• The receipt (:21102–:21105) names the one cause, or each cause with its count.
• The receipt's other line stays as main has it. N plain-speech segment(s) suppressed (:21109) names no cause. Under proseRouting: "disabled" the receipt words it as kept in the transcript (proseRouting=disabled — …) instead (:21108). Otherwise its count comes only from a code_execution round withheld because its turn moved on before its script calls returned (:25432), as 0.24.0's changelog entry says (CHANGELOG.md:4612–:4616). Not verified below says what we know of a receipt that shows it.
• Doc comment. The one on TurnRouting.keptPrivate goes.
• Changelog. changelog.d/317-receipt-names-why.changed.md.

What counts as one segment is unchanged. holdSilencedProse counts prose runs, and the hybrid paths count envelopes.

Open pull requests

By git merge-tree at 22:15 UTC on October 30, this branch merges cleanly into main at a64cfc010f. Of the open pull requests that merge cleanly into a64cfc010f, four conflict with this branch: #940 and #931 in src/framework.ts, #844 in test/present-while-acting.test.ts, and #190 in src/framework.ts and test/explicit-prose-routing.test.ts.

Tests

One run, from a clean checkout of this head, on Linux with Node 24.22.2 and npm 11.19.1. It deleted node_modules and package-lock.json, ran npm install --no-audit --no-fund and npx tsc --noEmit, then npm run build and npm run pretest, then each of the six test files this change touches alone, with node --import ./dist/test/helpers/force-exit-blocking-stdout.js --test --test-force-exit. Then it put back a64cfc010f's src/framework.ts, the only file under src/ this change touches, and built and ran the same six files again.

npm ls --depth=0 printed @animalabs/chronicle 0.5.1, @animalabs/context-manager 0.24.2, @animalabs/mcpl-core 0.4.0, @animalabs/membrane 0.8.0, @babel/parser 7.29.12, @modelcontextprotocol/client 2.4.0, @modelcontextprotocol/server 2.4.0, @types/node 22.20.5, @types/ws 8.18.2, chokidar 4.0.3, discord.js 14.28.0, tsx 4.23.15, typescript 7.0.2 and ws 8.22.0. This repository commits no root lockfile, so these are the versions a fresh install chose on October 30.

• This head: tsc reported no errors, and every test in the six files passed: prose-drafts 257, explicit-prose-routing 120, tool-result-guard 156, code-execution 99, present-while-acting 93 and send-into-closed-channel 24.
• The same tests on a64cfc010f's src/framework.ts: 12 failed.
  • prose-drafts, 9. Six assert a receipt that now names its cause, among them "deliberate privacy is never drafted: skip_reply and a same-round private think". Three are new: "a turn whose plain speech two causes kept private names each with its count", "hybrid mode: a turn whose plain speech all four causes kept private names each with its count, in order", and "a skip_reply round with a private think in it counts its plain speech once, as skip_reply's".
  • explicit-prose-routing, 2. "hybrid: after >>>skip_reply, the next unprefixed envelope stays in the context and counts as kept private", and "hybrid: a retried turn's text waits for the replaced stream's late deliveries, and follows what they set", whose receipt now names (>>>skip_reply).
  • tool-result-guard, 1. "a fresh turn starts new routing state in every mode, and leaves the earlier turn's as it was", for the per-cause count's empty start.
  • code-execution, present-while-acting and send-into-closed-channel passed.

Not verified

Line numbers are this head's.

• Whether any route that withholds a round then writes a receipt that reads the suppressed count. No test covers it. Two probes covered two shapes of it: a stream that completes while the round's script runs, and a provider error retried once. Run at 48f26ce56c, an earlier main, each with a probe test added, neither withheld the round at all: each round was routed when its code_execution call answered.
• A silent request's 'private' hold. holdSilencedProse's doc comment names "a silent turn" among the deliberate silences (src/framework.ts:20056), and this change labels every 'private' hold skip_reply. A probe with 48f26ce56c's src/, through a silent heartbeat tick whose held retry merged into a start that wasn't silent, found that the merged start ran neither silent nor 'private'. This change doesn't touch that path. No test covers a receipt after a silent request's hold.
• Private speech that neither main nor this change counts. Two kinds:
  • a mid-turn round with a private think and no send, whose prose :25354–:25357 logs as not routed, with no count;
  • the body of a live hybrid >>>skip_reply envelope, which deliverHybridEnvelope logs as kept in context and returns from with no count (:22705–:22712), as the comment at test/prose-drafts.test.ts:2833 says.
• Node 22.12.0, which CI's test job uses, and the rest of the suite. We ran the six test files this change touches. CI runs the whole suite when this pull request opens.

---

• Changelog fragment added: changelog.d/317-receipt-names-why.changed.md.

Nigel-2405 made this change, and Oscar-1808 and Ada-1017 made the calls on it. Ada-1017 wrote #317. Alfred-2570 read the change word for word, its merge with main included, and our internal review read its first version, then its fixes. Langston-2479 wrote this description.