@everystack/cli 0.4.77 → 0.4.78

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@everystack/cli` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.78] - 2026-09-07
+
+### Fixed
+
+- the adoption report describes the plan it ships with
+- the unreadable-tree refusal names the refs that carry each tree and leads with the fix the ledger supports
+- a squashed successor proves the fast-forward; the attest resolves through git; the plan predicts the apply; an empty edge names what carries the hash difference
+- closing-gate round 1 — app-only squash, squash proof recorded and announced, bounded runbook, scrubbed errors, git timeouts
+- closing-gate round 2 — doc matches the shipped squash rule, the round-1 fixes are pinned, every git call is bounded, the squash guard refuses when git cannot answer
+
 ## [0.4.77] - 2026-09-07
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/cli",
-  "version": "0.4.77",
+  "version": "0.4.78",
   "description": "CLI and OTA updates for Expo apps on everystack",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/cli/authz-adoption-class.ts

@@ -30,7 +30,8 @@
 
 import { matchPolicies, roleSetEqual } from './authz-identity';
 import { governedRoleSet } from './authz-reconcile';
-import { effectivePolicyCheck, holdsPrivilege, isPolicyDead, policyCommands } from './authz-contract';
+import { tablePoliciesEquivalent } from './authz-canonical';
+import { effectivePolicyCheck, holdsPrivilegeEffective, isPolicyDead, policyCommands } from './authz-contract';
 import type { AuthzContract, PolicyContract, TableContract } from './authz-contract';
 
 export type AdoptionClass = 'convention' | 'capability' | 'narrowing' | 'dead' | 'unclassified';
@@ -78,24 +79,66 @@ function covers(outer: readonly string[], inner: readonly string[]): boolean {
   return inner.every((r) => o.has(r));
 }
 
-/** Same authorization on every axis EXCEPT which roles it names — the role-split test. */
-function sameRule(a: PolicyContract, b: PolicyContract): boolean {
-  return a.command === b.command
-    && a.permissive === b.permissive
-    && (a.using ?? '') === (b.using ?? '')
-    && (effectivePolicyCheck(a) ?? '') === (effectivePolicyCheck(b) ?? '');
+/**
+ * The predicate slots ONE command enforces — the same fan the canonical form uses. SELECT and
+ * DELETE have no WITH CHECK; INSERT has no USING and its check falls back to USING when the
+ * source is a `FOR ALL` with no explicit check (the server's own defaulting rule); UPDATE and
+ * ALL carry both. Comparing policies through this is what lets a declared INSERT be measured
+ * against the INSERT arm of a live ALL instead of against a USING the INSERT never had.
+ */
+function armOf(p: PolicyContract, command: string): { using: string; check: string } {
+  const using = command === 'INSERT' ? '' : (p.using ?? '');
+  // ONE definition of the server's WITH CHECK defaulting rule — effectivePolicyCheck, shared with
+  // the matcher, the reconciler and the retained v10 canon.
+  const check = command === 'SELECT' || command === 'DELETE' ? '' : (effectivePolicyCheck(p) ?? '');
+  return { using, check };
 }
 
 /**
- * A policy's predicate, collapsed to one line for the report.
+ * Same authorization on every command the replacement governs, roles aside — the role-split and
+ * per-command tests. Arm for arm, so a live `FOR ALL USING (x)` is the same rule as a declared
+ * `INSERT WITH CHECK (x)` on INSERT. Whether the replacement covers EVERY live command is a
+ * separate question (`aliveCommands`), answered by the caller.
+ */
+function sameRule(r: PolicyContract, live: PolicyContract): boolean {
+  if (r.permissive !== live.permissive) return false;
+  const liveCommands = commandsOf(live);
+  return commandsOf(r).every((cmd) => {
+    if (!liveCommands.includes(cmd)) return false;
+    const a = armOf(r, cmd);
+    const b = armOf(live, cmd);
+    return a.using === b.using && a.check === b.check;
+  });
+}
+
+/** The commands a live policy actually governs — the arms some role it names holds the grant for. */
+function aliveCommands(t: TableContract, p: PolicyContract): string[] {
+  const roles = p.roles.includes('public') || p.roles.includes('PUBLIC')
+    ? Object.keys(t.effectivePrivileges ?? t.grants)
+    : p.roles;
+  return commandsOf(p).filter((cmd) => roles.some((r) => holdsPrivilegeEffective(t, r, cmd)));
+}
+
+/**
+ * A policy's predicate, collapsed to one line for the report, in the slot its command enforces:
+ * an INSERT is shown by its WITH CHECK (it has no USING — rendering one printed
+ * "true (unfiltered)" for every INSERT policy, which is what the consumer read as an unfiltered
+ * rule); UPDATE and ALL show both halves when they differ; SELECT and DELETE show USING.
  *
  * Live predicates arrive from `pg_get_expr` with real newlines and indentation (an EXISTS
  * subquery spans several lines), and the adoption report is one line per statement. Collapsing
  * keeps the rule READABLE in place rather than referring the operator elsewhere to find it.
  */
 function pred(p: PolicyContract): string {
-  const using = (p.using ?? 'true').replace(/\s+/g, ' ').trim();
-  return using === 'true' ? 'true (unfiltered)' : using;
+  const one = (s: string | null | undefined): string => {
+    const t = (s ?? 'true').replace(/\s+/g, ' ').trim();
+    return t === 'true' ? 'true (unfiltered)' : t;
+  };
+  if (p.command === 'INSERT') return `WITH CHECK ${one(p.check)}`;
+  if (p.command === 'SELECT' || p.command === 'DELETE') return `USING ${one(p.using)}`;
+  const using = one(p.using);
+  const check = one(p.check ?? p.using);
+  return check === using ? `USING ${using}` : `USING ${using} WITH CHECK ${check}`;
 }
 
 // `commandsOf` and the dead-policy test live in authz-contract — ONE definition, shared with
@@ -106,6 +149,16 @@ const isDead = isPolicyDead;
 /** Classify the policy statements one table would emit. */
 function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedStatement[], governed: ReadonlySet<string>): void {
   const table = d.table;
+
+  // The reconciler's own gate, mirrored (authz-reconcile reconcilePolicies, Condition B): two
+  // tables that are the SAME authorization under the canonical fan emit nothing, so there is
+  // nothing to classify. A live `FOR ALL` whose alive arms the declared per-command split covers
+  // is the shape that escaped — the per-policy matcher below cannot see it (a live ALL is never
+  // the same policy as a declared INSERT), so this classifier counted four narrowings for a plan
+  // that carried none. Gating on the same predicate the emitter gates on is the only way the
+  // two can never disagree.
+  if (tablePoliciesEquivalent(d, l, governed)) return;
+
   const m = matchPolicies(d.policies, l.policies);
   const liveByName = new Map(l.policies.map((p) => [p.name, p]));
 
@@ -144,12 +197,18 @@ function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedSta
 
     const replacementRoles = [...new Set(replacements.flatMap((r) => r.roles))];
 
+    // The COMMAND axis: which of the live policy's alive arms no replacement governs at all. A
+    // live ALL replaced by an INSERT-only declaration loses SELECT/UPDATE/DELETE — a narrowing
+    // no role or predicate comparison can see. Dead arms are not access, so they are not lost.
+    const liveAlive = aliveCommands(l, live);
+    const uncovered = liveAlive.filter((cmd) => !replacements.some((r) => commandsOf(r).includes(cmd)));
+
     // The role split: one live policy covering several roles, against the per-role policies the
     // compiler emits. Same predicate, and the declared roles union to EXACTLY the live role set,
     // so the two authorize identically for every session. Pure spelling — ours to fix (A5).
     // Note this is recognized here for LABELING before the matcher can act on it; the two must
     // agree once A5 lands, which is what the emitter-parity test pins.
-    if (roleSetEqual(live.roles, replacementRoles) && replacements.every((r) => sameRule(r, live))) {
+    if (roleSetEqual(live.roles, replacementRoles) && !uncovered.length && replacements.every((r) => sameRule(r, live))) {
       out.push({ table, subject: name, cls: 'convention', why: `live covers ${live.roles.join(' + ')} in one policy; we split it per role with the same predicate` });
       for (const r of replacements) {
         if (consumed.has(r.name)) continue;
@@ -181,21 +240,48 @@ function classifyPolicies(d: TableContract, l: TableContract, out: ClassifiedSta
     // we cannot prove is identical is reported as a reduction, and BOTH predicates are carried
     // so the operator reads the rule rather than the label.
     const sameRoleReplacements = replacements.filter((r) => r.roles.some((role) => live.roles.includes(role)));
-    if (sameRoleReplacements.length && !sameRoleReplacements.some((r) => sameRule(r, live))) {
-      const shared = [...new Set(sameRoleReplacements.flatMap((r) => r.roles.filter((role) => live.roles.includes(role))))];
+    const shared = [...new Set(sameRoleReplacements.flatMap((r) => r.roles.filter((role) => live.roles.includes(role))))];
+
+    // Same roles, same rule on every command the replacements govern, but some live command is
+    // left with no policy at all — the command-axis narrowing.
+    if (sameRoleReplacements.length && uncovered.length && sameRoleReplacements.every((r) => sameRule(r, live))) {
+      const covered = liveAlive.filter((cmd) => !uncovered.includes(cmd));
+      out.push({
+        table,
+        subject: name,
+        cls: 'narrowing',
+        why:
+          `live governs ${liveAlive.join('/')} for ${shared.join(', ')} ${pred(live)}; the declared replacement `
+          + `${sameRoleReplacements.map((r) => `"${r.name}"`).join(', ')} keeps the same rule but governs only `
+          + `${covered.join('/')} — ${uncovered.join('/')} loses its policy`,
+      });
+      for (const r of sameRoleReplacements) {
+        if (consumed.has(r.name)) continue;
+        consumed.add(r.name);
+        out.push({ table, subject: r.name, cls: 'narrowing', why: `the narrower replacement for "${name}"` });
+      }
+      continue;
+    }
+
+    if (sameRoleReplacements.length && !sameRoleReplacements.every((r) => sameRule(r, live))) {
+      const differing = sameRoleReplacements.filter((r) => !sameRule(r, live));
       out.push({
         table,
         subject: name,
         cls: 'narrowing',
         why:
-          `live applies to ${shared.join(', ')} USING ${pred(live)}; the declared replacement `
-          + `${sameRoleReplacements.map((r) => `"${r.name}"`).join(', ')} keeps the same role(s) but states `
-          + `${sameRoleReplacements.map((r) => pred(r)).join(' / ')} — a different rule, not a different spelling`,
+          `live applies to ${shared.join(', ')} ${pred(live)}; the declared replacement `
+          + `${differing.map((r) => `"${r.name}"`).join(', ')} keeps the same role(s) but states `
+          + `${differing.map((r) => pred(r)).join(' / ')} — a different rule, not a different spelling`,
       });
       for (const r of sameRoleReplacements) {
         if (consumed.has(r.name)) continue;
         consumed.add(r.name);
-        out.push({ table, subject: r.name, cls: 'narrowing', why: `the differently-predicated replacement for "${name}"` });
+        // A replacement that DOES match its live arm exists only because the differing one forced
+        // the live policy to be replaced — our spelling, emitted for a real difference next to it.
+        out.push(sameRule(r, live)
+          ? { table, subject: r.name, cls: 'convention', why: `the per-command half of "${name}", same rule; emitted because "${differing[0].name}" differs` }
+          : { table, subject: r.name, cls: 'narrowing', why: `the differently-predicated replacement for "${name}"` });
       }
       continue;
     }
@@ -298,17 +384,21 @@ export function classifyAdoption(
  * inline is a wall nobody reads, and they are each described by their class.
  */
 export function renderAdoptionReport(counts: AdoptionCounts, statements: readonly ClassifiedStatement[] = []): string[] {
+  const row = (label: string, n: number, why: string): string => `  ${label.padEnd(18)} ${n}  — ${why}`;
   const lines = [
-    `  convention   ${counts.convention}  — our spelling, not their schema (this must reach 0)`,
-    `  capability   ${counts.capability}  — the model cannot express what is live`,
-    `  narrowing    ${counts.narrowing}  — real access reduction, approve before applying`,
-    `  dead         ${counts.dead}  — policed but never granted`,
+    row('convention', counts.convention, 'our spelling, not their schema (this must reach 0)'),
+    row('capability', counts.capability, 'the model cannot express what is live'),
+    row('narrowing (access)', counts.narrowing, 'real access reduction, approve before applying'),
+    row('dead', counts.dead, 'policed but never granted'),
   ];
   if (counts.unclassified) {
-    lines.push(`  unclassified ${counts.unclassified}  — NOT described; read these before applying:`);
+    lines.push(row('unclassified', counts.unclassified, 'NOT described; read these before applying:'));
     for (const s of statements.filter((s) => s.cls === 'unclassified')) {
       lines.push(`    ${s.table} "${s.subject}" — ${s.why}`);
     }
   }
+  // The name collision from the module header, said where the operator can see it: the plan
+  // file's `narrowings` is the DESTRUCTIVE axis (lossy type changes) and is counted elsewhere.
+  lines.push('  (access counts above are policies and grants; the plan file\'s `narrowings` counts lossy type changes — the destructive axis, reported separately)');
   return lines;
 }

package/src/cli/commands/db-apply.ts

@@ -40,6 +40,7 @@ import {
   attestationNote,
   proveLineageLost,
   realLineageProbe,
+  resolveAttestation,
   type DescentLedgerRow,
   type LiveState,
   type ProveVerdict,
@@ -118,7 +119,12 @@ export function reportApplyResult(result: ApplyPlanResult, plan: EdgePlan): void
 export function describeDescentVerdict(verdict: ProveVerdict, opts: { destructive?: boolean } = {}): { level: 'info' | 'warn'; text: string } | null {
   switch (verdict.status) {
     case 'proven':
-      return { level: 'info', text: `descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.` };
+      // A squash proof names BOTH commits: the carrier that is an ancestor of HEAD, and the
+      // deploying commit that is not — announcing the carrier alone as "an ancestor" hid that
+      // the proof rests on tree identity (closing-gate review, 2026-09-07).
+      return verdict.via === 'squash' && verdict.witness
+        ? { level: 'info', text: `descent: proven via squash — ${verdict.commit.slice(0, 12)} (an ancestor of HEAD) carries the models tree of the deploying commit ${verdict.witness.slice(0, 12)}, which HEAD does not descend from; recorded in schema_log.` }
+        : { level: 'info', text: `descent: proven via ${verdict.via} — ${verdict.commit.slice(0, 12)} is an ancestor of HEAD, fast-forward.` };
     case 'fresh-target':
       return { level: 'info', text: 'descent: fresh target (no tables) — nothing to protect, bootstrapping.' };
     case 'no-git':
@@ -166,15 +172,18 @@ export async function proveDescentForApply(input: {
    *  Production passes nothing and rides the real loader. */
   descent?: Pick<ProveDescentOptions, 'loader' | 'materializeRoot'>;
 }): Promise<{ descentVerdict: { ok: true } | { ok: false; reason: string }; descentAttested?: string }> {
+  const cwd = input.cwd ?? process.cwd();
   const verdict = await proveDescent(input.modelsPath, input.live, input.ledger, {
     ...(input.cwd ? { cwd: input.cwd } : {}),
     ...(input.descent ?? {}),
   });
   reportDescentVerdict(verdict, { destructive: input.destructive });
+  // The attestation is resolved THROUGH git (a prefix, tag or HEAD~n → the full sha) before it is
+  // compared; a value git cannot resolve passes through and the prefix compare decides.
   const decision = decideDescentApply(verdict, {
-    ...(input.attestation ? { attestation: input.attestation } : {}),
+    ...(input.attestation ? { attestation: resolveAttestation(input.attestation, cwd) } : {}),
     destructive: input.destructive,
-    proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(input.cwd ?? process.cwd())),
+    proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(cwd)),
   });
   if (!decision.ok) return { descentVerdict: { ok: false, reason: decision.reason } };
   if (decision.attested) {

package/src/cli/commands/db-plan.ts

@@ -50,7 +50,9 @@ import { introspectSchema, type SchemaSnapshot } from '../schema-introspect';
 import { readStageStateTwice } from '../stage-read-consistency';
 import { FUNCTIONS_SQL, contractFunctionRow } from '../security-catalog';
 import { mintEdgePlan, planHash, buildPlanSummary } from '../edge-plan';
-import { proveDescent, describeDriftOrigin, type ProveVerdict } from '../git-descent';
+import { proveDescent, describeDriftOrigin, proveLineageLost, realLineageProbe, type ProveVerdict, type LineageProof } from '../git-descent';
+import { fingerprintLive, divergentSurfaces } from '../schema-fingerprint';
+import { predictLiveState } from '../edge-plan';
 import { readDescentLedger } from '../apply-execute';
 import { planBackfills, readBackfillLog } from '../backfill';
 import { readSqlDirIfPresent } from './db-sync';
@@ -77,9 +79,42 @@ import { step, success, fail, info, warn, reserveStdoutForData } from '../output
  * exhaustive: a new verdict fails to compile here instead of minting a plan with no warning and
  * refusing at apply with no hint of why.
  */
-export function describePlanDescent(verdict: ProveVerdict): string[] {
+export function describePlanDescent(
+  verdict: ProveVerdict,
+  opts: { proveLineage?: (sha: string) => LineageProof } = {},
+): string[] {
+  // The plan predicts the apply. For a verdict that names a declaring commit, run the SAME lineage
+  // proof db:apply runs and say what it will do with it: a commit reachable from a ref → rebase
+  // onto that ref; a commit reachable from NO ref → the exact attestation apply will honour. The
+  // two surfaces disagreed once (consumer cutover, cli 0.4.77): plan said "will refuse — rebase"
+  // on a commit no ref held, and apply honoured the attest. Phase A tests OBJECT presence, so a
+  // ref-less commit still reads as a revert until the lineage proof is asked.
+  const applyWillDo = (commit: string): string => {
+    const proof = opts.proveLineage?.(commit);
+    if (!proof) return 'db:apply from this checkout will refuse this plan — rebase first, then re-mint.';
+    if (proof.proven) {
+      return `db:apply from this checkout will refuse this plan without an attestation; commit ${commit} is reachable from no ref ` +
+        `(${proof.subcase}), so it will honour --attest-lineage-lost ${commit} — or fetch the branch that had it, rebase, and re-mint.`;
+    }
+    if (proof.kind === 'reachable' && proof.ref && proof.ref !== 'HEAD') {
+      // `ref` is a full ref name, or a REMOTE name when the commit was found in a remote branch's
+      // ancestry (the probe sees advertised tips, not their branch names) — you cannot rebase onto
+      // a remote, so that case says fetch first. `HEAD` cannot reach here from a revert (the commit
+      // is not an ancestor of HEAD by construction); if it ever did, the generic reason is safer
+      // than "git fetch HEAD".
+      return proof.ref.startsWith('refs/')
+        ? `db:apply from this checkout will refuse this plan — that commit is still on ${proof.ref}; rebase onto it, then re-mint.`
+        : `db:apply from this checkout will refuse this plan — that commit is still on remote '${proof.ref}'; fetch it (git fetch ${proof.ref}), rebase onto the branch that has it, then re-mint.`;
+    }
+    return `db:apply from this checkout will refuse this plan — ${proof.reason}`;
+  };
   switch (verdict.status) {
     case 'proven':
+      // A squash proof is the one PROVEN shape whose deploying commit is not in the operator's
+      // history — say so where a human reads the plan, as the apply record will.
+      return verdict.via === 'squash' && verdict.witness
+        ? [`descent: fast-forward proven via a squashed successor — ${verdict.commit.slice(0, 12)} (an ancestor of HEAD) carries the models tree of the deploying commit ${verdict.witness.slice(0, 12)}, which HEAD does not descend from. db:apply will record that.`]
+        : [];
     case 'fresh-target':
     case 'no-git':
       return [];
@@ -94,10 +129,19 @@ export function describePlanDescent(verdict: ProveVerdict): string[] {
         'db:apply from this checkout will refuse this plan — fetch and merge or rebase onto that commit, then re-mint.',
       ];
     case 'revert':
-      return [`descent: ${verdict.reason}`, 'db:apply from this checkout will refuse this plan — rebase first, then re-mint.'];
-    case 'unknown-commit':
-      // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit.
-      return [`descent: ${verdict.reason}`, 'db:apply from this checkout will refuse this plan until you fetch that commit — fetch, then re-mint.'];
+      return [`descent: ${verdict.reason}`, applyWillDo(verdict.commit)];
+    case 'unknown-commit': {
+      // NOT "rebase first" — the checkout is fine, it is just missing the deploying commit. Unless
+      // the lineage proof says the commit is gone from every remote too: then apply will honour the
+      // attestation, and fetching cannot help.
+      const proof = opts.proveLineage?.(verdict.commit);
+      return [
+        `descent: ${verdict.reason}`,
+        proof?.proven
+          ? applyWillDo(verdict.commit)
+          : 'db:apply from this checkout will refuse this plan until you fetch that commit — fetch, then re-mint.',
+      ];
+    }
     case 'unverifiable':
       // NOT "rebase first" — nothing is wrong with the checkout or the database. The search could
       // not finish (an unreadable tree, or a clone that is not full and current).
@@ -293,7 +337,17 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       await fs.writeFile(out, body, 'utf8');
     }
 
-    for (const line of buildPlanSummary(plan)) info(line);
+    // An EMPTY edge between two different fingerprints reads as a contradiction. `from` is the
+    // target's full fingerprint (the concurrency lock at apply); `to` is the declared endpoint
+    // through the models' governed set. They differ by exactly what the plan leaves alone — name
+    // it, computed at mint from the two canonical forms, never stored on the plan.
+    const carriedBy = plan.statements.length === 0 && plan.fromFingerprint !== plan.toFingerprint
+      ? divergentSurfaces(
+        predictLiveState(models, snapshot, contract, { governedRoles: governedRoleSet(declaredAuthz, declaredGovernedRoles) }).canonical,
+        fingerprintLive(snapshot, contract).canonical,
+      )
+      : undefined;
+    for (const line of buildPlanSummary(plan, carriedBy ? { carriedBy } : {})) info(line);
     info(`plan_ref: ${planHash(plan).slice(0, 12)}`);
 
     // WHY does each authorization statement exist? — the same report db:generate prints,
@@ -331,7 +385,9 @@ export async function dbPlanCommand(flags: Record<string, string>): Promise<void
       // A switch, not an `if (revert || drift)`. That form silently ignored every verdict it
       // did not name, so a new one would mint a plan with no warning and then be refused at
       // apply time with no hint of why. Exhaustive here means a new verdict cannot be forgotten.
-      for (const line of describePlanDescent(verdict)) warn(line);
+      // A PROVEN verdict is information, as it is on the apply surface; everything else is a warning.
+      const say = verdict.status === 'proven' ? info : warn;
+      for (const line of describePlanDescent(verdict, { proveLineage: (sha) => proveLineageLost(sha, realLineageProbe(process.cwd())) })) say(line);
     }
 
     // Visibility, never automation (brick 8): the review surface names the

package/src/cli/edge-plan.ts

@@ -409,12 +409,27 @@ export function checkPlanPrecondition(plan: EdgePlan, liveFingerprint: string):
 
 const short = (hash: string): string => hash.slice(0, 12);
 
-/** Human summary of a plan — the review surface. */
-export function buildPlanSummary(plan: EdgePlan): string[] {
+/**
+ * Human summary of a plan — the review surface.
+ *
+ * `carriedBy` names what accounts for an EMPTY edge between two DIFFERENT fingerprints: `from`
+ * is the target's full fingerprint (the concurrency lock), `to` the declared endpoint through the
+ * governed set, and they differ by exactly the live objects the plan leaves alone — an ungoverned
+ * role's grants, a policy the vocabulary cannot declare. Without the name the line "the target
+ * already declares this state" under two different hashes reads as a contradiction (consumer
+ * cutover, cli 0.4.77). The caller computes it at mint from the canonical forms; it is never
+ * stored on the plan.
+ */
+export function buildPlanSummary(plan: EdgePlan, opts: { carriedBy?: string[] } = {}): string[] {
   const lines: string[] = [];
   lines.push(`edge: ${short(plan.fromFingerprint)} → ${short(plan.toFingerprint)}`);
   if (plan.statements.length === 0) {
-    lines.push('empty — the target already declares this state');
+    if (plan.fromFingerprint === plan.toFingerprint) {
+      lines.push('empty — the target already declares this state');
+    } else {
+      lines.push('empty — no statement to emit. The fingerprints differ by what the plan leaves alone: `from` is the target\'s full fingerprint (the concurrency lock), `to` the declared endpoint through the governed set'
+        + (opts.carriedBy?.length ? `; carried by: ${opts.carriedBy.join('; ')}` : '') + '.');
+    }
     return lines;
   }
   lines.push(`${plan.executable} executable statement(s), ${plan.notices} notice(s)`);

package/src/cli/git-descent.ts

@@ -85,9 +85,13 @@ export interface ModelTreeCandidate {
 
 const short = (ref: string): string => ref.slice(0, 12);
 
+/** Every git command this module runs is bounded: in a partial clone even `cat-file` and
+ *  `merge-base` can fetch lazily over the network, and a hang must become a null (refuse-closed). */
+const GIT_TIMEOUT_MS = 60_000;
+
 function git(args: string[], cwd: string): string | null {
   try {
-    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+    return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).toString();
   } catch {
     return null;
   }
@@ -100,6 +104,44 @@ const defaultLoader: ModelsLoader = async (barrel) => {
   return models;
 };
 
+/**
+ * The SQUASHED SUCCESSOR of a witness commit HEAD does not descend from: an ancestor of HEAD that
+ * carries the witness's models tree UNCHANGED (same tree oid) and is not itself an ancestor of
+ * the witness. Deploy from a PR branch, squash-merge, deploy the next stage — the ledger names the
+ * PR commit, main carries its tree under a new sha, and every line of the declaring commit is
+ * inside HEAD. Refusing that as a revert is false (consumer cutover, cli 0.4.77, 2026-09-07).
+ *
+ * The second clause is the whole safety. In an S→T→S episode the pre-episode ancestor carries S's
+ * tree too — byte-identical — and a checkout branched there must still be refused: the witness
+ * (the re-declaration of S) DESCENDS from that carrier, so the carrier is the state the episode
+ * started from, not a successor. A squash commit is never an ancestor of the branch it squashed.
+ * Tree identity is exact and cheap (`rev-parse <sha>:<dir>`, no materialization); a state-level
+ * recompile is deliberately NOT used here, because it cannot tell those two shapes apart.
+ *
+ * One carrier that IS an ancestor of the witness still counts: the one with NO models change
+ * between it and the witness. That is the app-only PR — the deploy changed no models, the
+ * witness's tree is the base tree, and `rev-list --full-history -- <dir>` lists only the base as a
+ * carrier (closing-gate review, 2026-09-07). The pre-episode carrier never qualifies: the T
+ * episode sits between it and the witness, so `rev-list carrier..witness -- <dir>` is non-empty.
+ */
+function squashedSuccessor(witness: string, head: string, modelsDir: string, repoRoot: string): string | null {
+  const spec = modelsDir === '.' ? `${witness}^{tree}` : `${witness}:${modelsDir}`;
+  const tree = git(['rev-parse', '--verify', '--quiet', spec], repoRoot)?.trim();
+  if (!tree) return null;
+  const carriers = enumerateModelTrees(modelsDir, repoRoot, { ancestorsOf: head }).find((c) => c.tree === tree)?.commits ?? [];
+  const modelsUnchangedBetween = (carrier: string): boolean => {
+    const changes = git(['rev-list', `${carrier}..${witness}`, '--', modelsDir], repoRoot);
+    return changes !== null && changes.trim() === '';
+  };
+  // Refuse-closed on BOTH git questions: an ancestry git could not answer is not "not an
+  // ancestor" (that would accept the carrier), and a rev-list that failed is not "no changes".
+  return carriers.find((c) => {
+    const anc = ancestry(c, witness, repoRoot);
+    if (anc === null) return false;
+    return !anc || modelsUnchangedBetween(c);
+  }) ?? null;
+}
+
 /**
  * Every historical state of the models directory across ALL refs, newest
  * first, grouped by tree oid. `--full-history` keeps every !TREESAME commit
@@ -132,6 +174,7 @@ export function enumerateModelTrees(
       cwd,
       input: specs.join('\n') + '\n',
       stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: GIT_TIMEOUT_MS,
     }).toString();
   } catch {
     return [];
@@ -195,8 +238,9 @@ export function materializeTree(tree: string, dest: string, cwd: string): void {
 type TreeEval =
   | { kind: 'declares' }
   | { kind: 'no' }
-  | { kind: 'compile-failed'; detail: string }
-  | { kind: 'unevaluated'; detail: string };
+  /** `detail` is the one-line record (`<tree> (at <commit>): <error>`); `error` is the bare cause. */
+  | { kind: 'compile-failed'; detail: string; error: string }
+  | { kind: 'unevaluated'; detail: string; error: string };
 
 interface EvalContext {
   repoRoot: string;
@@ -225,7 +269,8 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
       fs.rmSync(dest, { recursive: true, force: true });
       ctx.materialize(candidate.tree, dest, ctx.repoRoot);
     } catch (err: any) {
-      return { kind: 'unevaluated', detail: `${where}: could not extract — ${firstLine(err.message)}` };
+      const error = `could not extract — ${firstLine(err.message)}`;
+      return { kind: 'unevaluated', detail: `${where}: ${error}`, error };
     }
   }
 
@@ -259,8 +304,100 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
     }
     return declares ? { kind: 'declares' } : { kind: 'no' };
   } catch (err: any) {
-    return { kind: 'compile-failed', detail: `${where}: ${firstLine(err.message)}` };
+    const error = firstLine(err.message);
+    return { kind: 'compile-failed', detail: `${where}: ${error}`, error };
+  }
+}
+
+/** One tree the walk could not read, with where it sits in history — the refusal names it. */
+interface UnreadableTree {
+  candidate: ModelTreeCandidate;
+  /** Carried by a commit HEAD descends from — no ref prune removes it. */
+  ancestor: boolean;
+  error: string;
+}
+
+/** The git verb that removes one ref, or null for a ref shape we do not prescribe deleting. */
+export function pruneCommand(ref: string): string | null {
+  const head = ref.match(/^refs\/heads\/(.+)$/);
+  if (head) return `git branch -D ${head[1]}`;
+  const remote = ref.match(/^refs\/remotes\/([^/]+)\/(.+)$/);
+  if (remote) return `git push ${remote[1]} --delete ${remote[2]}`;
+  const tag = ref.match(/^refs\/tags\/(.+)$/);
+  if (tag) return `git tag -d ${tag[1]}`;
+  return null;
+}
+
+/**
+ * The unreadable-tree refusal, built from what the walk KNOWS: each tree, the refs that carry it,
+ * whether HEAD descends from it, and what the target's ledger says about who deployed what.
+ *
+ * Consumer cutover, cli 0.4.77 (2026-09-07): four August trees carried only by one backup branch
+ * on origin refused a production apply, and the message led with "upgrade/pin the CLI that last
+ * deployed this state" — on a database no CLI had ever deployed (schema_log was empty). The
+ * operator reconstructed the carrying ref with `git rev-list --all -- db/models` and a per-tree
+ * grep. Every fact in that reconstruction was already in this function's hands.
+ *
+ * The verdict does not change here; only the account of it. A tree we cannot read may still
+ * describe live, so the walk stays refuse-closed; the ledger is a memoir and never decides
+ * (decision 7). What the ledger DOES decide is which fix comes first: with no recorded apply,
+ * no CLI deployed these trees and "pin the CLI" is false, so bundle + prune leads; with one, pin
+ * the CLI only when the recorded commit is itself among the unreadable trees.
+ */
+function unreadableRunbook(
+  unreadable: readonly UnreadableTree[],
+  lastApplied: DescentLedgerRow | undefined,
+  probe: GitLineageProbe,
+): string {
+  // Bounded on both axes, because this reason is RECORDED in schema_log and each ref lookup is a
+  // full ref walk: at most MAX_TREES trees are named, and a tree's refs are the union over its
+  // first MAX_COMMITS carrying commits (a tree is often carried by several commits on several
+  // branches — naming one commit's refs under-named the prune; closing-gate review, 2026-09-07).
+  const MAX_TREES = 10;
+  const MAX_COMMITS = 5;
+  const listed = unreadable.slice(0, MAX_TREES);
+  const refsOf = new Map<string, string[]>();
+  for (const u of listed) {
+    const refs = new Set<string>();
+    for (const commit of u.candidate.commits.slice(0, MAX_COMMITS)) {
+      for (const ref of probe.refsContaining(commit)) if (ref !== 'refs/stash') refs.add(ref);
+    }
+    refsOf.set(u.candidate.tree, [...refs].sort());
+  }
+  const lines = listed.map((u) => {
+    const refs = refsOf.get(u.candidate.tree)!;
+    const carried = refs.length === 0
+      ? 'carried by no ref'
+      : `carried by ${refs.slice(0, 3).join(', ')}${refs.length > 3 ? ` and ${refs.length - 3} more` : ''}`;
+    const where = u.ancestor ? "on your checkout's own history" : 'not an ancestor of your checkout';
+    return `  ${short(u.candidate.tree)} at ${short(u.candidate.commits[0])} — ${carried} (${where}) — ${scrubPaths(u.error)}`;
+  });
+  if (unreadable.length > listed.length) {
+    lines.push(`  … and ${unreadable.length - listed.length} more unreadable tree(s) not listed — their refs are not in the prune list below; re-run after pruning to see them`);
+  }
+
+  const prunable = listed.filter((u) => !u.ancestor);
+  const ancestors = unreadable.filter((u) => u.ancestor);
+  const pruneRefs = [...new Set(prunable.flatMap((u) => refsOf.get(u.candidate.tree)!))];
+  const pruneCmds = pruneRefs.map(pruneCommand).filter((c): c is string => c !== null);
+  const prune = pruneRefs.length === 0
+    ? ''
+    : `Keep them if you want (git bundle create unreadable-trees.bundle ${pruneRefs.join(' ')}), then prune: ${pruneCmds.join('; ')}; then re-run.`;
+  const rewrite = ancestors.length === 0
+    ? ''
+    : `${ancestors.length === unreadable.length ? 'These trees are' : `${ancestors.length} of them ${ancestors.length === 1 ? 'is' : 'are'}`} on your checkout's own history, which no ref prune removes; the walk needs every ancestor tree readable. Rewriting that history is the git-native remedy — keep it first (git bundle create everything.bundle --all).`;
+
+  let lead: string;
+  if (!lastApplied) {
+    lead = 'No everystack apply is recorded on this target, so no CLI deployed these trees.';
+  } else {
+    const at = lastApplied.gitRef ? `at ${short(lastApplied.gitRef)} ` : '';
+    const among = lastApplied.gitRef !== null && unreadable.some((u) => u.candidate.commits.includes(lastApplied.gitRef!));
+    lead = `everystack last applied here ${at}on ${shortDate(lastApplied.appliedAt)}.`
+      + (among ? ' That commit is among the unreadable trees — pin the CLI that applied it (the version in that commit\'s lockfile) and re-run.' : '');
+    if (among) return `${lines.join('\n')}\n${lead}`;
   }
+  return `${lines.join('\n')}\n${[lead, prune, rewrite].filter(Boolean).join(' ')}`;
 }
 
 /**
@@ -331,17 +468,32 @@ function resolveRepoContext(
 /** `git cat-file -e <ref>^{commit}` — is the commit present in THIS clone (not a shallow gap)? */
 function commitPresent(ref: string, cwd: string): boolean {
   try {
-    execFileSync('git', ['cat-file', '-e', `${ref}^{commit}`], { cwd, stdio: 'ignore' });
+    execFileSync('git', ['cat-file', '-e', `${ref}^{commit}`], { cwd, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
     return true;
   } catch {
     return false;
   }
 }
 
-/** `git merge-base --is-ancestor <ancestor> <head>` — does HEAD descend from the commit? */
+/**
+ * `git merge-base --is-ancestor`, three-valued: true / false / null when git could not answer
+ * (a timeout, a missing object, a broken repo). Every caller whose SAFE answer is "not an
+ * ancestor" may use {@link isAncestor}; a caller whose safe answer is the OTHER way — the squash
+ * guard accepts a carrier that is NOT an ancestor of the witness — must read null as "refuse".
+ */
+function ancestry(ancestor: string, head: string, cwd: string): boolean | null {
+  try {
+    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+    return true;
+  } catch (err: any) {
+    return err?.status === 1 ? false : null; // exit 1 = "not an ancestor"; anything else = could not tell
+  }
+}
+
+/** `git merge-base --is-ancestor <ancestor> <head>` — does HEAD descend from the commit? False when git cannot tell. */
 function isAncestor(ancestor: string, head: string, cwd: string): boolean {
   try {
-    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore' });
+    execFileSync('git', ['merge-base', '--is-ancestor', ancestor, head], { cwd, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
     return true;
   } catch {
     return false;
@@ -378,6 +530,11 @@ export interface GitLineageProbe {
   remotes(): string[] | null;
   /** `git ls-remote --heads --tags <remote>` advertised tip shas; null when the remote is unreachable. */
   lsRemote(remote: string): string[] | null;
+  /**
+   * Why the last `lsRemote(remote)` returned null — git's own first stderr line, paths scrubbed —
+   * or null when nothing was captured. Optional: a probe without it still names the remote.
+   */
+  lsRemoteError?(remote: string): string | null;
   /**
    * Does this object peel to a commit (`<sha>^{commit}`)? `null` when the object is absent from
    * the clone. An advertised tip that is present but is a tag on a blob or tree can carry no
@@ -387,9 +544,41 @@ export interface GitLineageProbe {
   peelsToCommit?(sha: string): boolean | null;
 }
 
+/**
+ * The runbook for a remote `git ls-remote` could not read. Three things it must do, each learned
+ * from a consumer's production cutover (cli 0.4.77, 2026-09-07) where the remote was named `db`
+ * and "could not read db" was read as the database being unreachable: name the remote AS a git
+ * remote, carry git's own error so the cause is on the surface, and name the verb that clears a
+ * dead one — `git remote remove` — next to the one that fixes a live one.
+ */
+function unreadableRemote(remote: string, git: GitLineageProbe): string {
+  const err = git.lsRemoteError?.(remote);
+  return `git remote '${remote}' could not be read: \`git ls-remote --heads --tags ${remote}\` failed${err ? ` — ${err}` : ''}. `
+    + `Fix the remote or remove it (git remote remove ${remote}), then re-run.`;
+}
+
+/**
+ * git's stderr, reduced to what a refusal may carry: the first non-empty line, absolute paths
+ * and file:// URLs replaced by `<path>` (the reason is recorded, and a home directory is not
+ * part of the diagnosis), capped so a chatty transport cannot flood the surface.
+ */
+export function firstErrorLine(stderr: string): string | null {
+  const line = stderr.split('\n').map((l) => l.trim()).find(Boolean);
+  if (!line) return null;
+  return scrubPaths(line).slice(0, 200);
+}
+
+/** Absolute paths and file:// URLs replaced by `<path>` — a recorded reason never carries a home directory. */
+export function scrubPaths(s: string): string {
+  return s
+    .replace(/file:\/\/\S+/g, 'file://<path>')
+    .replace(/(^|[\s'"(])\/[^\s'"()]+/g, '$1<path>');
+}
+
 export type LineageProof =
   | { proven: true; subcase: 'revert-unreachable' | 'unknown-commit-proven-absent' }
-  | { proven: false; kind: 'shallow' | 'partial' | 'reachable' | 'behind-remote' | 'remote-unreachable' | 'remote-list-failed' | 'no-remotes'; reason: string };
+  /** `ref` is set for `reachable`: the ref (or `HEAD`, or a remote name) that still holds the commit. */
+  | { proven: false; kind: 'shallow' | 'partial' | 'reachable' | 'behind-remote' | 'remote-unreachable' | 'remote-list-failed' | 'no-remotes'; reason: string; ref?: string };
 
 /**
  * Prove the declaring commit `sha` is reachable from NO ref, local or remote. Refuse-closed: every
@@ -410,10 +599,10 @@ export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProo
   if (present) {
     const containing = git.refsContaining(sha);
     if (containing.length > 0) {
-      return { proven: false, kind: 'reachable', reason: `commit ${short(sha)} is still reachable (${containing[0]}) — revert it in git and re-plan instead of attesting it lost.` };
+      return { proven: false, kind: 'reachable', ref: containing[0], reason: `commit ${short(sha)} is still reachable (${containing[0]}) — revert it in git and re-plan instead of attesting it lost.` };
     }
     if (git.isAncestorOf(sha, 'HEAD')) {
-      return { proven: false, kind: 'reachable', reason: `commit ${short(sha)} is still reachable (an ancestor of HEAD) — revert it in git and re-plan instead of attesting it lost.` };
+      return { proven: false, kind: 'reachable', ref: 'HEAD', reason: `commit ${short(sha)} is still reachable (an ancestor of HEAD) — revert it in git and re-plan instead of attesting it lost.` };
     }
   }
 
@@ -430,14 +619,14 @@ export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProo
   for (const remote of remotes) {
     const tips = git.lsRemote(remote);
     if (tips === null) {
-      return { proven: false, kind: 'remote-unreachable', reason: `could not read ${remote} to confirm ${short(sha)} is not on it — check connectivity and retry, or fetch the remote first.` };
+      return { proven: false, kind: 'remote-unreachable', reason: `cannot confirm ${short(sha)} is not on ${remote}: ${unreadableRemote(remote, git)}` };
     }
     for (const tip of tips) {
       if (!git.objectExists(tip)) {
         return { proven: false, kind: 'behind-remote', reason: `this clone is behind ${remote} (it advertises ${short(tip)}, which you do not have) — fetch it first; the declaring commit may still be on the remote.` };
       }
       if (present && git.isAncestorOf(sha, tip)) {
-        return { proven: false, kind: 'reachable', reason: `commit ${short(sha)} is still reachable (on ${remote}) — revert it in git and re-plan instead of attesting it lost.` };
+        return { proven: false, kind: 'reachable', ref: remote, reason: `commit ${short(sha)} is still reachable (on ${remote}) — revert it in git and re-plan instead of attesting it lost.` };
       }
     }
   }
@@ -464,9 +653,12 @@ export function proveLineageLost(sha: string, git: GitLineageProbe): LineageProo
 
 /** The real probe: each method is one git command run in `cwd`. */
 export function realLineageProbe(cwd: string): GitLineageProbe {
+  const lsRemoteErrors = new Map<string, string>();
+  // A hung remote must become a refusal, not a hang: every probe command is bounded. A timeout
+  // throws, so it reads as null — unreachable — and the proof refuses closed as it would offline.
   const run = (args: string[]): string | null => {
     try {
-      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+      return execFileSync('git', args, { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: GIT_TIMEOUT_MS }).toString();
     } catch {
       return null;
     }
@@ -489,10 +681,20 @@ export function realLineageProbe(cwd: string): GitLineageProbe {
       return out === null ? null : out.split('\n').map((l) => l.trim()).filter(Boolean);
     },
     lsRemote: (remote) => {
-      const out = run(['ls-remote', '--heads', '--tags', remote]);
-      if (out === null) return null;
+      // stderr is KEPT here, unlike `run`: the refusal this feeds must say why git could not read
+      // the remote, or "could not read db" is the database to whoever reads it.
+      let out: string;
+      try {
+        out = execFileSync('git', ['ls-remote', '--heads', '--tags', remote], { cwd, stdio: ['ignore', 'pipe', 'pipe'], timeout: GIT_TIMEOUT_MS }).toString();
+      } catch (e) {
+        const stderr = (e as { stderr?: Buffer | string }).stderr?.toString() ?? '';
+        lsRemoteErrors.set(remote, firstErrorLine(stderr) ?? firstErrorLine((e as Error).message ?? '') ?? 'no error output');
+        return null;
+      }
+      lsRemoteErrors.delete(remote);
       return out.split('\n').map((l) => l.split('\t')[0]?.trim()).filter((s): s is string => !!s && s.length >= 7);
     },
+    lsRemoteError: (remote) => lsRemoteErrors.get(remote) ?? null,
     peelsToCommit: (sha) => {
       if (!commitPresent(sha, cwd) && run(['cat-file', '-e', sha]) === null) return null; // absent
       return run(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`]) !== null;
@@ -550,8 +752,11 @@ export type ProveVerdict =
   | { status: 'fresh-target' }
   /** Not a git checkout — the rule cannot be verified here. */
   | { status: 'no-git' }
-  /** Fast-forward proven — via a ledger witness or an ancestor recompile. */
-  | { status: 'proven'; via: 'ledger' | 'recompile'; commit: string }
+  /** Fast-forward proven — via a ledger witness, its squashed successor, or an ancestor recompile.
+   *  For `squash`, `commit` is the CARRIER (an ancestor of HEAD holding the deploying commit's
+   *  models tree) and `witness` is the deploying commit the ledger names, which HEAD does not
+   *  descend from — both are surfaced and the weaker proof is recorded in schema_log. */
+  | { status: 'proven'; via: 'ledger' | 'squash' | 'recompile'; commit: string; witness?: string }
   /** The newest ledger witness is NOT an ancestor of HEAD — applying would revert merged work. */
   | { status: 'revert'; commit: string; appliedAt: string; reason: string }
   /** The witness names a commit this clone does not have (shallow) — fetch, do not guess. */
@@ -625,7 +830,7 @@ export function proveCloneCurrent(git: GitLineageProbe): { current: true } | { c
   for (const remote of remotes) {
     const tips = git.lsRemote(remote);
     if (tips === null) {
-      return { current: false, reason: `could not read ${remote} to confirm the clone is current — check connectivity and retry, or fetch the remote first.` };
+      return { current: false, reason: `cannot confirm the clone is current: ${unreadableRemote(remote, git)}` };
     }
     for (const tip of tips) {
       // refs/stash is excluded from the scan (enumerateModelTrees), so a tip contained ONLY by a
@@ -705,14 +910,17 @@ export async function proveDescent(
     if (isAncestor(r.gitRef, head, repoRoot)) {
       return { status: 'proven', via: 'ledger', commit: r.gitRef };
     }
+    const squash = squashedSuccessor(r.gitRef, head, modelsDir, repoRoot);
+    if (squash) return { status: 'proven', via: 'squash', commit: squash, witness: r.gitRef };
     return {
       status: 'revert',
       commit: r.gitRef,
       appliedAt: r.appliedAt,
       reason:
         `your checkout is behind the branch that last deployed this state — commit ${short(r.gitRef)} ` +
-        `(applied ${shortDate(r.appliedAt)}) is NOT an ancestor of HEAD. Applying now would revert ` +
-        'that merged work. Pull the deploying branch, rebase onto it, and re-plan.',
+        `(applied ${shortDate(r.appliedAt)}) is NOT an ancestor of HEAD, and no ancestor of HEAD carries ` +
+        'its models tree as a squashed successor. Applying now would revert that merged work. ' +
+        'Pull the deploying branch, rebase onto it, and re-plan.',
     };
   }
 
@@ -751,37 +959,39 @@ export async function proveDescent(
 
   const compileFailures: string[] = [];
   const unevaluated: string[] = [];
+  const unreadable: UnreadableTree[] = [];
+  const probe = opts.probe ?? realLineageProbe(repoRoot);
+  const lastApplied = ordered.find((r) => isAppliedOutcome(r.outcome));
   const unverifiable = (scope: string, scanned: number): ProveVerdict => {
     const notes: string[] = [];
     if (compileFailures.length > 0) notes.push(`${compileFailures.length} would not compile under this CLI`);
     if (unevaluated.length > 0) notes.push(`${unevaluated.length} could not be extracted`);
-    // Show the FIRST actual error: "Cannot find module '@everystack/model'" is a resolution
-    // problem with a different fix than "an older tree that no longer builds", and a message that
-    // hides it sends the operator to upgrade a CLI that is not the cause.
-    const first = compileFailures[0] ?? unevaluated[0];
+    // Every unreadable tree is NAMED — with the refs that carry it, its place in history, and its
+    // own error ("Cannot find module '@everystack/model'" is a resolution problem with a different
+    // fix than "an older tree that no longer builds") — and the runbook leads with the fix the
+    // ledger supports. See unreadableRunbook for the incident that shaped this.
     return {
       status: 'unverifiable',
       reason:
         `cannot verify the fast-forward rule — of ${scanned} ${scope} model state(s), ` +
         `${notes.join(' and ')}, and none of the readable ones declares the live state. This is a ` +
         'limit of THIS run (an older tree that no longer builds, or a failed extraction), not ' +
-        'evidence about the database — it is NOT drift. Upgrade/pin the CLI that last deployed ' +
-        `this state, or prune the branch that carries the unreadable tree, and re-run.${first ? ` First failure: ${first}` : ''}`,
+        `evidence about the database — it is NOT drift. Unreadable:\n${unreadableRunbook(unreadable, lastApplied, probe)}`,
       unevaluated,
       compileFailures,
     };
   };
+  const record = (candidate: ModelTreeCandidate, result: Extract<TreeEval, { error: string }>, ancestor: boolean): void => {
+    (result.kind === 'unevaluated' ? unevaluated : compileFailures).push(result.detail);
+    unreadable.push({ candidate, ancestor, error: result.error });
+  };
 
   let others: ModelTreeCandidate[] = [];
   try {
     for (const candidate of candidates) {
       const result = await evaluateTree(candidate, live, evalCtx);
-      if (result.kind === 'unevaluated') {
-        unevaluated.push(result.detail);
-        continue;
-      }
-      if (result.kind === 'compile-failed') {
-        compileFailures.push(result.detail);
+      if (result.kind === 'unevaluated' || result.kind === 'compile-failed') {
+        record(candidate, result, true);
         continue;
       }
       if (result.kind === 'no') continue;
@@ -824,7 +1034,7 @@ export async function proveDescent(
     }
     // Currency BEFORE the all-refs compile: a clone that is shallow, partial, or behind a remote
     // is told to fetch now, not after paying for every historical tree on every ref.
-    const currency = proveCloneCurrent(opts.probe ?? realLineageProbe(repoRoot));
+    const currency = proveCloneCurrent(probe);
     if (!currency.current) {
       return {
         status: 'unverifiable',
@@ -838,12 +1048,8 @@ export async function proveDescent(
     others = all.filter((c) => !seen.has(c.tree));
     for (const candidate of others) {
       const result = await evaluateTree(candidate, live, evalCtx);
-      if (result.kind === 'unevaluated') {
-        unevaluated.push(result.detail);
-        continue;
-      }
-      if (result.kind === 'compile-failed') {
-        compileFailures.push(result.detail);
+      if (result.kind === 'unevaluated' || result.kind === 'compile-failed') {
+        record(candidate, result, false);
         continue;
       }
       if (result.kind === 'no') continue;
@@ -873,7 +1079,6 @@ export async function proveDescent(
   // this is the first adoption of a database everystack never wrote. A dirty-worktree apply is
   // still an apply — its git_ref declares nothing (Phase A skips it as a witness), so the state
   // it produced was never committed anywhere; the origin says so.
-  const lastApplied = ordered.find((r) => isAppliedOutcome(r.outcome));
   const origin: DriftOrigin = lastApplied
     ? { kind: 'hand-edited', commit: lastApplied.gitRef, appliedAt: lastApplied.appliedAt, ...(lastApplied.dirty ? { dirty: true } : {}) }
     : { kind: 'never-declared' };
@@ -929,9 +1134,44 @@ export function attestationNote(a: { commit: string; subcase: string }): string
   return `descent-attested-lineage-lost (${short(a.commit)}, ${a.subcase})`;
 }
 
+/** The recorded note for a squash proof — goes in the apply row's schema_log outcome. */
+export function squashNote(carrier: string, witness: string): string {
+  return `descent: squash-successor (${short(carrier)} carries the models tree of ${short(witness)}, which HEAD does not descend from)`;
+}
+
+/**
+ * Does the operator's attestation name this commit? Exact, or a hex prefix of at least 7
+ * characters — compared against the ONE commit the refusal named, so there is nothing for a
+ * prefix to be ambiguous with. The refusal prints the 12-character form, and an operator who
+ * pastes it back is naming that commit. A strict string compare refused
+ * "42a3b97af246 does not match (42a3b97af246)" — two identical strings — because the ledger holds
+ * 40 characters and the refusal printed 12 (consumer cutover, cli 0.4.77, 2026-09-07).
+ */
+export function attestsCommit(attestation: string, commit: string): boolean {
+  const a = attestation.trim().toLowerCase();
+  if (a === commit.toLowerCase()) return true;
+  return a.length >= 7 && /^[0-9a-f]+$/.test(a) && commit.toLowerCase().startsWith(a);
+}
+
+/**
+ * Resolve an attestation through git before it is compared: a prefix, a tag, a branch, or a
+ * `HEAD~n` becomes the full sha. A value git cannot resolve (the commit is absent from this clone —
+ * the `unknown-commit-proven-absent` subcase, or a typo) passes through unchanged so the prefix
+ * compare above still gets its chance and a mismatch names what was given.
+ */
+export function resolveAttestation(attestation: string, cwd: string): string {
+  const full = git(['rev-parse', '--verify', '--quiet', `${attestation.trim()}^{commit}`], cwd)?.trim();
+  return full && /^[0-9a-f]{40,64}$/.test(full) ? full : attestation;
+}
+
 export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyContext): DescentApplyDecision {
   switch (verdict.status) {
     case 'proven':
+      // A squash proof rests on models-tree identity, not ancestry of the deploying commit — the
+      // record says so, exactly as an honoured attestation and a proven drift leave their trace.
+      return verdict.via === 'squash' && verdict.witness
+        ? { ok: true, note: squashNote(verdict.commit, verdict.witness) }
+        : { ok: true };
     case 'fresh-target':
       return { ok: true };
 
@@ -969,8 +1209,8 @@ export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyConte
       // construction, so the lineage-lost attestation can never be honoured here — the proof refuses
       // it as reachable. The escape is git-native: merge or rebase.
       if (!ctx.attestation) return { ok: false, reason: verdict.reason };
-      if (ctx.attestation !== verdict.commit) {
-        return { ok: false, reason: `--attest-lineage-lost ${short(ctx.attestation)} does not match the commit that declares this state (${short(verdict.commit)}) — drop the flag; that commit is reachable, so merge or rebase instead.` };
+      if (!attestsCommit(ctx.attestation, verdict.commit)) {
+        return { ok: false, reason: `--attest-lineage-lost ${ctx.attestation} does not match the commit that declares this state (${verdict.commit}) — drop the flag; that commit is reachable, so merge or rebase instead.` };
       }
       const proof = ctx.proveLineage(verdict.commit);
       return proof.proven
@@ -988,10 +1228,11 @@ export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyConte
           reason: `${verdict.reason} If that commit is gone for good (its branch was rebased away or deleted), attest it: --attest-lineage-lost ${short(verdict.commit)}${ctx.destructive ? ' --confirm' : ''}.`,
         };
       }
-      if (ctx.attestation !== verdict.commit) {
+      if (!attestsCommit(ctx.attestation, verdict.commit)) {
+        // Both in FULL: a short form on both sides once printed two identical strings as a mismatch.
         return {
           ok: false,
-          reason: `--attest-lineage-lost ${short(ctx.attestation)} does not match the commit that declared this state (${short(verdict.commit)}) — attest the exact commit the refusal names, or drop the flag.`,
+          reason: `--attest-lineage-lost ${ctx.attestation} does not match the commit that declared this state (${verdict.commit}) — attest the exact commit the refusal names, or drop the flag.`,
         };
       }
       const proof = ctx.proveLineage(verdict.commit);