projectstore-claude 0.29.3 → 0.30.0

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 (57) hide show
  1. package/README.md +13 -12
  2. package/bin/projectstore-claude.mjs +2 -2
  3. package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
  4. package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
  5. package/node_modules/projectstore/README.md +153 -77
  6. package/node_modules/projectstore/commands/bind.md +6 -17
  7. package/node_modules/projectstore/commands/doctor.md +12 -7
  8. package/node_modules/projectstore/commands/statusline.md +1 -1
  9. package/node_modules/projectstore/commands/story.md +15 -2
  10. package/node_modules/projectstore/docs/extending.md +11 -6
  11. package/node_modules/projectstore/docs/getting-started.md +21 -1
  12. package/node_modules/projectstore/docs/harnesses.md +13 -10
  13. package/node_modules/projectstore/docs/how-it-works.md +6 -4
  14. package/node_modules/projectstore/harnesses/claude-code.json +16 -15
  15. package/node_modules/projectstore/harnesses/codex.json +12 -13
  16. package/node_modules/projectstore/hooks/band.tsx +48 -20
  17. package/node_modules/projectstore/hooks/pre-compact.mjs +7 -10
  18. package/node_modules/projectstore/hooks/session-rules.mjs +14 -8
  19. package/node_modules/projectstore/hooks/session-start.mjs +50 -18
  20. package/node_modules/projectstore/hooks/session-stop.mjs +8 -6
  21. package/node_modules/projectstore/package.json +11 -2
  22. package/node_modules/projectstore/scripts/band-shared.mjs +141 -24
  23. package/node_modules/projectstore/scripts/band.mjs +72 -21
  24. package/node_modules/projectstore/scripts/binding.mjs +616 -85
  25. package/node_modules/projectstore/scripts/build-adapters.mjs +73 -29
  26. package/node_modules/projectstore/scripts/cli.mjs +1015 -185
  27. package/node_modules/projectstore/scripts/codemap.mjs +22 -7
  28. package/node_modules/projectstore/scripts/convergence.mjs +253 -83
  29. package/node_modules/projectstore/scripts/diff-refs.mjs +14 -8
  30. package/node_modules/projectstore/scripts/doctor-report.mjs +91 -23
  31. package/node_modules/projectstore/scripts/doctor.mjs +1317 -371
  32. package/node_modules/projectstore/scripts/draft.mjs +5 -2
  33. package/node_modules/projectstore/scripts/fetch-shell.mjs +188 -39
  34. package/node_modules/projectstore/scripts/graph.mjs +19 -13
  35. package/node_modules/projectstore/scripts/harness.mjs +123 -48
  36. package/node_modules/projectstore/scripts/install-harness.mjs +3532 -618
  37. package/node_modules/projectstore/scripts/kanban.mjs +2 -1
  38. package/node_modules/projectstore/scripts/lib.mjs +694 -159
  39. package/node_modules/projectstore/scripts/mcp.mjs +386 -105
  40. package/node_modules/projectstore/scripts/portable-registration.mjs +224 -51
  41. package/node_modules/projectstore/scripts/provenance.mjs +26 -10
  42. package/node_modules/projectstore/scripts/query.mjs +378 -80
  43. package/node_modules/projectstore/scripts/reconcile.mjs +55 -18
  44. package/node_modules/projectstore/scripts/run-host.mjs +62 -17
  45. package/node_modules/projectstore/scripts/scaffold.mjs +89 -28
  46. package/node_modules/projectstore/scripts/setup.mjs +987 -0
  47. package/node_modules/projectstore/scripts/stages.mjs +5 -1
  48. package/node_modules/projectstore/scripts/statusline-launcher.mjs +36 -11
  49. package/node_modules/projectstore/scripts/statusline.mjs +32 -14
  50. package/node_modules/projectstore/scripts/story-section.mjs +39 -17
  51. package/node_modules/projectstore/scripts/surfaces.mjs +416 -95
  52. package/node_modules/projectstore/scripts/term.mjs +382 -97
  53. package/node_modules/projectstore/scripts/tokens.mjs +106 -28
  54. package/node_modules/projectstore/scripts/touch-session.mjs +109 -70
  55. package/node_modules/projectstore/scripts/version-guard.mjs +74 -27
  56. package/node_modules/projectstore/scripts/worktree.mjs +16 -5
  57. package/package.json +3 -3
@@ -59,19 +59,38 @@ function die(msg) {
59
59
  // or command name so plugin-prefixed and legacy (pre-v0.13) names both land.
60
60
  const STAGE_OF = {
61
61
  // writing the artifact
62
- adr: "authoring", research: "authoring", epic: "authoring", story: "authoring",
63
- spec: "authoring", concept: "authoring", meeting: "authoring", runbook: "authoring",
62
+ adr: "authoring",
63
+ research: "authoring",
64
+ epic: "authoring",
65
+ story: "authoring",
66
+ spec: "authoring",
67
+ concept: "authoring",
68
+ meeting: "authoring",
69
+ runbook: "authoring",
64
70
  // checking the artifact — independent adversarial pass
65
- critic: "critique", "projectstore-critic": "critique", review: "critique",
71
+ critic: "critique",
72
+ "projectstore-critic": "critique",
73
+ review: "critique",
66
74
  // planning the implementation, then checking the diff against the story
67
- planner: "planning", "code-planner": "planning",
68
- reviewer: "code-review", "code-reviewer": "code-review",
75
+ planner: "planning",
76
+ "code-planner": "planning",
77
+ reviewer: "code-review",
78
+ "code-reviewer": "code-review",
69
79
  // keeping the vault itself coherent
70
- librarian: "curation", archaeologist: "curation",
80
+ librarian: "curation",
81
+ archaeologist: "curation",
71
82
  clerk: "upkeep",
72
- doctor: "upkeep", kanban: "upkeep", reconcile: "upkeep", codemap: "upkeep",
73
- status: "upkeep", statusline: "upkeep", search: "upkeep", bind: "upkeep",
74
- scaffold: "upkeep", agents: "upkeep", tokens: "upkeep",
83
+ doctor: "upkeep",
84
+ kanban: "upkeep",
85
+ reconcile: "upkeep",
86
+ codemap: "upkeep",
87
+ status: "upkeep",
88
+ statusline: "upkeep",
89
+ search: "upkeep",
90
+ bind: "upkeep",
91
+ scaffold: "upkeep",
92
+ agents: "upkeep",
93
+ tokens: "upkeep",
75
94
  };
76
95
  const STAGE_ORDER = ["authoring", "critique", "planning", "code-review", "curation", "upkeep", "other"];
77
96
 
@@ -92,7 +111,12 @@ export const PRICING = {
92
111
  // Transcripts carry variant ids ("claude-haiku-4-5-20251001", "opus",
93
112
  // "claude-opus-5[1m]") — normalize before the PRICING lookup so they don't
94
113
  // silently price at $0.
95
- const MODEL_ALIASES = { fable: "claude-fable-5-1", opus: "claude-opus-5", sonnet: "claude-sonnet-5", haiku: "claude-haiku-4-5" };
114
+ const MODEL_ALIASES = {
115
+ fable: "claude-fable-5-1",
116
+ opus: "claude-opus-5",
117
+ sonnet: "claude-sonnet-5",
118
+ haiku: "claude-haiku-4-5",
119
+ };
96
120
 
97
121
  export function normModel(model) {
98
122
  const m = model.replace(/\[[^\]]*\]$/, "").replace(/-\d{8}$/, "");
@@ -122,8 +146,10 @@ function parseArgs(argv) {
122
146
  else if (a === "--runs") opts.runs = true;
123
147
  else if (a === "--sessions") opts.sessions = true;
124
148
  else if (a === "--since") opts.since = argv[++i];
125
- else if (a === "--project") { opts.project = argv[++i]; if (!opts.project) die("--project expects a directory"); }
126
- else if (a === "--help" || a === "-h") opts.help = true;
149
+ else if (a === "--project") {
150
+ opts.project = argv[++i];
151
+ if (!opts.project) die("--project expects a directory");
152
+ } else if (a === "--help" || a === "-h") opts.help = true;
127
153
  else die(`unknown argument: ${a}`);
128
154
  }
129
155
  if (opts.since && !/^\d{4}-\d{2}-\d{2}$/.test(opts.since)) die("--since expects YYYY-MM-DD");
@@ -294,7 +320,21 @@ export function aggregate(rows, keyFn, calls) {
294
320
  const k = keyFn(row);
295
321
  let g = out.get(k);
296
322
  if (!g) {
297
- g = { key: k, reqs: 0, input: 0, cacheWrite: 0, cacheRead: 0, output: 0, toolCalls: 0, toolTurns: 0, cost: 0, ps: isProjectstore(row), models: new Set(), buckets: new Set(), unpriced: new Set() };
323
+ g = {
324
+ key: k,
325
+ reqs: 0,
326
+ input: 0,
327
+ cacheWrite: 0,
328
+ cacheRead: 0,
329
+ output: 0,
330
+ toolCalls: 0,
331
+ toolTurns: 0,
332
+ cost: 0,
333
+ ps: isProjectstore(row),
334
+ models: new Set(),
335
+ buckets: new Set(),
336
+ unpriced: new Set(),
337
+ };
298
338
  out.set(k, g);
299
339
  }
300
340
  g.reqs++;
@@ -329,12 +369,18 @@ function table(groups, label, { runs = false } = {}) {
329
369
  const head = cols(label, "runs", "reqs", "t/turn", "cache_rd", "output", "cost", "cost/run");
330
370
  const lines = [head, "─".repeat(head.length)];
331
371
  for (const g of groups) {
332
- lines.push(cols(
333
- g.key, g.runs ? n(g.runs) : "—", n(g.reqs),
334
- g.toolTurns ? (g.toolCalls / g.toolTurns).toFixed(2) : "—",
335
- n(g.cacheRead), n(g.output), usd(g.cost),
336
- g.runs ? usd(g.cost / g.runs) : "—",
337
- ));
372
+ lines.push(
373
+ cols(
374
+ g.key,
375
+ g.runs ? n(g.runs) : "—",
376
+ n(g.reqs),
377
+ g.toolTurns ? (g.toolCalls / g.toolTurns).toFixed(2) : "—",
378
+ n(g.cacheRead),
379
+ n(g.output),
380
+ usd(g.cost),
381
+ g.runs ? usd(g.cost / g.runs) : "—",
382
+ ),
383
+ );
338
384
  }
339
385
  return lines.join("\n");
340
386
  }
@@ -368,8 +414,9 @@ function main() {
368
414
  if (rows.size === 0) die(opts.since ? `no requests since ${opts.since}` : "no assistant requests found");
369
415
 
370
416
  const byBucket = aggregate(rows, (r) => r.bucket, calls);
371
- const byStage = aggregate([...rows.values()].filter(isProjectstore), stageOf, calls)
372
- .sort((a, b) => STAGE_ORDER.indexOf(a.key) - STAGE_ORDER.indexOf(b.key));
417
+ const byStage = aggregate([...rows.values()].filter(isProjectstore), stageOf, calls).sort(
418
+ (a, b) => STAGE_ORDER.indexOf(a.key) - STAGE_ORDER.indexOf(b.key),
419
+ );
373
420
  const ps = byBucket.filter((g) => g.ps);
374
421
  const rest = byBucket.filter((g) => !g.ps);
375
422
  const psT = totals(ps);
@@ -401,12 +448,26 @@ function main() {
401
448
  buckets: byBucket.map(shape),
402
449
  stages: byStage.map(shape),
403
450
  totals: Object.fromEntries(
404
- Object.entries({ projectstore: psT, other: restT, all: allT }).map(([k, t]) => [k, {
405
- requests: t.reqs, input: t.input, cache_write: t.cacheWrite,
406
- cache_read: t.cacheRead, output: t.output, cost_usd: +t.cost.toFixed(4),
407
- }]),
451
+ Object.entries({ projectstore: psT, other: restT, all: allT }).map(([k, t]) => [
452
+ k,
453
+ {
454
+ requests: t.reqs,
455
+ input: t.input,
456
+ cache_write: t.cacheWrite,
457
+ cache_read: t.cacheRead,
458
+ output: t.output,
459
+ cost_usd: +t.cost.toFixed(4),
460
+ },
461
+ ]),
408
462
  ),
409
- ...(opts.runs ? { agent_runs: aggregate([...rows.values()].filter((r) => r.run), (r) => r.run).map(shape) } : {}),
463
+ ...(opts.runs
464
+ ? {
465
+ agent_runs: aggregate(
466
+ [...rows.values()].filter((r) => r.run),
467
+ (r) => r.run,
468
+ ).map(shape),
469
+ }
470
+ : {}),
410
471
  ...(opts.sessions ? { by_session: aggregate(rows, (r) => r.session, calls).map(shape) } : {}),
411
472
  },
412
473
  null,
@@ -438,10 +499,27 @@ function main() {
438
499
  if (unpriced.size) out.push(`⚠ unpriced models (cost counted as $0): ${[...unpriced].join(", ")}`);
439
500
 
440
501
  if (opts.runs) {
441
- out.push("", "per agent run:", table(aggregate([...rows.values()].filter((r) => r.run), (r) => r.run), "run"));
502
+ out.push(
503
+ "",
504
+ "per agent run:",
505
+ table(
506
+ aggregate(
507
+ [...rows.values()].filter((r) => r.run),
508
+ (r) => r.run,
509
+ ),
510
+ "run",
511
+ ),
512
+ );
442
513
  }
443
514
  if (opts.sessions) {
444
- out.push("", table(aggregate(rows, (r) => r.session, calls), "session", { runs: true }));
515
+ out.push(
516
+ "",
517
+ table(
518
+ aggregate(rows, (r) => r.session, calls),
519
+ "session",
520
+ { runs: true },
521
+ ),
522
+ );
445
523
  }
446
524
  process.stdout.write(out.join("\n") + "\n");
447
525
  }
@@ -4,7 +4,9 @@
4
4
  // Called by BOTH the PreToolUse and PostToolUse hooks, and gated on which:
5
5
  // a write inside the vault fires both events, so without the gate the pointer
6
6
  // patch below would run twice per call — and that patch is the unguarded
7
- // read-modify-write the entry-rule state deliberately avoids.
7
+ // read-modify-write the entry-rule state deliberately avoids. A write's
8
+ // pointer patch (and the raw-edit nudge) runs on PostToolUse, from the file as
9
+ // written; any other tool's on PreToolUse (ADR-006, amended 2026-10-12).
8
10
  //
9
11
  // Responsibilities:
10
12
  // 1. Liveness — touches this session's registration file (mtime) so other
@@ -30,8 +32,7 @@
30
32
  // session_id, or on any error — a PreToolUse hook must never crash the
31
33
  // user's tool call.
32
34
 
33
- import { existsSync, readFileSync } from "node:fs";
34
- import { join } from "node:path";
35
+ import { existsSync } from "node:fs";
35
36
  import {
36
37
  readConfig,
37
38
  readStdinJson,
@@ -43,7 +44,7 @@ import {
43
44
  projectRoot,
44
45
  appendActivity,
45
46
  isInsideVault,
46
- parseFrontmatter,
47
+ pointerPatchFor,
47
48
  readSessionState,
48
49
  writeSessionState,
49
50
  isSourcePath,
@@ -61,7 +62,6 @@ import {
61
62
  loadLayout,
62
63
  anchorKeyOf,
63
64
  foldAnchor,
64
- composeAnchorName,
65
65
  bumpAnchor,
66
66
  readAnchorState,
67
67
  readAnchorOffer,
@@ -78,8 +78,9 @@ import {
78
78
  const NUDGE_INTERVAL_MS = 10 * 60 * 1000;
79
79
 
80
80
  // Per-session active pointer (ADR-006) — denormalized titles/status captured
81
- // at write time so the statusline renders with zero vault reads — plus the
82
- // raw-edit nudge (PS-IMPROVE story-003): throttled, never blocking.
81
+ // after the write so the statusline renders with zero vault reads — plus the
82
+ // raw-edit nudge (PS-IMPROVE story-003): throttled, never blocking. Both in
83
+ // patchPointer below.
83
84
  // The session-name offer (ADR: the settled-anchor offer). Returns a line or
84
85
  // null. Separate from the pointer patch because the two answer different
85
86
  // questions — the pointer is "what is current", this is "has the session
@@ -91,7 +92,7 @@ function layoutOnce(cfg) {
91
92
  }
92
93
 
93
94
  function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir = null) {
94
- // The two gates. The pointer patch above deliberately has neither: it answers
95
+ // The two gates. The pointer patch below deliberately has neither: it answers
95
96
  // "what am I looking at", for which a Read is a fine answer. A NAME is a
96
97
  // claim about what the session is DOING, so a review session that greps
97
98
  // thirty files must not be named after them, and a subagent — which shares
@@ -103,8 +104,12 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
103
104
  if (!speakingHarness()?.capabilities?.session_rename) return null;
104
105
 
105
106
  const rel = filePath.slice(cfg.vault_path.length + 1);
106
- let hit = null;
107
- try { hit = anchorKeyOf(rel, layoutOnce(cfg)); } catch { return null; }
107
+ let hit;
108
+ try {
109
+ hit = anchorKeyOf(rel, layoutOnce(cfg));
110
+ } catch {
111
+ return null;
112
+ }
108
113
  if (!hit) return null;
109
114
 
110
115
  // Both slots: the key tally is what settles an anchor, the leaf tally only
@@ -124,8 +129,7 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
124
129
  if (hit.leaf && leaves[hit.key] && leaves[hit.key][hit.leaf]) {
125
130
  leaves[hit.key] = { ...leaves[hit.key], [hit.leaf]: leaves[hit.key][hit.leaf] - 1 };
126
131
  }
127
- const { state, offer } = foldAnchor(
128
- { counts, leaves, incumbent: prev.incumbent, offered: prev.offered }, hit);
132
+ const { state, offer } = foldAnchor({ counts, leaves, incumbent: prev.incumbent, offered: prev.offered }, hit);
129
133
  if (!offer) return null;
130
134
 
131
135
  const rec = readAnchorOffer(proj, sid);
@@ -137,10 +141,10 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
137
141
  // classified as a deliberate choice and nothing was ever spoken again.
138
142
  // A name is the person's only if we have spoken at least once and it is none
139
143
  // of the names we composed.
140
- const declined = current && rec.offers.length > 0 && !rec.offers.includes(current)
141
- && !rec.declined.includes(current)
142
- ? [...rec.declined, current]
143
- : rec.declined;
144
+ const declined =
145
+ current && rec.offers.length > 0 && !rec.offers.includes(current) && !rec.declined.includes(current)
146
+ ? [...rec.declined, current]
147
+ : rec.declined;
144
148
 
145
149
  const chosen = sessionNameOffer(offer.name, {
146
150
  peers: liveSessionNames(sid, sessionsDir),
@@ -160,43 +164,36 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
160
164
  if (!chosen) return null;
161
165
  try {
162
166
  appendEntryLog(proj, {
163
- at: new Date().toISOString(), session_id: sid, kind: "name-offer", name: chosen.name,
167
+ at: new Date().toISOString(),
168
+ session_id: sid,
169
+ kind: "name-offer",
170
+ name: chosen.name,
164
171
  });
165
172
  } catch {}
166
173
  return sessionNameOfferText(chosen);
167
174
  }
168
175
 
169
- function updatePointerAndNudge(cfg, proj, sid, filePath, toolName) {
170
- const rel = filePath.slice(cfg.vault_path.length + 1);
176
+ // The pointer for one call: what its vault files say about this session's epic
177
+ // and story (pointerPatchFor), merged in path order, plus the raw-edit
178
+ // nudge's throttle for a write. One writeSessionState per call — it is an
179
+ // unlocked read-modify-write. A write tool's patch is made on PostToolUse,
180
+ // from the files as written: made before the write, it recorded the story's
181
+ // old status, and a close is the last touch a story gets (ADR-006 decision 1,
182
+ // amended 2026-10-12). Any other tool's (a Read) is made on PreToolUse.
183
+ // Returns the nudge's line, or null.
184
+ function patchPointer(cfg, proj, sid, vaultPaths, toolName) {
185
+ const cur = readSessionState(proj, sid) || {};
171
186
  let patch = null;
172
-
173
- const m = rel.match(/^epics\/([^/]+)\//);
174
- if (m) {
175
- const epicId = m[1];
176
- patch = { active_epic: epicId };
177
- try {
178
- const { data } = parseFrontmatter(
179
- readFileSync(join(cfg.vault_path, "epics", epicId, "epic.md"), "utf8"));
180
- if (data.title) patch.epic_title = String(data.title);
181
- } catch {}
182
- const sm = rel.match(/^epics\/[^/]+\/stories\/([^/]+\.md)$/);
183
- if (sm) {
184
- patch.active_story = sm[1].replace(/\.md$/, "");
185
- try {
186
- const { data } = parseFrontmatter(readFileSync(filePath, "utf8"));
187
- if (data.title) patch.story_title = String(data.title);
188
- if (data.status) patch.story_status = String(data.status);
189
- } catch {}
190
- }
187
+ for (const filePath of vaultPaths) {
188
+ const p = pointerPatchFor(cfg.vault_path, filePath, { ...cur, ...patch });
189
+ if (p) patch = { ...(patch || {}), ...p };
191
190
  }
192
191
 
193
192
  let nudge = null;
194
193
  if (isWriteTool(toolName || "") && cfg.guard !== "off") {
195
- const st = readSessionState(proj, sid);
196
- const last = st && st.nudged_at ? Date.parse(st.nudged_at) : 0;
194
+ const last = cur.nudged_at ? Date.parse(cur.nudged_at) : 0;
197
195
  if (Date.now() - last > NUDGE_INTERVAL_MS) {
198
- nudge =
199
- `projectstore: vault file edited directly — if this bypassed a ${commandForm("*")} command, run ${commandForm("reconcile")} (or doctor) afterwards so the board/indexes stay in sync.`;
196
+ nudge = `projectstore: vault file edited directly — if this bypassed a ${commandForm("*")} command, run ${commandForm("reconcile")} (or doctor) afterwards so the board/indexes stay in sync.`;
200
197
  patch = { ...(patch || {}), nudged_at: new Date().toISOString() };
201
198
  }
202
199
  }
@@ -205,8 +202,13 @@ function updatePointerAndNudge(cfg, proj, sid, filePath, toolName) {
205
202
  return nudge;
206
203
  }
207
204
 
205
+ // entryBranch's answer when the open-story sweep ran out of time: the caller
206
+ // exits once its own output is flushed (see there).
207
+ const UNKNOWN = Symbol("unknown");
208
+
208
209
  // The source-side branch (PostToolUse). Never throws: every failure here must
209
- // leave the user's tool call untouched.
210
+ // leave the user's tool call untouched. Returns the reminder's text, UNKNOWN,
211
+ // or nothing; the caller emits, so the reminder and the nudge share one line.
210
212
  async function entryBranch(cfg, proj, sid, filePath, input) {
211
213
  // Writes only. extractToolPath happily yields a path for Read, Grep, Glob and
212
214
  // LS — all of which carry file_path or path — so without this gate three
@@ -247,25 +249,28 @@ async function entryBranch(cfg, proj, sid, filePath, input) {
247
249
  verdict = await resolveOpenStory(cfg.vault_path);
248
250
  writeOpenStoryCache(proj, sid, verdict);
249
251
  }
250
- if (verdict === "unknown") {
251
- // Reached either from a fresh sweep that hit its budget with reads still
252
- // outstanding (the event loop would keep this hook alive until they settle)
253
- // or from a cached unknown, where nothing is outstanding and the exit is
254
- // merely redundant. Exiting is safe here and only here: an unknown verdict suppresses the reminder, so stdout is
255
- // untouched — process.exit does not flush pending pipe writes, and exiting
256
- // after emitting would truncate the reminder.
257
- process.exit(0);
258
- }
252
+ // Reached either from a fresh sweep that hit its budget with reads still
253
+ // outstanding (the event loop would keep this hook alive until they settle)
254
+ // or from a cached unknown, where nothing is outstanding and the exit is
255
+ // merely redundant. The caller exits — after flushing anything it has to say,
256
+ // since process.exit does not flush pending pipe writes. An unknown verdict
257
+ // suppresses the reminder.
258
+ if (verdict === "unknown") return UNKNOWN;
259
259
  if (verdict !== false) return;
260
260
 
261
261
  if (!electEmitter(proj, sid)) return;
262
262
  appendEntryLog(proj, { at: new Date().toISOString(), session_id: sid, score });
263
- process.stdout.write(JSON.stringify({
264
- hookSpecificOutput: {
265
- hookEventName: "PostToolUse",
266
- additionalContext: entryReminderText(score),
267
- },
268
- }) + "\n");
263
+ return entryReminderText(score);
264
+ }
265
+
266
+ // PostToolUse's one line: the nudge as a systemMessage, the entry reminder as
267
+ // the event's additionalContext. Null when there is nothing to say.
268
+ function postToolUseLine(messages, context) {
269
+ if (!messages.length && !context) return null;
270
+ const out = {};
271
+ if (messages.length) out.systemMessage = [...new Set(messages)].join("\n");
272
+ if (context) out.hookSpecificOutput = { hookEventName: "PostToolUse", additionalContext: context };
273
+ return JSON.stringify(out) + "\n";
269
274
  }
270
275
 
271
276
  async function main() {
@@ -307,28 +312,62 @@ async function main() {
307
312
  const filePaths = toolPaths(input);
308
313
  if (!filePaths.length) return;
309
314
 
315
+ const vaultPaths = filePaths.filter((p) => isInsideVault(p, cfg.vault_path));
316
+ const writes = isWriteTool(input.tool_name || "");
317
+
310
318
  if (event === "PostToolUse") {
311
- for (const filePath of filePaths) await entryBranch(cfg, proj, sid, filePath, input);
319
+ const messages = [];
320
+ // The same narrowing as entryBranch's: only "an object with success ===
321
+ // false" is a failed call; every other shape passes.
322
+ const response = input.tool_response;
323
+ const failed = response && typeof response === "object" && response.success === false;
324
+ if (writes && !failed && vaultPaths.length) {
325
+ try {
326
+ const nudge = patchPointer(cfg, proj, sid, vaultPaths, input.tool_name);
327
+ if (nudge) messages.push(nudge);
328
+ } catch {}
329
+ }
330
+ let context = null;
331
+ let unknown = false;
332
+ for (const filePath of filePaths) {
333
+ const said = await entryBranch(cfg, proj, sid, filePath, input);
334
+ if (said === UNKNOWN) {
335
+ unknown = true;
336
+ break;
337
+ }
338
+ if (said) context = said;
339
+ }
340
+ const line = postToolUseLine(messages, context);
341
+ if (line) process.stdout.write(line, () => unknown && process.exit(0));
342
+ else if (unknown) process.exit(0);
312
343
  return;
313
344
  }
314
345
 
315
346
  const messages = [];
316
- for (const filePath of filePaths) if (isInsideVault(filePath, cfg.vault_path)) {
317
- try { appendActivity(cfg.vault_path, sid, filePath, input.tool_name); } catch {}
318
- let nudge = null, offer = null;
319
- try { nudge = updatePointerAndNudge(cfg, proj, sid, filePath, input.tool_name); } catch {}
347
+ // A Read's pointer patch; a write's waits for PostToolUse (patchPointer).
348
+ if (!writes && vaultPaths.length) {
349
+ try {
350
+ patchPointer(cfg, proj, sid, vaultPaths, input.tool_name);
351
+ } catch {}
352
+ }
353
+ for (const filePath of vaultPaths) {
354
+ try {
355
+ appendActivity(cfg.vault_path, sid, filePath, input.tool_name);
356
+ } catch {}
320
357
  if (cfg.guard !== "off") {
321
358
  try {
322
- offer = anchorOffer(cfg, proj, sid, filePath, input.tool_name,
359
+ const offer = anchorOffer(
360
+ cfg,
361
+ proj,
362
+ sid,
363
+ filePath,
364
+ input.tool_name,
323
365
  Boolean(input.agent_id || input.agent_type),
324
- process.env.PROJECTSTORE_SESSIONS_DIR || null);
366
+ process.env.PROJECTSTORE_SESSIONS_DIR || null,
367
+ );
368
+ if (offer) messages.push(offer);
325
369
  } catch {}
326
370
  }
327
- // One invocation carries one systemMessage, so the two compose rather than
328
- // race: emitting twice would silently drop whichever went second, and the
329
- // offer fires once or twice a session against a nudge that fires every ten
330
- // minutes — the rare one would be the one lost.
331
- messages.push(...[nudge, offer].filter(Boolean));
332
371
  }
333
372
  if (messages.length) {
334
373
  process.stdout.write(JSON.stringify({ systemMessage: [...new Set(messages)].join("\n") }) + "\n");