ultra-builder-pro-cli 0.8.1 → 0.9.0

package/docs/RUNTIME-COMPAT-MATRIX.md

@@ -1,97 +1,139 @@
 # Runtime Compatibility Matrix
 
-Current presentation contract for Ultra Builder Pro. Claude Code, OpenCode, and
-Codex are the supported native plugin hosts. The canonical asset boundary lives
-in `adapters/_shared/runtime-assets.cjs`.
+Current presentation contract for Ultra Builder Pro. Claude Code, OpenCode,
+Codex, and Kimi Code 0.26+ are supported native plugin hosts. The canonical
+asset boundary lives in `adapters/_shared/runtime-assets.cjs`.
 
-Legend: **FULL** = native host surface, **DEGRADED** = supported but missing an
-equivalent lifecycle/control surface, **N/A** = intentionally not installed.
+Legend: **FULL** = native host surface, **FUNCTIONAL** = the complete outcome is
+available through a different native host primitive, **DEGRADED** = supported
+but missing an equivalent lifecycle/control surface, **N/A** = intentionally
+not installed.
 
 ## 1. Plugin and workflow surface
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` |
-| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` |
-| Public Ultra workflows | 12 | 12 | 12 |
-| Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled |
-| Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` |
-| External browser/deploy/framework skills | N/A | N/A | N/A |
-
-Codex converts the workflows into namespaced skills and records eleven legacy
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Package form | `.claude-plugin` native plugin | native config bundle + JS plugin | personal `.codex-plugin` | managed `kimi.plugin.json` plugin |
+| Public entry | `/ultra-*`, `/learn` | `/ultra-*`, `/learn` | `$ultra-builder-pro:<skill>` | `/ultra-builder-pro:<command>` |
+| Public Ultra workflows | 12 | 12 | 12 | 12 |
+| Internal agent-rule skills | 4, non-user-facing | 4, non-user-facing | 4 with implicit invocation disabled | 4, consumed by review workers |
+| Collaboration companions | `codex-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` | `cc-collab`, `ultra-verify` | `cc-collab`, `codex-collab`, `ultra-verify` |
+| Host bootstrap | native plugin context | native plugin context | native plugin context | `using-ultra-builder-pro` session-start skill |
+| External browser/deploy/framework skills | N/A | N/A | N/A | N/A |
+
+Codex converts workflows into namespaced skills and records eleven legacy
 command mappings in `command-map.json`; `ultra-review` remains directly
-invocable as a skill.
+invocable as a skill. Kimi registers all twelve commands through its native
+plugin command directory and exposes the allowlisted skills independently.
 
 ## 2. Agents and collaboration
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Bundled review/debug agents | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, nine managed TOML custom agents |
-| Native bounded delegation | native agent surface | native agent surface | native Codex subagents |
-| Cross-host advisor | explicit and read-only | explicit and read-only | explicit and read-only |
-| Primary-agent ownership | FULL | FULL | FULL |
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Bundled review/debug workers | FULL, native Markdown agents | FULL, native agent frontmatter | FULL, nine managed TOML agents | FUNCTIONAL, nine prompt templates consumed by `Agent` / `AgentSwarm` |
+| Plugin custom-agent registration | FULL | FULL | FULL | N/A; the 0.26 manifest has no custom-agent field |
+| Native bounded delegation | native agent surface | native agent surface | native Codex subagents | native `Agent` / `AgentSwarm` |
+| Cross-host advisor | explicit and read-only | explicit and read-only | explicit and read-only | explicit and read-only |
+| Primary-agent ownership | FULL | FULL | FULL | FULL |
 
-No bundled agent owns private persistent memory. It receives current-checkout
+No bundled worker owns private persistent memory. It receives current-checkout
 evidence and bounded context from the primary host, then returns a result for
-primary verification.
+primary verification. On Kimi, the review workflow reads the bundled worker
+template before creating the corresponding `AgentSwarm` item; the templates are
+not presented as nonexistent custom agents.
 
 ## 3. Workflow hooks
 
-| Lifecycle | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Session context/health | FULL, native `SessionStart` | DEGRADED, native context; health via `system.doctor` | FULL, native `SessionStart` |
-| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` |
-| Compaction recovery | FULL, validated checkpoint + resume/restore matcher | FULL, native compacting context | FULL, validated checkpoint + `PostCompact` restore |
-| Incomplete-stop gate | FULL, native blocking `Stop` | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` |
-| Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL |
+| Lifecycle | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Session context/health | FULL, native `SessionStart` | DEGRADED, native context; health via `system.doctor` | FULL, native `SessionStart` | FULL, session-start skill + `SessionStart` hooks |
+| Active edit boundary | FULL, `PreToolUse Edit|Write` | FULL, `tool.execute.before` rejects projection writes | FULL, `PreToolUse Edit|Write|apply_patch` | FULL, native `PreToolUse Edit|Write` deny contract |
+| Pre-compact checkpoint | FULL | FULL | FULL | FULL, native `PreCompact` |
+| Post-compact context injection | FULL | FULL, native compacting context | FULL, native `PostCompact` restore | DEGRADED; checkpoint restoration runs, but Kimi 0.26/0.27 does not reinject fire-and-forget hook text |
+| Incomplete-stop gate | FULL, native blocking `Stop` | DEGRADED, no equivalent blocking stop hook | FULL, native blocking `Stop` | FULL, native structured deny |
+| Subagent lifecycle evidence | FULL | DEGRADED, no equivalent packaged event | FULL | FULL, native `SubagentStart` / `SubagentStop` |
+
+Kimi's session bootstrap therefore also instructs recovery to inspect
+`.ultra/runtime/checkpoint.json` and call Ultra status/doctor after compaction.
+This keeps durable recovery intact without claiming dynamic context injection
+that the host does not guarantee.
 
 Health/context hooks inspect initialized projects; projection protection also
-applies at baseline, while compact/stop/subagent enforcement remains active-workflow scoped.
-No host receives prompt capture, transcript
-capture, observation journaling, session-summary memory, generic command
-blocking, or generic post-edit policy.
+applies at baseline, while compact/stop/subagent enforcement remains
+active-workflow scoped. No host receives prompt capture, transcript capture,
+observation journaling, session-summary memory, generic command blocking, or
+generic post-edit policy.
 
 ## 4. MCP and state
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` |
-| Live/declared contracts | 29 | 29 | 29 |
-| Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` |
-| Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
-| Ultra memory API | N/A | N/A | N/A |
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| stdio MCP registration | plugin `.mcp.json` | `opencode.json` local MCP entry | plugin `.mcp.json` | plugin `mcpServers` entry |
+| Live/declared contracts | 29 | 29 | 29 | 29 |
+| Host-native review/discovery/ask | native | native | documented in `codex-capability-map.json` | native Kimi tools and workers |
+| Durable authority | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` | project `.ultra/state.db` |
+| Ultra memory API | N/A | N/A | N/A | N/A |
 
 All 29 `task.*`, `session.*`, `change.*`, `system.*`, and `plan.*` operations
 registered by `mcp-server/server.cjs` are live. Review, impact discovery, skill
 loading, and user interaction remain host-native surfaces.
 
+Kimi starts plugin MCP processes with the managed plugin root as `cwd`. The
+generated launcher recovers the project from the inherited `PWD`, sets
+`UBP_ROOT_DIR` and `UBP_DB_PATH`, and refuses to start if that project boundary
+cannot be established. On POSIX it intentionally uses `env node` because Kimi
+0.26/0.27's embedded Node ABI differs from the ABI used to install `better-sqlite3`.
+
 ## 5. User handbook presentation
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` |
-| Automatic overwrite by plugin install | no | no | no |
-| Explicit managed-block sync | `ubp-handbook --runtime claude` | `ubp-handbook --runtime opencode` | `ubp-handbook --runtime codex` |
-| Backup before change | FULL | FULL | FULL |
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Durable user file | `~/.claude/CLAUDE.md` | `~/.config/opencode/AGENTS.md` | `~/.codex/AGENTS.md` | `~/.kimi-code/AGENTS.md` |
+| Automatic overwrite by plugin install | no | no | no | no |
+| Explicit managed-block sync | `ubp-handbook --runtime claude` | `ubp-handbook --runtime opencode` | `ubp-handbook --runtime codex` | `ubp-handbook --runtime kimi` |
+| Backup before change | FULL | FULL | FULL | FULL |
 
-## 6. Install, update, and uninstall
+The Kimi plugin installer does not edit `~/.kimi-code/config.toml`. Handbook
+sync remains a separate, previewable action so user policy and plugin mechanics
+do not become one irreversible mutation.
 
-| Capability | Claude Code | OpenCode | Codex |
-|---|---|---|---|
-| Adapter install | FULL | FULL | FULL |
-| Native update | next host session | host restart | cachebuster + `codex plugin add`, then new task |
-| Removes stale managed assets | FULL | FULL | FULL |
-| Preserves unrelated config | FULL | FULL | FULL |
-| Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers |
-| Normalized install provenance | FULL | FULL | FULL |
-| Read-only `ubp --doctor` | FULL | FULL | FULL |
-| Asset-content and host-contract drift detection | FULL | FULL | FULL |
+## 6. Install, update, and uninstall
 
-## 7. Verification sources
+| Capability | Claude Code | OpenCode | Codex | Kimi Code 0.26+ |
+|---|---|---|---|---|
+| Adapter install | FULL | FULL | FULL | FULL |
+| Global install command | `ubp --claude --global` | `ubp --opencode --global` | `ubp --codex --global` | `ubp --kimi --global` |
+| Native update visibility | next host session | host restart | cachebuster + new task | `/reload` or new session |
+| Removes stale managed assets | FULL | FULL | FULL | FULL |
+| Preserves unrelated config | FULL | FULL | FULL | FULL, including `config.toml` and unrelated registry records |
+| Uninstall ownership guard | managed plugin root | sentinels + owned MCP entry | managed root/manifest/agent headers | managed root + exact registry record |
+| Normalized install provenance | FULL | FULL | FULL | FULL |
+| Read-only `ubp --doctor` | FULL | FULL | FULL | FULL |
+| Asset-content and host-contract drift detection | FULL | FULL | FULL | FULL |
+
+Kimi's global managed root is
+`~/.kimi-code/plugins/managed/ultra-builder-pro`; its only registry mutation is
+the owned `ultra-builder-pro` entry in `~/.kimi-code/plugins/installed.json`.
+Reinstall preserves the user's enabled/capability choices and unrelated plugin
+records. Uninstall refuses an unmanaged or conflicting root.
+
+## 7. Durable schema compatibility
+
+| Capability | Contract |
+|---|---|
+| Current state schema | `9.1` |
+| Runtime values | `claude`, `opencode`, `codex`, `kimi` |
+| Upgrade from pre-Kimi schema | transactionally rebuilds only constrained `events` and `sessions` tables |
+| Preservation gate | rows, IDs, indexes, foreign keys, telemetry, incidents, and migration history remain intact |
+| Failure behavior | rollback; no partially upgraded authority database |
+
+## 8. Verification sources
 
 - `adapters/tests/*.test.cjs` verifies each installer and native manifest.
 - `tests/conformance/<runtime>/*.test.cjs` verifies command/skill, hook, MCP,
-  idempotency, and smoke presentation.
+  idempotency, and smoke presentation for all four hosts.
+- `tests/conformance/kimi/smoke.test.cjs` reproduces Kimi's plugin-root MCP
+  `cwd` and proves that the first state write lands in the active project.
 - `adapters/_shared/tests/runtime-assets.test.cjs` prevents retired or external
   skills and generic/memory hooks from re-entering a package.
 - `tests/retired-runtime.test.cjs` prevents retired runtime code or prompt text
@@ -100,7 +142,9 @@ loading, and user interaction remain host-native surfaces.
   migration, and idempotency.
 - `adapters/_shared/tests/provenance.test.cjs` verifies normalized manifests,
   content hashes, source attribution, corruption handling, and contract drift.
-- `tests/install.test.cjs` verifies healthy three-host doctor output and
+- `tests/install.test.cjs` verifies healthy four-host doctor output and
   host-specific hook/MCP degradation after controlled tampering.
+- `tests/package-smoke.test.cjs` installs the packed tarball into a clean
+  consumer and executes a live MCP round trip through every generated launcher.
 
 Any capability claim elsewhere must match current adapter code and these tests.

package/docs/USER-HANDBOOK-CONTRACT.md

@@ -15,8 +15,9 @@ syntax:
 | Claude Code | `~/.claude/CLAUDE.md` | `/ultra-plan` |
 | Codex | `~/.codex/AGENTS.md` | `$ultra-builder-pro:ultra-plan` |
 | OpenCode | `~/.config/opencode/AGENTS.md` | `/ultra-plan` |
+| Kimi Code | `~/.kimi-code/AGENTS.md` | `/ultra-builder-pro:ultra-plan` |
 
-The renderer never copies Claude Code-only APIs into Codex or OpenCode. Each
+The renderer never copies Claude Code-only APIs into Codex, OpenCode, or Kimi. Each
 host receives only its native invocation and collaboration names.
 
 ## Managed-block contract
@@ -42,6 +43,7 @@ Preview the full merged result before applying:
 ubp-handbook preview --runtime claude
 ubp-handbook preview --runtime codex
 ubp-handbook preview --runtime opencode
+ubp-handbook preview --runtime kimi
 ```
 
 Apply when the preview is correct:
@@ -50,6 +52,7 @@ Apply when the preview is correct:
 ubp-handbook apply --runtime claude
 ubp-handbook apply --runtime codex
 ubp-handbook apply --runtime opencode
+ubp-handbook apply --runtime kimi
 ```
 
 An existing target is copied to

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/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');
   })();
 }
 

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

@@ -9,11 +9,13 @@ const path = require('node:path');
 const {
   EXPECTED_VERSION,
   REQUIRED_TABLES,
+  SCHEMA_FILE,
   initStateDb,
   closeStateDb,
   openStateDb,
   tableNames,
 } = require('./state-db.cjs');
+const stateOps = require('./state-ops.cjs');
 
 function tmpDbPath(prefix = 'ubp-state') {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
@@ -114,3 +116,57 @@ test('Phase 8A.1 schema: tasks.parent_id column + tasks_parent partial index + s
     fs.rmSync(dir, { recursive: true, force: true });
   }
 });
+
+test('initStateDb migrates existing runtime constraints to Kimi without losing references', () => {
+  const { dir, file } = tmpDbPath('ubp-kimi-runtime-upgrade');
+  try {
+    const legacy = openStateDb(file);
+    const legacySchema = fs.readFileSync(SCHEMA_FILE, 'utf8').replaceAll(", 'kimi'", '');
+    legacy.exec(legacySchema);
+    legacy.prepare("DELETE FROM schema_version WHERE version = '9.1'").run();
+    legacy.prepare(
+      "INSERT INTO tasks (id, title, type, priority) VALUES ('task-old', 'Old', 'feature', 'P1')",
+    ).run();
+    legacy.prepare(
+      `INSERT INTO sessions
+       (sid, task_id, runtime, worktree_path, artifact_dir, lease_expires_at)
+       VALUES ('session-old', 'task-old', 'codex', '/tmp/worktree', '/tmp/artifacts', '2099-01-01T00:00:00.000Z')`,
+    ).run();
+    legacy.prepare(
+      "INSERT INTO telemetry (session_id, event_type, tool_name) VALUES ('session-old', 'tool_call', 'task.list')",
+    ).run();
+    legacy.prepare(
+      `INSERT INTO incidents
+       (id, code, severity, message, session_id)
+       VALUES ('incident-old', 'OLD', 'warning', 'preserve me', 'session-old')`,
+    ).run();
+    legacy.prepare(
+      "INSERT INTO events (type, session_id, runtime) VALUES ('session_spawned', 'session-old', 'codex')",
+    ).run();
+    closeStateDb(legacy);
+
+    const upgraded = initStateDb(file);
+    assert.equal(upgraded.schema_version, '9.1');
+    assert.equal(upgraded.db.prepare("SELECT runtime FROM sessions WHERE sid = 'session-old'").get().runtime, 'codex');
+    assert.equal(upgraded.db.prepare("SELECT COUNT(*) AS n FROM telemetry WHERE session_id = 'session-old'").get().n, 1);
+    assert.equal(upgraded.db.prepare("SELECT COUNT(*) AS n FROM incidents WHERE session_id = 'session-old'").get().n, 1);
+    assert.deepEqual(upgraded.db.pragma('foreign_key_check'), []);
+
+    upgraded.db.prepare(
+      "INSERT INTO tasks (id, title, type, priority) VALUES ('task-kimi', 'Kimi', 'feature', 'P1')",
+    ).run();
+    const session = stateOps.createSession(upgraded.db, {
+      sid: 'session-kimi',
+      task_id: 'task-kimi',
+      runtime: 'kimi',
+      worktree_path: '/tmp/kimi-worktree',
+      artifact_dir: '/tmp/kimi-artifacts',
+    });
+    assert.equal(session.runtime, 'kimi');
+    const event = stateOps.appendEvent(upgraded.db, { type: 'kimi-ready', runtime: 'kimi' });
+    assert.ok(event.event_id > 0);
+    closeStateDb(upgraded.db);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});

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

@@ -36,8 +36,8 @@ test('initProject copies bundled template into .ultra/', () => {
     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');
+      const version = db.prepare("SELECT version FROM schema_version WHERE version = '9.1'").get();
+      assert.equal(version.version, '9.1');
       assert.ok(db.prepare("SELECT name FROM sqlite_master WHERE name = 'changes'").get());
     } finally {
       db.close();

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

@@ -8,7 +8,7 @@ const path = require('node:path');
 
 const stateDb = require('../lib/state-db.cjs');
 
-test('initStateDb upgrades a pre-9.0 database in place with task/event change linkage', () => {
+test('initStateDb upgrades a pre-9.1 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 {
@@ -59,8 +59,8 @@ test('initStateDb upgrades a pre-9.0 database in place with task/event change li
     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());
+    assert.equal(upgraded.schema_version, '9.1');
+    assert.ok(upgraded.db.prepare("SELECT 1 FROM schema_version WHERE version = '9.1'").get());
     stateDb.closeStateDb(upgraded.db);
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra-builder-pro-cli",
-  "version": "0.8.1",
-  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, and Codex CLI.",
+  "version": "0.9.0",
+  "description": "Multi-runtime installer for the Ultra Builder Pro agent engineering system — deploys commands, agents, skills, hooks, and MCP server to Claude Code, OpenCode, Codex CLI, and Kimi Code.",
   "bin": {
     "ultra-builder-pro-cli": "bin/install.js",
     "ubp": "bin/install.js",
@@ -60,6 +60,7 @@
     "claude-code",
     "opencode",
     "codex",
+    "kimi-code",
     "agent",
     "cli",
     "multi-runtime",
@@ -92,6 +93,7 @@
     "verify:release": "npm run test:all && npm run test:hooks && npm audit --omit=dev --audit-level=high",
     "prepublishOnly": "npm run verify:release",
     "install:claude": "node bin/install.js --claude --local",
+    "install:kimi": "node bin/install.js --kimi --local",
     "install:all": "node bin/install.js --all --local"
   },
   "dependencies": {