@dotdrelle/wiki-manager 0.8.2 → 0.10.4

package/src/core/agentEvents.js

@@ -1,10 +1,19 @@
 import { normalizeActivity } from './activity.js';
 import { attachActivityToExistingPlan, syncActivitiesToPlan } from './plan.js';
+import { applyPlanPatch, normalizePlanPatch, normalizePlanRevision, rebasePlanPatch } from './planPatch.js';
+import { projectWorkflow } from './workflow.js';
+import { validateContractInDev } from '../contracts/schemas.js';
 
 const SESSION_PROJECTION_EVENTS = new Set([
   'run_started',
   'plan_set',
   'plan_step_updated',
+  'control_message_received',
+  'plan_patch_proposed',
+  'plan_patch_approved',
+  'plan_patch_applied',
+  'plan_patch_rebased',
+  'plan_patch_rejected',
   'activity_upserted',
   'run_evaluated',
   'run_replanned',
@@ -12,6 +21,8 @@ const SESSION_PROJECTION_EVENTS = new Set([
   'run_approved',
   'tool_pending_approval',
   'tool_approved',
+  'control_enqueued',
+  'control_started',
   'run_done',
   'run_error',
   'run_cancelled',
@@ -24,6 +35,7 @@ const SESSION_PROJECTION_EVENTS = new Set([
 const PLAN_MUTATING_EVENTS = new Set([
   'run_started',
   'plan_set',
+  'plan_patch_applied',
   'plan_step_updated',
   'activity_upserted',
   'run_done',
@@ -34,18 +46,20 @@ export function createAgentEvent(type, {
   payload = {},
   runId = null,
   turnId = null,
+  taskId = null,
   workspace = null,
 } = {}) {
-  return {
+  return validateContractInDev('agentRunEvent', {
     id: `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
     ts: new Date().toISOString(),
     type,
     origin,
     runId,
     turnId,
+    taskId,
     workspace,
     payload,
-  };
+  });
 }
 
 export function dispatchAgentEvent(session, event) {
@@ -53,6 +67,7 @@ export function dispatchAgentEvent(session, event) {
     event.id && event.ts ? event : createAgentEvent(event.type, event),
     session,
   );
+  validateContractInDev('agentRunEvent', normalized);
   const tracksPlan = PLAN_MUTATING_EVENTS.has(normalized.type);
   const previousPlan = tracksPlan ? JSON.stringify(session.headlessPlan ?? null) : null;
   session.agentEvents ??= [];
@@ -77,6 +92,7 @@ function withSessionRunIdentity(event, session) {
     ...event,
     runId: event.runId ?? identity.runId ?? null,
     turnId: event.turnId ?? identity.turnId ?? null,
+    taskId: event.taskId ?? identity.taskId ?? null,
     workspace: event.workspace ?? identity.workspace ?? null,
   };
 }
@@ -101,13 +117,16 @@ function createProjectionState() {
     evaluation: null,
     replans: [],
     approvals: [],
+    planRevision: 0,
+    planPatches: [],
+    controlQueue: [],
     summary: null,
     status: 'idle',
   };
 }
 
 function publicProjection(state) {
-  return {
+  const projection = {
     conversation: state.conversation.map((message) => ({ ...message })),
     chain: state.chain.map((step) => ({ ...step })),
     plan: state.plan ? state.plan.map((step) => ({ ...step })) : null,
@@ -116,14 +135,29 @@ function publicProjection(state) {
     evaluation: state.evaluation ? { ...state.evaluation } : null,
     replans: state.replans.map((replan) => ({ ...replan, plan: [...(replan.plan ?? [])] })),
     approvals: state.approvals.map((approval) => ({ ...approval })),
+    planRevision: state.planRevision,
+    planPatches: state.planPatches.map((patch) => ({
+      ...patch,
+      operations: (patch.operations ?? []).map((operation) => ({ ...operation })),
+      patch: patch.patch ? { ...patch.patch, operations: (patch.patch.operations ?? []).map((operation) => ({ ...operation })) } : null,
+    })),
+    controlQueue: state.controlQueue.map((item) => ({ ...item })),
     summary: state.summary,
     status: state.status,
   };
+  return {
+    ...projection,
+    workflow: projectWorkflow(projection),
+  };
 }
 
 export function applyAgentProjectionToSession(session, projection) {
   session.headlessPlan = projection.plan ? projection.plan.map((step) => ({ ...step })) : null;
   session.activities = Object.fromEntries((projection.activities ?? []).map((activity) => [activity.key, { ...activity }]));
+  session.controlQueue = (projection.controlQueue ?? []).map((item) => ({ ...item }));
+  session.planRevision = projection.planRevision ?? 0;
+  session.planPatches = (projection.planPatches ?? []).map((patch) => ({ ...patch }));
+  session.workflow = projection.workflow ? { ...projection.workflow } : null;
   const production = (projection.activities ?? []).filter((activity) => activity.source === 'production').at(-1);
   session.productionActivity = production ? {
     jobId: production.id,
@@ -138,13 +172,15 @@ function applyEvent(state, event) {
   switch (event.type) {
     case 'run_started':
       state.status = 'running';
-      state.plan = defaultRunPlan();
+      state.plan = null;
       state.chain = [];
       state.activities = {};
       state.logs = [];
       state.evaluation = null;
       state.replans = [];
       state.approvals = [];
+      state.planRevision = 0;
+      state.planPatches = [];
       state.summary = null;
       return;
     case 'user_message':
@@ -174,10 +210,97 @@ function applyEvent(state, event) {
       return;
     case 'plan_set':
       state.plan = normalizePlan(event.payload?.steps, event.payload ?? {});
+      // A plan_set always replaces the plan wholesale (initial declaration,
+      // fallback extraction, or a full replan) — bump the revision so any
+      // patch proposed against the prior plan is detected as stale and
+      // rebased instead of silently applying against a structure that no
+      // longer matches what it was built for. An explicit payload.planRevision
+      // still wins, for callers that manage revisions themselves.
+      state.planRevision = event.payload?.planRevision != null
+        ? normalizePlanRevision(event.payload.planRevision)
+        : state.planRevision + 1;
       return;
     case 'plan_step_updated':
       updatePlanStep(state.plan, event.payload ?? {});
       return;
+    case 'control_message_received':
+      state.logs.push(`Control message: ${String(event.payload?.input ?? '')}`);
+      state.logs = state.logs.slice(-200);
+      return;
+    case 'plan_patch_proposed':
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'proposed',
+        runId: event.runId ?? event.payload?.targetRunId ?? null,
+        workspace: event.workspace ?? null,
+        input: event.payload?.input ?? null,
+        patch: normalizePlanPatch(event.payload?.patch ?? {}, {
+          targetRunId: event.runId ?? event.payload?.targetRunId ?? null,
+          basePlanRevision: state.planRevision,
+        }),
+        createdAt: event.ts,
+        updatedAt: event.ts,
+      });
+      return;
+    case 'plan_patch_approved':
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'approved',
+        approvedAt: event.ts,
+        updatedAt: event.ts,
+      });
+      return;
+    case 'plan_patch_rebased': {
+      const existing = state.planPatches.find((patch) => patch.id === patchIdFromEvent(event));
+      const rebased = normalizePlanPatch(event.payload?.patch ?? rebasePlanPatch(existing?.patch ?? {}, { currentRevision: state.planRevision }), {
+        targetRunId: event.runId ?? null,
+        basePlanRevision: state.planRevision,
+      });
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'rebased',
+        patch: rebased,
+        updatedAt: event.ts,
+      });
+      return;
+    }
+    case 'plan_patch_applied': {
+      const patchId = patchIdFromEvent(event);
+      const patch = normalizePlanPatch(event.payload?.patch ?? {}, {
+        targetRunId: event.runId ?? event.payload?.targetRunId ?? null,
+        basePlanRevision: state.planRevision,
+      });
+      const applied = applyPlanPatch(state.plan, patch, { currentRevision: state.planRevision });
+      if (!applied.ok) {
+        upsertPlanPatch(state, {
+          id: patchId,
+          status: 'rejected',
+          rejectionReason: applied.reason,
+          currentRevision: applied.currentRevision,
+          updatedAt: event.ts,
+        });
+        return;
+      }
+      state.plan = applied.plan;
+      state.planRevision = applied.planRevision;
+      upsertPlanPatch(state, {
+        id: patchId,
+        status: 'applied',
+        patch,
+        appliedAt: event.ts,
+        planRevision: state.planRevision,
+        updatedAt: event.ts,
+      });
+      return;
+    }
+    case 'plan_patch_rejected':
+      upsertPlanPatch(state, {
+        id: patchIdFromEvent(event),
+        status: 'rejected',
+        rejectionReason: event.payload?.reason ?? null,
+        updatedAt: event.ts,
+      });
+      return;
     case 'run_summary':
       state.summary = String(event.payload?.content ?? '');
       if (state.summary) state.conversation.push({ role: 'assistant', content: state.summary });
@@ -226,14 +349,36 @@ function applyEvent(state, event) {
     case 'run_done':
       state.status = 'done';
       finishPendingPlanSteps(state.plan);
+      finishControlByRun(state.controlQueue, event.runId ?? event.payload?.runId ?? null, 'done', event.ts);
       return;
     case 'run_cancelled':
       state.status = 'cancelled';
       state.logs.push(String(event.payload?.message ?? 'Agent run cancelled.'));
+      finishControlByRun(state.controlQueue, event.runId ?? event.payload?.runId ?? null, 'cancelled', event.ts);
       return;
     case 'run_error':
       state.status = 'error';
       state.logs.push(String(event.payload?.message ?? 'Agent run failed.'));
+      finishControlByRun(state.controlQueue, event.runId ?? event.payload?.runId ?? null, 'failed', event.ts);
+      return;
+    case 'control_enqueued':
+      upsertControlItem(state.controlQueue, {
+        id: event.payload?.id ?? event.id,
+        workspace: event.workspace ?? event.payload?.workspace ?? null,
+        input: String(event.payload?.input ?? ''),
+        status: 'queued',
+        createdAt: event.payload?.createdAt ?? event.ts,
+        updatedAt: event.ts,
+      });
+      return;
+    case 'control_started':
+      upsertControlItem(state.controlQueue, {
+        id: event.payload?.id ?? null,
+        runId: event.runId ?? event.payload?.runId ?? null,
+        status: 'running',
+        startedAt: event.payload?.startedAt ?? event.ts,
+        updatedAt: event.ts,
+      });
       return;
     case 'runtime_log':
       state.logs.push(String(event.payload?.message ?? ''));
@@ -244,6 +389,41 @@ function applyEvent(state, event) {
   }
 }
 
+function upsertById(list, next) {
+  const index = list.findIndex((item) => item.id === next.id);
+  if (index === -1) {
+    list.push(next);
+    return;
+  }
+  list[index] = {
+    ...list[index],
+    ...next,
+  };
+}
+
+function upsertControlItem(queue, next) {
+  if (!next.id) return;
+  upsertById(queue, next);
+}
+
+function upsertPlanPatch(state, next) {
+  if (!next.id) return;
+  upsertById(state.planPatches, next);
+}
+
+function patchIdFromEvent(event) {
+  return event.payload?.id ?? event.payload?.patchId ?? event.id;
+}
+
+function finishControlByRun(queue, runId, status, finishedAt) {
+  if (!runId) return;
+  const item = queue.find((entry) => entry.runId === runId && entry.status === 'running');
+  if (!item) return;
+  item.status = status;
+  item.finishedAt = finishedAt;
+  item.updatedAt = finishedAt;
+}
+
 function appendAssistantDelta(state, delta) {
   if (!delta) return;
   const last = state.conversation.at(-1);
@@ -279,15 +459,7 @@ function finishToolCall(state, payload = {}) {
 }
 
 function upsertApproval(state, next) {
-  const index = state.approvals.findIndex((approval) => approval.id === next.id);
-  if (index === -1) {
-    state.approvals.push(next);
-    return;
-  }
-  state.approvals[index] = {
-    ...state.approvals[index],
-    ...next,
-  };
+  upsertById(state.approvals, next);
 }
 
 function finishPendingPlanSteps(plan) {
@@ -323,6 +495,10 @@ function ensurePlanFromActivityProjection(state, activity) {
       id: step.id ?? null,
       description: step.label,
       status: 'pending',
+      dependsOn: Array.isArray(step.dependsOn) ? step.dependsOn.map(String) : [],
+      executor: step.executor ?? null,
+      executorQuery: step.executorQuery ?? null,
+      outputRefs: Array.isArray(step.outputRefs) ? step.outputRefs.map(String) : [],
       owner: 'activity',
       ownerActivityKey: activity.key,
       _activityKey: activity.key,
@@ -334,6 +510,10 @@ function ensurePlanFromActivityProjection(state, activity) {
     id: null,
     description: activity.label,
     status: 'pending',
+    dependsOn: [],
+    executor: null,
+    executorQuery: null,
+    outputRefs: [],
     owner: 'activity',
     ownerActivityKey: activity.key,
     _activityKey: activity.key,
@@ -344,33 +524,41 @@ function normalizePlan(steps, payload = {}) {
   if (!Array.isArray(steps)) return null;
   const owner = payload.owner ?? 'orchestrator';
   const ownerActivityKey = payload.ownerActivityKey ?? payload.activityKey ?? null;
-  return steps.map((raw, i) => {
+  const plan = steps.map((raw, i) => {
     const item = typeof raw === 'string' ? { description: raw } : (raw ?? {});
     return {
       step: Number(item.step ?? i + 1),
       id: item.id ?? null,
       description: String(item.description ?? item.label ?? item.name ?? `Step ${i + 1}`),
       status: item.status ?? 'pending',
+      dependsOn: Array.isArray(item.dependsOn) ? item.dependsOn.map(String) : [],
+      executor: item.executor ?? null,
+      executorQuery: item.executorQuery ?? null,
+      outputRefs: Array.isArray(item.outputRefs) ? item.outputRefs.map(String) : [],
+      locks: Array.isArray(item.locks) ? item.locks.map(String) : item.locks ?? null,
+      writeLocks: Array.isArray(item.writeLocks) ? item.writeLocks.map(String) : item.writeLocks ?? null,
+      deliverableWrites: Array.isArray(item.deliverableWrites) ? item.deliverableWrites.map(String) : [],
+      wikiPageWrites: Array.isArray(item.wikiPageWrites) ? item.wikiPageWrites.map(String) : [],
+      workspaceWrite: item.workspaceWrite === true,
       owner: item.owner ?? owner,
       ownerActivityKey: item.ownerActivityKey ?? ownerActivityKey,
       _activityKey: item._activityKey ?? payload.activityKey ?? null,
     };
   });
-}
-
-function defaultRunPlan() {
-  return [
-    { step: 1, id: 'analyze', description: 'Analyze the request', status: 'running', owner: 'orchestrator', ownerActivityKey: null, _activityKey: null },
-    { step: 2, id: 'execute', description: 'Execute the required actions', status: 'pending', owner: 'orchestrator', ownerActivityKey: null, _activityKey: null },
-    { step: 3, id: 'verify', description: 'Verify the result', status: 'pending', owner: 'orchestrator', ownerActivityKey: null, _activityKey: null },
-  ];
+  return validateContractInDev('plan', plan);
 }
 
 function updatePlanStep(plan, payload) {
   if (!plan) return;
-  const step = plan.find((item) => item.step === Number(payload.step));
+  const requestedTaskId = payload.taskId ?? payload.id ?? payload.targetTaskId;
+  const step = requestedTaskId != null
+    ? plan.find((item) => String(item.id ?? item.step) === String(requestedTaskId))
+    : plan.find((item) => item.step === Number(payload.step));
   if (!step) return;
-  step.status = payload.status === 'failed' ? 'failed' : payload.status === 'running' ? 'running' : 'done';
+  if (payload.status === 'failed') step.status = 'failed';
+  else if (payload.status === 'running') step.status = 'running';
+  else if (payload.status === 'cancelled') step.status = 'cancelled';
+  else step.status = 'done';
   if (payload.activityKey) step.activityKey = payload.activityKey;
 }
 

package/src/core/agentEvents.test.js

@@ -22,9 +22,7 @@ test('reduceAgentEvents: run_started clears stale plan', () => {
     }),
     createAgentEvent('run_started', { origin: 'user' }),
   ]);
-  assert.equal(projection.plan.length, 3);
-  assert.equal(projection.plan[0].description, 'Analyze the request');
-  assert.equal(projection.plan[0].owner, 'orchestrator');
+  assert.equal(projection.plan, null);
   assert.equal(projection.activities.length, 0);
   assert.equal(projection.status, 'running');
 });
@@ -95,7 +93,7 @@ test('reduceAgentEvents: activity attaches to orchestrator plan without replacin
   assert.equal(projection.plan[0].ownerActivityKey, 'cme:export-1');
 });
 
-test('reduceAgentEvents: run activity attaches to execution step of default plan', () => {
+test('reduceAgentEvents: run activity creates activity-owned plan when no explicit plan exists', () => {
   const projection = reduceAgentEvents([
     createAgentEvent('run_started', { origin: 'runtime' }),
     createAgentEvent('activity_upserted', {
@@ -112,28 +110,34 @@ test('reduceAgentEvents: run activity attaches to execution step of default plan
     }),
   ]);
 
-  assert.equal(projection.plan[0].status, 'done');
-  assert.equal(projection.plan[1].status, 'running');
-  assert.equal(projection.plan[1].activityKey, 'production:build-1');
-  assert.equal(projection.plan[2].status, 'pending');
+  assert.equal(projection.plan.length, 1);
+  assert.equal(projection.plan[0].description, 'Production build');
+  assert.equal(projection.plan[0].status, 'running');
+  assert.equal(projection.plan[0].owner, 'activity');
 });
 
 test('reduceAgentEvents: run_done finalizes running and pending plan steps', () => {
   const projection = reduceAgentEvents([
-    createAgentEvent('run_started', { origin: 'runtime' }),
+    createAgentEvent('plan_set', {
+      origin: 'tool',
+      payload: { steps: ['Analyze', 'Execute'] },
+    }),
     createAgentEvent('run_done', { origin: 'runtime' }),
   ]);
 
-  assert.deepEqual(projection.plan.map((step) => step.status), ['done', 'done', 'done']);
+  assert.deepEqual(projection.plan.map((step) => step.status), ['done', 'done']);
   assert.equal(projection.status, 'done');
 });
 
 test('dispatchAgentEvent: run_done finalizes session plan', () => {
   const session = {};
-  dispatchAgentEvent(session, createAgentEvent('run_started', { origin: 'runtime' }));
+  dispatchAgentEvent(session, createAgentEvent('plan_set', {
+    origin: 'tool',
+    payload: { steps: ['Analyze', 'Execute'] },
+  }));
   dispatchAgentEvent(session, createAgentEvent('run_done', { origin: 'runtime' }));
 
-  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done', 'done']);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done']);
   assert.equal(session.agentProjection.status, 'done');
 });
 
@@ -210,6 +214,37 @@ test('reduceAgentEvents: approvals move from pending to approved', () => {
   assert.deepEqual(projection.approvals[0].plan, ['Build']);
 });
 
+test('reduceAgentEvents: control queue is event sourced and follows run status', () => {
+  const projection = reduceAgentEvents([
+    createAgentEvent('control_enqueued', {
+      origin: 'runtime',
+      workspace: 'docs',
+      payload: {
+        id: 'control-1',
+        workspace: 'docs',
+        input: 'Run after current task',
+        createdAt: '2026-01-01T00:00:00.000Z',
+      },
+    }),
+    createAgentEvent('control_started', {
+      origin: 'runtime',
+      runId: 'run-control-1',
+      workspace: 'docs',
+      payload: { id: 'control-1', runId: 'run-control-1' },
+    }),
+    createAgentEvent('run_done', {
+      origin: 'runtime',
+      runId: 'run-control-1',
+      workspace: 'docs',
+    }),
+  ]);
+
+  assert.equal(projection.controlQueue.length, 1);
+  assert.equal(projection.controlQueue[0].id, 'control-1');
+  assert.equal(projection.controlQueue[0].status, 'done');
+  assert.equal(projection.controlQueue[0].runId, 'run-control-1');
+});
+
 test('reduceAgentEvents: activity-owned plan is used when no orchestrator plan exists', () => {
   const projection = reduceAgentEvents([
     createAgentEvent('activity_upserted', {
@@ -273,3 +308,41 @@ test('dispatchAgentEvent: assistant deltas do not rewrite session plan or activi
   assert.equal(planUpdates, updatesAfterActivity);
   assert.equal(session.agentProjection.conversation.at(-1).content, 'bonjour');
 });
+
+test('reduceAgentEvents: plan patches are proposed, approved and applied with revisions', () => {
+  // plan_set bumps planRevision (it wholesale-replaces the plan), so a patch
+  // proposed after it must target that new revision (1), not 0.
+  const patch = {
+    targetRunId: 'run-patch',
+    basePlanRevision: 1,
+    operations: [{ op: 'add_task', task: { id: 'task-b', description: 'B', dependsOn: ['task-a'] } }],
+  };
+  const projection = reduceAgentEvents([
+    createAgentEvent('run_started', { origin: 'runtime', runId: 'run-patch' }),
+    createAgentEvent('plan_set', {
+      origin: 'tool',
+      runId: 'run-patch',
+      payload: { steps: [{ id: 'task-a', description: 'A', status: 'done' }] },
+    }),
+    createAgentEvent('plan_patch_proposed', {
+      origin: 'runtime',
+      runId: 'run-patch',
+      payload: { id: 'patch-1', patch },
+    }),
+    createAgentEvent('plan_patch_approved', {
+      origin: 'runtime',
+      runId: 'run-patch',
+      payload: { patchId: 'patch-1' },
+    }),
+    createAgentEvent('plan_patch_applied', {
+      origin: 'runtime',
+      runId: 'run-patch',
+      payload: { patchId: 'patch-1', patch },
+    }),
+  ]);
+
+  assert.equal(projection.planRevision, 2);
+  assert.deepEqual(projection.plan.map((step) => step.id), ['task-a', 'task-b']);
+  assert.equal(projection.plan[1].status, 'pending');
+  assert.equal(projection.planPatches[0].status, 'applied');
+});

package/src/core/agentLoop.js

@@ -2,6 +2,7 @@ import { buildAgentSystemPrompt, buildLimitedAgentResponse } from '../agent/grap
 import { createAgentEvent, dispatchAgentEvent } from './agentEvents.js';
 import { activitySnapshot, newNonTerminalActivities } from './activity.js';
 import { extractHeadlessPlan, formatCompletedActivities, formatPlanStatus } from './plan.js';
+import { formatReadyTaskPrompt, nextReadyPlanTask, readyPlanTasks } from './planPatch.js';
 
 export function abortError(message = 'Agent run cancelled.') {
   const err = new Error(message);
@@ -20,12 +21,14 @@ export async function runAgentTurn(agent, session, input, {
   let streamedContent = '';
   session._onStream = (delta) => { streamedContent += delta; };
   session._onStreamReset = () => { streamedContent = ''; };
+  if (signal) session._abortSignal = signal;
   let result;
   try {
-    result = await agent.invoke({ input, session, messages });
+    result = await agent.invoke({ input, session, messages, signal });
   } finally {
     delete session._onStream;
     delete session._onStreamReset;
+    if (session._abortSignal === signal) delete session._abortSignal;
   }
   if (result.streamedInline) {
     return streamedContent.trim() || buildLimitedAgentResponse({ input, session }, 'LLM stream ended without content');
@@ -65,6 +68,7 @@ export async function runAgenticLoop(agent, session, initialInput, {
   onActivitiesCompleted = null,
   onMaxTurns = null,
   abortMessage = 'Agent run cancelled.',
+  parallelHandoff = false,
 } = {}) {
   if (!waitForActivities) throw new Error('runAgenticLoop requires waitForActivities.');
   const conversationHistory = [];
@@ -108,13 +112,25 @@ export async function runAgenticLoop(agent, session, initialInput, {
 
     const newPending = newNonTerminalActivities(snapshot, session);
     if (newPending.length === 0) {
-      const pendingSteps = (session.headlessPlan ?? []).filter((step) => step.status === 'pending');
-      if (pendingSteps.length === 0) {
+      // pending_approval is unfinished work too (a request_approval patch op
+      // sets it) — it must not be treated as "nothing left to do" just
+      // because no step is literally 'pending' anymore.
+      const pending = (session.headlessPlan ?? []).filter((step) => step.status === 'pending' || step.status === 'pending_approval');
+      const pendingSteps = readyPlanTasks(session.headlessPlan);
+      if (pending.length === 0) {
         onComplete?.();
         return { ok: true };
       }
+      if (pendingSteps.length === 0) {
+        const reason = pending.every((step) => step.status === 'pending_approval') ? 'awaiting_approval' : 'no_ready_plan_task';
+        onPendingSteps?.({ pendingSteps: pending, blocked: true });
+        return { ok: false, stalled: true, reason };
+      }
+      if (parallelHandoff && pendingSteps.length > 1) {
+        return { ok: true, handoff: true };
+      }
       onPendingSteps?.({ pendingSteps });
-      currentInput = pendingStepsPrompt(initialInput, session.headlessPlan);
+      currentInput = pendingStepsPrompt(initialInput, session.headlessPlan, pendingSteps[0]);
       continue;
     }
 
@@ -132,6 +148,9 @@ export async function runAgenticLoop(agent, session, initialInput, {
     const completed = waitResult.completed ?? [];
     const summary = formatCompletedActivities(completed);
     onActivitiesCompleted?.({ completed, summary });
+    if (parallelHandoff && readyPlanTasks(session.headlessPlan).length > 1) {
+      return { ok: true, handoff: true };
+    }
     currentInput = completedActivitiesPrompt(initialInput, session.headlessPlan, summary);
   }
 
@@ -139,15 +158,18 @@ export async function runAgenticLoop(agent, session, initialInput, {
   return { ok: false, maxTurns: true };
 }
 
-function pendingStepsPrompt(initialInput, plan) {
+function pendingStepsPrompt(initialInput, plan, readyTask) {
   return [
     'Original task:',
     initialInput,
     '',
     `Plan status:\n${formatPlanStatus(plan)}`,
     '',
+    formatReadyTaskPrompt(readyTask),
+    '',
     'No new background activity was started in the previous turn.',
-    'Continue the original plan. Start the next pending step only.',
+    'Continue the original plan. Start exactly this next ready task only.',
+    'Do not start tasks whose dependencies are not done.',
     'If required information is missing and cannot be inferred, stop with a clear blocker.',
   ].join('\n');
 }
@@ -161,7 +183,10 @@ function completedActivitiesPrompt(initialInput, plan, summary) {
     'Completed activities:',
     summary,
     '',
-    'Continue the original plan. Start the next required step only.',
+    formatReadyTaskPrompt(nextReadyPlanTask(plan)),
+    '',
+    'Continue the original plan. Start exactly this next ready task only.',
+    'Do not start tasks whose dependencies are not done.',
     'If all steps are complete, provide the final summary.',
   ].filter(Boolean).join('\n');
 }

package/src/core/mcp.js

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
+const WIKI_MANAGER_VERSION = '0.10.4';
+
 function envValue(key) {
   const filePath = managerEnvFile();
   if (existsSync(filePath)) {
@@ -230,7 +232,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
           params: {
             protocolVersion: '2025-06-18',
             capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: '0.8.2' },
+            clientInfo: { name: 'wiki-manager', version: WIKI_MANAGER_VERSION },
           },
         }),
       });

package/src/core/plan.js

@@ -15,6 +15,10 @@ export function ensurePlanFromActivity(session, activity) {
       id: s.id ?? null,
       description: s.label,
       status: 'pending',
+      dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn.map(String) : [],
+      executor: s.executor ?? null,
+      executorQuery: s.executorQuery ?? null,
+      outputRefs: Array.isArray(s.outputRefs) ? s.outputRefs.map(String) : [],
       owner: 'activity',
       ownerActivityKey: activity.key,
       _activityKey: activity.key,