approval-md 0.2.0 → 0.3.0

package/dist/src/cli/channel-telegram.d.ts

@@ -14,12 +14,18 @@
  *    are read here and passed to the channel as values (SPEC.md §5.1: policy
  *    carries the env-var *names*, never the secrets). Nothing in `channels/`
  *    touches `process.env`.
- * 2. **It declares who is approving.** The decision is recorded against the
- *    human actor from `--as` / `APPROVAL_HUMAN`, never against anything the
- *    callback carried. SPEC.md §11: identity in v0.1 is config-declared, the
- *    trust boundary is the local machine, and everyone who can reach the
- *    configured chat can approve as that actor. This is stated in `--help`
- *    because an operator has to be able to see it without reading the source.
+ * 2. **It declares the identity the process itself acts under.** `--as` /
+ *    `APPROVAL_HUMAN` is what this listener is, and it is what a decision is
+ *    recorded as whenever the policy maps no sender for this channel: SPEC.md
+ *    §11's config-declared identity, where the trust boundary is the local
+ *    machine and everyone who can reach the configured chat can approve as that
+ *    actor. Since APRV-324 a policy MAY map Telegram account ids to approvers,
+ *    and then the decision is recorded against the person the operator attested
+ *    the tapping account to, and an unmapped account is refused rather than
+ *    recorded as this listener. Either way the choosing happens in
+ *    `channels/contract.ts` against the attested policy, never here and never
+ *    in the channel. Both settings are stated in `--help` because an operator
+ *    has to be able to see which one they are in without reading the source.
  * 3. **It holds the token.** A grant mints a single-use execution token;
  *    `recordChannelDecision` returns it to *this* handler, which prints it on
  *    **stdout** and never hands it back to the channel. It is never sent to
@@ -107,6 +113,8 @@ import { type ChannelTagRefusalCode, type TagOptions } from "../channels/tagging
 import { type CheckpointTap } from "./checkpoint-tap.js";
 import { TelegramChannel, type CheckpointTapResponse, type ReviewCard, type ReviewTapResponse, type TelegramCommand, type TelegramTerminalState } from "../channels/telegram.js";
 import { type TelegramDelivery } from "../core/telegram-config.js";
+import { type InstanceFinding } from "../core/instance.js";
+import { type ChannelSender } from "../core/sender-identity.js";
 import { type ParsedFlags } from "./args.js";
 import { type GlossRunner } from "./gloss.js";
 import { type GlossRunnerFactoryOptions } from "./gloss-options.js";
@@ -151,6 +159,32 @@ export interface ListenSetup {
      * `core/telegram-config.ts` beside the other Telegram policy readings.
      */
     delivery: TelegramDelivery;
+    /**
+     * Cross-instance findings `--allow-cross-instance` let through (APRV-390).
+     *
+     * Empty on every ordinary start, because a finding without the flag is a
+     * refusal. Carried on the setup rather than printed inside `prepareListen`
+     * for the reason that function prints nothing at all: `approval up` and
+     * `approval channel telegram listen` choose their own stream, and this is
+     * the one thing an overridden refusal still owes the operator.
+     */
+    crossInstance: readonly InstanceFinding[];
+    /**
+     * `--allow-cross-instance` as passed (APRV-390).
+     *
+     * Carried as well as applied, because the flag overrides TWO refusals and
+     * only one of them can be decided synchronously. The credential check is
+     * `prepareListen`'s; the bot-ownership claim needs a `getMe`, so it happens
+     * later and has to be able to ask whether the operator already said yes.
+     */
+    allowCrossInstance: boolean;
+    /**
+     * The Bot API base this listener talks to (APRV-390).
+     *
+     * Part of the bot's identity in the ownership registry, because a bot id is
+     * unique within one Bot API deployment and nothing more.
+     */
+    apiBase: string;
     /**
      * How the one-sentence model gloss is obtained (APRV-144).
      *
@@ -178,6 +212,42 @@ export interface ListenSetup {
      */
     checkpoint: CheckpointTap;
 }
+/**
+ * Claim this listener's bot before it polls (APRV-390).
+ *
+ * ONE `getMe`, once per process, before the first `getUpdates`. Two things
+ * come out of it: the bot's identity, which is the only thing that can tell
+ * two instances holding two differently-named copies of one token apart; and
+ * a claim in the per-machine registry, which is what makes the SECOND such
+ * listener refuse instead of joining a 409 loop.
+ *
+ * ## Why an unreachable Bot API is not a refusal
+ *
+ * A `getMe` that fails says nothing about ownership. The machine may be behind
+ * a captive portal, the API may be rate-limiting, the network may be down for
+ * four seconds. Refusing to start on that would mean a transient network fault
+ * took the phone channel down until somebody noticed, in exchange for no
+ * safety: an unreachable Bot API is also a `getUpdates` that cannot conflict
+ * with anything. So the preflight says what happened and lets the listener
+ * start, where the existing retry loop is already the right behaviour. The
+ * refusal is reserved for the case this task is about, which is a bot that is
+ * demonstrably somebody else's.
+ */
+export declare function claimListenerBot(setup: ListenSetup, report: (message: string) => void): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    code: ListenRefusalCode;
+    message: string;
+}>;
+/**
+ * What to append to a runtime 409, naming the other instance if one is known.
+ *
+ * Read at the moment of the conflict rather than captured at start-up, because
+ * the other gate may have claimed the bot in between: the registry is the only
+ * thing that knows, and it is cheap to re-read.
+ */
+export declare function conflictAdviceFor(setup: ListenSetup): () => string | null;
 /**
  * Why a listener could not be built. A closed union, because more than one
  * caller now branches on it: the verb turns each into an exit code, and
@@ -194,7 +264,22 @@ export declare const LISTEN_REFUSAL_CODES: readonly [
 /** The log could not be read (or its directory does not exist). */
 "log-unreadable", 
 /** `--payloads` did not hold a JSON object of action key -> payload. */
-"payloads-unreadable"];
+"payloads-unreadable", 
+/**
+ * A credential variable holds a value this instance did not configure
+ * (APRV-390): it was exported before the process started and is not this
+ * instance's own `approval env` export, or `.approval/env` names another
+ * instance's keystore item. Refused rather than warned since APRV-390 — the
+ * warning is what let a demo gate spend an evening on the production bot.
+ * `--allow-cross-instance` is the deliberate case.
+ */
+"cross-instance-credential", 
+/**
+ * `getMe` named a bot another instance on this machine has already claimed
+ * (APRV-390). Refused BEFORE the first `getUpdates`, so the operator reads
+ * which two gates are involved instead of an HTTP 409 loop.
+ */
+"bot-owned-elsewhere"];
 export type ListenRefusalCode = (typeof LISTEN_REFUSAL_CODES)[number];
 /** Everything {@link prepareListen} needs, already resolved to absolute paths. */
 export interface ListenRequest {
@@ -215,6 +300,11 @@ export interface ListenRequest {
     pollTimeout: string | null;
     once: boolean;
     json: boolean;
+    /**
+     * `--allow-cross-instance` (APRV-390): start on a credential this instance
+     * did not configure, saying so, instead of refusing.
+     */
+    allowCrossInstance?: boolean;
     /** Where the channel's operational complaints go. Ordinarily stderr. */
     log(message: string): void;
     /** The gloss runner, if the caller wants one. See {@link ListenSetup.gloss}. */
@@ -660,31 +750,13 @@ export declare function dispatchPending(setup: ListenSetup, streams: Streams, st
 export declare const COLLAPSE_STALE_AFTER_MS: number;
 /** The computed lines a collapsed re-delivery leads with (APRV-287). */
 export declare function staleLines(requests: ChannelRequest[], now: string): string[];
-/**
- * What a checkpoint tap does, on the machine the listener runs on (APRV-257).
- *
- * The signing happens HERE, in the listener's process, and that is the whole
- * point of the tap: this process holds the vault passphrase because a HUMAN
- * exported it into the shell they started it from, and `core/child-env.ts`
- * strips that variable from every child an agent's session spawns. No agent can
- * arrange for a process that reaches this function with a key.
- *
- * Nothing about the head is re-derived. The `(seq, hash)` comes back from the
- * channel exactly as it was put on the screen, and
- * {@link ../core/checkpoint.js appendCheckpointAt} signs that and checks the
- * log still carries it. A handler that quietly re-read the head would be
- * putting a human's key over bytes nobody looked at.
- *
- * `Not now` appends nothing and says so. It is not a rejection: there is no
- * request here to reject, and a checkpoint that is owed is a warning at every
- * layer and a refusal at none.
- */
 export declare function checkpointHandlerFor(setup: ListenSetup, streams: Streams): (tap: {
     sign: boolean;
     head: {
         seq: number;
         hash: string;
     };
+    sender?: ChannelSender;
 }) => CheckpointTapResponse;
 /**
  * What a review tap does: the human-only `reviewSample`, and nothing else
@@ -712,6 +784,7 @@ export declare function reviewHandlerFor(setup: ListenSetup, streams: Streams):
     verdict: "ok" | "denied";
     reaction?: "disliked" | "indifferent" | "liked" | "loved";
     note?: string;
+    sender?: ChannelSender;
 }) => ReviewTapResponse;
 /**
  * `/queue`, `/skip`, `/next` — the paced walkthrough's three verbs (APRV-216).

package/dist/src/cli/channel-telegram.js

@@ -14,12 +14,18 @@
  *    are read here and passed to the channel as values (SPEC.md §5.1: policy
  *    carries the env-var *names*, never the secrets). Nothing in `channels/`
  *    touches `process.env`.
- * 2. **It declares who is approving.** The decision is recorded against the
- *    human actor from `--as` / `APPROVAL_HUMAN`, never against anything the
- *    callback carried. SPEC.md §11: identity in v0.1 is config-declared, the
- *    trust boundary is the local machine, and everyone who can reach the
- *    configured chat can approve as that actor. This is stated in `--help`
- *    because an operator has to be able to see it without reading the source.
+ * 2. **It declares the identity the process itself acts under.** `--as` /
+ *    `APPROVAL_HUMAN` is what this listener is, and it is what a decision is
+ *    recorded as whenever the policy maps no sender for this channel: SPEC.md
+ *    §11's config-declared identity, where the trust boundary is the local
+ *    machine and everyone who can reach the configured chat can approve as that
+ *    actor. Since APRV-324 a policy MAY map Telegram account ids to approvers,
+ *    and then the decision is recorded against the person the operator attested
+ *    the tapping account to, and an unmapped account is refused rather than
+ *    recorded as this listener. Either way the choosing happens in
+ *    `channels/contract.ts` against the attested policy, never here and never
+ *    in the channel. Both settings are stated in `--help` because an operator
+ *    has to be able to see which one they are in without reading the source.
  * 3. **It holds the token.** A grant mints a single-use execution token;
  *    `recordChannelDecision` returns it to *this* handler, which prints it on
  *    **stdout** and never hands it back to the channel. It is never sent to
@@ -105,15 +111,21 @@ import { readFileSync, statSync } from "node:fs";
 import { isAbsolute, resolve as resolvePathSegments } from "node:path";
 import { HUMAN_ACTOR_ENV, resolveHumanActor } from "../core/attest.js";
 import { assembleBatch } from "../channels/batch.js";
-import { recordChannelDecision, } from "../channels/contract.js";
+import { recordChannelDecision, refusedDecisionLine, } from "../channels/contract.js";
 import { ageText, buildPendingQueue, } from "../channels/tagging.js";
 import { checkpointOfferFor, checkpointPromptLines, checkpointSignedLines, signCheckpointOffer, } from "./checkpoint-tap.js";
-import { actionRefOf, decidedLine, groupForDigest, isMessageNotModified, isTelegramTerminalState, TelegramChannel, telegramChatEnvFor, telegramTokenEnvFor, TELEGRAM_NOT_RECORDED, TELEGRAM_REVIEW_DENIED, TELEGRAM_REVIEW_RECORDED, TELEGRAM_TERMINAL_HEADLINES, utcClock, } from "../channels/telegram.js";
+import { actionRefOf, decidedLine, groupForDigest, isMessageNotModified, isTelegramTerminalState, TelegramChannel, telegramChatEnvFor, telegramTokenEnvFor, TELEGRAM_NOT_RECORDED, TELEGRAM_REVIEW_DENIED, TELEGRAM_REVIEW_RECORDED, TELEGRAM_DEFAULT_API_BASE, TELEGRAM_TERMINAL_HEADLINES, utcClock, } from "../channels/telegram.js";
 import { openReviewCards } from "./audit-card.js";
 import { reviewSample } from "../core/audit.js";
 import { abandonedAfterMs, HOOK_DEFAULT_WAIT_MS, HOOK_RETRY_GRACE_MS, } from "../core/harness-wait.js";
 import { telegramDeliveryFor } from "../core/telegram-config.js";
 import { loadPolicy } from "../core/policy-load.js";
+import { valueFindings } from "../core/instance.js";
+import { defaultSourceRunner } from "../core/env-file.js";
+import { claimBot, describeOwners, otherOwnersOf, ownedBot, } from "../core/channel-owner.js";
+import { actorForSender, recordedSenderFor, senderKeyFrom, } from "../core/sender-identity.js";
+import { recordRefusedGesture, } from "../core/gesture-refusal.js";
+import { attestationRefusal, checkAttestation } from "../core/attest.js";
 import { promptLayoutFor } from "../core/prompt-layout.js";
 import { passphraseEnvFor } from "../core/vault.js";
 import { isAttestationActionKey, proposalRecords, proposalState, } from "../core/policy-proposal.js";
@@ -136,6 +148,8 @@ const LISTEN_FLAGS = {
     "--api-base": "string",
     "--poll-timeout": "string",
     "--once": "boolean",
+    /** APRV-390: start on a credential this instance did not configure. */
+    "--allow-cross-instance": "boolean",
     "--gloss": "boolean",
     "--no-gloss": "boolean",
     "--gloss-provider": "string",
@@ -201,6 +215,77 @@ function env(name) {
     const value = process.env[name];
     return value === undefined || value.trim().length === 0 ? null : value.trim();
 }
+/**
+ * Claim this listener's bot before it polls (APRV-390).
+ *
+ * ONE `getMe`, once per process, before the first `getUpdates`. Two things
+ * come out of it: the bot's identity, which is the only thing that can tell
+ * two instances holding two differently-named copies of one token apart; and
+ * a claim in the per-machine registry, which is what makes the SECOND such
+ * listener refuse instead of joining a 409 loop.
+ *
+ * ## Why an unreachable Bot API is not a refusal
+ *
+ * A `getMe` that fails says nothing about ownership. The machine may be behind
+ * a captive portal, the API may be rate-limiting, the network may be down for
+ * four seconds. Refusing to start on that would mean a transient network fault
+ * took the phone channel down until somebody noticed, in exchange for no
+ * safety: an unreachable Bot API is also a `getUpdates` that cannot conflict
+ * with anything. So the preflight says what happened and lets the listener
+ * start, where the existing retry loop is already the right behaviour. The
+ * refusal is reserved for the case this task is about, which is a bot that is
+ * demonstrably somebody else's.
+ */
+export async function claimListenerBot(setup, report) {
+    let identity;
+    try {
+        identity = await setup.channel.identify();
+    }
+    catch (cause) {
+        report(`approval: telegram getMe could not be reached (${cause instanceof Error ? cause.message : String(cause)}), so which bot this token names is unknown and no ownership was recorded; starting anyway`);
+        return { ok: true };
+    }
+    if (identity.id.length === 0) {
+        report("approval: telegram getMe answered without a bot id, so no ownership was recorded; starting anyway");
+        return { ok: true };
+    }
+    const claim = claimBot(setup.logPath, {
+        channel: "telegram",
+        botId: identity.id,
+        username: identity.username,
+        apiBase: setup.apiBase,
+    });
+    if (!claim.ok) {
+        if (!setup.allowCrossInstance) {
+            return { ok: false, code: "bot-owned-elsewhere", message: claim.message };
+        }
+        // The deliberate case. It says what it is doing, and it does NOT record a
+        // second claim: the registry answers "who owns this bot", and two owners
+        // is the state it exists to report rather than a state to write down.
+        report(`approval: --allow-cross-instance: starting anyway — ${claim.message}`);
+        return { ok: true };
+    }
+    report(`approval: telegram ${identity.username} (bot id ${identity.id}) is this instance's own; no update was consumed by this check`);
+    return { ok: true };
+}
+/**
+ * What to append to a runtime 409, naming the other instance if one is known.
+ *
+ * Read at the moment of the conflict rather than captured at start-up, because
+ * the other gate may have claimed the bot in between: the registry is the only
+ * thing that knows, and it is cheap to re-read.
+ */
+export function conflictAdviceFor(setup) {
+    return () => {
+        const mine = ownedBot(setup.logPath, "telegram");
+        if (mine === null)
+            return null;
+        const others = otherOwnersOf(setup.logPath, mine.botId, mine.apiBase);
+        return others.length === 0
+            ? `this instance is ${mine.instanceHome} (instance ${mine.instanceId}) on ${mine.username}, and nothing else on this machine has claimed it — the other poller is on another machine, or was started outside this runtime`
+            : `${mine.instanceHome} (instance ${mine.instanceId}) and ${describeOwners(others)} have both claimed ${mine.username}; stop one of them`;
+    };
+}
 function payloadSource(resolved) {
     if (resolved === null)
         return { ok: true, source: undefined };
@@ -243,6 +328,21 @@ export const LISTEN_REFUSAL_CODES = [
     "log-unreadable",
     /** `--payloads` did not hold a JSON object of action key -> payload. */
     "payloads-unreadable",
+    /**
+     * A credential variable holds a value this instance did not configure
+     * (APRV-390): it was exported before the process started and is not this
+     * instance's own `approval env` export, or `.approval/env` names another
+     * instance's keystore item. Refused rather than warned since APRV-390 — the
+     * warning is what let a demo gate spend an evening on the production bot.
+     * `--allow-cross-instance` is the deliberate case.
+     */
+    "cross-instance-credential",
+    /**
+     * `getMe` named a bot another instance on this machine has already claimed
+     * (APRV-390). Refused BEFORE the first `getUpdates`, so the operator reads
+     * which two gates are involved instead of an HTTP 409 loop.
+     */
+    "bot-owned-elsewhere",
 ];
 /**
  * Everything that can fail without touching the network, in order.
@@ -280,6 +380,35 @@ export function prepareListen(request) {
             message: `telegram is not configured: ${missing.join(" and ")} ${missing.length === 1 ? "is" : "are"} unset or empty (both ${tokenEnv} and ${chatEnv} are required; APPROVAL.md carries only their names)`,
         };
     }
+    // APRV-390. WHOSE credentials are these? `instanceFindings` answers from
+    // names alone — no value is read, compared or printed — and until this task
+    // its answer was a warning `approval up` printed on the way past. It is a
+    // refusal now. The incident it is named after is a demo gate that started on
+    // the primary's exported token and long-polled the primary's bot: the
+    // warning was on the operator's terminal the whole time, above a process
+    // that had already started. An override exists because feeding a daemon from
+    // a shell profile is a deliberate, supported thing to do; what was missing
+    // is that it now has to be said out loud.
+    //
+    // `valueFindings` and not `instanceFindings`: this is the one caller that is
+    // about to USE the values, so it is allowed to resolve the file and compare
+    // (APRV-390, second round). Comparing is what tells a stale export — the
+    // shell holding a token the keychain has since replaced, which `approval env`
+    // will never override — from an honest one, and what stops the correct `eval
+    // "$(approval env)"` ritual being reported as a finding. `approval doctor`
+    // keeps the name-only rule, because a diagnostic may not block on an unlock
+    // dialog. No value is printed here or anywhere below.
+    const crossInstance = valueFindings(request.logPath, policyLoad, defaultSourceRunner);
+    if (crossInstance.length > 0 && request.allowCrossInstance !== true) {
+        const stale = crossInstance.some((finding) => finding.kind === "stale-export");
+        return {
+            ok: false,
+            code: "cross-instance-credential",
+            message: `${crossInstance.map((finding) => finding.detail).join("; ")}. ${stale
+                ? "A stale export is why a token re-stored in the keystore can still answer 401: `approval env` never overrides a variable this shell has already exported."
+                : "Two gates on one bot token both long-poll it, their getUpdates offsets acknowledge each other's updates, and an approval tap is answered by whichever listener asked first."} Fix it with one of: \`unset ${crossInstance.map((finding) => finding.variable).join(" ")}\` and then \`eval "$(approval env)"\` in this shell; a fresh shell that has never exported it; or \`approval setup channel telegram\` to give this instance its own bot. Pass --allow-cross-instance to start anyway`,
+        };
+    }
     const actor = resolveHumanActor(request.as === null ? {} : { actor: request.as });
     if (actor === null) {
         return {
@@ -342,6 +471,10 @@ export function prepareListen(request) {
             // asks of the policy file, and a policy that failed to load leaves the
             // default (paced) in force rather than a mode nobody chose.
             delivery: telegramDeliveryFor(policyLoad),
+            // APRV-390. Empty unless --allow-cross-instance let a finding through.
+            crossInstance,
+            allowCrossInstance: request.allowCrossInstance === true,
+            apiBase: request.apiBase ?? TELEGRAM_DEFAULT_API_BASE,
             gateOptions: { policy: request.policy },
             tagOptions: {
                 policy: request.policy,
@@ -458,6 +591,8 @@ function setUp(argv, streams, cwd) {
         pollTimeout: stringFlag(flags, "--poll-timeout"),
         once: boolFlag(flags, "--once"),
         json,
+        // APRV-390.
+        allowCrossInstance: boolFlag(flags, "--allow-cross-instance"),
         log: (message) => streams.err(`${message}\n`),
         // APRV-144, on by default, `--no-gloss` to turn it off (APRV-197).
         //
@@ -1569,7 +1704,10 @@ function handlerFor(setup, streams) {
             })}\n`);
         }
         else if (result.outcome.ok) {
-            streams.out(`${decision.decision === "grant" ? "granted" : "rejected"} ${decision.action_key} (seq ${result.outcome.record.seq}) by ${setup.actor} via telegram\n`);
+            // APRV-324: the actor off the RECORD, not the one this process was
+            // launched with. Under a sender mapping they differ, and the line a human
+            // reads on the operator's terminal has to say who the log says decided.
+            streams.out(`${decision.decision === "grant" ? "granted" : "rejected"} ${decision.action_key} (seq ${result.outcome.record.seq}) by ${result.outcome.record.actor} via telegram\n`);
         }
         else {
             streams.err(`approval: telegram decision refused (${result.outcome.code}): ${result.outcome.message}\n`);
@@ -1606,8 +1744,101 @@ function handlerFor(setup, streams) {
  * request here to reject, and a checkpoint that is owed is a warning at every
  * layer and a refusal at none.
  */
+/**
+ * Where this listener's policy lives, as `loadPolicy` wants it (APRV-324
+ * follow-up).
+ *
+ * The same location every gate operation this process performs resolves,
+ * because the handlers below ask the policy who a sender is and the gate asks
+ * it what a class resolves to, and two different files answering those two
+ * questions would be a listener enforcing one policy and attributing under
+ * another.
+ */
+function policyLoadOptions(setup) {
+    const policy = setup.gateOptions.policy;
+    if (policy?.file !== undefined)
+        return { file: policy.file };
+    if (policy?.dir !== undefined)
+        return { dir: policy.dir };
+    return {};
+}
+function senderIdentityFor(setup, sender) {
+    const load = loadPolicy(policyLoadOptions(setup));
+    if (sender === undefined)
+        return { ok: true, actor: setup.actor };
+    // APRV-370. The operator's sender key, and with it the form the two refusals
+    // below record the account in. Those two never reach the in-force mapping,
+    // so they take `recordedSenderFor`'s rule: the form follows the FILE, the
+    // mapping follows the ATTESTATION.
+    const key = senderKeyFrom();
+    if (load.ok) {
+        const read = readVerifiedRecords(setup.logPath);
+        if (!read.ok) {
+            return {
+                ok: false,
+                code: "policy-not-attested",
+                sender: recordedSenderFor(load, sender, key),
+                message: `the log could not be read to check whether ${load.source.filename} is attested (${read.code}): ${read.message}. Nothing was recorded; a decision made at a terminal carries no sender and is unaffected.`,
+            };
+        }
+        // `core/attest.ts`'s own check and its own wording, rather than a second
+        // comparison written here that could come to a different conclusion about
+        // the same file than the one the gate's refusal is built on.
+        const refusal = attestationRefusal(checkAttestation(read.records, load.source.path));
+        if (refusal !== null) {
+            return {
+                ok: false,
+                code: refusal.code,
+                sender: recordedSenderFor(load, sender, key),
+                message: `${refusal.message}. The sender mapping it declares is therefore not in force, so the account this gesture came from cannot be resolved against it and nothing was recorded. Re-attest the policy, or do this from a terminal, which authenticates no sender and is unaffected by the mapping.`,
+            };
+        }
+    }
+    return actorForSender(load, setup.actor, sender, key);
+}
+/**
+ * Record that a gesture this listener refused was made (APRV-355).
+ *
+ * Best-effort, and after the refusal is already decided: the card the person
+ * sees does not depend on this write landing. A failure is reported on stderr
+ * beside the refusal it was about, because a record that silently did not land
+ * is exactly the gap this task exists to close, and one that fails quietly is
+ * the same gap wearing a fix.
+ *
+ * The runtime cannot name a person on `sender-unmapped` or `sender-ambiguous`,
+ * which is the whole point of those refusals, so `actor` is the listener's
+ * configured identity ONLY where the resolution produced one. The observed
+ * account goes in either way; it is the only thing known about who tapped.
+ */
+function recordGestureRefusal(setup, streams, gesture, refused) {
+    const recorded = recordRefusedGesture(setup.logPath, {
+        gesture,
+        actor: null,
+        channel: "telegram",
+        sender: refused.sender,
+    }, { code: refused.code, message: refused.message }, setup.gateOptions);
+    if (!recorded.ok) {
+        streams.err(`approval: telegram ${gesture} refusal could not be recorded (${recorded.code}): ${recorded.message}\n`);
+    }
+}
 export function checkpointHandlerFor(setup, streams) {
     return (tap) => {
+        // APRV-324 follow-up, and FIRST, before the decline branch is even
+        // considered: a signature says this log's head is what this person saw, so
+        // an account the ATTESTED policy does not name may not produce one. Under
+        // no mapping this resolves to the configured identity and the whole branch
+        // is today's behaviour.
+        const resolved = senderIdentityFor(setup, tap.sender);
+        if (!resolved.ok) {
+            streams.err(`approval: telegram checkpoint refused (${resolved.code}): ${resolved.message}\n`);
+            recordGestureRefusal(setup, streams, "checkpoint-signature", resolved);
+            return {
+                ok: false,
+                headline: TELEGRAM_NOT_RECORDED,
+                detail: [refusedDecisionLine(resolved.code)],
+                toast: "Not signed.",
+            };
+        }
         if (!tap.sign) {
             return {
                 ok: true,
@@ -1619,7 +1850,7 @@ export function checkpointHandlerFor(setup, streams) {
                 toast: "Not now.",
             };
         }
-        const result = signCheckpointOffer(setup.checkpoint, tap.head, setup.actor, "telegram", process.cwd());
+        const result = signCheckpointOffer(setup.checkpoint, tap.head, resolved.actor, "telegram", process.cwd());
         const lines = checkpointSignedLines(result);
         const [headline, ...detail] = lines;
         if (setup.json) {
@@ -1632,7 +1863,7 @@ export function checkpointHandlerFor(setup, streams) {
             })}\n`);
         }
         else if (result.ok) {
-            streams.out(`checkpoint ${String(result.seq)}: signed head seq ${String(result.signed.seq)} ${result.signed.hash} by ${setup.actor} via telegram\n`);
+            streams.out(`checkpoint ${String(result.seq)}: signed head seq ${String(result.signed.seq)} ${result.signed.hash} by ${resolved.actor} via telegram\n`);
         }
         else {
             streams.err(`approval: telegram checkpoint refused (${result.code}): ${result.message}\n`);
@@ -1668,10 +1899,36 @@ export function checkpointHandlerFor(setup, streams) {
  */
 export function reviewHandlerFor(setup, streams) {
     return (tap) => {
-        const result = reviewSample(setup.logPath, { kind: "seq", seq: tap.sampleSeq }, setup.actor, tap.note ?? null, {
+        // APRV-324 follow-up. A review confers no authority and is still a HUMAN's
+        // observation: `approval feedback` hands it to agents as human-authored
+        // guidance, so a review attributed to the wrong person is guidance in
+        // somebody else's name. Resolved against the ATTESTED policy exactly as a
+        // signature is, and under no mapping this is the configured identity and
+        // today's behaviour.
+        const resolved = senderIdentityFor(setup, tap.sender);
+        if (!resolved.ok) {
+            streams.err(`approval: telegram review refused (${resolved.code}): ${resolved.message}\n`);
+            // `review-note` when the tap carried words: a note is attention spent
+            // writing rather than attention spent tapping, and an operator reading
+            // this record wants to know which they lost (APRV-355).
+            recordGestureRefusal(setup, streams, tap.note === undefined || tap.note.trim().length === 0 ? "review" : "review-note", resolved);
+            return {
+                ok: false,
+                headline: TELEGRAM_NOT_RECORDED,
+                detail: [refusedDecisionLine(resolved.code)],
+                toast: "Not recorded.",
+            };
+        }
+        const result = reviewSample(setup.logPath, { kind: "seq", seq: tap.sampleSeq }, resolved.actor, tap.note ?? null, {
             ...(setup.gateOptions.policy === undefined ? {} : { policy: setup.gateOptions.policy }),
             verdict: tap.verdict,
             ...(tap.reaction === undefined ? {} : { reaction: tap.reaction }),
+            ...(resolved.sender === undefined
+                ? {}
+                : {
+                    sender: resolved.sender,
+                    ...(resolved.source === undefined ? {} : { senderSource: resolved.source }),
+                }),
         });
         if (!result.ok) {
             // SPEC.md §11.1 invariant 6: the code is machine-readable and distinct,
@@ -1927,7 +2184,11 @@ export function startListener(setup, streams) {
         const beforePoll = async () => {
             reportCycle(await dispatchPending(setup, streams, state, new Date().toISOString()), streams);
         };
-        await channel.listen(setup.once ? { once: true, beforePoll } : { beforePoll });
+        // APRV-390. The 409's report reads the ownership registry at the moment
+        // the conflict happens; the channel prints what this returns and knows
+        // nothing about instances or files.
+        const conflictAdvice = conflictAdviceFor(setup);
+        await channel.listen(setup.once ? { once: true, beforePoll, conflictAdvice } : { beforePoll, conflictAdvice });
         if (setup.json) {
             streams.out(`${JSON.stringify({ event: "stopped", ...channel.stats() })}\n`);
         }
@@ -1936,6 +2197,16 @@ export function startListener(setup, streams) {
     return { done, stop };
 }
 async function runListener(setup, streams) {
+    // APRV-390. Before anything is delivered and before the first poll: whose
+    // bot is this? An override that got this far still owes the operator the
+    // sentence, because the whole point of `--allow-cross-instance` is that the
+    // deliberate case is deliberate out loud.
+    for (const finding of setup.crossInstance) {
+        streams.err(`approval: --allow-cross-instance: starting anyway — ${finding.detail}\n`);
+    }
+    const claimed = await claimListenerBot(setup, (message) => streams.err(`${message}\n`));
+    if (!claimed.ok)
+        return integrityError(streams, setup.json, claimed.message);
     const running = startListener(setup, streams);
     const stop = () => running.stop();
     process.on("SIGINT", stop);
@@ -1989,6 +2260,10 @@ export function commandTelegramHealth(argv, streams, cwd) {
     const parsed = parseFlags(argv, {
         "--policy": "string",
         "--dir": "string",
+        // APRV-390. Which instance's ownership record to read. Accepted here for
+        // the same reason `listen` accepts it: a gate may be configured with its
+        // log somewhere other than beside the policy.
+        "--log": "string",
         "--json": "boolean",
         "--help": "boolean",
         "-h": "boolean",
@@ -2013,6 +2288,19 @@ export function commandTelegramHealth(argv, streams, cwd) {
     const token = env(tokenEnv);
     const chatId = env(chatEnv);
     const ok = token !== null && chatId !== null;
+    // APRV-390. Which bot, and whose. Read from the two ownership records and
+    // never from the network: this verb makes no Bot API call on any path, and
+    // the last `getMe` a listener or a setup run made is already written down.
+    // An instance that has never started a listener has no record, which is a
+    // state and not a fault — the row says so rather than guessing.
+    const logPath = resolvePath(stringFlag(parsed.flags, "--log"), DEFAULT_LOG_PATH, dirFlag === null ? cwd : absolute(dirFlag, cwd));
+    const mine = ownedBot(logPath, "telegram");
+    const others = mine === null ? [] : otherOwnersOf(logPath, mine.botId, mine.apiBase);
+    const ownership = mine === null
+        ? "no bot recorded for this instance yet: it is written by the first `approval up` or `approval channel telegram listen` that reaches getMe"
+        : others.length === 0
+            ? `bot ${mine.username} (id ${mine.botId}) is owned by this instance, ${mine.instanceHome} (instance ${mine.instanceId}), recorded ${mine.claimedAt}`
+            : `bot ${mine.username} (id ${mine.botId}) is claimed by this instance AND by ${describeOwners(others)}; one of them must be given its own bot`;
     if (json) {
         streams.out(`${JSON.stringify({
             ok,
@@ -2022,10 +2310,20 @@ export function commandTelegramHealth(argv, streams, cwd) {
             token_set: token !== null,
             chat_env: chatEnv,
             chat_id: chatId,
+            // APRV-390. Names and ids, never a value.
+            bot_username: mine?.username ?? null,
+            bot_id: mine?.botId ?? null,
+            owner_instance: mine?.instanceId ?? null,
+            owner_home: mine?.instanceHome ?? null,
+            other_owners: others.map((claim) => ({
+                instance_id: claim.instanceId,
+                instance_home: claim.instanceHome,
+            })),
         })}\n`);
     }
     else if (ok) {
         streams.out(`telegram: configured (${tokenEnv} set, chat ${String(chatId)})\n`);
+        streams.out(`  ${ownership}\n`);
     }
     else {
         streams.err(`approval: telegram is not configured: ${[