termdock 1.4.345 → 1.4.347

package/dist/server/agent/collaborationCli.js

@@ -69,6 +69,9 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
     消息历史只覆盖仍保留记录；不存在的 after-id 返回 MESSAGE_NOT_FOUND，不能据此声称历史完整。
   session create --group <id> --launch-profile <id> --cwd <absolute-path> --idempotency-key <key>
   session get <id> | session restore <id> --idempotency-key <key>
+    启动一致性/原shell有限核验需服务1.4.346：session_launch_reload_fence/session_shell_startup_wait。
+    只等同一承载的前台shell证明，不判断应用input-ready，不自动重试失败启动。
+    独立Agent数据目录可由管理员在profile配置nativeIdentity；需Linux及session_profile_native_identity。
     get 可对账 tmux recovery 后仍指向旧 pane 的 IntegrationSession；需 Linux 服务1.4.328、session_recovery_binding_reconcile=true。
     仅凭成功恢复记录、唯一归属/承载与当前精确 native writer-lock 证明更新 binding/generation；证据不足仍拒绝。
     不另起 Agent、不重放已写入消息；成功后以 get 返回的 generation/terminal_binding 为准。

package/dist/server/agent/collaborationStore.js

@@ -467,6 +467,12 @@ export class CollaborationStore {
         const group = this.getGroup(groupId);
         if (!group || group.deleted || !context || typeof context !== 'object')
             return;
+        if (this.applyContext(group, context))
+            this.persist();
+    }
+    applyContext(group, context) {
+        if (group.deleted)
+            return false;
         let changed = false;
         const rules = context.instructions;
         if (rules && validRevision(rules) && typeof rules.text === 'string' && Buffer.byteLength(rules.text) <= 8192
@@ -488,8 +494,7 @@ export class CollaborationStore {
                 delete group.roles[id];
             changed = true;
         }
-        if (changed)
-            this.persist();
+        return changed;
     }
     removeSession(sessionId) {
         const count = this.document.groups.filter(group => group.sessionIds.includes(sessionId)).length;
@@ -712,12 +717,17 @@ export class CollaborationStore {
         if (existing && (!existing.federated || (existing.deleted && (!group.deleted || existing.updatedAt >= group.updatedAt))
             || (!group.deleted && existing.updatedAt > group.updatedAt)))
             return;
-        const incoming = group.deleted && existing && !existing.deleted
-            ? { ...group, updatedAt: Math.max(group.updatedAt, existing.updatedAt + 1) } : group;
-        const priorContext = existing ? this.context(group.id) : undefined;
-        this.document.groups = [...this.document.groups.filter((item) => item.id !== group.id), { ...incoming }];
-        if (priorContext)
-            this.mergeContext(group.id, priorContext);
+        // Directory refreshes repeat the same group every few seconds. Compare
+        // content as well as the timestamp: equal timestamps can carry real edits.
+        if (existing && stableJson(existing) === stableJson(group))
+            return;
+        const incoming = structuredClone(group.deleted && existing && !existing.deleted
+            ? { ...group, updatedAt: Math.max(group.updatedAt, existing.updatedAt + 1) } : group);
+        if (existing)
+            this.applyContext(incoming, this.context(group.id));
+        if (existing && stableJson(existing) === stableJson(incoming))
+            return;
+        this.document.groups = [...this.document.groups.filter((item) => item.id !== group.id), incoming];
         if (group.deleted)
             this.document.messages = this.document.messages.filter((item) => item.groupId !== group.id);
         this.persist();
@@ -861,16 +871,34 @@ export class CollaborationStore {
         const message = this.getMessage(id);
         if (!message)
             throw new CollaborationError('MESSAGE_NOT_FOUND', 'Message not found or no longer retained', 404);
-        const replies = this.document.messages.filter(reply => reply.replyTo === id
-            && (message.toPrincipalId ? reply.integrationOrigin?.integrationId === message.toPrincipalId : reply.fromSessionId === message.toSessionId)
+        return this.messageReceipt(message, this.document.messages.filter(reply => reply.replyTo === id), raw);
+    }
+    /** Reconcile message events in one pass without rescanning the complete
+     * history for every receipt or formatting snapshots which events omit. */
+    snapshotMessagesWithReceipts(groups) {
+        const replies = new Map();
+        for (const message of this.document.messages)
+            if (message.replyTo) {
+                const list = replies.get(message.replyTo) ?? [];
+                list.push(message);
+                replies.set(message.replyTo, list);
+            }
+        return structuredClone(this.document.messages.filter(message => groups.has(message.groupId)).map(message => {
+            const { snapshot: _, ...receipt } = this.messageReceipt(message, replies.get(message.id) ?? [], false, false);
+            return { message, receipt };
+        }));
+    }
+    messageReceipt(message, candidates, raw, includeSnapshot = true) {
+        const id = message.id;
+        const replies = candidates.filter(reply => (message.toPrincipalId ? reply.integrationOrigin?.integrationId === message.toPrincipalId : reply.fromSessionId === message.toSessionId)
             && (message.integrationOrigin ? reply.toPrincipalId === message.integrationOrigin.integrationId : reply.toSessionId === message.fromSessionId));
         const diagnostic = this.diagnostic(id);
-        const facts = terminalMessage(message, raw);
+        const facts = terminalMessage(includeSnapshot ? message : { ...message, snapshot: null }, raw);
         return { message_id: id, thread_id: message.threadId, status: facts.status, queued_at: message.status === 'stored' ? null : message.createdAt, stored_at: message.storedAt ?? null,
             from_principal_id: message.integrationOrigin?.integrationId ?? null, to_principal_id: message.toPrincipalId ?? null,
             delivered_at: facts.deliveredAt, expires_at: message.expiresAt ?? null,
             failure_reason: message.failureReason ?? null, delivery_semantics: message.status === 'stored' ? 'durable_storage' : facts.deliverySource ?? (facts.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'),
-            snapshot: message.snapshot ? (raw ? message.snapshot : plainCollaborationSnapshot(message.snapshot)) : null,
+            snapshot: includeSnapshot && message.snapshot ? (raw ? message.snapshot : plainCollaborationSnapshot(message.snapshot)) : null,
             delivery: { status: facts.status,
                 stage: message.status === 'stored' ? 'stored' : facts.deliveredAt !== null ? 'terminal_written' : diagnostic?.route_state === 'identity-mismatch' || diagnostic?.last_error === 'TMUX_PANE_CHANGED' ? 'blocked' : diagnostic?.remote_received_at ? 'remote_received' : 'queued',
                 ...(!diagnostic?.route_diagnostics && diagnostic?.last_error === 'TMUX_PANE_CHANGED' ? { requires_confirmation: true } : {}),

package/dist/server/agent/integrationCli.js

@@ -78,6 +78,16 @@ export const INTEGRATION_HELP = `td integration — local scoped integration adm
     Prior versions cannot reconstruct missing launch evidence retroactively.
   create --file <policy.json> --credential-file <private-output.json>
   update --file <policy.json> (same identity/group; preserves the credential)
+    1.4.346 launch profiles may declare nativeIdentity={kind:"linux-flock-owner",
+    directory:"{cwd}/.agent-home/cli/thread-writer-locks"} for an isolated Agent home.
+    Linux only; session_profile_native_identity=true required on the running service.
+    This configures read-only identity proof; it does not set Agent environment,
+    install hooks, create directories, or modify old session snapshots.
+    session_launch_reload_fence/session_shell_startup_wait (minimum 1.4.346)
+    protect launch tokens during disk reload and wait at most 5s for the same
+    unique foreground shell. This does not wait for application input-ready.
+    diagnostics may include shell_check (reason/pane/pgid/tpgid/samples/waited_ms),
+    never shell argv/output. A timed-out launch does not automatically retry.
   revoke <principal-id>
 Credentials are saved as a private file and never printed. Workers set
 TERMDOCK_INTEGRATION_CREDENTIAL_FILE, then use td collab --principal <id> …
@@ -248,6 +258,8 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
                 throw new Error('update requires only --file');
             const policy = JSON.parse(fs.readFileSync(options['--file'], 'utf8'));
             const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
+            if (policy.launchProfiles?.some((profile) => profile.nativeIdentity !== undefined) && capabilities.session_profile_native_identity !== true)
+                throw new CollaborationError('SESSION_PROFILE_NATIVE_IDENTITY_UNSUPPORTED', 'CLI and Linux service must support profile native identity (minimum 1.4.346)', 409);
             if (capabilities.integration_policy_update !== true || policy.launchProfiles?.some((profile) => profile.startupInput !== undefined) && capabilities.startup_input_conditions !== true)
                 throw new CollaborationError('STARTUP_INPUT_CONDITION_UNSUPPORTED', 'Running service does not support this policy update', 409);
             write(JSON.stringify(parsed(await request(socketPath, 'POST', `/admin/principals/${encodeURIComponent(policy.id)}/policy`, policy, headers(undefined, adminToken)))));
@@ -257,9 +269,11 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
             if (!options['--file'] || !options['--credential-file'] || Object.keys(options).length !== 2)
                 throw new Error('create requires --file and --credential-file');
             const policy = JSON.parse(fs.readFileSync(options['--file'], 'utf8'));
-            if (policy.launchProfiles?.some((profile) => profile.startupInput !== undefined)) {
+            if (policy.launchProfiles?.some((profile) => profile.startupInput !== undefined || profile.nativeIdentity !== undefined)) {
                 const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
-                if (capabilities.startup_input_conditions !== true)
+                if (policy.launchProfiles.some((profile) => profile.nativeIdentity !== undefined) && capabilities.session_profile_native_identity !== true)
+                    throw new CollaborationError('SESSION_PROFILE_NATIVE_IDENTITY_UNSUPPORTED', 'CLI and Linux service must support profile native identity (minimum 1.4.346)', 409);
+                if (policy.launchProfiles.some((profile) => profile.startupInput !== undefined) && capabilities.startup_input_conditions !== true)
                     throw new CollaborationError('STARTUP_INPUT_CONDITION_UNSUPPORTED', 'Running service does not support startup input conditions', 409);
             }
             const destination = path.resolve(options['--credential-file']);

package/dist/server/agent/integrationServer.js

@@ -29,6 +29,8 @@ export class IntegrationRuntime {
     streams = new Set();
     sent = new Map();
     syncing = false;
+    dirtySources = new Set(['messages', 'tasks', 'sessions']);
+    syncedGroups = '';
     retry;
     releaseBatchFile;
     releaseBatchOperations = [];
@@ -57,14 +59,17 @@ export class IntegrationRuntime {
                 throw error;
         }
         this.stops.push(options.messages.registerRuntimeGuard(id => this.sessions.assertRuntimeMessage(id)));
-        const changed = () => { try {
-            this.sync();
-        }
-        catch (error) {
-            this.failStreams(error);
-            this.scheduleRetry();
-        } };
-        this.stops.push(options.messages.subscribe(changed), options.taskStore.subscribe(changed), this.sessions.subscribe(changed));
+        const changed = (source) => () => {
+            this.dirtySources.add(source);
+            try {
+                this.sync();
+            }
+            catch (error) {
+                this.failStreams(error);
+                this.scheduleRetry();
+            }
+        };
+        this.stops.push(options.messages.subscribe(changed('messages')), options.taskStore.subscribe(changed('tasks')), this.sessions.subscribe(changed('sessions')));
         const app = express();
         app.use(express.json({ limit: '2mb' }));
         app.use((req, res, next) => {
@@ -144,7 +149,7 @@ export class IntegrationRuntime {
         app.post('/admin/principals/:id/policy', run(req => { admin(req); if (req.body?.id !== req.params.id)
             integrationError('INVALID_INTEGRATION_POLICY', 'Policy identity must match the requested identity'); this.group(req.body?.groupId); this.store.update(req.body); return { ok: true, id: req.params.id }; }));
         app.post('/admin/principals/:id/revoke', run(req => { admin(req); this.store.revoke(req.params.id); return { ok: true }; }));
-        app.get('/capabilities', run(req => { const p = principal(req); return { ...this.capabilities(), principal: { id: p.id, group_id: p.groupId, permissions: p.permissions, launch_profiles: p.launchProfiles.map(profile => ({ id: profile.id, agent_slug: profile.agentSlug, cwd_roots: profile.cwdRoots, startup_input_condition: !!profile.startupInput })) } }; }));
+        app.get('/capabilities', run(req => { const p = principal(req); return { ...this.capabilities(), principal: { id: p.id, group_id: p.groupId, permissions: p.permissions, launch_profiles: p.launchProfiles.map(profile => ({ id: profile.id, agent_slug: profile.agentSlug, cwd_roots: profile.cwdRoots, startup_input_condition: !!profile.startupInput, native_identity_scope: !!profile.nativeIdentity })) } }; }));
         app.get('/tasks', run(req => { const p = principal(req); this.authorize(p, 'task.read', req.query.group); return { tasks: options.tasks.list(p.groupId, null, req.query.purpose) }; }));
         app.get('/tasks/:id', run(async (req) => { const p = principal(req); this.taskPermission(p, req.params.id, 'task.read'); return { task: await options.tasks.get(req.params.id, null) }; }));
         app.post('/tasks', run(async (req) => {
@@ -299,6 +304,9 @@ export class IntegrationRuntime {
             terminal_input_runtime_fence: true, terminal_input_runtime_fence_min_version: '1.4.313',
             agent_launch_generation_consistency: true, agent_launch_generation_consistency_min_version: '1.4.322',
             terminal_input_check_diagnostics: true,
+            session_launch_reload_fence: true, session_launch_reload_fence_min_version: '1.4.346',
+            session_shell_startup_wait: true, session_shell_startup_wait_min_version: '1.4.346',
+            session_profile_native_identity: process.platform === 'linux', session_profile_native_identity_min_version: '1.4.346',
             session_launch_diagnostics: true, session_launch_diagnostics_min_version: '1.4.314',
             session_cold_retry: true, session_cold_retry_min_version: '1.4.314',
             session_rename: true, session_rename_min_version: '1.4.315',
@@ -458,11 +466,25 @@ export class IntegrationRuntime {
         if (this.syncing)
             return;
         this.syncing = true;
+        let sources = new Set();
         try {
             const groups = new Set(this.store.policies().filter(p => !p.revoked).map(p => p.groupId)), updates = [];
-            if (!groups.size)
+            const groupVersion = JSON.stringify([...groups].sort());
+            // Newly granted groups need a complete source reconciliation, including
+            // retained facts that predate the grant. Never advance dirty state until
+            // the durable event append succeeds.
+            if (groupVersion !== this.syncedGroups)
+                for (const source of ['messages', 'tasks', 'sessions'])
+                    this.dirtySources.add(source);
+            sources = this.dirtySources;
+            this.dirtySources = new Set();
+            if (!sources.size)
+                return;
+            if (!groups.size) {
+                this.syncedGroups = groupVersion;
                 return;
-            for (const task of this.options.taskStore.snapshot())
+            }
+            for (const task of sources.has('tasks') ? this.options.taskStore.snapshot() : [])
                 if (groups.has(task.groupId)) {
                     for (const event of task.events)
                         updates.push({ sourceKey: `task:${task.id}:${event.id}`, sourceVersion: '1', eventId: event.id, event: {
@@ -482,31 +504,30 @@ export class IntegrationRuntime {
                                 task_id: task.id, attempt_id: delivery.attemptId, message_id: delivery.messageId, source: 'system', payload: { delivery }
                             } });
                 }
-            for (const message of this.options.messages.snapshotMessages())
-                if (groups.has(message.groupId)) {
-                    const link = message.metadata?.termdockTask;
-                    const context = { group_id: message.groupId, task_id: link?.taskId ?? null, attempt_id: link?.attemptId ?? null,
-                        reply_to_event_id: link?.replyToEventId ?? null, message_id: message.id, source: message.integrationOrigin ? 'integration' : message.fromSessionId ? 'member' : 'system',
-                        actor: message.integrationOrigin ? { integration_id: message.integrationOrigin.integrationId } : message.fromSessionId ? { session_id: message.fromSessionId } : null,
-                        external_actor: message.integrationOrigin?.externalActor ?? null };
-                    updates.push({ sourceKey: `message:${message.id}`, sourceVersion: '1', event: { ...context,
-                            kind: message.kind === 'reply' ? 'message.reply' : 'message.queued', created_at: message.createdAt,
-                            payload: { message_id: message.id, thread_id: message.threadId, reply_to: message.replyTo ?? null,
-                                from_session_id: message.fromSessionId, to_session_id: message.toPrincipalId ? null : message.toSessionId,
-                                to_principal_id: message.toPrincipalId ?? null, integration_origin: message.integrationOrigin ?? null,
-                                response_kind: message.responseKind ?? null, stored_at: message.storedAt ?? null,
-                                content: message.content, metadata: message.metadata ?? null } } });
-                    const { snapshot: _, ...receipt } = this.options.messages.receipt(message.id);
-                    updates.push({ sourceKey: `message-status:${message.id}`, sourceVersion: JSON.stringify(receipt), event: {
-                            ...context, kind: 'message.delivery', created_at: message.deliveredAt ?? message.createdAt, payload: { receipt }
-                        } });
-                }
-            for (const session of this.sessions.snapshot())
+            for (const { message, receipt } of sources.has('messages') ? this.options.messages.snapshotMessagesWithReceipts(groups) : []) {
+                const link = message.metadata?.termdockTask;
+                const context = { group_id: message.groupId, task_id: link?.taskId ?? null, attempt_id: link?.attemptId ?? null,
+                    reply_to_event_id: link?.replyToEventId ?? null, message_id: message.id, source: message.integrationOrigin ? 'integration' : message.fromSessionId ? 'member' : 'system',
+                    actor: message.integrationOrigin ? { integration_id: message.integrationOrigin.integrationId } : message.fromSessionId ? { session_id: message.fromSessionId } : null,
+                    external_actor: message.integrationOrigin?.externalActor ?? null };
+                updates.push({ sourceKey: `message:${message.id}`, sourceVersion: '1', event: { ...context,
+                        kind: message.kind === 'reply' ? 'message.reply' : 'message.queued', created_at: message.createdAt,
+                        payload: { message_id: message.id, thread_id: message.threadId, reply_to: message.replyTo ?? null,
+                            from_session_id: message.fromSessionId, to_session_id: message.toPrincipalId ? null : message.toSessionId,
+                            to_principal_id: message.toPrincipalId ?? null, integration_origin: message.integrationOrigin ?? null,
+                            response_kind: message.responseKind ?? null, stored_at: message.storedAt ?? null,
+                            content: message.content, metadata: message.metadata ?? null } } });
+                updates.push({ sourceKey: `message-status:${message.id}`, sourceVersion: JSON.stringify(receipt), event: {
+                        ...context, kind: 'message.delivery', created_at: message.deliveredAt ?? message.createdAt, payload: { receipt }
+                    } });
+            }
+            const sessions = sources.has('sessions') ? this.sessions.snapshot() : [];
+            for (const session of sessions)
                 if (groups.has(session.group_id))
                     updates.push({ sourceKey: `session:${session.session_id}`, sourceVersion: JSON.stringify(publicIntegrationSession(session)), event: {
                             group_id: session.group_id, kind: `session.${session.state}`, created_at: session.updated_at, source: 'system', actor: { integration_id: session.principal_id }, payload: { session: publicIntegrationSession(session) }
                         } });
-            for (const session of this.sessions.snapshot())
+            for (const session of sessions)
                 if (groups.has(session.group_id) && session.name_updated_at)
                     updates.push({
                         sourceKey: `session-name:${session.session_id}`, sourceVersion: JSON.stringify([session.name, session.name_updated_at, session.name_generation]), event: {
@@ -516,9 +537,17 @@ export class IntegrationRuntime {
                     });
             updates.sort((a, b) => a.event.created_at - b.event.created_at);
             this.store.append(updates);
+            this.syncedGroups = groupVersion;
+        }
+        catch (error) {
+            for (const source of sources)
+                this.dirtySources.add(source);
+            throw error;
         }
         finally {
             this.syncing = false;
+            if (this.dirtySources.size)
+                this.scheduleRetry();
         }
     }
     failStreams(error) {

package/dist/server/agent/integrationSessions.js

@@ -68,6 +68,8 @@ export class IntegrationSessions {
     stopDeliveryGuard;
     observing = false;
     observeAgain = false;
+    observationTimer;
+    stopped = false;
     constructor(file, adapter, bindingTimeout = 120000) {
         this.file = file;
         this.adapter = adapter;
@@ -94,7 +96,22 @@ export class IntegrationSessions {
             if (record.startup_input && record.startup_input.state !== 'observed')
                 record.startup_input.matched_since = null;
         this.stopDeliveryGuard = adapter.registerDeliveryGuard?.(id => this.deliveryReadiness(id));
-        this.stopObservation = adapter.subscribe(() => { void this.refreshAll().catch(() => { }); });
+        this.stopObservation = adapter.subscribe(() => this.scheduleObservation());
+    }
+    scheduleObservation() {
+        if (this.stopped)
+            return;
+        if (this.observing) {
+            this.observeAgain = true;
+            return;
+        }
+        if (this.observationTimer)
+            return;
+        this.observationTimer = setTimeout(() => {
+            this.observationTimer = undefined;
+            void this.refreshAll().catch(() => { });
+        }, 250);
+        this.observationTimer.unref();
     }
     scheduleRefresh(record) {
         for (const deadline of new Set([record.deadline, ...(record.startup_input ? [record.startup_input.deadline] : [])])) {
@@ -974,18 +991,29 @@ export class IntegrationSessions {
             this.observeAgain = true;
             return;
         }
+        if (this.observationTimer) {
+            clearTimeout(this.observationTimer);
+            this.observationTimer = undefined;
+        }
         this.observing = true;
+        this.observeAgain = false;
         try {
-            do {
-                this.observeAgain = false;
-                for (const record of this.snapshot())
-                    await this.refresh(record.session_id);
-            } while (this.observeAgain);
+            for (const record of this.snapshot())
+                await this.refresh(record.session_id);
         }
         finally {
             this.observing = false;
+            if (this.observeAgain)
+                this.scheduleObservation();
         }
     }
-    close() { this.stopObservation(); this.stopDeliveryGuard?.(); for (const timer of this.timers)
-        clearTimeout(timer); }
+    close() {
+        this.stopped = true;
+        this.stopObservation();
+        this.stopDeliveryGuard?.();
+        if (this.observationTimer)
+            clearTimeout(this.observationTimer);
+        for (const timer of this.timers)
+            clearTimeout(timer);
+    }
 }

package/dist/server/agent/integrationShellWait.js

@@ -0,0 +1,33 @@
+import { CollaborationError } from './collaborationProtocol.js';
+export class IntegrationShellWaitError extends CollaborationError {
+    shellEvidence;
+    constructor(code, shellEvidence) {
+        super(code, 'The original runtime did not prove a unique foreground shell before launch', 409);
+        this.shellEvidence = shellEvidence;
+    }
+}
+const samePane = (a, b) => a.serverPid === b.serverPid && a.sessionId === b.sessionId && a.paneId === b.paneId && a.panePid === b.panePid;
+/** Wait for kernel/process evidence, never a prompt, fixed startup sleep, or
+ * application readiness. This observes one runtime and never sends input. */
+export async function waitForIntegrationShell(input) {
+    const now = input.now ?? Date.now, started = now();
+    const pause = input.pause ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    let pinned = input.expected ?? null, samples = 0;
+    for (;;) {
+        const observation = await input.observe();
+        samples++;
+        const evidence = { samples, waited_ms: now() - started,
+            reason: observation.reason, binding: observation.binding, pgid: observation.pgid, tpgid: observation.tpgid };
+        if (!observation.binding || pinned && !samePane(pinned, observation.binding)) {
+            throw new IntegrationShellWaitError('SESSION_IDENTITY_MISMATCH', evidence);
+        }
+        pinned ??= observation.binding;
+        if (observation.agent)
+            throw new IntegrationShellWaitError('SESSION_TARGET_NOT_SHELL', evidence);
+        if (observation.confirmed)
+            return pinned;
+        if (now() - started >= (input.timeoutMs ?? 5000))
+            throw new IntegrationShellWaitError('SESSION_TARGET_NOT_SHELL', evidence);
+        await pause(Math.min(100, (input.timeoutMs ?? 5000) - (now() - started)));
+    }
+}

package/dist/server/agent/integrationStore.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { CollaborationError } from './collaborationProtocol.js';
+import { resolveProfileNativeIdentity } from './nativeProcessIdentity.js';
 export const INTEGRATION_PROTOCOL = 1;
 export const INTEGRATION_OPERATIONS = ['message.send', 'message.read', 'task.read', 'task.create', 'task.configure', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore', 'session.release', 'session.rename', 'session.close'];
 export function integrationError(code, message, status = 400) { throw new CollaborationError(code, message, status); }
@@ -54,6 +55,9 @@ export function validatePolicy(value) {
             integrationError('INVALID_INTEGRATION_POLICY', 'resumeArgv requires one {sessionId} and one {launchArgs}; --last is forbidden');
         if (!Array.isArray(profile.cwdRoots) || !profile.cwdRoots.length || profile.cwdRoots.some(root => typeof root !== 'string' || !path.isAbsolute(root) || /[\x00-\x1f\x7f]/.test(root)))
             integrationError('INVALID_INTEGRATION_POLICY', 'cwdRoots must be absolute paths');
+        if (profile.nativeIdentity !== undefined && profile.cwdRoots.some(root => !resolveProfileNativeIdentity(profile.nativeIdentity, root))) {
+            integrationError('INVALID_INTEGRATION_POLICY', 'nativeIdentity must be an explicit owned-home writer-lock directory or a safe {cwd}/ relative template');
+        }
         if (profile.startupInput !== undefined) {
             const condition = profile.startupInput;
             const validTerms = (terms) => Array.isArray(terms) && terms.length <= 16
@@ -148,18 +152,19 @@ export class IntegrationStore {
             integrationError('INTEGRATION_PERMISSION_DENIED', 'Operation is outside the integration grant', 403);
     }
     append(updates) {
-        const next = structuredClone(this.doc);
-        let changed = false;
+        // Most reconciliations repeat already-journaled facts. Do not copy the
+        // retained event history until the first actual source-version change.
+        let next;
         for (const update of updates) {
-            if (next.sources[update.sourceKey] === update.sourceVersion)
+            if ((next ?? this.doc).sources[update.sourceKey] === update.sourceVersion)
                 continue;
+            next ??= structuredClone(this.doc);
             const group = update.event.group_id, sequence = (next.sequences[group] ?? 0) + 1;
             next.events.push({ ...update.event, event_id: update.eventId ?? randomUUID(), sequence, cursor: this.cursor(group, sequence) });
             next.sequences[group] = sequence;
             next.sources[update.sourceKey] = update.sourceVersion;
-            changed = true;
         }
-        if (!changed)
+        if (!next)
             return;
         const counts = new Map();
         next.events = next.events.reverse().filter(event => {

package/dist/server/agent/nativeProcessIdentity.js

@@ -14,6 +14,27 @@ export function nativeIdentityDirectory(config) {
     const directory = path.resolve(expanded), relative = path.relative(os.homedir(), directory);
     return relative && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative) ? directory : null;
 }
+/** Administrator-declared profile scope, never inferred from process env.
+ * {cwd} is permitted only as a leading directory anchor and cannot escape it. */
+export function resolveProfileNativeIdentity(config, cwd) {
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        return null;
+    const value = config;
+    if (value.kind !== 'linux-flock-owner' || typeof value.directory !== 'string'
+        || Object.keys(value).some(key => !['kind', 'directory'].includes(key)))
+        return null;
+    let directory = value.directory;
+    if (directory.startsWith('{cwd}/')) {
+        const suffix = directory.slice(6);
+        if (/[{}]/.test(suffix) || suffix.split(/[\\/]/).includes('..') || !path.isAbsolute(cwd))
+            return null;
+        directory = path.join(cwd, suffix);
+    }
+    else if (/[{}]/.test(directory))
+        return null;
+    const normalized = nativeIdentityDirectory({ kind: value.kind, directory });
+    return normalized ? { kind: 'linux-flock-owner', directory: normalized } : null;
+}
 const unavailable = { nativeId: null, outcome: 'unavailable' };
 function processStat(text, pid) {
     const close = text.lastIndexOf(')'), open = text.indexOf('(');

package/dist/server/agent/sessionLaunchDiagnostics.js

@@ -1,5 +1,6 @@
 import { CollaborationError } from './collaborationProtocol.js';
 import { TerminalInputTargetChangedError } from './terminalInput.js';
+import { IntegrationShellWaitError } from './integrationShellWait.js';
 export function beginLaunchDiagnostics(operation_id, generation, kind) {
     const now = Date.now();
     return { operation_id, generation, kind, phase: 'configuration', updated_at: now,
@@ -22,5 +23,6 @@ export function launchFailure(current, error, error_code) {
             : typeof value?.code === 'string' && standard.has(value.code) ? value.code
                 : typeof value?.message === 'string' && standard.has(value.message) ? value.message : 'UNCLASSIFIED_LAUNCH_ERROR';
     return { ...current, updated_at: Date.now(), error_code, reason_code,
+        ...(error instanceof IntegrationShellWaitError ? { shell_check: structuredClone(error.shellEvidence) } : {}),
         ...(error instanceof TerminalInputTargetChangedError ? { target_change: error.evidence } : {}) };
 }

package/dist/server/agent/sessionLaunchState.js

@@ -6,6 +6,7 @@ export function mergeSessionLaunchState(candidate, current, change) {
         return current ? { ...candidate,
             agentLaunchGeneration: current.agentLaunchGeneration ?? null,
             agentLaunchCheck: current.agentLaunchCheck ?? null,
+            agentNativeIdentity: current.agentNativeIdentity ?? null,
         } : candidate;
     if (!current || (current.agentLaunchGeneration ?? null) !== change.expectedGeneration
         || (current.agentLaunchCheck?.id ?? null) !== change.expectedCheckId) {
@@ -16,5 +17,38 @@ export function mergeSessionLaunchState(candidate, current, change) {
             check_phase: 'launch_state_commit', checked_at: Date.now(),
         });
     }
-    return { ...candidate, agentLaunchGeneration: change.generation, agentLaunchCheck: change.check };
+    return { ...candidate, agentLaunchGeneration: change.generation, agentLaunchCheck: change.check,
+        agentNativeIdentity: change.nativeIdentity === undefined ? current.agentNativeIdentity ?? null : change.nativeIdentity };
+}
+/** A file watcher can finish reading an old snapshot after an in-memory launch
+ * or deletion. It must not revert server-owned fields or resurrect that ID. */
+export function mergeReloadedSessionState(disk, beforeRead, current) {
+    const before = new Map(beforeRead.map(record => [record.sessionId, record]));
+    const live = new Map(current.map(record => [record.sessionId, record]));
+    const result = [];
+    const seen = new Set();
+    for (const candidate of disk) {
+        const id = candidate.sessionId, now = live.get(id), old = before.get(id);
+        if (seen.has(id) || old && !now)
+            continue;
+        seen.add(id);
+        result.push(now ? JSON.stringify(now) !== JSON.stringify(old) ? now
+            : mergeSessionLaunchState(candidate, now) : candidate);
+    }
+    for (const record of current) {
+        if (!seen.has(record.sessionId) && (JSON.stringify(record) !== JSON.stringify(before.get(record.sessionId))
+            || record.agentLaunchGeneration || record.agentNativeIdentity))
+            result.push(record);
+    }
+    return result;
+}
+/** Serialize durable global snapshots, taking a fresh value when each write
+ * acquires the queue. A delayed old rename must not overwrite a later launch. */
+export function createSessionStateWriter(current, write) {
+    let pending = Promise.resolve();
+    return () => {
+        const next = pending.catch(() => undefined).then(() => write(structuredClone(current())));
+        pending = next;
+        return next;
+    };
 }

package/dist/server/routes/terminal.js

@@ -4,7 +4,7 @@ import { isConfirmedEmptyTmuxServer } from '../utils/tmuxEmptyServerProbe.js';
 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 { nativeIdentityDirectory, readNativeProcessIdentity, resolveProfileNativeIdentity } from '../agent/nativeProcessIdentity.js';
 import { closeSessionRuntime, foregroundProcessInstance, processStartIdentity } from '../agent/sessionManagement.js';
 import { releaseSessionRuntime } from '../agent/sessionLifecycle.js';
 import { resumeConfigurationFingerprint } from '../agent/sessionResumeConfiguration.js';
@@ -59,7 +59,8 @@ import { assessAgentResourceBudget, collectHostResourceSnapshot, configuredAgent
 import { AutomationStore, normalizeAutomationSchedule } from '../agent/automationStore.js';
 import { writeBracketedPrompt, canDeliverPromptToAgent } from '../agent/promptDelivery.js';
 import { captureTerminalInputGuard, captureRuntimeInputGuard, waitAndWriteTerminalInput } from '../agent/terminalInput.js';
-import { mergeSessionLaunchState } from '../agent/sessionLaunchState.js';
+import { createSessionStateWriter, mergeReloadedSessionState, mergeSessionLaunchState } from '../agent/sessionLaunchState.js';
+import { waitForIntegrationShell, IntegrationShellWaitError } from '../agent/integrationShellWait.js';
 import { agentLaunchBlockReason, normalizeAgentLaunchCheck } from '../agent/agentLaunchCheck.js';
 import { prepareSupervisionEnable } from '../utils/enableSupervision.js';
 import { buildServerHealthState, dismissServerHealth } from '../utils/serverHealth.js';
@@ -531,12 +532,14 @@ async function migrateFromClientStatesFile() {
         return null;
     }
 }
-async function loadGlobalSessionStateFromDisk() {
+async function loadGlobalSessionStateFromDisk(reload = false) {
+    const beforeRead = structuredClone(globalSessionState.sessions);
     try {
         const data = await readJsonFileIfExists(GLOBAL_SESSION_STATE_FILE);
         if (data) {
+            const sessions = deduplicateGlobalSessions((data.sessions || []).map(s => normalizePersistedClientSession(s)).filter((s) => s !== null));
             globalSessionState = {
-                sessions: deduplicateGlobalSessions((data.sessions || []).map(s => normalizePersistedClientSession(s)).filter((s) => s !== null)),
+                sessions: reload ? mergeReloadedSessionState(sessions, beforeRead, globalSessionState.sessions) : sessions,
                 updatedAt: typeof data.updatedAt === 'number' ? data.updatedAt : Date.now(),
             };
             console.log(`[session-persist] Loaded ${globalSessionState.sessions.length} sessions from global state`);
@@ -587,7 +590,7 @@ async function persistTmuxRecoveryState() {
 async function reloadGlobalSessionStateFromDisk(source) {
     try {
         const previous = JSON.stringify(globalSessionState);
-        await loadGlobalSessionStateFromDisk();
+        await loadGlobalSessionStateFromDisk(true);
         const next = JSON.stringify(globalSessionState);
         if (previous === next) {
             return;
@@ -637,12 +640,13 @@ async function watchGlobalSessionStateFile() {
         reportFailure('[session-persist] Failed to watch global state file:', error);
     }
 }
+const writeGlobalSessionState = createSessionStateWriter(() => globalSessionState, snapshot => writeJsonFile(GLOBAL_SESSION_STATE_FILE, snapshot));
 function schedulePersistGlobalState() {
     if (persistGlobalStateTimer)
         clearTimeout(persistGlobalStateTimer);
     persistGlobalStateTimer = setTimeout(() => {
         try {
-            void writeJsonFile(GLOBAL_SESSION_STATE_FILE, globalSessionState).catch((error) => {
+            void writeGlobalSessionState().catch((error) => {
                 console.warn('[session-persist] Failed to persist global state:', getErrorMessage(error));
             });
         }
@@ -657,7 +661,7 @@ async function persistGlobalStateNow(strict = false) {
         persistGlobalStateTimer = null;
     }
     try {
-        await writeJsonFile(GLOBAL_SESSION_STATE_FILE, globalSessionState);
+        await writeGlobalSessionState();
     }
     catch (error) {
         console.warn('[session-persist] Failed to persist global state:', getErrorMessage(error));
@@ -1002,6 +1006,8 @@ function normalizePersistedClientSession(input) {
         agentLaunchCheck: normalizeAgentLaunchCheck(candidate.agentLaunchCheck),
         agentLaunchGeneration: typeof candidate.agentLaunchGeneration === 'string' ? candidate.agentLaunchGeneration
             : normalizeAgentLaunchCheck(candidate.agentLaunchCheck)?.id ?? null,
+        agentNativeIdentity: nativeIdentityDirectory(candidate.agentNativeIdentity)
+            ? { kind: 'linux-flock-owner', directory: nativeIdentityDirectory(candidate.agentNativeIdentity) } : null,
     };
 }
 function generateTmuxSessionName() {
@@ -1485,14 +1491,18 @@ function searchMetadataForBackend(backendSessionId, session) {
         updatedAt: session.lastActivity,
     };
 }
-async function beginAgentLaunchCheck(frontendSessionId, agentSlug, nativeSessionId = null) {
+async function beginAgentLaunchCheck(frontendSessionId, agentSlug, nativeSessionId = null, nativeIdentity) {
     const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
     if (!record)
         throw new Error('SESSION_REMOVED');
     const id = randomUUID();
     const updated = upsertGlobalSessionRecord(record, { expectedGeneration: record.agentLaunchGeneration ?? null,
         expectedCheckId: record.agentLaunchCheck?.id ?? null, generation: id,
-        check: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
+        check: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 },
+        nativeIdentity: nativeIdentity === undefined
+            ? record.agentResume?.slug === agentSlug || collaborationRouting.get(frontendSessionId)?.agentSlug === agentSlug
+                ? record.agentNativeIdentity ?? null : null
+            : nativeIdentity });
     // Capture the guard before persistence yields. The launch command must use
     // this exact generation, even if another launch occurs during an await.
     const assertCurrent = terminalInputGuard(updated);
@@ -1711,7 +1721,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, nativeProcessIdentity = false, freshProcess = false, describeNativeFailure = false) {
+async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane = false, nativeProcessIdentity = false, freshProcess = false, describeNativeFailure = false, identityOverride) {
     if (!binding.tmuxSessionName)
         return { state: 'offline', reason: 'TMUX_BINDING_MISSING' };
     const name = `=${binding.tmuxSessionName}`;
@@ -1737,7 +1747,7 @@ async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane =
         // pane_current_command alone cannot prove an exact resumed conversation.
         const program = await resolveTmuxPaneProgram(pane, true, nativeProcessIdentity || freshProcess);
         const agent = detectAgentFromCommand(program?.rawArgs ?? program?.command ?? '', agentCustomCommands());
-        const identity = nativeProcessIdentity ? await observeProgramNativeIdentity(agent, program)
+        const identity = nativeProcessIdentity ? await observeProgramNativeIdentity(agent, program, identityOverride ?? globalSessionState.sessions.find(record => record.sessionId === binding.sessionId)?.agentNativeIdentity ?? undefined)
             : { nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null, failure: null, source: null };
         if (identity.failure && !describeNativeFailure)
             integrationError(identity.failure === 'NATIVE_SESSION_IDENTITY_CONFLICT'
@@ -1755,7 +1765,7 @@ async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane =
         // pane so a plain shell member is drivable (run/capture are shell ops).
         return selectDrivePane(binding, candidates, layout.activePaneId);
     }
-    return { ...selectCollaborationPane(binding, candidates), candidates };
+    return { ...selectCollaborationPane(binding, candidates), candidates, layout };
 }
 function routeOwnershipConfirmed(frontendSessionId, binding, panes) {
     const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
@@ -2050,6 +2060,37 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
 async function integrationPaneIsIdleShell(pane) {
     return (await inspectIntegrationShell(pane)).confirmed;
 }
+function integrationNativeIdentity(record) {
+    if (!record.profile.nativeIdentity)
+        return undefined;
+    if (process.platform !== 'linux')
+        integrationError('SESSION_PROFILE_NATIVE_IDENTITY_UNSUPPORTED', 'Profile writer-lock identity requires Linux', 409);
+    const config = resolveProfileNativeIdentity(record.profile.nativeIdentity, record.cwd);
+    if (!config)
+        integrationError('INVALID_NATIVE_IDENTITY_CONFIG', 'Stored native identity scope is invalid', 409);
+    return config;
+}
+async function waitForOwnedIntegrationShell(record, expected) {
+    return waitForIntegrationShell({ expected, async observe() {
+            const terminal = integrationTerminalRecord(record);
+            if (!terminal)
+                return { binding: null, confirmed: false, agent: false, reason: 'RUNTIME_NOT_REGISTERED', pgid: null, tpgid: null };
+            const layout = await getTmuxLayout(terminal.tmuxSessionName);
+            if (layout.windows.flatMap(window => window.panes).length !== 1) {
+                return { binding: null, confirmed: false, agent: false, reason: 'MULTIPLE_TERMINAL_PANES', pgid: null, tpgid: null };
+            }
+            const inspected = await inspectCollaborationTmux({ sessionId: record.session_id, backendSessionId: terminal.backendSessionId,
+                mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: null, nativeSessionId: null, pane: expected }, null, true, false, true);
+            const pane = inspected.pane;
+            if (inspected.state !== 'ready' || !pane)
+                return { binding: null, confirmed: false, agent: false,
+                    reason: inspected.reason ?? 'PANE_UNCONFIRMED', pgid: null, tpgid: null };
+            const shell = await inspectIntegrationShell(pane);
+            return { binding: { serverPid: pane.serverPid, sessionId: pane.sessionId, paneId: pane.paneId, panePid: pane.panePid,
+                    agentSlug: '', nativeSessionId: null }, confirmed: shell.confirmed, agent: !!pane.agentSlug,
+                reason: pane.isShell ? shell.failure : 'PANE_NOT_SHELL', pgid: shell.pgid, tpgid: shell.tpgid };
+        } });
+}
 async function inspectIntegrationShell(pane) {
     if (!pane.isShell)
         return { confirmed: false, failure: null, pgid: null, tpgid: null };
@@ -2157,7 +2198,7 @@ async function observeIntegrationCloseTarget(record) {
         if (!record.agent_native_session_id || agent.slug !== record.agent_slug || program?.source !== 'tmux-tty' || !program.processPid) {
             integrationError('SESSION_CLOSE_TARGET_UNCONFIRMED', 'A running Agent requires a live exact native identity', 409);
         }
-        const identity = await observeProgramNativeIdentity(agent, program);
+        const identity = await observeProgramNativeIdentity(agent, program, integrationNativeIdentity(record));
         if (identity.failure || identity.nativeId !== record.agent_native_session_id)
             integrationError('SESSION_IDENTITY_MISMATCH', 'Current Agent native identity differs from the owned record', 409);
         kind = 'agent';
@@ -2246,7 +2287,7 @@ export const integrationSessionAdapter = {
         if (!agent || !command)
             integrationError('EXACT_RESUME_UNSUPPORTED', 'Agent must support exact native recovery', 409);
         return { version: 1, slug: agent.slug, aliases: agent.aliases, capabilities: agent.capabilities ?? [],
-            resume: getPluginResumeConfig(agent.slug) ?? command, nativeIdentity: getPluginNativeIdentityConfig(agent.slug) ?? null };
+            resume: getPluginResumeConfig(agent.slug) ?? command, nativeIdentity: integrationNativeIdentity(record) ?? getPluginNativeIdentityConfig(agent.slug) ?? null };
     },
     async runtimePresent(record) {
         if (integrationTerminalRecord(record))
@@ -2303,13 +2344,13 @@ 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, undefined, false, true);
+        const inspected = await inspectCollaborationTmux(binding, undefined, false, true, false, false, integrationNativeIdentity(record));
         if (inspected.state === 'offline')
             return { exists: false, running: false, shell: false, agentSlug: null, nativeId: null };
         if (inspected.state !== 'ready' || !inspected.pane)
             integrationError('SESSION_IDENTITY_MISMATCH', 'Owned tmux pane cannot be uniquely verified', 409);
         const pane = inspected.pane;
-        const layout = await getTmuxLayout(terminal.tmuxSessionName);
+        const layout = inspected.layout;
         if (layout.windows.flatMap(window => window.panes).length !== 1 || layout.activePaneId !== pane.paneId)
             integrationError('SESSION_IDENTITY_MISMATCH', 'Integration native binding requires the single owned pane', 409);
         const backend = terminal.backendSessionId ? terminalSessions.get(terminal.backendSessionId) : null;
@@ -2443,7 +2484,7 @@ 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 identity = await observeProgramNativeIdentity(agent, program, globalSessionState.sessions.find(record => record.sessionId === candidate.sessionId)?.agentNativeIdentity ?? integrationNativeIdentity(record));
                 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)),
@@ -2512,13 +2553,17 @@ async function launchIntegrationTerminal(record, restoring, prepared, progress,
             mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: null, nativeSessionId: null,
             // A recreated tmux may get a new pane only during explicit exact resume.
             pane: original.exists ? record.terminal_binding ?? null : null }, null, true);
-        if (inspected.state !== 'ready' || !inspected.pane || !await integrationPaneIsIdleShell(inspected.pane))
-            integrationError('SESSION_TARGET_NOT_SHELL', 'Refusing to launch into an unverified shell', 409);
+        if (inspected.state !== 'ready' || !inspected.pane)
+            throw new IntegrationShellWaitError('SESSION_TARGET_NOT_SHELL', {
+                samples: 1, waited_ms: 0, reason: inspected.reason ?? 'PANE_UNCONFIRMED', binding: null, pgid: null, tpgid: null
+            });
         const pane = inspected.pane;
         const pinned = { serverPid: pane.serverPid, sessionId: pane.sessionId,
             paneId: pane.paneId, panePid: pane.panePid, agentSlug: record.agent_slug, nativeSessionId: record.agent_native_session_id };
         progress?.('binding_persist');
         prepared(pinned); // Must persist before the command enters the terminal.
+        progress?.('runtime_shell_wait');
+        await waitForOwnedIntegrationShell(record, pinned);
         collaborationRouting.bind({ sessionId: record.session_id, backendSessionId: opened.terminalSession.sessionId,
             mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: record.agent_slug, nativeSessionId: record.agent_native_session_id, pane: pinned });
         const latest = collaborationStore.getGroup(group.id);
@@ -2540,17 +2585,14 @@ async function launchIntegrationTerminal(record, restoring, prepared, progress,
             await assertIntegrationNativeResumeAvailable(record);
         }
         progress?.('runtime_verify');
-        const shell = await inspectCollaborationTmux({ sessionId: record.session_id, backendSessionId: opened.terminalSession.sessionId,
-            mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: null, nativeSessionId: null, pane: pinned });
-        if (shell.state !== 'ready' || !shell.pane || !await integrationPaneIsIdleShell(shell.pane))
-            integrationError('SESSION_TARGET_NOT_SHELL', 'Owned shell changed before launch', 409);
+        await waitForOwnedIntegrationShell(record, pinned);
         // This owned pane is a verified shell; clear stale rich state before a new
         // process starts, so its new SessionStart must supply the native binding.
         backend.agentSession = null;
         backend.agent = null;
         backend.agentResumeRecovered = false;
         progress?.('launch_intent');
-        const launchGuard = await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null);
+        const launchGuard = await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null, integrationNativeIdentity(record) ?? null);
         await writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring), progress, launchGuard);
         broadcastClientState();
     });
@@ -4532,9 +4574,9 @@ async function resolveTmuxPaneProgram(pane, requireArgs = false, refreshTty = fa
     }
     return { command, source: 'tmux-pane', rawArgs: null };
 }
-async function observeProgramNativeIdentity(agent, program) {
+async function observeProgramNativeIdentity(agent, program, override) {
     const fromArgs = agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null;
-    const config = agent ? getPluginNativeIdentityConfig(agent.slug) : undefined;
+    const config = agent ? override ?? 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')
@@ -4546,7 +4588,11 @@ async function observeProgramNativeIdentity(agent, program) {
                 return { nativeId: null, source: null, failure: 'NATIVE_SESSION_IDENTITY_CONFLICT' };
             return { nativeId: proof.nativeId, source: 'linux-flock-owner', failure: null };
         }
+        if (override)
+            return { nativeId: null, source: null, failure: 'NATIVE_SESSION_OWNERSHIP_UNCONFIRMED' };
     }
+    if (override && agent)
+        return { nativeId: null, source: null, failure: 'NATIVE_SESSION_OWNERSHIP_UNCONFIRMED' };
     return { nativeId: fromArgs, source: fromArgs ? 'argv' : null, failure: null };
 }
 /**

package/docs/integrations.md

@@ -1354,3 +1354,43 @@ flock-owner 身份独立核验出原 agent slug 与原生 UUID。目标元组会
 fail-closed，旧绑定与原消息保留，`session get` 仍报告身份错误；不会按 tmux 名称、PID
 缓存、cwd、argv 中的 resume 参数或显示名猜测认领。此 capability 不新增权限；仅通过
 `session.read` 认证的所属 principal 可触发其自身记录的对账。
+
+## 1.4.346：启动磁盘重载、原 shell 核验与独立原生目录
+
+最低 CLI / 实际服务均为 **1.4.346**。通过所属 principal 的 `capabilities` 回读：
+
+- `session_launch_reload_fence=true`：服务运行期间的磁盘重载保留当前服务生成的 launch token、已解除的一次性 check 和显式原生目录。读取期间新增的会话不会消失，已删除的会话不会由旧读盘复活；全局状态写入串行，并在执行写入时采集当前快照。服务首次启动仍加载磁盘记录。这修复了磁盘 watch 路径绕过元数据 upsert 保护的缺口，不把每一例历史 `TERMINAL_INPUT_TARGET_CHANGED` 都归因为此。
+- `session_shell_startup_wait=true`：启动前先记录唯一原 pane 身份，再最多等待 5 秒核实该 shell 的前台关系和合格 shell 参数。只观察同一 tmux server/session/pane/PID，采样使用新鲜进程证据；承载改变、pane 不唯一或已有 Agent 时拒绝。不输入探针、不清理画面、不重建承载、不发送额外回车，也不把 shell 核验当成应用 input-ready。
+- `session_profile_native_identity=true`：当前仅 Linux 支持 profile 级只读 writer-lock 目录，覆盖该受管会话的插件缺省目录，不改变共享插件配置。三个字段分别有同名 `_min_version` 字段，值为 `1.4.346`。能力支持不等于 principal 已被授予权限。
+
+本机管理员可在现有完整 policy 的目标 `launchProfiles` 中加：
+
+```json
+"nativeIdentity": {
+  "kind": "linux-flock-owner",
+  "directory": "{cwd}/.agent-home/cli/thread-writer-locks"
+}
+```
+
+目录是示例，必须按实际 Agent 的持锁协议填写。支持管理员指定的绝对目录、`~/` 目录，以及仅以前缀 `{cwd}/` 锚定的模板；模板不允许 `..` 或其它变量，解析后的目录须在 TD 服务用户 home 内。调用现有 `td integration update --file <完整policy.json>`，不增加权限、不重建 principal 或凭据。CLI 在旧服务/非 Linux 服务上拒绝该配置，不能静默忽略。原有不配置此项的 profile 保持插件缺省行为。
+
+wrapper 负责实际设置 Agent 自己的数据目录、准备 hooks/参数，并最终运行真正的 Agent；这个字段只声明 TD 的核验目录，不设置环境、不执行脚本、不创建目录，不自动读取 `TRAECLI_HOME` 等私有变量。TD 仍检查目录与文件权限、进程 starttime、前台关系、实际 FD/inode 和当前内核 flock，要求唯一 native UUID。显式 profile 目录不可证明时不降级到 argv/hook/旧 UUID，多个持锁 UUID 仍拒绝。目录语义纳入恢复配置指纹，保存至启动代次；服务重启、metadata 更新、check 解除不会丢失它。
+
+该配置只用于之后创建的 session；旧 session 保留原 profile 快照，policy update 不迁移旧记录或修改运行 Agent。不要为旧未知结果自动 create 新 ID 或 retry-cold。原 UUID 恢复、重复 owner 保护、关闭仍遵守现有身份/代次/幂等门禁；独立数据目录不构成对同 UID 进程的安全隔离。
+
+启动失败管理员用 `td integration diagnostics <原TD-ID>` 回读；shell 等待失败新增 `shell_check={samples,waited_ms,reason,binding,pgid,tpgid}`，不包含 argv/env/终端正文。`SESSION_TARGET_NOT_SHELL` 表示有限核验未通过，不表示 wrapper 已执行；`paste/submit=not_attempted` 与后续 `runtime_present` 现场回读分开保存。失败不自动再次启动，只有符合原 `session retry-cold` 所有条件才可明确重试。
+
+用 stdin 文件给启动命令附带业务 prompt 是接入方的 bootstrap：TD 不为其中业务副作用提供消息幂等或执行确认；无 TD message 历史也不等于没有业务执行。冷启动与精确 resume 应分开处理，恢复时不得重放初始业务文件。host 收取 final/hook receipt 是 host 侧证据，不伪造成 TD 明确 reply。仍只粘贴一次、等待 50ms、写一次 CR。
+
+回归包含确定性交错的旧读盘覆盖/串行写入/删除不复活、同 pane shell 初始化等待与超时/换 pane/已有 Agent 拒绝、CLI 对旧服务拒绝，以及 Linux 真实 tmux/内核 flock 的独立目录核验。私有 TraeX/DevBox 的启动兼容仍需接入方维护窗实机验证；维护机合成测试不冒充该项通过。
+
+## 1.4.347：无变化同步与后台观察的开销
+
+这是服务运行时优化，不增加接口、权限或配置。需要更新实际运行服务到 **1.4.347**；仅安装新 CLI 不会更新已运行进程。
+
+- 跨服务目录重复合并相同群内容时不写盘、不通知事件同步。比较包含内容而非仅时间戳；同时间戳的真实变化仍处理。合并独立群规/角色版本后如有效内容未变也不写盘；有效群更新与保留的新上下文一次持久化。
+- 空事件追加及 source/version 全重复的追加在克隆事件历史之前返回。真实更新继续持久提交，失败保留可重试源版本，不改变事件 ID、顺序、ACK 或保留策略。
+- 事件同步按消息、任务、会话三个变化来源分别扫描；会话通知不再复制消息历史和生成全部消息回执。新授权组及服务重启仍对保留事实完整对账；失败来源继续重试。消息变化时一次建立回复索引，避免每条回执重扫历史；回执仍核验双方身份，并省去事件中不包含的终端快照格式化。这是按来源增量同步，真实变化仍会扫描该来源的保留记录。
+- 终端输出触发的后台会话观察按 250ms 窗口合并；一轮观察期间的新通知安排到后续一轮，不连续抢占。显式 `session get`、生命周期操作及投递前核验保留原路径，不以此窗口判断 Agent 可输入；不延迟业务输入来猜测应用状态。同一次 integration 观察复用其新鲜 tmux layout，下一次观察重新读取，不把缓存用作身份写入凭据。
+
+无删除消息/事件、缩短历史、停用消费者、额外 Enter 或正文重发。`pty_written` 仍只代表终端写入调用完成，不代表应用提交或任务完成。回归包含约 26 MB journal 的空/重复追加零克隆、相同群同步零写入、真实变化/持久化失败重试、授权后历史补收、通知洪峰合并、换 pane/原生身份冲突拒绝。生产 CPU、事件循环延迟和 health 改善须在实际维护窗升级后对比采样，不能用隔离基准代替实机验收。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.345",
+  "version": "1.4.347",
   "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.345",
+  "version": "1.4.347",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-ObG1OGq7e7fMFQmYoPxPp3jRodEusYHulVNa5mT1aW8=",
-  "serverBundleHash": "sha256-Nfa8USqdvNijehQjbAcl1xDcfyRMfMUVkHMqbUgXXAA=",
+  "serverBundleHash": "sha256-FXUdT0eV3/+rgHBnc0Jg9dn2sAb4hcLY83xScGapcKQ=",
   "clientBundleHash": "sha256-kn3Tg+BTj+H4rZe0g9OE5JUEQNsBGiUSGew8Epm5A38=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"