@edspencer/paddock 0.71.1 → 0.72.0

package/packages/server/dist/routes.d.ts

@@ -16,6 +16,9 @@
  *   git      — /api/git[/push|/github/*], project git status/diff/commit
  *   projects — projects CRUD + promote, pins, files/changelog/overview/commands
  *   discover — /api/discover, /api/discover/sessions (instance-level, #745)
+ *   transcripts — GET /api/transcripts/migration[/chats] (the own→host migration
+ *              probe + plan) and POST /api/transcripts/migration (execute)
+ *              (instance-level, #882)
  *   triggers — project triggers CRUD + runtime + run-now
  *   chats    — workspace chat lifecycle (list/runs/usage/create/messages/
  *              subagents/context/delete/rename/fork/archive/star/seen/promote)

package/packages/server/dist/routes.js

@@ -6,6 +6,7 @@ import { registerTriggerWorkspaceRoutes } from "./routes/triggers.js";
 import { registerChatWorkspaceRoutes } from "./routes/chats.js";
 import { registerMcpRoutes } from "./routes/mcp.js";
 import { registerDiscoverRoutes } from "./routes/discover.js";
+import { registerTranscriptsRoutes } from "./routes/transcripts.js";
 import { mountWorkspaceRoutes } from "./routes/workspace-mount.js";
 export { parseRangeHeader } from "./http-bytes.js";
 export async function registerRoutes(app, deps) {
@@ -14,6 +15,7 @@ export async function registerRoutes(app, deps) {
     registerGitRoutes(app, ctx);
     registerProjectRoutes(app, ctx);
     registerDiscoverRoutes(app, ctx);
+    registerTranscriptsRoutes(app, ctx);
     // The workspace-scoped half of every group, mounted twice: `/api/root` (the
     // root workspace, key `""`) and `/api/projects/:slug` (a project). Same
     // handlers both times — that identity is the point, not an optimisation.

package/packages/server/dist/transcript-move.d.ts

@@ -0,0 +1,62 @@
+/** Thrown rather than clobbering — see the module doc's property 2. */
+export declare class DestinationExistsError extends Error {
+    readonly destination: string;
+    constructor(destination: string);
+}
+/** Does anything at all live at `p` — including a broken symlink? */
+export declare function pathExists(p: string): Promise<boolean>;
+/**
+ * Move one file or directory tree `from` → `to`, without ever overwriting.
+ *
+ * The caller owns the collision policy: this refuses, it does not invent a
+ * name. See {@link uniqueDestination} for the migration's answer.
+ */
+export declare function moveEntry(from: string, to: string): Promise<void>;
+/**
+ * A free path at `dir/<name>`, suffixing `.1`, `.2`, … when taken.
+ *
+ * Used only for the PRESERVE side. A preserve dir can already hold a copy from
+ * an earlier run of a migration that failed partway, and "nothing is ever
+ * deleted" has to hold across retries too — so the second copy is set beside
+ * the first rather than on top of it. The real path used is what the response
+ * reports, so the user is never sent to a path that holds someone else's file.
+ */
+export declare function uniqueDestination(dir: string, name: string): Promise<string>;
+/**
+ * Everything in a store that belongs to one session id, as store-RELATIVE
+ * paths so the same list can be replayed against a destination.
+ *
+ * `.reverts/` is prefix-matched longest-first rather than split at a fixed
+ * offset: a session id is only guaranteed to match `[A-Za-z0-9._-]+`, so
+ * assuming a 36-char UUID mis-files every revert belonging to a chat named
+ * anything else, and a chat whose id is a prefix of another's would steal its
+ * neighbour's reverts.
+ */
+export interface ChatArtifacts {
+    sessionId: string;
+    /** Store-relative paths, in the order they should be moved. */
+    relative: string[];
+}
+/**
+ * List the artifacts of `sessionId` that actually exist in `store`.
+ *
+ * `revertNames` is passed in rather than read here because the migration reads
+ * `.reverts/` once per project and groups it, and a per-chat readdir of a
+ * directory shared by 500 chats is 500 readdirs of the same directory.
+ */
+export declare function collectChatArtifacts(store: string, sessionId: string, revertNames?: readonly string[]): Promise<ChatArtifacts>;
+/** Which chat a `.reverts/<id>-<stamp>.jsonl` belongs to; see {@link ChatArtifacts}. */
+export declare function revertOwner(name: string, chatIds: ReadonlySet<string>): string | undefined;
+/**
+ * Remove `dir` and every directory under it that holds no files, bottom-up.
+ *
+ * Not a delete of anything the user has: it clears the *structure* left behind
+ * once a directory's contents have been moved out — `.reverts/` after its
+ * snapshots have gone, `memory/` after its files have been merged. Without it
+ * those empty shells keep `.chats/` non-empty, `pointChatsDirAt` declines the
+ * redirect symlink, and the migration fails its own postcondition on a
+ * directory containing nothing at all.
+ *
+ * Anything holding a file is left completely alone.
+ */
+export declare function pruneEmptyTree(dir: string): Promise<void>;

package/packages/server/dist/transcript-move.js

@@ -0,0 +1,179 @@
+/**
+ * Moving a chat's files from one transcript store to another — the shared
+ * primitive under the `own → host` migration (#882).
+ *
+ * ## Why this is a module and not four lines inside the migration
+ *
+ * A "chat" is not one file. On this box's real stores a single session id owns
+ * up to four separate things:
+ *
+ *   `<id>.jsonl`             the transcript
+ *   `<id>/subagents/`        sidechain transcripts
+ *   `<id>/tool-results/`     spilled tool output
+ *   `.reverts/<id>-*.jsonl`  revert snapshots, in a directory SHARED by every
+ *                            session in the store (`herdctl.ts:1988`)
+ *
+ * `promoteSession` (`herdctl.ts:1814-1852`) moves only the first of those, and
+ * therefore silently orphans the rest — the `<id>/` directory and the reverts
+ * stay in the source store, pointing at a chat that is no longer there. That is
+ * a pre-existing bug, **filed as #898**, and this helper is its fix: promote
+ * should adopt {@link collectChatArtifacts} + {@link moveArtifacts} rather than
+ * grow a second copy of the enumeration. Deliberately NOT changed here — see
+ * `docs/DESIGN-transcripts-migration.md` §10.6 for why it is a follow-up
+ * (promote has its own failure modes and its own tests, and reviewing them as a
+ * footnote to a large feature is how a regression gets in).
+ *
+ * ## The two properties everything else rests on
+ *
+ * 1. **Nothing is ever deleted.** The migration's whole promise to the user is
+ *    that a copy they disagree with is set aside, not destroyed. So there is no
+ *    unlink in this module that is not the second half of a copy.
+ *
+ * 2. **A destination that exists is never written through.** This is the
+ *    load-bearing one, and it is not automatic: POSIX `rename(2)` *silently
+ *    replaces* an existing destination file. `mv a b` overwriting `b` is the
+ *    behaviour every caller would get by default, and on the `host` side `b` is
+ *    a file in the user's real `~/.claude`. {@link moveArtifacts} therefore
+ *    `lstat`s every destination first and refuses with
+ *    {@link DestinationExistsError}; the migration's own rule is to move the
+ *    superseded copy to the preserve dir BEFORE calling in here, so this guard
+ *    should never fire — which is exactly why it has to exist and be tested.
+ *
+ * ## `rename` first, copy on `EXDEV`
+ *
+ * `ensureProjectChats:352-362` unconditionally does `cp` + `rm` with the note
+ * *"rename would EXDEV across mounts"*. Correct, and it leaves a 53× speedup on
+ * the floor in the overwhelmingly common case where the data dir and
+ * `~/.claude` share a filesystem (measured in design §6: 24 ms vs 1.3 s for 500
+ * chats). So: try `rename`, and fall back only on the errors that actually mean
+ * "different device". `preserveTimestamps: true` on the copy path is load-bearing
+ * rather than cosmetic (#588): a transcript's mtime is the cache key for
+ * auto-name, preview and sidechain detection, and `fs.cp` stamps NOW by default.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/**
+ * The errors that mean "these paths are not on the same filesystem, `rename`
+ * cannot help you". `EXDEV` is the POSIX one; `ENOTSUP`/`EPERM` show up from
+ * some FUSE and overlay mounts (docker's overlayfs, sshfs) for the same reason.
+ */
+const CROSS_DEVICE = new Set(["EXDEV", "ENOTSUP", "EPERM"]);
+/** Thrown rather than clobbering — see the module doc's property 2. */
+export class DestinationExistsError extends Error {
+    destination;
+    constructor(destination) {
+        super(`refusing to overwrite an existing path: ${destination}`);
+        this.destination = destination;
+        this.name = "DestinationExistsError";
+    }
+}
+/** Does anything at all live at `p` — including a broken symlink? */
+export async function pathExists(p) {
+    return fs
+        .lstat(p)
+        .then(() => true)
+        .catch(() => false);
+}
+/**
+ * Move one file or directory tree `from` → `to`, without ever overwriting.
+ *
+ * The caller owns the collision policy: this refuses, it does not invent a
+ * name. See {@link uniqueDestination} for the migration's answer.
+ */
+export async function moveEntry(from, to) {
+    if (await pathExists(to))
+        throw new DestinationExistsError(to);
+    await fs.mkdir(path.dirname(to), { recursive: true });
+    try {
+        await fs.rename(from, to);
+        return;
+    }
+    catch (err) {
+        const code = err.code ?? "";
+        if (!CROSS_DEVICE.has(code))
+            throw err;
+    }
+    // Cross-device: copy then remove. If the copy throws, the source is still
+    // there and untouched — which is the failure mode we want, because the
+    // alternative is a half-moved chat with no copy anywhere.
+    await fs.cp(from, to, { recursive: true, preserveTimestamps: true });
+    await fs.rm(from, { recursive: true, force: true });
+}
+/**
+ * A free path at `dir/<name>`, suffixing `.1`, `.2`, … when taken.
+ *
+ * Used only for the PRESERVE side. A preserve dir can already hold a copy from
+ * an earlier run of a migration that failed partway, and "nothing is ever
+ * deleted" has to hold across retries too — so the second copy is set beside
+ * the first rather than on top of it. The real path used is what the response
+ * reports, so the user is never sent to a path that holds someone else's file.
+ */
+export async function uniqueDestination(dir, name) {
+    const first = path.join(dir, name);
+    if (!(await pathExists(first)))
+        return first;
+    for (let n = 1; n < 1000; n++) {
+        const candidate = path.join(dir, `${name}.${n}`);
+        if (!(await pathExists(candidate)))
+            return candidate;
+    }
+    throw new Error(`no free destination for ${name} in ${dir} after 1000 tries`);
+}
+/**
+ * List the artifacts of `sessionId` that actually exist in `store`.
+ *
+ * `revertNames` is passed in rather than read here because the migration reads
+ * `.reverts/` once per project and groups it, and a per-chat readdir of a
+ * directory shared by 500 chats is 500 readdirs of the same directory.
+ */
+export async function collectChatArtifacts(store, sessionId, revertNames = []) {
+    const relative = [];
+    const transcript = `${sessionId}.jsonl`;
+    if (await pathExists(path.join(store, transcript)))
+        relative.push(transcript);
+    if (await pathExists(path.join(store, sessionId)))
+        relative.push(sessionId);
+    for (const name of revertNames) {
+        if (await pathExists(path.join(store, ".reverts", name))) {
+            relative.push(path.join(".reverts", name));
+        }
+    }
+    return { sessionId, relative };
+}
+/** Which chat a `.reverts/<id>-<stamp>.jsonl` belongs to; see {@link ChatArtifacts}. */
+export function revertOwner(name, chatIds) {
+    let best;
+    for (let i = name.indexOf("-"); i > 0; i = name.indexOf("-", i + 1)) {
+        const candidate = name.slice(0, i);
+        if (chatIds.has(candidate) && (best === undefined || candidate.length > best.length)) {
+            best = candidate;
+        }
+    }
+    return best;
+}
+/**
+ * Remove `dir` and every directory under it that holds no files, bottom-up.
+ *
+ * Not a delete of anything the user has: it clears the *structure* left behind
+ * once a directory's contents have been moved out — `.reverts/` after its
+ * snapshots have gone, `memory/` after its files have been merged. Without it
+ * those empty shells keep `.chats/` non-empty, `pointChatsDirAt` declines the
+ * redirect symlink, and the migration fails its own postcondition on a
+ * directory containing nothing at all.
+ *
+ * Anything holding a file is left completely alone.
+ */
+export async function pruneEmptyTree(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => null);
+    if (!entries)
+        return;
+    for (const e of entries) {
+        if (e.isDirectory())
+            await pruneEmptyTree(path.join(dir, e.name));
+    }
+    // `["?"]` on failure so an unreadable directory is never mistaken for an
+    // empty one and removed.
+    if ((await fs.readdir(dir).catch(() => ["?"])).length === 0) {
+        await fs.rmdir(dir).catch(() => undefined);
+    }
+}

package/packages/server/dist/transcripts-migration-execute.d.ts

@@ -0,0 +1,144 @@
+import { type TranscriptsMode } from "./transcripts.js";
+import { type MigrationInput, type MigrationState, type MigrationWarning } from "./transcripts-migration.js";
+/**
+ * Why a copy ended up in the preserve dir rather than the host store.
+ *
+ * The design's enum was `["unchecked", "unplanned-diverged"]`, which only
+ * covers the cases where the USER declined a chat. Once the skip-if-present
+ * deadlock was replaced (see the module doc) three more became reachable, and
+ * two of them are about the *host* side — so the item also carries `side`.
+ * Collapsing them all into `unchecked` would tell a user their own terminal
+ * transcript was "not ticked", which is both false and alarming.
+ */
+export type MigrationPreserveReason = 
+/** The user did not tick it. Paddock's copy set aside; the user's survives. */
+"unchecked"
+/** Appeared after the plan was built and classified `diverged`, so its own
+ *  default (unchecked) was applied (§4.6). */
+ | "unplanned-diverged"
+/** Byte-identical on both sides, so no choice was ever offered. Paddock's
+ *  redundant copy is set aside rather than deleted. */
+ | "identical"
+/** Fast-forward with the HOST side ahead: the user's copy is the descendant
+ *  and survives, Paddock's ancestor is set aside. Lossless either way. */
+ | "already-ahead"
+/** The user's copy was superseded by Paddock's and moved out of `~/.claude`
+ *  BEFORE the replacement landed. The recovery path for a decision the user
+ *  regrets. */
+ | "superseded";
+export interface MigrationPreservedChat {
+    /**
+     * The chat id — or, for an agent-memory file set aside by the `memory/`
+     * merge, its path relative to the store (`memory/MEMORY.md`).
+     *
+     * A memory file is not a chat, and it is in this array anyway: this is the
+     * one place the completion screen renders as "here is everything that was
+     * set aside and where it went", and a recovery path with a hole in it is
+     * worse than a slightly loose field name.
+     */
+    sessionId: string;
+    slug: string;
+    /** Which store the preserved copy came out of. */
+    side: "own" | "host";
+    /** Absolute path of the preserved transcript, as actually written. */
+    path: string;
+    reason: MigrationPreserveReason;
+}
+export type MigrationFailureReason = "destination-exists" | "unreadable" | "move-failed" | "preserve-failed" | "unknown";
+export interface MigrationFailure {
+    sessionId: string;
+    slug: string;
+    reason: MigrationFailureReason;
+    message?: string;
+    /** The path the failure is about — disambiguates a project from its sweeper,
+     *  which share a slug. */
+    path?: string;
+}
+export interface MigrationUnplannedChat {
+    sessionId: string;
+    slug: string;
+    state: MigrationState;
+    action: "migrated" | "preserved";
+}
+export type MigrationProjectOutcome = "migrated" | "nothing-to-do" | "skipped-busy" | "failed";
+export interface MigrationProjectResult {
+    slug: string;
+    outcome: MigrationProjectOutcome;
+    migrated: number;
+    preserved: number;
+    /**
+     * Whether `<project.dir>/.chats/` is empty afterwards. FALSE IS A FAILURE:
+     * the redirect symlink will not be planted on restart and the project will be
+     * half-blind (#708). The config is not written while any project reports it.
+     */
+    chatsDirEmpty: boolean;
+    error?: string;
+}
+export interface MigrationExecuteResult {
+    ok: boolean;
+    alreadyMigrated: boolean;
+    dryRun: boolean;
+    projects: MigrationProjectResult[];
+    migrated: string[];
+    preserved: MigrationPreservedChat[];
+    unplanned: MigrationUnplannedChat[];
+    /** Ids in the request that are not in any `.chats/`. Ignored, and named
+     *  rather than silently dropped — the design says they are "reported under
+     *  unknown" and then gives the 200 body nowhere to report them. */
+    ignoredSessionIds: string[];
+    failed: MigrationFailure[];
+    sweepers: {
+        stores: number;
+        chats: number;
+    };
+    /** Carried through from the scan. `memory-collision` in particular is
+     *  REQUIRED by §10.2 and had nowhere to live in the design's 200 body. */
+    warnings: MigrationWarning[];
+    configWritten: boolean;
+    configPath: string;
+    configVersion?: string;
+    restartRequired: boolean;
+}
+export interface MigrationExecuteInput extends MigrationInput {
+    /** The chat ids the user TICKED. Everything else is preserved, not migrated. */
+    sessionIds: string[];
+    /**
+     * Every id the plan the user was looking at contained.
+     *
+     * Without it §4.6 is unimplementable: "a chat created between preview and
+     * submit" and "a chat the user deliberately unticked" are both "present on
+     * disk and absent from `sessionIds`", and nothing in the design's request
+     * body tells them apart. Optional — when omitted, every untricked chat is
+     * treated as a deliberate choice and `unplanned` comes back empty.
+     */
+    plannedSessionIds?: string[];
+    /** Report what WOULD happen; move nothing, write nothing. */
+    dryRun?: boolean;
+    /**
+     * The transcripts mode a RESTART would resolve from the config FILE — NOT
+     * `mode`, which is what this process froze at boot. They differ for the whole
+     * window between a successful migration and the restart it asks for, which is
+     * exactly the window a second POST arrives in.
+     */
+    pendingMode: TranscriptsMode;
+    /**
+     * §4.5's re-check: session ids with a live turn in `slug`, right now.
+     *
+     * `quiesceSession` stops what is running; it does not take a lock, so a fresh
+     * turn can start between the quiesce and this project's own moves. Called
+     * immediately before them, which narrows the window to microseconds without
+     * inventing a fleet-wide turn lock (§10.3 ruled that out of scope for v1).
+     */
+    busySessions?: (slug: string) => string[];
+    /** Write `claude.transcripts: host`; returns the new config fingerprint.
+     *  Called ONCE, LAST, and only when every project reached the postcondition. */
+    commitConfig: () => Promise<string | null>;
+}
+/**
+ * Steps 4–6: re-enumerate from disk, move, and — only if every project reached
+ * the postcondition — write the config.
+ *
+ * Steps 1–3 (single-flight, `expectedVersion`, quiesce) are the caller's; see
+ * the module doc for why.
+ */
+export declare function executeMigration(input: MigrationExecuteInput): Promise<MigrationExecuteResult>;