@codyswann/lisa 4.43.1 → 4.44.0

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.43.1",
+  "version": "4.44.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/hooks/worktree-binding-guard.mjs

@@ -47,7 +47,13 @@
  */
 
 import { execFileSync } from "node:child_process";
-import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import {
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 
@@ -148,6 +154,258 @@ function mainCheckout(cwd) {
   return null;
 }
 
+/**
+ * How much of an executed script this guard will read, in bytes.
+ *
+ * A generated fixture can be megabytes, and a guard that reads all of it on
+ * every Bash call is a guard someone switches off.
+ */
+const SCRIPT_READ_LIMIT = 256 * 1024;
+
+/**
+ * Programs that take their operands as DATA and never execute them.
+ *
+ * The same split `block-direct-issue-create.sh` makes, and for the same reason
+ * it had to: a guard that opens every file a command names, then judges the
+ * COMMAND by that FILE's contents, refuses ordinary inspection. Reading a
+ * script that visits another worktree is not visiting it.
+ *
+ * The list is an exemption, not an allowlist. Anything unrecognised is
+ * FOLLOWED, because an interpreter roster fails open on the runner nobody
+ * enumerated.
+ */
+const READ_ONLY_PROGRAMS = new Set([
+  "awk",
+  "basename",
+  "cat",
+  "cksum",
+  "cmp",
+  "comm",
+  "cut",
+  "diff",
+  "dirname",
+  "du",
+  "file",
+  "find",
+  "grep",
+  "egrep",
+  "fgrep",
+  "head",
+  "less",
+  "ls",
+  "md5",
+  "md5sum",
+  "more",
+  "nl",
+  "od",
+  "realpath",
+  "rg",
+  "sed",
+  "sha1sum",
+  "sha256sum",
+  "sort",
+  "stat",
+  "strings",
+  "tail",
+  "tee",
+  "tr",
+  "uniq",
+  "wc",
+  "xxd",
+]);
+
+/** Interpreters whose first non-option operand is the file they run. */
+const EXECUTING_INTERPRETERS = new Set([
+  "bash",
+  "dash",
+  "ksh",
+  "node",
+  "perl",
+  "python",
+  "python3",
+  "ruby",
+  "sh",
+  "zsh",
+  "bun",
+  "deno",
+  "tsx",
+]);
+
+/** Shell builtins that run a file in the CURRENT shell. */
+const SOURCE_BUILTINS = new Set([".", "source"]);
+
+/** Where one command ends and the next begins. */
+const COMMAND_SEPARATORS = /\|\||&&|[;|&\n]/u;
+
+/**
+ * Split a command into tokens, honouring simple quoting.
+ *
+ * Deliberately simple, and the guard fails OPEN when it is not enough — see
+ * {@link scriptReachingForeignTree}. A tokeniser that guessed would be worse
+ * than one that says it does not know.
+ */
+function tokenise(segment) {
+  const tokens = segment.match(/"[^"]*"|'[^']*'|[^\s]+/gu) ?? [];
+  return tokens.map(token => token.replace(/^["']|["']$/gu, ""));
+}
+
+/**
+ * The path this command EXECUTES, or null.
+ *
+ * The command-position question. A path anywhere else is an argument, and an
+ * argument is data.
+ */
+function executedPath(segment) {
+  const tokens = tokenise(segment);
+  if (tokens.length === 0) return null;
+  const [head, ...rest] = tokens;
+  const program = head.split("/").pop() ?? "";
+  if (READ_ONLY_PROGRAMS.has(program)) return null;
+  if (SOURCE_BUILTINS.has(program)) return rest[0] ?? null;
+  if (!EXECUTING_INTERPRETERS.has(program)) {
+    // A command word that is itself a file runs by its shebang.
+    return head.includes("/") ? head : null;
+  }
+  // A known interpreter: the first operand that is not an option.
+  const operand = rest.find(token => !token.startsWith("-"));
+  return operand ?? null;
+}
+
+/**
+ * A worktree root other than `bound` that this text reaches into, or null.
+ *
+ * ## Why this does not enumerate `cd`
+ *
+ * The redirect spellings — `cd`, `git -C`, `--work-tree`, `--git-dir`, a
+ * subshell, `env -C`, a variable holding the path — are an open set, and
+ * enumerating them is the failure this arm exists to end
+ * (CodySwannGT/lisa#3927 states it for the sibling guard). So the question is
+ * inverted the same way the filing guard inverted its own: not *which syntax
+ * moves*, which is unbounded, but *which tokens name a directory in another
+ * worktree*, which is bounded by the file.
+ *
+ * A path only has to RESOLVE. How it arrived does not matter, which is what
+ * makes an unenumerated spelling reach the same verdict as `cd`.
+ *
+ * ## Why comments are stripped first
+ *
+ * A script that merely MENTIONS a sibling worktree — a usage line, a comment,
+ * a log message — would otherwise be refused for describing the thing rather
+ * than doing it. Prose about a subject is the likeliest text to contain the
+ * subject's shapes, and the population that writes it is the people
+ * documenting the guard. A parity classifier elsewhere in this repository was
+ * fooled by exactly that and was caught only by a known-answer control.
+ */
+function foreignTreeIn(text, bound, cwd) {
+  const code = text
+    .split("\n")
+    .map(line => line.replace(/^\s*#.*$/u, ""))
+    .join("\n");
+  for (const raw of code.match(/[^\s'";|&()<>]+/gu) ?? []) {
+    const token = raw.replace(/^["']|["']$/gu, "");
+    if (!token.includes("/")) continue;
+    const candidate = isAbsolute(token) ? token : join(cwd, token);
+    let root;
+    try {
+      if (!statSync(candidate).isDirectory()) continue;
+      root = worktreeRoot(realpathSync(candidate));
+    } catch {
+      continue;
+    }
+    if (root && root !== bound) return root;
+  }
+  return null;
+}
+
+/**
+ * The foreign worktree an executed script reaches, or null.
+ *
+ * ## Why this arm exists at all
+ *
+ * The check above compares `payload.cwd` against the bound root, and that is
+ * the right comparison — but **`payload.cwd` is sampled before the child
+ * process runs**. A script that changes directory internally moves AFTER the
+ * guard has measured. The guard is not wrong about the target; it is right
+ * about a target that stops being the target one instruction later.
+ *
+ * A measurement taken before execution cannot bind what execution does
+ * (CodySwannGT/lisa#3924). So the only thing left is to read what is about to
+ * run.
+ *
+ * ## What this arm does NOT cover, stated rather than implied
+ *
+ * An INLINE redirect — `cd B && git status`, `git -C B status` — is not
+ * refused here. Those are already refused by the runtime's own worktree
+ * isolation, and duplicating a control is how two controls drift into
+ * disagreeing. The scripted form is the one neither covers, and it is the only
+ * cell this arm fills.
+ *
+ * ## A relative script path is resolved against `payload.cwd`, and that is a
+ * KNOWN limitation shared with `parity-safety-net.sh`
+ *
+ * CodySwannGT/lisa#3933, filed against that guard, is the same defect: a
+ * relative token is resolved against the hook process's working directory, not
+ * against the directory the command will have once it runs its own leading
+ * `cd`. So `cd <other tree> && bash scripts/foo.sh` reads THIS tree's copy of
+ * `scripts/foo.sh` and reports on it with full confidence.
+ *
+ * It matters here for the same reason it matters there: on a machine running
+ * many worktrees of one repository, every tree holds its own copy of every
+ * script at the same relative path, and they differ by whatever each lane is
+ * doing. A confident scan of the wrong copy is wrong in both directions, and
+ * the silent one — the copy that will run reaches out, the copy that was read
+ * does not — is the direction this arm exists to prevent.
+ *
+ * NOT fixed here on purpose. #3933 is assigned and its options (honour a
+ * leading `cd`, or fail closed when the effective cwd is uncertain) belong in
+ * one place rather than two: a second implementation of the same resolution is
+ * how two guards drift into disagreeing about which file a command runs.
+ * When that lands, this call site should adopt whatever it produces.
+ *
+ * The exposure here is narrower than there. This arm is reached only after the
+ * session has been confirmed to be in its bound worktree, so the common case
+ * is a relative path resolving inside the tree the session is actually in.
+ *
+ * Fails OPEN and says so, like every other undecidable case in this file.
+ */
+function scriptReachingForeignTree(payload, bound) {
+  const command = payload.tool_input?.command;
+  if (typeof command !== "string" || !command) return null;
+  for (const segment of command.split(COMMAND_SEPARATORS)) {
+    const named = executedPath(segment);
+    if (!named) continue;
+    const path = isAbsolute(named) ? named : join(payload.cwd, named);
+    let text;
+    try {
+      if (statSync(path).size > SCRIPT_READ_LIMIT) {
+        say(`${path} is too large to inspect; NOT enforcing on it`);
+        continue;
+      }
+      text = readFileSync(path, "utf8");
+    } catch {
+      // Not a readable file: nothing was executed that this can read.
+      continue;
+    }
+    const foreign = foreignTreeIn(text, bound, payload.cwd);
+    if (foreign) return { script: path, foreign };
+  }
+  return null;
+}
+
+function reachesOut(script, foreign, bound) {
+  return refuse([
+    "worktree-binding-guard: this command runs a script that reaches into",
+    "another worktree.",
+    `  script:    ${script}`,
+    `  reaches:   ${foreign}`,
+    `  bound to:  ${bound}`,
+    "The directory change lives inside the file, so it happens after this",
+    "guard has measured where the session is. Run the work from the tree it",
+    "belongs to, or acknowledge the move:",
+    acceptanceLine(foreign),
+  ]);
+}
+
 function stateFile(sessionId) {
   const home = process.env.LISA_STATE_HOME || join(homedir(), ".lisa");
   return join(home, "worktree-binding", `${sessionId}.json`);
@@ -328,6 +586,10 @@ function evaluate(payload) {
     return 0;
   }
   if (state.boundRoot !== observed) return displaced(state.boundRoot, observed);
+  // Last, and only once the session is provably where it should be: a script
+  // that moves somewhere else after this check has already run.
+  const reach = scriptReachingForeignTree(payload, observed);
+  if (reach) return reachesOut(reach.script, reach.foreign, observed);
   return 0;
 }
 

package/scripts/check-generated-artifact-merge-coverage.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/**
+ * Prove every generated artifact is either merge-driver covered or declared
+ * unsupported for a reason that is still true (issue CodySwannGT/lisa#3932).
+ *
+ * ## The gap this closes
+ *
+ * Lisa ships a merge driver for its checked-in generated artifacts, and
+ * `.gitattributes` maps two of them to it. It maps **two of four**. Nothing
+ * said so: an artifact joins the unregistered set by being written, and the
+ * only way to notice was to enumerate `.gitattributes` by hand and compare it
+ * against a list of artifacts that exists nowhere.
+ *
+ * ## Why the obvious repair is wrong, measured
+ *
+ * "Register the other two" looks free and is not. Run the driver's own parser
+ * over all four:
+ *
+ * ```
+ * src/core/upstream-evidence-manifest.ts               parse=OK  roundtrip=EXACT
+ * src/core/lisa-owned-hash-ledger.ts                   parse=OK  roundtrip=EXACT
+ * scripts/two-channel-couplings.json                   PARSE-FAIL: mixed indentation
+ * src/core/nightly-e2e-guard-behavior-certificate.ts   PARSE-FAIL: mixed indentation
+ * ```
+ *
+ * The parser handles a **flat** one-level `"key": scalar` map, which is what
+ * the manifest and the ledger are. The other two are **nested** —
+ * `two-channel-couplings.json` carries `ratified` / `inspected` / `counts`
+ * sub-objects, and the certificate nests a `contractVersion` /
+ * `packageVersions` / `provenances` record under each digest. Mapping them
+ * would make the driver run, fail to parse, exit 1 and leave the conflict
+ * exactly where it was — a control announcing coverage it does not have.
+ *
+ * So the unregistered set is a **capability boundary**, not an oversight, and
+ * this guard's job is to hold that distinction rather than to erase it.
+ *
+ * ## The tripwire, which is the part worth having
+ *
+ * An artifact declared `unsupported` is asserted to STILL fail the parser. The
+ * day somebody teaches the driver nested shapes, this guard goes red and names
+ * the artifact that can now be registered. A declaration that only recorded
+ * "unsupported" would quietly stay wrong forever — the failure mode of every
+ * comment that was true when written.
+ *
+ * CLI:
+ *   node scripts/check-generated-artifact-merge-coverage.mjs [--root <dir>]
+ *
+ * Exit codes:
+ *   0 — every artifact's declared merge status matches reality.
+ *   1 — a declaration is wrong, an artifact is undeclared, or a mapping is
+ *       missing or unsupported.
+ *   2 — operational error: `--root` missing its value, or a file unreadable.
+ *
+ * @module scripts/check-generated-artifact-merge-coverage
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+import { invokedAsScript } from "./lib/invoked-as-script.mjs";
+import { parseArtifact, renderArtifact } from "./merge-generated-artifact.mjs";
+
+/** The driver name `.gitattributes` maps an artifact to. */
+export const DRIVER = "lisa-generated-artifact";
+
+/** The npm script that runs every generated-artifact check in one go. */
+export const AGGREGATE_CHECK = "check:artifacts";
+
+/** Merge dispositions an artifact may declare. */
+export const DISPOSITION = Object.freeze({
+  DRIVER: "driver",
+  UNSUPPORTED: "unsupported",
+});
+
+/**
+ * Every checked-in generated artifact, with the npm check that regenerates it
+ * and the merge disposition it claims.
+ *
+ * The `check` field is not decoration: {@link undeclaredChecks} reads it so a
+ * fifth artifact cannot join `check:artifacts` without also appearing here.
+ */
+export const GENERATED_ARTIFACTS = Object.freeze([
+  Object.freeze({
+    path: "src/core/upstream-evidence-manifest.ts",
+    check: "check:upstream-evidence-manifest",
+    disposition: DISPOSITION.DRIVER,
+    reason: "",
+  }),
+  Object.freeze({
+    path: "src/core/lisa-owned-hash-ledger.ts",
+    check: "check:lisa-owned-hash-ledger",
+    disposition: DISPOSITION.DRIVER,
+    reason: "",
+  }),
+  Object.freeze({
+    path: "scripts/two-channel-couplings.json",
+    check: "check:two-channel-couplings",
+    disposition: DISPOSITION.UNSUPPORTED,
+    reason:
+      "nested: `ratified` / `inspected` / `counts` sub-objects, which the driver's flat one-level parser rejects",
+  }),
+  Object.freeze({
+    path: "src/core/nightly-e2e-guard-behavior-certificate.ts",
+    check: "check:nightly-guard-certificate",
+    disposition: DISPOSITION.UNSUPPORTED,
+    reason:
+      "nested: a contractVersion / packageVersions / provenances record under each digest, which the driver's flat one-level parser rejects",
+  }),
+]);
+
+/**
+ * Checks named by `check:artifacts` that own no generated artifact.
+ *
+ * `check:deletion-basis` reads the hand-authored `deletions.json` files. There
+ * is no generator behind it and therefore nothing for a merge driver to
+ * reconstruct, so it is out of this guard's subject rather than undeclared.
+ */
+export const NON_ARTIFACT_CHECKS = Object.freeze([
+  "check:deletion-basis",
+  // This guard itself. It runs inside `check:artifacts` and generates nothing;
+  // it was the first thing its own undeclared-check arm caught, which is the
+  // arm working rather than a special case being carved out for it.
+  "check:merge-coverage",
+]);
+
+/**
+ * Whether `.gitattributes` maps a path to the generated-artifact driver.
+ * @param {string} attributes - Contents of `.gitattributes`
+ * @param {string} artifactPath - Repository-relative artifact path
+ * @returns {boolean} True when a line maps exactly that path to the driver.
+ */
+export function mapsToDriver(attributes, artifactPath) {
+  return attributes
+    .split("\n")
+    .map(line => line.trim())
+    .includes(`${artifactPath} merge=${DRIVER}`);
+}
+
+/**
+ * Whether the driver can actually structure an artifact.
+ *
+ * Three conditions, and the third is the one that took measuring:
+ *
+ * 1. it parses;
+ * 2. re-emitting the parse reproduces the bytes, because the driver writes
+ *    back what it read and a lossy parse would corrupt the file;
+ * 3. **it yields at least one structured entry.** The parser passes
+ *    unrecognised regions through verbatim as opaque text, so conditions 1 and
+ *    2 alone are nearly unfalsifiable — measured, a hash ledger with every
+ *    leading indent stripped still parsed and still round-tripped exactly,
+ *    while structuring **0** entries. A mapping over a file the driver
+ *    structures nothing in is inert: it would merge no entry pointwise and
+ *    fall back to picking a side.
+ *
+ * ## What this deliberately does NOT claim
+ *
+ * It is a floor, not a proof of fidelity. Measured, reindenting a single entry
+ * left the count unchanged at 148, and appending a stray line *raised* it to
+ * 149 by structuring the stray as an entry. So this catches total structural
+ * collapse and an unparseable shape; it does not catch an artifact the parser
+ * structures slightly wrong. Saying so here rather than letting a future
+ * reader infer a stronger guarantee from a passing check.
+ * @param {string} text - The artifact's contents
+ * @returns {{ok: boolean, reason: string, entries: number}} Verdict, why not, and the entry count.
+ */
+export function driverCanStructure(text) {
+  const parsed = parseArtifact(text);
+  if (!parsed.ok) return { ok: false, reason: parsed.reason, entries: 0 };
+  if (renderArtifact(parsed.chunks) !== text)
+    return {
+      ok: false,
+      reason: "parsed, but re-emitting it changed the bytes",
+      entries: 0,
+    };
+  const entries = parsed.chunks.reduce(
+    (total, chunk) =>
+      total + (chunk.entries instanceof Map ? chunk.entries.size : 0),
+    0
+  );
+  return entries > 0
+    ? { ok: true, reason: "", entries }
+    : {
+        ok: false,
+        reason: "parsed and round-tripped, but structured ZERO entries",
+        entries: 0,
+      };
+}
+
+/**
+ * Checks wired into `check:artifacts` that no artifact declares.
+ * @param {string} packageJson - Contents of `package.json`
+ * @returns {string[]} Check names present in the script and undeclared here.
+ */
+export function undeclaredChecks(packageJson) {
+  const script = JSON.parse(packageJson).scripts?.[AGGREGATE_CHECK] ?? "";
+  const known = new Set([
+    // The aggregate names itself in its own failure message, so it appears in
+    // its own body. Excluding it here rather than in the regex keeps the regex
+    // a plain "find every check" and puts the reason next to the exclusion.
+    AGGREGATE_CHECK,
+    ...GENERATED_ARTIFACTS.map(entry => entry.check),
+    ...NON_ARTIFACT_CHECKS,
+  ]);
+  const referenced = [...script.matchAll(/\bcheck:[a-z0-9-]+/gu)].map(
+    match => match[0]
+  );
+  return [...new Set(referenced)].filter(name => !known.has(name));
+}
+
+/**
+ * Judge one artifact against its declaration.
+ * @param {object} entry - One {@link GENERATED_ARTIFACTS} record
+ * @param {string} attributes - Contents of `.gitattributes`
+ * @param {string} text - The artifact's contents
+ * @returns {string[]} Human-readable violations; empty when the declaration holds.
+ */
+export function judgeArtifact(entry, attributes, text) {
+  const mapped = mapsToDriver(attributes, entry.path);
+  const { ok, reason } = driverCanStructure(text);
+  const wantsDriver = entry.disposition === DISPOSITION.DRIVER;
+
+  if (wantsDriver && !mapped)
+    return [
+      `${entry.path}: declared \`driver\` but .gitattributes does not map it. Add:\n    ${entry.path} merge=${DRIVER}`,
+    ];
+  if (wantsDriver && !ok)
+    return [
+      `${entry.path}: declared \`driver\` and mapped, but the driver cannot structure it (${reason}). The mapping is inert — git falls back to a text merge and says nothing about the driver having done nothing.`,
+    ];
+  if (!wantsDriver && mapped)
+    return [
+      `${entry.path}: declared \`unsupported\` yet .gitattributes maps it to ${DRIVER}. The driver will run, fail, and leave the conflict while appearing to have handled it.`,
+    ];
+  if (!wantsDriver && ok)
+    return [
+      `${entry.path}: declared \`unsupported\` — reason recorded as "${entry.reason}" — but the driver can now structure it. The boundary moved: map it in .gitattributes and change its disposition to \`driver\`.`,
+    ];
+  return [];
+}
+
+/**
+ * Read one repository-relative file.
+ * @param {string} root - Repository root
+ * @param {string} relative - Repository-relative path
+ * @returns {string} File contents.
+ */
+function read(root, relative) {
+  return readFileSync(path.join(root, relative), "utf8");
+}
+
+/**
+ * Run the whole check against a checkout.
+ * @param {string} root - Repository root
+ * @returns {{violations: string[], checked: number}} What failed, and how many artifacts were read.
+ */
+export function inspectGeneratedArtifacts(root) {
+  const attributes = read(root, ".gitattributes");
+  const undeclared = undeclaredChecks(read(root, "package.json")).map(
+    name =>
+      `${name} runs in \`check:artifacts\` but no entry in GENERATED_ARTIFACTS declares it. A generated artifact that nothing declares cannot be told from one that needs no merge driver — add it, or list it in NON_ARTIFACT_CHECKS with the reason it owns no artifact.`
+  );
+  const perArtifact = GENERATED_ARTIFACTS.flatMap(entry =>
+    judgeArtifact(entry, attributes, read(root, entry.path))
+  );
+  return {
+    violations: [...undeclared, ...perArtifact],
+    checked: GENERATED_ARTIFACTS.length,
+  };
+}
+
+/**
+ * CLI entry point.
+ * @param {string[]} argv - Arguments after the script name
+ * @returns {number} Process exit code.
+ */
+export function main(argv) {
+  const flag = argv.indexOf("--root");
+  if (flag !== -1 && argv[flag + 1] === undefined) {
+    console.error("--root requires a directory");
+    return 2;
+  }
+  const root = flag === -1 ? process.cwd() : argv[flag + 1];
+
+  const { violations, checked } = inspectGeneratedArtifacts(root);
+  if (violations.length === 0) {
+    const driven = GENERATED_ARTIFACTS.filter(
+      entry => entry.disposition === DISPOSITION.DRIVER
+    ).length;
+    console.log(
+      `generated-artifact merge coverage: ${String(checked)} artifact(s) declared, ${String(driven)} merge-driver covered, ${String(checked - driven)} declared unsupported and still unparseable by the driver.`
+    );
+    return 0;
+  }
+  const detail = violations.map(line => `  - ${line}`).join("\n");
+  console.error(`generated-artifact merge coverage FAILED:\n${detail}`);
+  return 1;
+}
+
+if (invokedAsScript(import.meta.url)) {
+  process.exit(main(process.argv.slice(2)));
+}