@diffin/cli 0.0.0-stage → 0.1.0

package/lib/ignore.mjs

@@ -0,0 +1,208 @@
+// `.diffin-ignore` — a file a person puts in a folder to say: nothing made here is recorded.
+//
+// It covers the folder AND everything under it, found the way git finds a .gitignore: from the session's folder up
+// to the root. (It used to match the one folder exactly, so a file in ~/proj did nothing for a session opened in
+// ~/proj/server — the person had said "not this project" and half of it went up.) And it holds for every command
+// that sends: a capture and a BACKFILL alike. The backfill read only `--exclude`, so the first upload of a new
+// agent, a retry, or `--extend` sent a folder the person had already marked.
+//
+// A session is held back when the folder it began in OR the folder it is in now is covered — a session keeps writing
+// to the project dir it started in after the person cd's elsewhere, so the first folder alone would let a session
+// that moved INTO an excluded folder through. A session that only PASSES THROUGH one is not held back here: its rows
+// made there are cut one by one where every row is streamed out (`stream.mjs` `streamCutScrub`, `cli/test/ignore.mjs`),
+// since each row says the folder it was made in. Not covered by either: a file of an excluded folder reached by its
+// path from a session elsewhere — the row's folder is the session's, not the file's.
+import { existsSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { readState, writeState } from './state.mjs';
+
+/** how far back a capture of every session looks (capture.mjs), and what a later connect's folder list covers (backfill.mjs), for sessions that moved — a cheap
+ *  mtime superset of the entitlement; the server's floors decide what is actually sent */
+export const ALL_LOOKBACK_MS = 8 * 86_400_000;
+
+const FILE = '.diffin-ignore';
+const seen = new Map();
+
+/** the folder that excludes `dir` — itself or an ancestor holding the file — or null */
+export function ignoredBy(dir) {
+  if (!dir || typeof dir !== 'string') return null;
+  if (seen.has(dir)) return seen.get(dir);
+  // a folder the person switched off in the list (or with `diffin exclude`) is excluded the same way, it and all under it
+  const off = excludedFolders().find((x) => dir === x || dir.startsWith(x.endsWith(sep) ? x : x + sep)) ?? null;
+  if (off) { seen.set(dir, off); return off; }
+  let d = dir, found = null;
+  for (let i = 0; i < 64; i++) {
+    if (existsSync(join(d, FILE))) { found = d; break; }
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  seen.set(dir, found);
+  return found;
+}
+
+/**
+ * Folders excluded without a file in them: the ones switched off in the first upload's list, or named with
+ * `diffin exclude`. Kept on this machine (state.json) rather than written into the person's project as a
+ * `.diffin-ignore` — a file appearing in a repository is a change to someone's work that they did not make.
+ */
+export function excludedFolders() {
+  const x = readState().excluded;
+  return Array.isArray(x) ? x.filter((f) => typeof f === 'string' && f) : [];
+}
+export function excludeFolders(folders) {
+  const s = readState();
+  s.excluded = [...new Set([...excludedFolders(), ...folders.filter(Boolean)])];
+  writeState(s); seen.clear();
+}
+export function includeFolder(folder) {
+  const s = readState();
+  const before = excludedFolders();
+  s.excluded = before.filter((f) => f !== folder);
+  if (!s.excluded.length) delete s.excluded;
+  writeState(s); seen.clear();
+  return before.length !== (s.excluded?.length ?? 0);
+}
+/**
+ * The ALLOW list (2026-10-11, `docs/folder-consent.md`): the folders the person switched ON at onboarding (or allowed
+ * since), kept here beside the excluded ones. Once a machine has one, a session in a folder under none of them is
+ * HELD — not sent, its floor untouched — until the person allows that folder (`diffin allow`, `diffin folders`, both on
+ * a terminal only). `null` means this machine has no list yet: nothing is held, and the first capture seeds the list
+ * from the folders it would send (an existing machine is converted without being asked). A denial beats an allowance.
+ */
+export function allowedFolders() {
+  const x = readState().allowed;
+  return Array.isArray(x) ? x.filter((f) => typeof f === 'string' && f) : null;
+}
+/** of a set of folders, the ones not under another of the set */
+export function topFolders(folders) {
+  const u = [...new Set(folders.filter((f) => typeof f === 'string' && f))].sort();
+  return u.filter((d) => !u.some((x) => x !== d && d.startsWith(x.endsWith(sep) ? x : x + sep)));
+}
+/**
+ * Allow folders. `at` is the moment the PERSON allowed them (a terminal command, the app's decision): only the work after
+ * it goes up (`allowedSince`, sent as a capture session's `since`). The onboarding list and the seed pass no time — those
+ * folders' history is the backfill's and the watermark's, as before.
+ */
+export function allowFolders(folders, at) {
+  const s = readState();
+  const had = new Set(allowedFolders() ?? []);
+  s.allowed = topFolders([...had, ...folders]);
+  if (at) { s.allowedAt = { ...(s.allowedAt ?? {}) }; for (const f of folders) if (f && !had.has(f) && !allowedBy(f)) s.allowedAt[f] = new Date(at).toISOString(); }
+  writeState(s); seen.clear();
+}
+/** when the person allowed the folder covering `dir` — null for a folder of the onboarding list or the seed, or none */
+export function allowedSince(dir) {
+  const a = allowedBy(dir); if (!a) return null;
+  const at = readState().allowedAt?.[a];
+  return typeof at === 'string' && !Number.isNaN(Date.parse(at)) ? at : null;
+}
+/** the allowed folder covering `dir`, or null (also null while the machine has no list) */
+export function allowedBy(dir) {
+  const a = allowedFolders();
+  if (!a || !dir || typeof dir !== 'string') return null;
+  return a.find((x) => dir === x || dir.startsWith(x.endsWith(sep) ? x : x + sep)) ?? null;
+}
+/** a folder that is neither excluded nor allowed, on a machine that has an allow list: its sessions wait */
+export function heldBy(dir) {
+  if (!dir || typeof dir !== 'string' || allowedFolders() === null) return false;
+  return !ignoredBy(dir) && !allowedBy(dir);
+}
+/** the folders to remember as allowed, from the list's answer: a folder that is on under one that is off (or under none) */
+export function allowedFrom(tree, on) {
+  return tree.filter((it, i) => on[i] && (it.parent == null || !on[it.parent])).map((it) => it.dir);
+}
+
+/** whether a `.diffin-ignore` FILE (not the list) is what excludes `dir` */
+export function ignoreFileFor(dir) {
+  let d = dir;
+  for (let i = 0; i < 64 && d; i++) { if (existsSync(join(d, FILE))) return d; const up = dirname(d); if (up === d) break; d = up; }
+  return null;
+}
+
+/** the folder a session began in, as its rows say — the first row that names one (a few rows at most) */
+export async function firstCwd(entry) {
+  if (entry.cwd) return entry.cwd;
+  let n = 0;
+  for await (const r of entry.files[0].rows()) {
+    if (r?.cwd) return String(r.cwd);
+    if (++n > 200) break;
+  }
+  return null;
+}
+
+/** where a session began and where it is now, and whether either is excluded */
+export async function sessionFolders(entry) {
+  const first = await firstCwd(entry).catch(() => null);
+  const last = (typeof entry.lastCwd === 'function' ? entry.lastCwd() : null) ?? first;
+  return { first, last, ignored: Boolean(ignoredBy(first) || ignoredBy(last)) };
+}
+
+/**
+ * Where the work in a window was actually done: the folder of every turn the person made, counted. A session is not
+ * in one folder — each row says where it was made, and an agent moves about as it runs commands — so a list built from
+ * one folder per session was wrong whichever one it took (the last showed a repository's cli/ as a project of its own,
+ * the first a name the folder no longer has). This reads the rows. Costs one pass over the transcripts: measured
+ * 246,798 rows in 4.3 s on the owner's machine.
+ */
+export async function folderCensus(entries, { tsOf, fromMs = 0, toMs = Infinity }) {
+  const turns = new Map();
+  for (const e of entries) {
+    for await (const r of e.files[0].rows()) {
+      if (r?.type !== 'user' || r.isMeta) continue;
+      const t = tsOf(r);
+      if (t && (t < fromMs || t >= toMs)) continue;
+      const c = r.message?.content;
+      const said = typeof c === 'string' ? c.trim() : Array.isArray(c) && !c.some((b) => b?.type === 'tool_result') && c.some((b) => b?.type === 'text' && String(b.text ?? '').trim());
+      if (!said) continue;
+      const dir = String(r.cwd ?? e.cwd ?? '');
+      if (!dir || ignoredBy(dir)) continue;
+      turns.set(dir, (turns.get(dir) ?? 0) + 1);
+    }
+  }
+  return turns;
+}
+
+/**
+ * The census as a tree for the list: a folder sits under the nearest folder OF THE LIST that contains it, so the
+ * grouping is what the transcripts say and nothing is guessed (no looking for a repository's root). Items come in
+ * display order — a top folder, then everything under it — each with the turns made in it and under it.
+ */
+export function folderTree(turns) {
+  const dirs = [...turns.keys()].sort();
+  const under = (a, b) => a !== b && a.startsWith(b.endsWith(sep) ? b : b + sep);
+  const parentOf = (d) => dirs.filter((x) => under(d, x)).sort((a, b) => b.length - a.length)[0] ?? null;
+  const total = (d) => dirs.filter((x) => x === d || under(x, d)).reduce((t, x) => t + turns.get(x), 0);
+  const tops = dirs.filter((d) => !parentOf(d)).sort((a, b) => total(b) - total(a));
+  const out = [];
+  for (const t of tops) {
+    out.push({ dir: t, parent: null, turns: total(t), own: turns.get(t) });
+    // `rel` is the path under the folder it sits beneath, so a nested line reads as a step down from the one above it
+    for (const d of dirs.filter((x) => under(x, t))) { const up = parentOf(d); out.push({ dir: d, parent: up, turns: total(d), own: turns.get(d), rel: d.slice(up.length + (up.endsWith(sep) ? 0 : 1)) }); }
+  }
+  return out.map((it) => ({ ...it, parent: it.parent == null ? null : out.findIndex((x) => x.dir === it.parent) }));
+}
+
+/** the folders to remember as excluded, from the list's answer: a folder that is off under one that is on (or under
+ *  none) — what lies under an excluded folder is already covered by it */
+export function excludedFrom(tree, on) {
+  return tree.filter((it, i) => !on[i] && (it.parent == null || on[it.parent])).map((it) => it.dir);
+}
+
+/**
+ * Split a list of sessions into the ones that may be sent, how many a `.diffin-ignore` held back, and — with `hold` —
+ * the ones waiting for the person to allow their folder (`held`: the session and the folder it is in). A session is
+ * held when the folder it began in OR the one it is in now is held, as it is excluded by either.
+ */
+export async function withoutIgnored(entries, { hold = false } = {}) {
+  const kept = [], held = [];
+  let ignored = 0;
+  for (const e of entries) {
+    const f = await sessionFolders(e);
+    if (f.ignored) { ignored++; continue; }
+    const cwd = f.last ?? f.first ?? e.cwd;
+    if (hold && (heldBy(f.first) || heldBy(f.last))) { held.push({ entry: { ...e, cwd }, folder: heldBy(f.last) ? f.last : f.first }); continue; }
+    kept.push({ ...e, cwd, cwd0: f.first ?? cwd });
+  }
+  return { kept, ignored, held };
+}

package/lib/init.mjs

@@ -0,0 +1,114 @@
+// `diffin init` — put the capture skill where every agent on this machine reads
+// skills. Idempotent: an installed copy at the same or newer version is left alone,
+// an older one is replaced. For Claude Code and Codex it also puts `diffin capture` on
+// the agent's allowlist (settings.mjs): the send is the agent's own call, made without a
+// prompt, because consent was given at install and scoped by folder. Nothing else is
+// installed — the skill is the whole integration, the same for every agent.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { skillTargets } from './agents.mjs';
+import { dim, fail, out, stepDone, stepWarn } from './ui.mjs';
+import { installClaudeAllow, installCodexAllow } from './settings.mjs';
+
+const SKILL = 'capture';
+const BUNDLED = join(dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'skills', SKILL, 'SKILL.md');
+
+export function skillVersion(text) {
+  const m = String(text ?? '').match(/^\s*version:\s*"?([0-9]+(?:\.[0-9]+)*)"?\s*$/m);
+  return m ? m[1] : null;
+}
+const newer = (a, b) => { // a > b ?
+  const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) { const d = (pa[i] ?? 0) - (pb[i] ?? 0); if (d) return d > 0; }
+  return false;
+};
+
+/** what the bundled skill's version is, and what is installed for the agent we run under */
+export function installedVersion(dir) {
+  const p = join(dir, SKILL, 'SKILL.md');
+  return existsSync(p) ? skillVersion(readFileSync(p, 'utf8')) : null;
+}
+export const bundledVersion = () => skillVersion(readFileSync(BUNDLED, 'utf8'));
+
+/** the bundled skill, with a description an agent renders well: Hermes shows 60 chars */
+export function skillTextFor(agentId, text) {
+  if (agentId !== 'hermes') return text;
+  const desc = 'description: 기록해/capture, and whenever work just landed — merged, deployed, a document or request finished, a decision confirmed, the person wrapping up — records every session\'s work to diffin by running `diffin capture` alone, no confirmation. When unsure, run it — the command ends a call that comes too soon, without sending.';
+  return text.replace(/^description: .*$/m, desc);
+}
+
+export function init(argv = [], { quiet = false, skillsOnly = false, closing = true } = {}) {
+  const text = readFileSync(BUNDLED, 'utf8');
+  const version = skillVersion(text);
+  const targets = skillTargets();
+  if (!targets.length) {
+    fail('스킬을 읽는 에이전트가 이 기기에 없습니다.', 'Claude Code, Codex, Antigravity, Hermes 가운데 하나를 설치한 뒤 diffin init 을 다시 실행하세요.');
+    process.exitCode = 1; return [];
+  }
+  const results = [];
+  for (const t of targets) {
+    const dir = join(t.dir, SKILL);
+    const have = installedVersion(t.dir);
+    let action;
+    if (have && !newer(version, have)) action = have === version ? 'kept' : 'kept (newer)';
+    else { mkdirSync(dir, { recursive: true }); writeFileSync(join(dir, 'SKILL.md'), skillTextFor(t.agent.id, text)); action = have ? `updated ${have} → ${version}` : `installed ${version}`; }
+    results.push({ agent: t.agent.id, dir, action });
+    const label = action === 'kept' ? `최신 ${dim(version)}` : action === 'kept (newer)' ? `유지 ${dim(have)}` : action.startsWith('updated') ? `갱신 ${dim(`${have} → ${version}`)}` : `설치 ${dim(version)}`;
+    if (!quiet) stepDone(t.agent.name, dir.replace(process.env.DIFFIN_HOME ?? homedir(), '~'), dim(label));
+  }
+  if (skillsOnly) return results;
+  // `diffin capture` on the allowlist is what lets the agent's own call run without a
+  // permission prompt (a "no" on that prompt ends its turn).
+  if (results.some((r) => r.agent === 'cc')) {
+    const a = installClaudeAllow();
+    if (!quiet && a.installed) stepDone('Claude Code', '~/.claude/settings.json', dim('허용 목록에 diffin capture 추가'));
+    else if (!quiet && a.reason === 'unreadable') stepWarn('Claude Code', '~/.claude/settings.json', dim('읽을 수 없어 허용 항목을 넣지 않았습니다'));
+  }
+  // Codex: the same entry in its rules file — there it is also what lets the command out of the sandbox (settings.mjs)
+  if (results.some((r) => r.agent === 'codex')) {
+    const a = installCodexAllow();
+    if (!quiet && a.installed) stepDone('Codex', '~/.codex/rules/default.rules', dim('허용 목록에 diffin capture 추가'));
+    else if (!quiet && a.reason === 'unreadable') stepWarn('Codex', '~/.codex/rules/default.rules', dim('읽을 수 없어 허용 항목을 넣지 않았습니다'));
+  }
+  if (!quiet) {
+    if (results.some((r) => !['cc', 'hermes', 'codex', 'antigravity', 'agents'].includes(r.agent))) out(`    ${dim('기록은 아직 Claude Code, Codex, Antigravity, Hermes 세션만 지원합니다.')}`);
+    if (closing) {
+      out();
+      out(`    ${dim('에이전트의 다음 세션부터, 에이전트가 작업을 diffin 에 자동으로 기록합니다. 따로 할 일은 없습니다.')}`);
+      out(`    ${dim('잠시 멈추려면 diffin pause, 폴더를 빼려면 diffin exclude')}`);
+    }
+  }
+  return results;
+}
+
+/**
+ * Called by capture and backfill, so nobody has to remember `diffin init`. Three cases:
+ *
+ * An agent installed after onboarding: its skill dir has no capture yet. It gets
+ * the whole of init.
+ *
+ * A skill OLDER than the one this package carries: the package was updated and the
+ * skill was not. Nothing used to refresh it — the only notice was a dim line printed
+ * by `diffin capture`, a command the agent runs at the end of its turn, where nobody
+ * reads it — so an updated package kept instructing the agent by the old rules for
+ * good (measured 2026-10-03: the skill said an hour between captures ten hours after
+ * the server began refusing anything under five). A newer installed copy is left
+ * alone, as init leaves it.
+ *
+ * Quiet; one line per thing it touched.
+ */
+export function ensureInit() {
+  const targets = skillTargets();
+  const want = bundledVersion();
+  const missing = targets.filter((t) => !installedVersion(t.dir));
+  const stale = targets.map((t) => ({ t, have: installedVersion(t.dir) })).filter((x) => x.have && want && newer(want, x.have));
+  // Codex's rule is what lets its capture reach the server at all, so an agent that appeared later gets it here too
+  try { if (targets.some((t) => t.agent.id === 'codex') && installCodexAllow().changed) stepDone('Codex', '~/.codex/rules/default.rules', dim('허용 목록에 diffin capture 추가')); } catch { /* not worth an error */ }
+  if (!missing.length && !stale.length) return [];
+  const r = init([], { quiet: true, skillsOnly: !missing.length });
+  for (const t of missing) stepDone(t.agent.name, '새로 감지', dim('캡처 스킬 설치'));
+  for (const { t, have } of stale) stepDone(t.agent.name, `캡처 스킬 ${have} → ${want}`, dim('갱신'));
+  return r;
+}

package/lib/journey.mjs

@@ -0,0 +1,269 @@
+// The onboarding's wait as one journey: 올리기 → 읽기 → 묶기 → 완성, one track for the whole of it, a headline and a line
+// of what is happening, a character walking the track, and when it should be done. The same four stops and words as the
+// app's screen, so a person who watched one recognises the other.
+//
+// Why one track. The run used to show each server stage's own count, so the bar filled to the end and emptied again at
+// every stage (읽기 3/8, then 저장 0/8, then 묶기 0/1) and a stage that counts nothing showed no bar at all; the person
+// could see that something moved, never how far in they were. The wait is 12–20 minutes on a first run of eleven or
+// twelve days, and the moment it starts is the product's first impression.
+//
+// The stops are as long as the stages take. Measured on the run records (2026-10-07, wall time): a 554-record backfill
+// read 28% · stitch 68% · finish 3%; captures of 125, 44 and 6 records 21–26% · 68–76% · 6–9%. The upload, the one part
+// the CLI does itself, is short against them. So 10 · 22 · 60 · 8.
+//
+// Only on a terminal: a log or a pipe gets the step lines it always got (`backfill.mjs`, `watch.mjs`), one per result.
+import { accent, bold, dim, green, red } from './ui.mjs';
+
+export const WEIGHTS = { upload: 0.10, read: 0.22, stitch: 0.60, finish: 0.08 };
+const ORDER = ['upload', 'read', 'stitch', 'finish'];
+/** the stitch stage against the read stage, in wall time, and the finish against the read (the same runs as above:
+ *  stitch/read 2.4 · 2.6 · 3.3 · 4.8, finish/read 0.1 · 0.2 · 0.4 · 0.5) — what the wait still holds once reading is timed */
+export const STITCH_PER_READ = 2.7, FINISH_PER_READ = 0.3;
+
+const STOPS = {
+  upload: { name: '올리기', title: '대화를 받고 있습니다', note: '다 받으면 바로 읽기 시작합니다.', doing: '대화 받는 중', item: '📦', plain: '[]' },
+  read: { name: '읽기', title: '대화를 읽고 있습니다', note: '대화마다 무슨 일을 했는지 찾아 기록으로 남깁니다.', doing: '한 일 찾는 중', item: '👀', plain: 'oo' },
+  stitch: { name: '묶기', title: '기록을 작업으로 묶고 있습니다', note: '비슷한 기록끼리 모아 하나의 작업으로 만듭니다. 가장 오래 걸리는 단계입니다.', doing: '작업으로 묶는 중', item: '🧵', plain: '~~' },
+  finish: { name: '완성', title: '마지막으로 다듬고 있습니다', note: '작업마다 직군을 붙이고 비슷한 작업끼리 프로젝트로 나눕니다.', doing: '기록 고르는 중', item: '✨', plain: '**' },
+};
+
+/** where a server run is on the track, from the progress the worker writes on the run record (`progress.stage`) */
+export function serverPlace(view) {
+  const p = view?.progress ?? {};
+  const st = view?.status;
+  if (st === 'done' || st === 'empty' || p.stage === 'done') return { stage: 'finish', frac: 1, done: true };
+  const f = (x) => (p.total > 0 ? Math.min(1, Math.max(0, p.done / p.total)) : 0) * x;
+  switch (p.stage) {
+    case 'scan': return { stage: 'read', frac: 0.02 };
+    case 'map': return { stage: 'read', frac: 0.05 + f(0.75) };
+    case 'ship': return { stage: 'read', frac: 0.8 + f(0.2) };
+    case 'stitch': return { stage: 'stitch', frac: f(1), counted: p.total > 1 };
+    case 'domain': return { stage: 'finish', frac: 0.1 };
+    case 'relevance': return { stage: 'finish', frac: 0.45 };
+    case 'project': return { stage: 'finish', frac: 0.8 };
+    default: return { stage: 'read', frac: 0, waiting: true };
+  }
+}
+
+/** a stage measured only by time: up to 90% by the time it is expected to take, then ever slower, never full */
+export function eased(elapsed, expected) {
+  if (!(expected > 0)) return 0;
+  const x = elapsed / expected;
+  return x < 1 ? 0.9 * x : 0.9 + 0.09 * (1 - Math.exp(-(x - 1)));
+}
+
+/** the whole track's fill, 0–1, from a stage and how far into it */
+export function overall(stage, frac) {
+  let t = 0;
+  for (const s of ORDER) { if (s === stage) return t + WEIGHTS[s] * Math.min(1, Math.max(0, frac)); t += WEIGHTS[s]; }
+  return 1;
+}
+
+/** the stop and how far into it, from the track's fill — `overall` the other way round */
+export function placeOf(fill) {
+  let t = 0;
+  for (const s of ORDER) { if (fill < t + WEIGHTS[s] || s === 'finish') return { stage: s, frac: Math.min(1, Math.max(0, (fill - t) / WEIGHTS[s])) }; t += WEIGHTS[s]; }
+  return { stage: 'finish', frac: 1 };
+}
+
+/** the least a run takes on the server whatever its size: the four small runs of 2026-10-07 (4, 6, 8 records)
+ *  took 17, 20 and 25 s, nearly all of it fixed cost */
+export const RUN_FLOOR_SEC = 20;
+
+/**
+ * Where the server's half of the wait stands, from every run's place. The worker drives ONE run of a person at a
+ * time (a claim is per user, `pipeline/src/worker.ts`), so the runs are a queue, not a race: the fill is each run's
+ * own progress weighted by its size, and what is left is the run in hand plus every run still in line.
+ * Until 2026-10-07 the journey stood where the slowest run was — a queued run, at nothing, for as long as the first
+ * run took — so the track sat in 읽기 for seven minutes, the estimate read "약 47분", and then everything ran through
+ * in seconds once the queue reached the small runs.
+ *
+ * `places`: serverPlace(view) of each run, with `w` its size. `clocks[i]`: when run i was first seen at each stop
+ * (filled here). Returns { fill (0–1 of the server's part), waiting, left (seconds, or null) }.
+ */
+export function queue(places, clocks, now) {
+  const W = places.reduce((t, p) => t + (p.w ?? 1), 0) || 1;
+  let fill = 0, left = 0, known = true, spent = 0, spentW = 0;
+  const live = [];
+  places.forEach((p, i) => {
+    const c = (clocks[i] ??= {});
+    if (p.done) { if (c.read != null && c.end == null) c.end = now; } else if (!p.waiting) { c.read ??= now; c[p.stage] ??= now; }
+    let frac = p.frac;
+    if (!p.done && p.stage === 'stitch' && !p.counted && c.stitch != null) frac = Math.max(frac, eased((now - c.stitch) / 1000, Math.max(20, ((c.stitch - c.read) / 1000) * STITCH_PER_READ)));
+    const own = p.done ? 1 : p.waiting ? 0 : (overall(p.stage, frac) - WEIGHTS.upload) / (1 - WEIGHTS.upload);
+    fill += ((p.w ?? 1) / W) * own;
+    if (p.done) { if (c.read != null) { spent += (c.end - c.read) / 1000; spentW += p.w ?? 1; } return; }
+    if (p.waiting) return;
+    const r = remaining({ stage: p.stage, frac, now, clock: c });
+    if (r == null) known = false; else { left += r; spent += (now - c.read) / 1000 + r; spentW += p.w ?? 1; }
+    live.push(i);
+  });
+  // a run in line takes what the timed runs took per unit of size, never less than a run's fixed cost
+  const perW = spentW ? spent / spentW : null;
+  for (const p of places) if (!p.done && p.waiting) { if (perW == null) known = false; else left += Math.max(RUN_FLOOR_SEC, perW * (p.w ?? 1)); }
+  return { fill, waiting: !live.length && places.some((p) => !p.done), left: known ? left : null };
+}
+
+/** what is left, in seconds, or null while there is nothing to reckon from; `clock` holds when each stage began */
+export function remaining({ stage, frac, now, clock }) {
+  const readStart = clock.read, stitchStart = clock.stitch, finishStart = clock.finish;
+  if (stage === 'upload' || readStart == null) return null;
+  if (stage === 'read') {
+    const spent = (now - readStart) / 1000;
+    if (frac < 0.15 || spent < 10) return null;
+    const total = spent / frac;
+    return total * (1 - frac) + total * (STITCH_PER_READ + FINISH_PER_READ);
+  }
+  const readWall = ((stitchStart ?? now) - readStart) / 1000;
+  if (stage === 'stitch') {
+    const expected = Math.max(20, readWall * STITCH_PER_READ);
+    const spent = (now - stitchStart) / 1000;
+    return Math.max(expected - spent, expected * 0.1) + readWall * FINISH_PER_READ;
+  }
+  const spent = (now - (finishStart ?? now)) / 1000;
+  return Math.max(readWall * FINISH_PER_READ - spent, 5);
+}
+
+/** the number a person reads: it follows a falling estimate at once and a rising one only slowly */
+export function settle(shown, computed, dtSec) {
+  if (computed == null) return shown;
+  if (shown == null || computed <= shown) return computed;
+  return shown + Math.min(computed - shown, dtSec * 0.25);
+}
+export const leftText = (sec) => (sec == null ? '예상 시간 계산 중' : sec < 60 ? '곧 끝납니다' : `약 ${Math.ceil(sec / 60)}분 남음`);
+
+// terminal columns: a Hangul syllable or an emoji takes two
+const wide = (cp) => (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xfe30 && cp <= 0xfe4f) || (cp >= 0xff00 && cp <= 0xff60) || (cp >= 0x1f300 && cp <= 0x1faff) || cp === 0x2728;
+const BARE = /\x1b\[[0-9;]*m/g;
+export const cols = (s) => [...String(s).replace(BARE, '').replace(/\ufe0f/g, '')].reduce((n, ch) => n + (wide(ch.codePointAt(0)) ? 2 : 1), 0);
+const fit = (s, w) => { let out = '', n = 0; for (const ch of String(s)) { const c = wide(ch.codePointAt(0)) ? 2 : 1; if (n + c > w) break; out += ch; n += c; } return out; };
+const wrap = (s, w) => { const lines = []; let cur = ''; for (const word of String(s).split(' ')) { const next = cur ? `${cur} ${word}` : word; if (cols(next) > w && cur) { lines.push(cur); cur = word; } else cur = next; } if (cur) lines.push(cur); return lines.map((l) => fit(l, w)); };
+
+/** can this terminal draw emoji and the character's face? Not the old Windows console, not a dumb terminal */
+export function canDraw(env = process.env, platform = process.platform) {
+  if (env.DIFFIN_PLAIN || env.TERM === 'dumb') return false;
+  if (platform === 'win32' && !env.WT_SESSION && !env.TERM_PROGRAM) return false;
+  return true;
+}
+
+const FACE = { open: '(•ᴗ•)', blink: '(-ᴗ-)', happy: '(＾ᴗ＾)', out: '(×_×)' };
+const PLAIN_FACE = { open: '(o.o)', blink: '(-.-)', happy: '(^o^)', out: '(x_x)' };
+
+/**
+ * One frame of the journey, as lines. Pure — the clock, the size and the tick come in — so a test can hold it.
+ * `s`: { mode: 'run' | 'done' | 'stopped', stage, frac, sessions, elapsedSec, leftSec, waiting, result: { atoms, goals } }
+ */
+export function frame(s, { width = 80, tick = 0, emoji = true } = {}) {
+  const W = Math.max(28, Math.min(60, width - 4));
+  const face = emoji ? FACE : PLAIN_FACE;
+  const stop = STOPS[s.stage] ?? STOPS.upload;
+  const fill = s.mode === 'done' ? 1 : overall(s.stage, s.frac);
+  const lines = [];
+  const n = (x) => Number(x ?? 0).toLocaleString('ko-KR');
+
+  // the headline and what is happening
+  if (s.mode === 'done') {
+    lines.push(`${green('✓')} ${bold('정리가 끝났습니다')}`);
+    lines.push(...wrap(s.result?.atoms > 0 ? `기록 ${n(s.result.atoms)}개가 작업 ${n(s.result.goals)}개로 묶였습니다. 앞으로는 작업이 끝날 때마다 에이전트가 알아서 기록합니다.` : '새로 기록할 작업은 없었습니다. 앞으로는 작업이 끝날 때마다 에이전트가 알아서 기록합니다.', W));
+  } else if (s.mode === 'stopped') {
+    lines.push(bold('처리가 끝나지 않았습니다'));
+    lines.push(...wrap('이미 올라간 기록은 그대로 남아 있습니다. 터미널에서 아래 명령을 다시 실행하면 이어서 올라갑니다.', W));
+    lines.push('', `  ${dim('$')} npx @diffin/cli onboard`);
+  } else if (s.mode === 'later') {
+    lines.push(bold('서버가 마저 정리하고 있습니다'));
+    lines.push(...wrap('몇 분 뒤 앱에서 볼 수 있습니다. 창을 닫아도 계속됩니다.', W));
+  } else {
+    lines.push(`${bold(stop.title)}${emoji ? ` ${stop.item}` : ''}`);
+    lines.push(...wrap(stop.note, W));
+  }
+  lines.push('');
+
+  // the character above the track, where the track has reached; it carries the stage's thing and hops it now and then
+  const mood = s.mode === 'done' ? 'happy' : s.mode === 'stopped' ? 'out' : tick % 14 === 13 ? 'blink' : 'open';
+  const thing = s.mode === 'done' ? (emoji ? '🎉' : '\\o/') : s.mode === 'stopped' ? (emoji ? '💤' : 'zz') : emoji ? stop.item : stop.plain;
+  const at = Math.max(0, Math.min(W - 7, Math.round(fill * W) - 3));
+  const hop = s.mode === 'run' && Math.floor(tick / 3) % 2 === 1;
+  lines.push(' '.repeat(at + cols(face.open)) + (hop ? thing : ''));
+  lines.push(' '.repeat(at) + face[mood] + (hop ? '' : thing));
+
+  // the track: four lengths by how long each takes, a gap between, filled to where the run is
+  const gaps = ORDER.length - 1, span = W - gaps;
+  const min = 6;
+  let lens = ORDER.map((k) => Math.max(min, Math.round(WEIGHTS[k] * span)));
+  lens[2] += span - lens.reduce((a, b) => a + b, 0); // the longest stop takes the rounding
+  let filled = Math.round(fill * span), track = '', starts = [], pos = 0;
+  ORDER.forEach((k, i) => {
+    starts.push(pos);
+    const f = Math.max(0, Math.min(lens[i], filled)); filled -= lens[i];
+    track += accent('━'.repeat(f)) + dim('─'.repeat(lens[i] - f)) + (i < gaps ? ' ' : '');
+    pos += lens[i] + 1;
+  });
+  lines.push(track);
+  const here = s.mode === 'done' ? -1 : ORDER.indexOf(s.stage);
+  let labels = '', used = 0;
+  ORDER.forEach((k, i) => {
+    const name = STOPS[k].name; const pad = Math.max(0, starts[i] - used); labels += ' '.repeat(pad); used += pad;
+    labels += i === here ? bold(name) : i > here && here >= 0 ? dim(name) : name; used += cols(name);
+    if (i < gaps) { labels += ' '; used += 1; }
+  });
+  lines.push(labels, '');
+
+  // the status line: what is happening, how much, for how long, and how long still
+  // on a narrow terminal the parts go least needed first: how many conversations, then how long it has been
+  const parts = [s.sessions ? `대화 ${n(s.sessions)}개` : '', s.mode === 'done' ? `${since(s.elapsedSec)} 걸렸습니다` : s.mode === 'stopped' ? '' : `${since(s.elapsedSec)}째`, s.mode === 'run' ? leftText(s.leftSec) : ''].filter(Boolean);
+  const dot = s.mode === 'done' ? green('●') : s.mode === 'stopped' ? red('●') : accent('●');
+  const doing = s.mode === 'done' ? '정리 완료' : s.mode === 'stopped' ? '멈춤' : s.mode === 'later' ? '정리 중' : s.waiting ? '차례 기다리는 중' : stop.doing;
+  while (parts.length && cols(`● ${doing}  ${parts.join(' · ')}`) > W) parts.shift();
+  lines.push(`${dot} ${bold(doing)}  ${dim(parts.join(' · '))}`);
+  // the upload is the one part that stops with the window; the rest is the server's
+  if (s.mode === 'run' && s.stage !== 'upload') lines.push(dim('창을 닫아도 계속됩니다.'));
+  return lines.map((l) => `  ${l}`);
+}
+
+const since = (sec) => { const t = Math.max(0, Math.round(sec)); return t < 60 ? `${t}초` : `${Math.floor(t / 60)}분 ${String(t % 60).padStart(2, '0')}초`; };
+
+/**
+ * The live journey on stderr. `upload(done, total)` while files go up, `server(places)` with each run's place on every
+ * poll, then `end(mode, extra)` once — it leaves the last frame standing. `note(text)` prints a line above it (a skipped
+ * session, a failure) without tearing the drawing.
+ */
+export function journey({ sessions = 0, stream = process.stderr, emoji = canDraw() } = {}) {
+  const t0 = Date.now();
+  const clocks = [];
+  let st = { mode: 'run', stage: 'upload', frac: 0, sessions };
+  let shown = null, lastAt = t0, tick = 0, drawn = 0, ended = false, places = null, est = null;
+  const width = () => stream.columns || 80;
+  // every run's place, read again on each frame so a stitch that counts nothing still moves between polls
+  const place = (now) => {
+    const q = queue(places, clocks, now);
+    est = q.left;
+    const next = placeOf(WEIGHTS.upload + (1 - WEIGHTS.upload) * q.fill);
+    // the track never goes back: a later poll that reads a little lower holds where it was
+    st = overall(next.stage, next.frac) >= overall(st.stage, st.frac) ? { ...st, ...next, waiting: q.waiting } : { ...st, waiting: q.waiting };
+  };
+  const draw = () => {
+    const now = Date.now();
+    if (st.mode === 'run' && places) place(now);
+    if (st.mode === 'run') { shown = settle(shown != null ? Math.max(0, shown - (now - lastAt) / 1000) : null, est, (now - lastAt) / 1000); lastAt = now; }
+    const lines = frame({ ...st, elapsedSec: (now - t0) / 1000, leftSec: shown }, { width: width(), tick: tick++, emoji });
+    let buf = drawn ? `\x1b[${drawn}A` : '';
+    for (const l of lines) buf += `\r\x1b[2K${l}\n`;
+    for (let i = lines.length; i < drawn; i++) buf += '\r\x1b[2K\n';
+    if (drawn > lines.length) buf += `\x1b[${drawn - lines.length}A`;
+    stream.write(buf);
+    drawn = lines.length;
+  };
+  const show = () => stream.write('\x1b[?25h');
+  stream.write('\x1b[?25l');
+  process.once('exit', show);
+  const timer = setInterval(draw, 200);
+  timer.unref?.();
+  draw();
+  return {
+    upload(done, total) { st = { ...st, stage: 'upload', frac: total > 0 ? done / total : 0 }; },
+    /** every run's place on each poll, each with `w`, its size — the runs are a queue (`queue`) */
+    server(next) { if (!next.length) return; places = next; place(Date.now()); },
+    note(text) { if (ended) { stream.write(`${text}\n`); return; } let buf = drawn ? `\x1b[${drawn}A` : ''; for (let i = 0; i < drawn; i++) buf += '\r\x1b[2K\n'; buf += drawn ? `\x1b[${drawn}A` : ''; stream.write(buf + `${text}\n`); drawn = 0; draw(); },
+    end(mode, extra = {}) { if (ended) return; ended = true; clearInterval(timer); st = { ...st, ...extra, mode }; draw(); show(); },
+  };
+}

package/lib/login.mjs

@@ -0,0 +1,25 @@
+// `diffin login <setup-token>` — trade the 15-minute, single-use token the web page
+// showed for the real credential, and keep it at ~/.diffin/credentials.json (0600).
+// The setup token is worthless on its own: the guard refuses it for every API call,
+// and the exchange consumes it.
+import { SERVER, fetchRetry } from './net.mjs';
+import { readCreds, writeCreds } from './creds.mjs';
+import { fail, row, serverMessage } from './ui.mjs';
+import { forgetAccount } from './state.mjs';
+
+export async function login(argv = [], { quiet = false } = {}) {
+  const token = (argv.find((a) => !a.startsWith('--')) ?? '').trim();
+  if (!token) { fail('설치 토큰이 필요합니다.', 'diffin login <설치토큰> — 토큰은 앱의 연결 화면에 있습니다.'); process.exitCode = 1; return null; }
+  const res = await fetchRetry(`${SERVER}/auth/exchange`, () => ({
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ token }),
+  }));
+  if (!res.ok) {
+    fail(`로그인하지 못했습니다 — ${serverMessage(res.status, await res.text().catch(() => ''))}`, '설치 토큰은 15분 동안 한 번만 쓸 수 있습니다. 앱의 연결 화면에서 새로 받아 다시 실행하세요.');
+    process.exitCode = 1; return null;
+  }
+  const out = await res.json();
+  forgetAccount(); // when the next capture may go up was the previous account's
+  writeCreds({ ...(readCreds() ?? {}), token: out.token, email: out.email, server: SERVER, ...(out.appUrl ? { appUrl: out.appUrl } : {}) });
+  if (!quiet) row('계정', out.email);
+  return out;
+}