forget-connect 0.6.0 → 0.6.1

package/README.md

@@ -93,7 +93,9 @@ scripts remain until neither Codex nor Claude Code references them.
 --no-rules           Do not manage CLAUDE.md or AGENTS.md
 --no-skill           Do not install the shared Memory Agent skill
 --no-hooks           Do not install Codex/Claude Code memory hooks
---no-proxy           Do not wire the local capture proxy (macOS only)
+--proxy              Opt in to the local capture proxy (macOS only, off by default)
+--no-proxy           Accepted for compatibility; the proxy is already off by default
+--purge-capture      With disconnect: also delete ~/.forget/proxy/stream
 --no-migrate-enacta  Keep matching legacy config and rule blocks
 --dry-run            Show which files would change
 --timeout <seconds>  Doctor network timeout, from 1 to 60
@@ -157,8 +159,11 @@ registered by other tools are preserved byte-for-byte.
 
 ## Capture proxy (macOS)
 
-On macOS, connect also wires the zero-config capture proxy when `forget-proxy`
-(from `pip install 'forget-ai[server]'`) is on PATH:
+The capture proxy is **off by default** since 0.6.1. It records every Claude
+Code request and response (secret-scrubbed, owner-only files) in
+`~/.forget/proxy/stream/`, so it is wired only when you pass `--proxy`.
+With `--proxy` on macOS, and `forget-proxy` (from
+`pip install 'forget-ai[server]'`) on PATH, connect:
 
 - registers launchd services `ai.forget.proxy` (KeepAlive, port 8377) and
   `ai.forget.proxy.watchdog` (60s health checks)
@@ -171,4 +176,11 @@ If the proxy stops answering for three consecutive checks, the watchdog
 removes the override (only the value we wrote) and restores your original
 base URL — losing capture is cheaper than losing Claude. When the proxy
 recovers, the override returns unless you changed the value yourself.
-Skip with `--no-proxy`; `disconnect` always unwires and removes the services.
+`disconnect` always unwires and removes the services. It reports the size of
+the capture folder and keeps it unless you pass `--purge-capture` (or answer
+yes when asked). `forget-connect capture purge --before <YYYY-MM-DD>` deletes
+older day files. `doctor` shows whether the proxy is on and how much is stored.
+
+If 0.6.0 already wired the proxy on your machine, upgrading does not remove
+it: run `npx forget-connect disconnect` and then connect again without
+`--proxy`.

package/assets/hooks/forget_capture.py

@@ -36,6 +36,25 @@ except Exception:
     forget_digest = None
 
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
+
+
+def _auth_headers() -> dict:
+    """Content-Type plus, for a loopback server only, the local Bearer key from
+    $FORGET_HOME/api-key (written by `forget install-service`). Never sent off-box."""
+    headers = {"Content-Type": "application/json"}
+    try:
+        from pathlib import Path
+        from urllib.parse import urlsplit
+        if (urlsplit(FORGET_URL).hostname or "") not in ("127.0.0.1", "localhost", "::1"):
+            return headers
+        home = Path(os.environ.get("FORGET_HOME") or Path.home() / ".forget")
+        key = (home / "api-key").read_text().strip()
+        if key:
+            headers["Authorization"] = "Bearer " + key
+    except Exception:
+        pass
+    return headers
+
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 TAIL_BYTES = 400_000
 SNIPPET_LIMIT = 200
@@ -50,7 +69,7 @@ def _rpc(name: str, arguments: dict, timeout: int = 5) -> None:
     request = urllib.request.Request(
         FORGET_URL,
         data=json.dumps(payload).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
+        headers=_auth_headers(),
     )
     urllib.request.urlopen(request, timeout=timeout).read()
 

package/assets/hooks/forget_sessionstart.py

@@ -21,6 +21,25 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from forget_project import layered_filter, project_key_for_path, scope_disabled  # noqa: E402
 
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
+
+
+def _auth_headers() -> dict:
+    """Content-Type plus, for a loopback server only, the local Bearer key from
+    $FORGET_HOME/api-key (written by `forget install-service`). Never sent off-box."""
+    headers = {"Content-Type": "application/json"}
+    try:
+        from pathlib import Path
+        from urllib.parse import urlsplit
+        if (urlsplit(FORGET_URL).hostname or "") not in ("127.0.0.1", "localhost", "::1"):
+            return headers
+        home = Path(os.environ.get("FORGET_HOME") or Path.home() / ".forget")
+        key = (home / "api-key").read_text().strip()
+        if key:
+            headers["Authorization"] = "Bearer " + key
+    except Exception:
+        pass
+    return headers
+
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 CAPSULE_CHAR_BUDGET = 1_600  # ~400 tokens
 HANDOFF_MAX_AGE_SECONDS = 48 * 3600  # a stale shift-note is worse than none
@@ -135,7 +154,7 @@ def main() -> None:
     request = urllib.request.Request(
         FORGET_URL,
         data=json.dumps(payload).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
+        headers=_auth_headers(),
     )
     body = json.loads(urllib.request.urlopen(request, timeout=8).read())
     result = json.loads(body["result"]["content"][0]["text"])

package/assets/hooks/forget_turnrecall.py

@@ -42,6 +42,25 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 from forget_project import layered_filter, project_key_for_path, scope_disabled, wants_cross_project  # noqa: E402
 
 FORGET_URL = os.environ.get("FORGET_MCP_URL", "http://127.0.0.1:8000/mcp")
+
+
+def _auth_headers() -> dict:
+    """Content-Type plus, for a loopback server only, the local Bearer key from
+    $FORGET_HOME/api-key (written by `forget install-service`). Never sent off-box."""
+    headers = {"Content-Type": "application/json"}
+    try:
+        from pathlib import Path
+        from urllib.parse import urlsplit
+        if (urlsplit(FORGET_URL).hostname or "") not in ("127.0.0.1", "localhost", "::1"):
+            return headers
+        home = Path(os.environ.get("FORGET_HOME") or Path.home() / ".forget")
+        key = (home / "api-key").read_text().strip()
+        if key:
+            headers["Authorization"] = "Bearer " + key
+    except Exception:
+        pass
+    return headers
+
 STATE_DIR = os.path.expanduser("~/.forget/hooks/state")
 # 0.45 → 0.33 (2026-08-23, 다국어 mpnet 전환 실측): 새 공간의 합성 점수 대역이
 # 내려앉았다 — 관련 질의 상위 0.40~0.46, 무관 바닥 0.28. 구 문턱 0.45는 구 공간
@@ -176,7 +195,7 @@ def _rpc(name: str, arguments: dict, timeout: int = 5) -> dict:
     request = urllib.request.Request(
         FORGET_URL,
         data=json.dumps(payload).encode("utf-8"),
-        headers={"Content-Type": "application/json"},
+        headers=_auth_headers(),
     )
     body = json.loads(urllib.request.urlopen(request, timeout=timeout).read())
     return json.loads(body["result"]["content"][0]["text"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forget-connect",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Safely connect Claude Code, Codex, and Claude Desktop to Forget memory.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 import os from "node:os";
+import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin, stdout, stderr } from "node:process";
 import {
@@ -38,6 +39,11 @@ import {
   PROXY_BASE_URL,
   PROXY_LABEL,
   WATCHDOG_LABEL,
+  captureInfo,
+  legacyLine,
+  purgeCaptureBefore,
+  formatBytes,
+  purgeCapture,
   findExecutable,
   installProxyServices,
   readWiringState,
@@ -63,6 +69,7 @@ Usage:
   forget-connect status [options]
   forget-connect doctor [options]
   forget-connect disconnect [options]
+  forget-connect capture purge --before <YYYY-MM-DD>   delete older capture day files (asks yes)
 
 Options:
   --client <ids>       Comma-separated: claude-code,codex,claude-desktop,all
@@ -85,8 +92,14 @@ Scope:
   --no-skill           Do not install the shared Memory Agent skill
   --no-hooks           Do not install Codex/Claude Code memory hooks (session
                        capsule, per-turn recall, session capture)
-  --no-proxy           Do not wire the local capture proxy (launchd service +
-                       ANTHROPIC_BASE_URL override + health watchdog; macOS only)
+  --proxy              OPT-IN (macOS only): wire the local capture proxy (launchd
+                       service + ANTHROPIC_BASE_URL override + health watchdog).
+                       It records every Claude Code request and response
+                       (secret-scrubbed) in ~/.forget/proxy/stream/, kept 7 days,
+                       max 2 GB. Off unless you pass --proxy.
+  --no-proxy           Accepted for compatibility; the proxy is already off by default
+  --purge-capture      With disconnect: also delete ~/.forget/proxy/stream
+                       (otherwise only its size is reported and it is kept)
   --no-migrate-enacta  Keep matching legacy config and rules blocks
   --dry-run            Show the files that would change without writing them
   --timeout <seconds>  Doctor network timeout (default: 10)
@@ -155,7 +168,8 @@ export function parseArgs(argv, env = process.env) {
     rules: true,
     skills: true,
     hooks: true,
-    proxy: true,
+    proxy: false,
+    purgeCapture: false,
     migrateLegacy: true,
     dryRun: false,
     yes: false,
@@ -168,9 +182,16 @@ export function parseArgs(argv, env = process.env) {
   let actionSeen = false;
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (["connect", "disconnect", "status", "doctor"].includes(arg) && !actionSeen) {
+    if (["connect", "disconnect", "status", "doctor", "capture"].includes(arg) && !actionSeen) {
       options.action = arg;
       actionSeen = true;
+    } else if (options.action === "capture" && arg === "purge") {
+      options.captureSub = "purge";
+    } else if (arg === "--before") {
+      options.before = requireValue(argv, index, arg);
+      index += 1;
+    } else if (arg.startsWith("--before=")) {
+      options.before = arg.slice("--before=".length);
     } else if (arg === "--client") {
       options.clientValues.push(requireValue(argv, index, arg));
       index += 1;
@@ -207,8 +228,12 @@ export function parseArgs(argv, env = process.env) {
       options.skills = false;
     } else if (arg === "--no-hooks") {
       options.hooks = false;
+    } else if (arg === "--proxy") {
+      options.proxy = true;
     } else if (arg === "--no-proxy") {
       options.proxy = false;
+    } else if (arg === "--purge-capture") {
+      options.purgeCapture = true;
     } else if (arg === "--no-migrate-enacta") {
       options.migrateLegacy = false;
     } else if (arg === "--dry-run") {
@@ -424,6 +449,16 @@ function isLoopbackUrl(value) {
   return LOOPBACK_HOSTS.has(new URL(value).hostname.toLowerCase());
 }
 
+export async function readLocalApiKey(env = process.env) {
+  // $FORGET_HOME/api-key is written (0600) by `forget install-service`.
+  const home = env.FORGET_HOME || path.join(env.HOME ?? env.USERPROFILE ?? os.homedir(), ".forget");
+  try {
+    return (await readFile(path.join(home, "api-key"), "utf8")).trim();
+  } catch {
+    return "";
+  }
+}
+
 async function apiKeyFor(options, env) {
   if (!["connect", "doctor"].includes(options.action) || !options.auth || options.dryRun) return "";
   const fromEnv = env.FORGET_API_KEY?.trim();
@@ -441,6 +476,13 @@ async function apiKeyFor(options, env) {
       "Note: FORGET_API_KEY is set but the target is a loopback HTTP server; connecting without a token.\n",
     );
   }
+  // Local server: send the install's own key. Harmless while the server does
+  // not require auth, and required once it does (phase 2). Not used by doctor,
+  // which checks it separately and only warns.
+  if (!options.hosted && isLoopbackUrl(options.url) && options.action === "connect") {
+    const localKey = await readLocalApiKey(env);
+    if (localKey) return validateApiKey(localKey);
+  }
   if (options.localAuth) {
     throw new ConfigError("Set FORGET_API_KEY when using --local-auth.");
   }
@@ -520,6 +562,30 @@ function printDoctor(result) {
     }
     stdout.write(`${client.ok ? "✓" : "✗"} ${client.name}: ${details.join(", ")}\n`);
   }
+  if (result.capture) {
+    const c = result.capture;
+    const state = c.service_wired ? (c.capture_env ? "ON" : "passthrough (capture off)") : "off (proxy not installed)";
+    stdout.write(`${c.service_wired ? "!" : "○"} Capture proxy: ${state}\n`);
+    if (c.exists) {
+      stdout.write(`  folder ${c.dir}: ${formatBytes(c.bytes)} in ${c.files} day file(s), oldest ${c.oldest ?? "-"}, retention ${c.retention_days} days, cap ${formatBytes(c.max_bytes)}\n`);
+      const legacy = legacyLine(c);
+      if (legacy) stdout.write(`  ${legacy}\n`);
+      if (!c.service_wired && c.files) {
+        stdout.write("  not being written to now; delete with: forget-connect disconnect --purge-capture\n");
+      }
+    } else {
+      stdout.write("  no capture folder\n");
+    }
+  }
+  const aw = result.auth_warnings;
+  if (aw?.server_has_key && (aw.clients_without_key.length || aw.hooks_without_key)) {
+    const who = [...aw.clients_without_key, ...(aw.hooks_without_key ? ["hooks"] : [])].join(", ");
+    stdout.write(
+      `! Local API key: the server has a key ($FORGET_HOME/api-key) but ${who} do not send it.\n`
+      + "  Auth is not required yet, so nothing is broken. It will be required in a later release;\n"
+      + "  run `npx forget-connect` (connect) again to update clients and hooks.\n",
+    );
+  }
   if (result.remote.skipped) {
     stdout.write("○ MCP: not checked until local configuration is fixed\n");
     return;
@@ -538,6 +604,67 @@ function printDoctor(result) {
   }
 }
 
+async function confirmYes(question) {
+  if (!(stdin.isTTY && stdout.isTTY)) return false;
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(question)).trim().toLowerCase();
+    return answer === "y" || answer === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function runCapturePurge(options, env) {
+  if (options.captureSub !== "purge" || !options.before) {
+    throw new ConfigError("Usage: forget-connect capture purge --before <YYYY-MM-DD>");
+  }
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(options.before)) {
+    throw new ConfigError("--before needs a date like 2026-10-01");
+  }
+  const info = await captureInfo({ env });
+  if (!info.exists || !info.files) {
+    stdout.write("No capture files.\n");
+    return;
+  }
+  stdout.write(`Capture folder ${info.dir}: ${formatBytes(info.bytes)}, ${info.files} day file(s), ${info.oldest}~${info.newest}\n`);
+  stdout.write(`Will delete every day file dated before ${options.before}.\n`);
+  if (!(await confirmYes("Delete them? [y/N] "))) {
+    stdout.write("Nothing deleted (an interactive yes is required).\n");
+    return;
+  }
+  const removed = await purgeCaptureBefore({ env }, options.before);
+  stdout.write(`Deleted ${removed.length} file(s).\n`);
+}
+
+// Disconnect never deletes captured conversations silently: it reports the
+// size, and deletes only with --purge-capture or an interactive "yes".
+async function reportCapture(options, env) {
+  const info = await captureInfo({ env });
+  if (!info.exists || !info.files) return;
+  stdout.write(
+    `  capture folder kept: ${info.dir} (${formatBytes(info.bytes)}, ${info.files} day file(s), oldest ${info.oldest})\n`,
+  );
+  const legacy = legacyLine(info);
+  if (legacy) stdout.write(`  ${legacy}\n`);
+  let purge = options.purgeCapture;
+  if (!purge && stdin.isTTY && stdout.isTTY) {
+    const rl = readline.createInterface({ input: stdin, output: stdout });
+    try {
+      const answer = (await rl.question("Delete these captured conversations now? [y/N] ")).trim().toLowerCase();
+      purge = answer === "y" || answer === "yes";
+    } finally {
+      rl.close();
+    }
+  }
+  if (purge) {
+    await purgeCapture({ env });
+    stdout.write(`  deleted ${info.dir}\n`);
+  } else {
+    stdout.write("  to delete it: forget-connect disconnect --purge-capture\n");
+  }
+}
+
 async function version() {
   const raw = await readFile(new URL("../package.json", import.meta.url), "utf8");
   return JSON.parse(raw).version;
@@ -554,6 +681,11 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     return;
   }
 
+  if (options.action === "capture") {
+    await runCapturePurge(options, env);
+    return;
+  }
+
   const allClients = getClients({ env });
   const clients = await selectClients(options, allClients);
   if (options.action === "status") {
@@ -604,8 +736,19 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
   if (options.action === "doctor") {
     const probeUrl = clients.length ? urlFor(clients[0]) : options.url;
     const probeScope = options.scope ?? scopeFromUrl(probeUrl);
+    // The server may hold a key (install-service wrote one). Clients that
+    // already send it are fine; clients that don't only get a warning.
+    const localKey = isLoopbackUrl(probeUrl) && !options.hosted ? await readLocalApiKey(env) : "";
+    const plainStatuses = await inspectClients(clients, { url: options.url, apiKey, urlFor });
+    const withKey = localKey
+      ? await inspectClients(clients, { url: options.url, apiKey: localKey, urlFor })
+      : [];
     const local = localDoctorResults(
-      await inspectClients(clients, { url: options.url, apiKey, urlFor }),
+      plainStatuses.map((s, i) => (
+        localKey && withKey[i]?.authMatches && !s.authMatches
+          ? { ...s, authMatches: true, transportValid: s.transportValid || withKey[i].transportValid }
+          : s
+      )),
       { requireRules: options.rules },
     );
     const remote = local.every((client) => client.ok)
@@ -636,6 +779,12 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
           skipped: true,
         },
       };
+    const keyWarnings = [];
+    if (localKey) {
+      withKey.forEach((item) => {
+        if (item.config && !item.authMatches) keyWarnings.push(item.client.name);
+      });
+    }
     const hooksStatus = clients.some((client) => client.id === "claude-code")
       ? await inspectHooks({ env, clientId: "claude-code" })
       : null;
@@ -654,10 +803,16 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
       url: redactUrlForDisplay(probeUrl),
       scope: { configured: Boolean(probeScope) },
       clients: local,
+      auth_warnings: {
+        server_has_key: Boolean(localKey),
+        clients_without_key: keyWarnings,
+        hooks_without_key: [hooksStatus, codexHooksStatus].some((h) => h && h.sends_key === false),
+      },
       hooks: hooksStatus,
       codex_hooks: codexHooksStatus,
       skills: skillStatus,
       remote,
+      capture: await captureInfo({ env }),
     };
     if (options.json) stdout.write(`${JSON.stringify(result)}\n`);
     else printDoctor(result);
@@ -882,6 +1037,9 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
       proxyPaths = await removeProxyServices({ env });
     }
   }
+  if (options.action === "disconnect" && !options.dryRun) {
+    await reportCapture(options, env);
+  }
   const verb = options.action === "connect" ? "Connected" : "Disconnected";
   if (!result.changed.length && !hookScriptPaths.length && !proxyPaths.length && !skillPaths.length) {
     stdout.write("No changes needed.\n");
@@ -910,6 +1068,9 @@ export async function run(argv = process.argv.slice(2), env = process.env) {
     }
     if (manageProxy) {
       stdout.write(`  proxy: capture proxy at ${PROXY_BASE_URL} (launchd ${PROXY_LABEL}, watchdog ${WATCHDOG_LABEL})\n`);
+      stdout.write("  proxy RECORDS every Claude Code request and response (secrets scrubbed, owner-only 0600) in ~/.forget/proxy/stream/; kept 7 days, max 2 GB. Turn off: forget-connect disconnect (add --purge-capture to delete the files)\n");
+      const legacyNote = legacyLine(await captureInfo({ env }));
+      if (legacyNote) stdout.write(`  ${legacyNote}\n`);
       if (proxyUpstream) {
         stdout.write(`  proxy upstream: ${proxyUpstream} (your previous ANTHROPIC_BASE_URL, chained)\n`);
       }

package/src/hooks.js

@@ -251,9 +251,12 @@ export async function inspectHooks({ env, clientId = "claude-code" } = {}) {
   }
   const registered = hooksInstalled(settingsRaw, { hooksDir, clientId });
   let scriptsPresent = true;
+  let sendsKey = true;
   for (const script of HOOK_SCRIPTS) {
     try {
-      await readFile(path.join(hooksDir, script), "utf8");
+      const body = await readFile(path.join(hooksDir, script), "utf8");
+      // only scripts that call the server need the Bearer helper
+      if (body.includes("FORGET_MCP_URL") && !body.includes("_auth_headers")) sendsKey = false;
     } catch {
       scriptsPresent = false;
     }
@@ -264,6 +267,7 @@ export async function inspectHooks({ env, clientId = "claude-code" } = {}) {
   return {
     registered,
     scripts_present: scriptsPresent,
+    sends_key: sendsKey,
     python3,
     // registered-but-broken is a failure; absent hooks are a legitimate
     // choice (--no-hooks), so they don't fail the check

package/src/proxy.js

@@ -18,7 +18,7 @@
 
 import { execFile } from "node:child_process";
 import { constants as fsConstants } from "node:fs";
-import { access, readFile, unlink } from "node:fs/promises";
+import { access, readdir, readFile, rm, stat, unlink } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -429,3 +429,98 @@ export async function removeProxyServices(options = {}) {
   }
   return removed;
 }
+
+export const DEFAULT_RETENTION_DAYS = 7;
+
+export function captureDirFor(options = {}) {
+  return path.join(proxyDirFor(options), "stream");
+}
+
+/** Read-only summary of the capture folder: never opens file contents. */
+export async function captureInfo(options = {}) {
+  const env = options.env ?? process.env;
+  const dir = captureDirFor(options);
+  const rawDays = Number(env.FORGET_PROXY_RETENTION_DAYS);
+  const info = {
+    dir,
+    exists: false,
+    files: 0,
+    bytes: 0,
+    oldest: null,
+    newest: null,
+    retention_days: Number.isFinite(rawDays) && env.FORGET_PROXY_RETENTION_DAYS ? rawDays : DEFAULT_RETENTION_DAYS,
+    max_bytes: Number(env.FORGET_PROXY_MAX_BYTES) || 2 * 1024 ** 3,
+    capture_env: !["0", "false", "off", "no"].includes(String(env.FORGET_PROXY_CAPTURE ?? "1").toLowerCase()),
+    service_wired: Boolean(await readWiringState(options)),
+  };
+  let names;
+  try {
+    names = (await readdir(dir)).filter((n) => n.endsWith(".jsonl")).sort();
+    info.exists = true;
+  } catch (error) {
+    if (error && error.code === "ENOENT") return info;
+    throw error;
+  }
+  let since = null;
+  try {
+    const raw = (await readFile(path.join(dir, ".retention-since"), "utf8")).trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(raw)) since = raw;
+  } catch { /* marker absent: the new proxy has not run, every file is old */ }
+  info.since = since;
+  info.legacy = { files: 0, bytes: 0, oldest: null, newest: null };
+  const legacyNames = [];
+  for (const name of names) {
+    try {
+      const st = await stat(path.join(dir, name));
+      info.files += 1;
+      info.bytes += st.size;
+      const day = name.replace(/\.jsonl$/, "");
+      if (since === null || day <= since) {
+        info.legacy.files += 1;
+        info.legacy.bytes += st.size;
+        legacyNames.push(day);
+      }
+    } catch { /* vanished */ }
+  }
+  info.legacy.oldest = legacyNames[0] ?? null;
+  info.legacy.newest = legacyNames.at(-1) ?? null;
+  info.oldest = names[0]?.replace(/\.jsonl$/, "") ?? null;
+  info.newest = names.at(-1)?.replace(/\.jsonl$/, "") ?? null;
+  return info;
+}
+
+export function formatBytes(n) {
+  if (n >= 1024 ** 3) return `${(n / 1024 ** 3).toFixed(1)} GB`;
+  if (n >= 1024 ** 2) return `${(n / 1024 ** 2).toFixed(1)} MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} B`;
+}
+
+/** Delete only the capture folder. Callers must have explicit consent. */
+export async function purgeCapture(options = {}) {
+  await rm(captureDirFor(options), { recursive: true, force: true });
+}
+
+/** "예전 기록 N GB (a~b), 자동으로 지우지 않음" or null when there are none. */
+export function legacyLine(info) {
+  if (!info?.legacy?.files) return null;
+  const l = info.legacy;
+  return `예전 기록 ${formatBytes(l.bytes)} (${l.oldest}~${l.newest}), 자동으로 지우지 않음`;
+}
+
+/** Delete day files dated strictly before ``before`` (YYYY-MM-DD). */
+export async function purgeCaptureBefore(options, before) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(before)) throw new Error("--before needs a date like 2026-10-01");
+  const dir = captureDirFor(options);
+  const removed = [];
+  let names = [];
+  try { names = await readdir(dir); } catch { return removed; }
+  for (const name of names.sort()) {
+    if (!name.endsWith(".jsonl")) continue;
+    if (name.replace(/\.jsonl$/, "") < before) {
+      await unlink(path.join(dir, name));
+      removed.push(name);
+    }
+  }
+  return removed;
+}