ultra-builder-pro-cli 0.5.3 → 0.7.0

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);

package/mcp-server/tests/init-project.test.cjs

@@ -5,6 +5,7 @@ const assert = require('node:assert/strict');
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const Database = require('better-sqlite3');
 
 const { initProject, InitProjectError, DEFAULT_TEMPLATE } = require('../lib/init-project.cjs');
 
@@ -29,6 +30,18 @@ test('initProject copies bundled template into .ultra/', () => {
     assert.equal(r.created_path, path.join(target, '.ultra'));
     assert.ok(r.copied_files.includes('tasks/tasks.json'));
     assert.ok(r.copied_files.includes('specs/product.md'));
+    assert.ok(r.copied_files.includes('changes/active/.gitkeep'));
+    assert.ok(r.copied_files.includes('changes/archive/.gitkeep'));
+    assert.equal(r.state_db_path, path.join(target, '.ultra', 'state.db'));
+    assert.ok(fs.existsSync(r.state_db_path));
+    const db = new Database(r.state_db_path, { readonly: true });
+    try {
+      const version = db.prepare("SELECT version FROM schema_version WHERE version = '9.0'").get();
+      assert.equal(version.version, '9.0');
+      assert.ok(db.prepare("SELECT name FROM sqlite_master WHERE name = 'changes'").get());
+    } finally {
+      db.close();
+    }
     assert.ok(!r.copied_files.some((f) => f.endsWith('.DS_Store')));
   } finally { cleanup(target); }
 });
@@ -81,6 +94,38 @@ test('initProject with overwrite=true backs up existing .ultra/', () => {
   } finally { cleanup(target); }
 });
 
+test('initProject restores the prior .ultra when overwrite initialization fails', () => {
+  const target = mkTempDir();
+  const badTemplate = mkTempDir('ubp-bad-template-');
+  try {
+    initProject({ target_dir: target, project_name: 'first' });
+    fs.writeFileSync(path.join(target, '.ultra', 'sentinel.txt'), 'restore-me');
+    fs.cpSync(DEFAULT_TEMPLATE, badTemplate, { recursive: true });
+    fs.writeFileSync(path.join(badTemplate, 'tasks', 'tasks.json'), '{not-json\n');
+
+    assert.throws(
+      () => initProject({
+        target_dir: target,
+        project_name: 'broken-overwrite',
+        overwrite: true,
+        source_template: badTemplate,
+      }),
+      (error) => error instanceof InitProjectError && error.code === 'IO_ERROR',
+    );
+    assert.equal(
+      fs.readFileSync(path.join(target, '.ultra', 'sentinel.txt'), 'utf8'),
+      'restore-me',
+    );
+    assert.equal(
+      fs.readdirSync(target).some((name) => name.startsWith('.ultra.backup.')),
+      false,
+    );
+  } finally {
+    cleanup(target);
+    cleanup(badTemplate);
+  }
+});
+
 test('initProject rejects empty project_name', () => {
   const target = mkTempDir();
   try {

package/mcp-server/tests/server-contract.test.cjs

@@ -6,6 +6,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const yaml = require('js-yaml');
+const Database = require('better-sqlite3');
 
 const { Client } = require('@modelcontextprotocol/sdk/client/index.js');
 const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
@@ -19,7 +20,7 @@ function tmpProject() {
   return { dir, dbPath: path.join(dir, '.ultra', 'state.db') };
 }
 
-async function withClient({ dir, dbPath }, fn) {
+async function withClient({ dir, dbPath }, fn, extraEnv = {}) {
   const transport = new StdioClientTransport({
     command: process.execPath,
     args: [SERVER],
@@ -27,6 +28,7 @@ async function withClient({ dir, dbPath }, fn) {
       ...process.env,
       UBP_DB_PATH: dbPath,
       UBP_ROOT_DIR: dir,
+      ...extraEnv,
     },
     stderr: 'pipe',
   });
@@ -72,6 +74,13 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
       const list = await client.listTools();
       const names = list.tools.map((t) => t.name).sort();
       assert.deepEqual(names, [
+        'change.archive',
+        'change.context',
+        'change.converge',
+        'change.create',
+        'change.get',
+        'change.list',
+        'change.update',
         'plan.export',
         'plan.get',
         'session.admission_check',
@@ -81,6 +90,7 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
         'session.list',
         'session.spawn',
         'session.subscribe_events',
+        'system.doctor',
         'task.append_event',
         'task.create',
         'task.delete',
@@ -105,6 +115,67 @@ test('listTools returns workflow tools and exposes no Ultra memory API', async (
   }
 });
 
+test('change.create + change.context expose a continuous change unit with external provider references', async () => {
+  const proj = tmpProject();
+  try {
+    fs.writeFileSync(path.join(proj.dir, 'README.md'), '# project\n');
+    await withClient(proj, async (client) => {
+      const created = await client.callTool({
+        name: 'change.create',
+        arguments: {
+          id: 'mcp-change', title: 'Continuous maintenance', kind: 'quick',
+          intent: 'Keep daily modifications synchronized after initial delivery.',
+          docs_impact: { status: 'none', files: [], rationale: 'Contract-only fixture.' },
+          provider_refs: {
+            memory: { provider: 'cloud-mem', status: 'available', reference: 'cmem://fixture' },
+            code_graph: { provider: 'codebase-memory-mcp', status: 'stale', project: 'fixture' },
+          },
+        },
+      });
+      const payload = readToolPayload(created);
+      assert.equal(payload.change.id, 'mcp-change');
+      assert.equal(payload.change.status, 'active');
+      assert.equal(created._meta.ultra.state_commit, 'committed');
+      assert.equal(created._meta.ultra.projection_status, 'completed');
+
+      const context = readToolPayload(await client.callTool({
+        name: 'change.context', arguments: { id: 'mcp-change' },
+      }));
+      assert.equal(context.manifest.change.id, 'mcp-change');
+      assert.equal(context.manifest.providers.memory.provider, 'cloud-mem');
+      assert.equal(context.manifest.provider_boundary.includes('content remain external'), true);
+
+      const listed = readToolPayload(await client.callTool({
+        name: 'change.list', arguments: { status: 'active' },
+      }));
+      assert.equal(listed.count, 1);
+      assert.equal(listed.changes[0].id, 'mcp-change');
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
+test('system.doctor returns structured provider ownership and projection health', async () => {
+  const proj = tmpProject();
+  try {
+    await withClient(proj, async (client) => {
+      await client.callTool({
+        name: 'task.create',
+        arguments: { id: 'doctor-seed', title: 'doctor seed', type: 'feature', priority: 'P1' },
+      });
+      const result = readToolPayload(await client.callTool({
+        name: 'system.doctor', arguments: { repair: false },
+      }));
+      assert.equal(result.status, 'healthy');
+      assert.equal(result.checks.external_providers.ownership, 'external');
+      assert.equal(result.repair_performed, false);
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
 test('MCP metadata matches the package and tools/list does not create project state', async () => {
   const proj = tmpProject();
   try {
@@ -309,6 +380,54 @@ test('mutating tools trigger the projector — tasks.json appears under .ultra/'
   }
 });
 
+test('output schema drift cannot strand a committed mutation without a projection job', async () => {
+  const proj = tmpProject();
+  try {
+    const runtimeRoot = path.join(proj.dir, 'runtime-contract');
+    fs.mkdirSync(path.join(runtimeRoot, 'spec', 'schemas'), { recursive: true });
+    fs.copyFileSync(path.join(REPO_ROOT, 'package.json'), path.join(runtimeRoot, 'package.json'));
+    fs.copyFileSync(
+      path.join(REPO_ROOT, 'spec', 'schemas', 'state-db.sql'),
+      path.join(runtimeRoot, 'spec', 'schemas', 'state-db.sql'),
+    );
+    const manifest = yaml.load(
+      fs.readFileSync(path.join(REPO_ROOT, 'spec', 'mcp-tools.yaml'), 'utf8'),
+    );
+    const createTool = manifest.tools.find((tool) => tool.name === 'task.create');
+    createTool.output_schema.required = ['impossible_output_field'];
+    createTool.output_schema.properties.impossible_output_field = { type: 'string' };
+    fs.writeFileSync(
+      path.join(runtimeRoot, 'spec', 'mcp-tools.yaml'),
+      yaml.dump(manifest, { noRefs: true, lineWidth: 120 }),
+    );
+
+    await withClient(proj, async (client) => {
+      const result = await client.callTool({
+        name: 'task.create',
+        arguments: { id: 'schema-drift', title: 'schema drift', type: 'feature', priority: 'P1' },
+      });
+      const error = expectError(result);
+      assert.equal(error.code, 'OUTPUT_SCHEMA_DRIFT');
+      assert.equal(error.details._ultra.state_commit, 'committed');
+      assert.equal(error.details._ultra.projection_status, 'completed');
+    }, { UBP_RUNTIME_ROOT: runtimeRoot });
+
+    const db = new Database(proj.dbPath, { readonly: true, fileMustExist: true });
+    try {
+      assert.equal(db.prepare('SELECT COUNT(*) AS count FROM tasks WHERE id = ?').get('schema-drift').count, 1);
+      const job = db.prepare(
+        "SELECT status FROM projection_jobs WHERE tool_name = 'task.create' ORDER BY id DESC LIMIT 1",
+      ).get();
+      assert.deepEqual(job, { status: 'completed' });
+    } finally {
+      db.close();
+    }
+    assert.ok(fs.existsSync(path.join(proj.dir, '.ultra', 'tasks', 'tasks.json')));
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
 test('task.init_project creates .ultra/ skeleton in a fresh target directory', async () => {
   const proj = tmpProject();
   const freshTarget = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-init-target-'));
@@ -321,6 +440,8 @@ test('task.init_project creates .ultra/ skeleton in a fresh target directory', a
       const payload = readToolPayload(res);
       assert.equal(payload.status, 'created');
       assert.equal(payload.created_path, path.join(freshTarget, '.ultra'));
+      assert.equal(payload.state_db_path, path.join(freshTarget, '.ultra', 'state.db'));
+      assert.ok(fs.existsSync(payload.state_db_path));
       assert.ok(payload.copied_files.includes('tasks/tasks.json'));
       const tasksJson = JSON.parse(fs.readFileSync(path.join(payload.created_path, 'tasks', 'tasks.json'), 'utf8'));
       assert.equal(tasksJson.project.name, 'mcp-init');
@@ -390,6 +511,23 @@ test('session.admission_check + session.spawn: happy path returns sid and paths'
   }
 });
 
+test('session.spawn rejects a retired runtime at the MCP schema boundary', async () => {
+  const proj = tmpProject();
+  const retiredRuntime = ['gem', 'ini'].join('');
+  try {
+    await withClient(proj, async (client) => {
+      await seedTask(client, 's-runtime-guard');
+      const spawn = await client.callTool({
+        name: 'session.spawn',
+        arguments: { task_id: 's-runtime-guard', runtime: retiredRuntime },
+      });
+      assert.equal(expectError(spawn).code, 'VALIDATION_ERROR');
+    });
+  } finally {
+    fs.rmSync(proj.dir, { recursive: true, force: true });
+  }
+});
+
 test('session.spawn refuses second session for same task without takeover (ADMISSION_DENIED)', async () => {
   const proj = tmpProject();
   try {
@@ -731,6 +869,7 @@ test('plan.export → plan.get round trip: artifact on disk + retrievable', asyn
       const expData = readToolPayload(exp);
       assert.equal(expData.wave_count, 2);
       assert.ok(fs.existsSync(expData.plan_path), 'artifact file must exist');
+      assert.equal(exp._meta.ultra.projection_status, 'completed');
 
       const got = await client.callTool({ name: 'plan.get', arguments: { section: 'topo' } });
       const gotData = readToolPayload(got);

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

@@ -8,22 +8,59 @@ const path = require('node:path');
 
 const stateDb = require('../lib/state-db.cjs');
 
-test('initStateDb upgrades a v8A.1 database in place with estimated_days', () => {
+test('initStateDb upgrades a pre-9.0 database in place with task/event change linkage', () => {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-db-upgrade-'));
   const file = path.join(dir, 'state.db');
   try {
     const db = stateDb.openStateDb(file);
-    const oldSql = fs.readFileSync(stateDb.SCHEMA_FILE, 'utf8')
-      .replace(/^\s*estimated_days.*\n/m, '')
-      .replace(/^INSERT OR IGNORE INTO schema_version \(version, description\)\nVALUES \('8A\.2'.*\n/m, '');
-    db.exec(oldSql);
+    db.exec(`
+      CREATE TABLE tasks (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL,
+        type TEXT NOT NULL,
+        priority TEXT NOT NULL,
+        complexity INTEGER,
+        status TEXT NOT NULL DEFAULT 'pending',
+        deps TEXT,
+        files_modified TEXT,
+        session_id TEXT,
+        stale INTEGER NOT NULL DEFAULT 0,
+        complexity_hint TEXT,
+        tag TEXT,
+        trace_to TEXT,
+        context_file TEXT,
+        completion_commit TEXT,
+        parent_id TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      CREATE TABLE events (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts TEXT NOT NULL,
+        type TEXT NOT NULL,
+        task_id TEXT,
+        session_id TEXT,
+        runtime TEXT,
+        payload_json TEXT
+      );
+      CREATE TABLE schema_version (
+        version TEXT PRIMARY KEY,
+        applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+        description TEXT
+      );
+      INSERT INTO schema_version (version, applied_at, description)
+      VALUES ('8A.1', '2026-01-01T00:00:00.000Z', 'legacy fixture');
+    `);
     stateDb.closeStateDb(db);
 
     const upgraded = stateDb.initStateDb(file);
     const columns = upgraded.db.prepare('PRAGMA table_info(tasks)').all().map((row) => row.name);
     assert.ok(columns.includes('estimated_days'));
-    assert.equal(upgraded.schema_version, '8A.2');
-    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '8A.2'").get());
+    assert.ok(columns.includes('change_id'));
+    const eventColumns = upgraded.db.prepare('PRAGMA table_info(events)').all().map((row) => row.name);
+    assert.ok(eventColumns.includes('change_id'));
+    assert.equal(upgraded.schema_version, '9.0');
+    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '9.0'").get());
     stateDb.closeStateDb(upgraded.db);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });

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

@@ -112,6 +112,25 @@ test('patchTask updates JSON arrays + flags + status atomically', () => {
   }
 });
 
+test('patchTask status event follows the newly assigned continuous change', () => {
+  const { dir, db } = freshDb();
+  try {
+    db.prepare(
+      `INSERT INTO changes (id, title, kind, intent, artifact_root)
+       VALUES ('chg-link', 'Link task', 'quick', 'Link task to change.', '.ultra/changes/active/chg-link')`,
+    ).run();
+    ops.createTask(db, { id: 'link-task', title: 'link me', type: 'feature', priority: 'P1' });
+    ops.patchTask(db, 'link-task', { change_id: 'chg-link', status: 'in_progress' });
+    const event = db.prepare(
+      "SELECT change_id FROM events WHERE task_id = 'link-task' AND type = 'task_started'",
+    ).get();
+    assert.equal(event.change_id, 'chg-link');
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('patchTask rejects unknown fields', () => {
   const { dir, db } = freshDb();
   try {
@@ -194,6 +213,29 @@ test('createSession requires existing task and emits session_spawned', () => {
   }
 });
 
+test('runtime-bearing mutations reject unsupported runtimes before touching state', () => {
+  const { dir, db } = freshDb();
+  const retiredRuntime = ['gem', 'ini'].join('');
+  try {
+    ops.createTask(db, { id: 'runtime-guard', title: 'guard', type: 'feature', priority: 'P1' });
+    assert.throws(
+      () => ops.createSession(db, {
+        sid: 'unsupported', task_id: 'runtime-guard', runtime: retiredRuntime,
+        worktree_path: '/tmp/wt', artifact_dir: '/tmp/art',
+      }),
+      (error) => error.code === 'VALIDATION_ERROR' && /unsupported runtime/.test(error.message),
+    );
+    assert.throws(
+      () => ops.appendEvent(db, { type: 'task_started', task_id: 'runtime-guard', runtime: retiredRuntime }),
+      (error) => error.code === 'VALIDATION_ERROR' && /unsupported runtime/.test(error.message),
+    );
+    assert.equal(db.prepare("SELECT COUNT(*) AS n FROM sessions").get().n, 0);
+    closeStateDb(db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test('updateSession status=completed emits session_closed', () => {
   const { dir, db } = freshDb();
   try {

package/mcp-server/tests/telemetry.test.cjs

@@ -140,6 +140,20 @@ test('appendTelemetry event_type constraint: invalid value rejected', () => {
   } finally { teardown(dir, db); }
 });
 
+test('appendTelemetry rejects unsupported runtime labels', () => {
+  const { dir, db } = freshFixture();
+  const retiredRuntime = ['gem', 'ini'].join('');
+  try {
+    assert.throws(
+      () => telemetry.appendTelemetry(db, {
+        event_type: 'tool_call', runtime: retiredRuntime, rootDir: dir,
+      }),
+      /unsupported runtime/,
+    );
+    assert.equal(db.prepare('SELECT COUNT(*) AS n FROM telemetry').get().n, 0);
+  } finally { teardown(dir, db); }
+});
+
 // ─── aggregation ─────────────────────────────────────────────────────────
 
 test('aggregateTelemetryByRuntime: groups calls + sums tokens/cost', () => {