@aion0/forge 0.5.29 → 0.5.31

package/components/WorkspaceView.tsx

@@ -2211,7 +2211,7 @@ function FloatingTerminalInline({ agentLabel, agentIcon, projectPath, agentCliId
   return <div ref={containerRef} className="w-full h-full" style={{ background: '#0d1117' }} />;
 }
 
-function FloatingTerminal({ agentLabel, agentIcon, projectPath, agentCliId, cliCmd: cliCmdProp, cliType, workDir, preferredSessionName, existingSession, resumeMode, resumeSessionId, profileEnv, isPrimary, skipPermissions, persistentSession, boundSessionId, initialPos, onSessionReady, onClose }: {
+function FloatingTerminal({ agentLabel, agentIcon, projectPath, agentCliId, cliCmd: cliCmdProp, cliType, workDir, preferredSessionName, existingSession, resumeMode, resumeSessionId, profileEnv, isPrimary, skipPermissions, persistentSession, boundSessionId, initialPos, docked, onSessionReady, onClose }: {
   agentLabel: string;
   agentIcon: string;
   projectPath: string;
@@ -2229,6 +2229,7 @@ function FloatingTerminal({ agentLabel, agentIcon, projectPath, agentCliId, cliC
   persistentSession?: boolean;
   boundSessionId?: string;
   initialPos?: { x: number; y: number };
+  docked?: boolean;  // when true, render as grid cell instead of fixed floating window
   onSessionReady?: (name: string) => void;
   onClose: (killSession: boolean) => void;
 }) {
@@ -2243,9 +2244,24 @@ function FloatingTerminal({ agentLabel, agentIcon, projectPath, agentCliId, cliC
   }, [initialPos?.x, initialPos?.y]); // eslint-disable-line react-hooks/exhaustive-deps
   const [size, setSize] = useState({ w: 500, h: 300 });
   const [showCloseDialog, setShowCloseDialog] = useState(false);
+  const [mouseOn, setMouseOn] = useState(true);
   const dragRef = useRef<{ startX: number; startY: number; origX: number; origY: number } | null>(null);
   const resizeRef = useRef<{ startX: number; startY: number; origW: number; origH: number } | null>(null);
 
+  const toggleMouse = () => {
+    const next = !mouseOn;
+    setMouseOn(next);
+    // Send via current WebSocket (shared for all workspace terminals)
+    try {
+      const ws = new WebSocket(getWsUrl());
+      ws.onopen = () => {
+        ws.send(JSON.stringify({ type: 'tmux-mouse', mouse: next }));
+        setTimeout(() => ws.close(), 300);
+      };
+      ws.onerror = () => ws.close();
+    } catch {}
+  };
+
   useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -2437,13 +2453,16 @@ function FloatingTerminal({ agentLabel, agentIcon, projectPath, agentCliId, cliC
 
   return (
     <div
-      className="fixed z-50 bg-[#0d1117] border border-[#30363d] rounded-lg shadow-2xl flex flex-col overflow-hidden"
-      style={{ left: pos.x, top: pos.y, width: size.w, height: size.h }}
+      className={docked
+        ? "relative bg-[#0d1117] border border-[#30363d] rounded-lg flex flex-col overflow-hidden w-full h-full"
+        : "fixed z-50 bg-[#0d1117] border border-[#30363d] rounded-lg shadow-2xl flex flex-col overflow-hidden"
+      }
+      style={docked ? undefined : { left: pos.x, top: pos.y, width: size.w, height: size.h }}
     >
-      {/* Draggable header */}
+      {/* Header — draggable in floating mode, static in docked mode */}
       <div
-        className="flex items-center gap-2 px-3 py-1.5 bg-[#161b22] border-b border-[#30363d] cursor-move shrink-0 select-none"
-        onMouseDown={(e) => {
+        className={`flex items-center gap-2 px-3 py-1.5 bg-[#161b22] border-b border-[#30363d] shrink-0 select-none ${docked ? '' : 'cursor-move'}`}
+        onMouseDown={docked ? undefined : (e) => {
           e.preventDefault();
           dragRef.current = { startX: e.clientX, startY: e.clientY, origX: pos.x, origY: pos.y };
           setUserDragged(true);
@@ -2457,34 +2476,44 @@ function FloatingTerminal({ agentLabel, agentIcon, projectPath, agentCliId, cliC
         }}
       >
         <span className="text-sm">{agentIcon}</span>
-        <span className="text-[11px] font-semibold text-white">{agentLabel}</span>
-        <span className="text-[8px] text-gray-500">⌨️ manual terminal</span>
-        <button onClick={() => setShowCloseDialog(true)} className="ml-auto text-gray-500 hover:text-white text-sm">✕</button>
+        <span className="text-[11px] font-semibold text-white truncate">{agentLabel}</span>
+        {!docked && <span className="text-[8px] text-gray-500">⌨️ manual terminal</span>}
+        <button
+          onClick={(e) => { e.stopPropagation(); toggleMouse(); }}
+          onMouseDown={(e) => e.stopPropagation()}
+          className={`ml-auto text-[9px] px-1.5 py-0.5 rounded border transition-colors ${mouseOn ? 'border-green-600/40 text-green-400 bg-green-500/10' : 'border-gray-600 text-gray-500 bg-gray-800/50'}`}
+          title={mouseOn ? 'Mouse ON (trackpad scroll, Shift+drag to select text)' : 'Mouse OFF (drag to select text, Ctrl+B [ to scroll)'}
+        >
+          🖱️ {mouseOn ? 'ON' : 'OFF'}
+        </button>
+        <button onClick={() => setShowCloseDialog(true)} className="text-gray-500 hover:text-white text-sm shrink-0">✕</button>
       </div>
 
       {/* Terminal */}
       <div ref={containerRef} className="flex-1 min-h-0" style={{ background: '#0d1117' }} />
 
-      {/* Resize handle */}
-      <div
-        className="absolute bottom-0 right-0 w-4 h-4 cursor-se-resize"
-        onMouseDown={(e) => {
-          e.preventDefault();
-          e.stopPropagation();
-          resizeRef.current = { startX: e.clientX, startY: e.clientY, origW: size.w, origH: size.h };
-          const onMove = (ev: MouseEvent) => {
-            if (!resizeRef.current) return;
-            setSize({ w: Math.max(400, resizeRef.current.origW + ev.clientX - resizeRef.current.startX), h: Math.max(250, resizeRef.current.origH + ev.clientY - resizeRef.current.startY) });
-          };
-          const onUp = () => { resizeRef.current = null; window.removeEventListener('mousemove', onMove); window.removeEventListener('mouseup', onUp); };
-          window.addEventListener('mousemove', onMove);
-          window.addEventListener('mouseup', onUp);
-        }}
-      >
-        <svg viewBox="0 0 16 16" className="w-3 h-3 absolute bottom-0.5 right-0.5 text-gray-600">
-          <path d="M14 14L8 14L14 8Z" fill="currentColor" />
-        </svg>
-      </div>
+      {/* Resize handle — floating mode only */}
+      {!docked && (
+        <div
+          className="absolute bottom-0 right-0 w-4 h-4 cursor-se-resize"
+          onMouseDown={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            resizeRef.current = { startX: e.clientX, startY: e.clientY, origW: size.w, origH: size.h };
+            const onMove = (ev: MouseEvent) => {
+              if (!resizeRef.current) return;
+              setSize({ w: Math.max(400, resizeRef.current.origW + ev.clientX - resizeRef.current.startX), h: Math.max(250, resizeRef.current.origH + ev.clientY - resizeRef.current.startY) });
+            };
+            const onUp = () => { resizeRef.current = null; window.removeEventListener('mousemove', onMove); window.removeEventListener('mouseup', onUp); };
+            window.addEventListener('mousemove', onMove);
+            window.addEventListener('mouseup', onUp);
+          }}
+        >
+          <svg viewBox="0 0 16 16" className="w-3 h-3 absolute bottom-0.5 right-0.5 text-gray-600">
+            <path d="M14 14L8 14L14 8Z" fill="currentColor" />
+          </svg>
+        </div>
+      )}
 
       {/* Close confirmation dialog */}
       {showCloseDialog && (
@@ -3445,6 +3474,27 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
   };
   const [floatingTerminals, setFloatingTerminals] = useState<{ agentId: string; label: string; icon: string; cliId: string; cliCmd?: string; cliType?: string; workDir?: string; tmuxSession?: string; sessionName: string; resumeMode?: boolean; resumeSessionId?: string; profileEnv?: Record<string, string>; isPrimary?: boolean; skipPermissions?: boolean; persistentSession?: boolean; boundSessionId?: string; initialPos?: { x: number; y: number } }[]>([]);
   const [termPicker, setTermPicker] = useState<{ agent: AgentConfig; sessName: string; workDir?: string; supportsSession?: boolean; currentSessionId: string | null; initialPos?: { x: number; y: number } } | null>(null);
+  // Terminal layout: floating (draggable windows) or docked (fixed grid at bottom)
+  const [terminalLayout, setTerminalLayout] = useState<'floating' | 'docked'>(() => {
+    if (typeof window === 'undefined') return 'floating';
+    return (localStorage.getItem('forge.termLayout') as 'floating' | 'docked') || 'floating';
+  });
+  const [dockColumns, setDockColumns] = useState<number>(() => {
+    if (typeof window === 'undefined') return 2;
+    return parseInt(localStorage.getItem('forge.termDockCols') || '2');
+  });
+  const [dockHeight, setDockHeight] = useState<number>(() => {
+    if (typeof window === 'undefined') return 320;
+    return parseInt(localStorage.getItem('forge.termDockHeight') || '320');
+  });
+  const updateTerminalLayout = (l: 'floating' | 'docked') => {
+    setTerminalLayout(l);
+    if (typeof window !== 'undefined') localStorage.setItem('forge.termLayout', l);
+  };
+  const updateDockColumns = (n: number) => {
+    setDockColumns(n);
+    if (typeof window !== 'undefined') localStorage.setItem('forge.termDockCols', String(n));
+  };
 
   // Expose focusAgent to parent
   useImperativeHandle(ref, () => ({
@@ -3470,6 +3520,29 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
     ensureWorkspace(projectPath, projectName).then(setWorkspaceId).catch(() => {});
   }, [projectPath, projectName]);
 
+  // Saved node positions from server (loaded once on workspace init)
+  const [savedPositions, setSavedPositions] = useState<Record<string, { x: number; y: number }>>({});
+  useEffect(() => {
+    if (!workspaceId) return;
+    wsApi(workspaceId, 'get_positions').then((res: any) => {
+      if (res?.positions) setSavedPositions(res.positions);
+    }).catch(() => {});
+  }, [workspaceId]);
+
+  // Save positions (debounced) when nodes are dragged
+  const savePositionsDebounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const saveNodePositions = useCallback(() => {
+    if (!workspaceId) return;
+    if (savePositionsDebounceRef.current) clearTimeout(savePositionsDebounceRef.current);
+    savePositionsDebounceRef.current = setTimeout(() => {
+      const positions: Record<string, { x: number; y: number }> = {};
+      for (const n of rfNodes) {
+        positions[n.id] = { x: n.position.x, y: n.position.y };
+      }
+      wsApi(workspaceId, 'set_positions', { positions }).catch(() => {});
+    }, 500);
+  }, [workspaceId, rfNodes]);
+
   // SSE stream — server is the single source of truth
   const { agents, states, logPreview, busLog, daemonActive: daemonActiveFromStream, setDaemonActive: setDaemonActiveFromStream } = useWorkspaceStream(workspaceId, (event) => {
     if (event.type === 'user_input_request') {
@@ -3488,7 +3561,7 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
         const existing = prevMap.get(agent.id);
         const base = {
           id: agent.id,
-          position: existing?.position ?? { x: i * 260, y: 60 },
+          position: existing?.position ?? savedPositions[agent.id] ?? { x: i * 260, y: 60 },
           ...(existing?.measured ? { measured: existing.measured } : {}),
           ...(existing?.width ? { width: existing.width, height: existing.height } : {}),
         };
@@ -3598,7 +3671,7 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
         };
       });
     });
-  }, [agents, states, logPreview, workspaceId, mascotTheme]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [agents, states, logPreview, workspaceId, mascotTheme, savedPositions]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // Derive edges from dependsOn
   const rfEdges = useMemo(() => {
@@ -3770,6 +3843,32 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
           </>
         )}
         <div className="ml-auto flex items-center gap-2">
+          {/* Terminal layout switcher */}
+          <div className="flex items-center gap-0.5 px-1 py-0.5 rounded border border-[#30363d] bg-[#0d1117]">
+            <button
+              onClick={() => updateTerminalLayout('floating')}
+              className={`text-[8px] px-1.5 py-0.5 rounded ${terminalLayout === 'floating' ? 'bg-[#58a6ff]/20 text-[#58a6ff]' : 'text-gray-500 hover:text-white'}`}
+              title="Floating terminals (draggable windows)"
+            >⧉ Float</button>
+            <button
+              onClick={() => updateTerminalLayout('docked')}
+              className={`text-[8px] px-1.5 py-0.5 rounded ${terminalLayout === 'docked' ? 'bg-[#58a6ff]/20 text-[#58a6ff]' : 'text-gray-500 hover:text-white'}`}
+              title="Docked terminals (bottom grid)"
+            >▤ Dock</button>
+            {terminalLayout === 'docked' && (
+              <>
+                <span className="w-px h-3 bg-[#30363d] mx-0.5" />
+                {[1, 2, 3, 4].map(n => (
+                  <button
+                    key={n}
+                    onClick={() => updateDockColumns(n)}
+                    className={`text-[8px] px-1 py-0.5 rounded ${dockColumns === n ? 'bg-[#58a6ff]/20 text-[#58a6ff]' : 'text-gray-500 hover:text-white'}`}
+                    title={`${n} column${n > 1 ? 's' : ''}`}
+                  >{n}</button>
+                ))}
+              </>
+            )}
+          </div>
           <select value={mascotTheme} onChange={e => updateMascotTheme(e.target.value as MascotTheme)}
             className="text-[8px] px-1.5 py-0.5 rounded border border-[#30363d] bg-[#0d1117] text-gray-500 hover:text-white hover:border-[#58a6ff]/60 cursor-pointer focus:outline-none"
             title="Mascot theme">
@@ -3867,6 +3966,8 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
             edges={rfEdges}
             onNodesChange={onNodesChange}
             onNodeDragStop={() => {
+              // Persist positions
+              saveNodePositions();
               // Reposition terminals to follow their nodes
               setFloatingTerminals(prev => prev.map(ft => {
                 const nodeEl = document.querySelector(`[data-id="${ft.agentId}"]`);
@@ -4011,8 +4112,8 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
         />
       )}
 
-      {/* Floating terminals — positioned near their agent node */}
-      {floatingTerminals.map(ft => (
+      {/* Terminals — floating (draggable windows) or docked (bottom grid) */}
+      {terminalLayout === 'floating' && floatingTerminals.map(ft => (
         <FloatingTerminal
           key={ft.agentId}
           agentLabel={ft.label}
@@ -4043,6 +4144,67 @@ function WorkspaceViewInner({ projectPath, projectName, onClose }: {
         />
       ))}
 
+      {/* Docked terminals — bottom panel with grid layout */}
+      {terminalLayout === 'docked' && floatingTerminals.length > 0 && (
+        <div
+          className="fixed bottom-0 left-0 right-0 z-40 bg-[#0a0e14] border-t border-[#30363d] flex flex-col"
+          style={{ height: dockHeight }}
+        >
+          {/* Resize handle */}
+          <div
+            className="h-1 bg-[#30363d] hover:bg-[var(--accent)] cursor-ns-resize shrink-0"
+            onMouseDown={(e) => {
+              e.preventDefault();
+              const startY = e.clientY;
+              const startH = dockHeight;
+              const onMove = (ev: MouseEvent) => {
+                const newH = Math.max(200, Math.min(window.innerHeight - 100, startH - (ev.clientY - startY)));
+                setDockHeight(newH);
+              };
+              const onUp = () => {
+                window.removeEventListener('mousemove', onMove);
+                window.removeEventListener('mouseup', onUp);
+                if (typeof window !== 'undefined') localStorage.setItem('forge.termDockHeight', String(dockHeight));
+              };
+              window.addEventListener('mousemove', onMove);
+              window.addEventListener('mouseup', onUp);
+            }}
+          />
+          <div className="grid gap-1 p-1 flex-1 min-h-0" style={{ gridTemplateColumns: `repeat(${Math.min(floatingTerminals.length, dockColumns)}, minmax(0, 1fr))` }}>
+            {floatingTerminals.map(ft => (
+              <FloatingTerminal
+                key={ft.agentId}
+                agentLabel={ft.label}
+                agentIcon={ft.icon}
+                projectPath={projectPath}
+                agentCliId={ft.cliId}
+                cliCmd={ft.cliCmd}
+                cliType={ft.cliType}
+                workDir={ft.workDir}
+                preferredSessionName={ft.sessionName}
+                existingSession={ft.tmuxSession}
+                resumeMode={ft.resumeMode}
+                resumeSessionId={ft.resumeSessionId}
+                profileEnv={ft.profileEnv}
+                isPrimary={ft.isPrimary}
+                skipPermissions={ft.skipPermissions}
+                persistentSession={ft.persistentSession}
+                boundSessionId={ft.boundSessionId}
+                docked
+                onSessionReady={(name) => {
+                  if (workspaceId) wsApi(workspaceId, 'set_tmux_session', { agentId: ft.agentId, sessionName: name });
+                  setFloatingTerminals(prev => prev.map(t => t.agentId === ft.agentId ? { ...t, tmuxSession: name } : t));
+                }}
+                onClose={(killSession) => {
+                  setFloatingTerminals(prev => prev.filter(t => t.agentId !== ft.agentId));
+                  if (workspaceId) wsApi(workspaceId, 'close_terminal', { agentId: ft.agentId, kill: killSession });
+                }}
+              />
+            ))}
+          </div>
+        </div>
+      )}
+
       {/* User input request from agent (via bus) */}
       {userInputRequest && workspaceId && (
         <RunPromptDialog

package/lib/usage-scanner.ts

@@ -180,10 +180,10 @@ export function queryUsage(opts: {
   source?: string;
   model?: string;
 }): {
-  total: { input: number; output: number; cost: number; sessions: number; messages: number };
+  total: { input: number; output: number; cacheRead: number; cacheCreate: number; cost: number; sessions: number; messages: number };
   byProject: { name: string; input: number; output: number; cost: number; sessions: number }[];
   byModel: { model: string; input: number; output: number; cost: number; messages: number }[];
-  byDay: { date: string; input: number; output: number; cost: number }[];
+  byDay: { date: string; input: number; output: number; cacheRead: number; cacheCreate: number; cost: number; messages: number }[];
   bySource: { source: string; input: number; output: number; cost: number; messages: number }[];
 } {
   let where = '1=1';
@@ -202,6 +202,7 @@ export function queryUsage(opts: {
 
   const totalRow = db().prepare(`
     SELECT COALESCE(SUM(input_tokens), 0) as input, COALESCE(SUM(output_tokens), 0) as output,
+           COALESCE(SUM(cache_read_tokens), 0) as cacheRead, COALESCE(SUM(cache_create_tokens), 0) as cacheCreate,
            COALESCE(SUM(cost_usd), 0) as cost, COUNT(DISTINCT session_id) as sessions,
            COALESCE(SUM(message_count), 0) as messages
     FROM token_usage WHERE ${where}
@@ -226,11 +227,15 @@ export function queryUsage(opts: {
   }));
 
   const byDay = (db().prepare(`
-    SELECT day as date, SUM(input_tokens) as input, SUM(output_tokens) as output, SUM(cost_usd) as cost
+    SELECT day as date, SUM(input_tokens) as input, SUM(output_tokens) as output,
+           SUM(cache_read_tokens) as cacheRead, SUM(cache_create_tokens) as cacheCreate,
+           SUM(cost_usd) as cost, SUM(message_count) as messages
     FROM token_usage WHERE ${where} AND day != 'unknown'
     GROUP BY day ORDER BY day DESC LIMIT 30
   `).all(...params) as any[]).map(r => ({
-    date: r.date, input: r.input, output: r.output, cost: +r.cost.toFixed(4),
+    date: r.date, input: r.input, output: r.output,
+    cacheRead: r.cacheRead || 0, cacheCreate: r.cacheCreate || 0,
+    cost: +r.cost.toFixed(4), messages: r.messages || 0,
   }));
 
   const bySource = (db().prepare(`
@@ -243,7 +248,11 @@ export function queryUsage(opts: {
   }));
 
   return {
-    total: { input: totalRow.input, output: totalRow.output, cost: +totalRow.cost.toFixed(4), sessions: totalRow.sessions, messages: totalRow.messages },
+    total: {
+      input: totalRow.input, output: totalRow.output,
+      cacheRead: totalRow.cacheRead || 0, cacheCreate: totalRow.cacheCreate || 0,
+      cost: +totalRow.cost.toFixed(4), sessions: totalRow.sessions, messages: totalRow.messages,
+    },
     byProject, byModel, byDay, bySource,
   };
 }

package/lib/workspace/orchestrator.ts

@@ -96,6 +96,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
   private reconcileTick = 0; // counts health check ticks for 60s reconcile
   private _topoCache: WorkspaceTopo | null = null; // cached workspace topology
   private roleInjectState = new Map<string, { lastInjectAt: number; msgsSinceInject: number }>(); // per-agent role reminder tracking
+  private nodePositions: Record<string, { x: number; y: number }> = {}; // persisted smith positions in ReactFlow graph
 
   /** Emit a log event (auto-persisted via constructor listener) */
   emitLog(agentId: string, entry: any): void {
@@ -1175,18 +1176,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
         entry.worker = null;
       }
 
-      // 2b. For persistent sessions: send /clear to reset Claude's context if user is attached.
-      // This is a Claude Code slash command — no LLM call, just a local context reset.
-      if (entry.state.tmuxSession && entry.config.role?.trim()) {
-        let isAttached = false;
-        try {
-          const info = execSync(`tmux display-message -t "${entry.state.tmuxSession}" -p "#{session_attached}" 2>/dev/null`, { timeout: 3000, encoding: 'utf-8' }).trim();
-          isAttached = info !== '0';
-        } catch {}
-        if (isAttached) {
-          try { this.injectIntoSession(id, '/clear'); } catch {}
-        }
-      }
+      // Do NOT send /clear — preserves user's conversation context in attached terminals
       this.roleInjectState.delete(id);
 
       // 3. Kill tmux session (skip if user is attached to it)
@@ -1858,6 +1848,17 @@ export class WorkspaceOrchestrator extends EventEmitter {
     return this.bus.getLog();
   }
 
+  // ─── Node positions (ReactFlow layout) ─────────────────
+
+  getNodePositions(): Record<string, { x: number; y: number }> {
+    return { ...this.nodePositions };
+  }
+
+  setNodePositions(positions: Record<string, { x: number; y: number }>): void {
+    this.nodePositions = { ...this.nodePositions, ...positions };
+    this.saveNow();
+  }
+
   // ─── State Snapshot (for persistence) ──────────────────
 
   /** Get full workspace state for auto-save */
@@ -1868,7 +1869,7 @@ export class WorkspaceOrchestrator extends EventEmitter {
       projectName: this.projectName,
       agents: Array.from(this.agents.values()).map(e => e.config),
       agentStates: this.getAllAgentStates(),
-      nodePositions: {},
+      nodePositions: this.nodePositions,
       busLog: [...this.bus.getLog()],
       busOutbox: this.bus.getAllOutbox(),
       createdAt: this.createdAt,
@@ -1896,7 +1897,9 @@ export class WorkspaceOrchestrator extends EventEmitter {
     agentStates: Record<string, AgentState>;
     busLog: BusMessage[];
     busOutbox?: Record<string, BusMessage[]>;
+    nodePositions?: Record<string, { x: number; y: number }>;
   }): void {
+    if (data.nodePositions) this.nodePositions = { ...data.nodePositions };
     this.agents.clear();
     this.daemonActive = false; // Reset daemon — user must click Start Daemon again after restart
     for (const config of data.agents) {

package/lib/workspace/presets.ts

@@ -22,6 +22,43 @@ import type { WorkspaceAgentConfig } from './types';
 
 type PresetTemplate = Omit<WorkspaceAgentConfig, 'id'>;
 
+/**
+ * Shared decision rule for all smiths: when to use request documents
+ * vs inbox messages. This is the most common source of confusion.
+ */
+const REQUEST_VS_INBOX_RULE = `## Rule: Request vs Inbox
+
+Use **request document** (create_request / claim_request / update_response) when:
+- Delegating substantive work to another smith (implement feature, write tests, do review)
+- Work has concrete deliverables and acceptance criteria
+- Work should flow through a pipeline (engineer → qa → reviewer)
+- The task needs to be tracked, claimed, and its status visible to everyone
+
+Use **inbox message** (send_message) when:
+- Asking a clarifying question ("what format should X be?")
+- Quick status update ("I'm starting on this")
+- Reporting a bug back to upstream (after review fails)
+- Coordinating without a concrete deliverable
+
+**Decision tree when user or another smith asks you to coordinate work:**
+\`\`\`
+Is it substantive implementation/testing/review work with clear acceptance criteria?
+├─ YES → create_request (then notify via inbox if needed)
+└─ NO  → send_message only
+
+Is it a question or quick coordination (no deliverable)?
+├─ YES → send_message only
+└─ NO  → create_request
+
+Am I being asked to do work that would result in code/tests/docs changes?
+├─ YES and I'm executing it → claim_request if one exists, or tell user to create one
+└─ NO → just respond via inbox
+\`\`\`
+
+**When unsure, prefer create_request** — having a tracked artifact beats losing context in chat.
+`;
+
+
 export const AGENT_PRESETS: Record<string, PresetTemplate> = {
   pm: {
     label: 'PM',
@@ -162,7 +199,9 @@ IF request stuck open (no one claimed):
 - Do NOT write code — your output is request documents only
 - Each acceptance_criterion must be verifiable by QA
 - Group related requests in a batch for tracking
-- Downstream agents are auto-notified via DAG when you create requests`,
+- Downstream agents are auto-notified via DAG when you create requests
+
+${REQUEST_VS_INBOX_RULE}`,
     backend: 'cli',
     agentId: 'claude',
     dependsOn: [],
@@ -241,7 +280,9 @@ IF you encounter a blocking issue (unclear requirement, impossible constraint):
 - ALWAYS update_response when done — triggers downstream pipeline
 - Only implement what the request asks — don't scope-creep
 - Architecture docs are versioned — never overwrite
-- Existing working code stays unless request explicitly requires changes`,
+- Existing working code stays unless request explicitly requires changes
+
+${REQUEST_VS_INBOX_RULE}`,
     backend: 'cli',
     agentId: 'claude',
     dependsOn: [],
@@ -331,7 +372,9 @@ IF result = "failed":
 - Do NOT fix bugs — only report them
 - Each test must trace back to an acceptance_criterion
 - One consolidated message max — never spam Engineers
-- Never send messages during planning/writing — only after execution`,
+- Never send messages during planning/writing — only after execution
+
+${REQUEST_VS_INBOX_RULE}`,
     backend: 'cli',
     agentId: 'claude',
     dependsOn: [],
@@ -436,7 +479,9 @@ IF result = "rejected":
 - Review ONLY files_changed from the request, not the entire codebase
 - Actionable feedback: not "this is bad" but "change X to Y because Z"
 - One consolidated message max per verdict
-- MINOR findings go in report only — never message about style`,
+- MINOR findings go in report only — never message about style
+
+${REQUEST_VS_INBOX_RULE}`,
     backend: 'cli',
     agentId: 'claude',
     dependsOn: [],
@@ -549,7 +594,9 @@ IF multiple Engineers exist and request unclaimed:
 - Every delegated task MUST go through request documents (create_request)
 - Each request needs concrete acceptance_criteria that QA can verify
 - Do NOT duplicate work an active agent is already doing — check status first
-- When covering a gap, be thorough — don't half-do it just because it's not your "main" role`,
+- When covering a gap, be thorough — don't half-do it just because it's not your "main" role
+
+${REQUEST_VS_INBOX_RULE}`,
     backend: 'cli',
     agentId: 'claude',
     dependsOn: [],

package/lib/workspace-standalone.ts

@@ -58,7 +58,11 @@ function loadOrchestrator(id: string): WorkspaceOrchestrator {
       agentStates: state.agentStates,
       busLog: state.busLog,
       busOutbox: state.busOutbox,
+      nodePositions: state.nodePositions,
     });
+  } else if (state.nodePositions) {
+    // Load positions even when no agents yet (rare, but safe)
+    orch.loadSnapshot({ agents: [], agentStates: {}, busLog: [], nodePositions: state.nodePositions });
   }
 
   // Wire up SSE broadcasting
@@ -190,6 +194,15 @@ async function handleAgentsPost(id: string, body: any, res: ServerResponse): Pro
           return jsonError(res, err.message);
         }
       }
+      case 'set_positions': {
+        const positions = body.positions as Record<string, { x: number; y: number }> | undefined;
+        if (!positions) return jsonError(res, 'positions required');
+        orch.setNodePositions(positions);
+        return json(res, { ok: true });
+      }
+      case 'get_positions': {
+        return json(res, { positions: orch.getNodePositions() });
+      }
       case 'agent_done': {
         // Called by Claude Code Stop hook — agent finished a turn
         if (!agentId) return jsonError(res, 'agentId required');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aion0/forge",
-  "version": "0.5.29",
+  "version": "0.5.31",
   "description": "Unified AI workflow platform — multi-model task orchestration, persistent sessions, web terminal, remote access",
   "type": "module",
   "scripts": {