hop2 0.11.39 → 0.11.40

package/hop

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 const { spawn, execSync, execFile, execFileSync } = require('child_process');
+const trajectoryExtract = require('./scripts/trajectory-extract.js');
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
@@ -539,6 +540,45 @@ function enforceViewBudget() {
     } catch (e) { /* a failed sweep never blocks a publish */ }
 }
 
+// The uploads cache's housekeeping — same shape as enforceViewBudget. Runs
+// after every upload AND hourly on a timer, so the cache shrinks even on a
+// quiet day. Copies only: the phone/browser still has the original.
+function enforceUploadBudget() {
+    const root = path.join(HOME_DIR, 'uploads');
+    try {
+        const files = [];
+        const now = Date.now();
+        for (const sess of fs.readdirSync(root)) {
+            const dir = path.join(root, sess);
+            let st; try { st = fs.statSync(dir); } catch (e) { continue; }
+            if (!st.isDirectory()) continue;
+            for (const f of fs.readdirSync(dir)) {
+                const p = path.join(dir, f);
+                let fst; try { fst = fs.statSync(p); } catch (e) { continue; }
+                if (!fst.isFile()) continue;
+                if (now - fst.mtimeMs > UPLOADS_MAX_AGE_MS) {
+                    try { fs.rmSync(p); log(`[uploads] aged out ${sess}/${f}`, DIM); } catch (e) { /* next */ }
+                    continue;
+                }
+                files.push({ p, sess, f, bytes: fst.size, mtime: fst.mtimeMs });
+            }
+            // A session folder emptied by the sweep is just clutter.
+            try { if (fs.readdirSync(dir).length === 0) fs.rmdirSync(dir); } catch (e) { /* ignore */ }
+        }
+        let total = files.reduce((a, b) => a + b.bytes, 0);
+        if (total <= UPLOADS_BUDGET_BYTES) return;
+        files.sort((a, b) => a.mtime - b.mtime);
+        for (const it of files) {
+            if (total <= UPLOADS_BUDGET_BYTES) break;
+            try {
+                fs.rmSync(it.p);
+                total -= it.bytes;
+                log(`[uploads] budget: evicted ${it.sess}/${it.f} (${Math.round(it.bytes / 1024)} KB, oldest first)`, DIM);
+            } catch (e) { /* the next candidate still evicts */ }
+        }
+    } catch (e) { /* no uploads dir yet — and a failed sweep never blocks an upload */ }
+}
+
 // Does the proxied session behind a Views server row still exist? Answered
 // from the ports ledger on disk (plus the in-memory store, when this is the
 // daemon), so the CLI and the daemon agree.
@@ -645,6 +685,12 @@ const SESSION_COOKIE_NAME = 'tunnel_session';
 const LOG_DIR = path.join(HOME_DIR, 'logs');
 const SESSION_NAME_RE = /^[a-zA-Z0-9_-]+$/;
 const UPLOAD_MAX_BYTES = parsePositiveIntEnv('HOP_UPLOAD_MAX_BYTES', 100 * 1024 * 1024);
+// Uploads (photos from the phone, files dropped on the web) are transient
+// inputs — once the agent has read one it is dead weight, and nothing else
+// ever deleted them (Jian: "we need to clean cache periodically"). Two
+// limits: an AGE sweep and a SIZE budget, oldest evicted first.
+const UPLOADS_BUDGET_BYTES = parsePositiveIntEnv('HOP_UPLOADS_BUDGET_MB', 512) * 1024 * 1024;
+const UPLOADS_MAX_AGE_MS = parsePositiveIntEnv('HOP_UPLOADS_MAX_AGE_DAYS', 14) * 86400000;
 const DEFAULT_WORKSPACE_NAME = 'default';
 const HISTORY_DIR_NAME = 'history';
 const WORKSPACE_LOGS_DIR_NAME = 'logs';
@@ -914,7 +960,19 @@ function resolveDisplayNameClaim(internalName, claimed, liveIds = null) {
     if (claimed === internalName) return claimed;
     const owner = toInternalSessionName(claimed) || claimed;
     const taken = liveIds ? liveIds.has(owner) : hopSessionExists(owner);
-    return taken ? own : claimed;
+    if (!taken) return claimed;
+    // The borrower yields the name, but a minted id ("s_f131c76e88") is not
+    // a name a person can use: nine of those appeared in the wall at once
+    // when `hop restore` brought back legacy rooms whose ids were the astro
+    // names newer sessions had since been given (2026-09-04). Keep the name
+    // it was given and mark WHICH one this is — unique, stable, and no
+    // lookups, which matters because this runs inside every config read.
+    return isMintedSessionId(internalName) ? `${claimed} (${internalName.slice(2, 6)})` : own;
+}
+
+/** A machine-minted session id (see mintSessionInternalName), never a name. */
+function isMintedSessionId(internalName) {
+    return /^s_[0-9a-f]{10}$/.test(String(internalName || ''));
 }
 
 function toDisplaySessionName(internalName) {
@@ -11073,7 +11131,7 @@ happens until someone clicks it.
             req.on('data', chunk => body += chunk);
             req.on('end', async () => {
                 try {
-                    const { name, internalName } = JSON.parse(body);
+                    const { name, internalName, target } = JSON.parse(body);
                     const source = resolveSessionInternalName(name, internalName);
                     if (!source || !(hopSessionExists(source) || getEffectiveSessionConfig(source))) {
                         res.writeHead(404, { 'Content-Type': 'application/json' });
@@ -11094,27 +11152,82 @@ happens until someone clicks it.
                     const plausibleCwd = (c) => c && !/[\\/]\.claude[^\\/]*[\\/]projects([\\/]|$)/.test(String(c));
                     const cwd = [rec?.cwd, meta?.cwd, config.cwd].find(plausibleCwd) || undefined;
 
-                    let command;
-                    let kind = 'shell';
-                    if (rec) {
-                        const base = rebuildClaudeLaunch(rec.launchCmd) || 'claude';
-                        command = base + ' --resume ' + rec.sessionId + ' --fork-session';
-                        kind = 'claude';
-                    } else if (/codex/i.test(String(config.foregroundProcess || '')) ||
-                               /codex/i.test(String(getRuntimeSessionMetadata(source)?.foregroundProcess || ''))) {
-                        command = 'codex resume';
-                        kind = 'codex';
+                    // What the source is running: a claude conversation (the
+                    // hook's record), codex (by process — codex has no hook),
+                    // or a plain shell.
+                    const runsCodex = /codex/i.test(String(config.foregroundProcess || ''))
+                        || /codex/i.test(String(getRuntimeSessionMetadata(source)?.foregroundProcess || ''));
+                    const sourceKind = rec ? 'claude' : runsCodex ? 'codex' : 'shell';
+                    const wantTarget = typeof target === 'string' && target.trim() ? target.trim().toLowerCase() : null;
+                    if (wantTarget && wantTarget !== 'claude' && wantTarget !== 'codex') {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: `Unknown fork target "${wantTarget}" — claude or codex` }));
+                        return;
+                    }
+                    // Crossing tools is a HANDOFF, not a fork: neither tool can
+                    // resume the other's transcript, so the conversation is
+                    // extracted to a document the new agent reads before its
+                    // first turn (scripts/trajectory-extract.js). Same tool,
+                    // or no target, is the conversation fork as before.
+                    const handoff = !!wantTarget && wantTarget !== sourceKind;
+                    if (handoff && sourceKind === 'shell') {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'This session has no claude or codex conversation to hand off' }));
+                        return;
                     }
+                    const codexRollout = sourceKind === 'codex' ? resolveCodexTranscriptByCwd(cwd) : null;
 
                     const sourceDisplay = getSessionDisplayName(source) || source;
-                    let forkName = sourceDisplay + '-fork';
+                    const suffix = handoff ? '-' + wantTarget : '-fork';
+                    let forkName = sourceDisplay + suffix;
                     let n = 2;
                     while (isDisplayNameInUse(forkName) || hopSessionExists(toInternalSessionName(forkName))) {
-                        forkName = sourceDisplay + '-fork' + n;
+                        forkName = sourceDisplay + suffix + n;
                         n += 1;
                     }
                     const forkInternal = toInternalSessionName(forkName);
 
+                    let command;
+                    let kind = 'shell';
+                    let extract = null;
+                    const shq = (v) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+                    if (handoff) {
+                        const transcript = sourceKind === 'claude' ? resolveClaudeTranscriptPath(rec) : codexRollout;
+                        if (!transcript) {
+                            res.writeHead(404, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: `No ${sourceKind} transcript found for ${sourceDisplay} to hand off` }));
+                            return;
+                        }
+                        // Budget by what the RECEIVER can hold: Codex's context is
+                        // a fraction of Claude's, and a document it cannot finish
+                        // reading is worse than a shorter one it can.
+                        const maxChars = wantTarget === 'codex' ? 400000 : 800000;
+                        const result = await trajectoryExtract.extractConversation(transcript, { tool: sourceKind, maxChars });
+                        // Staged where uploads for the new session live: the
+                        // one per-session directory that already exists for
+                        // "a file this session is meant to read".
+                        const stage = path.join(HOME_DIR, 'uploads', forkInternal);
+                        fs.mkdirSync(stage, { recursive: true, mode: 0o700 });
+                        const stamp = new Date().toISOString().slice(0, 19).replace(/[:T]/g, '-');
+                        const extractPath = path.join(stage, `handoff-from-${sourceDisplay}-${stamp}.md`);
+                        writePrivateFile(extractPath, result.text);
+                        const bytes = Buffer.byteLength(result.text);
+                        const prompt = trajectoryExtract.handoffPrompt(extractPath, bytes, sourceKind);
+                        command = `${wantTarget} ${shq(prompt)}`;
+                        kind = 'handoff';
+                        extract = { path: extractPath, bytes, turns: result.turns, totalTurns: result.totalTurns };
+                    } else if (rec) {
+                        const base = rebuildClaudeLaunch(rec.launchCmd) || 'claude';
+                        command = base + ' --resume ' + rec.sessionId + ' --fork-session';
+                        kind = 'claude';
+                    } else if (runsCodex) {
+                        // By id when the rollout is identifiable — the picker
+                        // otherwise, which asks the user to find it.
+                        const rolloutId = codexRollout ? await trajectoryExtract.codexRolloutId(codexRollout) : null;
+                        command = rolloutId ? `codex resume ${shq(rolloutId)}` : 'codex resume';
+                        kind = 'codex';
+                    }
+
                     // The fork inherits the source's origin: forking an agent
                     // worker makes another agent worker; forking your own
                     // session makes yours.
@@ -11137,10 +11250,11 @@ happens until someone clicks it.
                         displayName: forkName,
                         cwd,
                         createdBy,
-                        forkedFrom: source
+                        forkedFrom: source,
+                        ...(handoff ? { handoffFrom: sourceKind, handoffTo: wantTarget } : {})
                     });
                     res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ ok: true, name: forkName, internalName: forkInternal, kind }));
+                    res.end(JSON.stringify({ ok: true, name: forkName, internalName: forkInternal, kind, target: handoff ? wantTarget : sourceKind, extract }));
                 } catch (e) {
                     res.writeHead(500, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ error: e?.message || 'Fork failed' }));
@@ -11386,6 +11500,7 @@ happens until someone clicks it.
                     fs.mkdirSync(dir, { recursive: true });
                     const filePath = uniqueUploadPath(dir, safeUploadFilename(parsedUrl.query.filename));
                     fs.writeFileSync(filePath, Buffer.concat(chunks), { mode: 0o600 });
+                    enforceUploadBudget();   // every upload pays its way; hourly timer covers idle days
                     log(`[upload] ${getSessionDisplayName(internalName) || internalName}: ${path.basename(filePath)} (${received} bytes)`, DIM);
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({ ok: true, path: filePath, name: path.basename(filePath), bytes: received }));
@@ -11573,6 +11688,17 @@ happens until someone clicks it.
             req.on('end', async () => {
                 try {
                     let { name, type, port, cwd, folderId, startRuntime, workspace, workspaceName, attachedTo, startup } = JSON.parse(body);
+                    // The web create form takes the directory as the user
+                    // typed it, ~ included; the host only checks that the
+                    // path exists, so an unexpanded ~ silently fell back to
+                    // home. Expand it here, once, for every caller.
+                    if (typeof cwd === 'string') {
+                        const t = cwd.trim();
+                        cwd = t === '' ? undefined
+                            : t === '~' ? os.homedir()
+                            : t.startsWith('~/') ? path.join(os.homedir(), t.slice(2))
+                            : t;
+                    }
                     // A new session can boot straight into an app instead of a
                     // bare shell: the web New picker sends startup='claude' /
                     // 'codex' (or empty for a plain terminal). Bounded, and
@@ -11901,6 +12027,40 @@ happens until someone clicks it.
         }
 
         // API: Restore saved sessions (recreate rooms + resume claude conversations)
+        if (parsedUrl.pathname === '/api/fs/complete' && req.method === 'GET') {
+            // Directory completion for the create form's working-directory
+            // field. Directories only: the last segment of `q` is a prefix
+            // (case-insensitive), everything before it must already exist. A
+            // leading ~ is the home directory and a relative path resolves
+            // under it, matching what a shell would do with the same text.
+            // Dot-directories appear only once the prefix itself starts with a
+            // dot, the way tab completion behaves.
+            const sp = parsedUrl.searchParams || new URLSearchParams(parsedUrl.search || '');
+            const q = String(sp.get('q') || '').trim();
+            const home = os.homedir();
+            const trailing = q.endsWith('/');
+            const expanded = q === '' || q === '~' ? home + '/'
+                : q.startsWith('~/') ? path.join(home, q.slice(2)) + (trailing ? '/' : '')
+                : q.startsWith('/') ? q
+                : path.join(home, q) + (trailing ? '/' : '');
+            const dir = expanded.endsWith('/') ? expanded.replace(/\/+$/, '') || '/' : path.dirname(expanded);
+            const prefix = expanded.endsWith('/') ? '' : path.basename(expanded).toLowerCase();
+            const entries = [];
+            try {
+                for (const name of fs.readdirSync(dir)) {
+                    if (!name.toLowerCase().startsWith(prefix)) continue;
+                    if (name.startsWith('.') && !prefix.startsWith('.')) continue;
+                    const full = path.join(dir, name);
+                    try { if (!fs.statSync(full).isDirectory()) continue; } catch (e) { continue; }
+                    entries.push({ name, path: full });
+                    if (entries.length >= 40) break;
+                }
+            } catch (e) { /* not a directory, or unreadable: no completions */ }
+            entries.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: 'base' }));
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ home, dir, entries }));
+            return;
+        }
         if (parsedUrl.pathname === '/api/sessions/restore/health' && req.method === 'GET') {
             const state = readRestoreReconcile();
             const sessions = Object.values(state.sessions || {});
@@ -18245,6 +18405,12 @@ async function main() {
         };
         setTimeout(runRestoreReconcile, 12000).unref?.();
         setInterval(runRestoreReconcile, 30000).unref?.();
+
+        // Uploads cache: age out + size-cap, once at boot (a daemon that sat
+        // idle for a week still cleans up) and then hourly. Cheap: one stat
+        // per file, and a no-op when the folder doesn't exist yet.
+        setTimeout(enforceUploadBudget, 20000).unref?.();
+        setInterval(enforceUploadBudget, 3600000).unref?.();
     }
 
     if (DAEMON_FLAG) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hop2",
-  "version": "0.11.39",
+  "version": "0.11.40",
   "description": "🐰 Hop into your terminal from anywhere. Secure remote shell access with 2FA via Cloudflare Tunnel. Next-gen rewrite with native terminal sharing.",
   "main": "hop",
   "bin": {

package/scripts/trajectory-extract.js

@@ -0,0 +1,234 @@
+'use strict';
+// Turn a Claude Code or Codex transcript into a readable handoff document.
+//
+// This is how a conversation crosses tools. A Claude transcript is a JSONL
+// of API messages; a Codex rollout is a JSONL of events; neither tool can
+// resume the other's. What CAN cross is the conversation itself — every user
+// turn, the assistant's reply, and a one-line summary of each action taken —
+// written as markdown the receiving agent reads before its first turn. That
+// is context sharing, not replay: tool results are not carried, and the
+// receiver starts by summarising what it read.
+//
+// Same document format as ~/Code/agent_tools/agent_migration.py --extract,
+// ported so hop needs no Python (and no TUI dependencies) to hand a session
+// off — with replies paired to the turn they answer (see readClaudeTurns).
+//
+// Streams line by line: real transcripts run to hundreds of MB.
+
+const fs = require('fs');
+const readline = require('readline');
+
+const NOISE_PREFIXES = [
+    '<task-notification>', '<turn_aborted>', '<local-command-caveat>',
+    '[Request interrupted', '<command-name>', '<system-reminder>',
+    '# AGENTS.md', '<INSTRUCTIONS>', '<local-command-stdout>',
+    'Automation:', '<subagent_notification>'
+];
+
+function summarizeToolCall(block) {
+    const name = block?.name || '?';
+    const inp = (block && typeof block.input === 'object' && block.input) || {};
+    switch (name) {
+        case 'Bash': return `[Bash] ${String(inp.command || '').slice(0, 120)}`;
+        case 'Read': return `[Read] ${inp.file_path || '?'}`;
+        case 'Edit': return `[Edit] ${inp.file_path || '?'}`;
+        case 'Write': return `[Write] ${inp.file_path || '?'}`;
+        case 'Glob': return `[Glob] ${inp.pattern || '?'}`;
+        case 'Grep': return `[Grep] ${inp.pattern || '?'}`;
+        case 'Agent': return `[Agent] ${String(inp.prompt || '?').slice(0, 80)}`;
+        default: {
+            const short = name.includes('__') ? name.split('__').pop() : name;
+            const args = Object.entries(inp).slice(0, 2).map(([k, v]) => `${k}=${String(v).slice(0, 30)}`).join(' ');
+            return `[${short}] ${args}`.slice(0, 120);
+        }
+    }
+}
+
+async function eachJsonLine(file, onEntry) {
+    const rl = readline.createInterface({ input: fs.createReadStream(file, { encoding: 'utf8' }), crlfDelay: Infinity });
+    for await (const line of rl) {
+        if (!line) continue;
+        let entry;
+        try { entry = JSON.parse(line); } catch (e) { continue; }
+        if (onEntry(entry) === false) { rl.close(); break; }
+    }
+}
+
+/**
+ * Claude Code transcript → [{ text, ts, assistant, assistantTs, tools }].
+ *
+ * A reply belongs to the user turn it answers. agent_migration.py attached
+ * each assistant message to the NEXT user turn and overwrote earlier text
+ * blocks, so a reply could land on a harness message (a <system-reminder>)
+ * and vanish with it when noise was filtered. Here every assistant text and
+ * tool call accrues to the most recent real user turn; harness messages and
+ * tool results never become turns at all.
+ */
+async function readClaudeTurns(file) {
+    const turns = [];
+    let current = null;
+    await eachJsonLine(file, (entry) => {
+        const ts = String(entry.timestamp || '');
+        if (entry.type === 'assistant') {
+            const msg = entry.message;
+            if (!msg || typeof msg !== 'object') return;
+            for (const block of Array.isArray(msg.content) ? msg.content : []) {
+                if (!block || typeof block !== 'object') continue;
+                if (block.type === 'text' && block.text) {
+                    if (current) {
+                        current.assistant = current.assistant ? `${current.assistant}\n${block.text}` : String(block.text);
+                        current.assistantTs = ts.slice(0, 19);
+                    }
+                } else if (block.type === 'tool_use') {
+                    if (current) current.tools.push(summarizeToolCall(block));
+                }
+            }
+        } else if (entry.type === 'user') {
+            const msg = entry.message;
+            const content = msg && typeof msg === 'object' ? msg.content : '';
+            let text = '';
+            if (typeof content === 'string') text = content.trim();
+            else if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block && typeof block === 'object' && block.type === 'text') { text = String(block.text || '').trim(); break; }
+                    if (typeof block === 'string') { text = block.trim(); break; }
+                }
+            }
+            if (!text || NOISE_PREFIXES.some((p) => text.startsWith(p))) return;
+            current = { text, ts: ts.slice(0, 19), assistant: '', assistantTs: '', tools: [] };
+            turns.push(current);
+        }
+    });
+    return turns;
+}
+
+/** Codex rollout → same shape (no tool summaries: rollouts do not carry them). */
+async function readCodexTurns(file) {
+    const turns = [];
+    let current = null;
+    await eachJsonLine(file, (entry) => {
+        const ts = String(entry.timestamp || '');
+        const payload = (entry.payload && typeof entry.payload === 'object') ? entry.payload : {};
+        if (entry.type === 'response_item' && payload.role === 'assistant' && payload.type === 'message') {
+            const parts = [];
+            for (const block of Array.isArray(payload.content) ? payload.content : []) {
+                if (block && typeof block === 'object' && block.type === 'output_text' && block.text) parts.push(block.text);
+            }
+            if (parts.length && current) {
+                const text = parts.join('\n');
+                current.assistant = current.assistant ? `${current.assistant}\n${text}` : text;
+                current.assistantTs = ts.slice(0, 19);
+            }
+            return;
+        }
+        let text = '';
+        if (entry.type === 'event_msg' && payload.type === 'user_message') {
+            text = String(payload.message || '').trim();
+        } else if (entry.type === 'response_item' && payload.role === 'user' && payload.type === 'message') {
+            for (const block of Array.isArray(payload.content) ? payload.content : []) {
+                if (block && typeof block === 'object' && block.type === 'input_text') { text = String(block.text || '').trim(); break; }
+            }
+        }
+        if (!text || text.length <= 3) return;
+        // Codex logs a user turn twice (event + response item); keep one.
+        if (current && current.text.slice(0, 100) === text.slice(0, 100) && current.ts === ts.slice(0, 19)) return;
+        current = { text, ts: ts.slice(0, 19), assistant: '', assistantTs: '', tools: [] };
+        turns.push(current);
+    });
+    return turns;
+}
+
+function detectTool(file) {
+    if (/[\\/]\.codex[\\/]/.test(file)) return 'codex';
+    if (/[\\/]\.gemini[\\/]/.test(file)) return 'gemini';
+    return 'claude';
+}
+
+/** The working directory the transcript was recorded in, from its first entry that says. */
+async function readTranscriptCwd(file) {
+    let cwd = 'unknown';
+    await eachJsonLine(file, (entry) => {
+        const c = entry.cwd || (entry.payload && entry.payload.cwd);
+        if (typeof c === 'string' && c) { cwd = c; return false; }
+        return true;
+    });
+    return cwd;
+}
+
+/** A Codex rollout's own session id, for `codex resume <id>`. */
+async function codexRolloutId(file) {
+    let id = null;
+    await eachJsonLine(file, (entry) => {
+        if (entry.type === 'session_meta' && entry.payload && typeof entry.payload.id === 'string') id = entry.payload.id;
+        return false;
+    });
+    return id;
+}
+
+/**
+ * Build the handoff document. Turns are taken from the END until the
+ * character budget fills — the most recent context is what the receiver
+ * needs — then harness noise is dropped.
+ */
+async function extractConversation(file, { maxChars = 800000, tool } = {}) {
+    const kind = tool || detectTool(file);
+    if (kind === 'gemini') throw new Error('Gemini transcripts are not supported for handoff');
+    const turns = kind === 'codex' ? await readCodexTurns(file) : await readClaudeTurns(file);
+    const selected = [];
+    let total = 0;
+    for (let i = turns.length - 1; i >= 0; i--) {
+        const t = turns[i];
+        const size = t.text.length + (t.assistant || '').length + (t.tools || []).reduce((n, x) => n + x.length, 0);
+        if (total + size > maxChars && selected.length) break;
+        selected.push(t);
+        total += size;
+    }
+    selected.reverse();
+    const kept = selected.filter((t) => !NOISE_PREFIXES.some((p) => t.text.trim().startsWith(p)));
+    const cwd = await readTranscriptCwd(file);
+    const lines = [
+        '# Conversation Extract',
+        `# Source tool: ${kind}`,
+        `# Source file: ${file}`,
+        `# Working directory: ${cwd}`
+    ];
+    if (turns.length) {
+        lines.push(`# First message: ${turns[0].ts || 'unknown'}`);
+        lines.push(`# Last message: ${turns[turns.length - 1].ts || 'unknown'}`);
+    }
+    lines.push(`# Turns included below: ${kept.length} (most recent, within token budget)`);
+    lines.push(`# Extracted: ${new Date().toISOString().slice(0, 19)}`);
+    lines.push('');
+    for (const t of kept) {
+        lines.push(`## User [${t.ts || ''}]`, t.text, '');
+        if (t.tools && t.tools.length) {
+            lines.push('### Actions taken:');
+            for (const x of t.tools) lines.push(`  ${x}`);
+            lines.push('');
+        }
+        if (t.assistant) lines.push('## Assistant', t.assistant, '');
+    }
+    return { text: lines.join('\n'), tool: kind, cwd, turns: kept.length, totalTurns: turns.length };
+}
+
+/** The instruction the receiving agent starts with. */
+function handoffPrompt(extractPath, bytes, sourceTool) {
+    const kb = Math.max(1, Math.round(bytes / 1024));
+    return `Read the ENTIRE file ${extractPath} (${kb}KB) from start to finish — do not stop at the first chunk. `
+        + `It contains a previous ${sourceTool} conversation. After reading all of it, summarize what we were working on and ask me what to do next.`;
+}
+
+module.exports = { extractConversation, readClaudeTurns, readCodexTurns, summarizeToolCall, detectTool, codexRolloutId, handoffPrompt };
+
+if (require.main === module) {
+    const argv = process.argv.slice(2);
+    const file = argv.find((a) => !a.startsWith('-'));
+    if (!file) {
+        console.error('Usage: node scripts/trajectory-extract.js <transcript.jsonl> [--max-chars N] [--tool claude|codex]');
+        process.exit(1);
+    }
+    const flag = (n) => { const i = argv.indexOf(n); return i >= 0 ? argv[i + 1] : undefined; };
+    extractConversation(file, { maxChars: Number(flag('--max-chars')) || undefined, tool: flag('--tool') })
+        .then((r) => process.stdout.write(r.text))
+        .catch((e) => { console.error(e.message); process.exit(1); });
+}

package/tests/trajectory-extract.unit.test.cjs

@@ -0,0 +1,72 @@
+'use strict';
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { extractConversation, codexRolloutId, handoffPrompt } = require('../scripts/trajectory-extract.js');
+
+const tmp = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hop-extract-'));
+const jsonl = (file, entries) => fs.writeFileSync(file, entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
+
+test('claude transcript: turns, tool summaries, noise dropped, most-recent-first budget', async () => {
+    const dir = tmp();
+    const file = path.join(dir, 'claude.jsonl');
+    jsonl(file, [
+        { type: 'user', timestamp: '2026-09-01T10:00:00.000Z', cwd: '/Users/me/proj', message: { role: 'user', content: 'fix the build' } },
+        { type: 'assistant', timestamp: '2026-09-01T10:00:05.000Z', message: { role: 'assistant', content: [
+            { type: 'text', text: 'Looking.' },
+            { type: 'tool_use', name: 'Bash', input: { command: 'npm test' } },
+            { type: 'tool_use', name: 'Edit', input: { file_path: '/Users/me/proj/a.ts' } }
+        ] } },
+        { type: 'user', timestamp: '2026-09-01T10:00:06.000Z', message: { role: 'user', content: [{ type: 'tool_result', content: 'ok' }] } },
+        { type: 'assistant', timestamp: '2026-09-01T10:00:09.000Z', message: { role: 'assistant', content: [{ type: 'text', text: 'Fixed a.ts.' }] } },
+        { type: 'user', timestamp: '2026-09-01T10:01:00.000Z', message: { role: 'user', content: '<system-reminder>ignore me</system-reminder>' } },
+        { type: 'user', timestamp: '2026-09-01T10:02:00.000Z', message: { role: 'user', content: [{ type: 'text', text: 'now ship it' }] } },
+        { type: 'assistant', timestamp: '2026-09-01T10:02:30.000Z', message: { role: 'assistant', content: [{ type: 'text', text: 'Shipped.' }] } }
+    ]);
+    const r = await extractConversation(file);
+    assert.equal(r.tool, 'claude');
+    assert.equal(r.cwd, '/Users/me/proj');
+    assert.equal(r.totalTurns, 2); // the tool result and the system-reminder are not turns
+    assert.equal(r.turns, 2);
+    assert.match(r.text, /^# Conversation Extract\n# Source tool: claude/);
+    assert.match(r.text, /## User \[2026-09-01T10:00:00\]\nfix the build\n/);
+    assert.match(r.text, /### Actions taken:\n {2}\[Bash\] npm test\n {2}\[Edit\] \/Users\/me\/proj\/a\.ts/);
+    // Both text blocks of the reply, in order, on the turn they answer.
+    assert.match(r.text, /## Assistant\nLooking\.\nFixed a\.ts\.\n/);
+    assert.ok(!r.text.includes('ignore me'));
+    assert.ok(r.text.indexOf('fix the build') < r.text.indexOf('now ship it'));
+    assert.match(r.text, /## Assistant\nShipped\.\n$/);
+
+    // A tight budget keeps the NEWEST turn.
+    const small = await extractConversation(file, { maxChars: 20 });
+    assert.equal(small.turns, 1);
+    assert.ok(small.text.includes('now ship it'));
+    assert.ok(!small.text.includes('fix the build'));
+});
+
+test('codex rollout: user turns deduped, assistant paired, id readable', async () => {
+    const dir = tmp();
+    const file = path.join(dir, '.codex', 'sessions', 'rollout.jsonl');
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    jsonl(file, [
+        { type: 'session_meta', timestamp: '2026-09-01T11:00:00.000Z', payload: { id: 'abc-123', cwd: '/Users/me/other' } },
+        { type: 'event_msg', timestamp: '2026-09-01T11:00:01.000Z', payload: { type: 'user_message', message: 'summarize the repo' } },
+        { type: 'response_item', timestamp: '2026-09-01T11:00:01.000Z', payload: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'summarize the repo' }] } },
+        { type: 'response_item', timestamp: '2026-09-01T11:00:20.000Z', payload: { type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'It is a CLI.' }] } },
+        { type: 'event_msg', timestamp: '2026-09-01T11:05:00.000Z', payload: { type: 'user_message', message: 'ok' } }
+    ]);
+    const r = await extractConversation(file);
+    assert.equal(r.tool, 'codex');
+    assert.equal(r.cwd, '/Users/me/other');
+    assert.equal(r.totalTurns, 1); // "ok" is too short to count; the duplicate is folded
+    assert.match(r.text, /## User \[2026-09-01T11:00:01\]\nsummarize the repo\n\n## Assistant\nIt is a CLI\./);
+    assert.equal(await codexRolloutId(file), 'abc-123');
+});
+
+test('handoff prompt names the file, its size, and the source tool', () => {
+    const p = handoffPrompt('/x/handoff.md', 5 * 1024, 'claude');
+    assert.match(p, /Read the ENTIRE file \/x\/handoff\.md \(5KB\)/);
+    assert.match(p, /previous claude conversation/);
+});