create-cmp-cli 0.13.0 → 0.14.1

package/src/lib/harness-upgrade.mjs

@@ -40,8 +40,9 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 
 import { listFiles } from "./fsutil.mjs";
-import { isBinaryPath } from "./tokens.mjs";
+import { isBinaryPath, replaceTokens } from "./tokens.mjs";
 import { BACKUP_SUFFIX } from "./upgrade.mjs";
+import { isHarnessFile } from "../../packages/harness/src/lib/harness-region.mjs";
 
 /** Sidecar suffix for the new engine content beside a conflicted file. */
 export const SIDECAR_SUFFIX = ".cmp-new";
@@ -62,6 +63,10 @@ export const EXCLUDED_PATTERNS = [
   "create-cmp.json",
   "qa/evidence/**",
   "qa/approvals.json",
+  // Derived state, rewritten explicitly once the region has landed. Sweeping
+  // it would copy a stale manifest in, back up a value that was about to be
+  // replaced anyway, and count a guaranteed no-op as actionable work.
+  "qa/harness.lock.json",
   "qa/comments.json",
   "qa/golden/**",
   ".git/**",
@@ -172,7 +177,147 @@ export function mergeThreeWay(theirs, base, next) {
  * @returns {{bucket:string, write:Buffer|null, sidecar:Buffer|null, remove:boolean}|null}
  *        null when the path is in neither base nor new (app-authored — invisible)
  */
-export function decideFile({ relPath, base, next, theirs, merge = mergeThreeWay }) {
+
+
+/**
+ * A `stampBase` function for an app's recorded config — reproduces what a
+ * pre-0.14.0 engine would have written into that app's lane, so a file the
+ * stamper touched is not mistaken for a local edit. Binary-safe: content that
+ * does not round-trip through UTF-8 is returned unchanged.
+ * @param {Array<[string,string]>} tokenMap from buildTokenMap(config)
+ * @returns {(base: Buffer) => Buffer}
+ */
+export function stampBaseWith(tokenMap) {
+  return (base) => {
+    const text = base.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(base)) return base;
+    return Buffer.from(replaceTokens(text, tokenMap), "utf8");
+  };
+}
+
+/** Where a preserved local patch to machine-owned lane code is written. */
+export const LOCAL_PATCH_PATH = "qa/harness-local.patch";
+
+/**
+ * Unified diff from `base` to `theirs`, rewritten so it applies against the
+ * project tree (`git apply qa/harness-local.patch`). git diff --no-index exits
+ * 1 when there ARE differences, which is the only case we call it in.
+ * @param {Buffer} base
+ * @param {Buffer} theirs
+ * @param {string} relPath project-relative path the patch should name
+ * @returns {string} patch text, or "" if git could not produce one
+ */
+export function diffPatch(base, theirs, relPath) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "cmp-harness-diff-"));
+  try {
+    const b = path.join(dir, "base");
+    const t = path.join(dir, "theirs");
+    fs.writeFileSync(b, base);
+    fs.writeFileSync(t, theirs);
+    const r = spawnSync("git", ["diff", "--no-index", "--no-color", "--", b, t], {
+      encoding: "utf8",
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    // 0 = identical (we never call it then), 1 = differences, >1 = trouble.
+    if (r.error || (r.status !== 0 && r.status !== 1) || !r.stdout) return "";
+    return r.stdout
+      .split("\n")
+      .map((line) => {
+        if (line.startsWith("diff --git ")) return `diff --git a/${relPath} b/${relPath}`;
+        if (line.startsWith("--- ")) return `--- a/${relPath}`;
+        if (line.startsWith("+++ ")) return `+++ b/${relPath}`;
+        return line;
+      })
+      .join("\n");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * The decision table for MACHINE-OWNED lane files — a different question from
+ * the one decideFile asks about app-shaped files.
+ *
+ * Lane code is byte-identical in every create-cmp app and carries no app
+ * content, so it is a derived artifact, and the right operation on a derived
+ * artifact is REPLACE, not merge. Three-way merging it is what made upgrades
+ * expensive: the 0.13.0 pilots produced ~1,000 conflicted lines per app whose
+ * diffs contained zero app-specific tokens.
+ *
+ * The region is therefore always taken to the new engine's content. What
+ * varies is how honestly we account for what the app had:
+ *
+ *   region-current    already the new content                    → silent
+ *   region-clean      untouched since stamp                      → replace
+ *   region-absorbed   locally edited, but the edit is ALREADY in the new
+ *                     content (the app hand-mirrored engine work — the
+ *                     pilots' overwhelmingly common case) → replace, silent
+ *   region-patched    a genuine local fork of lane code → replace, AND
+ *                     preserve base→theirs as a patch so nothing is lost
+ *   added / removed   as for any other file
+ *
+ * "region-patched" deliberately does NOT block or merge. A local edit to lane
+ * code is a fork the app is maintaining; making it explicit (a reviewable
+ * patch file plus a loud report) is better than the status quo, where the
+ * divergence was invisible until it cost a thousand hand-resolved lines at
+ * the next upgrade.
+ *
+ * @param {object} params
+ * @param {string} params.relPath
+ * @param {Buffer|null} params.base
+ * @param {Buffer|null} params.next
+ * @param {Buffer|null} params.theirs
+ * @param {Function} [params.merge] injectable three-way merge (classifier only)
+ * @returns {{bucket:string, write:Buffer|null, sidecar:null, remove:boolean, patch?:string}|null}
+ */
+export function decideRegionFile({ relPath, base, next, theirs, merge = mergeThreeWay, stampBase = null }) {
+  const eq = (a, b) => a !== null && b !== null && a.equals(b);
+  const replace = (bucket, extra = {}) => ({
+    bucket,
+    write: next,
+    sidecar: null,
+    remove: false,
+    ...extra,
+  });
+
+  if (next === null) {
+    // The engine dropped this lane file. Nothing app-owned can live here, so
+    // there is no "orphaned" case to protect — remove it.
+    if (theirs === null) return { bucket: "current", write: null, sidecar: null, remove: false };
+    return { bucket: "region-removed", write: null, sidecar: null, remove: true };
+  }
+  if (theirs === null) return replace(base === null ? "added" : "region-restored");
+  if (eq(theirs, next)) return { bucket: "current", write: null, sidecar: null, remove: false };
+  if (base === null) return replace("region-patched", { patch: "" }); // no base to diff against
+  if (eq(theirs, base)) return replace("region-clean");
+
+  // The app's copy may be what its OWN engine produced rather than what the
+  // base tree holds, because engines before 0.14.0 ran lane code through the
+  // token stamper. Such an app carries `Fuelled` where the base template says
+  // `__APP_NAME__` — a difference the engine created, not the app. Asking
+  // "does this match the base as THIS app would have had it stamped?" is the
+  // accurate form of "did the app never touch it", and it needs no version
+  // comparison: for a 0.14.0+ base there is nothing left to stamp, so the
+  // check simply never fires.
+  if (stampBase !== null) {
+    const asStamped = stampBase(base);
+    if (eq(theirs, asStamped)) return replace("region-clean");
+  }
+
+  // The app edited lane code. Is that edit already carried by the new engine?
+  // A clean three-way merge landing exactly on `next` means the local change
+  // contributed nothing beyond it — the hand-mirror case.
+  const m = merge(theirs, base, next);
+  if (m.clean && m.content !== null && m.content.equals(next)) return replace("region-absorbed");
+
+  return replace("region-patched", { patch: diffPatch(base, theirs, relPath) });
+}
+
+export function decideFile({ relPath, base, next, theirs, merge = mergeThreeWay, stampBase = null }) {
+  // Machine-owned lane files answer a different question — see decideRegionFile.
+  if (isHarnessFile(relPath) && !(base === null && next === null)) {
+    return decideRegionFile({ relPath, base, next, theirs, merge, stampBase });
+  }
   const none = (bucket) => ({ bucket, write: null, sidecar: null, remove: false });
   const write = (bucket, content) => ({ bucket, write: content, sidecar: null, remove: false });
   const conflict = () => ({ bucket: "conflicted", write: null, sidecar: next, remove: false });
@@ -240,7 +385,7 @@ function toRel(root, abs) {
  *            sidecar?:Buffer|null, remove?:boolean}>,
  *            counts: Record<string, number>}}
  */
-export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeThreeWay }) {
+export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeThreeWay, stampBase = null }) {
   const rels = new Set();
   for (const f of listFiles(baseDir)) rels.add(toRel(baseDir, f));
   for (const f of listFiles(newDir)) rels.add(toRel(newDir, f));
@@ -255,6 +400,12 @@ export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeT
     added: 0,
     removed: 0,
     orphaned: 0,
+    // Machine-owned lane buckets (decideRegionFile).
+    "region-clean": 0,
+    "region-absorbed": 0,
+    "region-patched": 0,
+    "region-restored": 0,
+    "region-removed": 0,
   };
   const entries = [];
   for (const relPath of [...rels].sort()) {
@@ -269,9 +420,10 @@ export function planHarnessUpgrade({ baseDir, newDir, projectDir, merge = mergeT
       next: readIfPresent(newDir, relPath),
       theirs: readIfPresent(projectDir, relPath),
       merge,
+      stampBase,
     });
     if (decision === null) continue;
-    counts[decision.bucket] += 1;
+    counts[decision.bucket] = (counts[decision.bucket] ?? 0) + 1;
     entries.push({ relPath, ...decision });
   }
   return { entries, counts };
@@ -299,7 +451,13 @@ export function applyHarnessPlan(projectDir, entries) {
   const deleted = [];
   const sidecars = [];
   const backups = [];
+  const patched = [];
+  const patchChunks = [];
   for (const e of entries) {
+    if (e.bucket === "region-patched" && e.patch) {
+      patched.push(e.relPath);
+      patchChunks.push(e.patch.endsWith("\n") ? e.patch : `${e.patch}\n`);
+    }
     const abs = path.join(projectDir, e.relPath);
     if (e.sidecar !== null && e.sidecar !== undefined) {
       const sidecarPath = abs + SIDECAR_SUFFIX;
@@ -328,7 +486,37 @@ export function applyHarnessPlan(projectDir, entries) {
       }
     }
   }
-  return { written, created, deleted, sidecars, backups };
+  // One patch file for the whole run — the app's genuine divergence from the
+  // lane, preserved rather than discarded. Written only when there is
+  // something to preserve, and only after the writes above succeeded.
+  let patchPath = null;
+  if (patchChunks.length > 0) {
+    const abs = path.join(projectDir, LOCAL_PATCH_PATH);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(
+      abs,
+      `# Local changes to machine-owned lane code, preserved by \`create-cmp upgrade --harness\`.\n` +
+        `#\n` +
+        `# The lane was replaced with the new engine's version. These edits were NOT\n` +
+        `# re-applied — a local change to lane code is a fork this app is maintaining,\n` +
+        `# and re-applying it silently would hide that.\n` +
+        `#\n` +
+        `# This diff is against the lane you WERE on, so it may not apply cleanly to\n` +
+        `# the new one. That is not a defect in the patch: it is the merge this tool\n` +
+        `# deliberately declined to do behind your back. To attempt it:\n` +
+        `#\n` +
+        `#     git apply --reject ${LOCAL_PATCH_PATH}\n` +
+        `#\n` +
+        `# What applies, applies; the rest lands in *.rej for you to judge. If it does\n` +
+        `# conflict, that IS the finding — the engine has moved under this fork.\n` +
+        `#\n` +
+        `# Better still: upstream the change so the next upgrade carries it for you.\n` +
+        `# Delete this file once you have decided.\n\n` +
+        patchChunks.join("\n"),
+    );
+    patchPath = LOCAL_PATCH_PATH;
+  }
+  return { written, created, deleted, sidecars, backups, patched, patchPath };
 }
 
 /**

package/src/scaffold.mjs

@@ -20,6 +20,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { validate, formatErrors } from "./lib/schema.mjs";
 import { validatePackageName } from "./lib/package-name.mjs";
 import { buildTokenMap, replaceTokens, replacePathTokens, isBinaryPath, slugifyAppName } from "./lib/tokens.mjs";
+import { isHarnessFile, listHarnessFiles } from "../packages/harness/src/lib/harness-region.mjs";
+import { writeHarnessLock } from "../packages/harness/src/lib/harness-lock.mjs";
 import { renamePackageDirs } from "./lib/rename.mjs";
 import {
   stripFeatureBlocks,
@@ -78,7 +80,22 @@ export function loadManifest(templateDir) {
 }
 
 /**
- * Apply token replacement to every text file's CONTENT under projectDir.
+ * Apply token replacement to every text file's CONTENT under projectDir —
+ * except the machine-owned harness region, which is COPIED, never stamped.
+ *
+ * The lane carries no app content, so there is nothing in it to stamp; running
+ * it through token replacement only ever corrupted it. Two live examples the
+ * region rule retires: qa/lib/approvals.mjs had to detect unresolved tokens by
+ * SHAPE because writing the literal `__PACKAGE__` in its own source got
+ * rewritten out from under it, and qa/scaffold-feature.mjs shipped an error
+ * message that meant to name the unresolved token and instead named the app's
+ * real package ("found com.acme.demo unresolved"). Anything app-specific the
+ * lane needs is read at RUNTIME from create-cmp.json.
+ *
+ * Skipping the region is also what makes it content-hashable: every stamped
+ * app carries byte-identical lane files, so a receipt can name the exact lane
+ * version that issued it and an app can prove its copy is unmodified offline.
+ * test/harness-parity.test.mjs pins that byte-equality through the scaffold.
  */
 function replaceContents(projectDir, tokenMap, manifestRel) {
   for (const file of listFiles(projectDir)) {
@@ -86,6 +103,7 @@ function replaceContents(projectDir, tokenMap, manifestRel) {
     if (manifestRel && path.resolve(file) === path.resolve(path.join(projectDir, manifestRel))) {
       continue;
     }
+    if (isHarnessFile(path.relative(projectDir, file).split(path.sep).join("/"))) continue;
     if (isBinaryPath(file)) continue;
     let content;
     try {
@@ -255,6 +273,41 @@ function applyAppNameSlug(projectDir, appName) {
  * @param {string} projectDir
  * @param {object} config validated engine config
  */
+/**
+ * The harness version this engine ships — read from the package that owns the
+ * lane, NOT from the engine's own package.json. The two version independently:
+ * the lane changes far more often than the template's app shape, and fusing
+ * them is what forced an app-shape merge every time a lane fix shipped.
+ * @returns {string} semver, or "unknown" if the manifest is unreadable
+ */
+function harnessVersion() {
+  try {
+    return JSON.parse(
+      fs.readFileSync(path.join(REPO_ROOT, "packages/harness/package.json"), "utf8")
+    ).version;
+  } catch {
+    return "unknown"; // best-effort — never fail the stamp over version metadata
+  }
+}
+
+/**
+ * Record which lane this app carries, and a sha256 per machine-owned file, so
+ * the lane can prove offline on every run that it is unmodified since stamp.
+ * Runs LAST, after stamping and feature-stripping, so it hashes exactly the
+ * bytes the app will ship with.
+ * @param {string} projectDir
+ */
+function writeLaneLock(projectDir) {
+  const version = harnessVersion();
+  if (version === "unknown") return; // nothing honest to record
+  // No lane, no lock. A config that strips the harness (or a template that
+  // never carried one) must not get a manifest describing an empty region —
+  // it would attest nothing while creating the very qa/ directory the strip
+  // just removed.
+  if (listHarnessFiles(projectDir).length === 0) return;
+  writeHarnessLock(projectDir, { version });
+}
+
 function writeSpecOfRecord(projectDir, config) {
   let engineVersion = "unknown";
   try {
@@ -436,6 +489,12 @@ export async function scaffold(config, opts = {}) {
   // are visible spec changes, not drift.
   writeSpecOfRecord(projectDir, config);
 
+  // Lock the lane LAST — after stamping, feature-stripping and every other
+  // mutation — so the manifest hashes exactly the bytes this app will ship
+  // with. From here the app can prove offline, on every lane run, that its
+  // harness is the one it was given.
+  writeLaneLock(projectDir);
+
   ok("Scaffold complete.");
 
   // (f) verify gate

package/template/AGENTS.md

@@ -6,3 +6,8 @@ device-free **UI feedback loop** (render every real screen headlessly and see ex
 what your edit changed) — lives in [CLAUDE.md](./CLAUDE.md).
 
 Read CLAUDE.md before making changes. It applies to every coding agent, not only Claude.
+
+One rule worth knowing before you touch anything: the `.mjs` files directly under `qa/`
+and `qa/lib/` are **machine-owned harness code**, byte-identical in every create-cmp app
+and hash-locked by `qa/harness.lock.json`. Editing them fails the lane's first step. Fix
+the engine upstream instead — see "The lane is not yours to edit" in CLAUDE.md.

package/template/CLAUDE.md

@@ -112,6 +112,36 @@ Commit it with your change; git history is the audit ledger. Binary artifacts un
 page reconstructs the full audit trail from the git log of `latest.json` — every commit is
 one verified, attributed state — so committing each receipt is what builds the record.
 
+## The lane is not yours to edit
+
+Every `.mjs` file directly under `qa/` and `qa/lib/` is **machine-owned**: harness code
+that is byte-identical in every create-cmp app and carries no app content at all. It
+belongs to `create-cmp-harness`, versioned independently of the engine that stamped this
+app's shape, and `qa/harness.lock.json` records a sha256 of every one of those files.
+
+`node qa/verify.mjs` checks that lock first, on every run. Editing lane code fails the
+`harnessIntegrity` step and names the file — because a lane that has been modified cannot
+honestly vouch for itself. Without that check the receipt was unfalsifiable in one
+specific way: force every step to PASS in `qa/verify.mjs` and the receipt still validated,
+since the edited file was simply part of the hashed input surface.
+
+**So: do not edit `qa/*.mjs` or `qa/lib/*.mjs`.** If the lane is wrong, the fix is
+upstream in the engine, not here. If you genuinely must fork it, know that
+`npx create-cmp-cli upgrade --harness` will replace the region and preserve your edits as
+`qa/harness-local.patch` for you to re-apply or upstream — nothing is lost, but the fork
+stops being invisible.
+
+Everything else under `qa/` **is** yours: `approvals.json`, `comments.json`, `golden/`,
+`evidence/`, and `e2e/*.yaml` (seeded once at stamp time, app-owned forever after). So is
+`specs/`, and so is every line under `composeApp/src/`.
+
+Upgrading the lane is safe to do unattended — it touches no app content and no signed
+artifact:
+
+```bash
+npx create-cmp-cli upgrade --harness
+```
+
 ## Approvals — governed artifacts need a human's sign-off
 
 Some artifacts are **governed**: a human approves them, and the approval is bound to the

package/template/gitignore

@@ -26,3 +26,11 @@ iosApp/*.xcworkspace/
 iosApp/build/
 xcuserdata/
 *.xcuserstate
+
+# `create-cmp upgrade`'s pre-write backups. In a git repo the previous commit IS
+# the backup, so these are redundant the moment they are created — and committing
+# them alongside the upgrade puts a stale copy of every touched file in history.
+# Kept on disk (an upgrade run in a dirty or non-git tree still needs them),
+# ignored by git. Delete them once you have reviewed the upgrade's diff.
+*.bak-upgrade
+*.cmp-new

package/template/qa/lib/harness-lock.mjs

@@ -0,0 +1,147 @@
+// qa/harness.lock.json — which lane this app carries, and whether it is intact.
+//
+// The lock is written at stamp time and rewritten by `create-cmp upgrade
+// --harness`. It names the harness version and records a sha256 per
+// machine-owned file, so two different questions get two different answers:
+//
+//   INTEGRITY  "is my lane unmodified since it was installed?"
+//              Answered LOCALLY, offline, on every lane run. Needs nothing
+//              but the tree and this file.
+//
+//   AUTHENTICITY  "is my lane the real published create-cmp-harness@X?"
+//              Answered REMOTELY, on request, by comparing this file's
+//              `sha256` against the published version's — `create-cmp
+//              upgrade --harness` does it, and so can any third party
+//              holding a receipt.
+//
+// Being honest about that split matters. Someone who edits the lane AND
+// rewrites this lock defeats the local check — of course they do; it is a
+// checksum, not a signature. What it cannot survive is the remote comparison,
+// because the attacker cannot change what the registry published under that
+// version number. Local integrity catches the accident and the drift (an
+// agent "fixing" a lane file, a half-applied upgrade); the remote comparison
+// catches the lie. Neither claim is stretched to cover the other's job.
+//
+// The lock is deliberately NOT a .mjs file, so it is not part of the region it
+// describes — a manifest inside its own manifest could never settle.
+//
+// SINGLE SOURCE OF TRUTH: packages/harness/src/lib/harness-lock.mjs in the
+// create-cmp repo — edit there, then run `node scripts/sync-harness.mjs`.
+
+import fs from "node:fs";
+import path from "node:path";
+import { hashHarnessRegion, compareHarnessRegion } from "./harness-region.mjs";
+
+export const LOCK_PATH = "qa/harness.lock.json";
+export const LOCK_SCHEMA = "cmp-harness-lock/1";
+
+/**
+ * Read the lock, or null when it is absent or unparsable. An unreadable lock
+ * is not distinguished from a missing one on purpose: both mean "this tree
+ * cannot tell me what lane it carries", and both get the same honest verdict
+ * from checkHarnessIntegrity — unknown, never intact.
+ * @param {string} root project root
+ * @returns {object|null}
+ */
+export function readHarnessLock(root) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(root, LOCK_PATH), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Hash the tree's region and write the lock describing it.
+ * Called at stamp time and after an upgrade replaces the region — never by
+ * the lane itself, which must only ever READ the lock. A lane that rewrote
+ * its own manifest could not fail the integrity check it exists to run.
+ * @param {string} root project root
+ * @param {{name?: string, version: string}} harness identity to record
+ * @returns {{sha256: string, fileCount: number}}
+ */
+export function writeHarnessLock(root, { name = "create-cmp-harness", version }) {
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error("writeHarnessLock: a harness version is required");
+  }
+  const region = hashHarnessRegion(root);
+  const lock = {
+    schema: LOCK_SCHEMA,
+    name,
+    version,
+    sha256: region.sha256,
+    fileCount: region.fileCount,
+    files: region.files,
+  };
+  const abs = path.join(root, LOCK_PATH);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, `${JSON.stringify(lock, null, 2)}\n`);
+  return { sha256: region.sha256, fileCount: region.fileCount };
+}
+
+/**
+ * Compare the tree's region against its lock.
+ *
+ * @param {string} root project root
+ * @returns {{status: "intact"|"modified"|"unlocked", name: string|null,
+ *            version: string|null, sha256: string, recordedSha256: string|null,
+ *            modified: string[], missing: string[], extra: string[],
+ *            fileCount: number}}
+ *   status "unlocked" means no readable lock — an app stamped before locks
+ *   existed, or one whose lock was deleted. Reported as its own state rather
+ *   than folded into "modified": nothing is known to be wrong, but nothing is
+ *   proven either, and a gate that cannot tell those apart teaches people to
+ *   ignore it.
+ */
+export function checkHarnessIntegrity(root) {
+  const lock = readHarnessLock(root);
+  const region = hashHarnessRegion(root);
+
+  if (!lock || typeof lock.files !== "object" || lock.files === null) {
+    return {
+      status: "unlocked",
+      name: lock?.name ?? null,
+      version: typeof lock?.version === "string" ? lock.version : null,
+      sha256: region.sha256,
+      recordedSha256: typeof lock?.sha256 === "string" ? lock.sha256 : null,
+      modified: [],
+      missing: [],
+      extra: [],
+      fileCount: region.fileCount,
+    };
+  }
+
+  const cmp = compareHarnessRegion(root, lock);
+  return {
+    status: cmp.intact ? "intact" : "modified",
+    name: typeof lock.name === "string" ? lock.name : null,
+    version: typeof lock.version === "string" ? lock.version : null,
+    sha256: cmp.sha256,
+    recordedSha256: typeof lock.sha256 === "string" ? lock.sha256 : null,
+    modified: cmp.modified,
+    missing: cmp.missing,
+    extra: cmp.extra,
+    fileCount: region.fileCount,
+  };
+}
+
+/**
+ * One-line human summary of an integrity result — shared by the lane step and
+ * the upgrade command so both describe the same state the same way.
+ * @param {ReturnType<typeof checkHarnessIntegrity>} r
+ * @returns {string}
+ */
+export function describeIntegrity(r) {
+  if (r.status === "intact") {
+    return `${r.name ?? "harness"} ${r.version ?? "?"} — ${r.fileCount} files verified`;
+  }
+  if (r.status === "unlocked") {
+    return `no ${LOCK_PATH} — this app's lane version is unrecorded`;
+  }
+  const parts = [];
+  if (r.modified.length) parts.push(`${r.modified.length} modified`);
+  if (r.missing.length) parts.push(`${r.missing.length} missing`);
+  if (r.extra.length) parts.push(`${r.extra.length} unrecorded`);
+  return `${r.name ?? "harness"} ${r.version ?? "?"} — ${parts.join(", ")}`;
+}