@phren/cli 0.1.13 → 0.1.14

package/dist/cli/hooks-session.js

@@ -1,1484 +1,23 @@
-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, buildSyncStatus, } from "./hooks-context.js";
-import { sessionMetricsFile, qualityMarkers, } from "../shared.js";
-import { autoMergeConflicts, mergeTask, mergeFindings, } from "../shared/content.js";
-import { runGit } from "../utils.js";
-import { readInstallPreferences } from "../init/preferences.js";
-import * as fs from "fs";
-import * as path from "path";
-import * as os from "os";
-import { execFileSync } from "child_process";
-import { spawnDetachedChild } from "../shared/process.js";
-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";
-import { logger } from "../logger.js";
-import * as crypto from "crypto";
-import { sessionFileForId, readSessionStateFile, writeSessionStateFile, } from "../session/utils.js";
-const SYNC_LOCK_STALE_MS = 10 * 60 * 1000; // 10 minutes
-const MAINTENANCE_LOCK_STALE_MS = 2 * 60 * 60 * 1000; // 2 hours
-export { buildHookContext, handleGuardSkip } from "./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) {
-        logger.debug("hooks-session", `readStdinJson: ${errorMessage(err)}`);
-        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 `phren add` to track it now.",
-        `Suggested command: \`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 `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 \`phren add\` from that directory.`,
-        "After onboarding, run `phren doctor` if hooks or MCP tools are not responding.",
-        "<phren-notice>",
-        "",
-    ].join("\n");
-}
-const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
-const SYNC_WARN_MARKER = "sync-broken-warned-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 `phren add` so SessionStart can inject project context.",
-            "Run `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 `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) {
-    // Prefer the entry script that started this process
-    const entry = process.argv[1];
-    if (entry && fs.existsSync(entry) && /index\.(ts|js)$/.test(entry))
-        return [entry, command];
-    // Fallback: look for index.js next to this file or one level up (for subdirectory builds)
-    const thisDir = path.dirname(fileURLToPath(import.meta.url));
-    for (const dir of [thisDir, path.dirname(thisDir)]) {
-        const candidate = path.join(dir, "index.js");
-        if (fs.existsSync(candidate))
-            return [candidate, 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 <= SYNC_LOCK_STALE_MS)
-                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 = spawnDetachedChild(spawnArgs, { phrenPath: phrenPathLocal, logFd });
-        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 <= MAINTENANCE_LOCK_STALE_MS)
-                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
-            logger.debug("hooks-session", `backgroundMaintenance lockClaim: ${errorMessage(err)}`);
-            return false;
-        }
-        try {
-            fs.writeSync(fd, lockContent);
-        }
-        finally {
-            fs.closeSync(fd);
-        }
-        if (project)
-            spawnArgs.push(project);
-        const logDir = path.join(phrenPathLocal, ".config");
-        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 = spawnDetachedChild(spawnArgs, { phrenPath: phrenPathLocal, logFd });
-        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) {
-                logger.debug("hooks-session", `backgroundMaintenance exitLog: ${errorMessage(err)}`);
-            }
-            if (code === 0) {
-                try {
-                    fs.writeFileSync(markers.done, new Date().toISOString() + "\n");
-                }
-                catch (err) {
-                    logger.debug("hooks-session", `backgroundMaintenance doneMarker: ${errorMessage(err)}`);
-                }
-            }
-            try {
-                fs.unlinkSync(markers.lock);
-            }
-            catch (err) {
-                logger.debug("hooks-session", `backgroundMaintenance unlockOnExit: ${errorMessage(err)}`);
-            }
-        });
-        child.on("error", (spawnErr) => {
-            const msg = `[${new Date().toISOString()}] spawn error: ${spawnErr.message}\n`;
-            try {
-                fs.appendFileSync(logPath, msg);
-            }
-            catch (err) {
-                logger.debug("hooks-session", `backgroundMaintenance errorLog: ${errorMessage(err)}`);
-            }
-            try {
-                fs.unlinkSync(markers.lock);
-            }
-            catch (err) {
-                logger.debug("hooks-session", `backgroundMaintenance unlockOnError: ${errorMessage(err)}`);
-            }
-        });
-        fs.closeSync(logFd);
-        child.unref();
-        return true;
-    }
-    catch (err) {
-        const errMsg = errorMessage(err);
-        try {
-            const logDir = path.join(phrenPathLocal, ".config");
-            fs.mkdirSync(logDir, { recursive: true });
-            fs.appendFileSync(path.join(logDir, "background-maintenance.log"), `[${new Date().toISOString()}] spawn failed: ${errMsg}\n`);
-        }
-        catch (err) {
-            logger.debug("hooks-session", `backgroundMaintenance logSpawnFailure: ${errorMessage(err)}`);
-        }
-        try {
-            fs.unlinkSync(markers.lock);
-        }
-        catch (err) {
-            logger.debug("hooks-session", `backgroundMaintenance unlockOnFailure: ${errorMessage(err)}`);
-        }
-        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) {
-        const allCommits = await runBestEffortGit(["rev-list", "--count", "HEAD"], cwd);
-        if (!allCommits.ok || !allCommits.output)
-            return 0;
-        const parsed = Number.parseInt(allCommits.output.trim(), 10);
-        return Number.isNaN(parsed) ? 0 : parsed;
-    }
-    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) {
-        logger.debug("hooks-session", `hookSessionStart trackSession: ${errorMessage(err)}`);
-    }
-    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"}`);
-    // Pull non-primary stores from store registry (best-effort, non-blocking)
-    try {
-        const { getNonPrimaryStores } = await import("../store-registry.js");
-        const otherStores = getNonPrimaryStores(phrenPath);
-        for (const store of otherStores) {
-            if (!fs.existsSync(store.path) || !fs.existsSync(path.join(store.path, ".git")))
-                continue;
-            try {
-                await runBestEffortGit(["pull", "--rebase", "--quiet"], store.path);
-            }
-            catch (err) {
-                debugLog(`session-start store-pull ${store.name}: ${errorMessage(err)}`);
-            }
-        }
-    }
-    catch {
-        // store-registry not available or no stores — skip silently
-    }
-    // Sync intent warning: if the user intended sync but remote is missing or pull failed, warn once
-    try {
-        const syncPrefs = readInstallPreferences(phrenPath);
-        const syncBroken = syncPrefs.syncIntent === "sync" && (!hasRemote || !pull.ok);
-        if (syncBroken) {
-            const syncWarnPath = sessionMarker(phrenPath, SYNC_WARN_MARKER);
-            if (!fs.existsSync(syncWarnPath)) {
-                const reason = !hasRemote
-                    ? "no git remote is connected"
-                    : `pull failed: ${pull.error || "unknown error"}`;
-                process.stdout.write([
-                    "<phren-notice>",
-                    `Sync is configured but ${reason}. Your phren data is local-only.`,
-                    `To fix: cd ${phrenPath} && git remote add origin <YOUR_REPO_URL> && git push -u origin main`,
-                    "<phren-notice>",
-                    "",
-                ].join("\n"));
-                try {
-                    fs.writeFileSync(syncWarnPath, `${startedAt}\n`);
-                }
-                catch (err) {
-                    debugLog(`sync-warn marker write failed: ${errorMessage(err)}`);
-                }
-            }
-        }
-    }
-    catch (err) {
-        debugLog(`sync-intent check failed: ${errorMessage(err)}`);
-    }
-    // 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)}`);
-    }
-    // ── Bridge: create a real session record so session_history tracks hook sessions ──
-    // Uses a file lock to prevent concurrent SessionStart hooks from racing on
-    // the active-hook-session pointer (read previous ID, end it, write new ID).
-    try {
-        const activeSessionFile = runtimeFile(phrenPath, "active-hook-session");
-        withFileLock(activeSessionFile, () => {
-            // Retroactively end the previous hook session (if any)
-            try {
-                const prevId = fs.readFileSync(activeSessionFile, "utf-8").trim();
-                if (prevId) {
-                    const prevFile = sessionFileForId(phrenPath, prevId);
-                    const prevState = readSessionStateFile(prevFile);
-                    if (prevState && !prevState.endedAt) {
-                        writeSessionStateFile(prevFile, { ...prevState, endedAt: startedAt });
-                    }
-                }
-            }
-            catch (err) {
-                // ENOENT is expected on the very first session — only log other errors
-                if (err.code !== "ENOENT") {
-                    debugLog(`session-bridge end-previous failed: ${errorMessage(err)}`);
-                }
-            }
-            // Create new session record
-            const sessionId = crypto.randomUUID();
-            const sessionState = {
-                sessionId,
-                project: activeProject || undefined,
-                startedAt,
-                findingsAdded: 0,
-                tasksCompleted: 0,
-                hookCreated: true,
-            };
-            writeSessionStateFile(sessionFileForId(phrenPath, sessionId), sessionState);
-            // Write active session ID atomically so other hooks (stop, tool) can reference it.
-            // Plain text format (not JSON) because the reader uses readFileSync + trim.
-            const tmpPath = `${activeSessionFile}.${process.pid}.${Date.now()}.tmp`;
-            fs.writeFileSync(tmpPath, sessionId + "\n");
-            fs.renameSync(tmpPath, activeSessionFile);
-            debugLog(`session-bridge created session ${sessionId.slice(0, 8)} for hook-driven session`);
-        });
-    }
-    catch (err) {
-        debugLog(`session-bridge 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.
+ * Session lifecycle hooks — orchestrator module.
+ *
+ * This file re-exports all session hook functionality from the split modules:
+ * - session-git.ts — Git context and command helpers
+ * - session-metrics.ts — Session metrics tracking
+ * - session-background.ts — Background sync/maintenance scheduling
+ * - session-start.ts — SessionStart hook handler + onboarding notices
+ * - session-stop.ts — Stop hook handler + background sync + conversation capture
+ * - session-tool-hook.ts — PostToolUse and context hook handlers + tool finding extraction
  */
-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) {
-                            logger.debug("hooks-session", `hookStop transcriptParse: ${errorMessage(err)}`);
-                        }
-                    }
-                    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) {
-                            logger.debug("hooks-session", `hookStop sessionCapCheck: ${errorMessage(err)}`);
-                        }
-                    }
-                    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;
-        }
-        // Stage all changes first, then unstage any sensitive files that slipped
-        // through. Using pathspec exclusions with `git add -A` can fail when
-        // excluded paths are also gitignored (git treats the pathspec as an error).
-        let add = await runBestEffortGit(["add", "-A"], phrenPath);
-        if (add.ok) {
-            // Belt-and-suspenders: unstage sensitive files that .gitignore should
-            // already block. Failures here are non-fatal (files may not exist).
-            await runBestEffortGit(["reset", "HEAD", "--", ".env", "**/.env", "*.pem", "*.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 .config, .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: buildSyncStatus({ now, pushStatus: "saved-local", pushDetail: "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: buildSyncStatus({ now, pushStatus: "saved-pushed", pushDetail: "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: buildSyncStatus({ now, pushStatus: "saved-pushed", pushDetail: recovered.detail, pullAt: now, pullStatus: recovered.pullStatus, pullDetail: recovered.pullDetail, successfulPullAt: now, unsyncedCommits: 0 }),
-            });
-            appendAuditLog(phrenPathLocal, "background_sync", `status=saved-pushed detail=${JSON.stringify(recovered.detail)}`);
-            return;
-        }
-        const unsyncedCommits = await countUnsyncedCommits(phrenPathLocal);
-        const failDetail = recovered.detail || push.error || "background sync push failed";
-        updateRuntimeHealth(phrenPathLocal, {
-            lastAutoSave: { at: now, status: "saved-local", detail: failDetail },
-            lastSync: buildSyncStatus({ now, pushStatus: "saved-local", pushDetail: failDetail, pullAt: now, pullStatus: recovered.pullStatus, pullDetail: recovered.pullDetail, unsyncedCommits }),
-        });
-        appendAuditLog(phrenPathLocal, "background_sync", `status=saved-local detail=${JSON.stringify(failDetail)}`);
-    }
-    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 = spawnDetachedChild(spawnArgs, { phrenPath: getPhrenPath() });
-                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("");
-            }
-        }
-        // Collect pinned tasks across ALL projects (excluding Done)
-        const allTaskRows = queryRows(db, "SELECT project, content FROM docs WHERE type = 'task'", []);
-        const pinnedFromOtherProjects = [];
-        if (allTaskRows) {
-            for (const row of allTaskRows) {
-                const taskProject = row[0];
-                if (taskProject === project)
-                    continue;
-                const content = row[1];
-                const pinned = content.split("\n")
-                    .filter(l => l.startsWith("- [ ] ") && /\[pinned\]/i.test(l))
-                    .map(l => `[${taskProject}] ${l}`);
-                pinnedFromOtherProjects.push(...pinned);
-            }
-        }
-        // Active project tasks — pinned float to top, exclude Done
-        const taskRow = queryRows(db, "SELECT content FROM docs WHERE project = ? AND type = 'task'", [project]);
-        const pinnedItems = [];
-        const otherItems = [];
-        if (taskRow) {
-            const content = taskRow[0][0];
-            const allItems = content.split("\n").filter(l => l.startsWith("- [ ] "));
-            for (const item of allItems) {
-                if (/\[pinned\]/i.test(item)) {
-                    pinnedItems.push(item);
-                }
-                else {
-                    otherItems.push(item);
-                }
-            }
-        }
-        const filteredOther = filterTaskByPriority(otherItems);
-        const allPinned = [...pinnedItems, ...pinnedFromOtherProjects].slice(0, 10);
-        const remaining = Math.max(0, 5 - allPinned.length);
-        const trimmedOther = filteredOther.slice(0, remaining);
-        if (allPinned.length > 0 || trimmedOther.length > 0) {
-            if (allPinned.length > 0) {
-                parts.push("## Pinned tasks");
-                parts.push(allPinned.join("\n"));
-            }
-            if (trimmedOther.length > 0) {
-                parts.push("## Active tasks");
-                parts.push(trimmedOther.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) {
-                logger.debug("hooks-session", `hookTool stdinRead: ${errorMessage(err)}`);
-                process.exit(0);
-            }
-        }
-        let data;
-        try {
-            data = JSON.parse(raw);
-        }
-        catch (err) {
-            logger.debug("hooks-session", `hookTool stdinParse: ${errorMessage(err)}`);
-            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) {
-            logger.debug("hooks-session", `hookTool toolLog: ${errorMessage(err)}`);
-        }
-        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) {
-            logger.debug("hooks-session", `hookTool cooldownStat: ${errorMessage(err)}`);
-        }
-        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) {
-                logger.debug("hooks-session", `hookTool sessionCapCheck: ${errorMessage(err)}`);
-            }
-        }
-        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) {
-                        logger.debug("hooks-session", `hookTool cooldownWrite: ${errorMessage(err)}`);
-                    }
-                    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) {
-                                logger.debug("hooks-session", `hookTool capFileRead: ${errorMessage(err)}`);
-                            }
-                            count += candidates.length;
-                            fs.writeFileSync(capFile, count.toString());
-                        }
-                        catch (err) {
-                            logger.debug("hooks-session", `hookTool capFileWrite: ${errorMessage(err)}`);
-                        }
-                    }
-                }
-            }
-            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;
-}
+export { buildHookContext, handleGuardSkip } from "./hooks-context.js";
+export { getGitContext } from "./session-git.js";
+// ── Session metrics ─────────────────────────────────────────────────────────
+export { trackSessionMetrics } from "./session-metrics.js";
+// ── Background scheduling ───────────────────────────────────────────────────
+export { resolveSubprocessArgs } from "./session-background.js";
+// ── Session start ───────────────────────────────────────────────────────────
+export { getUntrackedProjectNotice, getSessionStartOnboardingNotice, handleHookSessionStart, } from "./session-start.js";
+// ── Session stop + background sync ──────────────────────────────────────────
+export { extractConversationInsights, filterConversationInsightsForProactivity, handleHookStop, handleBackgroundSync, } from "./session-stop.js";
+// ── Tool + context hooks ────────────────────────────────────────────────────
+export { handleHookContext, handleHookTool, extractToolFindings, filterToolFindingsForProactivity, } from "./session-tool-hook.js";