codehere 0.5.0-alpha.2 → 0.5.0-alpha.4

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

@@ -14,6 +14,7 @@ import { Command } from 'commander';
 import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { homedir } from 'os';
 import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
 import { executeInitCommand } from './presentation/cli/commands/init-command.js';
 import { executeMemoryCommand } from './presentation/cli/commands/memory-command.js';
@@ -139,7 +140,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 +346,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 +407,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")
@@ -428,6 +429,25 @@ program
         }
     };
     try {
+        // v0.6.0 M1+M7 — migrate sessions.jsonl → ~/.codehere/projects/<slug>/thread.jsonl
+        // on daemon start. Idempotent: skips projects whose thread.jsonl already exists,
+        // so this is safe to run on every boot. Opt-out via CODEHERE_DISABLE_THREAD_MIGRATION=1.
+        // Failures are non-blocking — back-compat to v0.5 sessions.jsonl is preserved.
+        if (process.env.CODEHERE_DISABLE_THREAD_MIGRATION !== '1') {
+            try {
+                const { migrate } = await import('./infrastructure/storage/project-thread-migration.js');
+                const result = migrate({
+                    sourceJsonl: join(homedir(), '.codehere/sessions.jsonl'),
+                    targetDir: join(homedir(), '.codehere/projects'),
+                });
+                if (result.threadsWritten > 0) {
+                    console.log(colors.dim(`  v0.6 migration: created ${result.threadsWritten} project thread(s) from ${result.sessionsProcessed} sessions (${result.durationMs}ms)`));
+                }
+            }
+            catch (err) {
+                console.warn(colors.dim(`  v0.6 migration skipped: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        }
         const { startMCPServer } = await import('./infrastructure/protocols/mcp-server-impl.js');
         const server = startMCPServer({ port, host });
         // Wait for the server to either start listening or fail. The default
@@ -597,9 +617,44 @@ program
         r.end();
     });
 });
+// ── migrate-threads — v0.6.0 schema migration sessions.jsonl → projects/<slug>/thread.jsonl
+program
+    .command('migrate-threads', { hidden: true }) // hidden from --help (v0.6.0 internal — auto-runs on daemon start once wired)
+    .description('Migrate sessions.jsonl into per-project thread.jsonl files (v0.6.0 schema)')
+    .option('--source <path>', 'Source sessions.jsonl', `${homedir()}/.codehere/sessions.jsonl`)
+    .option('--target <dir>', 'Target projects dir', `${homedir()}/.codehere/projects`)
+    .option('--dry-run', 'Report what migrate WOULD do, write nothing', false)
+    .option('--rollback', 'Remove the projects dir; sessions.jsonl untouched', false)
+    .option('--keep-temp-dirs', 'Include /tmp + /var/folders cwds (default skips them)', false)
+    .action(async (options) => {
+    const { migrate, dryRun, rollback } = await import('./infrastructure/storage/project-thread-migration.js');
+    if (options.rollback) {
+        const r = rollback(options.target);
+        console.log(`Rollback: removed ${r.removedDirs} project dir(s) from ${options.target}`);
+        console.log(`Source ${options.source} untouched.`);
+        return;
+    }
+    const fn = options.dryRun ? dryRun : migrate;
+    const label = options.dryRun ? 'DRY RUN' : 'MIGRATION';
+    const result = fn({
+        sourceJsonl: options.source,
+        targetDir: options.target,
+        skipTempDirs: !options.keepTempDirs,
+    });
+    console.log(`=== ${label} ===`);
+    console.log(`  source:                  ${options.source}`);
+    console.log(`  target:                  ${options.target}`);
+    console.log(`  sessions processed:      ${result.sessionsProcessed}`);
+    console.log(`  threads ${options.dryRun ? 'would write' : 'written'}:   ${result.threadsWritten}`);
+    console.log(`  threads skipped (exist): ${result.threadsSkippedExisting}`);
+    console.log(`  unknown-cwd sessions:    ${result.unknownCwdSessions}`);
+    console.log(`  abandoned sessions:      ${result.abandonedSessions}`);
+    console.log(`  temp-dir sessions skipped: ${result.tempDirSessionsSkipped}`);
+    console.log(`  duration:                ${result.durationMs}ms`);
+});
 // ── 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 +668,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

@@ -221,6 +221,12 @@ export function spawnClaudeCode(prompt, options = {}) {
     }
     // ── stdout: newline-delimited JSON from `--output-format stream-json` ────────
     let stdoutBuf = '';
+    // Iter 13 — capture the claude-internal session_id from the init event so
+    // appendMessage can use `--resume <session-id>` (reliable) instead of `-c`
+    // (which picks "most recent in cwd" and can collide with other concurrent
+    // claude sessions OR with conversations containing thinking blocks the
+    // headless API can't replay).
+    let claudeSessionId;
     child.stdout?.on('data', (chunk) => {
         stdoutBuf += chunk.toString('utf-8');
         let idx;
@@ -231,6 +237,12 @@ export function spawnClaudeCode(prompt, options = {}) {
                 continue;
             try {
                 const data = JSON.parse(line);
+                if (claudeSessionId === undefined &&
+                    data.type === 'system' &&
+                    data.subtype === 'init' &&
+                    typeof data.session_id === 'string') {
+                    claudeSessionId = data.session_id;
+                }
                 emit({ type: data.type ?? 'message', timestamp: Date.now(), data });
             }
             catch {
@@ -284,6 +296,7 @@ export function spawnClaudeCode(prompt, options = {}) {
         startedAt,
         prompt,
         agent: 'claude-code',
+        canAppendMessage: true,
         memoryInjection: injected.record,
         get status() {
             return statusValue;
@@ -317,6 +330,77 @@ export function spawnClaudeCode(prompt, options = {}) {
                 }
             }, 3000);
         },
+        /**
+         * Iter 12 (with iter-13 fix) — follow-up message to a completed session.
+         *
+         * Iter 12 used `claude -p "<text>" -c` which picks "most recent
+         * conversation in current directory". Iter 13 dogfood proved this
+         * fragile: in a cwd with multiple concurrent claude sessions OR with
+         * conversations containing thinking blocks, -c either picks the wrong
+         * session or hits an API-replay error ("Invalid signature in thinking
+         * block"). Fix: capture the claude session_id from this session's init
+         * event (above) and use `--resume <session-id>` for follow-ups —
+         * unambiguous and replay-safe.
+         *
+         * Scope: still one-shot Q&A. No streaming. Returns assistant's response
+         * text. If we never captured a session_id (init event never fired —
+         * shouldn't happen in healthy claude runs), reject explicitly.
+         */
+        appendMessage(text) {
+            const startedAt = Date.now();
+            return new Promise((resolve, reject) => {
+                if (!claudeSessionId) {
+                    reject(new Error('Cannot reply: original claude session_id was never captured (init event missed)'));
+                    return;
+                }
+                let stdout = '';
+                let stderr = '';
+                const followup = spawn('claude', ['-p', text, '--resume', claudeSessionId, ...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

@@ -538,6 +538,11 @@ export function startMCPServer(options = {}) {
                             startedAt: session.startedAt,
                             status: session.status,
                             agent: session.agent,
+                            // Iter 13 — include canAppendMessage so the freshly-attached
+                            // session card can correctly enable/disable reply input on the
+                            // first render. Without this, ALL just-spawned sessions render
+                            // with reply disabled even when the adapter supports it.
+                            canAppendMessage: session.canAppendMessage === true,
                         }));
                     }
                     catch (e) {
@@ -548,16 +553,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 +599,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 +630,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>
+  <!-- intentionally empty: multi-project sidebar arrives in v0.6.x -->
 </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,11 @@ ${SHARED_STYLES}
     localStorage.setItem('codehere:cwd', cwdInput.value.trim());
   });
 
+  // Iter 13 — sidebar 'add project' button + handler removed (was iter 12 work).
+  // The handler cleared cwd input + scrolled + focused, but the label promised
+  // a new sidebar entry that we do not ship until v0.6.x multi-project work.
+  // Mismatch caused real founder confusion in iter-13 tasting. Removed cleanly.
+
   // 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 +1809,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 +1832,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 +2076,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 +2138,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 +2158,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 +2196,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() {
@@ -2051,7 +2218,7 @@ ${SHARED_STYLES}
       });
       const data = await res.json();
       if (!res.ok) { alert('Failed: ' + (data.error || res.status)); return; }
-      attachSession({ sessionId: data.sessionId, prompt, startedAt: data.startedAt, status: data.status, agent: data.agent || agent || 'conductor' });
+      attachSession({ sessionId: data.sessionId, prompt, startedAt: data.startedAt, status: data.status, agent: data.agent || agent || 'conductor', canAppendMessage: data.canAppendMessage === true });
       promptEl.value = '';
     } catch (e) {
       alert('Network error: ' + (e && e.message ? e.message : e));
@@ -2181,7 +2348,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 +2361,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/infrastructure/storage/project-thread-migration.js

@@ -0,0 +1,232 @@
+/**
+ * Project thread migration — sessions.jsonl → projects/<slug>/thread.jsonl.
+ *
+ * v0.6.0 M1+M7 foundation. The new schema groups sessions by their cwd
+ * (project) so the persistent project thread shape (one continuous chat per
+ * project) has a place to live. The original sessions.jsonl is preserved
+ * for one release as back-compat.
+ *
+ * Built from Spike-1 prototype (agent/spike/v0.6.0-migrate-sessions-to-threads.mjs).
+ * Spike validated lossless + reversible on 612 real sessions in 5ms.
+ *
+ * Production additions over the spike:
+ *   - Atomic per-project writes (.tmp + rename) so partial failures don't
+ *     leave half-written thread.jsonl files
+ *   - Idempotent: skips writing if target thread.jsonl already exists
+ *     (re-run on daemon start is safe)
+ *   - Temp-dir filter: skips /tmp/, /var/folders/, /private/var/folders/ by
+ *     default (configurable) — these are test artifacts, not real projects
+ *   - Abandoned-session marker: sessions with no completed event get
+ *     status='abandoned' instead of silent null
+ *   - Configurable input/output paths so tests can use temp fixtures
+ *
+ * NOT in scope for this module (handled by callers):
+ *   - CLI interface (codehere migrate-threads — TBD subcommand)
+ *   - Auto-run on daemon start
+ *   - Forward-mirroring (writing to thread.jsonl alongside sessions.jsonl
+ *     during normal daemon operation)
+ *
+ * See docs/research/v0.6.0-spike-1-migration.md for the validation history.
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync, readdirSync, renameSync } from 'fs';
+import { join } from 'path';
+import { createHash } from 'crypto';
+/** Path patterns considered ephemeral and skipped from project list. */
+const DEFAULT_TEMP_DIR_PATTERNS = [
+    /^\/tmp\//,
+    /^\/var\/folders\//,
+    /^\/private\/var\/folders\//,
+    /^\/private\/tmp\//,
+];
+/** sha1(cwd)[:12] — stable, short, filesystem-safe. */
+function slugForCwd(cwd, unknownLabel) {
+    if (!cwd)
+        return unknownLabel;
+    return createHash('sha1').update(cwd).digest('hex').slice(0, 12);
+}
+function isTempDir(cwd) {
+    if (!cwd)
+        return false;
+    return DEFAULT_TEMP_DIR_PATTERNS.some((re) => re.test(cwd));
+}
+/** Read JSONL events; tolerate malformed lines (count + skip). */
+function readEvents(path) {
+    if (!existsSync(path))
+        return { events: [], malformed: 0 };
+    const text = readFileSync(path, 'utf-8');
+    const lines = text.split('\n').filter((l) => l.trim());
+    const events = [];
+    let malformed = 0;
+    for (const line of lines) {
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            malformed++;
+        }
+    }
+    return { events, malformed };
+}
+/** Roll up event-log entries into one record per session. */
+function rollupSessions(events) {
+    const byId = new Map();
+    const completedIds = new Set();
+    for (const e of events) {
+        const id = (e.id ?? e.sessionId);
+        if (!id)
+            continue;
+        if (e.t === 'completed' || e.completedAt !== undefined)
+            completedIds.add(id);
+        const existing = byId.get(id) ?? { id, abandoned: true };
+        const existingAny = existing;
+        for (const k of ['agent', 'prompt', 'cwd', 'startedAt', 'status', 'durationMs', 'completedAt', 'steps', 'artifacts']) {
+            if (e[k] !== undefined && existingAny[k] === undefined) {
+                existingAny[k] = e[k];
+            }
+        }
+        byId.set(id, existing);
+    }
+    // Mark abandoned (sessions with no completed event)
+    for (const s of byId.values()) {
+        s.abandoned = !completedIds.has(s.id);
+        if (s.abandoned && !s.status)
+            s.status = 'abandoned';
+    }
+    return [...byId.values()];
+}
+function groupByCwd(sessions, unknownLabel) {
+    const groups = new Map();
+    for (const s of sessions) {
+        const cwd = s.cwd ?? null;
+        const slug = slugForCwd(cwd, unknownLabel);
+        const group = groups.get(slug) ?? { slug, cwd, sessions: [] };
+        group.sessions.push(s);
+        groups.set(slug, group);
+    }
+    return [...groups.values()];
+}
+/** Atomic write: write to .tmp then rename. Caller ensures dir exists. */
+function atomicWriteFile(path, content) {
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
+function buildThreadJsonl(group) {
+    const lines = [];
+    lines.push(JSON.stringify({
+        _meta: 'project',
+        slug: group.slug,
+        cwd: group.cwd,
+        sessionCount: group.sessions.length,
+        migratedFrom: 'sessions.jsonl',
+        migratedAt: Date.now(),
+    }));
+    const sorted = [...group.sessions].sort((a, b) => (a.startedAt ?? 0) - (b.startedAt ?? 0));
+    for (const s of sorted) {
+        lines.push(JSON.stringify({
+            type: 'task',
+            sessionId: s.id,
+            agent: s.agent,
+            prompt: s.prompt,
+            cwd: s.cwd,
+            startedAt: s.startedAt,
+            status: s.status,
+            durationMs: s.durationMs,
+            completedAt: s.completedAt,
+            steps: s.steps,
+            artifacts: s.artifacts,
+        }));
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Run the migration. Idempotent: skips projects whose thread.jsonl already
+ * exists (so daemon-startup auto-runs are safe).
+ */
+export function migrate(options) {
+    const startedAt = Date.now();
+    const skipTempDirs = options.skipTempDirs ?? true;
+    const unknownLabel = options.unknownCwdLabel ?? 'unknown';
+    const { events } = readEvents(options.sourceJsonl);
+    const sessions = rollupSessions(events);
+    const groups = groupByCwd(sessions, unknownLabel);
+    let threadsWritten = 0;
+    let threadsSkippedExisting = 0;
+    let unknownCwdSessions = 0;
+    let abandonedSessions = sessions.filter((s) => s.abandoned).length;
+    let tempDirSessionsSkipped = 0;
+    for (const group of groups) {
+        if (skipTempDirs && isTempDir(group.cwd)) {
+            tempDirSessionsSkipped += group.sessions.length;
+            continue;
+        }
+        if (group.cwd === null)
+            unknownCwdSessions += group.sessions.length;
+        const dir = join(options.targetDir, group.slug);
+        const threadFile = join(dir, 'thread.jsonl');
+        if (existsSync(threadFile)) {
+            threadsSkippedExisting++;
+            continue;
+        }
+        mkdirSync(dir, { recursive: true });
+        atomicWriteFile(threadFile, buildThreadJsonl(group));
+        threadsWritten++;
+    }
+    return {
+        sessionsProcessed: sessions.length,
+        threadsWritten,
+        threadsSkippedExisting,
+        unknownCwdSessions,
+        abandonedSessions,
+        tempDirSessionsSkipped,
+        durationMs: Date.now() - startedAt,
+    };
+}
+/** Dry-run: same as migrate but writes nothing. Returns what WOULD happen. */
+export function dryRun(options) {
+    const startedAt = Date.now();
+    const skipTempDirs = options.skipTempDirs ?? true;
+    const unknownLabel = options.unknownCwdLabel ?? 'unknown';
+    const { events } = readEvents(options.sourceJsonl);
+    const sessions = rollupSessions(events);
+    const groups = groupByCwd(sessions, unknownLabel);
+    let threadsWritten = 0;
+    let threadsSkippedExisting = 0;
+    let unknownCwdSessions = 0;
+    let abandonedSessions = sessions.filter((s) => s.abandoned).length;
+    let tempDirSessionsSkipped = 0;
+    for (const group of groups) {
+        if (skipTempDirs && isTempDir(group.cwd)) {
+            tempDirSessionsSkipped += group.sessions.length;
+            continue;
+        }
+        if (group.cwd === null)
+            unknownCwdSessions += group.sessions.length;
+        const threadFile = join(options.targetDir, group.slug, 'thread.jsonl');
+        if (existsSync(threadFile))
+            threadsSkippedExisting++;
+        else
+            threadsWritten++;
+    }
+    return {
+        sessionsProcessed: sessions.length,
+        threadsWritten,
+        threadsSkippedExisting,
+        unknownCwdSessions,
+        abandonedSessions,
+        tempDirSessionsSkipped,
+        durationMs: Date.now() - startedAt,
+    };
+}
+/**
+ * Rollback: removes the projects directory. Source sessions.jsonl is never
+ * touched. Returns the count of removed project subdirectories.
+ */
+export function rollback(targetDir) {
+    if (!existsSync(targetDir))
+        return { removedDirs: 0 };
+    const subdirs = readdirSync(targetDir);
+    rmSync(targetDir, { recursive: true });
+    return { removedDirs: subdirs.length };
+}
+//# sourceMappingURL=project-thread-migration.js.map

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.4",
   "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",