@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/workspace_collision.js

@@ -0,0 +1,688 @@
+/** Local, observational coordination. These records are advisory, never leases or locks. */
+import { execFile, spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants as fsConstants, closeSync, fstatSync, linkSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync } from 'node:fs';
+import { chmod, copyFile, link, lstat, mkdir, mkdtemp, open, readFile, readdir, readlink, realpath, rename, symlink, unlink, writeFile } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { deriveWorkspaceSessionWork, parseWorkspaceSessionWork, formatWorkspaceSessionWork } from './workspace_session_context.js';
+export class WorkspaceIsolationError extends Error {
+    retainedTarget;
+    constructor(message, retainedTarget = null) {
+        super(message);
+        this.retainedTarget = retainedTarget;
+        this.name = 'WorkspaceIsolationError';
+    }
+}
+const MAX_RECORDS = 128;
+const MAX_OWNER_SCAN = 4096;
+const MAX_PEERS = 32;
+const MAX_RECORD_BYTES = 64 * 1024;
+const WORK_CONTEXT_WARNING = 'Uncertain local work context: an owner summary was unavailable or invalid; presence evidence remains advisory.';
+const MAX_PATHS = 64;
+const STALE_MS = 90_000;
+const GIT_TIMEOUT_MS = 2_000;
+const PATCH_LIMIT = 16 * 1024 * 1024;
+const FILE_LIMIT = 64 * 1024 * 1024;
+const COPY_PATH_LIMIT = 512;
+const execFileAsync = promisify(execFile);
+function ownersDirectory() {
+    // All profiles share local coordination; selecting a profile cannot hide a sibling.
+    return join(process.env.ZTC_CONFIG_DIR || join(homedir(), '.ztc'), 'workspace-owners');
+}
+function gitEnvironment() {
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE'])
+        delete env[key];
+    return { ...env, GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' };
+}
+async function git(cwd, args, limit = 1024 * 1024, timeout = GIT_TIMEOUT_MS) {
+    const result = await execFileAsync('git', ['-C', cwd, ...args], {
+        env: gitEnvironment(), encoding: 'buffer', timeout, maxBuffer: limit,
+        windowsHide: true,
+    });
+    return result.stdout;
+}
+async function canonical(path) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        const absolute = resolve(path);
+        const parent = dirname(absolute);
+        return parent === absolute ? absolute : join(await canonical(parent), relative(parent, absolute));
+    }
+}
+async function gitIdentity(cwd) {
+    try {
+        const paths = (await git(cwd, ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'])).toString('utf8').trim().split('\n');
+        if (paths.length !== 2)
+            throw new Error('Invalid Git identity');
+        const [repositoryRoot, gitCommonDir] = await Promise.all(paths.map(canonical));
+        const [branch, head] = await Promise.all([
+            git(cwd, ['symbolic-ref', '--quiet', '--short', 'HEAD']).then(value => value.toString('utf8').trim()).catch(() => null),
+            git(cwd, ['rev-parse', '--verify', 'HEAD']).then(value => value.toString('utf8').trim()).catch(() => null),
+        ]);
+        return { repositoryRoot, gitCommonDir, branch, head };
+    }
+    catch {
+        return { repositoryRoot: null, gitCommonDir: null, branch: null, head: null };
+    }
+}
+function liveness(pid) {
+    try {
+        process.kill(pid, 0);
+        return 'live';
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'dead' : 'unknown';
+    }
+}
+function isKind(value) {
+    return value === 'interactive' || value === 'headless' || value === 'colony_child';
+}
+function isActivity(value) {
+    return value === 'idle' || value === 'running' || value === 'paused' || value === 'unknown';
+}
+function parsePresence(value, source) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const item = value;
+    if (!Number.isSafeInteger(item.pid) || item.pid <= 0
+        || typeof item.sessionId !== 'string' || !item.sessionId || item.sessionId.length > 256
+        || typeof item.cwd !== 'string' || !isAbsolute(item.cwd) || item.cwd.length > 4096
+        || typeof item.startedAt !== 'string' || !isKind(item.kind)
+        || (source === 'owner' && item.schemaVersion !== 1))
+        return null;
+    const observedPaths = Array.isArray(item.observedPaths)
+        ? item.observedPaths.filter((path) => typeof path === 'string' && isAbsolute(path) && path.length <= 4096).slice(0, MAX_PATHS)
+        : undefined;
+    return { sessionId: item.sessionId, pid: item.pid, cwd: item.cwd,
+        startedAt: item.startedAt, kind: item.kind, source, processIdentity: 'unknown',
+        heartbeatAt: typeof item.heartbeatAt === 'string' ? item.heartbeatAt : undefined,
+        activity: source === 'owner' && isActivity(item.activity) ? item.activity : 'unknown',
+        observedPaths: source === 'owner' ? observedPaths : undefined,
+        work: source === 'owner' ? parseWorkspaceSessionWork(item.work) : null };
+}
+async function readBounded(path) {
+    const metadata = await lstat(path);
+    if (!metadata.isFile() || metadata.size > MAX_RECORD_BYTES)
+        throw new Error('Invalid or oversized presence file');
+    const handle = await open(path, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK);
+    try {
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.dev !== metadata.dev || opened.ino !== metadata.ino)
+            throw new Error('Presence file changed during admission');
+        const buffer = Buffer.alloc(MAX_RECORD_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > MAX_RECORD_BYTES)
+            throw new Error('Presence output limit exceeded');
+        return JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Kernel start time distinguishes a reused PID from the captured process.
+ * Missing/unsupported observations remain uncertain; presence is advisory. */
+async function observedProcessStart(pid, timeout) {
+    try {
+        const result = await execFileAsync('ps', ['-p', String(pid), '-o', 'lstart='], {
+            timeout, maxBuffer: 1024, env: { ...process.env, LC_ALL: 'C', TZ: 'UTC' },
+        });
+        const value = Date.parse(`${result.stdout.trim()} UTC`);
+        return Number.isFinite(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Startup maintenance touches only canonical publications whose PID is gone.
+ * Capture before rechecking; preserve replacements, malformed data, and uncertainty. */
+async function reapExitedOwnerRecords() {
+    let names;
+    try {
+        names = (await readdir(ownersDirectory())).sort().slice(0, MAX_OWNER_SCAN);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    for (const name of names) {
+        if (!/^\d+-[a-f0-9]{16}-[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        const path = join(ownersDirectory(), name);
+        let record;
+        try {
+            record = parsePresence(await readBounded(path), 'owner');
+        }
+        catch {
+            continue;
+        }
+        if (!record || !name.startsWith(`${record.pid}-${createHash('sha256').update(record.sessionId).digest('hex').slice(0, 16)}-`)
+            || liveness(record.pid) !== 'dead')
+            continue;
+        const captured = `${path}.${randomUUID()}.retired.json`;
+        let removed = false;
+        try {
+            await rename(path, captured);
+            const current = parsePresence(await readBounded(captured), 'owner');
+            if (current && current.pid === record.pid && current.sessionId === record.sessionId
+                && current.startedAt === record.startedAt && liveness(current.pid) === 'dead') {
+                await unlink(captured);
+                removed = true;
+            }
+        }
+        catch { /* An unreadable/replaced record remains conservative evidence. */ }
+        finally {
+            if (!removed) {
+                try {
+                    await link(captured, path);
+                    await unlink(captured);
+                }
+                catch (error) {
+                    if (!['ENOENT', 'EEXIST'].includes(error.code ?? ''))
+                        throw error;
+                }
+            }
+        }
+    }
+}
+async function readPresence() {
+    const records = [];
+    const warnings = [];
+    let names = [];
+    try {
+        names = (await readdir(ownersDirectory())).filter(name => name.endsWith('.json')).sort();
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            warnings.push('Uncertain local presence: workspace owner records are unreadable.');
+    }
+    if (names.length > MAX_OWNER_SCAN)
+        warnings.push('Uncertain local presence: the bounded owner scan is incomplete.');
+    const starts = new Map();
+    const identityDeadline = performance.now() + GIT_TIMEOUT_MS;
+    const active = async (record) => {
+        const state = liveness(record.pid);
+        if (state === 'dead')
+            return false;
+        if (state === 'unknown')
+            return true;
+        let start = starts.get(record.pid);
+        if (!start) {
+            const remaining = Math.floor(identityDeadline - performance.now());
+            start = remaining <= 0 ? Promise.resolve(null) : observedProcessStart(record.pid, remaining);
+            starts.set(record.pid, start);
+        }
+        const observed = await start, captured = Date.parse(record.startedAt);
+        // Owner records capture process birth from Node uptime. Legacy instance
+        // records capture registration, which may happen well after startup.
+        // A process born after that registration is a reused PID; an earlier birth
+        // remains valid legacy evidence. ps has a two-second rounding allowance.
+        record.processIdentity = observed === null || !Number.isFinite(captured) ? 'unknown' : 'matched';
+        return record.processIdentity === 'unknown' || (record.source === 'legacy'
+            ? observed <= captured + 2000 : Math.abs(observed - captured) <= 2000);
+    };
+    for (const name of names.slice(0, MAX_OWNER_SCAN)) {
+        try {
+            const raw = await readBounded(join(ownersDirectory(), name));
+            const record = parsePresence(raw, 'owner');
+            if (record && await active(record)) {
+                records.push(record);
+                if (raw !== null && typeof raw === 'object' && Object.prototype.hasOwnProperty.call(raw, 'work') && record.work === null)
+                    warnings.push(WORK_CONTEXT_WARNING);
+            }
+            else if (!record)
+                warnings.push('Uncertain local presence: an invalid workspace owner record was retained.');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                warnings.push('Uncertain local presence: an unreadable workspace owner record was retained.');
+        }
+    }
+    try {
+        const legacy = await readBounded(join(homedir(), '.ztc', 'instances.json'));
+        if (!Array.isArray(legacy))
+            throw new Error('Invalid legacy registry');
+        for (const value of legacy) {
+            const record = parsePresence(value, 'legacy');
+            if (record && await active(record))
+                records.push(record);
+            else if (!record)
+                warnings.push('Uncertain local presence: an invalid legacy instance was retained.');
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            warnings.push('Uncertain local presence: the legacy registry is unreadable.');
+    }
+    // Prefer independent owner records, while leaving both source files untouched.
+    const unique = new Map();
+    for (const record of records) {
+        const key = `${record.pid}:${record.sessionId}`;
+        if (!unique.has(key) || record.source === 'owner')
+            unique.set(key, record);
+    }
+    if (unique.size > MAX_RECORDS)
+        warnings.push('Uncertain local presence: the bounded live owner inventory is incomplete.');
+    return { records: [...unique.values()].slice(0, MAX_RECORDS), warnings: [...new Set(warnings)] };
+}
+function evidenceQuality(record, now) {
+    const heartbeat = Date.parse(record.heartbeatAt || '');
+    const evidenceAgeMs = Number.isFinite(heartbeat) ? Math.max(0, now - heartbeat) : null;
+    if (record.processIdentity === 'unknown' || liveness(record.pid) === 'unknown' || evidenceAgeMs === null)
+        return { evidenceQuality: 'unknown', evidenceAgeMs };
+    return { evidenceQuality: evidenceAgeMs > STALE_MS ? 'stale' : record.source === 'owner' ? 'observed' : 'live', evidenceAgeMs };
+}
+async function sessionEvidence(record, now) {
+    const cwd = await canonical(record.cwd);
+    return { sessionId: record.sessionId, pid: record.pid, startedAt: record.startedAt, cwd,
+        ...(await gitIdentity(cwd)), kind: record.kind, activity: record.activity || 'unknown',
+        observedPaths: [...new Set(record.observedPaths || [])].sort(),
+        fileEvidence: record.source === 'owner' && Array.isArray(record.observedPaths) ? 'observed' : 'unknown',
+        ...evidenceQuality(record, now), work: record.source === 'owner' ? record.work ?? null : null };
+}
+function sameRepository(left, right) {
+    return left.gitCommonDir !== null && right.gitCommonDir !== null
+        ? left.gitCommonDir === right.gitCommonDir
+        : left.repositoryRoot === null && right.repositoryRoot === null && left.cwd === right.cwd;
+}
+function collisionReasons(snapshot) {
+    return snapshot.reasons.filter(reason => reason !== WORK_CONTEXT_WARNING);
+}
+/** Missing work context is advisory; actual presence, branch and path risks still require admission. */
+export function hasWorkspaceCollisionRisk(snapshot) {
+    return collisionReasons(snapshot).length > 0;
+}
+function fingerprint(snapshot) {
+    const stable = (owner) => ({ sessionId: owner.sessionId, pid: owner.pid,
+        startedAt: owner.startedAt, cwd: owner.cwd, repositoryRoot: owner.repositoryRoot, gitCommonDir: owner.gitCommonDir,
+        branch: owner.branch, head: owner.head, activity: owner.activity, observedPaths: owner.observedPaths,
+        fileEvidence: owner.fileEvidence, evidenceQuality: owner.evidenceQuality });
+    const { current } = snapshot;
+    // A caller's own idle/running/paused transitions do not create a new risk.
+    // Own paths affect the decision only when they add an overlap reason.
+    const identity = { sessionId: current.sessionId, pid: current.pid, startedAt: current.startedAt,
+        cwd: current.cwd, repositoryRoot: current.repositoryRoot, gitCommonDir: current.gitCommonDir,
+        branch: current.branch, head: current.head };
+    // Summary availability/content never creates a new workspace-collision decision.
+    return createHash('sha256').update(JSON.stringify({ current: identity, peers: snapshot.peers.map(stable), reasons: collisionReasons(snapshot) })).digest('hex');
+}
+/** Read-only: never call the legacy registry's pruning/reaping readers. */
+export async function inspectWorkspaceSessions(cwd, sessionId) {
+    const now = Date.now();
+    const presence = await readPresence();
+    const currentRecord = presence.records.find(record => record.pid === process.pid && (!sessionId || record.sessionId === sessionId));
+    const current = await sessionEvidence(currentRecord ? { ...currentRecord, cwd } : {
+        sessionId: sessionId || 'unknown', pid: process.pid, startedAt: new Date(now - process.uptime() * 1000).toISOString(),
+        cwd: resolve(cwd), kind: 'interactive', source: 'legacy', activity: 'unknown', processIdentity: 'unknown',
+    }, now);
+    const candidates = presence.records.filter(record => !(record.pid === process.pid && record.sessionId === current.sessionId)
+        && liveness(record.pid) !== 'dead');
+    const reasons = [...presence.warnings];
+    if (candidates.length > MAX_PEERS)
+        reasons.push('Uncertain local presence: the bounded peer discovery is incomplete.');
+    const peers = [];
+    // Four independent Git probes at a time; all commands have fixed argv and bounded output/time.
+    const selected = candidates.slice(0, MAX_PEERS);
+    for (let offset = 0; offset < selected.length; offset += 4) {
+        const batch = await Promise.all(selected.slice(offset, offset + 4).map(record => sessionEvidence(record, now)));
+        peers.push(...batch.filter(peer => sameRepository(current, peer)));
+    }
+    peers.sort((a, b) => a.sessionId.localeCompare(b.sessionId) || a.pid - b.pid || a.startedAt.localeCompare(b.startedAt));
+    for (const peer of peers) {
+        if (current.repositoryRoot !== null && current.repositoryRoot === peer.repositoryRoot)
+            reasons.push(`Same worktree: ${peer.sessionId} (${peer.activity}; ${peer.evidenceQuality} evidence).`);
+        if (current.branch !== null && current.branch === peer.branch)
+            reasons.push(`Same branch: ${peer.sessionId} on ${peer.branch}.`);
+        const overlap = current.observedPaths.filter(path => peer.observedPaths.includes(path));
+        if (overlap.length)
+            reasons.push(`Observed file activity overlaps ${peer.sessionId}: ${overlap.join(', ')}.`);
+        if (peer.evidenceQuality === 'stale' || peer.evidenceQuality === 'unknown')
+            reasons.push(`Uncertain activity: ${peer.sessionId} remains a live or unverifiable process; stale evidence is not an ownership grant.`);
+    }
+    const snapshot = { current, peers, reasons: [...new Set(reasons)].sort(), observedAt: new Date(now).toISOString() };
+    return { ...snapshot, fingerprint: fingerprint(snapshot) };
+}
+export function formatWorkspaceSnapshot(snapshot) {
+    const { current } = snapshot;
+    const lines = ['Active local sessions (advisory; observed activity is not an enforced lock):',
+        `Current: ${current.sessionId}  PID ${current.pid}  ${current.activity}`,
+        `Repository: ${current.repositoryRoot || 'unknown (not a Git repository)'}`,
+        `Branch: ${current.branch || 'unknown / detached'}`];
+    lines.push(...formatWorkspaceSessionWork(current.work, current.evidenceQuality));
+    if (!snapshot.peers.length)
+        lines.push('No sibling sessions observed in this repository.');
+    for (const peer of snapshot.peers) {
+        lines.push(`${peer.sessionId}  PID ${peer.pid}  ${peer.activity}  ${peer.evidenceQuality} evidence`, `  Repository: ${peer.repositoryRoot || 'unknown'}  Branch: ${peer.branch || 'unknown / detached'}`, `  ${peer.fileEvidence === 'unknown' ? 'File ownership unknown; no attributed write observations' : `Observed file activity: ${peer.observedPaths.length ? peer.observedPaths.join(', ') : 'no writes observed; other file activity remains unknown'}`}`);
+        lines.push(...formatWorkspaceSessionWork(peer.work, peer.evidenceQuality));
+    }
+    lines.push(...snapshot.reasons);
+    lines.push('Continue knowingly, isolate into a new worktree, or pause. This does not grant remote ownership.');
+    return lines.join('\n');
+}
+export class LocalWorkspaceCoordinator {
+    options;
+    startedAt = new Date(Date.now() - process.uptime() * 1000).toISOString();
+    recordPath;
+    activity = 'idle';
+    paths = [];
+    acknowledgement = null;
+    timer = null;
+    pending = Promise.resolve();
+    closed = false;
+    publication = null;
+    onProcessExit = () => { this.closeSync(); };
+    listeningForExit = false;
+    constructor(options) {
+        this.options = options;
+        if (!options.sessionId || options.sessionId.length > 256)
+            throw new Error('A canonical session ID is required for local workspace coordination.');
+        this.recordPath = join(ownersDirectory(), `${process.pid}-${createHash('sha256').update(options.sessionId).digest('hex').slice(0, 16)}-${randomUUID()}.json`);
+    }
+    async start() {
+        if (!this.listeningForExit && !this.closed) {
+            process.on('exit', this.onProcessExit);
+            this.listeningForExit = true;
+        }
+        try {
+            await reapExitedOwnerRecords();
+        }
+        catch { /* The following read-only inspection surfaces inaccessible records. */ }
+        const snapshot = await this.refresh();
+        if (!this.timer && !this.closed) {
+            this.timer = setInterval(() => { void this.refresh().catch(() => { }); }, 15_000);
+            this.timer.unref();
+        }
+        return snapshot;
+    }
+    refresh() {
+        const operation = this.pending.then(async () => {
+            if (this.closed)
+                throw new Error('Local workspace coordinator is closed.');
+            const cwd = await canonical(this.options.getCwd());
+            let warning = null;
+            let work = null;
+            let workWarning = null;
+            if (this.options.getWork) {
+                try {
+                    work = deriveWorkspaceSessionWork({ ...this.options.getWork(), cwd }, this.options.sessionId);
+                }
+                catch { /* Context failure leaves the independently observed peer identity available. */ }
+                if (work === null)
+                    workWarning = WORK_CONTEXT_WARNING;
+            }
+            const record = { schemaVersion: 1, sessionId: this.options.sessionId, pid: process.pid,
+                startedAt: this.startedAt, cwd, kind: this.options.kind, heartbeatAt: new Date().toISOString(),
+                activity: this.activity, observedPaths: this.paths, ...(this.options.getWork ? { work } : {}) };
+            let publication = JSON.stringify(record);
+            // New summaries must not make previously admitted identity/path evidence unreadable.
+            if (this.options.getWork && Buffer.byteLength(publication) > MAX_RECORD_BYTES) {
+                work = null;
+                record.work = null;
+                workWarning = WORK_CONTEXT_WARNING;
+                publication = JSON.stringify(record);
+                if (Buffer.byteLength(publication) > MAX_RECORD_BYTES) {
+                    delete record.work;
+                    publication = JSON.stringify(record);
+                }
+            }
+            const temporary = `${this.recordPath}.${randomUUID()}.tmp`;
+            try {
+                await mkdir(dirname(this.recordPath), { recursive: true, mode: 0o700 });
+                await writeFile(temporary, publication, { flag: 'wx', mode: 0o600 });
+                const identity = await lstat(temporary);
+                await rename(temporary, this.recordPath);
+                this.publication = { device: identity.dev, inode: identity.ino, sha256: createHash('sha256').update(publication).digest('hex') };
+            }
+            catch {
+                warning = 'Uncertain local presence: this session could not publish its advisory activity.';
+            }
+            finally {
+                try {
+                    await unlink(temporary);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        warning = 'Uncertain local presence: an incomplete publication could not be removed.';
+                }
+            }
+            const inspected = await inspectWorkspaceSessions(cwd, this.options.sessionId);
+            // The owning process knows its own state even if publication is unavailable.
+            inspected.current = { ...inspected.current, startedAt: this.startedAt, kind: this.options.kind,
+                activity: this.activity, observedPaths: [...this.paths], fileEvidence: 'observed', work };
+            if (warning)
+                inspected.reasons = [...new Set([...inspected.reasons, warning])].sort();
+            if (workWarning)
+                inspected.reasons = [...new Set([...inspected.reasons, workWarning])].sort();
+            inspected.fingerprint = fingerprint(inspected);
+            this.options.onSnapshot?.(inspected);
+            return inspected;
+        });
+        this.pending = operation.catch(() => { });
+        return operation;
+    }
+    setActivity(activity) {
+        this.activity = activity;
+        return this.refresh();
+    }
+    async recordObservedPaths(paths, cwd = this.options.getCwd()) {
+        const normalized = await Promise.all(paths.slice(0, MAX_PATHS).filter(path => typeof path === 'string' && path.length <= 4096)
+            .map(path => canonical(resolve(cwd, path))));
+        this.paths = [...new Set([...this.paths, ...normalized])].sort().slice(0, MAX_PATHS);
+        return this.refresh();
+    }
+    acknowledge(snapshot) { this.acknowledgement = snapshot.fingerprint; }
+    isAcknowledged(snapshot) { return this.acknowledgement === snapshot.fingerprint; }
+    async close() {
+        this.closed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        await this.pending;
+        this.closeSync();
+    }
+    /** Only the exact directly owned publication may be retired during process exit. */
+    closeSync() {
+        this.closed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        process.removeListener('exit', this.onProcessExit);
+        this.listeningForExit = false;
+        const expected = this.publication;
+        if (!expected)
+            return;
+        const captured = `${this.recordPath}.${randomUUID()}.retired.json`;
+        let owned = false;
+        try {
+            renameSync(this.recordPath, captured);
+            const fd = openSync(captured, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+            try {
+                const identity = fstatSync(fd);
+                owned = identity.isFile() && identity.size <= MAX_RECORD_BYTES && identity.dev === expected.device
+                    && identity.ino === expected.inode && createHash('sha256').update(readFileSync(fd)).digest('hex') === expected.sha256;
+            }
+            finally {
+                closeSync(fd);
+            }
+            if (owned) {
+                unlinkSync(captured);
+                this.publication = null;
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                console.error('Could not retire the owned workspace presence record:', error.message);
+        }
+        finally {
+            if (!owned) {
+                // Hard-link restoration never replaces a newer publication. A replaced
+                // file remains discoverable under the capture name if the original is busy.
+                try {
+                    lstatSync(captured);
+                    linkSync(captured, this.recordPath);
+                    unlinkSync(captured);
+                }
+                catch (error) {
+                    if (!['ENOENT', 'EEXIST'].includes(error.code ?? ''))
+                        console.error('Could not restore a replaced workspace presence record:', error.message);
+                }
+            }
+        }
+    }
+}
+function hash(value) { return createHash('sha256').update(value).digest('hex'); }
+async function captureSource(root) {
+    const [staged, unstaged, stagedPaths, unstagedPaths, untrackedRaw, indexRaw] = await Promise.all([
+        git(root, ['diff', '--cached', '--binary', '--no-ext-diff', 'HEAD', '--'], PATCH_LIMIT),
+        git(root, ['diff', '--binary', '--no-ext-diff', '--'], PATCH_LIMIT),
+        git(root, ['diff', '--cached', '--no-renames', '--name-only', '-z', 'HEAD', '--']),
+        git(root, ['diff', '--no-renames', '--name-only', '-z', '--']),
+        git(root, ['ls-files', '--others', '--exclude-standard', '-z']),
+        git(root, ['rev-parse', '--path-format=absolute', '--git-path', 'index']),
+    ]);
+    const split = (value) => value.toString('utf8').split('\0').filter(Boolean);
+    const untracked = split(untrackedRaw);
+    const paths = [...new Set([...split(stagedPaths), ...split(unstagedPaths), ...untracked])].sort();
+    if (paths.length > COPY_PATH_LIMIT)
+        throw new Error('Workspace isolation path limit exceeded; reduce the working set and retry.');
+    let size = 0;
+    const entries = [];
+    for (const path of paths) {
+        if (isAbsolute(path) || path.split(/[\\/]/).includes('..'))
+            throw new Error('Unsupported path in working tree.');
+        const absolute = join(root, path);
+        let metadata;
+        try {
+            metadata = await lstat(absolute);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                entries.push(`${path}:deleted`);
+                continue;
+            }
+            throw error;
+        }
+        if (metadata.isSymbolicLink()) {
+            entries.push(`${path}:link:${await readlink(absolute)}`);
+            continue;
+        }
+        if (!metadata.isFile())
+            throw new Error('Workspace isolation cannot copy submodule or special-file edits; preserve them manually.');
+        size += metadata.size;
+        if (size > FILE_LIMIT)
+            throw new Error('Workspace isolation content limit exceeded; preserve large files manually.');
+        entries.push(`${path}:${metadata.mode & 0o777}:${hash(await readFile(absolute))}`);
+    }
+    let index;
+    try {
+        index = hash(await readFile(indexRaw.toString('utf8').trim()));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            index = 'absent';
+        else
+            throw error;
+    }
+    return { staged, unstaged, paths, untracked, index, bytes: hash(JSON.stringify(entries)) };
+}
+async function applyPatch(cwd, patch, staged) {
+    if (!patch.length)
+        return;
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn('git', ['-C', cwd, 'apply', '--binary', ...(staged ? ['--index'] : []), '-'], {
+            env: gitEnvironment(), stdio: ['pipe', 'ignore', 'pipe'], windowsHide: true,
+        });
+        let stderr = '';
+        let timeout = false;
+        const timer = setTimeout(() => { timeout = true; child.kill('SIGKILL'); }, 10_000);
+        child.stderr.on('data', chunk => { if (stderr.length < 4096)
+            stderr += chunk.toString().slice(0, 4096 - stderr.length); });
+        child.stdin.on('error', () => { });
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', code => { clearTimeout(timer); code === 0 ? resolvePromise() : reject(new Error(timeout ? 'Git patch application timed out.' : `Git patch application failed: ${stderr.trim()}`)); });
+        child.stdin.end(patch);
+    });
+}
+function inside(parent, child) {
+    const path = relative(parent, child);
+    return path === '' || (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+}
+/** Create an isolated copy without stashing, resetting, checking out, or editing the source index. */
+export async function prepareWorkspaceIsolation(snapshot, target) {
+    const source = snapshot.current.repositoryRoot;
+    if (!source || !snapshot.current.head)
+        throw new WorkspaceIsolationError('A committed Git repository is required for workspace isolation.');
+    let destination = null;
+    let created = false;
+    try {
+        const current = await gitIdentity(source);
+        if (current.head !== snapshot.current.head || current.gitCommonDir !== snapshot.current.gitCommonDir)
+            throw new Error('Source HEAD changed since the workspace snapshot; refresh and retry isolation.');
+        const before = await captureSource(source);
+        if (target) {
+            destination = resolve(await canonical(dirname(resolve(target))), resolve(target).split(sep).at(-1));
+            if (inside(source, destination))
+                throw new Error('The isolation target must be outside the source repository.');
+            try {
+                await lstat(destination);
+                throw new Error('The isolation target already exists; choose a new target.');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        else {
+            destination = await mkdtemp(join(tmpdir(), 'ztc-workspace-'));
+            // Git permits an empty precreated directory; no existing user files are removed.
+        }
+        const branch = `ztc-isolate-${Date.now().toString(36)}-${randomUUID().slice(0, 8)}`;
+        // No --force: branch/path collisions remain recoverable errors.
+        created = true;
+        await git(source, ['worktree', 'add', '-b', branch, '--', destination, snapshot.current.head], 1024 * 1024, 10_000);
+        await applyPatch(destination, before.staged, true);
+        await applyPatch(destination, before.unstaged, false);
+        for (const path of before.untracked) {
+            const from = join(source, path);
+            const to = join(destination, path);
+            await mkdir(dirname(to), { recursive: true });
+            const metadata = await lstat(from);
+            if (metadata.isSymbolicLink())
+                await symlink(await readlink(from), to);
+            else {
+                await copyFile(from, to);
+                await chmod(to, metadata.mode & 0o777);
+            }
+        }
+        const [after, isolated, latest] = await Promise.all([captureSource(source), captureSource(destination), gitIdentity(source)]);
+        if (before.index !== after.index || before.bytes !== after.bytes || !before.staged.equals(after.staged)
+            || !before.unstaged.equals(after.unstaged) || latest.head !== snapshot.current.head)
+            throw new Error('Source changed while preparing isolation; both workspaces were retained for recovery.');
+        if (before.bytes !== isolated.bytes || !before.staged.equals(isolated.staged) || !before.unstaged.equals(isolated.unstaged))
+            throw new Error('The isolated copy did not preserve all captured edits; both workspaces were retained for recovery.');
+        const subdirectory = relative(source, snapshot.current.cwd);
+        const cwd = inside(source, snapshot.current.cwd) ? join(destination, subdirectory) : destination;
+        await mkdir(cwd, { recursive: true });
+        return { cwd, sourceCwd: snapshot.current.cwd, copiedPaths: [...before.paths], preservedSource: true };
+    }
+    catch (error) {
+        // A partial worktree is never force-removed. The caller receives its recovery path.
+        let retainedTarget = null;
+        if (created && destination) {
+            try {
+                await lstat(destination);
+                retainedTarget = destination;
+            }
+            catch (probeError) {
+                if (probeError.code !== 'ENOENT')
+                    retainedTarget = destination;
+            }
+        }
+        throw new WorkspaceIsolationError(error.message, retainedTarget);
+    }
+}