handmux 0.23.0 → 0.25.0

package/dist/src/workspace/checkpointer.js

@@ -0,0 +1,228 @@
+import { captureWorkspace } from './capture.js';
+import { detectEnvironmentChange } from './environment.js';
+import { fingerprintSnapshot } from './schema.js';
+function sameSnapshot(left, right) {
+    return fingerprintSnapshot(left) === fingerprintSnapshot(right);
+}
+function snapshotEnvironment(observed) {
+    return {
+        id: observed.id,
+        bootIdentity: observed.bootIdentity,
+        tmuxServerId: observed.tmuxServerId,
+    };
+}
+async function reconcileOnce(deps, cause) {
+    const handle = await deps.lock.tryAcquire({ operationId: `checkpointer:${cause}` });
+    if (!handle)
+        return { status: 'locked' };
+    try {
+        const observed = await deps.observeEnvironment();
+        if (!observed || observed.status === 'unknown')
+            return { status: 'unknown' };
+        const live = await deps.store.readLive();
+        if (live.status === 'corrupt')
+            return live;
+        const previous = live.status === 'ok' ? live.value.environment : null;
+        let change = detectEnvironmentChange(previous, observed);
+        if (cause === 'confirmed-empty' && observed.status === 'absent') {
+            change = { status: 'same', reason: 'same', current: observed };
+        }
+        if (change.status === 'unknown')
+            return change;
+        // An absent tmux server only ends a known live generation. An already-empty generation remains
+        // unknown unless a Handmux deletion explicitly confirms it.
+        if (observed.status === 'absent' && cause !== 'confirmed-empty' && change.status !== 'changed') {
+            return { status: 'unknown' };
+        }
+        const current = 'current' in change ? change.current : observed;
+        const captured = await deps.capture(snapshotEnvironment(current));
+        if (captured.status === 'changed-during-capture') {
+            deps.scheduleRetry?.();
+            return captured;
+        }
+        if (captured.status !== 'ok' && captured.status !== 'empty')
+            return captured;
+        if (captured.status === 'empty' && cause !== 'confirmed-empty' && observed.status !== 'present' && change.status !== 'changed') {
+            return { status: 'unknown' };
+        }
+        if (change.status === 'changed') {
+            const archived = await deps.store.archiveEnvironment({
+                endedReason: change.reason,
+                detectedAt: new Date(deps.now()).toISOString(),
+            });
+            if (archived.status !== 'ok' && archived.status !== 'empty')
+                return archived;
+        }
+        if (live.status === 'ok' && sameSnapshot(live.value, captured.snapshot))
+            return { status: 'unchanged' };
+        await deps.store.writeLive(captured.snapshot);
+        return { status: 'written', snapshot: captured.snapshot };
+    }
+    finally {
+        await handle.release();
+    }
+}
+export function createCheckpointer({ setInterval = globalThis.setInterval, clearInterval = globalThis.clearInterval, setTimeout = globalThis.setTimeout, clearTimeout = globalThis.clearTimeout, now = Date.now, ...rest }) {
+    const deps = {
+        ...rest, now, setInterval, clearInterval, setTimeout, clearTimeout,
+    };
+    let interval = null;
+    let debounce = null;
+    let running = null;
+    let pendingConfirmation = null;
+    let stopping = false;
+    let stopped = false;
+    let stopPromise = null;
+    let lastResult = null;
+    let lastError = null;
+    function launch(cause) {
+        const current = reconcileOnce(deps, cause);
+        running = current;
+        const settled = () => {
+            if (running !== current)
+                return;
+            running = null;
+            if (pendingConfirmation) {
+                const pending = pendingConfirmation;
+                pendingConfirmation = null;
+                launch('confirmed-empty').then(pending.resolve, pending.reject);
+            }
+        };
+        current.then((result) => {
+            lastResult = result;
+            lastError = null;
+            settled();
+        }, () => {
+            lastError = 'workspace-reconcile-failed';
+            settled();
+        });
+        return current;
+    }
+    function confirmEmpty() {
+        if (stopping || stopped)
+            return Promise.resolve({ status: 'stopped' });
+        if (!running)
+            return launch('confirmed-empty');
+        if (!pendingConfirmation) {
+            let resolve;
+            let reject;
+            const promise = new Promise((onResolve, onReject) => { resolve = onResolve; reject = onReject; });
+            pendingConfirmation = { promise, resolve, reject };
+        }
+        return pendingConfirmation.promise;
+    }
+    function reconcile(cause = 'timer') {
+        if (cause === 'confirmed-empty')
+            return confirmEmpty();
+        if (stopping || stopped)
+            return Promise.resolve({ status: 'stopped' });
+        return running || launch(cause);
+    }
+    function requestReconcile() {
+        if (stopping || stopped)
+            return;
+        clearTimeout(debounce);
+        debounce = setTimeout(() => {
+            debounce = null;
+            reconcile('event').catch(() => { });
+        }, 2_000);
+    }
+    deps.scheduleRetry = requestReconcile;
+    const outstanding = () => (running ?? pendingConfirmation?.promise ?? null);
+    return {
+        reconcile,
+        health() {
+            if (stopping || stopped)
+                return { status: 'degraded', detail: 'workspace-stopped' };
+            if (lastError)
+                return { status: 'degraded', detail: lastError };
+            if (!lastResult)
+                return { status: 'starting', detail: 'workspace-reconcile-starting' };
+            if (lastResult.status === 'written' || lastResult.status === 'unchanged') {
+                return { status: 'ready', detail: null };
+            }
+            if (lastResult.status === 'locked') {
+                return { status: 'ready', detail: 'workspace-writer-locked' };
+            }
+            return { status: 'degraded', detail: `workspace-${lastResult.status || 'unknown'}` };
+        },
+        start() {
+            if (stopping || stopped)
+                return Promise.resolve({ status: 'stopped' });
+            if (!interval)
+                interval = setInterval(() => { reconcile('timer').catch(() => { }); }, 60_000);
+            return reconcile('start');
+        },
+        requestReconcile,
+        confirmEmpty,
+        stop() {
+            if (stopPromise)
+                return stopPromise;
+            stopping = true;
+            stopPromise = (async () => {
+                if (interval)
+                    clearInterval(interval);
+                if (debounce)
+                    clearTimeout(debounce);
+                interval = null;
+                debounce = null;
+                let pending = outstanding();
+                while (pending) {
+                    await pending.catch(() => { });
+                    pending = outstanding();
+                }
+                await launch('shutdown').catch(() => { });
+                pending = outstanding();
+                while (pending) {
+                    await pending.catch(() => { });
+                    pending = outstanding();
+                }
+                stopped = true;
+            })();
+            return stopPromise;
+        },
+    };
+}
+export function createWorkspaceBackground({ store, tmux, observeEnvironment, lock, stateFile, getCodexApp = () => null, codexSessions, now = Date.now, }) {
+    return createCheckpointer({
+        store,
+        observeEnvironment,
+        lock,
+        now,
+        capture: (environment) => {
+            const codexApp = getCodexApp();
+            return captureWorkspace({
+                tmux, stateFile, environment,
+                ...(codexApp ? { codexApp } : {}),
+                ...(codexSessions ? { codexSessions } : {}),
+                now,
+            });
+        },
+    });
+}
+export function createGracefulShutdown({ events, workspace, browser, server }) {
+    let closing = null;
+    return function shutdown() {
+        if (!closing) {
+            closing = (async () => {
+                try {
+                    await events.stop();
+                }
+                finally {
+                    try {
+                        await workspace.stop();
+                    }
+                    finally {
+                        try {
+                            await browser?.close();
+                        }
+                        finally {
+                            server.close();
+                        }
+                    }
+                }
+            })();
+        }
+        return closing;
+    };
+}

package/dist/src/workspace/environment.js

@@ -0,0 +1,71 @@
+import crypto from 'node:crypto';
+import { execFile } from 'node:child_process';
+import fsp from 'node:fs/promises';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+function normalizeMacBootTime(value) {
+    const seconds = String(value).match(/\bsec\s*=\s*(\d+)\b/)?.[1];
+    return seconds && seconds !== '0' ? seconds : null;
+}
+function environmentId(bootIdentity, tmuxServerId) {
+    return crypto
+        .createHash('sha256')
+        .update(`${bootIdentity}\0${tmuxServerId || 'no-tmux'}`)
+        .digest('hex');
+}
+export function detectEnvironmentChange(previous, observed) {
+    if (!observed || observed.status === 'unknown')
+        return { status: 'unknown' };
+    if (!previous)
+        return { status: 'initial', current: observed };
+    if (previous.bootIdentity !== observed.bootIdentity)
+        return { status: 'changed', reason: 'boot-changed', current: observed };
+    if (observed.status === 'absent') {
+        return previous.tmuxServerId
+            ? { status: 'changed', reason: 'tmux-changed', current: observed }
+            : { status: 'unknown' };
+    }
+    if (!previous.tmuxServerId)
+        return { status: 'attached', reason: 'same', current: observed };
+    if (previous.tmuxServerId !== observed.tmuxServerId)
+        return { status: 'changed', reason: 'tmux-changed', current: observed };
+    return { status: 'same', reason: 'same', current: observed };
+}
+export function createBootIdentityProvider({ platform = process.platform, readFile = fsp.readFile, exec = execFileAsync, } = {}) {
+    return async () => {
+        try {
+            if (platform === 'linux') {
+                const identity = String(await readFile('/proc/sys/kernel/random/boot_id', 'utf8')).trim();
+                return identity || null;
+            }
+            if (platform === 'darwin') {
+                return normalizeMacBootTime((await exec('sysctl', ['-n', 'kern.boottime'])).stdout);
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    };
+}
+export function createEnvironmentProvider({ bootIdentityProvider = createBootIdentityProvider(), tmuxServerIdProvider, } = {}) {
+    return async () => {
+        try {
+            const bootIdentity = await bootIdentityProvider();
+            if (typeof bootIdentity !== 'string' || !bootIdentity)
+                return { status: 'unknown' };
+            const tmuxServerId = await tmuxServerIdProvider?.();
+            if (tmuxServerId !== null && (typeof tmuxServerId !== 'string' || !tmuxServerId))
+                return { status: 'unknown' };
+            return {
+                status: tmuxServerId === null ? 'absent' : 'present',
+                id: environmentId(bootIdentity, tmuxServerId),
+                bootIdentity,
+                tmuxServerId,
+            };
+        }
+        catch {
+            return { status: 'unknown' };
+        }
+    };
+}

package/dist/src/workspace/lock.js

@@ -0,0 +1,137 @@
+import crypto from 'node:crypto';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+const OWNER_FILE = 'owner.json';
+const SAFE_TOKEN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const errorCode = (error) => (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+    ? error.code : undefined);
+const asRecord = (value) => (value && typeof value === 'object' && !Array.isArray(value)
+    ? value : null);
+function defaultProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === 'EPERM';
+    }
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function ownerLabel(value) {
+    const owner = asRecord(value);
+    if (!owner)
+        return 'unknown owner';
+    const operation = typeof owner.operationId === 'string' && owner.operationId ? owner.operationId : 'unknown operation';
+    const pid = Number.isInteger(owner.pid) ? owner.pid : 'unknown';
+    return `${operation} (pid ${pid})`;
+}
+export function createWorkspaceLock({ dir, fs = fsp, pid = process.pid, now = Date.now, isProcessAlive = defaultProcessAlive, wait = delay, timeoutMs = 5_000, retryMs = 50, staleGraceMs = 5_000, randomUUID = crypto.randomUUID, }) {
+    if (typeof dir !== 'string' || !dir)
+        throw new Error('workspace lock directory is required');
+    async function readOwner() {
+        let stat = null;
+        try {
+            stat = await fs.stat(dir);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return null;
+            throw error;
+        }
+        try {
+            const value = JSON.parse(await fs.readFile(path.join(dir, OWNER_FILE), 'utf8'));
+            return { value, mtimeMs: stat.mtimeMs };
+        }
+        catch {
+            return { value: null, mtimeMs: stat.mtimeMs };
+        }
+    }
+    async function reclaimIfStale(record) {
+        if (!record)
+            return true;
+        const owner = asRecord(record.value);
+        if (!owner || typeof owner.token !== 'string' || !SAFE_TOKEN.test(owner.token))
+            return false;
+        const startedAt = typeof owner.startedAt === 'string' ? Date.parse(owner.startedAt) : Number.NaN;
+        const age = now() - (Number.isFinite(startedAt) ? startedAt : record.mtimeMs);
+        if (age < staleGraceMs)
+            return false;
+        if (typeof owner.pid === 'number' && Number.isInteger(owner.pid) && await isProcessAlive(owner.pid))
+            return false;
+        // Every contender that observed this owner uses the SAME destination. The winner leaves the renamed
+        // directory as a tombstone, so a loser cannot later rename a newly-created lock out of the way.
+        const staleDir = `${dir}.stale.${owner.token}`;
+        try {
+            await fs.rename(dir, staleDir);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return true;
+            return false;
+        }
+        return true;
+    }
+    async function tryAcquire({ operationId = 'workspace-writer' } = {}) {
+        await fs.mkdir(path.dirname(dir), { recursive: true, mode: 0o700 });
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const token = randomUUID();
+            if (!SAFE_TOKEN.test(token))
+                throw new Error('workspace lock token must be a UUID');
+            const owner = { pid, startedAt: new Date(now()).toISOString(), operationId, token };
+            try {
+                await fs.mkdir(dir, { mode: 0o700 });
+                try {
+                    await fs.writeFile(path.join(dir, OWNER_FILE), `${JSON.stringify(owner)}\n`, { mode: 0o600, flag: 'wx' });
+                }
+                catch (error) {
+                    await fs.rm(dir, { recursive: true, force: true });
+                    throw error;
+                }
+                let released = false;
+                return {
+                    owner,
+                    async release() {
+                        if (released)
+                            return;
+                        released = true;
+                        const current = await readOwner();
+                        if (asRecord(current?.value)?.token === token)
+                            await fs.rm(dir, { recursive: true, force: true });
+                    },
+                };
+            }
+            catch (error) {
+                if (errorCode(error) !== 'EEXIST')
+                    throw error;
+                const record = await readOwner();
+                if (!await reclaimIfStale(record))
+                    return null;
+            }
+        }
+        return null;
+    }
+    async function acquire(owner = {}, options = {}) {
+        const limit = options.timeoutMs ?? timeoutMs;
+        const started = now();
+        while (true) {
+            const handle = await tryAcquire(owner);
+            if (handle)
+                return handle;
+            const current = await readOwner();
+            if (now() - started >= limit) {
+                throw new Error(`workspace writer lock timed out; held by ${ownerLabel(current?.value)}`);
+            }
+            await wait(options.retryMs ?? retryMs);
+        }
+    }
+    async function withLock(owner, fn, options) {
+        const handle = await acquire(owner, options);
+        try {
+            return await fn(handle.owner);
+        }
+        finally {
+            await handle.release();
+        }
+    }
+    return { tryAcquire, acquire, withLock, readOwner: async () => (await readOwner())?.value ?? null };
+}

package/dist/src/workspace/mapping.js

@@ -0,0 +1,128 @@
+import crypto from 'node:crypto';
+const HASH = /^[0-9a-f]{64}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const KINDS = ['sessions', 'windows', 'panes'];
+const RUNTIME_ID = {
+    sessions: /^\$\d+$/,
+    windows: /^@\d+$/,
+    panes: /^%\d+$/,
+};
+function fail(message) {
+    throw new Error(`invalid recovery mapping: ${message}`);
+}
+function requireExactObject(value, fields, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        fail(`${label} must be a plain object`);
+    const keys = Object.keys(value);
+    if (keys.length !== fields.length || fields.some((field) => !keys.includes(field)))
+        fail(`${label} fields are invalid`);
+    return value;
+}
+function validateRecord(value, label, keyPattern, valuePattern) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        fail(`${label} must be a plain object`);
+    for (const [key, entry] of Object.entries(value)) {
+        if (!keyPattern.test(key) || typeof entry !== 'string' || !valuePattern.test(entry))
+            fail(`${label} entry is invalid`);
+    }
+}
+function sorted(value) {
+    if (Array.isArray(value))
+        return value.map(sorted);
+    if (!value || typeof value !== 'object')
+        return value;
+    const record = value;
+    return Object.fromEntries(Object.keys(record).sort().map((key) => [key, sorted(record[key])]));
+}
+function payload(mapping) {
+    return {
+        checkpointId: mapping.checkpointId,
+        names: mapping.names,
+        runtime: mapping.runtime,
+        logical: mapping.logical,
+    };
+}
+function mappingId(mapping) {
+    return crypto.createHash('sha256').update(JSON.stringify(sorted(payload(mapping)))).digest('hex');
+}
+function blankMapping(checkpointId) {
+    return {
+        checkpointId,
+        names: {},
+        runtime: { sessions: {}, windows: {}, panes: {} },
+        logical: { sessions: {}, windows: {}, panes: {} },
+    };
+}
+function validatePayload(mapping, checkpointId) {
+    if (typeof mapping.checkpointId !== 'string' || !mapping.checkpointId || mapping.checkpointId !== checkpointId) {
+        fail('checkpoint id mismatch');
+    }
+    if (!mapping.names || typeof mapping.names !== 'object' || Array.isArray(mapping.names)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(mapping.names)))
+        fail('names must be a plain object');
+    for (const [source, target] of Object.entries(mapping.names)) {
+        if (!source || ['__proto__', 'constructor', 'prototype'].includes(source) || typeof target !== 'string' || !target)
+            fail('name entry is invalid');
+    }
+    for (const group of ['runtime', 'logical']) {
+        requireExactObject(mapping[group], ['sessions', 'windows', 'panes'], group);
+    }
+    const runtime = mapping.runtime;
+    const logical = mapping.logical;
+    for (const kind of KINDS) {
+        validateRecord(runtime[kind], `runtime.${kind}`, RUNTIME_ID[kind], RUNTIME_ID[kind]);
+        validateRecord(logical[kind], `logical.${kind}`, UUID, RUNTIME_ID[kind]);
+    }
+}
+export function validateRecoveryMapping(mapping, checkpointId) {
+    const record = requireExactObject(mapping, ['id', 'checkpointId', 'restoredAt', 'names', 'runtime', 'logical'], 'mapping');
+    if (typeof record.id !== 'string' || !HASH.test(record.id))
+        fail('id is invalid');
+    if (typeof record.restoredAt !== 'string' || Number.isNaN(Date.parse(record.restoredAt)))
+        fail('restoredAt is invalid');
+    validatePayload(record, checkpointId);
+    if (record.id !== mappingId(record))
+        fail('hash mismatch');
+    return record;
+}
+function merge(target, source) {
+    Object.assign(target.names, source.names);
+    for (const kind of KINDS) {
+        Object.assign(target.runtime[kind], source.runtime[kind]);
+        Object.assign(target.logical[kind], source.logical[kind]);
+    }
+}
+function validateAddition(value, checkpointId) {
+    const record = requireExactObject(value, ['names', 'runtime', 'logical'], 'mapping addition');
+    const candidate = { checkpointId, ...record };
+    validatePayload(candidate, checkpointId);
+    return candidate;
+}
+function hasValues(mapping) {
+    return Object.keys(mapping.names).length > 0
+        || KINDS.some((kind) => (Object.keys(mapping.runtime[kind]).length > 0 || Object.keys(mapping.logical[kind]).length > 0));
+}
+export function buildRecoveryMapping(checkpointId, previous, additions, now = Date.now) {
+    const combined = blankMapping(checkpointId);
+    if (previous)
+        merge(combined, validateRecoveryMapping(previous, checkpointId));
+    if (!Array.isArray(additions))
+        fail('additions must be an array');
+    for (const addition of additions) {
+        if (addition !== null && addition !== undefined)
+            merge(combined, validateAddition(addition, checkpointId));
+    }
+    if (!hasValues(combined))
+        return null;
+    const mapping = {
+        id: mappingId(combined),
+        checkpointId,
+        restoredAt: new Date(now()).toISOString(),
+        names: combined.names,
+        runtime: combined.runtime,
+        logical: combined.logical,
+    };
+    return validateRecoveryMapping(mapping, checkpointId);
+}