@codyswann/lisa 3.30.1 → 3.31.1

package/package.json

@@ -131,7 +131,7 @@
     "ws": ">=8.21.0"
   },
   "name": "@codyswann/lisa",
-  "version": "3.30.1",
+  "version": "3.31.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

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

package/plugins/lisa/.codex-plugin/plugin.json

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

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/preflight-secrets.mjs

@@ -189,11 +189,26 @@ export function report(result, cfg) {
   } else {
     lines.push(
       `Secrets preflight FAILED on surface "${cfg.surface}".`,
-      `These credentials are required and resolve nowhere — not in the`,
-      `environment, not materialized, not in the "${cfg.provider}" grant.`,
+      `These credentials are required and were not found in the surfaces`,
+      `consulted — the environment, the materialized file, and the`,
+      `"${cfg.provider}" grant.`,
       `Extend the grant in the vault (or correct the routing that requires`,
       `them), then start a new session:`
     );
+    // A defaulted provider is the one case where the list above is not the
+    // whole story: no config was found, so the vault a project actually
+    // declares was never contacted. Saying "resolve nowhere" there sends the
+    // reader to grant a credential that was never absent.
+    if (!cfg.configPath) {
+      lines.push(
+        ``,
+        `NOTE: no .lisa.config.json was found at or above the working`,
+        `directory, so provider "${cfg.provider}" is a DEFAULT, not this`,
+        `project's setting. If this project uses a vault, the credential may`,
+        `resolve fine — start the session from the repository root, or check`,
+        `the config is present, before treating this as missing.`
+      );
+    }
   }
   lines.push(``);
   for (const { name, reasons } of result.missing) {

package/plugins/lisa/.codex-plugin/skills/lisa-secrets-access/scripts/surfaces.mjs

@@ -15,7 +15,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 import { bootstrapKeyFor } from "./providers.mjs";
 import { routingFloor } from "./routing-floor.mjs";
@@ -182,6 +182,64 @@ export function materializedPaths(namespace, env = process.env) {
   };
 }
 
+/**
+ * Directories the harness claims are this session's project, best first.
+ *
+ * `CLAUDE_PROJECT_DIR` is set by Claude Code for hook commands, and Lisa's own
+ * hooks already invoke scripts through it. `LISA_PROJECT_DIR` lets a harness
+ * without that convention — or an operator debugging one — say the same thing.
+ *
+ * Blank values are dropped rather than resolved, because an unset variable
+ * expands to the empty string in a shell and `resolve("")` is the current
+ * directory, which would silently re-check a path already searched.
+ *
+ * @param {Record<string, string | undefined>} env - Environment to read.
+ * @returns {string[]} Candidate project roots, deduplicated, best first.
+ */
+function projectAnchors(env) {
+  const raw = [env.LISA_PROJECT_DIR, env.CLAUDE_PROJECT_DIR];
+  return [...new Set(raw.map(value => (value ?? "").trim()).filter(Boolean))];
+}
+
+/**
+ * Find the nearest `.lisa.config.json` at or above `cwd`.
+ *
+ * Looking only in `cwd` made every session started anywhere but the repo root
+ * — a worktree subdirectory, a package folder, a parent wrapper directory —
+ * fall through to the environment defaults and resolve `provider: "env"`. The
+ * preflight then checked the environment, the materialized file, and the "env"
+ * grant, found nothing, and reported the credential as resolving NOWHERE,
+ * having never contacted the configured vault at all.
+ *
+ * That is a false negative wearing a definite answer's clothes, and the
+ * message it produces tells the reader to route the work to blocked. An
+ * obedient agent therefore abandons work over credentials it could have
+ * resolved, and nothing downstream ever re-derives that judgement.
+ *
+ * The walk stops at a repository boundary when it finds one, so a config
+ * belonging to an unrelated parent project is never adopted. If no boundary is
+ * found it stops at the filesystem root, which is what makes the bare-checkout
+ * and wrapper-directory layouts work.
+ *
+ * @param {string} cwd - Directory to start from.
+ * @returns {string | null} Absolute path to the config, or `null` if none.
+ */
+function locateConfig(cwd) {
+  let dir = resolve(cwd);
+  for (;;) {
+    const candidate = join(dir, ".lisa.config.json");
+    if (existsSync(candidate)) return candidate;
+    // Checked AFTER the config, so a repo root carrying one still matches.
+    // Checked as a path rather than a directory because a worktree's `.git` is
+    // a file, and treating that as "not a boundary" would walk out of the
+    // worktree into whatever encloses it.
+    if (existsSync(join(dir, ".git"))) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 /**
  * Read the `secrets` block from `.lisa.config.json`.
  *
@@ -189,10 +247,28 @@ export function materializedPaths(namespace, env = process.env) {
  * provider means the environment *is* the provider. A credentials manager is
  * the preferred path, never a required one.
  * @param {string} [cwd] Directory to look in.
- * @returns {{provider: string, bootstrap: {sources: string[], key: string|null}, require: string[]|null, requiredFloor: readonly string[], rotating: string[], namespace: string, narrow: object, surface: string, routing: {tracker?: string, source?: string}, capabilities: object}} Resolved configuration with defaults applied.
+ * @returns {{provider: string, bootstrap: {sources: string[], key: string|null}, require: string[]|null, requiredFloor: readonly string[], rotating: string[], namespace: string, narrow: object, surface: string, routing: {tracker?: string, source?: string}, capabilities: object, configPath: string|null}} Resolved configuration with defaults applied. `configPath` is the file the values came from, or `null` when none was found and the defaults apply.
  */
 export function readConfig(cwd = process.cwd(), env = process.env) {
-  const path = join(cwd, ".lisa.config.json");
+  // Walk from `cwd` first, then from whatever the harness says the project is.
+  //
+  // A walk from `cwd` alone does not close this. The SessionStart hook that
+  // runs the preflight never changes directory, so its cwd is wherever the
+  // harness happened to spawn it — `$HOME`, a plugin cache — and a walk from
+  // there terminates without finding anything, exactly as a walk from `cwd`
+  // inside the project succeeds. Measured on a session whose credential
+  // resolved fine from its own worktree while the preflight called it
+  // unreachable: every directory from that worktree upward carried a config,
+  // so the hook cannot have been running anywhere in that tree.
+  //
+  // cwd wins when it finds something, because an explicit working directory is
+  // intent and the project variable is only ever a hint about the session.
+  const path =
+    locateConfig(cwd) ??
+    projectAnchors(env)
+      .map(anchor => locateConfig(anchor))
+      .find(found => found !== null) ??
+    null;
   // No repository is a real, supported state — not just a missing file.
   //
   // A Claude Tag channel session runs as the organization with no user account,
@@ -203,7 +279,13 @@ export function readConfig(cwd = process.cwd(), env = process.env) {
   // The only values a config would supply here are the namespace and provider,
   // so they can come from the environment instead. Everything else keeps its
   // default, and an environment that sets neither still gets the old behaviour.
-  if (!existsSync(path)) return withSurface(fromEnvironment(env));
+  //
+  // It stays supported, but it no longer stays SILENT: `configPath: null` lets
+  // a caller say "no config found, assuming provider=env" instead of printing
+  // a defaulted provider that is indistinguishable from a declared one.
+  if (!path) {
+    return withSurface({ ...fromEnvironment(env), configPath: null });
+  }
   let root;
   try {
     root = JSON.parse(readFileSync(path, "utf8"));
@@ -216,7 +298,7 @@ export function readConfig(cwd = process.cwd(), env = process.env) {
   // `secrets` would be a second copy free to disagree with the one every other
   // skill dispatches on.
   const routing = { tracker: root.tracker, source: root.source };
-  if (!cfg) return withSurface({ ...DEFAULTS, routing });
+  if (!cfg) return withSurface({ ...DEFAULTS, routing, configPath: path });
   const provider = cfg.provider ?? DEFAULTS.provider;
   const namespace = assertNamespace(cfg.namespace ?? DEFAULTS.namespace);
   return withSurface({
@@ -229,6 +311,7 @@ export function readConfig(cwd = process.cwd(), env = process.env) {
     narrow: { ...DEFAULTS.narrow, ...(cfg.narrow ?? {}) },
     surface: cfg.surface ?? null,
     routing,
+    configPath: path,
   });
 }
 

package/plugins/lisa/scripts/automation-status-claude-adapter.mjs

@@ -16,9 +16,11 @@ import {
   renderAutomationGroups,
 } from "./automation-status-expected-fleet.mjs";
 import {
+  RUNBOOK_NOT_SCAFFOLDED_LINE,
   resolveAutomationRunDisplay,
   resolveRecoveryEscalation,
 } from "./automation-status-run-history.mjs";
+import { resolveUnrecordedRunFinding } from "./automation-status-unrecorded-runs.mjs";
 
 const CLAUDE_RUNTIME_LABEL = "Claude /schedule";
 const CLAUDE_ACTIVE_STATUSES = new Set([
@@ -241,7 +243,7 @@ function createObservedStatusItem(input) {
   const comparison = input.comparison;
   const observed = comparison.observedAutomation;
   const runDisplay = input.runDisplay;
-  const runSignal = classifyAutomationRunSignal({
+  const primaryRunSignal = classifyAutomationRunSignal({
     expected,
     observedAutomation: observed,
     now: input.now,
@@ -251,6 +253,27 @@ function createObservedStatusItem(input) {
   // the scheduler surface cannot see. It wins over the scheduler run-signal.
   const escalation = resolveRecoveryEscalation(runDisplay);
 
+  // A run the scheduler saw but the ledger did not. Ranked below `runSignal`
+  // on purpose: a disabled or failing scheduler entry EXPLAINS the missing
+  // rows, so reporting the silence over the cause would bury the cause.
+  const unrecorded = resolveUnrecordedRunFinding({
+    schedulerLastRunAt: observed?.lastRunAt,
+    ledgerLastRecordAt: runDisplay?.lastOutcome?.ts ?? null,
+    hasRunbook: runDisplay
+      ? runDisplay.runbook !== RUNBOOK_NOT_SCAFFOLDED_LINE
+      : undefined,
+    cadenceMs: observed
+      ? resolveObservedCadenceMs({ observed, expected })
+      : null,
+  });
+  const runSignal =
+    primaryRunSignal ??
+    (unrecorded && {
+      status: /** @type {const} */ ("DRIFTED"),
+      summary: unrecorded.summary,
+      remediation: unrecorded.remediation,
+    });
+
   const observedDetails = [comparison.observed];
   if (observed?.status) {
     observedDetails.push(`Scheduler status: ${observed.status}`);
@@ -262,6 +285,9 @@ function createObservedStatusItem(input) {
       "Last-run metadata unavailable from Claude /schedule."
     );
   }
+  if (runDisplay?.lastOutcome?.ts) {
+    observedDetails.push(`Newest run record: ${runDisplay.lastOutcome.ts}`);
+  }
   if (observed?.lastRunSummary) {
     observedDetails.push(`Latest summary: ${observed.lastRunSummary}`);
   } else if (observed?.lastRunFailed == null) {
@@ -337,11 +363,10 @@ function classifyAutomationRunSignal(input) {
     return null;
   }
 
-  const cadenceMs =
-    rruleToIntervalMs(observed.observedRRule) ??
-    cadenceLabelToIntervalMs(
-      observed.observedCadence ?? input.expected.expectedCadence
-    );
+  const cadenceMs = resolveObservedCadenceMs({
+    observed,
+    expected: input.expected,
+  });
   if (!cadenceMs) {
     return null;
   }
@@ -364,6 +389,31 @@ function classifyAutomationRunSignal(input) {
   return null;
 }
 
+/**
+ * Milliseconds between scheduled runs, preferring what the scheduler actually
+ * reports over what the fleet expects.
+ *
+ * The observed RRULE wins because a loop re-cadenced on the scheduler is still
+ * a correctly running loop; measuring it against the expected cadence would
+ * manufacture findings out of an intentional change.
+ *
+ * @param {{
+ *   readonly observed: ObservedClaudeAutomation
+ *   readonly expected: { readonly expectedCadence?: string }
+ * }} input - Observed scheduler entry and its expected-fleet counterpart.
+ * @returns {number | null} Interval in milliseconds, or `null` when neither
+ *   side expresses a parseable cadence.
+ */
+function resolveObservedCadenceMs(input) {
+  return (
+    rruleToIntervalMs(input.observed.observedRRule) ??
+    cadenceLabelToIntervalMs(
+      input.observed.observedCadence ?? input.expected.expectedCadence
+    ) ??
+    null
+  );
+}
+
 function coerceClaudeScheduleEntries(scheduleListing) {
   if (!scheduleListing) {
     return [];

package/plugins/lisa/scripts/automation-status-codex-adapter.mjs

@@ -25,9 +25,11 @@ import {
   renderAutomationGroups,
 } from "./automation-status-expected-fleet.mjs";
 import {
+  RUNBOOK_NOT_SCAFFOLDED_LINE,
   resolveAutomationRunDisplay,
   resolveRecoveryEscalation,
 } from "./automation-status-run-history.mjs";
+import { resolveUnrecordedRunFinding } from "./automation-status-unrecorded-runs.mjs";
 
 const CODEx_RUNTIME_LABEL = "Codex automations";
 const RUN_TIMESTAMP_PATTERN = /20\d{2}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z/;
@@ -664,7 +666,7 @@ function createObservedStatusItem(input) {
   const comparison = input.comparison;
   const observed = comparison.observedAutomation;
   const runDisplay = input.runDisplay;
-  const runSignal = classifyAutomationRunSignal({
+  const primaryRunSignal = classifyAutomationRunSignal({
     expected,
     observedAutomation: observed,
     now: input.now,
@@ -674,6 +676,27 @@ function createObservedStatusItem(input) {
   // the raw backing store cannot see. It wins over the scheduler run-signal.
   const escalation = resolveRecoveryEscalation(runDisplay);
 
+  // A run the scheduler saw but the ledger did not. Ranked below
+  // `primaryRunSignal` on purpose: a suspended entry or a broken cwd EXPLAINS
+  // the missing rows, so reporting the silence over the cause would bury it.
+  const unrecorded = resolveUnrecordedRunFinding({
+    schedulerLastRunAt: observed?.lastRunAt,
+    ledgerLastRecordAt: runDisplay?.lastOutcome?.ts ?? null,
+    hasRunbook: runDisplay
+      ? runDisplay.runbook !== RUNBOOK_NOT_SCAFFOLDED_LINE
+      : undefined,
+    cadenceMs: observed
+      ? resolveObservedCadenceMs({ observed, expected })
+      : null,
+  });
+  const runSignal =
+    primaryRunSignal ??
+    (unrecorded && {
+      status: /** @type {const} */ ("DRIFTED"),
+      summary: unrecorded.summary,
+      remediation: unrecorded.remediation,
+    });
+
   const observedDetails = [comparison.observed];
   if (observed?.status) {
     observedDetails.push(`Scheduler status: ${observed.status}`);
@@ -686,6 +709,9 @@ function createObservedStatusItem(input) {
   } else if (observed) {
     observedDetails.push("Last run metadata unavailable.");
   }
+  if (runDisplay?.lastOutcome?.ts) {
+    observedDetails.push(`Newest run record: ${runDisplay.lastOutcome.ts}`);
+  }
   if (observed?.lastRunSummary) {
     observedDetails.push(`Latest summary: ${observed.lastRunSummary}`);
   }
@@ -729,6 +755,29 @@ function composeAutomationSummary(input) {
   return `${input.runSignal.summary}; ${comparisonSummary}`;
 }
 
+/**
+ * Milliseconds between scheduled runs, preferring what the scheduler actually
+ * reports over what the fleet expects.
+ *
+ * The observed RRULE wins because an automation re-cadenced in Codex is still
+ * a correctly running automation; measuring it against the expected cadence
+ * would manufacture findings out of an intentional change.
+ *
+ * @param {{
+ *   readonly observed: { readonly observedRRule?: string | null }
+ *   readonly expected: { readonly expectedCadence?: string }
+ * }} input - Observed automation entry and its expected-fleet counterpart.
+ * @returns {number | null} Interval in milliseconds, or `null` when neither
+ *   side expresses a parseable cadence.
+ */
+function resolveObservedCadenceMs(input) {
+  return (
+    rruleToIntervalMs(input.observed.observedRRule) ??
+    cadenceLabelToIntervalMs(input.expected.expectedCadence) ??
+    null
+  );
+}
+
 function classifyAutomationRunSignal(input) {
   const observed = input.observedAutomation;
   if (!observed) {
@@ -765,9 +814,10 @@ function classifyAutomationRunSignal(input) {
     return null;
   }
 
-  const cadenceMs =
-    rruleToIntervalMs(observed.observedRRule) ??
-    cadenceLabelToIntervalMs(input.expected.expectedCadence);
+  const cadenceMs = resolveObservedCadenceMs({
+    observed,
+    expected: input.expected,
+  });
   if (!cadenceMs) {
     return null;
   }

package/plugins/lisa/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/skills/lisa-secrets-access/scripts/preflight-secrets.mjs

@@ -189,11 +189,26 @@ export function report(result, cfg) {
   } else {
     lines.push(
       `Secrets preflight FAILED on surface "${cfg.surface}".`,
-      `These credentials are required and resolve nowhere — not in the`,
-      `environment, not materialized, not in the "${cfg.provider}" grant.`,
+      `These credentials are required and were not found in the surfaces`,
+      `consulted — the environment, the materialized file, and the`,
+      `"${cfg.provider}" grant.`,
       `Extend the grant in the vault (or correct the routing that requires`,
       `them), then start a new session:`
     );
+    // A defaulted provider is the one case where the list above is not the
+    // whole story: no config was found, so the vault a project actually
+    // declares was never contacted. Saying "resolve nowhere" there sends the
+    // reader to grant a credential that was never absent.
+    if (!cfg.configPath) {
+      lines.push(
+        ``,
+        `NOTE: no .lisa.config.json was found at or above the working`,
+        `directory, so provider "${cfg.provider}" is a DEFAULT, not this`,
+        `project's setting. If this project uses a vault, the credential may`,
+        `resolve fine — start the session from the repository root, or check`,
+        `the config is present, before treating this as missing.`
+      );
+    }
   }
   lines.push(``);
   for (const { name, reasons } of result.missing) {