ultra-builder-pro-cli 0.23.0 → 0.24.0

package/mcp-server/server.cjs

@@ -1,194 +1,53 @@
 'use strict';
 
-// MCP server (stdio JSON-RPC) exposing task.* + session.* tools backed by
-// .ultra/.runtime/state.db. Uses the low-level Server API from
-// @modelcontextprotocol/server so we can pass raw JSON Schema (Draft 2020-12)
-// straight from spec/mcp-tools.yaml without translating to zod.
-
 const fs = require('node:fs');
 const path = require('node:path');
 
-const yaml = require('js-yaml');
 const Ajv = require('ajv/dist/2020');
 const addFormats = require('ajv-formats');
-
+const yaml = require('js-yaml');
 const { Server } = require('@modelcontextprotocol/server');
 const { StdioServerTransport } = require('@modelcontextprotocol/server/stdio');
-const { version: PACKAGE_VERSION } = require('../package.json');
 
+const { version: PACKAGE_VERSION } = require('../package.json');
 const {
-  initStateDb, closeStateDb, openStateDb, ensureSchemaVersion,
+  closeStateDb,
+  ensureSchemaVersion,
+  initStateDb,
+  openStateDb,
 } = require('./lib/state-db.cjs');
 const { assertStateAuthority } = require('./lib/state-authority.cjs');
+const gitBootstrap = require('./lib/git-bootstrap.cjs');
 const ops = require('./lib/state-ops.cjs');
+const planStore = require('./lib/plan-store.cjs');
 const projector = require('./lib/projector.cjs');
+const {
+  readProjectContextEnvelope,
+  renderProjectContextEnvelope,
+} = require('./lib/project-context.cjs');
+const runtimePaths = require('./lib/runtime-paths.cjs');
+const runtimeState = require('./lib/runtime-state.cjs');
 const taskLedger = require('./lib/task-ledger.cjs');
 const telemetry = require('./lib/telemetry.cjs');
-const topo = require('./lib/topo.cjs');
-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 baselines = require('./lib/baseline-workflow.cjs');
-const changes = require('./lib/change-workflow.cjs');
-const contextSpine = require('./lib/context-spine.cjs');
-const runtimeState = require('./lib/runtime-state.cjs');
-const runtimePaths = require('./lib/runtime-paths.cjs');
-const gitBootstrap = require('./lib/git-bootstrap.cjs');
-const workflows = require('./lib/workflow-state.cjs');
-const decisions = require('./lib/decision-dialogue.cjs');
-const doctor = require('./lib/doctor.cjs');
-const artifactRegistry = require('./lib/artifact-registry.cjs');
 const ultraFacade = require('./lib/ultra-facade.cjs');
-const {
-  readProjectBreadcrumb,
-  renderProjectBreadcrumb,
-} = require('./lib/project-breadcrumb.cjs');
-const sessionRunner = require('../orchestrator/session-runner.cjs');
 
 const REPO_ROOT = process.env.UBP_RUNTIME_ROOT
   ? path.resolve(process.env.UBP_RUNTIME_ROOT)
   : path.resolve(__dirname, '..');
 const TOOLS_FILE = path.join(REPO_ROOT, 'spec', 'mcp-tools.yaml');
-
-const TASK_TOOLS = Object.freeze([
-  'task.create',
-  'task.update',
-  'task.list',
-  'task.get',
-  'task.delete',
-  'task.init_project',
-  'task.append_event',
-  'task.subscribe_events',
-  'task.switch_tag',
-  'task.dependency_topo',
-  'task.parse_prd',
-  'task.expand',
-  'task.ledger_get',
-  'task.ledger_publish',
-  'task.ledger_import',
-]);
-
-const SESSION_TOOLS = Object.freeze([
-  'session.spawn',
-  'session.close',
-  'session.get',
-  'session.list',
-  'session.admission_check',
-  'session.heartbeat',
-  'session.subscribe_events',
-]);
-
-const PLAN_TOOLS = Object.freeze([
-  'plan.export',
-  'plan.get',
-]);
-
-const BASELINE_TOOLS = Object.freeze([
-  'baseline.start',
-  'baseline.record',
-  'baseline.get',
-  'baseline.converge',
-]);
-
-const CHANGE_TOOLS = Object.freeze([
-  'change.create',
-  'change.update',
-  'change.delta',
-  'change.documentation_reconcile',
-  'change.get',
-  'change.list',
-  'change.context',
-  'change.breadcrumb',
-  'change.learning_propose',
-  'change.learning_resolve',
-  'change.converge',
-  'change.archive',
-]);
-
-const WORKFLOW_TOOLS = Object.freeze([
-  'workflow.start',
-  'workflow.get',
-  'workflow.list',
-  'workflow.step',
-  'workflow.revise',
-  'workflow.supersede',
-  'workflow.complete',
-]);
-
-const DECISION_TOOLS = Object.freeze([
-  'decision.thread_start',
-  'decision.get',
-  'decision.list',
-  'decision.open',
-  'decision.resolve',
-  'decision.delegate',
-  'decision.defer',
-  'decision.supersede',
-  'decision.complete',
-  'decision.checkpoint',
-]);
-
-const SYSTEM_TOOLS = Object.freeze([
-  'system.doctor',
-]);
-
-const ARTIFACT_TOOLS = Object.freeze([
-  'artifact.record',
-  'artifact.get',
-]);
-
-const LEGACY_TOOLS = Object.freeze([
-  ...TASK_TOOLS, ...SESSION_TOOLS, ...PLAN_TOOLS, ...BASELINE_TOOLS, ...CHANGE_TOOLS,
-  ...DECISION_TOOLS,
-  ...WORKFLOW_TOOLS,
-  ...ARTIFACT_TOOLS,
-  ...SYSTEM_TOOLS,
-]);
 const PUBLIC_TOOLS = ultraFacade.PUBLIC_TOOLS;
-const REGISTERED_TOOLS = Object.freeze([...PUBLIC_TOOLS, ...LEGACY_TOOLS]);
-
-const STATELESS_TOOLS = new Set(['task.init_project']);
-
-function isStatelessPublicCall(name, input = {}) {
-  return name === 'ultra.record'
-    && Array.isArray(input.entries)
-    && input.entries.length === 1
-    && input.entries[0]?.operation === 'task.init_project';
-}
-
-// init_project owns its target project's schema, baseline seed, and first
-// projection internally. Do not enqueue a second projection on the caller DB.
-const MUTATING_TOOLS = new Set([
-  'ultra.record', 'ultra.checkpoint', 'ultra.sync', 'ultra.session', 'ultra.archive',
-  'task.create', 'task.update', 'task.delete', 'task.append_event', 'task.switch_tag',
-  'task.parse_prd', 'task.expand',
-  'task.ledger_import',
-  'session.spawn', 'session.close', 'session.heartbeat',
-  'plan.export',
-  'baseline.start', 'baseline.record', 'baseline.converge',
-  'change.create', 'change.update', 'change.delta', 'change.documentation_reconcile',
-  'change.context', 'change.converge', 'change.archive',
-  'change.learning_propose', 'change.learning_resolve',
-  'decision.thread_start', 'decision.open', 'decision.resolve', 'decision.delegate',
-  'decision.defer', 'decision.supersede', 'decision.complete', 'decision.checkpoint',
-  'workflow.start', 'workflow.step', 'workflow.revise', 'workflow.supersede',
-  'workflow.complete',
-  'artifact.record',
-]);
+const REGISTERED_TOOLS = PUBLIC_TOOLS;
 
-const TEAM_LEDGER_SYNC_TOOLS = new Set([
-  'ultra.record', 'ultra.checkpoint', 'ultra.archive',
-  'task.create', 'task.update', 'task.delete', 'task.parse_prd', 'task.expand',
-  'plan.export',
-  'baseline.start', 'baseline.record', 'baseline.converge',
-  'change.create', 'change.update', 'change.delta', 'change.documentation_reconcile',
-  'change.converge', 'change.archive',
-]);
-
-function loadRegisteredTools() {
+function loadToolContracts() {
   const manifest = yaml.load(fs.readFileSync(TOOLS_FILE, 'utf8'));
-  return manifest.tools.filter((t) => REGISTERED_TOOLS.includes(t.name));
+  const names = manifest.tools.map((tool) => tool.name).sort();
+  const expected = [...PUBLIC_TOOLS].sort();
+  if (JSON.stringify(names) !== JSON.stringify(expected)) {
+    const error = new Error('published MCP manifest does not match the seven-tool kernel');
+    error.code = 'PUBLIC_CONTRACT_DRIFT';
+    throw error;
+  }
+  return manifest.tools;
 }
 
 function buildAjv() {
@@ -197,754 +56,6 @@ function buildAjv() {
   return ajv;
 }
 
-async function dispatchTool(name, input, db, ctx = {}) {
-  switch (name) {
-    case 'task.create': {
-      const { randomUUID } = require('node:crypto');
-      const id = input.id || `task-${randomUUID()}`;
-      const changeId = ops.resolveTaskCreationChangeId(db, input);
-      const authorizedInput = { ...input, change_id: changeId };
-      changes.assertTaskCreationAllowed(db, authorizedInput, { rootDir: ctx.rootDir || process.cwd() });
-      const task = ops.createTask(db, { ...authorizedInput, id });
-      return { id: task.id, status: task.status, created_at: task.created_at };
-    }
-    case 'task.update': {
-      const before = ops.readTask(db, input.id);
-      const task = ops.patchTask(db, input.id, input.patch || {});
-      const durableChanged = before
-        && taskLedger.durableTask(before).digest !== taskLedger.durableTask(task).digest;
-      if (durableChanged) {
-        taskLedger.publishTaskLedger(db, {
-          rootDir: ctx.rootDir || process.cwd(),
-          reason: before.status !== task.status
-            ? `task_${task.status}`
-            : 'task_contract_updated',
-        });
-      }
-      return { ok: true, task };
-    }
-    case 'task.list': {
-      const tasks = ops.listTasks(db, input || {});
-      return { tasks, count: tasks.length };
-    }
-    case 'task.get': {
-      const task = ops.readTask(db, input.id);
-      if (!task) {
-        const err = new Error(`task ${input.id} not found`);
-        err.code = 'TASK_NOT_FOUND';
-        throw err;
-      }
-      return { task };
-    }
-    case 'task.delete': {
-      const result = ops.deleteTask(db, input.id, { force: !!input.force });
-      taskLedger.publishTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-        reason: 'task_deleted',
-      });
-      return result;
-    }
-    case 'task.init_project': {
-      return initProject(input);
-    }
-    case 'task.append_event': {
-      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,
-      });
-      return { event_id: r.event_id, ts: r.ts };
-    }
-    case 'task.subscribe_events': {
-      return ops.subscribeEventsSince(db, input || {});
-    }
-    case 'session.spawn': {
-      if (ctx.sessionId) {
-        const error = new Error(
-          `worker session ${ctx.sessionId} already owns an isolated worktree; `
-            + 'resume that session instead of recursively spawning another one',
-        );
-        error.code = 'NESTED_SESSION_FORBIDDEN';
-        throw error;
-      }
-      const rootDir = ctx.rootDir || process.cwd();
-      const handle = sessionRunner.spawnSession({
-        db,
-        repoRoot: rootDir,
-        task_id: input.task_id,
-        runtime: input.runtime,
-        takeover: Boolean(input.takeover),
-        worktree_base: input.worktree_base,
-      });
-      return {
-        sid: handle.sid,
-        worktree_path: handle.worktree_path,
-        artifact_dir: handle.artifact_dir,
-        lease_expires_at: handle.lease_expires_at,
-        worktree_created: true,
-      };
-    }
-    case 'session.close': {
-      if (ctx.sessionId) {
-        const error = new Error(
-          ctx.sessionId === input.sid
-            ? `worker session ${ctx.sessionId} is supervised by its parent; save evidence and exit so the parent can settle the lease`
-            : `worker session ${ctx.sessionId} cannot close unrelated session ${input.sid}`,
-        );
-        error.code = ctx.sessionId === input.sid
-          ? 'WORKER_SESSION_PARENT_OWNED'
-          : 'SESSION_SCOPE_VIOLATION';
-        throw error;
-      }
-      const closed = sessionRunner.closeSession(
-        { db, repoRoot: ctx.rootDir || process.cwd(), sid: input.sid },
-        { status: input.status, remove_worktree: input.remove_worktree === true },
-      );
-      return {
-        ok: true,
-        worktree_preserved: closed.worktree_preserved,
-      };
-    }
-    case 'session.get': {
-      const session = ops.readSession(db, input.sid);
-      if (!session) {
-        const err = new Error(`session ${input.sid} not found`);
-        err.code = 'SESSION_NOT_FOUND';
-        throw err;
-      }
-      return { session };
-    }
-    case 'session.admission_check': {
-      return sessionRunner.admissionCheck(
-        db,
-        ctx.rootDir || process.cwd(),
-        input.task_id,
-      );
-    }
-    case 'session.list': {
-      const sessions = ops.listActiveSessions(db, { task_id: input.task_id });
-      const status = input.status || 'running';
-      const filtered = status === 'running'
-        ? sessions
-        : db.prepare(
-            "SELECT * FROM sessions WHERE status = ? AND (? IS NULL OR task_id = ?) ORDER BY started_at ASC LIMIT ?",
-          ).all(status, input.task_id || null, input.task_id || null, Math.min(input.limit || 100, 500));
-      const limit = Math.min(input.limit || 100, 500);
-      const trimmed = filtered.slice(0, limit);
-      return { sessions: trimmed, count: trimmed.length };
-    }
-    case 'session.heartbeat': {
-      return ops.heartbeatSession(db, input.sid);
-    }
-    case 'session.subscribe_events': {
-      return ops.subscribeEventsSince(db, {
-        since_id: input.since_id,
-        session_id: input.sid,
-        limit: input.limit,
-      });
-    }
-    case 'task.switch_tag': {
-      return ops.switchTaskTag(db, input.id, input.tag);
-    }
-    case 'task.dependency_topo': {
-      const hasTaskIds = Array.isArray(input && input.task_ids);
-      const hasChangeId = typeof input?.change_id === 'string' && input.change_id.trim() !== '';
-      if (hasTaskIds === hasChangeId) {
-        const err = new Error('provide exactly one of task_ids or change_id');
-        err.code = 'VALIDATION_ERROR';
-        throw err;
-      }
-      let rows;
-      if (hasTaskIds) {
-        rows = input.task_ids.map((id) => {
-          const task = ops.readTask(db, id);
-          if (!task) {
-            const err = new Error(`task ${id} not found`);
-            err.code = 'TASK_NOT_FOUND';
-            throw err;
-          }
-          return task;
-        });
-      } else {
-        const change = changes.readChange(db, input.change_id);
-        if (!change) {
-          const err = new Error(`change ${input.change_id} not found`);
-          err.code = 'CHANGE_NOT_FOUND';
-          throw err;
-        }
-        rows = ops.listTasks(db, { change_id: change.id });
-      }
-      const graph = rows.map((t) => ({
-        id: t.id,
-        deps: Array.isArray(t.deps) ? t.deps : [],
-      }));
-      const result = topo.computeWaves(graph);
-      if (result.cycles.length > 0) {
-        const err = new Error(`dependency graph has ${result.cycles.length} cycle(s)`);
-        err.code = 'CYCLE_DETECTED';
-        err.details = { cycles: result.cycles };
-        throw err;
-      }
-      return { waves: result.waves };
-    }
-    case 'task.parse_prd': {
-      const dryRun = input.dry_run === true;
-      const rootDir = ctx.rootDir || process.cwd();
-      if (!dryRun && !String(input.change_id || '').trim()) {
-        const err = new Error('persisting a parsed task graph requires change_id');
-        err.code = 'CHANGE_REQUIRED';
-        throw err;
-      }
-      const creationAuthority = { change_id: input.change_id };
-      if (!dryRun) changes.assertTaskCreationAllowed(db, creationAuthority, { rootDir });
-      const parsed = parser.parsePrd(input.tasks, {
-        tag: input.tag,
-        changeId: input.change_id,
-      });
-      const shaped = parsed.tasks.map((t) => ({
-        id: t.id, title: t.title, type: t.type, priority: t.priority,
-        complexity: t.complexity, deps: t.deps, files_modified: t.files_modified,
-        tag: t.tag, change_id: t.change_id,
-      }));
-      const graph = shaped.map((t) => ({ id: t.id, deps: t.deps || [] }));
-      const topoResult = topo.computeWaves(graph);
-      if (topoResult.cycles.length > 0) {
-        const err = new Error(`parsed task graph has ${topoResult.cycles.length} cycle(s)`);
-        err.code = 'CYCLE_DETECTED';
-        err.details = { cycles: topoResult.cycles };
-        throw err;
-      }
-      if (!dryRun) {
-        try {
-          ops.tx(db, () => {
-            changes.assertTaskCreationAllowed(db, creationAuthority, { rootDir });
-            for (const t of shaped) ops.createTask(db, t);
-          });
-        } catch (err) {
-          if (['BASELINE_NOT_READY', 'CHANGE_NOT_FOUND', 'CHANGE_NOT_MUTABLE'].includes(err.code)) throw err;
-          const wrap = new Error(`failed to persist parsed tasks: ${err.message}`);
-          wrap.code = 'PARSE_FAILED';
-          wrap.cause = err;
-          throw wrap;
-        }
-      }
-      return { tasks: shaped, topo: topoResult.waves };
-    }
-    case 'task.expand': {
-      const parent = ops.readTask(db, input.id);
-      if (!parent) {
-        const err = new Error(`no task ${input.id}`);
-        err.code = 'TASK_NOT_FOUND';
-        throw err;
-      }
-      if (parent.status === 'expanded') {
-        const err = new Error(`task ${input.id} is already expanded`);
-        err.code = 'ALREADY_EXPANDED';
-        throw err;
-      }
-      const rootDir = ctx.rootDir || process.cwd();
-      changes.assertTaskCreationAllowed(db, { change_id: parent.change_id }, { rootDir });
-      const result = expander.expandTask(db, {
-        id: input.id,
-        children: input.children,
-        rootDir,
-      });
-      taskLedger.publishTaskLedger(db, {
-        rootDir,
-        reason: 'task_expanded',
-      });
-      return { parent_id: result.parent_id, children: result.children };
-    }
-    case 'task.ledger_get': {
-      const rootDir = ctx.rootDir || process.cwd();
-      return {
-        ledger: taskLedger.readTaskLedger(rootDir),
-        health: taskLedger.inspectTaskLedger(db, { rootDir }),
-      };
-    }
-    case 'task.ledger_publish': {
-      const result = taskLedger.publishTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-        reason: input.reason || 'manual_checkpoint',
-      });
-      const output = {
-        changed: result.changed,
-        path: path.relative(ctx.rootDir || process.cwd(), result.path),
-        generation: result.ledger.generation,
-        state_digest: result.ledger.state_digest,
-      };
-      if (result.migrated_legacy_projection) {
-        output.migrated_legacy_projection = true;
-        output.legacy_backup_path = path.relative(
-          ctx.rootDir || process.cwd(),
-          result.legacy_backup_path,
-        );
-      }
-      return output;
-    }
-    case 'task.ledger_import': {
-      const result = taskLedger.importTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-      });
-      return {
-        imported: result.imported,
-        preserved: result.preserved,
-        deleted: result.deleted,
-        imported_changes: result.imported_changes,
-        preserved_changes: result.preserved_changes,
-        imported_baseline: result.imported_baseline,
-        preserved_baseline: result.preserved_baseline,
-        generation: result.generation,
-        state_digest: result.state_digest,
-        requires_plan_revalidation: result.requires_plan_revalidation,
-        requires_baseline_revalidation: result.requires_baseline_revalidation,
-        already_current: result.already_current,
-      };
-    }
-    case 'plan.export': {
-      const rootDir = ctx.rootDir || process.cwd();
-      const change = changes.readChange(db, input.change_id);
-      if (!change) {
-        const err = new Error(`change ${input.change_id} not found`);
-        err.code = 'CHANGE_NOT_FOUND';
-        throw err;
-      }
-      if (!['active', 'blocked'].includes(change.status)) {
-        const err = new Error(`change ${change.id} is ${change.status}`);
-        err.code = 'CHANGE_NOT_MUTABLE';
-        throw err;
-      }
-      const tasks = ops.listTasks(db, { change_id: change.id });
-      if (tasks.length === 0) {
-        const err = new Error('no tasks to plan');
-        err.code = 'NO_TASKS';
-        throw err;
-      }
-      const context = contextSpine.validateContextSnapshot(db, {
-        change_id: change.id,
-        task_id: null,
-        role: 'plan',
-        gate: 'planning',
-      }, { rootDir });
-      if (!context.snapshot || context.blockers.length > 0) {
-        const err = new Error('plan export requires a current planning Context Manifest');
-        err.code = context.snapshot ? 'PLAN_CONTEXT_STALE' : 'PLAN_CONTEXT_REQUIRED';
-        err.details = { blockers: context.blockers };
-        throw err;
-      }
-      const plan = planStore.buildPlan(tasks, { changeId: change.id });
-      const planRun = db.prepare(
-        `SELECT id FROM workflow_runs
-         WHERE kind = 'plan' AND change_id = ? AND task_id IS NULL
-           AND status IN ('active', 'blocked', 'ready')
-         ORDER BY started_at DESC, rowid DESC LIMIT 1`,
-      ).get(change.id);
-      const owner = { type: 'change', id: change.id };
-      const contextArtifact = db.prepare(
-        `SELECT id FROM artifacts
-         WHERE path = ? AND status <> 'archived'
-         ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
-      ).get(context.snapshot.manifest_path);
-      const publication = planStore.prepareChangePlanPublication(plan, {
-        rootDir,
-        change,
-        tasks,
-        context: {
-          snapshot_id: context.snapshot.id,
-          manifest_path: context.snapshot.manifest_path,
-          manifest_digest: context.snapshot.manifest_hash,
-        },
-      });
-      const artifactInputs = publication.artifacts.map(({ kind, path: file, digest }) => ({
-        kind,
-        file,
-        digest,
-        input: {
-          owner_type: owner.type,
-          owner_id: owner.id,
-          kind,
-          path: path.relative(rootDir, file),
-          source_refs: [
-            { type: 'change', id: change.id, relation: 'planned_for' },
-            ...(contextArtifact
-              ? [{ type: 'artifact', id: contextArtifact.id, relation: 'compiled_from' }]
-              : []),
-            ...tasks.map((task) => ({
-              type: 'task', id: task.id, relation: 'compiled_from_task_contract',
-            })),
-          ],
-          consumer_refs: planRun
-            ? [{ type: 'workflow', id: planRun.id, relation: 'verified_by' }]
-            : [],
-          provenance: {
-            writer: 'plan.export',
-            workflow_run_id: planRun?.id || null,
-            publication_transaction_id: publication.transaction_id,
-          },
-          metadata: {
-            context_snapshot_id: context.snapshot.id,
-            context_digest: context.snapshot.manifest_hash,
-            terminal_role: !planRun,
-          },
-        },
-      }));
-      try {
-        ops.tx(db, () => {
-          const preflight = artifactInputs.map((artifact) => (
-            artifactRegistry.preflightArtifactPublication(
-              db, artifact.input, { rootDir },
-            )
-          ));
-          publication.publish();
-          const recorded = artifactInputs.map((artifact, index) => (
-            artifactRegistry.recordArtifactInTx(db, {
-              ...artifact.input,
-              id: preflight[index].artifact_id || undefined,
-              expected_before_digest: preflight[index].expected_before_digest,
-              content_digest: artifact.digest,
-            }, { rootDir })
-          ));
-          ops.appendEventInTx(db, {
-            type: 'plan_exported',
-            change_id: change.id,
-            payload: {
-              change_id: change.id,
-              plan_path: publication.plan_path,
-              plan_md_path: publication.plan_md_path,
-              publication_transaction_id: publication.transaction_id,
-              wave_count: plan.waves.length,
-            },
-          });
-          return recorded;
-        });
-      } catch (error) {
-        const rollback = publication.rollback();
-        const failure = rollback?.rolled_back === false
-          ? planStore.planRecoveryRequiredError(
-            error,
-            rollback,
-            publication.transaction_id,
-          )
-          : error;
-        if (failure.code === 'PLAN_RECOVERY_REQUIRED') {
-          const issue = failure.details?.rollback_issue
-            || failure.details?.issue
-            || {
-              code: failure.cause?.code || 'PLAN_RECOVERY_FAILED',
-              message: failure.cause?.message || failure.message,
-            };
-          ctx.markPlanRecoveryRequired?.({
-            recovered: 0,
-            finalized: 0,
-            pending: 1,
-            issues: [issue],
-          });
-        }
-        throw failure;
-      }
-      try {
-        publication.commit();
-      } catch (error) {
-        const issue = error.details?.issue || {
-          code: error.cause?.code || 'PLAN_RECOVERY_FAILED',
-          message: error.cause?.message || error.message,
-        };
-        ctx.markPlanRecoveryRequired?.({
-          recovered: 0,
-          finalized: 0,
-          pending: 1,
-          issues: [issue],
-        });
-        // The registry and target bytes committed atomically before cleanup.
-        // The remaining journal is still authoritative recovery work, so the
-        // caller must see a typed failure and later mutations must stop.
-        throw error;
-      }
-      return {
-        plan_path: publication.plan_path,
-        plan_md_path: publication.plan_md_path,
-        wave_count: plan.waves.length,
-      };
-    }
-    case 'plan.get': {
-      const rootDir = ctx.rootDir || process.cwd();
-      const change = changes.readChange(db, input.change_id);
-      if (!change) {
-        const err = new Error(`change ${input.change_id} not found`);
-        err.code = 'CHANGE_NOT_FOUND';
-        throw err;
-      }
-      const loaded = planStore.loadChangePlanArtifact(rootDir, change, {
-        db,
-        strict: true,
-      });
-      if (!loaded) {
-        const err = new Error('no plan has been computed yet');
-        err.code = 'NO_PLAN';
-        throw err;
-      }
-      return { plan: planStore.selectSection(loaded, input.section) };
-    }
-    case 'baseline.start': {
-      return {
-        baseline: baselines.startBaseline(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'baseline.record': {
-      return {
-        baseline: baselines.recordBaseline(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'baseline.get': {
-      const baseline = baselines.readBaseline(db, input.id);
-      if (!baseline) {
-        const err = new Error(input.id ? `baseline ${input.id} not found` : 'current baseline not found');
-        err.code = 'BASELINE_NOT_FOUND';
-        throw err;
-      }
-      return {
-        baseline,
-        health: baselines.inspectBaseline(db, {
-          rootDir: ctx.rootDir || process.cwd(), id: input.id,
-        }),
-      };
-    }
-    case 'baseline.converge': {
-      const result = baselines.convergeBaseline(
-        db, input, { rootDir: ctx.rootDir || process.cwd() },
-      );
-      if (result.ready) {
-        taskLedger.publishTaskLedger(db, {
-          rootDir: ctx.rootDir || process.cwd(),
-          reason: 'baseline_converged',
-        });
-      }
-      return result;
-    }
-    case 'change.create': {
-      const { randomUUID } = require('node:crypto');
-      const id = input.id || `chg-${randomUUID().slice(0, 12)}`;
-      const result = changes.createChange(
-        db,
-        { ...input, id },
-        { rootDir: ctx.rootDir || process.cwd() },
-      );
-      taskLedger.publishTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-        reason: 'change_created',
-      });
-      return result;
-    }
-    case 'change.update': {
-      const change = changes.updateChange(
-        db, input.id, input.patch || {}, { rootDir: ctx.rootDir || process.cwd() },
-      );
-      taskLedger.publishTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-        reason: 'change_updated',
-      });
-      return {
-        ok: true,
-        change,
-      };
-    }
-    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: {
-          ...change,
-          learning_candidates: changes.listSpecLearning(db, change.id),
-        },
-      };
-    }
-    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.breadcrumb': {
-      return {
-        breadcrumb: changes.readBreadcrumb(
-          db, input || {}, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'change.learning_propose': {
-      return {
-        candidate: changes.proposeSpecLearning(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'change.learning_resolve': {
-      return {
-        candidate: changes.resolveSpecLearning(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'change.converge': {
-      const result = changes.convergeChange(
-        db, input, { rootDir: ctx.rootDir || process.cwd() },
-      );
-      taskLedger.publishTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-        reason: 'change_converged',
-      });
-      return result;
-    }
-    case 'change.archive': {
-      const result = changes.archiveChange(
-        db, input, { rootDir: ctx.rootDir || process.cwd() },
-      );
-      taskLedger.publishTaskLedger(db, {
-        rootDir: ctx.rootDir || process.cwd(),
-        reason: 'change_archived',
-      });
-      return result;
-    }
-    case 'change.delta': {
-      return changes.recordDelta(db, input, { rootDir: ctx.rootDir || process.cwd() });
-    }
-    case 'change.documentation_reconcile': {
-      return changes.recordDocumentationReconciliation(
-        db, input, { rootDir: ctx.rootDir || process.cwd() },
-      );
-    }
-    case 'decision.thread_start': {
-      return { thread: decisions.startDecisionThread(db, input) };
-    }
-    case 'decision.get': {
-      const thread = decisions.readDecisionThread(db, input.id);
-      if (!thread) {
-        const error = new Error(`decision thread ${input.id} not found`);
-        error.code = 'DECISION_THREAD_NOT_FOUND';
-        throw error;
-      }
-      return { thread };
-    }
-    case 'decision.list': {
-      const threads = decisions.listDecisionThreads(db, input || {});
-      return { threads, count: threads.length };
-    }
-    case 'decision.open': {
-      return { thread: decisions.openDecision(db, input) };
-    }
-    case 'decision.resolve': {
-      return { thread: decisions.resolveDecision(db, input) };
-    }
-    case 'decision.delegate': {
-      return { thread: decisions.delegateDecision(db, input) };
-    }
-    case 'decision.defer': {
-      return { thread: decisions.deferDecision(db, input) };
-    }
-    case 'decision.supersede': {
-      return { thread: decisions.supersedeDecision(db, input) };
-    }
-    case 'decision.complete': {
-      return {
-        thread: decisions.completeDecisionThread(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'decision.checkpoint': {
-      return {
-        thread: decisions.checkpointDecisionThread(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'workflow.start': {
-      return {
-        workflow: workflows.startWorkflow(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'workflow.get': {
-      const workflow = workflows.readWorkflow(
-        db, input.id, { rootDir: ctx.rootDir || process.cwd() },
-      );
-      if (!workflow) {
-        const error = new Error(`workflow ${input.id} not found`);
-        error.code = 'WORKFLOW_NOT_FOUND';
-        throw error;
-      }
-      return { workflow };
-    }
-    case 'workflow.list': {
-      const rows = workflows.listWorkflows(
-        db, input || {}, { rootDir: ctx.rootDir || process.cwd() },
-      );
-      return { workflows: rows, count: rows.length };
-    }
-    case 'workflow.step': {
-      return {
-        workflow: workflows.recordWorkflowStep(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'workflow.revise': {
-      return {
-        workflow: workflows.reviseWorkflow(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'workflow.supersede': {
-      return workflows.supersedeWorkflow(
-        db, input, { rootDir: ctx.rootDir || process.cwd() },
-      );
-    }
-    case 'workflow.complete': {
-      return {
-        workflow: workflows.completeWorkflow(
-          db, input, { rootDir: ctx.rootDir || process.cwd() },
-        ),
-      };
-    }
-    case 'artifact.record': {
-      return artifactRegistry.recordArtifact(
-        db, input, { rootDir: ctx.rootDir || process.cwd() },
-      );
-    }
-    case 'artifact.get': {
-      return { artifact: artifactRegistry.getArtifact(db, input) };
-    }
-    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}`);
-  }
-}
-
 function errorResponse(code, message, retriable = false, details = undefined) {
   const error = { code, message, retriable };
   if (details !== undefined) error.details = details;
@@ -957,16 +68,48 @@ function errorResponse(code, message, retriable = false, details = undefined) {
   };
 }
 
+function isInitializeCall(name, input = {}) {
+  return name === 'ultra.record'
+    && Array.isArray(input.entries)
+    && input.entries.length === 1
+    && input.entries[0]?.kind === 'baseline'
+    && input.entries[0]?.action === 'initialize';
+}
+
+function isMutation(name, input = {}) {
+  if (name === 'ultra.record' || name === 'ultra.checkpoint' || name === 'ultra.archive') {
+    return true;
+  }
+  if (name === 'ultra.sync') return input.action !== 'inspect';
+  if (name === 'ultra.session') {
+    return ['acquire', 'heartbeat', 'release'].includes(input.action);
+  }
+  return name === 'ultra.doctor' && input.repair === true;
+}
+
+function requiresTeamSync(name, input = {}) {
+  return name === 'ultra.record'
+    || name === 'ultra.checkpoint'
+    || name === 'ultra.archive'
+    || (name === 'ultra.session' && input.action === 'acquire');
+}
+
+function ownsTeamAuthorityInspection(name) {
+  return ['ultra.context', 'ultra.sync', 'ultra.doctor'].includes(name);
+}
+
 function startServer({
   dbPath,
   rootDir,
   sessionId = null,
   projectOnWrite = true,
   project = projector.projectAll,
+  runtime = process.env.UBP_RUNTIME || 'unknown',
 }) {
   let db = null;
-  let planRecovery = null;
   let authorityDbPath = path.resolve(dbPath);
+  let planRecovery = null;
+
   const markPlanRecoveryRequired = (details) => {
     planRecovery = {
       recovered: Number(details?.recovered || 0),
@@ -975,33 +118,31 @@ function startServer({
       issues: Array.isArray(details?.issues) ? details.issues : [],
     };
   };
-  const getDb = (toolName = null) => {
+
+  const getDb = (toolName, input = {}) => {
     if (!db) {
-      if (toolName === 'ultra.context') {
-        if (!fs.existsSync(authorityDbPath)) {
-          const error = new Error(
-            'Ultra authority is not initialized; invoke ultra-init before reading project context',
-          );
-          error.code = 'STATE_DB_MISSING';
-          throw error;
-        }
-        db = openStateDb(authorityDbPath);
-        ensureSchemaVersion(db);
-        assertStateAuthority(db, rootDir, { importTeamLedger: false });
-        return db;
-      }
       const projectPaths = runtimePaths.pathsFor(rootDir);
-      if ([projectPaths.legacyStateDbPath, projectPaths.stateDbPath].includes(authorityDbPath)) {
-        // The packaged launcher has no explicit DB override. Its default path
-        // is the future canonical runtime location, which can legitimately be
-        // absent while a legacy project still owns its project-level DB. Admit and
-        // migrate that project before applying configured-authority binding.
+      const usesProjectAuthority = [
+        projectPaths.legacyStateDbPath,
+        projectPaths.stateDbPath,
+      ].includes(authorityDbPath);
+      const projectExists = fs.existsSync(path.join(rootDir, '.ultra'));
+
+      if (!projectExists) {
+        const error = new Error(
+          'Ultra authority is not initialized; invoke ultra-init before using project tools',
+        );
+        error.code = 'STATE_DB_MISSING';
+        throw error;
+      }
+
+      if (usesProjectAuthority) {
         authorityDbPath = runtimePaths.ensureRuntimeState(rootDir, {
-          admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(rootDir),
+          admitStorageBoundary: () => (
+            gitBootstrap.ensureExistingProjectStorageBoundary(rootDir)
+          ),
         }).stateDbPath;
       } else {
-        // Only a real external/task-linked override reaches binding
-        // validation. It may never invent or borrow project authority.
         runtimePaths.locateStateDb(rootDir, {
           env: { UBP_DB_PATH: authorityDbPath },
         });
@@ -1009,29 +150,51 @@ function startServer({
           env: { UBP_DB_PATH: authorityDbPath },
           allowConfiguredRuntimeLink: true,
           migrateState: false,
-          admitStorageBoundary: () => gitBootstrap.ensureExistingProjectStorageBoundary(rootDir),
+          admitStorageBoundary: () => (
+            gitBootstrap.ensureExistingProjectStorageBoundary(rootDir)
+          ),
         });
       }
-      db = initStateDb(authorityDbPath).db;
-      const teamSync = assertStateAuthority(db, rootDir, { importTeamLedger: true });
-      if (teamSync?.status === 'imported') {
-        runtimeState.enqueueProjection(db, {
-          tool_name: 'task.ledger_import',
-        });
-        runtimeState.processProjectionJobs(db, {
-          rootDir,
-          project,
-          limit: 500,
+
+      if (['ultra.context', 'ultra.doctor'].includes(toolName)
+          && !fs.existsSync(authorityDbPath)) {
+        const error = new Error('Ultra runtime state is missing');
+        error.code = 'STATE_DB_MISSING';
+        throw error;
+      }
+
+      db = fs.existsSync(authorityDbPath)
+        ? openStateDb(authorityDbPath)
+        : initStateDb(authorityDbPath).db;
+      ensureSchemaVersion(db);
+
+      if (!ownsTeamAuthorityInspection(toolName)) {
+        const teamSync = assertStateAuthority(db, rootDir, {
+          importTeamLedger: toolName !== 'ultra.context',
         });
+        if (teamSync?.status === 'imported') {
+          const job = runtimeState.enqueueProjection(db, { tool_name: 'ultra.sync' });
+          runtimeState.processProjectionJobs(db, {
+            rootDir,
+            project,
+            limit: 500,
+          });
+          if (!job?.id) {
+            const error = new Error('team authority import projection was not scheduled');
+            error.code = 'STATE_CORRUPT';
+            throw error;
+          }
+        }
       }
       planRecovery = planStore.recoverPlanPublications(db, { rootDir });
     }
-      if (!['system.doctor', 'ultra.doctor'].includes(toolName)
-      && (planRecovery?.pending > 0 || planRecovery?.issues?.length > 0)) {
+
+    if (!['ultra.context', 'ultra.doctor'].includes(toolName)
+        && (planRecovery?.pending > 0 || planRecovery?.issues?.length > 0)) {
       planRecovery = planStore.recoverPlanPublications(db, { rootDir });
       if (planRecovery.pending > 0 || planRecovery.issues.length > 0) {
         const error = new Error(
-          'plan publication recovery is incomplete; run system.doctor with repair=true',
+          'plan publication recovery is incomplete; run ultra.doctor with repair=true',
         );
         error.code = 'PLAN_RECOVERY_REQUIRED';
         error.details = planRecovery;
@@ -1041,14 +204,13 @@ function startServer({
     return db;
   };
 
-  const tools = loadRegisteredTools();
-  const publicTools = tools.filter((tool) => PUBLIC_TOOLS.includes(tool.name));
+  const toolContracts = loadToolContracts();
   const ajv = buildAjv();
   const inputValidators = new Map();
   const outputValidators = new Map();
-  for (const t of tools) {
-    inputValidators.set(t.name, ajv.compile(t.input_schema));
-    outputValidators.set(t.name, ajv.compile(t.output_schema));
+  for (const tool of toolContracts) {
+    inputValidators.set(tool.name, ajv.compile(tool.input_schema));
+    outputValidators.set(tool.name, ajv.compile(tool.output_schema));
   }
 
   const server = new Server(
@@ -1057,156 +219,113 @@ function startServer({
   );
 
   server.setRequestHandler('tools/list', async () => ({
-    tools: publicTools.map((t) => ({
-      name: t.name,
-      description: t.description,
-      inputSchema: t.input_schema,
+    tools: toolContracts.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.input_schema,
     })),
   }));
 
   server.setRequestHandler('tools/call', async (request) => {
-    const { name, arguments: args = {} } = request.params;
-    const toolStart = Date.now();
+    const { name, arguments: input = {} } = request.params;
+    const startedAt = Date.now();
     let toolError = null;
+    let toolDb = null;
 
     const emitTelemetry = () => {
-      if (!db) return;
+      if (!toolDb) return;
       try {
-        telemetry.appendTelemetry(db, {
+        telemetry.appendTelemetry(toolDb, {
           event_type: 'tool_call',
           tool_name: name,
-          session_id: (args && args.sid) || null,
+          session_id: input.scope?.sid || null,
           rootDir,
           payload: {
-            duration_ms: Date.now() - toolStart,
-            task_id: (args && (args.task_id || args.id)) || null,
+            duration_ms: Date.now() - startedAt,
+            task_id: input.scope?.task_id || null,
             error: toolError,
           },
         });
-      } catch (err) {
-        process.stderr.write(`telemetry warning: ${err.message}\n`);
+      } catch (error) {
+        process.stderr.write(`telemetry warning: ${error.message}\n`);
       }
     };
 
     if (!REGISTERED_TOOLS.includes(name)) {
-      toolError = 'UNKNOWN_TOOL';
-      emitTelemetry();
       return errorResponse('UNKNOWN_TOOL', `tool ${name} is not registered on this server`);
     }
     const validateInput = inputValidators.get(name);
-    if (!validateInput(args)) {
-      toolError = 'VALIDATION_ERROR';
-      emitTelemetry();
+    if (!validateInput(input)) {
       return errorResponse('VALIDATION_ERROR', ajv.errorsText(validateInput.errors));
     }
 
-    let result;
-    let toolDb = null;
     try {
-      toolDb = (STATELESS_TOOLS.has(name) || isStatelessPublicCall(name, args))
-        ? null
-        : getDb(name);
-      if (toolDb) assertStateAuthority(toolDb, rootDir);
-      if (toolDb && TEAM_LEDGER_SYNC_TOOLS.has(name)) {
+      toolDb = isInitializeCall(name, input) ? null : getDb(name, input);
+      if (toolDb && requiresTeamSync(name, input)) {
         taskLedger.syncTaskLedger(toolDb, { rootDir });
       }
-      const callContext = {
+      const result = await ultraFacade.dispatch(name, input, toolDb, {
         rootDir,
+        runtime,
         sessionId,
         projector: project,
         markPlanRecoveryRequired,
-      };
-      const callLegacy = async (legacyName, legacyArgs = {}) => {
-        if (!LEGACY_TOOLS.includes(legacyName)) {
-          const error = new Error(`legacy operation ${legacyName} is not supported`);
-          error.code = 'ULTRA_RECORD_OPERATION_UNSUPPORTED';
-          throw error;
-        }
-        const validateLegacyInput = inputValidators.get(legacyName);
-        if (!validateLegacyInput(legacyArgs)) {
-          const error = new Error(ajv.errorsText(validateLegacyInput.errors));
-          error.code = 'VALIDATION_ERROR';
-          error.details = validateLegacyInput.errors;
-          throw error;
-        }
-        const legacyResult = await dispatchTool(
-          legacyName,
-          legacyArgs,
+      });
+      if (name === 'ultra.doctor' && input.repair === true) {
+        planRecovery = result.repair?.plan_publications || null;
+      }
+
+      let runtimeMeta = null;
+      if (toolDb && projectOnWrite && isMutation(name, input)) {
+        const job = runtimeState.enqueueProjection(toolDb, { tool_name: name });
+        const processed = runtimeState.processProjectionJobs(
           toolDb,
-          callContext,
+          { rootDir, project, limit: 500 },
+        );
+        const own = processed.jobs.find((item) => item.id === job.id);
+        runtimeMeta = {
+          state_commit: 'committed',
+          projection_status: own?.status || 'failed',
+          projection_job_id: job.id,
+        };
+        if (own?.incident_id) runtimeMeta.incident_id = own.incident_id;
+      }
+
+      const validateOutput = outputValidators.get(name);
+      if (!validateOutput(result)) {
+        toolError = 'OUTPUT_SCHEMA_DRIFT';
+        emitTelemetry();
+        return errorResponse(
+          'OUTPUT_SCHEMA_DRIFT',
+          ajv.errorsText(validateOutput.errors),
+          false,
+          runtimeMeta ? { _ultra: runtimeMeta } : undefined,
         );
-        const validateLegacyOutput = outputValidators.get(legacyName);
-        if (!validateLegacyOutput(legacyResult)) {
-          const error = new Error(ajv.errorsText(validateLegacyOutput.errors));
-          error.code = 'OUTPUT_SCHEMA_DRIFT';
-          error.details = validateLegacyOutput.errors;
-          throw error;
-        }
-        return legacyResult;
-      };
-      result = PUBLIC_TOOLS.includes(name)
-        ? await ultraFacade.dispatch(name, args, toolDb, { ...callContext, callLegacy })
-        : await dispatchTool(name, args, toolDb, callContext);
-      if (['system.doctor', 'ultra.doctor'].includes(name) && args.repair === true) {
-        planRecovery = result.repair?.plan_publications || null;
       }
-    } catch (err) {
-      const code = err.code || (err instanceof ops.StateOpsError ? err.code : 'STATE_DB_ERROR');
-      toolError = code;
-      emitTelemetry();
-      return errorResponse(code, err.message, !!err.retriable, err.details);
-    }
 
-    let runtimeMeta = null;
-    const shouldProject = toolDb
-      && projectOnWrite
-      && MUTATING_TOOLS.has(name)
-      && !(name === 'task.ledger_import' && result.already_current === true);
-    if (shouldProject) {
-      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 && ['system.doctor', 'ultra.doctor'].includes(name) && args.repair === true) {
-      runtimeMeta = {
-        state_commit: 'committed',
-        projection_status: result.checks.projections.status === 'pass' ? 'completed' : 'failed',
-        backup_path: result.backup_path,
+      emitTelemetry();
+      const visible = runtimeMeta ? { ...result, _ultra: runtimeMeta } : result;
+      return {
+        content: [{ type: 'text', text: JSON.stringify(visible) }],
+        structuredContent: result,
+        ...(runtimeMeta ? { _meta: { ultra: runtimeMeta } } : {}),
       };
-    }
-
-    const validateOutput = outputValidators.get(name);
-    if (!validateOutput(result)) {
-      toolError = 'OUTPUT_SCHEMA_DRIFT';
+    } catch (error) {
+      toolError = error.code || 'STATE_DB_ERROR';
       emitTelemetry();
-      const response = errorResponse(
-        'OUTPUT_SCHEMA_DRIFT',
-        ajv.errorsText(validateOutput.errors),
-        false,
-        runtimeMeta ? { _ultra: runtimeMeta } : undefined,
+      return errorResponse(
+        toolError,
+        error.message,
+        Boolean(error.retriable),
+        error.details,
       );
-      if (runtimeMeta) response._meta = { ultra: runtimeMeta };
-      return response;
     }
-
-    emitTelemetry();
-    const visible = runtimeMeta ? { ...result, _ultra: runtimeMeta } : result;
-    return {
-      content: [{ type: 'text', text: JSON.stringify(visible) }],
-      structuredContent: result,
-      ...(runtimeMeta ? { _meta: { ultra: runtimeMeta } } : {}),
-    };
   });
 
   return {
     server,
     get db() { return db; },
-    tools,
+    tools: toolContracts,
     async close() { closeStateDb(db); },
   };
 }
@@ -1215,17 +334,15 @@ async function main() {
   const rootDir = process.env.UBP_ROOT_DIR
     ? path.resolve(process.env.UBP_ROOT_DIR)
     : path.resolve('.');
-  // Keep tools/list side-effect free. Root/layout validation happens inside the
-  // first state-backed tool call so clients receive a typed MCP error instead
-  // of a transport-level startup failure.
-  const configuredDb = typeof process.env.UBP_DB_PATH === 'string'
-    ? process.env.UBP_DB_PATH.trim()
-    : '';
+  const configuredDb = String(process.env.UBP_DB_PATH || '').trim();
   const dbPath = configuredDb
     ? path.resolve(configuredDb)
     : runtimePaths.pathsFor(rootDir).stateDbPath;
-  const sessionId = process.env.UBP_SESSION_ID || null;
-  const handle = startServer({ dbPath, rootDir, sessionId });
+  const handle = startServer({
+    dbPath,
+    rootDir,
+    sessionId: process.env.UBP_SESSION_ID || null,
+  });
   const transport = new StdioServerTransport();
   await handle.server.connect(transport);
   const cleanup = () => handle.close().finally(() => process.exit(0));
@@ -1251,37 +368,29 @@ function appendHookLifecycleEvent({ rootDir, action, hookInput = {} } = {}) {
   const db = openStateDb(dbPath);
   try {
     ensureSchemaVersion(db);
-    const workflow = db.prepare(
-      `SELECT change_id, task_id FROM workflow_runs
-       WHERE status IN ('active', 'blocked', 'ready') AND change_id IS NOT NULL
-       ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
-    ).get();
-    if (!workflow) return { recorded: false, reason: 'NO_ACTIVE_WORKFLOW' };
     const change = db.prepare(
       `SELECT id FROM changes
-       WHERE id = ? AND status IN ('active', 'blocked', 'ready')`,
-    ).get(workflow.change_id);
+       WHERE status = 'active'
+       ORDER BY updated_at DESC, rowid DESC LIMIT 1`,
+    ).get();
     if (!change) return { recorded: false, reason: 'NO_ACTIVE_CHANGE' };
-    const task = workflow.task_id
-      ? db.prepare(
-        `SELECT id FROM tasks
-         WHERE id = ? AND change_id = ?
-           AND status IN ('in_progress', 'pending', 'blocked')`,
-      ).get(workflow.task_id, change.id)
-      : db.prepare(
-        `SELECT id FROM tasks WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
-         ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
-                  updated_at DESC, rowid DESC LIMIT 1`,
-      ).get(change.id);
+    const task = db.prepare(
+      `SELECT id FROM tasks
+       WHERE change_id = ? AND status IN ('in_progress', 'pending', 'blocked')
+       ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'blocked' THEN 1 ELSE 2 END,
+                updated_at DESC, rowid DESC LIMIT 1`,
+    ).get(change.id);
     const payload = {
       agent_id: hookMetadata(hookInput.agent_id),
       agent_type: hookMetadata(hookInput.agent_type),
       host_session_id: hookMetadata(hookInput.session_id, '', 256),
     };
+    const hookRuntime = hookMetadata(hookInput.runtime, '', 64) || null;
     ops.appendEvent(db, {
       type: action === 'start' ? 'subagent_started' : 'subagent_stopped',
       change_id: change.id,
       task_id: task?.id || null,
+      runtime: hookRuntime,
       payload,
     });
     return { recorded: true, change_id: change.id, task_id: task?.id || null };
@@ -1291,8 +400,8 @@ function appendHookLifecycleEvent({ rootDir, action, hookInput = {} } = {}) {
 }
 
 if (require.main === module) {
-  main().catch((err) => {
-    process.stderr.write(`mcp-server fatal: ${err.message}\n`);
+  main().catch((error) => {
+    process.stderr.write(`mcp-server fatal: ${error.message}\n`);
     process.exit(1);
   });
 }
@@ -1300,22 +409,10 @@ if (require.main === module) {
 module.exports = {
   main,
   startServer,
-  dispatchTool,
-  TASK_TOOLS,
-  SESSION_TOOLS,
-  PLAN_TOOLS,
-  BASELINE_TOOLS,
-  CHANGE_TOOLS,
-  WORKFLOW_TOOLS,
-  ARTIFACT_TOOLS,
-  SYSTEM_TOOLS,
   REGISTERED_TOOLS,
-  LEGACY_TOOLS,
   PUBLIC_TOOLS,
-  STATELESS_TOOLS,
-  MUTATING_TOOLS,
   appendHookLifecycleEvent,
   findProjectRoot: runtimePaths.findProjectRoot,
-  readProjectBreadcrumb,
-  renderProjectBreadcrumb,
+  readProjectContextEnvelope,
+  renderProjectContextEnvelope,
 };