termdock 1.4.303 → 1.4.305

package/dist/server/agent/integrationCli.js

@@ -8,6 +8,7 @@ import { executeCollaborationCommand, duration } from './collaborationCli.js';
 import { getTermdockVersion } from '../utils/version.js';
 export const INTEGRATION_HELP = `td integration — local scoped integration administration
   groups | list
+  diagnostics <TD-session-id> (read the last restore check; administrator only)
   create --file <policy.json> --credential-file <private-output.json>
   update --file <policy.json> (same identity/group; preserves the credential)
   revoke <principal-id>
@@ -58,13 +59,22 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
             write(INTEGRATION_HELP);
             return 0;
         }
+        const socketPath = integrationSocketPath(port);
+        if (action === 'diagnostics') {
+            if (argv.length !== 2 || !/^[a-zA-Z0-9._-]{1,80}$/.test(argv[1]))
+                throw new Error('diagnostics requires one TD session id');
+            const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
+            if (capabilities.session_restore_diagnostics !== true)
+                throw new CollaborationError('SESSION_RESTORE_DIAGNOSTICS_UNSUPPORTED', 'Running service does not support stored restore diagnostics', 409);
+            write(JSON.stringify(parsed(await request(socketPath, 'GET', `/admin/sessions/${encodeURIComponent(argv[1])}/restore-diagnostics`, undefined, headers(undefined, adminToken)))));
+            return 0;
+        }
         for (let index = 1; index < argv.length; index += 2) {
             const flag = argv[index];
             if (!['--file', '--credential-file'].includes(flag) || !argv[index + 1] || options[flag])
                 throw new Error('Invalid integration arguments');
             options[flag] = argv[index + 1];
         }
-        const socketPath = integrationSocketPath(port);
         if (action === 'groups' || action === 'list') {
             if (argv.length !== 1)
                 throw new Error('Unexpected arguments');

package/dist/server/agent/integrationServer.js

@@ -61,6 +61,7 @@ export class IntegrationRuntime {
         };
         app.get('/admin/groups', run(req => { admin(req); return { groups: options.messages.list().filter(g => !g.federated).map(g => ({ id: g.id, name: g.name })) }; }));
         app.get('/admin/capabilities', run(req => { admin(req); return this.capabilities(); }));
+        app.get('/admin/sessions/:id/restore-diagnostics', run(req => { admin(req); return this.sessions.restoreDiagnostics(req.params.id); }));
         app.get('/admin/principals', run(req => { admin(req); return { integrations: this.store.policies() }; }));
         app.post('/admin/principals', run(req => { admin(req); this.group(req.body?.groupId); const provisioned = this.store.provision(req.body); try {
             this.sync();
@@ -145,6 +146,7 @@ export class IntegrationRuntime {
             idempotent_session_create: true, exact_session_restore: true, external_validation: false,
             startup_input_conditions: true,
             integration_policy_update: true,
+            session_restore_diagnostics: true,
             permissions: ['task.read', 'task.create', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore'] };
     }
     error(error) {

package/dist/server/agent/integrationSessions.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { atomicJson, integrationError } from './integrationStore.js';
+import { NativeResumeOwnerError } from './nativeResumeOwner.js';
 /** Quote each configured argument as literal shell data, including paths. */
 export function integrationLaunchCommand(record, restore) {
     const launchArgs = record.profile.argv.map(arg => arg === '{cwd}' ? record.cwd : arg);
@@ -15,8 +16,8 @@ function startupInput(record, now) {
     return condition ? { state: 'pending', deadline: now + (condition.timeoutMs ?? 120000), matched_since: null, observed_at: null } : undefined;
 }
 export function publicIntegrationSession(record) {
-    const { profile: _, deadline: _deadline, launch_submitted: _submitted, startup_condition: _condition, ...publicRecord } = record;
-    return publicRecord;
+    const { profile: _, deadline: _deadline, launch_submitted: _submitted, startup_condition: _condition, restore_diagnostics: diagnostics, ...publicRecord } = record;
+    return { ...publicRecord, ...(diagnostics ? { restore_diagnostics_available: true } : {}) };
 }
 export function permittedCwd(profile, cwd) {
     if (typeof cwd !== 'string' || !path.isAbsolute(cwd) || /[\x00-\x1f\x7f]/.test(cwd))
@@ -168,7 +169,9 @@ export class IntegrationSessions {
             catch (error) {
                 const current = this.doc.sessions.find(s => s.session_id === record.session_id);
                 const code = error.code;
-                this.saveRecord({ ...current, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_LAUNCH_FAILED', updated_at: Date.now() });
+                this.saveRecord({ ...current, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_LAUNCH_FAILED',
+                    restore_diagnostics: error instanceof NativeResumeOwnerError ? { ...structuredClone(error.diagnostics), operation_id: current.operation_id } : undefined,
+                    updated_at: Date.now() });
             }
             return structuredClone(this.doc.sessions.find(s => s.session_id === record.session_id));
         })().finally(() => this.pending.delete(record.session_id));
@@ -176,6 +179,14 @@ export class IntegrationSessions {
         return promise;
     }
     async get(principal, id) { this.lookup(principal, id); await this.refresh(id); return this.lookup(principal, id); }
+    /** Read the stored check only: no process probe, PTY attachment, or new launch. */
+    restoreDiagnostics(id) {
+        const record = this.doc.sessions.find(session => session.session_id === id);
+        if (!record)
+            return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Integration session does not exist', 404);
+        return structuredClone({ session_id: record.session_id, operation_id: record.operation_id,
+            state: record.state, error_code: record.error_code, diagnostics: record.restore_diagnostics ?? null });
+    }
     async restore(principal, id, idempotencyKey) {
         const request = this.request(principal, idempotencyKey, ['restore', id]);
         if (request.previous)
@@ -215,6 +226,7 @@ export class IntegrationSessions {
             record.operation_id = randomUUID();
             record.deadline = Date.now() + this.bindingTimeout;
             record.updated_at = Date.now();
+            record.restore_diagnostics = undefined;
             if (!record.profile.startupInput && !record.startup_condition)
                 record.startup_condition = structuredClone(principal.launchProfiles.find(profile => profile.id === record.launch_profile)?.startupInput);
             record.startup_input = startupInput(record, Date.now());

package/dist/server/agent/nativeResumeOwner.js

@@ -1,29 +1,83 @@
-import { integrationError } from './integrationStore.js';
-/** Last-known bindings select uncertain conflicts; only process observations
- * prove a conversation is running. The caller separately verifies its own pane. */
+import { CollaborationError } from './collaborationProtocol.js';
+/** A tmux remains observable without a browser/PTY attachment, including after
+ * service restart. Inventory UUIDs never filter the candidate set. */
+export function collectNativeResumeOwnerCandidates(inventory, backends) {
+    const candidates = [];
+    const seenTmux = new Set(), seenBackend = new Set();
+    for (const entry of inventory) {
+        if (entry.mode !== 'tmux' || !entry.tmuxSessionName || seenTmux.has(entry.tmuxSessionName))
+            continue;
+        const backend = entry.backendSessionId ? backends.get(entry.backendSessionId) : null;
+        candidates.push({ backendSessionId: entry.backendSessionId ?? `inventory:${entry.sessionId}`,
+            sessionId: entry.sessionId, backendAttached: !!backend,
+            tmuxSessionName: entry.tmuxSessionName, cachedSlug: backend?.agent?.slug ?? entry.agentResume?.slug ?? null,
+            cachedNativeId: backend?.agentSession?.sessionId ?? entry.agentResume?.sessionId ?? null });
+        seenTmux.add(entry.tmuxSessionName);
+        if (entry.backendSessionId)
+            seenBackend.add(entry.backendSessionId);
+    }
+    for (const [backendSessionId, backend] of backends) {
+        if (seenBackend.has(backendSessionId) || backend.mode === 'tmux' && backend.tmuxSessionName && seenTmux.has(backend.tmuxSessionName))
+            continue;
+        candidates.push({ backendSessionId, sessionId: inventory.find(entry => entry.backendSessionId === backendSessionId)?.sessionId ?? null,
+            backendAttached: true, tmuxSessionName: backend.mode === 'tmux' ? backend.tmuxSessionName : null,
+            cachedSlug: backend.agent?.slug ?? null, cachedNativeId: backend.agentSession?.sessionId ?? null });
+        if (backend.mode === 'tmux' && backend.tmuxSessionName)
+            seenTmux.add(backend.tmuxSessionName);
+    }
+    return candidates;
+}
+export class NativeResumeOwnerError extends CollaborationError {
+    diagnostics;
+    constructor(code, blockers) {
+        super(code, code === 'NATIVE_SESSION_ALREADY_RUNNING'
+            ? 'Another terminal process proves the exact native conversation is running'
+            : 'A possible native owner cannot be verified; inspect its terminal before restoring', 409);
+        // Preserve the proven owner even when earlier uncertain panes exceed the bound.
+        const ordered = code === 'NATIVE_SESSION_ALREADY_RUNNING' ? [blockers.at(-1), ...blockers.slice(0, -1)] : blockers;
+        this.diagnostics = { code, checked_at: Date.now(), candidates: ordered.slice(0, 128), total_blockers: blockers.length, truncated: blockers.length > 128 };
+    }
+}
+function diagnostic(candidate, process, reason) {
+    // Store only named locator/evidence fields. Never serialize a callback error,
+    // argv, terminal text, cwd, or plugin/wrapper payload into diagnostics.
+    const text = (value) => typeof value === 'string' && value.length <= 256 && !/[\x00-\x1f\x7f]/.test(value) ? value : null;
+    const pid = (value) => Number.isInteger(value) && value > 0 ? value : null;
+    return { session_id: text(candidate.sessionId), backend_session_id: candidate.backendSessionId.startsWith('inventory:') ? null : text(candidate.backendSessionId),
+        backend_attached: candidate.backendAttached ?? null, tmux_session_name: text(candidate.tmuxSessionName),
+        tmux_session_id: text(process?.tmuxSessionId), pane_id: text(process?.paneId), pane_pid: pid(process?.panePid),
+        program: text(process?.program), process_source: text(process?.processSource), arguments_observed: process?.argumentsObserved === true,
+        agent_slug: text(process?.agentSlug), last_known_native_id: text(candidate.cachedNativeId), observed_native_id: text(process?.nativeId),
+        pgid: Number.isInteger(process?.pgid) ? process.pgid : null,
+        tpgid: Number.isInteger(process?.tpgid) ? process.tpgid : null, reason, observed_at: Date.now() };
+}
+/** Only process observations prove presence or absence of another owner.
+ * Cached UUIDs cannot exclude a terminal; the caller verifies its own pane. */
 export async function assertNativeResumeAvailable(target, excludedBackendSessionId, candidates, observe) {
-    let uncertain = false;
+    const blockers = [];
     for (const candidate of candidates) {
         if (candidate.backendSessionId === excludedBackendSessionId)
             continue;
-        const cachedMatch = candidate.cachedSlug === target.slug && candidate.cachedNativeId === target.nativeSessionId;
         let processes;
         try {
             processes = await observe(candidate);
         }
         catch {
-            if (cachedMatch)
-                uncertain = true;
+            blockers.push(diagnostic(candidate, null, 'TERMINAL_OBSERVATION_FAILED'));
             continue;
         }
         for (const process of processes) {
             if (process.confirmed && process.agentSlug === target.slug && process.nativeId === target.nativeSessionId) {
-                integrationError('NATIVE_SESSION_ALREADY_RUNNING', 'Another terminal process proves the exact native conversation is running', 409);
+                blockers.push(diagnostic(candidate, process, 'NATIVE_SESSION_MATCH'));
+                throw new NativeResumeOwnerError('NATIVE_SESSION_ALREADY_RUNNING', blockers);
             }
-            if (cachedMatch && (!process.confirmed || process.agentSlug === target.slug && !process.nativeId))
-                uncertain = true;
+            if (!process.confirmed)
+                blockers.push(diagnostic(candidate, process, process.shellFailure
+                    ?? (process.argumentsObserved === false ? 'PROCESS_ARGUMENTS_UNAVAILABLE' : 'FOREGROUND_PROCESS_UNCONFIRMED')));
+            else if (process.agentSlug === target.slug && !process.nativeId)
+                blockers.push(diagnostic(candidate, process, 'NATIVE_SESSION_ID_MISSING'));
         }
     }
-    if (uncertain)
-        integrationError('NATIVE_SESSION_OWNER_UNCONFIRMED', 'A possible native owner cannot be verified; inspect its terminal before restoring', 409);
+    if (blockers.length)
+        throw new NativeResumeOwnerError('NATIVE_SESSION_OWNER_UNCONFIRMED', blockers);
 }

package/dist/server/routes/terminal.js

@@ -1,6 +1,6 @@
 import { collaborationSessionDisplayName } from '../utils/sessionDisplayName.js';
 import { integrationError } from '../agent/integrationStore.js';
-import { assertNativeResumeAvailable } from '../agent/nativeResumeOwner.js';
+import { assertNativeResumeAvailable, collectNativeResumeOwnerCandidates } from '../agent/nativeResumeOwner.js';
 import { integrationLaunchCommand } from '../agent/integrationSessions.js';
 import { ensureTeam } from '../agent/collaborationTeam.js';
 import { androidRecordings } from '../android/recording.js';
@@ -1825,19 +1825,26 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
 /** Restricted session adapter: only preconfigured argv and the exact owned
  * terminal can be launched; no remote drive or arbitrary shell commands. */
 async function integrationPaneIsIdleShell(pane) {
+    return (await inspectIntegrationShell(pane)).confirmed;
+}
+async function inspectIntegrationShell(pane) {
     if (!pane.isShell)
-        return false;
+        return { confirmed: false, failure: null, pgid: null, tpgid: null };
     try {
         const { stdout } = await execFileAsync('ps', ['-p', String(pane.panePid), '-o', 'pgid=,tpgid=,args='], { timeout: 3000, maxBuffer: 16384 });
-        const row = stdout.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
-        if (!row || row[1] !== row[2])
-            return false;
+        const row = stdout.trim().match(/^(-?\d+)\s+(-?\d+)\s+(.+)$/);
+        if (!row)
+            return { confirmed: false, failure: 'SHELL_PROCESS_NOT_FOUND', pgid: null, tpgid: null };
+        const pgid = Number(row[1]), tpgid = Number(row[2]);
+        if (pgid <= 0 || pgid !== tpgid)
+            return { confirmed: false, failure: 'SHELL_FOREGROUND_MISMATCH', pgid, tpgid };
         const argv = splitCommandToArgv(row[3]);
         const command = normalizeProgramName(argv[0]?.replace(/^-/, ''))?.toLowerCase();
-        return !!command && shellNamesBackend.has(command) && argv.slice(1).every(arg => ['-l', '-i', '-il', '-li', '--login', '--interactive'].includes(arg));
+        const confirmed = !!command && shellNamesBackend.has(command) && argv.slice(1).every(arg => ['-l', '-i', '-il', '-li', '--login', '--interactive'].includes(arg));
+        return { confirmed, failure: confirmed ? null : 'SHELL_ARGUMENTS_UNSUPPORTED', pgid, tpgid };
     }
     catch {
-        return false;
+        return { confirmed: false, failure: 'SHELL_OBSERVATION_FAILED', pgid: null, tpgid: null };
     }
 }
 function integrationTerminalRecord(record) {
@@ -1910,43 +1917,44 @@ async function assertIntegrationNativeResumeAvailable(record) {
     // Never use a recovered hook or the last-known UUID as live-owner proof.
     if (process.platform === 'linux')
         await getProcessSnapshot(true);
-    const candidates = [...terminalSessions].map(([backendSessionId, backend]) => {
-        const persisted = globalSessionState.sessions.find(entry => entry.backendSessionId === backendSessionId)?.agentResume;
-        return { backendSessionId, cachedSlug: backend.agent?.slug ?? persisted?.slug ?? null,
-            cachedNativeId: backend.agentSession?.sessionId ?? persisted?.sessionId ?? null };
-    });
+    const candidates = collectNativeResumeOwnerCandidates(globalSessionState.sessions, terminalSessions);
     await assertNativeResumeAvailable({ slug: record.agent_slug, nativeSessionId: record.agent_native_session_id }, own?.backendSessionId ?? null, candidates, async (candidate) => {
         const backend = terminalSessions.get(candidate.backendSessionId);
-        if (!backend)
-            return [];
+        const tmuxSessionName = candidate.tmuxSessionName;
         // Duplicate inventory attachments to the original owned pane are not
         // another process; launchIntegrationTerminal verifies that pane again.
-        if (backend.mode === 'tmux' && backend.tmuxSessionName === own?.tmuxSessionName)
+        if (tmuxSessionName && tmuxSessionName === own?.tmuxSessionName)
             return [];
-        if (backend.mode === 'tmux' && backend.tmuxSessionName) {
+        if (tmuxSessionName) {
             try {
-                await runTmux(['has-session', '-t', `=${backend.tmuxSessionName}`]);
+                await runTmux(['has-session', '-t', `=${tmuxSessionName}`]);
             }
             catch (error) {
                 if (/can't find session|no server running|no sessions|error connecting.*No such file/i.test(getErrorMessage(error)))
                     return [];
                 throw error;
             }
-            const layout = await getTmuxLayout(backend.tmuxSessionName);
+            const layout = await getTmuxLayout(tmuxSessionName);
             return Promise.all(layout.windows.flatMap(window => window.panes).map(async (pane) => {
                 const program = await resolveTmuxPaneProgram(pane, true, true);
                 const agent = detectAgentFromCommand(program?.rawArgs ?? program?.command ?? '', agentCustomCommands());
-                const shell = !agent && await integrationPaneIsIdleShell({ panePid: pane.pid,
-                    isShell: shellNamesBackend.has(normalizeProgramName(program?.command ?? '')?.toLowerCase() ?? '') });
-                return { confirmed: shell || program?.source === 'tmux-tty' && Boolean(program.rawArgs),
+                const shell = await inspectIntegrationShell({ panePid: pane.pid,
+                    isShell: !agent && shellNamesBackend.has(normalizeProgramName(program?.command ?? '')?.toLowerCase() ?? '') });
+                return { confirmed: shell.confirmed || program?.source === 'tmux-tty' && Boolean(program.rawArgs),
                     agentSlug: agent?.slug ?? null,
-                    nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null };
+                    nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null,
+                    paneId: pane.id, panePid: pane.pid, tmuxSessionId: layout.sessionId, program: program?.command ?? null,
+                    processSource: program?.source, argumentsObserved: !!program?.rawArgs,
+                    shellFailure: shell.failure, pgid: shell.pgid, tpgid: shell.tpgid };
             }));
         }
+        if (!backend)
+            return [];
         const program = await detectShellActiveProgram(backend);
         const agent = detectAgentFromCommand(program?.rawArgs ?? program?.command ?? '', agentCustomCommands());
         return [{ confirmed: !!program && program.source !== 'unknown', agentSlug: agent?.slug ?? null,
-                nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null }];
+                nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null,
+                program: program?.command ?? null, processSource: program?.source, argumentsObserved: !!program?.rawArgs }];
     });
 }
 async function launchIntegrationTerminal(record, restoring, prepared) {

package/docs/integrations.md

@@ -4,7 +4,9 @@
 启动输入条件与保留凭据的策略更新要求 **CLI / 实际运行服务均至少 1.4.301**；协议仍为 1。
 插件原生 ID 的前台 argv 回读及服务重启后的运行中 restore 核验修复要求
 **实际运行服务至少 1.4.302**。退出后的重复原生会话检查修复要求
-**实际运行服务至少 1.4.303**；建议 CLI 与服务同步安装 1.4.303（CLI 最低仍为 1.4.301）。
+**实际运行服务至少 1.4.303**。没有 PTY 附着的已登记 tmux 的重复保护修复要求
+**实际运行服务至少 1.4.304**。管理员恢复诊断要求 **CLI / 实际服务均至少 1.4.305**；
+建议 CLI 与服务同步安装 1.4.305（既有接入命令的 CLI 最低仍为 1.4.301）。
 现有 `--session`、消息投递、任务报告与自动协作入口继续兼容；旧的
 `task create --integration` 仍表示代码集成子任务，新身份使用 `--principal`。
 
@@ -303,9 +305,61 @@ operation/pane，不启动第二个 Agent；进程携带不同 UUID 时继续拒
 返回 `NATIVE_SESSION_OWNER_UNCONFIRMED` 并停止恢复；应检查该终端，不绕过保护。
 此检查覆盖服务已登记终端，不声称枚举其他应用中全部原生会话。
 
+1.4.304 起，检查合并持久终端清单和当前 PTY backend；服务重启后无需网页挂接，
+已登记 tmux 的每个 pane 都会现场核验。旧登记 UUID C 不会排除当前实际运行 UUID A
+的终端，终端的协作路由为 recovering/offline 或绑定不匹配也不会跳过检查。
+仅在确认 tmux 已消失或当前进程排除冲突时继续；未知进程、同 Agent 缺少精确 UUID、
+观察失败均返回 `NATIVE_SESSION_OWNER_UNCONFIRMED`，不以旧 UUID 证明没有冲突。
+
+### 管理员恢复诊断（1.4.305）
+
+`capabilities.session_restore_diagnostics=true` 表示服务支持持久恢复诊断。
+遇到 `NATIVE_SESSION_OWNER_UNCONFIRMED` 或 `NATIVE_SESSION_ALREADY_RUNNING` 后，
+本机管理员执行：
+
+```sh
+td integration diagnostics <TD-session-id>
+```
+
+命令经原私有 Unix socket 和本机管理员凭据读取报告，不使用 `--principal`。
+服务能力缺失时返回 `SESSION_RESTORE_DIAGNOSTICS_UNSUPPORTED`，不会假装诊断成功。
+命令仅读取已存记录，不重新扫描进程、不挂接 PTY、不试键、不创建恢复意图。
+304 及更早的失败没有此报告；升级后应使用新的 restore 幂等键执行一次明确检查，
+再读报告。旧键不会执行一次新检查。
+
+响应包含当前 `session_id / operation_id / state / error_code`，以及可为空的
+`diagnostics`。报告含其自身 `operation_id / checked_at / code`、`candidates`、
+`total_blockers / truncated`；它是该次检查的历史事实，不能代表读取时的当前进程。
+只有上一次**实际发起**的恢复检查会保存报告；下一次实际恢复清除旧报告，运行中
+no-op restore 不创建新检查。报告跟随会话保存并可在服务重启后回读。
+
+每个阻塞候选含 `session_id / backend_session_id / backend_attached`、
+`tmux_session_name / tmux_session_id / pane_id / pane_pid`、`program / process_source`、
+`arguments_observed / agent_slug / last_known_native_id / observed_native_id`、
+`pgid / tpgid / reason / observed_at`；无法观测的值为 null。backend 不存在或仅有旧
+登记仍可通过 tmux 核验；`pane_pid` 是承载 pane 的 PID，不冒充 Agent 前台 PID。
+报告最多保存 128 个阻塞候选；`total_blockers` 保留总数，确定的同 UUID 所有者优先展示。
+
+| reason | 实际证据缺口或冲突 |
+| --- | --- |
+| NATIVE_SESSION_MATCH | 当前前台进程明确携带目标 UUID |
+| NATIVE_SESSION_ID_MISSING | 当前同 Agent 的进程已观测，但没有可回读的精确 UUID |
+| PROCESS_ARGUMENTS_UNAVAILABLE | 无法取得可靠的当前进程 argv |
+| FOREGROUND_PROCESS_UNCONFIRMED | 无法可靠核验前台进程 |
+| SHELL_PROCESS_NOT_FOUND | shell 的 ps 输出未形成可解析记录 |
+| SHELL_FOREGROUND_MISMATCH | shell 未持有有效前台进程组；记录 pgid/tpgid |
+| SHELL_ARGUMENTS_UNSUPPORTED | 当前 shell 命令或启动参数未满足既有安全检查 |
+| SHELL_OBSERVATION_FAILED | shell 的进程观察失败 |
+| TERMINAL_OBSERVATION_FAILED | tmux 或终端观察失败，无法排除该候选 |
+
+完整候选可能来自其他组，因此仅管理员接口返回；principal 的 session 响应与推送
+事件只增加 `restore_diagnostics_available=true`，不含候选标识/UUID。报告不保存或
+返回原始 argv、cwd、终端正文、包装器异常、凭据。诊断不自动放宽任何拒绝条件，
+不能把旧 UUID、native ready 或 Agent 忙闲推测当作消除冲突的证据。
+
 常见失败码（每项都是完整字符串）：
 
-- 配置/权限：`LAUNCH_PROFILE_DENIED`, `LAUNCHER_UNAVAILABLE`, `COLLAB_AGENT_UNAVAILABLE`, `SESSION_CWD_MISSING`, `SESSION_CWD_DENIED`, `INTEGRATION_SESSION_NOT_FOUND`, `INTEGRATION_SESSION_LIMIT`。
+- 配置/权限：`LAUNCH_PROFILE_DENIED`, `LAUNCHER_UNAVAILABLE`, `COLLAB_AGENT_UNAVAILABLE`, `SESSION_CWD_MISSING`, `SESSION_CWD_DENIED`, `INTEGRATION_SESSION_NOT_FOUND`, `INTEGRATION_SESSION_LIMIT`, `SESSION_RESTORE_DIAGNOSTICS_UNSUPPORTED`。
 - 终端/身份：`SESSION_BACKEND_UNAVAILABLE`, `SESSION_TARGET_NOT_SHELL`, `SESSION_IDENTITY_MISMATCH`, `NATIVE_SESSION_ID_MISMATCH`, `NATIVE_SESSION_ID_INVALID`, `NATIVE_SESSION_ID_MISSING`。
 - 启动/恢复：`SESSION_CREATE_OUTCOME_UNKNOWN`, `SESSION_OPERATION_IN_PROGRESS`, `SESSION_BINDING_TIMEOUT`, `EXACT_RESUME_UNSUPPORTED`, `NATIVE_SESSION_ALREADY_RUNNING`, `NATIVE_SESSION_OWNER_UNCONFIRMED`, `AGENT_NOT_RUNNING`。
 - 未分类异常：`SESSION_LAUNCH_FAILED`, `SESSION_OBSERVATION_FAILED`；错误不包含包装器输出、密钥或原始堆栈。
@@ -325,7 +379,13 @@ operation/pane，不启动第二个 Agent；进程携带不同 UUID 时继续拒
 不重复启动、不同 UUID 拒绝，以及进程退出后缓存 UUID 不再阻挡恢复。使用方已报告
 1.4.302 真实 TraeX 服务重启回读、运行中恢复不重启、不同 UUID 拒绝通过；显式恢复
 原 UUID 也已回读 ready，但配置的模型 footer 条件被暂态提示替换，输入仍保持待投递。
-**1.4.303 的真实 TraeX 退出后恢复与稳定输入条件仍须使用方实机复验**。
+使用方已报告 1.4.303 退出后精确恢复通过，也发现未挂接 PTY 的已登记 tmux 重复保护
+遗漏；维护机已用“旧 UUID C、实际运行 UUID A、无 PTY 附着”的真实隔离 tmux 复现，
+并验证 1.4.304 编译后检查在该状态下拒绝再次启动。
+使用方已报告 1.4.304 在未挂接网页/PTY、旧登记 UUID C 而实际运行 A 的场景下，
+正确拒绝同 UUID 恢复且没有第二个进程。所有者退出后仍有未确认候选，不能仅凭
+错误码判断是哪一个 pane；1.4.305 提供管理员持久诊断，并保持原拒绝条件。
+**1.4.305 的真实 TraeX 阻塞候选诊断与稳定输入条件仍须使用方实机复验**。
 回读 capabilities 后，应核对原 TD ID、真实 TraeX UUID 与原 argv/cwd/包装器快照，
 并验证 Agent 真正加载原对话。
 先完成测试环境的创建→追问→关联答复，再验重复键、追加咨询、断线重投和精确恢复。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.303",
+  "version": "1.4.305",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",

package/runtime-manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.303",
+  "version": "1.4.305",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-+P0Zwo5Zg52vSfyTrvxcfAIAuwY0+n4i4f0kTf8BC0g=",
+  "serverBundleHash": "sha256-XkM6+bMn6xdVpuXe8oaPunofP3J+MgVfh7lwiOhSY4I=",
   "clientBundleHash": "sha256-HOoNMOYhnph9XwUhSYE5W2CdI9Vb4g0c64ubW49LnXE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"