sentinelayer-cli 0.34.5 → 0.34.7

package/package.json

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

package/src/commands/session.js

@@ -109,6 +109,7 @@ import {
 } from "../session/rotating-log.js";
 import { buildSessionRecap } from "../session/recap.js";
 import { computeTranscriptStats } from "../session/transcript.js";
+import { buildSessionUsageLedger } from "../session/pricing-ledger.js";
 import {
   buildSessionUsageReport,
   buildSessionUsageReportFromLedgerPayload,
@@ -150,6 +151,22 @@ function normalizeString(value) {
   return String(value || "").trim();
 }
 
+// A wake hook hands remote-influenced event fields to a local host command
+// (as SL_WAKE_* env vars). Bound + strip each value so a crafted event cannot
+// inject control chars / newlines into the child environment or blow it up.
+const WAKE_VALUE_MAX_LENGTH = 512;
+function sanitizeWakeValue(value) {
+  // Strip control chars (incl. NUL / newline) by codepoint so a crafted remote
+  // event cannot inject into the child env; a codepoint check avoids putting a
+  // control-char regex literal in source.
+  let out = "";
+  for (const ch of normalizeString(value)) {
+    const code = ch.codePointAt(0);
+    out += code < 0x20 || code === 0x7f ? " " : ch;
+  }
+  return out.slice(0, WAKE_VALUE_MAX_LENGTH);
+}
+
 function messagePartsHaveContent(messageParts) {
   const parts = Array.isArray(messageParts) ? messageParts : [messageParts];
   return parts.some((part) => normalizeString(part));
@@ -2160,14 +2177,28 @@ export function createSessionWakeRunner({
       return;
     }
     busy = true;
+    const rawSequence = event?.sequenceId ?? event?.sequence_id ?? "";
+    const sanitizedSequence = sanitizeWakeValue(rawSequence);
     const env = {
       ...process.env,
-      SL_WAKE_SESSION_ID: normalizeString(sessionId),
-      SL_WAKE_AGENT_ID: normalizeString(agentId),
-      SL_WAKE_EVENT_TYPE: normalizeString(event?.event),
-      SL_WAKE_EVENT_CURSOR: normalizeString(event?.cursor),
-      SL_WAKE_EVENT_SEQUENCE: String(event?.sequenceId ?? event?.sequence_id ?? ""),
-      SL_WAKE_ACTOR_ID: normalizeString(event?.agent?.id || event?.agentId),
+      SL_WAKE_SESSION_ID: sanitizeWakeValue(sessionId),
+      SL_WAKE_AGENT_ID: sanitizeWakeValue(agentId),
+      SL_WAKE_EVENT_TYPE: sanitizeWakeValue(event?.event),
+      SL_WAKE_EVENT_CURSOR: sanitizeWakeValue(event?.cursor),
+      SL_WAKE_EVENT_SEQUENCE: sanitizedSequence,
+      SL_WAKE_ACTOR_ID: sanitizeWakeValue(event?.agent?.id || event?.agentId),
+    };
+    // Metadata-only wake envelope for the host command's stdin. Deliberately
+    // EXCLUDES the event body/content so session message text / PII never
+    // reaches an external process — the woken agent re-reads the room over its
+    // own authenticated channel using this cursor/sequence.
+    const wakePayload = {
+      event: env.SL_WAKE_EVENT_TYPE,
+      sessionId: env.SL_WAKE_SESSION_ID,
+      agentId: env.SL_WAKE_AGENT_ID,
+      cursor: env.SL_WAKE_EVENT_CURSOR,
+      sequenceId: typeof rawSequence === "number" && Number.isFinite(rawSequence) ? rawSequence : sanitizedSequence || null,
+      actorId: env.SL_WAKE_ACTOR_ID,
     };
     let child;
     try {
@@ -2185,7 +2216,7 @@ export function createSessionWakeRunner({
     });
     try {
       if (child && child.stdin) {
-        child.stdin.write(JSON.stringify(event ?? {}));
+        child.stdin.write(JSON.stringify(wakePayload));
         child.stdin.end();
       }
     } catch {
@@ -4509,7 +4540,7 @@ export function registerSessionCommand(program) {
     .option("--max-polls <n>", "Stop after N poll cycles (useful for tests and smoke checks)")
     .option(
       "--wake <command>",
-      "Wake hook: run this shell command on each matched event (notify->resume bridge). Event JSON is piped to stdin; SL_WAKE_* env vars are set.",
+      "Wake hook: run this shell command on each matched event (notify->resume bridge). Metadata JSON is piped to stdin; sanitized SL_WAKE_* env vars are set.",
     )
     .option(
       "--wake-host <name>",
@@ -6267,9 +6298,14 @@ export function registerSessionCommand(program) {
       const hiddenControlEventCount =
         dedupedEvents.length - transcriptBaseEvents.length + rawActionEvents.length - actionEvents.length;
       const exportEvents = mergeSessionActionEvents(transcriptBaseEvents, actionEvents);
+      const usageLedger = buildSessionUsageLedger(exportEvents, {
+        sessionId: normalizedSessionId,
+        includeEstimatedMessages: true,
+      });
       const stats = computeTranscriptStats({
         sessionMeta: sessionPayload,
         events: exportEvents,
+        usageLedger,
       });
       const participants = buildSessionParticipants({
         statsAgents: stats.agents,

package/src/scan/generator.js

@@ -227,16 +227,21 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
             with: {
               github_token: "${{ github.token }}",
               openai_api_key: "${{ secrets.OPENAI_API_KEY }}",
-              google_api_key: "${{ secrets.GOOGLE_API_KEY }}",
-              llm_provider: "${{ secrets.GOOGLE_API_KEY != '' && 'google' || 'openai' }}",
+              google_api_key:
+                "${{ secrets.GOOGLE_GEMINI_API_KEY != '' && secrets.GOOGLE_GEMINI_API_KEY || secrets.GOOGLE_API_KEY }}",
+              llm_provider:
+                "${{ secrets.OPENAI_API_KEY != '' && 'openai' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'google' || 'openai') }}",
               sentinelayer_token: `\${{ secrets.${normalizedSecret} }}`,
-              sentinelayer_managed_llm: `\${{ secrets.GOOGLE_API_KEY == '' && secrets.OPENAI_API_KEY == '' && secrets.${normalizedSecret} != '' }}`,
+              sentinelayer_managed_llm: `\${{ secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '' && secrets.OPENAI_API_KEY == '' && secrets.${normalizedSecret} != '' }}`,
               scan_mode: profile.scanMode || "deep",
               severity_gate: profile.severityGate || "P1",
-              model: "${{ secrets.GOOGLE_API_KEY != '' && 'gemini-2.5-pro' || 'gpt-5.3-codex' }}",
+              model:
+                "${{ secrets.OPENAI_API_KEY != '' && 'gpt-5.3-codex' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-5.3-codex') }}",
               codex_model: "gpt-5.3-codex",
-              model_fallback: "${{ secrets.GOOGLE_API_KEY != '' && 'gemini-2.5-flash' || 'gpt-4.1-mini' }}",
-              use_codex: "${{ secrets.GOOGLE_API_KEY == '' }}",
+              model_fallback:
+                "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-4.1-mini' }}",
+              use_codex:
+                "${{ secrets.OPENAI_API_KEY != '' || (secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '') }}",
               codex_only: "false",
               llm_failure_policy: "block",
               max_daily_scans: "${{ vars.OMAR_MAX_DAILY_SCANS || '200' }}",
@@ -295,11 +300,15 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
               OMAR_SEVERITY_GATE: "${{ github.event_name == 'workflow_dispatch' && inputs.severity_gate || 'P1' }}",
               OMAR_P2_MAX_ALLOWED: "${{ github.event_name == 'workflow_dispatch' && inputs.p2_max_allowed || '5' }}",
               OMAR_OPENAI_KEY_PRESENT: "${{ secrets.OPENAI_API_KEY != '' }}",
-              OMAR_GOOGLE_KEY_PRESENT: "${{ secrets.GOOGLE_API_KEY != '' }}",
-              OMAR_MANAGED_LLM: `\${{ secrets.GOOGLE_API_KEY == '' && secrets.OPENAI_API_KEY == '' && secrets.${normalizedSecret} != '' }}`,
-              OMAR_LLM_PROVIDER: "${{ secrets.GOOGLE_API_KEY != '' && 'google' || 'openai' }}",
-              OMAR_MODEL: "${{ secrets.GOOGLE_API_KEY != '' && 'gemini-2.5-pro' || 'gpt-5.3-codex' }}",
-              OMAR_MODEL_FALLBACK: "${{ secrets.GOOGLE_API_KEY != '' && 'gemini-2.5-flash' || 'gpt-4.1-mini' }}",
+              OMAR_GOOGLE_KEY_PRESENT:
+                "${{ secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '' }}",
+              OMAR_MANAGED_LLM: `\${{ secrets.GOOGLE_GEMINI_API_KEY == '' && secrets.GOOGLE_API_KEY == '' && secrets.OPENAI_API_KEY == '' && secrets.${normalizedSecret} != '' }}`,
+              OMAR_LLM_PROVIDER:
+                "${{ secrets.OPENAI_API_KEY != '' && 'openai' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'google' || 'openai') }}",
+              OMAR_MODEL:
+                "${{ secrets.OPENAI_API_KEY != '' && 'gpt-5.3-codex' || ((secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-5.3-codex') }}",
+              OMAR_MODEL_FALLBACK:
+                "${{ (secrets.GOOGLE_GEMINI_API_KEY != '' || secrets.GOOGLE_API_KEY != '') && 'gemini-3.1-flash-lite' || 'gpt-4.1-mini' }}",
             },
             run: [
               "set -euo pipefail",
@@ -344,7 +353,7 @@ export function buildSecurityReviewWorkflow({ secretName = DEFAULT_SCAN_SECRET_N
               "        'llm_provider': env('OMAR_LLM_PROVIDER', 'openai'),",
               "        'model': env('OMAR_MODEL', 'gpt-5.3-codex'),",
               "        'model_fallback': env('OMAR_MODEL_FALLBACK', 'gpt-4.1-mini'),",
-              "        'llm_route': 'google_api_key' if bool_env('OMAR_GOOGLE_KEY_PRESENT') else ('openai_api_key' if bool_env('OMAR_OPENAI_KEY_PRESENT') else 'sentinelayer_managed'),",
+              "        'llm_route': 'openai_api_key' if bool_env('OMAR_OPENAI_KEY_PRESENT') else ('google_api_key' if bool_env('OMAR_GOOGLE_KEY_PRESENT') else 'sentinelayer_managed'),",
               "        'google_key_present': bool_env('OMAR_GOOGLE_KEY_PRESENT'),",
               "        'openai_key_present': bool_env('OMAR_OPENAI_KEY_PRESENT'),",
               "        'managed_llm': bool_env('OMAR_MANAGED_LLM'),",

package/src/session/pricing-ledger.js

@@ -4,10 +4,12 @@ import {
   DEFAULT_PRICE_BOOK_VERSION,
   estimateModelCost,
 } from "../cost/tracker.js";
+import { estimateTokens } from "../cost/tokenizer.js";
 
 const SESSION_USAGE_EVENT = "session_usage";
 export const BILLING_SESSION_USAGE_SCHEMA = "billing/v1";
 export const LOCAL_SESSION_USAGE_SCHEMA = "session_usage/local-v1";
+export const ESTIMATED_MESSAGE_USAGE_SCHEMA = "session_usage/estimated-message-v1";
 const LEGACY_SESSION_USAGE_SCHEMAS = new Set(["", "session_usage/v0"]);
 const SUPPORTED_SESSION_USAGE_SCHEMAS = new Set([
   BILLING_SESSION_USAGE_SCHEMA,
@@ -38,6 +40,19 @@ const USAGE_HINT_KEYS = [
   "cost_usd",
   "cost",
 ];
+const ESTIMATED_MESSAGE_EVENT_KINDS = new Set([
+  "agent_response",
+  "session_message",
+  "session_say",
+]);
+const HUMAN_AGENT_IDS = new Set([
+  "cli-user",
+  "human",
+  "user",
+  "you",
+]);
+const DEFAULT_ESTIMATED_MESSAGE_USAGE_DEDUPE_WINDOW_MS = 5 * 60 * 1000;
+const DEFAULT_ESTIMATED_MESSAGE_USAGE_DEDUPE_SEQUENCE_WINDOW = 3;
 
 function n(value) {
   return String(value == null ? "" : value).trim();
@@ -94,6 +109,12 @@ function roundUsd(value) {
   return Math.round(Number(value || 0) * 1_000_000) / 1_000_000;
 }
 
+function positiveInteger(value, fallbackValue) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallbackValue;
+  return Math.floor(parsed);
+}
+
 export function createSessionUsageLedgerId({
   sessionId = "",
   agentId = "",
@@ -116,6 +137,52 @@ function fallbackIdempotencyKey({ sessionId, event, agentId, action, model, tota
   return `event:${createHash("sha256").update(source).digest("hex").slice(0, 32)}`;
 }
 
+function messageEstimateIdempotencyKey({ sessionId, event, agentId, model, text }) {
+  const payload = object(event?.payload);
+  const explicit =
+    n(payload.clientMessageId || payload.client_message_id) ||
+    n(event?.eventId || event?.event_id) ||
+    n(event?.idempotencyToken || event?.idempotency_token) ||
+    n(event?.cursor);
+  if (explicit) return `estimated-message:${explicit}`;
+  const sequence = n(event?.sequenceId ?? event?.sequence_id);
+  if (sequence) return `estimated-message:seq:${sequence}`;
+  const timestamp = n(event?.ts || event?.timestamp);
+  const source = [sessionId, timestamp, agentId, model, text].join("\x1f");
+  return `estimated-message:${createHash("sha256").update(source).digest("hex").slice(0, 32)}`;
+}
+
+function isLikelyHumanAgent({ agentId = "", role = "", model = "" } = {}) {
+  const id = n(agentId).toLowerCase();
+  const normalizedRole = n(role).toLowerCase();
+  const normalizedModel = n(model).toLowerCase();
+  if (!id && !normalizedModel) return true;
+  if (HUMAN_AGENT_IDS.has(id)) return true;
+  if (id.startsWith("human-") || id.startsWith("user-")) return true;
+  if (normalizedModel === "human") return true;
+  const agentLikeRole = ["coder", "reviewer", "tester", "observer", "orchestrator"].includes(normalizedRole);
+  const agentLikeId = /(codex|claude|gpt|gemini|grok|senti|kai-chen|agent|bot|warden|architect|builder)/i.test(id);
+  const agentLikeModel = /(gpt|claude|gemini|grok|codex|sonnet|opus|haiku)/i.test(normalizedModel);
+  if (normalizedRole === "human") return true;
+  if (normalizedRole === "participant" && !agentLikeId && !agentLikeModel) return true;
+  if (!agentLikeRole && !agentLikeId && !agentLikeModel && (!normalizedModel || normalizedModel === "unknown")) {
+    return true;
+  }
+  return false;
+}
+
+function responseText(payload = {}) {
+  if (payload.response && typeof payload.response === "object" && !Array.isArray(payload.response)) {
+    return n(payload.response.text);
+  }
+  return n(payload.response);
+}
+
+function messageText(event = {}) {
+  const payload = object(event?.payload);
+  return n(payload.message) || responseText(payload) || n(payload.text);
+}
+
 function providerCostFromPriceBook({ model, inputTokens, outputTokens, explicitProviderCost }) {
   if (explicitProviderCost != null) {
     return { providerCostUsd: explicitProviderCost, unpriced: false };
@@ -217,9 +284,139 @@ export function buildUsageLedgerEntry(
     unpriced,
     timestamp: n(event?.ts || event?.timestamp),
     sequenceId: nonNegativeInt(event?.sequenceId ?? event?.sequence_id),
+    estimated: false,
+  };
+}
+
+export function buildEstimatedMessageLedgerEntry(
+  event,
+  {
+    sessionId = "",
+    priceBookVersion = DEFAULT_PRICE_BOOK_VERSION,
+    billingTier = "estimated",
+    includeHumanMessages = false,
+    action = "estimated_agent_message",
+  } = {},
+) {
+  const kind = n(event?.event || event?.type);
+  if (!ESTIMATED_MESSAGE_EVENT_KINDS.has(kind)) return null;
+
+  const payload = object(event?.payload);
+  if (hasUsageHints(payload) || hasUsageHints(payload.usage)) return null;
+
+  const text = messageText(event);
+  if (!text) return null;
+
+  const agent = object(event?.agent);
+  const agentId = n(agent.id || event?.agentId) || "unknown";
+  const model = n(agent.model || event?.agentModel || payload.model) || "unknown";
+  const role = n(agent.role || payload.role);
+  const lowerAgentId = agentId.toLowerCase();
+  if (lowerAgentId === "senti" || lowerAgentId === "kai-chen") {
+    return null;
+  }
+  if (!includeHumanMessages && isLikelyHumanAgent({ agentId, role, model })) {
+    return null;
+  }
+
+  const outputTokens = estimateTokens(text, {
+    model,
+    provider: n(agent.provider || payload.provider),
+  });
+  if (outputTokens <= 0) return null;
+
+  const actionName = n(action) || "estimated_agent_message";
+  const idempotencyKey = messageEstimateIdempotencyKey({
+    sessionId,
+    event,
+    agentId,
+    model,
+    text,
+  });
+  const ledgerEntryId = createSessionUsageLedgerId({
+    sessionId,
+    agentId,
+    action: actionName,
+    idempotencyKey,
+  });
+  const { providerCostUsd, unpriced } = providerCostFromPriceBook({
+    model,
+    inputTokens: 0,
+    outputTokens,
+    explicitProviderCost: null,
+  });
+
+  return {
+    ledgerEntryId,
+    idempotencyKey,
+    schema: ESTIMATED_MESSAGE_USAGE_SCHEMA,
+    sessionId: n(sessionId),
+    agentId,
+    action: actionName,
+    model,
+    priceBookVersion: n(priceBookVersion) || DEFAULT_PRICE_BOOK_VERSION,
+    billingTier: n(billingTier) || "estimated",
+    provider: n(agent.provider || payload.provider),
+    inputTokens: 0,
+    outputTokens,
+    totalTokens: outputTokens,
+    providerCostUsd: roundUsd(providerCostUsd),
+    customerCostUsd: null,
+    unpriced,
+    timestamp: n(event?.ts || event?.timestamp),
+    sequenceId: nonNegativeInt(event?.sequenceId ?? event?.sequence_id),
+    estimated: true,
   };
 }
 
+function collectRealUsageAnchors(events = [], options = {}) {
+  const anchors = new Map();
+  for (const event of events) {
+    const entry = buildUsageLedgerEntry(event, options);
+    if (!entry || entry.estimated) continue;
+    if (!anchors.has(entry.agentId)) anchors.set(entry.agentId, []);
+    anchors.get(entry.agentId).push({
+      timestampMs: Date.parse(n(entry.timestamp)),
+      sequenceId: Number.isFinite(entry.sequenceId) ? entry.sequenceId : null,
+    });
+  }
+  return anchors;
+}
+
+function hasNearbyRealUsageAnchor(entry, anchors, options = {}) {
+  if (!entry || !entry.estimated || !anchors || anchors.size === 0) return false;
+  const agentAnchors = anchors.get(entry.agentId);
+  if (!agentAnchors || agentAnchors.length === 0) return false;
+  const windowMs = positiveInteger(
+    options.estimatedMessageUsageDedupeWindowMs,
+    DEFAULT_ESTIMATED_MESSAGE_USAGE_DEDUPE_WINDOW_MS,
+  );
+  const sequenceWindow = positiveInteger(
+    options.estimatedMessageUsageDedupeSequenceWindow,
+    DEFAULT_ESTIMATED_MESSAGE_USAGE_DEDUPE_SEQUENCE_WINDOW,
+  );
+  const entryTimestampMs = Date.parse(n(entry.timestamp));
+  const hasEntryTimestamp = Number.isFinite(entryTimestampMs);
+  const entrySequenceId = Number.isFinite(entry.sequenceId) ? entry.sequenceId : null;
+  return agentAnchors.some((anchor) => {
+    if (
+      entrySequenceId !== null &&
+      Number.isFinite(anchor.sequenceId) &&
+      Math.abs(entrySequenceId - anchor.sequenceId) <= sequenceWindow
+    ) {
+      return true;
+    }
+    if (
+      hasEntryTimestamp &&
+      Number.isFinite(anchor.timestampMs) &&
+      Math.abs(entryTimestampMs - anchor.timestampMs) <= windowMs
+    ) {
+      return true;
+    }
+    return false;
+  });
+}
+
 function newRollup(label) {
   return {
     label,
@@ -231,6 +428,7 @@ function newRollup(label) {
     customerCostUsd: 0,
     hasCustomerCost: false,
     unpriced: 0,
+    estimatedEntries: 0,
   };
 }
 
@@ -245,6 +443,7 @@ function addToRollup(rollup, entry) {
     rollup.hasCustomerCost = true;
   }
   if (entry.unpriced) rollup.unpriced += 1;
+  if (entry.estimated) rollup.estimatedEntries += 1;
 }
 
 function finalizeRollup(rollup) {
@@ -257,6 +456,9 @@ export function buildSessionUsageLedger(events = [], options = {}) {
   if (!Array.isArray(events)) {
     throw new Error("events must be an array.");
   }
+  const realUsageAnchors = options.includeEstimatedMessages
+    ? collectRealUsageAnchors(events, options)
+    : new Map();
   const entries = [];
   const totals = newRollup("session");
   const perAgent = new Map();
@@ -266,8 +468,13 @@ export function buildSessionUsageLedger(events = [], options = {}) {
   let duplicatesSkipped = 0;
 
   for (const event of events) {
-    const entry = buildUsageLedgerEntry(event, options);
+    const entry =
+      buildUsageLedgerEntry(event, options) ||
+      (options.includeEstimatedMessages
+        ? buildEstimatedMessageLedgerEntry(event, options)
+        : null);
     if (!entry) continue;
+    if (hasNearbyRealUsageAnchor(entry, realUsageAnchors, options)) continue;
     const dedupeKeys = [
       entry.idempotencyKey ? `idem:${entry.idempotencyKey}` : "",
       entry.ledgerEntryId ? `ledger:${entry.ledgerEntryId}` : "",

package/src/session/recap.js

@@ -22,6 +22,23 @@ const DEFAULT_TASK_SUMMARY_LIMIT = 3;
 const DEFAULT_WORK_PLAN_SUMMARY_LIMIT = 5;
 const MAX_WORK_PLAN_BYTES = 128_000;
 const WORK_PLAN_RELATIVE_PATH = "tasks/todo.md";
+const HISTORICAL_WORK_PLAN_MIN_COMPLETED = 25;
+const HISTORICAL_WORK_PLAN_MIN_TOTAL = 50;
+const HISTORICAL_WORK_PLAN_COMPLETED_RATIO = 0.75;
+const GENERIC_WORK_PLAN_SECTIONS = new Set([
+  "plan",
+  "plans",
+  "todo",
+  "todos",
+  "to do",
+  "tasks",
+  "work items",
+  "workitems",
+  "workstream",
+  "workstreams",
+  "backlog",
+  "next",
+]);
 const RECAP_SOURCE_IGNORED_EVENTS = new Set([
   "agent_heartbeat",
   "agent_join",
@@ -458,6 +475,41 @@ function shortWorkPlanText(value) {
   return `${text.slice(0, 97)}...`;
 }
 
+function normalizedWorkPlanSection(value = "") {
+  return normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function isGenericWorkPlanSection(value = "") {
+  const normalized = normalizedWorkPlanSection(value);
+  if (!normalized) {
+    return false;
+  }
+  if (GENERIC_WORK_PLAN_SECTIONS.has(normalized)) {
+    return true;
+  }
+  return /^(active\s+)?(plan|todo|tasks|backlog)(\s+\d+)?$/.test(normalized);
+}
+
+function shouldSuppressHistoricalWorkPlanDetails(summary = emptyWorkPlanSummary()) {
+  const total = Number(summary.total || 0);
+  const open = Number(summary.open || 0);
+  const completed = Number(summary.completed || 0);
+  if (summary.truncated || open <= 0 || completed < HISTORICAL_WORK_PLAN_MIN_COMPLETED) {
+    return false;
+  }
+  if (total < HISTORICAL_WORK_PLAN_MIN_TOTAL) {
+    return false;
+  }
+  if (!isGenericWorkPlanSection(summary.currentSection)) {
+    return false;
+  }
+  return completed / Math.max(1, total) >= HISTORICAL_WORK_PLAN_COMPLETED_RATIO;
+}
+
 function summarizeWorkPlanMarkdown(
   raw = "",
   { limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT, truncated = false, sourceContext = {} } = {}
@@ -507,6 +559,10 @@ function summarizeWorkPlanMarkdown(
     .filter((record) => record.status === "open")
     .slice(-normalizedLimit);
   summary.recent = records.slice(-normalizedLimit);
+  if (!summary.detailSuppressed && shouldSuppressHistoricalWorkPlanDetails(summary)) {
+    summary.detailSuppressed = true;
+    summary.detailSuppressionReason = "historical_generic_plan_section";
+  }
   if (summary.detailSuppressed) {
     summary.currentSection = "";
     summary.recentOpen = [];
@@ -785,7 +841,15 @@ function buildWorkPlanText(workPlan = emptyWorkPlanSummary()) {
   const sourceReason = normalizeString(workPlan.sourceReason);
   const sourceReasonText = sourceReason ? ` (${sourceReason})` : "";
   if (workPlan.detailSuppressed || workPlan.truncated) {
-    return `Plan: ${open} open / ${completed} done in recent ${sourceText} window${sourceReasonText}. Current/next items suppressed because the plan file is large.`;
+    const suppressionReason = normalizeString(workPlan.detailSuppressionReason);
+    const sourceWindowText = workPlan.truncated
+      ? `recent ${sourceText} window`
+      : sourceText;
+    const suppressionText =
+      suppressionReason === "historical_generic_plan_section"
+        ? "Current/next items suppressed because this generic plan is mostly historical completed work."
+        : "Current/next items suppressed because the plan file is large.";
+    return `Plan: ${open} open / ${completed} done in ${sourceWindowText}${sourceReasonText}. ${suppressionText}`;
   }
   const currentSection = normalizeString(workPlan.currentSection);
   const currentText = currentSection ? ` Current: ${currentSection}.` : "";
@@ -814,7 +878,7 @@ function roundCurrency(value) {
 }
 
 function normalizeUsageSummary(events = []) {
-  const aggregate = aggregateSessionUsage(events);
+  const aggregate = aggregateSessionUsage(events, { includeEstimatedMessages: true });
   const totals = {
     totalTokens: Number(aggregate.totals.totalTokens || 0),
     inputTokens: Number(aggregate.totals.inputTokens || 0),

package/src/session/sync.js

@@ -349,6 +349,65 @@ function recordCircuitSuccess(circuit) {
   persistCircuitState();
 }
 
+function responseHeader(response, name) {
+  const headers = response?.headers;
+  if (!headers || !name) return "";
+  if (typeof headers.get === "function") {
+    return normalizeString(headers.get(name));
+  }
+  const lower = String(name).toLowerCase();
+  if (headers instanceof Map) {
+    for (const [key, value] of headers.entries()) {
+      if (String(key).toLowerCase() === lower) return normalizeString(value);
+    }
+    return "";
+  }
+  if (typeof headers === "object") {
+    for (const [key, value] of Object.entries(headers)) {
+      if (String(key).toLowerCase() === lower) return normalizeString(value);
+    }
+  }
+  return "";
+}
+
+function retryAfterMsFromResponse(response, payload, nowMs = Date.now()) {
+  const retryAfterMs = [
+    payload?.retryAfterMs,
+    payload?.error?.retryAfterMs,
+    payload?.detail?.retryAfterMs,
+  ].map(Number).find((value) => Number.isFinite(value) && value > 0);
+  if (Number.isFinite(retryAfterMs) && retryAfterMs > 0) {
+    return Math.ceil(retryAfterMs);
+  }
+
+  const retryAfterSeconds = [
+    payload?.retryAfterSeconds,
+    payload?.error?.retryAfterSeconds,
+    payload?.detail?.retryAfterSeconds,
+  ].map(Number).find((value) => Number.isFinite(value) && value > 0);
+  if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0) {
+    return Math.ceil(retryAfterSeconds * 1000);
+  }
+
+  const header = responseHeader(response, "Retry-After");
+  if (!header) return null;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return Math.ceil(seconds * 1000);
+  }
+  const retryAtMs = Date.parse(header);
+  if (Number.isFinite(retryAtMs)) {
+    return Math.max(0, Math.ceil(retryAtMs - nowMs));
+  }
+  return null;
+}
+
+function isRateLimitResponse(response, payload) {
+  if (response?.status === 429) return true;
+  const code = normalizeString(payload?.error?.code || payload?.code || payload?.detail?.code).toUpperCase();
+  return code === "RATE_LIMITED";
+}
+
 // Test-only helper. Resets both circuits in memory AND on disk so unit
 // tests that exercise hydration don't leak state across runs.
 export function __resetCircuitStateForTests(homeDir) {
@@ -1357,8 +1416,19 @@ export async function pollSessionEvents(
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
+      { readErrorBody: true },
     );
     if (!response || !response.ok) {
+      if (isRateLimitResponse(response, payload)) {
+        return {
+          ok: false,
+          reason: "rate_limited",
+          status: response?.status || 429,
+          retryAfterMs: retryAfterMsFromResponse(response, payload, normalizedNowMs),
+          events: [],
+          cursor: normalizedSince || null,
+        };
+      }
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
       return {
         ok: false,
@@ -1677,8 +1747,20 @@ export async function pollSessionEventsBefore(
       },
       normalizePositiveInteger(timeoutMs, DEFAULT_SYNC_TIMEOUT_MS),
       fetchImpl,
+      { readErrorBody: true },
     );
     if (!response || !response.ok) {
+      if (isRateLimitResponse(response, payload)) {
+        return {
+          ok: false,
+          reason: "rate_limited",
+          status: response?.status || 429,
+          retryAfterMs: retryAfterMsFromResponse(response, payload, normalizedNowMs),
+          events: [],
+          cursor: null,
+          beforeSequence: Number.isFinite(normalizedBeforeSequence) ? normalizedBeforeSequence : null,
+        };
+      }
       recordCircuitFailure(inboundCircuit, normalizedNowMs);
       return {
         ok: false,

package/src/session/transcript.js

@@ -425,6 +425,7 @@ export function computeTranscriptStats({
       usageEntries: resolvedUsageLedger.entries.length,
       duplicatesSkipped: resolvedUsageLedger.duplicatesSkipped,
       unpriced: resolvedUsageLedger.totals.unpriced,
+      estimatedEntries: resolvedUsageLedger.totals.estimatedEntries,
       priceBookVersions: resolvedUsageLedger.priceBookVersions,
     },
     sentiActions,
@@ -504,6 +505,12 @@ function rollupsByCostAndTokens(map) {
   ));
 }
 
+function estimateNote(count) {
+  const normalized = Math.max(0, Math.floor(Number(count || 0)));
+  if (normalized <= 0) return "";
+  return `${normalized.toLocaleString("en-US")} estimated`;
+}
+
 function recentUsageEntries(entries, limit = 10) {
   return entries
     .map((entry, index) => ({ entry, index }))
@@ -561,7 +568,15 @@ function appendUsageLedgerSection(lines, usageLedger) {
   );
   lines.push(`Provider cost: ${usdCell(totals.providerCostUsd)} · ${customerCostText}`);
   lines.push(`Price books: ${usageLedger.priceBookVersions.map(tableText).filter(Boolean).join(", ") || "—"}`);
-  lines.push(`Duplicates skipped: ${intCell(usageLedger.duplicatesSkipped)} · Unpriced entries: ${intCell(totals.unpriced)}`);
+  const estimateText = totals.estimatedEntries > 0
+    ? ` · Estimated entries: ${intCell(totals.estimatedEntries)}`
+    : "";
+  lines.push(
+    `Duplicates skipped: ${intCell(usageLedger.duplicatesSkipped)} · Unpriced entries: ${intCell(totals.unpriced)}${estimateText}`,
+  );
+  if (totals.estimatedEntries > 0) {
+    lines.push("_Estimated entries are output-text estimates from non-human session messages, not billing-grade provider usage._");
+  }
   lines.push("");
 
   appendUsageRollupTable(lines, {
@@ -580,8 +595,11 @@ function appendUsageLedgerSection(lines, usageLedger) {
   lines.push("| Time | Agent | Action | Model | Tokens | Provider cost | Customer cost | Idempotency key |");
   lines.push("|---|---|---|---|---:|---:|---:|---|");
   for (const entry of recentUsageEntries(usageLedger.entries)) {
+    const action = entry.estimated
+      ? `${entry.action} (${estimateNote(1)})`
+      : entry.action;
     lines.push(
-      `| ${tableText(timestampOnly(entry.timestamp)) || "—"} | ${codeCell(entry.agentId)} | ${codeCell(entry.action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(shortenIdempotencyKey(entry.idempotencyKey))} |`,
+      `| ${tableText(timestampOnly(entry.timestamp)) || "—"} | ${codeCell(entry.agentId)} | ${codeCell(action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(shortenIdempotencyKey(entry.idempotencyKey))} |`,
     );
   }
   lines.push("");
@@ -608,8 +626,10 @@ export function buildTranscriptMarkdown({
   speakerProfiles = new Map(),
   options = {},
 } = {}) {
+  const estimateMessageUsage = options.estimateMessageUsage !== false;
   const usageLedger = buildSessionUsageLedger(events, {
     sessionId: normalize(sessionMeta.sessionId),
+    includeEstimatedMessages: estimateMessageUsage,
   });
   const includeSystemEvents = options.includeSystemEvents !== false;
   const stats = computeTranscriptStats({ sessionMeta, events, speakerProfiles, usageLedger });
@@ -628,8 +648,12 @@ export function buildTranscriptMarkdown({
       stats.totals.customerCostTotalUsd == null
         ? ""
         : ` · Billable: $${stats.totals.customerCostTotalUsd.toFixed(4)}`;
+    const estimatedText =
+      stats.totals.estimatedEntries > 0
+        ? ` · Estimated entries: ${stats.totals.estimatedEntries.toLocaleString("en-US")}`
+        : "";
     lines.push(
-      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}${billableText}`,
+      `Tokens: ${stats.totals.tokenTotal.toLocaleString("en-US")} · Cost: $${stats.totals.costTotalUsd.toFixed(4)}${billableText}${estimatedText}`,
     );
   }
   lines.push("");

package/src/session/usage-report.js

@@ -116,6 +116,7 @@ function rollupToJson(rollup) {
     providerCostUsd: rollup.providerCostUsd,
     customerCostUsd: rollup.hasCustomerCost ? rollup.customerCostUsd : null,
     unpriced: rollup.unpriced,
+    estimatedEntries: rollup.estimatedEntries || 0,
   };
 }
 
@@ -133,6 +134,7 @@ function hostedRollupToJson(rollup, fallbackLabel = "") {
       ? money(bag.customerCostUsd ?? bag.customer_cost_usd ?? bag.billableCostUsd ?? bag.billable_cost_usd) ?? 0
       : null,
     unpriced: nonNegativeInt(bag.unpriced),
+    estimatedEntries: nonNegativeInt(bag.estimatedEntries ?? bag.estimated_entries),
   };
 }
 
@@ -155,6 +157,7 @@ function entryToJson(entry) {
     providerCostUsd: entry.providerCostUsd,
     customerCostUsd: entry.customerCostUsd,
     unpriced: entry.unpriced,
+    estimated: Boolean(entry.estimated),
   };
 }
 
@@ -181,6 +184,7 @@ function hostedEntryToJson(entry) {
     providerCostUsd: money(bag.providerCostUsd ?? bag.provider_cost_usd ?? bag.costUsd ?? bag.cost_usd ?? bag.cost) ?? 0,
     customerCostUsd: money(bag.customerCostUsd ?? bag.customer_cost_usd ?? bag.billableCostUsd ?? bag.billable_cost_usd),
     unpriced: Boolean(bag.unpriced),
+    estimated: Boolean(bag.estimated),
   };
 }
 
@@ -214,8 +218,12 @@ export function buildSessionUsageReport({
   sessionId = "",
   events = [],
   recentLimit = DEFAULT_RECENT_LIMIT,
+  estimateMessageUsage = true,
 } = {}) {
-  const ledger = buildSessionUsageLedger(events, { sessionId: normalize(sessionId) });
+  const ledger = buildSessionUsageLedger(events, {
+    sessionId: normalize(sessionId),
+    includeEstimatedMessages: estimateMessageUsage,
+  });
   const limit = clampRecentLimit(recentLimit);
   return {
     schema: SESSION_USAGE_REPORT_SCHEMA,
@@ -230,6 +238,7 @@ export function buildSessionUsageReport({
       providerCostUsd: ledger.totals.providerCostUsd,
       customerCostUsd: ledger.totals.hasCustomerCost ? ledger.totals.customerCostUsd : null,
       unpriced: ledger.totals.unpriced,
+      estimatedEntries: ledger.totals.estimatedEntries || 0,
       priceBookVersions: ledger.priceBookVersions,
     },
     perAgent: sortRollups(ledger.perAgent).map(rollupToJson),
@@ -281,6 +290,7 @@ export function buildSessionUsageReportFromLedgerPayload({
       providerCostUsd: totals.providerCostUsd,
       customerCostUsd: totals.customerCostUsd,
       unpriced: totals.unpriced,
+      estimatedEntries: nonNegativeInt(source.estimatedEntries ?? source.estimated_entries ?? sourceTotals.estimatedEntries ?? sourceTotals.estimated_entries),
       priceBookVersions: resolvedPriceBookVersions,
     },
     perAgent: sourceArray(
@@ -343,7 +353,12 @@ export function renderSessionUsageMarkdown(report = {}) {
     `Provider cost: ${usdCell(totals.providerCostUsd)} - Customer cost: ${optionalUsdCell(totals.customerCostUsd, totals.customerCostUsd != null)}`,
   );
   lines.push(`Price books: ${(totals.priceBookVersions || []).map(tableText).filter(Boolean).join(", ") || "-"}`);
-  lines.push(`Duplicates skipped: ${intCell(totals.duplicatesSkipped)} - Unpriced entries: ${intCell(totals.unpriced)}`);
+  lines.push(
+    `Duplicates skipped: ${intCell(totals.duplicatesSkipped)} - Unpriced entries: ${intCell(totals.unpriced)} - Estimated entries: ${intCell(totals.estimatedEntries)}`,
+  );
+  if (totals.estimatedEntries > 0) {
+    lines.push("_Estimated entries are output-text estimates from non-human session messages, not billing-grade provider usage._");
+  }
   lines.push("");
 
   appendRollupTable(lines, {
@@ -366,8 +381,9 @@ export function renderSessionUsageMarkdown(report = {}) {
     lines.push(`| - | - | - | - | 0 | ${usdCell(0)} | - | - | - |`);
   } else {
     for (const entry of entries) {
+      const action = entry.estimated ? `${entry.action} (estimated)` : entry.action;
       lines.push(
-        `| ${tableText(timestampOnly(entry.timestamp)) || "-"} | ${codeCell(entry.agentId)} | ${codeCell(entry.action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(entry.ledgerEntryId)} | ${codeCell(entry.idempotencyKeyHash)} |`,
+        `| ${tableText(timestampOnly(entry.timestamp)) || "-"} | ${codeCell(entry.agentId)} | ${codeCell(action)} | ${codeCell(entry.model)} | ${intCell(entry.totalTokens)} | ${usdCell(entry.providerCostUsd)} | ${optionalUsdCell(entry.customerCostUsd, entry.customerCostUsd != null)} | ${codeCell(entry.ledgerEntryId)} | ${codeCell(entry.idempotencyKeyHash)} |`,
       );
     }
   }
@@ -387,6 +403,9 @@ export function renderSessionUsageSummary(report = {}) {
   lines.push(
     `priceBooks=${(totals.priceBookVersions || []).map(tableText).filter(Boolean).join(",") || "-"} duplicatesSkipped=${intCell(totals.duplicatesSkipped)} unpriced=${intCell(totals.unpriced)}`,
   );
+  if (totals.estimatedEntries > 0) {
+    lines.push(`estimatedEntries=${intCell(totals.estimatedEntries)} (output-text estimates; not billing-grade)`);
+  }
   const agents = Array.isArray(report.perAgent) ? report.perAgent.slice(0, 8) : [];
   if (agents.length) {
     lines.push("");
@@ -403,7 +422,7 @@ export function renderSessionUsageSummary(report = {}) {
     lines.push("Recent:");
     for (const entry of entries) {
       lines.push(
-        `- ${timestampOnly(entry.timestamp) || "-"} ${entry.agentId} ${entry.action} ${intCell(entry.totalTokens)} tokens ${usdCell(entry.providerCostUsd)} ledger=${entry.ledgerEntryId}`,
+        `- ${timestampOnly(entry.timestamp) || "-"} ${entry.agentId} ${entry.action}${entry.estimated ? " (estimated)" : ""} ${intCell(entry.totalTokens)} tokens ${usdCell(entry.providerCostUsd)} ledger=${entry.ledgerEntryId}`,
       );
     }
   }

package/src/session/usage.js

@@ -241,8 +241,8 @@ export async function emitLLMInteraction(
  *   totals: { totalTokens, inputTokens, outputTokens, costUsd, interactions },
  * }}
  */
-export function aggregateSessionUsage(events = []) {
-  const ledger = buildSessionUsageLedger(events);
+export function aggregateSessionUsage(events = [], options = {}) {
+  const ledger = buildSessionUsageLedger(events, options);
   const perAgent = new Map();
   const totals = {
     totalTokens: 0,