hilos-agent 0.10.1 → 0.11.2

package/src/run.mjs

@@ -5,7 +5,7 @@
 import { hostname } from "node:os";
 import { basename } from "node:path";
 import { makeClient } from "./mcp.mjs";
-import { loadMentionCursor, saveMentionCursor } from "./cursor-store.mjs";
+import { loadMentionCursorState, saveMentionCursor } from "./cursor-store.mjs";
 import { mentionHandle } from "./daemon.mjs";
 import { handleTask } from "./handler.mjs";
 import { createQueue, looksLikeCancel, dedupeKey } from "./queue.mjs";
@@ -15,6 +15,12 @@ import { startWake, createWakeGate } from "./wake.mjs";
 import { scanReplyBridge, handleReplyBridgeJob } from "./reply-bridge.mjs";
 import { detectVendor, fastChatCmd, webCapability } from "./progress-emitter.mjs";
 import { commandArgv } from "./argv.mjs";
+import {
+  createIterateClaimRecoveryStore,
+  reconcileDaemonIterateClaims,
+} from "./iterate-claim-recovery.mjs";
+
+const MAX_IMMEDIATE_SEQUENCE_PAGES = 8;
 
 /**
  * The poll loop. Embeddable: pass a `signal` to stop it cleanly (interrupts the
@@ -28,9 +34,28 @@ import { commandArgv } from "./argv.mjs";
  *   log?: any,
  *   signal?: AbortSignal,
  *   onEvent?: (event: { type: string, [k: string]: any }) => void,
+ *   mentionCursorDir?: string,
+ *   iterateClaimRecoveryDir?: string,
+ *   iterateClaimRecoveryRetryDelay?: () => Promise<void>,
+ *   iterateClaimShutdownReconcileAttempts?: number,
+ *   iterateClaimShutdownReconcileTimeoutMs?: number,
  * }} [opts]
  */
-export async function run(cfg, { handler = handleTask, log = console, signal, onEvent } = {}) {
+export async function run(
+  cfg,
+  {
+    handler = handleTask,
+    log = console,
+    signal,
+    onEvent,
+    mentionCursorDir,
+    iterateClaimRecoveryDir,
+    iterateClaimRecoveryRetryDelay = () =>
+      new Promise((resolve) => setTimeout(resolve, 1000)),
+    iterateClaimShutdownReconcileAttempts = 2,
+    iterateClaimShutdownReconcileTimeoutMs = 1000,
+  } = {},
+) {
   if (!cfg.token) {
     // Throw, don't process.exit — the CLI's main().catch prints + exits 1 exactly
     // as before, and an embedding host (the desktop Local Agents runner) must
@@ -48,28 +73,93 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       /* a bad event listener must never break the daemon */
     }
   };
-  // The wake doorbell (0824): a Realtime ping resolves the pending inter-poll
-  // sleep so the next list_mentions poll happens NOW. A ping that lands while a
-  // poll is still running is remembered, so the following sleep returns
-  // immediately instead of the ping being lost to the race. That race lives in
-  // createWakeGate (wake.mjs) so it can be unit-tested; the sleep it hands back
-  // also resolves on abort, so "stop" never waits out the poll interval.
-  const { ping: onWakePing, sleep: interruptibleSleep } = createWakeGate({ signal });
+  let stoppingEmitted = false;
+  const emitStopping = () => {
+    if (stoppingEmitted) return;
+    stoppingEmitted = true;
+    emit({ type: "status", text: "stopping" });
+  };
 
   // Already asked to stop before we even connect → return cleanly, do nothing.
   if (signal?.aborted) {
-    emit({ type: "status", text: "stopping" });
+    emitStopping();
     return;
   }
+  const runController = new AbortController();
+  const abortFromCaller = () => runController.abort(signal?.reason);
+  signal?.addEventListener("abort", abortFromCaller, { once: true });
+  const runSignal = runController.signal;
+  // The wake doorbell (0824): a Realtime ping resolves the pending inter-poll
+  // sleep so the next list_mentions poll happens NOW. A ping that lands while a
+  // poll is still running is remembered, so the following sleep returns
+  // immediately instead of the ping being lost to the race. That race lives in
+  // createWakeGate (wake.mjs) so it can be unit-tested; the sleep it hands back
+  // also resolves on abort, so caller cancellation or a terminal auth response
+  // never waits out the poll interval.
+  const { ping: onWakePing, sleep: interruptibleSleep } = createWakeGate({
+    signal: runSignal,
+  });
+  const canceledByRunSignal = (error) =>
+    Boolean(signal?.aborted && (error?.abortedByCaller || error?.name === "AbortError"));
+  // Match the typed client error by its stable cross-realm name. This also
+  // works for embedding hosts and test doubles that do not share a constructor.
+  const isAuthStop = (error) => error?.name === "McpAuthStopError";
+  const reportAuthStop = (error) => {
+    if (!isAuthStop(error)) return false;
+    emitStopping();
+    return true;
+  };
 
-  const { tool, listTools, listToolNames } = makeClient({ url: cfg.url, token: cfg.token });
+  const client = makeClient({ url: cfg.url, token: cfg.token });
+  // Keep injected/older test clients compatible; the real makeClient always
+  // provides this lifecycle signal and terminal auth still latches through it.
+  const { tool, listTools, listToolNames } = client;
+  const stopSignal = client.stopSignal ?? new AbortController().signal;
+  const abortFromAuthStop = () => runController.abort(stopSignal.reason);
+  stopSignal.addEventListener("abort", abortFromAuthStop, { once: true });
+  const detachLifecycleSources = () => {
+    signal?.removeEventListener("abort", abortFromCaller);
+    stopSignal.removeEventListener("abort", abortFromAuthStop);
+  };
 
-  const who = await tool("whoami");
+  let who;
+  try {
+    who = await tool("whoami", {}, { signal: runSignal });
+  } catch (error) {
+    detachLifecycleSources();
+    if (reportAuthStop(error)) throw error;
+    if (canceledByRunSignal(error)) {
+      emitStopping();
+      return;
+    }
+    throw error;
+  }
   const me = { ...who, handle: mentionHandle(who.agentName) };
   if (!me.handle) {
+    detachLifecycleSources();
     // Throw for the same reason as the token guard above — embed-safe, CLI-equal.
     throw new Error("This agent has no display name / handle — set one in hilos, then reconnect.");
   }
+  // Initialized only after the server advertises the complete recovery
+  // protocol below. Older servers keep their pre-recovery Iterate behavior.
+  let iterateClaimRecoveryStore = null;
+  let queue = null;
+  let wake = null;
+  let reconcileClaimsOnce = async () => true;
+  const withinShutdownReconcileBound = async (promise) => {
+    let timer;
+    try {
+      return await Promise.race([
+        Promise.resolve(promise),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(false), iterateClaimShutdownReconcileTimeoutMs);
+        }),
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  };
+  try {
   log.log(`hilos-agent: ${me.agentName} (@${me.handle}) — ${cfg.url}`);
   if (cfg.channelId) log.log(`scope: channel ${cfg.channelId}`);
   log.log(`repos: ${Object.keys(cfg.repos).join(", ") || "(none configured)"}`);
@@ -94,11 +184,11 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   // listTools (schemas included) is the primary read; a client exposing only
   // listToolNames (an embedder's minimal mock, or an older embedded client)
   // still names the tools — it just never advertises arg-level capabilities.
-  const toolList = typeof listTools === "function" ? await listTools() : [];
+  const toolList = typeof listTools === "function" ? await listTools({ signal: runSignal }) : [];
   const toolNames = toolList.length
     ? toolList.map((t) => t.name)
     : typeof listToolNames === "function"
-      ? await listToolNames()
+      ? await listToolNames({ signal: runSignal })
       : [];
   const useMentions = toolNames.includes("list_mentions");
   // Arg-level capability sniffing (0866): a long-poll-capable server declares
@@ -107,7 +197,45 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   const toolArgProps = (name) =>
     toolList.find((t) => t.name === name)?.inputSchema?.properties ?? {};
   const serverMentionWait = "waitMs" in toolArgProps("list_mentions");
+  const serverMentionSequence = "sinceMentionSeq" in toolArgProps("list_mentions");
+  const serverMentionSequenceBootstrap = "initializeMentionSeq" in toolArgProps("list_mentions");
   const serverDecisionWait = "waitMs" in toolArgProps("get_permission_decision");
+  const updateRunArgs = toolArgProps("update_run");
+  const serverIterateClaimRecovery =
+    "claimId" in updateRunArgs &&
+    "confirmIterateClaim" in updateRunArgs &&
+    "releaseIterateClaim" in updateRunArgs;
+  if (me.agentId && serverIterateClaimRecovery) {
+    iterateClaimRecoveryStore = createIterateClaimRecoveryStore({
+      agentId: me.agentId,
+      url: cfg.url,
+      token: cfg.token,
+      ...(iterateClaimRecoveryDir ? { dir: iterateClaimRecoveryDir } : {}),
+      log,
+    });
+    if (!iterateClaimRecoveryStore.acquireLock()) {
+      throw new Error("Another local daemon already owns this agent and server connection.");
+    }
+    reconcileClaimsOnce = async (context) => {
+      try {
+        const recovery = await reconcileDaemonIterateClaims({
+          tool,
+          recoveryStore: iterateClaimRecoveryStore,
+          log,
+        });
+        if (recovery.unresolved === 0) return true;
+        log.error(
+          `iterate claim recovery unresolved (${recovery.unresolved}) ${context}; work remains paused`,
+        );
+        return false;
+      } catch (error) {
+        log.error(
+          `iterate claim recovery failed ${context}: ${error?.message || error}; work remains paused`,
+        );
+        return false;
+      }
+    };
+  }
   // Capabilities of THIS server, so the handler degrades gracefully on older
   // deploys (e.g. no edit_message → no live heartbeat, rather than erroring).
   const caps = {
@@ -142,6 +270,15 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // server has to offer the tool, and the operator has to have turned
     // `uploadTranscripts` on. Older servers simply never see the call.
     uploadTranscript: toolNames.includes("upload_run_transcript"),
+    // Runtime-neutral replay exhaust (1148). The daemon only projects local
+    // coding streams when this exact ingest boundary exists; older servers
+    // keep the current progress/transcript behavior byte-for-byte.
+    hepEvents: toolNames.includes("append_run_events"),
+    // Room directions for a running job (1181/1182). When the server can take
+    // the receipt, the daemon declares `next_turn` at start_run, reads
+    // `pendingInputs` off its heartbeat, and runs one more turn with them.
+    // Older servers never list a direction, and the daemon never declares.
+    runInputs: toolNames.includes("acknowledge_run_input"),
     // Emoji reactions (0860): the lightest answer to an untagged DM message
     // that needs no words. Absent on older servers → the agent stays quiet
     // instead, exactly as if it had no hand to wave.
@@ -156,7 +293,6 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   // On an older server the tool is absent and the daemon polls exactly as
   // before; with it, a new message in the workspace rings a content-free
   // Realtime broadcast that cuts mention pickup from pollMs to instant.
-  let wake = null;
   if (toolNames.includes("get_wake_channel")) {
     try {
       const chan = await tool("get_wake_channel");
@@ -181,6 +317,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
         log.log("wake: realtime doorbell enabled (polling stays as fallback)");
       }
     } catch (e) {
+      if (isAuthStop(e)) throw e;
       log.log(`wake: unavailable (${e.message}) — polling only`);
     }
   }
@@ -214,6 +351,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
           });
         }
       } catch (e) {
+        if (isAuthStop(e)) throw e;
         log.error(`link_folder failed for ${path}: ${e?.message || e}`);
       }
     }
@@ -231,17 +369,102 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   // Resume from the persisted cursor (0866) so mentions that arrived while the
   // daemon was down are delivered on restart instead of silently skipped —
   // bounded by catchupMs. `backfill` still means "from the beginning" and wins.
-  const persistedCursor = cfg.backfill
+  const persistedCursorState = cfg.backfill
     ? null
-    : loadMentionCursor(me.agentId, { catchupMs: cfg.catchupMs });
+    : loadMentionCursorState(me.agentId, {
+        catchupMs: cfg.catchupMs,
+        ...(mentionCursorDir ? { dir: mentionCursorDir } : {}),
+      });
+  const persistedCursor = persistedCursorState?.createdAt ?? null;
   if (persistedCursor) log.log(`resuming mention cursor from ${persistedCursor}`);
   const cursor = {
     value: persistedCursor ?? (since ? new Date(since).toISOString() : null),
+    seq: serverMentionSequence ? persistedCursorState?.mentionSeq ?? null : null,
   };
+  let mentionSequenceActive = serverMentionSequence && cursor.seq != null;
+  // Fetch progress is deliberately volatile. It moves through pages as soon as
+  // the server scans them (so an active job does not hot-poll one seen row),
+  // while `cursor` moves only after queue/recovery settlement. A restart always
+  // resumes from the durable cursor and therefore replays unfinished work.
+  const fetchCursor = { value: cursor.value, seq: cursor.seq };
+  // A capable server pages by monotonic mention ingestion sequence. Older
+  // servers remain timestamp batches and do not commit T until every accepted
+  // T sibling is settled.
+  const cursorBatches = new Map(); // mention-sequence/timestamp key → batch
+  const delegatedReplyIds = new Set();
+
+  const batchKey = (timestamp, mentionSeq) =>
+    mentionSequenceActive ? `seq:${mentionSeq}` : String(timestamp);
+
+  function registerCursorMention(message) {
+    const at = message?.created_at;
+    const timestamp = new Date(at).getTime();
+    if (!message?.id || !Number.isFinite(timestamp)) return;
+    const mentionSeq = Number.isSafeInteger(message.mentionSeq) && message.mentionSeq >= 0
+      ? message.mentionSeq
+      : null;
+    // Deploy, dispatch, ambient, and DM projections are useful intake, but are
+    // not rows in the explicit mention scan. They must never advance that
+    // durable high-watermark.
+    if (serverMentionSequence && mentionSeq == null) return;
+    const key = batchKey(timestamp, mentionSeq);
+    let batch = cursorBatches.get(key);
+    if (!batch) {
+      batch = { at, timestamp, seq: mentionSeq, ids: new Set(), settled: new Set() };
+      cursorBatches.set(key, batch);
+    }
+    batch.ids.add(message.id);
+  }
+
+  function commitSettledCursorBatches() {
+    let cursorTime = cursor.value ? new Date(cursor.value).getTime() : -Infinity;
+    let advanced = false;
+    const ordered = [...cursorBatches.entries()].sort((left, right) => {
+      if (mentionSequenceActive) return left[1].seq - right[1].seq;
+      const time = left[1].timestamp - right[1].timestamp;
+      return time;
+    });
+    for (const [key, batch] of ordered) {
+      const behind = mentionSequenceActive
+        ? cursor.seq != null && batch.seq <= cursor.seq
+        : batch.timestamp <= cursorTime;
+      if (behind) {
+        cursorBatches.delete(key);
+        continue;
+      }
+      if (batch.settled.size < batch.ids.size) break;
+      cursor.value = batch.at;
+      cursor.seq = batch.seq;
+      cursorTime = batch.timestamp;
+      cursorBatches.delete(key);
+      advanced = true;
+      if (mentionSequenceActive && (fetchCursor.seq == null || cursor.seq > fetchCursor.seq)) {
+        fetchCursor.value = cursor.value;
+        fetchCursor.seq = cursor.seq;
+      }
+    }
+    if (advanced && liveCfg.catchupMs > 0) {
+      saveMentionCursor(me.agentId, cursor.value, {
+        ...(mentionCursorDir ? { dir: mentionCursorDir } : {}),
+        ...(mentionSequenceActive ? { mentionSeq: cursor.seq } : {}),
+        log,
+      });
+    }
+  }
+
+  function settleCursorMention(message) {
+    const timestamp = new Date(message?.created_at).getTime();
+    const mentionSeq = Number.isSafeInteger(message?.mentionSeq) ? message.mentionSeq : null;
+    const batch = cursorBatches.get(batchKey(timestamp, mentionSeq));
+    if (!batch || !message?.id) return;
+    batch.settled.add(message.id);
+    commitSettledCursorBatches();
+  }
   // 0860 — a DM message inside its settle window: the server withheld it and
   // said when it matures. One shortened sleep picks it up right then, instead
   // of the person waiting out the full poll interval mid-conversation.
   let pollAgainMs = null;
+  let oldMentionReplayOnly = false;
 
   // Live config: re-read between polls so model/permission/codingCmd edits to
   // hilos-agent.json take effect without a restart. Identity stays pinned.
@@ -250,32 +473,52 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   // One-at-a-time worker so the poll loop NEVER blocks on a multi-minute run.
   // The loop only fetches + enqueues; the queue runs jobs in order. This is what
   // lets a "stop" (and new mentions) be picked up while a task is still running.
-  const queue = createQueue({
+  queue = createQueue({
     concurrency: cfg.queueConcurrency || 1,
     runJob: (job, { signal: jobSignal }) =>
       job.kind === "reply-bridge"
         ? safeBridgeHandle(job.bridge, jobSignal)
         : safeHandle(job.message, job.channelId, jobSignal),
+    // A handler can finish after the server committed its Iterate claim but
+    // before the local receipt was cleared. Never advance the FIFO until that
+    // exact durable owner has been reconciled.
+    afterJob: async (job) => {
+      const recoveryCheck = reconcileClaimsOnce("between queued jobs");
+      const safe = cfg.once
+        ? await withinShutdownReconcileBound(recoveryCheck)
+        : await recoveryCheck;
+      if (safe && job.kind !== "reply-bridge" && job.message?.created_at) {
+        settleCursorMention(job.message);
+      }
+      if (!safe && cfg.once) {
+        // Cron/--once has no future poll cycle in which an infinite barrier can
+        // recover. Hand the durable receipt to the next invocation; unstarted
+        // queue entries remain unacknowledged and replay from the cursor.
+        void queue.shutdown("once-mode recovery handoff");
+      }
+      return safe;
+    },
+    afterJobRetryDelay: iterateClaimRecoveryRetryDelay,
   });
 
   let boundThreadRoots = new Set();
   let replyScanOffset = 0;
 
-  // Stopping the embedded daemon: the moment the caller aborts, cancel the active
+  // Stopping the embedded daemon: the moment the caller aborts or the MCP client
+  // latches a terminal auth response, cancel the active
   // job (via the queue's existing cancel path — it aborts the in-flight job's
   // signal) so a multi-minute run is torn down promptly, and emit a stopping
   // event. New tasks are refused in intake(); the loop below exits on the same
-  // signal and run() resolves cleanly.
-  if (signal) {
-    signal.addEventListener(
-      "abort",
-      () => {
-        emit({ type: "status", text: "stopping" });
-        queue.cancelActive("run() aborted");
-      },
-      { once: true },
-    );
-  }
+  // signal. Caller cancellation resolves cleanly; terminal auth rejects after
+  // the same cleanup so the operator sees that the token must be replaced.
+  runSignal.addEventListener(
+    "abort",
+    () => {
+      emitStopping();
+      void queue.shutdown("run() aborted");
+    },
+    { once: true },
+  );
 
   async function safeHandle(message, channelId, jobSignal) {
     emit({ type: "task-start", channelId, messageId: message.id, text: (message.body || "").slice(0, 200) });
@@ -315,7 +558,12 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     try {
       log.log(`→ task in ${channelId}: "${(message.body || "").slice(0, 80)}"`);
       // liveCfg so a job uses the latest model/permission/codingCmd at run time.
-      const result = await handler({ message: withImages, channelId, tool, me, caps }, liveCfg, undefined, { signal: jobSignal, onStopRequested });
+      const result = await handler(
+        { message: withImages, channelId, tool, me, caps, iterateClaimRecoveryStore },
+        liveCfg,
+        undefined,
+        { signal: jobSignal, onStopRequested },
+      );
       emit({ type: "task-done", channelId, status: result && result.status });
     } catch (e) {
       emit({ type: "task-error", channelId, error: e?.message || String(e) });
@@ -360,7 +608,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   // when it lands behind work already in progress.
   async function intake(m, channelId) {
     // Once we're stopping, don't start anything new.
-    if (signal?.aborted) return;
+    if (runSignal.aborted) return { accepted: false };
     if (looksLikeCancel(m.body) && (queue.active() || queue.size())) {
       queue.cancelActive("user asked to stop");
       await tool("post_message", {
@@ -368,12 +616,18 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
         parentId: m.parentId ?? null,
         body: "Stopping the current task.",
       }).catch(() => {});
-      return;
+      return { accepted: false, settled: true };
     }
-    const r = queue.enqueue({ message: m, channelId, key: dedupeKey(m, channelId) });
-    if (r.deduped) {
-      log.log("  (deduped a repeat of an in-flight/queued ask)");
-      return;
+    const mentionSeq = Number.isSafeInteger(m?.mentionSeq) && m.mentionSeq >= 0
+      ? m.mentionSeq
+      : null;
+    const queueKey = mentionSequenceActive && mentionSeq != null
+      ? `${dedupeKey(m, channelId)}::mention-seq:${mentionSeq}`
+      : dedupeKey(m, channelId);
+    const r = queue.enqueue({ message: m, channelId, key: queueKey });
+    if (!r.accepted) {
+      if (r.deduped) log.log("  (deduped a repeat of an in-flight/queued ask)");
+      return { accepted: false, settled: Boolean(r.deduped) };
     }
     // A report-card deploy decision is already visible in place. list_mentions
     // projects the pending decision into this structured event, so don't add a
@@ -388,6 +642,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
         body: "Got it — queued behind the current task.",
       }).catch(() => {});
     }
+    return { accepted: true, settled: false };
   }
 
   // Long-poll (0866): ask a capable server to HOLD the request and answer the
@@ -396,50 +651,123 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   const mentionWaitMs = () =>
     serverMentionWait && liveCfg.longPollMs > 0 ? Math.floor(liveCfg.longPollMs) : 0;
 
-  async function passViaMentions() {
+  async function passViaMentions(immediatePage = 1) {
     const waitMs = mentionWaitMs();
     const mentionArgs = {
-      ...(cursor.value ? { since: cursor.value } : {}),
+      ...(fetchCursor.value ? { since: fetchCursor.value } : {}),
+      ...(mentionSequenceActive && fetchCursor.seq != null
+        ? { sinceMentionSeq: fetchCursor.seq }
+        : {}),
+      ...(serverMentionSequenceBootstrap && !mentionSequenceActive
+        ? { initializeMentionSeq: true }
+        : {}),
       ...(cfg.channelId ? { channelId: cfg.channelId } : {}),
       ...(waitMs ? { waitMs } : {}),
     };
-    const out = await tool("list_mentions", mentionArgs);
+    const out = await tool("list_mentions", mentionArgs, { signal: runSignal });
+    const mentions = (out?.mentions ?? []).slice().reverse();
+    const announcedSequence = out?.mentionCursor?.sequence;
+    const explicitMentions = mentions.filter(
+      (message) => Number.isSafeInteger(message?.mentionSeq) && message.mentionSeq >= 0,
+    );
+    let bootstrappedSequence = false;
+    let settledEmptySequencePage = false;
+    if (
+      mentionSequenceActive &&
+      Number.isSafeInteger(announcedSequence) &&
+      announcedSequence >= 0 &&
+      (fetchCursor.seq == null || announcedSequence > fetchCursor.seq)
+    ) {
+      fetchCursor.seq = announcedSequence;
+      // The server scanned explicit rows through this sequence but none
+      // survived its authoritative filters/revalidation. With no older batch
+      // still unsettled, advancing is a durable settlement rather than merely
+      // volatile fetch progress; otherwise --once would reload the same empty
+      // page forever and starve valid work behind it.
+      if (
+        explicitMentions.length === 0 &&
+        cursorBatches.size === 0 &&
+        (cursor.seq == null || announcedSequence > cursor.seq)
+      ) {
+        cursor.seq = announcedSequence;
+        if (!cursor.value) cursor.value = new Date().toISOString();
+        fetchCursor.value = cursor.value;
+        if (liveCfg.catchupMs > 0) {
+          saveMentionCursor(me.agentId, cursor.value, {
+            ...(mentionCursorDir ? { dir: mentionCursorDir } : {}),
+            mentionSeq: cursor.seq,
+            log,
+          });
+        }
+        settledEmptySequencePage = true;
+      }
+    } else if (
+      serverMentionSequenceBootstrap &&
+      !mentionSequenceActive &&
+      Number.isSafeInteger(announcedSequence) &&
+      announcedSequence >= 0 &&
+      explicitMentions.length === 0 &&
+      cursorBatches.size === 0
+    ) {
+      mentionSequenceActive = true;
+      cursor.seq = announcedSequence;
+      fetchCursor.seq = announcedSequence;
+      if (!cursor.value) cursor.value = new Date().toISOString();
+      fetchCursor.value = cursor.value;
+      if (liveCfg.catchupMs > 0) {
+        saveMentionCursor(me.agentId, cursor.value, {
+          ...(mentionCursorDir ? { dir: mentionCursorDir } : {}),
+          mentionSeq: cursor.seq,
+          log,
+        });
+      }
+      bootstrappedSequence = true;
+    }
     // Floor the server's settle hint so a clock skew can never hot-loop the poll.
     pollAgainMs =
       typeof out?.retryAfterMs === "number" && out.retryAfterMs > 0
         ? Math.max(500, out.retryAfterMs)
         : null;
-    const mentions = (out?.mentions ?? []).slice().reverse();
-    let advanced = false;
-    for (const m of mentions) {
-      if (seen.has(m.id)) continue;
-      seen.add(m.id);
+    const mentionSeenKey = (message) =>
+      mentionSequenceActive && Number.isSafeInteger(message?.mentionSeq) && message.mentionSeq >= 0
+        ? `${message.id}:mention-seq:${message.mentionSeq}`
+        : message.id;
+    const fresh = mentions.filter((message) => !seen.has(mentionSeenKey(message)));
+    oldMentionReplayOnly = !mentionSequenceActive && mentions.length > 0 && fresh.length === 0;
+    // Register the WHOLE response before enqueueing its first item. A fast
+    // first handler can otherwise settle timestamp T before its T sibling is
+    // even known locally, advancing a strict timestamp cursor too early.
+    for (const message of fresh) registerCursorMention(message);
+    for (const m of fresh) {
+      const seenKey = mentionSeenKey(m);
+      seen.add(seenKey);
       // A human reply in a locally-bound thread belongs to the provider
       // session that created that anchor — even when the person also typed an
       // @mention. Let the bridge take it; starting a fresh repo task here would
       // duplicate work and lose the session context this feature exists for.
       if (m.parentId && boundThreadRoots.has(m.parentId)) {
-        if (!cursor.value || new Date(m.created_at).getTime() > new Date(cursor.value).getTime()) {
-          cursor.value = m.created_at;
-          advanced = true;
+        if (delegatedReplyIds.has(m.id)) {
+          settleCursorMention(m);
+        } else {
+          // Delegation did not become durable in this pass. Let the next poll
+          // retry it instead of pinning an un-settleable seen entry forever.
+          seen.delete(seenKey);
         }
         continue;
       }
-      await intake(m, m.channelId);
-      // Compare numerically — created_at formats differ (Z vs +00:00 offset),
-      // so a lexicographic string compare can fail to advance the cursor.
-      if (!cursor.value || new Date(m.created_at).getTime() > new Date(cursor.value).getTime()) {
-        cursor.value = m.created_at;
-        advanced = true;
-      }
+      const accepted = await intake(m, m.channelId);
+      if (accepted?.settled) settleCursorMention(m);
+      if (!accepted?.accepted && !accepted?.settled) seen.delete(seenKey);
     }
-    // Persist on advance only — an idle pass has nothing new to remember —
-    // and only while catch-up is enabled: with catchupMs 0 the file would
-    // never be read back, so writing it would be pure disk noise (this is
-    // also what keeps embedded/mocked runs from touching a real ~/.hilos).
-    // Best-effort: a failed write degrades to restart-at-now, never a crash.
-    if (advanced && cursor.value && liveCfg.catchupMs > 0) {
-      saveMentionCursor(me.agentId, cursor.value, { log });
+    // The initialization response intentionally contains no explicit mention.
+    // Follow it with one sequence pass immediately so `--once` still performs
+    // useful work and a normal daemon does not spend a poll interval idle.
+    if (
+      (bootstrappedSequence || settledEmptySequencePage) &&
+      !runSignal.aborted &&
+      immediatePage < MAX_IMMEDIATE_SEQUENCE_PAGES
+    ) {
+      await passViaMentions(immediatePage + 1);
     }
   }
 
@@ -460,7 +788,8 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       const ids = bridge.replies.map((reply) => reply.id).filter(Boolean);
       const key = `reply-bridge:${bridge.binding.threadRootId}:${ids.join(",")}`;
       const queued = queue.enqueue({ kind: "reply-bridge", bridge, key });
-      if (queued.deduped) continue;
+      if (!queued.accepted && !queued.deduped) continue;
+      for (const id of ids) delegatedReplyIds.add(id);
       if (liveCfg.queueAcks && !queued.startedImmediately) {
         await tool("post_message", {
           channelId: bridge.binding.channelId,
@@ -485,7 +814,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
   }
 
   do {
-    if (signal?.aborted) break;
+    if (runSignal.aborted) break;
     // Pick up live edits to hilos-agent.json (model/permission/codingCmd/etc.)
     // before each pass. Guarded: a bad file leaves liveCfg untouched.
     try {
@@ -500,10 +829,33 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     }
     let passFailed = false;
     try {
-      await passViaReplyBridge();
-      if (useMentions) await passViaMentions();
-      else await passViaScan();
+      // A live queue job may have persisted its claim journal immediately
+      // before sending claim_local_run_iterate. Releasing that record from the
+      // poll loop would race the job that still owns it. Keep polling while a
+      // job runs (Stop must remain responsive), and reconcile on the first
+      // idle pass instead. A queued-but-not-active job cannot have written a
+      // claim record yet, so active() is the precise boundary.
+      const recovery = !iterateClaimRecoveryStore
+        ? { unresolved: 0, recoveryUnavailable: true }
+        : queue.active()
+        ? { unresolved: 0, deferredWhileActive: true }
+        : await reconcileDaemonIterateClaims({
+            tool,
+            recoveryStore: iterateClaimRecoveryStore,
+            log,
+          });
+      if (!recovery.deferredWhileActive && recovery.unresolved > 0) {
+        passFailed = true;
+        log.error(
+          `iterate claim recovery unresolved (${recovery.unresolved}); mention intake remains paused`,
+        );
+      } else {
+        await passViaReplyBridge();
+        if (useMentions) await passViaMentions();
+        else await passViaScan();
+      }
     } catch (e) {
+      if (isAuthStop(e)) throw e;
       passFailed = true;
       log.error(`poll error: ${e.message}`);
     }
@@ -512,7 +864,7 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
       await queue.idle();
       break;
     }
-    if (signal?.aborted) break;
+    if (runSignal.aborted) break;
     // Interruptible so an abort during the sleep returns promptly instead of
     // waiting out the full poll interval, and the doorbell (0824) still cuts
     // any sleep short. A long-polled pass (0866) already spent its waiting
@@ -520,16 +872,50 @@ export async function run(cfg, { handler = handleTask, log = console, signal, on
     // the pass FAILED, where re-holding immediately would hammer a hiccuping
     // server; an error always backs off by the full pollMs. A settling DM
     // (0860) shortens one sleep to the server's hint in either mode.
-    const held = useMentions && mentionWaitMs() > 0 && !passFailed;
+    const held = useMentions && mentionWaitMs() > 0 && !passFailed && !oldMentionReplayOnly;
     const base = held ? 250 : liveCfg.pollMs;
     await interruptibleSleep(pollAgainMs != null ? Math.min(base, pollAgainMs) : base);
-  } while (!signal?.aborted);
+  } while (!runSignal.aborted);
 
-  // Clean stop: close the doorbell socket, make sure any active job is cancelled
-  // (the abort listener already fired for the common case, but this covers a
-  // break for other reasons) and let in-flight teardown settle before returning.
-  wake?.stop();
-  if (signal?.aborted) {
-    queue.cancelActive("run() aborted");
+  // A terminal response may first surface inside a concurrently running
+  // handler while the poll loop is sleeping. The client latch aborts the run
+  // immediately; preserve the original typed error after the loop has fenced
+  // intake instead of turning that shutdown into a successful exit.
+  if (isAuthStop(stopSignal.reason)) throw stopSignal.reason;
+
+  // Clean stop: close the doorbell socket. The finally barrier below fences
+  // intake, discards pending work, and awaits active teardown before releasing
+  // this daemon's recovery-scope lock.
+  } catch (error) {
+    if (reportAuthStop(error)) throw error;
+    if (!canceledByRunSignal(error)) throw error;
+  } finally {
+    detachLifecycleSources();
+    wake?.stop();
+    await queue?.shutdown("run() shutting down");
+    let shutdownReconciled = !iterateClaimRecoveryStore || isAuthStop(stopSignal.reason);
+    const shutdownAttempts = Math.max(
+      1,
+      Math.floor(iterateClaimShutdownReconcileAttempts),
+    );
+    for (
+      let attempt = 0;
+      !shutdownReconciled && !isAuthStop(stopSignal.reason) && attempt < shutdownAttempts;
+      attempt += 1
+    ) {
+      shutdownReconciled = await withinShutdownReconcileBound(
+        reconcileClaimsOnce("before daemon lock release"),
+      );
+      if (!shutdownReconciled && attempt + 1 < shutdownAttempts) {
+        await withinShutdownReconcileBound(iterateClaimRecoveryRetryDelay());
+      }
+    }
+    if (!shutdownReconciled && iterateClaimRecoveryStore) {
+      log.error(
+        "iterate claim recovery remains durable after bounded shutdown reconciliation; the next daemon will retry it",
+      );
+    }
+    iterateClaimRecoveryStore?.releaseLock();
+    if (isAuthStop(stopSignal.reason)) throw stopSignal.reason;
   }
 }