termdock 1.4.350 → 1.4.352

package/dist/server/todos/cli.js

@@ -0,0 +1,91 @@
+import fs from 'node:fs';
+import { randomUUID } from 'node:crypto';
+export const TODO_HELP = `td todo — persistent todos on the local Termdock service
+  list
+  add --title <title> [--description <text> | --file <path> | --stdin]
+    [--source <direction>] [--external-id <stable-id>] [--url <https-url>]
+    [--collector <collector-id>] [--idempotency-key <key>]
+  report <run-id> --status complete|blocked|failed (--content <text> | --file <path> | --stdin)
+  complete|reopen|ignore <todo-id>
+  --help | --json
+External IDs deduplicate within a source. Reports attach to the exact execution run;
+only complete marks a todo completed. An Agent report never accepts a todo for the user.
+Use the running local service (same OS user); no unauthenticated HTTP fallback.`;
+export function parseTodoCommand(argv) {
+    const positional = [], options = {};
+    const values = ['title', 'description', 'file', 'source', 'external-id', 'url', 'collector', 'idempotency-key', 'status', 'content'];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--')) {
+            positional.push(arg);
+            continue;
+        }
+        const [key, ...inline] = arg.slice(2).split('=');
+        if (Object.hasOwn(options, key))
+            throw new Error(`Duplicate option --${key}`);
+        if (['help', 'json', 'stdin'].includes(key)) {
+            if (inline.length)
+                throw new Error(`--${key} takes no value`);
+            options[key] = true;
+        }
+        else if (values.includes(key)) {
+            const value = inline.length ? inline.join('=') : argv[++i];
+            if (!value || (!inline.length && value.startsWith('--')))
+                throw new Error(`--${key} requires a value`);
+            options[key] = value;
+        }
+        else
+            throw new Error(`Unknown option --${key}`);
+    }
+    const action = (options.help ? 'help' : positional.shift() ?? 'help');
+    if (!['help', 'list', 'add', 'report', 'complete', 'reopen', 'ignore'].includes(action))
+        throw new Error('See td todo --help');
+    if (action === 'help')
+        return { action, options };
+    const allowed = { list: [], add: ['title', 'description', 'file', 'stdin', 'source', 'external-id', 'url', 'collector', 'idempotency-key'], report: ['status', 'content', 'file', 'stdin'], complete: [], reopen: [], ignore: [] };
+    for (const flag of Object.keys(options))
+        if (flag !== 'json' && !allowed[action].includes(flag))
+            throw new Error(`--${flag} is not supported by ${action}`);
+    const id = !['list', 'add'].includes(action) ? positional.shift() : undefined;
+    if ((!['list', 'add'].includes(action) && !id) || positional.length)
+        throw new Error('Invalid arguments; see td todo --help');
+    if (action === 'add' && !options.title)
+        throw new Error('--title is required');
+    if (['description', 'content', 'file', 'stdin'].filter(k => options[k]).length > 1)
+        throw new Error('Choose one content input');
+    if (action === 'report' && (!['complete', 'blocked', 'failed'].includes(String(options.status)) || !['content', 'file', 'stdin'].some(k => options[k])))
+        throw new Error('report requires --status and content');
+    return { action, id, options };
+}
+export async function executeTodoCommand(command, io) {
+    try {
+        if (command.action === 'help') {
+            io.write(TODO_HELP);
+            return 0;
+        }
+        const base = '/api/terminal/operations/todos', o = command.options;
+        const request = async (method, suffix = '', body) => { const response = await io.request(method, base + suffix, body); const data = JSON.parse(response.body); if (response.statusCode < 200 || response.statusCode >= 300)
+            throw new Error(data.error || 'Todo request failed'); return data; };
+        const content = o.file ? fs.readFileSync(String(o.file), 'utf8') : o.stdin ? await io.stdin() : String(o.content ?? o.description ?? '');
+        let result;
+        if (command.action === 'list')
+            result = await request('GET');
+        else if (command.action === 'add')
+            result = await request('POST', '', { title: o.title, description: content, source: o.source || '外部注入', sourceUrl: o.url, externalId: o['external-id'], collectorId: o.collector, idempotencyKey: o['idempotency-key'] || randomUUID() });
+        else if (command.action === 'report')
+            result = await request('POST', `/runs/${encodeURIComponent(command.id)}/report`, { status: o.status, content });
+        else {
+            const snapshot = await request('GET');
+            const todo = snapshot.todos.find((t) => t.id === command.id);
+            if (!todo)
+                throw new Error('Todo not found');
+            result = await request('POST', `/${encodeURIComponent(command.id)}`, { revision: todo.revision, status: command.action === 'complete' ? 'completed' : command.action === 'ignore' ? 'ignored' : 'open' });
+        }
+        io.write(JSON.stringify(result));
+        return 0;
+    }
+    catch (error) {
+        io.write(JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) }));
+        return 1;
+    }
+}

package/dist/server/todos/routes.js

@@ -0,0 +1,73 @@
+import { Router } from 'express';
+import { launchConfig, TodoError } from './store.js';
+function shellQuote(value) { return "'" + value.replace(/'/g, "'\"'\"'") + "'"; }
+export function todoPrompt(store, run) {
+    const report = `完成或受阻时，请将结果写入一个 UTF-8 文件，并调用 td todo report ${run.id} --status complete --file <文件路径>；受阻时将 complete 换为 blocked，失败时换为 failed。报告只记录本次结果，由用户决定待办是否完成。`;
+    if (run.kind === 'collect')
+        return `${run.config.prompt}\n\n请将收集到的每条可执行待办通过本机 CLI 写入 Termdock，避免只输出列表。使用：\ntd todo add --title <标题> --description <描述> --source ${shellQuote(run.name)} --collector ${run.collectorId} --external-id <在此方向中稳定且唯一的标识>\n请附带必要上下文和可选的 --url https://... 。先用 td todo list 查看已有待办，避免重复。只收集待办，本轮不执行这些待办。\n${report}`;
+    const todo = store.get(run.todoId);
+    return `${run.config.prompt || '请处理下面这条待办，完成后说明结果和验证情况。'}\n\n待办：${todo.title}\n${todo.description}\n来源：${todo.source}\n${todo.sourceUrl ? `来源链接：${todo.sourceUrl}\n` : ''}\n待办 ID：${todo.id}\n执行记录 ID：${run.id}\n${report}`;
+}
+export class TodoRunner {
+    store;
+    runtime;
+    constructor(store, runtime) {
+        this.store = store;
+        this.runtime = runtime;
+    }
+    async start(kind, id, input, key, req) {
+        // Read-only validation happens before reserving a run; launch is always recorded before any side effect.
+        const base = kind === 'collect' ? this.store.collector(id).config : this.store.snapshot().defaults;
+        const config = await this.runtime.validate(launchConfig(input ?? {}, base), req);
+        const { run, fresh } = this.store.begin(kind, id, config, key);
+        if (fresh)
+            void this.runtime.launch(run, todoPrompt(this.store, run), sessionId => this.store.mark(run.id, { sessionId }), req)
+                .then(() => this.store.mark(run.id, { status: 'delivered' }))
+                .catch(error => { this.store.mark(run.id, { status: 'failed', error: error instanceof Error ? error.message : String(error) }); });
+        return run;
+    }
+    async tick() {
+        for (const collector of this.store.due()) {
+            try {
+                await this.start('collect', collector.id, undefined, `schedule:${collector.id}:${collector.nextRunAt}`);
+            }
+            catch (error) {
+                // Scheduled configuration failures also need a visible record and a new due time.
+                try {
+                    const { run, fresh } = this.store.begin('collect', collector.id, collector.config, `schedule:${collector.id}:${collector.nextRunAt}`);
+                    if (fresh)
+                        this.store.mark(run.id, { status: 'failed', error: error instanceof Error ? error.message : String(error) });
+                }
+                catch (recordError) {
+                    console.warn('[todo-collector]', collector.name, recordError instanceof Error ? recordError.message : recordError);
+                }
+            }
+        }
+    }
+}
+export function todoRoutes(store, runner, runtime) {
+    const router = Router();
+    const route = (fn) => async (req, res) => {
+        try {
+            await fn(req, res);
+        }
+        catch (error) {
+            res.status(error instanceof TodoError ? error.status : 400).json({ error: error instanceof Error ? error.message : String(error) });
+        }
+    };
+    router.get('/summary', route((_req, res) => res.json({ count: store.openCount() })));
+    router.get('/', route((_req, res) => res.json(store.snapshot())));
+    router.post('/', route((req, res) => res.json({ todo: store.create(req.body ?? {}) })));
+    router.post('/defaults', route(async (req, res) => res.json({ defaults: store.defaults(await runtime.validate(launchConfig(req.body ?? {}), req)) })));
+    router.post('/collectors', route(async (req, res) => {
+        const input = req.body ?? {};
+        const config = await runtime.validate(launchConfig(input.config ?? {}), req);
+        res.json({ collector: store.saveCollector({ ...input, config }) });
+    }));
+    router.post('/collectors/:id/remove', route((req, res) => { store.removeCollector(req.params.id, req.body?.revision); res.json({ ok: true }); }));
+    router.post('/collectors/:id/run', route(async (req, res) => res.json({ run: await runner.start('collect', req.params.id, undefined, req.body?.idempotencyKey, req) })));
+    router.post('/runs/:id/report', route((req, res) => res.json({ run: store.report(req.params.id, req.body?.status, req.body?.content) })));
+    router.post('/:id', route((req, res) => res.json({ todo: store.update(req.params.id, req.body ?? {}) })));
+    router.post('/:id/run', route(async (req, res) => res.json({ run: await runner.start('execute', req.params.id, req.body?.config, req.body?.idempotencyKey, req) })));
+    return router;
+}

package/dist/server/todos/store.js

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID, createHash } from 'node:crypto';
+import { nextAutomationRunAt, normalizeAutomationSchedule } from '../agent/automationStore.js';
+export class TodoError extends Error {
+    status;
+    constructor(message, status = 400) {
+        super(message);
+        this.status = status;
+    }
+}
+function string(value, max, fallback = '') {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'string' || value.length > max || value.includes('\0'))
+        throw new TodoError('内容格式或长度无效');
+    return value.trim();
+}
+function title(value) { const s = string(value, 200); if (!s)
+    throw new TodoError('请填写标题'); return s; }
+export function launchConfig(input, base) {
+    return { agentSlug: string(input.agentSlug, 100, base?.agentSlug), command: string(input.command, 4000, base?.command),
+        cwd: string(input.cwd, 4096, base?.cwd), prompt: string(input.prompt, 20000, base?.prompt) };
+}
+const blank = () => ({ version: 1, todos: [], collectors: [], runs: [], requests: {}, defaults: { agentSlug: '', command: '', cwd: '', prompt: '' } });
+export class TodoStore {
+    file;
+    doc = blank();
+    constructor(file) {
+        this.file = file;
+        try {
+            const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (doc.version !== 1 || !Array.isArray(doc.todos) || !Array.isArray(doc.collectors) || !Array.isArray(doc.runs) || !doc.requests || !doc.defaults)
+                throw new Error('无效的 Todo 数据文件');
+            this.doc = doc;
+            // Never replay a launch after a crash: it might already have reached a terminal.
+            if (doc.runs.some(r => r.status === 'launching'))
+                this.transaction(next => {
+                    for (const run of next.runs)
+                        if (run.status === 'launching') {
+                            run.status = 'failed';
+                            run.error = '服务重启中断了启动确认，请检查已有终端后重新发起';
+                            run.updatedAt = Date.now();
+                        }
+                });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    transaction(change) {
+        const next = structuredClone(this.doc), result = change(next);
+        const bytes = JSON.stringify(next);
+        if (Buffer.byteLength(bytes) > 32 * 1024 * 1024)
+            throw new TodoError('待办记录已达容量上限，请整理后重试', 409);
+        fs.mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        const fd = fs.openSync(temporary, 'w', 0o600);
+        try {
+            fs.writeFileSync(fd, bytes);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(temporary, this.file);
+        const directory = fs.openSync(path.dirname(this.file), 'r');
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+        this.doc = next;
+        return structuredClone(result);
+    }
+    openCount() { return this.doc.todos.filter(t => t.status === 'open').length; }
+    snapshot() { const { requests: _, version: _v, ...snapshot } = this.doc; return structuredClone(snapshot); }
+    get(id) { const todo = this.doc.todos.find(t => t.id === id); if (!todo)
+        throw new TodoError('待办不存在', 404); return structuredClone(todo); }
+    collector(id) { const collector = this.doc.collectors.find(c => c.id === id); if (!collector)
+        throw new TodoError('收集方向不存在', 404); return structuredClone(collector); }
+    run(id) { const run = this.doc.runs.find(r => r.id === id); if (!run)
+        throw new TodoError('执行记录不存在', 404); return structuredClone(run); }
+    check(revision, current) { if (revision !== current)
+        throw new TodoError('记录已更新，请刷新后重试', 409); }
+    create(input) {
+        const sourceUrl = string(input.sourceUrl, 4096);
+        if (sourceUrl) {
+            try {
+                if (!['http:', 'https:'].includes(new URL(sourceUrl).protocol))
+                    throw new Error();
+            }
+            catch {
+                throw new TodoError('来源链接须为有效的 http 或 https 地址');
+            }
+        }
+        const collectorId = string(input.collectorId, 100) || null;
+        const collectorName = collectorId ? this.doc.collectors.find(c => c.id === collectorId)?.name ?? this.doc.runs.find(r => r.collectorId === collectorId)?.name : null;
+        if (collectorId && !collectorName)
+            throw new TodoError('收集方向不存在', 404);
+        const values = { title: title(input.title), description: string(input.description, 40000), source: string(input.source, 200, collectorName ?? '手动添加') || '外部注入',
+            sourceUrl, externalId: string(input.externalId, 500), collectorId };
+        const key = string(input.idempotencyKey, 200);
+        const hash = this.hash(values);
+        const previous = key && this.doc.requests[`create:${key}`];
+        if (previous) {
+            if (previous.hash !== hash)
+                throw new TodoError('同一请求标识的内容不一致', 409);
+            return this.get(previous.id);
+        }
+        const existing = values.externalId && this.doc.todos.find(t => t.source === values.source && t.externalId === values.externalId);
+        if (existing)
+            return structuredClone(existing);
+        return this.transaction(doc => {
+            const now = Date.now();
+            const todo = { ...values, id: randomUUID(), status: 'open', createdAt: now, updatedAt: now, revision: 1 };
+            doc.todos.unshift(todo);
+            if (key)
+                doc.requests[`create:${key}`] = { hash, id: todo.id };
+            return todo;
+        });
+    }
+    update(id, input) {
+        return this.transaction(doc => {
+            const todo = doc.todos.find(t => t.id === id);
+            if (!todo)
+                throw new TodoError('待办不存在', 404);
+            this.check(input.revision, todo.revision);
+            if (input.title !== undefined)
+                todo.title = title(input.title);
+            if (input.description !== undefined)
+                todo.description = string(input.description, 40000);
+            if (input.status !== undefined) {
+                if (!['open', 'completed', 'ignored'].includes(input.status))
+                    throw new TodoError('待办状态无效');
+                todo.status = input.status;
+            }
+            todo.revision++;
+            todo.updatedAt = Date.now();
+            return todo;
+        });
+    }
+    defaults(input) { const config = launchConfig(input, this.doc.defaults); return this.transaction(doc => doc.defaults = config); }
+    saveCollector(input) {
+        const name = title(input.name), config = launchConfig(input.config);
+        if (!config.agentSlug || !config.command || !config.prompt)
+            throw new TodoError('请选择 Agent 并填写收集提示词');
+        const schedule = input.schedule == null ? null : normalizeAutomationSchedule(input.schedule);
+        if (input.schedule != null && !schedule)
+            throw new TodoError('运行频率无效');
+        return this.transaction(doc => {
+            const previous = input.id ? doc.collectors.find(c => c.id === input.id) : null;
+            if (input.id && !previous)
+                throw new TodoError('收集方向不存在', 404);
+            if (previous)
+                this.check(input.revision, previous.revision);
+            const now = Date.now(), enabled = input.enabled !== false;
+            const collector = { id: previous?.id ?? randomUUID(), name, config, enabled, schedule,
+                nextRunAt: schedule && enabled ? (previous?.enabled && JSON.stringify(previous.schedule) === JSON.stringify(schedule) ? previous.nextRunAt : nextAutomationRunAt(schedule, now, now)) : null,
+                createdAt: previous?.createdAt ?? now, updatedAt: now, revision: (previous?.revision ?? 0) + 1 };
+            if (previous)
+                Object.assign(previous, collector);
+            else
+                doc.collectors.push(collector);
+            return collector;
+        });
+    }
+    removeCollector(id, revision) { this.transaction(doc => { const c = doc.collectors.find(c => c.id === id); if (!c)
+        throw new TodoError('收集方向不存在', 404); this.check(revision, c.revision); doc.collectors = doc.collectors.filter(c => c.id !== id); }); }
+    due(now = Date.now()) { return this.doc.collectors.filter(c => c.enabled && c.nextRunAt !== null && c.nextRunAt <= now).map(c => structuredClone(c)); }
+    begin(kind, id, config, key) {
+        if (!key || key.length > 200)
+            throw new TodoError('缺少有效的请求标识');
+        const hash = this.hash({ kind, id, config });
+        const previous = this.doc.requests[`run:${key}`];
+        if (previous) {
+            if (previous.hash !== hash)
+                throw new TodoError('同一请求标识的内容不一致', 409);
+            return { run: this.run(previous.id), fresh: false };
+        }
+        const item = kind === 'execute' ? this.get(id) : this.collector(id);
+        if (kind === 'execute' && item.status !== 'open')
+            throw new TodoError('请先重新打开这条待办', 409);
+        if (this.doc.runs.some(r => r.status === 'launching' && (kind === 'execute' ? r.todoId === id : r.collectorId === id)))
+            throw new TodoError('此项正在启动，请稍候', 409);
+        return this.transaction(doc => {
+            const now = Date.now();
+            const run = { id: randomUUID(), kind, todoId: kind === 'execute' ? id : null, collectorId: kind === 'collect' ? id : null,
+                name: kind === 'execute' ? item.title : item.name, config, status: 'launching', createdAt: now, updatedAt: now, sessionId: null, result: '', error: '' };
+            doc.runs.push(run);
+            doc.requests[`run:${key}`] = { hash, id: run.id };
+            if (kind === 'collect') {
+                const c = doc.collectors.find(c => c.id === id);
+                c.nextRunAt = c.schedule && c.enabled ? nextAutomationRunAt(c.schedule, now + 1, c.createdAt) : null;
+                c.updatedAt = now;
+                c.revision++;
+            }
+            return { run, fresh: true };
+        });
+    }
+    mark(id, update) {
+        return this.transaction(doc => {
+            const run = doc.runs.find(r => r.id === id);
+            if (!run)
+                throw new TodoError('执行记录不存在', 404);
+            if (update.sessionId)
+                run.sessionId = update.sessionId;
+            // An Agent can submit its report before launch delivery acknowledgement returns.
+            if (run.status === 'launching') {
+                if (update.status)
+                    run.status = update.status;
+                if (update.error)
+                    run.error = update.error;
+            }
+            run.updatedAt = Date.now();
+            return run;
+        });
+    }
+    report(id, status, content) {
+        if (!['complete', 'blocked', 'failed'].includes(status))
+            throw new TodoError('结果状态无效');
+        const result = string(content, 40000);
+        if (!result)
+            throw new TodoError('请填写结果');
+        return this.transaction(doc => {
+            const run = doc.runs.find(r => r.id === id);
+            if (!run)
+                throw new TodoError('执行记录不存在', 404);
+            if (run.result && (run.status !== status || run.result !== result))
+                throw new TodoError('此轮已有结果，请发起新一轮执行', 409);
+            run.status = status;
+            run.result = result;
+            run.updatedAt = Date.now();
+            return run;
+        });
+    }
+    hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+}

package/dist/server/todos/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/utils/autoUpdate.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { compareVersions, verifyRunningTermdockInstallation, updateTermdockFromOfficialRegistry, } from './npmUpdate.js';
 export const AUTO_UPDATE_INITIAL_DELAY_MS = 15_000;
 export const AUTO_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1_000;
+export class TermdockUpdateStateChangedError extends Error {
+}
 function initialState(currentVersion) {
     return {
         status: 'idle',
@@ -86,9 +88,12 @@ export class TermdockAutoUpdateManager {
         });
         return this.checkPromise;
     }
-    confirmRestart() {
+    confirmRestart(expectedVersion) {
         if (this.state.status !== 'ready' || !hasPendingTermdockUpdate(this.state)) {
-            throw new Error('No installed Termdock update is waiting for restart.');
+            throw new TermdockUpdateStateChangedError('No installed Termdock update is waiting for restart.');
+        }
+        if (expectedVersion !== undefined && expectedVersion !== this.state.latestVersion) {
+            throw new TermdockUpdateStateChangedError('The pending Termdock update has changed. Please confirm the new version.');
         }
         try {
             this.verifyInstalled(this.state.latestVersion);

package/dist/server/utils/clientSnapshotMaintenance.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs/promises';
+import syncFs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+const DAY = 24 * 60 * 60_000;
+const KEY = /^[a-f0-9]{24}$/;
+async function realDirectory(directory) {
+    try {
+        return (await fs.lstat(directory)).isDirectory() && await fs.realpath(directory) === path.resolve(directory);
+    }
+    catch {
+        return false;
+    }
+}
+async function snapshot(directory) {
+    const key = path.basename(directory);
+    if (!KEY.test(key) || !await realDirectory(directory))
+        return null;
+    try {
+        const names = await fs.readdir(directory);
+        if (names.length !== 2 || !names.includes('dist') || !names.includes('snapshot-manifest.json'))
+            return null;
+        const manifestPath = path.join(directory, 'snapshot-manifest.json');
+        if (!(await fs.lstat(manifestPath)).isFile())
+            return null;
+        const manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+        if (Object.keys(manifest).sort().join() !== ['schemaVersion', 'serverBundleHash', 'clientBundleHash', 'clientEntrypoint'].sort().join()
+            || manifest.schemaVersion !== 1 || manifest.clientEntrypoint !== 'dist/client/index.html'
+            || typeof manifest.serverBundleHash !== 'string' || typeof manifest.clientBundleHash !== 'string'
+            || !/^sha256-[A-Za-z0-9+/]{43}=$/.test(manifest.clientBundleHash)
+            || crypto.createHash('sha256').update(`${manifest.serverBundleHash}\0${manifest.clientBundleHash}`).digest('hex').slice(0, 24) !== key)
+            return null;
+        const dist = path.join(directory, 'dist'), client = path.join(dist, 'client');
+        if (!await realDirectory(dist) || !await realDirectory(client) || (await fs.readdir(dist)).join() !== 'client')
+            return null;
+        if (!(await fs.lstat(path.join(client, 'index.html'))).isFile())
+            return null;
+        return { key, directory, client, hash: manifest.clientBundleHash, touchedAt: (await fs.stat(directory)).mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/** Same byte/path hash as generate-runtime-manifest.mjs; links are never eligible. */
+export async function hashGeneratedClient(directory) {
+    const digest = crypto.createHash('sha256');
+    const observed = [];
+    let bytes = 0, visited = 0;
+    const identity = (stat) => `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeMs}:${stat.ctimeMs}`;
+    const visit = async (current, relative = '') => {
+        const stat = await fs.lstat(current);
+        observed.push({ file: current, identity: identity(stat) });
+        if (!stat.isDirectory())
+            throw new Error('Snapshot contains a link or special entry');
+        for (const entry of (await fs.readdir(current, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (++visited > 10_000)
+                throw new Error('Snapshot entry limit reached');
+            const file = path.join(current, entry.name), name = path.join(relative, entry.name);
+            if (entry.isDirectory())
+                await visit(file, name);
+            else if (entry.isFile()) {
+                const before = await fs.lstat(file);
+                observed.push({ file, identity: identity(before) });
+                bytes += before.size;
+                digest.update(name.split(path.sep).join('/'));
+                digest.update('\0');
+                for await (const chunk of syncFs.createReadStream(file))
+                    digest.update(chunk);
+                digest.update('\0');
+            }
+            else
+                throw new Error('Snapshot contains a link or special entry');
+        }
+    };
+    await visit(directory);
+    return { hash: `sha256-${digest.digest('base64')}`, bytes, unchanged: async () => {
+            for (const item of observed) {
+                try {
+                    if (identity(await fs.lstat(item.file)) !== item.identity)
+                        return false;
+                }
+                catch {
+                    return false;
+                }
+            }
+            return true;
+        } };
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function leasedKeys(stateDirectory, reapDead) {
+    const result = new Set(), directory = path.join(stateDirectory, 'client-snapshot-leases');
+    try {
+        try {
+            await fs.lstat(directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return result;
+            throw error;
+        }
+        if (!await realDirectory(directory))
+            throw new Error('Snapshot lease directory is not verified');
+        for (const entry of await fs.readdir(directory, { withFileTypes: true })) {
+            if (!entry.isFile() || !/^\d+-[a-f0-9]{16}\.json$/.test(entry.name))
+                continue;
+            const file = path.join(directory, entry.name);
+            try {
+                const lease = JSON.parse(await fs.readFile(file, 'utf8'));
+                if (lease.kind !== 'termdock-client-snapshot-lease' || lease.version !== 1 || !KEY.test(lease.snapshotKey)
+                    || !Number.isSafeInteger(lease.pid) || lease.pid < 1 || !entry.name.startsWith(`${lease.pid}-`))
+                    throw new Error('Unverified lease');
+                if (alive(lease.pid))
+                    result.add(lease.snapshotKey);
+                else if (reapDead && Object.keys(lease).length === 4)
+                    await fs.unlink(file);
+            }
+            catch {
+                throw new Error('Client snapshot leases could not be verified');
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return result;
+}
+/** Protect every live server's pinned client, including other local ports. */
+export function leaseClientSnapshot(clientDirectory, stateDirectory) {
+    const root = path.join(stateDirectory, 'client-snapshots'), directory = path.resolve(clientDirectory, '..', '..');
+    if (path.dirname(directory) !== path.resolve(root) || !KEY.test(path.basename(directory)))
+        return () => { };
+    const leases = path.join(stateDirectory, 'client-snapshot-leases');
+    try {
+        syncFs.mkdirSync(leases, { recursive: true, mode: 0o700 });
+        if (syncFs.realpathSync(leases) !== path.resolve(leases))
+            return () => { };
+        const file = path.join(leases, `${process.pid}-${crypto.randomBytes(8).toString('hex')}.json`);
+        syncFs.writeFileSync(file, JSON.stringify({ kind: 'termdock-client-snapshot-lease', version: 1, pid: process.pid, snapshotKey: path.basename(directory) }), { mode: 0o600, flag: 'wx' });
+        const remove = () => { try {
+            syncFs.unlinkSync(file);
+        }
+        catch { /* already removed */ } };
+        process.once('exit', remove);
+        return () => { process.off('exit', remove); remove(); };
+    }
+    catch {
+        return () => { };
+    }
+}
+export async function pruneClientSnapshots(options) {
+    const root = path.join(options.stateDirectory, 'client-snapshots');
+    if (!await realDirectory(root))
+        return [];
+    const snapshots = [], result = [];
+    for (const entry of await fs.readdir(root, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !KEY.test(entry.name))
+            continue;
+        const directory = path.join(root, entry.name), candidate = await snapshot(directory);
+        if (candidate)
+            snapshots.push(candidate);
+        else
+            result.push({ path: directory, action: 'retained', reason: 'unrecognized-or-modified-snapshot', bytes: 0 });
+    }
+    snapshots.sort((a, b) => b.touchedAt - a.touchedAt);
+    const current = path.resolve(options.clientDirectory, '..', '..');
+    const newest = new Set(snapshots.slice(0, options.keepNewest ?? 3).map(item => item.key));
+    for (const item of snapshots) {
+        if (item.directory === current || newest.has(item.key) || (options.now ?? Date.now()) - item.touchedAt < (options.graceMs ?? 7 * DAY))
+            continue;
+        try {
+            // Validate the full original build before deleting any legacy directory.
+            const original = await hashGeneratedClient(item.client);
+            const fresh = await snapshot(item.directory);
+            const protectedKeys = await leasedKeys(options.stateDirectory, !options.dryRun);
+            if (!fresh || fresh.touchedAt !== item.touchedAt || fresh.hash !== item.hash || original.hash !== item.hash
+                || !await original.unchanged() || protectedKeys.has(item.key)) {
+                result.push({ path: item.directory, action: 'retained', reason: 'modified-in-use-or-unverified-snapshot', bytes: 0 });
+                continue;
+            }
+            if ((await fs.stat(item.directory)).mtimeMs !== item.touchedAt)
+                continue;
+            if (!options.dryRun)
+                await fs.rm(item.directory, { recursive: true });
+            result.push({ path: item.directory, action: options.dryRun ? 'would-remove' : 'removed', reason: 'verified-expired-generated-client', bytes: original.bytes });
+        }
+        catch {
+            result.push({ path: item.directory, action: 'retained', reason: 'snapshot-validation-failed', bytes: 0 });
+        }
+    }
+    return result;
+}