@mutmutco/kilo-plugin 3.83.0 → 3.85.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/kilo-plugin",
-  "version": "3.83.0",
+  "version": "3.85.0",
   "description": "MMI workflow skills and org gates delivery.",
   "author": {
     "name": "MMI Future",

package/scripts/hook-io.mjs

@@ -6,10 +6,15 @@ import { createInterface } from 'node:readline';
 
 /**
  * Read all stdin lines and JSON-parse them.
+ * #4118: the shared runner now runs a gate IN-PROCESS and has already drained stdin, so it passes the
+ * buffered payload in. Parsing it here keeps ONE contract — same throw on unreadable input, so every
+ * gate's fail-open/fail-closed branch is reached identically whether it was spawned or imported.
+ * @param {Buffer|string} [buffered] Payload already read by the caller; stdin is read when absent.
  * @returns {Promise<unknown>} Parsed JSON payload.
  * @throws {Error} On readline or JSON parse failure.
  */
-export async function readHookInput() {
+export async function readHookInput(buffered) {
+  if (buffered !== undefined) return JSON.parse(Buffer.isBuffer(buffered) ? buffered.toString('utf8') : String(buffered));
   const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
   const lines = [];
   for await (const line of rl) lines.push(line);

package/scripts/hook-run.mjs

@@ -6,11 +6,56 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { hookGate, hookSurface } from './hook-policy.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 
+// #4118: every fire used to be THREE process boots — launcher, this runner, then a SECOND node for the
+// gate script. The gate is ordinary ESM in the same tree, so it is imported here instead; measured
+// against the live 4,002-fire log that second boot was ~70ms of the ~226ms median, on every fire of
+// all three gates. The gate's own logic was 10-25ms of it.
+//
+// Losing the child process also loses the isolation it provided, so the boundary is rebuilt explicitly
+// and the five things the spawn used to guarantee are each restored by hand:
+//   - stdout/stderr are captured (the child's pipes) rather than reaching the host raw, and the
+//     captured stdout is then REDUCED to the one decision envelope before it leaves this runner (see
+//     decisionEnvelope below — capture alone never bought that, and did not on base either: an injected
+//     `process.stdout.write` inside a gate reaches the host ahead of the deny, byte-identical spawned or
+//     imported, and the host's JSON.parse fails on the stream). What is guaranteed is narrower than "a
+//     stray write can never be read as a decision": stdout that cannot be reduced to exactly ONE decision
+//     envelope is not forwarded at all, and on a fail-closed gate that is a gate FAULT (#4016) — the
+//     fallback deny runs. So on a gate's DENY path a stray write can suppress the gate's own answer (the
+//     fallback's reason replaces it) but cannot weaken the outcome. On a gate's ALLOW path it is not
+//     contained: with no carrier of the gate's own to outrank it, a stray write carrying a well-formed
+//     allow envelope is elected and forwarded, turning "no decision, defer to the host's prompt" into an
+//     explicit auto-approve — measured, and unchanged from base and from 8730324a, so this is the shape
+//     #4016 did NOT close. Measured on vault-edit and command-ladder, all ten fault
+//     shapes in the #4016 matrix deny, and four consecutive fires of the unterminated-stray shape all deny
+//     — the gate still records its own success, so that shape never reaches the #2598 breaker threshold.
+//     The breaker is otherwise unchanged: three consecutive GENUINE crashes still degrade fail-open behind
+//     its warning banner;
+//   - process.exit is trapped (the child's exit code) so a gate that exits mid-run yields a STATUS
+//     instead of taking the whole hook process — and with it the fail-closed fallback — down with it;
+//   - unhandled rejections and uncaught exceptions are trapped for the same reason: those are the two
+//     faults an `await` cannot see, and untrapped they kill the RUNNER (see trapAsyncFaults below);
+//   - process.env is set to the gate's effective env before the import, because the gates read
+//     surface-dependent modes at MODULE LOAD, and restored after;
+//   - the import is cache-busted per fire so a second run in one process re-reads those module-level
+//     constants exactly as a fresh child would.
+// Anything that escapes all of that lands in the catch as status 1, which is the same signal a crashed
+// child gave: fail-CLOSED for command-ladder and vault-edit (deny-gate-crash.mjs), fail-open for
+// secret-output. See scripts/hook-policy.mjs for the per-gate posture.
+let fireCount = 0;
+
+/** Thrown in place of a gate's process.exit so the runner keeps ownership of the exit code. */
+class GateExit extends Error {
+  constructor(code) {
+    super(`gate exited ${code}`);
+    this.code = code;
+  }
+}
+
 export function parseHookArgv(argv) {
   const parsed = { surface: '', gate: '' };
   for (let index = 0; index < argv.length; index += 1) {
@@ -41,14 +86,28 @@ export function payloadMeta(input) {
   }
 }
 
+/** Codex's spelling of the one shell tool. The redactor's UPDATABLE_TOOLS is the Claude vocabulary, so
+ *  the secret-output matcher can only equal it once the host name is translated — untranslated, a Codex
+ *  `shell` detection took the "cannot be masked for this TOOL" arm and blamed the tool for what is a
+ *  HOST limit (#4118). Translated for secret-output ONLY: the PreToolUse shell gates match these names
+ *  directly and pick a dialect from them (scripts/pretooluse-shell-gates.mjs). */
+export const CODEX_SHELL_TOOLS = Object.freeze(['shell', 'local_shell']);
+
 function normalizeInput(surface, gate, input) {
-  if (surface !== 'cursor') return input;
+  const codexShell = surface === 'codex' && gate === 'secret-output';
+  if (surface !== 'cursor' && !codexShell) return input;
   try {
     const payload = JSON.parse(Buffer.from(input).toString('utf8'));
     if (!payload || typeof payload !== 'object') return input;
-    if (payload.tool_name === 'Shell') {
+    if (payload.tool_name === 'Shell' || (codexShell && CODEX_SHELL_TOOLS.includes(payload.tool_name))) {
+      // Keep the name the HOST fired for the trace to read back. Translated-only, activity.jsonl logged
+      // BOTH Codex spellings as `tool: "PowerShell"` — a tool Codex does not have, and the two names
+      // became indistinguishable in the one log doctor, the Stop summary and this gate's own
+      // justification are counted from. secret-redact.mjs prefers this field when stamping `tool`.
+      payload.mmi_host_tool_name = payload.tool_name;
       payload.tool_name = process.platform === 'win32' ? 'PowerShell' : 'Bash';
     }
+    if (surface !== 'cursor') return Buffer.from(JSON.stringify(payload));
     if (!payload.session_id && typeof payload.conversation_id === 'string') {
       payload.session_id = payload.conversation_id;
     }
@@ -61,6 +120,43 @@ function normalizeInput(surface, gate, input) {
   }
 }
 
+/** Split a gate's stdout into the ONE decision envelope and everything else. Every gate writes at most
+ *  one envelope and always as a single line of JSON (pretooluse-shell-gates.mjs, vault-edit-gate.mjs,
+ *  secret-redact.mjs) — the same shape .kilo-plugin/server.mjs already reads back off this launcher.
+ *  Stray text is moved to stderr rather than dropped: still a symptom worth seeing, just not somewhere a
+ *  decision can be read from.
+ *
+ *  #4016: "the first line beginning with `{`" was the wrong test and measurably fails OPEN on a
+ *  fail-CLOSED gate in two shapes. With a `.env` Write driven through vault-edit and the write injected at
+ *  the gate entry: a stray line that is ITSELF JSON (`{"mmi_debug":"noise"}`) was elected the envelope and
+ *  the real deny went to stderr — the host then parses a well-formed NON-decision and allows, which base
+ *  could not do because base's stream did not parse at all; and a stray write with no trailing newline
+ *  merges with the envelope into one line that starts with `h`, so no line matched, stdout came back EMPTY
+ *  and the deny was gone. So the line is elected by PARSING it, `hookSpecificOutput` carriers first, and
+ *  the result reports `malformed` when stdout exists but cannot be reduced to exactly one — which
+ *  runPolicyGate treats as a gate fault, i.e. the fail-closed fallback for vault-edit/command-ladder. */
+function decisionEnvelope(stdout) {
+  if (!stdout.trim()) return { envelope: '', stray: '', malformed: false };
+  const lines = stdout.split(/\r?\n/);
+  const objects = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].trim()) continue;
+    let value;
+    try {
+      value = JSON.parse(lines[index]);
+    } catch {
+      continue;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) objects.push({ index, value });
+  }
+  const carriers = objects.filter(({ value }) => value.hookSpecificOutput !== undefined);
+  const candidates = carriers.length ? carriers : objects;
+  if (candidates.length !== 1) return { envelope: '', stray: stdout, malformed: true };
+  const at = candidates[0].index;
+  const stray = lines.filter((_, index) => index !== at).join('\n').trim();
+  return { envelope: `${lines[at]}\n`, stray: stray ? `${stray}\n` : '', malformed: false };
+}
+
 function adaptOutput(surface, stdout) {
   if (surface !== 'cursor' || !stdout.trim()) return stdout;
   try {
@@ -84,12 +180,12 @@ function childEnv(surface, input, env) {
   };
 }
 
-function inlineDeny(surface, gate, root) {
+function inlineDeny(surface, gate, root, fault = `its fail-closed fallback is missing from the plugin install at ${root}`) {
   return `${JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'PreToolUse',
       permissionDecision: 'deny',
-      permissionDecisionReason: `MMI ${gate} gate could not run on ${surface} and its fail-closed fallback is missing from the plugin install at ${root}. Reinstall the MMI plugin, or set MMI_GATES_FAIL_OPEN=1 to proceed unguarded.`,
+      permissionDecisionReason: `MMI ${gate} gate could not run on ${surface} and ${fault}. Reinstall the MMI plugin, or set MMI_GATES_FAIL_OPEN=1 to proceed unguarded.`,
     },
   })}\n`;
 }
@@ -110,7 +206,126 @@ function invoke(target, args, input, env, timeoutMs) {
   };
 }
 
-export function runPolicyGate({ surface, gate: gateId, input = Buffer.alloc(0), env = process.env, here = HERE }) {
+/** Point process.env at the gate's effective env for one in-process run, then put it back. */
+function applyProcessEnv(env) {
+  if (env === process.env) return () => {};
+  const prior = { ...process.env };
+  const sync = (target) => {
+    for (const key of Object.keys(process.env)) if (!(key in target)) delete process.env[key];
+    for (const [key, value] of Object.entries(target)) {
+      if (value === undefined) delete process.env[key];
+      else if (process.env[key] !== value) process.env[key] = value;
+    }
+  };
+  sync(env);
+  return () => sync(prior);
+}
+
+/** Buffer everything the gate writes, the way the child's pipes used to. */
+function captureStdio() {
+  const chunks = { stdout: [], stderr: [] };
+  const prior = { stdout: process.stdout.write, stderr: process.stderr.write };
+  const sink = (name) => function write(chunk, encoding, callback) {
+    chunks[name].push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+    const done = typeof encoding === 'function' ? encoding : callback;
+    if (typeof done === 'function') done();
+    return true;
+  };
+  process.stdout.write = sink('stdout');
+  process.stderr.write = sink('stderr');
+  return () => {
+    process.stdout.write = prior.stdout;
+    process.stderr.write = prior.stderr;
+    return { stdout: chunks.stdout.join(''), stderr: chunks.stderr.join('') };
+  };
+}
+
+/** The child's `timeout` option: a gate that never settles must not hold the turn open. The timer is
+ *  deliberately NOT unref'd — an unref'd timer lets the event loop drain when the gate settles nothing
+ *  and holds no handle, and the runner then exits 0 with no output, which is fail-OPEN. clearTimeout in
+ *  the `finally` is what keeps it from holding the loop open on the ordinary path. */
+function withTimeout(promise, timeoutMs) {
+  if (!timeoutMs) return promise;
+  return new Promise((settle, fail) => {
+    const timer = setTimeout(() => fail(new Error(`gate exceeded ${timeoutMs}ms`)), timeoutMs);
+    promise.then(settle, fail).finally(() => clearTimeout(timer));
+  });
+}
+
+/**
+ * The child process absorbed a gate's ASYNC faults — a detached rejection or a throw from a timer
+ * crashed the child, the runner read status 1, and the fail-closed fallback ran. In-process those two
+ * faults reach the runner's own default handler and kill it: measured against 1326c2db, a detached
+ * rejection inside vault-edit-gate left the runner at exit 1 with NO stdout, and a hook that exits 1
+ * is a non-blocking error on Claude Code, so the tool call proceeds unguarded. `await` cannot see
+ * either fault, so the only place to catch them is the process handlers, for the length of the run.
+ * Prior handlers are saved and restored: a host that embeds runPolicyGate keeps its own.
+ */
+function trapAsyncFaults() {
+  let onFault = () => {};
+  const fault = new Promise((_, fail) => {
+    onFault = (err) => fail(err instanceof Error ? err : new Error(String(err)));
+  });
+  // A fault that lands after the gate already settled has nothing racing it; swallow it here rather
+  // than let the rejection this function created become the next unhandled rejection.
+  fault.catch(() => {});
+  const prior = {
+    unhandledRejection: process.rawListeners('unhandledRejection'),
+    uncaughtException: process.rawListeners('uncaughtException'),
+  };
+  for (const event of Object.keys(prior)) {
+    process.removeAllListeners(event);
+    process.on(event, onFault);
+  }
+  return {
+    fault,
+    release() {
+      for (const [event, listeners] of Object.entries(prior)) {
+        process.removeAllListeners(event);
+        for (const listener of listeners) process.on(event, listener);
+      }
+    },
+  };
+}
+
+async function invokeInProcess(target, input, env, timeoutMs) {
+  const restoreEnv = applyProcessEnv(env);
+  const drain = captureStdio();
+  const faults = trapAsyncFaults();
+  const priorExit = process.exit;
+  process.exit = (code) => {
+    throw new GateExit(typeof code === 'number' ? code : 0);
+  };
+  let status = 0;
+  let error;
+  let legacy = false;
+  try {
+    const gateModule = await Promise.race([
+      faults.fault,
+      import(`${pathToFileURL(target).href}?mmi-hook-fire=${(fireCount += 1)}`),
+    ]);
+    // A gate from before #4118 is still a runnable script with its own self-run guard. Treating the
+    // missing export as a crash made every Edit/Write/Bash deny under the version skew the plugin's
+    // own `upgrade.mechanism: reinstall` creates (installed cache older than the tree); the spawn is
+    // the compatibility path, not a fallback for failure.
+    if (typeof gateModule.runHookGate !== 'function') legacy = true;
+    else await withTimeout(Promise.race([faults.fault, gateModule.runHookGate({ input })]), timeoutMs);
+  } catch (err) {
+    if (err instanceof GateExit) status = err.code;
+    else {
+      status = 1;
+      error = err;
+    }
+  } finally {
+    process.exit = priorExit;
+    faults.release();
+  }
+  const { stdout, stderr } = drain();
+  restoreEnv();
+  return { status, stdout, stderr, error, legacy };
+}
+
+export async function runPolicyGate({ surface, gate: gateId, input = Buffer.alloc(0), env = process.env, here = HERE }) {
   const gate = hookGate(gateId);
   hookSurface(surface);
   const root = pluginRoot(surface, env, here);
@@ -122,24 +337,48 @@ export function runPolicyGate({ surface, gate: gateId, input = Buffer.alloc(0),
   if (!existsSync(target)) {
     result = { status: 1, stdout: '', stderr: `[mmi-${surface}-hook] ${gate.script} not found under ${root}\n` };
   } else {
-    result = invoke(target, [], normalizedInput, effectiveEnv, gate.timeoutMs);
+    result = await invokeInProcess(target, normalizedInput, effectiveEnv, gate.timeoutMs);
+    if (result.legacy) result = invoke(target, [], normalizedInput, effectiveEnv, gate.timeoutMs);
     if (result.status === 0 || result.status === 2) {
-      return { ...result, stdout: adaptOutput(surface, result.stdout) };
+      const { envelope, stray, malformed } = decisionEnvelope(result.stdout);
+      if (!malformed) {
+        return { ...result, stdout: adaptOutput(surface, envelope), stderr: `${result.stderr}${stray}` };
+      }
+      // #4016: the gate exited cleanly but its stdout does not reduce to one decision. The runner cannot
+      // tell "allowed, then printed junk" from "denied, and the deny got mangled" — the second is exactly
+      // what an unterminated stray write produces — so this is a gate fault, not an allow.
+      result = { ...result, status: 1, stdout: '', stderr: `${result.stderr}${stray}` };
+      result.stderr += `[mmi-${surface}-hook] ${gate.script} wrote stdout with no single decision envelope\n`;
+    } else {
+      result.stderr += `[mmi-${surface}-hook] ${gate.script} exited ${result.status}`;
+      result.stderr += result.error ? `: ${result.error.message}\n` : '\n';
     }
-    result.stderr += `[mmi-${surface}-hook] ${gate.script} exited ${result.status}\n`;
   }
 
   if (gate.failure === 'open') return { ...result, status: 0 };
 
+  // The fallback deliberately keeps its own process. Whatever just failed did so INSIDE this one, so a
+  // fail-closed deny must not be computed by the same module registry and globals that produced it.
   const crashGate = join(root, 'scripts', 'deny-gate-crash.mjs');
   if (!existsSync(crashGate)) {
     return { status: 0, stdout: inlineDeny(surface, gate.fallbackGate, root), stderr: result.stderr };
   }
   const fallback = invoke(crashGate, [gate.fallbackGate], normalizedInput, effectiveEnv, gate.timeoutMs);
+  const { envelope, stray, malformed } = decisionEnvelope(fallback.stdout);
+  // An EMPTY fallback stdout is intentional (breaker open, or MMI_GATES_FAIL_OPEN) and stays empty;
+  // `malformed` is the other case — the fallback itself emitted something unreadable — and that must not
+  // become an allow either (#4016).
+  if (malformed) {
+    return {
+      status: 0,
+      stdout: inlineDeny(surface, gate.fallbackGate, root, 'its fail-closed fallback wrote no readable decision'),
+      stderr: `${result.stderr}${fallback.stderr}${stray}`,
+    };
+  }
   return {
     ...fallback,
-    stdout: adaptOutput(surface, fallback.stdout),
-    stderr: `${result.stderr}${fallback.stderr}`,
+    stdout: adaptOutput(surface, envelope),
+    stderr: `${result.stderr}${fallback.stderr}${stray}`,
   };
 }
 
@@ -151,11 +390,11 @@ function readStdin() {
   }
 }
 
-export function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2)) {
   const { surface, gate } = parseHookArgv(argv);
   let result;
   try {
-    result = runPolicyGate({ surface, gate, input: readStdin() });
+    result = await runPolicyGate({ surface, gate, input: readStdin() });
   } catch (error) {
     process.stderr.write(`[mmi-hook] ${error.message}\n`);
     process.exit(1);
@@ -167,4 +406,9 @@ export function main(argv = process.argv.slice(2)) {
 
 // Codex may import this file from a replacement cache while process.argv[1] still names the deleted
 // cache path captured when the session loaded. Match the stable relative suffix, not URL identity.
-if (process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('scripts/hook-run.mjs')) main();
+if (process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('scripts/hook-run.mjs')) {
+  main().catch((error) => {
+    process.stderr.write(`[mmi-hook] ${error && error.message}\n`);
+    process.exit(1);
+  });
+}

package/scripts/hook-trace.mjs

@@ -12,9 +12,8 @@
 // back to a per-cwd tmpdir path outside a repo so the trace still works anywhere. Fail-soft always:
 // the trace must never crash a turn or block a tool call.
 import { createHash } from 'node:crypto';
-import { execFileSync } from 'node:child_process';
-import { appendFileSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 
 const DEFAULT_SURFACE = 'claude';
@@ -54,10 +53,60 @@ function fallbackPath(cwd) {
   return join(tmpdir(), 'mmi-cli', hash, 'hooks', 'activity.jsonl');
 }
 
+// #4118: resolving the repo-local path used to shell out to `git rev-parse --git-path` — a fresh
+// process on EVERY hook fire, 4,002 of them in the sampled window, so memoising inside the process
+// would have saved nothing. Re-measured with the exact call it replaced, 25 samples in each of three
+// checkouts: median 24.4/25.2/27.3ms, max 48.3/49.0/51.3ms. (An earlier note here quoted the ~49ms tail
+// as the per-fire rate; it is roughly twice the median.) The answer is a pure function of the .git
+// layout, so it is read off the filesystem instead. This is the resolution cli/src/repo-runtime-state.ts
+// already performs for the CLI half of the same log; the two mirrors now agree by construction rather
+// than by two different mechanisms happening to land on the same path.
+//
+// Two layouts, both of which `--git-path` answers identically: a `.git` DIRECTORY (ordinary checkout),
+// and a `.git` FILE naming a private gitdir (a linked worktree — this org's normal working state —
+// or a submodule, where the named path may be relative). Unlike the CLI mirror this walks UP, because a
+// hook's cwd is the session's cwd and may sit below the repo root. A bare repo, where the cwd IS the
+// gitdir, is not resolved: hooks do not run there, and the tmpdir fallback below still gives a log.
+const GIT_DIR_MEMO = new Map();
+
+function gitDir(cwd, env) {
+  if (env.GIT_DIR) return resolve(cwd, env.GIT_DIR);
+  if (GIT_DIR_MEMO.has(cwd)) return GIT_DIR_MEMO.get(cwd);
+  let dir = resolve(cwd);
+  let found = '';
+  for (;;) {
+    const dotGit = join(dir, '.git');
+    let stats;
+    try {
+      stats = statSync(dotGit);
+    } catch {
+      stats = null;
+    }
+    if (stats?.isDirectory()) {
+      found = dotGit;
+      break;
+    }
+    if (stats?.isFile()) {
+      try {
+        const named = /^gitdir:\s*(.+)$/im.exec(readFileSync(dotGit, 'utf8').trim())?.[1]?.trim();
+        if (named) found = isAbsolute(named) ? named : resolve(dir, named);
+      } catch {
+        /* unreadable .git file — fall through to the tmpdir fallback */
+      }
+      break;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  GIT_DIR_MEMO.set(cwd, found);
+  return found;
+}
+
 /**
  * Resolve the hook-activity log path for a working directory.
- * Prefers the repo-local gitignored state dir (`.git/mmi-runtime/hooks/activity.jsonl` via
- * `git rev-parse --git-path`); falls back to a per-cwd tmpdir path so the trace still works
+ * Prefers the repo-local gitignored state dir (`.git/mmi-runtime/hooks/activity.jsonl`, resolved from
+ * the .git layout by `gitDir` above); falls back to a per-cwd tmpdir path so the trace still works
  * outside a repo. Env overrides: `MMI_HOOK_ACTIVITY_LOG` (full path, wins outright) and
  * `MMI_HOOK_ACTIVITY_CWD` (resolve against this directory instead of the hook process's own cwd —
  * the Kimi launcher stamps it from the hook payload because Kimi runs plugin hooks with cwd = the
@@ -70,15 +119,9 @@ function fallbackPath(cwd) {
 export function activityLogPath(cwd = process.cwd(), env = process.env) {
   if (env.MMI_HOOK_ACTIVITY_LOG) return env.MMI_HOOK_ACTIVITY_LOG;
   const effectiveCwd = env.MMI_HOOK_ACTIVITY_CWD || cwd;
-  try {
-    return execFileSync(
-      'git',
-      ['-C', effectiveCwd, 'rev-parse', '--path-format=absolute', '--git-path', 'mmi-runtime/hooks/activity.jsonl'],
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000, windowsHide: true },
-    ).trim();
-  } catch {
-    return fallbackPath(effectiveCwd);
-  }
+  const dir = gitDir(effectiveCwd, env);
+  if (dir && existsSync(dir)) return join(dir, 'mmi-runtime', 'hooks', 'activity.jsonl');
+  return fallbackPath(effectiveCwd);
 }
 
 /**

package/scripts/pretooluse-shell-gates.mjs

@@ -361,10 +361,12 @@ function runCommandLadder(input, { stdout = process.stdout, stderr = process.std
   }
 }
 
-export async function runPreToolUseShellGates({ stdout = process.stdout, stderr = process.stderr } = {}) {
+/** #4118: exported as `runHookGate` too — the uniform in-process entry hook-run.mjs imports instead of
+ *  booting a second node. `input` is the buffered payload when the runner already drained stdin. */
+export async function runPreToolUseShellGates({ input: buffered, stdout = process.stdout, stderr = process.stderr } = {}) {
   let input;
   try {
-    input = await readHookInput();
+    input = await readHookInput(buffered);
   } catch {
     // Unreadable/absent payload = out-of-contract host (Cursor's Claude-plugin import, #2992):
     // fail open without counting a crash. Post-parse crashes below stay fail-closed (#2598).
@@ -407,6 +409,8 @@ export async function runPreToolUseShellGates({ stdout = process.stdout, stderr
   }
 }
 
+export { runPreToolUseShellGates as runHookGate };
+
 if (
   process.argv[1] &&
   (process.argv[1].endsWith('pretooluse-shell-gates.mjs') ||

package/scripts/secret-redact.mjs

@@ -444,11 +444,20 @@ export function postToolUseRedactDecision(input) {
   return { toolName, redactable: false, hookSpecificOutput: null };
 }
 
-async function main() {
+/** The tool name the HOST actually fired, for the trace. hook-run.mjs rewrites a host's shell spelling
+ *  into the Claude vocabulary UPDATABLE_TOOLS is written in (#4118) and stamps the original beside it;
+ *  logging the rewritten name recorded Codex `shell` and `local_shell` as identical "PowerShell" rows. */
+function tracedTool(input) {
+  return typeof input?.mmi_host_tool_name === 'string' ? input.mmi_host_tool_name : input?.tool_name;
+}
+
+/** Shared entry (#4118): awaitable and exit-free so hook-run.mjs can import it in-process instead of
+ *  booting a second node. `input` is the buffered payload when the runner already drained stdin. */
+export async function runHookGate({ input: buffered } = {}) {
   let input;
   try {
     const { readHookInput } = await import('./hook-io.mjs');
-    input = await readHookInput();
+    input = await readHookInput(buffered);
   } catch {
     appendHookActivity({
       event: 'PostToolUse',
@@ -456,7 +465,7 @@ async function main() {
       outcome: 'failed',
       action: 'could not read hook input',
     });
-    process.exit(0);
+    return;
   }
 
   const raw = JSON.stringify(input);
@@ -466,9 +475,9 @@ async function main() {
       script: 'secret-redact',
       outcome: 'ran',
       action: 'clean (pre-filter)',
-      tool: input?.tool_name,
+      tool: tracedTool(input),
     });
-    process.exit(0);
+    return;
   }
 
   try {
@@ -500,7 +509,7 @@ async function main() {
     if (decision && !decision.redactable) {
       process.stderr.write(`[mmi-hook] secret-redact: a secret-shaped value was detected in ${decision.toolName || 'tool'} output and cannot be masked for this tool (no updatedToolOutput channel) — treat the transcript as exposed.\n`);
     }
-    appendHookActivity({ event: 'PostToolUse', script: 'secret-redact', outcome, action, tool: input?.tool_name });
+    appendHookActivity({ event: 'PostToolUse', script: 'secret-redact', outcome, action, tool: tracedTool(input) });
   } catch (err) {
     // #2610: the redactor stays fail-open (PostToolUse — the bytes already left the tool, blocking buys
     // nothing; see #2598 rescope), but its death must be LOUD. Record a greppable crash marker so a
@@ -511,10 +520,9 @@ async function main() {
       outcome: 'failed',
       action: 'redactor crashed during scan',
       error: err && typeof err === 'object' && 'message' in err ? String(err.message) : String(err),
-      tool: input?.tool_name,
+      tool: tracedTool(input),
     });
   }
-  process.exit(0);
 }
 
 if (
@@ -522,9 +530,9 @@ if (
   (process.argv[1].endsWith('secret-redact.mjs') ||
     process.argv[1].replace(/\\/g, '/').endsWith('scripts/secret-redact.mjs'))
 ) {
-  // #2610: a rejection from main() itself (e.g. the dynamic import blew up before the inner try) must not be
-  // swallowed silently either — record a crash marker, then keep the fail-open exit-0 contract.
-  main().catch((err) => {
+  // #2610: a rejection from runHookGate() itself (e.g. the dynamic import blew up before the inner try) must
+  // not be swallowed silently either — record a crash marker, then keep the fail-open exit-0 contract.
+  runHookGate().then(() => process.exit(0)).catch((err) => {
     appendHookActivity({
       event: 'PostToolUse',
       script: 'secret-redact',

package/scripts/vault-edit-gate.mjs

@@ -36,22 +36,24 @@ export function analyze(input) {
   };
 }
 
-async function main() {
-  let input;
+/** Shared entry (#4118): awaitable and exit-free so hook-run.mjs can import it in-process instead of
+ *  booting a second node. `input` is the buffered payload when the runner already drained stdin. */
+export async function runHookGate({ input } = {}) {
+  let parsed;
   try {
-    input = await readHookInput();
+    parsed = await readHookInput(input);
   } catch {
     // Unreadable/absent payload = out-of-contract host (#2992): fail open without counting a crash.
     const res = handleMissingHookInput(GATE_NAME);
     if (res.stdout) process.stdout.write(res.stdout);
     if (res.stderr) process.stderr.write(res.stderr);
-    process.exit(0);
+    return;
   }
   recordGateSuccess(GATE_NAME);
 
   const { block, reason } = analyze({
-    toolName: input?.tool_name,
-    filePaths: editedPaths(input),
+    toolName: parsed?.tool_name,
+    filePaths: editedPaths(parsed),
   });
 
   appendHookActivity({
@@ -59,7 +61,7 @@ async function main() {
     script: GATE_NAME,
     outcome: block ? (MODE === 'observe' ? 'observe' : 'deny') : 'ran',
     action: block ? reason : 'clean',
-    tool: input?.tool_name,
+    tool: parsed?.tool_name,
   });
 
   if (block) {
@@ -76,8 +78,6 @@ async function main() {
       process.stdout.write(decision + '\n');
     }
   }
-
-  process.exit(0);
 }
 
 if (
@@ -85,7 +85,7 @@ if (
   (process.argv[1].endsWith('vault-edit-gate.mjs') ||
     process.argv[1].replace(/\\/g, '/').endsWith('scripts/vault-edit-gate.mjs'))
 ) {
-  main().catch(() => {
+  runHookGate().then(() => process.exit(0)).catch(() => {
     const res = handleGateCrash(GATE_NAME);
     if (res.stdout) process.stdout.write(res.stdout);
     if (res.stderr) process.stderr.write(res.stderr);

package/server.mjs

@@ -44,10 +44,14 @@ export function nodeBin() {
 // Kilo tool names → the Claude vocabulary the shared gates already understand.
 const SHELL_TOOLS = new Set(['bash', 'shell', 'powershell']);
 const EDIT_TOOLS = new Set(['write', 'edit', 'patch', 'apply_patch']);
+// #4118: only the tools the redactor can actually MASK. secret-redact.mjs replaces output through
+// `updatedToolOutput`, which the harness offers for the shell/search family and nothing else — for
+// write/edit/patch/read it returned `redactable: false` and printed a warning, so those entries bought a
+// gate spawn per tool call and never masked a byte. Kilo's own map is the matcher here (there are no
+// manifest hook rules), so this is the same narrowing hooks/hooks.json makes for Claude.
 const REDACT_TOOL_NAME = {
   bash: 'Bash', shell: 'Bash', powershell: 'Bash',
-  write: 'Write', edit: 'Write', patch: 'Write', apply_patch: 'apply_patch',
-  read: 'Read', grep: 'Grep', glob: 'Glob',
+  grep: 'Grep', glob: 'Glob',
 };
 
 /** Idempotent first-run provisioning of the non-plugin payload (~/.kilo/{skills,command,agent}) behind
@@ -207,7 +211,8 @@ export default {
         }
       },
       // PostToolUse equivalent with a WORKING rewrite channel: secret-redact.mjs's updatedToolOutput is
-      // applied to output.output. Write/Read/WebFetch are not rewriteable (same harness limit as Claude).
+      // applied to output.output. A tool absent from REDACT_TOOL_NAME is one the redactor cannot mask,
+      // and is skipped rather than gated for a warning nobody could act on (#4118).
       'tool.execute.after': async (input, output) => {
         const tool = typeof input.tool === 'string' ? input.tool : '';
         const translated = REDACT_TOOL_NAME[tool];

package/skills/hotfix/SKILL.md

@@ -38,7 +38,11 @@ mmi-cli doctor --no-repo-writes
 ```
 
 Stop on a red authority or CLI-version result. The worktree must be clean; move scratch into `tmp/` or
-gitignore it rather than widening the hotfix diff.
+gitignore it rather than widening the hotfix diff. A TRACKED path named in a `working tree must be clean
+before …` refusal is not scratch: read both `git status --porcelain` columns, treat every state except
+exactly ` M` as real work to commit or stash, and for ` M` discard only when
+`git diff HEAD --numstat -- <paths>` is empty, and only with `git checkout -- <paths>`. Plain
+`git diff --numstat` prints nothing for a merely staged change, so it cannot make that call (#4004).
 
 ## 1. Start from the merged development fix
 

package/skills/rcand/SKILL.md

@@ -43,8 +43,12 @@ primary checkout.
 ## Step 1 — development ahead of rc?
 
 Preconditions: on `development`, clean tree. The clean-tree check rejects UNTRACKED scratch too, not just
-modified tracked files — if `--apply` stops with `working tree must be clean before …`, run `git status` and
-gitignore the `??` scratch (or move it to a gitignored path like `tmp/`) before retrying (#1472).
+modified tracked files — if `--apply` stops with `working tree must be clean before …`, run `git status
+--porcelain` on the paths it named and read both columns. Gitignore the `??` scratch (or move it to a
+gitignored path like `tmp/`). Treat every tracked state except exactly ` M` as real work to commit or stash;
+for ` M`, discard only when `git diff HEAD --numstat -- <paths>` is empty, and only with
+`git checkout -- <paths>`. Plain `git diff --numstat` prints nothing for a merely staged change, so it
+cannot tell real work from line-ending churn (#1472, #4004).
 ```bash
 git fetch origin
 git rev-list --count origin/rc..origin/development

package/skills/release/SKILL.md

@@ -72,9 +72,22 @@ breaks here: the new worktree's branch is never literally named `development`/`r
 development` inside it fails outright when `development` is already checked out in the primary checkout (git
 worktrees cannot have the same branch checked out twice). If you are in such a worktree, exit it first and
 run the release from the primary checkout.
-The clean-tree check rejects UNTRACKED scratch too, not just modified tracked files — if `--apply` stops
-with `working tree must be clean before …`, run `git status` and gitignore the `??` scratch (or move it to a
-gitignored path like `tmp/`) before retrying (#1472).
+The clean-tree check rejects UNTRACKED scratch too, not just modified tracked files. When `--apply` or
+`--resume` stops with `working tree must be clean before …`, run `git status --porcelain` on the paths it
+named and read BOTH status columns before touching anything (#1472, #4004):
+
+- `??` — untracked scratch. Gitignore it, or move it to a gitignored path like `tmp/`, then retry.
+- exactly ` M` (blank staged column) — the only state that can be churn rather than work. Test it with
+  `git diff HEAD --numstat -- <paths>`: non-empty is a real edit to commit or stash; empty means the
+  worktree normalizes straight back to HEAD (an LF↔CRLF rewrite, say), and `git checkout -- <paths>`
+  then clears the refusal without discarding anything.
+- anything else — `M `, `MM`, `A`, `D`, `R`, `T`, or any `U` conflict — is real work or an exceptional
+  index state. Commit, stash or resolve it; do not try to classify it.
+
+Do not substitute plain `git diff --numstat` for the `HEAD` form. It compares the worktree against the
+INDEX, so a change that is merely staged prints nothing at all, and reading that emptiness as
+"line-ending churn" throws the change away. The remedy is the index form of `git checkout` for the same
+reason: `git checkout HEAD -- <paths>` would overwrite a staged edit that was misread as churn.
 
 Full-track repos:
 ```bash
@@ -471,6 +484,19 @@ mmi-cli org project sync-info --apply   # omit --apply for the read-only plan
   channel — #3630 took SessionStart off the hook surface) runs the
   same fast-forward first thing, so a stale local `development`/`main`/`rc` self-heals to origin before you
   work — no manual `git pull`. Nothing here ever blocks or fails the release.
+- **Read the `checkout:` clause — it does not always say "returned" (#4006).** The report always prints
+  one, and restoration is deliberately skipped rather than forced when the repo is not in a fit state.
+  A release leaves the repo on `main` until the train moves it back, so a non-`returned` outcome means
+  you are still there and must return by hand once the cause is cleared:
+  - `checkout restoration skipped: working tree changed after release` — the tree went dirty DURING the
+    train, so the train declined to move you. Diagnose those paths with the Step 0 clean-tree rules,
+    then `git checkout <start branch>` yourself. The release itself already shipped; this is a
+    deliberate, harmless decline, not a failed release.
+  - `checkout restoration failed while returning to …` / `origin/<branch> fast-forward failed` — the
+    checkout or the pull errored. Read the appended git message; the release is unaffected.
+
+  `--resume` prints no `checkout:` clause at all, so after a resumed release check `git branch
+  --show-current` rather than assuming you were moved back.
 
 ## Step 6 — collect deploy verdict + report
 
@@ -478,6 +504,10 @@ Collect the backgrounded prod-deploy watch from Step 4 (it has typically finishe
 healthy (the central deploy workflow smoke step / a health check); **red** → report the failure prominently and flag
 that the release shipped on a failed deploy (re-run just the deploy — `main` is already correct).
 
+**This distribution verifier is Hub-only.** It assumes the Hub release fold has already committed its
+generated artifacts. Non-Hub `registry-publish` repositories must not run `release-distribution.mjs
+verify`: use their own release-workflow evidence and the publish-visibility contract below.
+
 Hub releases always carry a distribution bump (the Step 1b fold), so the **publish workflow**
 (`publish.yml`) ships every registry-declared public npm artifact on the GitHub Release from Step 4 —
 don't publish by hand.