@sna-sdk/core 0.3.0 → 0.4.0

package/README.md

@@ -86,6 +86,11 @@ const db = getDb(); // SQLite instance (data/sna.db)
 | `@sna-sdk/core/lib/sna-run` | `snaRun()` helper for spawning Claude Code |
 | `@sna-sdk/core/testing` | `startMockAnthropicServer()` for testing without real API calls |
 
+**Environment Variables:**
+- `SNA_DB_PATH` — Override SQLite database location (default: `process.cwd()/data/sna.db`)
+- `SNA_CLAUDE_COMMAND` — Override claude binary path
+- `SNA_PORT` — API server port (default: 3099)
+
 ## Documentation
 
 - [Architecture](https://github.com/neuradex/sna/blob/main/docs/architecture.md)

package/dist/core/providers/cc-history-adapter.d.ts

@@ -0,0 +1,37 @@
+import { HistoryMessage } from './types.js';
+
+/**
+ * History injection for Claude Code via JSONL resume.
+ *
+ * Writes a JSONL session file and passes --resume <filepath> to CC.
+ * CC loads it as real multi-turn conversation history.
+ *
+ * Key discovery: --resume with a .jsonl file path bypasses CC's project
+ * directory lookup and calls loadMessagesFromJsonlPath directly.
+ * This is the only reliable way to inject synthetic history.
+ *
+ * Verified: real Claude Haiku correctly recalls injected context.
+ * Fallback: recalled-conversation XML if file write fails.
+ */
+
+/**
+ * Write a JSONL session file for --resume <filepath>.
+ *
+ * Minimal format (verified working):
+ *   {"parentUuid":null,"isSidechain":false,"type":"user","uuid":"...","timestamp":"...","cwd":"...","sessionId":"...","message":{"role":"user","content":"..."}}
+ *   {"parentUuid":"<prev>","isSidechain":false,"type":"assistant","uuid":"...","timestamp":"...","cwd":"...","sessionId":"...","message":{"role":"assistant","content":[{"type":"text","text":"..."}]}}
+ */
+declare function writeHistoryJsonl(history: HistoryMessage[], opts: {
+    cwd: string;
+}): {
+    filePath: string;
+    extraArgs: string[];
+} | null;
+/**
+ * Pack history into a single assistant stdin message.
+ * CC treats type:"assistant" as context injection (no API call triggered).
+ * Used when file write fails.
+ */
+declare function buildRecalledConversation(history: HistoryMessage[]): string;
+
+export { buildRecalledConversation, writeHistoryJsonl };

package/dist/core/providers/cc-history-adapter.js

@@ -0,0 +1,70 @@
+import fs from "fs";
+import path from "path";
+function writeHistoryJsonl(history, opts) {
+  for (let i = 1; i < history.length; i++) {
+    if (history[i].role === history[i - 1].role) {
+      throw new Error(
+        `History validation failed: consecutive ${history[i].role} at index ${i - 1} and ${i}. Messages must alternate user\u2194assistant. Merge tool results into text before injecting.`
+      );
+    }
+  }
+  try {
+    const dir = path.join(opts.cwd, ".sna", "history");
+    fs.mkdirSync(dir, { recursive: true });
+    const sessionId = crypto.randomUUID();
+    const filePath = path.join(dir, `${sessionId}.jsonl`);
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const lines = [];
+    let prevUuid = null;
+    for (const msg of history) {
+      const uuid = crypto.randomUUID();
+      if (msg.role === "user") {
+        lines.push(JSON.stringify({
+          parentUuid: prevUuid,
+          isSidechain: false,
+          type: "user",
+          uuid,
+          timestamp: now,
+          cwd: opts.cwd,
+          sessionId,
+          message: { role: "user", content: msg.content }
+        }));
+      } else {
+        lines.push(JSON.stringify({
+          parentUuid: prevUuid,
+          isSidechain: false,
+          type: "assistant",
+          uuid,
+          timestamp: now,
+          cwd: opts.cwd,
+          sessionId,
+          message: {
+            role: "assistant",
+            content: [{ type: "text", text: msg.content }]
+          }
+        }));
+      }
+      prevUuid = uuid;
+    }
+    fs.writeFileSync(filePath, lines.join("\n") + "\n");
+    return { filePath, extraArgs: ["--resume", filePath] };
+  } catch {
+    return null;
+  }
+}
+function buildRecalledConversation(history) {
+  const xml = history.map((msg) => `<${msg.role}>${msg.content}</${msg.role}>`).join("\n");
+  return JSON.stringify({
+    type: "assistant",
+    message: {
+      role: "assistant",
+      content: [{ type: "text", text: `<recalled-conversation>
+${xml}
+</recalled-conversation>` }]
+    }
+  });
+}
+export {
+  buildRecalledConversation,
+  writeHistoryJsonl
+};

package/dist/core/providers/claude-code.js

@@ -2,6 +2,7 @@ import { spawn, execSync } from "child_process";
 import { EventEmitter } from "events";
 import fs from "fs";
 import path from "path";
+import { writeHistoryJsonl, buildRecalledConversation } from "./cc-history-adapter.js";
 import { logger } from "../../lib/logger.js";
 const SHELL = process.env.SHELL || "/bin/zsh";
 function resolveClaudePath(cwd) {
@@ -79,28 +80,9 @@ class ClaudeCodeProcess {
       this._alive = false;
       this.emitter.emit("error", err);
     });
-    if (options.history?.length) {
-      if (!options.prompt) {
-        throw new Error("history requires a prompt \u2014 the last stdin message must be a user message");
-      }
-      for (const msg of options.history) {
-        if (msg.role === "user") {
-          const line = JSON.stringify({
-            type: "user",
-            message: { role: "user", content: msg.content }
-          });
-          this.proc.stdin.write(line + "\n");
-        } else if (msg.role === "assistant") {
-          const line = JSON.stringify({
-            type: "assistant",
-            message: {
-              role: "assistant",
-              content: [{ type: "text", text: msg.content }]
-            }
-          });
-          this.proc.stdin.write(line + "\n");
-        }
-      }
+    if (options.history?.length && !options._historyViaResume) {
+      const line = buildRecalledConversation(options.history);
+      this.proc.stdin.write(line + "\n");
     }
     if (options.prompt) {
       this.send(options.prompt);
@@ -341,6 +323,14 @@ class ClaudeCodeProvider {
     if (options.permissionMode) {
       args.push("--permission-mode", options.permissionMode);
     }
+    if (options.history?.length && options.prompt) {
+      const result = writeHistoryJsonl(options.history, { cwd: options.cwd });
+      if (result) {
+        args.push(...result.extraArgs);
+        options._historyViaResume = true;
+        logger.log("agent", `history via JSONL resume \u2192 ${result.filePath}`);
+      }
+    }
     if (extraArgsClean.length > 0) {
       args.push(...extraArgsClean);
     }

package/dist/core/providers/types.d.ts

@@ -63,6 +63,8 @@ interface SpawnOptions {
      * Must alternate user→assistant. Assistant content is auto-wrapped in array format.
      */
     history?: HistoryMessage[];
+    /** @internal Set by provider when history was injected via JSONL resume. */
+    _historyViaResume?: boolean;
     /**
      * Additional CLI flags passed directly to the agent binary.
      * e.g. ["--system-prompt", "You are...", "--append-system-prompt", "Also...", "--mcp-config", "path"]

package/dist/db/schema.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 import fs from "fs";
 import path from "path";
-const DB_PATH = path.join(process.cwd(), "data/sna.db");
+const DB_PATH = process.env.SNA_DB_PATH ?? path.join(process.cwd(), "data/sna.db");
 const NATIVE_DIR = path.join(process.cwd(), ".sna/native");
 let _db = null;
 function loadBetterSqlite3() {

package/dist/scripts/sna.js

@@ -212,6 +212,9 @@ function cmdTu(args2) {
     case "claude":
       cmdTuClaude(args2.slice(1));
       break;
+    case "claude:oneshot":
+      cmdTuClaudeOneshot(args2.slice(1));
+      break;
     default:
       console.log(`
   sna tu \u2014 Test utilities (mock Anthropic API)
@@ -221,7 +224,8 @@ function cmdTu(args2) {
     sna tu api:down     Stop mock API server
     sna tu api:log      Show mock API request/response log
     sna tu api:log -f   Follow log in real-time (tail -f)
-    sna tu claude ...   Run claude with mock API env vars (proxy)
+    sna tu claude ...          Run claude with mock API env vars (proxy)
+    sna tu claude:oneshot ...  One-shot: mock server \u2192 claude \u2192 results \u2192 cleanup
 
   Flow:
     1. sna tu api:up            \u2192 mock server on random port
@@ -338,6 +342,19 @@ function cmdTuClaude(args2) {
     process.exit(e.status ?? 1);
   }
 }
+function cmdTuClaudeOneshot(args2) {
+  const scriptDir = path.dirname(new URL(import.meta.url).pathname);
+  const oneshotScript = fs.existsSync(path.join(scriptDir, "tu-oneshot.js")) ? path.join(scriptDir, "tu-oneshot.js") : path.join(scriptDir, "tu-oneshot.ts");
+  try {
+    execSync(`node --import tsx "${oneshotScript}" ${args2.map((a) => `"${a}"`).join(" ")}`, {
+      stdio: "inherit",
+      cwd: ROOT,
+      timeout: 9e4
+    });
+  } catch (e) {
+    process.exit(e.status ?? 1);
+  }
+}
 function readPidFile(filePath) {
   try {
     return parseInt(fs.readFileSync(filePath, "utf8").trim(), 10) || null;
@@ -784,7 +801,8 @@ Testing:
   sna tu api:down     Stop mock API server
   sna tu api:log      Show mock API request/response log
   sna tu api:log -f   Follow log in real-time
-  sna tu claude ...   Run claude with mock API (isolated env, no account pollution)
+  sna tu claude ...          Run claude with mock API (isolated env)
+  sna tu claude:oneshot ...  One-shot: mock server \u2192 claude \u2192 structured results \u2192 cleanup
 
   Set SNA_CLAUDE_COMMAND to override claude binary in SDK.
   See: docs/testing.md

package/dist/scripts/tu-oneshot.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/scripts/tu-oneshot.js

@@ -0,0 +1,66 @@
+import { startMockAnthropicServer } from "../testing/mock-api.js";
+import { spawn } from "child_process";
+import fs from "fs";
+import path from "path";
+async function main() {
+  const ROOT = process.cwd();
+  const STATE_DIR = path.join(ROOT, ".sna");
+  const args = process.argv.slice(2);
+  let claudePath = "claude";
+  const cachedPath = path.join(STATE_DIR, "claude-path");
+  if (fs.existsSync(cachedPath)) {
+    claudePath = fs.readFileSync(cachedPath, "utf8").trim() || claudePath;
+  }
+  const mock = await startMockAnthropicServer();
+  const mockConfigDir = path.join(STATE_DIR, "mock-claude-oneshot");
+  fs.mkdirSync(mockConfigDir, { recursive: true });
+  const env = {
+    PATH: process.env.PATH ?? "",
+    HOME: process.env.HOME ?? "",
+    SHELL: process.env.SHELL ?? "/bin/zsh",
+    TERM: process.env.TERM ?? "xterm-256color",
+    LANG: process.env.LANG ?? "en_US.UTF-8",
+    ANTHROPIC_BASE_URL: `http://localhost:${mock.port}`,
+    ANTHROPIC_API_KEY: "sk-test-mock-oneshot",
+    CLAUDE_CONFIG_DIR: mockConfigDir
+  };
+  const stdoutPath = path.join(STATE_DIR, "mock-claude-stdout.log");
+  const stderrPath = path.join(STATE_DIR, "mock-claude-stderr.log");
+  const proc = spawn(claudePath, args, {
+    env,
+    cwd: ROOT,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  proc.stdout.on("data", (d) => {
+    stdout += d.toString();
+  });
+  proc.stderr.on("data", (d) => {
+    stderr += d.toString();
+  });
+  proc.stdout.pipe(process.stdout);
+  proc.on("exit", (code) => {
+    fs.writeFileSync(stdoutPath, stdout);
+    fs.writeFileSync(stderrPath, stderr);
+    console.log(`
+${"\u2500".repeat(60)}`);
+    console.log(`Mock API: ${mock.requests.length} request(s)`);
+    for (const req of mock.requests) {
+      console.log(`  model=${req.model} stream=${req.stream} messages=${req.messages?.length}`);
+    }
+    console.log(`
+Log files:`);
+    console.log(`  stdout:   ${stdoutPath}`);
+    console.log(`  stderr:   ${stderrPath}`);
+    console.log(`  api log:  ${path.join(STATE_DIR, "mock-api-last-request.json")}`);
+    console.log(`  config:   ${mockConfigDir}`);
+    console.log(`  exit:     ${code}`);
+    mock.close();
+    process.exit(code ?? 0);
+  });
+  setTimeout(() => {
+    proc.kill();
+  }, 6e4);
+}
+main();

package/dist/server/api-types.d.ts

@@ -25,6 +25,12 @@ interface ApiResponses {
     "agent.send": {
         status: "sent";
     };
+    "agent.resume": {
+        status: "resumed";
+        provider: string;
+        sessionId: string;
+        historyCount: number;
+    };
     "agent.restart": {
         status: "restarted";
         provider: string;
@@ -46,6 +52,7 @@ interface ApiResponses {
     };
     "agent.status": {
         alive: boolean;
+        agentStatus: "idle" | "busy" | "disconnected";
         sessionId: string | null;
         ccSessionId: string | null;
         eventCount: number;

package/dist/server/history-builder.d.ts

@@ -0,0 +1,16 @@
+import { HistoryMessage } from '../core/providers/types.js';
+
+/**
+ * Build HistoryMessage[] from chat_messages DB records.
+ *
+ * Filters to user/assistant roles, ensures alternation,
+ * and merges consecutive same-role messages.
+ */
+
+/**
+ * Load conversation history from DB for a session.
+ * Returns alternating user↔assistant messages ready for JSONL injection.
+ */
+declare function buildHistoryFromDb(sessionId: string): HistoryMessage[];
+
+export { buildHistoryFromDb };

package/dist/server/history-builder.js

@@ -0,0 +1,25 @@
+import { getDb } from "../db/schema.js";
+function buildHistoryFromDb(sessionId) {
+  const db = getDb();
+  const rows = db.prepare(
+    `SELECT role, content FROM chat_messages
+     WHERE session_id = ? AND role IN ('user', 'assistant')
+     ORDER BY id ASC`
+  ).all(sessionId);
+  if (rows.length === 0) return [];
+  const merged = [];
+  for (const row of rows) {
+    const role = row.role;
+    if (!row.content?.trim()) continue;
+    const last = merged[merged.length - 1];
+    if (last && last.role === role) {
+      last.content += "\n\n" + row.content;
+    } else {
+      merged.push({ role, content: row.content });
+    }
+  }
+  return merged;
+}
+export {
+  buildHistoryFromDb
+};

package/dist/server/index.d.ts

@@ -1,13 +1,14 @@
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 import { SessionManager } from './session-manager.js';
-export { Session, SessionConfigChangedEvent, SessionInfo, SessionLifecycleEvent, SessionLifecycleState, SessionManagerOptions, StartConfig } from './session-manager.js';
+export { AgentStatus, Session, SessionConfigChangedEvent, SessionInfo, SessionLifecycleEvent, SessionLifecycleState, SessionManagerOptions, StartConfig } from './session-manager.js';
 export { eventsRoute } from './routes/events.js';
 export { createEmitRoute, emitRoute } from './routes/emit.js';
 export { createRunRoute } from './routes/run.js';
 export { createAgentRoutes } from './routes/agent.js';
 export { createChatRoutes } from './routes/chat.js';
 export { attachWebSocket } from './ws.js';
+export { buildHistoryFromDb } from './history-builder.js';
 import '../core/providers/types.js';
 import 'hono/utils/http-status';
 import 'ws';

package/dist/server/index.js

@@ -27,6 +27,7 @@ import { createAgentRoutes as createAgentRoutes2 } from "./routes/agent.js";
 import { createChatRoutes as createChatRoutes2 } from "./routes/chat.js";
 import { SessionManager as SessionManager2 } from "./session-manager.js";
 import { attachWebSocket } from "./ws.js";
+import { buildHistoryFromDb } from "./history-builder.js";
 function snaPortRoute(c) {
   const portFile = _path.join(process.cwd(), ".sna/sna-api.port");
   try {
@@ -39,6 +40,7 @@ function snaPortRoute(c) {
 export {
   SessionManager2 as SessionManager,
   attachWebSocket,
+  buildHistoryFromDb,
   createAgentRoutes2 as createAgentRoutes,
   createChatRoutes2 as createChatRoutes,
   createEmitRoute2 as createEmitRoute,

package/dist/server/routes/agent.js

@@ -5,6 +5,7 @@ import {
 } from "../../core/providers/index.js";
 import { logger } from "../../lib/logger.js";
 import { getDb } from "../../db/schema.js";
+import { buildHistoryFromDb } from "../history-builder.js";
 import { httpJson } from "../api-types.js";
 import { saveImages } from "../image-store.js";
 function getSessionId(c) {
@@ -194,7 +195,7 @@ function createAgentRoutes(sessionManager) {
       db.prepare(`INSERT INTO chat_messages (session_id, role, content, meta) VALUES (?, 'user', ?, ?)`).run(sessionId, textContent, Object.keys(meta).length > 0 ? JSON.stringify(meta) : null);
     } catch {
     }
-    session.state = "processing";
+    sessionManager.updateSessionState(sessionId, "processing");
     sessionManager.touch(sessionId);
     if (body.images?.length) {
       const content = [
@@ -272,6 +273,46 @@ function createAgentRoutes(sessionManager) {
       return c.json({ status: "error", message: e.message }, 500);
     }
   });
+  app.post("/resume", async (c) => {
+    const sessionId = getSessionId(c);
+    const body = await c.req.json().catch(() => ({}));
+    const session = sessionManager.getOrCreateSession(sessionId);
+    if (session.process?.alive) {
+      return c.json({ status: "error", message: "Session already running. Use agent.send instead." }, 400);
+    }
+    const history = buildHistoryFromDb(sessionId);
+    if (history.length === 0 && !body.prompt) {
+      return c.json({ status: "error", message: "No history in DB \u2014 nothing to resume." }, 400);
+    }
+    const providerName = body.provider ?? "claude-code";
+    const model = body.model ?? session.lastStartConfig?.model ?? "claude-sonnet-4-6";
+    const permissionMode = body.permissionMode ?? session.lastStartConfig?.permissionMode ?? "acceptEdits";
+    const extraArgs = body.extraArgs ?? session.lastStartConfig?.extraArgs;
+    const provider = getProvider(providerName);
+    try {
+      const proc = provider.spawn({
+        cwd: session.cwd,
+        prompt: body.prompt,
+        model,
+        permissionMode,
+        env: { SNA_SESSION_ID: sessionId },
+        history: history.length > 0 ? history : void 0,
+        extraArgs
+      });
+      sessionManager.setProcess(sessionId, proc, "resumed");
+      sessionManager.saveStartConfig(sessionId, { provider: providerName, model, permissionMode, extraArgs });
+      logger.log("route", `POST /resume?session=${sessionId} \u2192 resumed (${history.length} history msgs)`);
+      return httpJson(c, "agent.resume", {
+        status: "resumed",
+        provider: providerName,
+        sessionId: session.id,
+        historyCount: history.length
+      });
+    } catch (e) {
+      logger.err("err", `POST /resume?session=${sessionId} \u2192 ${e.message}`);
+      return c.json({ status: "error", message: e.message }, 500);
+    }
+  });
   app.post("/interrupt", async (c) => {
     const sessionId = getSessionId(c);
     const interrupted = sessionManager.interruptSession(sessionId);
@@ -299,8 +340,10 @@ function createAgentRoutes(sessionManager) {
   app.get("/status", (c) => {
     const sessionId = getSessionId(c);
     const session = sessionManager.getSession(sessionId);
+    const alive = session?.process?.alive ?? false;
     return httpJson(c, "agent.status", {
-      alive: session?.process?.alive ?? false,
+      alive,
+      agentStatus: !alive ? "disconnected" : session?.state === "processing" ? "busy" : "idle",
       sessionId: session?.process?.sessionId ?? null,
       ccSessionId: session?.ccSessionId ?? null,
       eventCount: session?.eventCounter ?? 0,

package/dist/server/session-manager.d.ts

@@ -29,11 +29,13 @@ interface Session {
     createdAt: number;
     lastActivityAt: number;
 }
+type AgentStatus = "idle" | "busy" | "disconnected";
 interface SessionInfo {
     id: string;
     label: string;
     alive: boolean;
     state: SessionState;
+    agentStatus: AgentStatus;
     cwd: string;
     meta: Record<string, unknown> | null;
     config: StartConfig | null;
@@ -45,7 +47,7 @@ interface SessionInfo {
 interface SessionManagerOptions {
     maxSessions?: number;
 }
-type SessionLifecycleState = "started" | "killed" | "exited" | "crashed" | "restarted";
+type SessionLifecycleState = "started" | "resumed" | "killed" | "exited" | "crashed" | "restarted";
 interface SessionLifecycleEvent {
     session: string;
     state: SessionLifecycleState;
@@ -64,6 +66,7 @@ declare class SessionManager {
     private permissionRequestListeners;
     private lifecycleListeners;
     private configChangedListeners;
+    private stateChangedListeners;
     constructor(options?: SessionManagerOptions);
     /** Restore session metadata from DB (cwd, label, meta). Process state is not restored. */
     private restoreFromDb;
@@ -84,7 +87,7 @@ declare class SessionManager {
         cwd?: string;
     }): Session;
     /** Set the agent process for a session. Subscribes to events. */
-    setProcess(sessionId: string, proc: AgentProcess): void;
+    setProcess(sessionId: string, proc: AgentProcess, lifecycleState?: SessionLifecycleState): void;
     /** Subscribe to real-time events for a session. Returns unsubscribe function. */
     onSessionEvent(sessionId: string, cb: (cursor: number, event: AgentEvent) => void): () => void;
     /** Subscribe to skill events broadcast. Returns unsubscribe function. */
@@ -99,6 +102,14 @@ declare class SessionManager {
     /** Subscribe to session config changes. Returns unsubscribe function. */
     onConfigChanged(cb: (event: SessionConfigChangedEvent) => void): () => void;
     private emitConfigChanged;
+    onStateChanged(cb: (event: {
+        session: string;
+        agentStatus: AgentStatus;
+        state: SessionState;
+    }) => void): () => void;
+    /** Update session state and push agentStatus change to subscribers. */
+    updateSessionState(sessionId: string, newState: SessionState): void;
+    private setSessionState;
     /** Create a pending permission request. Returns a promise that resolves when approved/denied. */
     createPendingPermission(sessionId: string, request: Record<string, unknown>): Promise<boolean>;
     /** Resolve a pending permission request. Returns false if no pending request. */
@@ -142,4 +153,4 @@ declare class SessionManager {
     get size(): number;
 }
 
-export { type Session, type SessionConfigChangedEvent, type SessionInfo, type SessionLifecycleEvent, type SessionLifecycleState, SessionManager, type SessionManagerOptions, type SessionState, type StartConfig };
+export { type AgentStatus, type Session, type SessionConfigChangedEvent, type SessionInfo, type SessionLifecycleEvent, type SessionLifecycleState, SessionManager, type SessionManagerOptions, type SessionState, type StartConfig };

package/dist/server/session-manager.js

@@ -11,6 +11,7 @@ class SessionManager {
     this.permissionRequestListeners = /* @__PURE__ */ new Set();
     this.lifecycleListeners = /* @__PURE__ */ new Set();
     this.configChangedListeners = /* @__PURE__ */ new Set();
+    this.stateChangedListeners = /* @__PURE__ */ new Set();
     this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
     this.restoreFromDb();
   }
@@ -123,11 +124,11 @@ class SessionManager {
     return this.createSession({ id, ...opts });
   }
   /** Set the agent process for a session. Subscribes to events. */
-  setProcess(sessionId, proc) {
+  setProcess(sessionId, proc, lifecycleState) {
     const session = this.sessions.get(sessionId);
     if (!session) throw new Error(`Session "${sessionId}" not found`);
     session.process = proc;
-    session.state = "processing";
+    this.setSessionState(sessionId, session, "processing");
     session.lastActivityAt = Date.now();
     proc.on("event", (e) => {
       if (e.type === "init" && e.data?.sessionId && !session.ccSessionId) {
@@ -140,7 +141,7 @@ class SessionManager {
         session.eventBuffer.splice(0, session.eventBuffer.length - MAX_EVENT_BUFFER);
       }
       if (e.type === "complete" || e.type === "error" || e.type === "interrupted") {
-        session.state = "waiting";
+        this.setSessionState(sessionId, session, "waiting");
       }
       this.persistEvent(sessionId, e);
       const listeners = this.eventListeners.get(sessionId);
@@ -149,14 +150,14 @@ class SessionManager {
       }
     });
     proc.on("exit", (code) => {
-      session.state = "idle";
+      this.setSessionState(sessionId, session, "idle");
       this.emitLifecycle({ session: sessionId, state: code != null ? "exited" : "crashed", code });
     });
     proc.on("error", () => {
-      session.state = "idle";
+      this.setSessionState(sessionId, session, "idle");
       this.emitLifecycle({ session: sessionId, state: "crashed" });
     });
-    this.emitLifecycle({ session: sessionId, state: "started" });
+    this.emitLifecycle({ session: sessionId, state: lifecycleState ?? "started" });
   }
   // ── Event pub/sub (for WebSocket) ─────────────────────────────
   /** Subscribe to real-time events for a session. Returns unsubscribe function. */
@@ -206,11 +207,29 @@ class SessionManager {
   emitConfigChanged(sessionId, config) {
     for (const cb of this.configChangedListeners) cb({ session: sessionId, config });
   }
+  // ── Agent status change pub/sub ────────────────────────────────
+  onStateChanged(cb) {
+    this.stateChangedListeners.add(cb);
+    return () => this.stateChangedListeners.delete(cb);
+  }
+  /** Update session state and push agentStatus change to subscribers. */
+  updateSessionState(sessionId, newState) {
+    const session = this.sessions.get(sessionId);
+    if (session) this.setSessionState(sessionId, session, newState);
+  }
+  setSessionState(sessionId, session, newState) {
+    const oldState = session.state;
+    session.state = newState;
+    const newStatus = !session.process?.alive ? "disconnected" : newState === "processing" ? "busy" : "idle";
+    if (oldState !== newState) {
+      for (const cb of this.stateChangedListeners) cb({ session: sessionId, agentStatus: newStatus, state: newState });
+    }
+  }
   // ── Permission management ─────────────────────────────────────
   /** Create a pending permission request. Returns a promise that resolves when approved/denied. */
   createPendingPermission(sessionId, request) {
     const session = this.sessions.get(sessionId);
-    if (session) session.state = "permission";
+    if (session) this.setSessionState(sessionId, session, "permission");
     return new Promise((resolve) => {
       const createdAt = Date.now();
       this.pendingPermissions.set(sessionId, { resolve, request, createdAt });
@@ -230,7 +249,7 @@ class SessionManager {
     pending.resolve(approved);
     this.pendingPermissions.delete(sessionId);
     const session = this.sessions.get(sessionId);
-    if (session) session.state = "processing";
+    if (session) this.setSessionState(sessionId, session, "processing");
     return true;
   }
   /** Get a pending permission for a specific session. */
@@ -282,7 +301,7 @@ class SessionManager {
     const session = this.sessions.get(id);
     if (!session?.process?.alive) return false;
     session.process.interrupt();
-    session.state = "waiting";
+    this.setSessionState(id, session, "waiting");
     return true;
   }
   /** Change model. Sends control message if alive, always persists to config. */
@@ -339,6 +358,7 @@ class SessionManager {
       label: s.label,
       alive: s.process?.alive ?? false,
       state: s.state,
+      agentStatus: !s.process?.alive ? "disconnected" : s.state === "processing" ? "busy" : "idle",
       cwd: s.cwd,
       meta: s.meta,
       config: s.lastStartConfig,