sentinelayer-cli 0.4.5 → 0.8.0

package/src/legacy-cli.js

@@ -21,6 +21,7 @@ import {
   resolveCodingAgent,
 } from "./config/agent-dictionary.js";
 import { resolveOutputRoot } from "./config/service.js";
+import { normalizeAgentEvent } from "./events/schema.js";
 import { collectCodebaseIngest, formatIngestSummary } from "./ingest/engine.js";
 import { getExpressTemplate, getPackageJsonTemplate, buildReadmeContent } from "./scaffold/templates.js";
 import { generateScaffold } from "./scaffold/generator.js";
@@ -203,6 +204,16 @@ function printUsage() {
   console.log("  sl auth sessions                   List stored session metadata");
   console.log("  sl auth logout                     Clear local session");
   console.log("");
+  console.log("Session Coordination:");
+  console.log("  sl session start --json            Create an agent coordination session");
+  console.log("  sl session join <id> --name <n>    Join a session as an agent");
+  console.log("  sl session say <id> \"msg\" --json  Append a message event to session stream");
+  console.log("  sl session read <id> --tail 20     Read session stream events");
+  console.log("  sl session status <id> --json      Show session health, agents, runs, leases");
+  console.log("  sl session leave <id>              Leave a session");
+  console.log("  sl session list --json             List active sessions");
+  console.log("  sl session kill --session <id> --agent <id>  Kill agent + revoke active leases");
+  console.log("");
   console.log("Security & Review:");
   console.log("  sl review scan --path . --json     Deterministic code review (full or --mode diff)");
   console.log("  sl /omargate deep --path . --json  Local Omar Gate security scan (P0/P1/P2 findings)");
@@ -809,7 +820,7 @@ function hasCommandOption(args, optionName) {
 async function collectScanFiles(rootPath) {
   const files = [];
   const stack = [rootPath];
-  const ignoredDirs = new Set([".git", "node_modules", ".venv", ".next", "dist", "build", ".sentinelayer"]);
+  const ignoredDirs = new Set([".git", "node_modules", ".venv", ".next", "dist", "build", "out", "coverage", "__pycache__", ".turbo", ".cache", ".parcel-cache", ".svelte-kit", ".nuxt", ".output", ".vercel", ".sentinelayer"]);
   const maxFileSizeBytes = 512 * 1024;
 
   while (stack.length > 0) {
@@ -942,7 +953,151 @@ function formatFindingsMarkdown(findings) {
     .join("\n");
 }
 
+const OMAR_SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const PERSONA_ICONS = {
+  security: "🛡️",
+  architecture: "🏗️",
+  backend: "⚙️",
+  testing: "🧪",
+  performance: "⚡",
+  compliance: "📋",
+  reliability: "🔄",
+  release: "🚀",
+  observability: "📊",
+  infrastructure: "☁️",
+  "supply-chain": "📦",
+  frontend: "🎨",
+  documentation: "📝",
+  "ai-governance": "🤖",
+  "code-quality": "💎",
+  data: "🗄️",
+};
+
+function formatElapsed(ms) {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const rem = seconds % 60;
+  return `${minutes}m${String(rem).padStart(2, "0")}s`;
+}
+
+function labelForPersona(payload) {
+  const identity = payload?.identity || {};
+  const short = identity.shortName || identity.fullName || "";
+  const id = payload?.personaId || "persona";
+  return short ? `${short} (${id})` : id;
+}
+
+function buildOmarTerminalHandler({ startedAt = Date.now() } = {}) {
+  let spinIdx = 0;
+  let spinInterval = null;
+  let currentMessage = "";
+
+  function startSpinner(msg) {
+    currentMessage = msg;
+    if (spinInterval) clearInterval(spinInterval);
+    spinInterval = setInterval(() => {
+      const frame = OMAR_SPINNER[spinIdx % OMAR_SPINNER.length];
+      process.stderr.write(`\r${pc.cyan(frame)} ${currentMessage}`);
+      spinIdx++;
+    }, 80);
+  }
+
+  function stopSpinner() {
+    if (spinInterval) {
+      clearInterval(spinInterval);
+      spinInterval = null;
+    }
+    process.stderr.write("\r" + " ".repeat(80) + "\r");
+  }
+
+  return (evt) => {
+    const normalizedEvent = normalizeAgentEvent(evt);
+    const event = normalizedEvent?.event || evt?.event || "";
+    const payload = normalizedEvent?.payload || evt?.payload || {};
+    const elapsed = formatElapsed(Date.now() - startedAt);
+
+    switch (event) {
+      case "omargate_start": {
+        const mode = payload.mode || "deep";
+        const roster = Array.isArray(payload.roster) ? payload.roster : [];
+        const count = roster.length || payload.personas?.length || 0;
+        console.error("");
+        console.error(pc.bold(pc.cyan(`  Omar Gate AI Analysis (${mode} — ${count} personas) ${pc.gray(`[${elapsed}]`)}`)));
+        console.error(pc.gray(`  Budget: $${(payload.maxCostUsd || 5).toFixed(2)} | Parallel: ${payload.maxParallel || 4}`));
+        if (roster.length) {
+          console.error("");
+          console.error(pc.bold("  Roster:"));
+          for (const member of roster) {
+            const icon = PERSONA_ICONS[member.id] || "🔍";
+            console.error(`    ${icon}  ${pc.white(member.fullName || member.id)} ${pc.gray(`— ${member.domain || member.id}`)}`);
+          }
+        }
+        console.error("");
+        startSpinner("Dispatching personas...");
+        break;
+      }
+      case "persona_start": {
+        const icon = PERSONA_ICONS[payload.personaId] || "🔍";
+        const label = labelForPersona(payload);
+        console.error(`  ${icon}  ${pc.cyan("→")} Dispatching ${pc.bold(label)} ${pc.gray(`[${elapsed}]`)}`);
+        startSpinner(`${icon}  ${label} analyzing...`);
+        break;
+      }
+      case "persona_finding": {
+        stopSpinner();
+        const sev = payload.severity || "P3";
+        const color = sev === "P0" ? pc.red : sev === "P1" ? pc.red : sev === "P2" ? pc.yellow : pc.gray;
+        const icon = PERSONA_ICONS[payload.personaId] || "🔍";
+        console.error(`  ${icon}  ${color(`[${sev}]`)} ${pc.white(payload.title || payload.message || "finding")} ${pc.gray(`(${payload.file || "?"}:${payload.line || "?"})`)}`);
+        startSpinner(`${icon}  ${labelForPersona(payload)} analyzing...`);
+        break;
+      }
+      case "persona_complete": {
+        stopSpinner();
+        const icon = PERSONA_ICONS[payload.personaId] || "🔍";
+        const count = payload.findings || 0;
+        const cost = payload.costUsd || 0;
+        const dur = ((payload.durationMs || 0) / 1000).toFixed(1);
+        const label = labelForPersona(payload);
+        console.error(`  ${icon}  ${pc.green("✓")} ${label} — ${count} finding${count === 1 ? "" : "s"} ${pc.gray(`($${cost.toFixed(4)}, ${dur}s, elapsed ${elapsed})`)}`);
+        break;
+      }
+      case "persona_skipped": {
+        stopSpinner();
+        const icon = PERSONA_ICONS[payload.personaId] || "🔍";
+        console.error(`  ${icon}  ${pc.gray("○")} ${labelForPersona(payload)} — skipped (${payload.reason || "budget"})`);
+        break;
+      }
+      case "persona_error": {
+        stopSpinner();
+        const icon = PERSONA_ICONS[payload.personaId] || "🔍";
+        console.error(`  ${icon}  ${pc.red("✗")} ${labelForPersona(payload)} — error: ${payload.error || "unknown"}`);
+        break;
+      }
+      case "omargate_complete": {
+        stopSpinner();
+        const s = payload.summary || {};
+        const total = payload.findings || 0;
+        const cost = (payload.totalCostUsd || 0).toFixed(4);
+        const dur = ((payload.totalDurationMs || 0) / 1000).toFixed(1);
+        const rec = payload.reconciliation || {};
+        console.error("");
+        console.error(pc.bold(`  AI Analysis Complete ${pc.gray(`[${elapsed}]`)}`));
+        console.error(`  Findings: ${pc.red(`P0=${s.P0 || 0}`)} ${pc.red(`P1=${s.P1 || 0}`)} ${pc.yellow(`P2=${s.P2 || 0}`)} ${pc.gray(`P3=${s.P3 || 0}`)} (${total} total)`);
+        if (rec.deterministicFindings !== undefined) {
+          console.error(pc.gray(`  Reconciled: ${rec.deterministicFindings} deterministic + ${rec.aiFindings} AI → ${rec.reconciledFindings} unique (${rec.multiSourceFindings || 0} confirmed by multiple layers)`));
+        }
+        console.error(`  Cost: $${cost} | Duration: ${dur}s | Personas: ${payload.personaCount || 0}`);
+        console.error("");
+        break;
+      }
+    }
+  };
+}
+
 async function runLocalOmarGateCommand(args) {
+  const commandStartedAt = Date.now();
   const mode = String(args[0] || "").trim().toLowerCase();
   if (mode && mode !== "deep") {
     throw new Error(`Unsupported /omargate mode '${mode}'. Use: /omargate deep`);
@@ -950,6 +1105,14 @@ async function runLocalOmarGateCommand(args) {
   const asJson = hasCommandOption(args, "--json");
   const pathArg = getCommandOptionValue(args, "--path") || ".";
   const outputDirArg = getCommandOptionValue(args, "--output-dir") || "";
+  const aiEnabled = !hasCommandOption(args, "--no-ai");
+  const aiDryRun = hasCommandOption(args, "--ai-dry-run");
+  const maxCostUsd = parseFloat(getCommandOptionValue(args, "--max-cost") || "5.0") || 5.0;
+  const modelOverride = getCommandOptionValue(args, "--model") || "";
+  const providerOverride = getCommandOptionValue(args, "--provider") || "";
+  const scanMode = getCommandOptionValue(args, "--scan-mode") || "deep";
+  const maxParallel = parseInt(getCommandOptionValue(args, "--max-parallel") || "4", 10) || 4;
+  const streamEnabled = hasCommandOption(args, "--stream");
   const targetPath = path.resolve(process.cwd(), pathArg);
   if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
     throw new Error(`Invalid --path target: ${targetPath}`);
@@ -958,21 +1121,208 @@ async function runLocalOmarGateCommand(args) {
   if (!asJson) {
     printSection("Local Omar Gate Deep");
     printInfo(`Target: ${targetPath}`);
+    printInfo(`Scan mode: ${scanMode} | AI: ${aiEnabled ? "enabled" : "disabled"}`);
+    console.error("");
+    console.error(pc.gray(`  [${formatElapsed(Date.now() - commandStartedAt)}] Phase 1: Deterministic analysis (22 rules)...`));
   }
 
-  const scan = await runCredentialScan(targetPath);
+  // Phase 1: Full 22-rule deterministic pipeline (replaces legacy 5-rule credential scan)
+  const { runDeterministicReviewPipeline } = await import("./review/local-review.js");
+  const deterministic = await runDeterministicReviewPipeline({
+    targetPath,
+    mode: "full",
+    outputDir: outputDirArg,
+  });
+
+  const detFindings = deterministic.findings || [];
+  const detSummary = deterministic.summary || { P0: 0, P1: 0, P2: 0, P3: 0, blocking: false };
+  const scannedFiles = deterministic.metadata?.ingest?.filesScanned || deterministic.metadata?.scannedFiles || detFindings.length;
+
+  if (!asJson) {
+    console.error(`  ${pc.green("✓")} [${formatElapsed(Date.now() - commandStartedAt)}] Deterministic: ${scannedFiles} files → P1=${detSummary.P1} P2=${detSummary.P2} findings`);
+    if (aiEnabled) {
+      console.error("");
+      console.error(pc.gray(`  [${formatElapsed(Date.now() - commandStartedAt)}] Phase 2: AI persona analysis via LLM...`));
+    }
+  }
+
+  // Phase 2: AI review layer (optional, default enabled)
+  let aiResult = null;
+  let orchestratorResult = null;
+  if (aiEnabled && scanMode) {
+    // Multi-persona orchestrator mode
+    try {
+      const { runOmarGateOrchestrator } = await import("./review/omargate-orchestrator.js");
+      const terminalHandler = (!asJson && !streamEnabled)
+        ? buildOmarTerminalHandler({ startedAt: commandStartedAt })
+        : null;
+      const streamHandler = streamEnabled
+        ? (evt) => console.log(JSON.stringify(evt))
+        : terminalHandler;
+
+      orchestratorResult = await runOmarGateOrchestrator({
+        targetPath,
+        scanMode,
+        maxParallel,
+        provider: providerOverride || undefined,
+        model: modelOverride || undefined,
+        maxCostUsd,
+        dryRun: aiDryRun,
+        outputDir: outputDirArg,
+        deterministic: {
+          summary: detSummary,
+          findings: detFindings,
+          metadata: deterministic.metadata || {},
+        },
+        onEvent: streamHandler,
+      });
+
+      // Use orchestrator results as the AI layer. aiResult represents ONLY
+      // the AI contribution — reconciliation is a separate top-level view.
+      const personaErrors = (orchestratorResult.personas || []).filter((p) => p.status === "error" || p.error);
+      const aiOnlyFindings = (orchestratorResult.findings || []).filter(
+        (f) => Array.isArray(f.sources) && f.sources.includes("ai")
+      );
+      const aiOnlySummary = {
+        P0: aiOnlyFindings.filter((f) => f.severity === "P0").length,
+        P1: aiOnlyFindings.filter((f) => f.severity === "P1").length,
+        P2: aiOnlyFindings.filter((f) => f.severity === "P2").length,
+        P3: aiOnlyFindings.filter((f) => f.severity === "P3").length,
+      };
+      aiResult = {
+        findings: aiOnlyFindings,
+        summary: aiOnlySummary,
+        costUsd: orchestratorResult.totalCostUsd || 0,
+        model: modelOverride || "multi-persona",
+        provider: providerOverride || "sentinelayer",
+        dryRun: aiDryRun,
+        personas: (orchestratorResult.personas || []).map((p) => ({
+          id: p.id || p.personaId,
+          identity: p.identity || null,
+          status: p.status,
+          findings: p.findings || 0,
+          costUsd: p.costUsd || 0,
+          durationMs: p.durationMs || 0,
+          error: p.error || null,
+        })),
+        errors: personaErrors.length > 0
+          ? personaErrors.map((p) => `${p.id || p.personaId}: ${p.error}`).join("; ")
+          : null,
+      };
+    } catch (aiError) {
+      if (!asJson) {
+        console.log(pc.yellow(`Orchestrator skipped: ${aiError.message}`));
+      }
+      aiResult = { skipped: true, reason: aiError.message, findings: [], summary: { P0: 0, P1: 0, P2: 0, P3: 0 } };
+    }
+  } else if (aiEnabled) {
+    // Single AI review layer (legacy, no --scan-mode)
+    try {
+      const { runAiReviewLayer } = await import("./review/ai-review.js");
+      aiResult = await runAiReviewLayer({
+        targetPath,
+        mode: "full",
+        runId: deterministic.metadata?.runId || `omargate-${nowIso()}`,
+        runDirectory: deterministic.artifacts?.runDirectory || targetPath,
+        deterministic: {
+          summary: detSummary,
+          findings: detFindings,
+          metadata: deterministic.metadata || {},
+        },
+        outputDir: outputDirArg,
+        provider: providerOverride || undefined,
+        model: modelOverride || undefined,
+        maxCostUsd,
+        dryRun: aiDryRun,
+        env: process.env,
+      });
+    } catch (aiError) {
+      if (!asJson) {
+        console.log(pc.yellow(`AI review layer skipped: ${aiError.message}`));
+      }
+      aiResult = { skipped: true, reason: aiError.message, findings: [], summary: { P0: 0, P1: 0, P2: 0, P3: 0 } };
+    }
+  }
+
+  // Reconciled findings: orchestrator already merges+dedupes deterministic+AI
+  // via reconcileReviewFindings. Use its output directly to avoid double-counting.
+  // Fallback path (legacy single ai-review): union of det + AI findings.
+  const aiFindings = aiResult?.findings || [];
+  const reconciledFromOrchestrator = orchestratorResult?.findings;
+  const allFindings = reconciledFromOrchestrator && reconciledFromOrchestrator.length >= 0
+    ? reconciledFromOrchestrator
+    : [...detFindings, ...aiFindings];
+  const combinedSummary = orchestratorResult?.summary || {
+    P0: detSummary.P0 + (aiResult?.summary?.P0 || 0),
+    P1: detSummary.P1 + (aiResult?.summary?.P1 || 0),
+    P2: detSummary.P2 + (aiResult?.summary?.P2 || 0),
+    P3: (detSummary.P3 || 0) + (aiResult?.summary?.P3 || 0),
+    blocking: (detSummary.P0 + (aiResult?.summary?.P0 || 0)) > 0 ||
+              (detSummary.P1 + (aiResult?.summary?.P1 || 0)) > 0,
+  };
+  const combinedP0 = combinedSummary.P0 || 0;
+  const combinedP1 = combinedSummary.P1 || 0;
+  const combinedP2 = combinedSummary.P2 || 0;
+  const combinedP3 = combinedSummary.P3 || 0;
+
+  // Write per-phase artifacts alongside REVIEW_DETERMINISTIC so post-mortems
+  // can inspect exactly what each layer contributed.
+  const reviewDir = deterministic?.artifacts?.runDirectory || "";
+  const writeJsonArtifact = async (name, payload) => {
+    if (!reviewDir) return null;
+    try {
+      const fp = path.join(reviewDir, name);
+      await fsp.writeFile(fp, JSON.stringify(payload, null, 2), "utf-8");
+      return fp;
+    } catch {
+      return null;
+    }
+  };
+  const artifactPaths = {};
+  if (orchestratorResult) {
+    artifactPaths.ai = await writeJsonArtifact("REVIEW_AI.json", {
+      runId: orchestratorResult.runId,
+      mode: orchestratorResult.mode,
+      roster: orchestratorResult.roster,
+      findings: (orchestratorResult.personas || []).flatMap((p) => []),
+      aiFindings: aiFindings,
+      personaCount: (orchestratorResult.personas || []).length,
+      totalCostUsd: orchestratorResult.totalCostUsd,
+      totalDurationMs: orchestratorResult.totalDurationMs,
+    });
+    artifactPaths.personas = await writeJsonArtifact("REVIEW_PERSONAS.json", {
+      runId: orchestratorResult.runId,
+      personas: orchestratorResult.personas || [],
+    });
+    artifactPaths.reconciled = await writeJsonArtifact("REVIEW_RECONCILED.json", {
+      runId: orchestratorResult.runId,
+      findings: orchestratorResult.findings || [],
+      summary: orchestratorResult.summary,
+      reconciliation: orchestratorResult.reconciliation,
+      findingsBySource: orchestratorResult.findingsBySource,
+    });
+  }
+
+  const totalElapsedMs = Date.now() - commandStartedAt;
+  const totalElapsed = formatElapsed(totalElapsedMs);
+
   const report = `# Local Omar Gate Deep Scan
 
 Generated: ${nowIso()}
 Target: ${targetPath}
+Elapsed: ${totalElapsed}
 
 Summary:
-- Files scanned: ${scan.scannedFiles}
-- P1 findings: ${scan.p1}
-- P2 findings: ${scan.p2}
+- Files scanned: ${scannedFiles}
+- Deterministic findings: P0=${detSummary.P0} P1=${detSummary.P1} P2=${detSummary.P2} P3=${detSummary.P3 || 0}
+- AI findings (raw, pre-reconciliation): ${aiResult ? `P0=${aiResult.summary?.P0 || 0} P1=${aiResult.summary?.P1 || 0} P2=${aiResult.summary?.P2 || 0} P3=${aiResult.summary?.P3 || 0}` : "skipped"}
+- Reconciled (deduped + confidence-boosted): P0=${combinedP0} P1=${combinedP1} P2=${combinedP2} P3=${combinedP3}
+${orchestratorResult?.reconciliation
+    ? `- Reconciliation: ${orchestratorResult.reconciliation.deterministicFindings} deterministic + ${orchestratorResult.reconciliation.aiFindings} AI → ${orchestratorResult.reconciliation.reconciledFindings} unique (${orchestratorResult.reconciliation.multiSourceFindings} multi-source confirmed, ${orchestratorResult.reconciliation.dedupedCount} deduped)`
+    : ""}
 
 Findings:
-${formatFindingsMarkdown(scan.findings)}
+${formatFindingsMarkdown(allFindings)}
 `;
 
   const reportPath = await writeLocalCommandReport(targetPath, "omargate-deep", report, {
@@ -985,10 +1335,31 @@ ${formatFindingsMarkdown(scan.findings)}
           command: "/omargate deep",
           targetPath,
           reportPath,
-          scannedFiles: scan.scannedFiles,
-          p1: scan.p1,
-          p2: scan.p2,
-          blocking: scan.p1 > 0,
+          scannedFiles,
+          p0: combinedP0,
+          p1: combinedP1,
+          p2: combinedP2,
+          p3: combinedP3,
+          blocking: combinedP0 > 0 || combinedP1 > 0,
+          elapsedMs: totalElapsedMs,
+          artifacts: artifactPaths,
+          deterministic: {
+            findings: detFindings.length,
+            summary: detSummary,
+          },
+          ai: aiResult
+            ? {
+                findings: aiFindings.length,
+                summary: aiResult.summary || {},
+                model: aiResult.model || null,
+                provider: aiResult.provider || null,
+                costUsd: aiResult.costUsd || 0,
+                dryRun: aiDryRun,
+                personas: aiResult.personas || [],
+              }
+            : null,
+          reconciliation: orchestratorResult?.reconciliation || null,
+          roster: orchestratorResult?.roster || [],
         },
         null,
         2
@@ -996,13 +1367,19 @@ ${formatFindingsMarkdown(scan.findings)}
     );
   } else {
     console.log(pc.cyan(`Report: ${reportPath}`));
-    console.log(`P1 findings: ${scan.p1}`);
-    console.log(`P2 findings: ${scan.p2}`);
+    console.log(`Deterministic: P1=${detSummary.P1} P2=${detSummary.P2}`);
+    if (aiResult) {
+      console.log(`AI layer: P1=${aiResult.summary?.P1 || 0} P2=${aiResult.summary?.P2 || 0} (model: ${aiResult.model || "default"}, cost: $${(aiResult.costUsd || 0).toFixed(4)})`);
+    } else if (aiEnabled) {
+      console.log(pc.gray("AI layer: skipped (no credentials or --no-ai)"));
+    }
+    console.log(pc.bold(`Reconciled: P0=${combinedP0} P1=${combinedP1} P2=${combinedP2} P3=${combinedP3}`));
+    console.log(pc.gray(`Elapsed: ${totalElapsed}`));
   }
 
-  if (scan.p1 > 0) {
+  if (combinedP0 > 0 || combinedP1 > 0) {
     if (!asJson) {
-      console.log(pc.red("Blocking findings detected (P1 > 0)."));
+      console.log(pc.red(`Blocking findings detected (P0=${combinedP0}, P1=${combinedP1}) after reconciliation.`));
     }
     return 2;
   }
@@ -1503,7 +1880,7 @@ async function ensureCodingAgentConfigFile({ projectDir, projectName, codingAgen
   };
 }
 
-function buildTodoContent({
+export function buildTodoContent({
   projectName,
   aiProvider,
   codingAgent,
@@ -1543,6 +1920,8 @@ Project: ${projectName}
 - [ ] PR 10: scale/performance tuning and caching strategy
 - [ ] PR 11: observability, retries, timeout policies, and structured logs
 - [ ] PR 12: docs, release, rollout safety checks, and production readiness
+- [ ] If working with other agents, join the SentinelLayer session and emit status updates
+- [ ] Update tasks/lessons.md with coordination patterns learned during this session
 
 ## Omar Loop Contract (Per PR)
 - [ ] Run Omar Gate for the PR.
@@ -1593,7 +1972,7 @@ function buildAgentPromptGuidance(promptTarget) {
 - Document assumptions and unresolved risks clearly.`;
 }
 
-function buildHandoffPrompt({
+export function buildHandoffPrompt({
   projectName,
   repoSlug,
   secretName,
@@ -1614,8 +1993,8 @@ function buildHandoffPrompt({
 - If you later adopt Omar Gate GitHub Action, set secrets.${secretName} and wire sentinelayer_token accordingly.`;
   const workflowTuning =
     authMode === "sentinelayer"
-      ? `- scan_mode: deep (default) or quick
-- severity_gate: P1 (default) or P2`
+      ? `- scan_mode: baseline | deep (default) | audit | full-depth
+- severity_gate: P0 | P1 (default) | P2 | none`
       : `- BYOK workflow is guidance-only and does not call the Sentinelayer action.
 - To enable Omar Gate later, set ${secretName} and configure scan_mode/severity_gate in workflow inputs.`;
 
@@ -1663,12 +2042,51 @@ Repo context:
 - Target repo: ${repoSlug || "not provided"}
 - Workspace mode: ${buildFromExistingRepo ? "existing codebase" : "new scaffold"}
 
+## Multi-Agent Coordination (if session active)
+
+If a SentinelLayer session is active (check \`sl session list\`):
+
+1. **On start:** Run \`sl session join <id> --name <your-name> --role coder\`
+2. **Periodically:** Run \`sl session say <id> "status: working on <file>"\` so others know what you're doing
+3. **On unexpected file change:** Instead of stopping, run:
+   \`sl session say <id> "help: unexpected change in <file> - who modified this?"\`
+   Then check \`sl session read <id> --tail 5\` for the answer and continue.
+4. **On findings:** Run \`sl session say <id> "finding: [P2] <title> in <file>:<line>"\`
+5. **On completion:** Run \`sl session leave <id>\`
+6. **Before modifying a file:** Check \`sl session read <id> --tail 10\` for recent activity on that file
+
 Start now and continue autonomously.
 `;
 }
 
-function fallbackWorkflow({ secretName = "SENTINELAYER_TOKEN", authMode = "sentinelayer" } = {}) {
+export function buildAgentsSessionGuideContent() {
+  return `# SentinelLayer Session Guide for AI Agents
+
+## Quick Start
+1. Check: \`sl session list\` - is there an active session?
+2. Join: \`sl session join <id> --name <your-short-name> --role <coder|reviewer|tester>\`
+3. Read context: \`sl session read <id> --tail 20\` — see what others are doing
+4. Work: emit status every 5 min, post findings, ask for help instead of stopping
+5. Leave: \`sl session leave <id>\` when done
+
+## Why This Matters
+- Other agents can see what you're working on and avoid file conflicts
+- If you see an unexpected file change, ask in the session first
+- Findings are shared immediately so other agents can act quickly
+- The daemon can monitor health and alert when agents appear stuck
+
+## What to Emit
+- Status: \`sl session say <id> "status: implementing JWT middleware in src/middleware/auth.js"\`
+- Finding: \`sl session say <id> "finding: [P2] missing rate limit on POST /api/auth/login"\`
+- Help: \`sl session say <id> "help: unexpected change in package.json - who modified it?"\`
+- Done: \`sl session say <id> "done: PR merged, auth hardening complete"\`
+`;
+}
+
+function fallbackWorkflow({ secretName = "SENTINELAYER_TOKEN", authMode = "sentinelayer", specId = "" } = {}) {
   const normalizedSecret = isValidSecretName(secretName) ? secretName : "SENTINELAYER_TOKEN";
+  const normalizedSpecId = String(specId || "").trim();
+  const specIdBindingLine = normalizedSpecId ? `\n          sentinelayer_spec_id: ${normalizedSpecId}` : "";
   const workflowName = authMode === "byok" ? "Omar Gate (BYOK Mode)" : "Omar Gate";
   return `name: ${workflowName}
 
@@ -1686,8 +2104,10 @@ on:
         default: deep
         type: choice
         options:
+          - baseline
           - deep
-          - nightly
+          - audit
+          - full-depth
       severity_gate:
         description: Severity threshold that blocks merge
         required: false
@@ -1737,9 +2157,9 @@ jobs:
           fi
       - name: Run Omar Gate
         id: omar
-        uses: mrrCarter/sentinelayer-v1-action@v1
+        uses: mrrCarter/sentinelayer-v1-action@55a2c158f637d7d92e26ab0ef3ba81db791da4be
         with:
-          sentinelayer_token: \${{ secrets.${normalizedSecret} }}
+          sentinelayer_token: \${{ secrets.${normalizedSecret} }}${specIdBindingLine}
           scan_mode: \${{ github.event_name == 'workflow_dispatch' && inputs.scan_mode || 'deep' }}
           severity_gate: \${{ github.event_name == 'workflow_dispatch' && inputs.severity_gate || 'P1' }}
       - name: Enforce Omar reviewer merge thresholds
@@ -1932,6 +2352,71 @@ function runGhSecretSet({ repoSlug, secretName, secretValue }) {
   return { ok: true };
 }
 
+function extractWorkflowSpecId(workflowMarkdown) {
+  const normalized = String(workflowMarkdown || "");
+  const match = normalized.match(/sentinelayer_spec_id:\s*([^\s#]+)/);
+  return match ? String(match[1] || "").trim() : "";
+}
+
+function resolveGeneratedSpecId(generated) {
+  const candidates = [
+    generated?.spec_id,
+    generated?.specId,
+    generated?.spec_hash,
+    generated?.specHash,
+  ];
+  for (const candidate of candidates) {
+    const normalized = String(candidate || "").trim();
+    if (normalized) return normalized;
+  }
+  return "";
+}
+
+async function writeInitConfigLockfile({
+  projectDir,
+  specId,
+  sentinelayerToken,
+  secretName,
+  repoSlug,
+  workflowPath,
+}) {
+  const lockDir = path.join(projectDir, ".sentinelayer");
+  const configPath = path.join(lockDir, "config.json");
+  const payload = {
+    schema_version: 1,
+    generated_at: new Date().toISOString(),
+    spec_id: String(specId || "").trim(),
+    sentinelayer_token: String(sentinelayerToken || "").trim(),
+    required_secret_name: String(secretName || "SENTINELAYER_TOKEN").trim() || "SENTINELAYER_TOKEN",
+    repo_slug: normalizeRepoSlug(repoSlug || ""),
+    workflow_path: path.relative(projectDir, workflowPath).replace(/\\/g, "/"),
+  };
+
+  await fsp.mkdir(lockDir, { recursive: true });
+  await fsp.writeFile(configPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8");
+  return configPath;
+}
+
+async function validateWorkflowSpecBinding({ workflowPath, expectedSpecId }) {
+  const expected = String(expectedSpecId || "").trim();
+  if (!expected) {
+    throw new Error("Missing spec_id/spec_hash in generated builder response. Cannot validate Omar spec binding.");
+  }
+  const workflowMarkdown = await fsp.readFile(workflowPath, "utf-8");
+  const workflowSpecId = extractWorkflowSpecId(workflowMarkdown);
+  if (!workflowSpecId) {
+    throw new Error(
+      `Generated workflow '${workflowPath}' is missing sentinelayer_spec_id. Regenerate the workflow before continuing.`
+    );
+  }
+  if (workflowSpecId !== expected) {
+    throw new Error(
+      `Workflow spec binding mismatch: expected '${expected}' but workflow has '${workflowSpecId}'.`
+    );
+  }
+  return workflowSpecId;
+}
+
 async function collectInterview({ initialProjectName, detectedRepo, detectedCodingAgent }) {
   const onCancel = () => {
     throw new Error("Prompt flow cancelled by user.");
@@ -2432,6 +2917,7 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
   const docsDir = path.join(projectDir, "docs");
   const promptsDir = path.join(projectDir, "prompts");
   const tasksDir = path.join(projectDir, "tasks");
+  const workflowPath = path.join(projectDir, ".github", "workflows", "omar-gate.yml");
 
   await writeTextFile(path.join(docsDir, "spec.md"), String(generated.spec_sheet || "").trim() + "\n");
   await writeTextFile(
@@ -2442,13 +2928,34 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
     path.join(promptsDir, "execution-prompt.md"),
     String(generated.builder_prompt || "").trim() + "\n"
   );
-  await writeTextFile(
-    path.join(projectDir, ".github", "workflows", "omar-gate.yml"),
+  const generatedSpecId = resolveGeneratedSpecId(generated);
+  if (effectiveAuthMode === "sentinelayer" && !generatedSpecId) {
+    throw new Error("Builder response is missing spec_id/spec_hash. Cannot generate a validated Omar Gate workflow.");
+  }
+  const workflowMarkdown =
     (
       (effectiveAuthMode === "sentinelayer" ? String(generated.omar_gate_yaml || "").trim() : "") ||
-      fallbackWorkflow({ secretName, authMode: effectiveAuthMode })
-    ) + "\n"
-  );
+      fallbackWorkflow({ secretName, authMode: effectiveAuthMode, specId: generatedSpecId })
+    ) + "\n";
+  await writeTextFile(workflowPath, workflowMarkdown);
+
+  const workflowSpecIdFromTemplate = extractWorkflowSpecId(workflowMarkdown);
+  let workflowSpecId = "";
+  if (generatedSpecId || workflowSpecIdFromTemplate) {
+    workflowSpecId = await validateWorkflowSpecBinding({
+      workflowPath,
+      expectedSpecId: generatedSpecId || workflowSpecIdFromTemplate,
+    });
+  }
+  const configLockfilePath = await writeInitConfigLockfile({
+    projectDir,
+    specId: workflowSpecId || generatedSpecId || workflowSpecIdFromTemplate,
+    sentinelayerToken,
+    secretName,
+    repoSlug: interview.repoSlug || detectRepoSlug(projectDir) || "",
+    workflowPath,
+  });
+
   await writeTextFile(
     path.join(tasksDir, "todo.md"),
     buildTodoContent({
@@ -2474,6 +2981,10 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
       codingAgent: interview.codingAgent,
     })
   );
+  await writeTextFile(
+    path.join(projectDir, ".sentinelayer", "AGENTS_SESSION_GUIDE.md"),
+    buildAgentsSessionGuideContent()
+  );
   const codingAgentConfig = await ensureCodingAgentConfigFile({
     projectDir,
     projectName: effectiveProjectName,
@@ -2524,17 +3035,59 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
     repoSlug: interview.connectRepo ? interview.repoSlug : "",
   });
 
-  let secretInjection = { ok: false, reason: "Skipped." };
-  if (interview.connectRepo && interview.injectSecret && interview.repoSlug && sentinelayerToken) {
-    secretInjection = runGhSecretSet({
-      repoSlug: interview.repoSlug,
+  const repoSlugForSecrets = normalizeRepoSlug(interview.repoSlug || detectRepoSlug(projectDir) || "");
+  const openAiApiKey = String(process.env.OPENAI_API_KEY || "").trim();
+  const secretTargets = [];
+  if (sentinelayerToken) {
+    secretTargets.push({
       secretName,
       secretValue: sentinelayerToken,
+      placeholder: "<sentinelayer-token>",
     });
   }
+  secretTargets.push({
+    secretName: "OPENAI_API_KEY",
+    secretValue: openAiApiKey,
+    placeholder: "<your-openai-api-key>",
+  });
+
+  const githubSecretResults = [];
+  if (repoSlugForSecrets) {
+    for (const target of secretTargets) {
+      const value = String(target.secretValue || "").trim();
+      if (!value) {
+        githubSecretResults.push({
+          secretName: target.secretName,
+          ok: false,
+          skipped: true,
+          reason: `No value resolved for ${target.secretName} in current environment/config.`,
+          placeholder: target.placeholder,
+        });
+        continue;
+      }
+      const result = runGhSecretSet({
+        repoSlug: repoSlugForSecrets,
+        secretName: target.secretName,
+        secretValue: value,
+      });
+      githubSecretResults.push({
+        secretName: target.secretName,
+        ok: Boolean(result.ok),
+        skipped: false,
+        reason: String(result.reason || "").trim(),
+        placeholder: target.placeholder,
+      });
+    }
+  }
 
   printSection("Complete");
   console.log(pc.green(`✔ Sentinelayer orchestration initialized in ${projectDir}`));
+  console.log(pc.green(`✔ Config lockfile written: ${configLockfilePath}`));
+  if (workflowSpecId) {
+    console.log(pc.green(`✔ Omar workflow spec binding validated: ${workflowSpecId}`));
+  } else {
+    console.log(pc.yellow("! Omar workflow did not expose sentinelayer_spec_id (BYOK/fallback mode)."));
+  }
   if (sentinelayerToken) {
     console.log(pc.green(`✔ ${secretName} injected into ${path.join(projectDir, ".env")}`));
   } else {
@@ -2545,14 +3098,30 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
       pc.green(`✔ ${codingAgentConfig.agent.name} config scaffolded at ${codingAgentConfig.path}`)
     );
   }
-  if (interview.connectRepo && interview.injectSecret && sentinelayerToken) {
-    if (secretInjection.ok) {
-      console.log(pc.green(`✔ ${secretName} injected into GitHub repo secret (${interview.repoSlug})`));
-    } else {
-      console.log(pc.yellow(`! GitHub secret injection skipped/failed: ${secretInjection.reason}`));
+  if (repoSlugForSecrets) {
+    for (const result of githubSecretResults) {
+      if (result.ok) {
+        console.log(pc.green(`✔ ${result.secretName} injected into GitHub repo secret (${repoSlugForSecrets})`));
+        continue;
+      }
+      const stateLabel = result.skipped ? "skipped" : "failed";
+      console.log(pc.yellow(`! GitHub secret injection ${stateLabel} for ${result.secretName}: ${result.reason}`));
+      console.log(
+        pc.yellow(
+          `  Run manually: gh secret set ${result.secretName} --repo ${repoSlugForSecrets} --body ${result.placeholder}`
+        )
+      );
+    }
+  } else if (secretTargets.length > 0) {
+    console.log(
+      pc.yellow(
+        "! GitHub secret auto-injection skipped: no repo slug detected. Connect a repo or run manual secret commands."
+      )
+    );
+    for (const target of secretTargets) {
       console.log(
         pc.yellow(
-          `  Run manually: gh secret set ${secretName} --repo ${interview.repoSlug || "<owner/repo>"}`
+          `  Run manually: gh secret set ${target.secretName} --repo <owner/repo> --body ${target.placeholder}`
         )
       );
     }