termdock 1.4.322 → 1.4.325

package/dist/server/utils/tmuxRecoveryOperations.js

@@ -0,0 +1,348 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export function summarizeRecoveryOperation(operation) {
+    const counts = operation.items.reduce((total, item) => {
+        total.total += 1;
+        total[item.state] += 1;
+        return total;
+    }, { total: 0, queued: 0, resource_wait: 0, running: 0, succeeded: 0, failed: 0 });
+    return { ...structuredClone(operation), ...counts };
+}
+export class TmuxRecoveryOperationError extends Error {
+    code;
+    operationId;
+    constructor(code, message, operationId) {
+        super(message);
+        this.code = code;
+        this.operationId = operationId;
+        this.name = 'TmuxRecoveryOperationError';
+    }
+}
+function requestHash(input) {
+    return JSON.stringify(input);
+}
+function terminalState(state) {
+    return state === 'succeeded' || state === 'partial_failure';
+}
+/** Durable, bounded-concurrency queue for explicit tmux recovery operations. */
+export class TmuxRecoveryOperationStore {
+    filePath;
+    concurrencyLimit;
+    onError;
+    state = { version: 1, operations: [] };
+    writeChain = Promise.resolve();
+    active = 0;
+    pumping = false;
+    pumpRequested = false;
+    runner;
+    admission;
+    listeners = new Set();
+    loaded = false;
+    constructor(filePath, concurrencyLimit, onError = () => { }) {
+        this.filePath = filePath;
+        this.concurrencyLimit = concurrencyLimit;
+        this.onError = onError;
+        if (!Number.isInteger(concurrencyLimit) || concurrencyLimit < 1 || concurrencyLimit > 16) {
+            throw new Error('tmux recovery concurrency must be between 1 and 16');
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    setRunner(runner) {
+        this.runner = runner;
+    }
+    setAdmission(admission) {
+        this.admission = admission;
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const parsed = JSON.parse(await fs.readFile(this.filePath, 'utf8'));
+            if (parsed.version !== 1 || !Array.isArray(parsed.operations))
+                throw new Error('Invalid tmux recovery operation state');
+            this.state = parsed;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const now = Date.now();
+        let recovered = false;
+        for (const operation of this.state.operations) {
+            for (const item of operation.items) {
+                if (item.state === 'running') {
+                    // A killed worker may have submitted the native resume before it died.
+                    // The runner always performs an exact-owner reconciliation before it launches.
+                    item.state = 'queued';
+                    item.phase = 'restart_reconciliation';
+                    item.errorCode = 'RECOVERY_WORKER_RESTARTED';
+                    item.error = 'Service restarted during recovery; exact runtime ownership will be reconciled before retry.';
+                    recovered = true;
+                }
+            }
+            if (!terminalState(operation.state) && !operation.paused)
+                operation.state = 'queued';
+            operation.updatedAt = recovered ? now : operation.updatedAt;
+        }
+        if (recovered)
+            await this.persist();
+    }
+    async create(input) {
+        if (!this.loaded)
+            await this.load();
+        if (!input.idempotencyKey || input.idempotencyKey.length > 200) {
+            throw new TmuxRecoveryOperationError('INVALID_IDEMPOTENCY_KEY', 'A non-empty idempotency key of at most 200 characters is required.');
+        }
+        const sessionIds = [...new Set(input.sessionIds)].sort();
+        if (sessionIds.length === 0)
+            throw new TmuxRecoveryOperationError('RECOVERY_SCOPE_EMPTY', 'The selected recovery scope contains no recoverable sessions.');
+        const concurrency = input.concurrency ?? this.concurrencyLimit;
+        if (!Number.isInteger(concurrency) || concurrency < 1 || concurrency > this.concurrencyLimit) {
+            throw new TmuxRecoveryOperationError('INVALID_RECOVERY_CONCURRENCY', `Concurrency must be between 1 and ${this.concurrencyLimit}.`);
+        }
+        const scope = input.scope.kind === 'sessions'
+            ? { ...input.scope, sessionIds: [...new Set(input.scope.sessionIds ?? [])].sort() }
+            : structuredClone(input.scope);
+        const fingerprint = requestHash({ incidentId: input.incidentId, sessionIds, scope, concurrency });
+        const existingKey = this.state.operations.find(operation => operation.idempotencyKey === input.idempotencyKey);
+        if (existingKey) {
+            if (existingKey.requestHash !== fingerprint)
+                throw new TmuxRecoveryOperationError('IDEMPOTENCY_CONFLICT', 'The idempotency key was already used for a different recovery request.');
+            return structuredClone(existingKey);
+        }
+        if (this.state.operations.length >= 2000)
+            throw new TmuxRecoveryOperationError('RECOVERY_OPERATION_LIMIT', 'Recovery operation history is full; archive diagnostics before creating another operation.');
+        const inProgress = this.state.operations.find(operation => !terminalState(operation.state)
+            && operation.items.some(item => sessionIds.includes(item.sessionId) && (item.state === 'queued' || item.state === 'resource_wait' || item.state === 'running')));
+        if (inProgress)
+            throw new TmuxRecoveryOperationError('RECOVERY_SESSION_IN_PROGRESS', 'At least one selected session is already in a recovery operation.', inProgress.id);
+        const now = Date.now();
+        const operation = {
+            id: randomUUID(), incidentId: input.incidentId, idempotencyKey: input.idempotencyKey,
+            requestHash: fingerprint, scope, state: 'queued', paused: false,
+            concurrency, createdAt: now, updatedAt: now,
+            items: sessionIds.map(sessionId => ({ sessionId, state: 'queued', attempt: 0, phase: 'queued', startedAt: null, completedAt: null, estimatedRssBytes: 512 * 1024 ** 2 })),
+        };
+        this.state.operations.push(operation);
+        try {
+            await this.persist();
+        }
+        catch (error) {
+            this.state.operations = this.state.operations.filter(candidate => candidate.id !== operation.id);
+            throw error;
+        }
+        this.emit();
+        void this.pump();
+        return structuredClone(operation);
+    }
+    get(id) {
+        const operation = this.state.operations.find(candidate => candidate.id === id);
+        return operation ? summarizeRecoveryOperation(operation) : null;
+    }
+    latest() {
+        const operation = this.state.operations.at(-1);
+        return operation ? summarizeRecoveryOperation(operation) : null;
+    }
+    all() {
+        return this.state.operations.map(summarizeRecoveryOperation);
+    }
+    async pause(id) {
+        const operation = this.state.operations.find(candidate => candidate.id === id);
+        if (!operation)
+            return null;
+        if (!terminalState(operation.state)) {
+            operation.paused = true;
+            operation.state = 'paused';
+            operation.updatedAt = Date.now();
+            await this.persist();
+            this.emit();
+        }
+        return this.get(id);
+    }
+    async resume(id) {
+        const operation = this.state.operations.find(candidate => candidate.id === id);
+        if (!operation)
+            return null;
+        if (!terminalState(operation.state)) {
+            operation.paused = false;
+            operation.state = 'queued';
+            operation.updatedAt = Date.now();
+            await this.persist();
+            this.emit();
+            void this.pump();
+        }
+        return this.get(id);
+    }
+    stats() {
+        const operations = this.state.operations;
+        const items = operations.flatMap(operation => operation.items);
+        const lastCompleted = [...items].filter(item => item.completedAt !== null).sort((a, b) => (b.completedAt ?? 0) - (a.completedAt ?? 0))[0];
+        return {
+            queued: items.filter(item => item.state === 'queued').length,
+            resource_wait: items.filter(item => item.state === 'resource_wait').length,
+            running: items.filter(item => item.state === 'running').length,
+            activeLaunches: this.active,
+            lastCompletedAt: lastCompleted?.completedAt ?? null,
+            lastCompletedSessionId: lastCompleted?.sessionId ?? null,
+        };
+    }
+    async resumePending() {
+        if (!this.loaded)
+            await this.load();
+        void this.pump();
+    }
+    notifyResourcesChanged() {
+        if (this.pumping) {
+            this.pumpRequested = true;
+            return;
+        }
+        void this.pump();
+    }
+    async flush() { await this.writeChain; }
+    async pump() {
+        if (this.pumping || !this.runner || !this.loaded)
+            return;
+        this.pumping = true;
+        try {
+            const deferred = new Set();
+            while (this.active < this.concurrencyLimit) {
+                const candidate = this.state.operations.find(operation => !operation.paused && !terminalState(operation.state)
+                    && operation.items.filter(item => item.state === 'running').length < operation.concurrency
+                    && operation.items.some(item => (item.state === 'queued' || item.state === 'resource_wait') && !deferred.has(`${operation.id}:${item.sessionId}`)));
+                const item = candidate?.items.find(entry => (entry.state === 'queued' || entry.state === 'resource_wait') && !deferred.has(`${candidate.id}:${entry.sessionId}`));
+                if (!candidate || !item)
+                    break;
+                if (this.admission) {
+                    let admission;
+                    try {
+                        admission = await this.admission(candidate.id, item.sessionId);
+                    }
+                    catch (error) {
+                        admission = { admitted: false, reason: error instanceof Error ? error.message : 'RESOURCE_SNAPSHOT_UNAVAILABLE' };
+                    }
+                    item.memAvailableBytes = admission.memAvailableBytes;
+                    item.estimatedRssBytes = admission.estimatedRssBytes ?? item.estimatedRssBytes;
+                    if (!admission.admitted) {
+                        item.state = 'resource_wait';
+                        item.phase = 'resource_wait';
+                        item.resourceWaitReason = admission.reason ?? 'Resource budget is not currently available.';
+                        candidate.state = 'resource_wait';
+                        candidate.updatedAt = Date.now();
+                        deferred.add(`${candidate.id}:${item.sessionId}`);
+                        await this.persist();
+                        this.emit();
+                        continue;
+                    }
+                    item.resourceWaitReason = undefined;
+                }
+                if (candidate.paused)
+                    break;
+                candidate.state = 'running';
+                item.state = 'running';
+                item.phase = item.phase === 'restart_reconciliation' ? item.phase : 'restoring';
+                item.attempt += 1;
+                item.startedAt = Date.now();
+                item.completedAt = null;
+                candidate.updatedAt = Date.now();
+                this.active += 1;
+                await this.persist();
+                this.emit();
+                void this.execute(candidate, item);
+            }
+            if (this.state.operations.some(operation => !operation.paused && !terminalState(operation.state)
+                && operation.items.some(item => item.state === 'resource_wait'))) {
+                const retry = setTimeout(() => void this.pump(), 5_000);
+                retry.unref?.();
+            }
+        }
+        catch (error) {
+            this.onError(error);
+        }
+        finally {
+            this.pumping = false;
+            if (this.pumpRequested) {
+                this.pumpRequested = false;
+                queueMicrotask(() => void this.pump());
+            }
+        }
+    }
+    async execute(operation, item) {
+        try {
+            const result = await this.runner(operation.id, item.sessionId, phase => {
+                item.phase = phase.slice(0, 80);
+                operation.updatedAt = Date.now();
+                void this.persist().then(() => this.emit()).catch(error => this.onError(error));
+            });
+            if (result?.actualRssBytes !== undefined)
+                item.actualRssBytes = result.actualRssBytes;
+            item.state = 'succeeded';
+            item.phase = 'completed';
+            item.error = undefined;
+            item.errorCode = undefined;
+        }
+        catch (error) {
+            const value = error && typeof error === 'object' ? error : {};
+            const message = error instanceof Error ? error.message : String(error);
+            const code = typeof value.code === 'string' ? value.code
+                : message.includes('TERMINAL_INPUT_TARGET_CHANGED') ? 'TERMINAL_INPUT_TARGET_CHANGED' : 'TMUX_RECOVERY_FAILED';
+            item.state = 'failed';
+            item.phase = code === 'TERMINAL_INPUT_TARGET_CHANGED' ? 'target_changed' : 'failed';
+            item.errorCode = code;
+            item.error = message.slice(0, 1000);
+            this.onError({ operationId: operation.id, sessionId: item.sessionId, code, message });
+        }
+        finally {
+            item.completedAt = Date.now();
+            operation.updatedAt = item.completedAt;
+            const hasPending = operation.items.some(candidate => candidate.state === 'queued' || candidate.state === 'resource_wait' || candidate.state === 'running');
+            if (!hasPending) {
+                operation.paused = false;
+                operation.state = operation.items.some(candidate => candidate.state === 'failed') ? 'partial_failure' : 'succeeded';
+            }
+            else {
+                operation.state = operation.paused ? 'paused'
+                    : operation.items.some(candidate => candidate.state === 'running') ? 'running'
+                        : operation.items.some(candidate => candidate.state === 'queued') ? 'queued' : 'resource_wait';
+            }
+            this.active = Math.max(0, this.active - 1);
+            try {
+                await this.persist();
+            }
+            catch (error) {
+                this.onError(error);
+            }
+            this.emit();
+            void this.pump();
+        }
+    }
+    emit() { for (const listener of this.listeners) {
+        try {
+            listener();
+        }
+        catch { /* observer failure is isolated */ }
+    } }
+    persist() {
+        const snapshot = JSON.stringify(this.state, null, 2);
+        const write = this.writeChain.then(async () => {
+            await fs.mkdir(path.dirname(this.filePath), { recursive: true });
+            const tempPath = `${this.filePath}.${process.pid}.${randomUUID()}.tmp`;
+            await fs.writeFile(tempPath, snapshot, { mode: 0o600 });
+            await fs.rename(tempPath, this.filePath);
+        });
+        this.writeChain = write.catch(error => { this.onError(error); });
+        return write;
+    }
+}
+export function configuredTmuxRecoveryConcurrency(value = process.env.TD_TMUX_RECOVERY_CONCURRENCY) {
+    if (value === undefined || value.trim() === '')
+        return 3;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 16)
+        throw new Error('Recovery concurrency must be an integer from 1 to 16');
+    return parsed;
+}

package/docs/integrations.md

@@ -1291,3 +1291,39 @@ runtime_resolved / queue_acquired / before_paste / before_submit`。时间是 TD
 确定性交错回归覆盖延迟改名/元数据回写、清除检查、持久化等待、输入队列等待、
 真实第二次启动、backend 替换及重新绑定；发生真实换代时，旧输入及旧的延迟回车
 仍被拒绝。测试证明 TD 一致性与终端写入边界，不代替私有 Agent 的实机消费验收。
+
+## 1.4.323：归档与恢复本机协作组显示
+
+最低 **CLI / 实际服务均为 1.4.323**，回读
+`admin_local_group_archive=true`、`admin_local_group_archive_min_version=1.4.323`。
+本机管理员可归档/恢复精确本机组；CLI 与服务均检查能力，旧服务返回
+`ADMIN_LOCAL_GROUP_ARCHIVE_UNSUPPORTED`。
+
+```sh
+td integration group get <精确group-id>
+td integration group archive <精确group-id> \
+  --expected-updated-at <当前updatedAt> --idempotency-key case-archive:v1
+td integration groups                         # 默认不列出归档组
+td integration groups --include-archived       # 显式查看
+td integration group unarchive <精确group-id> \
+  --expected-updated-at <当前updatedAt> --idempotency-key case-restore:v1
+```
+
+`group get` 对归档组仍可用，并在归档时返回 `archivedAt`。归档/恢复仅修改
+`archivedAt` 与组的 `updatedAt`，不改 `id`、名称、成员/角色、principal 固定组、
+TD/native session、运行承载、消息/reply、consumer 游标或历史；不关闭、释放、恢复
+会话，不停止业务调度，也不重放消息。Web 侧栏默认隐藏归档组，在“已归档协作组”
+中可查看并恢复显示；恢复组显示不会重启已关闭的 session。
+
+管理路由为 `POST /admin/groups/:id/archive` 与 `POST /admin/groups/:id/unarchive`，
+请求仅接受 `{expected_updated_at,idempotency_key}`。`GET /admin/groups` 默认隐藏归档
+组，传 `?include_archived=true` 显示归档组。归档/恢复 key 在同一操作范围内唯一，
+参数改变返回 `IDEMPOTENCY_CONFLICT`。成功回执分开返回当前 `group`、本次提交的
+`applied` 和 `replayed`；旧回执重放不会覆盖后来版本。并发版本过期返回
+`GROUP_CHANGED` 与 `currentUpdatedAt`，应先重新 get，再由调用者决定是否用新 key
+重试。同状态操作保留原 `archivedAt` 并记录幂等回执，不推进组版本。
+
+归档 journal 与组状态原子持久化，保留上限为 2000 条。状态/journal 不完整时返回
+`GROUP_ARCHIVE_STATE_UNCONFIRMED`，不会猜测或重建。只允许本机非 federated、未删除
+组；删除组、跨服务组和不确定的目标分别返回 `GROUP_NOT_FOUND`、`GROUP_NOT_LOCAL`、
+`GROUP_ARCHIVE_TARGET_UNAVAILABLE`。归档不延长消息历史保留期。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.322",
+  "version": "1.4.325",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",
@@ -43,7 +43,10 @@
     "test": "vitest --passWithNoTests",
     "test:ui": "vitest --ui",
     "prepublishOnly": "npm run build",
-    "postinstall": "node scripts/postinstall.mjs"
+    "postinstall": "node scripts/postinstall.mjs",
+    "preview:desktop:dev": "npm --prefix desktop-rust run dev",
+    "preview:desktop:build": "npm --prefix desktop-rust run build",
+    "preview:desktop:test": "npm --prefix desktop-rust run verify"
   },
   "dependencies": {
     "@chainsafe/libp2p-noise": "17.0.0",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.322",
+  "version": "1.4.325",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-oaGYi/P5ob8sd6VnNBOwshKozjhdV+hYiCmLAsn5x00=",
-  "serverBundleHash": "sha256-T9JZp3X9tfMUYciSrnZbiUIXuc+IHqHJuGp6Wf5bHs8=",
-  "clientBundleHash": "sha256-4wVT4/UzD+TMRQjVw307g0c0x0cJm6NknoDeybiIQfA=",
+  "serverBundleHash": "sha256-lFOekSTHpHZrRuNcWm20UDGwKSjiviUQKjaT/zSYBvc=",
+  "clientBundleHash": "sha256-RVhKCGWk1bExA0aa9FHB8dutqDr/aCkALgScfT+IS80=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }