@phren/cli 0.1.40 → 0.1.42

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/dist/auth/profiles.js +59 -5
  2. package/dist/cli/actions.js +12 -16
  3. package/dist/cli/config-access.js +8 -1
  4. package/dist/cli/extract.d.ts +27 -1
  5. package/dist/cli/extract.js +244 -9
  6. package/dist/cli/govern.js +6 -87
  7. package/dist/cli/hooks-context.d.ts +1 -1
  8. package/dist/cli/hooks-context.js +1 -1
  9. package/dist/cli/namespaces-review.js +14 -1
  10. package/dist/cli/namespaces-utils.js +1 -1
  11. package/dist/cli/session-git.d.ts +18 -0
  12. package/dist/cli/session-git.js +47 -0
  13. package/dist/cli/session-start.js +2 -2
  14. package/dist/cli/session-stop.d.ts +11 -0
  15. package/dist/cli/session-stop.js +141 -33
  16. package/dist/cli/session-tool-hook.js +17 -5
  17. package/dist/cli-registry.d.ts +1 -1
  18. package/dist/cli-registry.js +1 -0
  19. package/dist/content/archive.js +3 -2
  20. package/dist/content/dedup.d.ts +1 -4
  21. package/dist/content/dedup.js +11 -66
  22. package/dist/content/learning.d.ts +20 -2
  23. package/dist/content/learning.js +26 -7
  24. package/dist/content/quality.d.ts +23 -0
  25. package/dist/content/quality.js +123 -0
  26. package/dist/content/secrets.d.ts +52 -0
  27. package/dist/content/secrets.js +196 -0
  28. package/dist/data/access.d.ts +56 -2
  29. package/dist/data/access.js +255 -32
  30. package/dist/data/tasks.js +46 -6
  31. package/dist/entrypoint.js +5 -1
  32. package/dist/finding/impact.js +170 -43
  33. package/dist/finding/lifecycle.d.ts +19 -2
  34. package/dist/finding/lifecycle.js +18 -5
  35. package/dist/git-worktree.d.ts +19 -0
  36. package/dist/git-worktree.js +117 -0
  37. package/dist/governance/policy.d.ts +84 -4
  38. package/dist/governance/policy.js +213 -17
  39. package/dist/governance/rbac.d.ts +8 -0
  40. package/dist/governance/rbac.js +26 -0
  41. package/dist/hooks.d.ts +20 -0
  42. package/dist/hooks.js +113 -3
  43. package/dist/index.js +5 -1
  44. package/dist/init/guard-globals.d.ts +20 -0
  45. package/dist/init/guard-globals.js +72 -6
  46. package/dist/init/init-configure.js +6 -6
  47. package/dist/init/init.js +10 -6
  48. package/dist/init/setup.d.ts +4 -3
  49. package/dist/init/setup.js +120 -16
  50. package/dist/init/store-gitignore.d.ts +29 -0
  51. package/dist/init/store-gitignore.js +48 -0
  52. package/dist/link/doctor.js +86 -20
  53. package/dist/phren-core.d.ts +35 -8
  54. package/dist/phren-core.js +35 -8
  55. package/dist/phren-paths.d.ts +90 -1
  56. package/dist/phren-paths.js +150 -5
  57. package/dist/proactivity.js +1 -1
  58. package/dist/project-config.js +3 -2
  59. package/dist/project-topics.js +13 -12
  60. package/dist/shared/data-utils.js +13 -3
  61. package/dist/shared/embedding-cache.d.ts +16 -0
  62. package/dist/shared/embedding-cache.js +24 -0
  63. package/dist/shared/fragment-graph.js +10 -0
  64. package/dist/shared/index.d.ts +6 -0
  65. package/dist/shared/index.js +523 -138
  66. package/dist/shared/ollama.d.ts +14 -2
  67. package/dist/shared/ollama.js +84 -5
  68. package/dist/shared/retrieval.d.ts +22 -1
  69. package/dist/shared/retrieval.js +30 -1
  70. package/dist/shared/search-fallback.js +15 -3
  71. package/dist/shared/vector-index.d.ts +20 -1
  72. package/dist/shared/vector-index.js +18 -4
  73. package/dist/shared.d.ts +1 -1
  74. package/dist/shared.js +1 -1
  75. package/dist/status.js +18 -1
  76. package/dist/store-registry.d.ts +22 -0
  77. package/dist/store-registry.js +36 -3
  78. package/dist/store-routing.d.ts +8 -0
  79. package/dist/store-routing.js +23 -1
  80. package/dist/task/lifecycle.js +31 -0
  81. package/dist/tools/config.js +19 -9
  82. package/dist/tools/data.js +1 -1
  83. package/dist/tools/extract-facts.js +3 -2
  84. package/dist/tools/extract.js +2 -2
  85. package/dist/tools/finding.js +20 -8
  86. package/dist/tools/graph.js +9 -1
  87. package/dist/tools/memory.js +1 -1
  88. package/dist/tools/notes.js +3 -3
  89. package/dist/tools/ops.js +19 -18
  90. package/dist/tools/search.js +2 -2
  91. package/dist/tools/session.js +2 -2
  92. package/dist/tools/tasks.js +2 -2
  93. package/dist/tools/types.d.ts +32 -2
  94. package/dist/tools/types.js +41 -8
  95. package/dist/ui/scripts.js +2 -2
  96. package/dist/ui/server.js +7 -6
  97. package/dist/utils-fts.js +3 -2
  98. package/dist/utils-paths.d.ts +1 -0
  99. package/dist/utils-paths.js +1 -1
  100. package/dist/utils.d.ts +1 -1
  101. package/dist/utils.js +1 -1
  102. package/package.json +1 -1
  103. package/dist/cli-hooks-git.d.ts +0 -50
  104. package/dist/cli-hooks-git.js +0 -288
  105. package/starter/my-api/.claude/skills/README.md +0 -7
  106. package/starter/my-api/CLAUDE.md +0 -33
  107. package/starter/my-api/FINDINGS.md +0 -9
  108. package/starter/my-api/summary.md +0 -7
  109. package/starter/my-api/tasks.md +0 -7
  110. package/starter/my-first-project/.claude/skills/README.md +0 -7
  111. package/starter/my-first-project/CLAUDE.md +0 -49
  112. package/starter/my-first-project/FINDINGS.md +0 -24
  113. package/starter/my-first-project/summary.md +0 -11
  114. package/starter/my-first-project/tasks.md +0 -25
  115. package/starter/my-frontend/.claude/skills/README.md +0 -7
  116. package/starter/my-frontend/CLAUDE.md +0 -33
  117. package/starter/my-frontend/FINDINGS.md +0 -9
  118. package/starter/my-frontend/summary.md +0 -7
  119. package/starter/my-frontend/tasks.md +0 -7
@@ -36,7 +36,20 @@ export async function handleReviewNamespace(args) {
36
36
  console.error(`Failed to ${action} item: ${result.error ?? "Unknown error"}`);
37
37
  process.exit(1);
38
38
  }
39
- console.log(`${action === "approve" ? "✓ Approved" : "✗ Rejected"}: ${lineText.slice(0, 100)}${lineText.length > 100 ? "..." : ""}`);
39
+ // Print the data layer's own message rather than a generic one. approve
40
+ // and reject each have several distinct outcomes — promoted, already
41
+ // present, already archived, removed from the archive, discarded — and
42
+ // collapsing them into "Approved" hides the difference that matters most:
43
+ // on a store whose findings have aged into reference/topics/, most
44
+ // approvals dequeue without promoting anything.
45
+ const summary = lineText.slice(0, 100) + (lineText.length > 100 ? "..." : "");
46
+ const mark = action === "approve" ? "✓" : "✗";
47
+ const payload = result.data;
48
+ const detail = typeof payload === "string"
49
+ ? payload
50
+ : payload?.message;
51
+ console.log(`${mark} ${detail ?? (action === "approve" ? "Approved" : "Rejected")}`);
52
+ console.log(` ${summary}`);
40
53
  return;
41
54
  }
42
55
  // Default: show review queue (first arg is project name if not a subcommand)
@@ -3,9 +3,9 @@ import * as path from "path";
3
3
  import { execFileSync } from "child_process";
4
4
  import { errorMessage } from "../utils.js";
5
5
  import { logger } from "../logger.js";
6
+ import { getNonPrimaryStores } from "../store-registry.js";
6
7
  export function resolveProjectStorePath(phrenPath, project) {
7
8
  try {
8
- const { getNonPrimaryStores } = require("../store-registry.js");
9
9
  if (fs.existsSync(path.join(phrenPath, project)))
10
10
  return phrenPath;
11
11
  for (const store of getNonPrimaryStores(phrenPath)) {
@@ -8,6 +8,24 @@ export declare function runBestEffortGit(args: string[], cwd: string): Promise<{
8
8
  output?: string;
9
9
  error?: string;
10
10
  }>;
11
+ /**
12
+ * True when local HEAD and the tracking branch share no common ancestor.
13
+ *
14
+ * This is what happens when a store's remote is re-initialized: every
15
+ * `pull --rebase` fails, the rebase is aborted, and the next commit re-enters
16
+ * the same loop forever. A generic "pull failed" sends the user chasing
17
+ * network problems, so it is worth naming — no retry will ever fix it.
18
+ *
19
+ * Returns false when there is no upstream, or when git cannot answer; callers
20
+ * treat that as "some other failure" and report the raw error instead.
21
+ */
22
+ export declare function hasUnrelatedHistories(cwd: string): Promise<boolean>;
23
+ /**
24
+ * Files phren is allowed to auto-stage in a team store. Anything not in this
25
+ * list (notably `.runtime/`, secrets, build output) is skipped on session-stop
26
+ * and `push_changes`.
27
+ */
28
+ export declare const TEAM_STORE_PATHSPECS: readonly ["*/journal/*", "*/tasks.md", "*/truths.md", "*/FINDINGS.md", "*/FINDINGS.md.bak", "*/summary.md", "*/review.md", "*/CLAUDE.md", "*/topic-config.json", "*/phren.project.yaml", "*/reference/**", "*/skills/**", "*/notes/**", ".phren-team.yaml"];
11
29
  export declare function countUnsyncedCommits(cwd: string): Promise<number>;
12
30
  export declare function recoverPushConflict(cwd: string): Promise<{
13
31
  ok: boolean;
@@ -64,6 +64,53 @@ export async function runBestEffortGit(args, cwd) {
64
64
  }
65
65
  return { ok: false, error: "git command failed" };
66
66
  }
67
+ /**
68
+ * True when local HEAD and the tracking branch share no common ancestor.
69
+ *
70
+ * This is what happens when a store's remote is re-initialized: every
71
+ * `pull --rebase` fails, the rebase is aborted, and the next commit re-enters
72
+ * the same loop forever. A generic "pull failed" sends the user chasing
73
+ * network problems, so it is worth naming — no retry will ever fix it.
74
+ *
75
+ * Returns false when there is no upstream, or when git cannot answer; callers
76
+ * treat that as "some other failure" and report the raw error instead.
77
+ */
78
+ export async function hasUnrelatedHistories(cwd) {
79
+ const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
80
+ if (!upstream.ok || !upstream.output)
81
+ return false;
82
+ // Make sure we are comparing against what the remote actually has now.
83
+ await runBestEffortGit(["fetch", "--quiet"], cwd);
84
+ const localHead = await runBestEffortGit(["rev-parse", "HEAD"], cwd);
85
+ const remoteHead = await runBestEffortGit(["rev-parse", upstream.output.trim()], cwd);
86
+ if (!localHead.ok || !remoteHead.ok || !localHead.output || !remoteHead.output)
87
+ return false;
88
+ // `merge-base` exits non-zero with no output when the two commits are
89
+ // unrelated, which is exactly the signal we want.
90
+ const mergeBase = await runBestEffortGit(["merge-base", localHead.output.trim(), remoteHead.output.trim()], cwd);
91
+ return !mergeBase.ok || !mergeBase.output?.trim();
92
+ }
93
+ /**
94
+ * Files phren is allowed to auto-stage in a team store. Anything not in this
95
+ * list (notably `.runtime/`, secrets, build output) is skipped on session-stop
96
+ * and `push_changes`.
97
+ */
98
+ export const TEAM_STORE_PATHSPECS = [
99
+ "*/journal/*",
100
+ "*/tasks.md",
101
+ "*/truths.md",
102
+ "*/FINDINGS.md",
103
+ "*/FINDINGS.md.bak",
104
+ "*/summary.md",
105
+ "*/review.md",
106
+ "*/CLAUDE.md",
107
+ "*/topic-config.json",
108
+ "*/phren.project.yaml",
109
+ "*/reference/**",
110
+ "*/skills/**",
111
+ "*/notes/**",
112
+ ".phren-team.yaml",
113
+ ];
67
114
  export async function countUnsyncedCommits(cwd) {
68
115
  const upstream = await runBestEffortGit(["rev-parse", "--abbrev-ref", "@{upstream}"], cwd);
69
116
  if (!upstream.ok || !upstream.output) {
@@ -5,7 +5,7 @@
5
5
  import * as fs from "fs";
6
6
  import * as path from "path";
7
7
  import * as crypto from "crypto";
8
- import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, getProjectDirs, findProjectNameCaseInsensitive, updateRuntimeHealth, withFileLock, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, errorMessage, resolveRuntimeProfile, } from "./hooks-context.js";
8
+ import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, getProjectDirs, findProjectNameCaseInsensitive, projectSlugFromPath, updateRuntimeHealth, withFileLock, detectProject, isProjectHookEnabled, readProjectConfig, getProjectSourcePath, detectProjectDir, ensureLocalGitRepo, isProjectTracked, repairPreexistingInstall, errorMessage, resolveRuntimeProfile, } from "./hooks-context.js";
9
9
  import { TASKS_FILENAME } from "../data/tasks.js";
10
10
  import { FINDINGS_FILENAME } from "../data/access.js";
11
11
  import { readInstallPreferences } from "../init/preferences.js";
@@ -44,7 +44,7 @@ export function getUntrackedProjectNotice(phrenPath, cwd) {
44
44
  return null;
45
45
  if (detectProject(phrenPath, projectDir, activeProfile))
46
46
  return null;
47
- const projectName = path.basename(projectDir).toLowerCase().replace(/[^a-z0-9_-]/g, "-");
47
+ const projectName = projectSlugFromPath(projectDir);
48
48
  if (isProjectTracked(phrenPath, projectName, activeProfile)) {
49
49
  const trackedName = getProjectDirs(phrenPath, activeProfile)
50
50
  .map((dir) => path.basename(dir))
@@ -1,8 +1,19 @@
1
+ import { type PushStatus, type SyncStatus } from "../shared/governance.js";
1
2
  /**
2
3
  * Extract potential insights from conversation text using keyword heuristics.
3
4
  * Returns lines that contain insight-signal words and look like actionable knowledge.
4
5
  */
5
6
  export declare function extractConversationInsights(text: string): string[];
6
7
  export declare function filterConversationInsightsForProactivity(insights: string[], level?: "high" | "medium" | "low"): string[];
8
+ /**
9
+ * Build the `lastSync` patch for a sync attempt, carrying the failure streak
10
+ * forward. Success resets the counter and stamps `lastSuccessfulPushAt`;
11
+ * failure increments it. Without this the runtime health file only ever showed
12
+ * the most recent attempt, so "failed once" and "failed for two months" looked
13
+ * identical.
14
+ */
15
+ export declare function nextSyncStatus(previous: SyncStatus | undefined, patch: Omit<SyncStatus, "consecutiveFailures" | "lastSuccessfulPushAt"> & {
16
+ lastPushStatus: PushStatus;
17
+ }, now: string): SyncStatus;
7
18
  export declare function handleHookStop(): Promise<void>;
8
19
  export declare function handleBackgroundSync(): Promise<void>;
@@ -5,9 +5,10 @@
5
5
  import * as fs from "fs";
6
6
  import * as path from "path";
7
7
  import * as os from "os";
8
- import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, getPhrenPath, updateRuntimeHealth, withFileLock, getWorkflowPolicy, getProactivityLevelForTask, getProactivityLevelForFindings, hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel, FINDING_SENSITIVITY_CONFIG, isFeatureEnabled, errorMessage, homePath, isProjectHookEnabled, ensureLocalGitRepo, bootstrapPhrenDotEnv, finalizeTaskSession, appendFindingJournal, buildSyncStatus, } from "./hooks-context.js";
8
+ import { buildHookContext, handleGuardSkip, debugLog, appendAuditLog, runtimeFile, sessionMarker, getPhrenPath, updateRuntimeHealth, withFileLock, getWorkflowPolicy, getProactivityLevelForTask, getProactivityLevelForFindings, hasExplicitFindingSignal, shouldAutoCaptureFindingsForLevel, FINDING_SENSITIVITY_CONFIG, isFeatureEnabled, errorMessage, homePath, isProjectHookEnabled, ensureLocalGitRepo, bootstrapPhrenDotEnv, finalizeTaskSession, appendFindingJournal, } from "./hooks-context.js";
9
9
  import { logger } from "../logger.js";
10
- import { runBestEffortGit, countUnsyncedCommits, recoverPushConflict, } from "./session-git.js";
10
+ import { runBestEffortGit, countUnsyncedCommits, recoverPushConflict, hasUnrelatedHistories, } from "./session-git.js";
11
+ import { assessSyncOutage, getRuntimeHealth, } from "../shared/governance.js";
11
12
  import { resolveSubprocessArgs, scheduleBackgroundSync, } from "./session-background.js";
12
13
  import { spawnDetachedChild } from "../shared/process.js";
13
14
  import { resolveManagementCapabilities } from "../init/management-preset.js";
@@ -85,6 +86,75 @@ export function filterConversationInsightsForProactivity(insights, level = getPr
85
86
  return insights;
86
87
  return insights.filter((insight) => shouldAutoCaptureFindingsForLevel(level, insight));
87
88
  }
89
+ // ── Sync failure accounting ─────────────────────────────────────────────────
90
+ const SYNC_WARN_MARKER = "sync-outage-warned-v1";
91
+ /** Re-warn at most once a day, so a broken store nags without spamming. */
92
+ const SYNC_WARN_INTERVAL_MS = 86_400_000;
93
+ /**
94
+ * Build the `lastSync` patch for a sync attempt, carrying the failure streak
95
+ * forward. Success resets the counter and stamps `lastSuccessfulPushAt`;
96
+ * failure increments it. Without this the runtime health file only ever showed
97
+ * the most recent attempt, so "failed once" and "failed for two months" looked
98
+ * identical.
99
+ */
100
+ export function nextSyncStatus(previous, patch, now) {
101
+ const failed = ["pull-failed", "push-failed", "unrelated-histories", "error"].includes(patch.lastPushStatus);
102
+ if (failed) {
103
+ return {
104
+ ...patch,
105
+ consecutiveFailures: (previous?.consecutiveFailures ?? 0) + 1,
106
+ ...(previous?.lastSuccessfulPushAt ? { lastSuccessfulPushAt: previous.lastSuccessfulPushAt } : {}),
107
+ };
108
+ }
109
+ const reachedRemote = patch.lastPushStatus === "saved-pushed";
110
+ return {
111
+ ...patch,
112
+ consecutiveFailures: 0,
113
+ ...(reachedRemote
114
+ ? { lastSuccessfulPushAt: now }
115
+ : previous?.lastSuccessfulPushAt
116
+ ? { lastSuccessfulPushAt: previous.lastSuccessfulPushAt }
117
+ : {}),
118
+ };
119
+ }
120
+ /**
121
+ * Tell the user, on stdout, that their store has stopped syncing. The Stop hook
122
+ * is the only place that runs on every turn, so silence here is what let a
123
+ * two-month outage go unnoticed. Rate-limited via a marker file.
124
+ */
125
+ function warnIfSyncDegraded(phrenPath) {
126
+ try {
127
+ const assessment = assessSyncOutage(getRuntimeHealth(phrenPath).lastSync);
128
+ if (!assessment.degraded)
129
+ return;
130
+ const markerPath = sessionMarker(phrenPath, SYNC_WARN_MARKER);
131
+ try {
132
+ const lastWarned = Date.parse(fs.readFileSync(markerPath, "utf8").trim());
133
+ if (!Number.isNaN(lastWarned) && Date.now() - lastWarned < SYNC_WARN_INTERVAL_MS)
134
+ return;
135
+ }
136
+ catch {
137
+ // No marker yet (or unreadable) — warn.
138
+ }
139
+ process.stdout.write([
140
+ "<phren-notice>",
141
+ assessment.summary,
142
+ `Your findings and tasks are safe on disk in ${phrenPath}, but they are not reaching the remote.`,
143
+ `Diagnose with: phren status (then: cd ${phrenPath} && git pull --rebase)`,
144
+ "<phren-notice>",
145
+ "",
146
+ ].join("\n"));
147
+ try {
148
+ fs.writeFileSync(markerPath, `${new Date().toISOString()}\n`);
149
+ }
150
+ catch (err) {
151
+ debugLog(`sync-outage marker write failed: ${errorMessage(err)}`);
152
+ }
153
+ }
154
+ catch (err) {
155
+ debugLog(`sync-outage check failed: ${errorMessage(err)}`);
156
+ }
157
+ }
88
158
  // ── Session cap helper ──────────────────────────────────────────────────────
89
159
  function getSessionCap() {
90
160
  if (process.env.PHREN_AUTOCAPTURE_SESSION_CAP) {
@@ -282,17 +352,24 @@ export async function handleHookStop() {
282
352
  return;
283
353
  }
284
354
  if (!status.output) {
355
+ // A clean working tree says nothing about whether the store is in sync.
356
+ // Reporting "saved-pushed / no changes" here was the core lie: it
357
+ // overwrote a real `pull-failed` from the previous run every single turn,
358
+ // so the failure never accumulated and the user never saw it.
359
+ const previousSync = getRuntimeHealth(phrenPath).lastSync;
360
+ const pending = await countUnsyncedCommits(phrenPath);
361
+ const inSync = pending === 0;
362
+ const detail = inSync ? "no changes" : `no changes; ${pending} commit(s) still unpushed`;
285
363
  updateRuntimeHealth(phrenPath, {
286
364
  lastStopAt: now,
287
- lastAutoSave: { at: now, status: "clean", detail: "no changes" },
288
- lastSync: {
289
- lastPushAt: now,
290
- lastPushStatus: "saved-pushed",
291
- lastPushDetail: "no changes",
292
- unsyncedCommits: 0,
293
- },
365
+ lastAutoSave: { at: now, status: inSync ? "clean" : "sync-failed", detail },
366
+ lastSync: inSync
367
+ ? { ...previousSync, lastPushAt: now, lastPushDetail: detail, unsyncedCommits: 0 }
368
+ : { ...previousSync, lastPushAt: now, lastPushDetail: detail, unsyncedCommits: pending },
294
369
  });
295
- appendAuditLog(phrenPath, "hook_stop", "status=clean");
370
+ appendAuditLog(phrenPath, "hook_stop", `status=${inSync ? "clean" : "clean-unsynced"} pending=${pending}`);
371
+ if (!inSync)
372
+ warnIfSyncDegraded(phrenPath);
296
373
  return;
297
374
  }
298
375
  // Stage all changes first, then unstage any sensitive files that slipped
@@ -302,7 +379,11 @@ export async function handleHookStop() {
302
379
  if (add.ok) {
303
380
  // Belt-and-suspenders: unstage sensitive files that .gitignore should
304
381
  // already block. Failures here are non-fatal (files may not exist).
305
- await runBestEffortGit(["reset", "HEAD", "--", ".env", "**/.env", "*.pem", "*.key"], phrenPath);
382
+ // .config/auth-profiles.json is the legacy path for auth/profiles.ts's
383
+ // credential store (API keys, OpenAI Codex OAuth tokens) — it now lives
384
+ // in .runtime/ (never staged by `-A`, since that directory is
385
+ // gitignored), but this still protects a store from before that move.
386
+ await runBestEffortGit(["reset", "HEAD", "--", ".env", "**/.env", "*.pem", "*.key", ".config/auth-profiles.json"], phrenPath);
306
387
  }
307
388
  let commitMsg = "auto-save phren";
308
389
  if (add.ok) {
@@ -398,17 +479,22 @@ export async function handleHookStop() {
398
479
  status: "saved-local",
399
480
  detail: syncDetail,
400
481
  });
482
+ // The push has been handed to the background sync and has not happened yet,
483
+ // so only the push *detail* is updated here — the status, failure streak and
484
+ // last-success timestamp are left for whoever actually talks to the remote.
485
+ const priorSync = getRuntimeHealth(phrenPath).lastSync;
401
486
  updateRuntimeHealth(phrenPath, {
402
487
  lastStopAt: now,
403
488
  lastAutoSave: { at: now, status: "saved-local", detail: syncDetail },
404
489
  lastSync: {
490
+ ...priorSync,
405
491
  lastPushAt: now,
406
- lastPushStatus: "saved-local",
407
492
  lastPushDetail: syncDetail,
408
493
  unsyncedCommits,
409
494
  },
410
495
  });
411
496
  appendAuditLog(phrenPath, "hook_stop", `status=saved-local detail=${JSON.stringify(syncDetail)}`);
497
+ warnIfSyncDegraded(phrenPath);
412
498
  }); // end withFileLock(gitOpLockPath)
413
499
  // Auto governance scheduling (non-blocking)
414
500
  scheduleWeeklyGovernance();
@@ -419,41 +505,63 @@ export async function handleBackgroundSync() {
419
505
  const now = new Date().toISOString();
420
506
  const lockPath = runtimeFile(phrenPathLocal, "background-sync.lock");
421
507
  try {
508
+ const previousSync = getRuntimeHealth(phrenPathLocal).lastSync;
509
+ const record = (autoSaveStatus, patch, detail) => {
510
+ updateRuntimeHealth(phrenPathLocal, {
511
+ lastAutoSave: { at: now, status: autoSaveStatus, detail },
512
+ lastSync: nextSyncStatus(previousSync, patch, now),
513
+ });
514
+ appendAuditLog(phrenPathLocal, "background_sync", `status=${patch.lastPushStatus} detail=${JSON.stringify(detail)}`);
515
+ };
422
516
  const remotes = await runBestEffortGit(["remote"], phrenPathLocal);
423
517
  if (!remotes.ok || !remotes.output) {
424
518
  const unsyncedCommits = await countUnsyncedCommits(phrenPathLocal);
425
- updateRuntimeHealth(phrenPathLocal, {
426
- lastAutoSave: { at: now, status: "saved-local", detail: "background sync skipped; no remote configured" },
427
- lastSync: buildSyncStatus({ now, pushStatus: "saved-local", pushDetail: "background sync skipped; no remote configured", unsyncedCommits }),
428
- });
429
- appendAuditLog(phrenPathLocal, "background_sync", "status=saved-local detail=no_remote");
519
+ const detail = "background sync skipped; no remote configured";
520
+ record("saved-local", { lastPushAt: now, lastPushStatus: "saved-local", lastPushDetail: detail, unsyncedCommits }, detail);
430
521
  return;
431
522
  }
432
523
  const push = await runBestEffortGit(["push"], phrenPathLocal);
433
524
  if (push.ok) {
434
- updateRuntimeHealth(phrenPathLocal, {
435
- lastAutoSave: { at: now, status: "saved-pushed", detail: "commit pushed by background sync" },
436
- lastSync: buildSyncStatus({ now, pushStatus: "saved-pushed", pushDetail: "commit pushed by background sync", unsyncedCommits: 0 }),
437
- });
438
- appendAuditLog(phrenPathLocal, "background_sync", "status=saved-pushed");
525
+ const detail = "commit pushed by background sync";
526
+ record("saved-pushed", { lastPushAt: now, lastPushStatus: "saved-pushed", lastPushDetail: detail, unsyncedCommits: 0 }, detail);
439
527
  return;
440
528
  }
441
529
  const recovered = await recoverPushConflict(phrenPathLocal);
442
530
  if (recovered.ok) {
443
- updateRuntimeHealth(phrenPathLocal, {
444
- lastAutoSave: { at: now, status: "saved-pushed", detail: recovered.detail },
445
- lastSync: buildSyncStatus({ now, pushStatus: "saved-pushed", pushDetail: recovered.detail, pullAt: now, pullStatus: recovered.pullStatus, pullDetail: recovered.pullDetail, successfulPullAt: now, unsyncedCommits: 0 }),
446
- });
447
- appendAuditLog(phrenPathLocal, "background_sync", `status=saved-pushed detail=${JSON.stringify(recovered.detail)}`);
531
+ record("saved-pushed", {
532
+ lastPushAt: now,
533
+ lastPushStatus: "saved-pushed",
534
+ lastPushDetail: recovered.detail,
535
+ lastPullAt: now,
536
+ lastPullStatus: recovered.pullStatus,
537
+ lastPullDetail: recovered.pullDetail,
538
+ lastSuccessfulPullAt: now,
539
+ unsyncedCommits: 0,
540
+ }, recovered.detail);
448
541
  return;
449
542
  }
543
+ // The push leg genuinely failed. Report *which* leg failed instead of the
544
+ // old success-shaped "saved-local", and name the unrelated-histories case
545
+ // specifically — no retry will ever clear it, so a generic "pull failed"
546
+ // would send the user chasing the wrong problem.
450
547
  const unsyncedCommits = await countUnsyncedCommits(phrenPathLocal);
451
- const failDetail = recovered.detail || push.error || "background sync push failed";
452
- updateRuntimeHealth(phrenPathLocal, {
453
- lastAutoSave: { at: now, status: "saved-local", detail: failDetail },
454
- lastSync: buildSyncStatus({ now, pushStatus: "saved-local", pushDetail: failDetail, pullAt: now, pullStatus: recovered.pullStatus, pullDetail: recovered.pullDetail, unsyncedCommits }),
455
- });
456
- appendAuditLog(phrenPathLocal, "background_sync", `status=saved-local detail=${JSON.stringify(failDetail)}`);
548
+ const unrelated = recovered.pullStatus === "error" && await hasUnrelatedHistories(phrenPathLocal);
549
+ const pushStatus = unrelated
550
+ ? "unrelated-histories"
551
+ : recovered.pullStatus === "error" ? "pull-failed" : "push-failed";
552
+ const failDetail = unrelated
553
+ ? `local and remote histories are unrelated (no merge base) — the remote was most likely re-initialized. ` +
554
+ `Reconcile manually: cd ${phrenPathLocal} && git fetch && git log --oneline origin/HEAD`
555
+ : (recovered.detail || push.error || "background sync push failed");
556
+ record("sync-failed", {
557
+ lastPushAt: now,
558
+ lastPushStatus: pushStatus,
559
+ lastPushDetail: failDetail,
560
+ lastPullAt: now,
561
+ lastPullStatus: recovered.pullStatus,
562
+ lastPullDetail: recovered.pullDetail,
563
+ unsyncedCommits,
564
+ }, failDetail);
457
565
  }
458
566
  finally {
459
567
  try {
@@ -6,6 +6,7 @@ import * as fs from "fs";
6
6
  import * as path from "path";
7
7
  import { buildHookContext, debugLog, appendAuditLog, runtimeFile, sessionMarker, getPhrenPath, getWorkflowPolicy, appendReviewQueue, getProactivityLevelForFindings, FINDING_SENSITIVITY_CONFIG, isProjectHookEnabled, errorMessage, detectProject, } from "./hooks-context.js";
8
8
  import { logger } from "../logger.js";
9
+ import { findingQualityReason } from "../content/quality.js";
9
10
  import { rotateJsonlIfLarge } from "../phren-paths.js";
10
11
  import { buildIndex, queryRows, } from "../shared/index.js";
11
12
  import { filterTaskByPriority } from "../shared/retrieval.js";
@@ -210,10 +211,12 @@ export async function handleHookTool() {
210
211
  }
211
212
  }
212
213
  // Negative lookahead `(?!\(|\[)` rejects markdown link/reference patterns:
213
- // [Architecture](#architecture) ← TOC anchor, content was being captured as "(#architecture)"
214
- // [bug][1] ← markdown reference link, content was being captured as "[1]"
215
- // produced garbage review-queue entries like "[architecture] (#architecture)".
216
- const EXPLICIT_TAG_PATTERN = /\[(pitfall|decision|pattern|tradeoff|architecture|bug)\](?!\(|\[)\s*(.+)/i;
214
+ // [Pattern](#pattern) ← TOC anchor, content was being captured as "(#pattern)"
215
+ // [bug][1] ← markdown reference link, content was being captured as "[1]"
216
+ // produced garbage review-queue entries like "[pattern] (#pattern)".
217
+ // Tag list mirrors FINDING_TAGS (phren-core.ts): everything phren can write,
218
+ // offered or auto-detected, not just the smaller offered FINDING_TYPES set.
219
+ const EXPLICIT_TAG_PATTERN = /\[(pitfall|decision|pattern|bug|workaround|context)\](?!\(|\[)\s*(.+)/i;
217
220
  export function filterToolFindingsForProactivity(candidates, level = getProactivityLevelForFindings(getPhrenPath())) {
218
221
  if (level === "high")
219
222
  return candidates;
@@ -304,7 +307,16 @@ export function extractToolFindings(toolName, input, responseStr, toolResponse)
304
307
  }
305
308
  }
306
309
  }
307
- return candidates;
310
+ // Single quality gate for everything this hook scrapes. Explicit [tag] matches are not
311
+ // exempt: the tag scraper happily matched phren's own prompt text and code fragments
312
+ // like `[pattern] ");` and queued them for review.
313
+ return candidates.filter((candidate) => {
314
+ const reason = findingQualityReason(candidate.text);
315
+ if (!reason)
316
+ return true;
317
+ debugLog(`extractToolFindings: rejected (${reason}): ${candidate.text.slice(0, 80)}`);
318
+ return false;
319
+ });
308
320
  }
309
321
  // ── Context hook handler ────────────────────────────────────────────────────
310
322
  function readStdinJson() {
@@ -35,7 +35,7 @@ export interface Command {
35
35
  hidden?: boolean;
36
36
  run: RunFn;
37
37
  }
38
- export declare const ENV_HELP = "Environment variables:\n PHREN_PATH Override phren directory (default: ~/.phren)\n PHREN_PROFILE Active profile name\n PHREN_DEBUG Enable debug logging (set to 1)\n\n Embeddings:\n PHREN_OLLAMA_URL Ollama base URL (default: http://localhost:11434, 'off' to disable)\n PHREN_EMBEDDING_API_URL OpenAI-compatible /embeddings endpoint\n PHREN_EMBEDDING_API_KEY API key for embedding endpoint\n PHREN_EMBEDDING_MODEL Embedding model (default: nomic-embed-text)\n\n Context injection:\n PHREN_CONTEXT_TOKEN_BUDGET Max tokens injected per prompt (default: 550)\n PHREN_MAX_INJECT_TOKENS Hard cap on total injected tokens (default: 2000)\n PHREN_HOOK_TIMEOUT_MS Hook subprocess timeout in ms (default: 14000)\n\n Feature flags:\n PHREN_FEATURE_AUTO_EXTRACT=0 Disable auto memory extraction\n PHREN_FEATURE_AUTO_CAPTURE=1 Extract insights from conversations\n PHREN_FEATURE_SEMANTIC_DEDUP=1 LLM-based dedup on add_finding\n PHREN_FEATURE_HYBRID_SEARCH=0 Disable TF-IDF cosine fallback\n\n Run 'phren help all' to see everything.\n";
38
+ export declare const ENV_HELP = "Environment variables:\n PHREN_PATH Override phren directory (default: ~/.phren)\n PHREN_PROFILE Active profile name\n PHREN_DEBUG Enable debug logging (set to 1)\n\n Embeddings:\n PHREN_OLLAMA_URL Ollama base URL (default: http://localhost:11434, 'off' to disable)\n PHREN_EMBEDDING_API_URL OpenAI-compatible /embeddings endpoint\n PHREN_EMBEDDING_API_KEY API key for embedding endpoint\n PHREN_EMBEDDING_MODEL Embedding model (default: nomic-embed-text)\n\n Context injection:\n PHREN_CONTEXT_TOKEN_BUDGET Max tokens injected per prompt (default: 550)\n PHREN_MAX_INJECT_TOKENS Hard cap on total injected tokens (default: 2000)\n PHREN_HOOK_TIMEOUT_MS Hook subprocess timeout in ms (default: 14000)\n\n Feature flags:\n PHREN_FEATURE_TOOL_HOOK=0 Skip the PostToolUse subprocess (perf)\n PHREN_FEATURE_AUTO_EXTRACT=0 Disable auto memory extraction\n PHREN_FEATURE_AUTO_CAPTURE=1 Extract insights from conversations\n PHREN_FEATURE_SEMANTIC_DEDUP=1 LLM-based dedup on add_finding\n PHREN_FEATURE_HYBRID_SEARCH=0 Disable TF-IDF cosine fallback\n\n Run 'phren help all' to see everything.\n";
39
39
  export declare const DOC_TOPICS: Record<string, string>;
40
40
  export declare const REGISTRY: Command[];
41
41
  export declare function lookupCommand(name: string): Command | undefined;
@@ -43,6 +43,7 @@ export const ENV_HELP = `Environment variables:
43
43
  PHREN_HOOK_TIMEOUT_MS Hook subprocess timeout in ms (default: 14000)
44
44
 
45
45
  Feature flags:
46
+ PHREN_FEATURE_TOOL_HOOK=0 Skip the PostToolUse subprocess (perf)
46
47
  PHREN_FEATURE_AUTO_EXTRACT=0 Disable auto memory extraction
47
48
  PHREN_FEATURE_AUTO_CAPTURE=1 Extract insights from conversations
48
49
  PHREN_FEATURE_SEMANTIC_DEDUP=1 LLM-based dedup on add_finding
@@ -2,7 +2,8 @@ import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import * as crypto from "crypto";
4
4
  import { debugLog, runtimeFile, phrenOk, phrenErr, PhrenError, appendAuditLog, tryUnlink } from "../shared.js";
5
- import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
5
+ import { isValidProjectName, errorMessage } from "../utils.js";
6
+ import { storeAwareProjectPath } from "../store-routing.js";
6
7
  import { withFileLock } from "../shared/governance.js";
7
8
  import { walkDirectory } from "../shared/data-utils.js";
8
9
  import { appendArchivedEntriesToTopicDoc, classifyTopicForText, readProjectTopics, topicReferencePath } from "../project-topics.js";
@@ -114,7 +115,7 @@ function isAlreadyArchived(archivedSet, bullet) {
114
115
  export function autoArchiveToReference(phrenPath, project, keepCount) {
115
116
  if (!isValidProjectName(project))
116
117
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
117
- const resolvedDir = safeProjectPath(phrenPath, project);
118
+ const resolvedDir = storeAwareProjectPath(phrenPath, project);
118
119
  if (!resolvedDir || !fs.existsSync(resolvedDir))
119
120
  return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
120
121
  const learningsPath = path.join(resolvedDir, FINDINGS_FILENAME);
@@ -25,10 +25,7 @@ export declare function normalizeObservationTags(text: string): {
25
25
  text: string;
26
26
  warning?: string;
27
27
  };
28
- /**
29
- * Scan text for secrets and PII patterns. Returns the type of secret found, or null if clean.
30
- */
31
- export declare function scanForSecrets(text: string): string | null;
28
+ export { looksLikePlaceholderSecret, scanForSecrets, redactSecretsForLog } from "./secrets.js";
32
29
  /**
33
30
  * Resolve coreferences in learning text by replacing vague pronouns with concrete names.
34
31
  */
@@ -2,8 +2,9 @@ import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import * as crypto from "crypto";
4
4
  import { debugLog, runtimeFile, KNOWN_OBSERVATION_TAGS } from "../shared.js";
5
- import { isFeatureEnabled, safeProjectPath, errorMessage } from "../utils.js";
6
- import { UNIVERSAL_TECH_TERMS_RE, EXTRA_ENTITY_PATTERNS } from "../phren-core.js";
5
+ import { isFeatureEnabled, errorMessage } from "../utils.js";
6
+ import { storeAwareProjectPath } from "../store-routing.js";
7
+ import { UNIVERSAL_TECH_TERMS_RE, EXTRA_FRAGMENT_PATTERNS } from "../phren-core.js";
7
8
  import { isInactiveFindingLine } from "../finding/lifecycle.js";
8
9
  import { logger } from "../logger.js";
9
10
  import { FINDINGS_FILENAME } from "../data/access.js";
@@ -258,7 +259,7 @@ function extractProseEntities(text, dynamicEntities) {
258
259
  while ((m = re.exec(text)) !== null)
259
260
  found.add(m[0].toLowerCase());
260
261
  // Match additional fragment patterns (versions, env keys, file paths, error codes, dates)
261
- for (const { re: pattern } of EXTRA_ENTITY_PATTERNS) {
262
+ for (const { re: pattern } of EXTRA_FRAGMENT_PATTERNS) {
262
263
  const pRe = new RegExp(pattern.source, pattern.flags);
263
264
  let pm;
264
265
  while ((pm = pRe.exec(text)) !== null)
@@ -404,67 +405,11 @@ export function normalizeObservationTags(text) {
404
405
  : undefined;
405
406
  return { text: normalized, warning };
406
407
  }
407
- /**
408
- * Scan text for secrets and PII patterns. Returns the type of secret found, or null if clean.
409
- */
410
- export function scanForSecrets(text) {
411
- // AWS Access Key
412
- if (/AKIA[0-9A-Z]{16}/.test(text))
413
- return 'AWS access key';
414
- // AWS Secret Access Key (variable assignment pattern)
415
- if (/(?:aws[_-]?secret|AWS_SECRET)[_-]?(?:access[_-]?)?key[_-]?(?:id)?['":\s]+[A-Za-z0-9/+=]{40}/i.test(text))
416
- return 'AWS secret access key';
417
- // JWT token
418
- if (/eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/.test(text))
419
- return 'JWT token';
420
- // Long base64-encoded secret-like blob (requires base64 chars including +/= and must not be
421
- // a plain hex digest like a git commit SHA — 40-char lowercase hex is explicitly exempt).
422
- if (!/^[0-9a-f]{40}$/.test(text) && /(?=[A-Za-z0-9+/]*[+/][A-Za-z0-9+/]*)[A-Za-z0-9+/]{40,}={0,2}/.test(text.replace(/[0-9a-f]{40}/g, "")))
423
- return 'long base64 secret';
424
- // Connection string with credentials
425
- if (/(mongodb|postgres|mysql|redis):\/\/[^@\s]+:[^@\s]+@/i.test(text))
426
- return 'connection string with credentials';
427
- // SSH private key
428
- if (/-----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY-----/.test(text))
429
- return 'SSH private key';
430
- // Anthropic API key
431
- if (/sk-ant-api\d{2}-[A-Za-z0-9_\-]{10,}/.test(text))
432
- return 'Anthropic API key';
433
- // OpenAI API key
434
- if (/sk-proj-[A-Za-z0-9_\-]{30,}/.test(text))
435
- return 'OpenAI API key';
436
- // GitHub PAT classic
437
- if (/ghp_[A-Za-z0-9]{36}/.test(text))
438
- return 'GitHub personal access token';
439
- // GitHub OAuth token
440
- if (/gho_[A-Za-z0-9]{36}/.test(text))
441
- return 'GitHub OAuth token';
442
- // GitHub tokens (classic, OAuth, user, org, server)
443
- if (/gh[pousr]_[A-Za-z0-9]{36}/.test(text))
444
- return 'GitHub token';
445
- // Slack bot token
446
- if (/xoxb-[0-9]+-[A-Za-z0-9-]+/.test(text))
447
- return 'Slack bot token';
448
- // Slack user token
449
- if (/xoxp-[0-9]+-[A-Za-z0-9-]+/.test(text))
450
- return 'Slack user token';
451
- // Stripe secret key
452
- if (/sk_live_[A-Za-z0-9]{24,}/.test(text))
453
- return 'Stripe secret key';
454
- // Stripe publishable key
455
- if (/pk_live_[A-Za-z0-9]{24,}/.test(text))
456
- return 'Stripe publishable key';
457
- // npm access token
458
- if (/npm_[A-Za-z0-9]{36}/.test(text))
459
- return 'npm access token';
460
- // GCP service account
461
- if (/"private_key_id"\s*:\s*"[^"]{20,}"/.test(text))
462
- return 'GCP service account key';
463
- // Generic API key (only when variable name suggests it)
464
- if (/['"]?(api_?key|secret|token|password)['"]?\s*[=:]\s*['"]?[a-zA-Z0-9_\-\.]{20,}/i.test(text))
465
- return 'API key or secret';
466
- return null;
467
- }
408
+ // Credential detection lives in a dependency-free leaf module so hooks.ts can
409
+ // use it without dragging in this file's import graph. Re-exported here
410
+ // because content/learning.ts, data/notes.ts and shared/content.ts all import
411
+ // scanForSecrets from dedup.
412
+ export { looksLikePlaceholderSecret, scanForSecrets, redactSecretsForLog } from "./secrets.js";
468
413
  /**
469
414
  * Resolve coreferences in learning text by replacing vague pronouns with concrete names.
470
415
  */
@@ -499,7 +444,7 @@ export function resolveCoref(text, context) {
499
444
  export async function checkSemanticDedup(phrenPath, project, newLearning, signal) {
500
445
  if (!isFeatureEnabled("PHREN_FEATURE_SEMANTIC_DEDUP", false))
501
446
  return false;
502
- const resolvedDir = safeProjectPath(phrenPath, project);
447
+ const resolvedDir = storeAwareProjectPath(phrenPath, project);
503
448
  if (!resolvedDir)
504
449
  return false;
505
450
  const findingsPath = path.join(resolvedDir, FINDINGS_FILENAME);
@@ -551,7 +496,7 @@ const CONFLICT_CHECK_TOTAL_TIMEOUT_MS = 30_000;
551
496
  export async function checkSemanticConflicts(phrenPath, project, newFinding, signal) {
552
497
  if (!isFeatureEnabled("PHREN_FEATURE_SEMANTIC_CONFLICT", false))
553
498
  return { annotations: [], checked: false };
554
- const resolvedDir = safeProjectPath(phrenPath, project);
499
+ const resolvedDir = storeAwareProjectPath(phrenPath, project);
555
500
  if (!resolvedDir)
556
501
  return { annotations: [], checked: false };
557
502
  const newEntities = extractProseEntities(newFinding);