sentinelayer-cli 0.24.0 → 0.25.1

package/package.json

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

package/src/audit/agents/architecture.js

@@ -1,3 +1,5 @@
+import { isAuditSourceFile } from "./path-classification.js";
+
 function normalizeString(value) {
   return String(value || "").trim();
 }
@@ -21,6 +23,7 @@ function summarizeSeverity(findings = []) {
 function buildHotspots(ingest = {}) {
   const indexed = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
   return indexed
+    .filter((file) => isAuditSourceFile(file))
     .filter((file) => Number(file.loc || 0) >= 300)
     .sort((left, right) => Number(right.loc || 0) - Number(left.loc || 0))
     .slice(0, 20)
@@ -50,7 +53,7 @@ function deriveArchitectureFindings({ findings = [], hotspots = [] } = {}) {
       continue;
     }
     derived.push({
-      severity: hotspot.risk === "high" ? "P1" : "P2",
+      severity: "P2",
       file: hotspot.path,
       line: 1,
       message: `Large architectural hotspot detected (${hotspot.loc} LOC).`,

package/src/audit/agents/documentation.js

@@ -1,3 +1,5 @@
+import { isAuditSourceFile } from "./path-classification.js";
+
 function normalizeString(value) {
   return String(value || "").trim();
 }
@@ -26,9 +28,7 @@ function buildDocumentationInventory(ingest = {}) {
     language: file.language,
   }));
   const docFiles = normalized.filter((file) => /(^|\/)(docs?|guides?|adr|readme)/i.test(file.path));
-  const codeFiles = normalized.filter(
-    (file) => file.loc > 0 && !/(^|\/)(docs?|guides?|adr|readme)/i.test(file.path)
-  );
+  const codeFiles = normalized.filter((file) => file.loc > 0 && isAuditSourceFile(file));
   const docDensity = codeFiles.length > 0 ? docFiles.length / codeFiles.length : 0;
   const undocumentedHotspots = codeFiles
     .filter((file) => file.loc >= 320)
@@ -42,7 +42,7 @@ function buildDocumentationInventory(ingest = {}) {
       path: file.path,
       loc: file.loc,
       language: file.language,
-      severity: file.loc >= 800 ? "P1" : "P2",
+      severity: "P2",
     }));
 
   return {

package/src/audit/agents/path-classification.js

@@ -0,0 +1,120 @@
+const SOURCE_EXTENSIONS = new Set([
+  ".c",
+  ".cc",
+  ".cpp",
+  ".cs",
+  ".css",
+  ".go",
+  ".graphql",
+  ".h",
+  ".hpp",
+  ".java",
+  ".js",
+  ".jsx",
+  ".kt",
+  ".mjs",
+  ".php",
+  ".py",
+  ".rb",
+  ".rs",
+  ".scss",
+  ".sql",
+  ".svelte",
+  ".swift",
+  ".tf",
+  ".ts",
+  ".tsx",
+  ".vue",
+]);
+
+const SOURCE_LANGUAGES = new Set([
+  "c",
+  "c++",
+  "c#",
+  "css",
+  "dockerfile",
+  "go",
+  "graphql",
+  "java",
+  "javascript",
+  "jsx",
+  "kotlin",
+  "php",
+  "python",
+  "ruby",
+  "rust",
+  "scss",
+  "sql",
+  "svelte",
+  "swift",
+  "terraform",
+  "typescript",
+  "tsx",
+  "vue",
+]);
+
+const LOCKFILE_NAMES = new Set([
+  "cargo.lock",
+  "composer.lock",
+  "go.sum",
+  "package-lock.json",
+  "pipfile.lock",
+  "pnpm-lock.yaml",
+  "poetry.lock",
+  "yarn.lock",
+]);
+
+function normalizePath(value) {
+  return String(value || "").replace(/\\/g, "/").replace(/^\.\/+/, "").toLowerCase();
+}
+
+function basename(filePath) {
+  const normalized = normalizePath(filePath);
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+
+function extension(filePath) {
+  const name = basename(filePath);
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot) : "";
+}
+
+export function isAuditTestPath(filePath) {
+  const normalized = normalizePath(filePath);
+  return /(^|\/)(__tests__|tests?|specs?)(\/|$)|\.(test|spec)\.[^.\/]+$/i.test(normalized);
+}
+
+export function isAuditSupportPath(filePath) {
+  const normalized = normalizePath(filePath);
+  if (!normalized) {
+    return true;
+  }
+  if (LOCKFILE_NAMES.has(basename(normalized))) {
+    return true;
+  }
+  if (/(^|\/)(node_modules|vendor|fixtures?|__fixtures__|mocks?|__mocks__|snapshots?|__snapshots__)(\/|$)/i.test(normalized)) {
+    return true;
+  }
+  if (/(^|\/)(generated|__generated__|auto-generated|coverage|dist|build|out|\.next|\.nuxt|\.turbo|\.cache)(\/|$)/i.test(normalized)) {
+    return true;
+  }
+  if (/^(docs?|guides?|adr|tasks?|\.github|\.vscode|\.husky|public)(\/|$)/i.test(normalized)) {
+    return true;
+  }
+  if (/(\.min|\.bundle|generated)\.[^.\/]+$/i.test(normalized)) {
+    return true;
+  }
+  return false;
+}
+
+export function isAuditSourceFile(file = {}) {
+  const filePath = typeof file === "string" ? file : file.path;
+  const normalized = normalizePath(filePath);
+  if (!normalized || isAuditTestPath(normalized) || isAuditSupportPath(normalized)) {
+    return false;
+  }
+  if (SOURCE_EXTENSIONS.has(extension(normalized))) {
+    return true;
+  }
+  return SOURCE_LANGUAGES.has(String(file.language || "").trim().toLowerCase());
+}

package/src/audit/agents/performance.js

@@ -1,3 +1,5 @@
+import { isAuditSourceFile } from "./path-classification.js";
+
 function normalizeString(value) {
   return String(value || "").trim();
 }
@@ -21,6 +23,7 @@ function summarizeSeverity(findings = []) {
 function buildRuntimeHotspots(ingest = {}) {
   const indexed = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
   return indexed
+    .filter((file) => isAuditSourceFile(file))
     .filter((file) => Number(file.loc || 0) >= 280)
     .sort((left, right) => Number(right.loc || 0) - Number(left.loc || 0))
     .slice(0, 20)
@@ -28,7 +31,7 @@ function buildRuntimeHotspots(ingest = {}) {
       path: toPosixPath(file.path),
       loc: Number(file.loc || 0),
       language: file.language,
-      severity: Number(file.loc || 0) >= 900 ? "P1" : "P2",
+      severity: "P2",
     }));
 }
 

package/src/audit/agents/testing.js

@@ -1,3 +1,5 @@
+import { isAuditSourceFile, isAuditTestPath } from "./path-classification.js";
+
 function normalizeString(value) {
   return String(value || "").trim();
 }
@@ -18,10 +20,6 @@ function summarizeSeverity(findings = []) {
   return summary;
 }
 
-function isTestPath(filePath) {
-  return /(^|\/)(__tests__|tests?|spec)(\/|$)|\.(test|spec)\.[^.]+$/i.test(filePath);
-}
-
 function buildCoverageInventory(ingest = {}) {
   const indexedFiles = Array.isArray(ingest.indexedFiles?.files) ? ingest.indexedFiles.files : [];
   const normalized = indexedFiles.map((file) => ({
@@ -30,8 +28,8 @@ function buildCoverageInventory(ingest = {}) {
     loc: Number(file.loc || 0),
   }));
 
-  const testFiles = normalized.filter((file) => isTestPath(file.path));
-  const nonTestCodeFiles = normalized.filter((file) => !isTestPath(file.path) && file.loc > 0);
+  const testFiles = normalized.filter((file) => isAuditTestPath(file.path));
+  const nonTestCodeFiles = normalized.filter((file) => isAuditSourceFile(file) && file.loc > 0);
   const ratio = nonTestCodeFiles.length > 0 ? testFiles.length / nonTestCodeFiles.length : 0;
   const likelyGaps = nonTestCodeFiles
     .filter((file) => file.loc >= 260)
@@ -45,7 +43,7 @@ function buildCoverageInventory(ingest = {}) {
       path: file.path,
       loc: file.loc,
       language: file.language,
-      severity: file.loc >= 550 ? "P1" : "P2",
+      severity: "P2",
     }));
 
   return {

package/src/commands/action-options.js

@@ -0,0 +1,27 @@
+export function resolveActionOptions(options = {}, command = null) {
+  const localOptions = options && typeof options.opts === "function" ? options.opts() : { ...options };
+  const parent = command?.parent;
+  if (!parent || typeof parent.opts !== "function") {
+    return localOptions;
+  }
+
+  const parentOptions = parent.opts();
+  const merged = {
+    ...parentOptions,
+    ...localOptions,
+  };
+
+  for (const [key, value] of Object.entries(parentOptions)) {
+    const parentSource =
+      typeof parent.getOptionValueSource === "function" ? parent.getOptionValueSource(key) : null;
+    const localSource =
+      typeof command?.getOptionValueSource === "function" ? command.getOptionValueSource(key) : null;
+    const parentWasProvided = parentSource && parentSource !== "default";
+    const localIsOnlyDefault = localSource === "default" || localOptions[key] === undefined;
+    if (parentWasProvided && localIsOnlyDefault) {
+      merged[key] = value;
+    }
+  }
+
+  return merged;
+}

package/src/commands/audit.js

@@ -10,6 +10,7 @@ import { loadAuditRegistry, selectAuditAgents } from "../audit/registry.js";
 import { resolveOutputRoot } from "../config/service.js";
 import { createAgentEvent } from "../events/schema.js";
 import { createAuditSessionReporter, resolveAuditSessionId } from "../session/audit-reporter.js";
+import { resolveActionOptions } from "./action-options.js";
 import { buildLegacyArgs } from "./legacy-args.js";
 
 function shouldEmitJson(options, command) {
@@ -213,16 +214,17 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--output-dir <path>", "Optional artifact output root override")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const outputRoot = await resolveOutputRoot({
         cwd: targetPath,
-        outputDirOverride: options.outputDir,
+        outputDirOverride: actionOptions.outputDir,
         env: process.env,
       });
       const runDirectory = await resolveAuditRunDirectory({
         outputRoot,
-        runId: options.runId,
+        runId: actionOptions.runId,
       });
       const { report } = await loadAuditRunReport(runDirectory);
       const ddPackage = await writeDdPackage({
@@ -264,11 +266,12 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--refresh", "Refresh CODEBASE_INGEST before replay")
     .option("--json", "Emit machine-readable output")
     .action(async (runId, options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const initialTargetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const initialTargetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const outputRoot = await resolveOutputRoot({
         cwd: initialTargetPath,
-        outputDirOverride: options.outputDir,
+        outputDirOverride: actionOptions.outputDir,
         env: process.env,
       });
       const baseRunDirectory = await resolveAuditRunDirectory({
@@ -276,12 +279,12 @@ export function registerAuditCommand(program, invokeLegacy) {
         runId,
       });
       const { report: baseReport } = await loadAuditRunReport(baseRunDirectory);
-      const targetPath = options.path
-        ? path.resolve(process.cwd(), String(options.path || "."))
+      const targetPath = actionOptions.path
+        ? path.resolve(process.cwd(), String(actionOptions.path || "."))
         : path.resolve(String(baseReport.targetPath || "."));
 
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, (baseReport.selectedAgents || []).join(","));
       if (selected.selected.length === 0) {
@@ -292,9 +295,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: Number(baseReport.maxParallel || 1),
-        outputDir: options.outputDir,
+        outputDir: actionOptions.outputDir,
         dryRun: Boolean(baseReport.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        refreshIngest: Boolean(actionOptions.refresh),
         isolation: baseReport.isolation || "strict",
         seedFromDeterministic: baseReport.seedFromDeterministic !== false,
       });
@@ -341,11 +344,12 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--output-dir <path>", "Optional artifact output root override")
     .option("--json", "Emit machine-readable output")
     .action(async (baseRunId, candidateRunId, options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const outputRoot = await resolveOutputRoot({
         cwd: targetPath,
-        outputDirOverride: options.outputDir,
+        outputDirOverride: actionOptions.outputDir,
         env: process.env,
       });
       const baseRunDirectory = await resolveAuditRunDirectory({
@@ -388,9 +392,10 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--registry-file <path>", "Optional custom audit registry file")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const payload = {
         command: "audit registry",
@@ -422,10 +427,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--dry-run", "Skip deterministic baseline and run security planning only")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, "security");
       if (selected.selected.length !== 1) {
@@ -436,9 +442,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: 1,
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        outputDir: actionOptions.outputDir,
+        dryRun: Boolean(actionOptions.dryRun),
+        refreshIngest: Boolean(actionOptions.refresh),
       });
       const securityAgent = result.agentResults.find((agent) => agent.agentId === "security") || null;
 
@@ -486,10 +492,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--dry-run", "Skip deterministic baseline and run architecture planning only")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, "architecture");
       if (selected.selected.length !== 1) {
@@ -500,9 +507,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: 1,
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        outputDir: actionOptions.outputDir,
+        dryRun: Boolean(actionOptions.dryRun),
+        refreshIngest: Boolean(actionOptions.refresh),
       });
       const architectureAgent =
         result.agentResults.find((agent) => agent.agentId === "architecture") || null;
@@ -551,10 +558,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--dry-run", "Skip deterministic baseline and run testing planning only")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, "testing");
       if (selected.selected.length !== 1) {
@@ -565,9 +573,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: 1,
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        outputDir: actionOptions.outputDir,
+        dryRun: Boolean(actionOptions.dryRun),
+        refreshIngest: Boolean(actionOptions.refresh),
       });
       const testingAgent = result.agentResults.find((agent) => agent.agentId === "testing") || null;
 
@@ -615,10 +623,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--dry-run", "Skip deterministic baseline and run performance planning only")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, "performance");
       if (selected.selected.length !== 1) {
@@ -629,9 +638,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: 1,
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        outputDir: actionOptions.outputDir,
+        dryRun: Boolean(actionOptions.dryRun),
+        refreshIngest: Boolean(actionOptions.refresh),
       });
       const performanceAgent =
         result.agentResults.find((agent) => agent.agentId === "performance") || null;
@@ -680,10 +689,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--dry-run", "Skip deterministic baseline and run compliance planning only")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, "compliance");
       if (selected.selected.length !== 1) {
@@ -694,9 +704,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: 1,
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        outputDir: actionOptions.outputDir,
+        dryRun: Boolean(actionOptions.dryRun),
+        refreshIngest: Boolean(actionOptions.refresh),
       });
       const complianceAgent =
         result.agentResults.find((agent) => agent.agentId === "compliance") || null;
@@ -745,10 +755,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--dry-run", "Skip deterministic baseline and run documentation planning only")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
       const registry = await loadAuditRegistry({
-        registryFile: options.registryFile,
+        registryFile: actionOptions.registryFile,
       });
       const selected = selectAuditAgents(registry.agents, "documentation");
       if (selected.selected.length !== 1) {
@@ -759,9 +770,9 @@ export function registerAuditCommand(program, invokeLegacy) {
         targetPath,
         agents: selected.selected,
         maxParallel: 1,
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
+        outputDir: actionOptions.outputDir,
+        dryRun: Boolean(actionOptions.dryRun),
+        refreshIngest: Boolean(actionOptions.refresh),
       });
       const documentationAgent =
         result.agentResults.find((agent) => agent.agentId === "documentation") || null;
@@ -808,8 +819,9 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--reuse-omargate <runId>", "Reuse deterministic findings from an OmarGate run id or latest")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
+      const actionOptions = resolveActionOptions(options, command);
       const legacyArgs = buildLegacyArgs(["/audit"], {
-        commandOptions: options,
+        commandOptions: actionOptions,
         command,
       });
       await invokeLegacy(legacyArgs);
@@ -848,9 +860,10 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--output-dir <path>", "Artifact output root override")
     .option("--json", "Emit machine-readable final output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const emitStream = Boolean(options.stream);
-      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const emitStream = Boolean(actionOptions.stream);
+      const targetPath = path.resolve(process.cwd(), String(actionOptions.path || "."));
 
       // Lazy-load modules
       const { julesAuditLoop } = await import("../agents/jules/loop.js");
@@ -861,7 +874,7 @@ export function registerAuditCommand(program, invokeLegacy) {
       const { runDeterministicReviewPipeline } = await import("../review/local-review.js");
       const fsp = await import("node:fs/promises");
 
-      const outputRoot = await resolveOut({ targetPath, outputDir: options.outputDir });
+      const outputRoot = await resolveOut({ targetPath, outputDir: actionOptions.outputDir });
       const artifactDir = path.join(outputRoot, "reports", "jules-" + Date.now());
       await fsp.mkdir(artifactDir, { recursive: true });
 
@@ -876,7 +889,7 @@ export function registerAuditCommand(program, invokeLegacy) {
       try {
         ingest = await generateCodebaseIngest({
           rootPath: targetPath, outputDir: outputRoot,
-          refresh: Boolean(options.refresh),
+          refresh: Boolean(actionOptions.refresh),
         });
       } catch {
         ingest = await collectCodebaseIngest({ rootPath: targetPath });
@@ -887,7 +900,7 @@ export function registerAuditCommand(program, invokeLegacy) {
 
       // ── [2] OMAR BASELINE (blind — Jules won't see until reconciliation) ──
       let omarBaseline = null;
-      if (!options.skipBaseline) {
+      if (!actionOptions.skipBaseline) {
         emitProgress(onEvent, JULES_DEFINITION, "Running Omar 7-layer deterministic baseline...");
         try {
           omarBaseline = await runDeterministicReviewPipeline({
@@ -925,14 +938,14 @@ export function registerAuditCommand(program, invokeLegacy) {
 
       // ── [5] PROVIDER ──────────────────────────────────────────────
       const providerConfig = {};
-      if (options.provider) providerConfig.provider = options.provider;
-      if (options.model) providerConfig.model = options.model;
-      if (options.apiKey) providerConfig.apiKey = options.apiKey;
+      if (actionOptions.provider) providerConfig.provider = actionOptions.provider;
+      if (actionOptions.model) providerConfig.model = actionOptions.model;
+      if (actionOptions.apiKey) providerConfig.apiKey = actionOptions.apiKey;
 
       // ── [6] SYSTEM PROMPT (full production prompt) ─────────────────
       const { buildJulesProductionPrompt } = await import("../agents/jules/config/system-prompt.js");
       const systemPrompt = buildJulesProductionPrompt({
-        mode: options.mode,
+        mode: actionOptions.mode,
         framework: ingest?.frameworks?.[0] || "unknown",
         componentCount: ingest?.indexedFiles?.files?.filter(
           f => /\.(tsx|jsx|vue|svelte)$/.test(f.path || ""),
@@ -952,14 +965,14 @@ export function registerAuditCommand(program, invokeLegacy) {
         blackboard,
         memory: memoryIndex,
         budget: {
-          maxCostUsd: parseFloat(options.maxCost) || 5.0,
+          maxCostUsd: parseFloat(actionOptions.maxCost) || 5.0,
           maxOutputTokens: JULES_DEFINITION.budget.maxOutputTokens,
           maxRuntimeMs: JULES_DEFINITION.budget.maxRuntimeMs,
           maxToolCalls: JULES_DEFINITION.budget.maxToolCalls,
         },
         provider: providerConfig,
-        mode: options.mode,
-        maxTurns: parseInt(options.maxTurns) || 25,
+        mode: actionOptions.mode,
+        maxTurns: parseInt(actionOptions.maxTurns) || 25,
         onEvent,
       });
 
@@ -973,8 +986,8 @@ export function registerAuditCommand(program, invokeLegacy) {
 
       // ── [7.5] RUNTIME AUDIT (if --url provided or URL detected) ────
       let runtimeResult = null;
-      const runtimeUrl = options.url || null;
-      if (runtimeUrl || !options.skipRuntime) {
+      const runtimeUrl = actionOptions.url || null;
+      if (runtimeUrl || !actionOptions.skipRuntime) {
         emitProgress(onEvent, JULES_DEFINITION, "Checking for deployed URL...");
         try {
           const { runtimeAudit: runRT } = await import("../agents/jules/tools/runtime-audit.js");
@@ -1057,7 +1070,7 @@ export function registerAuditCommand(program, invokeLegacy) {
         command: "audit frontend",
         persona: JULES_DEFINITION.persona,
         targetPath,
-        mode: options.mode,
+        mode: actionOptions.mode,
         framework: ingest?.frameworks?.[0] || "unknown",
         findings: allFindings,
         summary: { total: allFindings.length, ...severityCounts, blocking: severityCounts.P0 > 0 || severityCounts.P1 > 0 },
@@ -1109,7 +1122,7 @@ export function registerAuditCommand(program, invokeLegacy) {
         const syncResult = await syncRunToDashboard({
           command: "audit frontend",
           persona: JULES_DEFINITION.persona,
-          mode: options.mode,
+          mode: actionOptions.mode,
           framework: ingest?.frameworks?.[0] || "unknown",
           summary: { total: allFindings.length, ...severityCounts, blocking: severityCounts.P0 > 0 || severityCounts.P1 > 0 },
           usage: report?.usage || {},

package/src/commands/review.js

@@ -25,6 +25,7 @@ import {
   writeReviewComparisonArtifact,
   writeReviewRunContext,
 } from "../review/replay.js";
+import { resolveActionOptions } from "./action-options.js";
 
 function shouldEmitJson(options, command) {
   const local = Boolean(options && options.json);
@@ -236,16 +237,17 @@ function registerVerdictCommand(review, verdict) {
     .option("--actor <id>", "Operator identifier for audit trail", "")
     .option("--json", "Emit machine-readable output")
     .action(async (findingId, options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = resolveTargetPath(".", options);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = resolveTargetPath(".", actionOptions);
       const result = await recordReviewDecision({
         targetPath,
-        runId: options.runId,
-        outputDir: options.outputDir,
+        runId: actionOptions.runId,
+        outputDir: actionOptions.outputDir,
         findingId,
         verdict,
-        note: options.note,
-        actor: options.actor,
+        note: actionOptions.note,
+        actor: actionOptions.actor,
         env: process.env,
       });
 
@@ -374,12 +376,13 @@ export function registerReviewCommand(program) {
     .option("--output-dir <path>", "Optional artifact output root override")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = resolveTargetPath(".", options);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = resolveTargetPath(".", actionOptions);
       const loaded = await loadUnifiedReviewReport({
         targetPath,
-        runId: options.runId,
-        outputDir: options.outputDir,
+        runId: actionOptions.runId,
+        outputDir: actionOptions.outputDir,
         env: process.env,
       });
 
@@ -412,14 +415,15 @@ export function registerReviewCommand(program) {
     .option("--output-file <path>", "Optional custom export output path")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = resolveTargetPath(".", options);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = resolveTargetPath(".", actionOptions);
       const exported = await exportUnifiedReviewReport({
         targetPath,
-        runId: options.runId,
-        outputDir: options.outputDir,
-        format: options.format,
-        outputFile: options.outputFile,
+        runId: actionOptions.runId,
+        outputDir: actionOptions.outputDir,
+        format: actionOptions.format,
+        outputFile: actionOptions.outputFile,
         env: process.env,
       });
 
@@ -453,12 +457,13 @@ export function registerReviewCommand(program) {
     .option("--ai-dry-run", "Force AI dry-run during replay")
     .option("--json", "Emit machine-readable output")
     .action(async (runId, options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const lookupPath = resolveTargetPath(".", options);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const lookupPath = resolveTargetPath(".", actionOptions);
       const source = await loadUnifiedReviewReport({
         targetPath: lookupPath,
         runId,
-        outputDir: options.outputDir,
+        outputDir: actionOptions.outputDir,
         env: process.env,
       });
 
@@ -470,20 +475,20 @@ export function registerReviewCommand(program) {
       }
 
       const invocation = sourceContext?.context?.invocation || {};
-      const replayTargetPath = options.path
-        ? resolveTargetPath(".", options)
+      const replayTargetPath = actionOptions.path
+        ? resolveTargetPath(".", actionOptions)
         : path.resolve(sourceContext?.context?.targetPath || source.report.targetPath || lookupPath);
-      const aiEnabled = options.noAi ? false : Boolean(invocation.aiEnabled);
+      const aiEnabled = actionOptions.noAi ? false : Boolean(invocation.aiEnabled);
 
       const replayOutcome = await executeReviewRun({
         targetPath: replayTargetPath,
         mode: sourceContext?.context?.mode || source.report.mode || "full",
-        outputDir: options.outputDir || invocation.outputDir || "",
-        specFile: options.spec || invocation.specFile || "",
-        refreshIngest: Boolean(options.refresh || invocation.refreshIngest),
+        outputDir: actionOptions.outputDir || invocation.outputDir || "",
+        specFile: actionOptions.spec || invocation.specFile || "",
+        refreshIngest: Boolean(actionOptions.refresh || invocation.refreshIngest),
         aiConfig: {
           enable: aiEnabled,
-          aiDryRun: Boolean(options.aiDryRun || invocation.aiDryRun),
+          aiDryRun: Boolean(actionOptions.aiDryRun || invocation.aiDryRun),
           provider: invocation.provider,
           model: invocation.model,
           sessionId: invocation.sessionId,
@@ -542,18 +547,19 @@ export function registerReviewCommand(program) {
     .option("--output-file <path>", "Optional custom output path for comparison JSON")
     .option("--json", "Emit machine-readable output")
     .action(async (baseRunId, candidateRunId, options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = resolveTargetPath(".", options);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = resolveTargetPath(".", actionOptions);
       const base = await loadUnifiedReviewReport({
         targetPath,
         runId: baseRunId,
-        outputDir: options.outputDir,
+        outputDir: actionOptions.outputDir,
         env: process.env,
       });
       const candidate = await loadUnifiedReviewReport({
         targetPath,
         runId: candidateRunId,
-        outputDir: options.outputDir,
+        outputDir: actionOptions.outputDir,
         env: process.env,
       });
 
@@ -566,8 +572,8 @@ export function registerReviewCommand(program) {
       });
 
       let outputPath = artifact.artifactPath;
-      if (options.outputFile) {
-        outputPath = path.resolve(targetPath, String(options.outputFile));
+      if (actionOptions.outputFile) {
+        outputPath = path.resolve(targetPath, String(actionOptions.outputFile));
         await fsp.mkdir(path.dirname(outputPath), { recursive: true });
         await fsp.writeFile(outputPath, `${JSON.stringify(artifact.payload, null, 2)}\n`, "utf-8");
       }
@@ -611,13 +617,14 @@ export function registerReviewCommand(program) {
     .option("--refresh", "Refresh CODEBASE_INGEST prior to compatibility scan")
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
-      const emitJson = shouldEmitJson(options, command);
-      const targetPath = resolveTargetPath(".", options);
+      const actionOptions = resolveActionOptions(options, command);
+      const emitJson = shouldEmitJson(actionOptions, command);
+      const targetPath = resolveTargetPath(".", actionOptions);
       let ingestRefresh = null;
-      if (options.refresh) {
+      if (actionOptions.refresh) {
         const ingestResolution = await resolveCodebaseIngest({
           rootPath: targetPath,
-          outputDir: options.outputDir,
+          outputDir: actionOptions.outputDir,
           refresh: true,
         });
         ingestRefresh = {
@@ -630,13 +637,13 @@ export function registerReviewCommand(program) {
           contentHash: ingestResolution.fingerprint?.contentHash || "",
         };
       }
-      const mode = resolveModeFromOptions(options, {
-        defaultMode: String(options.mode || "full").trim().toLowerCase() || "full",
+      const mode = resolveModeFromOptions(actionOptions, {
+        defaultMode: String(actionOptions.mode || "full").trim().toLowerCase() || "full",
       });
       const scan = await runLocalReviewScan({
         targetPath,
         mode,
-        specFile: options.spec,
+        specFile: actionOptions.spec,
       });
 
       const report = `# Local Review Scan
@@ -660,7 +667,7 @@ ${formatFindingsMarkdown(scan.findings)}
       const reportPath = await writeReviewReport({
         targetPath: scan.targetPath,
         mode: scan.mode,
-        outputDir: options.outputDir,
+        outputDir: actionOptions.outputDir,
         reportMarkdown: report,
       });
 

package/src/commands/session.js

@@ -62,6 +62,11 @@ import {
   updateSessionTitle,
 } from "../session/store.js";
 import { fetchSessionListeners, formatListenerLine } from "../session/listeners.js";
+import {
+  acceptSessionInvitation,
+  normalizeSessionOnboarding,
+  writeSessionOnboardingBrief,
+} from "../session/invitations.js";
 import { postFirstSentiMessage } from "../session/first-message.js";
 import { createListenerHostWake } from "../session/wake/listen-wake.js";
 import { appendToStream, readStream, tailStream } from "../session/stream.js";
@@ -124,6 +129,13 @@ function normalizeString(value) {
   return String(value || "").trim();
 }
 
+function optionWasSetByCli(command, optionName) {
+  if (!command || typeof command.getOptionValueSource !== "function") {
+    return false;
+  }
+  return command.getOptionValueSource(optionName) === "cli";
+}
+
 const SESSION_SAY_CONFIRM_ATTEMPTS = 3;
 const SESSION_SAY_CONFIRM_DELAY_MS = 250;
 const SESSION_SAY_CONFIRM_PAGE_LIMIT = 200;
@@ -2719,6 +2731,9 @@ export function registerSessionCommand(program) {
       "--agent <id>",
       "Granted agent id to emit an agent_join event as. Behaves like post-agent for human/placeholder ids — those are recorded in the local registry only.",
     )
+    .option("--invite-token <token>", "Invitation token to accept before joining the session")
+    .option("--seat-key <key>", "Reserved session seat key to claim while accepting an invite")
+    .option("--idempotency-key <key>", "Explicit idempotency key for invite acceptance")
     .option("--role <role>", "Agent role: coder, reviewer, tester, observer", "coder")
     .option("--model <model>", "Agent model hint", "cli")
     .option("--path <path>", "Workspace path for the session", ".")
@@ -2729,12 +2744,35 @@ export function registerSessionCommand(program) {
         throw new Error("session id is required.");
       }
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      const explicitAgent = normalizeString(options.agent);
+      const legacyName = normalizeString(options.name);
+      const inviteToken = normalizeString(options.inviteToken);
+      let invitationAccept = null;
+      let invitationAcceptResult = null;
+      if (inviteToken) {
+        invitationAccept = await acceptSessionInvitation(normalizedSessionId, {
+          targetPath,
+          invitationToken: inviteToken,
+          seatKey: options.seatKey,
+          agentId: explicitAgent || legacyName,
+          idempotencyKey: options.idempotencyKey,
+        });
+        invitationAcceptResult =
+          invitationAccept?.result && typeof invitationAccept.result === "object"
+            ? invitationAccept.result
+            : null;
+      }
 
       // PR #483 contract: verify the session exists and the caller has access
       // BEFORE materializing local cache state. Without this we'd silently
       // create a phantom local NDJSON for a session that's archived or owned
       // by another tenant — which is the bug Carter reported when asking for
       // a clean "share an id from web → join in CLI" flow.
+      //
+      // Invitation acceptance is the only exception to the old ordering:
+      // before the invite is accepted the user may legitimately receive 403,
+      // so --invite-token performs the guarded accept mutation first and this
+      // verification proves membership immediately afterward.
       const verification = await verifyRemoteSession(normalizedSessionId, { targetPath });
       if (!verification.ok) {
         if (verification.status === 404 || verification.reason === "not_found") {
@@ -2766,17 +2804,26 @@ export function registerSessionCommand(program) {
         targetPath,
       });
 
-      const explicitAgent = normalizeString(options.agent);
-      const agentSeed = explicitAgent || normalizeString(options.name);
+      const acceptedOnboarding = normalizeSessionOnboarding(
+        invitationAcceptResult?.onboarding,
+        invitationAcceptResult?.claimedSeat,
+      );
+      const acceptedAgentId = normalizeString(acceptedOnboarding?.agentId);
+      const agentSeed = explicitAgent || acceptedAgentId || legacyName;
       const resolvedAgentId = await defaultAgentId(agentSeed, targetPath);
-      const role = normalizeString(options.role) || "coder";
+      const roleWasExplicit = optionWasSetByCli(command, "role");
+      const role =
+        normalizeString(roleWasExplicit ? options.role : acceptedOnboarding?.role || options.role) ||
+        "coder";
       const model = normalizeString(options.model) || "cli";
+      const hasConcreteAgentIdentity = Boolean(explicitAgent || acceptedAgentId);
 
       // `registerAgent` already writes the canonical `agent_join` event to the
       // local NDJSON and best-effort relays it to /events via appendToStream
       // → syncSessionEventToApi. That gives us the exact `post-agent` parity
-      // the spec calls for when `--agent <granted>` is provided. We don't
-      // double-emit; we just record whether the explicit agent path was used
+      // the spec calls for when `--agent <granted>` or an accepted reserved
+      // seat provides a concrete agent id. We don't double-emit; we record
+      // whether a durable agent identity path was used
       // so the JSON output can advertise it to callers (and tests).
       const joined = await registerAgent(normalizedSessionId, {
         targetPath,
@@ -2784,15 +2831,21 @@ export function registerSessionCommand(program) {
         model,
         role,
         trackProcessExit: false,
-        awaitRemoteSync: Boolean(explicitAgent),
+        awaitRemoteSync: hasConcreteAgentIdentity,
       });
       const agentJoinRelayed =
         joined.emittedJoinEvent !== false &&
-        Boolean(explicitAgent) &&
+        hasConcreteAgentIdentity &&
         Boolean(resolvedAgentId) &&
         resolvedAgentId !== "cli-user" &&
         resolvedAgentId !== "unknown" &&
         !resolvedAgentId.startsWith("human-");
+      const onboardingBrief = await writeSessionOnboardingBrief(normalizedSessionId, {
+        targetPath,
+        onboarding: acceptedOnboarding,
+        claimedSeat: invitationAcceptResult?.claimedSeat || null,
+        agentId: joined.agentId,
+      });
 
       const eventCount = Number(remoteSession.eventCount ?? remoteSession.events ?? 0);
       const agents = Array.isArray(remoteSession.agents) ? remoteSession.agents : [];
@@ -2824,6 +2877,21 @@ export function registerSessionCommand(program) {
         agentCount: Number.isFinite(agentCount) ? agentCount : 0,
         lastActivityAt: lastActivityIso || null,
         agentJoinRelayed,
+        invitationAccepted: Boolean(invitationAcceptResult?.ok || invitationAccept),
+        invitationAccept: invitationAccept
+          ? {
+              idempotencyKey: invitationAccept.idempotencyKey,
+              claimedSeat: invitationAcceptResult?.claimedSeat || null,
+              onboarding: acceptedOnboarding,
+              capacity: invitationAcceptResult?.capacity || null,
+            }
+          : null,
+        onboardingGuide: onboardingBrief
+          ? {
+              markdownPath: onboardingBrief.markdownPath,
+              jsonPath: onboardingBrief.jsonPath,
+            }
+          : null,
       };
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -2836,7 +2904,17 @@ export function registerSessionCommand(program) {
           `Joined session ${titleLabel} (${normalizedSessionId}) — ${payload.eventCount} events, ${payload.agentCount} agents, last activity ${ageLabel}`,
         ),
       );
+      if (payload.invitationAccepted) {
+        const seat = payload.invitationAccept?.claimedSeat || {};
+        const seatLabel = normalizeString(seat.seatKey)
+          ? `; claimed ${normalizeString(seat.seatType) || "reserved"} seat ${seat.seatKey}`
+          : "";
+        console.log(pc.green(`Invitation accepted${seatLabel}`));
+      }
       console.log(pc.gray(`agent=${joined.agentId} role=${joined.role} model=${joined.model}`));
+      if (payload.onboardingGuide?.markdownPath) {
+        console.log(pc.gray(`onboarding=${payload.onboardingGuide.markdownPath}`));
+      }
     });
 
   session

package/src/coord/events-log.js

@@ -19,7 +19,7 @@ import {
   resolveSentinelDir,
 } from "./paths.js";
 
-const EVENTS_LOCK_TIMEOUT_MS = 5000;
+const EVENTS_LOCK_TIMEOUT_MS = 15_000;
 const EVENTS_LOCK_STALE_MS = 30_000;
 const EVENTS_LOCK_POLL_MS = 25;
 

package/src/legacy-cli.js

@@ -2294,6 +2294,9 @@ ${renderCoordinationNumberedList()}
 - 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"\`
+
+## Reserved Seat Onboarding
+- If \`sl session join\` returns \`onboardingGuide.markdownPath\`, read that file before posting; it contains your reserved-seat SOUL instructions, role, and first actions.
 `;
 }
 

package/src/session/invitations.js

@@ -0,0 +1,241 @@
+import { createHmac, randomUUID } from "node:crypto";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { requestJsonMutation } from "../auth/http.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
+import { renderCoordinationBulletList } from "./coordination-guidance.js";
+import { resolveSessionPaths } from "./paths.js";
+
+export const SESSION_INVITATION_ACCEPT_ROUTE_ID =
+  "POST /api/v1/sessions/{session_id}/invitations/accept";
+export const SESSION_MUTATION_ORIGIN = "https://sentinelayer.com";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function safeFileToken(value, fallback = "onboarding") {
+  const normalized = normalizeString(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return (normalized || fallback).slice(0, 80);
+}
+
+export function canonicalSessionRef(value) {
+  const raw = normalizeString(value);
+  if (!raw) return "unavailable";
+  return raw.toLowerCase();
+}
+
+export function createSessionMutationCsrfToken({
+  bearerToken,
+  sessionId,
+  routeId,
+  idempotencyKey,
+} = {}) {
+  const secret = normalizeString(bearerToken);
+  if (!secret) return "";
+  const message = [
+    "session-mutation-csrf:v1",
+    canonicalSessionRef(sessionId),
+    normalizeString(routeId),
+    normalizeString(idempotencyKey),
+  ].join("\0");
+  return createHmac("sha256", secret).update(message, "utf-8").digest("hex");
+}
+
+export function createSessionMutationHeaders({
+  bearerToken,
+  sessionId,
+  routeId,
+  idempotencyKey,
+  origin = SESSION_MUTATION_ORIGIN,
+} = {}) {
+  const token = normalizeString(bearerToken);
+  const normalizedOrigin = normalizeString(origin) || SESSION_MUTATION_ORIGIN;
+  return {
+    Authorization: `Bearer ${token}`,
+    Origin: normalizedOrigin,
+    "Sec-Fetch-Site": "same-site",
+    "X-Sentinelayer-Session-Mutation": "session-mutation",
+    "X-CSRF-Token": createSessionMutationCsrfToken({
+      bearerToken: token,
+      sessionId,
+      routeId,
+      idempotencyKey,
+    }),
+  };
+}
+
+export function createSessionMutationIdempotencyKey(operationName = "invitation-accept") {
+  const operation = normalizeString(operationName)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 32) || "session-mutation";
+  return `sl-cli-${operation}-${randomUUID()}`;
+}
+
+export async function acceptSessionInvitation(
+  sessionId,
+  {
+    invitationToken,
+    seatKey = "",
+    agentId = "",
+    targetPath = process.cwd(),
+    idempotencyKey = "",
+    origin = SESSION_MUTATION_ORIGIN,
+    resolveAuthSession = resolveActiveAuthSession,
+    requestMutation = requestJsonMutation,
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedInvitationToken = normalizeString(invitationToken);
+  if (!normalizedSessionId) {
+    throw new Error("session id is required.");
+  }
+  if (!normalizedInvitationToken) {
+    throw new Error("invite token is required.");
+  }
+
+  const auth = await resolveAuthSession({
+    cwd: targetPath,
+    env: process.env,
+    autoRotate: false,
+  });
+  if (!auth?.token || !auth?.apiUrl) {
+    throw new Error("Not authenticated. Run `sl auth login` first.");
+  }
+
+  const resolvedIdempotencyKey =
+    normalizeString(idempotencyKey) || createSessionMutationIdempotencyKey("session-invite-accept");
+  const apiUrl = normalizeString(auth.apiUrl).replace(/\/+$/, "");
+  const body = {
+    token: normalizedInvitationToken,
+  };
+  const normalizedSeatKey = normalizeString(seatKey);
+  const normalizedAgentId = normalizeString(agentId);
+  if (normalizedSeatKey) body.seatKey = normalizedSeatKey;
+  if (normalizedAgentId) body.agentId = normalizedAgentId;
+
+  const result = await requestMutation(
+    `${apiUrl}/api/v1/sessions/${encodeURIComponent(normalizedSessionId)}/invitations/accept`,
+    {
+      method: "POST",
+      operationName: "session.invitation_accept",
+      idempotencyKey: resolvedIdempotencyKey,
+      headers: createSessionMutationHeaders({
+        bearerToken: auth.token,
+        sessionId: normalizedSessionId,
+        routeId: SESSION_INVITATION_ACCEPT_ROUTE_ID,
+        idempotencyKey: resolvedIdempotencyKey,
+        origin,
+      }),
+      body,
+    },
+  );
+
+  return {
+    idempotencyKey: resolvedIdempotencyKey,
+    result,
+  };
+}
+
+export function normalizeSessionOnboarding(onboarding = {}, claimedSeat = null) {
+  const onboardingSource =
+    onboarding && typeof onboarding === "object" && !Array.isArray(onboarding) ? onboarding : {};
+  const seatSource =
+    claimedSeat && typeof claimedSeat === "object" && !Array.isArray(claimedSeat) ? claimedSeat : {};
+  const normalized = {
+    seatKey: normalizeString(onboardingSource.seatKey) || normalizeString(seatSource.seatKey) || null,
+    agentId:
+      normalizeString(onboardingSource.agentId) ||
+      normalizeString(seatSource.claimedAgentId) ||
+      normalizeString(seatSource.agentId) ||
+      null,
+    displayName:
+      normalizeString(onboardingSource.displayName) || normalizeString(seatSource.displayName) || null,
+    role: normalizeString(onboardingSource.role) || normalizeString(seatSource.role) || null,
+    instructions:
+      normalizeString(onboardingSource.instructions) || normalizeString(seatSource.instructions) || null,
+  };
+  return Object.values(normalized).some(Boolean) ? normalized : null;
+}
+
+function renderOnboardingMarkdown({ sessionId, onboarding, claimedSeat, agentId }) {
+  const lines = [
+    "# Senti Session Onboarding",
+    "",
+    `Session: ${sessionId}`,
+    `Agent: ${normalizeString(onboarding.agentId) || normalizeString(agentId) || "unknown"}`,
+  ];
+  if (onboarding.displayName) lines.push(`Display name: ${onboarding.displayName}`);
+  if (onboarding.role) lines.push(`Role: ${onboarding.role}`);
+  if (onboarding.seatKey) lines.push(`Seat key: ${onboarding.seatKey}`);
+  if (claimedSeat?.seatType) lines.push(`Seat type: ${normalizeString(claimedSeat.seatType)}`);
+  lines.push("", "## SOUL Instructions", "");
+  lines.push(onboarding.instructions || "No seat-specific instructions were provided.");
+  lines.push("", "## Session Etiquette", "", renderCoordinationBulletList());
+  lines.push(
+    "",
+    "## First Actions",
+    "",
+    `- Read recent room context: \`sl session read ${sessionId} --remote --tail 50 --json\``,
+    `- Start a quiet listener: \`sl session listen --session ${sessionId} --agent <your-name> --interval 60 --active-interval 5 --emit ndjson --no-presence\``,
+    `- Post a short plan before editing: \`sl session say ${sessionId} \"plan: <scope>; files: <paths>\"\``,
+    "- Review `AGENTS.md` / `CLAUDE.md`, then keep `tasks/todo.md` current for work status.",
+    "- Add any Carter correction pattern to `tasks/lessons.md` before continuing the next slice.",
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+export async function writeSessionOnboardingBrief(
+  sessionId,
+  {
+    onboarding,
+    claimedSeat = null,
+    agentId = "",
+    targetPath = process.cwd(),
+  } = {},
+) {
+  const normalizedSessionId = normalizeString(sessionId);
+  const normalizedOnboarding = normalizeSessionOnboarding(onboarding, claimedSeat);
+  if (!normalizedSessionId || !normalizedOnboarding) {
+    return null;
+  }
+  const paths = resolveSessionPaths(normalizedSessionId, { targetPath });
+  const owner = safeFileToken(normalizedOnboarding.agentId || agentId || normalizedOnboarding.seatKey);
+  const dir = path.join(paths.sentiDir, "onboarding");
+  const jsonPath = path.join(dir, `${owner}.json`);
+  const markdownPath = path.join(dir, `${owner}.md`);
+  const payload = {
+    schemaVersion: "1.0.0",
+    sessionId: normalizedSessionId,
+    agentId: normalizeString(agentId) || normalizedOnboarding.agentId || null,
+    onboarding: normalizedOnboarding,
+    claimedSeat: claimedSeat && typeof claimedSeat === "object" ? claimedSeat : null,
+    writtenAt: new Date().toISOString(),
+  };
+  await fsp.mkdir(dir, { recursive: true });
+  await Promise.all([
+    fsp.writeFile(jsonPath, `${JSON.stringify(payload, null, 2)}\n`, "utf-8"),
+    fsp.writeFile(
+      markdownPath,
+      renderOnboardingMarkdown({
+        sessionId: normalizedSessionId,
+        onboarding: normalizedOnboarding,
+        claimedSeat,
+        agentId,
+      }),
+      "utf-8",
+    ),
+  ]);
+  return {
+    jsonPath,
+    markdownPath,
+    onboarding: normalizedOnboarding,
+  };
+}

package/src/session/stream.js

@@ -15,6 +15,10 @@ const DEFAULT_LOCK_POLL_MS = 25;
 const DEFAULT_MAX_STREAM_EVENTS = 10_000;
 const DEFAULT_REMOTE_REFRESH_TTL_SECONDS = 24 * 60 * 60;
 const REMOTE_REFRESH_TIMEOUT_MS = 2_500;
+const METADATA_WRITE_RETRY_ATTEMPTS = 5;
+const METADATA_WRITE_RETRY_DELAY_MS = 50;
+
+let metadataWriteCounter = 0;
 
 function normalizeString(value) {
   return String(value || "").trim();
@@ -68,11 +72,36 @@ async function readSessionMetadata(paths) {
   }
 }
 
+function isRetryableMetadataWriteError(error) {
+  const code = error && typeof error === "object" ? error.code : "";
+  return code === "EPERM" || code === "EACCES" || code === "EBUSY";
+}
+
+async function replaceMetadataFile(tmpPath, metadataPath) {
+  for (let attempt = 1; attempt <= METADATA_WRITE_RETRY_ATTEMPTS; attempt += 1) {
+    try {
+      await fsp.rename(tmpPath, metadataPath);
+      return;
+    } catch (error) {
+      if (!isRetryableMetadataWriteError(error) || attempt >= METADATA_WRITE_RETRY_ATTEMPTS) {
+        throw error;
+      }
+      await sleep(METADATA_WRITE_RETRY_DELAY_MS * attempt);
+    }
+  }
+}
+
 async function writeSessionMetadata(paths, metadata = {}) {
   await fsp.mkdir(paths.sessionDir, { recursive: true });
-  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.tmp`;
+  metadataWriteCounter = (metadataWriteCounter + 1) % Number.MAX_SAFE_INTEGER;
+  const tmpPath = `${paths.metadataPath}.${process.pid}.${Date.now()}.${metadataWriteCounter}.tmp`;
   await fsp.writeFile(tmpPath, `${JSON.stringify(metadata, null, 2)}\n`, "utf-8");
-  await fsp.rename(tmpPath, paths.metadataPath);
+  try {
+    await replaceMetadataFile(tmpPath, paths.metadataPath);
+  } catch (error) {
+    await fsp.rm(tmpPath, { force: true }).catch(() => {});
+    throw error;
+  }
 }
 
 function remoteStatusAllowsLocalRefresh(remoteSession = {}) {