Function startController

services/kiloclaw/controller/src/index.ts:204–656

(env: NodeJS.ProcessEnv = process.env)

  return JSON.stringify({ status: 'ok', state: state.state });
}

export async function startController(env: NodeJS.ProcessEnv = process.env): Promise<void> {
  // Mutable state ref — read by the health endpoint on every request,
  // updated by bootstrap as it progresses through phases.
  const controllerState: ControllerStateRef = {
    current: { state: 'bootstrapping', phase: 'init' },
  };

  // ── Phase 1: Start HTTP server ──────────────────────────────────────
  // The server starts FIRST so /_kilo/health is always reachable, even
  // during bootstrap. During bootstrap, a lightweight inline handler
  // serves health probes directly. After bootstrap, the Hono app with
  // full routes takes over.
  let app: Hono | null = null;

  const server = http.createServer((req, res) => {
    // Once bootstrap has completed and the Hono app is ready, delegate all requests.
    if (app) {
      void handleHttpRequest(app, req, res).catch(error => {
        console.error('[controller] HTTP handler failed:', error);
        res.statusCode = 500;
        res.setHeader('content-type', 'application/json');
        res.end(JSON.stringify({ error: 'Internal Server Error' }));
      });
      return;
    }

    // Pre-bootstrap: serve health probes inline without Hono.
    // Strip query string so e.g. /_kilo/health?ts=123 still matches.
    const pathname = (req.url ?? '/').split('?')[0];
    if (pathname === '/_kilo/health' || pathname === '/health') {
      res.statusCode = 200;
      res.setHeader('content-type', 'application/json');
      if (pathname === '/health') {
        // Bare /health for Fly probes — no state details
        res.end(JSON.stringify({ status: 'ok' }));
      } else {
        res.end(healthJson(controllerState.current));
      }
      return;
    }

    // All other routes: 503 during bootstrap
    res.statusCode = 503;
    res.setHeader('content-type', 'application/json');
    res.end(JSON.stringify({ error: 'Service starting', state: controllerState.current.state }));
  });

  // Mutable ref for the WebSocket upgrade handler. Set once the Hono app and
  // supervisor are ready. Registered on the server early so connections during
  // bootstrap or degraded mode get a clean 503 rejection instead of hanging.
  const wsUpgradeRef: {
    handler: ((req: http.IncomingMessage, socket: Duplex, head: Buffer) => void) | null;
  } = { handler: null };

  server.on('upgrade', (req, socket, head) => {
    if (wsUpgradeRef.handler) {
      wsUpgradeRef.handler(req, socket, head);