@inceptionstack/roundhouse 0.5.17 → 0.5.20

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `@inceptionstack/roundhouse` are documented here.
 
+## [0.5.19] — 2026-05-10
+- Sub-agent orchestrator: spawn background Pi agents for review/research/scout/implementation
+- CLI: `roundhouse subagent spawn/status/list/abort`
+- Telegram notifications on sub-agent completion (✅/⏰/❌)
+- Security: UUID-only run IDs, path traversal guard, SIGKILL escalation
+- Boot turn: agent greets in-character on startup
+- /status shows configured model after /model switch
+- TUI: fresh session support on new deploys
+
 ## [0.5.14] — 2026-05-10
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inceptionstack/roundhouse",
-  "version": "0.5.17",
+  "version": "0.5.20",
   "type": "module",
   "description": "Multi-platform chat gateway that routes messages through a configured AI agent",
   "license": "MIT",

package/src/agents/pi/pi-adapter.ts

@@ -521,6 +521,7 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
     getInfo(threadId?: string): Record<string, unknown> {
       // Get model from the requested thread's session, or most recently used
       let modelInfo: string | undefined;
+      let hasActiveSession = false;
       let contextUsage: { tokens: number | null; contextWindow: number; percent: number | null } | undefined;
       const threadEntry = threadId ? sessions.get(threadId) : undefined;
 
@@ -528,6 +529,7 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
         const model = threadEntry.session.model;
         if (model) modelInfo = `${model.provider}/${model.id}`;
         contextUsage = threadEntry.session.getContextUsage() ?? undefined;
+        hasActiveSession = true;
       }
 
       if (!modelInfo) {
@@ -542,17 +544,18 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
         }
       }
 
-      // Fall back to configured default from settings.json
-      if (!modelInfo) {
-        try {
-          const settingsPath = join(homedir(), ".pi", "agent", "settings.json");
-          const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-          if (settings.defaultProvider && settings.defaultModel) {
-            modelInfo = `${settings.defaultProvider}/${settings.defaultModel}`;
-          }
-        } catch (err) {
-          console.warn(`[pi-agent] could not read settings.json for model info:`, (err as Error).message);
+      // Read configured model from settings.json (used for fallback + configuredModel field)
+      let configuredModel = "";
+      try {
+        const settingsPath = join(homedir(), ".pi", "agent", "settings.json");
+        const settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        if (settings.defaultProvider && settings.defaultModel) {
+          configuredModel = `${settings.defaultProvider}/${settings.defaultModel}`;
         }
+      } catch {}
+
+      if (!modelInfo && configuredModel) {
+        modelInfo = configuredModel;
       }
 
       // Read agent version
@@ -565,6 +568,8 @@ export const createPiAgentAdapter: AgentAdapterFactory = (config) => {
       return {
         version,
         model: modelInfo ?? "unknown",
+        hasActiveSession,
+        configuredModel: configuredModel || modelInfo || "unknown",
         activeSessions: sessions.size,
         cwd,
         contextTokens: contextUsage?.tokens ?? null,

package/src/cli/cli.ts

@@ -322,20 +322,20 @@ async function cmdTui() {
       })
       .sort((a, b) => b.mtime - a.mtime);
   } catch {
-    console.error(`No session directory found at ${threadPath}.`);
-    process.exit(1);
+    // No session directory — will start fresh below
   }
 
-  if (candidates.length === 0) {
-    console.error(`No session files found at ${threadPath}.`);
-    process.exit(1);
+  let piArgs: string[];
+  if (candidates.length > 0) {
+    const selected = candidates[0];
+    console.log(`\nResuming: ${selected.sessionFile}\n`);
+    piArgs = ["--resume", selected.sessionFile];
+  } else {
+    console.log(`\nNo existing sessions for thread "${threadId}". Starting fresh.\n`);
+    piArgs = ["--session-dir", threadPath];
   }
 
-  const selected = candidates[0];
-
-  console.log(`\nOpening: ${selected.sessionFile}\n`);
-
-  const child = spawn("pi", ["--resume", selected.sessionFile], { stdio: "inherit" });
+  const child = spawn("pi", piArgs, { stdio: "inherit" });
   child.on("error", (err) => {
     console.error((err as any).code === "ENOENT" ? "'pi' not found in PATH." : `Failed: ${err.message}`);
     process.exit(1);
@@ -390,6 +390,7 @@ import { cmdAgent } from "./agent-command";
 import { cmdCron } from "./cron";
 import { cmdSetup, cmdPair } from "./setup";
 import { cmdMessage } from "./message";
+import { handleSubagentCommand } from "./subagent-command";
 
 const command = process.argv[2];
 
@@ -410,6 +411,7 @@ const commands: Record<string, () => void | Promise<void>> = {
   doctor: () => cmdDoctor(process.argv.slice(3)),
   cron: () => cmdCron(process.argv.slice(3)),
   message: () => cmdMessage(process.argv.slice(3)),
+  subagent: () => handleSubagentCommand(process.argv.slice(3)),
   agent: cmdAgent,
 };
 

package/src/cli/subagent-command.ts

@@ -0,0 +1,171 @@
+/**
+ * cli/subagent-command.ts — CLI interface for sub-agent delegation
+ *
+ * Thin disk-state client that reads/writes ~/.roundhouse/subagents/ directly.
+ * The gateway's watcher handles lifecycle (timeout, completion notification).
+ * spawn() creates the process and persists state; the gateway adopts it on next poll.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { SubAgentOrchestratorImpl } from "../subagents/orchestrator";
+import { validateRunId } from "../subagents/run-store";
+import type { SpawnSpec, SubAgentRole, RoutingInfo } from "../subagents/types";
+
+const ROUNDHOUSE_DIR = join(homedir(), ".roundhouse");
+
+function loadGatewayConfig(): { notifyChatIds: number[] } {
+  try {
+    const raw = readFileSync(join(ROUNDHOUSE_DIR, "gateway.config.json"), "utf8");
+    const cfg = JSON.parse(raw);
+    return { notifyChatIds: cfg?.chat?.notifyChatIds ?? [] };
+  } catch {
+    return { notifyChatIds: [] };
+  }
+}
+
+function buildRouting(): RoutingInfo {
+  const cfg = loadGatewayConfig();
+  const chatId = String(cfg.notifyChatIds[0] ?? "");
+  if (!chatId) {
+    console.error("Error: no Telegram chat configured. Run 'roundhouse setup' first.");
+    process.exit(1);
+  }
+  return {
+    transport: "telegram",
+    chatId,
+    parentThreadId: `telegram:${chatId}:main`,
+  };
+}
+
+export async function handleSubagentCommand(args: string[]): Promise<void> {
+  const subcommand = args[0];
+
+  const orchestrator = new SubAgentOrchestratorImpl();
+
+  switch (subcommand) {
+    case "spawn": {
+      const role = getFlag(args, "--role") as SubAgentRole | undefined;
+      const task = getFlag(args, "--task");
+      const cwd = getFlag(args, "--cwd") || process.cwd();
+      const model = getFlag(args, "--model");
+      const timeoutStr = getFlag(args, "--timeout");
+
+      if (!role || !task) {
+        console.error("Usage: roundhouse subagent spawn --role <role> --task \"...\" [--cwd <dir>] [--model <id>] [--timeout <ms>]");
+        process.exit(1);
+      }
+
+      const validRoles: SubAgentRole[] = ["review", "research", "scout", "implementation"];
+      if (!validRoles.includes(role)) {
+        console.error(`Invalid role: ${role}. Must be one of: ${validRoles.join(", ")}`);
+        process.exit(1);
+      }
+
+      let timeoutMs: number | undefined;
+      if (timeoutStr) {
+        const n = Number(timeoutStr);
+        if (!Number.isFinite(n) || n <= 0) {
+          console.error(`Invalid timeout: ${timeoutStr}. Must be a positive number (milliseconds).`);
+          process.exit(1);
+        }
+        timeoutMs = n;
+      }
+
+      const spec: SpawnSpec = {
+        role,
+        task,
+        cwd,
+        routing: buildRouting(),
+        model: model || undefined,
+        timeoutMs,
+      };
+
+      try {
+        const runId = await orchestrator.spawn(spec);
+        console.log(JSON.stringify({ runId, status: "spawned", role, cwd }));
+      } catch (err) {
+        console.error(`Spawn failed: ${(err as Error).message}`);
+        process.exit(1);
+      }
+      break;
+    }
+
+    case "status": {
+      const runId = args[1];
+      if (!runId) {
+        console.error("Usage: roundhouse subagent status <runId>");
+        process.exit(1);
+      }
+      validateCliRunId(runId);
+      const status = await orchestrator.status(runId);
+      if (!status) {
+        console.error(`Run not found: ${runId}`);
+        process.exit(1);
+      }
+      console.log(JSON.stringify(status, null, 2));
+      break;
+    }
+
+    case "list": {
+      const statuses = await orchestrator.list();
+      if (statuses.length === 0) {
+        console.log("No sub-agent runs.");
+      } else {
+        for (const s of statuses) {
+          const duration = s.completedAt
+            ? `${Math.round((Date.parse(s.completedAt) - Date.parse(s.startedAt)) / 1000)}s`
+            : "running";
+          console.log(`${s.status.padEnd(8)} ${s.role.padEnd(14)} ${duration.padEnd(8)} ${s.runId.slice(0, 8)}`);
+        }
+      }
+      break;
+    }
+
+    case "abort": {
+      const runId = args[1];
+      if (!runId) {
+        console.error("Usage: roundhouse subagent abort <runId>");
+        process.exit(1);
+      }
+      validateCliRunId(runId);
+      const current = await orchestrator.status(runId);
+      if (!current) {
+        console.error(`Run not found: ${runId}`);
+        process.exit(1);
+      }
+      if (current.status !== "running") {
+        console.log(`Run already ${current.status}: ${runId.slice(0, 8)}`);
+        break;
+      }
+      await orchestrator.abort(runId);
+      const status = await orchestrator.status(runId);
+      if (status?.status === "running") {
+        console.log(`Abort requested: ${runId.slice(0, 8)}`);
+      } else {
+        console.log(`Aborted: ${runId.slice(0, 8)}`);
+      }
+      break;
+    }
+
+    default:
+      console.error("Usage: roundhouse subagent <spawn|status|list|abort>");
+      process.exit(1);
+  }
+}
+
+function getFlag(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  return args[idx + 1];
+}
+
+function validateCliRunId(runId: string): void {
+  try {
+    validateRunId(runId);
+  } catch (err) {
+    console.error((err as Error).message);
+    process.exit(1);
+  }
+}

package/src/gateway/commands.ts

@@ -211,7 +211,17 @@ export async function handleStatus(ctx: CommandContext): Promise<void> {
     `🤖 Agent: ${agentLabel}`,
   ];
 
-  if (info.model) lines.push(`🧠 Model: \`${info.model}\``);
+  if (info.model && info.model !== "unknown") {
+    const configuredModel = info.configuredModel as string | undefined;
+    if (configuredModel && configuredModel !== info.model && info.hasActiveSession) {
+      lines.push(`🧠 Model: \`${configuredModel}\` (configured)`);
+      lines.push(`   ↳ session using: \`${info.model}\` (until /new)`);
+    } else {
+      lines.push(`🧠 Model: \`${configuredModel || info.model}\``);
+    }
+  } else if (info.configuredModel) {
+    lines.push(`🧠 Model: \`${info.configuredModel}\``);
+  }
   if (info.activeSessions !== undefined) lines.push(`💬 Active sessions: ${info.activeSessions}`);
 
   lines.push(

package/src/gateway/gateway.ts

@@ -28,6 +28,8 @@ import { handleLater } from "./later-command";
 import { handleTopic, applyTopicOverride } from "./topic-command";
 import { TelegramAdapter } from "../transports";
 import type { TransportAdapter } from "../transports";
+import { SubAgentOrchestratorImpl, SubAgentWatcher } from "../subagents";
+import type { RunStatus, RoutingInfo } from "../subagents";
 import { hostname } from "node:os";
 import { join } from "node:path";
 import { injectToolsSection } from "./tools-inject";
@@ -89,6 +91,8 @@ export class Gateway {
   private sttService: SttService | null = null;
   private cronScheduler: CronSchedulerService | null = null;
   private ipcServer: IpcServer | null = null;
+  private subagentOrchestrator: SubAgentOrchestratorImpl | null = null;
+  private subagentWatcher: SubAgentWatcher | null = null;
 
   constructor(router: AgentRouter, config: GatewayConfig) {
     this.router = router;
@@ -362,8 +366,22 @@ export class Gateway {
       console.error("[roundhouse] IPC server start failed:", (err as Error).message);
     }
 
+    // Start sub-agent orchestrator + watcher
+    this.subagentOrchestrator = new SubAgentOrchestratorImpl();
+    this.subagentWatcher = new SubAgentWatcher(
+      this.subagentOrchestrator,
+      async (status, routing) => {
+        await this.handleSubagentCompletion(status, routing);
+      },
+    );
+    this.subagentWatcher.start();
+    console.log("[roundhouse] sub-agent watcher started");
+
     // Send startup notification (after cron init so we can include job counts)
     await this.notifyStartup(platforms);
+
+    // Fire boot turn — agent says hello (seeds session so it's never empty)
+    await this.fireBootTurn(verboseThreads, threadLocks, abortControllers);
   }
 
   /**
@@ -782,7 +800,62 @@ export class Gateway {
     }
   }
 
+  /**
+   * Fire a boot turn — send a prompt to the agent so it greets in-character.
+   * Seeds the session on startup so context is never empty.
+   */
+  private async fireBootTurn(
+    verboseThreads: Set<string>,
+    threadLocks: Map<string, Promise<void>>,
+    abortControllers: Map<string, AbortController>,
+  ) {
+    const chatIds = this.config.chat.notifyChatIds;
+    if (!chatIds?.length) return;
+
+    // Only fire for the primary (first) chat
+    const primaryChatId = chatIds[0];
+    const threadId = `telegram:${primaryChatId}`;
+    const agentThreadId = "main";
+
+    // Create a synthetic Telegram-compatible thread so streaming, HTML conversion,
+    // message splitting, and progressive edits all work identically to real chat threads.
+    const token = process.env.TELEGRAM_BOT_TOKEN;
+    const syntheticThread = {
+      id: threadId,
+      adapter: {
+        telegramFetch: async (method: string, payload: Record<string, unknown>) => {
+          if (!token) return null;
+          const res = await fetch(`https://api.telegram.org/bot${token}/${method}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ chat_id: primaryChatId, ...payload }),
+            signal: AbortSignal.timeout(30_000),
+          });
+          if (!res.ok) return null;
+          const json = await res.json() as { result?: unknown };
+          return json.result ?? null;
+        },
+      },
+      post: async (content: string | { markdown: string }) => {
+        const text = typeof content === "string" ? content : content.markdown;
+        await this.transport.notify([primaryChatId], text);
+      },
+      startTyping: async () => {},
+    };
+
+    const bootPrompt = "You just came online after a restart. Say a brief hello in-character (1–2 sentences max). Check your workspace for any pending tasks.";
+
+    try {
+      await this.handleAgentTurn(syntheticThread, agentThreadId, bootPrompt, [], verboseThreads, threadLocks, abortControllers);
+    } catch (err) {
+      console.error("[roundhouse] boot turn failed:", (err as Error).message);
+    }
+  }
+
   async stop() {
+    if (this.subagentWatcher) {
+      this.subagentWatcher.stop();
+    }
     if (this.ipcServer) {
       this.ipcServer.stop();
     }
@@ -793,4 +866,22 @@ export class Gateway {
     await this.router.dispose();
     console.log("[roundhouse] stopped");
   }
+
+  /** Handle sub-agent completion — post result to originating thread */
+  private async handleSubagentCompletion(status: RunStatus, routing: RoutingInfo): Promise<void> {
+    const emoji = status.status === "complete" ? "✅" : status.status === "timeout" ? "⏰" : "❌";
+    const duration = status.completedAt && status.startedAt
+      ? Math.round((Date.parse(status.completedAt) - Date.parse(status.startedAt)) / 1000)
+      : 0;
+    const summary = `${emoji} <b>Sub-agent ${status.status}</b> (${status.role})\n⏱ ${duration}s | run: <code>${status.runId.slice(0, 8)}</code>`;
+
+    try {
+      const chatId = Number(routing.chatId);
+      if (chatId) {
+        await this.transport.notify([chatId], summary, { parseMode: "HTML" });
+      }
+    } catch (err) {
+      console.error("[roundhouse] sub-agent completion notification failed:", err);
+    }
+  }
 }

package/src/gateway/tools.md

@@ -176,3 +176,42 @@ aws s3 ls
 aws logs tail /aws/lambda/<name> --since 1h
 aws cloudformation describe-stacks --stack-name <name>
 ```
+
+## Sub-Agent Delegation
+
+Spawn background sub-agents for tasks that take time. The main conversation stays responsive.
+
+**Usage:**
+```bash
+# Spawn a background agent
+roundhouse subagent spawn --role <role> --task "..." --cwd <dir>
+
+# Check status
+roundhouse subagent status <runId>
+roundhouse subagent list
+
+# Cancel a running agent
+roundhouse subagent abort <runId>
+```
+
+**Roles:**
+- `review` — Code review, architecture review, PR review
+- `research` — Read docs, explore APIs, gather information
+- `scout` — Search codebase, find patterns, map structure
+- `implementation` — Write code, fix bugs, refactor
+
+**Behavior:**
+- Sub-agents run as background processes (15 min timeout default)
+- You get notified when they complete
+- Multiple agents can run concurrently
+- They share the filesystem — no isolation between them
+
+**When to delegate:**
+- Task will take several minutes
+- User wants to keep chatting about something else
+- Independent work that doesn't need live interaction
+
+**When NOT to delegate:**
+- Quick tasks (< 30 seconds)
+- Tasks needing user input mid-way
+- You can just do it directly in the current turn

package/src/subagents/brief.ts

@@ -0,0 +1,28 @@
+import type { SpawnSpec } from "./types";
+
+export function buildBrief(spec: SpawnSpec): string {
+  const sections: string[] = [
+    "# Role",
+    spec.role,
+    "",
+    "# Task",
+    spec.task,
+    "",
+    "# Working Directory",
+    spec.cwd,
+  ];
+
+  if (spec.context?.briefing) {
+    sections.push("", "# Context", spec.context.briefing);
+  }
+
+  if (spec.context?.targetFiles?.length) {
+    sections.push("", "# Target Files", ...spec.context.targetFiles.map((file) => `- ${file}`));
+  }
+
+  if (spec.context?.completionContract) {
+    sections.push("", "# Done When", spec.context.completionContract);
+  }
+
+  return sections.join("\n") + "\n";
+}

package/src/subagents/index.ts

@@ -0,0 +1,8 @@
+export * from "./brief";
+export * from "./orchestrator";
+export * from "./pid";
+export * from "./process-launcher";
+export * from "./run-store";
+export * from "./types";
+export * from "./watcher";
+// Internal modules (not re-exported): run-finalizer.ts, termination-handler.ts

package/src/subagents/orchestrator.ts

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, stat } from "node:fs/promises";
+import type { ChildProcess } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { buildBrief } from "./brief";
+import { isProcessAlive as defaultIsProcessAlive } from "./pid";
+import { ProcessLauncher, type ProcessLauncherOptions } from "./process-launcher";
+import { RunFinalizer } from "./run-finalizer";
+import { RunStore } from "./run-store";
+import { TerminationHandler } from "./termination-handler";
+import type { RunStatus, SpawnSpec, SubAgentLifecycle, SubAgentOrchestrator } from "./types";
+const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
+
+export interface OrchestratorOptions extends ProcessLauncherOptions {
+  dataRoot?: string;
+  isProcessAlive?: (pid: number, expectedTicks: string) => Promise<boolean>;
+  now?: () => Date;
+}
+
+export class SubAgentOrchestratorImpl implements SubAgentOrchestrator, SubAgentLifecycle {
+  private readonly store: RunStore;
+  private readonly launcher: ProcessLauncher;
+  private readonly isProcessAlive: (pid: number, expectedTicks: string) => Promise<boolean>;
+  private readonly now: () => Date;
+  private readonly finalizer: RunFinalizer;
+  private readonly terminationHandler: TerminationHandler;
+  private readonly children = new Map<string, { pid: number }>();
+  private readonly statusReady = new Map<string, Promise<void>>();
+
+  constructor(options: OrchestratorOptions = {}) {
+    const dataRoot = options.dataRoot ?? join(homedir(), ".roundhouse");
+    this.store = new RunStore(dataRoot);
+    this.launcher = new ProcessLauncher(options);
+    this.isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+    this.now = options.now ?? (() => new Date());
+    this.finalizer = new RunFinalizer({ store: this.store, now: this.now });
+    this.terminationHandler = new TerminationHandler({
+      store: this.store,
+      isProcessAlive: this.isProcessAlive,
+      signalProcess: this.launcher.signalProcess,
+      finalizeRun: this.finalizer.finalizeRun.bind(this.finalizer),
+    });
+  }
+  onCompletion(listener: (status: RunStatus) => Promise<void> | void): () => void { return this.finalizer.onCompletion(listener); }
+  isRunManagedInProcess(runId: string): boolean { return this.children.has(runId); }
+
+  async spawn(spec: SpawnSpec): Promise<string> {
+    await assertDirectoryExists(spec.cwd);
+    this.launcher.assertAvailable();
+
+    const runId = randomUUID();
+    const runDir = this.store.getRunDir(runId);
+    const brief = buildBrief(spec);
+    const timeoutMs = spec.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const startedAt = this.now();
+
+    await mkdir(runDir, { recursive: true });
+    await this.store.writeFile(runId, "brief.md", brief);
+    if (spec.model) {
+      await this.store.writeJson(runId, "settings.json", { defaultModel: spec.model });
+    }
+
+    let resolveReady: () => void;
+    const readyPromise = new Promise<void>((r) => { resolveReady = r; });
+    this.statusReady.set(runId, readyPromise);
+    let launchedChild: ChildProcess | undefined;
+    let launchedPid: number | undefined;
+
+    try {
+      const { pid, spawnClockTicks } = await this.launcher.launch(runDir, spec.cwd, (child) => {
+        launchedChild = child;
+        child.on("exit", (exitCode) => {
+          void this.handleChildExit(runId, exitCode);
+        });
+        if (child.exitCode !== null) {
+          void this.handleChildExit(runId, child.exitCode);
+        }
+      });
+      launchedPid = pid;
+
+      const initialStatus: RunStatus = {
+        runId,
+        role: spec.role,
+        cwd: spec.cwd,
+        routing: spec.routing,
+        status: "running",
+        pid,
+        startedAt: startedAt.toISOString(),
+        deadlineAt: new Date(startedAt.getTime() + timeoutMs).toISOString(),
+        spawnClockTicks,
+      };
+
+      this.children.set(runId, { pid });
+      await this.store.write(initialStatus);
+      resolveReady!();
+      return runId;
+    } catch (err) {
+      this.children.delete(runId);
+      if (typeof launchedPid === "number") {
+        // Defense in depth: the launcher handles /proc/bootstrap failures, while the orchestrator
+        // still owns cleanup for later failures such as status.json persistence after launch.
+        try {
+          this.launcher.signalProcess(launchedPid, "SIGTERM");
+        } catch {}
+      } else if (typeof launchedChild?.pid === "number") {
+        try {
+          this.launcher.signalProcess(launchedChild.pid, "SIGTERM");
+        } catch {}
+      }
+      resolveReady!();
+      this.statusReady.delete(runId);
+      throw err;
+    }
+  }
+
+  async status(runId: string): Promise<RunStatus | null> {
+    const current = await this.store.read(runId);
+    if (!current) return null;
+    if (current.status !== "running") return current;
+    return this.refreshRunningStatus(current);
+  }
+
+  async list(): Promise<RunStatus[]> { return this.listRuns(true); }
+  async listRaw(): Promise<RunStatus[]> { return this.listRuns(false); }
+
+  private async listRuns(refresh: boolean): Promise<RunStatus[]> {
+    const dirs = await this.store.listDirs();
+    const statuses = await Promise.all(
+      dirs.map((id) => refresh ? this.status(id) : this.store.read(id)),
+    );
+    return statuses.filter((s): s is RunStatus => s !== null);
+  }
+
+  async abort(runId: string): Promise<void> { await this.terminationHandler.terminateRun(runId, "aborted"); }
+
+  async enforceTimeout(runId: string): Promise<RunStatus | null> {
+    const current = await this.store.read(runId);
+    if (!current || current.status !== "running") return current;
+    return this.terminationHandler.terminateRun(runId, "timeout");
+  }
+
+  async recoverRun(runId: string): Promise<RunStatus | null> {
+    const current = await this.store.read(runId);
+    if (!current || current.status !== "running") return current;
+    return this.refreshRunningStatus(current, true);
+  }
+
+  private async refreshRunningStatus(current: RunStatus, notify = false): Promise<RunStatus> {
+    const alive = await this.isProcessAlive(current.pid, current.spawnClockTicks);
+    if (alive) return current;
+
+    const outcome = this.terminationHandler.terminalStatusFor(current);
+    return this.finalizer.finalizeRun(current.runId, outcome, { notify });
+  }
+
+  private async handleChildExit(runId: string, exitCode: number | null): Promise<void> {
+    const ready = this.statusReady.get(runId);
+    if (ready) {
+      await ready;
+      this.statusReady.delete(runId);
+    }
+
+    this.children.delete(runId);
+
+    const current = await this.store.read(runId);
+    if (!current || current.status !== "running") return;
+
+    const outcome = current.requestedOutcome
+      ? this.terminationHandler.terminalStatusFor(current)
+      : (exitCode === 0 ? "complete" : "failed");
+
+    await this.finalizer.finalizeRun(runId, outcome, { exitCode: exitCode ?? undefined });
+  }
+}
+
+async function assertDirectoryExists(path: string): Promise<void> {
+  try {
+    const info = await stat(path);
+    if (!info.isDirectory()) throw new Error(`Sub-agent cwd is not a directory: ${path}`);
+  } catch (err: any) {
+    if (err?.code === "ENOENT") throw new Error(`Sub-agent cwd does not exist: ${path}`);
+    throw err;
+  }
+}

package/src/subagents/pid.ts

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+
+export interface ParsedStatFile {
+  state: string;
+  starttime: string;
+  isZombie: boolean;
+}
+
+export function parseStatFile(content: string): ParsedStatFile {
+  const trimmed = content.trim();
+  // Field 2 (comm) is parenthesized and can contain spaces/parens.
+  // Strip everything through the LAST ") " to safely reach field 3+.
+  const boundary = trimmed.lastIndexOf(") ");
+  if (boundary === -1) {
+    throw new Error("Invalid /proc stat format");
+  }
+
+  // After stripping pid + comm, remainder starts at field 3.
+  // fields[0] = state (field 3), fields[19] = starttime (field 22).
+  const remainder = trimmed.slice(boundary + 2).trim();
+  const fields = remainder.split(/\s+/);
+  if (fields.length < 20) {
+    throw new Error("Incomplete /proc stat format");
+  }
+
+  const state = fields[0];
+  const starttime = fields[19]; // Original /proc field 22 (starttime)
+  if (!state || !starttime) {
+    throw new Error("Missing required /proc stat fields");
+  }
+
+  return {
+    state,
+    starttime,
+    isZombie: state === "Z",
+  };
+}
+
+export async function readSpawnClockTicks(pid: number): Promise<string> {
+  const content = await readFile(`/proc/${pid}/stat`, "utf8");
+  return parseStatFile(content).starttime;
+}
+
+export async function isProcessAlive(pid: number, expectedTicks: string): Promise<boolean> {
+  try {
+    const content = await readFile(`/proc/${pid}/stat`, "utf8");
+    const parsed = parseStatFile(content);
+    return !parsed.isZombie && parsed.starttime === expectedTicks;
+  } catch {
+    return false;
+  }
+}

package/src/subagents/process-launcher.ts

@@ -0,0 +1,102 @@
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { readSpawnClockTicks as defaultReadSpawnClockTicks } from "./pid";
+
+export interface LaunchResult {
+  child: ChildProcess;
+  pid: number;
+  spawnClockTicks: string;
+}
+
+export interface ProcessLauncherOptions {
+  spawnProcess?: typeof spawn;
+  checkPiAvailable?: () => void;
+  readSpawnClockTicks?: (pid: number) => Promise<string>;
+  signalProcess?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+}
+
+export class ProcessLauncher {
+  private readonly spawnProcess: typeof spawn;
+  private readonly checkPiAvailable: () => void;
+  private readonly readSpawnClockTicksFn: (pid: number) => Promise<string>;
+  readonly signalProcess: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+
+  constructor(options: ProcessLauncherOptions = {}) {
+    this.spawnProcess = options.spawnProcess ?? spawn;
+    this.checkPiAvailable = options.checkPiAvailable ?? defaultPiAvailabilityCheck;
+    this.readSpawnClockTicksFn = options.readSpawnClockTicks ?? defaultReadSpawnClockTicks;
+    this.signalProcess = options.signalProcess ?? defaultSignalProcess;
+  }
+
+  assertAvailable(): void {
+    this.checkPiAvailable();
+  }
+
+  async launch(runDir: string, cwd: string, onChildCreated?: (child: ChildProcess) => void): Promise<LaunchResult> {
+    const stdoutHandle = await open(join(runDir, "stdout.log"), "a");
+    const stderrHandle = await open(join(runDir, "stderr.log"), "a");
+    let child: ChildProcess | undefined;
+
+    try {
+      child = this.spawnProcess("pi", ["--session-dir", runDir, "-p", `@${join(runDir, "brief.md")}`], {
+        cwd,
+        detached: true,
+        stdio: ["ignore", stdoutHandle.fd, stderrHandle.fd],
+      });
+      onChildCreated?.(child);
+
+      await waitForChildSpawn(child);
+
+      if (typeof child.pid !== "number") {
+        throw new Error("Sub-agent process did not expose a PID");
+      }
+
+      const spawnClockTicks = await this.readSpawnClockTicksFn(child.pid);
+      child.unref();
+
+      return { child, pid: child.pid, spawnClockTicks };
+    } catch (err) {
+      if (typeof child?.pid === "number") {
+        try {
+          this.signalProcess(child.pid, "SIGTERM");
+        } catch {}
+      }
+      throw err;
+    } finally {
+      await Promise.allSettled([stdoutHandle.close(), stderrHandle.close()]);
+    }
+  }
+}
+
+function defaultPiAvailabilityCheck(): void {
+  if (piAvailableCache === true) return;
+  // No negative caching — retry on every spawn so installing pi mid-session works
+  try {
+    execFileSync("which", ["pi"], { stdio: "pipe" });
+    piAvailableCache = true;
+  } catch {
+    throw new Error("pi executable not found in PATH");
+  }
+}
+
+let piAvailableCache: boolean | undefined;
+
+function defaultSignalProcess(pid: number, signal: "SIGTERM" | "SIGKILL"): void {
+  process.kill(pid, signal);
+}
+
+async function waitForChildSpawn(child: ChildProcess): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const onSpawn = (): void => {
+      child.off("error", onError);
+      resolve();
+    };
+    const onError = (err: Error): void => {
+      child.off("spawn", onSpawn);
+      reject(err);
+    };
+    child.once("spawn", onSpawn);
+    child.once("error", onError);
+  });
+}

package/src/subagents/run-finalizer.ts

@@ -0,0 +1,64 @@
+import { RunStore } from "./run-store";
+import type { RunStatus, TerminalStatus } from "./types";
+
+type CompletionListener = (status: RunStatus) => Promise<void> | void;
+
+export interface RunFinalizerOptions {
+  store: RunStore;
+  now: () => Date;
+}
+
+export class RunFinalizer {
+  private readonly store: RunStore;
+  private readonly now: () => Date;
+  private readonly completionListeners = new Set<CompletionListener>();
+  private readonly finalizingRuns = new Map<string, Promise<RunStatus>>();
+
+  constructor(options: RunFinalizerOptions) {
+    this.store = options.store;
+    this.now = options.now;
+  }
+
+  onCompletion(listener: CompletionListener): () => void {
+    this.completionListeners.add(listener);
+    return () => { this.completionListeners.delete(listener); };
+  }
+
+  async finalizeRun(
+    runId: string,
+    status: TerminalStatus,
+    extra: { exitCode?: number; notify?: boolean },
+  ): Promise<RunStatus> {
+    const inFlight = this.finalizingRuns.get(runId);
+    if (inFlight) return inFlight;
+
+    const finalization = (async (): Promise<RunStatus> => {
+      const latest = await this.store.read(runId);
+      if (!latest) throw new Error(`Unknown sub-agent run: ${runId}`);
+      if (latest.status !== "running") return latest;
+
+      const updated: RunStatus = {
+        ...latest,
+        status,
+        completedAt: this.now().toISOString(),
+        exitCode: extra.exitCode ?? latest.exitCode,
+      };
+
+      await this.store.write(updated);
+      if (extra.notify !== false) {
+        await Promise.allSettled(
+          [...this.completionListeners].map((listener) => Promise.resolve(listener(updated))),
+        );
+      }
+      return updated;
+    })();
+
+    this.finalizingRuns.set(runId, finalization);
+    try {
+      return await finalization;
+    } finally {
+      this.finalizingRuns.delete(runId);
+    }
+  }
+}
+

package/src/subagents/run-store.ts

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, readdir, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { RunStatus } from "./types";
+
+const RUN_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export function validateRunId(runId: string): string {
+  if (!RUN_ID_RE.test(runId)) {
+    throw new Error(`Invalid sub-agent run ID: ${runId}`);
+  }
+  return runId;
+}
+
+export class RunStore {
+  private readonly subagentsRoot: string;
+
+  constructor(dataRoot: string) {
+    this.subagentsRoot = join(dataRoot, "subagents");
+  }
+
+  getRunDir(runId: string): string {
+    return join(this.subagentsRoot, validateRunId(runId));
+  }
+
+  async read(runId: string): Promise<RunStatus | null> {
+    try {
+      const raw = await readFile(join(this.getRunDir(runId), "status.json"), "utf8");
+      return JSON.parse(raw) as RunStatus;
+    } catch (err: any) {
+      if (err?.code === "ENOENT") return null;
+      throw err;
+    }
+  }
+
+  async write(status: RunStatus): Promise<void> {
+    const dir = this.getRunDir(status.runId);
+    await mkdir(dir, { recursive: true });
+    await atomicWriteJson(join(dir, "status.json"), status);
+  }
+
+  async listDirs(): Promise<string[]> {
+    try {
+      const entries = await readdir(this.subagentsRoot, { withFileTypes: true });
+      return entries
+        .filter((e) => e.isDirectory() && RUN_ID_RE.test(e.name))
+        .map((e) => e.name);
+    } catch (err: any) {
+      if (err?.code === "ENOENT") return [];
+      throw err;
+    }
+  }
+
+  async writeFile(runId: string, filename: string, content: string): Promise<void> {
+    const dir = this.getRunDir(runId);
+    await mkdir(dir, { recursive: true });
+    await atomicWriteText(join(dir, filename), content);
+  }
+
+  async writeJson(runId: string, filename: string, value: unknown): Promise<void> {
+    const dir = this.getRunDir(runId);
+    await mkdir(dir, { recursive: true });
+    await atomicWriteJson(join(dir, filename), value);
+  }
+}
+
+async function atomicWriteJson(path: string, value: unknown): Promise<void> {
+  await atomicWriteText(path, JSON.stringify(value, null, 2) + "\n");
+}
+
+async function atomicWriteText(path: string, content: string): Promise<void> {
+  const tmp = `${path}.tmp.${randomUUID()}`;
+  try {
+    await writeFile(tmp, content, { mode: 0o600 });
+    await rename(tmp, path);
+  } catch (err) {
+    try { await unlink(tmp); } catch {}
+    throw err;
+  }
+}

package/src/subagents/termination-handler.ts

@@ -0,0 +1,87 @@
+import type { RunStatus, TerminalStatus } from "./types";
+import { RunStore } from "./run-store";
+
+const TERMINATE_GRACE_MS = 10_000;
+
+type RequestedOutcome = NonNullable<RunStatus["requestedOutcome"]>;
+
+export interface TerminationHandlerOptions {
+  store: RunStore;
+  isProcessAlive: (pid: number, expectedTicks: string) => Promise<boolean>;
+  signalProcess: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+  finalizeRun: (
+    runId: string,
+    status: TerminalStatus,
+    extra: { exitCode?: number; notify?: boolean },
+  ) => Promise<RunStatus>;
+}
+
+export class TerminationHandler {
+  private readonly store: RunStore;
+  private readonly isProcessAlive: (pid: number, expectedTicks: string) => Promise<boolean>;
+  private readonly signalProcess: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+  private readonly finalizeRun: (
+    runId: string,
+    status: TerminalStatus,
+    extra: { exitCode?: number; notify?: boolean },
+  ) => Promise<RunStatus>;
+
+  constructor(options: TerminationHandlerOptions) {
+    this.store = options.store;
+    this.isProcessAlive = options.isProcessAlive;
+    this.signalProcess = options.signalProcess;
+    this.finalizeRun = options.finalizeRun;
+  }
+
+  async terminateRun(runId: string, outcome: RequestedOutcome): Promise<RunStatus | null> {
+    const current = await this.store.read(runId);
+    if (!current || current.status !== "running") return current;
+    const updated = await this.persistRequestedOutcome(current, outcome);
+
+    const alive = await this.isProcessAlive(updated.pid, updated.spawnClockTicks);
+    if (!alive) {
+      return this.finalizeRun(runId, this.terminalStatusFor(updated), {});
+    }
+
+    try {
+      this.signalProcess(updated.pid, "SIGTERM");
+    } catch {
+      return this.finalizeRun(runId, this.terminalStatusFor(updated), {});
+    }
+
+    setTimeout(() => {
+      void this.escalateTermination(runId, updated.pid, updated.spawnClockTicks);
+    }, TERMINATE_GRACE_MS);
+
+    return updated;
+  }
+
+  async escalateTermination(runId: string, pid: number, spawnClockTicks: string): Promise<void> {
+    const current = await this.store.read(runId);
+    if (!current || current.status !== "running") return;
+    if (current.pid !== pid || current.spawnClockTicks !== spawnClockTicks) return;
+
+    const alive = await this.isProcessAlive(pid, spawnClockTicks);
+    if (!alive) return;
+
+    try {
+      this.signalProcess(pid, "SIGKILL");
+    } catch {}
+  }
+
+  terminalStatusFor(status: RunStatus): TerminalStatus {
+    if (status.requestedOutcome === "timeout") return "timeout";
+    // "aborted" maps to "failed" because there's no "aborted" terminal status in the
+    // RunStatus union — abort is an intent, "failed" is the observable outcome.
+    if (status.requestedOutcome === "aborted") return "failed";
+    return "failed";
+  }
+
+  async persistRequestedOutcome(current: RunStatus, requestedOutcome: RequestedOutcome): Promise<RunStatus> {
+    if (current.requestedOutcome === requestedOutcome) return current;
+    const updated: RunStatus = { ...current, requestedOutcome };
+    await this.store.write(updated);
+    return updated;
+  }
+}
+

package/src/subagents/types.ts

@@ -0,0 +1,57 @@
+export type SubAgentRole = "review" | "research" | "scout" | "implementation";
+
+/** Terminal states for a sub-agent run (excludes "running") */
+export type TerminalStatus = Exclude<RunStatus["status"], "running">;
+
+export interface RoutingInfo {
+  transport: "telegram";
+  chatId: string;
+  topicId?: string;
+  parentThreadId: string;
+}
+
+export interface SpawnSpec {
+  role: SubAgentRole;
+  task: string;
+  cwd: string;
+  routing: RoutingInfo;
+  context?: {
+    briefing?: string;
+    targetFiles?: string[];
+    completionContract?: string;
+  };
+  model?: string;
+  timeoutMs?: number;
+}
+
+export interface RunStatus {
+  runId: string;
+  role: SubAgentRole;
+  cwd: string;
+  routing: RoutingInfo;
+  status: "running" | "complete" | "failed" | "timeout";
+  requestedOutcome?: "aborted" | "timeout";
+  pid: number;
+  startedAt: string;
+  deadlineAt?: string;
+  completedAt?: string;
+  exitCode?: number;
+  spawnClockTicks: string;
+}
+
+/** Public API for consumers (gateway, commands, agent tools) */
+export interface SubAgentOrchestrator {
+  spawn(spec: SpawnSpec): Promise<string>;
+  status(runId: string): Promise<RunStatus | null>;
+  list(): Promise<RunStatus[]>;
+  abort(runId: string): Promise<void>;
+}
+
+/** Internal API used by SubAgentWatcher for lifecycle management */
+export interface SubAgentLifecycle {
+  listRaw(): Promise<RunStatus[]>;
+  recoverRun(runId: string): Promise<RunStatus | null>;
+  enforceTimeout(runId: string): Promise<RunStatus | null>;
+  isRunManagedInProcess(runId: string): boolean;
+  onCompletion(listener: (status: RunStatus) => Promise<void> | void): () => void;
+}

package/src/subagents/watcher.ts

@@ -0,0 +1,63 @@
+import type { RoutingInfo, RunStatus, SubAgentLifecycle } from "./types";
+
+export class SubAgentWatcher {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private polling = false;
+
+  constructor(
+    private readonly orchestrator: SubAgentLifecycle,
+    private readonly notifyCompletion: (status: RunStatus, routing: RoutingInfo) => Promise<void> | void,
+    private readonly pollIntervalMs = 5000,
+  ) {}
+
+  start(): void {
+    if (this.timer) return;
+
+    this.unsubscribe = this.orchestrator.onCompletion((status) =>
+      this.notifyCompletion(status, status.routing),
+    );
+
+    this.timer = setInterval(() => {
+      void this.poll().catch((err) => {
+        console.error("[roundhouse] subagent watcher poll error:", err);
+      });
+    }, this.pollIntervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = null;
+    }
+  }
+
+  private async poll(): Promise<void> {
+    if (this.polling) return;
+    this.polling = true;
+
+    try {
+      const statuses = await this.orchestrator.listRaw();
+      const now = Date.now();
+
+      for (const status of statuses) {
+        if (status.status !== "running") continue;
+        if (this.orchestrator.isRunManagedInProcess(status.runId)) continue;
+
+        if (status.deadlineAt && Date.parse(status.deadlineAt) <= now) {
+          await this.orchestrator.enforceTimeout(status.runId);
+        } else {
+          // Detect crashed out-of-process children and finalize with notification
+          await this.orchestrator.recoverRun(status.runId);
+        }
+      }
+    } finally {
+      this.polling = false;
+    }
+  }
+}

package/src/transports/telegram/telegram-adapter.ts

@@ -50,12 +50,12 @@ export class TelegramAdapter implements TransportAdapter {
     return isTelegramThread(thread as any);
   }
 
-  async notify(chatIds: number[], text: string): Promise<void> {
+  async notify(chatIds: number[], text: string, options?: { parseMode?: string }): Promise<void> {
     if (!process.env.TELEGRAM_BOT_TOKEN) {
       console.warn("[roundhouse] TELEGRAM_BOT_TOKEN not set — skipping notification");
       return;
     }
-    await sendTelegramToMany(chatIds, text);
+    await sendTelegramToMany(chatIds, text, options);
   }
 
   async isPairingPending(): Promise<boolean> {

package/src/transports/types.ts

@@ -54,7 +54,7 @@ export interface TransportAdapter {
   ownsThread(thread: ChatThread): boolean;
 
   /** Send notifications to configured recipients */
-  notify(chatIds: number[], text: string): Promise<void>;
+  notify(chatIds: number[], text: string, options?: { parseMode?: string }): Promise<void>;
 
   /**
    * Check if a pairing flow is pending.