@taskforcehq/taskforce 0.3.330 → 0.3.332

package/dist/services/executorPhaseAIssuerCore.js

@@ -14,6 +14,8 @@ const TRANSITIVE_TAG_KEYS = [
     'TaskforceWorkspaceHash',
     'TaskforceSource',
 ];
+const verifiedWorkloadJwtClaimsBrand = Symbol('verifiedExecutorPhaseAWorkloadJwtClaims');
+const verifiedWorkloadJwtClaims = new WeakSet();
 function timestamp(value, field) {
     const parsed = Date.parse(value);
     if (!Number.isFinite(parsed))
@@ -155,6 +157,111 @@ export async function signExecutorPhaseAWorkloadJwt(claims, signer) {
         throw new TypeError('The OIDC signer returned a non-RSA-2048 signature.');
     return `${signingInput}.${signature.toString('base64url')}`;
 }
+function decodeCanonicalJwtSegment(segment, field) {
+    if (!/^[A-Za-z0-9_-]+$/.test(segment))
+        throw new TypeError(`The workload JWT ${field} is not base64url.`);
+    const bytes = Buffer.from(segment, 'base64url');
+    if (bytes.toString('base64url') !== segment)
+        throw new TypeError(`The workload JWT ${field} is not canonical base64url.`);
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new TypeError(`The workload JWT ${field} is not valid JSON.`);
+    }
+    if (canonicalizeExecutorPhaseAJson(value).toString('base64url') !== segment) {
+        throw new TypeError(`The workload JWT ${field} is not canonical JSON.`);
+    }
+    return value;
+}
+export function verifyExecutorPhaseAWorkloadJwt(jwt, bundle, keys, now = new Date()) {
+    if (jwt.length > 16_384)
+        throw new TypeError('The workload JWT exceeds the maximum size.');
+    const segments = jwt.split('.');
+    if (segments.length !== 3)
+        throw new TypeError('The workload JWT must contain exactly three segments.');
+    const [headerSegment, payloadSegment, signatureSegment] = segments;
+    const header = decodeCanonicalJwtSegment(headerSegment, 'header');
+    if (!header || typeof header !== 'object' || Array.isArray(header)
+        || Object.keys(header).sort().join(',') !== 'alg,kid,typ'
+        || header.alg !== 'RS256'
+        || header.typ !== 'JWT'
+        || typeof header.kid !== 'string') {
+        throw new TypeError('The workload JWT header is invalid.');
+    }
+    const key = keys.find((candidate) => candidate.keyId === header.kid);
+    const signature = Buffer.from(signatureSegment, 'base64url');
+    const nowMs = now.getTime();
+    if (new Set(keys.map((candidate) => candidate.keyId)).size !== keys.length
+        || !key || (key.status !== 'active' && key.status !== 'retiring')
+        || nowMs < timestamp(key.validFrom, 'key.validFrom')
+        || nowMs >= timestamp(key.validUntil, 'key.validUntil') || key.publicKey.asymmetricKeyType !== 'rsa'
+        || key.publicKey.asymmetricKeyDetails?.modulusLength !== 2048
+        || !/^[A-Za-z0-9_-]+$/.test(signatureSegment)
+        || signature.length !== 256 || signature.toString('base64url') !== signatureSegment
+        || !verify('RSA-SHA256', Buffer.from(`${headerSegment}.${payloadSegment}`, 'ascii'), key.publicKey, signature)) {
+        throw new TypeError('The workload JWT signature or signing key is invalid.');
+    }
+    const claims = decodeCanonicalJwtSegment(payloadSegment, 'payload');
+    assertExecutorPhaseASchema('workloadJwtClaims', claims);
+    const capability = bundle.capability.payload;
+    const grant = bundle.grant.payload;
+    const nowSeconds = Math.floor(now.getTime() / 1000);
+    const skewSeconds = EXECUTOR_PHASE_A_CROSS_SERVICE_CLOCK_SKEW_MS / 1000;
+    const grantIssuedAt = Math.floor(timestamp(grant.issuedAt, 'grant.issuedAt') / 1000);
+    const grantExpiresAt = Math.floor(timestamp(grant.expiresAt, 'grant.expiresAt') / 1000);
+    const phaseDeadline = Math.floor(timestamp(grant.phase === 'cleanup' ? capability.cleanupDeadline : capability.mutationDeadline, 'phaseDeadline') / 1000);
+    const runDigest = createHash('sha256').update(capability.runId, 'utf8').digest('base64url');
+    const tags = claims['https://aws.amazon.com/tags'];
+    const expectedTags = grant.sessionTags;
+    if (claims.iss !== capability.oidcIssuer || claims.aud !== capability.oidcAudience
+        || claims.sub !== `tfr:${runDigest}:${grant.phase}`
+        || claims['https://aws.amazon.com/source_identity'] !== executorPhaseASourceIdentity(capability.runId, grant.phase)
+        || claims.iat < grantIssuedAt - skewSeconds || claims.iat > nowSeconds + skewSeconds
+        || claims.nbf !== claims.iat
+        || nowSeconds >= claims.exp + skewSeconds || claims.exp <= claims.iat || claims.exp - claims.iat > JWT_TTL_SECONDS
+        || claims.exp > grantExpiresAt || claims.exp > phaseDeadline
+        || tags.principal_tags.TaskforceRun[0] !== expectedTags.TaskforceRun
+        || tags.principal_tags.TaskforceReceipt[0] !== expectedTags.TaskforceReceipt
+        || tags.principal_tags.TaskforcePhase[0] !== expectedTags.TaskforcePhase
+        || tags.principal_tags.TaskforceWorkspaceHash[0] !== expectedTags.TaskforceWorkspaceHash
+        || tags.principal_tags.TaskforceSource[0] !== expectedTags.TaskforceSource
+        || claims.taskforce.receiptId !== capability.receiptId
+        || claims.taskforce.receiptSha256 !== capability.receiptSha256
+        || claims.taskforce.workspaceId !== capability.workspaceId
+        || claims.taskforce.taskId !== capability.taskId
+        || claims.taskforce.runId !== capability.runId
+        || claims.taskforce.sourceCommit !== capability.sourceCommit
+        || claims.taskforce.accountId !== capability.accountId
+        || claims.taskforce.region !== capability.region
+        || claims.taskforce.availabilityZone !== capability.availabilityZone
+        || claims.taskforce.logicalEnvelopeSha256 !== capability.logicalEnvelopeSha256
+        || claims.taskforce.budgetsSha256 !== capability.budgetsSha256
+        || claims.taskforce.roleArn !== grant.roleArn
+        || claims.taskforce.brokerKeyFingerprint !== capability.brokerKeyFingerprint
+        || claims.taskforce.grantId !== grant.grantId
+        || claims.taskforce.grantSha256 !== bundle.grantSha256
+        || claims.taskforce.senderProofSha256 !== bundle.senderProofSha256) {
+        throw new TypeError('The workload JWT claims differ from the verified grant.');
+    }
+    const verified = structuredClone(claims);
+    const freeze = (value) => {
+        if (!value || typeof value !== 'object' || Object.isFrozen(value))
+            return;
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    };
+    freeze(verified);
+    verifiedWorkloadJwtClaims.add(verified);
+    return verified;
+}
+export function assertVerifiedExecutorPhaseAWorkloadJwtClaims(claims) {
+    if (!claims || typeof claims !== 'object' || !verifiedWorkloadJwtClaims.has(claims)) {
+        throw new TypeError('The broker requires runtime-verified workload JWT claims.');
+    }
+}
 function verifyRedemptionResponse(response, request, cloudKeys, now) {
     assertExecutorPhaseASchema('issuerRedemptionResponse', response);
     const trustedKey = cloudKeys.find((key) => key.keyId === response.envelope.keyId && key.status !== 'disabled');

package/dist/services/taskforceAgentMcpBridge.d.ts

@@ -59,7 +59,7 @@ export declare function taskforceAgentMcpRequestId(call: TaskforceAgentMcpToolCa
 declare const MANAGED_AGENT_CAPABILITY_TOOLS: Readonly<{
     readonly tasks: readonly ["add_comment", "add_task_checklist_item", "complete_workflow_step", "get_schedule_board", "get_stats", "get_task", "get_task_attachments", "get_task_checklist", "get_task_workflow", "list_task_relationships", "list_tasks", "replace_task_checklist", "search_tasks", "update_task_checklist_item"];
     readonly planning: readonly ["add_initiative_comment", "add_workstream_comment", "get_initiative", "get_workstream", "list_initiatives", "list_workstreams"];
-    readonly documents: readonly ["get_document", "get_document_reviews", "search_documents"];
+    readonly documents: readonly ["get_document", "get_document_reviews", "review_document", "search_documents"];
     readonly images: readonly ["get_image", "get_image_annotations", "search_images"];
     readonly workspace: readonly ["get_config", "get_current_profile", "list_assignees"];
 }>;

package/dist/services/taskforceAgentMcpBridge.js

@@ -75,6 +75,7 @@ const MANAGED_AGENT_CAPABILITY_TOOLS = Object.freeze({
     documents: [
         'get_document',
         'get_document_reviews',
+        'review_document',
         'search_documents',
     ],
     images: [
@@ -187,21 +188,50 @@ function buildToolInstructions(baseSystem, tools, allowedMutationTaskId, readOnl
     const toolLines = tools.map((tool) => (`- ${tool.name}: ${compactText(tool.description, 180)} Args: ${describeToolSchema(tool.inputSchema)}`));
     const taskScope = String(allowedMutationTaskId || '').trim();
     const canCompleteWorkflow = tools.some((tool) => tool.name === 'complete_workflow_step');
+    const canReviewDocuments = tools.some((tool) => tool.name === 'review_document');
+    const canAddComments = tools.some((tool) => [
+        'add_comment',
+        'add_initiative_comment',
+        'add_workstream_comment',
+    ].includes(tool.name));
+    const canChangeChecklists = tools.some((tool) => [
+        'add_task_checklist_item',
+        'replace_task_checklist',
+        'update_task_checklist_item',
+    ].includes(tool.name));
+    const allowedWrites = [
+        ...(canAddComments ? ['comments'] : []),
+        ...(canChangeChecklists ? ['checklist changes'] : []),
+        ...(canReviewDocuments ? ['document review feedback'] : []),
+        ...(canCompleteWorkflow ? ['completion of the current owned workflow step'] : []),
+    ];
+    const allowedWritesSentence = allowedWrites.length > 0
+        ? `Allowed writes: ${allowedWrites.join(', ')}.${canCompleteWorkflow ? ' Use complete_workflow_step only after finishing that step.' : ''}`
+        : 'No Taskforce writes are enabled for this run.';
+    const availableToolNames = new Set(tools.map((tool) => tool.name));
+    const selectedToolCallExample = [
+        { name: 'get_task', arguments: { id: 'T-123' } },
+        { name: 'get_document', arguments: { documentId: 'D-123' } },
+        { name: 'get_initiative', arguments: { id: 'IN-123' } },
+        { name: 'get_workstream', arguments: { id: 'WS-123' } },
+        { name: 'get_config', arguments: {} },
+    ].find((example) => availableToolNames.has(example.name));
+    const toolCallExample = selectedToolCallExample
+        ? { tool: selectedToolCallExample.name, arguments: selectedToolCallExample.arguments }
+        : { tool: tools[0]?.name, arguments: {} };
     return [
         baseSystem,
         '',
         'Taskforce project tools are attached invisibly by the server. Use them when the user asks about current Taskforce tasks, initiatives, workstreams, documents, images, annotations, config, stats, or specific reference labels such as T-123, IN-123, WS-123, D-123, or I-123.',
         readOnly
             ? 'This run is read-only. Use Taskforce tools only to inspect data; no Taskforce writes are available.'
-            : canCompleteWorkflow
-                ? 'Allowed writes: task comments, checklist changes, and completion of the current owned workflow step. Use complete_workflow_step only after finishing that step.'
-                : 'Allowed writes: task comments and checklist changes.',
+            : allowedWritesSentence,
         ...(canCompleteWorkflow && !readOnly ? [
             'For workflow-step work, call get_task_workflow before acting. Reuse its completionCall arguments exactly; never invent or reuse workflow IDs. If requiresCommentEvidence is true, call add_comment and add its returned comment.id as evidenceCommentId. After all required work succeeds, call complete_workflow_step before answering. A comment or other task mutation does not complete the workflow step.',
         ] : []),
-        ...(taskScope ? [`This run is task-scoped to ${taskScope}. Mutating Taskforce tools must target only this task.`] : []),
+        ...(taskScope ? [`This run is task-scoped to ${taskScope}. Task-targeted mutations must target only this task.`] : []),
         'To use a Taskforce tool, respond with only one JSON object and no prose:',
-        '{"tool":"get_task","arguments":{"id":"T-123"}}',
+        JSON.stringify(toolCallExample),
         'After the server returns a tool result, answer the user normally unless another Taskforce tool is required; if another tool is required, respond with only one more tool-call JSON object.',
         'Do not mention MCP setup or credentials.',
         'Available Taskforce tools:',

package/dist/shared/executorPhaseASchemaValidation.js

@@ -1,4 +1,4 @@
-import Ajv2020 from 'ajv/dist/2020.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
 import approvalReceiptSchema from './executorPhaseASchemas/approval-receipt.schema.json' with { type: 'json' };
 import driftAttestationSchema from './executorPhaseASchemas/drift-attestation.schema.json' with { type: 'json' };
 import driftRequestSchema from './executorPhaseASchemas/drift-request.schema.json' with { type: 'json' };

package/dist/storage/postgresAdapter.js

@@ -179,8 +179,9 @@ export class PostgresAdapter {
         }
         const waitStartedAt = performance.now();
         const waitResult = Atomics.wait(status, RESPONSE_STATUS_INDEX, RESPONSE_INITIAL, this.deadlines.responseTimeoutMs);
-        recordPostgresWorkerWait(payload.op, performance.now() - waitStartedAt);
+        const workerWaitMs = performance.now() - waitStartedAt;
         if (waitResult === 'timed-out') {
+            recordPostgresWorkerWait(payload.op, workerWaitMs);
             this.quarantineWorker(worker);
             throw new PostgresWorkerOutcomeUnknownError(payload.op);
         }
@@ -190,6 +191,7 @@ export class PostgresAdapter {
         }
         const body = this.decoder.decode(responseBytes.subarray(0, responseLength));
         const parsed = JSON.parse(body);
+        recordPostgresWorkerWait(payload.op, workerWaitMs, parsed.pool);
         this.consecutiveUnexpectedExits = 0;
         if (!parsed.ok && parsed.errorCode === 'RESPONSE_BUFFER_TOO_SMALL') {
             const requiredBytes = Number(parsed.requiredBytes);

package/dist/storage/postgresRequestDiagnostics.d.ts

@@ -2,7 +2,15 @@ export type RequestPerformanceDiagnostics = {
     postgresQueryCount: number;
     postgresWorkerCallCount: number;
     postgresWorkerWaitMs: number;
+    postgresWorkerWaitMaxMs: number;
+    postgresPoolWaitingMax: number;
+    postgresPoolTotalMax: number;
+    postgresPoolIdleMin: number | null;
 };
 export declare function runWithRequestPerformanceDiagnostics<T>(enabled: boolean, callback: () => T): T;
-export declare function recordPostgresWorkerWait(operation: string, durationMs: number): void;
+export declare function recordPostgresWorkerWait(operation: string, durationMs: number, pool?: {
+    totalCount: number;
+    idleCount: number;
+    waitingCount: number;
+}): void;
 export declare function getRequestPerformanceDiagnostics(): RequestPerformanceDiagnostics | null;

package/dist/storage/postgresRequestDiagnostics.js

@@ -7,16 +7,29 @@ export function runWithRequestPerformanceDiagnostics(enabled, callback) {
         postgresQueryCount: 0,
         postgresWorkerCallCount: 0,
         postgresWorkerWaitMs: 0,
+        postgresWorkerWaitMaxMs: 0,
+        postgresPoolWaitingMax: 0,
+        postgresPoolTotalMax: 0,
+        postgresPoolIdleMin: null,
     }, callback);
 }
-export function recordPostgresWorkerWait(operation, durationMs) {
+export function recordPostgresWorkerWait(operation, durationMs, pool) {
     const diagnostics = requestPerformanceStorage.getStore();
     if (!diagnostics)
         return;
     diagnostics.postgresWorkerCallCount += 1;
     if (operation === 'query')
         diagnostics.postgresQueryCount += 1;
-    diagnostics.postgresWorkerWaitMs += Math.max(0, durationMs);
+    const boundedDurationMs = Math.max(0, durationMs);
+    diagnostics.postgresWorkerWaitMs += boundedDurationMs;
+    diagnostics.postgresWorkerWaitMaxMs = Math.max(diagnostics.postgresWorkerWaitMaxMs, boundedDurationMs);
+    if (pool) {
+        diagnostics.postgresPoolWaitingMax = Math.max(diagnostics.postgresPoolWaitingMax, pool.waitingCount);
+        diagnostics.postgresPoolTotalMax = Math.max(diagnostics.postgresPoolTotalMax, pool.totalCount);
+        diagnostics.postgresPoolIdleMin = diagnostics.postgresPoolIdleMin === null
+            ? pool.idleCount
+            : Math.min(diagnostics.postgresPoolIdleMin, pool.idleCount);
+    }
 }
 export function getRequestPerformanceDiagnostics() {
     const diagnostics = requestPerformanceStorage.getStore();

package/dist/storage/postgresWorker.js

@@ -111,6 +111,16 @@ if (!runtimeOptions.deadlines) {
 }
 const pool = createPool(connectionString, runtimeOptions.deadlines);
 const txClients = new Map();
+function withPoolSnapshot(payload) {
+    return {
+        ...payload,
+        pool: {
+            totalCount: Math.max(0, Number(pool.totalCount) || 0),
+            idleCount: Math.max(0, Number(pool.idleCount) || 0),
+            waitingCount: Math.max(0, Number(pool.waitingCount) || 0),
+        },
+    };
+}
 async function handleMessage(message) {
     const { payload } = message;
     const txId = payload.txId ? String(payload.txId) : null;
@@ -174,7 +184,7 @@ parentPort.on('message', async (message) => {
             return;
         }
         const response = await handleMessage(message);
-        writeResponse(message.statusBuffer, message.responseBuffer, response);
+        writeResponse(message.statusBuffer, message.responseBuffer, withPoolSnapshot(response));
     }
     catch (error) {
         const messageText = error instanceof Error ? error.message : String(error);
@@ -182,10 +192,10 @@ parentPort.on('message', async (message) => {
             && typeof error.code === 'string'
             ? String(error.code)
             : undefined;
-        writeResponse(message.statusBuffer, message.responseBuffer, {
+        writeResponse(message.statusBuffer, message.responseBuffer, withPoolSnapshot({
             ok: false,
             error: messageText,
             ...(databaseErrorCode ? { databaseErrorCode } : {}),
-        });
+        }));
     }
 });

package/dist/storage/postgresWorkerProtocol.d.ts

@@ -10,6 +10,11 @@ export type PostgresWorkerQueryResult = {
     rows: Record<string, unknown>[];
     rowCount?: number;
 };
+export type PostgresWorkerPoolSnapshot = {
+    totalCount: number;
+    idleCount: number;
+    waitingCount: number;
+};
 export type PostgresWorkerResponsePayload = {
     ok: boolean;
     result?: PostgresWorkerQueryResult;
@@ -18,6 +23,7 @@ export type PostgresWorkerResponsePayload = {
     databaseErrorCode?: string;
     requiredBytes?: number;
     responseToken?: string;
+    pool?: PostgresWorkerPoolSnapshot;
 };
 export type PostgresWorkerDeadlines = {
     responseTimeoutMs: number;

package/dist/storage/workflowStore.d.ts

@@ -200,7 +200,9 @@ export declare class WorkflowStore {
     installAssignmentForSync(workspaceIdRaw: string, snapshot: WorkflowAssignmentSyncRecord, options: {
         authority: 'pending-intent' | 'cloud-execution';
         expectedTaskId: string;
+        replaceAuthoritativeHistory?: boolean;
     }): WorkflowExecutionStateRecord;
+    private runAssignmentSyncTransaction;
     appendExecutionTransition(input: {
         workspaceId: string;
         executionId: string;

package/dist/storage/workflowStore.js

@@ -759,7 +759,7 @@ export class WorkflowStore {
             || snapshot.execution.updatedAt !== snapshotProjection.updatedAt) {
             throw new WorkflowAssignmentSyncConflictError('Workflow assignment execution does not match its event history.');
         }
-        return this.db.transaction(() => {
+        return this.runAssignmentSyncTransaction(Boolean(options.authority === 'cloud-execution' && options.replaceAuthoritativeHistory), () => {
             const existingForTask = this.getActiveExecutionForTask(workspaceId, snapshot.execution.taskId);
             if (existingForTask && existingForTask.id !== snapshot.execution.id) {
                 throw new WorkflowAssignmentSyncConflictError('Task already has a different active workflow execution.');
@@ -852,7 +852,14 @@ export class WorkflowStore {
                     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 `).run(snapshot.execution.id, this.tenantId, workspaceId, snapshot.execution.taskId, snapshot.template.id, snapshot.version.id, snapshot.execution.status, snapshot.execution.currentStepId || null, snapshot.execution.createdByActorId || null, snapshot.execution.updatedByActorId || null, snapshot.execution.createdAt, snapshot.execution.updatedAt, snapshot.execution.startedAt || null, snapshot.execution.completedAt || null, snapshot.execution.endedAt || null, snapshot.execution.deletedAt || null);
             }
-            const canonicalEvents = this.listExecutionEvents(workspaceId, snapshot.execution.id);
+            let canonicalEvents = this.listExecutionEvents(workspaceId, snapshot.execution.id);
+            if (options.authority === 'cloud-execution' && options.replaceAuthoritativeHistory) {
+                this.db.prepare(`
+                    DELETE FROM workflow_execution_events
+                    WHERE tenant_id = ? AND workspace_id = ? AND workflow_execution_id = ?
+                `).run(this.tenantId, workspaceId, snapshot.execution.id);
+                canonicalEvents = [];
+            }
             const authoritativeHistoryIsExactPrefix = options.authority === 'cloud-execution'
                 && snapshot.events.length < canonicalEvents.length
                 && snapshot.events.every((event, index) => canonicalJson(event) === canonicalJson(canonicalEvents[index]));
@@ -908,6 +915,36 @@ export class WorkflowStore {
                 `).run(snapshotProjection.status, snapshotProjection.currentStepId || null, snapshot.execution.updatedByActorId || null, snapshotProjection.updatedAt, snapshotProjection.startedAt || null, snapshotProjection.completedAt || null, snapshotProjection.endedAt || null, snapshot.execution.deletedAt || null, this.tenantId, workspaceId, snapshot.execution.id);
             }
             return this.getExecutionStateSnapshot(workspaceId, snapshot.execution.id);
+        });
+    }
+    runAssignmentSyncTransaction(replaceAuthoritativeHistory, apply) {
+        return this.db.transaction(() => {
+            if (!replaceAuthoritativeHistory)
+                return apply();
+            if (this.db.provider === 'postgres') {
+                throw new WorkflowAssignmentSyncConflictError('Authoritative workflow history replacement is local-runtime only.');
+            }
+            this.db.exec(`
+                DROP TRIGGER IF EXISTS trg_workflow_execution_events_no_update;
+                DROP TRIGGER IF EXISTS trg_workflow_execution_events_no_delete;
+            `);
+            try {
+                return apply();
+            }
+            finally {
+                this.db.exec(`
+                    CREATE TRIGGER IF NOT EXISTS trg_workflow_execution_events_no_update
+                    BEFORE UPDATE ON workflow_execution_events
+                    BEGIN
+                        SELECT RAISE(ABORT, 'Workflow execution events are append-only');
+                    END;
+                    CREATE TRIGGER IF NOT EXISTS trg_workflow_execution_events_no_delete
+                    BEFORE DELETE ON workflow_execution_events
+                    BEGIN
+                        SELECT RAISE(ABORT, 'Workflow execution events are append-only');
+                    END;
+                `);
+            }
         })();
     }
     appendExecutionTransition(input) {

package/dist/sync/cloudSyncApi.js

@@ -558,8 +558,10 @@ export async function prepareWorkspacePushChanges(input, dependencies = {}) {
             .filter((taskId) => taskUpsertIdSet.has(taskId) && !activeV3TaskCreateIds.has(taskId));
     }
     const ownershipFilteredChanges = input.changes.filter((change) => {
-        if (change.op === 'upsert')
-            return !activeV3TaskCreateIds.has(String(change.task?.id || '').trim());
+        if (change.op === 'upsert') {
+            const taskId = String(change.task?.id || '').trim();
+            return !activeV3TaskCreateIds.has(taskId) && !activeV3TaskDeleteIds.has(taskId);
+        }
         if (change.op === 'delete') {
             return !activeV3TaskDeleteIds.has(String(change.taskId || '').trim());
         }

package/dist/sync/collaborationSyncState.js

@@ -32,6 +32,11 @@ export function listWorkspaceSyncDocumentReviewCommentsSnapshot(deps, workspaceI
         authorActorId: comment.authorActorId,
         updatedByActorId: comment.updatedByActorId,
         deletedByActorId: comment.deletedByActorId,
+        parentCommentId: comment.parentCommentId,
+        threadStatus: comment.threadStatus,
+        threadStatusUpdatedAt: comment.threadStatusUpdatedAt,
+        resolvedAt: comment.resolvedAt,
+        resolvedByActorId: comment.resolvedByActorId,
         createdAt: comment.createdAt,
         updatedAt: comment.updatedAt,
         deletedAt: comment.deletedAt,

package/dist/sync/coordinator/localWorkspaceSyncRunner.d.ts

@@ -1,6 +1,6 @@
 import type { LocalSyncCoordinatorCommandRecord } from './localSyncCoordinatorTypes.js';
 import type { LocalSyncCoordinatorStore } from './localSyncCoordinatorStore.js';
-import { type LocalWorkspaceSyncRunnerCheckpoint, type LocalWorkspaceSyncRunnerState, type LocalWorkspaceSyncRunnerStateStore } from './localWorkspaceSyncRunnerState.js';
+import { type LocalWorkspaceSyncRunnerCheckpoint, type LocalWorkspaceSyncRunnerRetryKind, type LocalWorkspaceSyncRunnerState, type LocalWorkspaceSyncRunnerStateStore } from './localWorkspaceSyncRunnerState.js';
 import type { WorkspaceSyncCredentialBroker } from './workspaceSyncCredentialBroker.js';
 export interface LocalWorkspaceSyncRunnerOperationInput {
     command: LocalSyncCoordinatorCommandRecord | null;
@@ -55,6 +55,7 @@ export declare class LocalWorkspaceSyncRunnerError extends Error {
     readonly code: 'SYNC_RUNNER_NOT_STARTED' | 'SYNC_RUNNER_ALREADY_STARTED' | 'SYNC_RUNNER_COORDINATOR_FENCE_INVALID' | 'SYNC_RUNNER_COMMAND_INVALID' | 'SYNC_RUNNER_COMMAND_DISABLED' | 'SYNC_RUNNER_DRAIN_TIMEOUT';
     constructor(message: string, code: 'SYNC_RUNNER_NOT_STARTED' | 'SYNC_RUNNER_ALREADY_STARTED' | 'SYNC_RUNNER_COORDINATOR_FENCE_INVALID' | 'SYNC_RUNNER_COMMAND_INVALID' | 'SYNC_RUNNER_COMMAND_DISABLED' | 'SYNC_RUNNER_DRAIN_TIMEOUT');
 }
+export declare function canCoordinatorRecoveryPreemptRetry(kind: LocalWorkspaceSyncRunnerRetryKind): boolean;
 export declare class LocalWorkspaceSyncRunner {
     private readonly options;
     private context;
@@ -87,6 +88,7 @@ export declare class LocalWorkspaceSyncRunner {
     activate(): void;
     executeCommand(commandId: string): Promise<LocalSyncCoordinatorCommandRecord | null>;
     inspect(): Promise<void>;
+    recoverCoordinatorObligationsDue(isRecoveryStillRequired: () => boolean): Promise<void>;
     pullDue(): Promise<void>;
     retryDue(): Promise<void>;
     pushDue(): Promise<void>;

package/dist/sync/coordinator/localWorkspaceSyncRunner.js

@@ -21,6 +21,14 @@ const CONTENT_PREREQUISITE_BYPASSED_RETRY_KINDS = new Set([
     'pull',
     'repair',
 ]);
+const COORDINATOR_RECOVERY_BYPASSED_RETRY_KINDS = new Set([
+    'pull',
+    'push',
+    'v3-dispatch',
+]);
+export function canCoordinatorRecoveryPreemptRetry(kind) {
+    return COORDINATOR_RECOVERY_BYPASSED_RETRY_KINDS.has(kind);
+}
 function cloneCheckpoint(checkpoint) {
     return JSON.parse(canonicalWorkspaceSyncJson(checkpoint));
 }
@@ -140,6 +148,16 @@ export class LocalWorkspaceSyncRunner {
         }
         return this.enqueue(async () => this.runInspection());
     }
+    recoverCoordinatorObligationsDue(isRecoveryStillRequired) {
+        if (!this.context || this.terminated || !this.acceptingWork) {
+            return Promise.resolve();
+        }
+        return this.enqueue(async () => {
+            if (!isRecoveryStillRequired())
+                return;
+            await this.runInspection(this.options.operations.sync, { bypassRetryKinds: COORDINATOR_RECOVERY_BYPASSED_RETRY_KINDS });
+        });
+    }
     pullDue() {
         if (!this.context || this.terminated || !this.acceptingWork) {
             return Promise.resolve();

package/dist/sync/engine/workspaceSyncV2ChangeDispatcher.js

@@ -317,6 +317,7 @@ export function createWorkspaceSyncV2ChangeDispatcher(dependencies) {
                     taskforceAgentPushActorUserId: String(options.actorUserId || '').trim() || null,
                     taskforceAgentPushAccessPreflighted: true,
                 } : {}),
+                coexistenceDirection: options.coexistenceDirection,
                 recordSyncDiagnostic,
                 createSyncRouteError,
             });
@@ -777,6 +778,7 @@ export function createWorkspaceSyncV2ChangeDispatcher(dependencies) {
                         taskforceAgentPushActorUserId: String(options.actorUserId || '').trim() || null,
                         taskforceAgentPushAccessPreflighted: true,
                     } : {}),
+                    coexistenceDirection: options.coexistenceDirection,
                     recordSyncDiagnostic,
                     createSyncRouteError,
                 });

package/dist/sync/syncApplyHandlers.d.ts

@@ -257,6 +257,7 @@ export declare function applyCollaborationSyncChanges(input: {
     incomingAgentConversations?: Map<string, WorkspaceSyncAgentConversationSnapshot>;
     taskforceAgentPushActorUserId?: string | null;
     taskforceAgentPushAccessPreflighted?: boolean;
+    coexistenceDirection?: 'local-pull' | 'cloud-push';
     recordSyncDiagnostic: RecordSyncDiagnostic;
     createSyncRouteError: CreateSyncRouteError;
 }): void;

package/dist/sync/syncApplyHandlers.js

@@ -1053,7 +1053,7 @@ export async function applyContentSyncChanges(input) {
     }
 }
 export function applyCollaborationSyncChanges(input) {
-    const { core, workspaceId, incomingDocumentReviewSessions, incomingDocumentReviewSessionDeletes, incomingDocumentReviewComments, incomingDocumentReviewCommentDeletes, incomingAnnotatedAttachmentSessions, incomingAnnotatedAttachmentSessionDeletes, incomingTaskforceAgents = new Map(), incomingAgentRoles = new Map(), incomingTaskforceAgentSkills = new Map(), incomingAgentConversations = new Map(), taskforceAgentPushActorUserId, taskforceAgentPushAccessPreflighted = false, recordSyncDiagnostic, createSyncRouteError, } = input;
+    const { core, workspaceId, incomingDocumentReviewSessions, incomingDocumentReviewSessionDeletes, incomingDocumentReviewComments, incomingDocumentReviewCommentDeletes, incomingAnnotatedAttachmentSessions, incomingAnnotatedAttachmentSessionDeletes, incomingTaskforceAgents = new Map(), incomingAgentRoles = new Map(), incomingTaskforceAgentSkills = new Map(), incomingAgentConversations = new Map(), taskforceAgentPushActorUserId, taskforceAgentPushAccessPreflighted = false, coexistenceDirection, recordSyncDiagnostic, createSyncRouteError, } = input;
     if (taskforceAgentPushActorUserId !== undefined && !taskforceAgentPushAccessPreflighted) {
         assertTaskforceAgentSyncPushAccess({
             agents: incomingTaskforceAgents.values(),
@@ -1141,6 +1141,48 @@ export function applyCollaborationSyncChanges(input) {
                         .digest('hex')
                     : '';
                 const metadataCompare = resolveSyncConflictOrdering(comment.updatedAt, String(existing?.updatedAt || '').trim(), incomingTieBreak, existingTieBreak);
+                const parentCommentConflict = Boolean(existing
+                    && comment.parentCommentId !== undefined
+                    && comment.parentCommentId !== existing.parentCommentId);
+                const nonThreadFieldsMatch = Boolean(existing
+                    && comment.sessionId === existing.sessionId
+                    && comment.body === existing.body
+                    && JSON.stringify(comment.anchor ?? null) === JSON.stringify(existing.anchor ?? null)
+                    && comment.order === existing.order
+                    && (comment.authorActorId ?? null) === (existing.authorActorId ?? null)
+                    && (comment.updatedByActorId ?? null) === (existing.updatedByActorId ?? null)
+                    && (comment.deletedByActorId ?? null) === (existing.deletedByActorId ?? null)
+                    && comment.createdAt === existing.createdAt
+                    && comment.updatedAt === existing.updatedAt
+                    && (comment.deletedAt ?? null) === (existing.deletedAt ?? null));
+                const incomingIsLegacyProjectedRoot = Boolean(nonThreadFieldsMatch
+                    && comment.parentCommentId === null
+                    && comment.threadStatus === 'open'
+                    && comment.threadStatusUpdatedAt === comment.createdAt
+                    && !comment.resolvedAt
+                    && !comment.resolvedByActorId);
+                const existingIsLegacyProjectedRoot = Boolean(nonThreadFieldsMatch
+                    && existing
+                    && existing.parentCommentId === null
+                    && existing.threadStatus === 'open'
+                    && existing.threadStatusUpdatedAt === existing.createdAt
+                    && !existing.resolvedAt
+                    && !existing.resolvedByActorId);
+                const preserveLocalReplyParent = parentCommentConflict
+                    && coexistenceDirection === 'local-pull'
+                    && Boolean(existing?.parentCommentId)
+                    && incomingIsLegacyProjectedRoot;
+                const reconcileAuthoritativeParent = parentCommentConflict
+                    && coexistenceDirection === 'local-pull'
+                    && !preserveLocalReplyParent;
+                const reconcileLegacyCloudRoot = parentCommentConflict
+                    && coexistenceDirection === 'cloud-push'
+                    && existingIsLegacyProjectedRoot
+                    && Boolean(comment.parentCommentId);
+                const applyIncomingMetadata = metadataCompare >= 0
+                    && !(parentCommentConflict
+                        && coexistenceDirection === 'cloud-push'
+                        && !reconcileLegacyCloudRoot);
                 const incomingLifecycleTieBreak = createHash('sha256')
                     .update(JSON.stringify({
                     threadStatus: comment.threadStatus,
@@ -1160,28 +1202,43 @@ export function applyCollaborationSyncChanges(input) {
                 const lifecycleCompare = comment.threadStatusUpdatedAt === undefined
                     ? -1
                     : resolveSyncConflictOrdering(String(comment.threadStatusUpdatedAt || '').trim(), String(existing?.threadStatusUpdatedAt || '').trim(), incomingLifecycleTieBreak, existingLifecycleTieBreak);
-                if (metadataCompare < 0 && lifecycleCompare < 0)
+                if (metadataCompare < 0
+                    && lifecycleCompare < 0
+                    && !reconcileAuthoritativeParent
+                    && !reconcileLegacyCloudRoot)
                     continue;
-                core.upsertDocumentReviewCommentForSync({
+                const commentForSync = {
                     id: comment.id,
                     tenantId: core.getTenantId(),
                     workspaceId,
-                    sessionId: metadataCompare >= 0 ? comment.sessionId : existing.sessionId,
-                    body: metadataCompare >= 0 ? comment.body : existing.body,
-                    anchor: (metadataCompare >= 0 ? comment.anchor : existing.anchor),
-                    order: metadataCompare >= 0 ? comment.order : existing.order,
-                    authorActorId: metadataCompare >= 0 ? comment.authorActorId : existing.authorActorId,
-                    updatedByActorId: metadataCompare >= 0 ? comment.updatedByActorId : existing.updatedByActorId,
-                    deletedByActorId: metadataCompare >= 0 ? comment.deletedByActorId : existing.deletedByActorId,
-                    parentCommentId: metadataCompare >= 0 ? comment.parentCommentId : existing.parentCommentId,
+                    sessionId: applyIncomingMetadata ? comment.sessionId : existing.sessionId,
+                    body: applyIncomingMetadata ? comment.body : existing.body,
+                    anchor: (applyIncomingMetadata ? comment.anchor : existing.anchor),
+                    order: applyIncomingMetadata ? comment.order : existing.order,
+                    authorActorId: applyIncomingMetadata ? comment.authorActorId : existing.authorActorId,
+                    updatedByActorId: applyIncomingMetadata ? comment.updatedByActorId : existing.updatedByActorId,
+                    deletedByActorId: applyIncomingMetadata ? comment.deletedByActorId : existing.deletedByActorId,
+                    parentCommentId: preserveLocalReplyParent
+                        ? existing.parentCommentId
+                        : reconcileAuthoritativeParent || reconcileLegacyCloudRoot || applyIncomingMetadata
+                            ? comment.parentCommentId
+                            : existing.parentCommentId,
                     threadStatus: lifecycleCompare >= 0 ? comment.threadStatus : undefined,
                     threadStatusUpdatedAt: lifecycleCompare >= 0 ? comment.threadStatusUpdatedAt : undefined,
                     resolvedAt: lifecycleCompare >= 0 ? comment.resolvedAt : undefined,
                     resolvedByActorId: lifecycleCompare >= 0 ? comment.resolvedByActorId : undefined,
-                    createdAt: metadataCompare >= 0 ? comment.createdAt : existing.createdAt,
-                    updatedAt: metadataCompare >= 0 ? comment.updatedAt : existing.updatedAt,
-                    deletedAt: metadataCompare >= 0 ? comment.deletedAt : existing.deletedAt,
-                });
+                    createdAt: applyIncomingMetadata ? comment.createdAt : existing.createdAt,
+                    updatedAt: applyIncomingMetadata ? comment.updatedAt : existing.updatedAt,
+                    deletedAt: applyIncomingMetadata ? comment.deletedAt : existing.deletedAt,
+                };
+                if (reconcileAuthoritativeParent || reconcileLegacyCloudRoot) {
+                    core.upsertDocumentReviewCommentForSync(commentForSync, {
+                        allowAuthoritativeThreadReconciliation: true,
+                    });
+                }
+                else {
+                    core.upsertDocumentReviewCommentForSync(commentForSync);
+                }
                 if (comment.parentCommentId) {
                     const rootExists = core.listDocumentReviewCommentsForSync({
                         workspaceId,