chainlesschain 0.162.149 → 0.162.151

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 {
@@ -416,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.
@@ -477,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;
@@ -2533,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);
@@ -4460,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);

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",
+    );
+  });
+});

package/src/runtime/agent-core.js

@@ -221,6 +221,77 @@ export function killAllBackgroundShellTasks() {
   return killed;
 }
 
+// SYNCHRONOUS whole-tree kill for use inside a process 'exit' / signal handler,
+// where only synchronous work runs to completion (the async `spawn`/`taskkill`
+// in _killTask would be cut off the instant the process terminates, leaving the
+// grandchild orphaned). POSIX signals the process group with SIGKILL; Windows
+// uses spawnSync taskkill /T so the shell's children die too.
+function _killTaskSync(task) {
+  const child = task?.child;
+  if (!child || child.killed || task?.status !== "running") return false;
+  try {
+    if (process.platform === "win32") {
+      if (child.pid) {
+        spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+          windowsHide: true,
+        });
+      } else {
+        child.kill();
+      }
+    } else if (child.pid) {
+      // Negative pid → whole process group (requires the detached spawn above).
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch (_err) {
+        child.kill("SIGKILL");
+      }
+    } else {
+      child.kill("SIGKILL");
+    }
+    return true;
+  } catch (_err) {
+    return false;
+  }
+}
+
+/**
+ * Synchronously kill every still-running background shell task. Safe to call
+ * from a process 'exit' or signal handler (uses spawnSync/process.kill, not the
+ * async spawn path which a terminating process would cut off). This is the
+ * orphan-reclaim net for the paths the normal `finally` reaper can't cover: a
+ * Ctrl-C / SIGTERM unwinds no `finally`, so without it a backgrounded dev server
+ * outlives a killed `cc agent -p`.
+ * @returns {number} count of tasks signalled
+ */
+export function killAllBackgroundShellTasksSync() {
+  let killed = 0;
+  for (const task of _backgroundShellTasks.values()) {
+    if (_killTaskSync(task)) {
+      killed += 1;
+    }
+  }
+  return killed;
+}
+
+// Install a one-time process 'exit' net that synchronously reaps background
+// shell tasks. `finally` blocks (headless/REPL) already reap on normal
+// completion, but an explicit process.exit() elsewhere (serve shutdown, the
+// headless signal handler that converts Ctrl-C → exit) would otherwise leave a
+// backgrounded command orphaned. Installed lazily on the first background task,
+// so a process that never backgrounds anything pays nothing.
+let _bgExitReaperHooked = false;
+function _ensureBgExitReaper() {
+  if (_bgExitReaperHooked) return;
+  _bgExitReaperHooked = true;
+  process.once("exit", () => {
+    try {
+      killAllBackgroundShellTasksSync();
+    } catch {
+      /* best-effort teardown on exit */
+    }
+  });
+}
+
 // Idle-reap tuning (Claude-Code 2.1.193 "automatic memory-pressure reaping for
 // idle background shell commands"). A running task is a reap candidate when it
 // has produced no output for BG_IDLE_REAP_MS AND the system is under memory
@@ -324,16 +395,12 @@ async function runSettingsPreToolUseHooks(name, args, context, cwd) {
         ideResult: ide.result,
       };
     }
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const ok =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            rule: `hook:${outcome.hook}`,
-            reason: outcome.reason || "a PreToolUse hook requests confirmation",
-          })
-        : false;
+    const ok = await requestInteractivePermission(name, args, context, cwd, {
+      tool: name,
+      args,
+      rule: `hook:${outcome.hook}`,
+      reason: outcome.reason || "a PreToolUse hook requests confirmation",
+    });
     return ok
       ? { blocked: false }
       : {
@@ -345,6 +412,87 @@ async function runSettingsPreToolUseHooks(name, args, context, cwd) {
   return { blocked: false };
 }
 
+/**
+ * Run settings.json `PermissionRequest` hooks (Claude-Code parity). Fires at the
+ * exact moment a tool call would prompt the user for approval — BEFORE the
+ * prompt — so a policy hook can auto-approve (`allow`/`approve`), auto-reject
+ * (`deny`/`block`), or defer (`ask` / no decision) to the normal prompt.
+ * Returns `{ decision: "allow" | "deny" | null }`. No matching hook (or no
+ * `settingsHooks`) → `{ decision: null }` and the caller prompts exactly as
+ * before (default behaviour is byte-for-byte unchanged).
+ * @returns {{decision:("allow"|"deny"|null), reason?:string, hook?:string}}
+ */
+function runSettingsPermissionRequestHooks(name, args, context, cwd, reason) {
+  const matched = collectHooks(
+    context.settingsHooks,
+    "PermissionRequest",
+    name,
+  );
+  if (!matched || matched.length === 0) return { decision: null };
+  const payload = {
+    hook_event_name: "PermissionRequest",
+    tool_name: umbrellaFor(name),
+    raw_tool_name: name,
+    tool_input: args,
+    permission_reason: reason || null,
+    cwd,
+    session_id: context.sessionId || null,
+  };
+  const outcome = runCommandHooks(matched, payload, {
+    cwd,
+    event: "PermissionRequest",
+  });
+  // Precedence: deny > ask > allow > defer. The runner normalizes deny/block →
+  // "block" and short-circuits block/ask, but it COLLAPSES an "allow" into the
+  // aggregate "continue" (it only short-circuits block/ask) — so an explicit
+  // auto-approve must be recovered from the per-hook `results`. A deny or ask
+  // by any hook still wins over an allow (safety: never let an allow override a
+  // gate that another hook wanted to block or prompt for).
+  if (outcome.decision === "block") {
+    return { decision: "deny", reason: outcome.reason, hook: outcome.hook };
+  }
+  if (outcome.decision === "ask") {
+    return { decision: null }; // a hook asked → defer to the confirmer
+  }
+  const allowHook =
+    outcome.decision === "allow"
+      ? { command: outcome.hook }
+      : (outcome.results || []).find((r) => r && r.decision === "allow");
+  if (allowHook) {
+    return { decision: "allow", hook: allowHook.command || null };
+  }
+  return { decision: null }; // no actionable decision → defer to the confirmer
+}
+
+/**
+ * Resolve an interactive permission gate. Gives `PermissionRequest` hooks first
+ * say (auto-allow → true without prompting, auto-deny → false without
+ * prompting), then falls back to the injected confirmer with the identical
+ * arguments the call site would have passed. When no `PermissionRequest` hook
+ * matches this is byte-for-byte the previous `confirm(confirmArgs)` call, so
+ * every existing permission gate keeps its exact behaviour absent a hook.
+ * @returns {Promise<boolean>}
+ */
+async function requestInteractivePermission(
+  name,
+  args,
+  context,
+  cwd,
+  confirmArgs,
+) {
+  const verdict = runSettingsPermissionRequestHooks(
+    name,
+    args,
+    context,
+    cwd,
+    confirmArgs?.reason,
+  );
+  if (verdict.decision === "allow") return true;
+  if (verdict.decision === "deny") return false;
+  const confirm = context.permissionConfirm || context.shellConfirm || null;
+  return typeof confirm === "function" ? await confirm(confirmArgs) : false;
+}
+
 // ─── Tool definitions ────────────────────────────────────────────────────
 
 export const AGENT_TOOLS = getCodingAgentFunctionToolDefinitions();
@@ -1082,16 +1230,12 @@ export async function executeTool(name, args, context = {}) {
       source: "settings rule",
     });
     if (ide) return ide.result;
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const ok =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            rule: settingsVerdict.rule,
-            reason: `settings rule ${settingsVerdict.rule} requires confirmation`,
-          })
-        : false;
+    const ok = await requestInteractivePermission(name, args, context, cwd, {
+      tool: name,
+      args,
+      rule: settingsVerdict.rule,
+      reason: `settings rule ${settingsVerdict.rule} requires confirmation`,
+    });
     if (!ok) {
       return {
         error: `[Permission] Tool "${name}" requires confirmation (settings rule: ${settingsVerdict.rule}) but this run is non-interactive — denied. Do not retry; tell the user this action needs their approval.`,
@@ -1123,16 +1267,12 @@ export async function executeTool(name, args, context = {}) {
       await import("../lib/sensitive-file-guard.js");
     const sensReason = sensitiveFileReason(args.path);
     if (sensReason) {
-      const confirm = context.permissionConfirm || context.shellConfirm || null;
-      const ok =
-        typeof confirm === "function"
-          ? await confirm({
-              tool: name,
-              args,
-              rule: null,
-              reason: `sensitive file: ${sensReason}`,
-            })
-          : false;
+      const ok = await requestInteractivePermission(name, args, context, cwd, {
+        tool: name,
+        args,
+        rule: null,
+        reason: `sensitive file: ${sensReason}`,
+      });
       if (!ok) {
         return {
           error: `[Sensitive File] Writing "${args.path}" requires confirmation (${sensReason}) — denied. Add a settings allow rule to pre-authorize.`,
@@ -1155,16 +1295,12 @@ export async function executeTool(name, args, context = {}) {
     !planManager.isActive() &&
     isDangerousGitCommand(args?.command)
   ) {
-    const confirm = context.permissionConfirm || context.shellConfirm || null;
-    const ok =
-      typeof confirm === "function"
-        ? await confirm({
-            tool: name,
-            args,
-            rule: null,
-            reason: `destructive git command: git ${normalizeGitCommand(args.command)}`,
-          })
-        : false;
+    const ok = await requestInteractivePermission(name, args, context, cwd, {
+      tool: name,
+      args,
+      rule: null,
+      reason: `destructive git command: git ${normalizeGitCommand(args.command)}`,
+    });
     if (!ok) {
       return {
         error: `[Destructive Git] "git ${normalizeGitCommand(args.command)}" discards work irrecoverably and requires confirmation — denied. Add a settings allow rule to pre-authorize.`,
@@ -1199,17 +1335,18 @@ export async function executeTool(name, args, context = {}) {
         credReason = hit ? hit.reason : null;
       }
       if (credReason) {
-        const confirm =
-          context.permissionConfirm || context.shellConfirm || null;
-        const ok =
-          typeof confirm === "function"
-            ? await confirm({
-                tool: name,
-                args,
-                rule: null,
-                reason: `credential access: ${credReason}`,
-              })
-            : false;
+        const ok = await requestInteractivePermission(
+          name,
+          args,
+          context,
+          cwd,
+          {
+            tool: name,
+            args,
+            rule: null,
+            reason: `credential access: ${credReason}`,
+          },
+        );
         if (!ok) {
           const what =
             name === "read_file" ? `Reading "${args.path}"` : "This command";
@@ -1774,28 +1911,41 @@ const _codeIntelPool = new Map(); // root -> { ci, idleTimer }
 const CODE_INTEL_IDLE_MS = 60_000;
 let _codeIntelExitHooked = false;
 
-async function _getSharedCodeIntel(cwd) {
+export async function _getSharedCodeIntel(cwd) {
   const root = path.resolve(cwd || process.cwd());
   let entry = _codeIntelPool.get(root);
   if (!entry) {
     const { CodeIntelligence } =
       await import("../lib/lsp/code-intelligence.js");
-    entry = {
-      ci: new CodeIntelligence({ projectRoot: root, coldStart: true }),
-      idleTimer: null,
-    };
-    _codeIntelPool.set(root, entry);
-    if (!_codeIntelExitHooked) {
-      _codeIntelExitHooked = true;
-      process.once("exit", () => {
-        for (const e of _codeIntelPool.values()) {
-          try {
-            e.ci.dispose();
-          } catch {
-            /* best-effort teardown on exit */
+    // Re-check AFTER the await: two concurrent callers (the parallel read-only
+    // batch runs several `code_intelligence` calls at once) both observed an
+    // empty pool before this `await import`, so without this guard both would
+    // construct a CodeIntelligence — each spawning its own language server — and
+    // the second `set` would orphan the first (leaked server process) while its
+    // stale idle-timer, still bound to `root`, later evicts the wrong (warm,
+    // in-use) entry. This is exactly the orphaned-server/dangling-timer trap the
+    // pool exists to prevent. Construction below has NO further await, so once
+    // one continuation wins the re-check the other reuses its entry — the window
+    // is fully closed.
+    entry = _codeIntelPool.get(root);
+    if (!entry) {
+      entry = {
+        ci: new CodeIntelligence({ projectRoot: root, coldStart: true }),
+        idleTimer: null,
+      };
+      _codeIntelPool.set(root, entry);
+      if (!_codeIntelExitHooked) {
+        _codeIntelExitHooked = true;
+        process.once("exit", () => {
+          for (const e of _codeIntelPool.values()) {
+            try {
+              e.ci.dispose();
+            } catch {
+              /* best-effort teardown on exit */
+            }
           }
-        }
-      });
+        });
+      }
     }
   }
   if (entry.idleTimer) clearTimeout(entry.idleTimer);
@@ -2327,6 +2477,9 @@ async function executeToolInner(
           task.endedAt = new Date().toISOString();
         }
         _backgroundShellTasks.set(id, task);
+        // Arm the process-exit net so a Ctrl-C / hard exit can't orphan this
+        // task (the normal `finally` reaper is bypassed by signals).
+        _ensureBgExitReaper();
         return attachDescriptor(
           {
             background: true,
@@ -2463,6 +2616,14 @@ async function executeToolInner(
         return attachDescriptor(
           {
             error: err.message.substring(0, 2000),
+            // Surface stdout too: a failing command (test runner / linter /
+            // build) usually prints WHAT failed to stdout and only the summary
+            // to stderr, so dropping it on non-zero exit blinds the agent to the
+            // actual failure. Only attach it when there IS output (a timeout with
+            // no output keeps the field absent), mirroring the success path.
+            ...(err.stdout
+              ? { stdout: String(err.stdout).substring(0, 30000) }
+              : {}),
             stderr: (err.stderr || "").substring(0, 2000),
             exitCode: err.status,
             shellCommandPolicy: shellPolicy,
@@ -5440,10 +5601,22 @@ export async function* agentLoop(messages, options) {
               reason: preCompactReason,
             };
           }
+          // Auto-pin (OPT-IN): when enabled, the original task (first user turn)
+          // is pinned so compaction can't drop it. Off by default → no predicate
+          // is passed and compaction is byte-identical to before.
+          let pinOpts = {};
+          if (options.autoPin) {
+            const { buildAutoPinPredicate } = await import("./auto-pin.js");
+            const isPinned = buildAutoPinPredicate(messages, options.autoPin);
+            if (isPinned) pinOpts = { isPinned };
+          }
           const { messages: compacted, stats } =
             !needFull || preCompactBlocked
               ? { messages, stats: { saved: 0 } }
-              : await compactor.compress(messages, { preserveToolPairs: true });
+              : await compactor.compress(messages, {
+                  preserveToolPairs: true,
+                  ...pinOpts,
+                });
           if (stats.saved > 0 && compacted.length < messages.length) {
             messages.splice(0, messages.length, ...compacted);
             // Persist the compaction so a later --resume rebuilds from the

package/src/runtime/auto-pin.js

@@ -0,0 +1,117 @@
+/**
+ * Auto-pin policy for compaction (OPT-IN).
+ *
+ * Phase 7.7 gave the compressor a deterministic pin mechanism: a message the
+ * predicate marks is pulled out before any strategy and re-inserted verbatim,
+ * so it survives compaction no matter what the (non-deterministic) LLM summary
+ * drops. What was deliberately left unbuilt is the *policy* — deciding WHICH
+ * messages to auto-pin — because auto-pinning reorders the hot agent loop's
+ * context and is a product-UX call.
+ *
+ * This module supplies that policy, but strictly opt-in: it only ever produces
+ * a predicate when the caller explicitly enables auto-pin. When disabled it
+ * returns null and the caller passes NO predicate, so the compressor falls back
+ * to its default (pin only messages already tagged `pinned:true`) and behaviour
+ * is byte-identical to before.
+ *
+ * Default policy when enabled: pin the ORIGINAL TASK — the first user turn —
+ * because that is the single fact most likely to scroll out of the recent
+ * window yet most important to keep (the coding agent's goal). Explicit
+ * `pinned:true` messages are always honored on top of it. A token cap keeps a
+ * pathologically large first turn from itself blowing the budget.
+ */
+
+const DEFAULT_MAX_PIN_TOKENS = 2000;
+
+/**
+ * Normalize the opt-in value into a config object, or null when auto-pin is off.
+ * Accepts: falsy (off), `true` (defaults on), or a config object
+ * `{ firstUserGoal?, maxPinTokens? }`.
+ */
+export function resolveAutoPinConfig(opt) {
+  if (!opt) return null;
+  const cfg = typeof opt === "object" ? opt : {};
+  return {
+    firstUserGoal: cfg.firstUserGoal !== false, // default true when enabled
+    maxPinTokens: Number.isFinite(cfg.maxPinTokens)
+      ? cfg.maxPinTokens
+      : DEFAULT_MAX_PIN_TOKENS,
+  };
+}
+
+/** Coarse char/4 token estimate — matches the compressor's own heuristic. */
+function estimateTokens(text) {
+  return Math.ceil(String(text || "").length / 4);
+}
+
+function contentString(m) {
+  if (!m) return "";
+  return typeof m.content === "string"
+    ? m.content
+    : JSON.stringify(m.content || "");
+}
+
+/**
+ * Build an `isPinned(message)` predicate for `compress({ isPinned })`, or null
+ * when auto-pin is disabled (caller then passes no predicate → default).
+ *
+ * The predicate combines explicit pins (`pinned:true`/`_pin`) with the policy's
+ * auto-selected messages, matched by identity against `messages` (compress
+ * filters the same array, so identity is stable).
+ */
+export function buildAutoPinPredicate(messages, opt) {
+  const cfg = resolveAutoPinConfig(opt);
+  if (!cfg) return null;
+  if (!Array.isArray(messages)) {
+    return (m) => !!m && (m.pinned === true || m._pin === true);
+  }
+
+  const auto = new Set();
+  if (cfg.firstUserGoal) {
+    const firstUser = messages.find((m) => m && m.role === "user");
+    // Skip a first turn that is itself huge — pinning it would defeat the point
+    // (it would dominate the very budget compaction is trying to reclaim).
+    if (
+      firstUser &&
+      estimateTokens(contentString(firstUser)) <= cfg.maxPinTokens
+    ) {
+      auto.add(firstUser);
+    }
+  }
+
+  return (m) => !!m && (m.pinned === true || m._pin === true || auto.has(m));
+}
+
+/**
+ * Explain what the policy would pin for `messages` (for `--dry-run` / logging).
+ * Returns `{ enabled, reasons: [{ role, preview, why }] }`.
+ */
+export function describeAutoPin(messages, opt) {
+  const cfg = resolveAutoPinConfig(opt);
+  if (!cfg) return { enabled: false, reasons: [] };
+  const reasons = [];
+  const list = Array.isArray(messages) ? messages : [];
+  for (const m of list) {
+    if (m && (m.pinned === true || m._pin === true)) {
+      reasons.push({ role: m.role, preview: preview(m), why: "explicit pin" });
+    }
+  }
+  if (cfg.firstUserGoal) {
+    const firstUser = list.find((m) => m && m.role === "user");
+    if (
+      firstUser &&
+      estimateTokens(contentString(firstUser)) <= cfg.maxPinTokens
+    ) {
+      reasons.push({
+        role: "user",
+        preview: preview(firstUser),
+        why: "original task (first user turn)",
+      });
+    }
+  }
+  return { enabled: true, reasons };
+}
+
+function preview(m) {
+  return contentString(m).replace(/\s+/g, " ").slice(0, 80);
+}