codehere 0.5.0-alpha.6 → 0.6.0

package/dist/infrastructure/security/permissions-config.js

@@ -0,0 +1,234 @@
+/**
+ * Per-cwd permissions config — P18 slice 1 primitive.
+ *
+ * Reads `.codehere/permissions.yaml` from a project's cwd and lets the
+ * trust-scorer SKIP findings whose matched text fits an allow pattern.
+ *
+ * Use case: codehere blocks `rm -rf node_modules` because the pattern
+ * matches `rm -rf /`. The user knows it's safe in THIS cwd. They run
+ * `codehere permission allow "rm -rf node_modules"` (slice 2 CLI) and
+ * future blocks for that exact pattern in this cwd are skipped.
+ *
+ * Schema (.codehere/permissions.yaml):
+ *
+ *   allow:
+ *     - pattern: "rm -rf node_modules"
+ *       reason: "OK to nuke deps in this repo"
+ *       addedAt: 2026-05-08T20:00:00Z
+ *     - pattern: "ANTHROPIC_API_KEY"
+ *       reason: "Doc explains env vars; not actually leaking"
+ *
+ * Allow patterns are STRINGS not regex — exact substring match against
+ * the audit-finding `matched` field. Keeps the schema simple +
+ * non-technical-user friendly. Regex support is a v0.7 follow-up.
+ *
+ * Per claim_user_persona HIGH: the YAML is human-readable; non-
+ * technical users can edit it directly. Per overconfidence-guard:
+ * we DON'T claim the allow-list is "secure" — it's user CONSENT,
+ * not codehere certification.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+const EMPTY = { allow: [], deny: [] };
+/**
+ * Load .codehere/permissions.yaml from a cwd. Returns empty config if
+ * the file doesn't exist or fails to parse. Defensive: never throws —
+ * caller treats absence as "no overrides", which is the safest default
+ * (the scanner blocks normally).
+ */
+export function loadPermissions(cwd) {
+    if (!cwd || typeof cwd !== 'string')
+        return EMPTY;
+    const file = join(cwd, '.codehere', 'permissions.yaml');
+    if (!existsSync(file))
+        return EMPTY;
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf-8');
+    }
+    catch {
+        return EMPTY;
+    }
+    return parsePermissionsYaml(raw);
+}
+/**
+ * Tiny YAML subset parser — only handles the shape this file uses
+ * (top-level allow/deny lists of {pattern, reason, addedAt} objects).
+ * No external dep; the codehere repo already avoids the `yaml` package
+ * for read paths to keep cold-start fast. Format errors yield empty
+ * config (same posture as missing file).
+ */
+export function parsePermissionsYaml(raw) {
+    const cfg = { allow: [], deny: [] };
+    let bucket = null;
+    let pending = null;
+    for (const line of raw.split('\n')) {
+        const stripped = line.replace(/#.*$/, '').trimEnd();
+        if (!stripped.trim())
+            continue;
+        // Top-level key: "allow:" or "deny:"
+        const top = stripped.match(/^(allow|deny)\s*:\s*$/);
+        if (top) {
+            // Flush any pending entry into the previous bucket
+            if (pending && bucket && pending.pattern)
+                cfg[bucket].push(pending);
+            pending = null;
+            bucket = top[1];
+            continue;
+        }
+        if (!bucket)
+            continue;
+        // List entry start: "  - pattern: ..."
+        const listStart = stripped.match(/^\s*-\s+pattern\s*:\s*(.+)$/);
+        if (listStart) {
+            if (pending && pending.pattern)
+                cfg[bucket].push(pending);
+            pending = { pattern: unquote(listStart[1]) };
+            continue;
+        }
+        // Continuation field on a pending entry
+        const cont = stripped.match(/^\s+(reason|addedAt)\s*:\s*(.+)$/);
+        if (cont && pending) {
+            const key = cont[1];
+            pending[key] = unquote(cont[2]);
+        }
+    }
+    if (pending && bucket && pending.pattern)
+        cfg[bucket].push(pending);
+    return cfg;
+}
+function unquote(s) {
+    const t = s.trim();
+    if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}
+/**
+ * Check whether a finding's matched text is allow-listed in this cwd.
+ * Substring match — exact-text patterns are simpler for non-technical
+ * users than regex. Returns the matching entry (for audit-trail
+ * provenance) or null if no match.
+ */
+export function isAllowed(matchedText, cwd) {
+    const cfg = loadPermissions(cwd);
+    for (const entry of cfg.allow) {
+        if (entry.pattern && matchedText.includes(entry.pattern))
+            return entry;
+    }
+    return null;
+}
+/**
+ * Filter a findings list against the allow-list for a cwd. Returns
+ * the findings that survived (i.e., were NOT allow-listed). Used by
+ * the trust-scorer / pre-prompt-scan to drop findings that the user
+ * has explicitly approved.
+ *
+ * Side-effect-free: the allow-listed findings are dropped from the
+ * caller's perspective. The audit log writer can still record the
+ * full finding list IF the caller wants (then mark which were
+ * allow-listed). This function is the simple "what should we still
+ * block on" filter.
+ */
+export function filterAllowed(findings, cwd) {
+    if (findings.length === 0)
+        return { surviving: [], allowed: [] };
+    const cfg = loadPermissions(cwd);
+    if (cfg.allow.length === 0)
+        return { surviving: findings, allowed: [] };
+    const surviving = [];
+    const allowed = [];
+    for (const f of findings) {
+        const hit = cfg.allow.find((e) => e.pattern && f.matched.includes(e.pattern));
+        if (hit)
+            allowed.push({ finding: f, entry: hit });
+        else
+            surviving.push(f);
+    }
+    return { surviving, allowed };
+}
+// ── Write surface (P18 slice 3) ─────────────────────────────────────────────
+// Shared by the CLI (`codehere permission allow ...`) and the HTTP write
+// endpoint (POST /api/permissions). Single source of truth for the
+// idempotent-add semantics + the YAML serializer.
+import { mkdirSync, writeFileSync } from 'fs';
+/**
+ * Idempotent add — if the pattern already exists in the bucket, returns
+ * status='already_present' with the existing entry. Otherwise appends +
+ * writes the file. Writes via Write tool semantics (overwrites the
+ * whole YAML each time; entries are O(N) so re-serialization is cheap).
+ */
+export function addPermissionEntry(input) {
+    const bucket = input.bucket ?? 'allow';
+    const cfg = loadPermissions(input.cwd);
+    const list = cfg[bucket];
+    const existing = list.find((e) => e.pattern === input.pattern);
+    if (existing) {
+        return {
+            status: 'already_present',
+            bucket,
+            entry: existing,
+            filePath: join(input.cwd, '.codehere', 'permissions.yaml'),
+        };
+    }
+    const entry = {
+        pattern: input.pattern,
+        ...(input.reason ? { reason: input.reason } : {}),
+        addedAt: new Date().toISOString(),
+    };
+    cfg[bucket].push(entry);
+    const filePath = writePermissionsConfig(input.cwd, cfg);
+    return { status: 'added', bucket, entry, filePath };
+}
+/**
+ * Idempotent remove — drops every entry whose pattern matches across
+ * BOTH buckets. Returns count of removed entries.
+ */
+export function removePermissionEntry(cwd, pattern) {
+    const cfg = loadPermissions(cwd);
+    const before = cfg.allow.length + cfg.deny.length;
+    cfg.allow = cfg.allow.filter((e) => e.pattern !== pattern);
+    cfg.deny = cfg.deny.filter((e) => e.pattern !== pattern);
+    const after = cfg.allow.length + cfg.deny.length;
+    const removed = before - after;
+    if (removed > 0)
+        writePermissionsConfig(cwd, cfg);
+    return { removed, filePath: join(cwd, '.codehere', 'permissions.yaml') };
+}
+function writePermissionsConfig(cwd, cfg) {
+    const dir = join(cwd, '.codehere');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const filePath = join(dir, 'permissions.yaml');
+    writeFileSync(filePath, serializePermissionsYaml(cfg), 'utf-8');
+    return filePath;
+}
+export function serializePermissionsYaml(cfg) {
+    const out = [];
+    out.push('# codehere permissions — per-folder allow/deny list');
+    out.push('# See: codehere permission --help');
+    out.push('');
+    for (const bucket of ['allow', 'deny']) {
+        out.push(`${bucket}:`);
+        if (cfg[bucket].length === 0) {
+            out.push('  []');
+        }
+        else {
+            for (const e of cfg[bucket]) {
+                out.push(`  - pattern: ${quoteYaml(e.pattern)}`);
+                if (e.reason)
+                    out.push(`    reason: ${quoteYaml(e.reason)}`);
+                if (e.addedAt)
+                    out.push(`    addedAt: ${quoteYaml(e.addedAt)}`);
+            }
+        }
+        out.push('');
+    }
+    return out.join('\n');
+}
+function quoteYaml(s) {
+    if (s.includes('"') && !s.includes("'"))
+        return `'${s}'`;
+    return `"${s.replace(/"/g, '\\"')}"`;
+}
+//# sourceMappingURL=permissions-config.js.map

package/dist/infrastructure/storage/project-thread-mirror.js

@@ -27,18 +27,13 @@
  * Iter 13 — built after v0.5.0-alpha.4 ship. Previously the only way new
  * sessions reached thread.jsonl was to re-run migration; this closes the gap.
  */
-import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import { existsSync, mkdirSync, appendFileSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { createHash } from 'crypto';
 const PROJECTS_DIR = join(homedir(), '.codehere', 'projects');
 /** Match migration module's defaults. Same regex set kept in sync. */
-const TEMP_DIR_PATTERNS = [
-    /^\/tmp\//,
-    /^\/var\/folders\//,
-    /^\/private\/var\/folders\//,
-    /^\/private\/tmp\//,
-];
+const TEMP_DIR_PATTERNS = [/^\/tmp\//, /^\/var\/folders\//, /^\/private\/var\/folders\//, /^\/private\/tmp\//];
 function isTempDir(cwd) {
     if (!cwd)
         return false;
@@ -84,18 +79,330 @@ function appendThreadEntry(slug, entry) {
         return false;
     }
 }
-/** Append a project-meta update line (used by Title agent to set the title). */
+/** Append a project-meta update line (used by Title agent to set the title).
+ *  Returns true on successful write, false on any fs failure. Title-agent
+ *  callers ignore the return (best-effort); renameProject surfaces it as a
+ *  500 to the HTTP layer so users don't see "renamed" when nothing landed. */
 function appendMetaUpdate(slug, partial) {
     try {
         const dir = ensureProjectDir(slug);
         const file = join(dir, 'thread.jsonl');
         if (!existsSync(file))
-            return; // can't update what doesn't exist
+            return false; // can't update what doesn't exist
         appendFileSync(file, JSON.stringify({ _meta: 'project-update', slug, ...partial, updatedAt: Date.now() }) + '\n', 'utf-8');
+        return true;
     }
     catch {
-        // best-effort
+        return false;
+    }
+}
+/**
+ * Returns true if any prior project-update line for this slug carries
+ * userOverride:true. Used by the async Title agent (and the periodic backfill)
+ * to skip overwriting a title the user has manually set.
+ *
+ * The race this guards: spawn fires Title agent in background → user renames
+ * before LLM returns → Title agent's later write would clobber the manual
+ * rename because the reader takes the latest title. With this check, the
+ * Title agent reads its own outcome moments before writing and bails if the
+ * user got there first. Best-effort; on read failure returns false (Title
+ * agent proceeds) — same posture as every other appendThreadEntry caller.
+ */
+/**
+ * Derive a clean Title-Cased name from a working directory path. Used as the
+ * immediate seed title (so the sidebar never shows blank / placeholder during
+ * the LLM call) and as the permanent fallback when the Title agent returns
+ * null / garbage. Examples:
+ *   /Users/x/code/codehere       → "Codehere"
+ *   /Users/x/work/auth_service   → "Auth Service"
+ *   /Users/x/code/some-cool-thing → "Some Cool Thing"
+ *   /                            → "Project"
+ */
+export function titleFromCwd(cwd) {
+    if (!cwd)
+        return 'Project';
+    const segments = cwd.split('/').filter(Boolean);
+    const last = segments[segments.length - 1];
+    if (!last)
+        return 'Project';
+    // Replace separators with spaces, title-case each word, cap at 6 words
+    const words = last
+        .replace(/[._-]+/g, ' ')
+        .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase split
+        .split(/\s+/)
+        .filter(Boolean)
+        .slice(0, 6)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase());
+    return words.join(' ') || 'Project';
+}
+/**
+ * One-shot backfill for legacy garbage project titles (Bug A4 retroactive).
+ *
+ * The original A4 fix (rejected garbage titles + cwd fallback) only applied
+ * to NEW projects. Existing thread.jsonl files written before the fix can
+ * still carry titles like "Request ID: req_abc123…" or "I cannot generate…"
+ * sitting in the latest project-update record. Those show up in the sidebar
+ * forever until the user manually renames.
+ *
+ * Walks every ~/.codehere/projects/<slug>/thread.jsonl, reads the latest
+ * project-update title, runs the same garbage detection used at write time.
+ * If garbage, appends a new project-update with the cwd-derived fallback
+ * title plus `_backfilled: true` marker so re-runs are no-ops.
+ *
+ * Manual overrides (set via Pattern 10 inline rename) are NEVER touched —
+ * hasManualOverride guards the rewrite.
+ *
+ * Best-effort: any per-project failure logs to stderr (when CODEHERE_DEBUG=1)
+ * and continues. Returns the count of titles rewritten.
+ */
+export async function backfillProjectTitles() {
+    let scanned = 0;
+    let rewritten = 0;
+    if (!existsSync(PROJECTS_DIR))
+        return { scanned, rewritten };
+    // Lazy-load sanitizeTitle to avoid a static import cycle (use-case → infra).
+    const { sanitizeTitle } = await import('../../application/use-cases/generate-thread-title.js');
+    let entries;
+    try {
+        const { readdirSync } = await import('fs');
+        entries = readdirSync(PROJECTS_DIR);
+    }
+    catch {
+        return { scanned, rewritten };
+    }
+    for (const slug of entries) {
+        // Skip non-slug-shaped names + hidden files
+        if (!/^[a-f0-9]{12}$|^unknown$/.test(slug))
+            continue;
+        scanned++;
+        try {
+            const file = join(PROJECTS_DIR, slug, 'thread.jsonl');
+            if (!existsSync(file))
+                continue;
+            if (hasManualOverride(slug))
+                continue; // Never overwrite user renames
+            const content = readFileSync(file, 'utf-8');
+            const lines = content.split('\n').filter((l) => l.trim());
+            // Find the latest project-update + the most recent task cwd (for fallback)
+            let latestTitle = null;
+            let latestCwd = null;
+            let alreadyBackfilled = false;
+            for (const line of lines) {
+                try {
+                    const rec = JSON.parse(line);
+                    if (rec._meta === 'project-update' && typeof rec.title === 'string') {
+                        latestTitle = rec.title;
+                        if (rec._backfilled === true)
+                            alreadyBackfilled = true;
+                        else
+                            alreadyBackfilled = false;
+                    }
+                    if (rec.type === 'task' && typeof rec.cwd === 'string' && rec.cwd) {
+                        latestCwd = rec.cwd;
+                    }
+                }
+                catch {
+                    /* skip malformed line */
+                }
+            }
+            if (alreadyBackfilled)
+                continue; // idempotent — already cleaned
+            if (!latestTitle)
+                continue; // nothing to check
+            // Run the same garbage detection sanitizeTitle uses at write time.
+            // sanitizeTitle returns '' for garbage; non-empty means clean.
+            const cleaned = sanitizeTitle(latestTitle);
+            if (cleaned)
+                continue; // title is fine
+            // Garbage — write a new project-update with cwd-derived fallback.
+            const fallback = titleFromCwd(latestCwd);
+            const ok = appendMetaUpdate(slug, {
+                title: fallback,
+                cwd: latestCwd,
+                _backfilled: true,
+            });
+            if (ok) {
+                rewritten++;
+                if (process.env.CODEHERE_DEBUG === '1') {
+                    console.error(`[backfill] ${slug}: "${latestTitle.slice(0, 40)}" → "${fallback}"`);
+                }
+            }
+        }
+        catch {
+            /* per-project failure → continue */
+        }
+    }
+    return { scanned, rewritten };
+}
+/**
+ * One-shot reconciliation for stale-running tasks (Bug: project-thread.jsonl
+ * entries can stay in `status: 'running'` forever when the daemon dies
+ * mid-task or the subprocess crashes without a clean completion event).
+ *
+ * The visible failure mode (per dogfood screenshots May 6): the threads
+ * view shows RUNNING pills on 3-day-old tasks. With Pattern 8's peach-
+ * accent running pill, the page reads as "codehere doesn't know what
+ * state its own sessions are in" — a credibility bomb.
+ *
+ * Walks every ~/.codehere/projects/<slug>/thread.jsonl, reconstructs each
+ * session's latest task state by sessionId, and for any session whose
+ * latest state is `running` AND startedAt > 60 minutes ago, appends a
+ * synthetic completion record marking it `crashed` with `_reconciled: true`.
+ *
+ * Idempotent — sessions already carrying `_reconciled: true` are skipped.
+ * Preserves history (append-only, never rewrites prior lines).
+ *
+ * Best-effort: per-project failures log to stderr (CODEHERE_DEBUG=1) and
+ * continue. Returns count of sessions reconciled.
+ */
+export async function reconcileStaleProjectTasks(options) {
+    const STALE_AFTER_MS = options?.staleAfterMs ?? 60 * 60 * 1000; // 60 minutes
+    const now = Date.now();
+    let scanned = 0;
+    let reconciled = 0;
+    if (!existsSync(PROJECTS_DIR))
+        return { scanned, reconciled };
+    let entries;
+    try {
+        const { readdirSync } = await import('fs');
+        entries = readdirSync(PROJECTS_DIR);
+    }
+    catch {
+        return { scanned, reconciled };
+    }
+    for (const slug of entries) {
+        if (!/^[a-f0-9]{12}$|^unknown$/.test(slug))
+            continue;
+        scanned++;
+        try {
+            const file = join(PROJECTS_DIR, slug, 'thread.jsonl');
+            if (!existsSync(file))
+                continue;
+            const content = readFileSync(file, 'utf-8');
+            const lines = content.split('\n').filter((l) => l.trim());
+            const bySession = new Map();
+            for (const line of lines) {
+                try {
+                    const rec = JSON.parse(line);
+                    if (rec.type !== 'task' || typeof rec.sessionId !== 'string')
+                        continue;
+                    const cur = bySession.get(rec.sessionId) ?? {
+                        sessionId: rec.sessionId,
+                        status: '',
+                        startedAt: 0,
+                        reconciled: false,
+                    };
+                    if (typeof rec.status === 'string')
+                        cur.status = rec.status;
+                    if (typeof rec.startedAt === 'number' && rec.startedAt > 0)
+                        cur.startedAt = rec.startedAt;
+                    if (rec._reconciled === true)
+                        cur.reconciled = true;
+                    bySession.set(rec.sessionId, cur);
+                }
+                catch {
+                    /* skip malformed line */
+                }
+            }
+            // Find stale-running candidates and append synthetic completions.
+            for (const state of bySession.values()) {
+                if (state.status !== 'running')
+                    continue;
+                if (state.reconciled)
+                    continue; // already cleaned
+                if (state.startedAt <= 0)
+                    continue; // safety: no time data
+                if (now - state.startedAt < STALE_AFTER_MS)
+                    continue;
+                // appendThreadEntry returns `seeded` (first-write flag), not a
+                // success signal. For an already-seeded file, the return is always
+                // false on both success and failure. Best-effort approach: count
+                // optimistically — write failures are rare and bounded by the
+                // function's own try/catch.
+                appendThreadEntry(slug, {
+                    type: 'task',
+                    sessionId: state.sessionId,
+                    status: 'crashed',
+                    completedAt: now,
+                    durationMs: now - state.startedAt,
+                    _reconciled: true,
+                });
+                reconciled++;
+                if (process.env.CODEHERE_DEBUG === '1') {
+                    const ageMin = Math.round((now - state.startedAt) / 60000);
+                    console.error(`[reconcile] ${slug}/${state.sessionId.slice(0, 8)} stale running for ${ageMin}m → crashed`);
+                }
+            }
+        }
+        catch {
+            /* per-project failure → continue */
+        }
+    }
+    return { scanned, reconciled };
+}
+export function hasManualOverride(slug) {
+    try {
+        const file = join(PROJECTS_DIR, slug, 'thread.jsonl');
+        if (!existsSync(file))
+            return false;
+        const content = readFileSync(file, 'utf-8');
+        for (const line of content.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                const rec = JSON.parse(t);
+                if (rec._meta === 'project-update' && rec.userOverride === true)
+                    return true;
+            }
+            catch {
+                // skip malformed line
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * v0.6.x — user-initiated rename. The Title agent generates a title from the
+ * first prompt, but project intent drifts (e.g. /agent dir gets titled "Scan
+ * Auth File" forever even after 100+ unrelated tasks). This gives the user a
+ * mechanism to override that title without re-firing the LLM-based agent.
+ *
+ * Returns { ok: false, error } on validation/fs failure so the HTTP layer can
+ * surface a meaningful 4xx instead of a silent best-effort write. Note: this
+ * is the only project-update path that returns errors — Title agent
+ * appendMetaUpdate is silent because LLM hiccups are normal.
+ */
+export function renameProject(slug, newTitle) {
+    // Validate slug shape — guards against path traversal in case the caller
+    // doesn't sanitize the URL parameter (HTTP layer validates this too, defense in depth).
+    if (!/^([a-f0-9]{12}|unknown)$/.test(slug)) {
+        return { ok: false, error: 'Invalid project slug' };
+    }
+    // Validate title — strip whitespace, enforce length and single-line.
+    const trimmed = newTitle.trim();
+    if (!trimmed)
+        return { ok: false, error: 'Title cannot be empty' };
+    if (trimmed.length > 100)
+        return { ok: false, error: 'Title too long (max 100 chars)' };
+    if (/[\n\r]/.test(trimmed))
+        return { ok: false, error: 'Title cannot contain newlines' };
+    // Verify project exists — appendMetaUpdate is silent on missing files but
+    // we want a clean 404 path for the HTTP caller.
+    const file = join(PROJECTS_DIR, slug, 'thread.jsonl');
+    if (!existsSync(file))
+        return { ok: false, error: 'Project not found' };
+    // userOverride:true tells the async Title agent + periodic backfill to skip
+    // writing for this slug — see hasManualOverride() above. Without this flag,
+    // a slow LLM call from spawn-time can land AFTER the user's rename and
+    // clobber it (the reader takes the latest project-update title).
+    if (!appendMetaUpdate(slug, { title: trimmed, userOverride: true })) {
+        return { ok: false, error: 'Write failed' };
     }
+    return { ok: true };
 }
 /**
  * Mirror a spawn event to the project thread. Skips temp-dir cwds (matches
@@ -120,21 +427,36 @@ export function mirrorSpawnedToThread(rec) {
         startedAt: rec.startedAt,
         status: 'running',
     });
-    if (seeded && process.env.CODEHERE_DISABLE_TITLE_AGENT !== '1') {
-        // Fire Title agent in background; do not block the spawn path. Lazy-import
-        // to avoid loading the LLM module on every spawn when not needed.
-        void (async () => {
-            try {
-                const { generateThreadTitle } = await import('../../application/use-cases/generate-thread-title.js');
-                const title = await generateThreadTitle(rec.prompt, rec.cwd);
-                if (title) {
-                    appendMetaUpdate(slug, { title, cwd: rec.cwd });
+    if (seeded) {
+        // Seed an immediate cwd-derived title so the sidebar never shows a blank
+        // / placeholder while the LLM call is in flight (or if it fails entirely).
+        // The Title agent can later overwrite this with a richer prompt-derived
+        // title; user manual rename always wins over both.
+        if (!hasManualOverride(slug)) {
+            const fallback = titleFromCwd(rec.cwd);
+            appendMetaUpdate(slug, { title: fallback, cwd: rec.cwd });
+        }
+        if (process.env.CODEHERE_DISABLE_TITLE_AGENT !== '1') {
+            // Fire Title agent in background; do not block the spawn path. Lazy-import
+            // to avoid loading the LLM module on every spawn when not needed.
+            void (async () => {
+                try {
+                    const { generateThreadTitle } = await import('../../application/use-cases/generate-thread-title.js');
+                    const title = await generateThreadTitle(rec.prompt, rec.cwd);
+                    // Last-moment manual-override check: between spawn and now (LLM call
+                    // can take seconds), user may have already renamed. Don't clobber.
+                    // Also: if Title agent returned null (garbage rejected, provider
+                    // unreachable, refusal), keep the cwd-derived fallback already seeded
+                    // above — never write `(untitled)` or empty.
+                    if (title && !hasManualOverride(slug)) {
+                        appendMetaUpdate(slug, { title, cwd: rec.cwd });
+                    }
                 }
-            }
-            catch {
-                // best-effort
-            }
-        })();
+                catch {
+                    // best-effort — cwd fallback already seeded
+                }
+            })();
+        }
     }
 }
 /**
@@ -156,21 +478,31 @@ export function mirrorCompletedToThread(rec) {
         artifacts: rec.artifacts,
     });
 }
-/**
- * v0.6.x — mirror a successful appendMessage() reply to the project thread.
- *
- * Pre-fix: only initial spawn + completion wrote to thread.jsonl. Reply turns
- * (the `/api/task/:id/message` endpoint, the dashboard reply box, and the new
- * /threads reply bar) updated only the in-memory session. Result: /threads
- * showed the original spawn but every follow-up turn was invisible. Founder
- * flagged it 2026-05-03 as a v0.6.x cleanup item.
- *
- * Schema choice: write a single complete `{type: 'task', sessionId: <new>,
- * parentSessionId: <orig>, ...}` entry rather than splitting spawn+complete.
- * appendMessage is synchronous-from-caller's-POV (no streaming), so the whole
- * turn is known when this fires. The reader's sessionId merge logic surfaces
- * each reply as its own chronological row on /threads.
- */
+/** Label map for raw error codes → user-facing text. */
+const FAILOVER_LABELS = {
+    rate_limit: 'hit a rate limit',
+    quota_exceeded: 'exhausted its quota',
+    credit_low: 'ran low on credits',
+    error: 'encountered an error',
+};
+export function mirrorFailoverToThread(rec) {
+    if (isTempDir(rec.cwd))
+        return;
+    const slug = slugForCwd(rec.cwd);
+    const reasonLabel = FAILOVER_LABELS[rec.reason] ?? 'became unavailable';
+    const fromLabel = rec.fromAgent;
+    const toLabel = rec.toAgent;
+    appendThreadEntry(slug, {
+        type: 'task',
+        sessionId: rec.sessionId,
+        agent: 'system',
+        prompt: `↻ Switched from ${fromLabel} to ${toLabel} (${reasonLabel})`,
+        status: 'completed',
+        startedAt: Date.now(),
+        completedAt: Date.now(),
+        durationMs: 0,
+    });
+}
 export function mirrorReplyToThread(rec) {
     if (isTempDir(rec.cwd))
         return;