@mmnto/cli 1.124.0 → 2.1.0

package/dist/commands/install-hooks.js

@@ -3,6 +3,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { stdin as input, stdout as output } from 'node:process';
 import * as readline from 'node:readline/promises';
+// totem-context: mmnto-ai/totem#2753 — the rule's startup-cost premise does not apply to THIS module, because `install-hooks.js` is reached only through `await import` (index.ts, index-lite.ts, doctor.ts, doctor-parity.ts, eject.ts, init.ts, shield.ts), so it is never on the `--help` graph, and the core barrel is already in its static graph via `../git.js` (`import { safeExec } from '@mmnto/totem'`) and `../artifact-vocabulary.js`. The dynamic form is also unavailable: `isAttestedTrailer` is a SYNCHRONOUS exported predicate by contract and `installGitHook` is synchronous, so the only alternative would be duplicating core's `parseForkMarker` regex in the CLI — the divergence the shared parser exists to prevent.
+import { parseForkMarker, writeFileAtomicSync } from '@mmnto/totem';
 import { GROUNDING_ANCHOR_ISSUE, GROUNDING_ANCHOR_RECORD, PROMPT_SOURCE_OVERRIDE, } from '../artifact-vocabulary.js';
 import { resolveGitRoot } from '../git.js';
 import { SPEC_REQUIRED_SECTIONS } from './spec-templates.js';
@@ -270,8 +272,16 @@ function escapeBre(value) {
  */
 export async function resolveHookRenderOptions(cwd, flags) {
     const fallbackCmd = getFallbackCommand(cwd);
+    // `tierPinned` belongs on the DEFAULTS, not only on the fully-resolved return:
+    // both early exits below (no config anywhere, config present but unloadable)
+    // hand `defaults` straight back, and a flag is pinned in those states exactly as
+    // it is in the resolved one. Without it `tierForHook` would let an installed
+    // hook's own declaration override an explicit `--strict` / `--standard` in every
+    // config-less repo — `totem hook install --strict` a no-op, and `--force` writing
+    // the tier the user just asked to change (mmnto-ai/totem#2753 fold 3 F1).
     const defaults = {
         tier: flags?.tier ?? 'standard',
+        ...(flags?.tier === undefined ? {} : { tierPinned: true }),
         totemDir: DEFAULT_TOTEM_DIR,
         fallbackCmd,
     };
@@ -292,7 +302,7 @@ export async function resolveHookRenderOptions(cwd, flags) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
-        console.error(`[Totem] Could not load ${configPath} (${reason.split('\n')[0]}) — the git hooks are rendered at the defaults (totemDir '${DEFAULT_TOTEM_DIR}', tier '${defaults.tier}'); fix the config and re-run \`totem hook install --force\`.`);
+        console.error(`[Totem] Could not load ${configPath} (${reason.split('\n')[0]}) — the git hooks are rendered at the defaults (totemDir '${DEFAULT_TOTEM_DIR}'); the tier follows an explicit flag, else the tier each installed hook declares, else 'standard'; fix the config and re-run \`totem hook install --force\`.`);
         return { ...defaults, configError: reason };
     }
     const totemDir = isGlobalConfigPath(configPath)
@@ -305,13 +315,68 @@ export async function resolveHookRenderOptions(cwd, flags) {
         const { TotemError } = await import('@mmnto/totem');
         throw new TotemError('CONFIG_INVALID', `Refusing to render git hooks for totemDir ${JSON.stringify(totemDir)}: ${problem}`, 'Set `totemDir` to a plain relative directory inside the repo and re-run `totem hook install --force`.');
     }
+    const pinned = flags?.tier ?? config.hooks?.tier;
     return {
-        tier: flags?.tier ?? config.hooks?.tier ?? 'standard',
+        tier: pinned ?? 'standard',
+        ...(pinned === undefined ? {} : { tierPinned: true }),
         totemDir,
         fallbackCmd,
         configPath,
     };
 }
+/**
+ * The enforcement tier an INSTALLED hook declares (`TOTEM_HOOK_TIER="…"`), read from
+ * the TOTEM-OWNED BLOCK only — never from the whole file, so a user's own line
+ * carrying that assignment above an appended block cannot steer the render (the
+ * mmnto-ai/totem#2692 pass-2 F3 lesson, applied on the install side).
+ *
+ * `undefined` when the hook is absent, carries no marker, or predates the tier line.
+ *
+ * Only an ASSIGNMENT at the start of a line counts — the templates emit
+ * `TOTEM_HOOK_TIER="…"` unindented — so a comment inside the block that quotes the
+ * assignment (`# TOTEM_HOOK_TIER="strict" …`) cannot steer the render (Gemini,
+ * mmnto-ai/totem#2760 round 1).
+ *
+ * A hook with a start marker but NO end marker is read from the marker to EOF. That
+ * is a POLICY, not an observation about such files: everything below an unbounded
+ * start marker is TREATED as ours, because that file's one cure is `--force`, which
+ * discards the tail anyway. So a user line below it can only steer the render toward
+ * the tier it names — fail-closed toward strict, never a silent downgrade.
+ */
+export function declaredHookTier(content, marker, endMarker) {
+    const start = content.indexOf(marker);
+    if (start === -1)
+        return undefined;
+    const end = content.indexOf(endMarker, start + marker.length);
+    const block = end === -1 ? content.slice(start) : content.slice(start, end + endMarker.length);
+    return /^TOTEM_HOOK_TIER="(strict|standard)"/m.exec(block)?.[1];
+}
+/**
+ * The tier to RENDER one hook at: an explicit flag or a configured `hooks.tier`
+ * (both carried as `render.tierPinned`) wins; otherwise the tier the hook already
+ * on disk declares; otherwise `render.tier` (the `'standard'` default).
+ *
+ * Without this last-but-one rung a bare `totem hook install` or `totem init` on a
+ * repo that pins no tier re-renders a `--strict` hook at standard — a SILENT
+ * enforcement downgrade performed by a command the user ran to stay current
+ * (mmnto-ai/totem#2753 fold F4). doctor already refuses to call a tier difference
+ * drift for exactly this reason (mmnto-ai/totem#2692 amendment A10); this is the
+ * writer-side half of that ruling.
+ */
+function tierForHook(hooksDir, hookName, marker, endMarker, render) {
+    if (render.tierPinned === true)
+        return render.tier;
+    const hookPath = path.join(hooksDir, hookName);
+    let existing;
+    try {
+        existing = fs.readFileSync(hookPath, 'utf-8');
+        // totem-context: an unreadable/absent hook simply has no declared tier to honor — the caller falls back to the resolved default, which is the pre-#2753 behavior, never a crash of the install.
+    }
+    catch {
+        return render.tier;
+    }
+    return declaredHookTier(existing, marker, endMarker) ?? render.tier;
+}
 /**
  * Build a POSIX shell block that resolves the totem command at runtime.
  *
@@ -455,10 +520,12 @@ fi
  * integration. These scripts contain the full guard logic (diff checks, null-SHA
  * guards) that bare inline commands would skip.
  *
- * Takes the RESOLVED {@link HookRenderOptions} rather than resolving config
+ * Takes the RESOLVED {@link ResolvedHookRenderOptions} rather than resolving config
  * itself: both callers already hold the one resolution for this invocation, and
  * a required parameter is the same compiler-enforced thread the builders use
- * (mmnto-ai/totem#2692 C1/C2).
+ * (mmnto-ai/totem#2692 C1/C2). `tierPinned` rides along so this path applies the
+ * SAME tier rule the git-hook writers do — a hook-manager repo is not a repo whose
+ * enforcement tier may be silently reset (mmnto-ai/totem#2753 fold 3 F2).
  */
 export function generateHookHelpers(gitRoot, render) {
     // Refuse BEFORE the mkdir: the helper dir is joined from the value, and a
@@ -469,12 +536,22 @@ export function generateHookHelpers(gitRoot, render) {
     fs.mkdirSync(hooksDir, { recursive: true });
     const postMerge = buildHookContent(render);
     const postCheckout = buildPostCheckoutHookContent(render);
-    const preCommit = buildPreCommitHook(render);
-    const prePush = buildPrePushHook(render);
-    fs.writeFileSync(path.join(hooksDir, 'post-merge.sh'), postMerge, { mode: 0o755 });
-    fs.writeFileSync(path.join(hooksDir, 'post-checkout.sh'), postCheckout, { mode: 0o755 });
-    fs.writeFileSync(path.join(hooksDir, 'pre-commit.sh'), preCommit, { mode: 0o755 });
-    fs.writeFileSync(path.join(hooksDir, 'pre-push.sh'), prePush, { mode: 0o755 });
+    // Only these two carry `TOTEM_HOOK_TIER`, so only these two can be downgraded.
+    // The declaration is read from the helper ALREADY on disk, exactly as the git-hook
+    // path reads it from the installed hook.
+    const preCommit = buildPreCommitHook({
+        ...render,
+        tier: tierForHook(hooksDir, 'pre-commit.sh', TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END, render),
+    });
+    const prePush = buildPrePushHook({
+        ...render,
+        tier: tierForHook(hooksDir, 'pre-push.sh', TOTEM_PREPUSH_MARKER, TOTEM_PREPUSH_END, render),
+    });
+    // Atomic like every other git-hook write (mmnto-ai/totem#2760 round 1, leg F2).
+    writeExecutableHook(path.join(hooksDir, 'post-merge.sh'), postMerge);
+    writeExecutableHook(path.join(hooksDir, 'post-checkout.sh'), postCheckout);
+    writeExecutableHook(path.join(hooksDir, 'pre-commit.sh'), preCommit);
+    writeExecutableHook(path.join(hooksDir, 'pre-push.sh'), prePush);
 }
 function detectHookManager(cwd) {
     if (fs.existsSync(path.join(cwd, '.husky'))) {
@@ -599,31 +676,30 @@ export async function installPostMergeHook(cwd, rl, options) {
     const hookPath = path.join(hooksDir, 'post-merge');
     // Idempotency: check if already installed
     if (fs.existsSync(hookPath)) {
-        const existing = fs.readFileSync(hookPath, 'utf-8');
+        // Raw bytes are the user's file; the decoded text serves the probes only.
+        const raw = fs.readFileSync(hookPath);
+        const existing = raw.toString('utf-8');
         if (existing.includes(TOTEM_HOOK_MARKER)) {
             console.log('[Totem] Post-merge hook already installed.');
             return;
         }
-        // Append to existing hook — reuse buildHookContent, strip shebang
+        // Append to existing hook — reuse buildHookContent, strip shebang. Written as
+        // one atomic replacement of the whole file (the user's RAW bytes + ours) rather
+        // than an append: an interrupted append leaves a hook truncated mid-block,
+        // which git still runs (mmnto-ai/totem#2760 round 1, leg F2). The helper
+        // keeps the user's file mode.
         const separator = existing.endsWith('\n') ? '' : '\n';
         const appendBlock = buildHookContent(render)
             .replace(/^#!\/bin\/sh\n/, '')
             .trimStart();
-        fs.appendFileSync(hookPath, separator + '\n' + appendBlock);
+        writeFileAtomicSync(hookPath, Buffer.concat([raw, Buffer.from(separator + '\n' + appendBlock, 'utf-8')]));
         console.log('[Totem] Appended post-merge hook to existing hook file.');
         return;
     }
-    // Create new hook
+    // Create new hook — atomic, executable on POSIX, mode skipped on Windows by the
+    // helper's own boundary (git bash owns the bit there).
     fs.mkdirSync(hooksDir, { recursive: true });
-    fs.writeFileSync(hookPath, buildHookContent(render));
-    // Make executable (no-op on Windows, git bash handles it)
-    try {
-        fs.chmodSync(hookPath, 0o755);
-        // totem-context: intentional cleanup — chmod may fail on Windows; the hook still runs via git bash, so a failed mode bit is not a failed install.
-    }
-    catch {
-        // chmod may fail on Windows — hooks still work via git bash
-    }
+    writeExecutableHook(hookPath, buildHookContent(render));
     console.log('[Totem] Installed post-merge hook.');
 }
 // ─── Agent detection snippet (POSIX-compliant) ─────────
@@ -668,6 +744,22 @@ export function buildPreCommitHook(options) {
     // nothing. The record's sha256 is compared and REPORTED (matches / revised
     // since binding) but never blocks: blocking on revision would price every
     // fold of a design record at one LLM call, the friction this slice retires.
+    //
+    // #2737 fixes what that shape check MEASURED, on both halves. A body now ends
+    // only at a heading of the SAME OR SHALLOWER level: a deeper heading neither
+    // ends the body nor counts as one, so a section that opens with a `####`
+    // sub-heading is no longer read as empty (it was, in 3 of the 7 recorded R3
+    // drafts, on the longest section each of them wrote). And a promised heading
+    // is matched EXACTLY first, then — only if nothing matched — tolerantly, with
+    // ONE trailing parenthetical group stripped from BOTH sides: symmetric, so a
+    // dropped `(structural constraint)` and a differing `(required)` both match,
+    // and LEVEL-EXACT, because the `###` marker is part of the compared string
+    // (`## Problem Statement` never satisfies `### Problem Statement`). A
+    // tolerant match is never silent: the pass line carries `· tolerated
+    // <promised> ~ <found>` for each one, so the drift is disclosed on the commit
+    // that relied on it rather than absorbed. Trailing whitespace is not drift —
+    // `trimEnd()` settles it on the exact pass, and nothing is named.
+    //
     // Exit vocabulary: 0 evidence · 2 no spec artifact · 3 the newest spec
     // artifact is NOT evidence (reason on stdout) · anything else = the reader
     // itself could not run. The evidence line makes a stale pass VISIBLE (age
@@ -685,10 +777,32 @@ export function buildPreCommitHook(options) {
     // The artifact is a plain JSON file a seat can hand-edit, and its NAME comes
     // off the filesystem, so nothing echoed is trusted as text: EVERY value that
     // reaches stdout — the artifact's path, its `createdAt`, `anchor.kind`,
-    // `anchor.ref` and each required heading — passes through `safe()` first. A
+    // `anchor.ref`, `anchor.sha256`, the resolved realpath of a bound record,
+    // each required heading, and, on a tolerant match, the draft line it matched
+    // — passes through `safe()` first, except the two sha256 prefixes in
+    // `recordStatus`, which the preceding `/^[0-9a-f]{64}$/` block proves hex. A
     // newline in any of them would otherwise forge a second `[Totem]` line in the
-    // hook's own output; `safe()` collapses C0 (0x00–0x1f) AND the DEL/C1 band
-    // (0x7f–0x9f), because U+0085 (NEL) breaks a line on some terminals.
+    // hook's own output; `safe()` collapses C0 (0x00–0x1f), the DEL/C1 band
+    // (0x7f–0x9f), and U+2028/U+2029, because U+0085 (NEL) breaks a line on some
+    // terminals and U+2028/U+2029 are line separators for the same purpose.
+    //
+    // `safe()` is necessary but NOT sufficient, because it cannot see the attack
+    // that lives in PRINTABLE bytes (mmnto-ai/totem#2737 fold 3). A literal
+    // backslash followed by `n` is two printable characters, so it passes
+    // `safe()` untouched — and the hole was open wherever `/bin/sh` EXPANDS
+    // backslash escapes in `echo`: `dash`, which is `/bin/sh` on Debian and
+    // Ubuntu, and macOS's own `/bin/sh`, a bash built with `xpg_echo` on. On
+    // those the pair becomes a real newline at the shell and forges the second
+    // `[Totem]` line (`\\c` truncates the line instead, swallowing the cure text
+    // that follows). Only Git Bash and a plain bash leave it inert, so the hole
+    // was invisible in exactly the shells a seat develops in. The two
+    // sinks that echo an untrusted value — the evidence line and the BLOCKED
+    // reason, both carrying `$spec_evidence` — therefore print through
+    // `printf '%s\\n'`, which is defined to treat its ARGUMENT as literal text on
+    // every POSIX shell. The remaining echoes in this block carry only
+    // `$reader_status` (an integer from `$?`) and the render-time `runsDir`
+    // (validated by `assertRenderableTotemDir`, which refuses a backslash), so
+    // neither can carry the payload.
     // Containment is decided by RESOLUTION, not by inspecting one segment, and
     // it is decided TWICE. Lexically first: a `record` ref that is absolute
     // (either path flavor) or whose `path.resolve` against `process.cwd()` — the
@@ -711,8 +825,10 @@ export function buildPreCommitHook(options) {
 # top-level admission.runMetadata.caller of "spec"), read JSON-aware — a
 # substring match would accept a review artifact that merely quotes the key —
 # that is ANCHORED on an issue or a bound design record, and whose subject
-# carries a real shape: the required headings each with a body (an issue run
-# drafted by the built-in prompt), or at least one heading with a body (a
+# carries a real shape: every promised heading (level-exact; a trailing
+# parenthetical may differ or be dropped, and the evidence line names it) each
+# with a non-blank body before the next heading of the same or shallower level
+# (an issue run drafted by the built-in prompt), or at least one heading with a body (a
 # record run, or an issue run drafted under a custom prompt). A record run is
 # judged on the bytes of the record at grounding.anchor.ref, re-read here from
 # the worktree top; its sha256 is REPORTED, never enforced.
@@ -750,19 +866,26 @@ function safe(text) {
   let out = "";
   for (let i = 0; i < text.length; i++) {
     const code = text.charCodeAt(i);
-    const control = code < 32 || (code >= 127 && code <= 159);
+    const control = code < 32 || (code >= 127 && code <= 159) || [8232, 8233].indexOf(code) > -1;
     out = out + (control ? "?" : text.charAt(i));
   }
   return out;
 }
 const shownFile = safe(file);
 const shownAt = safe(best.at);
-function isHeading(line) {
+function headingLevel(line) {
   let n = 0;
   while (n < line.length && ["#"].indexOf(line.charAt(n)) > -1) n = n + 1;
-  if (n < 1 || n > 6) return false;
-  if ([" ", "\\t"].indexOf(line.charAt(n)) < 0) return false;
-  return line.slice(n + 1).trim().length > 0;
+  if (n < 1 || n > 6) return 0;
+  if ([" ", "\\t"].indexOf(line.charAt(n)) < 0) return 0;
+  return line.slice(n + 1).trim().length > 0 ? n : 0;
+}
+function stripParen(s) {
+  const t = s.trimEnd();
+  if (t.charAt(t.length - 1) !== ")") return t;
+  const open = t.lastIndexOf("(");
+  if (open < 1) return t;
+  return t.slice(0, open).trimEnd();
 }
 function escapesTop(rel) {
   const norm = rel.split("\\\\").join("/");
@@ -814,23 +937,144 @@ if (kind !== KIND_RECORD) {
 }
 if ([65279].indexOf(subject.charCodeAt(0)) > -1) subject = subject.slice(1);
 const lines = subject.split("\\n");
-function hasBodyAfter(start) {
+const tolerated = [];
+// Fences (mmnto-ai/totem#2769), by the CommonMark rule: a line indented at most
+// three spaces whose first run is three or more backticks or tildes OPENS a
+// fence — a backtick run only when the rest of the line carries no backtick —
+// and a CLOSER is the same character, at least as long, with nothing else on
+// the line; an unclosed fence runs to the end of the draft. A delimiter line
+// is neither a heading, a match candidate, nor body. A line inside a fence is
+// neither a heading nor a match candidate — a promised heading quoted there
+// (the skeleton pasted as an example) is not the section it names, and is not
+// body for the section above it either — but any other non-blank fenced line
+// IS body: a section whose content is one code block is a written section.
+const TICK = String.fromCharCode(96);
+const fenceLine = [];
+const inFence = [];
+const fenceOpenedAt = [];
+let fenceChar = "";
+let fenceLen = 0;
+let openedAt = 0;
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  let indent = 0;
+  while (indent < line.length && [" "].indexOf(line.charAt(indent)) > -1) indent = indent + 1;
+  const ch = line.charAt(indent);
+  let run = 0;
+  if (indent < 4 && [TICK, "~"].indexOf(ch) > -1) {
+    while (indent + run < line.length && [ch].indexOf(line.charAt(indent + run)) > -1) run = run + 1;
+  }
+  const rest = line.slice(indent + run);
+  if (fenceChar.length < 1) {
+    const opens = run >= 3 && ([TICK].indexOf(ch) < 0 || rest.indexOf(TICK) < 0);
+    if (opens) { fenceChar = ch; fenceLen = run; openedAt = i + 1; fenceLine.push(true); inFence.push(false); fenceOpenedAt.push(0); continue; }
+    fenceLine.push(false); inFence.push(false); fenceOpenedAt.push(0);
+    continue;
+  }
+  // Only spaces and tabs may follow a closer (CommonMark); JS trim() would also
+  // strip Unicode spaces such as U+00A0, so a closer that Markdown keeps open
+  // would read as closed here and a fenced skeleton after it would reach the
+  // gate (Greptile P1 on mmnto-ai/totem#2769).
+  const closes = run >= fenceLen && [fenceChar].indexOf(ch) > -1 && rest.split(" ").join("").split("	").join("").length < 1;
+  if (closes) { fenceChar = ""; fenceLen = 0; fenceLine.push(true); inFence.push(false); fenceOpenedAt.push(0); continue; }
+  fenceLine.push(false); inFence.push(true); fenceOpenedAt.push(openedAt);
+}
+// A line of only # characters and whitespace (mmnto-ai/totem#2769): not a
+// heading (no text) and not body either — it is the skeleton of one. Inside a
+// fence it is code, and code is body.
+function bareHashes(line) {
+  const t = line.trim();
+  return t.length > 0 && t.split("#").join("").length < 1;
+}
+function levelAt(i) {
+  if (fenceLine[i] || inFence[i]) return 0;
+  return headingLevel(lines[i]);
+}
+// A promised heading, spelled exactly or with one trailing parenthetical
+// dropped (the same tolerance the matcher extends), whatever its indentation.
+function promisedHeading(text) {
+  const t = text.trim();
+  if (REQUIRED.indexOf(t) > -1) return true;
+  const w = stripParen(t);
+  for (const h of REQUIRED) { if ([w].indexOf(stripParen(h)) > -1) return true; }
+  return false;
+}
+function isBody(i) {
+  if (fenceLine[i]) return false;
+  if (lines[i].trim().length < 1) return false;
+  if (inFence[i]) return !promisedHeading(lines[i]);
+  return !bareHashes(lines[i]);
+}
+// Why a section read as empty when it was not blank: the reader says which
+// rule emptied it, so the cure is never a line the seat can see and not explain.
+function emptyReason(start, level) {
+  let quoted = false;
+  let hashes = false;
+  let fences = false;
+  for (let i = start + 1; i < lines.length; i++) {
+    const n = levelAt(i);
+    if (n > 0 && n <= level) break;
+    if (n > 0) continue;
+    if (fenceLine[i]) fences = true;
+    else if (inFence[i] && lines[i].trim().length > 0) quoted = true;
+    else if (bareHashes(lines[i])) hashes = true;
+  }
+  const found = [];
+  if (quoted) found.push("a promised heading quoted inside a fenced code block");
+  if (hashes) found.push("a line of # characters");
+  if (fences && !quoted) found.push("an empty fenced code block");
+  if (found.length < 1) return "";
+  return " — nothing under it counts as body: " + found.join("; ");
+}
+function hasBodyAfter(start, level) {
   for (let i = start + 1; i < lines.length; i++) {
-    if (isHeading(lines[i])) return false;
-    if (lines[i].trim().length > 0) return true;
+    const n = levelAt(i);
+    if (n > 0 && n <= level) return false;
+    if (n > 0) continue;
+    if (isBody(i)) return true;
   }
   return false;
 }
+function candidate(i) {
+  return !fenceLine[i] && !inFence[i];
+}
+function fencedCopyOf(heading) {
+  const want = stripParen(heading);
+  for (let i = 0; i < lines.length; i++) {
+    if (!inFence[i]) continue;
+    const seen = lines[i].trim();
+    if ([heading].indexOf(seen) > -1 || [want].indexOf(stripParen(seen)) > -1) return i;
+  }
+  return -1;
+}
+// The fence still open when the scan ended, if any — its copy of a heading
+// gets the cure that fits (close it) rather than the one that does not.
+const unclosedAt = fenceChar.length > 0 ? openedAt : 0;
+function fenceCure(openLine) {
+  if (unclosedAt > 0 && [unclosedAt].indexOf(openLine) > -1) return " (that fence is never closed — close it with a bare closing fence: the same character, at least as long, nothing else on the line — or write the section outside it)";
+  return " (write the section outside the fence)";
+}
 if (shape !== "DOCUMENT") {
   for (const heading of REQUIRED) {
     let at = -1;
-    for (let i = 0; i < lines.length; i++) { if ([heading].indexOf(lines[i].trimEnd()) > -1) { at = i; break; } }
-    if (at < 0) block("the draft in " + shownFile + " is missing heading " + safe(heading));
-    if (!hasBodyAfter(at)) block("the draft in " + shownFile + " has an empty heading " + safe(heading));
+    for (let i = 0; i < lines.length; i++) { if (candidate(i) && [heading].indexOf(lines[i].trimEnd()) > -1) { at = i; break; } }
+    let matchedAs = "";
+    if (at < 0) {
+      const want = stripParen(heading);
+      for (let i = 0; i < lines.length; i++) { if (candidate(i) && [want].indexOf(stripParen(lines[i].trimEnd())) > -1) { at = i; break; } }
+      if (at > -1) { matchedAs = safe(lines[at].trimEnd()); tolerated.push(safe(heading) + " ~ " + matchedAs); }
+    }
+    if (at < 0) {
+      const fencedAt = fencedCopyOf(heading);
+      if (fencedAt > -1) block("the draft in " + shownFile + " is missing heading " + safe(heading) + " — it appears only inside a fenced code block opened at line " + fenceOpenedAt[fencedAt] + fenceCure(fenceOpenedAt[fencedAt]));
+      block("the draft in " + shownFile + " is missing heading " + safe(heading));
+    }
+    const shownHeading = safe(heading) + (matchedAs.length > 0 ? " (matched as " + matchedAs + ")" : "");
+    if (!hasBodyAfter(at, levelAt(at))) block("the draft in " + shownFile + " has an empty heading " + shownHeading + emptyReason(at, levelAt(at)));
   }
 } else {
   let bodied = false;
-  for (let i = 0; i < lines.length; i++) { if (isHeading(lines[i]) && hasBodyAfter(i)) { bodied = true; break; } }
+  for (let i = 0; i < lines.length; i++) { const n = levelAt(i); if (n > 0 && hasBodyAfter(i, n)) { bodied = true; break; } }
   if (!bodied && kind !== KIND_RECORD) block("the draft in " + shownFile + " has no heading with a body (custom prompt: the built-in template skeleton is not required)");
   if (!bodied) block("the bound record at " + shownRef + " has no heading with a body");
 }
@@ -838,6 +1082,7 @@ const stamp = best.at ? Date.parse(best.at) : NaN;
 const days = Number.isNaN(stamp) ? -1 : Math.floor((Date.now() - stamp) / 86400000);
 let out = shownFile + " (" + (shownAt || "undated") + (days >= 0 ? ", " + days + " days old" : "") + ")";
 out = out + " · anchor " + shownKind + " " + shownRef + " · shape " + shape;
+if (tolerated.length > 0) out = out + " · tolerated " + tolerated.join("; ");
 if (recordStatus.length > 0) out = out + " · " + recordStatus;
 emit(out);
 ' 2>/dev/null)
@@ -847,9 +1092,9 @@ emit(out);
   # each reported distinctly, never as "no evidence", and all fail-closed.
   reader_status=$?
   if [ "$reader_status" = "0" ] && [ -n "$spec_evidence" ]; then
-    echo "[Totem] spec evidence: $spec_evidence"
+    printf '%s\\n' "[Totem] spec evidence: $spec_evidence"
   elif [ "$reader_status" = "3" ]; then
-    echo "[Totem] BLOCKED: $spec_evidence — run 'totem spec <issue>' or 'totem spec --from <record>' (add --fresh if the response is cached) (strict mode)"
+    printf '%s\\n' "[Totem] BLOCKED: $spec_evidence — run 'totem spec <issue>' or 'totem spec --from <record>' (add --fresh if the response is cached) (strict mode)"
     exit 1
   elif [ "$reader_status" != "2" ]; then
     echo "[Totem] BLOCKED: the spec-evidence reader could not run (node exit status $reader_status — node missing from PATH, or ${runsDir}/ unreadable); fix the runtime and retry (strict mode)"
@@ -881,14 +1126,24 @@ export function buildPrePushHook(options) {
     const { fallbackCmd, totemDir } = options;
     const effectiveTier = options.tier;
     assertRenderableTotemDir(totemDir);
-    // The strict-tier review-leg floor (mmnto-ai/totem#2698; doctrine
-    // `model-tiering.md` § Review legs — a self-authored judgment-dense diff owes
-    // one falsification leg before it is presented). The gate itself derives
-    // everything: whether the push is legs-owed (the changed-file set against
-    // `hooks.legsOwed.globs`, read at RUN time so a glob edit needs no hook
-    // re-install) and whether a deposit ancestor-or-equal of HEAD answers for it.
-    // The hook maps that derivation onto exit codes and NOTHING else — the tier
-    // changes only which code blocks, never a line of the text.
+    // The review-leg floor (mmnto-ai/totem#2698; doctrine `model-tiering.md`
+    // § Review legs — a self-authored judgment-dense diff owes one falsification
+    // leg before it is presented). The gate itself derives everything: whether
+    // the push is legs-owed (the changed-file set against `hooks.legsOwed.globs`,
+    // read at RUN time so a glob edit needs no hook re-install) and whether a
+    // deposit ancestor-or-equal of HEAD answers for it. The hook maps that
+    // derivation onto exit codes and NOTHING else — the tier changes only which
+    // code blocks, never a line of the text.
+    //
+    // Since mmnto-ai/totem#2771 the repo's `hooks.legsOwed.enforce` (read at run
+    // time by the gate, like the globs) can arm this ONE gate at any tier
+    // (`'block'`) or soften it at every tier (`'advisory'`) without touching the
+    // spec-evidence and shield arms. The hook never reads the knob: it reads the
+    // EXIT CODE the gate has already mapped through it. So 3 and 2 block on
+    // every tier — under the advisory flag they only ever come back when the
+    // knob says block — and only a failure before the derivation (an unloadable
+    // config, which is also how the knob would go unread) stays strict-only,
+    // which keeps a knob-less install byte-for-byte on its old behaviour.
     //
     // Slotted BEFORE the shield block deliberately: on strict this is a sub-second
     // local read, and paying for the slow review gate before discovering the push
@@ -910,29 +1165,40 @@ export function buildPrePushHook(options) {
     // `legs gate` at all. `--advisory` is specific to this verb, so its presence
     // in that output means the verb itself answered.
     const legsBlock = `
-  # Strict mode: require a fresh falsification-leg deposit for legs-owed pushes
-  # (mmnto-ai/totem#2698, doctrine/model-tiering.md § Review legs).
+  # The review-leg floor: require a fresh falsification-leg deposit for
+  # legs-owed pushes (mmnto-ai/totem#2698, doctrine/model-tiering.md § Review legs).
   # Exit vocabulary of \`totem legs gate\`: 0 = not owed, or a deposit answers for
   # this head · 3 = owed with no fresh deposit · 2 = the gate could not derive
-  # (not a git repo, HEAD or the branch diff unresolvable). Advisory tiers print
-  # the SAME lines and exit 0.
+  # (not a git repo, HEAD or the branch diff unresolvable). The strict tier and
+  # agent seats run the bare gate; the other tiers pass --advisory, under which
+  # the gate prints the SAME lines and exits 0 — unless the repo's
+  # hooks.legsOwed.enforce says 'block', in which case the gate exits 3 or 2 at
+  # any tier and this hook blocks on it (mmnto-ai/totem#2771); 'advisory' makes
+  # it exit 0 at any tier. A status other than 0, 2 or 3 is a failure before
+  # the derivation (an unloadable config) and blocks only on the strict arm.
   if $TOTEM_CMD legs gate --help 2>/dev/null | grep -q -- '--advisory'; then
+    legs_strict=0
     if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]; then
+      legs_strict=1
       $TOTEM_CMD legs gate
       legs_status=$?
-      if [ "$legs_status" = "3" ]; then
-        echo "[Totem] BLOCKED: this push is legs-owed and carries no fresh falsification-leg deposit — run the leg, then 'totem legs deposit --sha HEAD --from <findings.json>' (mmnto-ai/totem#2698, strict mode)"
-        exit 1
-      elif [ "$legs_status" != "0" ]; then
-        echo "[Totem] BLOCKED: the legs gate could not derive (totem legs gate exit status $legs_status) — fix the checkout and retry (strict mode)"
-        exit 1
-      fi
     else
       $TOTEM_CMD legs gate --advisory
+      legs_status=$?
+    fi
+    if [ "$legs_status" = "3" ]; then
+      echo "[Totem] BLOCKED: this push is legs-owed and carries no fresh falsification-leg deposit — run the leg, then 'totem legs deposit --sha HEAD --from <findings.json>' (mmnto-ai/totem#2698; strict mode, an agent seat, or hooks.legsOwed.enforce: block)"
+      exit 1
+    elif [ "$legs_status" = "2" ]; then
+      echo "[Totem] BLOCKED: the legs gate could not derive (totem legs gate exit status 2) — fix the checkout and retry (strict mode, an agent seat, or hooks.legsOwed.enforce: block)"
+      exit 1
+    elif [ "$legs_status" != "0" ] && [ "$legs_strict" = "1" ]; then
+      echo "[Totem] BLOCKED: the legs gate failed before deriving (totem legs gate exit status $legs_status) — fix the config or the CLI and retry (strict mode or an agent seat)"
+      exit 1
     fi
   else
     if [ "$is_agent" = "1" ] || [ "$TOTEM_HOOK_TIER" = "strict" ]; then
-      echo "[Totem] BLOCKED: this hook expects 'totem legs gate' (mmnto-ai/totem#2698) but the resolved CLI lacks it — 'npm i -g @mmnto/cli@latest' (strict mode)" >&2
+      echo "[Totem] BLOCKED: this hook expects 'totem legs gate' (mmnto-ai/totem#2698) but the resolved CLI lacks it — 'npm i -g @mmnto/cli@latest' (strict mode or an agent seat)" >&2
       exit 1
     else
       echo "[totem] Hook running without the legs gate (CLI predates 'totem legs'); 'npm i -g @mmnto/cli@latest' enables it." >&2
@@ -1073,16 +1339,25 @@ const OWNED_WHOLE_FILE_PREAMBLE_RE = /^#![^\n]*\n#[ \t]*$/;
 /** POSIX executable mode for git hooks (rwxr-xr-x). */
 const HOOK_EXECUTABLE_MODE = 0o755;
 /**
- * Write a hook file and mark it executable. On POSIX the chmod failure propagates
- * (Tenet 4 — a hook git cannot execute must fail loud, never silently report
- * `installed`). On Windows the exec bit is skipped explicitly: git-bash owns the
- * executable bit there, and NTFS has no POSIX mode to set.
+ * Write a hook file and mark it executable — ATOMICALLY (core's
+ * `writeFileAtomicSync`, the Tenet 4 user-file mutation helper, mmnto-ai/totem#2620):
+ * the bytes land in a same-directory temp, the mode is applied to the temp, and
+ * the rename comes last, so an interrupted install leaves the old hook or the new
+ * one and never a truncated file. That matters most on the attested-extension
+ * rewrite (mmnto-ai/totem#2753): the trailer is the consumer's own lines, which no
+ * template can regenerate (Greptile P1, mmnto-ai/totem#2760 round 1).
+ *
+ * On POSIX a mode failure propagates from the helper (a hook git cannot execute
+ * must fail loud, never silently report `installed`). On Windows the exec bit is
+ * skipped by the helper's own boundary: git-bash owns the executable bit there,
+ * and NTFS has no POSIX mode to set. Symlinked hooks keep their link identity
+ * (the helper writes through to the real path). A DANGLING symlinked hook is the
+ * one case the old in-place write handled differently: `fs.writeFileSync` followed
+ * the link and created its target, the helper throws ENOENT and leaves the link
+ * untouched — remove or re-point the link first. Declared, not defended.
  */
 function writeExecutableHook(hookPath, content) {
-    fs.writeFileSync(hookPath, content);
-    if (process.platform !== 'win32') {
-        fs.chmodSync(hookPath, HOOK_EXECUTABLE_MODE);
-    }
+    writeFileAtomicSync(hookPath, content, { mode: HOOK_EXECUTABLE_MODE });
 }
 /**
  * Whether an existing hook is a totem-OWNED whole file (generated verbatim by a
@@ -1104,21 +1379,153 @@ function writeExecutableHook(hookPath, content) {
  *     whitespace may follow the end marker).
  */
 export function isTotemOwnedWholeFile(content, marker, endMarker) {
+    const trailerStart = ownedTrailerStart(content, marker, endMarker);
+    if (trailerStart === undefined)
+        return false;
+    return content.slice(trailerStart).trim().length === 0;
+}
+/**
+ * The offset just past the totem end marker — where a trailer would begin — for a
+ * hook whose managed region OPENS the file and is BOUNDED. `undefined` when either
+ * rule fails: no start marker, user content before it (beyond a shebang + the start
+ * of the marker comment), or no end marker after it (the legacy-hook path).
+ *
+ * The one shared prefix/bound rule behind {@link isTotemOwnedWholeFile} and
+ * {@link isTotemOwnedWithAttestedTrailer} — the two differ ONLY in what they
+ * accept after this offset (mmnto-ai/totem#2753).
+ */
+function ownedTrailerStart(content, marker, endMarker) {
     const idx = content.indexOf(marker);
     if (idx === -1)
-        return false;
+        return undefined;
     const before = content.slice(0, idx);
     if (before.trim().length !== 0 && !OWNED_WHOLE_FILE_PREAMBLE_RE.test(before)) {
-        return false;
+        return undefined;
     }
     const end = content.indexOf(endMarker, idx + marker.length);
     // Start marker present but end marker missing → region cannot be bounded →
-    // not safe to whole-file overwrite without --force (also the legacy-hook path).
+    // not safe to rewrite without --force (also the legacy-hook path).
     if (end === -1)
+        return undefined;
+    return end + endMarker.length;
+}
+/**
+ * {@link ownedTrailerStart} as a BYTE offset into the raw file — the offset the
+ * block-rewrite arm slices the trailer at — or `undefined` when the managed region
+ * (start of file through the end marker) does not decode as UTF-8 losslessly.
+ *
+ * The string offset converts to a byte offset only if the region's re-encoded text
+ * equals its raw bytes; totem wrote the region, so it does, and the equality check
+ * PROVES it rather than assuming it. A region that fails it is not totem's text any
+ * more — an ANSI-editor save that turned the template's em dash into one `0x97`
+ * byte, say — so the installer reports that shape (`skipped-non-utf8`) and doctor
+ * classifies it (`non-utf8`) instead of either guessing an offset or prescribing a
+ * bare install that would decline (mmnto-ai/totem#2760 legs F9 and F13). The
+ * trailer's own bytes are never decoded by anything that writes them back.
+ */
+export function ownedTrailerByteStart(raw, marker, endMarker) {
+    const existing = raw.toString('utf-8');
+    const trailerStart = ownedTrailerStart(existing, marker, endMarker);
+    if (trailerStart === undefined)
+        return undefined;
+    const prefixBytes = Buffer.from(existing.slice(0, trailerStart), 'utf-8');
+    return raw.subarray(0, prefixBytes.length).equals(prefixBytes) ? prefixBytes.length : undefined;
+}
+/**
+ * A trailer (the text after a managed hook's end marker) is ATTESTED when its
+ * LEADING COMMENT RUN carries a full fork attestation — reason, owner and attested
+ * all present and non-empty AFTER TRIMMING; a whitespace-only value does not attest
+ * (mmnto-ai/totem#2753; the trim from mmnto-ai/totem#2760 round 1).
+ *
+ * The leading comment run is every line up to the first line that is neither blank
+ * nor a shell comment — i.e. up to the extension's first COMMAND. Blank lines inside
+ * the run are skipped. The attestation is core's `<!-- totem:fork … -->` marker
+ * (`parseForkMarker`), the same shape the parity detector reads, on a comment line:
+ *
+ *     (blank)
+ *     # [lc] docs-inject extension
+ *     # <!-- totem:fork reason="…" owner="satur8d" attested="2026-06-07" -->
+ *     sh "tools/git-hooks/pre-commit-docs-inject.sh"
+ *
+ * The run, not the first line: a real consumer labels its block before it signs it.
+ * That is the measured liquid-city shape — `tools/git-hooks/install.cjs` emits a
+ * `# [lc] <name> extension` line FIRST and the fork marker SECOND — and a
+ * first-line-only rule declined the very datum this slice was built from
+ * (mmnto-ai/liquid-city#1174).
+ *
+ * Two things do NOT attest, and both matter:
+ *   - A marker below the first command. An attestation buried under code vouches
+ *     for nothing above it, so the run ends at that command.
+ *   - A marker on a NON-comment line. `rm -rf / # <!-- totem:fork … -->` is a
+ *     command, not a signature; only a line whose trimmed text STARTS with `#` can
+ *     carry one.
+ *
+ * The marker must also sit on ONE line: `parseForkMarker` is applied per line here,
+ * so core's multi-line (dotAll) form of the marker is deliberately not in play.
+ *
+ * A BARE `totem:fork` marker — or one missing any of the three fields — is not
+ * attested either. That asymmetry with the parity detector (where a bare marker is
+ * enough to CLAIM a fork) is deliberate: carrying a consumer's lines through a
+ * managed-block rewrite is a maintenance promise, and a promise needs a name, a
+ * reason and a date.
+ */
+export function isAttestedTrailer(trailer) {
+    for (const line of trailer.split('\n')) {
+        const trimmed = line.trim();
+        // Blank lines sit inside the run — the measured shape opens with one.
+        if (trimmed.length === 0)
+            continue;
+        // The first command ends the run: nothing below it can vouch for it.
+        if (!trimmed.startsWith('#'))
+            return false;
+        const fork = parseForkMarker(line);
+        // Trimmed: core's parser captures the quoted value raw, so `reason=" "` would
+        // otherwise pass a length check — a promise with no name is not a promise
+        // (Greptile P2, mmnto-ai/totem#2760 round 1).
+        if (fork !== undefined &&
+            typeof fork.reason === 'string' &&
+            fork.reason.trim().length > 0 &&
+            typeof fork.owner === 'string' &&
+            fork.owner.trim().length > 0 &&
+            typeof fork.attested === 'string' &&
+            fork.attested.trim().length > 0) {
+            return true;
+        }
+    }
+    // Blank/whitespace-only, or a comment run with no full marker in it.
+    return false;
+}
+/**
+ * The mmnto-ai/totem#2406 owned-whole-file shape with ONE relaxation: the trailer may
+ * be non-blank if it is attested ({@link isAttestedTrailer}).
+ *
+ * The precondition for the in-place managed-block rewrite: totem still owns
+ * everything from the top of the file through the end marker, and what follows it is
+ * a consumer extension that named itself. Everything before the end marker is
+ * regenerated; everything after it is carried through byte-for-byte.
+ */
+export function isTotemOwnedWithAttestedTrailer(content, marker, endMarker) {
+    const trailerStart = ownedTrailerStart(content, marker, endMarker);
+    if (trailerStart === undefined)
         return false;
-    if (content.slice(end + endMarker.length).trim().length !== 0)
-        return false;
-    return true;
+    return isAttestedTrailer(content.slice(trailerStart));
+}
+/**
+ * The trailer as it must be re-attached after a regenerated managed block: the BYTES
+ * after `endMarker` with exactly ONE leading line terminator (`\r\n` or `\n`)
+ * removed. The canonical hook text already ends with the end marker's own
+ * terminator, so re-attaching the raw slice would duplicate it (the `upgradeReflexes`
+ * seam precedent in init.ts). Everything past that one terminator is untouched —
+ * and never decoded: the trailer is the consumer's own file, and a byte that does
+ * not round-trip UTF-8 must come back as itself (mmnto-ai/totem#2760 leg F9).
+ */
+function trailerTailAfterEndMarker(raw, trailerStart) {
+    const trailer = raw.subarray(trailerStart);
+    if (trailer[0] === 0x0d && trailer[1] === 0x0a)
+        return trailer.subarray(2);
+    if (trailer[0] === 0x0a)
+        return trailer.subarray(1);
+    return trailer;
 }
 /**
  * Install a single git hook with idempotency and chain preservation.
@@ -1134,11 +1541,28 @@ export function isTotemOwnedWholeFile(content, marker, endMarker) {
  * templates now emit one. Drift-repair fires only when the caller threads the end
  * marker AND the on-disk hook carries it — a legacy pre-end-marker hook declines to
  * `exists` and takes one `totem hook install --force`.
+ *
+ * Since mmnto-ai/totem#2753 a THIRD arm sits between drift-repair and the decline: a
+ * file totem owns through its end marker whose trailer is an ATTESTED `totem:fork`
+ * extension ({@link isTotemOwnedWithAttestedTrailer}) has its managed block rewritten
+ * IN PLACE (`block-rewritten`) — the canonical text plus the existing trailer,
+ * byte-identical past the seam. That is the liquid-city shape: a consumer appending
+ * its own blocks after totem's end marker never received a managed-hook upgrade
+ * through bare `totem init` (measured at `@mmnto/cli` 1.123.0,
+ * mmnto-ai/liquid-city#1174). An UNATTESTED trailer still declines to `exists`,
+ * unchanged. `--force` is untouched by all of this: it overwrites the WHOLE file,
+ * trailer included.
  */
 export function installGitHook(hooksDir, hookName, hookContent, marker, force, endMarker) {
     const hookPath = path.join(hooksDir, hookName);
     if (fs.existsSync(hookPath)) {
-        const existing = fs.readFileSync(hookPath, 'utf-8');
+        // Raw bytes are the user's file; the decoded text serves the PROBES only
+        // (markers, shebang, terminator). Every write below that carries the user's
+        // content carries it as BYTES — a hook that does not round-trip UTF-8 must
+        // never come back with U+FFFD where its bytes were (the mmnto-ai/totem#2620
+        // eject ruling, re-learned on mmnto-ai/totem#2760 leg F8).
+        const raw = fs.readFileSync(hookPath);
+        const existing = raw.toString('utf-8');
         if (existing.includes(marker)) {
             if (force) {
                 // Force overwrite — replace the entire hook with the new content
@@ -1157,6 +1581,34 @@ export function installGitHook(hooksDir, hookName, hookContent, marker, force, e
                 writeExecutableHook(hookPath, hookContent);
                 return 'overwritten';
             }
+            // In-place managed-block rewrite (mmnto-ai/totem#2753): totem owns the file
+            // through its end marker and what follows is an ATTESTED `totem:fork`
+            // extension. Regenerate the block, carry the trailer through byte-for-byte.
+            // The currency compare here is the RECOMPOSED file, not the whole existing
+            // one — an attested-trailer hook whose block already equals the canonical is
+            // current (`exists`, no write), which is what makes a second bare run a no-op.
+            if (endMarker !== undefined && isTotemOwnedWithAttestedTrailer(existing, marker, endMarker)) {
+                // "Byte-for-byte" is literal: the trailer is sliced from the RAW file at the
+                // byte offset `ownedTrailerByteStart` PROVES — the region above the
+                // extension (shebang line and managed block) re-encodes to its own bytes.
+                // That is the ONE marker scan, shared with doctor (fold F11's rule, one
+                // implementation); the predicate above ran it too, and a second run on the
+                // same string is cheaper than a second implementation. A region that does
+                // not round-trip is not ours to rewrite — and not something to stay silent
+                // about: the skip is REPORTED, and doctor senses the same shape with the
+                // same predicate (legs F13, F16). The trailer's bytes are never decoded.
+                const trailerByteStart = ownedTrailerByteStart(raw, marker, endMarker);
+                if (trailerByteStart === undefined)
+                    return 'skipped-non-utf8';
+                const rewritten = Buffer.concat([
+                    Buffer.from(hookContent, 'utf-8'),
+                    trailerTailAfterEndMarker(raw, trailerByteStart),
+                ]);
+                if (rewritten.equals(raw))
+                    return 'exists';
+                writeExecutableHook(hookPath, rewritten);
+                return 'block-rewritten';
+            }
             return 'exists';
         }
         // Guard: do not append bash syntax to non-shell hooks (Node, Python, etc.)
@@ -1164,12 +1616,16 @@ export function installGitHook(hooksDir, hookName, hookContent, marker, force, e
         if (firstLine.startsWith('#!') && !SHELL_SHEBANG_RE.test(firstLine)) {
             return 'skipped-non-shell';
         }
-        // Append to existing hook — preserve user's existing hooks
+        // Append to existing hook — preserve user's existing hooks. One atomic
+        // replacement of the whole file (their RAW bytes + ours), not an append: an
+        // interrupted append leaves a hook truncated mid-block, which git still
+        // runs (mmnto-ai/totem#2760 round 1, leg F2). The helper keeps the user's
+        // file mode and writes through a symlink to its real path.
         const separator = existing.endsWith('\n') ? '\n' : '\n\n';
         const appendBlock = hookContent
             .replace(/^#!\/bin\/sh\n/, '') // Strip shebang when appending
             .trimStart();
-        fs.appendFileSync(hookPath, separator + appendBlock);
+        writeFileAtomicSync(hookPath, Buffer.concat([raw, Buffer.from(separator + appendBlock, 'utf-8')]));
         return 'appended';
     }
     // Create new hook
@@ -1223,8 +1679,17 @@ export async function installEnforcementHooks(cwd, rl, options) {
     // while every hook writer resolves at the git root: a pre-existing split this
     // slice names and does not close.
     const render = await resolveHookRenderOptions(gitRoot, { tier: options?.tier });
-    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(render), TOTEM_PRECOMMIT_MARKER, undefined, TOTEM_PRECOMMIT_END);
-    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook(render), TOTEM_PREPUSH_MARKER, undefined, TOTEM_PREPUSH_END);
+    // Render each hook at the tier it is entitled to keep (mmnto-ai/totem#2753 fold
+    // F4): nothing pinned + an installed `--strict` hook → strict, not a silent
+    // downgrade to standard.
+    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook({
+        ...render,
+        tier: tierForHook(hooksDir, 'pre-commit', TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END, render),
+    }), TOTEM_PRECOMMIT_MARKER, undefined, TOTEM_PRECOMMIT_END);
+    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook({
+        ...render,
+        tier: tierForHook(hooksDir, 'pre-push', TOTEM_PREPUSH_MARKER, TOTEM_PREPUSH_END, render),
+    }), TOTEM_PREPUSH_MARKER, undefined, TOTEM_PREPUSH_END);
     // Warn about non-shell hooks that Totem cannot safely append to
     if (preCommit === 'skipped-non-shell') {
         console.error('[Totem] Warning: pre-commit hook uses a non-shell interpreter. Manually integrate branch protection into your existing hook.');
@@ -1232,6 +1697,15 @@ export async function installEnforcementHooks(cwd, rl, options) {
     if (prePush === 'skipped-non-shell') {
         console.error('[Totem] Warning: pre-push hook uses a non-shell interpreter. Manually add: totem lint');
     }
+    // A skip with its reason, never a silent "already installed" (mmnto-ai/totem#2760 leg F13).
+    for (const [name, action] of [
+        ['pre-commit', preCommit],
+        ['pre-push', prePush],
+    ]) {
+        if (action === 'skipped-non-utf8') {
+            console.error(`[Totem] Skipped ${name} hook: the region above its extension (shebang line and managed block) does not decode as UTF-8, so it was left byte-identical. Re-save the hook as UTF-8 and re-run, or take \`totem hook install --force\` (rewrites the whole file and drops your extension).`);
+        }
+    }
     return { preCommit, prePush };
 }
 export async function installHooksCommand() {
@@ -1293,8 +1767,17 @@ export async function installHooksNonInteractive(cwd, force, options) {
         console.error(HOOKS_DIR_UNRESOLVED_MSG);
         return null;
     }
-    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook(render), TOTEM_PRECOMMIT_MARKER, force, TOTEM_PRECOMMIT_END);
-    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook(render), TOTEM_PREPUSH_MARKER, force, TOTEM_PREPUSH_END);
+    // Same entitlement rule as the init path (mmnto-ai/totem#2753 fold F4) — and it
+    // has to hold HERE above all, because `totem hook install` is the bare command
+    // the doctor's own stale-block remedy sends people to.
+    const preCommit = installGitHook(hooksDir, 'pre-commit', buildPreCommitHook({
+        ...render,
+        tier: tierForHook(hooksDir, 'pre-commit', TOTEM_PRECOMMIT_MARKER, TOTEM_PRECOMMIT_END, render),
+    }), TOTEM_PRECOMMIT_MARKER, force, TOTEM_PRECOMMIT_END);
+    const prePush = installGitHook(hooksDir, 'pre-push', buildPrePushHook({
+        ...render,
+        tier: tierForHook(hooksDir, 'pre-push', TOTEM_PREPUSH_MARKER, TOTEM_PREPUSH_END, render),
+    }), TOTEM_PREPUSH_MARKER, force, TOTEM_PREPUSH_END);
     const postMergeContent = buildHookContent(render);
     const postMerge = installGitHook(hooksDir, 'post-merge', postMergeContent, TOTEM_HOOK_MARKER, force, TOTEM_HOOK_END);
     const postCheckoutContent = buildPostCheckoutHookContent(render);
@@ -1411,9 +1894,21 @@ export async function hooksCommand(opts) {
                         ? `[Totem] Force-overwritten ${name} hook.`
                         : `[Totem] Drift-repaired ${name} hook (totem-owned bounded region).`);
                     break;
+                case 'block-rewritten':
+                    // Distinct from the whole-file line above: this write REGENERATED the
+                    // managed block and left everything after the end marker alone. Saying so
+                    // is the point — a consumer that extends its hooks needs to read, from the
+                    // summary, that its extension survived (mmnto-ai/totem#2753).
+                    console.error(`[Totem] Drift-repaired ${name} hook (managed block rewritten in place; the attested extension after its end marker carried through unchanged).`);
+                    break;
                 case 'skipped-non-shell':
                     console.error(`[Totem] Warning: ${name} hook uses a non-shell interpreter. Integrate manually.`);
                     break;
+                case 'skipped-non-utf8':
+                    // The eject precedent (mmnto-ai/totem#2620): a skip is reported with its
+                    // reason and the file is left byte-identical — never "already installed".
+                    console.error(`[Totem] Skipped ${name} hook: the region above its extension (shebang line and managed block) does not decode as UTF-8, so it was left byte-identical. Re-save the hook as UTF-8 and re-run, or take --force (rewrites the whole file and drops your extension).`);
+                    break;
             }
         }
     }
@@ -1753,10 +2248,21 @@ export async function upgradePrePushHookIfNeeded(cwd) {
         const hookPath = path.join(hooksDir, 'pre-push');
         if (!fs.existsSync(hookPath))
             return false;
-        const content = fs.readFileSync(hookPath, 'utf-8');
-        // Only upgrade hooks that Totem owns (have our marker)
+        const rawContent = fs.readFileSync(hookPath);
+        const content = rawContent.toString('utf-8');
+        // Only upgrade hooks that Totem owns (have our marker) — block presence FIRST,
+        // the order eject.ts ruled, so the two sites read alike even though this one
+        // returns a bare `false` either way.
         if (!content.includes(TOTEM_PREPUSH_MARKER))
             return false;
+        // The splice below is text on both sides of the block, so it is byte-exact
+        // only when the whole file decoded losslessly. A hook that does not
+        // round-trip UTF-8 is declined here — this upgrader's ruled posture is a
+        // silent `false` (mmnto-ai/totem#2692 N4), and declining beats writing U+FFFD
+        // over a user's bytes (mmnto-ai/totem#2620's eject ruling, mmnto-ai/totem#2760
+        // leg F9). Such a hook keeps its old block and takes `totem hook install --force`.
+        if (!Buffer.from(content, 'utf-8').equals(rawContent))
+            return false;
         // Already on the new stateless format — no upgrade needed.
         // SAFETY INVARIANT: old hooks (pre-verify-manifest) have a single top-level
         // if/fi block and no agent detection. The parser below relies on this — it
@@ -1799,6 +2305,7 @@ export async function upgradePrePushHookIfNeeded(cwd) {
         if (endOffset === -1)
             return false;
         const blockEnd = markerIdx + endOffset;
+        // totem-context: mmnto-ai/totem#2753 — this upgrader is unreachable for any hook carrying TOTEM_HOOK_TIER (the verify-manifest guard above skips every current template), so it renders from config alone; if that guard ever changes, route through tierForHook.
         const render = await resolveHookRenderOptions(gitRoot);
         // Build the replacement block (strip shebang — we're splicing into existing file)
         const newBlock = buildPrePushHook(render)
@@ -1808,13 +2315,10 @@ export async function upgradePrePushHookIfNeeded(cwd) {
         const before = content.slice(0, markerIdx);
         const after = content.slice(blockEnd);
         const upgraded = before + newBlock.trimEnd() + after;
-        fs.writeFileSync(hookPath, upgraded);
-        try {
-            fs.chmodSync(hookPath, 0o755);
-        }
-        catch {
-            // chmod may fail on Windows — hooks still work via git bash
-        }
+        // The splice keeps the user's lines on BOTH sides of the block — the exact
+        // shape Greptile P1 named on the attested-extension arm — so it takes the same
+        // atomic, executable write (mmnto-ai/totem#2760 round 1, leg F4).
+        writeExecutableHook(hookPath, upgraded);
         return true;
     }
     catch {