@taskforcehq/taskforce 0.3.327 → 0.3.329

package/dist/server/routes/workspaces.js

@@ -17,9 +17,11 @@ import { parseJsonBody } from './primitives.js';
 import { resolveRequestAccess, createSessionTokenCookie, resolveSessionCookieAttributesForRequest, } from '../auth.js';
 import { isWorkspaceSwitchingEnabledForRuntime } from '../../shared/runtimeContract.js';
 import { getRouteTimingNow, logSlowBootstrapRoute, requestBootstrapTraceId, resolveErrorStatusCode, serializeJsonWithTiming, setServerTimingHeader } from './shared.js';
+import { WorkspaceDeletionAdmission } from '../workspaceDeletionAdmission.js';
 // === SECTION: Registration ===
 export function registerWorkspaceRoutes(deps) {
     const { addRoute, core, context, ensureAppAccess, auditAuthAction, getObjectStorageClient, ensureWithinDir, sanitizeStorageSegment, sanitizeTaskIdForPath, normalizeDocumentPathInput, } = deps;
+    const workspaceDeletionAdmission = new WorkspaceDeletionAdmission();
     // === SECTION: Storage cleanup helper ===
     const cleanupDeletedWorkspaceStorage = async (summary) => {
         const warnings = [];
@@ -231,12 +233,49 @@ export function registerWorkspaceRoutes(deps) {
             res.end(JSON.stringify({ success: false, error: 'workspaceId is required.', code: 'WORKSPACE_ID_REQUIRED' }));
             return;
         }
-        const resolvedAccess = core.resolveUserAccess(access.userId, targetWorkspaceId, 'member');
+        const writeAdmissionError = (decision) => {
+            res.setHeader('Retry-After', String(Math.max(1, Math.ceil(decision.retryAfterMs / 1_000))));
+            const inProgress = decision.code === 'WORKSPACE_DELETE_IN_PROGRESS';
+            res.writeHead(inProgress ? 409 : 429, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: inProgress
+                    ? 'Workspace deletion is already running for this workspace.'
+                    : 'Workspace deletion was attempted recently. Wait before retrying.',
+                code: decision.code,
+                retryAfterMs: decision.retryAfterMs,
+            }));
+        };
+        const existingAdmission = workspaceDeletionAdmission.checkExisting(targetWorkspaceId);
+        if (existingAdmission) {
+            writeAdmissionError(existingAdmission);
+            return;
+        }
+        let resolvedAccess;
+        try {
+            resolvedAccess = core.resolveUserAccess(access.userId, targetWorkspaceId, 'member');
+        }
+        catch (error) {
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                success: false,
+                error: String(error?.message || 'Unable to resolve workspace access'),
+                code: error?.code,
+            }));
+            return;
+        }
         if (!resolvedAccess || resolvedAccess.role !== 'owner' || resolvedAccess.disabled) {
             res.writeHead(403, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: false, error: 'Only workspace owners can delete this workspace.' }));
             return;
         }
+        const deletionAdmissionKey = targetWorkspaceId;
+        const admission = workspaceDeletionAdmission.acquire(deletionAdmissionKey);
+        if (!admission.allowed) {
+            writeAdmissionError(admission);
+            return;
+        }
         try {
             const deleted = core.deleteWorkspace({ workspaceId: targetWorkspaceId });
             const cleanupWarnings = await cleanupDeletedWorkspaceStorage(deleted);
@@ -277,6 +316,9 @@ export function registerWorkspaceRoutes(deps) {
                 code: error?.code
             }));
         }
+        finally {
+            workspaceDeletionAdmission.settle(deletionAdmissionKey);
+        }
     });
     // === SECTION: Session workspace switch ===
     // POST /api/taskforce/session/workspace - Switch active workspace in auth session

package/dist/server/routes.js

@@ -602,7 +602,7 @@ export function createRoutes(core, context = {}) {
             taskId: input.taskId,
             workspaceId: input.workspaceId,
             action: 'task-attachments-changed',
-            actor: 'user',
+            actor: String(input.actorRef || '').trim() || 'user',
             createdAt: input.createdAt || new Date().toISOString(),
             details: {
                 changes: {
@@ -725,6 +725,7 @@ export function createRoutes(core, context = {}) {
                         asset,
                         beforeTask: taskBeforeLink,
                         createdAt: asset.updatedAt,
+                        actorRef: params.actorRef,
                     });
                 }
             }
@@ -788,7 +789,7 @@ export function createRoutes(core, context = {}) {
             return false;
         return /^workspaces\/[^/]+\/assets\/documents\/.+\.(md|markdown)$/.test(normalized);
     };
-    const resolveCanonicalDocumentRead = async (params) => {
+    const resolveCanonicalContentRead = async (params) => {
         const resolvedObjectStorage = resolveEffectiveObjectStorageConfig();
         const objectStorageClient = getObjectStorageClient();
         const { basePath } = core.getPaths();
@@ -800,17 +801,19 @@ export function createRoutes(core, context = {}) {
             : params.asset.storageProvider === 'local'
                 ? 'local'
                 : null;
+        const contentKind = params.asset.kind === 'document' ? 'document' : 'asset';
+        const contentLabel = params.asset.kind === 'document' ? 'Document' : 'Asset';
         const resolvedContent = publishedContentResolver && resolverOwnedProvider
             ? publishedContentResolver.resolve({
                 tenantId: core.getTenantId(),
                 workspaceId: params.asset.workspaceId,
-                kind: 'document',
+                kind: contentKind,
                 logicalPath: logicalStorageKey,
                 legacyProvider: resolverOwnedProvider
             })
             : {
                 source: 'legacy',
-                kind: 'document',
+                kind: contentKind,
                 logicalPath: logicalStorageKey,
                 physicalKey: logicalStorageKey,
                 storageProvider: params.asset.storageProvider
@@ -818,6 +821,31 @@ export function createRoutes(core, context = {}) {
         if (resolvedContent.source === 'deleted') {
             return { statusCode: 404 };
         }
+        if (resolvedContent.source === 'versioned' && (resolvedContent.storageProvider !== params.asset.storageProvider
+            || resolvedContent.contentSha256 !== params.asset.contentSha256
+            || resolvedContent.sizeBytes !== params.asset.sizeBytes)) {
+            return {
+                statusCode: 409,
+                headers: { 'Content-Type': 'application/json' },
+                body: Buffer.from(JSON.stringify({
+                    error: params.asset.kind === 'document'
+                        ? 'The published document head does not match the current canonical document metadata.'
+                        : 'The published asset head does not match the current canonical asset metadata.',
+                    code: params.asset.kind === 'document' ? 'MCP_DOCUMENT_HEAD_STALE' : 'WORKSPACE_ASSET_HEAD_STALE',
+                    details: {
+                        assetId: params.asset.assetId,
+                        currentVersion: params.asset.version,
+                        currentStorageProvider: params.asset.storageProvider,
+                        currentContentSha256: params.asset.contentSha256,
+                        currentSizeBytes: params.asset.sizeBytes,
+                        headVersionId: resolvedContent.versionId,
+                        headStorageProvider: resolvedContent.storageProvider,
+                        headContentSha256: resolvedContent.contentSha256,
+                        headSizeBytes: resolvedContent.sizeBytes,
+                    },
+                })),
+            };
+        }
         const physicalStorageKey = normalizeRelativeStorageKey(resolvedContent.physicalKey);
         if (!physicalStorageKey)
             return { statusCode: 404 };
@@ -852,7 +880,7 @@ export function createRoutes(core, context = {}) {
                         'Content-Disposition': contentDisposition
                     },
                     body: resolvedContent.source === 'versioned'
-                        ? verifyWorkspaceSyncPublishedContentBody(object.body, resolvedContent, `Document ${params.asset.assetId}`)
+                        ? verifyWorkspaceSyncPublishedContentBody(object.body, resolvedContent, `${contentLabel} ${params.asset.assetId}`)
                         : object.body
                 };
             }
@@ -879,7 +907,7 @@ export function createRoutes(core, context = {}) {
                     'Content-Disposition': contentDisposition
                 },
                 body: resolvedContent.source === 'versioned'
-                    ? verifyWorkspaceSyncPublishedContentBody(body, resolvedContent, `Document ${params.asset.assetId}`)
+                    ? verifyWorkspaceSyncPublishedContentBody(body, resolvedContent, `${contentLabel} ${params.asset.assetId}`)
                     : body
             };
         }
@@ -1497,7 +1525,7 @@ export function createRoutes(core, context = {}) {
         sanitizeDownloadFilename,
         contentTypeForExt,
         inferInlineDocumentFromPath,
-        resolveCanonicalDocumentRead,
+        resolveCanonicalContentRead,
         inferWorkspaceIdFromStoragePath,
         inferTaskIdFromStoragePath,
     });

package/dist/server/workspaceDeletionAdmission.d.ts

@@ -0,0 +1,23 @@
+export declare const WORKSPACE_DELETE_RETRY_COOLDOWN_MS = 30000;
+export type WorkspaceDeletionAdmissionDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    code: 'WORKSPACE_DELETE_IN_PROGRESS' | 'WORKSPACE_DELETE_RETRY_COOLDOWN';
+    retryAfterMs: number;
+};
+/**
+ * Serializes destructive workspace cleanup inside one server process and
+ * throttles immediate retries after an attempt settles. The caller supplies
+ * time so the admission policy can be verified without timers.
+ */
+export declare class WorkspaceDeletionAdmission {
+    private readonly cooldownMs;
+    private readonly entries;
+    constructor(cooldownMs?: number);
+    checkExisting(key: string, now?: number): Exclude<WorkspaceDeletionAdmissionDecision, {
+        allowed: true;
+    }> | null;
+    acquire(key: string, now?: number): WorkspaceDeletionAdmissionDecision;
+    settle(key: string, now?: number): void;
+}

package/dist/server/workspaceDeletionAdmission.js

@@ -0,0 +1,50 @@
+export const WORKSPACE_DELETE_RETRY_COOLDOWN_MS = 30_000;
+/**
+ * Serializes destructive workspace cleanup inside one server process and
+ * throttles immediate retries after an attempt settles. The caller supplies
+ * time so the admission policy can be verified without timers.
+ */
+export class WorkspaceDeletionAdmission {
+    cooldownMs;
+    entries = new Map();
+    constructor(cooldownMs = WORKSPACE_DELETE_RETRY_COOLDOWN_MS) {
+        this.cooldownMs = cooldownMs;
+    }
+    checkExisting(key, now = Date.now()) {
+        let existing = this.entries.get(key);
+        if (existing?.state === 'cooldown' && existing.retryAt <= now) {
+            this.entries.delete(key);
+            existing = undefined;
+        }
+        if (existing?.state === 'in-flight') {
+            return {
+                allowed: false,
+                code: 'WORKSPACE_DELETE_IN_PROGRESS',
+                retryAfterMs: Math.max(1_000, this.cooldownMs),
+            };
+        }
+        if (existing?.state === 'cooldown') {
+            return {
+                allowed: false,
+                code: 'WORKSPACE_DELETE_RETRY_COOLDOWN',
+                retryAfterMs: Math.max(1_000, existing.retryAt - now),
+            };
+        }
+        return null;
+    }
+    acquire(key, now = Date.now()) {
+        const existing = this.checkExisting(key, now);
+        if (existing)
+            return existing;
+        this.entries.set(key, { state: 'in-flight' });
+        return { allowed: true };
+    }
+    settle(key, now = Date.now()) {
+        if (this.entries.get(key)?.state !== 'in-flight')
+            return;
+        this.entries.set(key, {
+            state: 'cooldown',
+            retryAt: now + this.cooldownMs,
+        });
+    }
+}

package/dist/service/localServiceCli.js

@@ -1,9 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { applyLocalServiceCloudTarget, localServiceCloudTargetsEqual, parseLocalServiceCloudTarget, resolveLocalServiceCloudTarget, } from '../config/localServiceCloudTarget.js';
+import { localServiceRuntimeContractsEqual, parseLocalServiceRuntimeContract, resolveLocalServiceRuntimeContract, } from '../config/localServiceRuntimeContract.js';
 import { createStandaloneServer } from '../server/index.js';
 import { inspectLocalServiceDescriptor, redactLocalServiceDescriptor, } from '../server/localServiceLease.js';
 import { acquireLocalServiceOwnershipForRuntime, } from '../server/localServiceOwnershipBootstrap.js';
-import { LOCAL_SERVICE_API_BASE_PATH, LOCAL_SERVICE_PROTOCOL_VERSION, resolveLocalServiceLeaseInput, spawnDetachedLocalService, waitForLocalServiceDescriptor, } from './localServiceClientLifecycle.js';
+import { discoverOrStartLocalService, LOCAL_SERVICE_API_BASE_PATH, LOCAL_SERVICE_PROTOCOL_VERSION, resolveLocalServiceLeaseInput, spawnDetachedLocalService, waitForLocalServiceDescriptor, } from './localServiceClientLifecycle.js';
 import { listSqliteWalHolders } from '../storage/sqliteWalHealth.js';
 const STARTUP_TIMEOUT_MS = 15_000;
 export { LOCAL_SERVICE_PROTOCOL_VERSION } from './localServiceClientLifecycle.js';
@@ -58,6 +60,20 @@ function reportIncompatibleDescriptor(inspection, error) {
     error(`Taskforce service protocol ${inspection.descriptor.protocolVersion} is incompatible with client protocol ${LOCAL_SERVICE_PROTOCOL_VERSION}.`);
     return true;
 }
+function reportCloudTargetMismatch(descriptorTarget, requestedTarget, error) {
+    if (localServiceCloudTargetsEqual(descriptorTarget, requestedTarget))
+        return false;
+    error('Taskforce service is running for a different or unverified cloud target. '
+        + 'Stop it with `taskforce service stop --drain`, then retry.');
+    return true;
+}
+function reportRuntimeContractMismatch(descriptorContract, requestedContract, error) {
+    if (localServiceRuntimeContractsEqual(descriptorContract, requestedContract))
+        return false;
+    error('Taskforce service is running with a different or unverified local runtime contract. '
+        + 'Stop it with `taskforce service stop --drain`, then retry.');
+    return true;
+}
 function defaultRegisterShutdownSignals(handler) {
     process.once('SIGINT', handler);
     process.once('SIGTERM', handler);
@@ -75,6 +91,9 @@ async function waitForDescriptor(input, expected, options) {
     });
 }
 async function runForeground(command, options) {
+    const requestedCloudTarget = resolveLocalServiceCloudTarget(options.env);
+    applyLocalServiceCloudTarget(options.env, requestedCloudTarget);
+    const requestedRuntimeContract = resolveLocalServiceRuntimeContract(options.env);
     const ownership = await options.acquireOwnership(command.projectRoot, options.env);
     if (!ownership)
         throw new Error('The shared local service requires local runtime mode.');
@@ -84,6 +103,10 @@ async function runForeground(command, options) {
         if (inspection.status === 'live' && inspection.descriptor) {
             if (reportIncompatibleDescriptor(inspection, options.error))
                 return 2;
+            if (reportCloudTargetMismatch(inspection.descriptor.cloudTarget, requestedCloudTarget, options.error))
+                return 2;
+            if (reportRuntimeContractMismatch(inspection.descriptor.runtimeContract, requestedRuntimeContract, options.error))
+                return 2;
             options.log(`Taskforce service is already running at ${inspection.descriptor.endpoint}.`);
             return 0;
         }
@@ -116,6 +139,8 @@ async function runForeground(command, options) {
                 ownerPid: process.pid,
                 bootstrapCapability: ownership.lease.bootstrapCapability,
                 ownershipKey: ownership.lease.identity.ownershipKey,
+                cloudTarget: requestedCloudTarget,
+                runtimeContract: requestedRuntimeContract,
             },
             afterShutdown: async () => {
                 removeSignals();
@@ -138,6 +163,8 @@ async function runForeground(command, options) {
             endpoint: `http://127.0.0.1:${address.port}`,
             protocolVersion: LOCAL_SERVICE_PROTOCOL_VERSION,
             appVersion: options.appVersion,
+            cloudTarget: requestedCloudTarget,
+            runtimeContract: requestedRuntimeContract,
         });
         removeSignals = options.registerShutdownSignals(shutdown);
         server.once('error', (error) => {
@@ -164,34 +191,28 @@ async function runForeground(command, options) {
     }
 }
 async function runStart(command, options) {
-    const leaseInput = resolveLocalServiceLeaseInput(command.projectRoot, options.env);
-    const current = await options.inspectDescriptor(leaseInput);
-    if (current.status === 'live' && current.descriptor) {
-        if (reportIncompatibleDescriptor(current, options.error))
-            return 2;
-        options.log(`Taskforce service is already running at ${current.descriptor.endpoint}.`);
+    const requestedCloudTarget = resolveLocalServiceCloudTarget(options.env);
+    applyLocalServiceCloudTarget(options.env, requestedCloudTarget);
+    try {
+        const descriptor = await discoverOrStartLocalService({
+            projectRoot: command.projectRoot,
+            env: options.env,
+            executablePath: options.executablePath,
+            cliEntryPath: options.cliEntryPath,
+            execArgv: options.execArgv,
+            inspectDescriptor: options.inspectDescriptor,
+            spawnDetached: options.spawnDetached,
+            fetch: options.fetch,
+            sleep: options.sleep,
+            nowMs: options.nowMs,
+        });
+        options.log(`Taskforce service is ready at ${descriptor.endpoint}.`);
         return 0;
     }
-    if (current.status === 'indeterminate') {
-        options.error('Taskforce service state is indeterminate; refusing to start a competing owner.');
-        return 2;
-    }
-    options.spawnDetached(options.executablePath, [
-        ...options.execArgv,
-        options.cliEntryPath,
-        'service',
-        command.projectRoot,
-        '--detached-child',
-    ], options.env);
-    const inspection = await waitForDescriptor(leaseInput, 'live', options);
-    if (inspection.status !== 'live' || !inspection.descriptor) {
-        options.error('Taskforce service did not become ready before the startup deadline.');
+    catch (startError) {
+        options.error(String(startError?.message || startError));
         return 2;
     }
-    if (reportIncompatibleDescriptor(inspection, options.error))
-        return 2;
-    options.log(`Taskforce service started at ${inspection.descriptor.endpoint}.`);
-    return 0;
 }
 async function runStatus(command, options) {
     const leaseInput = resolveLocalServiceLeaseInput(command.projectRoot, options.env);
@@ -222,9 +243,15 @@ async function runStatus(command, options) {
                 throw new Error(`HTTP ${response.status}`);
             const payload = await response.json();
             const coordinatorPayload = payload.coordinator;
+            const diagnosticCloudTarget = parseLocalServiceCloudTarget(payload.cloudTarget);
+            const diagnosticRuntimeContract = parseLocalServiceRuntimeContract(payload.runtimeContract);
             if (payload.ownerPid !== inspection.descriptor.pid
                 || payload.generation !== inspection.descriptor.generation
                 || payload.protocolVersion !== inspection.descriptor.protocolVersion
+                || (inspection.descriptor.cloudTarget
+                    && !localServiceCloudTargetsEqual(diagnosticCloudTarget, inspection.descriptor.cloudTarget))
+                || (inspection.descriptor.runtimeContract
+                    && !localServiceRuntimeContractsEqual(diagnosticRuntimeContract, inspection.descriptor.runtimeContract))
                 || !Array.isArray(payload.sessions)
                 || !coordinatorPayload
                 || typeof coordinatorPayload !== 'object'

package/dist/service/localServiceClientLifecycle.js

@@ -1,6 +1,8 @@
 import { spawn } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { applyLocalServiceCloudTarget, localServiceCloudTargetsEqual, parseLocalServiceCloudTarget, resolveLocalServiceCloudTarget, } from '../config/localServiceCloudTarget.js';
+import { localServiceRuntimeContractsEqual, parseLocalServiceRuntimeContract, resolveLocalServiceRuntimeContract, } from '../config/localServiceRuntimeContract.js';
 import { inspectLocalServiceDescriptor, } from '../server/localServiceLease.js';
 import { resolveLocalDatabaseIdentity } from '../server/localDatabaseIdentity.js';
 export const LOCAL_SERVICE_PROTOCOL_VERSION = '1';
@@ -22,6 +24,11 @@ const LOCAL_MCP_CLIENT_ENV_KEYS = [
     'TASKFORCE_AI_SURFACE_TYPE',
     'TASKFORCE_AI_SEAT_SCOPE',
 ];
+function isQaIdentityEnvironmentKey(key) {
+    return key.startsWith('TASKFORCE_E2E_')
+        || key.startsWith('TASKFORCE_PLAYWRIGHT_')
+        || key.startsWith('SYNC_SOAK_');
+}
 export function resolveLocalServiceLeaseInput(projectRoot, env) {
     const provider = env.TASKFORCE_DB_PROVIDER === 'postgres' ? 'postgres' : 'sqlite';
     return {
@@ -39,10 +46,15 @@ export function spawnDetachedLocalService(executablePath, args, env) {
     });
     child.unref();
 }
-function buildLocalServiceProcessEnv(env) {
+function buildLocalServiceProcessEnv(env, cloudTarget) {
     const serviceEnv = { ...env };
     for (const key of LOCAL_MCP_CLIENT_ENV_KEYS)
         delete serviceEnv[key];
+    for (const key of Object.keys(serviceEnv)) {
+        if (isQaIdentityEnvironmentKey(key))
+            delete serviceEnv[key];
+    }
+    applyLocalServiceCloudTarget(serviceEnv, cloudTarget);
     return serviceEnv;
 }
 export async function waitForLocalServiceDescriptor(input, expected, options = {}) {
@@ -78,15 +90,72 @@ async function validateLocalServiceReadiness(descriptor, fetchFn) {
     catch {
         throw new Error('Taskforce shared local service readiness returned invalid JSON.');
     }
+    const readinessHasCloudTarget = Object.prototype.hasOwnProperty.call(readiness, 'cloudTarget');
+    const readinessCloudTarget = readinessHasCloudTarget
+        ? parseLocalServiceCloudTarget(readiness.cloudTarget)
+        : null;
+    const readinessHasRuntimeContract = Object.prototype.hasOwnProperty.call(readiness, 'runtimeContract');
+    const readinessRuntimeContract = readinessHasRuntimeContract
+        ? parseLocalServiceRuntimeContract(readiness.runtimeContract)
+        : null;
+    const descriptorCloudTarget = descriptor.cloudTarget || null;
+    const descriptorRuntimeContract = descriptor.runtimeContract || null;
+    const cloudTargetsMatch = descriptorCloudTarget || readinessCloudTarget
+        ? localServiceCloudTargetsEqual(descriptorCloudTarget, readinessCloudTarget)
+        : true;
+    const runtimeContractsMatch = descriptorRuntimeContract || readinessRuntimeContract
+        ? localServiceRuntimeContractsEqual(descriptorRuntimeContract, readinessRuntimeContract)
+        : true;
     if (readiness.ready !== true
         || readiness.protocolVersion !== LOCAL_SERVICE_PROTOCOL_VERSION
         || readiness.protocolVersion !== descriptor.protocolVersion
         || readiness.generation !== descriptor.generation
         || readiness.pid !== descriptor.pid
         || readiness.endpoint !== descriptor.endpoint
-        || readiness.dataIdentity !== descriptor.ownershipKey) {
+        || readiness.dataIdentity !== descriptor.ownershipKey
+        || (readinessHasCloudTarget && !readinessCloudTarget)
+        || !cloudTargetsMatch
+        || (readinessHasRuntimeContract && !readinessRuntimeContract)
+        || !runtimeContractsMatch) {
         throw new Error('Taskforce shared local service readiness does not match its descriptor.');
     }
+    return {
+        cloudTarget: descriptorCloudTarget,
+        runtimeContract: descriptorRuntimeContract,
+    };
+}
+async function requestIdleLocalServiceShutdown(descriptor, fetchFn) {
+    let response;
+    try {
+        response = await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/shutdown`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-taskforce-local-service-capability': descriptor.bootstrapCapability,
+            },
+            body: JSON.stringify({
+                intent: 'administrative-stop',
+                mode: 'refuse',
+                pid: descriptor.pid,
+                generation: descriptor.generation,
+            }),
+            redirect: 'error',
+            signal: AbortSignal.timeout(LOCAL_SERVICE_STARTUP_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new Error('Taskforce service uses a different cloud target or runtime contract and could not be stopped safely. '
+            + `No replacement was started. ${String(error?.message || error)}`);
+    }
+    if (!response.ok) {
+        const detail = (await response.text()).slice(0, 500);
+        const activeClientHint = response.status === 409
+            ? ' It may have active MCP clients; close them or run `taskforce service stop --drain`, then retry.'
+            : '';
+        throw new Error(`Taskforce service uses a different cloud target or runtime contract and refused safe idle replacement (${response.status}).`
+            + activeClientHint
+            + (detail ? ` ${detail}` : ''));
+    }
 }
 export async function discoverOrStartLocalService(input) {
     const requestedRoot = path.resolve(input.projectRoot);
@@ -94,13 +163,27 @@ export async function discoverOrStartLocalService(input) {
     const leaseInput = resolveLocalServiceLeaseInput(projectRoot, input.env);
     const inspectDescriptor = input.inspectDescriptor || inspectLocalServiceDescriptor;
     const fetchFn = input.fetch || fetch;
+    const requestedCloudTarget = resolveLocalServiceCloudTarget(input.env);
+    const requestedRuntimeContract = resolveLocalServiceRuntimeContract(input.env);
     const current = await inspectDescriptor(leaseInput);
     if (current.status === 'live' && current.descriptor) {
         if (current.descriptor.protocolVersion !== LOCAL_SERVICE_PROTOCOL_VERSION) {
             throw new Error(`Taskforce service protocol ${current.descriptor.protocolVersion} is incompatible with client protocol ${LOCAL_SERVICE_PROTOCOL_VERSION}.`);
         }
-        await validateLocalServiceReadiness(current.descriptor, fetchFn);
-        return current.descriptor;
+        const running = await validateLocalServiceReadiness(current.descriptor, fetchFn);
+        if (localServiceCloudTargetsEqual(running.cloudTarget, requestedCloudTarget)
+            && localServiceRuntimeContractsEqual(running.runtimeContract, requestedRuntimeContract)) {
+            return current.descriptor;
+        }
+        await requestIdleLocalServiceShutdown(current.descriptor, fetchFn);
+        const stopped = await waitForLocalServiceDescriptor(leaseInput, 'stale', {
+            inspectDescriptor,
+            sleep: input.sleep,
+            nowMs: input.nowMs,
+        });
+        if (stopped.status !== 'stale') {
+            throw new Error('Taskforce service accepted configuration replacement but did not release its owner lease. No replacement was started.');
+        }
     }
     if (current.status === 'indeterminate') {
         throw new Error('Taskforce service state is indeterminate; refusing to start a competing owner.');
@@ -111,7 +194,7 @@ export async function discoverOrStartLocalService(input) {
         'service',
         projectRoot,
         '--detached-child',
-    ], buildLocalServiceProcessEnv(input.env));
+    ], buildLocalServiceProcessEnv(input.env, requestedCloudTarget));
     const inspection = await waitForLocalServiceDescriptor(leaseInput, 'live', {
         inspectDescriptor,
         sleep: input.sleep,
@@ -123,6 +206,10 @@ export async function discoverOrStartLocalService(input) {
     if (inspection.descriptor.protocolVersion !== LOCAL_SERVICE_PROTOCOL_VERSION) {
         throw new Error(`Taskforce service protocol ${inspection.descriptor.protocolVersion} is incompatible with client protocol ${LOCAL_SERVICE_PROTOCOL_VERSION}.`);
     }
-    await validateLocalServiceReadiness(inspection.descriptor, fetchFn);
+    const started = await validateLocalServiceReadiness(inspection.descriptor, fetchFn);
+    if (!localServiceCloudTargetsEqual(started.cloudTarget, requestedCloudTarget)
+        || !localServiceRuntimeContractsEqual(started.runtimeContract, requestedRuntimeContract)) {
+        throw new Error('Taskforce service started with a different or unverified cloud target/runtime contract; refusing to attach.');
+    }
     return inspection.descriptor;
 }

package/dist/services/codexAppServerModelGateway.d.ts

@@ -0,0 +1,112 @@
+import type { ModelGateway, ModelGatewayGenerateInput, ModelGatewayGenerateResult } from './modelGateway.js';
+export type CodexAppServerModelKeyIdMap = Partial<Record<string, string>>;
+type CodexAppServerApprovalPolicy = 'never';
+type CodexAppServerSandboxMode = 'read-only';
+type CodexAppServerSandboxPolicy = {
+    type: 'readOnly';
+    networkAccess: false;
+};
+type CodexAppServerRuntimePolicy = {
+    cwd: string;
+    approvalPolicy: CodexAppServerApprovalPolicy;
+    sandbox: CodexAppServerSandboxMode;
+    sandboxPolicy: CodexAppServerSandboxPolicy;
+};
+export interface CodexAppServerClient {
+    initialize(): Promise<void>;
+    assertChatGptSubscriptionAuth(): Promise<void>;
+    startThread(input: {
+        model: string;
+        developerInstructions?: string;
+    } & CodexAppServerRuntimePolicy): Promise<{
+        threadId: string;
+    }>;
+    startTurnAndCollectText(input: {
+        threadId: string;
+        prompt: string;
+        model: string;
+        timeoutMs: number;
+    } & CodexAppServerRuntimePolicy): Promise<{
+        text: string;
+        stopReason?: string;
+    }>;
+    close(): void;
+}
+export interface CodexAppServerModelGatewayOptions {
+    client?: CodexAppServerClient;
+    clientFactory?: () => CodexAppServerClient;
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    modelKeyIds?: CodexAppServerModelKeyIdMap;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+}
+export declare const DEFAULT_CODEX_APP_SERVER_MODEL_KEY_IDS: CodexAppServerModelKeyIdMap;
+export declare function buildCodexAppServerEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function sanitizeCodexAppServerStderr(value: unknown): string;
+export declare function collectCodexAppServerStderr(current: string, chunk: unknown): string;
+export declare function assertCodexChatGptSubscriptionAccount(result: unknown): void;
+export declare function isCodexSubscriptionDevRuntimeAllowed(source?: NodeJS.ProcessEnv): boolean;
+export declare function extractCodexTurnCompletion(messages: unknown[]): {
+    text: string;
+    stopReason: string;
+} | null;
+export declare class CodexAppServerJsonRpcClient implements CodexAppServerClient {
+    private readonly process;
+    private readonly pending;
+    private readonly notifications;
+    private nextId;
+    private initialized;
+    private readonly lineReader;
+    private readonly requestTimeoutMs;
+    private readonly turnRejectors;
+    private terminalError;
+    private stderrTail;
+    constructor(options?: {
+        command?: string;
+        args?: string[];
+        cwd?: string;
+        env?: NodeJS.ProcessEnv;
+        requestTimeoutMs?: number;
+    });
+    initialize(): Promise<void>;
+    assertChatGptSubscriptionAuth(): Promise<void>;
+    startThread(input: {
+        model: string;
+        developerInstructions?: string;
+    } & CodexAppServerRuntimePolicy): Promise<{
+        threadId: string;
+    }>;
+    startTurnAndCollectText(input: {
+        threadId: string;
+        prompt: string;
+        system?: string;
+        model: string;
+        timeoutMs: number;
+    } & CodexAppServerRuntimePolicy): Promise<{
+        text: string;
+        stopReason?: string;
+    }>;
+    close(): void;
+    private request;
+    private sendNotification;
+    private handleLine;
+    private sendResponseError;
+    private waitForTurnCompletion;
+    private rejectAll;
+    private fail;
+}
+export declare class CodexAppServerModelGateway implements ModelGateway {
+    private readonly client?;
+    private readonly clientFactory;
+    private readonly modelKeyIds;
+    private readonly timeoutMs;
+    private readonly cwd;
+    constructor(options?: CodexAppServerModelGatewayOptions);
+    generate(input: ModelGatewayGenerateInput): Promise<ModelGatewayGenerateResult>;
+    private resolveModelId;
+    private formatMessages;
+}
+export {};