@taskforcehq/taskforce 0.3.304 → 0.3.305

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

@@ -1415,7 +1415,7 @@ describe('Billing Webhook Routes', () => {
             stripe_subscription_id: 'sub_email_match'
         }));
     });
-    it('updates the existing paid subscription instead of creating a second checkout', async () => {
+    it('updates the existing paid subscription and keeps canonical entitlement aligned with the new plan', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
@@ -1476,12 +1476,26 @@ describe('Billing Webhook Routes', () => {
             planVersionId: 'team-v1'
         }));
         const entitlement = db.prepare(`
-            SELECT plan_version_id
+            SELECT plan_version_id, entitlement_state, updated_by
             FROM account_entitlements
             WHERE tenant_id = 'default' AND account_id = 'u1'
             LIMIT 1
         `).get();
-        expect(entitlement?.plan_version_id).toBe('team-v1');
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'team-v1',
+            entitlement_state: 'active',
+            updated_by: 'checkout-confirm'
+        }));
+        const billingRow = db.prepare(`
+            SELECT stripe_price_id, billing_interval
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(billingRow).toEqual(expect.objectContaining({
+            stripe_price_id: 'price_team_month',
+            billing_interval: 'month'
+        }));
     });
     it('updates the existing subscription when only the interval changes on the same plan', async () => {
         const now = new Date().toISOString();
@@ -1544,7 +1558,7 @@ describe('Billing Webhook Routes', () => {
             planVersionId: 'pro-v1'
         }));
     });
-    it('confirms a successful checkout session and updates the entitlement immediately', async () => {
+    it('confirms a successful checkout session, activates canonical entitlement, and closes the checkout attempt', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
@@ -1554,6 +1568,11 @@ describe('Billing Webhook Routes', () => {
             INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
             VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
         `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_success_123', 'default', 'u1', 'pro-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
         const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
         expect(confirmHandler).toBeTypeOf('function');
         const req = createMockReq(JSON.stringify({
@@ -1570,14 +1589,36 @@ describe('Billing Webhook Routes', () => {
         }));
         expect(mockSubscriptionRetrieve).toHaveBeenCalledWith('sub_123');
         const entitlement = db.prepare(`
-            SELECT plan_version_id, entitlement_state
+            SELECT plan_version_id, entitlement_state, updated_by
             FROM account_entitlements
             WHERE tenant_id = 'default' AND account_id = 'u1'
             LIMIT 1
         `).get();
         expect(entitlement).toEqual(expect.objectContaining({
             plan_version_id: 'pro-v1',
-            entitlement_state: 'active'
+            entitlement_state: 'active',
+            updated_by: 'checkout-confirm'
+        }));
+        const billingRow = db.prepare(`
+            SELECT stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status
+            FROM user_billing
+            WHERE tenant_id = 'default' AND user_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(billingRow).toEqual(expect.objectContaining({
+            stripe_customer_id: 'cus_123',
+            stripe_subscription_id: 'sub_123',
+            stripe_price_id: 'price_pro_month',
+            stripe_status: 'active'
+        }));
+        const attempt = db.prepare(`
+            SELECT status
+            FROM billing_checkout_attempts
+            WHERE tenant_id = 'default' AND session_id = 'cs_success_123'
+            LIMIT 1
+        `).get();
+        expect(attempt).toEqual(expect.objectContaining({
+            status: 'confirmed'
         }));
     });
     it('does not activate entitlement when the checkout session is still incomplete', async () => {
@@ -1631,6 +1672,156 @@ describe('Billing Webhook Routes', () => {
             updated_by: 'checkout-start'
         }));
     });
+    it('keeps checkout confirmation retryable until Stripe attaches the subscription to the completed session', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('free-v1', 'default', 'free', 1, 1, '{}', ?, ?)
+        `).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, 0, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'free-v1', 'active', ?, 'registration', ?, ?)
+        `).run(now, now, now);
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_pending_subscription', 'default', 'u1', 'pro-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
+        mockCheckoutRetrieve.mockResolvedValueOnce({
+            id: 'cs_pending_subscription',
+            mode: 'subscription',
+            status: 'complete',
+            payment_status: 'paid',
+            customer: 'cus_123',
+            subscription: null,
+            metadata: { userId: 'u1', planVersionId: 'pro-v1' }
+        });
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_pending_subscription'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await confirmHandler(req, res, {});
+        expect(res.statusCode).toBe(409);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'Checkout session is still finalizing your subscription.',
+            code: 'CHECKOUT_SESSION_INCOMPLETE'
+        });
+        expect(mockSubscriptionRetrieve).not.toHaveBeenCalled();
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'free-v1',
+            entitlement_state: 'active'
+        }));
+        const attempt = db.prepare(`
+            SELECT status
+            FROM billing_checkout_attempts
+            WHERE tenant_id = 'default' AND session_id = 'cs_pending_subscription'
+            LIMIT 1
+        `).get();
+        expect(attempt).toEqual(expect.objectContaining({
+            status: 'open'
+        }));
+    });
+    it('keeps checkout confirmation retryable until the subscription settles into an active commercial state', async () => {
+        const now = new Date().toISOString();
+        db.prepare(`
+            INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
+            VALUES ('free-v1', 'default', 'free', 1, 1, '{}', ?, ?)
+        `).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, 0, '{}', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, active, created_at, updated_at)
+            VALUES ('default', 'pro-v1', 'month', 'price_pro_month', 1, ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO user_billing (
+                user_id, tenant_id, tier, entitlement_state, created_at, updated_at
+            ) VALUES ('u1', 'default', 'free', 'active', ?, ?)
+        `).run(now, now);
+        db.prepare(`
+            INSERT INTO account_entitlements (
+                account_id, tenant_id, plan_version_id, entitlement_state, effective_at, updated_by, created_at, updated_at
+            ) VALUES ('u1', 'default', 'free-v1', 'active', ?, 'registration', ?, ?)
+        `).run(now, now, now);
+        db.prepare(`
+            INSERT INTO billing_checkout_attempts (
+                session_id, tenant_id, user_id, plan_version_id, billing_interval, status, expires_at, created_at, updated_at
+            ) VALUES ('cs_wait_for_active', 'default', 'u1', 'pro-v1', 'month', 'open', ?, ?, ?)
+        `).run(new Date(Date.now() + 60 * 60 * 1000).toISOString(), now, now);
+        mockCheckoutRetrieve.mockResolvedValueOnce({
+            id: 'cs_wait_for_active',
+            mode: 'subscription',
+            status: 'complete',
+            payment_status: 'paid',
+            customer: 'cus_123',
+            subscription: 'sub_123',
+            metadata: { userId: 'u1', planVersionId: 'pro-v1' }
+        });
+        mockSubscriptionRetrieve.mockResolvedValueOnce({
+            id: 'sub_123',
+            customer: 'cus_123',
+            status: 'incomplete',
+            trial_end: null,
+            metadata: { userId: 'u1', planVersionId: 'pro-v1' },
+            items: {
+                data: [{
+                        id: 'si_123',
+                        current_period_end: Math.floor(Date.now() / 1000) + 86400,
+                        price: { id: 'price_pro_month', recurring: { interval: 'month' } }
+                    }]
+            }
+        });
+        const confirmHandler = routeHandlers.get('POST /api/taskforce/billing/checkout-session/confirm');
+        const req = createMockReq(JSON.stringify({
+            sessionId: 'cs_wait_for_active'
+        }), {
+            'x-taskforce-runtime-mode': 'cloud',
+            host: 'app.taskforcehq.ai'
+        });
+        const res = createMockRes();
+        await confirmHandler(req, res, {});
+        expect(res.statusCode).toBe(409);
+        expect(JSON.parse(res.body)).toEqual({
+            error: 'Checkout session is still finalizing your plan.',
+            code: 'CHECKOUT_SESSION_INCOMPLETE'
+        });
+        const entitlement = db.prepare(`
+            SELECT plan_version_id, entitlement_state
+            FROM account_entitlements
+            WHERE tenant_id = 'default' AND account_id = 'u1'
+            LIMIT 1
+        `).get();
+        expect(entitlement).toEqual(expect.objectContaining({
+            plan_version_id: 'free-v1',
+            entitlement_state: 'active'
+        }));
+        const attempt = db.prepare(`
+            SELECT status
+            FROM billing_checkout_attempts
+            WHERE tenant_id = 'default' AND session_id = 'cs_wait_for_active'
+            LIMIT 1
+        `).get();
+        expect(attempt).toEqual(expect.objectContaining({
+            status: 'open'
+        }));
+    });
     it('rejects checkout confirmation when a newer pending checkout superseded the session plan', async () => {
         const now = new Date().toISOString();
         db.prepare(`
@@ -1928,14 +2119,7 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(purged).toBeUndefined();
     });
-    it('lists stripe price options filtered by interval for system admin', async () => {
-        mockPricesList.mockResolvedValueOnce({
-            data: [
-                { id: 'price_month_1', active: true, currency: 'usd', unit_amount: 1200, recurring: { interval: 'month' }, nickname: 'Monthly', product: 'prod_1' },
-                { id: 'price_year_1', active: true, currency: 'usd', unit_amount: 12000, recurring: { interval: 'year' }, nickname: 'Yearly', product: 'prod_1' }
-            ],
-            has_more: false
-        });
+    it('rejects manual stripe price option listing now that pricing is import-only', async () => {
         const route = routeHandlers.get('GET /api/taskforce/admin/billing/stripe-price-options');
         expect(route).toBeTypeOf('function');
         const req = createMockReq('', {
@@ -1944,16 +2128,11 @@ describe('Billing Webhook Routes', () => {
         req.url = '/api/taskforce/admin/billing/stripe-price-options?interval=month';
         const res = createMockRes();
         await route(req, res, {});
-        expect(res.statusCode).toBe(200);
+        expect(res.statusCode).toBe(410);
         const body = JSON.parse(res.body);
-        expect(Array.isArray(body.options)).toBe(true);
-        expect(body.options.length).toBe(1);
-        expect(body.options[0]).toEqual(expect.objectContaining({
-            stripePriceId: 'price_month_1',
-            interval: 'month'
-        }));
+        expect(body.code).toBe('BILLING_PRICE_MANUAL_MAPPING_REMOVED');
     });
-    it('keeps active manual price mappings during Stripe import when the price is still active but lacks plan metadata', async () => {
+    it('keeps active imported price mappings during Stripe import when the Stripe price is still active but lacks plan metadata', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
@@ -1992,23 +2171,12 @@ describe('Billing Webhook Routes', () => {
         `).get();
         expect(row.active).toBe(1);
     });
-    it('upserts price mappings and deactivates prior active mapping for same version interval', async () => {
+    it('rejects manual price mapping upserts now that pricing is import-only', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
             VALUES ('collab-v1', 'default', 'collab', 1, 1, '{}', ?, ?)
         `).run(now, now);
-        db.prepare(`
-            INSERT INTO billing_price_mappings (tenant_id, plan_version_id, billing_interval, stripe_price_id, pricing_type, active, unit_amount, currency, created_at, updated_at)
-            VALUES ('default', 'collab-v1', 'month', 'price_old', 'stripe', 1, 1100, 'usd', ?, ?)
-        `).run(now, now);
-        mockPriceRetrieve.mockResolvedValueOnce({
-            id: 'price_new',
-            active: true,
-            currency: 'usd',
-            unit_amount: 1500,
-            recurring: { interval: 'month' }
-        });
         const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
         expect(upsertRoute).toBeTypeOf('function');
         const upsertReq = createMockReq(JSON.stringify({
@@ -2019,19 +2187,12 @@ describe('Billing Webhook Routes', () => {
         }), { 'x-taskforce-runtime-mode': 'cloud' });
         const upsertRes = createMockRes();
         await upsertRoute(upsertReq, upsertRes, {});
-        expect(upsertRes.statusCode).toBe(200);
-        const rows = db.prepare(`
-            SELECT stripe_price_id, active
-            FROM billing_price_mappings
-            WHERE tenant_id = 'default' AND plan_version_id = 'collab-v1' AND billing_interval = 'month'
-            ORDER BY stripe_price_id ASC
-        `).all();
-        expect(rows).toEqual([
-            { stripe_price_id: 'price_new', active: 1 },
-            { stripe_price_id: 'price_old', active: 0 }
-        ]);
+        expect(upsertRes.statusCode).toBe(410);
+        expect(JSON.parse(upsertRes.body)).toEqual(expect.objectContaining({
+            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+        }));
     });
-    it('allows the same stripe price id to be assigned to multiple plan versions', async () => {
+    it('rejects manual reuse of a Stripe price id across multiple plan versions', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
@@ -2041,13 +2202,6 @@ describe('Billing Webhook Routes', () => {
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
             VALUES ('team-v1', 'default', 'team', 1, 1, '{}', ?, ?)
         `).run(now, now);
-        mockPriceRetrieve.mockResolvedValue({
-            id: 'price_shared',
-            active: true,
-            currency: 'usd',
-            unit_amount: 1900,
-            recurring: { interval: 'month' }
-        });
         const upsertRoute = routeHandlers.get('PUT /api/taskforce/admin/billing/price-mappings');
         const firstReq = createMockReq(JSON.stringify({
             planVersionId: 'collab-v1',
@@ -2057,28 +2211,9 @@ describe('Billing Webhook Routes', () => {
         }), { 'x-taskforce-runtime-mode': 'cloud' });
         const firstRes = createMockRes();
         await upsertRoute(firstReq, firstRes, {});
-        expect(firstRes.statusCode).toBe(200);
-        const secondReq = createMockReq(JSON.stringify({
-            planVersionId: 'team-v1',
-            interval: 'month',
-            stripePriceId: 'price_shared',
-            active: true
-        }), { 'x-taskforce-runtime-mode': 'cloud' });
-        const secondRes = createMockRes();
-        await upsertRoute(secondReq, secondRes, {});
-        expect(secondRes.statusCode).toBe(200);
-        const rows = db.prepare(`
-            SELECT plan_version_id, stripe_price_id, active
-            FROM billing_price_mappings
-            WHERE tenant_id = 'default' AND stripe_price_id = 'price_shared'
-            ORDER BY plan_version_id ASC
-        `).all();
-        expect(rows).toEqual([
-            { plan_version_id: 'collab-v1', stripe_price_id: 'price_shared', active: 1 },
-            { plan_version_id: 'team-v1', stripe_price_id: 'price_shared', active: 1 }
-        ]);
+        expect(firstRes.statusCode).toBe(410);
     });
-    it('keeps reused mappings for other plan versions during Stripe import', async () => {
+    it('keeps reused active mappings during Stripe import when the shared Stripe price is still active', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
@@ -2125,7 +2260,7 @@ describe('Billing Webhook Routes', () => {
             { plan_version_id: 'team-v1', stripe_price_id: 'price_shared', active: 1 }
         ]);
     });
-    it('upserts explicit free pricing without requiring a Stripe price id', async () => {
+    it('rejects manual free price mapping upserts now that pricing is import-only', async () => {
         const now = new Date().toISOString();
         db.prepare(`
             INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, metadata_json, created_at, updated_at)
@@ -2141,17 +2276,10 @@ describe('Billing Webhook Routes', () => {
         }), { 'x-taskforce-runtime-mode': 'cloud' });
         const upsertRes = createMockRes();
         await upsertRoute(upsertReq, upsertRes, {});
-        expect(upsertRes.statusCode).toBe(200);
-        const row = db.prepare(`
-            SELECT stripe_price_id, pricing_type, active, unit_amount
-            FROM billing_price_mappings
-            WHERE tenant_id = 'default' AND plan_version_id = 'starter-v1' AND billing_interval = 'month'
-            LIMIT 1
-        `).get();
-        expect(row.stripe_price_id).toBe('free:starter-v1:month');
-        expect(row.pricing_type).toBe('free');
-        expect(row.active).toBe(1);
-        expect(row.unit_amount).toBe(0);
+        expect(upsertRes.statusCode).toBe(410);
+        expect(JSON.parse(upsertRes.body)).toEqual(expect.objectContaining({
+            code: 'BILLING_PRICE_MANUAL_MAPPING_REMOVED'
+        }));
     });
     it('rejects webhook failure diagnostics for non-admin', async () => {
         const nonAdminHandlers = buildBillingRouteHandlers(db, { isAdmin: false });

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

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'http';
 import type { TaskforceCore } from '../../core/Taskforce.js';
-import type { RouteHandler } from '../routes.js';
+import { type RouteHandler } from './primitives.js';
 export interface DocumentReviewRouteDependencies {
     addRoute: (method: string, path: string, handler: RouteHandler) => void;
     core: TaskforceCore;

package/dist/server/routes/documentReviews.js

@@ -1,4 +1,4 @@
-import { parseJsonBody } from '../routes.js';
+import { parseJsonBody } from './primitives.js';
 import { resolveErrorStatusCode } from './shared.js';
 function writeJson(res, statusCode, payload) {
     res.writeHead(statusCode, { 'Content-Type': 'application/json' });

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

@@ -28,7 +28,7 @@ import { ObjectStorageClient } from '../../storage/objectStorageClient.js';
 import type { DocumentRegistryEntry } from '../../storage/documentRegistry.js';
 import { TaskAssetStore } from '../../storage/taskAssetStore.js';
 import { WorkspaceAssetStore, type WorkspaceAssetEntry, type WorkspaceAssetKind } from '../../storage/workspaceAssetStore.js';
-import type { RouteContext, RouteHandler } from '../routes.js';
+import { type RouteContext, type RouteHandler } from './primitives.js';
 type AssetMetadata = DocumentRegistryEntry & {
     quarantineStatus?: 'none' | 'quarantined' | 'released';
     workspaceId?: string;
@@ -51,7 +51,9 @@ export interface DocumentRouteDependencies {
     resolveEffectiveObjectStorageConfig: () => ResolvedObjectStorageConfig;
     getObjectStorageClient: () => ObjectStorageClient | null;
     resolveStorageWorkspaceId: (req: IncomingMessage, body?: any) => string | null;
-    ensureContextUploadAllowed: (req: IncomingMessage, res: ServerResponse, workspaceId: string) => boolean;
+    ensureContextUploadAllowed: (req: IncomingMessage, res: ServerResponse, workspaceId: string, options?: {
+        requestedBytes?: number | null;
+    }) => boolean;
     parseStorageFolderSegments: (folderPathRaw: unknown) => string[] | null;
     buildCanonicalWorkspaceAssetRelativePath: (params: {
         workspaceIdRaw: unknown;

package/dist/server/routes/documents.js

@@ -29,21 +29,53 @@ 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';
+import { parseJsonBody } from './primitives.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;
+    const removeDocumentAttachmentFromTaskAttachments = (attachmentsRaw, asset) => {
+        const canonicalDocumentPath = `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`;
+        const legacyContextPath = `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`;
+        if (!Array.isArray(attachmentsRaw))
+            return [];
+        return attachmentsRaw.filter((attachment) => {
+            if (typeof attachment === 'string') {
+                const normalized = attachment.trim();
+                if (!normalized)
+                    return false;
+                return normalized !== canonicalDocumentPath
+                    && normalized !== legacyContextPath
+                    && normalized !== asset.storageKey;
+            }
+            if (!attachment || typeof attachment !== 'object')
+                return false;
+            const candidate = attachment;
+            const candidatePath = String(candidate.path || '').trim();
+            const candidateFsPath = String(candidate.fsPath || '').trim();
+            const candidateAssetId = String(candidate.assetId || '').trim();
+            if (candidateAssetId && candidateAssetId === asset.assetId)
+                return false;
+            if (candidatePath === canonicalDocumentPath || candidatePath === legacyContextPath)
+                return false;
+            if (candidateFsPath && candidateFsPath === asset.storageKey)
+                return false;
+            return !!candidatePath;
+        });
+    };
     addRoute('POST', '/api/taskforce/context-upload/init', async (req, res) => {
         const resolvedObjectStorage = resolveEffectiveObjectStorageConfig();
         const objectStorageClient = getObjectStorageClient();
         const body = await parseJsonBody(req);
         const { originalName, mimeType, taskId, folderPath } = body || {};
         const workspaceId = resolveStorageWorkspaceId(req, body);
+        const requestedBytes = Number(body?.size);
         if (!workspaceId) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'workspaceId is required and cannot be default for uploads.' }));
             return;
         }
-        if (!ensureContextUploadAllowed(req, res, workspaceId))
+        if (!ensureContextUploadAllowed(req, res, workspaceId, {
+            requestedBytes: Number.isFinite(requestedBytes) ? requestedBytes : null
+        }))
             return;
         const folderSegments = parseStorageFolderSegments(folderPath);
         if (folderSegments === null) {
@@ -144,6 +176,10 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'Uploaded file not found.' }));
             return;
         }
+        if (!ensureContextUploadAllowed(req, res, workspaceId, {
+            requestedBytes: object.body.length
+        }))
+            return;
         try {
             const taskId = typeof body?.taskId === 'string' && body.taskId.trim().length > 0
                 ? body.taskId.trim()
@@ -191,8 +227,6 @@ export function registerDocumentRoutes(deps) {
             res.end(JSON.stringify({ error: 'workspaceId is required and cannot be default for uploads.' }));
             return;
         }
-        if (!ensureContextUploadAllowed(req, res, workspaceId))
-            return;
         const folderSegments = parseStorageFolderSegments(folderPath);
         if (folderSegments === null) {
             res.writeHead(400, { 'Content-Type': 'application/json' });
@@ -233,6 +267,10 @@ export function registerDocumentRoutes(deps) {
         const actualFilename = `${safeBase}-${Date.now()}${extension}`;
         const { basePath, projectRoot } = core.getPaths();
         const buffer = Buffer.from(base64Data, 'base64');
+        if (!ensureContextUploadAllowed(req, res, workspaceId, {
+            requestedBytes: buffer.length
+        }))
+            return;
         const relativeToStorage = buildCanonicalWorkspaceAssetRelativePath({
             workspaceIdRaw: workspaceId,
             kind: mimeType.startsWith('image/') ? 'image' : inferAssetKindFromPath(actualFilename),
@@ -771,6 +809,8 @@ export function registerDocumentRoutes(deps) {
     addRoute('DELETE', '/api/taskforce/documents/:assetId', async (req, res, params) => {
         const workspaceId = requestWorkspaceId(req);
         const assetId = String(params.assetId || '').trim();
+        const body = await parseJsonBody(req);
+        const forceDetach = body?.forceDetach === true;
         if (!workspaceAssetStore || !assetId) {
             res.writeHead(404, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Document not found' }));
@@ -786,14 +826,39 @@ export function registerDocumentRoutes(deps) {
             .filter((link) => !link.deletedAt)
             .filter((link) => !!core.getTask(link.taskId, workspaceId));
         if (activeLinks.length > 0) {
-            res.writeHead(409, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Document is still attached to one or more tasks.' }));
-            return;
+            if (!forceDetach) {
+                res.writeHead(409, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    error: 'Document is still attached to one or more tasks.',
+                    activeAttachmentCount: activeLinks.length,
+                    requiresForceDetach: true
+                }));
+                return;
+            }
+            for (const link of activeLinks) {
+                const task = core.getTask(link.taskId, workspaceId);
+                if (!task)
+                    continue;
+                const updatedAttachments = removeDocumentAttachmentFromTaskAttachments(task.attachments, asset);
+                core.updateTask(link.taskId, { attachments: updatedAttachments }, workspaceId, {
+                    actorRef: 'user',
+                    saveSource: 'manual'
+                });
+            }
         }
         const nowIso = new Date().toISOString();
         const purgeAfter = new Date(Date.now() + documentRetentionDays * 24 * 60 * 60 * 1000).toISOString();
         const metadata = markAssetDeleted(asset.storageKey);
         workspaceAssetStore.markDeleted(asset.assetId, workspaceId, nowIso, purgeAfter);
+        const links = workspaceAssetStore.listLinksForAsset(asset.assetId, workspaceId, { includeDeleted: true });
+        for (const link of links) {
+            workspaceAssetStore.deleteLink({
+                workspaceId,
+                assetId: asset.assetId,
+                taskId: link.taskId,
+                role: link.role
+            });
+        }
         appendStorageTelemetry('delete.soft', {
             path: asset.storageKey,
             status: 'soft-deleted',
@@ -803,6 +868,7 @@ export function registerDocumentRoutes(deps) {
         res.end(JSON.stringify({
             success: true,
             softDeleted: true,
+            detachedTaskCount: activeLinks.length,
             retentionDays: documentRetentionDays,
             purgeAfter: metadata?.purgeAfter || purgeAfter
         }));

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

@@ -0,0 +1,11 @@
+import { IncomingMessage, ServerResponse } from 'http';
+import type { TaskforceAuthConfig } from '../auth.js';
+import type { ResolvedObjectStorageConfig } from '../../storage/objectStorage.js';
+export type RouteHandler = (req: IncomingMessage, res: ServerResponse, params: Record<string, string>) => Promise<void>;
+export interface RouteContext {
+    authConfig?: TaskforceAuthConfig;
+    objectStorage?: ResolvedObjectStorageConfig;
+}
+export declare function parseJsonBody(req: IncomingMessage, maxBytes?: number): Promise<any>;
+export declare function parseFormBody(req: IncomingMessage, maxBytes?: number): Promise<Record<string, string>>;
+export declare function escapeHtml(value: unknown): string;