codehere 0.5.0-alpha.2 → 0.5.0-alpha.3

package/dist/application/use-cases/generate-final-report.js

@@ -0,0 +1,144 @@
+/**
+ * Final Report — PM-UX Layer 3 · MVP (v0.5.0-alpha.3+).
+ *
+ * At task exit, generates a 3-paragraph plain-English summary of what the
+ * agent did, what was touched, and what the user should look at. Prints to
+ * stdout so the dogfood-while-building loop sees the artifact immediately.
+ *
+ * Provider strategy (MVP — try free first, fall back to paid):
+ *   - Tries `claude-free --bare -p "<prompt>"` first. The `claude-free`
+ *     wrapper is what actually routes through the FCC proxy at :8082
+ *     (verified 2026-05-02 dogfood: plain `claude --bare` does NOT route
+ *     through FCC — it hits paid Claude. The May 1 memory rule was wrong.)
+ *   - Falls back to `claude --bare -p "<prompt>"` if `claude-free` is not
+ *     installed (paid path; will fail gracefully if no credit).
+ *   - If neither binary is installed, returns null silently (no report).
+ *
+ * Env override: set CODEHERE_REPORT_BINARY=<binary-name> to force a
+ * specific provider (e.g. for testing or non-default setups).
+ *
+ * Iterations 5-9 (2026-05-02) refuted the "we own the supervisory layer"
+ * thesis. Final Report is the keystone delivery moment per the v3 chain
+ * (claim_market_position) — it's the artifact the dogfood loop produces
+ * that none of the surveyed competitors (ComposioHQ, Overstory, Praktor,
+ * Claude Squad, AI-Agents-Orchestrator) advertise.
+ */
+import { spawn } from 'child_process';
+const PROMPT_TEMPLATE = (i) => `You are a PM reporting back to a developer about what their AI coding agent
+just did. Write 3 short paragraphs in plain English. No headers, no bullet
+lists, no markdown — just three paragraphs separated by blank lines.
+
+Paragraph 1: What the agent DID. Verb-led. Name files specifically. 1-3 sentences.
+Paragraph 2: What was TOUCHED. Files modified, line counts, anything that looks risky. 1-3 sentences.
+Paragraph 3: What the developer should LOOK AT. Open concerns, things to verify.
+             If everything looks clean, say so explicitly. 1-2 sentences.
+
+Be specific. Don't pad. Don't editorialize. Don't praise the agent.
+
+The task was: ${i.prompt}
+The agent used: ${i.agent}
+Duration: ${i.durationMs}ms
+Status: ${i.status}
+
+Steps the agent took:
+${i.steps.length ? i.steps.map((s) => `- ${s.label} (${s.state})`).join('\n') : '(no structured steps captured)'}
+
+Files changed:
+${i.artifacts?.files?.length
+    ? i.artifacts.files.map((f) => `- ${f.path} (+${f.added}/-${f.removed}${f.trust !== undefined ? `, trust: ${f.trust}` : ''})`).join('\n')
+    : '(no file artifacts captured)'}
+
+Token usage: ${i.artifacts?.usage?.inputTokens ?? 0} in / ${i.artifacts?.usage?.outputTokens ?? 0} out
+
+Now write the 3 paragraphs.`;
+const REPORT_TIMEOUT_MS = 30_000;
+/** Provider chain: try free first, then paid. Override with CODEHERE_REPORT_BINARY. */
+function selectProviderBinary() {
+    const override = process.env.CODEHERE_REPORT_BINARY;
+    if (override)
+        return [override];
+    return ['claude-free', 'claude'];
+}
+/**
+ * Generate a Final Report. Returns null if no provider is reachable.
+ * Never throws — failure modes return null + log a debug line.
+ */
+export async function generateFinalReport(input) {
+    const prompt = PROMPT_TEMPLATE(input);
+    for (const binary of selectProviderBinary()) {
+        const result = await tryProvider(binary, prompt, input.sessionId);
+        if (result)
+            return result;
+    }
+    return null;
+}
+function tryProvider(binary, prompt, sessionId) {
+    const startedAt = Date.now();
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        const child = spawn(binary, ['--bare', '-p', prompt], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const timeout = setTimeout(() => {
+            child.kill('SIGTERM');
+            if (process.env.CODEHERE_DEBUG === '1') {
+                console.error(`[final-report] ${binary} timeout after ${REPORT_TIMEOUT_MS}ms for ${sessionId}`);
+            }
+            finish(null);
+        }, REPORT_TIMEOUT_MS);
+        child.on('error', (err) => {
+            clearTimeout(timeout);
+            // ENOENT = binary not installed. Silent fallback to next provider in chain.
+            if (process.env.CODEHERE_DEBUG === '1') {
+                console.error(`[final-report] ${binary} unavailable: ${err.message}`);
+            }
+            finish(null);
+        });
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                if (process.env.CODEHERE_DEBUG === '1') {
+                    console.error(`[final-report] ${binary} exited ${code}: ${stderr.slice(0, 200)}`);
+                }
+                finish(null);
+                return;
+            }
+            const summary = stdout.trim();
+            if (!summary) {
+                finish(null);
+                return;
+            }
+            finish({ summary, generatedAt: Date.now(), durationMs: Date.now() - startedAt });
+        });
+    });
+}
+/**
+ * Pretty-print to terminal. Used by session-manager when a spawned task exits.
+ * Wrapped in try/catch upstream — never let a print failure surface.
+ */
+export function printFinalReportToTerminal(input, output) {
+    const banner = '─'.repeat(60);
+    process.stdout.write('\n');
+    process.stdout.write(`${banner}\n`);
+    process.stdout.write(`Final Report · ${input.agent} · ${input.sessionId.slice(0, 8)}\n`);
+    process.stdout.write(`${banner}\n`);
+    process.stdout.write(`${output.summary}\n`);
+    process.stdout.write(`${banner}\n`);
+    process.stdout.write(`(generated in ${output.durationMs}ms)\n`);
+    process.stdout.write('\n');
+}
+//# sourceMappingURL=generate-final-report.js.map

package/dist/index.js

@@ -139,7 +139,7 @@ program
 // trust-scorer pattern bank to .codehere/protocols/hook_patterns.json so
 // auditors / cross-tool consumers can read codehere's safety surface.
 program
-    .command('protocols')
+    .command('protocols', { hidden: true }) // hidden from --help (May 2 cut: power-user F3 export, see docs/MEMORY.md)
     .description('F3 protocols layer · export (write hook_patterns.json from trust-scorer bank)')
     .argument('[action]', 'Action: export, help')
     .option('--rebuild', 'Refresh built-in patterns (project patterns are preserved)')
@@ -345,7 +345,7 @@ program
 // ── serve (MCP server) ───────────────────────────────────────────────────────
 program
     .command('serve')
-    .description('Start codehere as an MCP server — expose trust tools to Claude Desktop, Cursor, and any MCP client')
+    .description('Run codehere as a background MCP server (no web UI) — for Claude Desktop / Cursor integration')
     .option('-p, --port <number>', 'Port to listen on', '3773')
     .option('--host <host>', 'Host to bind to (default: 127.0.0.1)', '127.0.0.1')
     .option('--token <token>', 'Require Bearer token for authentication')
@@ -406,7 +406,7 @@ program
 // ── start (Mission Control: daemon + web UI) ─────────────────────────────────
 program
     .command('start')
-    .description('Start the codehere daemon — task intake UI + MCP server at localhost:3773')
+    .description('Start codehere — interactive PM dashboard at localhost:3773 (delegate tasks, watch agents work)')
     .option('-p, --port <number>', 'Port to listen on', '3773')
     .option('--host <host>', 'Host to bind to', '127.0.0.1')
     .option('--no-open', "Don't auto-open the browser")
@@ -599,7 +599,7 @@ program
 });
 // ── scan-tool (called by Claude Code hooks system, not users directly) ───────
 program
-    .command('scan-tool')
+    .command('scan-tool', { hidden: true }) // hidden from --help (May 2 cut: internal hook handler, called by Claude Code via stdin)
     .description('Hook handler: reads Claude Code tool event from stdin, outputs block/allow (used by hook system)')
     .option('--log-only', 'Never block, log only')
     .option('--block-all', 'Block on any finding, not just critical')
@@ -613,7 +613,7 @@ program
 });
 // ── completion (shell completion script generator) ──────────────────────────
 program
-    .command('completion')
+    .command('completion', { hidden: true }) // hidden from --help (May 2 cut: shell-completion is npm convention, not product surface)
     .description('Generate shell completion script')
     .argument('<shell>', 'Shell type: bash, zsh, or fish')
     .action(async (shell) => {

package/dist/infrastructure/orchestration/claude-code-adapter.js

@@ -284,6 +284,7 @@ export function spawnClaudeCode(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'claude-code',
+        canAppendMessage: true,
         memoryInjection: injected.record,
         get status() {
             return statusValue;
@@ -317,6 +318,66 @@ export function spawnClaudeCode(prompt, options = {}) {
                 }
             }, 3000);
         },
+        /**
+         * Iter 12 — follow-up message to a completed session. Spawns a fresh
+         * `claude -p "<text>" -c` in the same cwd, which uses Claude Code's
+         * native -c flag to continue the most recent conversation in that dir.
+         *
+         * Scope: one-shot Q&A. No streaming, no event piping into the parent
+         * emitter. Returns the assistant's response text. Iter 13 may upgrade
+         * to a true thread-streaming model if the dogfood signal warrants.
+         */
+        appendMessage(text) {
+            const startedAt = Date.now();
+            return new Promise((resolve, reject) => {
+                let stdout = '';
+                let stderr = '';
+                const followup = spawn('claude', ['-p', text, '-c', ...HEADLESS_FLAGS], {
+                    cwd,
+                    env: spawnEnv,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                followup.on('error', (err) => reject(err));
+                followup.stdout?.on('data', (chunk) => {
+                    stdout += chunk.toString('utf-8');
+                });
+                followup.stderr?.on('data', (chunk) => {
+                    stderr += chunk.toString('utf-8');
+                });
+                followup.on('exit', (code) => {
+                    if (code !== 0) {
+                        reject(new Error(`claude -c exited ${code}: ${stderr.slice(0, 200)}`));
+                        return;
+                    }
+                    // Parse stream-json — extract assistant message text from the
+                    // 'assistant' typed lines and the final 'result' line.
+                    const lines = stdout.split('\n').filter((l) => l.trim());
+                    const fragments = [];
+                    for (const line of lines) {
+                        try {
+                            const obj = JSON.parse(line);
+                            if (obj.type === 'assistant' && obj.message?.content) {
+                                for (const block of obj.message.content) {
+                                    if (block.type === 'text' && block.text)
+                                        fragments.push(block.text);
+                                }
+                            }
+                            else if (obj.type === 'result' && typeof obj.result === 'string') {
+                                fragments.push(obj.result);
+                            }
+                        }
+                        catch {
+                            // Non-JSON line — skip
+                        }
+                    }
+                    // Dedupe trivially: if 'result' contained the same text as the
+                    // last assistant block, take just one. Conservative: prefer 'result'
+                    // if present (it's the final summary), else join assistants.
+                    const result = fragments.length ? fragments[fragments.length - 1] : '(no response captured)';
+                    resolve({ result, durationMs: Date.now() - startedAt });
+                });
+            });
+        },
     };
 }
 // ── AgentAdapter implementation ─────────────────────────────────────────────

package/dist/infrastructure/orchestration/session-manager.js

@@ -23,6 +23,7 @@ import { buildConductorAdapter } from './conductor-adapter.js';
 import { seedAgentsConfig } from './agents-config-seed.js';
 import { AUDIT_FILE } from '../hooks/claude-sdk-hook.js';
 import { appendSpawned, appendCompleted, loadRecent } from './session-persistence.js';
+import { generateFinalReport, printFinalReportToTerminal } from '../../application/use-cases/generate-final-report.js';
 // ── Agent registry ─────────────────────────────────────────────────────────────
 // All backends codehere can spawn. Order here drives the default UI dropdown
 // order. Built-in adapters first; user-config-driven ones appended from
@@ -96,6 +97,18 @@ export class SessionManager {
      *  These subprocesses are long-dead; we surface them so the user doesn't lose
      *  their Final reports across restarts. */
     persistedCache = loadRecent(20);
+    /** When a spawned session exits, we capture the completion timestamp here
+     *  so the API layer can show duration on still-in-memory sessions (the
+     *  TaskSession interface intentionally has no completedAt; only PersistedSession
+     *  does, so anything reading session.completedAt got undefined pre-fix).
+     *  Surfaced May 2 by the cold-start dogfood — `duration: NaNs` in /api/tasks
+     *  for completed-but-not-yet-restarted sessions. Bug 2 sister-fix. */
+    completedAtBySession = new Map();
+    /** PM-UX Layer 3 · Final Report cache (iteration 11 MVP, UI-integration iter 12).
+     *  Populated when generateFinalReport resolves in the exit handler. Web UI
+     *  reads via getFinalReport() through the /api/tasks serializer so non-technical
+     *  users see the prose summary without opening a terminal. */
+    finalReportBySession = new Map();
     spawn(prompt, agentId = 'claude-code', options) {
         const adapter = getAdapter(agentId);
         if (!adapter) {
@@ -121,14 +134,50 @@ export class SessionManager {
             if (event.type !== 'exit')
                 return;
             const data = event.data;
+            const completedAt = Date.now();
+            // Surface completedAt to API consumers reading the still-in-memory
+            // session (Bug 2 sister-fix, May 2). Without this, /api/tasks shows
+            // status=completed but no completedAt → NaN duration in the UI.
+            this.completedAtBySession.set(session.sessionId, completedAt);
             appendCompleted({
                 id: session.sessionId,
                 status: session.status,
-                durationMs: Number(data?.durationMs ?? Date.now() - session.startedAt),
-                completedAt: Date.now(),
+                durationMs: Number(data?.durationMs ?? completedAt - session.startedAt),
+                completedAt,
                 steps: session.steps ? [...session.steps] : undefined,
                 artifacts: session.artifacts,
             });
+            // PM-UX Layer 3 · Final Report MVP. Fire-and-forget; the report appears
+            // in the terminal a few seconds after exit. Failure modes return null
+            // silently (claude CLI not installed, timeout, non-zero exit). No SSE,
+            // no UI integration in this MVP — terminal output only so the dogfood
+            // loop sees the artifact immediately. See `generate-final-report.ts`.
+            const reportInput = {
+                sessionId: session.sessionId,
+                prompt: session.prompt,
+                agent: session.agent,
+                status: session.status,
+                durationMs: completedAt - session.startedAt,
+                steps: session.steps ? [...session.steps] : [],
+                artifacts: session.artifacts,
+            };
+            generateFinalReport(reportInput)
+                .then((report) => {
+                if (report) {
+                    // Cache for web UI consumption via /api/tasks (iter 12 — non-technical
+                    // users live in the web UI, not the terminal).
+                    this.finalReportBySession.set(session.sessionId, report);
+                    try {
+                        printFinalReportToTerminal(reportInput, report);
+                    }
+                    catch {
+                        // Don't let a print failure crash the daemon.
+                    }
+                }
+            })
+                .catch(() => {
+                // generateFinalReport never throws by contract; defensive only.
+            });
             unsubscribe();
         });
         return session;
@@ -137,6 +186,20 @@ export class SessionManager {
     listPersisted() {
         return this.persistedCache;
     }
+    /** Completion timestamp for an in-memory session, if it has exited.
+     *  Returns undefined if the session is still running OR was never spawned
+     *  through this manager. Bug 2 sister-fix (May 2): TaskSession itself has
+     *  no completedAt field; this method lets the API layer compute durations. */
+    getCompletedAt(sessionId) {
+        return this.completedAtBySession.get(sessionId);
+    }
+    /** PM-UX Layer 3 · prose Final Report for an in-memory exited session.
+     *  Returns undefined while generation is in flight OR if the provider chain
+     *  failed (no claude-free, no claude, no credit, etc). The web UI reads this
+     *  through the /api/tasks serializer to render the prose summary inline. */
+    getFinalReport(sessionId) {
+        return this.finalReportBySession.get(sessionId);
+    }
     get(sessionId) {
         return this.sessions.get(sessionId);
     }

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

@@ -548,16 +548,29 @@ export function startMCPServer(options = {}) {
                 return;
             }
             if (req.method === 'GET' && req.url === '/api/tasks') {
-                const spawned = manager.list().map((s) => ({
-                    sessionId: s.sessionId,
-                    prompt: s.prompt,
-                    startedAt: s.startedAt,
-                    status: s.status,
-                    agent: s.agent,
-                    steps: s.steps ?? [],
-                    artifacts: s.artifacts,
-                    provenance: 'spawned',
-                }));
+                const spawned = manager.list().map((s) => {
+                    // Bug 2 sister-fix (May 2): include completedAt for in-memory exited
+                    // sessions so the UI can compute duration. TaskSession interface
+                    // intentionally lacks completedAt; SessionManager tracks it separately
+                    // in completedAtBySession map (populated when exit event fires).
+                    const completedAt = manager.getCompletedAt(s.sessionId);
+                    const finalReport = manager.getFinalReport(s.sessionId);
+                    return {
+                        sessionId: s.sessionId,
+                        prompt: s.prompt,
+                        startedAt: s.startedAt,
+                        status: s.status,
+                        agent: s.agent,
+                        steps: s.steps ?? [],
+                        artifacts: s.artifacts,
+                        ...(completedAt !== undefined ? { completedAt, durationMs: completedAt - s.startedAt } : {}),
+                        ...(finalReport !== undefined ? { finalReport } : {}),
+                        // Iter 12 — surface canAppendMessage so the UI knows whether to
+                        // render the reply input or a disabled "follow-up unsupported" state.
+                        canAppendMessage: s.canAppendMessage === true,
+                        provenance: 'spawned',
+                    };
+                });
                 const activeAgents = manager.listActiveAgents();
                 const persisted = manager.listPersisted();
                 // Layer 7: timestamp of most recent hook-audit line (= "last edit on this machine")
@@ -581,7 +594,7 @@ export function startMCPServer(options = {}) {
                 return;
             }
             // /api/task/:id/events  or  /api/task/:id/kill
-            const m = req.url.match(/^\/api\/task\/([^/]+)\/(events|kill)$/);
+            const m = req.url.match(/^\/api\/task\/([^/]+)\/(events|kill|message)$/);
             if (m) {
                 const [, sessionId, verb] = m;
                 const session = manager.get(sessionId);
@@ -612,6 +625,38 @@ export function startMCPServer(options = {}) {
                     res.end(JSON.stringify({ sessionId, status: session.status }));
                     return;
                 }
+                // Iter 12 — POST /api/task/:id/message — follow-up message to a
+                // completed session. The reply-to-thread surface in the web UI calls
+                // this. Body: { text }. Response: { result, durationMs }.
+                if (verb === 'message' && req.method === 'POST') {
+                    if (!session.canAppendMessage || !session.appendMessage) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: `Agent ${session.agent} does not support follow-up messages yet.` }));
+                        return;
+                    }
+                    let body = '';
+                    req.on('data', (c) => { body += c.toString('utf-8'); });
+                    req.on('end', async () => {
+                        try {
+                            const parsed = JSON.parse(body || '{}');
+                            const text = (parsed.text ?? '').trim();
+                            if (!text) {
+                                res.writeHead(400, { 'Content-Type': 'application/json' });
+                                res.end(JSON.stringify({ error: 'text is required' }));
+                                return;
+                            }
+                            const out = await session.appendMessage(text);
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ sessionId, ...out }));
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            res.writeHead(500, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({ error: msg }));
+                        }
+                    });
+                    return;
+                }
             }
             res.writeHead(405, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Method not allowed for this path' }));

package/dist/infrastructure/protocols/ui-page.js

@@ -253,6 +253,31 @@ const SHARED_STYLES = `
     color: var(--fg-40); text-transform: uppercase; letter-spacing: 0.12em; font-size: 10px;
     margin-bottom: 8px;
   }
+  /* Iter 12 — prose summary block. Plain English for non-technical users.
+     Sans-serif breaks the monospace context so it reads as narrative, not data. */
+  .final-report .fr-summary {
+    font-family: var(--sans);
+    font-size: 13px;
+    line-height: 1.55;
+    color: var(--fg);
+    margin-bottom: 12px;
+    padding-bottom: 12px;
+    border-bottom: 1px solid var(--border-soft);
+  }
+  .final-report .fr-summary p {
+    margin: 0 0 10px 0;
+  }
+  .final-report .fr-summary p:last-child { margin-bottom: 0; }
+  .final-report .fr-summary-pending p {
+    color: var(--fg-50);
+    font-style: italic;
+    animation: shimmer 1.6s linear infinite;
+    background: linear-gradient(90deg, var(--fg-30) 0%, var(--fg-70) 50%, var(--fg-30) 100%);
+    background-size: 200% auto;
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent;
+  }
   .final-report .fr-files { display: flex; flex-direction: column; gap: 3px; }
   .final-report .fr-file {
     display: grid;
@@ -1091,8 +1116,30 @@ ${SHARED_STYLES}
     color: var(--fg-50); font-size: 11px; font-family: var(--mono);
     display: flex; align-items: center; gap: 8px;
   }
-  .thread-input::before { content: '↳'; color: var(--fg-30); }
-  .thread-input .scaffold-note { color: var(--fg-30); font-size: 10px; margin-left: auto; }
+  /* Iter 12 — reply surface now functional. Wraps textarea + send button. */
+  .thread-input { padding: 8px; flex-direction: column; align-items: stretch; gap: 6px; }
+  .thread-input::before { display: none; }
+  .thread-input .reply-text {
+    width: 100%; min-height: 38px; resize: vertical;
+    background: transparent; border: 0; outline: none;
+    color: var(--fg); font-family: var(--sans); font-size: 12px; line-height: 1.5;
+    padding: 4px 0;
+  }
+  .thread-input .reply-text::placeholder { color: var(--fg-30); }
+  .thread-input .reply-send {
+    align-self: flex-end;
+    padding: 5px 14px; border-radius: 6px;
+    background: var(--accent-wash); color: var(--accent);
+    border: 1px solid rgba(255,154,118,0.25);
+    font-family: var(--sans); font-size: 11px; font-weight: 600;
+    cursor: pointer;
+  }
+  .thread-input .reply-send:hover { background: rgba(255,154,118,0.18); }
+  .thread-input .reply-send:disabled { opacity: 0.4; cursor: default; }
+  .thread-input .reply-status { color: var(--fg-50); font-size: 10px; font-family: var(--mono); }
+  .thread-input .reply-status.error { color: var(--block); }
+  .thread-input.disabled .reply-text,
+  .thread-input.disabled .reply-send { opacity: 0.5; cursor: not-allowed; }
 
   .view-toggle {
     display: inline-flex; gap: 0;
@@ -1165,7 +1212,7 @@ ${SHARED_STYLES}
       </div>
     </div>
   </div>
-  <button class="pane-add" type="button" title="Coming soon">+ New project</button>
+  <button class="pane-add" type="button" id="new-project-btn" title="Set a new working folder for the next task">+ New project</button>
 </aside>
 
 <section class="thread-pane">
@@ -1459,11 +1506,37 @@ ${SHARED_STYLES}
     list.innerHTML = all.map((a) => {
       const cls = presenceCls(a.state);
       const glyph = presenceGlyph(a.state);
-      return '<div class="member" title="' + escape(a.state || 'unknown') + '">' +
+      // Iter 12 — members are now clickable. Non-technical user expects
+      // clicking an agent in the right pane to pick that agent for the
+      // next task. Click handler below sets the agent <select> + scrolls
+      // intake into view + focuses the prompt textarea.
+      const stateTitle = a.state === 'ready' ? 'ready · click to select' :
+                         a.state === 'needs_install' ? 'needs install · click for setup' :
+                         a.state === 'needs_auth' ? 'needs auth · click for setup' :
+                         (a.state || 'unknown');
+      return '<div class="member" data-agent-id="' + escape(a.id) + '" title="' + escape(stateTitle) + '">' +
         '<span class="member-presence ' + cls + '">' + glyph + '</span>' +
         '<span class="member-label">' + escape(a.label || a.id) + '</span>' +
       '</div>';
     }).join('');
+    // Wire click → select-this-agent. One delegated handler is cheaper than
+    // attaching one per item, and survives re-renders without leak.
+    list.onclick = (ev) => {
+      const item = ev.target && ev.target.closest && ev.target.closest('.member');
+      if (!item) return;
+      const id = item.getAttribute('data-agent-id');
+      if (!id) return;
+      // Set the agent dropdown to this agent. Trigger 'change' so the
+      // updateSetupPanel code (existing) fires and shows install/auth help
+      // for needs_install / needs_auth states.
+      if (agentSelect) {
+        agentSelect.value = id;
+        try { agentSelect.dispatchEvent(new Event('change')); } catch { /* old browsers */ }
+      }
+      // Scroll intake into view + focus the prompt textarea.
+      try { promptEl && promptEl.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch { /* noop */ }
+      if (promptEl) promptEl.focus();
+    };
   }
 
   fetch('/api/readiness/agents').then(r => r.json()).then(d => {
@@ -1496,6 +1569,23 @@ ${SHARED_STYLES}
     localStorage.setItem('codehere:cwd', cwdInput.value.trim());
   });
 
+  // Iter 12 — "+ New project" button now wired. Previously dead chrome with
+  // title="Coming soon". Multi-project sidebar is iter 13+; for now the button
+  // does the simplest useful thing: clear the cwd input + scroll-and-focus
+  // so the user can type a new folder path. The intake form's existing Assign
+  // flow handles spawning the task in that path.
+  const newProjectBtn = document.getElementById('new-project-btn');
+  if (newProjectBtn) {
+    newProjectBtn.addEventListener('click', () => {
+      cwdInput.value = '';
+      localStorage.removeItem('codehere:cwd');
+      // Smooth-scroll the intake form into view (project sidebar is on the left,
+      // intake is on the right; on narrow screens the user might be scrolled).
+      try { cwdInput.scrollIntoView({ behavior: 'smooth', block: 'center' }); } catch { /* old browsers */ }
+      cwdInput.focus();
+    });
+  }
+
   // Gate A1: starter-prompt chips prefill the textarea + focus it so the user
   // can edit or hit ⌘-Enter immediately. No scroll-jumping, no redirect.
   const starterPromptsEl = document.getElementById('starter-prompts');
@@ -1731,7 +1821,15 @@ ${SHARED_STYLES}
         // seed prompt, breaking chronological order in thread view.
         '<div class="thread-messages"></div>' +
         '<div class="final-report" style="display:none"></div>' +
-        '<div class="thread-input">Reply to thread <span class="scaffold-note">(coming soon)</span></div>' +
+        // Iter 12 — reply surface now functional; replaced the prior dead
+        // placeholder. Active for adapters with canAppendMessage=true
+        // (claude-code today); disabled state for adapters that don't yet
+        // implement appendMessage.
+        '<div class="thread-input">' +
+          '<textarea class="reply-text" placeholder="Reply to thread… (Cmd+Enter to send)" rows="2"></textarea>' +
+          '<button class="reply-send" type="button">Send</button>' +
+          '<div class="reply-status" style="display:none"></div>' +
+        '</div>' +
         '<div class="event-log"></div>' +
       '</div>';
 
@@ -1746,6 +1844,57 @@ ${SHARED_STYLES}
     const finalReportEl = card.querySelector('.final-report');
     const threadEl = card.querySelector('.thread-messages');
     const bodyEl = card.querySelector('.session-body');
+    // Iter 12 — reply-to-thread refs + handler.
+    const threadInputEl = card.querySelector('.thread-input');
+    const replyTextEl = card.querySelector('.reply-text');
+    const replySendBtn = card.querySelector('.reply-send');
+    const replyStatusEl = card.querySelector('.reply-status');
+    if (!session.canAppendMessage) {
+      threadInputEl.classList.add('disabled');
+      replyTextEl.placeholder = 'Reply unsupported for ' + agentLabel(session.agent) + ' yet';
+      replyTextEl.disabled = true;
+      replySendBtn.disabled = true;
+    } else {
+      const sendReply = async () => {
+        const text = (replyTextEl.value || '').trim();
+        if (!text) return;
+        replySendBtn.disabled = true;
+        replySendBtn.textContent = '...';
+        replyStatusEl.style.display = 'none';
+        replyStatusEl.classList.remove('error');
+        // Optimistic: render the user's message immediately in the thread.
+        appendThreadMessage(threadMessage({
+          cls: 'user', author: 'You', time: new Date(), content: text,
+        }));
+        replyTextEl.value = '';
+        try {
+          const r = await fetch('/api/task/' + session.sessionId + '/message', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ text }),
+          });
+          const data = await r.json();
+          if (!r.ok) throw new Error(data.error || ('HTTP ' + r.status));
+          // Render assistant response in the thread.
+          appendThreadMessage(threadMessage({
+            cls: 'agent', author: agentLabel(session.agent), time: new Date(),
+            content: String(data.result || '(empty response)'),
+          }));
+        } catch (err) {
+          replyStatusEl.textContent = 'Reply failed: ' + (err && err.message ? err.message : String(err));
+          replyStatusEl.classList.add('error');
+          replyStatusEl.style.display = 'block';
+        } finally {
+          replySendBtn.disabled = false;
+          replySendBtn.textContent = 'Send';
+          replyTextEl.focus();
+        }
+      };
+      replySendBtn.addEventListener('click', sendReply);
+      replyTextEl.addEventListener('keydown', (ev) => {
+        if ((ev.metaKey || ev.ctrlKey) && ev.key === 'Enter') { ev.preventDefault(); sendReply(); }
+      });
+    }
     const safetyPillEl = card.querySelector('.safety-pill');
     const safetySafeEl = safetyPillEl.querySelector('.safe');
     const safetyBlockedEl = safetyPillEl.querySelector('.blocked');
@@ -1939,12 +2088,35 @@ ${SHARED_STYLES}
     // Layer 3: render the final report block when the task completes.
     // Principles #2 + #7 — density (files/tests/trust in one view) and
     // agent-provenance (the report attributes to a specific agent).
-    function renderArtifacts(artifacts) {
-      if (!artifacts) { finalReportEl.style.display = 'none'; return; }
+    // Iter 12 — prose summary (3 paragraphs, plain English) prepended above
+    // the artifact list. Non-technical users see prose first; raw artifact
+    // detail (files/tests/tokens) below as supporting context.
+    function renderArtifacts(artifacts, finalReport, status) {
+      // Show the block if either prose summary OR artifacts exist OR if a
+      // completed task is still generating its report (placeholder state).
+      const isCompleted = status === 'completed' || status === 'killed' || status === 'error';
+      const hasContent = artifacts || finalReport;
+      const isAwaitingReport = isCompleted && !finalReport;
+      if (!hasContent && !isAwaitingReport) { finalReportEl.style.display = 'none'; return; }
       finalReportEl.style.display = 'block';
-      const files = Array.isArray(artifacts.files) ? artifacts.files : [];
-      const tests = artifacts.tests;
+      const files = Array.isArray(artifacts?.files) ? artifacts.files : [];
+      const tests = artifacts?.tests;
       let html = '<div class="fr-label">Final report · ' + escape(agentLabel(session.agent)) + '</div>';
+      if (finalReport && finalReport.summary) {
+        // Plain-English prose. Split paragraphs on blank lines, render each as <p>.
+        // NOTE: this code is inside a TS template literal — backslashes in
+        // regex literals must be doubled so the served JS gets the right
+        // sequence (test/cli/ui-served-html-syntax.test.ts guards this).
+        const paragraphs = String(finalReport.summary).split(/\\n\\s*\\n/).filter(p => p.trim());
+        html += '<div class="fr-summary">' +
+          paragraphs.map(p => '<p>' + escape(p.trim()) + '</p>').join('') +
+          '</div>';
+      } else if (isAwaitingReport) {
+        // Placeholder — task done, report still generating (or provider failed silently).
+        // After ~30s with no report, the placeholder persists. Iter 13 will replace
+        // with explicit "report unavailable — start FCC proxy or set ANTHROPIC_API_KEY".
+        html += '<div class="fr-summary fr-summary-pending"><p>Generating report…</p></div>';
+      }
       if (files.length > 0) {
         html += '<div class="fr-files">' + files.map(f => {
           const lines = '<span class="add">+' + (f.added || 0) + '</span> <span class="rem">−' + (f.removed || 0) + '</span>';
@@ -1978,7 +2150,11 @@ ${SHARED_STYLES}
 
     // Hydrate from initial snapshot (late-joiner support + persisted sessions)
     if (Array.isArray(session.steps) && session.steps.length) renderSteps(session.steps);
-    if (session.artifacts) renderArtifacts(session.artifacts);
+    // Render Final Report block if there's anything to show (prose summary,
+    // artifacts, or "generating…" placeholder for a freshly-completed session).
+    if (session.artifacts || session.finalReport || session.status === 'completed' || session.status === 'killed' || session.status === 'error') {
+      renderArtifacts(session.artifacts, session.finalReport, session.status);
+    }
 
     // Persisted sessions have no live event stream and no subprocess to kill.
     if (isPersisted) {
@@ -1994,7 +2170,7 @@ ${SHARED_STYLES}
 
         // Layer 2/3 synthetic events — handle before renderEvent (so they don't leak into the raw log)
         if (event.type === 'codehere:steps') { renderSteps(event.data?.steps); return; }
-        if (event.type === 'codehere:artifacts') { renderArtifacts(event.data); return; }
+        if (event.type === 'codehere:artifacts') { renderArtifacts(event.data, undefined, session.status); return; }
 
         // Any structured error flips the status pill immediately — don't wait for
         // the subprocess to exit. Many CLIs print a logical error to stdout and
@@ -2032,7 +2208,10 @@ ${SHARED_STYLES}
       killBtn.textContent = 'Kill';
     });
 
-    sessions.set(session.sessionId, { card, logEl, es });
+    // Iter 12 — expose renderArtifacts so the polling loop can refresh the
+    // Final Report block when the prose summary arrives async (~2-5s after
+    // task exit). Without this, non-technical users would have to refresh.
+    sessions.set(session.sessionId, { card, logEl, es, renderArtifacts });
   }
 
   async function assignTask() {
@@ -2181,7 +2360,10 @@ ${SHARED_STYLES}
     }).catch(() => { /* fine */ });
   }
   loadSessions();
-  // Refresh detected-agents list + banner every 5s
+  // Refresh detected-agents list + banner every 5s. Iter 12 — also patches
+  // existing session cards with new finalReport prose when it arrives async.
+  // Cheap re-render (innerHTML on a small div); non-technical user sees the
+  // report appear on its own, no manual refresh.
   setInterval(() => {
     fetch('/api/tasks').then(r => r.json()).then(d => {
       const seen = new Set();
@@ -2191,6 +2373,13 @@ ${SHARED_STYLES}
       }
       pruneStaleAgents(seen);
       updateBanner(d);
+      // Patch existing session cards with finalReport when it arrives.
+      for (const s of (d.spawned || d.sessions || [])) {
+        const entry = sessions.get(s.sessionId);
+        if (entry && entry.renderArtifacts) {
+          entry.renderArtifacts(s.artifacts, s.finalReport, s.status);
+        }
+      }
     }).catch(() => { /* fine */ });
   }, 5000);
 

package/dist/presentation/cli/commands/init-command.js

@@ -550,8 +550,11 @@ export function executeInitCommand(options = {}) {
         console.log(`  1. Open ${colors.cyan('.codehere/CONTEXT.md')} and fill in what this repo is`);
         console.log(`  2. Run ${colors.cyan('codehere start')} and delegate your first task`);
         console.log(`  3. Track in-flight work in ${colors.cyan('.codehere/HANDOVER.md')} as you go`);
-        console.log(`  ${colors.dim('Inspect what gets injected at spawn:')} ${colors.cyan('codehere memory show injection')}`);
-        console.log(`  ${colors.dim('To adopt the F3 canonical layout (AGENTS.md / memory/working/session.md / skills/), run:')} ${colors.cyan('codehere memory init')}`);
+        // Power-user / advanced layout entry points moved to docs/advanced/ per the
+        // "one canonical entry" rule (May 2 CUT pass). Used to print two extra
+        // dim lines pointing at `codehere memory show injection` and the F3
+        // canonical layout migration — both confused new users in real-task
+        // dogfood. Power users find them in docs/MEMORY.md.
         newline();
     }
     catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "0.5.0-alpha.2",
+  "version": "0.5.0-alpha.3",
   "description": "A PM for your AI coding agents. Delegate, orchestrate, and audit Claude Code, Codex, Aider, OpenCode, Gemini, and any user-configured CLI agent from one local web UI — every AI action traced, every file scored, every spawn warmed with project memory.",
   "main": "dist/index.js",
   "type": "module",