@drewpayment/mink 0.13.0-beta.3 → 0.13.0-beta.5

package/src/core/agent-pi.ts

@@ -0,0 +1,383 @@
+import { join, resolve, dirname } from "path";
+import { existsSync, mkdirSync, copyFileSync, rmSync } from "fs";
+import { atomicWriteText } from "./fs-utils";
+
+// ── Paths ───────────────────────────────────────────────────────────────────
+// Pi auto-discovers extensions from `.pi/extensions/*.ts` and skills from
+// `.pi/skills/*/SKILL.md`, so simply writing these files wires Mink in — no
+// `.pi/settings.json` edit required, which keeps us from clobbering the user's
+// own Pi configuration.
+
+export function piExtensionPath(cwd: string): string {
+  return join(cwd, ".pi", "extensions", "mink.ts");
+}
+
+export function piGuidanceSkillPath(cwd: string): string {
+  return join(cwd, ".pi", "skills", "mink", "SKILL.md");
+}
+
+export function piNoteSkillPath(cwd: string): string {
+  return join(cwd, ".pi", "skills", "mink-note", "SKILL.md");
+}
+
+// ── Extension source ─────────────────────────────────────────────────────────
+
+/**
+ * Generate the Pi adapter extension. Like the Claude hook wiring, the `mink`
+ * invocation is templated: an installed package resolves the portable `mink`
+ * bin shim (so a committed `.pi/` works across machines), while source-dev mode
+ * falls back to `bun run <abs cli.ts>`.
+ *
+ * The adapter shells out to the same `mink` lifecycle commands every other host
+ * uses, translating Pi's event/tool shapes into Mink's canonical payload. It is
+ * deliberately defensive: it never throws into Pi, never blocks a tool, and
+ * times out fast — matching the safety contract of the Claude hooks.
+ */
+export function buildPiExtension(cliPath: string): string {
+  const isTsSource = cliPath.endsWith(".ts");
+  const cmd = isTsSource ? "bun" : "mink";
+  const baseArgs = isTsSource ? JSON.stringify(["run", cliPath]) : "[]";
+
+  return `// AUTO-GENERATED by \`mink init\`. Do not edit — re-run \`mink init\` to refresh.
+//
+// Mink adapter for the Pi coding agent. Routes Pi lifecycle and tool events
+// into the \`mink\` CLI so Pi shares the same ~/.mink state, file index, ledger,
+// and wiki as every other assistant wired to this project.
+//
+// Field shapes confirmed against pi source (earendil-works/pi,
+// packages/coding-agent): read params {path, offset, limit}; write {path,
+// content}; edit {path, edits:[{oldText,newText}]} (with legacy file_path /
+// top-level oldText,newText). tool_call/tool_result events expose toolName,
+// toolCallId, input; tool_result also exposes content (a content-block array),
+// details, isError. Advisories are surfaced by returning a modified result from
+// the tool_result handler — the documented mechanism; that same return path
+// SUBSTITUTES a reversible compressed result whenever a hook prints Claude
+// Code's { hookSpecificOutput: { updatedToolOutput } } envelope on stdout
+// (tool-output compression, spec 22 — Bash/Grep/Glob/MCP via post-tool, large
+// whole-file reads via post-read; the original is retrievable with
+// \`mink retrieve\`). pi.exec has no stdin, so the canonical payload is piped to
+// \`mink\` via a spawned child process. Every host-API access is defensive: the
+// adapter never throws into Pi or blocks a tool — a failure degrades to "no
+// advisory" and the original, uncompressed output.
+
+import { spawn } from "node:child_process";
+
+const MINK_CMD = ${JSON.stringify(cmd)};
+const MINK_BASE_ARGS = ${baseArgs};
+const TIMEOUT_MS = 5000;
+
+// Spawn a \`mink\` subcommand, pipe the canonical payload to its stdin, and
+// collect BOTH streams: stdout carries a compression replacement
+// (Claude Code's { hookSpecificOutput: { updatedToolOutput } } envelope) and
+// stderr carries human-visible advisories. Always resolves to { out, err } —
+// any failure or timeout degrades to empty strings, never a rejection.
+function runMink(sub, payload, cwd) {
+  return new Promise((res) => {
+    let done = false;
+    const finish = (out, err) => {
+      if (done) return;
+      done = true;
+      res({ out: (out || "").trim(), err: (err || "").trim() });
+    };
+    try {
+      const child = spawn(MINK_CMD, [...MINK_BASE_ARGS, sub], {
+        cwd,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout?.on("data", (d) => {
+        stdout += d.toString();
+      });
+      child.stderr?.on("data", (d) => {
+        stderr += d.toString();
+      });
+      child.on("error", () => finish("", ""));
+      child.on("close", () => finish(stdout, stderr));
+      const timer = setTimeout(() => {
+        try {
+          child.kill();
+        } catch {}
+        finish("", "");
+      }, TIMEOUT_MS);
+      timer.unref?.();
+      try {
+        child.stdin?.end(payload ? JSON.stringify(payload) : "");
+      } catch {}
+    } catch {
+      finish("", "");
+    }
+  });
+}
+
+// Pi's edit tool takes an array of { oldText, newText } replacements (legacy
+// inputs may put oldText/newText/new_string at the top level). Concatenate the
+// replacement text so Mink's write-enforcement sees everything being written.
+function editNewText(input) {
+  if (Array.isArray(input.edits)) {
+    return input.edits
+      .map((e) => e?.newText ?? e?.new_string ?? "")
+      .filter(Boolean)
+      .join("\\n");
+  }
+  return input.newText ?? input.new_string ?? input.replacement ?? "";
+}
+
+// Resolve Pi's tool name + arguments to Mink's canonical operation. Only the
+// three file operations matter; anything else returns null and is ignored.
+function toolInfo(event) {
+  const name = String(event?.toolName ?? event?.tool ?? event?.name ?? "").toLowerCase();
+  const input = event?.input ?? event?.arguments ?? {};
+  const filePath = input.path ?? input.file_path ?? input.filePath;
+  if (!filePath) return null;
+  if (name === "read") return { op: "read", filePath };
+  if (name === "write") return { op: "write", filePath, content: input.content ?? input.text ?? "" };
+  if (name === "edit") return { op: "edit", filePath, newString: editNewText(input) };
+  return null;
+}
+
+// A tool_result's content is an array of content blocks ({ type, text }); pull
+// the text out so Mink's post-read can estimate tokens from real content.
+function resultContent(event) {
+  const c = event?.content;
+  if (typeof c === "string") return c;
+  if (Array.isArray(c)) {
+    const text = c
+      .map((b) => (typeof b === "string" ? b : b?.text ?? ""))
+      .filter(Boolean)
+      .join("\\n");
+    return text || null;
+  }
+  return null;
+}
+
+// Parse a hook's stdout for a reversible compression replacement. Mink's
+// post-read/post-tool hooks print Claude Code's
+// { hookSpecificOutput: { updatedToolOutput } } envelope on stdout; under Pi we
+// read it here and substitute it into the tool result. Empty/non-JSON → null.
+function parseReplacement(out) {
+  if (!out) return null;
+  try {
+    const j = JSON.parse(out);
+    const r = j?.hookSpecificOutput?.updatedToolOutput;
+    return typeof r === "string" ? r : null;
+  } catch {
+    return null;
+  }
+}
+
+// Map a Pi non-file tool to the canonical Mink tool name the post-tool
+// compression hook accepts (Bash/Grep/Glob, or an mcp__* passthrough). Pi's
+// built-in tool names aren't all pinned, so map common shell/search aliases and
+// return null for anything Mink doesn't compress — those pass through untouched.
+function compressibleName(event) {
+  const raw = String(event?.toolName ?? event?.tool ?? event?.name ?? "");
+  const name = raw.toLowerCase();
+  if (name.startsWith("mcp__")) return raw;
+  if (name.startsWith("mcp")) return "mcp__" + raw;
+  if (name === "bash" || name === "shell" || name === "exec" || name === "command" || name === "run")
+    return "Bash";
+  if (name === "grep" || name === "search" || name === "ripgrep" || name === "rg")
+    return "Grep";
+  if (name === "glob" || name === "find") return "Glob";
+  return null;
+}
+
+function prePayload(info) {
+  if (info.op === "read")
+    return { sub: "pre-read", payload: { tool_name: "Read", tool_input: { file_path: info.filePath } } };
+  if (info.op === "write")
+    return {
+      sub: "pre-write",
+      payload: { tool_name: "Write", tool_input: { file_path: info.filePath, content: info.content } },
+    };
+  return {
+    sub: "pre-write",
+    payload: { tool_name: "Edit", tool_input: { file_path: info.filePath, new_string: info.newString } },
+  };
+}
+
+function postPayload(info, content) {
+  if (info.op === "read")
+    return {
+      sub: "post-read",
+      payload: {
+        tool_name: "Read",
+        tool_input: { file_path: info.filePath },
+        tool_output: content == null ? undefined : { content },
+      },
+    };
+  if (info.op === "write")
+    return {
+      sub: "post-write",
+      payload: { tool_name: "Write", tool_input: { file_path: info.filePath, content: info.content } },
+    };
+  return {
+    sub: "post-write",
+    payload: { tool_name: "Edit", tool_input: { file_path: info.filePath, new_string: info.newString } },
+  };
+}
+
+export default function (pi) {
+  const cwd = pi?.ctx?.cwd || process.cwd();
+  const pending = new Map();
+  const keyOf = (event) => event?.toolCallId ?? event?.id ?? event?.callId ?? "";
+
+  pi.on?.("session_start", (event) => {
+    // Skip hot-reloads so an extension reload mid-task doesn't reset the
+    // ephemeral session state; every genuinely new/resumed session starts fresh.
+    if (event?.reason === "reload") return;
+    void runMink("session-start", null, cwd);
+  });
+  pi.on?.("agent_end", () => {
+    void runMink("session-stop", null, cwd);
+  });
+  pi.on?.("session_shutdown", () => {
+    void runMink("session-stop", null, cwd);
+  });
+
+  pi.on?.("tool_call", async (event) => {
+    const info = toolInfo(event);
+    if (!info) return;
+    const { sub, payload } = prePayload(info);
+    const { err } = await runMink(sub, payload, cwd);
+    if (err) pending.set(keyOf(event), err);
+  });
+
+  // Build the Pi tool_result return value. A compression \`replacement\` (a hook's
+  // stdout) SUBSTITUTES the tool output; \`advisoryParts\` (hook stderr) are
+  // appended as an extra text block — the parity of Claude feeding hook stderr
+  // back. Returns undefined when nothing changes, leaving Pi's result intact.
+  const buildResult = (event, replacement, advisoryParts) => {
+    const advisory = advisoryParts.filter(Boolean).join("\\n");
+    if (replacement == null && !advisory) return undefined;
+    const base =
+      replacement != null
+        ? [{ type: "text", text: replacement }]
+        : Array.isArray(event.content)
+          ? event.content
+          : typeof event.content === "string"
+            ? [{ type: "text", text: event.content }]
+            : [];
+    const content = advisory ? [...base, { type: "text", text: advisory }] : base;
+    return { content, details: event.details, isError: event.isError };
+  };
+
+  pi.on?.("tool_result", async (event) => {
+    const info = toolInfo(event);
+    if (info) {
+      // File ops: post-read/post-write record state; a large whole-file read may
+      // also emit a reversible compression replacement on stdout.
+      const { sub, payload } = postPayload(info, resultContent(event));
+      const post = await runMink(sub, payload, cwd);
+      const pre = pending.get(keyOf(event)) ?? "";
+      pending.delete(keyOf(event));
+      return buildResult(event, parseReplacement(post.out), [pre, post.err]);
+    }
+
+    // Non-file tools (Bash/Grep/Glob/MCP): route the output text through the
+    // post-tool compression hook and substitute its reversible replacement. The
+    // original is cached host-side, retrievable via \`mink retrieve\`.
+    const canon = compressibleName(event);
+    if (!canon) return;
+    const content = resultContent(event);
+    if (content == null) return;
+    const post = await runMink(
+      "post-tool",
+      { tool_name: canon, tool_output: { content } },
+      cwd
+    );
+    return buildResult(event, parseReplacement(post.out), [post.err]);
+  });
+}
+`;
+}
+
+// ── Guidance skill ───────────────────────────────────────────────────────────
+// Pi has no automatic project-rules file (CLAUDE.md / AGENTS.md equivalent), so
+// the guidance Mink gives the assistant is delivered as a Pi skill instead.
+
+const PI_GUIDANCE_SKILL = `---
+name: mink
+description: Mink context management is active in this project. Read this to understand how Mink memory, write enforcement, and note capture work under Pi.
+---
+
+# Mink — context management for this project
+
+This project uses **Mink** (\`@drewpayment/mink\`) for cross-session context management.
+
+## How it works
+- Mink runs automatically through a Pi extension at \`.pi/extensions/mink.ts\` that hooks session start/stop and every read/edit/write tool call, plus Bash/Grep/Glob/MCP results.
+- Large tool outputs may be transparently replaced with a compact, reversible summary; if you need the full original, fetch it with \`mink retrieve <token>\` (the token appears in the summary).
+- All state lives in \`~/.mink/\` on the user's machine — **not** in this repository. Do not create or write to any in-repo state directory (no \`.wolf/\`, \`.mink/\`, etc.).
+- Read intelligence, write enforcement, bug memory, and the token ledger are handled by the extension. You do not need to manually read or update any state files.
+- Mink shares one \`~/.mink/\` state across every assistant wired to this project, so history is unified whether the user runs Pi or another assistant.
+
+## When to act on Mink
+- If the user asks to "save a note", "remember this", "log this to my wiki", or similar, use the \`mink-note\` skill (\`/skill:mink-note\`) — it captures into the user's \`~/.mink/\` vault.
+- If the extension surfaces a learning, past bug, or repeat-read warning in context, treat that as authoritative project memory and follow it.
+- The \`mink dashboard\` and \`mink agent\` commands are user tools — do not invoke them on the user's behalf.
+`;
+
+function resolveSkillsSourceDir(): string {
+  // Walk up until we find a package root that contains skills/ — works from
+  // src/core/agent-pi.ts (dev) and dist/cli.js (installed), which sit at
+  // different depths relative to the package root.
+  let dir = dirname(new URL(import.meta.url).pathname);
+  while (true) {
+    if (existsSync(join(dir, "package.json")) && existsSync(join(dir, "skills"))) {
+      return join(dir, "skills");
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(dirname(new URL(import.meta.url).pathname), "../../skills");
+}
+
+export interface PiInstallResult {
+  extensionPath: string;
+  guidancePath: string;
+  notePath: string | null;
+}
+
+export function installPi(cwd: string, cliPath: string): PiInstallResult {
+  const extensionPath = piExtensionPath(cwd);
+  mkdirSync(dirname(extensionPath), { recursive: true });
+  atomicWriteText(extensionPath, buildPiExtension(cliPath));
+
+  const guidancePath = piGuidanceSkillPath(cwd);
+  mkdirSync(dirname(guidancePath), { recursive: true });
+  atomicWriteText(guidancePath, PI_GUIDANCE_SKILL);
+
+  // Mirror the note-capture skill into Pi's skill directory so the single
+  // source of truth (skills/mink-note) is reused rather than duplicated.
+  let notePath: string | null = null;
+  try {
+    const src = join(resolveSkillsSourceDir(), "mink-note", "SKILL.md");
+    if (existsSync(src)) {
+      notePath = piNoteSkillPath(cwd);
+      mkdirSync(dirname(notePath), { recursive: true });
+      copyFileSync(src, notePath);
+    }
+  } catch {
+    // Note skill is non-critical — the extension and guidance still work.
+    notePath = null;
+  }
+
+  return { extensionPath, guidancePath, notePath };
+}
+
+export function removePi(cwd: string): void {
+  for (const p of [
+    piExtensionPath(cwd),
+    join(cwd, ".pi", "skills", "mink"),
+    join(cwd, ".pi", "skills", "mink-note"),
+  ]) {
+    try {
+      rmSync(p, { recursive: true, force: true });
+    } catch {
+      // best-effort
+    }
+  }
+}

package/src/core/code-skeleton.ts

@@ -1,4 +1,4 @@
-// Deterministic, dependency-free code skeleton extraction (spec 21 phase 3).
+// Deterministic, dependency-free code skeleton extraction (spec 22 phase 3).
 //
 // Produces a structural outline of source: top-level declarations and the direct
 // members of classes/interfaces, with function/method bodies elided to "{ … }".

package/src/core/compress-tool-output.ts

@@ -1,12 +1,12 @@
-// Compression pipeline orchestrator (spec 21). Ties together the config/holdout
+// Compression pipeline orchestrator (spec 22). Ties together the config/holdout
 // decisions, the pure engine, the reversible cache, and the ledger. Returns the
 // replacement text to emit, or null to pass the original through unchanged.
 //
 // Invariants:
-// - Disabled by default (config gate) → no-op.
+// - Enabled by default; the config gate still allows opt-out → no-op when off.
 // - Reversible or nothing: the original is stored BEFORE we return a compressed
 //   result; if storage fails we pass the original through, so a compressed
-//   result is never shown without a retrievable original (spec 21 edge case).
+//   result is never shown without a retrievable original (spec 22 edge case).
 // - Every failure degrades to "no compression" — a hook must never throw.
 // - Holdout arms pass the original through but are still measured.
 
@@ -23,7 +23,7 @@ import { CompressionCacheRepo } from "../repositories/compression-cache-repo";
 import { TokenLedgerRepo } from "../repositories/token-ledger-repo";
 
 // Deterministic FNV-1a → hex, used as a stable per-event key so an identical
-// output always lands in the same holdout arm (spec 21 edge case).
+// output always lands in the same holdout arm (spec 22 edge case).
 function contentKey(s: string): string {
   let h = 0x811c9dc5;
   for (let i = 0; i < s.length; i++) {

package/src/core/compression.ts

@@ -1,10 +1,9 @@
-// Tool-output compression — configuration and decision logic (spec 21).
+// Tool-output compression — configuration and decision logic (spec 22).
 //
 // This module is pure: it reads config and makes the eligibility / holdout /
 // min-savings decisions. It never touches the database or the tool payload, so
-// it is trivially testable. Phase 2 wires the actual compressors and the
-// reversible cache on top of these decisions; Phase 1 ships the measurement
-// instrument and leaves `enabled` off by default.
+// it is trivially testable. Compression is enabled by default; users opt out
+// with `mink config set compression.enabled false`.
 
 import { resolveConfigValue } from "./global-config";
 import type { ConfigKey } from "../types/config";
@@ -35,13 +34,13 @@ export function loadCompressionConfig(): CompressionConfig {
 }
 
 // An output is eligible for compression only once it crosses the size threshold;
-// small outputs are never touched (spec 21 §Eligibility).
+// small outputs are never touched (spec 22 §Eligibility).
 export function isEligible(originalTokens: number, config: CompressionConfig): boolean {
   return config.enabled && originalTokens >= config.thresholdTokens;
 }
 
 // A compression attempt is kept only if it saves at least the configured
-// fraction of tokens; otherwise the original is used (spec 21 §Thresholds).
+// fraction of tokens; otherwise the original is used (spec 22 §Thresholds).
 export function meetsMinSavings(
   originalTokens: number,
   compressedTokens: number,
@@ -58,7 +57,7 @@ export function measuredSavings(originalTokens: number, compressedTokens: number
 
 // Deterministic FNV-1a hash → a stable fraction in [0, 1) for a given key. Used
 // so holdout selection is stable per event: the same event always lands in the
-// same arm, which keeps measurement from being double-counted (spec 21 edge
+// same arm, which keeps measurement from being double-counted (spec 22 edge
 // case "Holdout selection must be stable for a given event").
 function hashUnitInterval(key: string): number {
   let h = 0x811c9dc5;

package/src/core/dashboard-api.ts

@@ -201,7 +201,7 @@ export function loadTokenLedgerPanel(cwd: string): TokenLedgerPayload {
   };
 }
 
-// Dedicated Compression panel (spec 21, phase 4). Reads the measured
+// Dedicated Compression panel (spec 22, phase 4). Reads the measured
 // compression aggregates, the holdout A/B split, per-kind/per-tool breakdowns,
 // and recent events, plus whether compression is currently enabled.
 export function loadCompressionPanel(cwd: string): CompressionPayload {

package/src/core/hook-output.ts

@@ -1,4 +1,4 @@
-// Helpers for PostToolUse hooks that replace a tool's result (spec 21). The
+// Helpers for PostToolUse hooks that replace a tool's result (spec 22). The
 // replacement mechanism is Claude Code's `hookSpecificOutput.updatedToolOutput`
 // (verified against the hooks reference): whatever JSON we print to stdout here
 // substitutes the original output before the model sees it.

package/src/core/hook-refresh.ts

@@ -0,0 +1,81 @@
+// Self-healing hook regeneration.
+//
+// Mink's generated wiring — `.claude/settings.json` and `.pi/extensions/mink.ts`
+// — is produced by `mink init` and pinned at the version that wrote it. After the
+// package upgrades, those files can go stale (e.g. they lack a newly-added hook,
+// or the Pi adapter template changed) until the user re-runs `mink init`.
+//
+// To avoid that manual step we stamp the project metadata with the Mink version
+// that generated the hooks (`hooksVersion`) and refresh when it changes:
+//   - lazily, per project, on `session-start` (refreshHooksIfStale), and
+//   - eagerly, across all registered projects, right after a successful upgrade
+//     (`mink refresh-hooks --all`, spawned as the freshly-installed binary).
+//
+// Both paths regenerate ONLY the hosts a project already uses and are defensive:
+// a failure degrades to "no refresh" and the next session-start tries again.
+
+import { projectMetaPath } from "./paths";
+import { safeReadJson, atomicWriteJson } from "./fs-utils";
+import { getInstallInfo } from "./self-update";
+
+export interface HookRefreshResult {
+  refreshed: boolean;
+  /** Hosts the project is wired for (claude/pi). */
+  agents: string[];
+  /** The Mink version now stamped, or null when nothing could be resolved. */
+  version: string | null;
+}
+
+const SKIP: HookRefreshResult = { refreshed: false, agents: [], version: null };
+
+/**
+ * Regenerate a single project's hooks for exactly the agents it already uses,
+ * then stamp the generating Mink version. With `force` off (session-start) it
+ * only acts when the stamp differs from the running version; with `force` on
+ * (`refresh-hooks`) it always regenerates. Never throws.
+ */
+export function refreshProjectHooks(
+  cwd: string,
+  opts: { force?: boolean } = {}
+): HookRefreshResult {
+  try {
+    const metaPath = projectMetaPath(cwd);
+    const meta = safeReadJson(metaPath) as Record<string, unknown> | null;
+    if (!meta) return SKIP; // never initialized here → nothing to refresh
+    const agents = Array.isArray(meta.agents) ? (meta.agents as string[]) : [];
+    if (agents.length === 0) return SKIP;
+
+    const current = getInstallInfo().currentVersion;
+    const stamped = typeof meta.hooksVersion === "string" ? meta.hooksVersion : null;
+    if (!opts.force && stamped === current) {
+      return { refreshed: false, agents, version: current };
+    }
+
+    rewireAgents(cwd, agents);
+    atomicWriteJson(metaPath, { ...meta, hooksVersion: current });
+    return { refreshed: true, agents, version: current };
+  } catch {
+    return SKIP;
+  }
+}
+
+/** Session-start convenience: refresh only when the version stamp is stale. */
+export function refreshHooksIfStale(cwd: string): HookRefreshResult {
+  return refreshProjectHooks(cwd);
+}
+
+function rewireAgents(cwd: string, agents: string[]): void {
+  // Lazy-require the installers so the common (up-to-date) path stays cheap and
+  // we avoid any import cycle (init.ts is heavy and pulls in the agent wiring).
+  const { resolveCliPath, installClaude } = require("../commands/init");
+  const { installPi } = require("./agent-pi");
+  const cliPath = resolveCliPath();
+  for (const agent of agents) {
+    try {
+      if (agent === "claude") installClaude(cwd, cliPath);
+      else if (agent === "pi") installPi(cwd, cliPath);
+    } catch {
+      // Per-agent best-effort; one host failing must not block the others.
+    }
+  }
+}

package/src/core/output-compression.ts

@@ -1,4 +1,4 @@
-// Tool-output compression engine (spec 21 §Content-Aware Compression).
+// Tool-output compression engine (spec 22 §Content-Aware Compression).
 //
 // Pure, deterministic, dependency-free. Each compressor takes a tool output
 // string and returns a smaller body plus a note of what was dropped, or null
@@ -8,7 +8,7 @@
 // "mink retrieve" footer. Keeping this layer pure makes every strategy trivially
 // testable and prompt-cache-stable (identical input → identical output).
 //
-// The "file" strategy does line-based signature extraction; spec 21's phase 3
+// The "file" strategy does line-based signature extraction; spec 22's phase 3
 // upgrades it to richer AST skeletons behind this same interface.
 
 import type { ContentKind, CompressionResult } from "../types/compression";

package/src/core/prompt.ts

@@ -0,0 +1,27 @@
+import { createInterface } from "readline";
+
+/**
+ * Whether the current process can safely prompt the user. We require a real
+ * interactive TTY on both stdin and stdout and honor the usual escape hatches
+ * (CI, an explicit opt-out) so `mink init` never blocks a script or pipeline.
+ */
+export function stdinIsInteractive(): boolean {
+  const stdin = process.stdin as NodeJS.ReadStream & { isTTY?: boolean };
+  const stdout = process.stdout as NodeJS.WriteStream & { isTTY?: boolean };
+  return (
+    Boolean(stdin.isTTY) &&
+    Boolean(stdout.isTTY) &&
+    process.env.MINK_NO_PROMPT !== "1" &&
+    !process.env.CI
+  );
+}
+
+export function ask(question: string): Promise<string> {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer);
+    });
+  });
+}

package/src/core/self-update.ts

@@ -232,9 +232,24 @@ function rotateLogIfNeeded(path: string): void {
 export async function runSelfUpgrade(opts: UpgradeOptions): Promise<UpgradeResult> {
   const result = await runSelfUpgradeInner(opts);
   appendLogEntry({ source: opts.source, ...result });
+  if (result.status === "upgraded") refreshHooksAfterUpgrade();
   return result;
 }
 
+// After a successful self-upgrade the running process is still the OLD code, so
+// regenerating hooks here would write stale templates. Instead spawn the
+// freshly-installed `mink` to refresh every project — it runs the NEW code and
+// stamps the new version. Best-effort: if it fails, each project's session-start
+// self-heal is the fallback. Skipped in dev mode (no global `mink` to invoke).
+function refreshHooksAfterUpgrade(): void {
+  try {
+    if (getInstallInfo().isDevMode) return;
+    spawnSync("mink", ["refresh-hooks", "--all"], { stdio: "ignore" });
+  } catch {
+    // Best-effort; session-start covers any project we miss here.
+  }
+}
+
 async function runSelfUpgradeInner(opts: UpgradeOptions): Promise<UpgradeResult> {
   // 1. Hard kill switch.
   if (process.env.MINK_DISABLE_AUTO_UPDATE === "1" && opts.source === "scheduler") {

package/src/repositories/compression-cache-repo.ts

@@ -1,4 +1,4 @@
-// Reversible-compression cache repository (spec 21 §Reversibility). Stores the
+// Reversible-compression cache repository (spec 22 §Reversibility). Stores the
 // byte-exact original of a compressed tool output keyed by a short retrieval
 // token, with a TTL. `get` treats an expired row as a miss and evicts it lazily,
 // so a stale token can never return partial or wrong content.

package/src/repositories/token-ledger-repo.ts

@@ -239,7 +239,7 @@ export class TokenLedgerRepo {
     });
   }
 
-  // ── Compression measurement (spec 21) ────────────────────────────────
+  // ── Compression measurement (spec 22) ────────────────────────────────
 
   // Record one compression decision and fold it into this device's
   // compression-lifetime aggregates, transactionally so the row and the

package/src/storage/schema.ts

@@ -177,7 +177,7 @@ CREATE TABLE IF NOT EXISTS counters (
   file_index_misses INTEGER NOT NULL DEFAULT 0
 );
 
--- Tool-output compression measurement (spec 21). One row per compression
+-- Tool-output compression measurement (spec 22). One row per compression
 -- decision: either a compressed arm (compressed_tokens < original_tokens) or a
 -- holdout arm (left uncompressed for control, compressed_tokens = original_tokens).
 -- These are append-only telemetry, independent of session lifecycle, written at
@@ -208,7 +208,7 @@ CREATE TABLE IF NOT EXISTS ledger_compression_lifetime (
   total_measured_savings  INTEGER NOT NULL DEFAULT 0
 );
 
--- Reversible-compression cache (spec 21 §Reversibility). When a tool output is
+-- Reversible-compression cache (spec 22 §Reversibility). When a tool output is
 -- compressed, the original is stored here keyed by a short retrieval token and
 -- embedded in the compressed result; "mink retrieve <token>" returns it
 -- byte-exact. Rows expire after the configured retention window; an expired or

package/src/types/compression.ts

@@ -1,4 +1,4 @@
-// Tool-output compression types (spec 21). The decision/config types live in
+// Tool-output compression types (spec 22). The decision/config types live in
 // src/core/compression.ts; these describe the reversible cache and the engine's
 // content-aware output.