@codyswann/lisa 4.17.6 → 4.17.7

package/dist/utils/postinstall-trampoline-report-source.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file postinstall-trampoline-report-source.ts
+ * @description The two reporting fragments inlined into the detached
+ * reconciliation child.
+ *
+ * These exist because the child is detached and `stdio: "ignore"`: anything it
+ * says to a stream is said to nobody, so the only evidence that survives the
+ * package manager exiting is a file. Before them, a trampoline that never
+ * spawned, one that died on arrival, and one that ran and correctly did nothing
+ * were indistinguishable — which is what made CodySwannGT/lisa#2750 invisible
+ * for as long as it existed.
+ * @module utils
+ */
+/**
+ * The report writer inlined into the trampoline child.
+ *
+ * This is the deliverable half of CodySwannGT/lisa#2750. The child is detached
+ * and `stdio: "ignore"`, so anything it says to a stream is said to nobody; the
+ * only place it can leave evidence is the filesystem, and the only evidence that
+ * survives the parent exiting is a file. Every write is atomic (temp + rename)
+ * so `lisa doctor` never reads a half-written document, and every write is
+ * wrapped so a read-only or full disk degrades to the old silence rather than
+ * killing a reconciliation that would otherwise have worked.
+ *
+ * `scheduled_at` and `lisa_version` are inherited from the report the parent
+ * apply wrote, so the age doctor reports is the age of the WHOLE reconciliation
+ * rather than of its last heartbeat.
+ * @param literals - Inlined JSON-safe literals
+ * @param literals.reportPath - Absolute path of the report file
+ * @param literals.reportSchemaVersion - Schema version stamped into each write
+ * @param literals.lisaVersion - Fallback Lisa version when no prior report exists
+ * @returns JS source fragment
+ */
+export declare function buildTrampolineReporter(literals: {
+    readonly reportPath: string;
+    readonly reportSchemaVersion: string;
+    readonly lisaVersion: string;
+}): string;
+/**
+ * The regen-outcome reporter inlined into the trampoline child.
+ *
+ * Split from the main IIFE only so each stays under the repo's function-length
+ * cap; it is the terminal half of one decision. Three outcomes, deliberately
+ * distinct: a regen that failed, a package.json change with no lockfile to
+ * repair, and a regen that landed. Collapsing any pair of them would restore
+ * exactly the ambiguity CodySwannGT/lisa#2750 was filed about.
+ * @returns JS source fragment
+ */
+export declare function buildTrampolineRegenReporter(): string;
+//# sourceMappingURL=postinstall-trampoline-report-source.d.ts.map

package/dist/utils/postinstall-trampoline-report-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postinstall-trampoline-report-source.d.ts","sourceRoot":"","sources":["../../src/utils/postinstall-trampoline-report-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GAAG,MAAM,CAqCT;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,IAAI,MAAM,CA8BrD"}

package/dist/utils/postinstall-trampoline-report-source.js

@@ -0,0 +1,113 @@
+/**
+ * @file postinstall-trampoline-report-source.ts
+ * @description The two reporting fragments inlined into the detached
+ * reconciliation child.
+ *
+ * These exist because the child is detached and `stdio: "ignore"`: anything it
+ * says to a stream is said to nobody, so the only evidence that survives the
+ * package manager exiting is a file. Before them, a trampoline that never
+ * spawned, one that died on arrival, and one that ran and correctly did nothing
+ * were indistinguishable — which is what made CodySwannGT/lisa#2750 invisible
+ * for as long as it existed.
+ * @module utils
+ */
+/**
+ * The report writer inlined into the trampoline child.
+ *
+ * This is the deliverable half of CodySwannGT/lisa#2750. The child is detached
+ * and `stdio: "ignore"`, so anything it says to a stream is said to nobody; the
+ * only place it can leave evidence is the filesystem, and the only evidence that
+ * survives the parent exiting is a file. Every write is atomic (temp + rename)
+ * so `lisa doctor` never reads a half-written document, and every write is
+ * wrapped so a read-only or full disk degrades to the old silence rather than
+ * killing a reconciliation that would otherwise have worked.
+ *
+ * `scheduled_at` and `lisa_version` are inherited from the report the parent
+ * apply wrote, so the age doctor reports is the age of the WHOLE reconciliation
+ * rather than of its last heartbeat.
+ * @param literals - Inlined JSON-safe literals
+ * @param literals.reportPath - Absolute path of the report file
+ * @param literals.reportSchemaVersion - Schema version stamped into each write
+ * @param literals.lisaVersion - Fallback Lisa version when no prior report exists
+ * @returns JS source fragment
+ */
+export function buildTrampolineReporter(literals) {
+    return `
+    const REPORT_PATH = ${literals.reportPath};
+
+    function readReport() {
+      try { return JSON.parse(readFileSync(REPORT_PATH, "utf8")); }
+      catch { return null; }
+    }
+
+    function report(outcome, detail, packageManagers) {
+      try {
+        const prior = readReport();
+        const now = new Date().toISOString();
+        const doc = {
+          schema_version: ${literals.reportSchemaVersion},
+          lisa_version:
+            prior && typeof prior.lisa_version === "string"
+              ? prior.lisa_version
+              : ${literals.lisaVersion},
+          outcome: outcome,
+          scheduled_at:
+            prior && typeof prior.scheduled_at === "string"
+              ? prior.scheduled_at
+              : now,
+          updated_at: now,
+          package_managers: packageManagers || [],
+          detail: detail,
+        };
+        mkdirSync(path.dirname(REPORT_PATH), { recursive: true });
+        const tempPath = REPORT_PATH + ".tmp";
+        writeFileSync(tempPath, JSON.stringify(doc, null, 2) + "\\n");
+        renameSync(tempPath, REPORT_PATH);
+      } catch {
+        // A report that cannot be written must never break an install.
+      }
+    }
+  `;
+}
+/**
+ * The regen-outcome reporter inlined into the trampoline child.
+ *
+ * Split from the main IIFE only so each stays under the repo's function-length
+ * cap; it is the terminal half of one decision. Three outcomes, deliberately
+ * distinct: a regen that failed, a package.json change with no lockfile to
+ * repair, and a regen that landed. Collapsing any pair of them would restore
+ * exactly the ambiguity CodySwannGT/lisa#2750 was filed about.
+ * @returns JS source fragment
+ */
+export function buildTrampolineRegenReporter() {
+    return `
+    function reportRegen(regen, reapplyNote) {
+      if (regen.failed.length > 0) {
+        report(
+          "failed",
+          "Lockfile regeneration failed for: " + regen.failed.join(", ") +
+            ". Lockfiles are still out of sync with package.json, so a " +
+            "frozen-lockfile install will fail." + reapplyNote,
+          regen.attempted
+        );
+        return;
+      }
+      if (regen.attempted.length === 0) {
+        report(
+          "not-needed",
+          "package.json changed but no lockfile was found to regenerate." +
+            reapplyNote,
+          []
+        );
+        return;
+      }
+      report(
+        "regenerated",
+        "Regenerated lockfiles for: " + regen.attempted.join(", ") + "." +
+          reapplyNote,
+        regen.attempted
+      );
+    }
+  `;
+}
+//# sourceMappingURL=postinstall-trampoline-report-source.js.map

package/dist/utils/postinstall-trampoline-report-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postinstall-trampoline-report-source.js","sourceRoot":"","sources":["../../src/utils/postinstall-trampoline-report-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAIvC;IACC,OAAO;0BACiB,QAAQ,CAAC,UAAU;;;;;;;;;;;;4BAYjB,QAAQ,CAAC,mBAAmB;;;;kBAItC,QAAQ,CAAC,WAAW;;;;;;;;;;;;;;;;;;GAkBnC,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,4BAA4B;IAC1C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BN,CAAC;AACJ,CAAC"}

package/dist/utils/postinstall-trampoline-source.d.ts

@@ -0,0 +1,65 @@
+import type { LockfileRegenPlan, PackageManager } from "./package-manager-detect.js";
+/**
+ * What the detached child needs in order to leave a durable record of itself.
+ *
+ * Passed in by the caller rather than imported, so this module stays free of a
+ * dependency on `core/`: the report's path and schema still have exactly one
+ * definition (`core/reconciliation-report`), and it travels here as data.
+ */
+export interface TrampolineReporting {
+    /** Absolute path of the report file the child writes. */
+    readonly reportPath: string;
+    /** Schema version stamped into every write. */
+    readonly reportSchemaVersion: number;
+    /** Lisa version, used only when no scheduled report exists to inherit it from. */
+    readonly lisaVersion: string;
+    /**
+     * sha256 of package.json as it stood BEFORE the apply that scheduled this
+     * child — which is the content the package manager resolved its lockfile
+     * from.
+     *
+     * This is the whole of CodySwannGT/lisa#2750. The child used to regenerate
+     * lockfiles only when ITS OWN re-apply changed package.json, which on a plain
+     * `bun install` it never does: the first apply (inside postinstall) already
+     * made the change, and the re-apply is idempotent. So the drift the first
+     * apply created — the drift the trampoline exists to repair — was the one
+     * case that never triggered a regen. Comparing against this baseline asks the
+     * question that actually matters: does package.json still match what the
+     * lockfile was built from?
+     */
+    readonly baselinePackageJsonHash: string | null;
+}
+/**
+ * Shape of the parameters embedded into the trampoline's inline JS source.
+ * Grouping keeps the callsite readable and the injected literals explicit.
+ */
+interface TrampolineSourceParams {
+    readonly parentPid: number;
+    readonly pollIntervalMs: number;
+    readonly maxWaitMs: number;
+    readonly settleDelayMs: number;
+    readonly lisaEntry: string;
+    readonly projectDir: string;
+    readonly nodeBin: string;
+    readonly trampolineEnvVar: string;
+    readonly lockfileRegenPlans: Readonly<Record<PackageManager, LockfileRegenPlan>>;
+    readonly reporting: TrampolineReporting;
+}
+/**
+ * Build the inline JS source that runs inside the detached trampoline child.
+ * The source is passed to `node -e` so it must be self-contained (no imports that
+ * require resolution via package.json, which is exactly the file we're racing).
+ *
+ * The trampoline now runs in two phases inside the child:
+ * 1. Wait for the parent PM to exit, then re-invoke Lisa to reconcile package.json.
+ * 2. If Lisa's re-invocation mutated package.json, regenerate whichever lockfiles
+ *    are present in the project so `bun install --frozen-lockfile` / `npm ci` in
+ *    downstream CI jobs do not fail with "lockfile had changes, but lockfile is
+ *    frozen." Lockfile regen runs with `--ignore-scripts` so the parent PM's
+ *    lifecycle hooks are not re-invoked (which would retrigger this trampoline).
+ * @param params - Embedded constants to inline into the trampoline source
+ * @returns JS source suitable for `node -e`
+ */
+export declare function buildTrampolineSource(params: TrampolineSourceParams): string;
+export {};
+//# sourceMappingURL=postinstall-trampoline-source.d.ts.map

package/dist/utils/postinstall-trampoline-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postinstall-trampoline-source.d.ts","sourceRoot":"","sources":["../../src/utils/postinstall-trampoline-source.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACf,MAAM,6BAA6B,CAAC;AAMrC;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED;;;GAGG;AACH,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,QAAQ,CACnC,MAAM,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAC1C,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;CACzC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,sBAAsB,GAAG,MAAM,CA4B5E"}

package/dist/utils/postinstall-trampoline-source.js

@@ -0,0 +1,312 @@
+/**
+ * @file postinstall-trampoline-source.ts
+ * @description The JS source that runs inside the detached reconciliation child.
+ *
+ * Split out of `postinstall-trampoline` because it is a different kind of code:
+ * everything here is a string template compiled into a `node -e` payload, which
+ * cannot import anything (it runs while package.json — the file it is repairing
+ * — is in flux), so every constant it needs is inlined as a JSON literal at
+ * build time. Keeping it beside the scheduling logic made one module that was
+ * half TypeScript and half generated JavaScript.
+ *
+ * The child's job, in order: announce that it is alive, wait for the package
+ * manager to exit, re-apply Lisa, and regenerate lockfiles when package.json no
+ * longer matches the baseline the package manager resolved its lockfile from —
+ * then record what it did (CodySwannGT/lisa#2750).
+ * @module utils
+ */
+import { PM_PATH_ENV_NAMES, PM_PATH_ENV_PREFIXES } from "./pm-env.js";
+import { buildTrampolineRegenReporter, buildTrampolineReporter, } from "./postinstall-trampoline-report-source.js";
+/**
+ * Build the inline JS source that runs inside the detached trampoline child.
+ * The source is passed to `node -e` so it must be self-contained (no imports that
+ * require resolution via package.json, which is exactly the file we're racing).
+ *
+ * The trampoline now runs in two phases inside the child:
+ * 1. Wait for the parent PM to exit, then re-invoke Lisa to reconcile package.json.
+ * 2. If Lisa's re-invocation mutated package.json, regenerate whichever lockfiles
+ *    are present in the project so `bun install --frozen-lockfile` / `npm ci` in
+ *    downstream CI jobs do not fail with "lockfile had changes, but lockfile is
+ *    frozen." Lockfile regen runs with `--ignore-scripts` so the parent PM's
+ *    lifecycle hooks are not re-invoked (which would retrigger this trampoline).
+ * @param params - Embedded constants to inline into the trampoline source
+ * @returns JS source suitable for `node -e`
+ */
+export function buildTrampolineSource(params) {
+    // JSON.stringify gives us safe inline literals for all primitive types.
+    const literals = {
+        parentPid: JSON.stringify(params.parentPid),
+        pollIntervalMs: JSON.stringify(params.pollIntervalMs),
+        maxWaitMs: JSON.stringify(params.maxWaitMs),
+        settleDelayMs: JSON.stringify(params.settleDelayMs),
+        lisaEntry: JSON.stringify(params.lisaEntry),
+        projectDir: JSON.stringify(params.projectDir),
+        nodeBin: JSON.stringify(params.nodeBin),
+        trampolineEnvVar: JSON.stringify(params.trampolineEnvVar),
+        lockfilePlans: JSON.stringify(params.lockfileRegenPlans),
+        pmEnvPrefixes: JSON.stringify(PM_PATH_ENV_PREFIXES),
+        pmEnvNames: JSON.stringify(PM_PATH_ENV_NAMES),
+        reportPath: JSON.stringify(params.reporting.reportPath),
+        reportSchemaVersion: JSON.stringify(params.reporting.reportSchemaVersion),
+        lisaVersion: JSON.stringify(params.reporting.lisaVersion),
+        baselineHash: JSON.stringify(params.reporting.baselinePackageJsonHash),
+    };
+    return [
+        buildTrampolinePrelude(literals),
+        buildTrampolineReporter(literals),
+        buildTrampolinePmHelpers(literals),
+        buildTrampolineHelpers(literals),
+        buildTrampolineRegenReporter(),
+        buildTrampolineMain(literals),
+    ].join("\n");
+}
+/**
+ * Inline `require` prelude + the lockfile plan table. Kept separate so each
+ * chunk of the trampoline source stays under the 75-line max-lines-per-function
+ * cap enforced by eslint.
+ * @param literals - Inlined JSON-safe literals
+ * @param literals.lockfilePlans - JSON-serialized lockfile plan table
+ * @param literals.pmEnvPrefixes - JSON-serialized package-manager env var prefixes to strip
+ * @param literals.pmEnvNames - JSON-serialized package-manager env var names to strip
+ * @returns JS source fragment
+ */
+function buildTrampolinePrelude(literals) {
+    return `
+    const { spawn } = require("node:child_process");
+    const { createHash } = require("node:crypto");
+    const {
+      existsSync,
+      mkdirSync,
+      readFileSync,
+      renameSync,
+      writeFileSync,
+    } = require("node:fs");
+    const path = require("node:path");
+
+    const LOCKFILE_PLANS = ${literals.lockfilePlans};
+    const PM_ENV_PREFIXES = ${literals.pmEnvPrefixes};
+    const PM_ENV_NAMES = ${literals.pmEnvNames};
+    // Strip PM path/lifecycle vars from spawned bun/Lisa env. Mirrors pm-env.ts.
+    function sanitizeEnv(env) {
+      const bad = (k) => PM_ENV_NAMES.indexOf(k) !== -1 || PM_ENV_PREFIXES.some((p) => k.startsWith(p));
+      return Object.fromEntries(Object.entries(env).filter(([k]) => !bad(k)));
+    }
+  `;
+}
+/**
+ * Package-manager helpers inlined into the trampoline child: the `engines`
+ * opt-out reader, the lockfile-presence detector, and the regen loop.
+ *
+ * The regen loop is still best-effort at the process level — a missing package
+ * manager binary must never cascade into a failed install — but it now returns
+ * which managers it tried and which failed, so the outcome can be recorded
+ * instead of swallowed (CodySwannGT/lisa#2750).
+ * @param literals - Inlined JSON-safe literals
+ * @param literals.projectDir - Project directory whose lockfiles are regenerated
+ * @returns JS source fragment
+ */
+function buildTrampolinePmHelpers(literals) {
+    return `
+    function enginesForbiddenManagers(dir) {
+      try {
+        const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+        const engines = (pkg && pkg.engines) || {};
+        return ["bun", "npm", "yarn", "pnpm"].filter(
+          (pm) => typeof engines[pm] === "string" && /please-use|do-not-use/i.test(engines[pm])
+        );
+      } catch {
+        return [];
+      }
+    }
+
+    function detectPackageManagers(dir) {
+      const forbidden = enginesForbiddenManagers(dir);
+      return Object.values(LOCKFILE_PLANS)
+        .filter((plan) => [plan.lockfile].concat(plan.lockfileAlternatives || []).some((f) => existsSync(path.join(dir, f))))
+        .map((plan) => plan.pm)
+        .filter((pm) => forbidden.indexOf(pm) === -1);
+    }
+
+    async function regenerateLockfiles() {
+      const attempted = [];
+      const failed = [];
+      for (const pm of detectPackageManagers(${literals.projectDir})) {
+        const plan = LOCKFILE_PLANS[pm];
+        if (!plan) continue;
+        attempted.push(pm);
+        // Still best-effort at the process level: a missing PM binary must not
+        // cascade into an install failure. What changed is that the failure is
+        // now RECORDED instead of swallowed outright, which is what makes a
+        // regen that did not work distinguishable from one that had nothing to
+        // do (CodySwannGT/lisa#2750).
+        const ok = await spawnChild(plan.command, plan.args);
+        if (!ok) {
+          failed.push(pm + " (" + plan.command + " " + plan.args.join(" ") + ")");
+        }
+      }
+      return { attempted: attempted, failed: failed };
+    }
+  `;
+}
+/**
+ * Process helpers inlined into the trampoline child: parent-liveness probe,
+ * file hasher, the wait loop, the sanitised child spawner, and the Lisa
+ * re-invoker. Each mirrors an exported TS helper in `postinstall-trampoline` or
+ * `package-manager-detect`, so the logic stays test-covered via those.
+ * @param literals - Inlined JSON-safe literals
+ * @param literals.parentPid - Parent package-manager PID for liveness probe
+ * @param literals.pollIntervalMs - Poll interval for parent-liveness checks
+ * @param literals.maxWaitMs - Max wait deadline before bailing out
+ * @param literals.nodeBin - Node binary path to re-invoke Lisa with
+ * @param literals.lisaEntry - Absolute path to Lisa's dist/index.js
+ * @param literals.projectDir - Project directory Lisa will reconcile
+ * @param literals.trampolineEnvVar - Env var name used to mark child as trampoline
+ * @returns JS source fragment
+ */
+function buildTrampolineHelpers(literals) {
+    return `
+    function isAlive(pid) {
+      if (!pid || pid <= 1) return false;
+      try { process.kill(pid, 0); return true; } catch { return false; }
+    }
+
+    function hashFile(p) {
+      try { return createHash("sha256").update(readFileSync(p)).digest("hex"); }
+      catch { return null; }
+    }
+
+    async function waitForParent() {
+      const deadline = Date.now() + ${literals.maxWaitMs};
+      while (Date.now() < deadline) {
+        if (!isAlive(${literals.parentPid})) return true;
+        await new Promise((r) => setTimeout(r, ${literals.pollIntervalMs}));
+      }
+      return false;
+    }
+
+    function spawnChild(command, args) {
+      return new Promise((resolve) => {
+        try {
+          const child = spawn(command, args, {
+            cwd: ${literals.projectDir},
+            stdio: "ignore",
+            env: Object.assign(sanitizeEnv(process.env), { [${literals.trampolineEnvVar}]: "1" }),
+          });
+          child.on("exit", (code) => resolve(code === 0));
+          child.on("error", () => resolve(false));
+        } catch {
+          resolve(false);
+        }
+      });
+    }
+
+    function runLisa() {
+      return spawnChild(${literals.nodeBin}, [${literals.lisaEntry}, "--yes", "--skip-git-check", ${literals.projectDir}]);
+    }
+
+  `;
+}
+/**
+ * Top-level async IIFE that orchestrates the trampoline child:
+ * 1) announce that the child is alive (so a spawn that produced nothing is
+ *    distinguishable from one that ran),
+ * 2) wait for the parent PM to exit,
+ * 3) re-run Lisa,
+ * 4) regenerate lockfiles when package.json no longer matches the baseline the
+ *    package manager resolved its lockfile from,
+ * 5) record the outcome either way.
+ *
+ * Step 4 is the fix for CodySwannGT/lisa#2750. It used to compare package.json
+ * before and after the child's OWN re-apply, and regenerate only when that
+ * re-apply changed something. On the path that matters — a plain `bun install`
+ * where the first apply (inside postinstall) already rewrote package.json and
+ * the re-apply is therefore idempotent — that comparison is always equal, so
+ * the regen never ran and the lockfile stayed exactly as stale as the install
+ * left it. Measured on a bun consumer: `bun.lock`'s mtime never moved, while
+ * the regen plan run by hand fixed the drift in 1.66 s.
+ *
+ * The baseline comparison asks the right question instead: package.json is
+ * compared against its content BEFORE the first apply, which is what the
+ * lockfile was built from. It also no longer requires the re-apply to have
+ * SUCCEEDED — a re-apply that fails leaves the first apply's drift in place,
+ * and refusing to regen there is the one case where the lockfile is guaranteed
+ * wrong.
+ *
+ * Timing out MUST NOT re-run Lisa — that would reintroduce the package.json
+ * race the trampoline is designed to avoid (parent PM still writing).
+ * @param literals - Inlined JSON-safe literals
+ * @param literals.settleDelayMs - Settle delay before re-invoking Lisa
+ * @param literals.projectDir - Project directory Lisa will reconcile
+ * @param literals.baselineHash - sha256 of package.json before the apply that scheduled this child
+ * @returns JS source fragment
+ */
+function buildTrampolineMain(literals) {
+    return `
+    (async () => {
+      try {
+        report(
+          "started",
+          "Waiting for the package manager to exit before re-applying Lisa.",
+          []
+        );
+        const parentExited = await waitForParent();
+        if (!parentExited) {
+          report(
+            "parent-wait-timed-out",
+            "The package manager was still running after the wait deadline, so " +
+              "Lisa did not re-apply (re-applying under a live package manager " +
+              "is the race this exists to avoid). Lockfiles may be out of sync " +
+              "with package.json.",
+            []
+          );
+          process.exit(0);
+        }
+        await new Promise((r) => setTimeout(r, ${literals.settleDelayMs}));
+
+        const pkgPath = path.join(${literals.projectDir}, "package.json");
+        const baselineHash = ${literals.baselineHash};
+
+        const lisaOk = await runLisa();
+        const reapplyNote = lisaOk
+          ? ""
+          : " The re-apply itself exited non-zero; run it by hand to see why.";
+
+        const postHash = hashFile(pkgPath);
+        if (postHash === null) {
+          report(
+            "failed",
+            "package.json could not be read after the re-apply, so lockfile " +
+              "drift could not be assessed." + reapplyNote,
+            []
+          );
+          process.exit(0);
+        }
+
+        // Compare against what the package manager built the lockfile FROM,
+        // not against what this child's own idempotent re-apply changed.
+        if (baselineHash !== null && postHash === baselineHash) {
+          report(
+            "not-needed",
+            "package.json matches what the package manager resolved the " +
+              "lockfile from, so no lockfile can be stale." + reapplyNote,
+            []
+          );
+          process.exit(0);
+        }
+
+        reportRegen(await regenerateLockfiles(), reapplyNote);
+
+        process.exit(0);
+      } catch (error) {
+        report(
+          "failed",
+          "The reconciliation aborted before completing: " +
+            (error && error.message ? error.message : String(error)),
+          []
+        );
+        process.exit(0);
+      }
+    })();
+  `;
+}
+//# sourceMappingURL=postinstall-trampoline-source.js.map

package/dist/utils/postinstall-trampoline-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postinstall-trampoline-source.js","sourceRoot":"","sources":["../../src/utils/postinstall-trampoline-source.ts"],"names":[],"mappings":"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"}

package/dist/utils/postinstall-trampoline.d.ts

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
 import { type LockfileRegenPlan, type PackageManager, LOCKFILE_REGEN_PLANS, detectPackageManagers, enginesForbiddenManagers, getLockfileRegenPlan } from "./package-manager-detect.js";
+import type { TrampolineReporting } from "./postinstall-trampoline-source.js";
 export { LOCKFILE_REGEN_PLANS, detectPackageManagers, enginesForbiddenManagers, getLockfileRegenPlan, };
-export type { LockfileRegenPlan, PackageManager };
+export type { LockfileRegenPlan, PackageManager, TrampolineReporting };
 /**
  * Determine whether this Lisa invocation is running as a package-manager lifecycle
  * script (postinstall, prepare, etc.). Works across npm, bun, yarn, and pnpm since
@@ -103,8 +104,9 @@ export declare function regenerateLockfilesInProcess(projectDir: string, spawnFn
  * @param projectDir - Absolute path to the project directory Lisa will reconcile
  * @param lisaDistDir - Absolute path to Lisa's dist directory (where index.js lives)
  * @param parentPid - PID of the package-manager process to wait on (usually process.ppid)
+ * @param reporting - Report path/schema plus the pre-apply package.json baseline the child compares against
  * @param spawnFn - Optional spawn implementation; defaults to node:child_process spawn. Tests pass a vi.fn() spy here as a dependency-injection seam, avoiding the unreliable vi.doMock-on-builtins pattern that breaks under v8 coverage in CI runners.
  * @returns Promise that resolves immediately after spawning the detached child
  */
-export declare function scheduleReconciliationChild(projectDir: string, lisaDistDir: string, parentPid: number, spawnFn?: typeof spawn): Promise<void>;
+export declare function scheduleReconciliationChild(projectDir: string, lisaDistDir: string, parentPid: number, reporting: TrampolineReporting, spawnFn?: typeof spawn): Promise<void>;
 //# sourceMappingURL=postinstall-trampoline.d.ts.map

package/dist/utils/postinstall-trampoline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postinstall-trampoline.d.ts","sourceRoot":"","sources":["../../src/utils/postinstall-trampoline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAU3C,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AAoCrC,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,CAAC;AACF,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,CAAC;AAkBlD;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CASvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uCAAuC,CACrD,MAAM,EAAE,OAAO,GACd,OAAO,CAaT;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EAMjB,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAmCf"}
+{"version":3,"file":"postinstall-trampoline.d.ts","sourceRoot":"","sources":["../../src/utils/postinstall-trampoline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAM3C,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAqC9E,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,GACrB,CAAC;AACF,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,mBAAmB,EAAE,CAAC;AAkBvE;;;;;GAKG;AACH,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,IAAI,OAAO,CASvC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uCAAuC,CACrD,MAAM,EAAE,OAAO,GACd,OAAO,CAaT;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAgBf;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,2BAA2B,CAC/C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,mBAAmB,EAM9B,OAAO,GAAE,OAAO,KAAa,GAC5B,OAAO,CAAC,IAAI,CAAC,CAoCf"}