@assistkick/create 1.26.0 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistkick/create",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "Scaffold assistkick-product-system into any project",
   "type": "module",
   "bin": {

package/templates/assistkick-product-system/packages/backend/src/server.ts

@@ -266,11 +266,14 @@ const terminalHandler = new TerminalWsHandler({ wss: terminalWss, authService, p
 
 // Set up WebSocket for Chat v2 streaming with permission management
 const chatWss = new WebSocketServer({ noServer: true });
-const chatCliBridge = new ChatCliBridge({ projectRoot: paths.projectRoot, workspacesDir: paths.workspacesDir, log });
+const chatCliBridge = new ChatCliBridge({ projectRoot: paths.projectRoot, workspacesDir: paths.workspacesDir, dataDir: paths.runtimeDataDir, log });
 const permissionService = new PermissionService({ getDb, log });
 const titleGeneratorService = new TitleGeneratorService({ log });
 const chatHandler = new ChatWsHandler({ wss: chatWss, authService, chatCliBridge, permissionService, chatMessageRepository, chatSessionService, titleGeneratorService, mcpConfigService, log });
 
+// Resume any CLI sessions left running by the previous server instance
+chatHandler.resumeSessions();
+
 // Chat permission routes — used by MCP permission server (no auth — internal only)
 const chatPermissionRoutes = createChatPermissionRoutes({ permissionService, log });
 app.use('/api/chat/permission', chatPermissionRoutes);
@@ -291,7 +294,7 @@ server.on('upgrade', (req, socket, head) => {
 process.on('SIGTERM', () => {
   previewManager.stopAll();
   ptyManager.destroyAllPty();
-  chatCliBridge.killAll();
+  chatCliBridge.detachAll(); // Release without killing — CLI processes survive restart
   server.close();
 });
 

package/templates/assistkick-product-system/packages/backend/src/services/chat_cli_bridge.ts

@@ -1,26 +1,31 @@
 /**
- * ChatCliBridge — spawns Claude Code CLI in non-interactive mode for Chat v2.
+ * ChatCliBridge — spawns Claude Code CLI as a detached process with file-based I/O.
+ *
+ * CLI processes survive server restarts (tsx watch). Output is written to temp files
+ * and tailed by the server. A manifest file tracks running sessions so the next
+ * server instance can resume tailing.
  *
  * Each user message spawns a new CLI invocation:
  *   claude -p - --output-format stream-json --verbose --include-partial-messages
  *          --append-system-prompt "We are working on project-id ${projectId}"
  *
  * New sessions use --session-id <uuid>, subsequent messages use --resume <uuid>.
- * Permission mode controls: --dangerously-skip-permissions, --allowedTools, or --permission-prompt-tool.
- * When permission mode is 'prompt', a temporary MCP config file is generated
- * pointing to the permission MCP server, and --mcp-config is passed to the CLI.
- * Emits parsed stream-json events via onEvent callback for downstream WebSocket forwarding.
  */
 
 import { spawn, type ChildProcess } from 'node:child_process';
 import { join } from 'node:path';
-import { existsSync, mkdirSync } from 'node:fs';
+import {
+  existsSync, mkdirSync, openSync, closeSync, readSync, fstatSync,
+  readFileSync, writeFileSync, unlinkSync, statSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
 
 export type PermissionMode = 'skip' | 'allowed_tools';
 
 export interface ChatCliBridgeDeps {
   projectRoot: string;
   workspacesDir: string;
+  dataDir: string;
   log: (tag: string, ...args: unknown[]) => void;
 }
 
@@ -42,7 +47,7 @@ export interface SpawnCompletion {
   exitCode: number | null;
   claudeSessionId: string;
   sessionId: string | null;
-  /** Captured stderr lines (if any) — useful for diagnosing non-zero exit codes */
+  /** Captured stderr (if any) — useful for diagnosing non-zero exit codes */
   stderr: string | null;
   /** Non-JSON lines from stdout (if any) — CLI errors often appear here */
   stdoutNonJsonLines: string | null;
@@ -55,35 +60,67 @@ export interface SpawnResult {
   systemPrompt: string | null;
 }
 
+/** Persisted metadata for an in-flight CLI session. */
+export interface CliSessionManifestEntry {
+  claudeSessionId: string;
+  pid: number;
+  stdoutPath: string;
+  stderrPath: string;
+  mcpConfigPath?: string;
+  startedAt: string;
+  /** Stream context metadata for WS handler reconstruction on resume. */
+  sessionId: string | null;
+  projectId: string;
+  userMessage: string;
+  attachmentBlocks: Array<{ type: string; path: string; name: string; mimeType: string }>;
+}
+
+/** Returned by resumeSessions() for each still-alive session. */
+export interface ResumedSession {
+  entry: CliSessionManifestEntry;
+  completion: Promise<SpawnCompletion>;
+}
+
+/** Internal state for an active file tailer. */
+interface TailerState {
+  interval: ReturnType<typeof setInterval>;
+  fd: number;
+  position: number;
+  lineBuf: string;
+  capturedSessionId: string | null;
+  stdoutNonJsonLines: string[];
+  onEvent: (event: Record<string, unknown>) => void;
+}
+
 export class ChatCliBridge {
   private readonly projectRoot: string;
   private readonly workspacesDir: string;
+  private readonly dataDir: string;
   private readonly log: ChatCliBridgeDeps['log'];
+  /** Child processes spawned in this server instance (have 'close' event). */
   private readonly activeProcesses = new Map<string, ChildProcess>();
+  /** Active file tailers (both direct spawns and resumed sessions). */
+  private readonly activeTailers = new Map<string, TailerState>();
+  private readonly manifestPath: string;
 
-  constructor({ projectRoot, workspacesDir, log }: ChatCliBridgeDeps) {
+  constructor({ projectRoot, workspacesDir, dataDir, log }: ChatCliBridgeDeps) {
     this.projectRoot = projectRoot;
     this.workspacesDir = workspacesDir;
+    this.dataDir = dataDir;
     this.log = log;
+    this.manifestPath = join(dataDir, 'active-cli-sessions.json');
+    if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
   }
 
-  /**
-   * Resolve the workspace directory path for a project (used in system prompt).
-   */
   getWorkspacePath = (projectId: string): string => {
     return join(this.workspacesDir, projectId);
   };
 
-  /**
-   * Build the CLI arguments array from spawn options.
-   * Returns both the args array and the composed system prompt text (if any).
-   */
   buildArgs = (options: SpawnOptions): { args: string[]; systemPrompt: string | null } => {
     const { projectId, claudeSessionId, isNewSession, permissionMode, allowedTools, continuationContext } = options;
     const args: string[] = [];
     let systemPrompt: string | null = null;
 
-    // Permission mode
     if (permissionMode === 'skip') {
       args.push('--dangerously-skip-permissions');
     } else if (permissionMode === 'allowed_tools' && allowedTools && allowedTools.length > 0) {
@@ -92,35 +129,27 @@ export class ChatCliBridge {
       }
     }
 
-    // MCP server configuration (temp file path)
     if (options.mcpConfigPath) {
       args.push('--mcp-config', options.mcpConfigPath);
     }
 
-    // Prompt via stdin
     args.push('-p', '-');
 
-    // Session management
     if (isNewSession) {
       args.push('--session-id', claudeSessionId);
     } else {
       args.push('--resume', claudeSessionId);
     }
 
-    // Output format
     args.push('--output-format', 'stream-json');
     args.push('--verbose');
     args.push('--include-partial-messages');
 
-    // Project context system prompt (only on first message; resumed sessions already have it)
     if (isNewSession) {
       const systemParts: string[] = [];
-
-      // Prepend compacted conversation context when continuing from a previous session
       if (continuationContext) {
         systemParts.push(continuationContext);
       }
-
       const wsPath = this.getWorkspacePath(projectId);
       systemParts.push(`We are working on project-id ${projectId}
 
@@ -145,10 +174,6 @@ export class ChatCliBridge {
     return { args, systemPrompt };
   };
 
-  /**
-   * Build environment variables for the CLI subprocess.
-   * Ensures common bin paths are available.
-   */
   buildEnv = (): Record<string, string> => {
     const env = { ...process.env } as Record<string, string>;
     const home = env.HOME || '/root';
@@ -168,8 +193,8 @@ export class ChatCliBridge {
   };
 
   /**
-   * Spawn a Claude CLI process for a chat message.
-   * Returns a handle to the child process and a promise that resolves on completion.
+   * Spawn a Claude CLI process as a detached process with file-based stdout/stderr.
+   * The process survives server restarts.
    */
   spawn = (options: SpawnOptions): SpawnResult => {
     const { projectId, message, claudeSessionId, isNewSession, onEvent } = options;
@@ -177,7 +202,6 @@ export class ChatCliBridge {
     const wsPath = this.getWorkspacePath(projectId);
     const { args, systemPrompt } = this.buildArgs(options);
 
-    // Ensure workspace directory exists (Docker volumes may not have project subdirs)
     if (!existsSync(wsPath)) {
       mkdirSync(wsPath, { recursive: true });
     }
@@ -186,105 +210,80 @@ export class ChatCliBridge {
     this.log('CHAT_CLI', `Spawning claude (${mode}) for project ${projectId}, session ${claudeSessionId}`);
     this.log('CHAT_CLI', `cwd: ${cwd} (exists: ${existsSync(cwd)}), args: claude ${args.join(' ')}`);
 
+    // Create temp files for stdout/stderr
+    const stdoutPath = join(tmpdir(), `claude-stdout-${claudeSessionId}.jsonl`);
+    const stderrPath = join(tmpdir(), `claude-stderr-${claudeSessionId}.log`);
+    const stdoutFd = openSync(stdoutPath, 'w');
+    const stderrFd = openSync(stderrPath, 'w');
+
     const child = spawn('claude', args, {
       cwd,
       env: this.buildEnv(),
-      stdio: ['pipe', 'pipe', 'pipe'],
+      detached: true,
+      stdio: ['pipe', stdoutFd, stderrFd],
     });
 
-    // Track active process by session
-    this.activeProcesses.set(claudeSessionId, child);
+    // Close write FDs in parent — kernel keeps them open for the child
+    closeSync(stdoutFd);
+    closeSync(stderrFd);
 
-    const completion = new Promise<SpawnCompletion>((resolve, reject) => {
-      let lineBuf = '';
-      let capturedSessionId: string | null = null;
-      let stdoutReceived = false;
-      let stderrLines: string[] = [];
-      let stdoutNonJsonLines: string[] = [];
-
-      // Attach error handlers on stdio streams to prevent unhandled 'error' events
-      // from crashing the process (e.g. EPIPE if CLI exits before stdin write completes)
-      child.stdin!.on('error', (err) => {
-        this.log('CHAT_CLI', `[stdin error] ${err.message}`);
-      });
-      child.stdout!.on('error', (err) => {
-        this.log('CHAT_CLI', `[stdout error] ${err.message}`);
-      });
-      child.stderr!.on('error', (err) => {
-        this.log('CHAT_CLI', `[stderr error] ${err.message}`);
-      });
-
-      child.stdout!.on('data', (chunk: Buffer) => {
-        stdoutReceived = true;
-        lineBuf += chunk.toString();
-        const lines = lineBuf.split('\n');
-        lineBuf = lines.pop()!;
-
-        for (const line of lines) {
-          const trimmed = line.trim();
-          if (!trimmed) continue;
-          this.processLine(trimmed, onEvent, (sid) => {
-            capturedSessionId = sid;
-          }, (nonJsonLine) => {
-            stdoutNonJsonLines.push(nonJsonLine);
-          });
-        }
-      });
+    const pid = child.pid!;
+    this.activeProcesses.set(claudeSessionId, child);
 
-      child.stderr!.on('data', (chunk: Buffer) => {
-        const text = chunk.toString();
-        text.split('\n').forEach(line => {
-          if (line.trim()) {
-            stderrLines.push(line.trim());
-            this.log('CHAT_CLI', `[stderr] ${line.trim()}`);
-          }
-        });
-      });
+    // Write message to stdin and close
+    child.stdin!.on('error', (err) => {
+      this.log('CHAT_CLI', `[stdin error] ${err.message}`);
+    });
+    child.stdin!.write(message);
+    child.stdin!.end();
+    this.log('CHAT_CLI', `Message written to stdin (${message.length} chars), pid ${pid}`);
+
+    // Save to manifest so next server instance can resume tailing
+    this.saveManifestEntry({
+      claudeSessionId,
+      pid,
+      stdoutPath,
+      stderrPath,
+      mcpConfigPath: options.mcpConfigPath,
+      startedAt: new Date().toISOString(),
+      sessionId: null, // WS handler sets this via setManifestMetadata()
+      projectId,
+      userMessage: message,
+      attachmentBlocks: [],
+    });
 
-      // Write the message to stdin and close
-      child.stdin!.write(message);
-      child.stdin!.end();
-      this.log('CHAT_CLI', `Message written to stdin (${message.length} chars)`);
+    // Start tailing the stdout file
+    const tailer = this.startTailer(claudeSessionId, stdoutPath, onEvent);
 
+    // When child exits normally (server still running), resolve via 'close' event
+    const completion = new Promise<SpawnCompletion>((resolve, reject) => {
       child.on('close', (code) => {
-        // Process any remaining data in the line buffer
-        if (lineBuf.trim()) {
-          this.processLine(lineBuf.trim(), onEvent, (sid) => {
-            capturedSessionId = sid;
-          }, (nonJsonLine) => {
-            stdoutNonJsonLines.push(nonJsonLine);
-          });
-        }
-
+        this.finishTailer(claudeSessionId, tailer);
         this.activeProcesses.delete(claudeSessionId);
 
+        const stderr = this.readStderrFile(stderrPath);
+
         if (code !== 0) {
           this.log('CHAT_CLI', `Process FAILED with exit code ${code} for session ${claudeSessionId}`);
-          if (stderrLines.length > 0) {
-            this.log('CHAT_CLI', `[stderr summary] ${stderrLines.join(' | ')}`);
-          }
-          if (stdoutNonJsonLines.length > 0) {
-            this.log('CHAT_CLI', `[stdout non-json summary] ${stdoutNonJsonLines.join(' | ')}`);
-          }
-          if (!stdoutReceived) {
-            this.log('CHAT_CLI', `No stdout received — CLI may have crashed or failed to start`);
-          }
         } else {
           this.log('CHAT_CLI', `Process exited successfully for session ${claudeSessionId}`);
         }
 
+        this.removeManifestEntry(claudeSessionId);
+        this.cleanupTempFiles(stdoutPath, stderrPath);
+
         resolve({
           exitCode: code,
           claudeSessionId,
-          sessionId: capturedSessionId,
-          stderr: stderrLines.length > 0 ? stderrLines.join('\n') : null,
-          stdoutNonJsonLines: stdoutNonJsonLines.length > 0 ? stdoutNonJsonLines.join('\n') : null,
+          sessionId: tailer.capturedSessionId,
+          stderr,
+          stdoutNonJsonLines: tailer.stdoutNonJsonLines.length > 0 ? tailer.stdoutNonJsonLines.join('\n') : null,
         });
       });
 
       child.on('error', (err) => {
         this.activeProcesses.delete(claudeSessionId);
-        this.log('CHAT_CLI', `Process spawn error for session ${claudeSessionId}: ${err.message} (${(err as NodeJS.ErrnoException).code || 'unknown'})`);
+        this.log('CHAT_CLI', `Process spawn error for session ${claudeSessionId}: ${err.message}`);
         reject(err);
       });
     });
@@ -292,61 +291,283 @@ export class ChatCliBridge {
     return { childProcess: child, completion, systemPrompt };
   };
 
+  /**
+   * Update manifest entry with stream context metadata (called by WS handler).
+   */
+  setManifestMetadata = (claudeSessionId: string, meta: {
+    sessionId?: string | null;
+    attachmentBlocks?: Array<{ type: string; path: string; name: string; mimeType: string }>;
+  }): void => {
+    const manifest = this.loadManifest();
+    const entry = manifest[claudeSessionId];
+    if (!entry) return;
+    if (meta.sessionId !== undefined) entry.sessionId = meta.sessionId;
+    if (meta.attachmentBlocks !== undefined) entry.attachmentBlocks = meta.attachmentBlocks;
+    this.writeManifest(manifest);
+  };
+
+  /**
+   * Resume tailing for CLI sessions left running by a previous server instance.
+   * Returns metadata + completion promises for each alive session.
+   */
+  resumeSessions = (
+    onEventFactory: (claudeSessionId: string) => (event: Record<string, unknown>) => void,
+  ): ResumedSession[] => {
+    const manifest = this.loadManifest();
+    const resumed: ResumedSession[] = [];
+    const alive: Record<string, CliSessionManifestEntry> = {};
+
+    for (const [id, entry] of Object.entries(manifest)) {
+      if (!this.isPidAlive(entry.pid) || !existsSync(entry.stdoutPath)) {
+        this.log('CHAT_CLI', `Cleaning up dead session ${id} (pid ${entry.pid})`);
+        this.cleanupTempFiles(entry.stdoutPath, entry.stderrPath, entry.mcpConfigPath);
+        continue;
+      }
+
+      this.log('CHAT_CLI', `Resuming tail for running session ${id} (pid ${entry.pid})`);
+      alive[id] = entry;
+
+      const onEvent = onEventFactory(id);
+      const tailer = this.startTailer(id, entry.stdoutPath, onEvent);
+
+      // Poll for process exit (no ChildProcess object for detached sessions from previous server)
+      const completion = new Promise<SpawnCompletion>((resolve) => {
+        const pollInterval = setInterval(() => {
+          if (!this.isPidAlive(entry.pid)) {
+            clearInterval(pollInterval);
+            this.finishTailer(id, tailer);
+
+            const stderr = this.readStderrFile(entry.stderrPath);
+            this.removeManifestEntry(id);
+            this.cleanupTempFiles(entry.stdoutPath, entry.stderrPath, entry.mcpConfigPath);
+
+            this.log('CHAT_CLI', `Resumed session ${id} (pid ${entry.pid}) finished`);
+            resolve({
+              exitCode: null, // Can't get exit code of previously-detached process
+              claudeSessionId: id,
+              sessionId: tailer.capturedSessionId,
+              stderr,
+              stdoutNonJsonLines: tailer.stdoutNonJsonLines.length > 0 ? tailer.stdoutNonJsonLines.join('\n') : null,
+            });
+          }
+        }, 500);
+      });
+
+      resumed.push({ entry, completion });
+    }
+
+    this.writeManifest(alive);
+    return resumed;
+  };
+
   /**
    * Kill an active CLI process by session ID.
-   * Returns true if a process was found and killed.
    */
   kill = (claudeSessionId: string): boolean => {
+    // Try in-process child first
     const child = this.activeProcesses.get(claudeSessionId);
-    if (!child) return false;
+    if (child) {
+      this.log('CHAT_CLI', `Killing process for session ${claudeSessionId}`);
+      child.kill('SIGTERM');
+      const forceKillTimer = setTimeout(() => {
+        if (!child.killed) {
+          this.log('CHAT_CLI', `Force killing process for session ${claudeSessionId}`);
+          child.kill('SIGKILL');
+        }
+      }, 5000);
+      child.on('close', () => clearTimeout(forceKillTimer));
+      return true;
+    }
 
-    this.log('CHAT_CLI', `Killing process for session ${claudeSessionId}`);
-    child.kill('SIGTERM');
+    // Fallback: kill by PID from manifest (resumed session)
+    const manifest = this.loadManifest();
+    const entry = manifest[claudeSessionId];
+    if (entry && this.isPidAlive(entry.pid)) {
+      this.log('CHAT_CLI', `Killing detached process for session ${claudeSessionId} (pid ${entry.pid})`);
+      try { process.kill(entry.pid, 'SIGTERM'); } catch { /* already dead */ }
+      setTimeout(() => {
+        try { process.kill(entry.pid, 'SIGKILL'); } catch { /* already dead */ }
+      }, 5000);
+      return true;
+    }
 
-    // Force kill after 5 seconds if still alive
-    const forceKillTimer = setTimeout(() => {
-      if (!child.killed) {
-        this.log('CHAT_CLI', `Force killing process for session ${claudeSessionId}`);
-        child.kill('SIGKILL');
-      }
-    }, 5000);
+    return false;
+  };
 
-    child.on('close', () => {
-      clearTimeout(forceKillTimer);
-    });
+  /**
+   * Release all processes for graceful server shutdown.
+   * Does NOT kill the CLI processes — they continue running.
+   * Stops tailers and unrefs children so the Node process can exit.
+   */
+  detachAll = (): void => {
+    for (const [sessionId, tailer] of this.activeTailers) {
+      clearInterval(tailer.interval);
+      try { closeSync(tailer.fd); } catch { /* ignore */ }
+      this.log('CHAT_CLI', `Stopped tailer for session ${sessionId} (server shutdown)`);
+    }
+    this.activeTailers.clear();
 
-    return true;
+    for (const [sessionId, child] of this.activeProcesses) {
+      child.removeAllListeners();
+      child.unref();
+      this.log('CHAT_CLI', `Detached process for session ${sessionId} (server shutdown)`);
+    }
+    this.activeProcesses.clear();
+    // Manifest is intentionally preserved for the next server instance
   };
 
   /**
-   * Kill all active CLI processes (for server shutdown).
+   * Kill all active CLI processes (explicit shutdown, not tsx watch restart).
    */
   killAll = (): void => {
     for (const [sessionId, child] of this.activeProcesses) {
-      this.log('CHAT_CLI', `Killing process for session ${sessionId} (shutdown)`);
+      this.log('CHAT_CLI', `Killing process for session ${sessionId}`);
       child.kill('SIGTERM');
     }
+    // Also kill any from manifest
+    const manifest = this.loadManifest();
+    for (const [sessionId, entry] of Object.entries(manifest)) {
+      if (this.isPidAlive(entry.pid)) {
+        this.log('CHAT_CLI', `Killing detached process for session ${sessionId} (pid ${entry.pid})`);
+        try { process.kill(entry.pid, 'SIGTERM'); } catch { /* ignore */ }
+      }
+    }
+    this.writeManifest({});
     this.activeProcesses.clear();
   };
 
-  /**
-   * Check if a process is currently active for a session.
-   */
   isActive = (claudeSessionId: string): boolean => {
-    return this.activeProcesses.has(claudeSessionId);
+    return this.activeProcesses.has(claudeSessionId) || this.activeTailers.has(claudeSessionId);
   };
 
-  /**
-   * Get the number of currently active processes.
-   */
   getActiveCount = (): number => {
-    return this.activeProcesses.size;
+    return this.activeTailers.size;
   };
 
-  /**
-   * Parse a single line of stream-json output and emit events.
-   * Also captures session_id from result events.
-   */
+  // ── File tailing ─────────────────────────────────────────────────
+
+  private startTailer(
+    claudeSessionId: string,
+    stdoutPath: string,
+    onEvent: (event: Record<string, unknown>) => void,
+  ): TailerState {
+    const fd = openSync(stdoutPath, 'r');
+    const state: TailerState = {
+      interval: setInterval(() => this.readChunk(state), 50),
+      fd,
+      position: 0,
+      lineBuf: '',
+      capturedSessionId: null,
+      stdoutNonJsonLines: [],
+      onEvent,
+    };
+    this.activeTailers.set(claudeSessionId, state);
+    return state;
+  }
+
+  /** Read all remaining data, close fd, stop interval. */
+  private finishTailer(claudeSessionId: string, state: TailerState): void {
+    clearInterval(state.interval);
+    // Final read to pick up any remaining data
+    this.readChunk(state);
+    // Process any incomplete line left in the buffer
+    if (state.lineBuf.trim()) {
+      this.processLine(state.lineBuf.trim(), state.onEvent, (sid) => {
+        state.capturedSessionId = sid;
+      }, (nonJson) => {
+        state.stdoutNonJsonLines.push(nonJson);
+      });
+      state.lineBuf = '';
+    }
+    try { closeSync(state.fd); } catch { /* ignore */ }
+    this.activeTailers.delete(claudeSessionId);
+  }
+
+  private readChunk(state: TailerState): void {
+    try {
+      const stats = fstatSync(state.fd);
+      if (stats.size <= state.position) return;
+
+      const toRead = Math.min(stats.size - state.position, 256 * 1024);
+      const buf = Buffer.alloc(toRead);
+      const bytesRead = readSync(state.fd, buf, 0, toRead, state.position);
+      if (bytesRead <= 0) return;
+
+      state.position += bytesRead;
+      state.lineBuf += buf.subarray(0, bytesRead).toString();
+
+      const lines = state.lineBuf.split('\n');
+      state.lineBuf = lines.pop()!;
+
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        this.processLine(trimmed, state.onEvent, (sid) => {
+          state.capturedSessionId = sid;
+        }, (nonJson) => {
+          state.stdoutNonJsonLines.push(nonJson);
+        });
+      }
+    } catch {
+      // File may have been deleted or fd closed
+    }
+  }
+
+  // ── Manifest I/O ─────────────────────────────────────────────────
+
+  private loadManifest(): Record<string, CliSessionManifestEntry> {
+    try {
+      if (existsSync(this.manifestPath)) {
+        return JSON.parse(readFileSync(this.manifestPath, 'utf-8'));
+      }
+    } catch { /* corrupt or missing */ }
+    return {};
+  }
+
+  private writeManifest(manifest: Record<string, CliSessionManifestEntry>): void {
+    try {
+      writeFileSync(this.manifestPath, JSON.stringify(manifest, null, 2));
+    } catch { /* never break the app */ }
+  }
+
+  private saveManifestEntry(entry: CliSessionManifestEntry): void {
+    const manifest = this.loadManifest();
+    manifest[entry.claudeSessionId] = entry;
+    this.writeManifest(manifest);
+  }
+
+  private removeManifestEntry(claudeSessionId: string): void {
+    const manifest = this.loadManifest();
+    delete manifest[claudeSessionId];
+    this.writeManifest(manifest);
+  }
+
+  // ── Helpers ──────────────────────────────────────────────────────
+
+  private isPidAlive(pid: number): boolean {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private readStderrFile(stderrPath: string): string | null {
+    try {
+      const content = readFileSync(stderrPath, 'utf-8').trim();
+      return content || null;
+    } catch {
+      return null;
+    }
+  }
+
+  private cleanupTempFiles(...paths: (string | undefined)[]): void {
+    for (const p of paths) {
+      if (p) { try { unlinkSync(p); } catch { /* ignore */ } }
+    }
+  }
+
   private processLine = (
     line: string,
     onEvent: (event: Record<string, unknown>) => void,
@@ -356,13 +577,10 @@ export class ChatCliBridge {
     try {
       const event = JSON.parse(line) as Record<string, unknown>;
       onEvent(event);
-
-      // Capture session_id from result event
       if (event.type === 'result' && typeof event.session_id === 'string') {
         onSessionId(event.session_id);
       }
     } catch {
-      // Not valid JSON — log and capture it as it may contain useful error info
       const truncated = line.slice(0, 500);
       this.log('CHAT_CLI', `[stdout non-json] ${truncated}`);
       onNonJsonLine?.(truncated);

package/templates/assistkick-product-system/packages/backend/src/services/chat_ws_handler.ts

@@ -275,6 +275,84 @@ export class ChatWsHandler {
     }
   }
 
+  /**
+   * Resume tracking CLI sessions left running by a previous server instance.
+   * Called once at server startup.
+   */
+  resumeSessions = (): void => {
+    const resumed = this.chatCliBridge.resumeSessions((claudeSessionId) => {
+      return (event: Record<string, unknown>) => {
+        // Forward to connected WS (if any)
+        const currentWs = this.sessionToWs.get(claudeSessionId);
+        if (currentWs) {
+          this.sendWsMessage(currentWs, { type: 'stream_event', event });
+        }
+        // Accumulate content in stream context
+        this.accumulateEvent(claudeSessionId, event);
+      };
+    });
+
+    for (const { entry, completion } of resumed) {
+      // Reconstruct stream context
+      this.streamContexts.set(entry.claudeSessionId, {
+        sessionId: entry.sessionId,
+        userMessage: entry.userMessage,
+        attachmentBlocks: entry.attachmentBlocks as Array<{ type: 'image' | 'file'; path: string; name: string; mimeType: string }>,
+        lastAssistantContent: '[]',
+        persisted: false,
+        persistedAssistantMessageId: null,
+        persistPromise: null,
+        lastContextUsageJson: null,
+        contextWindow: null,
+      });
+
+      // Check if messages were already persisted (WS disconnect during previous server)
+      if (entry.sessionId && this.chatMessageRepository) {
+        this.chatMessageRepository.getMessages(entry.sessionId)
+          .then((messages) => {
+            const ctx = this.streamContexts.get(entry.claudeSessionId);
+            if (!ctx || !messages) return;
+            // If messages exist, mark as already persisted
+            const assistantMsg = [...messages].reverse().find(m => m.role === 'assistant');
+            if (assistantMsg) {
+              ctx.persisted = true;
+              ctx.persistedAssistantMessageId = assistantMsg.id;
+            }
+          })
+          .catch(() => { /* ignore */ });
+      }
+
+      // Wire up completion handler
+      completion
+        .then((result) => {
+          const currentWs = this.sessionToWs.get(entry.claudeSessionId);
+          if (currentWs) {
+            this.removeActiveStream(currentWs, entry.claudeSessionId);
+          }
+          this.sessionToWs.delete(entry.claudeSessionId);
+
+          this.persistMessages(entry.claudeSessionId);
+
+          if (currentWs) {
+            this.sendWsMessage(currentWs, {
+              type: 'stream_end',
+              exitCode: result.exitCode,
+              claudeSessionId: entry.claudeSessionId,
+            });
+          }
+          this.log('CHAT_WS', `Resumed session ${entry.claudeSessionId} completed (exit ${result.exitCode})`);
+        })
+        .catch((err: Error) => {
+          this.persistMessages(entry.claudeSessionId);
+          this.log('CHAT_WS', `Resumed session ${entry.claudeSessionId} error: ${err.message}`);
+        });
+    }
+
+    if (resumed.length > 0) {
+      this.log('CHAT_WS', `Resumed ${resumed.length} CLI session(s) from previous server instance`);
+    }
+  };
+
   /** Remove a single Claude session from a WebSocket's active stream set. */
   private removeActiveStream = (ws: WebSocket, claudeSessionId: string): void => {
     const streams = this.activeStreams.get(ws);
@@ -462,78 +540,16 @@ export class ChatWsHandler {
           if (currentWs) {
             this.sendWsMessage(currentWs, { type: 'stream_event', event });
           }
-
-          // Accumulate assistant content and context usage for persistence
-          const ctx = this.streamContexts.get(claudeSessionId);
-          if (!ctx) return;
-
-          // Extract per-call context usage from assistant events only.
-          // The result event contains CUMULATIVE usage across all turns — not the context window size.
-          if (event.type === 'assistant') {
-            const message = event.message as Record<string, unknown> | undefined;
-            const usage = message?.usage as Record<string, unknown> | undefined;
-            if (usage) {
-              const input = typeof usage.input_tokens === 'number' ? usage.input_tokens : 0;
-              const output = typeof usage.output_tokens === 'number' ? usage.output_tokens : 0;
-              const cacheCreation = typeof usage.cache_creation_input_tokens === 'number' ? usage.cache_creation_input_tokens : 0;
-              const cacheRead = typeof usage.cache_read_input_tokens === 'number' ? usage.cache_read_input_tokens : 0;
-              ctx.lastContextUsageJson = JSON.stringify({
-                inputTokens: input,
-                outputTokens: output,
-                cacheCreationTokens: cacheCreation,
-                cacheReadTokens: cacheRead,
-                // totalTokens = input context only (output tokens don't count toward context window)
-                totalTokens: input + cacheCreation + cacheRead,
-                contextWindow: ctx.contextWindow,
-              });
-            }
-          }
-
-          // Extract contextWindow from result event's modelUsage
-          if (event.type === 'result') {
-            const modelUsage = event.modelUsage as Record<string, Record<string, unknown>> | undefined;
-            if (modelUsage) {
-              for (const info of Object.values(modelUsage)) {
-                if (typeof info.contextWindow === 'number') {
-                  ctx.contextWindow = info.contextWindow;
-                  // Re-emit the last context usage JSON with the contextWindow included
-                  if (ctx.lastContextUsageJson) {
-                    try {
-                      const parsed = JSON.parse(ctx.lastContextUsageJson);
-                      parsed.contextWindow = ctx.contextWindow;
-                      ctx.lastContextUsageJson = JSON.stringify(parsed);
-                    } catch { /* ignore */ }
-                  }
-                  break;
-                }
-              }
-            }
-          }
-
-          if (event.type === 'assistant') {
-            const newBlocks = extractEventContent(event);
-            if (newBlocks && newBlocks.length > 0) {
-              const existing = JSON.parse(ctx.lastAssistantContent) as Array<Record<string, unknown>>;
-              const merged = mergeAssistantContent(existing, newBlocks);
-              ctx.lastAssistantContent = JSON.stringify(merged);
-            }
-          } else {
-            // Capture tool_result blocks from human/tool_result events
-            const toolResults = extractToolResults(event);
-            if (toolResults.length > 0) {
-              const existing = JSON.parse(ctx.lastAssistantContent) as Array<Record<string, unknown>>;
-              const existingToolResultIds = new Set(
-                existing.filter(b => b.type === 'tool_result').map(b => b.tool_use_id as string),
-              );
-              const newResults = toolResults.filter(b => !existingToolResultIds.has(b.tool_use_id as string));
-              if (newResults.length > 0) {
-                ctx.lastAssistantContent = JSON.stringify([...existing, ...newResults]);
-              }
-            }
-          }
+          this.accumulateEvent(claudeSessionId, event);
         },
       });
 
+      // Update manifest with session metadata for cross-restart persistence
+      this.chatCliBridge.setManifestMetadata(claudeSessionId, {
+        sessionId: msg.sessionId || null,
+        attachmentBlocks: msg.attachmentBlocks || [],
+      });
+
       // Send composed system prompt to frontend and persist to session
       if (systemPrompt) {
         this.sendWsMessage(ws, { type: 'system_prompt', prompt: systemPrompt });
@@ -928,4 +944,72 @@ export class ChatWsHandler {
 
     this.log('CHAT_WS', `Client re-attached to in-flight stream for session ${claudeSessionId}`);
   };
+
+  /**
+   * Accumulate event data into the stream context for persistence.
+   * Shared by both direct spawns and resumed sessions.
+   */
+  private accumulateEvent = (claudeSessionId: string, event: Record<string, unknown>): void => {
+    const ctx = this.streamContexts.get(claudeSessionId);
+    if (!ctx) return;
+
+    if (event.type === 'assistant') {
+      const message = event.message as Record<string, unknown> | undefined;
+      const usage = message?.usage as Record<string, unknown> | undefined;
+      if (usage) {
+        const input = typeof usage.input_tokens === 'number' ? usage.input_tokens : 0;
+        const output = typeof usage.output_tokens === 'number' ? usage.output_tokens : 0;
+        const cacheCreation = typeof usage.cache_creation_input_tokens === 'number' ? usage.cache_creation_input_tokens : 0;
+        const cacheRead = typeof usage.cache_read_input_tokens === 'number' ? usage.cache_read_input_tokens : 0;
+        ctx.lastContextUsageJson = JSON.stringify({
+          inputTokens: input,
+          outputTokens: output,
+          cacheCreationTokens: cacheCreation,
+          cacheReadTokens: cacheRead,
+          totalTokens: input + cacheCreation + cacheRead,
+          contextWindow: ctx.contextWindow,
+        });
+      }
+    }
+
+    if (event.type === 'result') {
+      const modelUsage = event.modelUsage as Record<string, Record<string, unknown>> | undefined;
+      if (modelUsage) {
+        for (const info of Object.values(modelUsage)) {
+          if (typeof info.contextWindow === 'number') {
+            ctx.contextWindow = info.contextWindow;
+            if (ctx.lastContextUsageJson) {
+              try {
+                const parsed = JSON.parse(ctx.lastContextUsageJson);
+                parsed.contextWindow = ctx.contextWindow;
+                ctx.lastContextUsageJson = JSON.stringify(parsed);
+              } catch { /* ignore */ }
+            }
+            break;
+          }
+        }
+      }
+    }
+
+    if (event.type === 'assistant') {
+      const newBlocks = extractEventContent(event);
+      if (newBlocks && newBlocks.length > 0) {
+        const existing = JSON.parse(ctx.lastAssistantContent) as Array<Record<string, unknown>>;
+        const merged = mergeAssistantContent(existing, newBlocks);
+        ctx.lastAssistantContent = JSON.stringify(merged);
+      }
+    } else {
+      const toolResults = extractToolResults(event);
+      if (toolResults.length > 0) {
+        const existing = JSON.parse(ctx.lastAssistantContent) as Array<Record<string, unknown>>;
+        const existingToolResultIds = new Set(
+          existing.filter(b => b.type === 'tool_result').map(b => b.tool_use_id as string),
+        );
+        const newResults = toolResults.filter(b => !existingToolResultIds.has(b.tool_use_id as string));
+        if (newResults.length > 0) {
+          ctx.lastAssistantContent = JSON.stringify([...existing, ...newResults]);
+        }
+      }
+    }
+  };
 }

package/templates/assistkick-product-system/packages/backend/src/services/init.ts

@@ -110,6 +110,8 @@ export const paths = {
   skillsDir: SKILLS_DIR,
   toolsDir: TOOLS_DIR,
   dataDir: DATA_DIR,
+  /** Runtime data dir for logs, manifests, etc. — survives tsx watch restarts. */
+  runtimeDataDir: LOG_DIR,
   developerSkillPath: DEVELOPER_SKILL_PATH,
   reviewerSkillPath: REVIEWER_SKILL_PATH,
   debuggerSkillPath: DEBUGGER_SKILL_PATH,

package/templates/assistkick-product-system/packages/backend/src/services/project_workspace_service.ts

@@ -58,6 +58,9 @@ export class ProjectWorkspaceService {
   /** Verify that git is installed and available on the system. Throws if not. */
   verifyGitAvailable = async (): Promise<void> => {
     try {
+      // Ensure workspacesDir exists before spawning — if the cwd doesn't exist,
+      // spawn fails with ENOENT which would be misreported as "git not installed".
+      await this.ensureDir(this.workspacesDir);
       await this.claudeService.spawnCommand('git', ['--version'], this.workspacesDir);
     } catch {
       throw new Error('Git is required to create a project. Please install git and try again.');