sentinelayer-cli 0.28.4 → 0.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.28.4",
+  "version": "0.29.1",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/omargate.js

@@ -20,6 +20,8 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--model <id>", "LLM model override (default: gpt-5.3-codex)")
     .option("--provider <name>", "LLM provider: sentinelayer, openai, anthropic")
     .option("--max-cost <usd>", "Maximum AI layer cost in USD (default: 5.0)")
+    .option("--notify-session <session-id>", "Write Omar Deep billing-grade usage entries into this Senti session")
+    .option("--require-usage-ledger", "Fail if Omar Deep AI calls cannot write billing-grade session_usage")
     .option("--persona <csv>", "Only run these personas (comma-separated IDs); unknown IDs are dropped + warned")
     .option("--skip-persona <csv>", "Skip these personas (comma-separated IDs)")
     .option("--stream", "Emit NDJSON events to stdout as personas run")

package/src/commands/session.js

@@ -140,6 +140,8 @@ const SESSION_SAY_CONFIRM_ATTEMPTS = 3;
 const SESSION_SAY_CONFIRM_DELAY_MS = 250;
 const SESSION_SAY_CONFIRM_PAGE_LIMIT = 200;
 const SESSION_SAY_CONFIRM_MAX_PAGES = 10;
+const SESSION_SAY_CONFIRM_TOTAL_TIMEOUT_MS = 10_000;
+const SESSION_SAY_CONFIRM_REQUEST_TIMEOUT_MS = 2_000;
 const SESSION_SAY_LOCAL_ONLY_REASONS = new Set([
   "no_session",
   "not_authenticated",
@@ -201,21 +203,131 @@ async function readSessionConfirmationAnchor(sessionId, { targetPath } = {}) {
   };
 }
 
-async function confirmSessionEventVisible(sessionId, clientMessageId, { targetPath, anchorCursor = null } = {}) {
+function normalizePositiveIntegerOrDefault(value, fallbackValue) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    return fallbackValue;
+  }
+  return Math.floor(normalized);
+}
+
+function confirmationRemainingMs(deadlineMs, nowMs) {
+  const now = Number(nowMs()) || Date.now();
+  return Math.max(0, Math.floor(deadlineMs - now));
+}
+
+async function confirmSessionEventVisible(
+  sessionId,
+  clientMessageId,
+  {
+    targetPath,
+    anchorCursor = null,
+    pollSessionEventsFn = pollSessionEvents,
+    pollSessionEventsBeforeFn = pollSessionEventsBefore,
+    sleepFn = sleep,
+    nowMs = Date.now,
+    attempts = SESSION_SAY_CONFIRM_ATTEMPTS,
+    delayMs = SESSION_SAY_CONFIRM_DELAY_MS,
+    pageLimit = SESSION_SAY_CONFIRM_PAGE_LIMIT,
+    maxPages = SESSION_SAY_CONFIRM_MAX_PAGES,
+    totalTimeoutMs = SESSION_SAY_CONFIRM_TOTAL_TIMEOUT_MS,
+    requestTimeoutMs = SESSION_SAY_CONFIRM_REQUEST_TIMEOUT_MS,
+  } = {},
+) {
   let lastReason = "not_visible";
   let checked = 0;
   let pages = 0;
+  let tailChecks = 0;
   const normalizedAnchorCursor = normalizeString(anchorCursor) || null;
-  for (let attempt = 1; attempt <= SESSION_SAY_CONFIRM_ATTEMPTS; attempt += 1) {
-    let pageCursor = normalizedAnchorCursor;
-    for (let page = 1; page <= SESSION_SAY_CONFIRM_MAX_PAGES; page += 1) {
-      pages += 1;
-      const result = await pollSessionEvents(sessionId, {
+  const normalizedAttempts = normalizePositiveIntegerOrDefault(attempts, SESSION_SAY_CONFIRM_ATTEMPTS);
+  const normalizedDelayMs = normalizePositiveIntegerOrDefault(delayMs, SESSION_SAY_CONFIRM_DELAY_MS);
+  const normalizedPageLimit = normalizePositiveIntegerOrDefault(pageLimit, SESSION_SAY_CONFIRM_PAGE_LIMIT);
+  const normalizedMaxPages = normalizePositiveIntegerOrDefault(maxPages, SESSION_SAY_CONFIRM_MAX_PAGES);
+  const normalizedTotalTimeoutMs = normalizePositiveIntegerOrDefault(
+    totalTimeoutMs,
+    SESSION_SAY_CONFIRM_TOTAL_TIMEOUT_MS,
+  );
+  const normalizedRequestTimeoutMs = normalizePositiveIntegerOrDefault(
+    requestTimeoutMs,
+    SESSION_SAY_CONFIRM_REQUEST_TIMEOUT_MS,
+  );
+  const deadlineMs = (Number(nowMs()) || Date.now()) + normalizedTotalTimeoutMs;
+  const nextRequestTimeoutMs = () => {
+    const remaining = confirmationRemainingMs(deadlineMs, nowMs);
+    if (remaining <= 0) return 0;
+    return Math.max(1, Math.min(normalizedRequestTimeoutMs, remaining));
+  };
+
+  const maybeConfirmFromLatestTail = async () => {
+    const timeoutMs = nextRequestTimeoutMs();
+    if (timeoutMs <= 0) {
+      lastReason = "confirmation_timeout";
+      return null;
+    }
+    tailChecks += 1;
+    let result = null;
+    try {
+      result = await pollSessionEventsBeforeFn(sessionId, {
         targetPath,
-        since: pageCursor,
-        limit: SESSION_SAY_CONFIRM_PAGE_LIMIT,
+        limit: normalizedPageLimit,
+        timeoutMs,
         forceCircuitProbe: true,
       });
+    } catch (error) {
+      lastReason = normalizeString(error?.code || error?.message) || "confirmation_tail_poll_failed";
+      return null;
+    }
+    if (!result?.ok) {
+      lastReason = normalizeString(result?.reason) || "confirmation_tail_poll_failed";
+      return null;
+    }
+    const events = Array.isArray(result.events) ? result.events : [];
+    checked += events.length;
+    const confirmedEvent = events.find((candidate) => sessionEventMatchesClientMessageId(candidate, clientMessageId));
+    if (!confirmedEvent) {
+      lastReason = "not_visible";
+      return null;
+    }
+    return {
+      confirmed: true,
+      reason: "",
+      checked,
+      pages,
+      tailChecks,
+      source: "latest_tail",
+      anchorCursor: normalizedAnchorCursor,
+      event: confirmedEvent,
+    };
+  };
+
+  for (let attempt = 1; attempt <= normalizedAttempts; attempt += 1) {
+    let pageCursor = normalizedAnchorCursor;
+    for (let page = 1; page <= normalizedMaxPages; page += 1) {
+      const timeoutMs = nextRequestTimeoutMs();
+      if (timeoutMs <= 0) {
+        return {
+          confirmed: false,
+          reason: "confirmation_timeout",
+          checked,
+          pages,
+          tailChecks,
+          anchorCursor: normalizedAnchorCursor,
+        };
+      }
+      pages += 1;
+      let result = null;
+      try {
+        result = await pollSessionEventsFn(sessionId, {
+          targetPath,
+          since: pageCursor,
+          limit: normalizedPageLimit,
+          timeoutMs,
+          forceCircuitProbe: true,
+        });
+      } catch (error) {
+        lastReason = normalizeString(error?.code || error?.message) || "confirmation_poll_failed";
+        break;
+      }
       if (!result?.ok) {
         lastReason = normalizeString(result?.reason) || "confirmation_poll_failed";
         break;
@@ -229,6 +341,8 @@ async function confirmSessionEventVisible(sessionId, clientMessageId, { targetPa
           reason: "",
           checked,
           pages,
+          tailChecks,
+          source: "forward_cursor",
           anchorCursor: normalizedAnchorCursor,
           event: confirmedEvent,
         };
@@ -240,8 +354,17 @@ async function confirmSessionEventVisible(sessionId, clientMessageId, { targetPa
       }
       pageCursor = nextCursor;
     }
-    if (attempt < SESSION_SAY_CONFIRM_ATTEMPTS) {
-      await sleep(SESSION_SAY_CONFIRM_DELAY_MS);
+    const tailConfirmation = await maybeConfirmFromLatestTail();
+    if (tailConfirmation) {
+      return tailConfirmation;
+    }
+    if (attempt < normalizedAttempts) {
+      const remaining = confirmationRemainingMs(deadlineMs, nowMs);
+      if (remaining <= 0) {
+        lastReason = "confirmation_timeout";
+        break;
+      }
+      await sleepFn(Math.min(normalizedDelayMs, remaining));
     }
   }
   return {
@@ -249,6 +372,7 @@ async function confirmSessionEventVisible(sessionId, clientMessageId, { targetPa
     reason: lastReason,
     checked,
     pages,
+    tailChecks,
     anchorCursor: normalizedAnchorCursor,
   };
 }
@@ -1058,6 +1182,44 @@ async function findReusableSessionCandidate({
 //   - When `SENTINELAYER_SKIP_REMOTE_SYNC=1` (test bootstrap), short-circuits
 //     to `{ ok: true, source: "skipped", session: null }` so unit tests
 //     can exercise the local materialization path without a real API.
+async function fetchRemoteSessionDetail(endpoint, headers) {
+  let response;
+  try {
+    response = await fetch(endpoint, { method: "GET", headers });
+  } catch (err) {
+    return {
+      ok: false,
+      response: null,
+      status: 0,
+      reason: normalizeString(err?.message) || "fetch_failed",
+      retryable: true,
+    };
+  }
+  if (response && response.ok) {
+    return { ok: true, response, status: response.status, reason: "", retryable: false };
+  }
+  if (!response) {
+    return { ok: false, response: null, status: 0, reason: "no_response", retryable: true };
+  }
+  const status = Number(response.status) || 0;
+  return {
+    ok: false,
+    response,
+    status,
+    reason: `api_${status || "unknown"}`,
+    retryable: status >= 500 && status < 600,
+  };
+}
+
+async function parseRemoteSessionDetailResponse(response) {
+  const body = await response.json().catch(() => ({}));
+  return body && body.session && typeof body.session === "object"
+    ? body.session
+    : body && typeof body === "object"
+      ? body
+      : null;
+}
+
 async function verifyRemoteSession(sessionId, { targetPath } = {}) {
   const normalizedSessionId = normalizeString(sessionId);
   if (!normalizedSessionId) {
@@ -1085,60 +1247,43 @@ async function verifyRemoteSession(sessionId, { targetPath } = {}) {
   }
   const endpoint = `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}`;
   const headers = { Authorization: `Bearer ${auth.token}` };
-  let lastReason = "unknown";
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    let response;
-    try {
-      response = await fetch(endpoint, { method: "GET", headers });
-    } catch (err) {
-      lastReason = normalizeString(err?.message) || "fetch_failed";
-      continue;
-    }
-    if (response && response.ok) {
-      const body = await response.json().catch(() => ({}));
-      const sessionPayload = body && body.session && typeof body.session === "object"
-        ? body.session
-        : body && typeof body === "object"
-          ? body
-          : null;
-      return {
-        ok: true,
-        source: "singleton",
-        session: sessionPayload,
-        status: response.status,
-      };
-    }
-    if (!response) {
-      lastReason = "no_response";
-      continue;
-    }
-    if (response.status === 404) {
-      // Pre-#483 fallback: scan the list endpoint once for the same id.
-      const listResult = await listSessionsFromApi({
-        targetPath,
-        includeArchived: false,
-        limit: 50,
-      }).catch(() => null);
-      if (listResult && listResult.ok) {
-        const found = (listResult.sessions || []).find(
-          (entry) => normalizeString(entry?.sessionId) === normalizedSessionId,
-        );
-        if (found) {
-          return { ok: true, source: "list_fallback", session: found, status: 200 };
-        }
+  const firstAttempt = await fetchRemoteSessionDetail(endpoint, headers);
+  const detail = firstAttempt.retryable
+    ? await fetchRemoteSessionDetail(endpoint, headers)
+    : firstAttempt;
+  if (detail.ok) {
+    return {
+      ok: true,
+      source: "singleton",
+      session: await parseRemoteSessionDetailResponse(detail.response),
+      status: detail.status,
+    };
+  }
+  if (detail.status === 404) {
+    // Pre-#483 fallback: scan the list endpoint once for the same id.
+    const listResult = await listSessionsFromApi({
+      targetPath,
+      includeArchived: false,
+      limit: 50,
+    }).catch(() => null);
+    if (listResult && listResult.ok) {
+      const found = (listResult.sessions || []).find(
+        (entry) => normalizeString(entry?.sessionId) === normalizedSessionId,
+      );
+      if (found) {
+        return { ok: true, source: "list_fallback", session: found, status: 200 };
       }
-      return { ok: false, reason: "not_found", status: 404 };
-    }
-    if (response.status === 403) {
-      return { ok: false, reason: "forbidden", status: 403 };
-    }
-    if (response.status >= 500 && response.status < 600) {
-      lastReason = `api_${response.status}`;
-      continue; // retry once on 5xx
     }
-    return { ok: false, reason: `api_${response.status}`, status: response.status };
+    return { ok: false, reason: "not_found", status: 404 };
   }
-  return { ok: false, reason: lastReason };
+  if (detail.status === 403) {
+    return { ok: false, reason: "forbidden", status: 403 };
+  }
+  return {
+    ok: false,
+    reason: detail.reason || "unknown",
+    status: detail.status || undefined,
+  };
 }
 
 function normalizeRemoteResumeStatus(session = {}) {
@@ -1953,6 +2098,18 @@ function isSessionControlEvent(event = {}) {
   return normalizeString(payload.source).toLowerCase() === "session_listen";
 }
 
+function summarizeSessionTailEvent(event = null) {
+  if (!event || typeof event !== "object") return null;
+  return {
+    type: normalizeString(event.event || event.type) || null,
+    sequenceId: Number(event.sequenceId ?? event.sequence_id) || null,
+    cursor: normalizeString(event.cursor) || null,
+    ts: normalizeString(event.ts || event.timestamp) || null,
+    agentId: normalizeString(event.agent?.id || event.agentId || event.agent_id) || null,
+    control: isSessionControlEvent(event),
+  };
+}
+
 function checkpointSequenceRange(checkpoint = {}) {
   const start = Number(checkpoint.startSequence || 0);
   const end = Number(checkpoint.endSequence || 0);
@@ -4606,6 +4763,7 @@ export function registerSessionCommand(program) {
       let hydration = null;
       let remoteTail = null;
       let remoteActions = null;
+      let remoteTailStats = null;
       if (options.remote) {
         const authSession = await resolveActiveAuthSession({
           cwd: targetPath,
@@ -4632,6 +4790,23 @@ export function registerSessionCommand(program) {
             timeoutMs: 15_000,
           });
         }
+        const remoteTailEvents = remoteTail?.ok && Array.isArray(remoteTail.events) ? remoteTail.events : [];
+        const latestEvent = remoteTailEvents[remoteTailEvents.length - 1] || null;
+        const latestVisibleEvent = [...remoteTailEvents]
+          .reverse()
+          .find((event) => includeControlEvents || !isSessionControlEvent(event)) || null;
+        const controlEventCount = remoteTailEvents.filter((event) => isSessionControlEvent(event)).length;
+        remoteTailStats = {
+          controlEventCount,
+          materialEventCount: Math.max(0, remoteTailEvents.length - controlEventCount),
+          latestEvent: summarizeSessionTailEvent(latestEvent),
+          latestVisibleEvent: summarizeSessionTailEvent(latestVisibleEvent),
+          latestActivityHidden: Boolean(
+            latestEvent &&
+              isSessionControlEvent(latestEvent) &&
+              !includeControlEvents
+          ),
+        };
         if (!emitJson) {
           if (hydration.ok) {
             console.log(
@@ -4660,6 +4835,16 @@ export function registerSessionCommand(program) {
               ),
             );
           }
+          if (remoteTailStats.latestActivityHidden) {
+            const latest = remoteTailStats.latestEvent;
+            const type = latest?.type || "control event";
+            const seq = latest?.sequenceId ? ` seq=${latest.sequenceId}` : "";
+            console.log(
+              pc.gray(
+                `Latest remote activity is hidden control-plane traffic (${type}${seq}); showing recent material messages. Use --include-control-events to inspect it.`,
+              ),
+            );
+          }
         }
       }
 
@@ -4757,6 +4942,11 @@ export function registerSessionCommand(program) {
                       verified: Boolean(remoteTail.ok),
                       appended: remoteTailAppended,
                       displayedOnly: remoteTailDisplayedOnly,
+                      controlEventCount: remoteTailStats?.controlEventCount || 0,
+                      materialEventCount: remoteTailStats?.materialEventCount || 0,
+                      latestEvent: remoteTailStats?.latestEvent || null,
+                      latestVisibleEvent: remoteTailStats?.latestVisibleEvent || null,
+                      latestActivityHidden: Boolean(remoteTailStats?.latestActivityHidden),
                     }
                   : null,
                 actions: remoteActions

package/src/legacy-cli.js

@@ -1298,6 +1298,8 @@ async function runLocalOmarGateCommand(args) {
   const maxCostUsd = parseFloat(getCommandOptionValue(args, "--max-cost") || "5.0") || 5.0;
   const modelOverride = getCommandOptionValue(args, "--model") || "";
   const providerOverride = getCommandOptionValue(args, "--provider") || "";
+  const notifySession = getCommandOptionValue(args, "--notify-session") || "";
+  const requireUsageLedger = hasCommandOption(args, "--require-usage-ledger");
   const scanMode = getCommandOptionValue(args, "--scan-mode") || "deep";
   const maxParallel = parseInt(getCommandOptionValue(args, "--max-parallel") || "4", 10) || 4;
   const streamEnabled = hasCommandOption(args, "--stream");
@@ -1388,6 +1390,8 @@ async function runLocalOmarGateCommand(args) {
         onEvent: streamHandler,
         includeOnly: includeOnly.length > 0 ? includeOnly : null,
         skipPersonas: skipPersonas.length > 0 ? skipPersonas : null,
+        usageSessionId: notifySession,
+        requireUsageLedger,
       });
 
       // Use orchestrator results as the AI layer. aiResult represents ONLY
@@ -1415,6 +1419,7 @@ async function runLocalOmarGateCommand(args) {
           status: p.status,
           findings: p.findings || 0,
           costUsd: p.costUsd || 0,
+          billing: p.billing || null,
           durationMs: p.durationMs || 0,
           error: p.error || null,
         })),
@@ -1445,8 +1450,17 @@ async function runLocalOmarGateCommand(args) {
         outputDir: outputDirArg,
         provider: providerOverride || undefined,
         model: modelOverride || undefined,
+        sessionId: notifySession,
         maxCostUsd,
         dryRun: aiDryRun,
+        requireUsageLedger,
+        sourceCommand: "omargate deep",
+        billingAgentId: "omargate-orchestrator",
+        billingAction: "omargate_deep",
+        billingMetadata: {
+          scanMode,
+        },
+        usageFailureLabel: "OmarGate AI",
         env: process.env,
       });
     } catch (aiError) {

package/src/mcp/session-stdio-server.js

@@ -22,6 +22,8 @@ const SESSION_MCP_CONFIRM_ATTEMPTS = 3;
 const SESSION_MCP_CONFIRM_DELAY_MS = 250;
 const SESSION_MCP_CONFIRM_PAGE_LIMIT = 200;
 const SESSION_MCP_CONFIRM_MAX_PAGES = 10;
+const SESSION_MCP_CONFIRM_TOTAL_TIMEOUT_MS = 10_000;
+const SESSION_MCP_CONFIRM_REQUEST_TIMEOUT_MS = 2_000;
 const JSON_RPC_VERSION = "2.0";
 const CONTENT_LENGTH_PREFIX = "content-length:";
 
@@ -48,6 +50,11 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.floor(normalized);
 }
 
+function confirmationRemainingMs(deadlineMs, nowMs) {
+  const now = Number(nowMs()) || Date.now();
+  return Math.max(0, Math.floor(deadlineMs - now));
+}
+
 function normalizeLimit(value) {
   return Math.max(1, Math.min(MAX_TOOL_LIMIT, normalizePositiveInteger(value, DEFAULT_TOOL_LIMIT)));
 }
@@ -199,32 +206,111 @@ async function confirmSessionEventVisible(
     targetPath,
     anchorCursor = null,
     pollSessionEventsFn = pollSessionEvents,
+    pollSessionEventsBeforeFn = pollSessionEventsBefore,
     sleepFn = sleep,
+    nowMs = Date.now,
     attempts = SESSION_MCP_CONFIRM_ATTEMPTS,
     delayMs = SESSION_MCP_CONFIRM_DELAY_MS,
     pageLimit = SESSION_MCP_CONFIRM_PAGE_LIMIT,
     maxPages = SESSION_MCP_CONFIRM_MAX_PAGES,
+    totalTimeoutMs = SESSION_MCP_CONFIRM_TOTAL_TIMEOUT_MS,
+    requestTimeoutMs = SESSION_MCP_CONFIRM_REQUEST_TIMEOUT_MS,
   } = {},
 ) {
   let lastReason = "not_visible";
   let checked = 0;
   let pages = 0;
+  let tailChecks = 0;
   const normalizedAnchorCursor = normalizeString(anchorCursor) || null;
   const normalizedAttempts = normalizePositiveInteger(attempts, SESSION_MCP_CONFIRM_ATTEMPTS);
   const normalizedDelayMs = normalizePositiveInteger(delayMs, SESSION_MCP_CONFIRM_DELAY_MS);
   const normalizedPageLimit = normalizeLimit(pageLimit);
   const normalizedMaxPages = normalizePositiveInteger(maxPages, SESSION_MCP_CONFIRM_MAX_PAGES);
+  const normalizedTotalTimeoutMs = normalizePositiveInteger(
+    totalTimeoutMs,
+    SESSION_MCP_CONFIRM_TOTAL_TIMEOUT_MS,
+  );
+  const normalizedRequestTimeoutMs = normalizePositiveInteger(
+    requestTimeoutMs,
+    SESSION_MCP_CONFIRM_REQUEST_TIMEOUT_MS,
+  );
+  const deadlineMs = (Number(nowMs()) || Date.now()) + normalizedTotalTimeoutMs;
+  const nextRequestTimeoutMs = () => {
+    const remaining = confirmationRemainingMs(deadlineMs, nowMs);
+    if (remaining <= 0) return 0;
+    return Math.max(1, Math.min(normalizedRequestTimeoutMs, remaining));
+  };
 
-  for (let attempt = 1; attempt <= normalizedAttempts; attempt += 1) {
-    let pageCursor = normalizedAnchorCursor;
-    for (let page = 1; page <= normalizedMaxPages; page += 1) {
-      pages += 1;
-      const result = await pollSessionEventsFn(sessionId, {
+  const maybeConfirmFromLatestTail = async () => {
+    const timeoutMs = nextRequestTimeoutMs();
+    if (timeoutMs <= 0) {
+      lastReason = "confirmation_timeout";
+      return null;
+    }
+    tailChecks += 1;
+    let result = null;
+    try {
+      result = await pollSessionEventsBeforeFn(sessionId, {
         targetPath,
-        since: pageCursor,
         limit: normalizedPageLimit,
+        timeoutMs,
         forceCircuitProbe: true,
       });
+    } catch (error) {
+      lastReason = normalizeString(error?.code || error?.message) || "confirmation_tail_poll_failed";
+      return null;
+    }
+    if (!result?.ok) {
+      lastReason = normalizeString(result?.reason) || "confirmation_tail_poll_failed";
+      return null;
+    }
+    const events = Array.isArray(result.events) ? result.events : [];
+    checked += events.length;
+    const confirmedEvent = events.find((candidate) => sessionEventMatchesClientMessageId(candidate, clientMessageId));
+    if (!confirmedEvent) {
+      lastReason = "not_visible";
+      return null;
+    }
+    return {
+      confirmed: true,
+      reason: "",
+      checked,
+      pages,
+      tailChecks,
+      source: "latest_tail",
+      anchorCursor: normalizedAnchorCursor,
+      event: confirmedEvent,
+    };
+  };
+
+  for (let attempt = 1; attempt <= normalizedAttempts; attempt += 1) {
+    let pageCursor = normalizedAnchorCursor;
+    for (let page = 1; page <= normalizedMaxPages; page += 1) {
+      const timeoutMs = nextRequestTimeoutMs();
+      if (timeoutMs <= 0) {
+        return {
+          confirmed: false,
+          reason: "confirmation_timeout",
+          checked,
+          pages,
+          tailChecks,
+          anchorCursor: normalizedAnchorCursor,
+        };
+      }
+      pages += 1;
+      let result = null;
+      try {
+        result = await pollSessionEventsFn(sessionId, {
+          targetPath,
+          since: pageCursor,
+          limit: normalizedPageLimit,
+          timeoutMs,
+          forceCircuitProbe: true,
+        });
+      } catch (error) {
+        lastReason = normalizeString(error?.code || error?.message) || "confirmation_poll_failed";
+        break;
+      }
       if (!result?.ok) {
         lastReason = normalizeString(result?.reason) || "confirmation_poll_failed";
         break;
@@ -238,6 +324,8 @@ async function confirmSessionEventVisible(
           reason: "",
           checked,
           pages,
+          tailChecks,
+          source: "forward_cursor",
           anchorCursor: normalizedAnchorCursor,
           event: confirmedEvent,
         };
@@ -249,8 +337,17 @@ async function confirmSessionEventVisible(
       }
       pageCursor = nextCursor;
     }
+    const tailConfirmation = await maybeConfirmFromLatestTail();
+    if (tailConfirmation) {
+      return tailConfirmation;
+    }
     if (attempt < normalizedAttempts) {
-      await sleepFn(normalizedDelayMs);
+      const remaining = confirmationRemainingMs(deadlineMs, nowMs);
+      if (remaining <= 0) {
+        lastReason = "confirmation_timeout";
+        break;
+      }
+      await sleepFn(Math.min(normalizedDelayMs, remaining));
     }
   }
 
@@ -259,6 +356,7 @@ async function confirmSessionEventVisible(
     reason: lastReason,
     checked,
     pages,
+    tailChecks,
     anchorCursor: normalizedAnchorCursor,
   };
 }
@@ -441,6 +539,7 @@ async function persistSessionEvent({
     targetPath,
     anchorCursor: remoteConfirmationAnchor.cursor,
     pollSessionEventsFn,
+    pollSessionEventsBeforeFn,
     sleepFn,
     attempts: confirmationAttempts,
     delayMs: confirmationDelayMs,

package/src/review/ai-review.js

@@ -8,7 +8,7 @@ import {
   resolveProvider,
 } from "../ai/client.js";
 import { computeProviderCost } from "../billing/price-book.js";
-import { buildBillingRunId, buildCallIdempotencyKey } from "../billing/ledger-entry.js";
+import { buildBillingRunId, buildCallIdempotencyKey, sanitizeBillingMetadata } from "../billing/ledger-entry.js";
 import { recordSessionUsage } from "../billing/session-usage.js";
 import { loadConfig } from "../config/service.js";
 import { evaluateBudget } from "../cost/budget.js";
@@ -488,6 +488,12 @@ export async function runAiReviewLayer({
   dryRun = false,
   requireUsageLedger = false,
   usageRecorder = recordSessionUsage,
+  sourceCommand = "review",
+  billingAgentId = "audit-orchestrator",
+  billingAction = "audit_run",
+  billingTier = "internal",
+  billingMetadata = {},
+  usageFailureLabel = "Review AI",
   env = process.env,
 } = {}) {
   const normalizedTargetPath = path.resolve(String(targetPath || "."));
@@ -499,6 +505,12 @@ export async function runAiReviewLayer({
   );
   const normalizedRunId = normalizeString(runId) || "review-ai";
   const normalizedRequireUsageLedger = Boolean(requireUsageLedger);
+  const normalizedSourceCommand = normalizeString(sourceCommand) || "review";
+  const normalizedBillingAgentId = normalizeString(billingAgentId) || "audit-orchestrator";
+  const normalizedBillingAction = normalizeString(billingAction) || "audit_run";
+  const normalizedBillingTier = normalizeString(billingTier) || "internal";
+  const normalizedBillingMetadata = sanitizeBillingMetadata(billingMetadata);
+  const normalizedUsageFailureLabel = normalizeString(usageFailureLabel) || "Review AI";
 
   const config = await loadConfig({ cwd: normalizedTargetPath, env });
   let resolvedProvider = resolveProvider({
@@ -641,7 +653,7 @@ export async function runAiReviewLayer({
         toolCalls: 1,
       },
       metadata: {
-        sourceCommand: "review",
+        sourceCommand: normalizedSourceCommand,
         layer: "ai_reasoning",
         provider: resolvedProvider,
         model: resolvedModel,
@@ -657,28 +669,31 @@ export async function runAiReviewLayer({
       sessionId: normalizedSessionId,
       invocationTimestamp: startedAtIso,
       configHash: stableConfigHash({
-        sourceCommand: "review",
+        sourceCommand: normalizedSourceCommand,
         layer: "ai_reasoning",
         provider: resolvedProvider,
         model: resolvedModel,
         mode: normalizedMode,
         runId: normalizedRunId,
         dryRun: Boolean(dryRun),
+        billingAgentId: normalizedBillingAgentId,
+        billingAction: normalizedBillingAction,
       }),
     });
     sessionUsageLedger = await usageRecorder(
       normalizedSessionId,
       {
-        agentId: "audit-orchestrator",
-        action: "audit_run",
+        agentId: normalizedBillingAgentId,
+        action: normalizedBillingAction,
         model: resolvedModel,
         inputTokens,
         outputTokens,
         idempotencyKey: buildCallIdempotencyKey({ runId: billingRunId, callIndex: 0 }),
-        billingTier: "internal",
+        billingTier: normalizedBillingTier,
         createdAt: startedAtIso,
         metadata: {
-          sourceCommand: "review",
+          ...normalizedBillingMetadata,
+          sourceCommand: normalizedSourceCommand,
           layer: "ai_reasoning",
           provider: resolvedProvider,
           mode: normalizedMode,
@@ -698,7 +713,7 @@ export async function runAiReviewLayer({
     };
     if (normalizedRequireUsageLedger) {
       throw new Error(
-        `Review AI usage ledger recording failed: ${sessionUsageLedger.reason || "unknown"}.`
+        `${normalizedUsageFailureLabel} usage ledger recording failed: ${sessionUsageLedger.reason || "unknown"}.`
       );
     }
   }
@@ -729,7 +744,7 @@ export async function runAiReviewLayer({
           reasonCodes: budget.reasons.map((reason) => reason.code),
         },
         metadata: {
-          sourceCommand: "review",
+          sourceCommand: normalizedSourceCommand,
           layer: "ai_reasoning",
           provider: resolvedProvider,
           model: resolvedModel,

package/src/review/omargate-orchestrator.js

@@ -423,6 +423,10 @@ function omargateConfidenceFloorForPersona(personaId) {
   return OMARGATE_CONFIDENCE_FLOORS[personaId] || OMARGATE_DEFAULT_CONFIDENCE_FLOOR;
 }
 
+function isUsageLedgerFailure(message = "") {
+  return /usage ledger/i.test(String(message || ""));
+}
+
 async function runOmarPersonaSwarm({
   personaId,
   identity,
@@ -436,6 +440,9 @@ async function runOmarPersonaSwarm({
   perPersonaCost,
   dryRun,
   onEvent,
+  usageSessionId = "",
+  requireUsageLedger = false,
+  usageRecorder = undefined,
 } = {}) {
   const scope = buildPersonaFileScope({ deterministic });
   const decision = decideSwarm({ scope });
@@ -537,10 +544,26 @@ async function runOmarPersonaSwarm({
           outputDir,
           provider: provider || undefined,
           model: model || undefined,
-          sessionId: `${subagentRunId}-ai`,
+          sessionId: usageSessionId || `${subagentRunId}-ai`,
           maxCostUsd: budget.maxCostUsd,
           systemPrompt,
           dryRun,
+          requireUsageLedger,
+          usageRecorder,
+          sourceCommand: "omargate deep",
+          billingAgentId: `omargate-${personaId}-subagent-${subagentIndex}`,
+          billingAction: "omargate_deep",
+          billingMetadata: {
+            personaId,
+            subagentIndex,
+            partitionCount: partitions.length,
+            parentRunId: runId,
+            swarmRunId,
+            subagentRunId,
+            scanMode: mode,
+            fileCount: scopedFiles.length,
+          },
+          usageFailureLabel: "OmarGate AI",
           env: process.env,
         });
 
@@ -610,6 +633,7 @@ async function runOmarPersonaSwarm({
           summary: result?.summary || summarizeFindings(findings),
           costUsd: result?.usage?.costUsd || 0,
           model: result?.model || model || null,
+          billing: result?.billing || null,
           artifacts: result?.artifacts || null,
           durationMs: Date.now() - subagentStart,
         };
@@ -671,6 +695,41 @@ async function runOmarPersonaSwarm({
   const summary = summarizeFindings(findings);
   const okCount = settledSubagents.filter((result) => result.status === "ok").length;
   const errorCount = settledSubagents.filter((result) => result.status === "error").length;
+  const usageLedgerErrors = settledSubagents.filter((result) =>
+    result.status === "error" && isUsageLedgerFailure(result.error)
+  );
+  if (requireUsageLedger && usageLedgerErrors.length > 0) {
+    return {
+      personaId,
+      status: "error",
+      findings: [],
+      summary: { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false },
+      costUsd: totalCostUsd,
+      model: model || null,
+      durationMs: Date.now() - startedAt,
+      error: `OmarGate required usage ledger failed for ${usageLedgerErrors.length}/${settledSubagents.length} subagent(s).`,
+      swarm: {
+        runId: swarmRunId,
+        decision,
+        subagentCount: settledSubagents.length,
+        ok: okCount,
+        error: errorCount,
+        partitionSizes: partitions.map((files) => files.length),
+        blackboardEntries: blackboard.length,
+        subagents: settledSubagents.map((result) => ({
+          id: result.agentId,
+          index: result.subagentIndex,
+          status: result.status,
+          files: result.files,
+          findings: (result.findings || []).length,
+          costUsd: result.costUsd || 0,
+          durationMs: result.durationMs || 0,
+          error: result.error || null,
+          artifacts: result.artifacts || null,
+        })),
+      },
+    };
+  }
 
   if (onEvent) {
     onEvent(createAgentEvent({
@@ -723,6 +782,7 @@ async function runOmarPersonaSwarm({
         files: result.files,
         findings: (result.findings || []).length,
         costUsd: result.costUsd || 0,
+        billing: result.billing || null,
         durationMs: result.durationMs || 0,
         error: result.error || null,
         artifacts: result.artifacts || null,
@@ -747,6 +807,8 @@ async function runOmarPersonaSwarm({
  * @param {Function} [options.onEvent] - Event callback for streaming
  * @param {string[] | null} [options.includeOnly] - Only run these persona IDs (filters scan-mode roster).
  * @param {string[] | null} [options.skipPersonas] - Skip these persona IDs (filters scan-mode roster).
+ * @param {boolean} [options.requireUsageLedger] - Fail if Omar Deep AI calls cannot write billing-grade session_usage.
+ * @param {string} [options.usageSessionId] - Optional shared Senti session id for billing-grade usage entries.
  * @returns {Promise<object>} Orchestrated results
  */
 export async function runOmarGateOrchestrator({
@@ -762,6 +824,9 @@ export async function runOmarGateOrchestrator({
   onEvent = null,
   includeOnly = null,
   skipPersonas = null,
+  requireUsageLedger = false,
+  usageSessionId = "",
+  usageRecorder = undefined,
 } = {}) {
   const runId = `omargate-${Date.now()}-${randomUUID().slice(0, 8)}`;
   const startTime = Date.now();
@@ -931,6 +996,9 @@ export async function runOmarGateOrchestrator({
         perPersonaCost,
         dryRun,
         onEvent,
+        requireUsageLedger,
+        usageSessionId,
+        usageRecorder,
       });
 
       if (swarmResult) {
@@ -999,9 +1067,21 @@ export async function runOmarGateOrchestrator({
         outputDir,
         provider: provider || undefined,
         model: model || undefined,
+        sessionId: usageSessionId || `${runId}-${personaId}-ai`,
         maxCostUsd: perPersonaCost,
         systemPrompt,
         dryRun,
+        requireUsageLedger,
+        usageRecorder,
+        sourceCommand: "omargate deep",
+        billingAgentId: `omargate-${personaId}`,
+        billingAction: "omargate_deep",
+        billingMetadata: {
+          personaId,
+          parentRunId: runId,
+          scanMode: mode,
+        },
+        usageFailureLabel: "OmarGate AI",
         env: process.env,
       });
 
@@ -1062,6 +1142,7 @@ export async function runOmarGateOrchestrator({
         summary: result?.summary || { P0: 0, P1: 0, P2: 0, P3: 0 },
         costUsd: personaCost,
         model: result?.model || model || null,
+        billing: result?.billing || null,
         artifacts: result?.artifacts || null,
         durationMs: Date.now() - personaStart,
       };
@@ -1106,6 +1187,18 @@ export async function runOmarGateOrchestrator({
           durationMs: 0,
         })
   );
+  const usageLedgerFailures = settled.filter((r) =>
+    r.status === "error" && isUsageLedgerFailure(r.error)
+  );
+  if (requireUsageLedger && usageLedgerFailures.length > 0) {
+    const examples = usageLedgerFailures
+      .slice(0, 3)
+      .map((r) => `${r.personaId}: ${r.error}`)
+      .join("; ");
+    throw new Error(
+      `OmarGate required usage ledger recording failed for ${usageLedgerFailures.length}/${settled.length} persona(s).${examples ? ` ${examples}` : ""}`
+    );
+  }
 
   // Reconcile AI findings with deterministic findings — canonical single list.
   // Confidence boost when multiple layers agree; deterministic findings get
@@ -1183,6 +1276,7 @@ export async function runOmarGateOrchestrator({
       costUsd: r.costUsd,
       durationMs: r.durationMs,
       model: r.model || null,
+      billing: r.billing || null,
       error: r.error || null,
       swarm: r.swarm || null,
       artifacts: r.artifacts || null,