availsync 0.1.0

package/src/routes/work.ts

@@ -0,0 +1,1578 @@
+import express from 'express';
+import { z } from 'zod';
+import type { Pool, PoolClient } from 'pg';
+import pool from '../db/client';
+import { log } from '../lib/logger';
+import { actorFromAuth, durationSince, logActivity } from '../lib/activity';
+import { enforcePlanLimit, getPlanUsage } from '../lib/plans';
+import {
+  canAccessAgent,
+  isAgentAuth,
+  requireWorkspaceOrAgent,
+  type AnyAuthenticatedRequest,
+} from '../middleware/auth';
+import {
+  DEFAULT_WORK_LEASE_MINUTES,
+  MAX_WORK_EXTENSION_MINUTES,
+  MAX_WORK_LOCK_MINUTES,
+  claimWorkSlot,
+  expireOldWorkClaims,
+  initialWorkExpiresAt,
+  maxWorkExpiresAt,
+  previewWorkClaim,
+  secondsUntilExpiry,
+  upsertWorkResource,
+  workWindow,
+} from '../core/work';
+import type { WorkClaim, WorkResource } from '../types';
+
+const router = express.Router();
+
+const WorkRequestSchema = z.object({
+  agent_id: z.string().uuid(),
+  resource_type: z.enum(['project', 'repo']),
+  resource_key: z.string().min(1).max(300),
+  label: z.string().min(1).max(300).optional(),
+  start_at: z.string().datetime({ offset: true }).optional(),
+  duration_minutes: z.coerce.number().int().min(1).max(24 * 60).optional().default(45),
+  reason: z.string().max(500).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+
+const WorkRunStartSchema = WorkRequestSchema.extend({
+  idempotency_key: z.string().trim().min(1).max(200).optional(),
+  client_name: z.string().trim().min(1).max(100).optional(),
+});
+
+const WorkClaimsQuerySchema = z.object({
+  agent_id: z.string().uuid().optional(),
+  resource_type: z.enum(['project', 'repo']).optional(),
+  resource_key: z.string().min(1).max(300).optional(),
+  status: z.enum(['active', 'superseded', 'released', 'expired', 'blocked']).optional().default('active'),
+  limit: z.coerce.number().int().min(1).max(200).optional().default(100),
+});
+
+const ExtendWorkClaimSchema = z.object({
+  duration_minutes: z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_WORK_EXTENSION_MINUTES)
+    .optional()
+    .default(DEFAULT_WORK_LEASE_MINUTES),
+});
+
+const RunExtendWorkClaimSchema = ExtendWorkClaimSchema.extend({
+  claim_id: z.string().uuid(),
+  client_name: z.string().trim().min(1).max(100).optional(),
+});
+
+const RunFinishWorkClaimSchema = z.object({
+  claim_id: z.string().uuid(),
+  outcome: z.string().trim().min(1).max(100).optional(),
+  reason: z.string().trim().max(500).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+  client_name: z.string().trim().min(1).max(100).optional(),
+});
+
+const IdempotencyKeySchema = z.string().trim().min(1).max(200);
+
+async function getAgentInOrg(agentId: string, orgId: string) {
+  const result = await pool.query('SELECT * FROM agents WHERE id = $1 AND org_id = $2', [agentId, orgId]);
+  return result.rows[0];
+}
+
+function explainWorkResult(status: 'available' | 'would_win' | 'would_lose', resourceKey: string) {
+  if (status === 'available') {
+    return `No active work claim is blocking ${resourceKey}.`;
+  }
+  if (status === 'would_win') {
+    return `This agent has priority and would supersede lower-priority work on ${resourceKey}.`;
+  }
+  return `Another active work claim has priority on ${resourceKey}. The automation should skip with this reason.`;
+}
+
+async function findWorkResource(input: {
+  org_id: string;
+  resource_type: string;
+  resource_key: string;
+}): Promise<WorkResource | null> {
+  const result = await pool.query<WorkResource>(
+    `SELECT *
+     FROM work_resources
+     WHERE org_id = $1
+       AND resource_type = $2
+       AND resource_key = $3`,
+    [input.org_id, input.resource_type, input.resource_key],
+  );
+  return result.rows[0] ?? null;
+}
+
+function publicResource(resource: WorkResource | null, input: z.infer<typeof WorkRequestSchema>) {
+  return {
+    id: resource?.id ?? null,
+    resource_type: resource?.resource_type ?? input.resource_type,
+    resource_key: resource?.resource_key ?? input.resource_key,
+    label: resource?.label ?? input.label ?? input.resource_key,
+  };
+}
+
+function publicClaim<T extends Record<string, unknown>>(claim: T): Omit<T, 'idempotency_key'> & {
+  seconds_until_expiry: number | null;
+} {
+  const { idempotency_key: _idempotencyKey, ...rest } = claim;
+  const expiresAt = rest.expires_at ? new Date(String(rest.expires_at)) : null;
+  return {
+    ...rest,
+    seconds_until_expiry: expiresAt ? secondsUntilExpiry(expiresAt) : null,
+  };
+}
+
+function automationMetadata(metadata?: Record<string, unknown>) {
+  return {
+    ...(metadata ?? {}),
+    source: 'automation_guardrail',
+  };
+}
+
+function parseIdempotencyKey(headerValue: string | undefined, bodyValue?: string | null) {
+  if (headerValue) {
+    const parsed = IdempotencyKeySchema.safeParse(headerValue);
+    return parsed.success ? { key: headerValue.trim() } : { error: 'invalid_idempotency_key' };
+  }
+  if (bodyValue) {
+    const parsed = IdempotencyKeySchema.safeParse(bodyValue);
+    return parsed.success ? { key: bodyValue.trim() } : { error: 'invalid_idempotency_key' };
+  }
+  return { key: null };
+}
+
+async function insertWorkEvent(input: {
+  db?: Pool | PoolClient;
+  claim_id?: string | null;
+  event_type: 'created' | 'blocked' | 'superseded' | 'released' | 'expired' | 'extended' | 'shadow_blocked' | 'shadow_allowed';
+  agent_id: string;
+  org_id: string;
+  resource_id?: string | null;
+  conflicting_claim_id?: string | null;
+  rule_applied?: string | null;
+  metadata?: Record<string, unknown> | null;
+  actor_type?: string | null;
+  actor_id?: string | null;
+  actor_label?: string | null;
+}) {
+  const db = input.db ?? pool;
+  await db.query(
+    `INSERT INTO work_claim_events (
+       claim_id,
+       event_type,
+       agent_id,
+       org_id,
+       resource_id,
+       conflicting_claim_id,
+       rule_applied,
+       metadata,
+       actor_type,
+       actor_id,
+       actor_label
+     )
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+    [
+      input.claim_id ?? null,
+      input.event_type,
+      input.agent_id,
+      input.org_id,
+      input.resource_id ?? null,
+      input.conflicting_claim_id ?? null,
+      input.rule_applied ?? null,
+      JSON.stringify(input.metadata ?? {}),
+      input.actor_type ?? null,
+      input.actor_id ?? null,
+      input.actor_label ?? null,
+    ],
+  );
+}
+
+async function expireAndLogWorkClaims(db: Pool | PoolClient, orgId: string) {
+  const expired = await expireOldWorkClaims(db, orgId);
+  for (const claim of expired) {
+    await insertWorkEvent({
+      db,
+      claim_id: claim.id,
+      event_type: 'expired',
+      agent_id: claim.agent_id,
+      org_id: claim.org_id,
+      resource_id: claim.resource_id,
+      actor_type: 'system',
+      actor_label: 'Availsync',
+      metadata: {
+        expired_at: new Date().toISOString(),
+        expired_by: 'expires_at',
+        previous_expires_at: claim.expires_at.toISOString(),
+        planned_end_at: claim.end_at.toISOString(),
+      },
+    });
+  }
+}
+
+router.post('/work/check', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const parsed = WorkRequestSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  const { startAt, endAt } = workWindow(parsed.data);
+
+  try {
+    const agent = await getAgentInOrg(parsed.data.agent_id, authReq.org.id);
+    if (!agent) {
+      return res.status(403).json({ error: 'forbidden', message: 'Agent is outside your org' });
+    }
+    if (!canAccessAgent(authReq, parsed.data.agent_id)) {
+      return res.status(403).json({ error: 'forbidden', message: 'Agent key cannot act for another agent' });
+    }
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    await expireAndLogWorkClaims(pool, authReq.org.id);
+
+    const resource = await findWorkResource({
+      org_id: authReq.org.id,
+      resource_type: parsed.data.resource_type,
+      resource_key: parsed.data.resource_key,
+    });
+
+    const result = resource
+      ? await previewWorkClaim(pool, {
+          org_id: authReq.org.id,
+          agent_id: parsed.data.agent_id,
+          resource_id: resource.id,
+          start_at: startAt,
+          end_at: endAt,
+          reason: parsed.data.reason,
+          metadata: parsed.data.metadata,
+        })
+      : {
+          status: 'available' as const,
+          winning_claim_id: null,
+          losing_claim_ids: [],
+          rule_applied: 'none' as const,
+          suggested_retry_at: null,
+        };
+
+    await logActivity({
+      org_id: authReq.org.id,
+      agent_id: parsed.data.agent_id,
+      activity_type: 'work_check',
+      endpoint: '/v1/work/check',
+      method: 'POST',
+      status_code: 200,
+      status: 'success',
+      ...actorFromAuth(authReq),
+      latency_ms: durationSince(startedAt),
+      metadata: {
+        resource_type: parsed.data.resource_type,
+        resource_key: parsed.data.resource_key,
+        status: result.status,
+      },
+    });
+
+    return res.json({
+      status: result.status,
+      resource: publicResource(resource, parsed.data),
+      winning_claim_id: result.winning_claim_id,
+      losing_claim_ids: result.losing_claim_ids,
+      rule_applied: result.rule_applied,
+      explanation: explainWorkResult(result.status, parsed.data.resource_key),
+      suggested_retry_at: result.suggested_retry_at?.toISOString() ?? null,
+    });
+  } catch (err) {
+    log.error('[work] check error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/work/claim', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const parsed = WorkRequestSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  const actor = actorFromAuth(authReq);
+  const { startAt, endAt } = workWindow(parsed.data);
+  const idempotencyHeader = req.header('Idempotency-Key');
+  const idempotencyKey = idempotencyHeader
+    ? IdempotencyKeySchema.safeParse(idempotencyHeader).success
+      ? idempotencyHeader.trim()
+      : ''
+    : null;
+
+  if (idempotencyHeader && !idempotencyKey) {
+    return res.status(400).json({ error: 'invalid_idempotency_key', message: 'Idempotency-Key must be 1-200 characters' });
+  }
+
+  try {
+    const agent = await getAgentInOrg(parsed.data.agent_id, authReq.org.id);
+    if (!agent) {
+      return res.status(403).json({ error: 'forbidden', message: 'Agent is outside your org' });
+    }
+    if (!canAccessAgent(authReq, parsed.data.agent_id)) {
+      return res.status(403).json({ error: 'forbidden', message: 'Agent key cannot act for another agent' });
+    }
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
+        `${authReq.org.id}:${parsed.data.resource_type}:${parsed.data.resource_key}`,
+      ]);
+
+      await expireAndLogWorkClaims(client, authReq.org.id);
+
+      if (idempotencyKey) {
+        const existing = await client.query(
+          `SELECT
+             work_claims.*,
+             work_resources.resource_type,
+             work_resources.resource_key,
+             work_resources.label AS resource_label
+           FROM work_claims
+           JOIN work_resources ON work_resources.id = work_claims.resource_id
+           WHERE work_claims.org_id = $1
+             AND work_claims.agent_id = $2
+             AND work_claims.idempotency_key = $3
+           LIMIT 1`,
+          [authReq.org.id, parsed.data.agent_id, idempotencyKey],
+        );
+
+        if (existing.rows.length > 0) {
+          await client.query('COMMIT');
+          const existingClaim = existing.rows[0];
+          if (existingClaim.status === 'active' && new Date(existingClaim.expires_at) >= new Date()) {
+            await logActivity({
+              org_id: authReq.org.id,
+              agent_id: parsed.data.agent_id,
+              activity_type: 'work_claim',
+              endpoint: '/v1/work/claim',
+              method: 'POST',
+              status_code: 200,
+              status: 'success',
+              ...actor,
+              latency_ms: durationSince(startedAt),
+              metadata: {
+                claim_id: existingClaim.id,
+                idempotent_replay: true,
+                resource_type: existingClaim.resource_type,
+                resource_key: existingClaim.resource_key,
+              },
+            });
+            return res.status(200).json({
+              claim: publicClaim(existingClaim),
+              resource: {
+                id: existingClaim.resource_id,
+                resource_type: existingClaim.resource_type,
+                resource_key: existingClaim.resource_key,
+                label: existingClaim.resource_label,
+              },
+              status: 'available',
+              superseded_claim_ids: [],
+              idempotent_replay: true,
+            });
+          }
+
+          await logActivity({
+            org_id: authReq.org.id,
+            agent_id: parsed.data.agent_id,
+            activity_type: 'work_claim',
+            endpoint: '/v1/work/claim',
+            method: 'POST',
+            status_code: 409,
+            status: 'error',
+            ...actor,
+            latency_ms: durationSince(startedAt),
+            error_code: 'idempotency_key_reused',
+            error_message: 'Idempotency-Key was already used for an inactive work claim',
+            metadata: { previous_claim_id: existingClaim.id, previous_status: existingClaim.status },
+          });
+          return res.status(409).json({
+            error: 'idempotency_key_reused',
+            message: 'Idempotency-Key was already used for an inactive work claim',
+            previous_claim_id: existingClaim.id,
+            previous_status: existingClaim.status,
+          });
+        }
+      }
+
+      const claimResult = await claimWorkSlot(client, {
+        org_id: authReq.org.id,
+        agent_id: parsed.data.agent_id,
+        resource_type: parsed.data.resource_type,
+        resource_key: parsed.data.resource_key,
+        label: parsed.data.label,
+        start_at: startAt,
+        end_at: endAt,
+        reason: parsed.data.reason,
+        metadata: parsed.data.metadata,
+        idempotency_key: idempotencyKey,
+        actor,
+        beforeMutation: async ({ resource_existed, result }) => {
+          if (!resource_existed) {
+            const resourceAllowed = await enforcePlanLimit({
+              org_id: authReq.org.id,
+              limit_type: 'protected_resources',
+              db: client,
+              res,
+            });
+            if (!resourceAllowed) return false;
+          }
+
+          if (result.status === 'would_lose') return true;
+
+          const netActiveIncrease = result.status === 'would_win' ? Math.max(0, 1 - result.losing_claim_ids.length) : 1;
+          if (netActiveIncrease <= 0) return true;
+
+          const usage = await getPlanUsage(authReq.org.id, client);
+          return enforcePlanLimit({
+            org_id: authReq.org.id,
+            limit_type: 'active_work_claims',
+            increment: netActiveIncrease,
+            usage_override: usage.active_work_claims,
+            db: client,
+            res,
+          });
+        },
+      });
+
+      if (claimResult.outcome === 'aborted') {
+        await client.query('ROLLBACK');
+        return;
+      }
+
+      if (claimResult.outcome === 'blocked') {
+        await client.query('COMMIT');
+        await logActivity({
+          org_id: authReq.org.id,
+          agent_id: parsed.data.agent_id,
+          activity_type: 'work_blocked',
+          endpoint: '/v1/work/claim',
+          method: 'POST',
+          status_code: 409,
+          status: 'error',
+          ...actor,
+          latency_ms: durationSince(startedAt),
+          error_code: 'work_claim_blocked',
+          error_message: 'Another active work claim has priority for this resource',
+          metadata: {
+            resource_type: claimResult.resource.resource_type,
+            resource_key: claimResult.resource.resource_key,
+            winning_claim_id: claimResult.winning_claim_id,
+          },
+        });
+        return res.status(409).json({
+          error: 'work_claim_blocked',
+          message: 'Another active work claim has priority for this resource',
+          action: 'skip_run',
+          reason: explainWorkResult(claimResult.status, claimResult.resource.resource_key),
+          retry_after: claimResult.suggested_retry_at?.toISOString() ?? null,
+          blocking_claim: claimResult.blocking_claim ? publicClaim(claimResult.blocking_claim) : null,
+          status: claimResult.status,
+          resource: claimResult.resource,
+          winning_claim_id: claimResult.winning_claim_id,
+          losing_claim_ids: claimResult.losing_claim_ids,
+          rule_applied: claimResult.rule_applied,
+          explanation: explainWorkResult(claimResult.status, claimResult.resource.resource_key),
+          suggested_retry_at: claimResult.suggested_retry_at?.toISOString() ?? null,
+        });
+      }
+
+      await client.query('COMMIT');
+      await logActivity({
+        org_id: authReq.org.id,
+        agent_id: parsed.data.agent_id,
+        activity_type: 'work_claim',
+        endpoint: '/v1/work/claim',
+        method: 'POST',
+        status_code: 201,
+        status: 'success',
+        ...actor,
+        latency_ms: durationSince(startedAt),
+        metadata: {
+          claim_id: claimResult.claim.id,
+          resource_type: claimResult.resource.resource_type,
+          resource_key: claimResult.resource.resource_key,
+          superseded_claims: claimResult.losing_claim_ids,
+        },
+      });
+      return res.status(201).json({
+        claim: publicClaim(claimResult.claim as unknown as Record<string, unknown>),
+        resource: claimResult.resource,
+        status: claimResult.status,
+        superseded_claim_ids: claimResult.losing_claim_ids,
+        idempotent_replay: false,
+      });
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  } catch (err) {
+    log.error('[work] claim error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/work/run/start', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const parsed = WorkRunStartSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  const actor = actorFromAuth(authReq);
+  const { startAt, endAt } = workWindow(parsed.data);
+  const idempotency = parseIdempotencyKey(req.header('Idempotency-Key'), parsed.data.idempotency_key);
+
+  if ('error' in idempotency) {
+    return res.status(400).json({ error: 'invalid_idempotency_key', message: 'Idempotency-Key must be 1-200 characters' });
+  }
+
+  try {
+    const agent = await getAgentInOrg(parsed.data.agent_id, authReq.org.id);
+    if (!agent) {
+      return res.status(403).json({ error: 'forbidden', message: 'Agent is outside your org' });
+    }
+    if (!canAccessAgent(authReq, parsed.data.agent_id)) {
+      return res.status(403).json({ error: 'forbidden', message: 'Agent key cannot act for another agent' });
+    }
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await client.query('SELECT pg_advisory_xact_lock(hashtext($1))', [
+        `${authReq.org.id}:${parsed.data.resource_type}:${parsed.data.resource_key}`,
+      ]);
+
+      await expireAndLogWorkClaims(client, authReq.org.id);
+
+      if (agent.enforcement_mode === 'observe') {
+        const existingResource = await client.query<WorkResource>(
+          `SELECT *
+           FROM work_resources
+           WHERE org_id = $1
+             AND resource_type = $2
+             AND resource_key = $3
+           LIMIT 1`,
+          [authReq.org.id, parsed.data.resource_type, parsed.data.resource_key],
+        );
+        const resource = existingResource.rows[0] ?? null;
+        const result = resource
+          ? await previewWorkClaim(client, {
+              org_id: authReq.org.id,
+              agent_id: parsed.data.agent_id,
+              resource_id: resource.id,
+              start_at: startAt,
+              end_at: endAt,
+              reason: parsed.data.reason,
+              metadata: automationMetadata(parsed.data.metadata),
+            })
+          : {
+              status: 'available' as const,
+              winning_claim_id: null,
+              losing_claim_ids: [],
+              rule_applied: 'none' as const,
+              suggested_retry_at: null,
+            };
+
+        const blocking = result.winning_claim_id
+          ? await client.query(
+              `SELECT
+                 work_claims.*,
+                 work_resources.resource_type,
+                 work_resources.resource_key,
+                 work_resources.label AS resource_label,
+                 agents.name AS agent_name
+               FROM work_claims
+               JOIN work_resources ON work_resources.id = work_claims.resource_id
+               JOIN agents ON agents.id = work_claims.agent_id
+               WHERE work_claims.id = $1`,
+              [result.winning_claim_id],
+            )
+          : { rows: [] };
+        const wouldHaveBlocked = result.status === 'would_lose';
+        const publicWorkResource = publicResource(resource, parsed.data);
+
+        await insertWorkEvent({
+          db: client,
+          event_type: wouldHaveBlocked ? 'shadow_blocked' : 'shadow_allowed',
+          agent_id: parsed.data.agent_id,
+          org_id: authReq.org.id,
+          resource_id: resource?.id ?? null,
+          conflicting_claim_id: result.winning_claim_id,
+          rule_applied: result.rule_applied,
+          metadata: {
+            source: 'shadow_mode',
+            enforcement_mode: 'observe',
+            resource_type: parsed.data.resource_type,
+            resource_key: parsed.data.resource_key,
+            start_at: startAt.toISOString(),
+            end_at: endAt.toISOString(),
+            would_have_blocked: wouldHaveBlocked,
+            idempotency_key_present: Boolean(idempotency.key),
+          },
+          ...actor,
+        });
+
+        await client.query('COMMIT');
+        await logActivity({
+          org_id: authReq.org.id,
+          agent_id: parsed.data.agent_id,
+          activity_type: wouldHaveBlocked ? 'automation_shadow_blocked' : 'automation_shadow_allowed',
+          endpoint: '/v1/work/run/start',
+          method: 'POST',
+          status_code: 200,
+          status: 'success',
+          ...actor,
+          client_name: parsed.data.client_name ?? null,
+          latency_ms: durationSince(startedAt),
+          metadata: {
+            source: 'shadow_mode',
+            enforcement_mode: 'observe',
+            resource_type: parsed.data.resource_type,
+            resource_key: parsed.data.resource_key,
+            winning_claim_id: result.winning_claim_id,
+            would_have_blocked: wouldHaveBlocked,
+          },
+        });
+        return res.status(200).json({
+          action: 'proceed',
+          claim: null,
+          resource: publicWorkResource,
+          reason: wouldHaveBlocked
+            ? 'Observe-only mode would have skipped this run, but allowed it to proceed'
+            : 'Observe-only mode allowed this run; no active conflict was found',
+          retry_after: null,
+          blocking_claim: null,
+          status: result.status,
+          winning_claim_id: result.winning_claim_id,
+          losing_claim_ids: result.losing_claim_ids,
+          rule_applied: result.rule_applied,
+          explanation: explainWorkResult(result.status, parsed.data.resource_key),
+          suggested_retry_at: result.suggested_retry_at?.toISOString() ?? null,
+          shadow_mode: true,
+          would_have_blocked: wouldHaveBlocked,
+          shadow_decision: wouldHaveBlocked
+            ? {
+                action: 'skip_run',
+                reason: explainWorkResult(result.status, parsed.data.resource_key),
+                retry_after: result.suggested_retry_at?.toISOString() ?? null,
+                blocking_claim: blocking.rows[0] ? publicClaim(blocking.rows[0]) : null,
+                rule_applied: result.rule_applied,
+                winning_claim_id: result.winning_claim_id,
+              }
+            : null,
+        });
+      }
+
+      if (idempotency.key) {
+        const existing = await client.query(
+          `SELECT
+             work_claims.*,
+             work_resources.resource_type,
+             work_resources.resource_key,
+             work_resources.label AS resource_label
+           FROM work_claims
+           JOIN work_resources ON work_resources.id = work_claims.resource_id
+           WHERE work_claims.org_id = $1
+             AND work_claims.agent_id = $2
+             AND work_claims.idempotency_key = $3
+           LIMIT 1`,
+          [authReq.org.id, parsed.data.agent_id, idempotency.key],
+        );
+
+        if (existing.rows.length > 0) {
+          await client.query('COMMIT');
+          const existingClaim = existing.rows[0];
+          if (existingClaim.status === 'active' && new Date(existingClaim.expires_at) >= new Date()) {
+            await logActivity({
+              org_id: authReq.org.id,
+              agent_id: parsed.data.agent_id,
+              activity_type: 'automation_start',
+              endpoint: '/v1/work/run/start',
+              method: 'POST',
+              status_code: 200,
+              status: 'success',
+              ...actor,
+              client_name: parsed.data.client_name ?? null,
+              latency_ms: durationSince(startedAt),
+              metadata: {
+                source: 'automation_guardrail',
+                claim_id: existingClaim.id,
+                idempotent_replay: true,
+                resource_type: existingClaim.resource_type,
+                resource_key: existingClaim.resource_key,
+              },
+            });
+            return res.status(200).json({
+              action: 'proceed',
+              claim: publicClaim(existingClaim),
+              resource: {
+                id: existingClaim.resource_id,
+                resource_type: existingClaim.resource_type,
+                resource_key: existingClaim.resource_key,
+                label: existingClaim.resource_label,
+              },
+              reason: 'Existing active work slot returned for idempotent retry',
+              retry_after: null,
+              blocking_claim: null,
+              status: 'available',
+              superseded_claim_ids: [],
+              idempotent_replay: true,
+              extend_url: '/v1/work/run/extend',
+              finish_url: '/v1/work/run/finish',
+            });
+          }
+
+          await logActivity({
+            org_id: authReq.org.id,
+            agent_id: parsed.data.agent_id,
+            activity_type: 'automation_error',
+            endpoint: '/v1/work/run/start',
+            method: 'POST',
+            status_code: 409,
+            status: 'error',
+            ...actor,
+            client_name: parsed.data.client_name ?? null,
+            latency_ms: durationSince(startedAt),
+            error_code: 'idempotency_key_reused',
+            error_message: 'Idempotency-Key was already used for an inactive work claim',
+            metadata: {
+              source: 'automation_guardrail',
+              previous_claim_id: existingClaim.id,
+              previous_status: existingClaim.status,
+            },
+          });
+          return res.status(409).json({
+            error: 'idempotency_key_reused',
+            message: 'Idempotency-Key was already used for an inactive work claim',
+            previous_claim_id: existingClaim.id,
+            previous_status: existingClaim.status,
+          });
+        }
+      }
+
+      const existingResource = await client.query(
+        `SELECT id
+         FROM work_resources
+         WHERE org_id = $1
+           AND resource_type = $2
+           AND resource_key = $3
+         LIMIT 1`,
+        [authReq.org.id, parsed.data.resource_type, parsed.data.resource_key],
+      );
+      if (existingResource.rows.length === 0) {
+        const resourceAllowed = await enforcePlanLimit({
+          org_id: authReq.org.id,
+          limit_type: 'protected_resources',
+          db: client,
+          res,
+        });
+        if (!resourceAllowed) {
+          await client.query('ROLLBACK');
+          return;
+        }
+        const usage = await getPlanUsage(authReq.org.id, client);
+        const claimAllowed = await enforcePlanLimit({
+          org_id: authReq.org.id,
+          limit_type: 'active_work_claims',
+          increment: 1,
+          usage_override: usage.active_work_claims,
+          db: client,
+          res,
+        });
+        if (!claimAllowed) {
+          await client.query('ROLLBACK');
+          return;
+        }
+      }
+
+      const resource = await upsertWorkResource(client, {
+        org_id: authReq.org.id,
+        resource_type: parsed.data.resource_type,
+        resource_key: parsed.data.resource_key,
+        label: parsed.data.label,
+      });
+      const result = await previewWorkClaim(client, {
+        org_id: authReq.org.id,
+        agent_id: parsed.data.agent_id,
+        resource_id: resource.id,
+        start_at: startAt,
+        end_at: endAt,
+        reason: parsed.data.reason,
+        metadata: automationMetadata(parsed.data.metadata),
+      });
+
+      if (result.status === 'would_lose') {
+        const blocking = result.winning_claim_id
+          ? await client.query(
+              `SELECT
+                 work_claims.*,
+                 work_resources.resource_type,
+                 work_resources.resource_key,
+                 work_resources.label AS resource_label,
+                 agents.name AS agent_name
+               FROM work_claims
+               JOIN work_resources ON work_resources.id = work_claims.resource_id
+               JOIN agents ON agents.id = work_claims.agent_id
+               WHERE work_claims.id = $1`,
+              [result.winning_claim_id],
+            )
+          : { rows: [] };
+        await insertWorkEvent({
+          db: client,
+          event_type: 'blocked',
+          agent_id: parsed.data.agent_id,
+          org_id: authReq.org.id,
+          resource_id: resource.id,
+          conflicting_claim_id: result.winning_claim_id,
+          rule_applied: result.rule_applied,
+          metadata: {
+            source: 'automation_guardrail',
+            resource_type: resource.resource_type,
+            resource_key: resource.resource_key,
+            start_at: startAt.toISOString(),
+            end_at: endAt.toISOString(),
+          },
+          ...actor,
+        });
+        await client.query('COMMIT');
+        await logActivity({
+          org_id: authReq.org.id,
+          agent_id: parsed.data.agent_id,
+          activity_type: 'automation_skip',
+          endpoint: '/v1/work/run/start',
+          method: 'POST',
+          status_code: 200,
+          status: 'success',
+          ...actor,
+          client_name: parsed.data.client_name ?? null,
+          latency_ms: durationSince(startedAt),
+          metadata: {
+            source: 'automation_guardrail',
+            resource_type: resource.resource_type,
+            resource_key: resource.resource_key,
+            winning_claim_id: result.winning_claim_id,
+          },
+        });
+        return res.status(200).json({
+          action: 'skip_run',
+          claim: null,
+          resource,
+          reason: explainWorkResult(result.status, resource.resource_key),
+          retry_after: result.suggested_retry_at?.toISOString() ?? null,
+          blocking_claim: blocking.rows[0] ? publicClaim(blocking.rows[0]) : null,
+          status: result.status,
+          winning_claim_id: result.winning_claim_id,
+          losing_claim_ids: result.losing_claim_ids,
+          rule_applied: result.rule_applied,
+          explanation: explainWorkResult(result.status, resource.resource_key),
+          suggested_retry_at: result.suggested_retry_at?.toISOString() ?? null,
+        });
+      }
+
+      const netActiveIncrease =
+        result.status === 'would_win' ? Math.max(0, 1 - result.losing_claim_ids.length) : 1;
+      if (existingResource.rows.length > 0 && netActiveIncrease > 0) {
+        const usage = await getPlanUsage(authReq.org.id, client);
+        const claimAllowed = await enforcePlanLimit({
+          org_id: authReq.org.id,
+          limit_type: 'active_work_claims',
+          increment: netActiveIncrease,
+          usage_override: usage.active_work_claims,
+          db: client,
+          res,
+        });
+        if (!claimAllowed) {
+          await client.query('ROLLBACK');
+          return;
+        }
+      }
+
+      if (result.losing_claim_ids.length > 0) {
+        await client.query(
+          `UPDATE work_claims
+           SET status = 'superseded'
+           WHERE id = ANY($1::uuid[])
+             AND org_id = $2`,
+          [result.losing_claim_ids, authReq.org.id],
+        );
+      }
+
+      const created = await client.query<WorkClaim>(
+        `INSERT INTO work_claims (
+           org_id,
+           agent_id,
+           resource_id,
+           start_at,
+           end_at,
+           status,
+           reason,
+           metadata,
+           expires_at,
+           last_renewed_at,
+           renewal_count,
+           idempotency_key
+         )
+         VALUES ($1, $2, $3, $4, $5, 'active', $6, $7, $8, NOW(), 0, $9)
+         RETURNING *`,
+        [
+          authReq.org.id,
+          parsed.data.agent_id,
+          resource.id,
+          startAt,
+          endAt,
+          parsed.data.reason ?? null,
+          JSON.stringify(automationMetadata(parsed.data.metadata)),
+          initialWorkExpiresAt(startAt, endAt),
+          idempotency.key,
+        ],
+      );
+
+      await insertWorkEvent({
+        db: client,
+        claim_id: created.rows[0].id,
+        event_type: 'created',
+        agent_id: parsed.data.agent_id,
+        org_id: authReq.org.id,
+        resource_id: resource.id,
+        rule_applied: result.rule_applied,
+        metadata: {
+          source: 'automation_guardrail',
+          resource_type: resource.resource_type,
+          resource_key: resource.resource_key,
+          start_at: startAt.toISOString(),
+          end_at: endAt.toISOString(),
+        },
+        ...actor,
+      });
+
+      for (const losingClaimId of result.losing_claim_ids) {
+        await insertWorkEvent({
+          db: client,
+          claim_id: losingClaimId,
+          event_type: 'superseded',
+          agent_id: parsed.data.agent_id,
+          org_id: authReq.org.id,
+          resource_id: resource.id,
+          conflicting_claim_id: created.rows[0].id,
+          rule_applied: result.rule_applied,
+          metadata: { source: 'automation_guardrail', superseded_by_claim_id: created.rows[0].id },
+          ...actor,
+        });
+      }
+
+      await client.query('COMMIT');
+      await logActivity({
+        org_id: authReq.org.id,
+        agent_id: parsed.data.agent_id,
+        activity_type: 'automation_start',
+        endpoint: '/v1/work/run/start',
+        method: 'POST',
+        status_code: 200,
+        status: 'success',
+        ...actor,
+        client_name: parsed.data.client_name ?? null,
+        latency_ms: durationSince(startedAt),
+        metadata: {
+          source: 'automation_guardrail',
+          claim_id: created.rows[0].id,
+          resource_type: resource.resource_type,
+          resource_key: resource.resource_key,
+          superseded_claims: result.losing_claim_ids,
+        },
+      });
+      return res.status(200).json({
+        action: 'proceed',
+        claim: publicClaim(created.rows[0] as unknown as Record<string, unknown>),
+        resource,
+        reason: 'Work slot claimed',
+        retry_after: null,
+        blocking_claim: null,
+        status: result.status,
+        superseded_claim_ids: result.losing_claim_ids,
+        idempotent_replay: false,
+        extend_url: '/v1/work/run/extend',
+        finish_url: '/v1/work/run/finish',
+      });
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  } catch (err) {
+    log.error('[work] automation start error', { error: (err as Error).message });
+    await logActivity({
+      org_id: authReq.org.id,
+      agent_id: parsed.data.agent_id,
+      activity_type: 'automation_error',
+      endpoint: '/v1/work/run/start',
+      method: 'POST',
+      status_code: 500,
+      status: 'error',
+      ...actor,
+      client_name: parsed.data.client_name ?? null,
+      latency_ms: durationSince(startedAt),
+      error_code: 'internal_error',
+      error_message: 'An unexpected error occurred',
+      metadata: { source: 'automation_guardrail' },
+    });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/work/run/extend', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const parsed = RunExtendWorkClaimSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  const actor = actorFromAuth(authReq);
+
+  try {
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await expireAndLogWorkClaims(client, authReq.org.id);
+
+      const claim = await client.query<WorkClaim>(
+        `SELECT *
+         FROM work_claims
+         WHERE id = $1
+           AND org_id = $2
+           AND status = 'active'
+           AND ($3::uuid IS NULL OR agent_id = $3)
+         FOR UPDATE`,
+        [parsed.data.claim_id, authReq.org.id, isAgentAuth(authReq) ? authReq.agent.id : null],
+      );
+
+      if (claim.rows.length === 0) {
+        await client.query('ROLLBACK');
+        return res.status(404).json({ error: 'claim_not_found', message: 'Active work claim not found' });
+      }
+
+      const current = claim.rows[0];
+      const maxExpires = maxWorkExpiresAt(current.start_at);
+      if (current.expires_at >= maxExpires) {
+        await client.query('ROLLBACK');
+        await logActivity({
+          org_id: authReq.org.id,
+          agent_id: current.agent_id,
+          activity_type: 'automation_error',
+          endpoint: '/v1/work/run/extend',
+          method: 'POST',
+          status_code: 409,
+          status: 'error',
+          ...actor,
+          client_name: parsed.data.client_name ?? null,
+          latency_ms: durationSince(startedAt),
+          error_code: 'max_lock_reached',
+          error_message: 'Work claim is already at the maximum 4 hour lock window',
+          metadata: { source: 'automation_guardrail', claim_id: current.id, max_expires_at: maxExpires.toISOString() },
+        });
+        return res.status(409).json({
+          error: 'max_lock_reached',
+          message: `Work claims cannot be extended beyond ${MAX_WORK_LOCK_MINUTES} minutes from start_at`,
+          max_expires_at: maxExpires.toISOString(),
+        });
+      }
+
+      const requested = new Date(Date.now() + parsed.data.duration_minutes * 60_000);
+      const capped = requested < maxExpires ? requested : maxExpires;
+      const nextExpires = capped > current.expires_at ? capped : current.expires_at;
+
+      const updated = await client.query<WorkClaim>(
+        `UPDATE work_claims
+         SET expires_at = $1,
+             last_renewed_at = NOW(),
+             renewal_count = renewal_count + 1
+         WHERE id = $2
+         RETURNING *`,
+        [nextExpires, current.id],
+      );
+
+      await insertWorkEvent({
+        db: client,
+        claim_id: updated.rows[0].id,
+        event_type: 'extended',
+        agent_id: updated.rows[0].agent_id,
+        org_id: authReq.org.id,
+        resource_id: updated.rows[0].resource_id,
+        metadata: {
+          source: 'automation_guardrail',
+          previous_expires_at: current.expires_at.toISOString(),
+          expires_at: updated.rows[0].expires_at.toISOString(),
+          max_expires_at: maxExpires.toISOString(),
+          duration_minutes: parsed.data.duration_minutes,
+        },
+        ...actor,
+      });
+
+      await client.query('COMMIT');
+      await logActivity({
+        org_id: authReq.org.id,
+        agent_id: updated.rows[0].agent_id,
+        activity_type: 'automation_extend',
+        endpoint: '/v1/work/run/extend',
+        method: 'POST',
+        status_code: 200,
+        status: 'success',
+        ...actor,
+        client_name: parsed.data.client_name ?? null,
+        latency_ms: durationSince(startedAt),
+        metadata: {
+          source: 'automation_guardrail',
+          claim_id: updated.rows[0].id,
+          expires_at: updated.rows[0].expires_at.toISOString(),
+          renewal_count: updated.rows[0].renewal_count,
+        },
+      });
+
+      return res.json({
+        action: 'extended',
+        claim: publicClaim(updated.rows[0] as unknown as Record<string, unknown>),
+        expires_at: updated.rows[0].expires_at,
+        seconds_until_expiry: secondsUntilExpiry(updated.rows[0].expires_at),
+        last_renewed_at: updated.rows[0].last_renewed_at,
+        renewal_count: updated.rows[0].renewal_count,
+        max_expires_at: maxExpires.toISOString(),
+      });
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  } catch (err) {
+    log.error('[work] automation extend error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/work/run/finish', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const parsed = RunFinishWorkClaimSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  const actor = actorFromAuth(authReq);
+
+  try {
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    await expireAndLogWorkClaims(pool, authReq.org.id);
+    const updated = await pool.query<WorkClaim>(
+      `UPDATE work_claims
+       SET status = 'released'
+       WHERE id = $1
+         AND org_id = $2
+         AND status = 'active'
+         AND ($3::uuid IS NULL OR agent_id = $3)
+       RETURNING *`,
+      [parsed.data.claim_id, authReq.org.id, isAgentAuth(authReq) ? authReq.agent.id : null],
+    );
+
+    if (updated.rows.length === 0) {
+      const existing = await pool.query<WorkClaim>(
+        `SELECT *
+         FROM work_claims
+         WHERE id = $1
+           AND org_id = $2
+           AND ($3::uuid IS NULL OR agent_id = $3)
+         LIMIT 1`,
+        [parsed.data.claim_id, authReq.org.id, isAgentAuth(authReq) ? authReq.agent.id : null],
+      );
+
+      if (existing.rows.length === 0) {
+        return res.status(404).json({ error: 'claim_not_found', message: 'Work claim not found' });
+      }
+
+      await logActivity({
+        org_id: authReq.org.id,
+        agent_id: existing.rows[0].agent_id,
+        activity_type: 'automation_finish',
+        endpoint: '/v1/work/run/finish',
+        method: 'POST',
+        status_code: 200,
+        status: 'success',
+        ...actor,
+        client_name: parsed.data.client_name ?? null,
+        latency_ms: durationSince(startedAt),
+        metadata: {
+          source: 'automation_guardrail',
+          claim_id: existing.rows[0].id,
+          already_finished: true,
+          previous_status: existing.rows[0].status,
+          outcome: parsed.data.outcome ?? null,
+        },
+      });
+
+      return res.json({
+        action: 'already_finished',
+        claim: publicClaim(existing.rows[0] as unknown as Record<string, unknown>),
+      });
+    }
+
+    await insertWorkEvent({
+      claim_id: updated.rows[0].id,
+      event_type: 'released',
+      agent_id: updated.rows[0].agent_id,
+      org_id: authReq.org.id,
+      resource_id: updated.rows[0].resource_id,
+      metadata: automationMetadata({
+        outcome: parsed.data.outcome ?? null,
+        reason: parsed.data.reason ?? null,
+        ...(parsed.data.metadata ?? {}),
+      }),
+      ...actor,
+    });
+    await logActivity({
+      org_id: authReq.org.id,
+      agent_id: updated.rows[0].agent_id,
+      activity_type: 'automation_finish',
+      endpoint: '/v1/work/run/finish',
+      method: 'POST',
+      status_code: 200,
+      status: 'success',
+      ...actor,
+      client_name: parsed.data.client_name ?? null,
+      latency_ms: durationSince(startedAt),
+      metadata: {
+        source: 'automation_guardrail',
+        claim_id: updated.rows[0].id,
+        outcome: parsed.data.outcome ?? null,
+      },
+    });
+
+    return res.json({
+      action: 'finished',
+      claim: publicClaim(updated.rows[0] as unknown as Record<string, unknown>),
+    });
+  } catch (err) {
+    log.error('[work] automation finish error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.post('/work/claims/:claim_id/extend', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const parsed = ExtendWorkClaimSchema.safeParse(req.body);
+  if (!parsed.success) {
+    return res.status(422).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const claimId = z.string().uuid().safeParse(req.params.claim_id);
+  if (!claimId.success) {
+    return res.status(400).json({ error: 'validation_error', message: 'Invalid claim id' });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  const actor = actorFromAuth(authReq);
+
+  try {
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    const client = await pool.connect();
+    try {
+      await client.query('BEGIN');
+      await expireAndLogWorkClaims(client, authReq.org.id);
+
+      const claim = await client.query<WorkClaim>(
+        `SELECT *
+         FROM work_claims
+         WHERE id = $1
+           AND org_id = $2
+           AND status = 'active'
+           AND ($3::uuid IS NULL OR agent_id = $3)
+         FOR UPDATE`,
+        [claimId.data, authReq.org.id, isAgentAuth(authReq) ? authReq.agent.id : null],
+      );
+
+      if (claim.rows.length === 0) {
+        await client.query('ROLLBACK');
+        return res.status(404).json({ error: 'claim_not_found', message: 'Active work claim not found' });
+      }
+
+      const current = claim.rows[0];
+      const maxExpires = maxWorkExpiresAt(current.start_at);
+      if (current.expires_at >= maxExpires) {
+        await client.query('ROLLBACK');
+        await logActivity({
+          org_id: authReq.org.id,
+          agent_id: current.agent_id,
+          activity_type: 'work_extend',
+          endpoint: '/v1/work/claims/:claim_id/extend',
+          method: 'POST',
+          status_code: 409,
+          status: 'error',
+          ...actor,
+          latency_ms: durationSince(startedAt),
+          error_code: 'max_lock_reached',
+          error_message: 'Work claim is already at the maximum 4 hour lock window',
+          metadata: { claim_id: current.id, max_expires_at: maxExpires.toISOString() },
+        });
+        return res.status(409).json({
+          error: 'max_lock_reached',
+          message: `Work claims cannot be extended beyond ${MAX_WORK_LOCK_MINUTES} minutes from start_at`,
+          max_expires_at: maxExpires.toISOString(),
+        });
+      }
+
+      const requested = new Date(Date.now() + parsed.data.duration_minutes * 60_000);
+      const capped = requested < maxExpires ? requested : maxExpires;
+      const nextExpires = capped > current.expires_at ? capped : current.expires_at;
+
+      const updated = await client.query<WorkClaim>(
+        `UPDATE work_claims
+         SET expires_at = $1,
+             last_renewed_at = NOW(),
+             renewal_count = renewal_count + 1
+         WHERE id = $2
+         RETURNING *`,
+        [nextExpires, current.id],
+      );
+
+      await insertWorkEvent({
+        db: client,
+        claim_id: updated.rows[0].id,
+        event_type: 'extended',
+        agent_id: updated.rows[0].agent_id,
+        org_id: authReq.org.id,
+        resource_id: updated.rows[0].resource_id,
+        metadata: {
+          previous_expires_at: current.expires_at.toISOString(),
+          expires_at: updated.rows[0].expires_at.toISOString(),
+          max_expires_at: maxExpires.toISOString(),
+          duration_minutes: parsed.data.duration_minutes,
+        },
+        ...actor,
+      });
+
+      await client.query('COMMIT');
+      await logActivity({
+        org_id: authReq.org.id,
+        agent_id: updated.rows[0].agent_id,
+        activity_type: 'work_extend',
+        endpoint: '/v1/work/claims/:claim_id/extend',
+        method: 'POST',
+        status_code: 200,
+        status: 'success',
+        ...actor,
+        latency_ms: durationSince(startedAt),
+        metadata: {
+          claim_id: updated.rows[0].id,
+          expires_at: updated.rows[0].expires_at.toISOString(),
+          renewal_count: updated.rows[0].renewal_count,
+        },
+      });
+
+      return res.json({
+        claim: publicClaim(updated.rows[0] as unknown as Record<string, unknown>),
+        expires_at: updated.rows[0].expires_at,
+        last_renewed_at: updated.rows[0].last_renewed_at,
+        renewal_count: updated.rows[0].renewal_count,
+        max_expires_at: maxExpires.toISOString(),
+      });
+    } catch (err) {
+      await client.query('ROLLBACK');
+      throw err;
+    } finally {
+      client.release();
+    }
+  } catch (err) {
+    log.error('[work] extend error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.delete('/work/claims/:claim_id', requireWorkspaceOrAgent, async (req, res) => {
+  const startedAt = Date.now();
+  const authReq = req as AnyAuthenticatedRequest;
+  const actor = actorFromAuth(authReq);
+
+  try {
+    if (!(await enforcePlanLimit({
+      org_id: authReq.org.id,
+      limit_type: 'api_calls_month',
+      res,
+    }))) {
+      return;
+    }
+
+    await expireAndLogWorkClaims(pool, authReq.org.id);
+    const updated = await pool.query<WorkClaim>(
+      `UPDATE work_claims
+       SET status = 'released'
+       WHERE id = $1
+         AND org_id = $2
+         AND status = 'active'
+         AND ($3::uuid IS NULL OR agent_id = $3)
+       RETURNING *`,
+      [req.params.claim_id, authReq.org.id, isAgentAuth(authReq) ? authReq.agent.id : null],
+    );
+
+    if (updated.rows.length === 0) {
+      return res.status(404).json({ error: 'claim_not_found', message: 'Active work claim not found' });
+    }
+
+    await insertWorkEvent({
+      claim_id: updated.rows[0].id,
+      event_type: 'released',
+      agent_id: updated.rows[0].agent_id,
+      org_id: authReq.org.id,
+      resource_id: updated.rows[0].resource_id,
+      ...actor,
+    });
+    await logActivity({
+      org_id: authReq.org.id,
+      agent_id: updated.rows[0].agent_id,
+      activity_type: 'work_release',
+      endpoint: '/v1/work/claims/:claim_id',
+      method: 'DELETE',
+      status_code: 200,
+      status: 'success',
+      ...actor,
+      latency_ms: durationSince(startedAt),
+      metadata: { claim_id: updated.rows[0].id },
+    });
+
+    return res.json({ claim: publicClaim(updated.rows[0] as unknown as Record<string, unknown>) });
+  } catch (err) {
+    log.error('[work] release error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.get('/work/claims', requireWorkspaceOrAgent, async (req, res) => {
+  const parsed = WorkClaimsQuerySchema.safeParse(req.query);
+  if (!parsed.success) {
+    return res.status(400).json({ error: 'validation_error', details: parsed.error.flatten() });
+  }
+
+  const authReq = req as AnyAuthenticatedRequest;
+  if (isAgentAuth(authReq) && parsed.data.agent_id && parsed.data.agent_id !== authReq.agent.id) {
+    return res.status(403).json({ error: 'forbidden', message: 'Agent key cannot list another agent claims' });
+  }
+
+  try {
+    await expireAndLogWorkClaims(pool, authReq.org.id);
+
+    const effectiveAgentId = isAgentAuth(authReq) ? authReq.agent.id : parsed.data.agent_id;
+    const result = await pool.query(
+      `SELECT
+         work_claims.*,
+         work_resources.resource_type,
+         work_resources.resource_key,
+         work_resources.label AS resource_label,
+         agents.name AS agent_name
+       FROM work_claims
+       JOIN work_resources ON work_resources.id = work_claims.resource_id
+       JOIN agents ON agents.id = work_claims.agent_id
+       WHERE work_claims.org_id = $1
+         AND work_claims.status = $2
+         AND ($3::uuid IS NULL OR work_claims.agent_id = $3)
+         AND ($4::text IS NULL OR work_resources.resource_type = $4)
+         AND ($5::text IS NULL OR work_resources.resource_key = $5)
+       ORDER BY work_claims.created_at DESC
+       LIMIT $6`,
+      [
+        authReq.org.id,
+        parsed.data.status,
+        effectiveAgentId ?? null,
+        parsed.data.resource_type ?? null,
+        parsed.data.resource_key ?? null,
+        parsed.data.limit,
+      ],
+    );
+
+    return res.json({ claims: result.rows.map((row) => publicClaim(row)) });
+  } catch (err) {
+    log.error('[work] list error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+router.get('/work/resources', requireWorkspaceOrAgent, async (req, res) => {
+  const authReq = req as AnyAuthenticatedRequest;
+
+  try {
+    await expireAndLogWorkClaims(pool, authReq.org.id);
+    const result = await pool.query(
+      `SELECT
+         work_resources.*,
+         COUNT(work_claims.id) FILTER (WHERE work_claims.status = 'active' AND work_claims.expires_at >= NOW())::int AS active_claims_count,
+         MAX(work_claims.created_at) AS last_claim_at
+       FROM work_resources
+       LEFT JOIN work_claims ON work_claims.resource_id = work_resources.id
+       WHERE work_resources.org_id = $1
+       GROUP BY work_resources.id
+       ORDER BY COALESCE(MAX(work_claims.created_at), work_resources.created_at) DESC`,
+      [authReq.org.id],
+    );
+
+    return res.json({ resources: result.rows });
+  } catch (err) {
+    log.error('[work] resources error', { error: (err as Error).message });
+    return res.status(500).json({ error: 'internal_error', message: 'An unexpected error occurred' });
+  }
+});
+
+export default router;