@dotdrelle/wiki-manager 0.15.40 → 0.15.41

package/src/orchestrator/agentRegistry.js

@@ -4,6 +4,56 @@ import { assertContract } from '../contracts/schemas.js';
 
 const AVAILABLE = 'available';
 const UNAVAILABLE = 'unavailable';
+/**
+ * Santé d'un agent restauré depuis le journal, tant qu'aucun `agent_describe`
+ * n'a réussi dans le processus courant.
+ *
+ * Ni `available` ni `unavailable` : on ne SAIT pas. Le distinguer de
+ * `unavailable` a une conséquence pratique — un agent inconnu redevient
+ * disponible en silence dès le premier scan réussi, là où un agent déclaré
+ * indisponible mériterait d'être signalé comme tel à l'utilisateur.
+ */
+const UNKNOWN = 'unknown';
+
+/**
+ * Un agent persisté n'est pas un agent joignable.
+ *
+ * Au redémarrage, `hydrateSession` rejoue le journal d'événements et
+ * reconstruit les agents avec la santé qu'ils avaient AU MOMENT où l'événement
+ * a été écrit. `cme-main` réapparaissait donc `available` alors que son
+ * endpoint n'existe plus, était retenu comme fournisseur, et la tâche partait
+ * vers un agent absent — la panne observée le 2026-08-04.
+ *
+ * La persistance dit ce qui a existé, pas ce qui répond maintenant. Seul un
+ * `agent_describe` réussi dans ce processus autorise à parler de disponibilité.
+ */
+export function markPersistedAgentsStale(session) {
+  if (!session || typeof session !== 'object') return [];
+  const stale = (agent) => ({
+    ...agent,
+    health: UNKNOWN,
+    stale: true,
+    // La santé d'origine est conservée : elle raconte ce qu'on savait avant
+    // l'arrêt, ce qui aide à lire un journal, sans jamais servir au routage.
+    healthBeforeRestart: agent?.health ?? null,
+  });
+  /*
+   TOUTES les représentations restaurées, `agentRegistrySnapshot` compris.
+
+   J'avais d'abord épargné le snapshot, au motif qu'il pouvait porter un scan
+   vivant. C'était une inversion : à l'hydratation, aucun scan n'a encore eu
+   lieu — l'ordre est hydrate → invalidate → discover, et rien ne s'exécute
+   entre les deux premiers. Le snapshot vient donc de la même projection
+   persistée que `session.agents`. L'épargner laissait `cme-main` routable avec
+   son endpoint éteint, ce que la validation à chaud a montré.
+
+   Le seul scan qui compte est celui qui suivra : `discover()` réécrit le
+   snapshot en entier à partir des `agent_describe` réussis.
+  */
+  session.agents = (session.agents ?? []).map(stale);
+  session.agentRegistrySnapshot = (session.agentRegistrySnapshot ?? []).map(stale);
+  return session.agentRegistrySnapshot;
+}
 
 export function createAgentRegistry({
   callTool = callMcpTool,

package/src/orchestrator/agentRegistry.test.js

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { createAgentRegistry } from './agentRegistry.js';
+import { createAgentRegistry, markPersistedAgentsStale } from './agentRegistry.js';
+import { createCapabilityRegistry } from './capabilityRegistry.js';
 
 function description({ agentInstanceId = 'production-main', health = 'available', contractVersion = '1' } = {}) {
   return {
@@ -205,3 +206,77 @@ test('discovery sends no workspace argument when no workspace is active', async
 
   assert.deepEqual(seen, [{}]);
 });
+
+/*
+ Cas observé le 2026-08-04 : après redémarrage du runtime, `cme-main` était
+ toujours présenté `available` alors que son endpoint n'existait plus. La
+ relecture du journal restitue la santé qu'un agent avait AU MOMENT où
+ l'événement a été écrit — la persistance dit ce qui a existé, pas ce qui
+ répond maintenant.
+*/
+test('un agent restauré depuis le journal n’est pas déclaré disponible', () => {
+  const session = {
+    agents: [
+      { agentInstanceId: 'cme-main', serverName: 'cme', health: 'available', description: { contractVersion: '1', capabilities: [{ id: 'external-source.export', version: '1' }] } },
+      { agentInstanceId: 'production-main', serverName: 'production', health: 'available', description: { contractVersion: '1', capabilities: [{ id: 'knowledge.update', version: '1' }] } },
+    ],
+  };
+
+  markPersistedAgentsStale(session);
+
+  for (const agent of session.agents) {
+    assert.equal(agent.health, 'unknown');
+    assert.equal(agent.stale, true);
+    // Ce qu'on savait avant l'arrêt reste lisible, sans jamais servir au routage.
+    assert.equal(agent.healthBeforeRestart, 'available');
+  }
+  // Et surtout : plus aucun fournisseur sélectionnable tant que le scan n'a pas
+  // confirmé. C'est la seule chose qui empêche une tâche de partir vers un
+  // agent absent.
+  const registry = createCapabilityRegistry({ agents: session.agents });
+  assert.deepEqual(registry.providersFor('external-source.export'), []);
+  assert.deepEqual(registry.providersFor('knowledge.update'), []);
+});
+
+test('markPersistedAgentsStale invalide aussi l’instantané routable', () => {
+  /*
+   J'avais d'abord épargné `agentRegistrySnapshot`, au motif qu'il pouvait
+   porter un scan vivant. Inversion : à l'hydratation aucun scan n'a eu lieu,
+   l'ordre étant hydrate → invalidate → discover. L'épargner laissait
+   `cme-main` routable avec son endpoint éteint — constaté à chaud.
+  */
+  const session = {
+    agents: [{ agentInstanceId: 'cme-main', health: 'available' }],
+    agentRegistrySnapshot: [{ agentInstanceId: 'cme-main', health: 'available' }],
+  };
+
+  markPersistedAgentsStale(session);
+
+  assert.equal(session.agents[0].health, 'unknown');
+  assert.equal(session.agentRegistrySnapshot[0].health, 'unknown');
+});
+
+test('un agent redevient sélectionnable après un agent_describe réussi', async () => {
+  const session = {
+    workspace: 'juno',
+    agentEvents: [],
+    agents: [{ agentInstanceId: 'production-main', serverName: 'production', health: 'available', description: { contractVersion: '1', capabilities: [{ id: 'knowledge.update', version: '1' }] } }],
+    mcp: {
+      production: { status: 'connected', tools: [{ name: 'agent_describe' }] },
+    },
+  };
+  markPersistedAgentsStale(session);
+  assert.deepEqual(createCapabilityRegistry({ agents: session.agents }).providersFor('knowledge.update'), []);
+
+  const registry = createAgentRegistry({
+    callTool: async () => ({ content: [{ type: 'text', text: JSON.stringify(description()) }] }),
+  });
+  await registry.discover(session);
+
+  // La reconnexion suffit : aucune intervention, aucun redémarrage.
+  assert.equal(session.agentRegistrySnapshot[0].health, 'available');
+  assert.equal(
+    createCapabilityRegistry({ agents: session.agentRegistrySnapshot }).providersFor('knowledge.update').length,
+    1,
+  );
+});

package/src/orchestrator/approvalPolicy.js

@@ -1,9 +1,9 @@
 import { randomUUID } from 'node:crypto';
+import { isTerminal } from './taskStatuses.js';
 
 export const APPROVAL_DEFAULT_CLASS = 'default';
 
 const GRANTED_STATUSES = new Set(['approved', 'granted']);
-const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'error', 'complete', 'completed', 'success']);
 
 export function approvalClassForTask(task) {
   return String(task?.approvalClass ?? task?.mutationClass ?? APPROVAL_DEFAULT_CLASS);
@@ -74,7 +74,7 @@ export function applyApprovalCoverage(tasks = [], {
 } = {}) {
   const requested = [];
   for (const task of tasks) {
-    if (task?.requiresApproval !== true || TERMINAL_STATUSES.has(String(task.status ?? '').toLowerCase())) continue;
+    if (task?.requiresApproval !== true || isTerminal(task.status)) continue;
     const covered = approvalCovered(task, approvals, { runId, workspaceId, planRevision });
     if (!covered) {
       task.status = 'waiting_approval';

package/src/orchestrator/dependencyResolver.js

@@ -1,11 +1,11 @@
 import { locksForTask } from './lockManager.js';
 import { approvalCovered } from './approvalPolicy.js';
-
-const DONE_STATUSES = new Set(['done', 'completed', 'complete', 'success', 'succeeded']);
-const TERMINAL_STATUSES = new Set([...DONE_STATUSES, 'failed', 'cancelled', 'canceled', 'skipped']);
-// A task in one of these statuses hasn't run yet but could become ready —
-// shared with runner.js's scheduler-stall check so the two can't drift apart.
-export const PENDING_STATUSES = new Set(['pending', 'pending_approval', 'waiting_approval']);
+import { isPending, isSuccessful, isTerminal, isUnsuccessfulTerminal } from './taskStatuses.js';
+// Une tâche dans un de ces statuts n'a pas encore tourné mais peut le devenir.
+// Réexporté depuis le vocabulaire commun : l'ordonnanceur et le contrôle de
+// blocage du runner doivent tester la même chose, et un ensemble local ici
+// était précisément le moyen de les faire diverger.
+export { isPending } from './taskStatuses.js';
 
 export function readyTasks(dag, {
   registry = null,
@@ -15,13 +15,13 @@ export function readyTasks(dag, {
   activeTaskIds = [],
 } = {}) {
   const tasks = normalizeTasks(dag);
-  const done = new Set(tasks.filter((task) => DONE_STATUSES.has(statusOf(task))).map(taskId));
+  const done = new Set(tasks.filter((task) => isSuccessful(statusOf(task))).map(taskId));
   const active = new Set([...activeTaskIds].map(String));
   return tasks
     .filter((task) => {
       const status = statusOf(task);
       return status === 'pending'
-        || (PENDING_STATUSES.has(status)
+        || (isPending(status)
           && approvalCovered(task, approvals, {
             runId: task?.runId ?? dag?.runId ?? null,
             workspaceId: dag?.workspace ?? null,
@@ -40,9 +40,9 @@ export function readyTasks(dag, {
 
 export function tasksAwaitingApproval(dag, { approvals = [] } = {}) {
   const tasks = normalizeTasks(dag);
-  const done = new Set(tasks.filter((task) => DONE_STATUSES.has(statusOf(task))).map(taskId));
+  const done = new Set(tasks.filter((task) => isSuccessful(statusOf(task))).map(taskId));
   return tasks
-    .filter((task) => PENDING_STATUSES.has(statusOf(task)))
+    .filter((task) => isPending(statusOf(task)))
     .filter((task) => task?.requiresApproval === true)
     .filter((task) => !approvalCovered(task, approvals, {
       runId: task?.runId ?? dag?.runId ?? null,
@@ -64,12 +64,52 @@ function dependenciesDone(task, done) {
   return dependsOn(task).every((dep) => done.has(String(dep)));
 }
 
+/*
+ Une barrière de groupe attend que le groupe soit FINI, pas qu'il soit parfait.
+
+ Elle exigeait que chaque membre soit `done`. Un seul échec la fermait donc
+ définitivement : sur une ingestion de dix fichiers dont neuf réussissent, la
+ suite du plan n'était jamais débloquée et le run restait `running` pour
+ toujours. Un incident sur un document devenait une panne totale — le coût
+ était sans rapport avec le dégât.
+
+ La barrière s'ouvre donc quand tout le groupe est TERMINAL. Ce que valait
+ réellement la garantie « tout est done » est préservé ailleurs, et plus
+ finement : une tâche qui dépend explicitement d'une tâche en échec reste
+ bloquée par `dependenciesDone`, et le planificateur la marque `skipped`
+ (cf. blockedByFailedDependency). On distingue ainsi « la suite ne peut pas se
+ faire » de « la suite peut se faire sur ce qui a réussi ».
+*/
 function groupBarrierSatisfied(task, tasks) {
   const groupId = task?.dependsOnGroup;
   if (groupId == null || groupId === '') return true;
   const groupTasks = tasks.filter((candidate) => taskGroupId(candidate) === String(groupId));
   if (groupTasks.length === 0) return false;
-  return groupTasks.every((candidate) => DONE_STATUSES.has(statusOf(candidate)));
+  return groupTasks.every((candidate) => isTerminal(statusOf(candidate)));
+}
+
+/**
+ * Tâches en attente qui ne deviendront JAMAIS exécutables, parce qu'une de
+ * leurs dépendances directes est terminale sans avoir réussi.
+ *
+ * Sans cette liste, le planificateur ne pouvait que constater « plus aucune
+ * tâche prête » et déclarer le plan bloqué — ce qui déclenchait une
+ * replanification, donc un run qui ne se termine pas. Les nommer permet de les
+ * marquer `skipped` avec leur motif, de finaliser le run sur un résultat
+ * partiel, et de dire à l'utilisateur ce qui n'a pas été fait et pourquoi.
+ */
+export function blockedByFailedDependency(dag) {
+  const tasks = normalizeTasks(dag);
+  const statusById = new Map(tasks.map((task) => [taskId(task), statusOf(task)]));
+  return tasks
+    .filter((task) => isPending(statusOf(task)))
+    .map((task) => {
+      const culprits = dependsOn(task)
+        .map(String)
+        .filter((dependency) => isUnsuccessfulTerminal(statusById.get(dependency) ?? ''));
+      return culprits.length > 0 ? { task, dependencies: culprits } : null;
+    })
+    .filter(Boolean);
 }
 
 function agentSane(task, registry) {
@@ -135,5 +175,5 @@ function taskId(task) {
 }
 
 export function isTerminalTask(task) {
-  return TERMINAL_STATUSES.has(statusOf(task));
+  return isTerminal(statusOf(task));
 }

package/src/orchestrator/dispatcher.js

@@ -2,8 +2,8 @@ import { normalizeActivity, parseJsonText } from '../core/activity.js';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { emitRuntimeLog, pollActivitiesOnce } from '../runtime/supervisor.js';
+import { isSuccessful, isTerminal } from './taskStatuses.js';
 
-const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'complete', 'completed', 'success', 'succeeded', 'error']);
 
 export function createDispatcher({
   session = null,
@@ -205,7 +205,7 @@ function dispatchTaskActivity(session, task, assignment, jobId, statusTool, runI
 function taskResultFromStatus(task, assignment, jobId, statusPayload, attempt = null) {
   const result = statusPayload?.result ?? {};
   const resultStatus = String(result.status ?? statusPayload?.status ?? '').toLowerCase();
-  const ok = ['succeeded', 'success', 'done', 'complete', 'completed'].includes(resultStatus);
+  const ok = isSuccessful(resultStatus);
   return {
     ok,
     taskId: String(task.id ?? task.step),
@@ -332,9 +332,6 @@ function taskLogPayload(event, task, assignment, {
   };
 }
 
-function isTerminal(status) {
-  return TERMINAL_STATUSES.has(String(status ?? '').toLowerCase());
-}
 
 function delay(ms, signal) {
   return new Promise((resolve, reject) => {

package/src/orchestrator/planIntegrator.js

@@ -2,8 +2,8 @@ import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { readyPlanTasks } from '../core/planPatch.js';
 import { applyApprovalCoverage } from './approvalPolicy.js';
 import { isValidatedFragment, validateFragment } from './planValidator.js';
+import { isTerminal } from './taskStatuses.js';
 
-const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'error', 'complete', 'completed', 'success']);
 
 export function integrate(runId, fragment, {
   registry,
@@ -218,11 +218,11 @@ function mergePlan(currentPlan, newTasks, { insertBeforeTasks, insertAfterTasks
 
 function firstTerminalMutation(current, beforeIds, afterIds) {
   for (const id of beforeIds) {
-    if (isTerminal(current.get(id))) return id;
+    if (taskIsTerminal(current.get(id))) return id;
   }
   for (const id of afterIds) {
     const dependents = [...current.values()].filter((task) => (task.dependsOn ?? []).includes(id));
-    const terminal = dependents.find(isTerminal);
+    const terminal = dependents.find(taskIsTerminal);
     if (terminal) return terminal.id;
   }
   return null;
@@ -251,8 +251,8 @@ function currentRevision(session) {
   return Number.isInteger(session?.planRevision) && session.planRevision >= 0 ? session.planRevision : 0;
 }
 
-function isTerminal(task) {
-  return TERMINAL_STATUSES.has(String(task?.status ?? '').toLowerCase());
+function taskIsTerminal(task) {
+  return isTerminal(task?.status);
 }
 
 function stringifyList(value) {

package/src/orchestrator/resultAggregator.js

@@ -5,6 +5,7 @@ import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { resolve as resolveCapability } from './capabilityResolver.js';
 import { integrate } from './planIntegrator.js';
 import { validateFragment } from './planValidator.js';
+import { isSuccessful } from './taskStatuses.js';
 
 export function createResultAggregator({
   session = null,
@@ -188,7 +189,7 @@ function rejectExpansion({ session, runId, taskId, store, errors }) {
 
 function resultOk(result) {
   const status = String(result?.status ?? result?.result?.status ?? '').toLowerCase();
-  return result?.ok === true || ['succeeded', 'success', 'done', 'complete', 'completed'].includes(status);
+  return result?.ok === true || isSuccessful(status);
 }
 
 function cancelled(result) {

package/src/orchestrator/scheduler.test.js

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import test from 'node:test';
 
 import { createBudgetManager } from './budgetManager.js';
-import { readyTasks, tasksAwaitingApproval } from './dependencyResolver.js';
+import { blockedByFailedDependency, readyTasks, tasksAwaitingApproval } from './dependencyResolver.js';
 import { createLockManager } from './lockManager.js';
 import {
   describePlanConcurrency,
@@ -244,3 +244,64 @@ function task(id, overrides = {}) {
     ...overrides,
   };
 }
+
+/*
+ Cas observé le 2026-08-04 (workspace juno) : une ingestion de dix fichiers,
+ neuf réussis, le dixième en échec sur du JSON malformé. La barrière de groupe
+ exigeait que TOUS les membres soient `done` : elle ne s'est jamais ouverte, le
+ planificateur n'a plus trouvé de tâche prête, et le run est resté `running`
+ indéfiniment. Un incident sur un document devenait une panne totale.
+*/
+test('une barrière de groupe s’ouvre sur un groupe terminal, pas parfait', () => {
+  const plan = [
+    { id: 'f1', groupId: 'ingest', status: 'done', requiredCapability: 'knowledge.ingest' },
+    { id: 'f2', groupId: 'ingest', status: 'failed', requiredCapability: 'knowledge.ingest' },
+    { id: 'index', dependsOnGroup: 'ingest', status: 'pending', requiredCapability: 'knowledge.index' },
+  ];
+
+  const ready = readyTasks(plan).map((task) => task.id);
+
+  // La suite du plan peut se faire sur ce qui a réussi.
+  assert.deepEqual(ready, ['index']);
+});
+
+test('une barrière reste fermée tant que le groupe n’est pas terminal', () => {
+  const plan = [
+    { id: 'f1', groupId: 'ingest', status: 'done', requiredCapability: 'knowledge.ingest' },
+    { id: 'f2', groupId: 'ingest', status: 'running', requiredCapability: 'knowledge.ingest' },
+    { id: 'index', dependsOnGroup: 'ingest', status: 'pending', requiredCapability: 'knowledge.index' },
+  ];
+
+  assert.deepEqual(readyTasks(plan).map((task) => task.id), []);
+});
+
+test('une dépendance en échec nomme les tâches à ignorer plutôt que de bloquer', () => {
+  const plan = [
+    { id: 'convert', status: 'failed', requiredCapability: 'documents.convert' },
+    { id: 'ingest', dependsOn: ['convert'], status: 'pending', requiredCapability: 'knowledge.ingest' },
+    { id: 'other', status: 'pending', requiredCapability: 'knowledge.ingest' },
+  ];
+
+  const blocked = blockedByFailedDependency(plan);
+
+  // Seule la tâche qui en dépend est concernée : la branche indépendante
+  // continue, c'est tout l'objet du correctif.
+  assert.equal(blocked.length, 1);
+  assert.equal(blocked[0].task.id, 'ingest');
+  assert.deepEqual(blocked[0].dependencies, ['convert']);
+  assert.deepEqual(readyTasks(plan).map((task) => task.id), ['other']);
+});
+
+test('une tâche ignorée ne rebloque pas ses propres descendants', () => {
+  const plan = [
+    { id: 'convert', status: 'failed', requiredCapability: 'documents.convert' },
+    { id: 'ingest', dependsOn: ['convert'], status: 'skipped', requiredCapability: 'knowledge.ingest' },
+    { id: 'publish', dependsOn: ['ingest'], status: 'pending', requiredCapability: 'knowledge.publish' },
+  ];
+
+  // `skipped` est terminal et non réussi : le descendant est à son tour
+  // signalé, ce qui fait descendre la propagation jusqu'au bout du plan au
+  // lieu de laisser un résidu en attente éternelle.
+  const blocked = blockedByFailedDependency(plan);
+  assert.deepEqual(blocked.map((entry) => entry.task.id), ['publish']);
+});

package/src/orchestrator/taskStatuses.js

@@ -0,0 +1,99 @@
+/**
+ * Vocabulaire unique des statuts de tâche.
+ *
+ * Quatorze modules portaient chacun sa propre liste : `['done', 'failed',
+ * 'cancelled']` ici, un `Set` avec `success` et `succeeded` là, un troisième
+ * qui ajoutait `error` mais oubliait `canceled`. Aucune n'était fausse
+ * isolément ; ensemble elles ne décrivaient pas le même monde. Un statut
+ * `skipped` introduit dans l'ordonnanceur était terminal pour lui, inconnu
+ * pour la projection — qui le lisait comme un succès — et non terminal pour
+ * les panneaux, où la tâche tournait indéfiniment.
+ *
+ * Ce module est donc la seule définition. Les alias existent parce que les
+ * agents externes en produisent : `error` pour `failed`, `succeeded` pour
+ * `done`, `canceled` pour `cancelled`. Les normaliser à l'entrée évite d'avoir
+ * à les reconnaître à chaque comparaison.
+ */
+
+/** Succès : la tâche a produit ce qu'on attendait d'elle. */
+export const SUCCESS_STATUSES = Object.freeze(['done', 'complete', 'completed', 'success', 'succeeded']);
+/** Échec : la tâche a été tentée et n'a pas abouti. */
+export const FAILURE_STATUSES = Object.freeze(['failed', 'error', 'stalled']);
+/** Annulation : arrêtée par une décision, pas par un défaut. */
+export const CANCELLED_STATUSES = Object.freeze(['cancelled', 'canceled']);
+/** Abandon : jamais tentée, parce qu'elle ne pouvait plus l'être. */
+export const SKIPPED_STATUSES = Object.freeze(['skipped']);
+/** En attente : pas encore exécutable, mais susceptible de le devenir. */
+export const PENDING_STATUSES_LIST = Object.freeze(['pending', 'pending_approval', 'waiting_approval']);
+/** En cours : un agent y travaille en ce moment. */
+export const ACTIVE_STATUSES = Object.freeze(['running', 'in_progress', 'started', 'starting']);
+
+const ALIASES = new Map([
+  ...SUCCESS_STATUSES.map((status) => [status, 'done']),
+  ...FAILURE_STATUSES.map((status) => [status, 'failed']),
+  ...CANCELLED_STATUSES.map((status) => [status, 'cancelled']),
+  ...SKIPPED_STATUSES.map((status) => [status, 'skipped']),
+  ...ACTIVE_STATUSES.map((status) => [status, 'running']),
+  // Les statuts d'attente restent distincts : `pending_approval` et
+  // `waiting_approval` ne demandent pas la même chose que `pending`, et les
+  // confondre ferait disparaître les demandes d'approbation.
+  ...PENDING_STATUSES_LIST.map((status) => [status, status]),
+]);
+
+/**
+ * Statut canonique, ou `null` si le vocabulaire ne le connaît pas.
+ *
+ * Le `null` est un résultat, pas un accident : c'est lui qui permet aux
+ * appelants de traiter l'inconnu comme inconnu plutôt que de le ranger
+ * silencieusement du côté qui les arrange.
+ */
+export function normalizeTaskStatus(status) {
+  const value = String(status ?? '').trim().toLowerCase();
+  if (!value) return null;
+  return ALIASES.get(value) ?? null;
+}
+
+export function isSuccessful(status) {
+  return normalizeTaskStatus(status) === 'done';
+}
+
+export function isFailed(status) {
+  return normalizeTaskStatus(status) === 'failed';
+}
+
+export function isCancelled(status) {
+  return normalizeTaskStatus(status) === 'cancelled';
+}
+
+export function isSkipped(status) {
+  return normalizeTaskStatus(status) === 'skipped';
+}
+
+export function isPending(status) {
+  const normalized = normalizeTaskStatus(status);
+  return normalized != null && PENDING_STATUSES_LIST.includes(normalized);
+}
+
+export function isActive(status) {
+  return normalizeTaskStatus(status) === 'running';
+}
+
+/** Terminal : plus rien n'arrivera à cette tâche dans ce run. */
+export function isTerminal(status) {
+  const normalized = normalizeTaskStatus(status);
+  return normalized === 'done' || normalized === 'failed' || normalized === 'cancelled' || normalized === 'skipped';
+}
+
+/**
+ * Terminal sans avoir réussi. Regroupe échec, annulation et abandon — la
+ * distinction compte pour le rapport à l'utilisateur, pas pour décider si la
+ * suite du plan peut s'appuyer dessus.
+ */
+export function isUnsuccessfulTerminal(status) {
+  return isTerminal(status) && !isSuccessful(status);
+}
+
+/** Vrai pour un statut qu'aucun ensemble ne reconnaît. */
+export function isUnknownStatus(status) {
+  return String(status ?? '').trim() !== '' && normalizeTaskStatus(status) == null;
+}

package/src/orchestrator/taskStatuses.test.js

@@ -0,0 +1,112 @@
+import assert from 'node:assert/strict';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import {
+  isActive,
+  isCancelled,
+  isFailed,
+  isPending,
+  isSkipped,
+  isSuccessful,
+  isTerminal,
+  isUnknownStatus,
+  isUnsuccessfulTerminal,
+  normalizeTaskStatus,
+} from './taskStatuses.js';
+
+test('les alias des agents externes tombent sur le même statut canonique', () => {
+  for (const status of ['done', 'complete', 'completed', 'success', 'succeeded', 'DONE', ' Success ']) {
+    assert.equal(normalizeTaskStatus(status), 'done', status);
+  }
+  for (const status of ['failed', 'error', 'stalled']) {
+    assert.equal(normalizeTaskStatus(status), 'failed', status);
+  }
+  for (const status of ['cancelled', 'canceled']) {
+    assert.equal(normalizeTaskStatus(status), 'cancelled', status);
+  }
+  for (const status of ['running', 'in_progress', 'started', 'starting']) {
+    assert.equal(normalizeTaskStatus(status), 'running', status);
+  }
+});
+
+test('les statuts d’attente restent distincts les uns des autres', () => {
+  // Les confondre ferait disparaître les demandes d'approbation : une tâche
+  // `waiting_approval` réduite à `pending` serait ordonnancée sans accord.
+  assert.equal(normalizeTaskStatus('pending'), 'pending');
+  assert.equal(normalizeTaskStatus('pending_approval'), 'pending_approval');
+  assert.equal(normalizeTaskStatus('waiting_approval'), 'waiting_approval');
+  for (const status of ['pending', 'pending_approval', 'waiting_approval']) {
+    assert.equal(isPending(status), true, status);
+    assert.equal(isTerminal(status), false, status);
+  }
+});
+
+test('un statut inconnu vaut null, et null n’est ni un succès ni un échec', () => {
+  // C'est tout l'objet du module : l'inconnu doit rester inconnu au lieu
+  // d'être rangé du côté qui arrange l'appelant.
+  assert.equal(normalizeTaskStatus('brouette'), null);
+  assert.equal(isUnknownStatus('brouette'), true);
+  assert.equal(isSuccessful('brouette'), false);
+  assert.equal(isFailed('brouette'), false);
+  assert.equal(isTerminal('brouette'), false);
+  // Une absence de statut n'est pas un statut inconnu : c'est une absence.
+  assert.equal(isUnknownStatus(''), false);
+  assert.equal(isUnknownStatus(null), false);
+  assert.equal(normalizeTaskStatus(undefined), null);
+});
+
+test('skipped est terminal, et terminal sans succès', () => {
+  assert.equal(isSkipped('skipped'), true);
+  assert.equal(isTerminal('skipped'), true);
+  assert.equal(isSuccessful('skipped'), false);
+  assert.equal(isUnsuccessfulTerminal('skipped'), true);
+  for (const status of ['failed', 'error', 'cancelled', 'canceled']) {
+    assert.equal(isUnsuccessfulTerminal(status), true, status);
+  }
+  assert.equal(isUnsuccessfulTerminal('done'), false);
+  assert.equal(isActive('running'), true);
+  assert.equal(isCancelled('canceled'), true);
+});
+
+/*
+ Le vocabulaire ne vaut que s'il est le seul. Ce test échoue dès qu'un module
+ réintroduit sa propre liste — c'est exactement par là que la divergence est
+ revenue la première fois, une liste à la fois, chacune raisonnable seule.
+*/
+test('aucun module ne redéclare sa propre liste de statuts', () => {
+  const root = new URL('../..', import.meta.url).pathname;
+  const offenders = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      if (!entry.name.endsWith('.js') || entry.name.endsWith('.test.js')) continue;
+      if (path.endsWith(join('orchestrator', 'taskStatuses.js'))) continue;
+      const source = readFileSync(path, 'utf8');
+      /*
+       Une dérogation se déclare DANS le fichier concerné, pas dans une liste
+       de chemins tenue ici. Un run peut être `interrupted`, un job de la file
+       peut expirer : ces vocabulaires sont légitimement distincts. Mais une
+       liste d'exceptions centralisée vieillit mal — elle survit au fichier
+       qu'elle excusait, et redevient la liste locale qu'on voulait supprimer.
+       Le marqueur vit à côté du code, se déplace avec lui et se lit avec lui.
+      */
+      if (source.includes('@statuses-vocabulary')) continue;
+      // Une liste de statuts se reconnaît à la cohabitation de deux marqueurs
+      // qui n'ont aucune raison de se croiser ailleurs.
+      const suspicious = /['"](?:done|failed)['"][^\n]{0,120}['"](?:cancelled|canceled|succeeded|completed|error)['"]/;
+      for (const line of source.split('\n')) {
+        if (line.trimStart().startsWith('*') || line.trimStart().startsWith('//')) continue;
+        if (suspicious.test(line)) offenders.push(`${path.slice(root.length)}: ${line.trim().slice(0, 100)}`);
+      }
+    }
+  };
+  walk(join(root, 'src'));
+
+  assert.deepEqual(offenders, []);
+});