@phren/cli 0.0.1

package/mcp/dist/cli-hooks-session.js

@@ -0,0 +1,1402 @@
+import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, EXEC_TIMEOUT_MS, getPhrenPath, getProjectDirs, findProjectNameCaseInsensitive, homePath, updateRuntimeHealth, withFileLock, getWorkflowPolicy, appendReviewQueue, recordFeedback, getQualityMultiplier, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, getProactivityLevelForTask, getProactivityLevelForFindings, hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel, FINDING_SENSITIVITY_CONFIG, isFeatureEnabled, errorMessage, bootstrapPhrenDotEnv, finalizeTaskSession, appendFindingJournal, runDoctor, resolveRuntimeProfile, } from "./cli-hooks-context.js";
+import { sessionMetricsFile, qualityMarkers, } from "./shared.js";
+import { autoMergeConflicts, mergeTask, mergeFindings, } from "./shared-content.js";
+import { runGit } from "./utils.js";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { execFileSync, spawn } from "child_process";
+import { fileURLToPath } from "url";
+import { isTaskFileName, TASKS_FILENAME } from "./data-tasks.js";
+import { buildIndex, queryRows, } from "./shared-index.js";
+import { filterTaskByPriority } from "./shared-retrieval.js";
+function getRuntimeProfile() {
+    return resolveRuntimeProfile(getPhrenPath());
+}
+export { buildHookContext, checkHookGuard, handleGuardSkip } from "./cli-hooks-context.js";
+/** Read JSON from stdin if it's not a TTY. Returns null if stdin is a TTY or parsing fails. */
+function readStdinJson() {
+    if (process.stdin.isTTY)
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(0, "utf-8"));
+    }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] readStdinJson: ${errorMessage(err)}\n`);
+        return null;
+    }
+}
+/** Validate that a transcript path points to a safe, expected location.
+ * Uses realpathSync to dereference symlinks, preventing traversal attacks
+ * where a symlink inside a safe dir points outside it.
+ */
+function isSafeTranscriptPath(p) {
+    // Resolve symlinks so a link like ~/.claude/evil -> /etc/passwd is caught
+    let normalized;
+    try {
+        normalized = fs.realpathSync.native(p);
+    }
+    catch {
+        // If the file doesn't exist yet, fall back to lexical resolution
+        try {
+            normalized = fs.realpathSync.native(path.dirname(p));
+            normalized = path.join(normalized, path.basename(p));
+        }
+        catch {
+            normalized = path.resolve(p);
+        }
+    }
+    const safePrefixes = [
+        path.resolve(os.tmpdir()),
+        path.resolve(homePath(".claude")),
+        path.resolve(homePath(".config", "claude")),
+    ];
+    return safePrefixes.some(prefix => normalized.startsWith(prefix + path.sep) || normalized === prefix);
+}
+export function getUntrackedProjectNotice(phrenPath, cwd) {
+    const profile = resolveRuntimeProfile(phrenPath);
+    const projectDir = detectProjectDir(cwd, phrenPath);
+    if (!projectDir)
+        return null;
+    const activeProfile = profile || undefined;
+    // Check the exact current working directory against projects in the active profile.
+    // This avoids prompting when cwd is already inside a tracked sourcePath.
+    if (detectProject(phrenPath, cwd, activeProfile))
+        return null;
+    if (detectProject(phrenPath, projectDir, activeProfile))
+        return null;
+    const projectName = path.basename(projectDir).toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+    if (isProjectTracked(phrenPath, projectName, activeProfile)) {
+        const trackedName = getProjectDirs(phrenPath, activeProfile)
+            .map((dir) => path.basename(dir))
+            .find((name) => name.toLowerCase() === projectName)
+            || findProjectNameCaseInsensitive(phrenPath, projectName)
+            || projectName;
+        const config = readProjectConfig(phrenPath, trackedName);
+        const sourcePath = getProjectSourcePath(phrenPath, trackedName, config);
+        if (!sourcePath)
+            return null;
+        const resolvedProjectDir = path.resolve(projectDir);
+        const sameSource = resolvedProjectDir === sourcePath || resolvedProjectDir.startsWith(sourcePath + path.sep);
+        if (sameSource)
+            return null;
+    }
+    return [
+        "<phren-notice>",
+        "This project directory is not tracked by phren yet.",
+        "Run `npx phren add` to track it now.",
+        `Suggested command: \`npx phren add \"${projectDir}\"\``,
+        "Ask the user whether they want to add it to phren now.",
+        "If they say no, tell them they can always run `npx phren add` later.",
+        "If they say yes, also ask whether phren should manage repo instruction files or leave their existing repo-owned CLAUDE/AGENTS files alone.",
+        `Then use the \`add_project\` MCP tool with path="${projectDir}" and ownership="phren-managed"|"detached"|"repo-managed", or run \`npx phren add\` from that directory.`,
+        "After onboarding, run `npx phren doctor` if hooks or MCP tools are not responding.",
+        "<phren-notice>",
+        "",
+    ].join("\n");
+}
+const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
+function projectHasBootstrapSignals(phrenPath, project) {
+    const projectDir = path.join(phrenPath, project);
+    const findingsPath = path.join(projectDir, "FINDINGS.md");
+    if (fs.existsSync(findingsPath)) {
+        const findings = fs.readFileSync(findingsPath, "utf8");
+        if (/^-\s+/m.test(findings))
+            return true;
+    }
+    const tasksPath = path.join(projectDir, TASKS_FILENAME);
+    if (fs.existsSync(tasksPath)) {
+        const tasks = fs.readFileSync(tasksPath, "utf8");
+        if (/^-\s+\[(?: |x|X)\]/m.test(tasks))
+            return true;
+    }
+    return false;
+}
+export function getSessionStartOnboardingNotice(phrenPath, cwd, activeProject) {
+    const markerPath = sessionMarker(phrenPath, SESSION_START_ONBOARDING_MARKER);
+    if (fs.existsSync(markerPath))
+        return null;
+    if (getUntrackedProjectNotice(phrenPath, cwd))
+        return null;
+    const profile = resolveRuntimeProfile(phrenPath);
+    const trackedProjects = getProjectDirs(phrenPath, profile).filter((dir) => path.basename(dir) !== "global");
+    if (trackedProjects.length === 0) {
+        return [
+            "<phren-notice>",
+            "Phren onboarding: no tracked projects are active for this workspace yet.",
+            "Start in a project repo and run `npx phren add` so SessionStart can inject project context.",
+            "Run `npx phren doctor` to verify hooks and MCP wiring after setup.",
+            "<phren-notice>",
+            "",
+        ].join("\n");
+    }
+    if (!activeProject)
+        return null;
+    if (projectHasBootstrapSignals(phrenPath, activeProject))
+        return null;
+    return [
+        "<phren-notice>",
+        `Phren onboarding: project "${activeProject}" is tracked but memory is still empty.`,
+        "Capture one finding with `add_finding` and one task with `add_task` to seed future SessionStart context.",
+        "Run `npx phren doctor` if setup seems incomplete.",
+        "<phren-notice>",
+        "",
+    ].join("\n");
+}
+export function getGitContext(cwd) {
+    if (!cwd)
+        return null;
+    const git = (args) => runGit(cwd, args, EXEC_TIMEOUT_MS, debugLog);
+    const branch = git(["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (!branch)
+        return null;
+    const changedFiles = new Set();
+    for (const changed of [
+        git(["diff", "--name-only"]),
+        git(["diff", "--name-only", "--cached"]),
+    ]) {
+        if (!changed)
+            continue;
+        for (const line of changed.split("\n").map((s) => s.trim()).filter(Boolean)) {
+            changedFiles.add(line);
+            const basename = path.basename(line);
+            if (basename)
+                changedFiles.add(basename);
+        }
+    }
+    return { branch, changedFiles };
+}
+function parseSessionMetrics(phrenPathLocal) {
+    const file = sessionMetricsFile(phrenPathLocal);
+    if (!fs.existsSync(file))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (err) {
+        debugLog(`parseSessionMetrics: failed to read ${file}: ${errorMessage(err)}`);
+        return {};
+    }
+}
+function writeSessionMetrics(phrenPathLocal, data) {
+    const file = sessionMetricsFile(phrenPathLocal);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
+}
+function updateSessionMetrics(phrenPathLocal, updater) {
+    const file = sessionMetricsFile(phrenPathLocal);
+    withFileLock(file, () => {
+        const metrics = parseSessionMetrics(phrenPathLocal);
+        updater(metrics);
+        writeSessionMetrics(phrenPathLocal, metrics);
+    });
+}
+export function trackSessionMetrics(phrenPathLocal, sessionId, selected) {
+    updateSessionMetrics(phrenPathLocal, (metrics) => {
+        if (!metrics[sessionId])
+            metrics[sessionId] = { prompts: 0, keys: {}, lastChangedCount: 0, lastKeys: [] };
+        metrics[sessionId].prompts += 1;
+        const injectedKeys = [];
+        for (const injected of selected) {
+            injectedKeys.push(injected.key);
+            const key = injected.key;
+            const seen = metrics[sessionId].keys[key] || 0;
+            metrics[sessionId].keys[key] = seen + 1;
+            if (seen >= 1)
+                recordFeedback(phrenPathLocal, key, "reprompt");
+        }
+        const relevantCount = selected.filter((s) => getQualityMultiplier(phrenPathLocal, s.key) > 0.5).length;
+        const prevRelevant = metrics[sessionId].lastChangedCount || 0;
+        const prevKeys = metrics[sessionId].lastKeys || [];
+        if (relevantCount > prevRelevant) {
+            for (const prevKey of prevKeys) {
+                recordFeedback(phrenPathLocal, prevKey, "helpful");
+            }
+        }
+        metrics[sessionId].lastChangedCount = relevantCount;
+        metrics[sessionId].lastKeys = injectedKeys;
+        metrics[sessionId].lastSeen = new Date().toISOString();
+        const thirtyDaysAgo = Date.now() - 30 * 86400000;
+        for (const sid of Object.keys(metrics)) {
+            const seen = metrics[sid].lastSeen;
+            if (seen && new Date(seen).getTime() < thirtyDaysAgo) {
+                delete metrics[sid];
+            }
+        }
+    });
+}
+// ── Background maintenance ───────────────────────────────────────────────────
+export function resolveSubprocessArgs(command) {
+    const distEntry = path.join(path.dirname(fileURLToPath(import.meta.url)), "index.js");
+    if (fs.existsSync(distEntry))
+        return [distEntry, command];
+    const sourceEntry = process.argv.find((a) => /[\\/]index\.(ts|js)$/.test(a) && fs.existsSync(a));
+    const runner = process.argv[1];
+    if (sourceEntry && runner)
+        return [runner, sourceEntry, command];
+    return null;
+}
+function scheduleBackgroundSync(phrenPathLocal) {
+    const lockPath = runtimeFile(phrenPathLocal, "background-sync.lock");
+    const logPath = runtimeFile(phrenPathLocal, "background-sync.log");
+    const spawnArgs = resolveSubprocessArgs("background-sync");
+    if (!spawnArgs)
+        return false;
+    try {
+        if (fs.existsSync(lockPath)) {
+            const ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
+            if (ageMs <= 10 * 60 * 1000)
+                return false;
+            fs.unlinkSync(lockPath);
+        }
+    }
+    catch (err) {
+        debugLog(`scheduleBackgroundSync: lock check failed: ${errorMessage(err)}`);
+        return false;
+    }
+    try {
+        fs.writeFileSync(lockPath, JSON.stringify({ startedAt: new Date().toISOString(), pid: process.pid }) + "\n", { flag: "wx" });
+        const logFd = fs.openSync(logPath, "a");
+        fs.writeSync(logFd, `[${new Date().toISOString()}] spawn ${process.execPath} ${spawnArgs.join(" ")}\n`);
+        const child = spawn(process.execPath, spawnArgs, {
+            cwd: process.cwd(),
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+            env: {
+                ...process.env,
+                PHREN_PATH: phrenPathLocal,
+                PHREN_PROFILE: getRuntimeProfile(),
+            },
+        });
+        child.unref();
+        fs.closeSync(logFd);
+        return true;
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch { }
+        debugLog(`scheduleBackgroundSync: spawn failed: ${errorMessage(err)}`);
+        return false;
+    }
+}
+function scheduleBackgroundMaintenance(phrenPathLocal, project) {
+    if (!isFeatureEnabled("PHREN_FEATURE_DAILY_MAINTENANCE", true))
+        return false;
+    const markers = qualityMarkers(phrenPathLocal);
+    if (fs.existsSync(markers.done))
+        return false;
+    if (fs.existsSync(markers.lock)) {
+        try {
+            const ageMs = Date.now() - fs.statSync(markers.lock).mtimeMs;
+            if (ageMs <= 2 * 60 * 60 * 1000)
+                return false;
+            fs.unlinkSync(markers.lock);
+        }
+        catch (err) {
+            debugLog(`maybeRunBackgroundMaintenance: lock check failed: ${errorMessage(err)}`);
+            return false;
+        }
+    }
+    const spawnArgs = resolveSubprocessArgs("background-maintenance");
+    if (!spawnArgs)
+        return false;
+    try {
+        // Use exclusive open (O_EXCL) to atomically claim the lock; if another process
+        // already holds it this throws and we return false without spawning a duplicate.
+        const lockContent = JSON.stringify({
+            startedAt: new Date().toISOString(),
+            project: project || "all",
+            pid: process.pid,
+        }) + "\n";
+        let fd;
+        try {
+            fd = fs.openSync(markers.lock, "wx");
+        }
+        catch (err) {
+            // Another process already claimed the lock
+            if (process.env.PHREN_DEBUG)
+                process.stderr.write(`[phren] backgroundMaintenance lockClaim: ${errorMessage(err)}\n`);
+            return false;
+        }
+        try {
+            fs.writeSync(fd, lockContent);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        if (project)
+            spawnArgs.push(project);
+        const logDir = path.join(phrenPathLocal, ".governance");
+        fs.mkdirSync(logDir, { recursive: true });
+        const logPath = path.join(logDir, "background-maintenance.log");
+        const logFd = fs.openSync(logPath, "a");
+        fs.writeSync(logFd, `[${new Date().toISOString()}] spawn ${process.execPath} ${spawnArgs.join(" ")}\n`);
+        const child = spawn(process.execPath, spawnArgs, {
+            cwd: process.cwd(),
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+            env: {
+                ...process.env,
+                PHREN_PATH: phrenPathLocal,
+                PHREN_PROFILE: getRuntimeProfile(),
+            },
+        });
+        child.on("exit", (code, signal) => {
+            const msg = `[${new Date().toISOString()}] exit code=${code ?? "null"} signal=${signal ?? "none"}\n`;
+            try {
+                fs.appendFileSync(logPath, msg);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] backgroundMaintenance exitLog: ${errorMessage(err)}\n`);
+            }
+            if (code === 0) {
+                try {
+                    fs.writeFileSync(markers.done, new Date().toISOString() + "\n");
+                }
+                catch (err) {
+                    if (process.env.PHREN_DEBUG)
+                        process.stderr.write(`[phren] backgroundMaintenance doneMarker: ${errorMessage(err)}\n`);
+                }
+            }
+            try {
+                fs.unlinkSync(markers.lock);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] backgroundMaintenance unlockOnExit: ${errorMessage(err)}\n`);
+            }
+        });
+        child.on("error", (spawnErr) => {
+            const msg = `[${new Date().toISOString()}] spawn error: ${spawnErr.message}\n`;
+            try {
+                fs.appendFileSync(logPath, msg);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] backgroundMaintenance errorLog: ${errorMessage(err)}\n`);
+            }
+            try {
+                fs.unlinkSync(markers.lock);
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] backgroundMaintenance unlockOnError: ${errorMessage(err)}\n`);
+            }
+        });
+        fs.closeSync(logFd);
+        child.unref();
+        return true;
+    }
+    catch (err) {
+        const errMsg = errorMessage(err);
+        try {
+            const logDir = path.join(phrenPathLocal, ".governance");
+            fs.mkdirSync(logDir, { recursive: true });
+            fs.appendFileSync(path.join(logDir, "background-maintenance.log"), `[${new Date().toISOString()}] spawn failed: ${errMsg}\n`);
+        }
+        catch (err) {
+            if (process.env.PHREN_DEBUG)
+                process.stderr.write(`[phren] backgroundMaintenance logSpawnFailure: ${errorMessage(err)}\n`);
+        }
+        try {
+            fs.unlinkSync(markers.lock);
+        }
+        catch (err) {
+            if (process.env.PHREN_DEBUG)
+                process.stderr.write(`[phren] backgroundMaintenance unlockOnFailure: ${errorMessage(err)}\n`);
+        }
+        return false;
+    }
+}
+// ── Git command helpers for hooks ────────────────────────────────────────────
+function isTransientGitError(message) {
+    return /(timed out|connection|network|could not resolve host|rpc failed|429|502|503|504|service unavailable)/i.test(message);
+}
+function shouldRetryGitCommand(args) {
+    const cmd = args[0] || "";
+    return cmd === "push" || cmd === "pull" || cmd === "fetch";
+}
+async function runBestEffortGit(args, cwd) {
+    const retries = shouldRetryGitCommand(args) ? 2 : 0;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            const output = execFileSync("git", args, {
+                cwd,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+                timeout: EXEC_TIMEOUT_MS,
+            }).trim();
+            return { ok: true, output };
+        }
+        catch (err) {
+            const message = errorMessage(err);
+            if (attempt < retries && isTransientGitError(message)) {
+                const delayMs = 500 * (attempt + 1);
+                await new Promise((resolve) => setTimeout(resolve, delayMs));
+                continue;
+            }
+            return { ok: false, error: message };
+        }
+    }
+    return { ok: false, error: "git command failed" };
+}
+async function countUnsyncedCommits(cwd) {
+    const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
+    if (!upstream.ok || !upstream.output)
+        return 0;
+    const ahead = await runBestEffortGit(["rev-list", "--count", `${upstream.output.trim()}..HEAD`], cwd);
+    if (!ahead.ok || !ahead.output)
+        return 0;
+    const parsed = Number.parseInt(ahead.output.trim(), 10);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function isMergeableMarkdown(relPath) {
+    const filename = path.basename(relPath).toLowerCase();
+    return filename === "findings.md" || isTaskFileName(filename);
+}
+async function snapshotLocalMergeableFiles(cwd) {
+    const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
+    if (!upstream.ok || !upstream.output)
+        return new Map();
+    const changed = await runBestEffortGit(["diff", "--name-only", `${upstream.output.trim()}..HEAD`], cwd);
+    if (!changed.ok || !changed.output)
+        return new Map();
+    const snapshots = new Map();
+    for (const relPath of changed.output.split("\n").map((line) => line.trim()).filter(Boolean)) {
+        if (!isMergeableMarkdown(relPath))
+            continue;
+        const fullPath = path.join(cwd, relPath);
+        if (!fs.existsSync(fullPath))
+            continue;
+        snapshots.set(relPath, fs.readFileSync(fullPath, "utf8"));
+    }
+    return snapshots;
+}
+async function reconcileMergeableFiles(cwd, snapshots) {
+    let changedAny = false;
+    for (const [relPath, localBeforePull] of snapshots.entries()) {
+        const fullPath = path.join(cwd, relPath);
+        if (!fs.existsSync(fullPath))
+            continue;
+        const current = fs.readFileSync(fullPath, "utf8");
+        const filename = path.basename(relPath).toLowerCase();
+        const merged = filename === "findings.md"
+            ? mergeFindings(current, localBeforePull)
+            : mergeTask(current, localBeforePull);
+        if (merged === current)
+            continue;
+        fs.writeFileSync(fullPath, merged);
+        changedAny = true;
+    }
+    if (!changedAny)
+        return false;
+    const add = await runBestEffortGit(["add", "--", ...snapshots.keys()], cwd);
+    if (!add.ok)
+        return false;
+    const commit = await runBestEffortGit(["commit", "-m", "auto-merge markdown recovery"], cwd);
+    return commit.ok;
+}
+async function recoverPushConflict(cwd) {
+    const localSnapshots = await snapshotLocalMergeableFiles(cwd);
+    const pull = await runBestEffortGit(["pull", "--rebase", "--quiet"], cwd);
+    if (pull.ok) {
+        const reconciled = await reconcileMergeableFiles(cwd, localSnapshots);
+        const retryPush = await runBestEffortGit(["push"], cwd);
+        return {
+            ok: retryPush.ok,
+            detail: retryPush.ok
+                ? (reconciled ? "commit pushed after pull --rebase and markdown reconciliation" : "commit pushed after pull --rebase")
+                : (retryPush.error || "push failed after pull --rebase"),
+            pullStatus: "ok",
+            pullDetail: pull.output || "pull --rebase ok",
+        };
+    }
+    const conflicted = await runBestEffortGit(["diff", "--name-only", "--diff-filter=U"], cwd);
+    const conflictedOutput = conflicted.output?.trim() || "";
+    if (!conflicted.ok || !conflictedOutput) {
+        await runBestEffortGit(["rebase", "--abort"], cwd);
+        return {
+            ok: false,
+            detail: pull.error || "pull --rebase failed",
+            pullStatus: "error",
+            pullDetail: pull.error || "pull --rebase failed",
+        };
+    }
+    if (!autoMergeConflicts(cwd)) {
+        await runBestEffortGit(["rebase", "--abort"], cwd);
+        return {
+            ok: false,
+            detail: `rebase conflicts require manual resolution: ${conflictedOutput}`,
+            pullStatus: "error",
+            pullDetail: `rebase conflicts require manual resolution: ${conflictedOutput}`,
+        };
+    }
+    const continued = await runBestEffortGit(["-c", "core.editor=true", "rebase", "--continue"], cwd);
+    if (!continued.ok) {
+        await runBestEffortGit(["rebase", "--abort"], cwd);
+        return {
+            ok: false,
+            detail: continued.error || "rebase --continue failed",
+            pullStatus: "error",
+            pullDetail: continued.error || "rebase --continue failed",
+        };
+    }
+    const retryPush = await runBestEffortGit(["push"], cwd);
+    return {
+        ok: retryPush.ok,
+        detail: retryPush.ok ? "commit pushed after auto-merge recovery" : (retryPush.error || "push failed after auto-merge recovery"),
+        pullStatus: "ok",
+        pullDetail: "pull --rebase recovered via auto-merge",
+    };
+}
+// ── Hook handlers ────────────────────────────────────────────────────────────
+export async function handleHookSessionStart() {
+    const startedAt = new Date().toISOString();
+    const ctx = buildHookContext();
+    const { phrenPath, cwd, activeProject, manifest } = ctx;
+    // Check common guards (hooks enabled, tool enabled)
+    if (!ctx.hooksEnabled) {
+        handleGuardSkip(ctx, "hook_session_start", "disabled", { lastSessionStartAt: startedAt });
+        return;
+    }
+    if (!ctx.toolHookEnabled) {
+        handleGuardSkip(ctx, "hook_session_start", `tool_disabled tool=${ctx.hookTool}`);
+        return;
+    }
+    try {
+        repairPreexistingInstall(phrenPath);
+    }
+    catch (err) {
+        debugLog(`hook-session-start repair failed: ${errorMessage(err)}`);
+    }
+    if (!isProjectHookEnabled(phrenPath, activeProject, "SessionStart")) {
+        handleGuardSkip(ctx, "hook_session_start", `project_disabled project=${activeProject}`, { lastSessionStartAt: startedAt });
+        return;
+    }
+    if (manifest?.installMode === "project-local") {
+        updateRuntimeHealth(phrenPath, {
+            lastSessionStartAt: startedAt,
+            lastSync: {
+                lastPullAt: startedAt,
+                lastPullStatus: "ok",
+                lastPullDetail: "project-local mode does not manage git sync",
+            },
+        });
+        appendAuditLog(phrenPath, "hook_session_start", "status=skipped-local");
+        return;
+    }
+    const gitRepo = ensureLocalGitRepo(phrenPath);
+    const remotes = gitRepo.ok ? await runBestEffortGit(["remote"], phrenPath) : { ok: false, error: gitRepo.detail };
+    const hasRemote = Boolean(remotes.ok && remotes.output && remotes.output.trim());
+    const pull = !gitRepo.ok
+        ? { ok: false, error: gitRepo.detail }
+        : hasRemote
+            ? await runBestEffortGit(["pull", "--rebase", "--quiet"], phrenPath)
+            : {
+                ok: true,
+                output: gitRepo.initialized
+                    ? "initialized local git repo; no remote configured"
+                    : "local-only repo; no remote configured",
+            };
+    const doctor = await runDoctor(phrenPath, false);
+    const maintenanceScheduled = scheduleBackgroundMaintenance(phrenPath);
+    const unsyncedCommits = hasRemote ? await countUnsyncedCommits(phrenPath) : 0;
+    try {
+        const { trackSession } = await import("./telemetry.js");
+        trackSession(phrenPath);
+    }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] hookSessionStart trackSession: ${errorMessage(err)}\n`);
+    }
+    updateRuntimeHealth(phrenPath, {
+        lastSessionStartAt: startedAt,
+        lastSync: {
+            lastPullAt: startedAt,
+            lastPullStatus: pull.ok ? "ok" : "error",
+            lastPullDetail: pull.ok ? (pull.output || "pull ok") : (pull.error || "pull failed"),
+            lastSuccessfulPullAt: pull.ok && hasRemote ? startedAt : undefined,
+            unsyncedCommits,
+        },
+    });
+    appendAuditLog(phrenPath, "hook_session_start", `pull=${hasRemote ? (pull.ok ? "ok" : "fail") : "skipped-local"} doctor=${doctor.ok ? "ok" : "issues"} maintenance=${maintenanceScheduled ? "scheduled" : "skipped"}`);
+    // Untracked project detection: suggest `phren add` if CWD looks like a project but isn't tracked
+    try {
+        const notice = getUntrackedProjectNotice(phrenPath, cwd);
+        if (notice) {
+            process.stdout.write(notice);
+            debugLog(`untracked project detected at ${cwd}`);
+        }
+        const onboarding = getSessionStartOnboardingNotice(phrenPath, cwd, activeProject);
+        if (onboarding) {
+            process.stdout.write(onboarding);
+            try {
+                fs.writeFileSync(sessionMarker(phrenPath, SESSION_START_ONBOARDING_MARKER), `${startedAt}\n`);
+            }
+            catch (err) {
+                debugLog(`session-start onboarding marker write failed: ${errorMessage(err)}`);
+            }
+        }
+    }
+    catch (err) {
+        debugLog(`session-start onboarding detection failed: ${errorMessage(err)}`);
+    }
+}
+// ── Q21: Conversation memory capture ─────────────────────────────────────────
+const INSIGHT_KEYWORDS = [
+    "always", "never", "important", "pitfall", "gotcha", "trick", "workaround",
+    "careful", "caveat", "beware", "note that", "make sure",
+    "don't forget", "remember to", "must", "avoid", "prefer",
+];
+const INSIGHT_KEYWORD_RE = new RegExp(`\\b(${INSIGHT_KEYWORDS.join("|")})\\b`, "i");
+/**
+ * Extract potential insights from conversation text using keyword heuristics.
+ * Returns lines that contain insight-signal words and look like actionable knowledge.
+ */
+export function extractConversationInsights(text) {
+    const lines = text.split("\n").filter(l => l.trim().length > 20 && l.trim().length < 300);
+    const insights = [];
+    const seen = new Set();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip code-only lines, headers, etc.
+        if (trimmed.startsWith("```") || trimmed.startsWith("#") || trimmed.startsWith("//"))
+            continue;
+        if (trimmed.startsWith("$") || trimmed.startsWith(">"))
+            continue;
+        if (INSIGHT_KEYWORD_RE.test(trimmed) || hasExplicitFindingSignal(trimmed)) {
+            // Normalize for dedup
+            const normalized = trimmed.toLowerCase().replace(/\s+/g, " ");
+            if (!seen.has(normalized)) {
+                seen.add(normalized);
+                insights.push(trimmed);
+            }
+        }
+    }
+    // Cap to prevent flooding
+    return insights.slice(0, 5);
+}
+export function filterConversationInsightsForProactivity(insights, level = getProactivityLevelForFindings(getPhrenPath())) {
+    if (level === "high")
+        return insights;
+    return insights.filter((insight) => shouldAutoCaptureFindingsForLevel(level, insight));
+}
+export async function handleHookStop() {
+    const ctx = buildHookContext();
+    const { phrenPath, activeProject, manifest } = ctx;
+    const now = new Date().toISOString();
+    bootstrapPhrenDotEnv(phrenPath);
+    if (!ctx.hooksEnabled) {
+        handleGuardSkip(ctx, "hook_stop", "disabled", {
+            lastStopAt: now,
+            lastAutoSave: { at: now, status: "clean", detail: "hooks disabled by preference" },
+        });
+        return;
+    }
+    if (!ctx.toolHookEnabled) {
+        handleGuardSkip(ctx, "hook_stop", `tool_disabled tool=${ctx.hookTool}`);
+        return;
+    }
+    if (!isProjectHookEnabled(phrenPath, activeProject, "Stop")) {
+        handleGuardSkip(ctx, "hook_stop", `project_disabled project=${activeProject}`, {
+            lastStopAt: now,
+            lastAutoSave: { at: now, status: "clean", detail: `hooks disabled for project ${activeProject}` },
+        });
+        return;
+    }
+    // Read stdin early — it's a stream and can only be consumed once.
+    // Needed for auto-capture transcript_path parsing.
+    const stdinPayload = readStdinJson();
+    const taskSessionId = typeof stdinPayload?.session_id === "string" ? stdinPayload.session_id : undefined;
+    const taskLevel = getProactivityLevelForTask(phrenPath);
+    if (taskSessionId && taskLevel !== "high") {
+        debugLog(`hook-stop task proactivity=${taskLevel}`);
+    }
+    // Auto-capture BEFORE git operations so captured insights get committed and pushed.
+    // Gated behind PHREN_FEATURE_AUTO_CAPTURE=1.
+    const findingsLevel = getProactivityLevelForFindings(phrenPath);
+    if (isFeatureEnabled("PHREN_FEATURE_AUTO_CAPTURE", false) && findingsLevel !== "low") {
+        try {
+            let captureInput = process.env.PHREN_CONVERSATION_CONTEXT || "";
+            if (!captureInput && stdinPayload?.transcript_path) {
+                const transcriptPath = stdinPayload.transcript_path;
+                if (!isSafeTranscriptPath(transcriptPath)) {
+                    debugLog(`auto-capture: skipping unsafe transcript_path: ${transcriptPath}`);
+                }
+                else if (fs.existsSync(transcriptPath)) {
+                    // Cap at last 500 lines (~50 KB) to bound memory usage for long sessions
+                    const raw = fs.readFileSync(transcriptPath, "utf-8");
+                    const allLines = raw.split("\n").filter(Boolean);
+                    const lines = allLines.length > 500 ? allLines.slice(-500) : allLines;
+                    const assistantTexts = [];
+                    for (const line of lines) {
+                        try {
+                            const msg = JSON.parse(line);
+                            if (msg.role !== "assistant")
+                                continue;
+                            if (typeof msg.content === "string")
+                                assistantTexts.push(msg.content);
+                            else if (Array.isArray(msg.content)) {
+                                for (const block of msg.content) {
+                                    if (block.type === "text" && block.text)
+                                        assistantTexts.push(block.text);
+                                }
+                            }
+                        }
+                        catch (err) {
+                            if (process.env.PHREN_DEBUG)
+                                process.stderr.write(`[phren] hookSessionStart transcriptParse: ${errorMessage(err)}\n`);
+                        }
+                    }
+                    captureInput = assistantTexts.join("\n");
+                }
+            }
+            if (captureInput) {
+                if (activeProject) {
+                    // Check session cap before extracting — same guard as PostToolUse hook
+                    let capReached = false;
+                    if (taskSessionId) {
+                        try {
+                            const capFile = sessionMarker(phrenPath, `tool-findings-${taskSessionId}`);
+                            let count = 0;
+                            if (fs.existsSync(capFile)) {
+                                count = Number.parseInt(fs.readFileSync(capFile, "utf8").trim(), 10) || 0;
+                            }
+                            const sessionCap = getSessionCap();
+                            if (count >= sessionCap) {
+                                debugLog(`hook-stop: session cap reached (${count}/${sessionCap}), skipping extraction`);
+                                capReached = true;
+                            }
+                        }
+                        catch (err) {
+                            if (process.env.PHREN_DEBUG)
+                                process.stderr.write(`[phren] hookStop sessionCapCheck: ${errorMessage(err)}\n`);
+                        }
+                    }
+                    if (!capReached) {
+                        const insights = filterConversationInsightsForProactivity(extractConversationInsights(captureInput), findingsLevel);
+                        for (const insight of insights) {
+                            appendFindingJournal(phrenPath, activeProject, `[pattern] ${insight}`, {
+                                source: "hook",
+                                sessionId: `hook-stop-${Date.now()}`,
+                            });
+                            debugLog(`auto-capture: saved insight for ${activeProject}: ${insight.slice(0, 60)}`);
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            debugLog(`auto-capture failed: ${errorMessage(err)}`);
+        }
+    }
+    else if (isFeatureEnabled("PHREN_FEATURE_AUTO_CAPTURE", false)) {
+        debugLog("auto-capture: skipped because findings proactivity is low");
+    }
+    // Wrap git operations in a file lock to prevent concurrent agents from fighting
+    const gitOpLockPath = path.join(phrenPath, ".runtime", "git-op");
+    await withFileLock(gitOpLockPath, async () => {
+        if (manifest?.installMode === "project-local") {
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: { at: now, status: "saved-local", detail: "project-local mode writes files only" },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "saved-local",
+                    lastPushDetail: "project-local mode does not manage git sync",
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", "status=skipped-local");
+            return;
+        }
+        const gitRepo = ensureLocalGitRepo(phrenPath);
+        if (!gitRepo.ok) {
+            finalizeTaskSession({
+                phrenPath,
+                sessionId: taskSessionId,
+                status: "error",
+                detail: gitRepo.detail,
+            });
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: { at: now, status: "error", detail: gitRepo.detail },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "error",
+                    lastPushDetail: gitRepo.detail,
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", `status=error detail=${JSON.stringify(gitRepo.detail)}`);
+            return;
+        }
+        const status = await runBestEffortGit(["status", "--porcelain"], phrenPath);
+        if (!status.ok) {
+            finalizeTaskSession({
+                phrenPath,
+                sessionId: taskSessionId,
+                status: "error",
+                detail: status.error || "git status failed",
+            });
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: { at: now, status: "error", detail: status.error || "git status failed" },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "error",
+                    lastPushDetail: status.error || "git status failed",
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", `status=error detail=${JSON.stringify(status.error || "git status failed")}`);
+            return;
+        }
+        if (!status.output) {
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: { at: now, status: "clean", detail: "no changes" },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "saved-pushed",
+                    lastPushDetail: "no changes",
+                    unsyncedCommits: 0,
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", "status=clean");
+            return;
+        }
+        // Exclude sensitive files from staging: .env files and private keys should
+        // never be committed to the phren git repository.
+        const add = await runBestEffortGit(["add", "-A", "--", ":(exclude).env", ":(exclude)**/.env", ":(exclude)*.pem", ":(exclude)*.key"], phrenPath);
+        let commitMsg = "auto-save phren";
+        if (add.ok) {
+            const diff = await runBestEffortGit(["diff", "--cached", "--stat", "--no-color"], phrenPath);
+            if (diff.ok && diff.output) {
+                // Parse "project/file.md | 3 +++" lines into project names and file types
+                const changes = new Map();
+                for (const line of diff.output.split("\n")) {
+                    const m = line.match(/^\s*([^/]+)\/([^|]+)\s*\|/);
+                    if (!m)
+                        continue;
+                    const proj = m[1].trim();
+                    if (proj.startsWith("."))
+                        continue; // skip .governance, .runtime, etc.
+                    const file = m[2].trim();
+                    if (!changes.has(proj))
+                        changes.set(proj, new Set());
+                    if (/findings/i.test(file))
+                        changes.get(proj).add("findings");
+                    else if (/tasks/i.test(file))
+                        changes.get(proj).add("task");
+                    else if (/CLAUDE/i.test(file))
+                        changes.get(proj).add("config");
+                    else if (/summary/i.test(file))
+                        changes.get(proj).add("summary");
+                    else if (/skill/i.test(file))
+                        changes.get(proj).add("skills");
+                    else if (/reference/i.test(file))
+                        changes.get(proj).add("reference");
+                    else
+                        changes.get(proj).add("update");
+                }
+                if (changes.size > 0) {
+                    const parts = [...changes.entries()].map(([proj, types]) => `${proj}(${[...types].join(",")})`);
+                    commitMsg = `phren: ${parts.join(" ")}`;
+                }
+            }
+        }
+        const commit = add.ok ? await runBestEffortGit(["commit", "-m", commitMsg], phrenPath) : { ok: false, error: add.error };
+        if (!add.ok || !commit.ok) {
+            finalizeTaskSession({
+                phrenPath,
+                sessionId: taskSessionId,
+                status: "error",
+                detail: add.error || commit.error || "git add/commit failed",
+            });
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: {
+                    at: now,
+                    status: "error",
+                    detail: add.error || commit.error || "git add/commit failed",
+                },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "error",
+                    lastPushDetail: add.error || commit.error || "git add/commit failed",
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", `status=error detail=${JSON.stringify(add.error || commit.error || "git add/commit failed")}`);
+            return;
+        }
+        const remotes = await runBestEffortGit(["remote"], phrenPath);
+        if (!remotes.ok || !remotes.output) {
+            finalizeTaskSession({
+                phrenPath,
+                sessionId: taskSessionId,
+                status: "saved-local",
+                detail: "commit created; no remote configured",
+            });
+            const unsyncedCommits = await countUnsyncedCommits(phrenPath);
+            updateRuntimeHealth(phrenPath, {
+                lastStopAt: now,
+                lastAutoSave: { at: now, status: "saved-local", detail: "commit created; no remote configured" },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "saved-local",
+                    lastPushDetail: "commit created; no remote configured",
+                    unsyncedCommits,
+                },
+            });
+            appendAuditLog(phrenPath, "hook_stop", "status=saved-local");
+            return;
+        }
+        const unsyncedCommits = await countUnsyncedCommits(phrenPath);
+        const scheduled = scheduleBackgroundSync(phrenPath);
+        const syncDetail = scheduled
+            ? "commit saved; background sync scheduled"
+            : "commit saved; background sync already running";
+        finalizeTaskSession({
+            phrenPath,
+            sessionId: taskSessionId,
+            status: "saved-local",
+            detail: syncDetail,
+        });
+        updateRuntimeHealth(phrenPath, {
+            lastStopAt: now,
+            lastAutoSave: { at: now, status: "saved-local", detail: syncDetail },
+            lastSync: {
+                lastPushAt: now,
+                lastPushStatus: "saved-local",
+                lastPushDetail: syncDetail,
+                unsyncedCommits,
+            },
+        });
+        appendAuditLog(phrenPath, "hook_stop", `status=saved-local detail=${JSON.stringify(syncDetail)}`);
+    }); // end withFileLock(gitOpLockPath)
+    // Auto governance scheduling (non-blocking)
+    scheduleWeeklyGovernance();
+}
+export async function handleBackgroundSync() {
+    const phrenPathLocal = getPhrenPath();
+    const now = new Date().toISOString();
+    const lockPath = runtimeFile(phrenPathLocal, "background-sync.lock");
+    try {
+        const remotes = await runBestEffortGit(["remote"], phrenPathLocal);
+        if (!remotes.ok || !remotes.output) {
+            const unsyncedCommits = await countUnsyncedCommits(phrenPathLocal);
+            updateRuntimeHealth(phrenPathLocal, {
+                lastAutoSave: { at: now, status: "saved-local", detail: "background sync skipped; no remote configured" },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "saved-local",
+                    lastPushDetail: "background sync skipped; no remote configured",
+                    unsyncedCommits,
+                },
+            });
+            appendAuditLog(phrenPathLocal, "background_sync", "status=saved-local detail=no_remote");
+            return;
+        }
+        const push = await runBestEffortGit(["push"], phrenPathLocal);
+        if (push.ok) {
+            updateRuntimeHealth(phrenPathLocal, {
+                lastAutoSave: { at: now, status: "saved-pushed", detail: "commit pushed by background sync" },
+                lastSync: {
+                    lastPushAt: now,
+                    lastPushStatus: "saved-pushed",
+                    lastPushDetail: "commit pushed by background sync",
+                    unsyncedCommits: 0,
+                },
+            });
+            appendAuditLog(phrenPathLocal, "background_sync", "status=saved-pushed");
+            return;
+        }
+        const recovered = await recoverPushConflict(phrenPathLocal);
+        if (recovered.ok) {
+            updateRuntimeHealth(phrenPathLocal, {
+                lastAutoSave: { at: now, status: "saved-pushed", detail: recovered.detail },
+                lastSync: {
+                    lastPullAt: now,
+                    lastPullStatus: recovered.pullStatus,
+                    lastPullDetail: recovered.pullDetail,
+                    lastSuccessfulPullAt: now,
+                    lastPushAt: now,
+                    lastPushStatus: "saved-pushed",
+                    lastPushDetail: recovered.detail,
+                    unsyncedCommits: 0,
+                },
+            });
+            appendAuditLog(phrenPathLocal, "background_sync", `status=saved-pushed detail=${JSON.stringify(recovered.detail)}`);
+            return;
+        }
+        const unsyncedCommits = await countUnsyncedCommits(phrenPathLocal);
+        updateRuntimeHealth(phrenPathLocal, {
+            lastAutoSave: { at: now, status: "saved-local", detail: recovered.detail || push.error || "background sync push failed" },
+            lastSync: {
+                lastPullAt: now,
+                lastPullStatus: recovered.pullStatus,
+                lastPullDetail: recovered.pullDetail,
+                lastPushAt: now,
+                lastPushStatus: "saved-local",
+                lastPushDetail: recovered.detail || push.error || "background sync push failed",
+                unsyncedCommits,
+            },
+        });
+        appendAuditLog(phrenPathLocal, "background_sync", `status=saved-local detail=${JSON.stringify(recovered.detail || push.error || "background sync push failed")}`);
+    }
+    finally {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch { }
+    }
+}
+function scheduleWeeklyGovernance() {
+    try {
+        const lastGovPath = runtimeFile(getPhrenPath(), "last-governance.txt");
+        const lastRun = fs.existsSync(lastGovPath) ? parseInt(fs.readFileSync(lastGovPath, "utf8"), 10) : 0;
+        const daysSince = (Date.now() - lastRun) / 86_400_000;
+        if (daysSince >= 7) {
+            const spawnArgs = resolveSubprocessArgs("background-maintenance");
+            if (spawnArgs) {
+                const child = spawn(process.execPath, spawnArgs, { detached: true, stdio: "ignore" });
+                child.unref();
+                fs.writeFileSync(lastGovPath, Date.now().toString());
+                debugLog("hook_stop: scheduled weekly governance run");
+            }
+        }
+    }
+    catch (err) {
+        debugLog(`hook_stop: governance scheduling failed: ${errorMessage(err)}`);
+    }
+}
+export async function handleHookContext() {
+    const ctx = buildHookContext();
+    if (!ctx.hooksEnabled) {
+        process.exit(0);
+    }
+    let cwd = ctx.cwd;
+    const ctxStdin = readStdinJson();
+    if (ctxStdin?.cwd)
+        cwd = ctxStdin.cwd;
+    const project = cwd !== ctx.cwd ? detectProject(ctx.phrenPath, cwd, ctx.profile) : ctx.activeProject;
+    if (!isProjectHookEnabled(ctx.phrenPath, project, "UserPromptSubmit")) {
+        process.exit(0);
+    }
+    const db = await buildIndex(ctx.phrenPath, ctx.profile);
+    const contextLabel = project ? `\u25c6 phren \u00b7 ${project} \u00b7 context` : `\u25c6 phren \u00b7 context`;
+    const parts = [contextLabel, "<phren-context>"];
+    if (project) {
+        const summaryRow = queryRows(db, "SELECT content FROM docs WHERE project = ? AND type = 'summary'", [project]);
+        if (summaryRow) {
+            parts.push(`# ${project}`);
+            parts.push(summaryRow[0][0]);
+            parts.push("");
+        }
+        const findingsRow = queryRows(db, "SELECT content FROM docs WHERE project = ? AND type = 'findings'", [project]);
+        if (findingsRow) {
+            const content = findingsRow[0][0];
+            const bullets = content.split("\n").filter(l => l.startsWith("- ")).slice(0, 10);
+            if (bullets.length > 0) {
+                parts.push("## Recent findings");
+                parts.push(bullets.join("\n"));
+                parts.push("");
+            }
+        }
+        const taskRow = queryRows(db, "SELECT content FROM docs WHERE project = ? AND type = 'task'", [project]);
+        if (taskRow) {
+            const content = taskRow[0][0];
+            const activeItems = content.split("\n").filter(l => l.startsWith("- "));
+            const filtered = filterTaskByPriority(activeItems);
+            const trimmed = filtered.slice(0, 5);
+            if (trimmed.length > 0) {
+                parts.push("## Active tasks");
+                parts.push(trimmed.join("\n"));
+                parts.push("");
+            }
+        }
+    }
+    else {
+        const projectRows = queryRows(db, "SELECT DISTINCT project FROM docs ORDER BY project", []);
+        if (projectRows) {
+            parts.push("# Phren projects");
+            parts.push(projectRows.map(r => `- ${r[0]}`).join("\n"));
+            parts.push("");
+        }
+    }
+    parts.push("<phren-context>");
+    if (parts.length > 2) {
+        console.log(parts.join("\n"));
+    }
+}
+// ── PostToolUse hook ─────────────────────────────────────────────────────────
+const INTERESTING_TOOLS = new Set(["Read", "Write", "Edit", "Bash", "Glob", "Grep"]);
+const COOLDOWN_MS = parseInt(process.env.PHREN_AUTOCAPTURE_COOLDOWN_MS ?? "30000", 10);
+function getSessionCap() {
+    if (process.env.PHREN_AUTOCAPTURE_SESSION_CAP) {
+        return parseInt(process.env.PHREN_AUTOCAPTURE_SESSION_CAP, 10);
+    }
+    try {
+        const policy = getWorkflowPolicy(getPhrenPath());
+        const sensitivity = policy.findingSensitivity ?? "balanced";
+        return FINDING_SENSITIVITY_CONFIG[sensitivity]?.sessionCap ?? 10;
+    }
+    catch {
+        return 10;
+    }
+}
+function flattenToolResponseText(value, maxChars = 4000) {
+    if (typeof value === "string")
+        return value;
+    const queue = [value];
+    const parts = [];
+    let length = 0;
+    while (queue.length > 0 && length < maxChars) {
+        const current = queue.shift();
+        if (typeof current === "string") {
+            const trimmed = current.trim();
+            if (!trimmed)
+                continue;
+            parts.push(trimmed);
+            length += trimmed.length + 1;
+            continue;
+        }
+        if (Array.isArray(current)) {
+            queue.unshift(...current);
+            continue;
+        }
+        if (current && typeof current === "object") {
+            queue.unshift(...Object.values(current));
+        }
+    }
+    if (parts.length > 0)
+        return parts.join("\n").slice(0, maxChars);
+    return JSON.stringify(value ?? "").slice(0, maxChars);
+}
+export async function handleHookTool() {
+    const ctx = buildHookContext();
+    if (!ctx.hooksEnabled) {
+        process.exit(0);
+    }
+    try {
+        const start = Date.now();
+        let raw = "";
+        if (!process.stdin.isTTY) {
+            try {
+                raw = fs.readFileSync(0, "utf-8");
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] hookTool stdinRead: ${errorMessage(err)}\n`);
+                process.exit(0);
+            }
+        }
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch (err) {
+            if (process.env.PHREN_DEBUG)
+                process.stderr.write(`[phren] hookTool stdinParse: ${errorMessage(err)}\n`);
+            process.exit(0);
+        }
+        const toolName = String(data.tool_name ?? data.tool ?? "");
+        if (!INTERESTING_TOOLS.has(toolName)) {
+            process.exit(0);
+        }
+        const sessionId = data.session_id;
+        const input = (data.tool_input ?? {});
+        const entry = {
+            at: new Date().toISOString(),
+            session_id: sessionId,
+            tool: toolName,
+        };
+        if (toolName === "Read" || toolName === "Write" || toolName === "Edit") {
+            const filePath = input.file_path ?? input.path ?? undefined;
+            if (filePath)
+                entry.file = String(filePath);
+        }
+        else if (toolName === "Bash") {
+            const cmd = input.command ?? undefined;
+            if (cmd)
+                entry.command = String(cmd).slice(0, 200);
+        }
+        else if (toolName === "Glob") {
+            const pattern = input.pattern ?? undefined;
+            if (pattern)
+                entry.file = String(pattern);
+        }
+        else if (toolName === "Grep") {
+            const pattern = input.pattern ?? undefined;
+            const searchPath = input.path ?? undefined;
+            if (pattern)
+                entry.command = `grep ${pattern}${searchPath ? ` in ${searchPath}` : ""}`.slice(0, 200);
+        }
+        const responseStr = flattenToolResponseText(data.tool_response ?? "");
+        if (/(error|exception|failed|no such file|ENOENT)/i.test(responseStr)) {
+            entry.error = responseStr.slice(0, 300);
+        }
+        const cwd = (data.cwd ?? input.cwd ?? undefined);
+        let activeProject = cwd ? detectProject(ctx.phrenPath, cwd, ctx.profile) : null;
+        if (!isProjectHookEnabled(ctx.phrenPath, activeProject, "PostToolUse")) {
+            appendAuditLog(ctx.phrenPath, "hook_tool", `status=project_disabled project=${activeProject}`);
+            process.exit(0);
+        }
+        try {
+            const logFile = runtimeFile(ctx.phrenPath, "tool-log.jsonl");
+            fs.mkdirSync(path.dirname(logFile), { recursive: true });
+            fs.appendFileSync(logFile, JSON.stringify(entry) + "\n");
+        }
+        catch (err) {
+            if (process.env.PHREN_DEBUG)
+                process.stderr.write(`[phren] hookTool toolLog: ${errorMessage(err)}\n`);
+        }
+        const cooldownFile = runtimeFile(ctx.phrenPath, "hook-tool-cooldown");
+        try {
+            if (fs.existsSync(cooldownFile)) {
+                const age = Date.now() - fs.statSync(cooldownFile).mtimeMs;
+                if (age < COOLDOWN_MS) {
+                    debugLog(`hook-tool: cooldown active (${Math.round(age / 1000)}s < ${Math.round(COOLDOWN_MS / 1000)}s), skipping extraction`);
+                    activeProject = null;
+                }
+            }
+        }
+        catch (err) {
+            if (process.env.PHREN_DEBUG)
+                process.stderr.write(`[phren] hookTool cooldownStat: ${errorMessage(err)}\n`);
+        }
+        if (activeProject && sessionId) {
+            try {
+                const capFile = sessionMarker(ctx.phrenPath, `tool-findings-${sessionId}`);
+                let count = 0;
+                if (fs.existsSync(capFile)) {
+                    count = Number.parseInt(fs.readFileSync(capFile, "utf8").trim(), 10) || 0;
+                }
+                const sessionCap = getSessionCap();
+                if (count >= sessionCap) {
+                    debugLog(`hook-tool: session cap reached (${count}/${sessionCap}), skipping extraction`);
+                    activeProject = null;
+                }
+            }
+            catch (err) {
+                if (process.env.PHREN_DEBUG)
+                    process.stderr.write(`[phren] hookTool sessionCapCheck: ${errorMessage(err)}\n`);
+            }
+        }
+        const findingsLevelForTool = getProactivityLevelForFindings(ctx.phrenPath);
+        if (activeProject && findingsLevelForTool !== "low") {
+            try {
+                const candidates = filterToolFindingsForProactivity(extractToolFindings(toolName, input, responseStr), findingsLevelForTool);
+                for (const { text, confidence } of candidates) {
+                    appendReviewQueue(ctx.phrenPath, activeProject, "Review", [text]);
+                    debugLog(`hook-tool: queued candidate for review (conf=${confidence}): ${text.slice(0, 60)}`);
+                }
+                if (candidates.length > 0) {
+                    try {
+                        fs.writeFileSync(cooldownFile, Date.now().toString());
+                    }
+                    catch (err) {
+                        if (process.env.PHREN_DEBUG)
+                            process.stderr.write(`[phren] hookTool cooldownWrite: ${errorMessage(err)}\n`);
+                    }
+                    if (sessionId) {
+                        try {
+                            const capFile = sessionMarker(ctx.phrenPath, `tool-findings-${sessionId}`);
+                            let count = 0;
+                            try {
+                                count = Number.parseInt(fs.readFileSync(capFile, "utf8").trim(), 10) || 0;
+                            }
+                            catch (err) {
+                                if (process.env.PHREN_DEBUG)
+                                    process.stderr.write(`[phren] hookTool capFileRead: ${errorMessage(err)}\n`);
+                            }
+                            count += candidates.length;
+                            fs.writeFileSync(capFile, count.toString());
+                        }
+                        catch (err) {
+                            if (process.env.PHREN_DEBUG)
+                                process.stderr.write(`[phren] hookTool capFileWrite: ${errorMessage(err)}\n`);
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                debugLog(`hook-tool: finding extraction failed: ${errorMessage(err)}`);
+            }
+        }
+        else if (activeProject) {
+            debugLog("hook-tool: skipped because findings proactivity is low");
+        }
+        const elapsed = Date.now() - start;
+        debugLog(`hook-tool: ${toolName} logged in ${elapsed}ms`);
+        process.exit(0);
+    }
+    catch (err) {
+        debugLog(`hook-tool: unhandled error: ${err instanceof Error ? err.stack || err.message : String(err)}`);
+        process.exit(0);
+    }
+}
+const EXPLICIT_TAG_PATTERN = /\[(pitfall|decision|pattern|tradeoff|architecture|bug)\]\s*(.+)/i;
+export function filterToolFindingsForProactivity(candidates, level = getProactivityLevelForFindings(getPhrenPath())) {
+    if (level === "high")
+        return candidates;
+    if (level === "low")
+        return [];
+    return candidates.filter((candidate) => candidate.explicit === true);
+}
+export function extractToolFindings(toolName, input, responseStr) {
+    const candidates = [];
+    const changedContent = (toolName === "Edit" || toolName === "Write")
+        ? String(input.new_string ?? input.content ?? "")
+        : "";
+    const explicitSource = changedContent || responseStr;
+    const tagMatches = explicitSource.matchAll(new RegExp(EXPLICIT_TAG_PATTERN.source, "gi"));
+    for (const m of tagMatches) {
+        const tag = m[1].toLowerCase();
+        const content = m[2].replace(/\s+/g, " ").trim().slice(0, 200);
+        if (content) {
+            candidates.push({ text: `[${tag}] ${content}`, confidence: 0.85, explicit: true });
+        }
+    }
+    if (toolName === "Edit" || toolName === "Write") {
+        const filePath = String(input.file_path ?? input.path ?? "unknown");
+        const filename = path.basename(filePath);
+        if (/\b(TODO|FIXME)\b/.test(changedContent)) {
+            const firstLine = changedContent.split("\n").find((l) => /\b(TODO|FIXME)\b/.test(l));
+            if (firstLine) {
+                candidates.push({
+                    text: `[pitfall] ${filename}: ${firstLine.trim().slice(0, 150)}`,
+                    confidence: 0.45,
+                    explicit: false,
+                });
+            }
+        }
+        if (/\btry\s*\{[\s\S]*?\bcatch\b/.test(changedContent)) {
+            const meaningfulLine = changedContent.split("\n").find((l) => l.trim().length > 10 && !/^\s*(try|catch|\{|\})/.test(l));
+            if (meaningfulLine) {
+                candidates.push({
+                    text: `[pitfall] ${filename}: error handling added near "${meaningfulLine.trim().slice(0, 100)}"`,
+                    confidence: 0.45,
+                    explicit: false,
+                });
+            }
+        }
+    }
+    if (toolName === "Bash") {
+        const cmd = String(input.command ?? "").slice(0, 30);
+        const hasError = /(error|exception|failed|ENOENT|command not found|permission denied)/i.test(responseStr);
+        if (hasError && cmd) {
+            const firstErrorLine = responseStr.split("\n").find((l) => /(error|exception|failed|ENOENT|command not found|permission denied)/i.test(l));
+            if (firstErrorLine) {
+                candidates.push({
+                    text: `[bug] command '${cmd}' failed: ${firstErrorLine.trim().slice(0, 150)}`,
+                    confidence: 0.55,
+                    explicit: false,
+                });
+            }
+        }
+    }
+    return candidates;
+}