@north-light/api 0.3.580 → 0.3.588

package/dist/core/layout-migrate/index.js

@@ -0,0 +1,523 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import { symlinkSync, linkSync, chmodSync, chownSync, closeSync, cpSync, existsSync, fsyncSync, lchownSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readSync, readdirSync, renameSync, rmSync, rmdirSync, unlinkSync, writeSync } from 'node:fs';
+import { request } from 'node:http';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { LEGACY_LOCAL_PERSON } from '../canvas/legacy-person.js';
+import { LAYOUT_VERSION, assertSupportedLayoutMarker } from '../layout.js';
+import { InputError } from '../io.js';
+import { syncDirectory } from '../fs-utils.js';
+import { oldToNewPathMap } from './paths.js';
+import { conversations, memoryAndProfiles, previewStores, profileFolders, repairMovedRepositories, worktrees } from './stores.js';
+import { storedPaths } from './stored-paths.js';
+export { OldToNewPathMap, oldToNewPathMap } from './paths.js';
+const JUNK_FILES = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+export function isJunkFile(name) { return JUNK_FILES.has(name) || name.startsWith('._'); }
+/** Where a leftover the new layout has no place for is kept: `runtime/set-aside/<kind>/<name>`, never overwriting. */
+export function setAsidePath(migration, kind, name) {
+    const base = join(migration.map.old.root, 'runtime', 'set-aside', kind);
+    let path = join(base, name);
+    for (let n = 2; existsSync(path); n++)
+        path = join(base, `${name}.${n}`);
+    return path;
+}
+/** Move a leftover aside (a rename; never a copy). */
+export function setAside(from, kind, migration, name = basename(from)) {
+    const to = setAsidePath(migration, kind, name);
+    mkdirSync(dirname(to), { recursive: true });
+    renameSync(from, to);
+    migration.moved++;
+    migration.changes.push(`${from} -> ${to} (set aside)`);
+    return to;
+}
+function empty(path) {
+    const stat = lstatSync(path);
+    return stat.isDirectory() ? readdirSync(path).length === 0 : stat.isFile() && stat.size === 0;
+}
+export function claim(from, to, migration, wholeDirectory = false) {
+    const a = lstatSync(from);
+    const b = lstatSync(to);
+    if (a.isDirectory() && b.isDirectory() && !wholeDirectory)
+        return { action: 'merge' };
+    if (a.isFile() && b.isFile() && sameFile(from, to))
+        return { action: 'drop-source' };
+    if (empty(to))
+        return { action: 'remove-destination', line: `stray-destination: removed empty ${b.isDirectory() ? 'folder' : 'file'} ${to} that predates the migration` };
+    const aside = setAsidePath(migration, 'replaced', relative(migration.map.old.root, to));
+    return { action: 'set-aside-destination', line: `stray-destination: ${to} predates the migration; moved it to ${aside} and put ${from} in its place` };
+}
+/** Rename within the volume; merge an existing directory on interrupted runs, never overwrite a file. */
+export function movePath(from, to, migration, wholeDirectory = false) {
+    if (!existsSync(from))
+        return;
+    if (from === to)
+        return;
+    if (existsSync(to)) {
+        const decision = claim(from, to, migration, wholeDirectory);
+        if (decision.line)
+            migration.resolutions.push(decision.line);
+        if (decision.action === 'merge') {
+            for (const name of readdirSync(from))
+                movePath(join(from, name), join(to, name), migration);
+            rmdirSync(from);
+            return;
+        }
+        if (decision.action === 'drop-source') {
+            rmSync(from, { recursive: true });
+            migration.changes.push(`${from} (identical to ${to}; removed)`);
+            return;
+        }
+        if (decision.action === 'remove-destination') {
+            rmSync(to, { recursive: true });
+            migration.changes.push(`${to} (removed)`);
+        }
+        else
+            setAside(to, 'replaced', migration, relative(migration.map.old.root, to));
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    renameSync(from, to);
+    migration.moved++;
+    migration.changes.push(`${from} -> ${to}`);
+}
+/** Dry-run lines for a move: the claims the real run would make, without touching anything. */
+export function previewMove(from, to, migration, wholeDirectory = false) {
+    if (!existsSync(from) || from === to || !existsSync(to))
+        return;
+    const decision = claim(from, to, migration, wholeDirectory);
+    if (decision.line)
+        migration.resolutions.push(decision.line);
+    if (decision.action === 'merge')
+        for (const name of readdirSync(from))
+            previewMove(join(from, name), join(to, name), migration);
+}
+function canvasNodeApps(migration) {
+    const { map } = migration;
+    const oldNodes = join(map.old.canvas, 'nodes');
+    const oldDb = join(map.old.canvas, 'canvas.db');
+    const newDb = join(map.old.root, 'runtime', 'canvas.db');
+    const dbPath = existsSync(oldDb) ? oldDb : existsSync(newDb) && lstatSync(newDb).size > 0 ? newDb : '';
+    if (!dbPath) {
+        if (existsSync(oldNodes))
+            throw new Error('old node records exist without canvas.db');
+        return null;
+    }
+    // The daemon is offline. Checkpoint before moving the database so committed
+    // rows in a left-behind WAL remain present when the new path opens.
+    const db = new DatabaseSync(dbPath, { readOnly: migration.dryRun || dbPath !== oldDb });
+    try {
+        if (dbPath === oldDb && !migration.dryRun) {
+            const checkpoint = db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').get();
+            if (checkpoint.busy !== 0)
+                throw new Error('old canvas WAL is busy; stop every database user before migrating');
+        }
+        return new Map(db.prepare('SELECT node_id, grantee FROM nodes').all()
+            .map(row => {
+            const app = row.grantee === LEGACY_LOCAL_PERSON ? 'terminal' : row.grantee.startsWith('app:') ? row.grantee.slice(4) : '';
+            if (!app)
+                throw new Error(`node ${row.node_id} has no app assignment`);
+            return [row.node_id, app];
+        }));
+    }
+    finally {
+        db.close();
+    }
+}
+/** A `canvas/nodes` entry with no node row (or a row whose entry is not a folder) has no place in the new layout. */
+function orphanNodeEntries(migration, nodes) {
+    const oldNodes = join(migration.map.old.canvas, 'nodes');
+    if (!existsSync(oldNodes))
+        return [];
+    const orphans = [];
+    for (const id of readdirSync(oldNodes)) {
+        const path = join(oldNodes, id);
+        const directory = lstatSync(path).isDirectory();
+        if (nodes.has(id) && directory)
+            continue;
+        orphans.push({ path, remove: !directory && isJunkFile(id) });
+    }
+    return orphans;
+}
+function orphanLine(orphan, migration) {
+    return orphan.remove
+        ? `node-leftover: deleted ${orphan.path} (not a node record)`
+        : `node-leftover: ${orphan.path} has no node row; moved to ${setAsidePath(migration, 'nodes', basename(orphan.path))}`;
+}
+function records(migration) {
+    const { map } = migration;
+    const oldNodes = join(map.old.canvas, 'nodes');
+    const nodes = canvasNodeApps(migration);
+    if (!nodes)
+        return;
+    for (const [id, app] of nodes)
+        map.node(id, app);
+    if (!existsSync(oldNodes))
+        return;
+    for (const orphan of orphanNodeEntries(migration, nodes)) {
+        migration.resolutions.push(orphanLine(orphan, migration));
+        if (orphan.remove) {
+            unlinkSync(orphan.path);
+            migration.changes.push(`${orphan.path} (removed)`);
+            continue;
+        }
+        const aside = setAside(orphan.path, 'nodes', migration);
+        const target = join(map.old.targetRoot, relative(map.old.root, aside));
+        for (const canvas of new Set([map.old.storedCanvas, map.old.storedScope, join(map.old.storedScope, 'canvas')])) {
+            map.add(join(canvas, 'nodes', basename(orphan.path)), target);
+        }
+    }
+    for (const [id, app] of nodes) {
+        const source = join(oldNodes, id);
+        if (!existsSync(source))
+            continue;
+        // R23b moves context/memory and managed worktrees after this step.
+        for (const name of ['context', 'reports', 'attachments'])
+            movePath(join(source, name), join(map.old.root, 'apps', app, 'nodes', id, name), migration);
+        for (const name of readdirSync(source)) {
+            if (['worktree', 'view.sock', 'broker-launch.json', 'system-prompt.md', 'situational-context.md', 'injected-docs.json'].includes(name))
+                continue;
+            movePath(join(source, name), join(map.old.root, 'runtime', 'nodes', id, name), migration);
+        }
+        if (readdirSync(source).length === 0)
+            rmdirSync(source);
+    }
+    if (readdirSync(oldNodes).length === 0)
+        rmdirSync(oldNodes);
+}
+const CREDENTIALS = ['auth.json', 'anthropic-credentials.json', 'openai-codex-credentials.json', 'openai-credentials.json', 'crouter-operations.db'];
+function copyCredential(from, to, migration) {
+    if (!existsSync(from))
+        return;
+    if (!lstatSync(from).isFile())
+        throw new Error(`credential source is not a regular file: ${from}`);
+    const bytes = readFileSync(from);
+    if (existsSync(to)) {
+        // A newer build already wrote this credential; it is current. The old file stays for rollback.
+        if (!lstatSync(to).isFile() || !readFileSync(to).equals(bytes))
+            migration.resolutions.push(`credential: kept the existing ${to}; the older ${from} differs and stays where it is`);
+        return;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    const temp = join(dirname(to), `.${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temp, 'wx', 0o600);
+        try {
+            for (let offset = 0; offset < bytes.length;)
+                offset += writeSync(fd, bytes, offset, bytes.length - offset);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temp, to);
+        if (!readFileSync(to).equals(bytes))
+            throw new Error(`credential verification failed: ${to}`);
+    }
+    finally {
+        if (existsSync(temp))
+            unlinkSync(temp);
+    }
+    migration.moved++;
+    migration.changes.push(`${from} -> ${to} (source retained)`);
+}
+function checkpointDb(path) {
+    if (!existsSync(path))
+        return;
+    const db = new DatabaseSync(path);
+    try {
+        const checkpoint = db.prepare('PRAGMA wal_checkpoint(TRUNCATE)').get();
+        if (checkpoint.busy !== 0)
+            throw new Error(`SQLite WAL is busy: ${path}`);
+    }
+    finally {
+        db.close();
+    }
+}
+export function sameFile(from, to) {
+    if (lstatSync(from).size !== lstatSync(to).size)
+        return false;
+    const a = openSync(from, 'r');
+    const b = openSync(to, 'r');
+    const first = Buffer.allocUnsafe(64 * 1024);
+    const second = Buffer.allocUnsafe(first.length);
+    try {
+        for (;;) {
+            const size = readSync(a, first, 0, first.length, null);
+            if (size === 0)
+                return true;
+            let read = 0;
+            while (read < size) {
+                const next = readSync(b, second, read, size - read, null);
+                if (next === 0)
+                    return false;
+                read += next;
+            }
+            if (!first.subarray(0, size).equals(second.subarray(0, size)))
+                return false;
+        }
+    }
+    finally {
+        closeSync(a);
+        closeSync(b);
+    }
+}
+function sameTree(from, to, skipGitRecords = false) {
+    let b;
+    try {
+        b = lstatSync(to);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    const a = lstatSync(from);
+    if (a.isSymbolicLink())
+        return b.isSymbolicLink() && readlinkSync(from) === readlinkSync(to);
+    if (a.isFile())
+        return b.isFile() && sameFile(from, to);
+    if (!a.isDirectory() || !b.isDirectory())
+        return false;
+    const names = readdirSync(from).filter(name => !skipGitRecords || name !== '.git');
+    const other = readdirSync(to).filter(name => !skipGitRecords || name !== '.git');
+    const entries = new Set(other);
+    return names.length === other.length && names.every(name => entries.has(name) && sameTree(join(from, name), join(to, name), skipGitRecords));
+}
+/** The old hosted work directory is outside /volume; preserve its original
+ * container filesystem when copying it onto the persistent runtime volume. */
+function copyHostedWork(from, to, migration) {
+    if (!existsSync(from))
+        return;
+    if (!lstatSync(from).isDirectory())
+        throw new Error(`hosted work is not a directory: ${from}`);
+    if (existsSync(to)) {
+        // Git repair changes the copied repository's .git records after the copy.
+        if (sameTree(from, to, true))
+            return;
+        if (!lstatSync(to).isDirectory() || readdirSync(to).length !== 0) {
+            // The copy keeps its source, so the old work tree stays for rollback.
+            migration.resolutions.push(`hosted-work: kept the existing ${to}; the old ${from} differs and stays where it is`);
+            return;
+        }
+        rmdirSync(to);
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    const temp = join(dirname(to), `.work-${randomUUID()}.migrating`);
+    try {
+        cpSync(from, temp, { recursive: true, verbatimSymlinks: true, preserveTimestamps: true });
+        if (!sameTree(from, temp))
+            throw new Error(`hosted work copy verification failed: ${from}`);
+        renameSync(temp, to);
+        migration.moved++;
+        migration.changes.push(`${from} -> ${to} (source retained)`);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { recursive: true, force: true });
+    }
+}
+function topLevelMoves(migration) {
+    const { old } = migration.map;
+    const runtime = join(old.root, 'runtime');
+    const scope = join(runtime, 'scope');
+    const moves = [];
+    // on-disk-migrations.json records the legacy store migrations that already ran; the canvas import reads it from runtime/.
+    for (const name of ['canvas.db', 'canvas.db-wal', 'canvas.db-shm', 'on-disk-migrations.json', 'requests', 'reviews', 'plugins', 'marketplaces', 'crtrd.log', 'crtrd.err', 'cache'])
+        moves.push([join(old.canvas, name), join(runtime, name)]);
+    // The old canvas and user scope can be the same folder. Never rename that folder wholesale.
+    for (const name of ['prompts', 'personas', 'config.json', 'profile-defaults.json', 'operations.db', 'operations.db-wal', 'operations.db-shm'])
+        moves.push([join(old.scope, name), join(scope, name)]);
+    for (const name of ['support', 'prompt-reviews', 'plugins', 'marketplaces'])
+        moves.push([join(old.scope, name), join(runtime, name)]);
+    moves.push([join(old.canvas, 'secrets'), join(runtime, 'secrets')]);
+    return moves;
+}
+/** A top-level entry is renamed whole, so an existing destination was made by
+ * a newer build started before the migration (e.g. an empty `runtime/canvas.db`). */
+function topLevel(migration) {
+    const { old } = migration.map;
+    const runtime = join(old.root, 'runtime');
+    checkpointDb(join(old.scope, 'operations.db'));
+    for (const [from, to] of topLevelMoves(migration)) {
+        const links = relativeLinks(from);
+        movePath(from, to, migration, true);
+        retargetLinks(links, from, to, migration);
+    }
+    // Old provider credentials are on a separate mount. Keep them for rollback.
+    checkpointDb(join(old.agent, 'crouter-operations.db'));
+    for (const name of CREDENTIALS)
+        copyCredential(join(old.agent, name), join(runtime, 'secrets', name), migration);
+    if (process.platform === 'linux')
+        copyHostedWork(old.work, join(old.root, 'user', 'files'), migration);
+}
+/** The relative symlinks directly inside a folder, e.g. `plugins/<name>` installed as `../../Code/...`. */
+function relativeLinks(dir) {
+    if (!existsSync(dir) || !lstatSync(dir).isDirectory())
+        return [];
+    const out = [];
+    for (const name of readdirSync(dir)) {
+        const path = join(dir, name);
+        if (!lstatSync(path).isSymbolicLink())
+            continue;
+        const target = readlinkSync(path);
+        if (!isAbsolute(target))
+            out.push({ name, target });
+    }
+    return out;
+}
+/** A folder moved to another depth breaks its relative links: point each one at what it named before the move. */
+function retargetLinks(links, from, to, migration) {
+    if (links.length === 0 || !existsSync(to))
+        return;
+    for (const { name, target } of links) {
+        const link = join(to, name);
+        if (!lstatExists(link))
+            continue;
+        const named = migration.map.mapPath(resolve(from, target));
+        const next = relative(to, named);
+        if (next === target)
+            continue;
+        unlinkSync(link);
+        symlinkSync(next, link);
+        migration.changes.push(`${link}: link ${target} -> ${next}`);
+    }
+}
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ownership(root) {
+    if (process.platform !== 'linux')
+        return;
+    if (process.getuid?.() !== 0)
+        throw new Error('Linux layout migration requires root for the ownership pass');
+    const passwd = readFileSync('/etc/passwd', 'utf8').split('\n').find(line => line.startsWith('crtrd:'));
+    const group = readFileSync('/etc/group', 'utf8').split('\n').find(line => line.startsWith('crtr-data:'));
+    if (!passwd || !group)
+        throw new Error('layout migration requires crtrd user and crtr-data group');
+    const uid = Number(passwd.split(':')[2]);
+    const gid = Number(group.split(':')[2]);
+    if (!Number.isInteger(uid) || !Number.isInteger(gid))
+        throw new Error('invalid migration user or group');
+    const walk = (path, data) => {
+        if (!existsSync(path))
+            return;
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink()) {
+            lchownSync(path, uid, data ? gid : stat.gid);
+            return;
+        }
+        chownSync(path, uid, data ? gid : stat.gid);
+        if (stat.isDirectory()) {
+            chmodSync(path, data ? 0o2770 : 0o700);
+            for (const name of readdirSync(path))
+                walk(join(path, name), data);
+        }
+        else if (data)
+            chmodSync(path, (stat.mode & 0o111 ? 0o770 : 0o660));
+    };
+    walk(join(root, 'runtime'), false);
+    walk(join(root, 'user'), true);
+    walk(join(root, 'apps'), true);
+}
+export function daemonAnswers(socketPath) {
+    return new Promise(resolve => {
+        const req = request({ socketPath, path: '/healthz', method: 'GET', timeout: 1000 }, res => {
+            res.resume();
+            resolve(true); // A blocked daemon still answers and owns its files.
+        });
+        req.on('timeout', () => req.destroy(new Error('daemon probe timed out')));
+        req.on('error', error => {
+            if (error.code === 'ENOENT' || error.code === 'ECONNREFUSED')
+                resolve(false);
+            else
+                resolve(true); // Uncertain probe: do not mutate an owned volume.
+        });
+        req.end();
+    });
+}
+export async function migrateLayout(dryRun) {
+    const map = oldToNewPathMap();
+    const old = map.old;
+    const version = join(old.root, 'runtime', 'layout');
+    if (existsSync(version)) {
+        assertSupportedLayoutMarker(version);
+        return null;
+    }
+    // Inspect both the old and current socket; do not autostart a daemon.
+    const sockets = new Set([join(old.canvas, 'crtrd.sock'), join(old.scope, 'crtrd.sock'),
+        process.platform === 'linux' ? '/run/crtr/api.sock' : join(old.root, 'runtime', 'api.sock')]);
+    for (const socket of sockets)
+        if (await daemonAnswers(socket))
+            throw new InputError({
+                error: 'daemon_running',
+                message: `cannot migrate while a daemon answers on ${socket}`,
+                next: 'Stop the daemon that owns this volume, then run `crtr sys migrate` again.',
+            });
+    if (process.platform === 'linux' && !existsSync(old.agent))
+        throw new InputError({
+            error: 'credential_volume_missing',
+            message: `the old credential volume is not mounted at ${old.agent}`,
+            next: `Mount the old provider-auth volume at ${old.agent}, then run \`crtr sys migrate\` again.`,
+        });
+    const absentCredentials = CREDENTIALS.map(name => join(old.agent, name)).filter(path => !existsSync(path));
+    const result = { map, moved: 0, changes: [], resolutions: [], bodyPaths: [], absentCredentials, dryRun };
+    if (dryRun) {
+        // The same decisions the real run makes, computed read-only.
+        const nodes = canvasNodeApps(result);
+        if (nodes)
+            for (const orphan of orphanNodeEntries(result, nodes))
+                result.resolutions.push(orphanLine(orphan, result));
+        for (const [from, to] of topLevelMoves(result))
+            previewMove(from, to, result, true);
+        previewStores(result);
+        return result;
+    }
+    // Register every profile path before any step maps a stored path.
+    profileFolders(result);
+    // Move worktrees before the hosted repository moves so git can repair its metadata.
+    const steps = [records, worktrees, topLevel, repairMovedRepositories, memoryAndProfiles, conversations, storedPaths];
+    for (const step of steps)
+        step(result);
+    // Every old canvas entry has moved; an empty old canvas folder would name nothing.
+    if (old.canvas !== old.root && existsSync(old.canvas) && readdirSync(old.canvas).length === 0)
+        rmdirSync(old.canvas);
+    ownership(old.root);
+    // The version is the commit marker: no daemon accepts the tree until every
+    // move, stored-path rewrite and permission change has completed.
+    mkdirSync(dirname(version), { recursive: true });
+    const temporary = `${version}.${randomUUID()}.tmp`;
+    const fd = openSync(temporary, 'wx', 0o600);
+    try {
+        try {
+            if (process.platform === 'linux') {
+                const stat = lstatSync(dirname(version));
+                chownSync(temporary, stat.uid, stat.gid);
+            }
+            writeSync(fd, `${LAYOUT_VERSION}\n`);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        // Link, not rename: a marker that appeared since the check above is refused, never replaced.
+        try {
+            linkSync(temporary, version);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                assertSupportedLayoutMarker(version);
+            else
+                throw error;
+        }
+    }
+    finally {
+        unlinkSync(temporary);
+    }
+    syncDirectory(dirname(version));
+    return result;
+}

package/dist/core/layout-migrate/paths.d.ts

@@ -0,0 +1,30 @@
+export interface OldLayout {
+    root: string;
+    targetRoot: string;
+    canvas: string;
+    scope: string;
+    agent: string;
+    storedCanvas: string;
+    storedScope: string;
+    storedAgent: string;
+    work: string;
+}
+/** Sources are physical paths; stored prefixes are paths seen by the old daemon. */
+export declare function oldLayout(): OldLayout;
+export declare class OldToNewPathMap {
+    readonly old: OldLayout;
+    private readonly entries;
+    private readonly retired;
+    /** Stored paths inside a removed folder with no new location; left unchanged. */
+    readonly dangling: Set<string>;
+    constructor(old: OldLayout);
+    add(from: string, to: string): void;
+    /** A path whose planned destination changed: a worktree folder set aside instead of moving into its node. */
+    redirect(from: string, to: string): void;
+    /** A removed folder: the folder itself maps to `to`, and a stored path inside it with no finer entry is refused. */
+    retire(from: string, to: string): void;
+    node(nodeId: string, app: string): void;
+    /** Rewrites only approved old prefixes; later steps register profile and session paths. */
+    mapPath(path: string): string;
+}
+export declare function oldToNewPathMap(): OldToNewPathMap;

package/dist/core/layout-migrate/paths.js

@@ -0,0 +1,118 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { layoutRoot } from '../layout.js';
+/** Sources are physical paths; stored prefixes are paths seen by the old daemon. */
+export function oldLayout() {
+    const targetRoot = layoutRoot();
+    const hosted = process.platform === 'linux';
+    const root = hosted && targetRoot === '/' ? '/volume' : targetRoot;
+    const storedScope = hosted ? '/home/agent/.crouter' : root;
+    const canvas = existsSync(join(root, 'canvas')) ? join(root, 'canvas') : root;
+    // In the container the old credential volume is mounted at its old path;
+    // PI_CODING_AGENT_DIR there names the new location under /runtime.
+    const agent = hosted ? '/home/agent/.pi/agent' : resolve(process.env['PI_CODING_AGENT_DIR'] || join(homedir(), '.pi', 'agent'));
+    return {
+        root,
+        targetRoot,
+        canvas,
+        scope: root,
+        agent,
+        storedCanvas: canvas === root ? storedScope : join(storedScope, 'canvas'),
+        storedScope,
+        storedAgent: agent,
+        work: '/home/crtr/work',
+    };
+}
+export class OldToNewPathMap {
+    old;
+    entries = new Map();
+    retired = new Map();
+    /** Stored paths inside a removed folder with no new location; left unchanged. */
+    dangling = new Set();
+    constructor(old) {
+        this.old = old;
+        const runtime = join(old.targetRoot, 'runtime');
+        const scope = join(runtime, 'scope');
+        for (const canvas of new Set([old.storedCanvas, old.storedScope, join(old.storedScope, 'canvas')])) {
+            for (const name of ['canvas.db', 'canvas.db-wal', 'canvas.db-shm', 'requests', 'reviews', 'plugins', 'marketplaces', 'secrets', 'crtrd.log', 'crtrd.err', 'cache']) {
+                this.add(join(canvas, name), join(runtime, name));
+            }
+        }
+        for (const name of ['prompts', 'personas', 'config.json', 'profile-defaults.json', 'operations.db', 'operations.db-wal', 'operations.db-shm']) {
+            this.add(join(old.storedScope, name), join(scope, name));
+        }
+        for (const name of ['support', 'prompt-reviews', 'plugins', 'marketplaces'])
+            this.add(join(old.storedScope, name), join(runtime, name));
+        this.add(join(old.storedScope, 'memory'), join(old.targetRoot, 'user', 'memory'));
+        this.add(old.storedScope, scope);
+        this.add(old.work, join(old.targetRoot, 'user', 'files'));
+        for (const name of ['auth.json', 'anthropic-credentials.json', 'openai-codex-credentials.json', 'openai-credentials.json', 'crouter-operations.db']) {
+            this.add(join(old.storedAgent, name), join(runtime, 'secrets', name));
+        }
+        for (const canvas of new Set([old.storedCanvas, old.storedScope, join(old.storedScope, 'canvas')])) {
+            this.add(join(canvas, 'secrets', 'runtime-client.json'), join(runtime, 'secrets', 'runtime-client.json'));
+        }
+    }
+    add(from, to) {
+        if (!isAbsolute(from) || !isAbsolute(to))
+            throw new Error('migration paths must be absolute');
+        const previous = this.entries.get(from);
+        if (previous && previous !== to)
+            throw new Error(`conflicting migration path: ${from}`);
+        this.entries.set(from, to);
+    }
+    /** A path whose planned destination changed: a worktree folder set aside instead of moving into its node. */
+    redirect(from, to) {
+        if (!isAbsolute(from) || !isAbsolute(to))
+            throw new Error('migration paths must be absolute');
+        this.entries.set(from, to);
+    }
+    /** A removed folder: the folder itself maps to `to`, and a stored path inside it with no finer entry is refused. */
+    retire(from, to) {
+        if (!isAbsolute(from) || !isAbsolute(to))
+            throw new Error('migration paths must be absolute');
+        const previous = this.retired.get(from);
+        if (previous && previous !== to)
+            throw new Error(`conflicting migration path: ${from}`);
+        this.retired.set(from, to);
+    }
+    node(nodeId, app) {
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(nodeId) || !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(app))
+            throw new Error('unsafe migration node or app id');
+        const records = join(this.old.targetRoot, 'runtime', 'nodes', nodeId);
+        const agent = join(this.old.targetRoot, 'apps', app, 'nodes', nodeId);
+        // Once the old canvas directory is empty it disappears; both original
+        // shapes must remain addressable on an interrupted migration's rerun.
+        for (const canvas of new Set([this.old.storedCanvas, this.old.storedScope, join(this.old.storedScope, 'canvas')])) {
+            const from = join(canvas, 'nodes', nodeId);
+            for (const name of ['job', 'messages', 'meta.json', 'inbox.jsonl', 'passive.jsonl', 'transcript.jsonl', 'session.ptr'])
+                this.add(join(from, name), join(records, name));
+            for (const name of ['context', 'reports', 'attachments', 'worktree'])
+                this.add(join(from, name), join(agent, name));
+            this.add(join(from, 'context', 'memory'), join(this.old.targetRoot, 'apps', app, 'memory', 'nodes', nodeId));
+        }
+    }
+    /** Rewrites only approved old prefixes; later steps register profile and session paths. */
+    mapPath(path) {
+        if (!isAbsolute(path))
+            return path;
+        const exact = this.retired.get(path);
+        if (exact)
+            return exact;
+        let source = '';
+        for (const key of this.entries.keys()) {
+            if ((path === key || path.startsWith(key + sep)) && key.length > source.length)
+                source = key;
+        }
+        for (const key of this.retired.keys()) {
+            // A file the new layout drops (a profile manifest or lock): the stored path stays, naming nothing.
+            if (path.startsWith(key + sep) && key.length > source.length) {
+                this.dangling.add(path);
+                return path;
+            }
+        }
+        return source ? resolve(this.entries.get(source), relative(source, path)) : path;
+    }
+}
+export function oldToNewPathMap() { return new OldToNewPathMap(oldLayout()); }

package/dist/core/layout-migrate/stored-paths.d.ts

@@ -0,0 +1,9 @@
+import type { LayoutMigration } from './index.js';
+export declare function storedPaths(migration: LayoutMigration): void;
+/**
+ * Markdown links a moved profile folder by its old absolute path (or its `~/`
+ * spelling); point each at the new location. Scans the documents the canvas
+ * import reads: user and app memory, profile files, and node context. A dry
+ * run scans the same documents at their old locations and writes nothing.
+ */
+export declare function rewriteBodyPaths(migration: LayoutMigration): void;