@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/annotatedAttachments/commandService.js

@@ -0,0 +1,348 @@
+export class AnnotatedAttachmentCommandError extends Error {
+    code;
+    statusCode;
+    details;
+    constructor(message, code = 'MCP_INVALID_ARGUMENT', statusCode = 400, details) {
+        super(message);
+        this.name = 'AnnotatedAttachmentCommandError';
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+    }
+}
+function normalizeInstructionType(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'review'
+        || normalized === 'question'
+        || normalized === 'change'
+        || normalized === 'issue'
+        || normalized === 'idea') {
+        return normalized;
+    }
+    return undefined;
+}
+function normalizeKind(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized === 'pin' || normalized === 'arrow' || normalized === 'box') {
+        return normalized;
+    }
+    if (normalized === 'text-note' || normalized === 'note') {
+        return 'text-note';
+    }
+    throw new AnnotatedAttachmentCommandError('kind must be one of: pin, box, arrow, text-note');
+}
+function normalizeUnitCoordinate(value, fieldName) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < 0 || numeric > 1) {
+        throw new AnnotatedAttachmentCommandError(`${fieldName} must be a number between 0 and 1`);
+    }
+    return numeric;
+}
+function normalizeOptionalUnitCoordinate(value, fieldName) {
+    if (value === undefined)
+        return undefined;
+    return normalizeUnitCoordinate(value, fieldName);
+}
+function normalizeOptionalString(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = String(value || '').trim();
+    return normalized || undefined;
+}
+function normalizeNullableString(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const normalized = String(value || '').trim();
+    return normalized || null;
+}
+function normalizeOptionalInstructionType(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const normalized = normalizeInstructionType(value);
+    if (!normalized) {
+        throw new AnnotatedAttachmentCommandError('instructionType must be one of: review, question, change, issue, idea');
+    }
+    return normalized;
+}
+function normalizeOptionalColor(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    const normalized = String(value || '').trim();
+    return normalized || null;
+}
+function requireSession(deps, workspaceId, sessionId) {
+    const normalized = typeof sessionId === 'string' ? sessionId.trim() : '';
+    if (!normalized) {
+        throw new AnnotatedAttachmentCommandError('sessionId is required');
+    }
+    const session = deps.getSession({ workspaceId, sessionId: normalized });
+    if (!session) {
+        throw new AnnotatedAttachmentCommandError(`Annotated attachment session ${normalized} not found.`, 'MCP_NOT_FOUND', 404);
+    }
+    return session;
+}
+function createMarker(deps, args, order) {
+    const kind = normalizeKind(args.kind ?? args.type);
+    const instruction = normalizeOptionalString(args.instruction ?? args.text);
+    if (!instruction) {
+        throw new AnnotatedAttachmentCommandError('instruction is required');
+    }
+    const base = {
+        id: deps.generateAnnotationId(),
+        order,
+        kind,
+        markerType: normalizeOptionalInstructionType(args.instructionType) ?? 'review',
+        instruction,
+        color: normalizeOptionalColor(args.color) ?? null,
+    };
+    if (kind === 'pin' || kind === 'text-note') {
+        return {
+            ...base,
+            kind,
+            x: normalizeUnitCoordinate(args.x, 'x'),
+            y: normalizeUnitCoordinate(args.y, 'y'),
+        };
+    }
+    if (kind === 'arrow') {
+        return {
+            ...base,
+            kind,
+            x: normalizeUnitCoordinate(args.x, 'x'),
+            y: normalizeUnitCoordinate(args.y, 'y'),
+            x2: normalizeUnitCoordinate(args.x2, 'x2'),
+            y2: normalizeUnitCoordinate(args.y2, 'y2'),
+        };
+    }
+    return {
+        ...base,
+        kind,
+        x: normalizeUnitCoordinate(args.x, 'x'),
+        y: normalizeUnitCoordinate(args.y, 'y'),
+        width: normalizeUnitCoordinate(args.width, 'width'),
+        height: normalizeUnitCoordinate(args.height, 'height'),
+    };
+}
+function createMarkers(deps, markersInput, startingOrder) {
+    const markers = Array.isArray(markersInput) ? markersInput : null;
+    if (!markers || markers.length === 0) {
+        throw new AnnotatedAttachmentCommandError('markers must be a non-empty array');
+    }
+    return markers.map((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            throw new AnnotatedAttachmentCommandError(`markers[${index}] must be an object`);
+        }
+        return createMarker(deps, entry, startingOrder + index);
+    });
+}
+function updateMarker(existing, args) {
+    const instruction = normalizeNullableString(args.instruction);
+    const instructionType = normalizeOptionalInstructionType(args.instructionType);
+    const color = normalizeOptionalColor(args.color);
+    const nextInstruction = instruction === undefined ? existing.instruction : (instruction || '');
+    const nextMarkerType = instructionType === undefined ? existing.markerType : (instructionType || undefined);
+    const nextColor = color === undefined ? existing.color : color;
+    if (!nextInstruction.trim()) {
+        throw new AnnotatedAttachmentCommandError('instruction cannot be empty');
+    }
+    if (existing.kind === 'pin' || existing.kind === 'text-note') {
+        return {
+            ...existing,
+            instruction: nextInstruction,
+            markerType: nextMarkerType,
+            color: nextColor,
+            x: normalizeOptionalUnitCoordinate(args.x, 'x') ?? existing.x,
+            y: normalizeOptionalUnitCoordinate(args.y, 'y') ?? existing.y,
+        };
+    }
+    if (existing.kind === 'arrow') {
+        return {
+            ...existing,
+            instruction: nextInstruction,
+            markerType: nextMarkerType,
+            color: nextColor,
+            x: normalizeOptionalUnitCoordinate(args.x, 'x') ?? existing.x,
+            y: normalizeOptionalUnitCoordinate(args.y, 'y') ?? existing.y,
+            x2: normalizeOptionalUnitCoordinate(args.x2, 'x2') ?? existing.x2,
+            y2: normalizeOptionalUnitCoordinate(args.y2, 'y2') ?? existing.y2,
+        };
+    }
+    return {
+        ...existing,
+        instruction: nextInstruction,
+        markerType: nextMarkerType,
+        color: nextColor,
+        x: normalizeOptionalUnitCoordinate(args.x, 'x') ?? existing.x,
+        y: normalizeOptionalUnitCoordinate(args.y, 'y') ?? existing.y,
+        width: normalizeOptionalUnitCoordinate(args.width, 'width') ?? existing.width,
+        height: normalizeOptionalUnitCoordinate(args.height, 'height') ?? existing.height,
+    };
+}
+function metadata(session, extra = {}) {
+    return {
+        sessionId: session.id,
+        imageAssetId: session.baseImageAssetId,
+        taskId: session.taskId || null,
+        ...extra,
+    };
+}
+export function createAnnotatedAttachmentCommandService(deps) {
+    return {
+        reviewImage(context, input) {
+            const existingSessionId = typeof input.sessionId === 'string' ? input.sessionId.trim() : '';
+            const markers = createMarkers(deps, input.markers, 0);
+            let session = existingSessionId
+                ? requireSession(deps, context.workspaceId, existingSessionId)
+                : deps.createSession({
+                    workspaceId: context.workspaceId,
+                    taskId: input.taskId || null,
+                    baseImageAssetId: input.imageAssetId,
+                    title: typeof input.title === 'string' ? input.title : null,
+                    globalInstruction: typeof input.sessionInstruction === 'string' ? input.sessionInstruction : null,
+                    actorId: context.actorId,
+                });
+            if (session.baseImageAssetId !== input.imageAssetId) {
+                throw new AnnotatedAttachmentCommandError(`Session ${session.id} does not belong to image ${input.imageAssetId}.`, 'MCP_ATTACHMENT_CONFLICT', 409);
+            }
+            if (input.taskId && session.taskId && session.taskId !== input.taskId) {
+                throw new AnnotatedAttachmentCommandError(`Session ${session.id} does not belong to task ${input.taskId}.`, 'MCP_ATTACHMENT_CONFLICT', 409);
+            }
+            const annotations = existingSessionId
+                ? [...session.annotations, ...markers.map((marker, index) => ({
+                        ...marker,
+                        order: session.annotations.length + index,
+                    }))]
+                : markers;
+            session = deps.updateSession({
+                workspaceId: context.workspaceId,
+                sessionId: session.id,
+                title: input.title === undefined ? undefined : normalizeNullableString(input.title),
+                globalInstruction: input.sessionInstruction === undefined
+                    ? undefined
+                    : normalizeNullableString(input.sessionInstruction),
+                annotations: annotations.map((annotation, index) => ({ ...annotation, order: index })),
+                actorId: context.actorId,
+            });
+            return {
+                session,
+                markers,
+                metadata: metadata(session, {
+                    taskId: input.taskId || null,
+                    markerCount: markers.length,
+                    reusedSession: Boolean(existingSessionId),
+                }),
+            };
+        },
+        addMarker(context, input) {
+            const session = requireSession(deps, context.workspaceId, input.sessionId);
+            const marker = createMarker(deps, input, session.annotations.length);
+            const updated = deps.updateSession({
+                workspaceId: context.workspaceId,
+                sessionId: session.id,
+                annotations: [...session.annotations, marker].map((annotation, index) => ({ ...annotation, order: index })),
+                actorId: context.actorId,
+            });
+            return {
+                session: updated,
+                marker,
+                metadata: metadata(updated, { markerId: marker.id, kind: marker.kind }),
+            };
+        },
+        bulkAddMarkers(context, input) {
+            const session = requireSession(deps, context.workspaceId, input.sessionId);
+            const markers = createMarkers(deps, input.markers, session.annotations.length);
+            const updated = deps.updateSession({
+                workspaceId: context.workspaceId,
+                sessionId: session.id,
+                annotations: [...session.annotations, ...markers]
+                    .map((annotation, index) => ({ ...annotation, order: index })),
+                actorId: context.actorId,
+            });
+            return {
+                session: updated,
+                markers,
+                metadata: metadata(updated, { markerCount: markers.length }),
+            };
+        },
+        updateMarker(context, input) {
+            const session = requireSession(deps, context.workspaceId, input.sessionId);
+            const markerId = String(input.markerId || '').trim();
+            if (!markerId) {
+                throw new AnnotatedAttachmentCommandError('markerId is required');
+            }
+            const existing = session.annotations.find((annotation) => annotation.id === markerId);
+            if (!existing) {
+                throw new AnnotatedAttachmentCommandError(`Marker ${markerId} not found in session ${session.id}.`, 'MCP_NOT_FOUND', 404);
+            }
+            const marker = updateMarker(existing, input);
+            const updated = deps.updateSession({
+                workspaceId: context.workspaceId,
+                sessionId: session.id,
+                annotations: session.annotations.map((annotation, index) => (annotation.id === markerId ? { ...marker, order: index } : { ...annotation, order: index })),
+                actorId: context.actorId,
+            });
+            return {
+                session: updated,
+                marker,
+                metadata: metadata(updated, { markerId }),
+            };
+        },
+        reorderMarker(context, input) {
+            const session = requireSession(deps, context.workspaceId, input.sessionId);
+            const markerId = String(input.markerId || '').trim();
+            if (!markerId) {
+                throw new AnnotatedAttachmentCommandError('markerId is required');
+            }
+            const targetIndex = Number(input.toIndex);
+            if (!Number.isFinite(targetIndex)) {
+                throw new AnnotatedAttachmentCommandError('toIndex must be a number');
+            }
+            const fromIndex = session.annotations.findIndex((annotation) => annotation.id === markerId);
+            if (fromIndex === -1) {
+                throw new AnnotatedAttachmentCommandError(`Marker ${markerId} not found.`, 'MCP_NOT_FOUND', 404);
+            }
+            const toIndex = Math.max(0, Math.min(session.annotations.length - 1, Math.floor(targetIndex)));
+            const annotations = session.annotations.map((annotation) => ({ ...annotation }));
+            const [moved] = annotations.splice(fromIndex, 1);
+            annotations.splice(toIndex, 0, moved);
+            const updated = deps.updateSession({
+                workspaceId: context.workspaceId,
+                sessionId: session.id,
+                annotations: annotations.map((annotation, index) => ({ ...annotation, order: index })),
+                actorId: context.actorId,
+            });
+            return {
+                session: updated,
+                metadata: metadata(updated, { markerId, toIndex: targetIndex }),
+            };
+        },
+        deleteMarker(context, input) {
+            const session = requireSession(deps, context.workspaceId, input.sessionId);
+            const markerId = String(input.markerId || '').trim();
+            if (!markerId) {
+                throw new AnnotatedAttachmentCommandError('markerId is required');
+            }
+            if (!session.annotations.some((annotation) => annotation.id === markerId)) {
+                throw new AnnotatedAttachmentCommandError(`Marker ${markerId} not found in session ${session.id}.`, 'MCP_NOT_FOUND', 404);
+            }
+            const updated = deps.updateSession({
+                workspaceId: context.workspaceId,
+                sessionId: session.id,
+                annotations: session.annotations
+                    .filter((annotation) => annotation.id !== markerId)
+                    .map((annotation, index) => ({ ...annotation, order: index })),
+                actorId: context.actorId,
+            });
+            return {
+                session: updated,
+                deletedMarkerId: markerId,
+                metadata: metadata(updated, { markerId }),
+            };
+        },
+    };
+}

package/dist/annotatedAttachments/service.d.ts

@@ -8,6 +8,7 @@ export interface AnnotatedAttachmentServiceDeps {
     sessionStore: AnnotatedAttachmentSessionStore;
     normalizeWorkspaceId: (workspaceId?: string | null) => string;
     resolveWorkspaceActor: (workspaceId: string, actorRef: unknown) => TaskActor | null;
+    taskExists: (workspaceId: string, taskId: string) => boolean;
     generateEntityId: (prefix: string) => string;
     createRuleError: (message: string, statusCode?: number, code?: string) => Error;
 }
@@ -34,6 +35,7 @@ export declare function createAnnotatedAttachmentSessionService(deps: AnnotatedA
 export declare function updateAnnotatedAttachmentSessionService(deps: AnnotatedAttachmentServiceDeps, input: {
     workspaceId?: string | null;
     sessionId: string;
+    taskId?: string | null;
     title?: string | null;
     globalInstruction?: string | null;
     annotations?: AnnotatedAttachmentAnnotation[];

package/dist/annotatedAttachments/service.js

@@ -10,7 +10,7 @@ function hydrateSession(deps, session) {
         updatedByActor: session.updatedByActorId ? deps.resolveWorkspaceActor(session.workspaceId, session.updatedByActorId) : null,
     };
 }
-function getRequiredImageAsset(deps, workspaceId, taskId, assetId) {
+function getRequiredImageAsset(deps, workspaceId, assetId) {
     const asset = deps.workspaceAssetStore?.get(assetId, workspaceId) || null;
     if (!asset || asset.deletedAt) {
         throw deps.createRuleError('Base image asset not found.', 404, 'ANNOTATED_ATTACHMENT_IMAGE_NOT_FOUND');
@@ -18,16 +18,13 @@ function getRequiredImageAsset(deps, workspaceId, taskId, assetId) {
     if (asset.kind !== 'image') {
         throw deps.createRuleError('Base asset must be an image.', 400, 'ANNOTATED_ATTACHMENT_IMAGE_REQUIRED');
     }
-    if (!taskId) {
-        return asset;
-    }
-    const linked = deps.workspaceAssetStore?.listLinksForAsset(asset.assetId, workspaceId)
-        .some((entry) => !entry.deletedAt && entry.taskId === taskId);
-    if (!linked) {
-        throw deps.createRuleError('Base image asset must be attached to the target task.', 400, 'ANNOTATED_ATTACHMENT_IMAGE_UNLINKED');
-    }
     return asset;
 }
+function assertTaskExists(deps, workspaceId, taskId) {
+    if (taskId && !deps.taskExists(workspaceId, taskId)) {
+        throw deps.createRuleError('Target task not found.', 404, 'ANNOTATED_ATTACHMENT_TASK_NOT_FOUND');
+    }
+}
 function toImageRef(asset) {
     const displayName = String(asset.logicalName || asset.originalFilename || asset.assetId).trim() || asset.assetId;
     return {
@@ -64,7 +61,8 @@ export function createAnnotatedAttachmentSessionService(deps, input) {
     const baseImageAssetId = normalizeId(input.baseImageAssetId);
     if (!baseImageAssetId)
         throw deps.createRuleError('baseImageAssetId is required.', 400, 'ANNOTATED_ATTACHMENT_IMAGE_REQUIRED');
-    getRequiredImageAsset(deps, workspaceId, taskId, baseImageAssetId);
+    getRequiredImageAsset(deps, workspaceId, baseImageAssetId);
+    assertTaskExists(deps, workspaceId, taskId);
     const actorId = normalizeId(input.actorId) || null;
     const created = deps.sessionStore.create({
         id: deps.generateEntityId('annotated-attachment-session'),
@@ -84,10 +82,13 @@ export function updateAnnotatedAttachmentSessionService(deps, input) {
     const existing = deps.sessionStore.get(input.sessionId, workspaceId);
     if (!existing)
         throw deps.createRuleError('Annotated attachment session not found.', 404, 'ANNOTATED_ATTACHMENT_SESSION_NOT_FOUND');
-    getRequiredImageAsset(deps, workspaceId, existing.taskId, existing.baseImageAssetId);
+    const taskId = input.taskId === undefined ? existing.taskId : normalizeId(input.taskId);
+    getRequiredImageAsset(deps, workspaceId, existing.baseImageAssetId);
+    assertTaskExists(deps, workspaceId, taskId);
     const updated = deps.sessionStore.update({
         id: input.sessionId,
         workspaceId,
+        taskId: input.taskId,
         title: input.title,
         globalInstruction: input.globalInstruction,
         annotations: input.annotations,
@@ -104,7 +105,7 @@ export function buildAnnotatedAttachmentPayloadService(deps, input) {
     const session = deps.sessionStore.get(input.sessionId, workspaceId);
     if (!session)
         throw deps.createRuleError('Annotated attachment session not found.', 404, 'ANNOTATED_ATTACHMENT_SESSION_NOT_FOUND');
-    const asset = getRequiredImageAsset(deps, workspaceId, session.taskId, session.baseImageAssetId);
+    const asset = getRequiredImageAsset(deps, workspaceId, session.baseImageAssetId);
     const annotations = session.annotations.map((annotation) => {
         const cropHint = buildAnnotationCropHint(annotation);
         return cropHint ? { ...annotation, cropHint } : { ...annotation };

package/dist/cli.js

@@ -6,6 +6,7 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { TASKFORCE_CLOUD_ENVIRONMENTS } from './config/cloudEnvironment.js';
 import { resolveDeploymentConfig } from './config/deployment.js';
+import { resolveOpenPortSearchMax } from './cliOpenPort.js';
 /**
  * Taskforce CLI
  *
@@ -60,6 +61,13 @@ function getCliVersion() {
         return 'unknown';
     }
 }
+function getCliInstallationPaths() {
+    const executablePath = realpathSync(fileURLToPath(import.meta.url));
+    return {
+        packageRoot: realpathSync(join(dirname(executablePath), '..')),
+        executablePath,
+    };
+}
 /**
  * Find project root by traversing up to find package.json with taskforce
  */
@@ -141,24 +149,106 @@ function printStatus(projectRoot) {
  * Main CLI logic
  */
 async function main() {
-    if (command === 'help' || (command !== 'open' && command !== 'mcp' && command !== 'version' && command !== 'status')) {
+    if (command === 'help' || (command !== 'open' && command !== 'mcp' && command !== 'service' && command !== 'version' && command !== 'status' && command !== 'update' && command !== 'db-health')) {
         console.log('\x1b[35mTaskforce CLI\x1b[0m');
         console.log('\nUsage:');
         console.log('  taskforce <command> [options]');
         console.log('\nAvailable commands:');
-        console.log('  open [port]                         - Starts Taskforce on an unused port and opens it (default start port 5174)');
-        console.log('  mcp [path]                          - Starts the Model Context Protocol (MCP) server for the specified project');
+        console.log('  open [port]                         - Opens Taskforce (shared-service attach when enabled; legacy start port 5174)');
+        console.log('  mcp [path]                          - Attaches an MCP stdio client to the shared local service');
+        console.log('  service [path]                      - Runs the shared local Taskforce service in the foreground');
+        console.log('  service start|status|stop [path]    - Manages the detached shared local service');
         console.log('  status                              - Prints the resolved Taskforce CLI/runtime status');
+        console.log('  db-health [--checkpoint=passive|truncate] - Inspects local SQLite WAL health; truncate requires idle exclusive ownership');
+        console.log('  update [--check]                    - Checks for or installs a verified Global CLI update');
         console.log('  version                             - Prints the Taskforce CLI version');
         console.log('  help                                - Shows this help message');
         console.log('\nFlags:');
         console.log('  -v, --version                       - Prints the Taskforce CLI version');
+        console.log('\nUpdate check exit codes:');
+        console.log('  0 current, 10 update available, 2 indeterminate or unsupported');
         return;
     }
     if (command === 'version') {
         printVersion(versionFlagRequested);
         return;
     }
+    if (command === 'update') {
+        const { runTaskforceUpdateCli } = await import('./update/updateCli.js');
+        const paths = getCliInstallationPaths();
+        process.exitCode = await runTaskforceUpdateCli(args.slice(1), {
+            target: 'global-cli',
+            version: getCliVersion(),
+            runtimeMode: 'local',
+            ...paths,
+        });
+        return;
+    }
+    if (command === 'service') {
+        const { runLocalServiceCli } = await import('./service/localServiceCli.js');
+        process.exitCode = await runLocalServiceCli(args.slice(1), {
+            appVersion: getCliVersion(),
+            executablePath: process.execPath,
+            cliEntryPath: realpathSync(fileURLToPath(import.meta.url)),
+            execArgv: process.execArgv,
+        });
+        return;
+    }
+    if (command === 'db-health') {
+        const projectRoot = findProjectRoot() || process.cwd();
+        const dbPath = join(projectRoot, '.taskforce', 'taskforce.db');
+        if (!existsSync(dbPath)) {
+            throw new Error(`Taskforce SQLite database was not found at ${dbPath}.`);
+        }
+        const checkpointArg = args.slice(1).find((value) => value.startsWith('--checkpoint='));
+        const checkpointMode = checkpointArg?.slice('--checkpoint='.length) || 'none';
+        if (!['none', 'passive', 'truncate'].includes(checkpointMode)) {
+            throw new Error('Invalid checkpoint mode. Use passive or truncate.');
+        }
+        const unknownArgs = args.slice(1).filter((value) => !value.startsWith('--checkpoint='));
+        if (unknownArgs.length > 0) {
+            throw new Error(`Unknown db-health option: ${unknownArgs[0]}`);
+        }
+        const { SqliteAdapter } = await import('./storage/sqliteAdapter.js');
+        const { inspectSqliteWalHealth, listSqliteWalHolders, truncateSqliteWalSafely, } = await import('./storage/sqliteWalHealth.js');
+        let syncProcessLock = null;
+        let db = null;
+        try {
+            syncProcessLock = checkpointMode === 'truncate'
+                ? await (async () => {
+                    const { acquireLocalSyncProcessLock } = await import('./sync/coordinator/localSyncProcessLock.js');
+                    const lock = await acquireLocalSyncProcessLock({
+                        projectRoot,
+                        databaseIdentity: dbPath,
+                        databaseIdentityKind: 'path',
+                    });
+                    if (!lock.owned) {
+                        throw new Error('SQLite WAL truncate is blocked because another Taskforce process owns workspace sync.');
+                    }
+                    return lock;
+                })()
+                : null;
+            const holders = listSqliteWalHolders(dbPath).filter((holder) => holder.pid !== process.pid);
+            db = new SqliteAdapter(dbPath);
+            const health = checkpointMode === 'truncate'
+                ? truncateSqliteWalSafely({ db, dbPath, otherHolders: holders })
+                : inspectSqliteWalHealth({ db, dbPath, passiveCheckpoint: checkpointMode === 'passive' });
+            console.log(JSON.stringify({
+                ...health,
+                holders,
+                maintenance: checkpointMode,
+            }, null, 2));
+        }
+        finally {
+            try {
+                db?.close();
+            }
+            finally {
+                await syncProcessLock?.release();
+            }
+        }
+        return;
+    }
     // 1. Handle MCP Command
     if (command === 'mcp') {
         const projectPath = args[1] || process.cwd();
@@ -166,8 +256,28 @@ async function main() {
         process.argv[2] = projectPath;
         try {
             console.error(`\x1b[32m✓ Starting Taskforce MCP server for ${projectPath}\x1b[0m`);
-            // Import the MCP server - it will start automatically via its top-level await
-            await import('./mcp/server.js');
+            const clientMode = String(process.env.TASKFORCE_SHARED_LOCAL_MCP_CLIENT_MODE || 'proxy').trim().toLowerCase();
+            if (clientMode === 'proxy') {
+                process.env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED ??= 'true';
+                await import('./mcp/server.js');
+            }
+            else if (clientMode === 'legacy') {
+                const rollbackVersion = String(process.env.TASKFORCE_SHARED_LOCAL_MCP_ROLLBACK_VERSION || '').trim();
+                const cliVersion = getCliVersion();
+                if (!rollbackVersion || rollbackVersion !== cliVersion) {
+                    throw new Error('Legacy MCP rollback requires TASKFORCE_SHARED_LOCAL_MCP_ROLLBACK_VERSION '
+                        + `to exactly match this CLI version (${cliVersion}).`);
+                }
+                if (String(process.env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED || '').trim().toLowerCase() !== 'false') {
+                    throw new Error('Legacy MCP rollback requires TASKFORCE_SHARED_LOCAL_MCP_ENABLED=false after all clients are quiesced and the shared service is stopped.');
+                }
+                process.env.TASKFORCE_SHARED_LOCAL_MCP_CLIENT_MODE = 'legacy';
+                process.env.TASKFORCE_SHARED_LOCAL_MCP_ENABLED = 'false';
+                await import('./mcp/legacyServer.js');
+            }
+            else {
+                throw new Error('TASKFORCE_SHARED_LOCAL_MCP_CLIENT_MODE must be legacy or proxy.');
+            }
         }
         catch (e) {
             console.error('\x1b[31m❌ Failed to start MCP server:\x1b[0m', e);
@@ -191,8 +301,7 @@ async function main() {
         return;
     }
     console.log(`\x1b[32m✓ Found Taskforce in ${projectRoot}\x1b[0m`);
-    // 2. Always start a new server on an unused port
-    console.log(`\x1b[36m✨ Starting Taskforce server on an unused port...\x1b[0m`);
+    let releaseLocalSyncProcessLock = null;
     try {
         // Local CLI launches should default to local runtime unless explicitly overridden.
         // This prevents ambient TASKFORCE_DB_PROVIDER=postgres from flipping runtime to cloud.
@@ -215,7 +324,23 @@ async function main() {
         else if (hasExternalCloudEndpoint) {
             console.log('\x1b[36m[Taskforce] Using cloud endpoint from environment variables\x1b[0m');
         }
+        const { openTaskforceViaLocalService, shouldOpenViaLocalService } = await import('./service/localServiceOpen.js');
+        if (shouldOpenViaLocalService(process.env)) {
+            console.log(`\x1b[36m✨ Discovering the shared Taskforce service...\x1b[0m`);
+            await openTaskforceViaLocalService({
+                projectRoot,
+                env: process.env,
+                executablePath: process.execPath,
+                cliEntryPath: realpathSync(fileURLToPath(import.meta.url)),
+                execArgv: process.execArgv,
+                openBrowser,
+                log: (message) => console.log(`\x1b[32m✓ ${message}\x1b[0m`),
+            });
+            return;
+        }
+        console.log(`\x1b[36m✨ Starting Taskforce server on an unused port...\x1b[0m`);
         const { createStandaloneServer } = await import('./server/index.js');
+        const { acquireLocalServiceOwnershipForRuntime } = await import('./server/localServiceOwnershipBootstrap.js');
         const { createServer } = await import('net');
         /**
          * Find a free port starting from preferredPort
@@ -242,10 +367,33 @@ async function main() {
                 });
             });
         };
-        const targetPort = await findPort(preferredPort, preferredPort + 10);
+        const targetPort = await findPort(preferredPort, resolveOpenPortSearchMax(preferredPort));
+        const ownership = await acquireLocalServiceOwnershipForRuntime(projectRoot, process.env);
+        if (!ownership?.owned || !ownership.localDataOwnerPermit) {
+            throw new Error('Legacy open rollback could not acquire exclusive local data ownership. Stop the shared service before retrying.');
+        }
+        const localSyncProcessLock = ownership.syncProcessLock || undefined;
+        releaseLocalSyncProcessLock = () => ownership.release();
         const server = createStandaloneServer({
             projectRoot,
-            port: targetPort
+            port: targetPort,
+            localSyncProcessLock,
+            localDataOwnerPermit: ownership.localDataOwnerPermit,
+            afterShutdown: () => ownership.release(),
+        });
+        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 releaseLocalSyncProcessLock?.();
+                }
+            })
+                .finally(() => {
+                console.error('\x1b[31m❌ Taskforce server failed:\x1b[0m', String(error?.message || error));
+                process.exit(1);
+            });
         });
         server.listen(targetPort, () => {
             const url = `http://localhost:${targetPort}/taskforce/`;
@@ -255,6 +403,7 @@ async function main() {
         });
     }
     catch (e) {
+        await releaseLocalSyncProcessLock?.();
         console.error('\x1b[31m❌ Failed to start server:\x1b[0m', e.message);
         process.exit(1);
     }

package/dist/cliOpenPort.d.ts

@@ -0,0 +1 @@
+export declare function resolveOpenPortSearchMax(preferredPort: number, env?: NodeJS.ProcessEnv): number;

package/dist/cliOpenPort.js

@@ -0,0 +1,4 @@
+export function resolveOpenPortSearchMax(preferredPort, env = process.env) {
+    const exact = /^(1|true|yes|on)$/i.test(String(env.TASKFORCE_REQUIRE_EXACT_PORT || '').trim());
+    return exact ? preferredPort : preferredPort + 10;
+}