@codyswann/lisa 4.80.2 → 4.81.0

package/plugins/lisa/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/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/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/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/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;
 }
 
 /**

package/plugins/lisa/scripts/ready-queue-order.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * Vendor-neutral Ready-queue normalization and mine-first dispatch order.
+ *
+ * ## Why this exists
+ *
+ * Intake has always taken Ready work in whatever order the tracker returned
+ * it, and `intake.assignee` only NARROWS a selection — it never ranks one. A
+ * dispatcher that runs several workers at once needs a stable answer to "what
+ * next?": the work already assigned to me first (somebody chose me for it),
+ * then unassigned work, most urgent and oldest first. Work assigned to someone
+ * else is theirs, so it is excluded, never re-ordered.
+ *
+ * The three trackers disagree on every field this needs — GitHub has priority
+ * LABELS, Linear a native 0..4 number where 0 means "none", Jira a priority
+ * NAME from a scheme that varies by site — so each vendor gets one normalizer
+ * onto a single item shape, and ordering only ever sees that shape.
+ *
+ * `queue-status-build-readers.mjs` reads raw GitHub only; Jira and Linear
+ * arrive here already fetched by their vendor access skills. This module never
+ * fetches: the caller pages the tracker to completion, and
+ * {@link assertPagedToCompletion} refuses to order a half-read queue, because
+ * a truncated sweep silently reorders by omission (#3529, #4105).
+ *
+ * Held items are judged by {@link isHumanGated}, the one shared answer to "is
+ * a person holding this?", rather than by a local label check (#3805).
+ * @module ready-queue-order
+ */
+
+import {
+  DEFAULT_HUMAN_NEEDED_LABEL,
+  isHumanGated,
+} from "./intake-blocker-reprobe.mjs";
+
+/** Rank for GitHub `priority:<value>` labels; no label ranks 4. */
+const GITHUB_PRIORITY_RANKS = Object.freeze({
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+});
+const GITHUB_NO_PRIORITY = 4;
+
+/** Rank for Jira priority names, across the default and legacy schemes. */
+const JIRA_PRIORITY_RANKS = Object.freeze({
+  highest: 0,
+  blocker: 0,
+  high: 1,
+  critical: 1,
+  medium: 2,
+  major: 2,
+  low: 3,
+  minor: 3,
+  lowest: 4,
+  trivial: 4,
+});
+const JIRA_UNKNOWN_PRIORITY = 5;
+
+/** Linear native priority: 1 urgent .. 4 low, and 0 means no priority. */
+const LINEAR_NO_PRIORITY = 4;
+
+/** Linear workflow state types that leave a child finished. */
+const LINEAR_FINISHED_STATE_TYPES = new Set(["completed", "canceled"]);
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function text(value) {
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * A stable id as a string, or null. Numeric GitHub ids become strings so every
+ * comparison in this module is string-to-string.
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+function idOrNull(value) {
+  if (typeof value === "string" && value.trim().length > 0) {
+    return value.trim();
+  }
+  return Number.isSafeInteger(value) ? String(value) : null;
+}
+
+/**
+ * Label names from strings, `{name}` objects or a GraphQL `{nodes}` connection.
+ * @param {unknown} labels
+ * @returns {string[]}
+ */
+function labelNames(labels) {
+  const list = Array.isArray(labels)
+    ? labels
+    : Array.isArray(labels?.nodes)
+      ? labels.nodes
+      : [];
+  return list
+    .map(label => (typeof label === "string" ? label : text(label?.name)))
+    .map(label => label.trim())
+    .filter(label => label.length > 0);
+}
+
+/**
+ * The `repo:<name>` labels, lowercased, as `repo-scope-split` reads them.
+ * @param {readonly string[]} labels
+ * @returns {string[]}
+ */
+function repoLabelsOf(labels) {
+  return labels
+    .map(label => label.toLowerCase())
+    .filter(label => label.startsWith("repo:") && label.length > 5);
+}
+
+/**
+ * Flatten an Atlassian Document Format node to plain text, one line per block.
+ * A string description (the Markdown some access paths return) passes through.
+ * @param {unknown} node
+ * @returns {string}
+ */
+function adfText(node) {
+  if (typeof node === "string") return node;
+  if (!node || typeof node !== "object") return "";
+  if (node.type === "text") return text(node.text);
+  if (node.type === "hardBreak") return "\n";
+  const children = Array.isArray(node.content) ? node.content : [];
+  const joiner = node.type === "doc" ? "\n" : "";
+  return children.map(adfText).join(joiner);
+}
+
+/**
+ * Normalize one GitHub REST issue row. Returns null for a pull-request row,
+ * which the issues endpoint returns alongside issues and which is never a
+ * dispatchable leaf.
+ * @param {Record<string, any>} issue - REST `issues` list row
+ * @param {{ repo?: string }} [options] - `owner/repo`, else read from repository_url
+ * @returns {ReturnType<typeof shape> | null}
+ */
+export function normalizeGithubIssue(issue, options = {}) {
+  if (!issue || issue.pull_request) return null;
+  const labels = labelNames(issue.labels);
+  const ranks = labels
+    .map(label => label.toLowerCase())
+    .filter(label => label.startsWith("priority:"))
+    .map(label => GITHUB_PRIORITY_RANKS[label.slice("priority:".length)])
+    .filter(rank => rank !== undefined);
+  const repo =
+    text(options.repo) || text(issue.repository_url).split("/repos/")[1] || "";
+  const summary = issue.sub_issues_summary;
+  const assignee = issue.assignee ?? issue.assignees?.[0] ?? null;
+
+  return shape({
+    ref: `${repo}#${issue.number}`,
+    title: text(issue.title),
+    // GitHub "me" is the login (`gh api user --jq .login`), so match on it.
+    assigneeId: idOrNull(assignee?.login),
+    priorityRank: ranks.length > 0 ? Math.min(...ranks) : GITHUB_NO_PRIORITY,
+    createdAt: text(issue.created_at),
+    labels,
+    body: text(issue.body),
+    // Authors are trusted by stable id, never by login (ready-role-filing).
+    authorId: idOrNull(issue.user?.id),
+    isContainer: Number(summary?.total ?? 0) > Number(summary?.completed ?? 0),
+  });
+}
+
+/**
+ * Normalize one Jira REST/MCP issue. An epic (hierarchy level above 0) or an
+ * issue with any subtask not yet in the done category is a container.
+ * @param {Record<string, any>} issue - Issue with `key` and `fields`
+ * @returns {ReturnType<typeof shape>}
+ */
+export function normalizeJiraIssue(issue) {
+  const fields = issue?.fields ?? {};
+  const labels = labelNames(fields.labels);
+  const priority = text(fields.priority?.name).trim().toLowerCase();
+  const type = fields.issuetype ?? {};
+  const openSubtasks = (Array.isArray(fields.subtasks) ? fields.subtasks : [])
+    .map(sub => sub?.fields?.status?.statusCategory?.key)
+    .filter(category => category !== "done");
+
+  return shape({
+    ref: text(issue?.key),
+    title: text(fields.summary),
+    assigneeId: idOrNull(fields.assignee?.accountId),
+    priorityRank: JIRA_PRIORITY_RANKS[priority] ?? JIRA_UNKNOWN_PRIORITY,
+    createdAt: text(fields.created),
+    labels,
+    body: adfText(fields.description),
+    authorId: idOrNull(fields.reporter?.accountId ?? fields.creator?.accountId),
+    isContainer:
+      Number(type.hierarchyLevel ?? 0) > 0 ||
+      text(type.name).toLowerCase() === "epic" ||
+      openSubtasks.length > 0,
+  });
+}
+
+/**
+ * Normalize one Linear GraphQL issue. An issue with any child not completed
+ * or canceled is a container.
+ * @param {Record<string, any>} issue - Issue node
+ * @returns {ReturnType<typeof shape>}
+ */
+export function normalizeLinearIssue(issue) {
+  const native = Number(issue?.priority ?? 0);
+  const children = Array.isArray(issue?.children?.nodes)
+    ? issue.children.nodes
+    : Array.isArray(issue?.children)
+      ? issue.children
+      : [];
+  const labels = labelNames(issue?.labels);
+
+  return shape({
+    ref: text(issue?.identifier),
+    title: text(issue?.title),
+    assigneeId: idOrNull(issue?.assignee?.id),
+    priorityRank:
+      Number.isInteger(native) && native >= 1 && native <= 4
+        ? native - 1
+        : LINEAR_NO_PRIORITY,
+    createdAt: text(issue?.createdAt),
+    labels,
+    body: text(issue?.description),
+    authorId: idOrNull(issue?.creator?.id),
+    isContainer: children.some(
+      child => !LINEAR_FINISHED_STATE_TYPES.has(child?.state?.type)
+    ),
+  });
+}
+
+/**
+ * The one item shape every normalizer returns, in a fixed key order.
+ * @param {{ ref: string, title: string, assigneeId: string | null, priorityRank: number, createdAt: string, labels: string[], body: string, authorId: string | null, isContainer: boolean }} input
+ */
+function shape(input) {
+  return {
+    ref: input.ref,
+    title: input.title,
+    assigneeId: input.assigneeId,
+    priorityRank: input.priorityRank,
+    createdAt: input.createdAt,
+    labels: input.labels,
+    body: input.body,
+    authorId: input.authorId,
+    isContainer: input.isContainer,
+    repoLabels: repoLabelsOf(input.labels),
+  };
+}
+
+/**
+ * Why an item may not be dispatched, or null when it may.
+ *
+ * Order matters only for the reason reported: an item can fail several rules,
+ * and "someone else owns it" is the most useful thing to say about it.
+ * @param {Record<string, any>} item
+ * @param {{ me: string | null, trusted: ReadonlySet<string>, humanNeededLabel: string }} context
+ * @returns {string | null}
+ */
+function exclusionReason(item, context) {
+  const assignee = idOrNull(item.assigneeId);
+  if (assignee !== null && assignee !== context.me) return "assigned-to-other";
+  if (item.isContainer === true) return "container";
+  if (
+    isHumanGated({
+      labels: item.labels,
+      body: item.body,
+      comments: item.comments,
+      trustedHumanActorIds: item.trustedHumanActorIds,
+      humanNeededLabel: context.humanNeededLabel,
+    })
+  ) {
+    return "human-gated";
+  }
+  if (
+    context.trusted.size > 0 &&
+    !context.trusted.has(idOrNull(item.authorId))
+  ) {
+    return "untrusted-author";
+  }
+  return null;
+}
+
+/**
+ * @param {Record<string, any>} left
+ * @param {Record<string, any>} right
+ * @returns {number}
+ */
+function compareWithinGroup(left, right) {
+  return (
+    Number(left.priorityRank) - Number(right.priorityRank) ||
+    text(left.createdAt).localeCompare(text(right.createdAt)) ||
+    text(left.ref).localeCompare(text(right.ref))
+  );
+}
+
+/**
+ * Order normalized Ready items for dispatch, mine first.
+ *
+ * Group 0 is assigned to `me`, group 1 unassigned; within a group, priority
+ * rank ascending, then creation time ascending, then ref as a stable
+ * tiebreak. Excluded items keep their input order. With no `me`, every
+ * assigned item is someone else's — the safe direction, since claiming
+ * assigned work steals it.
+ * @param {readonly Record<string, any>[]} items - Normalized items
+ * @param {{ me?: string | null, trustedAuthorIds?: readonly unknown[], humanNeededLabel?: string }} [options]
+ * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
+ */
+export function orderReadyQueue(items, options = {}) {
+  const context = {
+    me: idOrNull(options.me),
+    trusted: new Set(
+      (options.trustedAuthorIds ?? []).map(idOrNull).filter(Boolean)
+    ),
+    humanNeededLabel: options.humanNeededLabel ?? DEFAULT_HUMAN_NEEDED_LABEL,
+  };
+  const judged = (items ?? []).map(item => ({
+    item,
+    reason: exclusionReason(item, context),
+  }));
+  const eligible = judged
+    .filter(one => one.reason === null)
+    .map(one => one.item);
+  const group = item => (idOrNull(item.assigneeId) === null ? 1 : 0);
+
+  return {
+    ordered: [...eligible].sort(
+      (left, right) =>
+        group(left) - group(right) || compareWithinGroup(left, right)
+    ),
+    excluded: judged
+      .filter(one => one.reason !== null)
+      .map(one => ({ ref: one.item.ref, reason: one.reason })),
+  };
+}
+
+/**
+ * Refuse a queue envelope that was not paged to completion.
+ *
+ * The vendor fetch writes `{complete, pages, items}`; anything but a literal
+ * `complete: true` means some pages may be missing, and ordering a partial
+ * queue would dispatch the wrong item with full confidence.
+ * @template T
+ * @param {T} envelope - `{ complete: true, pages, items }`
+ * @returns {T} The same envelope
+ */
+export function assertPagedToCompletion(envelope) {
+  if (envelope?.complete !== true) {
+    throw new Error(
+      "Ready queue was not paged to completion (envelope.complete !== true); refusing to order a partial queue."
+    );
+  }
+  return envelope;
+}

package/plugins/lisa/skills/lisa-automation-status/SKILL.md

@@ -31,6 +31,16 @@ scheduler means the project opted in, so the gardener is compared like any other
 means it is reported `UNSUPPORTED` (opted out), never `MISSING`. This skill stays read-only — it
 infers, it never writes the flag anywhere.
 
+**Locally hosted loops.** When `.lisa.config.json` has a `sessionManager` block, the resolved fleet
+carries one extra opt-in entry, `session-manager`, reported `UNSUPPORTED`. That status is honest:
+`/lisa:setup:session-manager` hosts the manager as a `/loop` in a local tmux session, not on this
+runtime's scheduler, so `/schedule` or Codex automations will never list it, and it is neither
+`MISSING` nor provably `HEALTHY` from here. The manager records every cycle through
+`automation-run-record.mjs` under loop id `session-manager`, so the row still shows its runbook
+(`.lisa/automations/session-manager.runbook.md`), last outcome and history. Pass the entry's reason
+through to the operator: it names the tmux session and says to check liveness with
+`/lisa:session-manager status`. With no `sessionManager` block the entry does not exist.
+
 Resolve the expected project identifier, fleet naming prefix, queue arguments, cadence, and stack-support rules from the same contract used by `setup-automations` and `tear-down-automations`. Do **not** invent a second source of truth for fleet naming or queue resolution.
 
 ## Runtime inspection