termdock 1.4.304 → 1.4.306

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,8 @@ 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,
+            native_identity_linux_flock_owner: process.platform === 'linux',
             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/nativeProcessIdentity.js

@@ -0,0 +1,162 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function nativeIdentityDirectory(config) {
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return null;
+    const c = config;
+    if (c.kind !== 'linux-flock-owner' || Object.keys(c).some(k => !['kind', 'directory'].includes(k))
+        || typeof c.directory !== 'string' || c.directory.length > 1024 || /[\x00-\x1f\x7f]/.test(c.directory))
+        return null;
+    const expanded = c.directory.startsWith('~/') ? path.join(os.homedir(), c.directory.slice(2)) : c.directory;
+    if (!path.isAbsolute(expanded))
+        return null;
+    const directory = path.resolve(expanded), relative = path.relative(os.homedir(), directory);
+    return relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) ? directory : null;
+}
+const unavailable = { nativeId: null, outcome: 'unavailable' };
+function processStat(text, pid) {
+    const close = text.lastIndexOf(')'), open = text.indexOf('(');
+    if (open < 0 || close <= open || Number(text.slice(0, open).trim()) !== pid)
+        return null;
+    const fields = text.slice(close + 1).trim().split(/\s+/);
+    const pgid = Number(fields[2]), tpgid = Number(fields[5]), start = fields[19];
+    return fields[0] !== 'Z' && pgid > 0 && pgid === tpgid && /^\d+$/.test(start ?? '') ? { pgid, tpgid, start, comm: text.slice(open + 1, close) } : null;
+}
+function safeFile(stat, uid) {
+    return stat.isFile() && stat.uid === BigInt(uid) && (stat.mode & 18n) === 0n;
+}
+function sameFile(a, b) { return a.dev === b.dev && a.ino === b.ino; }
+function kernelWriter(locks, pid, stat) {
+    // Linux dev_t encoding, matched against /proc/locks major:minor:inode.
+    const major = (stat.dev >> 8n & 0xfffn) | (stat.dev >> 32n & 0xfffff000n);
+    const minor = (stat.dev & 0xffn) | (stat.dev >> 12n & 0xffffff00n);
+    return locks.split('\n').some(line => {
+        const m = line.match(/^\d+:\s+FLOCK\s+ADVISORY\s+WRITE\s+(\d+)\s+([0-9a-f]+):([0-9a-f]+):(\d+)\s+0\s+EOF\s*$/i);
+        return !!m && Number(m[1]) === pid && BigInt(`0x${m[2]}`) === major && BigInt(`0x${m[3]}`) === minor && BigInt(m[4]) === stat.ino;
+    });
+}
+async function readOwner(file, uid) {
+    const handle = await fs.promises.open(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat({ bigint: true });
+        if (!safeFile(stat, uid) || stat.size > 4096n)
+            return null;
+        const buffer = Buffer.alloc(4097), { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead > 4096)
+            return null;
+        const value = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Confirm exactly one UUID using a current foreground PID, owner starttime,
+ * its real open FD/inode, and the kernel's exclusive whole-file flock. */
+export async function readNativeProcessIdentity(pid, config, expectedComm, expectedArgs) {
+    if (process.platform !== 'linux' || !Number.isSafeInteger(pid) || pid <= 1 || !process.getuid)
+        return unavailable;
+    const directory = nativeIdentityDirectory(config), uid = process.getuid();
+    if (!directory)
+        return unavailable;
+    let hadNativeDescriptor = false;
+    try {
+        const root = await fs.promises.lstat(directory, { bigint: true });
+        if (!root.isDirectory() || root.uid !== BigInt(uid) || (root.mode & 18n) !== 0n)
+            return unavailable;
+        const canonical = await fs.promises.realpath(directory), canonicalHome = await fs.promises.realpath(os.homedir());
+        if (!canonical.startsWith(`${canonicalHome}${path.sep}`))
+            return unavailable;
+        const proc = `/proc/${pid}`, initial = processStat(await fs.promises.readFile(`${proc}/stat`, 'utf8'), pid);
+        if (!initial || expectedComm && initial.comm !== expectedComm || (await fs.promises.stat(proc)).uid !== uid)
+            return { nativeId: null, outcome: 'process_changed' };
+        const argsMatch = async () => {
+            if (expectedArgs === undefined)
+                return true;
+            const handle = await fs.promises.open(`${proc}/cmdline`, fs.constants.O_RDONLY);
+            try {
+                const buffer = Buffer.alloc(16385), { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                return bytesRead < buffer.length && buffer.subarray(0, bytesRead).toString('utf8').replace(/\0$/, '').split('\0').join(' ').trim() === expectedArgs.trim();
+            }
+            finally {
+                await handle.close();
+            }
+        };
+        if (!await argsMatch())
+            return { nativeId: null, outcome: 'process_changed' };
+        const lockDescriptors = async () => {
+            const descriptors = await fs.promises.readdir(`${proc}/fd`);
+            if (descriptors.length > 4096)
+                throw new Error('descriptor bound');
+            const files = [];
+            for (const descriptor of descriptors) {
+                if (!/^\d+$/.test(descriptor))
+                    continue;
+                const fd = `${proc}/fd/${descriptor}`;
+                let target;
+                try {
+                    target = await fs.promises.readlink(fd);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        continue;
+                    throw error;
+                }
+                if (path.dirname(target) === canonical && /\.lock(?: \(deleted\))?$/.test(target))
+                    files.push({ fd, target });
+            }
+            return files.sort((a, b) => a.fd.localeCompare(b.fd));
+        };
+        const descriptors = await lockDescriptors();
+        hadNativeDescriptor = descriptors.length > 0;
+        const locks = await fs.promises.readFile('/proc/locks', 'utf8');
+        const verified = new Map();
+        let unproved = false;
+        for (const { fd, target } of descriptors) {
+            if (!target.endsWith('.lock')) {
+                unproved = true;
+                continue;
+            }
+            const nativeId = path.basename(target).slice(0, -5);
+            if (!/^[A-Za-z0-9._-]{1,256}$/.test(nativeId) || nativeId === '.' || nativeId === '..') {
+                unproved = true;
+                continue;
+            }
+            try {
+                const lock = await fs.promises.lstat(target, { bigint: true }), held = await fs.promises.stat(fd, { bigint: true });
+                const ownerFile = path.join(canonical, `${nativeId}.owner.json`), owner = await readOwner(ownerFile, uid);
+                if (!safeFile(lock, uid) || !sameFile(lock, held) || !kernelWriter(locks, pid, lock)
+                    || owner?.pid !== pid || owner.process_start_id !== `linux:${initial.start}`) {
+                    unproved = true;
+                    continue;
+                }
+                verified.set(nativeId, { fd, stat: lock, owner: ownerFile });
+            }
+            catch {
+                unproved = true;
+            }
+        }
+        if (verified.size > 1)
+            return { nativeId: null, outcome: 'ambiguous' };
+        if (unproved)
+            return { nativeId: null, outcome: 'unconfirmed' };
+        if (verified.size !== 1)
+            return unavailable;
+        const final = processStat(await fs.promises.readFile(`${proc}/stat`, 'utf8'), pid);
+        const currentLocks = await fs.promises.readFile('/proc/locks', 'utf8');
+        const [nativeId, evidence] = [...verified][0];
+        const current = await fs.promises.lstat(path.join(canonical, `${nativeId}.lock`), { bigint: true });
+        const held = await fs.promises.stat(evidence.fd, { bigint: true }), owner = await readOwner(evidence.owner, uid);
+        if (!final || final.start !== initial.start || final.comm !== initial.comm || final.pgid !== initial.pgid || final.tpgid !== initial.tpgid
+            || !await argsMatch()
+            || JSON.stringify(await lockDescriptors()) !== JSON.stringify(descriptors)
+            || !safeFile(current, uid) || !sameFile(current, evidence.stat) || !sameFile(current, held)
+            || !kernelWriter(currentLocks, pid, current) || owner?.pid !== pid || owner.process_start_id !== `linux:${final.start}`)
+            return { nativeId: null, outcome: 'process_changed' };
+        return { nativeId, outcome: 'verified' };
+    }
+    catch {
+        return hadNativeDescriptor ? { nativeId: null, outcome: 'unconfirmed' } : unavailable;
+    }
+}

package/dist/server/agent/nativeResumeOwner.js

@@ -1,4 +1,4 @@
-import { integrationError } from './integrationStore.js';
+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) {
@@ -9,6 +9,7 @@ export function collectNativeResumeOwnerCandidates(inventory, backends) {
             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);
@@ -18,17 +19,44 @@ export function collectNativeResumeOwnerCandidates(inventory, backends) {
     for (const [backendSessionId, backend] of backends) {
         if (seenBackend.has(backendSessionId) || backend.mode === 'tmux' && backend.tmuxSessionName && seenTmux.has(backend.tmuxSessionName))
             continue;
-        candidates.push({ backendSessionId, tmuxSessionName: backend.mode === 'tmux' ? backend.tmuxSessionName : null,
+        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),
+        process_pid: pid(process?.processPid), native_identity_source: process?.nativeIdentitySource === 'argv'
+            || process?.nativeIdentitySource === 'linux-flock-owner' ? process.nativeIdentitySource : null,
+        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;
@@ -37,17 +65,21 @@ export async function assertNativeResumeAvailable(target, excludedBackendSession
             processes = await observe(candidate);
         }
         catch {
-            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 (!process.confirmed || process.agentSlug === target.slug && !process.nativeId)
-                uncertain = true;
+            if (!process.confirmed)
+                blockers.push(diagnostic(candidate, process, process.nativeIdentityFailure ?? 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/agent/plugins.js

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { nativeIdentityDirectory } from './nativeProcessIdentity.js';
 export const PLUGINS_DIR = path.join(os.homedir(), '.termdock', 'agent-plugins');
 export const MANIFEST_FILE = 'manifest.json';
 export const ICON_FILE = 'icon.svg';
@@ -323,6 +324,13 @@ export function validateManifest(raw, dir) {
             };
         }
     }
+    let nativeIdentity;
+    if (m.nativeIdentity !== undefined) {
+        if (!nativeIdentityDirectory(m.nativeIdentity))
+            errors.push('nativeIdentity must declare linux-flock-owner with a directory under home');
+        else
+            nativeIdentity = { kind: 'linux-flock-owner', directory: m.nativeIdentity.directory };
+    }
     // Optional automatic-title provider. Commands are argv arrays rather than
     // shell snippets so a UI-installed manifest cannot gain accidental shell
     // interpolation beyond the executable it explicitly declares.
@@ -411,6 +419,7 @@ export function validateManifest(raw, dir) {
             statuses,
             hooks,
             resume: resumeConfig,
+            nativeIdentity,
             titleNamer,
         },
     };

package/dist/server/agent/registry.js

@@ -315,6 +315,7 @@ export function buildResumeCommand(agent, sessionId, launchArgv) {
 // ---------------------------------------------------------------------------
 /** Plugin-defined resume configs, keyed by slug. */
 const pluginResumeConfigs = new Map();
+const pluginNativeIdentityConfigs = new Map();
 /**
  * Register plugin agents into the lookup maps. Plugins whose slug or aliases
  * collide with built-in agents are skipped. Call `clearPluginAgents()` first
@@ -362,6 +363,8 @@ export function registerPluginAgents(plugins) {
                 staleFlags: manifest.resume.staleFlags ?? [],
             });
         }
+        if (manifest.nativeIdentity)
+            pluginNativeIdentityConfigs.set(manifest.slug, { ...manifest.nativeIdentity });
         registered++;
     }
     return { registered, skipped };
@@ -376,6 +379,11 @@ export function clearPluginAgents() {
             BY_ALIAS.delete(alias);
     }
     pluginResumeConfigs.clear();
+    pluginNativeIdentityConfigs.clear();
+}
+export function getPluginNativeIdentityConfig(slug) {
+    const config = pluginNativeIdentityConfigs.get(slug);
+    return config ? { ...config } : undefined;
 }
 export function getPluginResumeConfig(slug) {
     return pluginResumeConfigs.get(slug);

package/dist/server/routes/terminal.js

@@ -1,6 +1,7 @@
 import { collaborationSessionDisplayName } from '../utils/sessionDisplayName.js';
 import { integrationError } from '../agent/integrationStore.js';
 import { assertNativeResumeAvailable, collectNativeResumeOwnerCandidates } from '../agent/nativeResumeOwner.js';
+import { readNativeProcessIdentity } from '../agent/nativeProcessIdentity.js';
 import { integrationLaunchCommand } from '../agent/integrationSessions.js';
 import { ensureTeam } from '../agent/collaborationTeam.js';
 import { androidRecordings } from '../android/recording.js';
@@ -38,7 +39,7 @@ import { inspectLinuxInotifyUsage, isWatchResourceExhaustion } from '../utils/fi
 import { writeResponseChunk } from '../utils/httpResponse.js';
 import { getFocusSequence, removeClientFocusState, scanFocusTrackingMode, setClientFocusState, } from '../utils/tmuxFocus.js';
 import { extractProgramLabelFromArgs, normalizeProgramName, normalizeTmuxMetadataProgram, selectTmuxForegroundProgram, } from '../utils/tmuxProgramDetection.js';
-import { agentBySlug, buildResumeCommand, detectAgentFromCommand, inferResumeSessionId, listAgents, } from '../agent/registry.js';
+import { agentBySlug, buildResumeCommand, detectAgentFromCommand, inferResumeSessionId, getPluginNativeIdentityConfig, listAgents, } from '../agent/registry.js';
 import { applyAgentEvent, agentEventMatchesCurrentAgent, defaultAgentSessionState, parseAgentEvent, } from '../agent/session.js';
 import { canRestoreDeadAgentShell, isConfirmedAgentResumeProcess, normalizePersistedAgentResumeInfo, } from '../agent/resumePersistence.js';
 import { AgentResumeHistoryStore } from '../agent/resumeHistory.js';
@@ -1577,7 +1578,7 @@ function formatLocalCollaborationMessages(frontendSessionId, messages) {
  *  agent-keyed selector can never reach it. Delivery still needs an agent (the
  *  confirm gate and prompt formatting assume a TUI); driving a terminal —
  *  run/capture — is a shell operation and works on any pane. */
-async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane = false) {
+async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane = false, nativeProcessIdentity = false) {
     if (!binding.tmuxSessionName)
         return { state: 'offline', reason: 'TMUX_BINDING_MISSING' };
     const name = `=${binding.tmuxSessionName}`;
@@ -1596,12 +1597,19 @@ async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane =
     const serverPid = Number((await runTmux(['display-message', '-p', '#{pid}'])).trim());
     if (!Number.isInteger(serverPid) || serverPid <= 0)
         throw new Error('TMUX_SERVER_IDENTITY_UNAVAILABLE');
+    if (nativeProcessIdentity && process.platform === 'linux')
+        await getProcessSnapshot(true);
     const panes = await Promise.all(layout.windows.flatMap((window) => window.panes).map(async (pane) => {
         // Native identity needs the foreground argv even for a named binary;
         // pane_current_command alone cannot prove an exact resumed conversation.
         const program = await resolveTmuxPaneProgram(pane, true);
         const agent = detectAgentFromCommand(program?.rawArgs ?? program?.command ?? '', agentCustomCommands());
-        const nativeSessionId = agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null;
+        const identity = nativeProcessIdentity ? await observeProgramNativeIdentity(agent, program)
+            : { nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null, failure: null };
+        if (identity.failure)
+            integrationError(identity.failure === 'NATIVE_SESSION_IDENTITY_CONFLICT'
+                ? 'NATIVE_SESSION_ID_MISMATCH' : 'NATIVE_SESSION_OWNER_UNCONFIRMED', 'Current process native identity evidence conflicts or cannot be uniquely verified', 409);
+        const nativeSessionId = identity.nativeId;
         return { serverPid, sessionId: layout.sessionId, paneId: pane.id, panePid: pane.pid,
             agentSlug: agent?.slug ?? '', nativeSessionId, cwd: pane.currentPath,
             isShell: shellNamesBackend.has(normalizeProgramName(program?.command ?? '')?.toLowerCase() ?? '') };
@@ -1825,19 +1833,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) {
@@ -1865,7 +1880,7 @@ export const integrationSessionAdapter = {
         const binding = { sessionId: record.session_id, backendSessionId: terminal.backendSessionId,
             mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: record.agent_slug,
             nativeSessionId: record.agent_native_session_id, pane: record.terminal_binding ?? null };
-        const inspected = await inspectCollaborationTmux(binding);
+        const inspected = await inspectCollaborationTmux(binding, undefined, false, true);
         if (inspected.state === 'offline')
             return { exists: false, running: false, shell: false, agentSlug: null, nativeId: null };
         if (inspected.state !== 'ready' || !inspected.pane)
@@ -1931,11 +1946,16 @@ async function assertIntegrationNativeResumeAvailable(record) {
             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 identity = await observeProgramNativeIdentity(agent, program);
+                const shell = await inspectIntegrationShell({ panePid: pane.pid,
+                    isShell: !agent && shellNamesBackend.has(normalizeProgramName(program?.command ?? '')?.toLowerCase() ?? '') });
+                return { confirmed: !identity.failure && (shell.confirmed || program?.source === 'tmux-tty' && Boolean(program.rawArgs)),
                     agentSlug: agent?.slug ?? null,
-                    nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null };
+                    nativeId: identity.nativeId, nativeIdentityFailure: identity.failure, nativeIdentitySource: identity.source,
+                    processPid: program?.processPid,
+                    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)
@@ -1943,7 +1963,8 @@ async function assertIntegrationNativeResumeAvailable(record) {
         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) {
@@ -3937,13 +3958,15 @@ async function resolveTmuxPaneProgram(pane, requireArgs = false, refreshTty = fa
         }
         const selected = selectTmuxForegroundProgram({
             panePid: pane.pid,
+            includePaneProcess: requireArgs,
             rows,
             shellNames: shellNamesBackend,
             genericProgramNames,
             extractProgramLabel,
         });
         if (selected) {
-            return { command: selected.command, source: 'tmux-tty', rawArgs: selected.rawArgs };
+            return { command: selected.command, source: 'tmux-tty', rawArgs: selected.rawArgs,
+                ...(selected.processPid ? { processPid: selected.processPid, processComm: selected.processComm } : {}) };
         }
     }
     catch {
@@ -3951,6 +3974,23 @@ async function resolveTmuxPaneProgram(pane, requireArgs = false, refreshTty = fa
     }
     return { command, source: 'tmux-pane', rawArgs: null };
 }
+async function observeProgramNativeIdentity(agent, program) {
+    const fromArgs = agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null;
+    const config = agent ? getPluginNativeIdentityConfig(agent.slug) : undefined;
+    if (config && program?.processPid) {
+        const proof = await readNativeProcessIdentity(program.processPid, config, program.processComm, program.rawArgs ?? undefined);
+        if (proof.outcome === 'ambiguous' || proof.outcome === 'process_changed' || proof.outcome === 'unconfirmed')
+            return { nativeId: null, source: null,
+                failure: proof.outcome === 'ambiguous' ? 'NATIVE_SESSION_IDENTITY_AMBIGUOUS'
+                    : proof.outcome === 'unconfirmed' ? 'NATIVE_SESSION_OWNERSHIP_UNCONFIRMED' : 'NATIVE_SESSION_PROCESS_CHANGED' };
+        if (proof.nativeId) {
+            if (fromArgs && fromArgs !== proof.nativeId)
+                return { nativeId: null, source: null, failure: 'NATIVE_SESSION_IDENTITY_CONFLICT' };
+            return { nativeId: proof.nativeId, source: 'linux-flock-owner', failure: null };
+        }
+    }
+    return { nativeId: fromArgs, source: fromArgs ? 'argv' : null, failure: null };
+}
 /**
  * Extract a human-readable program label from a full command line.
  *

package/dist/server/utils/tmuxProgramDetection.js

@@ -86,7 +86,10 @@ function isDirectProgramMatch(row, command) {
 export function selectTmuxForegroundProgram(input) {
     const helperProgramNames = input.helperProgramNames ?? DEFAULT_TMUX_HELPER_PROGRAM_NAMES;
     const rowsByPid = new Map(input.rows.map((row) => [row.pid, row]));
-    const foregroundRows = input.rows.filter((row) => row.pid !== input.panePid && row.tpgid > 0 && row.pgid === row.tpgid && !row.stat.startsWith('Z'));
+    const foregroundRows = input.rows.filter((row) => (row.pid !== input.panePid || input.includePaneProcess === true
+        && !input.shellNames.has(lowerProgramName(row.comm)?.replace(/^-/, '') ?? '')
+        && !input.shellNames.has(lowerProgramName(input.extractProgramLabel(row.args) ?? row.comm)?.replace(/^-/, '') ?? ''))
+        && row.tpgid > 0 && row.pgid === row.tpgid && !row.stat.startsWith('Z'));
     if (foregroundRows.length === 0) {
         return null;
     }
@@ -130,6 +133,7 @@ export function selectTmuxForegroundProgram(input) {
     return {
         command: selected.command,
         rawArgs: selected.row.args,
+        ...(input.includePaneProcess ? { processPid: selected.row.pid, processComm: selected.row.comm } : {}),
     };
 }
 export function normalizeTmuxMetadataProgram(program, options) {

package/docs/integrations.md

@@ -5,7 +5,9 @@
 插件原生 ID 的前台 argv 回读及服务重启后的运行中 restore 核验修复要求
 **实际运行服务至少 1.4.302**。退出后的重复原生会话检查修复要求
 **实际运行服务至少 1.4.303**。没有 PTY 附着的已登记 tmux 的重复保护修复要求
-**实际运行服务至少 1.4.304**；建议 CLI 与服务同步安装 1.4.304（CLI 最低仍为 1.4.301）。
+**实际运行服务至少 1.4.304**。管理员恢复诊断要求 **CLI / 实际服务均至少 1.4.305**；
+直接 exec 为 pane PID 的原生 argv 核验及可选 Linux 持锁身份要求 **实际服务至少 1.4.306**；
+建议 CLI 与服务同步安装 1.4.306（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
 现有 `--session`、消息投递、任务报告与自动协作入口继续兼容；旧的
 `task create --integration` 仍表示代码集成子任务，新身份使用 `--principal`。
 
@@ -310,9 +312,102 @@ operation/pane，不启动第二个 Agent；进程携带不同 UUID 时继续拒
 仅在确认 tmux 已消失或当前进程排除冲突时继续；未知进程、同 Agent 缺少精确 UUID、
 观察失败均返回 `NATIVE_SESSION_OWNER_UNCONFIRMED`，不以旧 UUID 证明没有冲突。
 
+### 可选的当前进程原生身份（1.4.306）
+
+某些 Agent 首次启动的 argv 没有 UUID。支持以下所有权协议的 Agent 插件可以在
+原 `manifest.json` 中增加一个可选字段；现有别名、恢复命令和其他配置保持原样：
+
+```json
+"nativeIdentity": {
+  "kind": "linux-flock-owner",
+  "directory": "~/.my-agent/native-writer-locks"
+}
+```
+
+这是通用协议声明，TD 没有内置任何私有 Agent 名称或路径。锁目录须是当前用户
+home 内的绝对目录或 `~/` 路径；运行时目录、文件须由当前 UID 拥有，且不能被
+组或其他用户写入。目录/文件本身不能为软链接；目录的真实路径仍须在 home 内。
+锁是 `<native-id>.lock` 普通文件，配套 `<native-id>.owner.json` 至少含
+`{"pid":123,"process_start_id":"linux:456"}`；其他字段不用来证明身份。
+
+插件配置在服务启动时载入。升级、保留原配置并加入声明后，重启实际服务一次；
+Linux 服务 `capabilities.native_identity_linux_flock_owner=true` 表示支持此证据类型，
+不能替代核验插件声明与真实持锁情况。其他平台返回 false，继续使用原 argv 证据。
+不需要改 integration policy、凭据、原启动 argv/model/cwd/包装器或业务任务。
+
+TD 从当前终端的真实前台进程取得 PID（包括直接 exec 后就是 pane PID 的进程），
+再只读核验：该 PID 的 UID、前台进程组、当前 `/proc/<pid>/stat` 启动时间、owner
+文件中的 PID/start_id、它实际打开的 FD 与目录内锁文件的 dev/inode、以及
+`/proc/locks` 的同 PID 独占整文件 `FLOCK ADVISORY WRITE`。读取前后复核进程实例及 argv、
+相关 FD 集合、inode、owner 和内核持锁，任一无法成立都不推导身份。
+owner JSON 读取限 4096 字节、argv 比对限 16384 字节、进程 FD 数量限 4096；不会读会话正文/环境或尝试取得写锁。
+
+仅一个完整匹配的原生 ID 才可用于当前身份：明确持有目标 ID 拒绝重复启动；明确
+持有其他 ID 可以排除该进程。多个持锁 ID、argv 与锁身份矛盾、检查间进程变化
+均继续拒绝。owner 文件存在、PID 存活、旧登记或 hook 历史均不能单独确认身份。
+尚未建立可证明身份、协议不符或读权限不足时仍保留未确认保护；没有声明此字段的
+旧插件继续使用原有 argv 路径。此证据仅支持本机 Linux tmux 进程，不宣称能覆盖
+未登记外部进程、远端 Agent 或其他操作系统。
+
+维护机已用真实隔离 tmux/内核 flock 验证首次启动的 UUID 捕获、直接 exec 的 pane
+PID、同 ID 拒绝/不同 ID 排除、遗留 owner、错误 start_id/PID、inode 替换、没有真实
+持锁、多个 ID 和 argv 冲突。**私有 TraeX 的 1.4.306 身份接入仍需使用方实机复验**。
+原 `startupInput` 仍独立控制首次写入；核验 native ID 不表示输入初始化完成。
+
+### 管理员恢复诊断（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`；306 另含真实前台 `process_pid` 及
+`native_identity_source`（argv / linux-flock-owner / null）。无法观测的值为 null。backend 不存在或仅有旧
+登记仍可通过 tmux 核验；`pane_pid` 是承载 pane 的 PID，不冒充 Agent 前台 PID。
+报告最多保存 128 个阻塞候选；`total_blockers` 保留总数，确定的同 UUID 所有者优先展示。
+
+| reason | 实际证据缺口或冲突 |
+| --- | --- |
+| NATIVE_SESSION_MATCH | 当前前台进程的 argv 或完整持锁证据明确证明目标 UUID |
+| NATIVE_SESSION_IDENTITY_CONFLICT | argv 与完整持锁证据指向不同 UUID |
+| NATIVE_SESSION_IDENTITY_AMBIGUOUS | 当前进程持有多个可证明的原生 UUID |
+| NATIVE_SESSION_PROCESS_CHANGED | 持锁检查间进程实例或所有权证据变化 |
+| NATIVE_SESSION_OWNERSHIP_UNCONFIRMED | 当前打开了原生锁文件，但持锁/owner/inode 证据不能完整成立 |
+| 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`；错误不包含包装器输出、密钥或原始堆栈。
@@ -335,7 +430,12 @@ operation/pane，不启动第二个 Agent；进程携带不同 UUID 时继续拒
 使用方已报告 1.4.303 退出后精确恢复通过，也发现未挂接 PTY 的已登记 tmux 重复保护
 遗漏；维护机已用“旧 UUID C、实际运行 UUID A、无 PTY 附着”的真实隔离 tmux 复现，
 并验证 1.4.304 编译后检查在该状态下拒绝再次启动。
-**1.4.304 的真实 TraeX 重复保护与稳定输入条件仍须使用方实机复验**。
+使用方已报告 1.4.304 在未挂接网页/PTY、旧登记 UUID C 而实际运行 A 的场景下，
+正确拒绝同 UUID 恢复且没有第二个进程。1.4.305 实机诊断已定位四个同 Agent
+无 argv UUID 的候选，另一个候选主进程直接 exec 为 pane PID。使用方提供了当前
+PID/start_id、实际 FD/inode 与内核 flock 一致的私有原生所有权证据；1.4.306 提供
+上述可选通用插件声明，未修改私有 Agent 或放宽未确认保护。
+**1.4.306 的私有 TraeX 持锁身份接入与稳定输入条件仍须使用方实机复验**。
 回读 capabilities 后，应核对原 TD ID、真实 TraeX UUID 与原 argv/cwd/包装器快照，
 并验证 Agent 真正加载原对话。
 先完成测试环境的创建→追问→关联答复，再验重复键、追加咨询、断线重投和精确恢复。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.304",
+  "version": "1.4.306",
   "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.304",
+  "version": "1.4.306",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-7LaEwk0ur5djmnXCjBBkhMPg2z5dB5dcYm7tmh14Pko=",
+  "serverBundleHash": "sha256-X8EpOnbvlZo/rtZ5QLd5zVKFUOFeDkxeqJmY0hUBQnE=",
   "clientBundleHash": "sha256-HOoNMOYhnph9XwUhSYE5W2CdI9Vb4g0c64ubW49LnXE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"