@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/project-migration/containment.d.ts

@@ -0,0 +1,52 @@
+import type { ProjectMigrationJournal } from './journal.ts';
+/**
+ * What a project migration journal may name (hearsay-tools/cezarion#3089). A journal is read back
+ * from disk before a resume, so it is untrusted input: every path it names is checked before any
+ * step runs, and each step checks its write target again right before it writes.
+ *
+ * - `source` and `destination` are exactly `<root>/.ai/cezar` and `<root>/.ai/squawk`, and
+ *   `<root>/.ai` is a real directory.
+ * - A move goes from inside `source` to the same place inside `destination`; so does a worktree.
+ * - A receipt or cleanup checkpoint lies in `<git common dir>/cezar-owned-workspaces/`; every other
+ *   rewritten file lies in `<destination>/runs/`.
+ * - A rewritten value moves a path from a form of the project root's `.ai/cezar` to the same place
+ *   under `.ai/squawk`; a tracked file is a relative `.ai/cezar/...` path printed as a `git mv`.
+ * - No existing directory on the way to a checked path resolves elsewhere (a symlink out), and a
+ *   file the engine opens or rewrites in place (the run store and its `-wal` and `-shm`, each
+ *   rewritten JSON file, each receipt) is a regular file, never a symlink. A moved item may be a
+ *   symlink: a rename moves the link itself.
+ * - The journal file itself is a regular file of at most `MAX_JOURNAL_BYTES` that Git does not
+ *   track (the shared excludes keep it out of every ordinary add), checked before it is read.
+ */
+export declare class ProjectMigrationJournalRefusedError extends Error {
+    readonly journal: string;
+    constructor(journal: string, detail: string);
+}
+/**
+ * Why `path` may not be written as part of `root`: not a normalized absolute path, outside `root`
+ * by its letters, or an existing directory on its way (from `root` down) that resolves elsewhere.
+ * Undefined when it may. The last component itself is not followed: a move renames a link, and a
+ * rewrite replaces a file by rename.
+ */
+export declare function outsideOf(root: string, path: string): string | undefined;
+/** Why `path`, when it exists, may not be opened or rewritten in place: it is a symlink or not a file. */
+export declare function notRegularFile(path: string): string | undefined;
+/** The run store the run-store step opens, and the sidecars SQLite opens with it. */
+export declare function runStoreFiles(directory: string): string[];
+/**
+ * The largest journal a resume reads. A journal holds the plan, a few hundred bytes per path
+ * rewrite: 100,000 runs with several rewritten fields each stay well under it. Anything larger
+ * is not a journal this engine wrote.
+ */
+export declare const MAX_JOURNAL_BYTES: number;
+/**
+ * Accept the journal file at `path` before it is read: false when there is none; refused when it
+ * is a symlink or not a regular file, larger than `MAX_JOURNAL_BYTES`, tracked by Git (only a
+ * forced add or a clone tracks it; one Git call, only when a journal exists), or when that Git
+ * check cannot finish. Nothing is read.
+ */
+export declare function assertJournalFile(path: string, repoRoot: string): Promise<boolean>;
+/** The repository's receipt directory, where receipt and cleanup checkpoint rewrites must lie. */
+export declare function receiptDirectory(repoRoot: string): Promise<string>;
+/** Refuse `journal` before any step when it names anything outside the project's own state. */
+export declare function assertJournalContained(path: string, journal: ProjectMigrationJournal): Promise<void>;

package/dist/project-migration/containment.js

@@ -0,0 +1,200 @@
+import { execFile } from 'node:child_process';
+import { lstatSync, realpathSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { gitCommonDir } from '../delegation/workspace.js';
+import { MIGRATION_JOURNAL_FILE } from '../server/cockpit-ownership.js';
+import { pathPresent } from '../project-paths.js';
+import { RUNS_DB_FILE } from '../runs/run-database.js';
+/**
+ * What a project migration journal may name (hearsay-tools/cezarion#3089). A journal is read back
+ * from disk before a resume, so it is untrusted input: every path it names is checked before any
+ * step runs, and each step checks its write target again right before it writes.
+ *
+ * - `source` and `destination` are exactly `<root>/.ai/cezar` and `<root>/.ai/squawk`, and
+ *   `<root>/.ai` is a real directory.
+ * - A move goes from inside `source` to the same place inside `destination`; so does a worktree.
+ * - A receipt or cleanup checkpoint lies in `<git common dir>/cezar-owned-workspaces/`; every other
+ *   rewritten file lies in `<destination>/runs/`.
+ * - A rewritten value moves a path from a form of the project root's `.ai/cezar` to the same place
+ *   under `.ai/squawk`; a tracked file is a relative `.ai/cezar/...` path printed as a `git mv`.
+ * - No existing directory on the way to a checked path resolves elsewhere (a symlink out), and a
+ *   file the engine opens or rewrites in place (the run store and its `-wal` and `-shm`, each
+ *   rewritten JSON file, each receipt) is a regular file, never a symlink. A moved item may be a
+ *   symlink: a rename moves the link itself.
+ * - The journal file itself is a regular file of at most `MAX_JOURNAL_BYTES` that Git does not
+ *   track (the shared excludes keep it out of every ordinary add), checked before it is read.
+ */
+export class ProjectMigrationJournalRefusedError extends Error {
+    journal;
+    constructor(journal, detail) {
+        super(`The project migration journal ${journal} is refused: ${detail}. Nothing was changed. `
+            + 'The journal stays for inspection; remove it only if no migration of this project ran');
+        this.journal = journal;
+        this.name = 'ProjectMigrationJournalRefusedError';
+    }
+}
+function within(parent, path) {
+    const inside = relative(parent, path);
+    return inside === '' || (!isAbsolute(inside) && inside !== '..' && !inside.startsWith(`..${sep}`));
+}
+/**
+ * Why `path` may not be written as part of `root`: not a normalized absolute path, outside `root`
+ * by its letters, or an existing directory on its way (from `root` down) that resolves elsewhere.
+ * Undefined when it may. The last component itself is not followed: a move renames a link, and a
+ * rewrite replaces a file by rename.
+ */
+export function outsideOf(root, path) {
+    if (!isAbsolute(path) || resolve(path) !== path)
+        return `${path} is not a normalized absolute path`;
+    if (path === root || !within(root, path))
+        return `${path} is not inside ${root}`;
+    let existing = dirname(path);
+    while (!pathPresent(existing) && existing !== dirname(existing))
+        existing = dirname(existing);
+    try {
+        if (realpathSync(existing) !== existing)
+            return `${existing} resolves to ${realpathSync(existing)}, outside the project`;
+    }
+    catch (error) {
+        return `${existing} cannot be resolved: ${error.message}`;
+    }
+    return undefined;
+}
+/** Why `path`, when it exists, may not be opened or rewritten in place: it is a symlink or not a file. */
+export function notRegularFile(path) {
+    if (!pathPresent(path))
+        return undefined;
+    const info = lstatSync(path);
+    return info.isSymbolicLink() ? `${path} is a symbolic link` : info.isFile() ? undefined : `${path} is not a regular file`;
+}
+/** The run store the run-store step opens, and the sidecars SQLite opens with it. */
+export function runStoreFiles(directory) {
+    const database = join(directory, RUNS_DB_FILE);
+    return [database, `${database}-wal`, `${database}-shm`];
+}
+/** `path` inside `from`, carried to the same place inside `to`. */
+function carried(from, to, path) {
+    return outsideOf(from, path.from) ?? outsideOf(to, path.to)
+        ?? (path.to === to + path.from.slice(from.length) ? undefined : `${path.to} is not where ${path.from} goes`);
+}
+const execFileAsync = promisify(execFile);
+const LEGACY = `${sep}.ai${sep}cezar`;
+const MIGRATED = `${sep}.ai${sep}squawk`;
+/** A stored value: under some form of the project root's `.ai/cezar`, mapped to the same place under `.ai/squawk`. */
+function valueMoved(repoRoot, real, value) {
+    for (let at = value.from.indexOf(LEGACY); at > 0; at = value.from.indexOf(LEGACY, at + 1)) {
+        const rest = value.from.slice(at + LEGACY.length);
+        if (rest !== '' && !rest.startsWith(sep))
+            continue;
+        const prefix = value.from.slice(0, at);
+        if (real(prefix) === repoRoot && value.to === prefix + MIGRATED + rest)
+            return undefined;
+    }
+    return `the value ${value.from} -> ${value.to} does not move a path of this project from .ai/cezar to .ai/squawk`;
+}
+/** A tracked file: relative, `.ai/cezar/...` to the same `.ai/squawk/...`, no `..`. */
+function trackedMoved(file) {
+    const parts = file.from.split('/');
+    const ok = parts.length > 2 && parts[0] === '.ai' && parts[1] === 'cezar' && !parts.some(part => part === '' || part === '.' || part === '..')
+        && !file.from.includes('\\') && file.to === `.ai/squawk/${parts.slice(2).join('/')}`;
+    return ok ? undefined : `the tracked file ${file.from} -> ${file.to} is not a path under .ai/cezar`;
+}
+/** The first refusal `check` gives for any of `items`. */
+function firstRefusal(items, check) {
+    for (const item of items) {
+        const refusal = check(item);
+        if (refusal)
+            return refusal;
+    }
+    return undefined;
+}
+/** The directories, moves, worktrees and tracked files of `journal`. */
+function layoutRefusal(journal) {
+    const ai = join(journal.repoRoot, '.ai');
+    if (journal.source !== join(ai, 'cezar') || journal.destination !== join(ai, 'squawk'))
+        return `its directories are not ${join(ai, 'cezar')} and ${join(ai, 'squawk')}`;
+    // `<root>/.ai` itself must be a real directory of the root.
+    return outsideOf(journal.repoRoot, journal.source)
+        ?? firstRefusal([...journal.moves, ...journal.worktrees], item => carried(journal.source, journal.destination, item))
+        ?? firstRefusal(journal.tracked, trackedMoved);
+}
+/** Every rewrite of `journal`: the file it rewrites in place, the run store it opens, the value it moves. */
+async function rewritesRefusal(journal) {
+    const isReceipt = (rewrite) => rewrite.kind === 'receipt' || rewrite.kind === 'cleanup-checkpoint';
+    const receipts = journal.rewrites.some(isReceipt) ? await receiptDirectory(journal.repoRoot) : undefined;
+    const runs = join(journal.destination, 'runs');
+    const reals = new Map();
+    const real = (prefix) => {
+        if (!reals.has(prefix)) {
+            try {
+                reals.set(prefix, realpathSync(prefix));
+            }
+            catch {
+                reals.set(prefix, undefined);
+            }
+        }
+        return reals.get(prefix);
+    };
+    // The run store the run-store step opens: before the move it is the source's, after it the destination's.
+    const stores = journal.rewrites.some(rewrite => rewrite.kind === 'run-row') ? [...runStoreFiles(journal.source), ...runStoreFiles(journal.destination)] : [];
+    const fileRefusal = (rewrite) => {
+        if (!('file' in rewrite))
+            return undefined;
+        return outsideOf(isReceipt(rewrite) ? receipts : runs, rewrite.file) ?? notRegularFile(rewrite.file);
+    };
+    return firstRefusal(journal.rewrites, (rewrite) => { return fileRefusal(rewrite) ?? valueMoved(journal.repoRoot, real, rewrite); })
+        ?? firstRefusal(stores, notRegularFile);
+}
+/** The first reason `journal` may not run, checked before any step; undefined when it may. */
+async function journalRefusal(path, journal) {
+    return layoutRefusal(journal) ?? await rewritesRefusal(journal);
+}
+/**
+ * The largest journal a resume reads. A journal holds the plan, a few hundred bytes per path
+ * rewrite: 100,000 runs with several rewritten fields each stay well under it. Anything larger
+ * is not a journal this engine wrote.
+ */
+export const MAX_JOURNAL_BYTES = 64 * 1024 * 1024;
+/**
+ * Why Git tracking refuses the journal of the project at `repoRoot` (a real path): tracked, or the
+ * check could not finish. A directory outside any Git repository tracks nothing. The pathspec is
+ * the journal's canonical place, whatever form the caller's path has.
+ */
+async function trackedJournalRefusal(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['ls-files', '-z', '--', `.ai/${MIGRATION_JOURNAL_FILE}`], { cwd: repoRoot, encoding: 'utf8', timeout: 60_000 });
+        return stdout ? 'Git tracks it; a migration journal is never committed' : undefined;
+    }
+    catch (error) {
+        if (/not a git repository/i.test(String(error.stderr ?? '')))
+            return undefined;
+        return `Git could not tell whether it tracks the journal: ${error.message.split('\n')[0]}`;
+    }
+}
+/**
+ * Accept the journal file at `path` before it is read: false when there is none; refused when it
+ * is a symlink or not a regular file, larger than `MAX_JOURNAL_BYTES`, tracked by Git (only a
+ * forced add or a clone tracks it; one Git call, only when a journal exists), or when that Git
+ * check cannot finish. Nothing is read.
+ */
+export async function assertJournalFile(path, repoRoot) {
+    if (!pathPresent(path))
+        return false;
+    const refusal = notRegularFile(path) ?? (lstatSync(path).size > MAX_JOURNAL_BYTES ? `it is larger than ${MAX_JOURNAL_BYTES} bytes` : undefined)
+        ?? await trackedJournalRefusal(repoRoot);
+    if (refusal)
+        throw new ProjectMigrationJournalRefusedError(path, refusal);
+    return true;
+}
+/** The repository's receipt directory, where receipt and cleanup checkpoint rewrites must lie. */
+export async function receiptDirectory(repoRoot) {
+    return join(await gitCommonDir(repoRoot), 'cezar-owned-workspaces');
+}
+/** Refuse `journal` before any step when it names anything outside the project's own state. */
+export async function assertJournalContained(path, journal) {
+    const refusal = await journalRefusal(path, journal);
+    if (refusal)
+        throw new ProjectMigrationJournalRefusedError(path, refusal);
+}
+//# sourceMappingURL=containment.js.map

package/dist/project-migration/containment.js.map

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

package/dist/project-migration/durable.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The migration's durability invariant, enforced by `settle` alone:
+ *
+ * (a) After every effect on an entry (created, renamed in or out, rewritten or removed, by the
+ *     engine or by Git or SQLite on its behalf), the entry's data when it is a file that was
+ *     written, then every directory from its base root down to its parent, are fsynced. This runs
+ *     on the first run and on every resume, whether the effect happened now or before a crash.
+ * (b) Each step calls `settle` right after the effect and before anything that depends on it: the
+ *     next item, a worktree unlock, the step's done mark, the journal's removal.
+ *
+ * So a power loss never keeps a later action, or the done mark, while losing the effect it
+ * depended on. One object, so tests observe each call.
+ */
+export declare const durable: {
+    directory(path: string): void;
+    file(path: string): void;
+};
+/** `root` and every directory below it down to `path`. */
+export declare function directoriesDown(root: string, path: string): string[];
+/** Rule (a) for one entry: its data when `data` and it exists, then each directory from `root` down to its parent. */
+export declare function settle(root: string, entry: string, options?: {
+    data?: boolean;
+}): void;
+/** Atomic replacement with exact permission bits: temp file, fsync, rename. The caller settles it. */
+export declare function replaceAtomically(path: string, content: string, mode: number): void;

package/dist/project-migration/durable.js

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, fchmodSync, fsyncSync, openSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, sep } from 'node:path';
+import { syncDirectory } from '../home/private-files.js';
+import { pathPresent } from '../project-paths.js';
+/**
+ * The migration's durability invariant, enforced by `settle` alone:
+ *
+ * (a) After every effect on an entry (created, renamed in or out, rewritten or removed, by the
+ *     engine or by Git or SQLite on its behalf), the entry's data when it is a file that was
+ *     written, then every directory from its base root down to its parent, are fsynced. This runs
+ *     on the first run and on every resume, whether the effect happened now or before a crash.
+ * (b) Each step calls `settle` right after the effect and before anything that depends on it: the
+ *     next item, a worktree unlock, the step's done mark, the journal's removal.
+ *
+ * So a power loss never keeps a later action, or the done mark, while losing the effect it
+ * depended on. One object, so tests observe each call.
+ */
+export const durable = {
+    directory(path) { syncDirectory(path); },
+    file(path) {
+        // Windows opens no handle that FlushFileBuffers accepts read-only; its renames are write-through.
+        if (process.platform === 'win32')
+            return;
+        const fd = openSync(path, 'r');
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    },
+};
+/** `root` and every directory below it down to `path`. */
+export function directoriesDown(root, path) {
+    if (path !== root && !path.startsWith(root + sep))
+        throw new Error(`${path} is not inside ${root}`);
+    const directories = [root];
+    for (const part of path === root ? [] : path.slice(root.length + 1).split(sep))
+        directories.push(join(directories.at(-1), part));
+    return directories;
+}
+/** Rule (a) for one entry: its data when `data` and it exists, then each directory from `root` down to its parent. */
+export function settle(root, entry, options = {}) {
+    if (options.data && pathPresent(entry))
+        durable.file(entry);
+    for (const directory of directoriesDown(root, dirname(entry)))
+        durable.directory(directory);
+}
+/** Atomic replacement with exact permission bits: temp file, fsync, rename. The caller settles it. */
+export function replaceAtomically(path, content, mode) {
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    const fd = openSync(temporary, 'wx', mode);
+    try {
+        try {
+            fchmodSync(fd, mode);
+            writeFileSync(fd, content);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=durable.js.map

package/dist/project-migration/durable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable.js","sourceRoot":"","sources":["../../src/project-migration/durable.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACxG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG;IACrB,SAAS,CAAC,IAAY,IAAU,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACtD,IAAI,CAAC,IAAY;QACf,kGAAkG;QAClG,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO;QACzC,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC;YAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAAC,CAAC;gBAAS,CAAC;YAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAAC,CAAC;IACnD,CAAC;CACF,CAAC;AAEF,0DAA0D;AAC1D,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAY;IACxD,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,kBAAkB,IAAI,EAAE,CAAC,CAAC;IACpG,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,EAAE,IAAI,CAAC,CAAC,CAAC;IAClI,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,sHAAsH;AACtH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,KAAa,EAAE,OAAO,GAAuB,EAAE;IAClF,IAAI,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,KAAK,MAAM,SAAS,IAAI,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;AAC9F,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAe,EAAE,IAAY;IAC3E,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,UAAU,EAAE,MAAM,CAAC;IAChD,MAAM,EAAE,GAAG,QAAQ,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3C,IAAI,CAAC;QACH,IAAI,CAAC;YAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;YAAC,aAAa,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;YAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAAC,CAAC;gBAAS,CAAC;YAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAAC,CAAC;QACnG,UAAU,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;YAAS,CAAC;QAAC,MAAM,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAAC,CAAC;AACnD,CAAC"}

package/dist/project-migration/engine.d.ts

@@ -0,0 +1,47 @@
+import { type ProjectMigrationFence } from '../server/cockpit-ownership.ts';
+import { type ProjectMigrationJournal } from './journal.ts';
+import { type ProjectMigrationPlan } from './plan.ts';
+import { type MigrationFault } from './steps.ts';
+/**
+ * The project state migration engine (P4b2, hearsay-tools/cezarion#3088): it moves a project's
+ * runtime state from `.ai/cezar/` to `.ai/squawk/` under the exclusive project fence. A migration
+ * runs offline (hearsay-tools/cezarion#3089): no cockpit serves the project and no task is live.
+ *
+ * Order: the caller takes the fence (`fenceProject`); the engine checks that this process holds
+ * it, runs as its holder (`asFenceHolder`), closes the store the caller opened (`closeProject`),
+ * plans, writes the journal, runs each step and marks it done, and removes the journal last. The
+ * caller releases the fence afterwards, also after a failure: the journal then keeps the project
+ * blocked until a resume completes it.
+ */
+export interface ProjectMigrationOptions {
+    /** The project root, in the form the project is registered with. */
+    repoRoot: string;
+    /** The fence this process holds for the project. */
+    fence: ProjectMigrationFence;
+    /** Test seam: called at each fault point; throwing there stops the migration as a crash would. */
+    fault?: MigrationFault;
+}
+export interface ProjectMigrationResult {
+    /** The journal as completed (removed from disk). */
+    journal: ProjectMigrationJournal;
+    /** Whether an unfinished journal was completed rather than a new plan run. */
+    resumed: boolean;
+    /** Commands that move the tracked files the migration left in place, for the user to commit. */
+    gitMv: string[];
+    /** A completed migration had marked the project moved: nothing was written, no journal either. */
+    alreadyMoved: boolean;
+}
+/** The plan had conflicts or blockers: nothing was written and no journal exists. */
+export declare class ProjectMigrationRefusedError extends Error {
+    readonly plan: ProjectMigrationPlan;
+    constructor(plan: ProjectMigrationPlan);
+}
+/** Complete an unfinished journal, for P4b3's recovery before any project read; undefined without one. */
+export declare function resumeProjectMigration(options: ProjectMigrationOptions): Promise<ProjectMigrationResult | undefined>;
+/**
+ * Migrate the project, or finish its unfinished journal first. `closeProject` runs before the
+ * plan: the CLI closes the store it opened for its live-task check. A refused plan writes nothing.
+ */
+export declare function migrateProject(options: ProjectMigrationOptions & {
+    closeProject?: () => void | Promise<void>;
+}): Promise<ProjectMigrationResult>;

package/dist/project-migration/engine.js

@@ -0,0 +1,103 @@
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { asFenceHolder, holdsProjectFence, migrationFencePaths } from '../server/cockpit-ownership.js';
+import { PROJECT_MIGRATION_STEPS, readProjectMigrationJournal, removeProjectMigrationJournal, writeProjectMigrationJournal, } from './journal.js';
+import { gitMvCommands, LEGACY_PROJECT_DIR, planProjectMigration } from './plan.js';
+import { GIT_MIGRATION_STEPS, MIGRATION_STEP_RUNNERS } from './steps.js';
+import { withWorktreeMutation } from '../git-worktree-lock.js';
+import { assertJournalContained, assertJournalFile } from './containment.js';
+/** The plan had conflicts or blockers: nothing was written and no journal exists. */
+export class ProjectMigrationRefusedError extends Error {
+    plan;
+    constructor(plan) {
+        super(`Cannot migrate ${plan.repoRoot}:${[...plan.blockers, ...plan.conflicts.map(conflict => `${conflict.path}: ${conflict.reason}`)]
+            .map(line => `\n- ${line}`).join('')}`);
+        this.plan = plan;
+        this.name = 'ProjectMigrationRefusedError';
+    }
+}
+function legacyDataDir(repoRoot) {
+    return join(resolve(repoRoot), ...LEGACY_PROJECT_DIR.split('/'));
+}
+/** The engine runs only under a fence its own process holds, and only for that fence's project. */
+function assertHeldFence(dataDir, fence) {
+    const paths = migrationFencePaths(dataDir);
+    if (!paths || paths.lock !== fence.lock || paths.journal !== fence.journal || !holdsProjectFence(dataDir)) {
+        throw new Error(`The project migration of ${resolve(dataDir, '..', '..')} needs the project's migration fence held by this process`);
+    }
+}
+async function runJournal(path, start, resumed, fault) {
+    let journal = start;
+    const run = async (step, git) => {
+        if (journal.done.includes(step))
+            return;
+        fault(`${step}:before`);
+        await MIGRATION_STEP_RUNNERS[step](journal, fault, git);
+        fault(`${step}:after`);
+        journal = { ...journal, done: [...journal.done, step] };
+        writeProjectMigrationJournal(path, journal);
+        fault(`${step}:marked`);
+    };
+    // Worktree locks, moves and repairs in one hold of the common directory's mutation lock, so no
+    // cooperating process mutates worktree registrations in between; the Git locks cover a crash.
+    if (journal.worktrees.length > 0 && GIT_MIGRATION_STEPS.some(step => !journal.done.includes(step))) {
+        await withWorktreeMutation(journal.repoRoot, async (git) => { for (const step of GIT_MIGRATION_STEPS)
+            await run(step, git); });
+    }
+    for (const step of PROJECT_MIGRATION_STEPS)
+        await run(step);
+    removeProjectMigrationJournal(path);
+    return { journal, resumed, gitMv: gitMvCommands(journal.repoRoot, journal.tracked), alreadyMoved: false };
+}
+/** Complete an unfinished journal, for P4b3's recovery before any project read; undefined without one. */
+export async function resumeProjectMigration(options) {
+    const dataDir = legacyDataDir(options.repoRoot);
+    assertHeldFence(dataDir, options.fence);
+    return asFenceHolder(options.fence, async () => resumeHeld(options));
+}
+async function resumeHeld(options) {
+    const root = realpathSync(resolve(options.repoRoot));
+    // The file is accepted before anything reads it: a symlink, a huge file or a committed one is refused.
+    if (!await assertJournalFile(options.fence.journal, root))
+        return undefined;
+    const journal = readProjectMigrationJournal(options.fence.journal);
+    if (!journal)
+        return undefined;
+    if (journal.repoRoot !== root)
+        throw new Error(`The migration journal ${options.fence.journal} belongs to ${journal.repoRoot}, not ${root}`);
+    // Read back from disk, so untrusted: nothing outside the project's own state may be named in it.
+    await assertJournalContained(options.fence.journal, journal);
+    return runJournal(options.fence.journal, journal, true, options.fault ?? (() => undefined));
+}
+/**
+ * Migrate the project, or finish its unfinished journal first. `closeProject` runs before the
+ * plan: the CLI closes the store it opened for its live-task check. A refused plan writes nothing.
+ */
+export async function migrateProject(options) {
+    const dataDir = legacyDataDir(options.repoRoot);
+    assertHeldFence(dataDir, options.fence);
+    return asFenceHolder(options.fence, async () => {
+        await options.closeProject?.();
+        const unfinished = await resumeHeld(options);
+        if (unfinished)
+            return unfinished;
+        const plan = await planProjectMigration(options.repoRoot);
+        if (plan.blockers.length > 0 || plan.conflicts.length > 0)
+            throw new ProjectMigrationRefusedError(plan);
+        const journal = {
+            version: 1, id: randomUUID(), createdAt: new Date().toISOString(), repoRoot: plan.repoRoot, source: plan.source,
+            destination: plan.destination, done: [], moves: plan.moves, tracked: plan.tracked, worktrees: plan.worktrees, rewrites: plan.rewrites,
+        };
+        // The same rule as a resume, before the journal exists, so a refused plan leaves nothing behind.
+        await assertJournalContained(plan.journal, journal);
+        if (plan.alreadyMoved)
+            return { journal, resumed: false, gitMv: plan.gitMv, alreadyMoved: true };
+        const fault = options.fault ?? (() => undefined);
+        fault('journal:before');
+        writeProjectMigrationJournal(plan.journal, journal);
+        fault('journal:written');
+        return runJournal(plan.journal, journal, false, fault);
+    });
+}
+//# sourceMappingURL=engine.js.map

package/dist/project-migration/engine.js.map

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

package/dist/project-migration/fresh.d.ts

@@ -0,0 +1,4 @@
+/** Pin a fresh project's new write root before its first write. Any legacy path, including an
+ * empty directory, symlink or unreadable entry, keeps the existing migration rules. Reads of
+ * projectPaths stay pure. The marker uses the same private Git location as a completed move. */
+export declare function markFreshProject(root: string, enabled?: boolean): void;

package/dist/project-migration/fresh.js

@@ -0,0 +1,25 @@
+import { lstatSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { REBRAND_SWITCH } from '../home/switch.js';
+import { canStartFreshProject, pathPresent, projectMovedMarker, projectMoveMarked } from '../project-paths.js';
+import { replaceAtomically, settle } from './durable.js';
+/** Pin a fresh project's new write root before its first write. Any legacy path, including an
+ * empty directory, symlink or unreadable entry, keeps the existing migration rules. Reads of
+ * projectPaths stay pure. The marker uses the same private Git location as a completed move. */
+export function markFreshProject(root, enabled = REBRAND_SWITCH) {
+    if (!enabled || !canStartFreshProject(root) || projectMoveMarked(root))
+        return;
+    const marker = projectMovedMarker(root);
+    // Non-Git callers still use the fresh path; there is no Git marker location to write.
+    if (!marker)
+        return;
+    const directory = dirname(marker.path);
+    mkdirSync(directory, { mode: 0o700, recursive: true });
+    if (!lstatSync(directory).isDirectory())
+        throw new Error(`${directory} is not a directory`);
+    if (pathPresent(marker.path) && !lstatSync(marker.path).isFile())
+        throw new Error(`${marker.path} is not a regular file`);
+    replaceAtomically(marker.path, `${JSON.stringify({ version: 1, root: marker.root, from: join(marker.root, '.ai/cezar') })}\n`, 0o600);
+    settle(dirname(directory), marker.path, { data: true });
+}
+//# sourceMappingURL=fresh.js.map

package/dist/project-migration/fresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fresh.js","sourceRoot":"","sources":["../../src/project-migration/fresh.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC/G,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEzD;;gGAEgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAAO,GAAG,cAAc;IACrE,IAAI,CAAC,OAAO,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC;QAAE,OAAO;IAC/E,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IACxC,sFAAsF;IACtF,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,SAAS,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvD,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,SAAS,qBAAqB,CAAC,CAAC;IAC5F,IAAI,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,MAAM,CAAC,IAAI,wBAAwB,CAAC,CAAC;IAC1H,iBAAiB,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;AAC1D,CAAC"}