@stage-labs/metro 0.1.0-beta.259 → 0.1.0-beta.260

package/runtime/node_modules/@metro-labs/daemon/src/claude/api.ts

@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { errMsg, log } from '@metro-labs/core/log';
-import { apiFailure, apiSession, requireAdmin, cors, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { apiFailure, apiSession, requireAdmin, cors, readJsonBody, sendJson, type ApiSession } from '@metro-labs/http/api-http';
 import { ApiError } from '@metro-labs/http/api-error';
 import { isRecord } from '@metro-labs/core/is-record';
 import { listClaudeSettings, SETTINGS_MAX, writeClaudeSettings } from './settings.js';
@@ -22,25 +22,10 @@ import {
   type LoginTarget,
 } from './login.js';
 import { claudeLoginTarget, type ClaudeLoginDeps } from '../gateway/claude-logins.js';
+import { setupAnswer, type SetupApiDeps } from './setup-api.js';
 import {
-  claudeSetupStatus,
-  ensureClaudeSetup,
-  isPermissionMode,
-  liveEvents,
-  permissionMode,
-  setLiveEvents,
-  setMemoryRoutine,
-  setPermissionMode,
-  setPrivacy,
-  setSystemPrompt,
-  systemPrompt,
-  SYSTEM_PROMPT_MAX,
-  type PermissionMode,
-  type SetupDeps,
-} from './setup.js';
-import {
+  autostartEnabled,
   ensureSession,
-  sessionRunning,
   sessionStatus,
   setAutostart,
   startSession,
@@ -48,7 +33,6 @@ import {
   type SessionDeps,
 } from './session.js';
 import { claudeVersion, updateClaude, type VersionDeps } from './version.js';
-import { tryMemoryJob } from './memory-routine.js';
 import { receiveSessionFile, sessionFilePath } from './session-files.js';
 import { createReadStream } from '../agent-user/agent-fs.js';
 import { pipeline } from 'node:stream/promises';
@@ -70,15 +54,11 @@ const WRITABLE = new Set(['GET', 'DELETE', 'PUT', 'POST']);
 const PAGE = 100;
 const PAGE_MAX = 500;
 
-export interface ClaudeApiDeps {
+export interface ClaudeApiDeps extends SetupApiDeps {
   dir?: () => string;
   login?: LoginDeps;
   claudeLogins?: ClaudeLoginDeps;
-  session?: SessionDeps;
-  setup?: SetupDeps;
   version?: VersionDeps;
-  liveEvents?: (on: boolean) => void;
-  memoryJob?: (on: boolean) => void;
 }
 
 function projectOf(query: URLSearchParams): string {
@@ -155,104 +135,22 @@ const ADMIN_ONLY = /^\/api\/claude\/(login|session|version|setup)(\/|$)/;
 const LOGIN = 'login';
 const SESSION = 'session';
 const SETUP = 'setup';
-const SETUP_BODY_MAX = SYSTEM_PROMPT_MAX * 2;
 const VERSION = 'version';
 
-interface SetupChange {
-  privacy?: boolean;
-  permissionMode?: PermissionMode;
-  systemPrompt?: string;
-  liveEvents?: boolean;
-  memoryRoutine?: boolean;
-}
-
-function promptChange(raw: unknown): string | undefined {
-  if (raw === undefined) return undefined;
-  if (typeof raw !== 'string') throw new ApiError('systemPrompt must be text', 400);
-  if (Buffer.byteLength(raw) > SYSTEM_PROMPT_MAX) throw new ApiError(`systemPrompt must be under ${String(SYSTEM_PROMPT_MAX / 1024)} KiB`, 400);
-  return raw;
-}
-
-function flagChange(raw: unknown, name: string): boolean | undefined {
-  if (raw === undefined) return undefined;
-  if (typeof raw !== 'boolean') throw new ApiError(`${name} must be true or false`, 400);
-  return raw;
-}
-
-function modeChange(raw: unknown): PermissionMode | undefined {
-  if (raw === undefined) return undefined;
-  if (!isPermissionMode(raw)) throw new ApiError('permissionMode must be auto or bypass', 400);
-  return raw;
-}
-
-function setupChange(body: unknown): SetupChange {
-  if (!isRecord(body)) throw new ApiError('a body is required', 400);
-  const privacy = flagChange(body.privacy, 'privacy');
-  const permissionMode = modeChange(body.permissionMode);
-  const systemPrompt = promptChange(body.systemPrompt);
-  const liveEvents = flagChange(body.liveEvents, 'liveEvents');
-  const memoryRoutine = flagChange(body.memoryRoutine, 'memoryRoutine');
-  if ([privacy, permissionMode, systemPrompt, liveEvents, memoryRoutine].every((v) => v === undefined)) throw new ApiError('nothing to change', 400);
-  return {
-    ...(privacy === undefined ? {} : { privacy }),
-    ...(permissionMode === undefined ? {} : { permissionMode }),
-    ...(systemPrompt === undefined ? {} : { systemPrompt }),
-    ...(liveEvents === undefined ? {} : { liveEvents }),
-    ...(memoryRoutine === undefined ? {} : { memoryRoutine }),
-  };
-}
-
-function restartsSession(change: SetupChange, agents: string | undefined): boolean {
-  let restart = false;
-  if (change.permissionMode !== undefined && change.permissionMode !== permissionMode(agents)) {
-    setPermissionMode(change.permissionMode, agents);
-    restart = true;
-  }
-  if (change.systemPrompt !== undefined && change.systemPrompt.trim() !== systemPrompt(agents)) {
-    setSystemPrompt(change.systemPrompt, agents);
-    restart = true;
-  }
-  return restart;
-}
-
-function applyLiveEvents(on: boolean, deps: ClaudeApiDeps): void {
-  const agents = deps.setup?.agents;
-  if (on !== liveEvents(agents)) setLiveEvents(on, agents);
-  deps.liveEvents?.(on);
-}
-
-function applyMemoryRoutine(on: boolean, deps: ClaudeApiDeps): void {
-  setMemoryRoutine(on, deps.setup?.agents);
-  (deps.memoryJob ?? tryMemoryJob)(on);
-}
-
-function applySetupChange(change: SetupChange, deps: ClaudeApiDeps): void {
-  const setup = deps.setup ?? {};
-  if (change.privacy !== undefined) setPrivacy(change.privacy, setup.agents);
-  if (change.liveEvents !== undefined) applyLiveEvents(change.liveEvents, deps);
-  if (change.memoryRoutine !== undefined) applyMemoryRoutine(change.memoryRoutine, deps);
-  if (restartsSession(change, setup.agents) && sessionRunning(deps.session?.tmux ?? 'tmux')) stopSession(deps.session ?? {});
-  ensureClaudeSetup(setup);
-}
-
-async function setupAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise<unknown> {
-  const setup = deps.setup ?? {};
-  const method = req.method ?? 'GET';
-  if (method === 'GET') return claudeSetupStatus(setup);
-  if (method !== 'POST') throw new ApiError('method not allowed', 405);
-  applySetupChange(setupChange(await readJsonBody(req, SETUP_BODY_MAX)), deps);
-  return claudeSetupStatus(setup);
-}
-
 function sessionCommand(body: Record<string, unknown>, session: SessionDeps): unknown {
   if (body.action === 'start') {
     const status = sessionStatus(session);
-    if (status.running) return status;
-    if (status.blocked !== null) throw new ApiError(`cannot start a Claude session: ${status.blocked}`, 409);
-    return startSession(session);
+    if (!status.running && status.blocked !== null) throw new ApiError(`cannot start a Claude session: ${status.blocked}`, 409);
+    const started = status.running ? status : startSession(session);
+    setAutostart(typeof body.autostart === 'boolean' ? body.autostart : true, session.agents);
+    return { ...started, autostart: autostartEnabled(session.agents) };
+  }
+  if (body.action === 'stop') {
+    setAutostart(false, session.agents);
+    return stopSession(session);
   }
-  if (body.action === 'stop') return stopSession(session);
   if (body.action !== undefined) throw new ApiError('action must be start or stop', 400);
+  if (typeof body.autostart === 'boolean') setAutostart(body.autostart, session.agents);
   if (body.autostart === true) ensureSession(session);
   return sessionStatus(session);
 }
@@ -264,7 +162,6 @@ async function sessionAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise
   if (method !== 'POST') throw new ApiError('method not allowed', 405);
   const body = await readJsonBody(req);
   if (!isRecord(body)) throw new ApiError('a body is required', 400);
-  if (typeof body.autostart === 'boolean') setAutostart(body.autostart, session.agents);
   return sessionCommand(body, session);
 }
 
@@ -316,18 +213,18 @@ function versionAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise<unkno
   return updateClaude(version);
 }
 
-const SINGLETONS: Record<string, (req: IncomingMessage, deps: ClaudeApiDeps) => Promise<unknown>> = {
+const SINGLETONS: Record<string, (req: IncomingMessage, deps: ClaudeApiDeps, session: ApiSession) => Promise<unknown>> = {
   [SESSION]: sessionAnswer,
   [SETUP]: setupAnswer,
   [VERSION]: versionAnswer,
 };
 
-function routed(req: IncomingMessage, path: string, search: string, deps: ClaudeApiDeps): unknown {
+function routed(req: IncomingMessage, path: string, search: string, deps: ClaudeApiDeps, session: ApiSession): unknown {
   const dir = (deps.dir ?? claudeDir)();
   const [head = '', item = ''] = parts(path);
   if (head === LOGIN) return loginAnswer(req, item, deps);
   const single = item === '' ? SINGLETONS[head] : undefined;
-  if (single !== undefined) return single(req, deps);
+  if (single !== undefined) return single(req, deps, session);
   if (req.method === 'PUT') return writeAnswer(req, path, search, dir);
   if (req.method === 'POST') return created(req, path, dir);
   return answer(req.method ?? 'GET', path, new URLSearchParams(search), dir);
@@ -375,7 +272,7 @@ export function handleClaudeRequest(
       if (!session) throw new ApiError('unauthorized', 401);
       if (req.method !== 'GET' && ADMIN_ONLY.test(path)) requireAdmin(session);
       if (await streamed(req, res, path, search, (deps.dir ?? claudeDir)())) return;
-      sendJson(req, res, 200, await routed(req, path, search, deps));
+      sendJson(req, res, 200, await routed(req, path, search, deps, session));
     })
     .catch((err: unknown) => {
       if (err instanceof ApiError) apiFailure(req, res, err, 'claude-api');

package/runtime/node_modules/@metro-labs/daemon/src/claude/runner-activity.ts

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { parseRunnerActivity, type RunnerActivity } from '@metro-labs/core/runner-activity';
+import { readRange } from '../agent-user/agent-fs.js';
+
+const MAX_BYTES = 65_536;
+
+export function readAgentActivity(home: string): RunnerActivity | null {
+  try {
+    const path = join(home, '.metro', 'agent-status.json');
+    const bytes = readRange(path, 0, MAX_BYTES + 1);
+    if (bytes.length > MAX_BYTES) return null;
+    const raw: unknown = JSON.parse(bytes.toString('utf8'));
+    return parseRunnerActivity(raw);
+  } catch {
+    return null;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/runner-process.ts

@@ -0,0 +1,50 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { RunnerActivity } from '@metro-labs/core/runner-activity';
+import { ApiError } from '@metro-labs/http/api-error';
+import { asAgent } from '../agent-user/user.js';
+import { readAgentActivity } from './runner-activity.js';
+
+function identity(pid: number): { started: string; zombie: boolean } | null {
+  try {
+    const stat = readFileSync(`/proc/${String(pid)}/stat`, 'utf8');
+    const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+    return { started: fields[19] ?? '', zombie: fields[0] === 'Z' };
+  } catch {
+    return null;
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return isRecord(err) && err.code === 'EPERM';
+  }
+}
+
+export function sdkAlive(activity: RunnerActivity | null): boolean {
+  if (activity === null) return false;
+  const found = identity(activity.pid);
+  if (found?.zombie === true) return false;
+  if (activity.procStart !== undefined && found !== null && activity.procStart !== found.started) return false;
+  if (activity.procStart === undefined && activity.phase === 'stopped') return false;
+  return pidAlive(activity.pid);
+}
+
+function assertIdentity(activity: RunnerActivity): void {
+  const found = identity(activity.pid);
+  if (activity.pid === process.pid || activity.procStart === undefined || activity.procStart !== found?.started)
+    throw new ApiError('The Agent SDK is still running outside tmux, but its process identity cannot be verified safely. Stop that metro agent process from its terminal.', 503);
+}
+
+export function stopSdkRunner(home: string): void {
+  const activity = readAgentActivity(home);
+  if (activity === null || !sdkAlive(activity)) return;
+  assertIdentity(activity);
+  const run = spawnSync(...asAgent('kill', ['-TERM', String(activity.pid)]), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if ((run.error !== undefined || run.status !== 0) && sdkAlive(activity))
+    throw new ApiError(`The Agent SDK could not be stopped: ${run.error?.message ?? run.stderr.trim()}`, 503);
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/runner.ts

@@ -0,0 +1,45 @@
+import { agentsDir } from '../agents/files.js';
+import type { CodexMethod } from '../gateway/codex-auth.js';
+import { connectionOf, readModelConfig, routedConnection, type Connection, type ModelConfig } from '../gateway/model-config.js';
+import { readSetupState, writeSetupState } from './setup-state.js';
+
+const RUNNERS = ['cli', 'sdk'] as const;
+export type HarnessRunner = (typeof RUNNERS)[number];
+
+export const SDK_NEEDS_KEY =
+  'The Agent SDK runner needs an API key or a ChatGPT sign-in on every model the Model page lists, the first one and each fallback: use Anthropic with an API key, Amazon Bedrock, OpenRouter, or a signed-in Codex connection (with ChatGPT or with a code). Anthropic does not allow products built on the Agent SDK to use a Claude login, so on a login it runs only where the Metro operator allows it.';
+
+export const isHarnessRunner = (value: unknown): value is HarnessRunner => RUNNERS.some((r) => r === value);
+
+export function harnessRunner(agents = agentsDir()): HarnessRunner {
+  const runner = readSetupState(agents).runner;
+  return isHarnessRunner(runner) ? runner : 'cli';
+}
+
+export function setHarnessRunner(runner: HarnessRunner, agents = agentsDir()): void {
+  writeSetupState(agents, { runner });
+}
+
+export const sdkOnLogin = (agents = agentsDir()): boolean => readSetupState(agents).sdkOnLogin === true;
+
+export function setSdkOnLogin(on: boolean, agents = agentsDir()): void {
+  writeSetupState(agents, { sdkOnLogin: on });
+}
+
+const SDK_ON_CODEX: Record<CodexMethod, boolean> = { chatgpt: true, code: true };
+
+const permitted = (conn: Connection | null): boolean => conn !== null && (conn.apiKey !== '' || (conn.codex !== null && SDK_ON_CODEX[conn.codex.method]));
+
+const servingConnections = (cfg: ModelConfig): (Connection | null)[] => [routedConnection(cfg), ...(cfg.fallbacks ?? []).map((f) => connectionOf(cfg, f.connection))];
+
+const permittedRoute = (cfg: ModelConfig): boolean => servingConnections(cfg).every(permitted);
+
+export const sdkAllowed = (agents = agentsDir(), cfg: ModelConfig = readModelConfig(agents), loginAllowed?: boolean): boolean => permittedRoute(cfg) || (loginAllowed ?? sdkOnLogin(agents));
+
+export const sdkConnectionAllowed = (connection: Connection, agents = agentsDir()): boolean => permitted(connection) || sdkOnLogin(agents);
+
+export function runnerModel(cfg: ModelConfig): string | null {
+  const conn = routedConnection(cfg);
+  if (conn === null || conn.model === '') return null;
+  return conn.provider === 'anthropic' ? conn.model : `${conn.provider}:${conn.model}`;
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/session-continuity.ts

@@ -0,0 +1,48 @@
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { readJson, writeJson } from '@metro-labs/core/secure-fs';
+import { agentsDir } from '../agents/files.js';
+import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
+import { claudeDir } from './files.js';
+
+const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const sessionId = (value: unknown): string | null => typeof value === 'string' && SESSION_ID_RE.test(value) ? value : null;
+
+function sdkSavedSession(home: string): Record<string, unknown> | null {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(join(home, '.metro', 'agent-session.json'), 'utf8'));
+    return isRecord(raw) ? raw : null;
+  } catch (err) {
+    return isRecord(err) && err.code === 'ENOENT' ? {} : null;
+  }
+}
+
+export function sdkPending(home: string): number | null {
+  const state = sdkSavedSession(home);
+  if (state === null) return null;
+  if (state.sessionId !== undefined && state.sessionId !== null && sessionId(state.sessionId) === null) return null;
+  if (state.unanswered === undefined) return 0;
+  return Array.isArray(state.unanswered) ? state.unanswered.length : null;
+}
+
+function projectFolder(home: string, dir: string): string {
+  let cwd = home;
+  try {
+    cwd = realpathSync(home);
+  } catch {
+    cwd = home;
+  }
+  return join(dir, 'projects', cwd.replace(/[^A-Za-z0-9]/g, '-'));
+}
+
+export function continueArgs(home: string, dir = claudeDir(), agents = agentsDir()): string[] {
+  const path = join(agents, 'claude-session.json');
+  const raw = readJson<unknown>(path, null);
+  const state = isRecord(raw) ? raw : {};
+  const project = projectFolder(home, dir);
+  const pinned = sessionId(state.cliSessionId);
+  const id = pinned ?? randomUUID();
+  if (pinned === null) writeJson(path, { ...state, cliSessionId: id });
+  return [existsSync(join(project, `${id}.jsonl`)) ? '--resume' : '--session-id', id];
+}

package/runtime/node_modules/@metro-labs/daemon/src/claude/session.ts

@@ -1,5 +1,10 @@
-import { spawnSync } from 'node:child_process';
-import { realpathSync } from '../agent-user/agent-fs.js';
+import { spawn, spawnSync } from 'node:child_process';
+import { ApiError } from '@metro-labs/http/api-error';
+import type { RunnerActivity } from '@metro-labs/core/runner-activity';
+import { readAgentActivity } from './runner-activity.js';
+import { sdkAlive, stopSdkRunner } from './runner-process.js';
+import { continueArgs, sdkPending } from './session-continuity.js';
+import { syncAgentView } from '../agent-user/view.js';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { errMsg, log } from '@metro-labs/core/log';
@@ -8,7 +13,8 @@ import { readJson, writeJson } from '@metro-labs/core/secure-fs';
 import { METRO_VERSION } from '@metro-labs/core/version';
 import { agentsDir, listAgentFiles } from '../agents/files.js';
 import { notReady, readModelConfig, routedConnection } from '../gateway/model-config.js';
-import { claudeDir, listClaudeProjects } from './files.js';
+import { claudeDir } from './files.js';
+import { harnessRunner, isHarnessRunner, sdkAllowed, SDK_NEEDS_KEY, type HarnessRunner } from './runner.js';
 import { claudeAccount, claudeInstalled } from './login.js';
 import { trustFolder } from './onboarding.js';
 import { inSessionScope } from './memory.js';
@@ -35,17 +41,20 @@ const PAUSE_MS = 30 * 60_000;
 export interface SessionDeps {
   tmux?: string;
   metro?: string[];
+  runner?: string[];
   home?: string;
   agents?: string;
   signedIn?: () => boolean;
   now?: () => number;
   version?: string;
-  continues?: (home: string) => boolean;
+  prepare?: (runner: HarnessRunner) => Promise<void>;
 }
 
 export interface SessionStatus {
   name: string;
   running: boolean;
+  runner?: HarnessRunner;
+  activity?: RunnerActivity | null;
   autostart: boolean;
   blocked: string | null;
   lastStartedAt: string | null;
@@ -92,24 +101,6 @@ export const sessionRunning = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['has-ses
 
 export const tmuxServerUp = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['list-sessions']);
 
-function realDir(dir: string): string {
-  try {
-    return realpathSync(dir);
-  } catch {
-    return dir;
-  }
-}
-
-const encodedCwd = (dir: string): string => dir.replace(/[^A-Za-z0-9]/g, '-');
-
-export function hasConversation(home: string, dir = claudeDir()): boolean {
-  const cwd = realDir(home);
-  const folder = encodedCwd(cwd);
-  return listClaudeProjects(dir).some(
-    (project) => project.sessions > 0 && (project.id === folder || (project.cwd !== null && realDir(project.cwd) === cwd)),
-  );
-}
-
 export function metroCli(args: string[], fixed?: string[]): string[] {
   const bin = process.env.METRO_CLI_BIN?.trim() ?? '';
   const runtime = agentUser() === null ? process.execPath : 'node';
@@ -118,10 +109,53 @@ export function metroCli(args: string[], fixed?: string[]): string[] {
   return env.length === 0 || fixed !== undefined ? base : ['env', ...env, ...base];
 }
 
+const sessionHome = (deps: SessionDeps): string => deps.home ?? claudeHome() ?? homedir();
+
+export function sessionRunner(deps: SessionDeps = {}): HarnessRunner {
+  const agents = deps.agents ?? agentsDir();
+  const runner = readState(agents).runner;
+  return isHarnessRunner(runner) ? runner : harnessRunner(agents);
+}
+
+export function assertSessionStopped(deps: SessionDeps = {}): void {
+  if (sessionLive(deps)) throw new ApiError('The session is running. Let it finish its work, stop it, then change its runner, permissions or prompt and start it again.', 409);
+}
+
+export function assertSdkDrained(deps: SessionDeps = {}): void {
+  if (sdkPending(sessionHome(deps)) !== 0)
+    throw new ApiError('The Agent SDK still has chat messages it has not answered, or its saved state cannot be read. Start it so it answers them (fix the Model page first if it cannot start), stop it, then switch runners.', 409);
+}
+
+let changing = false;
+
+export async function withSessionChange<T>(run: () => Promise<T>): Promise<T> {
+  if (changing) throw new ApiError('A session change is already being prepared. Try again when it finishes.', 409);
+  changing = true;
+  try {
+    return await run();
+  } finally {
+    changing = false;
+  }
+}
+
+export async function prepareSessionRunner(runner: HarnessRunner, deps: SessionDeps = {}): Promise<void> {
+  if (deps.prepare !== undefined) return deps.prepare(runner);
+  const [bin = 'metro', ...args] = metroCli(['agent', '--prepare', runner]);
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(...asAgent(bin, args), { stdio: ['ignore', 'ignore', 'pipe'], timeout: 16 * 60_000 });
+    let error = '';
+    child.stderr.on('data', (chunk: Buffer) => { error = (error + chunk.toString()).slice(-2000); });
+    child.on('error', (err) => { reject(new ApiError(`Runner preparation failed: ${errMsg(err)}`, 503)); });
+    child.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new ApiError(`Runner preparation failed. The runner choice was not changed. ${error.trim()}`, 503));
+    });
+  });
+}
+
 function metroCommand(deps: SessionDeps, home: string): string[] {
-  const command = metroCli(['claude'], deps.metro);
-  const continues = (deps.continues ?? hasConversation)(home);
-  return continues ? [...command, '-c'] : command;
+  if (harnessRunner(deps.agents ?? agentsDir()) === 'sdk') return metroCli(['agent'], deps.runner);
+  return [...metroCli(['claude'], deps.metro), ...continueArgs(home, claudeDir(), deps.agents)];
 }
 
 function credentialReady(deps: SessionDeps): string | null {
@@ -130,7 +164,7 @@ function credentialReady(deps: SessionDeps): string | null {
   try {
     const cfg = readModelConfig(deps.agents ?? agentsDir());
     const conn = routedConnection(cfg);
-    if (conn !== null && conn.provider !== 'anthropic' && notReady(cfg) === null) return null;
+    if (conn !== null && notReady(cfg) === null && (conn.provider !== 'anthropic' || conn.apiKey !== '')) return null;
   } catch (err) {
     return `the Model page is not readable (${errMsg(err)})`;
   }
@@ -145,7 +179,12 @@ const ROOT_REFUSED = 'Metro runs as root; reinstall it as the metro user';
 export function sessionBlocked(deps: SessionDeps = {}): string | null {
   if (runningAsRoot()) return ROOT_REFUSED;
   const agents = deps.agents ?? agentsDir();
+  if (harnessRunner(agents) === 'sdk' && !sdkAllowed(agents)) return SDK_NEEDS_KEY;
   if (listAgentFiles(agents).length === 0) return 'no agent on this machine yet';
+  return launchBlocked(deps);
+}
+
+function launchBlocked(deps: SessionDeps): string | null {
   if (agentUserMissing(deps))
     return 'Claude Code runs as the user agent here, and that user is not ready yet; see the log';
   if (deps.metro === undefined && !claudeInstalled()) return 'Claude Code is not installed on this machine';
@@ -190,18 +229,29 @@ function recordStart(deps: SessionDeps, tmux: string, now: number, run: { error?
     return;
   }
   memory.lastError = null;
-  writeState(deps.agents ?? agentsDir(), { version: deps.version ?? METRO_VERSION });
+  const agents = deps.agents ?? agentsDir();
+  writeState(agents, { version: deps.version ?? METRO_VERSION, runner: harnessRunner(agents) });
   confirmChannels(tmux, now + CONFIRM_WAIT_MS);
 }
 
+function tmuxLaunch(deps: SessionDeps, tmux: string, args: string[]): [string, string[]] {
+  const launch = asAgent(tmux, args);
+  return deps.tmux === undefined && !tmuxServerUp(tmux) ? inSessionScope(launch) : launch;
+}
+
 export function startSession(deps: SessionDeps = {}): SessionStatus {
+  if (changing) throw new ApiError('A runner change is being prepared. Start the session after it finishes.', 409);
+  const status = sessionStatus(deps);
+  if (status.running) return status;
+  if (status.blocked !== null) throw new ApiError(`Cannot start the session: ${status.blocked}`, 409);
+  syncAgentView(undefined, deps.agents);
   const tmux = deps.tmux ?? 'tmux';
-  const home = deps.home ?? claudeHome() ?? homedir();
+  const home = sessionHome(deps);
   const now = (deps.now ?? Date.now)();
   const trusted = trustFolder(home);
   const [command = 'metro', ...args] = metroCommand(deps, home);
   const tmuxArgs = ['new-session', '-d', '-s', SESSION_NAME, '-c', home, '-x', '200', '-y', '50', command, ...args];
-  const launch = deps.tmux === undefined && !tmuxServerUp(tmux) ? inSessionScope(asAgent(tmux, tmuxArgs)) : asAgent(tmux, tmuxArgs);
+  const launch = tmuxLaunch(deps, tmux, tmuxArgs);
   const run = spawnSync(...launch, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], cwd: '/' });
   recordStart(deps, tmux, now, run);
   if (memory.lastError === null) log.info({ home, trusted, command: [command, ...args].join(' ') }, 'claude-session: started Claude Code in tmux');
@@ -210,13 +260,21 @@ export function startSession(deps: SessionDeps = {}): SessionStatus {
 
 export function stopSession(deps: SessionDeps = {}): SessionStatus {
   spawnSync(...asAgent(deps.tmux ?? 'tmux', ['kill-session', '-t', SESSION_NAME]), { stdio: 'ignore' });
+  stopSdkRunner(sessionHome(deps));
   return sessionStatus(deps);
 }
 
+export const sessionLive = (deps: SessionDeps = {}): boolean =>
+  sessionRunning(deps.tmux ?? 'tmux') || sdkAlive(readAgentActivity(sessionHome(deps)));
+
 export function sessionStatus(deps: SessionDeps = {}): SessionStatus {
+  const activity = readAgentActivity(sessionHome(deps));
+  const sdk = sdkAlive(activity);
   return {
     name: SESSION_NAME,
-    running: sessionRunning(deps.tmux ?? 'tmux'),
+    running: sessionRunning(deps.tmux ?? 'tmux') || sdk,
+    runner: sdk ? 'sdk' : sessionRunner(deps),
+    activity,
     autostart: autostartEnabled(deps.agents ?? agentsDir()),
     blocked: sessionBlocked(deps),
     lastStartedAt: memory.lastStartedAt === null ? null : new Date(memory.lastStartedAt).toISOString(),
@@ -264,8 +322,9 @@ function situation(r: Resolved): 'running' | 'stale' | 'absent' {
 export function ensureSession(deps: SessionDeps = {}): Ensured {
   const r = resolved(deps);
   if (!autostartEnabled(r.agents)) return 'off';
+  if (changing) return 'blocked';
   const found = situation(r);
-  if (found === 'running') return 'running';
+  if (found === 'running' || (found === 'absent' && sessionLive(deps))) return 'running';
   const held = holdsBack(deps, r.now);
   if (held !== null) return held;
   if (found === 'stale') {