@cello-protocol/daemon 0.0.227 → 0.0.229

package/dist/onboarding-guidance.d.ts

@@ -0,0 +1,79 @@
+/**
+ * What a machine with NO agents is told, and why it is one string in one place.
+ *
+ * ─── The failure this exists to prevent ──────────────────────────────────────────────────────
+ * A new operator installs the plugin, runs `cello login`, and gets `No registered agents to
+ * start.` — nine words that name no next command, no token, and no bot. Measured 2026-09-07: the
+ * words "waitlist", "cohort" and "wave" appeared NOWHERE in the CLI, the daemon, or any of the
+ * five plugin skills, and the bot was referred to only as "the CELLO Operations Agent on
+ * Telegram" — a description, never a handle you could search for.
+ *
+ * ─── THERE ARE TWO TOKENS, AND CONFLATING THEM IS THE DEFECT ─────────────────────────────────
+ * The first draft of this text treated them as one thing and got the shape wrong.
+ *
+ *   **Waitlist token** — minted by a wave when you are admitted from the waitlist. The gate
+ *   handler calls it a grant of NETWORK ACCESS. You present it to the bot ONCE and it is
+ *   BURNED; the burn links your Telegram account. It is not per-agent and you never see it again.
+ *
+ *   **Agent token** — the `CELLO-` pre-authorization capability the bot issues so a specific
+ *   agent may register. One per agent, single-use, 24-hour expiry.
+ *
+ * The system's own name for the first is `waitlist_tokens`, and that is what it is called here.
+ * It is deliberately NOT "telegram token": `cello-ops-agent-telegram-bot-token` already exists in
+ * the infrastructure as the bot's API credential, and giving two unrelated secrets one name is a
+ * support conversation nobody can untangle.
+ *
+ * ─── WHY THE GATE IS AT THE BOTTOM, NOT THE TOP ──────────────────────────────────────────────
+ * An earlier version led with the cohort gate on the theory that it prevents a wasted trip to
+ * Telegram. Andre's correction, and the gate handler agrees with him: the gate's first step is
+ * "is this Telegram ID already linked? → proceed". Once the waitlist token is burned, the
+ * condition is permanently satisfied. Leading with it means everyone past that point reads a
+ * standing warning about a door they already walked through, every time they have no agent on a
+ * machine — which is also true on a second laptop, after a reset, and after an ecosystem wipe.
+ *
+ * So the happy path leads and the gate is a CONDITION underneath it, phrased as a question so a
+ * reader who is past it skips it instead of re-reading it.
+ *
+ * ─── Why the gate is bullets and not a paragraph ─────────────────────────────────────────────
+ * It was a prose block, and it dropped out of scanning mode exactly where the reader is still
+ * scanning. Both halves are now lists — numbered steps, then bulleted steps — so the whole
+ * message reads as one shape rather than switching from instructions to explanation halfway
+ * down. The bullets are ACTIONS for the same reason: at that point the reader's question is
+ * "what do I do", not "what is this thing".
+ *
+ * ─── Why the handle is DERIVED and not a constant ────────────────────────────────────────────
+ * There are two bots — production and staging — and a hardcoded handle sends a staging operator
+ * to the production bot, which will refuse their staging waitlist token with a message about a
+ * grant they do hold, on a bot they should not be talking to. `CELLO_ENV` already exists in this
+ * daemon and already carries `staging`, so the handle derives from it.
+ *
+ * **The mapping is a whitelist of ONE, deliberately.** `resolveCelloEnv` defaults an unset
+ * `CELLO_ENV` to `"local"`, and the overwhelmingly common case — an operator who installed from
+ * npm and set nothing — must never be pointed at staging. So only a literal `staging` gets the
+ * staging bot and everything else gets production: a misconfiguration sends someone to the real
+ * bot, which is the recoverable direction of that error.
+ *
+ * ─── Why it lives in the daemon ──────────────────────────────────────────────────────────────
+ * Two surfaces show it: the CLI (`cello login`) and the MCP shim, for the operator who never
+ * opens a terminal. The CLI imports this because `cli` depends on `daemon`. **`connect` depends
+ * on NO @cello-protocol package** — it is a 233 KB socket shim by design, and making it depend on
+ * the 7.8 MB daemon would put a native SQLCipher build on every session start. So the shim cannot
+ * import this, and the text reaches it over the wire: `cello_list_agents` returns it as
+ * `onboarding` when the roster is empty. One definition, two renderers, no drift.
+ */
+/** Where someone who has not signed up starts. Live as of 2026-09-07. */
+export declare const WAITLIST_URL = "https://cello.mygentic.ai/waitlist";
+/** The operations agent on Telegram, by environment. */
+export declare const BOT_HANDLE_PRODUCTION = "@CelloConnectBot";
+export declare const BOT_HANDLE_STAGING = "@CelloConnectStagingBot";
+/**
+ * Which bot to send this operator to. Only an explicit `staging` diverges — see the whitelist
+ * note above for why an unrecognised or unset value must resolve to production.
+ */
+export declare function botHandle(celloEnv?: string | undefined): string;
+/**
+ * Shown when a machine has zero agents. Plain text, terminal-width, no ANSI — it is rendered
+ * verbatim by the CLI and passed through to an agent by the shim, and neither can assume a TTY.
+ */
+export declare function noAgentsGuidance(celloEnv?: string): string;
+//# sourceMappingURL=onboarding-guidance.d.ts.map

package/dist/onboarding-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-guidance.d.ts","sourceRoot":"","sources":["../src/onboarding-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,yEAAyE;AACzE,eAAO,MAAM,YAAY,uCAAuC,CAAC;AAEjE,wDAAwD;AACxD,eAAO,MAAM,qBAAqB,qBAAqB,CAAC;AACxD,eAAO,MAAM,kBAAkB,4BAA4B,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,SAAS,CAAC,QAAQ,GAAE,MAAM,GAAG,SAAoC,GAAG,MAAM,CAEzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAgB1D"}

package/dist/onboarding-guidance.js

@@ -0,0 +1,95 @@
+/**
+ * What a machine with NO agents is told, and why it is one string in one place.
+ *
+ * ─── The failure this exists to prevent ──────────────────────────────────────────────────────
+ * A new operator installs the plugin, runs `cello login`, and gets `No registered agents to
+ * start.` — nine words that name no next command, no token, and no bot. Measured 2026-09-07: the
+ * words "waitlist", "cohort" and "wave" appeared NOWHERE in the CLI, the daemon, or any of the
+ * five plugin skills, and the bot was referred to only as "the CELLO Operations Agent on
+ * Telegram" — a description, never a handle you could search for.
+ *
+ * ─── THERE ARE TWO TOKENS, AND CONFLATING THEM IS THE DEFECT ─────────────────────────────────
+ * The first draft of this text treated them as one thing and got the shape wrong.
+ *
+ *   **Waitlist token** — minted by a wave when you are admitted from the waitlist. The gate
+ *   handler calls it a grant of NETWORK ACCESS. You present it to the bot ONCE and it is
+ *   BURNED; the burn links your Telegram account. It is not per-agent and you never see it again.
+ *
+ *   **Agent token** — the `CELLO-` pre-authorization capability the bot issues so a specific
+ *   agent may register. One per agent, single-use, 24-hour expiry.
+ *
+ * The system's own name for the first is `waitlist_tokens`, and that is what it is called here.
+ * It is deliberately NOT "telegram token": `cello-ops-agent-telegram-bot-token` already exists in
+ * the infrastructure as the bot's API credential, and giving two unrelated secrets one name is a
+ * support conversation nobody can untangle.
+ *
+ * ─── WHY THE GATE IS AT THE BOTTOM, NOT THE TOP ──────────────────────────────────────────────
+ * An earlier version led with the cohort gate on the theory that it prevents a wasted trip to
+ * Telegram. Andre's correction, and the gate handler agrees with him: the gate's first step is
+ * "is this Telegram ID already linked? → proceed". Once the waitlist token is burned, the
+ * condition is permanently satisfied. Leading with it means everyone past that point reads a
+ * standing warning about a door they already walked through, every time they have no agent on a
+ * machine — which is also true on a second laptop, after a reset, and after an ecosystem wipe.
+ *
+ * So the happy path leads and the gate is a CONDITION underneath it, phrased as a question so a
+ * reader who is past it skips it instead of re-reading it.
+ *
+ * ─── Why the gate is bullets and not a paragraph ─────────────────────────────────────────────
+ * It was a prose block, and it dropped out of scanning mode exactly where the reader is still
+ * scanning. Both halves are now lists — numbered steps, then bulleted steps — so the whole
+ * message reads as one shape rather than switching from instructions to explanation halfway
+ * down. The bullets are ACTIONS for the same reason: at that point the reader's question is
+ * "what do I do", not "what is this thing".
+ *
+ * ─── Why the handle is DERIVED and not a constant ────────────────────────────────────────────
+ * There are two bots — production and staging — and a hardcoded handle sends a staging operator
+ * to the production bot, which will refuse their staging waitlist token with a message about a
+ * grant they do hold, on a bot they should not be talking to. `CELLO_ENV` already exists in this
+ * daemon and already carries `staging`, so the handle derives from it.
+ *
+ * **The mapping is a whitelist of ONE, deliberately.** `resolveCelloEnv` defaults an unset
+ * `CELLO_ENV` to `"local"`, and the overwhelmingly common case — an operator who installed from
+ * npm and set nothing — must never be pointed at staging. So only a literal `staging` gets the
+ * staging bot and everything else gets production: a misconfiguration sends someone to the real
+ * bot, which is the recoverable direction of that error.
+ *
+ * ─── Why it lives in the daemon ──────────────────────────────────────────────────────────────
+ * Two surfaces show it: the CLI (`cello login`) and the MCP shim, for the operator who never
+ * opens a terminal. The CLI imports this because `cli` depends on `daemon`. **`connect` depends
+ * on NO @cello-protocol package** — it is a 233 KB socket shim by design, and making it depend on
+ * the 7.8 MB daemon would put a native SQLCipher build on every session start. So the shim cannot
+ * import this, and the text reaches it over the wire: `cello_list_agents` returns it as
+ * `onboarding` when the roster is empty. One definition, two renderers, no drift.
+ */
+/** Where someone who has not signed up starts. Live as of 2026-09-07. */
+export const WAITLIST_URL = "https://cello.mygentic.ai/waitlist";
+/** The operations agent on Telegram, by environment. */
+export const BOT_HANDLE_PRODUCTION = "@CelloConnectBot";
+export const BOT_HANDLE_STAGING = "@CelloConnectStagingBot";
+/**
+ * Which bot to send this operator to. Only an explicit `staging` diverges — see the whitelist
+ * note above for why an unrecognised or unset value must resolve to production.
+ */
+export function botHandle(celloEnv = process.env["CELLO_ENV"]) {
+    return celloEnv === "staging" ? BOT_HANDLE_STAGING : BOT_HANDLE_PRODUCTION;
+}
+/**
+ * Shown when a machine has zero agents. Plain text, terminal-width, no ANSI — it is rendered
+ * verbatim by the CLI and passed through to an agent by the shim, and neither can assume a TTY.
+ */
+export function noAgentsGuidance(celloEnv) {
+    return ("No agents on this machine yet. To make one:\n" +
+        "\n" +
+        `  1. Get an agent token from ${botHandle(celloEnv)} on Telegram\n` +
+        "  2. cello create-agent <name>\n" +
+        "  3. cello register-agent <name> <token>\n" +
+        "\n" +
+        "That's it — your agent is live and reachable.\n" +
+        "\n" +
+        "First time with the bot? It asks for a waitlist token first. To get one:\n" +
+        "\n" +
+        `  - Join the waitlist: ${WAITLIST_URL}\n` +
+        "  - Wait to be admitted to a launch cohort — you'll be notified\n" +
+        "  - Give the bot that token once. It is burned on use and never asked for again");
+}
+//# sourceMappingURL=onboarding-guidance.js.map

package/dist/onboarding-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-guidance.js","sourceRoot":"","sources":["../src/onboarding-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,YAAY,GAAG,oCAAoC,CAAC;AAEjE,wDAAwD;AACxD,MAAM,CAAC,MAAM,qBAAqB,GAAG,kBAAkB,CAAC;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAE5D;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,WAA+B,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IAC/E,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,qBAAqB,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB;IAChD,OAAO,CACL,+CAA+C;QAC/C,IAAI;QACJ,gCAAgC,SAAS,CAAC,QAAQ,CAAC,gBAAgB;QACnE,kCAAkC;QAClC,4CAA4C;QAC5C,IAAI;QACJ,iDAAiD;QACjD,IAAI;QACJ,4EAA4E;QAC5E,IAAI;QACJ,0BAA0B,YAAY,IAAI;QAC1C,mEAAmE;QACnE,iFAAiF,CAClF,CAAC;AACJ,CAAC"}

package/dist/operator-guidance.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two things the daemon says when a call cannot proceed.
+ *
+ * Both are text an operator reads, and both exist because the wire code alone is not an answer.
+ * `no_current_agent` names the command that fixes it. The registration guidance goes further: the
+ * wire code stays `dkg_failed` because it is a closed protocol union, but this string is a local
+ * daemon-to-IPC message, so it can say what actually happened instead of asserting a guess.
+ *
+ * ⚠️ The `dkg_failed` case is why this file exists rather than a switch inline somewhere; what that
+ * case used to claim, and why it was wrong, is recorded at the case itself — once, not twice.
+ */
+/**
+ * FROZEN. This used to be a per-daemon `const`; it is now one module object handed BY IDENTITY to
+ * twelve handlers across six modules. Nothing mutates it today (the CLI renderer is copy-on-write and
+ * the fallback notice merges via spread), but an in-place annotation by any one of those callers
+ * would silently rewrite every other caller's guidance, in every future response. The freeze makes
+ * that fail at the write instead.
+ */
+export declare const NO_CURRENT_AGENT_RESPONSE: Readonly<{
+    ok: false;
+    reason: "no_current_agent";
+    guidance: "No current agent is set for this connection. Call cello_start_agent to bring an agent online, then call cello_use_agent to set it as the current agent for this connection.";
+}>;
+export declare const registrationGuidance: (reason: string, detail?: string) => string;
+//# sourceMappingURL=operator-guidance.d.ts.map

package/dist/operator-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-guidance.d.ts","sourceRoot":"","sources":["../src/operator-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB;;;;EAIpC,CAAC;AAKH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAsBtE,CAAC"}

package/dist/operator-guidance.js

@@ -0,0 +1,50 @@
+/**
+ * The two things the daemon says when a call cannot proceed.
+ *
+ * Both are text an operator reads, and both exist because the wire code alone is not an answer.
+ * `no_current_agent` names the command that fixes it. The registration guidance goes further: the
+ * wire code stays `dkg_failed` because it is a closed protocol union, but this string is a local
+ * daemon-to-IPC message, so it can say what actually happened instead of asserting a guess.
+ *
+ * ⚠️ The `dkg_failed` case is why this file exists rather than a switch inline somewhere; what that
+ * case used to claim, and why it was wrong, is recorded at the case itself — once, not twice.
+ */
+/**
+ * FROZEN. This used to be a per-daemon `const`; it is now one module object handed BY IDENTITY to
+ * twelve handlers across six modules. Nothing mutates it today (the CLI renderer is copy-on-write and
+ * the fallback notice merges via spread), but an in-place annotation by any one of those callers
+ * would silently rewrite every other caller's guidance, in every future response. The freeze makes
+ * that fail at the write instead.
+ */
+export const NO_CURRENT_AGENT_RESPONSE = Object.freeze({
+    ok: false,
+    reason: "no_current_agent",
+    guidance: "No current agent is set for this connection. Call cello_start_agent to bring an agent online, then call cello_use_agent to set it as the current agent for this connection.",
+});
+// `detail` carries the ACTUAL cause when one is known. The wire code stays `dkg_failed` — it is a
+// closed protocol union — but this string is a local daemon→IPC message, so it can say what really
+// happened instead of asserting a guess.
+export const registrationGuidance = (reason, detail) => {
+    switch (reason) {
+        case "already_registered":
+            return "This agent is already registered with the directory. No action needed.";
+        case "directory_unreachable":
+            return "The directory signaling stream is not connected (or its bootstrap endpoint could not be resolved). Wait for directory_signaling to show connected in cello status, then retry.";
+        case "dkg_failed":
+            // NOT "this usually means the pre-auth token". That diagnosis is confidently wrong for the
+            // causes that actually occur — a colliding NODE_ID across two directory boxes, a commitment
+            // that does not match the client's primary_pubkey, a node dropping mid-ceremony — and it sends
+            // the operator to the wrong subsystem. The cause is now captured one call frame away
+            // (registration.dkg.failed), so it is reported rather than guessed at.
+            return detail
+                ? `The FROST DKG ceremony with the directory failed: ${detail}`
+                : "The FROST DKG ceremony with the directory failed, and no underlying cause was captured. Check the daemon log for registration.dkg.failed, which carries the reason.";
+        case "timeout":
+            return "The directory did not respond within the registration timeout. Retry once directory_signaling is connected.";
+        default:
+            return detail
+                ? `Registration failed: ${reason} — ${detail}`
+                : `Registration failed: ${reason}. Check the daemon logs (registration.* events).`;
+    }
+};
+//# sourceMappingURL=operator-guidance.js.map

package/dist/operator-guidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-guidance.js","sourceRoot":"","sources":["../src/operator-guidance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrD,EAAE,EAAE,KAAK;IACT,MAAM,EAAE,kBAAkB;IAC1B,QAAQ,EAAE,6KAA6K;CACxL,CAAC,CAAC;AAEH,kGAAkG;AAClG,mGAAmG;AACnG,yCAAyC;AACzC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAc,EAAE,MAAe,EAAU,EAAE;IAC9E,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,oBAAoB;YACvB,OAAO,wEAAwE,CAAC;QAClF,KAAK,uBAAuB;YAC1B,OAAO,gLAAgL,CAAC;QAC1L,KAAK,YAAY;YACf,2FAA2F;YAC3F,4FAA4F;YAC5F,+FAA+F;YAC/F,qFAAqF;YACrF,uEAAuE;YACvE,OAAO,MAAM;gBACX,CAAC,CAAC,qDAAqD,MAAM,EAAE;gBAC/D,CAAC,CAAC,qKAAqK,CAAC;QAC5K,KAAK,SAAS;YACZ,OAAO,6GAA6G,CAAC;QACvH;YACE,OAAO,MAAM;gBACX,CAAC,CAAC,wBAAwB,MAAM,MAAM,MAAM,EAAE;gBAC9C,CAAC,CAAC,wBAAwB,MAAM,kDAAkD,CAAC;IACzF,CAAC;AACH,CAAC,CAAC"}

package/dist/orphan-triage.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 024-ORPHANTRIAGE — what an operator is told when a message arrives for a conversation this
+ * machine has no record of.
+ *
+ * ─── What was wrong, from the operator's chair ─────────────────────────────────────────────────
+ *
+ * The notice used to end *"ask the counterparty to start a NEW session"*. Somebody sends a message
+ * naming a conversation you have never had, we refuse it, and we advise you to go and talk to them.
+ * If that message came from a stranger who guessed or harvested your peer id, **making contact is
+ * the thing they sent it for**: it confirms somebody is home and that your agent answers. The
+ * refusal was correct and the advice handed the sender the one thing the refusal denied them.
+ *
+ * ─── There are exactly TWO actions, and never a third ──────────────────────────────────────────
+ *
+ * **Report it** — the default, and the only action unless every condition below holds. **Reach out
+ * in a SEPARATE conversation** — only when the message carries a signature that verifies, against a
+ * key the operator has deliberately vouched for, in a conversation this machine still holds part
+ * of. Waiting, replying into the named conversation, deleting and ignoring are not offered, because
+ * an affordance list is a menu and a menu is how the wrong option gets picked.
+ *
+ * ─── Why the signals are read the way they are ─────────────────────────────────────────────────
+ *
+ * Every input here is anchored on something the sender does NOT control:
+ *
+ *  - the signature is checked against the key carried inside the sender's own signed bytes, so it
+ *    proves **possession of a private key** and nothing else — never an identity;
+ *  - "known" is a TIER, not a row: an inbound offer writes an `UNKNOWN`-tier contact row from the
+ *    wire with no operator action, so a row means "somebody dialled", and only `KNOWN` or above
+ *    means the operator vouched;
+ *  - "ongoing" is read from the operator's own transcript rows, never from the sequence number the
+ *    sender chose to write.
+ *
+ * ─── Deliberately a pure function ──────────────────────────────────────────────────────────────
+ *
+ * Same reason as `parkRefusalGuidance`: a guidance string is a decision about what a person does
+ * next, and the branch that is WRONG is the one nothing cheap can reach. Every sentence below is
+ * assertable without a database, a daemon or a socket.
+ */
+/** The only two actions this triage ever names. A third would be a menu. */
+export declare const ORPHAN_ACTIONS: {
+    /** Tell CELLO. The default, and the whole answer whenever the sender cannot be established. */
+    readonly REPORT: "report";
+    /** Open a SEPARATE conversation with the key — never the one the message names. */
+    readonly REACH_OUT_NEW_CONVERSATION: "reach_out_new_conversation";
+};
+export type OrphanAction = (typeof ORPHAN_ACTIONS)[keyof typeof ORPHAN_ACTIONS];
+/**
+ * A signal that was never measured, kept apart from one measured `false`.
+ *
+ * Review F6: these two used to be `false` on every path that did not look, and the orphan log event
+ * then published them as readings. Somebody filtering that event days later would read
+ * `ongoingConversation: false` and conclude there was no local trace, when nothing had been asked.
+ */
+export declare const NOT_CHECKED = "not_checked";
+export type Signal = boolean | typeof NOT_CHECKED;
+/**
+ * The three signals, computed at the orphan branch from evidence the daemon already holds.
+ *
+ * `signerPubkeyHex` is the gate: `null` means no signature could be checked at all, and everything
+ * below it is then meaningless — a claimed key is a string anyone can type.
+ */
+export interface OrphanEvidence {
+    /**
+     * The key whose signature over the sender's own signed bytes VERIFIED — full hex, never
+     * truncated. `null` when the frame carried no readable signed record, which is a finding and not
+     * a missing field.
+     */
+    signerPubkeyHex: string | null;
+    /**
+     * Has the operator VOUCHED for that key — tier `KNOWN` or above? Read from OUR store, not from
+     * the message, and never from the mere existence of a row: an inbound offer writes an
+     * `UNKNOWN`-tier row from the wire, and blocking a contact leaves its row in place at `BLOCKED`.
+     */
+    knownContact: Signal;
+    /** The operator's own pet name for that key, when they have set one. */
+    contactMoniker: string | null;
+    /**
+     * Do we still hold part of this conversation locally? Anchored on OUR transcript rows — never on
+     * the sequence number the sender supplied, which they are free to invent.
+     */
+    ongoingConversation: Signal;
+}
+export interface OrphanTriage {
+    action: OrphanAction;
+    impact: string;
+    guidance: string;
+}
+/**
+ * The sentence that catches the operator who is unsure, and it is in EVERY case.
+ *
+ * The three signals are probabilistic: a vouched key can be stolen, a local trace can belong to a
+ * conversation someone has taken over mid-flight, and an operator standing here has no way to
+ * resolve it. Reporting costs them nothing and costs an attacker their anonymity, so uncertainty
+ * resolves to report — and it is needed most in the reach-out case, where the temptation to act
+ * alone is highest.
+ */
+export declare const WHEN_IN_DOUBT = "When in doubt, report it: reporting costs you nothing and costs whoever sent this their anonymity.";
+/**
+ * ⛔ REPORTING IS NOT REACHABLE YET, AND SAYING SO IS THE POINT.
+ *
+ * The destination is meant to be a CELLO agent — `CELLO_Reporting` — that any operator's agent
+ * opens a session with, which is the product demonstrating its own use. It does not exist: it needs
+ * a registered identity, somewhere to run, and a pubkey published in shipped guidance, and that
+ * last part is outward-facing wording. Naming a verb that resolves to nothing is exactly what
+ * Invariant 4 forbids, so this says plainly that there is nowhere to send it and names the one
+ * thing the operator CAN do — keep the evidence.
+ *
+ * ⚠️ **THE EVIDENCE DIFFERS BY CASE, AND SAYING "the public key" ALWAYS WAS WRONG** — review F4.
+ * In the unsigned case the impact has just finished explaining that any key on the message is a
+ * string somebody typed; telling the operator to write it down as evidence in the next breath asks
+ * them to record an unverified claim in the one case the paragraph above taught them not to.
+ *
+ * ⚠️ **"the time" IS NOT ON THE SURFACE** — review F9. The inbox projection carries session, reason,
+ * kind, impact, guidance and count; `first_at`/`last_at` exist in the table and are not selected. So
+ * the sentence names the time the reader has, which is the time they are reading.
+ *
+ * ⛔ TRIGGER: when `CELLO_Reporting` is provisioned and its pubkey is published, this becomes the
+ * session-open verb and its pubkey. Do not soften it before then.
+ */
+export declare function reportingNotYetAvailable(signerPubkeyHex: string | null): string;
+/**
+ * Render the triage.
+ *
+ * ⚠️ **NO SENTENCE HERE MAY SAY THE MESSAGE IS *FROM* ANYONE.** A verified signature proves that
+ * whoever produced it holds a private key. Keys are minted by anyone who wants one, and a key you
+ * recognise may have been stolen. "Signed by the key you know as X" survives that question;
+ * "from X" does not, and it is the sentence an operator would act on hardest.
+ */
+export declare function triageOrphanedContent(evidence: OrphanEvidence, retention: string): OrphanTriage;
+//# sourceMappingURL=orphan-triage.d.ts.map

package/dist/orphan-triage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-triage.d.ts","sourceRoot":"","sources":["../src/orphan-triage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,cAAc;IACzB,+FAA+F;;IAE/F,mFAAmF;;CAE3E,CAAC;AACX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEhF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,gBAAgB,CAAC;AACzC,MAAM,MAAM,MAAM,GAAG,OAAO,GAAG,OAAO,WAAW,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,uGAAuG,CAAC;AAElI;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAO/E;AAwBD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,YAAY,CAsD/F"}

package/dist/orphan-triage.js

@@ -0,0 +1,207 @@
+/**
+ * 024-ORPHANTRIAGE — what an operator is told when a message arrives for a conversation this
+ * machine has no record of.
+ *
+ * ─── What was wrong, from the operator's chair ─────────────────────────────────────────────────
+ *
+ * The notice used to end *"ask the counterparty to start a NEW session"*. Somebody sends a message
+ * naming a conversation you have never had, we refuse it, and we advise you to go and talk to them.
+ * If that message came from a stranger who guessed or harvested your peer id, **making contact is
+ * the thing they sent it for**: it confirms somebody is home and that your agent answers. The
+ * refusal was correct and the advice handed the sender the one thing the refusal denied them.
+ *
+ * ─── There are exactly TWO actions, and never a third ──────────────────────────────────────────
+ *
+ * **Report it** — the default, and the only action unless every condition below holds. **Reach out
+ * in a SEPARATE conversation** — only when the message carries a signature that verifies, against a
+ * key the operator has deliberately vouched for, in a conversation this machine still holds part
+ * of. Waiting, replying into the named conversation, deleting and ignoring are not offered, because
+ * an affordance list is a menu and a menu is how the wrong option gets picked.
+ *
+ * ─── Why the signals are read the way they are ─────────────────────────────────────────────────
+ *
+ * Every input here is anchored on something the sender does NOT control:
+ *
+ *  - the signature is checked against the key carried inside the sender's own signed bytes, so it
+ *    proves **possession of a private key** and nothing else — never an identity;
+ *  - "known" is a TIER, not a row: an inbound offer writes an `UNKNOWN`-tier contact row from the
+ *    wire with no operator action, so a row means "somebody dialled", and only `KNOWN` or above
+ *    means the operator vouched;
+ *  - "ongoing" is read from the operator's own transcript rows, never from the sequence number the
+ *    sender chose to write.
+ *
+ * ─── Deliberately a pure function ──────────────────────────────────────────────────────────────
+ *
+ * Same reason as `parkRefusalGuidance`: a guidance string is a decision about what a person does
+ * next, and the branch that is WRONG is the one nothing cheap can reach. Every sentence below is
+ * assertable without a database, a daemon or a socket.
+ */
+/** The only two actions this triage ever names. A third would be a menu. */
+export const ORPHAN_ACTIONS = {
+    /** Tell CELLO. The default, and the whole answer whenever the sender cannot be established. */
+    REPORT: "report",
+    /** Open a SEPARATE conversation with the key — never the one the message names. */
+    REACH_OUT_NEW_CONVERSATION: "reach_out_new_conversation",
+};
+/**
+ * A signal that was never measured, kept apart from one measured `false`.
+ *
+ * Review F6: these two used to be `false` on every path that did not look, and the orphan log event
+ * then published them as readings. Somebody filtering that event days later would read
+ * `ongoingConversation: false` and conclude there was no local trace, when nothing had been asked.
+ */
+export const NOT_CHECKED = "not_checked";
+/**
+ * The sentence that catches the operator who is unsure, and it is in EVERY case.
+ *
+ * The three signals are probabilistic: a vouched key can be stolen, a local trace can belong to a
+ * conversation someone has taken over mid-flight, and an operator standing here has no way to
+ * resolve it. Reporting costs them nothing and costs an attacker their anonymity, so uncertainty
+ * resolves to report — and it is needed most in the reach-out case, where the temptation to act
+ * alone is highest.
+ */
+export const WHEN_IN_DOUBT = "When in doubt, report it: reporting costs you nothing and costs whoever sent this their anonymity.";
+/**
+ * ⛔ REPORTING IS NOT REACHABLE YET, AND SAYING SO IS THE POINT.
+ *
+ * The destination is meant to be a CELLO agent — `CELLO_Reporting` — that any operator's agent
+ * opens a session with, which is the product demonstrating its own use. It does not exist: it needs
+ * a registered identity, somewhere to run, and a pubkey published in shipped guidance, and that
+ * last part is outward-facing wording. Naming a verb that resolves to nothing is exactly what
+ * Invariant 4 forbids, so this says plainly that there is nowhere to send it and names the one
+ * thing the operator CAN do — keep the evidence.
+ *
+ * ⚠️ **THE EVIDENCE DIFFERS BY CASE, AND SAYING "the public key" ALWAYS WAS WRONG** — review F4.
+ * In the unsigned case the impact has just finished explaining that any key on the message is a
+ * string somebody typed; telling the operator to write it down as evidence in the next breath asks
+ * them to record an unverified claim in the one case the paragraph above taught them not to.
+ *
+ * ⚠️ **"the time" IS NOT ON THE SURFACE** — review F9. The inbox projection carries session, reason,
+ * kind, impact, guidance and count; `first_at`/`last_at` exist in the table and are not selected. So
+ * the sentence names the time the reader has, which is the time they are reading.
+ *
+ * ⛔ TRIGGER: when `CELLO_Reporting` is provisioned and its pubkey is published, this becomes the
+ * session-open verb and its pubkey. Do not soften it before then.
+ */
+export function reportingNotYetAvailable(signerPubkeyHex) {
+    const evidence = signerPubkeyHex === null
+        // No key is named, deliberately. The only key-shaped thing here is the one the message claimed,
+        // and the impact has just said that claim proves nothing.
+        ? "the conversation id above, the time you are reading this, and the fact that the message carried no signature anyone could check"
+        : `the public key above, the conversation id, and the time you are reading this`;
+    return `CELLO has no agent to receive reports yet, so there is no command here that would send one. Write down ${evidence} — that IS the report — and keep it until there is somewhere to send it.`;
+}
+/**
+ * ✅ **THE TRIGGER FIRED, AND THE SENTENCE MOVED RATHER THAN BEING REWRITTEN IN PLACE.**
+ *
+ * This module used to define `MESSAGE_NOT_RETAINED`: *"The message itself was not kept — this build
+ * discards what it refuses."* `023-REFUSEDEVIDENCE` made that false, and 024's own note asked for a
+ * rewrite rather than a deletion so a reader can see the claim changed. Recorded here; the
+ * replacement is `retentionSentence` in `quarantine-framing.ts`.
+ *
+ * It lives THERE, not here. Whether a refused message was retained is 023's fact, and this module
+ * is prose about what to DO with it — so it receives the sentence as `retention` and renders it.
+ */
+/**
+ * The unchanging first half: what happened to the message, in every case.
+ *
+ * ⚠️ The last clause is review F11. The notice is deduplicated per (agent, session, reason) and
+ * carries a count, while the prose now names a SPECIFIC key — so a notice reading "5 times" beside
+ * one key would imply all five came from that key, and they may not have. The old text was generic
+ * and had no such problem; this unit introduced it, so this unit says so.
+ */
+const WHAT_HAPPENED = "A message arrived for a conversation this machine holds no record of. It was NOT delivered, NOT shown and NOT acknowledged, so the sender will redeliver it and be refused the same way. If this notice says it has happened more than once, what follows describes the most recent one — earlier arrivals may not have looked the same.";
+/**
+ * Render the triage.
+ *
+ * ⚠️ **NO SENTENCE HERE MAY SAY THE MESSAGE IS *FROM* ANYONE.** A verified signature proves that
+ * whoever produced it holds a private key. Keys are minted by anyone who wants one, and a key you
+ * recognise may have been stolen. "Signed by the key you know as X" survives that question;
+ * "from X" does not, and it is the sentence an operator would act on hardest.
+ */
+export function triageOrphanedContent(evidence, retention) {
+    const { signerPubkeyHex, knownContact, contactMoniker, ongoingConversation } = evidence;
+    // ── No checkable signature: nothing whatsoever is known about the sender. ────────────────────
+    //
+    // "Not signed" is a FINDING, and a strong one — it is stated as one rather than as an absent
+    // field, because an operator who reads it as a gap goes looking for the missing information and
+    // there is none to find.
+    if (signerPubkeyHex === null) {
+        return {
+            action: ORPHAN_ACTIONS.REPORT,
+            impact: `${WHAT_HAPPENED} It carried NO signature that could be checked, so nothing at all is known about who sent it — that is a finding, not a gap. A message with no verifiable signature could have been produced by anyone, and any public key it names is just a string that was typed.`,
+            guidance: reportOnlyGuidance(signerPubkeyHex, retention),
+        };
+    }
+    /**
+     * ── Anything short of BOTH conditions is a stranger, and gets the default. ───────────────────
+     *
+     * ⚠️ **THE CONJUNCTION IS ANDRE'S, VERBATIM, and dropping it was review F3.** *"whether to reach
+     * out depends on whether we can verify they are a known contact in their address book. And if
+     * they are a known contact **and this was an ongoing conversation until this point**, then a
+     * separate session with them … is warranted."* Branching on the vouch alone produced a notice
+     * that argued with itself — an impact saying nothing here favours a fault over a probe, above a
+     * guidance saying go and make contact anyway.
+     *
+     * `"not_checked"` lands here too, and that is the whole point of the third state: a signal nobody
+     * measured must never be the one that unlocks contact.
+     */
+    if (knownContact !== true || ongoingConversation !== true) {
+        return {
+            action: ORPHAN_ACTIONS.REPORT,
+            impact: `${WHAT_HAPPENED} A signature on it verified against the public key ${signerPubkeyHex}, which proves only that whoever produced it holds the private key matching that public key — anyone can mint a keypair and sign with it, so this identifies nobody. ${strangerReason(knownContact, ongoingConversation)}`,
+            guidance: reportOnlyGuidance(signerPubkeyHex, retention),
+        };
+    }
+    // ── A vouched key, and a conversation this machine still holds part of. ──────────────────────
+    const label = contactMoniker === null ? "that key" : `"${contactMoniker}"`;
+    return {
+        action: ORPHAN_ACTIONS.REACH_OUT_NEW_CONVERSATION,
+        impact: `${WHAT_HAPPENED} A signature on it verified against the public key ${signerPubkeyHex}, which you have vouched for in your address book as ${label}. That proves whoever produced it holds the private key matching the public key you know as ${label} — it does NOT prove they are ${label}, because a private key can be stolen or copied. This machine still holds part of a conversation under that id, so a lost session record is a likelier explanation than a probe — likelier, not proven, and somebody who has taken over a key mid-conversation would look exactly the same from here.`,
+        guidance: `ONE thing to do, and it is worth doing: open a NEW conversation with ${signerPubkeyHex} and ask whether they sent it. ` +
+            `It must be a NEW one — the conversation this message names does not exist on this machine, and opening THAT one because the message asked for it is the same probe succeeding by another route. ` +
+            `The valuable outcome is the bad one: if they say they sent nothing, you have both just learned that the key you know as ${label} is being used by someone else, and they can pause or burn that agent identity before it costs them more. ` +
+            // Review F5, and it is the sentence that keeps clause 4 from undoing clause 5: a CELLO
+            // conversation is authenticated by the key itself, so in the stolen-key case — the exact case
+            // this reach-out exists to detect — the thief is the one who answers, and answers "yes, that
+            // was me". The remedy only works over a channel the key does not control.
+            `A CELLO answer comes from whoever holds that key, so a "yes, that was me" proves nothing new — if you have another way to reach them, out of band, that is the one that actually answers this. ` +
+            `${reportingNotYetAvailable(signerPubkeyHex)} ${retention} ${WHEN_IN_DOUBT}`,
+    };
+}
+/**
+ * Why this signer is being treated as a stranger — said, rather than left as a silence.
+ *
+ * A notice that offers only "report" without saying which condition failed leaves an operator who
+ * DOES recognise the key with no way to understand the advice, and the likeliest thing they do next
+ * is ignore it.
+ */
+function strangerReason(knownContact, ongoingConversation) {
+    if (knownContact === NOT_CHECKED || ongoingConversation === NOT_CHECKED) {
+        return "Your address book and your own record of this conversation could NOT be read on this machine, so neither could be weighed — the daemon logged why under session.content.orphaned.evidence.failed. Nothing here has been ruled out; it has simply not been checked.";
+    }
+    if (knownContact === false) {
+        return "You have not vouched for that key: it is either absent from your address book, or present only because somebody dialled you, or blocked. A stranger who can sign is still a stranger.";
+    }
+    return "You have vouched for that key — but this machine holds no part of any conversation under the id the message names, so there is nothing here that makes a lost record more likely than a probe.";
+}
+/**
+ * The report-only guidance, shared by the three cases that get it.
+ *
+ * ⚠️ **NOT ONE CONTACT VERB APPEARS HERE, INCLUDING IN A PROHIBITION.** The obvious wording is
+ * "do not contact them" — and a notice containing that sentence has a contact verb in it, which is
+ * the string an agent skims for and the string a regression check greps for. The prohibition is
+ * therefore written in terms of what the operator does INSTEAD: nothing.
+ *
+ * ⚠️ **AND THAT RULE CAUGHT THIS FUNCTION ITSELF** — review F12. The first version said *"Answer
+ * nothing, open nothing"* and *"ANY response is the answer it is looking for"*, which puts `answer`
+ * and `respond` on the page by the module's own doctrine. The verb list in the tests had been
+ * calibrated to this text rather than to the rule, so it passed. Both verbs are gone and both are
+ * now in the list.
+ */
+function reportOnlyGuidance(signerPubkeyHex, retention) {
+    return ("ONE thing to do: record it as a report. Nothing goes back, nothing is opened, and this one is left exactly where it stands — silence is the correct move here. " +
+        "A message naming a conversation that does not exist is most often a probe testing whether anybody is home, and anything at all going back is the confirmation it is looking for. " +
+        `${reportingNotYetAvailable(signerPubkeyHex)} ${retention} ${WHEN_IN_DOUBT}`);
+}
+//# sourceMappingURL=orphan-triage.js.map

package/dist/orphan-triage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orphan-triage.js","sourceRoot":"","sources":["../src/orphan-triage.ts"],"names":[],"mappings":"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"}