fix: preserve exact provider continuation identity

Author: tomdps

AGENTS.md

@@ -335,9 +335,12 @@ POSIX providers run in a dedicated process group; Windows providers use the exac
 Provider continuation is agent- and generation-owned and becomes durable only after logical output
 validation and the `onComplete` hook succeed. A requested resume is successful only when the
 watcher captures that exact same nonempty provider session ID; absent or forked identity fails the
-attempt before hooks and forces the retry to rebuild full context. Persist the exact SQLite rowid
-high-water sequence, applied guidance sequence, and bounded SHA-256 selected-prompt identity with
-the observed provider session; never persist the selected prompt text. Restored
+attempt before hooks and forces the retry to rebuild full context. Watchers track every unique
+session ID observed in a task; once two IDs differ, the persisted capture is permanently ambiguous
+even if a later event repeats the requested ID. Persist SQLite rowid high-water and applied-guidance
+cursors as canonical decimal strings, bind them to SQLite as `BigInt`, and never coerce them through
+JavaScript `Number`. Persist those cursors and a bounded SHA-256 selected-prompt identity with the
+observed provider session; never persist the selected prompt text. Restored
 continuations fail closed unless the final durable `TASK_COMPLETED` boundary and all provenance
 match. Full and continuation source/guidance reads are bounded through the captured high-water;
 continuations query strictly after their prior sequence and de-duplicate the exact triggering

src/agent-wrapper.js

@@ -71,9 +71,9 @@ class AgentWrapper {
     this.currentTask = null;
     /** @type {string | null} */
     this.currentTaskId = null; // Track spawned task ID for resume capability
-    /** @type {{provider: string, sessionId: string, agentId: string, taskId: string, generation: number, cwd: string, worktreePath: string|null, contextSequence: number, guidanceSequence: number|null, promptIdentity: string|null} | null} */
+    /** @type {{provider: string, sessionId: string, agentId: string, taskId: string, generation: number, cwd: string, worktreePath: string|null, contextSequence: string, guidanceSequence: string|null, promptIdentity: string|null} | null} */
     this.providerSession = null; // Provider continuation state, owned by this logical agent only
-    this.currentContextSequence = 0;
+    this.currentContextSequence = '0';
     this.currentGuidanceSequence = null;
     this.currentPromptIdentity = null;
     /** @type {number | null} */
@@ -458,7 +458,7 @@ class AgentWrapper {
       cluster_id: this.cluster.id,
       orderBySequence: true,
     });
-    this.currentContextSequence = latestMessage?.sequence || 0;
+    this.currentContextSequence = latestMessage?.sequence || '0';
     const queuedGuidance = collectQueuedGuidance({
       messageBus: this.messageBus,
       clusterId: this.cluster.id,

src/agent/guidance-queue.js

@@ -1,5 +1,6 @@
 const GUIDANCE_BLOCK_START = '<<GUIDANCE_QUEUE_START>>';
 const GUIDANCE_BLOCK_END = '<<GUIDANCE_QUEUE_END>>';
+const { compareMessageSequences } = require('../ledger-sequence');
 
 function formatGuidanceMessage(message) {
   const timestamp = Number.isFinite(message.timestamp)
@@ -24,7 +25,7 @@ function formatGuidanceMessage(message) {
 function orderGuidanceMessages(messages, orderBySequence) {
   return messages.slice().sort((a, b) => {
     if (orderBySequence) {
-      return (a.sequence || 0) - (b.sequence || 0);
+      return compareMessageSequences(a.sequence || '0', b.sequence || '0');
     }
     return (a.timestamp || 0) - (b.timestamp || 0);
   });

src/agent/provider-session.js

@@ -2,6 +2,7 @@ const crypto = require('crypto');
 const path = require('path');
 
 const { normalizeProviderName, providerSupportsCapability } = require('../../lib/provider-names');
+const { tryCanonicalMessageSequence } = require('../ledger-sequence');
 
 const DURABLE_SESSION_BOUNDARY_EVENTS = new Set([
   'TASK_STARTED',
@@ -22,7 +23,7 @@ function normalizeAbsolutePath(value) {
 }
 
 function normalizeCursor(value) {
-  return Number.isInteger(value) && value >= 0 ? value : null;
+  return tryCanonicalMessageSequence(value);
 }
 
 function normalizeNullableCursor(value) {
@@ -148,6 +149,9 @@ function validateCompletedResumeIdentity(taskInfo) {
   if (!requestedSessionId) {
     return null;
   }
+  if (taskInfo?.sessionIdConflict === true) {
+    return 'Provider continuation emitted conflicting session identities';
+  }
 
   const capturedSessionId = normalizeNonEmptyString(taskInfo?.sessionId);
   if (capturedSessionId === requestedSessionId) {
@@ -175,6 +179,9 @@ function providerSessionFromCompletedTask({
   if (normalizeProviderName(taskInfo.provider) !== provider) {
     return null;
   }
+  if (taskInfo.sessionIdConflict === true) {
+    return null;
+  }
   if (validateCompletedResumeIdentity(taskInfo)) {
     return null;
   }
@@ -208,7 +215,7 @@ function readLastDurableSessionBoundary(messageBus, clusterId, agentId) {
     cluster_id: clusterId,
     topic: 'AGENT_LIFECYCLE',
     sender: agentId,
-    afterId: 0,
+    afterId: '0',
   });
   return lifecycle
     .filter((message) => DURABLE_SESSION_BOUNDARY_EVENTS.has(message.content?.data?.event))
@@ -222,7 +229,7 @@ function restoreAgentProviderSession({ agent, savedState, messageBus, clusterId
   }
   if (
     !Object.hasOwn(savedState, 'lastGuidanceAppliedId') ||
-    savedState.lastGuidanceAppliedId !== session.guidanceSequence
+    normalizeNullableCursor(savedState.lastGuidanceAppliedId) !== session.guidanceSequence
   ) {
     return null;
   }
@@ -237,8 +244,8 @@ function restoreAgentProviderSession({ agent, savedState, messageBus, clusterId
     data.taskId !== session.taskId ||
     data.iteration !== session.generation ||
     normalizeProviderName(data.provider) !== session.provider ||
-    data.contextSequence !== session.contextSequence ||
-    data.guidanceSequence !== session.guidanceSequence ||
+    normalizeCursor(data.contextSequence) !== session.contextSequence ||
+    normalizeNullableCursor(data.guidanceSequence) !== session.guidanceSequence ||
     data.promptIdentity !== session.promptIdentity
   ) {
     return null;

src/ledger-sequence.js

@@ -0,0 +1,63 @@
+const MAX_SQLITE_ROWID = 9223372036854775807n;
+const CANONICAL_SEQUENCE = /^(0|[1-9][0-9]*)$/;
+
+function canonicalMessageSequence(value, name = 'message sequence') {
+  let sequence;
+  if (typeof value === 'string' && CANONICAL_SEQUENCE.test(value)) {
+    sequence = value;
+  } else if (Number.isSafeInteger(value) && value >= 0) {
+    // Accept legacy JSON state while normalizing every new boundary to a
+    // JSON-safe decimal string.
+    sequence = String(value);
+  } else {
+    throw new TypeError(`${name} must be a canonical non-negative decimal string`);
+  }
+
+  if (BigInt(sequence) > MAX_SQLITE_ROWID) {
+    throw new RangeError(`${name} exceeds the SQLite rowid range`);
+  }
+  return sequence;
+}
+
+function messageSequenceFromSql(value, name = 'message sequence') {
+  if (typeof value === 'bigint') {
+    if (value < 0n || value > MAX_SQLITE_ROWID) {
+      throw new RangeError(`${name} is outside the SQLite rowid range`);
+    }
+    return value.toString();
+  }
+  return canonicalMessageSequence(value, name);
+}
+
+function messageSequenceToSql(value, name = 'message sequence') {
+  return BigInt(canonicalMessageSequence(value, name));
+}
+
+function compareMessageSequences(left, right) {
+  const leftValue = messageSequenceToSql(left, 'left message sequence');
+  const rightValue = messageSequenceToSql(right, 'right message sequence');
+  if (leftValue < rightValue) {
+    return -1;
+  }
+  if (leftValue > rightValue) {
+    return 1;
+  }
+  return 0;
+}
+
+function tryCanonicalMessageSequence(value) {
+  try {
+    return canonicalMessageSequence(value);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  MAX_SQLITE_ROWID,
+  canonicalMessageSequence,
+  compareMessageSequences,
+  messageSequenceFromSql,
+  messageSequenceToSql,
+  tryCanonicalMessageSequence,
+};