@taskforcehq/taskforce 0.3.306 → 0.3.307

package/dist/core/Taskforce.js

@@ -8,9 +8,9 @@ import { createDatabaseAdapter } from '../storage/createDatabaseAdapter.js';
 import { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
 import { AuthTokenService } from './AuthTokenService.js';
 import { AuthIdentityService } from './AuthIdentityService.js';
-import { archiveAiProfileService, getAiProfileByTokenService, listAiProfilesService, mergeAiProfilesService, resolveAiProfileService, updateAiProfileAvatarService, upsertAiProfileForSyncService, } from './AiProfileService.js';
-import { syncCanonicalTaskAttachmentLinksService, } from './AttachmentLinkService.js';
-import { addTaskEventService, buildTaskActivityService, listTaskEventsInternalService, listWorkspaceTaskEventsService, replaceTaskCommentsService, replaceTaskEventsService, upsertTaskEventForSyncService, } from './TaskActivityService.js';
+import { archiveAiProfileService, getAiProfileByTokenService, listAiProfilesService, mergeAiProfilesService, resolveAiProfileService, updateAiProfileAvatarService, updateAiProfileSurfaceTypeService, upsertAiProfileForSyncService, } from './AiProfileService.js';
+import { syncCanonicalAttachmentLinksForTargetService, syncCanonicalTaskAttachmentLinksService, } from './AttachmentLinkService.js';
+import { addEntityEventService, addTaskEventService, buildEntityActivityService, buildTaskActivityService, getEntityEventForSyncService, getTaskEventForSyncService, listEntityEventsInternalService, listWorkspaceEntityEventsForSyncService, listTaskEventsInternalService, listWorkspaceTaskEventsForSyncService, replaceEntityEventsService, replaceTaskCommentsService, replaceTaskEventsService, upsertEntityEventForSyncService, upsertTaskEventForSyncService, } from './TaskActivityService.js';
 import { addDeletedTaskRecordService, getDeletedTaskService, listDeletedTasksService, mapDeletedTaskRowService, normalizeTaskSnapshotForRestoreService, pruneDeletedTasksService, purgeExpiredDeletedTasksService, } from './DeletedTaskLifecycleService.js';
 import { applyWorkspaceSyncSnapshotService, deleteDocumentWatermarkService, getDocumentWatermarkService, listTasksForSyncService, listWorkspaceSyncDeletesSinceService, readPushIdempotencyService, recordSyncEventService, upsertDocumentWatermarkService, writePushIdempotencyService, } from './SyncReconciliationService.js';
 import { getGlobalSettingsService, hasPersistedGlobalSettingsService, readGlobalConfigService, updateGlobalSettingsService, writeGlobalConfigService, } from './GlobalSettingsService.js';
@@ -268,6 +268,15 @@ export class TaskforceCore {
         const normalized = String(value || '').trim().toLowerCase();
         return normalized === 'user' || normalized === 'human';
     }
+    isStableActorReference(value) {
+        const normalized = String(value || '').trim().toLowerCase();
+        if (!normalized)
+            return false;
+        return normalized === 'user'
+            || normalized === 'system'
+            || normalized.startsWith('user-')
+            || normalized.startsWith('ai-profile-');
+    }
     normalizeAiProfileName(name) {
         const normalized = String(name || '').trim();
         if (!normalized) {
@@ -375,6 +384,8 @@ export class TaskforceCore {
             color: this.normalizeAiProfileColor(row.color),
             avatarUrl: typeof row.avatar_url === 'string' && row.avatar_url.trim().length > 0 ? row.avatar_url.trim() : null,
             avatarSourceUrl: typeof row.avatar_source_url === 'string' && row.avatar_source_url.trim().length > 0 ? row.avatar_source_url.trim() : null,
+            avatarRevision: Number.isFinite(Number(row.avatar_revision)) ? Math.max(0, Math.floor(Number(row.avatar_revision))) : 0,
+            avatarUpdatedAt: typeof row.avatar_updated_at === 'string' && row.avatar_updated_at.trim().length > 0 ? row.avatar_updated_at.trim() : null,
             description: typeof row.description === 'string' && row.description.trim().length > 0 ? row.description.trim() : null,
             role: typeof row.role === 'string' && row.role.trim().length > 0 ? row.role.trim() : null,
             provider: typeof row.provider === 'string' && row.provider.trim().length > 0 ? row.provider.trim() : null,
@@ -404,7 +415,6 @@ export class TaskforceCore {
             color: profile.color,
             isNamed: true,
             meta: {
-                profileToken: profile.profileToken,
                 workspaceId: profile.workspaceId,
                 avatarUrl: profile.avatarUrl ?? null,
                 avatarSourceUrl: profile.avatarSourceUrl ?? null,
@@ -423,6 +433,59 @@ export class TaskforceCore {
             }
         };
     }
+    resolveCanonicalAiProfileId(rowById, profileId) {
+        let currentId = String(profileId || '').trim();
+        const visited = new Set();
+        while (currentId) {
+            if (visited.has(currentId))
+                break;
+            visited.add(currentId);
+            const row = rowById.get(currentId);
+            const mergedIntoProfileId = String(row?.merged_into_profile_id || '').trim();
+            if (!mergedIntoProfileId || mergedIntoProfileId === currentId)
+                break;
+            currentId = mergedIntoProfileId;
+        }
+        return currentId;
+    }
+    findCanonicalAiProfileIdsByAlias(workspaceId, actorRef) {
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const rawActorRef = String(actorRef || '').trim();
+        if (!rawActorRef)
+            return [];
+        const matches = this.db.prepare(`
+            SELECT *
+            FROM ai_profiles
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND (
+                  LOWER(name) = LOWER(?)
+                  OR LOWER(username) = LOWER(?)
+              )
+            ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
+        `).all(this.tenantId, normalizedWorkspaceId, rawActorRef, rawActorRef);
+        const rowById = new Map(matches
+            .map((row) => [String(row.id || '').trim(), row])
+            .filter(([id]) => Boolean(id)));
+        return [...new Set(matches
+                .map((row) => this.resolveCanonicalAiProfileId(rowById, String(row.id || '').trim()))
+                .filter(Boolean))];
+    }
+    resolveUniqueAiProfileActorByAlias(workspaceId, actorRef) {
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const uniqueCanonicalIds = this.findCanonicalAiProfileIdsByAlias(normalizedWorkspaceId, actorRef);
+        if (uniqueCanonicalIds.length !== 1)
+            return null;
+        const resolvedRow = this.db.prepare(`
+            SELECT *
+            FROM ai_profiles
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedWorkspaceId, uniqueCanonicalIds[0]);
+        return resolvedRow ? this.aiProfileToActor(this.aiProfileRowToRecord(resolvedRow)) : null;
+    }
     canonicalizeActorReference(workspaceId, value, fallback) {
         const raw = String(value || '').trim();
         if (!raw)
@@ -531,8 +594,21 @@ export class TaskforceCore {
                 normalized.fsPath = raw.fsPath.trim();
             if (typeof raw.caption === 'string' && raw.caption.trim())
                 normalized.caption = raw.caption.trim();
+            if (typeof raw.displayName === 'string' && raw.displayName.trim())
+                normalized.displayName = raw.displayName.trim();
+            if (typeof raw.originalFilename === 'string' && raw.originalFilename.trim())
+                normalized.originalFilename = raw.originalFilename.trim();
             if (typeof raw.timestamp === 'string' && raw.timestamp.trim())
                 normalized.timestamp = raw.timestamp.trim();
+            if (typeof raw.assetId === 'string' && raw.assetId.trim())
+                normalized.assetId = raw.assetId.trim();
+            const referenceNumber = this.sanitizeTaskReferenceNumber(raw.referenceNumber);
+            if (referenceNumber !== null)
+                normalized.referenceNumber = referenceNumber;
+            if (typeof raw.referenceLabel === 'string' && raw.referenceLabel.trim())
+                normalized.referenceLabel = raw.referenceLabel.trim();
+            if (typeof raw.taskId === 'string' && raw.taskId.trim())
+                normalized.taskId = raw.taskId.trim();
             return normalized;
         })
             .filter((attachment) => attachment !== null);
@@ -552,15 +628,27 @@ export class TaskforceCore {
             actorProfile
         };
     }
+    listEntityEventsInternal(entityType, entityId, workspaceId) {
+        return listEntityEventsInternalService(this.getTaskActivityServiceDeps(), entityType, entityId, workspaceId);
+    }
     listTaskEventsInternal(taskId, workspaceId) {
         return listTaskEventsInternalService(this.getTaskActivityServiceDeps(), taskId, workspaceId);
     }
+    buildEntityActivity(comments, entityEvents, hiddenActions) {
+        return buildEntityActivityService(comments, entityEvents, hiddenActions?.length ? { hiddenActions } : undefined);
+    }
     buildTaskActivity(comments, taskEvents) {
         return buildTaskActivityService(comments, taskEvents);
     }
+    addEntityEvent(input) {
+        addEntityEventService(this.getTaskActivityServiceDeps(), input);
+    }
     addTaskEvent(input) {
         addTaskEventService(this.getTaskActivityServiceDeps(), input);
     }
+    replaceEntityEvents(entityType, entityId, workspaceId, entityEvents) {
+        replaceEntityEventsService(this.getTaskActivityServiceDeps(), entityType, entityId, workspaceId, entityEvents);
+    }
     replaceTaskEvents(taskId, workspaceId, taskEvents) {
         replaceTaskEventsService(this.getTaskActivityServiceDeps(), taskId, workspaceId, taskEvents);
     }
@@ -1066,6 +1154,65 @@ export class TaskforceCore {
         }
         return (existingValue ?? null) === (nextValue ?? null);
     }
+    buildPlanningEntityEventChanges(existing, next, fields) {
+        const changes = {};
+        for (const field of fields) {
+            const previousValue = existing[field] ?? null;
+            const nextValue = next[field] ?? null;
+            if (JSON.stringify(previousValue) === JSON.stringify(nextValue))
+                continue;
+            changes[field] = { from: previousValue, to: nextValue };
+        }
+        return changes;
+    }
+    getPlanningEntityEventAction(entityType, changes) {
+        const fields = Object.keys(changes);
+        if (fields.length === 1 && fields[0] === 'attachments') {
+            return `${entityType}-attachments-changed`;
+        }
+        if (entityType === 'workstream' && fields.length === 1 && fields[0] === 'initiativeId') {
+            return 'workstream-relationship-changed';
+        }
+        return `${entityType}-updated`;
+    }
+    addWorkstreamTaskMembershipEvents(input) {
+        const previousWorkstreamId = this.sanitizeWorkstreamId(input.previousWorkstreamId);
+        const nextWorkstreamId = this.sanitizeWorkstreamId(input.nextWorkstreamId);
+        if (previousWorkstreamId === nextWorkstreamId)
+            return;
+        const details = {
+            taskId: input.task.id,
+            taskTitle: input.task.title,
+            changes: {
+                workstreamId: {
+                    from: previousWorkstreamId ?? null,
+                    to: nextWorkstreamId ?? null,
+                }
+            }
+        };
+        if (previousWorkstreamId) {
+            this.addEntityEvent({
+                entityType: 'workstream',
+                entityId: previousWorkstreamId,
+                workspaceId: input.workspaceId,
+                action: 'workstream-task-removed',
+                actor: input.actor,
+                createdAt: input.createdAt,
+                details,
+            });
+        }
+        if (nextWorkstreamId) {
+            this.addEntityEvent({
+                entityType: 'workstream',
+                entityId: nextWorkstreamId,
+                workspaceId: input.workspaceId,
+                action: 'workstream-task-added',
+                actor: input.actor,
+                createdAt: input.createdAt,
+                details,
+            });
+        }
+    }
     assertWorkstreamLinkAllowed(workstreamId, workspaceId) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         if (!workstreamId)
@@ -1470,6 +1617,19 @@ export class TaskforceCore {
                 FOREIGN KEY(task_id) REFERENCES tasks(id) ON DELETE CASCADE
             );
 
+            CREATE TABLE IF NOT EXISTS entity_events (
+                id TEXT PRIMARY KEY,
+                tenant_id TEXT NOT NULL DEFAULT 'default',
+                workspace_id TEXT NOT NULL DEFAULT 'default',
+                entity_type TEXT NOT NULL,
+                entity_id TEXT NOT NULL,
+                action TEXT NOT NULL,
+                actor TEXT NOT NULL,
+                actor_type TEXT NOT NULL,
+                details_json TEXT,
+                created_at TEXT NOT NULL
+            );
+
             CREATE TABLE IF NOT EXISTS deleted_tasks (
                 id TEXT PRIMARY KEY,
                 tenant_id TEXT NOT NULL DEFAULT 'default',
@@ -1598,6 +1758,9 @@ export class TaskforceCore {
                 token_prefix TEXT NOT NULL,
                 token_hash TEXT NOT NULL,
                 status TEXT NOT NULL DEFAULT 'active',
+                ai_profile_id TEXT,
+                ai_profile_token TEXT,
+                ai_profile_name TEXT,
                 last_used_at TEXT,
                 revoked_at TEXT,
                 revoked_by_user_id TEXT,
@@ -1656,6 +1819,8 @@ export class TaskforceCore {
                 color TEXT NOT NULL,
                 avatar_url TEXT,
                 avatar_source_url TEXT,
+                avatar_revision INTEGER NOT NULL DEFAULT 0,
+                avatar_updated_at TEXT,
                 description TEXT,
                 role TEXT,
                 provider TEXT,
@@ -1682,6 +1847,8 @@ export class TaskforceCore {
             CREATE INDEX IF NOT EXISTS idx_admin_audit_logs_workspace_created ON admin_audit_logs(workspace_id, created_at);
             CREATE INDEX IF NOT EXISTS idx_task_events_task_created ON task_events(tenant_id, workspace_id, task_id, created_at);
             CREATE INDEX IF NOT EXISTS idx_task_events_workspace_created ON task_events(tenant_id, workspace_id, created_at);
+            CREATE INDEX IF NOT EXISTS idx_entity_events_entity_created ON entity_events(tenant_id, workspace_id, entity_type, entity_id, created_at);
+            CREATE INDEX IF NOT EXISTS idx_entity_events_workspace_created ON entity_events(tenant_id, workspace_id, created_at);
             CREATE UNIQUE INDEX IF NOT EXISTS idx_deleted_tasks_workspace_task ON deleted_tasks(tenant_id, workspace_id, task_id);
             CREATE INDEX IF NOT EXISTS idx_deleted_tasks_workspace_deleted ON deleted_tasks(tenant_id, workspace_id, deleted_at);
             CREATE INDEX IF NOT EXISTS idx_mcp_audit_logs_workspace_created ON mcp_audit_logs(tenant_id, workspace_id, created_at);
@@ -1786,6 +1953,25 @@ export class TaskforceCore {
                 // Best-effort schema repair for older deployments.
             }
         }
+        if (this.db.provider === 'sqlite') {
+            this.db.exec(`
+                INSERT OR IGNORE INTO entity_events (
+                    id, tenant_id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
+                )
+                SELECT id, tenant_id, workspace_id, 'task', task_id, action, actor, actor_type, details_json, created_at
+                FROM task_events
+            `);
+        }
+        else {
+            this.db.exec(`
+                INSERT INTO entity_events (
+                    id, tenant_id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
+                )
+                SELECT id, tenant_id, workspace_id, 'task', task_id, action, actor, actor_type, details_json, created_at
+                FROM task_events
+                ON CONFLICT (id) DO NOTHING
+            `);
+        }
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_workstream ON tasks(tenant_id, workspace_id, workstream_id)`);
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(tenant_id, workspace_id, assignee, is_archived)`);
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_workstreams_initiative ON workstreams(tenant_id, workspace_id, initiative_id)`);
@@ -1806,6 +1992,28 @@ export class TaskforceCore {
             }
         }
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_auth_tokens_workspace_purpose ON auth_tokens(workspace_id, purpose)`);
+        if (this.db.provider === 'sqlite') {
+            const mcpOauthGrantColumns = this.db.prepare(`PRAGMA table_info(mcp_oauth_connector_grants)`).all();
+            if (!mcpOauthGrantColumns.some((c) => c.name === 'ai_profile_id')) {
+                this.db.exec(`ALTER TABLE mcp_oauth_connector_grants ADD COLUMN ai_profile_id TEXT`);
+            }
+            if (!mcpOauthGrantColumns.some((c) => c.name === 'ai_profile_token')) {
+                this.db.exec(`ALTER TABLE mcp_oauth_connector_grants ADD COLUMN ai_profile_token TEXT`);
+            }
+            if (!mcpOauthGrantColumns.some((c) => c.name === 'ai_profile_name')) {
+                this.db.exec(`ALTER TABLE mcp_oauth_connector_grants ADD COLUMN ai_profile_name TEXT`);
+            }
+        }
+        else {
+            try {
+                this.db.exec(`ALTER TABLE mcp_oauth_connector_grants ADD COLUMN IF NOT EXISTS ai_profile_id TEXT`);
+                this.db.exec(`ALTER TABLE mcp_oauth_connector_grants ADD COLUMN IF NOT EXISTS ai_profile_token TEXT`);
+                this.db.exec(`ALTER TABLE mcp_oauth_connector_grants ADD COLUMN IF NOT EXISTS ai_profile_name TEXT`);
+            }
+            catch {
+                // Best-effort schema repair for existing deployments.
+            }
+        }
         if (this.db.provider === 'sqlite') {
             const mcpAuditColumns = this.db.prepare(`PRAGMA table_info(mcp_audit_logs)`).all();
             if (!mcpAuditColumns.some((c) => c.name === 'request_id')) {
@@ -1906,6 +2114,8 @@ export class TaskforceCore {
                 { name: 'color', ddl: `ALTER TABLE ai_profiles ADD COLUMN color TEXT NOT NULL DEFAULT '#64748b'` },
                 { name: 'avatar_url', ddl: `ALTER TABLE ai_profiles ADD COLUMN avatar_url TEXT` },
                 { name: 'avatar_source_url', ddl: `ALTER TABLE ai_profiles ADD COLUMN avatar_source_url TEXT` },
+                { name: 'avatar_revision', ddl: `ALTER TABLE ai_profiles ADD COLUMN avatar_revision INTEGER NOT NULL DEFAULT 0` },
+                { name: 'avatar_updated_at', ddl: `ALTER TABLE ai_profiles ADD COLUMN avatar_updated_at TEXT` },
                 { name: 'description', ddl: `ALTER TABLE ai_profiles ADD COLUMN description TEXT` },
                 { name: 'role', ddl: `ALTER TABLE ai_profiles ADD COLUMN role TEXT` },
                 { name: 'provider', ddl: `ALTER TABLE ai_profiles ADD COLUMN provider TEXT` },
@@ -1938,6 +2148,8 @@ export class TaskforceCore {
                 `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS color TEXT NOT NULL DEFAULT '#64748b'`,
                 `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS avatar_url TEXT`,
                 `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS avatar_source_url TEXT`,
+                `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS avatar_revision INTEGER NOT NULL DEFAULT 0`,
+                `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS avatar_updated_at TEXT`,
                 `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS description TEXT`,
                 `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS role TEXT`,
                 `ALTER TABLE ai_profiles ADD COLUMN IF NOT EXISTS provider TEXT`,
@@ -1978,10 +2190,30 @@ export class TaskforceCore {
                     AND roster_state_updated_at < archived_at
                )
         `);
+        this.db.exec(`
+            UPDATE ai_profiles
+            SET avatar_revision = CASE
+                    WHEN (
+                        (avatar_url IS NOT NULL AND TRIM(avatar_url) <> '')
+                        OR (avatar_source_url IS NOT NULL AND TRIM(avatar_source_url) <> '')
+                    ) THEN 1
+                    ELSE 0
+                END,
+                avatar_updated_at = CASE
+                    WHEN (
+                        (avatar_url IS NOT NULL AND TRIM(avatar_url) <> '')
+                        OR (avatar_source_url IS NOT NULL AND TRIM(avatar_source_url) <> '')
+                    ) THEN COALESCE(NULLIF(TRIM(avatar_updated_at), ''), NULLIF(TRIM(updated_at), ''), NULLIF(TRIM(created_at), ''))
+                    ELSE NULL
+                END
+            WHERE avatar_revision IS NULL
+               OR avatar_revision = 0
+        `);
         this.migrateSystemRoleBackfillIfNeeded();
         this.migrateUserBetaAccessBackfillIfNeeded();
         this.migrateDuplicateAiProfilesIfNeeded();
         this.migrateLegacyActorReferencesIfNeeded();
+        this.migrateLegacyCommentActorReferencesIfNeeded();
         // Ensure sync watermark index exists on existing databases (added in v0.3.52+).
         this.db.exec(`
             CREATE INDEX IF NOT EXISTS idx_tasks_sync_watermark ON tasks(tenant_id, workspace_id, updated_at, id);
@@ -2128,7 +2360,7 @@ export class TaskforceCore {
         if (existing?.payload)
             return;
         const rows = this.db.prepare(`
-            SELECT id, workspace_id, name, username, created_at, updated_at, last_active_at
+            SELECT id, workspace_id, name, username, seat_scope, created_at, updated_at, last_active_at
             FROM ai_profiles
             WHERE tenant_id = ?
         `).all(this.tenantId);
@@ -2137,7 +2369,8 @@ export class TaskforceCore {
             const workspaceId = this.normalizeWorkspaceId(row.workspace_id);
             const normalizedName = String(row.name || '').trim().toLowerCase();
             const normalizedUsername = String(row.username || '').trim().toLowerCase();
-            const dedupeKey = `${workspaceId}::${normalizedName || normalizedUsername}`;
+            const seatScope = String(row.seat_scope || 'unknown').trim().toLowerCase() || 'unknown';
+            const dedupeKey = `${workspaceId}::${seatScope}::${normalizedName || normalizedUsername}`;
             if (!normalizedName && !normalizedUsername)
                 continue;
             const list = groups.get(dedupeKey) || [];
@@ -2185,15 +2418,19 @@ export class TaskforceCore {
         if (existing?.payload)
             return;
         const rows = this.db.prepare(`
-            SELECT id, workspace_id, name, username
+            SELECT id, workspace_id, name, username, merged_into_profile_id
             FROM ai_profiles
             WHERE tenant_id = ?
         `).all(this.tenantId);
+        const rowById = new Map(rows
+            .map((row) => [String(row.id || '').trim(), row])
+            .filter(([id]) => Boolean(id)));
         const aliasesByWorkspace = new Map();
         for (const row of rows) {
             const workspaceId = this.normalizeWorkspaceId(row.workspace_id);
             const profileId = String(row.id || '').trim();
-            if (!profileId)
+            const canonicalProfileId = this.resolveCanonicalAiProfileId(rowById, profileId);
+            if (!canonicalProfileId)
                 continue;
             const aliases = [
                 String(row.name || '').trim().toLowerCase(),
@@ -2208,8 +2445,8 @@ export class TaskforceCore {
             }
             for (const alias of aliases) {
                 const ids = aliasMap.get(alias) || [];
-                if (!ids.includes(profileId))
-                    ids.push(profileId);
+                if (!ids.includes(canonicalProfileId))
+                    ids.push(canonicalProfileId);
                 aliasMap.set(alias, ids);
             }
         }
@@ -2250,6 +2487,135 @@ export class TaskforceCore {
                 updated_at = excluded.updated_at
         `).run(this.tenantId, migrationKey, JSON.stringify({ completedAt: now }), now);
     }
+    migrateLegacyCommentActorReferencesIfNeeded() {
+        const migrationKey = 'migration.actor_refs.canonicalize_comments.v2';
+        const existing = this.db.prepare(`
+            SELECT payload
+            FROM system_settings
+            WHERE tenant_id = ? AND settings_key = ?
+            LIMIT 1
+        `).get(this.tenantId, migrationKey);
+        if (existing?.payload)
+            return;
+        const commentRows = this.db.prepare(`
+            SELECT id, task_id, workspace_id, author, submitted_author
+            FROM comments
+            WHERE tenant_id = ?
+        `).all(this.tenantId);
+        const updateCommentAuthor = this.db.prepare(`
+            UPDATE comments
+            SET author = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `);
+        const updateTaskSyncWatermark = this.db.prepare(`
+            UPDATE tasks
+            SET updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `);
+        const selectTaskSyncWatermark = this.db.prepare(`
+            SELECT updated_at, created_at
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+            LIMIT 1
+        `);
+        let repairedCount = 0;
+        let ambiguousCount = 0;
+        let skippedCount = 0;
+        const touchedTaskIdsByWorkspace = new Map();
+        const now = new Date().toISOString();
+        const nowMs = Date.parse(now);
+        const tx = this.db.transaction(() => {
+            for (const row of commentRows) {
+                const workspaceId = this.normalizeWorkspaceId(row.workspace_id);
+                const commentId = String(row.id || '').trim();
+                const taskId = String(row.task_id || '').trim();
+                const rawAuthor = String(row.author || '').trim();
+                const rawSubmittedAuthor = String(row.submitted_author || '').trim();
+                const normalizedAuthor = rawAuthor.toLowerCase();
+                if (!commentId) {
+                    skippedCount += 1;
+                    continue;
+                }
+                if (this.isStableActorReference(rawAuthor)
+                    || this.isHumanActorReference(rawAuthor)
+                    || normalizedAuthor === 'system') {
+                    skippedCount += 1;
+                    continue;
+                }
+                const candidateIds = new Set();
+                let hasAmbiguousEvidence = false;
+                const evidenceValues = [rawAuthor, rawSubmittedAuthor];
+                for (const value of evidenceValues) {
+                    const rawValue = String(value || '').trim();
+                    const normalizedValue = rawValue.toLowerCase();
+                    if (!rawValue)
+                        continue;
+                    if (this.isHumanActorReference(rawValue)
+                        || this.isGenericAiActorReference(rawValue)
+                        || normalizedValue === 'system'
+                        || normalizedValue.startsWith('user-')) {
+                        continue;
+                    }
+                    if (normalizedValue.startsWith('ai-profile-')) {
+                        const actor = this.resolveWorkspaceActor(workspaceId, rawValue);
+                        if (actor?.kind === 'ai' && actor.meta?.unresolved !== true) {
+                            candidateIds.add(actor.id);
+                        }
+                        continue;
+                    }
+                    const matches = this.findCanonicalAiProfileIdsByAlias(workspaceId, rawValue);
+                    if (matches.length === 1) {
+                        candidateIds.add(matches[0]);
+                    }
+                    else if (matches.length > 1) {
+                        hasAmbiguousEvidence = true;
+                    }
+                }
+                if (!hasAmbiguousEvidence && candidateIds.size === 1) {
+                    updateCommentAuthor.run([...candidateIds][0], this.tenantId, workspaceId, commentId);
+                    if (taskId) {
+                        let touchedTaskIds = touchedTaskIdsByWorkspace.get(workspaceId);
+                        if (!touchedTaskIds) {
+                            touchedTaskIds = new Set();
+                            touchedTaskIdsByWorkspace.set(workspaceId, touchedTaskIds);
+                        }
+                        touchedTaskIds.add(taskId);
+                    }
+                    repairedCount += 1;
+                    continue;
+                }
+                if (hasAmbiguousEvidence || candidateIds.size > 1) {
+                    ambiguousCount += 1;
+                    continue;
+                }
+                skippedCount += 1;
+            }
+            for (const [workspaceId, touchedTaskIds] of touchedTaskIdsByWorkspace.entries()) {
+                for (const taskId of touchedTaskIds) {
+                    const taskRow = selectTaskSyncWatermark.get(this.tenantId, workspaceId, taskId);
+                    const existingWatermark = String(taskRow?.updated_at || taskRow?.created_at || '').trim();
+                    const existingWatermarkMs = Date.parse(existingWatermark);
+                    const nextWatermarkMs = Number.isFinite(existingWatermarkMs)
+                        ? Math.max(existingWatermarkMs, nowMs) + 1
+                        : nowMs;
+                    updateTaskSyncWatermark.run(new Date(nextWatermarkMs).toISOString(), this.tenantId, workspaceId, taskId);
+                }
+            }
+        });
+        tx();
+        this.db.prepare(`
+            INSERT INTO system_settings (tenant_id, settings_key, payload, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT (tenant_id, settings_key) DO UPDATE SET
+                payload = excluded.payload,
+                updated_at = excluded.updated_at
+        `).run(this.tenantId, migrationKey, JSON.stringify({
+            completedAt: now,
+            repairedCount,
+            ambiguousCount,
+            skippedCount,
+        }), now);
+    }
     getWorkspaceOwnerUserId(workspaceId) {
         const normalizedWorkspaceId = String(workspaceId || '').trim();
         if (!normalizedWorkspaceId)
@@ -2925,6 +3291,9 @@ export class TaskforceCore {
     syncCanonicalTaskAttachmentLinks(taskId, workspaceId, attachments) {
         syncCanonicalTaskAttachmentLinksService(this.getAttachmentLinkServiceDeps(), taskId, workspaceId, attachments);
     }
+    syncCanonicalPlanningAttachmentLinks(targetType, targetId, workspaceId, attachments) {
+        syncCanonicalAttachmentLinksForTargetService(this.getAttachmentLinkServiceDeps(), targetType, targetId, workspaceId, attachments);
+    }
     rowToTask(row) {
         const workspaceId = this.normalizeWorkspaceId(row?.workspace_id);
         const commentsRaw = this.db.prepare('SELECT * FROM comments WHERE tenant_id = ? AND workspace_id = ? AND task_id = ? ORDER BY timestamp ASC').all(this.tenantId, workspaceId, row.id);
@@ -2983,12 +3352,21 @@ export class TaskforceCore {
             checklistItems
         };
     }
-    rowToInitiative(row) {
+    rowToInitiative(row, options) {
+        const id = String(row.id || '').trim();
+        const workspaceId = this.normalizeWorkspaceId(typeof row.workspace_id === 'string' ? row.workspace_id : undefined);
         const referenceNumber = this.sanitizeTaskReferenceNumber(row.reference_number);
         const comments = this.normalizeIncomingComments(this.parseJsonField(row.comments_json, []));
+        const includeActivity = options?.includeActivity === true;
+        const entityEvents = includeActivity
+            ? this.listEntityEventsInternal('initiative', id, workspaceId)
+            : undefined;
+        const activity = includeActivity
+            ? this.buildEntityActivity(comments, entityEvents || [])
+            : undefined;
         const attachments = this.normalizePlanningAttachments(this.parseJsonField(row.attachments_json, []));
         return {
-            id: String(row.id || '').trim(),
+            id,
             referenceNumber,
             referenceLabel: formatInitiativeReference(referenceNumber),
             title: String(row.title || '').trim() || 'Untitled Initiative',
@@ -3000,14 +3378,27 @@ export class TaskforceCore {
             isArchived: Boolean(row.is_archived),
             comments,
             attachments,
+            ...(includeActivity ? {
+                activity,
+                entityEvents,
+            } : {}),
         };
     }
-    rowToWorkstream(row) {
+    rowToWorkstream(row, options) {
+        const id = String(row.id || '').trim();
+        const workspaceId = this.normalizeWorkspaceId(typeof row.workspace_id === 'string' ? row.workspace_id : undefined);
         const referenceNumber = this.sanitizeTaskReferenceNumber(row.reference_number);
         const comments = this.normalizeIncomingComments(this.parseJsonField(row.comments_json, []));
+        const includeActivity = options?.includeActivity === true;
+        const entityEvents = includeActivity
+            ? this.listEntityEventsInternal('workstream', id, workspaceId)
+            : undefined;
+        const activity = includeActivity
+            ? this.buildEntityActivity(comments, entityEvents || [])
+            : undefined;
         const attachments = this.normalizePlanningAttachments(this.parseJsonField(row.attachments_json, []));
         return {
-            id: String(row.id || '').trim(),
+            id,
             referenceNumber,
             referenceLabel: formatWorkstreamReference(referenceNumber),
             initiativeId: typeof row.initiative_id === 'string' && row.initiative_id.trim().length > 0 ? row.initiative_id.trim() : null,
@@ -3020,6 +3411,10 @@ export class TaskforceCore {
             isArchived: Boolean(row.is_archived),
             comments,
             attachments,
+            ...(includeActivity ? {
+                activity,
+                entityEvents,
+            } : {}),
         };
     }
     rowToChecklistItem(row) {
@@ -3072,7 +3467,7 @@ export class TaskforceCore {
         `).get(this.tenantId, normalizedWorkspaceId, normalizedId);
         if (!row)
             return null;
-        return this.rowToInitiative(row);
+        return this.rowToInitiative(row, { includeActivity: true });
     }
     listInitiatives(workspaceId) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
@@ -3084,7 +3479,45 @@ export class TaskforceCore {
         `).all(this.tenantId, normalizedWorkspaceId);
         return rows.map((row) => this.rowToInitiative(row));
     }
-    createInitiative(input, workspaceId) {
+    isTransientPlanningHydrationError(error) {
+        const message = error instanceof Error ? String(error.message || '').trim() : String(error || '').trim();
+        if (!message)
+            return false;
+        return /(timed out|timeout|ETIMEDOUT|query canceled|statement timeout|database timeout|postgres worker)/i.test(message);
+    }
+    getInitiativeForWriteResult(id, workspaceId, fallback, context) {
+        try {
+            return this.getInitiative(id, workspaceId) || fallback;
+        }
+        catch (error) {
+            if (!this.isTransientPlanningHydrationError(error))
+                throw error;
+            console.warn('[Taskforce] Falling back to post-write initiative snapshot after hydration failed', {
+                context,
+                initiativeId: id,
+                workspaceId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return fallback;
+        }
+    }
+    getWorkstreamForWriteResult(id, workspaceId, fallback, context) {
+        try {
+            return this.getWorkstream(id, workspaceId) || fallback;
+        }
+        catch (error) {
+            if (!this.isTransientPlanningHydrationError(error))
+                throw error;
+            console.warn('[Taskforce] Falling back to post-write workstream snapshot after hydration failed', {
+                context,
+                workstreamId: id,
+                workspaceId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return fallback;
+        }
+    }
+    createInitiative(input, workspaceId, options) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         const id = String(input.id || '').trim() || this.generateEntityId('initiative');
         const referenceNumber = this.reserveInitiativeReferenceNumber(normalizedWorkspaceId, input.referenceNumber);
@@ -3123,18 +3556,37 @@ export class TaskforceCore {
             sortOrder: initiative.order,
             isArchived: initiative.isArchived ? 1 : 0,
         });
-        return initiative;
+        this.syncCanonicalPlanningAttachmentLinks('initiative', initiative.id, normalizedWorkspaceId, initiative.attachments || []);
+        if (options?.skipEntityEvents !== true) {
+            this.addEntityEvent({
+                entityType: 'initiative',
+                entityId: initiative.id,
+                workspaceId: normalizedWorkspaceId,
+                action: 'initiative-created',
+                actor: options?.actorRef || 'system',
+                createdAt: initiative.updatedAt || initiative.createdAt,
+                details: {
+                    title: initiative.title,
+                    ownerId: initiative.ownerId || null,
+                }
+            });
+        }
+        return this.getInitiativeForWriteResult(initiative.id, normalizedWorkspaceId, initiative, 'createInitiative:post-write');
     }
-    updateInitiative(id, patch, workspaceId) {
+    updateInitiative(id, patch, workspaceId, options) {
         const existing = this.getInitiative(id, workspaceId);
         if (!existing) {
             throw new TaskforceRuleError(`Initiative not found: ${id}`, 404, 'INITIATIVE_NOT_FOUND');
         }
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const nextAttachments = Object.prototype.hasOwnProperty.call(patch, 'attachments') && Array.isArray(patch.attachments)
+            ? patch.attachments
+            : existing.attachments;
         const next = {
             ...existing,
             ...patch,
             id: existing.id,
+            attachments: nextAttachments,
             updatedAt: String(patch.updatedAt || '').trim() || new Date().toISOString(),
             referenceLabel: formatInitiativeReference(patch.referenceNumber ?? existing.referenceNumber),
         };
@@ -3164,25 +3616,68 @@ export class TaskforceCore {
             sortOrder: next.order,
             isArchived: next.isArchived ? 1 : 0,
         });
-        return this.getInitiative(existing.id, normalizedWorkspaceId);
+        this.syncCanonicalPlanningAttachmentLinks('initiative', existing.id, normalizedWorkspaceId, next.attachments || []);
+        const hydrated = this.getInitiativeForWriteResult(existing.id, normalizedWorkspaceId, next, 'updateInitiative:post-write');
+        if (options?.skipEntityEvents !== true) {
+            const changes = this.buildPlanningEntityEventChanges(existing, next, ['title', 'description', 'ownerId', 'attachments']);
+            if (Object.keys(changes).length > 0) {
+                this.addEntityEvent({
+                    entityType: 'initiative',
+                    entityId: existing.id,
+                    workspaceId: normalizedWorkspaceId,
+                    action: this.getPlanningEntityEventAction('initiative', changes),
+                    actor: options?.actorRef || 'system',
+                    createdAt: next.updatedAt,
+                    details: { changes }
+                });
+                return this.getInitiativeForWriteResult(existing.id, normalizedWorkspaceId, hydrated, 'updateInitiative:post-event');
+            }
+        }
+        return hydrated;
     }
-    archiveInitiative(id, workspaceId) {
+    archiveInitiative(id, workspaceId, options) {
         const existing = this.getInitiative(id, workspaceId);
         if (!existing) {
             throw new TaskforceRuleError(`Initiative not found: ${id}`, 404, 'INITIATIVE_NOT_FOUND');
         }
         if (existing.isArchived)
             return existing;
-        return this.updateInitiative(id, { isArchived: true }, workspaceId);
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const archived = this.updateInitiative(id, { isArchived: true }, workspaceId, { ...options, skipEntityEvents: true });
+        if (options?.skipEntityEvents !== true) {
+            this.addEntityEvent({
+                entityType: 'initiative',
+                entityId: id,
+                workspaceId: normalizedWorkspaceId,
+                action: 'initiative-archived',
+                actor: options?.actorRef || 'system',
+                createdAt: archived.updatedAt || new Date().toISOString(),
+            });
+            return this.getInitiativeForWriteResult(id, normalizedWorkspaceId, archived, 'archiveInitiative:post-event');
+        }
+        return archived;
     }
-    unarchiveInitiative(id, workspaceId) {
+    unarchiveInitiative(id, workspaceId, options) {
         const existing = this.getInitiative(id, workspaceId);
         if (!existing) {
             throw new TaskforceRuleError(`Initiative not found: ${id}`, 404, 'INITIATIVE_NOT_FOUND');
         }
         if (!existing.isArchived)
             return existing;
-        return this.updateInitiative(id, { isArchived: false }, workspaceId);
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const restored = this.updateInitiative(id, { isArchived: false }, workspaceId, { ...options, skipEntityEvents: true });
+        if (options?.skipEntityEvents !== true) {
+            this.addEntityEvent({
+                entityType: 'initiative',
+                entityId: id,
+                workspaceId: normalizedWorkspaceId,
+                action: 'initiative-unarchived',
+                actor: options?.actorRef || 'system',
+                createdAt: restored.updatedAt || new Date().toISOString(),
+            });
+            return this.getInitiativeForWriteResult(id, normalizedWorkspaceId, restored, 'unarchiveInitiative:post-event');
+        }
+        return restored;
     }
     getWorkstream(id, workspaceId) {
         const normalizedId = String(id || '').trim();
@@ -3197,7 +3692,7 @@ export class TaskforceCore {
         `).get(this.tenantId, normalizedWorkspaceId, normalizedId);
         if (!row)
             return null;
-        return this.rowToWorkstream(row);
+        return this.rowToWorkstream(row, { includeActivity: true });
     }
     listWorkstreams(workspaceId) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
@@ -3266,7 +3761,7 @@ export class TaskforceCore {
             workstreamTaskSummaries: Array.from(workstreamTaskSummaries.values()),
         };
     }
-    createWorkstream(input, workspaceId) {
+    createWorkstream(input, workspaceId, options) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         const id = String(input.id || '').trim() || this.generateEntityId('workstream');
         const referenceNumber = this.reserveWorkstreamReferenceNumber(normalizedWorkspaceId, input.referenceNumber);
@@ -3309,14 +3804,33 @@ export class TaskforceCore {
             sortOrder: workstream.order,
             isArchived: workstream.isArchived ? 1 : 0,
         });
-        return workstream;
+        this.syncCanonicalPlanningAttachmentLinks('workstream', workstream.id, normalizedWorkspaceId, workstream.attachments || []);
+        if (options?.skipEntityEvents !== true) {
+            this.addEntityEvent({
+                entityType: 'workstream',
+                entityId: workstream.id,
+                workspaceId: normalizedWorkspaceId,
+                action: 'workstream-created',
+                actor: options?.actorRef || 'system',
+                createdAt: workstream.updatedAt || workstream.createdAt,
+                details: {
+                    title: workstream.title,
+                    ownerId: workstream.ownerId || null,
+                    initiativeId: workstream.initiativeId || null,
+                }
+            });
+        }
+        return this.getWorkstreamForWriteResult(workstream.id, normalizedWorkspaceId, workstream, 'createWorkstream:post-write');
     }
-    updateWorkstream(id, patch, workspaceId) {
+    updateWorkstream(id, patch, workspaceId, options) {
         const existing = this.getWorkstream(id, workspaceId);
         if (!existing) {
             throw new TaskforceRuleError(`Workstream not found: ${id}`, 404, 'WORKSTREAM_NOT_FOUND');
         }
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const nextAttachments = Object.prototype.hasOwnProperty.call(patch, 'attachments') && Array.isArray(patch.attachments)
+            ? patch.attachments
+            : existing.attachments;
         const next = {
             ...existing,
             ...patch,
@@ -3324,6 +3838,7 @@ export class TaskforceCore {
             initiativeId: Object.prototype.hasOwnProperty.call(patch, 'initiativeId')
                 ? this.sanitizeInitiativeId(patch.initiativeId)
                 : existing.initiativeId,
+            attachments: nextAttachments,
             updatedAt: String(patch.updatedAt || '').trim() || new Date().toISOString(),
             referenceLabel: formatWorkstreamReference(patch.referenceNumber ?? existing.referenceNumber),
         };
@@ -3356,41 +3871,94 @@ export class TaskforceCore {
             sortOrder: next.order,
             isArchived: next.isArchived ? 1 : 0,
         });
-        return this.getWorkstream(existing.id, normalizedWorkspaceId);
+        this.syncCanonicalPlanningAttachmentLinks('workstream', existing.id, normalizedWorkspaceId, next.attachments || []);
+        const hydrated = this.getWorkstreamForWriteResult(existing.id, normalizedWorkspaceId, next, 'updateWorkstream:post-write');
+        if (options?.skipEntityEvents !== true) {
+            const changes = this.buildPlanningEntityEventChanges(existing, next, ['title', 'description', 'ownerId', 'initiativeId', 'attachments']);
+            if (Object.keys(changes).length > 0) {
+                this.addEntityEvent({
+                    entityType: 'workstream',
+                    entityId: existing.id,
+                    workspaceId: normalizedWorkspaceId,
+                    action: this.getPlanningEntityEventAction('workstream', changes),
+                    actor: options?.actorRef || 'system',
+                    createdAt: next.updatedAt,
+                    details: { changes }
+                });
+                return this.getWorkstreamForWriteResult(existing.id, normalizedWorkspaceId, hydrated, 'updateWorkstream:post-event');
+            }
+        }
+        return hydrated;
     }
-    archiveWorkstream(id, workspaceId) {
+    archiveWorkstream(id, workspaceId, options) {
         const existing = this.getWorkstream(id, workspaceId);
         if (!existing) {
             throw new TaskforceRuleError(`Workstream not found: ${id}`, 404, 'WORKSTREAM_NOT_FOUND');
         }
         if (existing.isArchived)
             return existing;
-        return this.updateWorkstream(id, { isArchived: true }, workspaceId);
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const archived = this.updateWorkstream(id, { isArchived: true }, workspaceId, { ...options, skipEntityEvents: true });
+        if (options?.skipEntityEvents !== true) {
+            this.addEntityEvent({
+                entityType: 'workstream',
+                entityId: id,
+                workspaceId: normalizedWorkspaceId,
+                action: 'workstream-archived',
+                actor: options?.actorRef || 'system',
+                createdAt: archived.updatedAt || new Date().toISOString(),
+            });
+            return this.getWorkstreamForWriteResult(id, normalizedWorkspaceId, archived, 'archiveWorkstream:post-event');
+        }
+        return archived;
     }
-    unarchiveWorkstream(id, workspaceId) {
+    unarchiveWorkstream(id, workspaceId, options) {
         const existing = this.getWorkstream(id, workspaceId);
         if (!existing) {
             throw new TaskforceRuleError(`Workstream not found: ${id}`, 404, 'WORKSTREAM_NOT_FOUND');
         }
         if (!existing.isArchived)
             return existing;
-        return this.updateWorkstream(id, { isArchived: false }, workspaceId);
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
+        const restored = this.updateWorkstream(id, { isArchived: false }, workspaceId, { ...options, skipEntityEvents: true });
+        if (options?.skipEntityEvents !== true) {
+            this.addEntityEvent({
+                entityType: 'workstream',
+                entityId: id,
+                workspaceId: normalizedWorkspaceId,
+                action: 'workstream-unarchived',
+                actor: options?.actorRef || 'system',
+                createdAt: restored.updatedAt || new Date().toISOString(),
+            });
+            return this.getWorkstreamForWriteResult(id, normalizedWorkspaceId, restored, 'unarchiveWorkstream:post-event');
+        }
+        return restored;
     }
     upsertInitiativeForSync(initiative, workspaceId) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         const existing = this.getInitiative(initiative.id, normalizedWorkspaceId);
         if (existing) {
-            return this.updateInitiative(existing.id, initiative, normalizedWorkspaceId);
+            const existingUpdatedAtMs = Date.parse(String(existing.updatedAt || existing.createdAt || '').trim());
+            const incomingUpdatedAtMs = Date.parse(String(initiative.updatedAt || initiative.createdAt || '').trim());
+            if (Number.isFinite(existingUpdatedAtMs) && Number.isFinite(incomingUpdatedAtMs) && incomingUpdatedAtMs < existingUpdatedAtMs) {
+                return existing;
+            }
+            return this.updateInitiative(existing.id, initiative, normalizedWorkspaceId, { skipEntityEvents: true });
         }
-        return this.createInitiative(initiative, normalizedWorkspaceId);
+        return this.createInitiative(initiative, normalizedWorkspaceId, { skipEntityEvents: true });
     }
     upsertWorkstreamForSync(workstream, workspaceId) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         const existing = this.getWorkstream(workstream.id, normalizedWorkspaceId);
         if (existing) {
-            return this.updateWorkstream(existing.id, workstream, normalizedWorkspaceId);
+            const existingUpdatedAtMs = Date.parse(String(existing.updatedAt || existing.createdAt || '').trim());
+            const incomingUpdatedAtMs = Date.parse(String(workstream.updatedAt || workstream.createdAt || '').trim());
+            if (Number.isFinite(existingUpdatedAtMs) && Number.isFinite(incomingUpdatedAtMs) && incomingUpdatedAtMs < existingUpdatedAtMs) {
+                return existing;
+            }
+            return this.updateWorkstream(existing.id, workstream, normalizedWorkspaceId, { skipEntityEvents: true });
         }
-        return this.createWorkstream(workstream, normalizedWorkspaceId);
+        return this.createWorkstream(workstream, normalizedWorkspaceId, { skipEntityEvents: true });
     }
     listChecklistItems(taskId, workspaceId) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
@@ -4542,6 +5110,91 @@ export class TaskforceCore {
         `).run(now, now, this.tenantId, normalizedUserId, cutoff);
         return staleDrafts;
     }
+    createTaskAttachmentUploadDraft(input) {
+        const draftId = String(input.draftId || '').trim();
+        const workspaceId = String(input.workspaceId || '').trim();
+        const taskId = String(input.taskId || '').trim();
+        const actorRef = String(input.actorRef || '').trim() || 'system';
+        const storageKey = String(input.storageKey || '').trim();
+        const mimeType = String(input.mimeType || 'application/octet-stream').trim() || 'application/octet-stream';
+        const originalFilename = String(input.originalFilename || '').trim() || 'attachment';
+        const sizeBytes = Number.isFinite(Number(input.sizeBytes)) ? Math.max(0, Math.floor(Number(input.sizeBytes))) : 0;
+        const storageProvider = input.storageProvider === 'r2' || input.storageProvider === 'external' ? input.storageProvider : 'local';
+        if (!draftId)
+            throw new TaskforceRuleError('draftId is required', 400, 'TASK_ATTACHMENT_DRAFT_ID_REQUIRED');
+        if (!workspaceId)
+            throw new TaskforceRuleError('workspaceId is required', 400, 'WORKSPACE_ID_REQUIRED');
+        if (!taskId)
+            throw new TaskforceRuleError('taskId is required', 400, 'TASK_ID_REQUIRED');
+        if (!storageKey)
+            throw new TaskforceRuleError('storageKey is required', 400, 'TASK_ATTACHMENT_STORAGE_KEY_REQUIRED');
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            INSERT INTO task_attachment_upload_drafts (
+                draft_id, tenant_id, workspace_id, task_id, actor_ref, storage_key, mime_type, original_filename,
+                size_bytes, storage_provider, consumed_at, discarded_at, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?)
+        `).run(draftId, this.tenantId, workspaceId, taskId, actorRef, storageKey, mimeType, originalFilename, sizeBytes, storageProvider, now, now);
+        return this.getTaskAttachmentUploadDraft(draftId);
+    }
+    getTaskAttachmentUploadDraft(draftId) {
+        const normalizedDraftId = String(draftId || '').trim();
+        if (!normalizedDraftId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT draft_id, workspace_id, task_id, actor_ref, storage_key, mime_type, original_filename,
+                   size_bytes, storage_provider, consumed_at, discarded_at, created_at, updated_at
+            FROM task_attachment_upload_drafts
+            WHERE tenant_id = ? AND draft_id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedDraftId);
+        if (!row?.draft_id)
+            return null;
+        return {
+            draftId: String(row.draft_id),
+            workspaceId: String(row.workspace_id || ''),
+            taskId: String(row.task_id || ''),
+            actorRef: String(row.actor_ref || 'system'),
+            storageKey: String(row.storage_key || ''),
+            mimeType: String(row.mime_type || 'application/octet-stream'),
+            originalFilename: String(row.original_filename || 'attachment'),
+            sizeBytes: Number(row.size_bytes || 0),
+            storageProvider: String(row.storage_provider || 'local') === 'r2'
+                ? 'r2'
+                : String(row.storage_provider || 'local') === 'external'
+                    ? 'external'
+                    : 'local',
+            consumedAt: row.consumed_at ? String(row.consumed_at) : null,
+            discardedAt: row.discarded_at ? String(row.discarded_at) : null,
+            createdAt: String(row.created_at || ''),
+            updatedAt: String(row.updated_at || ''),
+        };
+    }
+    markTaskAttachmentUploadDraftConsumed(draftId) {
+        const existing = this.getTaskAttachmentUploadDraft(draftId);
+        if (!existing || existing.discardedAt)
+            return null;
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE task_attachment_upload_drafts
+            SET consumed_at = COALESCE(consumed_at, ?), updated_at = ?
+            WHERE tenant_id = ? AND draft_id = ? AND discarded_at IS NULL
+        `).run(now, now, this.tenantId, existing.draftId);
+        return this.getTaskAttachmentUploadDraft(existing.draftId);
+    }
+    discardTaskAttachmentUploadDraft(draftId) {
+        const existing = this.getTaskAttachmentUploadDraft(draftId);
+        if (!existing || existing.discardedAt)
+            return existing;
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE task_attachment_upload_drafts
+            SET discarded_at = ?, updated_at = ?
+            WHERE tenant_id = ? AND draft_id = ? AND discarded_at IS NULL
+        `).run(now, now, this.tenantId, existing.draftId);
+        return this.getTaskAttachmentUploadDraft(existing.draftId);
+    }
     getSystemRole(userId) {
         const normalizedUserId = String(userId || '').trim();
         if (!normalizedUserId || normalizedUserId === 'anonymous')
@@ -5106,6 +5759,9 @@ export class TaskforceCore {
     updateAiProfileAvatar(input) {
         return updateAiProfileAvatarService(this.getAiProfileServiceDeps(), input);
     }
+    updateAiProfileSurfaceType(input) {
+        return updateAiProfileSurfaceTypeService(this.getAiProfileServiceDeps(), input);
+    }
     resolveAiProfile(input, options) {
         return resolveAiProfileService(this.getAiProfileServiceDeps(), input, options);
     }
@@ -5246,6 +5902,9 @@ export class TaskforceCore {
     upsertTaskEventForSync(event) {
         return upsertTaskEventForSyncService(this.getTaskActivityServiceDeps(), event);
     }
+    upsertEntityEventForSync(event) {
+        return upsertEntityEventForSyncService(this.getTaskActivityServiceDeps(), event);
+    }
     deleteDocumentReviewSessionForSync(input) {
         const deps = this.getDocumentReviewServiceDeps();
         return deps.sessionStore.softDelete(input.sessionId, deps.normalizeWorkspaceId(input.workspaceId), input.deletedAt || undefined);
@@ -5313,38 +5972,9 @@ export class TaskforceCore {
         if (aiProfile) {
             return this.aiProfileToActor(this.aiProfileRowToRecord(aiProfile));
         }
-        // Name-based fallback: agents may use their display name instead of profile ID
-        const aiProfileByName = this.db.prepare(`
-            SELECT *
-            FROM ai_profiles
-            WHERE tenant_id = ?
-              AND workspace_id = ?
-              AND archived_at IS NULL
-              AND (
-                  LOWER(name) = LOWER(?)
-                  OR LOWER(username) = LOWER(?)
-              )
-            ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
-            LIMIT 1
-        `).get(this.tenantId, normalizedWorkspaceId, raw, raw);
-        if (aiProfileByName) {
-            return this.aiProfileToActor(this.aiProfileRowToRecord(aiProfileByName));
-        }
-        const archivedAiProfileByName = this.db.prepare(`
-            SELECT *
-            FROM ai_profiles
-            WHERE tenant_id = ?
-              AND workspace_id = ?
-              AND archived_at IS NOT NULL
-              AND (
-                  LOWER(name) = LOWER(?)
-                  OR LOWER(username) = LOWER(?)
-              )
-            ORDER BY COALESCE(last_active_at, updated_at, created_at) DESC, id ASC
-            LIMIT 1
-        `).get(this.tenantId, normalizedWorkspaceId, raw, raw);
-        if (archivedAiProfileByName) {
-            return this.aiProfileToActor(this.aiProfileRowToRecord(archivedAiProfileByName));
+        const uniqueAiProfileByAlias = this.resolveUniqueAiProfileActorByAlias(normalizedWorkspaceId, raw);
+        if (uniqueAiProfileByAlias) {
+            return uniqueAiProfileByAlias;
         }
         const workspaceUser = this.listWorkspaceUsers(normalizedWorkspaceId).find((user) => user.userId === raw);
         if (workspaceUser) {
@@ -6157,6 +6787,9 @@ export class TaskforceCore {
     revokeMcpAccessToken(input) {
         return this.mcpTokenService.revokeMcpAccessToken(input);
     }
+    deleteMcpAccessToken(input) {
+        return this.mcpTokenService.deleteMcpAccessToken(input);
+    }
     regenerateMcpAccessToken(input) {
         return this.mcpTokenService.regenerateMcpAccessToken(input);
     }
@@ -6190,6 +6823,9 @@ export class TaskforceCore {
     authenticateMcpOAuthAccessToken(token, workspaceId) {
         return this.mcpTokenService.authenticateMcpOAuthAccessToken(token, workspaceId);
     }
+    bindMcpOAuthConnectorGrantAiProfile(input) {
+        return this.mcpTokenService.bindMcpOAuthConnectorGrantAiProfile(input);
+    }
     recordMcpOAuthConnectorGrantUsage(input) {
         return this.mcpTokenService.recordMcpOAuthConnectorGrantUsage(input);
     }
@@ -6600,9 +7236,47 @@ export class TaskforceCore {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
         return this.listTaskEventsInternal(taskId, normalizedWorkspaceId);
     }
+    taskExistsForSync(id, workspaceId) {
+        return this.taskExists(id, this.normalizeWorkspaceId(workspaceId || undefined));
+    }
+    initiativeExistsForSync(id, workspaceId) {
+        return this.initiativeExists(id, this.normalizeWorkspaceId(workspaceId || undefined));
+    }
+    workstreamExistsForSync(id, workspaceId) {
+        return this.workstreamExists(id, this.normalizeWorkspaceId(workspaceId || undefined));
+    }
+    recordTaskEvent(input) {
+        this.addTaskEvent({
+            taskId: input.taskId,
+            workspaceId: this.normalizeWorkspaceId(input.workspaceId || undefined),
+            action: input.action,
+            actor: input.actor || 'system',
+            createdAt: input.createdAt,
+            details: input.details,
+        });
+    }
     listTaskEventsForSync(input) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(input.workspaceId || undefined);
-        return listWorkspaceTaskEventsService(this.getTaskActivityServiceDeps(), normalizedWorkspaceId);
+        return listWorkspaceTaskEventsForSyncService(this.getTaskActivityServiceDeps(), normalizedWorkspaceId);
+    }
+    getTaskEventForSync(input) {
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(input.workspaceId || undefined);
+        return getTaskEventForSyncService(this.getTaskActivityServiceDeps(), {
+            workspaceId: normalizedWorkspaceId,
+            taskId: input.taskId,
+            eventId: input.eventId,
+        });
+    }
+    listEntityEventsForSync(input) {
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(input.workspaceId || undefined);
+        return listWorkspaceEntityEventsForSyncService(this.getTaskActivityServiceDeps(), normalizedWorkspaceId);
+    }
+    getEntityEventForSync(input) {
+        const normalizedWorkspaceId = this.normalizeWorkspaceId(input.workspaceId || undefined);
+        return getEntityEventForSyncService(this.getTaskActivityServiceDeps(), {
+            workspaceId: normalizedWorkspaceId,
+            eventId: input.eventId,
+        });
     }
     getScheduleBoard(weekKey, showWeekends = false, workspaceId) {
         const parsedWeek = this.parseIsoWeekKeyToDates(weekKey);
@@ -6866,6 +7540,16 @@ export class TaskforceCore {
                     workstreamId: task.workstreamId || null
                 }
             });
+            if (task.workstreamId) {
+                this.addWorkstreamTaskMembershipEvents({
+                    task,
+                    workspaceId: normalizedWorkspaceId,
+                    actor: options?.actorRef || createdBy || 'system',
+                    createdAt: task.updatedAt || task.createdAt,
+                    previousWorkstreamId: null,
+                    nextWorkstreamId: task.workstreamId,
+                });
+            }
         }
         if (persistBackup) {
             this.persistBackup();
@@ -7187,6 +7871,16 @@ export class TaskforceCore {
                         createdAt: nextTask.updatedAt,
                         details: { changes }
                     });
+                    if (changes.workstreamId) {
+                        this.addWorkstreamTaskMembershipEvents({
+                            task: nextTask,
+                            workspaceId: normalizedWorkspaceId,
+                            actor: options?.actorRef || 'system',
+                            createdAt: nextTask.updatedAt,
+                            previousWorkstreamId: existing.workstreamId || null,
+                            nextWorkstreamId: nextTask.workstreamId || null,
+                        });
+                    }
                 }
             }
             return this.getTask(taskId, normalizedWorkspaceId);
@@ -7206,7 +7900,11 @@ export class TaskforceCore {
     }
     addComment(id, text, author, workspaceId, options) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
-        const existing = this.db.prepare('SELECT id FROM tasks WHERE tenant_id = ? AND workspace_id = ? AND id = ?').get(this.tenantId, normalizedWorkspaceId, id);
+        const existing = this.db.prepare(`
+            SELECT id, updated_at, created_at
+            FROM tasks
+            WHERE tenant_id = ? AND workspace_id = ? AND id = ?
+        `).get(this.tenantId, normalizedWorkspaceId, id);
         if (!existing)
             return null;
         const submittedAuthor = String(author || '').trim() || 'user';
@@ -7231,7 +7929,13 @@ export class TaskforceCore {
             submitted_author: comment.submittedAuthor,
             timestamp: comment.timestamp
         });
-        this.db.prepare('UPDATE tasks SET updated_at = ? WHERE tenant_id = ? AND workspace_id = ? AND id = ?').run(comment.timestamp, this.tenantId, normalizedWorkspaceId, id);
+        const existingWatermark = String(existing.updated_at || existing.created_at || '').trim();
+        const existingWatermarkMs = Date.parse(existingWatermark);
+        const commentTimestampMs = Date.parse(comment.timestamp);
+        const nextTaskUpdatedAt = Number.isFinite(existingWatermarkMs) && existingWatermarkMs >= commentTimestampMs
+            ? new Date(existingWatermarkMs + 1).toISOString()
+            : comment.timestamp;
+        this.db.prepare('UPDATE tasks SET updated_at = ? WHERE tenant_id = ? AND workspace_id = ? AND id = ?').run(nextTaskUpdatedAt, this.tenantId, normalizedWorkspaceId, id);
         if (options?.skipTaskEvents !== true) {
             this.addTaskEvent({
                 taskId: id,