sentinelayer-cli 0.46.5 → 0.48.0

package/skills/senti-room-notifications/listen-wrapper.cjs

@@ -0,0 +1,150 @@
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+
+function clip(s, n) {
+  const t = String(s);
+  return t.length <= n ? t : t.slice(0, n) + ` …[CLIPPED +${t.length - n} chars — READ FULL BEFORE ACTING/QUOTING]`;
+}
+
+// Shared by the listener and its offline self-tests. Each instance owns its state.
+function createClassifier({
+  me: ME, cwd: CWD, fs = require("fs"), now = Date.now,
+  setTimeout = global.setTimeout, clearTimeout = global.clearTimeout, log = console.log,
+}) {
+  const RECEIPT = CWD + "/last-delivered.json";
+  let deliveredMaxTs = "";
+  let observedMaxTs = "";
+  let hadReceiptAtBoot = false;
+  try {
+    const prior = JSON.parse(fs.readFileSync(RECEIPT, "utf8"));
+    if (prior && prior.deliveredMaxTs) { deliveredMaxTs = String(prior.deliveredMaxTs); hadReceiptAtBoot = true; }
+    if (prior && prior.observedMaxTs) observedMaxTs = String(prior.observedMaxTs);
+  } catch {}
+  function tsMs(ts) { const ms = Date.parse(String(ts || "")); return Number.isNaN(ms) ? -1 : ms; }
+  function newerThanDelivered(ts) { return tsMs(ts) > tsMs(deliveredMaxTs); }
+  let lastStateWrite = 0;
+  let stateTimer = null;
+  function writeState(force) {
+    const currentTime = now();
+    if (!force && currentTime - lastStateWrite < 5000) {
+      if (!stateTimer) stateTimer = setTimeout(() => { stateTimer = null; writeState(true); }, 5000);
+      return;
+    }
+    if (stateTimer) { clearTimeout(stateTimer); stateTimer = null; }
+    lastStateWrite = currentTime;
+    const pending = broadcastBuf.length ? broadcastBuf : [];
+    try {
+      fs.writeFileSync(RECEIPT, JSON.stringify({
+        deliveredMaxTs, observedMaxTs,
+        pendingCount: pending.length,
+        oldestPendingTs: pending.length ? pending[0].ts : null,
+        wroteAt: new Date(now()).toISOString(),
+      }));
+    } catch {}
+  }
+  function observe(ts) {
+    const v = String(ts || "");
+    if (tsMs(v) <= tsMs(observedMaxTs)) return;
+    observedMaxTs = v;
+    writeState(false);
+  }
+  function receipt(ts) {
+    const v = String(ts || "");
+    if (!newerThanDelivered(v)) return;
+    deliveredMaxTs = v;
+    if (tsMs(v) > tsMs(observedMaxTs)) observedMaxTs = v;
+    writeState(true);
+  }
+
+  const BROADCAST_FLUSH_MS = 180000;
+  const ADDRESSED_MAX_MENTIONS = 2;
+  let broadcastBuf = [];
+  let broadcastTimer = null;
+  const mySeqs = new Set();
+
+  function rememberMine(seq) {
+    if (!seq) return;
+    mySeqs.add(String(seq));
+    if (mySeqs.size > 200) mySeqs.delete(mySeqs.values().next().value);
+  }
+  function repliesToMe(target) { return !!target && mySeqs.has(String(target)); }
+  function mentionCount(text) {
+    const m = String(text || "").match(/@[A-Za-z][A-Za-z0-9._-]{2,}/g);
+    return m ? new Set(m.map((x) => x.toLowerCase())).size : 0;
+  }
+  function isHuman(who) { return /^human([-_]|$)/i.test(String(who || "")); }
+  function addressedToMe(text) {
+    return String(text || "").toLowerCase().includes(ME.toLowerCase())
+      && mentionCount(text) <= ADDRESSED_MAX_MENTIONS;
+  }
+  function flushBroadcasts() {
+    broadcastTimer = null;
+    if (!broadcastBuf.length) return;
+    const items = broadcastBuf; broadcastBuf = [];
+    const senders = [...new Set(items.map((i) => i.who))].join(",");
+    const manifest = items.map((i) => `${i.who}@${String(i.ts || "").slice(11, 19)}`).slice(0, 14).join(" ");
+    const newest = items[items.length - 1];
+    log(`[room-digest] ${items.length} broadcast(s) from ${senders} in ${BROADCAST_FLUSH_MS / 1000}s; newest ${newest.who} ${newest.ts} :: ${clip(newest.text, 500)} — READ THE ROOM for the others | batched: ${manifest}${items.length > 14 ? " +" + (items.length - 14) + " more" : ""}`);
+    receipt(newest.ts);
+  }
+  const deliveredKeys = new Set();
+  function normTs(ts) {
+    const ms = Date.parse(String(ts || ""));
+    return Number.isNaN(ms) ? String(ts || "") : String(ms);
+  }
+  function alreadyDelivered(who, ts) {
+    const k = String(who) + "|" + normTs(ts);
+    if (deliveredKeys.has(k)) return true;
+    deliveredKeys.add(k);
+    if (deliveredKeys.size > 500) deliveredKeys.delete(deliveredKeys.values().next().value);
+    return false;
+  }
+
+  function deliver(kind, who, ts, seq, target, text) {
+    if (alreadyDelivered(who, ts)) return;
+    if (isHuman(who) || addressedToMe(text) || repliesToMe(target)) {
+      log(`[${kind}] seq=${seq ?? "-"} ${who} ${ts || ""} replyTo=${target || "-"} :: ${clip(text, 700)}`);
+      receipt(ts);
+      return;
+    }
+    broadcastBuf.push({ who, ts, text });
+    if (!broadcastTimer) broadcastTimer = setTimeout(flushBroadcasts, BROADCAST_FLUSH_MS);
+  }
+
+  return {
+    deliver, addressedToMe, isHuman, mentionCount, rememberMine, flushBroadcasts,
+    tsMs, newerThanDelivered, receipt, observe, writeState,
+    bufLen: () => broadcastBuf.length,
+    state: () => ({ deliveredMaxTs, observedMaxTs, hadReceiptAtBoot }),
+  };
+}
+
+function main() {
+  const ME = process.env.SENTI_AGENT_ID;
+  const SID = process.env.SENTI_SESSION_ID;
+  const CLI = process.env.SENTI_CLI_PATH;
+  if (!ME || !SID || !CLI || !/^[a-zA-Z0-9_-]+$/.test(ME) || !/^[a-zA-Z0-9_-]+$/.test(SID)) {
+    console.error("Set SENTI_AGENT_ID, SENTI_SESSION_ID and SENTI_CLI_PATH before starting the listener.");
+    process.exit(1);
+  }
+  if (!path.isAbsolute(CLI)) {
+    console.error("SENTI_CLI_PATH must be an absolute path to sentinelayer-cli/bin/sentinelayer-cli.js.");
+    process.exit(1);
+  }
+  const CWD = path.join(os.homedir(), ".sentinelayer", "skill-listeners", SID, ME);
+  const POLL_CWD = path.join(CWD, "reply-poll");
+  const WAKE = null;
+
+  fs.mkdirSync(POLL_CWD, { recursive: true });
+  // The installed CLI owns subprocess orchestration; importing this file stays offline.
+  const runtime = path.join(path.dirname(fs.realpathSync(CLI)), "..", "src", "skills", "listener-runtime.cjs");
+  const { runListener } = require(runtime);
+  runListener({
+    me: ME, sessionId: SID, cliPath: CLI, cwd: CWD, pollCwd: POLL_CWD, wake: WAKE,
+    classifier: createClassifier({ me: ME, cwd: CWD }),
+  });
+}
+
+module.exports = { createClassifier };
+if (require.main === module) main();

package/skills/senti-room-notifications/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/skills/senti-room-notifications/test-classifier.js

@@ -0,0 +1,109 @@
+const path = require("path");
+const { createClassifier } = require(path.resolve(process.argv[2] || path.join(__dirname, "listen-wrapper.cjs")));
+if (typeof createClassifier !== "function") throw new Error("wrapper is missing createClassifier -- test would be vacuous");
+
+const printed = [];
+const api = createClassifier({
+  me: "agent-listener", cwd: "fake-cwd",
+  fs: { readFileSync: () => { throw new Error("no prior receipt"); }, writeFileSync: () => {} },
+  now: () => 10000,
+  log: (line) => printed.push(line),
+  setTimeout: () => 1, // never actually fire the timer; flush manually
+  clearTimeout: () => {},
+});
+// Fail before any assertions if the shipped factory stops exposing the code under test.
+for (const name of ["deliver", "addressedToMe", "isHuman", "mentionCount", "rememberMine", "flushBroadcasts", "bufLen"]) {
+  if (typeof api?.[name] !== "function") throw new Error("classifier is missing " + name + " -- test would be vacuous");
+}
+
+function immediate(fn) { const before = printed.length; fn(); return printed.length > before; }
+let fails = 0;
+function check(name, got, want) {
+  const ok = got === want;
+  if (!ok) fails++;
+  console.log(`${ok ? "PASS" : "FAIL"}  ${name}  (got ${got}, want ${want})`);
+}
+
+const TESTER = "@human-user @agent-reviewer @agent-builder @agent-peer @agent-listener one measurement, then I stop talking";
+const BUILDER  = "@agent-reviewer @agent-tester @agent-peer @agent-listener — I just generated a FALSE POSITIVE on the checker";
+const REVIEWER_REPLY = "reply #99: please verify the example";
+const ADDRESSED = "@agent-listener can you confirm the api sha flipped?";
+
+check("tester blanket broadcast is BUFFERED",
+  immediate(() => api.deliver("session_message", "agent-tester", "t1", 1, null, TESTER)), false);
+check("builder blanket broadcast is BUFFERED",
+  immediate(() => api.deliver("session_message", "agent-builder", "t2", 2, null, BUILDER)), false);
+check("post naming ONLY me wakes IMMEDIATELY",
+  immediate(() => api.deliver("session_message", "agent-reviewer", "t3", 3, null, ADDRESSED)), true);
+check("human-user wakes IMMEDIATELY",
+  immediate(() => api.deliver("session_message", "human-user", "t4", 4, null, "go on the migration")), true);
+check('poll-path actor "human" wakes IMMEDIATELY',
+  immediate(() => api.deliver("session_reply", "human", "t5", null, 99, "looks good")), true);
+check("unmentioned broadcast reply is BUFFERED",
+  immediate(() => api.deliver("session_reply", "agent-reviewer", "t6", null, 99, REVIEWER_REPLY)), false);
+
+// A reply to this agent's post wakes it even without an @-mention.
+api.rememberMine(555);
+check("reply to MY OWN post wakes IMMEDIATELY even with no mention",
+  immediate(() => api.deliver("session_reply", "agent-reviewer", "t7", null, 555, REVIEWER_REPLY)), true);
+check("reply to SOMEONE ELSE's post stays BUFFERED",
+  immediate(() => api.deliver("session_reply", "agent-reviewer", "t8", null, 99, REVIEWER_REPLY)), false);
+
+// Nothing was dropped: every buffered item is still there and one flush emits one line.
+check("buffered count is 4 (nothing dropped)", api.bufLen(), 4);
+const before = printed.length;
+api.flushBroadcasts();
+check("4 broadcasts cost exactly ONE wake", printed.length - before, 1);
+check("digest names all senders", /agent-tester/.test(printed[printed.length - 1]) && /agent-reviewer/.test(printed[printed.length - 1]), true);
+check("empty flush prints NOTHING", (() => { const n = printed.length; api.flushBroadcasts(); return printed.length - n; })(), 0);
+
+
+// Cross-path deduplication counts each event once.
+// The same event reaches deliver() twice: once from the listen stream, once from the reply-poll.
+// Two distinct broadcasts must produce two digest entries even when each arrives twice.
+const DUP_A = "@agent-one @agent-two @agent-three three-mention broadcast from builder";
+const DUP_B = "@agent-one @agent-two @agent-three @agent-four four-mention broadcast from tester";
+api.deliver("session_message", "agent-builder", "dup-ts-1", 11, null, DUP_A);   // stream
+api.deliver("session_reply",   "agent-builder", "dup-ts-1", null, null, DUP_A); // poll: SAME event
+api.deliver("session_message", "agent-tester",  "dup-ts-2", 12, null, DUP_B);   // stream
+api.deliver("session_reply",   "agent-tester",  "dup-ts-2", null, null, DUP_B); // poll: SAME event
+check("2 broadcasts on BOTH paths buffer as 2, not 4", api.bufLen(), 2);
+const b4 = printed.length;
+api.flushBroadcasts();
+check("digest says 2 broadcast(s), not 4", /2 broadcast/.test(printed[printed.length - 1]), true);
+check("that digest is still ONE wake", printed.length - b4, 1);
+
+// Duplicate addressed events must also produce only one wake.
+const before2 = printed.length;
+api.deliver("session_message", "agent-reviewer", "dup-ts-3", 13, null, "@agent-listener ping");
+api.deliver("session_reply",   "agent-reviewer", "dup-ts-3", null, null, "@agent-listener ping");
+check("addressed message on both paths wakes ONCE", printed.length - before2, 1);
+
+// Equivalent stream and poll timestamps must deduplicate despite different string formats.
+const STREAM_TS = "2000-01-01T00:00:01.115000+00:00";
+const POLL_TS   = "2000-01-01T00:00:01.115Z";
+const beforeFmt = printed.length;
+api.deliver("session_message", "agent-tester", STREAM_TS, 21, null, "@agent-listener real-format ping");
+api.deliver("session_reply",   "agent-tester", POLL_TS,   null, null, "@agent-listener real-format ping");
+check("same instant in the TWO REAL ts formats wakes ONCE", printed.length - beforeFmt, 1);
+
+const beforeFmt2 = printed.length;
+api.deliver("session_message", "agent-builder", "2000-01-01T00:00:02.500000+00:00", 22, null, "@agent-one @agent-two @agent-three broadcast");
+api.deliver("session_reply",   "agent-builder", "2000-01-01T00:00:02.500Z",         null, null, "@agent-one @agent-two @agent-three broadcast");
+check("cross-format broadcast buffers ONCE", api.bufLen(), 1);
+api.flushBroadcasts();
+check("digest says 1 broadcast(s), not 2", /1 broadcast/.test(printed[printed.length - 1]), true);
+
+// A genuinely different instant one millisecond away must still get through.
+const beforeMs = printed.length;
+api.deliver("session_message", "agent-tester", "2000-01-01T00:00:01.116Z", 23, null, "@agent-listener one ms later");
+check("an event 1ms apart is NOT deduped", printed.length - beforeMs, 1);
+
+// Guard the guard: distinct events from one sender must NOT be swallowed by the dedupe.
+const before3 = printed.length;
+api.deliver("session_message", "agent-reviewer", "distinct-ts-1", 14, null, "@agent-listener first");
+api.deliver("session_message", "agent-reviewer", "distinct-ts-2", 15, null, "@agent-listener second");
+check("two DISTINCT messages still wake twice", printed.length - before3, 2);
+
+console.log(fails ? (fails + " FAILING") : "ALL PASS");
+process.exit(fails ? 1 : 0);

package/skills/senti-room-notifications/test-receipt.js

@@ -0,0 +1,54 @@
+// Exercises the REAL receipt/reception code exported by the shipped wrapper.
+// This code is the recovery path: if it is wrong, a lost buffer stays lost and the safety net
+// cannot see the hole. It had two defects already (string compare, throttle with no trailing edge).
+const path = require("path");
+const { createClassifier } = require(path.resolve(process.argv[2] || path.join(__dirname, "listen-wrapper.cjs")));
+if (typeof createClassifier !== "function") throw new Error("wrapper is missing createClassifier -- test would be vacuous");
+
+let written = [];
+let timers = [];
+const fakeFs = {
+  readFileSync: () => { throw new Error("no prior receipt"); },
+  writeFileSync: (_p, body) => written.push(JSON.parse(body)),
+};
+const api = createClassifier({
+  me: "agent-listener", cwd: "fake-cwd", fs: fakeFs,
+  now: () => 10000,
+  setTimeout: (fn) => { timers.push(fn); return timers.length; },
+  clearTimeout: () => {}, log: () => {},
+});
+for (const name of ["tsMs", "newerThanDelivered", "receipt", "observe", "writeState", "state"]) {
+  if (typeof api?.[name] !== "function") throw new Error("classifier is missing " + name + " -- test would be vacuous");
+}
+
+let fails = 0;
+const check = (n, got, want) => { const ok = got === want; if (!ok) fails++; console.log(`${ok?"PASS":"FAIL"}  ${n}  (got ${got}, want ${want})`); };
+
+const STREAM = "2026-09-06T04:38:14.115000+00:00";
+const POLL   = "2026-09-06T04:38:14.115Z";
+check("the two wire formats parse to the SAME instant", api.tsMs(STREAM), api.tsMs(POLL));
+check("unparseable ts does not become 'newest'", api.tsMs("not-a-date"), -1);
+
+api.receipt(POLL);
+check("receipt advances delivered", api.state().deliveredMaxTs, POLL);
+check("INVARIANT delivered implies observed", api.tsMs(api.state().observedMaxTs) >= api.tsMs(POLL), true);
+check("same instant in the OTHER format is not 'newer'", api.newerThanDelivered(STREAM), false);
+check("one ms later IS newer", api.newerThanDelivered("2026-09-06T04:38:14.116Z"), true);
+
+// The throttle's trailing edge: the LAST observation of a burst must still reach disk.
+written = []; timers = [];
+api.observe("2026-09-06T04:39:00.000Z");          // lands (forced by receipt's earlier write? no: first observe)
+const afterFirst = written.length;
+api.observe("2026-09-06T04:39:01.000Z");          // throttled -> must SCHEDULE a trailing write
+api.observe("2026-09-06T04:39:02.000Z");          // throttled, already scheduled
+check("a throttled burst schedules a trailing write", timers.length >= 1, true);
+const beforeTrailing = written.length;
+timers.forEach((fn) => fn());                      // fire the trailing timer
+check("the trailing write actually lands", written.length > beforeTrailing, true);
+const last = written[written.length - 1];
+check("and it carries the NEWEST observation, not the first",
+  last.observedMaxTs, "2026-09-06T04:39:02.000Z");
+check("published state is self-consistent",
+  api.tsMs(last.observedMaxTs) >= api.tsMs(last.deliveredMaxTs), true);
+console.log(fails ? (fails + " FAILING") : "ALL PASS");
+process.exit(fails ? 1 : 0);

package/skills/sentinelayer-cli/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: sentinelayer-cli
+description: Operate the SentinelLayer sl CLI for authentication, Senti sessions, review, project guides and AIdenID identity. Use when a user asks for sl commands or work in a Senti room; check installed command help for current flags.
+metadata:
+  version: "1.0.0"
+---
+
+# Sentinelayer CLI (`sl`)
+
+Command reference for `sentinelayer-cli` (command alias: **`sl`**). Also installs the `sentinel`, `sl-cli`, `slc`, `create-sentinelayer`, and `sentinelayer-cli` bin names. Docs: https://sentinelayer.com/docs
+
+Use commands within the user's requested scope. Check the command help before changing remote state.
+
+## Global flags (apply broadly)
+
+- `-h, --help` — per-command help
+- `-v, --version` — version
+- `--json` — machine-readable JSON output (use this when capturing output for reasoning; it's available on almost every command)
+- `--path PATH` — target workspace path (default: `.`)
+- `--non-interactive` — disable prompts (requires `--interview-file`)
+
+When in doubt about a command's options, run `sl <cmd> --help` — help is authoritative and self-updates per release. Re-run `sl --help` if behavior seems stale; command availability depends on the installed release.
+
+## Quickstart flow
+
+```bash
+sl auth login && npx create-sentinelayer my-app && cd my-app
+# Then hand docs/spec.md to your coding agent
+```
+
+---
+
+## Authentication (`sl auth`)
+
+- `sl auth login` — browser auth, persists long-lived API token (provisions SentinelLayer + AIdenID)
+- `sl auth status` — show auth + AIdenID provisioning status
+- `sl auth sessions` (alias `sl auth list`) — list persisted local session metadata (for resume/audit)
+- `sl auth revoke` — revoke remote API token + clear matching local metadata
+- `sl auth logout` — clear local session (optionally revoke remote token)
+
+Always check `sl auth status` first if a session/scan command fails with an auth error.
+
+---
+
+## Session coordination (`sl session`) — the multi-agent room
+
+Ephemeral coordination sessions for multi-agent work. This is the biggest command group.
+
+### Lifecycle
+
+- `sl session start [--json]` — start or resume the workspace's most recent active session (reuses one active within the last hour; `--force-new` always mints fresh). Spawns a detached **Senti daemon** that manages greetings, mention routing, recaps, checkpoints. `--no-daemon` for unmanaged.
+- `sl session start --template code-review` — quick-start preset + launch plan
+- `sl session continue` — alias for `start --resume`
+- `sl session ensure` — join-or-create the canonical session for this workspace, emit JSON
+- `sl session templates --json` — list quick-start templates
+- `sl session join <id> [--name <n> | --agent <id>] [--role coder|reviewer|tester|observer] [--model <m>] [--json]` — attach to a remote-created session. **This is the command to use when the user says "join session X."** `--agent` emits an `agent_join` event as a granted agent id; `--name` is a legacy alias for `--agent`.
+- `sl session leave <id>` — leave
+- `sl session list [--remote] [--json]` — local cache by default; `--remote` queries the API for every session on the account
+- `sl session history` — past conversations with one-line previews (alias for `list --include-archived` + previews)
+- `sl session set-title <id> <title>` — set the human title (web sidebar + transcript)
+- `sl session cleanup [--cutoff-minutes N]` — bulk-archive empty stale sessions (≤1 events)
+
+### Posting & threading
+
+- `sl session say <id> "msg"` — top-level message. Key flags: `--agent <id>`, `--model`, `--display-name`, `--role`, `--to <agent>`, `--reply-to <seq>`, `--reply-cursor <cursor>`, `--force-cli-user`, `--local-only`, `--json`. The `--agent` resolves from `SENTINELAYER_AGENT_ID`, then the sole local joined agent, then `cli-user`.
+- `sl session post-agent <id> "msg"` — authenticated agent message through the canonical session event API
+- `sl session reply <id> <seq> "msg"` — threaded response under a target sequence
+- `sl session comment <id> <seq> "msg"` — alias for `reply`
+
+**Structured message forms** (passed as the `say` message body — Senti parses these):
+- `"lock: <file> - <intent>"` — request an exclusive file lock via Senti
+- `"assign: @agent <task>"` — create task assignment + lease
+- `"assign: @*:reviewer <task>"` — wildcard route to least-busy role
+- `"accepted: task <task-id>"` / `"done: task <task-id>"` — task transitions
+
+### Low-noise actions (no new top-level post)
+
+Run `sl session actions` for the live list. The supported set:
+
+- `ack` — `sl session react <id> ack --target-sequence <n>` — acknowledge read
+- `working_on` — `sl session action <id> working_on --target-sequence <n> --note "scope"` — claim ownership
+- `reply` / `comment` — `sl session reply <id> <seq> "msg"`
+- `like` — `sl session react <id> like --target-sequence <n>` (`--target-action-id <uuid>` to react to a threaded reply)
+- `dislike` — `sl session react <id> dislike --target-sequence <n>`
+- `disregard` — `sl session action <id> disregard --target-sequence <n>`
+- `view` — `sl session view <id> <seq>` — manually backfill a read receipt (remote reads record views automatically)
+
+### File locking (Senti, fail-closed, TTL auto-release)
+
+- `sl session lock <id> <files...> --intent <why>` — claim locks
+- `sl session unlock <id> <files...>` — release (only the holder can release)
+- `sl session locks <id> --json` — list active locks with holder + expiry
+
+### Reading & searching
+
+- `sl session read <id>` — recent messages. Flags: `--remote`, `--agent <id>` (auto-records views), `--tail 20`
+- `sl session pins <id> --json` — pinned messages with content (readable by agents)
+- `sl session search <id> <query>` — search durable events by text/type/agent
+- `sl session sync <id>` — pull human messages from the API into the local NDJSON stream
+- `sl session recap now <id> --remote --json` — summarize current owners, locks, work
+
+### Status, listeners, daemon
+
+- `sl session status <id> --json` — health, agents, runs, leases
+- `sl session listeners <id>` — who's actively listening + poll cadence (active/idle/stale/stopped), mirrors web roster
+- `sl session stop-listener <id> [--agent <id>]` — ask a listener (or all) to stop cleanly
+- `sl session listen --session <id> --agent <id>` — background-poll for events addressed to this agent or broadcast
+- `sl session daemon [id]` — run the Senti daemon in the foreground (greet joins, route mentions, recaps, checkpoints). `start` spawns it detached automatically; run manually only for foreground monitoring or after `--no-daemon`. Records pid in `senti-daemon.json`.
+- `sl session wake` — wake/register host CLI sessions for the Senti notification bus
+
+### Coordination guides & identity
+
+- `sl session setup-guides <id> --json` — upsert `AGENTS.md` / `CLAUDE.md` coordination section
+- `sl session inject-guide <id> --json` — append coordination section to existing `AGENTS.md` / `CLAUDE.md`
+- `sl session provision-emails <id> --count 5` — provision AIdenID emails for swarm testing
+
+### Export & admin
+
+- `sl session export <id>` — full transcript + metadata + agents + tasks as JSON (compliance/portability/handoff)
+- `sl session download <id>` — iMessage-style Markdown transcript (deterministic timestamps, per-agent active duration, persona avatars, human avatars from auth profile)
+- `sl session checkpoint` — list/create durable checkpoints
+- `sl session admin-kill <id> --reason <r>` — admin kill one remote session
+- `sl session admin-kill-all --confirm` — admin kill ALL remote sessions
+- `sl session kill --session <id> --agent <id>` — kill agent + revoke active leases
+
+### Typical "join and work" sequence
+
+```bash
+sl auth status                              # confirm authed
+sl session join <id> --agent <my-id> --role coder
+sl session read <id> --remote               # catch up
+sl session recap now <id> --remote --json   # who owns what, active locks
+sl session say <id> "lock: src/foo.ts - refactoring bar()"   # claim a file
+sl session say <id> "accepted: task <tid>"  # take a task
+# ... do the work ...
+sl session say <id> "done: task <tid>"
+sl session unlock <id> src/foo.ts
+```
+
+---
+
+## Security & review
+
+- `sl review scan --path . [--mode full|diff|staged] [--spec <path>] [--refresh] [--json]` — lightweight **policy** compatibility scan. `--diff` / `--staged` are aliases for the modes.
+- `sl scan validate` — validate existing security gate workflow against current spec profile
+- `sl scan precheck` — AI pre-scan triage from spec, emit review-ready report
+- `sl scan setup-secrets --repo <slug>` — inject `SENTINELAYER_TOKEN` into GitHub repo secrets
+
+---
+
+## Audit swarm (`sl audit`)
+
+- `sl audit --path . --json` — full **15-agent audit swarm**
+- `--agents <ids>` — comma-separated subset; `--max-parallel <n>` (default 3); `--isolation strict|relaxed` (default strict); `--dry-run` for planning only; `--stream` for NDJSON events; `--refresh` re-runs CODEBASE_INGEST first
+- `--session <id>` relays audit progress into a Senti session (defaults to the workspace's most recent active session; `--no-session` disables)
+- `--no-seed-from-deterministic` — run personas without deterministic baseline/specialist seed
+- Subcommands: `package`, `replay <runId>`, `diff <baseRunId> <candidateRunId>` (reproducibility comparison), `registry`
+- **Specialist-only runs:** `audit security | architecture | testing | performance | compliance | documentation`
+- `sl audit local` — legacy local readiness + policy audit
+- `sl audit frontend` — frontend runtime deep audit (use `--url` for runtime)
+
+---
+
+## Specification & planning
+
+- `sl spec list-templates` / `show-template <id>` — browse templates
+- `sl spec generate` — generate `SPEC.md` from ingest + template
+- `sl spec regenerate` — regenerate `SPEC.md`, **preserve manual edits**, show line diff before overwrite
+- `sl spec show` — render existing SPEC in terminal markdown
+- `sl prompt generate` / `preview` / `show` — agent execution prompt from SPEC
+- `sl guide generate` / `export` / `show` — phase-by-phase `BUILD_GUIDE.md` from SPEC
+
+---
+
+## Codebase ingest (`sl ingest`)
+
+- `sl ingest map --json` — generate `CODEBASE_INGEST.json` with stack/risk hints + framework detection (AST-based)
+
+---
+
+## Swarm planning (`sl swarm`)
+
+Governed multi-agent swarm execution with deterministic assignments + budgets.
+
+- `sl swarm registry` — list swarm agent registry
+- `sl swarm create` — create a governed swarm run (Phase 12.6 pen-test mode)
+- `sl swarm scenario` — create + validate swarm scenario DSL files
+- `sl swarm plan [path] --json` — build deterministic plan + artifacts
+- `sl swarm dashboard` — show/watch runtime dashboard snapshots from artifact streams
+- `sl swarm report` — build deterministic execution report bundle from runtime artifacts
+- `sl swarm run [path]` — execute governed swarm runtime loop (mock by default; optional Playwright adapter)
+
+---
+
+## AIdenID — identity testing (`sl ai`)
+
+- `sl ai provision-email` (alias `provision`) — provision an AIdenID payload (dry-run by default; `--execute` for live)
+- `sl ai identity provision --execute` — provision ephemeral test email (auto-credentials after login)
+- `sl ai identity wait-for-otp <id>` — poll for OTP extraction
+- `sl ai identity list` — tracked identities
+- `sl ai identity lineage <id>` — parent/child tree
+- `sl ai identity revoke <id>` — revoke
+
+---
+
+## Cost, policy, MCP, telemetry, config
+
+- `sl cost show --json` — accumulated cost tracking
+- `sl policy list` / `sl policy use <pack>` — list/switch policy packs
+- `sl mcp list --json` — list MCP registries and adapters
+- `sl telemetry show --json` — run event ledger
+- `sl config list` — current configuration
+
+---
+
+## Operating notes
+
+- **Help is authoritative.** Re-run `sl <cmd> --help` to confirm flags before relying on them.
+- **Prefer `--json`** whenever you're reasoning over output — it's stable and machine-readable across `session`, `review`, `scan`, `audit`, `ingest`, `swarm`, `cost`, `telemetry`.
+- **Sessions are the hub.** Most long-running work (audits, swarms) can relay progress into a Senti session via `--session <id>`. When the user says "join a session," use `sl session join <id> --agent <id> --role <role>`.
+- **Locks are fail-closed with TTL auto-release.** If a lock command fails, someone else holds it — read `sl session locks <id>` before retrying, don't force.
+- **`start` reuses recent sessions.** If you need a guaranteed-fresh session, pass `--force-new`.

package/src/agents/devtestbot/runner.js

@@ -6,6 +6,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { requireOutputFileSystem } from "../../config/output-filesystem.js";
 import AxeBuilder from "@axe-core/playwright";
 import { chromium } from "playwright";
 
@@ -28,6 +29,7 @@ export class DevTestBotRunnerError extends Error {
 }
 
 export async function launch({
+  outputFs,
   baseUrl,
   identityCreds = null,
   outputDir,
@@ -39,11 +41,13 @@ export async function launch({
   lighthouseTimeoutMs = DEFAULT_LIGHTHOUSE_TIMEOUT_MS,
   browserOptions = {},
 } = {}) {
+  requireOutputFileSystem(outputFs);
+  const writeJson = (...args) => writeJsonWithFs(outputFs, ...args);
   const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
   const runId = "devtestbot-" + new Date().toISOString().replace(/[:.]/g, "-") + "-" + randomUUID().slice(0, 8);
   const artifactRoot = path.resolve(outputDir || path.join(process.cwd(), ".sentinelayer", "runs", runId, "devtestbot"));
-  const videoDir = path.join(artifactRoot, "video");
-  await fsp.mkdir(videoDir, { recursive: true });
+  const videoDir = await outputFs.assertPath(path.join(artifactRoot, "video"));
+  await outputFs.mkdir(videoDir, { recursive: true });
 
   const browserExecutable = resolvePlaywrightChromiumExecutable();
   const playwrightFfmpeg = findPlaywrightFfmpegExecutable();
@@ -73,6 +77,7 @@ export async function launch({
     ...omit(browserOptions, ["args"]),
   });
 
+  await outputFs.assertPath(videoDir);
   const context = await browser.newContext({
     baseURL: normalizedBaseUrl,
     viewport,
@@ -260,6 +265,7 @@ export async function launch({
       url: targetUrl,
       outputPath,
       chromePath: browserExecutable,
+      outputFs,
       timeoutMs: options.timeoutMs || lighthouseTimeoutMs,
       sensitiveValues,
     });
@@ -284,7 +290,7 @@ export async function launch({
       await captureVideoFrame("final");
       if (videoFrames.length > 0) {
         const mp4Path = path.join(videoDir, "recording.mp4");
-        await writeMp4FromPngFrames(page, videoFrames, mp4Path, viewport);
+        await writeMp4FromPngFrames(page, videoFrames, mp4Path, viewport, outputFs);
         artifacts.videoMp4Path = mp4Path;
       }
     } catch (error) {
@@ -380,7 +386,8 @@ export function findPlaywrightFfmpegExecutable(env = process.env, platform = pro
   return null;
 }
 
-export async function writeMp4FromPngFrames(page, frames, outputPath, viewport = DEFAULT_VIEWPORT) {
+export async function writeMp4FromPngFrames(page, frames, outputPath, viewport = DEFAULT_VIEWPORT, outputFs) {
+  requireOutputFileSystem(outputFs);
   if (!Array.isArray(frames) || frames.length === 0) {
     throw new DevTestBotRunnerError("devTestBot MP4 generation requires at least one frame.", {
       code: "DEVTESTBOT_MP4_NO_FRAMES",
@@ -480,8 +487,8 @@ export async function writeMp4FromPngFrames(page, frames, outputPath, viewport =
     return Array.from(new Uint8Array(target.buffer));
   }, { payloadFrames, width, height });
 
-  await fsp.mkdir(path.dirname(outputPath), { recursive: true });
-  await fsp.writeFile(outputPath, Buffer.from(bytes));
+  await outputFs.mkdir(path.dirname(outputPath), { recursive: true });
+  await outputFs.writeFile(outputPath, Buffer.from(bytes));
   const stat = await fsp.stat(outputPath).catch(() => null);
   if (!stat || stat.size <= 0) {
     throw new DevTestBotRunnerError("devTestBot MP4 generation produced no output.", {
@@ -595,12 +602,15 @@ function sanitizeJson(value, sensitiveValues) {
   return value;
 }
 
-async function runLighthouseCli({ url, outputPath, chromePath, timeoutMs, sensitiveValues }) {
+async function runLighthouseCli({ url, outputPath, chromePath, timeoutMs, sensitiveValues, outputFs }) {
+  requireOutputFileSystem(outputFs);
+  const writeJson = (...args) => writeJsonWithFs(outputFs, ...args);
   const startedAt = new Date().toISOString();
-  await fsp.mkdir(path.dirname(outputPath), { recursive: true });
+  await outputFs.mkdir(path.dirname(outputPath), { recursive: true });
   let cliPath;
   try {
     cliPath = await resolveLighthouseCliPath();
+    outputPath = await outputFs.assertFilePath(outputPath);
     await execFileAsync(process.execPath, [
       cliPath,
       url,
@@ -750,9 +760,10 @@ async function settlePendingCaptures(pendingCaptures) {
   await Promise.allSettled([...pendingCaptures]);
 }
 
-async function writeJson(outputPath, payload) {
-  await fsp.mkdir(path.dirname(outputPath), { recursive: true });
-  await fsp.writeFile(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+async function writeJsonWithFs(outputFs, outputPath, payload) {
+  requireOutputFileSystem(outputFs);
+  await outputFs.mkdir(path.dirname(outputPath), { recursive: true });
+  await outputFs.writeFile(outputPath, JSON.stringify(payload, null, 2) + "\n", "utf-8");
 }
 
 function buildFinalResult({ artifacts, artifactRoot, consoleEvents, networkEvents }) {