@dotdrelle/wiki-manager 0.12.12 → 0.14.1

package/src/core/skills.js

@@ -69,32 +69,6 @@ function readWorkspaceManifest(workspacePath) {
   }
 }
 
-function readWorkspaceManifestSkill(workspacePath, loadedManifest = null) {
-  const loaded = loadedManifest ?? readWorkspaceManifest(workspacePath);
-  if (!loaded) return null;
-  const { manifest, manifestPath } = loaded;
-  const name = String(manifest.name || basename(workspacePath)).trim();
-  if (!SKILL_NAME_RE.test(name)) return null;
-  const entrypoints = manifest.entrypoints && typeof manifest.entrypoints === 'object'
-    ? manifest.entrypoints
-    : {};
-  const claude = safeRelativeEntry(entrypoints.claude, 'CLAUDE.md');
-  const body = readOptionalText(join(workspacePath, claude));
-  return {
-    name,
-    title: String(manifest.title || name).trim(),
-    description: String(manifest.description || '').trim(),
-    params: [],
-    body,
-    scope: 'workspace',
-    path: manifestPath,
-    manifest,
-    entrypoints,
-    version: manifest.version ? String(manifest.version) : null,
-    language: manifest.language ? String(manifest.language) : null,
-  };
-}
-
 function workspaceUiSkillDir(loadedManifest = null) {
   if (!loadedManifest) return DEFAULT_UI_SKILL_DIR;
   const { manifest } = loadedManifest;
@@ -119,8 +93,6 @@ export function listSkills(session = {}) {
   const skills = [];
   if (session.workspacePath) {
     const loadedManifest = readWorkspaceManifest(session.workspacePath);
-    const manifestSkill = readWorkspaceManifestSkill(session.workspacePath, loadedManifest);
-    if (manifestSkill) skills.push(manifestSkill);
     skills.push(...collectDirectorySkills(join(session.workspacePath, workspaceUiSkillDir(loadedManifest)), 'workspace'));
   }
 

package/src/core/toolLoop.js

@@ -0,0 +1,56 @@
+// Minimal, side-effect-free bounded tool-use loop.
+//
+// This is the shared mechanic of "ask the LLM with a tool set, run the tool
+// calls it emits, feed results back, repeat up to a cap". The caller injects
+// the ONLY policy that varies: `executeCall(call) -> string` decides whether a
+// requested tool is allowed and produces its textual result (allow-list check,
+// MCP dispatch, error formatting). The loop itself owns no plan, no delegation,
+// no run identity and no agent events — deliberately unlike the /agent
+// orchestration loop in createAgentGraph, which is a stateful LangGraph node
+// graph and stays separate. Use this for stateless tool-answer turns (e.g.
+// /chat read-only questions).
+//
+// `executeCall` may throw to abort the whole loop (e.g. an AbortError on
+// cancel); anything it returns is treated as the tool result for that call.
+export async function runBoundedToolLoop({
+  llm,
+  system,
+  messages,
+  tools,
+  executeCall,
+  maxIterations = 4,
+  signal,
+  onStep,
+} = {}) {
+  const cap = Math.max(1, Math.floor(maxIterations) || 1);
+  const convo = [...(messages ?? [])];
+  for (let i = 0; i < cap; i += 1) {
+    onStep?.(i + 1, cap);
+    const result = await llm.completeWithTools({
+      system,
+      tools,
+      messages: convo,
+      toolChoice: 'auto',
+      signal,
+    });
+    const calls = result?.tool_calls ?? [];
+    if (calls.length === 0) {
+      return {
+        content: result?.content ?? result?.message?.content ?? '',
+        iterations: i + 1,
+        capped: false,
+      };
+    }
+    convo.push(result.message ?? { role: 'assistant', content: result.content ?? '', tool_calls: calls });
+    // Tool calls within one turn are independent: dispatch concurrently, then
+    // replay results in the model's call order so the transcript stays stable.
+    const outcomes = await Promise.all(calls.map(async (call) => ({
+      tool_call_id: call.id,
+      content: await executeCall(call),
+    })));
+    for (const outcome of outcomes) {
+      convo.push({ role: 'tool', tool_call_id: outcome.tool_call_id, content: outcome.content });
+    }
+  }
+  return { content: '', iterations: cap, capped: true };
+}

package/src/core/toolLoop.test.js

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { runBoundedToolLoop } from './toolLoop.js';
+
+function toolCall(id, name, args = '{}') {
+  return { id, function: { name, arguments: args } };
+}
+
+test('returns the model answer directly when no tool is called', async () => {
+  const llm = {
+    async completeWithTools() {
+      return { content: 'plain answer', tool_calls: [] };
+    },
+  };
+  const out = await runBoundedToolLoop({ llm, tools: [], executeCall: async () => 'unused' });
+  assert.deepEqual(out, { content: 'plain answer', iterations: 1, capped: false });
+});
+
+test('dispatches a tool call, feeds the result back, then returns the final answer', async () => {
+  let round = 0;
+  const seen = [];
+  const llm = {
+    async completeWithTools({ messages }) {
+      round += 1;
+      if (round === 1) return { message: { role: 'assistant', content: '', tool_calls: [toolCall('c1', 'cme__cme_status')] }, tool_calls: [toolCall('c1', 'cme__cme_status')] };
+      seen.push(messages.find((m) => m.role === 'tool')?.content);
+      return { content: 'configured', tool_calls: [] };
+    },
+  };
+  const out = await runBoundedToolLoop({
+    llm,
+    tools: [{ function: { name: 'cme__cme_status' } }],
+    executeCall: async (call) => `RESULT(${call.function.name})`,
+  });
+  assert.equal(out.content, 'configured');
+  assert.equal(out.iterations, 2);
+  assert.equal(out.capped, false);
+  assert.deepEqual(seen, ['RESULT(cme__cme_status)']);
+});
+
+test('runs concurrent tool calls and replays results in call order', async () => {
+  let round = 0;
+  const order = [];
+  const llm = {
+    async completeWithTools({ messages }) {
+      round += 1;
+      if (round === 1) {
+        const calls = [toolCall('a', 's__list'), toolCall('b', 's__status')];
+        return { message: { role: 'assistant', content: '', tool_calls: calls }, tool_calls: calls };
+      }
+      order.push(...messages.filter((m) => m.role === 'tool').map((m) => m.tool_call_id));
+      return { content: 'done', tool_calls: [] };
+    },
+  };
+  const out = await runBoundedToolLoop({
+    llm,
+    tools: [],
+    executeCall: async (call) => call.id,
+  });
+  assert.equal(out.content, 'done');
+  assert.deepEqual(order, ['a', 'b']); // preserved model call order
+});
+
+test('reports capped when the model keeps calling tools past the cap', async () => {
+  const llm = {
+    async completeWithTools() {
+      const calls = [toolCall('x', 's__status')];
+      return { message: { role: 'assistant', content: '', tool_calls: calls }, tool_calls: calls };
+    },
+  };
+  const out = await runBoundedToolLoop({ llm, tools: [], executeCall: async () => 'r', maxIterations: 3 });
+  assert.equal(out.capped, true);
+  assert.equal(out.iterations, 3);
+});
+
+test('propagates an abort thrown by executeCall', async () => {
+  const llm = {
+    async completeWithTools() {
+      const calls = [toolCall('x', 's__status')];
+      return { message: { role: 'assistant', content: '', tool_calls: calls }, tool_calls: calls };
+    },
+  };
+  const abort = Object.assign(new Error('aborted'), { name: 'AbortError' });
+  await assert.rejects(
+    runBoundedToolLoop({ llm, tools: [], executeCall: async () => { throw abort; } }),
+    /aborted/,
+  );
+});

package/src/orchestrator/capabilityRegistry.js

@@ -45,6 +45,20 @@ export function createCapabilityRegistry({ agents = [], compatibleContractVersio
   };
 }
 
+// Discovery and registry construction are asynchronous and are not always
+// completed in the same order. Consumers must nevertheless validate against
+// the live discovered agents instead of treating a temporarily absent cached
+// registry as an empty registry.
+export function capabilityRegistryForSession(session) {
+  const agents = session?.agentRegistry?.snapshot?.()
+    ?? session?.agentRegistrySnapshot
+    ?? session?.agents
+    ?? [];
+  if (agents.length > 0) return createCapabilityRegistry({ agents });
+  if (session?.capabilityRegistry?.providersFor) return session.capabilityRegistry;
+  return createCapabilityRegistry();
+}
+
 function isProviderAgent(agent, compatible) {
   if (!agent || agent.legacy || agent.orchestrable === false) return false;
   if (!compatible.has(String(agent.description?.contractVersion ?? ''))) return false;

package/src/orchestrator/capabilityRegistry.test.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { createCapabilityRegistry } from './capabilityRegistry.js';
+import { capabilityRegistryForSession, createCapabilityRegistry } from './capabilityRegistry.js';
 
 function agent(agentInstanceId, capabilityId, { contractVersion = '1', health = 'available', version = '1' } = {}) {
   return {
@@ -23,6 +23,17 @@ function agent(agentInstanceId, capabilityId, { contractVersion = '1', health =
   };
 }
 
+test('capabilityRegistryForSession rebuilds the registry from live discovery when the cache is absent', () => {
+  const discoveredAgent = agent('production-main', 'knowledge.update');
+  const registry = capabilityRegistryForSession({
+    capabilityRegistry: createCapabilityRegistry(),
+    agentRegistry: { snapshot: () => [discoveredAgent] },
+    agentRegistrySnapshot: [],
+  });
+
+  assert.equal(registry.providersFor('knowledge.update').length, 1);
+});
+
 test('capabilityRegistry indexes two agents for the same capability', () => {
   const registry = createCapabilityRegistry({
     agents: [

package/src/orchestrator/dependencyResolver.js

@@ -15,7 +15,16 @@ export function readyTasks(dag, {
   const done = new Set(tasks.filter((task) => DONE_STATUSES.has(statusOf(task))).map(taskId));
   const active = new Set([...activeTaskIds].map(String));
   return tasks
-    .filter((task) => statusOf(task) === 'pending')
+    .filter((task) => {
+      const status = statusOf(task);
+      return status === 'pending'
+        || ((status === 'waiting_approval' || status === 'pending_approval')
+          && approvalCovered(task, approvals, {
+            runId: task?.runId ?? dag?.runId ?? null,
+            workspaceId: dag?.workspace ?? null,
+            planRevision: dag?.planRevision ?? null,
+          }));
+    })
     .filter((task) => !active.has(taskId(task)))
     .filter((task) => dependenciesDone(task, done))
     .filter((task) => groupBarrierSatisfied(task, tasks))

package/src/orchestrator/dispatcher.js

@@ -8,7 +8,7 @@ const TERMINAL_STATUSES = new Set(['done', 'failed', 'cancelled', 'canceled', 'c
 export function createDispatcher({
   session = null,
   callTool = callMcpTool,
-  pollIntervalMs = 250,
+  pollIntervalMs = 2500,
 } = {}) {
   return {
     execute(task, assignment, options = {}) {
@@ -30,7 +30,7 @@ export async function execute(task, assignment, {
   attempt = null,
   timeoutMs = null,
   pollBusy = new Set(),
-  pollIntervalMs = 250,
+  pollIntervalMs = 2500,
 } = {}) {
   if (!session) throw new Error('dispatcher.execute requires session.');
   if (!assignment?.serverName) throw new Error(`No MCP server found for agent ${assignment?.agentInstanceId ?? '(unknown)'}.`);
@@ -57,7 +57,7 @@ export async function execute(task, assignment, {
       signal,
     ));
     if (accepted?.accepted === false || accepted?.ok === false) {
-      throw new Error(String(accepted.error ?? 'agent_execute rejected task'));
+      return rejectedTaskResult(task, assignment, accepted, attempt);
     }
     jobId = String(accepted.jobId ?? '');
     if (!jobId) throw new Error('agent_execute did not return jobId.');
@@ -218,6 +218,37 @@ function taskResultFromStatus(task, assignment, jobId, statusPayload, attempt =
   };
 }
 
+function rejectedTaskResult(task, assignment, payload, attempt = null) {
+  const rawError = payload?.error;
+  const error = rawError && typeof rawError === 'object'
+    ? { ...rawError }
+    : {
+        code: String(rawError ?? 'execution_rejected'),
+        message: String(payload?.message ?? rawError ?? 'agent_execute rejected task'),
+        retryable: transientError(rawError ?? payload?.message),
+      };
+  return {
+    ok: false,
+    taskId: String(task.id ?? task.step),
+    attemptId: attempt?.attemptId ?? null,
+    jobId: payload?.activeJobId ?? null,
+    agentInstanceId: assignment.agentInstanceId,
+    status: 'failed',
+    outputRefs: [],
+    metrics: {},
+    error: {
+      code: String(error.code ?? 'execution_rejected'),
+      message: String(error.message ?? error.code ?? 'agent_execute rejected task'),
+      retryable: error.retryable === true || transientError(error.code) || transientError(error.message),
+    },
+    rawStatus: payload,
+  };
+}
+
+function transientError(value) {
+  return /(?:429|timeout|temporar|throttl|rate.?limit|quota|busy|unavailable)/i.test(String(value ?? ''));
+}
+
 function toolNameFor(session, serverName, baseName) {
   const tools = session.mcp?.[serverName]?.tools ?? [];
   const names = tools.map((tool) => String(tool.name ?? '')).filter(Boolean);

package/src/orchestrator/dispatcher.test.js

@@ -0,0 +1,34 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createDispatcher } from './dispatcher.js';
+
+test('dispatcher returns a retryable logical failure when agent_execute reports workspace_busy', async () => {
+  const session = {
+    workspace: 'test',
+    mcp: {
+      production: {
+        tools: [
+          { name: 'agent_execute' },
+          { name: 'agent_status' },
+          { name: 'agent_cancel' },
+        ],
+      },
+    },
+  };
+  const dispatcher = createDispatcher({
+    session,
+    callTool: async () => ({ accepted: false, error: 'workspace_busy', activeJobId: 'job-old' }),
+  });
+
+  const result = await dispatcher.execute(
+    { id: 'ingest-a', requiredCapability: 'knowledge.update', operation: 'ingest_plan', arguments: {} },
+    { serverName: 'production', agentInstanceId: 'production-main' },
+    { attempt: { attemptId: 'ingest-a:attempt-1', locks: [], release() {} } },
+  );
+
+  assert.equal(result.ok, false);
+  assert.equal(result.taskId, 'ingest-a');
+  assert.equal(result.attemptId, 'ingest-a:attempt-1');
+  assert.equal(result.error.code, 'workspace_busy');
+  assert.equal(result.error.retryable, true);
+});

package/src/orchestrator/objectiveResolver.js

@@ -0,0 +1,79 @@
+export async function resolveObjective(objective, session) {
+  const candidates = capabilityCandidates(session);
+  if (candidates.length === 0) throw new Error('No orchestrable capability is currently available.');
+  const llm = session?.llm;
+  if (!llm?.completeWithTools) throw new Error('Objective resolution requires the configured workspace LLM.');
+
+  const result = await llm.completeWithTools({
+    system: [
+      'You resolve one user objective against a closed capability registry.',
+      'Select exactly one listed capability and one of its supported operations.',
+      'Never invent identifiers. Return JSON only: {"capability":"...","operation":"..."}.',
+    ].join('\n'),
+    tools: [],
+    messages: [{
+      role: 'user',
+      content: `Objective:\n${String(objective)}\n\nRegistry:\n${JSON.stringify(candidates, null, 2)}`,
+    }],
+    signal: session?._abortSignal,
+  });
+  const selection = parseJson(result?.content);
+  const capability = String(selection?.capability ?? '');
+  const operation = String(selection?.operation ?? '');
+  const candidate = candidates.find((item) => item.id === capability);
+  if (!candidate) throw new Error(`Objective resolver selected unknown capability "${capability}".`);
+  if (!candidate.operations.includes(operation)) {
+    throw new Error(`Objective resolver selected unsupported operation "${operation}" for ${capability}.`);
+  }
+  const providers = providersFor(session, capability)
+    .filter((provider) => !operation || (provider.capability?.supportedOperations ?? []).includes(operation))
+    .sort((a, b) => String(a.agentInstanceId).localeCompare(String(b.agentInstanceId)));
+  if (providers.length === 0) throw new Error(`No healthy agent provides ${capability}/${operation}.`);
+  return { capability, operation, provider: providers[0], candidates };
+}
+
+export function capabilityCandidates(session) {
+  const snapshot = registrySnapshot(session);
+  const byId = new Map();
+  for (const [versionedId, providers] of Object.entries(snapshot)) {
+    const id = versionedId.includes('@') ? versionedId.slice(0, versionedId.lastIndexOf('@')) : versionedId;
+    const operations = [...new Set((providers ?? []).flatMap((provider) => provider?.capability?.supportedOperations ?? []))].sort();
+    const description = (providers ?? []).map((provider) => provider?.capability?.description).find(Boolean) ?? '';
+    byId.set(id, { id, description, operations });
+  }
+  return [...byId.values()].filter((item) => item.operations.length > 0).sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function providersFor(session, capability) {
+  if (session?.capabilityRegistry?.providersFor) return session.capabilityRegistry.providersFor(capability) ?? [];
+  return Object.entries(registrySnapshot(session))
+    .filter(([key]) => key === capability || key.startsWith(`${capability}@`))
+    .flatMap(([, providers]) => providers ?? []);
+}
+
+function registrySnapshot(session) {
+  const registry = session?.capabilityRegistry;
+  if (registry?.snapshot) return registry.snapshot();
+  if (registry && typeof registry === 'object') return registry;
+  const agents = session?.agentRegistry?.snapshot?.() ?? session?.agentRegistrySnapshot ?? [];
+  const snapshot = {};
+  for (const agent of agents) {
+    for (const capability of agent?.description?.capabilities ?? []) {
+      const key = `${capability.id}@${capability.version ?? '1'}`;
+      (snapshot[key] ??= []).push({
+        agentInstanceId: agent.agentInstanceId,
+        serverName: agent.serverName,
+        capability,
+        description: agent.description,
+        health: agent.health,
+      });
+    }
+  }
+  return snapshot;
+}
+
+function parseJson(content) {
+  const text = String(content ?? '').trim();
+  const fenced = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return JSON.parse(fenced ? fenced[1] : text);
+}

package/src/orchestrator/objectiveResolver.test.js

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { capabilityCandidates, resolveObjective } from './objectiveResolver.js';
+
+function sessionWithSelection(selection) {
+  const provider = {
+    agentInstanceId: 'production-1',
+    serverName: 'production',
+    capability: {
+      id: 'knowledge.update',
+      version: '1',
+      description: 'Update knowledge from pending sources.',
+      supportedOperations: ['ingest'],
+    },
+  };
+  return {
+    capabilityRegistry: {
+      snapshot: () => ({ 'knowledge.update@1': [provider] }),
+      providersFor: () => [provider],
+    },
+    llm: {
+      completeWithTools: async () => ({ content: JSON.stringify(selection) }),
+    },
+  };
+}
+
+test('capabilityCandidates exposes only the closed live registry', () => {
+  assert.deepEqual(capabilityCandidates(sessionWithSelection({})), [{
+    id: 'knowledge.update',
+    description: 'Update knowledge from pending sources.',
+    operations: ['ingest'],
+  }]);
+});
+
+test('resolveObjective selects and validates one real provider', async () => {
+  const result = await resolveObjective('Ingère tous les fichiers en attente', sessionWithSelection({
+    capability: 'knowledge.update',
+    operation: 'ingest',
+  }));
+  assert.equal(result.capability, 'knowledge.update');
+  assert.equal(result.operation, 'ingest');
+  assert.equal(result.provider.agentInstanceId, 'production-1');
+});
+
+test('resolveObjective rejects invented capability and operation', async () => {
+  await assert.rejects(
+    resolveObjective('Ingère tout', sessionWithSelection({ capability: 'ingest', operation: 'ingest_all_pending' })),
+    /unknown capability "ingest"/,
+  );
+});

package/src/orchestrator/scheduler.test.js

@@ -35,6 +35,31 @@ test('dependencyResolver orders ready tasks by priority before step', () => {
   assert.deepEqual(readyTasks(plan).map((item) => item.id), ['high', 'low', 'none']);
 });
 
+test('dependencyResolver releases a waiting task when a run grant covers it', () => {
+  const plan = {
+    runId: 'run-1',
+    workspace: 'test4',
+    planRevision: 1,
+    tasks: [task('ingest', {
+      status: 'waiting_approval',
+      requiresApproval: true,
+      approvalClass: 'mutation',
+    })],
+  };
+
+  assert.deepEqual(readyTasks(plan), []);
+  assert.deepEqual(readyTasks(plan, {
+    approvals: [{
+      status: 'approved',
+      scope: 'run',
+      runId: 'run-1',
+      workspaceId: 'test4',
+      planRevision: 1,
+      approvalClasses: ['mutation'],
+    }],
+  }).map((item) => item.id), ['ingest']);
+});
+
 test('dependencyResolver skips tasks whose locks are not free and keeps other ready work moving', () => {
   const lockManager = createLockManager();
   const held = lockManager.acquire(['deliverable:a.md']);

package/src/runtime/client.js

@@ -70,6 +70,25 @@ export async function postRuntimeRun(input, {
   return response.json();
 }
 
+export async function postRuntimeDelegate(objective, {
+  url = runtimeUrlFromEnv(),
+  token = runtimeToken(),
+  workspace = null,
+} = {}) {
+  const response = await fetch(runtimeEndpoint(url, '/delegate', workspace), {
+    method: 'POST',
+    headers: { ...runtimeHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ objective, workspace }),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const err = new Error(payload.error ?? `Runtime delegation failed: HTTP ${response.status}`);
+    err.status = response.status;
+    throw err;
+  }
+  return payload;
+}
+
 export async function postRuntimeControl(action, {
   url = runtimeUrlFromEnv(),
   token = runtimeToken(),
@@ -152,6 +171,9 @@ export async function postRuntimeApprove({
   runId = null,
   itemId = null,
   approvalId = null,
+  scope = null,
+  planRevision = null,
+  approvalClasses = null,
 } = {}) {
   const endpoint = runtimeEndpoint(url, '/approve', workspace);
   const parsed = new URL(endpoint);
@@ -160,7 +182,16 @@ export async function postRuntimeApprove({
   if (approvalId) parsed.searchParams.set('approvalId', approvalId);
   const response = await fetch(parsed.toString(), {
     method: 'POST',
-    headers: runtimeHeaders(token),
+    headers: { ...runtimeHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      workspace,
+      runId,
+      itemId,
+      approvalId,
+      scope,
+      planRevision,
+      approvalClasses,
+    }),
   });
   if (!response.ok) throw new Error(`Runtime approve failed: HTTP ${response.status}`);
   return response.json();

package/src/runtime/lifecycle.js

@@ -1,5 +1,6 @@
 import { execFile, spawn } from 'node:child_process';
-import { dirname, resolve } from 'node:path';
+import { readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { activeCacertPath } from '../core/cacert.js';
 import { checkRuntimeHealth, postRuntimeShutdown, runtimeUrlFromEnv } from './client.js';
@@ -10,6 +11,26 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const managerRoot = resolve(__dirname, '../..');
 const binPath = resolve(managerRoot, 'bin/wiki-manager.js');
 
+// Newest mtime (ms) of the manager's own source tree. Used to detect that the
+// code was edited after a reused runtime started, so ensureRuntime can restart
+// it instead of serving stale code. Returns 0 if the source tree is unreadable
+// (e.g. running from a packed install) — in that case staleness is not checked.
+function newestManagerSourceMtimeMs() {
+  const srcDir = join(managerRoot, 'src');
+  let newest = 0;
+  try {
+    for (const entry of readdirSync(srcDir, { recursive: true })) {
+      const name = String(entry);
+      if (!(name.endsWith('.js') || name.endsWith('.ts') || name.endsWith('.tsx'))) continue;
+      try {
+        const mtime = statSync(join(srcDir, name)).mtimeMs;
+        if (mtime > newest) newest = mtime;
+      } catch { /* file vanished mid-scan */ }
+    }
+  } catch { return 0; }
+  return newest;
+}
+
 export function runtimeNodeExecutable() {
   return process.versions.bun
     ? (process.env.WIKI_MANAGER_NODE_BIN ?? 'node')
@@ -47,13 +68,22 @@ export async function ensureRuntime({
   if (existing) {
     const expectedCacertPath = activeCacertPath();
     const actualCacertPath = existing.cacertPath ? resolve(existing.cacertPath) : null;
+    // Dev staleness: if the manager source was edited after this runtime
+    // started, the reused process would keep serving old code (the recurring
+    // "my change is not taking effect" trap). Treat it as stale and restart.
+    // Packed installs report mtime 0 (unreadable src) → never flagged stale.
+    // Opt out with WIKI_MANAGER_RUNTIME_NO_STALE_CHECK=1.
+    const startedAtMs = Number(existing.startedAtMs) || 0;
+    const sourceMtimeMs = process.env.WIKI_MANAGER_RUNTIME_NO_STALE_CHECK === '1' ? 0 : newestManagerSourceMtimeMs();
+    const stale = startedAtMs > 0 && sourceMtimeMs > startedAtMs;
     // forceRestart: the caller knows the manager configuration just changed
     // (e.g. mcp.endpoints.json scaffolded on first run) — a runtime started
     // BEFORE that only knows the old endpoints and would keep answering
     // without the agents until manually restarted.
-    if (!forceRestart && actualCacertPath === expectedCacertPath) {
+    if (!forceRestart && !stale && actualCacertPath === expectedCacertPath) {
       return { url, started: false, health: existing, token: auth.token, tokenPath: auth.tokenPath };
     }
+    if (stale) console.error('runtime: source changed since start — restarting for fresh code.');
     await postRuntimeShutdown({ url, token: auth.token });
     await waitForRuntimeShutdown(url, auth.token, 2500);
   }

package/src/runtime/recoveryManager.js

@@ -37,18 +37,25 @@ export async function recoverActiveRuns({
         errors.push({ runId: run.id, taskId: task.id, error: error instanceof Error ? error.message : String(error) });
       }
     }
-    // A run in which nothing was recovered or rescheduled can never progress:
-    // leaving it 'running' in the store would re-attach it as a zombie on
-    // every subsequent boot. Close it for good.
-    if (activeTasks.length > 0 && runOutcomes.length === activeTasks.length
-      && runOutcomes.every((outcome) => outcome?.status === 'interrupted')) {
-      const changed = store.interruptRuns?.({ workspace: run.workspace ?? null, runId: run.id, reason: 'Recovery found no recoverable task.' }) ?? 0;
+    // A run that recovery cannot move forward must be closed for good, or it
+    // re-attaches as a blocking "a runtime run is already active" zombie on
+    // every boot. This covers BOTH cases that can never resume on a fresh boot:
+    //  - runs whose active tasks were all interrupted, and
+    //  - runs with no active task to recover at all (e.g. left waiting for
+    //    approval, or with only un-started pending tasks). Nothing here will
+    //    ever progress, so finalize it now.
+    const progressed = runOutcomes.some((outcome) => outcome?.status === 'recovered' || outcome?.status === 'rescheduled');
+    if (!progressed) {
+      const reason = activeTasks.length > 0
+        ? 'Recovery found no recoverable task.'
+        : 'Recovery found no active task to resume.';
+      const changed = store.interruptRuns?.({ workspace: run.workspace ?? null, runId: run.id, reason }) ?? 0;
       if (changed > 0) {
         dispatch(session, store, 'runtime_log', {
           origin: 'recovery_manager',
           runId: run.id,
           workspace: run.workspace ?? workspaceFromSession(session),
-          payload: { message: `recovery: run ${run.id} interrupted (no recoverable task)` },
+          payload: { message: `recovery: run ${run.id} interrupted (${reason})` },
         });
       }
     }