@nac3/forge-cli 0.2.0-alpha.59z.121 → 0.2.0-alpha.59z.158

package/dist/chat/server.js

@@ -13,6 +13,7 @@
  */
 import { createServer } from 'node:http';
 import { promises as fs } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { ClaudeClient, ConfigurationError, ClaudeApiError } from './claude.js';
 import { renderPanelHtml } from './panel.js';
@@ -47,6 +48,19 @@ export async function startChatServer(opts) {
      *  CLI + panel converge. */
     const { resolveProjectSlug } = await import('./project_slug.js');
     const projectSlug = await resolveProjectSlug(opts.projectRoot);
+    /* Director sprint slice 9 -- hydrate ingest sessions from disk
+     *  for this project so spec extract+plan survive restarts. */
+    try {
+        const { setProjectSlugForIngest, loadProjectIngests } = await import('./ingest_session.js');
+        setProjectSlugForIngest(projectSlug);
+        await loadProjectIngests(projectSlug);
+    }
+    catch (err) {
+        try {
+            console.error('ingest_session boot hydrate failed: ' + (err instanceof Error ? err.message : String(err)));
+        }
+        catch { /* swallow */ }
+    }
     /* alpha.59v -- fire-and-forget auto-ingest of package.json deps
      *  whenever the boot detects a changed (or never-ingested)
      *  package.json. Never blocks the boot; never throws.
@@ -84,7 +98,27 @@ export async function startChatServer(opts) {
         });
     }
     catch { /* never break boot */ }
-    const claude = opts.claude ?? new ClaudeClient();
+    /* Provider selection: 'anthropic-api' (default, Console billing) vs
+     * 'claude-code-cli' (subscription billing via `claude -p`
+     * subprocess). The ClaudeCliClient is interface-compatible at the
+     * .chat() shape used by this server -- runTool round-trips happen
+     * inside the subprocess, so the wrapper returns toolRounds=[].
+     * Tests inject `opts.claude` directly and bypass this branch. */
+    let claude;
+    if (opts.claude) {
+        claude = opts.claude;
+    }
+    else if (opts.chatProvider === 'claude-code-cli') {
+        const { ClaudeCliClient } = await import('./claude_cli.js');
+        const cliOpts = {};
+        if (opts.chatProviderAddDirs && opts.chatProviderAddDirs.length > 0) {
+            cliOpts['addDirs'] = opts.chatProviderAddDirs;
+        }
+        claude = new ClaudeCliClient(cliOpts);
+    }
+    else {
+        claude = new ClaudeClient();
+    }
     const voice = opts.voice ?? new VoiceRouter({
         configDir: configDir(),
         registry: buildDefaultRegistry(),
@@ -131,6 +165,8 @@ export async function startChatServer(opts) {
                 claude,
                 voice,
                 store,
+                runtime: opts.runtime,
+                chatProvider: opts.chatProvider,
             });
         }
         catch (err) {
@@ -165,7 +201,19 @@ export async function startChatServer(opts) {
             if (componentWatcherHandle) {
                 Promise.resolve(componentWatcherHandle.stop()).catch(() => undefined);
             }
-            server.close(() => resolve());
+            /* alpha.59z.136 slice 14 -- flush in-flight ingest session
+             * writes BEFORE the server closes so test teardowns that
+             * fs.rm the home directory immediately after do not race
+             * with the fire-and-forget persist queue. */
+            (async () => {
+                try {
+                    const { flushPendingIngestWrites, setProjectSlugForIngest } = await import('./ingest_session.js');
+                    await flushPendingIngestWrites();
+                    setProjectSlugForIngest(null);
+                }
+                catch { /* swallow */ }
+                server.close(() => resolve());
+            })();
         }),
     };
 }
@@ -195,6 +243,42 @@ async function route(req, res, ctx) {
         });
         return;
     }
+    /* ------------------------------------------------------------
+     * Director sprint slice 5 -- agent runtime panel endpoints.
+     * GET  /api/agent/state    -- runtime status + agent definitions
+     * POST /api/agent/run      -- dispatch an agent through runtime
+     * GET  /api/agent/events   -- SSE stream of RuntimeEvent
+     * All return 503 when ctx.runtime is unwired so the UI can
+     * surface a clean "no runtime" state.
+     * ------------------------------------------------------------ */
+    if (req.method === 'GET' && url.pathname === '/api/agent/state') {
+        await handleAgentState(res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/agent/run') {
+        await handleAgentRun(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/agent/events') {
+        await handleAgentEventsSse(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/agent/approve') {
+        await handleAgentApprove(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/agent/activity') {
+        await handleAgentActivity(req, res, ctx);
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/agent/bridge-tail') {
+        await handleAgentBridgeTail(req, res, ctx);
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/agent/inject') {
+        await handleAgentInject(req, res, ctx);
+        return;
+    }
     /* Legal docs surfaced inside the product (Config -> About).
      * Serves the raw markdown so the panel can render or pop a
      * dialog. Routes are static names so a future i18n swap can
@@ -455,6 +539,113 @@ async function route(req, res, ctx) {
         }
         return;
     }
+    /* alpha.59z.150 F101 slice 3 -- MCP bridges UI endpoints.
+     *  GET /api/forge/mcp/bridges     -> list of discovered bridges
+     *                                    with id/endpoint/source/enabled/
+     *                                    display_name/protocol.
+     *  GET /api/forge/mcp/tools       -> tool catalog for the bridge_id
+     *                                    query param. Internally calls
+     *                                    MCPClient.listTools() (slice 4
+     *                                    FULL).
+     *  POST /api/forge/mcp/toggle     -> flip enabled flag on a bridge.
+     *  Panel uses these to render the Config tab + tool catalog modal.
+     *  Each one is best-effort; failures degrade to {ok:false, error}. */
+    if (req.method === 'GET' && url.pathname === '/api/forge/mcp/bridges') {
+        try {
+            const { getActiveBridges } = await import('../mcp/bridge_registry.js');
+            const bridges = await getActiveBridges({ projectRoot: ctx.projectRoot });
+            const shaped = bridges.map((b) => ({
+                id: b.id,
+                endpoint: b.endpoint,
+                source: b.source,
+                enabled: b.enabled,
+                display_name: b.display_name ?? b.id,
+                protocol: b.protocol ?? 'http_rest',
+            }));
+            sendJson(res, 200, { ok: true, bridges: shaped, count: shaped.length });
+        }
+        catch (err) {
+            sendJson(res, 200, { ok: false, error: err instanceof Error ? err.message : String(err), bridges: [], count: 0 });
+        }
+        return;
+    }
+    if (req.method === 'GET' && url.pathname === '/api/forge/mcp/tools') {
+        const bridgeId = url.searchParams.get('bridge_id') ?? '';
+        if (!bridgeId) {
+            sendJson(res, 400, { ok: false, error: 'bridge_id required' });
+            return;
+        }
+        try {
+            const { getActiveBridges } = await import('../mcp/bridge_registry.js');
+            const bridges = await getActiveBridges({ projectRoot: ctx.projectRoot });
+            const bridge = bridges.find((b) => b.id === bridgeId);
+            if (!bridge) {
+                sendJson(res, 404, { ok: false, error: 'bridge_id "' + bridgeId + '" not found', tools: [] });
+                return;
+            }
+            if (!bridge.enabled) {
+                sendJson(res, 200, { ok: false, error: 'bridge disabled', bridge_id: bridgeId, tools: [], disabled: true });
+                return;
+            }
+            try {
+                const { getMCPClient } = await import('../mcp/protocol_client.js');
+                const client = getMCPClient(bridge);
+                const r = await client.listTools();
+                if (r.ok) {
+                    sendJson(res, 200, { ok: true, bridge_id: bridgeId, tools: r.tools, count: r.count });
+                }
+                else {
+                    sendJson(res, 200, {
+                        ok: false,
+                        error: r.error,
+                        bridge_id: bridgeId,
+                        bridge_unreachable: true,
+                        tools: [],
+                    });
+                }
+            }
+            catch (toolErr) {
+                sendJson(res, 200, {
+                    ok: false,
+                    error: toolErr instanceof Error ? toolErr.message : String(toolErr),
+                    bridge_id: bridgeId,
+                    bridge_unreachable: true,
+                    tools: [],
+                });
+            }
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/forge/mcp/toggle') {
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch {
+            sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+            return;
+        }
+        const bridgeId = typeof body.bridge_id === 'string' ? body.bridge_id.trim() : '';
+        if (!bridgeId) {
+            sendJson(res, 400, { ok: false, error: 'bridge_id required' });
+            return;
+        }
+        const enabled = body.enabled === true || body.enabled === 'true' || body.enabled === 1;
+        try {
+            const { setBridgeEnabled } = await import('../mcp/state.js');
+            await setBridgeEnabled(bridgeId, enabled);
+            const { resetBridgeCache } = await import('../mcp/bridge_registry.js');
+            resetBridgeCache();
+            sendJson(res, 200, { ok: true, bridge_id: bridgeId, enabled });
+        }
+        catch (err) {
+            sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
+        }
+        return;
+    }
     /* alpha.59l -- "what changed in this version" notification.
      *  Compares ~/.yujin-forge/last_seen_version vs current VERSION
      *  + returns the cumulative bullet catalog entries. Panel shows
@@ -2485,7 +2676,14 @@ async function handleChat(req, res, ctx) {
          * cannot infinite-loop when Danger Zone is on. */
         const callSig = [];
         const LOOP_REPEAT_THRESHOLD = 3;
-        const unified = makeUnifiedClient(brainSelection);
+        /* When the operator launched `yf chat --provider claude-code-cli`,
+         * route EVERY turn through ctx.claude (a ClaudeCliClient) and
+         * skip the unified cost_router branch -- otherwise the router
+         * would pick Gemini/Haiku/etc and bill against Console. The
+         * fallback branch below uses ctx.claude.chat() directly. */
+        const unified = ctx.chatProvider === 'claude-code-cli'
+            ? null
+            : makeUnifiedClient(brainSelection);
         const callerForChat = unified
             ? unified
             : {
@@ -2494,6 +2692,40 @@ async function handleChat(req, res, ctx) {
                     return { ...claudeReply, brain: { ...brainSelection, runtime_wired: false } };
                 },
             };
+        /* alpha.59z.135 slice 11 -- panoramic graph snapshot. Compact
+         * structural view of the project graph, cached per-slug with
+         * hash refresh. The chat also receives the relevance ranking
+         * below (graphSection); snapshot is the panorama, relevance is
+         * the zoom. Graceful no-op on worker / vault failure. */
+        let snapshotSection = '';
+        try {
+            const { buildGraphSnapshotSection } = await import('./graph_snapshot.js');
+            const r = await buildGraphSnapshotSection({
+                project_slug: ctx.projectSlug || '',
+                fetcher: async (slug) => {
+                    try {
+                        const { semanticGraphGet } = await import('../license/hito4_client.js');
+                        const resp = await semanticGraphGet('/v1/semantic-graph/nodes', {}, { project_slug: slug });
+                        if (!resp.ok || !Array.isArray(resp.body.nodes)) {
+                            return { ok: false, nodes: [] };
+                        }
+                        return {
+                            ok: true,
+                            nodes: resp.body
+                                .nodes
+                                .filter((n) => typeof n.id === 'string' && typeof n.kind === 'string')
+                                .map((n) => ({ id: n.id, kind: n.kind, label: n.label })),
+                        };
+                    }
+                    catch {
+                        return { ok: false, nodes: [] };
+                    }
+                },
+            });
+            if (r.ok && r.text)
+                snapshotSection = '\n\n' + r.text;
+        }
+        catch (_) { /* swallow -- chat continues without snapshot */ }
         /* alpha.59p -- semantic graph injection. Pulls "what primitives
          * exist in this project" from the worker + appends to system
          * prompt so the LLM does NOT reinvent libs/components/protocols
@@ -2581,7 +2813,7 @@ async function handleChat(req, res, ctx) {
                 tier: brainSelection.tier,
                 provider: brainSelection.provider,
                 model: brainSelection.model,
-            }, globalLearnings, mcpAvailable, backendToolsSection) + graphSection + workflowSection,
+            }, globalLearnings, mcpAvailable, backendToolsSection) + snapshotSection + graphSection + workflowSection,
             maxTokens: 1024,
             tools: FORGE_TOOL_SPECS,
             runTool: async (name, input) => {
@@ -3016,6 +3248,21 @@ backendToolsSection = '') {
         '  judgment ("looks good?"), $$/scope decision, or user-only creds.',
         '  Otherwise: diagnose yourself + report the diagnosis, not the path.',
         '',
+        'SQ 9 -- VERIFY FACTUAL CLAIMS ABOUT THE WORKSPACE (MANDATORY,',
+        '  added 2026-06-06 alpha.59z.158). When the user states something',
+        '  factual about the current workspace -- "no tiene X", "falta Y",',
+        '  "ya existe Z", "el bug esta en archivo W" -- DO NOT take it at',
+        '  face value if it would lead you to write code, add files, or',
+        '  recommend an action. Verify with native verbs FIRST:',
+        '    - "no tiene vault"   -> yujin.fs.find({glob:"**/vault*"}) or fs.list-files',
+        '    - "falta tests"      -> yujin.fs.list-files({subdir:"tests"})',
+        '    - "el bug en X.ts"   -> yujin.fs.read-file({path:"X.ts"}) first',
+        '    - "ya existe Z"      -> yujin.fs.find then proceed only if confirmed',
+        '  If the verification contradicts the user, REPORT the contradiction',
+        '  in chat ("Veo que ya hay server/vault.ts -- queres reemplazarlo,',
+        '  extenderlo, o algo mas especifico?"). Never proceed with an action',
+        '  premised on an unverified factual claim about the workspace.',
+        '',
         '=================================================================',
         'PRODUCT WORKFLOW (on-demand)',
         '=================================================================',
@@ -3241,6 +3488,659 @@ function sendJson(res, status, body) {
     res.setHeader('content-type', 'application/json; charset=utf-8');
     res.end(JSON.stringify(body));
 }
+/* ============================================================
+ * Director sprint slice 5 -- agent runtime panel handlers.
+ * ============================================================ */
+/** Project the AgentDefinition to a UI-safe shape. Drops the
+ *  system prompt + secret-ish fields, keeps the fields the panel
+ *  graph needs to render the topology + per-agent status. */
+function projectAgentForPanel(def) {
+    return {
+        slug: def.slug,
+        name: def.name,
+        description: def.description,
+        status: def.status,
+        brain_tier: def.brain_tier,
+        can_call: def.can_call,
+        can_be_called_by: def.can_be_called_by,
+        allowed_verbs: def.allowed_verbs,
+        trigger: def.trigger,
+    };
+}
+async function handleAgentState(res, ctx) {
+    if (!ctx.runtime) {
+        sendJson(res, 503, { ok: false, error: 'agent runtime not wired into this chat server' });
+        return;
+    }
+    const { listAgentDefinitions } = await import('../agents/store.js');
+    const defs = await listAgentDefinitions({ root: ctx.runtime.getAgentsRoot() });
+    sendJson(res, 200, {
+        ok: true,
+        runtime: ctx.runtime.status(),
+        agents: defs.map(projectAgentForPanel),
+    });
+}
+async function handleAgentRun(req, res, ctx) {
+    if (!ctx.runtime) {
+        sendJson(res, 503, { ok: false, error: 'agent runtime not wired into this chat server' });
+        return;
+    }
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    if (typeof body.slug !== 'string' || body.slug.length === 0) {
+        sendJson(res, 400, { ok: false, error: 'missing required field: slug' });
+        return;
+    }
+    const trigger_reason = typeof body.trigger_reason === 'string' && body.trigger_reason.length > 0
+        ? body.trigger_reason
+        : 'panel';
+    /* Slice 1 N-projects sprint -- optional project_slug. */
+    const project_slug = (typeof body.project_slug === 'string' && body.project_slug.trim())
+        ? body.project_slug.trim()
+        : 'self';
+    try {
+        const run = await ctx.runtime.dispatchAgent(body.slug, trigger_reason, { project_slug });
+        sendJson(res, 200, { ok: true, run });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        /* Map known runtime errors to actionable HTTP codes. */
+        if (/not registered/i.test(msg)) {
+            sendJson(res, 404, { ok: false, error: msg });
+        }
+        else if (/not started/i.test(msg)) {
+            sendJson(res, 503, { ok: false, error: msg });
+        }
+        else {
+            sendJson(res, 500, { ok: false, error: msg });
+        }
+    }
+}
+async function handleAgentEventsSse(req, res, ctx) {
+    if (!ctx.runtime) {
+        sendJson(res, 503, { ok: false, error: 'agent runtime not wired into this chat server' });
+        return;
+    }
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/event-stream; charset=utf-8');
+    res.setHeader('cache-control', 'no-store, no-transform');
+    res.setHeader('connection', 'keep-alive');
+    /* Flush headers so the client can settle the response before
+     * any event is emitted. */
+    if (typeof res.flushHeaders === 'function') {
+        res.flushHeaders();
+    }
+    /* Initial comment line keeps the proxy from buffering the
+     * empty stream + signals the client the connection is live. */
+    res.write(': connected to agent runtime event stream\n\n');
+    const sendEvent = (e) => {
+        try {
+            res.write('event: ' + e.kind + '\n');
+            res.write('data: ' + JSON.stringify(e) + '\n\n');
+        }
+        catch {
+            /* Socket may be closed; ignore. The 'close' handler below
+             * unsubscribes regardless. */
+        }
+    };
+    ctx.runtime.on('event', sendEvent);
+    /* Heartbeat keeps the connection alive through idle proxies.
+     * 15s mirrors the existing chat SSE cadence. */
+    const heartbeat = setInterval(() => {
+        try {
+            res.write(': hb\n\n');
+        }
+        catch { /* socket dead */ }
+    }, 15_000);
+    if (typeof heartbeat.unref === 'function') {
+        heartbeat.unref();
+    }
+    const cleanup = () => {
+        clearInterval(heartbeat);
+        if (ctx.runtime)
+            ctx.runtime.off('event', sendEvent);
+    };
+    req.on('close', cleanup);
+    req.on('error', cleanup);
+}
+/**
+ * Director sprint slice 10 -- POST /api/agent/approve.
+ *
+ * Single endpoint that resolves an R8-style approval envelope an
+ * agent emitted (decision: 'approved' | 'rejected'). Delegates to
+ * the existing approval queue + audit log. Independent of runtime
+ * state -- a pending row can survive runtime restarts via the
+ * queue's TTL, so we do NOT gate this endpoint on ctx.runtime.
+ */
+async function handleAgentApprove(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const traceId = typeof body.trace_id === 'string' ? body.trace_id.trim() : '';
+    if (!traceId) {
+        sendJson(res, 400, { ok: false, error: 'trace_id required' });
+        return;
+    }
+    const decision = typeof body.decision === 'string' ? body.decision : '';
+    if (decision !== 'approved' && decision !== 'rejected') {
+        sendJson(res, 400, { ok: false, error: 'decision must be "approved" or "rejected"' });
+        return;
+    }
+    const reason = typeof body.reason === 'string' ? body.reason.slice(0, 240) : undefined;
+    const pending = popPending(traceId);
+    if (!pending) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: '?',
+            decision: 'expired',
+            args_sample: {},
+            policy: '?',
+            reason: 'trace_id not in queue (expired or already resolved)',
+        });
+        sendJson(res, 404, { ok: false, error: 'no pending approval for trace_id (expired or already resolved)' });
+        return;
+    }
+    if (decision === 'rejected') {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'reject',
+            args_sample: pending.args,
+            policy: pending.verb.policy,
+            reason,
+        });
+        /* Director closure pendiente 5 followup -- fire the SSE event
+         * so the panel SVG can clear the paused-for-approval marker on
+         * the originating agent node. Best-effort: no runtime / no
+         * agent_slug means nobody is listening for this event anyway. */
+        if (ctx.runtime && pending.agent_slug) {
+            ctx.runtime.emitExternal({
+                kind: 'agent_run_paused_resolved',
+                slug: pending.agent_slug,
+                trace_id: traceId,
+                decision: 'rejected',
+                at: Date.now(),
+            });
+        }
+        sendJson(res, 200, {
+            ok: true,
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'rejected',
+        });
+        return;
+    }
+    /* Approve path: execute the bound verb via its captured legacy
+     * alias, mirroring handleNac3Approve. */
+    if (!pending.legacy_alias) {
+        sendJson(res, 500, { ok: false, error: 'pending row has no legacy alias' });
+        return;
+    }
+    let result;
+    try {
+        result = await pending.legacy_run(pending.legacy_alias, pending.args, ctx.projectRoot === pending.ctx.projectRoot ? pending.ctx : { projectRoot: ctx.projectRoot });
+    }
+    catch (err) {
+        await logApproval({
+            ts: new Date().toISOString(),
+            trace_id: traceId,
+            verb_id: pending.verb.id,
+            decision: 'approve',
+            args_sample: pending.args,
+            policy: pending.verb.policy,
+            reason: 'handler threw: ' + (err instanceof Error ? err.message : String(err)),
+        });
+        sendJson(res, 500, {
+            ok: false,
+            error: 'handler threw on approved verb: ' + (err instanceof Error ? err.message : String(err)),
+        });
+        return;
+    }
+    await logApproval({
+        ts: new Date().toISOString(),
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'approve',
+        args_sample: pending.args,
+        policy: pending.verb.policy,
+        reason,
+    });
+    /* Director closure pendiente 5 followup -- fire the SSE event so
+     * the panel SVG can clear the paused-for-approval marker on the
+     * originating agent node. */
+    if (ctx.runtime && pending.agent_slug) {
+        ctx.runtime.emitExternal({
+            kind: 'agent_run_paused_resolved',
+            slug: pending.agent_slug,
+            trace_id: traceId,
+            decision: 'approved',
+            at: Date.now(),
+        });
+    }
+    sendJson(res, 200, {
+        ok: true,
+        trace_id: traceId,
+        verb_id: pending.verb.id,
+        decision: 'approved',
+        is_error: result.is_error ?? false,
+        result: result.result,
+    });
+}
+/* ===================================================================
+ * Agent activity log + bridge inspector + chat-per-agent
+ * (visibility sprint -- alpha.59z.153).
+ *
+ * Three endpoints that surface what the agents are actually doing
+ * so the operator is not staring at a silent SVG:
+ *
+ *  GET  /api/agent/activity?since=<iso?>&limit=<n?>
+ *       -> recent timestamped events: agent runs (started/finished),
+ *          bridge sends, dispatch invokes, approval decisions.
+ *          Merge of 4 jsonl tails + 1 dir scan; sorted by ts desc.
+ *
+ *  GET  /api/agent/bridge-tail?pair_id=<from__to?>&limit=<n?>
+ *       -> messages out of bridge.json filtered + sorted desc.
+ *          When pair_id absent, lists all pairs with counts.
+ *
+ *  POST /api/agent/inject {slug, text, dispatch?}
+ *       -> append a user-role message to the agent's active
+ *          conversation file + optionally dispatch a run.
+ *
+ * All three are best-effort: missing files are normal (no agents
+ * yet) -- they return ok:true with empty arrays, not 404.
+ * =============================================================== */
+async function tailJsonl(file, limit) {
+    try {
+        const raw = await fs.readFile(file, 'utf-8');
+        const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+        const slice = lines.length > limit ? lines.slice(lines.length - limit) : lines;
+        const out = [];
+        for (const line of slice) {
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch { /* skip corrupt line */ }
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+function agentsRootDefault(ctx) {
+    if (ctx.runtime)
+        return ctx.runtime.getAgentsRoot();
+    /* Mirror the runtime default. YF_CONFIG_DIR is the same env var
+     * approval_queue / dispatch_log honor; tests inject it to scope
+     * the entire ~/.yujin-forge tree to a tmpdir. */
+    if (process.env.YF_CONFIG_DIR)
+        return process.env.YF_CONFIG_DIR;
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    return path.join(home, '.yujin-forge');
+}
+async function handleAgentActivity(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const limit = clampInt(url.searchParams.get('limit'), 200, 1, 2000);
+    const since = url.searchParams.get('since') || '';
+    /* Slice 1 N-projects sprint -- optional project filter. Empty
+     * = all projects (default; back-compat with single-project
+     * callers). Explicit slug filters events by project_slug. */
+    const projectFilter = (url.searchParams.get('project_slug') || '').trim();
+    const events = [];
+    const agentsRoot = agentsRootDefault(ctx);
+    const yfRoot = path.join(agentsRoot);
+    /* 1. nac3 dispatch log -- every verb invoke / deny / panel-dispatch */
+    const dispatchLog = path.join(yfRoot, 'nac3_log.jsonl');
+    for (const e of await tailJsonl(dispatchLog, limit)) {
+        const r = e;
+        if (!r.ts)
+            continue;
+        const label = r.kind === 'invoke' ? ((r.result_ok ? 'ok' : 'err') + ' ' + (r.verb_id ?? '?'))
+            : r.kind === 'verb-not-found' ? ('unknown verb ' + (r.verb_id ?? '?'))
+                : r.kind === 'policy-deny' ? ('policy denied ' + (r.verb_id ?? '?'))
+                    : r.kind === 'panel-handler-error' ? ('panel error ' + (r.verb_id ?? '?'))
+                        : String(r.kind ?? 'event');
+        events.push({
+            ts: String(r.ts),
+            kind: 'dispatch.' + String(r.kind ?? 'unknown'),
+            text: label,
+            trace_id: r.trace_id ? String(r.trace_id) : undefined,
+            extra: {
+                duration_ms: r.duration_ms,
+                policy: r.policy,
+                side_effects_declared: r.side_effects_declared,
+            },
+        });
+    }
+    /* 2. approvals log -- R8 modal decisions */
+    const approvalLog = path.join(yfRoot, 'nac3_approvals.jsonl');
+    for (const e of await tailJsonl(approvalLog, limit)) {
+        const r = e;
+        if (!r.ts)
+            continue;
+        events.push({
+            ts: String(r.ts),
+            kind: 'approval.' + String(r.decision ?? 'event'),
+            text: 'R8 ' + String(r.decision ?? '?') + ' on ' + String(r.verb_id ?? '?'),
+            trace_id: r.trace_id ? String(r.trace_id) : undefined,
+            extra: { policy: r.policy, reason: r.reason },
+        });
+    }
+    /* 3. agent runs -- scan ~/.yujin-forge/agents/by-slug/<slug>/runs/*.json */
+    const bySlug = path.join(yfRoot, 'agents', 'by-slug');
+    let slugs = [];
+    try {
+        slugs = await fs.readdir(bySlug);
+    }
+    catch { /* no agents yet -- ok */ }
+    for (const slug of slugs) {
+        const runsDir = path.join(bySlug, slug, 'runs');
+        let runFiles = [];
+        try {
+            runFiles = (await fs.readdir(runsDir)).filter((n) => n.endsWith('.json'));
+        }
+        catch {
+            continue;
+        }
+        /* Newest first; we cap at limit per agent so a noisy one
+         * does not drown others. */
+        runFiles.sort();
+        const cap = runFiles.slice(-Math.min(50, limit));
+        for (const fn of cap) {
+            try {
+                const raw = await fs.readFile(path.join(runsDir, fn), 'utf-8');
+                const r = JSON.parse(raw);
+                const startTs = r.started_at ? new Date(Number(r.started_at)).toISOString() : '';
+                const endTs = r.ended_at ? new Date(Number(r.ended_at)).toISOString() : startTs;
+                const runProject = (typeof r.project_slug === 'string' && r.project_slug) ? r.project_slug : 'self';
+                events.push({
+                    ts: startTs || endTs,
+                    kind: 'agent.run_started',
+                    slug,
+                    text: '[' + runProject + '] ' + slug + ' started: ' + String(r.trigger_reason ?? '').slice(0, 120),
+                    project_slug: runProject,
+                });
+                if (r.ended_at) {
+                    events.push({
+                        ts: endTs,
+                        kind: 'agent.run_finished',
+                        slug,
+                        text: '[' + runProject + '] ' + slug + ' ' + String(r.status ?? '?')
+                            + ' (in=' + (r.tokens_in ?? 0) + ' out=' + (r.tokens_out ?? 0)
+                            + ' tools=' + (r.tool_calls ?? 0) + ')',
+                        project_slug: runProject,
+                        extra: {
+                            status: r.status,
+                            tokens_in: r.tokens_in,
+                            tokens_out: r.tokens_out,
+                            tool_calls: r.tool_calls,
+                            kill_reason: r.kill_reason,
+                            last_reply_summary: typeof r.last_reply_summary === 'string'
+                                ? String(r.last_reply_summary).slice(0, 240)
+                                : undefined,
+                        },
+                    });
+                }
+            }
+            catch { /* skip */ }
+        }
+    }
+    /* 4. bridge messages -- scan every shard under
+     *    ~/.yujin-forge/bridge/ (bridge.json + bridge-{slug}.json).
+     *    Each shard's messages tag themselves with project_slug
+     *    derived from the filename so the activity feed knows which
+     *    project a message belongs to. */
+    const bridgeDir = path.join(yfRoot, 'bridge');
+    let bridgeShards = [];
+    try {
+        bridgeShards = (await fs.readdir(bridgeDir)).filter((n) => n.endsWith('.json') && (n === 'bridge.json' || n.startsWith('bridge-')));
+    }
+    catch { /* no bridge dir -- ok */ }
+    for (const fname of bridgeShards) {
+        const projectFromFile = fname === 'bridge.json'
+            ? 'self'
+            : fname.slice('bridge-'.length, fname.length - '.json'.length) || 'self';
+        try {
+            const raw = await fs.readFile(path.join(bridgeDir, fname), 'utf-8');
+            const b = JSON.parse(raw);
+            const msgs = Array.isArray(b.messages) ? b.messages : [];
+            /* Take last `limit` per shard to bound memory while not
+             * losing recent activity. */
+            const slice = msgs.length > limit ? msgs.slice(msgs.length - limit) : msgs;
+            for (const m of slice) {
+                const ts = m.sent_at ? new Date(Number(m.sent_at)).toISOString()
+                    : (m.created_at ? new Date(Number(m.created_at)).toISOString() : '');
+                const msgProject = (typeof m.project_slug === 'string' && m.project_slug)
+                    ? m.project_slug
+                    : projectFromFile;
+                events.push({
+                    ts,
+                    kind: 'bridge.message',
+                    from: String(m.from_slug ?? m.from ?? '?'),
+                    to: String(m.to_slug ?? m.to ?? '?'),
+                    text: '[' + msgProject + '] '
+                        + String(m.from_slug ?? m.from ?? '?') + ' -> ' + String(m.to_slug ?? m.to ?? '?')
+                        + ': ' + String(m.payload ?? '').slice(0, 160),
+                    project_slug: msgProject,
+                    extra: { tokens: m.tokens_used, status: m.status, id: m.id },
+                });
+            }
+        }
+        catch { /* skip unreadable shard */ }
+    }
+    /* Sort desc by ts (ISO strings sort correctly). Filter by since
+     * + project_filter. */
+    events.sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0));
+    let filtered = since ? events.filter((e) => e.ts > since) : events;
+    if (projectFilter) {
+        filtered = filtered.filter((e) => e.project_slug === projectFilter
+            /* Events without a project_slug (legacy or non-project-
+             * tagged kinds like dispatch.*) appear under 'self' so a
+             * filter for the default project still sees them. */
+            || (!e.project_slug && projectFilter === 'self'));
+    }
+    const final = filtered.slice(0, limit);
+    sendJson(res, 200, { ok: true, count: final.length, project_filter: projectFilter || null, events: final });
+}
+async function handleAgentBridgeTail(req, res, ctx) {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const limit = clampInt(url.searchParams.get('limit'), 100, 1, 1000);
+    const pairId = (url.searchParams.get('pair_id') || '').trim();
+    /* Slice 1 N-projects sprint -- optional project filter. Empty
+     * means "scan every shard". 'self' means only the default
+     * (legacy bridge.json). */
+    const projectFilter = (url.searchParams.get('project_slug') || '').trim();
+    const yfRoot = agentsRootDefault(ctx);
+    const bridgeDir = path.join(yfRoot, 'bridge');
+    /* Discover every shard file, then read whichever ones match
+     * the filter. */
+    let shardFiles = [];
+    try {
+        shardFiles = (await fs.readdir(bridgeDir)).filter((n) => n.endsWith('.json') && (n === 'bridge.json' || n.startsWith('bridge-')));
+    }
+    catch {
+        sendJson(res, 200, { ok: true, pairs: [], messages: [], pair_state: {}, project_filter: projectFilter || null });
+        return;
+    }
+    /* Load every shard. msgs carries an extra `_project_slug` for
+     * downstream filtering. pair_state aggregated per-shard. */
+    const allMsgs = [];
+    const allPairState = {};
+    for (const fname of shardFiles) {
+        const project = fname === 'bridge.json'
+            ? 'self'
+            : fname.slice('bridge-'.length, fname.length - '.json'.length) || 'self';
+        if (projectFilter && projectFilter !== project)
+            continue;
+        try {
+            const raw = await fs.readFile(path.join(bridgeDir, fname), 'utf-8');
+            const b = JSON.parse(raw);
+            const ms = Array.isArray(b.messages) ? b.messages : [];
+            for (const m of ms)
+                allMsgs.push({ ...m, _project_slug: project });
+            if (b.pair_state) {
+                for (const [pid, st] of Object.entries(b.pair_state)) {
+                    allPairState[pid + '@' + project] = { project_slug: project, state: st };
+                }
+            }
+        }
+        catch { /* skip unreadable shard */ }
+    }
+    /* When pair_id absent: aggregate by pair (cross-shard). The
+     * project_slug is part of the visible pair card so two pairs
+     * with the same from/to but different projects don't merge. */
+    if (!pairId) {
+        const pairs = {};
+        for (const m of allMsgs) {
+            const fromSlug = String(m.from_slug ?? m.from ?? '?');
+            const toSlug = String(m.to_slug ?? m.to ?? '?');
+            const proj = m._project_slug;
+            const key = fromSlug + '__' + toSlug + (proj === 'self' ? '' : '@' + proj);
+            const ts = m.sent_at ? new Date(Number(m.sent_at)).toISOString()
+                : (m.created_at ? new Date(Number(m.created_at)).toISOString() : '');
+            if (!pairs[key]) {
+                pairs[key] = { from: fromSlug, to: toSlug, count: 0, last_ts: ts, project_slug: proj };
+            }
+            pairs[key].count++;
+            if (ts > pairs[key].last_ts)
+                pairs[key].last_ts = ts;
+        }
+        const list = Object.entries(pairs).map(([k, v]) => ({ pair_id: k, ...v }))
+            .sort((a, b) => (a.last_ts < b.last_ts ? 1 : -1));
+        sendJson(res, 200, { ok: true, pairs: list, project_filter: projectFilter || null });
+        return;
+    }
+    /* With pair_id: parse out optional @project suffix; filter
+     * messages newest first, capped. */
+    const atIdx = pairId.lastIndexOf('@');
+    const pairCore = atIdx >= 0 ? pairId.slice(0, atIdx) : pairId;
+    const pairProject = atIdx >= 0 ? pairId.slice(atIdx + 1) : 'self';
+    const filtered = allMsgs.filter((m) => {
+        const fromSlug = String(m.from_slug ?? m.from ?? '?');
+        const toSlug = String(m.to_slug ?? m.to ?? '?');
+        return (fromSlug + '__' + toSlug) === pairCore && m._project_slug === pairProject;
+    });
+    const slice = filtered.length > limit ? filtered.slice(filtered.length - limit) : filtered;
+    slice.sort((a, b) => Number(b.sent_at ?? 0) - Number(a.sent_at ?? 0));
+    /* Find matching pair_state from the per-shard map. */
+    const pairStateKey = Object.keys(allPairState).find((k) => k.endsWith('@' + pairProject))
+        || null;
+    sendJson(res, 200, {
+        ok: true,
+        pair_id: pairId,
+        project_slug: pairProject,
+        count: slice.length,
+        messages: slice,
+        pair_state: pairStateKey ? allPairState[pairStateKey].state : null,
+    });
+}
+async function handleAgentInject(req, res, ctx) {
+    let body;
+    try {
+        body = JSON.parse(await readBody(req));
+    }
+    catch {
+        sendJson(res, 400, { ok: false, error: 'invalid JSON body' });
+        return;
+    }
+    const slug = typeof body.slug === 'string' ? body.slug.trim() : '';
+    const text = typeof body.text === 'string' ? body.text.trim() : '';
+    if (!slug) {
+        sendJson(res, 400, { ok: false, error: 'slug required' });
+        return;
+    }
+    if (!text) {
+        sendJson(res, 400, { ok: false, error: 'text required' });
+        return;
+    }
+    const doDispatch = body.dispatch !== false;
+    /* Slice 1 N-projects sprint -- explicit project_slug routes
+     * the user message to that project's conversation/run instance.
+     * Defaults to 'self' for legacy single-project behaviour. */
+    const project_slug = (typeof body.project_slug === 'string' && body.project_slug.trim())
+        ? body.project_slug.trim()
+        : 'self';
+    const yfRoot = agentsRootDefault(ctx);
+    const convDir = path.join(yfRoot, 'agents', 'by-slug', slug, 'conversations');
+    /* Pick the most recently modified conversation file, or create
+     * one named "manual" if none exists yet. */
+    let convFile = path.join(convDir, 'manual.json');
+    try {
+        const files = (await fs.readdir(convDir)).filter((n) => n.endsWith('.json'));
+        if (files.length > 0) {
+            const stats = await Promise.all(files.map(async (n) => ({
+                name: n,
+                mtime: (await fs.stat(path.join(convDir, n))).mtimeMs,
+            })));
+            stats.sort((a, b) => b.mtime - a.mtime);
+            convFile = path.join(convDir, stats[0].name);
+        }
+    }
+    catch {
+        /* convDir does not exist yet -- mkdir below + start manual. */
+    }
+    let messages = [];
+    try {
+        const raw = await fs.readFile(convFile, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.messages))
+            messages = parsed.messages;
+    }
+    catch { /* fresh */ }
+    messages.push({ role: 'user', content: text });
+    try {
+        await fs.mkdir(convDir, { recursive: true });
+        await fs.writeFile(convFile, JSON.stringify({ version: 1, messages }, null, 2), 'utf-8');
+    }
+    catch (err) {
+        sendJson(res, 500, { ok: false, error: 'persist failed: ' + (err instanceof Error ? err.message : String(err)) });
+        return;
+    }
+    if (doDispatch) {
+        if (!ctx.runtime) {
+            sendJson(res, 200, {
+                ok: true, persisted: convFile, dispatched: false,
+                note: 'runtime not wired -- message saved but no run fired',
+            });
+            return;
+        }
+        try {
+            const run = await ctx.runtime.dispatchAgent(slug, 'user-injected: ' + text.slice(0, 80), { project_slug });
+            sendJson(res, 200, {
+                ok: true, persisted: convFile, dispatched: true,
+                run_status: run.status, run_id: run.id, last_reply: run.last_reply_summary,
+                project_slug: run.project_slug ?? project_slug,
+            });
+        }
+        catch (err) {
+            sendJson(res, 200, {
+                ok: true, persisted: convFile, dispatched: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return;
+    }
+    sendJson(res, 200, { ok: true, persisted: convFile, dispatched: false });
+}
+function clampInt(raw, fallback, lo, hi) {
+    const n = raw != null ? Number(raw) : fallback;
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(lo, Math.min(hi, Math.floor(n)));
+}
 /** Serve a legal doc (privacy policy / limited responsibility) as
  *  text/markdown. Reads from dist/docs/<basename> (copied at build
  *  time by scripts/copy_qa_assets.mjs). Names are static + sanitised