termdock 1.4.305 → 1.4.306

package/dist/server/agent/integrationServer.js

@@ -147,6 +147,7 @@ export class IntegrationRuntime {
             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/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

@@ -46,6 +46,8 @@ function diagnostic(candidate, process, reason) {
     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,
@@ -72,7 +74,7 @@ export async function assertNativeResumeAvailable(target, excludedBackendSession
                 throw new NativeResumeOwnerError('NATIVE_SESSION_ALREADY_RUNNING', blockers);
             }
             if (!process.confirmed)
-                blockers.push(diagnostic(candidate, process, process.shellFailure
+                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'));

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() ?? '') };
@@ -1872,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)
@@ -1938,11 +1946,13 @@ 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 identity = await observeProgramNativeIdentity(agent, program);
                 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),
+                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 };
@@ -3948,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 {
@@ -3962,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

@@ -6,7 +6,8 @@
 **实际运行服务至少 1.4.302**。退出后的重复原生会话检查修复要求
 **实际运行服务至少 1.4.303**。没有 PTY 附着的已登记 tmux 的重复保护修复要求
 **实际运行服务至少 1.4.304**。管理员恢复诊断要求 **CLI / 实际服务均至少 1.4.305**；
-建议 CLI 与服务同步安装 1.4.305（既有接入命令的 CLI 最低仍为 1.4.301）。
+直接 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`。
 
@@ -311,6 +312,48 @@ 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` 表示服务支持持久恢复诊断。
@@ -336,13 +379,18 @@ 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 不存在或仅有旧
+`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 | 当前前台进程明确携带目标 UUID |
+| 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 | 无法可靠核验前台进程 |
@@ -383,9 +431,11 @@ no-op restore 不创建新检查。报告跟随会话保存并可在服务重启
 遗漏；维护机已用“旧 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 阻塞候选诊断与稳定输入条件仍须使用方实机复验**。
+正确拒绝同 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.305",
+  "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.305",
+  "version": "1.4.306",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-XkM6+bMn6xdVpuXe8oaPunofP3J+MgVfh7lwiOhSY4I=",
+  "serverBundleHash": "sha256-X8EpOnbvlZo/rtZ5QLd5zVKFUOFeDkxeqJmY0hUBQnE=",
   "clientBundleHash": "sha256-HOoNMOYhnph9XwUhSYE5W2CdI9Vb4g0c64ubW49LnXE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"