botmux 3.10.0 → 3.11.0

package/dist/core/ask-broker.js

@@ -9,8 +9,38 @@
  */
 import { randomUUID } from 'node:crypto';
 import { logger } from '../utils/logger.js';
+import { askKeyFor, dispatchUuidForKey, HANDOFF_RETENTION_MS, } from './ask-persist-store.js';
+import { AskDispatchError } from './ask-types.js';
+/** Origins for which restart-resume + durable handoff are enabled. Only a
+ *  caller that has a reconnecting claimant after a daemon restart may persist:
+ *  the hook process survives in the CLI's tmux/persistent-backend session and
+ *  re-POSTs with the same requestId. An explicit `botmux ask buttons` CLI exits
+ *  on restart (no claimant) and a PTY-backend hook doesn't survive, so those
+ *  must NOT persist/handoff — else they leave orphan records (codex P1-4). */
+const RESUMABLE_ORIGINS = new Set(['hook']);
 const pending = new Map();
 let dispatcher = null;
+/** Injected durable store (codex P1-4: no global-dataDir reads from the broker).
+ *  Wired once at daemon bootstrap via setAskPersistStore; null → persistence is
+ *  a no-op (unit tests that don't exercise restart-resume需要绑定各自 temp
+ *  store，绝不回落到全局目录). */
+let persistStore = null;
+/** Effective handoff-retention window. Defaults to the durable-store constant;
+ *  a test may shrink it via `_setHandoffRetentionForTest` so the absolute-expiry
+ *  reaper (codex P1-4) can be exercised with real timers instead of a 24h wait
+ *  or fake-timer gymnastics around the async dispatch loop. */
+let handoffRetentionMs = HANDOFF_RETENTION_MS;
+/** Wire the durable persist store. Called once at daemon bootstrap with the
+ *  real dir; tests inject a temp store (and only clean their own sentinel dir). */
+export function setAskPersistStore(store) {
+    persistStore = store;
+}
+/** Shrink the handoff-retention window — for tests only, so the absolute-expiry
+ *  reaper (codex P1-4) can be verified with a short real timer. Restored to the
+ *  default by `_resetForTest`. */
+export function _setHandoffRetentionForTest(ms) {
+    handoffRetentionMs = ms;
+}
 /** IM-side canTalk predicate, wired by the daemon at bootstrap. Lets the broker
  *  honour the bot's canTalk gate without importing Lark types: whoever may
  *  address the bot in this chat may answer its `botmux ask`. Returns false until
@@ -57,29 +87,82 @@ export function registerAsk(input) {
     if (!dispatcher) {
         throw new Error('ask-broker: cardDispatcher not wired — daemon bootstrap bug');
     }
+    const originKind = input.originKind ?? 'hook';
+    // Resumability is gated by TWO independent facts (codex P1-4):
+    //  1. the origin has a reconnecting claimant (only 'hook' re-POSTs after a
+    //     restart; an explicit `botmux ask buttons` process exits), AND
+    //  2. the issuing session's backend actually SURVIVES a daemon restart —
+    //     computed by the daemon from the authenticated session's frozen backend
+    //     (tmux/herdr/zellij/zmx), NOT trusted from the client. A PTY-backed hook
+    //     dies with the daemon, so persisting it would orphan a record no one can
+    //     ever re-claim. Undefined backend signal → false (fail closed).
+    // A caller-supplied requestId is still required (it's the re-attach identity).
+    const resumable = RESUMABLE_ORIGINS.has(originKind) &&
+        input.requestId !== undefined &&
+        input.backendSurvivesRestart === true;
+    // Invocation identity: prefer the caller-supplied requestId (hook generates it
+    // once and reuses it across reconnect retries). A caller without one (explicit
+    // `botmux ask buttons`) gets a synthesized id and is NOT resumable — it has no
+    // reconnecting claimant, so persisting/handing off would orphan (codex P1-4).
+    const requestId = input.requestId ?? randomUUID();
+    // Identity is SCOPED to the authenticated (larkAppId, sessionId): a requestId
+    // is an idempotency id, never a bearer secret — a different session reusing it
+    // lands on a different key and can't reclaim this ask (codex P1-3).
+    const askKey = askKeyFor(input.larkAppId, input.sessionId, originKind, requestId);
+    // Same-key handling — covers ALL states of an existing entry with this key
+    // (codex P1-1). The scoped key already pins (app/session/origin/request); here
+    // we additionally require the FULL immutable identity (chat/root/questions) to
+    // match before joining/replaying/re-attaching.
+    const existing = findByKey(askKey);
+    if (existing) {
+        if (sameIdentity(existing, input)) {
+            // active (still awaiting a click): add another waiter → both callers get the
+            // one result; no second ask, no second card.
+            if (!existing.settled && !existing.dormant) {
+                logger.info?.(`ask-broker: active replay joined ask ${existing.askId} (key=${askKey})`);
+                return new Promise((resolve) => { existing.waiters.push(resolve); });
+            }
+            // recent-terminal (settled, still retained): return the same terminal result.
+            if (existing.settled && existing.terminalResult && !existing.dormant) {
+                logger.info?.(`ask-broker: replay returned retained terminal result for ${existing.askId}`);
+                return Promise.resolve(existing.terminalResult);
+            }
+            // dormant (restored after restart): re-attach (handoff or fresh waiter).
+            if (existing.dormant) {
+                return reattachByRequest(existing);
+            }
+        }
+        else {
+            // Same key, DIFFERENT immutable identity (crafted / stale-but-mutated
+            // re-POST). FAIL CLOSED (codex P1-2): never fall through to a second ask —
+            // that would post an ambiguous second card and a click could resolve
+            // either. The caller gets a terminal `invalidated` and no card is sent.
+            logger.warn?.(`ask-broker: identity mismatch on key ${askKey} (existing ask ${existing.askId}) — rejecting re-register`);
+            return Promise.resolve({
+                kind: 'invalidated',
+                reason: 'ask identity mismatch (same key, different question set / chat)',
+                selected: null, by: null, comment: null, timedOut: false,
+            });
+        }
+    }
     const askId = randomUUID();
     const nonce = randomUUID().slice(0, 8);
     const createdAt = Date.now();
     const deadlineAt = createdAt + input.timeoutMs;
     return new Promise((resolve) => {
         const timeoutHandle = setTimeout(() => {
-            settle(askId, {
-                kind: 'timedOut',
-                selected: null,
-                by: null,
-                comment: null,
-                timedOut: true,
-            });
+            settle(askId, { kind: 'timedOut', selected: null, by: null, comment: null, timedOut: true });
         }, input.timeoutMs);
-        // Don't keep the event loop alive just because an ask is pending.
         timeoutHandle.unref?.();
-        // 为每个问题初始化空的勾选集合
         const selections = new Map();
-        for (let i = 0; i < input.questions.length; i++) {
+        for (let i = 0; i < input.questions.length; i++)
             selections.set(i, new Set());
-        }
         const ask = {
             askId,
+            askKey,
+            requestId,
+            originKind,
+            resumable,
             nonce,
             larkAppId: input.larkAppId,
             chatId: input.chatId,
@@ -90,33 +173,180 @@ export function registerAsk(input) {
             createdAt,
             deadlineAt,
             settled: false,
-            resolve,
+            waiters: [resolve],
             timeoutHandle,
             selections,
         };
         pending.set(askId, ask);
-        // Card dispatch is async — store the messageId once it lands.
-        void dispatcher
-            .send(snapshot(ask))
-            .then(({ messageId }) => {
-            const cur = pending.get(askId);
-            if (cur && !cur.settled)
-                cur.cardMessageId = messageId;
-        })
-            .catch((err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            logger.warn?.(`ask-broker: ${askId} card dispatch failed: ${msg}`);
-            settle(askId, {
-                kind: 'invalidated',
-                reason: `card dispatch failed: ${msg}`,
-                selected: null,
-                by: null,
-                comment: null,
-                timedOut: false,
-            });
-        });
+        // Persist ONLY resumable origins (codex P1-4). A restart before the card
+        // lands still leaves a resumable record; restore/re-attach re-sends.
+        if (resumable) {
+            persistFromInternal(ask);
+            logger.info?.(`ask-broker: registered + persisted ask ${askId} (key=${askKey}, session=${input.sessionId})`);
+        }
+        void sendCardForAsk(ask);
+    });
+}
+/** Immutable-identity equality: a reattach/replay must match the ORIGINAL ask on
+ *  every caller-independent field, not just the (already-scoped) key. Guards
+ *  against a stale/crafted requestId landing on a mismatched ask (codex P1-3). */
+function sameIdentity(ask, input) {
+    return (ask.larkAppId === input.larkAppId &&
+        ask.sessionId === input.sessionId &&
+        ask.chatId === input.chatId &&
+        ask.rootMessageId === input.rootMessageId &&
+        ask.originKind === (input.originKind ?? 'hook') &&
+        questionsShape(ask.questions) === questionsShape(input.questions));
+}
+/** Stable shape string for question-set equality (prompt + multiSelect + each
+ *  option's key AND label, order-sensitive). Two question sets that would render
+ *  a DIFFERENT card to the user — including a relabelled option whose key is
+ *  unchanged — must not re-attach/replay (codex P1-2). */
+function questionsShape(qs) {
+    return JSON.stringify(qs.map((q) => ({
+        p: q.prompt,
+        m: !!q.multiSelect,
+        o: q.options.map((o) => [o.key, o.label]),
+    })));
+}
+/** Max card (re-)dispatch attempts on transient failures before giving up and
+ *  invalidating. Small: a card send is a single Feishu POST; if a handful of
+ *  attempts across a few seconds all fail transiently, the chat is unreachable
+ *  and waiting longer won't help. */
+const CARD_DISPATCH_MAX_ATTEMPTS = 4;
+/** Base backoff between transient re-sends (linear: base × attempt, capped). */
+const CARD_DISPATCH_BACKOFF_MS = 500;
+const CARD_DISPATCH_BACKOFF_CAP_MS = 4_000;
+/** Dispatch (or idempotently re-dispatch) the card and record its messageId. The
+ *  dispatcher gets a stable `dispatchUuid` (derived from the scoped key) so any
+ *  re-send — a bounded transient retry here, or a restart re-attach — returns the
+ *  ORIGINAL message_id instead of posting a duplicate (codex P1-1/P1-3).
+ *
+ *  Retry policy (codex P1-3 partial-success): a `retryable` AskDispatchError
+ *  (5xx/429/network) is retried up to CARD_DISPATCH_MAX_ATTEMPTS with linear
+ *  backoff, reusing the SAME uuid — so a send that landed server-side before the
+ *  socket broke converges to one logical card. A non-retryable error
+ *  (deterministic 4xx / withdrawn) — or a plain untyped throw (fail closed) —
+ *  invalidates immediately. */
+function sendCardForAsk(ask) {
+    void (async () => {
+        for (let attempt = 1; attempt <= CARD_DISPATCH_MAX_ATTEMPTS; attempt++) {
+            // Bail if the ask settled out from under us (timeout / invalidate / a click
+            // on a restored dormant card) — nothing left to dispatch.
+            const live = pending.get(ask.askId);
+            if (!live || live.settled)
+                return;
+            try {
+                const { messageId } = await dispatcher.send(snapshot(ask));
+                const cur = pending.get(ask.askId);
+                if (cur && !cur.settled) {
+                    cur.cardMessageId = messageId;
+                    if (cur.resumable)
+                        persistFromInternal(cur);
+                }
+                return; // sent (or server-deduped to the original) — done
+            }
+            catch (err) {
+                const retryable = err instanceof AskDispatchError && err.retryable;
+                const msg = err instanceof Error ? err.message : String(err);
+                if (retryable && attempt < CARD_DISPATCH_MAX_ATTEMPTS) {
+                    const backoff = Math.min(CARD_DISPATCH_BACKOFF_MS * attempt, CARD_DISPATCH_BACKOFF_CAP_MS);
+                    logger.warn?.(`ask-broker: ${ask.askId} card dispatch attempt ${attempt} failed (transient): ${msg} — retrying in ${backoff}ms`);
+                    await sleep(backoff);
+                    continue;
+                }
+                // Deterministic failure, exhausted retries, or an untyped throw (fail
+                // closed): invalidate so the blocked CLI unblocks instead of hanging.
+                logger.warn?.(`ask-broker: ${ask.askId} card dispatch failed (${retryable ? 'transient, retries exhausted' : 'not retryable'}): ${msg}`);
+                settle(ask.askId, {
+                    kind: 'invalidated', reason: `card dispatch failed: ${msg}`,
+                    selected: null, by: null, comment: null, timedOut: false,
+                });
+                return;
+            }
+        }
+    })();
+}
+/** Promise-based sleep whose timer never keeps the process alive (unref). */
+function sleep(ms) {
+    return new Promise((resolve) => {
+        const h = setTimeout(resolve, ms);
+        h.unref?.();
+    });
+}
+/** Find an entry by its scoped stable key (any state). */
+function findByKey(askKey) {
+    for (const ask of pending.values())
+        if (ask.askKey === askKey)
+            return ask;
+    return undefined;
+}
+/**
+ * Re-attach a reconnecting hook to a restored DORMANT ask. Two cases:
+ *  - answer already stashed (click → reattach): deliver the durable-handoff
+ *    result immediately, settle, remove the persisted record. No new card/timer.
+ *  - still awaiting a click: install a waiter + timeout re-armed to the ORIGINAL
+ *    absolute deadline; re-send the card if it was never confirmed sent.
+ */
+function reattachByRequest(ask) {
+    if (ask.answeredResult) {
+        const result = ask.answeredResult;
+        ask.dormant = false;
+        ask.settled = true;
+        ask.settledAt = Date.now();
+        ask.terminalResult = result;
+        clearTimeout(ask.timeoutHandle);
+        clearTimeout(ask.handoffExpiryHandle); // claimed → cancel the unclaimed-stash reaper
+        persistStore?.remove(ask.askKey); // claimed → durable record no longer needed
+        gcSettled();
+        logger.info?.(`ask-broker: re-attach delivered stashed answer for ask ${ask.askId} (key=${ask.askKey})`);
+        return Promise.resolve(result);
+    }
+    return new Promise((resolve) => {
+        ask.dormant = false;
+        ask.waiters.push(resolve);
+        clearTimeout(ask.timeoutHandle);
+        const remaining = Math.max(0, ask.deadlineAt - Date.now());
+        ask.timeoutHandle = setTimeout(() => {
+            settle(ask.askId, { kind: 'timedOut', selected: null, by: null, comment: null, timedOut: true });
+        }, remaining);
+        ask.timeoutHandle.unref?.();
+        logger.info?.(`ask-broker: re-attached hook to restored ask ${ask.askId} (key=${ask.askKey}, ` +
+            `${Math.round(remaining / 1000)}s left, card=${ask.cardMessageId ? 'live' : 'MISSING→resend'})`);
+        if (!ask.cardMessageId)
+            sendCardForAsk(ask);
     });
 }
+/** Build the persisted projection from a live internal ask and write it. Only
+ *  called for resumable asks. */
+function persistFromInternal(ask) {
+    if (!persistStore || !ask.resumable)
+        return;
+    // A settled ask with a stashed answer is a durable handoff that must be KEPT
+    // until claimed; a settled ask without one has nothing left to resume.
+    if (ask.settled && !ask.answeredResult)
+        return;
+    const persisted = {
+        v: 2,
+        askKey: ask.askKey,
+        requestId: ask.requestId,
+        originKind: ask.originKind,
+        askId: ask.askId,
+        nonce: ask.nonce,
+        larkAppId: ask.larkAppId,
+        chatId: ask.chatId,
+        rootMessageId: ask.rootMessageId,
+        sessionId: ask.sessionId,
+        chatType: ask.chatType,
+        questions: ask.questions,
+        createdAt: ask.createdAt,
+        deadlineAt: ask.deadlineAt,
+        cardMessageId: ask.cardMessageId,
+        selections: ask.questions.map((_, i) => [...(ask.selections.get(i) ?? new Set())]),
+        ...(ask.answeredResult ? { answeredResult: ask.answeredResult, answeredAt: ask.settledAt ?? Date.now() } : {}),
+    };
+    persistStore.put(persisted);
+}
 /**
  * 勾选/取消勾选某问题的某个选项（累积模式，不 settle）。
  *
@@ -159,6 +389,9 @@ export function toggleAsk(args) {
         sel.clear();
         sel.add(args.key);
     }
+    // Persist the updated checkbox state so a restart mid-multi-select keeps the
+    // boxes the user already ticked (best-effort; never blocks the toggle).
+    persistFromInternal(ask);
     return 'toggled';
 }
 /**
@@ -322,6 +555,105 @@ export function invalidateAll(reason) {
     }
     return ids.length;
 }
+/**
+ * Restore pending asks from disk after a daemon restart. Each becomes a DORMANT
+ * entry: its card is still live in Feishu (we do NOT re-post — cardMessageId is
+ * preserved), so a click can settle it, but there is no waiter Promise until the
+ * surviving CLI hook reconnects and re-registers (findDormantByKey →
+ * reattachDormantAsk installs a fresh resolve). Each dormant ask arms a timer to
+ * its ORIGINAL absolute deadline so it can't linger forever if the CLI never
+ * comes back. Called once during daemon bootstrap. Returns the count restored.
+ *
+ * Idempotent-ish: an askKey already present (e.g. re-invoked) is skipped.
+ */
+export function restorePersistedAsks(now = Date.now(), larkAppId) {
+    let restored = 0;
+    if (!persistStore) {
+        logger.info?.('ask-broker: restore sweep skipped — no persist store wired');
+        return 0;
+    }
+    for (const p of persistStore.list(now)) {
+        // One bot per daemon process: only restore asks this daemon can actually
+        // serve (its own bot's sessions). Another bot's daemon owns the rest.
+        if (larkAppId && p.larkAppId !== larkAppId)
+            continue;
+        // Skip if this key is already live (defensive — boot runs once).
+        let dup = false;
+        for (const a of pending.values())
+            if (a.askKey === p.askKey && !a.settled) {
+                dup = true;
+                break;
+            }
+        if (dup)
+            continue;
+        const selections = new Map();
+        for (let i = 0; i < p.questions.length; i++) {
+            selections.set(i, new Set(p.selections?.[i] ?? []));
+        }
+        const hasStashedAnswer = p.answeredResult !== undefined;
+        // A stashed-answer restore is already terminal (settled), awaiting only the
+        // hook's claim — it must NOT arm a deadline timer (there's nothing left to
+        // time out). A still-awaiting-click restore arms the ORIGINAL absolute
+        // deadline so it can't linger forever if the CLI never returns.
+        const remaining = Math.max(0, p.deadlineAt - now);
+        const timeoutHandle = hasStashedAnswer
+            ? undefined
+            : setTimeout(() => {
+                settle(p.askId, {
+                    kind: 'timedOut', selected: null, by: null, comment: null, timedOut: true,
+                });
+            }, remaining);
+        timeoutHandle?.unref?.();
+        const ask = {
+            askId: p.askId,
+            askKey: p.askKey,
+            requestId: p.requestId,
+            originKind: p.originKind,
+            resumable: true, // only resumable origins were ever persisted
+            nonce: p.nonce,
+            larkAppId: p.larkAppId,
+            chatId: p.chatId,
+            rootMessageId: p.rootMessageId,
+            sessionId: p.sessionId,
+            chatType: p.chatType,
+            questions: p.questions,
+            createdAt: p.createdAt,
+            deadlineAt: p.deadlineAt,
+            cardMessageId: p.cardMessageId,
+            // A stashed-answer restore is terminal-but-unclaimed: settled=true so
+            // gcSettled/other paths treat it as done, dormant=true so a hook re-POST
+            // routes to reattachByRequest to CLAIM it.
+            settled: hasStashedAnswer,
+            settledAt: hasStashedAnswer ? (p.answeredAt ?? now) : undefined,
+            dormant: true,
+            waiters: [], // attached when the reconnecting hook re-registers
+            // Carry a stashed answer forward (user answered before restart): the
+            // reconnecting hook claims it via reattachByRequest.
+            ...(p.answeredResult ? { answeredResult: p.answeredResult, terminalResult: p.answeredResult } : {}),
+            // timeoutHandle is only meaningful for the awaiting-click case; a stashed
+            // restore uses a no-op cleared handle so clearTimeout calls stay safe.
+            timeoutHandle: timeoutHandle ?? setTimeout(() => { }, 0),
+            selections,
+        };
+        if (timeoutHandle === undefined) {
+            clearTimeout(ask.timeoutHandle);
+        }
+        pending.set(p.askId, ask);
+        // Re-arm the absolute handoff-expiry reaper for a restored stash (codex
+        // P1-4): a SECOND restart before the hook claims must still reap memory +
+        // disk at the ORIGINAL answeredAt + retention, not restart the clock.
+        if (hasStashedAnswer)
+            armHandoffExpiry(ask);
+        restored++;
+        logger.info?.(`ask-broker: restored pending ask ${p.askId} (key=${p.askKey}, session=${p.sessionId}, ` +
+            `dormant${p.answeredResult ? '+answered' : ''}, ${Math.round((p.deadlineAt - now) / 1000)}s left) — awaiting hook re-attach`);
+    }
+    // Always log the boot sweep outcome (even 0) so a live restart test can
+    // confirm the restore path ran, not just infer it from behaviour.
+    logger.info?.(`ask-broker: restore sweep complete — ${restored} pending ask(s) restored` +
+        (larkAppId ? ` for ${larkAppId}` : ''));
+    return restored;
+}
 /** Internal — settle an ask exactly once and notify the dispatcher's onSettle
  *  hook (best-effort, never blocks broker state transitions). The settled
  *  entry stays in the map for `SETTLED_RETENTION_MS` so late race-losers get
@@ -330,48 +662,129 @@ function settle(askId, result) {
     const ask = pending.get(askId);
     if (!ask || ask.settled)
         return;
+    // Durable handoff (codex P1-1): a dormant ask (restored after a restart, no
+    // waiter yet) that receives an ANSWER must NOT drop it into the void. Stash
+    // the terminal result and KEEP the persisted record so the reconnecting hook
+    // can claim it (reattachDormantAsk delivers + removes). Only answered results
+    // are worth stashing — a dormant ask that timed out / was invalidated has no
+    // consumer to hand off to, so it settles+cleans normally.
+    if (ask.dormant && ask.waiters.length === 0 && result.kind === 'answered') {
+        ask.settled = true;
+        ask.settledAt = Date.now();
+        ask.answeredResult = result;
+        ask.terminalResult = result;
+        clearTimeout(ask.timeoutHandle);
+        persistFromInternal(ask); // re-persist WITH answeredResult + answeredAt (kept until claimed)
+        // Arm the absolute handoff-expiry timer (codex P1-4): if the reconnecting
+        // hook never claims this stash (CLI gone for good), reap memory + disk
+        // TOGETHER at answeredAt + HANDOFF_RETENTION_MS — not just on the next boot
+        // list() sweep, which a long-running daemon never performs.
+        armHandoffExpiry(ask);
+        logger.info?.(`ask-broker: stashed answer for dormant ask ${askId} (key=${ask.askKey}) — awaiting hook claim`);
+        // Still notify the card layer so the Feishu card flips to its settled view.
+        notifyOnSettle(ask, result);
+        return;
+    }
     ask.settled = true;
     ask.settledAt = Date.now();
+    ask.terminalResult = result; // retained for a same-requestId replay in the ambiguous window
     clearTimeout(ask.timeoutHandle);
+    // The durable record's job is done the moment the ask leaves the pending
+    // state (delivered to live waiters, or a terminal non-answer) — drop it so a
+    // later restart doesn't resurrect a settled ask.
+    persistStore?.remove(ask.askKey);
     // Reap older settled entries opportunistically — keeps the map bounded
     // without paying for a dedicated GC timer.
     gcSettled();
-    try {
-        ask.resolve(result);
-    }
-    catch (err) {
-        logger.warn?.(`ask-broker: ${askId} resolve threw: ${err instanceof Error ? err.message : String(err)}`);
-    }
-    if (dispatcher?.onSettle) {
+    // Resolve every waiter (normally one; >1 when a same-requestId active replay
+    // joined). A dormant ask has no waiters — the loop simply no-ops.
+    const waiters = ask.waiters;
+    ask.waiters = [];
+    for (const w of waiters) {
         try {
-            void Promise.resolve(dispatcher.onSettle(snapshot(ask), result)).catch((err) => {
-                logger.warn?.(`ask-broker: ${askId} onSettle failed: ${err instanceof Error ? err.message : String(err)}`);
-            });
+            w(result);
         }
         catch (err) {
-            logger.warn?.(`ask-broker: ${askId} onSettle threw: ${err instanceof Error ? err.message : String(err)}`);
+            logger.warn?.(`ask-broker: ${askId} waiter threw: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    notifyOnSettle(ask, result);
+}
+/** Notify the IM-side dispatcher's onSettle hook (best-effort — never blocks
+ *  broker state). Shared by the normal settle path and the dormant-answer stash. */
+function notifyOnSettle(ask, result) {
+    if (!dispatcher?.onSettle)
+        return;
+    try {
+        void Promise.resolve(dispatcher.onSettle(snapshot(ask), result)).catch((err) => {
+            logger.warn?.(`ask-broker: ${ask.askId} onSettle failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    catch (err) {
+        logger.warn?.(`ask-broker: ${ask.askId} onSettle threw: ${err instanceof Error ? err.message : String(err)}`);
+    }
 }
 /** Strip broker-internal fields before handing a snapshot to the IM-side
- *  dispatcher. Keeps the dispatcher contract narrow. */
+ *  dispatcher. Keeps the dispatcher contract narrow (PendingAsk only). */
 function snapshot(ask) {
-    const { resolve: _r, timeoutHandle: _t, settledAt: _sat, selections: _sel, ...rest } = ask;
+    const { 
+    // Runtime-only / broker-internal fields excluded from the IM contract:
+    waiters: _w, timeoutHandle: _t, settledAt: _sat, selections: _sel, askKey: _ak, requestId: _rid, originKind: _ok, resumable: _rs, dormant: _dm, answeredResult: _ar, terminalResult: _tr, ...rest } = ask;
     return {
         ...rest,
         selections: ask.questions.map((_, i) => [...(ask.selections.get(i) ?? new Set())]),
+        // EVERY ask carries a scoped dedupe token (codex P1-1): the broker's bounded
+        // retry re-sends the card, and a re-send without a uuid posts a DUPLICATE on
+        // the Feishu side. The uuid is the card's dedupe identity for THIS broker
+        // lifetime — derived from the scoped askKey, independent of persistence.
+        // `resumable` gates only cross-restart persistence, NOT intra-process
+        // dispatch idempotency, so explicit / PTY asks (which also retry) dedupe too.
+        dispatchUuid: dispatchUuidForKey(ask.askKey),
     };
 }
 /** Drop settled entries that have aged past the retention window. Cheap O(n)
- *  walk — n is tiny in practice (≤ a few dozen pending+recent asks). */
+ *  walk — n is tiny in practice (≤ a few dozen pending+recent asks). A dormant
+ *  ask holding a stashed answer (durable handoff, awaiting the hook's claim) is
+ *  NEVER reaped from memory here — it lives until claimed or its deadline; on
+ *  disk it survives regardless, and a restart re-hydrates it. */
 function gcSettled() {
     const cutoff = Date.now() - SETTLED_RETENTION_MS;
     for (const [id, ask] of pending) {
+        if (ask.dormant && ask.answeredResult)
+            continue; // unclaimed handoff — keep
         if (ask.settled && ask.settledAt !== undefined && ask.settledAt < cutoff) {
             pending.delete(id);
         }
     }
 }
+/**
+ * Arm an absolute-expiry timer for an unclaimed handoff stash (codex P1-4). A
+ * stashed answer is kept until the reconnecting hook claims it — but if the CLI
+ * is gone for good, nothing would ever remove it from a long-running daemon's
+ * memory (gcSettled deliberately skips unclaimed handoffs) OR from disk (the
+ * disk reap only runs in list() at boot). This timer closes both: at
+ * `answeredAt + HANDOFF_RETENTION_MS` it deletes the in-memory entry AND the
+ * persisted record TOGETHER, so memory and disk never diverge.
+ *
+ * Idempotent: clears any prior handle first (re-arming on a second restore is
+ * fine). The timer is unref'd so it never keeps the process alive.
+ */
+function armHandoffExpiry(ask) {
+    clearTimeout(ask.handoffExpiryHandle);
+    const stashedAt = ask.settledAt ?? Date.now();
+    const fireIn = Math.max(0, stashedAt + handoffRetentionMs - Date.now());
+    ask.handoffExpiryHandle = setTimeout(() => {
+        // Only reap if STILL an unclaimed stash (a claim clears this handle, but
+        // guard against a late fire racing a claim).
+        const cur = pending.get(ask.askId);
+        if (!cur || !cur.dormant || !cur.answeredResult)
+            return;
+        pending.delete(cur.askId);
+        persistStore?.remove(cur.askKey);
+        logger.info?.(`ask-broker: handoff stash expired unclaimed for ask ${cur.askId} (key=${cur.askKey}) — reaped memory + disk`);
+    }, fireIn);
+    ask.handoffExpiryHandle.unref?.();
+}
 // ---- diagnostics for tests ---------------------------------------------------
 /** Count of asks still awaiting a click / timeout — excludes settled entries
  *  retained within the race-loser feedback window. For tests and metrics only. */
@@ -442,10 +855,17 @@ export function _allAskIds() {
 /** Reset broker state — for tests only. Does NOT resolve outstanding promises,
  *  so tests must not call this while real CLI processes might be waiting. */
 export function _resetForTest() {
-    for (const ask of pending.values())
+    for (const ask of pending.values()) {
         clearTimeout(ask.timeoutHandle);
+        clearTimeout(ask.handoffExpiryHandle);
+    }
     pending.clear();
     dispatcher = null;
     canTalkChecker = null;
+    handoffRetentionMs = HANDOFF_RETENTION_MS; // restore default retention
+    // Detach the injected store — never delete files here (codex P1-4: a helper
+    // reaping a shared dataDir could wipe a LIVE pending ask). Tests own their
+    // temp dir's cleanup via their own teardown.
+    persistStore = null;
 }
 //# sourceMappingURL=ask-broker.js.map