baychat 0.38.0 → 0.40.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "baychat",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "displayName": "BayChat",
   "description": "Wakes this Claude Code session the moment a BayChat message arrives: no Monitor, no 30-minute deadline. Uses the baychat CLI already on this computer (npm install -g baychat, then baychat login).",
   "author": {

package/README.md

@@ -6,15 +6,20 @@
 
 **The BayChat connector.** Bring Claude Code, Codex, Cursor or an agent you built yourself into one
 group chat with you and your team. Your agents work together, ask before they act, and wait for your
-answer, from your phone if you're out. [baychat.io](https://baychat.io) · free with three agents.
+answer, from your phone if you're out. [baychat.io](https://baychat.io) · free with one agent.
 
-## Connect an agent in one line
+## One command
 
 ```bash
-npx baychat connect claude     # Claude Code   (also: codex · cursor · desktop)
+npx baychat
 ```
 
-The first time, it shows a QR: approve it in the BayChat app and this computer is yours. Then, inside
+The first time, it shows a QR: approve it in the BayChat app and this computer is yours. Then it sets up
+every agent app it finds on this computer (Claude Code, Claude Desktop, Codex, Cursor), lists what is
+ready, and starts a session when you run it inside a project folder. After that, `npx baychat` just starts
+a session. Installed another app later? `npx baychat setup` looks again.
+
+One app at a time still works: `npx baychat connect claude` (also `codex` · `cursor` · `desktop`). Inside
 Claude Code, join a room with `/baychat Scout "Launch week"`.
 
 **Your own agent**, anything that can run a shell command: in the app, *Add agent → Any agent via the CLI*

package/dist/approval-wait.js

@@ -53,7 +53,11 @@ async function askOwnerAndWait(device, ask, deadlineMs, deps, label) {
                 options: ask.options,
                 ...(ask.guardedOptions?.length ? { guardedOptions: ask.guardedOptions } : {}),
                 direct: true,
-                wait: holdSeconds(deadlineMs - deps.now()),
+                wait: deps.onCard ? 1 : holdSeconds(deadlineMs - deps.now()),
+                // When THIS process stops waiting (AGENT_STOP_UNDO.md T14): a Bay's undo window holds an
+                // answer only if it can still be delivered before then — otherwise the server sends it at
+                // once, so a short `--timeout` never turns a phone's "yes" into a deny. Older servers ignore it.
+                waitUntil: new Date(deadlineMs).toISOString(),
             });
         }
         catch (err) {
@@ -62,6 +66,12 @@ async function askOwnerAndWait(device, ask, deadlineMs, deps, label) {
         const requestId = typeof reply.requestId === "string" ? reply.requestId : "";
         if (!requestId)
             return { kind: "failed", reason: "BayChat did not return an approval id" };
+        try {
+            deps.onCard?.(requestId);
+        }
+        catch (err) {
+            deps.log(`${label}: could not note the card (${reasonOf(err)})`);
+        }
         // Wait. Re-arm across the bounded holds exactly as `await_approval` does. Marked while it
         // waits, so the relay's automatic update never restarts BayChat under an open question.
         const unmark = (0, waiting_cards_1.markWaitingCard)(requestId);
@@ -133,9 +143,11 @@ async function waitOnOwnerQuestion(device, requestId, deadlineMs, deps, label) {
  * effort and NEVER THROWS: a card left pending is harmless — the answer would reach nobody — so
  * a failure here is only logged.
  */
-async function withdrawOwnerQuestion(device, requestId, log) {
+async function withdrawOwnerQuestion(device, requestId, log, 
+/** "answered_elsewhere": it was answered in the session's own terminal — the card says so. */
+reason) {
     try {
-        await (0, api_1.apiRequest)(device, "POST", `/api/device-api/approvals/${encodeURIComponent(requestId)}/withdraw`, {});
+        await (0, api_1.apiRequest)(device, "POST", `/api/device-api/approvals/${encodeURIComponent(requestId)}/withdraw`, reason ? { reason } : {});
     }
     catch (err) {
         log(`could not withdraw the card ${requestId} (${reasonOf(err)})`);

package/dist/approve-hook.js

@@ -38,6 +38,8 @@ exports.allowDecision = allowDecision;
 exports.denyDecision = denyDecision;
 exports.describeToolRequest = describeToolRequest;
 exports.composeQuestion = composeQuestion;
+exports.answeredInTerminal = answeredInTerminal;
+exports.setHeldCardForTest = setHeldCardForTest;
 exports.decideApproval = decideApproval;
 exports.sessionFromClaude = sessionFromClaude;
 exports.linkFromClaude = linkFromClaude;
@@ -62,8 +64,9 @@ exports.cmdApproveHook = cmdApproveHook;
 // THE ONE RULE: EVERY PATH OUT OF HERE PRINTS A DECISION.
 // ─────────────────────────────────────────────────────────────────────────────────────────────
 //
-// Claude Code hooks FAIL OPEN. Verified against the current hooks reference, all of these mean
-// "the tool call proceeds through the normal permission flow":
+// A broken hook decides NOTHING. All of these render no decision, and Claude Code then shows its
+// own terminal permission prompt — the "normal permission flow" (a timeout and an exit 1 with
+// non-JSON output were tested 30 Oct with Claude Code 2.1.314: the prompt came up, nothing ran):
 //
 //   • the hook times out                    • it exits 1 (or any code but 2)
 //   • stdout is empty, or is not JSON       • stdout is JSON that fails schema validation
@@ -76,12 +79,14 @@ exports.cmdApproveHook = cmdApproveHook;
 // So the fail-closed guarantee is entirely this file's. Every abnormal path — no credential, DNS
 // failure, connection refused, 500, 401, unparseable body, ambiguous session, our own deadline,
 // an exception nobody predicted — is converted into an explicit DENY object and exit 0. There is
-// no `process.exit(1)` anywhere below, because exit 1 ALLOWS.
+// no `process.exit(1)` anywhere below: exit 1 decides nothing and leaves the terminal prompt, which
+// nobody at a phone can answer.
 //
 // Two consequences worth stating plainly:
 //
-//   1. OUR WAIT MUST END BEFORE THE HANDLER'S `timeout`. A hook that times out allows, so a
-//      deadline we control (which denies) must always be reached first. Hence
+//   1. OUR WAIT MUST END BEFORE THE HANDLER'S `timeout`. A hook that times out renders no
+//      decision (the terminal prompt comes back; tested 30 Oct with Claude Code 2.1.314), so a deadline we control,
+//      which denies explicitly and says why, must always be reached first. Hence
 //      DEFAULT_WAIT_SECONDS < RECOMMENDED_HANDLER_TIMEOUT_SECONDS, and the docs say to raise
 //      both together or neither.
 //   2. STDOUT IS THE DECISION CHANNEL. Nothing else may ever be written to it — "Stdout must
@@ -98,11 +103,13 @@ exports.cmdApproveHook = cmdApproveHook;
 //
 // The card itself never expires: the ApprovalRequest row stays PENDING for as long as it takes,
 // exactly like a terminal prompt. Our deadline bounds only how long THIS PROCESS waits, and it
-// exists solely because the alternative (being killed by the handler timeout) would allow.
+// exists because the alternative (being killed by the handler timeout) decides nothing: the
+// terminal prompt reappears with no word to the phone about why.
 const child_process_1 = require("child_process");
 const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const approval_wait_1 = require("./approval-wait");
+const card_key_1 = require("./card-key");
 const config_1 = require("./config");
 const hook_stdin_1 = require("./hook-stdin");
 const claude_link_1 = require("./channel/claude-link");
@@ -151,8 +158,8 @@ function denyClosed(reason) {
 /**
  * How long this process waits before denying, in seconds.
  *
- * An hour, not forever: the handler's own `timeout` would otherwise kill us first, and a
- * killed hook ALLOWS. This number and the `timeout` in settings.json are one setting in two
+ * An hour, not forever: the handler's own `timeout` would otherwise kill us first, and a killed
+ * hook decides nothing (the terminal prompt comes back; tested 30 Oct with Claude Code 2.1.314). This number and the `timeout` in settings.json are one setting in two
  * places — see the doc.
  */
 exports.DEFAULT_WAIT_SECONDS = 3600;
@@ -271,6 +278,45 @@ exports.APPROVE_OPTIONS = ["Allow this once", "Deny"];
 /** The ONLY index that means yes. Anything else — a second option, a third, an index the server
  *  invented — is a deny, so a mismatch between these labels and the answer can only fail safe. */
 const ALLOW_INDEX = 0;
+/**
+ * The card this process is waiting on right now, for `answeredInTerminal`: the credential, and the
+ * card's id once BayChat has made it. One hook run per process, so one card.
+ */
+let heldCard = null;
+/** How long a terminal answer waits for a card id still on its way, and for the withdrawal itself. */
+const SIGNAL_GRACE_MS = 2_000;
+/**
+ * Claude Code ended this hook mid-wait — measured on 2.1.316: a "No" at the terminal sends SIGTERM
+ * (a "Yes" leaves the hook parked; the after-hook closes that card). Close the card "answered at the
+ * computer" so it leaves Needs you, then the deny: EVERY PATH PRINTS A DECISION, even one Claude Code
+ * no longer reads. Bounded: a slow BayChat only leaves the card for "Mark done". NEVER THROWS.
+ */
+async function answeredInTerminal(deps = {}) {
+    try {
+        const held = heldCard;
+        if (held) {
+            const grace = deps.graceMs ?? SIGNAL_GRACE_MS;
+            const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+            // A card made in the hook's first second may not have its id yet.
+            for (let waited = 0; !held.cardId && waited < grace; waited += 100)
+                await sleep(100);
+            if (held.cardId) {
+                await Promise.race([
+                    (deps.withdraw ?? approval_wait_1.withdrawOwnerQuestion)(held.device, held.cardId, held.log, "answered_elsewhere"),
+                    sleep(grace),
+                ]);
+            }
+        }
+    }
+    catch {
+        // The deny below is the guarantee; the withdrawal is a courtesy to the phone.
+    }
+    return deny("it was answered in the terminal.");
+}
+/** Test seam: what `answeredInTerminal` would close. */
+function setHeldCardForTest(card) {
+    heldCard = card;
+}
 function parseArgs(argv) {
     const at = (name) => {
         const i = argv.indexOf(name);
@@ -328,13 +374,32 @@ async function decideApproval(rawStdin, argv = [], deps = {}) {
         // not "answered with index 0" becomes a deny below.
         // While the card is on the phone, notify-hook stays quiet for this session: one prompt, one
         // thing on the phone (notify-state.ts).
+        // The mark also names the call, and the card once it exists: answered at the keyboard instead,
+        // the after-hook closes it (card-after.ts), and a SIGTERM closes it here (`answeredInTerminal`).
         const claudeSession = str(input.session_id);
-        (0, notify_state_1.markCardPending)(claudeSession);
+        const key = (0, card_key_1.cardKeyOf)(toolName, input.tool_input);
+        (0, notify_state_1.markCardPending)(claudeSession, {}, key ? { key } : undefined);
+        heldCard = { device, cardId: undefined, log };
         let outcome;
         try {
-            outcome = await (0, approval_wait_1.askOwnerAndWait)(device, { session: opts.session, question, options: [...exports.APPROVE_OPTIONS] }, deadline, { now, sleep, log }, "baychat approve-hook");
+            outcome = await (0, approval_wait_1.askOwnerAndWait)(device, { session: opts.session, question, options: [...exports.APPROVE_OPTIONS] }, deadline, {
+                now,
+                sleep,
+                log,
+                onCard: (cardId) => {
+                    if (heldCard)
+                        heldCard.cardId = cardId;
+                    (0, notify_state_1.markCardPending)(claudeSession, {}, { cardId, key });
+                    // Already answered at the keyboard, before the card had an id: close it now. The wait
+                    // then sees "withdrawn" and this prints its deny.
+                    if (key && (0, notify_state_1.takeSettled)(claudeSession) === key) {
+                        void (deps.withdraw ?? approval_wait_1.withdrawOwnerQuestion)(device, cardId, log, "answered_elsewhere");
+                    }
+                },
+            }, "baychat approve-hook");
         }
         finally {
+            heldCard = null;
             (0, notify_state_1.clearCardPending)(claudeSession);
         }
         return verdictOf(outcome, opts.waitSeconds, isChained(toolName, input.tool_input));
@@ -366,7 +431,7 @@ function verdictOf(outcome, waitSeconds, chained = false) {
             return deny("the decision was withdrawn in BayChat without an answer.");
         case "deadline":
             return deny(`nobody answered within ${waitSeconds}s.`, "The decision card is still in BayChat; this call was refused because waiting longer " +
-                "would have let the hook time out, and a timed-out hook silently ALLOWS.");
+                "would have let the hook time out, which hands the decision back to the terminal prompt.");
         case "failed":
             return denyClosed(outcome.reason);
         case "unrecognised":
@@ -508,6 +573,20 @@ function noDecisionNotice(deps = {}) {
  * call PROCEEDS — so exiting 1 on failure would be precisely backwards.
  */
 async function cmdApproveHook(argv = [], stdin = process.stdin, deps = {}) {
+    // Ended mid-wait (a "No" at the terminal sends SIGTERM): close the card, then print the deny — once.
+    let printed = false;
+    const onSignal = () => {
+        if (printed)
+            return;
+        printed = true;
+        void answeredInTerminal().then((denied) => {
+            process.stdout.write(`${JSON.stringify(denied)}\n`);
+            process.exit(0);
+        });
+    };
+    const signals = ["SIGTERM", "SIGINT", "SIGHUP"];
+    for (const sig of signals)
+        process.on(sig, onSignal);
     let decision;
     try {
         decision = await decideApprovalOrDefer(await (0, hook_stdin_1.readStdin)(stdin), argv);
@@ -518,6 +597,12 @@ async function cmdApproveHook(argv = [], stdin = process.stdin, deps = {}) {
         process.stderr.write(`baychat approve-hook: ${err instanceof Error ? err.message : String(err)}\n`);
         decision = denyClosed("the approval gate could not run");
     }
+    for (const sig of signals)
+        process.off(sig, onSignal);
+    // A signal already printed its deny; one decision on stdout, never two.
+    if (printed)
+        return 0;
+    printed = true;
     // No decision: `--session-from-claude` with no session found — Claude Code's own dialog, plus a
     // line saying why when this is a channel session that lost its link.
     if (decision === null) {

package/dist/card-after.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.settleAnsweredCard = settleAnsweredCard;
+// The after-hook's half of "Needs you closes itself" (fix/needs-you-closes-itself, 2 Nov 2026).
+//
+// Measured on Claude Code 2.1.316: while approve-hook waits on its card, the terminal dialog is open
+// too. Answered "Yes" at the keyboard, the tool runs and PostToolUse fires — and approve-hook is NOT
+// stopped, so its card would stay in Needs you for up to an hour. Here the finished call is compared
+// with the session's pending card (notify-state.ts, written by approve-hook): the same call closes the
+// card "answered at the computer"; approve-hook then sees "withdrawn", prints its deny and leaves.
+//
+// It runs on every matching tool call (inside the async `denied-after` hook), so it reads ONE local
+// file first and touches the network only when that file names this very call. Loads no CLI.
+const approval_wait_1 = require("./approval-wait");
+const card_key_1 = require("./card-key");
+const config_1 = require("./config");
+const notify_state_1 = require("./notify-state");
+/** Close the session's card if THIS finished call is the one it asked about. NEVER THROWS. */
+async function settleAnsweredCard(input, deps = {}) {
+    const log = deps.log ?? ((line) => process.stderr.write(`${line}\n`));
+    try {
+        const call = (input && typeof input === "object" ? input : {});
+        const session = typeof call.session_id === "string" ? call.session_id : "";
+        if (!session)
+            return "none";
+        const pending = (0, notify_state_1.readPendingCard)(session, { dir: deps.dir });
+        if (!pending)
+            return "none";
+        const key = (0, card_key_1.cardKeyOf)(typeof call.tool_name === "string" ? call.tool_name : "", call.tool_input);
+        if (!key || pending.key !== key)
+            return "other-call";
+        if (!pending.cardId) {
+            // Answered at the keyboard before BayChat had even made the card: approve-hook closes it.
+            (0, notify_state_1.markSettled)(session, key, { dir: deps.dir });
+            return "settled-early";
+        }
+        const device = (deps.loadDevice ?? config_1.loadDeviceCredentials)();
+        if (!device)
+            return "none";
+        await (deps.withdraw ?? ((d, id) => (0, approval_wait_1.withdrawOwnerQuestion)(d, id, log, "answered_elsewhere")))(device, pending.cardId);
+        return "withdrawn";
+    }
+    catch (err) {
+        log(`baychat after-hook: could not close an answered card (${err instanceof Error ? err.message : String(err)})`);
+        return "none";
+    }
+}

package/dist/card-key.js

@@ -0,0 +1,27 @@
+"use strict";
+// Which call a permission card asks about, as a key both of Claude Code's events can produce
+// (fix/needs-you-closes-itself). The PermissionRequest hook gets no `tool_use_id` — only the tool and
+// its input — and PostToolUse gets the same two, so the key is built from those alone. Pure.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cardKeyOf = cardKeyOf;
+/** `Bash:<command>`; any other tool `<name>:<its input, keys sorted>`; undefined when it cannot be named. */
+function cardKeyOf(toolName, toolInput) {
+    if (!toolName)
+        return undefined;
+    const input = toolInput && typeof toolInput === "object" && !Array.isArray(toolInput) ? toolInput : {};
+    if (toolName === "Bash") {
+        // Only the command: Claude Code may add a description or a timeout on one side and not the other.
+        const command = typeof input.command === "string" ? input.command.trim() : "";
+        return command ? `Bash:${command}` : undefined;
+    }
+    return `${toolName}:${stable(input)}`;
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(",")}]`;
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stable(v)}`).join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}

package/dist/cli-help.js

@@ -19,10 +19,15 @@ Exit 0: step succeeded; 2: awaiting approval or expired; 1: error.
 exports.HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code, Codex)
 
 Usage:
-  baychat                               Start a session. This is the whole thing: it runs
-                                        your agent somewhere BayChat can reach, so /clear
-                                        and /new from the app work. Sign in once with
-                                        \`baychat login\` first
+  baychat                               Start a session: the one command. The first time it
+                                        signs this computer in (one QR on your phone) and sets
+                                        up every agent app it finds — Claude Code, Claude
+                                        Desktop, Codex, Cursor — then starts a session if you
+                                        are in a project folder. After that it just starts a
+                                        session, somewhere BayChat can reach, so /clear and
+                                        /new from the app work
+  baychat setup                         Look again and set up any agent app installed since;
+                                        starts nothing
   baychat start [name] [--runtime <runtime>]
                                         Start a session (what bare \`baychat\` does), with
                                         a name for it

package/dist/denied/after-hook.js

@@ -3,7 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.afterCall = afterCall;
 exports.cmdDeniedAfter = cmdDeniedAfter;
 // `baychat denied-after` — the PostToolUse / PostToolUseFailure hook that takes an "Allow once"
-// rule back out as soon as the retried call has run.
+// rule back out as soon as the retried call has run, and closes a permission card whose call was
+// answered at the keyboard instead (card-after.ts, fix/needs-you-closes-itself).
 //
 // It is installed beside `denied-hook` (relay/launcher/approval-settings.ts) as an ASYNC hook:
 // Claude Code starts it and moves on, so it adds nothing to any tool call's latency, and it prints
@@ -14,6 +15,7 @@ exports.cmdDeniedAfter = cmdDeniedAfter;
 // and every run here sweeps too — including a grant whose deferred confirmation never finished,
 // which is taken back and the owner told (confirm.ts; it loads only the card client and config,
 // no MCP SDK and none of the CLI's commands).
+const card_after_1 = require("../card-after");
 const hook_stdin_1 = require("../hook-stdin");
 const confirm_1 = require("./confirm");
 const grants_1 = require("./grants");
@@ -21,9 +23,12 @@ const permission_rule_1 = require("./permission-rule");
 /** Handle one finished call. NEVER THROWS; diagnostics go to stderr. */
 async function afterCall(rawStdin, log = defaultLog) {
     try {
+        const input = JSON.parse(rawStdin);
+        // A permission card answered at the keyboard instead: close it (card-after.ts — one local file
+        // read unless this very call has a card on the phone).
+        await (0, card_after_1.settleAnsweredCard)(input, { log });
         if (!(0, grants_1.hasGrantsToSweep)())
             return;
-        const input = JSON.parse(rawStdin);
         const call = typeof input.tool_name === "string" ? (0, permission_rule_1.callKeyOf)(input.tool_name, input.tool_input) : undefined;
         if (call && typeof input.session_id === "string")
             await (0, grants_1.consumeOnceGrants)(input.session_id, call);

package/dist/main.js

@@ -11,6 +11,7 @@ const notify_hook_1 = require("./notify-hook");
 const notify_answer_1 = require("./notify-answer");
 const session_name_1 = require("./session-name");
 const start_command_1 = require("./start-command");
+const setup_command_1 = require("./setup-command");
 const update_command_1 = require("./update-command");
 const notice_1 = require("./auto-update/notice");
 const session_command_1 = require("./session-command");
@@ -58,13 +59,14 @@ function numberFlag(args, name) {
 }
 async function main() {
     const [command, ...args] = process.argv.slice(2);
-    // BARE `baychat` STARTS A SESSION. The bar is "download BayChat, start a session, nothing
-    // else", and a usage dump printed at somebody who typed the product's own name is the
-    // "something else". `--help` still prints the help, and `start` refuses with one sentence
-    // when this machine is not signed in, so nothing is launched from an unusable state.
+    // BARE `baychat` IS THE ONE COMMAND (31 Oct 2026, setup-command.ts). The first time it signs this
+    // computer in once and sets up every agent app it finds, then starts a session — only inside a
+    // project, never in the home folder. Once set up it starts straight away, as it always did. A usage
+    // dump printed at somebody who typed the product's own name would be "something else"; `--help`
+    // still prints the help.
     if (command === undefined) {
         (0, notice_1.printUpdateNotice)(command);
-        return (0, start_command_1.cmdStart)([]);
+        return (0, setup_command_1.runBare)((0, setup_command_1.realSetupDeps)());
     }
     // "BayChat updated itself to …": the relay's one line for the terminal, shown once, on a command
     // a person typed (never into a hook's or an MCP server's output).
@@ -85,6 +87,10 @@ async function main() {
             return (0, session_command_1.cmdJoinSession)(args);
         case "start":
             return (0, start_command_1.cmdStart)(args);
+        case "setup":
+            // Look again and set up what is new (an app installed since); starts nothing.
+            (0, args_1.rejectUnknownFlags)(args, [], "baychat setup");
+            return (0, setup_command_1.runSetupCommand)((0, setup_command_1.realSetupDeps)());
         case "update":
             // `--quiet` is how an old version hands a `start`-driven update to the new one.
             (0, args_1.rejectUnknownFlags)(args, ["--quiet", "--auto"], "baychat update [--auto on|off]");

package/dist/notify-state.js

@@ -36,7 +36,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.notifyStateDir = void 0;
 exports.stateKey = stateKey;
 exports.markCardPending = markCardPending;
+exports.readPendingCard = readPendingCard;
 exports.clearCardPending = clearCardPending;
+exports.markSettled = markSettled;
+exports.takeSettled = takeSettled;
 exports.cardPendingSince = cardPendingSince;
 exports.readLastNotice = readLastNotice;
 exports.writeLastNotice = writeLastNotice;
@@ -74,18 +77,48 @@ function file(sessionId, ext, dir) {
         return undefined;
     }
 }
-function markCardPending(sessionId, opts = {}) {
+function markCardPending(sessionId, opts = {}, card) {
     const f = file(sessionId, "card", opts.dir);
     if (!f)
         return;
     try {
         fs.mkdirSync(path.dirname(f), { recursive: true, mode: 0o700 });
-        fs.writeFileSync(f, String((opts.now ?? Date.now)()), { mode: 0o600 });
+        const at = (opts.now ?? Date.now)();
+        const body = card ? JSON.stringify({ at, ...(card.cardId ? { cardId: card.cardId } : {}), ...(card.key ? { key: card.key } : {}) }) : String(at);
+        fs.writeFileSync(f, body, { mode: 0o600 });
     }
     catch {
         // Bookkeeping only.
     }
 }
+/** The session's pending card, or undefined when there is none (or the mark is unreadable). */
+function readPendingCard(sessionId, opts = {}) {
+    const f = file(sessionId, "card", opts.dir);
+    if (!f)
+        return undefined;
+    let raw;
+    try {
+        raw = fs.readFileSync(f, "utf8").trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (/^\d+$/.test(raw))
+        return { at: Number(raw) };
+    try {
+        const v = JSON.parse(raw);
+        if (typeof v.at !== "number" || !Number.isFinite(v.at))
+            return undefined;
+        return {
+            at: v.at,
+            ...(typeof v.cardId === "string" && v.cardId ? { cardId: v.cardId } : {}),
+            ...(typeof v.key === "string" && v.key ? { key: v.key } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 function clearCardPending(sessionId, opts = {}) {
     const f = file(sessionId, "card", opts.dir);
     if (!f)
@@ -97,19 +130,41 @@ function clearCardPending(sessionId, opts = {}) {
         // Bookkeeping only.
     }
 }
-/** When the pending card was marked, or undefined when there is none. */
-function cardPendingSince(sessionId, opts = {}) {
-    const f = file(sessionId, "card", opts.dir);
+/**
+ * `<session_id>.settled` — the after-hook saw the call run while the card had no id yet (answered at
+ * the keyboard within the hook's first second). approve-hook takes it once it has the id and closes
+ * the card itself. Holds the call's key; read once and removed.
+ */
+function markSettled(sessionId, key, opts = {}) {
+    const f = file(sessionId, "settled", opts.dir);
+    if (!f)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(f), { recursive: true, mode: 0o700 });
+        fs.writeFileSync(f, key, { mode: 0o600 });
+    }
+    catch {
+        // Bookkeeping only: at worst the card waits for "Mark done".
+    }
+}
+/** The settled call's key, removed as it is read; undefined when there is none. */
+function takeSettled(sessionId, opts = {}) {
+    const f = file(sessionId, "settled", opts.dir);
     if (!f)
         return undefined;
     try {
-        const at = Number(fs.readFileSync(f, "utf8").trim());
-        return Number.isFinite(at) ? at : undefined;
+        const key = fs.readFileSync(f, "utf8");
+        fs.rmSync(f, { force: true });
+        return key || undefined;
     }
     catch {
         return undefined;
     }
 }
+/** When the pending card was marked, or undefined when there is none. */
+function cardPendingSince(sessionId, opts = {}) {
+    return readPendingCard(sessionId, opts)?.at;
+}
 function readLastNotice(sessionId, opts = {}) {
     const f = file(sessionId, "json", opts.dir);
     if (!f)