@aion0/forge 0.5.42 → 0.5.44

package/intellij-plugin/src/main/kotlin/com/aion0/forge/ui/toolwindow/WorkspacesView.kt

@@ -0,0 +1,166 @@
+package com.aion0.forge.ui.toolwindow
+
+import com.aion0.forge.api.ForgeClient
+import com.intellij.icons.AllIcons
+import com.intellij.openapi.actionSystem.AnAction
+import com.intellij.openapi.actionSystem.AnActionEvent
+import com.intellij.openapi.project.Project
+import com.intellij.openapi.ui.Messages
+import org.jetbrains.plugins.terminal.ShellTerminalWidget
+import org.jetbrains.plugins.terminal.TerminalView
+import javax.swing.tree.DefaultMutableTreeNode
+
+class WorkspacesView(project: Project) : ForgeTreeView(project) {
+
+    /** Cache of open smith terminals keyed by tmux session name. Re-clicking a smith
+     *  focuses the existing terminal tab instead of spawning a duplicate. */
+    private val openedTerminals = mutableMapOf<String, ShellTerminalWidget>()
+
+    override fun rootLabel() = "workspaces"
+
+    override fun reload(): List<DefaultMutableTreeNode> {
+        val r = ForgeClient.get().request("/api/workspace")
+        if (r.status == 401 || r.status == 403) return listOf(DefaultMutableTreeNode(TreeNodeData.Hint("🔑 Tools → Forge: Login")))
+        if (!r.ok || r.data == null || !r.data.isJsonArray) {
+            return listOf(DefaultMutableTreeNode(TreeNodeData.Hint("⚠ ${r.error ?: "Not connected"}")))
+        }
+        val arr = r.data.asJsonArray
+        if (arr.size() == 0) return listOf(DefaultMutableTreeNode(TreeNodeData.Hint("No workspaces yet")))
+        val sorted = arr.toList().sortedBy { it.asJsonObject.get("projectName")?.asString ?: "" }
+        return sorted.mapNotNull { el ->
+            val ws = el.asJsonObject
+            val id = ws.get("id")?.asString ?: return@mapNotNull null
+            val name = ws.get("projectName")?.asString ?: id
+            val ar = ForgeClient.get().request("/api/workspace/$id/agents")
+            val agents = ar.data?.asJsonObject?.getAsJsonArray("agents")
+            val states = ar.data?.asJsonObject?.getAsJsonObject("states")
+            val daemon = ar.data?.asJsonObject?.get("daemonActive")?.asBoolean ?: false
+            val mark = if (daemon) "🟢" else "○"
+            val node = DefaultMutableTreeNode(TreeNodeData.Workspace("$mark $name  (${agents?.size() ?: 0} smiths)", id, name, daemon))
+            agents?.forEach { aEl ->
+                val a = aEl.asJsonObject
+                val aId = a.get("id")?.asString ?: return@forEach
+                val label = a.get("label")?.asString ?: aId
+                val icon = a.get("icon")?.asString ?: "🤖"
+                val s = states?.getAsJsonObject(aId)
+                val task = s?.get("taskStatus")?.asString ?: "idle"
+                val smith = s?.get("smithStatus")?.asString ?: "down"
+                val paused = s?.get("paused")?.asBoolean == true
+                val tmux = s?.get("tmuxSession")?.asString
+                val statusEmoji = when {
+                    paused             -> "⏸"
+                    smith == "down"    -> "○"
+                    smith == "starting"-> "◐"
+                    task == "running"  -> "▶"
+                    task == "failed"   -> "✕"
+                    task == "done"     -> "✓"
+                    else               -> "·"
+                }
+                node.add(DefaultMutableTreeNode(
+                    TreeNodeData.Smith("$statusEmoji $icon $label  ($task)", id, aId, label, task, paused, tmux),
+                ))
+            }
+            node
+        }
+    }
+
+    override fun onDoubleClick(data: TreeNodeData, node: DefaultMutableTreeNode) {
+        when (data) {
+            is TreeNodeData.Smith -> openSmithTerminal(data)
+            else -> {}
+        }
+    }
+
+    override fun contextActions(data: TreeNodeData, node: DefaultMutableTreeNode): List<AnAction> = when (data) {
+        is TreeNodeData.Workspace -> if (data.daemonActive) {
+            listOf(
+                act("Stop Daemon",   AllIcons.Actions.Suspend) { confirmAndDoWs(data.workspaceId, "stop_daemon",  "Stop the workspace daemon? Running smiths will be terminated.") },
+                act("Restart Daemon",AllIcons.Actions.Restart) { runApi(project, "Restart daemon", { restartDaemon(data.workspaceId) }) { refresh() } },
+            )
+        } else {
+            listOf(
+                act("Start Daemon", AllIcons.Actions.Execute) { runApi(project, "Start daemon", { wsAction(data.workspaceId, "start_daemon") }) { refresh() } },
+            )
+        }
+        is TreeNodeData.Smith -> buildList {
+            add(act("Open Terminal", AllIcons.Debugger.Console) { openSmithTerminal(data) })
+            add(act("Send Message",  AllIcons.General.Balloon) { promptSendMessage(data) })
+            if (data.paused) {
+                add(act("Resume", AllIcons.Actions.Execute) { runApi(project, "Resume ${data.agentLabel}", { wsAction(data.workspaceId, "resume", mapOf("agentId" to data.agentId)) }) { refresh() } })
+            } else {
+                add(act("Pause", AllIcons.Actions.Suspend) { runApi(project, "Pause ${data.agentLabel}", { wsAction(data.workspaceId, "pause", mapOf("agentId" to data.agentId)) }) { refresh() } })
+            }
+            if (data.taskStatus == "running") {
+                add(act("Mark Done",   null) { runApi(project, "Mark done",   { wsAction(data.workspaceId, "mark_done",   mapOf("agentId" to data.agentId, "notify" to true)) }) { refresh() } })
+                add(act("Mark Failed", null) { runApi(project, "Mark failed", { wsAction(data.workspaceId, "mark_failed", mapOf("agentId" to data.agentId, "notify" to true)) }) { refresh() } })
+                add(act("Mark Idle",   null) { runApi(project, "Mark idle",   { wsAction(data.workspaceId, "mark_done",   mapOf("agentId" to data.agentId, "notify" to false)) }) { refresh() } })
+            }
+            if (data.taskStatus == "failed") {
+                add(act("Retry", AllIcons.Actions.Refresh) { runApi(project, "Retry ${data.agentLabel}", { wsAction(data.workspaceId, "retry", mapOf("agentId" to data.agentId)) }) { refresh() } })
+            }
+        }
+        else -> emptyList()
+    }
+
+    private fun confirmAndDoWs(wsId: String, action: String, prompt: String) {
+        val r = Messages.showYesNoDialog(project, prompt, "Forge", Messages.getQuestionIcon())
+        if (r == Messages.YES) runApi(project, action, { wsAction(wsId, action) }) { refresh() }
+    }
+
+    private fun restartDaemon(wsId: String): com.aion0.forge.api.ApiResult {
+        val stop = wsAction(wsId, "stop_daemon")
+        if (!stop.ok) return stop
+        Thread.sleep(800)
+        return wsAction(wsId, "start_daemon")
+    }
+
+    /** Open an IDE terminal and run `tmux attach -t <session>` — works for
+     *  local forge. Remote forge would need a WebSocket-bridged JediTerm
+     *  session (TODO). Reuses an existing terminal tab if one was already
+     *  opened for this smith. */
+    private fun openSmithTerminal(smith: TreeNodeData.Smith) {
+        val res = ForgeClient.get().request(
+            "/api/workspace/${smith.workspaceId}/agents",
+            method = "POST",
+            body = mapOf("action" to "open_terminal", "agentId" to smith.agentId),
+        )
+        val tmux = res.data?.asJsonObject?.get("tmuxSession")?.asString ?: smith.tmuxSession
+        if (tmux.isNullOrBlank()) {
+            notify(project, "Forge: smith ${smith.agentLabel} has no tmux session yet — start the daemon first.", com.intellij.notification.NotificationType.WARNING)
+            return
+        }
+        val existing = openedTerminals[tmux]
+        if (existing != null && !com.intellij.openapi.util.Disposer.isDisposed(existing)) {
+            // Surface the existing tab in the Terminal tool window.
+            val tw = com.intellij.openapi.wm.ToolWindowManager.getInstance(project).getToolWindow("Terminal")
+            tw?.activate(null)
+            existing.requestFocusInWindow()
+            return
+        }
+        val terminalView = TerminalView.getInstance(project)
+        val widget = terminalView.createLocalShellWidget(project.basePath ?: System.getProperty("user.home"), "forge: ${smith.agentLabel}")
+        openedTerminals[tmux] = widget
+        com.intellij.openapi.util.Disposer.register(widget) { openedTerminals.remove(tmux) }
+        // Force UTF-8 + 256-color terminfo so the tmux UI doesn't render as garbled
+        // box-drawing characters in JediTerm. `-u` opts into UTF-8, `-2` forces 256-color.
+        widget.executeCommand("TERM=xterm-256color tmux -2 -u attach -t \"$tmux\" || TERM=xterm-256color tmux -2 -u new -A -s \"$tmux\"")
+    }
+
+    private fun promptSendMessage(smith: TreeNodeData.Smith) {
+        val text = Messages.showMultilineInputDialog(
+            project,
+            "Send message to ${smith.agentLabel}",
+            "Forge: Send Message",
+            "",
+            null, null,
+        ) ?: return
+        if (text.isBlank()) return
+        runApi(project, "Send message to ${smith.agentLabel}",
+            { wsAction(smith.workspaceId, "message", mapOf("agentId" to smith.agentId, "content" to text)) },
+        ) { refresh() }
+    }
+
+    private fun act(name: String, icon: javax.swing.Icon?, run: () -> Unit) = object : AnAction(name, null, icon) {
+        override fun actionPerformed(e: AnActionEvent) = run()
+    }
+}

package/intellij-plugin/src/main/resources/META-INF/plugin.xml

@@ -0,0 +1,88 @@
+<idea-plugin>
+    <id>com.aion0.forge</id>
+    <name>Forge Vibe Coding</name>
+    <version>0.1.0</version>
+    <vendor email="liuzhen1984@gmail.com" url="https://github.com/aiwatching/forge">aion0</vendor>
+
+    <description><![CDATA[
+        <p>Drive your <a href="https://github.com/aiwatching/forge">Forge</a> instance from
+        the IDE — workspaces, agents, terminals, pipelines and docs in one tool window.</p>
+
+        <p><b>⚠ Requires Forge running locally.</b> Install once:</p>
+        <pre>npm install -g @aion0/forge
+forge server start</pre>
+        <p>Default port <code>8403</code>. Configure remote forges under
+        <b>Settings → Tools → Forge</b>.</p>
+
+        <h3>Features</h3>
+        <ul>
+            <li>Workspaces — daemon control, multi-agent smiths, tmux attach, pause/resume/retry</li>
+            <li>Terminals — per-project claude sessions, double-click to resume, right-click → Open With for any agent</li>
+            <li>Pipelines — bindings + run details with per-node prompt / result / diff viewer</li>
+            <li>Docs — open files in editor, "open terminal here"</li>
+            <li>Multi-connection — local + remote forges with status-bar switcher</li>
+        </ul>
+    ]]></description>
+
+    <change-notes><![CDATA[
+        <h3>0.1.0</h3>
+        <ul>
+            <li>Initial scaffold: tool window shell, settings page, login flow, multi-connection support.</li>
+        </ul>
+    ]]></change-notes>
+
+    <depends>com.intellij.modules.platform</depends>
+    <depends>org.jetbrains.plugins.terminal</depends>
+
+    <extensions defaultExtensionNs="com.intellij">
+        <!-- Persisted application-level state (connections + active connection). -->
+        <applicationService serviceImplementation="com.aion0.forge.connection.ConnectionManager"/>
+        <applicationService serviceImplementation="com.aion0.forge.api.ForgeClient"/>
+        <applicationService serviceImplementation="com.aion0.forge.auth.Auth"/>
+
+        <!-- Tool window: lives on the right side, contains tabs for each section. -->
+        <toolWindow
+            id="Forge"
+            anchor="left"
+            secondary="true"
+            icon="/icons/forge.svg"
+            factoryClass="com.aion0.forge.ui.toolwindow.ForgeToolWindowFactory"/>
+
+        <!-- Settings page (Preferences → Tools → Forge). -->
+        <applicationConfigurable
+            parentId="tools"
+            instance="com.aion0.forge.settings.ForgeConfigurable"
+            id="com.aion0.forge.settings.ForgeConfigurable"
+            displayName="Forge"/>
+
+        <!-- Status bar widget — connection state + click-to-switch. -->
+        <statusBarWidgetFactory
+            id="com.aion0.forge.statusbar"
+            implementation="com.aion0.forge.ui.toolwindow.ForgeStatusBarWidgetFactory"
+            order="last"/>
+
+        <notificationGroup id="Forge" displayType="BALLOON"/>
+    </extensions>
+
+    <actions>
+        <group id="com.aion0.forge.actions" text="Forge" popup="true">
+            <action id="com.aion0.forge.action.LoginAction"
+                    class="com.aion0.forge.action.LoginAction"
+                    text="Forge: Login"
+                    description="Authenticate against the active Forge server."/>
+            <action id="com.aion0.forge.action.LogoutAction"
+                    class="com.aion0.forge.action.LogoutAction"
+                    text="Forge: Logout"
+                    description="Clear the saved token for the active connection."/>
+            <action id="com.aion0.forge.action.SwitchConnectionAction"
+                    class="com.aion0.forge.action.SwitchConnectionAction"
+                    text="Forge: Switch Connection…"
+                    description="Pick a different Forge server."/>
+            <action id="com.aion0.forge.action.OpenWebUIAction"
+                    class="com.aion0.forge.action.OpenWebUIAction"
+                    text="Forge: Open Web UI"
+                    description="Open the Forge web UI in the default browser."/>
+            <add-to-group group-id="ToolsMenu" anchor="last"/>
+        </group>
+    </actions>
+</idea-plugin>

package/intellij-plugin/src/main/resources/icons/forge.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="13" height="13" viewBox="0 0 24 24" fill="currentColor">
+  <path d="M12 2L3 7v6c0 5 3.5 9.5 9 11 5.5-1.5 9-6 9-11V7l-9-5zm0 4.5l5 2.8v3.4l-5-2.8-5 2.8V9.3l5-2.8zm-5 6.4l5 2.8v5.6c-3.4-1.4-5-4.6-5-7.6v-.8zm10 .8c0 3-1.6 6.2-5 7.6v-5.6l5-2.8v.8z"/>
+</svg>

package/lib/agents/index.ts

@@ -209,7 +209,7 @@ export function resolveTerminalLaunch(agentId?: string): TerminalLaunchInfo {
 
   // Determine CLI command and capabilities from cliType
   const cliMap: Record<string, { cmd: string; session: boolean; resume: string }> = {
-    'claude-code': { cmd: 'claude', session: true, resume: '-c' },
+    'claude-code': { cmd: 'claude', session: true, resume: '--resume' },
     'codex': { cmd: 'codex', session: false, resume: '' },
     'aider': { cmd: 'aider', session: false, resume: '' },
     'generic': { cmd: agentCfg.path || agentId || 'claude', session: false, resume: '' },

package/lib/help-docs/00-overview.md

@@ -17,6 +17,7 @@ Forge is a self-hosted Vibe Coding platform for Claude Code. It provides a brows
 | **Remote Access** | One-click Cloudflare tunnel for remote browsing |
 | **GitHub Issue Auto-fix** | Scan issues, auto-fix, create PRs |
 | **Memory (optional)** | Code graph + knowledge via `@aion0/temper` MCP server |
+| **IDE Plugins** | First-party VSCode extension and IntelliJ plugin — drive workspaces, agents, terminals, pipelines and docs from inside the editor (see `13-ide-plugins.md`) |
 
 ## Quick Start
 

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/help-docs/13-ide-plugins.md

@@ -0,0 +1,90 @@
+# IDE Plugins
+
+Forge ships with two first-party IDE plugins that mirror the web UI's feature set so you can drive workspaces, agent terminals, pipelines and docs without leaving the editor. Both are **thin clients** — they require a Forge server running locally (or reachable over a tunnel).
+
+| | VSCode extension | IntelliJ plugin |
+|---|---|---|
+| Marketplace ID | `aion0.forge-vibecoding` | `Forge Vibe Coding` (`com.aion0.forge`) |
+| Install | VSCode → Extensions → search `Forge Vibe Coding` | IDE → Settings → Plugins → Marketplace → search `Forge Vibe Coding` |
+| Source | `vscode-extension/` | `intellij-plugin/` |
+| Min IDE | VSCode ≥ 1.80 | IntelliJ Platform ≥ 2024.1 (build 241) |
+
+## Prerequisites
+
+The plugins do **not** ship Forge — install it once first:
+
+```bash
+npm install -g @aion0/forge
+forge server start
+```
+
+Default port `8403`. The plugins auto-detect `http://localhost:8403`. For remote forges (over Cloudflare tunnel or LAN), add a connection in plugin settings (see below).
+
+## Tool Window / Sidebar Layout
+
+Both plugins expose four tabs:
+
+| Tab | Shows | Right-click actions | Double-click |
+|---|---|---|---|
+| **Workspaces** | Forge workspaces with daemon status (🟢/○) and per-smith status emoji (▶ running / ⏸ paused / ✓ done / ✕ failed / ◐ starting) | Workspace: start / stop / restart daemon. Smith: open terminal, send message, pause/resume, mark done/failed/idle, retry. | Smith → attach to its tmux session in an IDE terminal |
+| **Terminals** | Each forge project as a folder with its claude sessions (★ = bound/pinned default). | Project: **Open With ▸** submenu of every configured agent (claude/codex/aider/...) — fresh launch; New Session… (pick agent); Plain Terminal Here. Session: Resume; Resume With… submenu; Pin as Default Session. | Session row resumes that exact session via `claude --resume <id>` |
+| **Pipelines** | Forge projects with their pipeline bindings (⚙ enabled / ⊘ disabled) and recent runs (▶/✓/✕/⊘). | Project: Add Pipeline…; Binding: Trigger Now, Enable/Disable, Remove; Run: Show Nodes; Node: Show Result. | Binding: trigger; Run: expand to see nodes; Node: open prompt/result/diff/log as a markdown buffer |
+| **Docs** | Configured doc roots → file/dir tree. | Dir: Open Terminal Here (runs claude); File: Open. | File: open in IDE editor |
+
+## Multi-Connection (Local + Remote forges)
+
+Both plugins support multiple Forge servers — useful when you have one Forge running locally for `~/.forge` and a second running on an office Mac mini exposed via tunnel.
+
+**VSCode**: edit `forge.connections` in settings.json:
+```json
+{
+  "forge.connections": [
+    { "name": "Local",  "serverUrl": "http://localhost:8403", "terminalUrl": "ws://localhost:8404" },
+    { "name": "Office", "serverUrl": "https://forge-office.trycloudflare.com", "terminalUrl": "wss://forge-office.trycloudflare.com" }
+  ],
+  "forge.activeConnection": "Local"
+}
+```
+Click the status-bar entry (bottom right, `Forge: <name>`) to switch.
+
+**IntelliJ**: Settings → Tools → Forge → Connections list. Status-bar widget toggles active connection.
+
+Tokens are stored per-connection: VSCode uses `SecretStorage`, IntelliJ uses `PasswordSafe`. `Forge: Login` (command palette / Tools menu) prompts for the admin password and caches the bearer token.
+
+## How agent terminals work
+
+When you double-click a session row or pick `Open With ▸ <agent>`:
+
+1. Plugin calls `GET /api/agents?resolve=<agentId>` → gets `cliCmd`, `cliType`, `supportsSession`, `env`, `model`.
+2. For specific-session resume: `claude --resume <sid>` (forced regardless of API's `resumeFlag` — `-c` is wrong for specific resume).
+3. Profile env vars are forwarded to the spawned process.
+4. `model` is passed as `--model <name>` for claude-code agents (so a "sonnet" profile actually runs sonnet).
+5. **IntelliJ** spawns the agent CLI directly as the pty's primary process (`LocalTerminalDirectRunner` subclass with `enableShellIntegration = false` + `configureStartupOptions` override) — no shell, no `executeCommand` race. The user's login shell (`$SHELL -l`) is wrapped around it so `.zprofile` / `.bash_profile` is sourced for PATH.
+6. **VSCode** uses the existing terminal-server WebSocket (`forge.terminalUrl`) to attach.
+
+Workspace smith terminals attach to a pre-existing tmux session via `tmux -2 -u attach -t <session>` (UTF-8 + 256-color forced, otherwise JediTerm/xterm.js render boxes wrong).
+
+## Releasing new versions (maintainers)
+
+Each plugin has a `publish.sh` in its directory:
+
+```bash
+# VSCode — needs `vsce login aion0` cached, or $VSCE_PAT env var
+cd vscode-extension
+./publish.sh patch          # bump 0.2.x → 0.2.(x+1) and publish
+
+# IntelliJ — needs $JETBRAINS_MARKETPLACE_TOKEN env var
+cd intellij-plugin
+./publish.sh patch
+```
+
+VSCode goes live in 1–2 minutes. IntelliJ goes through human moderation: 1–3 business days for the first publish, hours-to-1-day for subsequent updates of an already-approved plugin.
+
+## Troubleshooting
+
+- **"Not connected" / "401" in tree** — Forge server isn't running or the token expired. Run `Forge: Login` (or `forge server start` if the server is down).
+- **Terminal opens but agent CLI fails** ("`claude: command not found`") — IDE inherited a stripped PATH. The IntelliJ plugin spawns under `$SHELL -l -c …` to source `.zprofile`/`.bash_profile`; if your PATH is set in `.zshrc` only (not `.zprofile`), move it.
+- **Smith terminal shows garbled output** — make sure tmux ≥ 3.0 and the IDE terminal supports UTF-8 + 256-color. The plugin already passes `tmux -2 -u attach`; if it still looks broken, check `$LANG` is `*.UTF-8`.
+- **Picked a session, claude opens a different one** — Forge ≤ 0.5.43 had `resume: '-c'` hardcoded for claude (which is `--continue`, zero-arg). Upgrade Forge or pull the latest `lib/agents/index.ts`.
+- **JetBrains plugin install fails with "incompatible build"** — verify your IDE is build 241+ (Help → About → Build #). The plugin's `sinceBuild = 241`.
+- **Tree keeps collapsing folders I expanded** — fixed in IntelliJ plugin v0.1.17 (full path expansion is preserved across the 5-second poll, not just top-level).

package/lib/help-docs/CLAUDE.md

@@ -43,6 +43,7 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 | `10-troubleshooting.md` | Common issues and solutions |
 | `11-workspace.md` | Workspace (Forge Smiths) — multi-agent orchestration, daemon, message bus, profiles |
 | `12-usage.md` | Token usage analytics — charts, heatmap, cost estimation, by model/project/source |
+| `13-ide-plugins.md` | VSCode extension + IntelliJ plugin — install, tabs, multi-connection, agent terminal launching |
 
 ## Matching questions to docs
 
@@ -64,3 +65,5 @@ The token is valid for 24 hours. Store it in a variable and reuse for all API ca
 - Usage/cost/tokens/spending/billing/analytics → `12-usage.md`
 - Terminal dock/float/mouse toggle/reconnect → `07-projects.md` + `11-workspace.md`
 - Sidebar collapse/project tabs/favorites → `07-projects.md`
+- VSCode/IntelliJ/IDE plugin/extension/marketplace → `13-ide-plugins.md`
+- vsce/vsix/JetBrains marketplace publish → `13-ide-plugins.md`

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

package/lib/workspace/types.ts

@@ -99,6 +99,19 @@ export interface AgentState {
   // ─── Task layer (current work) ──────────
   taskStatus: TaskStatus;             // idle/running/done/failed
 
+  // Transient runtime flag — paused smith ignores bus pickups, drops new
+  // incoming messages as failed, and suppresses watch alerts. Never persisted;
+  // any daemon stop/start or process restart clears it.
+  paused?: boolean;
+
+  // Transient: timestamp of the most recent taskStatus *change* (idempotent
+  // re-emits of the same value don't update this). Used by agent_status watches
+  // to detect transitions without polling. Reset to Date.now() on load.
+  taskStatusChangedAt?: number;
+  // Transient: previous taskStatus value, used by orchestrator's event listener
+  // to dedup idempotent emits. Reset to current taskStatus on load.
+  lastTaskStatus?: TaskStatus;
+
   // ─── Execution details ──────────────────
   currentStep?: number;
   history: TaskLogEntry[];