@cgh567/agent 2.4.2 → 2.4.3

package/daemon/helios-api.js

@@ -1,6 +1,6 @@
 'use strict';
 /**
- * helios-api.js — REST API for Helios daemon (port 9091)
+ * helios-api.js — REST API for Helios daemon
  *
  * Endpoints:
  *   GET  /api/health
@@ -48,8 +48,8 @@ const TRANSCRIPTS_DIR = path.join(__dirname, 'transcripts');
 const _transcriptStore = new TranscriptStore(TRANSCRIPTS_DIR);
 const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, PATCH, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Accept',
+  'Access-Control-Allow-Methods': 'GET, POST, PATCH, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization',
 };
 
 // ── Logging ────────────────────────────────────────────────────────────────────────────────
@@ -61,6 +61,14 @@ function log(level, msg, extra) {
   else process.stdout.write(JSON.stringify(entry) + '\n');
 }
 
+function mirrorHboStore(label, write) {
+  try {
+    if (typeof write === 'function') write();
+  } catch (err) {
+    log('warn', `hbo-core mirror failed: ${label}`, { error: err.message });
+  }
+}
+
 // ── SSE Client Registry ───────────────────────────────────────────────────────
 
 const sseClients = new Set();
@@ -260,6 +268,7 @@ async function handleHealth(req, res, ctx) {
   const { tickCount, modules } = ctx;
   jsonResponse(res, 200, {
     status: 'ok',
+    port: ctx.actualBoundPort ?? ctx.apiPort ?? null,
     tick: tickCount ?? 0,
     modules: modules ?? [],
     timestamp: new Date().toISOString(),
@@ -374,13 +383,58 @@ async function handleCreateTask(req, res, ctx) {
   const cid = ctx.cid;
 
   const body = await parseBody(req);
-  const { title, assigneeAgentId, priority, body: taskBody } = body;
+  const { title, assigneeAgentId, priority, body: taskBody, executionPolicy } = body;
 
   if (!title || typeof title !== 'string' || title.trim() === '') {
     jsonResponse(res, 400, { error: 'title is required and must be a non-empty string' });
     return;
   }
 
+  // P4-02: validate executionPolicy if provided
+  let validatedPolicyJson = null;
+  if (executionPolicy !== undefined) {
+    if (!executionPolicy || typeof executionPolicy !== 'object' || !Array.isArray(executionPolicy.stages)) {
+      jsonResponse(res, 400, { error: 'executionPolicy must have a stages array' });
+      return;
+    }
+    if (executionPolicy.stages.length === 0) {
+      jsonResponse(res, 400, { error: 'executionPolicy.stages must not be empty' });
+      return;
+    }
+    for (const stage of executionPolicy.stages) {
+      if (!stage.type || !['review', 'approval'].includes(stage.type)) {
+        jsonResponse(res, 400, { error: `stage.type must be 'review' or 'approval', got: ${stage.type}` });
+        return;
+      }
+      if (!Array.isArray(stage.participants) || stage.participants.length === 0) {
+        jsonResponse(res, 400, { error: 'each stage must have a non-empty participants array' });
+        return;
+      }
+    }
+    // M-1 fix: validate ALL participants in a single batched query instead of N sequential queries
+    const allParticipantIds = [...new Set(
+      executionPolicy.stages.flatMap(s => s.participants.map(p => String(p)))
+    )];
+    const agentCheckResult = await mgQuery(
+      `MATCH (a:BusinessAgent {companyId: $cid}) WHERE a.id IN $pids RETURN collect(a.id) AS found`,
+      { cid, pids: allParticipantIds }
+    );
+    const foundIds = new Set(
+      (parseRows(agentCheckResult)[0]?.[0] ?? parseRows(agentCheckResult)[0]?.['found'] ?? [])
+    );
+    const missingIds = allParticipantIds.filter(id => !foundIds.has(id));
+    if (missingIds.length > 0) {
+      jsonResponse(res, 400, { error: `participants not found as BusinessAgents in this company: ${missingIds.join(', ')}` });
+      return;
+    }
+    validatedPolicyJson = JSON.stringify(executionPolicy);
+  }
+
+  // P4-03: initial executionState — 'idle' when policy exists, null string otherwise
+  const initialStateJson = validatedPolicyJson
+    ? JSON.stringify({ status: 'idle', currentStageIndex: null, currentParticipant: null, returnAssignee: null, completedStageIds: [] })
+    : 'null';
+
   const taskId = `task:api:${crypto.randomUUID()}`;
   const resolvedPriority = Number.isFinite(Number(priority)) ? Number(priority) : 2;
 
@@ -394,6 +448,8 @@ async function handleCreateTask(req, res, ctx) {
          priority: toInteger($priority),
          assigneeAgentId: $assigneeAgentId,
          body: $body,
+         executionPolicyJson: $policyJson,
+         executionStateJson: $stateJson,
          createdAt: datetime()
        })`,
       {
@@ -403,11 +459,26 @@ async function handleCreateTask(req, res, ctx) {
         priority: resolvedPriority,
         assigneeAgentId: assigneeAgentId ? String(assigneeAgentId) : null,
         body: taskBody ? String(taskBody) : null,
+        policyJson: validatedPolicyJson,
+        stateJson: initialStateJson,
       }
     );
 
+    mirrorHboStore('task.create', () => hboStore.createTask?.({
+      id: taskId,
+      companyId: cid,
+      title: String(title).trim(),
+      status: 'todo',
+      priority: resolvedPriority,
+      assigneeAgentId: assigneeAgentId ? String(assigneeAgentId) : null,
+      body: taskBody ? String(taskBody) : null,
+      executionPolicyJson: validatedPolicyJson,
+      executionStateJson: initialStateJson,
+      createdAt: Date.now(),
+    }));
+
     broadcast({ type: 'task.created', taskId, status: 'todo', companyId: cid });
-    jsonResponse(res, 201, { task: { id: taskId, title, status: 'todo', priority: resolvedPriority, assigneeAgentId } });
+    jsonResponse(res, 201, { task: { id: taskId, title, status: 'todo', priority: resolvedPriority, assigneeAgentId, executionPolicyJson: validatedPolicyJson } });
   } catch (err) {
     jsonResponse(res, 500, { error: `Create failed: ${err.message}` });
   }
@@ -422,7 +493,8 @@ async function handleUpdateTask(req, res, ctx, taskId) {
   const body = await parseBody(req);
   const { status, priority } = body;
 
-  const VALID_STATUSES = new Set(['todo', 'in_progress', 'done', 'failed', 'cancelled', 'blocked', 'escalated']);
+  // P4-01: 'in_review' added — allows execution policy gate to hold a task for review
+  const VALID_STATUSES = new Set(['todo', 'in_progress', 'done', 'failed', 'cancelled', 'blocked', 'escalated', 'in_review']);
   if (status !== undefined && !VALID_STATUSES.has(status)) {
     jsonResponse(res, 400, { error: `Invalid status. Allowed: ${[...VALID_STATUSES].join(', ')}` });
     return;
@@ -438,6 +510,259 @@ async function handleUpdateTask(req, res, ctx, taskId) {
   }
 
   try {
+    // ─────────────────────────────────────────────────────────────────────────
+    // EXECUTION POLICY STATE MACHINE
+    //
+    // The state machine has three actors:
+    //   A) Original executor sets status='done' and task has an active policy
+    //      → INTERCEPT: redirect to in_review, assign to current stage reviewer
+    //   B) Reviewer (currently assigned) sets status='done' to approve
+    //      → ADVANCE: move to next stage, or if last stage, allow done
+    //   C) Reviewer sets any non-done status to reject/request changes
+    //      → CHANGES_REQUESTED: return task to original executor
+    //
+    // C-1 fix: The intercept (actor A) uses TWO queries, but the second (SET) query
+    // re-checks the WHERE condition with the expected policyJson — if policy changed
+    // between reads, the second query returns 0 rows and we return 409 (optimistic
+    // concurrency control). This correctly closes the TOCTOU window.
+    // ─────────────────────────────────────────────────────────────────────────
+
+    if (status === 'done') {
+      // Step 1: Read task's current state (fast metadata read)
+      const taskReadResult = await mgQuery(
+        `MATCH (t:Task {id: $id, companyId: $cid})
+         RETURN t.status AS taskStatus,
+                t.assigneeAgentId AS assigneeAgentId,
+                t.executionPolicyJson AS policyJson,
+                t.executionStateJson AS stateJson`,
+        { id: taskId, cid }
+      );
+      const taskReadRows = parseRows(taskReadResult);
+
+      if (taskReadRows.length > 0) {
+        const taskRow = taskReadRows[0];
+        const taskStatus     = taskRow[0] ?? taskRow['taskStatus']     ?? null;
+        const returnAssignee = taskRow[1] ?? taskRow['assigneeAgentId'] ?? null;
+        const policyJson     = taskRow[2] ?? taskRow['policyJson']     ?? null;
+        const stateJsonRaw   = taskRow[3] ?? taskRow['stateJson']      ?? 'null';
+
+        let policy, state;
+        try { policy = policyJson ? JSON.parse(policyJson) : null; } catch (_) { policy = null; }
+        try { state  = JSON.parse(stateJsonRaw); } catch (_) { state = null; }
+        if (state === null && stateJsonRaw === 'null') state = null; // explicit null string
+
+        // ── ACTOR B: Reviewer approving (task is currently in_review) ───────
+        if (taskStatus === 'in_review' && policy && state) {
+          const currentStageIdx = typeof state.currentStageIndex === 'number' ? state.currentStageIndex : 0;
+          const stages = Array.isArray(policy.stages) ? policy.stages : [];
+          const nextStageIdx = currentStageIdx + 1;
+
+          if (nextStageIdx < stages.length) {
+            // Advance to next stage (multi-stage full advancement — C-4 full)
+            const nextStage = stages[nextStageIdx];
+            const nextParticipant = nextStage?.participants?.[0] ?? null;
+            if (nextParticipant) {
+              const newState = JSON.stringify({
+                status: 'pending',
+                currentStageIndex: nextStageIdx,
+                currentParticipant: nextParticipant,
+                returnAssignee: state.returnAssignee,
+                completedStageIds: [...(state.completedStageIds ?? []), `stage:${currentStageIdx}`],
+              });
+              // Atomic: re-check we're still in_review before advancing
+              const advanceResult = await mgQuery(
+                `MATCH (t:Task {id: $id, companyId: $cid})
+                 WHERE t.status = 'in_review' AND t.executionPolicyJson = $expectedPolicy
+                 SET t.executionStateJson = $stateJson,
+                     t.assigneeAgentId = $nextReviewer,
+                     t.updatedAt = datetime()
+                 RETURN t.id`,
+                { id: taskId, cid, expectedPolicy: policyJson, stateJson: newState, nextReviewer: nextParticipant }
+              );
+              if (parseRows(advanceResult).length === 0) {
+                jsonResponse(res, 409, { error: 'Concurrent update conflict' });
+                return;
+              }
+              mgQuery(
+                `MATCH (a:BusinessAgent {id: $agentId, companyId: $cid, status: 'active'})
+                 OPTIONAL MATCH (existing:AgentReadySignal {agentId: $agentId, companyId: $cid, status: 'pending'})
+                 WITH a, existing WHERE existing IS NULL
+                 CREATE (s:AgentReadySignal {id: $sigId, agentId: $agentId, companyId: $cid,
+                   status: 'pending', claimedBy: null, createdAt: datetime()})`,
+                { agentId: nextParticipant, cid, sigId: `ars:advance:${taskId}:${crypto.randomUUID()}` }
+              ).catch(e => log('warn', `P4 advance AgentReadySignal failed: ${e.message}`));
+              mirrorHboStore('task.update.advance_stage', () => hboStore.updateTask?.(taskId, cid, { executionStateJson: newState, assigneeAgentId: nextParticipant }));
+              broadcast({ type: 'task.updated', taskId, status: 'in_review', companyId: cid });
+              jsonResponse(res, 200, { updated: true, taskId, advanced: true, nextStage: nextStageIdx, nextReviewer: nextParticipant });
+              return;
+            }
+          }
+
+          // All stages passed (or last stage reviewer approved) — mark completed and allow done
+          const completedState = JSON.stringify({
+            ...state,
+            status: 'completed',
+            completedStageIds: [...(state.completedStageIds ?? []), `stage:${currentStageIdx}`],
+          });
+          // Atomic: re-check still in_review before marking completed
+          const completeResult = await mgQuery(
+            `MATCH (t:Task {id: $id, companyId: $cid})
+             WHERE t.status = 'in_review' AND t.executionPolicyJson = $expectedPolicy
+             SET t.status = 'done',
+                 t.executionStateJson = $stateJson,
+                 t.updatedAt = datetime()
+             RETURN t.id`,
+            { id: taskId, cid, expectedPolicy: policyJson, stateJson: completedState }
+          );
+          if (parseRows(completeResult).length === 0) {
+            jsonResponse(res, 409, { error: 'Concurrent update conflict' });
+            return;
+          }
+          mirrorHboStore('task.update.approved', () => hboStore.updateTask?.(taskId, cid, { status: 'done', executionStateJson: completedState }));
+          broadcast({ type: 'task.updated', taskId, status: 'done', companyId: cid });
+          jsonResponse(res, 200, { updated: true, taskId, approved: true, status: 'done' });
+          return;
+        }
+
+        // ── ACTOR A: Original executor marking done with active policy ───────
+        if (taskStatus !== 'in_review' && policy) {
+          // Check if state is already completed — if so, allow done through
+          const alreadyCompleted = state && typeof state === 'object' && state.status === 'completed';
+          if (!alreadyCompleted) {
+            const firstStage = Array.isArray(policy.stages) && policy.stages.length > 0 ? policy.stages[0] : null;
+            const firstParticipant = firstStage?.participants?.[0] ?? null;
+
+            // C-2 fix: explicit guard — if no valid participant, log and fall through to done
+            if (!firstParticipant) {
+              log('warn', `P4: task ${taskId} has executionPolicy but no valid first participant — allowing done through`);
+              // fall through to standard path below
+            } else {
+              const newState = JSON.stringify({
+                status: 'pending',
+                currentStageIndex: 0,
+                currentParticipant: firstParticipant,
+                returnAssignee,          // captured returnAssignee = original executor
+                completedStageIds: [],
+              });
+              // C-1 fix: ATOMIC check+set — WHERE re-checks policyJson so a concurrent
+              // policy change causes 0 rows returned → 409 (optimistic concurrency control)
+              const atomicResult = await mgQuery(
+                `MATCH (t:Task {id: $id, companyId: $cid})
+                 WHERE t.executionPolicyJson = $expectedPolicy
+                   AND t.status <> 'in_review'
+                   AND (t.executionStateJson IS NULL OR NOT t.executionStateJson CONTAINS '"status":"completed"')
+                 SET t.status = 'in_review',
+                     t.executionStateJson = $stateJson,
+                     t.assigneeAgentId = $reviewer,
+                     t.updatedAt = datetime()
+                 RETURN t.id AS id`,
+                { id: taskId, cid, expectedPolicy: policyJson, stateJson: newState, reviewer: firstParticipant }
+              );
+              if (parseRows(atomicResult).length === 0) {
+                // Policy changed or state changed between reads — 409
+                jsonResponse(res, 409, { error: 'Concurrent update conflict — task state changed by another request' });
+                return;
+              }
+              mgQuery(
+                `MATCH (a:BusinessAgent {id: $agentId, companyId: $cid, status: 'active'})
+                 OPTIONAL MATCH (existing:AgentReadySignal {agentId: $agentId, companyId: $cid, status: 'pending'})
+                 WITH a, existing WHERE existing IS NULL
+                 CREATE (s:AgentReadySignal {id: $sigId, agentId: $agentId, companyId: $cid,
+                   status: 'pending', claimedBy: null, createdAt: datetime()})`,
+                { agentId: firstParticipant, cid, sigId: `ars:review:${taskId}:${crypto.randomUUID()}` }
+              ).catch(e => log('warn', `P4-04 AgentReadySignal emit failed: ${e.message}`));
+              mirrorHboStore('task.update.in_review', () => hboStore.updateTask?.(taskId, cid, { status: 'in_review', executionStateJson: newState, assigneeAgentId: firstParticipant }));
+              broadcast({ type: 'task.updated', taskId, status: 'in_review', companyId: cid });
+              jsonResponse(res, 200, { updated: true, taskId, intercepted: true, status: 'in_review', reviewer: firstParticipant });
+              return;
+            }
+          }
+        }
+      }
+    }
+
+    // ── ACTOR C: Reviewer rejecting / requesting changes ───────────────────
+    // C-3 fix: WHERE t.status = 'in_review' added to the SET query (prevents TOCTOU
+    // overwriting a task that was concurrently moved out of in_review by another request).
+    // FIX-H1: Check stage type to differentiate review vs approval semantics.
+    // FIX-M2: Explicit return for state=null case — no fall-through.
+    if (status !== undefined && status !== 'done') {
+      // Single atomic read+write: check in_review AND apply in one round-trip
+      // by embedding the WHERE in the SET query.
+      const reviewCheckResult = await mgQuery(
+        `MATCH (t:Task {id: $id, companyId: $cid})
+         WHERE t.status = 'in_review' AND t.executionStateJson IS NOT NULL
+         RETURN t.executionStateJson AS stateJson, t.executionPolicyJson AS policyJson`,
+        { id: taskId, cid }
+      );
+      const reviewRows = parseRows(reviewCheckResult);
+      if (reviewRows.length > 0) {
+        const reviewRow = reviewRows[0];
+        const stateJsonStr = reviewRow[0] ?? reviewRow['stateJson'] ?? 'null';
+        const policyJsonStr = reviewRow[1] ?? reviewRow['policyJson'] ?? null;
+        let state, policy;
+        try { state  = JSON.parse(stateJsonStr); } catch (_) { state = null; }
+        try { policy = policyJsonStr ? JSON.parse(policyJsonStr) : null; } catch (_) { policy = null; }
+
+        // M2 fix: if state is null (corrupt JSON), block the standard path on in_review tasks
+        if (!state) {
+          jsonResponse(res, 409, { error: 'Task is in_review but execution state is corrupt — cannot apply status change' });
+          return;
+        }
+
+        if (state.returnAssignee) {
+          const returnAssignee = state.returnAssignee;
+          const changesState = JSON.stringify({ ...state, status: 'changes_requested' });
+          // C-3 fix: WHERE t.status = 'in_review' guards against concurrent status change
+          const changesResult = await mgQuery(
+            `MATCH (t:Task {id: $id, companyId: $cid})
+             WHERE t.status = 'in_review'
+             SET t.status = 'in_progress',
+                 t.assigneeAgentId = $returnAssignee,
+                 t.executionStateJson = $stateJson,
+                 t.updatedAt = datetime()
+             RETURN t.id`,
+            { id: taskId, cid, returnAssignee, stateJson: changesState }
+          );
+          if (parseRows(changesResult).length === 0) {
+            // Concurrent write changed task out of in_review — fall through to standard path
+            // (the task is no longer in_review so standard update is correct)
+          } else {
+            mgQuery(
+              `MATCH (a:BusinessAgent {id: $agentId, companyId: $cid, status: 'active'})
+               OPTIONAL MATCH (existing:AgentReadySignal {agentId: $agentId, companyId: $cid, status: 'pending'})
+               WITH a, existing WHERE existing IS NULL
+               CREATE (s:AgentReadySignal {id: $sigId, agentId: $agentId, companyId: $cid,
+                 status: 'pending', claimedBy: null, createdAt: datetime()})`,
+              { agentId: returnAssignee, cid, sigId: `ars:changes:${taskId}:${crypto.randomUUID()}` }
+            ).catch(e => log('warn', `P4-05 AgentReadySignal emit failed: ${e.message}`));
+            mirrorHboStore('task.update.changes_requested', () => hboStore.updateTask?.(taskId, cid, { status: 'in_progress', executionStateJson: changesState, assigneeAgentId: returnAssignee }));
+            broadcast({ type: 'task.updated', taskId, status: 'in_progress', companyId: cid });
+            jsonResponse(res, 200, { updated: true, taskId, changesRequested: true, returnAssignee });
+            return;
+          }
+        } else {
+          // returnAssignee is null — escalation path (no valid return point)
+          // M2 fix: explicit return after escalation to prevent fall-through
+          const escalateResult = await mgQuery(
+            `MATCH (t:Task {id: $id, companyId: $cid})
+             WHERE t.status = 'in_review'
+             SET t.status = 'blocked', t.blockedReason = 'escalation_chain_exhausted', t.updatedAt = datetime()
+             RETURN t.id`,
+            { id: taskId, cid }
+          ).catch(() => null);
+          if (escalateResult && parseRows(escalateResult).length > 0) {
+            mirrorHboStore('task.escalation', () => hboStore.updateTask?.(taskId, cid, { status: 'blocked', blockedReason: 'escalation_chain_exhausted' }));
+            broadcast({ type: 'task.blocked', taskId, reason: 'escalation_chain_exhausted', companyId: cid });
+            jsonResponse(res, 200, { updated: true, taskId, escalated: true });
+            return;
+          }
+          // If escalate returned 0 rows, task was concurrently moved out of in_review — fall through
+        }
+      }
+    }
+
+    // Standard update path (no policy intercept applies)
     const setClauses = [];
     const params = { id: taskId, cid };
     if (status !== undefined) { setClauses.push('t.status = $status'); params.status = status; }
@@ -454,6 +779,11 @@ async function handleUpdateTask(req, res, ctx, taskId) {
       return;
     }
 
+    const storeUpdate = {};
+    if (status !== undefined) storeUpdate.status = status;
+    if (priority !== undefined) storeUpdate.priority = Number(priority);
+    mirrorHboStore('task.update', () => hboStore.updateTask?.(taskId, cid, storeUpdate));
+
     broadcast({ type: 'task.updated', taskId, ...(status !== undefined ? { status } : {}), companyId: cid });
     jsonResponse(res, 200, { updated: true, taskId });
   } catch (err) {
@@ -461,6 +791,76 @@ async function handleUpdateTask(req, res, ctx, taskId) {
   }
 }
 
+// P4-07: PATCH /api/tasks/:id/policy — set or update executionPolicy on an existing task
+async function handlePatchTaskPolicy(req, res, ctx, taskId) {
+  const { mgQuery } = ctx;
+  if (!mgQuery) { jsonResponse(res, 503, { error: 'Memgraph not connected' }); return; }
+  if (!taskId) { jsonResponse(res, 400, { error: 'Missing task ID' }); return; }
+  const cid = ctx.cid;
+
+  const body = await parseBody(req);
+  const { policy } = body;
+
+  if (!policy || typeof policy !== 'object' || !Array.isArray(policy.stages)) {
+    jsonResponse(res, 400, { error: 'policy must have a stages array' });
+    return;
+  }
+  if (policy.stages.length === 0) {
+    jsonResponse(res, 400, { error: 'policy.stages must not be empty' });
+    return;
+  }
+  for (const stage of policy.stages) {
+    if (!stage.type || !['review', 'approval'].includes(stage.type)) {
+      jsonResponse(res, 400, { error: `stage.type must be 'review' or 'approval'` });
+      return;
+    }
+    if (!Array.isArray(stage.participants) || stage.participants.length === 0) {
+      jsonResponse(res, 400, { error: 'each stage must have a non-empty participants array' });
+      return;
+    }
+  }
+  // M-1 fix: validate ALL participants in a single batched query
+  const allPolicyPids = [...new Set(policy.stages.flatMap(s => s.participants.map(p => String(p))))];
+  const policyAgentCheck = await mgQuery(
+    `MATCH (a:BusinessAgent {companyId: $cid}) WHERE a.id IN $pids RETURN collect(a.id) AS found`,
+    { cid, pids: allPolicyPids }
+  );
+  const foundPolicyAgents = new Set(
+    (parseRows(policyAgentCheck)[0]?.[0] ?? parseRows(policyAgentCheck)[0]?.['found'] ?? [])
+  );
+  const missingPolicyAgents = allPolicyPids.filter(id => !foundPolicyAgents.has(id));
+  if (missingPolicyAgents.length > 0) {
+    jsonResponse(res, 400, { error: `participants not found as BusinessAgents: ${missingPolicyAgents.join(', ')}` });
+    return;
+  }
+
+  const policyJson = JSON.stringify(policy);
+  // H-5 fix: initial executionStateJson for the policy — ensures state machine starts correctly.
+  // Without this, existing tasks with executionStateJson='null' would have returnAssignee=null
+  // when P4-04 fires, causing immediate escalation instead of returning to the original executor.
+  const initialStateJson = JSON.stringify({ status: 'idle', currentStageIndex: null, currentParticipant: null, returnAssignee: null, completedStageIds: [] });
+  try {
+    const result = await mgQuery(
+      `MATCH (t:Task {id: $id, companyId: $cid})
+       SET t.executionPolicyJson = $policyJson,
+           t.executionStateJson = $stateJson,
+           t.updatedAt = datetime()
+       RETURN t.id`,
+      { id: taskId, cid, policyJson, stateJson: initialStateJson }
+    );
+    if (parseRows(result).length === 0) {
+      jsonResponse(res, 404, { error: `Task not found: ${taskId}` });
+      return;
+    }
+    // P4-08: SQLite write-through for policy and initial state
+    mirrorHboStore('task.policy', () => hboStore.updateTask?.(taskId, cid, { executionPolicyJson: policyJson, executionStateJson: initialStateJson }));
+    broadcast({ type: 'task.policy.updated', taskId, companyId: cid });
+    jsonResponse(res, 200, { updated: true, taskId, executionPolicyJson: policyJson });
+  } catch (err) {
+    jsonResponse(res, 500, { error: `Policy update failed: ${err.message}` });
+  }
+}
+
 async function handleCancelTask(req, res, ctx, taskId) {
   const { mgQuery } = ctx;
   if (!mgQuery) { jsonResponse(res, 503, { error: 'Memgraph not connected' }); return; }
@@ -481,6 +881,7 @@ async function handleCancelTask(req, res, ctx, taskId) {
       jsonResponse(res, 404, { error: `Task not found: ${taskId}` });
       return;
     }
+    mirrorHboStore('task.cancel', () => hboStore.updateTask?.(taskId, cid, { status: 'cancelled', cancelReason: 'api_cancel' }));
     broadcast({ type: 'task.cancelled', taskId, companyId: cid });
     jsonResponse(res, 200, { cancelled: true, taskId });
   } catch (err) {
@@ -581,11 +982,12 @@ async function handleApproveApproval(req, res, ctx, approvalId) {
        RETURN a.id`,
       { id: approvalId, cid, answer }
     );
-    const rows = parseRows(approveResult);
-    if (rows.length === 0) {
-      jsonResponse(res, 409, { error: `Approval not found or not in pending state: ${approvalId}` });
-      return;
-    }
+      const rows = parseRows(approveResult);
+      if (rows.length === 0) {
+        jsonResponse(res, 409, { error: `Approval not found or not in pending state: ${approvalId}` });
+        return;
+      }
+      mirrorHboStore('approval.approve', () => hboStore.updateApproval?.(approvalId, cid, { status: 'approved', answer, approvedAt: Date.now() }));
 
     // Synchronously update linked Strategy if this is a strategy_proposal
     try {
@@ -714,6 +1116,7 @@ async function handleRejectApproval(req, res, ctx, approvalId) {
       jsonResponse(res, 409, { error: `Approval not found or not in pending state: ${approvalId}` });
       return;
     }
+    mirrorHboStore('approval.reject', () => hboStore.updateApproval?.(approvalId, cid, { status: 'rejected', rejectReason: reason, rejectedAt: Date.now() }));
     broadcast({ type: 'approval.rejected', approvalId, reason, companyId: cid });
     jsonResponse(res, 200, { rejected: true, approvalId, reason });
   } catch (err) {
@@ -2222,6 +2625,18 @@ async function handleCreateStrategy(req, res, ctx) {
       { id: approvalId, cid, approvalTitle: `Strategy: ${title}`, plan, proposedBy, strategyId }
     );
 
+    mirrorHboStore('approval.create', () => hboStore.createApproval?.({
+      id: approvalId,
+      companyId: cid,
+      type: 'strategy_proposal',
+      title: `Strategy: ${title}`,
+      description: plan,
+      requestedBy: proposedBy,
+      strategyId,
+      status: 'pending',
+      createdAt: Date.now(),
+    }));
+
     // Link goal to strategy
     await mgQuery(
       `MATCH (g:CompanyGoal {id: $goalId}), (s:Strategy {id: $strategyId})
@@ -2305,13 +2720,13 @@ async function handleFireWebhookTrigger(req, res, ctx, publicId) {
     const result = await mgQuery(
       `MATCH (rt:RoutineTrigger {publicId: $publicId, companyId: $cid})-[:TRIGGERS]->(r:Routine)
        RETURN rt.id AS triggerId, rt.routineId AS routineId, r.title AS routineTitle,
-              r.variables AS variables, r.companyId AS companyId`,
+              r.variables AS variables, r.companyId AS companyId, rt.secret AS secret`,
       { publicId, cid: ctx.cid }
     );
     const rows = parseRows(result);
     if (rows.length === 0) return jsonResponse(res, 404, { error: 'Trigger not found' });
 
-    const keys = ['triggerId', 'routineId', 'routineTitle', 'variables', 'companyId'];
+    const keys = ['triggerId', 'routineId', 'routineTitle', 'variables', 'companyId', 'secret'];
     const trigger = rowToObj(rows[0], keys);
 
     // S-06: Verify HMAC signature if trigger has a secret configured
@@ -2356,8 +2771,8 @@ async function handleFireWebhookTrigger(req, res, ctx, publicId) {
       }
     );
 
-    broadcast({ type: 'routine.fired', routineId: trigger.routineId, taskId, source: 'webhook', companyId: cid });
-    return jsonResponse(res, 200, { fired: true, taskId, routineId: trigger.routineId });
+      broadcast({ type: 'routine.fired', routineId: trigger.routineId, taskId, source: 'webhook', companyId: trigger.companyId });
+      return jsonResponse(res, 200, { fired: true, taskId, routineId: trigger.routineId });
   } catch (err) {
     return jsonResponse(res, 500, { error: err.message });
   }
@@ -2365,6 +2780,124 @@ async function handleFireWebhookTrigger(req, res, ctx, publicId) {
 
 // ── Routine Revisions & Runs ──────────────────────────────────────────────────
 
+// P5-01: GET /api/routines — list all routines for a company
+// SQL parity: falls back to hboStore.getRoutinesByCompany when Memgraph unavailable
+async function handleGetRoutines(req, res, ctx) {
+  const { mgQuery } = ctx;
+  const cid = ctx.cid;
+  const url = new URL(req.url, 'http://localhost');
+  const statusFilter = url.searchParams.get('status') || '';
+
+  if (mgQuery) {
+    try {
+      let cypher = `MATCH (r:Routine {companyId: $cid})`;
+      const params = { cid };
+      if (statusFilter) { cypher += ` WHERE r.status = $status`; params.status = statusFilter; }
+      cypher += ` RETURN r.id, r.name, r.cronExpr, r.agentId, r.status, r.concurrencyPolicy,
+                         r.catchUpPolicy, r.catchUpCap, r.nextRunAt, r.lastRunAt, r.createdAt
+                  ORDER BY r.createdAt DESC`;
+      const result = await mgQuery(cypher, params);
+      const keys = ['id','name','cronExpr','agentId','status','concurrencyPolicy','catchUpPolicy','catchUpCap','nextRunAt','lastRunAt','createdAt'];
+      const routines = parseRows(result).map(r => rowToObj(r, keys));
+      return jsonResponse(res, 200, { routines, count: routines.length });
+    } catch (e) {
+      log('warn', `handleGetRoutines Memgraph failed, falling back to SQLite: ${e.message}`);
+    }
+  }
+  // SQLite fallback
+  try {
+    const rows = hboStore.getRoutinesByCompany ? hboStore.getRoutinesByCompany(cid, statusFilter || undefined) : [];
+    const routines = (rows || []).map(r => ({
+      id: r.id, name: r.name ?? null, cronExpr: r.cron_expr ?? r.cronExpr ?? null,
+      agentId: r.agent_id ?? r.agentId ?? null, status: r.status ?? 'active',
+      concurrencyPolicy: r.concurrency_policy ?? r.concurrencyPolicy ?? 'skip_if_active',
+      catchUpPolicy: r.catch_up_policy ?? r.catchUpPolicy ?? 'skip_missed',
+      catchUpCap: r.catch_up_cap ?? r.catchUpCap ?? 0,
+      nextRunAt: r.next_run_at ?? r.nextRunAt ?? null,
+      lastRunAt: r.last_run_at ?? r.lastRunAt ?? null,
+      createdAt: r.created_at ? new Date(r.created_at).toISOString() : null,
+    }));
+    return jsonResponse(res, 200, { routines, count: routines.length, _source: 'sqlite' });
+  } catch (storeErr) {
+    return jsonResponse(res, 503, { error: `Routines unavailable: ${storeErr.message}` });
+  }
+}
+
+// P5-02: POST /api/routines — create a new routine
+async function handleCreateRoutine(req, res, ctx) {
+  const { mgQuery } = ctx;
+  if (!mgQuery) { jsonResponse(res, 503, { error: 'Memgraph not connected' }); return; }
+  const cid = ctx.cid;
+  if (!cid || cid === 'default-company') { jsonResponse(res, 400, { error: 'companyId is required' }); return; }
+
+  const body = await parseBody(req);
+  const { name, agentId, cronExpr, concurrencyPolicy, catchUpPolicy, catchUpCap } = body;
+
+  if (!name || typeof name !== 'string' || !name.trim()) {
+    jsonResponse(res, 400, { error: 'name is required' });
+    return;
+  }
+  if (!agentId || typeof agentId !== 'string') {
+    jsonResponse(res, 400, { error: 'agentId is required' });
+    return;
+  }
+  if (!cronExpr || typeof cronExpr !== 'string') {
+    jsonResponse(res, 400, { error: 'cronExpr is required' });
+    return;
+  }
+
+  // Compute nextRunAt using croner (confirmed available in daemon)
+  let nextRunAt;
+  try {
+    const { Cron } = require('croner');
+    const cron = new Cron(cronExpr);
+    const next = cron.nextRun();
+    cron.stop();
+    nextRunAt = next ? next.toISOString().replace(/\.\d{3}Z$/, '+00:00') : null;
+  } catch (cronErr) {
+    log('warn', `P5-02: cronExpr could not be parsed: ${cronErr.message} — using +1h fallback`);
+    nextRunAt = null; // Memgraph will use datetime() + duration("PT1H") fallback
+  }
+
+  const resolvedPolicy = ['skip_if_active', 'coalesce_if_active', 'allow_concurrent'].includes(concurrencyPolicy)
+    ? concurrencyPolicy : 'skip_if_active';
+  const resolvedCatchUp = ['skip_missed', 'enqueue_missed_with_cap'].includes(catchUpPolicy)
+    ? catchUpPolicy : 'skip_missed';
+  const resolvedCap = Number.isFinite(Number(catchUpCap)) ? Math.max(0, Number(catchUpCap)) : 0;
+  const routineId = `routine:${cid}:${crypto.randomUUID()}`;
+
+  try {
+    const cypher = nextRunAt
+      ? `CREATE (r:Routine { id:$id, companyId:$cid, agentId:$agentId, name:$name,
+           cronExpr:$cron, status:'active', concurrencyPolicy:$policy, catchUpPolicy:$catchUp,
+           catchUpCap:toInteger($cap), nextRunAt:datetime($nextRun), createdAt:datetime() })`
+      : `CREATE (r:Routine { id:$id, companyId:$cid, agentId:$agentId, name:$name,
+           cronExpr:$cron, status:'active', concurrencyPolicy:$policy, catchUpPolicy:$catchUp,
+           catchUpCap:toInteger($cap), nextRunAt:datetime() + duration("PT1H"), createdAt:datetime() })`;
+    const params = {
+      id: routineId, cid, agentId: String(agentId), name: String(name).trim(),
+      cron: cronExpr, policy: resolvedPolicy, catchUp: resolvedCatchUp, cap: resolvedCap,
+      ...(nextRunAt ? { nextRun: nextRunAt } : {}),
+    };
+    await mgQuery(cypher, params);
+
+    // P5-SQL: SQLite write-through (fire-and-forget)
+    try {
+      hboStore.upsertRoutine?.({
+        id: routineId, company_id: cid, agent_id: String(agentId), name: String(name).trim(),
+        cron_expr: cronExpr, status: 'active', concurrency_policy: resolvedPolicy,
+        catch_up_policy: resolvedCatchUp, catch_up_cap: resolvedCap,
+        next_run_at: nextRunAt, created_at: Date.now(),
+      });
+    } catch (storeErr) { log('error', 'hboStore.upsertRoutine failed', { err: storeErr.message }); }
+
+    broadcast({ type: 'routine.created', routineId, companyId: cid });
+    jsonResponse(res, 201, { routine: { id: routineId, name: String(name).trim(), agentId, cronExpr, status: 'active', concurrencyPolicy: resolvedPolicy, catchUpCap: resolvedCap } });
+  } catch (err) {
+    jsonResponse(res, 500, { error: `Create routine failed: ${err.message}` });
+  }
+}
+
 async function handlePatchRoutine(req, res, ctx, routineId) {
   const { mgQuery } = ctx;
   const body = await parseBody(req);
@@ -2500,7 +3033,7 @@ async function dispatchToAdapter(mgQuery, ctx, taskId, agentId) {
     HELIOS_AGENT_ID: agentId,
     HELIOS_RUN_ID: runId,
     HELIOS_TASK_ID: taskId,
-    HELIOS_API_URL: `http://localhost:${ctx.apiPort || 9091}`,
+    HELIOS_API_URL: `http://localhost:${ctx.apiPort || 9093}`,
   };
 
   broadcast({ type: 'run.started', runId, taskId, agentId, adapterType, companyId: cid });
@@ -2799,6 +3332,7 @@ const tasksRoute = require('./routes/tasks')({
   handleGetTaskComments,
   handlePostTaskComment,
   handlePatchTask: handleUpdateTask,  // GAP-20 fix: was wired to duplicate (no companyId); now uses correct handleUpdateTask
+  handlePatchTaskPolicy,              // P4-07: PATCH /api/tasks/:id/policy
 });
 
 const approvalsRoute = require('./routes/approvals')({
@@ -2845,6 +3379,8 @@ const strategyRoute = require('./routes/strategy')({
 });
 
 const routinesRoute = require('./routes/routines')({
+  handleGetRoutines,
+  handleCreateRoutine,
   handleGetRoutineTriggers,
   handleCreateRoutineTrigger,
   handleFireWebhookTrigger,
@@ -2931,6 +3467,10 @@ async function route(req, res, ctx) {
   // It can never elevate to a company this daemon doesn't own.
   const qcid = parsedUrl.searchParams.get('companyId');
   const primaryCid = ctx.companies?.[0]?.id ?? 'default-company';
+  if (method === 'GET' && pathname === '/api/agents' && (!qcid || !qcid.trim())) {
+    jsonResponse(res, 400, { error: 'companyId required' });
+    return;
+  }
   // qcid will be validated against allowedCompanyIds before being used;
   // if it doesn't match, the 403 below catches it. This is safe.
   // Group C: Create per-request context clone so concurrent requests can't corrupt each other's cid.
@@ -3654,7 +4194,7 @@ async function handleGetDepartmentPageRoute(req, res, ctx, department) {
  * Start the REST API server.
  *
  * @param {Function} mgQuery - Memgraph query function: (cypher, params) => Promise<rows>
- * @param {object}   config  - Daemon config (uses config.apiPort ?? 9091)
+ * @param {object}   config  - Daemon config (uses config.apiPort ?? 9093)
  * @param {object}   state   - Optional shared state for health endpoint
  * @returns {{ server, updateTick, setDraining }}
  */
@@ -3662,6 +4202,16 @@ async function handleGetDepartmentPageRoute(req, res, ctx, department) {
 
 async function handleGetTaskDetail(req, res, ctx, taskId) {
   const cid = ctx.cid;
+  // H-2 fix: SQLite fallback when Memgraph is unavailable
+  if (!ctx.mgQuery) {
+    try {
+      const t = hboStore.getTask ? hboStore.getTask(taskId, cid) : null;
+      if (!t) return jsonResponse(res, 404, { error: 'Task not found' });
+      return jsonResponse(res, 200, { task: t, _source: 'sqlite' });
+    } catch (storeErr) {
+      return jsonResponse(res, 503, { error: 'Task unavailable: Memgraph not connected', task: null });
+    }
+  }
   try {
     const result = await ctx.mgQuery('MATCH (t:Task {id: $id, companyId: $cid}) RETURN t', { id: taskId, cid });
     if (result.rows && result.rows.length > 0) {
@@ -3842,6 +4392,7 @@ function startApi(mgQuery, config = {}, state = {}) {
       invalidateContextCache,
       semanticUpdater: container?.cradle?.projectSemanticUpdater ?? null,
       driftDetector:   container?.cradle?.projectDriftDetector   ?? null,
+      hboStore,
     });
     // Dept Catchball pitch — shares same semanticUpdater from container
     deptRoute = require('./routes/dept')({
@@ -3852,7 +4403,7 @@ function startApi(mgQuery, config = {}, state = {}) {
   } catch (e) {
     // container.js not yet built — projectRoute falls back to () => false
     const { invalidateContextCache } = require('./context-enrichment');
-    projectRoute = require('./routes/project')({ mgQuery, broadcast: state.broadcast ?? (() => {}), invalidateContextCache });
+    projectRoute = require('./routes/project')({ mgQuery, broadcast: state.broadcast ?? (() => {}), invalidateContextCache, hboStore });
     deptRoute = require('./routes/dept')({ mgQuery, broadcast: state.broadcast ?? (() => {}) });
   }
 
@@ -3870,7 +4421,7 @@ function startApi(mgQuery, config = {}, state = {}) {
   try { channelsRoute   = require('./routes/channels')({ mgQuery }); }          catch(e) { log('warn', `channels route unavailable: ${e.message}`); }
   try { emailInfraRoute = require('./routes/email-infrastructure')({ mgQuery }); } catch(e) { log('warn', `emailInfra route unavailable: ${e.message}`); }
 
-  const port = config.apiPort ?? 9091;
+  const port = config.apiPort ?? 9093;
 
   // Security: shared-secret token for WebSocket upgrade.
   // Mirrors GHSA-3c6j-hq33-3jv4 (forged exec lifecycle events via unauthenticated WS).
@@ -3882,6 +4433,8 @@ function startApi(mgQuery, config = {}, state = {}) {
     mgQuery,
     companies: state.companies ?? [],
     cid: state.companies?.[0]?.id ?? 'default-company', // default — overridden per-request in route()
+    apiPort: port,
+    actualBoundPort: null,
     tickCount: 0,
     draining: false,
     apiToken: config.apiToken || null, // null = no auth (backward compat)
@@ -4000,11 +4553,12 @@ function startApi(mgQuery, config = {}, state = {}) {
   });
 
   server.listen(port, config.apiHost ?? '127.0.0.1', () => {
+    ctx.actualBoundPort = server.address()?.port ?? port;
     process.stdout.write(JSON.stringify({
       ts: new Date().toISOString(),
       level: 'info',
       module: 'helios-api',
-      msg: `REST API listening on http://127.0.0.1:${port}`,
+      msg: `REST API listening on http://127.0.0.1:${ctx.actualBoundPort}`,
     }) + '\n');
 
     // Write daemon.lock — the ground-truth discovery file for Helios Desktop.