@codyswann/lisa 4.80.2 → 4.81.1

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/cli-workers.mjs

@@ -0,0 +1,295 @@
+/**
+ * Worker subcommands of the session-manager CLI: capacity, spawn, resume and
+ * classify.
+ *
+ * `spawn` is the one that starts yolo-mode sessions, so its checks run in a
+ * fixed order and each has its own exit code the manager skill branches on:
+ * the repo must be a Lisa repo (2), there must be capacity (3), and no live
+ * worker may already hold the ref (4). Only then does it run
+ * `claude --bg`, with the cwd set to the routed repo and every `TELEGRAM_*`
+ * variable removed from the worker's environment. A repo whose workspace
+ * trust was never accepted is exit 2 too (see worker-launch.mjs).
+ * @module session-manager/cli-workers
+ */
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+
+import { computeCapacity, readMachineStats } from "./capacity.mjs";
+import {
+  CliError,
+  EXIT,
+  asSetupError,
+  intFlag,
+  listAgents,
+  loadProject,
+  mustRun,
+  requireConfig,
+  requireLisaRepo,
+  requirePositional,
+  run,
+  stdinText,
+  validOrAbsent,
+} from "./cli-runtime.mjs";
+import { SESSION_MANAGER_DEFAULTS, resolveRepoDir } from "./config.mjs";
+import {
+  appendSessionEvent,
+  readLedger,
+  recordProgress,
+  recordSpawn,
+} from "./ledger.mjs";
+import {
+  DEFAULT_STALL,
+  buildWorkerName,
+  buildWorkerResume,
+  buildWorkerSpawn,
+  classifyWorker,
+  countRunningWorkers,
+  findLiveWorker,
+  parseSessionId,
+} from "./workers.mjs";
+import { resolveFullSessionId, runWorkerSession } from "./worker-launch.mjs";
+
+/**
+ * Compute the capacity report for this machine and these agents.
+ * @param {object} ctx - CLI context
+ * @param {object} capacityConfig - `sessionManager.capacity`
+ * @param {ReturnType<typeof listAgents>} agents - Normalized rows
+ * @returns {Promise<ReturnType<typeof computeCapacity>>} Report
+ */
+async function measure(ctx, capacityConfig, agents) {
+  const meminfoPath = ctx.values.meminfo;
+  const stats = await readMachineStats({
+    // The hidden --meminfo flag reads a Linux meminfo file on any host.
+    platform: meminfoPath ? "linux" : ctx.platform,
+    meminfoPath,
+    exec: async command => mustRun(command, [], { env: ctx.env }),
+    readFile: file => readFile(file, "utf8"),
+  });
+  const { control } = await readLedger(ctx.root);
+  return computeCapacity({
+    stats,
+    running: countRunningWorkers(agents),
+    config: capacityConfig,
+    control,
+    flagMaxWorkers: intFlag(ctx.values["max-workers"], "--max-workers"),
+  });
+}
+
+/**
+ * `capacity`: the report the manager reads before every dispatch. Works with
+ * no `sessionManager` block (the documented defaults apply).
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} Capacity report
+ */
+export async function capacity(ctx) {
+  const config = validOrAbsent(loadProject(ctx.root));
+  const capacityConfig = config?.capacity ?? SESSION_MANAGER_DEFAULTS.capacity;
+  return { json: await measure(ctx, capacityConfig, listAgents(ctx)) };
+}
+
+/**
+ * Every worker name this project has used or can see, so a retry never
+ * reuses one.
+ * @param {ReturnType<typeof listAgents>} agents - Normalized rows
+ * @param {Awaited<ReturnType<typeof readLedger>>} ledger - Ledger
+ * @returns {Set<string>} Names
+ */
+function knownNames(agents, ledger) {
+  const fromLedger = Object.values(ledger.items).flatMap(item => [
+    item.worker,
+    ...(item.history ?? []).map(event => event.worker),
+  ]);
+  return new Set(
+    [...agents.map(agent => agent.name), ...fromLedger].filter(Boolean)
+  );
+}
+
+/**
+ * `spawn <ref> [--repo <key>]`: start one worker for one claimed item.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} `{ref,name,sessionId,repo,cwd}`
+ */
+export async function spawn(ctx) {
+  const ref = requirePositional(ctx, "ref");
+  const config = requireConfig(ctx);
+  const key = ctx.values.repo;
+  const repoDir = requireLisaRepo(
+    asSetupError(() => resolveRepoDir(config, key, ctx.root))
+  );
+
+  const agents = listAgents(ctx, { all: true });
+  const report = await measure(ctx, config.capacity, agents);
+  if (!report.can_spawn) {
+    throw new CliError(
+      `No capacity: ${report.running} running, cap ${report.cap}` +
+        `${report.paused ? ", paused" : ""}${report.overloaded ? ", overloaded" : ""}.`,
+      EXIT.NO_CAPACITY,
+      report
+    );
+  }
+  const live = asSetupError(() => findLiveWorker(agents, ref));
+  if (live) {
+    throw new CliError(
+      `${ref} already has a live worker: ${live.name}.`,
+      EXIT.LIVE_WORKER,
+      { ref, worker: live.name, sessionId: live.sessionId }
+    );
+  }
+
+  const ledger = await readLedger(ctx.root);
+  const spec = asSetupError(() => {
+    const name = buildWorkerName(ref, ctx.now(), knownNames(agents, ledger));
+    return buildWorkerSpawn({
+      ref,
+      name,
+      manager: config.name,
+      repoDir,
+      env: ctx.env,
+    });
+  });
+  const name = spec.args[2];
+  const stdout = runWorkerSession(spec);
+  const sessionId = parseSessionId(stdout);
+  if (sessionId === null) {
+    ctx.warn(
+      `claude --bg printed no session id; find ${name} in claude agents --json.`
+    );
+  }
+  const repo = key ?? ".";
+  await recordSpawn(ctx.root, { ref, worker: name, sessionId, repo });
+  await appendSessionEvent(ctx.root, {
+    event: "spawn",
+    ref,
+    worker: name,
+    sessionId,
+    repo,
+    cwd: repoDir,
+  });
+  return { json: { ref, name, sessionId, repo, cwd: repoDir } };
+}
+
+/**
+ * The ledger row for `ref`, or exit 2.
+ * @param {Awaited<ReturnType<typeof readLedger>>} ledger - Ledger
+ * @param {string} ref - Item ref
+ * @returns {object} Ledger item
+ */
+function ledgerItem(ledger, ref) {
+  const item = Object.hasOwn(ledger.items, ref) ? ledger.items[ref] : null;
+  if (!item) throw new CliError(`${ref} is not in the ledger.`, 2);
+  return item;
+}
+
+/**
+ * `resume <ref>`: resume a stopped worker with the message on stdin, in the
+ * worker's own repo and with the same environment scrub as a spawn.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object }>} `{ref,worker,sessionId,resumed}`
+ */
+export async function resume(ctx) {
+  const ref = requirePositional(ctx, "ref");
+  const text = stdinText(ctx, "message for the worker");
+  const config = requireConfig(ctx);
+  const item = ledgerItem(await readLedger(ctx.root), ref);
+  if (!item.sessionId && !item.worker) {
+    throw new CliError(`${ref} has no recorded session id to resume.`, 2);
+  }
+  // probe-direction: fail-closed — no full id means no resume: a short id
+  // would start an unseen copy of the conversation instead of the worker.
+  const sessionId = resolveFullSessionId(listAgents(ctx, { all: true }), item);
+  if (sessionId === null) {
+    throw new CliError(
+      `${ref}: no claude agents row gives the full session id for ` +
+        `${item.worker ?? item.sessionId}, and resuming by short id starts a ` +
+        `copy instead of the worker. Check claude agents --json --all.`,
+      2
+    );
+  }
+  const repoKey = item.repo === "." ? undefined : item.repo;
+  const spec = asSetupError(() =>
+    buildWorkerResume({
+      sessionId,
+      text,
+      repoDir: requireLisaRepo(resolveRepoDir(config, repoKey, ctx.root)),
+      env: ctx.env,
+    })
+  );
+  runWorkerSession(spec);
+  await appendSessionEvent(ctx.root, {
+    event: "resume",
+    ref,
+    worker: item.worker,
+    sessionId,
+  });
+  return {
+    json: {
+      ref,
+      worker: item.worker,
+      sessionId,
+      resumed: true,
+    },
+  };
+}
+
+/**
+ * Hash of `claude logs <name>`, or null when it cannot be read. An unchanged
+ * hash across cycles is the only "no output" signal the CLI offers.
+ *
+ * probe-direction: fail-closed — a failed `claude logs` read yields null,
+ * which `classifyWorker` never credits as progress, so the worker can only
+ * move toward `stalled` (a retry), never be kept `working` on a read that
+ * did not happen.
+ * @param {object} ctx - CLI context
+ * @param {string} name - Worker name
+ * @returns {string | null} sha256 hex
+ */
+function logsHash(ctx, name) {
+  const result = run("claude", ["logs", name], { env: ctx.env });
+  if (result.status !== 0) return null;
+  return createHash("sha256").update(result.stdout).digest("hex");
+}
+
+/**
+ * `classify [<ref>]`: classify one ledger item, or every one, for this cycle,
+ * and record each logs hash as progress.
+ * @param {object} ctx - CLI context
+ * @returns {Promise<{ json: object[] }>} One row per item
+ */
+export async function classify(ctx) {
+  const config = validOrAbsent(loadProject(ctx.root));
+  const stall = config?.stall ?? DEFAULT_STALL;
+  const ledger = await readLedger(ctx.root);
+  const [only] = ctx.positionals;
+  const refs = only ? [only] : Object.keys(ledger.items).sort();
+  const agents = listAgents(ctx, { all: true });
+  const rows = [];
+  for (const ref of refs) {
+    const entry = ledgerItem(ledger, ref);
+    // A worker-less item (asked about, never dispatched) has no session to
+    // pair with; `null === null` would adopt any unnamed agent as its worker.
+    const named = entry.worker
+      ? agents.filter(agent => agent.name === entry.worker)
+      : [];
+    const agent = named.find(row => row.active) ?? named[0] ?? null;
+    const hash = agent ? logsHash(ctx, entry.worker) : null;
+    const classification = classifyWorker({
+      agent,
+      entry,
+      logsHash: hash,
+      now: ctx.now(),
+      stall,
+    });
+    if (hash !== null) await recordProgress(ctx.root, { ref, logsHash: hash });
+    rows.push({
+      ref,
+      worker: entry.worker ?? null,
+      sessionId: entry.sessionId ?? null,
+      repo: entry.repo ?? null,
+      classification,
+      attempts: entry.attempts ?? 0,
+      agentStatus: agent?.status ?? agent?.state ?? null,
+      pendingQuestion: entry.pendingQuestion ?? null,
+    });
+  }
+  return { json: rows };
+}

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/config.mjs

@@ -0,0 +1,265 @@
+/**
+ * Resolve the opt-in `sessionManager` block of `.lisa.config.json`.
+ *
+ * Every other session-manager module reads its settings from the object this
+ * returns, so the documented defaults live in exactly one place. Merging is per
+ * key, local over global, the same rule every other Lisa config key follows: a
+ * developer can lower `capacity.maxWorkers` on their own machine without
+ * restating the rest of the block.
+ *
+ * The block is deliberately not registered in `src/sync/registry.ts`. That
+ * registry populates defaults into every project, and the manager starts
+ * yolo-mode sessions; it must exist only where an operator wrote it.
+ *
+ * Pure apart from `detectRepos`, whose filesystem calls are injectable.
+ * @module session-manager/config
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+
+import {
+  mergeConfigLayers as mergeLayers,
+  parseLoopInterval,
+  validateSessionManager,
+} from "../../lisa-secrets-access/scripts/validate-config.mjs";
+
+export { parseLoopInterval, validateSessionManager };
+
+/**
+ * Documented defaults for every optional key.
+ *
+ * `name` and `notify.stateDir` have none: both are per-project, and a shared
+ * default for either is how two projects end up fighting over one bot.
+ * `buildDefaultBlock` derives them from the project slug at setup time.
+ */
+export const SESSION_MANAGER_DEFAULTS = Object.freeze({
+  interval: "5m",
+  capacity: Object.freeze({
+    maxWorkers: 6,
+    gbPerWorker: 3,
+    reserveGb: 8,
+    cpuFraction: 0.75,
+    maxLoadPerCore: 1.5,
+  }),
+  stall: Object.freeze({
+    noOutputMinutes: 60,
+    maxAttempts: 3,
+    requestionHours: 4,
+  }),
+  notify: Object.freeze({ provider: "telegram" }),
+});
+
+/**
+ * @typedef {{ root: string, entries: Record<string, { hints: string[] }> }} ReposBlock
+ * @typedef {{ maxWorkers: number, gbPerWorker: number, reserveGb: number,
+ *   cpuFraction: number, maxLoadPerCore: number }} CapacityBlock
+ * @typedef {{ noOutputMinutes: number, maxAttempts: number,
+ *   requestionHours: number }} StallBlock
+ * @typedef {{ provider: string, stateDir?: string }} NotifyBlock
+ * @typedef {{
+ *   name: string,
+ *   interval: string,
+ *   repos: ReposBlock | null,
+ *   capacity: CapacityBlock,
+ *   stall: StallBlock,
+ *   notify: NotifyBlock,
+ *   trustedAuthorIds: string[] | null,
+ * }} SessionManagerConfig
+ * @typedef {{
+ *   name: string,
+ *   interval: string,
+ *   repos?: ReposBlock,
+ *   capacity: CapacityBlock,
+ *   stall: StallBlock,
+ *   notify: { provider: string, stateDir: string },
+ * }} SessionManagerBlock
+ */
+
+/** Where child repos live when `repos.root` is omitted. */
+const DEFAULT_REPOS_ROOT = "projects";
+
+/** One path segment that cannot climb out of, or hide inside, its parent. */
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+/**
+ * Whether a value is a plain object (not null, not an array).
+ * @param {unknown} value Candidate.
+ * @returns {boolean} True for `{}`-shaped values.
+ */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Resolve the effective `sessionManager` settings.
+ *
+ * Pass the two parsed config files, or one already-merged config. Returns
+ * `null` when neither declares the block, so callers can say "not configured"
+ * instead of running with a guessed name. Validation is separate
+ * (`validateSessionManager`), because doctor wants every problem listed while
+ * the CLI only needs a usable object.
+ * @param {object|undefined} globalConfig Parsed `.lisa.config.json` (or a
+ *   merged config).
+ * @param {object|undefined} [localConfig] Parsed `.lisa.config.local.json`.
+ * @returns {SessionManagerConfig | null} The resolved block, or null when
+ *   absent.
+ */
+export function resolveSessionManagerConfig(globalConfig, localConfig) {
+  const declared = [globalConfig, localConfig]
+    .map(config => (isPlainObject(config) ? config.sessionManager : undefined))
+    .filter(isPlainObject);
+  if (declared.length === 0) return null;
+
+  const merged = mergeLayers(SESSION_MANAGER_DEFAULTS, ...declared);
+  const repos = isPlainObject(merged.repos)
+    ? mergeLayers({ root: DEFAULT_REPOS_ROOT, entries: {} }, merged.repos)
+    : null;
+  return {
+    ...merged,
+    repos,
+    trustedAuthorIds: merged.trustedAuthorIds ?? null,
+  };
+}
+
+/**
+ * List the Lisa-configured child repos of a multi-repo project.
+ *
+ * A child counts only when it carries its own `.lisa.config.json`: workers run
+ * `/lisa:implement` inside it, which needs that file, and a stray directory
+ * under `projects/` is not something to route tickets into.
+ * @param {string} root Project root.
+ * @param {{
+ *   reposRoot?: string,
+ *   fs?: { existsSync: (p: string) => boolean,
+ *     readdirSync: (p: string, o: { withFileTypes: true }) =>
+ *       Array<{ name: string, isDirectory: () => boolean }> },
+ * }} [options] Repos root (default `projects`) and filesystem seam.
+ * @returns {string[]} Child directory names, sorted.
+ */
+export function detectRepos(root, options = {}) {
+  const fs = options.fs ?? { existsSync, readdirSync };
+  const base = join(root, options.reposRoot ?? DEFAULT_REPOS_ROOT);
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && SAFE_SEGMENT.test(entry.name))
+    .filter(entry => fs.existsSync(join(base, entry.name, ".lisa.config.json")))
+    .map(entry => entry.name)
+    .sort();
+}
+
+/**
+ * Turn a project name into a slug the validator accepts.
+ * @param {string} projectSlug Project name, possibly with dots or capitals.
+ * @returns {string} Lowercase, dash-separated slug.
+ */
+function normalizeSlug(projectSlug) {
+  const slug = String(projectSlug ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    // Leave room for the "-manager" suffix inside the 64-character name limit.
+    .slice(0, 56)
+    .replace(/-+$/, "");
+  if (!slug) {
+    throw new Error(
+      `project slug ${JSON.stringify(projectSlug)} has no letters or digits ` +
+        `to name the manager after.`
+    );
+  }
+  return slug;
+}
+
+/**
+ * Build the block setup writes into a project's `.lisa.config.json`.
+ *
+ * Defaults are written out rather than left implicit, so an operator sees
+ * every knob in the file they will edit. With no detected repos the block has
+ * no `repos` key, which is what makes a project single-repo. Each detected
+ * repo's hints start as its own name: valid, and an obvious prompt to add real
+ * ones.
+ * @param {{ projectSlug: string, detectedRepos?: string[] }} input Project
+ *   slug and the output of `detectRepos`.
+ * @returns {SessionManagerBlock} A block `validateSessionManager` accepts.
+ */
+export function buildDefaultBlock({ projectSlug, detectedRepos = [] }) {
+  const slug = normalizeSlug(projectSlug);
+  const repos = [...detectedRepos].sort();
+  return {
+    name: `${slug}-manager`,
+    interval: SESSION_MANAGER_DEFAULTS.interval,
+    ...(repos.length > 0
+      ? {
+          repos: {
+            root: DEFAULT_REPOS_ROOT,
+            entries: Object.fromEntries(
+              repos.map(name => [name, { hints: [name] }])
+            ),
+          },
+        }
+      : {}),
+    capacity: { ...SESSION_MANAGER_DEFAULTS.capacity },
+    stall: { ...SESSION_MANAGER_DEFAULTS.stall },
+    notify: {
+      provider: SESSION_MANAGER_DEFAULTS.notify.provider,
+      stateDir: `~/.claude/channels/telegram-${slug}`,
+    },
+  };
+}
+
+/**
+ * Resolve the directory a worker for `key` must start in.
+ *
+ * Workers run with permissions bypassed, so this refuses rather than guesses:
+ * an unknown key, a key on a single-repo project, or a missing key on a
+ * multi-repo one all throw. Only own `entries` keys resolve, so `constructor`
+ * and friends cannot.
+ * @param {{ repos?: unknown } | null | undefined} config Resolved (or raw)
+ *   `sessionManager` block.
+ * @param {string|undefined} key Repo key; omit, or pass `.`, for single-repo.
+ * @param {string} projectRoot Absolute project root.
+ * @returns {string} Absolute repo directory.
+ */
+export function resolveRepoDir(config, key, projectRoot) {
+  if (typeof projectRoot !== "string" || !isAbsolute(projectRoot)) {
+    throw new Error(
+      `project root ${JSON.stringify(projectRoot)} must be an absolute path.`
+    );
+  }
+  const repos = isPlainObject(config?.repos) ? config.repos : null;
+  const noKey = key === undefined || key === null || key === "" || key === ".";
+
+  if (!repos) {
+    if (noKey) return resolve(projectRoot);
+    throw new Error(
+      `repo ${JSON.stringify(key)} given, but this is a single-repo project ` +
+        `(sessionManager.repos is not set); workers start at the project root.`
+    );
+  }
+
+  const entries = isPlainObject(repos.entries) ? repos.entries : {};
+  const known = Object.keys(entries).sort();
+  if (noKey) {
+    throw new Error(
+      `this multi-repo project needs a repo key; one of: ${known.join(", ")}.`
+    );
+  }
+  if (!Object.hasOwn(entries, key) || !SAFE_SEGMENT.test(key)) {
+    throw new Error(
+      `repo ${JSON.stringify(key)} is not one of sessionManager.repos.entries: ` +
+        `${known.join(", ")}.`
+    );
+  }
+  const base = resolve(projectRoot);
+  const dir = resolve(base, repos.root ?? DEFAULT_REPOS_ROOT, key);
+  // `repos.root` is validated elsewhere, but this is the last step before a
+  // bypass-permissions launch, so it re-checks containment itself.
+  if (!dir.startsWith(`${base}${sep}`)) {
+    throw new Error(
+      `sessionManager.repos.root ${JSON.stringify(repos.root)} resolves ` +
+        `outside the project root.`
+    );
+  }
+  return dir;
+}

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/isolation.mjs

@@ -0,0 +1,130 @@
+/**
+ * Keeping one project's manager, bot and token apart from every other
+ * project's on the same machine.
+ *
+ * The manager's tmux session name and its Telegram state dir are both derived
+ * from a project slug. A slug taken from the repository name alone collides
+ * for two checkouts of one repository, or for two projects that share a
+ * folder name, and the collision is silent: the second project's `start`
+ * reports "already-running" about the first project's manager, which then
+ * dispatches the wrong project's work with bypass permissions. So:
+ * - the default slug carries a short hash of the real project root, and
+ * - before treating a running session as ours, the CLI asks tmux where that
+ *   session was started and compares real paths.
+ * @module session-manager/isolation
+ */
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+import { CliError, EXIT, run } from "./cli-runtime.mjs";
+import { buildHasSession, buildSessionPath } from "./launch.mjs";
+
+/** Characters of the repo name kept, so `<name>-<hash6>` fits in 56. */
+const SLUG_BASE_LENGTH = 49;
+
+/** Hex characters of the root hash in a default slug. */
+const ROOT_HASH_LENGTH = 6;
+
+/**
+ * The real path of `dir`, or its plain resolution when it does not exist.
+ * @param {string} dir - Directory
+ * @returns {string} Absolute path with symlinks resolved where possible
+ */
+export function realpathOr(dir) {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return path.resolve(dir);
+  }
+}
+
+/**
+ * The default project slug: the repo (or folder) name plus a stable hash of
+ * the real project root, `<name>-<hash6>`. The name is cut first so the hash
+ * always survives the 56-character slug limit `buildDefaultBlock` applies.
+ * @param {string} root - Absolute project root
+ * @param {string | undefined} repoName - `github.repo`, when configured
+ * @returns {string} Slug for `buildDefaultBlock`
+ */
+export function defaultProjectSlug(root, repoName) {
+  const base = String(repoName ?? path.basename(root)).slice(
+    0,
+    SLUG_BASE_LENGTH
+  );
+  const hash = createHash("sha256")
+    .update(realpathOr(root))
+    .digest("hex")
+    .slice(0, ROOT_HASH_LENGTH);
+  return `${base}-${hash}`;
+}
+
+/**
+ * Whether the manager's tmux session is running, and if so, that it is this
+ * project's. A session started anywhere else (or one tmux cannot place) is
+ * another project's manager under the same name, which is exit 2: neither
+ * "already running" nor "stopped" would be true.
+ * @param {{ root: string }} ctx - CLI context
+ * @param {string} name - Manager session name
+ * @param {Record<string, string | undefined>} env - Environment for tmux
+ * @returns {{ running: boolean, missing: boolean }} `missing` when tmux is
+ *   not on PATH
+ */
+export function probeOwnSession(ctx, name, env) {
+  const probe = run("tmux", buildHasSession(name), { env });
+  if (probe.missing) return { running: false, missing: true };
+  // probe-direction: fail-closed — a failed has-session reads as "not
+  // running", so `start` goes on to new-session, which tmux refuses for a
+  // duplicate name; it never reports someone else's session as ours.
+  if (probe.status !== 0) return { running: false, missing: false };
+  const where = run("tmux", buildSessionPath(name), { env }).stdout.trim();
+  if (where && realpathOr(where) === realpathOr(ctx.root)) {
+    return { running: true, missing: false };
+  }
+  const place = where
+    ? `was started in ${where}, not in ${ctx.root}`
+    : `is running, but tmux cannot say where it was started`;
+  throw new CliError(
+    `tmux session "${name}" ${place}. Another project is using the same ` +
+      `manager name: give this project its own sessionManager.name and ` +
+      `notify.stateDir (init-config derives unique ones), or stop that ` +
+      `project's manager from its own root.`,
+    EXIT.SETUP
+  );
+}
+
+/** How often the survival check asks tmux, in milliseconds. */
+const SURVIVAL_POLL_MS = 250;
+
+/**
+ * Wait `ms` milliseconds.
+ * @param {number} ms - Delay
+ * @returns {Promise<void>} Resolves after the delay
+ */
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+/**
+ * Whether a just-started manager session is still there after `settleMs`.
+ *
+ * tmux `new-session -d` succeeds as soon as the session exists, even when its
+ * command (claude) exits a moment later on a bad argv; tmux then closes the
+ * window and the session with it. So a check right after `new-session` proves
+ * nothing: this asks `has-session -t =<name>` every 250 ms for the whole
+ * window and returns false the first time the session is gone. Bounded by
+ * `settleMs`, which the caller caps.
+ * @param {string} name - Manager session name
+ * @param {Record<string, string | undefined>} env - Environment for tmux
+ * @param {number} settleMs - How long the session must survive
+ * @returns {Promise<boolean>} True when it was there at every check
+ */
+export async function sessionSurvives(name, env, settleMs) {
+  const checks = Math.max(1, Math.ceil(settleMs / SURVIVAL_POLL_MS));
+  const step = settleMs / checks;
+  for (let check = 0; check < checks; check += 1) {
+    await sleep(step);
+    // probe-direction: fail-closed — a failed has-session reads as "the manager
+    // died", so start refuses to report it as started.
+    if (run("tmux", buildHasSession(name), { env }).status !== 0) return false;
+  }
+  return true;
+}