chore: version packages

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Ark0N

CHANGELOG.md

@@ -1,5 +1,19 @@
 # codeman
 
+## 0.2.7
+
+### Patch Changes
+
+- Fix race condition in StateStore where dirty flag was overwritten after async write, silently discarding mutations
+- Fix PlanOrchestrator session leak by adding session.stop() in finally blocks and centralizing cleanup
+- Fix symlink path traversal in file-content and file-raw endpoints by adding realpathSync validation
+- Fix PTY exit handler to clean up sessionListenerRefs, transcriptWatchers, runSummaryTrackers, and terminal batching state
+- Fix sendInput() fire-and-forget by propagating runPrompt errors to task queue via taskError event
+- Fix Ralph Loop tick() race condition by running checkTimeouts/assignTasks sequentially with per-iteration error handling
+- Fix shell injection in hook scripts by piping HOOK_DATA via printf to curl stdin instead of inline embedding
+- Narrow tail-file allowlist to remove ~/.cache and ~/.local/share paths that exposed credentials
+- Fix stored XSS in quick-start dropdown by escaping case names with escapeHtml()
+
 ## 0.2.6
 
 ### Patch Changes

CLAUDE.md

@@ -17,7 +17,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **You may be running inside a Codeman-managed tmux session.** Before killing ANY tmux or Claude process:
 
-1. Check: `echo $CODEMAN_TMUX` - if `1`, you're in a managed session
+1. Check: `echo $CODEMAN_MUX` - if `1`, you're in a managed session
 2. **NEVER** run `tmux kill-session`, `pkill tmux`, or `pkill claude` without confirming
 3. Use the web UI or `./scripts/tmux-manager.sh` instead of direct kill commands
 
@@ -52,7 +52,7 @@ When user says "COM":
 4. **Sync CLAUDE.md version**: Update the `**Version**` line below to match the new version from `package.json`
 5. **Commit and deploy**: `git add -A && git commit -m "chore: version packages" && git push && npm run build && systemctl --user restart codeman-web`
 
-**Version**: 0.2.6 (must match `package.json`)
+**Version**: 0.2.7 (must match `package.json`)
 
 ## Project Overview
 
@@ -90,15 +90,18 @@ npx vitest run -t "pattern"        # Tests matching name
 npm run test:coverage              # With coverage report
 
 # Production
-npm run build
+npm run build                      # esbuild via scripts/build.mjs (not tsc)
+npm run start                      # node dist/index.js (production)
 systemctl --user restart codeman-web
 journalctl --user -u codeman-web -f
 ```
 
+**CI**: `.github/workflows/ci.yml` runs `typecheck`, `lint`, and `format:check` on push to master. Tests are intentionally excluded from CI (they spawn tmux).
+
 ## Common Gotchas
 
 - **Single-line prompts only** — `writeViaMux()` sends text and Enter separately; multi-line breaks Ink
-- **Don't kill tmux sessions blindly** — Check `$CODEMAN_TMUX` first; you might be inside one
+- **Don't kill tmux sessions blindly** — Check `$CODEMAN_MUX` first; you might be inside one
 - **Global regex `lastIndex` sharing** — `ANSI_ESCAPE_PATTERN_FULL/SIMPLE` have `g` flag; use `createAnsiPatternFull/Simple()` factory functions for fresh instances in loops
 - **DEC 2026 sync blocks** — Never discard incomplete sync blocks (START without END); buffer up to 50ms then flush. See `app.js:extractSyncSegments()`
 - **Terminal writes during buffer load** — Live SSE writes are queued while `_isLoadingBuffer` is true to prevent interleaving with historical data
@@ -116,6 +119,7 @@ journalctl --user -u codeman-web -f
 
 | File | Purpose |
 |------|---------|
+| `src/index.ts` | CLI entry point: global error recovery, uncaught exception guard, `MAX_CONSECUTIVE_ERRORS` auto-restart |
 | `src/session.ts` | PTY wrapper: `runPrompt()`, `startInteractive()`, `startShell()` |
 | `src/mux-interface.ts` | `TerminalMultiplexer` interface + `MuxSession` type |
 | `src/mux-factory.ts` | Create tmux multiplexer instance |
@@ -168,6 +172,24 @@ journalctl --user -u codeman-web -f
 | `buffer-limits.ts` | Terminal/text buffer size limits |
 | `map-limits.ts` | Global limits for Maps, sessions, watchers |
 
+### Utilities (`src/utils/`)
+
+Re-exported via `src/utils/index.ts`. Key exports:
+
+| File | Exports |
+|------|---------|
+| `cleanup-manager.ts` | `CleanupManager` — centralized disposal for timers, intervals, watchers, listeners, streams |
+| `lru-map.ts` | `LRUMap` — bounded cache with eviction |
+| `stale-expiration-map.ts` | `StaleExpirationMap` — TTL-based map with automatic cleanup |
+| `regex-patterns.ts` | `ANSI_ESCAPE_PATTERN_FULL/SIMPLE`, `createAnsiPatternFull/Simple()`, `stripAnsi`, `TOKEN_PATTERN`, `SPINNER_PATTERN` |
+| `buffer-accumulator.ts` | `BufferAccumulator` — batches rapid writes into single flushes |
+| `claude-cli-resolver.ts` | `findClaudeDir`, `getAugmentedPath` — resolves Claude CLI paths |
+| `opencode-cli-resolver.ts` | `resolveOpenCodeDir`, `isOpenCodeAvailable`, `getOpenCodeAugmentedPath` — OpenCode CLI support |
+| `string-similarity.ts` | `stringSimilarity`, `fuzzyPhraseMatch`, `todoContentHash` |
+| `token-validation.ts` | `validateTokenCounts`, `validateTokensAndCost` |
+| `nice-wrapper.ts` | `wrapWithNice` — wraps commands with `nice`/`ionice` for lower priority |
+| `type-safety.ts` | `assertNever` — exhaustive switch/case guard |
+
 ### Data Flow
 
 1. Session spawns `claude --dangerously-skip-permissions` via node-pty
@@ -426,8 +448,20 @@ Use `LRUMap` for bounded caches with eviction, `StaleExpirationMap` for TTL-base
 | **Error codes** | `createErrorResponse()` in `src/types.ts` |
 | **Test utilities** | `test/respawn-test-utils.ts` |
 | **Mobile test suite** | `mobile-test/README.md` |
-
-Additional design docs, plans, and investigation reports are in the `docs/` directory.
+| **OpenCode integration** | `docs/opencode-integration.md` |
+| **Local echo overlay** | `docs/local-echo-overlay-plan.md` |
+| **Performance investigation** | `docs/performance-investigation-report.md` |
+| **First-load optimization** | `docs/first-load-optimization-plan.md`, `docs/perf-audit-first-load.md` |
+| **Dead code audit** | `docs/cleanup-findings.md` |
+| **TypeScript improvements** | `docs/typescript-improvement-suggestions.md` |
+| **Browser testing** | `docs/browser-testing-guide.md` |
+| **Mobile testing report** | `docs/mobile-testing-report.md` |
+| **Voice input** | `docs/voice-input-plan.md` |
+| **Improvement roadmaps** | `docs/respawn-improvement-plan.md`, `docs/ralph-improvement-plan.md`, `docs/plan-improvement-roadmap.md` |
+| **Background keystroke forwarding** | `docs/background-keystroke-forwarding-merged-plan.md` |
+| **Run summary** | `docs/run-summary-plan.md` |
+
+Additional design docs and investigation reports are in the `docs/` directory.
 
 ## Scripts
 
@@ -437,6 +471,9 @@ Additional design docs, plans, and investigation reports are in the `docs/` dire
 | `scripts/monitor-respawn.sh` | Monitor respawn state machine in real-time |
 | `scripts/watch-subagents.ts` | Real-time subagent transcript watcher (list, follow by session/agent ID) |
 | `scripts/codeman-web.service` | systemd service file for production deployment |
+| `scripts/codeman-tunnel.service` | systemd service file for persistent Cloudflare tunnel |
+| `scripts/tunnel.sh` | Start/stop/check Cloudflare quick tunnel (`./scripts/tunnel.sh start\|stop\|url`) |
+| `scripts/build.mjs` | esbuild-based production build (called by `npm run build`) |
 | `scripts/postinstall.js` | npm postinstall hook for setup |
 
 Additional scripts in `scripts/` for screenshots, demos, Ralph wizards, and browser testing.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeman",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "The missing control plane for AI coding agents - run 20 autonomous agents with real-time monitoring and session persistence",
   "type": "module",
   "main": "dist/index.js",

src/file-stream-manager.ts

@@ -398,13 +398,7 @@ export class FileStreamManager extends EventEmitter {
 
     // Check if the resolved path is within the working directory
     // or common log directories (/tmp intentionally excluded — world-writable)
-    const allowedPaths = [
-      normalizedWorkingDir,
-      '/var/log',
-      resolve(homedir(), '.local/share'),
-      resolve(homedir(), '.cache'),
-      resolve(homedir(), 'logs'),
-    ];
+    const allowedPaths = [normalizedWorkingDir, '/var/log', resolve(homedir(), 'logs')];
 
     const isAllowed = allowedPaths.some((allowed) => {
       const rel = relative(allowed, absolutePath);

src/hooks-config.ts

@@ -27,9 +27,10 @@ export function generateHooksConfig(): { hooks: Record<string, unknown[]> } {
   // Falls back to empty object if stdin is unavailable or malformed.
   const curlCmd = (event: HookEventType) =>
     `HOOK_DATA=$(cat 2>/dev/null || echo '{}'); ` +
+    `printf '{"event":"${event}","sessionId":"%s","data":%s}' "$CODEMAN_SESSION_ID" "$HOOK_DATA" | ` +
     `curl -s -X POST "$CODEMAN_API_URL/api/hook-event" ` +
     `-H 'Content-Type: application/json' ` +
-    `-d "{\\"event\\":\\"${event}\\",\\"sessionId\\":\\"$CODEMAN_SESSION_ID\\",\\"data\\":$HOOK_DATA}" ` +
+    `--data @- ` +
     `2>/dev/null || true`;
 
   return {

src/plan-orchestrator.ts

@@ -444,8 +444,6 @@ export class PlanOrchestrator {
     try {
       const { result: response } = await session.runPrompt(prompt, { model: this.researchModel });
 
-      this.runningSessions.delete(session);
-
       const durationMs = Date.now() - startTime;
 
       // Extract JSON from response
@@ -528,7 +526,6 @@ export class PlanOrchestrator {
 
       return result;
     } catch (err) {
-      this.runningSessions.delete(session);
       const durationMs = Date.now() - startTime;
       const error = err instanceof Error ? err.message : String(err);
       onSubagent?.({
@@ -554,7 +551,10 @@ export class PlanOrchestrator {
         durationMs,
       };
     } finally {
-      // Always clear the progress interval to prevent memory leaks
+      // Always clean up session and progress interval — centralizing here
+      // prevents the race where cancel() and catch both try to manage the set
+      await session.stop().catch(() => {});
+      this.runningSessions.delete(session);
       clearInterval(progressInterval);
     }
   }
@@ -617,8 +617,6 @@ export class PlanOrchestrator {
     try {
       const { result: response } = await session.runPrompt(prompt, { model: this.plannerModel });
 
-      this.runningSessions.delete(session);
-
       const durationMs = Date.now() - startTime;
 
       // Extract JSON from response
@@ -670,7 +668,6 @@ export class PlanOrchestrator {
 
       return { success: true, items, gaps, warnings };
     } catch (err) {
-      this.runningSessions.delete(session);
       const durationMs = Date.now() - startTime;
       const error = err instanceof Error ? err.message : String(err);
       onSubagent?.({
@@ -684,7 +681,10 @@ export class PlanOrchestrator {
       });
       return { success: false, error };
     } finally {
-      // Always clear the progress interval to prevent memory leaks
+      // Always clean up session and progress interval — centralizing here
+      // prevents the race where cancel() and catch both try to manage the set
+      await session.stop().catch(() => {});
+      this.runningSessions.delete(session);
       clearInterval(progressInterval);
     }
   }

src/ralph-loop.ts

@@ -77,6 +77,7 @@ export class RalphLoop extends EventEmitter {
     completion: (sessionId: string, phrase: string) => void;
     error: (sessionId: string, error: string) => void;
     stopped: (sessionId: string) => void;
+    taskError: (sessionId: string, taskId: string, error: string) => void;
   } | null = null;
 
   constructor(options: RalphLoopOptions = {}) {
@@ -118,11 +119,15 @@ export class RalphLoop extends EventEmitter {
       stopped: (sessionId: string) => {
         this.handleSessionStopped(sessionId);
       },
+      taskError: (sessionId: string, taskId: string, error: string) => {
+        this.handleSessionTaskError(sessionId, taskId, error);
+      },
     };
 
     this.sessionManager.on('sessionCompletion', this.sessionEventHandlers.completion);
     this.sessionManager.on('sessionError', this.sessionEventHandlers.error);
     this.sessionManager.on('sessionStopped', this.sessionEventHandlers.stopped);
+    this.sessionManager.on('sessionTaskError', this.sessionEventHandlers.taskError);
   }
 
   /** Remove event listeners to prevent memory leaks */
@@ -131,6 +136,7 @@ export class RalphLoop extends EventEmitter {
       this.sessionManager.off('sessionCompletion', this.sessionEventHandlers.completion);
       this.sessionManager.off('sessionError', this.sessionEventHandlers.error);
       this.sessionManager.off('sessionStopped', this.sessionEventHandlers.stopped);
+      this.sessionManager.off('sessionTaskError', this.sessionEventHandlers.taskError);
       this.sessionEventHandlers = null;
     }
   }
@@ -281,8 +287,11 @@ export class RalphLoop extends EventEmitter {
   private async tick(): Promise<void> {
     this.store.setRalphLoopState({ lastCheckAt: Date.now() });
 
-    // Run independent checks in parallel for better performance
-    await Promise.all([this.checkTimeouts(), this.assignTasks()]);
+    // Run sequentially: timeouts first so timed-out tasks are cleaned up
+    // before assignTasks() picks new work (prevents race where both
+    // mutate the same task concurrently)
+    await this.checkTimeouts();
+    await this.assignTasks();
 
     // Check if we should auto-generate tasks (depends on assignment results)
     if (this.autoGenerateTasks && this.shouldGenerateTasks()) {
@@ -304,7 +313,11 @@ export class RalphLoop extends EventEmitter {
         break;
       }
 
-      await this.assignTaskToSession(task, session);
+      try {
+        await this.assignTaskToSession(task, session);
+      } catch (err) {
+        console.error(`[RalphLoop] Failed to assign task ${task.id} to session ${session.id}:`, err);
+      }
     }
   }
 
@@ -400,6 +413,17 @@ export class RalphLoop extends EventEmitter {
     }
   }
 
+  private handleSessionTaskError(_sessionId: string, taskId: string, error: string): void {
+    const task = this.taskQueue.getTask(taskId);
+    if (!task) {
+      return;
+    }
+
+    task.fail(error);
+    this.taskQueue.updateTask(task);
+    this.emit('taskFailed', task.id, error);
+  }
+
   private shouldGenerateTasks(): boolean {
     // Generate tasks if:
     // 1. No pending tasks

src/session-manager.ts

@@ -54,6 +54,7 @@ interface SessionHandlers {
   error: (data: string) => void;
   completion: (phrase: string) => void;
   exit: () => void;
+  taskError: (taskId: string, error: string) => void;
 }
 
 export class SessionManager extends EventEmitter {
@@ -134,12 +135,16 @@ export class SessionManager extends EventEmitter {
           this.emit('sessionStopped', session.id);
           this.updateSessionState(session);
         },
+        taskError: (taskId: string, error: string) => {
+          this.emit('sessionTaskError', session.id, taskId, error);
+        },
       };
 
       session.on('output', handlers.output);
       session.on('error', handlers.error);
       session.on('completion', handlers.completion);
       session.on('exit', handlers.exit);
+      session.on('taskError', handlers.taskError);
 
       // Store handlers for later cleanup
       this.sessionHandlers.set(session.id, handlers);
@@ -183,6 +188,7 @@ export class SessionManager extends EventEmitter {
       session.off('error', handlers.error);
       session.off('completion', handlers.completion);
       session.off('exit', handlers.exit);
+      session.off('taskError', handlers.taskError);
       this.sessionHandlers.delete(id);
     }
 

src/session.ts

@@ -2203,6 +2203,16 @@ export class Session extends EventEmitter {
     this._lastActivityAt = Date.now();
     this.runPrompt(input).catch((err) => {
       const errorMsg = err instanceof Error ? err.message : String(err);
+      // Clean up task state so the task queue doesn't get stuck
+      if (this._currentTaskId) {
+        const taskId = this._currentTaskId;
+        this._currentTaskId = null;
+        this._status = 'idle';
+        this._lastActivityAt = Date.now();
+        this.emit('taskError', taskId, errorMsg);
+      } else {
+        this._status = 'idle';
+      }
       this.emit('error', errorMsg);
     });
   }

src/state-store.ts

@@ -210,6 +210,10 @@ export class StateStore {
       return;
     }
 
+    // Clear dirty flag BEFORE async I/O so mutations during write re-set it.
+    // The state snapshot is already captured in `json` above.
+    this.dirty = false;
+
     // Step 2: Create backup via file copy (async, no read+parse+write)
     try {
       await access(this.filePath);
@@ -223,15 +227,15 @@ export class StateStore {
       await writeFile(tempPath, json, 'utf-8');
       await rename(tempPath, this.filePath);
 
-      // Success! Clear dirty flag AFTER write completes
-      this.dirty = false;
       this.consecutiveSaveFailures = 0;
       if (this.circuitBreakerOpen) {
         console.log('[StateStore] Circuit breaker CLOSED - save succeeded');
         this.circuitBreakerOpen = false;
       }
     } catch (err) {
       console.error('[StateStore] Failed to write state file:', err);
+      // Re-mark dirty so the data is retried on the next save cycle
+      this.dirty = true;
       this.consecutiveSaveFailures++;
 
       // Try to clean up temp file on error