@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/server/smtpTransport.d.ts

@@ -10,12 +10,20 @@ export interface SmtpTransport {
         messageId?: string;
     }>;
 }
-export declare function createSmtpTransport(config: {
+export interface SmtpTransportConfig {
     host: string;
     port: number;
     secure: boolean;
-    auth: {
+    auth?: {
         user: string;
         pass: string;
     };
-}): Promise<SmtpTransport>;
+    connectionTimeout?: number;
+    greetingTimeout?: number;
+    socketTimeout?: number;
+}
+export declare function resolveSmtpTransportConfig(config: SmtpTransportConfig): SmtpTransportConfig & {
+    disableFileAccess: true;
+    disableUrlAccess: true;
+};
+export declare function createSmtpTransport(config: SmtpTransportConfig): Promise<SmtpTransport>;

package/dist/server/smtpTransport.js

@@ -1,11 +1,18 @@
+export function resolveSmtpTransportConfig(config) {
+    return {
+        ...config,
+        disableFileAccess: true,
+        disableUrlAccess: true
+    };
+}
 export async function createSmtpTransport(config) {
     try {
         const dynamicImport = new Function('modulePath', 'return import(modulePath);');
         const mod = await dynamicImport('nodemailer');
         const nodemailer = mod.default || mod;
-        return nodemailer.createTransport(config);
+        return nodemailer.createTransport(resolveSmtpTransportConfig(config));
     }
     catch {
-        throw new Error('Nodemailer dependency is missing. Install nodemailer to use google-workspace provider.');
+        throw new Error('Nodemailer dependency is missing. Install nodemailer to use SMTP email providers.');
     }
 }

package/dist/server/start.js

@@ -1,17 +1,49 @@
 import { createStandaloneServer } from './index.js';
+import { acquireLocalServiceOwnershipForRuntime } from './localServiceOwnershipBootstrap.js';
 const parsedPort = Number.parseInt(String(process.env.PORT || '8080'), 10);
 const port = Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : 8080;
 const projectRoot = process.cwd();
-try {
-    const server = createStandaloneServer({
-        projectRoot,
-        port
-    });
-    server.listen(port, () => {
-        console.log(`[Taskforce] Server started on port ${port}`);
-    });
+async function main() {
+    const ownership = await acquireLocalServiceOwnershipForRuntime(projectRoot);
+    if (ownership && (!ownership.owned || !ownership.localDataOwnerPermit)) {
+        throw new Error('Local standalone startup could not acquire exclusive local data ownership.');
+    }
+    const localSyncProcessLock = ownership?.syncProcessLock || undefined;
+    try {
+        const server = createStandaloneServer({
+            projectRoot,
+            port,
+            localSyncProcessLock,
+            localDataOwnerPermit: ownership?.localDataOwnerPermit || undefined,
+            afterShutdown: () => ownership?.release(),
+        });
+        if (localSyncProcessLock && !localSyncProcessLock.owned) {
+            console.warn('[Taskforce] Another local process owns workspace sync; sync transfer routes will fail closed.');
+        }
+        server.once('error', (error) => {
+            void server.shutdownTaskforce()
+                .catch(async () => {
+                // A runtime-owned lock must survive an incomplete sync drain.
+                // Capture-only processes have no coordinator runtime to protect.
+                if (!server.localSyncCoordinatorHost) {
+                    await ownership?.release();
+                }
+            })
+                .finally(() => {
+                console.error(`[Taskforce] Server failed: ${String(error?.message || error)}`);
+                process.exit(1);
+            });
+        });
+        server.listen(port, () => {
+            console.log(`[Taskforce] Server started on port ${port}`);
+        });
+    }
+    catch (error) {
+        await ownership?.release();
+        throw error;
+    }
 }
-catch (error) {
+main().catch((error) => {
     console.error(`[Taskforce] Failed to start standalone server: ${error?.message || error}`);
     process.exit(1);
-}
+});

package/dist/service/localServiceCli.d.ts

@@ -0,0 +1,33 @@
+import { createStandaloneServer } from '../server/index.js';
+import { inspectLocalServiceDescriptor } from '../server/localServiceLease.js';
+import { acquireLocalServiceOwnershipForRuntime } from '../server/localServiceOwnershipBootstrap.js';
+import { type SqliteWalHolder } from '../storage/sqliteWalHealth.js';
+export { LOCAL_SERVICE_PROTOCOL_VERSION } from './localServiceClientLifecycle.js';
+export type LocalServiceAction = 'foreground' | 'start' | 'status' | 'stop';
+export type LocalServiceStopMode = 'refuse' | 'drain' | 'force';
+export interface ParsedLocalServiceCommand {
+    action: LocalServiceAction;
+    projectRoot: string;
+    stopMode: LocalServiceStopMode;
+    detachedChild: boolean;
+}
+export declare function parseLocalServiceCommand(argv: readonly string[], cwd?: string): ParsedLocalServiceCommand;
+export interface LocalServiceCliOptions {
+    env?: NodeJS.ProcessEnv;
+    appVersion: string;
+    executablePath: string;
+    cliEntryPath: string;
+    execArgv?: readonly string[];
+    createServer?: typeof createStandaloneServer;
+    acquireOwnership?: typeof acquireLocalServiceOwnershipForRuntime;
+    inspectDescriptor?: typeof inspectLocalServiceDescriptor;
+    spawnDetached?: (executablePath: string, args: readonly string[], env: NodeJS.ProcessEnv) => void;
+    fetch?: typeof fetch;
+    listDatabaseHolders?: (dbPath: string) => SqliteWalHolder[];
+    sleep?: (delayMs: number) => Promise<void>;
+    nowMs?: () => number;
+    registerShutdownSignals?: (handler: () => void) => () => void;
+    log?: (message: string) => void;
+    error?: (message: string) => void;
+}
+export declare function runLocalServiceCli(argv: readonly string[], input: LocalServiceCliOptions): Promise<number>;

package/dist/service/localServiceCli.js

@@ -0,0 +1,365 @@
+import * as fs from 'fs';
+import * as path from 'path';
+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 { listSqliteWalHolders } from '../storage/sqliteWalHealth.js';
+const STARTUP_TIMEOUT_MS = 15_000;
+export { LOCAL_SERVICE_PROTOCOL_VERSION } from './localServiceClientLifecycle.js';
+export function parseLocalServiceCommand(argv, cwd = process.cwd()) {
+    const values = [...argv];
+    const requestedAction = values[0];
+    const action = requestedAction === 'start'
+        || requestedAction === 'status'
+        || requestedAction === 'stop'
+        ? requestedAction
+        : 'foreground';
+    if (action !== 'foreground')
+        values.shift();
+    const detachedChild = values.includes('--detached-child');
+    const drain = values.includes('--drain');
+    const force = values.includes('--force');
+    if (drain && force)
+        throw new Error('Choose only one shutdown mode: --drain or --force.');
+    if (action !== 'stop' && (drain || force)) {
+        throw new Error('--drain and --force are valid only with taskforce service stop.');
+    }
+    if (action !== 'foreground' && detachedChild) {
+        throw new Error('--detached-child is an internal foreground-service option.');
+    }
+    const positional = values.filter((value) => !value.startsWith('--'));
+    const unknownFlags = values.filter((value) => value.startsWith('--')
+        && !['--detached-child', '--drain', '--force'].includes(value));
+    if (unknownFlags.length > 0)
+        throw new Error(`Unknown service option: ${unknownFlags[0]}`);
+    if (positional.length > 1)
+        throw new Error('The service command accepts at most one project path.');
+    const requestedRoot = path.resolve(positional[0] || cwd);
+    const projectRoot = fs.existsSync(requestedRoot) ? fs.realpathSync(requestedRoot) : requestedRoot;
+    return {
+        action,
+        projectRoot,
+        stopMode: force ? 'force' : drain ? 'drain' : 'refuse',
+        detachedChild,
+    };
+}
+function isEnabled(env) {
+    const configured = String(env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED || '').trim();
+    return !configured || /^(1|true|yes|on)$/i.test(configured);
+}
+function isDescriptorCompatible(inspection) {
+    return !inspection.descriptor
+        || inspection.descriptor.protocolVersion === LOCAL_SERVICE_PROTOCOL_VERSION;
+}
+function reportIncompatibleDescriptor(inspection, error) {
+    if (isDescriptorCompatible(inspection))
+        return false;
+    error(`Taskforce service protocol ${inspection.descriptor.protocolVersion} is incompatible with client protocol ${LOCAL_SERVICE_PROTOCOL_VERSION}.`);
+    return true;
+}
+function defaultRegisterShutdownSignals(handler) {
+    process.once('SIGINT', handler);
+    process.once('SIGTERM', handler);
+    return () => {
+        process.off('SIGINT', handler);
+        process.off('SIGTERM', handler);
+    };
+}
+async function waitForDescriptor(input, expected, options) {
+    return waitForLocalServiceDescriptor(input, expected, {
+        inspectDescriptor: options.inspectDescriptor,
+        sleep: options.sleep,
+        nowMs: options.nowMs,
+        timeoutMs: STARTUP_TIMEOUT_MS,
+    });
+}
+async function runForeground(command, options) {
+    const ownership = await options.acquireOwnership(command.projectRoot, options.env);
+    if (!ownership)
+        throw new Error('The shared local service requires local runtime mode.');
+    const leaseInput = resolveLocalServiceLeaseInput(command.projectRoot, options.env);
+    if (!ownership.owned) {
+        const inspection = await waitForDescriptor(leaseInput, 'live', options);
+        if (inspection.status === 'live' && inspection.descriptor) {
+            if (reportIncompatibleDescriptor(inspection, options.error))
+                return 2;
+            options.log(`Taskforce service is already running at ${inspection.descriptor.endpoint}.`);
+            return 0;
+        }
+        options.error('A local service owner exists but readiness could not be proven.');
+        return 2;
+    }
+    let server = null;
+    let removeSignals = () => { };
+    let shutdownStarted = false;
+    const shutdown = () => {
+        if (shutdownStarted || !server)
+            return;
+        shutdownStarted = true;
+        void server.shutdownTaskforce().catch((error) => {
+            options.error(`Taskforce service shutdown failed: ${String(error?.message || error)}`);
+            process.exitCode = 1;
+        });
+    };
+    try {
+        server = options.createServer({
+            projectRoot: command.projectRoot,
+            port: 0,
+            localSyncProcessLock: ownership.syncProcessLock || undefined,
+            localDataOwnerPermit: ownership.localDataOwnerPermit || undefined,
+            manageProcessSignals: false,
+            localService: {
+                generation: ownership.lease.generation,
+                protocolVersion: LOCAL_SERVICE_PROTOCOL_VERSION,
+                appVersion: options.appVersion,
+                ownerPid: process.pid,
+                bootstrapCapability: ownership.lease.bootstrapCapability,
+                ownershipKey: ownership.lease.identity.ownershipKey,
+            },
+            afterShutdown: async () => {
+                removeSignals();
+                await ownership.release();
+            },
+        });
+        await new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            server.once('error', onError);
+            server.listen(0, '127.0.0.1', () => {
+                server.off('error', onError);
+                resolve();
+            });
+        });
+        const address = server.address();
+        if (!address || typeof address.port !== 'number') {
+            throw new Error('Taskforce service did not bind a loopback TCP port.');
+        }
+        const descriptor = ownership.lease.publishDescriptor({
+            endpoint: `http://127.0.0.1:${address.port}`,
+            protocolVersion: LOCAL_SERVICE_PROTOCOL_VERSION,
+            appVersion: options.appVersion,
+        });
+        removeSignals = options.registerShutdownSignals(shutdown);
+        server.once('error', (error) => {
+            options.error(`Taskforce service failed: ${String(error?.message || error)}`);
+            shutdown();
+        });
+        options.log(`Taskforce service ready at ${descriptor.endpoint} (generation ${descriptor.generation}).`);
+        return 0;
+    }
+    catch (error) {
+        removeSignals();
+        if (server) {
+            try {
+                await server.shutdownTaskforce();
+            }
+            catch (shutdownError) {
+                throw new AggregateError([error, shutdownError], 'Taskforce service startup and fail-closed shutdown both failed.');
+            }
+        }
+        else {
+            await ownership.release();
+        }
+        throw error;
+    }
+}
+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}.`);
+        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.');
+        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);
+    const inspection = await options.inspectDescriptor(leaseInput);
+    const compatible = isDescriptorCompatible(inspection);
+    let holders = [];
+    let holderInspectionError = null;
+    if (leaseInput.databaseIdentityKind === 'path') {
+        try {
+            holders = options.listDatabaseHolders(leaseInput.databaseIdentity);
+        }
+        catch (holderError) {
+            holderInspectionError = String(holderError?.message || holderError);
+        }
+    }
+    let diagnostics = null;
+    let diagnosticsError = null;
+    if (compatible && inspection.status === 'live' && inspection.descriptor) {
+        try {
+            const response = await options.fetch(`${inspection.descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/diagnostics`, {
+                headers: {
+                    'x-taskforce-local-service-capability': inspection.descriptor.bootstrapCapability,
+                },
+                redirect: 'error',
+                signal: AbortSignal.timeout(STARTUP_TIMEOUT_MS),
+            });
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            const payload = await response.json();
+            const coordinatorPayload = payload.coordinator;
+            if (payload.ownerPid !== inspection.descriptor.pid
+                || payload.generation !== inspection.descriptor.generation
+                || payload.protocolVersion !== inspection.descriptor.protocolVersion
+                || !Array.isArray(payload.sessions)
+                || !coordinatorPayload
+                || typeof coordinatorPayload !== 'object'
+                || typeof coordinatorPayload.ownershipMode !== 'string'
+                || typeof coordinatorPayload.desiredOwnershipMode !== 'string'
+                || !Number.isSafeInteger(coordinatorPayload.coordinatorGeneration)
+                || !Object.prototype.hasOwnProperty.call(coordinatorPayload, 'activeWorkspaceId')
+                || typeof coordinatorPayload.transitionState !== 'string') {
+                throw new Error('service diagnostics do not match the active descriptor or required ownership shape');
+            }
+            diagnostics = payload;
+        }
+        catch (diagnosticError) {
+            diagnosticsError = String(diagnosticError?.message || diagnosticError);
+        }
+    }
+    const coordinator = diagnostics?.coordinator && typeof diagnostics.coordinator === 'object'
+        ? diagnostics.coordinator
+        : null;
+    options.log(JSON.stringify({
+        status: compatible ? inspection.status : 'incompatible',
+        compatible,
+        descriptor: inspection.descriptor
+            ? redactLocalServiceDescriptor(inspection.descriptor)
+            : null,
+        serviceOwner: inspection.descriptor ? {
+            pid: inspection.descriptor.pid,
+            generation: inspection.descriptor.generation,
+            appVersion: inspection.descriptor.appVersion,
+            protocolVersion: inspection.descriptor.protocolVersion,
+        } : null,
+        clients: Array.isArray(diagnostics?.sessions) ? diagnostics.sessions : [],
+        databaseHolders: holders,
+        holderInspectionError,
+        syncExecutor: coordinator ? {
+            ownershipMode: coordinator.ownershipMode,
+            desiredOwnershipMode: coordinator.desiredOwnershipMode,
+            coordinatorGeneration: coordinator.coordinatorGeneration,
+            activeWorkspaceId: coordinator.activeWorkspaceId,
+            transitionState: coordinator.transitionState,
+        } : null,
+        diagnosticsError,
+    }, null, 2));
+    if (!compatible) {
+        reportIncompatibleDescriptor(inspection, options.error);
+        return 2;
+    }
+    const holderMismatch = leaseInput.databaseIdentityKind === 'path'
+        && (inspection.status === 'live'
+            ? holders.length === 0 || holders.some((holder) => holder.pid !== inspection.descriptor?.pid)
+            : holders.length > 0);
+    if (diagnosticsError || holderInspectionError || holderMismatch)
+        return 2;
+    return inspection.status === 'live' ? 0 : inspection.status === 'stale' ? 1 : 2;
+}
+async function runStop(command, options) {
+    const leaseInput = resolveLocalServiceLeaseInput(command.projectRoot, options.env);
+    const inspection = await options.inspectDescriptor(leaseInput);
+    if (inspection.status === 'stale' || !inspection.descriptor) {
+        options.log('Taskforce service is not running.');
+        return 0;
+    }
+    if (inspection.status !== 'live') {
+        options.error('Taskforce service state is indeterminate; refusing administrative shutdown.');
+        return 2;
+    }
+    if (reportIncompatibleDescriptor(inspection, options.error))
+        return 2;
+    const descriptor = inspection.descriptor;
+    let response;
+    try {
+        response = await options.fetch(`${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: command.stopMode,
+                pid: descriptor.pid,
+                generation: descriptor.generation,
+            }),
+            signal: AbortSignal.timeout(STARTUP_TIMEOUT_MS),
+        });
+    }
+    catch (requestError) {
+        options.error(`Taskforce service shutdown request failed: ${String(requestError?.message || requestError)}`);
+        return 2;
+    }
+    if (!response.ok) {
+        const message = (await response.text()).slice(0, 1_000);
+        options.error(`Taskforce service refused shutdown (${response.status}): ${message}`);
+        return response.status === 409 ? 1 : 2;
+    }
+    const stopped = await waitForDescriptor(leaseInput, 'stale', options);
+    if (stopped.status !== 'stale') {
+        options.error('Taskforce service accepted shutdown but did not release its descriptor in time.');
+        return 2;
+    }
+    options.log('Taskforce service stopped.');
+    return 0;
+}
+export async function runLocalServiceCli(argv, input) {
+    const command = parseLocalServiceCommand(argv);
+    const env = input.env || process.env;
+    const log = input.log || console.log;
+    const error = input.error || console.error;
+    if ((command.action === 'foreground' || command.action === 'start') && !isEnabled(env)) {
+        error('Shared local MCP service is disabled. Set TASKFORCE_SHARED_LOCAL_MCP_ENABLED=true to enable it.');
+        return 2;
+    }
+    const common = {
+        env,
+        appVersion: input.appVersion,
+        executablePath: input.executablePath,
+        cliEntryPath: input.cliEntryPath,
+        execArgv: input.execArgv || [],
+        createServer: input.createServer || createStandaloneServer,
+        acquireOwnership: input.acquireOwnership || acquireLocalServiceOwnershipForRuntime,
+        inspectDescriptor: input.inspectDescriptor || inspectLocalServiceDescriptor,
+        spawnDetached: input.spawnDetached || spawnDetachedLocalService,
+        fetch: input.fetch || fetch,
+        listDatabaseHolders: input.listDatabaseHolders || listSqliteWalHolders,
+        sleep: input.sleep || ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs))),
+        nowMs: input.nowMs || Date.now,
+        registerShutdownSignals: input.registerShutdownSignals || defaultRegisterShutdownSignals,
+        log,
+        error,
+    };
+    if (command.action === 'start')
+        return runStart(command, common);
+    if (command.action === 'status')
+        return runStatus(command, common);
+    if (command.action === 'stop')
+        return runStop(command, common);
+    return runForeground(command, common);
+}

package/dist/service/localServiceClientLifecycle.d.ts

@@ -0,0 +1,25 @@
+import { inspectLocalServiceDescriptor, type LocalServiceDescriptor, type LocalServiceDescriptorInspection, type LocalServiceLeaseIdentityInput } from '../server/localServiceLease.js';
+export declare const LOCAL_SERVICE_PROTOCOL_VERSION = "1";
+export declare const LOCAL_SERVICE_API_BASE_PATH = "/api/taskforce/local-service/v1";
+export declare const LOCAL_SERVICE_STARTUP_TIMEOUT_MS = 15000;
+export declare const LOCAL_SERVICE_STARTUP_POLL_MS = 100;
+export declare function resolveLocalServiceLeaseInput(projectRoot: string, env: NodeJS.ProcessEnv): LocalServiceLeaseIdentityInput;
+export declare function spawnDetachedLocalService(executablePath: string, args: readonly string[], env: NodeJS.ProcessEnv): void;
+export declare function waitForLocalServiceDescriptor(input: LocalServiceLeaseIdentityInput, expected: 'live' | 'stale', options?: {
+    inspectDescriptor?: typeof inspectLocalServiceDescriptor;
+    sleep?: (delayMs: number) => Promise<void>;
+    nowMs?: () => number;
+    timeoutMs?: number;
+}): Promise<LocalServiceDescriptorInspection>;
+export declare function discoverOrStartLocalService(input: {
+    projectRoot: string;
+    env: NodeJS.ProcessEnv;
+    executablePath: string;
+    cliEntryPath: string;
+    execArgv?: readonly string[];
+    inspectDescriptor?: typeof inspectLocalServiceDescriptor;
+    spawnDetached?: typeof spawnDetachedLocalService;
+    fetch?: typeof fetch;
+    sleep?: (delayMs: number) => Promise<void>;
+    nowMs?: () => number;
+}): Promise<LocalServiceDescriptor>;

package/dist/service/localServiceClientLifecycle.js

@@ -0,0 +1,128 @@
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { inspectLocalServiceDescriptor, } from '../server/localServiceLease.js';
+import { resolveLocalDatabaseIdentity } from '../server/localDatabaseIdentity.js';
+export const LOCAL_SERVICE_PROTOCOL_VERSION = '1';
+export const LOCAL_SERVICE_API_BASE_PATH = '/api/taskforce/local-service/v1';
+export const LOCAL_SERVICE_STARTUP_TIMEOUT_MS = 15_000;
+export const LOCAL_SERVICE_STARTUP_POLL_MS = 100;
+const LOCAL_MCP_CLIENT_ENV_KEYS = [
+    'TASKFORCE_MCP_CLIENT_ID',
+    'TASKFORCE_MCP_CONNECTION_ID',
+    'TASKFORCE_MCP_TOOL_PROFILE',
+    'TASKFORCE_AI_PROFILE_TOKEN',
+    'TASKFORCE_AI_NAME',
+    'TASKFORCE_AI_ICON',
+    'TASKFORCE_AI_COLOR',
+    'TASKFORCE_AI_DESCRIPTION',
+    'TASKFORCE_AI_ROLE',
+    'TASKFORCE_AI_PROVIDER',
+    'TASKFORCE_AI_MODEL',
+    'TASKFORCE_AI_SURFACE_TYPE',
+    'TASKFORCE_AI_SEAT_SCOPE',
+];
+export function resolveLocalServiceLeaseInput(projectRoot, env) {
+    const provider = env.TASKFORCE_DB_PROVIDER === 'postgres' ? 'postgres' : 'sqlite';
+    return {
+        projectRoot,
+        databaseIdentity: resolveLocalDatabaseIdentity(projectRoot, provider, env),
+        databaseIdentityKind: provider === 'sqlite' ? 'path' : 'opaque',
+    };
+}
+export function spawnDetachedLocalService(executablePath, args, env) {
+    const child = spawn(executablePath, [...args], {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+        env,
+    });
+    child.unref();
+}
+function buildLocalServiceProcessEnv(env) {
+    const serviceEnv = { ...env };
+    for (const key of LOCAL_MCP_CLIENT_ENV_KEYS)
+        delete serviceEnv[key];
+    return serviceEnv;
+}
+export async function waitForLocalServiceDescriptor(input, expected, options = {}) {
+    const inspectDescriptor = options.inspectDescriptor || inspectLocalServiceDescriptor;
+    const sleep = options.sleep || ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs)));
+    const nowMs = options.nowMs || Date.now;
+    const deadline = nowMs() + (options.timeoutMs ?? LOCAL_SERVICE_STARTUP_TIMEOUT_MS);
+    let inspection = await inspectDescriptor(input);
+    while (inspection.status !== expected && nowMs() < deadline) {
+        await sleep(LOCAL_SERVICE_STARTUP_POLL_MS);
+        inspection = await inspectDescriptor(input);
+    }
+    return inspection;
+}
+async function validateLocalServiceReadiness(descriptor, fetchFn) {
+    let response;
+    try {
+        response = await fetchFn(`${descriptor.endpoint}${LOCAL_SERVICE_API_BASE_PATH}/readiness`, {
+            redirect: 'error',
+            signal: AbortSignal.timeout(LOCAL_SERVICE_STARTUP_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw new Error(`Taskforce shared local service readiness failed: ${String(error?.message || error)}`);
+    }
+    if (!response.ok) {
+        throw new Error(`Taskforce shared local service readiness failed (${response.status}).`);
+    }
+    let readiness;
+    try {
+        readiness = await response.json();
+    }
+    catch {
+        throw new Error('Taskforce shared local service readiness returned invalid JSON.');
+    }
+    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) {
+        throw new Error('Taskforce shared local service readiness does not match its descriptor.');
+    }
+}
+export async function discoverOrStartLocalService(input) {
+    const requestedRoot = path.resolve(input.projectRoot);
+    const projectRoot = fs.existsSync(requestedRoot) ? fs.realpathSync(requestedRoot) : requestedRoot;
+    const leaseInput = resolveLocalServiceLeaseInput(projectRoot, input.env);
+    const inspectDescriptor = input.inspectDescriptor || inspectLocalServiceDescriptor;
+    const fetchFn = input.fetch || fetch;
+    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;
+    }
+    if (current.status === 'indeterminate') {
+        throw new Error('Taskforce service state is indeterminate; refusing to start a competing owner.');
+    }
+    (input.spawnDetached || spawnDetachedLocalService)(input.executablePath, [
+        ...(input.execArgv || []),
+        input.cliEntryPath,
+        'service',
+        projectRoot,
+        '--detached-child',
+    ], buildLocalServiceProcessEnv(input.env));
+    const inspection = await waitForLocalServiceDescriptor(leaseInput, 'live', {
+        inspectDescriptor,
+        sleep: input.sleep,
+        nowMs: input.nowMs,
+    });
+    if (inspection.status !== 'live' || !inspection.descriptor) {
+        throw new Error('Taskforce service did not become ready before the startup deadline.');
+    }
+    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);
+    return inspection.descriptor;
+}

package/dist/service/localServiceOpen.d.ts

@@ -0,0 +1,17 @@
+import type { LocalServiceDescriptor } from '../server/localServiceLease.js';
+import { discoverOrStartLocalService } from './localServiceClientLifecycle.js';
+export declare function shouldOpenViaLocalService(env: NodeJS.ProcessEnv): boolean;
+export declare function buildLocalServiceUiUrl(descriptor: LocalServiceDescriptor): string;
+export declare function openTaskforceViaLocalService(input: {
+    projectRoot: string;
+    env: NodeJS.ProcessEnv;
+    executablePath: string;
+    cliEntryPath: string;
+    execArgv?: readonly string[];
+    discover?: typeof discoverOrStartLocalService;
+    openBrowser: (url: string) => void;
+    log?: (message: string) => void;
+}): Promise<{
+    descriptor: LocalServiceDescriptor;
+    url: string;
+}>;