termdock 1.4.312 → 1.4.314

package/dist/server/agent/collaborationTmuxDelivery.js

@@ -1,5 +1,6 @@
 import { plainCollaborationSnapshot } from './collaborationText.js';
 import { normalizePromptForPaste, waitForPromptSubmit } from './promptDelivery.js';
+import { serializeTerminalInput } from './terminalInput.js';
 const TMUX_KEY_NAMES = {
     enter: 'Enter', escape: 'Escape', space: 'Space', left: 'Left', right: 'Right', up: 'Up', down: 'Down',
 };
@@ -31,21 +32,22 @@ async function assertSamePane(run, pane) {
 /** Unique-per-process buffer name so concurrent deliveries to different panes
  *  never share (or clobber) a buffer. */
 let bufferSequence = 0;
-const paneWrites = new Map();
+function paneInputKey(pane) {
+    return `${pane.serverPid}:${pane.sessionId}:${pane.paneId}:${pane.panePid}`;
+}
 /** Serialize TD paste/submit pairs for this exact runtime pane. */
-export function writeCollaborationTmuxPane(run, pane, prompt, stdin) {
-    const key = `${pane.serverPid}:${pane.sessionId}:${pane.paneId}:${pane.panePid}`;
-    const previous = paneWrites.get(key) ?? Promise.resolve();
-    const operation = previous.catch(() => undefined).then(() => writeTmuxPrompt(run, pane, prompt, stdin))
-        .finally(() => { if (paneWrites.get(key) === operation)
-        paneWrites.delete(key); });
-    paneWrites.set(key, operation);
-    return operation;
+export function writeCollaborationTmuxPane(run, pane, prompt, stdin, assertCurrent, progress) {
+    progress?.('queue_wait');
+    return serializeTerminalInput(paneInputKey(pane), () => {
+        progress?.('queue_acquired');
+        return writeTmuxPrompt(run, pane, prompt, stdin, assertCurrent, progress);
+    });
 }
 async function writeTmuxPrompt(run, pane, prompt, 
 /** Body travels on stdin so tmux cannot parse its semicolons/backslashes. */
-stdin) {
+stdin, assertCurrent, progress) {
     await assertSamePane(run, pane);
+    assertCurrent?.();
     // A fixed pane target is independent of the current window, keyboard focus
     // and browser presence. Delivery goes through a named tmux buffer rather
     // than `send-keys -l`: while a pane is in copy-mode, literal bytes are
@@ -66,6 +68,7 @@ stdin) {
     try {
         // Paste once, then send one unbracketed CR after 50ms. No screen parsing,
         // Agent-specific recovery, consumption confirmation or additional Enter.
+        progress?.('paste_attempted');
         await stdin([
             // The body arrives on stdin, not argv: it is user content, and in a
             // `\;` chain argv is a language where `;` and `\` mean something.
@@ -75,8 +78,11 @@ stdin) {
             // for it to rewrite — the flag is insurance, not the mechanism.
             'paste-buffer', '-p', '-r', '-d', '-b', buffer, '-t', pane.paneId,
         ], normalizePromptForPaste(prompt));
+        progress?.('paste_written');
         await waitForPromptSubmit();
         await assertSamePane(run, pane);
+        assertCurrent?.();
+        progress?.('submit_attempted');
         await run([
             // The submit key rides outside the paste block: inside it, an editor
             // inserts a pasted CR as text instead of acting on it. Pasting the bare
@@ -84,6 +90,7 @@ stdin) {
             'set-buffer', '-b', buffer, '--', '\r', ';',
             'paste-buffer', '-d', '-b', buffer, '-t', pane.paneId,
         ]);
+        progress?.('submit_written');
     }
     finally {
         // -d consumed the buffer on the happy path; this sweeps up after a failed
@@ -100,10 +107,14 @@ export async function paneInMode(run, pane) {
  *  unchanged. Named keys only — no freeform keystroke passthrough. Refuses
  *  while the pane is in a mode: there the key would be taken by the mode
  *  handler (Enter in copy-mode exits the user's scroll) rather than the app. */
-export async function sendTmuxPaneKey(run, pane, key) {
+export function sendTmuxPaneKey(run, pane, key, assertCurrent) {
+    return serializeTerminalInput(paneInputKey(pane), () => sendTmuxPaneKeyUnlocked(run, pane, key, assertCurrent));
+}
+async function sendTmuxPaneKeyUnlocked(run, pane, key, assertCurrent) {
     await assertSamePane(run, pane);
     if (await paneInMode(run, pane))
         throw new Error('TMUX_PANE_IN_MODE');
+    assertCurrent?.();
     await run(['send-keys', '-t', pane.paneId, TMUX_KEY_NAMES[key]]);
 }
 /** Current pane screen text (viewport), identity-checked. */
@@ -116,14 +127,16 @@ export async function captureTmuxPaneText(run, pane, rawOutput = false) {
  *  Enter (the highlighted option). Refuses unless the screen actually shows
  *  an approval prompt: driving a dialog that isn't there would only inject
  *  a stray keystroke into the agent's work. Returns false when no dialog. */
-export async function approveCollaborationDialog(run, pane) {
-    const content = await captureTmuxPaneText(run, pane);
-    if (!detectApprovalDialog(content))
-        return false;
-    // sendTmuxPaneKey refuses in-mode panes, so a dialog-looking screen behind a
-    // user's scroll never turns Enter into copy-mode navigation.
-    await sendTmuxPaneKey(run, pane, 'enter');
-    return true;
+export function approveCollaborationDialog(run, pane, assertCurrent) {
+    return serializeTerminalInput(paneInputKey(pane), async () => {
+        assertCurrent?.();
+        const content = await captureTmuxPaneText(run, pane);
+        if (!detectApprovalDialog(content))
+            return false;
+        // The same input queue covers both the observation and requested key.
+        await sendTmuxPaneKeyUnlocked(run, pane, 'enter', assertCurrent);
+        return true;
+    });
 }
 /** History-inclusive terminal observation, without inferring consumption. */
 export async function captureTmuxPaneHistory(run, pane, lines = 800, rawOutput = false) {

package/dist/server/agent/integrationCli.js

@@ -28,7 +28,10 @@ export const INTEGRATION_HELP = `td integration — local scoped integration adm
     Minimum CLI/running service 1.4.309; capabilities.session_resume_configuration=true.
     Errors: RESUME_CONFIGURATION_CHANGED, EXACT_RESUME_UNSUPPORTED,
     SESSION_GENERATION_MISMATCH, SESSION_OPERATION_IN_PROGRESS, LAUNCHER_UNAVAILABLE.
-  diagnostics <TD-session-id> (read the last restore check; administrator only)
+  diagnostics <TD-session-id> (read stored launch/restore diagnostics; administrator only)
+    1.4.314 adds phase/timestamps, paste/submit write facts and target-change
+    evidence; no argv/environment/credentials or application readiness claim.
+    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)
   revoke <principal-id>
@@ -217,11 +220,13 @@ export async function runIntegrationCollab(command, port, io) {
             return subscribe(socketPath, `/events?${params}`, credential, command.options.timeout ? duration(String(command.options.timeout)) : undefined, io.write);
         }
         if (command.action === 'session') {
+            if (command.operation === 'retry-cold' && capability.session_cold_retry !== true)
+                throw new CollaborationError('SESSION_COLD_RETRY_UNSUPPORTED', 'CLI and running service must support explicit cold retry (minimum 1.4.314)', 409);
             if (command.operation === 'release' && (capability.session_runtime_release !== true || capability.session_lifecycle_generation !== true || capability.stable_session_identity !== true))
                 throw new CollaborationError('SESSION_RELEASE_UNSUPPORTED', 'CLI and running service must support the lifecycle contract (minimum 1.4.309)', 409);
-            const route = command.operation === 'create' ? '/sessions' : `/sessions/${encodeURIComponent(command.target)}${['restore', 'release'].includes(command.operation) ? `/${command.operation}` : ''}`;
+            const route = command.operation === 'create' ? '/sessions' : `/sessions/${encodeURIComponent(command.target)}${['restore', 'release', 'retry-cold'].includes(command.operation) ? `/${command.operation}` : ''}`;
             const body = command.operation === 'create' ? { group_id: command.options.group, launch_profile: command.options['launch-profile'], cwd: command.options.cwd, idempotency_key: command.options['idempotency-key'] }
-                : ['restore', 'release'].includes(command.operation) ? { ...(command.operation === 'release' ? { generation: Number(command.options.generation) } : {}), idempotency_key: command.options['idempotency-key'] } : undefined;
+                : ['restore', 'release', 'retry-cold'].includes(command.operation) ? { ...(['release', 'retry-cold'].includes(command.operation) ? { generation: Number(command.options.generation) } : {}), idempotency_key: command.options['idempotency-key'] } : undefined;
             io.write(JSON.stringify(parsed(await request(socketPath, command.operation === 'get' ? 'GET' : 'POST', route, body, headers(credential)))));
             return 0;
         }

package/dist/server/agent/integrationServer.js

@@ -70,7 +70,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/sessions/:id/restore-diagnostics', run(req => { admin(req); return { ...this.sessions.restoreDiagnostics(req.params.id), ...this.sessions.launchDiagnostics(req.params.id) }; }));
         app.get('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return this.sessions.resumeConfiguration(req.params.id); }));
         app.post('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return { session: publicIntegrationSession(await this.sessions.confirmResumeConfiguration(req.params.id, req.body?.generation, req.body?.fingerprint)) }; }));
         app.post('/admin/sessions/:id/startup-input/clear', run(async (req) => {
@@ -197,6 +197,7 @@ export class IntegrationRuntime {
         }));
         app.get('/sessions/:id', run(async (req) => { const p = principal(req); this.authorize(p, 'session.read'); return { session: publicIntegrationSession(await this.sessions.get(p, req.params.id)) }; }));
         app.post('/sessions/:id/restore', run(async (req) => { const p = principal(req); this.authorize(p, 'session.restore'); const session = await this.sessions.restore(p, req.params.id, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
+        app.post('/sessions/:id/retry-cold', run(async (req) => { const p = principal(req); this.authorize(p, 'session.create'); const session = await this.sessions.retryCold(p, req.params.id, req.body?.generation, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
         app.post('/sessions/:id/release', run(async (req) => { const p = principal(req); this.authorize(p, 'session.release'); const session = await this.sessions.release(p, req.params.id, req.body?.generation, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
         app.get('/events', run((req, res) => {
             const p = principal(req);
@@ -225,6 +226,9 @@ export class IntegrationRuntime {
             session_resume_configuration: true, session_lifecycle_min_version: '1.4.309',
             session_startup_input_clear: true, session_startup_input_clear_min_version: '1.4.310',
             agent_launch_process_check: true, agent_launch_process_check_min_version: '1.4.312',
+            terminal_input_runtime_fence: true, terminal_input_runtime_fence_min_version: '1.4.313',
+            session_launch_diagnostics: true, session_launch_diagnostics_min_version: '1.4.314',
+            session_cold_retry: true, session_cold_retry_min_version: '1.4.314',
             integration_policy_update: true,
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',

package/dist/server/agent/integrationSessions.js

@@ -5,6 +5,8 @@ import { atomicJson, integrationError } from './integrationStore.js';
 import { SessionLifecycleCoordinator, assertMessageRuntime, assertReleaseFacts, assertReleaseGeneration } from './sessionLifecycle.js';
 import { resumeConfigurationFingerprint } from './sessionResumeConfiguration.js';
 import { NativeResumeOwnerError } from './nativeResumeOwner.js';
+import { CollaborationError } from './collaborationProtocol.js';
+import { beginLaunchDiagnostics, launchFailure, launchProgress } from './sessionLaunchDiagnostics.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);
@@ -20,8 +22,9 @@ 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, restore_diagnostics: diagnostics, ...publicRecord } = record;
-    return { ...publicRecord, ...(diagnostics ? { restore_diagnostics_available: true } : {}) };
+    const { profile: _, deadline: _deadline, launch_submitted: _submitted, startup_condition: _condition, restore_diagnostics: diagnostics, launch_diagnostics: launchDiagnostics, launch_diagnostics_history: _history, message_history_seen: _messages, ...publicRecord } = record;
+    return { ...publicRecord, ...(diagnostics ? { restore_diagnostics_available: true } : {}),
+        ...(launchDiagnostics ? { launch_diagnostics_available: true } : {}) };
 }
 export function permittedCwd(profile, cwd) {
     if (typeof cwd !== 'string' || !path.isAbsolute(cwd) || /[\x00-\x1f\x7f]/.test(cwd))
@@ -56,6 +59,7 @@ export class IntegrationSessions {
     listeners = new Set();
     lifecycle = new SessionLifecycleCoordinator();
     mutations = new Map();
+    coldRetries = new Set();
     timers = new Set();
     stopObservation;
     stopDeliveryGuard;
@@ -111,7 +115,9 @@ export class IntegrationSessions {
     }
     saveRecord(record) {
         const before = this.doc.sessions;
-        this.doc.sessions = [...before.filter(s => s.session_id !== record.session_id), structuredClone(record)];
+        const seen = before.find(s => s.session_id === record.session_id)?.message_history_seen;
+        this.doc.sessions = [...before.filter(s => s.session_id !== record.session_id), structuredClone({ ...record,
+                ...(seen ? { message_history_seen: true } : {}) })];
         try {
             this.save();
         }
@@ -154,7 +160,8 @@ export class IntegrationSessions {
         const now = Date.now(), record = { operation_id: randomUUID(), session_id: randomBytes(6).toString('hex'),
             group_id: principal.groupId, principal_id: principal.id, agent_slug: profile.agentSlug, agent_native_session_id: null,
             state: 'starting', generation: 1, runtime_present: null, error_code: null, cwd, launch_profile: profile.id, profile: structuredClone(profile),
-            created_at: now, updated_at: now, deadline: now + this.bindingTimeout, launch_submitted: false };
+            created_at: now, updated_at: now, deadline: now + this.bindingTimeout, launch_submitted: false, message_history_seen: false };
+        record.launch_diagnostics = beginLaunchDiagnostics(record.operation_id, 1, 'cold_start');
         record.startup_input = startupInput(record, now);
         this.doc.requests[request.scoped] = { hash: request.hash, sessionId: record.session_id };
         try {
@@ -166,7 +173,7 @@ export class IntegrationSessions {
         }
         return this.launch(record, false);
     }
-    launch(record, restoring) {
+    launch(record, restoring, retryCold = false) {
         const promise = (async () => {
             try {
                 // Store intent before launching. A failed persistence cannot execute.
@@ -181,17 +188,29 @@ export class IntegrationSessions {
                     catch (error) {
                         // Existing creation supports plugins without an exact resume path.
                         // They remain launchable, but cannot gain a releasable descriptor.
-                        if (restoring || error.code !== 'EXACT_RESUME_UNSUPPORTED')
+                        if (restoring || retryCold || error.code !== 'EXACT_RESUME_UNSUPPORTED')
                             throw error;
                     }
                 }
                 record.launch_submitted = true;
                 this.saveRecord(record);
+                const progress = (phase) => {
+                    const latest = this.doc.sessions.find(s => s.session_id === record.session_id);
+                    if (latest.operation_id !== record.operation_id || latest.generation !== record.generation)
+                        integrationError('SESSION_GENERATION_MISMATCH', 'Launch operation changed during progress recording', 409);
+                    if (latest.launch_diagnostics) {
+                        record.launch_diagnostics = launchProgress(latest.launch_diagnostics, phase);
+                        this.saveRecord({ ...latest, launch_diagnostics: record.launch_diagnostics });
+                    }
+                };
                 const prepared = (binding) => { record.terminal_binding = binding; this.saveRecord(record); };
-                if (restoring)
-                    await this.adapter.restore(record, prepared);
+                if (retryCold)
+                    await this.adapter.retryCold(record, prepared, progress);
+                else if (restoring)
+                    await this.adapter.restore(record, prepared, progress);
                 else
-                    await this.adapter.create(record, prepared);
+                    await this.adapter.create(record, prepared, progress);
+                progress('binding_observe');
                 await this.refresh(record.session_id);
                 this.scheduleRefresh(record);
             }
@@ -199,6 +218,7 @@ export class IntegrationSessions {
                 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',
+                    launch_diagnostics: current.launch_diagnostics ? launchFailure(current.launch_diagnostics, error, typeof code === 'string' ? code : 'SESSION_LAUNCH_FAILED') : undefined,
                     restore_diagnostics: error instanceof NativeResumeOwnerError ? { ...structuredClone(error.diagnostics), operation_id: current.operation_id } : undefined,
                     updated_at: Date.now() });
             }
@@ -216,10 +236,27 @@ export class IntegrationSessions {
         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 });
     }
-    assertRuntimeMessage(id) { assertMessageRuntime(this.doc.sessions.find(s => s.session_id === id)); }
+    launchDiagnostics(id) {
+        const record = this.doc.sessions.find(s => s.session_id === id);
+        if (!record)
+            return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Integration session does not exist', 404);
+        return structuredClone({ launch_diagnostics: record.launch_diagnostics ?? null,
+            launch_diagnostics_history: record.launch_diagnostics_history ?? [] });
+    }
+    assertRuntimeMessage(id) {
+        const record = this.doc.sessions.find(s => s.session_id === id);
+        if (this.coldRetries.has(id) || record?.cold_retry_pending)
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Cold retry must finish or be reconciled before sending', 409);
+        assertMessageRuntime(record);
+        // Durable, conservative latch before admission; even a later enqueue
+        // failure cannot make a previously attempted business request disappear.
+        if (record && !record.message_history_seen)
+            this.saveRecord({ ...record, message_history_seen: true });
+    }
     assertMessageTarget(principal, id) {
         const record = this.doc.sessions.find(s => s.session_id === id && s.group_id === principal.groupId);
-        assertMessageRuntime(record);
+        if (record)
+            this.assertRuntimeMessage(id);
     }
     async mutate(principal, key, input, action) {
         const request = this.request(principal, key, input);
@@ -259,6 +296,74 @@ export class IntegrationSessions {
     async restore(principal, id, key) {
         return this.mutate(principal, key, ['restore', id], () => this.lifecycle.run(id, () => this.restoreOnce(principal, id, key)));
     }
+    async retryCold(principal, id, generation, key) {
+        return this.mutate(principal, key, ['retry-cold', id, generation], () => this.lifecycle.run(id, async () => {
+            const request = this.request(principal, key, ['retry-cold', id, generation]);
+            if (request.previous)
+                return this.replayRequest(principal, id, request.previous);
+            if (!this.adapter.retryCold || !this.adapter.messageHistory)
+                integrationError('SESSION_COLD_RETRY_UNSUPPORTED', 'Runtime adapter does not support verified cold retry', 409);
+            if (this.pending.has(id))
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Launch is in progress', 409);
+            this.coldRetries.add(id);
+            try {
+                const record = await this.get(principal, id);
+                assertReleaseGeneration(record, generation);
+                if (record.cold_retry_pending || record.operation_uncertain)
+                    integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Reconcile prior lifecycle outcome before cold retry', 409);
+                if (record.agent_native_session_id)
+                    integrationError('SESSION_COLD_RETRY_NATIVE_BOUND', 'Use exact native restore for a bound session', 409);
+                if (record.state !== 'failed')
+                    integrationError('SESSION_COLD_RETRY_NOT_FAILED', 'Only failed unbound cold starts can be retried', 409);
+                const history = this.adapter.messageHistory(id);
+                if (history === null)
+                    integrationError('SESSION_MESSAGE_HISTORY_UNCONFIRMED', 'Message history cannot be verified', 409);
+                if (record.message_history_seen || history || this.adapter.pendingMessages?.(id))
+                    integrationError('SESSION_MESSAGE_HISTORY_PRESENT', 'Cold retry refuses any TD business message history or attempted admission', 409);
+                const authorized = principal.launchProfiles.find(p => p.id === record.launch_profile);
+                if (!authorized)
+                    integrationError('LAUNCH_PROFILE_DENIED', 'Original launch profile is no longer authorized', 403);
+                permittedCwd(authorized, record.cwd);
+                permittedCwd(record.profile, record.cwd);
+                if (!record.resume_configuration_fingerprint)
+                    integrationError('RESUME_CONFIGURATION_UNCONFIRMED', 'Administrator must confirm the launcher/plugin fingerprint', 409);
+                if (record.resume_configuration_fingerprint !== await resumeConfigurationFingerprint(record, this.adapter))
+                    integrationError('RESUME_CONFIGURATION_CHANGED', 'Launcher/plugin configuration changed', 409);
+                const observed = await this.adapter.inspect(record);
+                if (!record.terminal_binding || !observed.exists || observed.running || !observed.shell || observed.nativeId)
+                    integrationError('SESSION_COLD_RETRY_RUNTIME_UNCONFIRMED', 'Retry requires the exact original, exited foreground shell', 409);
+                record.launch_diagnostics_history = [...(record.launch_diagnostics_history ?? []), ...(record.launch_diagnostics ? [record.launch_diagnostics] : [])].slice(-16);
+                record.generation = generation + 1;
+                record.operation_id = randomUUID();
+                record.state = 'starting';
+                record.error_code = null;
+                record.cold_retry_pending = true;
+                record.cold_retry_count = (record.cold_retry_count ?? 0) + 1;
+                record.runtime_present = true;
+                record.launch_submitted = false;
+                record.updated_at = Date.now();
+                record.deadline = Date.now() + this.bindingTimeout;
+                record.restore_diagnostics = undefined;
+                record.startup_input = startupInput(record, Date.now());
+                record.launch_diagnostics = beginLaunchDiagnostics(record.operation_id, record.generation, 'cold_retry');
+                this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
+                try {
+                    this.saveRecord(record);
+                }
+                catch (error) {
+                    delete this.doc.requests[request.scoped];
+                    throw error;
+                }
+                const result = await this.launch(record, false, true);
+                result.cold_retry_pending = false;
+                this.saveRecord(result);
+                return result;
+            }
+            finally {
+                this.coldRetries.delete(id);
+            }
+        }));
+    }
     async restoreOnce(principal, id, idempotencyKey) {
         const request = this.request(principal, idempotencyKey, ['restore', id]);
         if (request.previous)
@@ -268,6 +373,8 @@ export class IntegrationSessions {
         let releaseNative;
         try {
             const record = await this.get(principal, id);
+            if (record.cold_retry_pending)
+                integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Reconcile the cold retry before native restore', 409);
             if (!record.agent_native_session_id)
                 integrationError('NATIVE_SESSION_ID_MISSING', 'An exact native session binding is required', 409);
             // Recheck the current grant and actual directories; restore uses the
@@ -310,6 +417,8 @@ export class IntegrationSessions {
             record.deadline = Date.now() + this.bindingTimeout;
             record.updated_at = Date.now();
             record.restore_diagnostics = undefined;
+            record.launch_diagnostics_history = [...(record.launch_diagnostics_history ?? []), ...(record.launch_diagnostics ? [record.launch_diagnostics] : [])].slice(-16);
+            record.launch_diagnostics = beginLaunchDiagnostics(record.operation_id, record.generation, 'native_restore');
             if (!record.startup_input_disabled && !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());
@@ -443,6 +552,8 @@ export class IntegrationSessions {
         const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
         if (!record)
             return;
+        if (record.cold_retry_pending && (this.lifecycle.active(id) || this.pending.has(id)))
+            return;
         if (record.state === 'released' || record.state === 'releasing' || record.operation_uncertain) {
             if (this.lifecycle.active(id))
                 return;
@@ -483,8 +594,10 @@ export class IntegrationSessions {
             if (JSON.stringify(current) !== JSON.stringify(record))
                 return;
             const code = error.code;
-            if (record.state !== 'failed' || record.error_code !== code)
-                this.saveRecord({ ...record, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_OBSERVATION_FAILED', updated_at: Date.now() });
+            const errorCode = typeof code === 'string' ? code : 'SESSION_OBSERVATION_FAILED';
+            if (record.state !== 'failed' || record.error_code !== errorCode)
+                this.saveRecord({ ...record, state: 'failed', error_code: errorCode,
+                    launch_diagnostics: record.launch_diagnostics ? launchFailure(record.launch_diagnostics, error, errorCode) : undefined, updated_at: Date.now() });
             return;
         }
         const next = { ...record, runtime_present: this.adapter.runtimePresent ? await this.adapter.runtimePresent(record) : observed.exists };
@@ -521,6 +634,27 @@ export class IntegrationSessions {
             next.state = 'failed';
             next.error_code = 'SESSION_BINDING_TIMEOUT';
         }
+        if (record.cold_retry_pending) {
+            if (next.state === 'ready')
+                next.cold_retry_pending = false;
+            else if (record.terminal_binding && observed.exists && !observed.running && observed.shell && !observed.nativeId) {
+                next.state = 'failed';
+                next.error_code = 'SESSION_COLD_RETRY_INTERRUPTED';
+                next.cold_retry_pending = false;
+                if (next.launch_diagnostics)
+                    next.launch_diagnostics = launchProgress(next.launch_diagnostics, 'reconciled_shell');
+            }
+            else if (!observed.exists) {
+                next.state = 'failed';
+                next.error_code = 'SESSION_COLD_RETRY_RUNTIME_UNCONFIRMED';
+            }
+        }
+        if (next.launch_diagnostics) {
+            next.launch_diagnostics = { ...next.launch_diagnostics, runtime_exists: observed.exists };
+            if (next.state === 'failed' && next.error_code && (record.state !== 'failed' || record.error_code !== next.error_code)) {
+                next.launch_diagnostics = launchFailure(next.launch_diagnostics, new CollaborationError(next.error_code, '', 409), next.error_code);
+            }
+        }
         if (next.startup_input && next.startup_input.state !== 'observed') {
             const condition = next.startup_condition ?? next.profile.startupInput;
             let matched = false;

package/dist/server/agent/promptDelivery.js

@@ -1,3 +1,4 @@
+import { serializeTerminalInput } from './terminalInput.js';
 /**
  * Fold a prompt into the single-channel form both tmux and agent TUIs expect:
  * every line break becomes one CR (commits a line inside the editor, and is
@@ -16,18 +17,21 @@ export function waitForPromptSubmit() {
 export function buildBracketedPasteBytes(prompt) {
     return `\x1b[200~${normalizePromptForPaste(prompt)}\x1b[201~`;
 }
-const promptWrites = new WeakMap();
 /** Serialize TD prompt pairs per PTY. Success only records terminal writes. */
-export function writeBracketedPrompt(target, prompt) {
-    const previous = promptWrites.get(target) ?? Promise.resolve();
-    const operation = previous.catch(() => undefined).then(async () => {
+export function writeBracketedPrompt(target, prompt, assertCurrent, progress) {
+    progress?.('queue_wait');
+    return serializeTerminalInput(target, async () => {
+        progress?.('queue_acquired');
+        assertCurrent?.();
+        progress?.('paste_attempted');
         target.write(buildBracketedPasteBytes(prompt));
+        progress?.('paste_written');
         await waitForPromptSubmit();
+        assertCurrent?.();
+        progress?.('submit_attempted');
         target.write('\r');
-    }).finally(() => { if (promptWrites.get(target) === operation)
-        promptWrites.delete(target); });
-    promptWrites.set(target, operation);
-    return operation;
+        progress?.('submit_written');
+    });
 }
 /**
  * Process detection and hook events are independent Agent signals. A target is

package/dist/server/agent/sessionLaunchDiagnostics.js

@@ -0,0 +1,26 @@
+import { CollaborationError } from './collaborationProtocol.js';
+import { TerminalInputTargetChangedError } from './terminalInput.js';
+export function beginLaunchDiagnostics(operation_id, generation, kind) {
+    const now = Date.now();
+    return { operation_id, generation, kind, phase: 'configuration', updated_at: now,
+        error_code: null, reason_code: null, paste: 'not_attempted', submit: 'not_attempted',
+        runtime_exists: null, steps: [{ phase: 'configuration', at: now }] };
+}
+export function launchProgress(current, phase) {
+    const now = Date.now();
+    return { ...current, phase, updated_at: now, steps: [...current.steps, { phase, at: now }].slice(-24),
+        paste: phase === 'paste_attempted' ? 'attempted' : phase === 'paste_written' ? 'write_returned' : current.paste,
+        submit: phase === 'submit_attempted' ? 'attempted' : phase === 'submit_written' ? 'write_returned' : current.submit };
+}
+/** Error text/stdout/argv are never copied into durable diagnostics. */
+export function launchFailure(current, error, error_code) {
+    const value = error;
+    const standard = new Set(['ENOENT', 'EACCES', 'EPERM', 'EIO', 'ETIMEDOUT', 'EPIPE', 'ECONNRESET',
+        'TMUX_PANE_CHANGED', 'TMUX_PANE_IN_MODE', 'SESSION_REMOVED', 'SHELL_BACKEND_CHANGED']);
+    const reason_code = error instanceof TerminalInputTargetChangedError ? error.code
+        : error instanceof CollaborationError && /^[A-Z][A-Z0-9_]{0,79}$/.test(error.code) ? 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 TerminalInputTargetChangedError ? { target_change: error.evidence } : {}) };
+}

package/dist/server/agent/terminalInput.js

@@ -0,0 +1,44 @@
+/** One TD input operation per actual transport, independent of application state. */
+const objectInputs = new WeakMap();
+const namedInputs = new Map();
+export function serializeTerminalInput(target, action) {
+    return typeof target === 'string' ? serializeInQueue(namedInputs, target, action)
+        : serializeInQueue(objectInputs, target, action);
+}
+function serializeInQueue(store, target, action) {
+    const previous = store.get(target) ?? Promise.resolve();
+    const operation = previous.catch(() => undefined).then(action).finally(() => {
+        if (store.get(target) === operation)
+            store.delete(target);
+    });
+    store.set(target, operation);
+    return operation;
+}
+export class TerminalInputTargetChangedError extends Error {
+    evidence;
+    code = 'TERMINAL_INPUT_TARGET_CHANGED';
+    constructor(evidence) {
+        super('TERMINAL_INPUT_TARGET_CHANGED');
+        this.evidence = evidence;
+    }
+}
+/** Clearing a one-time launch check does not change the runtime generation. */
+export function captureTerminalInputGuard(current, expected = current()) {
+    return () => {
+        if (current() !== expected)
+            throw new TerminalInputTargetChangedError();
+    };
+}
+/** Await the actual write instead of leaving detached timers after reporting success. */
+export async function waitAndWriteTerminalInput(input) {
+    for (let attempt = 0;; attempt++) {
+        input.assertCurrent();
+        const ready = await input.ready(attempt);
+        input.assertCurrent();
+        if (ready) {
+            await input.write();
+            return;
+        }
+        await new Promise(resolve => setTimeout(resolve, 250));
+    }
+}