@playcraft/cli 0.1.27 → 0.1.28

package/dist/workspace-runtime/codex/app-server.js

@@ -18,21 +18,32 @@ function asRecord(value) {
         ? value
         : {};
 }
-function waitForChildExit(child) {
-    if (child.exitCode !== null || child.signalCode !== null)
+function waitForChildExit(child, processGroup = false) {
+    if ((child.exitCode !== null || child.signalCode !== null) && child.stdout?.destroyed && child.stderr?.destroyed)
         return Promise.resolve();
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        let drainTimer;
         const done = () => {
             clearTimeout(timer);
+            clearTimeout(drainTimer);
             resolve();
         };
         const timer = setTimeout(() => {
-            if (child.exitCode === null && child.signalCode === null)
+            if (processGroup && child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* The group may have exited already. */ }
+            }
+            else if (child.exitCode === null && child.signalCode === null)
                 child.kill('SIGKILL');
+            drainTimer = setTimeout(() => {
+                child.off('close', done);
+                reject(new Error('codex_stdio_stop_unconfirmed'));
+            }, 3000);
         }, 3_000);
-        child.once('exit', done);
-        if (child.exitCode !== null || child.signalCode !== null)
-            done();
+        // A process exit can precede its final stdout data; close follows the drained pipes.
+        child.once('close', done);
     });
 }
 function spawnCommand(bin) {
@@ -54,6 +65,7 @@ export function createCodexAppServerAdapter(options) {
     let rpc;
     let readyFlag = false;
     let closed = false;
+    let closing;
     let startPromise;
     let catalogDirectory;
     let skillsRestartFailed = false;
@@ -186,8 +198,8 @@ export function createCodexAppServerAdapter(options) {
         if (previous)
             previous.superseded = true;
         readyFlag = false;
-        await previous?.rpc.close();
         await previous?.child.stop();
+        await previous?.rpc.close();
         if (closed)
             throw new Error('codex_not_started');
         rpc = undefined;
@@ -217,8 +229,8 @@ export function createCodexAppServerAdapter(options) {
             skillsRestartFailed = true;
             if (live) {
                 live.superseded = true;
-                await live.rpc.close();
                 await live.child.stop();
+                await live.rpc.close();
             }
             throw new NativePreparationError('workspace_skills_unavailable');
         }
@@ -267,11 +279,15 @@ export function createCodexAppServerAdapter(options) {
                 sandbox_mode: 'danger-full-access',
             }))
                 args.push('-c', `${key}=${JSON.stringify(value)}`);
+            // Prepare isolated Codex profiles as the development identity before replacing the shell.
+            const argv = process.platform === 'linux' && command === '/usr/local/bin/codex'
+                ? ['/usr/bin/bash', '-c', 'umask 077; mkdir -p -- "$CODEX_HOME" && exec "$@"', 'playcraft-codex', command, ...args]
+                : [command, ...args];
             child = await startLauncherProcess({
                 socketPath: launcherSocket,
                 processId: `codex-${randomUUID()}`,
                 runtimeEpoch: executionEpoch,
-                argv: [command, ...args],
+                argv,
                 // The launcher admits the dev home, not the shared /workspaces root.
                 // Each thread supplies its registered workspace separately.
                 cwd: options.config.workspaceMode === 'multi' ? '/home/playcraft-dev' : options.config.workspaceRoot,
@@ -292,7 +308,7 @@ export function createCodexAppServerAdapter(options) {
             await new Promise((resolve, reject) => { local.once('spawn', resolve); local.once('error', reject); });
             child = {
                 pid: local.pid, stdin: local.stdin, stdout: local.stdout, stderr: local.stderr,
-                onExit(listener) { local.once('exit', listener); },
+                onExit(listener) { local.once('close', listener); },
                 async stop() {
                     if (local.exitCode === null && local.signalCode === null) {
                         if (options.processGroup && local.pid) {
@@ -304,7 +320,7 @@ export function createCodexAppServerAdapter(options) {
                         else
                             local.kill('SIGTERM');
                     }
-                    await waitForChildExit(local);
+                    await waitForChildExit(local, options.processGroup);
                 },
             };
         }
@@ -381,8 +397,8 @@ export function createCodexAppServerAdapter(options) {
         }
         catch (error) {
             current.superseded = true;
-            await current.rpc.close();
             await current.child.stop();
+            await current.rpc.close();
             throw error;
         }
     }
@@ -412,9 +428,9 @@ export function createCodexAppServerAdapter(options) {
             startPromise = undefined;
             threads.clear();
             approvals.clear();
-            await previous?.rpc.close().catch(() => undefined);
             if (previous)
                 await previous.child.stop();
+            await previous?.rpc.close().catch(() => undefined);
             executionEpoch += 1;
             skillsRestartFailed = false;
             if (closed)
@@ -611,26 +627,27 @@ export function createCodexAppServerAdapter(options) {
             }));
             return { outcome: 'accepted', approvalId: input.approvalId, turnId: pending.turnId };
         },
-        async close() {
-            if (closed)
-                return;
-            closed = true;
-            readyFlag = false;
-            if (live)
-                live.superseded = true;
-            const current = child;
-            await rpc?.close().catch(() => undefined);
-            rpc = undefined;
-            if (current)
-                await current.stop();
-            child = undefined;
-            live = undefined;
-            await options.modelBroker?.close();
-            if (catalogDirectory)
-                await rm(catalogDirectory, { recursive: true, force: true });
-            for (const directory of coordinatorDirectories.values())
-                await rm(directory, { recursive: true, force: true });
-            coordinatorDirectories.clear();
+        close() {
+            closing ??= (async () => {
+                closed = true;
+                readyFlag = false;
+                if (live)
+                    live.superseded = true;
+                const current = child, currentRpc = rpc;
+                if (current)
+                    await current.stop();
+                await currentRpc?.close().catch(() => undefined);
+                rpc = undefined;
+                child = undefined;
+                live = undefined;
+                await options.modelBroker?.close();
+                if (catalogDirectory)
+                    await rm(catalogDirectory, { recursive: true, force: true });
+                for (const directory of coordinatorDirectories.values())
+                    await rm(directory, { recursive: true, force: true });
+                coordinatorDirectories.clear();
+            })();
+            return closing;
         },
     };
 }

package/dist/workspace-runtime/codex/launcher-client.js

@@ -43,6 +43,8 @@ export async function startLauncherProcess(input) {
     let buffer = '';
     let identity;
     let stopPromise;
+    let finishTransport;
+    const transportClosed = new Promise(resolve => { finishTransport = resolve; });
     const stdin = new Writable({
         write(chunk, _encoding, callback) {
             socket.write(`${JSON.stringify({ action: 'stdin', data: chunk.toString('base64') })}\n`, callback);
@@ -122,6 +124,7 @@ export async function startLauncherProcess(input) {
             stderr.end();
             stdin.destroy();
             exit();
+            finishTransport();
         });
     });
     return {
@@ -149,7 +152,18 @@ export async function startLauncherProcess(input) {
                     while (Date.now() < deadline) {
                         const status = await request(input.socketPath, { ...identity, action: 'status' });
                         if (status.running === false) {
-                            socket.destroy();
+                            let timeout;
+                            try {
+                                await Promise.race([transportClosed, new Promise((_resolve, reject) => {
+                                        timeout = setTimeout(() => {
+                                            socket.destroy();
+                                            reject(new Error('launcher_output_drain_unconfirmed'));
+                                        }, 3000);
+                                    })]);
+                            }
+                            finally {
+                                clearTimeout(timeout);
+                            }
                             return;
                         }
                         await delay(50);

package/dist/workspace-runtime/production/native.js

@@ -1,6 +1,8 @@
 import { join } from 'node:path';
 import { lstat, mkdir } from 'node:fs/promises';
+import { hashOperationPayload, operationScopeKey, productionSessionId, transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
 import { createCodexAppServerAdapter } from '../codex/app-server.js';
+import { ingestCollected, publishSourceEvents, recordNativeEvents } from '../server/dispatch.js';
 import { verifyProductionLease } from './storage.js';
 import { processBirth, stopProductionGroup } from './processes.js';
 import { openDirectoryToDevelopment } from '../workspaces/directory-access.js';
@@ -42,16 +44,74 @@ export async function runProductionNative(state, input, root, record, track) {
             await record(group);
         },
     });
-    track(() => adapter.close());
-    const sessionId = `production-${input.task.attemptId}`;
+    const sessionId = productionSessionId(input.task.attemptId);
+    const prompt = String(input.payload.prompt ?? '');
+    const now = new Date().toISOString();
+    const operation = {
+        operationId: `${input.task.attemptId}:generate`, clientRequestId: `${input.task.attemptId}:generate`,
+        environment: input.task.environment, userId: input.task.userId, workspaceId: input.task.workspaceId,
+        directoryName: input.directoryName, sessionId, kind: 'session.turn', status: 'dispatched',
+        generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+        payloadHash: hashOperationPayload({ text: prompt }), createdAt: now, updatedAt: now,
+    };
+    const scopeKey = operationScopeKey(operation);
+    let collecting = Promise.resolve();
+    let notifying;
+    let pendingNotifications = [];
+    const notify = (events) => {
+        // Notifications only wake the source archive; every event already belongs to the durable journal.
+        pendingNotifications = [...pendingNotifications, ...events].slice(-100);
+        notifying ??= (async () => {
+            while (pendingNotifications.length) {
+                const page = pendingNotifications;
+                pendingNotifications = [];
+                await publishSourceEvents(state, page);
+            }
+        })().finally(() => {
+            notifying = undefined;
+            if (pendingNotifications.length)
+                notify([]);
+        });
+    };
+    let archiveError;
+    let shutdownError;
+    let cancelled = false;
+    let rootThreadId;
+    let rootTurnId;
+    let completedTurn;
+    let timeout;
+    let leaseCheck;
     let completion;
     const done = new Promise(resolve => { completion = resolve; });
+    track(async () => {
+        cancelled = true;
+        completion('unknown');
+        await adapter.close?.();
+        await collecting;
+    });
     const unsubscribe = adapter.onCollected?.(event => {
         if (event.kind === 'process_exit')
             completion('unknown');
+        else {
+            const params = event.params && typeof event.params === 'object'
+                ? event.params : {};
+            // The prompt is recorded before dispatch; Codex may echo the same user message afterward.
+            if (params.item?.type !== 'userMessage' || params.threadId !== rootThreadId) {
+                collecting = collecting.then(async () => notify(await ingestCollected(state, {
+                    ...event, params: { ...params, directoryName: input.directoryName },
+                }, false))).catch(error => {
+                    archiveError ??= error;
+                    completion('unknown');
+                });
+            }
+        }
         if (event.method === 'turn/completed') {
             const value = event.params;
-            completion(value.turn?.status === 'completed' ? 'completed' : 'failed');
+            if (value.threadId === rootThreadId && value.turn?.id) {
+                completedTurn = value.turn;
+                if (value.turn.id === rootTurnId)
+                    completion(value.turn.status === 'completed' ? 'completed' : 'failed');
+            }
         }
     });
     try {
@@ -63,28 +123,72 @@ export async function runProductionNative(state, input, root, record, track) {
         groups.push(group);
         await record(group);
         const thread = await adapter.startThread({ sessionId, cwd: root });
-        const turn = await adapter.startTurn({ sessionId, threadId: thread.threadId, text: String(input.payload.prompt ?? ''),
-            clientRequestId: `${input.task.attemptId}:generate`, persistReservation: async () => undefined });
+        rootThreadId = thread.threadId;
+        // A production thread lives in its own Codex home and must never resume through the main adapter.
+        await state.journal.putSession({ sessionId, workspaceId: input.task.workspaceId, directoryName: input.directoryName,
+            threadId: thread.threadId, cwd: root, recoverability: 'history_only', turnStatus: 'starting' });
+        const creation = { ...operation, operationId: `${input.task.attemptId}:session.create`,
+            clientRequestId: `${input.task.attemptId}:session.create`, kind: 'session.create', status: 'completed',
+            payloadHash: hashOperationPayload({}), nativeThreadId: thread.threadId };
+        await state.journal.putOperation(operationScopeKey(creation), creation);
+        await state.journal.putOperation(scopeKey, { ...operation, nativeThreadId: thread.threadId });
+        notify(await recordNativeEvents(state, creation, [{ type: 'session.created', occurredAt: now, payload: {
+                    sessionId, threadId: thread.threadId, batchId: input.task.batchId, attemptId: input.task.attemptId,
+                    taskId: input.task.taskId, readonly: true, recoverability: 'history_only',
+                } }], false));
+        notify(await recordNativeEvents(state, operation, [{ type: 'item/completed', occurredAt: now, payload: {
+                    item: { id: `${sessionId}-prompt`, type: 'userMessage', content: [{ type: 'text', text: prompt }] },
+                } }], false));
+        const turn = await adapter.startTurn({ sessionId, threadId: thread.threadId, text: prompt,
+            clientRequestId: operation.clientRequestId, persistReservation: async ({ nativeRequestId }) => {
+                await state.journal.putOperation(scopeKey, { ...operation, nativeThreadId: thread.threadId, nativeRequestId });
+            } });
         if (turn.outcome !== 'accepted')
-            throw new Error('production_native_start_unknown');
-        const timeout = setTimeout(() => completion('unknown'), 30 * 60_000);
+            throw new Error(turn.outcome === 'failed' ? 'production_native_failed' : 'production_native_start_unknown');
+        rootTurnId = turn.turnId;
+        const reserved = state.journal.getOperation(scopeKey);
+        const released = await state.journal.bindTurn({ scopeKey, sessionId, threadId: thread.threadId, turnId: turn.turnId,
+            operation: transitionOperation(reserved, 'accepted', { nativeThreadId: thread.threadId, nativeTurnId: turn.turnId }) });
+        if (released.length)
+            notify(released);
+        if (completedTurn?.id === rootTurnId)
+            completion(completedTurn.status === 'completed' ? 'completed' : 'failed');
+        timeout = setTimeout(() => completion('unknown'), 30 * 60_000);
         let checking = false;
-        const leaseCheck = setInterval(() => {
+        leaseCheck = setInterval(() => {
             if (checking)
                 return;
             checking = true;
             void verifyProductionLease(input).catch(async () => { completion('unknown'); await adapter.close?.().catch(() => undefined); }).finally(() => { checking = false; });
         }, 5000);
         const status = await done;
-        clearInterval(leaseCheck);
-        clearTimeout(timeout);
         if (status !== 'completed')
             throw new Error(status === 'failed' ? 'production_native_failed' : 'production_native_unknown');
     }
     finally {
+        clearInterval(leaseCheck);
+        clearTimeout(timeout);
+        await adapter.close?.().catch(error => { shutdownError = error; });
         unsubscribe?.();
-        await adapter.close?.().catch(() => undefined);
+        await collecting;
         for (const group of groups)
             await record({ ...group, stopped: await stopProductionGroup(group) });
+        const latest = state.journal.getOperation(scopeKey);
+        if (latest && ['dispatched', 'accepted', 'uncertain'].includes(latest.status)) {
+            const status = cancelled ? 'interrupted' : 'failed';
+            await state.journal.putOperation(scopeKey, transitionOperation(latest, status, {
+                error: cancelled ? 'production_execution_stopped' : 'production_native_unknown',
+            }));
+            const session = state.journal.getSession(sessionId);
+            if (session) {
+                await state.journal.putSession({ ...session, turnStatus: status, turnBlock: undefined });
+                notify(await recordNativeEvents(state, latest, [{ type: `turn.${status}`, occurredAt: new Date().toISOString(),
+                        payload: { turnId: latest.nativeTurnId, error: cancelled ? 'production_execution_stopped' : 'production_native_unknown' } }], false));
+            }
+        }
+        if (archiveError)
+            throw new Error('production_chat_archive_failed');
+        if (shutdownError)
+            throw new Error('production_native_stop_unknown');
     }
 }

package/dist/workspace-runtime/server/dispatch.js

@@ -2,7 +2,7 @@ import { withObservedFile } from '../workspaces/revisions.js';
 import { revisionScope, sessionWorkspaceRoot, workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { PLATFORM_ROUTES, platformEndpoint, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, reasoningEffortSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { PLATFORM_ROUTES, platformEndpoint, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, productionSessionAttemptId, reasoningEffortSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { closeCliCredentials } from '../workspaces/cli-credentials.js';
 import { artifactFormat } from '../workspaces/artifact-files.js';
 import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
@@ -62,6 +62,9 @@ export async function executeOperation(state, scopeKey, operation, payload, reco
 }
 async function executeScopedOperation(state, scopeKey, operation, payload, recovery) {
     let current = await persist(state, scopeKey, transitionOperation(operation, 'dispatched'));
+    if (operation.kind.startsWith('session.') && operation.sessionId && productionSessionAttemptId(operation.sessionId)) {
+        return persist(state, scopeKey, transitionOperation(current, 'failed', { error: 'production_session_readonly' }));
+    }
     if (operation.kind === 'runtime.ensure') {
         current = await persist(state, scopeKey, transitionOperation(current, 'accepted'));
         return persist(state, scopeKey, transitionOperation(current, 'completed'));
@@ -807,7 +810,7 @@ export function attachNativeCollector(state) {
         void ingestCollected(state, event);
     });
 }
-async function ingestCollected(state, event) {
+export async function ingestCollected(state, event, publish = true) {
     const ids = nativeIds(event.params);
     const recorded = await state.journal.ingestNative({
         runtimeId: state.config.runtimeId,
@@ -821,10 +824,11 @@ async function ingestCollected(state, event) {
         itemId: ids.itemId,
         occurredAt: event.occurredAt,
     });
-    if (recorded.length > 0)
+    if (publish && recorded.length > 0)
         await publishSourceEvents(state, recorded);
+    return recorded;
 }
-export async function recordNativeEvents(state, operation, events) {
+export async function recordNativeEvents(state, operation, events, publish = true) {
     const recorded = [];
     for (const event of events) {
         const payload = {
@@ -845,11 +849,11 @@ export async function recordNativeEvents(state, operation, events) {
             operationId: operation.operationId,
         }));
     }
-    if (recorded.length > 0)
+    if (publish && recorded.length > 0)
         await publishSourceEvents(state, recorded);
     return recorded;
 }
-async function publishSourceEvents(state, events) {
+export async function publishSourceEvents(state, events) {
     await notifyCallback(state, events).catch(() => undefined);
 }
 function sessionTurnBusy(session) {
@@ -870,6 +874,7 @@ function nativeIds(params) {
 async function notifyCallback(state, events) {
     await fetch(platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.events), {
         method: 'POST',
+        signal: AbortSignal.timeout(5000),
         headers: {
             authorization: `Bearer ${state.config.controlToken}`,
             'x-playcraft-control-token': state.config.controlToken,

package/dist/workspace-runtime/server/http.js

@@ -1,7 +1,7 @@
 import { readObservedFile, withObservedFile } from '../workspaces/revisions.js';
 import { registerWorkspace, revisionScope, sessionWorkspaceRoot, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
 import { randomUUID } from 'node:crypto';
-import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, hashOperationPayload, isLostThreadError, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, isWorkspaceMutation, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, hashOperationPayload, isLostThreadError, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, productionSessionAttemptId, isWorkspaceMutation, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { applyRuntimeEndpointPatch } from './endpoints.js';
 import { canExecuteKind, executeOperation } from './dispatch.js';
@@ -365,6 +365,8 @@ export async function handleRuntimeRequest(state, request, response) {
             return;
         }
         if (request.method === 'POST' && url.pathname === '/runtime/operations') {
+            // Track creation before accepting it, so a new unconnected terminal is known not to have spawned.
+            terminalHost(state);
             await acceptOperation(state, request, response);
             return;
         }
@@ -527,6 +529,10 @@ async function acceptOperation(state, request, response) {
             writeJson(response, 200, decision.operation);
             return;
         }
+        if (parsed.data.kind.startsWith('session.') && parsed.data.sessionId && productionSessionAttemptId(parsed.data.sessionId)) {
+            writeError(response, runtimeError('capability_unavailable', 'production_session_readonly'));
+            return;
+        }
         if (parsed.data.kind === 'session.create') {
             const creation = state.journal.findSessionCreation(parsed.data.sessionId);
             const session = state.journal.getSession(parsed.data.sessionId);
@@ -702,15 +708,13 @@ async function handleTerminalIdentity(state, request, response, remainder) {
         return;
     }
     if (request.method === 'DELETE' && !action) {
-        const destroyed = terminal.status === 'destroyed'
-            ? terminal
-            : await state.journal.putTerminal({
-                ...terminal,
-                status: 'destroyed',
-                destroyedAt: new Date().toISOString(),
-            });
-        terminalHost(state).revoke(destroyed.terminalId, 'terminal_destroyed');
-        writeJson(response, 200, { terminalId: destroyed.terminalId, status: destroyed.status });
+        try {
+            const destroyed = await terminalHost(state).destroy(terminalId);
+            writeJson(response, 200, { terminalId: destroyed.terminalId, status: destroyed.status });
+        }
+        catch {
+            writeError(response, runtimeError('capability_unavailable', 'terminal_stop_unconfirmed'));
+        }
         return;
     }
     writeJson(response, 404, { error: 'not_found' });

package/dist/workspace-runtime/server/terminal-host.js

@@ -32,9 +32,16 @@ export class TerminalHost {
     disposed = false;
     sessions = new Map();
     spawning = new Map();
+    restored;
+    attempted = new Set();
+    closing = new Set();
+    stops = new Map();
+    confirmed = new Set();
     sockets = new WebSocketServer({ noServer: true });
     constructor(state) {
         this.state = state;
+        // An absent in-memory session cannot prove a restored terminal's old process group stopped.
+        this.restored = new Set((state.journal?.listTerminals?.() ?? []).map(terminal => terminal.terminalId));
     }
     async handleUpgrade(request, socket, head) {
         const url = new URL(request.url ?? '/', 'http://127.0.0.1');
@@ -68,6 +75,10 @@ export class TerminalHost {
             rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_destroyed'));
             return;
         }
+        if (this.closing.has(terminalId) || this.restored.has(terminalId) && !this.sessions.has(terminalId)) {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_stop_unconfirmed'));
+            return;
+        }
         let session = this.sessions.get(terminal.terminalId);
         if (!session) {
             try {
@@ -84,14 +95,41 @@ export class TerminalHost {
                 return;
             }
         }
-        if (this.disposed || this.state.journal.destroyed() || this.state.journal.getTerminal(terminalId)?.status === 'destroyed') {
-            this.revoke(terminalId, 'terminal_destroyed');
+        if (this.disposed || this.state.journal.destroyed() || this.closing.has(terminalId) || this.state.journal.getTerminal(terminalId)?.status === 'destroyed') {
+            if (!this.closing.has(terminalId))
+                this.revoke(terminalId, 'terminal_destroyed');
             rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_destroyed'));
             return;
         }
         const active = session;
         this.sockets.handleUpgrade(request, socket, head, (ws) => this.attach(active, ws));
     }
+    destroy(terminalId) {
+        const pending = this.stops.get(terminalId);
+        if (pending)
+            return pending;
+        this.closing.add(terminalId);
+        const stopped = (async () => {
+            await this.spawning.get(terminalId);
+            const session = this.sessions.get(terminalId);
+            if (session)
+                await session.stop();
+            else if (!this.confirmed.has(terminalId) && (this.restored.has(terminalId) || this.attempted.has(terminalId)))
+                throw new Error('terminal_stop_unconfirmed');
+            const terminal = this.state.journal.getTerminal(terminalId);
+            if (!terminal)
+                throw new Error('terminal_not_found');
+            const destroyed = terminal.status === 'destroyed' ? terminal : await this.state.journal.putTerminal({
+                ...terminal, status: 'destroyed', destroyedAt: new Date().toISOString(),
+            });
+            this.confirmed.add(terminalId);
+            this.revoke(terminalId, 'terminal_destroyed');
+            this.closing.delete(terminalId);
+            return destroyed;
+        })().finally(() => this.stops.delete(terminalId));
+        this.stops.set(terminalId, stopped);
+        return stopped;
+    }
     revoke(terminalId, reason) {
         const session = this.sessions.get(terminalId);
         if (!session)
@@ -124,13 +162,15 @@ export class TerminalHost {
             const socketPath = process.env.PLAYCRAFT_LAUNCHER_SOCKET;
             if (!socketPath)
                 throw new Error('pty_unavailable');
+            this.attempted.add(terminal.terminalId);
             const child = await startLauncherProcess({ socketPath, processId: `terminal-${randomUUID()}`,
                 runtimeEpoch: this.state.runtimeEpoch, cwd, argv: [], env: {}, terminal: { cols: 80, rows: 24 } });
             if (this.disposed) {
                 await child.stop();
                 throw new Error('pty_unavailable');
             }
-            const session = { streamId: randomUUID(), log: createTerminalOutputLog(), listeners: new Set(),
+            const session = { terminalId: terminal.terminalId, streamId: randomUUID(), log: createTerminalOutputLog(), listeners: new Set(),
+                stop: () => child.stop(),
                 pty: { write: (data) => { child.stdin?.write(data); }, resize: child.resize,
                     kill: () => { void child.stop().catch(() => undefined); } } };
             const decoder = new StringDecoder('utf8');
@@ -140,14 +180,20 @@ export class TerminalHost {
                 const tail = decoder.end();
                 if (tail)
                     publish(session, tail);
-                this.exited(session, code ?? null);
+                const stopped = code === undefined ? Promise.resolve(false) : child.stop().then(() => true, () => false);
+                void stopped.then(confirmed => this.exited(terminal.terminalId, session, confirmed ? code : undefined)).catch(() => undefined);
             });
             this.sessions.set(terminal.terminalId, session);
             return session;
         }
         const pty = require('node-pty');
         const command = commands.get(this.state) ?? defaultShell();
+        let finishExit;
+        let didExit = false;
+        const knownExit = new Promise(resolve => { finishExit = () => { didExit = true; resolve(); }; });
+        this.attempted.add(terminal.terminalId);
         const session = {
+            terminalId: terminal.terminalId,
             streamId: randomUUID(),
             log: createTerminalOutputLog(),
             listeners: new Set(),
@@ -158,17 +204,43 @@ export class TerminalHost {
                 cwd,
                 env: shellEnv(command.file, cwd),
             }),
+            stop: async () => {
+                if (!didExit)
+                    session.pty.kill();
+                let timer;
+                try {
+                    await Promise.race([knownExit, new Promise((_resolve, reject) => {
+                            timer = setTimeout(() => reject(new Error('terminal_stop_unconfirmed')), 3000);
+                        })]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
         };
         const local = session.pty;
         local.onData((data) => publish(session, data));
-        local.onExit(({ exitCode, signal }) => this.exited(session, exitCode, signal));
+        local.onExit(({ exitCode, signal }) => { finishExit(); void this.exited(terminal.terminalId, session, exitCode, signal).catch(() => undefined); });
         this.sessions.set(terminal.terminalId, session);
         return session;
     }
-    exited(session, code, signal) {
-        session.exited = { code, ...(signal === undefined ? {} : { signal: String(signal) }) };
-        for (const listener of session.listeners)
-            listener(exitFrame(session));
+    async exited(terminalId, session, code, signal) {
+        session.exited = { code: code ?? null, ...(signal === undefined ? {} : { signal: String(signal) }) };
+        try {
+            if (code !== undefined) {
+                const terminal = this.state.journal.getTerminal(terminalId);
+                if (terminal && terminal.status !== 'destroyed')
+                    await this.state.journal.putTerminal({
+                        ...terminal, status: 'destroyed', destroyedAt: new Date().toISOString(),
+                    });
+                if (terminal)
+                    this.confirmed.add(terminalId);
+            }
+        }
+        finally {
+            for (const listener of session.listeners)
+                listener(exitFrame(session));
+        }
     }
     attach(session, ws) {
         let open = true;
@@ -199,7 +271,7 @@ export class TerminalHost {
                 return;
             }
             const parsed = terminalClientFrameSchema.safeParse(body);
-            if (!parsed.success || session.exited && parsed.data.type !== 'resume')
+            if (!parsed.success || (session.exited || this.closing.has(session.terminalId)) && parsed.data.type !== 'resume')
                 return;
             const frame = parsed.data;
             if (frame.type === 'resume') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "private": false,
   "type": "module",
   "engines": {
@@ -50,8 +50,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.27",
-    "@playcraft/common": "^0.1.27",
+    "@playcraft/build": "^0.1.28",
+    "@playcraft/common": "^0.1.28",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",