@taskforcehq/taskforce 0.3.328 → 0.3.329

package/dist/config/localServiceRuntimeContract.d.ts

@@ -0,0 +1,13 @@
+export interface LocalServiceRuntimeContract {
+    schemaVersion: 1;
+    fingerprint: string;
+    coverageVersion: number | null;
+}
+export declare function hydrateSourceCheckoutServiceEnvironment(input: {
+    env: NodeJS.ProcessEnv;
+    projectRoot: string;
+    packageRoot: string;
+}): string | null;
+export declare function resolveLocalServiceRuntimeContract(env: NodeJS.ProcessEnv): LocalServiceRuntimeContract;
+export declare function parseLocalServiceRuntimeContract(value: unknown): LocalServiceRuntimeContract | null;
+export declare function localServiceRuntimeContractsEqual(left: LocalServiceRuntimeContract | null | undefined, right: LocalServiceRuntimeContract | null | undefined): boolean;

package/dist/config/localServiceRuntimeContract.js

@@ -0,0 +1,135 @@
+import { createHash } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import { parseTaskforceCloudEnvironment } from './cloudEnvironment.js';
+const SERVICE_ENV_EXACT_KEYS = new Set([
+    'CF_ACCESS_CLIENT_ID',
+    'CF_ACCESS_CLIENT_SECRET',
+    'TASKFORCE_CF_ACCESS_CLIENT_ID',
+    'TASKFORCE_CF_ACCESS_CLIENT_SECRET',
+    'TASKFORCE_REALTIME_SYNC',
+    'TASKFORCE_RUNTIME_MODE',
+]);
+function isServiceEnvironmentKey(key) {
+    if (SERVICE_ENV_EXACT_KEYS.has(key))
+        return true;
+    if (key.startsWith('TASKFORCE_E2E_') || key.startsWith('TASKFORCE_PLAYWRIGHT_'))
+        return false;
+    return key.startsWith('TASKFORCE_SYNC_')
+        || key.startsWith('TASKFORCE_LOCAL_SYNC_')
+        || key.startsWith('VITE_TASKFORCE_');
+}
+function isContractKey(key) {
+    return key === 'TASKFORCE_RUNTIME_MODE'
+        || key === 'TASKFORCE_REALTIME_SYNC'
+        || key.startsWith('TASKFORCE_SYNC_')
+        || key.startsWith('TASKFORCE_LOCAL_SYNC_');
+}
+function stripQuotes(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2) {
+        const first = trimmed[0];
+        const last = trimmed[trimmed.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return trimmed.slice(1, -1);
+        }
+    }
+    return trimmed;
+}
+function isInside(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function loadTrustedEnvFile(filePath, packageRoot, loaded, visited) {
+    const resolved = fs.realpathSync(filePath);
+    if (!isInside(packageRoot, resolved) || !path.basename(resolved).startsWith('.env')) {
+        throw new Error('Taskforce source-checkout environment includes must remain trusted .env files inside the package root.');
+    }
+    if (visited.has(resolved))
+        return;
+    visited.add(resolved);
+    const lines = fs.readFileSync(resolved, 'utf8').split(/\r?\n/);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const include = trimmed.match(/^(?:\.|source)\s+([^\s]+)$/);
+        if (include) {
+            const includePath = path.resolve(path.dirname(resolved), stripQuotes(include[1]));
+            loadTrustedEnvFile(includePath, packageRoot, loaded, visited);
+            continue;
+        }
+        const normalized = trimmed.startsWith('export ') ? trimmed.slice(7).trim() : trimmed;
+        const separator = normalized.indexOf('=');
+        if (separator <= 0)
+            continue;
+        const key = normalized.slice(0, separator).trim();
+        if (!/^[A-Z][A-Z0-9_]*$/.test(key) || !isServiceEnvironmentKey(key))
+            continue;
+        loaded.set(key, stripQuotes(normalized.slice(separator + 1)));
+    }
+}
+export function hydrateSourceCheckoutServiceEnvironment(input) {
+    const projectRoot = fs.realpathSync(input.projectRoot);
+    const packageRoot = fs.realpathSync(input.packageRoot);
+    if (projectRoot !== packageRoot)
+        return null;
+    const environment = parseTaskforceCloudEnvironment(input.env.TASKFORCE_CLOUD_ENVIRONMENT);
+    if (environment !== 'performance' && environment !== 'staging')
+        return null;
+    const envFile = path.join(packageRoot, `.env.${environment}`);
+    if (!fs.existsSync(envFile))
+        return null;
+    const explicitKeys = new Set(Object.keys(input.env));
+    const loaded = new Map();
+    loadTrustedEnvFile(envFile, packageRoot, loaded, new Set());
+    for (const [key, value] of loaded) {
+        if (!explicitKeys.has(key))
+            input.env[key] = value;
+    }
+    return envFile;
+}
+export function resolveLocalServiceRuntimeContract(env) {
+    const effectiveEnv = {
+        ...env,
+        TASKFORCE_RUNTIME_MODE: String(env.TASKFORCE_RUNTIME_MODE || 'local').trim().toLowerCase(),
+    };
+    const entries = Object.entries(effectiveEnv)
+        .filter(([key, value]) => isContractKey(key) && value !== undefined)
+        .map(([key, value]) => [key, String(value)])
+        .sort(([left], [right]) => left.localeCompare(right));
+    const fingerprint = createHash('sha256')
+        .update(JSON.stringify(entries))
+        .digest('hex');
+    const rawCoverageVersion = Number.parseInt(String(env.TASKFORCE_SYNC_V3_COMBINED_FEED_COVERAGE_VERSION || ''), 10);
+    return {
+        schemaVersion: 1,
+        fingerprint,
+        coverageVersion: Number.isSafeInteger(rawCoverageVersion) && rawCoverageVersion > 0
+            ? rawCoverageVersion
+            : null,
+    };
+}
+export function parseLocalServiceRuntimeContract(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    if (record.schemaVersion !== 1
+        || typeof record.fingerprint !== 'string'
+        || !/^[a-f0-9]{64}$/.test(record.fingerprint)
+        || (record.coverageVersion !== null
+            && (!Number.isSafeInteger(record.coverageVersion) || Number(record.coverageVersion) < 1))) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        fingerprint: record.fingerprint,
+        coverageVersion: record.coverageVersion === null ? null : Number(record.coverageVersion),
+    };
+}
+export function localServiceRuntimeContractsEqual(left, right) {
+    return Boolean(left && right
+        && left.schemaVersion === right.schemaVersion
+        && left.fingerprint === right.fingerprint
+        && left.coverageVersion === right.coverageVersion);
+}

package/dist/core/AiProfileService.js

@@ -931,15 +931,27 @@ function reconcileSyncedAiProfileConnectionBindings(deps, workspaceId, profileId
             .sort()
         : [];
     const clientId = String(connection.clientId || '').trim() || null;
-    if (bindingIds.length === 0) {
-        deps.db.prepare(`DELETE FROM ai_profile_connection_bindings WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ?`)
+    // Credential-derived bindings are authentication state owned by the cloud
+    // runtime. Synced profile metadata must never create, remove, or reassign
+    // them; doing so would let a stale replica change write attribution.
+    const syncedBindingIds = bindingIds.filter((bindingId) => !isCredentialOwnedConnectionBindingId(bindingId));
+    if (syncedBindingIds.length === 0) {
+        deps.db.prepare(`DELETE FROM ai_profile_connection_bindings
+            WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ?
+              AND connection_id NOT LIKE 'oauth:%'
+              AND connection_id NOT LIKE 'oauth-client:%'
+              AND connection_id NOT LIKE 'token:%'`)
             .run(deps.tenantId, workspaceId, profileId);
         return;
     }
-    const placeholders = bindingIds.map(() => '?').join(', ');
+    const placeholders = syncedBindingIds.map(() => '?').join(', ');
     deps.db.prepare(`DELETE FROM ai_profile_connection_bindings
-        WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ? AND connection_id NOT IN (${placeholders})`)
-        .run(deps.tenantId, workspaceId, profileId, ...bindingIds);
+        WHERE tenant_id = ? AND workspace_id = ? AND profile_id = ?
+          AND connection_id NOT LIKE 'oauth:%'
+          AND connection_id NOT LIKE 'oauth-client:%'
+          AND connection_id NOT LIKE 'token:%'
+          AND connection_id NOT IN (${placeholders})`)
+        .run(deps.tenantId, workspaceId, profileId, ...syncedBindingIds);
     const now = new Date().toISOString();
     const upsert = deps.db.prepare(`INSERT INTO ai_profile_connection_bindings
         (tenant_id, workspace_id, connection_id, profile_id, client_id, created_at, updated_at)
@@ -948,7 +960,7 @@ function reconcileSyncedAiProfileConnectionBindings(deps, workspaceId, profileId
             profile_id = excluded.profile_id,
             client_id = excluded.client_id,
             updated_at = excluded.updated_at`);
-    for (const bindingId of bindingIds) {
+    for (const bindingId of syncedBindingIds) {
         upsert.run(deps.tenantId, workspaceId, bindingId, profileId, clientId, now, now);
     }
 }
@@ -1282,6 +1294,11 @@ function normalizeConnectionBindingId(deps, value) {
     }
     return normalized;
 }
+function isCredentialOwnedConnectionBindingId(connectionId) {
+    return connectionId.startsWith('oauth:')
+        || connectionId.startsWith('oauth-client:')
+        || connectionId.startsWith('token:');
+}
 function parseProviderMetadataRow(row) {
     if (typeof row.provider_metadata_json !== 'string' || !row.provider_metadata_json.trim())
         return {};
@@ -1304,10 +1321,29 @@ export function bindAiProfileConnectionService(deps, input) {
         if (!target)
             throw deps.createRuleError(`Profile ${profileId} not found`, 404, 'AI_PROFILE_NOT_FOUND');
         const now = new Date().toISOString();
-        deps.db.prepare(`INSERT INTO ai_profile_connection_bindings (tenant_id, workspace_id, connection_id, profile_id, client_id, created_at, updated_at)
+        deps.db.prepare(`INSERT INTO ai_profile_connection_bindings
+            (tenant_id, workspace_id, connection_id, profile_id, client_id, created_at, updated_at)
             VALUES (?, ?, ?, ?, ?, ?, ?)
-            ON CONFLICT (tenant_id, workspace_id, connection_id) DO UPDATE SET profile_id = excluded.profile_id, client_id = excluded.client_id, updated_at = excluded.updated_at`)
+            ON CONFLICT (tenant_id, workspace_id, connection_id) DO NOTHING`)
             .run(deps.tenantId, workspaceId, connectionId, profileId, clientId, now, now);
+        const existing = deps.db.prepare(`SELECT b.profile_id, p.archived_at
+            FROM ai_profile_connection_bindings b
+            LEFT JOIN ai_profiles p ON p.tenant_id = b.tenant_id AND p.workspace_id = b.workspace_id AND p.id = b.profile_id
+            WHERE b.tenant_id = ? AND b.workspace_id = ? AND b.connection_id = ? LIMIT 1`)
+            .get(deps.tenantId, workspaceId, connectionId);
+        if (!existing?.profile_id) {
+            throw deps.createRuleError('Failed to establish the MCP connection binding.', 500, 'AI_PROFILE_CONNECTION_BIND_FAILED');
+        }
+        if (existing && existing.profile_id !== profileId && !existing.archived_at) {
+            throw deps.createRuleError('This MCP connection is already bound to a different active AI profile. Reconnect or use an authorized profile recovery flow.', 409, 'AI_PROFILE_CONNECTION_CONFLICT', { workspaceId, connectionId, existingProfileId: existing.profile_id || null, requestedProfileId: profileId });
+        }
+        const updateResult = deps.db.prepare(`UPDATE ai_profile_connection_bindings
+            SET profile_id = ?, client_id = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND connection_id = ? AND profile_id = ?`)
+            .run(profileId, clientId, now, deps.tenantId, workspaceId, connectionId, existing.profile_id);
+        if (updateResult.changes !== 1) {
+            throw deps.createRuleError('The MCP connection binding changed concurrently. Retry after refreshing the intended profile.', 409, 'AI_PROFILE_CONNECTION_CONFLICT', { workspaceId, connectionId, expectedProfileId: existing.profile_id || null, requestedProfileId: profileId });
+        }
         const rows = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ?`).all(deps.tenantId, workspaceId);
         for (const row of rows) {
             const metadata = parseProviderMetadataRow(row);
@@ -1351,6 +1387,8 @@ export function getAiProfileByConnectionService(deps, input) {
         const record = hydrateAiProfileRecord(deps, binding);
         return input.seatScope !== undefined && (record.seatScope ?? null) !== input.seatScope ? null : record;
     }
+    if (isCredentialOwnedConnectionBindingId(connectionId))
+        return null;
     const legacyRows = deps.db.prepare(`SELECT * FROM ai_profiles WHERE tenant_id = ? AND workspace_id = ?`).all(deps.tenantId, workspaceId)
         .filter((row) => {
         const record = hydrateAiProfileRecord(deps, row);

package/dist/core/DeletedTaskLifecycleService.d.ts

@@ -8,6 +8,7 @@ export interface DeletedTaskLifecycleServiceDeps {
     generateEntityId: (prefix: string) => string;
     normalizeWorkspaceId: (workspaceId: string | undefined) => string;
     resolveWorkspaceActor: (workspaceId: string, actorRef: unknown) => TaskActor | null;
+    resolveWorkspaceActors: (workspaceId: string, actorRefs: unknown[]) => Map<string, TaskActor | null>;
     sanitizeOrderInDay: (value: unknown) => number | null;
     sanitizeDateOnly: (value: unknown) => string | null;
     normalizeTaskEventActor: (actorRef: unknown, workspaceId: string) => {

package/dist/core/DeletedTaskLifecycleService.js

@@ -119,6 +119,41 @@ export function mapDeletedTaskRowService(deps, row) {
         actorProfile: actor === 'system' ? null : deps.resolveWorkspaceActor(workspaceId, actor)
     };
 }
+function mapDeletedTaskRowsService(deps, rows) {
+    const actorProfiles = new Map();
+    const actorRefsByWorkspace = new Map();
+    for (const row of rows) {
+        const workspaceId = deps.normalizeWorkspaceId(typeof row.workspace_id === 'string' ? row.workspace_id : undefined);
+        const actorRef = String(row.actor || 'system').trim() || 'system';
+        if (actorRef === 'system') {
+            actorProfiles.set(`${workspaceId}\u0000${actorRef}`, null);
+            continue;
+        }
+        const workspaceActorRefs = actorRefsByWorkspace.get(workspaceId) ?? new Set();
+        workspaceActorRefs.add(actorRef);
+        actorRefsByWorkspace.set(workspaceId, workspaceActorRefs);
+    }
+    for (const [workspaceId, actorRefs] of actorRefsByWorkspace) {
+        const resolvedWorkspaceActors = deps.resolveWorkspaceActors(workspaceId, [...actorRefs]);
+        for (const actorRef of actorRefs) {
+            actorProfiles.set(`${workspaceId}\u0000${actorRef}`, resolvedWorkspaceActors.get(actorRef) ?? null);
+        }
+    }
+    const cachedDeps = {
+        ...deps,
+        resolveWorkspaceActor: (workspaceId, actorRef) => {
+            const cacheKey = `${workspaceId}\u0000${String(actorRef || '').trim()}`;
+            if (actorProfiles.has(cacheKey))
+                return actorProfiles.get(cacheKey) ?? null;
+            const actorProfile = deps.resolveWorkspaceActor(workspaceId, actorRef);
+            actorProfiles.set(cacheKey, actorProfile);
+            return actorProfile;
+        },
+    };
+    return rows
+        .map((row) => mapDeletedTaskRowService(cachedDeps, row))
+        .filter((row) => Boolean(row));
+}
 function deletedTaskListSnapshotSelect() {
     const snapshotPairs = DELETED_TASK_LIST_SNAPSHOT_FIELDS
         .map((field) => `'${field}', snapshot -> '${field}'`)
@@ -220,9 +255,7 @@ export function listDeletedTasksService(deps, workspaceId) {
     `;
     const rows = deps.db.prepare(listSql).all(deps.tenantId, normalizedWorkspaceId);
     return {
-        deleted: rows
-            .map((row) => mapDeletedTaskRowService(deps, row))
-            .filter((row) => Boolean(row))
+        deleted: mapDeletedTaskRowsService(deps, rows)
     };
 }
 export function listDeletedTasksReadOnlyService(deps, workspaceId) {
@@ -240,9 +273,7 @@ export function listDeletedTasksReadOnlyService(deps, workspaceId) {
     `;
     const rows = deps.db.prepare(listSql).all(deps.tenantId, normalizedWorkspaceId);
     return {
-        deleted: rows
-            .map((row) => mapDeletedTaskRowService(deps, row))
-            .filter((row) => Boolean(row))
+        deleted: mapDeletedTaskRowsService(deps, rows)
             .filter((row) => row.deletedAt >= cutoff || durableDeleteOwnedTaskIds.has(row.taskId))
     };
 }

package/dist/core/TaskAttachmentLinksDurableMutationService.d.ts

@@ -8,7 +8,7 @@ export declare class DurableTaskAttachmentLinksApplyError extends Error {
     constructor(message: string, code: 'TASK_ATTACHMENT_ASSET_NOT_READY' | 'TASK_ATTACHMENT_ASSET_INVALID' | 'TASK_ATTACHMENT_LINK_INVALID', statusCode: number, assetId?: string | undefined);
 }
 export interface DurableTaskAttachmentLinksCore {
-    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'adoptReadableReferenceNumber'>;
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'adoptReadableReferenceNumber' | 'restoreDeleted'>;
     getWorkspaceAssetDispatchReadiness(assetId: string, workspaceId: string): {
         ready: boolean;
         retryable: boolean;
@@ -16,7 +16,7 @@ export interface DurableTaskAttachmentLinksCore {
     };
 }
 export interface DurableWorkspaceTaskAttachmentLinksCore extends DurableTaskAttachmentLinksCore {
-    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'listLinksForWorkspace' | 'listAllNormalizedByWorkspace' | 'adoptReadableReferenceNumber'>;
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'listLinksForWorkspace' | 'listAllNormalizedByWorkspace' | 'adoptReadableReferenceNumber' | 'restoreDeleted'>;
 }
 export declare function resolveTaskCardCoverAssetIdForLinks(input: {
     currentCardCoverAssetId?: string | null;
@@ -29,6 +29,7 @@ export declare function resolveTaskAttachmentLinksForDurableSync(core: DurableTa
     requireDispatchReady?: boolean;
     adoptAuthoritativeReferenceNumber?: boolean;
     ignoreAssetMetadataSnapshots?: boolean;
+    restoreDeletedExternalAssetForAuthoritativeSync?: boolean;
 }): AttachmentItem[];
 export declare function normalizeTaskAttachmentDescriptorsForDurableSync(core: DurableTaskAttachmentLinksCore, workspaceId: string, attachments: readonly AttachmentItem[], options?: {
     requireDispatchReady?: boolean;

package/dist/core/TaskAttachmentLinksDurableMutationService.js

@@ -53,6 +53,12 @@ function canonicalRole(asset, requested) {
     }
     return expected;
 }
+function canonicalPersistedRole(asset, persisted) {
+    // Historical external links predate the reference-only invariant. Repair
+    // projections must publish the current canonical shape, while mutation
+    // inputs continue through canonicalRole and remain strictly validated.
+    return asset.storageProvider === 'external' ? 'reference' : canonicalRole(asset, persisted);
+}
 function referenceFields(asset) {
     if (!asset.referenceNumber)
         return { referenceNumber: null, referenceLabel: null };
@@ -83,9 +89,13 @@ function assertReady(core, workspaceId, asset, options) {
     }
 }
 function canonicalLink(asset, link, fallbackOrder) {
+    // Historical task links could persist an external asset as an attachment.
+    // External assets are references by contract, so repair/export must emit the
+    // canonical role rather than reproducing an un-installable legacy link.
+    const role = asset.storageProvider === 'external' ? 'reference' : link.role;
     return {
         assetId: asset.assetId,
-        role: link.role,
+        role,
         order: Number.isSafeInteger(link.sortOrder) && Number(link.sortOrder) >= 0
             ? Number(link.sortOrder)
             : fallbackOrder,
@@ -107,7 +117,7 @@ export function listTaskAttachmentLinksForDurableSync(core, workspaceId, taskId)
             fail(`Task attachment asset is deleted: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
         }
         assertReady(core, workspaceId, asset);
-        return canonicalLink(asset, link, index);
+        return canonicalLink(asset, { ...link, role: canonicalPersistedRole(asset, link.role) }, index);
     })
         .sort((left, right) => left.order - right.order
         || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0)
@@ -139,7 +149,7 @@ export function listWorkspaceTaskAttachmentLinksForDurableSync(core, workspaceId
                 fail(`Task attachment asset is deleted: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
             }
             assertReady(core, workspaceId, asset);
-            return canonicalLink(asset, link, index);
+            return canonicalLink(asset, { ...link, role: canonicalPersistedRole(asset, link.role) }, index);
         }).sort((left, right) => left.order - right.order
             || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0)
             || (left.role < right.role ? -1 : left.role > right.role ? 1 : 0))
@@ -156,6 +166,14 @@ export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, link
         if (!asset) {
             fail(`Task attachment asset is unavailable because it has not reached this runtime: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425, link.assetId);
         }
+        if (asset.deletedAt
+            && asset.storageProvider === 'external'
+            && options?.restoreDeletedExternalAssetForAuthoritativeSync === true) {
+            // External pointers do not travel through binary content hydration.
+            // An active authoritative link is the lifecycle proof needed to
+            // revive the existing local placeholder inside the apply transaction.
+            asset = store.restoreDeleted(asset.assetId, workspaceId, asset.updatedAt) || asset;
+        }
         assertReady(core, workspaceId, asset, options);
         // Replicated apply may align independently hydrated local D-/I- numbers
         // to cloud authority. Ordinary local/cloud mutation writers must never
@@ -175,8 +193,8 @@ export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, link
         const displayName = String(link.displayName
             || (options?.ignoreAssetMetadataSnapshots === true ? '' : link.originalFilename)
             || (options?.ignoreAssetMetadataSnapshots === true ? '' : link.caption)
-            || asset.originalFilename
-            || asset.logicalName).trim() || null;
+            || (options?.ignoreAssetMetadataSnapshots === true ? '' : asset.originalFilename)
+            || (options?.ignoreAssetMetadataSnapshots === true ? '' : asset.logicalName)).trim() || null;
         const projected = canonicalLink(asset, { role, displayName, sortOrder: index }, index);
         if (options?.ignoreAssetMetadataSnapshots !== true
             && ((link.referenceNumber ?? null) !== (projected.referenceNumber ?? null)
@@ -187,12 +205,18 @@ export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, link
             path: canonicalAssetPath(asset),
             assetId: asset.assetId,
             linkRole: role,
-            ...(asset.kind === 'document' && asset.storageProvider !== 'external' && projected.caption !== undefined
+            ...(options?.ignoreAssetMetadataSnapshots !== true
+                && asset.kind === 'document'
+                && asset.storageProvider !== 'external'
+                && projected.caption !== undefined
                 ? { caption: projected.caption } : {}),
             ...(projected.displayName !== undefined ? { displayName: projected.displayName } : {}),
-            ...(projected.originalFilename !== undefined ? { originalFilename: projected.originalFilename } : {}),
-            ...(projected.referenceNumber !== undefined ? { referenceNumber: projected.referenceNumber } : {}),
-            ...(projected.referenceLabel !== undefined ? { referenceLabel: projected.referenceLabel } : {}),
+            ...(options?.ignoreAssetMetadataSnapshots !== true && projected.originalFilename !== undefined
+                ? { originalFilename: projected.originalFilename } : {}),
+            ...(options?.ignoreAssetMetadataSnapshots !== true && projected.referenceNumber !== undefined
+                ? { referenceNumber: projected.referenceNumber } : {}),
+            ...(options?.ignoreAssetMetadataSnapshots !== true && projected.referenceLabel !== undefined
+                ? { referenceLabel: projected.referenceLabel } : {}),
         };
     });
 }

package/dist/core/Taskforce.d.ts

@@ -95,6 +95,17 @@ export interface AuditActivityItem {
     event: TaskEvent;
 }
 export type TaskActivityItem = CommentActivityItem | AuditActivityItem;
+export type TaskActivitySummaryItem = {
+    id: string;
+    type: 'comment';
+    timestamp: string;
+    comment: Pick<Comment, 'text' | 'author' | 'actor'>;
+} | {
+    id: string;
+    type: 'event';
+    timestamp: string;
+    event: Pick<TaskEvent, 'action' | 'details' | 'actor' | 'actorType' | 'actorProfile'>;
+};
 export interface EntityAuditActivityItem {
     id: string;
     type: 'event';
@@ -153,6 +164,7 @@ export interface TaskItem {
     taskEvents?: TaskEvent[];
     attachments?: AttachmentItem[];
     cardCoverAssetId?: string | null;
+    cardCoverAttachment?: Exclude<AttachmentItem, string> | null;
     /** @deprecated Use status='done'. Safe to remove after v0.4.x migration gate. */
     completed?: boolean;
     /** @deprecated Use status='cancelled'. Safe to remove after v0.4.x migration gate. */
@@ -171,7 +183,27 @@ export interface TaskItem {
     workstreamOrder?: number | null;
     workstreamId?: string | null;
     checklistItems?: ChecklistItem[];
-}
+    /** True when this object came from a collection read and omits the full task graph. */
+    isSummary?: boolean;
+    commentCount?: number;
+    checklistCount?: number;
+    completedChecklistCount?: number;
+    attachmentCount?: number;
+    relationshipCount?: number;
+    /** Compact newest comment or audit event carried by lightweight collection reads. */
+    latestActivity?: TaskActivitySummaryItem | null;
+    detailRevision?: string;
+}
+export type TaskSummary = Omit<TaskItem, 'description' | 'comments' | 'activity' | 'taskEvents' | 'attachments' | 'checklistItems'> & {
+    isSummary: true;
+    commentCount: number;
+    checklistCount: number;
+    completedChecklistCount: number;
+    attachmentCount: number;
+    relationshipCount: number;
+    latestActivity: TaskActivitySummaryItem | null;
+    detailRevision: string;
+};
 export type AttachmentItem = string | {
     path: string;
     fsPath?: string;
@@ -351,12 +383,23 @@ export interface TaskFile {
         manualComplexityEnabled?: boolean;
         checklistDropdownEnabled?: boolean;
         showTaskCardStatusLabel?: boolean;
+        showTaskCardDescription?: boolean;
+        showTaskCardAttachments?: boolean;
+        showTaskCardChecklistProgress?: boolean;
+        showTaskCardLatestActivity?: boolean;
+        tintTaskCardActivityBackground?: boolean;
         taxonomies?: any[];
     };
 }
 export interface ArchiveFile {
     archived: TaskItem[];
 }
+export interface TaskSummaryFile {
+    tasks: TaskSummary[];
+}
+export interface ArchiveSummaryFile {
+    archived: TaskSummary[];
+}
 export interface BulkCreateTaskError {
     index: number;
     message: string;
@@ -997,6 +1040,7 @@ export interface TaskforceSyncCapable {
         repairLegacyBinding?: boolean;
     }): AiProfileRecord | null;
     resolveWorkspaceActor(workspaceId: string, actorRef: unknown): TaskActor | null;
+    resolveWorkspaceActors(workspaceId: string, actorRefs: unknown[]): Map<string, TaskActor | null>;
 }
 export type TaskRelationshipInputType = 'depends_on' | 'blocks' | 'related_to' | 'supersedes';
 export type TaskRelationshipKind = 'dependency' | 'related' | 'supersedes';
@@ -1146,6 +1190,7 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         requireDispatchReady?: boolean;
         adoptAuthoritativeReferenceNumber?: boolean;
         ignoreAssetMetadataSnapshots?: boolean;
+        restoreDeletedExternalAssetForAuthoritativeSync?: boolean;
     }): AttachmentItem[];
     private normalizeEntitlementState;
     private upsertCanonicalEntitlementRecord;
@@ -1445,6 +1490,16 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
     private getSyncReconciliationServiceDeps;
     private getWorkspaceLifecycleServiceDeps;
     listTasks(workspaceId?: string): TaskFile;
+    private listTaskSummaries;
+    listActiveTaskSummaries(workspaceId?: string): TaskSummaryFile;
+    listArchiveSummaries(workspaceId?: string): ArchiveSummaryFile;
+    getTaskDetailRevision(id: string, workspaceId?: string): string | null;
+    getTaskDetailSnapshot(id: string, workspaceId?: string): TaskItem | null;
+    updateTaskIfDetailRevisionMatches(id: string, expectedDetailRevision: string, updates: Partial<TaskItem>, workspaceId?: string, options?: {
+        actorRef?: string;
+        saveSource?: 'manual' | 'autosave';
+    }): TaskItem | null;
+    assertTaskDetailRevisionForUpdate(id: string, expectedDetailRevision: string, workspaceId?: string): void;
     /**
      * Filter-pushdown listing used by read-only surfaces that don't need the
      * full task graph (MCP list_tasks, CLI summaries). Avoids the per-task
@@ -1480,7 +1535,10 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         title: string;
         status: TaskStatus;
     }>;
-    searchTaskSummaries(query: string, scope?: 'all' | 'active' | 'archive', workspaceId?: string): Array<Record<string, unknown>>;
+    searchTaskSummaries(query: string, scope?: 'all' | 'active' | 'archive', workspaceId?: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Array<Record<string, unknown>>;
     getDataVersion(): number;
     getDatabaseProvider(): DatabaseProvider;
     isDatabaseHealthy(): boolean;
@@ -1805,7 +1863,9 @@ export declare class TaskforceCore implements TaskforceSyncCapable {
         sessionId: string;
     }): boolean;
     private getAiProfileServiceDeps;
+    private buildUnresolvedWorkspaceActor;
     resolveWorkspaceActor(workspaceId: string, actorRef: unknown): TaskActor | null;
+    resolveWorkspaceActors(workspaceId: string, actorRefs: unknown[]): Map<string, TaskActor | null>;
     listAssignableActors(workspaceId: string): TaskActor[];
     addAdminAuditLog(input: {
         action: string;