@xenosystem/agent-interface-host 0.1.3

package/dist/engineering/EngineeringWorkbenchService.js

@@ -0,0 +1,2301 @@
+import { randomUUID } from 'crypto';
+import { spawn } from 'child_process';
+import { commandSucceeded } from '../isolation/CommandExecution.js';
+import { LocalCommandExecutor } from '../isolation/LocalCommandExecutor.js';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, unlinkSync, writeFileSync, } from 'fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'path';
+import { isPathInside, hashText, resolveRootDirectory, safeReadJson, safeWriteJson, workspaceIndexDirectory, } from '../codebase/codeUtils.js';
+import { getRuntimeEventStore } from '../runtime/RuntimeEventStore.js';
+import { buildPatchReviewHunks, composePatchSnapshot, effectivePatchDecisions, } from './patchReview.js';
+const MAX_GIT_OUTPUT = 1_500_000;
+const DEFAULT_RUN_OUTPUT = 2_000_000;
+const MAX_STORED_RUNS = 80;
+const MAX_STORED_BACKGROUND_RUNS = 80;
+const MAX_STORED_PATCH_REVIEWS = 120;
+const MAX_CHECKPOINT_COMPARE_PATCHES = 40;
+const MAX_TRANSACTIONAL_SNAPSHOT_BYTES = 1_000_000;
+const MAX_TRANSACTIONAL_SNAPSHOT_CHARS = 250_000;
+export class EngineeringWorkbenchService {
+    activeBackgroundRuns = new Map();
+    runtimeEventStore;
+    /**
+     * The landing queue, when the composition mounted one.
+     *
+     * Optional in the same way the host's observation service is: landing consults
+     * observed diffs and verification results, and a host with neither has nothing
+     * to gate with. Answering `unavailable` is honest; answering "landed" after
+     * consulting nothing is the merge-debt failure with extra steps.
+     */
+    landingService;
+    constructor(options = {}) {
+        this.runtimeEventStore = options.runtimeEventStore || getRuntimeEventStore();
+        this.landingService = options.landingService;
+    }
+    /** Mounted after construction when the composition builds the queue later. */
+    configureLandingService(landingService) {
+        this.landingService = landingService;
+    }
+    configureRuntimeEventStore(runtimeEventStore) {
+        this.runtimeEventStore = runtimeEventStore;
+    }
+    close() {
+        for (const active of this.activeBackgroundRuns.values()) {
+            active.stopRequested = true;
+            killProcessTree(active.child);
+        }
+    }
+    async request(method, input) {
+        if (method === 'engineering.git.status')
+            return await this.gitStatus(input);
+        if (method === 'engineering.git.diff')
+            return await this.gitDiff(input);
+        if (method === 'engineering.git.stage')
+            return await this.gitStage(input);
+        if (method === 'engineering.git.unstage')
+            return await this.gitUnstage(input);
+        if (method === 'engineering.git.commit')
+            return await this.gitCommit(input);
+        if (method === 'engineering.git.branch')
+            return await this.gitBranch(input);
+        if (method === 'engineering.git.push')
+            return await this.gitPush(input);
+        if (method === 'engineering.git.pr.create')
+            return await this.gitCreatePullRequest(input);
+        if (method === 'engineering.landing.enqueue')
+            return this.landing('enqueue', input);
+        if (method === 'engineering.landing.remove')
+            return this.landing('remove', input);
+        if (method === 'engineering.landing.status')
+            return this.landing('status', input);
+        if (method === 'engineering.landing.land')
+            return await this.landing('land', input);
+        if (method === 'engineering.landing.verify')
+            return await this.landing('verify', input);
+        if (method === 'engineering.checks.discover')
+            return this.discoverChecks(input);
+        if (method === 'engineering.checks.run')
+            return await this.runCheck(input);
+        if (method === 'engineering.background.start')
+            return this.startBackgroundCheck(input);
+        if (method === 'engineering.background.list')
+            return this.listBackgroundRuns(input);
+        if (method === 'engineering.background.output')
+            return this.readBackgroundRunOutput(input);
+        if (method === 'engineering.background.stop')
+            return this.stopBackgroundRun(input);
+        if (method === 'engineering.runs.list')
+            return this.listRuns(input);
+        if (method === 'engineering.diagnostics')
+            return await this.diagnostics(input);
+        if (method === 'engineering.patches.list')
+            return this.listPatchReviews(input);
+        if (method === 'engineering.patches.enqueue')
+            return this.enqueuePatchReview(input);
+        if (method === 'engineering.patches.update')
+            return this.updatePatchReview(input);
+        if (method === 'engineering.patches.review')
+            return this.reviewPatchSelection(input);
+        if (method === 'engineering.checkpoints.list')
+            return this.listCheckpoints(input);
+        if (method === 'engineering.checkpoints.compare')
+            return this.compareCheckpoints(input);
+        if (method === 'engineering.checkpoints.restore')
+            return this.restoreCheckpoint(input);
+        if (method === 'engineering.sessions.list')
+            return this.listSessions(input);
+        if (method === 'engineering.runtime.timeline')
+            return this.runtimeTimeline(input);
+        throw new Error(`Unsupported engineering workbench method: ${String(method)}`);
+    }
+    async gitStatus(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            if (!await this.isGitRepo(rootDirectory)) {
+                return { success: true, isGitRepo: false, rootDirectory, clean: true, files: [] };
+            }
+            const [statusResult, numstatResult] = await Promise.all([
+                runProcess('git', ['status', '--porcelain=v1', '-b'], rootDirectory, 8000, MAX_GIT_OUTPUT),
+                runProcess('git', ['diff', '--numstat'], rootDirectory, 8000, MAX_GIT_OUTPUT),
+            ]);
+            if (!statusResult.success && statusResult.exitCode !== 0) {
+                return {
+                    success: false,
+                    isGitRepo: true,
+                    rootDirectory,
+                    clean: true,
+                    files: [],
+                    error: statusResult.error || statusResult.stderr || 'Failed to read git status.',
+                };
+            }
+            const branch = parseBranch(statusResult.stdout);
+            const statsByPath = parseNumstat(numstatResult.stdout);
+            const files = parseGitStatusFiles(rootDirectory, statusResult.stdout);
+            for (const file of files) {
+                const stats = statsByPath.get(file.relativePath);
+                if (stats) {
+                    file.additions = stats.additions;
+                    file.deletions = stats.deletions;
+                }
+            }
+            return {
+                success: true,
+                isGitRepo: true,
+                rootDirectory,
+                branch: branch.branch,
+                upstream: branch.upstream,
+                ahead: branch.ahead,
+                behind: branch.behind,
+                clean: files.length === 0,
+                files,
+                raw: statusResult.stdout,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                isGitRepo: false,
+                rootDirectory: request.rootDirectory || '',
+                clean: true,
+                files: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async gitDiff(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            if (!await this.isGitRepo(rootDirectory)) {
+                return { success: true, isGitRepo: false, rootDirectory, diff: '', truncated: false };
+            }
+            const safePaths = this.validateRelativePaths(rootDirectory, request.paths || []);
+            const args = ['diff', ...(request.staged ? ['--staged'] : []), '--', ...safePaths];
+            const result = await runProcess('git', args, rootDirectory, 12000, request.maxBytes || MAX_GIT_OUTPUT);
+            return {
+                success: result.success || result.exitCode === 1 || result.exitCode === 0,
+                isGitRepo: true,
+                rootDirectory,
+                diff: result.stdout,
+                truncated: result.truncated,
+                error: result.success || result.exitCode === 1 || result.exitCode === 0 ? undefined : result.error || result.stderr,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                isGitRepo: false,
+                rootDirectory: request.rootDirectory || '',
+                diff: '',
+                truncated: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async gitStage(request) {
+        return this.runGitMutation(request, ['add', '--', ...this.validateRelativePaths(this.resolveRoot(request), request.paths)]);
+    }
+    async gitUnstage(request) {
+        return this.runGitMutation(request, ['restore', '--staged', '--', ...this.validateRelativePaths(this.resolveRoot(request), request.paths)]);
+    }
+    /**
+     * Create or switch to a branch.
+     *
+     * Local and reversible, so unlike push and PR creation it needs no
+     * confirmation. The NAME is validated rather than trusted: it reaches a
+     * command line, and git itself accepts things a caller rarely means —
+     * a leading dash reads as a flag.
+     */
+    async gitBranch(request) {
+        const name = String(request.name || '').trim();
+        const invalid = validateRefName(name);
+        if (invalid)
+            return this.gitFailure(request, invalid);
+        // `git switch`, never `git checkout`. `checkout` is overloaded: it takes
+        // branches AND pathspecs, so `checkout -- main` restores a FILE called main
+        // rather than switching branch — which is what the first version of this
+        // did, and the test caught. `switch` only ever means a branch, so the
+        // ambiguity is not something to be careful about; it is gone.
+        if (request.create === false) {
+            return this.runGitMutation(request, ['switch', name]);
+        }
+        const startPoint = String(request.startPoint || '').trim();
+        if (startPoint) {
+            const invalidStart = validateRefName(startPoint);
+            if (invalidStart)
+                return this.gitFailure(request, invalidStart);
+            return this.runGitMutation(request, ['switch', '-c', name, startPoint]);
+        }
+        return this.runGitMutation(request, ['switch', '-c', name]);
+    }
+    /**
+     * Push a branch to a remote.
+     *
+     * 🔴 The first verb here whose effect leaves the machine, and the first that
+     * refuses without `confirmed`. The host cannot otherwise distinguish an agent
+     * deciding to publish from a human asking it to, and those are different acts
+     * with different consequences — a push is visible to other people and, unlike
+     * every other verb on this surface, cannot be undone locally.
+     *
+     * There is no `--force`, by construction rather than by policy: it destroys
+     * history others may already hold, every XENO repo rule forbids it, and a
+     * command that cannot express it cannot be talked into it.
+     */
+    async gitPush(request) {
+        const base = await this.gitStatus(request);
+        if (request.confirmed !== true) {
+            return { ...base, success: false, pushed: false, error: 'Pushing publishes work to a remote and was not confirmed. Send confirmed: true from a human action.' };
+        }
+        if (!base.isGitRepo)
+            return { ...base, pushed: false };
+        const remote = String(request.remote || 'origin').trim();
+        const invalidRemote = validateRemoteName(remote);
+        if (invalidRemote)
+            return { ...base, success: false, pushed: false, error: invalidRemote };
+        const branch = String(request.branch || base.branch || '').trim();
+        const invalidBranch = validateRefName(branch);
+        if (invalidBranch)
+            return { ...base, success: false, pushed: false, error: invalidBranch };
+        const args = ['push'];
+        if (request.setUpstream)
+            args.push('--set-upstream');
+        args.push(remote, branch);
+        const result = await this.runGitMutation(request, args);
+        return {
+            ...result,
+            pushed: result.success,
+            remote,
+            pushedBranch: branch,
+        };
+    }
+    /**
+     * Open a pull request, through the `gh` CLI.
+     *
+     * `gh` rather than a GitHub API client on purpose: it already holds the
+     * operator's credential, so this adds no token storage, no scope decisions and
+     * no second place a credential can leak. The cost is a dependency on `gh`
+     * being installed, which is reported plainly when it is not — a missing tool
+     * is a legible failure, while a stored token is a permanent liability.
+     *
+     * Outward-facing, so confirmed like a push. `draft` defaults to TRUE: opening
+     * a review request notifies people, and an action taken on someone's behalf
+     * should default to the quieter form.
+     */
+    async gitCreatePullRequest(request) {
+        if (request.confirmed !== true) {
+            return { success: false, created: false, error: 'Opening a pull request notifies reviewers and was not confirmed. Send confirmed: true from a human action.' };
+        }
+        const title = String(request.title || '').trim();
+        if (title.length < 3)
+            return { success: false, created: false, error: 'A pull request title of at least 3 characters is required.' };
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            if (!await this.isGitRepo(rootDirectory)) {
+                return { success: false, created: false, error: 'Workspace is not a git repository.' };
+            }
+            const args = ['pr', 'create', '--title', title, '--body', String(request.body || '')];
+            // Draft unless explicitly told otherwise — see the note above.
+            if (request.draft !== false)
+                args.push('--draft');
+            for (const [flag, value] of [['--base', request.base], ['--head', request.head]]) {
+                const ref = String(value || '').trim();
+                if (!ref)
+                    continue;
+                const invalid = validateRefName(ref);
+                if (invalid)
+                    return { success: false, created: false, error: invalid };
+                args.push(flag, ref);
+            }
+            const result = await runProcess('gh', args, rootDirectory, 60000, MAX_GIT_OUTPUT);
+            if (!result.success) {
+                return {
+                    success: false,
+                    created: false,
+                    error: result.error || result.stderr || 'Failed to create the pull request. Is the GitHub CLI installed and authenticated?',
+                };
+            }
+            const url = /https:\/\/\S+/.exec(result.stdout)?.[0];
+            const number = url ? Number(/\/(\d+)(?:\s|$)/.exec(url)?.[1]) : Number.NaN;
+            return {
+                success: true,
+                created: true,
+                ...(url ? { url } : {}),
+                ...(Number.isFinite(number) ? { number } : {}),
+            };
+        }
+        catch (err) {
+            return { success: false, created: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    /**
+     * Routes a landing call, or says plainly that landing is not mounted.
+     *
+     * 🔴 An unmounted queue reports `success: false` with a reason, never an empty
+     * queue. An empty queue reads as "nothing is waiting", which is a fact about
+     * the world; "no queue exists here" is a fact about this installation. A
+     * caller that cannot tell them apart will wait for a landing that can never
+     * be attempted.
+     */
+    landing(operation, input) {
+        const service = this.landingService;
+        if (!service) {
+            const unavailable = {
+                success: false,
+                entries: [],
+                fingerprint: 'empty',
+                error: 'Landing is not available: this host has no landing queue mounted.',
+            };
+            if (operation === 'land') {
+                return Promise.resolve({ ...unavailable, landed: false, verdict: unavailable.error });
+            }
+            if (operation === 'verify') {
+                return Promise.resolve({ ...unavailable, verified: false, checks: [], problem: unavailable.error });
+            }
+            return unavailable;
+        }
+        if (operation === 'enqueue')
+            return service.enqueue(input);
+        if (operation === 'remove')
+            return service.remove(input);
+        if (operation === 'status')
+            return service.status(input);
+        if (operation === 'verify')
+            return service.verify(input);
+        return service.land(input);
+    }
+    /**
+     * The merge behind a landing — deliberately NOT a host method.
+     *
+     * There is no `engineering.git.merge` in the contract: a free-standing merge
+     * verb would sit beside the gate rather than behind it, and a gate that can be
+     * walked around is documentation. This is reachable only from
+     * `engineering.landing.land`, which runs it after the queue admitted the run.
+     *
+     * `--no-ff` on purpose. A landing is a decision, and a decision should appear
+     * in the history as one revertable commit rather than dissolving into trunk.
+     */
+    async gitMergeForLanding(request) {
+        const branch = String(request.branch || '').trim();
+        const invalid = validateRefName(branch);
+        if (invalid)
+            return { merged: false, error: invalid };
+        const result = await this.runGitMutation(request, ['merge', '--no-ff', '--no-edit', branch]);
+        return result.success ? { merged: true } : { merged: false, ...(result.error ? { error: result.error } : {}) };
+    }
+    /** A failed git response that still reports where it was looking. */
+    gitFailure(request, error) {
+        return { success: false, isGitRepo: false, rootDirectory: request.rootDirectory || '', clean: true, files: [], error };
+    }
+    async gitCommit(request) {
+        const message = String(request.message || '').trim();
+        if (message.length < 3) {
+            return {
+                success: false,
+                isGitRepo: false,
+                rootDirectory: request.rootDirectory || '',
+                clean: true,
+                files: [],
+                error: 'Commit message must be at least 3 characters.',
+            };
+        }
+        return this.runGitMutation(request, ['commit', '-m', message]);
+    }
+    discoverChecks(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const packagePath = join(rootDirectory, 'package.json');
+            if (!existsSync(packagePath)) {
+                return { success: true, rootDirectory, checks: [] };
+            }
+            const parsed = JSON.parse(readFileSync(packagePath, 'utf-8'));
+            const scripts = parsed.scripts && typeof parsed.scripts === 'object' ? parsed.scripts : {};
+            const checks = [];
+            for (const [scriptName, rawCommand] of Object.entries(scripts)) {
+                if (typeof rawCommand !== 'string')
+                    continue;
+                if (!/^[a-zA-Z0-9:_-]+$/.test(scriptName))
+                    continue;
+                const kind = classifyScript(scriptName, rawCommand);
+                if (!kind)
+                    continue;
+                const invocation = npmScriptInvocation(scriptName);
+                checks.push({
+                    id: `script:${scriptName}`,
+                    kind,
+                    name: scriptName,
+                    command: invocation.command,
+                    args: invocation.args,
+                    packageScript: scriptName,
+                });
+            }
+            checks.sort((a, b) => checkSortScore(a) - checkSortScore(b) || a.name.localeCompare(b.name));
+            return { success: true, rootDirectory, checks, packageManager: 'npm' };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                checks: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async runCheck(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const check = this.discoverChecks(request).checks.find((item) => item.id === request.checkId);
+            if (!check)
+                return { success: false, error: 'Check was not discovered for this workspace.' };
+            const startedAt = Date.now();
+            const outputLimit = Math.max(20_000, Math.min(request.maxOutputBytes || DEFAULT_RUN_OUTPUT, 5_000_000));
+            const result = await runProcess(check.command, check.args, rootDirectory, Math.max(5_000, Math.min(request.timeoutMs || 10 * 60_000, 30 * 60_000)), outputLimit);
+            const endedAt = Date.now();
+            const run = {
+                id: `eng-run-${startedAt}-${Math.random().toString(36).slice(2, 8)}`,
+                rootDirectory,
+                check,
+                startedAt,
+                endedAt,
+                durationMs: endedAt - startedAt,
+                success: result.success,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+                truncated: result.truncated,
+                error: result.error || (result.timedOut ? 'Check timed out.' : undefined),
+            };
+            this.appendRun(rootDirectory, run);
+            return { success: true, run };
+        }
+        catch (err) {
+            return { success: false, error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    listRuns(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            return { success: true, rootDirectory, runs: this.readRunStore(rootDirectory).runs };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                runs: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    startBackgroundCheck(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const check = this.discoverChecks(request).checks.find((item) => item.id === request.checkId);
+            if (!check)
+                return { success: false, rootDirectory, error: 'Check was not discovered for this workspace.' };
+            const startedAt = Date.now();
+            const outputLimit = Math.max(20_000, Math.min(request.maxOutputBytes || DEFAULT_RUN_OUTPUT, 5_000_000));
+            const run = {
+                id: `eng-bg-${startedAt}-${Math.random().toString(36).slice(2, 8)}`,
+                rootDirectory,
+                check,
+                status: 'running',
+                startedAt,
+                updatedAt: startedAt,
+                stdout: '',
+                stderr: '',
+                truncated: false,
+            };
+            const child = spawn(check.command, check.args, {
+                cwd: rootDirectory,
+                windowsHide: true,
+                shell: false,
+                env: process.env,
+            });
+            const active = {
+                run,
+                child,
+                outputLimit,
+                stopRequested: false,
+                finalized: false,
+            };
+            this.activeBackgroundRuns.set(run.id, active);
+            this.writeBackgroundRun(rootDirectory, run);
+            const append = (target, chunk) => {
+                const text = chunk.toString();
+                if (target === 'stdout')
+                    active.run.stdout += text;
+                else
+                    active.run.stderr += text;
+                if (active.run.stdout.length + active.run.stderr.length > active.outputLimit) {
+                    active.run.truncated = true;
+                    const keep = Math.max(4_000, Math.floor(active.outputLimit / 2));
+                    active.run.stdout = active.run.stdout.slice(-keep);
+                    active.run.stderr = active.run.stderr.slice(-keep);
+                }
+                active.run.updatedAt = Date.now();
+                this.writeBackgroundRun(rootDirectory, active.run);
+            };
+            const finalize = (status, exitCode, error) => {
+                if (active.finalized)
+                    return;
+                active.finalized = true;
+                const endedAt = Date.now();
+                active.run.status = status;
+                active.run.exitCode = exitCode;
+                active.run.error = error || active.run.error;
+                active.run.endedAt = endedAt;
+                active.run.updatedAt = endedAt;
+                active.run.durationMs = endedAt - active.run.startedAt;
+                this.activeBackgroundRuns.delete(active.run.id);
+                this.writeBackgroundRun(rootDirectory, active.run);
+                this.appendRun(rootDirectory, {
+                    id: active.run.id,
+                    rootDirectory,
+                    check: active.run.check,
+                    startedAt: active.run.startedAt,
+                    endedAt,
+                    durationMs: active.run.durationMs,
+                    success: status === 'completed',
+                    exitCode,
+                    stdout: active.run.stdout,
+                    stderr: active.run.stderr,
+                    truncated: active.run.truncated,
+                    error: active.run.error,
+                });
+            };
+            child.stdout.on('data', (chunk) => append('stdout', chunk));
+            child.stderr.on('data', (chunk) => append('stderr', chunk));
+            child.on('error', (err) => finalize('failed', null, err.message));
+            child.on('close', (code) => {
+                if (active.stopRequested)
+                    finalize('stopped', code, 'Background check stopped by user.');
+                else
+                    finalize(code === 0 ? 'completed' : 'failed', code);
+            });
+            return { success: true, rootDirectory, run };
+        }
+        catch (err) {
+            return { success: false, rootDirectory: request.rootDirectory || '', error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    listBackgroundRuns(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            return { success: true, rootDirectory, runs: this.readBackgroundRunStore(rootDirectory).runs };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                runs: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    readBackgroundRunOutput(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const runId = String(request.runId || '').trim();
+            if (!runId)
+                return { success: false, rootDirectory, error: 'runId is required.' };
+            const run = this.activeBackgroundRuns.get(runId)?.run
+                || this.readBackgroundRunStore(rootDirectory).runs.find((entry) => entry.id === runId);
+            if (!run)
+                return { success: false, rootDirectory, error: 'Background run was not found.' };
+            return { success: true, rootDirectory, run };
+        }
+        catch (err) {
+            return { success: false, rootDirectory: request.rootDirectory || '', error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    stopBackgroundRun(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const runId = String(request.runId || '').trim();
+            if (!runId)
+                return { success: false, rootDirectory, error: 'runId is required.' };
+            const active = this.activeBackgroundRuns.get(runId);
+            if (active) {
+                active.stopRequested = true;
+                active.run.status = 'stopped';
+                active.run.updatedAt = Date.now();
+                active.run.error = 'Background check stopped by user.';
+                this.writeBackgroundRun(rootDirectory, active.run);
+                killProcessTree(active.child);
+                return { success: true, rootDirectory, run: active.run };
+            }
+            const store = this.readBackgroundRunStore(rootDirectory);
+            const run = store.runs.find((entry) => entry.id === runId);
+            if (!run)
+                return { success: false, rootDirectory, error: 'Background run was not found.' };
+            if (run.status === 'running') {
+                const now = Date.now();
+                run.status = 'stopped';
+                run.updatedAt = now;
+                run.endedAt = now;
+                run.durationMs = now - run.startedAt;
+                run.error = 'Background process is no longer attached to this Hub session.';
+                this.writeBackgroundRun(rootDirectory, run);
+            }
+            return { success: true, rootDirectory, run };
+        }
+        catch (err) {
+            return { success: false, rootDirectory: request.rootDirectory || '', error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    async diagnostics(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const [git, discovery] = await Promise.all([
+                this.gitStatus(request),
+                Promise.resolve(this.discoverChecks(request)),
+            ]);
+            const recentRuns = this.readRunStore(rootDirectory).runs.slice(0, 12);
+            const backgroundRuns = this.readBackgroundRunStore(rootDirectory).runs.slice(0, 12);
+            const failedRuns = recentRuns.filter((run) => !run.success).length;
+            const activeBackgroundRuns = backgroundRuns.filter((run) => run.status === 'running').length;
+            const dirtyFiles = git.files?.length || 0;
+            const issues = collectDiagnosticIssues(rootDirectory, recentRuns, backgroundRuns);
+            const summaryParts = [
+                git.isGitRepo ? `${dirtyFiles} changed git file${dirtyFiles === 1 ? '' : 's'}` : 'not a git repository',
+                `${discovery.checks.length} runnable check${discovery.checks.length === 1 ? '' : 's'}`,
+                recentRuns.length ? `${failedRuns} failing recent run${failedRuns === 1 ? '' : 's'}` : 'no recent runs',
+                backgroundRuns.length ? `${activeBackgroundRuns} active background check${activeBackgroundRuns === 1 ? '' : 's'}` : 'no background checks',
+                issues.length ? `${issues.length} parsed diagnostic${issues.length === 1 ? '' : 's'}` : 'no parsed diagnostics',
+            ];
+            return {
+                success: true,
+                rootDirectory,
+                summary: summaryParts.join(' / '),
+                git,
+                checks: discovery.checks,
+                recentRuns,
+                backgroundRuns,
+                issues,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                summary: '',
+                checks: [],
+                recentRuns: [],
+                issues: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    listPatchReviews(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            return { success: true, rootDirectory, items: this.readPatchReviewStore(rootDirectory).items };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                items: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    enqueuePatchReview(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const diff = String(request.diff || '').trim();
+            if (!diff)
+                return { success: false, rootDirectory, error: 'Patch review diff is required.' };
+            const now = Date.now();
+            const store = this.readPatchReviewStore(rootDirectory);
+            const id = String(request.id || `patch-review-${now}-${Math.random().toString(36).slice(2, 8)}`);
+            const existing = store.items.find((item) => item.id === id);
+            const rawFiles = request.files || request.filesChanged || existing?.filesChanged || existing?.files || [];
+            const reviewFiles = rawFiles
+                .map((file) => String(file || '').trim())
+                .filter(Boolean)
+                .map((file) => isAbsolute(file) && isPathInside(file, rootDirectory)
+                ? relative(rootDirectory, file).replace(/\\/g, '/')
+                : file.replace(/\\/g, '/'));
+            const item = {
+                id,
+                rootDirectory,
+                title: String(request.title || existing?.title || 'Patch review').trim() || 'Patch review',
+                description: request.description || existing?.description,
+                diff,
+                files: this.validateRelativePaths(rootDirectory, reviewFiles),
+                filesChanged: this.validateRelativePaths(rootDirectory, reviewFiles),
+                summary: String(request.summary || request.title || existing?.summary || existing?.title || 'Patch review').trim() || 'Patch review',
+                timestamp: Number.isFinite(request.timestamp) ? Number(request.timestamp) : (existing?.timestamp || now),
+                conversationId: normalizeOptionalId(request.conversationId || existing?.conversationId),
+                requestId: normalizeOptionalId(request.requestId || existing?.requestId),
+                checkpointId: normalizeOptionalId(request.checkpointId || existing?.checkpointId),
+                testsRun: normalizeStringList(request.testsRun || existing?.testsRun || []),
+                finalSummary: request.finalSummary || existing?.finalSummary,
+                fileSnapshots: normalizePatchFileSnapshots(rootDirectory, request.fileSnapshots || existing?.fileSnapshots || []),
+                hunks: [],
+                decisions: normalizePatchReviewDecisions(existing?.decisions || []),
+                status: existing?.status || 'open',
+                notes: existing?.notes,
+                source: request.source || existing?.source || 'manual',
+                createdAt: existing?.createdAt || now,
+                updatedAt: now,
+            };
+            item.hunks = buildPatchReviewHunks(item.fileSnapshots || []);
+            store.items = [item, ...store.items.filter((entry) => entry.id !== item.id)].slice(0, MAX_STORED_PATCH_REVIEWS);
+            this.writePatchReviewStore(rootDirectory, store);
+            return { success: true, rootDirectory, item, items: store.items };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    updatePatchReview(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const id = String(request.id || '').trim();
+            if (!id)
+                return { success: false, rootDirectory, error: 'Patch review id is required.' };
+            const store = this.readPatchReviewStore(rootDirectory);
+            const item = store.items.find((entry) => entry.id === id);
+            if (!item)
+                return { success: false, rootDirectory, error: 'Patch review was not found.' };
+            item.status = normalizePatchReviewStatus(request.status, item.status);
+            item.notes = request.notes ?? item.notes;
+            item.updatedAt = Date.now();
+            this.writePatchReviewStore(rootDirectory, store);
+            return { success: true, rootDirectory, item, items: store.items };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    reviewPatchSelection(request) {
+        const empty = { selectedHunkIds: [], wouldChangeFiles: [] };
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const id = normalizeRequiredId(request.id, 'id');
+            const relativePath = this.validateRelativePaths(rootDirectory, [String(request.relativePath || '').replace(/\\/g, '/')])[0];
+            if (!relativePath)
+                return { success: false, rootDirectory, ...empty, error: 'A safe relative patch path is required.' };
+            if (request.action !== 'accept' && request.action !== 'reject' && request.action !== 'comment') {
+                return { success: false, rootDirectory, ...empty, error: 'Patch decision action must be accept, reject, or comment.' };
+            }
+            const store = this.readPatchReviewStore(rootDirectory);
+            const item = store.items.find((entry) => entry.id === id);
+            if (!item)
+                return { success: false, rootDirectory, ...empty, error: 'Patch review was not found.' };
+            item.fileSnapshots = normalizePatchFileSnapshots(rootDirectory, item.fileSnapshots || []);
+            item.hunks = buildPatchReviewHunks(item.fileSnapshots);
+            const decisions = normalizePatchReviewDecisions(item.decisions || []);
+            item.decisions = decisions;
+            const pathKey = reviewPathKey(relativePath);
+            const snapshot = item.fileSnapshots.find((entry) => reviewPathKey(entry.relativePath) === pathKey);
+            const pathHunks = item.hunks.filter((entry) => reviewPathKey(entry.relativePath) === pathKey);
+            const requestedHunk = request.hunkId
+                ? pathHunks.find((entry) => entry.id === request.hunkId)
+                : undefined;
+            if (request.action === 'comment') {
+                const comment = normalizeReviewComment(request.comment);
+                if (!comment)
+                    return { success: false, rootDirectory, ...empty, error: 'A non-empty review comment is required.' };
+                if (request.hunkId && !requestedHunk) {
+                    return { success: false, rootDirectory, ...empty, error: 'The selected patch hunk was not found.' };
+                }
+                const now = Date.now();
+                decisions.push({
+                    id: `patch-decision-${now}-${randomUUID()}`,
+                    relativePath,
+                    ...(requestedHunk ? { hunkId: requestedHunk.id } : {}),
+                    action: 'comment',
+                    comment,
+                    state: 'applied',
+                    createdAt: now,
+                    updatedAt: now,
+                });
+                item.decisions = decisions.slice(-1_000);
+                item.updatedAt = now;
+                this.writePatchReviewStore(rootDirectory, store);
+                return {
+                    success: true,
+                    rootDirectory,
+                    item,
+                    selectedHunkIds: requestedHunk ? [requestedHunk.id] : [],
+                    wouldChangeFiles: [],
+                    applied: true,
+                };
+            }
+            const conflicts = [];
+            if (!snapshot) {
+                conflicts.push({ relativePath, reason: 'selection_not_found', detail: 'The patch has no immutable snapshot for this file.' });
+            }
+            if (request.hunkId && !requestedHunk) {
+                conflicts.push({ relativePath, reason: 'selection_not_found', detail: 'The selected patch hunk was not found.' });
+            }
+            const effective = effectivePatchDecisions(decisions);
+            const targetHunks = request.hunkId
+                ? (requestedHunk ? [requestedHunk] : [])
+                : pathHunks.filter((hunk) => !effective.has(hunk.id));
+            for (const hunk of targetHunks) {
+                if (effective.has(hunk.id)) {
+                    conflicts.push({ relativePath, reason: 'already_decided', detail: `Patch hunk ${hunk.id} already has a final decision.` });
+                }
+            }
+            if (targetHunks.length === 0 && conflicts.length === 0) {
+                conflicts.push({ relativePath, reason: 'already_decided', detail: 'Every hunk in this file already has a final decision.' });
+            }
+            let expectedBefore;
+            let resulting;
+            let inspected;
+            if (snapshot && conflicts.length === 0) {
+                if (snapshot.originalExists === undefined || snapshot.modifiedExists === undefined) {
+                    conflicts.push({
+                        relativePath,
+                        reason: 'legacy_snapshot_ambiguous',
+                        detail: 'This patch predates explicit file-existence metadata and cannot be selectively applied.',
+                    });
+                }
+                else {
+                    try {
+                        expectedBefore = composePatchSnapshot(snapshot, pathHunks, decisions);
+                        const prospectiveDecisions = [
+                            ...decisions,
+                            ...targetHunks.map((hunk, index) => ({
+                                id: `preview-${index}`,
+                                relativePath,
+                                hunkId: hunk.id,
+                                action: request.action,
+                                state: 'applied',
+                                createdAt: Date.now() + index,
+                                updatedAt: Date.now() + index,
+                            })),
+                        ];
+                        resulting = composePatchSnapshot(snapshot, pathHunks, prospectiveDecisions);
+                        inspected = inspectRestoreTarget(rootDirectory, relativePath);
+                        if (inspected.exists !== expectedBefore.exists
+                            || (inspected.exists && inspected.sha256 !== expectedBefore.sha256)) {
+                            conflicts.push({
+                                relativePath,
+                                reason: 'current_state_changed',
+                                expectedExists: expectedBefore.exists,
+                                actualExists: inspected.exists,
+                                ...(expectedBefore.exists ? { expectedSha256: expectedBefore.sha256 } : {}),
+                                ...(inspected.sha256 ? { actualSha256: inspected.sha256 } : {}),
+                                detail: 'The workspace file no longer matches the exact reviewed patch state.',
+                            });
+                        }
+                    }
+                    catch (error) {
+                        const message = error instanceof Error ? error.message : String(error);
+                        conflicts.push({
+                            relativePath,
+                            reason: /regular text file|size limit|snapshot/i.test(message) ? 'unsupported_file_type' : 'unsafe_path',
+                            detail: message,
+                        });
+                    }
+                }
+            }
+            const selectedHunkIds = targetHunks.map((hunk) => hunk.id);
+            const changesFile = request.action === 'reject'
+                && !!expectedBefore
+                && !!resulting
+                && (expectedBefore.exists !== resulting.exists || expectedBefore.sha256 !== resulting.sha256);
+            const wouldChangeFiles = changesFile ? [relativePath] : [];
+            const previewToken = hashText(JSON.stringify({
+                id,
+                rootDirectory: resolve(rootDirectory),
+                relativePath,
+                action: request.action,
+                selectedHunkIds,
+                expectedBefore,
+                resulting,
+                actual: inspected ? { exists: inspected.exists, sha256: inspected.sha256 || null } : null,
+                conflicts,
+            }));
+            if (!request.confirmed) {
+                return {
+                    success: true,
+                    rootDirectory,
+                    item,
+                    selectedHunkIds,
+                    wouldChangeFiles,
+                    previewToken,
+                    conflicts,
+                    applied: false,
+                };
+            }
+            if (!request.previewToken || request.previewToken !== previewToken) {
+                return {
+                    success: false,
+                    rootDirectory,
+                    item,
+                    selectedHunkIds,
+                    wouldChangeFiles,
+                    previewToken,
+                    conflicts,
+                    applied: false,
+                    error: 'Patch review preview is missing or stale. Preview the selection again before confirming.',
+                };
+            }
+            if (conflicts.length > 0 || !snapshot || !expectedBefore || !resulting || !inspected) {
+                return {
+                    success: false,
+                    rootDirectory,
+                    item,
+                    selectedHunkIds,
+                    wouldChangeFiles,
+                    previewToken,
+                    conflicts,
+                    applied: false,
+                    error: 'Patch selection conflicts with the immutable snapshot or current workspace state.',
+                };
+            }
+            const now = Date.now();
+            const pending = targetHunks.map((hunk, index) => ({
+                id: `patch-decision-${now}-${index}-${randomUUID()}`,
+                relativePath,
+                hunkId: hunk.id,
+                action: request.action,
+                ...(normalizeReviewComment(request.comment) ? { comment: normalizeReviewComment(request.comment) } : {}),
+                state: changesFile ? 'pending' : 'applied',
+                expectedBeforeExists: expectedBefore.exists,
+                expectedBeforeSha256: expectedBefore.sha256,
+                resultingExists: resulting.exists,
+                resultingSha256: resulting.sha256,
+                createdAt: now + index,
+                updatedAt: now + index,
+            }));
+            decisions.push(...pending);
+            item.decisions = decisions.slice(-1_000);
+            item.updatedAt = now;
+            if (changesFile)
+                this.writePatchReviewStore(rootDirectory, store);
+            let transactionId;
+            if (changesFile) {
+                try {
+                    const transaction = applyCheckpointRestoreTransaction(rootDirectory, `patch-review-${id}`, [{
+                            relativePath,
+                            targetPath: inspected.targetPath,
+                            originalContent: resulting.content,
+                            originalExists: resulting.exists,
+                            originalSha256: resulting.sha256,
+                            expectedCurrentExists: expectedBefore.exists,
+                            expectedCurrentSha256: expectedBefore.sha256,
+                            actualExists: inspected.exists,
+                            actualSha256: inspected.sha256,
+                        }]);
+                    transactionId = transaction.transactionId;
+                    for (const decision of pending) {
+                        decision.state = 'applied';
+                        decision.transactionId = transactionId;
+                        decision.updatedAt = Date.now();
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    for (const decision of pending) {
+                        decision.state = 'failed';
+                        decision.error = message;
+                        decision.updatedAt = Date.now();
+                    }
+                    this.writePatchReviewStore(rootDirectory, store);
+                    return {
+                        success: false,
+                        rootDirectory,
+                        item,
+                        selectedHunkIds,
+                        wouldChangeFiles,
+                        previewToken,
+                        conflicts,
+                        applied: false,
+                        error: message,
+                    };
+                }
+            }
+            item.status = derivePatchReviewStatus(item);
+            item.updatedAt = Date.now();
+            this.writePatchReviewStore(rootDirectory, store);
+            return {
+                success: true,
+                rootDirectory,
+                item,
+                selectedHunkIds,
+                wouldChangeFiles,
+                previewToken,
+                conflicts: [],
+                applied: true,
+                ...(transactionId ? { transactionId } : {}),
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                ...empty,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    listCheckpoints(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            return { success: true, rootDirectory, checkpoints: this.buildCheckpointSummaries(rootDirectory) };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                checkpoints: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    compareCheckpoints(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const fromId = normalizeRequiredId(request.fromCheckpointId, 'fromCheckpointId');
+            const toId = normalizeRequiredId(request.toCheckpointId, 'toCheckpointId');
+            const checkpoints = this.buildCheckpointSummaries(rootDirectory);
+            const from = checkpoints.find((checkpoint) => checkpoint.checkpointId === fromId);
+            const to = checkpoints.find((checkpoint) => checkpoint.checkpointId === toId);
+            if (!from || !to) {
+                return {
+                    success: false,
+                    rootDirectory,
+                    filesChanged: [],
+                    diff: '',
+                    patches: [],
+                    error: 'Both checkpoints must exist in patch history before they can be compared.',
+                };
+            }
+            const patches = selectPatchesBetweenCheckpoints(this.readPatchReviewStore(rootDirectory).items, fromId, toId);
+            const filesChanged = uniqueStrings(patches.flatMap((patch) => patch.filesChanged.length ? patch.filesChanged : patch.files));
+            return {
+                success: true,
+                rootDirectory,
+                from,
+                to,
+                filesChanged,
+                diff: joinPatchDiffs(patches),
+                patches,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                filesChanged: [],
+                diff: '',
+                patches: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    restoreCheckpoint(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            recoverInterruptedRestoreTransactions(rootDirectory);
+            const checkpointId = normalizeRequiredId(request.checkpointId, 'checkpointId');
+            const checkpoint = this.buildCheckpointSummaries(rootDirectory).find((entry) => entry.checkpointId === checkpointId);
+            if (!checkpoint) {
+                return {
+                    success: false,
+                    rootDirectory,
+                    previewDiff: '',
+                    wouldRestoreFiles: [],
+                    error: 'Checkpoint was not found in engineering patch history.',
+                };
+            }
+            const patches = this.readPatchReviewStore(rootDirectory).items.filter((patch) => patch.checkpointId === checkpointId);
+            const previewDiff = joinPatchDiffs(patches);
+            const plan = buildCheckpointRestorePlan(rootDirectory, checkpointId, patches);
+            const wouldRestoreFiles = plan.entries.map((entry) => entry.relativePath);
+            if (!request.confirmed) {
+                return {
+                    success: true,
+                    rootDirectory,
+                    checkpoint,
+                    previewDiff,
+                    wouldRestoreFiles,
+                    previewToken: plan.previewToken,
+                    conflicts: plan.conflicts,
+                    restored: false,
+                    restoredFiles: [],
+                };
+            }
+            if (!request.previewToken || request.previewToken !== plan.previewToken) {
+                return {
+                    success: false,
+                    rootDirectory,
+                    checkpoint,
+                    previewDiff,
+                    wouldRestoreFiles,
+                    previewToken: plan.previewToken,
+                    conflicts: plan.conflicts,
+                    restored: false,
+                    restoredFiles: [],
+                    error: 'Checkpoint restore preview is missing or stale. Preview the checkpoint again before confirming.',
+                };
+            }
+            const nonOverridableConflicts = plan.conflicts.filter((conflict) => (conflict.reason === 'unsafe_path'
+                || conflict.reason === 'unsupported_file_type'
+                || conflict.reason === 'legacy_snapshot_ambiguous'
+                || conflict.reason === 'missing_snapshot_data'
+                || conflict.reason === 'snapshot_chain_broken'));
+            if (nonOverridableConflicts.length > 0
+                || (plan.conflicts.length > 0 && request.conflictStrategy !== 'overwrite')) {
+                return {
+                    success: false,
+                    rootDirectory,
+                    checkpoint,
+                    previewDiff,
+                    wouldRestoreFiles,
+                    previewToken: plan.previewToken,
+                    conflicts: plan.conflicts,
+                    restored: false,
+                    restoredFiles: [],
+                    error: nonOverridableConflicts.length > 0
+                        ? 'Checkpoint contains unsafe, unsupported, or ambiguous legacy snapshots and cannot be restored automatically.'
+                        : 'Workspace files changed after this checkpoint. Choose an explicit overwrite strategy or keep the current files.',
+                };
+            }
+            const transaction = applyCheckpointRestoreTransaction(rootDirectory, checkpointId, plan.entries);
+            const conversationId = normalizeOptionalId(request.conversationId || checkpoint.conversationId);
+            const requestId = normalizeOptionalId(request.requestId || checkpoint.requestId) || `checkpoint-restore-${Date.now()}`;
+            const runtimeEvent = {
+                id: `hub-checkpoint-restore-${checkpointId}-${Date.now()}`,
+                type: 'hub.checkpoint.restore',
+                checkpointId,
+                rootDirectory,
+                filesChanged: transaction.restoredFiles,
+                transactionId: transaction.transactionId,
+                restoredHashes: transaction.restoredHashes,
+                summary: `Restored ${transaction.restoredFiles.length} file${transaction.restoredFiles.length === 1 ? '' : 's'} from ${checkpointId}`,
+            };
+            if (conversationId) {
+                this.runtimeEventStore.append({
+                    conversationId,
+                    requestId,
+                    event: runtimeEvent,
+                    source: 'engineering-workbench',
+                });
+            }
+            return {
+                success: true,
+                rootDirectory,
+                checkpoint,
+                previewDiff,
+                wouldRestoreFiles,
+                previewToken: plan.previewToken,
+                conflicts: plan.conflicts,
+                restored: true,
+                restoredFiles: transaction.restoredFiles,
+                transactionId: transaction.transactionId,
+                runtimeEvent,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                previewDiff: '',
+                wouldRestoreFiles: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    listSessions(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            return { success: true, rootDirectory, sessions: this.buildEngineeringSessions(rootDirectory) };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                sessions: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    runtimeTimeline(request) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            const conversationId = normalizeRequiredId(request.conversationId, 'conversationId');
+            const projection = this.runtimeEventStore.project(conversationId);
+            if (!projection.success) {
+                return { success: false, rootDirectory, conversationId, error: projection.error || 'Failed to project runtime timeline.' };
+            }
+            return { success: true, rootDirectory, conversationId, timeline: projection.projection?.timeline };
+        }
+        catch (err) {
+            return {
+                success: false,
+                rootDirectory: request.rootDirectory || '',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    resolveRoot(request) {
+        return resolveRootDirectory(request.rootDirectory, request.allowedDirectories);
+    }
+    buildCheckpointSummaries(rootDirectory) {
+        const byCheckpoint = new Map();
+        for (const patch of this.readPatchReviewStore(rootDirectory).items) {
+            if (!patch.checkpointId)
+                continue;
+            const list = byCheckpoint.get(patch.checkpointId) || [];
+            list.push(patch);
+            byCheckpoint.set(patch.checkpointId, list);
+        }
+        return [...byCheckpoint.entries()]
+            .map(([checkpointId, patches]) => {
+            const ordered = patches.slice().sort((a, b) => a.timestamp - b.timestamp || a.id.localeCompare(b.id));
+            const first = ordered[0];
+            const last = ordered[ordered.length - 1];
+            return {
+                id: `checkpoint-summary-${checkpointId}`,
+                checkpointId,
+                rootDirectory,
+                createdAt: first?.timestamp || first?.createdAt || Date.now(),
+                conversationId: first?.conversationId,
+                requestId: first?.requestId,
+                summary: uniqueStrings(ordered.map((patch) => patch.summary || patch.title)).join(' / ') || `Checkpoint ${checkpointId}`,
+                filesChanged: uniqueStrings(ordered.flatMap((patch) => patch.filesChanged.length ? patch.filesChanged : patch.files)),
+                patchIds: ordered.map((patch) => patch.id),
+                patchCount: ordered.length,
+                ...(last?.requestId ? { requestId: last.requestId } : {}),
+            };
+        })
+            .sort((a, b) => b.createdAt - a.createdAt || b.checkpointId.localeCompare(a.checkpointId));
+    }
+    buildEngineeringSessions(rootDirectory) {
+        const patches = this.readPatchReviewStore(rootDirectory).items
+            .filter((patch) => patch.conversationId)
+            .slice()
+            .sort((a, b) => a.timestamp - b.timestamp || a.id.localeCompare(b.id));
+        const runs = this.readRunStore(rootDirectory).runs;
+        const checkpoints = this.buildCheckpointSummaries(rootDirectory);
+        const byConversation = new Map();
+        for (const patch of patches) {
+            const key = patch.conversationId || 'manual';
+            const list = byConversation.get(key) || [];
+            list.push(patch);
+            byConversation.set(key, list);
+        }
+        return [...byConversation.entries()].map(([conversationId, sessionPatches]) => {
+            const startedAt = Math.min(...sessionPatches.map((patch) => patch.timestamp || patch.createdAt));
+            const endedAt = Math.max(...sessionPatches.map((patch) => patch.updatedAt || patch.timestamp || patch.createdAt));
+            const sessionCheckpoints = checkpoints.filter((checkpoint) => checkpoint.conversationId === conversationId);
+            const testsRun = runs.filter((run) => run.startedAt >= startedAt && run.startedAt <= Math.max(endedAt, startedAt));
+            const changedFiles = uniqueStrings(sessionPatches.flatMap((patch) => patch.filesChanged.length ? patch.filesChanged : patch.files));
+            const passCount = testsRun.filter((run) => run.success).length;
+            const failCount = testsRun.length - passCount;
+            return {
+                id: `engineering-session-${conversationId}`,
+                rootDirectory,
+                conversationId,
+                startedAt,
+                endedAt,
+                patches: sessionPatches.slice().reverse(),
+                checkpoints: sessionCheckpoints,
+                testsRun,
+                finalSummary: `${sessionPatches.length} patch${sessionPatches.length === 1 ? '' : 'es'} / ${changedFiles.length} file${changedFiles.length === 1 ? '' : 's'} changed / ${testsRun.length} test run${testsRun.length === 1 ? '' : 's'} (${passCount} pass, ${failCount} fail)`,
+            };
+        }).sort((a, b) => b.startedAt - a.startedAt);
+    }
+    async isGitRepo(rootDirectory) {
+        const result = await runProcess('git', ['rev-parse', '--is-inside-work-tree'], rootDirectory, 5000, 8000);
+        return result.success && result.stdout.trim() === 'true';
+    }
+    validateRelativePaths(rootDirectory, paths) {
+        const safe = paths
+            .map((item) => String(item || '').trim())
+            .filter(Boolean)
+            .map((item) => item.replace(/\\/g, '/'))
+            .filter((item) => !item.startsWith('/') && !/^[A-Za-z]:/.test(item))
+            .filter((item) => {
+            const full = join(rootDirectory, item);
+            return isPathInside(full, rootDirectory);
+        });
+        if (paths.length > 0 && safe.length === 0)
+            throw new Error('No safe relative file paths were provided.');
+        return safe;
+    }
+    async runGitMutation(request, args) {
+        try {
+            const rootDirectory = this.resolveRoot(request);
+            if (!await this.isGitRepo(rootDirectory)) {
+                return { success: false, isGitRepo: false, rootDirectory, clean: true, files: [], error: 'Workspace is not a git repository.' };
+            }
+            const result = await runProcess('git', args, rootDirectory, 120000, MAX_GIT_OUTPUT);
+            if (!result.success) {
+                return {
+                    success: false,
+                    isGitRepo: true,
+                    rootDirectory,
+                    clean: true,
+                    files: [],
+                    error: result.error || result.stderr || 'Git operation failed.',
+                };
+            }
+            return this.gitStatus(request);
+        }
+        catch (err) {
+            return {
+                success: false,
+                isGitRepo: false,
+                rootDirectory: request.rootDirectory || '',
+                clean: true,
+                files: [],
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    appendRun(rootDirectory, run) {
+        const store = this.readRunStore(rootDirectory);
+        store.runs = [run, ...store.runs.filter((entry) => entry.id !== run.id)].slice(0, MAX_STORED_RUNS);
+        safeWriteJson(this.runStorePath(rootDirectory), store);
+    }
+    readRunStore(rootDirectory) {
+        return safeReadJson(this.runStorePath(rootDirectory), { version: 1, runs: [] });
+    }
+    runStorePath(rootDirectory) {
+        return join(workspaceIndexDirectory(rootDirectory), 'engineering-runs.json');
+    }
+    readBackgroundRunStore(rootDirectory) {
+        const store = safeReadJson(this.backgroundRunStorePath(rootDirectory), { version: 1, runs: [] });
+        let changed = false;
+        const runs = store.runs
+            .map((run) => {
+            const active = this.activeBackgroundRuns.get(run.id);
+            if (active)
+                return active.run;
+            if (run.status !== 'running')
+                return run;
+            changed = true;
+            const now = Date.now();
+            return {
+                ...run,
+                status: 'stopped',
+                updatedAt: run.updatedAt || now,
+                endedAt: run.endedAt || now,
+                durationMs: run.durationMs || Math.max(0, now - run.startedAt),
+                error: run.error || 'Background process is no longer attached to this Hub session.',
+            };
+        })
+            .slice(0, MAX_STORED_BACKGROUND_RUNS);
+        const normalized = { version: 1, runs };
+        if (changed || runs.length !== store.runs.length)
+            safeWriteJson(this.backgroundRunStorePath(rootDirectory), normalized);
+        return normalized;
+    }
+    writeBackgroundRun(rootDirectory, run) {
+        const store = safeReadJson(this.backgroundRunStorePath(rootDirectory), { version: 1, runs: [] });
+        const runs = [run, ...store.runs.filter((entry) => entry.id !== run.id)].slice(0, MAX_STORED_BACKGROUND_RUNS);
+        safeWriteJson(this.backgroundRunStorePath(rootDirectory), { version: 1, runs });
+    }
+    backgroundRunStorePath(rootDirectory) {
+        return join(workspaceIndexDirectory(rootDirectory), 'engineering-background-runs.json');
+    }
+    readPatchReviewStore(rootDirectory) {
+        recoverInterruptedRestoreTransactions(rootDirectory);
+        const store = safeReadJson(this.patchReviewStorePath(rootDirectory), { version: 1, items: [] });
+        let changed = false;
+        store.items = Array.isArray(store.items) ? store.items.slice(0, MAX_STORED_PATCH_REVIEWS) : [];
+        for (const item of store.items) {
+            const snapshots = normalizePatchFileSnapshots(rootDirectory, item.fileSnapshots || []);
+            const hunks = buildPatchReviewHunks(snapshots);
+            const decisions = normalizePatchReviewDecisions(item.decisions || []);
+            item.fileSnapshots = snapshots;
+            item.hunks = hunks;
+            item.decisions = decisions;
+            for (const decision of decisions) {
+                if (decision.state !== 'pending')
+                    continue;
+                try {
+                    const inspected = inspectRestoreTarget(rootDirectory, decision.relativePath);
+                    if (matchesReviewDecisionState(inspected, decision.resultingExists, decision.resultingSha256)) {
+                        decision.state = 'applied';
+                        decision.error = 'Recovered a committed selective-review filesystem transaction.';
+                    }
+                    else if (matchesReviewDecisionState(inspected, decision.expectedBeforeExists, decision.expectedBeforeSha256)) {
+                        decision.state = 'failed';
+                        decision.error = 'Recovered a selective-review decision before its filesystem transaction committed.';
+                    }
+                    else {
+                        decision.state = 'conflict';
+                        decision.error = 'Selective-review recovery found a file state matching neither the pre-decision nor resulting snapshot.';
+                    }
+                }
+                catch (error) {
+                    decision.state = 'conflict';
+                    decision.error = error instanceof Error ? error.message : String(error);
+                }
+                decision.updatedAt = Date.now();
+                changed = true;
+            }
+            const status = derivePatchReviewStatus(item);
+            if (status !== item.status) {
+                item.status = status;
+                changed = true;
+            }
+        }
+        if (changed)
+            this.writePatchReviewStore(rootDirectory, store);
+        return store;
+    }
+    writePatchReviewStore(rootDirectory, store) {
+        safeWriteJson(this.patchReviewStorePath(rootDirectory), {
+            version: 1,
+            items: store.items.slice(0, MAX_STORED_PATCH_REVIEWS),
+        });
+    }
+    patchReviewStorePath(rootDirectory) {
+        return join(workspaceIndexDirectory(rootDirectory), 'patch-review-queue.json');
+    }
+}
+function buildCheckpointRestorePlan(rootDirectory, checkpointId, patches) {
+    const entriesByPath = new Map();
+    const conflicts = [];
+    const orderedPatches = patches.slice().sort((left, right) => (left.timestamp - right.timestamp || left.id.localeCompare(right.id)));
+    for (const patch of orderedPatches) {
+        for (const snapshot of patch.fileSnapshots || []) {
+            const relativePath = snapshot.relativePath.replace(/\\/g, '/');
+            const key = process.platform === 'win32' ? relativePath.toLowerCase() : relativePath;
+            const prior = entriesByPath.get(key);
+            const originalSha256 = snapshot.originalSha256 || hashText(snapshot.originalContent);
+            const modifiedSha256 = snapshot.modifiedSha256 || hashText(snapshot.modifiedContent);
+            if (!prior) {
+                entriesByPath.set(key, {
+                    relativePath,
+                    targetPath: resolve(rootDirectory, relativePath),
+                    originalContent: snapshot.originalContent,
+                    originalExists: snapshot.originalExists,
+                    originalSha256,
+                    expectedCurrentExists: snapshot.modifiedExists,
+                    expectedCurrentSha256: modifiedSha256,
+                    actualExists: false,
+                });
+            }
+            else {
+                if (prior.expectedCurrentExists !== undefined
+                    && snapshot.originalExists !== undefined
+                    && (prior.expectedCurrentExists !== snapshot.originalExists
+                        || (snapshot.originalExists && prior.expectedCurrentSha256 !== originalSha256))) {
+                    conflicts.push({
+                        relativePath,
+                        reason: 'snapshot_chain_broken',
+                        expectedExists: prior.expectedCurrentExists,
+                        actualExists: snapshot.originalExists,
+                        ...(prior.expectedCurrentExists ? { expectedSha256: prior.expectedCurrentSha256 } : {}),
+                        ...(snapshot.originalExists ? { actualSha256: originalSha256 } : {}),
+                        detail: 'Consecutive snapshots for this checkpoint do not form one continuous file history.',
+                    });
+                }
+                prior.expectedCurrentExists = snapshot.modifiedExists;
+                prior.expectedCurrentSha256 = modifiedSha256;
+            }
+        }
+    }
+    const entries = [...entriesByPath.values()].sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+    if (entries.length === 0) {
+        conflicts.push({
+            relativePath: '(checkpoint)',
+            reason: 'missing_snapshot_data',
+            detail: 'This checkpoint has no restorable file snapshots.',
+        });
+    }
+    for (const entry of entries) {
+        if (entry.originalExists === undefined || entry.expectedCurrentExists === undefined) {
+            conflicts.push({
+                relativePath: entry.relativePath,
+                reason: 'legacy_snapshot_ambiguous',
+                detail: 'This snapshot predates explicit file-existence metadata, so automatic deletion or recreation would be unsafe.',
+            });
+            continue;
+        }
+        try {
+            const inspected = inspectRestoreTarget(rootDirectory, entry.relativePath);
+            entry.targetPath = inspected.targetPath;
+            entry.actualExists = inspected.exists;
+            entry.actualSha256 = inspected.sha256;
+            if (entry.actualExists !== entry.expectedCurrentExists
+                || (entry.actualExists && entry.actualSha256 !== entry.expectedCurrentSha256)) {
+                conflicts.push({
+                    relativePath: entry.relativePath,
+                    reason: 'current_state_changed',
+                    expectedExists: entry.expectedCurrentExists,
+                    actualExists: entry.actualExists,
+                    ...(entry.expectedCurrentExists ? { expectedSha256: entry.expectedCurrentSha256 } : {}),
+                    ...(entry.actualSha256 ? { actualSha256: entry.actualSha256 } : {}),
+                    detail: 'The current file no longer matches the exact post-edit snapshot.',
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            conflicts.push({
+                relativePath: entry.relativePath,
+                reason: /regular text file|size limit/i.test(message) ? 'unsupported_file_type' : 'unsafe_path',
+                detail: message,
+            });
+        }
+    }
+    const previewToken = hashText(JSON.stringify({
+        checkpointId,
+        rootDirectory: resolve(rootDirectory),
+        files: entries.map((entry) => ({
+            relativePath: entry.relativePath,
+            originalExists: entry.originalExists,
+            originalSha256: entry.originalSha256,
+            expectedCurrentExists: entry.expectedCurrentExists,
+            expectedCurrentSha256: entry.expectedCurrentSha256,
+            actualExists: entry.actualExists,
+            actualSha256: entry.actualSha256 || null,
+        })),
+        conflicts,
+    }));
+    return { entries, conflicts, previewToken };
+}
+function inspectRestoreTarget(rootDirectory, relativePath) {
+    const targetPath = assertSafeRestorePath(rootDirectory, relativePath);
+    if (!existsSync(targetPath))
+        return { targetPath, exists: false };
+    const stats = lstatSync(targetPath);
+    if (stats.isSymbolicLink() || !stats.isFile()) {
+        throw new Error('Checkpoint targets must be regular text files, never symlinks or directories.');
+    }
+    if (stats.size > MAX_TRANSACTIONAL_SNAPSHOT_BYTES) {
+        throw new Error(`Current file exceeds the ${MAX_TRANSACTIONAL_SNAPSHOT_BYTES}-byte transactional snapshot size limit.`);
+    }
+    const content = readFileSync(targetPath, 'utf8');
+    if (content.length > MAX_TRANSACTIONAL_SNAPSHOT_CHARS) {
+        throw new Error(`Current file exceeds the ${MAX_TRANSACTIONAL_SNAPSHOT_CHARS}-character transactional snapshot size limit.`);
+    }
+    return { targetPath, exists: true, sha256: hashText(content) };
+}
+function assertSafeRestorePath(rootDirectory, relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+    const parts = normalized.split('/').filter(Boolean);
+    if (!normalized || isAbsolute(normalized) || parts.some((part) => part === '.' || part === '..')) {
+        throw new Error('Checkpoint contains an unsafe relative path.');
+    }
+    const targetPath = resolve(rootDirectory, normalized);
+    if (!isPathInside(targetPath, rootDirectory))
+        throw new Error('Checkpoint target escapes the workspace root.');
+    const canonicalRoot = realpathSync(rootDirectory);
+    let cursor = resolve(rootDirectory);
+    for (const part of parts.slice(0, -1)) {
+        cursor = join(cursor, part);
+        if (!existsSync(cursor))
+            continue;
+        const stats = lstatSync(cursor);
+        if (stats.isSymbolicLink() || !stats.isDirectory()) {
+            throw new Error('Checkpoint target crosses a symlink or non-directory path component.');
+        }
+        if (!isPathInside(realpathSync(cursor), canonicalRoot)) {
+            throw new Error('Checkpoint target resolves outside the canonical workspace root.');
+        }
+    }
+    return targetPath;
+}
+function applyCheckpointRestoreTransaction(rootDirectory, checkpointId, entries) {
+    const transactionId = `checkpoint-restore-${Date.now()}-${randomUUID()}`;
+    const transactionDirectory = checkpointTransactionDirectory(rootDirectory);
+    mkdirSync(transactionDirectory, { recursive: true });
+    const manifestPath = join(transactionDirectory, `${transactionId}.json`);
+    const transactionFiles = [];
+    for (const entry of entries) {
+        if (entry.originalExists === undefined)
+            throw new Error(`Checkpoint snapshot is ambiguous: ${entry.relativePath}`);
+        const targetPath = assertSafeRestorePath(rootDirectory, entry.relativePath);
+        const inspected = inspectRestoreTarget(rootDirectory, entry.relativePath);
+        if (inspected.exists !== entry.actualExists
+            || (inspected.exists && inspected.sha256 !== entry.actualSha256)) {
+            throw new Error(`Checkpoint restore preview became stale for ${entry.relativePath}.`);
+        }
+        const parentDirectory = dirname(targetPath);
+        mkdirSync(parentDirectory, { recursive: true });
+        const suffix = `.xeno-${transactionId}`;
+        const stagePath = entry.originalExists ? `${targetPath}${suffix}.stage` : null;
+        const backupPath = `${targetPath}${suffix}.backup`;
+        if (stagePath)
+            writeFileSync(stagePath, entry.originalContent, { encoding: 'utf8', flag: 'wx' });
+        transactionFiles.push({
+            relativePath: entry.relativePath,
+            targetPath,
+            stagePath,
+            backupPath,
+            hadCurrent: inspected.exists,
+            expectedCurrentExists: inspected.exists,
+            expectedCurrentSha256: inspected.sha256,
+            restoreExists: entry.originalExists,
+            restoreSha256: entry.originalSha256,
+        });
+    }
+    const manifest = {
+        version: 1,
+        transactionId,
+        checkpointId,
+        rootDirectory,
+        phase: 'prepared',
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+        files: transactionFiles,
+    };
+    safeWriteJson(manifestPath, manifest);
+    try {
+        manifest.phase = 'applying';
+        manifest.updatedAt = Date.now();
+        safeWriteJson(manifestPath, manifest);
+        for (const file of transactionFiles) {
+            validateRestoreTransactionFile(rootDirectory, transactionId, file);
+            const inspected = inspectRestoreTarget(rootDirectory, file.relativePath);
+            if (inspected.exists !== file.expectedCurrentExists
+                || (inspected.exists && inspected.sha256 !== file.expectedCurrentSha256)) {
+                throw new Error(`Checkpoint restore target changed during the transaction: ${file.relativePath}`);
+            }
+            if (existsSync(file.backupPath))
+                throw new Error(`Checkpoint backup path already exists: ${file.relativePath}`);
+            if (existsSync(file.targetPath))
+                renameSync(file.targetPath, file.backupPath);
+            if (file.restoreExists && file.stagePath)
+                renameSync(file.stagePath, file.targetPath);
+        }
+        const restoredHashes = {};
+        for (const file of transactionFiles) {
+            if (!file.restoreExists) {
+                if (existsSync(file.targetPath))
+                    throw new Error(`Checkpoint verification failed: ${file.relativePath} still exists.`);
+                restoredHashes[file.relativePath] = null;
+                continue;
+            }
+            if (!existsSync(file.targetPath))
+                throw new Error(`Checkpoint verification failed: ${file.relativePath} is missing.`);
+            const restoredHash = hashText(readFileSync(file.targetPath, 'utf8'));
+            if (restoredHash !== file.restoreSha256) {
+                throw new Error(`Checkpoint verification failed for ${file.relativePath}.`);
+            }
+            restoredHashes[file.relativePath] = restoredHash;
+        }
+        manifest.phase = 'committed';
+        manifest.updatedAt = Date.now();
+        safeWriteJson(manifestPath, manifest);
+        cleanupTransactionArtifacts(transactionFiles);
+        return {
+            transactionId,
+            restoredFiles: transactionFiles.map((file) => file.relativePath),
+            restoredHashes,
+        };
+    }
+    catch (error) {
+        const rolledBack = rollbackTransactionFiles(rootDirectory, transactionId, transactionFiles);
+        manifest.phase = rolledBack ? 'rolled_back' : 'rollback_failed';
+        manifest.updatedAt = Date.now();
+        manifest.error = `${error instanceof Error ? error.message : String(error)}${rolledBack ? '' : ' Automatic rollback was incomplete; recovery artifacts were retained.'}`;
+        safeWriteJson(manifestPath, manifest);
+        throw error;
+    }
+}
+function recoverInterruptedRestoreTransactions(rootDirectory) {
+    const directory = checkpointTransactionDirectory(rootDirectory);
+    if (!existsSync(directory))
+        return;
+    for (const name of readdirSync(directory)) {
+        if (!name.endsWith('.json'))
+            continue;
+        const manifestPath = join(directory, name);
+        const manifest = safeReadJson(manifestPath, null);
+        if (!manifest || manifest.version !== 1 || !sameResolvedPath(manifest.rootDirectory, rootDirectory))
+            continue;
+        if (name !== `${manifest.transactionId}.json` || !/^checkpoint-restore-\d+-[0-9a-f-]{36}$/i.test(manifest.transactionId))
+            continue;
+        try {
+            validateRestoreTransactionFiles(rootDirectory, manifest.transactionId, manifest.files);
+            if (manifest.phase === 'committed') {
+                cleanupTransactionArtifacts(manifest.files);
+                continue;
+            }
+            if (manifest.phase !== 'prepared' && manifest.phase !== 'applying' && manifest.phase !== 'rollback_failed')
+                continue;
+            const recovered = manifest.phase === 'prepared'
+                ? (cleanupTransactionArtifacts(manifest.files), true)
+                : rollbackTransactionFiles(rootDirectory, manifest.transactionId, manifest.files);
+            manifest.phase = recovered ? 'recovered_rollback' : 'rollback_failed';
+            manifest.updatedAt = Date.now();
+            manifest.error = recovered
+                ? 'Recovered and rolled back an interrupted checkpoint restore transaction.'
+                : 'Checkpoint restore recovery was incomplete; retained backup artifacts require another recovery pass.';
+            safeWriteJson(manifestPath, manifest);
+        }
+        catch (error) {
+            manifest.phase = 'rollback_failed';
+            manifest.updatedAt = Date.now();
+            manifest.error = `Checkpoint restore recovery rejected unsafe transaction metadata: ${error instanceof Error ? error.message : String(error)}`;
+            safeWriteJson(manifestPath, manifest);
+        }
+    }
+}
+function rollbackTransactionFiles(rootDirectory, transactionId, files) {
+    validateRestoreTransactionFiles(rootDirectory, transactionId, files);
+    let complete = true;
+    for (const file of files.slice().reverse()) {
+        try {
+            if (existsSync(file.backupPath)) {
+                if (existsSync(file.targetPath))
+                    unlinkSync(file.targetPath);
+                renameSync(file.backupPath, file.targetPath);
+            }
+            else if (!file.hadCurrent && existsSync(file.targetPath)) {
+                unlinkSync(file.targetPath);
+            }
+        }
+        catch {
+            complete = false;
+            // Keep the transaction manifest and remaining artifacts for the next recovery pass.
+        }
+    }
+    cleanupTransactionStageArtifacts(files);
+    return complete && files.every((file) => !existsSync(file.backupPath));
+}
+function validateRestoreTransactionFiles(rootDirectory, transactionId, files) {
+    for (const file of files)
+        validateRestoreTransactionFile(rootDirectory, transactionId, file);
+}
+function validateRestoreTransactionFile(rootDirectory, transactionId, file) {
+    const targetPath = assertSafeRestorePath(rootDirectory, file.relativePath);
+    const suffix = `.xeno-${transactionId}`;
+    const expectedStagePath = file.restoreExists ? `${targetPath}${suffix}.stage` : null;
+    const expectedBackupPath = `${targetPath}${suffix}.backup`;
+    if (!sameResolvedPath(file.targetPath, targetPath)
+        || (file.stagePath === null ? expectedStagePath !== null : expectedStagePath === null || !sameResolvedPath(file.stagePath, expectedStagePath))
+        || !sameResolvedPath(file.backupPath, expectedBackupPath)) {
+        throw new Error(`Transaction artifact paths do not match the workspace target for ${file.relativePath}.`);
+    }
+}
+function sameResolvedPath(left, right) {
+    const normalizedLeft = resolve(left);
+    const normalizedRight = resolve(right);
+    return process.platform === 'win32'
+        ? normalizedLeft.toLowerCase() === normalizedRight.toLowerCase()
+        : normalizedLeft === normalizedRight;
+}
+function cleanupTransactionStageArtifacts(files) {
+    for (const file of files) {
+        if (!file.stagePath || !existsSync(file.stagePath))
+            continue;
+        try {
+            unlinkSync(file.stagePath);
+        }
+        catch { /* retained for a later recovery/repair pass */ }
+    }
+}
+function cleanupTransactionArtifacts(files) {
+    for (const file of files) {
+        for (const artifact of [file.stagePath, file.backupPath]) {
+            if (!artifact || !existsSync(artifact))
+                continue;
+            try {
+                unlinkSync(artifact);
+            }
+            catch { /* retained for a later recovery/repair pass */ }
+        }
+    }
+}
+function checkpointTransactionDirectory(rootDirectory) {
+    return join(workspaceIndexDirectory(rootDirectory), 'snapshots', 'transactions');
+}
+function normalizeRequiredId(value, label) {
+    const normalized = normalizeOptionalId(value);
+    if (!normalized)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+function normalizeOptionalId(value) {
+    return typeof value === 'string' && value.trim() ? value.trim().slice(0, 240) : undefined;
+}
+function normalizeStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return uniqueStrings(value.map((entry) => typeof entry === 'string' ? entry.trim() : '').filter(Boolean));
+}
+function normalizePatchFileSnapshots(rootDirectory, value) {
+    if (!Array.isArray(value))
+        return [];
+    const snapshots = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const record = entry;
+        const rawPath = typeof record.path === 'string' ? record.path.trim() : '';
+        const rawRelativePath = typeof record.relativePath === 'string' ? record.relativePath.trim() : '';
+        const relativePath = (rawRelativePath || (isAbsolute(rawPath) && isPathInside(rawPath, rootDirectory)
+            ? relative(rootDirectory, rawPath)
+            : rawPath)).replace(/\\/g, '/');
+        if (!relativePath || relativePath.startsWith('/') || /^[A-Za-z]:/.test(relativePath))
+            continue;
+        const absolutePath = join(rootDirectory, relativePath);
+        if (!isPathInside(absolutePath, rootDirectory))
+            continue;
+        const originalContent = typeof record.originalContent === 'string' ? record.originalContent : '';
+        const modifiedContent = typeof record.modifiedContent === 'string' ? record.modifiedContent : '';
+        const originalSha256 = hashText(originalContent);
+        const modifiedSha256 = hashText(modifiedContent);
+        persistSnapshotBlob(rootDirectory, originalSha256, originalContent);
+        persistSnapshotBlob(rootDirectory, modifiedSha256, modifiedContent);
+        snapshots.push({
+            path: absolutePath,
+            relativePath,
+            originalContent,
+            modifiedContent,
+            ...(typeof record.originalExists === 'boolean' ? { originalExists: record.originalExists } : {}),
+            ...(typeof record.modifiedExists === 'boolean' ? { modifiedExists: record.modifiedExists } : {}),
+            originalSha256,
+            modifiedSha256,
+            originalBlobId: `sha256:${originalSha256}`,
+            modifiedBlobId: `sha256:${modifiedSha256}`,
+            language: typeof record.language === 'string' ? record.language : undefined,
+            addedLines: typeof record.addedLines === 'number' && Number.isFinite(record.addedLines) ? record.addedLines : undefined,
+            removedLines: typeof record.removedLines === 'number' && Number.isFinite(record.removedLines) ? record.removedLines : undefined,
+        });
+    }
+    return snapshots.slice(0, 80);
+}
+function persistSnapshotBlob(rootDirectory, sha256, content) {
+    const directory = join(workspaceIndexDirectory(rootDirectory), 'snapshots', 'blobs');
+    const blobPath = join(directory, sha256);
+    if (existsSync(blobPath))
+        return;
+    mkdirSync(directory, { recursive: true });
+    const temporaryPath = `${blobPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+    try {
+        writeFileSync(temporaryPath, content, 'utf8');
+        if (!existsSync(blobPath))
+            renameSync(temporaryPath, blobPath);
+    }
+    finally {
+        if (existsSync(temporaryPath)) {
+            try {
+                unlinkSync(temporaryPath);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+    }
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const normalized = String(value || '').trim().replace(/\\/g, '/');
+        const key = normalized.toLowerCase();
+        if (!normalized || seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(normalized);
+    }
+    return out;
+}
+function joinPatchDiffs(patches) {
+    return patches
+        .slice(0, MAX_CHECKPOINT_COMPARE_PATCHES)
+        .map((patch) => [
+        `# ${patch.id} / ${patch.summary || patch.title}`,
+        patch.diff.trim(),
+    ].filter(Boolean).join('\n'))
+        .filter(Boolean)
+        .join('\n\n');
+}
+function selectPatchesBetweenCheckpoints(items, fromCheckpointId, toCheckpointId) {
+    const ordered = items
+        .filter((patch) => patch.checkpointId)
+        .slice()
+        .sort((a, b) => a.timestamp - b.timestamp || a.id.localeCompare(b.id));
+    const fromIndex = ordered.findIndex((patch) => patch.checkpointId === fromCheckpointId);
+    const toIndex = ordered.findIndex((patch) => patch.checkpointId === toCheckpointId);
+    if (fromIndex === -1 || toIndex === -1)
+        return [];
+    const start = Math.min(fromIndex, toIndex);
+    const end = Math.max(fromIndex, toIndex);
+    return ordered.slice(start, end + 1);
+}
+function normalizePatchReviewStatus(value, fallback) {
+    return value === 'open'
+        || value === 'approved'
+        || value === 'changes-requested'
+        || value === 'applied'
+        || value === 'dismissed'
+        ? value
+        : fallback;
+}
+function normalizePatchReviewDecisions(value) {
+    if (!Array.isArray(value))
+        return [];
+    const decisions = [];
+    for (const entry of value.slice(-1_000)) {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const record = entry;
+        const id = normalizeOptionalId(record.id);
+        const relativePath = typeof record.relativePath === 'string'
+            ? record.relativePath.trim().replace(/\\/g, '/').slice(0, 2_000)
+            : '';
+        const action = record.action === 'accept' || record.action === 'reject' || record.action === 'comment'
+            ? record.action
+            : undefined;
+        const state = record.state === 'pending' || record.state === 'applied' || record.state === 'failed' || record.state === 'conflict'
+            ? record.state
+            : undefined;
+        if (!id || !relativePath || !action || !state)
+            continue;
+        const createdAt = typeof record.createdAt === 'number' && Number.isFinite(record.createdAt) ? record.createdAt : Date.now();
+        const updatedAt = typeof record.updatedAt === 'number' && Number.isFinite(record.updatedAt) ? record.updatedAt : createdAt;
+        decisions.push({
+            id,
+            relativePath,
+            ...(normalizeOptionalId(record.hunkId) ? { hunkId: normalizeOptionalId(record.hunkId) } : {}),
+            action,
+            ...(normalizeReviewComment(record.comment) ? { comment: normalizeReviewComment(record.comment) } : {}),
+            state,
+            ...(typeof record.expectedBeforeExists === 'boolean' ? { expectedBeforeExists: record.expectedBeforeExists } : {}),
+            ...(normalizeSha256(record.expectedBeforeSha256) ? { expectedBeforeSha256: normalizeSha256(record.expectedBeforeSha256) } : {}),
+            ...(typeof record.resultingExists === 'boolean' ? { resultingExists: record.resultingExists } : {}),
+            ...(normalizeSha256(record.resultingSha256) ? { resultingSha256: normalizeSha256(record.resultingSha256) } : {}),
+            ...(normalizeOptionalId(record.transactionId) ? { transactionId: normalizeOptionalId(record.transactionId) } : {}),
+            ...(typeof record.error === 'string' && record.error.trim() ? { error: record.error.trim().slice(0, 4_000) } : {}),
+            createdAt,
+            updatedAt,
+        });
+    }
+    return decisions;
+}
+function normalizeReviewComment(value) {
+    return typeof value === 'string' && value.trim() ? value.trim().slice(0, 20_000) : undefined;
+}
+function normalizeSha256(value) {
+    return typeof value === 'string' && /^[0-9a-f]{64}$/i.test(value) ? value.toLowerCase() : undefined;
+}
+function reviewPathKey(value) {
+    const normalized = value.replace(/\\/g, '/');
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function derivePatchReviewStatus(item) {
+    const hunks = item.hunks || [];
+    if (hunks.length === 0)
+        return item.status;
+    const effective = effectivePatchDecisions(item.decisions || []);
+    if (effective.size >= hunks.length) {
+        return [...effective.values()].every((action) => action === 'accept') ? 'approved' : 'applied';
+    }
+    return [...effective.values()].some((action) => action === 'reject') ? 'changes-requested' : 'open';
+}
+function matchesReviewDecisionState(inspected, expectedExists, expectedSha256) {
+    if (expectedExists === undefined || inspected.exists !== expectedExists)
+        return false;
+    if (!expectedExists)
+        return true;
+    return !!expectedSha256 && inspected.sha256 === expectedSha256;
+}
+function npmScriptInvocation(scriptName) {
+    if (process.platform === 'win32') {
+        return { command: 'cmd.exe', args: ['/d', '/s', '/c', 'npm', 'run', scriptName] };
+    }
+    return { command: 'npm', args: ['run', scriptName] };
+}
+function classifyScript(name, command) {
+    const haystack = `${name} ${command}`.toLowerCase();
+    if (haystack.includes('typecheck') || haystack.includes('tsc '))
+        return 'typecheck';
+    if (haystack.includes('test') || haystack.includes('vitest') || haystack.includes('jest') || haystack.includes('playwright'))
+        return 'test';
+    if (haystack.includes('lint') || haystack.includes('eslint'))
+        return 'lint';
+    if (haystack.includes('build') || haystack.includes('vite build') || haystack.includes('electron-vite build'))
+        return 'build';
+    return null;
+}
+function checkSortScore(check) {
+    if (check.kind === 'typecheck')
+        return 1;
+    if (check.kind === 'test')
+        return 2;
+    if (check.kind === 'lint')
+        return 3;
+    if (check.kind === 'build')
+        return 4;
+    return 5;
+}
+function collectDiagnosticIssues(rootDirectory, recentRuns, backgroundRuns) {
+    const issues = [];
+    const seen = new Set();
+    for (const run of recentRuns) {
+        const output = [run.error, run.stderr, run.stdout].filter(Boolean).join('\n');
+        for (const issue of parseDiagnosticOutput(rootDirectory, output, run.check.name, run.id)) {
+            const key = diagnosticIssueKey(issue);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            issues.push(issue);
+            if (issues.length >= 100)
+                return issues;
+        }
+    }
+    for (const run of backgroundRuns) {
+        const output = [run.error, run.stderr, run.stdout].filter(Boolean).join('\n');
+        for (const issue of parseDiagnosticOutput(rootDirectory, output, run.check.name, run.id)) {
+            const key = diagnosticIssueKey(issue);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            issues.push(issue);
+            if (issues.length >= 100)
+                return issues;
+        }
+    }
+    return issues;
+}
+function parseDiagnosticOutput(rootDirectory, output, source, runId) {
+    const issues = [];
+    const lines = output.split(/\r?\n/);
+    for (const rawLine of lines) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const parsed = parseDiagnosticLine(rootDirectory, line, source, runId);
+        if (parsed)
+            issues.push(parsed);
+        if (issues.length >= 80)
+            break;
+    }
+    return issues;
+}
+function parseDiagnosticLine(rootDirectory, line, source, runId) {
+    const filePattern = String.raw `(?<file>(?:[A-Za-z]:)?[^:\r\n()]+?\.(?:ts|tsx|js|jsx|mjs|cjs|css|scss|sass|less|json|md|mdx|py|rs|go|c|cc|cpp|h|hpp|cs|java|kt|html|htm))`;
+    const tsMatch = line.match(new RegExp(`^${filePattern}\\((?<line>\\d+),(?<column>\\d+)\\):\\s*(?<severity>error|warning|info)?\\s*(?<code>[A-Za-z]+\\d+)?\\s*:?\\s*(?<message>.+)$`, 'i'));
+    const colonMatch = line.match(new RegExp(`^${filePattern}:(?<line>\\d+):(?<column>\\d+)\\s*(?:[-:]\\s*)?(?<severity>error|warning|warn|info)?\\s*(?<code>[A-Za-z]+\\d+)?\\s*:?\\s*(?<message>.+)$`, 'i'));
+    const failMatch = line.match(new RegExp(`^(?:FAIL|ERROR|Error:)\\s+${filePattern}(?:\\s|$)(?<message>.*)$`, 'i'));
+    const groups = tsMatch?.groups || colonMatch?.groups || failMatch?.groups;
+    if (!groups?.file)
+        return null;
+    const pathInfo = resolveDiagnosticPath(rootDirectory, groups.file);
+    const severityText = (groups.severity || '').toLowerCase();
+    const severity = severityText === 'warning' || severityText === 'warn'
+        ? 'warning'
+        : severityText === 'info'
+            ? 'info'
+            : 'error';
+    const lineNumber = Number(groups.line);
+    const columnNumber = Number(groups.column);
+    const message = String(groups.message || line).trim();
+    return {
+        id: `diag-${runId}-${hashDiagnosticLine(line)}`,
+        rootDirectory,
+        ...pathInfo,
+        line: Number.isFinite(lineNumber) && lineNumber > 0 ? lineNumber : undefined,
+        column: Number.isFinite(columnNumber) && columnNumber > 0 ? columnNumber : undefined,
+        severity,
+        source,
+        code: groups.code,
+        message,
+        runId,
+    };
+}
+function resolveDiagnosticPath(rootDirectory, rawPath) {
+    const cleanPath = rawPath.trim().replace(/^"|"$/g, '').replace(/\\/g, '/');
+    const absolutePath = isAbsolute(cleanPath) ? cleanPath : join(rootDirectory, cleanPath);
+    if (isPathInside(absolutePath, rootDirectory)) {
+        return {
+            filePath: absolutePath,
+            relativePath: relative(rootDirectory, absolutePath).replace(/\\/g, '/'),
+        };
+    }
+    return { relativePath: cleanPath };
+}
+function diagnosticIssueKey(issue) {
+    return [
+        issue.relativePath || issue.filePath || '',
+        issue.line || 0,
+        issue.column || 0,
+        issue.code || '',
+        issue.message,
+    ].join(':');
+}
+function hashDiagnosticLine(line) {
+    let hash = 0;
+    for (let i = 0; i < line.length; i += 1) {
+        hash = ((hash << 5) - hash + line.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+function parseBranch(status) {
+    const line = status.split(/\r?\n/).find((entry) => entry.startsWith('## '));
+    if (!line)
+        return {};
+    const content = line.slice(3).trim();
+    const match = content.match(/^([^.\s]+)(?:\.\.\.([^\s\[]+))?(?:\s+\[(.+)\])?/);
+    if (!match)
+        return { branch: content };
+    const flags = match[3] || '';
+    const aheadMatch = flags.match(/ahead\s+(\d+)/);
+    const behindMatch = flags.match(/behind\s+(\d+)/);
+    return {
+        branch: match[1],
+        upstream: match[2],
+        ahead: aheadMatch ? Number(aheadMatch[1]) : 0,
+        behind: behindMatch ? Number(behindMatch[1]) : 0,
+    };
+}
+function parseGitStatusFiles(rootDirectory, status) {
+    const lines = status.split(/\r?\n/).filter((line) => line && !line.startsWith('## '));
+    return lines.map((line) => {
+        const indexStatus = line[0] || ' ';
+        const workTreeStatus = line[1] || ' ';
+        const statusCode = `${indexStatus}${workTreeStatus}`.trim() || 'M';
+        let body = line.slice(3).trim();
+        let renamedFrom;
+        if (body.includes(' -> ')) {
+            const [from, to] = body.split(' -> ');
+            if (from !== undefined && to !== undefined) {
+                renamedFrom = cleanGitPath(from);
+                body = to;
+            }
+        }
+        const relativePath = cleanGitPath(body);
+        return {
+            path: join(rootDirectory, relativePath),
+            relativePath,
+            status: statusCode,
+            indexStatus: indexStatus.trim() || ' ',
+            workTreeStatus: workTreeStatus.trim() || ' ',
+            renamedFrom,
+        };
+    });
+}
+function cleanGitPath(value) {
+    return value.trim().replace(/^"|"$/g, '').replace(/\\/g, '/');
+}
+function parseNumstat(numstat) {
+    const map = new Map();
+    for (const line of numstat.split(/\r?\n/)) {
+        const parts = line.split(/\t/);
+        if (parts.length < 3)
+            continue;
+        const additions = Number(parts[0]);
+        const deletions = Number(parts[1]);
+        const relativePath = cleanGitPath(parts.slice(2).join('\t'));
+        if (!relativePath)
+            continue;
+        map.set(relativePath, {
+            additions: Number.isFinite(additions) ? additions : 0,
+            deletions: Number.isFinite(deletions) ? deletions : 0,
+        });
+    }
+    return map;
+}
+/**
+ * The first adopter of `CommandExecutionPort` — ADE §5.3.
+ *
+ * 🔴 A thin adapter now, deliberately. The spawning moved to
+ * `LocalCommandExecutor` unchanged; what remains here is the mapping from the
+ * port's result to `ProcessResult`, which differs by exactly one field:
+ * `success`. Seven call sites read `result.success`, and rewriting them was not
+ * the point of this change — proving the port's shape against real code was.
+ *
+ * `success` now comes from `commandSucceeded` rather than being recomputed
+ * here. The old expression was `!timedOut && code === 0`, which is equivalent
+ * for every case this site can produce, and the shared one additionally refuses
+ * success when `error` is set — the case the spawn-failure branch used to
+ * handle by writing `success: false` by hand. One spelling, and the site that
+ * had it right stops being the one that has its own copy.
+ *
+ * This is why engineering went first: its `ProcessResult` WAS the model for
+ * `CommandExecutionResult`, so nothing had to bend to fit. An adoption that has
+ * to contort the caller is evidence the port is wrong.
+ */
+const commandExecutor = new LocalCommandExecutor();
+function runProcess(command, args, cwd, timeoutMs, outputLimit) {
+    return commandExecutor
+        .execute({
+        // The port takes argv as a LIST, and this site already had it split —
+        // which is the shape the sandbox implementation needs and the reason the
+        // rule cost nothing here.
+        argv: [command, ...args],
+        cwd,
+        timeoutMs,
+        maxOutputBytes: outputLimit,
+    })
+        .then((result) => ({
+        stdout: result.stdout,
+        stderr: result.stderr,
+        exitCode: result.exitCode,
+        success: commandSucceeded(result),
+        timedOut: result.timedOut,
+        truncated: result.truncated,
+        ...(result.error === undefined ? {} : { error: result.error }),
+    }));
+}
+function killProcessTree(child) {
+    if (process.platform === 'win32' && child.pid) {
+        const killer = spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+            windowsHide: true,
+            shell: false,
+            stdio: 'ignore',
+        });
+        killer.on('error', () => {
+            try {
+                child.kill();
+            }
+            catch { /* process already exited */ }
+        });
+        return;
+    }
+    try {
+        child.kill();
+    }
+    catch { /* process already exited */ }
+}
+let singleton = null;
+export function getEngineeringWorkbenchService() {
+    if (!singleton)
+        singleton = new EngineeringWorkbenchService();
+    return singleton;
+}
+/**
+ * Refuses a ref name git would accept but a caller rarely means.
+ *
+ * These names reach a command line. `--upload-pack=...` is a git OPTION, not a
+ * branch, and a name beginning with a dash is read as one wherever the argument
+ * is not guarded by `--`. Rejecting the shape is simpler and stronger than
+ * remembering to place `--` correctly at every call site, and the failure is
+ * legible rather than mysterious.
+ */
+function validateRefName(name) {
+    if (!name)
+        return 'A branch name is required.';
+    if (name.length > 255)
+        return 'Branch names are limited to 255 characters.';
+    if (name.startsWith('-'))
+        return 'A branch name may not begin with a dash; git would read it as an option.';
+    // git check-ref-format's own rules, the ones that matter here.
+    if (/[\s~^:?*\[\\]/.test(name))
+        return 'Branch names may not contain whitespace or any of ~ ^ : ? * [ \\';
+    if (name.includes('..') || name.endsWith('.lock') || name.endsWith('/') || name.startsWith('/')) {
+        return 'That is not a valid git ref name.';
+    }
+    return undefined;
+}
+function validateRemoteName(name) {
+    if (!name)
+        return 'A remote name is required.';
+    if (name.startsWith('-'))
+        return 'A remote name may not begin with a dash; git would read it as an option.';
+    if (!/^[A-Za-z0-9._\/-]+$/.test(name))
+        return 'That is not a valid git remote name.';
+    return undefined;
+}
+//# sourceMappingURL=EngineeringWorkbenchService.js.map