@dotdrelle/wiki-manager 0.11.0 → 0.11.6

package/src/runtime/runner.test.js

@@ -3,6 +3,41 @@ import test from 'node:test';
 import { createAgentEvent, dispatchAgentEvent } from '../core/agentEvents.js';
 import { finishRuntimeRun, replanRuntimeRun, runRuntimeAgenticWorkflow, runRuntimeParallelPlan } from './runner.js';
 
+test('runRuntimeAgenticWorkflow completes conversational turns without evaluation or replan', async () => {
+  const events = [];
+  const session = {
+    activities: {},
+    headlessPlan: null,
+    llm: {
+      async completeWithTools() {
+        assert.fail('conversation-only turn must not call evaluator or replanner');
+      },
+    },
+    _onAgentEvent: (event) => events.push(event),
+  };
+  const agent = {
+    async invoke() {
+      return { response: 'Salut.' };
+    },
+  };
+
+  const started = Date.now();
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'salut', {
+    runId: 'run-chat',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    maxReplans: 1,
+  });
+
+  assert.equal(result.ok, true);
+  assert.ok(Date.now() - started < 5000);
+  assert.equal(session.headlessPlan, null);
+  assert.equal(Object.keys(session.activities).length, 0);
+  assert.ok(events.some((event) => event.type === 'run_done'));
+  assert.equal(events.some((event) => event.type === 'run_evaluated'), false);
+  assert.equal(events.some((event) => event.type === 'run_replanned'), false);
+});
+
 test('finishRuntimeRun emits evaluation before run_done', async () => {
   const events = [];
   const session = {
@@ -33,6 +68,47 @@ test('finishRuntimeRun emits evaluation before run_done', async () => {
   assert.equal(session.agentProjection.status, 'done');
 });
 
+test('runRuntimeAgenticWorkflow clarifies vague evaluations without replan', async () => {
+  const events = [];
+  const session = {
+    activities: {},
+    headlessPlan: [{ step: 1, id: 'task', description: 'Task', status: 'done' }],
+    llm: {
+      async completeWithTools({ system }) {
+        assert.match(system, /strict evaluator/);
+        return { content: '{"ok":false,"reason":"demande vague / objectif indefini","suggestedAction":"clarifier l objectif"}' };
+      },
+    },
+    _onAgentEvent: (event) => events.push(event),
+  };
+  const agent = {
+    async invoke({ session: turnSession }) {
+      if (turnSession.headlessPlan === null) {
+        dispatchAgentEvent(turnSession, createAgentEvent('plan_set', {
+          origin: 'tool',
+          payload: { steps: [{ step: 1, id: 'task', description: 'Task', status: 'done' }] },
+        }));
+      }
+      return { response: 'Terminé.' };
+    },
+  };
+
+  const result = await runRuntimeAgenticWorkflow(agent, session, 'fais le truc', {
+    runId: 'run-vague',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    maxReplans: 1,
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(result.clarified, true);
+  assert.ok(session.agentProjection.conversation.at(-1).content.includes('clarifier'));
+  assert.ok(events.some((event) => event.type === 'run_evaluated'));
+  assert.equal(events.some((event) => event.type === 'run_replanned'), false);
+  assert.equal(events.some((event) => event.type === 'tool_call_started'), false);
+  assert.equal(session.agentProjection.status, 'done');
+});
+
 test('finishRuntimeRun turns negative evaluation into run_error', async () => {
   const events = [];
   const session = {
@@ -62,7 +138,7 @@ test('finishRuntimeRun turns negative evaluation into run_error', async () => {
 test('finishRuntimeRun falls back open when evaluator response is invalid', async () => {
   const session = {
     activities: {},
-    headlessPlan: null,
+    headlessPlan: [{ step: 1, description: 'Do work', status: 'done' }],
     agentProjection: { conversation: [] },
     llm: {
       async completeWithTools() {
@@ -126,13 +202,20 @@ test('runRuntimeAgenticWorkflow replans after negative evaluation', async () =>
   const agent = {
     async invoke({ session: turnSession }) {
       turns += 1;
+      if (turnSession.headlessPlan === null) {
+        dispatchAgentEvent(turnSession, createAgentEvent('plan_set', {
+          origin: 'tool',
+          payload: { steps: [{ step: 1, id: 'initial', description: 'Initial work', status: 'done' }] },
+        }));
+        return { response: 'Initial done.' };
+      }
       if (turnSession.headlessPlan?.[0]?.status === 'pending') {
         dispatchAgentEvent(turnSession, createAgentEvent('plan_step_updated', {
           origin: 'tool',
           payload: { step: 1, status: 'done' },
         }));
       }
-      return { response: turns === 1 ? 'Initial done.' : 'Export done.' };
+      return { response: 'Export done.' };
     },
   };
 
@@ -175,6 +258,27 @@ test('replanRuntimeRun preserves completed outputs when replacing remaining work
   assert.deepEqual(session.headlessPlan[1].dependsOn, ['export']);
 });
 
+test('replanRuntimeRun requires runtime approval for mutating replanned work', async () => {
+  const session = {
+    activities: {},
+    headlessPlan: [{ step: 1, id: 'build', description: 'Build', status: 'failed' }],
+    llm: {
+      async completeWithTools() {
+        return { content: '{"steps":["Run production build"]}' };
+      },
+    },
+  };
+
+  const result = await replanRuntimeRun(session, 'Build deliverable', {
+    kind: 'evaluation',
+    reason: 'Build missing.',
+  }, { runId: 'run-replan-approval', replansLeft: 1 });
+
+  assert.equal(result.ok, true);
+  assert.equal(session._runApprovalRequired, true);
+  assert.equal(session._runApprovalResolved, false);
+});
+
 test('runRuntimeAgenticWorkflow replans after terminal activity error', async () => {
   const originalFetch = globalThis.fetch;
   let pollAttempts = 0;
@@ -276,7 +380,13 @@ test('runRuntimeAgenticWorkflow stops after replan budget is exhausted', async (
     },
   };
   const agent = {
-    async invoke() {
+    async invoke({ session: turnSession }) {
+      if (turnSession.headlessPlan === null) {
+        dispatchAgentEvent(turnSession, createAgentEvent('plan_set', {
+          origin: 'tool',
+          payload: { steps: [{ step: 1, id: 'task', description: 'Task', status: 'done' }] },
+        }));
+      }
       return { response: 'Done.' };
     },
   };
@@ -337,6 +447,232 @@ test('runRuntimeParallelPlan executes ready tasks concurrently in one parent run
   assert.ok(session.agentEvents.some((event) => event.taskId === 'b'));
 });
 
+test('runRuntimeParallelPlan schedules a plan patch applied during an active parallel run', async () => {
+  const started = [];
+  const release = {};
+  const session = {
+    activities: {},
+    headlessPlan: [
+      { step: 1, id: 'a', description: 'Task A', status: 'pending', dependsOn: [] },
+      { step: 2, id: 'b', description: 'Task B', status: 'pending', dependsOn: [] },
+    ],
+  };
+  const agent = {
+    async invoke({ input }) {
+      const id = input.match(/Task id: ([^\n]+)/)?.[1];
+      started.push(id);
+      if (id === 'a' || id === 'b') {
+        await new Promise((resolve) => { release[id] = resolve; });
+      }
+      return { response: `done ${id}` };
+    },
+  };
+
+  const running = runRuntimeParallelPlan(agent, session, 'Do patched work', {
+    runId: 'run-patch-active',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    concurrency: 2,
+  });
+  await waitFor(() => started.includes('a') && started.includes('b'));
+  const patch = {
+    targetRunId: 'run-patch-active',
+    basePlanRevision: session.agentProjection.planRevision,
+    operations: [
+      {
+        op: 'add_task',
+        task: {
+          id: 'c',
+          description: 'Task C added during run',
+          status: 'pending',
+          dependsOn: ['a'],
+          executor: null,
+          outputRefs: [],
+        },
+      },
+    ],
+  };
+  dispatchAgentEvent(session, createAgentEvent('plan_patch_proposed', {
+    origin: 'runtime',
+    runId: 'run-patch-active',
+    payload: { id: 'patch-active', patch },
+  }));
+  dispatchAgentEvent(session, createAgentEvent('plan_patch_approved', {
+    origin: 'runtime',
+    runId: 'run-patch-active',
+    payload: { patchId: 'patch-active' },
+  }));
+  dispatchAgentEvent(session, createAgentEvent('plan_patch_applied', {
+    origin: 'runtime',
+    runId: 'run-patch-active',
+    payload: { patchId: 'patch-active', patch },
+  }));
+
+  assert.deepEqual(session.headlessPlan.map((step) => step.id), ['a', 'b', 'c']);
+  release.a();
+  await waitFor(() => started.includes('c'));
+  release.b();
+
+  const result = await running;
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(started, ['a', 'b', 'c']);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done', 'done']);
+  assert.equal(session.headlessPlan.find((step) => step.id === 'c').dependsOn[0], 'a');
+});
+
+test('runRuntimeParallelPlan rejects a stale patch during an active parallel run without silently applying it', async () => {
+  const release = {};
+  const session = {
+    activities: {},
+    headlessPlan: [
+      { step: 1, id: 'a', description: 'Task A', status: 'pending', dependsOn: [] },
+      { step: 2, id: 'b', description: 'Task B', status: 'pending', dependsOn: [] },
+    ],
+  };
+  const agent = {
+    async invoke({ input }) {
+      const id = input.match(/Task id: ([^\n]+)/)?.[1];
+      await new Promise((resolve) => { release[id] = resolve; });
+      return { response: `done ${id}` };
+    },
+  };
+
+  const running = runRuntimeParallelPlan(agent, session, 'Do stale patch work', {
+    runId: 'run-stale-patch',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    concurrency: 2,
+  });
+  await waitFor(() => release.a && release.b);
+  const patch = {
+    targetRunId: 'run-stale-patch',
+    basePlanRevision: session.agentProjection.planRevision + 99,
+    operations: [
+      { op: 'add_task', task: { id: 'c', description: 'Should not apply', dependsOn: ['a'] } },
+    ],
+  };
+  dispatchAgentEvent(session, createAgentEvent('plan_patch_proposed', {
+    origin: 'runtime',
+    runId: 'run-stale-patch',
+    payload: { id: 'patch-stale', patch },
+  }));
+  dispatchAgentEvent(session, createAgentEvent('plan_patch_applied', {
+    origin: 'runtime',
+    runId: 'run-stale-patch',
+    payload: { patchId: 'patch-stale', patch },
+  }));
+
+  assert.deepEqual(session.headlessPlan.map((step) => step.id), ['a', 'b']);
+  assert.equal(session.agentProjection.planPatches.find((item) => item.id === 'patch-stale').status, 'rejected');
+  assert.equal(session.agentProjection.planPatches.find((item) => item.id === 'patch-stale').rejectionReason, 'revision_mismatch');
+  release.a();
+  release.b();
+
+  const result = await running;
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done']);
+});
+
+test('runRuntimeParallelPlan aborts a running child task cancelled by plan patch without stopping siblings', async () => {
+  const started = [];
+  let bAborted = false;
+  const session = {
+    activities: {},
+    headlessPlan: [
+      { step: 1, id: 'a', description: 'Task A', status: 'pending', dependsOn: [] },
+      { step: 2, id: 'b', description: 'Task B', status: 'pending', dependsOn: [] },
+    ],
+  };
+  const agent = {
+    async invoke({ input, signal }) {
+      const id = input.match(/Task id: ([^\n]+)/)?.[1];
+      started.push(id);
+      if (id === 'b') {
+        await new Promise((resolve, reject) => {
+          signal.addEventListener('abort', () => {
+            bAborted = true;
+            const err = new Error('cancelled');
+            err.name = 'AbortError';
+            reject(err);
+          }, { once: true });
+        });
+      }
+      return { response: `done ${id}` };
+    },
+  };
+
+  const running = runRuntimeParallelPlan(agent, session, 'Cancel one child', {
+    runId: 'run-cancel-task',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    concurrency: 2,
+  });
+  await waitFor(() => started.includes('a') && started.includes('b'));
+  await waitFor(() => session.headlessPlan.find((step) => step.id === 'a')?.status === 'done');
+  const patch = {
+    targetRunId: 'run-cancel-task',
+    basePlanRevision: session.agentProjection.planRevision,
+    operations: [{ op: 'cancel_task', taskId: 'b' }],
+  };
+  dispatchAgentEvent(session, createAgentEvent('plan_patch_applied', {
+    origin: 'runtime',
+    runId: 'run-cancel-task',
+    payload: { patchId: 'patch-cancel-b', patch },
+  }));
+
+  const result = await running;
+
+  assert.equal(result.ok, true);
+  assert.equal(bAborted, true);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'cancelled']);
+  assert.equal(session.agentProjection.planPatches.find((item) => item.id === 'patch-cancel-b').status, 'applied');
+});
+
+test('runRuntimeParallelPlan never exceeds the configured concurrency with twice the limit ready', async () => {
+  let active = 0;
+  let maxActive = 0;
+  const release = {};
+  const session = {
+    activities: {},
+    headlessPlan: Array.from({ length: 6 }, (_, index) => ({
+      step: index + 1,
+      id: `task-${index + 1}`,
+      description: `Task ${index + 1}`,
+      status: 'pending',
+      dependsOn: [],
+    })),
+  };
+  const agent = {
+    async invoke({ input }) {
+      const id = input.match(/Task id: ([^\n]+)/)?.[1];
+      active += 1;
+      maxActive = Math.max(maxActive, active);
+      await new Promise((resolve) => { release[id] = resolve; });
+      active -= 1;
+      return { response: `done ${id}` };
+    },
+  };
+
+  const running = runRuntimeParallelPlan(agent, session, 'Respect limit', {
+    runId: 'run-limit',
+    timeoutMs: 1000,
+    maxTurns: 1,
+    concurrency: 3,
+  });
+  for (let batch = 0; batch < 2; batch += 1) {
+    await waitFor(() => Object.keys(release).length >= (batch + 1) * 3);
+    for (const id of Object.keys(release).slice(batch * 3, (batch + 1) * 3)) release[id]();
+  }
+
+  const result = await running;
+
+  assert.equal(result.ok, true);
+  assert.equal(maxActive, 3);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['done', 'done', 'done', 'done', 'done', 'done']);
+});
+
 test('runRuntimeParallelPlan serializes conflicting write locks', async () => {
   let active = 0;
   let maxActive = 0;
@@ -441,6 +777,52 @@ test('runRuntimeParallelPlan propagates parent cancellation to child tasks', asy
   assert.equal(session.headlessPlan[0].status, 'cancelled');
 });
 
+test('runRuntimeParallelPlan aborts every active child on parent cancellation and records terminal updates after running updates', async () => {
+  const controller = new AbortController();
+  const aborted = [];
+  const session = {
+    activities: {},
+    headlessPlan: [
+      { step: 1, id: 'a', description: 'Task A', status: 'pending', dependsOn: [] },
+      { step: 2, id: 'b', description: 'Task B', status: 'pending', dependsOn: [] },
+      { step: 3, id: 'c', description: 'Task C', status: 'pending', dependsOn: [] },
+    ],
+  };
+  const agent = {
+    async invoke({ input, signal }) {
+      const id = input.match(/Task id: ([^\n]+)/)?.[1];
+      await new Promise((resolve, reject) => {
+        signal.addEventListener('abort', () => {
+          aborted.push(id);
+          const err = new Error('cancelled');
+          err.name = 'AbortError';
+          reject(err);
+        }, { once: true });
+      });
+      return { response: `done ${id}` };
+    },
+  };
+
+  const running = runRuntimeParallelPlan(agent, session, 'Cancel all children', {
+    runId: 'run-cancel-all',
+    signal: controller.signal,
+    timeoutMs: 1000,
+    maxTurns: 1,
+    concurrency: 3,
+  });
+  await waitFor(() => session.headlessPlan.every((step) => step.status === 'running'));
+  controller.abort();
+
+  await assert.rejects(running, { name: 'AbortError' });
+  assert.deepEqual(aborted.sort(), ['a', 'b', 'c']);
+  assert.deepEqual(session.headlessPlan.map((step) => step.status), ['cancelled', 'cancelled', 'cancelled']);
+  const updates = session.agentEvents
+    .filter((event) => event.type === 'plan_step_updated')
+    .map((event) => `${event.taskId}:${event.payload.status}`);
+  assert.deepEqual(updates.slice(0, 3).sort(), ['a:running', 'b:running', 'c:running']);
+  assert.deepEqual(updates.slice(3).sort(), ['a:cancelled', 'b:cancelled', 'c:cancelled']);
+});
+
 test('runRuntimeAgenticWorkflow hands off to the parallel scheduler when turn 1 sets a multi-task ready plan', async () => {
   const session = {
     activities: {},

package/src/runtime/server.js

@@ -6,7 +6,7 @@ import { validateContractInDev } from '../contracts/schemas.js';
 import { runtimeTokenFromEnv } from './auth.js';
 
 export function startRuntimeServer({
-  host = '0.0.0.0',
+  host = '127.0.0.1',
   port = 7788,
   token = runtimeTokenFromEnv(),
   store,
@@ -18,6 +18,7 @@ export function startRuntimeServer({
   approve,
   configProfiles,
   useConfigProfile,
+  exitOnShutdown = process.env.WIKI_MANAGER_RUNTIME_CHILD === '1',
 } = {}) {
   const clients = new Set();
   const defaultContext = { workspace: null, session, running: false, currentAbortController: null, currentRunId: null };
@@ -31,6 +32,13 @@ export function startRuntimeServer({
     }
   }
 
+  function publishState(workspace = null, context = null) {
+    for (const client of clients) {
+      if (client.workspace && client.workspace !== workspace) continue;
+      client.response.write(`event: state\ndata: ${JSON.stringify(runtimeState(context, store, { workspace, session }))}\n\n`);
+    }
+  }
+
   const server = createServer(async (request, response) => {
     try {
       if (!isAuthorized(request, token)) {
@@ -223,6 +231,23 @@ export function startRuntimeServer({
         sendJson(response, 202, { cancelled: true, workspace: context.workspace ?? workspace ?? null });
         return;
       }
+      if (request.method === 'POST' && url.pathname === '/shutdown') {
+        const workspace = workspaceFromUrl(url);
+        const context = await resolveContext({ workspace });
+        if (context?.running && context.currentAbortController) {
+          context.currentAbortController.abort();
+          await cancel?.(context);
+        }
+        sendJson(response, 202, { shutdown: true });
+        setImmediate(() => {
+          for (const client of clients) client.response.end();
+          clients.clear();
+          server.close(() => {
+            if (exitOnShutdown) process.exit(0);
+          });
+        });
+        return;
+      }
       if (request.method === 'POST' && url.pathname === '/resume') {
         const workspace = workspaceFromUrl(url);
         const result = await resume?.({ workspace });
@@ -307,6 +332,7 @@ export function startRuntimeServer({
         context.currentAbortController = null;
         context.currentRunId = null;
         context.currentRunWorkspace = null;
+        publishState(runWorkspace, context);
         void startNextControlRequest(context);
       });
     return { accepted: true, runId, workspace: runWorkspace };
@@ -610,7 +636,7 @@ function classifyControlMessage(input, status, forcedIntent = null) {
   if (['observe', 'converse', 'mutate', 'enqueue'].includes(intent)) {
     return { kind: intent, confidence: 1, reason: 'explicit_intent' };
   }
-  if (/\b(o[uù] en est|status|statut|progress|progression|build|run|job|queue|file|logs?|explique|explain|inspect|show|montre|quoi de neuf)\b/i.test(lower)) {
+  if (/\b(o[uù] en es[t-]|status|statut|progress|progression|build|run|job|queue|file|logs?|explique|explain|inspect|show|montre|quoi de neuf)\b/i.test(lower)) {
     return { kind: 'observe', confidence: 0.86, reason: 'status_or_explanation_request' };
   }
   if (status.running && /\b(ajoute|add|change|modifie|modify|remplace|replace|retire|remove|skip|ignore|apr[eè]s|before|after|chaque|each|plan|step|t[aâ]che)\b/i.test(lower)) {

package/src/runtime/server.test.js

@@ -46,6 +46,44 @@ test('runtime server checks bearer and x-runtime-token credentials', async (t) =
   }
 });
 
+test('runtime server shutdown endpoint closes the listener', async (t) => {
+  let handle;
+  try {
+    handle = await startRuntimeServer({
+      host: '127.0.0.1',
+      port: 0,
+      token: 'runtime-secret',
+      exitOnShutdown: false,
+      store: {
+        dbPath: ':memory:',
+        getState: () => ({ status: 'idle' }),
+        listEvents: () => [],
+      },
+      session: {},
+      run: async () => {},
+    });
+  } catch (err) {
+    if (err?.code === 'EPERM') {
+      t.skip('network listen is not permitted in this sandbox');
+      return;
+    }
+    throw err;
+  }
+
+  const url = `http://127.0.0.1:${handle.port}`;
+  const response = await fetch(`${url}/shutdown`, {
+    method: 'POST',
+    headers: { authorization: 'Bearer runtime-secret' },
+  });
+  assert.equal(response.status, 202);
+  assert.equal((await response.json()).shutdown, true);
+
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  await assert.rejects(fetch(`${url}/health`, {
+    headers: { authorization: 'Bearer runtime-secret' },
+  }));
+});
+
 test('runtime server accepts only one active run', async (t) => {
   let releaseRun;
   let runCount = 0;

package/src/runtime/store.js

@@ -1,4 +1,4 @@
-import { mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
 import { applyAgentProjectionToSession, dispatchAgentEvent, reduceAgentEvents } from '../core/agentEvents.js';
@@ -9,6 +9,9 @@ import { projectWorkflow } from '../core/workflow.js';
 export { defaultRuntimeStateDir };
 
 const NON_PERSISTED_EVENT_TYPES = new Set(['runtime_log']);
+export const RUNTIME_STORE_SCHEMA_VERSION = 1;
+const RUNTIME_RETENTION_DAYS = 30;
+const TERMINAL_RUN_STATUSES = ['done', 'error', 'cancelled', 'interrupted'];
 
 const RUN_STATUS_BY_EVENT = {
   run_done: 'done',
@@ -21,13 +24,20 @@ const RUN_STATUS_BY_EVENT = {
 const RECOVERABLE_RUN_STATUSES = ['running', 'waiting', 'pending_approval'];
 export const RECOVERABLE_QUEUE_STATUSES = ['waiting', 'queued', 'starting', 'running', 'blocked', 'pending_approval'];
 
-export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName = 'runtime.db' } = {}) {
+export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName = 'runtime.db', metaPath = null } = {}) {
   const resolvedStateDir = resolve(stateDir);
   mkdirSync(resolvedStateDir, { recursive: true });
   const dbPath = join(resolvedStateDir, fileName);
   const db = new DatabaseSync(dbPath);
   db.exec('PRAGMA journal_mode = WAL');
   db.exec('PRAGMA foreign_keys = ON');
+  try {
+    ensureKnownStoreVersion(db, dbPath);
+    ensureRuntimeMeta(metaPath ?? defaultRuntimeMetaPath(resolvedStateDir));
+  } catch (error) {
+    db.close();
+    throw error;
+  }
   db.exec(`
     CREATE TABLE IF NOT EXISTS events (
       sequence INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -76,6 +86,8 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
   backfillEventSequence(db);
   db.exec('CREATE INDEX IF NOT EXISTS idx_events_workspace ON events(workspace)');
   db.exec('CREATE INDEX IF NOT EXISTS idx_events_sequence ON events(sequence)');
+  db.exec(`PRAGMA user_version = ${RUNTIME_STORE_SCHEMA_VERSION}`);
+  purgeOldTerminalRuns(db);
 
   let lastEventId = null;
   let lastEventSequence = null;
@@ -423,6 +435,64 @@ export function openRuntimeStore({ stateDir = defaultRuntimeStateDir(), fileName
   };
 }
 
+function defaultRuntimeMetaPath(stateDir) {
+  return join(dirname(stateDir), '.wiki', 'meta.json');
+}
+
+function ensureKnownStoreVersion(db, dbPath) {
+  const row = db.prepare('PRAGMA user_version').get();
+  const version = Number(row?.user_version ?? 0);
+  if (version > RUNTIME_STORE_SCHEMA_VERSION) {
+    throw new Error(`Unsupported runtime store schema version ${version} in ${dbPath}; this manager supports version ${RUNTIME_STORE_SCHEMA_VERSION}. Upgrade llm-wiki-manager before opening this runtime store.`);
+  }
+}
+
+function ensureRuntimeMeta(metaPath) {
+  mkdirSync(dirname(metaPath), { recursive: true });
+  if (!existsSync(metaPath)) {
+    writeFileSync(metaPath, `${JSON.stringify({ schemaVersion: RUNTIME_STORE_SCHEMA_VERSION }, null, 2)}\n`, 'utf8');
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(metaPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Invalid runtime metadata file ${metaPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const version = Number(parsed?.schemaVersion ?? 0);
+  if (version > RUNTIME_STORE_SCHEMA_VERSION) {
+    throw new Error(`Unsupported runtime metadata schemaVersion ${version} in ${metaPath}; this manager supports version ${RUNTIME_STORE_SCHEMA_VERSION}. Upgrade llm-wiki-manager before opening this runtime state.`);
+  }
+  if (!version) {
+    writeFileSync(metaPath, `${JSON.stringify({ ...parsed, schemaVersion: RUNTIME_STORE_SCHEMA_VERSION }, null, 2)}\n`, 'utf8');
+  }
+}
+
+function purgeOldTerminalRuns(db, now = new Date()) {
+  const cutoff = new Date(now.getTime() - RUNTIME_RETENTION_DAYS * 24 * 60 * 60 * 1000).toISOString();
+  const placeholders = TERMINAL_RUN_STATUSES.map(() => '?').join(', ');
+  const oldRuns = db
+    .prepare(`SELECT id FROM runs WHERE status IN (${placeholders}) AND updated_at < ?`)
+    .all(...TERMINAL_RUN_STATUSES, cutoff)
+    .map((row) => row.id);
+  if (oldRuns.length === 0) return 0;
+  db.exec('BEGIN');
+  try {
+    const deleteEvents = db.prepare('DELETE FROM events WHERE run_id = ? OR json_extract(payload, \'$.runId\') = ?');
+    const deleteRun = db.prepare('DELETE FROM runs WHERE id = ?');
+    for (const runId of oldRuns) {
+      deleteEvents.run(runId, runId);
+      deleteRun.run(runId);
+    }
+    db.exec('COMMIT');
+  } catch (error) {
+    db.exec('ROLLBACK');
+    throw error;
+  }
+  db.exec('VACUUM');
+  return oldRuns.length;
+}
+
 function rowToEvent(row) {
   return {
     sequence: row.sequence ?? null,