@codyswann/lisa 4.80.1 → 4.81.0

package/plugins/src/base/skills/lisa-session-manager/scripts/reconcile.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * The session manager's decision for one Blocked item: release it to Ready,
+ * keep it, escalate it, or leave it to a human.
+ *
+ * ## Why this composes rather than decides
+ *
+ * Two shared modules already own the hard questions, and both exist because a
+ * local re-implementation went wrong. `humanGateVerdict` is the only answer to
+ * "is a person holding this?" — a label-only reader promoted held items
+ * (#3805) — and it is the only place a hold ends, honouring only a release
+ * from a trusted human actor. `resolveBlockerEdges` is the only answer to "is
+ * this dependency satisfied?" — containment, never closure, and a NOT_PLANNED
+ * blocker escalates instead of dissolving (#3472). This module imports both
+ * and adds only the precedence between them, so the manager can never drift
+ * from repair-intake's Class A ruling.
+ *
+ * ## Scope
+ *
+ * Only dependency blocks (Class A) and the manager's own pending questions.
+ * An item blocked with no dependency edges is a gate self-block or a
+ * clarification block (Class B/C); those belong to repair-intake and humans,
+ * so this plan keeps them rather than guessing. The plan is pure: the caller
+ * reads the item and computes containment, then performs the writes.
+ * @module session-manager/reconcile
+ */
+
+import { resolveBlockerEdges } from "../../../scripts/blocker-edge-resolution.mjs";
+import { humanGateVerdict } from "../../../scripts/intake-blocker-reprobe.mjs";
+
+/** Every action the plan may return. */
+export const BLOCKED_RELEASE_ACTIONS = Object.freeze([
+  "release",
+  "keep",
+  "escalate",
+  "skip-human-gate",
+]);
+
+/**
+ * Plan what to do with one Blocked item.
+ *
+ * Precedence, first match wins: a held human gate (`skip-human-gate`), a
+ * pending manager question (`keep`), no edges (`keep`), every edge dissolves
+ * (`release`), any edge escalates (`escalate`), otherwise `keep`.
+ *
+ * `edges` carries the per-edge decisions — each input edge plus its `action`
+ * and `reason` — so the caller can quote them in the explanatory tracker
+ * comment. It is empty when the edges were never judged.
+ * @param {{
+ *   labels?: unknown,
+ *   body?: unknown,
+ *   comments?: unknown,
+ *   trustedHumanActorIds?: unknown,
+ *   humanNeededLabel?: unknown,
+ *   edges?: readonly object[] | null | undefined,
+ *   pendingQuestion?: unknown,
+ * }} [input] The item's hold surfaces, its judged edges, and the ledger question.
+ * @returns {{
+ *   action: string,
+ *   reason: string,
+ *   edges: {action: string, reason: string}[],
+ *   gate: ReturnType<typeof humanGateVerdict>,
+ * }} The decision, why, and the evidence behind it.
+ */
+export function planBlockedRelease(input = {}) {
+  const gate = humanGateVerdict({
+    labels: input.labels,
+    body: input.body,
+    comments: input.comments,
+    trustedHumanActorIds: input.trustedHumanActorIds,
+    humanNeededLabel: input.humanNeededLabel,
+  });
+
+  if (gate.held) {
+    return {
+      action: "skip-human-gate",
+      reason:
+        "a person is holding this item and no trusted human has released it, so its edges are " +
+        "not the manager's to judge.",
+      edges: [],
+      gate,
+    };
+  }
+
+  if (input.pendingQuestion) {
+    return {
+      action: "keep",
+      reason:
+        "the manager is still waiting on an answer to its question about this item.",
+      edges: [],
+      gate,
+    };
+  }
+
+  const edges = Array.isArray(input.edges) ? input.edges : [];
+  if (edges.length === 0) {
+    return {
+      action: "keep",
+      reason:
+        "the item has no dependency edges, so it is a gate or clarification block; those are left " +
+        "to repair-intake and humans.",
+      edges: [],
+      gate,
+    };
+  }
+
+  const resolution = resolveBlockerEdges(edges);
+  if (resolution.proceed) {
+    return {
+      action: "release",
+      reason:
+        "every blocker's code is on the branch this item builds from, so each edge dissolves.",
+      edges: resolution.decisions,
+      gate,
+    };
+  }
+
+  if (resolution.escalations > 0) {
+    return {
+      action: "escalate",
+      reason: `${resolution.escalations} of ${edges.length} blocker edge(s) need a human decision.`,
+      edges: resolution.decisions,
+      gate,
+    };
+  }
+
+  return {
+    action: "keep",
+    reason:
+      "at least one blocker has not shipped to the branch this item builds from.",
+    edges: resolution.decisions,
+    gate,
+  };
+}

package/plugins/src/base/skills/lisa-session-manager/scripts/session-manager.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * The session manager's one entrypoint: every skill call goes through here.
+ *
+ * It parses argv, builds one context, runs a subcommand and maps the outcome
+ * to an exit code the manager skill branches on (0 ok, 1 failure, 2 bad repo
+ * or config, 3 no capacity, 4 live worker). The logic lives in the pure
+ * modules beside it; this file only wires real seams into them.
+ *
+ * The real environment is read in exactly one place, the call at the bottom
+ * of this file. It is passed down as `ctx.env`, and every child that could be
+ * a worker or could host one gets it through `scrubWorkerEnv`, which drops
+ * every `TELEGRAM_*` key. Children are started with argv arrays, never a shell
+ * string, and untrusted text arrives on stdin, so a ticket title or a
+ * Telegram message can never become shell syntax.
+ *
+ * Runtime parity: the manager PROCESS is always Claude Code, because it needs
+ * background sessions (`claude --bg`, `claude agents`), cross-session
+ * messaging and channels, which no other supported agent has. Codex, Cursor,
+ * OpenCode, Antigravity, Copilot and Devin can run the setup-time subcommands
+ * (init-config, store-token, validate, start), and `start` hosts a Claude Code
+ * manager in tmux whatever agent ran it; they cannot run a manager cycle
+ * themselves. OpenCode copies skill folders without the plugin-level
+ * `scripts/` directory, so `queue` and `record-cycle` (which import from it)
+ * are unavailable there unless the npm package provides that directory.
+ * @module session-manager
+ */
+import { readFileSync, realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+import {
+  LEDGER_ACTION_NAMES,
+  blockedPlan,
+  ledger,
+  recordCycle,
+  route,
+} from "./cli-cycle.mjs";
+import {
+  initConfig,
+  repoDir,
+  start,
+  status,
+  stop,
+  storeToken,
+  validate,
+} from "./cli-manager.mjs";
+import { queue } from "./cli-queue.mjs";
+import { CliError, EXIT } from "./cli-runtime.mjs";
+import { USAGE } from "./cli-usage.mjs";
+import { capacity, classify, resume, spawn } from "./cli-workers.mjs";
+
+const text = { type: "string" };
+const flag = { type: "boolean" };
+const MEASURE = { "max-workers": text, meminfo: text };
+
+/** Each subcommand: handler, accepted flags, and how many positionals. */
+const COMMANDS = {
+  capacity: { run: capacity, options: MEASURE, positionals: 0 },
+  spawn: { run: spawn, options: { ...MEASURE, repo: text }, positionals: 1 },
+  resume: { run: resume, options: {}, positionals: 1 },
+  classify: { run: classify, options: {}, positionals: 1 },
+  status: { run: status, options: {}, positionals: 0 },
+  start: { run: start, options: { "settle-ms": text }, positionals: 0 },
+  stop: { run: stop, options: {}, positionals: 0 },
+  "store-token": {
+    run: storeToken,
+    options: { replace: flag },
+    positionals: 0,
+  },
+  "repo-dir": {
+    run: repoDir,
+    options: { repo: text, raw: flag },
+    positionals: 0,
+  },
+  validate: { run: validate, options: {}, positionals: 0 },
+  "init-config": {
+    run: initConfig,
+    options: { slug: text, write: flag },
+    positionals: 0,
+  },
+  queue: {
+    run: queue,
+    options: {
+      tracker: text,
+      input: text,
+      me: text,
+      label: text,
+      "github-repo": text,
+    },
+    positionals: 0,
+  },
+  ledger: { run: ledger, options: {}, positionals: 0 },
+  route: {
+    run: route,
+    options: { "reply-to": text, owner: text },
+    positionals: 0,
+  },
+  "blocked-plan": {
+    run: blockedPlan,
+    options: { input: text, ref: text },
+    positionals: 0,
+  },
+  "record-cycle": {
+    run: recordCycle,
+    options: {
+      outcome: text,
+      ref: { ...text, multiple: true },
+      "run-id": text,
+    },
+    positionals: 0,
+  },
+};
+
+/** Flags and positionals for each `ledger <action>`. */
+const LEDGER_SPECS = {
+  get: { options: {}, positionals: 1 },
+  "record-spawn": {
+    options: { worker: text, "session-id": text, repo: text },
+    positionals: 1,
+  },
+  "set-question": {
+    options: { "telegram-message-id": text, sender: text },
+    positionals: 1,
+  },
+  "clear-question": { options: {}, positionals: 1 },
+  finish: { options: { status: text, sender: text }, positionals: 1 },
+  control: {
+    options: { paused: text, "max-workers": text, me: text },
+    positionals: 0,
+  },
+};
+
+const COMMON = { "project-root": text, help: { ...flag, short: "h" } };
+
+/**
+ * Resolve the subcommand (and ledger action) and parse its argv strictly.
+ * @param {string[]} argv - Arguments after the script path
+ * @returns {{ command: object, action: string | undefined,
+ *   values: Record<string, any>, positionals: string[] }} Parsed call
+ */
+function parseCall(argv) {
+  const [name, ...rest] = argv;
+  const command = Object.hasOwn(COMMANDS, name) ? COMMANDS[name] : null;
+  if (!command) throw new CliError(`Unknown subcommand "${name}".`, EXIT.SETUP);
+  const isLedger = name === "ledger";
+  const action = isLedger ? rest.shift() : undefined;
+  if (isLedger && !LEDGER_ACTION_NAMES.includes(action ?? "")) {
+    throw new CliError(
+      `ledger needs one of: ${LEDGER_ACTION_NAMES.join(", ")}.`,
+      EXIT.SETUP
+    );
+  }
+  const spec = isLedger ? LEDGER_SPECS[action] : command;
+  const { values, positionals } = parseArgs({
+    args: rest,
+    options: { ...COMMON, ...spec.options },
+    allowPositionals: true,
+    strict: true,
+  });
+  if (positionals.length > spec.positionals) {
+    throw new CliError(
+      `Unexpected argument "${positionals[spec.positionals]}".`,
+      EXIT.SETUP
+    );
+  }
+  return { command, action, values, positionals };
+}
+
+/**
+ * The project root: `--project-root` (absolute), else the cwd.
+ * @param {string | undefined} value - Flag value
+ * @returns {string} Absolute root
+ */
+function projectRoot(value) {
+  if (value === undefined) return process.cwd();
+  if (!path.isAbsolute(value)) {
+    throw new CliError("--project-root must be an absolute path.", EXIT.SETUP);
+  }
+  return path.resolve(value);
+}
+
+/**
+ * Read all of stdin. Refuses an interactive terminal rather than waiting on
+ * a read nobody will answer.
+ * @returns {string} stdin contents
+ */
+function readStdin() {
+  if (process.stdin.isTTY) {
+    throw new CliError("Pipe the input on stdin.", EXIT.SETUP);
+  }
+  return readFileSync(0, "utf8");
+}
+
+/**
+ * Run one CLI call.
+ * @param {string[]} argv - Arguments after the script path
+ * @param {{ env: Record<string, string | undefined> }} seams - The real
+ *   environment, read once by the caller
+ * @returns {Promise<number>} Exit code
+ */
+async function main(argv, { env }) {
+  const out = chunk => process.stdout.write(chunk);
+  const warn = message => process.stderr.write(`${message}\n`);
+  try {
+    if (argv.length === 0 || ["help", "--help", "-h"].includes(argv[0])) {
+      out(USAGE);
+      return EXIT.OK;
+    }
+    const { command, action, values, positionals } = parseCall(argv);
+    if (values.help) {
+      out(USAGE);
+      return EXIT.OK;
+    }
+    const result = await command.run({
+      root: projectRoot(values["project-root"]),
+      env,
+      values,
+      positionals,
+      action,
+      platform: process.platform,
+      homedir: os.homedir(),
+      scriptsDir: path.dirname(fileURLToPath(import.meta.url)),
+      now: () => new Date(),
+      readStdin,
+      warn,
+    });
+    if (result.text !== undefined) out(result.text);
+    if (result.json !== undefined) out(`${JSON.stringify(result.json)}\n`);
+    return result.exitCode ?? EXIT.OK;
+  } catch (error) {
+    if (error?.json !== undefined) out(`${JSON.stringify(error.json)}\n`);
+    warn(error?.message ?? String(error));
+    if (typeof error?.exitCode === "number") return error.exitCode;
+    if (String(error?.code ?? "").startsWith("ERR_PARSE_ARGS")) {
+      warn("Run with --help for usage.");
+      return EXIT.SETUP;
+    }
+    return EXIT.FAILURE;
+  }
+}
+
+/**
+ * Whether this module is the one node was asked to run. Both sides are
+ * realpath'd, so a worktree, a symlinked checkout or a /tmp path on macOS
+ * still runs the CLI instead of silently exiting 0. A local copy rather than
+ * an import, because plugin payload scripts ship standalone.
+ * @param {string} moduleUrl - The caller's own `import.meta.url`
+ * @param {string | undefined} [argv1] - Entry path
+ * @returns {boolean} Whether to run the CLI body
+ */
+function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  // The single read of the real environment (see the module header).
+  main(process.argv.slice(2), { env: { ...process.env } }).then(
+    code => {
+      process.exitCode = code;
+    },
+    error => {
+      process.stderr.write(`${error?.message ?? error}\n`);
+      process.exitCode = EXIT.FAILURE;
+    }
+  );
+}

package/plugins/src/base/skills/lisa-session-manager/scripts/state-dir.mjs

@@ -0,0 +1,112 @@
+/**
+ * The manager's per-project Telegram state dir, and the refusal error every
+ * launch-time check throws.
+ *
+ * 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`), and on start it SIGTERMs whichever
+ * poller holds the `bot.pid` in the same dir. So the shared default dir is
+ * refused outright, including through a symlink. Split out of launch.mjs,
+ * which re-exports everything here.
+ * @module state-dir
+ */
+import * as nodeFs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** Exit code for every refusal here: a setup problem the operator must fix. */
+const EXIT_SETUP = 2;
+
+/**
+ * A refusal that the CLI maps to a process exit code (always 2 here: the
+ * operator must fix setup before the manager can start).
+ */
+export class LaunchError extends Error {
+  /**
+   * @param {string} message - Operator-readable reason; never contains a token
+   * @param {number} [exitCode] - Process exit code the CLI should use
+   */
+  constructor(message, exitCode = EXIT_SETUP) {
+    super(message);
+    this.name = "LaunchError";
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Paths the plugin falls back to when `TELEGRAM_STATE_DIR` is unset. Both the
+ * `CLAUDE_CONFIG_DIR` one and the `~/.claude` one are refused, because the
+ * operator's own sessions may run with either.
+ * @param {{ env?: Record<string, string | undefined>, homedir?: string }} seams
+ *   - Injected env and home dir
+ * @returns {string[]} Absolute shared-default dirs
+ */
+function sharedDefaultDirs({ env = {}, homedir = os.homedir() }) {
+  const roots = [path.join(homedir, ".claude")];
+  if (env.CLAUDE_CONFIG_DIR) roots.push(path.resolve(env.CLAUDE_CONFIG_DIR));
+  return roots.map(root => path.join(root, "channels", "telegram"));
+}
+
+/**
+ * Resolve symlinks in the longest existing prefix of `target`, keeping the
+ * not-yet-created remainder as written. A state dir usually does not exist
+ * before `store-token` creates it, but its parent (or `~/.claude`) may be a
+ * symlink, and a plain string comparison would miss the shared dir behind it.
+ * @param {string} target - Absolute path
+ * @param {Pick<typeof nodeFs, "realpathSync">} fs - Injected fs
+ * @returns {string} Path with every existing component's symlinks resolved
+ */
+export function realpathExisting(target, fs = nodeFs) {
+  const rest = [];
+  let current = target;
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync(current), ...rest);
+    } catch {
+      const parent = path.dirname(current);
+      if (parent === current) return target;
+      rest.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+/**
+ * Resolve the configured state dir to an absolute path, refusing the shared
+ * default. Both sides are compared after resolving symlinks where the path
+ * exists, so an alias of the shared dir is refused too. The comparison ignores
+ * case because macOS volumes usually do.
+ * @param {string} stateDir - `sessionManager.notify.stateDir`, `~` allowed
+ * @param {{ env?: Record<string, string | undefined>, homedir?: string }} [seams]
+ *   - Injected env (for CLAUDE_CONFIG_DIR) and home dir
+ * @returns {string} Absolute, normalized dir
+ */
+export function resolveStateDir(stateDir, seams = {}) {
+  const homedir = seams.homedir ?? os.homedir();
+  if (typeof stateDir !== "string" || stateDir.trim() === "") {
+    throw new LaunchError("notify.stateDir is empty; set a per-project dir.");
+  }
+  const expanded =
+    stateDir === "~" || stateDir.startsWith("~/")
+      ? path.join(homedir, stateDir.slice(1))
+      : stateDir;
+  if (!path.isAbsolute(expanded)) {
+    throw new LaunchError(
+      `notify.stateDir "${stateDir}" must be absolute or start with ~/.`
+    );
+  }
+  const resolved = path.resolve(expanded);
+  const real = realpathExisting(resolved).toLowerCase();
+  const shared = sharedDefaultDirs({ ...seams, homedir }).flatMap(dir => [
+    dir.toLowerCase(),
+    realpathExisting(dir).toLowerCase(),
+  ]);
+  if (shared.includes(resolved.toLowerCase()) || shared.includes(real)) {
+    throw new LaunchError(
+      `notify.stateDir ${resolved} is the shared Telegram default. Pick a ` +
+        `per-project dir (e.g. ~/.claude/channels/telegram-<project>), or the ` +
+        `manager and your own Telegram session will kill each other's poller.`
+    );
+  }
+  return resolved;
+}