sentinelayer-cli 0.21.0 → 0.23.0

package/README.md

@@ -101,6 +101,28 @@ Inputs for non-interactive mode:
 
 ## Multi-Agent Session Workflow
 
+Create a managed session (the golden path — one command):
+
+```bash
+sl session start --title "my room" --force-new
+```
+
+`session start` resumes this workspace's most recent active session when it was
+active within the last hour (`--force-new` always mints a fresh one) and spawns
+the **detached Senti daemon** that manages the room — agent greetings, mention
+routing, recaps, durable checkpoints — surviving your terminal. `--no-daemon`
+opts out; `sl session daemon <id>` runs the manager in the foreground. One
+daemon per session is enforced via `senti-daemon.json` in the session directory
+(logs in `senti-daemon.log` next to it), and the daemon exits on its own when
+the session expires.
+
+Then point your agents at it:
+
+```bash
+sl session join <session-id> --agent <agent-name>
+sl session say <session-id> "status: starting on auth middleware" --agent <agent-name>
+```
+
 Sentinelayer includes a deterministic session coordination surface for multi-agent coding loops:
 
 - session event stream and replay (`start`, `join`, `say`, `read`, `status`, `leave`, `list`, `kill`)

package/package.json

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

package/src/audit/orchestrator.js

@@ -753,6 +753,23 @@ export async function runAuditOrchestrator({
     });
     const agentPath = path.join(agentsDirectory, `${agent.id}.json`);
     await fsp.writeFile(agentPath, `${JSON.stringify(result, null, 2)}\n`, "utf-8");
+    emitAuditLifecycleEvent(
+      onEvent,
+      runId,
+      "agent_complete",
+      {
+        phase: "dispatch",
+        agentId: agent.id,
+        persona: agent.persona,
+        domain: agent.domain,
+        status: agentStatus,
+        findingCount: findings.length,
+        summary,
+        confidence,
+        durationMs: result.durationMs,
+      },
+      `${agent.id} persona complete: ${findings.length} finding(s).`
+    );
     return {
       ...result,
       artifactPath: agentPath,

package/src/commands/audit.js

@@ -9,6 +9,7 @@ import { writeAuditComparisonArtifact } from "../audit/replay.js";
 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 { buildLegacyArgs } from "./legacy-args.js";
 
 function shouldEmitJson(options, command) {
@@ -89,6 +90,11 @@ export function registerAuditCommand(program, invokeLegacy) {
     .option("--no-seed-from-deterministic", "Run personas without deterministic baseline or specialist seed findings")
     .option("--reuse-omargate <runId>", "Reuse deterministic findings from an OmarGate run id or latest")
     .option("--stream", "Emit NDJSON agent events to stdout")
+    .option(
+      "--session <id>",
+      "Senti session id to relay audit progress into (defaults to the workspace's most recent active session)"
+    )
+    .option("--no-session", "Disable senti session progress relay")
     .option("--json", "Emit machine-readable output")
     .action(async (targetPathArg, options, command) => {
       const emitJson = shouldEmitJson(options, command);
@@ -105,18 +111,49 @@ export function registerAuditCommand(program, invokeLegacy) {
         throw new Error("No agents selected for audit run.");
       }
 
-      const result = await runAuditOrchestrator({
+      const auditSessionId = await resolveAuditSessionId({
+        targetPath,
+        explicitSessionId: typeof options.session === "string" ? options.session : "",
+        disabled: options.session === false,
+      });
+      const sessionReporter = createAuditSessionReporter({
+        sessionId: auditSessionId,
         targetPath,
-        agents: selected.selected,
-        maxParallel: parseMaxParallel(options.maxParallel),
-        outputDir: options.outputDir,
-        dryRun: Boolean(options.dryRun),
-        refreshIngest: Boolean(options.refresh),
-        isolation: parseIsolationMode(options.isolation),
-        seedFromDeterministic: options.seedFromDeterministic !== false,
-        reuseOmarGate: options.reuseOmargate,
-        onEvent: buildAuditOrchestratorEventHandler(emitStream),
       });
+      const streamHandler = buildAuditOrchestratorEventHandler(emitStream);
+      const onEvent =
+        streamHandler || sessionReporter
+          ? (evt) => {
+              if (streamHandler) {
+                streamHandler(evt);
+              }
+              if (sessionReporter) {
+                sessionReporter.handleEvent(evt);
+              }
+            }
+          : null;
+
+      let result;
+      try {
+        result = await runAuditOrchestrator({
+          targetPath,
+          agents: selected.selected,
+          maxParallel: parseMaxParallel(options.maxParallel),
+          outputDir: options.outputDir,
+          dryRun: Boolean(options.dryRun),
+          refreshIngest: Boolean(options.refresh),
+          isolation: parseIsolationMode(options.isolation),
+          seedFromDeterministic: options.seedFromDeterministic !== false,
+          reuseOmarGate: options.reuseOmargate,
+          onEvent,
+        });
+      } catch (error) {
+        if (sessionReporter) {
+          await sessionReporter.failed(error);
+        }
+        throw error;
+      }
+      const sessionRelay = sessionReporter ? await sessionReporter.completed(result) : null;
 
       const payload = {
         command: "audit",
@@ -144,12 +181,23 @@ export function registerAuditCommand(program, invokeLegacy) {
         ddPackageFindingsPath: result.ddPackage?.findingsIndexPath || "",
         ddPackageSummaryPath: result.ddPackage?.executiveSummaryPath || "",
         ingestRefresh: result.ingest?.refresh || null,
+        sessionId: auditSessionId || "",
+        sessionRelay: sessionRelay || null,
       };
 
       if (emitJson) {
         console.log(JSON.stringify(payload, null, 2));
       } else if (!emitStream) {
         printAuditSummary(result);
+        if (auditSessionId) {
+          console.log(
+            pc.gray(
+              `Senti session: ${auditSessionId} (posted ${sessionRelay?.posted ?? 0} update(s)${
+                sessionRelay?.failed ? `, ${sessionRelay.failed} failed` : ""
+              })`
+            )
+          );
+        }
       }
 
       if (result.summary.blocking) {

package/src/commands/session.js

@@ -33,6 +33,12 @@ import {
   unregisterAgent,
 } from "../session/agent-registry.js";
 import { startSenti, stopSenti } from "../session/daemon.js";
+import {
+  getDaemonStatus,
+  removeDaemonPidRecord,
+  spawnDetachedSentiDaemon,
+  writeDaemonPidRecord,
+} from "../session/daemon-spawn.js";
 import { listRuntimeRuns } from "../session/runtime-bridge.js";
 import {
   listFileLocks,
@@ -77,6 +83,7 @@ import {
 import { hydrateSessionFromRemote } from "../session/remote-hydrate.js";
 import { mergeLiveSources } from "../session/live-source.js";
 import { listenSessionEvents } from "../session/listener.js";
+import { SESSION_LIVE_SUCCESS_TIPS } from "../session/coordination-guidance.js";
 import { buildSessionRecap } from "../session/recap.js";
 import { computeTranscriptStats } from "../session/transcript.js";
 import { deriveSessionTitle } from "../session/senti-naming.js";
@@ -780,6 +787,42 @@ function sentiAutostartDisabled() {
   return String(process.env.SENTINELAYER_SKIP_SENTI_AUTOSTART || "").trim() === "1";
 }
 
+export function formatSentiDaemonStatusLine(sentiDaemon = {}, { cliCommand = "sl", sessionId = "" } = {}) {
+  if (sentiDaemon.spawned) {
+    return {
+      tone: "green",
+      text: `Senti: managing this session (daemon pid ${sentiDaemon.pid}, detached — survives this terminal). Log: ${sentiDaemon.logPath}`,
+    };
+  }
+  if (sentiDaemon.reason === "already_running") {
+    return {
+      tone: "green",
+      text: `Senti: already managing this session (daemon pid ${sentiDaemon.pid}).`,
+    };
+  }
+  if (sentiDaemon.reason === "disabled" || sentiDaemon.reason === "opt_out") {
+    return {
+      tone: "gray",
+      text: `Senti daemon skipped (${sentiDaemon.reason === "opt_out" ? "--no-daemon" : "SENTINELAYER_SKIP_SENTI_AUTOSTART=1"}); session is unmanaged. Start manually: ${cliCommand} session daemon ${sessionId}`,
+    };
+  }
+  return {
+    tone: "yellow",
+    text: `! Senti daemon not started (${sentiDaemon.reason || "unknown"}); session is unmanaged. Start manually: ${cliCommand} session daemon ${sessionId}`,
+  };
+}
+
+function printSentiDaemonStatusLine(sentiDaemon, context) {
+  const line = formatSentiDaemonStatusLine(sentiDaemon, context);
+  if (line.tone === "green") {
+    console.log(pc.green(line.text));
+  } else if (line.tone === "yellow") {
+    console.log(pc.yellow(line.text));
+  } else {
+    console.log(pc.gray(line.text));
+  }
+}
+
 function buildResumeContext(candidate, { reuseWindowSeconds = 3600 } = {}) {
   if (!candidate) return null;
   const source = normalizeString(candidate._source) || "unknown";
@@ -1200,7 +1243,7 @@ async function ensureLocalSessionForRemoteCommand(
   return { materialized: true, refreshed: false, session: created };
 }
 
-async function ensureWorkspaceSession({
+export async function ensureWorkspaceSession({
   targetPath,
   ttlSeconds = DEFAULT_TTL_SECONDS,
   template = null,
@@ -1405,6 +1448,41 @@ function formatListenerCatchupNotice(catchup = {}) {
   ].join(" ");
 }
 
+// Periodic in-session coaching reminder surfaced by `session listen`. Keeps
+// agents continually nudged toward good coordination (ack, claim work, reply
+// in-thread, surface findings). `tick` makes each emission idempotent so the
+// same reminder is not deduped across the run.
+export function buildSessionCoachingEvent({
+  sessionId,
+  agentId,
+  agentModel = "cli",
+  displayName = "",
+  listenerId = "",
+  tick = 0,
+  tips = SESSION_LIVE_SUCCESS_TIPS,
+} = {}) {
+  const tipList = Array.isArray(tips) && tips.length ? tips : SESSION_LIVE_SUCCESS_TIPS;
+  return createAgentEvent({
+    event: "session_coaching",
+    sessionId,
+    agent: {
+      id: agentId,
+      model: normalizeString(agentModel) || "cli",
+      role: "listener",
+      displayName: normalizeString(displayName) || agentId,
+      clientKind: "cli",
+    },
+    eventId: `session-coaching-${listenerId || agentId}-${tick}`,
+    idempotencyToken: `session-coaching:${listenerId || agentId}:${tick}`,
+    payload: compactPayload({
+      source: "session_listen",
+      kind: "coaching",
+      message: "Session success reminders:",
+      tips: [...tipList],
+    }),
+  });
+}
+
 function buildListenerCatchupEvent({
   sessionId,
   agentId,
@@ -1708,6 +1786,41 @@ async function resolveSessionAgentEnvelope(
   return Object.fromEntries(Object.entries(envelope).filter(([, value]) => value !== undefined));
 }
 
+// Builds the lock/unlock say-convention directive the session daemon parses
+// into the authoritative file-lock registry. Kept pure + exported for testing.
+export function buildSessionLockDirective(verb, file, intent = "") {
+  const normalizedFile = normalizeString(file);
+  const normalizedIntent = normalizeString(intent);
+  if (verb === "unlock") {
+    return `unlock: ${normalizedFile} - ${normalizedIntent || "done"}`;
+  }
+  return normalizedIntent ? `lock: ${normalizedFile} - ${normalizedIntent}` : `lock: ${normalizedFile}`;
+}
+
+// Posts a coordination directive (e.g. "lock: <file> - <intent>") as a session
+// message so the session daemon processes it into the authoritative file-lock
+// registry. Used by `session lock`/`unlock` as ergonomic sugar over the
+// say-convention; locks are advisory + daemon-enforced with TTL auto-release,
+// so this is a best-effort post.
+async function postSessionDirectiveMessage(sessionId, message, {
+  agentId,
+  targetPath = process.cwd(),
+} = {}) {
+  const clientMessageId = `cli-${randomUUID()}`;
+  const agent = await resolveSessionAgentEnvelope(sessionId, agentId, { targetPath });
+  await ensureSessionSayAgentRegistered(sessionId, agent, { targetPath });
+  const event = createAgentEvent({
+    event: "session_message",
+    agent,
+    sessionId,
+    payload: { message, channel: "session", clientMessageId },
+  });
+  event.eventId = clientMessageId;
+  event.idempotencyToken = clientMessageId;
+  const result = await syncSessionEventToApi(sessionId, event, { targetPath });
+  return { event, result };
+}
+
 async function runWithConcurrency(items = [], concurrency = 1, worker = async () => null) {
   const normalizedItems = Array.isArray(items) ? items : [];
   const normalizedConcurrency = Math.max(
@@ -2107,7 +2220,7 @@ export function registerSessionCommand(program) {
   session
     .command("start")
     .description(
-      "Start (or resume) a persistent session. By default reuses the most recent active session for this workspace; pass --force-new to always mint a fresh id.",
+      "Start (or resume) a managed session. Reuses this workspace's most recent active session when it was active within the last hour (--force-new always mints a fresh id), then spawns the detached Senti daemon that manages it — agent greetings, mention routing, recaps, checkpoints — surviving this terminal. Pass --no-daemon for an unmanaged session.",
     )
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--title <title>", "Human-readable label (shown in web sidebar + transcript)")
@@ -2137,6 +2250,10 @@ export function registerSessionCommand(program) {
       "Window in which an existing active session for this workspace will be reused (default 3600 = 1h)",
       "3600",
     )
+    .option(
+      "--no-daemon",
+      "Do not spawn the detached Senti daemon (session will be unmanaged: no greetings, recaps, or checkpoints)",
+    )
     .option("--json", "Emit machine-readable output")
     .action(async (options, command) => {
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -2219,19 +2336,25 @@ export function registerSessionCommand(program) {
         }).catch(() => {});
       }
 
-      // Auto-start the Senti orchestrator daemon. Without this, every
-      // session ran with `Senti actions: 1` (just the welcome alert)
-      // because nothing kicked the daemon ticking — agents joining
-      // never got greeted, mentions never routed, recaps never fired.
-      // Best-effort + non-blocking: the daemon registers itself in an
-      // in-memory map keyed by (sessionId, targetPath) and tolerates
-      // being started for an already-active session (returns the
-      // existing handle). If the daemon fails to start (unauth env,
-      // missing model proxy), the session keeps working — Senti just
-      // stays quiet, same as before this change.
-      if (!sentiAutostartDisabled()) {
-        void startSenti(created.sessionId, { targetPath }).catch(() => {});
+      // Make the session managed by default: spawn the Senti daemon as a
+      // DETACHED process so greetings, mention routing, recaps, and
+      // checkpoints keep running after this CLI command (and terminal)
+      // exits. The old in-process `startSenti` died the moment this
+      // action returned, so every session was effectively unmanaged.
+      // Deduped via the session's pid file; best-effort and never blocks
+      // session creation.
+      let sentiDaemon = { spawned: false, pid: null, reason: "skipped", logPath: "" };
+      if (sentiAutostartDisabled()) {
+        sentiDaemon.reason = "disabled";
+      } else if (options.daemon === false) {
+        sentiDaemon.reason = "opt_out";
+      } else {
+        sentiDaemon = await spawnDetachedSentiDaemon({
+          sessionId: created.sessionId,
+          targetPath,
+        });
       }
+      payload.sentiDaemon = sentiDaemon;
 
       if (shouldEmitJson(options, command)) {
         console.log(JSON.stringify(payload, null, 2));
@@ -2253,6 +2376,7 @@ export function registerSessionCommand(program) {
         }
         console.log("");
         console.log(`Dashboard: ${dashboardUrl}`);
+        printSentiDaemonStatusLine(sentiDaemon, { cliCommand, sessionId: created.sessionId });
         return;
       }
 
@@ -2278,6 +2402,13 @@ export function registerSessionCommand(program) {
       console.log(
         `status=${created.status} created_at=${created.createdAt} expires_at=${created.expiresAt} ttl_seconds=${ttlSeconds}`,
       );
+      console.log(pc.gray(`Dashboard: ${dashboardUrl}`));
+      printSentiDaemonStatusLine(sentiDaemon, { cliCommand, sessionId: created.sessionId });
+      console.log(
+        pc.gray(
+          `Agents join with: ${cliCommand} session join ${created.sessionId} --agent <name>`,
+        ),
+      );
       if (remoteSync.status === "auth_required") {
         console.log(
           pc.yellow(
@@ -2290,7 +2421,9 @@ export function registerSessionCommand(program) {
       if (!resumed) {
         console.log(
           pc.gray(
-            `Tip: subsequent \`${cliCommand} session start\` in this workspace within an hour will resume this session. Pass --force-new to override.`,
+            options.forceNew
+              ? `Tip: fresh session minted (--force-new honored). Subsequent \`${cliCommand} session start\` here within an hour will resume this new session.`
+              : `Tip: subsequent \`${cliCommand} session start\` in this workspace within an hour will resume this session. Pass --force-new to override.`,
           ),
         );
       }
@@ -3225,6 +3358,121 @@ export function registerSessionCommand(program) {
       return payload;
     });
 
+  const runLockDirectiveCommand = async (verb, sessionId, files, options, command) => {
+    const normalizedSessionId = normalizeString(sessionId);
+    if (!normalizedSessionId) {
+      throw new Error("session id is required.");
+    }
+    const fileList = (Array.isArray(files) ? files : [files])
+      .map((file) => normalizeString(file))
+      .filter(Boolean);
+    if (fileList.length === 0) {
+      throw new Error(`session ${verb} requires at least one file path.`);
+    }
+    const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+    await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+    const identity = await resolveMessageActionIdentity({
+      sessionId: normalizedSessionId,
+      optionAgent: options.agent,
+      targetPath,
+      env: process.env,
+    });
+    if (shouldBlockImplicitCliUserSessionSay(identity)) {
+      throw new Error(
+        identity.identityWarning ||
+          `session ${verb} requires an agent identity; pass --agent <id>, set SENTINELAYER_AGENT_ID, or run session join --agent <id> first.`,
+      );
+    }
+    const intent = normalizeString(options.intent);
+    const processed = [];
+    for (const file of fileList) {
+      const directive = buildSessionLockDirective(verb, file, intent);
+      await postSessionDirectiveMessage(normalizedSessionId, directive, {
+        agentId: identity.agentId,
+        targetPath,
+      });
+      processed.push(file);
+    }
+    const payload = {
+      command: `session ${verb}`,
+      sessionId: normalizedSessionId,
+      agentId: identity.agentId,
+      files: processed,
+    };
+    if (shouldEmitJson(options, command)) {
+      console.log(JSON.stringify(payload, null, 2));
+      return payload;
+    }
+    const action = verb === "lock" ? "Requested lock on" : "Released";
+    console.log(pc.green(`${action} ${processed.length} file(s) as ${identity.agentId}: ${processed.join(", ")}`));
+    if (verb === "lock") {
+      console.log(
+        pc.gray("Senti enforces fail-closed; locks auto-release on TTL. Release with `sl session unlock`."),
+      );
+    }
+    return payload;
+  };
+
+  session
+    .command("lock <sessionId> <files...>")
+    .description("Claim exclusive file locks via Senti (fail-closed, TTL auto-release)")
+    .option("--intent <text>", "Why you're locking these files (shown to peers)")
+    .option("--agent <id>", "Agent id claiming the lock (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, files, options, command) => {
+      await runLockDirectiveCommand("lock", sessionId, files, options, command);
+    });
+
+  session
+    .command("unlock <sessionId> <files...>")
+    .description("Release file locks you hold (Senti only lets the holder release)")
+    .option("--intent <text>", "Optional note on the release")
+    .option("--agent <id>", "Agent id releasing the lock (defaults to the joined session agent)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, files, options, command) => {
+      await runLockDirectiveCommand("unlock", sessionId, files, options, command);
+    });
+
+  session
+    .command("locks <sessionId>")
+    .description("List active file locks for the session (who holds what, and when they expire)")
+    .option("--path <path>", "Workspace path for the session", ".")
+    .option("--json", "Emit machine-readable output")
+    .action(async (sessionId, options, command) => {
+      const normalizedSessionId = normalizeString(sessionId);
+      if (!normalizedSessionId) {
+        throw new Error("session id is required.");
+      }
+      const targetPath = path.resolve(process.cwd(), String(options.path || "."));
+      await ensureLocalSessionForRemoteCommand(normalizedSessionId, { targetPath });
+      const locks = await listFileLocks(normalizedSessionId, { targetPath });
+      const lockList = Array.isArray(locks) ? locks : [];
+      const payload = {
+        command: "session locks",
+        sessionId: normalizedSessionId,
+        count: lockList.length,
+        locks: lockList,
+      };
+      if (shouldEmitJson(options, command)) {
+        console.log(JSON.stringify(payload, null, 2));
+        return payload;
+      }
+      if (lockList.length === 0) {
+        console.log(pc.gray("No active file locks."));
+        return payload;
+      }
+      console.log(pc.bold(`Active file locks (${lockList.length})`));
+      for (const lock of lockList) {
+        const file = normalizeString(lock.file || lock.filePath) || "(unknown file)";
+        const holder = normalizeString(lock.agentId) || "unknown";
+        const expires = normalizeString(lock.expiresAt);
+        console.log(pc.cyan(`  ${file}`) + pc.gray(`  held by ${holder}${expires ? ` · expires ${expires}` : ""}`));
+      }
+      return payload;
+    });
+
   session
     .command("listen")
     .description("Background-poll a session for events addressed to this agent or broadcast")
@@ -3272,6 +3520,12 @@ export function registerSessionCommand(program) {
       "--wake <command>",
       "Wake hook: run this shell command on each matched event (notify->resume bridge). Event JSON is piped to stdin; SL_WAKE_* env vars are set.",
     )
+    .option(
+      "--coaching-interval <seconds>",
+      "Seconds between in-session success reminders (ack, claim work, reply in-thread). Default 900; 0 disables.",
+      "900",
+    )
+    .option("--no-coaching", "Do not emit periodic in-session success reminders")
     .action(async (options) => {
       const normalizedSessionId = resolveSessionIdOption(options);
       const targetPath = path.resolve(process.cwd(), String(options.path || "."));
@@ -3345,6 +3599,44 @@ export function registerSessionCommand(program) {
       const presenceIntervalMs = Math.max(1, presenceIntervalSeconds) * 1000;
       let lastPresenceHeartbeatMs = 0;
 
+      // Periodic in-session success reminders (ack, claim work, reply
+      // in-thread). Long-running interactive listeners only — skipped under
+      // --max-polls (smoke/test) and when --no-coaching is set.
+      const coachingIntervalSeconds =
+        options.coaching === false
+          ? 0
+          : parsePositiveInteger(options.coachingInterval, "coaching-interval", 900);
+      let coachingTick = 0;
+      const emitCoaching = () => {
+        if (emitFormat === "ndjson") {
+          console.log(
+            JSON.stringify(
+              buildSessionCoachingEvent({
+                sessionId: normalizedSessionId,
+                agentId,
+                agentModel,
+                displayName,
+                listenerId,
+                tick: coachingTick++,
+              }),
+            ),
+          );
+        } else {
+          console.log(pc.cyan("Session success reminders:"));
+          for (const tip of SESSION_LIVE_SUCCESS_TIPS) {
+            console.log(pc.gray(`  - ${tip}`));
+          }
+        }
+      };
+      let coachingTimer = null;
+      if (coachingIntervalSeconds > 0 && maxPolls === null) {
+        emitCoaching();
+        coachingTimer = setInterval(emitCoaching, coachingIntervalSeconds * 1000);
+        if (coachingTimer && typeof coachingTimer.unref === "function") {
+          coachingTimer.unref();
+        }
+      }
+
       if (emitFormat === "text") {
         console.log(
           pc.gray(
@@ -3455,14 +3747,20 @@ export function registerSessionCommand(program) {
           },
         });
       } finally {
+        if (coachingTimer) {
+          clearInterval(coachingTimer);
+        }
         process.removeListener("SIGINT", onSigint);
       }
     });
 
   session
     .command("daemon [sessionId]")
-    .description("Run the Senti session daemon: hydrate events, emit recaps, and generate checkpoints")
+    .description(
+      "Run the Senti daemon that manages a session: greet joining agents, route mentions, emit recaps, and generate durable checkpoints. `session start` spawns this automatically as a detached background process — run it manually only for foreground monitoring or after --no-daemon. Records its pid in the session dir (senti-daemon.json) and exits when the session expires.",
+    )
     .option("--session <id>", "Session id to monitor")
+    .option("--force", "Take over even if senti-daemon.json reports another live daemon for this session")
     .option("--path <path>", "Workspace path for the session", ".")
     .option("--tick-interval <seconds>", "Seconds between health ticks (default 30)", "30")
     .option("--stale-agent-seconds <seconds>", "Seconds before an inactive agent is flagged stale (default 90)", "90")
@@ -3490,6 +3788,18 @@ export function registerSessionCommand(program) {
         "tick-interval",
         30,
       );
+      // One manager per session: refuse to double-run unless --force.
+      // A stale pid file (reboot, hard kill) reads as not-running and is
+      // safely overwritten.
+      if (!options.once) {
+        const existingDaemon = await getDaemonStatus(normalizedSessionId, { targetPath });
+        if (existingDaemon.running && existingDaemon.pid !== process.pid && !options.force) {
+          throw new Error(
+            `A Senti daemon is already managing session ${normalizedSessionId} (pid ${existingDaemon.pid}). Use --force to take over.`,
+          );
+        }
+        await writeDaemonPidRecord(normalizedSessionId, { targetPath, tickIntervalMs });
+      }
       const daemon = await startSenti(normalizedSessionId, {
         targetPath,
         autoStart: false,
@@ -3591,10 +3901,28 @@ export function registerSessionCommand(program) {
           } else {
             console.log(pc.gray(`tick ${payload.summary.generatedAt}: recap=${payload.summary.recap.reason || payload.summary.recap.mode || "ok"} checkpoint=${payload.summary.checkpoint.reason || payload.summary.checkpoint.checkpointId || "ok"}`));
           }
+          // A daemon must not outlive its session: stop cleanly once the
+          // session expires or its local cache disappears.
+          const liveSession = await getSession(normalizedSessionId, { targetPath }).catch(() => null);
+          const expiresAtMs = Date.parse(liveSession?.expiresAt || "");
+          if (
+            !liveSession ||
+            liveSession.status !== "active" ||
+            (Number.isFinite(expiresAtMs) && expiresAtMs <= Date.now())
+          ) {
+            if (!emitJson) {
+              console.log(pc.gray("senti daemon: session expired or closed; stopping."));
+            }
+            break;
+          }
         }
       } finally {
         process.removeListener("SIGINT", stop);
         process.removeListener("SIGTERM", stop);
+        await removeDaemonPidRecord(normalizedSessionId, {
+          targetPath,
+          onlyForPid: process.pid,
+        }).catch(() => {});
         const stopped = await daemon.stop("signal");
         if (emitJson) {
           console.log(

package/src/legacy-cli.js

@@ -227,6 +227,9 @@ function printUsage() {
   console.log("  sl session read <id> --remote --agent <id>  Read stream events and auto-record views");
   console.log("  sl session view <id> <seq>          Manually backfill a read receipt");
   console.log("  sl session pins <id> --json         List pinned messages with content (readable by agents)");
+  console.log("  sl session lock <id> <files...> --intent <why>  Claim file locks (fail-closed, TTL auto-release)");
+  console.log("  sl session unlock <id> <files...>   Release file locks you hold");
+  console.log("  sl session locks <id> --json        List active file locks (holder + expiry)");
   console.log("  sl session listen --session <id> --agent <id>  Background-poll a session for new events");
   console.log("  sl session recap now <id> --remote --json  Summarize current owners, locks, and work");
   console.log("  sl session daemon --session <id>    Run Senti recaps/checkpoints for long rooms");
@@ -2179,6 +2182,7 @@ export function buildHandoffPrompt({
   buildFromExistingRepo,
   authMode,
   codingAgent,
+  sessionId,
 }) {
   const codingAgentProfile = resolveCodingAgent(codingAgent || DEFAULT_CODING_AGENT_ID);
   const codingAgentConfigPath = codingAgentProfile.configFile || "none";
@@ -2242,7 +2246,16 @@ Repo context:
 - Target repo: ${repoSlug || "not provided"}
 - Workspace mode: ${buildFromExistingRepo ? "existing codebase" : "new scaffold"}
 
-## Multi-Agent Coordination (if session active)
+${
+  String(sessionId || "").trim()
+    ? `## Multi-Agent Coordination
+
+Project senti session (auto-created at init): \`${String(sessionId).trim()}\`
+- Join before starting work: \`sl session join ${String(sessionId).trim()} --agent <your-agent-name>\`
+- Post status updates as you work: \`sl session say ${String(sessionId).trim()} "<update>" --agent <your-agent-name>\`
+- Audit runs (\`sentinel /audit\`) relay per-persona progress into this session automatically, so swarm agents can watch each other's findings without losing context.`
+    : `## Multi-Agent Coordination (if session active)`
+}
 
 ${renderCoordinationNumberedList()}
 
@@ -2574,6 +2587,7 @@ async function writeInitConfigLockfile({
   secretName,
   repoSlug,
   workflowPath,
+  sessionId,
 }) {
   const lockDir = path.join(projectDir, ".sentinelayer");
   const configPath = path.join(lockDir, "config.json");
@@ -2585,6 +2599,7 @@ async function writeInitConfigLockfile({
     required_secret_name: String(secretName || "SENTINELAYER_TOKEN").trim() || "SENTINELAYER_TOKEN",
     repo_slug: normalizeRepoSlug(repoSlug || ""),
     workflow_path: path.relative(projectDir, workflowPath).replace(/\\/g, "/"),
+    session_id: String(sessionId || "").trim(),
   };
 
   await fsp.mkdir(lockDir, { recursive: true });
@@ -3142,6 +3157,26 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
       expectedSpecId: generatedSpecId || workflowSpecIdFromTemplate,
     });
   }
+  // Project senti session: every new project gets its own coordination room
+  // so agents (audit personas, builders, reviewers) can post progress and see
+  // each other's messages without losing context. Local-first + best-effort:
+  // an offline/unauthenticated init still completes.
+  let projectSession = null;
+  if (!boolFromEnv(process.env.SENTINELAYER_SKIP_PROJECT_SESSION)) {
+    try {
+      const { bootstrapProjectSession } = await import("./session/project-bootstrap.js");
+      projectSession = await bootstrapProjectSession({
+        projectDir,
+        projectName: effectiveProjectName,
+        skipGuides: true,
+      });
+    } catch (error) {
+      console.log(
+        pc.yellow(`! Senti project session bootstrap skipped: ${error?.message || error}`)
+      );
+    }
+  }
+
   const configLockfilePath = await writeInitConfigLockfile({
     projectDir,
     specId: workflowSpecId || generatedSpecId || workflowSpecIdFromTemplate,
@@ -3149,6 +3184,7 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
     secretName,
     repoSlug: interview.repoSlug || detectRepoSlug(projectDir) || "",
     workflowPath,
+    sessionId: projectSession?.sessionId || "",
   });
 
   await writeTextFile(
@@ -3174,6 +3210,7 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
       buildFromExistingRepo: interview.buildFromExistingRepo,
       authMode: effectiveAuthMode,
       codingAgent: interview.codingAgent,
+      sessionId: projectSession?.sessionId || "",
     })
   );
   await writeTextFile(
@@ -3186,6 +3223,19 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
     codingAgent: interview.codingAgent,
   });
 
+  // Guides go in after the coding-agent config so the config scaffold above
+  // doesn't see a guide-created AGENTS.md/CLAUDE.md and skip itself.
+  if (projectSession?.sessionId) {
+    try {
+      const { setupSessionGuides } = await import("./session/setup-guides.js");
+      projectSession.guides = await setupSessionGuides(projectSession.sessionId, {
+        targetPath: projectDir,
+      });
+    } catch (error) {
+      console.log(pc.yellow(`! Session coordination guides skipped: ${error?.message || error}`));
+    }
+  }
+
   await ensureSentinelStartScript(projectDir, effectiveProjectName);
 
   // Code scaffold: write starter source files, skip existing
@@ -3278,6 +3328,32 @@ export async function runLegacyCli(rawArgs = process.argv.slice(2)) {
   printSection("Complete");
   console.log(pc.green(`✔ Sentinelayer orchestration initialized in ${projectDir}`));
   console.log(pc.green(`✔ Config lockfile written: ${configLockfilePath}`));
+  if (projectSession?.sessionId) {
+    console.log(pc.green(`✔ Senti project session created: ${projectSession.sessionId}`));
+    console.log(pc.green(`  Dashboard: ${projectSession.dashboardUrl}`));
+    if (projectSession.daemon?.spawned) {
+      console.log(
+        pc.green(`  Senti: managing this session (daemon pid ${projectSession.daemon.pid}, detached).`)
+      );
+    } else if (projectSession.daemon?.reason && projectSession.daemon.reason !== "disabled") {
+      console.log(
+        pc.yellow(
+          `  Senti daemon not started (${projectSession.daemon.reason}); run: sl session daemon ${projectSession.sessionId}`
+        )
+      );
+    }
+    console.log(
+      pc.gray(
+        `  Agents coordinate here: sl session join ${projectSession.sessionId} --agent <name>; audit runs post progress automatically.`
+      )
+    );
+  } else {
+    console.log(
+      pc.yellow(
+        "! Senti project session not created. Run `sl session start` inside the project to create the coordination room."
+      )
+    );
+  }
   if (workflowSpecId) {
     console.log(pc.green(`✔ Omar workflow spec binding validated: ${workflowSpecId}`));
   } else {

package/src/session/audit-reporter.js

@@ -0,0 +1,164 @@
+import { createAgentEvent } from "../events/schema.js";
+import { registerAgent } from "./agent-registry.js";
+import { listActiveSessions } from "./store.js";
+import { appendToStream } from "./stream.js";
+
+const ORCHESTRATOR_AGENT_ID = "audit-orchestrator";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function formatSeveritySummary(summary = {}) {
+  return `P0=${Number(summary.P0 || 0)} P1=${Number(summary.P1 || 0)} P2=${Number(summary.P2 || 0)} P3=${Number(summary.P3 || 0)}`;
+}
+
+function formatDurationSeconds(durationMs) {
+  return `${Math.max(0, Math.round(Number(durationMs || 0) / 1000))}s`;
+}
+
+/**
+ * Resolve which senti session an audit run should report into.
+ * Explicit id wins; otherwise the workspace's most recently active local
+ * session (the one `create-sentinelayer` bootstraps for new projects).
+ * Returns "" when relay is disabled or no session exists — audit runs
+ * never require a session.
+ */
+export async function resolveAuditSessionId({
+  targetPath = process.cwd(),
+  explicitSessionId = "",
+  disabled = false,
+} = {}) {
+  if (disabled) {
+    return "";
+  }
+  const explicit = normalizeString(explicitSessionId);
+  if (explicit) {
+    return explicit;
+  }
+  const sessions = await listActiveSessions({ targetPath }).catch(() => []);
+  if (!Array.isArray(sessions) || sessions.length === 0) {
+    return "";
+  }
+  const sorted = [...sessions].sort((left, right) =>
+    normalizeString(right.lastInteractionAt || right.updatedAt || right.createdAt).localeCompare(
+      normalizeString(left.lastInteractionAt || left.updatedAt || left.createdAt)
+    )
+  );
+  return normalizeString(sorted[0]?.sessionId);
+}
+
+/**
+ * Relay audit-orchestrator lifecycle events into a senti session so swarm
+ * personas can see each other's progress (start, per-agent completion,
+ * final summary) in the project's shared room.
+ *
+ * Posts are queued sequentially so transcript order matches audit order,
+ * and every post is best-effort: a session outage never fails an audit.
+ */
+export function createAuditSessionReporter({ sessionId, targetPath = process.cwd() } = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return null;
+  }
+
+  const registeredAgents = new Set();
+  let postedCount = 0;
+  let failedCount = 0;
+  let queue = Promise.resolve();
+
+  const post = (agentId, message) => {
+    const id = normalizeString(agentId) || ORCHESTRATOR_AGENT_ID;
+    queue = queue.then(async () => {
+      try {
+        if (!registeredAgents.has(id)) {
+          registeredAgents.add(id);
+          await registerAgent(normalizedSessionId, {
+            agentId: id,
+            model: "audit-persona",
+            role: "auditor",
+            targetPath,
+            trackProcessExit: false,
+          }).catch(() => {});
+        }
+        const event = createAgentEvent({
+          event: "session_message",
+          agent: { id, persona: id },
+          sessionId: normalizedSessionId,
+          payload: { message, channel: "session" },
+        });
+        await appendToStream(normalizedSessionId, event, { targetPath, awaitRemoteSync: true });
+        postedCount += 1;
+      } catch {
+        failedCount += 1;
+      }
+    });
+    return queue;
+  };
+
+  const handleEvent = (evt) => {
+    if (!evt || typeof evt !== "object") {
+      return;
+    }
+    const payload = evt.payload && typeof evt.payload === "object" ? evt.payload : {};
+    switch (evt.event) {
+      case "phase_start":
+        if (payload.phase === "dispatch") {
+          void post(
+            ORCHESTRATOR_AGENT_ID,
+            `🔍 Audit dispatch started: ${Number(payload.agentCount || 0)} persona(s), max ${Number(payload.maxParallel || 1)} in parallel.`
+          );
+        }
+        break;
+      case "dispatch":
+        void post(
+          payload.agentId,
+          `▶ Starting ${normalizeString(payload.persona) || normalizeString(payload.agentId)} audit (${normalizeString(payload.domain) || "general"}).`
+        );
+        break;
+      case "agent_complete":
+        void post(
+          payload.agentId,
+          `✅ ${normalizeString(payload.agentId)} audit complete: ${Number(payload.findingCount || 0)} finding(s) (${formatSeveritySummary(payload.summary)}), status=${normalizeString(payload.status) || "ok"}, ${formatDurationSeconds(payload.durationMs)}.`
+        );
+        break;
+      case "phase_complete":
+        if (payload.phase === "dispatch") {
+          void post(
+            ORCHESTRATOR_AGENT_ID,
+            `Dispatch complete: ${Number(payload.agentCount || 0)} persona result(s) in ${formatDurationSeconds(payload.durationMs)}.`
+          );
+        }
+        break;
+      default:
+        break;
+    }
+  };
+
+  const stats = () => ({ posted: postedCount, failed: failedCount });
+
+  const completed = async (result = {}) => {
+    await post(
+      ORCHESTRATOR_AGENT_ID,
+      `🏁 Audit run ${normalizeString(result.runId)} complete — ${formatSeveritySummary(result.summary)} across ${Array.isArray(result.agentResults) ? result.agentResults.length : 0} persona(s). Report: ${normalizeString(result.reportMarkdownPath)}`
+    );
+    await queue;
+    return stats();
+  };
+
+  const failed = async (error) => {
+    await post(
+      ORCHESTRATOR_AGENT_ID,
+      `❌ Audit run failed: ${normalizeString(error?.message) || "unknown error"}`
+    );
+    await queue;
+    return stats();
+  };
+
+  return {
+    sessionId: normalizedSessionId,
+    handleEvent,
+    completed,
+    failed,
+  };
+}

package/src/session/coordination-guidance.js

@@ -21,6 +21,23 @@ export function getCoordinationEtiquetteItems() {
   return [...COORDINATION_ETIQUETTE_ITEMS];
 }
 
+// Short, punchy success reminders surfaced periodically by `session listen` so
+// agents are continually nudged to coordinate well (Carter: "keep reminding
+// agents how to be successful... always ack and say if you're working on
+// something"). Kept tight on purpose — this fires on a timer, so it must stay
+// low-noise.
+export const SESSION_LIVE_SUCCESS_TIPS = Object.freeze([
+  "Ack messages you've read: `sl session react <id> ack --target-sequence <n>` — don't go silent.",
+  "Say what you're doing: claim work with `sl session action <id> working_on --target-sequence <n>`.",
+  'Reply in-thread with `sl session reply <id> <seq> "..."`; start a new top-level post only when needed.',
+  "Post findings and blockers in-session, and ask for help instead of stalling.",
+  "Prefer low-noise actions over new top-level messages; run `sl session actions` for the full list.",
+]);
+
+export function getSessionLiveSuccessTips() {
+  return [...SESSION_LIVE_SUCCESS_TIPS];
+}
+
 export function renderCoordinationNumberedList({
   items = COORDINATION_ETIQUETTE_ITEMS,
   indent = "",

package/src/session/daemon-spawn.js

@@ -0,0 +1,192 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+import { resolveSessionPaths } from "./paths.js";
+
+const PID_FILE_NAME = "senti-daemon.json";
+const LOG_FILE_NAME = "senti-daemon.log";
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+export function sentiDaemonDisabled(env = process.env) {
+  return (
+    normalizeString(env.SENTINELAYER_SKIP_SENTI_AUTOSTART) === "1" ||
+    normalizeString(env.SENTINELAYER_SKIP_SENTI_DAEMON) === "1"
+  );
+}
+
+export function resolveDaemonPidPath(sessionId, { targetPath = process.cwd() } = {}) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  return path.join(paths.sessionDir, PID_FILE_NAME);
+}
+
+export function resolveDaemonLogPath(sessionId, { targetPath = process.cwd() } = {}) {
+  const paths = resolveSessionPaths(sessionId, { targetPath });
+  return path.join(paths.sessionDir, LOG_FILE_NAME);
+}
+
+export function isProcessAlive(pid) {
+  const numericPid = Number(pid);
+  if (!Number.isInteger(numericPid) || numericPid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(numericPid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means the process exists but belongs to another user.
+    return error?.code === "EPERM";
+  }
+}
+
+export async function readDaemonPidRecord(sessionId, { targetPath = process.cwd() } = {}) {
+  const pidPath = resolveDaemonPidPath(sessionId, { targetPath });
+  try {
+    const raw = await fsp.readFile(pidPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeDaemonPidRecord(
+  sessionId,
+  { targetPath = process.cwd(), pid = process.pid, tickIntervalMs = 30000 } = {}
+) {
+  const pidPath = resolveDaemonPidPath(sessionId, { targetPath });
+  const record = {
+    pid: Number(pid),
+    sessionId: normalizeString(sessionId),
+    targetPath: path.resolve(String(targetPath || ".")),
+    tickIntervalMs: Number(tickIntervalMs) || 30000,
+    startedAt: new Date().toISOString(),
+  };
+  await fsp.mkdir(path.dirname(pidPath), { recursive: true });
+  await fsp.writeFile(pidPath, `${JSON.stringify(record, null, 2)}\n`, "utf-8");
+  return record;
+}
+
+export async function removeDaemonPidRecord(
+  sessionId,
+  { targetPath = process.cwd(), onlyForPid = null } = {}
+) {
+  const pidPath = resolveDaemonPidPath(sessionId, { targetPath });
+  if (onlyForPid != null) {
+    const existing = await readDaemonPidRecord(sessionId, { targetPath });
+    if (existing && Number(existing.pid) !== Number(onlyForPid)) {
+      return false;
+    }
+  }
+  try {
+    await fsp.unlink(pidPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Whether a detached Senti daemon is currently managing the session.
+ * Stale pid files (machine reboot, hard kill on Windows) are reported as
+ * not running so the caller can safely respawn over them.
+ */
+export async function getDaemonStatus(sessionId, { targetPath = process.cwd() } = {}) {
+  const record = await readDaemonPidRecord(sessionId, { targetPath });
+  if (!record) {
+    return { running: false, pid: null, stale: false, record: null };
+  }
+  const alive = isProcessAlive(record.pid);
+  return {
+    running: alive,
+    pid: alive ? Number(record.pid) : null,
+    stale: !alive,
+    record,
+  };
+}
+
+export function resolveCliEntryPath() {
+  const entry = normalizeString(process.argv[1]);
+  return entry ? path.resolve(entry) : "";
+}
+
+/**
+ * Spawn `sl session daemon <id>` as a detached background process so the
+ * session stays managed (greetings, recaps, checkpoints, mention routing)
+ * after the creating terminal exits. Deduped via the session's pid file;
+ * output goes to senti-daemon.log in the session directory.
+ *
+ * Never throws: returns { spawned, pid, reason, logPath } so callers can
+ * report status without ever failing session creation.
+ */
+export async function spawnDetachedSentiDaemon({
+  sessionId,
+  targetPath = process.cwd(),
+  cliPath = "",
+  env = process.env,
+} = {}) {
+  const normalizedSessionId = normalizeString(sessionId);
+  if (!normalizedSessionId) {
+    return { spawned: false, pid: null, reason: "missing_session_id", logPath: "" };
+  }
+  if (sentiDaemonDisabled(env)) {
+    return { spawned: false, pid: null, reason: "disabled", logPath: "" };
+  }
+
+  const status = await getDaemonStatus(normalizedSessionId, { targetPath });
+  if (status.running) {
+    return {
+      spawned: false,
+      pid: status.pid,
+      reason: "already_running",
+      logPath: resolveDaemonLogPath(normalizedSessionId, { targetPath }),
+    };
+  }
+
+  const entryPath = normalizeString(cliPath) || resolveCliEntryPath();
+  if (!entryPath) {
+    return { spawned: false, pid: null, reason: "cli_entry_unresolved", logPath: "" };
+  }
+
+  const logPath = resolveDaemonLogPath(normalizedSessionId, { targetPath });
+  let logFd = null;
+  try {
+    await fsp.mkdir(path.dirname(logPath), { recursive: true });
+    logFd = fs.openSync(logPath, "a");
+    const child = spawn(
+      process.execPath,
+      [entryPath, "session", "daemon", normalizedSessionId, "--path", path.resolve(String(targetPath || "."))],
+      {
+        detached: true,
+        stdio: ["ignore", logFd, logFd],
+        windowsHide: true,
+        env,
+      }
+    );
+    child.unref();
+    return { spawned: true, pid: child.pid ?? null, reason: "spawned", logPath };
+  } catch (error) {
+    return {
+      spawned: false,
+      pid: null,
+      reason: `spawn_failed: ${normalizeString(error?.message) || "unknown"}`,
+      logPath,
+    };
+  } finally {
+    if (logFd != null) {
+      try {
+        fs.closeSync(logFd);
+      } catch {
+        // fd already closed
+      }
+    }
+  }
+}

package/src/session/project-bootstrap.js

@@ -0,0 +1,115 @@
+import path from "node:path";
+
+import { ensureWorkspaceSession } from "../commands/session.js";
+import { createAgentEvent } from "../events/schema.js";
+import { spawnDetachedSentiDaemon } from "./daemon-spawn.js";
+import { setupSessionGuides } from "./setup-guides.js";
+import { appendToStream } from "./stream.js";
+import { syncSessionMetadataToApi } from "./sync.js";
+import { buildDashboardUrl } from "./templates.js";
+
+export const PROJECT_BOOTSTRAP_AGENT = Object.freeze({
+  id: "project-bootstrap",
+  persona: "Project Bootstrap",
+  shortName: "Bootstrap",
+  color: "green",
+  avatar: "P",
+});
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+export function buildProjectSessionWelcomeMessage({ projectName, sessionId } = {}) {
+  const name = normalizeString(projectName) || "this project";
+  return [
+    `🏗️ Project session for "${name}" is live (created by \`create-sentinelayer\`).`,
+    "",
+    "This is the project's shared coordination room. Agents working on this codebase should:",
+    `- Join before starting work: \`sl session join ${sessionId} --agent <your-agent-name>\``,
+    `- Post status updates as you work: \`sl session say ${sessionId} "<update>" --agent <your-agent-name>\``,
+    "- Audit runs (`sentinel audit`) post per-persona progress here automatically, so swarm agents can see each other's findings without losing context.",
+  ].join("\n");
+}
+
+/**
+ * Create the project's senti session as part of `create-sentinelayer` init:
+ * a fresh workspace session rooted at the new project directory, with
+ * coordination guides written into AGENTS.md / CLAUDE.md and a welcome
+ * message announcing the room to joining agents.
+ *
+ * Local-first: session creation always succeeds offline; dashboard metadata
+ * sync and the welcome-message relay are best-effort and never throw.
+ *
+ * Pass `skipGuides: true` when the caller writes coding-agent config files
+ * after this call (guide upsert would otherwise create AGENTS.md/CLAUDE.md
+ * first and make the config scaffold skip itself) — then call
+ * `setupSessionGuides` once those files exist.
+ */
+export async function bootstrapProjectSession({
+  projectDir,
+  projectName,
+  ttlSeconds,
+  skipGuides = false,
+} = {}) {
+  const targetPath = path.resolve(normalizeString(projectDir) || ".");
+  const title = normalizeString(projectName) || path.basename(targetPath);
+
+  const ensured = await ensureWorkspaceSession({
+    targetPath,
+    title,
+    resume: false,
+    forceNew: true,
+    ...(Number.isFinite(Number(ttlSeconds)) && Number(ttlSeconds) > 0
+      ? { ttlSeconds: Math.floor(Number(ttlSeconds)) }
+      : {}),
+  });
+  const created = ensured.created;
+  const sessionId = created.sessionId;
+
+  // Best-effort dashboard visibility — session creation stays local-first.
+  await syncSessionMetadataToApi(sessionId, {
+    targetPath,
+    sessionId,
+    status: created.status,
+    createdAt: created.createdAt,
+    expiresAt: created.expiresAt,
+    title: ensured.title || title,
+    template: created.template,
+    codebaseContext: created.codebaseContext,
+  }).catch(() => {});
+
+  const guides = skipGuides ? null : await setupSessionGuides(sessionId, { targetPath });
+
+  const welcomeEvent = createAgentEvent({
+    event: "session_message",
+    agent: PROJECT_BOOTSTRAP_AGENT,
+    sessionId,
+    payload: {
+      message: buildProjectSessionWelcomeMessage({ projectName: title, sessionId }),
+      channel: "session",
+    },
+  });
+  let welcomePosted = true;
+  try {
+    await appendToStream(sessionId, welcomeEvent, { targetPath, awaitRemoteSync: true });
+  } catch {
+    welcomePosted = false;
+  }
+
+  // Project rooms are managed by default too: the detached Senti daemon
+  // greets joining agents and keeps recaps/checkpoints flowing. Honors
+  // SENTINELAYER_SKIP_SENTI_AUTOSTART / SENTINELAYER_SKIP_SENTI_DAEMON
+  // and never fails the bootstrap.
+  const daemon = await spawnDetachedSentiDaemon({ sessionId, targetPath });
+
+  return {
+    sessionId,
+    title: ensured.title || title,
+    targetPath,
+    dashboardUrl: buildDashboardUrl(sessionId),
+    guides,
+    welcomePosted,
+    daemon,
+  };
+}