@everystack/cli 0.4.76 → 0.4.78

package/src/cli/git-descent.ts

@@ -17,15 +17,24 @@
  * historical state of the models directory across all refs, compile each
  * unique tree, and ask whether its predicted live endpoint equals the
  * target's live fingerprint (brick 4's merged prediction, so unmodeled
- * brownfield tables ride through the test). A fingerprint no commit
- * declares is a DRIFT report and an explicit operator decision — never a
- * guess. Identity is the models-directory TREE, not the commit: a
- * cherry-picked identical state is the same declared state.
+ * brownfield tables ride through the test). Identity is the models-directory
+ * TREE, not the commit: a cherry-picked identical state is the same declared
+ * state.
+ *
+ * A fingerprint NO commit on ANY ref declares is DRIFT, and proven drift is the
+ * operator's decision the design promised: it PASSES at apply. The rule exists to
+ * stop an apply from reverting MERGED work, and when no ref anywhere declares the
+ * live state there is no merged work to revert — by construction. The proof is
+ * refuse-closed: a ref you do not descend from that DOES declare live refuses by
+ * name (`declared-elsewhere`, a teammate got there first); a tree that could not be
+ * read, or a clone that is shallow, partial, or behind a remote, is UNVERIFIABLE,
+ * never drift. `--force-descent` used to be the operator's drift decision; its
+ * retirement (2026-08-26) left drift with no escape at all, and a consumer walked
+ * into that dead end on 2026-09-07. The proof replaced the flag (Fable-ruled).
  */
 
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import type { ModelDescriptor } from '@everystack/model';
@@ -76,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;
   }
@@ -91,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
@@ -107,7 +158,10 @@ export function enumerateModelTrees(
   // `ancestorsOf`, restrict to the ancestors of one commit — the fallback proof only ever
   // considers trees the checkout descends from, so a diverged side branch is not even a
   // candidate (a non-ancestor declaring commit is the ledger's REVERT case, not recompile's).
-  const range = opts.ancestorsOf ? [opts.ancestorsOf] : ['--all'];
+  // `--all` walks refs/stash too. A stash is a WIP snapshot, never a deployed state: one that will
+  // not compile would poison the drift proof to unverifiable, and one that happens to match live
+  // would be named as a teammate's deployment. Excluded here and in refsContaining, consistently.
+  const range = opts.ancestorsOf ? [opts.ancestorsOf] : ['--exclude=refs/stash', '--all'];
   const out = git(['rev-list', ...range, '--full-history', '--date-order', '--', modelsDir], cwd);
   if (out === null) return [];
   const shas = out.trim().split('\n').filter(Boolean);
@@ -120,6 +174,7 @@ export function enumerateModelTrees(
       cwd,
       input: specs.join('\n') + '\n',
       stdio: ['pipe', 'pipe', 'ignore'],
+      timeout: GIT_TIMEOUT_MS,
     }).toString();
   } catch {
     return [];
@@ -183,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;
@@ -213,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 — ${err.message}` };
+      const error = `could not extract — ${firstLine(err.message)}`;
+      return { kind: 'unevaluated', detail: `${where}: ${error}`, error };
     }
   }
 
@@ -228,6 +285,12 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
 
   const evaluate = async (): Promise<boolean> => {
     const models = await ctx.loader(barrelPath);
+    // A barrel that compiles to ZERO models declares NOTHING. The prediction rides every
+    // undeclared live table through unchanged, so an empty models array "predicts" any live
+    // state exactly — it would declare every database there is. Absent barrel and empty barrel
+    // are the same clean 'no'. (Closing-gate review round 2, 2026-09-07: on a side branch this
+    // minted a false declared-elsewhere; as a HEAD ancestor it silently proved a fast-forward.)
+    if (models.length === 0) return false;
     const governedRoles = governedRolesForModels(models);
     const predicted = predictLiveFingerprint(models, live.snapshot, live.contract, { schema: ctx.schema, governedRoles });
     return predicted === governedLiveFingerprint(live.snapshot, live.contract, governedRoles);
@@ -241,15 +304,153 @@ async function evaluateTree(candidate: ModelTreeCandidate, live: LiveState, ctx:
     }
     return declares ? { kind: 'declares' } : { kind: 'no' };
   } catch (err: any) {
-    return { kind: 'compile-failed', detail: `${where}: ${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(' ')}`;
+}
+
+/**
+ * A compile/extraction error, summarized for a refusal that is RECORDED in a shared stage's
+ * schema_log: the cause, never the operator's filesystem.
+ *
+ *  - MODULE_NOT_FOUND: line 1 is the cause ("Cannot find module '@everystack/model'"); the
+ *    `Require stack:` that follows is absolute local paths — dropped.
+ *  - An esbuild TransformError (the "older tree that no longer builds" case): line 1 is only the
+ *    header "Transform failed with 1 error:" and the cause is on line 2 — kept, with the sandbox
+ *    path prefix stripped so what remains is `db/models/index.ts:2:0: ERROR: …`.
+ *  - An empty message says so instead of rendering nothing.
+ *
+ * (Closing-gate review round 5: a bare first-line take blanked the cause on exactly the class the
+ * `unverifiable` message exists to explain.)
+ */
+export function summarizeCompileError(message: unknown): string {
+  const lines = String(message ?? '').split('\n').map((l) => l.trimEnd());
+  const stop = lines.findIndex((l) => /^\s*Require stack:/.test(l));
+  const useful = (stop === -1 ? lines : lines.slice(0, stop)).filter((l) => l.trim().length > 0);
+  if (useful.length === 0) return '(error with no message)';
+  const take = /^Transform failed with \d+ errors?:?$/.test(useful[0].trim()) && useful.length > 1 ? useful.slice(0, 2) : useful.slice(0, 1);
+  return take
+    .map((l) => l.replace(/\/[^\s:'"]*\.everystack-descent-[^/\s]+\/[0-9a-f]+\//g, '').trim())
+    .join(' — ');
+}
+const firstLine = summarizeCompileError;
+
+/**
+ * Where historical trees materialize so that the materialized barrel can `import '@everystack/model'`:
+ * node walks UP from the importing file, so the sandbox must sit below a `node_modules` that holds
+ * the package. That is the nearest `node_modules` ABOVE THE MODELS BARREL, not the repo root's —
+ * in a monorepo the app (`apps/expo/db/models`) has `apps/expo/node_modules`, and the root
+ * `node_modules` may not carry the package at all (closing-gate review round 4, reproduced). No
+ * `node_modules` anywhere up to the repo root → the repo root itself (a nested checkout still walks
+ * up to its host's). Never the OS temp dir — that resolves nothing (the db:adopt 0.4.74 bug).
+ */
+export function materializeBase(repoRoot: string, modelsAbs: string): string {
+  let dir = path.dirname(modelsAbs);
+  while (dir.startsWith(repoRoot)) {
+    const nm = path.join(dir, 'node_modules');
+    if (fs.existsSync(nm)) return nm;
+    if (dir === repoRoot) break;
+    dir = path.dirname(dir);
+  }
+  return repoRoot;
 }
 
 /** Resolve the repo root, HEAD, and the models directory/barrel split — shared setup. */
 function resolveRepoContext(
   modelsPath: string,
   opts: DescentOptions,
-): { repoRoot: string; head: string; modelsDir: string; barrel: string } | null {
+): { repoRoot: string; head: string; modelsDir: string; barrel: string; modelsAbs: string } | null {
   const cwd = opts.cwd ?? process.cwd();
   const rootOut = git(['rev-parse', '--show-toplevel'], cwd);
   if (rootOut === null) return null;
@@ -261,23 +462,38 @@ function resolveRepoContext(
   // /private/var), and a mismatched prefix would walk the models path right out of the repo.
   const modelsAbs = path.resolve(fs.realpathSync(cwd), modelsPath);
   const rel = path.relative(repoRoot, modelsAbs);
-  return { repoRoot, head, modelsDir: path.dirname(rel) || '.', barrel: path.basename(modelsAbs) };
+  return { repoRoot, head, modelsDir: path.dirname(rel) || '.', barrel: path.basename(modelsAbs), modelsAbs };
 }
 
 /** `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;
@@ -314,11 +530,55 @@ 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
+   * models and cannot be `--contains`-tested (git errors on a non-commit), so currency skips it.
+   * Optional: a probe without it treats every tip as a commit (refuse-closed).
+   */
+  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
@@ -339,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.` };
     }
   }
 
@@ -359,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.` };
       }
     }
   }
@@ -393,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;
     }
@@ -418,10 +681,24 @@ 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;
+    },
   };
 }
 
@@ -451,34 +728,127 @@ export interface DescentLedgerRow {
   dirty: boolean;
   /** When the apply landed — for the REVERT message (names the commit + date). */
   appliedAt: string;
-  /** Only a successful state apply is a witness. */
+  /** Only a successful state apply is a witness: `applied`, or `applied — <descent note>`. */
   outcome: string;
 }
 
+/** A successful state apply, with or without a recorded descent note (`applied — …`). */
+export const isAppliedOutcome = (outcome: string): boolean => outcome === 'applied' || outcome.startsWith('applied — ');
+
+/**
+ * Where a proven drift came from — informs the warning and the schema_log note, never the
+ * verdict (the ledger is a memoir, decision 7). `never-declared`: no successful state apply is
+ * recorded here — first adoption of a database everystack never wrote. `hand-edited`: everystack
+ * did apply here once (the newest such row is named), and the database has moved since, outside
+ * the tool.
+ */
+export type DriftOrigin =
+  | { kind: 'never-declared' }
+  /** `dirty`: that last apply ran from a dirty worktree, so its commit never declared what it applied. */
+  | { kind: 'hand-edited'; commit: string | null; appliedAt: string; dirty?: boolean };
+
 export type ProveVerdict =
   /** The database has no tables — first apply bootstraps it. */
   | { 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. */
   | { status: 'unknown-commit'; commit: string; reason: string }
-  /** No ledger witness, and the ancestor recompile could not read every tree — inconclusive. */
+  /** A ref HEAD does not descend from declares the live state — a teammate's merged work. */
+  | { status: 'declared-elsewhere'; commit: string; reason: string }
+  /** The search could not read every tree, or the clone is not full and current — inconclusive. */
   | { status: 'unverifiable'; reason: string; unevaluated: string[]; compileFailures: string[] }
-  /** No ledger witness, every ancestor tree read cleanly, none declares live — real drift. */
-  | { status: 'drift'; reason: string; scannedTrees: number };
+  /** Every tree on every ref read cleanly in a full, current clone, and none declares live —
+   *  PROVEN drift. Passes at apply: nothing merged exists to revert. */
+  | { status: 'drift'; reason: string; scannedTrees: number; origin: DriftOrigin };
 
 export interface ProveDescentOptions extends DescentOptions {
   /** Retained-canon registry override — the cross-bump recompute path (tests inject a
    *  synthetic retired canon). Defaults to the module's RETAINED_CANONS. */
   canons?: Readonly<Record<number, CanonHasher>>;
+  /** The git probe the drift proof uses to establish the clone is full and current.
+   *  Default: {@link realLineageProbe} over the repo root. Injected so tests can prove each
+   *  currency refusal without a remote. */
+  probe?: GitLineageProbe;
 }
 
 const shortDate = (at: string): string => at.slice(0, 10);
 
+/**
+ * The origin, in words — ONE rendering for the plan warning, the apply warning, and the recorded
+ * note, so the dirty-worktree sub-case can never be surfaced in one place and dropped in another
+ * (closing-gate review round 4: the flag was computed and reached no human and no record).
+ *
+ *   never-declared                      — no everystack apply is recorded here
+ *   hand-edited since <sha>, <date>     — everystack applied from that commit; the database moved since
+ *   applied from a DIRTY worktree at <sha>, <date> — that commit never declared what was applied,
+ *                                          so nothing committed can declare this state
+ */
+export function describeDriftOrigin(origin: DriftOrigin, opts: { human?: boolean } = {}): string {
+  if (origin.kind === 'never-declared') return opts.human ? 'never declared: no everystack apply is recorded here' : 'never-declared';
+  const at = origin.commit ? `${short(origin.commit)}, ${shortDate(origin.appliedAt)}` : `an apply on ${shortDate(origin.appliedAt)}`;
+  return origin.dirty ? `applied from a DIRTY worktree at ${at}` : `hand-edited since ${at}`;
+}
+
+/** The recorded note for a proven drift — goes in the apply row's schema_log outcome. */
+export function driftOriginNote(origin: DriftOrigin): string {
+  return `descent: drift-origin proven (${describeDriftOrigin(origin)})`;
+}
+
+/**
+ * Is this clone full and current with every remote? The drift proof's precondition: "no ref
+ * anywhere declares live" is only a claim we may make when we hold every ref there is. Same
+ * probe as the lineage proof, but the question differs — currency, not the fate of one commit —
+ * so an empty remote set is simply current (a purely local repo has nothing to be behind).
+ * Refuse-closed: a failed `git remote` or an unreachable remote is NOT current.
+ *
+ * The test is REF reachability, never object presence. The scan this guards is `git rev-list
+ * --all`, which walks refs; an advertised tip that is present as an object but contained by no
+ * ref (a `git fetch origin <branch>` that wrote only FETCH_HEAD, or a locally deleted branch
+ * the remote still has) is invisible to the scan and MUST count as behind. Testing
+ * `objectExists` here let exactly that tip satisfy currency while the scan missed the models
+ * it declared — found by the closing-gate review 2026-09-07, before it shipped.
+ */
+export function proveCloneCurrent(git: GitLineageProbe): { current: true } | { current: false; reason: string } {
+  if (git.isShallow()) {
+    return { current: false, reason: 'this is a shallow clone, so a ref that declares the live state may simply not be here — unshallow first (git fetch --unshallow), then re-run.' };
+  }
+  if (git.isPartial()) {
+    return { current: false, reason: 'this is a partial clone, so objects can be missing locally — fetch the full history, then re-run.' };
+  }
+  const remotes = git.remotes();
+  if (remotes === null) {
+    return { current: false, reason: "could not list this repo's git remotes to confirm the clone is current — retry, or fetch the remotes first." };
+  }
+  for (const remote of remotes) {
+    const tips = git.lsRemote(remote);
+    if (tips === null) {
+      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
+      // stash counts as behind here — the two sides of the currency proof see the same refs, and
+      // this direction is refuse-closed. The probe itself stays raw: for the lineage proof a stash
+      // that reaches a commit is a REACHABLE commit, and filtering it there would fall open.
+      if (git.refsContaining(tip).filter((ref) => ref !== 'refs/stash').length === 0) {
+        // A tip we HOLD that is not a commit and peels to none (a tag on a blob or tree — the
+        // `junio-gpg-pub` shape) carries no models and can never be contained by a ref; it is
+        // not evidence of being behind. An ABSENT tip, or a present commit no ref contains, is.
+        if (git.peelsToCommit && git.peelsToCommit(tip) === false) continue;
+        return { current: false, reason: `this clone is behind ${remote} (it advertises ${short(tip)}, which no ref here contains) — fetch it first (git fetch ${remote} --tags); a ref there may declare the live state.` };
+      }
+    }
+  }
+  return { current: true };
+}
+
 /**
  * The fast-forward proof, ledger-first. Refuse-closed: no inconclusive branch passes.
  *
@@ -508,7 +878,7 @@ export async function proveDescent(
 
   const ctx = resolveRepoContext(modelsPath, opts);
   if (ctx === null) return { status: 'no-git' };
-  const { repoRoot, head, modelsDir, barrel } = ctx;
+  const { repoRoot, head, modelsDir, barrel, modelsAbs } = ctx;
 
   // ---- Phase A: the ledger witness (newest usable row wins). ----
   // "Newest wins" (the S→T→S pre-episode refusal) is a security-relevant property, so do not
@@ -516,7 +886,7 @@ export async function proveDescent(
   // future caller passing an unsorted ledger must not silently let a pre-episode row win.
   const ordered = [...ledger].sort((a, b) => Number(b.id) - Number(a.id));
   for (const r of ordered) {
-    if (r.outcome !== 'applied') continue; // only a successful state apply is a witness
+    if (!isAppliedOutcome(r.outcome)) continue; // only a successful state apply is a witness
     if (!r.toFingerprint) continue;
     if (!r.gitRef) continue; // a null git_ref cannot declare a commit
     if (r.dirty) continue; // a dirty mint's git_ref does not declare what was applied
@@ -540,23 +910,43 @@ 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.',
     };
   }
 
   // ---- Phase B: no usable ledger witness → ancestor-restricted recompile. ----
   const candidates = enumerateModelTrees(modelsDir, repoRoot, { ancestorsOf: head });
 
-  const nodeModules = path.join(repoRoot, 'node_modules');
+  // No ancestor carries a committed models directory to compare against — a shallow clone that
+  // truncated the deploying history, or the deploying branch is simply not in this checkout.
+  // That is a limit of THIS clone, not a hand-edit: UNVERIFIABLE, never drift.
+  if (candidates.length === 0) {
+    return {
+      status: 'unverifiable',
+      reason:
+        'cannot verify the fast-forward rule — no ancestor of your checkout carries a committed ' +
+        'models directory to compare against. This is a shallow clone (fetch the full history: ' +
+        'git fetch --unshallow) or the deploying branch is not in this checkout, not evidence ' +
+        'about the database — it is NOT drift. Fetch the deploying history and re-run.',
+      unevaluated: [],
+      compileFailures: [],
+    };
+  }
+
+  // Historical trees materialize INSIDE the project, below the nearest node_modules above the
+  // models barrel — see materializeBase. Never the OS temp dir.
   const materializeRoot = opts.materializeRoot
-    ?? fs.mkdtempSync(path.join(fs.existsSync(nodeModules) ? nodeModules : os.tmpdir(), '.everystack-descent-'));
+    ?? fs.mkdtempSync(path.join(materializeBase(repoRoot, modelsAbs), '.everystack-descent-'));
   const ownsRoot = !opts.materializeRoot;
   const evalCtx: EvalContext = {
     repoRoot,
@@ -569,15 +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`);
+    // 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. 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;
@@ -586,79 +1000,108 @@ export async function proveDescent(
       const ancestor = candidate.commits.find((commit) => isAncestor(commit, head, repoRoot)) ?? candidate.commits[0];
       return { status: 'proven', via: 'recompile', commit: ancestor };
     }
-  } finally {
-    if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
-  }
 
-  // No ancestor carries a committed models directory to compare against — a shallow clone that
-  // truncated the deploying history, or the deploying branch is simply not in this checkout.
-  // That is a limit of THIS clone, not a hand-edit: UNVERIFIABLE, never drift.
-  if (candidates.length === 0) {
-    return {
-      status: 'unverifiable',
-      reason:
-        'cannot verify the fast-forward rule — no ancestor of your checkout carries a committed ' +
-        'models directory to compare against. This is a shallow clone (fetch the full history: ' +
-        'git fetch --unshallow) or the deploying branch is not in this checkout, not evidence ' +
-        'about the database — it is NOT drift. Fetch the deploying history, or waive the rule deliberately.',
-      unevaluated,
-      compileFailures,
-    };
-  }
+    // A tree we could not READ is not evidence about the database. If any ancestor tree could not
+    // be extracted or compiled, "nothing declares this state" is a claim we are not entitled to
+    // make — the answer is UNVERIFIABLE, and its next move is retry/upgrade, never db:pull.
+    if (unevaluated.length > 0 || compileFailures.length > 0) return unverifiable('ancestor', candidates.length);
 
-  // A tree we could not READ is not evidence about the database. If any ancestor tree could not
-  // be extracted or compiled, "nothing declares this state" is a claim we are not entitled to
-  // make — the answer is UNVERIFIABLE, and its next move is retry/upgrade, never db:pull.
-  if (unevaluated.length > 0 || compileFailures.length > 0) {
-    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`);
-    return {
-      status: 'unverifiable',
-      reason:
-        `cannot verify the fast-forward rule — of ${candidates.length} ancestor 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 waive the rule deliberately.',
-      unevaluated,
-      compileFailures,
-    };
+    // ---- Phase C: the drift proof — no ancestor declares live, so scan EVERY ref. ----
+    // The fast-forward rule protects MERGED work. Before calling the live state undeclared, look
+    // at every tree on every ref this clone holds: one that declares live belongs to a line of
+    // history HEAD does not descend from — a teammate deployed it — and applying our edge would
+    // revert it. That refuses BY NAME. Only when no tree anywhere declares live is there nothing
+    // to protect.
+    const seen = new Set(candidates.map((c) => c.tree));
+    const all = enumerateModelTrees(modelsDir, repoRoot);
+    // The all-refs walk must be a SUPERSET of the ancestor walk — every ancestor tree is reachable
+    // from `--all`. When it is not, `git rev-list --all` failed (a broken or dangling ref makes it
+    // exit 128 while the ancestor walk still succeeds) and returned nothing, which is NOT "no
+    // other refs". Reading an empty result as "nothing else declares live" fell open to drift;
+    // found by the closing-gate review 2026-09-07.
+    const allTrees = new Set(all.map((c) => c.tree));
+    if ([...seen].some((tree) => !allTrees.has(tree))) {
+      return {
+        status: 'unverifiable',
+        reason:
+          'cannot verify the fast-forward rule — the walk over EVERY ref (git rev-list --all) did not ' +
+          'return the trees the ancestor walk did, so it failed part-way: a broken or dangling ref ' +
+          '(run `git fsck`, prune the bad ref) or a git error. That is a limit of THIS clone, not ' +
+          'evidence about the database — it is NOT drift. Repair the ref and re-run.',
+        unevaluated,
+        compileFailures,
+      };
+    }
+    // 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(probe);
+    if (!currency.current) {
+      return {
+        status: 'unverifiable',
+        reason:
+          `cannot verify the fast-forward rule — no ancestor of your checkout declares the live state, and ` +
+          `${currency.reason} That is a limit of THIS clone, not evidence about the database — it is NOT drift.`,
+        unevaluated,
+        compileFailures,
+      };
+    }
+    others = all.filter((c) => !seen.has(c.tree));
+    for (const candidate of others) {
+      const result = await evaluateTree(candidate, live, evalCtx);
+      if (result.kind === 'unevaluated' || result.kind === 'compile-failed') {
+        record(candidate, result, false);
+        continue;
+      }
+      if (result.kind === 'no') continue;
+      const commit = candidate.commits[0];
+      return {
+        status: 'declared-elsewhere',
+        commit,
+        reason:
+          `a ref your checkout does NOT descend from declares the target's live state — commit ` +
+          `${short(commit)} carries the models that match it. Someone deployed from that line of ` +
+          'history; applying your edge would revert their work. Fetch and merge or rebase onto it, ' +
+          'then re-plan.',
+      };
+    }
+  } finally {
+    if (ownsRoot) fs.rmSync(materializeRoot, { recursive: true, force: true });
   }
 
-  return {
-    status: 'drift',
-    scannedTrees: candidates.length,
-    reason:
-      `no ancestor of your checkout declares the target's live fingerprint ` +
-      `${short(fingerprintLive(live.snapshot, live.contract).hash)} — read ${candidates.length} ` +
-      'ancestor model state(s), all cleanly, and none matches. Either this database has never been ' +
-      'adopted into Models (nothing committed can declare it — the first-adoption case), or it ' +
-      'drifted after adoption. THE RUNBOOK: run everystack db:adopt — it renders Models from the ' +
-      'live database and PROVES they declare it exactly (it REFUSES rather than paper over any ' +
-      'difference); commit AND push that baseline, then re-run db:plan / db:apply and it descends ' +
-      'normally. If instead your Models are the source of truth and the database drifted, reconcile ' +
-      'with db:generate, or waive the rule deliberately.',
-  };
-}
+  const scannedTrees = candidates.length + others.length;
+  // A side branch we could not read is not evidence either — refuse-closed, naming the count so
+  // the operator can prune the branch that carries it.
+  if (unevaluated.length > 0 || compileFailures.length > 0) return unverifiable('reachable', scannedTrees);
 
-/**
- * Collapse a ProveVerdict into the ok/reason shape the apply core enforces. Refuse-closed:
- * only proven / fresh-target / no-git pass; every other verdict refuses, carrying its own
- * distinct cause so the operator's next move is unambiguous.
- */
-export function proveVerdictForApply(verdict: ProveVerdict): { ok: true } | { ok: false; reason: string } {
-  switch (verdict.status) {
-    case 'proven':
-    case 'fresh-target':
-    case 'no-git':
-      return { ok: true };
-    case 'revert':
-    case 'unknown-commit':
-    case 'unverifiable':
-    case 'drift':
-      return { ok: false, reason: verdict.reason };
-  }
+  // PROVEN DRIFT (the clone was proven full and current before the all-refs scan). The origin is
+  // read from the ledger for the MESSAGE only (memoir, not control): any successful state apply
+  // recorded here means everystack once wrote this database and it has moved since; none means
+  // 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 origin: DriftOrigin = lastApplied
+    ? { kind: 'hand-edited', commit: lastApplied.gitRef, appliedAt: lastApplied.appliedAt, ...(lastApplied.dirty ? { dirty: true } : {}) }
+    : { kind: 'never-declared' };
+  const fp = short(fingerprintLive(live.snapshot, live.contract).hash);
+  // The scan is scoped to THIS checkout's models path: a ref that declares live from a different
+  // directory (a models move on another line of history) is outside it. Say so — the claim must
+  // be exactly as wide as the search.
+  const scanned = `read ${scannedTrees} model state(s) at ${modelsDir}/ across every ref of a full, current clone, all cleanly, and none matches`;
+  const runbook =
+    'The reviewed plan you mint is the ORIGIN: `everystack db:plan --stage <name>` mints it, ' +
+    '`everystack db:apply --plan <file> --stage <name>` applies it, warns, and records the origin ' +
+    'in schema_log; every later apply descends from that row.';
+  const reason = origin.kind === 'never-declared'
+    ? `no commit on any ref declares the target's live fingerprint ${fp} — ${scanned}. Nothing has ever ` +
+      'declared this database (no everystack state apply is recorded here), so there is no merged work ' +
+      `the fast-forward rule could protect. ${runbook}`
+    : `no commit on any ref declares the target's live fingerprint ${fp} — ${scanned}. everystack last ` +
+      `applied here ${origin.commit ? `at commit ${short(origin.commit)} ` : ''}on ${shortDate(origin.appliedAt)}` +
+      (origin.dirty
+        ? ' from a DIRTY worktree — that commit never declared what was applied, so nothing committed can declare this state. '
+        : ', and the database has been changed outside the tool since (hand-edited). No ref declares what it is now, so ') +
+      `there is no merged work the fast-forward rule could protect; your committed Models are the source of truth. ${runbook}`;
+  return { status: 'drift', scannedTrees, origin, reason };
 }
 
 // ---------------------------------------------------------------------------
@@ -681,8 +1124,9 @@ export interface DescentApplyContext {
 }
 
 export type DescentApplyDecision =
-  /** Proceed. `attested` is set only when the attestation was honoured — record it in schema_log. */
-  | { ok: true; attested?: { commit: string; subcase: 'revert-unreachable' | 'unknown-commit-proven-absent' } }
+  /** Proceed. `attested` is set only when the attestation was honoured — record it in schema_log.
+   *  `note` is set for a proven drift — its origin, recorded in schema_log the same way. */
+  | { ok: true; attested?: { commit: string; subcase: 'revert-unreachable' | 'unknown-commit-proven-absent' }; note?: string }
   | { ok: false; reason: string };
 
 /** A short recorded note for a honoured attestation — goes in the apply row's schema_log outcome. */
@@ -690,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 };
 
@@ -703,17 +1182,42 @@ export function decideDescentApply(verdict: ProveVerdict, ctx: DescentApplyConte
         ? { ok: false, reason: 'this is not a git checkout and the plan is DESTRUCTIVE, so the fast-forward rule cannot be verified — run db:apply from the git checkout that declares your models.' }
         : { ok: true };
 
-    case 'unverifiable':
     case 'drift':
-      // No single declaring commit — nothing to attest ABOUT. The escape is to make HEAD declare the
-      // live state, then re-plan. An attestation here is a category error, refused as one.
+      // PROVEN drift is the operator's decision: no ref anywhere declares live, so there is no merged
+      // work to revert. It passes, and its origin is recorded. An attestation here is a category
+      // error — there is no single declaring commit to attest about — refused as one.
+      if (ctx.attestation) {
+        return {
+          ok: false,
+          reason: `--attest-lineage-lost does not apply here: there is no single declaring commit to attest about. ${verdict.reason} Proven drift needs no attestation — drop the flag and re-run.`,
+        };
+      }
+      return { ok: true, note: driftOriginNote(verdict.origin) };
+
+    case 'unverifiable':
+      // The search could not finish (an unreadable tree, or a clone that is not full and current).
+      // The verdict carries its own fetch/retry runbook; nothing to attest ABOUT.
       return {
         ok: false,
         reason: ctx.attestation
-          ? `--attest-lineage-lost does not apply here: there is no single declaring commit to attest about. ${verdict.reason} Commit your models so HEAD declares this state (db:generate), then db:plan and db:apply again.`
-          : `${verdict.reason} Commit your models so HEAD declares this state (db:generate), then db:plan and db:apply again.`,
+          ? `--attest-lineage-lost does not apply here: there is no single declaring commit to attest about. ${verdict.reason}`
+          : verdict.reason,
       };
 
+    case 'declared-elsewhere': {
+      // A commit on a ref we hold declares live and HEAD does not descend from it. Reachable by
+      // 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 (!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
+        ? { ok: true, attested: { commit: verdict.commit, subcase: proof.subcase } }
+        : { ok: false, reason: proof.reason };
+    }
+
     case 'revert':
     case 'unknown-commit': {
       // These name a declaring commit. Without an attestation the flagless escape (git revert / fetch)
@@ -724,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);