@codyswann/lisa 4.83.1 → 4.84.0

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

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

@@ -9,6 +9,10 @@
  * `{complete, pages, items}`; anything but a literal `complete: true` is
  * refused with exit 2, because ordering a partial queue would dispatch the
  * wrong item with full confidence.
+ *
+ * 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.
  * @module session-manager/cli-queue
  */
 import { readFileSync } from "node:fs";
@@ -18,6 +22,7 @@ import {
   normalizeGithubIssue,
   normalizeJiraIssue,
   normalizeLinearIssue,
+  orderBacklogQueue,
   orderReadyQueue,
 } from "../../../scripts/ready-queue-order.mjs";
 import { resolveRole } from "../../../scripts/resolve-lifecycle-role.mjs";
@@ -61,12 +66,12 @@ export function readJsonFile(file) {
 }
 
 /**
- * Fetch every open GitHub issue carrying the ready label, all pages.
+ * 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 {{ items: object[], pages: number }} Normalized items
+ * @returns {string} `owner/repo`
  */
-function fetchGithubQueue(ctx, project) {
+function githubRepo(ctx, project) {
   const merged = { ...project.global?.github, ...project.local?.github };
   const repo =
     ctx.values["github-repo"] ??
@@ -77,6 +82,68 @@ function fetchGithubQueue(ctx, project) {
       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",
@@ -101,24 +168,51 @@ function fetchGithubQueue(ctx, project) {
 }
 
 /**
- * Read a vendor-skill envelope and normalize its raw issues.
- * @param {object} ctx - CLI context
+ * Check one paged envelope and normalize its raw issues.
+ * @param {unknown} envelope - `{complete, pages, items}`
+ * @param {string} where - Where it came from, for messages
  * @param {"jira"|"linear"} tracker - Vendor
  * @returns {{ items: object[], pages: unknown }} Normalized items
  */
-function readEnvelopeQueue(ctx, tracker) {
+function normalizeEnvelope(envelope, where, tracker) {
+  asSetupError(() => assertPagedToCompletion(envelope));
+  if (!Array.isArray(envelope.items)) {
+    throw new CliError(`${where}: items must be an array.`, 2);
+  }
+  return {
+    items: envelope.items.map(NORMALIZERS[tracker]),
+    pages: envelope.pages ?? null,
+  };
+}
+
+/**
+ * Read a vendor-skill envelope and normalize its raw issues. With
+ * `withBacklog`, the envelope must also carry `backlog`, a second
+ * `{complete, pages, items}` envelope held to the same paging rule.
+ * @param {object} ctx - CLI context
+ * @param {"jira"|"linear"} tracker - Vendor
+ * @param {boolean} withBacklog - Whether the backlog tier is required
+ * @returns {{ items: object[], pages: unknown, backlog: { items: object[], pages: unknown } | null }} Normalized items
+ */
+function readEnvelopeQueue(ctx, tracker, withBacklog) {
   const file = ctx.values.input;
   if (!file) {
     throw new CliError(`queue --tracker ${tracker} needs --input <file>.`, 2);
   }
   const envelope = readJsonFile(file);
-  asSetupError(() => assertPagedToCompletion(envelope));
-  if (!Array.isArray(envelope.items)) {
-    throw new CliError(`${file}: items must be an array.`, 2);
+  const ready = normalizeEnvelope(envelope, file, tracker);
+  if (!withBacklog) return { ...ready, backlog: null };
+  if (!envelope.backlog) {
+    throw new CliError(
+      `${file}: sessionManager.backlogPickup is on, so the input needs a ` +
+        `"backlog" envelope {complete:true,pages,items} of open leaf items ` +
+        `in no lifecycle role.`,
+      2
+    );
   }
   return {
-    items: envelope.items.map(NORMALIZERS[tracker]),
-    pages: envelope.pages ?? null,
+    ...ready,
+    backlog: normalizeEnvelope(envelope.backlog, `${file} backlog`, tracker),
   };
 }
 
@@ -126,8 +220,12 @@ function readEnvelopeQueue(ctx, tracker) {
  * `queue --tracker <github|jira|linear>`: the Ready queue, the operator's
  * items first (`sessionManager.operatorIds`), then mine, then unassigned.
  * @param {object} ctx - CLI context
+ * With `sessionManager.backlogPickup` on it also returns the backlog tier,
+ * ordered the same way and always dispatched after every Ready item.
+ * @param {object} ctx - CLI context
  * @returns {Promise<{ json: object }>}
- *   `{tracker,me,operators,total,pages,ordered,excluded}`
+ *   `{tracker,me,operators,total,pages,ordered,excluded,backlogPickup[,
+ *   backlogTotal,backlogPages,backlogOrdered,backlogExcluded]}`
  */
 export async function queue(ctx) {
   const tracker = ctx.values.tracker;
@@ -136,19 +234,48 @@ export async function queue(ctx) {
   }
   const project = loadProject(ctx.root);
   const config = validOrAbsent(project);
-  const { items, pages } =
+  const backlogPickup = config?.backlogPickup === true;
+  const { items, pages, backlog } =
     tracker === "github"
-      ? fetchGithubQueue(ctx, project)
-      : readEnvelopeQueue(ctx, tracker);
-  const me = ctx.values.me ?? (await readLedger(ctx.root)).control.me ?? null;
+      ? {
+          ...fetchGithubQueue(ctx, project),
+          backlog: backlogPickup ? fetchGithubBacklog(ctx, project) : null,
+        }
+      : readEnvelopeQueue(ctx, tracker, backlogPickup);
+  const ledger = await readLedger(ctx.root);
+  const me = ctx.values.me ?? ledger.control.me ?? null;
   const operators = config?.operatorIds ?? [];
-  const order = orderReadyQueue(items, {
+  const policy = {
     me,
     operators,
     trustedAuthorIds: config?.trustedAuthorIds ?? undefined,
     humanNeededLabel: humanNeededLabel(project, tracker),
+  };
+  const order = orderReadyQueue(items, policy);
+  const json = {
+    tracker,
+    me,
+    operators,
+    total: items.length,
+    pages,
+    ...order,
+    backlogPickup,
+  };
+  if (!backlog) return { json };
+  // 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,
   });
   return {
-    json: { tracker, me, operators, total: items.length, pages, ...order },
+    json: {
+      ...json,
+      backlogTotal: backlogItems.length,
+      backlogPages: backlog.pages,
+      backlogOrdered: tier.ordered,
+      backlogExcluded: tier.excluded,
+    },
   };
 }

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

@@ -117,6 +117,13 @@ Per cycle
       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.
+      With sessionManager.backlogPickup true, also prints backlogTotal,
+      backlogPages, backlogOrdered and backlogExcluded: open leaves in no
+      lifecycle role, same order, always after every ready item; excluded
+      also for blocked-by-open-item and failed-validation-unchanged (the
+      ledger's validationFailures entry matches the item's updatedAt).
+      GitHub fetches them itself; jira|linear need <file>.backlog =
+      {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>]
@@ -124,6 +131,12 @@ Per cycle
   ledger clear-question <ref>
   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
+      Caches a backlog item's failed validation; queue skips it until the
+      item's updatedAt changes.
+  ledger validation-cleared <ref>
+      Forgets that failure: after a promotion, or by hand to have the next
+      cycle re-validate an item without editing it. stdout {cleared}.
   ledger control [--paused true|false] [--max-workers <n>|none] [--me <id>|none]
   route [--reply-to <telegram message id>] [--owner <name>] STDIN: message
       stdout {kind:"answer",ref,body[,message]} | {kind:"command",name,...}

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

@@ -67,6 +67,7 @@ export const SESSION_MANAGER_DEFAULTS = Object.freeze({
  *   notify: NotifyBlock,
  *   trustedAuthorIds: string[] | null,
  *   operatorIds?: string[] | null,
+ *   backlogPickup?: boolean,
  * }} SessionManagerConfig
  * @typedef {{
  *   name: string,