memtrace 0.3.81 → 0.3.85

package/bin/memtrace.js

@@ -10,6 +10,12 @@ const { getBinaryPath } = require("../install.js");
 const { platformBinary, spawnOptionsForPlatform } = require("../lib/spawn-helper");
 const { shouldPromptForUpgrade, isPromptDisabled } = require("../lib/update-prompt");
 const { fetchLatestVersion, readCachedVersion } = require("../lib/update-check");
+// ─── Honest-lifecycle (Leaf B / fortress-round-1 T5) ──────────────────────
+// Pure exit-code translator — pins child(0) → 0, child(75) → 75,
+// SIGKILL → 137, SIGTERM → 143, SIGINT → 130. Pre-fix the shim
+// translated SIGKILL → 1 (mcp branch) or → 0 (sync branch) which
+// is the silent-disappearance bug from /tmp/mt-debug/exit.
+const { propagateChildExit } = require("../lib/exit-code");
 
 // ── Handle `memtrace uninstall` before delegating to the Rust binary ────────
 // npm v7+ does NOT fire preuninstall hooks for global packages (npm/cli#3042).
@@ -37,6 +43,29 @@ if (args[0] === "install" || args[0] === "update" || args[0] === "upgrade") {
   const npmCmd = platformBinary("npm", process.platform);
   const memtraceCmd = platformBinary("memtrace", process.platform);
 
+  // ── Pre-commit hook drift check (agent-precommit-optin, 2026-05-08) ──
+  // `memtrace install` is the natural place a user re-runs after an
+  // upgrade. If a prior version installed the pre-commit hook (now
+  // opt-in by default), surface a one-line note so partners hitting
+  // the ~2 min agentic-pipeline tax know the off-ramp. We DO NOT
+  // remove the hook automatically — that's the user's call.
+  try {
+    const cwdHook = path.join(process.cwd(), ".git", "hooks", "pre-commit");
+    if (fs.existsSync(cwdHook)) {
+      const body = fs.readFileSync(cwdHook, "utf8");
+      // Match the canonical BEGIN marker we ship in hooks.rs.
+      if (body.includes("BEGIN MEMTRACE BLOCK")) {
+        process.stdout.write(
+          "memtrace: pre-commit hook is installed in this repo — " +
+          "uninstall with `memtrace uninstall-hooks --pre-commit` " +
+          "if it's slowing your agentic pipeline.\n"
+        );
+      }
+    }
+  } catch (_) {
+    // Best-effort — never fail the install on a hook-detection hiccup.
+  }
+
   process.stdout.write("memtrace: fetching latest from npm registry…\n");
   const installResult = spawnSync(
     npmCmd,
@@ -269,7 +298,12 @@ if (args[0] === "mcp") {
     process.exit(1);
   });
   child.on("exit", (code, signal) => {
-    process.exit(signal ? 1 : (code ?? 0));
+    // ─── Leaf B T5 ─── propagate the child's typed exit code (or
+    // signal-derived 128+sig) so CI / supervisors can grep $? and
+    // distinguish exit 75 (Phase-2 partial) from SIGKILL (137) from a
+    // clean exit (0). Pre-fix this folded SIGKILL into 1 → silent jet-
+    // sam disappearance.
+    process.exit(propagateChildExit({ code, signal }));
   });
 
 } else {
@@ -296,6 +330,9 @@ if (args[0] === "mcp") {
       console.error(`Failed to run memtrace: ${result.error.message}`);
       process.exit(1);
     }
-    process.exit(result.status ?? 0);
+    // ─── Leaf B T5 ─── same propagation contract as the mcp branch.
+    // `spawnSync` returns `{status, signal}` — `status` is null when
+    // the child was killed; `?? 0` would silently drop signal info.
+    process.exit(propagateChildExit({ code: result.status, signal: result.signal }));
   })();
 }

package/hooks/userprompt-claude.sh

@@ -14,6 +14,16 @@
 #     not on which file the model chose to grep
 #   - non-blocking → just adds context, never denies a tool call
 #
+# Per-session debounce (round-2 G4 / agent-I):
+#   The hook still fires once per user turn, but in a long Orbit-
+#   style automated session that's dozens of fires per prompt.
+#   Each fire pings the daemon health endpoint — cheap individually,
+#   death-by-thousand-cuts in aggregate. We add a per-session lock
+#   file at $HOME/.memtrace/hook-debounce/<session_id>.lock; if its
+#   mtime is within MEMTRACE_HOOK_DEBOUNCE_SECS (default 120s) we
+#   short-circuit to a no-op-but-well-formed JSON output and skip
+#   the daemon probe entirely.
+#
 # Exit codes:
 #   0  : success (stdout is parsed for hook output)
 #   2  : would block the prompt (we never want this)
@@ -22,14 +32,161 @@
 #   { "decision": "continue", "additionalContext": "..." }
 #
 # Override:
-#   MEMTRACE_HOOK_MODE=off    → unconditional no-op
-#   MEMTRACE_HEALTH_URL=...   → custom health endpoint (default 3030)
+#   MEMTRACE_HOOK_MODE=off              → unconditional no-op (skips lock too)
+#   MEMTRACE_HEALTH_URL=...             → custom health endpoint (default 3030)
+#   MEMTRACE_HOOK_DEBOUNCE_SECS=120     → debounce window seconds (0 disables)
+#   MEMTRACE_HOOK_DEBOUNCE_DIR=...      → override lock dir (default $HOME/.memtrace/hook-debounce)
+#   CLAUDE_SESSION_ID / CLAUDE_CONVERSATION_ID → session id sources
 #
 set -euo pipefail
 
 mode="${MEMTRACE_HOOK_MODE:-advisory}"
 [[ "$mode" == "off" ]] && exit 0
 
+# ── Session-id resolution (G4.2) ────────────────────────────────────
+#
+# Source priority:
+#   1. CLAUDE_SESSION_ID  env (preferred — Claude Code may set this)
+#   2. CLAUDE_CONVERSATION_ID env (alternate naming)
+#   3. fallback: stable hash of $PPID + parent process start time
+#      (so the same parent process tree always resolves to the same
+#       id, but a new shell parent gets its own id).
+#
+# Output is sanitised (only [A-Za-z0-9_-]) so it's safe to use as a
+# filename component on every supported OS.
+resolve_session_id() {
+    local raw=""
+    if [[ -n "${CLAUDE_SESSION_ID:-}" ]]; then
+        raw="$CLAUDE_SESSION_ID"
+    elif [[ -n "${CLAUDE_CONVERSATION_ID:-}" ]]; then
+        raw="$CLAUDE_CONVERSATION_ID"
+    else
+        # Hash of PPID + parent start-time. ps prints lstart for
+        # the parent process; combined with PPID this is stable
+        # within the parent's lifetime and changes when a new
+        # parent process is spawned.
+        local ppid="${PPID:-0}"
+        local pstart=""
+        pstart="$(ps -o lstart= -p "$ppid" 2>/dev/null || true)"
+        # Fold to a short hash so the lock file name stays short.
+        # md5/shasum availability varies; prefer shasum (POSIX-ish),
+        # fall back to a python one-liner, then to the raw string.
+        local input="ppid=${ppid};start=${pstart}"
+        if command -v shasum >/dev/null 2>&1; then
+            raw="$(printf '%s' "$input" | shasum -a 1 | awk '{print $1}')"
+        elif command -v sha1sum >/dev/null 2>&1; then
+            raw="$(printf '%s' "$input" | sha1sum | awk '{print $1}')"
+        elif command -v python3 >/dev/null 2>&1; then
+            raw="$(printf '%s' "$input" | python3 -c '
+import hashlib, sys
+print(hashlib.sha1(sys.stdin.buffer.read()).hexdigest())
+' 2>/dev/null || true)"
+        else
+            raw="$input"
+        fi
+    fi
+
+    # Sanitise for filesystem safety: keep only [A-Za-z0-9_-], replace
+    # everything else with `_`. Also collapse to at most 128 chars so
+    # we don't blow path-length limits.
+    local cleaned
+    cleaned="$(printf '%s' "$raw" | tr -c 'A-Za-z0-9_-' '_' | cut -c1-128)"
+    if [[ -z "$cleaned" ]]; then
+        cleaned="unknown_session"
+    fi
+    printf '%s' "$cleaned"
+}
+
+# ── Debounce window parsing ─────────────────────────────────────────
+#
+# Validates that MEMTRACE_HOOK_DEBOUNCE_SECS is a non-negative
+# integer. Anything malformed falls back to 120s. A literal `0`
+# disables debounce entirely (every fire proceeds).
+parse_debounce_secs() {
+    local raw="${MEMTRACE_HOOK_DEBOUNCE_SECS:-120}"
+    if [[ "$raw" =~ ^[0-9]+$ ]]; then
+        printf '%s' "$raw"
+    else
+        printf '%s' "120"
+    fi
+}
+
+# ── Orphan cleanup (G4.5) ───────────────────────────────────────────
+#
+# Opportunistic + bounded: at hook entry, remove lock files older
+# than 24h, but cap how many we touch per fire so we don't stat
+# thousands of files on every prompt. `find ... -mtime +1 -delete`
+# is the portable form (BSD + GNU find both support it). We pipe
+# through `head -n N` to bound the work.
+ORPHAN_CLEANUP_MAX="${MEMTRACE_HOOK_ORPHAN_CLEANUP_MAX:-32}"
+orphan_cleanup() {
+    local dir="$1"
+    local max="$2"
+    [[ -d "$dir" ]] || return 0
+    # `-mmin +1440` matches files modified more than 1440 minutes
+    # (24h) ago. We deliberately use mmin (not -mtime +1) because
+    # BSD `find` truncates `-mtime` to whole days then strict-
+    # compares — so a 25h-old file does NOT match `-mtime +1`. The
+    # mmin form is unambiguous on both BSD (macOS) and GNU (Linux).
+    # We list candidates, head-bound them, then rm. This avoids
+    # walking a giant directory linearly on every fire.
+    local f
+    while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        rm -f -- "$f" 2>/dev/null || true
+    done < <(find "$dir" -maxdepth 1 -type f -name '*.lock' -mmin +1440 2>/dev/null | head -n "$max")
+}
+
+# ── Lock-file gate ──────────────────────────────────────────────────
+LOCK_DIR="${MEMTRACE_HOOK_DEBOUNCE_DIR:-${HOME:-/tmp}/.memtrace/hook-debounce}"
+DEBOUNCE_SECS="$(parse_debounce_secs)"
+
+# Ensure lock dir exists. If we can't create it (read-only home,
+# permission denied, etc.) the hook still works — we just skip the
+# debounce gate this fire.
+mkdir -p "$LOCK_DIR" 2>/dev/null || true
+
+# Cleanup orphans BEFORE evaluating the gate so a stale lock that's
+# been orphaned for 24h+ doesn't accidentally suppress the fire.
+if [[ -d "$LOCK_DIR" ]]; then
+    orphan_cleanup "$LOCK_DIR" "$ORPHAN_CLEANUP_MAX"
+fi
+
+SESSION_ID="$(resolve_session_id)"
+LOCK_FILE="$LOCK_DIR/$SESSION_ID.lock"
+
+# Debounce gate: if lock exists and is fresh, short-circuit.
+# DEBOUNCE_SECS==0 is the explicit disable knob; we skip the gate
+# entirely so every fire proceeds (useful for debugging & tests).
+if (( DEBOUNCE_SECS > 0 )) && [[ -f "$LOCK_FILE" ]]; then
+    NOW=$(date +%s)
+    # `stat -f %m` is BSD/macOS, `stat -c %Y` is GNU/Linux. Try
+    # both; if neither works (extremely unusual) we treat the lock
+    # as fresh enough to suppress, on the principle that "we just
+    # touched it" is the safer default than "spam the daemon".
+    LAST="$(stat -f %m "$LOCK_FILE" 2>/dev/null || stat -c %Y "$LOCK_FILE" 2>/dev/null || printf '%s' "$NOW")"
+    if [[ "$LAST" =~ ^[0-9]+$ ]]; then
+        AGE=$((NOW - LAST))
+        if (( AGE < DEBOUNCE_SECS )); then
+            # Within debounce window → emit a well-formed no-op
+            # hook output and exit. We do NOT probe the daemon.
+            cat <<'EOF'
+{
+  "decision": "continue",
+  "additionalContext": ""
+}
+EOF
+            exit 0
+        fi
+    fi
+fi
+
+# Outside the window (or first fire): touch the lock and proceed.
+# `touch` creates the file if missing and updates mtime if present;
+# this is the canonical "I just fired" signal for the next gate
+# evaluation in the same session.
+touch "$LOCK_FILE" 2>/dev/null || true
+
 # ── Daemon liveness (portable: works on macOS/Linux/Windows-WSL) ──
 #
 # We use the Memtrace UI's status endpoint instead of `pgrep` so

package/install.js

@@ -293,6 +293,26 @@ if (require.main === module) {
   } catch (e) {
     console.warn(`memtrace: failed to persist uninstall script: ${e.message}`);
   }
+
+  // 6. Background-daemon discovery hint (Leaf H / fortress-round-2).
+  //    Operators on long-running setups (Sivant on Windows, Orbit on
+  //    Linux, macOS lab hosts) shouldn't have to keep a terminal open
+  //    to keep the indexer alive — point them at the subcommand. The
+  //    hint is post-install only, never on update; CI systems don't
+  //    benefit and we don't want to nag.
+  //
+  //    The exact substring `memtrace daemon install` is contract-pinned
+  //    by the F2F test row H-035
+  //    (`npm_shim_post_install_prints_daemon_install_hint`). Renaming
+  //    the subcommand here without updating that test is a regression.
+  try {
+    if (process.env.MEMTRACE_SUPPRESS_DAEMON_HINT !== "1") {
+      console.log(
+        "memtrace: want it to run as a background service? `memtrace daemon install` " +
+          "(macOS launchd / Linux systemd-user / Windows Service)."
+      );
+    }
+  } catch { /* best-effort — never fail install on a logging hiccup */ }
 }
 
 module.exports = {

package/lib/exit-code.js

@@ -0,0 +1,99 @@
+"use strict";
+
+// ─── Honest-lifecycle (Leaf B / fortress-round-1 T5) ─────────────────────────
+//
+// The npm shim spawns the native `memtrace` binary as a child process and
+// MUST propagate the child's exit code (or signal-derived equivalent) so
+// CI / supervisors can distinguish a clean exit (0), Phase-2 partial
+// failure (75 / EX_TEMPFAIL — the new contract from cmd_start), and
+// signal-driven exits (SIGKILL → 137, SIGINT → 130, etc.).
+//
+// Pre-fix shipped two divergent behaviours:
+//   * `mcp` branch: `process.exit(signal ? 1 : (code ?? 0))` —
+//     SIGKILL became exit 1, NOT 137. That's the silent-disappearance
+//     bug from /tmp/mt-debug/exit: macOS jetsam'd the embedder, the
+//     shim returned 0/1, and the user saw "memtrace silently
+//     disappeared" with no way to grep the exit code.
+//   * non-mcp `spawnSync` branch: `process.exit(result.status ?? 0)`
+//     — `result.status` is null when the child was killed by signal,
+//     and `?? 0` collapses that to a clean exit. Same bug, different
+//     surface.
+//
+// The contract this file pins (rows B-013 / B-014 / B-015 / B-022):
+//   * child exit(0)            → shim exit 0
+//   * child exit(75)           → shim exit 75
+//   * child killed by SIGKILL  → shim exit 137 (= 128 + 9)
+//   * child killed by SIGTERM  → shim exit 143 (= 128 + 15)
+//   * child killed by SIGINT   → shim exit 130 (= 128 + 2)
+//
+// Pure function; safe to require from anywhere; no side effects.
+
+// Numeric signal map for the platforms the shim runs on (POSIX). On
+// Windows, `child.kill(signal)` is best-effort and the OS doesn't
+// surface a real signal number — the helper falls back to 1 (the
+// generic failure code) when the signal name isn't recognised.
+const SIGNAL_NUMBERS = Object.freeze({
+    SIGHUP: 1,
+    SIGINT: 2,
+    SIGQUIT: 3,
+    SIGILL: 4,
+    SIGTRAP: 5,
+    SIGABRT: 6,
+    SIGBUS: 7,
+    SIGFPE: 8,
+    SIGKILL: 9,
+    SIGUSR1: 10,
+    SIGSEGV: 11,
+    SIGUSR2: 12,
+    SIGPIPE: 13,
+    SIGALRM: 14,
+    SIGTERM: 15,
+    SIGCHLD: 17,
+    SIGCONT: 18,
+    SIGSTOP: 19,
+    SIGTSTP: 20,
+    SIGTTIN: 21,
+    SIGTTOU: 22,
+});
+
+/**
+ * Pure decision: given the `(code, signal)` shape Node hands back from
+ * `child.on('exit')` or `spawnSync`'s `{status, signal}`, return the
+ * exit code the shim should pass to `process.exit`.
+ *
+ * @param {object} args
+ * @param {number|null|undefined} args.code   Numeric exit code, or null when killed by signal.
+ * @param {string|null|undefined} args.signal Signal name (e.g. "SIGKILL"), or null on clean exit.
+ * @returns {number} Exit code to forward to `process.exit`.
+ */
+function propagateChildExit({ code, signal } = {}) {
+    // Clean exit takes priority. Node guarantees `code` is non-null
+    // when the child exited normally, even if it exited with 0.
+    if (typeof code === "number") {
+        // Sanitise: process.exit clamps to [0, 255] anyway, but pin
+        // the contract so ill-behaved children producing > 255 don't
+        // confuse the supervisor.
+        return code & 0xff;
+    }
+    // Signal-driven exit. POSIX shells use `128 + signal_number` as
+    // the exit-status convention so callers can disambiguate "child
+    // returned 9" from "child got SIGKILL". We follow the same rule.
+    if (signal && typeof signal === "string") {
+        const n = SIGNAL_NUMBERS[signal];
+        if (typeof n === "number") {
+            return 128 + n;
+        }
+        // Unknown signal name (Windows, exotic platforms): fall back
+        // to 1 — generic failure — rather than guessing.
+        return 1;
+    }
+    // Neither code nor signal — should not happen on Node ≥ 0.12,
+    // but pin a deterministic default so the shim never silently
+    // exits 0 on a malformed child shape.
+    return 1;
+}
+
+module.exports = {
+    propagateChildExit,
+    SIGNAL_NUMBERS,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.81",
+  "version": "v0.3.85",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",