talos-code 0.0.1 → 0.1.0

package/dist/workspace/checkpoint.js

@@ -0,0 +1,413 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveWorkspaceIdentity } from "../security/workspace-identity.js";
+export const CHECKPOINT_LIMITS = { maxEntries: 50_000, maxStoredBytes: 256 * 1024 * 1024, maxStoredFileBytes: 64 * 1024 * 1024 };
+function coded(code, message = code, details = {}) { return Object.assign(new Error(message === code ? code : `${code}: ${message}`), { code, details }); }
+function sha256(data) { return createHash('sha256').update(data).digest('hex'); }
+function slash(value) { return value.split(path.sep).join('/'); }
+function safeRelative(value) {
+    const normalized = value.replace(/\\/gu, '/');
+    if (!normalized || normalized.startsWith('/') || normalized.split('/').some(part => !part || part === '.' || part === '..'))
+        throw coded('CHECKPOINT_PATH_INVALID');
+    return normalized;
+}
+function absoluteFromRelative(root, relative) { return path.resolve(root, ...safeRelative(relative).split('/')); }
+function inside(root, candidate) { const relative = path.relative(root, candidate); return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative)); }
+/*
+ * R0 (2026-09-23). A file is made durable through a WRITABLE handle: FlushFileBuffers needs GENERIC_WRITE, so on Windows
+ * `open(path,'r')` + `sync()` is EPERM and every checkpoint undo/redo failed (exit 70) before restoring anything. POSIX
+ * accepts fsync on a read-only descriptor, which keeps a file already chmod-ed read-only syncable there. A file fsync
+ * error is never swallowed (gate E8/E9); only the directory step below is tolerated on win32.
+ */
+export async function durableFile(pathname) {
+    let handle;
+    try {
+        handle = await open(pathname, 'r+');
+    }
+    catch (error) {
+        if (process.platform === 'win32' || (error?.code !== 'EACCES' && error?.code !== 'EPERM'))
+            throw error;
+        handle = await open(pathname, 'r');
+    }
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function durableDir(dirname) { try {
+    const handle = await open(dirname, 'r');
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+catch (error) {
+    if (process.platform !== 'win32')
+        throw error;
+} }
+async function ensurePrivateDir(dirname) { await mkdir(dirname, { recursive: true, mode: 0o700 }); try {
+    await chmod(dirname, 0o700);
+}
+catch (error) {
+    if (process.platform !== 'win32')
+        throw error;
+} }
+async function storeBlob(blobRoot, data) {
+    const hash = sha256(data), target = path.join(blobRoot, hash);
+    await ensurePrivateDir(blobRoot);
+    const temp = path.join(blobRoot, `.${hash}.${process.pid}.tmp`);
+    try {
+        const handle = await open(temp, 'wx', 0o600);
+        try {
+            await handle.writeFile(data);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temp, target).catch(async (error) => { if (error?.code === 'EEXIST') {
+            await rm(temp, { force: true });
+            return;
+        } throw error; });
+        await durableDir(blobRoot);
+    }
+    catch (error) {
+        if (error?.code !== 'EEXIST')
+            throw error;
+    }
+    return hash;
+}
+function consumeFileBudget(budget, size) {
+    if (size > budget.limits.maxStoredFileBytes)
+        throw coded('CHECKPOINT_FILE_TOO_LARGE');
+    if (budget.storedBytes + size > budget.limits.maxStoredBytes)
+        throw coded('CHECKPOINT_SNAPSHOT_TOO_LARGE');
+    budget.storedBytes += size;
+}
+function consumeEntry(budget) { budget.entries += 1; if (budget.entries > budget.limits.maxEntries)
+    throw coded('CHECKPOINT_TOO_MANY_ENTRIES'); }
+async function gitBytes(cwd, args, maxBytes = 64 * 1024 * 1024, allowedExitCodes = [0], stdin) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['-c', 'core.quotepath=false', ...args], { cwd, stdio: [stdin ? 'pipe' : 'ignore', 'pipe', 'pipe'], windowsHide: true });
+        const out = [];
+        const err = [];
+        let total = 0;
+        const stdout = child.stdout, stderr = child.stderr;
+        if (!stdout || !stderr) {
+            reject(coded('CHECKPOINT_GIT_PIPE_UNAVAILABLE'));
+            return;
+        }
+        stdout.on('data', (chunk) => { total += chunk.length; if (total > maxBytes) {
+            child.kill();
+            reject(coded('CHECKPOINT_GIT_OUTPUT_TOO_LARGE'));
+            return;
+        } out.push(chunk); });
+        stderr.on('data', (chunk) => err.push(chunk));
+        child.on('error', reject);
+        if (stdin) {
+            child.stdin?.end(stdin);
+        }
+        child.on('close', code => { if (code !== null && allowedExitCodes.includes(code))
+            resolve(Buffer.concat(out));
+        else
+            reject(coded('CHECKPOINT_GIT_READ_FAILED', Buffer.concat(err).toString('utf8').trim() || `git exited ${code}`)); });
+    });
+}
+async function gitText(cwd, args, maxBytes = 64 * 1024 * 1024) { return (await gitBytes(cwd, args, maxBytes)).toString('utf8'); }
+function nulList(buffer) { return buffer.toString('utf8').split('\0').filter(Boolean); }
+async function gitHead(gitRoot) { try {
+    return (await gitText(gitRoot, ['rev-parse', '--verify', 'HEAD'], 1024)).trim() || null;
+}
+catch {
+    return null;
+} }
+async function gitIndexHash(gitRoot) {
+    let raw;
+    try {
+        raw = (await gitText(gitRoot, ['rev-parse', '--git-path', 'index'], 16 * 1024)).trim();
+    }
+    catch {
+        return null;
+    }
+    if (!raw)
+        return null;
+    const indexPath = path.isAbsolute(raw) ? raw : path.resolve(gitRoot, raw);
+    try {
+        return sha256(await readFile(indexPath));
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function assertExistingPathContained(workspace, absolute) {
+    const canonical = await realpath(absolute);
+    if (!inside(workspace.canonicalRoot, canonical))
+        throw coded('CHECKPOINT_PATH_ESCAPE', `Checkpoint path escapes workspace: ${absolute}`);
+}
+async function captureActualFile(workspace, absolute, relative, blobRoot, budget, indexExecutable = false) {
+    let stat;
+    try {
+        stat = await lstat(absolute);
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    consumeEntry(budget);
+    if (stat.isSymbolicLink()) {
+        let canonical;
+        try {
+            canonical = await realpath(absolute);
+        }
+        catch {
+            throw coded('CHECKPOINT_SYMLINK_ESCAPE', `Checkpoint symlink cannot be resolved safely: ${relative}`);
+        }
+        if (!inside(workspace.canonicalRoot, canonical))
+            throw coded('CHECKPOINT_SYMLINK_ESCAPE', `Checkpoint symlink escapes workspace: ${relative}`);
+        return { kind: 'symlink', target: await readlink(absolute) };
+    }
+    if (!stat.isFile())
+        throw coded('CHECKPOINT_SPECIAL_FILE_UNSUPPORTED', `Unsupported workspace entry: ${relative}`);
+    await assertExistingPathContained(workspace, absolute);
+    consumeFileBudget(budget, stat.size);
+    const data = await readFile(absolute);
+    const ref = await storeBlob(blobRoot, data);
+    const executable = process.platform === 'win32' ? indexExecutable : Boolean(stat.mode & 0o111);
+    return { kind: 'file', source: 'blob', ref, size: stat.size, mode: stat.mode & 0o777, executable };
+}
+async function captureGit(workspace, blobRoot, budget) {
+    const gitRoot = workspace.gitRoot;
+    const prefix = slash(path.relative(gitRoot, workspace.canonicalRoot));
+    const scope = prefix ? ['--', prefix] : [];
+    const [trackedRaw, dirtyRaw, untrackedRaw, flagsRaw, head, indexHash, conversionConfig] = await Promise.all([
+        gitBytes(gitRoot, ['ls-files', '-s', '-z', ...scope]),
+        gitBytes(gitRoot, ['diff', '--name-only', '-z', ...scope]),
+        gitBytes(gitRoot, ['ls-files', '--others', '--exclude-standard', '-z', ...scope]),
+        gitBytes(gitRoot, ['ls-files', '-v', '-z', ...scope]), gitHead(gitRoot), gitIndexHash(gitRoot),
+        gitBytes(gitRoot, ['config', '--null', '--get-regexp', '^(core\\.autocrlf|core\\.eol|filter\\.)'], 64 * 1024 * 1024, [0, 1]),
+    ]);
+    const trackedRows = nulList(trackedRaw);
+    const trackedPaths = trackedRows.map(row => { const tab = row.indexOf('\t'); if (tab < 0)
+        throw coded('CHECKPOINT_GIT_INDEX_INVALID'); return row.slice(tab + 1); });
+    const attributeInput = Buffer.from(trackedPaths.map(value => `${value}\0`).join(''), 'utf8');
+    const attributeState = await gitBytes(gitRoot, ['check-attr', '-a', '-z', '--stdin'], 64 * 1024 * 1024, [0], attributeInput);
+    const worktreeSemanticsHash = sha256(Buffer.concat([conversionConfig, Buffer.from([0]), attributeState]));
+    const dirty = new Set(nulList(dirtyRaw));
+    for (const row of nulList(flagsRaw)) {
+        const space = row.indexOf(' ');
+        if (space <= 0)
+            continue;
+        const flag = row.slice(0, space), name = row.slice(space + 1);
+        if (flag !== flag.toUpperCase() || flag === 'S')
+            dirty.add(name);
+    }
+    const entries = {};
+    const seen = new Set();
+    for (const row of trackedRows) {
+        const tab = row.indexOf('\t');
+        if (tab < 0)
+            throw coded('CHECKPOINT_GIT_INDEX_INVALID');
+        const meta = row.slice(0, tab).split(' ');
+        const gitPath = row.slice(tab + 1);
+        if (meta.length < 3 || meta[2] !== '0')
+            throw coded('CHECKPOINT_GIT_UNMERGED', 'Unmerged Git index state is not checkpointable safely.');
+        const mode = meta[0], oid = meta[1];
+        if (seen.has(gitPath))
+            throw coded('CHECKPOINT_GIT_UNMERGED');
+        seen.add(gitPath);
+        if (mode === '160000')
+            throw coded('CHECKPOINT_GITLINK_UNSUPPORTED', `Gitlink/submodule is outside checkpoint coverage: ${gitPath}`);
+        const relGit = prefix ? (gitPath === prefix ? '' : gitPath.startsWith(`${prefix}/`) ? gitPath.slice(prefix.length + 1) : null) : gitPath;
+        if (!relGit)
+            continue;
+        const relative = safeRelative(relGit);
+        const absolute = absoluteFromRelative(workspace.canonicalRoot, relative);
+        let stat;
+        try {
+            stat = await lstat(absolute);
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        const mustCapture = dirty.has(gitPath) || stat.isSymbolicLink() || !stat.isFile();
+        if (mustCapture) {
+            const actual = await captureActualFile(workspace, absolute, relative, blobRoot, budget, mode === '100755');
+            if (actual)
+                entries[relative] = actual;
+            continue;
+        }
+        consumeEntry(budget);
+        await assertExistingPathContained(workspace, absolute);
+        entries[relative] = { kind: 'file', source: 'git', ref: oid, size: stat.size, mode: stat.mode & 0o777, executable: mode === '100755', gitPath };
+    }
+    for (const gitPath of nulList(untrackedRaw)) {
+        const relGit = prefix ? (gitPath.startsWith(`${prefix}/`) ? gitPath.slice(prefix.length + 1) : null) : gitPath;
+        if (!relGit)
+            continue;
+        const relative = safeRelative(relGit);
+        if (entries[relative])
+            continue;
+        const actual = await captureActualFile(workspace, absoluteFromRelative(workspace.canonicalRoot, relative), relative, blobRoot, budget);
+        if (actual)
+            entries[relative] = actual;
+    }
+    return { capturedAt: new Date().toISOString(), workspace: { canonicalRoot: workspace.canonicalRoot, identityHash: workspace.identityHash, gitRoot }, entries, git: { root: gitRoot, head, indexHash, worktreeSemanticsHash }, coverage: { tracked: true, untrackedNonIgnored: true, ignoredUntracked: false, gitMetadataRestored: false }, exclusions: ['Untracked files ignored by Git are outside rollback coverage.', 'Empty-directory existence is outside rollback coverage.', 'Git refs, index and object database are observed for conflict evidence but are not restored.'] };
+}
+async function captureNonGit(workspace, blobRoot, budget) {
+    const entries = {};
+    async function preflight(dirname, relativeDir) {
+        const rows = await readdir(dirname, { withFileTypes: true });
+        rows.sort((a, b) => a.name.localeCompare(b.name));
+        for (const row of rows) {
+            const relative = safeRelative(relativeDir ? `${relativeDir}/${row.name}` : row.name);
+            const absolute = path.join(dirname, row.name);
+            if (row.isDirectory()) {
+                await assertExistingPathContained(workspace, absolute);
+                await preflight(absolute, relative);
+                continue;
+            }
+            let stat;
+            try {
+                stat = await lstat(absolute);
+            }
+            catch (error) {
+                if (error?.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            consumeEntry(budget);
+            if (stat.isSymbolicLink()) {
+                let canonical;
+                try {
+                    canonical = await realpath(absolute);
+                }
+                catch {
+                    throw coded('CHECKPOINT_SYMLINK_ESCAPE', `Checkpoint symlink cannot be resolved safely: ${relative}`);
+                }
+                if (!inside(workspace.canonicalRoot, canonical))
+                    throw coded('CHECKPOINT_SYMLINK_ESCAPE', `Checkpoint symlink escapes workspace: ${relative}`);
+                continue;
+            }
+            if (!stat.isFile())
+                throw coded('CHECKPOINT_SPECIAL_FILE_UNSUPPORTED', `Unsupported workspace entry: ${relative}`);
+            await assertExistingPathContained(workspace, absolute);
+            consumeFileBudget(budget, stat.size);
+        }
+    }
+    await preflight(workspace.canonicalRoot, '');
+    budget.entries = 0;
+    budget.storedBytes = 0;
+    async function walk(dirname, relativeDir) {
+        const rows = await readdir(dirname, { withFileTypes: true });
+        rows.sort((a, b) => a.name.localeCompare(b.name));
+        for (const row of rows) {
+            const relative = safeRelative(relativeDir ? `${relativeDir}/${row.name}` : row.name);
+            const absolute = path.join(dirname, row.name);
+            if (row.isDirectory()) {
+                await assertExistingPathContained(workspace, absolute);
+                await walk(absolute, relative);
+                continue;
+            }
+            const actual = await captureActualFile(workspace, absolute, relative, blobRoot, budget);
+            if (actual)
+                entries[relative] = actual;
+        }
+    }
+    await walk(workspace.canonicalRoot, '');
+    return { capturedAt: new Date().toISOString(), workspace: { canonicalRoot: workspace.canonicalRoot, identityHash: workspace.identityHash, gitRoot: null }, entries, git: null, coverage: { tracked: false, untrackedNonIgnored: true, ignoredUntracked: true, gitMetadataRestored: false }, exclusions: ['Filesystem metadata other than file content, executable bit and symlink target is outside rollback coverage.', 'Empty-directory existence is outside rollback coverage.'] };
+}
+export async function captureWorkspaceSnapshot({ projectRoot, blobRoot, limits = CHECKPOINT_LIMITS }) {
+    const workspace = await resolveWorkspaceIdentity({ projectRoot });
+    await ensurePrivateDir(blobRoot);
+    const canonicalBlobRoot = await realpath(blobRoot);
+    if (inside(workspace.canonicalRoot, canonicalBlobRoot))
+        throw coded('CHECKPOINT_STORE_INSIDE_WORKSPACE');
+    const budget = { entries: 0, storedBytes: 0, limits };
+    return workspace.gitRoot ? captureGit(workspace, canonicalBlobRoot, budget) : captureNonGit(workspace, canonicalBlobRoot, budget);
+}
+export function checkpointMutationAllowed(mode) { return mode !== 'plan'; }
+export function extractWorkspaceWriteEvidence(raw) {
+    if (!raw || typeof raw !== 'object')
+        return [];
+    const row = raw;
+    if (row.type !== 'StateDelta' || !Array.isArray(row.delta))
+        return [];
+    const out = [];
+    for (const item of row.delta) {
+        const pointer = typeof item?.path === 'string' ? item.path : '';
+        if (!pointer.startsWith('/file/'))
+            continue;
+        let relative;
+        try {
+            relative = safeRelative(pointer.slice('/file/'.length));
+        }
+        catch {
+            continue;
+        }
+        const before = item.prima === null ? null : typeof item.prima === 'string' ? sha256(item.prima) : null;
+        const after = typeof item.value === 'string' ? sha256(item.value) : null;
+        out.push({ path: relative, existedBefore: item.op === 'replace', beforeHash: before, afterHash: after });
+    }
+    return out;
+}
+export function sameSnapshotEntry(left, right) {
+    if (!left || !right)
+        return left === right;
+    if (left.kind !== right.kind)
+        return false;
+    if (left.kind === 'symlink' && right.kind === 'symlink')
+        return left.target === right.target;
+    if (left.kind === 'file' && right.kind === 'file')
+        return left.source === right.source && left.ref === right.ref && left.mode === right.mode && left.executable === right.executable;
+    return false;
+}
+export function sameGitSnapshot(left, right) { return left === null && right === null || Boolean(left && right && left.root === right.root && left.head === right.head && left.indexHash === right.indexHash && left.worktreeSemanticsHash === right.worktreeSemanticsHash); }
+export async function materializeSnapshotFile(snapshot, entry, blobRoot, destination) {
+    await mkdir(path.dirname(destination), { recursive: true, mode: 0o700 });
+    if (entry.source === 'blob') {
+        const source = path.join(blobRoot, entry.ref);
+        const data = await readFile(source);
+        if (sha256(data) !== entry.ref)
+            throw coded('CHECKPOINT_BLOB_CORRUPT');
+        await copyFile(source, destination);
+        await durableFile(destination);
+        if (process.platform !== 'win32')
+            await chmod(destination, entry.mode);
+        return;
+    }
+    if (!snapshot.git || !entry.gitPath)
+        throw coded('CHECKPOINT_GIT_REFERENCE_INVALID');
+    await new Promise((resolve, reject) => {
+        const child = spawn('git', ['-c', 'core.quotepath=false', 'cat-file', '--filters', `--path=${entry.gitPath}`, entry.ref], { cwd: snapshot.git.root, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        const stream = createWriteStream(destination, { mode: entry.mode });
+        const errors = [];
+        let childDone = false, streamDone = false, failed = false;
+        const finish = () => { if (!failed && childDone && streamDone)
+            resolve(); };
+        child.stderr.on('data', (chunk) => errors.push(chunk));
+        child.on('error', error => { failed = true; reject(error); });
+        stream.on('error', error => { failed = true; reject(error); });
+        stream.on('close', () => { streamDone = true; finish(); });
+        child.stdout.pipe(stream);
+        child.on('close', code => { if (code !== 0) {
+            failed = true;
+            reject(coded('CHECKPOINT_GIT_OBJECT_UNAVAILABLE', Buffer.concat(errors).toString('utf8').trim()));
+            return;
+        } childDone = true; finish(); });
+    });
+    await durableFile(destination);
+    if (process.platform !== 'win32')
+        await chmod(destination, entry.mode);
+}

package/dist/workspace/restore.js

@@ -0,0 +1,232 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, copyFile, mkdir, rename, rm, symlink } from 'node:fs/promises';
+import path from 'node:path';
+import { durableFile, materializeSnapshotFile, sameGitSnapshot, sameSnapshotEntry } from "./checkpoint.js";
+function coded(code, message = code, details = {}) { return Object.assign(new Error(message === code ? code : `${code}: ${message}`), { code, details }); }
+function stateAt(snapshot, relative) { return snapshot.entries[relative]; }
+function changedPaths(left, right) { return [...new Set([...Object.keys(left.entries), ...Object.keys(right.entries)])].filter(relative => !sameSnapshotEntry(stateAt(left, relative), stateAt(right, relative))).sort(); }
+function absolute(root, relative) { const candidate = path.resolve(root, ...relative.split('/')); const rel = path.relative(root, candidate); if (rel.startsWith(`..${path.sep}`) || rel === '..' || path.isAbsolute(rel))
+    throw coded('CHECKPOINT_PATH_INVALID'); return candidate; }
+function assertNoStructuralTransition(left, right) {
+    const leftKeys = Object.keys(left.entries), rightKeys = Object.keys(right.entries);
+    for (const relative of leftKeys)
+        if (rightKeys.some(candidate => candidate.startsWith(`${relative}/`)))
+            throw coded('CHECKPOINT_STRUCTURAL_TRANSITION_UNSUPPORTED', `Cannot safely replace file/symlink ${relative} with a directory tree.`);
+    for (const relative of rightKeys)
+        if (leftKeys.some(candidate => candidate.startsWith(`${relative}/`)))
+            throw coded('CHECKPOINT_STRUCTURAL_TRANSITION_UNSUPPORTED', `Cannot safely replace directory tree ${relative} with a file/symlink.`);
+}
+function snapshotsFor(record, direction) {
+    if (record.state === 'open' || !record.post)
+        throw coded('CHECKPOINT_NOT_FINALIZED');
+    if (!record.reversible)
+        throw coded(record.nonReversibleReason ?? 'CHECKPOINT_NOT_REVERSIBLE');
+    if (direction === 'undo' && record.state !== 'complete')
+        throw coded('CHECKPOINT_STATE_INVALID');
+    if (direction === 'redo' && record.state !== 'undone')
+        throw coded('CHECKPOINT_STATE_INVALID');
+    const pair = direction === 'undo' ? { source: record.post, target: record.pre } : { source: record.pre, target: record.post };
+    assertNoStructuralTransition(pair.source, pair.target);
+    return pair;
+}
+function assertGitMetadata(current, expected) { if (!sameGitSnapshot(current.git, expected.git))
+    throw coded('CHECKPOINT_GIT_METADATA_CONFLICT', 'Git ref/index state changed since this checkpoint boundary.'); }
+function assertCurrentMatches(current, expected, paths, code = 'CHECKPOINT_CONFLICT') {
+    for (const relative of paths)
+        if (!sameSnapshotEntry(stateAt(current, relative), stateAt(expected, relative)))
+            throw coded(code, `Workspace changed outside the checkpoint at ${relative}.`, { path: relative });
+}
+function assertCurrentMatchesEither(current, left, right, paths) {
+    for (const relative of paths) {
+        const now = stateAt(current, relative);
+        if (!sameSnapshotEntry(now, stateAt(left, relative)) && !sameSnapshotEntry(now, stateAt(right, relative)))
+            throw coded('CHECKPOINT_RECOVERY_CONFLICT', `Cannot recover interrupted restore because ${relative} changed externally.`, { path: relative });
+    }
+}
+async function stageTargets(store, snapshot, paths, token) {
+    const root = path.join(store.rootDir, 'restore-staging', token);
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const staged = new Map();
+    let index = 0;
+    try {
+        for (const relative of paths) {
+            const entry = stateAt(snapshot, relative);
+            if (!entry)
+                continue;
+            if (entry.kind === 'symlink') {
+                staged.set(relative, { kind: 'symlink', target: entry.target });
+                continue;
+            }
+            const temp = path.join(root, String(index++));
+            await materializeSnapshotFile(snapshot, entry, store.blobRoot, temp);
+            staged.set(relative, { kind: 'file', path: temp, entry });
+        }
+        return { root, staged };
+    }
+    catch (error) {
+        await rm(root, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+}
+async function placeTemp(temp, target) {
+    try {
+        await rename(temp, target);
+    }
+    catch (error) {
+        if (!['EEXIST', 'EPERM', 'ENOTEMPTY'].includes(String(error?.code)))
+            throw error;
+        await rm(target, { force: true });
+        await rename(temp, target);
+    }
+}
+async function applyStaged(snapshot, paths, staged, token) {
+    let index = 0;
+    for (const relative of paths) {
+        const target = absolute(snapshot.workspace.canonicalRoot, relative), entry = stateAt(snapshot, relative);
+        if (!entry) {
+            await rm(target, { force: true });
+            continue;
+        }
+        await mkdir(path.dirname(target), { recursive: true });
+        const temp = path.join(path.dirname(target), `.${path.basename(target)}.talos-checkpoint-${token}-${index++}.tmp`);
+        await rm(temp, { force: true });
+        const prepared = staged.get(relative);
+        if (!prepared)
+            throw coded('CHECKPOINT_RESTORE_STAGE_MISSING');
+        if (prepared.kind === 'symlink')
+            await symlink(prepared.target, temp);
+        else {
+            await copyFile(prepared.path, temp);
+            if (process.platform !== 'win32')
+                await chmod(temp, prepared.entry.mode);
+            await durableFile(temp);
+        }
+        await placeTemp(temp, target);
+    }
+}
+async function applySnapshot(store, snapshot, paths) { const token = randomUUID(), bundle = await stageTargets(store, snapshot, paths, token); try {
+    await applyStaged(snapshot, paths, bundle.staged, token);
+}
+finally {
+    await rm(bundle.root, { recursive: true, force: true }).catch(() => { });
+} }
+async function recoverPendingRestore(store) {
+    const tx = await store.readRestoreTransaction();
+    if (!tx)
+        return;
+    const record = await store.show(tx.checkpointId);
+    if (record.state === tx.expectedFinalState) {
+        await store.clearRestoreTransaction();
+        return;
+    }
+    if (!record.post)
+        throw coded('CHECKPOINT_RECOVERY_INVALID');
+    const source = tx.direction === 'undo' ? record.post : record.pre, target = tx.direction === 'undo' ? record.pre : record.post;
+    assertNoStructuralTransition(source, target);
+    const current = await store.capture();
+    assertGitMetadata(current, source);
+    assertCurrentMatchesEither(current, source, target, tx.paths);
+    await applySnapshot(store, source, tx.paths);
+    await store.clearRestoreTransaction();
+}
+async function restore({ store, id, direction }) {
+    return store.withRestoreLock(async () => {
+        await recoverPendingRestore(store);
+        const requested = id ? await store.show(id) : await store.latest(direction === 'undo' ? 'complete' : 'undone');
+        if (!requested)
+            throw coded('CHECKPOINT_NOT_FOUND');
+        const { source, target } = snapshotsFor(requested, direction);
+        const paths = changedPaths(source, target);
+        const current = await store.capture();
+        assertGitMetadata(current, source);
+        assertCurrentMatches(current, source, paths);
+        const token = randomUUID(), bundle = await stageTargets(store, target, paths, token);
+        try {
+            const currentAgain = await store.capture();
+            assertGitMetadata(currentAgain, source);
+            assertCurrentMatches(currentAgain, source, paths);
+            const expectedFinalState = direction === 'undo' ? 'undone' : 'complete';
+            const tx = { schema: 'talos.cli.checkpoint-restore.v1', checkpointId: requested.id, direction, expectedFinalState, paths, createdAt: new Date().toISOString() };
+            await store.writeRestoreTransaction(tx);
+            try {
+                await applyStaged(target, paths, bundle.staged, token);
+            }
+            catch (error) {
+                try {
+                    await applySnapshot(store, source, paths);
+                    await store.clearRestoreTransaction();
+                }
+                catch (rollback) {
+                    throw coded('CHECKPOINT_RESTORE_ROLLBACK_FAILED', rollback instanceof Error ? rollback.message : String(rollback));
+                }
+                throw error;
+            }
+            const at = new Date().toISOString();
+            const updated = { ...requested, state: expectedFinalState, transitions: [...requested.transitions, { kind: direction, at }] };
+            await store.replace(updated);
+            await store.clearRestoreTransaction();
+            return updated;
+        }
+        finally {
+            await rm(bundle.root, { recursive: true, force: true }).catch(() => { });
+        }
+    });
+}
+export async function undoCheckpoint({ store, id }) { return restore({ store, ...(id ? { id } : {}), direction: 'undo' }); }
+export async function redoCheckpoint({ store, id }) { return restore({ store, ...(id ? { id } : {}), direction: 'redo' }); }
+/*
+ * R5b D3 (owner decision Q-R5-13 and the owner's answers of 2026-09-25): the /undo picker goes BACK TO A POINT — the chosen
+ * checkpoint and every newer one of the same session are undone, newest first (Claude Code's /rewind, Hermes's /rollback) —
+ * and re-applies an undone point: it and every older undone one of the session, oldest first. Every step is the checked,
+ * locked restore above; a step that fails puts back the steps already taken (in reverse), so the files never stay between two
+ * points, and the step's own error (the file that changed outside TALOS) is what the person reads. The whole range is checked
+ * first: a checkpoint that cannot be restored refuses the step before any file is touched.
+ */
+function assertRestorable(rows) {
+    for (const row of rows) {
+        if (row.state === 'open' || !row.post)
+            throw coded('CHECKPOINT_NOT_FINALIZED');
+        if (!row.reversible)
+            throw coded(row.nonReversibleReason ?? 'CHECKPOINT_NOT_REVERSIBLE');
+    }
+}
+async function stepThrough(steps, forward, back) {
+    const done = [];
+    for (const step of steps) {
+        try {
+            done.push(await forward(step.id));
+        }
+        catch (error) {
+            for (const taken of [...done].reverse()) {
+                try {
+                    await back(taken.id);
+                }
+                catch (rollback) {
+                    throw coded('CHECKPOINT_RESTORE_ROLLBACK_FAILED', rollback instanceof Error ? rollback.message : String(rollback), { checkpointId: taken.id });
+                }
+            }
+            throw error;
+        }
+    }
+    return done;
+}
+export async function rewindToCheckpoint({ store, id }) {
+    const target = await store.show(id);
+    if (target.state !== 'complete')
+        throw coded('CHECKPOINT_STATE_INVALID');
+    const session = (await store.list()).filter(row => row.sessionId === target.sessionId);
+    const at = session.findIndex(row => row.id === target.id);
+    const range = session.slice(0, at + 1).filter(row => row.state !== 'undone');
+    assertRestorable(range);
+    return stepThrough(range, step => undoCheckpoint({ store, id: step }), step => redoCheckpoint({ store, id: step }));
+}
+export async function reapplyToCheckpoint({ store, id }) {
+    const target = await store.show(id);
+    if (target.state !== 'undone')
+        throw coded('CHECKPOINT_STATE_INVALID');
+    const session = (await store.list()).filter(row => row.sessionId === target.sessionId);
+    const at = session.findIndex(row => row.id === target.id);
+    const range = session.slice(at).filter(row => row.state === 'undone').reverse();
+    assertRestorable(range);
+    return stepThrough(range, step => redoCheckpoint({ store, id: step }), step => undoCheckpoint({ store, id: step }));
+}