@phren/cli 0.0.32 → 0.0.34

package/mcp/dist/cli/actions.js

@@ -290,6 +290,9 @@ export async function handleUpdate(args) {
     if (!result.ok) {
         process.exitCode = 1;
     }
+    else {
+        console.log("Run 'npx phren init' to refresh hooks and config.");
+    }
 }
 export async function handleReview(args) {
     const phrenPath = getPhrenPath();

package/mcp/dist/cli/config.js

@@ -8,7 +8,7 @@ import { PROACTIVITY_LEVELS, getProactivityLevel, getProactivityLevelForTask, ge
 import { PROJECT_OWNERSHIP_MODES, getProjectOwnershipDefault, parseProjectOwnershipMode, updateProjectConfigOverrides, } from "../project-config.js";
 import { isValidProjectName, learnedSynonymsPath, learnSynonym, loadLearnedSynonyms, removeLearnedSynonym, } from "../utils.js";
 // ── Shared helpers ────────────────────────────────────────────────────────────
-export function parseProjectArg(args) {
+function parseProjectArg(args) {
     const project = args.find((a) => a.startsWith("--project="))?.slice("--project=".length)
         ?? (args.indexOf("--project") !== -1 ? args[args.indexOf("--project") + 1] : undefined);
     const rest = args.filter((a, i) => a !== "--project" && !a.startsWith("--project=") && args[i - 1] !== "--project");
@@ -53,7 +53,7 @@ function formatConfigAsTable(label, rows) {
         console.log(`  ${k.padEnd(maxKey)}  ${v}`);
     }
 }
-export function handleConfigShow(args) {
+function handleConfigShow(args) {
     const phrenPath = getPhrenPath();
     const { project: projectArg } = parseProjectArg(args);
     if (projectArg) {
@@ -461,7 +461,7 @@ function handleConfigFindingSensitivity(args) {
 // ── LLM config ───────────────────────────────────────────────────────────────
 const EXPENSIVE_MODEL_RE = /opus|sonnet|gpt-4(?!o-mini)/i;
 const DEFAULT_LLM_MODEL = "gpt-4o-mini / claude-haiku-4-5-20251001";
-export function printSemanticCostNotice(model) {
+function printSemanticCostNotice(model) {
     const effectiveModel = model || process.env.PHREN_LLM_MODEL || DEFAULT_LLM_MODEL;
     console.log(`  Note: Each semantic check is ~80 input + ~5 output tokens (one call per 'maybe' pair, cached 24h).`);
     console.log(`  Current model: ${effectiveModel}`);

package/mcp/dist/cli/govern.js

@@ -228,10 +228,10 @@ export async function handleConsolidateMemories(args = []) {
         return;
     console.log(`Updated backups (${backups.length}): ${backups.join(", ")}`);
 }
-export async function handleGcMaintain(args = []) {
+async function handleGcMaintain(args = []) {
     const dryRun = args.includes("--dry-run");
     const phrenPath = getPhrenPath();
-    const { execSync } = await import("child_process");
+    const { execFileSync } = await import("child_process");
     const report = {
         gitGcRan: false,
         commitsSquashed: 0,
@@ -244,7 +244,7 @@ export async function handleGcMaintain(args = []) {
     }
     else {
         try {
-            execSync("git gc --aggressive --quiet", { cwd: phrenPath, stdio: "pipe" });
+            execFileSync("git", ["gc", "--aggressive", "--quiet"], { cwd: phrenPath, stdio: "pipe" });
             report.gitGcRan = true;
             console.log("git gc --aggressive: done");
         }
@@ -256,7 +256,10 @@ export async function handleGcMaintain(args = []) {
     const sevenDaysAgo = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 10);
     let oldCommits = [];
     try {
-        const raw = execSync(`git log --before="${sevenDaysAgo}" --format="%H %ci %s"`, { cwd: phrenPath, encoding: "utf8" }).trim();
+        const raw = execFileSync("git", ["log", `--before=${sevenDaysAgo}`, "--format=%H %ci %s"], {
+            cwd: phrenPath,
+            encoding: "utf8",
+        }).trim();
         if (raw) {
             oldCommits = raw.split("\n").filter((l) => l.includes("auto-save:") || l.includes("[auto]"));
         }
@@ -295,8 +298,11 @@ export async function handleGcMaintain(args = []) {
             try {
                 const oldest = hashes[hashes.length - 1];
                 const newest = hashes[0];
-                // Use git rebase --onto to squash: squash all into the oldest parent
-                const parentOfOldest = execSync(`git rev-parse ${oldest}^`, { cwd: phrenPath, encoding: "utf8" }).trim();
+                // Use git rev-parse to get the parent of the oldest commit
+                const parentOfOldest = execFileSync("git", ["rev-parse", `${oldest}^`], {
+                    cwd: phrenPath,
+                    encoding: "utf8",
+                }).trim();
                 // Build rebase script via env variable to squash all but first to "squash"
                 const rebaseScript = hashes
                     .map((h, i) => `${i === hashes.length - 1 ? "pick" : "squash"} ${h} auto-save`)
@@ -304,8 +310,12 @@ export async function handleGcMaintain(args = []) {
                     .join("\n");
                 const scriptPath = path.join(phrenPath, ".runtime", `gc-rebase-${weekKey}.sh`);
                 fs.writeFileSync(scriptPath, rebaseScript);
-                // Use GIT_SEQUENCE_EDITOR to feed our script
-                execSync(`GIT_SEQUENCE_EDITOR="cat ${scriptPath} >" git rebase -i ${parentOfOldest}`, { cwd: phrenPath, stdio: "pipe" });
+                // Use GIT_SEQUENCE_EDITOR env var to feed our script to git rebase
+                execFileSync("git", ["rebase", "-i", parentOfOldest], {
+                    cwd: phrenPath,
+                    stdio: "pipe",
+                    env: { ...process.env, GIT_SEQUENCE_EDITOR: `cat ${scriptPath} >` },
+                });
                 fs.unlinkSync(scriptPath);
                 report.commitsSquashed += hashes.length - 1;
                 console.log(`Squashed ${hashes.length} auto-save commits for week of ${weekKey} (${newest.slice(0, 7)}..${oldest.slice(0, 7)}).`);

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

@@ -39,7 +39,7 @@ export function handleGuardSkip(ctx, hookName, reason, healthUpdate) {
 }
 // Re-export frequently used functions so hook handlers can import from one place
 export { debugLog, appendAuditLog, getPhrenPath, readRootManifest, sessionMarker, runtimeFile, EXEC_TIMEOUT_MS, getProjectDirs, findProjectNameCaseInsensitive, homePath, } from "../shared.js";
-export { updateRuntimeHealth, getWorkflowPolicy, withFileLock, appendReviewQueue, recordFeedback, getQualityMultiplier, } from "../shared/governance.js";
+export { updateRuntimeHealth, buildSyncStatus, getWorkflowPolicy, withFileLock, appendReviewQueue, recordFeedback, getQualityMultiplier, } from "../shared/governance.js";
 export { detectProject } from "../shared/index.js";
 export { isProjectHookEnabled, readProjectConfig, getProjectSourcePath } from "../project-config.js";
 export { resolveRuntimeProfile } from "../runtime-profile.js";

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

@@ -1,4 +1,4 @@
-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 "./hooks-context.js";
+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";
@@ -6,16 +6,16 @@ import { readInstallPreferences } from "../init/preferences.js";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { execFileSync, spawn } from "child_process";
+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";
-function getRuntimeProfile() {
-    return resolveRuntimeProfile(getPhrenPath());
-}
-export { buildHookContext, checkHookGuard, handleGuardSkip } from "./hooks-context.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)
@@ -252,7 +252,7 @@ function scheduleBackgroundSync(phrenPathLocal) {
     try {
         if (fs.existsSync(lockPath)) {
             const ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
-            if (ageMs <= 10 * 60 * 1000)
+            if (ageMs <= SYNC_LOCK_STALE_MS)
                 return false;
             fs.unlinkSync(lockPath);
         }
@@ -265,16 +265,7 @@ function scheduleBackgroundSync(phrenPathLocal) {
         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(),
-            },
-        });
+        const child = spawnDetachedChild(spawnArgs, { phrenPath: phrenPathLocal, logFd });
         child.unref();
         fs.closeSync(logFd);
         return true;
@@ -297,7 +288,7 @@ function scheduleBackgroundMaintenance(phrenPathLocal, project) {
     if (fs.existsSync(markers.lock)) {
         try {
             const ageMs = Date.now() - fs.statSync(markers.lock).mtimeMs;
-            if (ageMs <= 2 * 60 * 60 * 1000)
+            if (ageMs <= MAINTENANCE_LOCK_STALE_MS)
                 return false;
             fs.unlinkSync(markers.lock);
         }
@@ -339,16 +330,7 @@ function scheduleBackgroundMaintenance(phrenPathLocal, project) {
         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(),
-            },
-        });
+        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 {
@@ -1019,12 +1001,7 @@ export async function handleBackgroundSync() {
             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,
-                },
+                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;
@@ -1033,12 +1010,7 @@ export async function handleBackgroundSync() {
         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,
-                },
+                lastSync: buildSyncStatus({ now, pushStatus: "saved-pushed", pushDetail: "commit pushed by background sync", unsyncedCommits: 0 }),
             });
             appendAuditLog(phrenPathLocal, "background_sync", "status=saved-pushed");
             return;
@@ -1047,34 +1019,18 @@ export async function handleBackgroundSync() {
         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,
-                },
+                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: 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,
-            },
+            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(recovered.detail || push.error || "background sync push failed")}`);
+        appendAuditLog(phrenPathLocal, "background_sync", `status=saved-local detail=${JSON.stringify(failDetail)}`);
     }
     finally {
         try {
@@ -1091,7 +1047,7 @@ function scheduleWeeklyGovernance() {
         if (daysSince >= 7) {
             const spawnArgs = resolveSubprocessArgs("background-maintenance");
             if (spawnArgs) {
-                const child = spawn(process.execPath, spawnArgs, { detached: true, stdio: "ignore" });
+                const child = spawnDetachedChild(spawnArgs, { phrenPath: getPhrenPath() });
                 child.unref();
                 fs.writeFileSync(lastGovPath, Date.now().toString());
                 debugLog("hook_stop: scheduled weekly governance run");

package/mcp/dist/cli/namespaces.js

@@ -667,7 +667,7 @@ export async function handleProjectsNamespace(args, profile) {
             console.error(`Project "${name}" not found.`);
             process.exit(1);
         }
-        const { readFindings, readTasks, resolveTaskFilePath, TASKS_FILENAME } = await import("../data/access.js");
+        const { readFindings, readTasks, resolveTaskFilePath } = await import("../data/access.js");
         const exported = { project: name, exportedAt: new Date().toISOString(), version: 1 };
         const summaryPath = path.join(projectDir, "summary.md");
         if (fs.existsSync(summaryPath))

package/mcp/dist/cli/search.js

@@ -1,7 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { runtimeFile } from "../shared.js";
-import { buildIndex, extractSnippet, queryDocRows, queryRows, queryEntityLinks, queryDocBySourceKey, logEntityMiss } from "../shared/index.js";
+import { buildIndex, extractSnippet, queryDocRows, queryRows, queryFragmentLinks, queryDocBySourceKey, logFragmentMiss } from "../shared/index.js";
 import { buildFtsQueryVariants, errorMessage, isValidProjectName } from "../utils.js";
 import { logger } from "../logger.js";
 import { keywordFallbackSearch } from "../core/search.js";
@@ -24,7 +24,7 @@ const SEARCH_TYPES = new Set([
 function historyFile(phrenPath) {
     return runtimeFile(phrenPath, "search-history.jsonl");
 }
-export function readSearchHistory(phrenPath) {
+function readSearchHistory(phrenPath) {
     const file = historyFile(phrenPath);
     if (!fs.existsSync(file))
         return [];
@@ -319,7 +319,7 @@ export async function runFragmentSearch(query, phrenPath, profile, opts) {
     }
     const rows = queryRows(db, sql, params);
     if (!rows || rows.length === 0) {
-        logEntityMiss(phrenPath, query, "cli_search_fragments", opts.project);
+        logFragmentMiss(phrenPath, query, "cli_search_fragments", opts.project);
         return { lines: [`No fragments matching "${query}".`], exitCode: 0 };
     }
     const lines = [`Fragments matching "${query}" (${rows.length} result(s)):\n`];
@@ -362,14 +362,14 @@ export async function runRelatedDocs(entity, phrenPath, profile, opts) {
     }
     const db = await buildIndex(phrenPath, profile);
     const max = opts.limit ?? 10;
-    const links = queryEntityLinks(db, entity.toLowerCase());
+    const links = queryFragmentLinks(db, entity.toLowerCase());
     let relatedDocs = links.related.filter(r => r.includes("/"));
     if (opts.project) {
         relatedDocs = relatedDocs.filter(d => d.startsWith(`${opts.project}/`));
     }
     relatedDocs = relatedDocs.slice(0, max);
     if (relatedDocs.length === 0) {
-        logEntityMiss(phrenPath, entity, "cli_related_docs", opts.project);
+        logFragmentMiss(phrenPath, entity, "cli_related_docs", opts.project);
         return { lines: [`No docs found referencing fragment "${entity}".`], exitCode: 0 };
     }
     const lines = [`Docs referencing "${entity}" (${relatedDocs.length} result(s)):\n`];

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

@@ -36,7 +36,10 @@ export async function handleHookContext() {
         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);
+            const bullets = content.split("\n")
+                .filter(l => l.startsWith("- "))
+                .filter(l => !(/<!--\s*superseded_by:/.test(l) || /<!--\s*(?:phren:)?retract/.test(l) || /status\s+"retracted"/.test(l) || /status\s+"superseded"/.test(l)))
+                .slice(0, 10);
             if (bullets.length > 0) {
                 parts.push("## Recent findings");
                 parts.push(bullets.join("\n"));
@@ -72,6 +75,7 @@ export async function handleHookContext() {
 // ── 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);
+const MAX_TOOL_COMMAND_LENGTH = 200;
 function flattenToolResponseText(value, maxChars = 4000) {
     if (typeof value === "string")
         return value;
@@ -144,7 +148,7 @@ export async function handleHookTool() {
         else if (toolName === "Bash") {
             const cmd = input.command ?? undefined;
             if (cmd)
-                entry.command = String(cmd).slice(0, 200);
+                entry.command = String(cmd).slice(0, MAX_TOOL_COMMAND_LENGTH);
         }
         else if (toolName === "Glob") {
             const pattern = input.pattern ?? undefined;
@@ -155,7 +159,7 @@ export async function handleHookTool() {
             const pattern = input.pattern ?? undefined;
             const searchPath = input.path ?? undefined;
             if (pattern)
-                entry.command = `grep ${pattern}${searchPath ? ` in ${searchPath}` : ""}`.slice(0, 200);
+                entry.command = `grep ${pattern}${searchPath ? ` in ${searchPath}` : ""}`.slice(0, MAX_TOOL_COMMAND_LENGTH);
         }
         const responseStr = flattenToolResponseText(data.tool_response ?? "");
         if (/(error|exception|failed|no such file|ENOENT)/i.test(responseStr)) {

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

@@ -2,18 +2,15 @@
  * SessionStart handler and onboarding helpers.
  * Extracted from cli-hooks-session.ts for modularity.
  */
-import { buildHookContext, handleGuardSkip, debugLog, sessionMarker, getPhrenPath, getProjectDirs, findProjectNameCaseInsensitive, updateRuntimeHealth, appendAuditLog, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, isFeatureEnabled, errorMessage, runDoctor, resolveRuntimeProfile, } from "./cli/hooks-context.js";
+import { buildHookContext, handleGuardSkip, debugLog, sessionMarker, getProjectDirs, findProjectNameCaseInsensitive, updateRuntimeHealth, appendAuditLog, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, isFeatureEnabled, errorMessage, runDoctor, resolveRuntimeProfile, } from "./cli/hooks-context.js";
 import { qualityMarkers, } from "./shared.js";
 import { readInstallPreferences } from "./init/preferences.js";
 import { logger } from "./logger.js";
 import * as fs from "fs";
 import * as path from "path";
-import { spawn } from "child_process";
+import { spawnDetachedChild } from "./shared/process.js";
 import { TASKS_FILENAME } from "./data/tasks.js";
 import { resolveSubprocessArgs as _resolveSubprocessArgs, runBestEffortGit, countUnsyncedCommits, } from "./cli-hooks-git.js";
-function getRuntimeProfile() {
-    return resolveRuntimeProfile(getPhrenPath());
-}
 const SESSION_START_ONBOARDING_MARKER = "session-start-onboarding-v1";
 const SYNC_WARN_MARKER = "sync-broken-warned-v1";
 function projectHasBootstrapSignals(phrenPath, project) {
@@ -156,16 +153,7 @@ function scheduleBackgroundMaintenance(phrenPathLocal, project) {
         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(),
-            },
-        });
+        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 {

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

@@ -2,16 +2,14 @@
  * Stop hook handler: git commit/push, background sync, auto-capture, governance.
  * Extracted from cli-hooks-session.ts for modularity.
  */
-import { buildHookContext, handleGuardSkip, debugLog, runtimeFile, sessionMarker, getPhrenPath, updateRuntimeHealth, appendAuditLog, withFileLock, getWorkflowPolicy, isProjectHookEnabled, ensureLocalGitRepo, getProactivityLevelForTask, getProactivityLevelForFindings, hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel, FINDING_SENSITIVITY_CONFIG, isFeatureEnabled, errorMessage, bootstrapPhrenDotEnv, finalizeTaskSession, appendFindingJournal, homePath, resolveRuntimeProfile, } from "./cli/hooks-context.js";
+import { buildHookContext, handleGuardSkip, debugLog, runtimeFile, sessionMarker, getPhrenPath, updateRuntimeHealth, buildSyncStatus, appendAuditLog, withFileLock, getWorkflowPolicy, isProjectHookEnabled, ensureLocalGitRepo, getProactivityLevelForTask, getProactivityLevelForFindings, hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel, FINDING_SENSITIVITY_CONFIG, isFeatureEnabled, errorMessage, bootstrapPhrenDotEnv, finalizeTaskSession, appendFindingJournal, homePath, } from "./cli/hooks-context.js";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { spawn } from "child_process";
+import { spawnDetachedChild } from "./shared/process.js";
 import { resolveSubprocessArgs as _resolveSubprocessArgs, runBestEffortGit, countUnsyncedCommits, recoverPushConflict, } from "./cli-hooks-git.js";
 import { logger } from "./logger.js";
-function getRuntimeProfile() {
-    return resolveRuntimeProfile(getPhrenPath());
-}
+const SYNC_LOCK_STALE_MS = 10 * 60 * 1000; // 10 minutes
 /** Read JSON from stdin if it's not a TTY. Returns null if stdin is a TTY or parsing fails. */
 export function readStdinJson() {
     if (process.stdin.isTTY)
@@ -112,7 +110,7 @@ function scheduleBackgroundSync(phrenPathLocal) {
     try {
         if (fs.existsSync(lockPath)) {
             const ageMs = Date.now() - fs.statSync(lockPath).mtimeMs;
-            if (ageMs <= 10 * 60 * 1000)
+            if (ageMs <= SYNC_LOCK_STALE_MS)
                 return false;
             fs.unlinkSync(lockPath);
         }
@@ -125,16 +123,7 @@ function scheduleBackgroundSync(phrenPathLocal) {
         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(),
-            },
-        });
+        const child = spawnDetachedChild(spawnArgs, { phrenPath: phrenPathLocal, logFd });
         child.unref();
         fs.closeSync(logFd);
         return true;
@@ -156,7 +145,7 @@ function scheduleWeeklyGovernance() {
         if (daysSince >= 7) {
             const spawnArgs = _resolveSubprocessArgs("background-maintenance");
             if (spawnArgs) {
-                const child = spawn(process.execPath, spawnArgs, { detached: true, stdio: "ignore" });
+                const child = spawnDetachedChild(spawnArgs, { phrenPath: getPhrenPath() });
                 child.unref();
                 fs.writeFileSync(lastGovPath, Date.now().toString());
                 debugLog("hook_stop: scheduled weekly governance run");
@@ -481,12 +470,7 @@ export async function handleBackgroundSync() {
             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,
-                },
+                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;
@@ -495,12 +479,7 @@ export async function handleBackgroundSync() {
         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,
-                },
+                lastSync: buildSyncStatus({ now, pushStatus: "saved-pushed", pushDetail: "commit pushed by background sync", unsyncedCommits: 0 }),
             });
             appendAuditLog(phrenPathLocal, "background_sync", "status=saved-pushed");
             return;
@@ -509,16 +488,7 @@ export async function handleBackgroundSync() {
         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,
-                },
+                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;
@@ -527,15 +497,7 @@ export async function handleBackgroundSync() {
         const failDetail = recovered.detail || push.error || "background sync push failed";
         updateRuntimeHealth(phrenPathLocal, {
             lastAutoSave: { at: now, status: "saved-local", detail: failDetail },
-            lastSync: {
-                lastPullAt: now,
-                lastPullStatus: recovered.pullStatus,
-                lastPullDetail: recovered.pullDetail,
-                lastPushAt: now,
-                lastPushStatus: "saved-local",
-                lastPushDetail: failDetail,
-                unsyncedCommits,
-            },
+            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)}`);
         // Append to sync-warnings.jsonl so health_check and session_start can surface recent failures

package/mcp/dist/content/archive.js

@@ -4,6 +4,7 @@ import * as crypto from "crypto";
 import { debugLog, runtimeFile, phrenOk, phrenErr, PhrenError, appendAuditLog, tryUnlink } from "../shared.js";
 import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
 import { withFileLock } from "../shared/governance.js";
+import { walkDirectory } from "../shared/data-utils.js";
 import { appendArchivedEntriesToTopicDoc, classifyTopicForText, readProjectTopics, topicReferencePath } from "../project-topics.js";
 import { isCitationLine, isArchiveStart, isArchiveEnd, stripComments } from "./metadata.js";
 import { logger } from "../logger.js";
@@ -81,28 +82,15 @@ function parseActiveEntries(content) {
 /** Build a Set of normalized bullet strings from all .md files in referenceDir. */
 function buildArchivedBulletSet(referenceDir) {
     const bulletSet = new Set();
-    if (!fs.existsSync(referenceDir))
-        return bulletSet;
     try {
-        const stack = [referenceDir];
-        while (stack.length > 0) {
-            const current = stack.pop();
-            for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-                const fullPath = path.join(current, entry.name);
-                if (entry.isDirectory()) {
-                    stack.push(fullPath);
+        for (const filePath of walkDirectory(referenceDir)) {
+            const content = fs.readFileSync(filePath, "utf8");
+            for (const line of content.split("\n")) {
+                if (!line.startsWith("- "))
                     continue;
-                }
-                if (!entry.isFile() || !entry.name.endsWith(".md"))
-                    continue;
-                const content = fs.readFileSync(fullPath, "utf8");
-                for (const line of content.split("\n")) {
-                    if (!line.startsWith("- "))
-                        continue;
-                    const normalizedLine = stripComments(line).replace(/^-\s+/, "").trim().toLowerCase();
-                    if (normalizedLine)
-                        bulletSet.add(normalizedLine);
-                }
+                const normalizedLine = stripComments(line).replace(/^-\s+/, "").trim().toLowerCase();
+                if (normalizedLine)
+                    bulletSet.add(normalizedLine);
             }
         }
     }