@codyswann/lisa 4.45.16 → 4.46.0

package/package.json

@@ -176,7 +176,7 @@
     "zod-validation-error": "^4.0.0"
   },
   "name": "@codyswann/lisa",
-  "version": "4.45.16",
+  "version": "4.46.0",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -324,7 +324,7 @@
     "test": "tests"
   },
   "types": "./dist/index.d.ts",
-  "lisaReleaseCommit": "aa04e94afdea3719bcfb16bdd9465921d85cfc40",
-  "gitHead": "aa04e94afdea3719bcfb16bdd9465921d85cfc40",
-  "lisaReleaseTag": "v4.45.16"
+  "lisaReleaseCommit": "37f59b7109a6d4847bc7b9af4a8ae025c9a09c36",
+  "gitHead": "37f59b7109a6d4847bc7b9af4a8ae025c9a09c36",
+  "lisaReleaseTag": "v4.46.0"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "4.45.16",
+  "version": "4.46.0",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"
@@ -267,6 +267,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforcement-vintage.sh"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [
@@ -331,6 +340,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/enforcement-vintage.sh"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [

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

@@ -189,6 +189,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/enforcement-vintage.sh"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [
@@ -244,6 +253,15 @@
           }
         ]
       },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${PLUGIN_ROOT}/hooks/enforcement-vintage.sh"
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [

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

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

package/plugins/lisa/.codex-plugin/skills/lisa-drive-pr-to-merge/SKILL.md

@@ -229,6 +229,30 @@ fi
 gh pr view <pr> --json autoMergeRequest -q .autoMergeRequest   # must print null
 ```
 
+**Then declare the hold**, so the deliberate case stays distinguishable from the
+defect. `/lisa:queue-status`'s arming sweep (#3903) reports every open PR whose
+`autoMergeRequest` is `null`, because a green unarmed PR waits forever and no
+other surface says so. An undeclared deliberate hold appears there as a finding
+on every run, and a report that is wrong every run is one operators learn to
+ignore:
+
+```bash
+gh pr edit <pr> --add-label "lisa:auto-merge-off"
+```
+
+Where that label does not exist in the repo, put the marker in the PR body
+instead — the sweep reads either spelling — and **give it a reason**, because
+the sweep prints one and prints `no reason declared` when it cannot:
+
+```text
+<!-- [lisa-auto-merge-off] reason=<why a human owns this merge> -->
+```
+
+Declaring the hold **suppresses it from the findings, not from the report**: the
+sweep still counts and names every held PR. That is deliberate — a label that
+turned a red sweep green and left no trace would be a bypass wearing the costume
+of a fix.
+
 If the disarm fails or the re-read still shows an armed `autoMergeRequest`,
 **fail closed**: treat the PR as a hard block (section 4) and report that the
 `awaiting-human` state was NOT reached — never proceed to a state in which the

package/plugins/lisa/.codex-plugin/skills/lisa-queue-status/SKILL.md

@@ -69,6 +69,30 @@ For each inspected queue, report:
 
 The report should stay terminal-first and immediately actionable: observable queue facts first, then the smallest useful next step.
 
+## Pull request arming (#3903)
+
+Alongside the two work queues, report the **arming state of the repo's open pull requests**. A PR whose `autoMergeRequest` is `null` is fully green and permanently unmergeable: every check passes, `mergeStateStatus` is green, nothing complains, and it waits forever. Green-and-unarmed and green-and-waiting read identically on every other surface, so this is the one place that asks the question.
+
+Run the sweep rather than eyeballing the list — an LLM reading PR pages one at a time is exactly the shell-loop-by-prose failure #3512 records:
+
+```bash
+gh pr list --state open --limit 200 \
+  --json number,title,url,isDraft,labels,body,autoMergeRequest \
+  | node "${CLAUDE_PLUGIN_ROOT}/scripts/pr-arming-sweep.mjs"
+```
+
+Report the verdict verbatim, and never translate it into an absence:
+
+- `MEASURED_CLEAN` — a **positive assertion**: N open PRs were read and every one is armed or deliberately unarmed. Say the count. "Nothing to report" is not the same sentence and must not be substituted for it.
+- `UNARMED_PRS_FOUND` — list each PR. The next step is `gh pr merge <n> --auto --merge` **followed by reading the state back** (`gh pr view <n> --json autoMergeRequest`); arming can be silently dropped after the fact, so an arm that was not read back is not a fact.
+- `NOT_MEASURED` — the arming state was **not read** for at least one PR (usually a `--json` selection missing `autoMergeRequest`). This is an unanswered question, not a clean queue. Fix the query and re-run; do **not** report the queue as healthy.
+
+Arming state feeds no queue verdict and gates nothing — this stays a report, per #3903's Out of Scope. Never arm a PR from this skill; `/lisa:queue-status` is read-only.
+
+A PR deliberately left for a human (`lisa-drive-pr-to-merge`'s `auto_merge=false` mode) declares itself with the `lisa:auto-merge-off` label or a `[lisa-auto-merge-off] reason=<text>` body marker. Drafts are excluded — GitHub will not arm a draft.
+
+**Held PRs are suppressed from the findings, never from the report.** Always show the `Held (declared, not merging): N` block and the numbers under it, including when the verdict is `MEASURED_CLEAN`. This is a one-label remedy for a red sweep and it will look like housekeeping to whoever applies it — "4 armed, 0 unarmed" and "4 armed, 0 unarmed, 9 held" describe very different queues, and only the second lets an operator notice the label spreading. Flag it when holds outnumber armed PRs, or when several read `no reason declared`.
+
 ## Highlight semantics
 
 Each queue section may include one or more highlighted items. A highlight is not a raw dump of every issue in that role; it is the single oldest or otherwise most actionable item Lisa can justify surfacing without mutating work.

package/plugins/lisa/hooks/enforcement-vintage.mjs

@@ -0,0 +1,453 @@
+/**
+ * SessionStart / SubagentStart: tell the agent WHICH COPY of Lisa is executing
+ * in this session, and whether a newer one is sitting on the same disk.
+ *
+ * The defect this closes (CodySwannGT/lisa#3714). A session resolves its Lisa
+ * copy ONCE, at session start, and executes that copy for its whole life. On
+ * Claude that is `~/.claude/plugins/cache/lisa/lisa/<version>/`; in the Lisa
+ * monorepo the repository hook dispatcher additionally resolves guards out of
+ * the CHECKOUT. Neither is refreshed by anything that happens afterwards:
+ * merging to `main`, publishing to npm, updating the marketplace, or running
+ * `lisa apply` all leave a running session on the copy it started with.
+ *
+ * So `origin/main` contains a fix is a fact about the repository, and never a
+ * fact about this session. Measured on this fleet: a lane eleven hours old was
+ * executing 4.32.2 while `main` and the marketplace clone were at 4.35.1, with
+ * 4.35.1 already sitting in the cache beside 310 other versions. It is not a
+ * distribution failure — the newer copy had arrived and could not be reached.
+ *
+ * The consequence was measured twice, in OPPOSITE directions, by careful agents
+ * holding real measurements:
+ *
+ *   - A lane read an already-fixed defect out of its stale copy, believed it
+ *     live, and filed a ticket for it.
+ *   - Another lane nearly shipped against a superseded contract, because the
+ *     contract it read was the stale copy's.
+ *
+ * One cause, two opposite errors, and NEITHER was visible from inside the
+ * session. That invisibility is the whole defect: the version was knowable at
+ * every moment and nothing ever said it.
+ *
+ * Why this is context and not a refusal. The obvious remedy — refuse, or
+ * restart the fleet — is not free here: sessions hold uncommitted sole-copy
+ * work, so a forced restart can cost more than the staleness it cures. A
+ * session that can SEE it is stale can say so, discount its own evidence, and
+ * verify against `origin/main` before reporting — and that costs nothing. The
+ * enforcement fallback already computes a version comparison and prints it to
+ * stderr; on the exit-0 path Claude Code shows a hook's stderr to the user in
+ * transcript mode only and NEVER to the agent, so the agent — the party that
+ * acts on it — was the one party never told. Injected context is the channel
+ * that reaches it.
+ *
+ * Why it always speaks, including when current. Silence would be ambiguous
+ * between "this copy is current" and "the hook did not run", and an ambiguous
+ * signal is the failure mode this file exists to remove. A current session gets
+ * one short line; a stale one gets the delta and what to do about it.
+ *
+ * FAIL SOFT, ALWAYS. Every exit is 0. A session that cannot date itself must
+ * still start.
+ * @module plugins/src/base/hooks/enforcement-vintage
+ */
+import { readFileSync, existsSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { realpathSync } from "fs";
+
+/** Marker the block is wrapped in, so an agent can cite it by name. */
+const BLOCK_TAG = "lisa-enforcement-vintage";
+
+/**
+ * The version a JSON manifest states at its TOP LEVEL.
+ *
+ * Parsed rather than pattern-matched, which is the one place this renderer
+ * should not copy the Bash dispatcher beside it. That dispatcher runs on every
+ * tool call under bash 3.2 with no JSON parser available, so it approximates
+ * "top-level" by anchoring a line-oriented regex to at most three leading
+ * spaces — an approximation that fails outright on a minified manifest, where
+ * every key is on one line. Node has a real parser and this runs once per
+ * session, so it reads the key it means: `node_modules/@codyswann/lisa/package.json`
+ * carries nested `"version"` keys inside its dependency block, and only a parse
+ * distinguishes those from Lisa's own in every formatting.
+ *
+ * The anchored regex is kept as a FALLBACK, for the one input a parse cannot
+ * serve: a manifest that is malformed. A file that is broken but pretty-printed
+ * still dates its copy, and a copy that cannot be dated is reported as unknown
+ * rather than assumed current.
+ * @param {string} file Absolute path to a JSON file.
+ * @param {string} key Top-level key holding the version.
+ * @returns {string} The version, or "" when the file or key is absent.
+ */
+export function readJsonVersion(file, key) {
+  let raw = "";
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const value = parsed?.[key];
+    if (typeof value === "string" && value) return value;
+    return "";
+  } catch {
+    const pattern = new RegExp(`^ {0,3}"${key}"\\s*:\\s*"([^"]+)"`, "m");
+    const match = pattern.exec(raw);
+    return match ? match[1] : "";
+  }
+}
+
+/**
+ * Numeric release fields of a version string, ignoring prerelease and build
+ * suffixes.
+ *
+ * A field that is not a plain number becomes 0 rather than throwing, so a
+ * version string this does not understand can never be reported as NEWER than
+ * one it does. That direction is deliberate: the failure mode is silence, not
+ * a fleet-wide false staleness alarm.
+ * @param {string} version A dotted version string.
+ * @returns {readonly number[]} Three release fields.
+ */
+export function releaseFields(version) {
+  const core = String(version).split("-")[0].split("+")[0];
+  const parts = core.split(".").slice(0, 3);
+  return [0, 1, 2].map(index => {
+    const field = parts[index];
+    return /^\d+$/u.test(field ?? "") ? Number(field) : 0;
+  });
+}
+
+/**
+ * Whether the first version names an older Lisa than the second.
+ * @param {string} a Candidate older version.
+ * @param {string} b Candidate newer version.
+ * @returns {boolean} True when `a` precedes `b`.
+ */
+export function isOlder(a, b) {
+  const left = releaseFields(a);
+  const right = releaseFields(b);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] < right[index];
+  }
+  return false;
+}
+
+/**
+ * The newest of a set of dated copies.
+ *
+ * A maximum over local evidence, never one nominated reference — the same
+ * choice the Bash dispatcher makes, and load-bearing in both directions. In the
+ * Lisa monorepo `node_modules/@codyswann/lisa` is a fixture pinned majors
+ * behind the repository, so treating it as "the installed release" would report
+ * every current checkout as ahead and never report a stale one. In a host
+ * project it is the most meaningful reference available. A maximum needs no
+ * ranking between them and cannot invent staleness: a copy is behind only when
+ * something demonstrably newer sits on the same disk.
+ * @param {readonly {version: string, source: string}[]} copies Dated copies.
+ * @returns {{version: string, source: string} | null} The newest, or null.
+ */
+export function newestOf(copies) {
+  return copies
+    .filter(copy => copy.version)
+    .reduce(
+      (best, copy) =>
+        best === null || isOlder(best.version, copy.version) ? copy : best,
+      /** @type {{version: string, source: string} | null} */ (null)
+    );
+}
+
+/**
+ * Date the copy this hook is itself executing from.
+ *
+ * Located from the script's OWN path rather than from an environment variable,
+ * and that is the point. `CLAUDE_PLUGIN_ROOT` is a claim the harness makes;
+ * the directory the file was loaded out of is not a claim at all. A copy that
+ * dates itself cannot be misattributed by a variable that is unset, stale, or
+ * pointing somewhere else.
+ * @param {string} hooksDir Directory holding this script.
+ * @returns {{version: string, source: string, root: string}} The running copy.
+ */
+export function runningCopy(hooksDir) {
+  const root = path.dirname(hooksDir);
+  const manifest = path.join(root, ".claude-plugin", "plugin.json");
+  return {
+    version: readJsonVersion(manifest, "version"),
+    source: manifest,
+    root,
+  };
+}
+
+/**
+ * The guard tree the repository hook dispatcher would resolve, and its vintage.
+ *
+ * Resolution is first-wins: `scripts/lisa-hooks/` shadows `plugins/lisa/hooks/`
+ * outright and the shadowed copy never runs. So the tree reported here is
+ * whichever is FIRST, never whichever is newest — the distinction the whole
+ * ticket turns on. The host tree is dated by the apply receipt, because the
+ * same `lisa apply` run produced both and they cannot disagree; the monorepo's
+ * own tree is dated by the plugin manifest beside it.
+ * @param {string} projectDir Repository root.
+ * @returns {{tree: string, version: string, repair: string} | null} The tree.
+ */
+export function repositoryTree(projectDir) {
+  const hostTree = path.join(projectDir, "scripts", "lisa-hooks");
+  const pluginTree = path.join(projectDir, "plugins", "lisa", "hooks");
+  if (existsSync(path.join(hostTree, "block-no-verify.sh"))) {
+    return {
+      tree: hostTree,
+      version: readJsonVersion(
+        path.join(projectDir, ".lisa", "apply-receipt.json"),
+        "lisa_version"
+      ),
+      repair: "`npx @codyswann/lisa apply` rewrites this tree",
+    };
+  }
+  if (existsSync(path.join(pluginTree, "block-no-verify.sh"))) {
+    return {
+      tree: pluginTree,
+      version: readJsonVersion(
+        path.join(
+          projectDir,
+          "plugins",
+          "lisa",
+          ".claude-plugin",
+          "plugin.json"
+        ),
+        "version"
+      ),
+      repair:
+        "this tree IS the checkout's own source, so only moving the branch refreshes it",
+    };
+  }
+  return null;
+}
+
+/**
+ * Every dated Lisa this machine can be SHOWN to hold.
+ * @param {string} projectDir Repository root.
+ * @param {string} configDir Harness config directory.
+ * @returns {readonly {version: string, source: string}[]} Dated copies.
+ */
+export function localCopies(projectDir, configDir) {
+  const marketplace = path.join(
+    configDir,
+    "plugins",
+    "marketplaces",
+    "lisa",
+    "plugins",
+    "lisa",
+    ".claude-plugin",
+    "plugin.json"
+  );
+  const installed = path.join(
+    projectDir,
+    "node_modules",
+    "@codyswann",
+    "lisa",
+    "package.json"
+  );
+  const checkout = path.join(
+    projectDir,
+    "plugins",
+    "lisa",
+    ".claude-plugin",
+    "plugin.json"
+  );
+  return [
+    { version: readJsonVersion(marketplace, "version"), source: marketplace },
+    { version: readJsonVersion(installed, "version"), source: installed },
+    { version: readJsonVersion(checkout, "version"), source: checkout },
+  ];
+}
+
+/**
+ * Everything the block needs, resolved from disk.
+ * @param {{hooksDir: string, projectDir: string, configDir: string}} where Paths.
+ * @returns {object} Resolved vintage state.
+ */
+export function resolveState(where) {
+  const running = runningCopy(where.hooksDir);
+  const tree = repositoryTree(where.projectDir);
+
+  // Two maxima, and the split is what lets AHEAD exist as its own answer.
+  //
+  // `reference` deliberately EXCLUDES the running copy, because a session
+  // cannot be evidence about itself: folding it in makes an ahead session
+  // select itself as the newest thing on the disk, which collapses "ahead of
+  // every other copy here" into "current" and loses the distinction entirely.
+  //
+  // `newest` includes it, because the reported ROW answers a different
+  // question — what is the newest Lisa on this disk — and on a machine where
+  // the session copy is the only dateable one, excluding it would leave that
+  // row empty and make a current session indistinguishable from an undateable
+  // one. Same numbers, two questions, and only the first may be self-referential.
+  const reference = newestOf([
+    ...localCopies(where.projectDir, where.configDir),
+    ...(tree ? [{ version: tree.version, source: tree.tree }] : []),
+  ]);
+  const newest = newestOf([
+    ...(reference ? [reference] : []),
+    { version: running.version, source: running.source },
+  ]);
+  const behind = Boolean(
+    reference && running.version && isOlder(running.version, reference.version)
+  );
+  const ahead = Boolean(
+    reference && running.version && isOlder(reference.version, running.version)
+  );
+  // Measured against the disk maximum rather than against the session copy: a
+  // session running an OLDER build than the tree it polices would otherwise
+  // report a nine-minor-old tree as fine.
+  const treeBehind = Boolean(
+    tree && newest && tree.version && isOlder(tree.version, newest.version)
+  );
+  return { running, tree, reference, newest, behind, ahead, treeBehind };
+}
+
+/** What a stale session must do differently, stated as actions. */
+const CONSEQUENCES = [
+  "A guard refusal or contract you read HERE may already be fixed or superseded on `origin/main`. Filing it as live is the error this measured twice tonight, in both directions.",
+  "Verify any claim about this repository's source with `git show origin/main:<path>` — never from a working tree — and say which vintage you read when you report it. A REFUTATION needs that provenance more than a claim does: a stale `grep` returns a clean, specific, checkable-looking negative.",
+  "Merge ancestry proves a fix EXISTS. It never proves the exposure is closed for a session already running. Report those two facts separately.",
+  "Only starting a new session re-resolves the copy. Publishing, `lisa apply`, and updating the marketplace do not reach this one.",
+];
+
+/**
+ * Render the injected block.
+ * @param {object} state Resolved vintage state.
+ * @returns {string} Block text.
+ */
+export function renderBlock(state) {
+  const lines = [`<${BLOCK_TAG}>`];
+  lines.push(
+    "The Lisa copy executing in this session was resolved when the session started " +
+      "and never changes afterwards. What `origin/main` contains is not what runs here."
+  );
+  lines.push("");
+  lines.push(
+    `session copy: ${state.running.version ? `lisa ${state.running.version}` : "vintage unknown (no manifest beside it, so it cannot be shown current)"} at ${state.running.root}`
+  );
+  if (state.tree) {
+    lines.push(
+      `repository guards: ${state.tree.version ? `lisa ${state.tree.version}` : "vintage unknown"} at ${state.tree.tree}${state.treeBehind ? ` — BEHIND; ${state.tree.repair}` : ""}`
+    );
+  }
+  if (state.newest) {
+    lines.push(
+      `newest on this disk: lisa ${state.newest.version} at ${state.newest.source}`
+    );
+  }
+  lines.push("");
+  if (state.behind || !state.running.version || state.treeBehind) {
+    lines.push(
+      state.behind
+        ? `STALE — this session executes lisa ${state.running.version} while lisa ${state.reference.version} is already on this machine. Act on that:`
+        : "UNPROVEN — this session cannot be shown to be current. Treat it as stale:"
+    );
+    CONSEQUENCES.forEach(line => lines.push(`- ${line}`));
+  } else if (state.ahead) {
+    // Not an alarm, and not the same as current. A session ahead of every
+    // released copy is running code no other session on this machine has, so
+    // guard behaviour observed here is evidence about an UNRELEASED build —
+    // which is the mirror of the stale reading and produces the same class of
+    // wrong report, in the other direction.
+    lines.push(
+      `AHEAD — this session executes lisa ${state.running.version}, newer than lisa ` +
+        `${state.reference.version} at ${state.reference.source}. Nothing here is stale, but ` +
+        "behaviour you observe may not exist yet for anyone else: do not report it as how " +
+        "Lisa behaves, and say which version you were on."
+    );
+  } else {
+    lines.push(
+      "CURRENT — no newer Lisa is on this disk, so guard behaviour and skill contracts " +
+        "observed here match the newest copy this machine holds. State the version anyway " +
+        "when you report on guard or contract behaviour; it is only current until the next release."
+    );
+  }
+  lines.push(`</${BLOCK_TAG}>`);
+  return lines.join("\n");
+}
+
+/**
+ * Read the hook event name from the harness's stdin payload.
+ * @param {string} raw Raw stdin.
+ * @returns {string} The event name, defaulting to `SessionStart`.
+ */
+export function eventName(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.hook_event_name === "string"
+      ? parsed.hook_event_name
+      : "SessionStart";
+  } catch {
+    return "SessionStart";
+  }
+}
+
+/**
+ * Emit the hook envelope. Always exits 0 — see the module comment.
+ * @param {string[]} argv Process arguments.
+ * @param {string} stdin Raw stdin.
+ * @param {NodeJS.ProcessEnv} [env] Environment.
+ * @returns {string} The JSON envelope.
+ */
+export function run(argv, stdin, env = process.env) {
+  const flagValue = name => {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : "";
+  };
+  const hooksDir =
+    flagValue("--hooks-dir") || path.dirname(fileURLToPath(import.meta.url));
+  const projectDir = flagValue("--project-dir") || process.cwd();
+  const configDir =
+    flagValue("--config-dir") ||
+    env.CLAUDE_CONFIG_DIR ||
+    path.join(env.HOME || "", ".claude");
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: eventName(stdin),
+      additionalContext: renderBlock(
+        resolveState({ hooksDir, projectDir, configDir })
+      ),
+    },
+  });
+}
+
+/**
+ * Whether this module is the process entry point.
+ *
+ * Both sides are realpath'd: comparing `fileURLToPath(import.meta.url)` against
+ * `path.resolve(process.argv[1])` disagrees whenever the checkout is reached
+ * through a symlink — a git worktree, or any `/tmp` path on macOS, `/tmp` being
+ * a symlink to `/private/tmp` — because `import.meta.url` is the REAL path
+ * while `argv[1]` is whatever the caller typed.
+ *
+ * The one implementation lives at `scripts/lib/invoked-as-script.mjs`. This
+ * file cannot import it: it is materialized into every plugin payload, where
+ * there is no `./lib/` to import from — the same accommodation
+ * `inject-resolved-config.mjs` makes.
+ * @param {string} moduleUrl The caller's own `import.meta.url`.
+ * @param {string | undefined} [argv1] Entry path; defaults to `process.argv[1]`.
+ * @returns {boolean} Whether the caller should run its CLI body.
+ */
+export function invokedAsScript(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (invokedAsScript(import.meta.url)) {
+  let stdin = "";
+  try {
+    stdin = readFileSync(0, "utf8");
+  } catch {
+    stdin = "";
+  }
+  try {
+    process.stdout.write(`${run(process.argv.slice(2), stdin)}\n`);
+  } catch {
+    // Fail soft: a hook that cannot render must never wedge session start.
+  }
+}

package/plugins/lisa/hooks/enforcement-vintage.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# SessionStart / SubagentStart: put the VINTAGE of the executing Lisa copy in
+# front of the agent (CodySwannGT/lisa#3714).
+#
+# A session resolves its Lisa copy once, at session start, and runs that copy
+# until it ends. Nothing that happens afterwards — a merge to `main`, a publish,
+# a marketplace update, a `lisa apply` — reaches it. So "the fix is on `main`"
+# is a fact about the repository and never a fact about this session, and until
+# now nothing in the session said which of the two it was looking at.
+#
+# All the work lives in the sibling `.mjs`, which is unit-tested. This wrapper
+# only resolves the project root and hands stdin through — the same division
+# `inject-resolved-config.sh` beside it makes.
+#
+# `--hooks-dir` is deliberately NOT passed. The renderer dates the copy from its
+# own `import.meta.url`, which is where the file was actually loaded from; a
+# path this wrapper computed from an environment variable would be a claim about
+# which copy is running rather than an observation of it, and this whole file
+# exists because such a claim was wrong for eleven hours without anyone noticing.
+#
+# FAIL SOFT, ALWAYS. Every exit is 0 and every failure is silent. The right
+# response to "node is missing" is a session that starts without this block,
+# never a session that does not start. The hard reading of the same question
+# lives where it can afford to be hard: `lisa doctor` reports what a checkout
+# resolves and exits non-zero on it.
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+RENDERER="$ROOT/hooks/enforcement-vintage.mjs"
+
+[ -f "$RENDERER" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+
+# CLAUDE_PROJECT_DIR is the harness's own declaration of the root and is the
+# only source that stays correct when the session's cwd has moved. Falling back
+# to the git toplevel before $PWD matters for the same reason it does in
+# `inject-resolved-config.sh`: the artifacts this dates live at the repository
+# root, and a hook that reads the cwd reports the wrong tree from any
+# subdirectory.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "${PROJECT_DIR}" ] || [ ! -d "${PROJECT_DIR}" ]; then
+  PROJECT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+fi
+
+printf '%s' "$INPUT" | node "$RENDERER" --project-dir "$PROJECT_DIR" || true
+exit 0