@dotdrelle/wiki-manager 0.11.0 → 0.11.6

package/src/runtime/client.js

@@ -97,6 +97,18 @@ export async function postRuntimeCancel({
   return response.json();
 }
 
+export async function postRuntimeShutdown({
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/shutdown'), {
+    method: 'POST',
+    headers: runtimeHeaders(token),
+  });
+  if (!response.ok) throw new Error(`Runtime shutdown failed: HTTP ${response.status}`);
+  return response.json();
+}
+
 export async function postRuntimeResume({
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),

package/src/runtime/donna-contract.test.js

@@ -0,0 +1,359 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
+import { runRuntimeAgenticWorkflow } from './runner.js';
+import { startRuntimeServer } from './server.js';
+
+// Executable version of plan-0.11.5-hotfix-final.md §3 ("La recette — le seul
+// critère de sortie qui compte"). Each test below is one row of that table,
+// referenced by its recipe number. Correctifs 1-3 and 8 (runner.js's
+// conversational short-circuit, plan sanitization, and no-replan-on-vague
+// paths) are exercised with a mocked agent standing in for the LLM's
+// per-turn decision, exactly like the existing runner.test.js unit tests --
+// this file's job is traceability to the recipe, not a new test seam.
+// Recipes 4-6 drive the real scheduler (runAgenticLoop / runRuntimeParallelPlan,
+// imported and executed for real, never reimplemented). Recipe 7 drives the
+// real control-lane HTTP endpoint. Per plan §4.1: this file is the CI gate --
+// no release ships while it is red.
+
+function baseSession(overrides = {}) {
+  return { activities: {}, headlessPlan: null, ...overrides };
+}
+
+function eventTypes(session) {
+  return (session.agentEvents ?? []).map((event) => event.type);
+}
+
+async function waitFor(predicate, timeoutMs = 500) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((resolve) => setTimeout(resolve, 1));
+  }
+  assert.fail('condition was not met before timeout');
+}
+
+test('Recipe #1 — "salut" gets a plain reply: no plan, no activity, no job, run done', async () => {
+  const session = baseSession({
+    llm: {
+      async completeWithTools() {
+        assert.fail('a plain greeting must never reach the evaluator or replanner');
+      },
+    },
+  });
+  const agent = {
+    async invoke() {
+      return { response: 'Bonjour ! Comment puis-je vous aider ?' };
+    },
+  };
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'salut', {
+    runId: 'recipe-1',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    maxReplans: 1,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(session.headlessPlan, null);
+  assert.equal(Object.keys(session.activities).length, 0);
+  const types = eventTypes(session);
+  assert.ok(types.includes('run_done'));
+  assert.equal(types.includes('run_evaluated'), false);
+  assert.equal(types.includes('run_replanned'), false);
+  assert.equal(types.includes('tool_call_started'), false);
+  assert.equal(types.includes('plan_set'), false);
+});
+
+test('Recipe #2 — "quel est le profil actif ?" answers in conversation, never poses a plan', async () => {
+  const session = baseSession({
+    llm: {
+      async completeWithTools() {
+        assert.fail('a read-only config question must never reach the evaluator or replanner');
+      },
+    },
+  });
+  const agent = {
+    async invoke({ session: turnSession }) {
+      dispatchAgentEvent(turnSession, createAgentEvent('tool_call_started', {
+        origin: 'tool',
+        payload: { name: 'shell.status', args: '{}', summary: 'calling...' },
+      }));
+      dispatchAgentEvent(turnSession, createAgentEvent('tool_call_result', {
+        origin: 'tool',
+        payload: { name: 'shell.status', ok: true, result: 'profile: albert-openai (mistral-large)', summary: 'done' },
+      }));
+      return { response: 'Le profil actif est albert-openai (mistral-large).' };
+    },
+  };
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'quel est le profil actif ?', {
+    runId: 'recipe-2',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    maxReplans: 1,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(session.headlessPlan, null);
+  const types = eventTypes(session);
+  assert.ok(types.includes('tool_call_started'));
+  assert.ok(types.includes('run_done'));
+  assert.equal(types.includes('plan_set'), false);
+  assert.equal(types.includes('run_evaluated'), false);
+});
+
+test('Recipe #3 — "où en est le dernier build ?" reads status, starts no new production run', async () => {
+  const session = baseSession({
+    llm: {
+      async completeWithTools() {
+        assert.fail('a status question must never reach the evaluator or replanner');
+      },
+    },
+  });
+  const agent = {
+    async invoke({ session: turnSession }) {
+      dispatchAgentEvent(turnSession, createAgentEvent('tool_call_started', {
+        origin: 'tool',
+        payload: { name: 'production.production_job_status', args: '{}', summary: 'calling...' },
+      }));
+      dispatchAgentEvent(turnSession, createAgentEvent('tool_call_result', {
+        origin: 'tool',
+        payload: { name: 'production.production_job_status', ok: true, result: 'last build: done', summary: 'done' },
+      }));
+      return { response: 'Le dernier build est terminé avec succès.' };
+    },
+  };
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'où en est le dernier build ?', {
+    runId: 'recipe-3',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    maxReplans: 1,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(session.headlessPlan, null);
+  assert.equal(Object.keys(session.activities).length, 0);
+  const types = eventTypes(session);
+  assert.equal(types.includes('activity_upserted'), false);
+  assert.equal(types.includes('plan_set'), false);
+});
+
+function buildSingleTaskAgent({ taskId, description, finalResponse }) {
+  let turn = 0;
+  return {
+    async invoke({ session: turnSession }) {
+      turn += 1;
+      if (turn === 1) {
+        dispatchAgentEvent(turnSession, createAgentEvent('plan_set', {
+          origin: 'tool',
+          payload: { steps: [{ step: 1, id: taskId, description, status: 'pending', dependsOn: [] }] },
+        }));
+        return { response: `Je lance ${description}.` };
+      }
+      dispatchAgentEvent(turnSession, createAgentEvent('plan_step_updated', {
+        origin: 'tool',
+        payload: { step: 1, status: 'done' },
+      }));
+      return { response: finalResponse };
+    },
+  };
+}
+
+test('Recipe #4 — "lance le doctor": one-task plan, progress visible, summarized result', async () => {
+  const session = baseSession();
+  const agent = buildSingleTaskAgent({
+    taskId: 'doctor',
+    description: 'Diagnostic doctor',
+    finalResponse: 'Doctor terminé : aucun problème détecté.',
+  });
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'lance le doctor', {
+    runId: 'recipe-4',
+    timeoutMs: 1000,
+    maxTurns: 3,
+    maxReplans: 1,
+    evaluate: false,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(session.headlessPlan.length, 1);
+  assert.equal(session.headlessPlan[0].status, 'done');
+  const types = eventTypes(session);
+  assert.deepEqual(types.filter((type) => type === 'plan_set' || type === 'plan_step_updated'), ['plan_set', 'plan_step_updated']);
+  assert.ok(types.includes('run_done'));
+  assert.equal(session.agentProjection.conversation.at(-1).content, 'Doctor terminé : aucun problème détecté.');
+});
+
+test('Recipe #5 — "construis le livrable X": plan posed, job runs, progress, done, summarized', async () => {
+  const session = baseSession();
+  const agent = buildSingleTaskAgent({
+    taskId: 'build-x',
+    description: 'Construire le livrable X',
+    finalResponse: 'Le livrable X est construit.',
+  });
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'construis le livrable X', {
+    runId: 'recipe-5',
+    timeoutMs: 1000,
+    maxTurns: 3,
+    maxReplans: 1,
+    evaluate: false,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(session.headlessPlan[0].status, 'done');
+  assert.ok(eventTypes(session).includes('run_done'));
+  assert.equal(session.agentProjection.conversation.at(-1).content, 'Le livrable X est construit.');
+});
+
+function buildTwoParallelTasksAgent() {
+  const started = [];
+  const release = {};
+  let parentTurnDone = false;
+  return {
+    started,
+    release,
+    async invoke({ input, session: turnSession }) {
+      const taskMatch = input.match(/Task id: (\w+)/);
+      if (!taskMatch) {
+        if (!parentTurnDone) {
+          parentTurnDone = true;
+          dispatchAgentEvent(turnSession, createAgentEvent('plan_set', {
+            origin: 'tool',
+            payload: {
+              steps: [
+                { step: 1, id: 'x', description: 'Construire X', status: 'pending', dependsOn: [] },
+                { step: 2, id: 'y', description: 'Construire Y', status: 'pending', dependsOn: [] },
+              ],
+            },
+          }));
+          return { response: 'Je construis X et Y en parallèle.' };
+        }
+        return { response: 'X et Y sont construits.' };
+      }
+      const id = taskMatch[1];
+      started.push(id);
+      await new Promise((resolve) => { release[id] = resolve; });
+      return { response: `${id} construit.` };
+    },
+  };
+}
+
+test('Recipe #6 — "construis X et Y": two tasks run in parallel, converge, done', async () => {
+  const session = baseSession();
+  const agent = buildTwoParallelTasksAgent();
+
+  const running = runRuntimeAgenticWorkflow(agent, session, 'construis X et Y', {
+    runId: 'recipe-6',
+    timeoutMs: 2000,
+    maxTurns: 3,
+    maxReplans: 1,
+    evaluate: false,
+  });
+
+  await waitFor(() => agent.started.includes('x') && agent.started.includes('y'));
+  assert.deepEqual(
+    session.headlessPlan.filter((step) => ['x', 'y'].includes(step.id)).map((step) => step.status),
+    ['running', 'running'],
+  );
+  agent.release.x();
+  agent.release.y();
+
+  const result = await running;
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done']);
+});
+
+test('Recipe #7 — "où en es-tu ?" during an active run: status in conversation, run continues, no new run', async (t) => {
+  const session = { workspace: 'juno', controlQueue: [] };
+  let runCount = 0;
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({
+          status: 'running',
+          plan: [{ step: 1, description: 'Construire le livrable X', status: 'running' }],
+          queue: [],
+          approvals: [],
+          summary: null,
+        }),
+        listEvents: () => [],
+      },
+      getContext: async () => ({
+        workspace: 'juno',
+        session,
+        running: true,
+        currentAbortController: new AbortController(),
+      }),
+      run: async () => { runCount += 1; },
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${handle.port}/control?workspace=juno`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'message', input: 'où en es-tu ?' }),
+    });
+    assert.equal(response.status, 200);
+    const body = await response.json();
+    assert.equal(body.kind, 'observe');
+    assert.match(body.explanation, /Construire le livrable X/);
+    assert.equal(session.controlQueue.length, 0);
+    assert.equal(runCount, 0);
+  } finally {
+    await handle.close();
+  }
+});
+
+test('Recipe #8 — vague request gets clarification, never a job, never boilerplate', async () => {
+  const session = baseSession({
+    headlessPlan: [{ step: 1, id: 'task', description: 'Task', status: 'done' }],
+    llm: {
+      async completeWithTools({ system }) {
+        assert.match(system, /strict evaluator/);
+        return { content: '{"ok":false,"reason":"demande vague / objectif indefini","suggestedAction":"clarifier l objectif"}' };
+      },
+    },
+  });
+  const agent = {
+    async invoke({ session: turnSession }) {
+      if (turnSession.headlessPlan === null) {
+        dispatchAgentEvent(turnSession, createAgentEvent('plan_set', {
+          origin: 'tool',
+          payload: { steps: [{ step: 1, id: 'task', description: 'Task', status: 'done' }] },
+        }));
+      }
+      return { response: 'Terminé.' };
+    },
+  };
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'dis-moi une bêtise puis stop', {
+    runId: 'recipe-8',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    maxReplans: 1,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.clarified, true);
+  const lastMessage = session.agentProjection.conversation.at(-1).content;
+  assert.ok(lastMessage.includes('clarifier'));
+  assert.doesNotMatch(lastMessage, /Donna is active|Plan is stalled/i);
+  const types = eventTypes(session);
+  assert.equal(types.includes('run_replanned'), false);
+  assert.equal(types.includes('tool_call_started'), false);
+});

package/src/runtime/lifecycle.js

@@ -33,7 +33,7 @@ export async function assertRuntimeNode(executable = runtimeNodeExecutable()) {
 }
 
 export async function ensureRuntime({
-  host = process.env.WIKI_MANAGER_RUNTIME_HOST ?? '0.0.0.0',
+  host = process.env.WIKI_MANAGER_RUNTIME_HOST ?? '127.0.0.1',
   port = Number(process.env.WIKI_MANAGER_RUNTIME_PORT ?? 7788),
   stateDir = process.env.WIKI_MANAGER_STATE_DIR ?? defaultRuntimeStateDir(),
   url = process.env.WIKI_MANAGER_RUNTIME_URL ?? `http://127.0.0.1:${port}`,

package/src/runtime/runner.e2e.test.js

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { runRuntimeParallelPlan } from './runner.js';
+
+// Regression guard for plan-0.11.4-stabilisation.md §3: build de 2 templates
+// en séquentiel -> T1, en multi-agent -> T2, assert T2 < 0.65*T1. Exercises
+// the scheduler (runRuntimeParallelPlan) directly with mocked, fixed-latency
+// tasks — it proves the scheduler itself parallelizes ready tasks, not that a
+// real llm-wiki build/provider round-trip shows the same margin.
+const SIMULATED_BUILD_LATENCY_MS = 150;
+const MAX_PARALLEL_TO_SEQUENTIAL_RATIO = 0.65;
+
+function buildTwoTemplatePlan() {
+  return [
+    { step: 1, id: 'template-a', description: 'Build template A', status: 'pending', dependsOn: [] },
+    { step: 2, id: 'template-b', description: 'Build template B', status: 'pending', dependsOn: [] },
+  ];
+}
+
+function latencyAgent() {
+  return {
+    async invoke() {
+      await new Promise((resolve) => setTimeout(resolve, SIMULATED_BUILD_LATENCY_MS));
+      return { response: 'done' };
+    },
+  };
+}
+
+async function timedRun(concurrency, runId) {
+  const session = { activities: {}, headlessPlan: buildTwoTemplatePlan() };
+  const startedAt = Date.now();
+  const result = await runRuntimeParallelPlan(latencyAgent(), session, 'Build 2 templates', {
+    runId,
+    timeoutMs: 10_000,
+    maxTurns: 1,
+    concurrency,
+  });
+  return { result, durationMs: Date.now() - startedAt };
+}
+
+test('multi-agent scheduler beats sequential on 2 independent build tasks by the required margin (plan 0.11.4 §3 guard)', async () => {
+  const { result: sequentialResult, durationMs: sequentialDurationMs } = await timedRun(1, 'e2e-accel-sequential');
+  const { result: parallelResult, durationMs: parallelDurationMs } = await timedRun(2, 'e2e-accel-parallel');
+
+  assert.equal(sequentialResult.ok, true);
+  assert.equal(parallelResult.ok, true);
+  const thresholdMs = MAX_PARALLEL_TO_SEQUENTIAL_RATIO * sequentialDurationMs;
+  assert.ok(
+    parallelDurationMs < thresholdMs,
+    `expected multi-agent duration (${parallelDurationMs}ms) under ${MAX_PARALLEL_TO_SEQUENTIAL_RATIO * 100}% of sequential duration (${sequentialDurationMs}ms, threshold ${thresholdMs}ms)`,
+  );
+});

package/src/runtime/runner.js

@@ -2,7 +2,7 @@ import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { activityKey, sessionActivities, terminalFailures } from '../core/activity.js';
 import { runAgenticLoop, throwIfAborted } from '../core/agentLoop.js';
 import { formatPlanStatus } from '../core/plan.js';
-import { formatReadyTaskPrompt, readyPlanTasks } from '../core/planPatch.js';
+import { formatReadyTaskPrompt, readyPlanTasks, sanitizePlanForExecution } from '../core/planPatch.js';
 import { emitRuntimeLog, pollActivitiesOnce } from './supervisor.js';
 
 const DEFAULT_MAX_REPLANS = 2;
@@ -92,6 +92,7 @@ export async function runRuntimeAgenticWorkflow(agent, session, input, {
   let replansLeft = Math.max(0, Math.floor(Number(maxReplans) || 0));
 
   while (true) {
+    sanitizeSessionPlanForExecution(session, runId);
     const result = shouldUseParallelScheduler(session.headlessPlan)
       ? await runRuntimeParallelPlan(agent, session, input, {
         signal,
@@ -134,7 +135,9 @@ export async function runRuntimeAgenticWorkflow(agent, session, input, {
       return { ok: false, result };
     }
 
-    const evaluation = await evaluateRuntimeRun(session, input, { runId, signal, evaluate });
+    const evaluation = session.headlessPlan
+      ? await evaluateRuntimeRun(session, input, { runId, signal, evaluate })
+      : null;
     if (evaluation) {
       dispatchAgentEvent(session, createAgentEvent('run_evaluated', {
         origin: 'runtime',
@@ -147,6 +150,19 @@ export async function runRuntimeAgenticWorkflow(agent, session, input, {
         },
       }));
       if (!evaluation.ok) {
+        if (isUndefinedObjectiveEvaluation(evaluation)) {
+          dispatchAgentEvent(session, createAgentEvent('assistant_message', {
+            origin: 'runtime',
+            runId,
+            payload: { content: clarificationMessageForEvaluation(evaluation) },
+          }));
+          dispatchAgentEvent(session, createAgentEvent('run_done', {
+            origin: 'runtime',
+            runId,
+            payload: { runId },
+          }));
+          return { ok: true, evaluation, clarified: true };
+        }
         if (replansLeft > 0) {
           const trigger = {
             kind: 'evaluation',
@@ -199,11 +215,17 @@ export async function runRuntimeParallelPlan(agent, session, input, {
   const locks = new Set();
   const failures = [];
   const previousIdentity = session._currentRunIdentity;
+  const previousPlanUpdate = session._onPlanUpdate;
   session._currentRunIdentity = {
     ...(previousIdentity ?? {}),
     runId,
     workspace: session.workspace ?? previousIdentity?.workspace ?? null,
   };
+  session._onPlanUpdate = () => {
+    previousPlanUpdate?.();
+    abortCancelledActiveTasks(session, active);
+  };
+  sanitizeSessionPlanForExecution(session, runId);
   ensurePlanProjection(session, runId);
   emitRuntimeLog(session, `scheduler: parallel plan enabled (concurrency ${limit})`);
 
@@ -238,11 +260,15 @@ export async function runRuntimeParallelPlan(agent, session, input, {
       }
 
       const settled = await Promise.race([...active.values()].map((entry) => entry.promise));
+      const activeEntry = active.get(settled.taskId);
       active.delete(settled.taskId);
+      activeEntry?.cleanup?.();
       for (const lock of settled.locks) locks.delete(lock);
       if (settled.cancelled) {
-        await drainActive(active, locks);
-        throwIfAborted(signal, 'Runtime run cancelled.');
+        if (signal?.aborted) {
+          await drainActive(active, locks);
+          throwIfAborted(signal, 'Runtime run cancelled.');
+        }
         continue;
       }
       if (!settled.ok) failures.push(settled);
@@ -250,16 +276,43 @@ export async function runRuntimeParallelPlan(agent, session, input, {
   } finally {
     if (previousIdentity) session._currentRunIdentity = previousIdentity;
     else delete session._currentRunIdentity;
+    if (previousPlanUpdate) session._onPlanUpdate = previousPlanUpdate;
+    else delete session._onPlanUpdate;
   }
 }
 
+function sanitizeSessionPlanForExecution(session, runId = null) {
+  if (!session.headlessPlan) return;
+  const sanitized = sanitizePlanForExecution(session.headlessPlan);
+  if (sanitized.warnings.length === 0) return;
+  session.headlessPlan = sanitized.plan;
+  dispatchAgentEvent(session, createAgentEvent('runtime_log', {
+    origin: 'runtime',
+    runId,
+    payload: {
+      message: `plan warning: ${sanitized.warnings.join('; ')}`,
+    },
+  }));
+}
+
 async function drainActive(active, locks) {
   if (active.size === 0) return;
-  await Promise.all([...active.values()].map((entry) => entry.promise));
+  const entries = [...active.values()];
+  await Promise.all(entries.map((entry) => entry.promise));
+  for (const entry of entries) entry.cleanup?.();
   active.clear();
   locks.clear();
 }
 
+function abortCancelledActiveTasks(session, active) {
+  for (const [taskId, entry] of active.entries()) {
+    const current = (session.headlessPlan ?? []).find((step) => planTaskId(step) === taskId);
+    if (current?.status === 'cancelled' && !entry.signal?.aborted) {
+      entry.controller?.abort();
+    }
+  }
+}
+
 // Scope the evaluator/replanner's view of "completed" activities to the
 // tasks that actually failed, instead of every activity the whole run has
 // ever recorded — a long-running sibling's stale (or unrelated, already
@@ -323,20 +376,44 @@ function startReadyTasks(agent, session, input, {
       payload: { taskId, status: 'running' },
     }));
     emitRuntimeLog(session, `scheduler: starting task ${taskId}`);
+    const taskAbort = createTaskAbortSignal(signal);
     const promise = runParallelTask(agent, session, input, task, {
-      signal,
+      signal: taskAbort.signal,
       timeoutMs,
       maxTurns,
       runId,
       pollBusy,
       locks: taskLocks,
     });
-    active.set(taskId, { taskId, locks: taskLocks, promise });
+    active.set(taskId, {
+      taskId,
+      locks: taskLocks,
+      promise,
+      controller: taskAbort.controller,
+      signal: taskAbort.signal,
+      cleanup: taskAbort.cleanup,
+    });
     started += 1;
   }
   return started;
 }
 
+function createTaskAbortSignal(parentSignal) {
+  const controller = new AbortController();
+  if (!parentSignal) return { controller, signal: controller.signal, cleanup: null };
+  if (parentSignal.aborted) {
+    controller.abort();
+    return { controller, signal: controller.signal, cleanup: null };
+  }
+  const abort = () => controller.abort();
+  parentSignal.addEventListener('abort', abort, { once: true });
+  return {
+    controller,
+    signal: controller.signal,
+    cleanup: () => parentSignal.removeEventListener('abort', abort),
+  };
+}
+
 async function runParallelTask(agent, parentSession, input, task, {
   signal,
   timeoutMs,
@@ -364,6 +441,9 @@ async function runParallelTask(agent, parentSession, input, task, {
       }));
       return { ok: false, taskId, locks, result };
     }
+    if ((parentSession.headlessPlan ?? []).find((step) => planTaskId(step) === taskId)?.status === 'cancelled') {
+      return { ok: false, taskId, locks, cancelled: true };
+    }
     dispatchAgentEvent(parentSession, createAgentEvent('plan_step_updated', {
       origin: 'runtime',
       runId,
@@ -521,7 +601,9 @@ export async function finishRuntimeRun(session, input, {
   signal = null,
   evaluate = true,
 } = {}) {
-  const evaluation = await evaluateRuntimeRun(session, input, { runId, signal, evaluate });
+  const evaluation = session.headlessPlan
+    ? await evaluateRuntimeRun(session, input, { runId, signal, evaluate })
+    : null;
   if (evaluation) {
     dispatchAgentEvent(session, createAgentEvent('run_evaluated', {
       origin: 'runtime',
@@ -534,6 +616,19 @@ export async function finishRuntimeRun(session, input, {
       },
     }));
     if (!evaluation.ok) {
+      if (isUndefinedObjectiveEvaluation(evaluation)) {
+        dispatchAgentEvent(session, createAgentEvent('assistant_message', {
+          origin: 'runtime',
+          runId,
+          payload: { content: clarificationMessageForEvaluation(evaluation) },
+        }));
+        dispatchAgentEvent(session, createAgentEvent('run_done', {
+          origin: 'runtime',
+          runId,
+          payload: { runId },
+        }));
+        return { ok: true, evaluation, clarified: true };
+      }
       dispatchAgentEvent(session, createAgentEvent('run_error', {
         origin: 'runtime',
         runId,
@@ -623,6 +718,21 @@ function normalizeEvaluation(value) {
   };
 }
 
+function isUndefinedObjectiveEvaluation(evaluation) {
+  const text = `${evaluation?.reason ?? ''} ${evaluation?.suggestedAction ?? ''}`
+    .toLowerCase()
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '');
+  return /\b(vague|undefined|indefini|unclear|clarif|ambiguous|missing objective|no objective)\b/.test(text);
+}
+
+function clarificationMessageForEvaluation(evaluation) {
+  const reason = String(evaluation?.reason ?? '').trim();
+  return reason
+    ? `Je dois clarifier la demande avant d'agir : ${reason}`
+    : "Je dois clarifier la demande avant d'agir.";
+}
+
 function fallbackEvaluation(reason) {
   return {
     ok: true,
@@ -674,6 +784,10 @@ export async function replanRuntimeRun(session, input, trigger, {
         steps: mergedSteps,
       },
     }));
+    if (hasMutatingReplanStep(steps)) {
+      session._runApprovalRequired = true;
+      session._runApprovalResolved = false;
+    }
     return { ok: true, steps };
   } catch (err) {
     return { ok: false, reason: err instanceof Error ? err.message : String(err) };
@@ -762,6 +876,10 @@ function normalizeReplan(steps) {
     .slice(0, 12);
 }
 
+function hasMutatingReplanStep(steps) {
+  return steps.some((step) => /\b(build|copy|ingest|import|export|polish|pipeline|write|create|delete|update|send|deploy|publish|generate|construire|copier|importer|exporter|publier|envoyer|supprimer|modifier|creer|générer|generer)\b/i.test(step));
+}
+
 function mergeReplanWithCompleted(plan, steps) {
   const completed = (plan ?? [])
     .filter((step) => step.status === 'done')