@dfosco/storyboard 0.6.0-beta.2 → 0.6.0-beta.21

package/src/core/canvas/terminal-server.js

@@ -23,7 +23,7 @@
  */
 
 import { execSync } from 'node:child_process'
-import { readFileSync, mkdirSync, writeFileSync, renameSync, existsSync, unlinkSync } from 'node:fs'
+import { readFileSync, mkdirSync, writeFileSync, renameSync, existsSync, unlinkSync, rmSync } from 'node:fs'
 import { resolve, join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { tmpdir } from 'node:os'
@@ -63,6 +63,7 @@ import {
   captureFilePath,
   ensureCopilotCaptureHookInstalled,
   ensureClaudeCaptureHookInstalled,
+  ensureCodexCaptureHookInstalled,
 } from './agent-session.js'
 
 let pty
@@ -157,15 +158,11 @@ function cleanEnv() {
   return filtered
 }
 
-/** Read terminal config from storyboard.config.json */
+import { readTerminalSettings, readAgentsConfig } from './configReader.js'
+
+/** Read terminal-widget settings (merged from lib defaults + storyboard.config.json + terminal.config.json). */
 function readTerminalConfig() {
-  try {
-    const raw = readFileSync(resolve(process.cwd(), 'storyboard.config.json'), 'utf8')
-    const config = JSON.parse(raw)
-    return config?.canvas?.terminal ?? {}
-  } catch {
-    return {}
-  }
+  return readTerminalSettings()
 }
 
 /**
@@ -174,22 +171,19 @@ function readTerminalConfig() {
  */
 function resolveAgentConfig(startupCommand) {
   if (!startupCommand || startupCommand === 'shell') return null
-  try {
-    const raw = readFileSync(resolve(process.cwd(), 'storyboard.config.json'), 'utf8')
-    const agentsConfig = JSON.parse(raw)?.canvas?.agents
-    if (!agentsConfig || typeof agentsConfig !== 'object') return null
-    for (const [id, cfg] of Object.entries(agentsConfig)) {
-      if (!cfg?.startupCommand) continue
-      // Prefer exact/prefix match for deterministic routing; keep binary fallback for backwards compat.
-      if (
-        startupCommand === cfg.startupCommand
-        || startupCommand.startsWith(`${cfg.startupCommand} `)
-        || startupCommand.startsWith(cfg.startupCommand.split(' ')[0])
-      ) {
-        return { id, cfg }
-      }
+  const agentsConfig = readAgentsConfig()
+  if (!agentsConfig || typeof agentsConfig !== 'object') return null
+  for (const [id, cfg] of Object.entries(agentsConfig)) {
+    if (!cfg?.startupCommand) continue
+    // Prefer exact/prefix match for deterministic routing; keep binary fallback for backwards compat.
+    if (
+      startupCommand === cfg.startupCommand
+      || startupCommand.startsWith(`${cfg.startupCommand} `)
+      || startupCommand.startsWith(cfg.startupCommand.split(' ')[0])
+    ) {
+      return { id, cfg }
     }
-  } catch { /* empty */ }
+  }
   return null
 }
 
@@ -314,6 +308,46 @@ function stripAnsi(str) {
   return str.replace(/\x1b\[[0-9;]*[a-zA-Z]|\x1b\].*?(\x07|\x1b\\)|\x1b[()][0-9A-B]|\x1b[>=<]|\x1b\[[?]?[0-9;]*[hlsur]/g, '')
 }
 
+/**
+ * Send text into a tmux pane and confirm it submitted.
+ *
+ * The naive `send-keys -l <text>; send-keys Enter` pattern is racy against
+ * TUI agents (Copilot, Claude) that are still initializing their input
+ * widget when we fire — the text lands in the prompt box but the Enter
+ * is eaten before submit. We work around it by capturing the pane after
+ * each send and re-sending Enter (up to N times) until the unique tail
+ * of our text is no longer visible (= input was cleared = submitted).
+ *
+ * Synchronous on purpose (matches existing send-keys helpers).
+ */
+function tmuxSubmit(tmuxName, text, { retries = 5, delayMs = 250 } = {}) {
+  if (!hasTmux || !text) return
+  // Pick a needle that's unique enough to detect in the pane but short
+  // enough to survive wrapping. Last 40 chars of the message works well
+  // and avoids matching the original injected echo from earlier sends.
+  const needle = text.slice(-40)
+  const sleep = (ms) => {
+    try { execSync(`sleep ${(ms / 1000).toFixed(3)}`, { stdio: 'ignore' }) } catch { /* empty */ }
+  }
+  try {
+    execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(text)}`, { stdio: 'ignore' })
+  } catch { return }
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    sleep(delayMs)
+    try {
+      execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+    } catch { return }
+    sleep(delayMs)
+    let pane = ''
+    try {
+      pane = execSync(`tmux capture-pane -t "${tmuxName}" -p -J`, { encoding: 'utf8', timeout: 1000 })
+    } catch { return }
+    // If the tail of our text is no longer in the visible pane, the input
+    // was consumed (submitted). Done.
+    if (!pane.includes(needle)) return
+  }
+}
+
 /**
  * Inject a [System] identity message into a running agent's stdin via tmux send-keys.
  * Called from BOTH hot and cold paths after the tmux session is bound and config is written.
@@ -327,19 +361,13 @@ function injectIdentityMessage(tmuxName, { widgetId, displayName, canvasId, bran
   if (!hasTmux) return
   const configFile = `.storyboard/terminals/${widgetId}.json`
   const msg = `[System] Your terminal identity has been set. widgetId=${widgetId} displayName=${displayName} canvasId=${canvasId} configFile=${configFile} serverUrl=${serverUrl} — this is a configuration step, no response needed.`
-  try {
-    execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(msg)}`, { stdio: 'ignore' })
-    execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-  } catch { /* best effort */ }
+  tmuxSubmit(tmuxName, msg)
 }
 
 function injectRoleMessage(tmuxName, role) {
   if (!hasTmux || !role) return
   const msg = `Your role in the hub is ${role}, read .agents/roles/${role}.role.md to follow additional instructions`
-  try {
-    execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(msg)}`, { stdio: 'ignore' })
-    execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-  } catch { /* best effort */ }
+  tmuxSubmit(tmuxName, msg)
 }
 
 function injectHubTokenMessage(tmuxName, hasToken) {
@@ -347,10 +375,7 @@ function injectHubTokenMessage(tmuxName, hasToken) {
   const msg = hasToken
     ? 'You hold the hub token (speaking rights). Read .agents/roles/cluster-token.md for instructions.'
     : 'You do not hold the hub token. Wait for a message token before acting in the hub.'
-  try {
-    execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(msg)}`, { stdio: 'ignore' })
-    execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-  } catch { /* best effort */ }
+  tmuxSubmit(tmuxName, msg)
 }
 
 function injectRoleMessageForWidget(tmuxName, widgetId) {
@@ -687,11 +712,13 @@ export function setupTerminalServer(httpServer, base = '/', branch = 'unknown',
   initRegistry(root, { gracePeriod: termCfg.orphanGracePeriod })
   initTerminalConfig(root)
 
-  // Install user-level Copilot CLI hook (~/.copilot/hooks/storyboard-capture.json)
-  // and Claude Code hook (~/.claude/settings.json) that capture sessionStart
-  // payloads into per-widget files. Idempotent.
+  // Install user-level Copilot CLI hook (~/.copilot/hooks/storyboard-capture.json),
+  // Claude Code hook (~/.claude/settings.json), and Codex CLI hook
+  // (~/.codex/hooks.json) that capture sessionStart payloads into per-widget
+  // files. All idempotent.
   try { ensureCopilotCaptureHookInstalled() } catch { /* best-effort */ }
   try { ensureClaudeCaptureHookInstalled() } catch { /* best-effort */ }
+  try { ensureCodexCaptureHookInstalled() } catch { /* best-effort */ }
 
   // Best-effort: apply shell-config overrides if a tmux server already exists
   // from a previous dev server run. If no server exists, this fails silently —
@@ -1104,8 +1131,7 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
 
         // Agent shorthand scripts (copilot, claude, codex, etc.)
         try {
-          const raw = readFileSync(resolve(process.cwd(), 'storyboard.config.json'), 'utf8')
-          const agentsConfig = JSON.parse(raw)?.canvas?.agents
+          const agentsConfig = readAgentsConfig()
           if (agentsConfig && typeof agentsConfig === 'object') {
             for (const [id, cfg] of Object.entries(agentsConfig)) {
               if (!cfg.startupCommand) continue
@@ -1135,8 +1161,7 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
           `start() { if [ $# -eq 0 ]; then ${welcomeBase}; else ${welcomeBase} --startup "$*"; fi; }`,
         ]
         try {
-          const raw = readFileSync(resolve(process.cwd(), 'storyboard.config.json'), 'utf8')
-          const agentsConfig = JSON.parse(raw)?.canvas?.agents
+          const agentsConfig = readAgentsConfig()
           if (agentsConfig && typeof agentsConfig === 'object') {
             for (const [id, cfg] of Object.entries(agentsConfig)) {
               if (!cfg.startupCommand) continue
@@ -1170,17 +1195,22 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
         // pool-keyed for the life of the warm process, so the user-level
         // hook always writes there, not to the widget-keyed file.)
         const postStartup = resolvedAgentCfg?.postStartup || null
-        const readinessSignal = resolvedAgentCfg?.readinessSignal || null
+        // ── H2 fix: skip readiness re-poll on warm handoff.
+        // The hot pool already verified readiness when it warmed this session.
+        // Re-polling for a one-shot signal like Copilot's "Environment loaded:"
+        // against an already-running TUI always misses (the echo has long
+        // since scrolled off the visible pane, and `tmux capture-pane -p`
+        // returns only the visible region). Falling through to the 30s
+        // timeout fallback was delaying /allow-all, identity, role, and
+        // bindWidget by ~30s for every warm Copilot widget.
+        const readinessSignal = null
         setTimeout(() => {
           let completed = false
           const finalize = () => {
             if (completed) return
             completed = true
             if (postStartup) {
-              try {
-                execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(postStartup)}`, { stdio: 'ignore' })
-                execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-              } catch { /* empty */ }
+              tmuxSubmit(tmuxName, postStartup)
             }
             injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
             injectRoleMessageForWidget(tmuxName, widgetId)
@@ -1243,17 +1273,31 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
         const binDir = join(cwd, '.storyboard', 'terminals', 'bin')
         envParts.push(`export PATH="${binDir}:$PATH"`)
 
-        // Chain clear before exports so the typed env soup is wiped from
-        // view as soon as Enter executes, then chain clear again after so
-        // the agent starts on a clean screen.
-        let envExports = envParts.join(' && ')
-        if (startupCommand) {
-          envExports = `clear && ${envExports} && clear`
-        }
+        // Write env exports to a per-widget shell script and source it via a
+        // short send-keys. Avoids tmux send-keys -l truncation when the env
+        // soup (especially PATH expansion) gets large — observed: a 4 KB+
+        // chain stops mid-line on macOS, the agent command never runs.
+        const envScriptDir = join(cwd, '.storyboard', 'terminals')
+        try { mkdirSync(envScriptDir, { recursive: true }) } catch { /* empty */ }
+        const envScriptPath = join(envScriptDir, `${widgetId}.env.sh`)
+        // The Copilot/Claude/Codex sessionStart hooks touch this file once
+        // the agent is fully loaded with an interactive prompt — much more
+        // reliable than scanning the pane for a transient shell echo.
+        // See agent-session.js:buildCaptureBashScript.
+        const readyFilePath = join(envScriptDir, `${widgetId}.ready`)
+        try { rmSync(readyFilePath, { force: true }) } catch { /* empty */ }
+        try {
+          writeFileSync(envScriptPath, envParts.join('\n') + '\n')
+        } catch { /* empty */ }
+        // Source env script; the trailing readiness echo MUST remain on
+        // the pane so the post-startup poller can match it. Don't append
+        // a `clear` here — the welcomeCmd that runs next clears the pane
+        // itself before launching the agent.
+        const envSourceCmd = `source ${JSON.stringify(envScriptPath)}`
 
         setTimeout(() => {
           try {
-            execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(envExports)}`, { stdio: 'ignore' })
+            execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(envSourceCmd)}`, { stdio: 'ignore' })
             execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
           } catch { /* empty */ }
         }, 300)
@@ -1279,6 +1323,12 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
             let cmd = agentCfg?.startupCommand || startupCommand
             const postStartup = agentCfg?.postStartup || null
             const readinessSignal = agentCfg?.readinessSignal || null
+            // Agents with a sessionStart hook (Copilot/Claude/Codex) touch
+            // the .ready marker once the agent is fully loaded with an
+            // interactive prompt. Wait for the marker even when no
+            // readinessSignal is configured — much more accurate than
+            // pane scanning.
+            const useReadyFile = !!agentCfg?.sessionIdEnv
 
             // ── Resume: if we previously captured a session id for this
             // widget and it's still resumable (UUID + session-state dir
@@ -1325,54 +1375,69 @@ function handleConnection(ws, widgetId, canvasId, prettyName, widgetStartupComma
                 execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
               } catch { /* empty */ }
 
-              if (readinessSignal) {
-                // Poll for readiness, then send postStartup command and deliver messages
-                let sent = false
-                const finalize = (reason) => {
-                  if (sent) return
-                  sent = true
+              if (readinessSignal || useReadyFile) {
+                // Poll for readiness, then send postStartup command and deliver messages.
+                // The .ready marker is the accurate signal (Copilot/Claude/Codex
+                // sessionStart hook touches it once the TUI is interactive). On
+                // consumer repos with cold caches + resume mode, that can easily
+                // take 30–60s — well past any reasonable hard timeout. So we:
+                //   1. Keep polling indefinitely at 3s intervals for .ready.
+                //   2. At 30s, do a "soft commit": inject identity and bind to
+                //      the messaging bus so the widget is at least addressable
+                //      for hub broadcast and live messages.
+                //   3. When .ready finally appears, run the real postStartup.
+                let softBound = false
+                let postStartupSent = false
+                const softBind = () => {
+                  if (softBound) return
+                  softBound = true
+                  injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
+                  injectRoleMessageForWidget(tmuxName, widgetId)
+                  setTimeout(() => {
+                    migratePendingMessages(widgetId, branch, canvasId).then(() => {
+                      bindWidget({ widgetId, tmuxName, branch, canvasId, displayName: prettyName }).catch(() => {})
+                    }).catch(() => {
+                      bindWidget({ widgetId, tmuxName, branch, canvasId, displayName: prettyName }).catch(() => {})
+                    })
+                    joinPresence({ widgetId, senderName: prettyName || widgetId, branch, canvasId }).catch(() => {})
+                  }, 2000)
+                }
+                const runPostStartup = (reason) => {
+                  if (postStartupSent) return
+                  postStartupSent = true
                   clearInterval(pollInterval)
+                  try { rmSync(readyFilePath, { force: true }) } catch { /* empty */ }
                   setTimeout(() => {
                     if (postStartup) {
-                      try {
-                        execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(postStartup)}`, { stdio: 'ignore' })
-                        execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
-                      } catch { /* empty */ }
+                      tmuxSubmit(tmuxName, postStartup)
                     }
-                    // Inject identity, then bind to messaging bus. This restores
-                    // hub/role/broadcast context after a tmux restart — the
-                    // widget's terminal-config preserves hubs/role/connectedWidgets,
-                    // and bindWidget reattaches live message delivery + backfill.
-                    injectIdentityMessage(tmuxName, { widgetId, displayName: prettyName, canvasId, branch, serverUrl })
-                    injectRoleMessageForWidget(tmuxName, widgetId)
-                    setTimeout(() => {
-                      migratePendingMessages(widgetId, branch, canvasId).then(() => {
-                        bindWidget({ widgetId, tmuxName, branch, canvasId, displayName: prettyName }).catch(() => {})
-                      }).catch(() => {
-                        bindWidget({ widgetId, tmuxName, branch, canvasId, displayName: prettyName }).catch(() => {})
-                      })
-                      joinPresence({ widgetId, senderName: prettyName || widgetId, branch, canvasId }).catch(() => {})
-                    }, 2000)
+                    // Ensure identity/bind happened (no-op if already soft-bound)
+                    softBind()
                   }, 500)
-                  if (reason === 'timeout') {
-                    devLog(`[terminal-server] readiness timeout for ${widgetId} (${tmuxName}); proceeding with bind anyway (likely resume mode)`)
+                  if (reason === 'soft-bind-timeout') {
+                    devLog(`[terminal-server] readiness slow for ${widgetId} (${tmuxName}); soft-binding now, will run postStartup when .ready arrives`)
                   }
                 }
                 const pollInterval = setInterval(() => {
-                  if (sent) { clearInterval(pollInterval); return }
+                  if (postStartupSent) { clearInterval(pollInterval); return }
+                  // Primary: sessionStart hook touches the marker once the
+                  // agent is fully loaded and interactive.
+                  if (useReadyFile && existsSync(readyFilePath)) { runPostStartup('file'); return }
+                  if (!readinessSignal) return
                   try {
+                    // Fallback for agents without a hook: scan pane + 200
+                    // lines of scrollback (so the signal survives a TUI repaint).
                     const paneContent = execSync(
-                      `tmux capture-pane -t "${tmuxName}" -p`,
+                      `tmux capture-pane -t "${tmuxName}" -p -S -200`,
                       { encoding: 'utf8', timeout: 1000 }
                     )
-                    if (paneContent.includes(readinessSignal)) finalize('signal')
+                    if (paneContent.includes(readinessSignal)) runPostStartup('signal')
                   } catch { /* empty */ }
-                }, 2000)
-                // Fallback: if readiness signal never matches (e.g. resume mode
-                // doesn't print "Environment loaded:", or the agent shows a
-                // prompt we can't detect), bind anyway after 30s so the widget
-                // is at least addressable for live messages and hub broadcast.
-                setTimeout(() => finalize('timeout'), 30000)
+                }, 500)
+                // Soft-bind at 30s so the widget is addressable for hub/live
+                // messages even if Copilot's TUI is still warming up. The poller
+                // keeps running and will fire postStartup once .ready appears.
+                setTimeout(softBind, 30000)
               } else {
                 // No readiness signal — inject identity and bind to bus after a delay
                 setTimeout(() => {

package/src/core/cli/agent.js

@@ -14,6 +14,71 @@
 
 import { parseFlags } from './flags.js'
 import { dim, bold, cyan, yellow } from './intro.js'
+import { getServerUrl } from './serverUrl.js'
+
+/**
+ * Resolve a list of candidate server URLs to try, in priority order:
+ *   1. Live server registry / worktree port (getServerUrl)
+ *   2. STORYBOARD_SERVER_URL env (set when terminal was spawned — may be stale)
+ *   3. Terminal config file (`.storyboard/terminals/<widgetId>.json`)
+ *
+ * Registry-first because the env var can be stale if the dev server was
+ * restarted on a new port since the agent was spawned.
+ */
+async function resolveServerUrlCandidates(widgetId) {
+  const urls = []
+  const add = (u) => {
+    if (!u) return
+    const norm = String(u).replace(/\/$/, '')
+    if (!urls.includes(norm)) urls.push(norm)
+  }
+  try { add(getServerUrl()) } catch { /* ignore */ }
+  add(process.env.STORYBOARD_SERVER_URL)
+  if (widgetId) {
+    try {
+      const { readFileSync, existsSync } = await import('node:fs')
+      const path = await import('node:path')
+      const cfgPath = path.join(process.cwd(), '.storyboard', 'terminals', `${widgetId}.json`)
+      if (existsSync(cfgPath)) {
+        const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'))
+        add(cfg.serverUrl)
+      }
+    } catch { /* ignore */ }
+  }
+  return urls
+}
+
+/**
+ * POST to the first reachable candidate. Returns { url, res } on a server
+ * response (caller checks res.ok). Returns null if every candidate failed
+ * at the network layer.
+ */
+async function postWithFallback(candidates, pathSuffix, body, headers) {
+  let lastErr = null
+  for (const base of candidates) {
+    const url = `${base}${pathSuffix}`
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const res = await fetch(url, {
+          method: 'POST',
+          headers,
+          body,
+          signal: AbortSignal.timeout(5000),
+        })
+        if (res.ok || (res.status >= 400 && res.status < 500 && res.status !== 404)) {
+          return { url, res }
+        }
+        if (attempt === 1) break
+        await new Promise((r) => setTimeout(r, 200))
+      } catch (err) {
+        lastErr = err
+        break
+      }
+    }
+  }
+  if (lastErr) throw lastErr
+  return null
+}
 
 const subcommand = process.argv[3]
 
@@ -31,7 +96,6 @@ if (subcommand === 'signal') {
   const canvasId = flags.canvas || process.env.STORYBOARD_CANVAS_ID
   const status = flags.status
   const message = flags.message || null
-  const serverUrl = process.env.STORYBOARD_SERVER_URL || 'http://localhost:1234'
   const branch = process.env.STORYBOARD_BRANCH || 'unknown'
 
   if (!widgetId || !canvasId || !status) {
@@ -46,37 +110,26 @@ if (subcommand === 'signal') {
     process.exit(1)
   }
 
-  try {
-    const url = `${serverUrl}/_storyboard/canvas/agent/signal`
-    const body = JSON.stringify({ widgetId, canvasId, branch, status, message })
-    const headers = { 'Content-Type': 'application/json' }
+  const candidates = await resolveServerUrlCandidates(widgetId)
+  const body = JSON.stringify({ widgetId, canvasId, branch, status, message })
+  const headers = { 'Content-Type': 'application/json' }
 
-    // Retry transient failures (404/5xx) once with a short backoff — the dev
-    // proxy can briefly route to a stale port during reloads.
-    let res = null
-    let lastErr = null
-    for (let attempt = 0; attempt < 3; attempt++) {
-      try {
-        res = await fetch(url, { method: 'POST', headers, body })
-        if (res.ok) break
-        if (res.status >= 400 && res.status < 500 && res.status !== 404) break
-      } catch (err) {
-        lastErr = err
-      }
-      if (attempt < 2) await new Promise((r) => setTimeout(r, 250 * (attempt + 1)))
-    }
-
-    if (res && res.ok) {
-      console.log(`${cyan('✓')} Agent status: ${bold(status)}${message ? ` — ${message}` : ''}`)
-    } else if (res) {
-      const data = await res.json().catch(() => ({}))
-      console.error(`${yellow('⚠')} Server returned ${res.status}: ${data.error || 'unknown error'}`)
+  try {
+    const result = candidates.length > 0
+      ? await postWithFallback(candidates, '/_storyboard/canvas/agent/signal', body, headers)
+      : null
+    if (result && result.res.ok) {
+      console.log(`${cyan('✓')} Agent status: ${bold(status)}${message ? ` — ${message}` : ''} ${dim(`(${result.url})`)}`)
+    } else if (result) {
+      const data = await result.res.json().catch(() => ({}))
+      console.error(`${yellow('⚠')} Server returned ${result.res.status}: ${data.error || 'unknown error'} ${dim(`(${result.url})`)}`)
       await fallbackWrite({ branch, canvasId, widgetId, status, message })
     } else {
-      throw lastErr || new Error('signal request failed')
+      console.error(`${yellow('⚠')} No reachable server. Tried: ${candidates.join(', ') || '(none resolved)'}`)
+      await fallbackWrite({ branch, canvasId, widgetId, status, message })
     }
-  } catch {
-    // Server not reachable — write directly to terminal config file
+  } catch (err) {
+    console.error(`${yellow('⚠')} Signal failed (${err.message}). Tried: ${candidates.join(', ')}`)
     await fallbackWrite({ branch, canvasId, widgetId, status, message })
   }
 } else if (subcommand === 'spawn') {
@@ -96,7 +149,7 @@ if (subcommand === 'signal') {
   const agentId = spawnFlags['agent-id'] || undefined
   const autopilot = spawnFlags.autopilot !== false
   const branchOverride = spawnFlags.branch || undefined
-  const serverUrl = process.env.STORYBOARD_SERVER_URL || 'http://localhost:1234'
+  const serverUrl = getServerUrl()
 
   if (!canvasId || !widgetId || !prompt) {
     console.error(`${bold('Usage:')} npx storyboard agent spawn --prompt "task description"`)
@@ -133,7 +186,7 @@ if (subcommand === 'signal') {
   const widgetId = statusFlags.widget || process.env.STORYBOARD_WIDGET_ID
   const canvasId = statusFlags.canvas || process.env.STORYBOARD_CANVAS_ID || 'unknown'
   const branch = statusFlags.branch || process.env.STORYBOARD_BRANCH || 'unknown'
-  const serverUrl = process.env.STORYBOARD_SERVER_URL || 'http://localhost:1234'
+  const serverUrl = getServerUrl()
 
   if (!widgetId) {
     console.error(`${bold('Usage:')} npx storyboard agent status --widget <id>`)
@@ -165,7 +218,7 @@ if (subcommand === 'signal') {
 
   const widgetId = peekFlags.widget || process.env.STORYBOARD_WIDGET_ID
   const canvasId = peekFlags.canvas || process.env.STORYBOARD_CANVAS_ID
-  const serverUrl = process.env.STORYBOARD_SERVER_URL || 'http://localhost:1234'
+  const serverUrl = getServerUrl()
 
   if (!widgetId) {
     console.error(`${bold('Usage:')} npx storyboard agent peek --widget <id>`)
@@ -200,7 +253,7 @@ if (subcommand === 'signal') {
 
   const canvasId = listFlags.canvas || process.env.STORYBOARD_CANVAS_ID
   const branch = listFlags.branch || process.env.STORYBOARD_BRANCH || null
-  const serverUrl = process.env.STORYBOARD_SERVER_URL || 'http://localhost:1234'
+  const serverUrl = getServerUrl()
 
   if (!canvasId) {
     console.error(`${bold('Usage:')} npx storyboard agent list --canvas <id> [--branch <name>] [--json]`)
@@ -251,7 +304,7 @@ async function fallbackWrite({ branch, canvasId, widgetId, status, message }) {
     const { updateAgentStatus, initTerminalConfig } = await import('../canvas/terminal-config.js')
     initTerminalConfig(process.cwd())
     updateAgentStatus({ branch, canvasId, widgetId, status, message })
-    console.log(`${cyan('✓')} Agent status written to config file (server offline): ${bold(status)}`)
+    console.error(`${yellow('⚠')} Agent status persisted to config file only — UI will NOT update until server reconnects: ${bold(status)}`)
   } catch (err) {
     console.error(`Failed to write agent status: ${err.message}`)
     process.exit(1)