@stage-labs/metro 0.1.0-beta.23 → 0.1.0-beta.231

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

@@ -0,0 +1,32 @@
+import { existsSync } from 'node:fs';
+import { totalmem } from 'node:os';
+import { helperArgv, runningAsMetro } from '../metro-user/privilege.js';
+
+const GIB = 1024 ** 3;
+const RESERVE = 1.5 * GIB;
+const FLOOR = GIB;
+
+export interface ScopeHost {
+  metro: boolean;
+  systemd: boolean;
+  total: number;
+}
+
+const realHost = (): ScopeHost => ({
+  metro: runningAsMetro(),
+  systemd: existsSync('/run/systemd/system'),
+  total: totalmem(),
+});
+
+export function sessionMemoryLimit(total: number): number {
+  const kept = Math.min(Math.floor(total * 0.8), total - RESERVE);
+  return Math.max(FLOOR, Math.floor(kept / (1024 * 1024)) * 1024 * 1024);
+}
+
+export function inSessionScope(command: [string, string[]], host: ScopeHost = realHost()): [string, string[]] {
+  const [file, args] = command;
+  const asAgent = file === 'sudo' && args[0] === '-n' && args[1] === '-u' && args[3] === '--';
+  if (!host.metro || !host.systemd || !asAgent) return command;
+  const limit = sessionMemoryLimit(host.total);
+  return helperArgv(['as-agent-scope', String(limit), String(Math.floor(limit * 0.9)), ...args.slice(4)]);
+}

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

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { writeHomeText } from '../agent-user/home-fs.js';
+import { agentUser } from '../agent-user/user.js';
+
+const FILE = '.claude.json';
+const FLAG = 'hasCompletedOnboarding';
+
+export type OnboardingMark = 'marked' | 'already' | 'unreadable';
+
+const given = (value: string | undefined): string | undefined =>
+  value !== undefined && value.trim() !== '' ? value.trim() : undefined;
+
+export function claudeConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const user = agentUser();
+  if (user !== null) return join(user.home, FILE);
+  return join(given(env.CLAUDE_CONFIG_DIR) ?? given(env.HOME) ?? homedir(), FILE);
+}
+
+function readConfig(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return {};
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function markOnboardingDone(path = claudeConfigPath()): OnboardingMark {
+  const config = readConfig(path);
+  if (config === null) return 'unreadable';
+  if (config[FLAG] === true) return 'already';
+  writeHomeText(path, `${JSON.stringify({ ...config, [FLAG]: true }, null, 2)}\n`, 0o600);
+  return 'marked';
+}
+
+const TRUST = 'hasTrustDialogAccepted';
+
+function realDir(dir: string): string {
+  try {
+    return realpathSync(dir);
+  } catch {
+    return dir;
+  }
+}
+
+export function trustFolder(dir: string, path = claudeConfigPath()): OnboardingMark {
+  const config = readConfig(path);
+  if (config === null) return 'unreadable';
+  const key = realDir(dir);
+  const projects = isRecord(config.projects) ? config.projects : {};
+  const project = isRecord(projects[key]) ? projects[key] : {};
+  if (project[TRUST] === true) return 'already';
+  const next = { ...config, projects: { ...projects, [key]: { ...project, [TRUST]: true } } };
+  writeHomeText(path, `${JSON.stringify(next, null, 2)}\n`, 0o600);
+  return 'marked';
+}

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

@@ -0,0 +1,149 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync, realpathSync } from '../agent-user/agent-fs.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import { agentMarketplaceDir, agentUser, asAgent, claudeBin } from '../agent-user/user.js';
+
+const MARKETPLACE = 'metro';
+const PLUGIN = 'metro@metro';
+const STEP_MS = 120_000;
+const SAID_MAX = 300;
+
+export interface Answer {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+export type Run = (args: string[]) => Promise<Answer>;
+
+export interface PluginInstallDeps {
+  run: Run | null;
+  marketplaceDir: string | null;
+}
+
+export type PluginOutcome = 'skipped' | 'unchanged' | 'installed' | 'updated' | 'failed';
+
+function storeMarketplaceDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  if (store === '') return null;
+  const dir = join(store, 'marketplace');
+  return existsSync(join(dir, '.claude-plugin', 'marketplace.json')) ? dir : null;
+}
+
+export function stagedMarketplaceDir(env: NodeJS.ProcessEnv = process.env): string | null {
+  const store = storeMarketplaceDir(env);
+  const user = agentUser();
+  if (store === null || user === null) return store;
+  const copy = agentMarketplaceDir(user);
+  return existsSync(join(copy, '.claude-plugin', 'marketplace.json')) ? copy : null;
+}
+
+export function stagedPluginVersion(dir: string): string | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(dir, 'plugin', '.claude-plugin', 'plugin.json'), 'utf8'));
+    return isRecord(parsed) && typeof parsed.version === 'string' ? parsed.version : null;
+  } catch {
+    return null;
+  }
+}
+
+const runner =
+  (bin: string): Run =>
+  (args) =>
+    new Promise((resolve) => {
+      execFile(...asAgent(bin, args), { encoding: 'utf8', timeout: STEP_MS, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const status = err === null ? 0 : typeof (err as { code?: unknown }).code === 'number' ? (err as { code: number }).code : 1;
+        resolve({ status, stdout, stderr });
+      });
+    });
+
+async function findClaude(candidates = agentUser() === null ? ['claude', join(homedir(), '.local', 'bin', 'claude')] : [claudeBin()]): Promise<Run | null> {
+  for (const bin of candidates) {
+    const run = runner(bin);
+    if ((await run(['--version'])).status === 0) return run;
+  }
+  return null;
+}
+
+function listOf(stdout: string): Record<string, unknown>[] {
+  try {
+    const parsed: unknown = JSON.parse(stdout);
+    return Array.isArray(parsed) ? parsed.filter(isRecord) : [];
+  } catch {
+    return [];
+  }
+}
+
+const realish = (path: string): string => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+};
+
+const samePath = (a: string | null, b: string): boolean => a !== null && realish(a) === realish(b);
+
+async function step(run: Run, args: string[]): Promise<boolean> {
+  const answer = await run(args);
+  if (answer.status === 0) {
+    log.info({ args }, 'plugin: claude');
+    return true;
+  }
+  log.warn({ args, said: `${answer.stderr}${answer.stdout}`.trim().slice(0, SAID_MAX) }, 'plugin: claude refused');
+  return false;
+}
+
+async function marketplacePath(run: Run): Promise<string | null | undefined> {
+  const mine = listOf((await run(['plugin', 'marketplace', 'list', '--json'])).stdout).find((m) => m.name === MARKETPLACE);
+  if (mine === undefined) return undefined;
+  const at = mine.installLocation ?? mine.path;
+  return typeof at === 'string' ? at : null;
+}
+
+async function ensureMarketplace(run: Run, dir: string): Promise<boolean> {
+  const at = await marketplacePath(run);
+  if (at !== undefined && samePath(at, dir)) return true;
+  if (at !== undefined) await step(run, ['plugin', 'marketplace', 'remove', MARKETPLACE]);
+  return step(run, ['plugin', 'marketplace', 'add', dir]);
+}
+
+async function installedVersion(run: Run): Promise<string | null> {
+  const mine = listOf((await run(['plugin', 'list', '--json'])).stdout).find((p) => p.id === PLUGIN);
+  return mine !== undefined && typeof mine.version === 'string' ? mine.version : null;
+}
+
+async function ensureInstalled(run: Run, wanted: string | null): Promise<PluginOutcome> {
+  const have = await installedVersion(run);
+  if (have === null) return (await step(run, ['plugin', 'install', PLUGIN, '-y', '--scope', 'user'])) ? 'installed' : 'failed';
+  if (wanted === null || have === wanted) return 'unchanged';
+  await step(run, ['plugin', 'marketplace', 'update', MARKETPLACE]);
+  return (await step(run, ['plugin', 'update', PLUGIN, '-y'])) ? 'updated' : 'failed';
+}
+
+function explainMissingMarketplace(env: NodeJS.ProcessEnv = process.env): void {
+  const store = env.METRO_RUNTIME_STORE?.trim() ?? '';
+  if (store === '') return;
+  log.warn(
+    { store },
+    'plugin: the runtime store holds no plugin marketplace, so metro cannot install its Claude Code plugin; restart the metro service once so `metro serve` stages it again',
+  );
+}
+
+export async function ensureMetroPlugin(deps?: Partial<PluginInstallDeps>): Promise<PluginOutcome> {
+  const dir = deps?.marketplaceDir === undefined ? stagedMarketplaceDir() : deps.marketplaceDir;
+  if (dir === null) {
+    if (deps?.marketplaceDir === undefined) explainMissingMarketplace();
+    return 'skipped';
+  }
+  const run = deps?.run === undefined ? await findClaude() : deps.run;
+  if (run === null) {
+    log.info('plugin: claude is not on this machine, so metro leaves its Claude Code plugin alone');
+    return 'skipped';
+  }
+  if (!(await ensureMarketplace(run, dir))) return 'failed';
+  return ensureInstalled(run, stagedPluginVersion(dir));
+}

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,295 @@
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from '../agent-user/agent-fs.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, listClaudeProjects } from './files.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[];
+  home?: string;
+  agents?: string;
+  signedIn?: () => boolean;
+  now?: () => number;
+  version?: string;
+  continues?: (home: string) => boolean;
+}
+
+export interface SessionStatus {
+  name: string;
+  running: boolean;
+  autostart: boolean;
+  blocked: string | null;
+  lastStartedAt: string | null;
+  lastError: 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']);
+
+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)),
+  );
+}
+
+function metroCommand(deps: SessionDeps, home: string): string[] {
+  const bin = process.env.METRO_CLI_BIN?.trim() ?? '';
+  const runtime = agentUser() === null ? process.execPath : 'node';
+  const base = deps.metro ?? (bin === '' ? ['metro', 'claude'] : [runtime, bin, 'claude']);
+  const continues = (deps.continues ?? hasConversation)(home);
+  const env = Object.entries(sessionEnv()).map(([k, v]) => `${k}=${v}`);
+  const command = env.length === 0 || deps.metro !== undefined ? base : ['env', ...env, ...base];
+  return continues ? [...command, '-c'] : command;
+}
+
+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 && conn.provider !== 'anthropic' && notReady(cfg) === null) 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 (listAgentFiles(agents).length === 0) return 'no agent on this machine yet';
+  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;
+  writeState(deps.agents ?? agentsDir(), { version: deps.version ?? METRO_VERSION });
+  confirmChannels(tmux, now + CONFIRM_WAIT_MS);
+}
+
+export function startSession(deps: SessionDeps = {}): SessionStatus {
+  const tmux = deps.tmux ?? 'tmux';
+  const home = deps.home ?? claudeHome() ?? homedir();
+  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 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 = {}): SessionStatus {
+  spawnSync(...asAgent(deps.tmux ?? 'tmux', ['kill-session', '-t', SESSION_NAME]), { stdio: 'ignore' });
+  return sessionStatus(deps);
+}
+
+export function sessionStatus(deps: SessionDeps = {}): SessionStatus {
+  return {
+    name: SESSION_NAME,
+    running: sessionRunning(deps.tmux ?? 'tmux'),
+    autostart: autostartEnabled(deps.agents ?? agentsDir()),
+    blocked: sessionBlocked(deps),
+    lastStartedAt: memory.lastStartedAt === null ? null : new Date(memory.lastStartedAt).toISOString(),
+    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';
+  const found = situation(r);
+  if (found === 'running') 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;
+}