@codyswann/lisa 4.80.2 → 4.81.0

package/plugins/lisa/.codex-plugin/skills/lisa-session-manager/scripts/workers.mjs

@@ -0,0 +1,406 @@
+/**
+ * Worker bookkeeping for the session manager: names, live detection, spawn
+ * argv and stall classification.
+ *
+ * A worker is a background Claude Code session (`claude --bg`) running
+ * `/lisa:implement <REF> managedBy=<manager>` for one work item. The manager
+ * never keeps a handle on a worker; it rediscovers every worker each cycle
+ * from `claude agents --json` by name. So the name is the join key between the
+ * tracker item, the ledger row and the live session, and everything here is
+ * about keeping that join exact.
+ *
+ * Every export is pure. `session-manager.mjs` owns the real `process.env`,
+ * `child_process` and clock, and passes them in.
+ * @module workers
+ */
+
+/** Settings blob every worker gets, so the manager's messages reach it. */
+export const WORKER_SETTINGS = JSON.stringify({
+  crossSessionInbound: "accept",
+});
+
+/**
+ * Stall policy used when the caller passes none. Mirrors the
+ * `sessionManager.stall` defaults, so a missing config block still classifies.
+ */
+export const DEFAULT_STALL = Object.freeze({
+  noOutputMinutes: 60,
+  requestionHours: 4,
+  maxAttempts: 3,
+});
+
+/** Every worker session name starts with this. Anything else is not ours. */
+const WORKER_PREFIX = "wk-";
+
+/**
+ * `wk-<token>-<MMDD>-<HHMM>[-<n>]`, read from the right. The token is greedy,
+ * so it is everything before the LAST stamp group: a ref whose number has four
+ * or more digits (`PROJ-1234`) or that itself ends in `-dddd-dddd` keeps its
+ * whole token. A lazy token read `wk-PROJ-1234-1012-1530` as `PROJ`, and the
+ * live-worker guard never fired. The collision suffix is capped at three
+ * digits so it can never be mistaken for the `HHMM` half of a stamp. The name
+ * is anchored so a token is compared exactly — never by `startsWith`, which
+ * would let an `ABC-12` worker answer for `ABC-1`.
+ */
+const WORKER_NAME_PATTERN = /^wk-(.+)-(\d{4}-\d{4})(?:-([1-9]\d{0,2}))?$/;
+
+/**
+ * `claude agents --json --all` states a finished row carries. Never enough on
+ * its own: an idle worker whose turn ended is alive but also reads `done`.
+ */
+const TERMINAL_AGENT_STATES = new Set(["done", "stopped"]);
+
+/** Ledger statuses that mean the worker reported its own outcome. */
+const FINISHED_STATUSES = new Set(["DONE", "FAILED"]);
+
+/** The `managedBy=` value contract `lisa-implement` enforces. */
+const MANAGER_NAME_PATTERN = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** A full session UUID, which `--resume` accepts directly. */
+const SESSION_UUID_PATTERN =
+  /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i;
+
+/** The short id `claude --bg` prints and `claude agents` lists. */
+const SHORT_ID_PATTERN = /\b[0-9a-f]{8}\b/i;
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+
+/**
+ * Reduce a work-item ref to the `[A-Za-z0-9-]` token used in worker names.
+ *
+ * A GitHub ref `owner/repo#12` becomes `repo-12`: the owner adds nothing
+ * inside one project and `/` and `#` are not safe in a session name. Jira and
+ * Linear keys already fit and pass through unchanged.
+ * @param {string} ref - Tracker ref as the queue reported it
+ * @returns {string} Name-safe token
+ */
+export function sanitizeRefToken(ref) {
+  if (typeof ref !== "string") {
+    throw new TypeError(`ref must be a string, got ${typeof ref}`);
+  }
+  const github = /^(?:[^/\s]+\/)?([^/#\s]*)#(\d+)$/.exec(ref.trim());
+  const raw = github ? [github[1], github[2]].filter(Boolean).join("-") : ref;
+  const token = raw
+    .replace(/[^A-Za-z0-9-]+/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-|-$/g, "");
+  if (token === "") {
+    throw new Error(`ref ${JSON.stringify(ref)} yields an empty worker token`);
+  }
+  return token;
+}
+
+/**
+ * Format a clock reading as local `MMDD-HHMM`.
+ * @param {Date | number} now - Clock reading
+ * @returns {string} Stamp
+ */
+function formatStamp(now) {
+  const date = now instanceof Date ? now : new Date(now);
+  const pad = value => String(value).padStart(2, "0");
+  return `${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}`;
+}
+
+/**
+ * Name a new worker for `ref`, unique against every name already known.
+ *
+ * A retry in the same minute would otherwise reuse the name of the worker it
+ * replaces, and `claude agents` could no longer tell them apart, so a
+ * collision gets `-2`, `-3`, ….
+ * @param {string} ref - Tracker ref
+ * @param {Date | number} now - Clock reading
+ * @param {Iterable<string>} [existingNames] - Every session name in use or on record
+ * @returns {string} Worker session name
+ */
+export function buildWorkerName(ref, now, existingNames = []) {
+  const known = new Set(existingNames);
+  const base = `${WORKER_PREFIX}${sanitizeRefToken(ref)}-${formatStamp(now)}`;
+  if (!known.has(base)) return base;
+  const suffix = Array.from(
+    { length: known.size + 1 },
+    (_, index) => index + 2
+  ).find(candidate => !known.has(`${base}-${candidate}`));
+  return `${base}-${suffix}`;
+}
+
+/**
+ * Split a worker session name into its parts.
+ * @param {string} name - Session name
+ * @returns {{token: string, stamp: string, suffix: number | null} | null} Parts, or null when the name is not a worker's
+ */
+export function parseWorkerName(name) {
+  const match =
+    typeof name === "string" ? WORKER_NAME_PATTERN.exec(name) : null;
+  if (!match) return null;
+  return {
+    token: match[1],
+    stamp: match[2],
+    suffix: match[3] === undefined ? null : Number(match[3]),
+  };
+}
+
+/**
+ * Read a value only when it is a string.
+ * @param {unknown} value - Candidate
+ * @returns {string | null} The string, or null
+ */
+function stringOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+
+/**
+ * Normalize `claude agents --json` output (with or without `--all`).
+ *
+ * The shapes differ: an active row carries `{pid,status}`; a completed row
+ * from `--all` carries `{id,state}` with `state` of `done` or `stopped` and no
+ * `pid` or `status`. Claude Code 2.1.296 also prints hybrids: an idle worker
+ * whose turn ended is `{pid,status:"idle",state:"done"}` while its process is
+ * alive, a worker waiting on a question is `state:"blocked"`, and a worker
+ * that has just been spawned is `{pid:null,status:null,state:"working"}`. So a
+ * row is alive when it has a pid or a status (the active shape) whatever its
+ * `state`, or when its state is not terminal; only a row with neither, in a
+ * terminal state, has finished. Reading `state` alone undercounted capacity,
+ * let `spawn` duplicate a live worker and made `classify` say `dead`.
+ * Every row comes back with all fields present (null when absent) and an
+ * `active` flag, so callers never branch on shape.
+ * @param {unknown} parsed - `JSON.parse` of the command's stdout
+ * @returns {Array<{name: string|null, sessionId: string|null, id: string|null, pid: number|null, cwd: string|null, kind: string|null, startedAt: number|null, status: string|null, state: string|null, active: boolean}>} Rows
+ */
+export function normalizeAgents(parsed) {
+  if (!Array.isArray(parsed)) {
+    throw new TypeError("claude agents --json must return an array");
+  }
+  return parsed
+    .filter(row => row !== null && typeof row === "object")
+    .map(row => {
+      const state = stringOrNull(row.state);
+      const pid = typeof row.pid === "number" ? row.pid : null;
+      const status = stringOrNull(row.status);
+      const activeShape = pid !== null || status !== null;
+      return {
+        name: stringOrNull(row.name),
+        sessionId: stringOrNull(row.sessionId),
+        id: stringOrNull(row.id),
+        pid,
+        cwd: stringOrNull(row.cwd),
+        kind: stringOrNull(row.kind),
+        startedAt: typeof row.startedAt === "number" ? row.startedAt : null,
+        status,
+        state,
+        active:
+          activeShape || state === null || !TERMINAL_AGENT_STATES.has(state),
+      };
+    });
+}
+
+/**
+ * Whether a normalized row is a running worker.
+ * @param {{active: boolean, name: string|null}} agent - Normalized row
+ * @returns {boolean} True for an active `wk-` session
+ */
+function isRunningWorker(agent) {
+  return agent.active && parseWorkerName(agent.name) !== null;
+}
+
+/**
+ * Count running workers, the `running` input to capacity.
+ * @param {ReturnType<typeof normalizeAgents>} agents - Normalized rows
+ * @returns {number} Active `wk-` sessions
+ */
+export function countRunningWorkers(agents) {
+  return agents.filter(isRunningWorker).length;
+}
+
+/**
+ * Find the running worker for `ref`, by exact token.
+ * @param {ReturnType<typeof normalizeAgents>} agents - Normalized rows
+ * @param {string} ref - Tracker ref
+ * @returns {ReturnType<typeof normalizeAgents>[number] | null} The row, or null
+ */
+export function findLiveWorker(agents, ref) {
+  const token = sanitizeRefToken(ref);
+  return (
+    agents.find(
+      agent =>
+        isRunningWorker(agent) && parseWorkerName(agent.name)?.token === token
+    ) ?? null
+  );
+}
+
+/**
+ * Copy an environment without any `TELEGRAM_*` key.
+ *
+ * The manager runs with `TELEGRAM_STATE_DIR` (and possibly
+ * `TELEGRAM_BOT_TOKEN`) set. A worker that inherited either could start a
+ * second poller on the same bot and take the manager's messages, so every
+ * `TELEGRAM_*` key goes — a superset of the two that matter today.
+ * @param {Record<string, string | undefined>} env - Source environment
+ * @returns {Record<string, string | undefined>} New environment
+ */
+export function scrubWorkerEnv(env) {
+  return Object.fromEntries(
+    Object.entries(env).filter(([key]) => !key.startsWith("TELEGRAM_"))
+  );
+}
+
+/**
+ * Throw unless `value` is a non-empty string.
+ * @param {string} label - Field name for the message
+ * @param {unknown} value - Candidate
+ */
+function requireText(label, value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+}
+
+/**
+ * Build the spawn for a new worker. Passed as argv to `spawnSync`, never a
+ * shell string, so no ref or name is ever interpreted by a shell.
+ *
+ * The prompt is exactly `/lisa:implement <REF> managedBy=<manager>`: any
+ * trailing prose would make `lisa-track` classify the arguments as free text.
+ * @param {{ref: string, name: string, manager: string, repoDir: string, env: Record<string, string | undefined>}} input - Spawn inputs
+ * @returns {{command: string, args: string[], cwd: string, env: Record<string, string | undefined>}} Spawn spec
+ */
+export function buildWorkerSpawn({ ref, name, manager, repoDir, env }) {
+  requireText("ref", ref);
+  if (/\s/.test(ref)) {
+    throw new Error(`ref ${JSON.stringify(ref)} must not contain whitespace`);
+  }
+  if (typeof manager !== "string" || !MANAGER_NAME_PATTERN.test(manager)) {
+    throw new Error(
+      `manager ${JSON.stringify(manager)} must match ${MANAGER_NAME_PATTERN}`
+    );
+  }
+  if (parseWorkerName(name) === null) {
+    throw new Error(`name ${JSON.stringify(name)} is not a worker name`);
+  }
+  requireText("repoDir", repoDir);
+  return {
+    command: "claude",
+    args: [
+      "--bg",
+      "-n",
+      name,
+      "--dangerously-skip-permissions",
+      "--settings",
+      WORKER_SETTINGS,
+      `/lisa:implement ${ref} managedBy=${manager}`,
+    ],
+    cwd: repoDir,
+    env: scrubWorkerEnv(env),
+  };
+}
+
+/**
+ * Build the spawn that resumes a worker with one message (an answer, or a
+ * nudge after a stall), with the same cwd and environment scrub as a spawn.
+ * @param {{sessionId: string, text: string, repoDir: string, env: Record<string, string | undefined>}} input - Resume inputs
+ * @returns {{command: string, args: string[], cwd: string, env: Record<string, string | undefined>}} Spawn spec
+ */
+export function buildWorkerResume({ sessionId, text, repoDir, env }) {
+  requireText("sessionId", sessionId);
+  if (sessionId.startsWith("-")) {
+    throw new Error(
+      `sessionId ${JSON.stringify(sessionId)} must not look like a flag`
+    );
+  }
+  requireText("text", text);
+  requireText("repoDir", repoDir);
+  return {
+    command: "claude",
+    // `--` ends option parsing: an answer that starts with `--` (claude
+    // 2.1.296 reads `--x` there as an unknown option) stays message text.
+    args: ["--bg", "--resume", sessionId, "--", text],
+    cwd: repoDir,
+    env: scrubWorkerEnv(env),
+  };
+}
+
+/**
+ * Pull the session id out of `claude --bg` stdout. A full UUID wins; else the
+ * short id `claude --bg` prints. The manager can always map either back to
+ * the full `sessionId` through `claude agents --json` by worker name.
+ * @param {string} stdout - Command output
+ * @returns {string | null} Session id, or null
+ */
+export function parseSessionId(stdout) {
+  const text = typeof stdout === "string" ? stdout : "";
+  return (
+    SESSION_UUID_PATTERN.exec(text)?.[0] ??
+    SHORT_ID_PATTERN.exec(text)?.[0] ??
+    null
+  );
+}
+
+/**
+ * Read a timestamp that may be an ISO string, epoch milliseconds or a Date.
+ * @param {unknown} value - Candidate
+ * @returns {number | null} Epoch milliseconds, or null
+ */
+function toMillis(value) {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  return null;
+}
+
+/**
+ * Classify one dispatched item for this cycle.
+ *
+ * Order matters: a recorded DONE/FAILED wins; a pending question means the
+ * worker ended its turn on purpose, so it is `waiting` even when its row
+ * reads `done`; only then is liveness judged. `stalled` and `dead` become
+ * `exhausted` at `maxAttempts`, which is the manager's cue to move the item to
+ * Blocked instead of retrying it again.
+ * @param {{agent: ReturnType<typeof normalizeAgents>[number] | null, entry: {status?: string, startedAt?: string|number, lastProgressAt?: string|number|null, logsHash?: string|null, pendingQuestion?: {askedAt?: string|number, lastPingAt?: string|number|null} | null, attempts?: number}, logsHash?: string | null | undefined, now: Date | number, stall?: {noOutputMinutes: number, requestionHours: number, maxAttempts: number}}} input - Classification inputs
+ * @returns {"finished"|"waiting"|"requestion"|"working"|"stalled"|"dead"|"exhausted"} Classification
+ */
+export function classifyWorker({
+  agent,
+  entry,
+  logsHash,
+  now,
+  stall = DEFAULT_STALL,
+}) {
+  if (FINISHED_STATUSES.has(entry.status ?? "")) return "finished";
+  const nowMs = toMillis(now) ?? 0;
+  const question = entry.pendingQuestion;
+  if (question) {
+    const lastPing =
+      toMillis(question.lastPingAt) ?? toMillis(question.askedAt) ?? nowMs;
+    return nowMs - lastPing > stall.requestionHours * HOUR_MS
+      ? "requestion"
+      : "waiting";
+  }
+  const outcome = agent?.active
+    ? judgeActive(entry, logsHash, nowMs, stall)
+    : "dead";
+  if (outcome !== "working" && (entry.attempts ?? 0) >= stall.maxAttempts) {
+    return "exhausted";
+  }
+  return outcome;
+}
+
+/**
+ * Decide whether an active worker is making progress.
+ * @param {{logsHash?: string|null, lastProgressAt?: string|number|null, startedAt?: string|number}} entry - Ledger row
+ * @param {string | null | undefined} logsHash - This cycle's hash of `claude logs <name>`
+ * @param {number} nowMs - Clock reading
+ * @param {{noOutputMinutes: number}} stall - Stall policy
+ * @returns {"working"|"stalled"} Classification
+ */
+function judgeActive(entry, logsHash, nowMs, stall) {
+  if (typeof logsHash === "string" && logsHash !== entry.logsHash)
+    return "working";
+  const lastProgress =
+    toMillis(entry.lastProgressAt) ?? toMillis(entry.startedAt) ?? nowMs;
+  return nowMs - lastProgress <= stall.noOutputMinutes * MINUTE_MS
+    ? "working"
+    : "stalled";
+}

package/plugins/lisa/.codex-plugin/skills/lisa-setup-session-manager/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: lisa-setup-session-manager
+description: "Set up the local session…"
+allowed-tools: ["Bash", "Read", "Write", "Skill", "AskUserQuestion"]
+---
+Set up the local session manager for this project: writes the non-secret `sessionManager` block to `.lisa.config.json` (detecting a multi-repo `projects/*` layout), stores the project's own Telegram bot token outside the repo, checks the Telegram plugin is installed but not enabled at user scope, keeps the manager's state out of git, seeds the checked-in runbook, starts the manager in tmux, walks the operator through pairing, and finishes with doctor's session-manager check. Idempotent.
+
+
+# Setup session manager
+
+After this skill the project has a `sessionManager` block, a bot token in its own state directory, a
+runbook at `.lisa/automations/session-manager.runbook.md`, and a running manager paired with the
+operator's Telegram chat. Re-running is safe: every step keeps what is already there.
+
+The manager itself always runs on Claude Code (see `lisa-session-manager` "Runtime parity"). Setup
+can run from any agent that can reach the scripts; `start` launches the Claude Code manager.
+
+## Step 0: Preconditions
+
+Stop with the named gap if any of these fail:
+
+- **Tracker configured.** `.tracker` in `.lisa.config.json` is `github`, `jira` or `linear`.
+  Otherwise stop: "No tracker configured. Run the matching /lisa:setup:<tracker> first."
+- **Tools.** `claude --version` is at least 2.1.224; `tmux -V` and `bun --version` succeed. Name the
+  missing or outdated tool and stop.
+
+## Step 1: Locate the scripts
+
+Resolve the scripts directory with the same ladder as `lisa-session-manager`:
+
+```bash
+SM="${SM_SCRIPTS_DIR:-}"
+[ -z "$SM" ] && [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && SM="$CLAUDE_PLUGIN_ROOT/skills/lisa-session-manager/scripts"
+[ -n "$SM" ] && [ -f "$SM/session-manager.mjs" ] || SM="$(claude plugin list --json 2>/dev/null | node -e 'let s="";process.stdin.on("data",d=>{s+=d}).on("end",()=>{let l=[];try{l=JSON.parse(s)}catch{}const c=l.filter(p=>String(p.id).startsWith("lisa@"));const p=c.find(p=>p.projectPath===process.cwd())||c.find(p=>p.scope==="user");process.stdout.write(p?p.installPath:"")})')/skills/lisa-session-manager/scripts"
+[ -f "$SM/session-manager.mjs" ] || SM="$PWD/node_modules/@codyswann/lisa/plugins/lisa/skills/lisa-session-manager/scripts"
+[ -f "$SM/session-manager.mjs" ] || { echo "lisa-session-manager scripts not found" >&2; exit 1; }
+echo "$SM"
+```
+
+Shell variables do not survive between Bash calls: use the printed absolute path wherever this skill
+writes `$SM`, and pass `--project-root "$ROOT"` (the absolute project root) on every call.
+
+## Step 2: Write the config block
+
+1. Preview: `node "$SM/session-manager.mjs" init-config --project-root "$ROOT"`. It detects
+   `projects/*/.lisa.config.json` and proposes `name`, `interval`, `repos`, `capacity`, `stall` and a
+   per-project `notify.stateDir`. Show the block to the operator.
+2. Write it: the same command with `--write`. It adds only non-secret fields and never overwrites an
+   existing block (`reason: "exists"` means keep it).
+3. Ask the operator to replace each repo's starter `hints` with the technologies and areas that
+   identify it (e.g. `api`: `["NestJS","migrations"]`, `web`: `["Expo","screens"]`), and whether to
+   set `sessionManager.trustedAuthorIds`. Without it, any author's Ready item reaches a
+   bypass-permissions worker; say so plainly. The list holds stable tracker user ids as strings,
+   never logins: the GitHub numeric user id (`gh api users/<login> --jq .id`), the Jira
+   `accountId`, or the Linear user id. A login matches no one and silently excludes every item.
+4. `node "$SM/session-manager.mjs" validate --project-root "$ROOT"` must print `valid: true`.
+
+## Step 3: Store the bot token
+
+The operator creates a bot with @BotFather, one per project. Then run
+`node "$SM/session-manager.mjs" store-token --project-root "$ROOT"`.
+
+- `stored: true`: done.
+- Exit 2 because a token already exists: keep it (re-running setup is safe). Only when the operator
+  says the stored token is wrong or belongs to another project, re-run with `store-token --replace`.
+- `reason: "no-tty"` (an agent's Bash has no terminal): print `command` from the output and ask the
+  operator to run it in their own terminal, where it prompts with echo off. Wait for them to confirm.
+- `empty` / `invalid`: say what was wrong and ask again.
+
+Never ask for the token in chat, never echo, log or commit it, and never put it in
+`.lisa.config.json`. It lives only in `<notify.stateDir>/.env`.
+
+## Step 4: Telegram plugin scope
+
+Read `claude plugin list --json` and look at the `telegram@claude-plugins-official` entries.
+
+- **Not installed:** ask the operator to install it with
+  `claude plugin install telegram@claude-plugins-official -s user`, then re-check.
+- **Enabled at user scope** (`scope: "user"` and `enabled: true`): every session on this machine
+  would start its own poller and take the bot away from the manager. Print the remedy and stop until
+  it is fixed:
+
+  ```bash
+  claude plugin disable telegram@claude-plugins-official -s user
+  ```
+
+- **Installed and not enabled at user scope:** correct. The manager enables it for itself only.
+
+## Step 5: Keep manager state out of git
+
+At the project root, when it is a git repo:
+`git check-ignore -q .lisa/session-manager/ledger.json || printf '%s\n' '.lisa/session-manager/' >> "$(git rev-parse --git-common-dir)/info/exclude"`,
+then re-run `git check-ignore -q .lisa/session-manager/ledger.json`. If it is still not ignored, stop
+and report. A root that is not a git repo needs nothing.
+
+## Step 6: Seed the runbook
+
+If `.lisa/automations/session-manager.runbook.md` does not exist, copy
+`$SM/../references/runbook-template.md` there. Never overwrite an existing runbook: it is the
+project's. It is checked in, like every automation runbook (`automation-runbook-contract`).
+
+## Step 7: Coexistence warning
+
+Tell the operator, before starting: if this project also runs the scheduled `intake-repair` loop, it
+can re-dispatch an item a local worker is still building (it treats a claimed item with no tracker
+activity for `intake.repair.staleAfterHours` as stalled). `intake-tickets` competes for the same
+Ready items. Recommend tearing down `intake-tickets` (`/lisa:tear-down-automations intake-tickets`)
+and either raising `intake.repair.staleAfterHours` above `stall.noOutputMinutes × stall.maxAttempts`
+or tearing down `intake-repair`.
+
+## Step 8: Accept workspace trust in each worker repo
+
+Workers are background sessions, and a background session cannot show Claude Code's "trust this
+folder?" prompt: until someone has accepted it in a directory, `claude --bg` refuses to start there
+and `spawn` exits 2 saying so. Do this once per routed repo (or once for the root on a single-repo
+project), on every machine that runs the manager:
+
+1. List the directories workers start in. Single-repo: the project root. Multi-repo: for each key in
+   `sessionManager.repos.entries`,
+   `node "$SM/session-manager.mjs" repo-dir --repo <key> --raw --project-root "$ROOT"`.
+2. Ask the operator, in their own terminal, to run `claude` once in that directory,
+   accept the trust prompt, then exit. An agent's Bash cannot answer that prompt, so never try to
+   accept it for them.
+3. Re-run this step whenever a repo is added to `sessionManager.repos`.
+
+## Step 9: Start and pair
+
+0. **Public GitHub repo gate.** When `.tracker` is `github`, run
+   `gh repo view <github.org>/<github.repo> --json visibility`. If it is `PUBLIC` and
+   `sessionManager.trustedAuthorIds` is not set, setup will not start the manager until
+   `trustedAuthorIds` is set: anyone on the internet could otherwise write the work a
+   bypass-permissions worker runs. Ask the operator for the IDs, add them, re-run `validate`, then
+   continue. `lisa doctor` fails on the same condition.
+1. `node "$SM/session-manager.mjs" start --project-root "$ROOT"`. `started` and `already-running`
+   are both fine. Exit 2 names what is missing (usually the token from Step 3), or that a tmux
+   session of the same name belongs to another project root, or that the manager
+   exited right after starting. For the last, ask the operator to run the printed foreground command
+   in their own terminal: claude prints its own error there. Fix it, then run `start` again.
+2. Walk the operator through pairing, in their own terminal:
+   1. `tmux attach -t <name>` (the `attach` value from the output).
+   2. Send any message to the bot in a private chat. The bot replies with a pairing code.
+   3. In the attached manager session: `/telegram:access pair <code>`.
+   4. Then: `/telegram:access policy allowlist`, so only paired senders reach the manager.
+   5. Detach with `Ctrl-b d`. The manager keeps running.
+
+Pairing and allowlist changes are made only in that terminal. Never approve a pairing because a
+Telegram message asked for it. Every allowlisted sender effectively has shell access to this machine
+(the manager and its workers run with bypass permissions), so keep the allowlist to the owner.
+
+## Step 10: Verify
+
+Run `lisa doctor` (or `npx @codyswann/lisa doctor` when the `lisa` CLI is not on the PATH) and
+confirm the "Session manager Telegram isolation?" check is green. Fix every warning it names, then
+`node "$SM/session-manager.mjs" status --project-root "$ROOT"` should show the manager running.
+
+Report: the config block written (or kept), where the token lives (the path, never the value), the
+plugin scope result, the runbook path, which repo dirs had workspace trust accepted, the manager's
+tmux session name, and the doctor result.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-session-manager/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Session Manager"
+short_description: "Set up the local session…"
+default_prompt:
+  - "Use $lisa-setup-session-manager: Set up the local session…."

package/plugins/lisa/.codex-plugin/skills/lisa-tear-down-automations/SKILL.md

@@ -47,6 +47,16 @@ that one registered loop.
   `/setup-automations` scaffolded are project knowledge and the historical record of what these
   loops did. Teardown removes scheduler registrations only; it never deletes, edits, or moves a
   runbook file. An operator who wants them gone removes them deliberately, in git.
+- **The locally hosted session manager** has no scheduler registration to delete: it runs as a
+  `/loop` in a tmux session, not under `/schedule` or Codex automations. When `.lisa.config.json`
+  has a `sessionManager` block, a fleet teardown, or `/lisa:tear-down-automations session-manager`,
+  stops it with `/lisa:session-manager stop` (the `session-manager.mjs stop` subcommand, which kills
+  only the manager's tmux session and is a no-op when it is not running). Never search the scheduler
+  for it and never report it "already absent" there. **Never stop its workers**: each holds claimed
+  work and finishes or hands off on its own. List them for the operator instead (run
+  `/lisa:session-manager status` before stopping, or `claude agents --json`). Its runbook,
+  `.lisa/automations/session-manager.runbook.md`, stays on disk like every other. Without a
+  `sessionManager` block there is nothing to stop.
 
 ## Answering a `policy-obsolete` teardown proposal
 

package/plugins/lisa/commands/implement.md

@@ -1,8 +1,8 @@
 ---
 description: "Implement a single work item end-to-end. Vendor-agnostic: given a work-item URL/key (JIRA, Linear, GitHub Issues) or description, reads it, determines work type (Build/Fix/Improve/Investigate), assembles an agent team, runs the full lifecycle through PR + evidence. Pass executionEnv=codex-cloud to run the work on a remote surface instead of locally — it submits and returns without polling, so the laptop is a launcher rather than the execution substrate. For batch processing of all Status=Ready tickets in a queue, use /lisa:intake instead."
-argument-hint: "[executionEnv=local|codex-cloud] <single-work-item-url | key | description>"
+argument-hint: "[executionEnv=local|codex-cloud] [managedBy=<session-name>] <single-work-item-url | key | description>"
 ---
 
 Use the /lisa-implement skill to take the work item from spec to shipped: read the source, determine work type, assemble an agent team, and run the full lifecycle through PR creation, code review, deploy, and empirical verification.
 
-If `$ARGUMENTS` carries `executionEnv=` with anything other than `local`, route the work to that surface via /lisa-remote-dispatch and report the recorded task identifier instead of running the lifecycle locally. $ARGUMENTS
+If `$ARGUMENTS` carries both `managedBy=` and a non-`local` `executionEnv=`, do not dispatch: stop with "managedBy requires a local Claude Code session; remote surfaces cannot reach the manager." Otherwise, if `$ARGUMENTS` carries `executionEnv=` with anything other than `local`, route the work to that surface via /lisa-remote-dispatch and report the recorded task identifier instead of running the lifecycle locally. `managedBy=<session-name>` sends every question and the final DONE/FAILED status to that Claude Code session instead of the terminal. $ARGUMENTS

package/plugins/lisa/commands/session-manager.md

@@ -0,0 +1,7 @@
+---
+description: "Run the local session manager: one dispatch-and-relay cycle (the /loop prompt), or start, stop or show the tmux-hosted manager. Dispatches Ready work items to fresh background worker sessions and relays their questions over the project's Telegram bot. Claude Code only; configure it with /lisa:setup:session-manager."
+allowed-tools: ["Skill"]
+argument-hint: "[cycle|start|stop|status]"
+---
+
+Use the /lisa-session-manager skill to run one manager cycle or to start, stop or report on the manager. $ARGUMENTS

package/plugins/lisa/commands/setup/session-manager.md

@@ -0,0 +1,6 @@
+---
+description: "Set up the local session manager for this project: write the sessionManager config block, store the project's own Telegram bot token, check the Telegram plugin scope, seed the runbook, start the manager in tmux, walk through pairing, and run doctor's session-manager check."
+allowed-tools: ["Skill"]
+---
+
+Use the /lisa-setup-session-manager skill to set up and start the session manager for this project. $ARGUMENTS

package/plugins/lisa/rules/reference/automation-runbook-contract.md

@@ -21,6 +21,20 @@ Membership is **registration, not skill-existence**: a loop is under this contra
 registered as a scheduled automation, and registering a new one pulls it in automatically. There is
 no hardcoded roster of loops anywhere.
 
+### Locally hosted loops
+
+A loop the runtime's scheduler does not host is still a member. The session manager
+(`lisa-session-manager`) is the case: its registration is the tmux session
+`/lisa:setup:session-manager` starts, running a `/loop`, not a `/schedule` routine or a Codex
+automation. It is a member exactly when `.lisa.config.json` has a `sessionManager` block. It keeps
+the same obligations as a scheduled loop: a checked-in runbook at
+`.lisa/automations/session-manager.runbook.md`, one of the six outcomes per cycle, and a run record
+written through `automation-run-record.mjs` under loop id `session-manager`. Only the scheduler-facing
+surfaces differ. `lisa-automation-status` lists it `UNSUPPORTED`, with a reason naming the tmux
+session, because no scheduler can see it, and still shows its runbook and recorded cycles.
+`lisa-tear-down-automations` stops the tmux session instead of deleting a scheduler entry, never
+stops its workers, and leaves the runbook.
+
 ### Interactive flows are members too
 
 The outcome vocabulary is **not cron-specific** — it answers "did this need me?", which an operator