@stage-labs/metro 0.1.0-beta.28 → 0.1.0-beta.280

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,57 @@
+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;
+  }
+}
+
+const inputState = (value: unknown): boolean => value === undefined || value === 'queued' || value === 'started';
+
+function sdkInput(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  return typeof value.text === 'string' && typeof value.at === 'number' && Number.isFinite(value.at) && (value.uuid === undefined || sessionId(value.uuid) !== null) && inputState(value.state);
+}
+
+const sdkInputs = (value: unknown): value is unknown[] | undefined => value === undefined || (Array.isArray(value) && value.every(sdkInput));
+
+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 (!sdkInputs(state.unanswered) || !sdkInputs(state.interrupted)) return null;
+  return state.unanswered?.length ?? 0;
+}
+
+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-files.ts

@@ -0,0 +1,75 @@
+import { existsSync, statSync } from '../agent-user/agent-fs.js';
+import { Transform, type Readable } from 'node:stream';
+import { moveHome, receiveHomeFile, removeHome } from '../agent-user/home-fs.js';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { claudeDir, PROJECT_RE, safeName, SESSION_RE } from './files.js';
+
+const SESSION_FILE_MAX = 512 * 1024 * 1024;
+const FILE_MODE = 0o644;
+
+export interface SessionFile {
+  id: string;
+  bytes: number;
+}
+
+const transcriptPath = (project: string, session: string, dir: string): string =>
+  join(dir, 'projects', safeName(project, PROJECT_RE, 'Claude project id'), `${safeName(session, SESSION_RE, 'session id')}.jsonl`);
+
+export function sessionFilePath(project: string, session: string, dir = claudeDir()): string {
+  const path = transcriptPath(project, session, dir);
+  if (!existsSync(path)) throw new ApiError('no such session', 404);
+  if (statSync(path).size > SESSION_FILE_MAX) throw new ApiError(`a session file is at most ${String(SESSION_FILE_MAX)} bytes`, 400);
+  return path;
+}
+
+const HEAD_BYTES = 64 * 1024;
+
+function watched(body: Readable, head: Buffer[]): Transform {
+  let total = 0;
+  let kept = 0;
+  const check = new Transform({
+    transform(chunk: Buffer, _enc, done): void {
+      total += chunk.length;
+      if (total > SESSION_FILE_MAX) {
+        done(new ApiError(`a session file is at most ${String(SESSION_FILE_MAX)} bytes`, 413));
+        return;
+      }
+      if (kept < HEAD_BYTES) {
+        head.push(chunk.subarray(0, HEAD_BYTES - kept));
+        kept += chunk.length;
+      }
+      done(null, chunk);
+    },
+  });
+  return body.pipe(check);
+}
+
+export async function receiveSessionFile(project: string, session: string, body: Readable, dir = claudeDir()): Promise<SessionFile> {
+  const path = transcriptPath(project, session, dir);
+  const tmp = `${path}.metro-upload`;
+  const head: Buffer[] = [];
+  try {
+    await receiveHomeFile(tmp, watched(body, head), FILE_MODE);
+  } catch (err) {
+    removeHome(tmp);
+    throw err;
+  }
+  if (!firstLineIsJson(Buffer.concat(head).toString('utf8'))) {
+    removeHome(tmp);
+    throw new ApiError('a session file is JSON lines, one Claude Code entry per line', 400);
+  }
+  moveHome(tmp, path);
+  return { id: safeName(session, SESSION_RE, 'session id'), bytes: statSync(path).size };
+}
+
+function firstLineIsJson(text: string): boolean {
+  const first = text.split('\n').find((line) => line.trim() !== '');
+  if (first === undefined) return false;
+  try {
+    return isRecord(JSON.parse(first));
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,375 @@
+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';
+import { isRecord } from '@metro-labs/core/is-record';
+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 } 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';
+import { runningAsRoot } from '../metro-user/privilege.js';
+import { agentExtraEnv, agentUser, agentUserExpected, agentViewDir, asAgent, claudeHome } from '../agent-user/user.js';
+
+function sessionEnv(): Record<string, string> {
+  const user = agentUser();
+  if (user === null) return {};
+  const port = process.env.METRO_WEBHOOK_PORT?.trim() ?? '';
+  return { ...agentExtraEnv(), METRO_AGENTS_DIR: agentViewDir(user), ...(port === '' ? {} : { METRO_WEBHOOK_PORT: port }) };
+}
+
+const SESSION_NAME = 'metro';
+const STATE_FILE = 'claude-session.json';
+const WARNING = 'WARNING: Loading development channels';
+const CONFIRM_POLL_MS = 500;
+const CONFIRM_WAIT_MS = 60_000;
+const WATCH_MS = 15_000;
+const STRIKE_WINDOW_MS = 60_000;
+const MAX_STRIKES = 5;
+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;
+  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;
+  lastError: string | null;
+}
+
+export interface SessionSnapshot {
+  running: boolean;
+  runner: HarnessRunner | null;
+  activity: RunnerActivity | null;
+  lastStartedAt: string | null;
+}
+
+interface Memory {
+  lastStartedAt: number | null;
+  lastError: string | null;
+  strikes: number;
+  pausedUntil: number;
+}
+
+const memory: Memory = { lastStartedAt: null, lastError: null, strikes: 0, pausedUntil: 0 };
+
+const statePath = (agents: string): string => join(agents, STATE_FILE);
+
+function readState(agents: string): Record<string, unknown> {
+  const raw = readJson<unknown>(statePath(agents), null);
+  return isRecord(raw) ? raw : {};
+}
+
+const writeState = (agents: string, patch: Record<string, unknown>): void => {
+  writeJson(statePath(agents), { ...readState(agents), ...patch });
+};
+
+export const autostartEnabled = (agents = agentsDir()): boolean => readState(agents).autostart !== false;
+
+export function setAutostart(enabled: boolean, agents = agentsDir()): void {
+  writeState(agents, { autostart: enabled });
+}
+
+function startedVersion(agents = agentsDir()): string | null {
+  const version = readState(agents).version;
+  return typeof version === 'string' ? version : null;
+}
+
+function tmuxOk(tmux: string, args: string[]): boolean {
+  const run = spawnSync(...asAgent(tmux, args), { stdio: 'ignore' });
+  return run.error === undefined && run.status === 0;
+}
+
+export const sessionRunning = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['has-session', '-t', SESSION_NAME]);
+
+export const tmuxServerUp = (tmux = 'tmux'): boolean => tmuxOk(tmux, ['list-sessions']);
+
+export function metroCli(args: string[], fixed?: string[]): string[] {
+  const bin = process.env.METRO_CLI_BIN?.trim() ?? '';
+  const runtime = agentUser() === null ? process.execPath : 'node';
+  const base = fixed ?? (bin === '' ? ['metro', ...args] : [runtime, bin, ...args]);
+  const env = Object.entries(sessionEnv()).map(([k, v]) => `${k}=${v}`);
+  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[] {
+  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 {
+  const signedIn = deps.signedIn ?? (() => claudeAccount().signedIn);
+  if (signedIn()) return null;
+  try {
+    const cfg = readModelConfig(deps.agents ?? agentsDir());
+    const conn = routedConnection(cfg);
+    if (conn !== null && notReady(cfg) === null && (conn.provider !== 'anthropic' || conn.apiKey !== '')) return null;
+  } catch (err) {
+    return `the Model page is not readable (${errMsg(err)})`;
+  }
+  return 'Claude Code is not signed in and the Model page routes nowhere yet';
+}
+
+const agentUserMissing = (deps: SessionDeps): boolean =>
+  deps.metro === undefined && agentUserExpected() && agentUser() === null;
+
+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';
+  if (!tmuxOk(deps.tmux ?? 'tmux', ['-V'])) return 'tmux is not installed on this machine';
+  return credentialReady(deps);
+}
+
+function capturePane(tmux: string): string {
+  const run = spawnSync(...asAgent(tmux, ['capture-pane', '-p', '-t', SESSION_NAME]), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return run.error === undefined && run.status === 0 ? run.stdout : '';
+}
+
+function noteLaunchLines(pane: string, seen: Set<string>): void {
+  for (const line of pane.split('\n').map((l) => l.trim()))
+    if (line.startsWith('metro claude:') && !seen.has(line)) {
+      seen.add(line);
+      log.info({ line }, 'claude-session: metro claude said');
+    }
+}
+
+function confirmChannels(tmux: string, until: number): void {
+  const seen = new Set<string>();
+  let confirmed = false;
+  const tick = (): void => {
+    const pane = capturePane(tmux);
+    noteLaunchLines(pane, seen);
+    if (!confirmed && pane.includes(WARNING) && pane.includes('server:metro')) {
+      spawnSync(...asAgent(tmux, ['send-keys', '-t', SESSION_NAME, 'Enter']), { stdio: 'ignore' });
+      log.info('claude-session: confirmed the development channels dialog for server:metro');
+      confirmed = true;
+    }
+    if (Date.now() < until && sessionRunning(tmux)) setTimeout(tick, CONFIRM_POLL_MS).unref();
+  };
+  setTimeout(tick, CONFIRM_POLL_MS).unref();
+}
+
+function recordStart(deps: SessionDeps, tmux: string, now: number, run: { error?: Error; status: number | null; stderr: string }): void {
+  memory.lastStartedAt = now;
+  if (run.error !== undefined || run.status !== 0) {
+    memory.lastError = run.error === undefined ? `tmux new-session exited ${String(run.status)}: ${run.stderr.trim()}` : errMsg(run.error);
+    log.warn({ err: memory.lastError }, 'claude-session: tmux could not start');
+    return;
+  }
+  memory.lastError = null;
+  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 = 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 = 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');
+  return sessionStatus(deps);
+}
+
+export function stopSession(deps: SessionDeps = {}, cancelActive = false): SessionStatus {
+  if (!stopSdkRunner(sessionHome(deps), cancelActive))
+    spawnSync(...asAgent(deps.tmux ?? 'tmux', ['kill-session', '-t', SESSION_NAME]), { stdio: 'ignore' });
+  return sessionStatus(deps);
+}
+
+export const sessionLive = (deps: SessionDeps = {}): boolean =>
+  sessionRunning(deps.tmux ?? 'tmux') || sdkAlive(readAgentActivity(sessionHome(deps)));
+
+export function sessionSnapshot(deps: SessionDeps = {}): SessionSnapshot {
+  const activity = readAgentActivity(sessionHome(deps));
+  const sdk = sdkAlive(activity);
+  const tmux = sessionRunning(deps.tmux ?? 'tmux');
+  const runner = sdk ? 'sdk' : tmux ? readState(deps.agents ?? agentsDir()).runner : null;
+  return {
+    running: tmux || sdk,
+    runner: isHarnessRunner(runner) ? runner : null,
+    activity,
+    lastStartedAt: memory.lastStartedAt === null ? null : new Date(memory.lastStartedAt).toISOString(),
+  };
+}
+
+export function sessionStatus(deps: SessionDeps = {}): SessionStatus {
+  const snapshot = sessionSnapshot(deps);
+  return {
+    name: SESSION_NAME,
+    ...snapshot,
+    runner: snapshot.runner ?? sessionRunner(deps),
+    autostart: autostartEnabled(deps.agents ?? agentsDir()),
+    blocked: sessionBlocked(deps),
+    lastError: memory.lastError,
+  };
+}
+
+function strike(now: number): boolean {
+  if (memory.lastStartedAt !== null && now - memory.lastStartedAt < STRIKE_WINDOW_MS) memory.strikes += 1;
+  else memory.strikes = 1;
+  if (memory.strikes < MAX_STRIKES) return false;
+  memory.pausedUntil = now + PAUSE_MS;
+  memory.strikes = 0;
+  log.warn({ pauseMinutes: PAUSE_MS / 60_000 }, 'claude-session: Claude Code keeps exiting right after starting; not restarting it for a while');
+  return true;
+}
+
+export type Ensured = 'started' | 'restarted' | 'running' | 'blocked' | 'off' | 'paused';
+
+function holdsBack(deps: SessionDeps, now: number): Ensured | null {
+  if (now < memory.pausedUntil) return 'paused';
+  if (sessionBlocked(deps) !== null) return 'blocked';
+  return strike(now) ? 'paused' : null;
+}
+
+interface Resolved {
+  now: number;
+  agents: string;
+  version: string;
+  tmux: string;
+}
+
+const resolved = (deps: SessionDeps): Resolved => ({
+  now: (deps.now ?? Date.now)(),
+  agents: deps.agents ?? agentsDir(),
+  version: deps.version ?? METRO_VERSION,
+  tmux: deps.tmux ?? 'tmux',
+});
+
+function situation(r: Resolved): 'running' | 'stale' | 'absent' {
+  if (!sessionRunning(r.tmux)) return 'absent';
+  return startedVersion(r.agents) === r.version ? 'running' : 'stale';
+}
+
+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' || (found === 'absent' && sessionLive(deps))) return 'running';
+  const held = holdsBack(deps, r.now);
+  if (held !== null) return held;
+  if (found === 'stale') {
+    log.info({ was: startedVersion(r.agents), now: r.version }, 'claude-session: restarting the session an older metro started, so the new plugin and flags load');
+    stopSession(deps);
+  }
+  startSession(deps);
+  return found === 'stale' ? 'restarted' : 'started';
+}
+
+let watcher: ReturnType<typeof setInterval> | null = null;
+
+export function watchSession(deps: SessionDeps = {}, everyMs = WATCH_MS): void {
+  if (watcher !== null) return;
+  const tick = (): void => {
+    try {
+      const outcome = ensureSession(deps);
+      if (outcome === 'started' || outcome === 'restarted') log.info({ outcome }, 'claude-session: Claude Code is up');
+    } catch (err) {
+      log.warn({ err: errMsg(err) }, 'claude-session: check failed');
+    }
+  };
+  watcher = setInterval(tick, everyMs);
+  watcher.unref();
+  setTimeout(tick, 1_000).unref();
+}
+
+export function unwatchSession(): void {
+  if (watcher !== null) clearInterval(watcher);
+  watcher = null;
+}

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

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, realpathSync, statSync } from '../agent-user/agent-fs.js';
+import { join } from 'node:path';
+import { ApiError } from '@metro-labs/http/api-error';
+import { claudeDir, listClaudeProjects } from './files.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg } from '@metro-labs/core/log';
+import { writeHomeText } from '../agent-user/home-fs.js';
+
+export const SETTINGS_MAX = 256 * 1024;
+const USER_ID = 'user';
+const LOCAL_SUFFIX = '.local';
+
+type SettingsScope = 'user' | 'project' | 'local';
+
+export interface ClaudeSettingsFile {
+  id: string;
+  scope: SettingsScope;
+  label: string;
+  path: string;
+  exists: boolean;
+  editable: boolean;
+  text: string;
+  modifiedAt: string | null;
+}
+
+const missing = (id: string, scope: SettingsScope, label: string, path: string): ClaudeSettingsFile => ({
+  id,
+  scope,
+  label,
+  path,
+  exists: false,
+  editable: true,
+  text: '',
+  modifiedAt: null,
+});
+
+function entryOf(id: string, scope: SettingsScope, label: string, path: string): ClaudeSettingsFile {
+  if (!existsSync(path)) return missing(id, scope, label, path);
+  const stat = statSync(path);
+  const editable = stat.size <= SETTINGS_MAX;
+  return {
+    id,
+    scope,
+    label,
+    path,
+    exists: true,
+    editable,
+    text: editable ? readFileSync(path, 'utf8') : '',
+    modifiedAt: stat.mtime.toISOString(),
+  };
+}
+
+const PROJECT_FILES: [string, SettingsScope, string][] = [
+  ['', 'project', 'settings.json'],
+  [LOCAL_SUFFIX, 'local', 'settings.local.json'],
+];
+
+function projectEntries(dir: string): ClaudeSettingsFile[] {
+  const out: ClaudeSettingsFile[] = [];
+  for (const project of listClaudeProjects(dir)) {
+    const cwd = project.cwd;
+    if (cwd === null) continue;
+    for (const [suffix, scope, name] of PROJECT_FILES) {
+      const path = join(cwd, '.claude', name);
+      if (existsSync(path)) out.push(entryOf(`${project.id}${suffix}`, scope, cwd, path));
+    }
+  }
+  return out;
+}
+
+const sameFile = (a: string, b: string): boolean => {
+  try {
+    return realpathSync(a) === realpathSync(b);
+  } catch {
+    return a === b;
+  }
+};
+
+export function listClaudeSettings(dir = claudeDir()): ClaudeSettingsFile[] {
+  const user = entryOf(USER_ID, 'user', 'This machine', join(dir, 'settings.json'));
+  return [user, ...projectEntries(dir).filter((p) => !sameFile(p.path, user.path))];
+}
+
+function assertSettingsJson(text: string): void {
+  if (text.length > SETTINGS_MAX) throw new ApiError('that is more text than a settings file may hold', 413);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new ApiError(`that is not valid JSON: ${errMsg(err)}`, 400);
+  }
+  if (!isRecord(parsed)) throw new ApiError('Claude Code settings must be a JSON object', 400);
+}
+
+export function writeClaudeSettings(
+  id: string,
+  text: string,
+  seenAt: string | null | undefined,
+  dir = claudeDir(),
+): ClaudeSettingsFile {
+  const target = listClaudeSettings(dir).find((file) => file.id === id);
+  if (target === undefined) throw new ApiError('no such settings file', 404);
+  if (!target.editable) throw new ApiError('that settings file is too large to edit here', 409);
+  assertSettingsJson(text);
+  if (seenAt !== undefined && seenAt !== target.modifiedAt)
+    throw new ApiError('that file changed on disk since you opened it; reload it before saving', 409);
+  writeHomeText(target.path, text, existsSync(target.path) ? statSync(target.path).mode & 0o777 : 0o644);
+  return entryOf(target.id, target.scope, target.label, target.path);
+}