@codyswann/lisa 2.316.2 → 2.317.0

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/toolchain.mjs

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Decide what a remote environment already has and what it still needs.
+ *
+ * Remote environments arrive with a base image that already provides much of
+ * what a project needs, so the manifest has two entry kinds rather than one:
+ *
+ *   require — assert present, fail setup with a clear message if missing
+ *   install — provision it, pinned and checksummed
+ *
+ * The distinction is not bookkeeping. A base image is **not a contract**: the
+ * vendor can change it. A project quietly depending on a preinstalled tool
+ * should break loudly at setup when that happens, rather than mysteriously
+ * mid-task weeks later. `require` is what converts an implicit assumption into
+ * an explicit check.
+ *
+ * Planning is separated from execution so the whole decision table is testable
+ * without a container, a network, or a real binary anywhere.
+ * @module toolchain
+ */
+
+/**
+ * Compare dotted version strings numerically.
+ *
+ * String comparison gets this wrong in the case that matters: "10" sorts before
+ * "9", so a base-image bump to a newer major would read as a downgrade and pass
+ * a minimum-version check it should fail.
+ * @param {string} a Left version.
+ * @param {string} b Right version.
+ * @returns {number} Negative, zero, or positive.
+ */
+export function compareVersions(a, b) {
+  const left = String(a).split(".").map(Number);
+  const right = String(b).split(".").map(Number);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff) return diff;
+  }
+  return 0;
+}
+
+/**
+ * Pull a dotted version out of whatever a tool prints for `--version`.
+ *
+ * Tools are wildly inconsistent here ("bws 2.1.0", "v20.11.0", "Python 3.12.1"),
+ * and normalising with a regex is more honest than maintaining a per-tool parser
+ * table that silently rots.
+ * @param {string} output Raw `--version` output.
+ * @returns {string|null} The version, or null when none is recognisable.
+ */
+export function extractVersion(output) {
+  const match = /(\d+(?:\.\d+)*)/.exec(String(output ?? ""));
+  return match ? match[1] : null;
+}
+
+/**
+ * Classify one required tool against what the environment actually provides.
+ * @param {object} tool Manifest entry.
+ * @param {{version: string|null, present: boolean}} found Probe result.
+ * @returns {{name: string, action: string, reason: string}} The decision.
+ */
+function planRequired(tool, found) {
+  if (!found.present) {
+    return {
+      name: tool.name,
+      action: "missing",
+      reason:
+        `${tool.name} is required but not present. The base image is not a ` +
+        `contract — if it used to provide this, the vendor has changed it. ` +
+        `Either add an install entry or pin a different image.`,
+    };
+  }
+  if (
+    tool.minVersion &&
+    compareVersions(found.version ?? "0", tool.minVersion) < 0
+  ) {
+    return {
+      name: tool.name,
+      action: "missing",
+      reason:
+        `${tool.name} ${found.version ?? "(unknown)"} is older than the ` +
+        `required ${tool.minVersion}. Presence alone is not enough when a ` +
+        `project depends on a specific version.`,
+    };
+  }
+  return {
+    name: tool.name,
+    action: "present",
+    reason: `${tool.name} ${found.version ?? ""}`.trim(),
+  };
+}
+
+/**
+ * Classify one installable tool against what is already on disk.
+ *
+ * Detect first, install second. Skipping a matching version is what makes setup
+ * and maintenance the same script, and it is the cheap path when a container
+ * resumes from cache rather than being built fresh.
+ * @param {object} tool Manifest entry.
+ * @param {{version: string|null, present: boolean}} found Probe result.
+ * @returns {{name: string, action: string, reason: string}} The decision.
+ */
+function planInstallable(tool, found) {
+  if (!tool.version) {
+    return {
+      name: tool.name,
+      action: "invalid",
+      reason: `${tool.name} has no pinned version. An unpinned install is not reproducible.`,
+    };
+  }
+  if (found.present && found.version === tool.version) {
+    return {
+      name: tool.name,
+      action: "skip",
+      reason: `${tool.name} ${tool.version} already installed`,
+    };
+  }
+  return {
+    name: tool.name,
+    action: "install",
+    reason: found.present
+      ? `${tool.name} ${found.version ?? "(unknown)"} does not match pin ${tool.version}`
+      : `${tool.name} ${tool.version} not installed`,
+  };
+}
+
+/**
+ * Produce the complete plan for a toolchain manifest.
+ * @param {{require?: object[], install?: object[]}} tools Manifest.
+ * @param {(name: string) => {version: string|null, present: boolean}} probe Version probe.
+ * @returns {Array<{name: string, action: string, reason: string}>} Ordered decisions.
+ */
+export function planToolchain(tools, probe) {
+  const plan = [];
+  for (const tool of tools.require ?? [])
+    plan.push(planRequired(tool, probe(tool.name)));
+  for (const tool of tools.install ?? [])
+    plan.push(planInstallable(tool, probe(tool.name)));
+  return plan;
+}
+
+/**
+ * Reject a manifest entry that could install something unverifiable.
+ *
+ * A pinned version with no checksum still trusts whatever the URL serves today.
+ * Requiring both, changed together in one reviewed commit, is what makes an
+ * unexpected archive fail before installation rather than after.
+ * @param {object} tool Manifest entry.
+ */
+export function assertPinned(tool) {
+  if (tool.install === "release-zip") {
+    if (!tool.url || !tool.sha256) {
+      throw new Error(
+        `${tool.name}: a release-zip install needs both url and sha256.\n` +
+          `A version bump must move the checksum in the same reviewed commit.`
+      );
+    }
+    return;
+  }
+  if (tool.install === "npm-global") {
+    if (!tool.package)
+      throw new Error(`${tool.name}: npm-global install needs a package`);
+    return;
+  }
+  throw new Error(
+    `${tool.name}: unknown install method "${tool.install}".\n` +
+      `Supported: release-zip, npm-global.`
+  );
+}

package/plugins/lisa-agy/skills/lisa-setup-remote-env/scripts/verify-remote-env.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * Prove a remote environment is actually configured the way it was meant to be.
+ *
+ * This runs identically whatever provisioned the environment — an API, a driven
+ * browser, or a human pasting emitted config. That is the point: trust comes
+ * from the read-back, not from the mechanism, so the weakest provisioning tier
+ * ends up as trustworthy as the strongest.
+ *
+ * Every assertion is made **without printing a value**. Presence, mode, and
+ * shape are all checkable without revealing content, and an environment proof
+ * that leaks the thing it is proving is not a proof worth having.
+ *
+ * One rule this encodes the hard way: never verify against a vendor's own UI.
+ * A dashboard counter reported zero tasks for an environment that had
+ * demonstrably completed one, because the underlying records carried no
+ * environment identifier. Assert against durable state instead.
+ *
+ * Usage:
+ *   verify-remote-env.mjs
+ * @module verify-remote-env
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+
+import { readRemoteEnvConfig } from "./setup-remote-env.mjs";
+import { extractVersion } from "./toolchain.mjs";
+
+/** Collected results, so every check runs before anything reports failure. */
+const results = [];
+
+/**
+ * Record one assertion.
+ * @param {boolean} ok Whether it held.
+ * @param {string} label What was checked.
+ * @param {string} [detail] Extra context, never a secret value.
+ */
+function check(ok, label, detail = "") {
+  results.push({ ok, label, detail });
+}
+
+/**
+ * Assert a path exists with an exact permission mode.
+ *
+ * The mode is the assertion, not merely existence. A world-readable secrets
+ * file is present and wrong, and "present" is what a weaker check would report.
+ * @param {string} path Filesystem path.
+ * @param {number} mode Expected permission bits.
+ * @param {string} label What this path is.
+ */
+function checkMode(path, mode, label) {
+  if (!existsSync(path)) {
+    check(false, label, "absent");
+    return;
+  }
+  const actual = statSync(path).mode & 0o777;
+  check(
+    actual === mode,
+    label,
+    actual === mode
+      ? `mode ${mode.toString(8)}`
+      : `mode ${actual.toString(8)}, expected ${mode.toString(8)}`
+  );
+}
+
+/**
+ * Run a sibling skill's script and capture its output.
+ * @param {string[]} args Node arguments.
+ * @returns {{ok: boolean, out: string}} Result.
+ */
+function node(args) {
+  try {
+    const out = execFileSync("node", args, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { ok: true, out: out.trim() };
+  } catch (err) {
+    return { ok: false, out: String(err.stderr ?? err.message).trim() };
+  }
+}
+
+/**
+ * Assert each declared tool is present at its pinned or minimum version.
+ * @param {object} tools Toolchain manifest.
+ */
+function verifyToolchain(tools) {
+  for (const tool of tools.require ?? []) {
+    try {
+      const out = execFileSync(tool.name, ["--version"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      check(true, `tool ${tool.name}`, extractVersion(out) ?? "present");
+    } catch {
+      check(false, `tool ${tool.name}`, "required but not present");
+    }
+  }
+  for (const tool of tools.install ?? []) {
+    try {
+      const out = execFileSync(tool.name, ["--version"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const found = extractVersion(out);
+      check(
+        found === tool.version,
+        `tool ${tool.name}`,
+        `${found} (pin ${tool.version})`
+      );
+    } catch {
+      check(
+        false,
+        `tool ${tool.name}`,
+        `pinned ${tool.version} but not installed`
+      );
+    }
+  }
+}
+
+/**
+ * Assert the working tree is clean.
+ *
+ * A remote environment that starts dirty will carry unrelated changes into
+ * whatever it produces, and the resulting diff is no longer attributable to the
+ * task that ran.
+ */
+function verifyCleanCheckout() {
+  try {
+    const out = execFileSync("git", ["status", "--porcelain"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    check(
+      out.trim() === "",
+      "clean checkout",
+      out.trim() ? "working tree is dirty" : ""
+    );
+  } catch {
+    check(false, "clean checkout", "not a git repository");
+  }
+}
+
+function main() {
+  const cfg = readRemoteEnvConfig();
+  const secretsDir = process.argv[2];
+
+  verifyToolchain(cfg.tools);
+
+  const surface = node([
+    new URL(
+      "../../lisa-secrets-access/scripts/resolve-secret.mjs",
+      import.meta.url
+    ).pathname,
+    "surface",
+  ]);
+  check(surface.ok, "surface detected", surface.out);
+
+  if (secretsDir) {
+    checkMode(secretsDir, 0o700, "secrets directory");
+    checkMode(`${secretsDir}/secrets.env`, 0o600, "values file");
+    checkMode(`${secretsDir}/secret-notes.json`, 0o600, "notes file");
+  }
+
+  verifyCleanCheckout();
+
+  let failed = 0;
+  for (const r of results) {
+    if (!r.ok) failed += 1;
+    console.log(
+      `  ${r.ok ? "ok  " : "FAIL"} ${r.label.padEnd(28)} ${r.detail}`
+    );
+  }
+  if (failed) throw new Error(`${failed} environment check(s) failed`);
+  console.log("\nRemote environment verified without revealing any value.");
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    main();
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+}

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.316.2",
+  "version": "2.317.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.316.2",
+  "version": "2.317.0",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-cdk-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.316.2",
+  "version": "2.317.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.316.2",
+  "version": "2.317.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.316.2",
+  "version": "2.317.0",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/lisa-copilot/commands/lisa/implement.md

@@ -1,6 +1,8 @@
 ---
-description: "Implement a single work item end-to-end. Vendor-agnostic: given a work-item URL/key (JIRA, Linear, GitHub Issues) or description, reads it, determines work type (Build/Fix/Improve/Investigate), assembles an agent team, runs the full lifecycle through PR + evidence. For batch processing of all Status=Ready tickets in a queue, use /lisa:intake instead."
-argument-hint: "<single-work-item-url | key | description>"
+description: "Implement a single work item end-to-end. Vendor-agnostic: given a work-item URL/key (JIRA, Linear, GitHub Issues) or description, reads it, determines work type (Build/Fix/Improve/Investigate), assembles an agent team, runs the full lifecycle through PR + evidence. Pass executionEnv=codex-cloud to run the work on a remote surface instead of locally — it submits and returns without polling, so the laptop is a launcher rather than the execution substrate. For batch processing of all Status=Ready tickets in a queue, use /lisa:intake instead."
+argument-hint: "[executionEnv=local|codex-cloud] <single-work-item-url | key | description>"
 ---
 
-Use the /lisa-implement skill to take the work item from spec to shipped: read the source, determine work type, assemble an agent team, and run the full lifecycle through PR creation, code review, deploy, and empirical verification. $ARGUMENTS
+Use the /lisa-implement skill to take the work item from spec to shipped: read the source, determine work type, assemble an agent team, and run the full lifecycle through PR creation, code review, deploy, and empirical verification.
+
+If `$ARGUMENTS` carries `executionEnv=` with anything other than `local`, route the work to that surface via /lisa-remote-dispatch and report the recorded task identifier instead of running the lifecycle locally. $ARGUMENTS

package/plugins/lisa-copilot/commands/lisa/setup/remote-env.md

@@ -0,0 +1,7 @@
+---
+description: "Provision and verify a remote execution environment for this project — Codex Cloud today. Generates the repository-owned setup script that installs the declared toolchain, materializes secrets through lisa-secrets-access, and runs the project's own hook. Provisions by API where one exists, by driving the vendor console where one does not, and by emitting exact config otherwise, then proves the result with the same read-back regardless of tier. Run this before dispatching work with executionEnv."
+allowed-tools: ["Skill"]
+argument-hint: "[codex-cloud] [--verify]"
+---
+
+Use the /lisa-setup-remote-env skill to provision and verify a remote execution environment. $ARGUMENTS

package/plugins/lisa-copilot/skills/lisa-atlassian-access/SKILL.md

@@ -81,6 +81,23 @@ read_atlassian_token() {
   local slug=$(echo "$email" | tr '[:upper:]@.' '[:lower:]__')
   local varname="ATLASSIAN_API_TOKEN_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get ATLASSIAN_API_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided /lisa:setup:atlassian
+  # flow, for projects that have not adopted a credentials provider. Reached only
+  # when the chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-atlassian -a "$email" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && secret-tool lookup service lisa-atlassian account "$email" 2>/dev/null ;;

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

@@ -43,6 +43,29 @@ Branch on the active runtime and prefer the runtime's native automation listing
 
 The report must stay repo-scoped: inspect only automations whose names belong to the current repo's Lisa fleet prefix, and do not absorb unrelated automations into the result.
 
+### GitHub Actions loops: check the clock itself
+
+Loops declared with `scheduler: "github-actions"` in `.lisa.config.json` are **not** visible to any runtime-native listing. Inspect them separately, and report a **stopped clock** as a finding in its own right — not merely the absence of recent work.
+
+Three distinct states, all of which look identical from the work side:
+
+| Observation | State | Remediation |
+| --- | --- | --- |
+| Workflow file exists, no `schedule:` trigger | **registered-disabled** | Expected until the production path is proven once. Prove it with a manual dispatch, then set `enabled: true` and regenerate. |
+| `schedule:` present, but no run in well over the declared cadence | **clock stopped** | GitHub **auto-disables scheduled workflows after 60 days of repository inactivity.** Re-enable it in the Actions UI, or push any commit. |
+| Runs firing, none dispatching | **idle** | Healthy. The queue is empty. |
+
+The middle row is the one worth building for. A quiet repository silently stops running its loops and *nothing announces it*, so an unattended factory can be dead for weeks while every individual signal still looks fine. Do not infer health from "no failures"; a clock that never fires produces no failures at all.
+
+```sh
+gh run list --workflow "lisa-<loop>.yml" --limit 5 \
+  --json createdAt,conclusion,event
+```
+
+Compare the newest `schedule`-event run against the declared cron. Absent or far older than the cadence means the clock is the problem, and no amount of inspecting the queue will reveal it.
+
+Also note that GitHub's scheduled triggers are **best-effort**: they are delayed under load, sometimes considerably. Judge against a generous multiple of the cadence rather than flagging a single late tick.
+
 ## What to report
 
 For each expected automation, report:

package/plugins/lisa-copilot/skills/lisa-doctor/SKILL.md

@@ -419,10 +419,43 @@ The verdict ladder is:
 - `READY_WITH_WARNINGS` — no `FAIL`, but one or more `WARN`.
 - `NOT_READY` — one or more `FAIL`.
 
+## Secrets configuration
+
+Run the secrets health checks through the skill that owns the contract, rather than reimplementing
+any part of it here:
+
+```sh
+node .claude/skills/lisa-secrets-access/scripts/validate-config.mjs   # shape
+node .claude/skills/lisa-secrets-access/scripts/doctor-secrets.mjs    # health
+```
+
+Run the validator first. It checks only the *shape* of the `secrets`, `remoteEnv`, and
+`automations` blocks — whether a declaration could ever be correct — and catches the failures that
+would otherwise surface somewhere unhelpful: a container failing mid-setup, a scheduled loop that
+never fires, a dispatch naming a surface nobody provisioned. The health check then asks whether the
+credentials actually resolve.
+
+It reports without ever printing a value, and compares two copies of the same credential by digest.
+Map its findings into the doctor's own verdicts: `error` → `FAIL`, `warn` → `WARN`.
+
+**A project with no credentials manager is `WARN`, never `FAIL`.** The `env` provider is a supported
+state — the environment *is* the provider. A manager is the preferred path because it gives one
+store, rotation, and an audit trail; it is not a requirement, and doctor must not act as though it
+were.
+
+The check worth understanding before triaging its output is the two-store one. A value present in
+both the provider and a local copy is **not a duplicate** — it is two live credentials, one of them
+untracked. Both authenticate, so the difference is invisible from either side, and "tidying up the
+duplicate" deletes a working credential that no record accounts for. Treat a mismatch as
+stop-and-ask, never as something to adjudicate automatically.
+
 ## Delegation and reuse
 
 - Reuse `config-resolution` for config and lifecycle role defaults instead of inventing a second
   schema.
+- Reuse `lisa-secrets-access` for every secrets check. Doctor must never read a keychain, parse a
+  `.env`, or invoke a provider CLI itself — one chokepoint is what makes the single-store rule
+  enforceable, and a diagnostic that bypasses it is exactly the second reader that creates drift.
 - Reuse the existing `github-project-v2` chokepoint for GitHub Project coordination checks instead
   of inlining bespoke access logic.
 - Reuse ideas from `lisa-wiki-doctor` for grouped verdict rendering where they fit, while keeping

package/plugins/lisa-copilot/skills/lisa-implement/SKILL.md

@@ -5,6 +5,23 @@ description: This skill should be used for any non-trivial request — features,
 
 # Implement: $ARGUMENTS
 
+## Routing: `executionEnv` (check this first)
+
+Before anything else — before team orchestration, before reading the input — check `$ARGUMENTS` for an `executionEnv=` parameter.
+
+| Value | What you do |
+| --- | --- |
+| absent, or `executionEnv=local` | Nothing changes. Continue to team orchestration below. |
+| `executionEnv=<surface>` | Invoke `lisa-remote-dispatch` with `$ARGUMENTS`, report what it returns, and **stop**. |
+
+This check comes first because dispatching is the whole job in that case: the remote runs this identical skill from this identical repository, so forming a team locally would duplicate the work you are about to send away.
+
+**Routing only.** `executionEnv` changes *where* the work happens and nothing about *what* happens. Do not vary the lifecycle, the gates, the review obligations, or the evidence requirements based on it. If a behaviour genuinely must differ, encode it here as an explicit branch — never as an unstated assumption in the dispatcher.
+
+`lisa-remote-dispatch` rejects an unknown surface rather than falling back to local. Do not catch that and continue: a silently ignored `executionEnv` runs work locally while the operator believes it went remote, and nothing downstream contradicts that belief.
+
+Dispatch is fire-and-record. It returns a task identifier and exits without polling; that identifier and the recorded ledger entry are the deliverable. Do not wait for the remote task, and do not report the work as complete — report it as dispatched.
+
 ## Orchestration: agent team
 
 Implement is a **team-first** flow. Bug, Build, Improve, and Investigate-Only all compose multiple specialists (Reproduce → debug → fix → review → verify). Single-agent mode is not permitted based on task complexity — the only exception is when no team creation or subagent delegation tool is available in the current runtime (see no-team fallback in the paragraph below).

package/plugins/lisa-copilot/skills/lisa-notion-access/SKILL.md

@@ -58,6 +58,23 @@ read_notion_token() {
   local slug=$(echo "$workspace" | tr '[:upper:]-' '[:lower:]_')
   local varname="NOTION_API_TOKEN_${slug}"
   [ -n "${!varname}" ] && { echo "${!varname}"; return; }
+  # Preferred path: the single secrets chokepoint. It owns the one-store rule
+  # and the surface ladder, so anything it can answer must not be read out of an
+  # OS keychain here — a second reader is how the same credential ends up living
+  # in two places and drifting.
+  local resolver
+  for resolver in .claude/skills/lisa-secrets-access/scripts/resolve-secret.mjs \
+                  .agents/skills/lisa-secrets-access/scripts/resolve-secret.mjs; do
+    if [ -f "$resolver" ]; then
+      local via_lisa
+      via_lisa=$(node "$resolver" get NOTION_API_TOKEN 2>/dev/null) \
+        && [ -n "$via_lisa" ] && { echo "$via_lisa"; return; }
+      break
+    fi
+  done
+  # Legacy fallback: the OS keychain written by the guided /lisa:setup:notion
+  # flow, for projects that have not adopted a credentials provider. Reached only
+  # when the chokepoint is absent or has no entry.
   case "$(uname -s)" in
     Darwin)  security find-generic-password -s lisa-notion -a "$workspace" -w 2>/dev/null ;;
     Linux)   command -v secret-tool >/dev/null && \