@diffin/cli 0.0.0-stage → 0.1.0

package/lib/sources/hermes.mjs

@@ -0,0 +1,170 @@
+// Hermes adapter. Same contract as Claude Code — detect / enumerate / tsOf — so
+// backfill.mjs treats it identically. The one structural difference: Hermes has no
+// session files. Sessions live in a SQLite DB (~/.hermes/state.db), so each entry's
+// rows() thunk queries the DB and yields CC-shaped rows straight from memory. Nothing
+// touches disk on the way: an unscrubbed copy of a session never sits in a temp dir.
+//
+// node:sqlite is built in (Node ≥ 22.5), so this stays dependency-free.
+import { existsSync } from 'node:fs';
+import { projectDirOf } from './project-dir.mjs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DB = join(process.env.DIFFIN_HOME ?? homedir(), '.hermes', 'state.db');
+const MIN_SCHEMA = 20; // schema is cumulative; anything at/after 20 is readable
+
+let _sqlite = null;
+function sqlite() {
+  if (_sqlite) return _sqlite;
+  // node:sqlite prints an ExperimentalWarning — our implementation detail, nothing the
+  // user can act on. It fires asynchronously, after the DB is opened, and Node's own
+  // default printer emits it, so swapping the 'warning' listener does not stop it.
+  // Intercept at the source: drop this one warning in process.emitWarning, pass all
+  // others through untouched.
+  const orig = process.emitWarning.bind(process);
+  process.emitWarning = (warning, ...rest) => {
+    const type = rest[0]?.type ?? rest[0];
+    const msg = typeof warning === 'string' ? warning : warning?.message ?? '';
+    if ((type === 'ExperimentalWarning' || warning?.name === 'ExperimentalWarning') && /SQLite/i.test(msg)) return;
+    return orig(warning, ...rest);
+  };
+  _sqlite = process.getBuiltinModule ? process.getBuiltinModule('node:sqlite') : null;
+  if (!_sqlite) throw new Error('node:sqlite unavailable (node < 22.5)');
+  return _sqlite;
+}
+
+function open() {
+  const { DatabaseSync } = sqlite();
+  return new DatabaseSync(DB, { readOnly: true });
+}
+
+export const hermes = {
+  name: 'hermes',
+
+  detect() {
+    if (!existsSync(DB)) return null;
+    let d;
+    try { d = open(); } catch { return null; }
+    try {
+      const schema = d.prepare('SELECT MAX(version) v FROM schema_version').get()?.v
+        ?? d.prepare("SELECT value FROM state_meta WHERE key='schema_version'").get()?.value ?? null;
+      if (schema == null || Number(schema) < MIN_SCHEMA) return { present: false, note: '지원 예정(스키마)' };
+      const row = d.prepare("SELECT COUNT(*) n FROM sessions WHERE source='cli' AND cwd IS NOT NULL").get();
+      return { present: (row?.n ?? 0) > 0, sessions: row?.n ?? 0 };
+    } catch { return null; }
+    finally { try { d.close(); } catch { /* closing */ } }
+  },
+
+  // List in-window sessions. mtime can't prefilter (no files), so filter on the
+  // session's last activity; the per-row cut in stream.mjs keeps only in-window turns
+  // like everywhere else. Each entry's rows() reads that one session when called.
+  enumerate({ from }) {
+    if (!existsSync(DB)) return [];
+    const fromSec = new Date(from).getTime() / 1000;
+    let d;
+    try { d = open(); } catch { return []; }
+    const out = [];
+    try {
+      const sessions = d.prepare(
+        "SELECT id, cwd, model, last_activity_at FROM sessions WHERE source='cli' AND cwd IS NOT NULL",
+      ).all();
+      for (const s of sessions) {
+        if ((s.last_activity_at ?? 0) < fromSec) continue;
+        const meta = { id: String(s.id), cwd: String(s.cwd), model: s.model };
+        out.push({
+          sid: 'hm-' + meta.id,
+          projectDir: projectDirOf(meta.cwd),
+          files: [{ path: 'main', rows: () => sessionRows(meta) }],
+          last: Number(s.last_activity_at ?? 0) * 1000,
+          cwd: meta.cwd,
+        });
+      }
+    } catch { /* read failure must not crash the whole backfill */ }
+    finally { try { d.close(); } catch { /* closing */ } }
+    return out;
+  },
+
+  tsOf(r) { return r?.timestamp ? new Date(r.timestamp).getTime() : 0; },
+
+  /**
+   * The session a capture is for: the one Hermes named in HERMES_SESSION_ID (it sets
+   * that for every terminal command), else the most recently active CLI session in
+   * this folder. Gateway sessions have no cwd and are not captured, as in backfill.
+   */
+  currentSession(cwd = process.cwd(), env = process.env) {
+    if (!existsSync(DB)) return null;
+    let d;
+    try { d = open(); } catch { return null; }
+    try {
+      const named = env.HERMES_SESSION_ID;
+      if (named) {
+        const s = d.prepare('SELECT id, cwd FROM sessions WHERE id=?').get(String(named));
+        if (s?.cwd) return { sid: 'hm-' + String(s.id), id: String(s.id), cwd: String(s.cwd), how: 'env' };
+      }
+      const s = d.prepare(
+        "SELECT id, cwd FROM sessions WHERE source='cli' AND cwd=? ORDER BY COALESCE(last_activity_at, started_at) DESC LIMIT 1",
+      ).get(String(cwd));
+      return s ? { sid: 'hm-' + String(s.id), id: String(s.id), cwd: String(s.cwd), how: 'newest' } : null;
+    } catch { return null; }
+    finally { try { d.close(); } catch { /* closing */ } }
+  },
+};
+
+// One Hermes session → CC-shaped rows: user turns and assistant turns (text + tool_use
+// blocks), each stamped with a stable hm: uuid so refs land. Compaction re-injections
+// and pure context blocks are dropped — they are not real utterances. Opens its own
+// handle so the enumerate-time connection need not stay open across the upload.
+async function* sessionRows(s) {
+  let d;
+  try { d = open(); } catch { return; }
+  let msgs;
+  try {
+    msgs = d.prepare(
+      'SELECT id, role, content, tool_calls, timestamp FROM messages WHERE session_id=? ORDER BY id',
+    ).all(s.id);
+  } catch { return; }
+  finally { try { d.close(); } catch { /* closing */ } }
+
+  const seen = new Set(); // compaction re-inserts copies — dedup on content (>16 chars)
+  for (const m of msgs) {
+    const content = String(m.content ?? '');
+    if (content.length > 16) { if (seen.has(content)) continue; seen.add(content); }
+    const ts = new Date(Number(m.timestamp) * 1000).toISOString();
+    const uuid = 'hm:' + String(m.id);
+    if (m.role === 'user') {
+      yield { type: 'user', uuid, timestamp: ts, cwd: s.cwd, message: { content } };
+    } else if (m.role === 'assistant') {
+      if (!m.tool_calls && (content.startsWith('[PRIOR CONTEXT') || content.startsWith('[CONTEXT COMPACTION'))) continue;
+      const blocks = [];
+      if (m.content) blocks.push({ type: 'text', text: content });
+      if (m.tool_calls) {
+        try {
+          for (const tc of JSON.parse(m.tool_calls)) {
+            const t = mapTool(tc);
+            if (t.name) blocks.push({ type: 'tool_use', name: t.name, input: t.input, id: String(tc.id ?? tc.call_id ?? '') });
+          }
+        } catch { /* malformed tool_calls — skip the block */ }
+      }
+      yield { type: 'assistant', uuid, timestamp: ts, message: { content: blocks, model: s.model } };
+    }
+    // role='tool' dropped — the marker is the assistant's tool_use, outputs aren't shipped
+  }
+}
+
+// Hermes tool names → the Claude Code marker names the extractor understands. A tool
+// with no CC equivalent (read_file, skill_*, browser_*) is dropped — it carries no
+// signal the did needs.
+function mapTool(tc) {
+  const fn = tc.function ?? {};
+  let args = {};
+  try { args = JSON.parse(fn.arguments ?? '{}'); } catch { /* keep {} */ }
+  switch (fn.name) {
+    case 'terminal': case 'process': return { name: 'Bash', input: { command: String(args.command ?? '') } };
+    case 'write_file': return { name: 'Write', input: { file_path: String(args.path ?? '') } };
+    case 'patch': return { name: 'Edit', input: { file_path: String(args.path ?? '') } };
+    case 'web_extract': return { name: 'WebFetch', input: { url: String((args.urls ?? [])[0] ?? '') } };
+    case 'web_search': case 'session_search': return { name: 'WebSearch', input: { query: String(args.query ?? '') } };
+    case 'delegate_task': return { name: 'Task', input: { description: String(args.goal ?? '') } };
+    default: return { name: null };
+  }
+}

package/lib/sources/index.mjs

@@ -0,0 +1,29 @@
+// The agent-source registry. backfill.mjs and capture.mjs iterate whatever registers here and never
+// branch on which source it is — another agent is one new file and one line below. Each adapter answers:
+//   name                 → the source key the server's watermark and the run use (agents.mjs `source`)
+//   detect()             → { present, sessions } | null
+//   enumerate({from})    → [{ sid, projectDir, files: [{ path, rows() }], last, cwd?, lastCwd?() }]
+//                          sessions that moved since `from`; each file's rows() is a thunk
+//                          returning an (async) iterable of Claude Code-shaped row objects —
+//                          nothing is read until the upload streams it
+//   tsOf(row)            → ms epoch of that row, the key the range cut uses
+//   currentSession(cwd, env) → { sid, cwd?, … } | null — the session a one-session capture is for
+import { claudeCode } from './claude-code.mjs';
+import { hermes } from './hermes.mjs';
+import { codex } from './codex.mjs';
+import { antigravity } from './antigravity.mjs';
+
+// Order is display order only.
+const ADAPTERS = [claudeCode, hermes, codex, antigravity];
+
+export function detectSources() {
+  return ADAPTERS.map((a) => ({ name: a.name, ...(a.detect() ?? { present: false }) }))
+    .filter((s) => s.present);
+}
+
+/** every adapter — a capture reads all of them, whichever agent asked */
+export const allAdapters = () => ADAPTERS;
+
+export function adapter(name) {
+  return ADAPTERS.find((a) => a.name === name) ?? null;
+}

package/lib/sources/project-dir.mjs

@@ -0,0 +1,13 @@
+// The name a session's files go up under, for an agent that keeps no project folder of its own (Hermes, Codex,
+// Antigravity): the folder the session began in, encoded the way ~/.claude/projects encodes one — separators and a
+// Windows drive's colon become '-'. No source prefix: run directories are already per source, and a prefix would
+// glue a word character in front of "-Users-", which is exactly what the home-path scrub rule's lookbehind refuses —
+// the username would leak.
+//
+// The server takes a name of 1–200 characters that does not start with a dot (backfill.controller.ts PROJECT_DIR)
+// and refuses the upload otherwise, so a session with no folder on record, or one under a very long path, is given a
+// name it accepts. Nothing reads the name back as a path: a record's folder comes from each row's own `cwd`.
+export function projectDirOf(cwd) {
+  const name = String(cwd ?? '').replace(/[\\/:]/g, '-').replace(/^\.+/, '').slice(0, 200);
+  return name || 'unknown';
+}

package/lib/state.mjs

@@ -0,0 +1,113 @@
+// What this machine remembers between commands (~/.diffin/state.json, 0600): whether recording is paused, and when
+// the server said the next capture may go up.
+//
+// That second fact is the whole link between the server's limit and the agent. The agent decides WHEN to record from
+// the skill alone — no hook tells it, because a hook is something one agent has and the next does not — and it cannot
+// know when the person last recorded: the capture may have gone up from another window, another folder, or a
+// conversation since cleared. So the knowledge lives HERE, not in the agent's context: `diffin capture` reads it
+// before it asks the server anything, and an early call ends on this machine in one line, with no request.
+//
+// The time is the SERVER's (`nextCaptureAt` on a completed capture, the seconds left on a refusal). This package holds
+// no gap of its own: a number copied here would be wrong the day the server's moved, until every machine updated.
+import { randomBytes } from 'node:crypto';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const HOME = () => process.env.DIFFIN_HOME ?? homedir();
+const STATE = () => join(HOME(), '.diffin', 'state.json');
+
+export function readState() {
+  try { return JSON.parse(readFileSync(STATE(), 'utf8')); } catch { return {}; }
+}
+export function writeState(s) {
+  try { mkdirSync(join(HOME(), '.diffin'), { recursive: true, mode: 0o700 }); writeFileSync(STATE(), JSON.stringify(s, null, 2) + '\n', { mode: 0o600 }); } catch { /* remembering is not worth an error */ }
+}
+
+/**
+ * `diffin pause` … `diffin resume`: off the record. A pause has no end time — it lasts until the person turns
+ * recording back on — and what was said in between is not sent, then or later: the stretches are kept here
+ * (`pauses`) and every row stamped inside one is dropped as transcripts are read (stream.mjs).
+ *
+ * It used to be a timer on the upload ("2h") and nothing more: the conversation of a paused stretch sat in the
+ * transcript and went up with the first capture after it, which is the opposite of what a person who says
+ * "don't record this" expects.
+ */
+export function pause(at = new Date()) {
+  const s = readState();
+  if (!s.pausedSince) s.pausedSince = new Date(at).toISOString();
+  writeState(s);
+  return new Date(s.pausedSince);
+}
+export function resume(at = new Date()) {
+  const s = readState();
+  if (!s.pausedSince) return null;
+  const from = s.pausedSince;
+  s.pauses = [...(Array.isArray(s.pauses) ? s.pauses : []), { from, to: new Date(at).toISOString() }];
+  delete s.pausedSince;
+  writeState(s);
+  return new Date(from);
+}
+export function pausedSince() {
+  const u = readState().pausedSince; return u ? new Date(u) : null;
+}
+/** whether a moment falls in a stretch the person had recording off — one that ended, or the one still open */
+export function offTheRecord() {
+  const s = readState();
+  const spans = (Array.isArray(s.pauses) ? s.pauses : []).map((p) => [Date.parse(p.from), Date.parse(p.to)]).filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b));
+  const open = s.pausedSince ? Date.parse(s.pausedSince) : NaN;
+  if (!spans.length && !Number.isFinite(open)) return null;
+  return (ms) => Number.isFinite(ms) && ms > 0 && ((Number.isFinite(open) && ms >= open) || spans.some(([a, b]) => ms >= a && ms < b));
+}
+
+/** what the server said: the next capture may go up at `at` (null forgets it — another account, or the server's word changed) */
+export function setNextCapture(at) {
+  const s = readState();
+  const t = at ? new Date(at).getTime() : NaN;
+  if (Number.isFinite(t)) s.nextCaptureAt = new Date(t).toISOString(); else delete s.nextCaptureAt;
+  writeState(s);
+}
+/** the time before which a capture would be refused, or null when one may go up now as far as this machine knows */
+export function nextCaptureAt(now = Date.now()) {
+  const u = readState().nextCaptureAt; if (!u) return null;
+  const t = Date.parse(u); return t > now ? new Date(t) : null;
+}
+/** a capture went up from this machine — what `diffin status` shows */
+export function markSent(at = new Date()) {
+  const s = readState(); s.lastCaptureAt = new Date(at).toISOString(); writeState(s);
+}
+/** a different account is signing in or this one is leaving: what was remembered was about someone else */
+/**
+ * This computer's own id for diffin: random, made the first time it is asked for, kept in state.json. It is not a
+ * hardware id and says nothing about the machine; it only lets the server tell two of the person's computers apart —
+ * a backfill is once per source on EACH device, and an open run is handed back only to the device that opened it.
+ * It outlives a change of account (`forgetAccount` keeps it): it names the computer, not the person.
+ */
+export function deviceId() {
+  const s = readState();
+  if (typeof s.device === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(s.device)) return s.device;
+  s.device = `d-${randomBytes(12).toString('hex')}`;
+  writeState(s);
+  return s.device;
+}
+
+/** whether this computer was ever asked which folders not to record — a backfill's list, or the one a later connect shows */
+export const foldersAsked = () => readState().foldersAsked === true;
+export function markFoldersAsked() { const s = readState(); s.foldersAsked = true; writeState(s); }
+
+export function forgetAccount() {
+  const s = readState(); delete s.nextCaptureAt; delete s.lastCaptureAt; delete s.sessions; writeState(s);
+}
+
+/**
+ * Can this process write where diffin keeps what it remembers? Under Codex it is the one thing that tells a command
+ * its rules allow from one they do not: a command Codex runs sits in a sandbox that refuses a write outside the
+ * workspace and has no network, and an allowed one has both (measured 2026-10-04 with a probe: `write: ok` and
+ * `net: 200` against `Operation not permitted` and no network). Codex's environment variables do NOT tell — the first
+ * cut read `CODEX_SANDBOX*` as "inside", on a list of variables that turned out to be the last three lines of a
+ * longer one, and refused a capture on a guess.
+ */
+export function canWriteState() {
+  const p = join(HOME(), '.diffin', `.probe-${process.pid}`);
+  try { mkdirSync(join(HOME(), '.diffin'), { recursive: true, mode: 0o700 }); writeFileSync(p, ''); rmSync(p, { force: true }); return true; } catch { return false; }
+}

package/lib/status.mjs

@@ -0,0 +1,71 @@
+// `diffin status` — what this machine is set up to do, read from this machine alone:
+// which version, which account and server, which agents carry the skill,
+// whether recording is paused, and when the next capture may go up. No request is made:
+// status is what a person runs when something is wrong, which is when the network may be
+// what is wrong. So it says "로그인됨" about the credential it holds, not about what the
+// server would answer — a capture is what finds out.
+//
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SERVER } from './net.mjs';
+import { readCreds } from './creds.mjs';
+import { agentMatrix } from './agents.mjs';
+import { excludedFolders, excludeFolders, ignoreFileFor, ignoredBy, includeFolder } from './ignore.mjs';
+import { posixPath, scrub } from './scrub.mjs';
+import { resolve as resolvePath } from 'node:path';
+import { bundledVersion, installedVersion } from './init.mjs';
+import { nextCaptureAt, pausedSince, readState } from './state.mjs';
+import { banner, dim, ok, out, stepDone, stepInfo, stepSkip, stepWarn, when } from './ui.mjs';
+
+
+/** the package's own version, from the package.json that ships beside the code */
+export function version() {
+  try { return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8')).version ?? '?'; } catch { return '?'; }
+}
+
+export function status() {
+  banner(version());
+  const c = readCreds();
+  if (!c?.token) stepWarn('계정', '연결되지 않음', dim('앱의 연결 화면에 있는 명령을 실행하세요'));
+  else stepDone('계정', c.email ?? '(이메일 없음)', dim(process.env.DIFFIN_TOKEN ? '환경 변수의 토큰' : '연결됨'));
+  const want = bundledVersion();
+  for (const m of agentMatrix()) {
+    if (!m.present) continue;
+    const have = installedVersion(m.skillDir);
+    if (!have) stepWarn(m.agent.name, '캡처 스킬 없음', dim('diffin init 으로 설치합니다'));
+    else if (!m.agent.capture) stepSkip(m.agent.name, `캡처 스킬 ${have}`, dim('이 에이전트의 기록은 아직 지원하지 않습니다'));
+    else if (have !== want) stepDone(m.agent.name, `캡처 스킬 ${have} → ${want}`, dim('다음 기록 때 자동 갱신'));
+    else stepDone(m.agent.name, `캡처 스킬 ${have}`);
+  }
+  const st = readState();
+  const paused = pausedSince();
+  if (paused) stepWarn('자동 기록', `일시정지 중 — ${when(paused)} 부터`, dim('다시 켜려면 diffin resume'));
+  else stepDone('자동 기록', '켜짐', dim('멈추려면 diffin pause'));
+  const next = nextCaptureAt();
+  if (next) stepSkip('다음 기록', `${when(next)} 이후`, dim('그 전의 작업도 그때 함께 올라갑니다'));
+  const excl = ignoredBy(process.cwd());
+  if (excl) stepWarn('이 폴더', '기록하지 않음', dim(ignoreFileFor(process.cwd()) ? '.diffin-ignore 파일이 있습니다' : '제외한 폴더입니다 · 되돌리려면 diffin include'));
+  // facts with no verdict, under the ones that have one
+  const off = excludedFolders();
+  if (st.lastCaptureAt || off.length) out();
+  if (st.lastCaptureAt) stepInfo('마지막 기록', when(st.lastCaptureAt));
+  off.forEach((f, k) => stepInfo(k ? '' : '제외한 폴더', posixPath(scrub(f)), k ? '' : dim('되돌리려면 diffin include <폴더>')));
+  out();
+  stepInfo('서버', dim(SERVER));
+}
+
+/** `diffin exclude [폴더]` — this folder and everything under it is not recorded; `diffin include [폴더]` undoes it */
+export function exclude(argv = []) {
+  const dir = resolvePath(argv[0] ?? process.cwd());
+  excludeFolders([dir]);
+  ok(`${posixPath(scrub(dir))} 와 그 아래 폴더는 기록하지 않습니다.`);
+  out(dim('    이미 올라간 기록은 앱에서 지울 수 있습니다. 되돌리려면 diffin include'));
+}
+export function include(argv = []) {
+  const dir = resolvePath(argv[0] ?? process.cwd());
+  const file = ignoreFileFor(dir);
+  if (includeFolder(dir)) ok(`${posixPath(scrub(dir))} 를 다시 기록합니다.`);
+  else if (!file) out(`  ${dim('○')} 제외한 폴더가 아닙니다.`);
+  if (file) out(dim(`    ${posixPath(scrub(file))} 에 .diffin-ignore 파일이 있어 계속 제외됩니다. 그 파일을 지우면 기록합니다.`));
+}

package/lib/stream.mjs

@@ -0,0 +1,67 @@
+// One pass over a session's rows: cut to the window and scrub, holding only a small
+// tail buffer. The predecessor read the whole file and parsed every row into an array
+// — measured 1.7GB resident on a 336MB session, which would OOM the modest laptop this
+// runs on. Here memory is flat regardless of session size.
+//
+// Takes rows, not a path: an adapter that has files streams them with readline; one
+// that has a database yields rows straight from its query. Nothing is written to disk
+// on the way — so no unscrubbed copy of a session ever sits in a temp directory.
+import { cleanRow, queuedTurn } from './scrub.mjs';
+import { ignoredBy } from './ignore.mjs';
+import { offTheRecord } from './state.mjs';
+
+const TAIL = 8;
+const TAIL_CHARS = 300;
+
+// tsOf(row)→ms decides the cut. Rows at/after `from` and before `to` are kept; rows
+// before `from` feed the context lead-in; rows at/after `to` are simply dropped (an
+// --extend run's upper bound is where existing coverage begins). from=0 keeps all.
+export async function* streamCutScrub(rows, { tsOf, fromMs = 0, toMs = Infinity }) {
+  const tail = [];
+  let started = false, hidden = false;
+  const off = offTheRecord(); // the stretches the person had recording paused
+
+  for await (const row of rows) {
+    // A row made in a folder the person excluded does not leave the machine — whichever session it sits in, and not as
+    // the [PRIOR CONTEXT] lead-in either. Every row says where it was made, so the exclusion is exact: a session that
+    // passed through an excluded folder loses those turns and keeps the rest.
+    if (row?.cwd && ignoredBy(String(row.cwd))) continue;
+    const t = tsOf(row);
+    // …and a row from a paused stretch does not either: paused means off the record, not sent later. A row with no
+    // time goes with the row before it, as it does at the window's edge.
+    if (off) { if (t) hidden = off(t); if (hidden) continue; }
+    if (t && t >= toMs) continue;
+    const inWindow = fromMs === 0 || (t ? t >= fromMs : started);
+    if (!inWindow) {
+      tail.push(queuedTurn(row) ?? row); // a message typed mid-turn is part of the run-up too
+      if (tail.length > TAIL) tail.shift();
+      continue;
+    }
+    if (!started) {
+      started = true;
+      const ctx = contextRow(tail, row);
+      if (ctx) { const c = cleanRow(ctx); if (c != null) yield c; }
+    }
+    const c = cleanRow(row);
+    if (c != null) yield c;
+  }
+}
+
+// The [PRIOR CONTEXT] lead-in: the dropped tail as plain text with NO id, so MAP has
+// the run-up without those turns being referenceable (a ref would double-own).
+function contextRow(tail, firstKept) {
+  if (!tail.length) return null;
+  const text = tail.map((r) => {
+    const c = r?.message?.content;
+    const s = typeof c === 'string'
+      ? c
+      : Array.isArray(c) ? c.filter((b) => b?.type === 'text').map((b) => b.text).join(' ') : '';
+    return s ? `${r.type === 'user' ? 'user' : 'ai'}: ${s.slice(0, TAIL_CHARS)}` : null;
+  }).filter(Boolean).join('\n');
+  if (!text) return null;
+  return {
+    type: 'assistant',
+    timestamp: firstKept?.timestamp,
+    message: { content: [{ type: 'text', text: `[PRIOR CONTEXT — reference only; not new messages]\n${text}` }] },
+  };
+}