@diffin/cli 0.0.0-stage → 0.1.0

package/lib/capture.mjs

@@ -0,0 +1,443 @@
+// `diffin capture` — the new work of every agent session on this machine (`--this`: only
+// the session running it), sent through the same run protocol a backfill uses. The agent decides WHEN (a work
+// boundary); nothing on this machine decides WHAT the work was. Extraction, placement
+// and grouping happen on the server with the same models and rules a backfill gets,
+// so a captured session and a backfilled one come out the same shape and dedup by
+// turn ref. The predecessor's skill had the user's own agent extract atoms locally:
+// a second extractor with a different view, and atoms with no refs that a later
+// backfill could not recognise as its own.
+//
+// There is no confirmation: consent was given at install and is scoped by folder
+// (`--exclude` at backfill, a `.diffin-ignore` file for capture) and paused by
+// `diffin pause`. The agent runs this the way it runs a commit.
+import { readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { SERVER, fetchRetry, reportFail, pinRun, runAuth } from './net.mjs';
+import { tokenOrDie } from './creds.mjs';
+import { claudeCode } from './sources/claude-code.mjs';
+import { adapter, allAdapters } from './sources/index.mjs';
+import { streamCutScrub } from './stream.mjs';
+import { scrub, posixPath } from './scrub.mjs';
+import { clock, dim, fail, marks, say, stepDone, when } from './ui.mjs';
+import { markSent, nextCaptureAt, setNextCapture, pausedSince, pause as pauseState, resume as resumeState, canWriteState, deviceId } from './state.mjs';
+import { putFile } from './backfill.mjs';
+import { machineHash } from './machine.mjs';
+import { detectAgent, agentById } from './agents.mjs';
+import { ensureInit } from './init.mjs';
+import { ALL_LOOKBACK_MS, allowFolders, allowedFolders, allowedSince, excludeFolders, excludedFolders, heldBy, ignoredBy, includeFolder, topFolders, withoutIgnored } from './ignore.mjs';
+import { homedir } from 'node:os';
+
+const ROOT = join(process.env.DIFFIN_HOME ?? homedir(), '.claude', 'projects');
+
+/**
+ * The session being written right now. Claude Code says which one it is
+ * (CLAUDE_CODE_SESSION_ID); when that is absent or points at nothing, the newest
+ * transcript in this folder's project dir is the fallback.
+ */
+export function currentSession(cwd = process.cwd(), env = process.env) {
+  // how the agent names a folder's project dir: separators (and a Windows drive's colon) become '-', and newer
+  // builds turn every character that is not a letter or digit into one. The first spelling that exists is it.
+  const spellings = [...new Set([cwd.replace(/\//g, '-'), cwd.replace(/[\\/:]/g, '-'), cwd.replace(/[^A-Za-z0-9]/g, '-')])];
+  const projectDir = spellings.find((d) => existsSync(join(ROOT, d))) ?? spellings[0];
+  const dir = join(ROOT, projectDir);
+  const named = env.CLAUDE_CODE_SESSION_ID;
+  if (named && /^[A-Za-z0-9_-]+$/.test(named)) {
+    if (existsSync(join(dir, named + '.jsonl'))) {
+      return { sid: named, path: join(dir, named + '.jsonl'), mtime: statSync(join(dir, named + '.jsonl')).mtimeMs, projectDir, how: 'env' };
+    }
+    // The agent names the session; the folder is a guess. A session keeps writing to
+    // the project dir it started in even after the person cd's elsewhere or renames
+    // the folder — measured: a session begun in a folder that was later deleted could
+    // not capture from anywhere. The id is authoritative, so look for it everywhere.
+    if (existsSync(ROOT)) {
+      for (const d of readdirSync(ROOT)) {
+        const f = join(ROOT, d, named + '.jsonl');
+        if (existsSync(f)) return { sid: named, path: f, mtime: statSync(f).mtimeMs, projectDir: d, how: 'env-elsewhere' };
+      }
+    }
+  }
+  if (!existsSync(dir)) return null;
+  let best = null;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.jsonl') || f.startsWith('._')) continue;
+    const m = statSync(join(dir, f)).mtimeMs;
+    if (!best || m > best.mtime) best = { sid: f.replace(/\.jsonl$/, ''), path: join(dir, f), mtime: m, projectDir, how: 'newest' };
+  }
+  return best;
+}
+
+/** what would be sent: the in-window user turns, scrubbed, one line each */
+// every turn, not the first dozen: this printout is what the person approves
+// The preview applies the same resend rules the server's scan applies, so the count
+// and the lines the person approves are what will be recorded: an unanswered turn
+// re-sent (one-character fix, or the same text with more appended) is one turn, and a
+// turn already in the tail before the window (the [PRIOR CONTEXT] lead-in) is not new.
+// The same rule SCAN applies on the server (`pipeline/src/stages/scan.ts`), exported from both so a test can hold
+// them equal: the preview's count is a promise about what the ledger will record.
+export function nearDuplicate(a, b) {
+  const n = Math.max(a.length, b.length);
+  if (n < 16) return false;
+  if (a === b) return true;
+  if (a.length >= 16 && b.startsWith(a)) return true;
+  if (Math.abs(a.length - b.length) > n * 0.1) return false;
+  let p = 0; while (p < a.length && p < b.length && a[p] === b[p]) p++;
+  let q = 0; while (q < a.length - p && q < b.length - p && a[a.length - 1 - q] === b[b.length - 1 - q]) q++;
+  return (p + q) / n >= 0.9;
+}
+const norm = (t) => String(t ?? '').replace(/\[이미지\]/g, '').replace(/\s+/g, ' ').trim();
+
+export async function preview(rows, cutOpts, max = Infinity) {
+  const lines = [];
+  const priorUsers = [];
+  let turns = 0, first = null, last = null;
+  let pending = null; // the last user turn: { at, key } and whether the assistant answered it
+  for await (const line of streamCutScrub(rows, cutOpts)) {
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    if (r.type === 'assistant') {
+      const blocks = Array.isArray(r.message?.content) ? r.message.content : [];
+      const ctx = blocks.find((b) => b?.type === 'text' && String(b.text ?? '').startsWith('[PRIOR CONTEXT'));
+      if (ctx) {
+        let cur = null;
+        const flush = () => { if (cur) { const k = norm(cur); if (k.length > 16) priorUsers.push(k); } cur = null; };
+        for (const l of String(ctx.text).split('\n').slice(1)) { if (l.startsWith('user: ')) { flush(); cur = l.slice(6); } else if (l.startsWith('ai: ')) flush(); else if (cur !== null) cur += '\n' + l; }
+        flush();
+      } else if (pending && blocks.some((b) => (b?.type === 'text' && String(b.text ?? '').trim()) || b?.type === 'tool_use')) pending.answered = true;
+      continue;
+    }
+    if (r.type !== 'user' || !r.uuid || r.isMeta) continue; // meta rows ("Continue from where you left off.") are not turns
+    const c = r.message?.content;
+    const t = (typeof c === 'string' ? c : Array.isArray(c) ? c.filter((b) => b?.type === 'text').map((b) => b.text).join(' ') : '').replace(/\s+/g, ' ').trim();
+    // the same injected-row rule SCAN applies (pipeline/src/stages/scan.ts INJECTED): a
+    // compaction summary is not something the person said, and the preview listed it
+    if (!t || /^\s*<[a-z-]+>|^\s*\{"|^\[Request interrupted|^Caveat:|This session is being continued|<task-notification>|<system-reminder>/.test(t)) continue;
+    // a screenshot's companion row (a temp path, no words) is not a turn — scan drops it too
+    if (!t.replace(/\[Image: source: [^\]]*\]/g, '').replace(/\[이미지\]/g, '').trim()) continue;
+    const key = norm(t);
+    if (key.length > 16 && priorUsers.some((p) => key === p || (p.length >= 200 && key.startsWith(p)))) continue; // already recorded before the window
+    const text = `  ${clock(r.timestamp)}  ${t.slice(0, 110)}${t.length > 110 ? '…' : ''}`;
+    if (pending && !pending.answered && nearDuplicate(pending.key, key)) {
+      // a resend of an unanswered turn takes its place
+      if (pending.at >= 0) lines[pending.at] = text;
+      pending.key = key; last = r.timestamp;
+      continue;
+    }
+    turns++; first ??= r.timestamp; last = r.timestamp;
+    let at = -1;
+    if (lines.length < max) { lines.push(text); at = lines.length - 1; }
+    pending = { at, key, answered: false };
+  }
+  return { turns, first, last, lines };
+}
+
+/**
+ * The server's DECISIONS about a capture — too soon after the last one, the day's
+ * count, the day's spend — are not failures: nothing is lost, the floor stays where it
+ * was and the work goes up with the next capture. Printed as the server said it, with
+ * exit 0, so the agent does not read a refusal it was told to expect as an error to
+ * report; and "too soon" says how long is left, which this machine keeps (state.mjs) so
+ * the next early call ends here without asking. Exported for the test.
+ */
+// 'capture-other-device': another of the person's computers is sending right now; this one's work goes with its next
+const DECISIONS = new Set(['capture-too-soon', 'daily-budget', 'capture-other-device', 'computer-accounts']);
+export function refusal(status, bodyText, now = Date.now()) {
+  if (status !== 429) return null;
+  let b = null; try { b = JSON.parse(bodyText); } catch { return null; }
+  if (!DECISIONS.has(b?.code)) return null;
+  const sec = Number(b.retryAfterSec);
+  return { code: b.code, message: String(b.message ?? ''), until: b.code === 'capture-too-soon' && sec > 0 ? new Date(now + sec * 1000) : null };
+}
+async function refused(res) {
+  const text = await res.text().catch(() => '');
+  const r = refusal(res.status, text);
+  if (!r) { reportFail(res.status, text, '캡처'); process.exitCode = 1; return; }
+  if (r.until) { setNextCapture(r.until); notYet(r.until); return; }
+  say(marks.wait(), r.message, '지금까지의 작업은 다음 기록 때 함께 올라갑니다.');
+}
+/** the one answer to an early capture, whoever found out — this machine or the server */
+function notYet(at) {
+  say(marks.wait(), `다음 기록은 ${when(at)} 이후에 가능합니다.`, '지금까지의 작업은 그때 함께 올라갑니다. 그 전에는 다시 실행하지 않아도 됩니다.');
+}
+
+// which transcript reader and server source a capture from `env` uses: the adapter registered under the agent's
+// source. Claude Code is the default (a plain terminal, or an agent with no adapter), and its session is found by
+// this module's `currentSession`, which knows how Claude Code names a folder's project dir.
+function adapterFor(env = process.env) {
+  const agent = detectAgent(env);
+  const source = agentById(agent)?.source;
+  const ad = source && source !== 'cc' ? adapter(source) : null;
+  if (ad) return { agent, source, ad, session: (cwd) => ad.currentSession(cwd, env) };
+  return { agent: agent ?? 'cc', source: 'cc', ad: claudeCode, session: (cwd) => currentSession(cwd, env) };
+}
+
+export async function capture(argv = []) {
+  const cwd = process.cwd();
+  // --from/--to: re-record a stretch already behind the floor (a record extracted
+  // before its answer existed). The server clamps the window; the ref dedup keeps
+  // everything already owned from being stored twice.
+  const val = (name) => { const i = argv.indexOf(name); return i >= 0 && argv[i + 1] ? argv[i + 1] : undefined; };
+  const window = val('--from') && val('--to') ? { from: val('--from'), to: val('--to') } : undefined;
+  if ((val('--from') || val('--to')) && !window) { fail('--from 과 --to 는 함께 주세요 (ISO 시각).'); process.exitCode = 1; return; }
+  try { ensureInit(); } catch { /* a missing or stale skill is not a reason to lose a capture */ }
+  // the person's two local controls, before anything is read
+  const paused = pausedSince();
+  if (paused) { say(marks.wait(), '일시정지 중입니다. 기록하지 않습니다.', `${when(paused)} 부터 · 다시 켜려면 diffin resume`); return; }
+  // The server said when the next capture may go up, and this machine kept it: an early call ends here, with no
+  // request. This is what makes the agent's own judgment cheap — it cannot know when the person last recorded (another
+  // window, a cleared conversation), so it may ask, and asking costs nothing.
+  const early = nextCaptureAt();
+  if (early) { notYet(early); return; }
+  // which agent are we under? Only one whose transcript we can read may be captured.
+  const agent = detectAgent();
+  if (agent && !agentById(agent)?.capture) {
+    fail(`${agentById(agent)?.name ?? agent} 세션의 캡처는 아직 지원하지 않습니다.`, '지금은 Claude Code, Codex, Antigravity, Hermes 세션을 올릴 수 있습니다. 지원되면 npm install -g @diffin/cli 로 붙습니다.');
+    process.exitCode = 1; return;
+  }
+  // Codex ran this inside its sandbox: nothing can go up from here, and saying so beats a network error the agent
+  // would retry. `diffin init`, run once from a terminal, writes the rule that lets the command out (settings.mjs).
+  if (agent === 'codex' && !canWriteState()) {
+    say(marks.wait(), 'Codex 의 샌드박스 안이라 올릴 수 없습니다.', '터미널에서 diffin init 을 한 번 실행한 뒤 Codex 를 다시 시작하세요. 그리고 diffin capture 는 다른 명령과 묶지 말고 단독으로 실행해야 합니다.');
+    return;
+  }
+  // Every session on this machine is the default: whichever session asks, every
+  // session's new turns go (see captureAll). `--this` is the one-session form, and an
+  // explicit --from/--to window is always about one session. Each folder's own
+  // .diffin-ignore is checked per session there, so this folder's does not stop others.
+  if (argv.includes('--all') && window) { fail('--all 에는 --from/--to 를 함께 쓸 수 없습니다.'); process.exitCode = 1; return; }
+  if (!argv.includes('--this') && !window) return captureAll();
+  const excl = ignoredBy(cwd);
+  if (excl) { say(marks.wait(), '이 폴더는 기록하지 않습니다.', `${posixPath(scrub(excl))} 를 제외해 두었습니다. 되돌리려면 diffin include`); return; }
+  if (heldBy(cwd)) { say(marks.wait(), '이 폴더는 아직 기록하지 않습니다.', `${posixPath(scrub(cwd))} 는 허용한 폴더가 아닙니다. 허용하려면 터미널에서 diffin allow . (사람이 직접 실행합니다)`); return; }
+  const { agent: under, source, ad, session: find } = adapterFor();
+  const session = find(cwd);
+  if (!session) { fail(`이 폴더의 ${agentById(under).name} 세션을 찾지 못했습니다.`, scrub(cwd)); process.exitCode = 1; return; }
+
+  const token = tokenOrDie();
+  // a Hermes session names its own folder; a Claude Code one is found by the folder
+  const container = posixPath(scrub(session.cwd ?? cwd));
+  // the server owns the boundary: the later of this session's last recorded work and
+  // the source's watermark. The CLI only names the session and asks.
+  const res = await fetchRetry(`${SERVER}/backfill/runs`, () => ({
+    method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ source, device: deviceId(), ...(machineHash() ? { computer: machineHash() } : {}), capture: { container, session: session.sid, ...(window ?? {}) } }),
+  }));
+  if (!res.ok) { await refused(res); return; }
+  const { runId, machine, from, to, resumed, done } = await res.json();
+  pinRun(machine);
+  const cutOpts = { tsOf: ad.tsOf, fromMs: new Date(from).getTime(), toMs: new Date(to).getTime() };
+
+  // the entry for this one session, the way the adapter would list it
+  const entry = ad.enumerate({ from }).find((e) => e.sid === session.sid);
+  if (!entry) { say(marks.wait(), '이번 세션에 올릴 새 작업이 없습니다.'); await discard(token, runId, resumed); return; }
+
+  const p = await preview(entry.files[0].rows(), cutOpts);
+  const since = when(from);
+  if (!p.turns) { say(marks.wait(), `${since} 이후 새 작업이 없습니다.`); await discard(token, runId, resumed); return; }
+
+  const landed = new Set((done ?? []).find((d) => d.sid === session.sid)?.paths ?? []);
+  const projectDir = scrub(entry.projectDir);
+  let failed = 0;
+  for (const file of entry.files) {
+    if (landed.has(file.path)) continue;
+    const r = await putFile(token, runId, session.sid, projectDir, file, cutOpts);
+    if (r === 'failed') { failed++; break; }
+    if (r === 'empty' && file.path === 'main') break;
+  }
+  if (failed) { fail('올리지 못했습니다.', 'diffin capture 를 다시 실행하면 이어서 올립니다.'); process.exitCode = 1; return; }
+  const fin = await fetchRetry(`${SERVER}/backfill/runs/${runId}/complete`, () => ({ method: 'POST', headers: runAuth(token) }));
+  const fin2 = fin.ok ? await fin.json() : null;
+  if (fin2?.status === 'ready') { stepDone('올렸습니다', `발화 ${p.turns}개`, dim('몇 분 뒤 앱에 반영됩니다')); wentUp(fin2); }
+  else if (fin2?.status === 'empty') say(marks.wait(), '올릴 내용이 없었습니다.');
+  else { fail('완료 처리에 실패했습니다.', 'diffin capture 를 다시 실행하세요.'); process.exitCode = 1; }
+}
+
+/** how many sessions one capture may name — the server's own bound (backfill.controller.ts MAX_CAPTURE_SESSIONS),
+ *  past which it refuses the whole request. With every agent's sessions offered the list is kept under it here:
+ *  the sessions that moved last go, and the rest wait for the next capture, their floors where they were. */
+const MAX_OFFERED = 200;
+export const newestFirst = (offered, max = MAX_OFFERED) => [...offered].sort((a, b) => (b.e.last ?? 0) - (a.e.last ?? 0)).slice(0, max);
+
+/**
+ * The sessions a capture of every session would send, and each one's cut. Exported
+ * for the tests: which sessions are offered, which are held back by a folder's
+ * .diffin-ignore, and that each is cut to its OWN floor.
+ */
+export async function planAll(ad, floors, to, entries) {
+  const plan = [];
+  for (const e of entries) {
+    const from = floors?.[e.sid];
+    if (!from) continue;
+    const cut = { tsOf: ad.tsOf, fromMs: new Date(from).getTime(), toMs: new Date(to).getTime() };
+    const p = await preview(e.files[0].rows(), cut);
+    if (p.turns) plan.push({ entry: e, cut, p, from });
+  }
+  return plan;
+}
+
+/**
+ * Candidate sessions: moved recently, and not in a folder the person excluded (ignore.mjs — the folder it began in
+ * or the one it is in now, either of them under a `.diffin-ignore`).
+ */
+export async function candidates(ad, now = Date.now(), { hold = false } = {}) {
+  return withoutIgnored(ad.enumerate({ from: new Date(now - ALL_LOOKBACK_MS).toISOString() }), { hold });
+}
+
+/**
+ * A machine with no allow list yet is converted without being asked (decided 2026-10-11): the folders of the sessions
+ * a capture would send now become the list, and from then on a folder under none of them is held. A machine with no
+ * sessions to read is left without a list — there is nothing to seed it from, and holding everything would be wrong.
+ */
+async function seedAllowed() {
+  if (allowedFolders() !== null) return;
+  const dirs = [];
+  // both folders of a session — where it began and where it is — or a session that moved would be held by the seed it made
+  for (const ad of allAdapters()) { try { const { kept } = await candidates(ad); dirs.push(...kept.flatMap((e) => [e.cwd, e.cwd0]).filter(Boolean)); } catch { /* an unreadable agent seeds nothing */ } }
+  if (dirs.length) allowFolders(topFolders(dirs));
+}
+
+/** a scrubbed folder name (`~/x`) back to this machine's path — the app decides in the names the CLI reported */
+const unscrub = (p) => (p === '~' ? homedir() : p.startsWith('~/') ? join(homedir(), p.slice(2)) : p);
+
+/**
+ * The app's side of the allow list (`docs/folder-consent.md`, step 2): tell the server which folders this machine holds,
+ * allows and excludes (its deny list; a `.diffin-ignore` file is not a list) — names only — and take back the decisions
+ * the person made in the app: an allowance lifts an exclusion too, as `diffin include` would, and is dated by the
+ * decision's own time — only the work after it goes up. Nothing here may stop a capture: a server that cannot be
+ * reached, or an older server without the route, leaves the lists as they are.
+ */
+async function syncFolders(token, heldAll) {
+  const allowed = allowedFolders();
+  if (allowed === null) return { changed: false };
+  const held = topFolders(heldAll.map((h) => h.folder).filter(Boolean)).map((f) => posixPath(scrub(f)));
+  let body = null;
+  try {
+    const res = await fetchRetry(`${SERVER}/folders/held`, () => ({ method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify({ device: deviceId(), held, allowed: allowed.map((f) => posixPath(scrub(f))), excluded: excludedFolders().map((f) => posixPath(scrub(f))) }) }), 1);
+    if (res.ok) body = await res.json();
+  } catch { /* the capture goes on with the lists this machine has */ }
+  const decisions = Array.isArray(body?.decisions) ? body.decisions : [];
+  if (!decisions.length) return { changed: false };
+  const applied = [];
+  for (const d of decisions) {
+    const dir = unscrub(String(d.path ?? '')); if (!dir) continue;
+    if (d.decision === 'allow') { includeFolder(dir); allowFolders([dir], Number.isNaN(Date.parse(String(d.at))) ? new Date() : new Date(String(d.at))); say(marks.done(), `${posixPath(scrub(dir))} 를 앱에서 허용했습니다. 허용한 뒤의 작업부터 올라갑니다.`); }
+    else if (d.decision === 'exclude') { excludeFolders([dir]); say(marks.wait(), `${posixPath(scrub(dir))} 를 앱에서 제외했습니다.`); }
+    else continue;
+    applied.push(String(d.id));
+  }
+  if (applied.length) { try { await fetchRetry(`${SERVER}/folders/applied`, () => ({ method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify({ device: deviceId(), ids: applied }) }), 1); } catch { /* reported next time: the server hands an unapplied decision back, and applying it again changes nothing */ } }
+  return { changed: applied.length > 0 };
+}
+
+/** the one line about folders waiting for the person — the agent relays it, the person acts on a terminal */
+function sayHeld(held) {
+  const folders = topFolders(held.map((h) => h.folder).filter(Boolean));
+  if (!folders.length) return;
+  say(marks.wait(), `새 폴더 ${folders.length}곳은 아직 기록하지 않습니다 · ${folders.map((f) => posixPath(scrub(f))).join(' · ')}`,
+    '허용하려면 터미널에서 diffin allow <폴더> 또는 diffin folders (사람이 직접 실행합니다)');
+}
+
+/**
+ * `diffin capture` (the default; `--all` says it out loud) — every session's new turns,
+ * whichever session asks. `diffin capture --this` is the one-session form.
+ *
+ * People run several agent sessions at once, in several folders. A capture of one
+ * session left the others to wait for their own boundary, and the gap between
+ * captures (five hours; an hour when this was measured, twice in one afternoon) is per
+ * person — so one session's capture kept every other session from recording. Here each session is held
+ * to its own floor, which the server computes; the CLI names the sessions and when
+ * each last moved, and sends only what lies past each floor.
+ */
+async function captureAll() {
+  const { source } = adapterFor();
+  const token = tokenOrDie();
+  // Every AGENT's sessions, not only the asking one's. The gap between captures is per person, so a capture that
+  // sent one agent's sessions kept the others' waiting for their own agent to ask after the gap — with three agents
+  // on a machine, most of a day's work. The run is the asker's; a session of another agent names its own.
+  await seedAllowed();
+  const gather = async () => {
+    const found = [], heldAll = [];
+    for (const ad of allAdapters()) {
+      let kept = [], held = [];
+      try { ({ kept, held } = await candidates(ad, Date.now(), { hold: true })); } catch { /* an agent whose sessions cannot be read holds nobody else back */ }
+      for (const e of kept) found.push({ ad, e });
+      heldAll.push(...held);
+    }
+    return { found, heldAll };
+  };
+  let { found, heldAll } = await gather();
+  // the app may have decided on a held folder since the last capture: apply, then look again with the lists as they are now
+  const { changed } = await syncFolders(token, heldAll);
+  if (changed) ({ found, heldAll } = await gather());
+  // a session of a folder the person allowed after the fact goes up from that moment: the later of its two folders' times
+  const sinceOf = (e) => { const ts = [e.cwd, e.cwd0].map((c) => allowedSince(c)).filter(Boolean).sort(); return ts.length ? ts[ts.length - 1] : null; };
+  const offered = newestFirst(found);
+  if (!offered.length) { say(marks.wait(), '최근 움직인 세션이 없습니다.'); sayHeld(heldAll); return; }
+  const res = await fetchRetry(`${SERVER}/backfill/runs`, () => ({
+    method: 'POST', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ source, device: deviceId(), ...(machineHash() ? { computer: machineHash() } : {}), capture: { all: true, sessions: offered.map(({ ad, e }) => ({ id: e.sid, ...(e.last ? { last: new Date(e.last).toISOString() } : {}), ...(sinceOf(e) ? { since: sinceOf(e) } : {}), ...(ad.name !== source ? { source: ad.name } : {}) })) } }),
+  }));
+  if (!res.ok) { await refused(res); return; }
+  const { runId, machine, to, floors, resumed, done } = await res.json();
+  pinRun(machine);
+  const plan = [];
+  for (const ad of allAdapters()) plan.push(...await planAll(ad, floors, to, offered.filter((o) => o.ad === ad).map((o) => o.e)));
+  if (!plan.length) {
+    say(marks.wait(), '모든 세션에 새 작업이 없습니다.');
+    sayHeld(heldAll);
+    await discard(token, runId, resumed);
+    return;
+  }
+
+  const total = plan.reduce((n, x) => n + x.p.turns, 0);
+  let failed = 0;
+  const sent = [];
+  for (const { entry, cut } of plan) {
+    const landed = new Set((done ?? []).find((d) => d.sid === entry.sid)?.paths ?? []);
+    const projectDir = scrub(entry.projectDir);
+    for (const file of entry.files) {
+      if (landed.has(file.path)) continue;
+      const r = await putFile(token, runId, entry.sid, projectDir, file, cut);
+      if (r === 'failed') { failed++; break; }
+      if (r === 'empty' && file.path === 'main') break;
+    }
+    if (failed) break;
+    sent.push(entry.sid);
+  }
+  if (failed) { fail('올리지 못했습니다.', 'diffin capture 를 다시 실행하면 이어서 올립니다.'); process.exitCode = 1; return; }
+  const fin = await fetchRetry(`${SERVER}/backfill/runs/${runId}/complete`, () => ({ method: 'POST', headers: runAuth(token) }));
+  const finBody = fin.ok ? await fin.json() : null;
+  const st = finBody?.status ?? null;
+  if (st === 'ready' || st === 'empty') {
+    const folders = new Set(plan.filter((x) => sent.includes(x.entry.sid)).map((x) => x.entry.cwd ?? x.entry.projectDir)).size;
+    if (st === 'ready') stepDone('올렸습니다', `폴더 ${folders}곳 · 발화 ${total}개`, dim('몇 분 뒤 앱에 반영됩니다')); else say(marks.wait(), '올릴 내용이 없었습니다.');
+    if (st === 'ready') wentUp(finBody);
+    sayHeld(heldAll);
+  } else { fail('완료 처리에 실패했습니다.', 'diffin capture 를 다시 실행하세요.'); process.exitCode = 1; }
+}
+
+/** a capture went up: keep the server's word on when the next may, and say it — the agent reads this line */
+function wentUp(body) {
+  markSent();
+  const at = body?.nextCaptureAt ? new Date(body.nextCaptureAt) : null;
+  if (at && Number.isFinite(at.getTime())) { setNextCapture(at); say(marks.wait(), dim(`다음 기록은 ${when(at)} 이후에 가능합니다.`)); }
+  else setNextCapture(null);
+}
+
+// a run with nothing in it: tell the server so it is removed rather than left open
+// (an open run would be handed back next time as "resume")
+async function discard(token, runId, resumed) {
+  if (!runId || resumed) return; // nothing was opened; or a resumed run held files from before
+  await fetchRetry(`${SERVER}/backfill/runs/${runId}/complete`, () => ({ method: 'POST', headers: runAuth(token) })).catch(() => null);
+}
+
+/** `diffin pause` — off the record until `diffin resume`: nothing is sent, and what is said meanwhile never is */
+export function pause() {
+  const was = pausedSince();
+  const since = pauseState();
+  if (was) say(marks.wait(), `이미 일시정지 중입니다. ${when(since)} 부터`, '다시 켜려면 diffin resume');
+  else say(marks.done(), '기록을 멈췄습니다.', '지금부터의 대화는 올라가지 않습니다. 다시 켜면 그 뒤의 대화부터 기록합니다.', '다시 켜려면 diffin resume');
+}
+export function resume() {
+  const from = resumeState();
+  if (from) say(marks.done(), '기록을 다시 켰습니다.', `${when(from)} 부터 지금까지의 대화는 올라가지 않습니다.`);
+  else say(marks.wait(), '일시정지 상태가 아니었습니다.');
+}

package/lib/command.mjs

@@ -0,0 +1,44 @@
+// The `diffin` command on PATH — what the agent runs (`diffin capture`, the skill's one command) long after the person
+// ran `npx @diffin/cli onboard` once. npx runs the package from its cache and leaves nothing on PATH, so without this
+// the first capture an agent asked for answered "command not found" on every machine but the developer's own (where
+// `npm link` had put one). Onboarding installs it globally, at the version that is running, unless a command of that
+// version or newer is already there (a developer's link is newer or equal and is left alone).
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const win = process.platform === 'win32';
+const pkg = () => JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+export const PACKAGE = () => pkg().name;
+
+/** the version of the `diffin` on PATH, or null when there is none (or it does not answer) */
+export function commandVersion() {
+  const r = spawnSync(win ? 'diffin.cmd' : 'diffin', ['--version'], { encoding: 'utf8', timeout: 15_000, shell: win, stdio: ['ignore', 'pipe', 'ignore'] });
+  const v = r.status === 0 ? String(r.stdout).trim().split('\n').pop() : '';
+  return /^\d+\.\d+\.\d+/.test(v) ? v : null;
+}
+
+/** a ≥ b, by numbers */
+export function atLeast(a, b) {
+  const x = String(a).split(/[.-]/).map(Number), y = String(b).split(/[.-]/).map(Number);
+  for (let i = 0; i < 3; i++) { if ((x[i] || 0) !== (y[i] || 0)) return (x[i] || 0) > (y[i] || 0); }
+  return true;
+}
+
+/** install this package globally at `version`; returns null on success or the last lines npm printed */
+export function installCommand(version) {
+  const r = spawnSync(win ? 'npm.cmd' : 'npm', ['install', '-g', `${PACKAGE()}@${version}`, '--no-fund', '--no-audit', '--loglevel=error'], { encoding: 'utf8', timeout: 300_000, shell: win, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (r.status === 0) return null;
+  return (String(r.stderr || r.stdout || r.error?.message || '').trim().split('\n').slice(-2).join(' ') || `npm exited ${r.status}`).slice(0, 200);
+}
+
+/** make sure the agent can run `diffin`: { state: 'present' | 'installed' | 'failed', version, error? } */
+export function ensureCommand(version) {
+  const have = commandVersion();
+  if (have && atLeast(have, version)) return { state: 'present', version: have };
+  const error = installCommand(version);
+  const now = commandVersion();
+  if (!error && now && atLeast(now, version)) return { state: 'installed', version: now };
+  return { state: 'failed', version: now, error: error ?? 'installed, but `diffin` is not on PATH' };
+}

package/lib/creds.mjs

@@ -0,0 +1,35 @@
+// Token storage. The CLI's credential does not expire (the server confines it to the upload routes instead), so
+// there is nothing to renew. The token lives in ~/.diffin/credentials.json at
+// 0600; DIFFIN_TOKEN in the environment overrides it (the ops runbook injects a
+// per-run token, and testing injects one) and is never written back.
+import { chmodSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fail } from './ui.mjs';
+
+const DIR = join(process.env.DIFFIN_HOME ?? homedir(), '.diffin');
+const PATH = join(DIR, 'credentials.json');
+
+export function readCreds() {
+  let saved = null;
+  try { saved = JSON.parse(readFileSync(PATH, 'utf8')); } catch { /* none yet */ }
+  if (process.env.DIFFIN_TOKEN) return { ...(saved ?? {}), token: process.env.DIFFIN_TOKEN };
+  return saved;
+}
+
+export function writeCreds(c) {
+  mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  writeFileSync(PATH, JSON.stringify(c, null, 2) + '\n', { mode: 0o600 });
+  // `mode` applies only when the file is created: one that was there already keeps the permissions it had, and this
+  // token no longer expires. (Windows has no such bits; the profile folder's own protection stands.)
+  try { chmodSync(PATH, 0o600); } catch { /* not a filesystem that has them */ }
+}
+
+export function tokenOrDie() {
+  const t = readCreds()?.token;
+  if (!t) {
+    fail('로그인이 필요합니다.', 'diffin login <설치토큰> — 토큰은 앱의 연결 화면에 있습니다.');
+    process.exit(1);
+  }
+  return t;
+}

package/lib/folders.mjs

@@ -0,0 +1,76 @@
+// `diffin allow` · `diffin folders` — the person widens (or narrows) what a capture may send, on a TERMINAL only.
+//
+// The allow list (ignore.mjs, `docs/folder-consent.md`) is the person's; an agent runs commands without a terminal
+// (stdin and stdout are not TTYs under Claude Code, Codex, Cursor), so a command that insists on one cannot be run by
+// the agent that just asked for a capture — the same gate the onboarding's folder list already has. The capture's own
+// result line names the held folders and these two commands; the agent relays the line, the person types.
+import { resolve as resolvePath } from 'node:path';
+import { allAdapters } from './sources/index.mjs';
+import { ALL_LOOKBACK_MS, allowFolders, allowedFolders, allowedFrom, excludeFolders, excludedFrom, folderCensus, folderTree, heldBy, ignoreFileFor, includeFolder, topFolders, withoutIgnored } from './ignore.mjs';
+import { posixPath, scrub } from './scrub.mjs';
+import { dim, fail, ok, out, selectMany, spin, stepLive } from './ui.mjs';
+
+const n = (x) => x.toLocaleString('ko-KR');
+export const onTerminal = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+const needTerminal = (cmd) => { fail('사람이 터미널에서 실행해야 합니다.', `${cmd} 는 에이전트가 아니라 사람이 직접 터미널에서 실행하는 명령입니다. 터미널을 열어 같은 명령을 입력하세요.`); process.exitCode = 1; };
+
+/** the sessions of every agent that moved recently, and the folders among them waiting to be allowed */
+async function recent() {
+  const now = Date.now(), fromMs = now - ALL_LOOKBACK_MS;
+  const jobs = [], heldDirs = [];
+  for (const ad of allAdapters()) {
+    try {
+      const { kept, held } = await withoutIgnored(ad.enumerate({ from: new Date(fromMs).toISOString() }), { hold: true });
+      jobs.push({ ad, entries: [...kept, ...held.map((h) => h.entry)], cutOpts: { tsOf: ad.tsOf, fromMs, toMs: now } });
+      heldDirs.push(...held.map((h) => h.folder));
+    } catch { /* an agent whose sessions cannot be read is left out */ }
+  }
+  return { jobs, held: topFolders(heldDirs) };
+}
+
+/** `diffin allow [폴더 | . | --all]` — this folder and everything under it may be recorded from now on */
+export async function allow(argv = []) {
+  if (!onTerminal()) return needTerminal('diffin allow');
+  let dirs;
+  if (argv.includes('--all')) {
+    dirs = (await recent()).held;
+    if (!dirs.length) { out(`  ${dim('○')} 기다리는 폴더가 없습니다.`); return; }
+  } else dirs = [resolvePath(argv[0] ?? process.cwd())];
+  for (const dir of dirs) {
+    includeFolder(dir);
+    allowFolders([dir], new Date());
+    ok(`${posixPath(scrub(dir))} 와 그 아래 폴더를 기록합니다.`);
+    const file = ignoreFileFor(dir);
+    if (file) out(dim(`    ${posixPath(scrub(file))} 에 .diffin-ignore 파일이 있어 그 아래는 계속 제외됩니다. 그 파일을 지우면 기록합니다.`));
+  }
+  out(dim('    지금부터의 작업이 다음 캡처부터 올라갑니다. 허용 전의 대화는 올라가지 않습니다.'));
+}
+
+/**
+ * `diffin folders` — the onboarding's list again, over the folders recent sessions were made in: folders waiting to
+ * be allowed are marked and switched on, allowed ones on, excluded ones are not shown (they are `diffin include`'s).
+ * Enter keeps what is on and excludes what was switched off.
+ */
+export async function folders() {
+  if (!onTerminal()) return needTerminal('diffin folders');
+  const stop = spin((frame) => stepLive(frame, '폴더 살펴보기', dim('어느 폴더에서 한 작업인지 읽고 있습니다')));
+  const turns = new Map();
+  let held = [];
+  try {
+    const r = await recent(); held = r.held;
+    for (const j of r.jobs) for (const [dir, c] of await folderCensus(j.entries, j.cutOpts)) turns.set(dir, (turns.get(dir) ?? 0) + c);
+  } finally { stop(); }
+  const tree = folderTree(turns);
+  if (!tree.length) { out(`  ${dim('○')} 최근 작업한 폴더가 없습니다.`); return; }
+  const isHeld = (dir) => heldBy(dir);
+  const items = tree.map((it) => ({ label: it.parent == null ? posixPath(scrub(it.dir)) : posixPath(it.rel), tail: `발화 ${n(it.turns)}개${isHeld(it.dir) && (it.parent == null || !isHeld(tree[it.parent].dir)) ? ' · 새 폴더, 아직 기록하지 않음' : ''}`, parent: it.parent }));
+  const picked = await selectMany({ title: '기록할 폴더', note: `이 기기에서 최근 작업한 폴더입니다. 켜진 폴더와 그 아래만 기록합니다.${held.length ? ` 새 폴더 ${held.length}곳이 기다리고 있습니다.` : ''}`, items, initial: tree.map(() => true),
+    unit: (on) => `폴더 ${on.filter(Boolean).length}곳 기록` });
+  if (!picked) { out('취소했습니다. 바뀐 것은 없습니다.'); process.exitCode = 1; return; }
+  const on = allowedFrom(tree, picked), off = excludedFrom(tree, picked);
+  for (const d of on) includeFolder(d);
+  allowFolders(on, new Date()); // folders already allowed keep their time; the ones switched on now are allowed from now
+  if (off.length) excludeFolders(off);
+  ok(`기록하는 폴더 ${n((allowedFolders() ?? []).length)}곳${off.length ? ` · 제외한 폴더 ${off.map((f) => posixPath(scrub(f))).join(' · ')}` : ''}`);
+  out(dim('    다음 캡처부터 적용됩니다 · 되돌리려면 diffin include <폴더> 또는 다시 diffin folders'));
+}