mixdog 1.3.4 → 1.4.0

package/src/tui/session/session-flow/drain.mjs

@@ -6,24 +6,18 @@
 import {
   isGoalQueuedEntry,
   isQueuedEntryEditable,
-  isQueuedEntryVisible,
   isSlashQueuedEntry,
   mergePromptContents,
   mergePastedImages,
   mergePastedTexts,
 } from '../queue-helpers.mjs';
-import { appendTuiSteeringPersist, dropTuiSteeringPersist } from '../tui-steering-persist.mjs';
 import { parseModelVisibleCompletionWrapper } from '../agent-envelope.mjs';
 import { rewoundFailedTurnItems } from './failed-turn-rewind.mjs';
-
-// Re-check cadence for a drain that found a gate closed. A gate is state, not
-// an event: the queue re-reads it instead of trusting that whoever closes it
-// will remember to kick the queue on the way out. Both timers exist only while
-// the queue actually holds work, so an idle session never polls.
-const BLOCKED_DRAIN_RETRY_MS = 50;
-// Session commands (setModel/newSession/resume/auto-clear) release in seconds;
-// an active turn can run for many minutes, so its gate is re-read coarsely.
-const ACTIVE_TURN_RECHECK_MS = 2_000;
+import { PROMPT_ORIGIN_AGENT_REPORT, PROMPT_ORIGIN_CHANNEL } from '../../../runtime/shared/prompt-origin.mjs';
+import { ACTIVE_TURN_RECHECK_MS, createBlockedDrainRetry } from './drain-retry.mjs';
+import { createClosedQueueSettler } from './drain-closed-queue.mjs';
+import { createEnqueue } from './drain-enqueue.mjs';
+import { sessionTurnPrelude } from '../../../runtime/shared/session-turn-prelude.mjs';
 
 function earliestSubmittedAt(batch) {
   const earliest = batch.reduce((min, entry) => {
@@ -89,6 +83,18 @@ function batchPromptSource(batch) {
   return undefined;
 }
 
+// The batch's provenance for the prompt-cache warmer (cache-warm.mjs
+// cacheWarmTurnKind): one inbound channel message makes it real external
+// activity whatever its presentation; it is an agent report only when every
+// entry is one (a user prompt merged into it is the user speaking).
+function batchPromptOrigin(batch) {
+  if (batch.some((entry) => entry?.origin === PROMPT_ORIGIN_CHANNEL)) return { promptOrigin: PROMPT_ORIGIN_CHANNEL };
+  if (batch.length > 0 && batch.every((entry) => entry?.origin === PROMPT_ORIGIN_AGENT_REPORT)) {
+    return { promptOrigin: PROMPT_ORIGIN_AGENT_REPORT };
+  }
+  return {};
+}
+
 /** The batch's transcript metadata; a batch of completion wakes also records
  *  the execution ids it delivers (`consumedExecutionIds`, from each entry's
  *  execution or resume keys; null for one with neither), the structured
@@ -117,6 +123,7 @@ export function turnOptionsForBatch(batch, steering) {
   );
   return {
     promptSource: batchPromptSource(batch),
+    ...batchPromptOrigin(batch),
     retryFailedTurn: batch[0]?.retryFailedTurn === true,
     retryTurnId: batch[0]?.retryTurnId || null,
     retryAttemptId: batch[0]?.retryAttemptId || null,
@@ -151,19 +158,36 @@ export function turnOptionsForBatch(batch, steering) {
       for (const entry of batch) {
         try {
           entry.onToolResult?.(message);
-        } catch {}
+        } catch {
+          // One submitter's callback must not stop the batch's other entries.
+        }
       }
     },
     onSettled: (detail) => {
       for (const entry of batch) {
         try {
           entry.onSettled?.(detail);
-        } catch {}
+        } catch {
+          // One submitter's callback must not stop the batch's other entries.
+        }
       }
     },
   };
 }
 
+// A failed-turn retry: drop the failed turn's rows when it produced no
+// output, so the resubmitted prompt renders once (the session rewinds the
+// matching message under its own lock).
+function rewindFailedTurnRows(batch, { getState, set, replaceItems }) {
+  const entry = batch[0];
+  if (entry?.retryFailedTurn !== true || entry.retryTurnId) return;
+  const rewound = rewoundFailedTurnItems(getState().items, entry.text);
+  if (!rewound) return;
+  set({
+    items: replaceItems(rewound, { preserveStreamingTail: true, preserveSpill: true, preserveTranscriptView: true }),
+  });
+}
+
 export function createDrainLoop(
   bag,
   { queue, steering, submissions, flushDeferredClearedSessionUi, autoClearBeforeWake }
@@ -181,35 +205,7 @@ export function createDrainLoop(
     flushDeferredExecutionPendingResumeKick,
   } = bag;
 
-  // A failed-turn retry: drop the failed turn's rows when it produced no
-  // output, so the resubmitted prompt renders once (the session rewinds the
-  // matching message under its own lock).
-  function rewindFailedTurnRows(batch) {
-    const entry = batch[0];
-    if (entry?.retryFailedTurn !== true || entry.retryTurnId) return;
-    const rewound = rewoundFailedTurnItems(getState().items, entry.text);
-    if (!rewound) return;
-    set({
-      items: replaceItems(rewound, { preserveStreamingTail: true, preserveSpill: true, preserveTranscriptView: true }),
-    });
-  }
-
-  function scheduleBlockedDrainRetry(delayMs = BLOCKED_DRAIN_RETRY_MS) {
-    if (pending.length === 0 || flags.disposed) return;
-    if (flags.blockedDrainRetryTimer) return;
-    const timer = setTimeout(() => {
-      flags.blockedDrainRetryTimer = null;
-      if (pending.length > 0) void drain();
-    }, delayMs);
-    if (typeof timer.unref === 'function') timer.unref();
-    flags.blockedDrainRetryTimer = timer;
-  }
-
-  function clearBlockedDrainRetry() {
-    if (!flags.blockedDrainRetryTimer) return;
-    clearTimeout(flags.blockedDrainRetryTimer);
-    flags.blockedDrainRetryTimer = null;
-  }
+  const { scheduleBlockedDrainRetry, clearBlockedDrainRetry } = createBlockedDrainRetry({ flags, pending, drain });
 
   function hasModelDrainablePending() {
     return pending.some((entry) => !isSlashQueuedEntry(entry));
@@ -217,45 +213,34 @@ export function createDrainLoop(
 
   const admission = () => flags.admission || 'open';
 
-  // Canonical close settled: nothing queued can ever run. Every accepted
-  // submission is settled explicitly (rejected), never silently dropped, and
-  // its durable steering mirror is released so a restart cannot resurrect it
-  // into the closed conversation.
-  function settleClosedQueue() {
-    const entries = pending.splice(0);
-    pendingNotificationKeys.clear();
-    clearBlockedDrainRetry();
-    if (entries.length === 0) return;
-    queue.removeQueuedEntries(entries);
-    const mirrored = entries.filter((entry) => steering.shouldMirrorSteeringEntry(entry) && entry.steeringPersistId);
-    if (mirrored.length > 0) {
-      void Promise.resolve(dropTuiSteeringPersist(steering.leadSessionId(), mirrored)).catch(() => {});
-    }
-    for (const entry of entries) {
-      if (entry.id) submissions.forget(entry.id);
-      try {
-        entry.onSettled?.({ status: 'rejected', reason: 'session-closed', result: null, session: null });
-      } catch {}
-    }
-  }
+  const settleClosedQueue = createClosedQueueSettler({
+    pending,
+    pendingNotificationKeys,
+    clearBlockedDrainRetry,
+    queue,
+    steering,
+    submissions,
+  });
 
-  async function drain() {
+  // Whether a drain may start now. A closed gate either settles (terminal),
+  // waits for its own release edge, or schedules a re-check of itself.
+  function mayStartDrain() {
     // Execution admission fence: a closing session starts nothing (the close
     // path re-kicks the queue if the durable close fails); a closed one
     // settles what was queued.
-    if (admission() === 'closing') return;
+    if (admission() === 'closing') return false;
     if (admission() === 'terminal') {
       settleClosedQueue();
-      return;
+      return false;
     }
-    if (flags.draining) return;
+    if (flags.draining) return false;
     // Bail while any session command holds commandBusy (auto-clear implies it,
     // but so do setModel/newSession/resume/etc). Running a turn concurrently
     // with a command that swaps or reroutes the live session is a race; the
     // commandBusy-release hook re-kicks drain once the command finishes.
     if (flags.autoClearRunning || flags.quotaResumePending || getState().commandBusy) {
       scheduleBlockedDrainRetry();
-      return;
+      return false;
     }
     // A queued prompt/notification can arrive while a
     // provider turn is already in flight (scheduled message, webhook, agent
@@ -273,8 +258,44 @@ export function createDrainLoop(
       // a lead idled 24 minutes on ten queued agent completions and only moved
       // when the user typed. Queued work re-reads this gate on its own.
       scheduleBlockedDrainRetry(ACTIVE_TURN_RECHECK_MS);
-      return;
+      return false;
     }
+    return true;
+  }
+
+  // Slash commands must run through the TUI command dispatcher, not be
+  // delivered to the model as plain text, so slash entries are handled
+  // outside the queued-command drain.
+  function dequeueModelBatch(firstBatch) {
+    return queue.dequeueQueueBatch('later', {
+      limit: firstBatch ? 1 : Infinity,
+      predicate: (entry) => !isSlashQueuedEntry(entry),
+    });
+  }
+
+  // The batch's rows go on the transcript before its turn starts; returns the
+  // merged prompt the turn sends.
+  function presentBatch(batch) {
+    tuiDebug(`busy-queue drain batch=${batch.length} remaining=${pending.length}`);
+    const merged = mergePromptContents(batch);
+    rewindFailedTurnRows(batch, { getState, set, replaceItems });
+    renderBatchItems(batch, pushUserOrSyntheticItem);
+    return merged;
+  }
+
+  // The drain that still owns the loop hands off: settle a closed queue, run
+  // again for model work that arrived meanwhile, or release the deferred
+  // pending-resume kick.
+  function finishDrain() {
+    flags.draining = false;
+    flushDeferredClearedSessionUi();
+    if (admission() === 'terminal') settleClosedQueue();
+    else if (hasModelDrainablePending()) void drain();
+    else flushDeferredExecutionPendingResumeKick();
+  }
+
+  async function drain() {
+    if (!mayStartDrain()) return;
     clearBlockedDrainRetry();
     const drainEpoch = (Number(flags.drainEpoch) || 0) + 1;
     flags.drainEpoch = drainEpoch;
@@ -293,13 +314,7 @@ export function createDrainLoop(
         // Drain one priority/mode bucket at a time (unified command queue):
         // prompt steering stays editable and task notifications stay
         // non-editable but model-visible.
-        const batch = queue.dequeueQueueBatch('later', {
-          limit: firstBatch ? 1 : Infinity,
-          // Slash commands must run through the TUI command dispatcher, not be
-          // delivered to the model as plain text, so slash entries are handled
-          // outside the queued-command drain.
-          predicate: (entry) => !isSlashQueuedEntry(entry),
-        });
+        const batch = dequeueModelBatch(firstBatch);
         firstBatch = false;
         if (batch.length === 0) break;
         if (isGoalQueuedEntry(batch[0]) && bag.shouldRunGoalContinuation?.(batch[0]) !== true) {
@@ -314,10 +329,17 @@ export function createDrainLoop(
             return;
           }
         }
-        tuiDebug(`busy-queue drain batch=${batch.length} remaining=${pending.length}`);
-        const merged = mergePromptContents(batch);
-        rewindFailedTurnRows(batch);
-        renderBatchItems(batch, pushUserOrSyntheticItem);
+        // Rows owed to this thread before its next prompt (a bot's progress
+        // updates from the sessions it handed work to) land first.
+        const prelude = sessionTurnPrelude(bag.runtime?.id);
+        if (prelude) {
+          await prelude.catch((error) => tuiDebug(`turn prelude failed: ${error?.message || error}`));
+          if (flags.drainEpoch !== drainEpoch || admission() !== 'open' || getState().commandBusy) {
+            queue.requeueEntriesFront(batch);
+            return;
+          }
+        }
+        const merged = presentBatch(batch);
         const turnStatus = await bag.runTurn(merged, turnOptionsForBatch(batch, steering));
         if (flags.drainEpoch !== drainEpoch) return;
         // A deferred cleared-session UI sync (from a late-settling abandoned
@@ -330,78 +352,25 @@ export function createDrainLoop(
         if (turnStatus === 'cancelled' && pending.length === 0) break;
       }
     } finally {
-      if (flags.drainEpoch === drainEpoch) {
-        flags.draining = false;
-        flushDeferredClearedSessionUi();
-        if (admission() === 'terminal') settleClosedQueue();
-        else if (hasModelDrainablePending()) void drain();
-        else flushDeferredExecutionPendingResumeKick();
-      }
+      if (flags.drainEpoch === drainEpoch) finishDrain();
     }
   }
 
-  function enqueue(text, options = {}) {
-    // Admission fence. While closing, only user prompts are accepted (retained
-    // so a failed close loses nothing); notification-driven/model-visible
-    // enqueues are refused. A closed session accepts nothing.
-    const state = admission();
-    const mode = options.mode || 'prompt';
-    if (state !== 'open' && (state === 'terminal' || mode !== 'prompt')) {
-      tuiDebug(`enqueue refused: session admission=${state} mode=${mode}`);
-      return false;
-    }
-    const submissionId = String(options.id || '').trim();
-    // Idempotent intake: a transport that re-sent this exact submission (its
-    // first attempt landed but the response was lost) must not double-post.
-    if (submissionId && submissions.has(submissionId)) {
-      tuiDebug(`prompt-duplicate id=${submissionId} ignored`);
-      // This is an idempotent success, not a rejected submit. Returning false
-      // makes Desktop restore and retry a message that is already queued.
-      return true;
-    }
-    const entry = queue.makeQueueEntry(text, options);
-    if (entry.mode === 'task-notification' && entry.key) {
-      if (pendingNotificationKeys.has(entry.key)) return false;
-      pendingNotificationKeys.add(entry.key);
-    }
-    submissions.remember(submissionId);
-    pending.push(entry);
-    // Typed input or a deliverable notification ends a passive task wait or
-    // shell hold so the next boundary hands it to the model now.
-    const wake = steering.taskWaitWakeForEntry(entry);
-    if (wake) {
-      try {
-        bag.runtime?.interruptTaskWait?.(wake, wake === 'notification' ? entry.execution?.id || null : null);
-      } catch {}
-    }
-    const needsDurableSteering =
-      (getState().busy || getState().commandBusy || flags.autoClearRunning || flags.quotaResumePending) &&
-      steering.shouldMirrorSteeringEntry(entry);
-    const persistence = needsDurableSteering ? appendTuiSteeringPersist(steering.leadSessionId(), entry) : null;
-    if (isQueuedEntryVisible(entry)) {
-      set({ queued: [...getState().queued, entry] });
-      if (isQueuedEntryEditable(entry)) flushEmitImmediate?.();
-    }
-    const queueAgeMs = Math.max(0, Date.now() - Number(entry.submittedAt || Date.now()));
-    tuiDebug(`prompt-queued id=${String(entry.id)} busy=${getState().busy ? 1 : 0} ageMs=${queueAgeMs}`);
-    if (getState().busy) tuiDebug(`busy-queue enqueue mode=${entry.mode} pending=${pending.length}`);
-    void drain();
-    if (options.awaitPersistence === true && persistence) {
-      return Promise.resolve(persistence).then((persisted) => {
-        if (persisted !== false) return true;
-        const index = pending.indexOf(entry);
-        // A turn already took the prompt while its durable mirror was being
-        // written: it was delivered, so rejecting it would hand the sender a
-        // copy of a message the model already has.
-        if (index < 0) return true;
-        pending.splice(index, 1);
-        queue.removeQueuedEntries([entry]);
-        if (submissionId) submissions.forget(submissionId);
-        return false;
-      });
-    }
-    return true;
-  }
+  const enqueue = createEnqueue({
+    admission,
+    tuiDebug,
+    flags,
+    pending,
+    pendingNotificationKeys,
+    getState,
+    set,
+    flushEmitImmediate,
+    getRuntime: () => bag.runtime,
+    queue,
+    steering,
+    submissions,
+    drain,
+  });
 
   return { drain, enqueue, settleClosedQueue };
 }

package/src/tui/session/session-flow/queue/entry-shape.mjs

@@ -9,6 +9,7 @@ import {
   promptDisplayText,
   promptContentImageMeta,
 } from '../../queue-helpers.mjs';
+import { promptOriginOf } from '../../../../runtime/shared/prompt-origin.mjs';
 
 export function makeQueueEntry(text, options = {}, nextId) {
   const mode = options.mode || 'prompt';
@@ -33,6 +34,10 @@ export function makeQueueEntry(text, options = {}, nextId) {
     ...(options.execution && typeof options.execution === 'object' ? { execution: { ...options.execution } } : {}),
     priority,
     key: options.key || null,
+    // Provenance apart from the mode (shared/prompt-origin.mjs): an inbound
+    // channel message queued as a task notification is real external
+    // activity; an agent report queued as a prompt is the runtime's.
+    origin: promptOriginOf(options.origin),
     skipSlashCommands: options.skipSlashCommands === true,
     displayText: mode === 'task-notification' ? notificationDisplayText(displayText) : String(displayText || ''),
     suppressDisplay: options.suppressDisplay === true,

package/src/tui/session/session-flow/queue/take-entries.mjs

@@ -19,6 +19,9 @@ const attributionOf = (entry) =>
     entry?.transcriptMeta?.hop || 0
   }`;
 
+/** A retry of a failed turn runs alone: its options belong to its own turn. */
+const isRetryEntry = (entry) => entry.retryFailedTurn === true || Boolean(entry.retryTurnId);
+
 export function createTakeEntriesOps({ pending, pendingNotificationKeys, removeQueuedEntries, leadSessionId }) {
   function dequeueQueueBatch(maxPriority = 'later', options = {}) {
     if (pending.length === 0) return [];
@@ -45,14 +48,14 @@ export function createTakeEntriesOps({ pending, pendingNotificationKeys, removeQ
         (entry.mode || 'prompt') === targetMode &&
         queuePriorityValue(entry.priority) === bestPriority
       ) {
-        if (batch.length > 0 && entry.retryTurnId) break;
+        if (batch.length > 0 && isRetryEntry(entry)) break;
         // One turn records one sender: a bot's message never merges with the user's.
         if (batch.length > 0 && attributionOf(entry) !== attributionOf(batch[0])) break;
         batch.push(entry);
         pending.splice(i, 1);
         if (entry.mode === 'task-notification' && entry.key) pendingNotificationKeys.delete(entry.key);
         // A routine fire is a turn of its own, never merged with another.
-        if (entry.retryTurnId || entry.mode === 'routine' || batch.length >= limit) break;
+        if (isRetryEntry(entry) || entry.mode === 'routine' || batch.length >= limit) break;
       } else {
         i += 1;
       }

package/src/tui/session/tool-approval-delegation.mjs

@@ -0,0 +1,64 @@
+/**
+ * src/tui/session/tool-approval-delegation.mjs — where else a tool-approval
+ * request shows: the top-level chat above a sub-agent (`delegationSurface`) or
+ * the chats handing this session work (`handsOff`, `offerToHandoffs`;
+ * runtime/shared/delegated-approval-host.mjs).
+ */
+import { agentIdOfHomeSession } from '../../runtime/agent/orchestrator/session/agent-home.mjs';
+import { roomMemberOfSession } from '../../runtime/agent/orchestrator/session/agent-room.mjs';
+import { delegateToHandoffs } from '../../runtime/shared/delegated-approval-host.mjs';
+
+/** Requests a sub-agent (or a session a chat handed work to) shows in the
+ *  conversation the user watches too. A secret and a takeover go there as
+ *  well: the value goes to this PC by its request id and the sign-in window
+ *  is bound to the asking session, wherever the card is answered. A
+ *  sub-agent's question stays in its own session (its answer belongs to that
+ *  conversation); a handed-off session's question shows in the chats handing
+ *  it work too, beside their hand-off line (tool-approval.mjs
+ *  `handoffQuestions`), never in their queue. */
+const DELEGATED_KINDS = new Set(['', 'approval', 'outbound', 'permission', 'secret', 'takeover']);
+const HANDOFF_KINDS = new Set([...DELEGATED_KINDS, 'question']);
+
+export function createApprovalDelegation({ surfaceOf, ownSessionId }) {
+  /** `{ sessionId, chain }` of the top-level chat a sub-agent's request also
+   *  shows in, or null (no delegation, another kind, or this is the top). */
+  function delegationSurface(request) {
+    if (typeof surfaceOf !== 'function' || !DELEGATED_KINDS.has(request.kind)) return null;
+    const own = String(request.sessionId || ownSessionId());
+    let surface = null;
+    try {
+      surface = surfaceOf(own);
+    } catch {
+      return null;
+    }
+    const sessionId = String(surface?.sessionId || '');
+    if (!sessionId || sessionId === own || sessionId === ownSessionId()) return null;
+    return { sessionId, chain: Array.isArray(surface.chain) ? surface.chain.map(String) : [] };
+  }
+  /** Whether a request this (top-level) session itself makes also shows in
+   *  the chats handing it work (delegated-approval-host.mjs), while it waits. */
+  function handsOff(request) {
+    if (typeof surfaceOf !== 'function' || !HANDOFF_KINDS.has(request.kind)) return false;
+    const own = ownSessionId();
+    return Boolean(own) && String(request.sessionId || own) === own;
+  }
+  function offerToHandoffs(id, request, answer) {
+    const own = ownSessionId();
+    const agentId = agentIdOfHomeSession(own) || roomMemberOfSession(own)?.agentId || '';
+    // Each chat handing this session work names it its own way.
+    delegateToHandoffs({
+      id,
+      sessionId: own,
+      request,
+      answer,
+      copyFor: (chat, { title }) => ({
+        ...request,
+        sessionId: request.sessionId || own,
+        chain: [],
+        surfaceSessionId: chat,
+        handoff: { title, ...(agentId ? { agentId } : {}) },
+      }),
+    });
+  }
+  return { delegationSurface, handsOff, offerToHandoffs };
+}

package/src/tui/session/tool-approval-request.mjs

@@ -0,0 +1,39 @@
+/**
+ * src/tui/session/tool-approval-request.mjs — the request record a tool-approval
+ * queue (tool-approval.mjs) holds and presents: name, args, reason, and its
+ * own wait limit.
+ */
+import { humanRequestFields } from '../../runtime/agent/orchestrator/session/human-gate/requests.mjs';
+
+/** The queue's default wait limit from its `timeoutMs` option: a positive
+ *  number, else null (no limit). */
+export function defaultApprovalTimeoutMs(timeoutMs) {
+  return Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0 ? Number(timeoutMs) : null;
+}
+
+export function normalizeToolApprovalRequest(input, id, defaultTimeoutMs) {
+  const now = Date.now();
+  // An explicit `timeoutMs: null` means no wait limit (no timer, no expiry);
+  // any other missing/invalid value falls back to the session default,
+  // which is itself no limit unless the runtime configures one.
+  let requestTimeoutMs = defaultTimeoutMs;
+  if (input?.timeoutMs === null) requestTimeoutMs = null;
+  else if (Number.isFinite(Number(input?.timeoutMs)) && Number(input.timeoutMs) > 0) {
+    requestTimeoutMs = Number(input.timeoutMs);
+  }
+  return {
+    id,
+    name: String(input?.name || input?.tool_name || 'tool'),
+    kind: typeof input?.kind === 'string' ? input.kind : '',
+    args: input?.args ?? input?.tool_input ?? null,
+    cwd: input?.cwd || null,
+    sessionId: input?.sessionId || input?.session_id || null,
+    toolCallId: input?.toolCallId || input?.tool_use_id || null,
+    reason: String(input?.reason || input?.message || 'approval requested by hook').trim(),
+    requestedAt: now,
+    timeoutMs: requestTimeoutMs,
+    expiresAt: requestTimeoutMs === null ? null : now + requestTimeoutMs,
+    // outbound / secret / takeover / permission fields (human-gate/requests.mjs).
+    ...humanRequestFields(input),
+  };
+}

package/src/tui/session/tool-approval-settle.mjs

@@ -0,0 +1,62 @@
+/**
+ * src/tui/session/tool-approval-settle.mjs — how one tool-approval entry ends:
+ * the answer its waiter gets, the forwarded answer of a copy, and the outcome
+ * record published on the state (`toolApprovalResult`).
+ */
+import { normalizeHumanResponse } from '../../runtime/agent/orchestrator/session/human-gate/requests.mjs';
+import { withdrawDelegatedApproval } from '../../runtime/shared/delegated-approval-host.mjs';
+
+// Settle one entry: drop its timeout, then hand the waiter its answer. The
+// resolve stays guarded — a waiter whose caller already went away must never
+// take the rest of the queue down with it.
+export function settleToolApproval(entry, approved, reason, answers, reply, extra, device = '') {
+  if (entry?.timer) clearTimeout(entry.timer);
+  const result = { approved, reason };
+  if (answers !== undefined) result.answers = answers;
+  if (reply !== undefined) result.reply = reply;
+  // A human-kind request answers with its canonical response (never a value).
+  if (entry?.request?.remember) {
+    Object.assign(result, normalizeHumanResponse(entry.request, approved, extra));
+    if (device) result.device = device;
+  }
+  if (extra?.timedOut === true) result.timedOut = true;
+  // Settled here: its copy in the top-level chat goes away.
+  if (entry?.delegated) {
+    withdrawDelegatedApproval(entry.id, { approved, device, ...(extra?.timedOut === true ? { expired: true } : {}) });
+  }
+  try {
+    entry.resolve(result);
+  } catch {
+    // The requester's resolver must not break settling the queue.
+  }
+}
+
+/** Hand a copy's answer to the queue that owns the request; false when the
+ *  owner had already settled it. */
+export function forwardToOwner(entry, approved, reason, device, answers, reply, extra) {
+  try {
+    return entry.mirror.answer(approved, reason, device, answers, reply, extra) === true;
+  } catch {
+    return false;
+  }
+}
+
+/** How the shown entry ended, from its own finish: only an answer from a known
+ *  device is attributed; a real timeout says `expired`; any other unattributed
+ *  end names nobody (null). */
+export function finishedOutcome(id, approved, device, extra) {
+  if (device) return { id, approved: approved === true, device: String(device), at: Date.now() };
+  if (extra?.timedOut === true) return { id, approved: false, device: '', expired: true, at: Date.now() };
+  return null;
+}
+
+/** How a copy ended, from the owner's settle: answered from a known device
+ *  (who), a real timeout (`expired`), or taken away with no answer
+ *  (`withdrawn`: the owner's turn ended, the hand-off copy was removed). */
+export function copyOutcome(id, result) {
+  const device = String(result?.device || '');
+  const at = Date.now();
+  if (device) return { id, approved: result.approved === true, device, at };
+  if (result?.expired === true) return { id, approved: false, device: '', expired: true, at };
+  return { id, approved: false, device: '', withdrawn: true, at };
+}