@aion0/forge 0.5.40 → 0.5.43

package/.forge/mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "forge": {
       "type": "sse",
-      "url": "http://localhost:8406/sse?workspaceId=656c9e65-9d73-4cb6-a065-60d966e1fc78"
+      "url": "http://localhost:8406/sse?workspaceId=6fc40ffc-3dfc-4e2d-bf93-c934d1996af2"
     }
   }
 }

package/CLAUDE.md

@@ -1,53 +1,95 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 ## Project: Forge (@aion0/forge)
 
-### Scripts
+Self-hosted Vibe Coding platform — Next.js web UI + tmux-backed browser terminal + multi-agent workspace + Telegram bot + Cloudflare tunnel, wrapping Claude Code and other CLIs.
+
+Package manager is **pnpm** (pinned in `packageManager`). `better-sqlite3` and `node-pty` are native — `pnpm rebuild` after a Node upgrade.
+
+## Scripts
+
 ```bash
 # ── Start ──
-./start.sh              # production (kill old processes → build → start)
-./start.sh dev           # development (hot-reload)
-forge server start              # production via npm link/install
-forge server start --dev        # dev mode
-forge server start              # background by default, logs to ~/.forge/forge.log
-forge server start --foreground # foreground mode
-forge server stop               # stop default instance (port 8403)
-forge server stop --port 4000 --dir ~/.forge-staging  # stop specific instance
-forge server restart            # stop + start (safe for remote)
-forge server rebuild            # force rebuild
-forge server start --port 4000 --terminal-port 4001 --dir ~/.forge-staging
+./start.sh                       # production (kill old processes → build → start)
+./start.sh dev                   # development (hot-reload, FORGE_DEV=1 bypasses auth)
+forge server start               # production via npm link/install, background + logs to <data>/forge.log
+forge server start --foreground  # run in foreground
+forge server start --dev         # dev mode
+forge server stop                # stop default instance (port 8403)
+forge server stop --port 4000 --dir ~/.forge-staging   # stop specific instance
+forge server restart             # stop + start (safe for remote)
+forge server rebuild             # force rebuild .next
+forge server start --port 4000 --terminal-port 4001 --workspace-port 4002 --dir ~/.forge-staging
 forge server start --reset-terminal  # kill terminal server (loses tmux attach)
-forge --version                 # show version
-
-# ── Test ──
-./dev-test.sh            # test instance (port 4000, data ~/.forge-test)
+forge --reset-password           # reset admin password
+forge --version
 
-# ── Install ──
-./install.sh             # install from npm
-./install.sh --local     # install from local source (npm link + build)
+# ── Test instance ──
+./dev-test.sh                    # port 4000, data ~/.forge-test, hot-reload
 
-# ── Publish ──
-./publish.sh             # bump patch version, commit, tag
-./publish.sh minor       # bump minor
-./publish.sh 1.0.0       # explicit version
+# ── Install / Publish ──
+./install.sh                     # from npm
+./install.sh --local             # npm link + pnpm build from source
+./publish.sh [patch|minor|major|x.y.z]   # bump, generate RELEASE_NOTES.md, commit, tag, push, gh release
 npm login && npm publish --access public --otp=<code>
 
 # ── Monitor ──
-./check-forge-status.sh  # show process status + tmux sessions
-
-# ── CLI ──
-forge                    # help
-forge --version          # show version
-forge tcode              # show tunnel URL + session code
-forge tasks              # list tasks
-forge task <project> "prompt"  # submit task
-forge watch <id>         # live stream task output
+./check-forge-status.sh          # show process status + tmux sessions
+
+# ── Tests (no framework — custom tsx scripts) ──
+npx tsx lib/workspace/__tests__/workspace.test.ts
+npx tsx lib/workspace/__tests__/state-machine.test.ts
+npx tsx scripts/verify-usage.ts
+
+# ── CLI (talks to running server over HTTP) ──
+forge                            # help
+forge task <project> "prompt"    # submit a background task (--new for fresh session)
+forge tasks                      # list
+forge watch <id>                 # live stream task output
+forge tcode                      # tunnel URL + session code
 ```
 
-### Key Paths
-- Data: `~/.forge/` (settings, db, password, terminal-state, flows, bin)
-- npm package: `@aion0/forge`
-- GitHub: `github.com/aiwatching/forge`
+The CLI (`cli/mw.ts`) reaches the server at `http://localhost:${MW_URL port or 3000}`. Set `MW_URL` if the server is not on the default port.
+
+## Architecture
+
+### Process model
+Forge runs as **four cooperating processes**, normally launched by `bin/forge-server.mjs`:
+
+| Process | Port (default) | Responsibility |
+|---|---|---|
+| `next-server` (web UI + API) | 8403 | Next.js app — UI, REST/SSE APIs, auth |
+| `lib/terminal-standalone.ts` | 8404 | WebSocket ↔ tmux pty bridge for browser terminals |
+| `lib/workspace-standalone.ts` | 8405 (+ MCP 8406) | Workspace daemon + MCP server — **exclusive writer of workspace `state.json`** |
+| `lib/telegram-standalone.ts` | — | Telegram bot polling loop |
+
+Each forked service is spawned with a `--forge-port=<webPort>` instance tag. `forge-server.mjs`'s `cleanupOrphans()` uses this tag to kill *this* instance's stale processes and legacy untagged orphans while leaving other instances alone. When adding a new standalone, keep the tag forwarded.
+
+### Dev mode vs production mode
+- `FORGE_EXTERNAL_SERVICES=1` tells Next.js (`lib/init.ts`) **not** to spawn terminal/telegram/workspace — `forge-server.mjs` manages them. This is set automatically by `forge-server.mjs` in prod/background/dev.
+- Plain `pnpm dev` (or `./dev-test.sh`) sets it to `0` — `lib/init.ts` becomes the process supervisor and spawns the standalones itself. Use this when iterating on Next.js only.
+- `FORGE_DEV=1` (set by `./start.sh dev`) **bypasses login in `middleware.ts`** — never set in production.
+
+### Data layout (`lib/dirs.ts`)
+- `getConfigDir()` → `~/.forge/` — shared across instances, holds `bin/` (cloudflared).
+- `getDataDir()` → `FORGE_DATA_DIR` env var, or `--dir` flag, or `~/.forge/data/` — **per-instance** settings, sqlite (`workflow.db`), encrypted key, flows, logs, workspaces.
+- A one-time migration on startup moves the legacy flat `~/.forge/*` layout into `~/.forge/data/*` (also handled in `forge-server.mjs`). If touching paths, check both places.
+
+### `lib/init.ts` side effects
+First API request per Next.js worker triggers `ensureInitialized()` (guarded by a global Symbol). It migrates secrets, auto-detects CLI agents (`which claude`), installs Forge's skills into `~/.claude/skills/`, syncs `lib/help-docs/` to `<dataDir>/help/`, and starts the task runner / session watcher / pipeline scheduler. Anything you add here runs on every cold worker — keep it idempotent.
+
+### Workspace orchestration (`lib/workspace/`)
+- `orchestrator.ts` (3400 lines) is the core DAG engine; `manager.ts` is a singleton cache of orchestrators keyed by workspace ID (HMR-safe via `globalThis.__forgeOrchestrators`).
+- `persistence.ts` exports `loadWorkspace` / `listWorkspaces` etc. but **intentionally does not export `saveWorkspace`** — all mutations must go through the workspace daemon's HTTP API to avoid multi-writer races. Respect this when adding new mutators.
+- `agent-bus.ts` = inter-agent messages (notifications + tickets); `agent-worker.ts` = per-agent loop; `backends/{api,cli}-backend.ts` = API vs CLI execution; `watch-manager.ts` = autonomous file/git/command monitoring.
+
+### Settings & secrets
+`lib/settings.ts` reads/writes `<dataDir>/settings.yaml`. Fields listed in `SECRET_FIELDS` (`lib/crypto.ts`) are auto-encrypted with AES-256-GCM using `<dataDir>/.encrypt-key`. `lib/init.ts#migrateSecrets` re-encrypts any plaintext secret on startup.
+
+## Help Docs Rule
 
-### Help Docs Rule
 When adding or changing a feature, check if `lib/help-docs/` needs updating. Each file covers one module:
 - `00-overview.md` — install, start, data paths
 - `01-settings.md` — all settings fields
@@ -62,12 +104,18 @@ When adding or changing a feature, check if `lib/help-docs/` needs updating. Eac
 - `10-troubleshooting.md` — common issues
 - `11-workspace.md` — multi-agent workspace (smiths, daemon, request docs)
 - `12-usage.md` — token usage analytics and cost tracking
-If a feature change affects user-facing behavior, update the corresponding help doc in the same commit.
 
-### Architecture
-- `forge-server.mjs` starts: Next.js + terminal-standalone + telegram-standalone
-- `pnpm dev` / `start.sh dev` starts: Next.js (init.ts spawns terminal + telegram)
-- `FORGE_EXTERNAL_SERVICES=1` → init.ts skips spawning (forge-server manages them)
+If a feature change affects user-facing behavior, update the corresponding help doc in the same commit. These docs are also served to the in-app Help AI — `lib/help-docs/CLAUDE.md` is its system prompt.
+
+## Commit conventions
+
+`publish.sh` groups release notes by prefix: `feat:`, `fix:`, `perf:`, `refactor:`, `docs:`. Anything else lands in "Other". Use these prefixes for anything you want surfaced in release notes.
+
+## Key paths
+
+- Data: `~/.forge/data/` (override with `FORGE_DATA_DIR` or `--dir`)
+- npm package: `@aion0/forge`
+- GitHub: `github.com/aiwatching/forge`
 
 ## Obsidian Vault
 Location: /Users/zliu/MyDocuments/obsidian-project/Projects/Bastion

package/RELEASE_NOTES.md

@@ -1,12 +1,11 @@
-# Forge v0.5.40
+# Forge v0.5.43
 
-Released: 2026-04-14
+Released: 2026-04-25
 
-## Changes since v0.5.38
+## Changes since v0.5.42
 
-### Other
-- v0.5.39
-- add option to disable claude modification
+### Features
+- feat: smith pause/resume + agent_status watch event-driven + primary session picker
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.38...v0.5.40
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.5.42...v0.5.43

package/app/api/git/route.ts

@@ -1,6 +1,6 @@
 import { NextResponse, type NextRequest } from 'next/server';
-import { execSync, exec } from 'node:child_process';
-import { existsSync, readdirSync } from 'node:fs';
+import { execSync, execFileSync, exec } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
 import { promisify } from 'node:util';
@@ -78,23 +78,41 @@ export async function POST(req: NextRequest) {
 
   if (action === 'clone') {
     // Clone a repo into a project root
-    if (!repoUrl) return NextResponse.json({ error: 'repoUrl required' }, { status: 400 });
+    if (!repoUrl || typeof repoUrl !== 'string') {
+      return NextResponse.json({ error: 'repoUrl required' }, { status: 400 });
+    }
     const settings = loadSettings();
     const roots = (settings.projectRoots || []).map(r => r.replace(/^~/, homedir()));
-    const cloneTarget = targetDir || roots[0];
-    if (!cloneTarget) return NextResponse.json({ error: 'No project root configured' }, { status: 400 });
+    const expandedTarget = typeof targetDir === 'string' ? targetDir.replace(/^~/, homedir()) : undefined;
+    // If caller specified targetDir, it must be under a configured project root
+    if (expandedTarget && !roots.some(r => expandedTarget === r || expandedTarget.startsWith(r + '/'))) {
+      return NextResponse.json({ error: 'targetDir must be under a configured project root' }, { status: 400 });
+    }
+    const cloneTarget = expandedTarget || roots[0];
+    if (!cloneTarget) return NextResponse.json({ error: 'No project root configured — add one in Settings' }, { status: 400 });
 
     try {
-      const output = execSync(`git clone "${repoUrl}"`, {
+      if (!existsSync(cloneTarget)) mkdirSync(cloneTarget, { recursive: true });
+      // execFileSync avoids shell interpolation; GIT_TERMINAL_PROMPT=0 makes git fail fast
+      // instead of hanging for credentials when there is no TTY.
+      const output = execFileSync('git', ['clone', '--', repoUrl], {
         cwd: cloneTarget,
         encoding: 'utf-8',
-        timeout: 60000,
+        timeout: 120000,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
       });
-      // Extract cloned dir name from URL
       const repoName = repoUrl.split('/').pop()?.replace(/\.git$/, '') || 'repo';
       return NextResponse.json({ ok: true, path: join(cloneTarget, repoName), output });
     } catch (e: any) {
-      return NextResponse.json({ error: e.message }, { status: 500 });
+      // Surface git's real message (stderr) so the UI can show "Repository not found",
+      // "Authentication failed", etc. — not a bare "Command failed".
+      const stderr = (e.stderr ? e.stderr.toString() : '').trim();
+      const msg = stderr || e.message || 'git clone failed';
+      console.error('[git] clone failed:', msg);
+      // User-caused failures (bad URL, auth, already exists) → 400; infra failures → 500
+      const isUserError = /not found|authentication|could not read username|already exists|invalid|permission denied/i.test(msg);
+      return NextResponse.json({ error: msg }, { status: isUserError ? 400 : 500 });
     }
   }
 

package/bin/forge-server.mjs

@@ -108,6 +108,45 @@ if (!getArg('--dir')) {
 
 mkdirSync(DATA_DIR, { recursive: true });
 
+// ── tmux check (required for browser terminals) ──
+if (!isStop) {
+  try {
+    execSync('command -v tmux', { stdio: ['ignore', 'pipe', 'pipe'] });
+  } catch {
+    console.error('[forge] tmux is required but was not found on PATH.');
+    console.error('[forge] Install it with one of:');
+    if (process.platform === 'darwin') {
+      console.error('    brew install tmux');
+    } else if (process.platform === 'linux') {
+      console.error('    sudo apt install -y tmux          # Debian/Ubuntu');
+      console.error('    sudo dnf install -y tmux          # Fedora/RHEL');
+      console.error('    sudo pacman -S tmux               # Arch');
+    } else {
+      console.error('    See https://github.com/tmux/tmux/wiki/Installing');
+    }
+    console.error('[forge] Then re-run: forge server start');
+    process.exit(1);
+  }
+}
+
+// ── Agent CLI check (warn-only — API-only profiles still work) ──
+if (!isStop) {
+  const has = (bin) => {
+    try { execSync(`command -v ${bin}`, { stdio: ['ignore', 'pipe', 'pipe'] }); return true; }
+    catch { return false; }
+  };
+  const hasClaude = has('claude');
+  const hasCodex = has('codex');
+  const hasAider = has('aider');
+  if (!hasClaude && !hasCodex && !hasAider) {
+    console.warn('[forge] ⚠️  No agent CLI found (claude / codex / aider).');
+    console.warn('[forge] Forge needs at least one to drive terminals, tasks, and workspace agents.');
+    console.warn('[forge] Install Claude Code:  npm install -g @anthropic-ai/claude-code');
+    console.warn('[forge] Install Codex:        https://github.com/openai/codex#installation');
+    console.warn('[forge] Or configure API-only profiles in Settings after login.');
+  }
+}
+
 // ── Load <data-dir>/.env.local ──
 const envFile = join(DATA_DIR, '.env.local');
 if (existsSync(envFile)) {

package/components/Dashboard.tsx

@@ -148,6 +148,11 @@ export default function Dashboard({ user }: { user: any }) {
   }, []);
   useEffect(() => { refreshDisplayName(); }, [refreshDisplayName]);
 
+  // Reflect the current user's name in the browser tab title
+  useEffect(() => {
+    document.title = displayName && displayName !== 'Forge' ? `Forge — ${displayName}` : 'Forge';
+  }, [displayName]);
+
   // Listen for open-terminal events from ProjectManager
   useEffect(() => {
     const handler = (e: Event) => {
@@ -278,7 +283,9 @@ export default function Dashboard({ user }: { user: any }) {
       <header className="h-12 border-b-2 border-[var(--border)] flex items-center justify-between px-4 shrink-0 bg-[var(--bg-secondary)]">
         <div className="flex items-center gap-4">
           <img src="/icon.png" alt="Forge" width={28} height={28} className="rounded" />
-          <span className="text-sm font-bold text-[var(--accent)]">Forge</span>
+          <span className="text-sm font-bold text-[var(--accent)]">
+            Forge{displayName && displayName !== 'Forge' ? ` · ${displayName}` : ''}
+          </span>
           {versionInfo && (
             <span className="flex items-center gap-1.5">
               <span className="text-[10px] text-[var(--text-secondary)]">v{versionInfo.current}</span>

package/components/WorkspaceView.tsx

@@ -34,6 +34,7 @@ interface AgentConfig {
 interface AgentState {
   smithStatus: 'down' | 'starting' | 'active';
   taskStatus: 'idle' | 'running' | 'done' | 'failed';
+  paused?: boolean;
   currentStep?: number;
   tmuxSession?: string;
   artifacts: { type: string; path?: string; summary?: string }[];
@@ -2794,6 +2795,7 @@ interface AgentNodeData {
   workspaceId: string | null;
   onRun: () => void;
   onPause: () => void;
+  onResume: () => void;
   onStop: () => void;
   onRetry: () => void;
   onEdit: () => void;
@@ -3307,7 +3309,7 @@ function WorkerMascot({ taskStatus, smithStatus, seed, accentColor, theme }: { t
 }
 
 function AgentFlowNode({ data }: NodeProps<Node<AgentNodeData>>) {
-  const { config, state, colorIdx, previewLines, projectPath, workspaceId, onRun, onPause, onStop, onRetry, onEdit, onRemove, onMessage, onApprove, onShowLog, onShowMemory, onShowInbox, onOpenTerminal, onSwitchSession, onSaveAsTemplate, mascotTheme, bellOn = false, onToggleBell, inboxPending = 0, inboxFailed = 0 } = data;
+  const { config, state, colorIdx, previewLines, projectPath, workspaceId, onRun, onPause, onResume, onStop, onRetry, onEdit, onRemove, onMessage, onApprove, onShowLog, onShowMemory, onShowInbox, onOpenTerminal, onSwitchSession, onSaveAsTemplate, mascotTheme, bellOn = false, onToggleBell, inboxPending = 0, inboxFailed = 0 } = data;
   const c = COLORS[colorIdx % COLORS.length];
   const smithStatus = state?.smithStatus || 'down';
   const taskStatus = state?.taskStatus || 'idle';
@@ -3426,10 +3428,20 @@ function AgentFlowNode({ data }: NodeProps<Node<AgentNodeData>>) {
           </>
         )}
         {/* Message button — send instructions to agent */}
-        {smithStatus === 'active' && taskStatus !== 'running' && (
+        {smithStatus === 'active' && taskStatus !== 'running' && !state?.paused && (
           <button onPointerDown={e => e.stopPropagation()} onClick={e => { e.stopPropagation(); onMessage(); }}
             className="text-[9px] px-1.5 py-0.5 rounded bg-blue-600/20 text-blue-400 hover:bg-blue-600/30">💬 Message</button>
         )}
+        {/* Pause / Resume — icon-only so it doesn't widen the card */}
+        {smithStatus !== 'down' && config.type !== 'input' && (
+          <button onPointerDown={e => e.stopPropagation()}
+            onClick={e => { e.stopPropagation(); state?.paused ? onResume() : onPause(); }}
+            className={`text-[9px] px-1 ${state?.paused ? 'text-orange-400 hover:text-orange-300' : 'text-gray-600 hover:text-orange-400'}`}
+            title={state?.paused
+              ? 'Paused — click to resume bus pickups and watch alerts'
+              : 'Pause — drop new bus messages and watch alerts as failed (in-flight task continues)'}
+          >{state?.paused ? '▶' : '⏸'}</button>
+        )}
         <div className="flex-1" />
         <span className="flex items-center">
             <button onPointerDown={e => e.stopPropagation()}
@@ -3733,6 +3745,7 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
               wsApi(workspaceId!, 'run', { agentId: agent.id });
             },
             onPause: () => wsApi(workspaceId!, 'pause', { agentId: agent.id }),
+            onResume: () => wsApi(workspaceId!, 'resume', { agentId: agent.id }),
             onStop: () => wsApi(workspaceId!, 'stop', { agentId: agent.id }),
             mascotTheme,
             bellOn: bellAgents.has(agent.id),

package/install.sh

@@ -7,6 +7,46 @@
 
 set -e
 
+# tmux is required for browser terminals — warn early if missing
+if ! command -v tmux >/dev/null 2>&1; then
+  echo "[forge] ⚠️  tmux not found — Forge terminals won't work without it."
+  case "$(uname -s)" in
+    Darwin)
+      echo "[forge] Install: brew install tmux"
+      if command -v brew >/dev/null 2>&1; then
+        read -r -p "[forge] Run 'brew install tmux' now? [y/N] " reply
+        case "$reply" in [yY]*) brew install tmux ;; esac
+      fi
+      ;;
+    Linux)
+      if command -v apt-get >/dev/null 2>&1; then
+        echo "[forge] Install: sudo apt install -y tmux"
+      elif command -v dnf >/dev/null 2>&1; then
+        echo "[forge] Install: sudo dnf install -y tmux"
+      elif command -v pacman >/dev/null 2>&1; then
+        echo "[forge] Install: sudo pacman -S tmux"
+      else
+        echo "[forge] Install tmux via your distro's package manager."
+      fi
+      ;;
+    *)
+      echo "[forge] See https://github.com/tmux/tmux/wiki/Installing"
+      ;;
+  esac
+  echo ""
+fi
+
+# Agent CLI check — at least one of claude / codex / aider is needed
+if ! command -v claude >/dev/null 2>&1 \
+   && ! command -v codex >/dev/null 2>&1 \
+   && ! command -v aider >/dev/null 2>&1; then
+  echo "[forge] ⚠️  No agent CLI found (claude / codex / aider)."
+  echo "[forge] Install Claude Code:  npm install -g @anthropic-ai/claude-code"
+  echo "[forge] Install Codex:        https://github.com/openai/codex#installation"
+  echo "[forge] Or configure API-only profiles in Settings after login."
+  echo ""
+fi
+
 if [ "$1" = "local" ] || [ "$1" = "--local" ]; then
   echo "[forge] Installing from local source..."
   npm uninstall -g @aion0/forge 2>/dev/null || true

package/lib/help-docs/11-workspace.md

@@ -414,7 +414,7 @@ Each smith can display an animated companion character next to its node.
 | **Stop Daemon** | Stop all smiths, kill workers. Preserves user's terminal conversation context (no `/clear` is sent). Tmux sessions attached to by a user are kept alive. |
 | **Run All** | Trigger all runnable agents once |
 | **Run** | Trigger specific agent |
-| **Pause/Resume** | Pause/resume message consumption for one agent |
+| **Pause/Resume** | Pause stops new bus pickups, drops queued + incoming messages to `failed`, and suppresses watch-alert dispatch. In-flight task continues. Resume re-enables. The pause flag is transient — daemon stop/start or process restart clears it. UI: ⏸ / ▶ icon on the smith card. |
 | **Mark Done/Failed/Idle** | Manually set task status |
 | **Retry** | Re-run a failed agent from checkpoint |
 | **Open Terminal** | Enter manual mode with tmux session |
@@ -592,6 +592,7 @@ Use this exact JSON structure when calling `POST /api/workspace/<id>/agents` wit
 
 - `action` values: `log` | `analyze` | `approve` | `send_message`
 - `sendTo` is required only when `action: "send_message"`
+- `agent_status` target is event-driven — orchestrator stamps a transition timestamp on every real `taskStatus` change (idempotent re-emits are deduped). The watch tick compares timestamps and only fires when the target has settled to a non-busy state (not `running`/`starting`) and matches `pattern`. Does not depend on polling, so sub-tick task transitions are caught reliably. Pattern matches the **final** state only — intermediate states during the interval window don't affect matching.
 
 ## Complete Recipes
 

package/lib/workspace/orchestrator.ts

@@ -39,7 +39,7 @@ import {
   loadMemory, saveMemory, createMemory, formatMemoryForPrompt,
   addObservation, addSessionSummary, parseStepToObservations, buildSessionSummary,
 } from './smith-memory';
-import { getFixedSession } from '../project-sessions';
+import { getFixedSession, setFixedSession } from '../project-sessions';
 
 // ─── Workspace Topology Cache ────────────────────────────
 
@@ -116,12 +116,29 @@ export class WorkspaceOrchestrator extends EventEmitter {
       if (event.type === 'log' && event.agentId && event.entry) {
         appendAgentLog(this.workspaceId, event.agentId, event.entry).catch(() => {});
       }
+      // Stamp taskStatus transitions. Idempotent re-emits of the same value
+      // don't bump the timestamp — agent_status watches rely on this to detect
+      // real transitions without polling.
+      if (event.type === 'task_status' && event.agentId && event.taskStatus) {
+        const entry = this.agents.get(event.agentId);
+        if (entry && entry.state.lastTaskStatus !== event.taskStatus) {
+          const prev = entry.state.lastTaskStatus;
+          entry.state.lastTaskStatus = event.taskStatus;
+          entry.state.taskStatusChangedAt = Date.now();
+          console.log(`[task_status] ${entry.config.label}: ${prev || '(none)'} → ${event.taskStatus} @ ${entry.state.taskStatusChangedAt}`);
+        }
+      }
     });
     // Handle watch events
     this.watchManager.on('watch_alert', (event) => {
+      const alertEntry = this.agents.get(event.agentId);
+      // Paused source smith — observation continues but no dispatch.
+      if (alertEntry?.state.paused) {
+        console.log(`[watch] ${alertEntry.config.label}: paused — alert dropped`);
+        return;
+      }
       this.emit('event', event);
       // Push alert to agent history so Log panel shows it
-      const alertEntry = this.agents.get(event.agentId);
       if (alertEntry && event.entry) {
         alertEntry.state.history.push(event.entry);
         this.emit('event', { type: 'log', agentId: event.agentId, entry: event.entry } as any);
@@ -266,6 +283,21 @@ export class WorkspaceOrchestrator extends EventEmitter {
     return null;
   }
 
+  /** Resolve the primary smith's fixed session for this project. If none is bound
+   *  yet, auto-bind to the latest existing claude session so the terminal picker
+   *  can offer "Current Session" instead of forcing the user into a fresh shell. */
+  resolvePrimaryFixedSession(): string | null {
+    const existing = getFixedSession(this.projectPath);
+    if (existing) return existing;
+    const primary = this.getPrimaryAgent();
+    if (!primary) return null;
+    const latest = this.getLatestSessionId(primary.config.workDir);
+    if (!latest) return null;
+    setFixedSession(this.projectPath, latest);
+    console.log(`[workspace] primary auto-bound to existing session ${latest} for ${this.projectPath}`);
+    return latest;
+  }
+
   addAgent(config: WorkspaceAgentConfig): void {
     const conflict = this.validateOutputs(config);
     if (conflict) throw new Error(conflict);
@@ -440,7 +472,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
       const workerState = entry.worker?.getState();
       // Merge: worker state for task/smith, entry.state for mode (orchestrator controls mode)
       result[id] = workerState
-        ? { ...workerState, taskStatus: entry.state.taskStatus, tmuxSession: entry.state.tmuxSession, currentMessageId: entry.state.currentMessageId }
+        ? { ...workerState, taskStatus: entry.state.taskStatus, tmuxSession: entry.state.tmuxSession, currentMessageId: entry.state.currentMessageId, paused: entry.state.paused }
         : entry.state;
     }
     return result;
@@ -930,6 +962,9 @@ export class WorkspaceOrchestrator extends EventEmitter {
     // Clean up stale state from previous run
     this.bus.markAllRunningAsFailed();
 
+    // Paused is transient — clear on every daemon start so any leftover flag goes away.
+    for (const entry of this.agents.values()) entry.state.paused = false;
+
     // Install forge skills globally (once per daemon start)
     try {
       installForgeSkills(this.projectPath, this.workspaceId, '', Number(process.env.PORT) || 8403);
@@ -1167,6 +1202,9 @@ export class WorkspaceOrchestrator extends EventEmitter {
     for (const [id, entry] of this.agents) {
       if (entry.config.type === 'input') continue;
 
+      // 0. Clear transient paused flag — daemon stop should always reset it.
+      entry.state.paused = false;
+
       // 1. Stop message loop
       this.stopMessageLoop(id);
 
@@ -1633,16 +1671,40 @@ export class WorkspaceOrchestrator extends EventEmitter {
     return this.daemonActive;
   }
 
-  /** Pause a running agent */
+  /** Pause a smith — drop pending/incoming bus messages as failed, suppress watch alerts.
+   *  In-flight task continues. Resume does NOT replay dropped messages.
+   *  Transient: any daemon stop/start or process restart clears the flag. */
   pauseAgent(agentId: string): void {
     const entry = this.agents.get(agentId);
-    entry?.worker?.pause();
+    if (!entry) return;
+    entry.state.paused = true;
+    entry.worker?.pause();
+
+    // Drain inbox: anything queued for this smith → failed (visible in inbox).
+    let drained = 0;
+    for (const m of this.bus.getLog()) {
+      if (m.to !== agentId || m.type === 'ack') continue;
+      if (m.status === 'pending' || m.status === 'pending_approval') {
+        m.status = 'failed' as any;
+        drained++;
+        this.emit('event', { type: 'bus_message_status', messageId: m.id, status: 'failed' } as any);
+      }
+    }
+
+    this.emit('event', { type: 'task_status', agentId, taskStatus: entry.state.taskStatus } as any);
+    this.emitAgentsChanged();
+    console.log(`[workspace] ${entry.config.label}: paused${drained ? ` (${drained} pending message(s) dropped to failed)` : ''}`);
   }
 
-  /** Resume a paused agent */
+  /** Resume a paused smith — clear flag, re-enable bus pickup and watch dispatch. */
   resumeAgent(agentId: string): void {
     const entry = this.agents.get(agentId);
-    entry?.worker?.resume();
+    if (!entry) return;
+    entry.state.paused = false;
+    entry.worker?.resume();
+    this.emit('event', { type: 'task_status', agentId, taskStatus: entry.state.taskStatus } as any);
+    this.emitAgentsChanged();
+    console.log(`[workspace] ${entry.config.label}: resumed`);
   }
 
   /** Stop a running agent */
@@ -2902,6 +2964,14 @@ Silently ingest this context. Do NOT respond — await an actual task.`;
     // ── Store message in agent history ──
     target.state.history.push(logEntry);
 
+    // ── Paused smith → drop as failed; user retries/deletes from inbox. ──
+    if (target.state.paused) {
+      msg.status = 'failed' as any;
+      this.emit('event', { type: 'bus_message_status', messageId: msg.id, status: 'failed' } as any);
+      console.log(`[bus] ${target.config.label}: paused — ${action} dropped to failed`);
+      return;
+    }
+
     // ── requiresApproval → set pending_approval on arrival ──
     if (target.config.requiresApproval) {
       msg.status = 'pending_approval';
@@ -2933,6 +3003,9 @@ Silently ingest this context. Do NOT respond — await an actual task.`;
       // (loop stays alive so it works when smith comes back)
       if (entry.state.smithStatus !== 'active') return;
 
+      // Paused smiths refuse new bus pickups; loop stays alive for resume.
+      if (entry.state.paused) return;
+
       // Skip if already busy
       if (entry.state.taskStatus === 'running') return;
 

package/lib/workspace/persistence.ts

@@ -53,6 +53,9 @@ export async function saveWorkspace(state: WorkspaceState): Promise<void> {
         ...s,
         history: [],
         logFile: agentLogFile(state.id, id),
+        paused: undefined,                // transient — never persisted
+        taskStatusChangedAt: undefined,   // transient
+        lastTaskStatus: undefined,        // transient
       }])
     ),
     updatedAt: Date.now(),
@@ -90,6 +93,9 @@ export function saveWorkspaceSync(state: WorkspaceState): void {
         ...s,
         history: [],
         logFile: agentLogFile(state.id, id),
+        paused: undefined,                // transient — never persisted
+        taskStatusChangedAt: undefined,   // transient
+        lastTaskStatus: undefined,        // transient
       }])
     ),
     updatedAt: Date.now(),
@@ -160,6 +166,16 @@ export function loadWorkspace(workspaceId: string): WorkspaceState | null {
       if (agentState.taskStatus === 'running') {
         agentState.taskStatus = 'idle';
       }
+
+      // Defensive: paused is transient. Force false on load in case any
+      // older state.json still has it persisted.
+      agentState.paused = false;
+
+      // Init the agent_status watch fields. Setting changedAt to now() means
+      // any transitions that happen after load advance the timestamp; watchers
+      // record this baseline at their first tick and won't spuriously fire.
+      agentState.taskStatusChangedAt = Date.now();
+      agentState.lastTaskStatus = agentState.taskStatus;
     }
 
     // Migrate Input nodes: content → entries