@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/session/bivy-session.js

@@ -0,0 +1 @@
+export {};

package/dist/session/checkpoint-pack.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Ship a session's git checkpoint between the owner node's repo and a standby's
+// replica repo as a git BUNDLE (docs/session-replication.md, worktree sync).
+//
+// The harness records each turn's checkpoint as a commit under the private ref
+// `refs/bivy/checkpoints/<slug>` (src/harness/checkpoint.ts). To replicate the
+// workspace we move those commits — nothing else — to the standby:
+//
+//   owner:   git bundle create <tmp> [<sinceSha>..]<ref>   → bytes over the wire
+//   standby: git fetch <tmp> <ref>:<ref>                    → objects land locally
+//            git read-tree <ref> && git checkout-index -a -f → materialize worktree
+//
+// A bundle is a self-contained, verifiable pack: when `sinceSha` is given it is a
+// THIN bundle carrying only the new commits (the standby already holds the base),
+// falling back to a FULL bundle when the standby has nothing or its base is gone.
+// If a thin bundle's prerequisite is missing on the standby, `applyCheckpointBundle`
+// reports `needFull` so the owner re-sends a full one — the same self-healing shape
+// as the transcript cursor.
+//
+// Kept dependency-light (just `git` + a temp file) and unit-tested against real
+// repos (test/checkpoint-pack.test.ts).
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const exec = promisify(execFile);
+const IDENTITY_ENV = {
+    GIT_AUTHOR_NAME: "Bivy Harness",
+    GIT_AUTHOR_EMAIL: "harness@bivy.local",
+    GIT_COMMITTER_NAME: "Bivy Harness",
+    GIT_COMMITTER_EMAIL: "harness@bivy.local",
+};
+/** The private checkpoint ref for a session (mirrors CheckpointStore.slugRef). */
+export function checkpointRef(sessionId) {
+    const slug = sessionId.replace(/[^A-Za-z0-9._-]/g, "-");
+    return `refs/bivy/checkpoints/${slug}`;
+}
+function git(cwd, args) {
+    return exec("git", ["-C", cwd, ...args], {
+        env: { ...process.env, ...IDENTITY_ENV },
+        maxBuffer: 256 * 1024 * 1024,
+    });
+}
+async function withTempFile(fn) {
+    const file = path.join(os.tmpdir(), `bivy-ckpt-${randomUUID()}.bundle`);
+    try {
+        return await fn(file);
+    }
+    finally {
+        await fs.promises.rm(file, { force: true });
+    }
+}
+/**
+ * Build a bundle carrying the session's checkpoint commit(s). Returns the bundle
+ * bytes, or `null` when there is nothing to send (no checkpoint ref yet, or the
+ * standby is already at the tip so an incremental range would be empty).
+ *
+ * @param repoDir   the owner's worktree (any path inside the repo)
+ * @param sessionId the session whose checkpoint ref to bundle
+ * @param sinceSha  the standby's last-known checkpoint sha; when it is an ancestor
+ *                  of the current tip, only the delta is bundled (thin)
+ */
+export async function createCheckpointBundle(repoDir, sessionId, sinceSha) {
+    const ref = checkpointRef(sessionId);
+    // No checkpoint ref → nothing to replicate yet.
+    const tip = await git(repoDir, ["rev-parse", "--verify", "--quiet", ref]).then((r) => r.stdout.trim()).catch(() => "");
+    if (!tip)
+        return null;
+    // Already current — skip an empty bundle.
+    if (sinceSha && sinceSha === tip)
+        return null;
+    // Use a thin range only when `sinceSha` is a real ancestor we can negate against.
+    let range = ref;
+    if (sinceSha) {
+        const isAncestor = await git(repoDir, ["merge-base", "--is-ancestor", sinceSha, ref]).then(() => true).catch(() => false);
+        if (isAncestor)
+            range = `${sinceSha}..${ref}`;
+    }
+    return withTempFile(async (file) => {
+        try {
+            await git(repoDir, ["bundle", "create", file, range]);
+        }
+        catch {
+            // An empty range ("Refusing to create empty bundle") or any bundle failure
+            // → nothing to ship.
+            return null;
+        }
+        return fs.promises.readFile(file);
+    });
+}
+/**
+ * Apply a checkpoint bundle into the standby's replica repo, advancing its
+ * checkpoint ref. Returns `{ ok:false, needFull:true }` when the bundle is thin
+ * and its prerequisite base commit is missing locally, so the caller can request
+ * a full bundle. Does NOT touch the working tree — call `materializeCheckpoint`
+ * for that once the objects are present.
+ */
+export async function applyCheckpointBundle(replicaDir, sessionId, bundle) {
+    const ref = checkpointRef(sessionId);
+    return withTempFile(async (file) => {
+        await fs.promises.writeFile(file, bundle);
+        // A thin bundle with an absent prerequisite fails verification here.
+        const verified = await git(replicaDir, ["bundle", "verify", file]).then(() => true).catch(() => false);
+        if (!verified)
+            return { ok: false, needFull: true };
+        await git(replicaDir, ["fetch", file, `${ref}:${ref}`]);
+        return { ok: true };
+    });
+}
+/**
+ * Materialize the standby's checkpoint ref into its replica working tree, so a
+ * promoted session continues from the exact files of the last replicated turn.
+ * Uses a throwaway index and force checkout — the replica worktree is ours to own.
+ */
+export async function materializeCheckpoint(replicaDir, sessionId) {
+    const ref = checkpointRef(sessionId);
+    const tmpIndex = path.join(os.tmpdir(), `bivy-ckpt-index-${randomUUID()}`);
+    try {
+        const withIndex = (args) => exec("git", ["-C", replicaDir, ...args], {
+            env: { ...process.env, ...IDENTITY_ENV, GIT_INDEX_FILE: tmpIndex },
+            maxBuffer: 256 * 1024 * 1024,
+        });
+        await withIndex(["read-tree", ref]);
+        await withIndex(["checkout-index", "-a", "-f"]);
+    }
+    finally {
+        await fs.promises.rm(tmpIndex, { force: true });
+    }
+}

package/dist/session/event-log.js

@@ -0,0 +1,340 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+//
+// Single append-only per-session event log (docs/dramatic-simplification-plan.md,
+// slice 2). A session's transcript detail used to live in THREE whole-file JSON
+// stores — `intermediate-messages/<id>.json`, `tool-activities/<id>.json`, and the
+// base transcript `transcripts/<id>.json` — each rewritten in full on every change
+// and each able to drift from the others. This collapses all of them into one
+// append-only JSONL log (`event-log/<id>.jsonl`): writes append, and history is
+// DERIVED by replaying the log.
+//
+// The log carries two independent projections, distinguished by `bivyKind`:
+//   - OVERLAY entries (`intermediate` / `tool`): reasoning + tool-activity detail,
+//     folded by `replayExtras` (reproducing the legacy per-kind fold) into the flat
+//     `extras` list `mergeTranscript` consumes.
+//   - BASE entries (`base`): the runtime's own transcript (user prompts + assistant
+//     text). The base is a SNAPSHOT that is overwritten each turn and SHRINKS on
+//     compaction, so it cannot be appended naively. Instead each snapshot is stored
+//     as a bounded DELTA against the previous one: a `reset:false` record carrying
+//     only the new tail when the snapshot merely extends the last (the common case),
+//     or a `reset:true` record carrying the full snapshot when it shrinks or a
+//     prefix message changed (compaction / in-place mutation). `baseReplay` folds
+//     these back — reset replaces, non-reset extends — reproducing the last snapshot
+//     exactly, so the fold is behaviour-preserving while keeping the file bounded
+//     (~O(total messages)) instead of O(turns × transcript size).
+//
+// The two projections are independent: base records and overlay records may be
+// interleaved in any order on disk; each replay reads only its own kind.
+import fs from "node:fs";
+import { normalizedIntermediateText, thinkingTextFromContent, mergeTranscript } from "./transcript-merge.js";
+function isOverlay(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const kind = value.bivyKind;
+    return (kind === "intermediate" || kind === "tool") && typeof value.afterMessageCount === "number";
+}
+function isBase(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.bivyKind === "base" && Array.isArray(record.messages) && typeof record.reset === "boolean";
+}
+function isRecord(value) {
+    return isOverlay(value) || isBase(value);
+}
+/**
+ * Fold the intermediate-reasoning entries exactly as the legacy incremental
+ * upsert did (`upsertIntermediateMessage` in server.ts): last write wins per id;
+ * a same-text/same-anchor entry under a DIFFERENT id is merged onto the first
+ * (keeping its id and the earlier `createdAt`); the result is ordered by
+ * `afterMessageCount` then `createdAt`. Replaying the append log through this
+ * reproduces the array the legacy store held.
+ */
+export function foldIntermediate(entries) {
+    const out = [];
+    for (const entry of entries) {
+        const entryText = normalizedIntermediateText(thinkingTextFromContent(entry.content));
+        const index = out.findIndex((m) => m.id != null && m.id === entry.id);
+        if (index >= 0) {
+            out[index] = entry;
+        }
+        else {
+            const dup = entryText
+                ? out.findIndex((m) => m.id !== entry.id && m.afterMessageCount === entry.afterMessageCount && normalizedIntermediateText(thinkingTextFromContent(m.content)) === entryText)
+                : -1;
+            if (dup >= 0)
+                out[dup] = { ...out[dup], ...entry, id: out[dup].id, createdAt: Math.min(out[dup].createdAt, entry.createdAt) };
+            else
+                out.push(entry);
+        }
+        out.sort((a, b) => a.afterMessageCount - b.afterMessageCount || a.createdAt - b.createdAt);
+    }
+    return out;
+}
+/**
+ * Fold the tool-activity entries exactly as the legacy `upsertToolActivityMessage`
+ * did: merge onto an existing id (`{...existing, ...entry}`), else append; order by
+ * `afterMessageCount` then `createdAt`; keep only the most recent 500.
+ */
+export function foldTool(entries) {
+    let out = [];
+    for (const entry of entries) {
+        const index = out.findIndex((m) => m.id != null && m.id === entry.id);
+        if (index >= 0)
+            out[index] = { ...out[index], ...entry };
+        else
+            out.push(entry);
+        out.sort((a, b) => a.afterMessageCount - b.afterMessageCount || a.createdAt - b.createdAt);
+        out = out.slice(-500);
+    }
+    return out;
+}
+/**
+ * Replay a session's overlay entries into the flat `extras` list `mergeTranscript`
+ * consumes — the intermediate entries folded first, then the tool entries, matching
+ * the legacy `[...loadIntermediateMessages, ...loadToolActivityMessages]` order.
+ * Base records are ignored (they are folded separately by `baseReplay`).
+ */
+export function replayExtras(entries) {
+    const intermediate = [];
+    const tool = [];
+    for (const entry of entries) {
+        if (entry.bivyKind === "intermediate")
+            intermediate.push(entry);
+        else if (entry.bivyKind === "tool")
+            tool.push(entry);
+    }
+    return [...foldIntermediate(intermediate), ...foldTool(tool)];
+}
+/**
+ * Replay a session's base records into the base transcript: `reset` replaces the
+ * working array, non-reset extends it with its tail. The result equals the last
+ * full snapshot the server persisted, exactly. Overlay records are ignored.
+ */
+export function baseReplay(entries) {
+    let base = [];
+    for (const entry of entries) {
+        if (entry.bivyKind !== "base")
+            continue;
+        if (entry.reset)
+            base = [...entry.messages];
+        else
+            base = base.concat(entry.messages);
+    }
+    return base;
+}
+/** Parse a JSONL log body into valid records, skipping malformed/blank lines. */
+export function parseLog(body) {
+    const out = [];
+    for (const line of body.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const value = JSON.parse(trimmed);
+            if (isRecord(value))
+                out.push(value);
+        }
+        catch { }
+    }
+    return out;
+}
+/**
+ * Append-only, coalesced, throttled JSONL log store — the write+read companion to
+ * the legacy `SidecarStore`, but appending lines instead of rewriting the whole
+ * file. In-memory state keeps reads cheap; disk writes coalesce to at most one per
+ * `throttleMs` per session (a burst of same-id deltas within a window collapses to
+ * one appended line). Durability at boundaries is explicit `flush()` (turn-end,
+ * close, delete, shutdown), mirroring `SidecarStore`.
+ */
+export class EventLog {
+    dir;
+    pathFor;
+    redact;
+    throttleMs;
+    disk = new Map();
+    pending = new Map();
+    timers = new Map();
+    lastFlush = new Map();
+    counters = new Map();
+    // Per-message JSON of the base snapshot the log currently represents, so the next
+    // snapshot can be diffed (prefix-compared) into a bounded delta. Seeded from disk
+    // on first use of a session after a restart.
+    baseKeys = new Map();
+    constructor(dir, pathFor, redact = (t) => t, throttleMs = 500) {
+        this.dir = dir;
+        this.pathFor = pathFor;
+        this.redact = redact;
+        this.throttleMs = throttleMs;
+    }
+    load(id) {
+        const cached = this.disk.get(id);
+        if (cached)
+            return cached;
+        let data = [];
+        try {
+            data = parseLog(fs.readFileSync(this.pathFor(id), "utf8"));
+        }
+        catch { }
+        this.disk.set(id, data);
+        return data;
+    }
+    /** Allocate a unique synthetic coalescing key (for id-less records). */
+    syntheticKey(id) {
+        const next = (this.counters.get(id) ?? 0) + 1;
+        this.counters.set(id, next);
+        return `#${next}`;
+    }
+    /** Queue a fully-formed record into the pending batch and schedule a flush. */
+    enqueue(id, key, record) {
+        let batch = this.pending.get(id);
+        if (!batch) {
+            batch = new Map();
+            this.pending.set(id, batch);
+        }
+        // Same key within a flush window coalesces to one line (streaming deltas of one
+        // logical entry). Id-less records get a unique synthetic key so they never merge.
+        batch.set(key, record);
+        if (this.timers.has(id))
+            return; // a trailing flush is already scheduled
+        const elapsed = Date.now() - (this.lastFlush.get(id) ?? 0);
+        if (elapsed >= this.throttleMs)
+            this.flush(id);
+        else
+            this.timers.set(id, setTimeout(() => { this.timers.delete(id); this.flush(id); }, this.throttleMs - elapsed));
+    }
+    /** Coalesce an overlay entry into the pending batch and schedule a flush. */
+    append(id, entry) {
+        this.load(id);
+        // Snapshot the entry: the server reuses one live object for a streaming reasoning
+        // block, reassigning `.content` per delta. A shallow copy captures the state at
+        // append time so the pending/on-disk record can't change under us.
+        this.enqueue(id, entry.id ?? this.syntheticKey(id), { ...entry });
+    }
+    /**
+     * Record the runtime's current base transcript snapshot as a bounded delta. The
+     * snapshot is diffed against the base the log already represents: a prefix-extend
+     * appends only the new tail (`reset:false`), anything else appends a full replace
+     * (`reset:true`). A no-op (identical snapshot) appends nothing. The stored messages
+     * are a deep JSON copy, so a later in-place mutation of the runtime's objects can't
+     * change what was recorded.
+     */
+    appendBaseSnapshot(id, messages) {
+        this.load(id);
+        let prevKeys = this.baseKeys.get(id);
+        if (!prevKeys) {
+            prevKeys = baseReplay(this.entries(id)).map((m) => JSON.stringify(m));
+            this.baseKeys.set(id, prevKeys);
+        }
+        const nextKeys = messages.map((m) => JSON.stringify(m));
+        // Identical snapshot → nothing to record.
+        if (nextKeys.length === prevKeys.length && prevKeys.every((k, i) => k === nextKeys[i]))
+            return;
+        // A prefix-EXTEND (strictly longer, every prior message unchanged) appends only
+        // the new tail; anything else — a shrink (compaction), a changed prefix message
+        // (in-place mutation), or the first snapshot (empty prev, nothing to extend) —
+        // appends a full reset. Rebuild the recorded messages from the serialized form:
+        // a free deep copy that also matches exactly what will land on disk.
+        const extend = prevKeys.length > 0 && nextKeys.length > prevKeys.length && prevKeys.every((k, i) => k === nextKeys[i]);
+        const record = extend
+            ? { bivyKind: "base", reset: false, createdAt: Date.now(), messages: nextKeys.slice(prevKeys.length).map((s) => JSON.parse(s)) }
+            : { bivyKind: "base", reset: true, createdAt: Date.now(), messages: nextKeys.map((s) => JSON.parse(s)) };
+        this.baseKeys.set(id, nextKeys);
+        this.enqueue(id, this.syntheticKey(id), record);
+    }
+    /** Replay the overlay entries (disk + pending) into the flat `extras` list. */
+    read(id) {
+        return replayExtras(this.entries(id));
+    }
+    /** Replay the base records (disk + pending) into the base transcript. */
+    readBase(id) {
+        return baseReplay(this.entries(id));
+    }
+    /**
+     * The full derived conversation: overlay detail merged into the base transcript.
+     * Prefers the runtime's own live transcript when it has one; otherwise replays the
+     * base persisted in the log (a reopened session on a runtime that can't rebuild it).
+     * This is the single read path — it absorbs the former `mergeConversation` helper.
+     */
+    deriveHistory(id, runtimeBase) {
+        const base = runtimeBase && runtimeBase.length ? runtimeBase : this.readBase(id);
+        return mergeTranscript(base, this.read(id));
+    }
+    /** Full ordered record list (already-flushed followed by pending). */
+    entries(id) {
+        const disk = this.load(id);
+        const batch = this.pending.get(id);
+        return batch && batch.size ? [...disk, ...batch.values()] : disk;
+    }
+    /** Whether this session has any overlay entries (in memory or on disk). */
+    hasEntries(id) {
+        return this.entries(id).some((e) => e.bivyKind === "intermediate" || e.bivyKind === "tool");
+    }
+    /** Whether this session has any base record (in memory or on disk). */
+    hasBase(id) {
+        return this.entries(id).some((e) => e.bivyKind === "base");
+    }
+    flush(id) {
+        const timer = this.timers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(id);
+        }
+        const batch = this.pending.get(id);
+        if (!batch || !batch.size)
+            return;
+        const lines = [...batch.values()];
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            fs.appendFileSync(this.pathFor(id), this.redact(lines.map((e) => JSON.stringify(e)).join("\n") + "\n"));
+            const disk = this.load(id);
+            disk.push(...lines);
+            batch.clear();
+            this.lastFlush.set(id, Date.now());
+        }
+        catch { }
+    }
+    /**
+     * Overwrite a session's log with a known-complete set of records. Used by the
+     * one-time legacy→log migration to seed the log before it becomes the sole source.
+     * Replaces the file and the in-memory state and discards any pending batch, since
+     * `entries` is authoritative. The replays re-fold on read, so passing already-folded
+     * records is exact and idempotent.
+     */
+    rewrite(id, entries) {
+        const copy = entries.map((e) => ({ ...e }));
+        const timer = this.timers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(id);
+        }
+        this.pending.delete(id);
+        this.baseKeys.delete(id);
+        this.disk.set(id, copy);
+        try {
+            fs.mkdirSync(this.dir, { recursive: true });
+            const body = copy.length ? copy.map((e) => JSON.stringify(e)).join("\n") + "\n" : "";
+            fs.writeFileSync(this.pathFor(id), this.redact(body));
+            this.lastFlush.set(id, Date.now());
+        }
+        catch { }
+    }
+    /** Cancel any pending write and forget the session (used when it's deleted). */
+    drop(id) {
+        const timer = this.timers.get(id);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(id);
+        }
+        this.disk.delete(id);
+        this.pending.delete(id);
+        this.lastFlush.delete(id);
+        this.counters.delete(id);
+        this.baseKeys.delete(id);
+    }
+    flushAll() {
+        for (const id of this.pending.keys())
+            this.flush(id);
+    }
+}

package/dist/session/fork-dirty.js

@@ -0,0 +1,73 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Capture / re-apply a session's UNCOMMITTED working-tree changes for a fork
+ * (see docs/session-fork-plan.md). The committed branch already travels via
+ * origin (the destination re-clones + checks it out); this carries the in-flight
+ * edits on top so a fork never silently drops work-in-progress.
+ *
+ * Resolved decision: the patch is size-capped. When the working tree is larger
+ * than the cap (big or binary churn), we DON'T inline it — `capture` returns
+ * `pushedInstead: true` and the caller commits & pushes the branch so the
+ * destination reproduces from the pushed commit instead.
+ */
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024; // 5 MiB of patch text
+function git(repoDir, args) {
+    try {
+        return execFileSync("git", ["-C", repoDir, ...args], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch (err) {
+        // `git diff --no-index` exits 1 when files differ — that's the normal case,
+        // and the useful patch is on stdout, so surface it rather than throwing.
+        const e = err;
+        if (typeof e.stdout === "string")
+            return e.stdout;
+        throw err;
+    }
+}
+/**
+ * Snapshot the working tree at `repoDir`: tracked changes vs HEAD plus untracked
+ * (non-ignored) files, as a single `git apply`-able patch. Returns
+ * `pushedInstead: true` (and an empty patch) when the snapshot exceeds `maxBytes`.
+ */
+export function captureDirtyPatch(repoDir, opts = {}) {
+    const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+    // Tracked changes relative to HEAD (staged + unstaged), binary-safe.
+    const tracked = git(repoDir, ["diff", "HEAD", "--binary"]);
+    const untracked = git(repoDir, ["ls-files", "--others", "--exclude-standard"])
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter(Boolean);
+    // Each untracked file becomes a "new file" patch via --no-index against /dev/null.
+    const untrackedPatches = untracked.map((rel) => git(repoDir, ["diff", "--no-index", "--binary", "--", "/dev/null", rel]));
+    const patch = [tracked, ...untrackedPatches].filter(Boolean).join("");
+    if (Buffer.byteLength(patch, "utf8") > maxBytes) {
+        return { patch: "", untracked: [], pushedInstead: true };
+    }
+    return { patch, untracked };
+}
+/**
+ * Re-apply a captured patch onto a fresh checkout at `repoDir`. A no-op when the
+ * source pushed the branch instead (`pushedInstead`) or the working tree was
+ * clean (empty patch). Uses `git apply` so both tracked hunks and untracked
+ * new-file hunks (produced via `--no-index`) land correctly.
+ */
+export function applyDirtyPatch(repoDir, dirty) {
+    if (!dirty || dirty.pushedInstead || !dirty.patch.trim())
+        return;
+    const tmp = path.join(os.tmpdir(), `bivy-fork-${Date.now()}-${Math.random().toString(36).slice(2)}.patch`);
+    fs.writeFileSync(tmp, dirty.patch);
+    try {
+        execFileSync("git", ["-C", repoDir, "apply", "--whitespace=nowarn", tmp], { stdio: "pipe" });
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch {
+            // best effort
+        }
+    }
+}

package/dist/session/fork-prereqs.js

@@ -0,0 +1,61 @@
+/**
+ * Fork prerequisite detection (docs/session-fork-plan.md, acceptance: "Missing
+ * prerequisites on the destination node are detected and clearly communicated").
+ *
+ * The engine reports what the destination is missing to continue the forked
+ * session so the UI can guide the user instead of failing opaquely:
+ *   - agent — the target runtime must be installed/available (a HARD blocker).
+ *   - model — the model's provider should have auth on this node (soft: the
+ *     runtime can fall back, or the model-auth vault can supply it).
+ *   - repo  — the source repo should be reachable (soft: it may be public, or
+ *     the user can connect GitHub afterwards).
+ *
+ * Pure so the server can gather the raw booleans however it likes and this stays
+ * unit-testable.
+ */
+export function evaluateForkPrereqs(input) {
+    const out = [];
+    out.push({
+        kind: "agent",
+        ok: input.agent.available,
+        label: input.agent.displayName,
+        detail: input.agent.available
+            ? `${input.agent.displayName} is installed on this node.`
+            : `${input.agent.displayName} is not installed on this node — install it to continue.`,
+        blocking: !input.agent.available,
+        ...(input.agent.available ? {} : { fix: "runtime.install" }),
+    });
+    if (input.model) {
+        out.push({
+            kind: "model",
+            ok: input.model.configured,
+            label: input.model.provider,
+            detail: input.model.configured
+                ? `${input.model.provider} is authenticated on this node.`
+                : `${input.model.provider} isn't logged in here — connect it (or the fork will fall back to an available model).`,
+            blocking: false,
+            ...(input.model.configured ? {} : { fix: "provider.connect" }),
+        });
+    }
+    if (input.repo) {
+        out.push({
+            kind: "repo",
+            ok: input.repo.reachable,
+            label: input.repo.slug,
+            detail: input.repo.reachable
+                ? `${input.repo.slug} is reachable from this node.`
+                : `${input.repo.slug} may not be reachable here — connect GitHub if the branch fails to check out.`,
+            blocking: false,
+            ...(input.repo.reachable ? {} : { fix: "github.connect" }),
+        });
+    }
+    return out;
+}
+/** The subset that should stop a fork from proceeding (missing + blocking). */
+export function blockingForkPrereqs(prereqs) {
+    return prereqs.filter((p) => !p.ok && p.blocking);
+}
+/** The subset worth surfacing to the user (anything not satisfied). */
+export function missingForkPrereqs(prereqs) {
+    return prereqs.filter((p) => !p.ok);
+}

package/dist/session/fork.js

@@ -0,0 +1,57 @@
+import { normalizeMessages, buildSeedPrompt, } from "./transcript-normal.js";
+/**
+ * Capture a fork bundle on the source node. Always includes the normalized
+ * transcript (the cross-runtime seed, and the fallback when a same-runtime
+ * destination can't natively import). Adds the runtime's native payload for a
+ * full same-runtime replay — but only when the fork could actually use it: a
+ * fork to a known different agent skips it, since the native format never
+ * round-trips across runtimes.
+ */
+export function buildForkBundle(opts) {
+    const { runtime, sessionFile, record } = opts;
+    const messages = runtime.readMessages?.(sessionFile);
+    const normalized = normalizeMessages(messages, {
+        sourceRuntimeId: runtime.id,
+        model: record.model,
+        title: record.title,
+        createdAt: new Date().toISOString(),
+    });
+    // Only worth capturing when the target is the same runtime (or not yet known).
+    const nativeCouldReplay = !opts.targetRuntimeId || opts.targetRuntimeId === runtime.id;
+    const native = nativeCouldReplay && runtime.capabilities.forkTransport && runtime.exportForFork
+        ? runtime.exportForFork(sessionFile)
+        : undefined;
+    return { record, normalized, ...(native ? { native } : {}), ...(opts.dirtyPatch ? { dirtyPatch: opts.dirtyPatch } : {}) };
+}
+/**
+ * Decide the fidelity a fork of `bundle` into `targetRuntime` can achieve —
+ * "full" only when the target is the SAME runtime that produced the native
+ * payload and can import it; "seeded" otherwise. Pure; no side effects.
+ */
+export function resolveForkFidelity(bundle, targetRuntime) {
+    const native = bundle.native;
+    const canImport = !!native &&
+        native.runtimeId === targetRuntime.id &&
+        !!targetRuntime.capabilities.forkTransport &&
+        typeof targetRuntime.importForFork === "function";
+    return canImport ? "full" : "seeded";
+}
+/**
+ * Turn a fork bundle into a concrete stand-up plan on the destination node:
+ * either resume a natively imported transcript (full) or a seed prompt for a
+ * fresh session (seeded). The server executes the returned plan (worktree +
+ * session creation live there); this stays pure of daemon wiring.
+ */
+export async function materializeFork(opts) {
+    const { bundle, targetRuntime, ctx } = opts;
+    if (resolveForkFidelity(bundle, targetRuntime) === "full" && bundle.native && targetRuntime.importForFork) {
+        const { sessionFile, id } = await targetRuntime.importForFork(bundle.native, ctx);
+        return { kind: "resume", fidelity: "full", sessionFile, id };
+    }
+    const seedPrompt = buildSeedPrompt(bundle.normalized, {
+        targetAgent: targetRuntime.displayName,
+        context: { repoSlug: bundle.record.repoSlug, branch: bundle.record.branch, prUrl: bundle.record.prUrl },
+        ...opts.seed,
+    });
+    return { kind: "seed", fidelity: "seeded", seedPrompt };
+}