@aion0/forge 0.10.47 → 0.10.48

package/RELEASE_NOTES.md

@@ -1,12 +1,12 @@
-# Forge v0.10.47
+# Forge v0.10.48
 
 Released: 2026-06-08
 
-## Changes since v0.10.46
+## Changes since v0.10.47
 
 ### Other
-- ui(header): selected tab uses accent tint, not bg-secondary shade
-- ui(header): bell for Alerts, stacked dept/name pill, +1px nav font
+- fix(proxy): drop runtime:'nodejs' — Next.js 16 errors on it
+- Implement an MCP layer for forge management (#34)
 
 
-**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.46...v0.10.47
+**Full Changelog**: https://github.com/aiwatching/forge/compare/v0.10.47...v0.10.48

package/app/api/auth/keys/[id]/route.ts

@@ -0,0 +1,16 @@
+import { NextResponse } from 'next/server';
+import { verifyAdmin } from '@/lib/password';
+import { revokeApiKey } from '@/lib/api-keys';
+
+// DELETE /api/auth/keys/:id — revoke a key; requires the admin password (in body)
+export async function DELETE(req: Request, { params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params;
+  const body = await req.json().catch(() => ({}));
+  const { adminPassword } = body as { adminPassword?: string };
+
+  if (!verifyAdmin(adminPassword || '')) {
+    return NextResponse.json({ error: 'Invalid admin password' }, { status: 403 });
+  }
+  const ok = revokeApiKey(id);
+  return NextResponse.json({ ok });
+}

package/app/api/auth/keys/route.ts

@@ -0,0 +1,36 @@
+import { NextResponse } from 'next/server';
+import { verifyAdmin, getAdminPassword } from '@/lib/password';
+import { createApiKey, listApiKeys } from '@/lib/api-keys';
+import { isAuthenticated } from '@/lib/api-auth';
+import { isValidToken } from '@/app/api/auth/verify/route';
+
+function isDev(): boolean {
+  return process.env.NODE_ENV !== 'production' || process.env.FORGE_DEV === '1';
+}
+
+/** Reads require an authenticated caller (browser session, valid key, or dev). */
+async function canRead(req: Request): Promise<boolean> {
+  return isDev() || (await isAuthenticated(req)) || isValidToken(req);
+}
+
+// GET /api/auth/keys — list keys (no secrets)
+export async function GET(req: Request) {
+  if (!(await canRead(req))) return NextResponse.json({ error: 'unauthorized' }, { status: 401 });
+  return NextResponse.json({ keys: listApiKeys(), adminConfigured: !!getAdminPassword() });
+}
+
+// POST /api/auth/keys — mint a key; requires the admin password
+export async function POST(req: Request) {
+  const body = await req.json().catch(() => ({}));
+  const { name, adminPassword } = body as { name?: string; adminPassword?: string };
+
+  if (!getAdminPassword()) {
+    return NextResponse.json({ error: 'Set an admin password first' }, { status: 400 });
+  }
+  if (!verifyAdmin(adminPassword || '')) {
+    return NextResponse.json({ error: 'Invalid admin password' }, { status: 403 });
+  }
+
+  const { key, record } = createApiKey(name || 'agent key');
+  return NextResponse.json({ key, record });
+}

package/app/api/mcp/route.ts

@@ -0,0 +1,144 @@
+/**
+ * Forge Management MCP — HTTP endpoint (Streamable HTTP transport).
+ *
+ * Hosts `createManagementMcpServer()` inside Next.js so it inherits Forge's
+ * auth middleware and the nginx reverse proxy — no new port, no new auth surface.
+ *
+ * Uses the SDK's Web-standard transport, whose handleRequest(Request) → Response
+ * fits an app-router handler directly. Stateful/session-keyed: the initialize
+ * handshake mints a session id that ties later calls together. (Stateless mode
+ * skips session validation but forbids transport reuse, so it can't hold a
+ * multi-call session.) `enableJsonResponse` gives the stdio proxy plain JSON
+ * back per request.
+ *
+ * The `forge mcp` stdio proxy (cli/mcp-proxy.ts) is the intended client: it
+ * forwards JSON-RPC frames here and carries the Mcp-Session-Id header.
+ */
+
+import { isValidToken } from '@/app/api/auth/verify/route';
+import { isAuthenticated } from '@/lib/api-auth';
+import { createManagementMcpServer } from '@/mcp/server';
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { randomUUID } from 'node:crypto';
+
+export const runtime = 'nodejs';
+
+// A live session: the SDK transport plus when we last saw traffic (for idle eviction).
+interface Session {
+  transport: WebStandardStreamableHTTPServerTransport;
+  lastSeen: number;
+}
+
+const SESSION_IDLE_MS = 30 * 60_000; // evict sessions idle longer than 30 min
+const SESSION_MAX = 256; // hard cap; evict oldest beyond this
+
+// Survive HMR / multiple route module evaluations (same pattern as the rest of Forge).
+const KEY = Symbol.for('forge-management-mcp-sessions');
+const g = globalThis as unknown as Record<symbol, Map<string, Session>>;
+if (!g[KEY]) g[KEY] = new Map();
+const sessions = g[KEY];
+
+/** A real MCP client (not the proxy) typically closes its session with DELETE,
+ *  but the stdio proxy may exit without one. Lazily reap idle/overflow sessions
+ *  so the module-global Map can't grow unbounded on a long-running server. */
+function reap(): void {
+  const now = Date.now();
+  for (const [id, s] of sessions) {
+    if (now - s.lastSeen > SESSION_IDLE_MS) {
+      try { s.transport.close(); } catch { /* best-effort */ }
+      sessions.delete(id);
+    }
+  }
+  if (sessions.size > SESSION_MAX) {
+    const oldest = [...sessions.entries()].sort((a, b) => a[1].lastSeen - b[1].lastSeen);
+    for (const [id, s] of oldest.slice(0, sessions.size - SESSION_MAX)) {
+      try { s.transport.close(); } catch { /* best-effort */ }
+      sessions.delete(id);
+    }
+  }
+}
+
+/** Returns a 401 Response if the request is not authorized, else null. */
+async function denied(req: Request): Promise<Response | null> {
+  const isDev = process.env.NODE_ENV !== 'production' || process.env.FORGE_DEV === '1';
+  if (isDev) return null;
+  // A valid API key (Bearer/x-forge-token) or validated browser session, or the
+  // legacy admin-password-minted token.
+  if ((await isAuthenticated(req)) || isValidToken(req)) return null;
+  return Response.json({ error: 'unauthorized' }, { status: 401 });
+}
+
+/** Streamable-HTTP's signal for a stale/unknown session id: the client should
+ *  discard it and re-initialize. Shaped as a JSON-RPC error so even a non-proxy
+ *  client gets a usable body, with the 404 status the spec expects. */
+function sessionNotFound(): Response {
+  return Response.json(
+    { jsonrpc: '2.0', error: { code: -32001, message: 'Session not found' }, id: null },
+    { status: 404 },
+  );
+}
+
+export async function POST(req: Request): Promise<Response> {
+  const d = await denied(req);
+  if (d) return d;
+  reap();
+
+  const sid = req.headers.get('mcp-session-id') || '';
+  if (sid) {
+    // A session id was supplied — it MUST already exist. If it doesn't (server
+    // restarted, HMR reset, idle-evicted), reject with 404 instead of silently
+    // building a fresh, uninitialized transport (which would surface a confusing
+    // 400 "Server not initialized" and leak an un-stored transport).
+    const s = sessions.get(sid);
+    if (!s) return sessionNotFound();
+    s.lastSeen = Date.now();
+    return s.transport.handleRequest(req);
+  }
+
+  // No session id → this MUST be an `initialize` request. Anything else (a stale
+  // client after a restart, a stray frame) would otherwise build a transport that
+  // onsessioninitialized never stores — a leaked connected pair surfaced as a
+  // confusing 400. Reject it with the same 404 the unknown-session path returns.
+  let initBody: any;
+  try { initBody = await req.clone().json(); } catch { initBody = null; }
+  const isInit = Array.isArray(initBody)
+    ? initBody.some((m) => m && m.method === 'initialize')
+    : !!(initBody && initBody.method === 'initialize');
+  if (!isInit) return sessionNotFound();
+
+  let transport: WebStandardStreamableHTTPServerTransport;
+  transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+    enableJsonResponse: true,
+    onsessioninitialized: (id) => { sessions.set(id, { transport, lastSeen: Date.now() }); },
+  });
+  transport.onclose = () => {
+    const id = transport.sessionId;
+    if (id) sessions.delete(id);
+  };
+  const server = createManagementMcpServer();
+  await server.connect(transport);
+  return transport.handleRequest(req);
+}
+
+export async function GET(req: Request): Promise<Response> {
+  const d = await denied(req);
+  if (d) return d;
+  reap();
+  const sid = req.headers.get('mcp-session-id') || '';
+  const s = sid ? sessions.get(sid) : undefined;
+  if (!s) return sessionNotFound();
+  s.lastSeen = Date.now();
+  return s.transport.handleRequest(req);
+}
+
+export async function DELETE(req: Request): Promise<Response> {
+  const d = await denied(req);
+  if (d) return d;
+  reap();
+  const sid = req.headers.get('mcp-session-id') || '';
+  const s = sid ? sessions.get(sid) : undefined;
+  if (!s) return sessionNotFound();
+  // handleRequest → transport.close() → onclose deletes the entry from `sessions`.
+  return s.transport.handleRequest(req);
+}

package/cli/key.ts

@@ -0,0 +1,67 @@
+/**
+ * forge key — manage API keys (service/agent credentials, incl. MCP).
+ *
+ *   forge key create [name] [--save]   mint a key
+ *   forge key list                     list keys
+ *   forge key revoke <id>              revoke a key
+ *
+ * Operates directly on the local key store (<dataDir>/api-keys.json) — running
+ * the `forge` CLI already proves local filesystem access, so no admin password is
+ * needed (the HTTP route still requires it; that's the remote/browser path). The
+ * running server picks up changes on its next request (its key cache
+ * self-invalidates on the file's mtime). Set FORGE_DATA_DIR to target a
+ * non-default instance's data dir.
+ */
+
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createApiKey, listApiKeys, revokeApiKey } from '../lib/api-keys';
+
+export async function keyCommand(args: string[]): Promise<void> {
+  const sub = args[0];
+  const positional = args.slice(1).filter((a) => !a.startsWith('--'));
+
+  if (sub === 'list') {
+    const keys = listApiKeys();
+    if (!keys.length) { console.log('No API keys. Create one: forge key create <name>'); return; }
+    for (const k of keys) {
+      const used = k.lastUsedAt ? k.lastUsedAt.slice(0, 10) : 'never';
+      console.log(`  ${k.id}  ${String(k.prefix).padEnd(20)} ${k.name}  (created ${k.createdAt?.slice(0, 10)}, last used ${used})`);
+    }
+    return;
+  }
+
+  if (sub === 'create') {
+    const name = positional[0] || 'agent key';
+    const { key } = createApiKey(name);
+    console.log(`\n✓ API key created (${name}):\n\n  ${key}\n`);
+    console.log('  Copy it now — it will not be shown again.');
+    if (args.includes('--save')) {
+      const dir = join(homedir(), '.forge');
+      mkdirSync(dir, { recursive: true });
+      const f = join(dir, 'mcp-key');
+      writeFileSync(f, key, { mode: 0o600 });
+      console.log(`  Saved to ${f} — forge mcp will read it automatically.`);
+    } else {
+      console.log('  Use it:  export FORGE_API_KEY=<key>   (or rerun with --save)');
+    }
+    return;
+  }
+
+  if (sub === 'revoke') {
+    const id = positional[0];
+    if (!id) { console.log('Usage: forge key revoke <id>'); process.exit(1); }
+    console.log(revokeApiKey(id) ? `✓ Revoked key ${id}` : `Key ${id} not found`);
+    return;
+  }
+
+  console.log(`forge key — manage API keys (service/agent credentials, incl. MCP)
+
+  forge key create [name] [--save]   Mint a key (--save writes it to ~/.forge/mcp-key)
+  forge key list                     List keys
+  forge key revoke <id>              Revoke a key
+
+  No admin password — operates on the local key store directly.
+  Set FORGE_DATA_DIR to target a non-default instance.`);
+}

package/cli/mcp-install.ts

@@ -0,0 +1,106 @@
+/**
+ * `forge mcp install` — add the Forge Management MCP to Claude Code.
+ *
+ * Mints an API key if one isn't already saved, then runs `claude mcp add` — so a
+ * user can just say "add forge management MCP" and the agent runs one command.
+ *
+ * No admin password: running the `forge` CLI already proves filesystem access to
+ * the data dir, so the key is minted directly into <dataDir>/api-keys.json. The
+ * running server picks it up on its next request (its key cache self-invalidates
+ * on the file's mtime), and the server need not even be up. (A loopback-IP check
+ * would be wrong — Forge runs behind nginx, so remote users also arrive over
+ * loopback; filesystem access is the only trustworthy local signal.)
+ *
+ * The store is getDataDir() — FORGE_DATA_DIR, else ~/.forge/data — so set
+ * FORGE_DATA_DIR to mint into a non-default instance's data dir.
+ *
+ * A --remote install can't reach the remote's data dir, so it uses a key you
+ * already hold (FORGE_API_KEY, the saved key file, or --http --header).
+ *
+ *   forge mcp install                 stdio proxy, local server
+ *   forge mcp install --http          register the HTTP transport instead
+ *   forge mcp install --scope user    available in every project
+ *   forge mcp install --remote URL    target a remote Forge (needs FORGE_API_KEY)
+ *   forge mcp install --print         print the `claude mcp add` command, don't run it
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createApiKey } from '../lib/api-keys';
+
+const opt = (args: string[], name: string): string | undefined => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const keyFile = (): string => join(homedir(), '.forge', 'mcp-key');
+
+/** A key already available from env or the Forge-owned key file, if any. */
+function savedKey(): string {
+  const env = (process.env.FORGE_API_KEY || process.env.FORGE_API_TOKEN || '').trim();
+  if (env) return env;
+  try { if (existsSync(keyFile())) return readFileSync(keyFile(), 'utf-8').trim(); } catch { /* ignore */ }
+  return '';
+}
+
+/** Return a usable key, minting one locally if none is saved.
+ *  Local mint writes <dataDir>/api-keys.json (no password, no running server).
+ *  Remote installs can't mint here, so a saved key is required. */
+function ensureKey(remote: string | undefined): string {
+  const existing = savedKey();
+  if (existing) return existing;
+  if (remote) throw new Error("remote install needs a key — set FORGE_API_KEY (mint one in the remote's Settings → API Key)");
+
+  const { key } = createApiKey('claude-code');
+  mkdirSync(join(homedir(), '.forge'), { recursive: true });
+  writeFileSync(keyFile(), key, { mode: 0o600 });
+  console.error(`[forge mcp install] minted a local API key → ${keyFile()}`);
+  return key;
+}
+
+export async function mcpInstallCommand(args: string[]): Promise<void> {
+  const name = opt(args, '--name') || 'forge';
+  const scope = opt(args, '--scope');
+  const remote = opt(args, '--remote');
+  const useHttp = args.includes('--http');
+  const printOnly = args.includes('--print');
+  const port = opt(args, '--port');
+  const base = (remote || process.env.MW_URL || `http://localhost:${port || '8403'}`).replace(/\/$/, '');
+
+  // A local mint lands in getDataDir() (FORGE_DATA_DIR or ~/.forge/data), which
+  // ignores --port/MW_URL. If those target a non-default instance, the key would
+  // go to the wrong store and silently 401 — refuse with guidance instead.
+  if (!printOnly && !remote && !savedKey() && !process.env.FORGE_DATA_DIR
+      && (process.env.MW_URL || (port && port !== '8403'))) {
+    throw new Error('targeting a non-default instance — set FORGE_DATA_DIR to its data dir so the key is minted into the store that server reads');
+  }
+
+  // --print is a dry run: don't mint anything, just show the command.
+  const key = printOnly ? savedKey() : ensureKey(remote);
+
+  const add = ['mcp', 'add'];
+  if (scope) add.push('--scope', scope);
+  if (useHttp) {
+    add.push('--transport', 'http', name, `${base}/api/mcp`);
+    if (key) add.push('--header', `Authorization: Bearer ${key}`);
+    else if (printOnly) add.push('--header', 'Authorization: Bearer forge_sk_YOUR_KEY');
+  } else {
+    // The stdio proxy reads ~/.forge/mcp-key itself; only forward MW_URL when non-default.
+    if (remote || process.env.MW_URL) add.push('--env', `MW_URL=${base}`);
+    add.push(name, '--', 'forge', 'mcp');
+  }
+
+  const pretty = `claude ${add.map((a) => (a.includes(' ') ? JSON.stringify(a) : a)).join(' ')}`;
+  if (printOnly) { console.log(pretty); return; }
+
+  const r = spawnSync('claude', add, { stdio: 'inherit' });
+  if (r.error && (r.error as NodeJS.ErrnoException).code === 'ENOENT') {
+    console.error('[forge mcp install] the `claude` CLI is not on PATH. Run this yourself:\n');
+    console.log(`  ${pretty}\n`);
+    return;
+  }
+  if (r.status && r.status !== 0) process.exit(r.status);
+  console.error(`\n[forge mcp install] added '${name}'. Run /mcp in a Claude Code session to confirm.`);
+}

package/cli/mcp-proxy.ts

@@ -0,0 +1,196 @@
+/**
+ * `forge mcp` — thin stdio↔HTTP proxy for the Forge Management MCP.
+ *
+ * THE CONTRACT (see mcp/README.md): transport-only. No database driver, no SQL,
+ * no `lib/` business imports, no secrets. It reads newline-delimited JSON-RPC
+ * frames from stdin, forwards each to the Forge server's /api/mcp endpoint over
+ * HTTP, and writes responses back to stdout. All logic lives behind the service.
+ *
+ * stdout is the protocol channel — diagnostics MUST go to stderr only, and only
+ * well-formed JSON-RPC frames are ever written to stdout (never a raw HTTP error
+ * body, which would corrupt the client's stream).
+ *
+ * Robustness (so a real client never hangs or sees garbage):
+ *  - transport failure / non-2xx → a JSON-RPC error keyed to the frame's id is
+ *    emitted, so the client's pending request resolves instead of hanging.
+ *  - a dead session (server restarted → 404) is healed transparently: the cached
+ *    `initialize` frame is replayed to mint a new session, then the failed frame
+ *    is retried once.
+ *  - on stdin EOF the session is released with a best-effort DELETE.
+ *
+ * Config (env):
+ *   MW_URL          base URL of the Forge server (default http://localhost:8403)
+ *   FORGE_API_KEY   persistent API key (sent as Authorization: Bearer). Generate
+ *                   one in Settings → API Key. Falls back to a Forge-owned
+ *                   ~/.forge/mcp-key file. Preferred over the legacy token below.
+ *   FORGE_API_TOKEN legacy admin-minted token (sent as x-forge-token). Ephemeral
+ *                   in-memory/session-scoped — mint one via POST /api/auth/verify
+ *                   with the admin password. Prefer FORGE_API_KEY.
+ *
+ * Session plumbing: the Streamable-HTTP endpoint is stateful, so this captures
+ * the Mcp-Session-Id from the initialize response and the negotiated
+ * MCP-Protocol-Version, and replays both on later requests.
+ */
+
+import { createInterface } from 'node:readline';
+import { readFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Resolve the API credential: env first, then a Forge-owned key file
+ *  (~/.forge/mcp-key). Never read from ~/.claude or other prompt infrastructure. */
+function resolveCredential(): string {
+  const env = process.env.FORGE_API_KEY || process.env.FORGE_API_TOKEN;
+  if (env) return env.trim();
+  try {
+    const f = join(homedir(), '.forge', 'mcp-key');
+    if (existsSync(f)) return readFileSync(f, 'utf-8').trim();
+  } catch { /* ignore */ }
+  return '';
+}
+
+/** Injectable IO + fetch, so the recovery logic can be tested without a real
+ *  server or stdio. Defaults wire up process.stdin/stdout/stderr and global fetch. */
+export interface ProxyDeps {
+  input?: NodeJS.ReadableStream;
+  writeOut?: (s: string) => void;
+  logErr?: (s: string) => void;
+  fetchImpl?: typeof fetch;
+}
+
+export async function mcpProxyCommand(_args: string[], deps: ProxyDeps = {}): Promise<void> {
+  const input = deps.input ?? process.stdin;
+  const out = deps.writeOut ?? ((s: string) => { process.stdout.write(s); });
+  const logErr = deps.logErr ?? ((s: string) => { process.stderr.write(s); });
+  const doFetch = deps.fetchImpl ?? fetch;
+
+  const base = (process.env.MW_URL || 'http://localhost:8403').replace(/\/$/, '');
+  const endpoint = `${base}/api/mcp`;
+  const credential = resolveCredential();
+  // forge_sk_ keys go in Authorization: Bearer; legacy admin-minted tokens stay
+  // on x-forge-token. Applied to every request.
+  const applyAuth = (headers: Record<string, string>) => {
+    if (!credential) return;
+    if (credential.startsWith('forge_sk_')) headers['authorization'] = `Bearer ${credential}`;
+    else headers['x-forge-token'] = credential;
+  };
+
+  const err = (m: string) => logErr(`[forge mcp] ${m}\n`);
+  err(`proxy → ${endpoint}`);
+
+  let sessionId = '';
+  let protocolVersion = '';
+  let initFrame = ''; // cached initialize request, for transparent session recovery
+
+  // ── stdout helpers (protocol channel) ──────────────────
+  const writeFrame = (text: string) => out(text.endsWith('\n') ? text : text + '\n');
+  const emit = (obj: unknown) => out(JSON.stringify(obj) + '\n');
+  const rpcError = (id: unknown, message: string, code = -32000) =>
+    emit({ jsonrpc: '2.0', id, error: { code, message } });
+
+  // ── HTTP helpers ───────────────────────────────────────
+  const post = (frame: string, useSession: boolean): Promise<Response> => {
+    const headers: Record<string, string> = {
+      'content-type': 'application/json',
+      accept: 'application/json, text/event-stream',
+    };
+    applyAuth(headers);
+    if (useSession && sessionId) headers['mcp-session-id'] = sessionId;
+    if (protocolVersion) headers['mcp-protocol-version'] = protocolVersion;
+    return doFetch(endpoint, { method: 'POST', headers, body: frame });
+  };
+  const adoptSession = (res: Response) => {
+    const sid = res.headers.get('mcp-session-id');
+    if (sid) sessionId = sid;
+  };
+  const learnProtocol = (text: string) => {
+    try {
+      const v = JSON.parse(text)?.result?.protocolVersion;
+      if (typeof v === 'string') protocolVersion = v;
+    } catch { /* not an initialize result — ignore */ }
+  };
+  // Never surface a raw HTTP body (could be HTML) onto the protocol channel.
+  const errorMessage = (status: number, text: string): string => {
+    try {
+      const m = JSON.parse(text)?.error?.message;
+      if (typeof m === 'string') return m;
+    } catch { /* not JSON */ }
+    return `Forge server returned HTTP ${status}`;
+  };
+  const sessionDead = (status: number, text: string) =>
+    status === 404 || (status === 400 && /not initialized|session not found/i.test(text));
+
+  /** Replay initialize on a fresh session, then retry the failed frame once.
+   *  Always "handles" the frame (writes output or a JSON-RPC error). */
+  async function recover(frame: string, id: unknown, hasId: boolean): Promise<void> {
+    err('session expired — re-initializing');
+    sessionId = '';
+    protocolVersion = '';
+    let initRes: Response;
+    try { initRes = await post(initFrame, false); }
+    catch (e) { if (hasId) rpcError(id, `forge mcp: re-init failed: ${(e as Error).message}`); return; }
+    adoptSession(initRes);
+    if (!initRes.ok) { if (hasId) rpcError(id, 'forge mcp: re-initialization failed'); return; }
+    learnProtocol(await initRes.text());
+    try { await post('{"jsonrpc":"2.0","method":"notifications/initialized"}', true); } catch { /* best-effort */ }
+
+    let retry: Response;
+    try { retry = await post(frame, true); }
+    catch (e) { if (hasId) rpcError(id, `forge mcp: ${(e as Error).message}`); return; }
+    adoptSession(retry);
+    if (retry.status === 202) return;
+    const rtext = await retry.text();
+    if (retry.ok) { if (rtext) writeFrame(rtext); return; }
+    if (hasId) rpcError(id, errorMessage(retry.status, rtext));
+  }
+
+  // ── main loop ──────────────────────────────────────────
+  const rl = createInterface({ input, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    const frame = line.trim();
+    if (!frame) continue;
+
+    let msg: { id?: unknown; method?: string } | undefined;
+    try { msg = JSON.parse(frame); }
+    catch { err('dropping non-JSON stdin line'); continue; }
+    const hasId = !!msg && 'id' in msg && msg.id !== null && msg.id !== undefined;
+    const id = hasId ? msg!.id : undefined;
+    if (msg?.method === 'initialize') initFrame = frame;
+
+    let res: Response;
+    try { res = await post(frame, true); }
+    catch (e) {
+      err(`request failed: ${(e as Error).message}`);
+      if (hasId) rpcError(id, `forge mcp: ${(e as Error).message}`);
+      continue;
+    }
+
+    adoptSession(res);
+    if (res.status === 202) continue; // notification/response accepted, no body
+
+    const text = await res.text();
+    if (res.ok) {
+      learnProtocol(text);
+      if (text) writeFrame(text);
+      continue;
+    }
+
+    if (sessionDead(res.status, text) && initFrame && msg?.method !== 'initialize') {
+      await recover(frame, id, hasId);
+      continue;
+    }
+    if (hasId) rpcError(id, errorMessage(res.status, text));
+    else err(`server ${res.status} on notification (dropped)`);
+  }
+
+  // stdin closed → release the server-side session (best-effort).
+  if (sessionId) {
+    try {
+      const headers: Record<string, string> = { 'mcp-session-id': sessionId };
+      applyAuth(headers);
+      if (protocolVersion) headers['mcp-protocol-version'] = protocolVersion;
+      await doFetch(endpoint, { method: 'DELETE', headers });
+    } catch { /* best-effort */ }
+  }
+}