chainlesschain 0.162.40 → 0.162.41

package/src/lib/json-schema-output.js

@@ -0,0 +1,181 @@
+/**
+ * `cc agent -p --json-schema <file>` — structured output for headless runs.
+ *
+ * The final answer must be JSON that validates against a (subset) JSON
+ * Schema; invalid replies are retried with a corrective prompt (up to
+ * MAX_ATTEMPTS total). Implemented entirely AROUND runAgentHeadless using its
+ * `deps.writeOut` capture seam — the runner itself is untouched: each attempt
+ * runs with output captured, the validated JSON is the only thing printed.
+ *
+ * Validator subset (enough for tool/script contracts, not full draft-2020):
+ * type (object/array/string/number/integer/boolean/null), properties,
+ * required, items, enum, const, additionalProperties:false. Zero deps.
+ */
+
+import fsDefault from "fs";
+
+export const MAX_ATTEMPTS = 3;
+export const _deps = { fs: fsDefault };
+
+/** Validate `value` against the schema subset. Returns error strings ([] = valid). */
+export function validateAgainstSchema(value, schema, path = "$") {
+  const errors = [];
+  if (!schema || typeof schema !== "object") return errors;
+
+  const typeOf = (v) =>
+    v === null
+      ? "null"
+      : Array.isArray(v)
+        ? "array"
+        : typeof v === "number" && Number.isInteger(v)
+          ? "integer"
+          : typeof v;
+
+  if (schema.type) {
+    const want = Array.isArray(schema.type) ? schema.type : [schema.type];
+    const got = typeOf(value);
+    const ok = want.some((t) => t === got || (t === "number" && got === "integer"));
+    if (!ok) {
+      errors.push(`${path}: expected type ${want.join("|")}, got ${got}`);
+      return errors; // type mismatch — deeper checks are noise
+    }
+  }
+  if (schema.enum && !schema.enum.some((e) => JSON.stringify(e) === JSON.stringify(value))) {
+    errors.push(`${path}: value not in enum [${schema.enum.map((e) => JSON.stringify(e)).join(", ")}]`);
+  }
+  if (schema.const !== undefined && JSON.stringify(schema.const) !== JSON.stringify(value)) {
+    errors.push(`${path}: must equal const ${JSON.stringify(schema.const)}`);
+  }
+  if (typeOf(value) === "object" && !Array.isArray(value)) {
+    for (const req of schema.required || []) {
+      if (!(req in value)) errors.push(`${path}: missing required property "${req}"`);
+    }
+    const props = schema.properties || {};
+    for (const [k, v] of Object.entries(value)) {
+      if (props[k]) {
+        errors.push(...validateAgainstSchema(v, props[k], `${path}.${k}`));
+      } else if (schema.additionalProperties === false) {
+        errors.push(`${path}: unexpected property "${k}"`);
+      }
+    }
+  }
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => {
+      errors.push(...validateAgainstSchema(item, schema.items, `${path}[${i}]`));
+    });
+  }
+  return errors;
+}
+
+/** Pull a JSON payload out of an LLM reply (bare, fenced, or embedded). */
+export function extractJsonPayload(text) {
+  const raw = String(text || "").trim();
+  const tries = [];
+  tries.push(raw);
+  const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(raw);
+  if (fence) tries.push(fence[1].trim());
+  const firstObj = raw.indexOf("{");
+  const lastObj = raw.lastIndexOf("}");
+  if (firstObj !== -1 && lastObj > firstObj) tries.push(raw.slice(firstObj, lastObj + 1));
+  const firstArr = raw.indexOf("[");
+  const lastArr = raw.lastIndexOf("]");
+  if (firstArr !== -1 && lastArr > firstArr) tries.push(raw.slice(firstArr, lastArr + 1));
+  for (const candidate of tries) {
+    if (!candidate) continue;
+    try {
+      return { ok: true, value: JSON.parse(candidate) };
+    } catch {
+      /* next candidate */
+    }
+  }
+  return { ok: false, error: "reply contains no parseable JSON" };
+}
+
+export function buildSchemaInstruction(schema) {
+  return [
+    "OUTPUT CONTRACT: your FINAL reply must be ONLY a JSON value (no prose, no markdown fences) that validates against this JSON Schema:",
+    JSON.stringify(schema),
+  ].join("\n");
+}
+
+export function buildRetryPrompt(originalPrompt, raw, errors) {
+  return [
+    originalPrompt,
+    "",
+    "Your previous reply failed JSON Schema validation:",
+    ...errors.slice(0, 10).map((e) => `- ${e}`),
+    "",
+    `Previous reply (for reference): ${String(raw).slice(0, 2000)}`,
+    "",
+    "Reply again with ONLY the corrected JSON.",
+  ].join("\n");
+}
+
+/**
+ * Run a headless turn constrained to a schema, retrying on validation
+ * failure. Prints the validated JSON to writeOut; returns the exit code.
+ *
+ * @param {object} cfg { schemaFile|schema, baseOptions, runHeadless,
+ *                       maxAttempts?, writeOut?, writeErr?, deps? }
+ */
+export async function runJsonSchemaConstrained(cfg = {}) {
+  const fs = cfg.deps?.fs || _deps.fs;
+  const writeOut = cfg.writeOut || ((s) => process.stdout.write(s));
+  const writeErr = cfg.writeErr || ((s) => process.stderr.write(s));
+  const maxAttempts = cfg.maxAttempts || MAX_ATTEMPTS;
+
+  const schema =
+    cfg.schema || JSON.parse(fs.readFileSync(cfg.schemaFile, "utf-8"));
+  const instruction = buildSchemaInstruction(schema);
+  const base = cfg.baseOptions || {};
+
+  let prompt = base.prompt;
+  let lastRaw = "";
+  let lastErrors = ["no attempts ran"];
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    let captured = "";
+    const outcome = await cfg.runHeadless(
+      {
+        ...base,
+        prompt,
+        outputFormat: "text",
+        appendSystemPrompt: [base.appendSystemPrompt, instruction]
+          .filter(Boolean)
+          .join("\n\n"),
+      },
+      {
+        writeOut: (s) => {
+          captured += s;
+        },
+        writeErr,
+      },
+    );
+    const raw = String(outcome?.result ?? captured ?? "").trim() || captured.trim();
+    lastRaw = raw;
+    const parsed = extractJsonPayload(raw);
+    if (parsed.ok) {
+      const errors = validateAgainstSchema(parsed.value, schema);
+      if (errors.length === 0) {
+        writeOut(`${JSON.stringify(parsed.value, null, 2)}\n`);
+        return 0;
+      }
+      lastErrors = errors;
+    } else {
+      lastErrors = [parsed.error];
+    }
+    if (attempt < maxAttempts) {
+      writeErr(
+        `--json-schema: attempt ${attempt} failed validation (${lastErrors.length} error(s)) — retrying…\n`,
+      );
+      prompt = buildRetryPrompt(base.prompt, raw, lastErrors);
+    }
+  }
+
+  writeErr(
+    `--json-schema: reply failed validation after ${maxAttempts} attempts:\n${lastErrors
+      .map((e) => `  - ${e}`)
+      .join("\n")}\nLast reply:\n${lastRaw.slice(0, 1000)}\n`,
+  );
+  return 1;
+}

package/src/lib/mcp-serve.js

@@ -0,0 +1,259 @@
+/**
+ * `cc mcp serve` — expose cc's local file tools as an MCP server so OTHER
+ * MCP clients (Claude Desktop, another cc, any Streamable-HTTP client) can
+ * use this machine's workspace. Claude-Code `claude mcp serve` parity.
+ *
+ * Protocol: Streamable-HTTP MCP, same shape the IDE-bridge work verified
+ * against the real CLI MCPClient — every request is POST JSON-RPC answered
+ * with application/json (no persistent SSE GET needed): `initialize`,
+ * `notifications/initialized`, `tools/list`, `tools/call`; tool failures are
+ * `isError` results, transport failures JSON-RPC errors.
+ *
+ * Security: tools are CONFINED to the serve root (path resolves inside root
+ * or the call fails), Bearer-token auth is on by default (random token,
+ * printed once), `--read-only` drops write_file. Zero npm deps (node http).
+ */
+
+import http from "http";
+import fsDefault from "fs";
+import pathDefault from "path";
+import { randomBytes } from "crypto";
+
+export const MAX_READ_BYTES = 200 * 1024;
+export const MAX_LIST_ENTRIES = 500;
+export const MAX_SEARCH_RESULTS = 200;
+export const MAX_SEARCH_ENTRIES = 50_000;
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build"]);
+
+export const _deps = { fs: fsDefault, path: pathDefault };
+
+/** Resolve `rel` inside `root`; throws on escape (.. traversal, abs paths out). */
+export function confine(root, rel, deps = _deps) {
+  const abs = deps.path.resolve(root, rel || ".");
+  const normRoot = deps.path.resolve(root);
+  if (abs !== normRoot && !abs.startsWith(normRoot + deps.path.sep)) {
+    throw new Error(`path escapes serve root: ${rel}`);
+  }
+  return abs;
+}
+
+function ok(text) {
+  return { content: [{ type: "text", text: String(text) }] };
+}
+function fail(message) {
+  return { content: [{ type: "text", text: String(message) }], isError: true };
+}
+
+/** Build the tool table (name → {description, inputSchema, handler}). */
+export function buildTools({ root, readOnly = false, deps = _deps }) {
+  const fs = deps.fs;
+  const tools = {
+    read_file: {
+      description: `Read a UTF-8 file under the serve root (${MAX_READ_BYTES} byte cap)`,
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+        required: ["path"],
+      },
+      handler: ({ path: rel }) => {
+        const abs = confine(root, rel, deps);
+        const buf = fs.readFileSync(abs);
+        const truncated = buf.length > MAX_READ_BYTES;
+        const text = (truncated ? buf.slice(0, MAX_READ_BYTES) : buf).toString(
+          "utf-8",
+        );
+        return ok(truncated ? `${text}\n… [truncated ${buf.length} bytes]` : text);
+      },
+    },
+    list_dir: {
+      description: "List a directory under the serve root (dirs get trailing /)",
+      inputSchema: {
+        type: "object",
+        properties: { path: { type: "string" } },
+      },
+      handler: ({ path: rel } = {}) => {
+        const abs = confine(root, rel || ".", deps);
+        const entries = fs
+          .readdirSync(abs, { withFileTypes: true })
+          .slice(0, MAX_LIST_ENTRIES)
+          .map((e) => (e.isDirectory() ? `${e.name}/` : e.name));
+        return ok(entries.join("\n"));
+      },
+    },
+    search_files: {
+      description:
+        "Find files under the serve root whose RELATIVE PATH contains the query (case-insensitive, bounded walk)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+          dir: { type: "string" },
+        },
+        required: ["query"],
+      },
+      handler: ({ query, dir } = {}) => {
+        const base = confine(root, dir || ".", deps);
+        const q = String(query).toLowerCase();
+        const hits = [];
+        let seen = 0;
+        const walk = (d) => {
+          if (hits.length >= MAX_SEARCH_RESULTS || seen >= MAX_SEARCH_ENTRIES)
+            return;
+          let list;
+          try {
+            list = fs.readdirSync(d, { withFileTypes: true });
+          } catch {
+            return;
+          }
+          for (const e of list) {
+            if (hits.length >= MAX_SEARCH_RESULTS || ++seen >= MAX_SEARCH_ENTRIES)
+              return;
+            const abs = deps.path.join(d, e.name);
+            if (e.isDirectory()) {
+              if (!SKIP_DIRS.has(e.name) && !e.name.startsWith("."))
+                walk(abs);
+            } else {
+              const rel = deps.path.relative(root, abs).replace(/\\/g, "/");
+              if (rel.toLowerCase().includes(q)) hits.push(rel);
+            }
+          }
+        };
+        walk(base);
+        return ok(hits.join("\n") || "(no matches)");
+      },
+    },
+  };
+  if (!readOnly) {
+    tools.write_file = {
+      description: "Write a UTF-8 file under the serve root (creates parent dirs)",
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string" },
+          content: { type: "string" },
+        },
+        required: ["path", "content"],
+      },
+      handler: ({ path: rel, content }) => {
+        const abs = confine(root, rel, deps);
+        fs.mkdirSync(deps.path.dirname(abs), { recursive: true });
+        fs.writeFileSync(abs, String(content), "utf-8");
+        return ok(`wrote ${Buffer.byteLength(String(content))} bytes to ${rel}`);
+      },
+    };
+  }
+  return tools;
+}
+
+function rpcResult(id, result) {
+  return JSON.stringify({ jsonrpc: "2.0", id, result });
+}
+function rpcError(id, code, message) {
+  return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+/**
+ * Start the server. Returns { server, port, token, url, close() }.
+ *
+ * @param {object} opts { root, port=0, token (null → random, false → no auth),
+ *                        readOnly, deps }
+ */
+export function startMcpServe(opts = {}) {
+  const deps = { ..._deps, ...(opts.deps || {}) };
+  const root = deps.path.resolve(opts.root || process.cwd());
+  const readOnly = Boolean(opts.readOnly);
+  const token =
+    opts.token === false
+      ? null
+      : opts.token || randomBytes(16).toString("hex");
+  const tools = buildTools({ root, readOnly, deps });
+
+  const server = http.createServer((req, res) => {
+    const send = (status, body) => {
+      res.writeHead(status, { "Content-Type": "application/json" });
+      res.end(body);
+    };
+    if (req.method !== "POST") {
+      return send(405, rpcError(null, -32600, "POST only"));
+    }
+    if (token) {
+      const auth = req.headers.authorization || "";
+      if (auth !== `Bearer ${token}`) {
+        return send(401, rpcError(null, -32001, "unauthorized"));
+      }
+    }
+    let raw = "";
+    req.on("data", (c) => {
+      raw += c;
+    });
+    req.on("end", () => {
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return send(400, rpcError(null, -32700, "parse error"));
+      }
+      const { id, method, params } = msg || {};
+      try {
+        if (method === "initialize") {
+          return send(
+            200,
+            rpcResult(id, {
+              protocolVersion: params?.protocolVersion || "2025-03-26",
+              capabilities: { tools: {} },
+              serverInfo: { name: "cc-mcp-serve", version: "1.0.0" },
+            }),
+          );
+        }
+        if (method === "notifications/initialized") {
+          res.writeHead(202);
+          return res.end();
+        }
+        if (method === "tools/list") {
+          return send(
+            200,
+            rpcResult(id, {
+              tools: Object.entries(tools).map(([name, t]) => ({
+                name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+              })),
+            }),
+          );
+        }
+        if (method === "tools/call") {
+          const tool = tools[params?.name];
+          if (!tool) {
+            return send(200, rpcResult(id, fail(`unknown tool: ${params?.name}`)));
+          }
+          let result;
+          try {
+            result = tool.handler(params?.arguments || {});
+          } catch (err) {
+            result = fail(err.message);
+          }
+          return send(200, rpcResult(id, result));
+        }
+        return send(200, rpcError(id, -32601, `method not found: ${method}`));
+      } catch (err) {
+        return send(500, rpcError(id, -32603, err.message));
+      }
+    });
+  });
+
+  return new Promise((resolve, reject) => {
+    server.on("error", reject);
+    server.listen(opts.port || 0, "127.0.0.1", () => {
+      const port = server.address().port;
+      resolve({
+        server,
+        port,
+        token,
+        root,
+        readOnly,
+        url: `http://127.0.0.1:${port}/mcp`,
+        close: () => new Promise((r) => server.close(r)),
+      });
+    });
+  });
+}

package/src/lib/project-instructions.js

@@ -136,10 +136,88 @@ export function findInstructionFiles(opts = {}) {
     // Template-scaffolded project rules (`cc init -t` writes these) join the
     // chain too, so scaffold-flow and memory-flow projects both feed the agent.
     push(path.join(d, ".chainlesschain", "rules.md"), "rules");
+    // Path-scoped rule files (`.claude/rules/*.md`, YAML frontmatter `paths:`
+    // globs). Glob filtering happens at LOAD time where content is available.
+    try {
+      const rulesDir = path.join(d, ".claude", "rules");
+      for (const f of fs
+        .readdirSync(rulesDir)
+        .filter((n) => n.endsWith(".md"))
+        .sort()) {
+        push(path.join(rulesDir, f), "rule");
+      }
+    } catch {
+      /* no rules dir */
+    }
   }
   return out;
 }
 
+/**
+ * Parse a rule file's YAML-ish frontmatter (zero-dep): `paths:`/`globs:` as a
+ * dash-list or inline value. Returns { globs, body } with frontmatter
+ * stripped from body; files without frontmatter pass through unchanged.
+ */
+export function parseRuleFrontmatter(text) {
+  const str = String(text);
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(str);
+  if (!m) return { globs: [], body: str };
+  const globs = [];
+  let inPaths = false;
+  const take = (raw) => {
+    const v = raw.trim().replace(/^["']|["']$/g, "");
+    if (v) globs.push(v);
+  };
+  for (const rawLine of m[1].split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const key = /^(paths|globs)\s*:\s*(.*)$/.exec(line);
+    if (key) {
+      inPaths = true;
+      const inline = key[2].trim();
+      if (inline) {
+        for (const g of inline.startsWith("[")
+          ? inline.replace(/^\[|\]$/g, "").split(",")
+          : [inline]) {
+          take(g);
+        }
+      }
+      continue;
+    }
+    if (inPaths) {
+      const item = /^-\s*(.+)$/.exec(line);
+      if (item) take(item[1]);
+      else if (line) inPaths = false;
+    }
+  }
+  return { globs, body: str.slice(m[0].length) };
+}
+
+/**
+ * Does a path-scoped rule apply when the agent runs at `relCwd` (cwd relative
+ * to the dir holding `.claude/`)? v1 prefix-overlap semantics: the glob's
+ * literal prefix and the cwd must sit on the same path line — running at the
+ * project root loads every rule; running inside packages/cli loads rules
+ * whose glob prefix is packages/cli plus prefixless globs (star-star
+ * patterns). Finer tool-time injection is a later phase (module 99 §5.3).
+ */
+export function ruleApplies(globs, relCwd) {
+  if (!globs || globs.length === 0) return true;
+  const cwd = String(relCwd || "")
+    .replace(/\\/g, "/")
+    .replace(/^\.\/?/, "");
+  if (!cwd) return true; // at the project root every rule is in play
+  for (const glob of globs) {
+    const g = String(glob).replace(/\\/g, "/");
+    const star = g.search(/[*?[]/);
+    const prefix = (star === -1 ? g : g.slice(0, star)).replace(/\/+$/, "");
+    if (!prefix) return true; // "**/*.js" — applies everywhere
+    if (cwd === prefix || cwd.startsWith(`${prefix}/`) || prefix.startsWith(`${cwd}/`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Collect `@path` import tokens from instruction text, skipping fenced code
  * blocks (``` / ~~~). Line-level scanning is good enough for memory files,
@@ -212,6 +290,17 @@ export function loadProjectInstructions(opts = {}) {
       warnings.push(`${abs} — cannot read: ${err.message}`);
       continue;
     }
+    if (scope === "rule") {
+      // <base>/.claude/rules/<file>.md → base is three dirs up.
+      const base = path.dirname(path.dirname(path.dirname(abs)));
+      const relCwd = path.relative(
+        base,
+        path.resolve(opts.cwd || process.cwd()),
+      );
+      const { globs, body } = parseRuleFrontmatter(entry.content);
+      if (!ruleApplies(globs, relCwd)) continue; // out of scope for this cwd
+      entry = { ...entry, content: body };
+    }
     total += Math.min(entry.bytes, maxFileBytes);
     out.push({ path: abs, scope, ...entry });
 

package/src/lib/repl-completer.js

@@ -107,8 +107,12 @@ export function makeAtCompleter(opts = {}) {
               .map((f) => {
                 const rel = path.relative(cwd, f);
                 // Keep workspace files relative (the natural @ref form);
-                // out-of-workspace files keep their absolute path.
-                return rel && !rel.startsWith("..") ? fwd(rel) : fwd(f);
+                // out-of-workspace files keep their absolute path. On
+                // Windows a cross-drive relative() returns an *absolute*
+                // path (no ".." prefix), so isAbsolute must also gate it.
+                return rel && !rel.startsWith("..") && !path.isAbsolute(rel)
+                  ? fwd(rel)
+                  : fwd(f);
               })
           : [];
         ideFetchedAt = now();
@@ -131,7 +135,9 @@ export function makeAtCompleter(opts = {}) {
     const slash = /^\/([A-Za-z_-]*)$/.exec(line);
     if (slash && slashCommands.length) {
       const pref = `/${slash[1].toLowerCase()}`;
-      const hits = slashCommands.filter((c) => c.toLowerCase().startsWith(pref));
+      const hits = slashCommands.filter((c) =>
+        c.toLowerCase().startsWith(pref),
+      );
       return [hits, line];
     }
     const at = extractAtPrefix(line);

package/src/lib/repl-rewind.js

@@ -0,0 +1,107 @@
+/**
+ * REPL conversation rewind — Claude-Code double-Esc parity (v1: conversation
+ * state; file state stays on `cc checkpoint restore`, hinted alongside).
+ *
+ * Pure helpers over the REPL's live `messages` array so the picker logic is
+ * unit-testable without readline:
+ *  - listUserTurns(): newest-first numbered list of user messages
+ *  - rewindToTurn(): truncate the conversation BACK TO BEFORE turn #n and
+ *    return the original text so the caller can prefill the input line
+ *    (edit-and-resend, like Claude Code's rewind).
+ *
+ * Trigger surfaces (wired in agent-repl): `/rewind` lists, `/rewind <n>`
+ * rewinds, and a double-Esc while idle prints the same list as a shortcut.
+ */
+
+export const DEFAULT_LIST_LIMIT = 10;
+export const PREVIEW_CHARS = 60;
+
+function previewOf(content) {
+  const text =
+    typeof content === "string" ? content : JSON.stringify(content || "");
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > PREVIEW_CHARS
+    ? `${flat.slice(0, PREVIEW_CHARS)}…`
+    : flat;
+}
+
+/**
+ * Newest-first user turns.
+ * @returns {Array<{n:number, index:number, preview:string, content:any}>}
+ *          n is the 1-based pick number (1 = most recent user message).
+ */
+export function listUserTurns(messages, { limit = DEFAULT_LIST_LIMIT } = {}) {
+  const turns = [];
+  for (let i = (messages || []).length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (!m || m.role !== "user") continue;
+    turns.push({
+      n: turns.length + 1,
+      index: i,
+      preview: previewOf(m.content),
+      content: m.content,
+    });
+    if (turns.length >= limit) break;
+  }
+  return turns;
+}
+
+/**
+ * Rewind the conversation to BEFORE the picked user turn (mutates `messages`
+ * in place — everything from that user message onward is dropped).
+ *
+ * @param {Array} messages  live conversation array
+ * @param {number} n        1-based pick from listUserTurns
+ * @returns {{ removed:number, text:string|null }|null}  null on bad pick;
+ *          `text` is the original user text when it was a plain string
+ *          (caller prefills the input line with it).
+ */
+export function rewindToTurn(messages, n) {
+  const turns = listUserTurns(messages, { limit: 1000 });
+  const turn = turns.find((t) => t.n === Number(n));
+  if (!turn) return null;
+  const removed = messages.length - turn.index;
+  messages.splice(turn.index);
+  return {
+    removed,
+    text: typeof turn.content === "string" ? turn.content : null,
+  };
+}
+
+/**
+ * Offline extractive recap for a resumed conversation ("where were we") —
+ * no LLM call: turn counts + last ask + last reply previews.
+ * @returns {string[]|null} lines to print, or null when nothing to recap.
+ */
+export function buildResumeRecap(messages, { previewChars = 160 } = {}) {
+  const list = messages || [];
+  const flat = (c) =>
+    (typeof c === "string" ? c : JSON.stringify(c || ""))
+      .replace(/\s+/g, " ")
+      .trim();
+  const cap = (s) =>
+    s.length > previewChars ? `${s.slice(0, previewChars)}…` : s;
+  const lastOf = (role) => {
+    for (let i = list.length - 1; i >= 0; i--) {
+      if (list[i]?.role === role) return list[i].content;
+    }
+    return null;
+  };
+  const users = list.filter((m) => m?.role === "user").length;
+  const assistants = list.filter((m) => m?.role === "assistant").length;
+  if (!users && !assistants) return null;
+  const lines = [`${users} user / ${assistants} assistant turns`];
+  const lu = lastOf("user");
+  if (lu) lines.push(`last ask  : ${cap(flat(lu))}`);
+  const la = lastOf("assistant");
+  if (la) lines.push(`last reply: ${cap(flat(la))}`);
+  return lines;
+}
+
+/** Render the picker list (shared by /rewind and double-Esc). */
+export function renderTurnList(turns) {
+  if (!turns.length) return "  (no user turns yet)";
+  return turns
+    .map((t) => `  ${String(t.n).padStart(2)}. ${t.preview}`)
+    .join("\n");
+}