sentinelayer-cli 0.8.11 → 0.9.0

package/src/cost/history.js

@@ -7,6 +7,7 @@ import { rollupUsage } from "./tracker.js";
 
 const HISTORY_VERSION = 1;
 const HISTORY_FILE_NAME = "cost-history.json";
+const costHistoryWriteQueues = new Map();
 
 function normalizeNumber(value, field) {
   const normalized = Number(value || 0);
@@ -76,6 +77,14 @@ export async function resolveCostHistoryPath({
 
 export async function loadCostHistory(options = {}) {
   const filePath = await resolveCostHistoryPath(options);
+  const history = await readCostHistoryFile(filePath);
+  return {
+    filePath,
+    history,
+  };
+}
+
+async function readCostHistoryFile(filePath) {
   try {
     const raw = await fsp.readFile(filePath, "utf-8");
     const parsed = JSON.parse(raw);
@@ -83,20 +92,14 @@ export async function loadCostHistory(options = {}) {
       throw new Error("Invalid cost history payload.");
     }
     return {
-      filePath,
-      history: {
-        version: Number(parsed.version || HISTORY_VERSION),
-        entries: parsed.entries,
-      },
+      version: Number(parsed.version || HISTORY_VERSION),
+      entries: parsed.entries,
     };
   } catch (error) {
     if (error && typeof error === "object" && error.code === "ENOENT") {
       return {
-        filePath,
-        history: {
-          version: HISTORY_VERSION,
-          entries: [],
-        },
+        version: HISTORY_VERSION,
+        entries: [],
       };
     }
     throw error;
@@ -114,17 +117,34 @@ export async function saveCostHistory({ filePath, history }) {
 
 export async function appendCostEntry(options = {}, entry = {}) {
   const normalizedEntry = normalizeEntry(entry);
-  const { filePath, history } = await loadCostHistory(options);
-  const nextHistory = {
-    version: HISTORY_VERSION,
-    entries: [...history.entries, normalizedEntry],
-  };
-  await saveCostHistory({ filePath, history: nextHistory });
-  return {
-    filePath,
-    entry: normalizedEntry,
-    history: nextHistory,
-  };
+  const filePath = await resolveCostHistoryPath(options);
+  return withCostHistoryWriteQueue(filePath, async () => {
+    const history = await readCostHistoryFile(filePath);
+    const nextHistory = {
+      version: HISTORY_VERSION,
+      entries: [...history.entries, normalizedEntry],
+    };
+    await saveCostHistory({ filePath, history: nextHistory });
+    return {
+      filePath,
+      entry: normalizedEntry,
+      history: nextHistory,
+    };
+  });
+}
+
+async function withCostHistoryWriteQueue(filePath, fn) {
+  const previous = costHistoryWriteQueues.get(filePath) || Promise.resolve();
+  const next = previous.catch(() => {}).then(fn);
+  const queued = next.catch(() => {});
+  costHistoryWriteQueues.set(filePath, queued);
+  try {
+    return await next;
+  } finally {
+    if (costHistoryWriteQueues.get(filePath) === queued) {
+      costHistoryWriteQueues.delete(filePath);
+    }
+  }
 }
 
 function summarizeSessionEntries(entries) {

package/src/events/schema.js

@@ -1,5 +1,31 @@
 const AGENT_EVENT_STREAM = "sl_event";
 const LEGACY_AGENT_ID = "legacy-emitter";
+const AGENT_EVENT_TYPES = Object.freeze([
+  "agent_start",
+  "agent_complete",
+  "agent_abort",
+  "agent_error",
+  "progress",
+  "heartbeat",
+  "tool_call",
+  "tool_result",
+  "finding",
+  "reasoning",
+  "budget_warning",
+  "budget_stop",
+  "swarm_start",
+  "swarm_complete",
+  "phase_start",
+  "phase_complete",
+  "orchestrator_start",
+  "dispatch",
+  "reconcile_start",
+  "reconcile_complete",
+  "orchestrator_complete",
+  "convergence_expansion",
+  "coverage_gap",
+  "llm_error",
+]);
 
 function isPlainObject(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -187,4 +213,4 @@ export function validateAgentEvent(evt, options = {}) {
   return Boolean(normalizeAgentEvent(evt, options));
 }
 
-export { AGENT_EVENT_STREAM };
+export { AGENT_EVENT_STREAM, AGENT_EVENT_TYPES };

package/src/guide/generator.js

@@ -1,3 +1,9 @@
+import {
+  getCoordinationEtiquetteItems,
+  renderCoordinationMarkdownSection,
+  renderCoordinationTicketBlock,
+} from "../session/coordination-guidance.js";
+
 export const SUPPORTED_GUIDE_EXPORT_FORMATS = Object.freeze([
   "jira",
   "linear",
@@ -167,6 +173,8 @@ function buildTicket(phase, index) {
       "",
       "Acceptance criteria:",
       acceptanceBlock || "1. Phase outcomes are verified by deterministic checks.",
+      "",
+      renderCoordinationTicketBlock(),
     ].join("\n"),
   };
 }
@@ -235,6 +243,8 @@ ${goal}
 ## Phase Execution Plan
 ${phaseMarkdown}
 
+${renderCoordinationMarkdownSection()}
+
 ## Suggested PR Sequence
 ${resolvedPhases
   .map((phase, index) => `${index + 1}. ${phase.title} (${phase.effort.label})`)
@@ -246,6 +256,7 @@ ${resolvedPhases
     goal,
     phases: resolvedPhases,
     tickets,
+    coordinationRules: getCoordinationEtiquetteItems(),
     markdown,
   };
 }
@@ -256,12 +267,14 @@ export function renderGuideExport({ format, guide }) {
     project: guide.projectName,
     generated_at: new Date().toISOString(),
     issues: guide.tickets,
+    coordination_rules: Array.isArray(guide.coordinationRules) ? guide.coordinationRules : [],
   };
 
   if (normalized === "jira") {
     return JSON.stringify(
       {
         format: "jira",
+        coordination_rules: payload.coordination_rules,
         issues: payload.issues.map((issue) => ({
           summary: issue.title,
           description: issue.description,
@@ -279,6 +292,7 @@ export function renderGuideExport({ format, guide }) {
     return JSON.stringify(
       {
         format: "linear",
+        coordination_rules: payload.coordination_rules,
         issues: payload.issues.map((issue, index) => ({
           title: issue.title,
           description: issue.description,

package/src/legacy-cli.js

@@ -25,6 +25,10 @@ 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";
+import {
+  getCoordinationEtiquetteItems,
+  renderCoordinationNumberedList,
+} from "./session/coordination-guidance.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";
@@ -1121,6 +1125,10 @@ async function runLocalOmarGateCommand(args) {
     const maxParallel =
       parseInt(getCommandOptionValue(args, "--max-parallel") || "3", 10) || 3;
     const streamEnabled = hasCommandOption(args, "--stream");
+    const devTestBotEnabled = !hasCommandOption(args, "--no-devtestbot");
+    const devTestBotBaseUrl = getCommandOptionValue(args, "--devtestbot-base-url") || "";
+    const devTestBotScope = getCommandOptionValue(args, "--devtestbot-scope") || "";
+    const emailOnComplete = getCommandOptionValue(args, "--email-on-complete") || "";
 
     const targetPath = path.resolve(process.cwd(), pathArg);
     if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
@@ -1128,6 +1136,9 @@ async function runLocalOmarGateCommand(args) {
     }
 
     const { runInvestorDd } = await import("./review/investor-dd-orchestrator.js");
+    const reportEmailClient = emailOnComplete
+      ? await import("./review/dd-report-email-client.js")
+      : null;
     if (!asJson) {
       printSection("Investor-DD Audit");
       printInfo(`Target: ${targetPath}`);
@@ -1141,6 +1152,24 @@ async function runLocalOmarGateCommand(args) {
       outputDir: outputDirArg,
       budgetOptions: { maxCostUsd, maxRuntimeMinutes, maxParallel },
       dryRun,
+      devTestBot: {
+        enabled: devTestBotEnabled,
+        baseUrl: devTestBotBaseUrl,
+        scope: devTestBotScope,
+      },
+      reportEmail: emailOnComplete
+        ? {
+            to: emailOnComplete,
+            client: {
+              send: ({ runId, to }) => reportEmailClient.sendDdReportEmail({
+                runId,
+                to,
+                cwd: targetPath,
+                env: process.env,
+              }),
+            },
+          }
+        : null,
       onEvent: streamEnabled
         ? (event) => process.stdout.write(`${JSON.stringify(event)}\n`)
         : () => {},
@@ -1237,7 +1266,10 @@ async function runLocalOmarGateCommand(args) {
         deterministic: {
           summary: detSummary,
           findings: detFindings,
+          scope: deterministic.scope || {},
+          layers: deterministic.layers || {},
           metadata: deterministic.metadata || {},
+          artifacts: deterministic.artifacts || {},
         },
         onEvent: streamHandler,
         includeOnly: includeOnly.length > 0 ? includeOnly : null,
@@ -1331,6 +1363,7 @@ async function runLocalOmarGateCommand(args) {
   const combinedP1 = combinedSummary.P1 || 0;
   const combinedP2 = combinedSummary.P2 || 0;
   const combinedP3 = combinedSummary.P3 || 0;
+  const omargateRunId = orchestratorResult?.runId || deterministic.runId;
 
   // Write per-phase artifacts alongside REVIEW_DETERMINISTIC so post-mortems
   // can inspect exactly what each layer contributed.
@@ -1376,6 +1409,7 @@ async function runLocalOmarGateCommand(args) {
   const report = `# Local Omar Gate Deep Scan
 
 Generated: ${nowIso()}
+Run ID: ${omargateRunId}
 Target: ${targetPath}
 Elapsed: ${totalElapsed}
 
@@ -1395,12 +1429,24 @@ ${formatFindingsMarkdown(allFindings)}
   const reportPath = await writeLocalCommandReport(targetPath, "omargate-deep", report, {
     outputDir: outputDirArg,
   });
+  const { writeOmarGateDeterministicCache } = await import("./review/omargate-cache.js");
+  const deterministicCache = await writeOmarGateDeterministicCache({
+    targetPath,
+    outputDir: outputDirArg,
+    runId: omargateRunId,
+    deterministic,
+    reportPath,
+  });
+  artifactPaths.deterministicCache = deterministicCache.artifactPath;
+  artifactPaths.latestOmarGate = deterministicCache.latestPath;
+
   if (asJson) {
     console.log(
       JSON.stringify(
         {
           command: "/omargate deep",
           targetPath,
+          runId: omargateRunId,
           reportPath,
           scannedFiles,
           p0: combinedP0,
@@ -1457,6 +1503,7 @@ async function runLocalAuditCommand(args) {
   const asJson = hasCommandOption(args, "--json");
   const pathArg = getCommandOptionValue(args, "--path") || ".";
   const outputDirArg = getCommandOptionValue(args, "--output-dir") || "";
+  const reuseOmarGate = getCommandOptionValue(args, "--reuse-omargate") || "";
   const targetPath = path.resolve(process.cwd(), pathArg);
   if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
     throw new Error(`Invalid --path target: ${targetPath}`);
@@ -1467,6 +1514,16 @@ async function runLocalAuditCommand(args) {
     printInfo(`Target: ${targetPath}`);
   }
 
+  const buildScanFromOmarGateCache = (cache) => {
+    const findings = Array.isArray(cache?.findings) ? cache.findings : [];
+    return {
+      scannedFiles: Number(cache?.scope?.scannedFiles || findings.length || 0),
+      findings,
+      p1: findings.filter((item) => item.severity === "P1").length,
+      p2: findings.filter((item) => item.severity === "P2").length,
+    };
+  };
+
   const requiredChecks = [
     {
       key: ".github/workflows/omar-gate.yml",
@@ -1488,7 +1545,44 @@ async function runLocalAuditCommand(args) {
     },
   ];
 
-  const scan = await runCredentialScan(targetPath);
+  let omargateReuse = {
+    requested: reuseOmarGate || "",
+    used: false,
+    runId: "",
+    artifactPath: "",
+    reason: reuseOmarGate ? "not_found" : "not_requested",
+  };
+  let scan = null;
+  if (reuseOmarGate) {
+    const { loadOmarGateDeterministicCache } = await import("./review/omargate-cache.js");
+    const reused = await loadOmarGateDeterministicCache({
+      targetPath,
+      outputDir: outputDirArg,
+      runIdOrLatest: reuseOmarGate,
+    });
+    if (reused.found) {
+      scan = buildScanFromOmarGateCache(reused.cache);
+      omargateReuse = {
+        requested: reuseOmarGate,
+        used: true,
+        runId: reused.runId,
+        deterministicRunId: reused.cache?.deterministicRunId || "",
+        artifactPath: reused.artifactPath,
+        reason: "",
+      };
+    } else {
+      omargateReuse = {
+        requested: reuseOmarGate,
+        used: false,
+        runId: "",
+        artifactPath: "",
+        reason: reused.reason || "not_found",
+      };
+    }
+  }
+  if (!scan) {
+    scan = await runCredentialScan(targetPath);
+  }
   const failedP1Checks = requiredChecks.filter((item) => !item.ok && item.severity === "P1").length;
   const failedP2Checks = requiredChecks.filter((item) => !item.ok && item.severity === "P2").length;
   const totalP1 = scan.p1 + failedP1Checks;
@@ -1506,11 +1600,13 @@ async function runLocalAuditCommand(args) {
 Generated: ${nowIso()}
 Target: ${targetPath}
 Overall status: ${overallStatus}
+OmarGate reuse: ${omargateReuse.used ? `yes (${omargateReuse.runId})` : omargateReuse.requested ? `requested ${omargateReuse.requested} (${omargateReuse.reason})` : "no"}
 
 Readiness checks:
 ${checkText}
 
 Scan summary:
+- Reused OmarGate run: ${omargateReuse.used ? omargateReuse.runId : "n/a"}
 - Files scanned: ${scan.scannedFiles}
 - P1 findings: ${scan.p1}
 - P2 findings: ${scan.p2}
@@ -1536,6 +1632,9 @@ ${formatFindingsMarkdown(scan.findings)}
           p1Total: totalP1,
           p2Total: totalP2,
           blocking: totalP1 > 0,
+          omargateReuse,
+          reusedOmarGateRunId: omargateReuse.used ? omargateReuse.runId : "",
+          reusedOmarGateDeterministicPath: omargateReuse.used ? omargateReuse.artifactPath : "",
         },
         null,
         2
@@ -1543,6 +1642,11 @@ ${formatFindingsMarkdown(scan.findings)}
     );
   } else {
     console.log(pc.cyan(`Report: ${reportPath}`));
+    if (omargateReuse.used) {
+      console.log(pc.gray(`Reused OmarGate run: ${omargateReuse.runId}`));
+    } else if (omargateReuse.requested) {
+      console.log(pc.gray(`OmarGate reuse unavailable: ${omargateReuse.reason}`));
+    }
     console.log(`Overall status: ${overallStatus}`);
     console.log(`P1 total: ${totalP1}`);
     console.log(`P2 total: ${totalP2}`);
@@ -1875,6 +1979,7 @@ function buildCodingAgentConfigTemplate({ agentProfile, projectName }) {
     "Read docs/spec.md, docs/build-guide.md, tasks/todo.md, and AGENT_HANDOFF_PROMPT.md in order.",
     "Work one PR scope at a time and keep changes deterministic.",
     "Run local checks before push: /omargate deep and /audit.",
+    ...getCoordinationEtiquetteItems(),
   ];
 
   if (agentProfile.id === "aider") {
@@ -1885,7 +1990,7 @@ read:
   - tasks/todo.md
   - AGENT_HANDOFF_PROMPT.md
 notes:
-  - ${commonChecklist.join("\n  - ")}
+  - ${commonChecklist.map((item) => JSON.stringify(item)).join("\n  - ")}
 `;
   }
 
@@ -2111,16 +2216,7 @@ Repo context:
 
 ## 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
+${renderCoordinationNumberedList()}
 
 Start now and continue autonomously.
 `;
@@ -2129,12 +2225,8 @@ Start now and continue autonomously.
 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
+## Required Etiquette
+${renderCoordinationNumberedList()}
 
 ## Why This Matters
 - Other agents can see what you're working on and avoid file conflicts

package/src/prompt/generator.js

@@ -1,3 +1,5 @@
+import { getCoordinationEtiquetteItems } from "../session/coordination-guidance.js";
+
 export const SUPPORTED_PROMPT_TARGETS = Object.freeze([
   "claude",
   "cursor",
@@ -34,11 +36,7 @@ const TARGET_GUIDANCE = Object.freeze({
   ],
 });
 
-const SESSION_COORDINATION_GUIDANCE = Object.freeze([
-  "Multi-agent coordination: use `sl session` commands to communicate with other agents.",
-  "Always update the session chat room with your current activity so joining agents have context.",
-  "Never break your autonomous loop on unexpected file changes; ask in the session first.",
-]);
+const SESSION_COORDINATION_GUIDANCE = Object.freeze(getCoordinationEtiquetteItems());
 
 function normalizeTarget(target) {
   const normalized = String(target || "generic").trim().toLowerCase();
@@ -61,14 +59,6 @@ function buildAgentHeader(target) {
   return headers[target] || headers.generic;
 }
 
-function shouldAppendSessionGuidance(specMarkdown) {
-  const normalized = String(specMarkdown || "").toLowerCase();
-  if (!normalized) {
-    return false;
-  }
-  return normalized.includes("coordination protocol") || normalized.includes("session");
-}
-
 export function resolvePromptTarget(target) {
   return normalizeTarget(target);
 }
@@ -96,9 +86,7 @@ export function generateExecutionPrompt({
   }
 
   const operatingRules = [...guidance];
-  if (shouldAppendSessionGuidance(specText)) {
-    operatingRules.push(...SESSION_COORDINATION_GUIDANCE);
-  }
+  operatingRules.push(...SESSION_COORDINATION_GUIDANCE);
   const guidanceMarkdown = operatingRules.map((item, index) => `${index + 1}. ${item}`).join("\n");
 
   const hasAidenId = specText.toLowerCase().includes("aidenid");