@codyswann/lisa 4.83.1 → 4.84.0

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/ledger.mjs

@@ -81,6 +81,17 @@ const FINISH_STATUSES = new Set(["DONE", "FAILED"]);
  * @property {number} version - Shape version
  * @property {Record<string, LedgerItem>} items - Items keyed by ref
  * @property {{paused: boolean, maxWorkers: number|null, me: string|null}} control - Operator controls
+ * @property {Record<string, ValidationFailure>} validationFailures - Backlog
+ *   items that failed validation, keyed by ref, so an unchanged item is not
+ *   re-validated every cycle
+ */
+
+/**
+ * A backlog item's last failed validation.
+ * @typedef {object} ValidationFailure
+ * @property {string} updatedAt - The item's tracker `updatedAt` when it failed
+ * @property {string} at - When the failure was recorded (ISO)
+ * @property {string|null} reason - Short summary of the failing gates
  */
 
 /**
@@ -119,6 +130,7 @@ function emptyLedger() {
     version: LEDGER_VERSION,
     items: {},
     control: { paused: false, maxWorkers: null, me: null },
+    validationFailures: {},
   };
 }
 
@@ -159,6 +171,7 @@ export async function readLedger(projectRoot, seams) {
     version: parsed.version ?? empty.version,
     items: parsed.items ?? {},
     control: { ...empty.control, ...parsed.control },
+    validationFailures: parsed.validationFailures ?? {},
   };
 }
 
@@ -384,6 +397,63 @@ export function recordFinish(projectRoot, { ref, status, reason }, seams) {
   });
 }
 
+/**
+ * Remember that a backlog item failed validation at its current tracker
+ * `updatedAt`. The backlog queue skips it until the item changes, so an
+ * unready item costs one validation per edit, not one per cycle.
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string, updatedAt: string, reason?: string|null}} failure - What failed
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<ValidationFailure>} The stored record
+ */
+export function recordValidationFailure(
+  projectRoot,
+  { ref, updatedAt, reason = null },
+  seams
+) {
+  if (typeof ref !== "string" || ref === "") {
+    return Promise.reject(new Error("validation failure needs a ref"));
+  }
+  if (typeof updatedAt !== "string" || updatedAt === "") {
+    return Promise.reject(
+      new Error(
+        "validation failure needs the item's updatedAt; without it the cache could never expire"
+      )
+    );
+  }
+  return updateLedger(projectRoot, seams, (ledger, at) => {
+    const entry = { updatedAt, at, reason: reason || null };
+    return {
+      ledger: {
+        ...ledger,
+        validationFailures: { ...ledger.validationFailures, [ref]: entry },
+      },
+      result: entry,
+    };
+  });
+}
+
+/**
+ * Forget a backlog item's validation failure (it was promoted, or a human
+ * asked for it to be judged again).
+ * @param {string} projectRoot - Absolute project root
+ * @param {{ref: string}} target - Item to forget
+ * @param {LedgerSeams} [seams] - Injected seams
+ * @returns {Promise<{cleared: boolean}>} Whether a record existed
+ */
+export function clearValidationFailure(projectRoot, { ref }, seams) {
+  return updateLedger(projectRoot, seams, ledger => {
+    if (!Object.hasOwn(ledger.validationFailures, ref)) {
+      return { ledger, result: { cleared: false } };
+    }
+    const { [ref]: _removed, ...rest } = ledger.validationFailures;
+    return {
+      ledger: { ...ledger, validationFailures: rest },
+      result: { cleared: true },
+    };
+  });
+}
+
 /**
  * Check a control patch before it is written.
  * @param {{paused?: unknown, maxWorkers?: unknown, me?: unknown}} patch - Patch

package/plugins/lisa-copilot/skills/lisa-session-manager/scripts/session-manager.mjs

@@ -130,6 +130,8 @@ const LEDGER_SPECS = {
   },
   "clear-question": { options: {}, positionals: 1 },
   finish: { options: { status: text, sender: text }, positionals: 1 },
+  "validation-failed": { options: { "updated-at": text }, positionals: 1 },
+  "validation-cleared": { options: {}, positionals: 1 },
   control: {
     options: { paused: text, "max-workers": text, me: text },
     positionals: 0,

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

@@ -68,7 +68,14 @@ writes `$SM`, and pass `--project-root "$ROOT"` (the absolute project root) on e
    "me", spelled as the tracker API returns it: the GitHub **login** (`gh api users/<login> --jq
    .login`), the Jira `accountId`, or the Linear user id (the operator's entry in the team's member
    list, or `viewer.id` only when the operator runs the lookup with their own credential).
-5. `node "$SM/session-manager.mjs" validate --project-root "$ROOT"` must print `valid: true`.
+5. Ask whether to set `sessionManager.backlogPickup` to `true` (default off). When the Ready queue
+   is exhausted and a worker slot is still free, the manager then looks at backlog items (open
+   leaves in no lifecycle role) that nobody else is assigned to, that are not human-held and have
+   no unfinished blocker. Each one that passes the full tracker validation, including the
+   stateless-pickup check, is assigned to the first `operatorIds` entry, moved to Ready and
+   dispatched. Say plainly that this lets the manager start work nobody marked Ready, so it needs
+   `operatorIds` and should go with `trustedAuthorIds` on any tracker outsiders can write to.
+6. `node "$SM/session-manager.mjs" validate --project-root "$ROOT"` must print `valid: true`.
 
 ## Step 3: Store the bot token
 

package/plugins/lisa-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.83.1",
+  "version": "4.84.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cursor/rules/config-resolution-reference.mdc

@@ -740,6 +740,7 @@ have a `.lisa.config.json` and their own `.git` (written as `"root": "."`).
 | `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. |
 | `sessionManager.operatorIds` | no | — | Optional, non-empty list of the people the manager works for, as tracker user ids matched against the **assignee** the same way "me" is: the GitHub **login**, the Jira `accountId`, or the Linear user id, spelled exactly as the tracker API returns it (matching is case-sensitive, so look the OPERATOR up rather than typing from memory: `gh api users/<operator-login> --jq .login` returns the canonical GitHub spelling. Do not use `gh api user`, which returns whoever the credential belongs to — the agent account, when that is the case this key exists for). Dispatch order is assigned to an operator, then to "me" (the tracker credential's identity), then unassigned; items assigned to anyone else are skipped. Set it whenever the tracker credential is not the operator's own (an agent account), or the operator's Ready items are never dispatched. |
+| `sessionManager.backlogPickup` | no | `false` | Opt-in lowest dispatch tier. When the Ready queue is exhausted and capacity remains, the manager considers backlog items (open leaves in no lifecycle role) with the Ready exclusions plus any unfinished blocker; each one that passes the tracker validator (all gates, including the stateless-pickup dry-run) is assigned to the first `operatorIds` entry, moved to Ready in one write, read back and dispatched. A failed validation is cached against the item's `updatedAt`, so it is re-judged only after the item changes. Requires `operatorIds`. |
 
 - **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

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

@@ -29,6 +29,12 @@
  *
  * 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).
+ *
+ * {@link orderBacklogQueue} ranks a second, lower tier: open leaf items in no
+ * lifecycle role, which the session manager may promote to Ready when
+ * `sessionManager.backlogPickup` is on. It applies every Ready exclusion plus
+ * two of its own (an unfinished blocker, an unchanged validation failure), and
+ * its list is always walked after the whole Ready queue.
  * @module ready-queue-order
  */
 
@@ -67,6 +73,9 @@ const LINEAR_NO_PRIORITY = 4;
 /** Linear workflow state types that leave a child finished. */
 const LINEAR_FINISHED_STATE_TYPES = new Set(["completed", "canceled"]);
 
+/** Jira link types whose inward side reads as "this item is blocked by". */
+const JIRA_BLOCKED_BY = /blocked by/i;
+
 /**
  * @param {unknown} value
  * @returns {string}
@@ -88,6 +97,26 @@ function idOrNull(value) {
   return Number.isSafeInteger(value) ? String(value) : null;
 }
 
+/**
+ * A non-negative integer count, 0 for anything else.
+ * @param {unknown} value
+ * @returns {number}
+ */
+function count(value) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : 0;
+}
+
+/**
+ * The rows of an array or a GraphQL `{nodes}` connection.
+ * @param {unknown} list
+ * @returns {any[]}
+ */
+function nodesOf(list) {
+  if (Array.isArray(list)) return list;
+  return Array.isArray(list?.nodes) ? list.nodes : [];
+}
+
 /**
  * Label names from strings, `{name}` objects or a GraphQL `{nodes}` connection.
  * @param {unknown} labels
@@ -160,11 +189,14 @@ export function normalizeGithubIssue(issue, options = {}) {
     assigneeId: idOrNull(assignee?.login),
     priorityRank: ranks.length > 0 ? Math.min(...ranks) : GITHUB_NO_PRIORITY,
     createdAt: text(issue.created_at),
+    updatedAt: text(issue.updated_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),
+    // `blocked_by` in the dependency summary counts only OPEN blockers.
+    openBlockers: count(issue.issue_dependencies_summary?.blocked_by),
   });
 }
 
@@ -182,6 +214,12 @@ export function normalizeJiraIssue(issue) {
   const openSubtasks = (Array.isArray(fields.subtasks) ? fields.subtasks : [])
     .map(sub => sub?.fields?.status?.statusCategory?.key)
     .filter(category => category !== "done");
+  const openBlockers = nodesOf(fields.issuelinks).filter(
+    link =>
+      link?.inwardIssue &&
+      JIRA_BLOCKED_BY.test(text(link.type?.inward)) &&
+      link.inwardIssue.fields?.status?.statusCategory?.key !== "done"
+  ).length;
 
   return shape({
     ref: text(issue?.key),
@@ -189,6 +227,7 @@ export function normalizeJiraIssue(issue) {
     assigneeId: idOrNull(fields.assignee?.accountId),
     priorityRank: JIRA_PRIORITY_RANKS[priority] ?? JIRA_UNKNOWN_PRIORITY,
     createdAt: text(fields.created),
+    updatedAt: text(fields.updated),
     labels,
     body: adfText(fields.description),
     authorId: idOrNull(fields.reporter?.accountId ?? fields.creator?.accountId),
@@ -196,6 +235,7 @@ export function normalizeJiraIssue(issue) {
       Number(type.hierarchyLevel ?? 0) > 0 ||
       text(type.name).toLowerCase() === "epic" ||
       openSubtasks.length > 0,
+    openBlockers,
   });
 }
 
@@ -213,6 +253,13 @@ export function normalizeLinearIssue(issue) {
       ? issue.children
       : [];
   const labels = labelNames(issue?.labels);
+  // Linear has no "blocked by" relation type: B blocked by A is A's `blocks`
+  // relation, read from B as an inverse relation.
+  const openBlockers = nodesOf(issue?.inverseRelations).filter(
+    relation =>
+      relation?.type === "blocks" &&
+      !LINEAR_FINISHED_STATE_TYPES.has(relation.issue?.state?.type)
+  ).length;
 
   return shape({
     ref: text(issue?.identifier),
@@ -223,18 +270,22 @@ export function normalizeLinearIssue(issue) {
         ? native - 1
         : LINEAR_NO_PRIORITY,
     createdAt: text(issue?.createdAt),
+    updatedAt: text(issue?.updatedAt),
     labels,
     body: text(issue?.description),
     authorId: idOrNull(issue?.creator?.id),
     isContainer: children.some(
       child => !LINEAR_FINISHED_STATE_TYPES.has(child?.state?.type)
     ),
+    openBlockers,
   });
 }
 
 /**
  * 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
+ * `updatedAt` keys the backlog tier's validation cache; `openBlockers` counts
+ * dependencies whose blocker is not finished. The Ready tier ignores both.
+ * @param {{ ref: string, title: string, assigneeId: string | null, priorityRank: number, createdAt: string, updatedAt: string, labels: string[], body: string, authorId: string | null, isContainer: boolean, openBlockers: number }} input
  */
 function shape(input) {
   return {
@@ -243,10 +294,12 @@ function shape(input) {
     assigneeId: input.assigneeId,
     priorityRank: input.priorityRank,
     createdAt: input.createdAt,
+    updatedAt: input.updatedAt,
     labels: input.labels,
     body: input.body,
     authorId: input.authorId,
     isContainer: input.isContainer,
+    openBlockers: input.openBlockers,
     repoLabels: repoLabelsOf(input.labels),
   };
 }
@@ -320,7 +373,50 @@ function compareWithinGroup(left, right) {
  * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
  */
 export function orderReadyQueue(items, options = {}) {
-  const context = {
+  const context = orderingContext(options);
+  return rank(items, item => exclusionReason(item, context), context);
+}
+
+/**
+ * Order normalized backlog items — open leaves in no lifecycle role — for
+ * promotion, the tier walked only after the whole Ready queue.
+ *
+ * Every Ready exclusion applies, then two more: an item with an unfinished
+ * blocker (`blocked-by-open-item`) cannot be taken to completion, and an item
+ * that already failed validation at its current `updatedAt`
+ * (`failed-validation-unchanged`, from `validationFailures`) would only fail
+ * again, so it waits until someone edits it. Grouping and ordering match
+ * {@link orderReadyQueue}.
+ * @param {readonly Record<string, any>[]} items - Normalized items
+ * @param {{ me?: string | null, operators?: readonly unknown[], trustedAuthorIds?: readonly unknown[], humanNeededLabel?: string, validationFailures?: Readonly<Record<string, { updatedAt?: string }>> }} [options]
+ * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
+ */
+export function orderBacklogQueue(items, options = {}) {
+  const context = orderingContext(options);
+  const failures = options.validationFailures ?? {};
+  return rank(
+    items,
+    item => {
+      const reason = exclusionReason(item, context);
+      if (reason !== null) return reason;
+      if (count(item.openBlockers) > 0) return "blocked-by-open-item";
+      const failed = Object.hasOwn(failures, item.ref)
+        ? failures[item.ref]
+        : null;
+      return failed && text(failed.updatedAt) === text(item.updatedAt)
+        ? "failed-validation-unchanged"
+        : null;
+    },
+    context
+  );
+}
+
+/**
+ * The identities and policy every ordering judges against.
+ * @param {{ me?: string | null, operators?: readonly unknown[], trustedAuthorIds?: readonly unknown[], humanNeededLabel?: string }} options
+ */
+function orderingContext(options) {
+  return {
     me: idOrNull(options.me),
     operators: new Set((options.operators ?? []).map(idOrNull).filter(Boolean)),
     trusted: new Set(
@@ -328,10 +424,17 @@ export function orderReadyQueue(items, options = {}) {
     ),
     humanNeededLabel: options.humanNeededLabel ?? DEFAULT_HUMAN_NEEDED_LABEL,
   };
-  const judged = (items ?? []).map(item => ({
-    item,
-    reason: exclusionReason(item, context),
-  }));
+}
+
+/**
+ * Split items into ordered eligible ones and excluded ones with reasons.
+ * @param {readonly Record<string, any>[] | undefined} items
+ * @param {(item: Record<string, any>) => string | null} judge - Exclusion reason, or null
+ * @param {ReturnType<typeof orderingContext>} context
+ * @returns {{ ordered: Record<string, any>[], excluded: { ref: string, reason: string }[] }}
+ */
+function rank(items, judge, context) {
+  const judged = (items ?? []).map(item => ({ item, reason: judge(item) }));
   const eligible = judged
     .filter(one => one.reason === null)
     .map(one => one.item);

package/plugins/lisa-cursor/skills/lisa-secrets-access/scripts/validate-config.mjs

@@ -819,10 +819,38 @@ export function validateSessionManager(block) {
         ]
       : []),
     ...validateOperatorIds(block.operatorIds),
+    ...validateBacklogPickup(block.backlogPickup, block.operatorIds),
     ...findCredentials(block, "sessionManager"),
   ];
 }
 
+/**
+ * Validate `sessionManager.backlogPickup`: opt-in promotion of validated
+ * backlog items to Ready, assigned to `operatorIds[0]`. Without an operator
+ * there is nobody to assign the promoted item to, so it is refused rather
+ * than promoting work into the agent's own name.
+ * @param {unknown} value The value, if present.
+ * @param {unknown} operatorIds `sessionManager.operatorIds`, if present.
+ * @returns {string[]} Problems found.
+ */
+function validateBacklogPickup(value, operatorIds) {
+  if (value === undefined) return [];
+  if (typeof value !== "boolean") {
+    return [
+      `sessionManager.backlogPickup must be true or false (absent means false).`,
+    ];
+  }
+  const hasOperator =
+    Array.isArray(operatorIds) &&
+    operatorIds.some(id => typeof id === "string" && id.trim() !== "");
+  return value && !hasOperator
+    ? [
+        `sessionManager.backlogPickup needs sessionManager.operatorIds: a ` +
+          `promoted backlog item is assigned to the first operator.`,
+      ]
+    : [];
+}
+
 /**
  * Validate every block this plan introduced.
  * @param {object} cfg Parsed `.lisa.config.json`.

package/plugins/lisa-cursor/skills/lisa-session-manager/SKILL.md

@@ -214,6 +214,17 @@ Skip while `capacity` reports `paused`. Otherwise:
      createdAt, assignee, labels, description, creator and children with their state type.
    - `ordered` is the dispatch order: assigned to an operator, then to "me", then unassigned; each
      group by priority, then age. `excluded` needs no action.
+   - **Backlog tier** (only when `sessionManager.backlogPickup` is `true`). GitHub: `queue` fetches
+     it itself (open issues with no build or PRD lifecycle label). Jira / Linear: also fetch the
+     open leaf items in **no** lifecycle role — Linear workflow state type `backlog` or `unstarted`
+     other than the configured `ready` state; Jira status category "To Do" other than the configured
+     `ready` status — paged to completion, including each item's `updatedAt` / `updated` and its
+     blockers (Linear `inverseRelations` with `type` and the blocking issue's `state.type`; Jira
+     `issuelinks`). Put them in the same input file as
+     `"backlog":{"complete":true,"pages":<n>,"items":[...]}`; `queue` refuses a missing or partial
+     backlog envelope while the key is on. It returns `backlogOrdered` (same grouping and order,
+     minus items with an unfinished blocker and items whose cached validation failure still matches
+     their `updatedAt`) and `backlogExcluded`.
 2. **While `capacity` says `can_spawn`** and items remain, take the next item that has no pending
    question in the ledger:
    1. Read it fully (`lisa-tracker-read`): title, description, labels, project, parent, comments.
@@ -244,6 +255,34 @@ Skip while `capacity` reports `paused`. Otherwise:
         `recovery-required` with that message as the summary. It is not a failed attempt; do not
         dispatch to that repo again until the operator fixes it.
       - any other exit: move the item back to the `ready` role, notify Telegram, continue.
+3. **Backlog tier, lowest priority.** Only when `backlogPickup` is on, every `ordered` item has been
+   taken or skipped, and `capacity` still says `can_spawn`. Ready work always wins: never promote a
+   backlog item while a dispatchable Ready item remains. For the next `backlogOrdered` item with no
+   pending question in the ledger:
+   1. Read it fully (`lisa-tracker-read`). If it gained an assignee who is neither "me" nor an
+      operator, a lifecycle role, open child work, a human hold or an unfinished blocker since the
+      queue was listed, skip it.
+   2. **Validate it** with `lisa-tracker-validate` against the live item (identifier mode, all
+      gates, including the stateless-pickup dry-run). This is what "can be taken to completion"
+      means. On a definitive `FAIL`, record
+      `ledger validation-failed <ref> --updated-at <the item's updatedAt>` with a one-line summary
+      of the failing gates on STDIN, and skip it; the queue leaves it out until the item changes.
+      On could-not-validate (an outage or unreadable item, not a verdict), skip it WITHOUT
+      recording, so the next cycle retries it. Either way, post nothing to Telegram: backlog
+      grooming is not the operator's inbox.
+   3. **Route the repo** as in step 2.2, but never ask: an ambiguous or multi-repo backlog item is
+      skipped.
+   4. **Promote** in ONE `lisa-tracker-write` update: assignee = the first `operatorIds` entry, move
+      to the `ready` role, comment
+      `[lisa-session-manager] Promoted from backlog: validation passed; assigned to the operator.`
+      Read it back with `lisa-tracker-read` and continue only when the role is `ready` and the
+      assignee is that operator. Then `ledger validation-cleared <ref>`.
+   5. Continue with steps 2.3 and 2.4 (claim in the child repo, re-read, spawn, handle the exit)
+      exactly as for a Ready item, with one change: on exit 0, post
+      `[<REF>] promoted from backlog and started in <repo> (<name>)` in place of the plain start
+      notice. Every other exit keeps its step 2.4 handling.
+   A promotion written and read back counts as a state change for the run outcome; a spawn that
+   then fails follows step 2.4's exits (the item stays in Ready, assigned to the operator).
 
 ### 3. Report and record
 

package/plugins/lisa-cursor/skills/lisa-session-manager/references/runbook-template.md

@@ -23,6 +23,12 @@ then to the manager's own tracker identity, then unassigned; within each, by pri
 Items assigned to someone else, containers, human-held items and (when configured) items by
 untrusted authors are skipped. As many as the machine has capacity for.
 
+When `sessionManager.backlogPickup` is on and capacity remains after every Ready item, a lowest tier
+follows: backlog items (open leaves in no lifecycle role) in the same order, minus those with an
+unfinished blocker and those that already failed validation and have not changed since. Each one
+must pass the full tracker validation before it is assigned to the first operator, moved to Ready
+and dispatched like any other item.
+
 ## Scope/bounds
 
 Only the repos listed in `sessionManager.repos` (or this repo). It never writes code itself, never

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

@@ -24,9 +24,11 @@ import {
 import { parseJson, readJsonFile } from "./cli-queue.mjs";
 import {
   clearPendingQuestion,
+  clearValidationFailure,
   readLedger,
   recordFinish,
   recordSpawn,
+  recordValidationFailure,
   setControl,
   setPendingQuestion,
 } from "./ledger.mjs";
@@ -130,6 +132,14 @@ const LEDGER_ACTIONS = {
       reason: stdinText(ctx, "reason", { required: false }),
     });
   },
+  "validation-failed": ctx =>
+    recordValidationFailure(ctx.root, {
+      ref: requirePositional(ctx, "ref"),
+      updatedAt: requireValue(ctx, "updated-at"),
+      reason: stdinText(ctx, "reason", { required: false }),
+    }),
+  "validation-cleared": ctx =>
+    clearValidationFailure(ctx.root, { ref: requirePositional(ctx, "ref") }),
   control: ctx =>
     setControl(
       ctx.root,