@dotdrelle/wiki-manager 0.14.16 → 0.14.20

package/.env.example

@@ -74,10 +74,24 @@ DOCUMENTS_MCP_AUTH_TOKEN=
 # WIKI_MANAGER_RUNTIME_HOST=0.0.0.0
 
 
-# Parallel tasks dispatched at once for capability runs. Defaults to what the
-# agent itself declares (agent_describe limits); set only to constrain it.
-# Example constraint (never raises an agent's declared capacity):
-# WIKI_MANAGER_CAPABILITY_CONCURRENCY=3
+# ── Parallelism & throughput ───────────────────────────────────────────────────
+# Effective concurrency = MIN(agent recommendedConcurrency, agent maxConcurrency,
+# this ceiling, per-task limits). So the PRIMARY levers live on the production
+# agent (PRODUCTION_RECOMMENDED_CONCURRENCY / PRODUCTION_MAX_CONCURRENCY); this
+# manager variable can only LOWER the result, never raise it. Full explanation
+# and low/high profiles in docs/configuration.md § "Parallelism & throughput".
+#
+# Manager ceiling — leave unset to let the agent decide. Set to constrain:
+# WIKI_MANAGER_CAPABILITY_CONCURRENCY=4
+#
+# Production agent capacity (passed through by docker-compose). Intermediate
+# defaults are 4/8 (effective ≈ 4 parallel). Profiles:
+#   low   → PRODUCTION_RECOMMENDED_CONCURRENCY=2  PRODUCTION_MAX_CONCURRENCY=4
+#   high  → PRODUCTION_RECOMMENDED_CONCURRENCY=8  PRODUCTION_MAX_CONCURRENCY=16
+# The wiki LLM backend must accept this many concurrent requests, and
+# ingest_apply stays serialized regardless (global workspace-write lock).
+# PRODUCTION_RECOMMENDED_CONCURRENCY=4
+# PRODUCTION_MAX_CONCURRENCY=8
 
 # ── MCP retry policy (optional) ────────────────────────────────────────────────
 

package/README.md

@@ -550,6 +550,25 @@ or the shell command `/approve item <id>`. The approval timeout defaults to 10
 minutes and can be changed with `WIKI_MANAGER_APPROVAL_TIMEOUT_MS` or
 `approvalTimeoutMs` in the `/run` body.
 
+Directly-launched capability runs (ingest, pipeline) now **wait for approval by
+default** before their mutating tasks: reply "valide tout", run `/approve`, or
+click Approve in either UI (Shell right-pane banner, or the `serve` banner above
+the composer). Auto-approval only happens when the run is started with
+`autoApprove: true` (headless/CI).
+
+### Parallelism & throughput
+
+The number of tasks that run at once is `MIN(agent recommendedConcurrency, agent
+maxConcurrency, WIKI_MANAGER_CAPABILITY_CONCURRENCY, per-task limits)` — a
+minimum, so the manager ceiling can only lower it. The production agent ships
+intermediate defaults (`PRODUCTION_RECOMMENDED_CONCURRENCY=4` /
+`PRODUCTION_MAX_CONCURRENCY=8`, ≈ 4 parallel); locks then cap real parallelism
+per phase (`ingest_apply` stays serial). The resolved value is shown in both
+UIs' run summary and on the run node of the execution graph, with an amber
+"(ceiling)" marker when the manager ceiling binds. Low/high profiles, the lock
+model and the LLM-backend caveat are in
+[docs/configuration.md § "Parallelism & throughput"](docs/configuration.md).
+
 While a run is active, `GET`/`POST /control` still answers without waiting for
 it to finish: `{"action":"status"}` returns the current run/plan/queue state,
 `{"action":"explain"}` adds a one-line plain-language summary, and

package/docker-compose.yml

@@ -110,6 +110,11 @@ services:
       - WIKI_CONFIG_PATH=${WIKI_CONFIG_PATH:-}
       - PRODUCTION_ALLOWED_STEPS=${PRODUCTION_ALLOWED_STEPS:-doctor,ingest,ingest_plan,ingest_apply,build,export,polish,pipeline}
       - PRODUCTION_REQUIRE_CONFIRMATION=${PRODUCTION_REQUIRE_CONFIRMATION:-false}
+      # Parallelism levers — effective concurrency ≈ recommendedConcurrency.
+      # Intermediate defaults (4/8). Low profile 2/4, high profile 8/16.
+      # See docs/configuration.md § "Parallelism & throughput".
+      - PRODUCTION_RECOMMENDED_CONCURRENCY=${PRODUCTION_RECOMMENDED_CONCURRENCY:-4}
+      - PRODUCTION_MAX_CONCURRENCY=${PRODUCTION_MAX_CONCURRENCY:-8}
       - PRODUCTION_JOBS_DIR=${PRODUCTION_JOBS_DIR:-/workspace/.wiki/production-jobs}
       - PRODUCTION_LOCKS_DIR=${PRODUCTION_LOCKS_DIR:-/workspace/.wiki/production-jobs/locks}
     ports:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotdrelle/wiki-manager",
-  "version": "0.14.16",
+  "version": "0.14.20",
   "description": "Agentic shell and orchestration cockpit for llm-wiki workspaces.",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "dotrelle",

package/src/activity/activityAggregator.js

@@ -93,17 +93,21 @@ function groupLine(group, activities) {
   // still progressing. Show the live worker as running; surface the group
   // failure once no work remains. Otherwise its business label was rendered
   // red even though that exact task was healthy and advancing.
+  // Glyphs mirror the Shell PlanPanel so the two never disagree: done is a
+  // check (not a cross — "[x]" read as a failure X), failure is a distinct
+  // cross, and an approval wait gets its own pause glyph instead of reusing the
+  // failure "[!]".
   if (running.length > 0 || activeActivity) {
     icon = '[...]';
     status = activeProgress != null ? `${Math.round(activeProgress)} %` : `${done}/${total}`;
   } else if (failed) {
-    icon = '[!]';
+    icon = '[✗]';
     status = 'error';
   } else if (done === total) {
-    icon = '[x]';
+    icon = '[✓]';
     status = 'done';
   } else if (waitingApproval) {
-    icon = '[!]';
+    icon = '[⏸]';
     status = 'validation';
   } else if (done > 0) {
     icon = '[...]';

package/src/activity/activityAggregator.test.js

@@ -5,6 +5,20 @@ import { aggregateActivity } from './activityAggregator.js';
 import { visibleActivityEvents } from './activityDeduplicator.js';
 import { calculateWeightedProgress } from './progressCalculator.js';
 
+test('a group awaiting approval renders a distinct pause glyph, not a failure', () => {
+  const aggregated = aggregateActivity({
+    plan: [
+      { id: 'publish', label: 'Publication', groupId: 'publish', status: 'pending_approval', progressWeight: 1 },
+    ],
+    activities: [],
+  });
+  const line = aggregated.lines.find((item) => /publish|Publication/.test(item.label));
+  assert.ok(line, 'the awaiting-approval group is present');
+  assert.match(line.label, /\[⏸\]/, 'uses the pause glyph');
+  assert.doesNotMatch(line.label, /\[!\]|\[✗\]/, 'never reuses the failure glyph');
+  assert.equal(line.status, 'validation');
+});
+
 test('activityDeduplicator keeps one visible entry for repeated 2 percent polls', () => {
   const events = Array.from({ length: 50 }, () => ({
     type: 'activity_upserted',
@@ -54,7 +68,7 @@ test('aggregateActivity exposes initial synthesis and grouped display lines', ()
 
   assert.deepEqual(activity.initialSynthesis, ['120 sources detectees', '6 traitements simultanes recommandes']);
   assert.equal(activity.progress.percent, 54);
-  assert.ok(activity.lines.some((line) => /\[x\] collect - done/.test(line.label)));
+  assert.ok(activity.lines.some((line) => /\[✓\] collect - done/.test(line.label)));
   assert.ok(activity.lines.some((line) => /\[\.\.\.\] customer-data\.enrich - 63 %/.test(line.label)));
   const enrichLine = activity.lines.find((line) => /customer-data\.enrich/.test(line.label));
   assert.equal(enrichLine.progress.label, 'Export rapport.md');
@@ -92,7 +106,7 @@ test('aggregateActivity keeps activities not attached to any plan task visible',
 
   const aggregated = aggregateActivity(state, []);
   const labels = aggregated.lines.map((line) => line.label).join('\n');
-  assert.match(labels, /\[x\] .* done/, 'the done plan group stays visible');
+  assert.match(labels, /\[✓\] .* done/, 'the done plan group stays visible');
   assert.match(labels, /Ingest b87acaf6/, 'the unattached running ingest must appear');
   const ingestLine = aggregated.lines.find((line) => /Ingest/.test(line.label));
   assert.equal(ingestLine.status, 'running');

package/src/cli/wiki-manager.js

@@ -114,6 +114,18 @@ export async function forwardRuntimeApproval(getWorkspaceContext, request = {})
   return context.approvalManager?.approve(request) ?? { approved: false };
 }
 
+export function resolvePreparedDelegationApproval({
+  autoApprove = false,
+  approvalManager = null,
+  runId,
+} = {}) {
+  if (autoApprove !== true || typeof approvalManager?.approve !== 'function') {
+    return { approved: false, awaitingApproval: true };
+  }
+  const result = approvalManager.approve({ scope: 'run', runId });
+  return { approved: true, awaitingApproval: false, result };
+}
+
 function timestampForFile() {
   return new Date().toISOString().replace(/[:.]/g, '-');
 }
@@ -923,14 +935,24 @@ async function runRuntime(argv, agent) {
           throw new Error(`Delegated plan integration failed: ${(integrated.errors ?? []).map((error) => error.message ?? error.code ?? String(error)).join('; ')}`);
         }
         emitRuntimeLog(session, `delegation: ${prepared.fragment.tasks.length} validated task(s) integrated from ${prepared.provider.serverName}.agent_plan (${prepared.capability}/${prepared.operation})`);
-        // Demandé = consenti: a directly-delegated run carries the user's
-        // explicit consent, so auto-approve its initial plan. Persisting a
-        // run-scope grant (via the approval manager) makes the scheduler's
-        // readyTasks approval check pass, so the tasks run without re-prompting.
-        // Replanned tasks are integrated later without a fresh grant.
-        if (context.approvalManager?.approve) {
-          context.approvalManager.approve({ scope: 'run', runId });
-          emitRuntimeLog(session, `approval: run ${runId} auto-approved (user-requested action)`);
+        // Real approval gate (opt-out): a directly-delegated run only skips the
+        // human approval step when the caller explicitly opts in via
+        // `autoApprove` (e.g. headless/CI, or a future "trust this run" toggle).
+        // By default the run WAITS: integrate() above created the per-task
+        // approval requests, and the scheduler's approvalCovered() filter blocks
+        // the mutating tasks until a run-scope grant arrives (/approve or
+        // "valide tout"). This keeps a visible pending_approval window instead of
+        // resolving it programmatically ~30ms after launch, which no polled UI
+        // could ever render.
+        const approval = resolvePreparedDelegationApproval({
+          autoApprove: body.autoApprove,
+          approvalManager: context.approvalManager,
+          runId,
+        });
+        if (approval.approved) {
+          emitRuntimeLog(session, `approval: run ${runId} auto-approved (autoApprove opt-in)`);
+        } else {
+          emitRuntimeLog(session, `approval: run ${runId} awaiting explicit approval before mutations (/approve or « valide tout »)`);
         }
         body._planReady?.resolve?.({ runId, planRevision: session.agentProjection?.planRevision ?? 0 });
       }

package/src/cli/wiki-manager.test.js

@@ -1,6 +1,9 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { forwardRuntimeApproval } from './wiki-manager.js';
+import {
+  forwardRuntimeApproval,
+  resolvePreparedDelegationApproval,
+} from './wiki-manager.js';
 
 test('runtime approval bridge preserves the complete run-scoped grant', async () => {
   let forwarded = null;
@@ -26,3 +29,39 @@ test('runtime approval bridge preserves the complete run-scoped grant', async ()
   assert.deepEqual(forwarded, request);
   assert.deepEqual(result, { approved: true });
 });
+
+test('prepared delegation waits for explicit approval by default', () => {
+  let calls = 0;
+  const result = resolvePreparedDelegationApproval({
+    runId: 'run-gated',
+    approvalManager: {
+      approve() {
+        calls += 1;
+      },
+    },
+  });
+
+  assert.equal(calls, 0);
+  assert.deepEqual(result, { approved: false, awaitingApproval: true });
+});
+
+test('prepared delegation only approves when autoApprove is explicitly true', () => {
+  let forwarded = null;
+  const result = resolvePreparedDelegationApproval({
+    autoApprove: true,
+    runId: 'run-headless',
+    approvalManager: {
+      approve(request) {
+        forwarded = request;
+        return { approved: true };
+      },
+    },
+  });
+
+  assert.deepEqual(forwarded, { scope: 'run', runId: 'run-headless' });
+  assert.deepEqual(result, {
+    approved: true,
+    awaitingApproval: false,
+    result: { approved: true },
+  });
+});

package/src/core/buildInfo.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.14.16",
-  "commit": "a603298"
+  "version": "0.14.20",
+  "commit": "8833a7e"
 }

package/src/core/mcp.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { managerEnvFile, managerMcpEndpointsFile, readEnvFile } from './env.js';
 
-const WIKI_MANAGER_VERSION = '0.14.16';
+const WIKI_MANAGER_VERSION = '0.14.20';
 
 function envValue(key) {
   const filePath = managerEnvFile();

package/src/core/workflow.js

@@ -107,11 +107,83 @@ export function projectWorkflow(state = {}, events = []) {
     activity,
     waitingReasons,
     warnings,
+    usage: summarizeTokenUsage(events),
+    timingByTask: summarizeTaskTiming(events),
   };
   projected.graph = aggregateGraph(projected, events);
   return projected;
 }
 
+// Per-task wall-clock timing, derived from the lifecycle events. Start = the
+// first assigned/started event, finish = the last terminal event. Display-only
+// (the inspector shows duration + orders tasks into a temporal flow); never used
+// for scheduling.
+function summarizeTaskTiming(events = []) {
+  const byTask = {};
+  const START_EVENTS = new Set(['task.assigned', 'task.started']);
+  const END_EVENTS = new Set(['task.completed', 'task.failed', 'task.result_returned']);
+  for (const event of events) {
+    if (!START_EVENTS.has(event.type) && !END_EVENTS.has(event.type)) continue;
+    const taskId = String(event.taskId ?? event.payload?.taskId ?? '').replace(/^task:/, '');
+    if (!taskId) continue;
+    const ts = Number(new Date(event.ts).getTime());
+    if (!Number.isFinite(ts)) continue;
+    const entry = byTask[taskId] ?? (byTask[taskId] = { startedAt: null, finishedAt: null, durationMs: null });
+    if (START_EVENTS.has(event.type)) {
+      entry.startedAt = entry.startedAt == null ? ts : Math.min(entry.startedAt, ts);
+    } else {
+      entry.finishedAt = entry.finishedAt == null ? ts : Math.max(entry.finishedAt, ts);
+    }
+  }
+  for (const entry of Object.values(byTask)) {
+    if (entry.startedAt != null && entry.finishedAt != null && entry.finishedAt >= entry.startedAt) {
+      entry.durationMs = entry.finishedAt - entry.startedAt;
+    }
+  }
+  return byTask;
+}
+
+function summarizeTokenUsage(events = []) {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let totalTokens = 0;
+  let inputKnown = false;
+  let outputKnown = false;
+  let totalKnown = false;
+  const byTask = {};
+  const seen = new Set();
+  for (const event of events) {
+    if (!['task.result_returned', 'task.completed', 'task.failed'].includes(event.type)) continue;
+    const result = event.payload?.result ?? {};
+    const metrics = result.metrics ?? event.payload?.metrics ?? {};
+    const attemptId = result.attemptId ?? event.payload?.attemptId ?? event.id;
+    if (attemptId && seen.has(attemptId)) continue;
+    if (attemptId) seen.add(attemptId);
+    const input = metricNumber(metrics.inputTokens ?? metrics.promptTokens ?? metrics.prompt_tokens);
+    const output = metricNumber(metrics.outputTokens ?? metrics.completionTokens ?? metrics.completion_tokens);
+    const total = metricNumber(metrics.totalTokens ?? metrics.total_tokens ?? metrics.tokens);
+    if (input != null) { inputTokens += input; inputKnown = true; }
+    if (output != null) { outputTokens += output; outputKnown = true; }
+    if (total != null) { totalTokens += total; totalKnown = true; }
+    else if (input != null || output != null) { totalTokens += (input ?? 0) + (output ?? 0); totalKnown = true; }
+    const taskId = String(event.taskId ?? event.payload?.taskId ?? '');
+    if (taskId && (input != null || output != null || total != null)) {
+      const current = byTask[taskId] ?? { inputTokens: 0, outputTokens: 0, totalTokens: 0, inputKnown: false, outputKnown: false, totalKnown: false };
+      if (input != null) { current.inputTokens += input; current.inputKnown = true; }
+      if (output != null) { current.outputTokens += output; current.outputKnown = true; }
+      current.totalTokens += total ?? ((input ?? 0) + (output ?? 0));
+      current.totalKnown = true;
+      byTask[taskId] = current;
+    }
+  }
+  return { inputTokens, outputTokens, totalTokens, inputKnown, outputKnown, totalKnown, byTask };
+}
+
+function metricNumber(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : null;
+}
+
 function currentRun(state, events) {
   const runId = state.runId ?? state.runs?.find((run) => isActiveStatus(run.status))?.id ?? events.findLast?.((event) => event.runId)?.runId ?? null;
   if (!runId && !state.status) return null;

package/src/core/workflow.test.js

@@ -64,3 +64,60 @@ test('projectWorkflow reports approval and queue waiting reasons', () => {
   assert.ok(workflow.waitingReasons.includes('approval:approval-1'));
   assert.ok(workflow.waitingReasons.includes('queue:queued-1'));
 });
+
+test('projectWorkflow aggregates input and output tokens once per attempt', () => {
+  const state = {
+    status: 'done',
+    runId: 'run-usage',
+    plan: [{ id: 'build', description: 'Build', status: 'done' }],
+    activities: [],
+    queue: [],
+    approvals: [],
+  };
+  const result = {
+    attemptId: 'attempt-1',
+    metrics: { inputTokens: 1200, outputTokens: 300, totalTokens: 1500 },
+  };
+  const workflow = projectWorkflow(state, [
+    { id: 'event-1', type: 'task.result_returned', runId: 'run-usage', taskId: 'build', payload: { result } },
+    { id: 'event-2', type: 'task.completed', runId: 'run-usage', taskId: 'build', payload: { result } },
+  ]);
+
+  assert.deepEqual(workflow.usage, {
+    inputTokens: 1200,
+    outputTokens: 300,
+    totalTokens: 1500,
+    inputKnown: true,
+    outputKnown: true,
+    totalKnown: true,
+    byTask: {
+      build: {
+        inputTokens: 1200,
+        outputTokens: 300,
+        totalTokens: 1500,
+        inputKnown: true,
+        outputKnown: true,
+        totalKnown: true,
+      },
+    },
+  });
+});
+
+test('projectWorkflow derives per-task timing (start, finish, duration) from lifecycle events', () => {
+  const state = {
+    status: 'done',
+    runId: 'run-timing',
+    plan: [{ id: 'ingest', description: 'Ingest', status: 'done' }],
+    activities: [],
+    queue: [],
+    approvals: [],
+  };
+  const workflow = projectWorkflow(state, [
+    { id: 'e1', type: 'task.started', runId: 'run-timing', taskId: 'ingest', ts: '2026-07-23T10:00:00.000Z', payload: {} },
+    { id: 'e2', type: 'task.completed', runId: 'run-timing', taskId: 'ingest', ts: '2026-07-23T10:00:12.500Z', payload: {} },
+  ]);
+
+  assert.equal(workflow.timingByTask.ingest.startedAt, Date.parse('2026-07-23T10:00:00.000Z'));
+  assert.equal(workflow.timingByTask.ingest.finishedAt, Date.parse('2026-07-23T10:00:12.500Z'));
+  assert.equal(workflow.timingByTask.ingest.durationMs, 12500);
+});

package/src/orchestrator/scheduler.js

@@ -9,7 +9,11 @@ export function resolveSchedulerConcurrency(value = process.env.WIKI_MANAGER_SCH
     : DEFAULT_SCHEDULER_CONCURRENCY;
 }
 
-export function resolvePlanConcurrency({ plan = [], agents = [], configured = null } = {}) {
+// Display-only breakdown of the SAME computation resolvePlanConcurrency uses.
+// resolvePlanConcurrency delegates to this so the number surfaced to the UIs can
+// never diverge from the number the scheduler actually enforces. Never used to
+// gate scheduling — only `.limit` feeds startReadyTasks.
+export function describePlanConcurrency({ plan = [], agents = [], configured = null } = {}) {
   const capabilities = new Set(plan.map((task) => task?.requiredCapability).filter(Boolean).map(String));
   const assignedAgents = new Set(plan.map((task) => task?.agentInstanceId).filter(Boolean).map(String));
   const relevantAgents = agents.filter((agent) => {
@@ -17,12 +21,28 @@ export function resolvePlanConcurrency({ plan = [], agents = [], configured = nu
     if (id && assignedAgents.has(id)) return true;
     return (agent?.description?.capabilities ?? []).some((capability) => capabilities.has(String(capability?.id ?? '')));
   });
-  const values = [
-    positiveInteger(configured),
-    ...plan.flatMap(concurrencyValues),
-    ...relevantAgents.flatMap(concurrencyValues),
-  ].filter(Boolean);
-  return values.length > 0 ? Math.max(1, Math.min(...values)) : DEFAULT_SCHEDULER_CONCURRENCY;
+  const ceiling = positiveInteger(configured);
+  const agentValues = relevantAgents.flatMap(concurrencyValues).filter(Boolean);
+  const taskValues = plan.flatMap(concurrencyValues).filter(Boolean);
+  const values = [ceiling, ...taskValues, ...agentValues].filter(Boolean);
+  const limit = values.length > 0 ? Math.max(1, Math.min(...values)) : DEFAULT_SCHEDULER_CONCURRENCY;
+  const otherMin = [...taskValues, ...agentValues].length > 0
+    ? Math.min(...taskValues, ...agentValues)
+    : null;
+  // The manager ceiling "bit" when it is the (uniquely) binding constraint: it
+  // is set, equals the resolved limit, and is strictly below every other input.
+  const cappedByCeiling = ceiling != null && limit === ceiling && (otherMin == null || ceiling < otherMin);
+  return {
+    limit,
+    ceiling: ceiling ?? null,
+    agentLimit: agentValues.length > 0 ? Math.min(...agentValues) : null,
+    taskLimit: taskValues.length > 0 ? Math.min(...taskValues) : null,
+    cappedByCeiling,
+  };
+}
+
+export function resolvePlanConcurrency(options = {}) {
+  return describePlanConcurrency(options).limit;
 }
 
 export function resolveCapabilityConcurrency(agent = null, ...constraints) {

package/src/orchestrator/scheduler.test.js

@@ -7,6 +7,7 @@ import { createBudgetManager } from './budgetManager.js';
 import { readyTasks, tasksAwaitingApproval } from './dependencyResolver.js';
 import { createLockManager } from './lockManager.js';
 import {
+  describePlanConcurrency,
   effectiveConcurrency,
   resolveCapabilityConcurrency,
   resolvePlanConcurrency,
@@ -141,6 +142,28 @@ test('scheduler uses the relevant agent declaration instead of hard-capping plan
   assert.equal(resolvePlanConcurrency({ plan, agents, configured: 20 }), 10);
 });
 
+test('describePlanConcurrency mirrors resolvePlanConcurrency and flags the ceiling', () => {
+  const plan = [{ id: 'task-1', requiredCapability: 'ingest' }];
+  const agents = [{ description: { capabilities: [{ id: 'ingest' }], limits: { recommendedConcurrency: 10, maxConcurrency: 12 } } }];
+
+  // The number must never diverge from what the scheduler enforces.
+  for (const configured of [undefined, 3, 20]) {
+    const opts = configured === undefined ? { plan, agents } : { plan, agents, configured };
+    assert.equal(describePlanConcurrency(opts).limit, resolvePlanConcurrency(opts));
+  }
+
+  // Ceiling binds → flagged.
+  const capped = describePlanConcurrency({ plan, agents, configured: 3 });
+  assert.equal(capped.limit, 3);
+  assert.equal(capped.ceiling, 3);
+  assert.equal(capped.cappedByCeiling, true);
+
+  // Ceiling above the agent declaration → does not bind, not flagged.
+  const loose = describePlanConcurrency({ plan, agents, configured: 20 });
+  assert.equal(loose.limit, 10);
+  assert.equal(loose.cappedByCeiling, false);
+});
+
 test('scheduler ignores unrelated agents and falls back to three without declarations', () => {
   const plan = [{ id: 'task-1', requiredCapability: 'ingest' }];
   const agents = [{

package/src/runtime/runner.js

@@ -11,7 +11,7 @@ import { approvalRequestForTask } from '../orchestrator/approvalPolicy.js';
 import { PENDING_STATUSES, tasksAwaitingApproval } from '../orchestrator/dependencyResolver.js';
 import { assertValidatedFragment } from '../orchestrator/planValidator.js';
 import { createResultAggregator } from '../orchestrator/resultAggregator.js';
-import { drainActive, resolvePlanConcurrency, startReadyTasks } from '../orchestrator/scheduler.js';
+import { describePlanConcurrency, drainActive, startReadyTasks } from '../orchestrator/scheduler.js';
 import { emitRuntimeLog, pollActivitiesOnce } from './supervisor.js';
 
 // 0 by default: automatic replans turn evaluator/replanner TEXT into
@@ -363,11 +363,24 @@ export async function runRuntimeParallelPlan(agent, session, input, {
   const configuredConcurrency = Number(concurrency) > 0
     ? Number(concurrency)
     : Number(process.env.WIKI_MANAGER_CAPABILITY_CONCURRENCY || process.env.WIKI_MANAGER_SCHEDULER_CONCURRENCY);
-  const limit = resolvePlanConcurrency({
+  const concurrencyDetail = describePlanConcurrency({
     plan: session.headlessPlan ?? [],
     agents,
     configured: configuredConcurrency,
   });
+  const limit = concurrencyDetail.limit;
+  // Publish the RESOLVED concurrency so both UIs show the real dispatch cap
+  // (not a value re-derived from the fragment). Display-only: scheduling still
+  // uses `limit` exactly as before. NOTE: this is a plain field assignment — do
+  // NOT emit a runtime_log here (it runs before ensurePlanProjection and would
+  // clobber session.headlessPlan via applyAgentProjectionToSession). The audit
+  // line is folded into the existing "parallel plan enabled" log below.
+  session._runConcurrency = {
+    limit,
+    ceiling: concurrencyDetail.ceiling,
+    agentLimit: concurrencyDetail.agentLimit,
+    cappedByCeiling: concurrencyDetail.cappedByCeiling,
+  };
   const active = new Map();
   const attempts = attemptManager ?? createAttemptManager();
   const assigner = assignmentManager ?? createAssignmentManager({ session });
@@ -392,7 +405,7 @@ export async function runRuntimeParallelPlan(agent, session, input, {
   };
   sanitizeSessionPlanForExecution(session, runId);
   ensurePlanProjection(session, runId);
-  emitRuntimeLog(session, `scheduler: parallel plan enabled (concurrency ${limit})`);
+  emitRuntimeLog(session, `scheduler: parallel plan enabled (concurrency ${limit}; agent=${concurrencyDetail.agentLimit ?? 'n/a'}, ceiling=${concurrencyDetail.ceiling ?? 'none'}${concurrencyDetail.cappedByCeiling ? ' → capped by manager ceiling' : ''})`);
   // Interactive approvals do NOT expire: the user has /approve, "valide
   // tout", /cancel and /run kill — an arbitrary timer only created mystery
   // failures. A deadline exists only when explicitly configured (headless
@@ -534,6 +547,20 @@ export async function runRuntimeParallelPlan(agent, session, input, {
               workspace: session.workspace ?? null,
               payload: request,
             }));
+            // Reflect the block on the task's plan step so the UIs can render it
+            // distinctly (amber "[⏸]" in the Shell, banner/badge in serve)
+            // instead of leaving it as a neutral "pending" indistinguishable
+            // from a not-started step. Only promote a plain pending task — never
+            // overwrite a status the planner already set (e.g. waiting_approval).
+            const currentStatus = String(task.status ?? '').toLowerCase();
+            if (!['pending_approval', 'waiting_approval'].includes(currentStatus)) {
+              dispatchAgentEvent(session, createAgentEvent('plan_step_updated', {
+                origin: 'runtime',
+                runId,
+                taskId,
+                payload: { taskId, status: 'pending_approval' },
+              }));
+            }
           }
           if (newlyRequested.length > 0) {
             dispatchAgentEvent(session, createAgentEvent('assistant_message', {

package/src/runtime/store.js

@@ -541,6 +541,12 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
   const listApprovalGrantsByRunStatement = db.prepare(`
     SELECT * FROM approval_grants WHERE run_id = ? ORDER BY created_at ASC, id ASC
   `);
+  const listPendingApprovalGrantsByRunStatement = db.prepare(`
+    SELECT * FROM approval_grants WHERE run_id = ? AND status = 'pending_approval'
+  `);
+  const markApprovalGrantApprovedStatement = db.prepare(`
+    UPDATE approval_grants SET status = 'approved', granted_at = ? WHERE id = ?
+  `);
 
   function persistEvent(event) {
     if (NON_PERSISTED_EVENT_TYPES.has(event.type)) return event;
@@ -687,10 +693,12 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
       const delResults = db.prepare('DELETE FROM task_results WHERE task_id IN (SELECT id FROM tasks WHERE run_id = ?)');
       const delAssignments = db.prepare('DELETE FROM task_assignments WHERE task_id IN (SELECT id FROM tasks WHERE run_id = ?)');
       const delAttempts = db.prepare('DELETE FROM task_attempts WHERE run_id = ?');
+      const delApprovals = db.prepare('DELETE FROM approval_grants WHERE run_id = ?');
       for (const runId of runIds) {
         delResults.run(runId);
         delAssignments.run(runId);
         delAttempts.run(runId);
+        delApprovals.run(runId);
       }
       const events = (workspace
         ? db.prepare('DELETE FROM events WHERE workspace = ?').run(workspace)
@@ -1020,6 +1028,29 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
       status === 'approved' ? (payload.grantedAt ?? event.ts) : null,
       status === 'rejected' ? (payload.rejectedAt ?? event.ts) : null,
     );
+    // Mirror the in-memory projection's markCoveredApprovalsApproved into the
+    // persisted table: a broad (run/group) grant covers the per-task
+    // pending_approval requests, so mark them approved here too. Without this,
+    // the scheduler proceeds (the projection knows they're covered) but the
+    // approval_grants table keeps them pending_approval forever — orphaned rows
+    // that pile up (32 per run observed) and survive run purges.
+    if (status === 'approved') {
+      const grantedAt = payload.grantedAt ?? event.ts;
+      const grant = {
+        scope: String(payload.scope ?? 'run'),
+        runId: String(runId),
+        workspaceId: event.workspace ?? payload.workspaceId ?? payload.workspace ?? null,
+        planRevision: payload.planRevision == null ? null : Number(payload.planRevision),
+        groupId: payload.groupId ?? null,
+        approvalClasses: normalizeApprovalClasses(payload.approvalClasses ?? payload.approvalClass),
+        ids: new Set([payload.taskId, payload.itemId, payload.approvalId, payload.id, event.taskId]
+          .filter(Boolean).map(String)),
+      };
+      for (const row of listPendingApprovalGrantsByRunStatement.all(String(runId))) {
+        if (String(row.id) === String(id)) continue;
+        if (persistedGrantCovers(grant, row)) markApprovalGrantApprovedStatement.run(grantedAt, row.id);
+      }
+    }
   }
 
   function lifecycleTaskId(event) {
@@ -1177,6 +1208,10 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
     return {
       ...baseState,
       runs,
+      // Resolved scheduler concurrency for the live run (display-only). Null for
+      // replayed/historical state — the UIs then fall back to the plan-derived
+      // value. Never consumed by scheduling.
+      concurrency: session?._runConcurrency ?? null,
       workflow: projectWorkflow({ ...baseState, runs, workspace }, events ?? session?.agentEvents ?? []),
     };
   }
@@ -1281,9 +1316,11 @@ function purgeOldTerminalRuns(db, now = new Date()) {
   db.exec('BEGIN');
   try {
     const deleteEvents = db.prepare('DELETE FROM events WHERE run_id = ? OR json_extract(payload, \'$.runId\') = ?');
+    const deleteApprovals = db.prepare('DELETE FROM approval_grants WHERE run_id = ?');
     const deleteRun = db.prepare('DELETE FROM runs WHERE id = ?');
     for (const runId of oldRuns) {
       deleteEvents.run(runId, runId);
+      deleteApprovals.run(runId);
       deleteRun.run(runId);
     }
     db.exec('COMMIT');
@@ -1403,6 +1440,23 @@ function normalizeApprovalClasses(value) {
   return [...new Set(values.map((item) => String(item).trim()).filter(Boolean))];
 }
 
+// Persisted-table twin of markCoveredApprovalsApproved (core/agentEvents.js):
+// does `grant` (already-approved) cover the pending approval_grants `row`?
+// Kept in sync with that reducer so the DB never disagrees with the projection.
+function persistedGrantCovers(grant, row) {
+  if (grant.runId != null && row.run_id != null && String(grant.runId) !== String(row.run_id)) return false;
+  if (grant.workspaceId != null && row.workspace_id != null && String(grant.workspaceId) !== String(row.workspace_id)) return false;
+  if (grant.planRevision != null && row.plan_revision != null && Number(grant.planRevision) !== Number(row.plan_revision)) return false;
+  const rowClasses = row.approval_classes ? normalizeApprovalClasses(parseJsonMaybe(row.approval_classes)) : [];
+  if (grant.approvalClasses.length > 0 && rowClasses.length > 0 && !rowClasses.some((item) => grant.approvalClasses.includes(item))) return false;
+  if (grant.scope === 'group' && String(grant.groupId ?? '') !== String(row.group_id ?? '')) return false;
+  if (grant.scope === 'task' || grant.scope === 'tool') {
+    const rowIds = [row.task_id, row.id].filter(Boolean).map(String);
+    if (!rowIds.some((id) => grant.ids.has(id))) return false;
+  }
+  return true;
+}
+
 function parseJsonMaybe(value) {
   try {
     return JSON.parse(value);

package/src/runtime/store.test.js

@@ -540,6 +540,48 @@ test('runtime store persists bounded approval grants', () => {
   store.close();
 });
 
+test('runtime store: a run-scope grant marks covered task grants approved (no orphans)', () => {
+  const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-runtime-'));
+  const store = openRuntimeStore({ stateDir });
+  // Two per-task approval requests for the same run.
+  for (const taskId of ['run-x:ingest-a', 'run-x:ingest-b']) {
+    store.persistEvent(createAgentEvent('approval.requested', {
+      origin: 'runtime',
+      runId: 'run-x',
+      workspace: 'docs',
+      taskId,
+      payload: { id: `approval:${taskId}`, scope: 'task', runId: 'run-x', workspaceId: 'docs', taskId },
+    }));
+  }
+  assert.equal(store.listApprovalGrants({ runId: 'run-x' }).filter((g) => g.status === 'pending_approval').length, 2);
+
+  // A single run-scope grant covers both.
+  store.persistEvent(createAgentEvent('approval.granted', {
+    origin: 'runtime',
+    runId: 'run-x',
+    workspace: 'docs',
+    payload: { id: 'grant-run-x', scope: 'run', runId: 'run-x', workspaceId: 'docs' },
+  }));
+  const grants = store.listApprovalGrants({ runId: 'run-x' });
+  assert.equal(grants.filter((g) => g.status === 'pending_approval').length, 0, 'no task grant left pending');
+  assert.equal(grants.filter((g) => g.status === 'approved').length, 3, 'both tasks + run grant approved');
+  store.close();
+});
+
+test('runtime store: clearWorkspaceState removes approval grants', () => {
+  const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-runtime-'));
+  const store = openRuntimeStore({ stateDir });
+  store.persistEvent(createAgentEvent('run_started', { origin: 'runtime', runId: 'run-y', workspace: 'docs', payload: { runId: 'run-y' } }));
+  store.persistEvent(createAgentEvent('approval.requested', {
+    origin: 'runtime', runId: 'run-y', workspace: 'docs', taskId: 'run-y:t',
+    payload: { id: 'approval:run-y:t', scope: 'task', runId: 'run-y', workspaceId: 'docs', taskId: 'run-y:t' },
+  }));
+  assert.equal(store.listApprovalGrants({ runId: 'run-y' }).length, 1);
+  store.clearWorkspaceState({ workspace: 'docs' });
+  assert.equal(store.listApprovalGrants({ runId: 'run-y' }).length, 0);
+  store.close();
+});
+
 test('runtime store orders events by durable sequence', () => {
   const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-runtime-'));
   const store = openRuntimeStore({ stateDir });

package/src/shell/RightPane.tsx

@@ -145,11 +145,16 @@ function activityPercentBadge(activity: any): { text: string; bg: string; fg: st
 // pending icon). Shared by planStepColor and PlanPanel's icon().
 const DONE_STATUSES = ['done', 'complete', 'completed', 'success', 'succeeded'];
 const FAILED_STATUSES = ['failed', 'error'];
+// A task blocked on a human decision — distinct from both running and pending,
+// so it must not render as a neutral gray "[ ]" (indistinguishable from
+// not-started) nor as a running step.
+const APPROVAL_STATUSES = ['pending_approval', 'waiting_approval'];
 
 function planStepColor(step: PlanStep, firstPendingStep: number | null) {
   const status = String(step.status ?? '').toLowerCase();
   if (DONE_STATUSES.includes(status)) return '#8BD5CA';
   if (FAILED_STATUSES.includes(status)) return '#F38BA8';
+  if (APPROVAL_STATUSES.includes(status)) return '#FBBF24';
   if (status === 'running') return '#89B4FA';
   if (step.step === firstPendingStep) return '#89B4FA';
   return '#7F8C8D';
@@ -175,7 +180,7 @@ function queueSummary(item: QueueItem) {
   return parts.join(' ');
 }
 
-export function PlanPanel(props: { plan: PlanStep[]; width: number; jobName?: string }) {
+export function PlanPanel(props: { plan: PlanStep[]; width: number; jobName?: string; summary?: string | null; spinnerFrame?: string }) {
   // Keep one column for the native vertical scrollbar when the plan is long.
   const lineWidth = () => Math.max(8, props.width - 3);
   const firstPending = () => props.plan.find((s) => s.status === 'pending')?.step ?? null;
@@ -183,7 +188,11 @@ export function PlanPanel(props: { plan: PlanStep[]; width: number; jobName?: st
     const status = String(rawStatus ?? '').toLowerCase();
     if (DONE_STATUSES.includes(status)) return '[✓]';
     if (FAILED_STATUSES.includes(status)) return '[✗]';
-    return status === 'running' ? '[…]' : '[ ]';
+    if (APPROVAL_STATUSES.includes(status)) return '[⏸]';
+    // Animated braille spinner on the running step: a long production job (LLM
+    // building a template) otherwise leaves the whole plan visually frozen. Same
+    // frames as the chat spinner. Falls back to a static glyph if not supplied.
+    return status === 'running' ? `[${props.spinnerFrame ?? '…'}]` : '[ ]';
   };
   const visualRows = createMemo(() => props.plan.reduce((total, step) =>
     total + wrapLine(`${icon(step.status)} ${step.step}. ${step.description}`, lineWidth()).slice(0, 2).length, 0));
@@ -192,9 +201,17 @@ export function PlanPanel(props: { plan: PlanStep[]; width: number; jobName?: st
     return visualRows() > PLAN_VIEWPORT_ROWS ? `${label} (${props.plan.length}) · scroll` : label;
   };
   const viewportRows = () => Math.min(PLAN_VIEWPORT_ROWS, Math.max(1, visualRows()));
+  const summaryLines = () => props.summary ? wrapLine(props.summary, lineWidth()).slice(0, 2) : [];
   return (
     <box flexShrink={0} flexDirection="column" padding={1}>
       <text width={lineWidth()} fg="#D6DEE8" content={fit(title(), lineWidth())} />
+      <Show when={summaryLines().length > 0}>
+        <box flexShrink={0} flexDirection="column">
+          <Index each={summaryLines()}>
+            {(line) => <text width={lineWidth()} fg="#89B4FA" content={line()} />}
+          </Index>
+        </box>
+      </Show>
       <scrollbox
         height={viewportRows()}
         focusable={false}
@@ -469,6 +486,7 @@ export function RightPane(props: {
   activities: any[];
   logs: string[];
   plan: PlanStep[] | null;
+  runSummary?: string | null;
   queueItems: QueueItem[];
   queueInfo: QueueInfo;
   activeTab: 'plan' | 'queue';
@@ -476,6 +494,7 @@ export function RightPane(props: {
   pendingApprovals: any[];
   onApprove: () => void;
   onTabClick: (tab: 'plan' | 'queue') => void;
+  spinnerFrame?: string;
 }) {
   const planJobName = () => activityJobName(
     [...props.activities].reverse().find((activity) => !activity.terminal) ?? props.activities.at(-1),
@@ -501,7 +520,7 @@ export function RightPane(props: {
       <Show when={props.activeTab === 'queue'} fallback={(
         <>
           <Show when={props.plan && props.plan.length > 0}>
-            <PlanPanel width={props.width} plan={props.plan!} jobName={planJobName()} />
+            <PlanPanel width={props.width} plan={props.plan!} jobName={planJobName()} summary={props.runSummary} spinnerFrame={props.spinnerFrame} />
           </Show>
           <ActivityPanel width={props.width} activities={props.activities} />
         </>

package/src/shell/repl.test.js

@@ -100,6 +100,19 @@ test('ShellUI lets the right pane extend to the terminal edge', async () => {
   assert.doesNotMatch(pane, /height="100%" flexDirection="column" padding=\{1\}/);
 });
 
+test('ShellUI shows the canonical run summary above the plan', async () => {
+  const session = await readFile(new URL('./useSession.ts', import.meta.url), 'utf8');
+  const pane = await readFile(new URL('./RightPane.tsx', import.meta.url), 'utf8');
+  const tui = await readFile(new URL('./tui.tsx', import.meta.url), 'utf8');
+  assert.match(session, /const runSummary = createMemo/);
+  assert.match(session, /agent\$\{agents\.size === 1/);
+  assert.match(session, /parallel \$\{activeParallel\}\/×\$\{maxParallel\}/);
+  assert.match(session, /usage\.inputKnown/);
+  assert.match(session, /usage\.outputKnown/);
+  assert.match(pane, /summary=\{props\.runSummary\}/);
+  assert.match(tui, /runSummary=\{state\.runSummary\(\)\}/);
+});
+
 test('Flow/Trace does not repeat the runtime source prefix on every line', async () => {
   const source = await readFile(new URL('./RightPane.tsx', import.meta.url), 'utf8');
   const entryRenderer = source.slice(

package/src/shell/tui.tsx

@@ -287,7 +287,10 @@ function App(props: {
   });
 
   const spinnerTimer = setInterval(() => {
-    if (state.busy()) setSpinnerIndex((value) => (value + 1) % 10);
+    // Advance while the chat is streaming OR a runtime run is executing. Without
+    // executionActive(), the plan spinner froze on frame 0 during a scheduler-
+    // driven run (no conversation turn), so it looked static.
+    if (state.busy() || state.executionActive()) setSpinnerIndex((value) => (value + 1) % 10);
   }, 90);
   onCleanup(() => {
     clearInterval(spinnerTimer);
@@ -392,6 +395,7 @@ function App(props: {
             activities={state.activities()}
             logs={state.logs()}
             plan={state.plan()}
+            runSummary={state.runSummary()}
             queueItems={state.queueItems()}
             queueInfo={state.queueInfo()}
             activeTab={state.rightTab()}
@@ -399,6 +403,7 @@ function App(props: {
             pendingApprovals={state.pendingApprovals()}
             onApprove={() => { void state.submitInput('/approve'); }}
             onTabClick={state.selectRightTab}
+            spinnerFrame={SPINNER_FRAMES[spinnerIndex()] ?? SPINNER_FRAMES[0]}
           />
           <SlashDialog context={state.activeEditor() ? null : state.slash()} />
           <FileEditorDialog

package/src/shell/useSession.ts

@@ -321,6 +321,52 @@ export function useSession(props: { agent: unknown; packageJson: Record<string,
       ? lastVisiblePlan.map((step) => ({ ...step }))
       : current;
   });
+  const runSummary = createMemo(() => {
+    version();
+    const workflow = runtimeState()?.workflow;
+    const tasks = Array.isArray(workflow?.nodes)
+      ? workflow.nodes.filter((node: any) => node.type === 'task')
+      : [];
+    if (tasks.length === 0) return null;
+
+    const graphNodes = Array.isArray(workflow?.graph?.nodes) ? workflow.graph.nodes : [];
+    const graphEdges = Array.isArray(workflow?.graph?.edges) ? workflow.graph.edges : [];
+    const agents = new Set<string>();
+    for (const task of tasks) {
+      if (task.executor) agents.add(String(task.executor));
+      const assignmentIds = graphEdges
+        .filter((edge: any) => edge.type === 'assigned_to' && edge.from === task.id)
+        .map((edge: any) => edge.to);
+      for (const assignmentId of assignmentIds) {
+        graphEdges
+          .filter((edge: any) => edge.type === 'uses_agent' && edge.from === assignmentId)
+          .forEach((edge: any) => agents.add(String(edge.to).replace(/^agent:/, '')));
+      }
+    }
+
+    const activeParallel = tasks.filter((task: any) => String(task.status) === 'running').length;
+    const groupConcurrency = graphNodes
+      .filter((node: any) => node.type === 'task_group')
+      .map((node: any) => Number(node.raw?.recommendedConcurrency))
+      .filter((value: number) => Number.isFinite(value) && value > 0);
+    // Authoritative resolved concurrency published by the runtime; fall back to
+    // the plan-derived value for replayed/historical runs.
+    const resolved = runtimeState()?.concurrency;
+    const maxParallel = Number.isFinite(Number(resolved?.limit))
+      ? Number(resolved.limit)
+      : Math.max(1, activeParallel, ...groupConcurrency);
+    const done = tasks.filter((task: any) => String(task.status) === 'done').length;
+    const usage = workflow?.usage ?? {};
+    const tokens = (known: unknown, value: unknown) =>
+      known ? new Intl.NumberFormat().format(Number(value) || 0) : '—';
+
+    return [
+      `${agents.size} agent${agents.size === 1 ? '' : 's'}`,
+      `parallel ${activeParallel}/×${maxParallel}${resolved?.cappedByCeiling ? ' (ceiling)' : ''}`,
+      `${done}/${tasks.length} tasks`,
+      `${tokens(usage.inputKnown, usage.inputTokens)} in · ${tokens(usage.outputKnown, usage.outputTokens)} out`,
+    ].join(' · ');
+  });
   const visibleLogs = createMemo(() => {
     version();
     const runtimeLogs = runtimeState()?.logs;
@@ -728,6 +774,7 @@ export function useSession(props: { agent: unknown; packageJson: Record<string,
     toggleRightTab,
     selectRightTab,
     plan,
+    runSummary,
     pendingApprovals,
     conversationScroll,
     scrollConversation,