@taskforcehq/taskforce 0.3.329 → 0.3.332

package/dist/sync/coordinator/localWorkspaceSyncRunnerState.js

@@ -1,6 +1,7 @@
 import { fingerprintWorkspaceSyncPayload, } from '../v3/syncDurabilityStore.js';
 import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
 import { WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS, } from '../v3/workspaceSyncV2ProjectionExclusions.js';
+import { createWorkspaceSyncEngineV2SettlementIdentityProjection } from '../engine/workspaceSyncEnginePushCompletion.js';
 import { WORKSPACE_PUSH_PREPARED_PLAN_VERSION, } from '../workspacePushPreparedPlan.js';
 import { LOCAL_SYNC_COORDINATOR_ID } from './localSyncCoordinatorTypes.js';
 export const LOCAL_WORKSPACE_SYNC_RUNNER_STATE_VERSION = 1;
@@ -123,6 +124,7 @@ const ENCODED_PAYLOAD_OPTIONAL_KEYS = [
     'currentTaskChangeKeys',
     'currentTaskRelationshipChangeKeys',
     'currentTaxonomyChangeKey',
+    'currentPlanningIdentityWatermarks',
     'currentAiProfileChangeKeys',
     'currentTaskforceAgentIds',
     'currentTaskforceAgentWatermarks',
@@ -176,6 +178,7 @@ const OPTIONAL_DIAGNOSTIC_DOMAINS = [
     'taskforceAgents',
     'taskforceAgentSkills',
     'agentConversations',
+    'planningIdentities',
 ];
 function isDeltaDiagnostics(value) {
     if (!isRecord(value) || !hasExactKeys(value, [
@@ -240,6 +243,7 @@ function isEncodedWorkspaceSyncPayload(value) {
         'currentTaskWatermarks',
         'currentTaskChangeKeys',
         'currentTaskRelationshipChangeKeys',
+        'currentPlanningIdentityWatermarks',
         'currentAiProfileChangeKeys',
         'currentTaskforceAgentWatermarks',
         'currentTaskforceAgentSkillWatermarks',
@@ -302,6 +306,7 @@ export function encodeWorkspaceSyncPayload(payload) {
         currentInitiativeWatermarks: encodeStringMap(payload.currentInitiativeWatermarks, 'Initiative watermarks'),
         currentWorkstreamIds: encodeStringSet(payload.currentWorkstreamIds, 'Current workstream ids'),
         currentWorkstreamWatermarks: encodeStringMap(payload.currentWorkstreamWatermarks, 'Workstream watermarks'),
+        currentPlanningIdentityWatermarks: encodeStringMap(payload.currentPlanningIdentityWatermarks || new Map(), 'Planning identity watermarks'),
         currentAiProfileIds: encodeStringSet(payload.currentAiProfileIds, 'Current AI profile ids'),
         currentAiProfileWatermarks: encodeStringMap(payload.currentAiProfileWatermarks, 'AI profile watermarks'),
         currentAiProfileChangeKeys: encodeOptionalStringMap(payload.currentAiProfileChangeKeys, 'AI profile change keys'),
@@ -356,6 +361,7 @@ export function decodeWorkspaceSyncPayload(encoded) {
         currentInitiativeWatermarks: new Map(encoded.currentInitiativeWatermarks),
         currentWorkstreamIds: new Set(encoded.currentWorkstreamIds),
         currentWorkstreamWatermarks: new Map(encoded.currentWorkstreamWatermarks),
+        currentPlanningIdentityWatermarks: new Map(encoded.currentPlanningIdentityWatermarks || []),
         currentAiProfileIds: new Set(encoded.currentAiProfileIds),
         currentAiProfileWatermarks: new Map(encoded.currentAiProfileWatermarks),
         currentAiProfileChangeKeys: encoded.currentAiProfileChangeKeys
@@ -411,6 +417,21 @@ export function createLocalWorkspaceSyncPendingV2Push(input) {
 export function fingerprintLocalWorkspaceSyncPreparedPlan(plan) {
     return fingerprintWorkspaceSyncPayload(plan);
 }
+export function upgradeLocalWorkspaceSyncPendingV2PushSettlement(pending) {
+    if (pending.settlementVersion === 1)
+        return structuredClone(pending);
+    if (!pending.preparedPlan || !pending.preparedPlanFingerprint) {
+        throw new Error('The frozen V2 push must have a prepared plan before settlement activation.');
+    }
+    return {
+        ...structuredClone(pending),
+        settlementVersion: 1,
+        settledBatchOperationIdentities: [
+            ...pending.acknowledgedNonApplyingBatchOperationIdentities,
+        ],
+        settledBatchContributions: [],
+    };
+}
 function isPushBaseline(value) {
     if (!isRecord(value))
         return false;
@@ -421,6 +442,7 @@ function isPushBaseline(value) {
         'taskRelationshipChangeKeys',
         'initiativeWatermarks',
         'workstreamWatermarks',
+        'planningIdentityWatermarks',
         'aiProfileWatermarks',
         'aiProfileChangeKeys',
         'taskforceAgentWatermarks',
@@ -458,6 +480,7 @@ function isPushBaseline(value) {
         'taskforceAgentWatermarks',
         'taskforceAgentSkillWatermarks',
         'agentConversationWatermarks',
+        'planningIdentityWatermarks',
     ];
     if (optionalPairs.some((key) => value[key] !== undefined && !isStringPairArray(value[key])))
         return false;
@@ -470,7 +493,9 @@ function isPushBaseline(value) {
     return true;
 }
 function isPendingV2Push(value) {
-    if (!isRecord(value) || !hasExactKeys(value, [
+    if (!isRecord(value))
+        return false;
+    const legacyKeys = [
         'signature',
         'payloadFingerprint',
         'frozenPayload',
@@ -480,8 +505,71 @@ function isPendingV2Push(value) {
         'preparedPlanFingerprint',
         'acknowledgedNonApplyingBatchOperationIdentities',
         'lastBatchProgress',
-    ]))
+    ];
+    const settlementKeys = [
+        ...legacyKeys,
+        'settlementVersion',
+        'settledBatchOperationIdentities',
+        'settledBatchContributions',
+    ];
+    const hasLegacyShape = hasExactKeys(value, legacyKeys);
+    const hasSettlementShape = hasExactKeys(value, settlementKeys);
+    if (!hasLegacyShape && !hasSettlementShape)
         return false;
+    const settledBatchOperationIdentities = isStringArray(value.settledBatchOperationIdentities) ? value.settledBatchOperationIdentities : null;
+    const settledBatchContributions = Array.isArray(value.settledBatchContributions) ? value.settledBatchContributions : null;
+    const preparedPlan = isPreparedV2PushPlan(value.preparedPlan)
+        ? value.preparedPlan
+        : null;
+    const settlementValid = hasLegacyShape || (value.settlementVersion === 1
+        && settledBatchOperationIdentities !== null
+        && new Set(settledBatchOperationIdentities).size
+            === settledBatchOperationIdentities.length
+        && settledBatchOperationIdentities.every((identity) => /^[a-f0-9]{64}$/.test(identity))
+        && settledBatchContributions !== null
+        && settledBatchContributions.every((entry) => (isRecord(entry)
+            && hasExactKeys(entry, [
+                'operationIdentity',
+                'settlementIdentityFingerprint',
+                'appliedTaskUpserts',
+            ])
+            && typeof entry.operationIdentity === 'string'
+            && /^[a-f0-9]{64}$/.test(entry.operationIdentity)
+            && typeof entry.settlementIdentityFingerprint === 'string'
+            && /^[a-f0-9]{64}$/.test(entry.settlementIdentityFingerprint)
+            && Array.isArray(entry.appliedTaskUpserts)
+            && entry.appliedTaskUpserts.every((upsert) => (isRecord(upsert)
+                && hasRequiredAndAllowedKeys(upsert, ['archived', 'task'], ['durableRevision'])
+                && typeof upsert.archived === 'boolean'
+                && isRecord(upsert.task)
+                && isNonEmptyText(upsert.task.id)
+                && isJson(upsert.task)
+                && (upsert.durableRevision === undefined
+                    || (isRecord(upsert.durableRevision) && isJson(upsert.durableRevision)))))))
+        && new Set(settledBatchContributions.map((entry) => entry.operationIdentity)).size === settledBatchContributions.length
+        && settledBatchContributions.every((entry) => (settledBatchOperationIdentities.includes(entry.operationIdentity))));
+    const settlementContributionsMatchPlan = hasLegacyShape || (preparedPlan !== null
+        && settledBatchContributions !== null
+        && settledBatchContributions.every((rawEntry) => {
+            const entry = rawEntry;
+            const batchIndex = preparedPlan.batchOperationIdentities.indexOf(entry.operationIdentity);
+            if (batchIndex < 0)
+                return false;
+            const changes = preparedPlan.batches[batchIndex].map((planEntry) => (planEntry.preparedChange
+                || value.frozenPayload
+                    .changes[planEntry.sourceChangeIndex]));
+            try {
+                return fingerprintWorkspaceSyncPayload(createWorkspaceSyncEngineV2SettlementIdentityProjection({
+                    operationIdentity: entry.operationIdentity,
+                    changes,
+                    appliedTaskUpserts: entry.appliedTaskUpserts,
+                    excludedProjections: preparedPlan.ownership.combinedExcludedProjections,
+                })) === entry.settlementIdentityFingerprint;
+            }
+            catch {
+                return false;
+            }
+        }));
     return isNonEmptyText(value.signature)
         && typeof value.payloadFingerprint === 'string'
         && /^[a-f0-9]{64}$/.test(value.payloadFingerprint)
@@ -499,6 +587,12 @@ function isPendingV2Push(value) {
                     < value.frozenPayload.changes.length))))
         && isStringArray(value.acknowledgedNonApplyingBatchOperationIdentities)
         && value.acknowledgedNonApplyingBatchOperationIdentities.every((identity) => /^[a-f0-9]{64}$/.test(identity))
+        && settlementValid
+        && settlementContributionsMatchPlan
+        && (!hasSettlementShape
+            || (preparedPlan !== null
+                && settledBatchOperationIdentities !== null
+                && settledBatchOperationIdentities.every((identity) => preparedPlan.batchOperationIdentities.includes(identity))))
         && (value.lastBatchProgress === null
             || (isPendingV2PushBatchProgress(value.lastBatchProgress)
                 && value.lastBatchProgress.completedChanges <= value.frozenPayload.changes.length
@@ -582,6 +676,9 @@ function normalizePendingV2Push(value) {
         'preparedPlan',
         'preparedPlanFingerprint',
         'acknowledgedNonApplyingBatchOperationIdentities',
+        'settlementVersion',
+        'settledBatchOperationIdentities',
+        'settledBatchContributions',
         'lastBatchProgress',
     ])) {
         return value;

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

@@ -43,6 +43,7 @@ export declare class WorkspaceSyncCredentialBrokerError extends Error {
 export declare class WorkspaceSyncCredentialBroker {
     private readonly options;
     private capability;
+    private boundIdentity;
     private blockedReason;
     constructor(options: {
         sessionCookieName: string;

package/dist/sync/coordinator/workspaceSyncCredentialBroker.js

@@ -12,6 +12,9 @@ export class WorkspaceSyncCredentialBrokerError extends Error {
 export class WorkspaceSyncCredentialBroker {
     options;
     capability = null;
+    // Retain the non-secret principal fence while auth is blocked so a logout or
+    // expired cookie cannot let another account adopt the live coordinator.
+    boundIdentity = null;
     blockedReason = 'server-restart';
     constructor(options) {
         this.options = options;
@@ -39,16 +42,21 @@ export class WorkspaceSyncCredentialBroker {
             throw new WorkspaceSyncCredentialBrokerError('The Taskforce session is not valid for the requested workspace.', 'SYNC_COORDINATOR_AUTH_INVALID');
         }
         const existing = this.capability;
+        const identity = existing || this.boundIdentity;
         const samePrincipal = existing
             && existing.workspaceId === validated.workspaceId
             && existing.principal.userId === validated.principal.userId
             && existing.principal.tenantId === validated.principal.tenantId;
-        if (existing && !samePrincipal && !input.allowPrincipalRebind) {
+        const sameBoundIdentity = identity
+            && identity.workspaceId === validated.workspaceId
+            && identity.principal.userId === validated.principal.userId
+            && identity.principal.tenantId === validated.principal.tenantId;
+        if (identity && !sameBoundIdentity && !input.allowPrincipalRebind) {
             throw new WorkspaceSyncCredentialBrokerError('A different Taskforce principal is already bound to this workspace coordinator.', 'SYNC_COORDINATOR_PRINCIPAL_CONFLICT');
         }
-        if (samePrincipal
-            && input.coordinatorGeneration < existing.coordinatorGeneration) {
-            throw new WorkspaceSyncCredentialBrokerError(`Coordinator generation ${input.coordinatorGeneration} is stale; current generation is ${existing.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
+        if (sameBoundIdentity
+            && input.coordinatorGeneration < identity.coordinatorGeneration) {
+            throw new WorkspaceSyncCredentialBrokerError(`Coordinator generation ${input.coordinatorGeneration} is stale; current generation is ${identity.coordinatorGeneration}.`, 'SYNC_COORDINATOR_STALE_GENERATION');
         }
         const authorizedCookies = samePrincipal
             ? new Map(existing.authorizedCookies)
@@ -67,6 +75,11 @@ export class WorkspaceSyncCredentialBroker {
             cookieHeader,
             authorizedCookies,
         };
+        this.boundIdentity = {
+            workspaceId: validated.workspaceId,
+            coordinatorGeneration: input.coordinatorGeneration,
+            principal: validated.principal,
+        };
         this.blockedReason = null;
         return this.readSnapshot();
     }
@@ -143,6 +156,11 @@ export class WorkspaceSyncCredentialBroker {
             cookieHeader: prepared.cookieHeader,
             authorizedCookies: new Map([[cookieValue, prepared.validation]]),
         };
+        this.boundIdentity = {
+            workspaceId: prepared.targetWorkspaceId,
+            coordinatorGeneration: prepared.targetCoordinatorGeneration,
+            principal: prepared.principal,
+        };
         prepared.activated = true;
         this.blockedReason = null;
         return this.readSnapshot();
@@ -159,6 +177,11 @@ export class WorkspaceSyncCredentialBroker {
                 coordinatorGeneration,
                 authorizedCookies: new Map(prepared.sourceCapability.authorizedCookies),
             };
+            this.boundIdentity = {
+                workspaceId: prepared.sourceWorkspaceId,
+                coordinatorGeneration,
+                principal: prepared.sourceCapability.principal,
+            };
             prepared.activated = false;
             this.blockedReason = null;
         }
@@ -175,6 +198,9 @@ export class WorkspaceSyncCredentialBroker {
             throw new WorkspaceSyncCredentialBrokerError('The coordinator generation transition is invalid.', 'SYNC_COORDINATOR_STALE_GENERATION');
         }
         this.capability.coordinatorGeneration = input.toCoordinatorGeneration;
+        if (this.boundIdentity) {
+            this.boundIdentity.coordinatorGeneration = input.toCoordinatorGeneration;
+        }
         return this.readSnapshot();
     }
     /**
@@ -197,6 +223,9 @@ export class WorkspaceSyncCredentialBroker {
             throw new WorkspaceSyncCredentialBrokerError('The coordinator generation transition is stale or non-adjacent.', 'SYNC_COORDINATOR_STALE_GENERATION');
         }
         capability.coordinatorGeneration = input.toCoordinatorGeneration;
+        if (this.boundIdentity) {
+            this.boundIdentity.coordinatorGeneration = input.toCoordinatorGeneration;
+        }
         return this.readSnapshot();
     }
     authorizeCookieHeader(input) {

package/dist/sync/engine/workspaceSyncContentLifecycleAdapter.d.ts

@@ -1,4 +1,4 @@
-import { type WorkspaceSyncContentHead, type WorkspaceSyncContentKind, type WorkspaceSyncContentScope, type WorkspaceSyncContentVersionStore } from './workspaceSyncContentVersionStore.js';
+import { type WorkspaceSyncContentHead, type WorkspaceSyncContentKind, type WorkspaceSyncContentScope, type WorkspaceSyncContentTombstoneProvenance, type WorkspaceSyncContentVersionStore } from './workspaceSyncContentVersionStore.js';
 export type WorkspaceSyncContentTombstoneInput = WorkspaceSyncContentScope & {
     kind: WorkspaceSyncContentKind;
     logicalPath: string;
@@ -6,6 +6,7 @@ export type WorkspaceSyncContentTombstoneInput = WorkspaceSyncContentScope & {
     publishedAt: string;
     deletedAt: string;
     retireGcAfter?: string | null;
+    provenance?: WorkspaceSyncContentTombstoneProvenance;
 };
 export interface WorkspaceSyncContentLifecyclePort {
     tombstone(input: WorkspaceSyncContentTombstoneInput): WorkspaceSyncContentHead;

package/dist/sync/engine/workspaceSyncContentVersionStore.d.ts

@@ -48,6 +48,36 @@ export type WorkspaceSyncContentHead = WorkspaceSyncContentScope & {
     publishedAt: string;
     deletedAt: string | null;
 };
+/**
+ * Durable, queryable attribution for an accepted content tombstone. operationId/
+ * actorId are optional because the current WorkspaceSyncChange wire format and
+ * apply pipeline don't yet carry per-change requester identity from origin
+ * through to this layer — threading that through is a larger, separate change
+ * (it would mean extending the delete-change payload and every intermediate
+ * outbox/apply layer, not just this store). What IS reliably knowable at the
+ * point a tombstone is admitted is recorded: which admission path produced it,
+ * the source revision it was admitted at, which runtime applied it, and
+ * whether workspace repair was involved.
+ */
+export type WorkspaceSyncContentTombstoneProvenance = {
+    source: 'explicit-delete' | 'synchronized-tombstone' | 'repair';
+    operationId?: string | null;
+    actorId?: string | null;
+    sourceRuntime?: string | null;
+    repairInvolved?: boolean;
+};
+export type WorkspaceSyncContentTombstoneProvenanceRecord = WorkspaceSyncContentScope & {
+    id: string;
+    kind: WorkspaceSyncContentKind;
+    logicalPath: string;
+    source: string;
+    operationId: string | null;
+    actorId: string | null;
+    sourceRuntime: string | null;
+    sourceUpdatedAt: string;
+    repairInvolved: boolean;
+    recordedAt: string;
+};
 export type WorkspaceSyncContentLegacyFallback = {
     source: 'legacy';
 };
@@ -141,7 +171,15 @@ export declare class WorkspaceSyncContentVersionStore {
         publishedAt: string;
         deletedAt: string;
         retireGcAfter?: string | null;
+        provenance?: WorkspaceSyncContentTombstoneProvenance;
     }): WorkspaceSyncContentHead;
+    private recordTombstoneProvenance;
+    /** Queryable read side for tombstone provenance — most recent admission first. */
+    listTombstoneProvenance(input: WorkspaceSyncContentScope & {
+        kind?: WorkspaceSyncContentKind;
+        logicalPath?: string;
+        limit?: number;
+    }): WorkspaceSyncContentTombstoneProvenanceRecord[];
     resolveHead(input: WorkspaceSyncContentScope & {
         kind: WorkspaceSyncContentKind;
         logicalPath: string;

package/dist/sync/engine/workspaceSyncContentVersionStore.js

@@ -1,4 +1,4 @@
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import { compareWorkspaceMutationOrdering } from '../workspaceSyncSurface.js';
 import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
 export class WorkspaceSyncContentVersionConflictError extends Error {
@@ -577,9 +577,58 @@ export class WorkspaceSyncContentVersionStore {
                 contentSha256: null,
                 sizeBytes: null,
             });
+            // Only a tombstone that's actually newly accepted (didn't early-return
+            // above as superseded/no-op) gets a provenance record — provenance
+            // tracks admission events, not every replayed/no-op call.
+            this.recordTombstoneProvenance(input);
             return this.requireHead(input);
         })();
     }
+    recordTombstoneProvenance(input) {
+        const provenance = input.provenance;
+        this.db.prepare(`
+            INSERT INTO workspace_sync_content_tombstone_provenance (
+                id, tenant_id, workspace_id, kind, logical_path, source,
+                operation_id, actor_id, source_runtime, source_updated_at,
+                repair_involved, recorded_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(randomUUID(), input.tenantId, input.workspaceId, input.kind, input.logicalPath, provenance?.source || 'unknown', provenance?.operationId || null, provenance?.actorId || null, provenance?.sourceRuntime || null, input.sourceUpdatedAt, provenance?.repairInvolved === true ? 1 : 0, input.publishedAt);
+    }
+    /** Queryable read side for tombstone provenance — most recent admission first. */
+    listTombstoneProvenance(input) {
+        const limit = Math.max(1, Math.min(500, Math.floor(Number(input.limit) || 100)));
+        const conditions = ['tenant_id = ?', 'workspace_id = ?'];
+        const params = [input.tenantId, input.workspaceId];
+        if (input.kind) {
+            conditions.push('kind = ?');
+            params.push(input.kind);
+        }
+        if (input.logicalPath) {
+            conditions.push('logical_path = ?');
+            params.push(input.logicalPath);
+        }
+        const rows = this.db.prepare(`
+            SELECT *
+            FROM workspace_sync_content_tombstone_provenance
+            WHERE ${conditions.join(' AND ')}
+            ORDER BY recorded_at DESC
+            LIMIT ?
+        `).all(...params, limit);
+        return rows.map((row) => ({
+            id: String(row.id || ''),
+            tenantId: String(row.tenant_id || ''),
+            workspaceId: String(row.workspace_id || ''),
+            kind: row.kind === 'document' ? 'document' : 'asset',
+            logicalPath: String(row.logical_path || ''),
+            source: String(row.source || 'unknown'),
+            operationId: row.operation_id == null ? null : String(row.operation_id),
+            actorId: row.actor_id == null ? null : String(row.actor_id),
+            sourceRuntime: row.source_runtime == null ? null : String(row.source_runtime),
+            sourceUpdatedAt: String(row.source_updated_at || ''),
+            repairInvolved: Number(row.repair_involved) === 1,
+            recordedAt: String(row.recorded_at || ''),
+        }));
+    }
     resolveHead(input) {
         const head = this.getHead(input);
         return head ? { source: 'versioned', head } : { source: 'legacy' };

package/dist/sync/engine/workspaceSyncEngineLifecyclePolicy.js

@@ -25,7 +25,7 @@ export function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt
             summary: busy
                 ? 'Uploading this workspace to cloud for the first time.'
                 : 'Preparing the first upload to cloud.',
-            recommendedAction: 'Keep this window open while the first upload finishes. If it seems stalled, press Sync.'
+            recommendedAction: 'Keep this window open while the first upload finishes.'
         };
     }
     if (phase === 'attach-cloud') {
@@ -71,14 +71,14 @@ export function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt
         return {
             status: 'attention',
             summary: 'Sync hit a temporary problem and will retry automatically.',
-            recommendedAction: 'Wait for the automatic retry, or press Sync to retry now.'
+            recommendedAction: 'Wait for the automatic retry.'
         };
     }
     if (lastErrorMessage || phase === 'error') {
         return {
             status: 'attention',
             summary: 'Sync needs attention before it can continue.',
-            recommendedAction: 'Press Sync to retry. If the same error keeps returning, press Repair.'
+            recommendedAction: 'Keep sync enabled. If the same error keeps returning, press Repair.'
         };
     }
     if (pendingChanges > 0 || (durableOutbox?.pending || 0) > 0 || (durableOutbox?.inFlight || 0) > 0) {
@@ -104,14 +104,14 @@ export function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt
             summary: lastPushMs === null
                 ? 'This device has not completed its first cloud pull.'
                 : 'Cloud uploads are working, but this device has not completed a cloud pull.',
-            recommendedAction: 'Press Retry now. If the cloud check still does not complete, press Repair and copy the report.'
+            recommendedAction: 'Keep sync enabled. If the cloud check still does not complete, press Repair and copy the report.'
         };
     }
     if (lastErrorMs !== null && lastErrorMs > lastPullMs) {
         return {
             status: 'attention',
             summary: 'A sync issue occurred after the last successful cloud pull.',
-            recommendedAction: 'Press Retry now to verify cloud changes can still be received. If the issue returns, copy the report.'
+            recommendedAction: 'Wait for the automatic retry. If the issue returns, copy the report.'
         };
     }
     const pullIsStale = Number.isFinite(nowMs)
@@ -122,7 +122,7 @@ export function resolveWorkspaceSyncPresentation({ enabled, phase, busy, retryAt
             summary: lastPushMs !== null && lastPushMs > lastPullMs
                 ? 'Cloud uploads are succeeding, but this device has not received cloud changes recently.'
                 : 'This device has not checked for cloud changes recently.',
-            recommendedAction: 'Press Retry now to check cloud changes. If Last cloud check does not advance, press Repair and copy the report.'
+            recommendedAction: 'Keep sync enabled. If Last cloud check does not advance, press Repair and copy the report.'
         };
     }
     return {

package/dist/sync/engine/workspaceSyncEnginePushCompletion.d.ts

@@ -1,4 +1,5 @@
 import type { WorkspaceSyncChange, WorkspaceSyncDurableTaskRevision, WorkspaceSyncTaskSnapshot } from '../workspaceSyncModel.js';
+import type { WorkspaceSyncV2ProjectionExclusion } from '../v3/workspaceSyncV2ProjectionExclusions.js';
 export declare const WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION: 1;
 /**
  * Stable attempt-wide boundary shared by every V2 push batch. Individual
@@ -18,3 +19,16 @@ export interface WorkspaceSyncEngineAppliedTaskUpsert {
 }
 export declare function workspaceSyncEngineExpectedTaskEchoIds(changes: readonly WorkspaceSyncChange[]): string[];
 export declare function parseWorkspaceSyncEngineAppliedTaskUpserts(value: unknown, expectedTaskIds: readonly string[]): WorkspaceSyncEngineAppliedTaskUpsert[];
+export declare function createWorkspaceSyncEngineV2SettlementIdentityProjection(input: {
+    operationIdentity: string;
+    changes: readonly WorkspaceSyncChange[];
+    appliedTaskUpserts: readonly WorkspaceSyncEngineAppliedTaskUpsert[];
+    excludedProjections?: readonly WorkspaceSyncV2ProjectionExclusion[];
+}): {
+    version: 1;
+    operationIdentity: string;
+    taskUpserts: Array<{
+        archived: boolean;
+        task: Record<string, unknown>;
+    }>;
+};

package/dist/sync/engine/workspaceSyncEnginePushCompletion.js

@@ -1,3 +1,4 @@
+import { canonicalWorkspaceSyncJson } from '../v3/canonicalWorkspaceSyncJson.js';
 export const WORKSPACE_SYNC_ENGINE_V2_PUSH_BOUNDARY_VERSION = 1;
 export function createWorkspaceSyncEngineV2PushBoundary(batchOperationIdentities) {
     if (!Array.isArray(batchOperationIdentities)
@@ -85,3 +86,86 @@ export function parseWorkspaceSyncEngineAppliedTaskUpserts(value, expectedTaskId
     }
     return normalized;
 }
+function taskSettlementProjection(task, preserveReferenceNumber) {
+    const { updatedAt: _updatedAt, ...stableTask } = structuredClone(task);
+    if (!preserveReferenceNumber)
+        delete stableTask.referenceNumber;
+    return stableTask;
+}
+function taskSettlementOwnedProjection(input) {
+    // The cloud echo is authoritative for the complete task row, but this V2
+    // page may own only carrier fields. Validate exactly that remaining V2
+    // surface; V3-owned fields are checked by their own acknowledgement/feed.
+    const task = taskSettlementProjection(input.task, input.preserveReferenceNumber);
+    const rootOwnedByV3 = input.excludedProjections.has('task/root-v1');
+    const commentsOwnedByV3 = input.excludedProjections.has('task-comments/full-v1');
+    const checklistOwnedByV3 = input.excludedProjections.has('task-checklist/full-v1');
+    const attachmentLinksV1OwnedByV3 = input.excludedProjections
+        .has('task-attachment-links/full-v1');
+    const attachmentLinksV2OwnedByV3 = input.excludedProjections
+        .has('task-attachment-links/full-v2');
+    if (rootOwnedByV3) {
+        for (const key of Object.keys(task)) {
+            if (![
+                'id',
+                'comments',
+                'checklistItems',
+                'attachments',
+                'cardCoverAssetId',
+            ].includes(key)) {
+                delete task[key];
+            }
+        }
+    }
+    if (commentsOwnedByV3)
+        delete task.comments;
+    if (checklistOwnedByV3)
+        delete task.checklistItems;
+    if (attachmentLinksV1OwnedByV3 || attachmentLinksV2OwnedByV3) {
+        delete task.attachments;
+    }
+    if (attachmentLinksV2OwnedByV3)
+        delete task.cardCoverAssetId;
+    return {
+        ...(rootOwnedByV3 ? {} : { archived: input.archived }),
+        task,
+    };
+}
+export function createWorkspaceSyncEngineV2SettlementIdentityProjection(input) {
+    const operationIdentity = String(input.operationIdentity || '').trim();
+    if (!operationIdentity || operationIdentity !== input.operationIdentity) {
+        throw new TypeError('The V2 push settlement operation identity is invalid.');
+    }
+    const expectedTaskUpserts = input.changes.filter((change) => change.op === 'upsert');
+    if (expectedTaskUpserts.length !== input.appliedTaskUpserts.length) {
+        throw new TypeError('The V2 push authoritative settlement projection is incomplete.');
+    }
+    const expectedProjection = expectedTaskUpserts.map((change) => ({
+        archived: change.archived,
+        task: taskSettlementProjection(change.task, change.task.referenceNumber !== undefined && change.task.referenceNumber !== null),
+    }));
+    const excludedProjections = new Set(input.excludedProjections || []);
+    const expectedOwnedProjection = expectedTaskUpserts.map((change) => (taskSettlementOwnedProjection({
+        archived: change.archived,
+        task: change.task,
+        preserveReferenceNumber: change.task.referenceNumber !== undefined
+            && change.task.referenceNumber !== null,
+        excludedProjections,
+    })));
+    const authoritativeOwnedProjection = input.appliedTaskUpserts.map((entry, index) => (taskSettlementOwnedProjection({
+        archived: entry.archived,
+        task: entry.task,
+        preserveReferenceNumber: expectedTaskUpserts[index]?.task.referenceNumber !== undefined
+            && expectedTaskUpserts[index]?.task.referenceNumber !== null,
+        excludedProjections,
+    })));
+    if (canonicalWorkspaceSyncJson(authoritativeOwnedProjection)
+        !== canonicalWorkspaceSyncJson(expectedOwnedProjection)) {
+        throw new TypeError('The V2 push authoritative settlement does not match the canonical request state.');
+    }
+    return {
+        version: 1,
+        operationIdentity,
+        taskUpserts: expectedProjection,
+    };
+}

package/dist/sync/engine/workspaceSyncEngineRecovery.js

@@ -10,6 +10,7 @@ function resetWorkspaceSyncStatePushBaselines(runtime) {
     runtime.lastPushedInitiativeWatermarks.current = new Map();
     runtime.lastPushedWorkstreamIds.current = new Set();
     runtime.lastPushedWorkstreamWatermarks.current = new Map();
+    runtime.lastPushedPlanningIdentityWatermarks.current = new Map();
     runtime.lastPushedAiProfileIds.current = new Set();
     runtime.lastPushedAiProfileWatermarks.current = new Map();
     runtime.lastPushedAiProfileChangeKeys.current = new Map();

package/dist/sync/engine/workspaceSyncEngineRuntime.d.ts

@@ -26,6 +26,7 @@ export interface WorkspaceSyncEngineRuntime {
     lastPushedInitiativeWatermarks: WorkspaceSyncMutableValue<Map<string, string>>;
     lastPushedWorkstreamIds: WorkspaceSyncMutableValue<Set<string>>;
     lastPushedWorkstreamWatermarks: WorkspaceSyncMutableValue<Map<string, string>>;
+    lastPushedPlanningIdentityWatermarks: WorkspaceSyncMutableValue<Map<string, string>>;
     lastPushedAiProfileIds: WorkspaceSyncMutableValue<Set<string>>;
     lastPushedAiProfileWatermarks: WorkspaceSyncMutableValue<Map<string, string>>;
     lastPushedAiProfileChangeKeys: WorkspaceSyncMutableValue<Map<string, string>>;

package/dist/sync/engine/workspaceSyncEngineRuntime.js

@@ -24,6 +24,7 @@ export function createWorkspaceSyncEngineRuntime() {
         lastPushedInitiativeWatermarks: mutable(new Map()),
         lastPushedWorkstreamIds: mutable(new Set()),
         lastPushedWorkstreamWatermarks: mutable(new Map()),
+        lastPushedPlanningIdentityWatermarks: mutable(new Map()),
         lastPushedAiProfileIds: mutable(new Set()),
         lastPushedAiProfileWatermarks: mutable(new Map()),
         lastPushedAiProfileChangeKeys: mutable(new Map()),