ultra-builder-pro-cli 0.6.0 → 0.7.0

package/mcp-server/lib/runtime-state.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+const { randomUUID } = require('node:crypto');
+
+const ops = require('./state-ops.cjs');
+const defaultProjector = require('./projector.cjs');
+
+class RuntimeStateError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'RuntimeStateError';
+    this.code = code;
+  }
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function parseJson(value) {
+  if (value == null) return null;
+  try { return JSON.parse(value); }
+  catch (error) {
+    throw new RuntimeStateError('STATE_CORRUPT', `invalid runtime JSON: ${error.message}`);
+  }
+}
+
+function rowToIncident(row) {
+  if (!row) return null;
+  return {
+    ...row,
+    retryable: Boolean(row.retryable),
+    evidence: parseJson(row.evidence_json),
+  };
+}
+
+function recordIncident(db, input) {
+  if (!input || !input.code || !input.message) {
+    throw new RuntimeStateError('VALIDATION_ERROR', 'incident code and message required');
+  }
+  return ops.tx(db, () => {
+    const existing = db.prepare(
+      `SELECT * FROM incidents
+       WHERE status = 'open' AND code = ?
+         AND change_id IS ? AND task_id IS ? AND session_id IS ?
+         AND source_kind IS ? AND source_id IS ?
+       ORDER BY first_seen_at ASC LIMIT 1`,
+    ).get(
+      input.code, input.change_id ?? null, input.task_id ?? null, input.session_id ?? null,
+      input.source_kind ?? null, input.source_id ?? null,
+    );
+    const ts = nowIso();
+    if (existing) {
+      db.prepare(
+        `UPDATE incidents SET message = ?, severity = ?, retryable = ?, evidence_json = ?,
+         occurrence_count = occurrence_count + 1, last_seen_at = ? WHERE id = ?`,
+      ).run(
+        input.message, input.severity || 'error', input.retryable ? 1 : 0,
+        input.evidence === undefined ? existing.evidence_json : JSON.stringify(input.evidence),
+        ts, existing.id,
+      );
+      return rowToIncident(db.prepare('SELECT * FROM incidents WHERE id = ?').get(existing.id));
+    }
+    const id = `inc-${randomUUID().slice(0, 12)}`;
+    db.prepare(
+      `INSERT INTO incidents
+       (id, code, severity, retryable, message, change_id, task_id, session_id,
+        source_kind, source_id, evidence_json, first_seen_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      id, input.code, input.severity || 'error', input.retryable ? 1 : 0, input.message,
+      input.change_id ?? null, input.task_id ?? null, input.session_id ?? null,
+      input.source_kind ?? null, input.source_id ?? null,
+      input.evidence === undefined ? null : JSON.stringify(input.evidence), ts, ts,
+    );
+    return rowToIncident(db.prepare('SELECT * FROM incidents WHERE id = ?').get(id));
+  });
+}
+
+function resolveIncident(db, id, resolution) {
+  const result = db.prepare(
+    `UPDATE incidents SET status = 'resolved', resolved_at = ?, resolution = ?
+     WHERE id = ? AND status = 'open'`,
+  ).run(nowIso(), resolution || 'resolved', id);
+  return { resolved: result.changes > 0 };
+}
+
+const LIST_INCIDENTS_SQL = "SELECT * FROM incidents WHERE (@status IS NULL OR status = @status) AND (@change_id IS NULL OR change_id = @change_id) AND (@task_id IS NULL OR task_id = @task_id) ORDER BY last_seen_at DESC LIMIT @maxn";
+
+function listIncidents(db, { status = null, change_id = null, task_id = null, limit = 100 } = {}) {
+  return db.prepare(LIST_INCIDENTS_SQL).all({
+    status, change_id, task_id, maxn: Math.min(Math.max(limit, 1), 500),
+  }).map(rowToIncident);
+}
+
+function enqueueProjection(db, { tool_name, event_cursor, max_attempts = 3 } = {}) {
+  if (!tool_name) throw new RuntimeStateError('VALIDATION_ERROR', 'projection tool_name required');
+  const cursor = Number.isInteger(event_cursor)
+    ? event_cursor
+    : Number(db.prepare('SELECT COALESCE(MAX(id), 0) AS id FROM events').get().id);
+  const result = db.prepare(
+    `INSERT INTO projection_jobs (tool_name, event_cursor, max_attempts)
+     VALUES (?, ?, ?)`,
+  ).run(tool_name, cursor, max_attempts);
+  return readProjectionJob(db, Number(result.lastInsertRowid));
+}
+
+function readProjectionJob(db, id) {
+  return db.prepare('SELECT * FROM projection_jobs WHERE id = ?').get(id) || null;
+}
+
+const LIST_PROJECTION_JOBS_SQL = "SELECT * FROM projection_jobs WHERE (@status IS NULL OR status = @status) ORDER BY id ASC LIMIT @maxn";
+
+function listProjectionJobs(db, { status = null, limit = 100 } = {}) {
+  return db.prepare(LIST_PROJECTION_JOBS_SQL).all({
+    status, maxn: Math.min(Math.max(limit, 1), 500),
+  });
+}
+
+function processProjectionJobs(db, {
+  rootDir = '.', project = defaultProjector.projectAll, limit = 10,
+} = {}) {
+  const pending = listProjectionJobs(db, { status: 'pending', limit });
+  const jobs = [];
+  for (const row of pending) {
+    const claimed = db.prepare(
+      "UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ? AND status = 'pending'",
+    ).run(nowIso(), row.id);
+    if (claimed.changes === 0) continue;
+    const active = readProjectionJob(db, row.id);
+    try {
+      const projection = project(db, { rootDir });
+      const ts = nowIso();
+      db.prepare(
+        `UPDATE projection_jobs SET status = 'completed', attempts = attempts + 1,
+         last_error = NULL, updated_at = ?, completed_at = ? WHERE id = ?`,
+      ).run(ts, ts, row.id);
+      const related = db.prepare(
+        "SELECT id FROM incidents WHERE status = 'open' AND source_kind = 'projection_job' AND source_id = ?",
+      ).all(String(row.id));
+      for (const incident of related) resolveIncident(db, incident.id, 'projection completed on retry');
+      jobs.push({ id: row.id, status: 'completed', projection });
+    } catch (error) {
+      const attempts = active.attempts + 1;
+      const status = attempts >= active.max_attempts ? 'failed' : 'pending';
+      db.prepare(
+        `UPDATE projection_jobs SET status = ?, attempts = ?, last_error = ?, updated_at = ?
+         WHERE id = ?`,
+      ).run(status, attempts, error.message, nowIso(), row.id);
+      const incident = recordIncident(db, {
+        code: 'PROJECTION_FAILED', severity: 'error', retryable: true,
+        message: error.message, source_kind: 'projection_job', source_id: String(row.id),
+        evidence: { tool_name: row.tool_name, event_cursor: row.event_cursor, attempts },
+      });
+      jobs.push({ id: row.id, status: status === 'pending' ? 'retrying' : 'failed', error: error.message, incident_id: incident.id });
+    }
+  }
+  return { processed: jobs.length, jobs };
+}
+
+function requeueInterruptedProjections(db, { staleBefore } = {}) {
+  const cutoff = staleBefore || new Date(Date.now() - 5 * 60 * 1000).toISOString();
+  if (typeof cutoff !== 'string' || Number.isNaN(Date.parse(cutoff))) {
+    throw new RuntimeStateError('VALIDATION_ERROR', 'staleBefore must be an ISO date-time');
+  }
+  const result = db.prepare(
+    `UPDATE projection_jobs
+     SET status = 'pending', last_error = 'interrupted projection requeued by doctor',
+         updated_at = ?, completed_at = NULL
+     WHERE status = 'running' AND updated_at < ?`,
+  ).run(nowIso(), cutoff);
+  return { requeued: result.changes, stale_before: cutoff };
+}
+
+function requeueFailedProjections(db) {
+  const result = db.prepare(
+    "UPDATE projection_jobs SET status = 'pending', attempts = 0, updated_at = ? WHERE status = 'failed'",
+  ).run(nowIso());
+  return { requeued: result.changes };
+}
+
+function ensureProjectionJob(db, { tool_name = 'runtime.reconcile' } = {}) {
+  const eventCursor = Number(db.prepare('SELECT COALESCE(MAX(id), 0) AS id FROM events').get().id);
+  const projectedCursor = Number(db.prepare(
+    "SELECT COALESCE(MAX(event_cursor), 0) AS id FROM projection_jobs WHERE status IN ('pending', 'running', 'completed')",
+  ).get().id);
+  if (eventCursor <= projectedCursor) return { enqueued: false, event_cursor: eventCursor };
+  return { enqueued: true, job: enqueueProjection(db, { tool_name, event_cursor: eventCursor }) };
+}
+
+function readConsumerCursor(db, name) {
+  const row = db.prepare('SELECT cursor FROM event_consumers WHERE name = ?').get(name);
+  return row ? Number(row.cursor) : 0;
+}
+
+function writeConsumerCursor(db, name, cursor) {
+  if (!name || !Number.isInteger(cursor) || cursor < 0) {
+    throw new RuntimeStateError('VALIDATION_ERROR', 'consumer name and non-negative cursor required');
+  }
+  db.prepare(
+    `INSERT INTO event_consumers (name, cursor, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT(name) DO UPDATE SET
+       cursor = MAX(event_consumers.cursor, excluded.cursor), updated_at = excluded.updated_at`,
+  ).run(name, cursor, nowIso());
+  return { name, cursor: readConsumerCursor(db, name) };
+}
+
+module.exports = {
+  RuntimeStateError,
+  recordIncident,
+  resolveIncident,
+  listIncidents,
+  enqueueProjection,
+  readProjectionJob,
+  listProjectionJobs,
+  processProjectionJobs,
+  requeueInterruptedProjections,
+  requeueFailedProjections,
+  ensureProjectionJob,
+  readConsumerCursor,
+  writeConsumerCursor,
+};

package/mcp-server/lib/runtime-state.test.cjs

@@ -0,0 +1,92 @@
+'use strict';
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { initStateDb, closeStateDb } = require('./state-db.cjs');
+const runtime = require('./runtime-state.cjs');
+
+function fixture() {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-runtime-state-'));
+  const { db } = initStateDb(path.join(rootDir, '.ultra', 'state.db'));
+  return { rootDir, db };
+}
+
+function cleanup({ rootDir, db }) {
+  closeStateDb(db);
+  fs.rmSync(rootDir, { recursive: true, force: true });
+}
+
+test('projection jobs complete and retain their event cursor', () => {
+  const fx = fixture();
+  try {
+    const job = runtime.enqueueProjection(fx.db, { tool_name: 'task.create', event_cursor: 7 });
+    const result = runtime.processProjectionJobs(fx.db, {
+      rootDir: fx.rootDir,
+      project: () => ({ tasks_json: { count: 0 }, contexts: [] }),
+    });
+    assert.equal(result.processed, 1);
+    assert.equal(result.jobs[0].status, 'completed');
+    const stored = runtime.readProjectionJob(fx.db, job.id);
+    assert.equal(stored.status, 'completed');
+    assert.equal(stored.event_cursor, 7);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('projection failures are explicit, retryable incidents rather than swallowed warnings', () => {
+  const fx = fixture();
+  try {
+    runtime.enqueueProjection(fx.db, { tool_name: 'task.update', event_cursor: 4, max_attempts: 1 });
+    // Test Double rationale: deterministic projector failure is required; filesystem permission failures vary by host.
+    const result = runtime.processProjectionJobs(fx.db, {
+      rootDir: fx.rootDir,
+      project: () => { throw new Error('projection disk unavailable'); },
+    });
+    assert.equal(result.jobs[0].status, 'failed');
+    assert.match(result.jobs[0].error, /projection disk unavailable/);
+    const incidents = runtime.listIncidents(fx.db, { status: 'open' });
+    assert.equal(incidents.length, 1);
+    assert.equal(incidents[0].code, 'PROJECTION_FAILED');
+    assert.equal(incidents[0].retryable, true);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('event consumer cursors are durable and monotonic', () => {
+  const fx = fixture();
+  try {
+    assert.equal(runtime.readConsumerCursor(fx.db, 'spec-staleness'), 0);
+    runtime.writeConsumerCursor(fx.db, 'spec-staleness', 12);
+    runtime.writeConsumerCursor(fx.db, 'spec-staleness', 9);
+    assert.equal(runtime.readConsumerCursor(fx.db, 'spec-staleness'), 12);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('interrupted running projections are requeued only after the stale cutoff', () => {
+  const fx = fixture();
+  try {
+    const stale = runtime.enqueueProjection(fx.db, { tool_name: 'task.update', event_cursor: 3 });
+    const fresh = runtime.enqueueProjection(fx.db, { tool_name: 'task.create', event_cursor: 4 });
+    fx.db.prepare("UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ?")
+      .run('2000-01-01T00:00:00.000Z', stale.id);
+    fx.db.prepare("UPDATE projection_jobs SET status = 'running', updated_at = ? WHERE id = ?")
+      .run('2999-01-01T00:00:00.000Z', fresh.id);
+
+    const result = runtime.requeueInterruptedProjections(fx.db, {
+      staleBefore: '2026-01-01T00:00:00.000Z',
+    });
+    assert.equal(result.requeued, 1);
+    assert.equal(runtime.readProjectionJob(fx.db, stale.id).status, 'pending');
+    assert.equal(runtime.readProjectionJob(fx.db, fresh.id).status, 'running');
+  } finally {
+    cleanup(fx);
+  }
+});

package/mcp-server/lib/state-db.cjs

@@ -9,7 +9,7 @@ const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..', '..');
 const SCHEMA_FILE = path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql');
-const EXPECTED_VERSION = '8A.2';
+const EXPECTED_VERSION = '9.0';
 
 const REQUIRED_TABLES = Object.freeze([
   'tasks',
@@ -20,6 +20,13 @@ const REQUIRED_TABLES = Object.freeze([
   'telemetry',
   'specs_refs',
   'circuit_breaker',
+  'changes',
+  'artifacts',
+  'context_snapshots',
+  'trace_links',
+  'incidents',
+  'projection_jobs',
+  'event_consumers',
 ]);
 
 function readSchemaSql() {
@@ -64,18 +71,33 @@ function columnNames(db, table) {
   return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((row) => row.name));
 }
 
-function applyCompatibleUpgrades(db) {
+function applyCompatibleColumns(db) {
+  const tables = new Set(tableNames(db));
+  if (!tables.has('tasks')) return;
   const taskColumns = columnNames(db, 'tasks');
   if (!taskColumns.has('estimated_days')) {
-    db.transaction(() => {
-      db.exec('ALTER TABLE tasks ADD COLUMN estimated_days REAL CHECK (estimated_days IS NULL OR estimated_days > 0)');
-      db.prepare(
-        'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
-      ).run(EXPECTED_VERSION, 'Phase 8A.2 — tasks.estimated_days preserved across MCP and v4.4 migration');
-    })();
+    db.exec('ALTER TABLE tasks ADD COLUMN estimated_days REAL CHECK (estimated_days IS NULL OR estimated_days > 0)');
+  }
+  if (!taskColumns.has('change_id')) {
+    db.exec('ALTER TABLE tasks ADD COLUMN change_id TEXT REFERENCES changes(id) ON DELETE SET NULL');
+  }
+  if (tables.has('events')) {
+    const eventColumns = columnNames(db, 'events');
+    if (!eventColumns.has('change_id')) db.exec('ALTER TABLE events ADD COLUMN change_id TEXT');
   }
 }
 
+function applyCompatibleUpgrades(db) {
+  db.transaction(() => {
+    applyCompatibleColumns(db);
+    db.exec('CREATE INDEX IF NOT EXISTS tasks_change ON tasks(change_id) WHERE change_id IS NOT NULL');
+    db.exec('CREATE INDEX IF NOT EXISTS events_change ON events(change_id, id)');
+    db.prepare(
+      'INSERT OR IGNORE INTO schema_version (version, description) VALUES (?, ?)',
+    ).run(EXPECTED_VERSION, 'Continuous change units and recoverable runtime state');
+  })();
+}
+
 function ensureSchemaVersion(db) {
   // schema_version is an audit trail — multiple rows across phase upgrades.
   // Guard by checking whether the expected version row exists rather than
@@ -94,6 +116,7 @@ function ensureSchemaVersion(db) {
 function initStateDb(dbPath) {
   const db = openStateDb(dbPath);
   const existing = new Set(tableNames(db));
+  applyCompatibleColumns(db);
   const missing = REQUIRED_TABLES.filter((t) => !existing.has(t));
   if (missing.length > 0) {
     applySchema(db);

package/mcp-server/lib/state-ops.cjs

@@ -27,6 +27,7 @@ const TASK_FIELDS = Object.freeze([
   'id', 'title', 'type', 'priority', 'complexity', 'estimated_days', 'status',
   'deps', 'files_modified', 'session_id', 'stale', 'complexity_hint',
   'tag', 'trace_to', 'context_file', 'completion_commit', 'parent_id',
+  'change_id',
   'created_at', 'updated_at',
 ]);
 
@@ -34,6 +35,7 @@ const PATCHABLE_FIELDS = Object.freeze([
   'priority', 'complexity', 'estimated_days', 'deps', 'files_modified',
   'session_id', 'stale', 'complexity_hint', 'tag', 'trace_to',
   'context_file', 'completion_commit',
+  'change_id',
 ]);
 
 const SESSION_PATCHABLE = Object.freeze([
@@ -153,10 +155,14 @@ function createTask(db, input) {
     context_file: input.context_file ?? null,
     completion_commit: null,
     parent_id: input.parent_id ?? null,
+    change_id: input.change_id ?? null,
     created_at: ts,
     updated_at: ts,
   };
   return tx(db, () => {
+    if (row.change_id && !db.prepare('SELECT id FROM changes WHERE id = ?').get(row.change_id)) {
+      throw new StateOpsError('CHANGE_NOT_FOUND', `change ${row.change_id} does not exist`);
+    }
     try {
       db.prepare(
         `INSERT INTO tasks (${TASK_FIELDS.join(', ')})
@@ -171,6 +177,7 @@ function createTask(db, input) {
     appendEventInTx(db, {
       type: 'task_created',
       task_id: row.id,
+      change_id: row.change_id,
       payload: { priority: row.priority, type: row.type },
     });
     return readTask(db, row.id);
@@ -193,6 +200,10 @@ function patchTask(db, id, patch = {}) {
         throw new StateOpsError('VALIDATION_ERROR', `field ${key} is not patchable`);
       }
       let value = patch[key];
+      if (key === 'change_id' && value !== null
+        && !db.prepare('SELECT id FROM changes WHERE id = ?').get(value)) {
+        throw new StateOpsError('CHANGE_NOT_FOUND', `change ${value} does not exist`);
+      }
       if (key === 'deps' || key === 'files_modified') {
         if (value !== null && !Array.isArray(value)) {
           throw new StateOpsError('VALIDATION_ERROR', `${key} must be an array`);
@@ -224,6 +235,7 @@ function patchTask(db, id, patch = {}) {
       appendEventInTx(db, {
         type: statusEventType(nextStatus),
         task_id: id,
+        change_id: patch.change_id !== undefined ? patch.change_id : current.change_id,
         payload: { from: current.status, to: nextStatus },
       });
     }
@@ -268,11 +280,12 @@ function appendEventInTx(db, event) {
     throw new StateOpsError('VALIDATION_ERROR', `unsupported runtime: ${event.runtime}`);
   }
   const result = db.prepare(
-    `INSERT INTO events (type, task_id, session_id, runtime, payload_json)
-     VALUES (?, ?, ?, ?, ?)`,
+    `INSERT INTO events (type, task_id, change_id, session_id, runtime, payload_json)
+     VALUES (?, ?, ?, ?, ?, ?)`,
   ).run(
     event.type,
     event.task_id ?? null,
+    event.change_id ?? null,
     event.session_id ?? null,
     event.runtime ?? null,
     event.payload === undefined ? null : JSON.stringify(event.payload),
@@ -287,7 +300,7 @@ function appendEvent(db, event) {
 
 // Single static SQL using json_each for the optional types IN-list and
 // NULL-pass-through for task_id/session_id. Frozen literal — no concat, no interpolation.
-const SUBSCRIBE_EVENTS_SQL = "SELECT id, ts, type, task_id, session_id, runtime, payload_json FROM events WHERE id > @since_id AND (@types_json IS NULL OR EXISTS (SELECT 1 FROM json_each(@types_json) WHERE value = events.type)) AND (@task_id IS NULL OR task_id = @task_id) AND (@session_id IS NULL OR session_id = @session_id) ORDER BY id ASC LIMIT @maxn";
+const SUBSCRIBE_EVENTS_SQL = "SELECT id, ts, type, task_id, change_id, session_id, runtime, payload_json FROM events WHERE id > @since_id AND (@types_json IS NULL OR EXISTS (SELECT 1 FROM json_each(@types_json) WHERE value = events.type)) AND (@task_id IS NULL OR task_id = @task_id) AND (@session_id IS NULL OR session_id = @session_id) ORDER BY id ASC LIMIT @maxn";
 
 function subscribeEventsSince(db, { since_id = 0, types, task_id, session_id, limit = 100 } = {}) {
   const events = db.prepare(SUBSCRIBE_EVENTS_SQL).all({
@@ -704,6 +717,7 @@ module.exports = {
   deleteTask,
   // events
   appendEvent,
+  appendEventInTx,
   subscribeEventsSince,
   // sessions
   createSession,

package/mcp-server/server.cjs

@@ -28,6 +28,9 @@ const parser = require('./lib/prd-parser.cjs');
 const expander = require('./lib/task-expander.cjs');
 const planStore = require('./lib/plan-store.cjs');
 const { initProject } = require('./lib/init-project.cjs');
+const changes = require('./lib/change-workflow.cjs');
+const runtimeState = require('./lib/runtime-state.cjs');
+const doctor = require('./lib/doctor.cjs');
 
 const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
@@ -64,8 +67,22 @@ const PLAN_TOOLS = Object.freeze([
   'plan.get',
 ]);
 
+const CHANGE_TOOLS = Object.freeze([
+  'change.create',
+  'change.update',
+  'change.get',
+  'change.list',
+  'change.context',
+  'change.converge',
+  'change.archive',
+]);
+
+const SYSTEM_TOOLS = Object.freeze([
+  'system.doctor',
+]);
+
 const REGISTERED_TOOLS = Object.freeze([
-  ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS,
+  ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS, ...CHANGE_TOOLS, ...SYSTEM_TOOLS,
 ]);
 
 const STATELESS_TOOLS = new Set(['task.init_project']);
@@ -76,6 +93,8 @@ const MUTATING_TOOLS = new Set([
   'task.create', 'task.update', 'task.delete', 'task.append_event', 'task.switch_tag',
   'task.parse_prd', 'task.expand',
   'session.spawn', 'session.close', 'session.heartbeat',
+  'plan.export',
+  'change.create', 'change.update', 'change.context', 'change.converge', 'change.archive',
 ]);
 
 function loadRegisteredTools() {
@@ -145,6 +164,7 @@ async function dispatchTool(name, input, db, ctx = {}) {
       const r = ops.appendEvent(db, {
         type: input.type,
         task_id: input.task_id,
+        change_id: input.change_id,
         session_id: input.session_id,
         runtime: input.runtime,
         payload: input.payload,
@@ -328,6 +348,53 @@ async function dispatchTool(name, input, db, ctx = {}) {
       }
       return { plan: planStore.selectSection(loaded, input.section) };
     }
+    case 'change.create': {
+      const { randomUUID } = require('node:crypto');
+      const id = input.id || `chg-${randomUUID().slice(0, 12)}`;
+      return changes.createChange(db, { ...input, id }, { rootDir: ctx.rootDir || process.cwd() });
+    }
+    case 'change.update': {
+      return {
+        ok: true,
+        change: changes.updateChange(
+          db, input.id, input.patch || {}, { rootDir: ctx.rootDir || process.cwd() },
+        ),
+      };
+    }
+    case 'change.get': {
+      const change = changes.readChange(db, input.id);
+      if (!change) {
+        const err = new Error(`change ${input.id} not found`);
+        err.code = 'CHANGE_NOT_FOUND';
+        throw err;
+      }
+      return { change };
+    }
+    case 'change.list': {
+      const rows = changes.listChanges(db, input || {});
+      return { changes: rows, count: rows.length };
+    }
+    case 'change.context': {
+      const out = changes.compileContext(db, input, { rootDir: ctx.rootDir || process.cwd() });
+      return {
+        manifest_path: out.context_manifest_path,
+        manifest_hash: out.manifest_hash,
+        manifest: out.manifest,
+      };
+    }
+    case 'change.converge': {
+      return changes.convergeChange(db, input, { rootDir: ctx.rootDir || process.cwd() });
+    }
+    case 'change.archive': {
+      return changes.archiveChange(db, input, { rootDir: ctx.rootDir || process.cwd() });
+    }
+    case 'system.doctor': {
+      return doctor.runDoctor(db, {
+        rootDir: ctx.rootDir || process.cwd(),
+        repair: input.repair === true,
+        project: ctx.projector || projector.projectAll,
+      });
+    }
     default:
       throw new Error(`unhandled tool ${name}`);
   }
@@ -345,7 +412,7 @@ function errorResponse(code, message, retriable = false, details = undefined) {
   };
 }
 
-function startServer({ dbPath, rootDir, projectOnWrite = true }) {
+function startServer({ dbPath, rootDir, projectOnWrite = true, project = projector.projectAll }) {
   let db = null;
   const getDb = () => {
     if (!db) db = initStateDb(dbPath).db;
@@ -415,7 +482,7 @@ function startServer({ dbPath, rootDir, projectOnWrite = true }) {
     try {
       toolDb = STATELESS_TOOLS.has(name) ? null : getDb();
       if (toolDb) assertStateAuthority(toolDb, rootDir);
-      result = await dispatchTool(name, args, toolDb, { rootDir });
+      result = await dispatchTool(name, args, toolDb, { rootDir, projector: project });
     } catch (err) {
       const code = err.code || (err instanceof ops.StateOpsError ? err.code : 'STATE_DB_ERROR');
       toolError = code;
@@ -423,22 +490,45 @@ function startServer({ dbPath, rootDir, projectOnWrite = true }) {
       return errorResponse(code, err.message, !!err.retriable, err.details);
     }
 
+    let runtimeMeta = null;
+    if (toolDb && projectOnWrite && MUTATING_TOOLS.has(name)) {
+      const job = runtimeState.enqueueProjection(toolDb, { tool_name: name });
+      const processed = runtimeState.processProjectionJobs(toolDb, { rootDir, project, limit: 500 });
+      const own = processed.jobs.find((item) => item.id === job.id);
+      runtimeMeta = {
+        state_commit: 'committed',
+        projection_status: own ? own.status : 'failed',
+        projection_job_id: job.id,
+      };
+      if (own && own.incident_id) runtimeMeta.incident_id = own.incident_id;
+    } else if (toolDb && name === 'system.doctor' && args.repair === true) {
+      runtimeMeta = {
+        state_commit: 'committed',
+        projection_status: result.checks.projections.status === 'pass' ? 'completed' : 'failed',
+        backup_path: result.backup_path,
+      };
+    }
+
     const validateOutput = outputValidators.get(name);
     if (!validateOutput(result)) {
       toolError = 'OUTPUT_SCHEMA_DRIFT';
       emitTelemetry();
-      return errorResponse('OUTPUT_SCHEMA_DRIFT', ajv.errorsText(validateOutput.errors));
-    }
-
-    if (toolDb && projectOnWrite && MUTATING_TOOLS.has(name)) {
-      try { projector.projectAll(toolDb, { rootDir }); }
-      catch (err) { process.stderr.write(`projector warning: ${err.message}\n`); }
+      const response = errorResponse(
+        'OUTPUT_SCHEMA_DRIFT',
+        ajv.errorsText(validateOutput.errors),
+        false,
+        runtimeMeta ? { _ultra: runtimeMeta } : undefined,
+      );
+      if (runtimeMeta) response._meta = { ultra: runtimeMeta };
+      return response;
     }
 
     emitTelemetry();
+    const visible = runtimeMeta ? { ...result, _ultra: runtimeMeta } : result;
     return {
-      content: [{ type: 'text', text: JSON.stringify(result) }],
+      content: [{ type: 'text', text: JSON.stringify(visible) }],
       structuredContent: result,
+      ...(runtimeMeta ? { _meta: { ultra: runtimeMeta } } : {}),
     };
   });
 
@@ -478,6 +568,8 @@ module.exports = {
   dispatchTool,
   TASK_TOOLS,
   SESSION_TOOLS,
+  CHANGE_TOOLS,
+  SYSTEM_TOOLS,
   REGISTERED_TOOLS,
   STATELESS_TOOLS,
   MUTATING_TOOLS,

package/mcp-server/tests/db-ops.test.cjs

@@ -46,7 +46,11 @@ test('db vacuum reports reclaimed bytes after deleting rows', () => {
   try {
     const init = initStateDb(dbPath);
     for (let i = 0; i < 50; i++) {
-      ops.appendEvent(init.db, { type: 'task_created', task_id: `t-${i}` });
+      ops.appendEvent(init.db, {
+        type: 'task_created',
+        task_id: `t-${i}`,
+        payload: { padding: 'x'.repeat(16 * 1024) },
+      });
     }
     init.db.prepare('DELETE FROM events').run();
     closeStateDb(init.db);