feat(kiloclaw): add Kilo CLI recovery agent (#1657)

* feat(kiloclaw): add kilo CLI run feature (spawn, poll, UI)

Add the ability to run `kilo run --auto` on a KiloClaw instance from the
dashboard, with real-time output polling and DB persistence.

Stack: controller spawn route -> CF Worker DO proxy -> platform routes ->
tRPC procedures -> React polling page. Includes admin visibility,
changelog entry, and 12 controller route tests.

* Fix dev-CLI

* refactor(kiloclaw): use DB run ID in CLI run URL instead of prompt query param

* Remove debug info

* feat(kiloclaw): add admin CLI Runs tab with search and pagination

* feat(kiloclaw): use KiloClaw default model for Kilo CLI runs

Sync the Kilo CLI's model config with the user's selected KiloClaw
default model (KILOCODE_DEFAULT_MODEL). Previously the CLI ignored this
env var and fell back to kilo-auto/small. Now the model is written to
opencode.json on both fresh installs and every boot, converting the
kilocode/ provider prefix to kilo/ for the CLI's naming convention.

* feat(kiloclaw): add system context prompt template for Kilo CLI runs

Wrap the user's prompt with system context (key paths, architecture,
diagnostic commands, and fix instructions) so the agent knows where
to look and how to repair broken OpenClaw instances. The original
user prompt is still stored for UI display; only the expanded prompt
is passed to `kilo run --auto`.

* refactor(kiloclaw): use shared constants in prompt template, improve CLI run UI

Export path constants from config-writer and kilo-cli-config so the
prompt template references them instead of duplicating string literals.
Add openclaw doctor to diagnostics. Improve the CLI run detail page
with SetPageTitle, remove max-height on output, and clean up layout.

* refactor(kiloclaw): rebrand CLI run as recovery tool

* fix(kiloclaw): wrap long output lines and auto-scroll on all updates

* chore: remove migration 0060 before rebase

* chore(db): regenerate migration 0060 for kiloclaw_cli_runs after rebase

* chore: fix migration numbering, type errors, and formatting after rebase

* docs(kiloclaw): update changelog entry to match recovery branding

* fix(kiloclaw): set baseURL in kilo CLI config instead of deleting it

* fix(kiloclaw): scope CLI run status to requested run ID and add GDPR cleanup

* fix(kiloclaw): revert baseURL config patch — delete stale field instead of setting it

* perf(kiloclaw): lazy-load CLI run output instead of fetching with list

Exclude the output column from listAllCliRuns to avoid sending up to
~25MB per page. Add a dedicated getCliRunOutput procedure that fetches
output for a single run on demand when selected in the admin panel.

* fix(kiloclaw): scope cancelKiloCliRun DB update to specific run ID

* chore(db): remove migration 0061 before merge with main

* chore(db): regenerate migration 0064 after merge with main

* fix(kilo-app): fix unsafe type access in useForceUpdate hook

* Undo unwanted change

Author: RSO

kiloclaw/controller/src/bootstrap.test.ts

@@ -279,6 +279,26 @@ describe('setupDirectories', () => {
     expect(env.INVOCATION_ID).toBe('1');
     expect(env.GOG_KEYRING_PASSWORD).toBe('kiloclaw');
   });
+
+  it('derives KILO_API_URL from KILOCODE_API_BASE_URL origin', () => {
+    const { deps } = fakeDeps();
+    const env: Record<string, string | undefined> = {
+      KILOCODE_API_BASE_URL: 'https://api.example.com/v1',
+    };
+
+    setupDirectories(env, deps);
+
+    expect(env.KILO_API_URL).toBe('https://api.example.com');
+  });
+
+  it('does not set KILO_API_URL when KILOCODE_API_BASE_URL is absent', () => {
+    const { deps } = fakeDeps();
+    const env: Record<string, string | undefined> = {};
+
+    setupDirectories(env, deps);
+
+    expect(env.KILO_API_URL).toBeUndefined();
+  });
 });
 
 // ---- applyFeatureFlags ----

kiloclaw/controller/src/bootstrap.ts

@@ -188,6 +188,11 @@ export function setupDirectories(env: EnvLike, deps: BootstrapDeps = defaultDeps
 
   // GOG_KEYRING_PASSWORD is NOT a secret — see gog-credentials.ts for context.
   env.GOG_KEYRING_PASSWORD = 'kiloclaw';
+
+  // Derive the API origin for the Kilo CLI from the full base URL.
+  if (env.KILOCODE_API_BASE_URL) {
+    env.KILO_API_URL = new URL(env.KILOCODE_API_BASE_URL).origin;
+  }
 }
 
 // ---- Step 3: Feature flags ----

kiloclaw/controller/src/config-writer.ts

@@ -370,7 +370,7 @@ export function setNestedValue(obj: ConfigObject, path: string, value: string):
   current[segments[segments.length - 1]] = value;
 }
 
-const DEFAULT_MCPORTER_CONFIG_PATH = '/root/.openclaw/workspace/config/mcporter.json';
+export const DEFAULT_MCPORTER_CONFIG_PATH = '/root/.openclaw/workspace/config/mcporter.json';
 
 /**
  * Write mcporter.json with MCP server definitions derived from environment variables.

kiloclaw/controller/src/index.ts

@@ -18,6 +18,7 @@ import { createPairingCache } from './pairing-cache';
 import { registerEnvRoutes } from './routes/env';
 import { registerGmailPushRoute } from './routes/gmail-push';
 import { registerFileRoutes } from './routes/files';
+import { registerKiloCliRunRoutes } from './routes/kilo-cli-run';
 import { CONTROLLER_COMMIT, CONTROLLER_VERSION } from './version';
 import { writeKiloCliConfig } from './kilo-cli-config';
 import { writeGogCredentials } from './gog-credentials';
@@ -362,6 +363,7 @@ export async function startController(env: NodeJS.ProcessEnv = process.env): Pro
   registerEnvRoutes(honoApp, supervisor, config.expectedToken);
   registerGmailPushRoute(honoApp, gmailWatchSupervisor ?? null, config.expectedToken);
   registerFileRoutes(honoApp, config.expectedToken, '/root/.openclaw');
+  registerKiloCliRunRoutes(honoApp, config.expectedToken);
   honoApp.all(
     '*',
     createHttpProxy({

kiloclaw/controller/src/kilo-cli-config.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { writeKiloCliConfig, type KiloCliConfigDeps } from './kilo-cli-config';
+import { writeKiloCliConfig, toKiloModelId, type KiloCliConfigDeps } from './kilo-cli-config';
 
 function fakeDeps(existingConfig?: string) {
   const written: { path: string; data: string; mode: number }[] = [];
@@ -34,6 +34,20 @@ function baseEnv(overrides: Record<string, string> = {}): Record<string, string
   };
 }
 
+describe('toKiloModelId', () => {
+  it('replaces kilocode/ prefix with kilo/', () => {
+    expect(toKiloModelId('kilocode/anthropic/claude-opus-4.6')).toBe(
+      'kilo/anthropic/claude-opus-4.6'
+    );
+    expect(toKiloModelId('kilocode/openai/gpt-5')).toBe('kilo/openai/gpt-5');
+  });
+
+  it('passes through values without kilocode/ prefix', () => {
+    expect(toKiloModelId('kilo/anthropic/claude-opus-4.6')).toBe('kilo/anthropic/claude-opus-4.6');
+    expect(toKiloModelId('other/model')).toBe('other/model');
+  });
+});
+
 describe('writeKiloCliConfig', () => {
   it('returns false when feature flag is disabled', () => {
     const { deps, written } = fakeDeps();
@@ -72,13 +86,25 @@ describe('writeKiloCliConfig', () => {
     expect(seedConfig.$schema).toBe('https://app.kilo.ai/config.json');
     // No provider block — KiloAuthPlugin auto-registers via KILO_API_KEY env var
     expect(seedConfig.provider).toBeUndefined();
-    // No model — CLI defaults to kilo-auto/small, user picks their own
+    // No model when KILOCODE_DEFAULT_MODEL is not set
     expect(seedConfig.model).toBeUndefined();
     expect(seedConfig.permission.edit).toBe('allow');
     expect(seedConfig.permission.bash).toBe('allow');
     expect(written[0].mode).toBe(0o600);
   });
 
+  it('includes model in seed config when KILOCODE_DEFAULT_MODEL is set', () => {
+    const { deps, written } = fakeDeps();
+    const env = baseEnv({ KILOCODE_DEFAULT_MODEL: 'kilocode/anthropic/claude-opus-4.6' });
+    const result = writeKiloCliConfig(env, '/tmp/kilo', deps);
+
+    expect(result).toBe(true);
+    expect(written.length).toBeGreaterThanOrEqual(1);
+    const seedConfig = JSON.parse(written[0].data);
+    expect(seedConfig.model).toBe('kilo/anthropic/claude-opus-4.6');
+    expect(seedConfig.permission.edit).toBe('allow');
+  });
+
   it('does not seed config on fresh install when config already exists', () => {
     const existing = JSON.stringify({ permission: { edit: 'allow', bash: 'allow' } });
     const { deps, written } = fakeDeps(existing);
@@ -99,71 +125,86 @@ describe('writeKiloCliConfig', () => {
     expect(written).toHaveLength(0);
   });
 
-  it('patches base URL on existing config using provider.kilo', () => {
-    const existing = JSON.stringify({ permission: { edit: 'allow', bash: 'allow' } });
-    const { deps, written } = fakeDeps(existing);
-    const env = baseEnv({
-      KILOCLAW_FRESH_INSTALL: 'false',
-      KILOCODE_API_BASE_URL: 'https://tunnel.example.com/',
+  it('removes stale provider.kilo.options.baseURL from existing config', () => {
+    const existing = JSON.stringify({
+      permission: { edit: 'allow', bash: 'allow' },
+      provider: { kilo: { options: { baseURL: 'https://stale.example.com' } } },
     });
+    const { deps, written } = fakeDeps(existing);
+    const env = baseEnv({ KILOCLAW_FRESH_INSTALL: 'false' });
 
     writeKiloCliConfig(env, '/tmp/kilo', deps);
 
     expect(written).toHaveLength(1);
     const config = JSON.parse(written[0].data);
-    expect(config.provider.kilo.options.baseURL).toBe('https://tunnel.example.com/');
+    expect(config.provider.kilo.options.baseURL).toBeUndefined();
   });
 
-  it('does not set model from KILOCODE_DEFAULT_MODEL', () => {
+  it('patches model from KILOCODE_DEFAULT_MODEL on existing config', () => {
     const existing = JSON.stringify({ permission: { edit: 'allow', bash: 'allow' } });
     const { deps, written } = fakeDeps(existing);
     const env = baseEnv({
       KILOCLAW_FRESH_INSTALL: 'false',
       KILOCODE_DEFAULT_MODEL: 'kilocode/openai/gpt-5',
-      KILOCODE_API_BASE_URL: 'https://tunnel.example.com/',
     });
 
     writeKiloCliConfig(env, '/tmp/kilo', deps);
 
     expect(written).toHaveLength(1);
     const config = JSON.parse(written[0].data);
-    // KILOCODE_DEFAULT_MODEL is for OpenClaw, not Kilo CLI
-    expect(config.model).toBeUndefined();
-    // But base URL is patched
-    expect(config.provider.kilo.options.baseURL).toBe('https://tunnel.example.com/');
+    expect(config.model).toBe('kilo/openai/gpt-5');
   });
 
-  it('creates provider structure when patching base URL on minimal config', () => {
-    const existing = JSON.stringify({});
+  it('patches model and scrubs stale baseURL together', () => {
+    const existing = JSON.stringify({
+      permission: { edit: 'allow', bash: 'allow' },
+      provider: { kilo: { options: { baseURL: 'https://stale.example.com' } } },
+    });
     const { deps, written } = fakeDeps(existing);
     const env = baseEnv({
       KILOCLAW_FRESH_INSTALL: 'false',
-      KILOCODE_API_BASE_URL: 'https://tunnel.example.com/',
+      KILOCODE_DEFAULT_MODEL: 'kilocode/openai/gpt-5',
+    });
+
+    writeKiloCliConfig(env, '/tmp/kilo', deps);
+
+    expect(written).toHaveLength(1);
+    const config = JSON.parse(written[0].data);
+    expect(config.model).toBe('kilo/openai/gpt-5');
+    expect(config.provider.kilo.options.baseURL).toBeUndefined();
+  });
+
+  it('does not set model when KILOCODE_DEFAULT_MODEL is absent', () => {
+    const existing = JSON.stringify({
+      permission: { edit: 'allow', bash: 'allow' },
+      provider: { kilo: { options: { baseURL: 'https://stale.example.com' } } },
     });
+    const { deps, written } = fakeDeps(existing);
+    const env = baseEnv({ KILOCLAW_FRESH_INSTALL: 'false' });
 
     writeKiloCliConfig(env, '/tmp/kilo', deps);
 
+    expect(written).toHaveLength(1);
     const config = JSON.parse(written[0].data);
-    expect(config.provider.kilo.options.baseURL).toBe('https://tunnel.example.com/');
+    expect(config.model).toBeUndefined();
+    // baseURL scrubbed as side effect
+    expect(config.provider.kilo.options.baseURL).toBeUndefined();
   });
 
-  it('does not write when no env overrides set', () => {
+  it('does not write when config has no stale baseURL and no model override', () => {
     const existing = JSON.stringify({ permission: { edit: 'allow' } });
     const { deps, written } = fakeDeps(existing);
     const env = baseEnv({ KILOCLAW_FRESH_INSTALL: 'false' });
 
     writeKiloCliConfig(env, '/tmp/kilo', deps);
 
-    // No KILOCODE_API_BASE_URL → no patch needed, no write
+    // Nothing to scrub or patch — no write
     expect(written).toHaveLength(0);
   });
 
   it('skips patch gracefully when config file contains corrupt JSON', () => {
     const { deps, written } = fakeDeps('not valid json {{{');
-    const env = baseEnv({
-      KILOCLAW_FRESH_INSTALL: 'false',
-      KILOCODE_API_BASE_URL: 'https://tunnel.example.com/',
-    });
+    const env = baseEnv({ KILOCLAW_FRESH_INSTALL: 'false' });
 
     const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
     const result = writeKiloCliConfig(env, '/tmp/kilo', deps);
@@ -177,7 +218,7 @@ describe('writeKiloCliConfig', () => {
     consoleSpy.mockRestore();
   });
 
-  it('seeds config and then patches base URL on fresh install', () => {
+  it('seeds config on fresh install without adding baseURL', () => {
     const { deps, written } = fakeDeps();
 
     let seeded = false;
@@ -197,17 +238,18 @@ describe('writeKiloCliConfig', () => {
     });
 
     const env = baseEnv({
-      KILOCODE_API_BASE_URL: 'https://tunnel.example.com/',
+      KILOCODE_API_BASE_URL: 'https://tunnel.example.com/api/gateway',
     });
 
     const result = writeKiloCliConfig(env, '/tmp/kilo', deps);
 
     expect(result).toBe(true);
-    expect(written).toHaveLength(2); // seed + patch
+    // Only the seed write — no baseURL patch (seeded config has no stale baseURL to scrub)
+    expect(written).toHaveLength(1);
 
-    const finalConfig = JSON.parse(written[1].data);
+    const finalConfig = JSON.parse(written[0].data);
     expect(finalConfig.$schema).toBe('https://app.kilo.ai/config.json');
-    expect(finalConfig.provider.kilo.options.baseURL).toBe('https://tunnel.example.com/');
+    expect(finalConfig.provider).toBeUndefined();
     expect(finalConfig.model).toBeUndefined();
   });
 });

kiloclaw/controller/src/kilo-cli-config.ts

@@ -15,8 +15,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const KILO_CONFIG_DIR = '/root/.config/kilo';
-const CONFIG_FILE = 'opencode.json';
+export const KILO_CONFIG_DIR = '/root/.config/kilo';
+export const CONFIG_FILE = 'opencode.json';
+
+/** The Kilo CLI uses `kilo/` as the provider prefix, but KiloClaw uses `kilocode/`. */
+export function toKiloModelId(kilocodeModelId: string): string {
+  if (kilocodeModelId.startsWith('kilocode/')) {
+    return 'kilo/' + kilocodeModelId.slice('kilocode/'.length);
+  }
+  return kilocodeModelId;
+}
 
 export type KiloCliConfigDeps = {
   mkdirSync: (dir: string, opts: { recursive: boolean }) => void;
@@ -49,33 +57,48 @@ export function writeKiloCliConfig(
   // No provider block needed — the KiloAuthPlugin auto-registers the "kilo"
   // provider when KILO_API_KEY is in the environment (set by bootstrap).
   if (isFreshInstall && !deps.existsSync(configPath)) {
-    const config = {
+    const config: Record<string, unknown> = {
       $schema: 'https://app.kilo.ai/config.json',
       permission: { edit: 'allow', bash: 'allow' },
     };
+    if (env.KILOCODE_DEFAULT_MODEL) {
+      config.model = toKiloModelId(env.KILOCODE_DEFAULT_MODEL);
+    }
     deps.mkdirSync(configDir, { recursive: true });
     deps.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
     console.log('[kilo-cli] Seeded config at ' + configPath);
   }
 
   // Patch config on every boot (if it exists).
-  // Only writes when a change is actually made to avoid silent no-op writes.
-  if (deps.existsSync(configPath) && env.KILOCODE_API_BASE_URL) {
+  if (deps.existsSync(configPath)) {
     try {
       // JSON structure is open-ended (user may add arbitrary keys), so we use `any`
-      // rather than a strict schema. The patch only touches provider.kilo.options.baseURL.
+      // rather than a strict schema.
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       const config: any = JSON.parse(deps.readFileSync(configPath, 'utf8'));
+      let dirty = false;
+
+      // Remove any stale provider.kilo.options.baseURL from the config file.
+      // Setting baseURL in opencode.json is broken (the Kilo CLI ignores it
+      // in certain code paths). The correct mechanism is the KILO_API_URL env
+      // var, which bootstrap sets from KILOCODE_API_BASE_URL. Early deployments
+      // may still have the broken field, so we scrub it on every boot.
+      if (config.provider?.kilo?.options?.baseURL) {
+        delete config.provider.kilo.options.baseURL;
+        dirty = true;
+      }
 
-      // Override the kilo provider's base URL for local dev (e.g., ngrok tunnel).
-      // In production this env var is not set and the built-in default is used.
-      config.provider = config.provider || {};
-      config.provider.kilo = config.provider.kilo || {};
-      config.provider.kilo.options = config.provider.kilo.options || {};
-      config.provider.kilo.options.baseURL = env.KILOCODE_API_BASE_URL;
-      console.log('[kilo-cli] Patched base URL: ' + env.KILOCODE_API_BASE_URL);
+      // Sync Kilo CLI's model with the user's KiloClaw default model.
+      // Updated on every boot so model changes in KiloClaw settings take effect.
+      const defaultModel = env.KILOCODE_DEFAULT_MODEL;
+      if (defaultModel) {
+        config.model = toKiloModelId(defaultModel);
+        dirty = true;
+      }
 
-      deps.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+      if (dirty) {
+        deps.writeFileSync(configPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+      }
     } catch (err) {
       console.error('[kilo-cli] Failed to patch config (corrupt JSON?), skipping:', err);
     }