@cotal-ai/cli 0.50.1 → 0.52.0

package/dist/lib/seat-capture.js

@@ -0,0 +1,195 @@
+/**
+ * Step 7 and 8 of the preservation cut: capture one seat's repository state and harness session
+ * store, then seal a checkpoint over the captured bytes.
+ *
+ * Ordering is the whole point and it is not negotiable. Capture runs only after
+ * `Manager.awaitHandleExit` has proven every child gone (step 6). A capture before that races the
+ * harness by construction: the transcript is still being written and the working tree is still
+ * being edited. Nothing in this file may be called from a path that has not proven the stop.
+ *
+ * The git work shells out to the operator's own git rather than reimplementing bundle and diff
+ * formats, so a self-hoster can verify every artifact by hand with the same commands.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { sessionContinuityClass } from "@cotal-ai/core";
+import { createSeatCheckpointWriter, } from "@cotal-ai/workspace";
+/** The selection rule the untracked set is produced under, recorded in the checkpoint so a
+ *  destination that cannot reproduce it refuses.
+ *
+ *  Two clauses, and the second is not an optimization. `--exclude-standard` honors `.gitignore`,
+ *  so an ignored file the seat actually needs is outside the checkpoint and has to be named
+ *  separately by the operator. The `.cotal/` exclusion is a SECRECY boundary: when a seat's cwd is
+ *  also the mesh root, which is what an operator gets by running `cotal up` and `cotal spawn` in
+ *  one directory, the control directory is untracked and the unfiltered selection pulls
+ *  `auth/broker.json`, the space account, the manager instance identity's private seed and the
+ *  seat's own `.creds` into the artifact. A checkpoint carries credential REFERENCES, never
+ *  values, so the control directory never travels; the destination resolves that material itself. */
+export const UNTRACKED_SELECTION = "git ls-files --others --exclude-standard -z, excluding .cotal/";
+/** The control directory a checkpoint must never carry, relative to the seat's cwd. */
+const CONTROL_DIR = ".cotal/";
+/** Default freshness horizon: 24 hours. A property of the deployment, carried in every record so a
+ *  destination and an operator cannot disagree about what was promised. */
+export const DEFAULT_RECENCY_HORIZON_MS = 24 * 60 * 60 * 1000;
+function git(cwd, args) {
+    return execFileSync("git", args, { cwd, maxBuffer: 1024 * 1024 * 1024 });
+}
+/**
+ * Where one captured session file lands on the destination.
+ *
+ * Anchored, never absolute: the destination has its own workspace root, its own account home and
+ * its own seat working tree, and the source host's spelling for any of them is a path the
+ * destination may not have or may not own. The anchors are tried innermost first, so a file inside
+ * the seat's tree travels with the tree rather than with the root it happens to sit under.
+ * A file under none of them has no destination-relative spelling and the cut refuses, rather than
+ * recording an absolute path a restore would write blind.
+ */
+function restoreDestination(path, what, cwd, workspaceRoot) {
+    const target = resolve(path);
+    const anchors = [
+        ["cwd", cwd],
+        ["workspace-root", workspaceRoot],
+        ["home", homedir()],
+    ];
+    for (const [anchor, base] of anchors) {
+        if (!base)
+            continue;
+        const rel = relative(resolve(base), target);
+        if (rel && !rel.startsWith("..") && !rel.startsWith(sep) && rel !== ".")
+            return { anchor, path: rel.split(sep).join("/") };
+    }
+    throw new Error(`seat checkpoint: ${what} ${target} is under neither the seat's working tree, the workspace root, nor this account's home, so no destination-relative path can be recorded for it`);
+}
+/** Every regular file under one operator-named store path, relative to that path. A store is a
+ *  directory of opaque harness bytes; nothing here parses one. */
+function storeFiles(path) {
+    const root = resolve(path);
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (entry.isFile())
+                found.push(full);
+            else
+                throw new Error(`seat checkpoint: session store entry ${full} is neither a regular file nor a directory`);
+        }
+    };
+    if (!statSync(root).isDirectory())
+        throw new Error(`seat checkpoint: session store ${root} is not a directory`);
+    walk(root);
+    return found;
+}
+/**
+ * Capture and seal. Returns the sealed record. Throws, leaving no checkpoint directory behind,
+ * when anything cannot be captured: a partial checkpoint that looks complete is worse than none.
+ */
+export function captureSeatCheckpoint(destination, entry, request) {
+    const { cwd } = request;
+    const base = git(cwd, ["rev-parse", "HEAD"]).toString("utf8").trim();
+    if (!/^[0-9a-f]{40,64}$/.test(base))
+        throw new Error(`seat checkpoint: ${cwd} did not report a full base object id (got ${JSON.stringify(base)})`);
+    // git writes the bundle and the diffs here first, so the checkpoint writer only ever copies a
+    // finished file and digests what it copied. The parent is the checkpoint destination's own
+    // parent, which the caller may not have created yet on a first cut.
+    const parent = dirname(resolve(destination));
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const staging = mkdtempSync(join(parent, "cotal-seat-capture-"));
+    const writer = createSeatCheckpointWriter(destination);
+    try {
+        const bundlePath = join(staging, "repo.bundle");
+        git(cwd, ["bundle", "create", bundlePath, "--all"]);
+        // Two diffs, not one. A single diff against the base records the difference between that
+        // commit and the worktree without recording which parts were STAGED, so a restore from it
+        // reports every change as unstaged. Base-to-index and index-to-worktree, applied in that
+        // order, reproduce the source's `git status --porcelain`, worktree bytes and staged content
+        // together.
+        const indexDiffPath = join(staging, "repo.index.diff");
+        writeFileSync(indexDiffPath, git(cwd, ["diff", "--binary", "--cached"]));
+        const worktreeDiffPath = join(staging, "repo.worktree.diff");
+        writeFileSync(worktreeDiffPath, git(cwd, ["diff", "--binary"]));
+        // The untracked set has to travel as BYTES. Digesting a `git status` listing would record that
+        // the files exist without recording what is in them.
+        const untrackedPath = join(staging, "repo.untracked.tar");
+        const names = git(cwd, ["ls-files", "--others", "--exclude-standard", "-z"])
+            .toString("utf8").split("\0").filter(Boolean)
+            // Drop the control directory and everything under it: see UNTRACKED_SELECTION.
+            .filter((name) => name !== CONTROL_DIR.slice(0, -1) && !name.startsWith(CONTROL_DIR));
+        const namesFile = join(staging, "untracked.list");
+        writeFileSync(namesFile, names.length ? `${names.join("\0")}\0` : "");
+        execFileSync("tar", ["--null", "--files-from", namesFile, "-cf", untrackedPath], { cwd, maxBuffer: 1024 * 1024 * 1024 });
+        // The status a destination compares its promoted tree against, read under the same selection
+        // rule the untracked set was produced under. `git status --porcelain` reports the control
+        // directory the capture deliberately excludes, so a raw reading would describe a tree these
+        // bytes cannot reproduce and every restore would refuse.
+        const status = git(cwd, ["status", "--porcelain"]).toString("utf8")
+            .split("\n").filter(Boolean)
+            .filter((line) => !(line.startsWith("?? ") && (line.slice(3) === CONTROL_DIR || line.slice(3).startsWith(CONTROL_DIR))))
+            .map((line) => `${line}\n`).join("");
+        const bundle = writer.captureFile("repo.bundle", "bundle", bundlePath);
+        const indexDiff = writer.captureFile("repo.index.diff", "index-diff", indexDiffPath);
+        const worktreeDiff = writer.captureFile("repo.worktree.diff", "worktree-diff", worktreeDiffPath);
+        const untracked = writer.captureFile("repo.untracked.tar", "untracked", untrackedPath);
+        const untrackedSet = new Set(names);
+        // A store file the untracked archive already carries would be captured twice and restored
+        // twice, and the second placement would land on a file the extraction just wrote. Refuse at
+        // the cut rather than produce an artifact whose own restore cannot complete.
+        const destinationFor = (path, what) => {
+            const destination = restoreDestination(path, what, cwd, request.workspaceRoot);
+            if (destination.anchor === "cwd" && untrackedSet.has(destination.path))
+                throw new Error(`seat checkpoint: ${what} ${resolve(path)} is already carried by the untracked capture of ${cwd}; name a store outside the seat's working tree`);
+            return destination;
+        };
+        const pointer = request.sessionStatePath
+            ? writer.captureFile("session-pointer.json", "session-pointer", request.sessionStatePath, destinationFor(request.sessionStatePath, "the connector session pointer"))
+            : undefined;
+        // Each operator-named store path is a directory of opaque harness bytes, captured file by file
+        // so every one travels by size and digest like everything else in the record.
+        const store = [];
+        for (const path of request.sessionStorePaths ?? []) {
+            for (const file of storeFiles(path)) {
+                store.push(writer.captureFile(`session-store.${store.length}`, "session-store", file, destinationFor(file, "a session store file")));
+            }
+        }
+        // What the connector DECLARES, capped by what this cut actually carried. A class is a promise
+        // a destination is entitled to act on, and `exact` or `fork` promises a session the destination
+        // can reopen, which takes BOTH halves: the pointer names the session and the store holds the
+        // transcript it reopens. A pointer alone names a session whose bytes are not in the artifact,
+        // so it is capped exactly like carrying nothing. Capping here keeps the promise answerable to
+        // the artifact rather than to the declaration.
+        const declared = sessionContinuityClass(request.connector ?? {});
+        const carriesSession = pointer !== undefined && store.length > 0;
+        const continuity = !carriesSession && (declared === "exact" || declared === "fork")
+            ? (request.connector?.supportsFreshStart ? "fresh" : "drain-only")
+            : declared;
+        const session = {
+            continuity,
+            ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+            ...(pointer ? { pointer } : {}),
+            store,
+        };
+        return writer.seal({
+            entry,
+            space: request.space,
+            name: request.name,
+            lifecycleUid: request.lifecycleUid,
+            generation: request.generation,
+            capturedAt: new Date().toISOString(),
+            recencyHorizonMs: request.recencyHorizonMs ?? DEFAULT_RECENCY_HORIZON_MS,
+            profile: request.profile,
+            repository: { base, untrackedSelection: UNTRACKED_SELECTION, status, bundle, indexDiff, worktreeDiff, untracked },
+            session,
+        });
+    }
+    catch (error) {
+        writer.cleanup();
+        throw error;
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=seat-capture.js.map

package/dist/lib/seat-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-capture.js","sourceRoot":"","sources":["../../src/lib/seat-capture.ts"],"names":[],"mappings":"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"}

package/dist/lib/seat-restore.d.ts

@@ -0,0 +1,39 @@
+import { type SeatCheckpoint } from "@cotal-ai/workspace";
+/** One admitted seat this restore is about to place, with the destination paths it lands on. */
+export interface SeatRestoreRequest {
+    readonly name: string;
+    /** The directory the checkpoint was read from, re-verified here over the files as they are now. */
+    readonly directory: string;
+    readonly checkpoint: SeatCheckpoint;
+    /** The working tree the manager will launch this seat in, from the retained inventory. */
+    readonly cwd: string;
+    /** The session id the retained inventory says this seat reopens, when it has one. A pointer that
+     *  names a different session is not this seat's pointer. */
+    readonly inventorySessionId?: string;
+}
+export interface SeatRestoreOptions {
+    /** The destination workspace root, the anchor a `workspace-root` destination resolves against. */
+    readonly root: string;
+    readonly seats: readonly SeatRestoreRequest[];
+    /** Reports each promoted seat, so the command can print what it placed. */
+    readonly onPromoted?: (seat: {
+        name: string;
+        cwd: string;
+        superseded?: string;
+    }) => void;
+}
+/** Every refusal below. The message names the seat, the step, and what git or tar actually said. */
+export declare class SeatRestoreError extends Error {
+    constructor(message: string);
+}
+/**
+ * Restore every admitted seat, or leave every live `cwd` as it was.
+ *
+ * Two phases. Every seat is staged first, so a refusal on the last seat costs nothing on the first.
+ * Only once every staging directory is complete does any promotion happen, and a failure during the
+ * promotion phase puts back what this call moved: the renames it made are undone in reverse and the
+ * session files it exclusively created are removed, so the destination is where it started and the
+ * whole set can be retried once the refusal is understood.
+ */
+export declare function restoreSeatCheckpoints(options: SeatRestoreOptions): void;
+//# sourceMappingURL=seat-restore.d.ts.map

package/dist/lib/seat-restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-restore.d.ts","sourceRoot":"","sources":["../../src/lib/seat-restore.ts"],"names":[],"mappings":"AAoCA,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,qBAAqB,CAAC;AAE7B,gGAAgG;AAChG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,0FAA0F;IAC1F,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;gEAC4D;IAC5D,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,kBAAkB;IACjC,kGAAkG;IAClG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC9C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1F;AAED,oGAAoG;AACpG,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AA4JD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA+BxE"}

package/dist/lib/seat-restore.js

@@ -0,0 +1,249 @@
+/**
+ * Restore: the destination consumes an admitted seat checkpoint before the seat is alive.
+ *
+ * This is section 6 step 7 of `docs/design/session-recovery.md`, which that record gives as a shell
+ * sequence and calls manual only because no command carried it. Every rule stated there is a rule
+ * here, and the reasons are the same ones measured there:
+ *
+ * - The sequence stages. A clone lands in `<cwd>.incoming`, every verification and both applies run
+ *   inside it, and the two renames that promote it are the only steps that touch the path the seat
+ *   will use. A failed restore leaves the live `cwd` as it was.
+ * - An existing `<cwd>.incoming` refuses. A staging directory from a failed run is the only record
+ *   of what failed, so nothing here removes one: an operator inspects it and removes it by hand.
+ *   The shell version's `set -e` exists because a bare test reported and continued, and the final
+ *   `mv` then promoted a leftover directory that was never restored. Here every step throws.
+ * - `git clone` rather than a fetch into an existing repository, because the refspec form that
+ *   would populate it fails against the branch HEAD is on, and clone avoids the question.
+ * - The recorded base is verified in the clone. A bundle that does not contain it does not apply to
+ *   the tree this checkpoint describes.
+ * - Two applies, `--index` first and the worktree diff second, both `--binary --allow-empty`. The
+ *   order is what puts staged content back in the index rather than only in the worktree, and
+ *   `--allow-empty` is why the cleanest possible seat is still restorable.
+ * - A pre-existing `cwd` is moved aside under a timestamped name rather than deleted, so a wrong
+ *   checkpoint costs a rename instead of a tree.
+ *
+ * Two things this adds over the manual sequence. The session files travel with the tree, to the
+ * paths the destination's own connector will read. And the promoted tree is re-read with
+ * `git status --porcelain` and compared to what the checkpoint recorded, so a restore that applied
+ * without error and still produced a different index is a refusal rather than a silent difference.
+ *
+ * git and tar run as child processes through `execFileSync`, never a shell string.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { assertSeatCheckpointIntegrity, } from "@cotal-ai/workspace";
+/** Every refusal below. The message names the seat, the step, and what git or tar actually said. */
+export class SeatRestoreError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SeatRestoreError";
+    }
+}
+function run(command, args, cwd, seat, step) {
+    try {
+        // Both streams are captured. git writes progress and advice to stderr even when it succeeds,
+        // and the default here would forward that to the operator's terminal as if the resume had
+        // failed; on a failure the same bytes are what the refusal has to name.
+        return execFileSync(command, args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            maxBuffer: 1024 * 1024 * 1024,
+        });
+    }
+    catch (error) {
+        const failure = error;
+        const output = `${failure.stderr ?? ""}${failure.stdout ?? ""}`.trim() || failure.message || "no output";
+        throw new SeatRestoreError(`seat ${seat}: ${step} failed (${command}): ${output}`);
+    }
+}
+/**
+ * Where one captured session file lands on THIS host.
+ *
+ * The anchors are the destination's own: its workspace root, the account home it runs under, and
+ * the seat's working tree. The record carries a relative path and the reader already refused an
+ * absolute one or a `..` segment, so the result cannot leave the anchor it names.
+ */
+function destinationPath(destination, root, cwd) {
+    const anchor = destination.anchor === "workspace-root" ? root : destination.anchor === "home" ? homedir() : cwd;
+    return join(anchor, destination.path);
+}
+/**
+ * Write one captured session file where the connector will read it.
+ *
+ * Durable, private and exclusive. A file already at that path is judged by CONTENT, which is the
+ * same rule the rest of the checkpoint is judged by: a destination whose file already hashes to the
+ * recorded digest holds the bytes this step exists to place, and that is the ordinary same-host
+ * resume, where nothing removed the transcript the seat was writing. Different bytes under the path
+ * the connector is about to read are a different session, and that is refused rather than
+ * clobbered: the harness transcript is the one thing here Cotal cannot reconstruct.
+ */
+function placeSessionFile(seat, file, root, created) {
+    const path = destinationPath(file.restore, root, seat.cwd);
+    const bytes = readFileSync(join(seat.directory, file.path));
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    let fd;
+    try {
+        fd = openSync(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            const present = createHash("sha256").update(readFileSync(path)).digest("hex");
+            if (present === file.sha256)
+                return;
+            throw new SeatRestoreError(`seat ${seat.name}: ${path} already holds different bytes than the checkpoint recorded (${present} against ${file.sha256}); inspect it and move it aside before resuming`);
+        }
+        throw error;
+    }
+    created.push(path);
+    try {
+        writeSync(fd, bytes);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/** The sha256-verified pointer's own session id, refused when it is not the one this seat reopens. */
+function assertPointerSession(seat, pointer) {
+    const recorded = seat.checkpoint.session.sessionId ?? seat.inventorySessionId;
+    if (!recorded)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(join(seat.directory, pointer.path), "utf8"));
+    }
+    catch (error) {
+        throw new SeatRestoreError(`seat ${seat.name}: captured session pointer is not readable JSON (${error.message})`);
+    }
+    if (typeof parsed.sessionId !== "string" || parsed.sessionId !== recorded)
+        throw new SeatRestoreError(`seat ${seat.name}: captured session pointer names session ${JSON.stringify(parsed.sessionId)}, this resume reopens ${JSON.stringify(recorded)}`);
+    if (seat.inventorySessionId && seat.checkpoint.session.sessionId && seat.inventorySessionId !== seat.checkpoint.session.sessionId)
+        throw new SeatRestoreError(`seat ${seat.name}: checkpoint records session ${seat.checkpoint.session.sessionId}, the retained inventory says ${seat.inventorySessionId}`);
+}
+/** Stage one seat: everything up to and including the extraction, inside `<cwd>.incoming` alone. */
+function stageSeat(seat, staging) {
+    // THE ONE TREE A PROMOTION MAY NOT REPLACE.
+    //
+    // A checkpoint deliberately excludes the control directory (see `UNTRACKED_SELECTION`): it holds
+    // the broker trust material, the space account, the seat's own credentials and the maintenance
+    // journal this very resume is reading, and a checkpoint carries credential references rather than
+    // values. Promotion replaces the whole `cwd`, so when the seat's `cwd` IS a workspace root, which
+    // is the ordinary layout an operator gets by running `cotal up` and `cotal spawn` in one
+    // directory, promoting a clone that cannot contain `.cotal/` moves the live control directory
+    // aside and leaves the destination with none.
+    //
+    // Moving the control directory across the promotion is not the answer: its contents are live
+    // while this command runs. So this refuses, and names the remedy rather than degrading.
+    const control = join(resolve(seat.cwd), ".cotal");
+    if (existsSync(control))
+        throw new SeatRestoreError(`seat ${seat.name}: ${resolve(seat.cwd)} holds a control directory at ${control}, and a checkpoint never carries one, so promoting the restored tree over it would move this destination's live trust material and maintenance state aside; give the seat a working tree that is not a workspace root, then resume`);
+    // The digests again, over the files as they are NOW. Gate 1 ran before custody moved; a
+    // checkpoint that changed between the gate and the bytes being applied is not the admitted one.
+    try {
+        assertSeatCheckpointIntegrity(seat.directory, seat.checkpoint);
+    }
+    catch (error) {
+        throw new SeatRestoreError(`seat ${seat.name}: re-verifying the checkpoint before restore failed: ${error.message}`);
+    }
+    // Before the clone, because this decides nothing about the tree and therefore should cost
+    // nothing: a pointer that names another session leaves no staging directory to inspect for a
+    // step that never ran.
+    if (seat.checkpoint.session.pointer)
+        assertPointerSession(seat, seat.checkpoint.session.pointer);
+    // A leftover staging directory is evidence of a failed run, never a tree to promote, and nothing
+    // here removes it.
+    if (existsSync(staging))
+        throw new SeatRestoreError(`seat ${seat.name}: ${staging} already exists; a staging directory from a failed restore is evidence - inspect it and remove it by hand, then resume`);
+    const parent = dirname(staging);
+    mkdirSync(parent, { recursive: true });
+    const repository = seat.checkpoint.repository;
+    run("git", ["clone", "--quiet", join(seat.directory, repository.bundle.path), staging], parent, seat.name, "cloning the bundle");
+    run("git", ["rev-parse", "--verify", `${repository.base}^{commit}`], staging, seat.name, `verifying the recorded base ${repository.base}`);
+    run("git", ["checkout", "--quiet", "--detach", repository.base], staging, seat.name, "checking out the recorded base");
+    run("git", ["apply", "--binary", "--allow-empty", "--index", join(seat.directory, repository.indexDiff.path)], staging, seat.name, "applying the index diff");
+    run("git", ["apply", "--binary", "--allow-empty", join(seat.directory, repository.worktreeDiff.path)], staging, seat.name, "applying the worktree diff");
+    run("tar", ["-xf", join(seat.directory, repository.untracked.path)], staging, seat.name, "extracting the untracked archive");
+}
+/**
+ * Move an existing `cwd` aside under a timestamped name, and return the name it went to.
+ *
+ * The name has to be one this call can prove it owns. A whole-second timestamp is not that: two
+ * promotions of the same seat inside one second compute the same path, and the second `rename`
+ * lands on the non-empty directory the first one just created. A refusal naming a rename instead
+ * of the real cause is not acceptable for the one step that exists to keep a superseded tree.
+ *
+ * So the rename IS the claim. Nothing creates the timestamped name ahead of the move: an
+ * exclusive `mkdir` first and a rename onto that empty directory is the replace POSIX allows, but
+ * Windows refuses to rename onto any existing directory (EPERM), so a claim made that way can never
+ * be redeemed there. Renaming onto a name that already holds a tree fails on every platform
+ * (ENOTEMPTY or EEXIST on POSIX, EPERM on Windows), and that failure is read as "taken" and retried
+ * with a counter. A rename that fails for any other reason is the error it is.
+ */
+function supersede(cwd, seat) {
+    const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+    for (let attempt = 0; attempt < 100; attempt++) {
+        const candidate = `${cwd}.superseded.${stamp}${attempt ? `.${attempt}` : ""}`;
+        try {
+            renameSync(cwd, candidate);
+            return candidate;
+        }
+        catch (error) {
+            const code = error.code;
+            if ((code === "ENOTEMPTY" || code === "EEXIST" || code === "EPERM") && existsSync(candidate))
+                continue;
+            throw error;
+        }
+    }
+    throw new SeatRestoreError(`seat ${seat}: could not claim a free superseded name beside ${cwd}; ${cwd}.superseded.${stamp}[.0-99] are all taken, so an earlier tree would be overwritten`);
+}
+/**
+ * Restore every admitted seat, or leave every live `cwd` as it was.
+ *
+ * Two phases. Every seat is staged first, so a refusal on the last seat costs nothing on the first.
+ * Only once every staging directory is complete does any promotion happen, and a failure during the
+ * promotion phase puts back what this call moved: the renames it made are undone in reverse and the
+ * session files it exclusively created are removed, so the destination is where it started and the
+ * whole set can be retried once the refusal is understood.
+ */
+export function restoreSeatCheckpoints(options) {
+    const staged = options.seats.map((seat) => ({ seat, staging: `${resolve(seat.cwd)}.incoming` }));
+    for (const { seat, staging } of staged)
+        stageSeat(seat, staging);
+    const promoted = [];
+    const created = [];
+    try {
+        for (const { seat, staging } of staged) {
+            const cwd = resolve(seat.cwd);
+            const superseded = existsSync(cwd) ? supersede(cwd, seat.name) : undefined;
+            renameSync(staging, cwd);
+            promoted.push({ cwd, staging, ...(superseded ? { superseded } : {}) });
+            // Before the status is read, for the same reason the capture read it with the store in place:
+            // a store file inside the tree is part of the state the checkpoint recorded.
+            if (seat.checkpoint.session.pointer)
+                placeSessionFile(seat, seat.checkpoint.session.pointer, options.root, created);
+            for (const file of seat.checkpoint.session.store)
+                placeSessionFile(seat, file, options.root, created);
+            // The bytes landed and git accepted them; this is the only check that sees a restore which
+            // applied cleanly and still produced a different index.
+            const status = run("git", ["status", "--porcelain"], cwd, seat.name, "re-reading the restored working tree status");
+            if (status !== seat.checkpoint.repository.status)
+                throw new SeatRestoreError(`seat ${seat.name}: the restored tree reports a different status than the checkpoint recorded\n  recorded: ${JSON.stringify(seat.checkpoint.repository.status)}\n  restored: ${JSON.stringify(status)}`);
+            options.onPromoted?.({ name: seat.name, cwd, ...(superseded ? { superseded } : {}) });
+        }
+    }
+    catch (error) {
+        for (const path of created.reverse())
+            rmSync(path, { force: true });
+        for (const entry of promoted.reverse()) {
+            renameSync(entry.cwd, entry.staging);
+            if (entry.superseded)
+                renameSync(entry.superseded, entry.cwd);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=seat-restore.js.map

package/dist/lib/seat-restore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-restore.js","sourceRoot":"","sources":["../../src/lib/seat-restore.ts"],"names":[],"mappings":"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"}

package/dist/lib/seat-resume.d.ts

@@ -0,0 +1,24 @@
+/** One stale checkpoint the operator deliberately admitted, for the resume journal. */
+export interface StaleCheckpointConsent {
+    readonly name: string;
+    readonly capturedAt: string;
+    readonly ageMs: number;
+    readonly horizonMs: number;
+}
+/**
+ * Run section 2.2's gates over every seat checkpoint the cut wrote, restore the captured bytes,
+ * then take custody of each seat.
+ *
+ * Gate 2 is told which lifecycle uids are live. On these paths that set is empty and the reason is
+ * structural rather than an omission: a preserved resume is only reached from a `ready` journal,
+ * which `down --preserve-state` publishes after it has proven every recorded process stopped and
+ * the exact recorded endpoint unreachable. There is no roster to consult because there is no
+ * broker. A destination that resumes against a live space supplies the roster instead.
+ *
+ * The restore runs inside the admission, after every gate and before any generation is claimed, so
+ * a refusal costs nothing: no tree has been promoted, no claim has been made, nothing has started.
+ */
+export declare function admitAndRestoreSeatCheckpoints(root: string, space: string, attemptId: string, values: {
+    "accept-stale-checkpoint"?: boolean;
+}, inventory: unknown): StaleCheckpointConsent[];
+//# sourceMappingURL=seat-resume.d.ts.map

package/dist/lib/seat-resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seat-resume.d.ts","sourceRoot":"","sources":["../../src/lib/seat-resume.ts"],"names":[],"mappings":"AAyBA,uFAAuF;AACvF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AASD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE;IAAE,yBAAyB,CAAC,EAAE,OAAO,CAAA;CAAE,EAC/C,SAAS,EAAE,OAAO,GACjB,sBAAsB,EAAE,CAuF1B"}