@aion0/forge 0.5.7 → 0.5.8

package/lib/claude-sessions.ts

@@ -53,36 +53,11 @@ export function listClaudeSessions(projectName: string): ClaudeSessionInfo[] {
   const dir = getClaudeDirForProject(projectName);
   if (!dir) return [];
 
-  // Try reading sessions-index.json first
-  const indexPath = join(dir, 'sessions-index.json');
-  if (existsSync(indexPath)) {
-    try {
-      const index = JSON.parse(readFileSync(indexPath, 'utf-8'));
-      const sessions: ClaudeSessionInfo[] = (index.entries || []).map((e: any) => ({
-        sessionId: e.sessionId,
-        summary: e.summary,
-        firstPrompt: e.firstPrompt,
-        messageCount: e.messageCount,
-        created: e.created,
-        modified: e.modified,
-        gitBranch: e.gitBranch,
-        fileSize: 0,
-      }));
-
-      // Enrich with file size
-      for (const s of sessions) {
-        const fp = join(dir, `${s.sessionId}.jsonl`);
-        try { s.fileSize = statSync(fp).size; } catch {}
-      }
-
-      return sessions.sort((a, b) => (b.modified || '').localeCompare(a.modified || ''));
-    } catch {}
-  }
-
-  // Fallback: scan for .jsonl files
+  // Scan .jsonl files on disk (authoritative source)
+  let diskSessions: ClaudeSessionInfo[] = [];
   try {
     const files = readdirSync(dir).filter(f => f.endsWith('.jsonl'));
-    return files.map(f => {
+    diskSessions = files.map(f => {
       const sessionId = f.replace('.jsonl', '');
       const fp = join(dir, f);
       const stat = statSync(fp);
@@ -96,6 +71,29 @@ export function listClaudeSessions(projectName: string): ClaudeSessionInfo[] {
   } catch {
     return [];
   }
+
+  // Enrich with metadata from sessions-index.json if available
+  const indexPath = join(dir, 'sessions-index.json');
+  if (existsSync(indexPath)) {
+    try {
+      const index = JSON.parse(readFileSync(indexPath, 'utf-8'));
+      const indexMap = new Map<string, any>();
+      for (const e of (index.entries || [])) {
+        if (e.sessionId) indexMap.set(e.sessionId, e);
+      }
+      for (const s of diskSessions) {
+        const meta = indexMap.get(s.sessionId);
+        if (meta) {
+          s.summary = meta.summary;
+          s.firstPrompt = meta.firstPrompt;
+          s.messageCount = meta.messageCount;
+          s.gitBranch = meta.gitBranch;
+        }
+      }
+    } catch {}
+  }
+
+  return diskSessions;
 }
 
 /**

package/lib/forge-mcp-server.ts

@@ -0,0 +1,389 @@
+/**
+ * Forge MCP Server — agent communication bus via Model Context Protocol.
+ *
+ * Each Claude Code session connects with context baked into the SSE URL:
+ *   http://localhost:8406/sse?workspaceId=xxx&agentId=yyy
+ *
+ * The agent doesn't need to know IDs. It just calls:
+ *   send_message(to: "Reviewer", content: "fixed the bug")
+ *   get_inbox()
+ *   get_status()
+ *
+ * Forge resolves everything from the connection context.
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { z } from 'zod';
+import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
+
+// Lazy imports to avoid circular deps (workspace modules)
+let _getOrchestrator: ((workspaceId: string) => any) | null = null;
+
+export function setOrchestratorResolver(fn: (id: string) => any): void {
+  _getOrchestrator = fn;
+}
+
+function getOrch(workspaceId: string): any {
+  if (!_getOrchestrator) throw new Error('Orchestrator resolver not set');
+  return _getOrchestrator(workspaceId);
+}
+
+// Per-session context (resolved from SSE URL + orchestrator topo)
+interface SessionContext {
+  workspaceId: string;
+  agentId: string; // resolved dynamically, may be empty for non-agent terminals
+}
+const sessionContexts = new Map<string, SessionContext>();
+
+/** Resolve agentId from orchestrator's agent-tmux mapping */
+function resolveAgentFromOrch(workspaceId: string): string {
+  // For now, default to primary agent. Future: resolve from tmux session → agent map
+  try {
+    const orch = getOrch(workspaceId);
+    const primary = orch.getPrimaryAgent();
+    return primary?.config?.id || '';
+  } catch { return ''; }
+}
+
+// ─── MCP Server Definition ──────────────────────────────
+
+function createForgeMcpServer(sessionId: string): McpServer {
+  const server = new McpServer({
+    name: 'forge',
+    version: '1.0.0',
+  });
+
+  // Helper: get context for this session
+  const ctx = () => sessionContexts.get(sessionId) || { workspaceId: '', agentId: '' };
+
+  // ── send_message ──────────────────────────
+  server.tool(
+    'send_message',
+    'Send a message to another agent in the workspace',
+    {
+      to: z.string().describe('Target agent — name like "Reviewer", or description like "the one who does testing"'),
+      content: z.string().describe('Message content'),
+      action: z.string().optional().describe('Message type: fix_request, update_notify, question, review, info_request'),
+    },
+    async (params) => {
+      const { to, content, action = 'update_notify' } = params;
+      const { workspaceId, agentId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context.' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const snapshot = orch.getSnapshot();
+        const candidates = snapshot.agents.filter((a: any) => a.type !== 'input' && a.id !== agentId);
+
+        // Match: exact label > label contains > role contains
+        const toLower = to.toLowerCase();
+        let target = candidates.find((a: any) => a.label.toLowerCase() === toLower);
+        if (!target) target = candidates.find((a: any) => a.label.toLowerCase().includes(toLower));
+        if (!target) target = candidates.find((a: any) => (a.role || '').toLowerCase().includes(toLower));
+
+        if (!target) {
+          const available = candidates.map((a: any) => `${a.label} (${(a.role || '').slice(0, 50)})`).join(', ');
+          return { content: [{ type: 'text', text: `No agent matches "${to}". Available: ${available}` }] };
+        }
+
+        orch.getBus().send(agentId, target.id, 'notify', { action, content });
+        return { content: [{ type: 'text', text: `Message sent to ${target.label}` }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ── get_inbox ─────────────────────────────
+  server.tool(
+    'get_inbox',
+    'Check inbox messages from other agents',
+    {},
+    async () => {
+      const { workspaceId, agentId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const messages = orch.getBus().getLog()
+          .filter((m: any) => m.to === agentId && m.type !== 'ack')
+          .slice(-20);
+
+        if (messages.length === 0) {
+          return { content: [{ type: 'text', text: 'No messages in inbox.' }] };
+        }
+
+        const snapshot = orch.getSnapshot();
+        const getLabel = (id: string) => snapshot.agents.find((a: any) => a.id === id)?.label || id;
+
+        const formatted = messages.map((m: any) =>
+          `[${m.status}] From ${getLabel(m.from)}: ${m.payload?.content || m.payload?.action || '(no content)'} (${m.id.slice(0, 8)})`
+        ).join('\n');
+
+        return { content: [{ type: 'text', text: formatted }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ── mark_message_done ─────────────────────
+  server.tool(
+    'mark_message_done',
+    'Mark an inbox message as done after handling it',
+    {
+      message_id: z.string().describe('Message ID (first 8 chars or full UUID)'),
+    },
+    async (params) => {
+      const { workspaceId, agentId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const msg = orch.getBus().getLog().find((m: any) =>
+          (m.id === params.message_id || m.id.startsWith(params.message_id)) && m.to === agentId
+        );
+        if (!msg) return { content: [{ type: 'text', text: 'Message not found' }] };
+
+        msg.status = 'done';
+        return { content: [{ type: 'text', text: `Message ${params.message_id} marked as done` }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ── get_status ────────────────────────────
+  server.tool(
+    'get_status',
+    'Get status of all agents in the workspace',
+    {},
+    async () => {
+      const { workspaceId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const snapshot = orch.getSnapshot();
+        const states = orch.getAllAgentStates();
+
+        const lines = snapshot.agents
+          .filter((a: any) => a.type !== 'input')
+          .map((a: any) => {
+            const s = states[a.id];
+            const smith = s?.smithStatus || 'down';
+            const task = s?.taskStatus || 'idle';
+            const icon = smith === 'active' ? (task === 'running' ? '🔵' : task === 'done' ? '✅' : task === 'failed' ? '🔴' : '🟢') : '⬚';
+            return `${icon} ${a.label}: smith=${smith} task=${task}${s?.error ? ` error=${s.error}` : ''}`;
+          });
+
+        return { content: [{ type: 'text', text: lines.join('\n') || 'No agents configured.' }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ── get_agents ────────────────────────────
+  server.tool(
+    'get_agents',
+    'Get all agents in the workspace with their roles and relationships. Use this to understand who does what before sending messages.',
+    {},
+    async () => {
+      const { workspaceId, agentId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const snapshot = orch.getSnapshot();
+
+        const agents = snapshot.agents
+          .filter((a: any) => a.type !== 'input')
+          .map((a: any) => {
+            const deps = a.dependsOn
+              .map((depId: string) => snapshot.agents.find((d: any) => d.id === depId)?.label || depId)
+              .join(', ');
+            const isMe = a.id === agentId;
+            return [
+              `${a.icon} ${a.label}${isMe ? ' (you)' : ''}${a.primary ? ' [PRIMARY]' : ''}`,
+              `  Role: ${a.role || '(no role defined)'}`,
+              deps ? `  Depends on: ${deps}` : null,
+              a.workDir && a.workDir !== './' ? `  Work dir: ${a.workDir}` : null,
+            ].filter(Boolean).join('\n');
+          });
+
+        return { content: [{ type: 'text', text: agents.join('\n\n') || 'No agents configured.' }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ── sync_progress ─────────────────────────
+  server.tool(
+    'sync_progress',
+    'Report your work progress to the workspace (what you did, files changed)',
+    {
+      summary: z.string().describe('Brief summary of what you accomplished'),
+      files: z.array(z.string()).optional().describe('List of files changed'),
+    },
+    async (params) => {
+      const { workspaceId, agentId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const entry = orch.getSnapshot().agents.find((a: any) => a.id === agentId);
+        if (!entry) return { content: [{ type: 'text', text: 'Agent not found in workspace' }] };
+
+        orch.completeManualAgent(agentId, params.files || []);
+
+        return { content: [{ type: 'text', text: `Progress synced: ${params.summary}` }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  // ── check_outbox ──────────────────────────
+  server.tool(
+    'check_outbox',
+    'Check status of messages you sent to other agents. See if they replied or completed.',
+    {},
+    async () => {
+      const { workspaceId, agentId } = ctx();
+      if (!workspaceId) return { content: [{ type: 'text', text: 'Error: No workspace context' }] };
+
+      try {
+        const orch = getOrch(workspaceId);
+        const snapshot = orch.getSnapshot();
+        const getLabel = (id: string) => snapshot.agents.find((a: any) => a.id === id)?.label || id;
+
+        // Messages sent BY this agent
+        const sent = orch.getBus().getLog()
+          .filter((m: any) => m.from === agentId && m.type !== 'ack')
+          .slice(-20);
+
+        if (sent.length === 0) {
+          return { content: [{ type: 'text', text: 'No messages sent.' }] };
+        }
+
+        // Check for replies
+        const formatted = sent.map((m: any) => {
+          const targetLabel = getLabel(m.to);
+          const replies = orch.getBus().getLog().filter((r: any) =>
+            r.from === m.to && r.to === agentId && r.timestamp > m.timestamp && r.type !== 'ack'
+          );
+          const replyInfo = replies.length > 0
+            ? `replied: ${replies[replies.length - 1].payload?.content?.slice(0, 100) || '(no content)'}`
+            : 'no reply yet';
+          return `→ ${targetLabel}: [${m.status}] ${(m.payload?.content || '').slice(0, 60)} | ${replyInfo}`;
+        }).join('\n');
+
+        return { content: [{ type: 'text', text: formatted }] };
+      } catch (err: any) {
+        return { content: [{ type: 'text', text: `Error: ${err.message}` }] };
+      }
+    }
+  );
+
+  return server;
+}
+
+// ─── HTTP Server with SSE Transport ─────────────────────
+
+let mcpHttpServer: ReturnType<typeof createServer> | null = null;
+const transports = new Map<string, SSEServerTransport>();
+
+export async function startMcpServer(port: number): Promise<void> {
+  mcpHttpServer = createServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const url = new URL(req.url || '/', `http://localhost:${port}`);
+
+    // CORS
+    res.setHeader('Access-Control-Allow-Origin', '*');
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
+
+    // SSE endpoint — each connection gets its own MCP server instance
+    if (url.pathname === '/sse' && req.method === 'GET') {
+      const transport = new SSEServerTransport('/message', res);
+      const sessionId = transport.sessionId;
+      transports.set(sessionId, transport);
+
+      // Extract workspace context from URL params
+      const workspaceId = url.searchParams.get('workspaceId') || '';
+      const agentId = url.searchParams.get('agentId') || (workspaceId ? resolveAgentFromOrch(workspaceId) : '');
+      sessionContexts.set(sessionId, { workspaceId, agentId });
+
+      transport.onclose = () => {
+        transports.delete(sessionId);
+        sessionContexts.delete(sessionId);
+      };
+
+      // Each session gets its own MCP server with context
+      const server = createForgeMcpServer(sessionId);
+      await server.connect(transport);
+      const agentLabel = workspaceId ? (getOrch(workspaceId)?.getSnapshot()?.agents?.find((a: any) => a.id === agentId)?.label || agentId) : 'unknown';
+      console.log(`[forge-mcp] Client connected: ${agentLabel} (ws=${workspaceId.slice(0, 8)}, session=${sessionId})`);
+      return;
+    }
+
+    // Message endpoint — route by sessionId query param
+    if (url.pathname === '/message' && req.method === 'POST') {
+      const sessionId = url.searchParams.get('sessionId');
+      if (!sessionId) {
+        res.writeHead(400);
+        res.end('Missing sessionId parameter');
+        return;
+      }
+
+      const transport = transports.get(sessionId);
+      if (!transport) {
+        res.writeHead(404);
+        res.end('Session not found');
+        return;
+      }
+
+      // Read body and pass to transport
+      const body: Buffer[] = [];
+      req.on('data', (chunk: Buffer) => body.push(chunk));
+      req.on('end', async () => {
+        try {
+          const parsed = JSON.parse(Buffer.concat(body).toString());
+          await transport.handlePostMessage(req, res, parsed);
+        } catch (err: any) {
+          if (!res.headersSent) { res.writeHead(400); res.end('Invalid JSON'); }
+        }
+      });
+      return;
+    }
+
+    // Health check
+    if (url.pathname === '/health') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, sessions: transports.size }));
+      return;
+    }
+
+    res.writeHead(404);
+    res.end('Not found');
+  });
+
+  mcpHttpServer.listen(port, () => {
+    console.log(`[forge-mcp] MCP Server running on http://localhost:${port}`);
+  });
+}
+
+export function stopMcpServer(): void {
+  if (mcpHttpServer) {
+    mcpHttpServer.close();
+    mcpHttpServer = null;
+    transports.clear();
+  }
+}
+
+export function getMcpPort(): number {
+  return Number(process.env.MCP_PORT) || 8406;
+}

package/lib/forge-skills/forge-inbox.md

@@ -1,5 +1,5 @@
 ---
-description: Check and manage messages from other Forge Workspace agents (QA reports, review feedback, PM requests)
+description: "[FALLBACK — only use if MCP get_inbox tool is NOT available] Check messages from other Forge Workspace agents via HTTP API"
 ---
 
 # Forge Inbox
@@ -12,26 +12,27 @@ Check for messages from other agents and manage their status.
 
 ## How to use
 
-IMPORTANT: Do NOT check environment variables. Just run the commands — they auto-discover the workspace.
+### Option 1: MCP Tools (preferred)
+If MCP tools are available, use them directly:
+- `get_inbox()` — check messages
+- `mark_message_done(message_id: "ID")` — mark as done
+- `check_outbox()` — check messages you sent
 
-Step 1 — Get workspace ID:
-```bash
-curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
-```
+### Option 2: HTTP API (fallback)
 
-Step 2 — Check inbox (replace WORKSPACE_ID):
+Step 1 — Get workspace ID (env var first, then API fallback):
 ```bash
-curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"inbox","agentId":"'"$FORGE_AGENT_ID"'"}'
+WS_ID="${FORGE_WORKSPACE_ID:-$(curl -s "http://localhost:8405/resolve?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('workspaceId',''))" 2>/dev/null)}"
 ```
 
-## Mark message as done
+Step 2 — Check inbox:
 ```bash
-curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"message_done","agentId":"'"$FORGE_AGENT_ID"'","messageId":"MESSAGE_ID"}'
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"inbox","agentId":"'"$FORGE_AGENT_ID"'"}'
 ```
 
-## Mark message as failed
+## Mark message as done
 ```bash
-curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"message_failed","agentId":"'"$FORGE_AGENT_ID"'","messageId":"MESSAGE_ID"}'
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"message_done","agentId":"'"$FORGE_AGENT_ID"'","messageId":"MESSAGE_ID"}'
 ```
 
 After handling a message, always mark it as done or failed.

package/lib/forge-skills/forge-send.md

@@ -1,5 +1,5 @@
 ---
-description: Send a message to another Forge Workspace agent immediately via API (notify QA of a fix, ask PM a question, etc.)
+description: "[FALLBACK — only use if MCP send_message tool is NOT available] Send a message to another Forge Workspace agent via HTTP API"
 ---
 
 # Forge Send
@@ -17,16 +17,23 @@ Send a message to another agent in the Forge Workspace.
 
 ## How to send
 
-IMPORTANT: Do NOT check environment variables first. Just run the command below — it auto-discovers everything.
+### Option 1: MCP Tool (preferred)
+If the `send_message` tool is available, use it directly:
+```
+send_message(to: "TARGET_LABEL", content: "YOUR MESSAGE", action: "ACTION")
+```
+
+### Option 2: HTTP API (fallback if MCP not available)
 
-Step 1 — Get workspace ID:
+Step 1 — Get workspace ID (env var first, then API fallback):
 ```bash
-curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+WS_ID="${FORGE_WORKSPACE_ID:-$(curl -s "http://localhost:8405/resolve?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('workspaceId',''))" 2>/dev/null)}"
+echo "$WS_ID"
 ```
 
-Step 2 — Send message (replace WORKSPACE_ID with result from step 1):
+Step 2 — Send message:
 ```bash
-curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"send","agentId":"'"$FORGE_AGENT_ID"'","to":"TARGET_LABEL","msgAction":"ACTION","content":"YOUR MESSAGE"}'
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"send","agentId":"'"$FORGE_AGENT_ID"'","to":"TARGET_LABEL","msgAction":"ACTION","content":"YOUR MESSAGE"}'
 ```
 
 Replace:

package/lib/forge-skills/forge-status.md

@@ -1,5 +1,5 @@
 ---
-description: Check the status of all agents in the Forge Workspace (who is running, done, waiting)
+description: "[FALLBACK — only use if MCP get_status tool is NOT available] Check agent statuses via HTTP API"
 ---
 
 # Forge Status
@@ -12,21 +12,21 @@ Check the current status of all agents in the Forge Workspace.
 
 ## How to check
 
-IMPORTANT: Do NOT check environment variables. Just run the commands.
+### Option 1: MCP Tools (preferred)
+If MCP tools are available:
+- `get_status()` — all agent statuses
+- `get_agents()` — agent details (roles, dependencies)
 
-Step 1 — Get workspace ID:
+### Option 2: HTTP API (fallback)
+
+Step 1 — Get workspace ID (env var first, then API fallback):
 ```bash
-curl -s "http://localhost:8403/api/workspace?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))"
+WS_ID="${FORGE_WORKSPACE_ID:-$(curl -s "http://localhost:8405/resolve?projectPath=$(pwd)" | python3 -c "import sys,json; print(json.load(sys.stdin).get('workspaceId',''))" 2>/dev/null)}"
 ```
 
-Step 2 — Check status (replace WORKSPACE_ID):
+Step 2 — Check status:
 ```bash
-curl -s -X POST "http://localhost:8403/api/workspace/WORKSPACE_ID/smith" -H "Content-Type: application/json" -d '{"action":"status","agentId":"'"$FORGE_AGENT_ID"'"}'
+curl -s -X POST "http://localhost:8403/api/workspace/$WS_ID/smith" -H "Content-Type: application/json" -d '{"action":"status","agentId":"'"$FORGE_AGENT_ID"'"}'
 ```
 
-Present the results as a clear status overview:
-- 🟢 active — smith is online and listening
-- 🔵 running — agent is currently executing a task
-- ✅ done — agent completed its work
-- 🔴 failed — agent encountered an error
-- ⬚ down — smith is not started
+Present the results as a clear status overview.

package/lib/project-sessions.ts

@@ -0,0 +1,48 @@
+/**
+ * Project-level fixed session binding.
+ * Stores { projectPath: sessionId } in ~/.forge/data/project-sessions.json
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataDir } from '@/src/config';
+
+function getFilePath(): string {
+  const dir = getDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return join(dir, 'project-sessions.json');
+}
+
+function loadAll(): Record<string, string> {
+  const fp = getFilePath();
+  if (!existsSync(fp)) return {};
+  try { return JSON.parse(readFileSync(fp, 'utf-8')); } catch { return {}; }
+}
+
+function saveAll(data: Record<string, string>): void {
+  writeFileSync(getFilePath(), JSON.stringify(data, null, 2));
+}
+
+/** Get the fixed session ID for a project */
+export function getFixedSession(projectPath: string): string | undefined {
+  return loadAll()[projectPath] || undefined;
+}
+
+/** Set the fixed session ID for a project */
+export function setFixedSession(projectPath: string, sessionId: string): void {
+  const data = loadAll();
+  data[projectPath] = sessionId;
+  saveAll(data);
+}
+
+/** Clear the fixed session for a project */
+export function clearFixedSession(projectPath: string): void {
+  const data = loadAll();
+  delete data[projectPath];
+  saveAll(data);
+}
+
+/** Get all bindings */
+export function getAllFixedSessions(): Record<string, string> {
+  return loadAll();
+}