sentinelayer-cli 0.32.1 → 0.32.3

package/README.md

@@ -929,6 +929,18 @@ Ledger contract:
 - network access to Sentinelayer API/web
 - optional: GitHub CLI (`gh`) authenticated for secret injection
 
+## Operator and architecture references
+
+- First-run engineering onboarding: `docs/ENGINEERING_ONBOARDING.md`
+- Senti session operations, coordination, kill, and rollback conventions: `docs/sessions.md`
+- Release workflow map and rollback drill ownership: `docs/workflow-matrix.md`
+- Release rollback execution: `.github/workflows/rollback.yml` and `.github/scripts/release-rollback-readiness.sh`
+- Architecture and decision records for major surfaces:
+  - Hosted MCP connector boundary: `docs/mcp-hosted-connector.md`
+  - MCP local/runtime entry points: `docs/mcp.md`
+  - Investor-DD architecture: `docs/INVESTOR_DD_ARCHITECTURE.md`
+  - CI/CD acknowledged release risks: `.github/policies/cicd-acknowledged-risks.md`
+
 ## Release to npm
 
 This repo includes `.github/workflows/release.yml`.
@@ -949,14 +961,15 @@ 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:
+3. Wait for the main-branch `Release Please` workflow run on that merge commit to complete successfully.
+4. 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.
+5. The guarded command confirms the exact release commit has one successful main `Release Please` run, 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`.
+6. 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.
 
 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.
 
@@ -964,6 +977,7 @@ Release publish now enforces tarball checksum-manifest validation and attestatio
 
 Release guardrails now require successful upstream checks on the target commit:
 
+- `Release Please`
 - `Quality Summary`
 - `Omar Gate`
 - `Attestation Summary`

package/package.json

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

package/src/commands/omargate.js

@@ -20,7 +20,7 @@ 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("--notify-session <session-id>", "Write Omar Deep billing-grade usage entries into this Senti session (default: auto-detect active 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)")
@@ -54,7 +54,7 @@ export function registerOmarGateCommand(program, invokeLegacy) {
     .option("--stream", "Emit NDJSON events to stdout as personas work file-by-file")
     .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("--notify-session <session-id>", "Stream progress + billing-grade usage into this Senti session (default: auto-detect active Senti session)")
     .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")

package/src/legacy-cli.js

@@ -29,6 +29,7 @@ import {
   getCoordinationEtiquetteItems,
   renderCoordinationNumberedList,
 } from "./session/coordination-guidance.js";
+import { resolveUsageSessionId } from "./session/usage-session-resolver.js";
 
 let DEFAULT_API_URL = process.env.SENTINELAYER_API_URL || "https://api.sentinelayer.com";
 let DEFAULT_WEB_URL = process.env.SENTINELAYER_WEB_URL || "https://sentinelayer.com";
@@ -1200,7 +1201,7 @@ 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 notifySessionFlag = 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";
@@ -1211,6 +1212,12 @@ async function runLocalOmarGateCommand(args) {
     if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
       throw new Error(`Invalid --path target: ${targetPath}`);
     }
+    const usageSession = await resolveUsageSessionId({
+      explicitSessionId: notifySessionFlag,
+      targetPath,
+      env: process.env,
+    });
+    const notifySession = usageSession.sessionId || "";
 
     const { runInvestorDd } = await import("./review/investor-dd-orchestrator.js");
     const { parsePersonaCsv, resolveFilteredPersonas } = await import("./review/scan-modes.js");
@@ -1235,6 +1242,15 @@ async function runLocalOmarGateCommand(args) {
         printInfo(`Skipped personas: ${personaFilter.dropped.join(", ")}`);
       }
       if (dryRun) printInfo("Mode: dry-run (plan + stub report only)");
+      if (notifySession) {
+        printInfo(
+          `Usage ledger: ${usageSession.source === "explicit" ? "using" : "auto-detected"} Senti session ${notifySession}`,
+        );
+      } else if (requireUsageLedger) {
+        printInfo(
+          `Usage ledger: required but no active Senti session was auto-detected (${usageSession.reason || "missing_session"}).`,
+        );
+      }
     }
     const result = await runInvestorDd({
       rootPath: targetPath,
@@ -1298,7 +1314,7 @@ 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 notifySessionFlag = 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;
@@ -1315,6 +1331,12 @@ async function runLocalOmarGateCommand(args) {
   if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
     throw new Error(`Invalid --path target: ${targetPath}`);
   }
+  const usageSession = await resolveUsageSessionId({
+    explicitSessionId: notifySessionFlag,
+    targetPath,
+    env: process.env,
+  });
+  const notifySession = usageSession.sessionId || "";
   // Default scope to changed-files when the target has a git delta (uncommitted
   // or staged), matching gh's PR-scoped Omar; fall back to full repo otherwise.
   // Explicit --scope-mode/--diff/--staged always override (see resolveScopeModeFromOptions).
@@ -1327,6 +1349,15 @@ async function runLocalOmarGateCommand(args) {
     printInfo(`Target: ${targetPath}`);
     printInfo(`Scope mode: ${scopeMode}`);
     printInfo(`Scan mode: ${scanMode} | AI: ${aiEnabled ? "enabled" : "disabled"}`);
+    if (notifySession) {
+      printInfo(
+        `Usage ledger: ${usageSession.source === "explicit" ? "using" : "auto-detected"} Senti session ${notifySession}`,
+      );
+    } else if (requireUsageLedger) {
+      printInfo(
+        `Usage ledger: required but no active Senti session was auto-detected (${usageSession.reason || "missing_session"}).`,
+      );
+    }
     console.error("");
     console.error(pc.gray(`  [${formatElapsed(Date.now() - commandStartedAt)}] Phase 1: Deterministic analysis (22 rules)...`));
   }

package/src/session/usage-session-resolver.js

@@ -0,0 +1,132 @@
+import process from "node:process";
+
+import { listActiveSessions } from "./store.js";
+
+const USAGE_SESSION_ENV_KEYS = [
+  "SENTINELAYER_NOTIFY_SESSION",
+  "SENTINELAYER_SESSION_ID",
+  "SL_SESSION_ID",
+];
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function isSafeUsageSessionId(value) {
+  const normalized = normalizeString(value);
+  if (!/^[A-Za-z0-9._-]{1,200}$/.test(normalized)) return false;
+  if (normalized === "." || normalized === "..") return false;
+  if (normalized.includes("..")) return false;
+  return true;
+}
+
+function normalizeTrustedUsageSessionId(value, source) {
+  const normalized = normalizeString(value);
+  if (!normalized) return "";
+  if (!isSafeUsageSessionId(normalized)) {
+    throw new Error(
+      `Invalid ${source} usage session id: must be a single session identifier without path traversal, separators, or control characters.`,
+    );
+  }
+  return normalized;
+}
+
+function parseEpoch(value) {
+  const epoch = Date.parse(normalizeString(value));
+  return Number.isFinite(epoch) ? epoch : 0;
+}
+
+function sessionRecencyEpoch(session = {}) {
+  return Math.max(
+    parseEpoch(session.lastInteractionAt),
+    parseEpoch(session.updatedAt),
+    parseEpoch(session.createdAt),
+  );
+}
+
+function resolveEnvUsageSession(env = process.env) {
+  for (const key of USAGE_SESSION_ENV_KEYS) {
+    const sessionId = normalizeTrustedUsageSessionId(env?.[key], key);
+    if (sessionId) {
+      return { sessionId, source: "env", envKey: key };
+    }
+  }
+  return null;
+}
+
+export function selectMostRecentUsageSession(sessions = []) {
+  const candidatesBySessionId = new Map();
+  for (const session of Array.isArray(sessions) ? sessions : []) {
+    const sessionId = normalizeString(session?.sessionId);
+    if (!isSafeUsageSessionId(sessionId)) continue;
+
+    const candidate = {
+      sessionId,
+      title: normalizeString(session?.title),
+      recencyEpoch: sessionRecencyEpoch(session),
+    };
+    const existing = candidatesBySessionId.get(sessionId);
+    if (!existing || candidate.recencyEpoch > existing.recencyEpoch) {
+      candidatesBySessionId.set(sessionId, candidate);
+    }
+  }
+
+  const candidates = Array.from(candidatesBySessionId.values());
+
+  if (candidates.length === 0) {
+    return { sessionId: "", source: "none", reason: "no_active_session" };
+  }
+
+  candidates.sort((left, right) => {
+    if (right.recencyEpoch !== left.recencyEpoch) {
+      return right.recencyEpoch - left.recencyEpoch;
+    }
+    return left.sessionId.localeCompare(right.sessionId);
+  });
+
+  const [winner, runnerUp] = candidates;
+  if (runnerUp && runnerUp.recencyEpoch === winner.recencyEpoch) {
+    return {
+      sessionId: "",
+      source: "ambiguous",
+      reason: "multiple_active_sessions_same_recency",
+      candidates: candidates.map((candidate) => candidate.sessionId),
+    };
+  }
+
+  return {
+    sessionId: winner.sessionId,
+    source: "local_active_session",
+    title: winner.title || null,
+    candidates: candidates.map((candidate) => candidate.sessionId),
+  };
+}
+
+export async function resolveUsageSessionId({
+  explicitSessionId = "",
+  targetPath = process.cwd(),
+  env = process.env,
+  listActiveSessionsFn = listActiveSessions,
+} = {}) {
+  const explicit = normalizeTrustedUsageSessionId(explicitSessionId, "--notify-session");
+  if (explicit) {
+    return { sessionId: explicit, source: "explicit" };
+  }
+
+  const envSession = resolveEnvUsageSession(env);
+  if (envSession) {
+    return envSession;
+  }
+
+  try {
+    const sessions = await listActiveSessionsFn({ targetPath });
+    return selectMostRecentUsageSession(sessions);
+  } catch (error) {
+    return {
+      sessionId: "",
+      source: "error",
+      reason: "list_active_sessions_failed",
+      errorCode: error && typeof error === "object" ? normalizeString(error.code) || null : null,
+    };
+  }
+}