projectstore-claude 0.30.4 → 0.30.6

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 (50) hide show
  1. package/node_modules/projectstore/.claude-plugin/marketplace.json +2 -2
  2. package/node_modules/projectstore/.claude-plugin/plugin.json +6 -2
  3. package/node_modules/projectstore/.mcp.json +1 -2
  4. package/node_modules/projectstore/README.md +65 -16
  5. package/node_modules/projectstore/agents/archaeologist.md +1 -1
  6. package/node_modules/projectstore/agents/librarian.md +1 -1
  7. package/node_modules/projectstore/agents/planner.md +1 -1
  8. package/node_modules/projectstore/commands/doctor.md +14 -11
  9. package/node_modules/projectstore/commands/reconcile.md +1 -1
  10. package/node_modules/projectstore/commands/review.md +2 -2
  11. package/node_modules/projectstore/commands/story.md +1 -1
  12. package/node_modules/projectstore/docs/getting-started.md +3 -4
  13. package/node_modules/projectstore/docs/harnesses.md +1 -1
  14. package/node_modules/projectstore/docs/how-it-works.md +7 -0
  15. package/node_modules/projectstore/docs/images/icon.png +0 -0
  16. package/node_modules/projectstore/harnesses/claude-code.json +61 -11
  17. package/node_modules/projectstore/harnesses/codex.json +45 -15
  18. package/node_modules/projectstore/hooks/band.tsx +19 -8
  19. package/node_modules/projectstore/hooks/hooks.json +6 -6
  20. package/node_modules/projectstore/hooks/session-start.mjs +55 -24
  21. package/node_modules/projectstore/hooks/session-stop.mjs +43 -20
  22. package/node_modules/projectstore/package.json +11 -12
  23. package/node_modules/projectstore/scripts/band-shared.mjs +17 -2
  24. package/node_modules/projectstore/scripts/band.mjs +20 -2
  25. package/node_modules/projectstore/scripts/binding.mjs +1 -1
  26. package/node_modules/projectstore/scripts/build-adapters.mjs +45 -4
  27. package/node_modules/projectstore/scripts/cli.mjs +74 -1373
  28. package/node_modules/projectstore/scripts/convergence.mjs +59 -16
  29. package/node_modules/projectstore/scripts/doctor.mjs +199 -36
  30. package/node_modules/projectstore/scripts/harness.mjs +88 -6
  31. package/node_modules/projectstore/scripts/install-handlers.mjs +925 -0
  32. package/node_modules/projectstore/scripts/install-harness.mjs +129 -2081
  33. package/node_modules/projectstore/scripts/install-layout.mjs +453 -0
  34. package/node_modules/projectstore/scripts/install-preview.mjs +747 -0
  35. package/node_modules/projectstore/scripts/lib.mjs +387 -107
  36. package/node_modules/projectstore/scripts/mcp-server.mjs +33 -0
  37. package/node_modules/projectstore/scripts/mcp.mjs +60 -60
  38. package/node_modules/projectstore/scripts/model-spec.mjs +24 -0
  39. package/node_modules/projectstore/scripts/models.mjs +6 -10
  40. package/node_modules/projectstore/scripts/query.mjs +7 -6
  41. package/node_modules/projectstore/scripts/read-verbs.mjs +277 -0
  42. package/node_modules/projectstore/scripts/setup.mjs +62 -12
  43. package/node_modules/projectstore/scripts/statusline-launcher.mjs +36 -3
  44. package/node_modules/projectstore/scripts/surfaces.mjs +18 -5
  45. package/node_modules/projectstore/scripts/touch-session.mjs +30 -15
  46. package/node_modules/projectstore/scripts/verbs.mjs +1202 -0
  47. package/node_modules/projectstore/scripts/version-guard.mjs +57 -7
  48. package/package.json +3 -3
  49. package/node_modules/projectstore/docs/images/loop-light.svg +0 -94
  50. package/node_modules/projectstore/docs/images/team-light.svg +0 -79
@@ -64,7 +64,16 @@ import {
64
64
  languageNames,
65
65
  } from "./binding.mjs";
66
66
  import { analyseRegistration, analyseJsonEntry } from "./surfaces.mjs";
67
- import { runningCopies, coreCommand, channelChoices, pinFor, terminalRun } from "./convergence.mjs";
67
+ import {
68
+ runningCopies,
69
+ coreCommand,
70
+ channelChoices,
71
+ pinFor,
72
+ terminalRun,
73
+ directoryConsequence,
74
+ directoryKeepConsequence,
75
+ DIRECTORY,
76
+ } from "./convergence.mjs";
68
77
  import { runVerb, isInteractive, gateText, channelText, publicItem, planOptions } from "./install-harness.mjs";
69
78
  import { resolveBinding } from "./worktree.mjs";
70
79
  import * as term from "./term.mjs";
@@ -82,6 +91,13 @@ export const TITLES = Object.freeze({
82
91
  export const CHANNEL_TEXT =
83
92
  "This project loads projectstore from the git marketplace (updated by /plugin). Switch this project to the npm install, or keep the git marketplace?";
84
93
  export const CHANNEL_ANSWERS = Object.freeze({ npm: "Switch to npm", git: "Keep the git marketplace" });
94
+ // …and for a copy synced from claude.ai (PS-DIRECTORY, "Setup and install keep
95
+ // a directory copy…", decision 6), the question's words when that copy is the
96
+ // one this project loads: the same two answers, `git` still meaning the keep.
97
+ export const DIRECTORY_TEXT = `This project loads projectstore from ${DIRECTORY} (updated from claude.ai). Keep the directory copy, or move this project to the npm install?`;
98
+ export const DIRECTORY_ANSWERS = Object.freeze({ npm: "Move to npm", git: "Keep the directory copy" });
99
+ export const channelWords = (directory) =>
100
+ directory ? { text: DIRECTORY_TEXT, answers: DIRECTORY_ANSWERS } : { text: CHANNEL_TEXT, answers: CHANNEL_ANSWERS };
85
101
  const UNRECORDED = "nothing is recorded: this project has no binding; setup asks again once it is bound";
86
102
 
87
103
  const real = (p) => {
@@ -105,7 +121,7 @@ const surfaceOf = (m, test) =>
105
121
  Object.entries(m?.surfaces || {}).find(([k, s]) => !k.startsWith("_") && s && test(s)) || null;
106
122
  const registrationOf = (m) => surfaceOf(m, (s) => s.kind === "registration");
107
123
  // The harness whose project can switch channels: the one with a host plugin
108
- // registration (cli.mjs's switchHarness reads it the same way).
124
+ // registration (verbs.mjs's switchHarness reads it the same way).
109
125
  const hostRegistrationOf = (m) => surfaceOf(m, (s) => s.format === "host-plugin-registration");
110
126
  // The harness with a status-line slot of ours (install-harness.mjs's flagHarness).
111
127
  const statuslineOf = (m) => {
@@ -187,10 +203,15 @@ export function harnessRows({ listed, detected, presence, home = null }) {
187
203
  // table). `selected`: the copy contract 12's selection keeps, from another
188
204
  // marketplace, with the version it runs; `kept`: the binding's channel_keep;
189
205
  // `sessionCopy`: the copy the selection finds at all, for "inside a session
190
- // running the git-marketplace copy".
206
+ // running the git-marketplace copy". `directory`: the copy synced from
207
+ // claude.ai this project loads (analyseRegistration's), asked about as a git
208
+ // copy is, with the keep the default and each answer's consequence
209
+ // (PS-DIRECTORY); `display` the host's name those consequences say.
191
210
  export function decideChannel({
192
211
  inSet,
193
212
  others = [],
213
+ directory = null,
214
+ display = null,
194
215
  flag = null,
195
216
  interactive = false,
196
217
  running = null,
@@ -200,15 +221,33 @@ export function decideChannel({
200
221
  sessionCopy = null,
201
222
  }) {
202
223
  if (flag) return { asked: false, value: flag, why: "flag" };
203
- if (!inSet || !others.length) return { asked: false, value: null, why: "none" };
224
+ if (!inSet || (!others.length && !directory)) return { asked: false, value: null, why: "none" };
204
225
  if (interactive) {
205
226
  const newer = Boolean(selected?.version && running && cmpPrecedence(selected.version, running) > 0);
227
+ if (!others.length) {
228
+ const stop = newer
229
+ ? `it runs ${running} in place of ${selected.version}; if ${selected.version} is published, setup stops after these questions and names it`
230
+ : "setup and upgrade update the npm copy from now on";
231
+ return {
232
+ asked: true,
233
+ default: "git",
234
+ newer,
235
+ choices: [
236
+ {
237
+ value: "git",
238
+ label: DIRECTORY_ANSWERS.git,
239
+ reason: kept ? `kept on ${String(kept.at).slice(0, 10)}` : directoryKeepConsequence(display, directory.key),
240
+ },
241
+ { value: "npm", label: DIRECTORY_ANSWERS.npm, reason: `${directoryConsequence(display)}; ${stop}` },
242
+ ],
243
+ };
244
+ }
206
245
  const keepReason = kept
207
246
  ? `kept on ${String(kept.at).slice(0, 10)}`
208
247
  : "/plugin keeps updating it; setup refreshes this project's files through that copy";
209
248
  const switchReason = newer
210
249
  ? `switching runs ${running} in place of ${selected.version}; if ${selected.version} is published, setup stops after these questions and names it`
211
- : "setup and upgrade update it from now on; /plugin update no longer reaches this project";
250
+ : "setup and upgrade update it from now on; the git-marketplace copy's updates no longer reach this project";
212
251
  return {
213
252
  asked: true,
214
253
  default: newer || kept ? "git" : "npm",
@@ -219,7 +258,8 @@ export function decideChannel({
219
258
  ],
220
259
  };
221
260
  }
222
- if (inSession && sessionCopy?.channel === "marketplace") return { asked: false, value: "git", why: "session" };
261
+ if (inSession && ["marketplace", "synced"].includes(sessionCopy?.channel))
262
+ return { asked: false, value: "git", why: "session" };
223
263
  if (kept) return { asked: false, value: "git", why: "recorded" };
224
264
  return { asked: false, value: null, refuse: true };
225
265
  }
@@ -315,12 +355,13 @@ function factsOf(project, { env, home, root, version, interactive }) {
315
355
  const binding = readConfigAt(project);
316
356
  const channelHarness = manifests.find((m) => hostRegistrationOf(m)) || null;
317
357
  let others = [],
358
+ directory = null,
318
359
  selected = null,
319
360
  sessionCopy = null;
320
361
  if (channelHarness) {
321
362
  const [, s] = hostRegistrationOf(channelHarness);
322
- others = analyseRegistration(project, s, { root, home, harness: channelHarness, env }).others;
323
- const pick = selectCopy(home, project, { harness: channelHarness, only: "marketplace" });
363
+ ({ others, directory } = analyseRegistration(project, s, { root, home, harness: channelHarness, env }));
364
+ const pick = selectCopy(home, project, { harness: channelHarness, only: ["marketplace", "synced"] });
324
365
  // The version it runs, as the convergence story reads it (runningCopies,
325
366
  // under no channel answer: local and read-only).
326
367
  const copies = runningCopies(project, { harnesses: [channelHarness.id], root, home, env, channel: null, version });
@@ -350,6 +391,7 @@ function factsOf(project, { env, home, root, version, interactive }) {
350
391
  binding,
351
392
  channelHarness,
352
393
  others,
394
+ directory,
353
395
  selected,
354
396
  sessionCopy,
355
397
  slotHarness,
@@ -476,9 +518,12 @@ async function questions(rail, s) {
476
518
  `--channel chooses ${ch ? ch.display_name : "the host plugin"}'s channel; this run does not install ${ch ? ch.display_name : "it"}`,
477
519
  ),
478
520
  };
521
+ const words = channelWords(!f.others.length && Boolean(f.directory));
479
522
  const dc = decideChannel({
480
523
  inSet: chInSet,
481
524
  others: f.others,
525
+ directory: f.directory,
526
+ display: ch?.display_name ?? null,
482
527
  flag: flagChannel,
483
528
  interactive: Boolean(rail),
484
529
  running: version,
@@ -489,7 +534,12 @@ async function questions(rail, s) {
489
534
  });
490
535
  if (dc.refuse) {
491
536
  const blocks = channelChoices({
492
- gate: { args: { harnesses: named }, keys: f.others.map((o) => o.key), version: pinFor(root, version) },
537
+ gate: {
538
+ args: { harnesses: named },
539
+ keys: f.others.map((o) => o.key),
540
+ directory: f.directory ? [f.directory.key] : [],
541
+ version: pinFor(root, version),
542
+ },
493
543
  });
494
544
  return {
495
545
  early: refused(
@@ -507,11 +557,11 @@ async function questions(rail, s) {
507
557
  const a = await rail.select(
508
558
  TITLES.channel,
509
559
  dc.choices.map((x) => ({ ...x, reason: glyphs(x.reason) })),
510
- { default: dc.default, note: CHANNEL_TEXT },
560
+ { default: dc.default, note: words.text },
511
561
  );
512
562
  if (cancelled(a)) return CANCEL;
513
563
  channel = a;
514
- } else if (rail && dc.why === "flag") rail.answered(TITLES.channel, CHANNEL_ANSWERS[channel]);
564
+ } else if (rail && dc.why === "flag") rail.answered(TITLES.channel, words.answers[channel]);
515
565
  summary.channel = channel;
516
566
 
517
567
  // Question 4, the vault (rule 7), or --vault.
@@ -618,7 +668,7 @@ async function questions(rail, s) {
618
668
  // A keep with no binding to record it in says so (rule 6), once the vault's
619
669
  // answer has settled that there is none.
620
670
  if (rail && channel === "git" && !leaves)
621
- rail.answered(TITLES.channel, `${CHANNEL_ANSWERS.git} ${term.icon(c, "dot")} ${UNRECORDED}`);
671
+ rail.answered(TITLES.channel, `${words.answers.git} ${term.icon(c, "dot")} ${UNRECORDED}`);
622
672
 
623
673
  // Question 6, the status line (rule 9).
624
674
  const sh = f.slotHarness;
@@ -16,7 +16,7 @@
16
16
  // Never crashes: a status line that throws blanks the user's HUD, so every
17
17
  // failure path degrades to an empty line.
18
18
 
19
- import { existsSync, readFileSync, realpathSync } from "node:fs";
19
+ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
20
20
  import { join, dirname } from "node:path";
21
21
  import { homedir } from "node:os";
22
22
  import { spawnSync } from "node:child_process";
@@ -46,8 +46,8 @@ function versionKey(v) {
46
46
  // helper would mean naming a versioned path, which is the exact bug this file
47
47
  // exists to remove.
48
48
  function installedRoot() {
49
+ const claudeHome = (HOME_ENV && process.env[HOME_ENV]) || join(homedir(), ".claude");
49
50
  try {
50
- const claudeHome = (HOME_ENV && process.env[HOME_ENV]) || join(homedir(), ".claude");
51
51
  const reg = JSON.parse(readFileSync(join(claudeHome, "plugins", "installed_plugins.json"), "utf8"));
52
52
  const family = dirname(FALLBACK_ROOT); // …/<marketplace>/projectstore
53
53
  // This launcher lives at <project>/<config dir>/<runtime dir>/…: a row the
@@ -87,12 +87,45 @@ function installedRoot() {
87
87
  // this file imports whatever it picks. Same rule as installedPluginRoot().
88
88
  const pool = found.filter((f) => f.same);
89
89
  pool.sort((a, b) => b.mine - a.mine || b.at - a.at || b.v[0] - a.v[0] || b.v[1] - a.v[1] || b.v[2] - a.v[2]);
90
- return pool.length ? pool[0].p : null;
90
+ if (pool.length) return pool[0].p;
91
+ } catch {}
92
+ try {
93
+ return syncedRoot(claudeHome);
91
94
  } catch {
92
95
  return null;
93
96
  }
94
97
  }
95
98
 
99
+ // A copy Claude Code synced from claude.ai (Anthropic's directory) has no
100
+ // install record: <home>/plugins/synced/<bucket>/projectstore/, whose bucket
101
+ // may change across an update. Its family is that folder, so only a launcher
102
+ // written from a synced copy looks there; the newest version on disk wins,
103
+ // read from the copy's own plugin.json, then the most recently written. The
104
+ // folder is spelled here as installed_plugins.json is above: this file runs
105
+ // standalone and cannot read the manifest (registry.synced_dir). Gone to
106
+ // plugins/.trash/ (sync turned off), none is found, and the fallbacks below run.
107
+ // Known edge, left as is: a copy of ours installed later loads over the synced
108
+ // one in the session, while this launcher keeps rendering the synced copy until
109
+ // an install re-stamps it from the copy that loads (the family rule above).
110
+ // CLAUDE_CODE_PLUGIN_CACHE_DIR, which moves the host's whole plugins folder,
111
+ // is not read here, as it is not for installed_plugins.json: a known gap.
112
+ function syncedRoot(claudeHome) {
113
+ const dir = join(claudeHome, "plugins", "synced");
114
+ if (!FALLBACK_ROOT.replace(/\\/g, "/").startsWith(dir.replace(/\\/g, "/") + "/")) return null;
115
+ const found = [];
116
+ for (const b of readdirSync(dir)) {
117
+ const p = join(dir, b, "projectstore");
118
+ if (b.startsWith(".") || !existsSync(join(p, "scripts", "statusline.mjs"))) continue;
119
+ let v = null;
120
+ try {
121
+ v = JSON.parse(readFileSync(join(p, ".claude-plugin", "plugin.json"), "utf8")).version;
122
+ } catch {}
123
+ found.push({ p, v: versionKey(v), at: statSync(p).mtimeMs });
124
+ }
125
+ found.sort((a, b) => b.v[0] - a.v[0] || b.v[1] - a.v[1] || b.v[2] - a.v[2] || b.at - a.at);
126
+ return found.length ? found[0].p : null;
127
+ }
128
+
96
129
  // Try the installed plugin, then the root that generated this file. The second
97
130
  // attempt matters: existsSync only proves the script is there, and a truncated
98
131
  // or mid-update file throws on import — without a retry a working fallback
@@ -34,7 +34,7 @@ import {
34
34
  pluginRoot,
35
35
  renderStatusLineLauncher,
36
36
  statusLineIsOurWiring,
37
- isPluginCacheRoot,
37
+ isHostInstallRoot,
38
38
  desiredStatusLineCommand,
39
39
  findAgentsBlock,
40
40
  agentsBlockVersion,
@@ -327,7 +327,7 @@ export function analyseStampedFile(
327
327
  renderRoot,
328
328
  legacyPath: atLegacy ? legacyPath : null,
329
329
  };
330
- if (s.condition === "plugin_cache_install" && !isPluginCacheRoot(renderRoot, home)) {
330
+ if (s.condition === "plugin_cache_install" && !isHostInstallRoot(renderRoot, home)) {
331
331
  // Not produced for this installation (a dev checkout is wired directly).
332
332
  a.produced = false;
333
333
  if (!file.present) return { ...a, state: "absent" };
@@ -441,7 +441,7 @@ export function analyseRegistration(
441
441
  entryKey: id,
442
442
  pkg,
443
443
  bin: whichOnPath(s.cli?.bin || "claude", env),
444
- produced: !(s.condition === "npm_package_root" && isPluginCacheRoot(root, home)),
444
+ produced: !(s.condition === "npm_package_root" && isHostInstallRoot(root, home)),
445
445
  dir: { present: existsSync(paths.dir), manifest: null, prov: null, pkg: null, disabled: [], digestOk: null },
446
446
  known: null,
447
447
  registeredHere: null,
@@ -450,6 +450,8 @@ export function analyseRegistration(
450
450
  installPath: null,
451
451
  enabled: null,
452
452
  others: [],
453
+ synced: null,
454
+ directory: null,
453
455
  otherProjects: 0,
454
456
  writtenBy: null,
455
457
  newer: false,
@@ -503,9 +505,20 @@ export function analyseRegistration(
503
505
  // this checkout's own before a user-scope one. The convergence story's rule
504
506
  // 6 reads the same rows (lib's projectCopiesByKey), so the deferral of a
505
507
  // newer copy and the stop never disagree about its version.
506
- for (const e of projectCopiesByKey(home, projectDir)) {
507
- if (e.key !== id) a.others.push({ key: e.key, path: e.path, version: e.version });
508
+ // Never a synced copy (Anthropic's directory): Claude Code loads an enabled
509
+ // copy of ours over it, so it neither loads twice nor is ours to turn off.
510
+ const copies = projectCopiesByKey(home, projectDir);
511
+ for (const e of copies) {
512
+ if (e.key !== id && !e.synced) a.others.push({ key: e.key, path: e.path, version: e.version });
508
513
  }
514
+ // The synced copy enabled for this project, and — as `directory` — the same
515
+ // copy when it is the one Claude Code loads here: no copy of another origin
516
+ // is enabled for this project, ours included (the install spec, contract
517
+ // 21, rule 1, as amended for PS-DIRECTORY). An npm registration planned
518
+ // over `directory` shadows it; nothing turns it off.
519
+ const synced = copies.find((e) => e.synced);
520
+ a.synced = synced ? { key: synced.key, path: synced.path, version: synced.version, synced: true } : null;
521
+ a.directory = a.synced && !copies.some((e) => !e.synced) ? a.synced : null;
509
522
  a.newer = Boolean(a.dir.pkg) && cmpPrecedence(a.dir.pkg, pkg) > 0;
510
523
  // Same version, different payload: the directory's recorded digest against
511
524
  // this package's — contract 4's rung 3 (source changed) for a directory.
@@ -33,6 +33,7 @@
33
33
  // user's tool call.
34
34
 
35
35
  import { existsSync } from "node:fs";
36
+ import { isAbsolute, resolve } from "node:path";
36
37
  import {
37
38
  readConfig,
38
39
  readStdinJson,
@@ -43,7 +44,8 @@ import {
43
44
  sessionFilePath,
44
45
  projectRoot,
45
46
  appendActivity,
46
- isInsideVault,
47
+ vaultLocation,
48
+ vaultRootOf,
47
49
  pointerPatchFor,
48
50
  readSessionState,
49
51
  writeSessionState,
@@ -91,7 +93,7 @@ function layoutOnce(cfg) {
91
93
  return LAYOUT;
92
94
  }
93
95
 
94
- function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir = null) {
96
+ function anchorOffer(cfg, proj, sid, rel, toolName, isSubagent, sessionsDir = null) {
95
97
  // The two gates. The pointer patch below deliberately has neither: it answers
96
98
  // "what am I looking at", for which a Read is a fine answer. A NAME is a
97
99
  // claim about what the session is DOING, so a review session that greps
@@ -103,7 +105,6 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
103
105
  // tally and logs nothing for one (generation spec, contract 18).
104
106
  if (!speakingHarness()?.capabilities?.session_rename) return null;
105
107
 
106
- const rel = filePath.slice(cfg.vault_path.length + 1);
107
108
  let hit;
108
109
  try {
109
110
  hit = anchorKeyOf(rel, layoutOnce(cfg));
@@ -181,11 +182,11 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
181
182
  // old status, and a close is the last touch a story gets (ADR-006 decision 1,
182
183
  // amended 2026-10-12). Any other tool's (a Read) is made on PreToolUse.
183
184
  // Returns the nudge's line, or null.
184
- function patchPointer(cfg, proj, sid, vaultPaths, toolName) {
185
+ function patchPointer(cfg, proj, sid, placed, toolName) {
185
186
  const cur = readSessionState(proj, sid) || {};
186
187
  let patch = null;
187
- for (const filePath of vaultPaths) {
188
- const p = pointerPatchFor(cfg.vault_path, filePath, { ...cur, ...patch });
188
+ for (const { path, loc } of placed) {
189
+ const p = pointerPatchFor(cfg.vault_path, path, { ...cur, ...patch }, undefined, { loc });
189
190
  if (p) patch = { ...(patch || {}), ...p };
190
191
  }
191
192
 
@@ -193,7 +194,12 @@ function patchPointer(cfg, proj, sid, vaultPaths, toolName) {
193
194
  if (isWriteTool(toolName || "") && cfg.guard !== "off") {
194
195
  const last = cur.nudged_at ? Date.parse(cur.nudged_at) : 0;
195
196
  if (Date.now() - last > NUDGE_INTERVAL_MS) {
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.`;
197
+ // A reconcile acts on the bound vault, so an edit in a worktree's copy
198
+ // is reconciled there once it is merged, not now.
199
+ const inCopy = placed.some(({ loc }) => loc.root !== vaultRootOf(cfg.vault_path));
200
+ nudge = inCopy
201
+ ? `projectstore: vault file edited in a worktree of the vault — if this bypassed a ${commandForm("*")} command, run ${commandForm("reconcile")} in the bound vault after the merge so the board/indexes stay in sync.`
202
+ : `projectstore: vault file edited directly — if this bypassed a ${commandForm("*")} command, run ${commandForm("reconcile")} (or doctor) afterwards so the board/indexes stay in sync.`;
197
203
  patch = { ...(patch || {}), nudged_at: new Date().toISOString() };
198
204
  }
199
205
  }
@@ -246,7 +252,7 @@ async function entryBranch(cfg, proj, sid, filePath, input) {
246
252
 
247
253
  let verdict = readOpenStoryCache(proj, sid);
248
254
  if (verdict === null) {
249
- verdict = await resolveOpenStory(cfg.vault_path);
255
+ verdict = await resolveOpenStory(cfg.vault_path, { storyRoot: readSessionState(proj, sid)?.story_root });
250
256
  writeOpenStoryCache(proj, sid, verdict);
251
257
  }
252
258
  // Reached either from a fresh sweep that hit its budget with reads still
@@ -312,7 +318,16 @@ async function main() {
312
318
  const filePaths = toolPaths(input);
313
319
  if (!filePaths.length) return;
314
320
 
315
- const vaultPaths = filePaths.filter((p) => isInsideVault(p, cfg.vault_path));
321
+ // The vault side: any copy of the vault (a worktree included), with a
322
+ // relative tool path (Codex's apply_patch) taken against the payload's cwd.
323
+ // The entry rule below keeps the raw paths.
324
+ const cwd = input.cwd || proj;
325
+ const placed = [];
326
+ for (const p of filePaths) {
327
+ const abs = isAbsolute(p) ? p : resolve(cwd, p);
328
+ const loc = vaultLocation(abs, cfg.vault_path);
329
+ if (loc) placed.push({ path: abs, loc });
330
+ }
316
331
  const writes = isWriteTool(input.tool_name || "");
317
332
 
318
333
  if (event === "PostToolUse") {
@@ -321,9 +336,9 @@ async function main() {
321
336
  // false" is a failed call; every other shape passes.
322
337
  const response = input.tool_response;
323
338
  const failed = response && typeof response === "object" && response.success === false;
324
- if (writes && !failed && vaultPaths.length) {
339
+ if (writes && !failed && placed.length) {
325
340
  try {
326
- const nudge = patchPointer(cfg, proj, sid, vaultPaths, input.tool_name);
341
+ const nudge = patchPointer(cfg, proj, sid, placed, input.tool_name);
327
342
  if (nudge) messages.push(nudge);
328
343
  } catch {}
329
344
  }
@@ -345,12 +360,12 @@ async function main() {
345
360
 
346
361
  const messages = [];
347
362
  // A Read's pointer patch; a write's waits for PostToolUse (patchPointer).
348
- if (!writes && vaultPaths.length) {
363
+ if (!writes && placed.length) {
349
364
  try {
350
- patchPointer(cfg, proj, sid, vaultPaths, input.tool_name);
365
+ patchPointer(cfg, proj, sid, placed, input.tool_name);
351
366
  } catch {}
352
367
  }
353
- for (const filePath of vaultPaths) {
368
+ for (const { path: filePath, loc } of placed) {
354
369
  try {
355
370
  appendActivity(cfg.vault_path, sid, filePath, input.tool_name);
356
371
  } catch {}
@@ -360,7 +375,7 @@ async function main() {
360
375
  cfg,
361
376
  proj,
362
377
  sid,
363
- filePath,
378
+ loc.rel,
364
379
  input.tool_name,
365
380
  Boolean(input.agent_id || input.agent_type),
366
381
  process.env.PROJECTSTORE_SESSIONS_DIR || null,