@dotdrelle/wiki-manager 0.8.2 → 0.9.3

package/README.md

@@ -460,6 +460,21 @@ 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.
 
+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
+`{"action":"enqueue","input":"..."}` accepts a new request without touching the
+active plan. A queued request starts automatically as soon as the workspace
+goes idle — either because the enqueue call itself found the workspace free,
+or because the run in progress finished and drained the next queued item.
+
+`GET /config/profiles` lists the `.wikirc` profiles for a workspace and
+`POST /config/use {"profile":"..."}` switches the active one — the same
+switch as the shell's `/config use`, rejected with 409 while a run is active.
+The manager is the source of truth for which profile is active; `llm-wiki
+serve`'s config-profile picker mirrors whatever the manager reports rather
+than tracking its own state.
+
 ### Starting external agents
 
 Start CME, documents, and mailer once for all workspaces:

package/package.json

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

package/src/cli/wiki-manager.js

@@ -8,6 +8,8 @@ import { createAgentGraph } from '../agent/graph.js';
 import { handleSlashCommand, printHelp, printVersion, refreshMcpRuntimeStatus } from '../commands/slash.js';
 import { runShell } from '../shell/repl.js';
 import { runChecks } from '../core/startupCheck.js';
+import { applySessionWikircProfile } from '../core/sessionConfig.js';
+import { listWikircProfiles } from '../core/wikirc.js';
 import { callMcpTool, formatMcpToolResult } from '../core/mcp.js';
 import { extractActivity, parseJsonText, sessionActivities, terminalFailures } from '../core/activity.js';
 import { syncActivitiesToPlan, formatPlanStatus } from '../core/plan.js';
@@ -512,11 +514,14 @@ async function runRuntime(argv, agent) {
         };
       }
       emitRuntimeLog(context.session, manual ? 'runtime: manual resume completed' : 'runtime: recovery completed');
+      const controlStarted = pollingActivities.length === 0
+        ? serverHandle?.drainControl?.(context) === true
+        : false;
       return {
         workspace: context.workspace ?? workspace ?? null,
         resumed: true,
         interrupted: 0,
-        mode: pollingActivities.length > 0 ? 'activity_poll' : 'context',
+        mode: controlStarted ? 'control_queue' : pollingActivities.length > 0 ? 'activity_poll' : 'context',
       };
     } catch (err) {
       const interrupted = store.interruptRuns({ workspace });
@@ -629,6 +634,33 @@ async function runRuntime(argv, agent) {
       const context = await getWorkspaceContext(workspace);
       return context.approvalManager?.approve({ runId, itemId, approvalId }) ?? { approved: false };
     },
+    configProfiles: async (context) => {
+      const profiles = listWikircProfiles(context.session.workspacePath);
+      return {
+        profiles: profiles.map((profile) => profile.name),
+        active: context.session.wikirc?.profile ?? null,
+        items: profiles.map((profile) => ({
+          name: profile.name,
+          fileName: profile.fileName,
+          default: Boolean(profile.default),
+        })),
+      };
+    },
+    useConfigProfile: async (context, profile) => {
+      const { summary, config } = applySessionWikircProfile(context.session, profile);
+      await refreshMcpRuntimeStatus(context.session);
+      dispatchAgentEvent(context.session, createAgentEvent('runtime_log', {
+        origin: 'runtime',
+        payload: { message: `runtime: config profile switched to ${context.session.wikirc?.profile ?? profile}` },
+      }));
+      return {
+        ok: true,
+        active: context.session.wikirc?.profile ?? profile,
+        fileName: context.session.wikirc?.fileName ?? null,
+        summary,
+        config,
+      };
+    },
     token: auth.token,
   });
   const recovery = await recoverRuntime();

package/src/commands/slash.js

@@ -1,7 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { createLlmClientFromWikiConfig } from '../agent/llm.js';
 import { composeServices, listServices, runWikiCli, serviceLogs, serviceStates, startService, stopService } from '../core/compose.js';
 import {
   applyMcpRuntimeStatus,
@@ -26,10 +25,10 @@ import {
 } from '../core/jobQueue.js';
 import {
   listWikircProfiles,
-  loadWikircProfile,
   resolveWikircProfile,
   summarizeWikircConfig,
 } from '../core/wikirc.js';
+import { applySessionWikircProfile } from '../core/sessionConfig.js';
 import { deleteWorkspaceAndFiles, startAgents, stopAgents } from '../core/wikiSetup.js';
 import {
   cleanDocumentUploads,
@@ -546,25 +545,6 @@ function loadWorkspaceSystemPrompt(workspacePath) {
   return existsSync(promptPath) ? readFileSync(promptPath, 'utf8').trim() || null : null;
 }
 
-function loadSessionWikirc(session, profileName = 'default') {
-  if (!session.workspacePath) {
-    throw new Error('No workspace loaded. Use /use <workspace>.');
-  }
-  const loaded = loadWikircProfile(session.workspacePath, profileName);
-  session.wikirc = {
-    profile: loaded.profile.name,
-    fileName: loaded.profile.fileName,
-    path: loaded.profile.path,
-  };
-  session.wikircConfig = loaded.config;
-  session.language = loaded.config?.language ?? null;
-  session.llm = createLlmClientFromWikiConfig(loaded.config);
-  if (session.mcp?.production) {
-    session.mcp.production.activeConfigPath = loaded.profile.fileName;
-  }
-  return summarizeWikircConfig(loaded.profile, loaded.config);
-}
-
 function clearWorkspaceSession(session) {
   session.workspace = null;
   session.workspacePath = null;
@@ -720,7 +700,7 @@ export async function handleSlashCommand(line, context) {
       context.session.systemPrompt = loadWorkspaceSystemPrompt(workspace.workspacePath);
       try {
         step(`Workspace: loading ${workspace.name} config…`);
-        const summary = loadSessionWikirc(context.session, 'default');
+        const { summary } = applySessionWikircProfile(context.session, 'default');
         step(`Workspace: discovering ${workspace.name} MCP tools…`);
         await refreshMcpRuntimeStatus(context.session);
         return {
@@ -759,7 +739,7 @@ export async function handleSlashCommand(line, context) {
           return { output: 'Usage: /config use <default|name>' };
         }
         try {
-          const summary = loadSessionWikirc(context.session, profileName);
+          const { summary } = applySessionWikircProfile(context.session, profileName);
           await refreshMcpRuntimeStatus(context.session);
           return {
             output: [

package/src/core/agentEvents.js

@@ -12,6 +12,8 @@ const SESSION_PROJECTION_EVENTS = new Set([
   'run_approved',
   'tool_pending_approval',
   'tool_approved',
+  'control_enqueued',
+  'control_started',
   'run_done',
   'run_error',
   'run_cancelled',
@@ -101,6 +103,7 @@ function createProjectionState() {
     evaluation: null,
     replans: [],
     approvals: [],
+    controlQueue: [],
     summary: null,
     status: 'idle',
   };
@@ -116,6 +119,7 @@ function publicProjection(state) {
     evaluation: state.evaluation ? { ...state.evaluation } : null,
     replans: state.replans.map((replan) => ({ ...replan, plan: [...(replan.plan ?? [])] })),
     approvals: state.approvals.map((approval) => ({ ...approval })),
+    controlQueue: state.controlQueue.map((item) => ({ ...item })),
     summary: state.summary,
     status: state.status,
   };
@@ -124,6 +128,7 @@ function publicProjection(state) {
 export function applyAgentProjectionToSession(session, projection) {
   session.headlessPlan = projection.plan ? projection.plan.map((step) => ({ ...step })) : null;
   session.activities = Object.fromEntries((projection.activities ?? []).map((activity) => [activity.key, { ...activity }]));
+  session.controlQueue = (projection.controlQueue ?? []).map((item) => ({ ...item }));
   const production = (projection.activities ?? []).filter((activity) => activity.source === 'production').at(-1);
   session.productionActivity = production ? {
     jobId: production.id,
@@ -226,14 +231,36 @@ function applyEvent(state, event) {
     case 'run_done':
       state.status = 'done';
       finishPendingPlanSteps(state.plan);
+      finishControlByRun(state.controlQueue, event.runId ?? event.payload?.runId ?? null, 'done', event.ts);
       return;
     case 'run_cancelled':
       state.status = 'cancelled';
       state.logs.push(String(event.payload?.message ?? 'Agent run cancelled.'));
+      finishControlByRun(state.controlQueue, event.runId ?? event.payload?.runId ?? null, 'cancelled', event.ts);
       return;
     case 'run_error':
       state.status = 'error';
       state.logs.push(String(event.payload?.message ?? 'Agent run failed.'));
+      finishControlByRun(state.controlQueue, event.runId ?? event.payload?.runId ?? null, 'failed', event.ts);
+      return;
+    case 'control_enqueued':
+      upsertControlItem(state.controlQueue, {
+        id: event.payload?.id ?? event.id,
+        workspace: event.workspace ?? event.payload?.workspace ?? null,
+        input: String(event.payload?.input ?? ''),
+        status: 'queued',
+        createdAt: event.payload?.createdAt ?? event.ts,
+        updatedAt: event.ts,
+      });
+      return;
+    case 'control_started':
+      upsertControlItem(state.controlQueue, {
+        id: event.payload?.id ?? null,
+        runId: event.runId ?? event.payload?.runId ?? null,
+        status: 'running',
+        startedAt: event.payload?.startedAt ?? event.ts,
+        updatedAt: event.ts,
+      });
       return;
     case 'runtime_log':
       state.logs.push(String(event.payload?.message ?? ''));
@@ -244,6 +271,32 @@ function applyEvent(state, event) {
   }
 }
 
+function upsertById(list, next) {
+  const index = list.findIndex((item) => item.id === next.id);
+  if (index === -1) {
+    list.push(next);
+    return;
+  }
+  list[index] = {
+    ...list[index],
+    ...next,
+  };
+}
+
+function upsertControlItem(queue, next) {
+  if (!next.id) return;
+  upsertById(queue, next);
+}
+
+function finishControlByRun(queue, runId, status, finishedAt) {
+  if (!runId) return;
+  const item = queue.find((entry) => entry.runId === runId && entry.status === 'running');
+  if (!item) return;
+  item.status = status;
+  item.finishedAt = finishedAt;
+  item.updatedAt = finishedAt;
+}
+
 function appendAssistantDelta(state, delta) {
   if (!delta) return;
   const last = state.conversation.at(-1);
@@ -279,15 +332,7 @@ function finishToolCall(state, payload = {}) {
 }
 
 function upsertApproval(state, next) {
-  const index = state.approvals.findIndex((approval) => approval.id === next.id);
-  if (index === -1) {
-    state.approvals.push(next);
-    return;
-  }
-  state.approvals[index] = {
-    ...state.approvals[index],
-    ...next,
-  };
+  upsertById(state.approvals, next);
 }
 
 function finishPendingPlanSteps(plan) {

package/src/core/agentEvents.test.js

@@ -210,6 +210,37 @@ test('reduceAgentEvents: approvals move from pending to approved', () => {
   assert.deepEqual(projection.approvals[0].plan, ['Build']);
 });
 
+test('reduceAgentEvents: control queue is event sourced and follows run status', () => {
+  const projection = reduceAgentEvents([
+    createAgentEvent('control_enqueued', {
+      origin: 'runtime',
+      workspace: 'docs',
+      payload: {
+        id: 'control-1',
+        workspace: 'docs',
+        input: 'Run after current task',
+        createdAt: '2026-01-01T00:00:00.000Z',
+      },
+    }),
+    createAgentEvent('control_started', {
+      origin: 'runtime',
+      runId: 'run-control-1',
+      workspace: 'docs',
+      payload: { id: 'control-1', runId: 'run-control-1' },
+    }),
+    createAgentEvent('run_done', {
+      origin: 'runtime',
+      runId: 'run-control-1',
+      workspace: 'docs',
+    }),
+  ]);
+
+  assert.equal(projection.controlQueue.length, 1);
+  assert.equal(projection.controlQueue[0].id, 'control-1');
+  assert.equal(projection.controlQueue[0].status, 'done');
+  assert.equal(projection.controlQueue[0].runId, 'run-control-1');
+});
+
 test('reduceAgentEvents: activity-owned plan is used when no orchestrator plan exists', () => {
   const projection = reduceAgentEvents([
     createAgentEvent('activity_upserted', {

package/src/core/mcp.js

@@ -230,7 +230,7 @@ async function mcpRequest(endpoint, method, params, signal, options = {}) {
           params: {
             protocolVersion: '2025-06-18',
             capabilities: {},
-            clientInfo: { name: 'wiki-manager', version: '0.8.2' },
+            clientInfo: { name: 'wiki-manager', version: '0.9.3' },
           },
         }),
       });

package/src/core/sessionConfig.js

@@ -0,0 +1,24 @@
+import { createLlmClientFromWikiConfig } from '../agent/llm.js';
+import { loadWikircProfile, summarizeWikircConfig } from './wikirc.js';
+
+export function applySessionWikircProfile(session, profileName = 'default') {
+  if (!session.workspacePath) {
+    throw new Error('No workspace loaded. Use /use <workspace>.');
+  }
+  const loaded = loadWikircProfile(session.workspacePath, profileName);
+  session.wikirc = {
+    profile: loaded.profile.name,
+    fileName: loaded.profile.fileName,
+    path: loaded.profile.path,
+  };
+  session.wikircConfig = loaded.config;
+  session.language = loaded.config?.language ?? null;
+  session.llm = createLlmClientFromWikiConfig(loaded.config);
+  if (session.mcp?.production) {
+    session.mcp.production.activeConfigPath = loaded.profile.fileName;
+  }
+  return {
+    summary: summarizeWikircConfig(loaded.profile, loaded.config),
+    config: loaded.config,
+  };
+}

package/src/runtime/server.js

@@ -1,5 +1,6 @@
 import { createServer } from 'node:http';
 import { randomUUID } from 'node:crypto';
+import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { runtimeTokenFromEnv } from './auth.js';
 
 export function startRuntimeServer({
@@ -13,6 +14,8 @@ export function startRuntimeServer({
   cancel,
   resume,
   approve,
+  configProfiles,
+  useConfigProfile,
 } = {}) {
   const clients = new Set();
   const defaultContext = { workspace: null, session, running: false, currentAbortController: null };
@@ -56,6 +59,72 @@ export function startRuntimeServer({
         sendJson(response, 200, { events: store.listEvents({ workspace }) });
         return;
       }
+      if (request.method === 'GET' && url.pathname === '/control') {
+        const workspace = workspaceFromUrl(url);
+        const context = await resolveContext({ workspace });
+        sendJson(response, 200, controlStatus(context, store));
+        return;
+      }
+      if (request.method === 'POST' && url.pathname === '/control') {
+        const { body, context } = await resolveBodyContext(request, url);
+        const action = String(body.action ?? 'status').trim().toLowerCase();
+        if (action === 'status') {
+          sendJson(response, 200, controlStatus(context, store));
+          return;
+        }
+        if (action === 'explain') {
+          const status = controlStatus(context, store);
+          sendJson(response, 200, { ...status, explanation: explainControlState(status) });
+          return;
+        }
+        if (action === 'enqueue') {
+          const input = String(body.input ?? body.prompt ?? body.request ?? '').trim();
+          if (!input) {
+            sendJson(response, 400, { error: 'Missing input.' });
+            return;
+          }
+          const item = enqueueControlRequest(context, input);
+          void startNextControlRequest(context);
+          sendJson(response, 202, {
+            accepted: true,
+            item,
+            ...controlStatus(context, store),
+          });
+          return;
+        }
+        sendJson(response, 400, { error: 'Unsupported control action.' });
+        return;
+      }
+      if (request.method === 'GET' && url.pathname === '/config/profiles') {
+        if (typeof configProfiles !== 'function') {
+          sendJson(response, 501, { error: 'Config profiles are not supported.' });
+          return;
+        }
+        const workspace = workspaceFromUrl(url);
+        const context = await resolveContext({ workspace });
+        const result = await configProfiles(context);
+        sendJson(response, 200, result);
+        return;
+      }
+      if (request.method === 'POST' && url.pathname === '/config/use') {
+        if (typeof useConfigProfile !== 'function') {
+          sendJson(response, 501, { error: 'Config profile switching is not supported.' });
+          return;
+        }
+        const { body, context } = await resolveBodyContext(request, url);
+        if (context.running) {
+          sendJson(response, 409, { error: 'Cannot switch config while a runtime run is active.' });
+          return;
+        }
+        const profile = String(body.profile ?? '').trim();
+        if (!profile) {
+          sendJson(response, 400, { error: 'Missing profile.' });
+          return;
+        }
+        const result = await useConfigProfile(context, profile);
+        sendJson(response, 200, result);
+        return;
+      }
       if (request.method === 'GET' && url.pathname === '/events/stream') {
         const workspace = workspaceFromUrl(url);
         const context = workspace ? await resolveContext({ workspace }) : null;
@@ -72,9 +141,7 @@ export function startRuntimeServer({
         return;
       }
       if (request.method === 'POST' && url.pathname === '/run') {
-        const body = await readJson(request);
-        const workspace = workspaceFromBody(body) ?? workspaceFromUrl(url);
-        const context = await resolveContext({ workspace });
+        const { body, context } = await resolveBodyContext(request, url);
         if (context.running) {
           sendJson(response, 409, { error: 'A runtime run is already active.' });
           return;
@@ -85,21 +152,8 @@ export function startRuntimeServer({
             sendJson(response, 400, { error: 'Missing input.' });
             return;
           }
-          const runId = randomUUID();
-          const runWorkspace = context.workspace ?? workspace ?? null;
-          context.running = true;
-          context.currentAbortController = new AbortController();
-          const runBody = { ...body, workspace: runWorkspace, runId };
-          const runPromise = run(context, runBody, { signal: context.currentAbortController.signal, runId });
-          runPromise
-            .catch((err) => {
-              context.session?._onRuntimeError?.(err);
-            })
-            .finally(() => {
-              context.running = false;
-              context.currentAbortController = null;
-            });
-          sendJson(response, 202, { accepted: true, runId, workspace: runWorkspace });
+          const accepted = startRuntimeRun(context, body);
+          sendJson(response, 202, accepted);
         } catch (err) {
           context.running = false;
           context.currentAbortController = null;
@@ -153,6 +207,7 @@ export function startRuntimeServer({
         host,
         port: typeof address === 'object' && address ? address.port : port,
         publish,
+        drainControl: (context) => startNextControlRequest(context),
         close: () => new Promise((closeResolve, closeReject) => {
           for (const client of clients) client.response.end();
           clients.clear();
@@ -165,6 +220,54 @@ export function startRuntimeServer({
   async function resolveContext({ workspace = null } = {}) {
     return resolvedGetContext(workspace);
   }
+
+  // Shared by POST handlers that take a JSON body carrying an optional
+  // `workspace` field: read the body, resolve the target workspace (body
+  // wins over the `?workspace=` query param), then resolve its context.
+  async function resolveBodyContext(request, url) {
+    const body = await readJson(request);
+    const workspace = workspaceFromBody(body) ?? workspaceFromUrl(url);
+    const context = await resolveContext({ workspace });
+    return { body, workspace, context };
+  }
+
+  function startRuntimeRun(context, body, { controlItemId = null } = {}) {
+    const runId = randomUUID();
+    const runWorkspace = context.workspace ?? body.workspace ?? null;
+    context.running = true;
+    context.currentAbortController = new AbortController();
+    const runBody = { ...body, workspace: runWorkspace, runId };
+    if (controlItemId) {
+      dispatchAgentEvent(context.session, createAgentEvent('control_started', {
+        origin: 'runtime',
+        runId,
+        workspace: runWorkspace,
+        payload: { id: controlItemId, runId },
+      }));
+    }
+    const runPromise = run(context, runBody, { signal: context.currentAbortController.signal, runId });
+    runPromise
+      .catch((err) => {
+        context.session?._onRuntimeError?.(err);
+      })
+      .finally(() => {
+        context.running = false;
+        context.currentAbortController = null;
+        void startNextControlRequest(context);
+      });
+    return { accepted: true, runId, workspace: runWorkspace };
+  }
+
+  function startNextControlRequest(context) {
+    if (!context?.session || context.running) return false;
+    const item = controlQueueFor(context.session).find((entry) => entry.status === 'queued');
+    if (!item) return false;
+    startRuntimeRun(context, {
+      input: item.input,
+      workspace: item.workspace ?? context.workspace ?? null,
+    }, { controlItemId: item.id });
+    return true;
+  }
 }
 
 function workspaceFromUrl(url) {
@@ -177,6 +280,66 @@ function workspaceFromBody(body) {
   return workspace == null ? null : String(workspace).trim() || null;
 }
 
+function controlStatus(context, store) {
+  const workspace = context?.workspace ?? context?.session?.workspace ?? null;
+  const state = store.getState(context?.session ?? null, { workspace });
+  return {
+    ok: true,
+    workspace,
+    status: context?.running ? 'running' : state.status ?? 'idle',
+    running: Boolean(context?.running),
+    plan: Array.isArray(state.plan) ? state.plan : [],
+    queue: Array.isArray(state.queue) ? state.queue : [],
+    controlQueue: controlQueueFor(context?.session),
+    approvals: Array.isArray(state.approvals) ? state.approvals : [],
+    summary: state.summary ?? null,
+  };
+}
+
+function explainControlState(status) {
+  if (status.running) {
+    const runningStep = status.plan.find((step) => step.status === 'running');
+    return runningStep
+      ? `Runtime run is active. Current step: ${runningStep.description ?? runningStep.label ?? runningStep.step}.`
+      : 'Runtime run is active. No current plan step is available yet.';
+  }
+  const pendingApproval = status.approvals.find((approval) => approval.status === 'pending_approval');
+  if (pendingApproval) {
+    return `Runtime is waiting for approval: ${pendingApproval.reason ?? pendingApproval.id}.`;
+  }
+  const queued = status.controlQueue.filter((item) => item.status === 'queued');
+  if (queued.length > 0) {
+    return `${queued.length} control request${queued.length === 1 ? '' : 's'} queued. They are not applied to the active plan automatically.`;
+  }
+  if (status.plan.some((step) => step.status === 'pending')) {
+    return 'Runtime is idle with pending plan steps visible from the last run.';
+  }
+  return 'Runtime is idle.';
+}
+
+function controlQueueFor(session) {
+  return Array.isArray(session?.controlQueue) ? session.controlQueue : [];
+}
+
+function enqueueControlRequest(context, input) {
+  const now = new Date().toISOString();
+  const item = {
+    id: `control-${randomUUID()}`,
+    workspace: context?.workspace ?? context?.session?.workspace ?? null,
+    type: 'run_request',
+    input,
+    status: 'queued',
+    createdAt: now,
+    updatedAt: now,
+  };
+  dispatchAgentEvent(context.session, createAgentEvent('control_enqueued', {
+    origin: 'runtime',
+    workspace: item.workspace,
+    payload: item,
+  }));
+  return item;
+}
+
 function isAuthorized(request, token) {
   if (!token) return true;
   const authorization = request.headers.authorization ?? '';

package/src/runtime/server.test.js

@@ -306,3 +306,325 @@ test('runtime server exposes approval endpoint', async (t) => {
     await handle.close();
   }
 });
+
+test('runtime server exposes control status and explanation', async (t) => {
+  const session = {
+    workspace: 'juno',
+    controlQueue: [{ id: 'control-1', workspace: 'juno', status: 'queued', input: 'later' }],
+  };
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({
+          status: 'idle',
+          plan: [{ step: 1, description: 'Check status', status: 'pending' }],
+          queue: [],
+          controlQueue: session.controlQueue,
+          approvals: [],
+          summary: null,
+        }),
+        listEvents: () => [],
+      },
+      getContext: async () => ({
+        workspace: 'juno',
+        session,
+        running: false,
+        currentAbortController: null,
+      }),
+      run: async () => {},
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const status = await fetch(`http://127.0.0.1:${handle.port}/control?workspace=juno`);
+    assert.equal(status.status, 200);
+    const statusBody = await status.json();
+    assert.equal(statusBody.status, 'idle');
+    assert.equal(statusBody.running, false);
+    assert.equal(statusBody.controlQueue[0].id, 'control-1');
+
+    const explain = await fetch(`http://127.0.0.1:${handle.port}/control?workspace=juno`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'explain' }),
+    });
+    assert.equal(explain.status, 200);
+    assert.match((await explain.json()).explanation, /control request/);
+  } finally {
+    await handle.close();
+  }
+});
+
+test('runtime server control enqueue emits events but does not patch an active plan or start a run', async (t) => {
+  const session = {
+    workspace: 'juno',
+    controlQueue: [],
+  };
+  const events = [];
+  session._onAgentEvent = (event) => events.push(event);
+  let runCount = 0;
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({
+          status: 'running',
+          plan: [{ step: 1, description: 'Active step', status: 'running' }],
+          queue: [],
+          controlQueue: session.controlQueue,
+          approvals: [],
+          summary: null,
+        }),
+        listEvents: () => [],
+      },
+      getContext: async () => ({
+        workspace: 'juno',
+        session,
+        running: true,
+        currentAbortController: new AbortController(),
+      }),
+      run: async () => { runCount += 1; },
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${handle.port}/control?workspace=juno`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'enqueue', input: 'run this after current work' }),
+    });
+    assert.equal(response.status, 202);
+    const body = await response.json();
+    assert.equal(body.accepted, true);
+    assert.equal(body.item.status, 'queued');
+    assert.equal(body.controlQueue.length, 1);
+    assert.equal(body.plan[0].description, 'Active step');
+    assert.equal(session.controlQueue[0].input, 'run this after current work');
+    assert.equal(events.filter((event) => event.type === 'control_enqueued').length, 1);
+    assert.equal(runCount, 0);
+  } finally {
+    await handle.close();
+  }
+});
+
+test('runtime server drains queued control requests when idle', async (t) => {
+  const session = {
+    workspace: 'juno',
+    controlQueue: [],
+  };
+  const events = [];
+  session._onAgentEvent = (event) => events.push(event);
+  let receivedBody = null;
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({
+          status: 'idle',
+          plan: [],
+          queue: [],
+          controlQueue: session.controlQueue,
+          approvals: [],
+          summary: null,
+        }),
+        listEvents: () => [],
+      },
+      getContext: async () => ({
+        workspace: 'juno',
+        session,
+        running: false,
+        currentAbortController: null,
+      }),
+      run: async (_context, body) => {
+        receivedBody = body;
+      },
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${handle.port}/control?workspace=juno`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ action: 'enqueue', input: 'run from control queue' }),
+    });
+    assert.equal(response.status, 202);
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(receivedBody.input, 'run from control queue');
+    assert.equal(receivedBody.workspace, 'juno');
+    assert.match(receivedBody.runId, /^[0-9a-f-]{36}$/);
+    assert.equal(session.controlQueue[0].status, 'running');
+    assert.equal(session.controlQueue[0].runId, receivedBody.runId);
+    assert.deepEqual(events.map((event) => event.type), ['control_enqueued', 'control_started']);
+  } finally {
+    await handle.close();
+  }
+});
+
+test('runtime server handle drains a pre-existing hydrated control request', async (t) => {
+  const session = {
+    workspace: 'juno',
+    controlQueue: [{ id: 'control-existing', workspace: 'juno', status: 'queued', input: 'resume queued control' }],
+  };
+  const events = [];
+  session._onAgentEvent = (event) => events.push(event);
+  const context = {
+    workspace: 'juno',
+    session,
+    running: false,
+    currentAbortController: null,
+  };
+  let receivedBody = null;
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({ status: 'idle' }),
+        listEvents: () => [],
+      },
+      getContext: async () => context,
+      run: async (_context, body) => {
+        receivedBody = body;
+      },
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    assert.equal(handle.drainControl(context), true);
+    await new Promise((resolve) => setImmediate(resolve));
+    assert.equal(receivedBody.input, 'resume queued control');
+    assert.equal(session.controlQueue[0].status, 'running');
+    assert.equal(events[0].type, 'control_started');
+  } finally {
+    await handle.close();
+  }
+});
+
+test('runtime server exposes config profile list and switch endpoints', async (t) => {
+  const context = {
+    workspace: 'juno',
+    session: { workspace: 'juno', wikirc: { profile: 'default' } },
+    running: false,
+    currentAbortController: null,
+  };
+  let switchedProfile = null;
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({ status: 'idle' }),
+        listEvents: () => [],
+      },
+      getContext: async () => context,
+      run: async () => {},
+      configProfiles: async () => ({ profiles: ['default', 'vpn'], active: context.session.wikirc.profile }),
+      useConfigProfile: async (_context, profile) => {
+        switchedProfile = profile;
+        context.session.wikirc.profile = profile;
+        return { ok: true, active: profile, config: { llm: { model: 'model-vpn' } } };
+      },
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const profiles = await fetch(`http://127.0.0.1:${handle.port}/config/profiles?workspace=juno`);
+    assert.equal(profiles.status, 200);
+    assert.deepEqual(await profiles.json(), { profiles: ['default', 'vpn'], active: 'default' });
+
+    const use = await fetch(`http://127.0.0.1:${handle.port}/config/use?workspace=juno`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ profile: 'vpn' }),
+    });
+    assert.equal(use.status, 200);
+    assert.equal(switchedProfile, 'vpn');
+    assert.deepEqual(await use.json(), { ok: true, active: 'vpn', config: { llm: { model: 'model-vpn' } } });
+  } finally {
+    await handle.close();
+  }
+});
+
+test('runtime server rejects config switching while a run is active', async (t) => {
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({ status: 'running' }),
+        listEvents: () => [],
+      },
+      getContext: async () => ({
+        workspace: 'juno',
+        session: { workspace: 'juno' },
+        running: true,
+        currentAbortController: null,
+      }),
+      run: async () => {},
+      useConfigProfile: async () => ({ ok: true }),
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  try {
+    const response = await fetch(`http://127.0.0.1:${handle.port}/config/use?workspace=juno`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ profile: 'vpn' }),
+    });
+    assert.equal(response.status, 409);
+  } finally {
+    await handle.close();
+  }
+});

package/src/runtime/store.js

@@ -366,6 +366,9 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
       ...projection,
       runs: listRuns({ workspace }),
       queue: projectQueue(projection.plan, rawQueue, { workspace }),
+      controlQueue: Array.isArray(projection.controlQueue)
+        ? projection.controlQueue.filter((item) => !workspace || item.workspace === workspace || !item.workspace).map((item) => ({ ...item }))
+        : [],
       eventsCursor: session?.agentEvents?.at(-1)?.sequence ?? events?.at(-1)?.sequence ?? lastEventSequence,
     };
   }

package/src/runtime/store.test.js

@@ -412,6 +412,31 @@ test('runtime state exposes queue as blocked jobs and pending plan steps', () =>
   store.close();
 });
 
+test('runtime store persists and replays control queue events without mixing MCP queue', () => {
+  const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-runtime-'));
+  const store = openRuntimeStore({ stateDir });
+  store.persistEvent(createAgentEvent('control_enqueued', {
+    origin: 'runtime',
+    workspace: 'docs',
+    payload: { id: 'control-docs', workspace: 'docs', input: 'later' },
+  }));
+  store.persistEvent(createAgentEvent('control_enqueued', {
+    origin: 'runtime',
+    workspace: 'juno',
+    payload: { id: 'control-juno', workspace: 'juno', input: 'other' },
+  }));
+  store.close();
+
+  const reopened = openRuntimeStore({ stateDir });
+  const session = { activities: {}, headlessPlan: null };
+  reopened.hydrateSession(session, { workspace: 'docs' });
+  const state = reopened.getState(session, { workspace: 'docs' });
+  assert.deepEqual(state.controlQueue.map((item) => item.id), ['control-docs']);
+  assert.deepEqual(state.queue, []);
+  assert.deepEqual(session.controlQueue.map((item) => item.id), ['control-docs']);
+  reopened.close();
+});
+
 test('runtime store identifies recoverable workspaces and interrupts stale runs', () => {
   const stateDir = mkdtempSync(join(tmpdir(), 'wiki-manager-runtime-'));
   const store = openRuntimeStore({ stateDir });