ultra-builder-pro-cli 0.7.0 → 0.9.0

package/hooks/adapters/kimi.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Kimi Code wire adapter for Ultra Builder Pro lifecycle hooks.
+
+Kimi 0.26 uses snake_case JSON input compatible with the workflow hooks, but
+its output contract accepts only ``message`` plus an optional structured deny.
+This adapter preserves real projection/stop blocks, converts foreign context
+fields into Kimi messages, and fails open with diagnostic evidence.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+
+HOOK_ROOT = Path(__file__).resolve().parent.parent
+ALLOWED_FEATURES = {
+    "active_task_context.py",
+    "health_check.py",
+    "pre_stop_check.py",
+    "subagent_tracker.py",
+    "workflow_checkpoint.py",
+    "workflow_context.py",
+    "workflow_resume.py",
+}
+
+
+def normalize_input(payload: dict[str, Any]) -> dict[str, Any]:
+    """Add only the legacy aliases required by the shared workflow hooks."""
+    normalized = copy.deepcopy(payload)
+    agent_name = normalized.get("agent_name")
+    if isinstance(agent_name, str) and agent_name:
+        normalized.setdefault("agent_id", agent_name)
+        normalized.setdefault("agent_type", agent_name)
+    if normalized.get("tool_response") is not None and normalized.get("tool_output") is None:
+        normalized["tool_output"] = normalized["tool_response"]
+    return normalized
+
+
+def _text(value: Any) -> str:
+    return str(value).strip() if value is not None else ""
+
+
+def adapt_output(output: dict[str, Any], event: str) -> dict[str, Any]:
+    """Convert one legacy hook result to Kimi's exact structured schema."""
+    if not isinstance(output, dict):
+        return {}
+    specific = output.get("hookSpecificOutput")
+    specific = specific if isinstance(specific, dict) else {}
+
+    decision = specific.get("permissionDecision")
+    blocked = output.get("decision") == "block" or decision == "deny"
+    reason = (
+        _text(specific.get("permissionDecisionReason"))
+        or _text(output.get("reason"))
+        or f"Ultra {event} gate blocked continuation"
+    )
+    if blocked:
+        return {
+            "hookSpecificOutput": {
+                "message": reason,
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+
+    context = (
+        _text(specific.get("additionalContext"))
+        or _text(output.get("additionalContext"))
+        or _text(output.get("systemMessage"))
+        or _text(specific.get("message"))
+        or _text(output.get("message"))
+    )
+    advisory = _text(specific.get("permissionDecisionReason")) if decision == "ask" else ""
+    message = "\n\n".join(part for part in [advisory, context] if part)
+    return {"message": message} if message else {}
+
+
+def _parse_output(stdout: str) -> dict[str, Any]:
+    text = stdout.strip()
+    if not text:
+        return {}
+    try:
+        value = json.loads(text)
+    except json.JSONDecodeError:
+        return {"message": f"Ultra hook returned non-JSON output: {text[:500]}"}
+    return value if isinstance(value, dict) else {}
+
+
+def run_feature(feature: str, payload: dict[str, Any], feature_args: list[str]) -> dict[str, Any]:
+    if feature not in ALLOWED_FEATURES or Path(feature).name != feature:
+        return {"message": f"Ultra hook adapter refused unknown feature: {feature}"}
+    script = HOOK_ROOT / feature
+    if not script.is_file():
+        return {"message": f"Ultra hook feature is missing: {feature}"}
+
+    event = str(payload.get("hook_event_name") or "")
+    normalized = normalize_input(payload)
+    if feature == "workflow_resume.py" and event == "PostCompact":
+        normalized["hook_event_name"] = "SessionStart"
+        normalized["source"] = "compact"
+
+    env = os.environ.copy()
+    env["UBP_HOOK_RUNTIME"] = "kimi"
+    plugin_data = env.get("PLUGIN_DATA") or env.get("KIMI_PLUGIN_ROOT")
+    if plugin_data:
+        env["UBP_HOOK_DATA"] = plugin_data
+
+    cwd = normalized.get("cwd")
+    run_cwd = str(cwd) if isinstance(cwd, str) and Path(cwd).is_dir() else os.getcwd()
+    proc = subprocess.run(
+        [sys.executable, str(script), *feature_args],
+        input=json.dumps(normalized),
+        text=True,
+        capture_output=True,
+        cwd=run_cwd,
+        env=env,
+        timeout=30,
+        check=False,
+    )
+    if proc.stderr:
+        print(proc.stderr.rstrip(), file=sys.stderr)
+    if proc.returncode != 0:
+        return {
+            "message": (
+                f"Ultra hook {feature} failed with exit {proc.returncode}: "
+                f"{proc.stderr.strip()[:500]}"
+            )
+        }
+    return adapt_output(_parse_output(proc.stdout), event)
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        print(json.dumps({"message": "Ultra Kimi hook adapter requires a feature name"}))
+        return 0
+    feature = sys.argv[1]
+    feature_args = sys.argv[2:]
+    try:
+        payload = json.loads(sys.stdin.read() or "{}")
+        if not isinstance(payload, dict):
+            payload = {}
+    except json.JSONDecodeError as exc:
+        print(json.dumps({"message": f"Ultra hook input parse error: {exc}"}))
+        return 0
+    try:
+        output = run_feature(feature, payload, feature_args)
+    except subprocess.TimeoutExpired:
+        output = {"message": f"Ultra hook {feature} timed out"}
+    except Exception as exc:  # Kimi hooks are fail-open at this adapter boundary.
+        output = {"message": f"Ultra hook adapter error in {feature}: {exc}"}
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/workflow_checkpoint.py

@@ -11,6 +11,17 @@ from pathlib import Path
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
+def valid_workflow(state: object) -> bool:
+    return (
+        isinstance(state, dict)
+        and isinstance(state.get("command"), str)
+        and bool(state["command"].strip())
+        and state.get("step") is not None
+        and isinstance(state.get("status"), str)
+        and bool(state["status"].strip())
+    )
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -28,7 +39,10 @@ def main() -> None:
         except (OSError, json.JSONDecodeError) as exc:
             print(f"[workflow_checkpoint] cannot read {state_file}: {exc}", file=sys.stderr)
             break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+        if not valid_workflow(state):
+            print(f"[workflow_checkpoint] invalid workflow state in {state_file}", file=sys.stderr)
+            break
+        if state.get("status") in TERMINAL:
             break
         runtime_dir = root / ".ultra" / "runtime"
         runtime_dir.mkdir(parents=True, exist_ok=True)

package/hooks/workflow_resume.py

@@ -2,12 +2,82 @@
 """Restore only the current Ultra workflow boundary after compaction."""
 
 import json
+import os
 import sys
+import tempfile
+from datetime import datetime, timezone
 from pathlib import Path
 
 TERMINAL = {"committed", "completed", "done", "cancelled"}
 
 
+def valid_workflow(state: object) -> bool:
+    return (
+        isinstance(state, dict)
+        and isinstance(state.get("command"), str)
+        and bool(state["command"].strip())
+        and state.get("step") is not None
+        and isinstance(state.get("status"), str)
+        and bool(state["status"].strip())
+    )
+
+
+def read_json(file: Path, label: str):
+    if not file.is_file():
+        return None
+    try:
+        return json.loads(file.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"[workflow_resume] cannot read {label} {file}: {exc}", file=sys.stderr)
+        return None
+
+
+def parse_time(value: object):
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except ValueError:
+        return None
+
+
+def newest_time(file: Path, *values: object) -> datetime:
+    candidates = [parsed for value in values if (parsed := parse_time(value)) is not None]
+    try:
+        candidates.append(datetime.fromtimestamp(file.stat().st_mtime, tz=timezone.utc))
+    except OSError:
+        pass
+    return max(candidates, default=datetime.min.replace(tzinfo=timezone.utc))
+
+
+def load_checkpoint(file: Path):
+    checkpoint = read_json(file, "checkpoint")
+    if checkpoint is None:
+        return None
+    if not isinstance(checkpoint, dict):
+        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
+        return None
+    captured_at = checkpoint.get("captured_at")
+    workflow = checkpoint.get("workflow")
+    if checkpoint.get("schema") != 1 or parse_time(captured_at) is None or not valid_workflow(workflow):
+        print(f"[workflow_resume] invalid checkpoint schema in {file}", file=sys.stderr)
+        return None
+    return checkpoint
+
+
+def restore_state(file: Path, state: dict) -> None:
+    file.parent.mkdir(parents=True, exist_ok=True)
+    fd, temp_name = tempfile.mkstemp(prefix="workflow-state.", suffix=".json", dir=file.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(state, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+        os.replace(temp_name, file)
+    finally:
+        if os.path.exists(temp_name):
+            os.unlink(temp_name)
+
+
 def main() -> None:
     try:
         data = json.loads(sys.stdin.read() or "{}")
@@ -18,21 +88,40 @@ def main() -> None:
     start = Path(data.get("cwd") or Path.cwd()).resolve()
     for root in (start, *start.parents):
         state_file = root / ".ultra" / "workflow-state.json"
-        if not state_file.is_file():
+        checkpoint_file = root / ".ultra" / "runtime" / "checkpoint.json"
+        if not state_file.is_file() and not checkpoint_file.is_file():
             continue
-        try:
-            state = json.loads(state_file.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError) as exc:
-            print(f"[workflow_resume] cannot read {state_file}: {exc}", file=sys.stderr)
+        live = read_json(state_file, "workflow state")
+        if live is not None and not valid_workflow(live):
+            print(f"[workflow_resume] invalid workflow state in {state_file}", file=sys.stderr)
+            live = None
+        if live is not None and live.get("status") in TERMINAL:
             break
-        if not isinstance(state, dict) or state.get("status") in TERMINAL:
+        checkpoint = load_checkpoint(checkpoint_file)
+        checkpoint_state = checkpoint["workflow"] if checkpoint is not None else None
+        if checkpoint_state is not None and checkpoint_state.get("status") in TERMINAL:
+            checkpoint_state = None
+
+        source = ".ultra/workflow-state.json"
+        state = live
+        if checkpoint_state is not None:
+            checkpoint_time = newest_time(
+                checkpoint_file, checkpoint_state.get("ts"), checkpoint.get("captured_at")
+            )
+            live_time = newest_time(state_file, live.get("ts")) if live is not None else None
+            if live_time is None or checkpoint_time >= live_time:
+                state = checkpoint_state
+                source = ".ultra/runtime/checkpoint.json"
+                restore_state(state_file, state)
+        if state is None:
             break
         text = (
             "[Ultra workflow resumed] "
             f"command={state.get('command', 'unknown')}; "
             f"task={state.get('task_id', state.get('task', 'unknown'))}; "
             f"step={state.get('step', 'unknown')}; status={state.get('status', 'active')}. "
-            "Continue from .ultra/workflow-state.json and verify state through .ultra/state.db."
+            f"source={source}. Continue from the recovered workflow boundary and verify "
+            "task/session/change state through .ultra/state.db."
         )
         event = data.get("hook_event_name", "SessionStart")
         if event == "SessionStart":

package/mcp-server/lib/change-workflow.cjs

@@ -26,6 +26,13 @@ const REQUIRED_EVIDENCE = Object.freeze({
   major: ['diff', 'tests', 'spec', 'docs', 'review'],
   incident: ['diagnosis', 'diff', 'tests'],
 });
+const INCIDENT_DIAGNOSIS_SECTIONS = Object.freeze([
+  { heading: 'Reproduction', key: 'reproduction' },
+  { heading: 'Hypotheses', key: 'hypotheses' },
+  { heading: 'Root cause', key: 'root-cause' },
+  { heading: 'Regression test', key: 'regression-test' },
+  { heading: 'Recovery', key: 'recovery' },
+]);
 
 class ChangeWorkflowError extends Error {
   constructor(code, message, details) {
@@ -149,6 +156,53 @@ function writeIntent(file, change) {
   fs.writeFileSync(file, `${lines.join('\n')}\n`);
 }
 
+function writeIncidentDiagnosis(file, change) {
+  const lines = [
+    `# Incident diagnosis: ${change.title}`,
+    '',
+    ...INCIDENT_DIAGNOSIS_SECTIONS.flatMap(({ heading }) => [`## ${heading}`, '', '']),
+  ];
+  fs.writeFileSync(file, `${lines.join('\n')}\n`);
+}
+
+function readMarkdownSections(text) {
+  const sections = new Map();
+  let current = null;
+  for (const line of String(text).split(/\r?\n/)) {
+    const heading = /^##\s+(.+?)\s*$/.exec(line);
+    if (heading) {
+      current = heading[1].trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+      if (!sections.has(current)) sections.set(current, []);
+      continue;
+    }
+    if (current) sections.get(current).push(line);
+  }
+  return new Map([...sections].map(([key, lines]) => [key, lines.join('\n').trim()]));
+}
+
+function inspectIncidentDiagnosis(change, artifactDir, rootDir) {
+  if (change.kind !== 'incident') return { blockers: [], artifact: null };
+  const diagnosisPath = path.join(artifactDir, 'diagnosis.md');
+  if (!fs.existsSync(diagnosisPath)) {
+    return { blockers: ['DIAGNOSIS_ARTIFACT_MISSING'], artifact: null };
+  }
+  const content = fs.readFileSync(diagnosisPath);
+  const sections = readMarkdownSections(content.toString('utf8'));
+  const blockers = INCIDENT_DIAGNOSIS_SECTIONS
+    .filter(({ key }) => !sections.get(key) || sections.get(key).length < 3)
+    .map(({ key }) => `DIAGNOSIS_SECTION_MISSING:${key}`);
+  return {
+    blockers,
+    artifact: {
+      change_id: change.id,
+      kind: 'diagnosis',
+      artifactPath: path.relative(rootDir, diagnosisPath),
+      contentHash: crypto.createHash('sha256').update(content).digest('hex'),
+      metadata: { required_sections: INCIDENT_DIAGNOSIS_SECTIONS.map(({ key }) => key) },
+    },
+  };
+}
+
 function upsertArtifact(db, { change_id, task_id = null, kind, artifactPath, contentHash, metadata }) {
   const id = `art-${crypto.randomUUID().slice(0, 12)}`;
   db.prepare(
@@ -275,6 +329,17 @@ function createChange(db, input, { rootDir = process.cwd() } = {}) {
         change_id: row.id, kind: 'intent', artifactPath: path.relative(rootDir, intentPath),
         contentHash: crypto.createHash('sha256').update(fs.readFileSync(intentPath)).digest('hex'),
       });
+      if (row.kind === 'incident') {
+        const diagnosisPath = path.join(artifactDir, 'diagnosis.md');
+        writeIncidentDiagnosis(diagnosisPath, row);
+        upsertArtifact(db, {
+          change_id: row.id,
+          kind: 'diagnosis',
+          artifactPath: path.relative(rootDir, diagnosisPath),
+          contentHash: crypto.createHash('sha256').update(fs.readFileSync(diagnosisPath)).digest('hex'),
+          metadata: { required_sections: INCIDENT_DIAGNOSIS_SECTIONS.map(({ key }) => key) },
+        });
+      }
       ops.appendEventInTx(db, {
         type: 'change_created', change_id: row.id,
         payload: { kind: row.kind, artifact_root: row.artifact_root },
@@ -410,6 +475,8 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   }
 
   const artifactDir = path.resolve(rootDir, change.artifact_root);
+  const diagnosis = inspectIncidentDiagnosis(change, artifactDir, rootDir);
+  for (const blocker of diagnosis.blockers) blockers.add(blocker);
   if (['standard', 'major'].includes(change.kind)) {
     if (filesUnder(path.join(artifactDir, 'delta')).length === 0) blockers.add('SPEC_DELTA_MISSING');
     if (!fs.existsSync(path.join(artifactDir, 'plan.md'))) blockers.add('CHANGE_PLAN_MISSING');
@@ -434,6 +501,7 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
     ops.tx(db, () => {
       db.prepare("UPDATE changes SET status = 'blocked', updated_at = ? WHERE id = ?")
         .run(nowIso(), change.id);
+      if (diagnosis.artifact) upsertArtifact(db, diagnosis.artifact);
       ops.appendEventInTx(db, {
         type: 'change_blocked', change_id: change.id, payload: { blockers: blockerList },
       });
@@ -452,6 +520,7 @@ function convergeChange(db, input, { rootDir = process.cwd() } = {}) {
   ops.tx(db, () => {
     db.prepare("UPDATE changes SET status = 'ready', updated_at = ? WHERE id = ?")
       .run(nowIso(), change.id);
+    if (diagnosis.artifact) upsertArtifact(db, diagnosis.artifact);
     upsertArtifact(db, {
       change_id: change.id, kind: 'verification', artifactPath: path.relative(rootDir, verificationPath),
       contentHash: crypto.createHash('sha256').update(fs.readFileSync(verificationPath)).digest('hex'),

package/mcp-server/lib/change-workflow.test.cjs

@@ -38,6 +38,14 @@ function standardEvidence() {
   ];
 }
 
+function incidentEvidence() {
+  return [
+    { category: 'diagnosis', status: 'pass', evidence: 'Structured diagnosis artifact reviewed.' },
+    { category: 'diff', status: 'pass', evidence: 'Root-cause fix diff reviewed.' },
+    { category: 'tests', status: 'pass', evidence: 'Regression test reproduces then verifies the fix.' },
+  ];
+}
+
 test('createChange persists a change and an inspectable external-provider context manifest', () => {
   const fx = fixture();
   try {
@@ -257,3 +265,82 @@ test('updateChange rejects whitespace-only title or intent outside the MCP bound
     cleanup(fx);
   }
 });
+
+test('incident changes create a durable structured diagnosis artifact', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-incident-diagnosis', title: 'Diagnose runtime failure', kind: 'incident',
+      intent: 'Reproduce and fix the runtime failure at its root cause.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal runtime repair.' },
+    }, { rootDir: fx.rootDir });
+
+    const diagnosisPath = path.join(path.dirname(created.intent_path), 'diagnosis.md');
+    assert.ok(fs.existsSync(diagnosisPath));
+    const text = fs.readFileSync(diagnosisPath, 'utf8');
+    for (const heading of ['Reproduction', 'Hypotheses', 'Root cause', 'Regression test', 'Recovery']) {
+      assert.match(text, new RegExp(`^## ${heading}$`, 'm'));
+    }
+    const artifact = fx.db.prepare(
+      "SELECT kind, path, content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-diagnosis');
+    assert.equal(artifact.kind, 'diagnosis');
+    assert.match(artifact.content_hash, /^[0-9a-f]{64}$/);
+    assert.equal(path.join(fx.rootDir, artifact.path), diagnosisPath);
+  } finally {
+    cleanup(fx);
+  }
+});
+
+test('incident convergence requires every structured diagnosis section and refreshes its artifact hash', () => {
+  const fx = fixture();
+  try {
+    const created = changes.createChange(fx.db, {
+      id: 'chg-incident-converge', title: 'Converge runtime diagnosis', kind: 'incident',
+      intent: 'Require inspectable debugging evidence before incident closure.',
+      docs_impact: { status: 'none', files: [], rationale: 'Internal runtime repair.' },
+    }, { rootDir: fx.rootDir });
+    ops.createTask(fx.db, {
+      id: 'incident-task', title: 'Fix diagnosed failure', type: 'bugfix', priority: 'P0',
+      change_id: 'chg-incident-converge',
+    });
+    ops.updateTaskStatus(fx.db, 'incident-task', 'in_progress');
+    ops.updateTaskStatus(fx.db, 'incident-task', 'completed');
+    changes.compileContext(fx.db, { id: 'chg-incident-converge' }, { rootDir: fx.rootDir });
+
+    const blocked = changes.convergeChange(fx.db, {
+      id: 'chg-incident-converge', evidence: incidentEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(blocked.ready, false);
+    assert.ok(blocked.blockers.includes('DIAGNOSIS_SECTION_MISSING:reproduction'));
+    assert.ok(blocked.blockers.includes('DIAGNOSIS_SECTION_MISSING:root-cause'));
+
+    const diagnosisPath = path.join(path.dirname(created.intent_path), 'diagnosis.md');
+    const beforeHash = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-converge').content_hash;
+    fs.writeFileSync(diagnosisPath, [
+      '# Incident diagnosis: Converge runtime diagnosis', '',
+      '## Reproduction', '', 'The projection worker fails after an interrupted claim.', '',
+      '## Hypotheses', '', 'A stale running job is never returned to the pending queue.', '',
+      '## Root cause', '', 'Boot recovery did not consume interrupted projection state.', '',
+      '## Regression test', '', 'The test seeds a stale running job and verifies requeue.', '',
+      '## Recovery', '', 'Requeue the job after the stale cutoff and replay projection.', '',
+    ].join('\n'));
+
+    const ready = changes.convergeChange(fx.db, {
+      id: 'chg-incident-converge', evidence: incidentEvidence(),
+    }, { rootDir: fx.rootDir });
+    assert.equal(ready.ready, true);
+    const afterHash = fx.db.prepare(
+      "SELECT content_hash FROM artifacts WHERE change_id = ? AND kind = 'diagnosis'",
+    ).get('chg-incident-converge').content_hash;
+    assert.notEqual(afterHash, beforeHash);
+    assert.equal(
+      afterHash,
+      require('node:crypto').createHash('sha256').update(fs.readFileSync(diagnosisPath)).digest('hex'),
+    );
+  } 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 = '9.0';
+const EXPECTED_VERSION = '9.1';
 
 const REQUIRED_TABLES = Object.freeze([
   'tasks',
@@ -87,14 +87,97 @@ function applyCompatibleColumns(db) {
   }
 }
 
+function tableSupportsKimi(db, table) {
+  const row = db.prepare(
+    "SELECT sql FROM sqlite_master WHERE type = 'table' AND name = ?",
+  ).get(table);
+  return typeof row?.sql === 'string' && row.sql.includes("'kimi'");
+}
+
+function upgradeRuntimeConstraints(db) {
+  if (tableSupportsKimi(db, 'events') && tableSupportsKimi(db, 'sessions')) return false;
+  const previousVersion = db.prepare(
+    'SELECT version FROM schema_version ORDER BY applied_at DESC LIMIT 1',
+  ).get()?.version || 'unknown';
+  const foreignKeys = db.pragma('foreign_keys', { simple: true });
+  db.pragma('foreign_keys = OFF');
+  try {
+    db.transaction(() => {
+      db.exec(`
+        DROP TABLE IF EXISTS events_runtime_upgrade;
+        CREATE TABLE events_runtime_upgrade (
+          id            INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts            TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+          type          TEXT    NOT NULL,
+          task_id       TEXT,
+          change_id     TEXT,
+          session_id    TEXT,
+          runtime       TEXT CHECK (runtime IS NULL OR runtime IN ('claude', 'opencode', 'codex', 'kimi')),
+          payload_json  TEXT
+        );
+        INSERT INTO events_runtime_upgrade
+          (id, ts, type, task_id, change_id, session_id, runtime, payload_json)
+        SELECT id, ts, type, task_id, change_id, session_id, runtime, payload_json FROM events;
+        DROP TABLE events;
+        ALTER TABLE events_runtime_upgrade RENAME TO events;
+        CREATE INDEX events_ts_type ON events(ts, type);
+        CREATE INDEX events_task ON events(task_id, id);
+        CREATE INDEX events_session ON events(session_id, id);
+        CREATE INDEX events_change ON events(change_id, id);
+
+        DROP TABLE IF EXISTS sessions_runtime_upgrade;
+        CREATE TABLE sessions_runtime_upgrade (
+          sid               TEXT PRIMARY KEY,
+          task_id           TEXT NOT NULL REFERENCES tasks(id),
+          runtime           TEXT NOT NULL CHECK (runtime IN ('claude', 'opencode', 'codex', 'kimi')),
+          pid               INTEGER,
+          worktree_path     TEXT NOT NULL,
+          artifact_dir      TEXT NOT NULL,
+          status            TEXT NOT NULL DEFAULT 'running'
+                              CHECK (status IN ('running', 'completed', 'crashed', 'orphan')),
+          lease_expires_at  TEXT NOT NULL,
+          heartbeat_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+          started_at        TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+        );
+        INSERT INTO sessions_runtime_upgrade
+          (sid, task_id, runtime, pid, worktree_path, artifact_dir, status,
+           lease_expires_at, heartbeat_at, started_at)
+        SELECT sid, task_id, runtime, pid, worktree_path, artifact_dir, status,
+               lease_expires_at, heartbeat_at, started_at FROM sessions;
+        DROP TABLE sessions;
+        ALTER TABLE sessions_runtime_upgrade RENAME TO sessions;
+        CREATE INDEX sessions_active ON sessions(status, task_id);
+        CREATE INDEX sessions_lease ON sessions(lease_expires_at) WHERE status = 'running';
+      `);
+      db.prepare(
+        `INSERT INTO migration_history
+          (from_version, to_version, direction, status, notes)
+         VALUES (?, ?, 'forward', 'success', ?)`,
+      ).run(
+        previousVersion,
+        EXPECTED_VERSION,
+        'Add Kimi to durable event and session runtime constraints',
+      );
+      const violations = db.pragma('foreign_key_check');
+      if (violations.length > 0) {
+        throw new Error(`runtime constraint migration produced ${violations.length} foreign key violation(s)`);
+      }
+    })();
+  } finally {
+    db.pragma(`foreign_keys = ${foreignKeys ? 'ON' : 'OFF'}`);
+  }
+  return true;
+}
+
 function applyCompatibleUpgrades(db) {
+  upgradeRuntimeConstraints(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');
+    ).run(EXPECTED_VERSION, 'Kimi runtime support with durable event and session state');
   })();
 }