@codyswann/lisa 4.74.8 → 4.75.0

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

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * Shared read-only run-history projection for `/lisa:automation-status`.
+ *
+ * The durable run-outcome substrate (RBC-3, `automation-run-record.mjs`) stores
+ * one bounded JSONL file per registered loop under `.lisa/automations/runs/`.
+ * This module turns that substrate — plus the checked-in per-loop runbook
+ * (`automation-runbook-contract`) — into the per-item display fields both
+ * runtime adapters attach to their status rows, so the Codex and Claude
+ * adapters never diverge on how the contract, last outcome, and bounded history
+ * are rendered.
+ *
+ * STRICTLY READ-ONLY: it stats the runbook and reads the run-record file. It
+ * never creates the runs directory, a runbook, or a run record — a status read
+ * must leave the fleet byte-identical.
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  automationRunQuarantinePath,
+  automationRunRecordPath,
+  readAutomationRunRecords,
+} from "./automation-run-record.mjs";
+
+/**
+ * Inline history cap: the newest N outcomes are listed, the remainder is only
+ * counted. A bounded view of an already-bounded file, with the trim stated in
+ * the output rather than applied silently.
+ */
+export const AUTOMATION_RUN_HISTORY_DISPLAY_LIMIT = 5;
+
+/** The recorded outcome that signals a loop could not finish its own work. */
+export const RECOVERY_REQUIRED_OUTCOME = "recovery-required";
+
+/**
+ * How many trailing `recovery-required` runs in a row flip a loop to `FAILING`.
+ * The RBC-5 acceptance criteria pin "last three runs" as the escalation
+ * trigger; that wins over the ticket prose's looser "five in a row" pattern.
+ */
+export const RECOVERY_REQUIRED_ESCALATION_THRESHOLD = 3;
+
+const RUNBOOK_NOT_SCAFFOLDED_LINE =
+  "not scaffolded — run /lisa:setup-automations";
+const NO_RECORDED_RUNS_LINE = "no recorded runs yet";
+
+/**
+ * @typedef {{
+ *   readonly ts: string
+ *   readonly outcome: string
+ *   readonly summary: string
+ * }} AutomationLastOutcome
+ *
+ * @typedef {{
+ *   readonly runbook: string
+ *   readonly lastOutcome?: AutomationLastOutcome
+ *   readonly outcomeHistory: readonly string[]
+ *   readonly olderRecordCount: number
+ *   readonly recoveryRequiredStreak: number
+ *   readonly recoverySummaries: readonly string[]
+ *   readonly skippedCorruptLines: number
+ *   readonly recordsPath: string
+ *   readonly quarantinePath: string
+ * }} AutomationRunDisplay
+ */
+
+/**
+ * Resolve the read-only run-history display fields for one registered loop.
+ *
+ * @param {{
+ *   readonly projectRoot?: string
+ *   readonly loopId: string
+ *   readonly runbookPath?: string
+ * }} input
+ * @returns {Promise<AutomationRunDisplay>}
+ */
+export async function resolveAutomationRunDisplay(input) {
+  const projectRoot = path.resolve(input.projectRoot ?? process.cwd());
+  const runbook = await resolveRunbookLine(projectRoot, input.runbookPath);
+  const recordsPath = automationRunRecordPath(projectRoot, input.loopId);
+  const { records, skippedCorruptLines } =
+    await readAutomationRunRecords(recordsPath);
+
+  const newestFirst = records.toReversed();
+  const latest = records.at(-1);
+  const lastOutcome = latest
+    ? { ts: latest.ts, outcome: latest.outcome, summary: latest.summary }
+    : undefined;
+  const outcomeHistory = newestFirst
+    .slice(0, AUTOMATION_RUN_HISTORY_DISPLAY_LIMIT)
+    .map(record => record.outcome);
+  const olderRecordCount = Math.max(
+    0,
+    records.length - AUTOMATION_RUN_HISTORY_DISPLAY_LIMIT
+  );
+  const trailingRecovery = collectTrailingRecoveryRuns(records);
+
+  return {
+    runbook,
+    lastOutcome,
+    outcomeHistory,
+    olderRecordCount,
+    recoveryRequiredStreak: trailingRecovery.length,
+    recoverySummaries: trailingRecovery.map(record => record.summary),
+    skippedCorruptLines,
+    recordsPath,
+    quarantinePath: automationRunQuarantinePath(projectRoot, input.loopId),
+  };
+}
+
+/**
+ * Report a ledger holding rows this module cannot read as drift.
+ *
+ * `skippedCorruptLines` was computed on every read, returned by both the read
+ * and the write path, and destructured by every caller — and printed by none
+ * of them. A counter nobody reads is not a control, and this one guarded the
+ * only evidence that a loop's own history had been damaged (#2578).
+ *
+ * `DRIFTED`, not `FAILING`: the ledger is local scheduler state, and rows it
+ * cannot read say nothing about whether the loop is doing its job. Escalating
+ * it to a loop failure would misattribute a storage problem to the automation
+ * and bury the real health signal underneath it.
+ * @param {AutomationRunDisplay | undefined} runDisplay
+ * @returns {{ readonly status: "DRIFTED", readonly summary: string, readonly remediation: string } | null}
+ */
+export function resolveLedgerIntegrityFinding(runDisplay) {
+  if (!runDisplay || runDisplay.skippedCorruptLines < 1) {
+    return null;
+  }
+  return {
+    status: "DRIFTED",
+    summary: `${runDisplay.skippedCorruptLines} stored run record(s) in this loop's history cannot be read`,
+    remediation: `Open ${runDisplay.recordsPath} and look at the lines that are not valid run records. They are left exactly as written and are left out of the history above, so the outcomes shown are an incomplete picture. Nothing deletes them: each is copied to ${runDisplay.quarantinePath} before the history bound would evict it. Fix or remove those lines and this stops being reported.`,
+  };
+}
+
+/**
+ * Force a `FAILING` verdict when a loop has recorded three or more consecutive
+ * `recovery-required` runs — the fleet-health signal the scheduler surface
+ * cannot see on its own. Returns a run-signal-shaped escalation, or null when
+ * the streak is below the threshold.
+ *
+ * @param {AutomationRunDisplay | undefined} runDisplay
+ * @returns {{ readonly status: "FAILING", readonly summary: string, readonly remediation: string } | null}
+ */
+export function resolveRecoveryEscalation(runDisplay) {
+  if (
+    !runDisplay ||
+    runDisplay.recoveryRequiredStreak < RECOVERY_REQUIRED_ESCALATION_THRESHOLD
+  ) {
+    return null;
+  }
+
+  // Number the citations rather than joining on a delimiter: recorded summaries
+  // carry their own `;` and `.`, so a `; `-separated list is ambiguous. `(1) …
+  // (2) …` stays legible no matter what punctuation a summary contains.
+  const citations = runDisplay.recoverySummaries
+    .map((summary, index) => `(${index + 1}) ${summary}`)
+    .join(" ");
+  return {
+    status: "FAILING",
+    summary: `the last ${runDisplay.recoveryRequiredStreak} recorded runs all required recovery`,
+    remediation: `Repeated recovery-required runs — ${citations} Inspect the loop's runbook and the cited runs, fix the recurring failure, then let the next scheduled run confirm recovery.`,
+  };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {string | undefined} runbookPath
+ * @returns {Promise<string>}
+ */
+async function resolveRunbookLine(projectRoot, runbookPath) {
+  if (!runbookPath) {
+    return RUNBOOK_NOT_SCAFFOLDED_LINE;
+  }
+  const scaffolded = await runbookIsScaffolded(
+    path.join(projectRoot, runbookPath)
+  );
+  return scaffolded ? runbookPath : RUNBOOK_NOT_SCAFFOLDED_LINE;
+}
+
+/**
+ * Read-only existence check for a checked-in runbook. Any stat failure — the
+ * file is absent, unreadable, or not a regular file — degrades to "not
+ * scaffolded" so the status read never implies health it could not confirm and
+ * never throws mid-report.
+ *
+ * @param {string} runbookAbsolutePath
+ * @returns {Promise<boolean>}
+ */
+async function runbookIsScaffolded(runbookAbsolutePath) {
+  try {
+    const stat = await fs.stat(runbookAbsolutePath);
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {readonly import("./automation-run-record.mjs").AutomationRunRecord[]} records
+ * @returns {readonly import("./automation-run-record.mjs").AutomationRunRecord[]} trailing recovery-required runs, newest first
+ */
+function collectTrailingRecoveryRuns(records) {
+  const trailing = [];
+  for (let index = records.length - 1; index >= 0; index -= 1) {
+    if (records[index].outcome !== RECOVERY_REQUIRED_OUTCOME) {
+      break;
+    }
+    trailing.push(records[index]);
+  }
+  return trailing;
+}
+
+export { RUNBOOK_NOT_SCAFFOLDED_LINE, NO_RECORDED_RUNS_LINE };

package/plugins/lisa-devin/scripts/automation-status-unrecorded-runs.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * Detect registered-loop cycles that ran and recorded nothing.
+ *
+ * The Automation Runbook Contract requires every run of a registered loop to
+ * end in exactly one of six recorded outcomes, but the recorder is invoked only
+ * by prose instruction inside each loop's `SKILL.md`. A cycle that finishes
+ * without running it appends no row, and an absent row is ambiguous in the one
+ * way that matters: it looks identical to a cycle that never ran.
+ *
+ * That ambiguity is not merely an audit gap. Cycles read the ledger tail to
+ * decide whether the lane was already worked, so a missing row feeds back into
+ * selection — the next cycle sees stale activity, concludes the lane is
+ * unworked, and re-picks the rung a peer is already holding.
+ *
+ * This module resolves the ambiguity with a signal the loop does not control:
+ * the scheduler's own last-run time. A row written by a cycle necessarily
+ * postdates that cycle's start, so a newest row older than the last scheduler
+ * run means the run in between recorded nothing. Neither side can fake it —
+ * the scheduler timestamp is written by the runtime, and the ledger timestamp
+ * by the recorder.
+ *
+ * Reporting only, never blocking, per the contract's own escape: "If recording
+ * still fails, degrade, never abort." Every unreadable input degrades to `null`
+ * rather than to a finding, because a detector that guesses would poison the
+ * same selection loop it exists to protect.
+ */
+
+/**
+ * @typedef {{
+ *   readonly missedCycles: number
+ *   readonly schedulerLastRunAt: string
+ *   readonly ledgerLastRecordAt: string | null
+ *   readonly summary: string
+ *   readonly remediation: string
+ * }} UnrecordedRunFinding
+ */
+
+/**
+ * Remediation text shared by both finding shapes.
+ *
+ * It names the contract rather than the script because the omission is a
+ * skipped step in the loop, not a broken recorder — a broken recorder reports
+ * itself through the degradation path this module deliberately leaves alone.
+ */
+const UNRECORDED_RUN_REMEDIATION =
+  "The loop ran without recording an outcome. Confirm the loop's SKILL.md " +
+  "still ends every path by invoking `automation-run-record.mjs`, including " +
+  "the paths that find no work, per the automation-runbook-contract rule.";
+
+/**
+ * Whether a scheduled run finished without appending a run record.
+ *
+ * Tolerance is one full cadence, not a fixed grace period. The scheduler's
+ * `lastRunAt` may be stamped at either end of a cycle depending on runtime, and
+ * a cycle can legitimately run for many minutes, so anything tighter would
+ * report a slow-but-honest loop as a silent one. A full cadence cannot be
+ * crossed by a single well-behaved run: it means an entire scheduled cycle came
+ * and went between the newest row and the newest run.
+ *
+ * @param {{
+ *   readonly schedulerLastRunAt?: string | null
+ *   readonly ledgerLastRecordAt?: string | null
+ *   readonly hasRunbook?: boolean
+ *   readonly cadenceMs?: number | null
+ * }} input - Scheduler-side run time, ledger-side newest record, and cadence.
+ * @returns {UnrecordedRunFinding | null} The finding, or `null` when the
+ *   comparison cannot be made from trustworthy inputs.
+ */
+export function resolveUnrecordedRunFinding(input) {
+  const cadenceMs = input.cadenceMs;
+  if (!cadenceMs || !Number.isFinite(cadenceMs) || cadenceMs <= 0) {
+    return null;
+  }
+
+  // No scheduler timestamp means the runtime never reported a run, which is
+  // indistinguishable from a loop registered moments ago. Silence here is the
+  // honest answer, and `classifyAutomationRunSignal` already reports the
+  // missing metadata separately.
+  if (!input.schedulerLastRunAt) {
+    return null;
+  }
+  const schedulerLastRun = Date.parse(input.schedulerLastRunAt);
+  if (Number.isNaN(schedulerLastRun)) {
+    return null;
+  }
+
+  // A loop with no runbook is not yet under the contract; `automation-status`
+  // reports the un-scaffolded runbook itself, and stacking a second finding on
+  // it would blame the loop for a setup step it never took.
+  if (input.hasRunbook === false) {
+    return null;
+  }
+
+  if (!input.ledgerLastRecordAt) {
+    return {
+      missedCycles: 1,
+      schedulerLastRunAt: input.schedulerLastRunAt,
+      ledgerLastRecordAt: null,
+      summary: `scheduler reports a run at ${input.schedulerLastRunAt} but the ledger holds no record at all`,
+      remediation: UNRECORDED_RUN_REMEDIATION,
+    };
+  }
+
+  const ledgerLastRecord = Date.parse(input.ledgerLastRecordAt);
+  if (Number.isNaN(ledgerLastRecord)) {
+    return null;
+  }
+
+  const gapMs = schedulerLastRun - ledgerLastRecord;
+  if (gapMs <= cadenceMs) {
+    return null;
+  }
+
+  const missedCycles = Math.floor(gapMs / cadenceMs);
+  return {
+    missedCycles,
+    schedulerLastRunAt: input.schedulerLastRunAt,
+    ledgerLastRecordAt: input.ledgerLastRecordAt,
+    summary: `${missedCycles} scheduled ${
+      missedCycles === 1 ? "run" : "runs"
+    } recorded no outcome (newest record ${input.ledgerLastRecordAt}, last run ${input.schedulerLastRunAt})`,
+    remediation: UNRECORDED_RUN_REMEDIATION,
+  };
+}
+
+export { UNRECORDED_RUN_REMEDIATION };

package/plugins/lisa-devin/scripts/blocker-edge-resolution.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * What to do with a dependency edge once its blocker has been judged.
+ *
+ * ## The gap this fills
+ *
+ * `blocker-containment` decides ONE question — given an edge, is it satisfied —
+ * and says so in its own words: it "does not decide when a dependency edge
+ * should exist, dissolve an edge once satisfied, or govern what a surface does
+ * after clearing". Nothing else claimed that job. So a repair pass that ruled a
+ * dependency satisfied moved the STATE and left the EDGE, recording the ruling
+ * as a comment; the next reader parses relations, not prose, and blocks again
+ * (CodySwannGT/lisa#3472). The durable artifact of "this is satisfied" had no
+ * mechanical effect.
+ *
+ * Measured on this repository while writing this: of 11 open `status:blocked`
+ * items carrying a parsable `Blocked by #N`, 5 were held behind blockers that
+ * were all closed.
+ *
+ * ## Why closure is not the test, and neither is "it is finished"
+ *
+ * Two different mistakes converge on the same wrong answer.
+ *
+ * The first is testing a state NAME. That half is already fixed: the triage
+ * gate now clear-checks by containment, because a promotion workflow types its
+ * merged-and-deployed rungs `started`, so `Done` strands every dependent behind
+ * work already merged where the dependent needs it.
+ *
+ * The second is treating CLOSED as satisfied. An `is blocked by` edge is a
+ * DEVELOPMENT dependency: it is satisfied when the blocker's code is on the
+ * branch this work builds from. A blocker can be closed with no code — and a
+ * blocker closed `NOT_PLANNED` is the sharp case, because it means the thing
+ * depended on will never be built. Dissolving that edge silently converts "what
+ * we needed is cancelled" into "we are unblocked", which is the same wrong-write
+ * family as CodySwannGT/lisa#3479, where a reason-blind repair would have
+ * stamped a production terminal on abandoned work. So an abandoned blocker
+ * ESCALATES to a human rather than dissolving or silently holding forever:
+ * somebody has to decide whether the dependent still makes sense.
+ *
+ * ## What this module does not decide
+ *
+ * How an edge is dissolved on a given tracker. That is vendor work with its own
+ * hazard: on Linear, `issueRelationCreate` CONVERTS an existing relation rather
+ * than adding one (CodySwannGT/lisa#3605), so a writer that "updates" an edge
+ * can destroy a different one. This module returns a decision; the vendor
+ * surface performs it and reads it back.
+ * @module blocker-edge-resolution
+ */
+
+/** Every action a surface may take on a judged edge. */
+export const EDGE_ACTIONS = Object.freeze(["dissolve", "keep", "escalate"]);
+
+/** GitHub's closure reason for work that will deliberately not be done. */
+const NOT_PLANNED = "not_planned";
+
+/**
+ * Decide what happens to one `is blocked by` edge.
+ *
+ * `contained` is the containment verdict — the blocker's merged code is an
+ * ancestor of the branch this work builds from — and it is deliberately the
+ * ONLY positive signal. Everything else here exists to keep a non-containment
+ * signal from being mistaken for one.
+ * @param {{
+ *   contained?: boolean | null,
+ *   blockerState?: string,
+ *   blockerReason?: string,
+ * }} input The containment verdict and the blocker's tracker state.
+ * @returns {{action: string, reason: string}} What to do, and why.
+ */
+export function resolveBlockerEdge(input = {}) {
+  const state = String(input.blockerState ?? "")
+    .trim()
+    .toLowerCase();
+  const reason = String(input.blockerReason ?? "")
+    .trim()
+    .toLowerCase();
+
+  // Checked BEFORE containment, because an abandoned blocker whose branch
+  // happens to contain some earlier commit of its own is still abandoned. The
+  // question a human has to answer is whether the dependent still makes sense,
+  // and a containment true would silently answer it for them.
+  if (state === "closed" && reason === NOT_PLANNED) {
+    return {
+      action: "escalate",
+      reason:
+        "the blocker was closed as NOT PLANNED, so the work this item depends on will never be " +
+        "delivered. Dissolving the edge would read as 'unblocked' when nothing was built, and " +
+        "holding it forever hides a decision somebody has to make: does this item still make sense " +
+        "without its blocker? That is a human call, not a sweep's.",
+    };
+  }
+
+  if (input.contained === true) {
+    return {
+      action: "dissolve",
+      reason:
+        "the blocker's merged code is present on the branch this item builds from, so the " +
+        "development dependency is satisfied. Remove the edge in the same write that records the " +
+        "ruling, and read it back — a state move plus a comment is a claim about a clearance, not " +
+        "a clearance, and the next reader parses relations rather than prose.",
+    };
+  }
+
+  if (input.contained === null || input.contained === undefined) {
+    return {
+      action: "escalate",
+      reason:
+        "containment could not be computed for this blocker, so whether the dependency is satisfied " +
+        "is unknown. An unknown is not a clearance: dissolving here would be a guess in the " +
+        "direction that releases work, which is the direction nothing downstream re-checks.",
+    };
+  }
+
+  return {
+    action: "keep",
+    reason:
+      state === "closed"
+        ? "the blocker is closed but its code is not on the branch this item builds from. Closing an " +
+          "item is not the same as shipping it, and an `is blocked by` edge is a development " +
+          "dependency, not a bookkeeping one."
+        : "the blocker's code is not yet on the branch this item builds from, so the dependency " +
+          "still holds.",
+  };
+}
+
+/**
+ * Decide a whole set of edges, and say whether the item can proceed.
+ *
+ * An item proceeds only when every edge dissolves. One escalation holds the
+ * item — reporting it, rather than proceeding on the majority verdict, is what
+ * keeps a single unanswerable edge from being rounded away.
+ * @param {readonly object[]} edges Per-edge inputs, in the item's own order.
+ * @returns {{
+ *   proceed: boolean,
+ *   decisions: {action: string, reason: string}[],
+ *   escalations: number,
+ * }} The per-edge decisions and whether the item is free to move.
+ */
+export function resolveBlockerEdges(edges = []) {
+  const decisions = (edges ?? []).map(edge => ({
+    ...edge,
+    ...resolveBlockerEdge(edge),
+  }));
+  return {
+    proceed:
+      decisions.length > 0 && decisions.every(one => one.action === "dissolve"),
+    decisions,
+    escalations: decisions.filter(one => one.action === "escalate").length,
+  };
+}