@mmnto/cli 1.124.0 → 2.0.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,9 +937,12 @@ 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 = [];
+function hasBodyAfter(start, level) {
   for (let i = start + 1; i < lines.length; i++) {
-    if (isHeading(lines[i])) return false;
+    const n = headingLevel(lines[i]);
+    if (n > 0 && n <= level) return false;
+    if (n > 0) continue;
     if (lines[i].trim().length > 0) return true;
   }
   return false;
@@ -825,12 +951,19 @@ 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; } }
+    let matchedAs = "";
+    if (at < 0) {
+      const want = stripParen(heading);
+      for (let i = 0; i < lines.length; i++) { if ([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) block("the draft in " + shownFile + " is missing heading " + safe(heading));
-    if (!hasBodyAfter(at)) block("the draft in " + shownFile + " has an empty heading " + safe(heading));
+    const shownHeading = safe(heading) + (matchedAs.length > 0 ? " (matched as " + matchedAs + ")" : "");
+    if (!hasBodyAfter(at, headingLevel(lines[at]))) block("the draft in " + shownFile + " has an empty heading " + shownHeading);
   }
 } 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 = headingLevel(lines[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 +971,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 +981,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)"
@@ -1073,16 +1207,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 +1247,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 +1409,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 +1449,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 +1484,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 +1547,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 +1565,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 +1635,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 +1762,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 +2116,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 +2173,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 +2183,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 {