@codyswann/lisa 4.80.2 → 4.81.0

package/plugins/lisa-copilot/commands/lisa/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-copilot/commands/lisa/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-copilot/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

package/plugins/lisa-copilot/rules/reference/config-resolution.md

@@ -280,6 +280,7 @@ fi
 | `health.schedule` | no | `off` | Health cadence contract: `off`, `daily`, or `weekly`. `lisa sync` populates the default with `_lisaSync.populated` provenance and rejects values outside this closed vocabulary. Runtime results live only at the gitignored `.lisa/health/latest.json`, never in either config file. |
 | `usage` | no | — | Optional token/cost pricing metadata consumed by the `usage-accounting` rule. Missing pricing never blocks a lifecycle flow; Lisa records token counts with `estimated_cost: null` when no trustworthy price source is configured. |
 | `wiki` | no | — | Wiki location for the `wiki-knowledge-source` rule. Omit for a local in-repo wiki (`wiki/`). See **Wiki source** below. |
+| `sessionManager` | no | — (opt-in) | Local session manager: polls the Ready queue, runs each item in a fresh background Claude Code session, and relays questions over a per-project Telegram bot. Absent means the manager is not used; `lisa sync` never populates it. Written by `/lisa:setup:session-manager`. See **Session manager (`sessionManager`)** below. |
 
 ### Host rules (`.agents/rules/`)
 
@@ -688,6 +689,63 @@ Resolution order matches every other key: `$ARGUMENTS` override → `.lisa.confi
 roles count as "stuck", what each repair does) are fixed like every other lifecycle transition;
 only these thresholds are tunable.
 
+### Session manager (`sessionManager`)
+
+The optional `sessionManager` block configures `lisa-session-manager`, a locally hosted loop that
+claims Ready leaf items and runs each one as `/lisa:implement` in a fresh background Claude Code
+session. It is **opt-in**: an absent block means no manager, and `lisa sync` never populates it
+(it is deliberately not in the sync registry, because the manager starts sessions with permissions
+bypassed). `/lisa:setup:session-manager` writes it, detecting a multi-repo layout from
+`projects/*/.lisa.config.json`.
+
+```json
+"sessionManager": {
+  "name": "<project>-manager",
+  "interval": "5m",
+  "repos": {
+    "root": "projects",
+    "entries": {
+      "api": { "hints": ["NestJS", "API", "migrations"] },
+      "web": { "hints": ["Expo", "React", "screens"] }
+    }
+  },
+  "capacity": { "maxWorkers": 6, "gbPerWorker": 3, "reserveGb": 8, "cpuFraction": 0.75, "maxLoadPerCore": 1.5 },
+  "stall": { "noOutputMinutes": 60, "maxAttempts": 3, "requestionHours": 4 },
+  "notify": { "provider": "telegram", "stateDir": "~/.claude/channels/telegram-<project>" }
+}
+```
+
+| Key | Required | Default | Notes |
+|-----|----------|---------|-------|
+| `sessionManager.name` | **yes** | — | Manager session name: lowercase letters, digits, `-` or `_`, at most 64 characters. It names the tmux session and the session workers `SendMessage` to. Setup writes `<project>-manager`. |
+| `sessionManager.interval` | no | `5m` | `/loop` cadence: a positive integer plus `s`, `m`, `h` or `d`. |
+| `sessionManager.repos` | no | — | Omit for a single-repo project: every item routes to the project root. When present, `entries` must name at least one repo. |
+| `sessionManager.repos.root` | no | `projects` | Relative directory holding the child repos. It must stay inside the project. |
+| `sessionManager.repos.entries.<key>.hints` | **yes** (per entry) | — | Non-empty list of words the manager matches a work item against to choose the repo. `<key>` is the child directory name (one safe path segment). |
+| `sessionManager.capacity.maxWorkers` | no | `6` | Hard cap on concurrent workers (a positive integer). Telegram `cap N` overrides it at runtime through the manager's ledger, not config. |
+| `sessionManager.capacity.gbPerWorker` | no | `3` | Memory budgeted per worker, in GB (positive). |
+| `sessionManager.capacity.reserveGb` | no | `8` | Memory kept free for everything else, in GB (zero or positive). |
+| `sessionManager.capacity.cpuFraction` | no | `0.75` | Share of CPU cores workers may occupy, greater than 0 and at most 1. |
+| `sessionManager.capacity.maxLoadPerCore` | no | `1.5` | No new worker starts while the 1-minute load average exceeds cores × this (positive). |
+| `sessionManager.stall.noOutputMinutes` | no | `60` | A live worker with no new output for this long counts as stalled (zero or positive). |
+| `sessionManager.stall.maxAttempts` | no | `3` | Fresh sessions per item before it moves to the configured `blocked` role (a positive integer). |
+| `sessionManager.stall.requestionHours` | no | `4` | How long an unanswered worker question waits before the manager asks again (zero or positive). |
+| `sessionManager.notify.provider` | no | `telegram` | Only `telegram` is implemented. |
+| `sessionManager.notify.stateDir` | **yes** | — | This project's own Telegram state dir. Never the shared default `~/.claude/channels/telegram`, because one bot per state dir is how projects stay isolated. Setup writes `~/.claude/channels/telegram-<project>`. |
+| `sessionManager.trustedAuthorIds` | no | — | Optional list of **stable tracker user ids**, as strings: the GitHub numeric user id (`gh api users/<login> --jq .id`), the Jira `accountId`, or the Linear user id. Not logins or display names: matching compares ids, so a login silently matches no one and excludes every item. When set, the manager takes only items authored by these people. |
+
+- **Non-secret only.** The bot token lives in `<stateDir>/.env` (directory 0700, file 0600),
+  written by setup. A credential-named field or a token-shaped value anywhere in this block is a
+  validation error.
+- **Local over global, per key.** `.lisa.config.local.json` overrides `.lisa.config.json` key by key
+  (for example, a smaller `capacity.maxWorkers` on one machine); arrays such as `hints` are
+  replaced, not merged. Built-in defaults fill whatever neither file sets.
+- **Workflow roles are not here.** Ready, claimed and blocked come from the existing tracker
+  workflow config, through the single role resolver, like every other lifecycle flow.
+- **Shape check.** `validateSessionManager` in
+  `lisa-secrets-access/scripts/validate-config.mjs` runs as part of `validateConfig`, so
+  `/lisa:doctor` reports a malformed block.
+
 ### Env-keyed `done`
 
 The `done` role is special: the terminal status/label depends on which environment a PR was merged into. A hotfix to staging ends at `On Stg`; a production hotfix ends at `Done`. So `done` is a **map** keyed by env name (`dev`, `staging`, `production`).

package/plugins/lisa-copilot/scripts/automation-status-claude-adapter.mjs

@@ -123,7 +123,9 @@ export async function inspectClaudeAutomationFleet(input) {
       status: "UNSUPPORTED",
       summary: unsupported.reason,
       expectedCadence: unsupported.expectedCadence,
-      observed: "No automation is expected for this repo/runtime combination.",
+      observed:
+        unsupported.observed ??
+        "No automation is expected for this repo/runtime combination.",
       runbook: runDisplay?.runbook,
       lastOutcome: runDisplay?.lastOutcome,
       outcomeHistory: runDisplay?.outcomeHistory,
@@ -233,6 +235,7 @@ async function resolveFleetRunDisplays(projectRoot, expectedFleet) {
         projectRoot,
         loopId: entry.id,
         runbookPath: entry.runbookPath,
+        runbookSetupCommand: entry.runbookSetupCommand,
       })
     )
   );

package/plugins/lisa-copilot/scripts/automation-status-codex-adapter.mjs

@@ -214,7 +214,9 @@ export async function inspectCodexAutomationFleet(input) {
       status: "UNSUPPORTED",
       summary: unsupported.reason,
       expectedCadence: unsupported.expectedCadence,
-      observed: "No automation is expected for this repo/runtime combination.",
+      observed:
+        unsupported.observed ??
+        "No automation is expected for this repo/runtime combination.",
       runbook: runDisplay?.runbook,
       lastOutcome: runDisplay?.lastOutcome,
       outcomeHistory: runDisplay?.outcomeHistory,
@@ -656,6 +658,7 @@ async function resolveFleetRunDisplays(projectRoot, expectedFleet) {
         projectRoot,
         loopId: entry.id,
         runbookPath: entry.runbookPath,
+        runbookSetupCommand: entry.runbookSetupCommand,
       })
     )
   );

package/plugins/lisa-copilot/scripts/automation-status-expected-fleet.mjs

@@ -140,7 +140,16 @@ export function renderAutomationGroups(bins) {
  *   readonly expectedCadence: string
  *   readonly expectedRRule: string
  *   readonly runbookPath: string
+ *   readonly observed?: string
+ *   readonly runbookSetupCommand?: string
  * }} UnsupportedAutomationEntry
+ *
+ * `observed` overrides the adapters' default "No automation is expected" text
+ * for an entry that does run, just not where the scheduler can see it.
+ * `runbookSetupCommand` names the command that scaffolds this loop's runbook
+ * when it is not `/lisa:setup-automations` (the session manager's runbook is
+ * seeded by `/lisa:setup:session-manager`), so the "not scaffolded" fix-it
+ * text sends the operator to the command that can actually fix it.
  */
 
 /**
@@ -351,6 +360,12 @@ export function resolveExpectedAutomationFleet(input = {}) {
     );
   }
 
+  if (isPlainObject(config.sessionManager)) {
+    unsupported.push(
+      createSessionManagerEntry(identity, config.sessionManager)
+    );
+  }
+
   return {
     ...identity,
     expected,
@@ -413,6 +428,89 @@ function createUnsupportedEntry(identity, id, reason, group) {
   };
 }
 
+/** Loop id the session manager records its cycles under. */
+export const SESSION_MANAGER_LOOP_ID = "session-manager";
+
+/** Interval used when `sessionManager.interval` is absent or unparseable. */
+const SESSION_MANAGER_DEFAULT_INTERVAL = "5m";
+
+/**
+ * RRULE units, largest first, so `120m` reads as `HOURLY;INTERVAL=2`.
+ * @type {readonly (readonly [string, number])[]}
+ */
+const RRULE_UNITS = [
+  ["DAILY", 86400],
+  ["HOURLY", 3600],
+  ["MINUTELY", 60],
+  ["SECONDLY", 1],
+];
+
+/** Seconds per `sessionManager.interval` unit suffix. */
+const LOOP_INTERVAL_UNIT_SECONDS = { s: 1, m: 60, h: 3600, d: 86400 };
+
+/**
+ * Build the UNSUPPORTED entry for the locally hosted session manager.
+ *
+ * The manager is a `/loop` in a tmux session that setup starts, so no runtime
+ * scheduler can see it: MISSING would be a lie and HEALTHY unprovable. It is
+ * listed as UNSUPPORTED with a reason that says where it runs and how to check
+ * it, and the adapters still attach its runbook and recorded cycles (it records
+ * through `automation-run-record.mjs --loop-id session-manager`). Opt-in: only
+ * called when `config.sessionManager` exists, so other fleets are unchanged.
+ *
+ * The interval parser mirrors `parseLoopInterval` in the config validator; it
+ * is inlined because plugin-level scripts do not import from skill folders.
+ *
+ * @param {{ readonly automationPrefix: string }} identity
+ * @param {Record<string, any>} block The `sessionManager` config block.
+ * @returns {UnsupportedAutomationEntry}
+ */
+function createSessionManagerEntry(identity, block) {
+  const parsed = parseIntervalSeconds(block.interval);
+  const interval =
+    parsed === null ? SESSION_MANAGER_DEFAULT_INTERVAL : block.interval;
+  const seconds = parsed ?? parseIntervalSeconds(interval);
+  const [freq, unit] = RRULE_UNITS.find(([, size]) => seconds % size === 0);
+  const session =
+    typeof block.name === "string" && block.name !== ""
+      ? `tmux session \`${block.name}\``
+      : "the manager's tmux session";
+  return {
+    id: SESSION_MANAGER_LOOP_ID,
+    automationId: `${identity.automationPrefix}${SESSION_MANAGER_LOOP_ID}`,
+    expectedCadence: `every ${interval} (tmux-hosted /loop)`,
+    expectedRRule: `FREQ=${freq};INTERVAL=${seconds / unit}`,
+    group: "opt-in",
+    reason: `Hosted locally in ${session} by /lisa:setup:session-manager, not by this runtime's scheduler, so the scheduler cannot see it. Its recorded cycles are below; check it is alive with \`/lisa:session-manager status\`.`,
+    observed:
+      "Hosted locally in tmux; the scheduler cannot observe it — check `/lisa:session-manager status`",
+    runbookPath: resolveAutomationRunbookPath(SESSION_MANAGER_LOOP_ID),
+    runbookSetupCommand: "/lisa:setup:session-manager",
+  };
+}
+
+/**
+ * Parse a `/loop` interval such as `5m` into seconds.
+ *
+ * @param {unknown} text
+ * @returns {number | null} Seconds, or null when unparseable or zero.
+ */
+function parseIntervalSeconds(text) {
+  if (typeof text !== "string") return null;
+  const match = /^(\d+)([smhd])$/.exec(text);
+  if (!match) return null;
+  const seconds = Number(match[1]) * LOOP_INTERVAL_UNIT_SECONDS[match[2]];
+  return seconds > 0 ? seconds : null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} True for `{}`-shaped values.
+ */
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /**
  * @param {Record<string, any>} config
  * @param {string | undefined} source

package/plugins/lisa-copilot/scripts/automation-status-run-history.mjs

@@ -41,8 +41,23 @@ export const RECOVERY_REQUIRED_OUTCOME = "recovery-required";
  */
 export const RECOVERY_REQUIRED_ESCALATION_THRESHOLD = 3;
 
-const RUNBOOK_NOT_SCAFFOLDED_LINE =
-  "not scaffolded — run /lisa:setup-automations";
+/** The command that scaffolds a scheduled loop's runbook. */
+const DEFAULT_RUNBOOK_SETUP_COMMAND = "/lisa:setup-automations";
+
+/**
+ * The "not scaffolded" fix-it line, naming the command that scaffolds this
+ * loop's runbook.
+ *
+ * @param {string} [setupCommand]
+ * @returns {string}
+ */
+function runbookNotScaffoldedLine(
+  setupCommand = DEFAULT_RUNBOOK_SETUP_COMMAND
+) {
+  return `not scaffolded — run ${setupCommand}`;
+}
+
+const RUNBOOK_NOT_SCAFFOLDED_LINE = runbookNotScaffoldedLine();
 const NO_RECORDED_RUNS_LINE = "no recorded runs yet";
 
 /**
@@ -72,12 +87,18 @@ const NO_RECORDED_RUNS_LINE = "no recorded runs yet";
  *   readonly projectRoot?: string
  *   readonly loopId: string
  *   readonly runbookPath?: string
- * }} input
+ *   readonly runbookSetupCommand?: string
+ * }} input `runbookSetupCommand` overrides `/lisa:setup-automations` in the
+ *   "not scaffolded" line for a loop another setup command scaffolds.
  * @returns {Promise<AutomationRunDisplay>}
  */
 export async function resolveAutomationRunDisplay(input) {
   const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
-  const runbook = await resolveRunbookLine(projectRoot, input.runbookPath);
+  const runbook = await resolveRunbookLine(
+    projectRoot,
+    input.runbookPath,
+    runbookNotScaffoldedLine(input.runbookSetupCommand)
+  );
   const recordsPath = automationRunRecordPath(projectRoot, input.loopId);
   const { records, skippedCorruptLines } =
     await readAutomationRunRecords(recordsPath);
@@ -168,16 +189,17 @@ export function resolveRecoveryEscalation(runDisplay) {
 /**
  * @param {string} projectRoot
  * @param {string | undefined} runbookPath
+ * @param {string} missingLine The "not scaffolded" line for this loop
  * @returns {Promise<string>}
  */
-async function resolveRunbookLine(projectRoot, runbookPath) {
+async function resolveRunbookLine(projectRoot, runbookPath, missingLine) {
   if (!runbookPath) {
-    return RUNBOOK_NOT_SCAFFOLDED_LINE;
+    return missingLine;
   }
   const scaffolded = await runbookIsScaffolded(
     path.join(projectRoot, runbookPath)
   );
-  return scaffolded ? runbookPath : RUNBOOK_NOT_SCAFFOLDED_LINE;
+  return scaffolded ? runbookPath : missingLine;
 }
 
 /**