termdock 1.4.313 → 1.4.315

package/dist/server/agent/integrationSessions.js

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
+import { cleanMemberName } from './collaborationRoutes.js';
 import path from 'node:path';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 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 +23,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, close_intent: _closeIntent, ...publicRecord } = record;
+    return { ...publicRecord, close_pending: !!_closeIntent, ...(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 +60,8 @@ export class IntegrationSessions {
     listeners = new Set();
     lifecycle = new SessionLifecycleCoordinator();
     mutations = new Map();
+    coldRetries = new Set();
+    closingOperations = new Set();
     timers = new Set();
     stopObservation;
     stopDeliveryGuard;
@@ -80,7 +86,7 @@ export class IntegrationSessions {
             record.runtime_present ??= null;
         }
         for (const record of this.doc.sessions)
-            if (['starting', 'restoring', 'binding_pending'].includes(record.state) || record.state === 'releasing' || record.startup_input?.state === 'pending')
+            if (['starting', 'restoring', 'binding_pending'].includes(record.state) || ['releasing', 'closing'].includes(record.state) || record.startup_input?.state === 'pending')
                 this.scheduleRefresh(record);
         // A pre-restart partial match cannot prove continuity of the live screen.
         for (const record of this.doc.sessions)
@@ -111,7 +117,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 +162,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 +175,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 +190,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 +220,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 +238,33 @@ 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.closingOperations.has(id))
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Session close preflight is in progress', 409);
+        if (this.coldRetries.has(id) || record?.cold_retry_pending)
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Cold retry must finish or be reconciled before sending', 409);
+        if (record?.state === 'closing' && !record.operation_uncertain)
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Session close is in progress', 409);
+        if (record?.close_intent)
+            integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Close outcome requires reconciliation', 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 +304,76 @@ 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);
+            this.assertManagementSettled(this.lookup(principal, id));
+            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);
+                this.assertManagementSettled(record);
+                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 +383,9 @@ export class IntegrationSessions {
         let releaseNative;
         try {
             const record = await this.get(principal, id);
+            this.assertManagementSettled(record);
+            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 +428,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());
@@ -339,6 +459,7 @@ export class IntegrationSessions {
             const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
             if (!record)
                 return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Recovery record does not exist', 404);
+            this.assertManagementSettled(record);
             assertReleaseGeneration(record, generation);
             if (this.pending.has(id) || record.operation_uncertain || ['starting', 'restoring', 'binding_pending', 'releasing'].includes(record.state)) {
                 integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the current lifecycle operation before clearing startup input conditions', 409);
@@ -360,6 +481,7 @@ export class IntegrationSessions {
             const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
             if (!record)
                 return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Recovery record does not exist', 404);
+            this.assertManagementSettled(record);
             assertReleaseGeneration(record, generation);
             if (this.pending.has(id) || ['starting', 'restoring', 'binding_pending', 'releasing'].includes(record.state))
                 integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the current operation before confirming compatibility', 409);
@@ -372,16 +494,145 @@ export class IntegrationSessions {
             return record;
         });
     }
+    assertManagementSettled(record) {
+        if (record.state === 'closed')
+            integrationError('SESSION_CLOSED', 'Explicitly closed sessions cannot be restored or restarted', 409);
+        if (record.state === 'closing' && !record.operation_uncertain)
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Session close is in progress', 409);
+        if (record.close_intent || record.state === 'closing')
+            integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Reconcile the pending close before any lifecycle operation', 409);
+        if (record.rename_pending)
+            integrationError('SESSION_RENAME_SYNC_PENDING', 'Read session get to reconcile the pending name update', 409);
+    }
+    assertManagementIdle(record) {
+        if (this.pending.has(record.session_id) || record.cold_retry_pending || record.operation_uncertain || ['starting', 'restoring', 'binding_pending', 'releasing', 'closing'].includes(record.state)) {
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the current lifecycle operation first', 409);
+        }
+    }
+    async rename(principal, id, generation, value, key) {
+        if (typeof value !== 'string')
+            integrationError('INVALID_NAME', 'name must be non-empty text up to 80 characters');
+        const name = cleanMemberName(value);
+        if (!name)
+            integrationError('INVALID_NAME', 'name must be non-empty text up to 80 characters');
+        return this.mutate(principal, key, ['rename', id, generation, name], () => this.lifecycle.run(id, async () => {
+            const request = this.request(principal, key, ['rename', id, generation, name]);
+            if (request.previous)
+                return this.replayRequest(principal, id, request.previous);
+            if (!this.adapter.rename)
+                integrationError('SESSION_RENAME_UNSUPPORTED', 'Runtime adapter does not support renaming', 409);
+            const record = await this.get(principal, id);
+            assertReleaseGeneration(record, generation);
+            if (record.close_intent || record.rename_pending)
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the pending management operation first', 409);
+            this.assertManagementIdle(record);
+            await this.adapter.prepareRename?.(record);
+            record.name = name;
+            record.name_updated_at = Date.now();
+            record.updated_at = record.name_updated_at;
+            record.generation = generation + 1;
+            record.name_generation = record.generation;
+            record.name_operation_id = record.operation_id;
+            record.rename_pending = true;
+            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;
+            }
+            try {
+                await this.adapter.rename(record);
+                record.rename_pending = false;
+                this.saveRecord(record);
+            }
+            catch { /* Durable intent is retried by get/restart; no runtime is created. */ }
+            return this.lookup(principal, id);
+        }));
+    }
+    async closeSession(principal, id, generation, key) {
+        return this.mutate(principal, key, ['close', id, generation], () => this.lifecycle.run(id, async () => {
+            const request = this.request(principal, key, ['close', id, generation]);
+            if (request.previous)
+                return this.replayRequest(principal, id, request.previous);
+            this.closingOperations.add(id);
+            try {
+                if (!this.adapter.prepareClose || !this.adapter.closeRuntime || !this.adapter.runtimePresent)
+                    integrationError('SESSION_CLOSE_UNSUPPORTED', 'Runtime adapter does not support closing', 409);
+                const record = await this.get(principal, id);
+                assertReleaseGeneration(record, generation);
+                if (record.close_intent || record.rename_pending)
+                    integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Read session get to reconcile prior management intent', 409);
+                this.assertManagementIdle(record);
+                if (record.state === 'closed') {
+                    if (await this.adapter.runtimePresent(record))
+                        integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Unexpected runtime exists for a closed record', 409);
+                    this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
+                    try {
+                        this.save();
+                    }
+                    catch (error) {
+                        delete this.doc.requests[request.scoped];
+                        throw error;
+                    }
+                    return record;
+                }
+                if (this.adapter.pendingMessages?.(id))
+                    integrationError('SESSION_PENDING_MESSAGES', 'Pending messages must be resolved before closing', 409);
+                const target = await this.adapter.prepareClose(record);
+                record.operation_id = randomUUID();
+                record.generation = generation + 1;
+                record.state = 'closing';
+                record.close_intent = { operation_id: record.operation_id, target };
+                record.error_code = null;
+                record.operation_uncertain = false;
+                record.updated_at = Date.now();
+                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;
+                }
+                try {
+                    await this.adapter.closeRuntime(record, false);
+                    if (await this.adapter.runtimePresent(record))
+                        integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Runtime removal cannot be confirmed', 409);
+                    record.state = 'closed';
+                    record.runtime_present = false;
+                    record.terminal_binding = null;
+                    record.startup_input = undefined;
+                    record.close_intent = undefined;
+                }
+                catch (error) {
+                    record.state = 'failed';
+                    record.operation_uncertain = true;
+                    record.runtime_present = null;
+                    record.error_code = typeof error.code === 'string' ? error.code : 'SESSION_CLOSE_FAILED';
+                }
+                record.updated_at = Date.now();
+                this.saveRecord(record);
+                return record;
+            }
+            finally {
+                this.closingOperations.delete(id);
+            }
+        }));
+    }
     async release(principal, id, generation, key) {
         return this.mutate(principal, key, ['release', id, generation], () => this.lifecycle.run(id, async () => {
             const request = this.request(principal, key, ['release', id, generation]);
             if (request.previous)
                 return this.replayRequest(principal, id, request.previous);
+            this.assertManagementSettled(this.lookup(principal, id));
             if (!this.adapter.release || !this.adapter.runtimePresent)
                 integrationError('SESSION_RELEASE_UNSUPPORTED', 'Runtime adapter does not support release', 409);
             if (this.pending.has(id))
                 integrationError('SESSION_OPERATION_IN_PROGRESS', 'Launch is in progress', 409);
             const record = await this.get(principal, id);
+            this.assertManagementSettled(record);
             assertReleaseGeneration(record, generation);
             if (record.state !== 'released') {
                 assertReleaseFacts(record, await this.adapter.inspect(record));
@@ -443,6 +694,54 @@ export class IntegrationSessions {
         const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
         if (!record)
             return;
+        if (record.rename_pending) {
+            if (this.lifecycle.active(id))
+                return;
+            try {
+                await this.lifecycle.run(id, async () => {
+                    if (!this.adapter.rename)
+                        return;
+                    await this.adapter.rename(record);
+                    if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+                        return;
+                    record.rename_pending = false;
+                    this.saveRecord(record);
+                });
+            }
+            catch { /* Keep the persisted intent for a later get/restart. */ }
+            return;
+        }
+        if (record.state === 'closed' || record.state === 'closing' || record.close_intent) {
+            if (this.lifecycle.active(id))
+                return;
+            try {
+                if (record.state !== 'closed') {
+                    if (!this.adapter.closeRuntime)
+                        integrationError('SESSION_CLOSE_UNSUPPORTED', 'Close reconciliation is unavailable', 409);
+                    await this.adapter.closeRuntime(record, true);
+                }
+                if (!this.adapter.runtimePresent || await this.adapter.runtimePresent(record))
+                    integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Runtime exists for a closed or closing session', 409);
+                const next = { ...record, state: 'closed', runtime_present: false, terminal_binding: null, close_intent: undefined,
+                    operation_uncertain: false, error_code: null, startup_input: undefined };
+                if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+                    return;
+                if (JSON.stringify(next) !== JSON.stringify(record))
+                    this.saveRecord({ ...next, updated_at: Date.now() });
+            }
+            catch (error) {
+                if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+                    return;
+                // Keep closed terminal, and keep unresolved intent fenced. Never kill on refresh.
+                const next = { ...record, runtime_present: null, operation_uncertain: true,
+                    error_code: typeof error.code === 'string' ? error.code : 'OPERATION_OUTCOME_UNCONFIRMED' };
+                if (JSON.stringify(next) !== JSON.stringify(record))
+                    this.saveRecord({ ...next, updated_at: Date.now() });
+            }
+            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 +782,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 +822,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;
@@ -554,6 +876,12 @@ export class IntegrationSessions {
         const existing = this.doc.sessions.find(record => record.session_id === id);
         if (!existing)
             return null;
+        if (this.closingOperations.has(id))
+            return { allowed: false, reason: 'SESSION_OPERATION_IN_PROGRESS' };
+        if (existing.state === 'closed')
+            return { allowed: false, reason: 'SESSION_CLOSED' };
+        if (existing.close_intent || existing.state === 'closing')
+            return { allowed: false, reason: 'SESSION_OPERATION_IN_PROGRESS' };
         if (existing.state === 'released' || existing.state === 'releasing' || existing.operation_uncertain)
             return { allowed: false, reason: existing.state === 'released' ? 'SESSION_RELEASED' : 'SESSION_OPERATION_IN_PROGRESS' };
         if (!existing.startup_input)

package/dist/server/agent/integrationStore.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { CollaborationError } from './collaborationProtocol.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'];
+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); }
 export function atomicJson(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });

package/dist/server/agent/promptDelivery.js

@@ -18,13 +18,19 @@ export function buildBracketedPasteBytes(prompt) {
     return `\x1b[200~${normalizePromptForPaste(prompt)}\x1b[201~`;
 }
 /** Serialize TD prompt pairs per PTY. Success only records terminal writes. */
-export function writeBracketedPrompt(target, prompt, assertCurrent) {
+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');
+        progress?.('submit_written');
     });
 }
 /**

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/sessionLifecycle.js

@@ -50,6 +50,10 @@ export function assertReleaseFacts(record, facts) {
 export function assertMessageRuntime(record) {
     if (!record)
         return;
+    if (record.state === 'closed')
+        fail('SESSION_CLOSED', 'Session was explicitly closed; it cannot be sent to or restored');
+    if (record.state === 'closing')
+        fail('SESSION_OPERATION_IN_PROGRESS', 'Session close is in progress');
     if (record.state === 'released')
         fail('SESSION_RELEASED', 'Runtime was released; explicitly restore this session before sending');
     if (record.state === 'releasing')