@stage-labs/metro 0.1.0-beta.294 → 0.1.0-beta.295

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.294",
+  "version": "0.1.0-beta.295",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.294",
+  "version": "0.1.0-beta.295",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

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

@@ -26,6 +26,9 @@ const FAILURE = {
   status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
   saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
   executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  module: 'The SDK runtime could not load a required module. Prepare the SDK runtime again.',
+  configuration: 'The SDK launch configuration is missing or invalid. Check Harness and the Model page before starting.',
+  process_exit: 'The SDK process exited unexpectedly. Check its reported exit code or signal before retrying.',
   connection: 'The SDK connection failed. Check the server and provider connection.',
   session_ended: 'The Agent SDK session ended unexpectedly.',
   interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
@@ -33,8 +36,40 @@ const FAILURE = {
 } as const;
 export type RunnerFailureCode = keyof typeof FAILURE;
 
-export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null): string {
-  return code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+const ERROR_CODES = ['ENOENT', 'EACCES', 'EPERM', 'ENOEXEC', 'ENOMEM', 'ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ERR_DLOPEN_FAILED', 'ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'] as const;
+const SIGNALS = ['SIGTERM', 'SIGKILL', 'SIGSEGV', 'SIGABRT', 'SIGBUS', 'SIGILL', 'SIGINT', 'SIGHUP', 'SIGPIPE'] as const;
+
+export interface RunnerDiagnostic {
+  source: 'exception' | 'stderr';
+  errorCode?: (typeof ERROR_CODES)[number];
+  httpStatus?: number;
+  exitCode?: number;
+  signal?: (typeof SIGNALS)[number];
+}
+
+const boundedNumber = (value: unknown, min: number, max: number): number | undefined => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max ? value : undefined;
+
+export function runnerDiagnostic(raw: unknown): RunnerDiagnostic | undefined {
+  if (!isRecord(raw) || (raw.source !== 'exception' && raw.source !== 'stderr')) return undefined;
+  const errorCode = ERROR_CODES.find((code) => code === raw.errorCode);
+  const signal = SIGNALS.find((value) => value === raw.signal);
+  const httpStatus = boundedNumber(raw.httpStatus, 400, 599);
+  const exitCode = boundedNumber(raw.exitCode, 0, 255);
+  return {
+    source: raw.source,
+    ...(errorCode === undefined ? {} : { errorCode }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(exitCode === undefined ? {} : { exitCode }),
+    ...(signal === undefined ? {} : { signal }),
+  };
+}
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null, diagnostic?: RunnerDiagnostic): string {
+  const summary = code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+  const safe = runnerDiagnostic(diagnostic);
+  if (safe === undefined) return summary;
+  const details = [safe.errorCode, safe.httpStatus === undefined ? null : `HTTP ${safe.httpStatus}`, safe.exitCode === undefined ? null : `exit ${safe.exitCode}`, safe.signal].filter((value) => value !== undefined && value !== null);
+  return details.length === 0 ? summary : `${summary} Observed: ${details.join(', ')} (${safe.source === 'stderr' ? 'startup stderr' : 'exception'}).`;
 }
 
 export interface RunnerTask {
@@ -70,6 +105,7 @@ export interface RunnerEvent {
   toolUseId?: string;
   taskId: string | null;
   code?: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
 }
 
 export interface RunnerFailure extends RunnerEvent {
@@ -146,16 +182,17 @@ function tool(raw: unknown): RunnerTool | null {
   return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
 }
 
-const failureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+export const runnerFailureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
 const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
 
 function event(raw: unknown): RunnerEvent | null {
   if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
   return {
     at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
     ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
     ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
-    ...(failureKind(raw.kind) && failureCode(raw.code) ? { code: raw.code } : {}),
+    ...(failureKind(raw.kind) && runnerFailureCode(raw.code) ? { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) } : {}),
   };
 }
 
@@ -184,7 +221,7 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
 function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
   const activeFailure = failure(raw.activeFailure);
   return {
-    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool) : safeError(raw.lastError),
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool, activeFailure.diagnostic) : safeError(raw.lastError),
     ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
     ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
   };

package/runtime/node_modules/@metro-labs/daemon/src/channels/relay.ts

@@ -42,6 +42,10 @@ export class ChannelRelay {
     });
   }
 
+  whenIdle(): Promise<void> {
+    return this.chain;
+  }
+
   replayMissed(): void {
     const missed = bufferedSince(this.ledger.startAt).filter(
       (b) => !this.ledger.delivered.has(b.busSeq),

package/runtime/node_modules/@metro-labs/daemon/src/mcp/index.ts

@@ -84,7 +84,7 @@ async function serveGet(
     scope: session.scope,
     req,
     res,
-    previous: session.currentSink,
+    previous: () => session.currentSink,
     log: channelLog,
     registerSink: (sink) => {
       session.bindSink(sink);

package/runtime/node_modules/@metro-labs/daemon/src/mcp/raw-get-stream.ts

@@ -55,6 +55,9 @@ export interface RawGetSink {
   close: () => void;
 }
 
+const streamEnded = (sink: RawGetSink, res: ServerResponse): boolean =>
+  sink.closed || res.destroyed || res.writableEnded;
+
 export interface ValidateResult {
   ok: boolean;
   status?: number;
@@ -93,6 +96,7 @@ export interface ServeOpts {
   res: ServerResponse;
   log: (...a: unknown[]) => void;
   registerSink: (sink: RawGetSink | undefined) => void;
+  previous?: () => RawGetSink | undefined;
 }
 
 export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
@@ -111,13 +115,17 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
   res.write(COMMENT);
 
   let active = transport;
+  let entry: StreamEntry | undefined;
   const timers: { keepalive?: ReturnType<typeof setInterval> } = {};
   const closeStream = (): void => {
     if (sink.closed) return;
     sink.closed = true;
     if (timers.keepalive) clearInterval(timers.keepalive);
-    web(active)?._streamMapping?.delete(STANDALONE_STREAM_ID);
-    registerSink(undefined);
+    const mapping = web(active)?._streamMapping;
+    if (entry !== undefined && mapping?.get(STANDALONE_STREAM_ID) === entry) {
+      mapping.delete(STANDALONE_STREAM_ID);
+      registerSink(undefined);
+    }
     try {
       res.end();
     } catch {
@@ -128,11 +136,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     closed: false,
     attach: (next: StreamableHTTPServerTransport): void => {
       active = next;
-      const entry: StreamEntry = {
+      entry = {
         controller: {
           enqueue: (chunk: Uint8Array): void => {
-            if (sink.closed) return;
-            if (res.destroyed || res.writableEnded) {
+            if (streamEnded(sink, res)) {
               closeStream();
               return;
             }
@@ -147,6 +154,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     close: closeStream,
   };
 
+  res.on('close', closeStream);
+  res.on('error', closeStream);
+  req.on('close', closeStream);
+
   const lastEventId = headerValue(req, 'last-event-id');
   if (lastEventId) {
     await eventStore.replayEventsAfter(lastEventId, {
@@ -168,12 +179,17 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     });
   }
 
+  if (streamEnded(sink, res)) {
+    closeStream();
+    return;
+  }
+  opts.previous?.()?.close();
   sink.attach(transport);
   registerSink(sink);
+  if (sink.closed) return;
 
   timers.keepalive = setInterval(() => {
-    if (sink.closed) return;
-    if (res.destroyed || res.writableEnded) {
+    if (streamEnded(sink, res)) {
       closeStream();
       return;
     }
@@ -185,14 +201,10 @@ export async function serveStandaloneGet(opts: ServeOpts): Promise<void> {
     }
   }, KEEPALIVE_MS);
   timers.keepalive.unref?.();
-
-  res.on('close', closeStream);
-  res.on('error', closeStream);
-  req.on('close', closeStream);
 }
 
 export interface ChannelGetOpts extends ServeOpts {
-  previous: RawGetSink | undefined;
+  previous: () => RawGetSink | undefined;
 }
 
 export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
@@ -201,7 +213,7 @@ export async function serveChannelGet(opts: ChannelGetOpts): Promise<boolean> {
     opts.res.writeHead(check.status ?? 400).end(check.message ?? 'bad request');
     return false;
   }
-  if (opts.previous && !opts.previous.closed) opts.previous.close();
+  opts.previous()?.close();
   await serveStandaloneGet(opts);
   return true;
 }

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

@@ -1,5 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { currentBusSeq } from '@metro-labs/core/events';
+import { errMsg } from '@metro-labs/core/log';
 import { newReplayLedger } from '../channels/relay.js';
 import { McpSession, channelLog, type SessionKind } from './session.js';
 import { allowedAgents, type RequestIdentity } from './request-identity.js';
@@ -9,6 +10,7 @@ export class SessionSlot {
   private readonly ledger = newReplayLedger();
   private started = false;
   private live: boolean;
+  private changing: Promise<void> = Promise.resolve();
 
   constructor(
     live = true,
@@ -45,10 +47,20 @@ export class SessionSlot {
     if (this.started) this.session?.startChannel();
   }
 
-  async open(
-    identity: RequestIdentity,
-    adoptId?: string,
-  ): Promise<McpSession> {
+  open(identity: RequestIdentity, adoptId?: string): Promise<McpSession> {
+    return this.change(() => this.replace(identity, adoptId));
+  }
+
+  private change<T>(run: () => Promise<T>): Promise<T> {
+    const changed = this.changing.then(run);
+    this.changing = changed.then(() => undefined).catch((err: unknown) => {
+      channelLog('session: change failed', errMsg(err));
+    });
+    return changed;
+  }
+
+  private async replace(identity: RequestIdentity, adoptId?: string): Promise<McpSession> {
+    if (adoptId !== undefined && this.session?.id === adoptId) return this.session;
     await this.session?.close();
     if (this.ledger.startAt < 0) this.ledger.startAt = currentBusSeq();
     const id = adoptId ?? randomUUID();
@@ -61,6 +73,11 @@ export class SessionSlot {
       live: () => this.live,
       onClosed: (s) => {
         if (this.session === s) this.session = undefined;
+        s.channel.whenIdle().then(() => {
+          if (this.session?.streamAttached) this.session.replayMissed();
+        }).catch((err: unknown) => {
+          channelLog('session: handoff replay failed', errMsg(err));
+        });
       },
     });
     this.session = session;
@@ -69,7 +86,9 @@ export class SessionSlot {
     return session;
   }
 
-  async close(): Promise<void> {
-    await this.session?.close();
+  close(): Promise<void> {
+    return this.change(async () => {
+      await this.session?.close();
+    });
   }
 }

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

@@ -177,6 +177,10 @@ export class McpSession {
   }
 
   bindSink(sink: RawGetSink | undefined): void {
+    if (this.closed) {
+      sink?.close();
+      return;
+    }
     this.sink = sink;
     if (sink !== undefined) {
       this.announceCallState();

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.294"
+  "version": "0.1.0-beta.295"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/runner-activity.ts

@@ -26,6 +26,9 @@ const FAILURE = {
   status_unavailable: 'The SDK status file cannot be written. Check its path and permissions before starting.',
   saved_state: 'The saved Agent SDK state cannot be read. Restore it before starting.',
   executable: 'The SDK executable could not start. Prepare the SDK runtime again.',
+  module: 'The SDK runtime could not load a required module. Prepare the SDK runtime again.',
+  configuration: 'The SDK launch configuration is missing or invalid. Check Harness and the Model page before starting.',
+  process_exit: 'The SDK process exited unexpectedly. Check its reported exit code or signal before retrying.',
   connection: 'The SDK connection failed. Check the server and provider connection.',
   session_ended: 'The Agent SDK session ended unexpectedly.',
   interrupted: 'The SDK stopped before finishing a chat request. Check Conversations before retrying; actions may already have run.',
@@ -33,8 +36,40 @@ const FAILURE = {
 } as const;
 export type RunnerFailureCode = keyof typeof FAILURE;
 
-export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null): string {
-  return code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+const ERROR_CODES = ['ENOENT', 'EACCES', 'EPERM', 'ENOEXEC', 'ENOMEM', 'ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND', 'ERR_DLOPEN_FAILED', 'ECONNREFUSED', 'ECONNRESET', 'ENOTFOUND', 'EAI_AGAIN', 'ETIMEDOUT', 'CERT_HAS_EXPIRED', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'] as const;
+const SIGNALS = ['SIGTERM', 'SIGKILL', 'SIGSEGV', 'SIGABRT', 'SIGBUS', 'SIGILL', 'SIGINT', 'SIGHUP', 'SIGPIPE'] as const;
+
+export interface RunnerDiagnostic {
+  source: 'exception' | 'stderr';
+  errorCode?: (typeof ERROR_CODES)[number];
+  httpStatus?: number;
+  exitCode?: number;
+  signal?: (typeof SIGNALS)[number];
+}
+
+const boundedNumber = (value: unknown, min: number, max: number): number | undefined => typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max ? value : undefined;
+
+export function runnerDiagnostic(raw: unknown): RunnerDiagnostic | undefined {
+  if (!isRecord(raw) || (raw.source !== 'exception' && raw.source !== 'stderr')) return undefined;
+  const errorCode = ERROR_CODES.find((code) => code === raw.errorCode);
+  const signal = SIGNALS.find((value) => value === raw.signal);
+  const httpStatus = boundedNumber(raw.httpStatus, 400, 599);
+  const exitCode = boundedNumber(raw.exitCode, 0, 255);
+  return {
+    source: raw.source,
+    ...(errorCode === undefined ? {} : { errorCode }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+    ...(exitCode === undefined ? {} : { exitCode }),
+    ...(signal === undefined ? {} : { signal }),
+  };
+}
+
+export function runnerFailureSummary(code: RunnerFailureCode, tool: string | null = null, diagnostic?: RunnerDiagnostic): string {
+  const summary = code === 'tool_error' && name(tool) !== null ? `${tool} failed. See its result in Conversations.` : FAILURE[code];
+  const safe = runnerDiagnostic(diagnostic);
+  if (safe === undefined) return summary;
+  const details = [safe.errorCode, safe.httpStatus === undefined ? null : `HTTP ${safe.httpStatus}`, safe.exitCode === undefined ? null : `exit ${safe.exitCode}`, safe.signal].filter((value) => value !== undefined && value !== null);
+  return details.length === 0 ? summary : `${summary} Observed: ${details.join(', ')} (${safe.source === 'stderr' ? 'startup stderr' : 'exception'}).`;
 }
 
 export interface RunnerTask {
@@ -70,6 +105,7 @@ export interface RunnerEvent {
   toolUseId?: string;
   taskId: string | null;
   code?: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
 }
 
 export interface RunnerFailure extends RunnerEvent {
@@ -146,16 +182,17 @@ function tool(raw: unknown): RunnerTool | null {
   return { id: String(raw.id), name: String(raw.name), taskId: name(raw.taskId), startedAt: count(raw.startedAt), ...(typeof raw.worker === 'boolean' ? { worker: raw.worker } : {}) };
 }
 
-const failureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
+export const runnerFailureCode = (value: unknown): value is RunnerFailureCode => typeof value === 'string' && Object.hasOwn(FAILURE, value);
 const failureKind = (value: RunnerEventKind): boolean => ['turn_failed', 'tool_failed', 'task_failed', 'compact_failed', 'session_failed'].includes(value);
 
 function event(raw: unknown): RunnerEvent | null {
   if (!isRecord(raw) || !eventKind(raw.kind) || count(raw.at) === 0) return null;
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
   return {
     at: count(raw.at), kind: raw.kind, tool: name(raw.tool), taskId: name(raw.taskId),
     ...(name(raw.id) === null ? {} : { id: String(raw.id) }),
     ...(name(raw.toolUseId) === null ? {} : { toolUseId: String(raw.toolUseId) }),
-    ...(failureKind(raw.kind) && failureCode(raw.code) ? { code: raw.code } : {}),
+    ...(failureKind(raw.kind) && runnerFailureCode(raw.code) ? { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) } : {}),
   };
 }
 
@@ -184,7 +221,7 @@ function processIdentity(value: unknown): Pick<RunnerActivity, 'procStart'> {
 function failureFields(raw: Record<string, unknown>): Pick<RunnerActivity, 'lastError' | 'activeFailure' | 'lastFailure'> {
   const activeFailure = failure(raw.activeFailure);
   return {
-    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool) : safeError(raw.lastError),
+    lastError: Object.hasOwn(raw, 'activeFailure') ? activeFailure === null ? null : runnerFailureSummary(activeFailure.code, activeFailure.tool, activeFailure.diagnostic) : safeError(raw.lastError),
     ...(Object.hasOwn(raw, 'activeFailure') ? { activeFailure } : {}),
     ...(Object.hasOwn(raw, 'lastFailure') ? { lastFailure: failure(raw.lastFailure) } : {}),
   };

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.294",
+  "version": "0.1.0-beta.295",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",

package/runtime/sdk-runner/src/activity.ts

@@ -3,11 +3,13 @@ import { readFileSync } from 'node:fs';
 import type { SDKMessage } from '@anthropic-ai/claude-agent-sdk';
 import { isRecord } from '@metro-labs/core/is-record';
 import { log } from '@metro-labs/core/log';
-import { runnerFailureSummary, type RunnerActivity, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerInput, type RunnerPhase, type RunnerTool } from '@metro-labs/core/runner-activity';
+import { runnerFailureSummary, type RunnerActivity, type RunnerDiagnostic, type RunnerEvent, type RunnerEventKind, type RunnerFailure, type RunnerFailureCode, type RunnerInput, type RunnerPhase, type RunnerTool } from '@metro-labs/core/runner-activity';
 import { writeAtomic } from '@metro-labs/core/secure-fs';
 import { ActivityTasks, activityName } from './activity-tasks.js';
 import type { ApprovalAsk } from './approvals.js';
 import type { SavedTask } from './task-state.js';
+import { sessionFailure } from './errors.js';
+export { failureSummary } from './errors.js';
 
 const HEARTBEAT_MS = 5_000;
 const MAX_TRACKED = 200;
@@ -18,19 +20,10 @@ type System = Extract<SDKMessage, { type: 'system' }>;
 interface TrackedTool extends RunnerTool { parent: string | null }
 interface Approval { tool: string | null; taskId: string | null; worker: boolean }
 
-function sessionFailureCode(err: unknown): RunnerFailureCode {
-  const text = err instanceof Error ? err.message : String(err);
-  for (const code of ['status_unavailable', 'session_ended', 'interrupted', 'saved_state', 'authentication', 'executable', 'connection'] as const)
-    if (text === runnerFailureSummary(code)) return code;
-  if (/saved Agent SDK state/i.test(text)) return 'saved_state';
-  if (/unauthorized|authentication|invalid.*key|\b40[13]\b/i.test(text)) return 'authentication';
-  if (/ENOENT|not found|executable|spawn/i.test(text)) return 'executable';
-  if (/ECONN|network|fetch failed|timed? ?out/i.test(text)) return 'connection';
-  return 'session_error';
+function copyEvent<T extends RunnerEvent>(event: T): T {
+  return { ...event, ...(event.diagnostic === undefined ? {} : { diagnostic: { ...event.diagnostic } }) };
 }
 
-export function failureSummary(err: unknown): string { return runnerFailureSummary(sessionFailureCode(err)); }
-
 const PROVIDER_ERRORS: Record<NonNullable<Extract<SDKMessage, { type: 'assistant' }>['error']>, RunnerFailureCode> = {
   authentication_failed: 'authentication', oauth_org_not_allowed: 'authentication', cloud_credential_error: 'authentication', account_on_hold: 'authentication', verification_required: 'authentication',
   billing_error: 'billing', rate_limit: 'rate_limit', overloaded: 'provider_unavailable', server_error: 'provider_unavailable',
@@ -94,9 +87,9 @@ export class Activity {
     const s = this.state;
     return {
       ...s, tools: [...s.tools], activeTools: s.activeTools.map((tool) => ({ ...tool })),
-      tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map((event) => ({ ...event })),
+      tasks: s.tasks.map((task) => ({ ...task })), events: s.events.map(copyEvent),
       ...(s.inputs === undefined ? {} : { inputs: s.inputs.map((input) => ({ ...input })) }),
-      activeFailure: s.activeFailure ? { ...s.activeFailure } : null, lastFailure: s.lastFailure ? { ...s.lastFailure } : null,
+      activeFailure: s.activeFailure ? copyEvent(s.activeFailure) : null, lastFailure: s.lastFailure ? copyEvent(s.lastFailure) : null,
     };
   }
 
@@ -154,13 +147,14 @@ export class Activity {
     this.update();
   }
 
-  fail(message: string): void {
+  fail(err: unknown): void {
     this.failed = true;
-    const failure = this.failure('session_failed', sessionFailureCode(message), true);
+    const safe = sessionFailure(err);
+    const failure = this.failure('session_failed', safe.code, true, null, null, {}, safe.diagnostic);
     if (failure.code === 'interrupted') this.interrupted = failure;
     this.state.phase = 'error';
     this.state.mainPhase = 'error';
-    log.error({ reason: failure.code }, 'sdk-runner: activity error');
+    log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: this.state.lastError }, 'sdk-runner: activity error');
     this.flush();
   }
 
@@ -335,12 +329,12 @@ export class Activity {
     this.state.lastError = this.interrupted === null ? null : runnerFailureSummary(this.interrupted.code);
   }
 
-  private failure(kind: RunnerEventKind, code: RunnerFailureCode, active: boolean, tool: string | null = null, taskId: string | null = null, identity: Pick<RunnerEvent, 'id' | 'toolUseId'> = {}): RunnerFailure {
-    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }) };
+  private failure(kind: RunnerEventKind, code: RunnerFailureCode, active: boolean, tool: string | null = null, taskId: string | null = null, identity: Pick<RunnerEvent, 'id' | 'toolUseId'> = {}, diagnostic?: RunnerDiagnostic): RunnerFailure {
+    const failure: RunnerFailure = { id: activityName(identity.id) ?? randomUUID(), at: Date.now(), kind, code, tool, taskId, ...(activityName(identity.toolUseId) === null ? {} : { toolUseId: identity.toolUseId }), ...(diagnostic === undefined ? {} : { diagnostic }) };
     this.state.lastFailure = failure;
     if (active) {
       this.state.activeFailure = failure;
-      this.state.lastError = runnerFailureSummary(code, tool);
+      this.state.lastError = runnerFailureSummary(code, tool, diagnostic);
     }
     this.record(failure);
     return failure;

package/runtime/sdk-runner/src/app.ts

@@ -4,7 +4,7 @@ import { AutomationStore } from '@metro-labs/core/automation-store';
 import { errMsg, log } from '@metro-labs/core/log';
 import { skillSourceRoot } from '@metro-labs/core/skill-source';
 import { SkillsRefresh } from './skills.js';
-import { failureSummary, type Activity } from './activity.js';
+import type { Activity } from './activity.js';
 import { approvalsThrough } from './approvals.js';
 import type { RunnerConfig } from './config.js';
 import { MetroLink } from './link.js';
@@ -79,7 +79,7 @@ export async function startAgent(cfg: RunnerConfig, hooks: AppHooks): Promise<Ru
     hooks.activity?.start();
     return await connected(cfg, hooks, release);
   } catch (err) {
-    hooks.activity?.fail(failureSummary(err));
+    hooks.activity?.fail(err);
     hooks.activity?.stop();
     await release().catch(() => { log.warn('sdk-runner: releasing process ownership failed'); });
     throw err;

package/runtime/sdk-runner/src/errors.ts

@@ -0,0 +1,131 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { runnerDiagnostic, runnerFailureCode, runnerFailureSummary, type RunnerDiagnostic, type RunnerFailureCode } from '@metro-labs/core/runner-activity';
+
+const SCAN_MAX = 2_048;
+const ERROR_FAILURES: Record<NonNullable<RunnerDiagnostic['errorCode']>, RunnerFailureCode> = {
+  ENOENT: 'executable', EACCES: 'executable', EPERM: 'executable', ENOEXEC: 'executable', ENOMEM: 'executable',
+  ERR_MODULE_NOT_FOUND: 'module', MODULE_NOT_FOUND: 'module', ERR_DLOPEN_FAILED: 'module',
+  ECONNREFUSED: 'connection', ECONNRESET: 'connection', ENOTFOUND: 'connection', EAI_AGAIN: 'connection', ETIMEDOUT: 'connection',
+  CERT_HAS_EXPIRED: 'connection', UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'connection',
+};
+const KNOWN = ['status_unavailable', 'session_ended', 'interrupted', 'saved_state', 'authentication', 'executable', 'connection', 'module', 'configuration', 'process_exit', 'session_error'] as const;
+
+export interface SessionFailure {
+  code: RunnerFailureCode;
+  diagnostic?: RunnerDiagnostic;
+}
+
+function normalizeFailure(raw: unknown): SessionFailure {
+  if (!isRecord(raw) || !runnerFailureCode(raw.code)) return { code: 'session_error' };
+  const diagnostic = runnerDiagnostic(raw.diagnostic);
+  return { code: raw.code, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
+
+export class SessionError extends Error {
+  readonly failure: SessionFailure;
+
+  constructor(failure: SessionFailure) {
+    const safe = normalizeFailure(failure);
+    super(runnerFailureSummary(safe.code, null, safe.diagnostic));
+    this.failure = safe;
+  }
+}
+
+function statusFailure(status: number | undefined): RunnerFailureCode | null {
+  if (status === undefined) return null;
+  if (status === 401 || status === 403) return 'authentication';
+  if (status === 402) return 'billing';
+  if (status === 429) return 'rate_limit';
+  return status >= 500 ? 'provider_unavailable' : 'invalid_request';
+}
+
+const TEXT_FAILURES: [RunnerFailureCode, RegExp][] = [
+  ['authentication', /\bunauthorized\b|\bauthentication (?:failed|error)\b|\binvalid(?:[ -]api)?[ -]key\b/i],
+  ['module', /cannot find (?:module|package)|error (?:while )?loading shared libraries|module not found/i],
+  ['configuration', /METRO_(?:RUNNER_MCP_URL|AGENT_KEY) is not set|invalid (?:configuration|settings)|failed to parse (?:configuration|settings)|unknown (?:option|argument)/i],
+  ['executable', /executable|spawn|command not found/i],
+  ['connection', /network|fetch failed|timed? ?out/i],
+];
+
+function errorText(value: unknown): string {
+  if (typeof value === 'string') return value.slice(0, SCAN_MAX);
+  return isRecord(value) && typeof value.message === 'string' ? value.message.slice(0, SCAN_MAX) : '';
+}
+
+function evidence(raw: Record<string, unknown>, message: string, source: RunnerDiagnostic['source']): RunnerDiagnostic | undefined {
+  const errorCodes = message.match(/\b[A-Z][A-Z_]{2,40}\b/g) ?? [];
+  return runnerDiagnostic({
+    source, errorCode: raw.code ?? errorCodes.find((code) => Object.hasOwn(ERROR_FAILURES, code)),
+    httpStatus: raw.status ?? raw.statusCode ?? Number(/(?:^|\bHTTP(?:\/[12](?:\.\d)?)?\s+|\bstatus(?: code)?[:= ]+)([45]\d\d)\b/i.exec(message)?.[1]),
+    exitCode: raw.exitCode ?? Number(/^Claude Code process exited with code (\d{1,3})\b/.exec(message)?.[1]),
+    signal: raw.signal ?? /^Claude Code process terminated by signal (SIG[A-Z]{1,8})\b/.exec(message)?.[1],
+  });
+}
+
+function diagnosticCode(message: string, diagnostic: RunnerDiagnostic | undefined): RunnerFailureCode | null {
+  if (/saved Agent SDK state/i.test(message)) return 'saved_state';
+  if (diagnostic?.errorCode !== undefined) return ERROR_FAILURES[diagnostic.errorCode];
+  return statusFailure(diagnostic?.httpStatus);
+}
+
+function processFailure(diagnostic: RunnerDiagnostic | undefined): RunnerFailureCode | null {
+  return diagnostic?.exitCode !== undefined || diagnostic?.signal !== undefined ? 'process_exit' : null;
+}
+
+function classify(value: unknown, source: RunnerDiagnostic['source']): SessionFailure {
+  const message = errorText(value);
+  const known = KNOWN.find((code) => message === runnerFailureSummary(code));
+  if (known !== undefined) return { code: known };
+  const diagnostic = evidence(isRecord(value) ? value : {}, message, source);
+  const code = diagnosticCode(message, diagnostic) ?? TEXT_FAILURES.find(([, pattern]) => pattern.test(message))?.[0] ?? processFailure(diagnostic) ?? 'session_error';
+  return code === 'session_error' ? { code } : { code, ...(diagnostic === undefined ? {} : { diagnostic }) };
+}
+
+export function sessionFailure(err: unknown): SessionFailure {
+  try {
+    if (err instanceof SessionError) return normalizeFailure(err.failure);
+    let current = err;
+    let result: SessionFailure = { code: 'session_error' };
+    for (let depth = 0; depth < 4; depth++) {
+      const next = classify(current, 'exception');
+      if (next.code !== 'session_error') result = next;
+      if (!isRecord(current) || current.cause === undefined) break;
+      current = current.cause;
+    }
+    return result;
+  } catch {
+    return { code: 'session_error' };
+  }
+}
+
+export const failureSummary = (err: unknown): string => {
+  const failure = sessionFailure(err);
+  return runnerFailureSummary(failure.code, null, failure.diagnostic);
+};
+
+export class StartupDiagnostics {
+  private tail = '';
+  private observed: SessionFailure | null = null;
+
+  stderr(text: string): void {
+    const head = text.slice(0, SCAN_MAX);
+    const candidates = [head, (this.tail + head).slice(-SCAN_MAX), text.length > SCAN_MAX ? text.slice(-SCAN_MAX) : ''];
+    for (const candidate of candidates) {
+      const failure = classify(candidate, 'stderr');
+      if (failure.code !== 'session_error' && (failure.code !== 'process_exit' || this.observed === null)) this.observed = failure;
+    }
+    this.tail = (this.tail + (text.length > SCAN_MAX ? text.slice(-SCAN_MAX) : text)).slice(-SCAN_MAX);
+  }
+
+  failure(err: unknown): SessionFailure {
+    const failure = sessionFailure(err);
+    const observed = this.observed;
+    if (observed === null || !['session_error', 'process_exit'].includes(failure.code)) return failure;
+    return { ...observed, diagnostic: runnerDiagnostic({ ...failure.diagnostic, ...observed.diagnostic }) };
+  }
+
+  clear(): void {
+    this.tail = '';
+    this.observed = null;
+  }
+}

package/runtime/sdk-runner/src/main.ts

@@ -3,6 +3,7 @@ import { log } from '@metro-labs/core/log';
 import { Activity, failureSummary } from './activity.js';
 import { startAgent, type RunningAgent } from './app.js';
 import { runnerConfig } from './config.js';
+import { sessionFailure } from './errors.js';
 
 let agent: RunningAgent | null = null;
 let starting: Promise<RunningAgent> | null = null;
@@ -45,9 +46,10 @@ try {
     await agent.done;
     if (!exiting) activity.fail('The Agent SDK session ended unexpectedly.');
   } catch (err) {
-    if (!exiting) activity.fail(failureSummary(err));
+    if (!exiting) activity.fail(err);
   }
 } catch (err) {
-  log.error({ reason: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
+  const failure = sessionFailure(err);
+  log.error({ reason: failure.code, diagnostic: failure.diagnostic, summary: failureSummary(err) }, 'sdk-runner: the Agent SDK session failed to start');
 }
 await exit(1);

package/runtime/sdk-runner/src/runner.ts

@@ -18,6 +18,7 @@ import type { SessionStore } from './session-store.js';
 import { completedCommand, SessionWatch, startedCommand, uuidsOf } from './session-watch.js';
 import { TaskRecovery } from './task-recovery.js';
 import { METRO_SERVER, type MetroTools } from './tool-proxy.js';
+import { failureSummary, SessionError, StartupDiagnostics } from './errors.js';
 
 const STARTUP_WAIT = 'CLAUDE_CODE_MCP_STARTUP_WAIT_MS';
 export const COMPACT_AT = 120_000;
@@ -53,9 +54,6 @@ export function runnerOptions(cfg: RunnerConfig, tools: MetroTools, canUseTool:
     includePartialMessages: true,
     extraArgs: { 'system-prompt-snapshot': 'off' },
     ...(resume === null ? {} : { resume }),
-    stderr: (text: string) => {
-      log.debug({ text: text.slice(0, 500) }, 'sdk-runner: claude stderr');
-    },
   };
 }
 
@@ -98,6 +96,7 @@ export class Runner {
   readonly automation: Automation | null;
   private readonly recovery: TaskRecovery;
   private readonly watch: SessionWatch;
+  private readonly diagnostics = new StartupDiagnostics();
   private readonly tasks = new ActivityTasks(() => undefined);
   private readonly skillWork = new SkillWork();
   private compactTimer: ReturnType<typeof setTimeout> | null = null;
@@ -149,7 +148,13 @@ export class Runner {
     if (this.session !== null) throw new Error('the runner was already started');
     if (options.resume === undefined) this.watch.restoreContext(0);
     else this.maybeCompact(true);
-    this.session = (this.parts.open ?? query)({ prompt: this.inbox, options });
+    try {
+      this.session = (this.parts.open ?? query)({ prompt: this.inbox, options: { ...options, stderr: (text) => { if (this.sessionId === null) this.diagnostics.stderr(text); } } });
+    } catch (err) {
+      const failure = this.diagnostics.failure(err);
+      this.diagnostics.clear();
+      throw new SessionError(failure);
+    }
     this.model = options.model ?? null;
     this.queueModel(this.model);
     this.parts.skills?.start({
@@ -185,15 +190,22 @@ export class Runner {
         this.maybeCompact();
         observe?.(message);
       }
+    } catch (err) {
+      throw new SessionError(this.diagnostics.failure(err));
     } finally {
-      this.cancelCompact();
-      this.parts.skills?.close();
-      this.automation?.close(false);
-      this.recovery.close(false);
-      this.ended = true;
+      this.finishRun();
     }
   }
 
+  private finishRun(): void {
+    this.diagnostics.clear();
+    this.cancelCompact();
+    this.parts.skills?.close();
+    this.automation?.close(false);
+    this.recovery.close(false);
+    this.ended = true;
+  }
+
   chat(event: ChannelEvent): Uuid {
     try {
       const uuid = this.inbox.push('chat', channelText(METRO_SERVER, event.content, event.meta));
@@ -228,8 +240,9 @@ export class Runner {
     this.switching = this.switching
       .then(() => this.applyModel(model))
       .catch((err: unknown) => {
-        this.parts.activity?.fail('The SDK could not apply the selected model. Check the Model page.');
-        log.warn({ model, err: errMsg(err) }, 'sdk-runner: the session could not take the model the Model page picked');
+        const failure = new SessionError(this.diagnostics.failure(err));
+        this.parts.activity?.fail(failure);
+        log.warn({ reason: failure.failure.code, diagnostic: failure.failure.diagnostic, summary: failureSummary(failure) }, 'sdk-runner: the session could not take the model the Model page picked');
       });
   }
 
@@ -333,6 +346,7 @@ export class Runner {
     const id = typeof m.session_id === 'string' ? m.session_id : null;
     if (id === null || id === this.sessionId) return;
     this.sessionId = id;
+    this.diagnostics.clear();
     log.info({ session: id, model: m.model, claude: m.claude_code_version }, 'sdk-runner: session up');
     try {
       this.parts.store.save(id);