sentinelayer-cli 0.16.0 → 0.17.1

package/README.md

@@ -111,6 +111,9 @@ Sentinelayer includes a deterministic session coordination surface for multi-age
 
 Read the full guide: [docs/sessions.md](docs/sessions.md)
 
+For new engineers or agents joining an active SentinelLayer loop, start with
+[docs/ENGINEERING_ONBOARDING.md](docs/ENGINEERING_ONBOARDING.md).
+
 For strategy context, see the long-form blog draft: [docs/blog/slack-for-ai-coding-agents.md](docs/blog/slack-for-ai-coding-agents.md)
 
 ## Advanced options
@@ -914,13 +917,20 @@ Prerequisites:
   - repository secret `NPM_TOKEN` with publish access, or
   - npm trusted publishing for this repository/tag workflow
 
-Release options:
+Release flow:
+
+1. Merge to `main` and let `Release Please` open/update the release PR.
+2. Merge the release PR after Omar, Quality Gates, and Attestation are green.
+3. From a clean checkout of the release commit, run the guarded release command:
+   ```bash
+   git fetch origin main --tags
+   git checkout main && git pull --ff-only
+   npm run release:publish -- --tag v0.1.1 --notes-file release-notes.md
+   ```
+4. The guarded command creates the tag with `git tag -s`, verifies it with `git tag -v`, pushes it, confirms the remote GitHub tag object is annotated and cryptographically verified by an allowlisted signer, then creates the GitHub release with `gh release create --verify-tag`.
+5. The tag push triggers `Release`, which re-verifies upstream checks, release artifact attestations, rollback readiness, protected `package-release` approval, and npm trusted publishing OIDC before publishing.
 
-1. Merge to `main` and let `Release Please` open/update the release PR and tag.
-2. Push a tag like `v0.1.1` to publish automatically (or via release-please tag creation).
-3. Run `Release` manually (`workflow_dispatch`) to validate gates and rollback readiness without publishing.
-4. Tag-triggered publish resolves auth mode at runtime (`NPM_TOKEN` first, otherwise trusted publishing OIDC).
-5. If neither auth mode is available, publish fails closed with an explicit workflow error.
+Do not run `gh release create v0.1.1` before pushing the signed tag. GitHub release creation creates a lightweight tag when the tag does not already exist, and the Release workflow intentionally fails closed for lightweight tags. If a remote tag already exists as a lightweight tag, `npm run release:publish` refuses to create the GitHub release.
 
 Release publish now enforces tarball checksum-manifest validation and attestation verification bound to `.github/workflows/release.yml` before `npm publish`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {
@@ -11,7 +11,8 @@
     "test:unit": "node --import ./tests/setup-env.mjs --test tests/unit*.test.mjs",
     "test:e2e": "node --import ./tests/setup-env.mjs --test tests/e2e.test.mjs",
     "test:coverage": "c8 node --import ./tests/setup-env.mjs --test tests/unit*.test.mjs",
-    "verify": "npm run check && npm run docs:build && npm run test:e2e && npm run test:coverage && npm pack --dry-run"
+    "verify": "npm run check && npm run docs:build && npm run test:e2e && npm run test:coverage && npm pack --dry-run",
+    "release:publish": "node scripts/release-publish.mjs"
   },
   "bin": {
     "sentinelayer-cli": "bin/sentinelayer-cli.js",

package/src/commands/legacy-args.js

@@ -61,6 +61,7 @@ export function buildLegacyArgs(baseArgs, { commandOptions = {}, command } = {})
   appendPassthroughFlag(args, "--notify-email", commandOptions.notifyEmail);
   appendPassthroughFlag(args, "--email-on-complete", commandOptions.emailOnComplete);
   appendPassthroughFlag(args, "--notify-session", commandOptions.notifySession);
+  appendBooleanFlag(args, "--require-usage-ledger", commandOptions.requireUsageLedger);
   appendPassthroughFlag(args, "--devtestbot-base-url", commandOptions.devtestbotBaseUrl);
   appendPassthroughFlag(args, "--devtestbot-scope", commandOptions.devtestbotScope);
   appendNegatedBooleanFlag(args, "--no-devtestbot", commandOptions.devtestbot);

package/src/commands/omargate.js

@@ -50,6 +50,7 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--notify-email <addr>", "Send final report to this email (default: account email)")
     .option("--email-on-complete <addr>", "Trigger the API-side DD report email after the run completes")
     .option("--notify-session <session-id>", "Stream progress into this Senti session (default: auto-start)")
+    .option("--require-usage-ledger", "Fail if Investor-DD LLM planner calls cannot write session_usage")
     .option("--no-email", "Skip email dispatch")
     .option("--no-dashboard", "Skip dashboard card persistence")
     .option("--devtestbot-base-url <url>", "Approved absolute URL for devTestBot browser lanes")

package/src/commands/session.js

@@ -43,6 +43,7 @@ import { listSessionTasks } from "../session/tasks.js";
 import {
   createSession,
   DEFAULT_TTL_SECONDS,
+  expireSession,
   getSession,
   isSessionCacheExpired,
   listActiveSessions,
@@ -86,7 +87,7 @@ import {
   generateSessionCheckpoint,
   listSessionCheckpoints,
 } from "../session/checkpoints.js";
-import { authLoginHint } from "../ui/command-hints.js";
+import { authLoginHint, preferredCliCommand } from "../ui/command-hints.js";
 import { parseCsvTokens } from "./ai/shared.js";
 
 function shouldEmitJson(options, command) {
@@ -425,6 +426,63 @@ function sentiAutostartDisabled() {
   return String(process.env.SENTINELAYER_SKIP_SENTI_AUTOSTART || "").trim() === "1";
 }
 
+function buildResumeContext(candidate, { reuseWindowSeconds = 3600 } = {}) {
+  if (!candidate) return null;
+  const source = normalizeString(candidate._source) || "unknown";
+  const lastActivityAt =
+    normalizeString(candidate.lastInteractionAt) ||
+    normalizeString(candidate.lastActivityAt) ||
+    normalizeString(candidate.updatedAt) ||
+    normalizeString(candidate.createdAt) ||
+    null;
+  return {
+    source,
+    reuseWindowSeconds,
+    lastActivityAt,
+    reason: `recent_${source}_session`,
+  };
+}
+
+async function resolveSessionRemoteSyncState({ dashboardUrl } = {}) {
+  if (remoteSessionLookupDisabled()) {
+    return {
+      status: "disabled",
+      attempted: false,
+      reason: "remote_sync_disabled",
+      dashboardUrl,
+    };
+  }
+
+  let storedSession = null;
+  try {
+    storedSession = await readStoredSession();
+  } catch {
+    storedSession = null;
+  }
+  const apiUrl =
+    normalizeString(storedSession?.apiUrl) ||
+    normalizeString(process.env.SENTINELAYER_API_URL) ||
+    "https://api.sentinelayer.com";
+  const hasToken = Boolean(
+    normalizeString(storedSession?.token) || normalizeString(process.env.SENTINELAYER_TOKEN),
+  );
+  if (!hasToken) {
+    return {
+      status: "auth_required",
+      attempted: false,
+      reason: "not_authenticated",
+      apiUrl,
+      dashboardUrl,
+    };
+  }
+  return {
+    status: "background_sync_queued",
+    attempted: true,
+    apiUrl,
+    dashboardUrl,
+  };
+}
+
 function mergeResumeCandidate(existing, incoming) {
   if (!existing) return incoming;
   const existingActivity = Number(existing._activityMs || 0);
@@ -614,6 +672,69 @@ async function verifyRemoteSession(sessionId, { targetPath } = {}) {
   return { ok: false, reason: lastReason };
 }
 
+function normalizeRemoteResumeStatus(session = {}) {
+  return normalizeString(session?.archiveStatus || session?.status).toLowerCase();
+}
+
+function remoteStatusAllowsResume(status) {
+  if (!status) return true;
+  return status === "active" || status === "pending";
+}
+
+async function reconcileLocalResumeCandidate(candidate, { targetPath } = {}) {
+  if (!candidate || candidate._source !== "local" || remoteSessionLookupDisabled()) {
+    return { candidate, staleResume: null };
+  }
+  const verification = await verifyRemoteSession(candidate.sessionId, { targetPath }).catch((error) => ({
+    ok: false,
+    reason: normalizeString(error?.message) || "probe_failed",
+  }));
+
+  if (verification.ok) {
+    const remoteStatus = normalizeRemoteResumeStatus(verification.session);
+    if (remoteStatusAllowsResume(remoteStatus)) {
+      return { candidate, staleResume: null };
+    }
+    await expireSession(candidate.sessionId, { targetPath }).catch(() => null);
+    return {
+      candidate: null,
+      staleResume: {
+        sessionId: candidate.sessionId,
+        source: "remote",
+        reason: "remote_not_active",
+        remoteStatus,
+        action: "expired_local_and_created_new",
+      },
+    };
+  }
+
+  if (verification.reason === "not_found" || verification.reason === "forbidden") {
+    await expireSession(candidate.sessionId, { targetPath }).catch(() => null);
+    return {
+      candidate: null,
+      staleResume: {
+        sessionId: candidate.sessionId,
+        source: "remote",
+        reason: verification.reason,
+        remoteStatus: verification.reason,
+        status: verification.status || null,
+        action: "expired_local_and_created_new",
+      },
+    };
+  }
+
+  return {
+    candidate,
+    staleResume: {
+      sessionId: candidate.sessionId,
+      source: "remote",
+      reason: verification.reason || "probe_failed",
+      status: verification.status || null,
+      action: "kept_local_resume",
+    },
+  };
+}
+
 // Render an absolute ISO timestamp as a coarse "Nm ago" / "Nh ago" / "Nd ago"
 // label for human-readable join output. Returns `"never"` for missing input
 // and `"just now"` for sub-minute deltas.
@@ -737,12 +858,15 @@ async function ensureWorkspaceSession({
   const titleArg = normalizeString(title);
   const fallbackTitle = deriveSessionTitle(targetPath);
   const startedAt = Date.now();
-  const resumedCandidate = await findReusableSessionCandidate({
+  let resumedCandidate = await findReusableSessionCandidate({
     targetPath,
     reuseWindowSeconds,
     resume,
     forceNew,
   });
+  const reconciliation = await reconcileLocalResumeCandidate(resumedCandidate, { targetPath });
+  resumedCandidate = reconciliation.candidate;
+  const staleResume = reconciliation.staleResume;
   let created;
   const resumeTitle =
     titleArg || normalizeString(resumedCandidate?.title) || fallbackTitle;
@@ -825,6 +949,7 @@ async function ensureWorkspaceSession({
     title: effectiveTitle || null,
     titleAuto,
     titleSync,
+    staleResume,
   };
 }
 
@@ -848,6 +973,42 @@ async function defaultAgentId(value, _targetPath) {
   return resolveSessionSayAgentId(value);
 }
 
+async function resolveSessionAgentEnvelope(
+  sessionId,
+  agentId,
+  {
+    targetPath = process.cwd(),
+    model = "",
+    role = "",
+    displayName = "",
+    clientKind = "cli",
+  } = {}
+) {
+  const normalizedAgentId = normalizeAgentId(agentId, "cli-user");
+  let registeredAgent = null;
+  try {
+    const agents = await listAgents(sessionId, { targetPath, includeInactive: true });
+    registeredAgent = agents.find(
+      (agent) => normalizeString(agent.agentId).toLowerCase() === normalizedAgentId.toLowerCase(),
+    );
+  } catch {
+    registeredAgent = null;
+  }
+
+  const resolvedModel = normalizeString(model) || normalizeString(registeredAgent?.model);
+  const resolvedRole = normalizeString(role) || normalizeString(registeredAgent?.role);
+  const resolvedDisplayName =
+    normalizeString(displayName) || normalizeString(registeredAgent?.displayName);
+  const envelope = {
+    id: normalizedAgentId,
+    model: resolvedModel || undefined,
+    role: resolvedRole || undefined,
+    displayName: resolvedDisplayName || undefined,
+    clientKind: normalizeString(clientKind) || undefined,
+  };
+  return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
+}
+
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
   const normalizedItems = Array.isArray(items) ? items : [];
   const normalizedConcurrency = Math.max(
@@ -913,13 +1074,93 @@ function checkpointSequenceRange(checkpoint = {}) {
   return "anchor pending";
 }
 
-function formatCheckpointLine(checkpoint = {}) {
+function checkpointGradeLabel(checkpoint = {}) {
+  const grade = normalizeString(checkpoint.grade || checkpoint.gradeLetter || checkpoint.grade_letter).toUpperCase();
+  if (!["A", "B", "C", "D", "F"].includes(grade)) {
+    return "";
+  }
+  const score = Number(checkpoint.gradeScore ?? checkpoint.grade_score);
+  const scoreLabel = Number.isFinite(score) ? ` ${Math.max(0, Math.min(100, Math.floor(score)))}/100` : "";
+  const rawReasons = Array.isArray(checkpoint.gradeReasons)
+    ? checkpoint.gradeReasons
+    : Array.isArray(checkpoint.grade_reasons)
+      ? checkpoint.grade_reasons
+      : [];
+  const reasons = rawReasons
+    .map((reason) => normalizeString(reason?.message || reason?.code || reason))
+    .filter(Boolean)
+    .slice(0, 2);
+  const reasonLabel = reasons.length ? `: ${reasons.join("; ")}` : "";
+  return ` completeness ${grade}${scoreLabel}${reasonLabel}`;
+}
+
+function checkpointSummarySections(checkpoint = {}) {
+  const sections = checkpoint.summarySections || checkpoint.summary_sections;
+  return sections && typeof sections === "object" && !Array.isArray(sections) ? sections : null;
+}
+
+function normalizeCheckpointTextItems(value, limit = 3) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((item) => normalizeString(item))
+    .filter(Boolean)
+    .slice(0, limit);
+}
+
+function formatCheckpointSectionPreview(checkpoint = {}) {
+  const sections = checkpointSummarySections(checkpoint);
+  if (!sections) {
+    return "";
+  }
+  const parts = [];
+  const work = normalizeCheckpointTextItems(sections.workCompleted || sections.work_completed, 1)[0];
+  if (work) {
+    parts.push(`work: ${work}`);
+  }
+  const agents = Array.isArray(sections.agentContributions)
+    ? sections.agentContributions
+    : Array.isArray(sections.agent_contributions)
+      ? sections.agent_contributions
+      : [];
+  const agentLabels = agents
+    .map((item) => {
+      const agentId = normalizeString(item?.agentId || item?.agent_id);
+      const summary = normalizeString(item?.summary);
+      return agentId && summary ? `${agentId}: ${summary}` : "";
+    })
+    .filter(Boolean)
+    .slice(0, 2);
+  if (agentLabels.length) {
+    parts.push(`agents: ${agentLabels.join("; ")}`);
+  }
+  const evidence = Array.isArray(sections.evidence) ? sections.evidence : [];
+  const evidenceLabels = evidence
+    .map((item) => normalizeString(item?.label || item?.value))
+    .filter(Boolean)
+    .slice(0, 3);
+  if (evidenceLabels.length) {
+    parts.push(`evidence: ${evidenceLabels.join(", ")}`);
+  }
+  const risks = normalizeCheckpointTextItems(sections.risks, 1);
+  if (risks.length) {
+    parts.push(`risks: ${risks.join("; ")}`);
+  }
+  const nextSteps = normalizeCheckpointTextItems(sections.nextSteps || sections.next_steps, 1);
+  if (nextSteps.length) {
+    parts.push(`next: ${nextSteps.join("; ")}`);
+  }
+  return parts.length ? ` | ${parts.join(" | ")}` : "";
+}
+
+export function formatCheckpointLine(checkpoint = {}) {
   const id = normalizeString(checkpoint.checkpointId) || "checkpoint";
   const kind = normalizeString(checkpoint.kind) || "summary";
   const title = normalizeString(checkpoint.title) || "Untitled checkpoint";
   const byline = normalizeString(checkpoint.createdByAgentId || checkpoint.createdBy);
   const by = byline ? ` by ${byline}` : "";
-  return `${checkpointSequenceRange(checkpoint)} ${id} [${kind}] ${title}${by}`;
+  return `${checkpointSequenceRange(checkpoint)} ${id} [${kind}] ${title}${by}${checkpointGradeLabel(checkpoint)}${formatCheckpointSectionPreview(checkpoint)}`;
 }
 
 async function readCheckpointSummaryOption(options = {}, { targetPath } = {}) {
@@ -1224,6 +1465,9 @@ export function registerSessionCommand(program) {
       const launchPlan = template ? buildTemplateLaunchPlan(created.sessionId, template) : [];
       const dashboardUrl = buildDashboardUrl(created.sessionId);
       const effectiveTitle = ensured.title;
+      const cliCommand = preferredCliCommand();
+      const resumeContext = buildResumeContext(ensured.resumedCandidate, { reuseWindowSeconds });
+      const remoteSync = await resolveSessionRemoteSyncState({ dashboardUrl });
 
       const payload = {
         command: "session start",
@@ -1245,23 +1489,29 @@ export function registerSessionCommand(program) {
         launchPlan,
         dashboardUrl,
         resumed,
+        resumeSource: resumeContext?.source || null,
+        resumeContext: resumeContext || undefined,
+        staleResume: ensured.staleResume || undefined,
+        remoteSync,
         title: effectiveTitle || null,
         titleAuto: Boolean(ensured.titleAuto),
         titleSync: ensured.titleSync || undefined,
       };
 
       // Best-effort admin visibility sync. Session creation remains local-first.
-      void syncSessionMetadataToApi(created.sessionId, {
-        targetPath,
-        sessionId: created.sessionId,
-        status: created.status,
-        createdAt: created.createdAt,
-        expiresAt: created.expiresAt,
-        title: effectiveTitle || null,
-        ttlSeconds,
-        template: created.template,
-        codebaseContext: created.codebaseContext,
-      }).catch(() => {});
+      if (remoteSync.attempted) {
+        void syncSessionMetadataToApi(created.sessionId, {
+          targetPath,
+          sessionId: created.sessionId,
+          status: created.status,
+          createdAt: created.createdAt,
+          expiresAt: created.expiresAt,
+          title: effectiveTitle || null,
+          ttlSeconds,
+          template: created.template,
+          codebaseContext: created.codebaseContext,
+        }).catch(() => {});
+      }
 
       // Auto-start the Senti orchestrator daemon. Without this, every
       // session ran with `Senti actions: 1` (just the welcome alert)
@@ -1303,15 +1553,38 @@ export function registerSessionCommand(program) {
       console.log(pc.bold(resumed ? "Session resumed" : "Session created"));
       console.log(pc.gray(`Session: ${created.sessionId}`));
       if (titleArg) console.log(pc.gray(`Title: ${titleArg}`));
+      if (resumeContext) {
+        console.log(
+          pc.gray(
+            `Resume source: ${resumeContext.source} (last activity ${resumeContext.lastActivityAt || "unknown"}; window ${reuseWindowSeconds}s)`,
+          ),
+        );
+      }
+      if (ensured.staleResume?.action === "expired_local_and_created_new") {
+        console.log(
+          pc.yellow(
+            `Skipped stale local session ${ensured.staleResume.sessionId}: remote status is ${ensured.staleResume.remoteStatus || ensured.staleResume.reason}.`,
+          ),
+        );
+      }
       if (created.streamPath) console.log(pc.gray(`Stream: ${created.streamPath}`));
       console.log(pc.gray(`${resumed ? "Resumed" : "Created"} in ${durationMs}ms`));
       console.log(
         `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`,
       );
+      if (remoteSync.status === "auth_required") {
+        console.log(
+          pc.yellow(
+            `Dashboard sync pending: run \`${authLoginHint()}\`, then rerun \`${cliCommand} session start\` in this workspace to publish local metadata.`,
+          ),
+        );
+      } else if (remoteSync.status === "disabled") {
+        console.log(pc.gray("Dashboard sync disabled by SENTINELAYER_SKIP_REMOTE_SYNC=1."));
+      }
       if (!resumed) {
         console.log(
           pc.gray(
-            "Tip: subsequent `slc session start` in this workspace within an hour will resume this session. Pass --force-new to override.",
+            `Tip: subsequent \`${cliCommand} session start\` in this workspace within an hour will resume this session. Pass --force-new to override.`,
           ),
         );
       }
@@ -1431,13 +1704,20 @@ export function registerSessionCommand(program) {
         forceNew: Boolean(options.forceNew),
         reuseWindowSeconds,
       });
+      const dashboardUrl = buildDashboardUrl(ensured.created.sessionId);
+      const resumeContext = buildResumeContext(ensured.resumedCandidate, { reuseWindowSeconds });
+      const remoteSync = await resolveSessionRemoteSyncState({ dashboardUrl });
       const payload = {
         command: "session ensure",
         targetPath,
         sessionId: ensured.created.sessionId,
         title: ensured.title || null,
         resumed: Boolean(ensured.resumedCandidate),
-        dashboardUrl: buildDashboardUrl(ensured.created.sessionId),
+        resumeSource: resumeContext?.source || null,
+        resumeContext: resumeContext || undefined,
+        staleResume: ensured.staleResume || undefined,
+        dashboardUrl,
+        remoteSync,
         titleSync: ensured.titleSync || undefined,
       };
       console.log(JSON.stringify(payload, null, 2));
@@ -1701,6 +1981,21 @@ export function registerSessionCommand(program) {
     .command("say <sessionId> <message>")
     .description("Send a message to the session")
     .option("--agent <id>", "Agent id to emit from", "cli-user")
+    .option(
+      "--model <model>",
+      "Agent model/provider hint; defaults to local joined agent metadata or SENTINELAYER_AGENT_MODEL",
+      process.env.SENTINELAYER_AGENT_MODEL || "",
+    )
+    .option(
+      "--display-name <name>",
+      "Human-readable agent display name",
+      process.env.SENTINELAYER_AGENT_DISPLAY_NAME || process.env.SENTINELAYER_AGENT_NAME || "",
+    )
+    .option(
+      "--role <role>",
+      "Agent role metadata; defaults to local joined agent metadata or SENTINELAYER_AGENT_ROLE",
+      process.env.SENTINELAYER_AGENT_ROLE || "",
+    )
     .option("--to <agent>", "Direct the message to a specific agent id")
     .option("--reply-to <sequence>", "Mark this message as a reply to a target sequence id")
     .option("--reply-cursor <cursor>", "Mark this message as a reply to a target event cursor")
@@ -1737,9 +2032,15 @@ export function registerSessionCommand(program) {
         eventPayload.replyToCursor = replyToCursor;
       }
       const clientMessageId = `cli-${randomUUID()}`;
+      const agent = await resolveSessionAgentEnvelope(normalizedSessionId, agentId, {
+        targetPath,
+        model: options.model,
+        role: options.role,
+        displayName: options.displayName,
+      });
       const event = createAgentEvent({
         event: "session_message",
-        agentId,
+        agent,
         sessionId: normalizedSessionId,
         payload: eventPayload,
       });
@@ -1834,13 +2135,9 @@ export function registerSessionCommand(program) {
       event.eventId = clientMessageId;
       event.idempotencyToken = clientMessageId;
 
-      let remoteSync = null;
-      for (let attempt = 0; attempt < 2; attempt += 1) {
-        remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
-          targetPath,
-        });
-        if (remoteSync?.synced) break;
-      }
+      const remoteSync = await syncSessionEventToApi(normalizedSessionId, event, {
+        targetPath,
+      });
       if (!remoteSync?.synced) {
         throw new Error(
           `Agent post failed (${remoteSync?.reason || "unknown"}). Ensure this user has an active grant for '${agentId}'.`,

package/src/events/schema.js

@@ -54,6 +54,14 @@ function normalizeTimestamp(value, fallbackTimestamp) {
   return new Date(epoch).toISOString();
 }
 
+function normalizePositiveInteger(value) {
+  const normalized = Number(value);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    return undefined;
+  }
+  return Math.floor(normalized);
+}
+
 function stripUndefinedEntries(record) {
   const cleaned = {};
   for (const [key, value] of Object.entries(record || {})) {
@@ -112,6 +120,11 @@ export function createAgentEvent({
   agent,
   ts,
   timestamp,
+  eventId,
+  idempotencyToken,
+  cursor,
+  sequenceId,
+  sequence_id,
 } = {}) {
   const normalizedEvent = normalizeNonEmptyString(event);
   const normalizedAgent = normalizeAgentShape({
@@ -135,6 +148,10 @@ export function createAgentEvent({
     runId: normalizeOptionalString(runId),
     workItemId: normalizeOptionalString(workItemId),
     requestId: normalizeOptionalString(requestId),
+    eventId: normalizeOptionalString(eventId),
+    idempotencyToken: normalizeOptionalString(idempotencyToken),
+    cursor: normalizeOptionalString(cursor),
+    sequenceId: normalizePositiveInteger(sequenceId ?? sequence_id),
     ts: canonicalTs,
     // Keep legacy timestamp key for existing consumers while PR0 migrates envelope usage.
     timestamp: canonicalTs,
@@ -202,6 +219,10 @@ export function normalizeAgentEvent(evt, { allowLegacy = true } = {}) {
       runId: evt.runId,
       workItemId: evt.workItemId,
       requestId: evt.requestId,
+      eventId: evt.eventId,
+      idempotencyToken: evt.idempotencyToken,
+      cursor: evt.cursor,
+      sequenceId: evt.sequenceId ?? evt.sequence_id,
       ts: normalizedTs,
     });
   } catch {

package/src/legacy-cli.js

@@ -1135,6 +1135,10 @@ async function runLocalOmarGateCommand(args) {
     const devTestBotBaseUrl = getCommandOptionValue(args, "--devtestbot-base-url") || "";
     const devTestBotScope = getCommandOptionValue(args, "--devtestbot-scope") || "";
     const emailOnComplete = getCommandOptionValue(args, "--email-on-complete") || "";
+    const notifySession = getCommandOptionValue(args, "--notify-session") || "";
+    const requireUsageLedger = hasCommandOption(args, "--require-usage-ledger");
+    const model = getCommandOptionValue(args, "--model") || "gpt-5.3-codex";
+    const provider = getCommandOptionValue(args, "--provider") || "sentinelayer";
 
     const targetPath = path.resolve(process.cwd(), pathArg);
     if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
@@ -1163,6 +1167,18 @@ async function runLocalOmarGateCommand(args) {
         baseUrl: devTestBotBaseUrl,
         scope: devTestBotScope,
       },
+      sessionUsage: notifySession || requireUsageLedger
+        ? {
+            sessionId: notifySession,
+            agentId: "investor-dd",
+            model,
+            provider,
+            targetPath,
+            billingTier: "internal",
+            sourceCommand: "omargate investor-dd",
+            required: requireUsageLedger,
+          }
+        : null,
       reportEmail: emailOnComplete
         ? {
             to: emailOnComplete,