codehere 0.5.0-alpha.6 → 0.6.0-alpha.1

package/dist/infrastructure/protocols/mcp-server-impl.js

@@ -23,17 +23,21 @@ import { readFileSync, existsSync, statSync, watchFile, unwatchFile } from 'fs';
 import { join, relative, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { collectFilesForMCP, scoreFileForMCP } from './mcp-helpers.js';
-import { scanPayload, calculateRiskScore, AUDIT_FILE } from '../hooks/claude-sdk-hook.js';
+import { scanPayload, calculateRiskScore, AUDIT_FILE, verifyAuditChain, } from '../hooks/claude-sdk-hook.js';
 import { getVersion } from '../../utils/version.js';
 import { TASK_HTML, HISTORY_HTML, THREAD_HTML } from './ui-page.js';
 import { SessionManager, availableAgents, readinessForAllAgents, getAdapter, allAdapters, } from '../orchestration/session-manager.js';
 import { isAbsolute } from 'path';
 import { readCrossToolAgents } from '../storage/cross-tool-agents.js';
 import { listProjects, readProjectThread } from '../storage/project-thread-reader.js';
-import { mirrorReplyToThread } from '../storage/project-thread-mirror.js';
+import { mirrorReplyToThread, renameProject } from '../storage/project-thread-mirror.js';
 import { randomUUID } from 'crypto';
 import { installAgent } from '../orchestration/agent-installer.js';
 import { detectReadiness } from '../orchestration/readiness.js';
+import { getHookMode } from '../hooks/hook-mode.js';
+import { addPermissionEntry, loadPermissions, removePermissionEntry } from '../security/permissions-config.js';
+import { computeSpendToday, estimateCostUsd } from '../cost/spend-aggregator.js';
+import { loadBudget, isOverBudget, budgetUsedPct } from '../cost/budget-config.js';
 // ── Tool definitions ─────────────────────────────────────────────────────────
 const TOOLS = [
     {
@@ -72,12 +76,20 @@ const TOOLS = [
     },
     {
         name: 'codehere_audit',
-        description: 'Read recent hook audit log entries — shows which tool calls codehere blocked or allowed in Claude Code sessions.',
+        description: 'Read recent hook audit log entries — shows which tool calls codehere blocked, allowed, or overrode (fail-open paths) in Claude Code sessions. Pass verify:true to instead validate the SHA-256 hash chain and return any tampering detected.',
         inputSchema: {
             type: 'object',
             properties: {
                 limit: { type: 'number', description: 'Number of recent entries to return (default: 20)' },
                 blockedOnly: { type: 'boolean', description: 'Only return blocked events' },
+                overrideOnly: {
+                    type: 'boolean',
+                    description: 'Only return trust-override events — cases where the scanner was bypassed (stdin failure, parse failure, --log-only, scan exception). Per CC frontier Q1 (auditable permission trails) — surface every bypass for review.',
+                },
+                verify: {
+                    type: 'boolean',
+                    description: 'Verify the SHA-256 hash chain instead of returning entries. Returns { valid, totalEntries, chainedEntries, legacyEntries, errors[] } where errors lists every detected tampering point (modification / deletion / insertion / parse failure). Per CC frontier Q1 (cryptographic commitment + tamper evidence).',
+                },
             },
         },
     },
@@ -195,6 +207,14 @@ function handleReview(params) {
 function handleAudit(params) {
     const limit = Number(params.limit ?? 20);
     const blockedOnly = Boolean(params.blockedOnly);
+    const overrideOnly = Boolean(params.overrideOnly);
+    const verify = Boolean(params.verify);
+    if (verify) {
+        // Tamper-evidence verification — walks the file, recomputes every hash,
+        // checks the chain. Returns full report including ALL break points.
+        const result = verifyAuditChain(AUDIT_FILE_PATH);
+        return JSON.stringify(result, null, 2);
+    }
     if (!existsSync(AUDIT_FILE_PATH)) {
         return JSON.stringify({
             message: 'No audit log yet — install hooks first with: codehere hook install',
@@ -215,7 +235,13 @@ function handleAudit(params) {
         }
     })
         .filter(Boolean)
-        .filter((e) => !blockedOnly || e.blocked)
+        .filter((e) => {
+        if (overrideOnly)
+            return Boolean(e.overrideReason);
+        if (blockedOnly)
+            return Boolean(e.blocked);
+        return true;
+    })
         .slice(-limit);
     return JSON.stringify({ entries, total: entries.length });
 }
@@ -306,7 +332,8 @@ export function startMCPServer(options = {}) {
             return;
         }
         // v0.6.0 M1 — project thread view; consumes /api/projects + /api/projects/:slug
-        if (req.method === 'GET' && (req.url === '/threads' || req.url === '/threads/' || req.url?.startsWith('/threads?'))) {
+        if (req.method === 'GET' &&
+            (req.url === '/threads' || req.url === '/threads/' || req.url?.startsWith('/threads?'))) {
             res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
             res.end(withDevElu(THREAD_HTML));
             return;
@@ -373,6 +400,123 @@ export function startMCPServer(options = {}) {
             res.end(JSON.stringify({ agents: availableAgents() }));
             return;
         }
+        // P12 slice — tamper-evidence verification of the audit log.
+        // Calls verifyAuditChain() and returns a compact summary. /history
+        // polls this every minute and shows a red banner if valid=false.
+        if (req.method === 'GET' && req.url === '/api/audit/verify') {
+            try {
+                const r = verifyAuditChain();
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    valid: r.valid,
+                    totalEntries: r.totalEntries,
+                    chainedEntries: r.chainedEntries,
+                    legacyEntries: r.legacyEntries,
+                    errors: r.errors.slice(0, 10),
+                }));
+            }
+            catch {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ valid: true, totalEntries: 0, chainedEntries: 0, legacyEntries: 0, errors: [] }));
+            }
+            return;
+        }
+        // P18 slice 3 — permissions read/write surface. Lets the future
+        // dashboard panel (when a hook block fires) call "Approve in this
+        // folder" without shelling out. The CLI command and this endpoint
+        // both call addPermissionEntry → single source of truth.
+        if (req.method === 'GET' && req.url?.startsWith('/api/permissions?')) {
+            const cwd = decodeURIComponent(req.url.split('cwd=')[1] || '');
+            if (!cwd || !isAbsolute(cwd)) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'cwd query param required (absolute path)' }));
+                return;
+            }
+            try {
+                const cfg = loadPermissions(cwd);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ cwd, permissions: cfg }));
+            }
+            catch {
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ cwd, permissions: { allow: [], deny: [] } }));
+            }
+            return;
+        }
+        if (req.method === 'POST' && req.url === '/api/permissions') {
+            let body = '';
+            req.on('data', (c) => { body += c; });
+            req.on('end', () => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(body || '{}');
+                }
+                catch (e) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON body', detail: String(e) }));
+                    return;
+                }
+                const cwd = parsed.cwd;
+                const pattern = parsed.pattern;
+                const bucket = parsed.bucket === 'deny' ? 'deny' : 'allow';
+                if (!cwd || typeof cwd !== 'string' || !isAbsolute(cwd) || cwd.includes('\0')) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'cwd must be an absolute path with no NUL bytes' }));
+                    return;
+                }
+                if (!pattern || typeof pattern !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'pattern (non-empty string) required' }));
+                    return;
+                }
+                try {
+                    const result = addPermissionEntry({ cwd, pattern, bucket, reason: parsed.reason });
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(result));
+                }
+                catch (e) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'write_failed', detail: String(e?.message || e) }));
+                }
+            });
+            return;
+        }
+        if (req.method === 'DELETE' && req.url?.startsWith('/api/permissions?')) {
+            const params = new URLSearchParams(req.url.split('?')[1] || '');
+            const cwd = params.get('cwd') || '';
+            const pattern = params.get('pattern') || '';
+            if (!cwd || !isAbsolute(cwd) || !pattern) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'cwd (absolute) + pattern query params required' }));
+                return;
+            }
+            try {
+                const result = removePermissionEntry(cwd, pattern);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify(result));
+            }
+            catch (e) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'remove_failed', detail: String(e?.message || e) }));
+            }
+            return;
+        }
+        // Pattern 20 — hook-mode indicator. Read-only by design; mode
+        // switching goes through `codehere hook install/uninstall` so the
+        // safety surface re-validates. Cheap (one settings.json parse);
+        // safe to poll from the dashboard header at 30s cadence.
+        if (req.method === 'GET' && req.url === '/api/hook/mode') {
+            let mode;
+            try {
+                mode = getHookMode();
+            }
+            catch {
+                mode = 'off';
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ mode }));
+            return;
+        }
         // ── Gate B3 · Audit summary (moat visible on main page) ───────────────────
         // Principle #3 status-at-a-glance + #7 agent-provenance. Reads the hook audit
         // log's last 24h, aggregates: how many actions fired across all agents, how
@@ -514,6 +658,34 @@ export function startMCPServer(options = {}) {
             }
             return;
         }
+        // ── v0.6 S3 — spend-today aggregator + budget state ──────────────────────
+        // GET /api/spend/today — read-only aggregate of today's estimated USD spend
+        // plus budget config (slice 2: dailyUsd, pctUsed, over). Powers the
+        // dashboard's "spent today" pill + budget warn/block colors. Per
+        // claim_market_position v3 capture-strategy edge "cost-bounded execution":
+        // this is the read surface; the actual block happens at /api/task spawn.
+        if (req.method === 'GET' && req.url === '/api/spend/today') {
+            try {
+                const spend = computeSpendToday();
+                const budget = loadBudget();
+                const pctUsed = budgetUsedPct(spend.totalUsd, budget);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    ...spend,
+                    budget: {
+                        dailyUsd: budget.dailyUsd,
+                        warnAtPct: budget.warnAtPct,
+                        pctUsed,
+                        over: isOverBudget(spend.totalUsd, budget),
+                    },
+                }));
+            }
+            catch (e) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'spend_today_failed', detail: String(e) }));
+            }
+            return;
+        }
         // ── F1a readiness check ───────────────────────────────────────────────────
         if (req.method === 'GET' && req.url === '/api/readiness') {
             try {
@@ -570,6 +742,57 @@ export function startMCPServer(options = {}) {
             }
             return;
         }
+        // POST /api/projects/:slug/rename  — body { title }
+        // User-initiated rename. Title agent generates a title from the first
+        // prompt; project intent drifts. Without rename, /agent dir gets stuck
+        // titled "Scan Auth File" forever even after 100+ unrelated tasks.
+        if (req.method === 'POST' && req.url?.match(/^\/api\/projects\/[^/]+\/rename$/)) {
+            const slug = req.url.split('/')[3];
+            let body = '';
+            req.on('data', (c) => {
+                body += c;
+            });
+            req.on('end', () => {
+                let parsed;
+                try {
+                    const raw = JSON.parse(body);
+                    // JSON.parse accepts the literal `null` and primitive bodies as
+                    // valid JSON. Reject anything that isn't a plain object — otherwise
+                    // the .title access below throws and crashes the request callback.
+                    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'invalid_body' }));
+                        return;
+                    }
+                    parsed = raw;
+                }
+                catch {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'invalid_json' }));
+                    return;
+                }
+                if (typeof parsed.title !== 'string') {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'title_required' }));
+                    return;
+                }
+                const result = renameProject(slug, parsed.title);
+                if (!result.ok) {
+                    // 404 = project missing; 500 = fs append failed; 400 = validation.
+                    let status = 400;
+                    if (result.error === 'Project not found')
+                        status = 404;
+                    else if (result.error === 'Write failed')
+                        status = 500;
+                    res.writeHead(status, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: result.error }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, slug, title: parsed.title.trim() }));
+            });
+            return;
+        }
         // ── F1 task orchestration routes ─────────────────────────────────────────
         // POST /api/task               — { prompt, cwd? } → { sessionId }
         // GET  /api/tasks              — list all sessions
@@ -577,14 +800,118 @@ export function startMCPServer(options = {}) {
         // POST /api/task/:id/kill      — terminate
         if (req.url && req.url.startsWith('/api/task')) {
             const manager = SessionManager.getInstance();
+            // v0.6 M5 slice 1 — POST /api/task/batch.
+            // Spawns N tasks at once (independent files only, per W2 — same-file
+            // conflicts ship in v0.7). Each spawn flows through SessionManager
+            // so pre-prompt scan + audit still run per task. Cap of 5 concurrent
+            // to prevent runaway. Returns array of { sessionId, agent } in input
+            // order; per-task failures are surfaced as { error, agent } entries
+            // so a partial-failure batch still returns useful info.
+            if (req.method === 'POST' && req.url === '/api/task/batch') {
+                let body = '';
+                req.on('data', (c) => { body += c; });
+                req.on('end', () => {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(body || '{}');
+                    }
+                    catch (e) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Invalid JSON body', detail: String(e) }));
+                        return;
+                    }
+                    const tasks = Array.isArray(parsed.tasks) ? parsed.tasks : [];
+                    if (tasks.length === 0) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'tasks (non-empty array) required' }));
+                        return;
+                    }
+                    if (tasks.length > 5) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'batch size capped at 5', requested: tasks.length }));
+                        return;
+                    }
+                    const validAgentIds = new Set(allAdapters().map((a) => a.id));
+                    // v0.6 S3 slice 2 — pre-spawn budget gate, applied per-task. Fan-out
+                    // is the most likely way to overshoot a daily budget (5 paid spawns
+                    // at once); checking once at batch entry then re-checking per task
+                    // is overkill, so we snapshot the budget + spend ONCE and let each
+                    // paid spawn that would push us over fail with the same error shape
+                    // /api/task uses. Free-tier spawns always pass.
+                    const batchBudget = loadBudget();
+                    const batchSpendNow = batchBudget.dailyUsd !== null ? computeSpendToday().totalUsd : 0;
+                    const results = [];
+                    for (const t of tasks) {
+                        const prompt = t.prompt;
+                        if (!prompt || typeof prompt !== 'string') {
+                            results.push({ error: 'prompt (string) required', agent: t.agent ?? null });
+                            continue;
+                        }
+                        const agentId = typeof t.agent === 'string' && t.agent.length > 0 ? t.agent : 'conductor';
+                        if (!validAgentIds.has(agentId)) {
+                            results.push({ error: `Unknown agent: ${agentId}`, agent: agentId });
+                            continue;
+                        }
+                        if (t.cwd !== undefined) {
+                            if (typeof t.cwd !== 'string' || t.cwd.includes('\0') || !isAbsolute(t.cwd)) {
+                                results.push({ error: 'cwd must be absolute, no NUL bytes', agent: agentId });
+                                continue;
+                            }
+                        }
+                        // Per-task budget check (paid agents only).
+                        if (batchBudget.dailyUsd !== null) {
+                            const probe = estimateCostUsd(agentId, { inputTokens: 1, outputTokens: 1 });
+                            if (probe > 0 && isOverBudget(batchSpendNow, batchBudget)) {
+                                results.push({
+                                    error: 'daily_budget_exhausted',
+                                    agent: agentId,
+                                    spentTodayUsd: batchSpendNow,
+                                    dailyBudgetUsd: batchBudget.dailyUsd,
+                                });
+                                continue;
+                            }
+                        }
+                        try {
+                            const session = manager.spawn(prompt, agentId, { cwd: t.cwd });
+                            results.push({
+                                sessionId: session.sessionId,
+                                agent: session.agent,
+                                status: session.status,
+                                startedAt: session.startedAt,
+                            });
+                        }
+                        catch (e) {
+                            const msg = String(e?.message || e);
+                            const code = msg.includes('pre-prompt scan blocked') ? 'pre_prompt_blocked' : 'spawn_failed';
+                            results.push({ error: code, reason: msg, agent: agentId });
+                        }
+                    }
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ tasks: results, count: results.length }));
+                });
+                return;
+            }
             if (req.method === 'POST' && req.url === '/api/task') {
                 let body = '';
                 req.on('data', (c) => {
                     body += c;
                 });
                 req.on('end', () => {
+                    // Two-phase try: JSON parse failures get one error shape, spawn
+                    // failures get a different one. Pre-fix the catch wrapped every
+                    // failure as "Invalid JSON body" — including the pre-prompt scan
+                    // throw — which read as a parse bug to the client.
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(body || '{}');
+                    }
+                    catch (e) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Invalid JSON body', detail: String(e) }));
+                        return;
+                    }
                     try {
-                        const { prompt, cwd, agent } = JSON.parse(body || '{}');
+                        const { prompt, cwd, agent } = parsed;
                         if (!prompt || typeof prompt !== 'string') {
                             res.writeHead(400, { 'Content-Type': 'application/json' });
                             res.end(JSON.stringify({ error: 'prompt (string) required' }));
@@ -608,7 +935,7 @@ export function startMCPServer(options = {}) {
                             return;
                         }
                         const validAgentIds = new Set(allAdapters().map((a) => a.id));
-                        const agentId = (typeof agent === 'string' && agent.length > 0) ? agent : 'conductor';
+                        const agentId = typeof agent === 'string' && agent.length > 0 ? agent : 'conductor';
                         if (!validAgentIds.has(agentId)) {
                             res.writeHead(400, { 'Content-Type': 'application/json' });
                             res.end(JSON.stringify({
@@ -626,6 +953,31 @@ export function startMCPServer(options = {}) {
                                 return;
                             }
                         }
+                        // v0.6 S3 slice 2 — pre-spawn budget gate. Blocks paid spawns
+                        // when today's estimated spend already meets the user's daily
+                        // ceiling. Free-tier specialists (gemini, opencode) always pass:
+                        // "don't let me spend more, but free is fine" matches user intent.
+                        // Conductor is treated as paid because it routes to whatever's
+                        // available (typically claude-code). Per
+                        // claim_market_position v3 cost-bounded-execution edge.
+                        const budgetForSpawn = loadBudget();
+                        if (budgetForSpawn.dailyUsd !== null) {
+                            const probe = estimateCostUsd(agentId, { inputTokens: 1, outputTokens: 1 });
+                            const isPaidSpawn = probe > 0;
+                            if (isPaidSpawn) {
+                                const todaySpend = computeSpendToday();
+                                if (isOverBudget(todaySpend.totalUsd, budgetForSpawn)) {
+                                    res.writeHead(429, { 'Content-Type': 'application/json' });
+                                    res.end(JSON.stringify({
+                                        error: 'daily_budget_exhausted',
+                                        message: `Today's estimated spend ($${todaySpend.totalUsd.toFixed(2)}) has reached the daily budget ($${budgetForSpawn.dailyUsd.toFixed(2)}). Switch to a free agent (gemini, opencode) or raise the budget with \`codehere budget set <amount>\`.`,
+                                        spentTodayUsd: todaySpend.totalUsd,
+                                        dailyBudgetUsd: budgetForSpawn.dailyUsd,
+                                    }));
+                                    return;
+                                }
+                            }
+                        }
                         const session = manager.spawn(prompt, agentId, { cwd });
                         res.writeHead(200, { 'Content-Type': 'application/json' });
                         res.end(JSON.stringify({
@@ -641,8 +993,20 @@ export function startMCPServer(options = {}) {
                         }));
                     }
                     catch (e) {
-                        res.writeHead(400, { 'Content-Type': 'application/json' });
-                        res.end(JSON.stringify({ error: 'Invalid JSON body', detail: String(e) }));
+                        // Spawn-phase failure. Distinguish the cross-vendor pre-prompt
+                        // scan refusal (#110) — actionable safety block — from generic
+                        // adapter / install / SessionManager errors. The pre-prompt
+                        // case gets 422 (Unprocessable Entity, "we understood but
+                        // refused") + a structured 'pre_prompt_blocked' code so the
+                        // web UI can surface a recovery affordance.
+                        const msg = String(e?.message || e);
+                        if (msg.includes('pre-prompt scan blocked')) {
+                            res.writeHead(422, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: 'pre_prompt_blocked', reason: msg }));
+                            return;
+                        }
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'spawn_failed', detail: msg }));
                     }
                 });
                 return;
@@ -698,6 +1062,55 @@ export function startMCPServer(options = {}) {
                 }));
                 return;
             }
+            // P18 slice 4 — GET /api/task/:id/blocks → audit entries with
+            // blocked:true for this session. Lets the session-card UI panel
+            // surface "codehere noticed this pattern" prompts when the per-
+            // tool hook fires mid-session. Reads from the tail of the audit
+            // log; cheap because hook entries are short.
+            const blocksMatch = req.url.match(/^\/api\/task\/([^/]+)\/blocks$/);
+            if (blocksMatch && req.method === 'GET') {
+                const sessId = blocksMatch[1];
+                const blocks = [];
+                try {
+                    if (existsSync(AUDIT_FILE)) {
+                        const content = readFileSync(AUDIT_FILE, 'utf-8');
+                        const lines = content.split('\n');
+                        // Walk backward — most recent first — collect up to 20.
+                        for (let i = lines.length - 1; i >= 0 && blocks.length < 20; i--) {
+                            const ln = lines[i].trim();
+                            if (!ln)
+                                continue;
+                            try {
+                                const e = JSON.parse(ln);
+                                if (e.sessionId === sessId && e.blocked === true) {
+                                    blocks.unshift(e);
+                                }
+                            }
+                            catch {
+                                /* skip malformed */
+                            }
+                        }
+                    }
+                }
+                catch {
+                    /* fail open — empty list */
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ blocks }));
+                return;
+            }
+            // v0.6 M3 — GET /api/task/:id/narration → latest mid-task summary.
+            // Read-only; SessionManager generates the narration in a background
+            // timer and caches the latest. Frontend polls (~30s) while the
+            // session is running.
+            const narrMatch = req.url.match(/^\/api\/task\/([^/]+)\/narration$/);
+            if (narrMatch && req.method === 'GET') {
+                const sessId = narrMatch[1];
+                const narration = manager.getNarration(sessId);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ narration: narration ?? null }));
+                return;
+            }
             // /api/task/:id/events  or  /api/task/:id/kill
             const m = req.url.match(/^\/api\/task\/([^/]+)\/(events|kill|message)$/);
             if (m) {
@@ -740,7 +1153,9 @@ export function startMCPServer(options = {}) {
                         return;
                     }
                     let body = '';
-                    req.on('data', (c) => { body += c.toString('utf-8'); });
+                    req.on('data', (c) => {
+                        body += c.toString('utf-8');
+                    });
                     req.on('end', async () => {
                         try {
                             const parsed = JSON.parse(body || '{}');
@@ -844,12 +1259,116 @@ export function startMCPServer(options = {}) {
             }
             return;
         }
-        // 404
-        res.writeHead(404);
-        res.end();
+        // 404 — friendly HTML page with route list (Bug A6 fix May 6 2026).
+        // Pre-fix: empty body, blank-page failure mode the dogfood walk caught.
+        // Per claim_user_persona HIGH non-technical-first: a non-technical user
+        // who typos a URL gets a useful page back, not a void.
+        const requestedPath = (req.url ?? '/').split('?')[0];
+        res.writeHead(404, { 'Content-Type': 'text/html; charset=utf-8' });
+        res.end(`<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>codehere · page not found</title>
+<style>
+  :root {
+    --bg: #0f0f12;
+    --fg: #f5f5f7;
+    --fg-50: #8b8b94;
+    --fg-30: #5a5a62;
+    --border: #2a2a32;
+    --accent: #ff9a76;
+    --mono: ui-monospace, 'SF Mono', Menlo, monospace;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0; min-height: 100vh;
+    background: var(--bg); color: var(--fg);
+    font-family: Inter, system-ui, -apple-system, 'Segoe UI', sans-serif;
+    display: flex; flex-direction: column; align-items: center; justify-content: center;
+    padding: 48px 24px;
+  }
+  main { max-width: 480px; width: 100%; }
+  .label {
+    font-family: var(--mono); font-size: 11px; letter-spacing: 1.5px;
+    color: var(--fg-30); margin-bottom: 12px;
+  }
+  h1 { font-size: 22px; font-weight: 600; margin: 0 0 12px 0; }
+  .path {
+    font-family: var(--mono); font-size: 13px;
+    color: var(--fg-50); background: rgba(255,255,255,0.04);
+    border: 1px solid var(--border); border-radius: 4px;
+    padding: 6px 10px; display: inline-block; margin-bottom: 28px;
+    word-break: break-all;
+  }
+  .routes {
+    border-top: 1px solid var(--border);
+    padding-top: 24px; margin-top: 8px;
+  }
+  .routes-label {
+    font-family: var(--mono); font-size: 11px; letter-spacing: 1.5px;
+    color: var(--fg-30); margin-bottom: 12px;
+  }
+  .route {
+    display: flex; align-items: baseline; gap: 14px;
+    padding: 8px 0; border-bottom: 1px solid var(--border);
+    text-decoration: none; color: var(--fg);
+  }
+  .route:last-child { border-bottom: none; }
+  .route:hover { background: rgba(255,255,255,0.02); }
+  .route-name { font-weight: 500; }
+  .route-path { font-family: var(--mono); font-size: 12px; color: var(--fg-50); margin-left: auto; }
+</style>
+</head>
+<body>
+<main>
+  <div class="label">404 · NOT FOUND</div>
+  <h1>That page doesn't exist</h1>
+  <div class="path">${escapeHtmlText(requestedPath)}</div>
+  <div class="routes">
+    <div class="routes-label">VALID ROUTES</div>
+    <a class="route" href="/"><span class="route-name">Dashboard</span><span class="route-path">/</span></a>
+    <a class="route" href="/threads"><span class="route-name">Project threads</span><span class="route-path">/threads</span></a>
+    <a class="route" href="/history"><span class="route-name">Audit history</span><span class="route-path">/history</span></a>
+  </div>
+</main>
+</body>
+</html>`);
     });
+    function escapeHtmlText(s) {
+        return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+    }
     server.listen(port, host, () => {
-        // server started
+        // Daemon-start data hygiene — runs once after listen so any failure
+        // doesn't block the server coming up. Both are best-effort.
+        void (async () => {
+            try {
+                const { backfillProjectTitles } = await import('../storage/project-thread-mirror.js');
+                const r = await backfillProjectTitles();
+                if (process.env.CODEHERE_DEBUG === '1' && r.rewritten > 0) {
+                    console.error(`[daemon-start] backfilled ${r.rewritten}/${r.scanned} project titles`);
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+            // Stale-session reconciliation. Walks per-project thread.jsonl files
+            // and marks any sessions stuck in 'running' for >60 min as crashed.
+            // Closes the dogfood-found gap where 3-day-old tasks displayed as
+            // RUNNING in the threads view because a daemon crash never wrote
+            // their completion event.
+            try {
+                const { reconcileStaleProjectTasks } = await import('../storage/project-thread-mirror.js');
+                const r = await reconcileStaleProjectTasks();
+                if (process.env.CODEHERE_DEBUG === '1' && r.reconciled > 0) {
+                    console.error(`[daemon-start] reconciled ${r.reconciled} stale running tasks`);
+                }
+            }
+            catch {
+                /* best-effort */
+            }
+        })();
     });
     return server;
 }