chainlesschain 0.162.148 → 0.162.150

package/src/repl/agent-repl.js

@@ -64,6 +64,7 @@ import {
   PromptCompressor,
   getContextWindow,
 } from "../harness/prompt-compressor.js";
+import { buildAutoPinPredicate } from "../runtime/auto-pin.js";
 import { feature } from "../lib/feature-flags.js";
 import { recordCompressionMetric } from "../lib/compression-telemetry.js";
 import {
@@ -121,6 +122,20 @@ let _permissionConfirm = null;
 let _managedPermissionRulesOnly = false;
 // .claude/settings.json `hooks` block (decision-capable PreToolUse/PostToolUse).
 let _settingsHooks = null;
+// Installed-plugin background monitors (Phase 3.3i) — a supervisor owning any
+// long-running/interval watcher processes a trusted plugin declared; reaped in
+// the SessionEnd cleanup so nothing outlives the REPL.
+let _pluginMonitors = null;
+// Installed-plugin `bin` PATH injection (Phase 3.3n) — restore() puts PATH back
+// at SessionEnd so plugin executables are only resolvable during the session.
+let _pluginBinRestore = null;
+// Installed-plugin `settings` default env (Phase 3.3o) — restore() removes the
+// plugin-provided env-var defaults at SessionEnd (session-scoped).
+let _pluginSettingsRestore = null;
+// Async settings-hook supervisor (Phase 6) — owns fire-and-forget `async:true`
+// hook processes; their results/rewakes drain into the next turn's context.
+// Lazily created when the first async hook is dispatched; reaped at SessionEnd.
+let _asyncHookSupervisor = null;
 // .claude/settings.json `respondToBashCommands` (Claude-Code 2.1.186): whether a
 // `!command` auto-triggers an assistant response to its output. undefined =
 // unset → defaults OFF (opt-in) in shouldRespondToBashCommands.
@@ -402,10 +417,15 @@ export async function startAgentRepl(options = {}) {
   // Unset → agent-core's 180s default (matches cc chat/ask). Set to 0 to
   // disable. Left undefined here means "use the default".
   let _streamStallTimeoutMs;
+  // Auto-pin (OPT-IN, off by default): when set, compaction pins the original
+  // task. Resolved from config `context.autoPin` or CC_AUTO_PIN=1; falsy → the
+  // compress calls below pass no pin predicate (byte-identical default).
+  let _autoPinOpt;
   try {
     const { loadConfig } = await import("../lib/config-manager.js");
     const _cfg = loadConfig();
     _visionModel = _cfg?.llm?.visionModel || undefined;
+    _autoPinOpt = _cfg?.context?.autoPin;
     const raw = _cfg?.llm?.streamStallTimeoutMs;
     const t = Number(raw);
     // Accept 0 (explicit disable) — only ignore absent/invalid values.
@@ -436,10 +456,12 @@ export async function startAgentRepl(options = {}) {
   const _fallbackChatFn = _fallbackModels.length
     ? makeFallbackChatFn({
         fallbackModels: _fallbackModels,
-        onFallback: ({ from, to, error }) =>
+        onFallback: ({ from, to, error, skipped, reason, crossProvider }) =>
           logger.info(
             chalk.yellow(
-              `[fallback] model "${from}" failed (${error}); retrying with "${to}"`,
+              skipped
+                ? `[fallback] "${to}" skipped (${reason})`
+                : `[fallback] model "${from}" failed (${error}); retrying with ${crossProvider ? "cross-provider " : ""}"${to}"`,
             ),
           ),
       })
@@ -461,6 +483,15 @@ export async function startAgentRepl(options = {}) {
   if (feature("PROMPT_COMPRESSOR")) {
     _compressor = new PromptCompressor({ model, provider });
   }
+  if (process.env.CC_AUTO_PIN === "1") _autoPinOpt = _autoPinOpt || true;
+  // Compaction options shared by /compact + auto-compact. Adds the opt-in
+  // pin predicate only when auto-pin is enabled; otherwise byte-identical.
+  const _compactOpts = (msgs) => {
+    const base = { preserveToolPairs: true };
+    if (!_autoPinOpt) return base;
+    const isPinned = buildAutoPinPredicate(msgs, _autoPinOpt);
+    return isPinned ? { ...base, isPinned } : base;
+  };
 
   // Initialize permanent memory
   let permanentMemory = null;
@@ -610,9 +641,14 @@ export async function startAgentRepl(options = {}) {
     const { loadHooks, projectHookTrustNotice } =
       await import("../lib/settings-hooks.cjs");
     const loaded = loadHooks({ cwd: process.cwd() });
+    // Fold in installed plugins' hooks/hooks.json (Phase 3.3c).
+    const { mergePluginHooks } = await import("../lib/plugin-runtime/hooks.js");
+    const effectiveHooks = mergePluginHooks(loaded.hooks, {
+      cwd: process.cwd(),
+    });
     _settingsHooks =
-      loaded.hooks && Object.keys(loaded.hooks).length > 0
-        ? loaded.hooks
+      effectiveHooks && Object.keys(effectiveHooks).length > 0
+        ? effectiveHooks
         : null;
     // First-run trust notice for an untrusted/cloned repo's shell-running
     // hooks (Claude-Code 2.1.195 parity). Best-effort, stderr-only.
@@ -626,6 +662,60 @@ export async function startAgentRepl(options = {}) {
     _settingsHooks = null;
   }
 
+  // Start installed plugins' background monitors (Phase 3.3i). Trust-gated
+  // inside collectPluginMonitors — only user/local-scope and explicitly-trusted
+  // project plugins get a process spawned. Reaped in the SessionEnd cleanup +
+  // a process-exit backstop, so no monitor outlives the session.
+  try {
+    const { collectPluginMonitors } =
+      await import("../lib/plugin-runtime/monitors.js");
+    const monitors = collectPluginMonitors({ cwd: process.cwd() });
+    if (monitors.length > 0) {
+      const { PluginMonitorSupervisor } =
+        await import("../lib/plugin-monitor-supervisor.js");
+      _pluginMonitors = new PluginMonitorSupervisor();
+      const started = _pluginMonitors.start(monitors);
+      if (started.length > 0) {
+        process.stderr.write(
+          `  monitors: started ${started.length} from trusted plugin(s): ${started.join(", ")}\n`,
+        );
+      }
+    }
+  } catch (_err) {
+    _pluginMonitors = null;
+  }
+
+  // Put trusted plugins' bin/ executables on PATH for the session (Phase 3.3n),
+  // restored at SessionEnd. Trust-gated inside collectPluginBinDirs.
+  try {
+    const { applyPluginBinPath } = await import("../lib/plugin-runtime/bin.js");
+    const res = applyPluginBinPath({ cwd: process.cwd() });
+    _pluginBinRestore = res.restore;
+    if (res.added.length > 0) {
+      process.stderr.write(
+        `  bin: added ${res.added.length} plugin bin dir(s) to PATH\n`,
+      );
+    }
+  } catch (_err) {
+    _pluginBinRestore = null;
+  }
+
+  // Apply trusted plugins' default env vars (Phase 3.3o) — only for env keys the
+  // user/system didn't already set; restored at SessionEnd.
+  try {
+    const { applyPluginSettingsEnv } =
+      await import("../lib/plugin-runtime/settings.js");
+    const res = applyPluginSettingsEnv({ cwd: process.cwd() });
+    _pluginSettingsRestore = res.restore;
+    if (res.added.length > 0) {
+      process.stderr.write(
+        `  settings: applied ${res.added.length} plugin env default(s)\n`,
+      );
+    }
+  } catch (_err) {
+    _pluginSettingsRestore = null;
+  }
+
   // Resume existing session or create new one
   const useJsonl = feature("JSONL_SESSION");
 
@@ -980,6 +1070,27 @@ export async function startAgentRepl(options = {}) {
     } catch (_err) {
       // Non-critical
     }
+    // settings.json SessionResume hooks: a persisted transcript was just
+    // replayed into this interactive session (distinct from SessionStart).
+    // Observe-only, best-effort — never blocks entering the REPL.
+    if (_settingsHooks && messages.some((m) => m.role !== "system")) {
+      try {
+        const { runObserveHooks } =
+          await import("../lib/settings-hook-events.cjs");
+        runObserveHooks(
+          _settingsHooks,
+          "SessionResume",
+          {
+            session_id: sessionId,
+            resumed_from: sessionId,
+            cwd: process.cwd(),
+          },
+          { cwd: process.cwd() },
+        );
+      } catch {
+        /* observe-only */
+      }
+    }
     // Resume recap (offline, extractive — no LLM): a quick "where were we"
     // so the user doesn't have to scroll the old transcript.
     try {
@@ -1091,6 +1202,7 @@ export async function startAgentRepl(options = {}) {
       "/quit",
       "/reindex",
       "/release-notes",
+      "/reload-plugins",
       "/reload-skills",
       "/review",
       "/rewind",
@@ -1217,6 +1329,25 @@ export async function startAgentRepl(options = {}) {
           /* already aborted */
         }
         _turnAbort = null;
+        // settings.json SessionPause hooks: the user interrupted the in-flight
+        // turn — the session stays open, the current work is suspended. The
+        // keypress handler can't await, so fire observe-only fire-and-forget.
+        if (_settingsHooks) {
+          import("../lib/settings-hook-events.cjs")
+            .then(({ runObserveHooks }) =>
+              runObserveHooks(
+                _settingsHooks,
+                "SessionPause",
+                {
+                  session_id: sessionId,
+                  reason: "user-interrupt",
+                  cwd: process.cwd(),
+                },
+                { cwd: process.cwd() },
+              ),
+            )
+            .catch(() => {});
+        }
         return;
       }
 
@@ -1604,6 +1735,9 @@ export async function startAgentRepl(options = {}) {
       logger.log(
         `  ${chalk.cyan("/reload-skills")} Re-scan skill layers without restarting`,
       );
+      logger.log(
+        `  ${chalk.cyan("/reload-plugins")} Re-scan installed plugins after add/trust/upgrade`,
+      );
       logger.log(
         `  ${chalk.cyan("/review")}     Diff-first code review (/review [high] [--security|--simplify] [--fix])`,
       );
@@ -2414,7 +2548,7 @@ export async function startAgentRepl(options = {}) {
       if (_compressor && messages.length > 3) {
         const { messages: compacted, stats } = await _compressor.compress(
           messages,
-          { preserveToolPairs: true },
+          _compactOpts(messages),
         );
         messages.length = 0;
         messages.push(...compacted);
@@ -2564,6 +2698,117 @@ export async function startAgentRepl(options = {}) {
       return;
     }
 
+    // `/reload-plugins` (Phase 3.3m): re-scan installed plugins after an
+    // install / trust / upgrade WITHOUT restarting — resets memoized LSP
+    // registration + managed-policy/trust caches, re-merges the effective hook
+    // map, and restarts the monitor supervisor with the fresh set. Already-
+    // connected MCP servers stay for this session (new ones load next session).
+    if (trimmed === "/reload-plugins") {
+      try {
+        const cwd = process.cwd();
+        const { reloadPluginRuntime } =
+          await import("../lib/plugin-runtime/reload.js");
+        const sum = reloadPluginRuntime({ cwd });
+
+        // Re-merge plugin hooks onto the user's settings hooks (live session).
+        try {
+          const { loadHooks } = await import("../lib/settings-hooks.cjs");
+          const { mergePluginHooks } =
+            await import("../lib/plugin-runtime/hooks.js");
+          const base = loadHooks({ cwd }).hooks;
+          const merged = mergePluginHooks(base, { cwd });
+          _settingsHooks =
+            merged && Object.keys(merged).length > 0 ? merged : null;
+        } catch {
+          /* hooks re-merge is best-effort */
+        }
+
+        // settings.json ConfigChange hooks (Claude-Code parity): the live
+        // hooks / permissions / trusted-plugin set just changed, so fire
+        // ConfigChange with the FRESH hook set — a policy hook can observe or
+        // react (e.g. re-audit the newly-trusted config). Best-effort.
+        if (_settingsHooks) {
+          try {
+            const { runObserveHooks, dispatchAsyncHooks } =
+              await import("../lib/settings-hook-events.cjs");
+            const payload = {
+              session_id: sessionId || null,
+              source: "reload-plugins",
+            };
+            runObserveHooks(_settingsHooks, "ConfigChange", payload, { cwd });
+            if (!_asyncHookSupervisor) {
+              const { AsyncHookSupervisor } =
+                await import("../lib/async-hook-supervisor.cjs");
+              _asyncHookSupervisor = new AsyncHookSupervisor();
+            }
+            dispatchAsyncHooks(_settingsHooks, "ConfigChange", payload, {
+              cwd,
+              supervisor: _asyncHookSupervisor,
+            });
+          } catch {
+            /* ConfigChange hooks are best-effort */
+          }
+        }
+
+        // Restart background monitors with the fresh, trust-gated set.
+        try {
+          const { collectPluginMonitors } =
+            await import("../lib/plugin-runtime/monitors.js");
+          if (_pluginMonitors) {
+            _pluginMonitors.stopAll();
+            _pluginMonitors = null;
+          }
+          const monitors = collectPluginMonitors({ cwd });
+          if (monitors.length > 0) {
+            const { PluginMonitorSupervisor } =
+              await import("../lib/plugin-monitor-supervisor.js");
+            _pluginMonitors = new PluginMonitorSupervisor();
+            _pluginMonitors.start(monitors);
+          }
+        } catch {
+          /* monitor restart is best-effort */
+        }
+
+        // Re-apply plugin bin PATH (a newly-trusted plugin's executables).
+        try {
+          const { applyPluginBinPath } =
+            await import("../lib/plugin-runtime/bin.js");
+          if (_pluginBinRestore) _pluginBinRestore();
+          const res = applyPluginBinPath({ cwd });
+          _pluginBinRestore = res.restore;
+        } catch {
+          /* bin re-apply is best-effort */
+        }
+
+        // Re-apply plugin default env vars (a newly-trusted plugin's settings).
+        try {
+          const { applyPluginSettingsEnv } =
+            await import("../lib/plugin-runtime/settings.js");
+          if (_pluginSettingsRestore) _pluginSettingsRestore();
+          const res = applyPluginSettingsEnv({ cwd });
+          _pluginSettingsRestore = res.restore;
+        } catch {
+          /* settings re-apply is best-effort */
+        }
+
+        logger.log(
+          chalk.green(
+            `✔ plugins reloaded — ${sum.plugins} plugin(s): ` +
+              `${sum.skills} skill layer(s), ${sum.agents} agent dir(s), ` +
+              `${sum.lspRegistered} LSP server(s), ${sum.hooks} hook event(s), ` +
+              `${sum.mcp} MCP server(s), ${sum.monitors} monitor(s)`,
+          ),
+        );
+        logger.log(
+          chalk.gray("  (newly-added MCP servers connect on the next session)"),
+        );
+      } catch (err) {
+        logger.error(`/reload-plugins failed: ${err.message}`);
+      }
+      prompt();
+      return;
+    }
+
     // `/review` — diff-first code review of your changes (Claude-Code
     // /code-review parity). Reuses the `cc review` machinery: collects the git
     // diff and runs ONE focused agent turn. Read-only by default; `--fix`
@@ -3743,11 +3988,95 @@ export async function startAgentRepl(options = {}) {
         if (ups.additionalContext) {
           userContent += `\n\n[hook context]\n${ups.additionalContext}`;
         }
+        // Fire-and-forget the `async:true` UserPromptSubmit hooks (Phase 6): a
+        // long-running check (background tests, CI status) runs ALONGSIDE this
+        // turn without blocking it; its result/rewake surfaces on a later turn
+        // via the async-hook drain below. Lazily create the supervisor.
+        const { dispatchAsyncHooks } =
+          await import("../lib/settings-hook-events.cjs");
+        if (!_asyncHookSupervisor) {
+          const { AsyncHookSupervisor } =
+            await import("../lib/async-hook-supervisor.cjs");
+          _asyncHookSupervisor = new AsyncHookSupervisor();
+        }
+        dispatchAsyncHooks(
+          _settingsHooks,
+          "UserPromptSubmit",
+          { prompt: userContent },
+          { cwd: process.cwd(), supervisor: _asyncHookSupervisor },
+        );
       } catch (_err) {
         // settings hook dispatch is best-effort
       }
     }
 
+    // Plugin background-monitor output (Phase 3.3i/Phase 6): surface anything a
+    // trusted plugin's monitor captured SINCE the last turn as additionalContext,
+    // so the agent sees e.g. a background test failure or a tailed log on its
+    // next turn. Drained (cleared) so each line is shown once; bounded so a noisy
+    // monitor can't blow up the prompt.
+    if (_pluginMonitors) {
+      try {
+        const recs = _pluginMonitors.drainOutputs();
+        if (recs.length > 0) {
+          const shown = recs.slice(-40);
+          const lines = shown
+            .map((r) => `  [${r.monitor}/${r.stream}] ${r.line}`)
+            .join("\n");
+          const omitted =
+            recs.length > shown.length
+              ? `\n  … (${recs.length - shown.length} earlier line(s) omitted)`
+              : "";
+          userContent += `\n\n[plugin monitors — new output since last turn]\n${lines}${omitted}`;
+        }
+      } catch (_err) {
+        // monitor drain is best-effort — never blocks a turn
+      }
+    }
+
+    // Async settings-hook output (Phase 6): fold in any `async:true` hook that
+    // FINISHED since the last turn. Failed `asyncRewake` hooks are surfaced
+    // first + prominently (the "rewake" — a background test failure re-engages
+    // the agent with the structured error) followed by the plain results.
+    // Drained (cleared) so each is shown once.
+    if (_asyncHookSupervisor) {
+      try {
+        const rewakes = _asyncHookSupervisor.drainRewakes();
+        const results = _asyncHookSupervisor.drainResults();
+        if (rewakes.length > 0) {
+          const lines = rewakes
+            .map(
+              (r) =>
+                `  ✗ ${r.command}${r.event ? ` (${r.event})` : ""}: ${
+                  r.error || "failed"
+                }`,
+            )
+            .join("\n");
+          userContent += `\n\n[async hook — REWAKE: a background hook failed, address it]\n${lines}`;
+        }
+        // Non-rewake informational results (successful context / non-opted
+        // failures). Rewake records already shown above are excluded to avoid
+        // duplication.
+        const info = results.filter((r) => !(r.asyncRewake === true && !r.ok));
+        const ctxLines = info
+          .map((r) => {
+            if (r.skipped) return `  … ${r.command}: ${r.error}`;
+            if (r.ok && r.additionalContext)
+              return `  ✔ ${r.command}: ${r.additionalContext}`;
+            if (!r.ok) return `  ✗ ${r.command}: ${r.error || "failed"}`;
+            return null;
+          })
+          .filter(Boolean);
+        if (ctxLines.length > 0) {
+          userContent += `\n\n[async hooks — finished since last turn]\n${ctxLines
+            .slice(-20)
+            .join("\n")}`;
+        }
+      } catch (_err) {
+        // async-hook drain is best-effort — never blocks a turn
+      }
+    }
+
     // IDE live context (Claude-Code parity): re-shared on every prompt while
     // an IDE bridge is connected — the user's selection moves between turns.
     // Ephemeral: persistence stores effectivePrompt, not this snapshot.
@@ -3933,6 +4262,14 @@ export async function startAgentRepl(options = {}) {
       // merge fires exactly once (2.1.187 parity; see _sanitizeRolesNextTurn).
       const _mergeRolesThisTurn = _sanitizeRolesNextTurn;
       _sanitizeRolesNextTurn = false;
+      // Ensure the async-hook supervisor exists so `async:true` PostToolUse
+      // hooks (fired inside the loop, per tool call) can be dispatched
+      // fire-and-forget; their results/rewakes drain into the next turn above.
+      if (_settingsHooks && !_asyncHookSupervisor) {
+        const { AsyncHookSupervisor } =
+          await import("../lib/async-hook-supervisor.cjs");
+        _asyncHookSupervisor = new AsyncHookSupervisor();
+      }
       const {
         content: response,
         usageEvents,
@@ -3996,6 +4333,7 @@ export async function startAgentRepl(options = {}) {
         permissionRules: _permissionRules,
         permissionConfirm: _permissionConfirm,
         settingsHooks: _settingsHooks,
+        hookSupervisor: _asyncHookSupervisor,
         classifyAllShell: _classifyAllShell,
         // Interactive session: gate run_code through the ApprovalGate (like
         // run_shell) so a strict tier prompts before arbitrary code runs.
@@ -4137,7 +4475,7 @@ export async function startAgentRepl(options = {}) {
         try {
           const { messages: compacted, stats } = await _compressor.compress(
             messages,
-            { preserveToolPairs: true },
+            _compactOpts(messages),
           );
           messages.length = 0;
           messages.push(...compacted);
@@ -4171,6 +4509,37 @@ export async function startAgentRepl(options = {}) {
           // Non-critical
         }
       }
+
+      // settings.json Stop hooks (Claude-Code parity): the agent just finished a
+      // turn. Sync Stop hooks observe; `async:true` Stop hooks fire-and-forget
+      // (the canonical "run the test suite after the turn" trigger) with their
+      // results/rewakes drained into the NEXT turn's context (see the async-hook
+      // drain above). Best-effort — never break turn completion.
+      if (_settingsHooks) {
+        try {
+          const { runObserveHooks, dispatchAsyncHooks } =
+            await import("../lib/settings-hook-events.cjs");
+          runObserveHooks(
+            _settingsHooks,
+            "Stop",
+            { session_id: sessionId || null },
+            { cwd: process.cwd() },
+          );
+          if (!_asyncHookSupervisor) {
+            const { AsyncHookSupervisor } =
+              await import("../lib/async-hook-supervisor.cjs");
+            _asyncHookSupervisor = new AsyncHookSupervisor();
+          }
+          dispatchAsyncHooks(
+            _settingsHooks,
+            "Stop",
+            {},
+            { cwd: process.cwd(), supervisor: _asyncHookSupervisor },
+          );
+        } catch (_e) {
+          // Stop-hook dispatch is best-effort
+        }
+      }
     } catch (err) {
       _turnAbort = null;
       // Esc interrupt: an aborted turn is normal flow, not an error — the
@@ -4331,6 +4700,48 @@ export async function startAgentRepl(options = {}) {
       // Non-critical
     }
 
+    // Reap plugin background monitors (Phase 3.3i) — clear interval timers and
+    // SIGTERM every watcher child so no monitor process outlives the session.
+    if (_pluginMonitors) {
+      try {
+        _pluginMonitors.stopAll();
+      } catch (_e) {
+        // Non-critical
+      }
+      _pluginMonitors = null;
+    }
+
+    // Reap async settings-hook processes (Phase 6) — SIGTERM any fire-and-forget
+    // `async:true` hook still running so none outlives the session.
+    if (_asyncHookSupervisor) {
+      try {
+        _asyncHookSupervisor.stopAll();
+      } catch (_e) {
+        // Non-critical
+      }
+      _asyncHookSupervisor = null;
+    }
+
+    // Restore PATH — drop the plugin bin dirs added at startup (Phase 3.3n).
+    if (_pluginBinRestore) {
+      try {
+        _pluginBinRestore();
+      } catch (_e) {
+        // Non-critical
+      }
+      _pluginBinRestore = null;
+    }
+
+    // Drop plugin-provided default env vars added at startup (Phase 3.3o).
+    if (_pluginSettingsRestore) {
+      try {
+        _pluginSettingsRestore();
+      } catch (_e) {
+        // Non-critical
+      }
+      _pluginSettingsRestore = null;
+    }
+
     // Shutdown runtime
     try {
       await shutdown();

package/src/runtime/__tests__/auto-pin.test.js

@@ -0,0 +1,104 @@
+/**
+ * auto-pin policy tests — the OPT-IN compaction pin policy. Verifies it is off
+ * by default (returns null → caller passes no predicate → byte-identical), and
+ * when enabled pins the original task (first user turn) plus explicit pins,
+ * honoring the token cap.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  resolveAutoPinConfig,
+  buildAutoPinPredicate,
+  describeAutoPin,
+} from "../auto-pin.js";
+
+const MSGS = [
+  { role: "system", content: "you are a coding agent" },
+  { role: "user", content: "Refactor the auth module to use async/await" },
+  { role: "assistant", content: "ok, reading files" },
+  { role: "user", content: "also add tests" },
+];
+
+describe("resolveAutoPinConfig", () => {
+  it("returns null when off (falsy)", () => {
+    expect(resolveAutoPinConfig(undefined)).toBeNull();
+    expect(resolveAutoPinConfig(false)).toBeNull();
+    expect(resolveAutoPinConfig(0)).toBeNull();
+  });
+  it("defaults firstUserGoal on when enabled with true", () => {
+    expect(resolveAutoPinConfig(true)).toMatchObject({ firstUserGoal: true });
+  });
+  it("accepts an object and can disable firstUserGoal", () => {
+    expect(resolveAutoPinConfig({ firstUserGoal: false })).toMatchObject({
+      firstUserGoal: false,
+    });
+    expect(resolveAutoPinConfig({ maxPinTokens: 50 }).maxPinTokens).toBe(50);
+  });
+});
+
+describe("buildAutoPinPredicate", () => {
+  it("returns null when auto-pin is off (→ default compaction, byte-identical)", () => {
+    expect(buildAutoPinPredicate(MSGS, false)).toBeNull();
+    expect(buildAutoPinPredicate(MSGS, undefined)).toBeNull();
+  });
+
+  it("pins the first user turn (the original task) when enabled", () => {
+    const isPinned = buildAutoPinPredicate(MSGS, true);
+    expect(isPinned(MSGS[1])).toBe(true); // first user
+    expect(isPinned(MSGS[3])).toBe(false); // second user NOT pinned
+    expect(isPinned(MSGS[0])).toBe(false); // system not pinned
+    expect(isPinned(MSGS[2])).toBe(false); // assistant not pinned
+  });
+
+  it("always honors explicit pins on top of the policy", () => {
+    const msgs = [
+      ...MSGS,
+      { role: "assistant", content: "important decision", pinned: true },
+      { role: "assistant", content: "legacy marker", _pin: true },
+    ];
+    const isPinned = buildAutoPinPredicate(msgs, true);
+    expect(isPinned(msgs[4])).toBe(true); // pinned:true
+    expect(isPinned(msgs[5])).toBe(true); // _pin
+  });
+
+  it("honors explicit pins even with firstUserGoal disabled", () => {
+    const msgs = [
+      MSGS[0],
+      MSGS[1],
+      { role: "user", content: "x", pinned: true },
+    ];
+    const isPinned = buildAutoPinPredicate(msgs, { firstUserGoal: false });
+    expect(isPinned(msgs[1])).toBe(false); // first user NOT auto-pinned
+    expect(isPinned(msgs[2])).toBe(true); // explicit pin still honored
+  });
+
+  it("skips a first user turn that exceeds the token cap", () => {
+    const big = { role: "user", content: "x".repeat(10_000) }; // ~2500 tokens
+    const msgs = [MSGS[0], big, MSGS[2]];
+    const isPinned = buildAutoPinPredicate(msgs, { maxPinTokens: 100 });
+    expect(isPinned(big)).toBe(false); // too big to pin
+  });
+
+  it("matches by identity, not by value (compaction filters the same array)", () => {
+    const isPinned = buildAutoPinPredicate(MSGS, true);
+    const clone = { ...MSGS[1] }; // same content, different object
+    expect(isPinned(clone)).toBe(false);
+  });
+});
+
+describe("describeAutoPin", () => {
+  it("reports disabled when off", () => {
+    expect(describeAutoPin(MSGS, false)).toEqual({
+      enabled: false,
+      reasons: [],
+    });
+  });
+  it("explains the original-task pin", () => {
+    const d = describeAutoPin(MSGS, true);
+    expect(d.enabled).toBe(true);
+    expect(d.reasons.some((r) => r.why.includes("original task"))).toBe(true);
+    expect(d.reasons[d.reasons.length - 1].preview).toContain(
+      "Refactor the auth",
+    );
+  });
+});