@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
@@ -15,9 +15,21 @@ export declare function getCloudEmbeddingUrl(): string | null;
15
15
  export declare function getOllamaUrl(): string | null;
16
16
  export declare function getEmbeddingModel(): string;
17
17
  export declare function getExtractModel(): string;
18
- export declare function checkOllamaAvailable(url?: string): Promise<boolean>;
18
+ export declare function checkOllamaAvailable(url?: string, timeoutMs?: number): Promise<boolean>;
19
+ /** Budget for the one query embedding a prompt-time vector search is allowed to wait on. */
20
+ export declare function getVectorQueryTimeoutMs(): number;
21
+ /**
22
+ * Cheap, cached "can we embed right now?" check for latency-sensitive callers.
23
+ *
24
+ * Returns false immediately (no network at all) when a probe within the last
25
+ * minute already failed, so a machine without Ollama pays at most one 800ms
26
+ * probe per minute instead of a 10s stall per prompt. A configured cloud
27
+ * embedding endpoint short-circuits to true — it has its own timeout and is not
28
+ * expected to be a local process that may simply be missing.
29
+ */
30
+ export declare function isEmbeddingBackendReachable(phrenPath: string): Promise<boolean>;
19
31
  export declare function checkModelAvailable(model?: string, url?: string): Promise<boolean>;
20
- export declare function embedText(text: string, model?: string, url?: string): Promise<number[] | null>;
32
+ export declare function embedText(text: string, model?: string, url?: string, timeoutMs?: number): Promise<number[] | null>;
21
33
  export declare function generateText(prompt: string, model?: string, url?: string): Promise<string | null>;
22
34
  export type OllamaStatus = "ready" | "no_model" | "not_running" | "disabled";
23
35
  /**
@@ -1,4 +1,5 @@
1
- import { debugLog } from "../shared.js";
1
+ import * as fs from "fs";
2
+ import { debugLog, runtimeFile } from "../shared.js";
2
3
  const DEFAULT_OLLAMA_URL = "http://localhost:11434";
3
4
  const DEFAULT_EMBEDDING_MODEL = "nomic-embed-text";
4
5
  const DEFAULT_EXTRACT_MODEL = "llama3.2";
@@ -81,7 +82,7 @@ export function getEmbeddingModel() {
81
82
  export function getExtractModel() {
82
83
  return process.env["PHREN_EXTRACT_MODEL"] ?? DEFAULT_EXTRACT_MODEL;
83
84
  }
84
- export async function checkOllamaAvailable(url) {
85
+ export async function checkOllamaAvailable(url, timeoutMs = OLLAMA_HEALTH_TIMEOUT_MS) {
85
86
  // When cloud embedding is configured, report as "available" (skip Ollama probe)
86
87
  if (!url && getCloudEmbeddingUrl())
87
88
  return true;
@@ -90,7 +91,7 @@ export async function checkOllamaAvailable(url) {
90
91
  return false;
91
92
  try {
92
93
  const controller = new AbortController();
93
- const id = setTimeout(() => controller.abort(), OLLAMA_HEALTH_TIMEOUT_MS);
94
+ const id = setTimeout(() => controller.abort(), timeoutMs);
94
95
  const res = await fetch(`${baseUrl}/api/tags`, { signal: controller.signal });
95
96
  clearTimeout(id);
96
97
  return res.ok;
@@ -99,6 +100,84 @@ export async function checkOllamaAvailable(url) {
99
100
  return false;
100
101
  }
101
102
  }
103
+ // ── Hook-safe reachability gate ─────────────────────────────────────────────
104
+ //
105
+ // PHREN_OLLAMA_URL defaults to http://localhost:11434, so a user who never set
106
+ // up Ollama still has an embedding backend "configured". A socket that accepts
107
+ // the connection and then never answers — Ollama mid-restart, a model still
108
+ // loading, an unrelated listener — makes `embedText` sit on its 10s abort
109
+ // timeout, which is the *entire* UserPromptSubmit budget: the hook is killed
110
+ // and the prompt gets no phren context at all. Measured on a 1892-file store:
111
+ // 306ms with the backend off, 368ms with it absent, 10,376ms against a
112
+ // listening-but-silent socket.
113
+ //
114
+ // So probe first, briefly, and remember the answer on disk. Hooks are separate
115
+ // processes, so an in-process memo would never survive to help the next prompt.
116
+ const HOOK_PROBE_TIMEOUT_MS = 800;
117
+ const REACHABILITY_TTL_DEFAULT_MS = 60_000;
118
+ function reachabilityFile(phrenPath) {
119
+ return runtimeFile(phrenPath, "embedding-backend-health.json");
120
+ }
121
+ function readReachability(phrenPath, url) {
122
+ try {
123
+ const parsed = JSON.parse(fs.readFileSync(reachabilityFile(phrenPath), "utf8"));
124
+ if (typeof parsed?.url !== "string" || typeof parsed.ok !== "boolean" || typeof parsed.at !== "number")
125
+ return null;
126
+ if (parsed.url !== url)
127
+ return null;
128
+ // The cost of being wrong is asymmetric and bounded either way: a stale
129
+ // "down" costs a minute of degraded (not broken) semantic search, a stale
130
+ // "up" costs one probe. `phren doctor` still probes live, so diagnostics
131
+ // never read from this marker.
132
+ if (Date.now() - parsed.at > positiveIntEnv("PHREN_EMBEDDING_HEALTH_TTL_MS", REACHABILITY_TTL_DEFAULT_MS))
133
+ return null;
134
+ return parsed;
135
+ }
136
+ catch {
137
+ return null;
138
+ }
139
+ }
140
+ function writeReachability(phrenPath, marker) {
141
+ try {
142
+ fs.writeFileSync(reachabilityFile(phrenPath), JSON.stringify(marker));
143
+ }
144
+ catch (err) {
145
+ debugLog(`writeReachability: ${err instanceof Error ? err.message : String(err)}`);
146
+ }
147
+ }
148
+ function positiveIntEnv(name, fallback) {
149
+ const raw = process.env[name];
150
+ if (!raw)
151
+ return fallback;
152
+ const parsed = Number.parseInt(raw, 10);
153
+ return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
154
+ }
155
+ /** Budget for the one query embedding a prompt-time vector search is allowed to wait on. */
156
+ export function getVectorQueryTimeoutMs() {
157
+ return positiveIntEnv("PHREN_VECTOR_QUERY_TIMEOUT_MS", 5_000);
158
+ }
159
+ /**
160
+ * Cheap, cached "can we embed right now?" check for latency-sensitive callers.
161
+ *
162
+ * Returns false immediately (no network at all) when a probe within the last
163
+ * minute already failed, so a machine without Ollama pays at most one 800ms
164
+ * probe per minute instead of a 10s stall per prompt. A configured cloud
165
+ * embedding endpoint short-circuits to true — it has its own timeout and is not
166
+ * expected to be a local process that may simply be missing.
167
+ */
168
+ export async function isEmbeddingBackendReachable(phrenPath) {
169
+ if (getCloudEmbeddingUrl())
170
+ return true;
171
+ const url = getOllamaUrl();
172
+ if (!url)
173
+ return false;
174
+ const cached = readReachability(phrenPath, url);
175
+ if (cached)
176
+ return cached.ok;
177
+ const ok = await checkOllamaAvailable(url, HOOK_PROBE_TIMEOUT_MS);
178
+ writeReachability(phrenPath, { url, ok, at: Date.now() });
179
+ return ok;
180
+ }
102
181
  export async function checkModelAvailable(model, url) {
103
182
  // When cloud embedding is configured, assume model is available (no /api/tags equivalent)
104
183
  if (!url && getCloudEmbeddingUrl())
@@ -121,7 +200,7 @@ export async function checkModelAvailable(model, url) {
121
200
  return false;
122
201
  }
123
202
  }
124
- export async function embedText(text, model, url) {
203
+ export async function embedText(text, model, url, timeoutMs) {
125
204
  const modelName = model ?? getEmbeddingModel();
126
205
  const input = prepareEmbeddingInput(text);
127
206
  if (!input)
@@ -136,7 +215,7 @@ export async function embedText(text, model, url) {
136
215
  return null;
137
216
  try {
138
217
  const controller = new AbortController();
139
- const id = setTimeout(() => controller.abort(), OLLAMA_EMBEDDING_TIMEOUT_MS);
218
+ const id = setTimeout(() => controller.abort(), timeoutMs ?? OLLAMA_EMBEDDING_TIMEOUT_MS);
140
219
  const res = await fetch(`${baseUrl}/api/embed`, {
141
220
  method: "POST",
142
221
  headers: { "Content-Type": "application/json" },
@@ -50,6 +50,24 @@ export interface FederatedDocRow extends DocRow {
50
50
  * Returns an array of results tagged with their source store. Read-only — no mutations.
51
51
  */
52
52
  export declare function searchFederatedStores(localPhrenPath: string, options: Omit<SearchKnowledgeRowsOptions, "phrenPath">): Promise<FederatedDocRow[]>;
53
+ /**
54
+ * Doc types that must never be pushed into an agent's prompt automatically.
55
+ *
56
+ * - `notes` — personal scratch context; the user's, not the agent's.
57
+ * - `review-queue` — review.md, which is a *quarantine*. Its entries are candidates
58
+ * nobody has approved yet, and the trust filter does not even look at them (they are
59
+ * not in TRUST_FILTERED_TYPES), so an unreviewed line would reach a prompt with no
60
+ * staleness, confidence, or citation checks at all. Injecting the queue would also
61
+ * defeat the point of having a queue: approve/reject would decide nothing, because
62
+ * the content is already in play.
63
+ *
64
+ * Both remain indexed and reachable through explicit `search_knowledge` — a pull the
65
+ * caller asked for, tagged with its doc type — which is how a user answers "why is this
66
+ * in my review queue?" without the content leaking into every prompt.
67
+ */
68
+ export declare const NON_INJECTABLE_TYPES: Set<string>;
69
+ /** True when a doc type is allowed on the automatic injection path. */
70
+ export declare function isInjectableDocType(type: string): boolean;
53
71
  export type TrustFilterQueueItem = {
54
72
  project: string;
55
73
  section: "Stale" | "Conflicts";
@@ -61,7 +79,10 @@ export type TrustFilterResult = {
61
79
  auditEntries: string[];
62
80
  };
63
81
  /** Apply trust filter to rows. Returns filtered rows plus any queue/audit items to be written
64
- * by the caller — retrieval itself should remain side-effect-free. */
82
+ * by the caller — retrieval itself should remain side-effect-free.
83
+ *
84
+ * This runs only on the automatic injection path, so it is also where non-injectable
85
+ * doc types (notes, review-queue) are dropped. */
65
86
  export declare function applyTrustFilter(rows: DocRow[], ttlDays: number, minConfidence: number, decay: Partial<RetentionPolicy["decay"]>, phrenPath?: string): TrustFilterResult;
66
87
  /** Item 3: Recency boost for findings. Recent findings rank higher. Accepts pre-computed date string. */
67
88
  export declare function recencyBoost(docType: string, latestDate: string): number;
@@ -556,13 +556,37 @@ export async function searchFederatedStores(localPhrenPath, options) {
556
556
  }
557
557
  // ── Trust filter ─────────────────────────────────────────────────────────────
558
558
  const TRUST_FILTERED_TYPES = new Set(["findings", "reference", "knowledge"]);
559
+ /**
560
+ * Doc types that must never be pushed into an agent's prompt automatically.
561
+ *
562
+ * - `notes` — personal scratch context; the user's, not the agent's.
563
+ * - `review-queue` — review.md, which is a *quarantine*. Its entries are candidates
564
+ * nobody has approved yet, and the trust filter does not even look at them (they are
565
+ * not in TRUST_FILTERED_TYPES), so an unreviewed line would reach a prompt with no
566
+ * staleness, confidence, or citation checks at all. Injecting the queue would also
567
+ * defeat the point of having a queue: approve/reject would decide nothing, because
568
+ * the content is already in play.
569
+ *
570
+ * Both remain indexed and reachable through explicit `search_knowledge` — a pull the
571
+ * caller asked for, tagged with its doc type — which is how a user answers "why is this
572
+ * in my review queue?" without the content leaking into every prompt.
573
+ */
574
+ export const NON_INJECTABLE_TYPES = new Set(["notes", "review-queue"]);
575
+ /** True when a doc type is allowed on the automatic injection path. */
576
+ export function isInjectableDocType(type) {
577
+ return !NON_INJECTABLE_TYPES.has(type);
578
+ }
559
579
  /** Apply trust filter to rows. Returns filtered rows plus any queue/audit items to be written
560
- * by the caller — retrieval itself should remain side-effect-free. */
580
+ * by the caller — retrieval itself should remain side-effect-free.
581
+ *
582
+ * This runs only on the automatic injection path, so it is also where non-injectable
583
+ * doc types (notes, review-queue) are dropped. */
561
584
  export function applyTrustFilter(rows, ttlDays, minConfidence, decay, phrenPath) {
562
585
  const queueItems = [];
563
586
  const auditEntries = [];
564
587
  const highImpactFindingIds = phrenPath ? getHighImpactFindings(phrenPath, 3) : undefined;
565
588
  const filtered = rows
589
+ .filter((doc) => isInjectableDocType(doc.type))
566
590
  .map((doc) => {
567
591
  if (!TRUST_FILTERED_TYPES.has(doc.type))
568
592
  return doc;
@@ -835,6 +859,11 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
835
859
  }).join('\n');
836
860
  }
837
861
  for (const doc of rows) {
862
+ // Last gate before content becomes prompt text. Quarantined and personal doc types
863
+ // never get this far on the normal path, but this is the only place that is
864
+ // unconditionally true of everything injected, so it is checked here too.
865
+ if (!isInjectableDocType(doc.type))
866
+ continue;
838
867
  let snippet = compactSnippet(extractSnippet(doc.content, keywords, 8), lineBudget, charBudget);
839
868
  if (!snippet.trim())
840
869
  continue;
@@ -4,7 +4,7 @@ import { logger } from "../logger.js";
4
4
  import { STOP_WORDS, errorMessage } from "../utils.js";
5
5
  import { porterStem } from "./stemmer.js";
6
6
  import { classifyFile, normalizeIndexedContent, rowToDocWithRowid } from "./index.js";
7
- import { embedText, cosineSimilarity, getEmbeddingModel, getOllamaUrl, getCloudEmbeddingUrl } from "./ollama.js";
7
+ import { embedText, cosineSimilarity, getEmbeddingModel, getOllamaUrl, getCloudEmbeddingUrl, getVectorQueryTimeoutMs, isEmbeddingBackendReachable, } from "./ollama.js";
8
8
  import { getEmbeddingCache } from "./embedding-cache.js";
9
9
  import { getPersistentVectorIndex } from "./vector-index.js";
10
10
  import * as fs from "fs";
@@ -297,6 +297,14 @@ export async function vectorFallback(phrenPath, query, excludePaths, limit, proj
297
297
  // Run when either Ollama or a cloud embedding endpoint is available
298
298
  if (!getOllamaUrl() && !getCloudEmbeddingUrl())
299
299
  return [];
300
+ // Reachability first, and before the embedding cache load. Without a backend
301
+ // this function can only return [], so parsing a multi-megabyte
302
+ // embeddings.json ahead of that check is work whose result is already known
303
+ // — 42ms of a hook's budget on an 8.5MB cache, every prompt, for nothing.
304
+ if (!await isEmbeddingBackendReachable(phrenPath)) {
305
+ debugLog("vectorFallback: embedding backend unreachable, skipping vector search");
306
+ return [];
307
+ }
300
308
  const cache = getEmbeddingCache(phrenPath);
301
309
  // Ensure the cache is loaded from disk — in hook subprocesses the singleton
302
310
  // starts empty because load() is only called in the MCP server / CLI entry.
@@ -310,7 +318,9 @@ export async function vectorFallback(phrenPath, query, excludePaths, limit, proj
310
318
  }
311
319
  if (cache.size() === 0)
312
320
  return [];
313
- const queryVec = await embedText(query);
321
+ // A reachable backend can still be slow (a cold model load takes seconds).
322
+ // Cap the one embedding a prompt waits on so the hook always finishes.
323
+ const queryVec = await embedText(query, undefined, undefined, getVectorQueryTimeoutMs());
314
324
  if (!queryVec || queryVec.length === 0)
315
325
  return [];
316
326
  const model = getEmbeddingModel();
@@ -333,7 +343,9 @@ export async function vectorFallback(phrenPath, query, excludePaths, limit, proj
333
343
  return [];
334
344
  const eligiblePaths = new Set(entries.map((entry) => entry.path));
335
345
  const vectorIndex = getPersistentVectorIndex(phrenPath);
336
- vectorIndex.ensure(cache.getAllEntries());
346
+ // Stamp the index with the revision these entries came from, not with a fresh
347
+ // stat: a long-lived process's cache can lag the file on disk.
348
+ vectorIndex.ensure(cache.getAllEntries(), cache.sourceMarker());
337
349
  const indexedPaths = vectorIndex.query(model, queryVec, limit, eligiblePaths);
338
350
  const candidatePaths = indexedPaths.length > 0 ? new Set(indexedPaths) : eligiblePaths;
339
351
  const scored = entries
@@ -1,3 +1,8 @@
1
+ /** Mirrors `EmbeddingSourceMarker`; kept structural so the modules stay decoupled. */
2
+ interface SourceMarker {
3
+ mtimeMs: number;
4
+ size: number;
5
+ }
1
6
  interface EmbeddingEntryLike {
2
7
  path: string;
3
8
  model: string;
@@ -11,7 +16,21 @@ declare class PersistentVectorIndex {
11
16
  constructor(phrenPath: string);
12
17
  private loadFromDisk;
13
18
  private saveToDisk;
14
- ensure(entries: EmbeddingEntryLike[]): void;
19
+ /**
20
+ * Build (or reuse) the LSH tables for `entries`.
21
+ *
22
+ * `entriesSource` is the embeddings.json revision `entries` was read from.
23
+ * It matters because the caller's entry list can lag the file on disk: a
24
+ * long-lived MCP server loads the embedding cache once, while hooks and
25
+ * background reindexes keep rewriting embeddings.json underneath it. Statting
26
+ * the file here instead would stamp the *current* revision onto tables built
27
+ * from the *older* entry list, and every later process would then accept that
28
+ * index as fresh — permanently invisible documents, not a rebuild loop.
29
+ *
30
+ * Callers that genuinely hold the file's current contents may omit it; the
31
+ * marker then falls back to a stat, which is what it always was.
32
+ */
33
+ ensure(entries: EmbeddingEntryLike[], entriesSource?: SourceMarker | null): void;
15
34
  query(model: string, queryVec: number[], limit: number, eligiblePaths?: Set<string>): string[];
16
35
  }
17
36
  export declare function getPersistentVectorIndex(phrenPath: string): PersistentVectorIndex;
@@ -138,13 +138,27 @@ class PersistentVectorIndex {
138
138
  debugLog(`PersistentVectorIndex save failed: ${errorMessage(err)}`);
139
139
  }
140
140
  }
141
- ensure(entries) {
141
+ /**
142
+ * Build (or reuse) the LSH tables for `entries`.
143
+ *
144
+ * `entriesSource` is the embeddings.json revision `entries` was read from.
145
+ * It matters because the caller's entry list can lag the file on disk: a
146
+ * long-lived MCP server loads the embedding cache once, while hooks and
147
+ * background reindexes keep rewriting embeddings.json underneath it. Statting
148
+ * the file here instead would stamp the *current* revision onto tables built
149
+ * from the *older* entry list, and every later process would then accept that
150
+ * index as fresh — permanently invisible documents, not a rebuild loop.
151
+ *
152
+ * Callers that genuinely hold the file's current contents may omit it; the
153
+ * marker then falls back to a stat, which is what it always was.
154
+ */
155
+ ensure(entries, entriesSource) {
142
156
  this.loadFromDisk();
143
- const currentSource = readSourceMarker(this.phrenPath);
144
- if (markersMatch(this.source, currentSource) && Object.keys(this.models).length > 0)
157
+ const source = entriesSource !== undefined ? entriesSource : readSourceMarker(this.phrenPath);
158
+ if (markersMatch(this.source, source) && Object.keys(this.models).length > 0)
145
159
  return;
146
160
  this.models = buildVectorIndexData(entries);
147
- this.source = currentSource;
161
+ this.source = source;
148
162
  this.saveToDisk();
149
163
  }
150
164
  query(model, queryVec, limit, eligiblePaths) {
package/dist/shared.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export type { HookToolName } from "./provider-adapters.js";
2
2
  export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
3
3
  export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, type PhrenErrorCode, type PhrenResult, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, type FindingType, FINDING_TAGS, type FindingTag, KNOWN_OBSERVATION_TAGS, DOC_TYPES, type DocType, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
4
- export { ROOT_MANIFEST_FILENAME, type InstallMode, type SyncMode, type PhrenRootManifest, type InstallContext, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
4
+ export { ROOT_MANIFEST_FILENAME, type InstallMode, type SyncMode, type PhrenRootManifest, type InstallContext, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, projectSlugFromPath, canonicalProjectKey, findProjectNameCaseInsensitive, findProjectNamesByCanonicalKey, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, ensurePrivateDir, ftsCacheRoot, ensureFtsCacheRootPrivate, } from "./phren-paths.js";
5
5
  export { PROACTIVITY_LEVELS, type ProactivityLevel, parseProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
6
6
  export declare function normalizeMemoryScope(scope?: string | null): string | undefined;
7
7
  export declare function isMemoryScopeVisible(itemScope: string | undefined, activeScope?: string): boolean;
package/dist/shared.js CHANGED
@@ -6,7 +6,7 @@ import { withFileLock } from "./governance/locks.js";
6
6
  const MAX_LOG_LINES = 1000;
7
7
  export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
8
8
  export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, FINDING_TAGS, KNOWN_OBSERVATION_TAGS, DOC_TYPES, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
9
- export { ROOT_MANIFEST_FILENAME, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, findProjectNameCaseInsensitive, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, } from "./phren-paths.js";
9
+ export { ROOT_MANIFEST_FILENAME, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, projectSlugFromPath, canonicalProjectKey, findProjectNameCaseInsensitive, findProjectNamesByCanonicalKey, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, ensurePrivateDir, ftsCacheRoot, ensureFtsCacheRootPrivate, } from "./phren-paths.js";
10
10
  export { PROACTIVITY_LEVELS, parseProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
11
11
  const MEMORY_SCOPE_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
12
12
  export function normalizeMemoryScope(scope) {
package/dist/status.js CHANGED
@@ -10,6 +10,7 @@ import { getTelemetrySummary } from "./telemetry.js";
10
10
  import { runGit as runGitShared, errorMessage } from "./utils.js";
11
11
  import { logger } from "./logger.js";
12
12
  import { readRuntimeHealth, resolveTaskFilePath, FINDINGS_FILENAME } from "./data/access.js";
13
+ import { assessSyncOutage } from "./shared/governance.js";
13
14
  import { resolveRuntimeProfile } from "./runtime-profile.js";
14
15
  import { renderPhrenArt } from "./phren-art.js";
15
16
  import { RESET, BOLD, DIM, GREEN, YELLOW, RED, CYAN } from "./shell/render.js";
@@ -313,10 +314,19 @@ export async function runStatus() {
313
314
  roleParts.push(`${readonlyCount} readonly`);
314
315
  console.log(`\n ${BOLD}Stores${RESET} ${DIM}(${stores.length} stores: ${roleParts.join(", ")})${RESET}`);
315
316
  for (const store of stores) {
316
- const exists = fs.existsSync(store.path);
317
+ const exists = store.available !== false;
317
318
  const existsLabel = exists ? `${GREEN}yes${RESET}` : `${RED}no${RESET}`;
318
319
  console.log(` ${store.name} ${DIM}(${store.role}, ${store.sync})${RESET} path=${existsLabel}${store.remote ? ` remote=${DIM}${store.remote}${RESET}` : ""}`);
319
320
  }
321
+ // A store declared in stores.yaml but absent here is not cosmetic: any
322
+ // project it claims cannot be written until it is attached.
323
+ const { describeUnavailableStore } = await import("./store-registry.js");
324
+ for (const store of stores.filter((s) => s.available === false)) {
325
+ console.log(` ${YELLOW}! ${describeUnavailableStore(store)}${RESET}`);
326
+ if (store.projects?.length) {
327
+ console.log(` ${YELLOW}writes to ${store.projects.join(", ")} will fail until it is attached${RESET}`);
328
+ }
329
+ }
320
330
  }
321
331
  }
322
332
  catch (err) {
@@ -355,9 +365,16 @@ export async function runStatus() {
355
365
  console.log(` last pull ${runtime.lastSync?.lastPullStatus || "n/a"}${runtime.lastSync?.lastPullAt ? ` @ ${runtime.lastSync.lastPullAt}` : ""}`);
356
366
  console.log(` last push ${runtime.lastSync?.lastPushStatus || "n/a"}${runtime.lastSync?.lastPushAt ? ` @ ${runtime.lastSync.lastPushAt}` : ""}`);
357
367
  console.log(` unsynced commits ${runtime.lastSync?.unsyncedCommits ?? 0}`);
368
+ if (runtime.lastSync?.lastSuccessfulPushAt) {
369
+ console.log(` last successful push ${runtime.lastSync.lastSuccessfulPushAt}`);
370
+ }
358
371
  if (runtime.lastSync?.lastPushDetail) {
359
372
  console.log(` push detail ${runtime.lastSync.lastPushDetail}`);
360
373
  }
374
+ const outage = assessSyncOutage(runtime.lastSync);
375
+ if (outage.degraded) {
376
+ console.log(` ${RED}! ${outage.summary}${RESET}`);
377
+ }
361
378
  }
362
379
  // Recent changes (git log)
363
380
  if (isGitRepo) {
@@ -15,6 +15,12 @@ export interface StoreEntry {
15
15
  sync: StoreSyncMode;
16
16
  /** Projects claimed by this store (for write routing in phase 2). */
17
17
  projects?: string[];
18
+ /**
19
+ * Whether {@link path} exists on this machine. Computed by
20
+ * {@link resolveAllStores}; never persisted to stores.yaml. `undefined` on
21
+ * hand-built entries that never went through resolution.
22
+ */
23
+ available?: boolean;
18
24
  }
19
25
  export interface StoreRegistry {
20
26
  version: 1;
@@ -31,13 +37,29 @@ export declare function storesFilePath(phrenPath: string): string;
31
37
  export declare function generateStoreId(): string;
32
38
  export declare function readStoreRegistry(phrenPath: string): StoreRegistry | null;
33
39
  export declare function writeStoreRegistry(phrenPath: string, registry: StoreRegistry): void;
40
+ /** True when a store's directory exists on this machine. */
41
+ export declare function storePathExists(storePath: string): boolean;
34
42
  /**
35
43
  * Resolve the full list of stores. This is the **key backward-compat function**:
36
44
  * - If stores.yaml exists → parse and return entries
37
45
  * - If stores.yaml is missing → return a single implicit primary entry for phrenPath
38
46
  * - In both cases, append PHREN_FEDERATION_PATHS entries as readonly stores
47
+ *
48
+ * Every returned entry carries `available`, recording whether its path exists
49
+ * here. Declared-but-absent stores are deliberately **still returned**: callers
50
+ * must be able to see that a store claims a project before deciding what to do,
51
+ * otherwise a team store that simply isn't cloned yet would look like "no store
52
+ * claims this project" and its writes would land in the primary store.
39
53
  */
40
54
  export declare function resolveAllStores(phrenPath: string): StoreEntry[];
55
+ /** Stores declared in stores.yaml whose directory is missing on this machine. */
56
+ export declare function getUnavailableStores(phrenPath: string): StoreEntry[];
57
+ /**
58
+ * One actionable sentence about a store that is declared but not attached here.
59
+ * Shared by write routing, `phren status`, and `phren doctor` so all three name
60
+ * the same store, the same expected path, and the same remedy.
61
+ */
62
+ export declare function describeUnavailableStore(store: StoreEntry): string;
41
63
  /** The primary store (role=primary). Falls back to implicit entry. */
42
64
  export declare function getPrimaryStore(phrenPath: string): StoreEntry;
43
65
  /** All stores that can be read (all roles). */
@@ -58,10 +58,12 @@ export function writeStoreRegistry(phrenPath, registry) {
58
58
  const err = validateRegistry(registry);
59
59
  if (err)
60
60
  throw new Error(`${PhrenError.VALIDATION_ERROR}: ${err}`);
61
- // Collapse paths to ~ prefix for portability
61
+ // Collapse paths to ~ prefix for portability. `available` is machine-local
62
+ // state computed at resolve time — it must never be written to stores.yaml,
63
+ // which is shared across machines via git.
62
64
  const portable = {
63
65
  version: 1,
64
- stores: registry.stores.map((s) => ({
66
+ stores: registry.stores.map(({ available: _available, ...s }) => ({
65
67
  ...s,
66
68
  path: collapsePath(s.path),
67
69
  })),
@@ -69,11 +71,26 @@ export function writeStoreRegistry(phrenPath, registry) {
69
71
  atomicWriteText(storesFilePath(phrenPath), yaml.dump(portable, { lineWidth: 200 }));
70
72
  }
71
73
  // ── Resolution ───────────────────────────────────────────────────────────────
74
+ /** True when a store's directory exists on this machine. */
75
+ export function storePathExists(storePath) {
76
+ try {
77
+ return fs.statSync(storePath).isDirectory();
78
+ }
79
+ catch {
80
+ return false;
81
+ }
82
+ }
72
83
  /**
73
84
  * Resolve the full list of stores. This is the **key backward-compat function**:
74
85
  * - If stores.yaml exists → parse and return entries
75
86
  * - If stores.yaml is missing → return a single implicit primary entry for phrenPath
76
87
  * - In both cases, append PHREN_FEDERATION_PATHS entries as readonly stores
88
+ *
89
+ * Every returned entry carries `available`, recording whether its path exists
90
+ * here. Declared-but-absent stores are deliberately **still returned**: callers
91
+ * must be able to see that a store claims a project before deciding what to do,
92
+ * otherwise a team store that simply isn't cloned yet would look like "no store
93
+ * claims this project" and its writes would land in the primary store.
77
94
  */
78
95
  export function resolveAllStores(phrenPath) {
79
96
  const registry = readStoreRegistry(phrenPath);
@@ -92,7 +109,23 @@ export function resolveAllStores(phrenPath) {
92
109
  knownPaths.add(fedPath);
93
110
  }
94
111
  }
95
- return stores;
112
+ return stores.map((s) => ({ ...s, available: storePathExists(s.path) }));
113
+ }
114
+ /** Stores declared in stores.yaml whose directory is missing on this machine. */
115
+ export function getUnavailableStores(phrenPath) {
116
+ return resolveAllStores(phrenPath).filter((s) => s.available === false);
117
+ }
118
+ /**
119
+ * One actionable sentence about a store that is declared but not attached here.
120
+ * Shared by write routing, `phren status`, and `phren doctor` so all three name
121
+ * the same store, the same expected path, and the same remedy.
122
+ */
123
+ export function describeUnavailableStore(store) {
124
+ const attach = store.remote
125
+ ? `git clone ${store.remote} "${store.path}" (or: phren team join ${store.remote})`
126
+ : `phren team join <git-url> --name ${store.name}`;
127
+ return (`Store "${store.name}" (role=${store.role}) is declared in ${STORES_FILENAME} but is not attached on this machine — ` +
128
+ `expected path: ${store.path}. Attach it with: ${attach}`);
96
129
  }
97
130
  /** The primary store (role=primary). Falls back to implicit entry. */
98
131
  export function getPrimaryStore(phrenPath) {
@@ -35,3 +35,11 @@ export declare function listAllProjects(phrenPath: string, profile?: string): Ar
35
35
  projectName: string;
36
36
  projectDir: string;
37
37
  }>;
38
+ /**
39
+ * Store-aware variant of safeProjectPath for callers holding the primary store
40
+ * root: when the project directory does not exist in `phrenPath`, resolve the
41
+ * owning store from the registry and build the path under it instead. Falls
42
+ * back to the (nonexistent) primary-store path when the project is in no store
43
+ * or is ambiguous, so callers' existing not-found handling fires unchanged.
44
+ */
45
+ export declare function storeAwareProjectPath(phrenPath: string, project: string, ...segments: string[]): string | null;
@@ -2,7 +2,7 @@ import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { getProjectDirs } from "./phren-paths.js";
4
4
  import { PhrenError } from "./phren-core.js";
5
- import { isValidProjectName } from "./utils.js";
5
+ import { isValidProjectName, safeProjectPath } from "./utils.js";
6
6
  import { resolveAllStores } from "./store-registry.js";
7
7
  // ── Parsing ──────────────────────────────────────────────────────────────────
8
8
  /**
@@ -93,6 +93,28 @@ export function listAllProjects(phrenPath, profile) {
93
93
  }
94
94
  return results;
95
95
  }
96
+ /**
97
+ * Store-aware variant of safeProjectPath for callers holding the primary store
98
+ * root: when the project directory does not exist in `phrenPath`, resolve the
99
+ * owning store from the registry and build the path under it instead. Falls
100
+ * back to the (nonexistent) primary-store path when the project is in no store
101
+ * or is ambiguous, so callers' existing not-found handling fires unchanged.
102
+ */
103
+ export function storeAwareProjectPath(phrenPath, project, ...segments) {
104
+ let root = phrenPath;
105
+ const primaryDir = safeProjectPath(phrenPath, project);
106
+ if (!primaryDir)
107
+ return null;
108
+ if (!fs.existsSync(primaryDir)) {
109
+ try {
110
+ root = resolveProject(phrenPath, project).store.path;
111
+ }
112
+ catch {
113
+ // keep the primary root
114
+ }
115
+ }
116
+ return safeProjectPath(root, project, ...segments);
117
+ }
96
118
  // ── Internal helpers ─────────────────────────────────────────────────────────
97
119
  const STORE_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
98
120
  function isValidStoreName(name) {
@@ -15,6 +15,31 @@ const CONVERSATIONAL_NOISE_RE = /^(ok|okay|yeah|yep|nah|nope|hi|hey|ss|bro|lol|l
15
15
  // Raw system/SQL error fragment signals — patterns that only appear in error output, never real task requests.
16
16
  // Intentionally does NOT include "line \d+" or "incorrect syntax" alone (too broad — they appear in dev prompts).
17
17
  const RAW_MESSAGE_SIGNALS_RE = /\b(msg \d+, level \d+|cannot insert the value null|insufficient result space|uniqueidentifier value to char|pgevision-prod|task-notification|tool-use-id|toolu_0[a-z0-9])\b/i;
18
+ // Pasted terminal banners and web-page chrome. Observed verbatim as committed tasks: a whole
19
+ // GitHub page starting "Skip to content ... Repository navigation Code Issues Pull requests",
20
+ // and "Windows PowerShell Copyright (C) Microsoft Corporation". None of it is a request.
21
+ const PASTED_CONTENT_RE = new RegExp([
22
+ // Web page chrome
23
+ "^\\s*skip to (?:main )?content\\b",
24
+ "\\brepository navigation\\b",
25
+ "\\bjump to (?:content|bottom)\\b",
26
+ "\\byou signed (?:in|out) with another tab\\b",
27
+ "\\bcode\\s+issues\\s+pull requests\\b",
28
+ // Terminal banners and prompts
29
+ "^\\s*windows powershell\\b",
30
+ "\\bcopyright \\(c\\) microsoft corporation\\b",
31
+ "\\bmicrosoft windows \\[version\\b",
32
+ "\\ball rights reserved\\b",
33
+ "\\bps [a-z]:\\\\",
34
+ "^[a-z]:\\\\[^\\n]*>",
35
+ "\\blast login: \\w{3} \\w{3}",
36
+ "npm ERR!",
37
+ "Traceback \\(most recent call last\\)",
38
+ ].join("|"), "i");
39
+ // Chat filler markers. Unlike CONVERSATIONAL_NOISE_RE these match anywhere in the prompt,
40
+ // because the observed echoes wrap filler around an incidental verb — "Its literally just the
41
+ // start of the day LMAO" clears the substance floor on "start" but is not a task.
42
+ const CONVERSATIONAL_FILLER_RE = /\b(?:lmao|lmfao|rofl|lol+|haha+|idk|idc|tbh|ngl|smh|wtf|meh|yolo)\b/i;
18
43
  const ACTIONABLE_RE = /\b(add|build|change|complete|continue|create|delete|fix|implement|improve|investigate|make|move|refactor|remove|rename|repair|ship|start|update|wire)\b/i;
19
44
  const CONTINUE_RE = /\b(continue|keep going|finish|resume|pick up|work on that|that task)\b/i;
20
45
  const GITHUB_URL_RE = /https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/issues\/\d+(?:[?#][^\s]*)?/g;
@@ -118,6 +143,12 @@ function isActionablePrompt(prompt, intent) {
118
143
  return false;
119
144
  if (RAW_MESSAGE_SIGNALS_RE.test(normalized))
120
145
  return false;
146
+ // Task auto-capture writes the prompt verbatim onto a `Context:` line, so anything that is
147
+ // not a request becomes a permanent task. Pasted pages/terminals and chat filler never are.
148
+ if (PASTED_CONTENT_RE.test(normalized))
149
+ return false;
150
+ if (CONVERSATIONAL_FILLER_RE.test(normalized))
151
+ return false;
121
152
  // Substance floor — independent of intent / proactivity. Short utterances without
122
153
  // any actionable signal are conversational fragments, not tasks.
123
154
  if (!hasMinimumTaskSubstance(normalized))