@codyswann/lisa 4.80.1 → 4.81.0

package/plugins/lisa-agy/skills/lisa-session-manager/scripts/launch.mjs

@@ -0,0 +1,234 @@
+/**
+ * Starting and stopping the session manager, and the Telegram bot token it
+ * needs.
+ *
+ * The official Telegram plugin keeps its token, pairing list, inbox and
+ * `bot.pid` in one state dir (`TELEGRAM_STATE_DIR`, else
+ * `<CLAUDE_CONFIG_DIR>/channels/telegram`). It long-polls from EVERY session
+ * where it is enabled, and on start it SIGTERMs whichever poller holds the
+ * `bot.pid` in the same dir. So isolation is the whole design here:
+ * - the manager gets its own per-project state dir, set only in its own tmux
+ *   env, and the shared default dir is refused outright;
+ * - the plugin is enabled only through the manager's own `--settings`, never
+ *   at user scope, so worker sessions never start a poller;
+ * - the token lives in `<stateDir>/.env` (dir 0700, file 0600), is read from
+ *   the operator's terminal with echo off, and never appears in argv, a
+ *   return value, an error message or a log line.
+ *
+ * The tmux argv is returned as an array and handed straight to `spawnSync`.
+ * With more than one command argument tmux runs the command directly rather
+ * than through `sh -c`, so the settings JSON and the loop prompt are never
+ * re-parsed by a shell.
+ *
+ * The state dir lives in state-dir.mjs and the token in token.mjs; both are
+ * re-exported here so callers keep one import.
+ *
+ * Everything here is pure or takes injected seams. This module never reads
+ * the environment and never runs tmux or claude itself: `session-manager.mjs`
+ * passes the real env in and executes the argv.
+ * @module launch
+ */
+import path from "node:path";
+
+import { parseLoopInterval } from "./config.mjs";
+import { LaunchError } from "./state-dir.mjs";
+
+export {
+  LaunchError,
+  realpathExisting,
+  resolveStateDir,
+} from "./state-dir.mjs";
+export {
+  assertTokenPresent,
+  buildStoreTokenCommand,
+  loadPromptSecret,
+  storeToken,
+  validateBotToken,
+  writeTokenFile,
+} from "./token.mjs";
+
+/** The plugin the manager, and only the manager, enables. */
+export const TELEGRAM_PLUGIN_ID = "telegram@claude-plugins-official";
+
+/** Same slug rule the config validator applies to `sessionManager.name`. */
+const SESSION_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/** A `'` inside a single-quoted shell word: close, escaped quote, reopen. */
+const ESCAPED_QUOTE = "'\\''";
+
+/** An argument a POSIX shell reads back unchanged without quotes. */
+const SHELL_SAFE = /^[A-Za-z0-9_@%+=:,./-]+$/;
+
+/** The skill command each manager loop iteration runs. */
+const CYCLE_COMMAND = "/lisa:session-manager cycle";
+
+/**
+ * Settings blob for the manager session only: the Telegram plugin on, and
+ * workers' messages accepted.
+ * @returns {{ crossSessionInbound: "accept",
+ *   enabledPlugins: Record<string, boolean> }} Fresh settings object
+ */
+export function buildManagerSettings() {
+  return {
+    crossSessionInbound: "accept",
+    enabledPlugins: { [TELEGRAM_PLUGIN_ID]: true },
+  };
+}
+
+/**
+ * Refuse a tmux session name that is not a plain slug; `:` and `.` would be
+ * read by tmux as a window or pane target.
+ * @param {unknown} name - Session name
+ * @returns {string} The name
+ */
+function assertSessionName(name) {
+  if (typeof name !== "string" || !SESSION_NAME_PATTERN.test(name)) {
+    throw new LaunchError(
+      `Manager name "${String(name)}" must be a slug: lowercase letters, ` +
+        `digits, "-" or "_", at most 64 characters.`
+    );
+  }
+  return name;
+}
+
+/**
+ * Refuse a path that is not absolute.
+ * @param {string} label - Field name for the message
+ * @param {unknown} value - Path to check
+ * @returns {string} The path
+ */
+function assertAbsolute(label, value) {
+  if (typeof value !== "string" || !path.isAbsolute(value)) {
+    throw new LaunchError(`${label} must be an absolute path.`);
+  }
+  return value;
+}
+
+/**
+ * tmux argv (without `tmux`) that starts the manager detached.
+ *
+ * `TELEGRAM_STATE_DIR` goes only into this session's env so no other session
+ * ever sees it. `SM_SCRIPTS_DIR` lets every cycle's Bash find these scripts
+ * without re-resolving the plugin root.
+ * @param {{ name: string, root: string, stateDir: string, scriptsDir: string,
+ *   interval: string }} input - Session name, project root, resolved state
+ *   dir, this scripts dir, and the loop interval (e.g. "5m")
+ * @returns {string[]} argv for `spawnSync("tmux", argv)`
+ */
+export function buildManagerLaunch({
+  name,
+  root,
+  stateDir,
+  scriptsDir,
+  interval,
+}) {
+  assertSessionName(name);
+  assertAbsolute("root", root);
+  assertAbsolute("stateDir", stateDir);
+  assertAbsolute("scriptsDir", scriptsDir);
+  if (parseLoopInterval(interval) === null) {
+    throw new LaunchError(
+      `interval "${String(interval)}" must be a positive duration like 5m.`
+    );
+  }
+  return [
+    "new-session",
+    "-d",
+    "-s",
+    name,
+    "-c",
+    root,
+    "-e",
+    `TELEGRAM_STATE_DIR=${stateDir}`,
+    "-e",
+    `SM_SCRIPTS_DIR=${scriptsDir}`,
+    "claude",
+    "-n",
+    name,
+    "--dangerously-skip-permissions",
+    "--settings",
+    JSON.stringify(buildManagerSettings()),
+    "--channels",
+    `plugin:${TELEGRAM_PLUGIN_ID}`,
+    // `--channels` is variadic (claude 2.1.296): without `--` it takes the
+    // prompt as a second channel entry and claude exits 1 ("--channels
+    // entries must be tagged") before the session starts.
+    "--",
+    `/loop ${interval} ${CYCLE_COMMAND}`,
+  ];
+}
+
+/**
+ * Quote one argument for a POSIX shell, for display only.
+ * @param {string} value - Argument
+ * @returns {string} Single-quoted argument
+ */
+function shellQuote(value) {
+  return `'${value.replaceAll("'", ESCAPED_QUOTE)}'`;
+}
+
+/**
+ * The shell line an operator runs to start the manager in the foreground,
+ * from the tmux argv {@link buildManagerLaunch} returned: same cwd, the same
+ * two session variables, the same claude argv. `start` prints it when the
+ * tmux session dies at once, because tmux closes the window and claude's own
+ * error goes with it. It is display text only and is never executed here.
+ * The token is not in the argv, so it is not in this line either.
+ * @param {readonly string[]} argv - Result of {@link buildManagerLaunch}
+ * @returns {string} One shell line
+ */
+export function buildForegroundCommand(argv) {
+  const claudeAt = argv.indexOf("claude");
+  const head = argv.slice(0, claudeAt);
+  const cwd = head[head.indexOf("-c") + 1];
+  const vars = head
+    .filter((_, index) => head[index - 1] === "-e")
+    .map(entry => {
+      const at = entry.indexOf("=");
+      return `${entry.slice(0, at)}=${shellQuote(entry.slice(at + 1))}`;
+    });
+  const command = argv
+    .slice(claudeAt)
+    .map(arg => (SHELL_SAFE.test(arg) ? arg : shellQuote(arg)));
+  return `cd ${shellQuote(cwd)} && ${[...vars, ...command].join(" ")}`;
+}
+
+/**
+ * tmux argv that reports (by exit status) whether the manager is running.
+ * `=` asks for an exact name: tmux otherwise falls back to a prefix match, so
+ * `demo` would find a running `demo-manager` that belongs to someone else.
+ * @param {string} name - Manager session name
+ * @returns {string[]} argv for `spawnSync("tmux", argv)`
+ */
+export function buildHasSession(name) {
+  return ["has-session", "-t", `=${assertSessionName(name)}`];
+}
+
+/**
+ * tmux argv that prints the directory the manager session was started in.
+ * This is a target-pane command, where `=name` alone does not resolve to a
+ * session; `=name:` does. tmux 3.6 prints an empty line and exits 0 for a
+ * session that does not exist, so callers treat empty output as unknown.
+ * @param {string} name - Manager session name
+ * @returns {string[]} argv for `spawnSync("tmux", argv)`
+ */
+export function buildSessionPath(name) {
+  return [
+    "display-message",
+    "-p",
+    "-t",
+    `=${assertSessionName(name)}:`,
+    "#{session_path}",
+  ];
+}
+
+/**
+ * tmux argv that stops the manager session and nothing else (exact name, see
+ * {@link buildHasSession}). Workers are separate background sessions and keep
+ * running.
+ * @param {string} name - Manager session name
+ * @returns {string[]} argv for `spawnSync("tmux", argv)`
+ */
+export function buildStopManager(name) {
+  return ["kill-session", "-t", `=${assertSessionName(name)}`];
+}

package/plugins/lisa-agy/skills/lisa-session-manager/scripts/ledger.mjs

@@ -0,0 +1,445 @@
+/**
+ * The session manager's ledger: one JSON file of everything the manager
+ * dispatched, plus an append-only log of session events.
+ *
+ * Attempts are counted here and **never** in tracker comments. A counter kept
+ * in append-only comments cannot be reset when an item recovers, so a later
+ * cycle re-reads the old count and blocks the item again. The cost of keeping
+ * it local is stated plainly: a lost ledger resets attempts to zero.
+ *
+ * Every write goes through a temp file and a rename, so a crash mid-write
+ * leaves the previous ledger intact rather than half a file. A corrupt ledger
+ * is refused, not replaced, because replacing it would silently reset every
+ * attempt count.
+ *
+ * File I/O and the clock are injected (`{fs, now}`) so tests can observe the
+ * rename and pin timestamps. Nothing here reads `process.env` or a tracker.
+ * @module ledger
+ */
+
+import { randomUUID } from "node:crypto";
+import * as nodeFs from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+/** Shape version, bumped only on an incompatible change. */
+const LEDGER_VERSION = 1;
+
+/** Upper bound for `control.maxWorkers`, matching the Telegram `cap N` range. */
+const MAX_WORKERS_LIMIT = 32;
+
+/** Outcomes a worker can report about itself. */
+const FINISH_STATUSES = new Set(["DONE", "FAILED"]);
+
+/**
+ * @typedef {object} LedgerSeams
+ * @property {Pick<typeof nodeFs, "readFile"|"writeFile"|"rename"|"mkdir"|"appendFile">} [fs] - File system
+ * @property {() => Date} [now] - Clock
+ */
+
+/**
+ * The question an item is waiting on, and when it was last re-sent.
+ * @typedef {object} PendingQuestion
+ * @property {string} text - Question text
+ * @property {string} askedAt - When it was first asked (ISO)
+ * @property {string} lastPingAt - When it was last (re-)sent (ISO)
+ * @property {number|null} telegramMessageId - Telegram message carrying it
+ */
+
+/**
+ * One row of an item's history. `event` names what happened; the remaining
+ * fields depend on the event (a spawn carries the worker, a finish its status).
+ * @typedef {object} LedgerHistoryRow
+ * @property {string} event - spawn | question | answered | finish
+ * @property {string} at - When it happened (ISO)
+ * @property {string} [worker] - Spawned worker name
+ * @property {string|null} [sessionId] - Spawned session id
+ * @property {number} [attempt] - Attempt number of a spawn
+ * @property {string} [status] - Reported finish status
+ * @property {string} [reason] - Reported finish reason
+ */
+
+/**
+ * Everything the manager remembers about one dispatched (or asked-about) ref.
+ * @typedef {object} LedgerItem
+ * @property {string|null} repo - Repository the worker runs in
+ * @property {string|null} worker - Worker name
+ * @property {string|null} sessionId - Agent session id
+ * @property {string} status - running | question | DONE | FAILED
+ * @property {string|null} startedAt - Last spawn time (ISO)
+ * @property {string|null} lastProgressAt - Last time the logs hash moved (ISO)
+ * @property {string|null} logsHash - Hash of the worker's logs last cycle
+ * @property {PendingQuestion|null} pendingQuestion - Open question, if any
+ * @property {number} attempts - Spawns so far for this ref
+ * @property {LedgerHistoryRow[]} history - Everything that happened, in order
+ * @property {string|null} [reason] - Reason given with a finish
+ * @property {string|null} [finishedAt] - When the worker finished (ISO)
+ */
+
+/**
+ * The whole ledger file.
+ * @typedef {object} Ledger
+ * @property {number} version - Shape version
+ * @property {Record<string, LedgerItem>} items - Items keyed by ref
+ * @property {{paused: boolean, maxWorkers: number|null, me: string|null}} control - Operator controls
+ */
+
+/**
+ * Directory holding all session-manager state.
+ * @param {string} projectRoot - Absolute project root
+ * @returns {string} State directory
+ */
+function stateDir(projectRoot) {
+  return join(projectRoot, ".lisa", "session-manager");
+}
+
+/**
+ * Path of the ledger file.
+ * @param {string} projectRoot - Absolute project root
+ * @returns {string} Ledger path
+ */
+export function ledgerPath(projectRoot) {
+  return join(stateDir(projectRoot), "ledger.json");
+}
+
+/**
+ * Path of the session event log.
+ * @param {string} projectRoot - Absolute project root
+ * @returns {string} JSONL path
+ */
+export function sessionsLogPath(projectRoot) {
+  return join(stateDir(projectRoot), "sessions.jsonl");
+}
+
+/**
+ * A ledger with nothing in it.
+ * @returns {Ledger} Empty ledger
+ */
+function emptyLedger() {
+  return {
+    version: LEDGER_VERSION,
+    items: {},
+    control: { paused: false, maxWorkers: null, me: null },
+  };
+}
+
+/**
+ * Resolve injected seams against the real defaults.
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {{fs: NonNullable<LedgerSeams["fs"]>, now: () => Date}} Resolved seams
+ */
+function resolveSeams(seams = {}) {
+  return { fs: seams.fs ?? nodeFs, now: seams.now ?? (() => new Date()) };
+}
+
+/**
+ * Read the ledger. A missing file is an empty ledger; a corrupt one throws.
+ * @param {string} projectRoot - Absolute project root
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<Ledger>} Ledger
+ */
+export async function readLedger(projectRoot, seams) {
+  const { fs } = resolveSeams(seams);
+  const file = ledgerPath(projectRoot);
+  const text = await fs.readFile(file, "utf8").catch(error => {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  });
+  if (text === null) return emptyLedger();
+  const parsed = (() => {
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(
+        `session-manager ledger at ${file} is not valid JSON (${error.message}); refusing to reset attempts — repair or remove it`
+      );
+    }
+  })();
+  const empty = emptyLedger();
+  return {
+    version: parsed.version ?? empty.version,
+    items: parsed.items ?? {},
+    control: { ...empty.control, ...parsed.control },
+  };
+}
+
+/**
+ * Write the whole ledger atomically (temp file, then rename).
+ * @param {string} projectRoot - Absolute project root
+ * @param {Ledger} ledger - Ledger to persist
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<void>}
+ */
+export async function writeLedger(projectRoot, ledger, seams) {
+  const { fs } = resolveSeams(seams);
+  const file = ledgerPath(projectRoot);
+  await fs.mkdir(dirname(file), { recursive: true });
+  const tempPath = `${file}.${process.pid}.${randomUUID()}.tmp`;
+  await fs.writeFile(tempPath, `${JSON.stringify(ledger, null, 2)}\n`, "utf8");
+  await fs.rename(tempPath, file);
+}
+
+/**
+ * Read, transform and write the ledger in one step.
+ * @template T
+ * @param {string} projectRoot - Absolute project root
+ * @param {LedgerSeams | undefined} seams - Injected seams
+ * @param {(ledger: Ledger, at: string) => {ledger: Ledger, result: T}} transform - Pure update
+ * @returns {Promise<T>} The transform's result
+ */
+async function updateLedger(projectRoot, seams, transform) {
+  const { now } = resolveSeams(seams);
+  const current = await readLedger(projectRoot, seams);
+  const { ledger, result } = transform(current, now().toISOString());
+  await writeLedger(projectRoot, ledger, seams);
+  return result;
+}
+
+/**
+ * Replace one item in a ledger, returning the new ledger and the new item.
+ * @param {Ledger} ledger - Current ledger
+ * @param {string} ref - Item key
+ * @param {LedgerItem} entry - New item
+ * @returns {{ledger: Ledger, result: LedgerItem}} Update
+ */
+function withItem(ledger, ref, entry) {
+  return {
+    ledger: { ...ledger, items: { ...ledger.items, [ref]: entry } },
+    result: entry,
+  };
+}
+
+/**
+ * Look up an item that must already exist.
+ * @param {Ledger} ledger - Current ledger
+ * @param {string} ref - Item key
+ * @returns {LedgerItem} The item
+ */
+function requireItem(ledger, ref) {
+  const entry = ledger.items[ref];
+  if (!entry)
+    throw new Error(
+      `session-manager ledger has no item ${JSON.stringify(ref)}`
+    );
+  return entry;
+}
+
+/**
+ * A ledger item for a ref the manager has asked about but not dispatched.
+ * @returns {LedgerItem} Placeholder item
+ */
+function placeholderItem() {
+  return {
+    repo: null,
+    worker: null,
+    sessionId: null,
+    status: "question",
+    startedAt: null,
+    lastProgressAt: null,
+    logsHash: null,
+    pendingQuestion: null,
+    attempts: 0,
+    history: [],
+  };
+}
+
+/**
+ * Record a worker spawn. Each spawn for the same ref is one more attempt.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string, worker: string, sessionId: string|null, repo: string}} spawn - What was spawned
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<LedgerItem>} The updated item
+ */
+export function recordSpawn(
+  projectRoot,
+  { ref, worker, sessionId, repo },
+  seams
+) {
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const previous = ledger.items[ref] ?? placeholderItem();
+    const attempts = (previous.attempts ?? 0) + 1;
+    return withItem(ledger, ref, {
+      ...previous,
+      repo,
+      worker,
+      sessionId,
+      status: "running",
+      startedAt: at,
+      lastProgressAt: at,
+      logsHash: null,
+      pendingQuestion: null,
+      reason: null,
+      finishedAt: null,
+      attempts,
+      history: [
+        ...(previous.history ?? []),
+        { event: "spawn", at, worker, sessionId, attempt: attempts },
+      ],
+    });
+  });
+}
+
+/**
+ * Record (or re-ping) the question an item is waiting on.
+ *
+ * The same text again is a re-ping: `askedAt` is kept and `lastPingAt` moves,
+ * so the requestion clock restarts without forgetting how old the question
+ * is. A ref with no item yet (a repo-routing question asked before dispatch)
+ * gets a placeholder item with zero attempts.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string, text: string, telegramMessageId: number|null}} question - Question
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<LedgerItem>} The updated item
+ */
+export function setPendingQuestion(
+  projectRoot,
+  { ref, text, telegramMessageId },
+  seams
+) {
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const previous = ledger.items[ref] ?? placeholderItem();
+    const existing = previous.pendingQuestion;
+    const askedAt = existing?.text === text ? existing.askedAt : at;
+    return withItem(ledger, ref, {
+      ...previous,
+      pendingQuestion: {
+        text,
+        askedAt,
+        lastPingAt: at,
+        telegramMessageId: telegramMessageId ?? null,
+      },
+      history: [...(previous.history ?? []), { event: "question", at }],
+    });
+  });
+}
+
+/**
+ * Clear an item's pending question, once its answer has been delivered.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string}} target - Item
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<LedgerItem>} The updated item
+ */
+export function clearPendingQuestion(projectRoot, { ref }, seams) {
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const previous = requireItem(ledger, ref);
+    return withItem(ledger, ref, {
+      ...previous,
+      pendingQuestion: null,
+      history: [...(previous.history ?? []), { event: "answered", at }],
+    });
+  });
+}
+
+/**
+ * Record this cycle's hash of the worker's logs. `lastProgressAt` moves only
+ * when the hash changed, which is what "no output for N minutes" measures.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string, logsHash: string}} progress - Observed hash
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<{changed: boolean, entry: LedgerItem}>} Whether it moved, and the item
+ */
+export function recordProgress(projectRoot, { ref, logsHash }, seams) {
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const previous = requireItem(ledger, ref);
+    if (previous.logsHash === logsHash) {
+      return { ledger, result: { changed: false, entry: previous } };
+    }
+    const { ledger: next, result: entry } = withItem(ledger, ref, {
+      ...previous,
+      logsHash,
+      lastProgressAt: at,
+    });
+    return { ledger: next, result: { changed: true, entry } };
+  });
+}
+
+/**
+ * Record the worker's own terminal report.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string, status: "DONE"|"FAILED", reason: string}} finish - Report
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<LedgerItem>} The updated item
+ */
+export function recordFinish(projectRoot, { ref, status, reason }, seams) {
+  if (!FINISH_STATUSES.has(status)) {
+    return Promise.reject(
+      new Error(
+        `finish status must be DONE or FAILED, got ${JSON.stringify(status)}`
+      )
+    );
+  }
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const previous = requireItem(ledger, ref);
+    return withItem(ledger, ref, {
+      ...previous,
+      status,
+      reason,
+      finishedAt: at,
+      pendingQuestion: null,
+      history: [
+        ...(previous.history ?? []),
+        { event: "finish", at, status, reason },
+      ],
+    });
+  });
+}
+
+/**
+ * Check a control patch before it is written.
+ * @param {{paused?: unknown, maxWorkers?: unknown, me?: unknown}} patch - Patch
+ */
+function assertControlPatch(patch) {
+  if ("paused" in patch && typeof patch.paused !== "boolean") {
+    throw new Error("control.paused must be a boolean");
+  }
+  if (
+    "maxWorkers" in patch &&
+    patch.maxWorkers !== null &&
+    !(
+      Number.isInteger(patch.maxWorkers) &&
+      patch.maxWorkers >= 0 &&
+      patch.maxWorkers <= MAX_WORKERS_LIMIT
+    )
+  ) {
+    throw new Error(
+      `control.maxWorkers must be null or an integer 0..${MAX_WORKERS_LIMIT}`
+    );
+  }
+  if ("me" in patch && patch.me !== null && typeof patch.me !== "string") {
+    throw new Error("control.me must be a string or null");
+  }
+}
+
+/**
+ * Merge operator controls into the ledger: `paused`, the `maxWorkers`
+ * override (null clears it) and `me`, the resolved tracker identity.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{paused?: boolean, maxWorkers?: number|null, me?: string|null}} patch - Fields to set
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<{paused: boolean, maxWorkers: number|null, me: string|null}>} New control block
+ */
+export async function setControl(projectRoot, patch, seams) {
+  assertControlPatch(patch);
+  return updateLedger(projectRoot, seams, ledger => {
+    const control = { ...ledger.control, ...patch };
+    return { ledger: { ...ledger, control }, result: control };
+  });
+}
+
+/**
+ * Append one event to `sessions.jsonl`, stamped with the time.
+ * @param {string} projectRoot - Absolute project root
+ * @param {Record<string, unknown>} event - Event fields
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<void>}
+ */
+export async function appendSessionEvent(projectRoot, event, seams) {
+  const { fs, now } = resolveSeams(seams);
+  const file = sessionsLogPath(projectRoot);
+  await fs.mkdir(dirname(file), { recursive: true });
+  await fs.appendFile(
+    file,
+    `${JSON.stringify({ at: now().toISOString(), ...event })}\n`,
+    "utf8"
+  );
+}