@taskforcehq/taskforce 0.3.300 → 0.3.302

package/dist/server/routes/auth.js

@@ -21,6 +21,7 @@
  *   POST /api/taskforce/auth/logout
  *   GET  /api/taskforce/account/access-status
  *   GET  /api/taskforce/account/entitlements
+ *   GET  /api/taskforce/account/team-management-access
  *   GET  /api/taskforce/account/plan-preview
  *   GET  /api/taskforce/auth/workspace-members
  *   GET  /api/taskforce/workspace/assignee-options
@@ -33,15 +34,45 @@
  *   DELETE /api/taskforce/admin/users/:id
  *   GET  /api/taskforce/admin/workspace-audit-logs
  */
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
 import { parseJsonBody } from '../routes.js';
 import { hasValidSession, createClearSessionCookie, createSessionTokenCookie, resolveRequestAccess, resolveSessionCookieAttributesForRequest, } from '../auth.js';
 import { resolveEffectiveEmailConfig, sendEmail } from '../email.js';
 import { resolveDeploymentConfig } from '../../config/deployment.js';
 import { resolveRuntimeModeContract } from '../../shared/runtimeContract.js';
-import { resolveErrorStatusCode } from './shared.js';
+import { requestHeader, resolveErrorStatusCode } from './shared.js';
+import { normalizeTaskDataRelativePath } from '../../storage/objectStorageClient.js';
 // === SECTION: Registration ===
 export function registerAuthRoutes(deps) {
-    const { addRoute, core, context, requestWorkspaceId, requestUserId, ensureAppAccess, ensureAuthenticatedUser, ensureWorkspaceAdminRole, ensureCloudPlanData, requireCloudRuntime, auditAuthAction, resolveAdminRequestActor, shouldExposeDevAuthTokens, resolveRuntimeConfigBaseUrl, resolvePublicAuthBaseUrl, } = deps;
+    const { addRoute, core, context, requestWorkspaceId, requestUserId, ensureAppAccess, ensureAuthenticatedUser, ensureWorkspaceAdminRole, ensureCloudPlanData, requireCloudRuntime, auditAuthAction, resolveAdminRequestActor, shouldExposeDevAuthTokens, resolveRuntimeConfigBaseUrl, resolvePublicAuthBaseUrl, resolveEffectiveObjectStorageConfig, getObjectStorageClient, } = deps;
+    const normalizeTeamWorkspaceRole = (value) => {
+        const role = String(value || '').trim().toLowerCase();
+        if (role === 'owner' || role === 'admin' || role === 'member' || role === 'read-only')
+            return role;
+        return null;
+    };
+    const resolveBooleanSetting = (value, fallback) => {
+        if (typeof value === 'boolean')
+            return value;
+        if (typeof value === 'number')
+            return value !== 0;
+        const normalized = String(value || '').trim().toLowerCase();
+        if (!normalized)
+            return fallback;
+        if (['1', 'true', 'yes', 'on'].includes(normalized))
+            return true;
+        if (['0', 'false', 'no', 'off'].includes(normalized))
+            return false;
+        return fallback;
+    };
+    const resolveTeamPlanModeFromEntitlements = (payload) => {
+        const state = String(payload?.state || '').trim().toLowerCase();
+        const teamAllowed = payload?.features?.['collaboration.team_management']?.allowed === true;
+        const stateAllows = state === 'active' || state === 'trialing' || state === 'grace';
+        return teamAllowed && stateAllows ? 'team' : 'personal';
+    };
     // === SECTION: Email delivery helpers ===
     const getEmailConfig = () => {
         if (context.authConfig?.runtimeMode !== 'cloud') {
@@ -57,10 +88,10 @@ export function registerAuthRoutes(deps) {
         const authRateLimitWindowMsRaw = Number(authSettings.authRateLimitWindowMs);
         const signupSettings = core.getSignupMonetizationSettings();
         return {
-            allowSelfRegistration: authSettings.allowSelfRegistration !== false,
-            requireVerifiedEmail: authSettings.requireVerifiedEmail !== false,
-            defaultNewUserBetaAccess: authSettings.defaultNewUserBetaAccess === true,
-            authRateLimitEnabled: authSettings.authRateLimitEnabled !== false,
+            allowSelfRegistration: resolveBooleanSetting(authSettings.allowSelfRegistration, true),
+            requireVerifiedEmail: resolveBooleanSetting(authSettings.requireVerifiedEmail, true),
+            defaultNewUserBetaAccess: resolveBooleanSetting(authSettings.defaultNewUserBetaAccess, false),
+            authRateLimitEnabled: resolveBooleanSetting(authSettings.authRateLimitEnabled, true),
             authRateLimitMaxRequests: Number.isFinite(authRateLimitMaxRequestsRaw) && authRateLimitMaxRequestsRaw >= 1
                 ? Math.floor(authRateLimitMaxRequestsRaw)
                 : 10,
@@ -75,10 +106,57 @@ export function registerAuthRoutes(deps) {
         const globalSettings = core.getGlobalSettings();
         const siteSettings = globalSettings.site || {};
         return {
-            showRunTaskforceLocally: siteSettings.showRunTaskforceLocally !== false,
-            pricingPageEnabled: siteSettings.pricingPageEnabled !== false
+            showRunTaskforceLocally: resolveBooleanSetting(siteSettings.showRunTaskforceLocally, true),
+            pricingPageEnabled: resolveBooleanSetting(siteSettings.pricingPageEnabled, true)
         };
     };
+    const AVATAR_DRAFT_RETENTION_MS = 24 * 60 * 60 * 1000;
+    const MAX_AVATAR_UPLOAD_BYTES = 5 * 1024 * 1024;
+    const AVATAR_MIME_EXTENSION = {
+        'image/png': '.png',
+        'image/jpeg': '.jpg',
+        'image/webp': '.webp',
+        'image/gif': '.gif'
+    };
+    const buildUserAvatarStoragePath = (userIdRaw, draftIdRaw, originalNameRaw, mimeTypeRaw) => {
+        const userId = String(userIdRaw || '').trim().replace(/[^a-zA-Z0-9._-]/g, '-') || 'user';
+        const draftId = String(draftIdRaw || '').trim().replace(/[^a-zA-Z0-9._-]/g, '-') || randomUUID().replace(/-/g, '');
+        const originalName = String(originalNameRaw || '').trim();
+        const mimeType = String(mimeTypeRaw || '').trim().toLowerCase();
+        const originalExt = originalName ? path.extname(originalName).toLowerCase() : '';
+        const ext = originalExt || AVATAR_MIME_EXTENSION[mimeType] || '.bin';
+        const stem = (originalName ? path.basename(originalName, originalExt) : 'avatar')
+            .replace(/[^a-zA-Z0-9._-]/g, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-+|-+$/g, '')
+            .slice(0, 64) || 'avatar';
+        return `users/${userId}/profile/avatar/${draftId}-${stem}${ext}`;
+    };
+    const deleteStoredAvatarObject = async (relativePathRaw) => {
+        const relativePath = normalizeTaskDataRelativePath(String(relativePathRaw || '').trim());
+        if (!relativePath)
+            return;
+        const objectStorageClient = getObjectStorageClient();
+        const effectiveObjectStorage = resolveEffectiveObjectStorageConfig();
+        if (objectStorageClient && effectiveObjectStorage.provider === 'r2') {
+            await objectStorageClient.deleteObject(relativePath).catch(() => { });
+            return;
+        }
+        const { basePath } = core.getPaths();
+        const resolvedPath = path.resolve(basePath, relativePath);
+        if (!resolvedPath.startsWith(path.resolve(basePath)))
+            return;
+        if (fs.existsSync(resolvedPath)) {
+            fs.rmSync(resolvedPath, { force: true });
+        }
+    };
+    const cleanupStaleAvatarDrafts = async (userId) => {
+        const cutoff = new Date(Date.now() - AVATAR_DRAFT_RETENTION_MS).toISOString();
+        const staleDrafts = core.cleanupStaleUserAvatarUploadDrafts(userId, cutoff);
+        for (const draft of staleDrafts) {
+            await deleteStoredAvatarObject(draft.storageKey);
+        }
+    };
     const logAuthLink = (kind, email, token, req) => {
         const base = resolvePublicAuthBaseUrl(req);
         const urlPath = kind === 'verify-email'
@@ -187,8 +265,10 @@ export function registerAuthRoutes(deps) {
         let userId = access?.userId || 'anonymous';
         let email = null;
         let displayName = null;
+        let avatarUrl = null;
         let betaAccess = true;
         if (authenticated && access?.userId) {
+            await cleanupStaleAvatarDrafts(access.userId);
             betaAccess = core.getUserBetaAccess(access.userId);
             const resolved = core.resolveUserAccess(access.userId, workspaceId, role);
             if (resolved) {
@@ -204,6 +284,7 @@ export function registerAuthRoutes(deps) {
             const identity = core.resolveUserIdentity(userId);
             email = identity?.email || null;
             displayName = identity?.displayName || null;
+            avatarUrl = identity?.avatarUrl || null;
         }
         res.writeHead(200, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({
@@ -213,6 +294,7 @@ export function registerAuthRoutes(deps) {
             role,
             email,
             displayName,
+            avatarUrl,
             betaAccess
         }));
     });
@@ -229,28 +311,67 @@ export function registerAuthRoutes(deps) {
     addRoute('POST', '/api/taskforce/auth/profile', async (req, res) => {
         if (!requireCloudRuntime(res, 'Authentication'))
             return;
-        if (!ensureAuthenticatedUser(req)) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+        const authConfig = context.authConfig;
+        if (!authConfig) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth context unavailable.' }));
             return;
         }
-        const userId = String(requestUserId(req) || '').trim();
-        if (!userId || userId === 'anonymous') {
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = String(access.userId || '').trim();
+        if (!access.authenticated || !userId || userId === 'anonymous') {
             res.writeHead(401, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
             return;
         }
         const body = await parseJsonBody(req);
         try {
-            const updated = core.updateUserDisplayName(userId, String(body?.displayName || ''));
+            await cleanupStaleAvatarDrafts(userId);
+            const avatarDraftId = typeof body?.avatarDraftId === 'string' ? body.avatarDraftId.trim() : '';
+            const clearAvatar = body?.clearAvatar === true;
+            let avatarUrl;
+            if (avatarDraftId) {
+                const draft = core.getUserAvatarUploadDraft(userId, avatarDraftId);
+                if (!draft || draft.discardedAt || !draft.finalizedAt) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ success: false, error: 'Avatar draft is invalid or expired.', code: 'AVATAR_DRAFT_INVALID' }));
+                    return;
+                }
+                avatarUrl = `/api/taskforce/context/${encodeURIComponent(draft.storageKey)}`;
+            }
+            else if (clearAvatar) {
+                avatarUrl = null;
+            }
+            const previousIdentity = core.resolveUserIdentity(userId);
+            const updated = core.updateUserProfile(userId, {
+                displayName: String(body?.displayName || ''),
+                ...((avatarDraftId || clearAvatar) ? { avatarUrl: avatarUrl || null } : {})
+            });
             if (!updated) {
                 res.writeHead(404, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ success: false, error: 'User not found.', code: 'USER_NOT_FOUND' }));
                 return;
             }
+            if (avatarDraftId) {
+                core.markUserAvatarUploadDraftConsumed(userId, avatarDraftId);
+            }
+            if (avatarDraftId || clearAvatar) {
+                const previousAvatarUrl = String(previousIdentity?.avatarUrl || '').trim();
+                const nextAvatarUrl = String(updated.avatarUrl || '').trim();
+                const currentDraft = avatarDraftId ? core.getUserAvatarUploadDraft(userId, avatarDraftId) : null;
+                const currentStorageKey = String(currentDraft?.storageKey || '').trim();
+                if (previousAvatarUrl.startsWith('/api/taskforce/context/')
+                    && previousAvatarUrl !== nextAvatarUrl) {
+                    const previousStorageKey = normalizeTaskDataRelativePath(decodeURIComponent(previousAvatarUrl.slice('/api/taskforce/context/'.length)));
+                    if (previousStorageKey && previousStorageKey !== currentStorageKey) {
+                        await deleteStoredAvatarObject(previousStorageKey);
+                    }
+                }
+            }
             auditAuthAction(req, 'auth-profile-updated', {
                 userId,
-                displayName: updated.displayName || null
+                displayName: updated.displayName || null,
+                avatarUrl: updated.avatarUrl || null
             });
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({
@@ -258,7 +379,8 @@ export function registerAuthRoutes(deps) {
                 profile: {
                     userId: updated.userId,
                     email: updated.email,
-                    displayName: updated.displayName || null
+                    displayName: updated.displayName || null,
+                    avatarUrl: updated.avatarUrl || null
                 }
             }));
         }
@@ -268,6 +390,161 @@ export function registerAuthRoutes(deps) {
             res.end(JSON.stringify({ success: false, error: String(error?.message || 'Unable to update profile.'), code: error?.code }));
         }
     });
+    addRoute('POST', '/api/taskforce/auth/profile/avatar/init', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Authentication'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth context unavailable.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = String(access.userId || '').trim();
+        if (!access.authenticated || !userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const objectStorageClient = getObjectStorageClient();
+        const effectiveObjectStorage = resolveEffectiveObjectStorageConfig();
+        if (!objectStorageClient || effectiveObjectStorage.provider !== 'r2' || !effectiveObjectStorage.r2) {
+            res.writeHead(501, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Avatar uploads require object storage.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const originalName = String(body?.originalName || '').trim();
+        const mimeType = String(body?.mimeType || '').trim().toLowerCase();
+        const size = Number(body?.size || 0);
+        if (!originalName || !mimeType.startsWith('image/') || !(mimeType in AVATAR_MIME_EXTENSION)) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'A supported image file is required.', code: 'AVATAR_FILE_INVALID' }));
+            return;
+        }
+        if (!Number.isFinite(size) || size <= 0 || size > MAX_AVATAR_UPLOAD_BYTES) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Avatar must be 5 MB or smaller.', code: 'AVATAR_SIZE_INVALID' }));
+            return;
+        }
+        await cleanupStaleAvatarDrafts(userId);
+        const draftId = `avatar-draft-${randomUUID().replace(/-/g, '')}`;
+        const relativePath = buildUserAvatarStoragePath(userId, draftId, originalName, mimeType);
+        core.createUserAvatarUploadDraft({
+            userId,
+            draftId,
+            storageKey: relativePath,
+            mimeType,
+            originalFilename: originalName,
+            sizeBytes: size,
+            storageProvider: 'r2'
+        });
+        const uploadUrl = objectStorageClient.createSignedPutUrl(relativePath, effectiveObjectStorage.r2.signedUploadTtlSeconds, mimeType);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            mode: 'direct',
+            draftId,
+            uploadUrl,
+            method: 'PUT',
+            headers: { 'Content-Type': mimeType },
+            relativePath,
+            path: `/api/taskforce/context/${encodeURIComponent(relativePath)}`
+        }));
+    });
+    addRoute('POST', '/api/taskforce/auth/profile/avatar/finalize', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Authentication'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth context unavailable.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = String(access.userId || '').trim();
+        if (!access.authenticated || !userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const draftId = String(body?.draftId || '').trim();
+        const relativePath = normalizeTaskDataRelativePath(String(body?.relativePath || '').trim());
+        if (!draftId || !relativePath) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'draftId and relativePath are required.' }));
+            return;
+        }
+        await cleanupStaleAvatarDrafts(userId);
+        const draft = core.getUserAvatarUploadDraft(userId, draftId);
+        if (!draft || draft.discardedAt || draft.storageKey !== relativePath) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Avatar draft is invalid or expired.', code: 'AVATAR_DRAFT_INVALID' }));
+            return;
+        }
+        const objectStorageClient = getObjectStorageClient();
+        if (objectStorageClient) {
+            const uploaded = await objectStorageClient.getObject(relativePath);
+            if (!uploaded) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Uploaded avatar not found.', code: 'AVATAR_UPLOAD_MISSING' }));
+                return;
+            }
+        }
+        else {
+            const { basePath } = core.getPaths();
+            const resolvedPath = path.resolve(basePath, relativePath);
+            if (!resolvedPath.startsWith(path.resolve(basePath)) || !fs.existsSync(resolvedPath)) {
+                res.writeHead(404, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: false, error: 'Uploaded avatar not found.', code: 'AVATAR_UPLOAD_MISSING' }));
+                return;
+            }
+        }
+        const finalized = core.markUserAvatarUploadDraftFinalized(userId, draftId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+            success: true,
+            draftId,
+            avatarUrl: `/api/taskforce/context/${encodeURIComponent(relativePath)}`,
+            profile: finalized
+        }));
+    });
+    addRoute('POST', '/api/taskforce/auth/profile/avatar/discard', async (req, res) => {
+        if (!requireCloudRuntime(res, 'Authentication'))
+            return;
+        const authConfig = context.authConfig;
+        if (!authConfig) {
+            res.writeHead(500, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Auth context unavailable.' }));
+            return;
+        }
+        const access = resolveRequestAccess(req, authConfig);
+        const userId = String(access.userId || '').trim();
+        if (!access.authenticated || !userId || userId === 'anonymous') {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'Authentication required.' }));
+            return;
+        }
+        const body = await parseJsonBody(req);
+        const draftId = String(body?.draftId || '').trim();
+        if (!draftId) {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: false, error: 'draftId is required.' }));
+            return;
+        }
+        await cleanupStaleAvatarDrafts(userId);
+        const draft = core.getUserAvatarUploadDraft(userId, draftId);
+        if (!draft) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ success: true, discarded: false }));
+            return;
+        }
+        core.discardUserAvatarUploadDraft(userId, draftId);
+        await deleteStoredAvatarObject(draft.storageKey);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ success: true, discarded: true }));
+    });
     // === SECTION: Login and register ===
     // POST /api/taskforce/auth/login - Exchange email/password for secure session cookie
     addRoute('POST', '/api/taskforce/auth/login', async (req, res) => {
@@ -857,6 +1134,63 @@ export function registerAuthRoutes(deps) {
             res.end(JSON.stringify({ error: String(error?.message || 'Unable to resolve entitlements'), code: error?.code, details: error?.details }));
         }
     });
+    // GET /api/taskforce/account/team-management-access - Resolve authoritative team-management access for the active workspace.
+    addRoute('GET', '/api/taskforce/account/team-management-access', async (req, res) => {
+        if (!ensureAuthenticatedUser(req)) {
+            res.writeHead(401, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Authentication required.' }));
+            return;
+        }
+        const wid = requestWorkspaceId(req);
+        const userId = requestUserId(req);
+        const hintedRole = normalizeTeamWorkspaceRole(requestHeader(req, 'x-taskforce-workspace-role', ''));
+        const resolvedAccess = core.resolveUserAccess(userId, wid, 'member');
+        const role = normalizeTeamWorkspaceRole(resolvedAccess?.role || hintedRole || null);
+        const canManageWorkspace = role === 'owner' || role === 'admin';
+        if (!canManageWorkspace) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                workspaceId: wid,
+                role,
+                canManageWorkspace: false,
+                teamPlanMode: 'unknown',
+                allowed: false
+            }));
+            return;
+        }
+        try {
+            const entitlements = core.getAccountEntitlementsPayload({ userId, workspaceId: wid });
+            const teamPlanMode = resolveTeamPlanModeFromEntitlements(entitlements);
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                workspaceId: wid,
+                role,
+                canManageWorkspace: true,
+                teamPlanMode,
+                allowed: teamPlanMode === 'team'
+            }));
+        }
+        catch (error) {
+            if (error?.code === 'ENTITLEMENT_NOT_FOUND') {
+                const access = core.getAccountAccessStatus(userId);
+                const teamPlanMode = access.gate === 'plan_selection_required' ? 'personal' : 'unknown';
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    workspaceId: wid,
+                    role,
+                    canManageWorkspace: true,
+                    teamPlanMode,
+                    allowed: false,
+                    gate: access.gate,
+                    planSelectionRequired: access.planSelectionRequired
+                }));
+                return;
+            }
+            const statusCode = resolveErrorStatusCode(error, 400);
+            res.writeHead(statusCode, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: String(error?.message || 'Unable to resolve team management access'), code: error?.code, details: error?.details }));
+        }
+    });
     // GET /api/taskforce/account/plan-preview - Read-only payload for upgrade/support CTAs.
     addRoute('GET', '/api/taskforce/account/plan-preview', async (req, res) => {
         if (!ensureCloudPlanData(req, res))

package/dist/server/routes/billing.js

@@ -6,6 +6,7 @@ const BILLING_CONFIG_KEY_PLAN = 'billing.config.v1';
 const PRICE_METADATA_PLAN_VERSION = 'taskforce_plan_version_id';
 const BILLING_DIAGNOSTIC_RETENTION_DAYS = 30;
 const BILLING_DIAGNOSTIC_MAX_PAYLOAD_BYTES = 8 * 1024;
+const BILLING_STATUS_RECONCILIATION_TTL_MS = 30_000;
 const TASKFORCE_PROXY_ORIGIN_HOST_HEADER = 'x-taskforce-origin-host';
 const TASKFORCE_PROXY_ORIGIN_PROTO_HEADER = 'x-taskforce-origin-proto';
 const TASKFORCE_PROXY_ORIGIN_BASE_URL_HEADER = 'x-taskforce-origin-base-url';
@@ -623,12 +624,18 @@ function getBillingMirrorRow(core, userIdRaw) {
     const db = core.getDatabaseAdapter();
     const tenantId = core.getTenantId();
     return db.prepare(`
-        SELECT stripe_status, stripe_customer_id, stripe_subscription_id, stripe_price_id, billing_interval, trial_end, current_period_end, effective_until, entitlement_state, tier
+        SELECT stripe_status, stripe_customer_id, stripe_subscription_id, stripe_price_id, billing_interval, trial_end, current_period_end, effective_until, entitlement_state, tier, updated_at
         FROM user_billing
         WHERE tenant_id = ? AND user_id = ?
         LIMIT 1
     `).get(tenantId, userId);
 }
+function isBillingMirrorFresh(row) {
+    const updatedAt = Date.parse(String(row?.updated_at || ''));
+    if (!Number.isFinite(updatedAt))
+        return false;
+    return (Date.now() - updatedAt) < BILLING_STATUS_RECONCILIATION_TTL_MS;
+}
 function isStripeManagedSubscriptionStatus(statusRaw) {
     const status = String(statusRaw || '').trim().toLowerCase();
     return status === 'trialing'
@@ -708,6 +715,9 @@ async function reconcileBillingMirrorIfNeeded(core, userIdRaw) {
     if (!userId)
         return { row: null, conflictCode: null };
     let row = getBillingMirrorRow(core, userId);
+    if (isBillingMirrorFresh(row)) {
+        return { row, conflictCode: null };
+    }
     if (String(row?.stripe_subscription_id || '').trim()) {
         try {
             await reconcileBillingFromStripe(core, userId, row?.stripe_subscription_id);

package/dist/server/routes/billing.test.js

@@ -1435,6 +1435,7 @@ describe('Billing Webhook Routes', () => {
     });
     it('reconciles stale entitlement from Stripe when billing status is requested', async () => {
         const now = new Date().toISOString();
+        const stale = new Date(Date.now() - 60_000).toISOString();
         db.prepare(`
             INSERT INTO plan_catalog (plan_id, tenant_id, display_name, status, created_at, updated_at)
             VALUES ('pro', 'default', 'Pro Plan', 'active', ?, ?)
@@ -1451,12 +1452,12 @@ describe('Billing Webhook Routes', () => {
             INSERT INTO user_billing (
                 user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
             ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_old', 'active', 'starter', 'month', 'active', ?, ?)
-        `).run(now, now);
+        `).run(stale, stale);
         db.prepare(`
             INSERT INTO account_entitlements (
                 account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
             ) VALUES ('u1', 'default', 'starter-v1', 'active', ?, ?, ?)
-        `).run(now, now, now);
+        `).run(stale, stale, stale);
         const statusRoute = routeHandlers.get('GET /api/taskforce/billing/status');
         const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
         const res = createMockRes();
@@ -1471,6 +1472,35 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(entitlement?.plan_version_id).toBe('pro-v1');
     });
+    it('skips Stripe reconciliation for fresh billing mirror rows when billing status is requested', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_catalog (plan_id, tenant_id, display_name, status, created_at, updated_at)
+            VALUES ('pro', 'default', 'Pro Plan', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('pro-v1', 'default', 'pro', 1, 1, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, tier, billing_interval, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'cus_123', 'sub_123', 'price_pro_month', 'active', 'pro', 'month', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, created_at, updated_at
+            ) VALUES ('u1', 'default', 'pro-v1', 'active', ?, ?, ?)
+        `).run(now, now, now);
+        const statusRoute = routeHandlers.get('GET /api/taskforce/billing/status');
+        const req = createMockReq('', { 'x-taskforce-runtime-mode': 'cloud' });
+        const res = createMockRes();
+        await statusRoute(req, res, {});
+        expect(res.statusCode).toBe(200);
+        expect(mockSubscriptionRetrieve).not.toHaveBeenCalled();
+        expect(mockCustomersList).not.toHaveBeenCalled();
+        expect(mockSubscriptionList).not.toHaveBeenCalled();
+    });
     it('repairs billing status from an active Stripe subscription discovered by account email', async () => {
         const now = new Date().toISOString();
         db.prepare(`

package/dist/server/routes/documents.js

@@ -24,9 +24,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { normalizeTaskDataRelativePath } from '../../storage/objectStorageClient.js';
+import { shouldUseProvisionalTaskReferences } from '../../utils/taskReferences.js';
 import { purgeExpiredDocuments } from '../../storage/documentPurge.js';
 import { parsePlan } from '../../utils/planParser.js';
 import { getCanonicalDocumentName, getReadableDocumentName, isGeneratedDocumentName } from '../../utils/documentNames.js';
+import { requestRuntimeMode } from './shared.js';
 import { parseJsonBody } from '../routes.js';
 export function registerDocumentRoutes(deps) {
     const { addRoute, core, context, requestWorkspaceId, ensureAdminRole, resolveEffectiveObjectStorageConfig, getObjectStorageClient, resolveStorageWorkspaceId, ensureContextUploadAllowed, parseStorageFolderSegments, buildCanonicalWorkspaceAssetRelativePath, inferAssetKindFromPath, appendStorageTelemetry, scanAndRecordDocument, buildTaskAttachmentPayload, workspaceAssetStore, taskAssetStore, normalizeDocumentPathInput, getAssetMetadata, getCanonicalAssetMetadata, documentRetentionDays, appendDocumentPurgeHistory, markAssetDeleted, isAssetDeleted, clearAssetDeleted, ensureWithinDir, sanitizeDownloadFilename, contentTypeForExt, inferInlineDocumentFromPath, resolveCanonicalDocumentRead, inferWorkspaceIdFromStoragePath, inferTaskIdFromStoragePath, } = deps;
@@ -1097,7 +1099,10 @@ export function registerDocumentRoutes(deps) {
                         type: node.type || 'feature',
                         priority: typeof node.priority === 'number' ? node.priority : 2,
                         status: 'task',
-                    }, { workspaceId });
+                    }, {
+                        workspaceId,
+                        provisionalLocalReference: shouldUseProvisionalTaskReferences(requestRuntimeMode(req))
+                    });
                     created.push(taskItem.id);
                     totalCreated++;
                 }

package/dist/server/routes/shared.d.ts

@@ -30,6 +30,6 @@ export declare function makeResolveAdminRequestActor(core: TaskforceCore, contex
     systemRole: "system_admin" | "user";
 };
 export declare function makeAuditAdminAction(core: TaskforceCore, context: RouteContext): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
-export declare function makeAuditAuthAction(core: TaskforceCore, requestWorkspaceId: (req: IncomingMessage) => string): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
+export declare function makeAuditAuthAction(core: TaskforceCore, requestWorkspaceId: (req: IncomingMessage) => string, context: RouteContext): (req: IncomingMessage, action: string, details: Record<string, unknown>) => void;
 export declare function makeRequireCloudRuntime(context: RouteContext): (res: ServerResponse, feature: string) => boolean;
 export declare function makeEnsureCloudPlanData(context: RouteContext): (req: IncomingMessage, res: ServerResponse) => boolean;

package/dist/server/routes/shared.js

@@ -257,13 +257,21 @@ export function makeAuditAdminAction(core, context) {
         console.info(`[Taskforce Admin Audit] ${JSON.stringify(payload)}`);
     };
 }
-export function makeAuditAuthAction(core, requestWorkspaceId) {
+export function makeAuditAuthAction(core, requestWorkspaceId, context) {
     return function auditAuthAction(req, action, details) {
+        const authConfig = context.authConfig;
+        const resolvedAccess = authConfig?.enabled ? resolveRequestAccess(req, authConfig) : null;
+        const actorUserId = resolvedAccess?.authenticated && resolvedAccess.userId && resolvedAccess.userId !== 'anonymous'
+            ? resolvedAccess.userId
+            : requestUserId(req);
+        const actorRole = resolvedAccess?.authenticated
+            ? String(resolvedAccess.role || '').trim().toLowerCase() || requestRole(req)
+            : requestRole(req);
         const payload = {
             ts: new Date().toISOString(),
             action,
-            actorUserId: requestUserId(req),
-            actorRole: requestRole(req),
+            actorUserId,
+            actorRole,
             workspaceId: requestWorkspaceId(req),
             details
         };