@phnx-labs/agents-cli 1.22.57 → 1.22.59

package/dist/lib/session/db.js

@@ -15,8 +15,8 @@ import { getSessionsDir, getSessionsDbPath } from '../state.js';
 import { query as queryEvents, queryToolUsageForSessions } from '../feed/events.js';
 import { machineForSessionFile } from '../origin-machine.js';
 import { loadSessionActorIndex, readSessionActorRecord } from './actor-sidecar.js';
-import { toolCallsFromEvents } from './tool-calls.js';
-import { persistToolCalls, toolEvidenceSourcePath } from './tool-store.js';
+import { scanEventToolCalls } from './tool-calls.js';
+import { persistToolCalls, planEventToolResume, toolEvidenceSourcePath } from './tool-store.js';
 import { buildClaudeAccountIndex, resolveClaudeAccount } from './claude-accounts.js';
 import { extractBackgroundShells, extractSkills, extractSlashCommands, harnessTracksBackgroundShells, isSubAgentTool, } from './highlights.js';
 import { resolveResource } from '../resources.js';
@@ -27,7 +27,7 @@ const DB_PATH = getSessionsDbPath();
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export const SCHEMA_VERSION = 42;
+export const SCHEMA_VERSION = 44;
 /**
  * Bump to force the content extractor (assistant-answer text, alongside the
  * user-prompt text every harness already accumulates) to re-derive on every
@@ -207,6 +207,11 @@ CREATE TABLE IF NOT EXISTS tool_calls (
   ordinal INTEGER NOT NULL,
   source_call_id TEXT,
   timestamp TEXT NOT NULL,
+  -- When the call's RESULT record arrived (its own end time). end_timestamp
+  -- minus timestamp is the call's own blocking duration, which the traces
+  -- insight engine attributes as a failed call's wasted time (PHNX-3437). NULL
+  -- for a call that never produced a result and for rows an older extractor stored.
+  end_timestamp TEXT,
   tool TEXT NOT NULL,
   input TEXT NOT NULL,
   outcome TEXT NOT NULL,
@@ -352,6 +357,26 @@ CREATE TABLE IF NOT EXISTS session_topics (
   topic_json TEXT NOT NULL
 );
 
+-- Derived failure phenotype for traces sync (PHNX-3327). Like session_topics /
+-- session_insights, this is a lazy, stamp-validated cache keyed on
+-- (file_mtime_ms, file_size) and intentionally independent of SCHEMA_VERSION.
+-- Classifying a phenotype needs the full derived SessionTrajectory (ordered
+-- steps, gaps), which buildIndexShard does NOT have from flat tool_calls rows —
+-- so it is computed per-session ONCE (parse -> trajectory -> classify) and cached
+-- here, then read for the WHOLE corpus on every sync. That is what lets the
+-- phenotype grouping dimension fold two identically-signatured sessions into one
+-- cluster regardless of which incremental batch each was first synced in, without
+-- re-parsing transcripts at 10k+ session scale. phenotype_json holds
+-- { phenotype: FailurePhenotype | null } (null = no failure phenotype matched).
+CREATE TABLE IF NOT EXISTS session_phenotypes (
+  session_id TEXT PRIMARY KEY,
+  file_mtime_ms INTEGER,
+  file_size INTEGER,
+  extractor_version INTEGER NOT NULL,
+  computed_at INTEGER NOT NULL,
+  phenotype_json TEXT NOT NULL
+);
+
 -- Normalized data behind sessions preview. Like session_insights this is a
 -- lazy, stamp-validated cache: opening one session parses only that transcript,
 -- while subsequent processes reuse the derived preview until its bytes change.
@@ -437,7 +462,12 @@ CREATE INDEX IF NOT EXISTS idx_computer_sessions_started ON computer_sessions(st
 export const INSIGHTS_EXTRACTOR_VERSION = 7;
 /** Bump when classifyTopic's output changes so cached topics recompute (human task taxonomy v2). */
 export const SESSION_TOPIC_EXTRACTOR_VERSION = 2;
-const PREVIEW_EXTRACTOR_VERSION = 1;
+// Bumped to 2 (PHNX-2973): the digest now carries `changedFiles` (per-file
+// paths). Bumping invalidates v1 cache rows so a fresh recompute populates the
+// new field instead of serving a stale digest that predates it.
+const PREVIEW_EXTRACTOR_VERSION = 2;
+/** Bump when classifyPhenotype's output changes so cached phenotypes recompute (PHNX-3327 v1). */
+export const SESSION_PHENOTYPE_EXTRACTOR_VERSION = 1;
 let dbInstance = null;
 /**
  * Apply schema migrations from `fromVersion` → SCHEMA_VERSION. The new
@@ -1152,6 +1182,55 @@ function migrateSchema(db, fromVersion) {
         // Claude/Codex resumable continuation) stay intact for rows that don't
         // need a full reparse for any OTHER reason.
     }
+    if (fromVersion < 43) {
+        // v42 -> v43: persist a per-tool-call END timestamp (PHNX-3437). The traces
+        // insight engine could only book a failed call's wasted time from the
+        // bounded gap to the NEXT call — so a call that BLOCKED for minutes and was
+        // the last in its session (or was followed quickly by an unrelated call)
+        // registered as ~0 waste. The call's result record already carried its own
+        // timestamp at ingestion; this column persists it so `end_timestamp -
+        // timestamp` (the call's own blocking duration) becomes the primary
+        // attribution, with the gap heuristic kept as the fallback for NULL rows.
+        //
+        // Additive, nullable column — no ledger flush (the v33->v34 contract that
+        // adding a column keeps warm session ledgers warm). Pre-upgrade rows stay
+        // NULL until re-indexed, and `insights.ts` degrades a NULL end back to the
+        // bounded-gap behavior, so nothing crashes or yields NaN. The paired
+        // TOOL_INDEX_VERSION bump (7 -> 8) is what re-derives it on a re-index; the
+        // tool index is deliberately independent of SCHEMA_VERSION and is never
+        // force-rescanned by a migration (only by the explicit tool backfill or a
+        // normal incremental append), so a bare ALTER here would otherwise leave
+        // existing rows dark forever.
+        const cols = new Set(db.prepare(`PRAGMA table_info(tool_calls)`).all().map((c) => c.name));
+        if (!cols.has('end_timestamp'))
+            db.exec(`ALTER TABLE tool_calls ADD COLUMN end_timestamp TEXT`);
+    }
+    if (fromVersion < 44) {
+        // v43 -> v44: backfill duration_ms for sessions whose harness scan extractor
+        // never derived it (PHNX-3457). rush/grok/kimi/cursor/muse/antigravity/hermes/
+        // openclaw left duration_ms NULL — 52% of the corpus, 100% of rush — so the
+        // console median was computed over only the ~48% that carried it, skewing it
+        // short. Going forward resolveDurationMs() populates it at every upsert; this
+        // repairs already-indexed rows in place from the timestamps they already store
+        // (last_activity, itself resolved from the last-message time else file mtime,
+        // minus the creation timestamp), so no transcript is re-parsed. julianday is
+        // avoided because it does not accept a trailing 'Z'; the arithmetic is done in
+        // JS with the exact Date.parse resolveDurationMs uses, keeping the backfill and
+        // the live path consistent. Only rows with a positive span are touched; a NULL
+        // that cannot be resolved stays NULL rather than becoming a fabricated 0.
+        const nullDurationRows = db.prepare(`SELECT id, timestamp, last_activity FROM sessions
+       WHERE duration_ms IS NULL AND last_activity IS NOT NULL`).all();
+        // Runs inside migrateSchema's own transaction (db.ts:1468), so no nested
+        // db.transaction() here — that would raise "transaction within a transaction".
+        const update = db.prepare(`UPDATE sessions SET duration_ms = ? WHERE id = ?`);
+        for (const row of nullDurationRows) {
+            const startMs = Date.parse(row.timestamp);
+            const lastMs = Date.parse(row.last_activity);
+            if (Number.isFinite(startMs) && Number.isFinite(lastMs) && lastMs > startMs) {
+                update.run(lastMs - startMs, row.id);
+            }
+        }
+    }
 }
 /**
  * Stamp `account_key` / `account_org` / `account` on every Claude row from its
@@ -2022,7 +2101,7 @@ export function upsertSession(meta, content, scan, assistantContent = '') {
         cache_write_tokens: meta.cacheWriteTokens ?? null,
         cost_usd: meta.costUsd ?? null,
         cost_usd_nocache: meta.costUsdNoCache ?? null,
-        duration_ms: meta.durationMs ?? null,
+        duration_ms: resolveDurationMs(meta, scan),
         model: meta.model ?? null,
         tool_call_count: meta.toolCallCount ?? null,
         file_path: meta.filePath,
@@ -2110,6 +2189,23 @@ export function upsertSessionsBatch(entries) {
                 ? { ...entry, meta: { ...entry.meta, ...fanOutCounts(entry.events, entry.meta.agent) } }
                 : entry;
         }
+        // Harnesses whose scanners produce no events AND whose parseSession reads a
+        // potentially large flat transcript file (not a compact SQLite DB). Calling
+        // parseSession on the warm tick for an active large session wedges the Node
+        // event loop for seconds, making browser IPC miss its connection window
+        // (PHNX-3411). Defer their tool-call indexing to runDeferredToolIndex, which
+        // uses ensureToolIndex with tool_scan_ledger stamps and byte/file budget caps.
+        // NOT opencode — parseOpenCode issues a targeted SQLite query, so it is fast
+        // even for large sessions and its results populate recentDirectoriesTouched.
+        const LARGE_TRANSCRIPT_AGENTS = new Set(['kimi', 'grok']);
+        if (!entry.events && LARGE_TRANSCRIPT_AGENTS.has(entry.meta.agent)) {
+            return entry;
+        }
+        // Enrich the entry. When the scanner already provided events, use them
+        // directly (no transcript re-read). When it didn't — e.g. OpenCode whose
+        // scanner produces only metadata but whose parseOpenCode is a fast SQLite
+        // query — fall back to parseSession. Agents that would call an expensive
+        // flat-file parse already returned above.
         try {
             const toolSourcePath = toolEvidenceSourcePath(entry.meta.filePath, entry.meta.agent);
             const toolScan = toolSourcePath === entry.meta.filePath
@@ -2118,11 +2214,23 @@ export function upsertSessionsBatch(entries) {
                     const stat = fs.statSync(toolSourcePath);
                     return { fileMtimeMs: stat.mtimeMs, fileSize: stat.size };
                 })();
-            // Some non-resumable scanners already normalized the transcript while
-            // deriving metadata. Reuse those events; scanners that only read summary
-            // metadata fall back to exactly one normalized parse here.
             const events = entry.events ?? parseSession(entry.meta.filePath, entry.meta.agent);
             writeResourceUsage(entry.meta.id, events, entry.meta.cwd);
+            // Resume the tool index from the last scan of this append-only stream when
+            // it is safe to (PHNX-3411). A live session's transcript grows every tick,
+            // so a full re-derive re-sanitizes its ENTIRE tool history each time — the
+            // synchronous O(session) work that wedged the daemon event loop for the
+            // 11 non-streaming harnesses. `planEventToolResume` returns the prior
+            // snapshot only when the file is still an append of what was scanned
+            // before; otherwise `prior` is null and this is a full replace from
+            // event 0 (identical index, just re-derived).
+            // No tool stamp (a scanner that carried no scan record) means the resume
+            // point cannot be size-guarded, so full-scan rather than trust a stale
+            // offset. persistToolCalls below also skips a resume-less write.
+            const prior = toolScan
+                ? planEventToolResume(db, entry.meta.id, toolSourcePath, toolScan, events.length)
+                : null;
+            const scanned = scanEventToolCalls(events, prior ?? undefined);
             return {
                 ...entry,
                 meta: {
@@ -2131,11 +2239,14 @@ export function upsertSessionsBatch(entries) {
                     recentDirectoriesTouched: extractRecentDirectoriesTouched(events, entry.meta.cwd),
                     ...fanOutCounts(events, entry.meta.agent),
                 },
-                toolCalls: toolCallsFromEvents(events),
+                // The CHANGED calls only. On a resume these are the newly appended tail
+                // (append-safe upsert); on a full scan they are the whole history.
+                toolCalls: scanned.calls,
                 toolScan,
-                // These are complete event arrays, not an appended tail. Append would
-                // duplicate existing evidence even when persistToolCalls supports it.
-                toolIndexMode: 'replace',
+                toolIndexMode: (prior ? 'append' : 'replace'),
+                // Persist where the NEXT scan resumes: the collector snapshot + how many
+                // events this scan folded.
+                toolResume: { parserState: JSON.stringify(scanned.snapshot), parsedOffset: scanned.eventCount },
             };
         }
         catch {
@@ -2231,7 +2342,7 @@ export function upsertSessionsBatch(entries) {
                     cache_write_tokens: meta.cacheWriteTokens ?? null,
                     cost_usd: meta.costUsd ?? null,
                     cost_usd_nocache: meta.costUsdNoCache ?? null,
-                    duration_ms: meta.durationMs ?? null,
+                    duration_ms: resolveDurationMs(meta, scan),
                     model: meta.model ?? null,
                     tool_call_count: meta.toolCallCount ?? null,
                     file_path: meta.filePath,
@@ -2284,7 +2395,13 @@ export function upsertSessionsBatch(entries) {
         if (!toolScan || !entry.toolCalls)
             continue;
         try {
-            persistToolCalls(db, entry.meta, entry.toolCalls, toolScan, { mode: entry.toolIndexMode ?? 'replace' });
+            // `resume` is set only by the full-file harness path above; claude/codex
+            // pass none, so their tool ledger keeps carrying no event-offset resume
+            // point (their resume rides the content-scan ledger instead) — unchanged.
+            persistToolCalls(db, entry.meta, entry.toolCalls, toolScan, {
+                mode: entry.toolIndexMode ?? 'replace',
+                resume: entry.toolResume,
+            });
         }
         catch {
             // Boundary is intentionally retryable via tool_scan_ledger.
@@ -2522,6 +2639,36 @@ function resolveLastActivity(meta, scan) {
         return new Date(scan.fileMtimeMs).toISOString();
     return meta.timestamp;
 }
+/**
+ * The persisted wall-clock span for a session (PHNX-3457).
+ *
+ * `durationMs` is canonically `lastTs − firstTs`. Some harness scan extractors
+ * derive it themselves from per-event timestamps (claude/codex/droid/gemini/
+ * opencode set `meta.durationMs`); the rest (rush/grok/kimi/cursor/muse/
+ * antigravity/hermes/openclaw) never did, so `duration_ms` landed NULL for them —
+ * 52% of the corpus, including 100% of the dominant `rush` usage — and the
+ * console median was computed over only the ~48% that happened to carry it,
+ * skewing it short and misleading.
+ *
+ * This closes the gap at the single write boundary every harness funnels
+ * through, so parity is automatic rather than per-extractor: when the extractor
+ * already computed a precise span, keep it; otherwise derive it from the same
+ * `timestamp` (creation) and `resolveLastActivity` (last event, itself resolved
+ * from the harness's last-message time, else file mtime) that the row already
+ * stores. Returns null only when no positive span can be established (a single
+ * timestamped event, or a clock that runs backwards), which reads as NULL rather
+ * than a fabricated 0.
+ */
+function resolveDurationMs(meta, scan) {
+    if (meta.durationMs != null)
+        return meta.durationMs;
+    const startMs = Date.parse(meta.timestamp);
+    const lastMs = Date.parse(resolveLastActivity(meta, scan));
+    if (Number.isFinite(startMs) && Number.isFinite(lastMs) && lastMs > startMs) {
+        return lastMs - startMs;
+    }
+    return null;
+}
 export function isSessionActivityFresh(row, maxAgeMs, nowMs) {
     const parsedActivityMs = Date.parse(row.last_activity ?? row.timestamp);
     const activityMs = Number.isFinite(parsedActivityMs) ? parsedActivityMs : row.file_mtime_ms ?? undefined;
@@ -2815,6 +2962,26 @@ export function querySessions(options = {}) {
     const trimmed = options.limit ? live.slice(0, options.limit) : live;
     return trimmed.map(rowToMeta);
 }
+/**
+ * Cheap query for the daemon's deferred tool-index pass (PHNX-3411).
+ *
+ * Returns the most-recently-active sessions whose parseSession reads a large
+ * flat transcript (kimi: wire.jsonl, grok: chat_history.jsonl). Their scanners
+ * produce no events, so upsertSessionsBatch skips them in the warm tick to
+ * avoid wedging the event loop. ensureToolIndex uses tool_scan_ledger stamps
+ * to skip already-current rows and applies byte/file budget caps.
+ */
+export function querySessionsForDeferredToolIndex(limit) {
+    const db = getDB();
+    const rows = db.prepare(`
+    SELECT * FROM sessions
+    WHERE file_path IS NOT NULL
+      AND agent IN ('kimi', 'grok')
+    ORDER BY last_activity DESC, timestamp DESC
+    LIMIT ?
+  `).all(limit);
+    return rows.map(rowToMeta);
+}
 /** Count sessions matching the given filter options. */
 export function countSessions(options = {}) {
     const db = getDB();
@@ -2950,6 +3117,59 @@ export function writeSessionTopics(entries) {
         }
     })();
 }
+/** Read cached failure phenotypes only when their transcript byte stamps still match. */
+export function readSessionPhenotypes(ids) {
+    const db = getDB();
+    const out = new Map();
+    if (ids.length === 0)
+        return out;
+    const CHUNK = 400;
+    for (let i = 0; i < ids.length; i += CHUNK) {
+        const chunk = ids.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => '?').join(',');
+        const rows = db.prepare(`
+      SELECT sp.session_id AS id, sp.phenotype_json AS phenotypeJson
+      FROM session_phenotypes sp
+      JOIN sessions s ON s.id = sp.session_id
+      WHERE sp.session_id IN (${placeholders})
+        AND sp.extractor_version = ?
+        AND sp.file_mtime_ms IS s.file_mtime_ms
+        AND sp.file_size IS s.file_size
+    `).all(...chunk, SESSION_PHENOTYPE_EXTRACTOR_VERSION);
+        for (const row of rows) {
+            try {
+                out.set(row.id, JSON.parse(row.phenotypeJson));
+            }
+            catch {
+                // Invalid derived cache data is a miss and self-heals on the next write.
+            }
+        }
+    }
+    return out;
+}
+/** Persist failure phenotypes against the exact transcript bytes used to classify them. */
+export function writeSessionPhenotypes(entries) {
+    if (entries.length === 0)
+        return;
+    const db = getDB();
+    const stmt = db.prepare(`
+    INSERT INTO session_phenotypes
+      (session_id, file_mtime_ms, file_size, extractor_version, computed_at, phenotype_json)
+    VALUES (?, ?, ?, ?, ?, ?)
+    ON CONFLICT(session_id) DO UPDATE SET
+      file_mtime_ms = excluded.file_mtime_ms,
+      file_size = excluded.file_size,
+      extractor_version = excluded.extractor_version,
+      computed_at = excluded.computed_at,
+      phenotype_json = excluded.phenotype_json
+  `);
+    const now = Date.now();
+    db.transaction(() => {
+        for (const entry of entries) {
+            stmt.run(entry.id, entry.fileMtimeMs, entry.fileSize, SESSION_PHENOTYPE_EXTRACTOR_VERSION, now, JSON.stringify(entry.phenotype));
+        }
+    })();
+}
 /** Read one derived preview only when it matches the transcript bytes on disk. */
 export function readSessionPreviewCache(id, sourceStamp) {
     const row = getDB().prepare(`
@@ -3203,17 +3423,43 @@ export function queryResourceUsageStats(options) {
     return db.prepare(sql).all(...allParams);
 }
 /**
- * Coverage of the resource-usage signal: how many distinct sessions carry any
- * row in session_resource_usage vs. the total indexed. A low ratio means the
- * historical backfill (`agents sessions backfill resources`) hasn't run — the
- * stats surface uses this to tell the user their zero-counts may just be
- * un-scanned history, not genuine non-use.
+ * Coverage of the resource-usage signal, as three honest facts:
+ *
+ * - `scanned`  — sessions the resource extractor has actually processed, i.e.
+ *   those carrying a `resource_scan_ledger` row at the current
+ *   `RESOURCE_INDEX_VERSION`. This is the true "has the historical backfill run"
+ *   signal: the ledger is stamped for EVERY scanned session, including ones that
+ *   invoked nothing (`resource_count = 0`), so `scanned/total` rises to ~1 after
+ *   `agents sessions backfill resources` regardless of how sparse explicit
+ *   invocations are.
+ * - `covered`  — distinct sessions that carry AT LEAST ONE row in
+ *   `session_resource_usage`, i.e. that actually recorded an explicit invocation.
+ *   This is an ABSOLUTE signal count, not a coverage ratio: it stays small even
+ *   at full scan coverage because most sessions invoke no skill/command, and a
+ *   non-recording harness contributes none by construction.
+ * - `total`    — sessions indexed.
+ *
+ * The two were previously conflated: `covered/total` was framed as coverage and
+ * read ~1.2% even after a full backfill (most sessions genuinely invoke nothing),
+ * so the "run the backfill" hint never cleared. Keying the hint on `scanned/total`
+ * fixes that — see `commands/sessions-stats.ts` (PHNX-2301).
  */
 export function resourceUsageCoverage() {
     const db = getDB();
     const covered = db.prepare(`SELECT COUNT(DISTINCT session_id) AS n FROM session_resource_usage`).get().n;
+    // JOIN sessions so a ledger row for a since-vanished transcript (dropped from
+    // `sessions` but not yet from the ledger) can't inflate scan coverage past the
+    // indexed set. Only rows at the current extractor version count as scanned —
+    // a stale-version row is re-derived on the next backfill, so it is not yet
+    // "covered" for this extractor.
+    const scanned = db.prepare(`
+    SELECT COUNT(*) AS n
+    FROM resource_scan_ledger l
+    JOIN sessions s ON s.id = l.session_id
+    WHERE l.extractor_version = ?
+  `).get(RESOURCE_INDEX_VERSION).n;
     const total = db.prepare(`SELECT COUNT(*) AS n FROM sessions`).get().n;
-    return { covered, total };
+    return { covered, scanned, total };
 }
 /** Has this session's resource usage been derived at the current extractor version for this exact file? */
 function needsResourceIndex(db, sessionId, stamp) {

package/dist/lib/session/fork.d.ts

@@ -1,32 +1,51 @@
+/**
+ * Session forking — branch an existing conversation into a new, independent
+ * sibling that continues the work, leaving the original untouched.
+ *
+ * `resume` continues the SAME conversation (same id, same file — it appends).
+ * `fork` launches a NEW same-harness session, load-balanced, seeded with a
+ * recap of the source so it picks up where the original left off. This is the
+ * "git branch" of conversations.
+ *
+ * The recap — not a transcript copy — is what makes fork work across every
+ * device and every REPL harness: the sibling is handed plain text as its opening
+ * input, so it never has to reach a transcript that may live on another box. The
+ * source is resolved cross-fleet by the same resolver `preview` uses; this module
+ * owns only the pure recap text the resolved data folds into.
+ */
 import type { SessionMeta } from './types.js';
-/** Agents that `fork` can branch today (see the module doc for why). */
-export declare const FORKABLE_AGENTS: readonly ["claude"];
-/** Whether a session's agent can be forked by {@link forkSession}. */
-export declare function isForkableAgent(agent: string): boolean;
-/** Outcome of a successful fork. */
-export interface ForkResult {
-    /** The new session's full id. */
-    newId: string;
-    /** The new session's short id (first 8 chars), for display/resume. */
-    shortId: string;
-    /** Absolute path of the copied transcript. */
-    filePath: string;
-    /** The label applied to the fork. */
+/** File-change tally as `sessions preview --json` serializes it (digest.changes). */
+export interface ForkRecapChanges {
+    created: number;
+    modified: number;
+    deleted: number;
+}
+/** Everything the recap seed is built from — resolved cross-fleet before launch. */
+export interface ForkRecapInput {
+    /** Source harness id — the sibling launches the same one. */
+    agent: string;
+    /** Display label for the source (label → topic → short id, resolved by the caller). */
     label: string;
+    /** Source working directory, so the sibling re-roots itself. */
+    cwd?: string;
+    /** Linear/GitHub ticket the source was bound to, if any. */
+    ticketId?: string;
+    /** Device that owns the source transcript, for the `/continue` escape hatch. */
+    machine?: string;
+    /** Short + full id, so the sibling can pull full history with `/continue <id>`. */
+    shortId: string;
+    id: string;
+    /** The source's last assistant line — the single best "where it left off" signal. */
+    lastAssistant?: string;
+    /** Changed-files tally so far. */
+    changes?: ForkRecapChanges;
 }
+/** Resolve the human display label the caller passes in from a raw SessionMeta. */
+export declare function forkLabelFor(session: Pick<SessionMeta, 'label' | 'topic' | 'shortId'>): string;
 /**
- * Fork a Claude session into a new, independent one.
- *
- * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
- * embedded session id, registers the new session in the index, and records a
- * `--name`-style label. Returns the new ids/path. Throws if the source
- * transcript is missing.
+ * Build the recap-seed prompt handed to the forked sibling as its opening input.
  *
- * @param source  The resolved metadata of the session being forked.
- * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
- * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ * Pure and deterministic (unit-tested) — no filesystem, no spawn — so the launch
+ * orchestration in `commands/fork.ts` stays the only side-effecting layer.
  */
-export declare function forkSession(source: SessionMeta, opts?: {
-    name?: string;
-    now?: string;
-}): ForkResult;
+export declare function buildForkRecap(input: ForkRecapInput): string;

package/dist/lib/session/fork.js

@@ -1,102 +1,39 @@
-/**
- * Session forking — branch an existing conversation into a new, independent
- * session that can be continued separately, leaving the original untouched.
- *
- * `resume` continues the SAME conversation (same id, same file — it appends).
- * `fork` copies the transcript under a FRESH session id, so continuing the fork
- * diverges from the original instead of mutating it. This is the "git branch"
- * of conversations.
- *
- * v1 supports Claude, whose session id IS its `<id>.jsonl` filename and which
- * resumes natively via `--resume`. A fork is therefore: copy the transcript to
- * a new-uuid filename in the same directory, rewrite the embedded `sessionId`
- * on each line, register the new session in the index, and label it. Other
- * agents (codex single-file; grok/kimi multi-file; opencode DB-only) are a
- * natural follow-up and are refused up front for now.
- */
-import { randomUUID } from 'crypto';
-import * as fs from 'fs';
-import * as path from 'path';
-import { upsertSession } from './db.js';
-import { recordRunName } from './run-names.js';
-import { deriveShortId } from '../text/short-id.js';
-/** Agents that `fork` can branch today (see the module doc for why). */
-export const FORKABLE_AGENTS = ['claude'];
-/** Whether a session's agent can be forked by {@link forkSession}. */
-export function isForkableAgent(agent) {
-    return FORKABLE_AGENTS.includes(agent);
+/** Longest last-assistant excerpt carried into the seed — enough to convey intent
+ * without pasting a wall of text (decision: Recap, not Full digest). */
+const LAST_LINE_CAP = 400;
+/** Collapse whitespace and cap length so a multi-paragraph final message becomes
+ * one scannable recap line. */
+function trimLastLine(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= LAST_LINE_CAP)
+        return collapsed;
+    return `${collapsed.slice(0, LAST_LINE_CAP).trimEnd()}…`;
 }
-/**
- * Rewrite the per-line `sessionId` field of a Claude JSONL transcript to a new
- * id. Claude resolves a conversation by its filename, so this is belt-and-braces
- * (keeps the in-file id consistent with the new filename); malformed lines are
- * passed through untouched.
- */
-function rewriteSessionId(transcript, newId) {
-    return transcript
-        .split('\n')
-        .map((line) => {
-        if (!line.trim())
-            return line;
-        try {
-            const obj = JSON.parse(line);
-            if (typeof obj.sessionId === 'string') {
-                obj.sessionId = newId;
-                return JSON.stringify(obj);
-            }
-            return line;
-        }
-        catch {
-            return line;
-        }
-    })
-        .join('\n');
+/** Resolve the human display label the caller passes in from a raw SessionMeta. */
+export function forkLabelFor(session) {
+    return session.label || session.topic || session.shortId;
 }
 /**
- * Fork a Claude session into a new, independent one.
- *
- * Copies `source.filePath` to a new `<uuid>.jsonl` beside it, rewrites the
- * embedded session id, registers the new session in the index, and records a
- * `--name`-style label. Returns the new ids/path. Throws if the source
- * transcript is missing.
+ * Build the recap-seed prompt handed to the forked sibling as its opening input.
  *
- * @param source  The resolved metadata of the session being forked.
- * @param opts.name  Optional explicit label; defaults to `fork of <original>`.
- * @param now  ISO timestamp to stamp the fork with (injectable for tests).
+ * Pure and deterministic (unit-tested) — no filesystem, no spawn — so the launch
+ * orchestration in `commands/fork.ts` stays the only side-effecting layer.
  */
-export function forkSession(source, opts = {}) {
-    if (!fs.existsSync(source.filePath)) {
-        throw new Error(`transcript not found for session ${source.shortId}: ${source.filePath}`);
+export function buildForkRecap(input) {
+    const lines = [];
+    lines.push(`Continue a prior ${input.agent} session ("${input.label}"). Pick up where it left off — do not restart it.`);
+    if (input.cwd)
+        lines.push(`Working directory: ${input.cwd}`);
+    if (input.ticketId)
+        lines.push(`Ticket: ${input.ticketId}`);
+    const last = input.lastAssistant ? trimLastLine(input.lastAssistant) : '';
+    if (last)
+        lines.push(`It last said: "${last}"`);
+    const chg = input.changes;
+    if (chg && (chg.created || chg.modified || chg.deleted)) {
+        lines.push(`Changes so far: +${chg.created} ~${chg.modified} -${chg.deleted}.`);
     }
-    const newId = randomUUID();
-    const shortId = deriveShortId(newId);
-    const dir = path.dirname(source.filePath);
-    const filePath = path.join(dir, `${newId}.jsonl`);
-    const transcript = fs.readFileSync(source.filePath, 'utf-8');
-    const rewritten = rewriteSessionId(transcript, newId);
-    fs.writeFileSync(filePath, rewritten);
-    const original = source.label || source.topic || source.shortId;
-    const label = opts.name || `fork of ${original}`;
-    // Label sidecar (seeds the DB label; survives rescans until an agent title
-    // supersedes it), mirroring `agents run --name`.
-    recordRunName({ sessionId: newId, name: label, agent: source.agent, cwd: source.cwd });
-    // Register the new session so it resolves immediately (by `agents sessions resume`,
-    // `agents sessions`, etc.) without waiting for the next scan.
-    const stamp = opts.now ?? new Date().toISOString();
-    const meta = {
-        ...source,
-        id: newId,
-        shortId,
-        filePath,
-        label,
-        timestamp: stamp,
-        lastActivity: stamp,
-        // The fork has not opened its own PR / team; drop origin-specific refs.
-        prUrl: undefined,
-        prNumber: undefined,
-        teamOrigin: undefined,
-        spawnedTeam: undefined,
-    };
-    upsertSession(meta, rewritten);
-    return { newId, shortId, filePath, label };
+    const origin = input.machine ? ` on ${input.machine}` : '';
+    lines.push(`Source session ${input.shortId}${origin} — run \`/continue ${input.id}\` if you need the full transcript.`);
+    return lines.join('\n');
 }