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

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

@@ -0,0 +1,242 @@
+import { randomBytes } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { markOnboardingDone } from './onboarding.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { agentCommand, asAgent, claudeBin } from '../agent-user/user.js';
+
+const LOGIN_ARGS = ['auth', 'login', '--claudeai'];
+const STATUS_COMMAND = ['auth', 'status', '--json'];
+const TTL_MS = 10 * 60_000;
+const OUTPUT_MAX = 8_000;
+const COLS = 100;
+const ROWS = 40;
+const ESC = String.fromCharCode(27);
+const CSI = /^\[[0-9;?]*[a-zA-Z]/;
+const URL_RE = /https:\/\/[^\s"'`]+/g;
+
+type LoginState = 'pending' | 'done' | 'failed';
+
+export interface LoginView {
+  id: string;
+  state: LoginState;
+  url: string | null;
+  output: string;
+  error: string | null;
+}
+
+export interface LoginTarget {
+  key: string;
+  env: Record<string, string>;
+  settle: (ok: boolean) => Promise<string | null>;
+}
+
+interface Live {
+  id: string;
+  startedAt: number;
+  state: LoginState;
+  output: string;
+  error: string | null;
+  target: LoginTarget | null;
+  write: (text: string) => void;
+  kill: () => void;
+}
+
+export interface LoginDeps {
+  command?: string[];
+}
+
+let live: Live | null = null;
+
+export function plainText(raw: string): string {
+  return raw
+    .split(ESC)
+    .map((part, index) => (index === 0 ? part : part.replace(CSI, '')))
+    .join('');
+}
+
+export function loginUrlIn(output: string): string | null {
+  const found = output.match(URL_RE) ?? [];
+  const trimmed = found.map((url) => url.replace(/[.,)]+$/, ''));
+  return trimmed.find((url) => url.includes('claude.ai') || url.includes('anthropic.com')) ?? trimmed[0] ?? null;
+}
+
+const view = (session: Live): LoginView => ({
+  id: session.id,
+  state: session.state,
+  url: loginUrlIn(session.output),
+  output: session.output,
+  error: session.error,
+});
+
+function sweep(now: number): void {
+  if (live !== null && live.state !== 'pending') return;
+  if (live !== null && now - live.startedAt > TTL_MS) {
+    live.kill();
+    live = null;
+  }
+}
+
+const CHECK_MS = 30_000;
+
+interface Checked<T> {
+  at: number;
+  value: T;
+}
+
+const checks: { installed?: Checked<boolean>; account?: Checked<ClaudeAccount> } = {};
+
+function remembered<T>(slot: Checked<T> | undefined, read: () => T, keep: (c: Checked<T>) => void): T {
+  const now = Date.now();
+  if (slot !== undefined && now - slot.at < CHECK_MS) return slot.value;
+  const value = read();
+  keep({ at: now, value });
+  return value;
+}
+
+function forgetClaudeChecks(): void {
+  delete checks.installed;
+  delete checks.account;
+}
+
+export function claudeInstalled(): boolean {
+  return remembered(checks.installed, () => {
+    const run = spawnSync(...asAgent(claudeBin(), ['--version']), { stdio: 'ignore' });
+    return run.error === undefined && run.status === 0;
+  }, (c) => {
+    checks.installed = c;
+  });
+}
+
+export interface ClaudeAccount {
+  signedIn: boolean;
+  account: string | null;
+  plan: string | null;
+}
+
+const SIGNED_OUT: ClaudeAccount = { signedIn: false, account: null, plan: null };
+
+export function claudeAccount(): ClaudeAccount {
+  return remembered(checks.account, () => claudeAccountIn({}), (c) => {
+    checks.account = c;
+  });
+}
+
+const textOf = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null);
+
+export function claudeAccountIn(env: Record<string, string>): ClaudeAccount {
+  const run = spawnSync(...asAgent(claudeBin(), STATUS_COMMAND, env), { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, ...env } });
+  if (run.error !== undefined || typeof run.stdout !== 'string') return SIGNED_OUT;
+  try {
+    const parsed: unknown = JSON.parse(run.stdout);
+    if (!isRecord(parsed)) return SIGNED_OUT;
+    const account = textOf(parsed.email) ?? textOf(parsed.organization) ?? textOf(parsed.orgName);
+    return { signedIn: parsed.authenticated === true || parsed.loggedIn === true || account !== null, account, plan: textOf(parsed.subscriptionType) };
+  } catch {
+    return SIGNED_OUT;
+  }
+}
+
+function note(session: Live, chunk: string): void {
+  const next = session.output + plainText(chunk);
+  session.output = next.length > OUTPUT_MAX ? next.slice(next.length - OUTPUT_MAX) : next;
+}
+
+async function verdict(session: Live, code: number): Promise<string | null> {
+  const problem = code === 0 ? null : `the login ended with status ${String(code)}`;
+  if (session.target === null) return problem;
+  try {
+    return (await session.target.settle(problem === null)) ?? problem;
+  } catch (err) {
+    return errMsg(err);
+  }
+}
+
+function runningFor(target: LoginTarget | null): Live | null {
+  if (live === null || live.state !== 'pending') return null;
+  if (live.target?.key === target?.key) return live;
+  live.kill();
+  live = null;
+  return null;
+}
+
+export function startClaudeLogin(deps: LoginDeps = {}, now = Date.now(), target: LoginTarget | null = null): LoginView {
+  sweep(now);
+  const running = runningFor(target);
+  if (running !== null) return view(running);
+  const env = { TERM: 'xterm-256color', ...target?.env };
+  const command = deps.command ?? agentCommand([claudeBin(), ...LOGIN_ARGS], env);
+  const session: Live = {
+    id: randomBytes(9).toString('base64url'),
+    startedAt: now,
+    state: 'pending',
+    output: '',
+    error: null,
+    target,
+    write: () => undefined,
+    kill: () => undefined,
+  };
+  const terminal = new Bun.Terminal({
+    cols: COLS,
+    rows: ROWS,
+    data: (_term, chunk: Uint8Array) => {
+      note(session, Buffer.from(chunk).toString('utf8'));
+    },
+  });
+  const proc = Bun.spawn(command, { terminal, env: { ...process.env, ...env } });
+  session.write = (text: string) => {
+    terminal.write(Buffer.from(`${text}\r`, 'utf8'));
+  };
+  session.kill = () => {
+    proc.kill();
+    terminal.close();
+  };
+  proc.exited
+    .then(async (code) => {
+      session.write = () => undefined;
+      terminal.close();
+      forgetClaudeChecks();
+      session.error = await verdict(session, code);
+      session.state = session.error === null ? 'done' : 'failed';
+      const onboarding = session.error === null ? markOnboardingDone() : 'skipped';
+      log.info({ state: session.state, onboarding, own: session.target !== null }, 'claude-login: the official login finished');
+    })
+    .catch((err: unknown) => {
+      session.state = 'failed';
+      session.error = errMsg(err);
+    });
+  live = session;
+  log.info({ command: command[0] }, 'claude-login: started');
+  return view(session);
+}
+
+function current(id: string): Live {
+  const session = live;
+  if (session?.id !== id) throw new ApiError('that sign-in is over; start another one', 404);
+  return session;
+}
+
+export function claudeLoginView(id: string, now = Date.now()): LoginView {
+  sweep(now);
+  return view(current(id));
+}
+
+export function answerClaudeLogin(id: string, text: string): LoginView {
+  const session = current(id);
+  if (session.state !== 'pending') throw new ApiError('that sign-in has already finished', 409);
+  session.write(text);
+  return view(session);
+}
+
+export function endClaudeLogin(id: string): { ended: true } {
+  const session = current(id);
+  session.kill();
+  live = null;
+  return { ended: true };
+}
+
+export const forgetClaudeLogin = (): void => {
+  live?.kill();
+  live = null;
+};

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

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import { errMsg, log } from '@metro-labs/core/log';
+import { existsSync, readFileSync } from '../agent-user/agent-fs.js';
+import { readCrontab, withBlock, writeCrontab } from '../agent-user/crontab.js';
+import { writeHomeText } from '../agent-user/home-fs.js';
+import { listSchedules, parseCronLine, realRunner, type Runner } from '../agent-user/schedules.js';
+import { agentPath, agentUser, type AgentUser } from '../agent-user/user.js';
+
+const BEGIN = '# metro memory routine: begin';
+const END = '# metro memory routine: end';
+const REPLACED = '# replaced by memory-routine: ';
+const OWN_JOB = /memory/i;
+const SCHEDULE = '0 0,12 * * *';
+
+export type MemoryJobState = 'scheduled' | 'own' | 'off' | 'unavailable';
+
+export interface MemoryJob {
+  state: MemoryJobState;
+  job: string | null;
+}
+
+export interface MemoryJobDeps {
+  user?: AgentUser | null;
+  runner?: Runner;
+  cli?: string;
+  port?: string;
+}
+
+let last: MemoryJob = { state: 'unavailable', job: null };
+
+export const memoryJobStatus = (): MemoryJob => ({ ...last });
+
+export const launcherPath = (user: AgentUser): string => join(user.home, '.metro', 'bin', 'memory-routine');
+export const skillPath = (user: AgentUser): string => join(user.home, '.claude', 'skills', 'memory', 'SKILL.md');
+const logPath = (user: AgentUser): string => join(user.home, '.metro', 'memory-routine.log');
+const quoted = (text: string): string => `'${text.replace(/'/g, '\'\\\'\'')}'`;
+
+export function launcherText(user: AgentUser, cli: string, port: string): string {
+  return [
+    '#!/bin/sh',
+    `PATH=${quoted(agentPath(user))}`,
+    'export PATH',
+    ...(port === '' ? [] : [`METRO_WEBHOOK_PORT=${quoted(port)}`, 'export METRO_WEBHOOK_PORT']),
+    'cd "$HOME" || exit 1',
+    `exec node ${quoted(cli)} memory "$@"`,
+    '',
+  ].join('\n');
+}
+
+export const cronLine = (user: AgentUser): string => `${SCHEDULE} ${launcherPath(user)} ${skillPath(user)} >> ${logPath(user)} 2>&1`;
+
+const commandName = (command: string): string => command.split(/\s+/)[0]?.split('/').pop() ?? 'cron';
+
+const ownCommand = (user: AgentUser, line: string): string | null => {
+  const parsed = parseCronLine(line);
+  return parsed === null || parsed.command.includes(launcherPath(user)) || !OWN_JOB.test(parsed.command) ? null : parsed.command;
+};
+
+const replaces = (user: AgentUser, line: string): boolean => OWN_JOB.test(commandName(ownCommand(user, line) ?? ''));
+
+function ownJob(user: AgentUser, runner: Runner, lines: string[]): string | null {
+  const cron = lines.flatMap((line) => {
+    const command = ownCommand(user, line);
+    return command === null || replaces(user, line) ? [] : [commandName(command)];
+  });
+  const timers = listSchedules(null, runner).filter((job) => job.runsAs === user.name && OWN_JOB.test(`${job.name} ${job.command}`));
+  return cron[0] ?? timers[0]?.name ?? null;
+}
+
+const restored = (line: string): string => (line.startsWith(REPLACED) ? line.slice(REPLACED.length) : line);
+
+function marked(user: AgentUser, lines: string[], on: boolean, scheduled: boolean): string[] {
+  if (!on) return lines.map(restored);
+  return lines.map((l) => (scheduled && replaces(user, l) ? `${REPLACED}${l}` : l));
+}
+
+function placeLauncher(path: string, text: string): void {
+  if (existsSync(path) && readFileSync(path, 'utf8') === text) return;
+  writeHomeText(path, text, 0o755);
+}
+
+const envText = (name: string): string => process.env[name]?.trim() ?? '';
+
+function resolved(deps: MemoryJobDeps): Required<MemoryJobDeps> {
+  return {
+    user: deps.user === undefined ? agentUser() : deps.user,
+    runner: deps.runner ?? realRunner,
+    cli: deps.cli ?? envText('METRO_CLI_BIN'),
+    port: deps.port ?? envText('METRO_WEBHOOK_PORT'),
+  };
+}
+
+const stateOf = (scheduled: boolean, own: string | null): MemoryJobState => {
+  if (scheduled) return 'scheduled';
+  return own === null ? 'off' : 'own';
+};
+
+export function ensureMemoryJob(on: boolean, deps: MemoryJobDeps = {}): MemoryJob {
+  const { user, runner, cli, port } = resolved(deps);
+  if (user === null || cli === '') {
+    last = { state: 'unavailable', job: null };
+    return memoryJobStatus();
+  }
+  const lines = readCrontab(user, runner);
+  const own = on ? ownJob(user, runner, lines) : null;
+  const scheduled = on && own === null;
+  const launcher = launcherPath(user);
+  if (scheduled) placeLauncher(launcher, launcherText(user, cli, port));
+  const kept = marked(user, lines, on, scheduled);
+  const next = withBlock(kept, BEGIN, END, scheduled ? [cronLine(user)] : [], 'end', (l) => l.includes(launcher));
+  const changed = writeCrontab(user, runner, lines, next);
+  last = { state: stateOf(scheduled, own), job: own };
+  if (changed) log.info({ ...last, rewritten: kept.filter((l, i) => l !== lines[i]) }, 'memory-routine: updated the memory job');
+  return memoryJobStatus();
+}
+
+export function tryMemoryJob(on: boolean): void {
+  try {
+    ensureMemoryJob(on);
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'memory-routine: could not set up the daily memory job');
+  }
+}

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/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,52 @@
+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): activity is RunnerActivity {
+  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, cancelActive = false): boolean {
+  const activity = readAgentActivity(home);
+  if (!sdkAlive(activity)) return false;
+  assertIdentity(activity);
+  const signal = cancelActive && activity.cancelSignal === 'SIGUSR2' ? '-USR2' : '-TERM';
+  const run = spawnSync(...asAgent('kill', [signal, 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);
+  return true;
+}