@codyswann/lisa 4.84.11 → 4.86.0

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

@@ -13,159 +13,33 @@
  * With `sessionManager.backlogPickup` on, `queue` also ranks the backlog tier
  * (open leaves in no lifecycle role) as `backlogOrdered`, under the same
  * paging rule. The manager walks it only after the whole Ready queue.
+ *
+ * The GitHub fetches live in queue-github.mjs and JSON input in
+ * json-input.mjs (re-exported here), to keep each module under the line
+ * budget.
  * @module session-manager/cli-queue
  */
-import { readFileSync } from "node:fs";
-
 import {
   assertPagedToCompletion,
-  normalizeGithubIssue,
   normalizeJiraIssue,
   normalizeLinearIssue,
   orderBacklogQueue,
   orderReadyQueue,
 } from "../../../scripts/ready-queue-order.mjs";
-import { resolveRole } from "../../../scripts/resolve-lifecycle-role.mjs";
 import {
   CliError,
   asSetupError,
   humanNeededLabel,
   loadProject,
-  mustRun,
   validOrAbsent,
 } from "./cli-runtime.mjs";
+import { readJsonFile } from "./json-input.mjs";
 import { readLedger } from "./ledger.mjs";
-import { scrubWorkerEnv } from "./workers.mjs";
-
-const NORMALIZERS = { jira: normalizeJiraIssue, linear: normalizeLinearIssue };
+import { fetchGithubBacklog, fetchGithubQueue } from "./queue-github.mjs";
 
-const OWNER_REPO = /^[\w.-]+\/[\w.-]+$/;
+export { parseJson, readJsonFile } from "./json-input.mjs";
 
-/**
- * Parse JSON, or exit 2 naming the source.
- * @param {string} text - JSON text
- * @param {string} source - Where it came from
- * @returns {any} Parsed value
- */
-export function parseJson(text, source) {
-  try {
-    return JSON.parse(text);
-  } catch (error) {
-    throw new CliError(`${source} is not valid JSON: ${error.message}`, 2);
-  }
-}
-
-/**
- * Read a JSON file named by a flag, or exit 2.
- * @param {string} file - Path
- * @returns {any} Parsed value
- */
-export function readJsonFile(file) {
-  const text = asSetupError(() => readFileSync(file, "utf8"));
-  return parseJson(text, file);
-}
-
-/**
- * The GitHub repo to read: `--github-repo`, else github.org/github.repo.
- * @param {object} ctx - CLI context
- * @param {ReturnType<typeof loadProject>} project - Loaded project
- * @returns {string} `owner/repo`
- */
-function githubRepo(ctx, project) {
-  const merged = { ...project.global?.github, ...project.local?.github };
-  const repo =
-    ctx.values["github-repo"] ??
-    (merged.org && merged.repo ? `${merged.org}/${merged.repo}` : "");
-  if (!OWNER_REPO.test(repo)) {
-    throw new CliError(
-      "No GitHub repo: set github.org and github.repo, or pass --github-repo <owner/repo>.",
-      2
-    );
-  }
-  return repo;
-}
-
-/**
- * Every string leaf of an object (label names, including env-keyed `done`).
- * @param {unknown} value - Config subtree
- * @returns {string[]} Leaves
- */
-function stringLeaves(value) {
-  if (typeof value === "string") return value ? [value] : [];
-  if (!value || typeof value !== "object") return [];
-  return Object.values(value).flatMap(stringLeaves);
-}
-
-/**
- * Fetch every open GitHub issue carrying no lifecycle label (build or PRD),
- * all pages: the GitHub backlog tier.
- * @param {object} ctx - CLI context
- * @param {ReturnType<typeof loadProject>} project - Loaded project
- * @returns {{ items: object[], pages: number }} Normalized items
- */
-function fetchGithubBacklog(ctx, project) {
-  const repo = githubRepo(ctx, project);
-  const lifecycle = new Set(
-    [project.global?.github?.labels, project.local?.github?.labels]
-      .flatMap(labels => [
-        ...stringLeaves(labels?.build),
-        ...stringLeaves(labels?.prd),
-      ])
-      .map(label => label.toLowerCase())
-  );
-  const stdout = mustRun(
-    "gh",
-    [
-      "api",
-      "--paginate",
-      "--slurp",
-      `repos/${repo}/issues?state=open&per_page=100`,
-    ],
-    { env: scrubWorkerEnv(ctx.env) }
-  );
-  const pages = parseJson(stdout, "gh api output");
-  const rows = Array.isArray(pages) ? pages.flat() : [];
-  return {
-    items: rows
-      .map(row => normalizeGithubIssue(row, { repo }))
-      .filter(Boolean)
-      .filter(
-        item => !item.labels.some(label => lifecycle.has(label.toLowerCase()))
-      ),
-    pages: Array.isArray(pages) ? pages.length : 0,
-  };
-}
-
-/**
- * Fetch every open GitHub issue carrying the ready label, all pages.
- * @param {object} ctx - CLI context
- * @param {ReturnType<typeof loadProject>} project - Loaded project
- * @returns {{ items: object[], pages: number }} Normalized items
- */
-function fetchGithubQueue(ctx, project) {
-  const repo = githubRepo(ctx, project);
-  const role = resolveRole({
-    role: "ready",
-    vendor: "github",
-    intent: "read",
-    local: project.local,
-    global: project.global,
-  });
-  const label = ctx.values.label ?? role.value;
-  if (!label) throw new CliError(role.message, 2);
-  const endpoint =
-    `repos/${repo}/issues?state=open&labels=${encodeURIComponent(label)}` +
-    `&per_page=100`;
-  const stdout = mustRun("gh", ["api", "--paginate", "--slurp", endpoint], {
-    env: scrubWorkerEnv(ctx.env),
-  });
-  const pages = parseJson(stdout, "gh api output");
-  const rows = Array.isArray(pages) ? pages.flat() : [];
-  return {
-    items: rows.map(row => normalizeGithubIssue(row, { repo })).filter(Boolean),
-    pages: Array.isArray(pages) ? pages.length : 0,
-  };
-}
+const NORMALIZERS = { jira: normalizeJiraIssue, linear: normalizeLinearIssue };
 
 /**
  * Check one paged envelope and normalize its raw issues.
@@ -216,6 +90,40 @@ function readEnvelopeQueue(ctx, tracker, withBacklog) {
   };
 }
 
+/**
+ * Refs waiting on a human: every ledger item with a pending question.
+ * @param {{items: Record<string, {pendingQuestion?: unknown}>}} ledger - Ledger
+ * @returns {Set<string>} Refs
+ */
+function pendingRefs(ledger) {
+  return new Set(
+    Object.entries(ledger.items)
+      .filter(([, item]) => item.pendingQuestion)
+      .map(([ref]) => ref)
+  );
+}
+
+/**
+ * Move items waiting on a human out of `ordered` into `excluded` with reason
+ * `pending-question` (#4555). The item stays marked for its human; every
+ * other item is still dispatched, so one question never stalls the queue.
+ * @param {{ordered: {ref: string}[], excluded: {ref: string, reason: string}[]}} order - Ordered tier
+ * @param {Set<string>} waiting - Refs with a pending question
+ * @returns {{ordered: {ref: string}[], excluded: {ref: string, reason: string}[]}} Filtered tier
+ */
+function withoutPending(order, waiting) {
+  return {
+    ...order,
+    ordered: order.ordered.filter(item => !waiting.has(item.ref)),
+    excluded: [
+      ...order.excluded,
+      ...order.ordered
+        .filter(item => waiting.has(item.ref))
+        .map(item => ({ ref: item.ref, reason: "pending-question" })),
+    ],
+  };
+}
+
 /**
  * `queue --tracker <github|jira|linear>`: the Ready queue, the operator's
  * items first (`sessionManager.operatorIds`), then mine, then unassigned.
@@ -251,7 +159,8 @@ export async function queue(ctx) {
     trustedAuthorIds: config?.trustedAuthorIds ?? undefined,
     humanNeededLabel: humanNeededLabel(project, tracker),
   };
-  const order = orderReadyQueue(items, policy);
+  const waiting = pendingRefs(ledger);
+  const order = withoutPending(orderReadyQueue(items, policy), waiting);
   const json = {
     tracker,
     me,
@@ -265,10 +174,13 @@ export async function queue(ctx) {
   // An item both Ready and in the backlog fetch is Ready work; never twice.
   const readyRefs = new Set(items.map(item => item.ref));
   const backlogItems = backlog.items.filter(item => !readyRefs.has(item.ref));
-  const tier = orderBacklogQueue(backlogItems, {
-    ...policy,
-    validationFailures: ledger.validationFailures,
-  });
+  const tier = withoutPending(
+    orderBacklogQueue(backlogItems, {
+      ...policy,
+      validationFailures: ledger.validationFailures,
+    }),
+    waiting
+  );
   return {
     json: {
       ...json,

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

@@ -227,15 +227,17 @@ export function requireLisaRepo(dir) {
  * Run a command with an argv array and no shell.
  * @param {string} command - Executable, looked up on PATH
  * @param {readonly string[]} args - argv
- * @param {{ env: Record<string, string | undefined>, cwd?: string }} options
- *   - Environment and working directory
+ * @param {{ env: Record<string, string | undefined>, cwd?: string,
+ *   input?: string }} options - Environment, working directory and stdin
+ *   (for text that must stay out of argv)
  * @returns {{ status: number | null, stdout: string, stderr: string,
  *   missing: boolean }} Outcome; `missing` when the command is not on PATH
  */
-export function run(command, args, { env, cwd }) {
+export function run(command, args, { env, cwd, input }) {
   const result = spawnSync(command, args, {
     cwd,
     env,
+    ...(input === undefined ? {} : { input }),
     encoding: "utf8",
     maxBuffer: MAX_BUFFER,
   });

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

@@ -21,25 +21,36 @@ import {
   buildDefaultBlock,
   detectRepoLayout,
   draftHints,
+  notifyProvider,
   resolveRepoDir,
 } from "./config.mjs";
 import { defaultProjectSlug } from "./isolation.mjs";
 import {
+  readTokenFromClipboard,
+  readTokenFromPrompt,
+  resolveStateDir,
   storeToken as storeTokenFile,
   storeTokenFromClipboard,
 } from "./launch.mjs";
+import {
+  loadTokenSecrets,
+  storeTokenInProvider,
+  telegramSecretName,
+} from "./token-store.mjs";
 import {
   coexistence as readCoexistence,
   trustStatus as readTrust,
 } from "./setup-checks.mjs";
 
 /**
- * `init-config [--slug <slug>] [--write]`: the default block for this
- * project, written to `.lisa.config.json` only with `--write` and only when
- * no block exists. Non-secret fields only; the token never goes here. Repos
- * are the routable children `detectRepoLayout` finds under `projects/`, else
- * directly under the root (linked worktrees and second clones of one remote
- * left out), each with drafted hints.
+ * `init-config [--slug <slug>] [--notify none|telegram] [--write]`: the
+ * default block for this project, written to `.lisa.config.json` only with
+ * `--write` and only when no block exists. Non-secret fields only; the token
+ * never goes here. Repos are the routable children `detectRepoLayout` finds
+ * under `projects/`, else directly under the root (linked worktrees and second
+ * clones of one remote left out), each with drafted hints. `--notify` defaults
+ * to `none` (no notification channel, so no state dir); `telegram` adds the
+ * per-project state dir. Anything else exits 2.
  * @param {object} ctx - CLI context
  * @returns {{ json: object }} `{written,block,...}`
  */
@@ -60,7 +71,13 @@ export function initConfig(ctx) {
     ])
   );
   const block = asSetupError(() =>
-    buildDefaultBlock({ projectSlug: slug, detectedRepos, hints, reposRoot })
+    buildDefaultBlock({
+      projectSlug: slug,
+      detectedRepos,
+      hints,
+      reposRoot,
+      notify: ctx.values.notify ?? "none",
+    })
   );
   if (!ctx.values.write) return { json: { written: false, block } };
 
@@ -80,16 +97,33 @@ export function initConfig(ctx) {
 }
 
 /**
- * `store-token [--replace] [--from-clipboard]`: store the bot token in the
- * project's state dir. By default it prompts on the operator's terminal (echo
- * off); with no TTY it prints the two commands that work instead and exits 0
- * with `stored:false`. `--from-clipboard` reads the system clipboard and needs
- * no TTY. An existing token is kept (exit 2) unless `--replace` is given.
+ * `store-token [--replace] [--from-clipboard] [--vault-project <id>]`: store
+ * the bot token. With a secrets provider configured (`secrets.provider` set
+ * and not `env`) it goes into the provider as `TELEGRAM_BOT_TOKEN_<NAME>`
+ * and nothing is written to disk: a plaintext `<stateDir>/.env` left by an
+ * older setup is migrated (stored, read back and compared, then deleted), and
+ * an already-stored token is kept (exit 0) unless `--replace` is given
+ * (#4555). With no provider it is written to `<stateDir>/.env` as before,
+ * and an existing file is kept (exit 2) unless `--replace`.
+ *
+ * Either way the token is read from the operator's terminal (echo off) or,
+ * with `--from-clipboard`, from the system clipboard; with no TTY it prints
+ * the two commands that work instead and exits 0 with `stored:false`. The
+ * token is never printed.
  * @param {object} ctx - CLI context
  * @returns {Promise<{ json: object, exitCode: number }>} Outcome
  */
 export async function storeToken(ctx) {
   const config = requireConfig(ctx);
+  if (notifyProvider(config) !== "telegram") {
+    throw new CliError(
+      `sessionManager.notify.provider is "none", so there is no bot token ` +
+        `to store. To use Telegram, set notify to {"provider":"telegram",` +
+        `"stateDir":"~/.claude/channels/telegram-<project>"} and run ` +
+        `store-token again.`,
+      EXIT.SETUP
+    );
+  }
   const input = {
     stateDir: config.notify?.stateDir,
     scriptsDir: ctx.scriptsDir,
@@ -98,11 +132,57 @@ export async function storeToken(ctx) {
     env: ctx.env,
     homedir: ctx.homedir,
   };
+  const secrets = await asSetupErrorAsync(() =>
+    loadTokenSecrets(ctx.root, ctx.env)
+  );
+  const result =
+    secrets === null
+      ? await storeInFile(ctx, input)
+      : await asSetupErrorAsync(() =>
+          storeInProvider(ctx, input, { ...secrets, name: config.name })
+        );
+  const refused = result.stored === false && result.reason !== "no-tty";
+  return { json: result, exitCode: refused ? EXIT.SETUP : EXIT.OK };
+}
+
+/**
+ * The no-provider path: `<stateDir>/.env`, as before #4555.
+ * @param {object} ctx - CLI context
+ * @param {object} input - Store input
+ * @returns {Promise<object>} Outcome, with `storage:"file"` once stored
+ */
+async function storeInFile(ctx, input) {
   const result = ctx.values["from-clipboard"]
     ? asSetupError(() => storeTokenFromClipboard(input))
     : await asSetupErrorAsync(() => storeTokenFile(input));
-  const refused = result.stored === false && result.reason !== "no-tty";
-  return { json: result, exitCode: refused ? EXIT.SETUP : EXIT.OK };
+  return result.stored ? { ...result, storage: "file" } : result;
+}
+
+/**
+ * The provider path: see {@link storeTokenInProvider}. The token reader
+ * (prompt or clipboard) runs only when there is no plaintext file to migrate
+ * and no stored token to keep.
+ * @param {object} ctx - CLI context
+ * @param {object} input - Store input
+ * @param {{ cfg: object, adapter: object, name: string }} secrets - Provider
+ *   config, adapter and the manager name
+ * @returns {Promise<object>} Outcome
+ */
+function storeInProvider(ctx, input, { cfg, adapter, name }) {
+  const secret = telegramSecretName(name);
+  const vaultProject = ctx.values["vault-project"];
+  return storeTokenInProvider({
+    cfg,
+    adapter,
+    name: secret,
+    stateDir: resolveStateDir(input.stateDir, input),
+    replace: input.replace,
+    vaultProject,
+    readToken: () =>
+      ctx.values["from-clipboard"]
+        ? readTokenFromClipboard()
+        : readTokenFromPrompt({ ...input, label: secret, vaultProject }),
+  });
 }
 
 /**

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

@@ -0,0 +1,73 @@
+/**
+ * The `status` subcommand of the session-manager CLI, split out of
+ * cli-manager.mjs to keep it under the line budget (#4555): is the manager's
+ * tmux session up, which notification provider is configured, what the
+ * ledger says about each worker, and which items wait on a human.
+ * cli-manager.mjs re-exports {@link status}, so callers keep one import.
+ * @module session-manager/cli-status
+ */
+import path from "node:path";
+
+import { listAgents, requireConfig, run } from "./cli-runtime.mjs";
+import { notifyProvider } from "./config.mjs";
+import { buildHasSession } from "./launch.mjs";
+import { listPendingQuestions } from "./ledger-questions.mjs";
+import { readLedger } from "./ledger.mjs";
+import { shellQuote } from "./token.mjs";
+import { parseWorkerName } from "./workers.mjs";
+
+/**
+ * The line an operator at this machine runs to answer a pending question:
+ * the answer goes on stdin, never in argv. Every word is single-quoted for
+ * the shell, so a path or ref holding `$(…)` or a backtick runs nothing.
+ * @param {{scriptsDir: string, root: string}} ctx - CLI context
+ * @param {string} ref - Item ref
+ * @returns {string} Command line
+ */
+function answerCommandFor(ctx, ref) {
+  const script = path.join(ctx.scriptsDir, "session-manager.mjs");
+  return `node ${shellQuote(script)} answer ${shellQuote(ref)} --project-root ${shellQuote(ctx.root)} < answer.txt`;
+}
+
+/**
+ * `status`: is the manager's tmux session up, and what does the ledger say
+ * about each worker it dispatched.
+ * @param {object} ctx - CLI context
+ * `notify` is the configured notification provider (`telegram` or `none`),
+ * so the manager knows each cycle whether a channel exists.
+ * @returns {Promise<{ json: object }>}
+ *   `{manager,notify,control,workers,untracked,pendingQuestions}`
+ */
+export async function status(ctx) {
+  const config = requireConfig(ctx);
+  const tmux = run("tmux", buildHasSession(config.name), { env: ctx.env });
+  const agents = listAgents(ctx, { all: true });
+  const ledger = await readLedger(ctx.root);
+  const liveNames = new Set(
+    agents.filter(agent => agent.active).map(agent => agent.name)
+  );
+  const tracked = new Set(Object.values(ledger.items).map(i => i.worker));
+  return {
+    json: {
+      manager: { name: config.name, running: tmux.status === 0 },
+      notify: notifyProvider(config),
+      control: ledger.control,
+      workers: Object.entries(ledger.items).map(([ref, item]) => ({
+        ref,
+        worker: item.worker ?? null,
+        sessionId: item.sessionId ?? null,
+        repo: item.repo ?? null,
+        status: item.status ?? null,
+        attempts: item.attempts ?? 0,
+        pendingQuestion: Boolean(item.pendingQuestion),
+        live: liveNames.has(item.worker),
+      })),
+      untracked: [...liveNames]
+        .filter(name => parseWorkerName(name) !== null && !tracked.has(name))
+        .sort(),
+      pendingQuestions: listPendingQuestions(ledger, ref =>
+        answerCommandFor(ctx, ref)
+      ),
+    },
+  };
+}

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

@@ -44,12 +44,29 @@ Workers and capacity
         pendingQuestion}], classification one of finished|waiting|requestion|
       working|stalled|dead|exhausted.
   status
-      stdout {manager:{name,running},control,workers:[{ref,worker,sessionId,
-      repo,status,attempts,pendingQuestion,live}],untracked:[wk- names]}.
+      stdout {manager:{name,running},notify,control,workers:[{ref,worker,
+      sessionId,repo,status,attempts,pendingQuestion,live}],untracked:[wk-
+      names],pendingQuestions:[{ref,kind,text,askedAt,marked,answerQueued,
+      answerCommand}]}. notify is the configured channel: "telegram" or
+      "none". pendingQuestions lists every item waiting on a human, oldest
+      first; answerCommand is the answer line to run at this machine.
 
 Manager
   start [--settle-ms <n>]
-             Refuses (exit 2) without <notify.stateDir>/.env (mode 0600) or for
+             With notify.provider "none" (or no notify block): no token, state
+             dir or Telegram plugin is needed; launches with no --channels, no
+             TELEGRAM_STATE_DIR and no plugin in --settings. With "telegram"
+             and a secrets provider (secrets.provider set, not "env"): reads
+             TELEGRAM_BOT_TOKEN_<NAME> from the provider once, before any tmux
+             call, and passes it to tmux on stdin (tmux start-server ;
+             source-file -), never in argv; tmux's stderr is never shown.
+             Exit 2 when a plaintext <notify.stateDir>/.env is left over (the
+             message names the store-token command that migrates it), when
+             the secret is missing, or when secrets.require does not list it.
+             Exit 1, "Nothing was started", when the provider cannot be
+             reached, is rate-limited or times out: wait a minute and run
+             start again. With "telegram" and no provider: refuses (exit 2)
+             without <notify.stateDir>/.env (mode 0600). Either way exit 2 for
              the shared default state dir. "already-running" when the tmux
              session =<name> exists and was started in this project root;
              exit 2 naming the conflict when it was started anywhere else.
@@ -57,21 +74,38 @@ Manager
              has-session -t =<name> every 250 ms for --settle-ms (default
              3000, at most 60000): exit 2, with the foreground command to run
              to see claude's error, when the session is gone.
-             stdout {status:"started"|"already-running",name,...}.
+             stdout {status:"started"|"already-running",name,notify,
+             [stateDir,tokenSource:"provider"|"file",secret,]attach}.
   stop       tmux kill-session -t =<name> only, and only for a session started
              in this root (exit 2 otherwise); workers keep running.
              stdout {status:"stopped"|"not-running",name}.
-  store-token [--replace] [--from-clipboard]
-             Prompts for the bot token on the terminal (echo off) and writes
-             <stateDir>/.env. Exit 2 when a token is already there, unless
-             --replace. With no TTY (an agent's Bash, and Claude Code's !
+  store-token [--replace] [--from-clipboard] [--vault-project <id>]
+             Telegram only: exit 2 when notify.provider is "none".
+             With a secrets provider: stores the token in it as
+             TELEGRAM_BOT_TOKEN_<NAME> and writes nothing to disk. A
+             plaintext <stateDir>/.env is migrated: stored, read back and
+             compared, then deleted (refused, exit 2, when the file holds
+             other keys or a different token than the stored one). An
+             already-stored token is kept (exit 0, alreadyStored:true) unless
+             --replace. --vault-project picks the provider project for a new
+             secret (default: the one in secrets.narrow.projectIds, else the
+             one every visible secret is in). stdout {stored:true,
+             storage:"provider",provider,secret,verified,[migratedFrom,
+             deleted]}. Provider unreachable or rate-limited: exit 1, nothing
+             stored, the file kept.
+             With no provider: prompts for the bot token on the terminal (echo
+             off) and writes <stateDir>/.env. Exit 2 when a token is already
+             there, unless --replace.
+             Either way, with no TTY (an agent's Bash, and Claude Code's !
              prefix too): exit 0, stdout {stored:false,reason:"no-tty",
              message,command,clipboardCommand}; command is the line the
              operator runs in a separate terminal app.
              --from-clipboard reads the token from the clipboard instead
              (pbpaste; wl-paste, xclip or xsel on Linux), needs no TTY, and
              clears the clipboard after a successful store. stdout
-             {stored:true,path,clipboardCleared}. The token is never printed.
+             {stored:true,storage:"file",path,clipboardCleared} (with a
+             provider, the provider shape plus clipboardCleared). The token
+             is never printed.
              Bad input, empty clipboard or no clipboard tool: exit 2,
              {stored:false,reason,message}.
 
@@ -80,8 +114,12 @@ Config and routing
              stdout {repo,dir}; --raw prints the bare dir. Exit 2 for an
              unknown key or a dir without .lisa.config.json.
   validate   stdout {valid,errors}; exit 2 when invalid or absent.
-  init-config [--slug <slug>] [--write]
-             stdout {written,block[,reason:"exists"][,path]}. Detects
+  init-config [--slug <slug>] [--notify none|telegram] [--write]
+             stdout {written,block[,reason:"exists"][,path]}. --notify picks
+             the notification channel (default none): none writes
+             notify {provider:"none"} and no state dir; telegram writes
+             {provider:"telegram",stateDir:"~/.claude/channels/telegram-<slug>"}.
+             Any other value: exit 2. Detects
              projects/*/.lisa.config.json, else root children with their own
              .lisa.config.json and .git (repos.root "."), skipping linked
              worktrees (.git is a file) and keeping one child per origin
@@ -113,7 +151,9 @@ Per cycle
       <file> = {complete:true,pages,items:[raw vendor issues]}; exit 2 unless
       complete is exactly true.
       Both print {tracker,me,operators,total,pages,ordered,excluded:[{ref,
-      reason}]}. ordered: items assigned to sessionManager.operatorIds
+      reason}]}. An item with a pending question in the ledger is excluded
+      (pending-question) from both tiers, and every other item still comes
+      back, so one item waiting on a human never stops dispatch. ordered: items assigned to sessionManager.operatorIds
       first, then to --me, then unassigned; each group by priority, then age.
       Items assigned to anyone else are excluded (assigned-to-other).
       --me defaults to the ledger's control.me.
@@ -126,9 +166,23 @@ Per cycle
       {complete:true,pages,items}, else exit 2.
   ledger get [<ref>]
   ledger record-spawn <ref> --worker <name> [--session-id <id>] [--repo <key>]
-  ledger set-question <ref> [--telegram-message-id <n>] [--sender <name>]
-                                                           STDIN: question
-  ledger clear-question <ref>
+  ledger set-question <ref> [--kind <kind>] [--telegram-message-id <n>]
+                           [--sender <name>]               STDIN: question
+      --kind: worker-question (default) | repo-route | exhausted | decision.
+      No message id with no channel. A re-ask keeps the item's marker
+      fields (markerType, marker, markedAt); a queued answer survives only a
+      re-ping of the same text.
+  ledger marked <ref> --marker-type label|role --marker <value>
+                     --comment-id <id>
+      Records that the human-needed marker was applied on the tracker and
+      read back (markedAt). --comment-id (required): the id of the question
+      comment the manager posted; item-answer anchors on it to find the
+      answer after it, and never reads it as an answer. Exit 2 when it is
+      missing or not a tracker comment id, or <ref> has no pending
+      question.
+  ledger clear-question <ref> [--reset-attempts]
+      After the answer is delivered and the marker removed. --reset-attempts
+      zeroes the attempt count (an exhausted item a human has answered).
   ledger finish <ref> --status DONE|FAILED [--sender <name>]  STDIN: reason
       --sender: exit 2 unless the ledger's worker for <ref> is exactly <name>.
   ledger validation-failed <ref> --updated-at <ts>     STDIN: failing gates
@@ -148,6 +202,42 @@ Per cycle
       unset); trustedHumanActorIds in the input is ignored. stdout
       {action:release|keep|escalate|skip-human-gate,reason,edges,gate}.
       --ref fills pendingQuestion from the ledger.
+  mark-plan <ref> --kind <kind>                 STDIN: question or reason
+      Plans marking an item that needs a human; writes nothing. kind:
+      worker-question | repo-route | exhausted | decision. stdout {ref,kind,
+      marker:{type:"label"|"role",value},[move:{role:"blocked",value},]
+      comment,answerWith:{item,cli,channel}}. marker is the tracker's
+      configured human-needed label, else the configured blocked role;
+      exhausted also moves to the blocked role. comment starts with
+      [lisa-session-manager-question] and says, in plain words, how to
+      answer: on the item (only when operatorIds or trustedAuthorIds is set;
+      answerWith.item is null otherwise), with the answerCommand that status
+      lists, or on Telegram when it is the channel. Exit 2 for an unknown
+      kind, empty or credential-shaped text, no marker configured, or
+      exhausted with no blocked role.
+  answer <ref>                                  STDIN: the answer
+      Queues an operator's answer (source "cli") for the next cycle to
+      deliver. stdout {queued:true,ref,source}. Exit 2 when <ref> has no
+      pending question, or the text looks like a credential.
+  item-answer <ref>          STDIN: {"comments":[{user|author,body,createdAt}]}
+      Queues the human's answer from the item's comments (source "item"):
+      the first comment after the latest [lisa-session-manager-question]
+      comment whose author's STABLE id (GitHub login or numeric id, Jira
+      accountId, Linear user id; never a name, displayName or email) is in
+      sessionManager.operatorIds or trustedAuthorIds, and that is not a
+      machine comment, checked first (body starting with a bracketed tag
+      such as [lisa-...] or [claude-sync]; [lisa- or <!-- lisa: anywhere;
+      "Written by Claude"; the agent "Generated with Claude Code" footer;
+      or an id in the ledger's managerCommentIds, so keep each comment's
+      id). For GitHub, pipe the rows of
+      gh api --paginate repos/<o>/<r>/issues/<n>/comments (user.login,
+      user.id). stdout {queued:true,ref,source,author} or {queued:false,ref,
+      reason:no-question-comment|no-answer-yet|already-queued|
+      no-answerers-configured[,explanation]}. no-answerers-configured (exit
+      0): neither list is set, so nothing on the item is read, because the
+      tracker identity is the one workers post as; answer with answer.
+      Exit 2 when <ref> has no pending question, or the answer looks like a
+      credential.
   record-cycle --outcome <outcome> [--ref <url>]... [--run-id <id>]
       STDIN: one-line summary. Records loop session-manager with runbook
       .lisa/automations/session-manager.runbook.md. stdout {path,appended,