projectstore-claude 0.30.3 → 0.30.5

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -19,7 +19,8 @@
 //
 // Normative: the install spec — contract 0 (exclusive vs shared), 3–4 (the
 // four states and the ladder, rungs 1′ and 1″ included), 6 (per-entry states
-// for shared files: ours-current, ours-stale, ours-absent, unparseable),
+// for shared files: ours-current, ours-stale, ours-newer — 2026-10-14 —, ours-absent,
+// unparseable),
 // 12 (current, last written by), 14 (host-managed surfaces have no state to
 // derive), 16 (a harness is in use when detected or when it has files of
 // ours). Pure node, no external deps.
@@ -37,6 +38,8 @@ import {
   desiredStatusLineCommand,
   findAgentsBlock,
   agentsBlockVersion,
+  newerBlockWords,
+  isNewerBlock,
   agentsBlockTemplatePath,
   renderAgentsBlock,
   loadLayout,
@@ -185,6 +188,15 @@ export function analyseBlock(
   a.current = withBlock.find((e) => e.file === preferred.file) || withBlock[0] || null;
   a.duplicates = withBlock.filter((e) => e !== a.current);
   if (!a.current) return { ...a, state: "ours-absent" };
+  // A marker above this copy's template is never rendered down (the install
+  // spec, contracts 4 and 6, as amended 2026-10-14). Placement still decides
+  // first (rungs B4–B6), and a block that moves, migrates or is deduplicated
+  // carries the newest block's own text; one that stays is `ours-newer`
+  // (B7), before the render is compared, so its roster is never re-rendered.
+  const newest = withBlock.reduce((n, e) => (e.block.v > n.block.v ? e : n), a.current);
+  a.newer = isNewerBlock(newest.block.v, a.version) ? newest : null;
+  const words = a.newer ? newerBlockWords(a.newer.block.v, a.version) : null;
+  const carried = a.newer ? ` with its own text (${words})` : "";
   // A block this harness CANNOT READ moves, and its target is created if it has
   // to be: that is the whole difference between a second harness arriving and a
   // preference. A block it can read moves only when the preferred file already
@@ -197,17 +209,25 @@ export function analyseBlock(
     return {
       ...a,
       state: "ours-stale",
-      reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}`,
+      reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}${carried}`,
     };
   }
   if (a.current.file !== preferred.file && preferred.present)
-    return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
+    return {
+      ...a,
+      state: "ours-stale",
+      reason: `in ${a.current.file}; install migrates it to ${preferred.file}${carried}`,
+    };
   if (a.duplicates.length)
     return {
       ...a,
       state: "ours-stale",
-      reason: `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}`,
+      reason:
+        a.newer && a.newer !== a.current
+          ? `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}, and ${a.newer.file}'s carries v${a.newer.block.v}, newer than this copy's v${a.version}: its text replaces the block in ${a.current.file}`
+          : `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}${carried}`,
     };
+  if (a.newer) return { ...a, state: "ours-newer", reason: `${words}: left as it is` };
   if (a.current.block.v === a.version && a.current.block.block === a.desired) return { ...a, state: "ours-current" };
   return {
     ...a,
@@ -223,8 +243,15 @@ export function analyseBlock(
 
 // `renderRoot` (contract 4′, two phases): the root the surface is planned
 // AGAINST — the host's install path a registration produces — when it differs
-// from the root the templates are read from. Defaults to `root`.
-export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = homedir(), renderRoot = root } = {}) {
+// from the root the templates are read from. Defaults to `root`. `harness` is
+// the one the entry is FOR: its launcher lives under its own state directory,
+// whichever harness launched this process (the install spec, contract 6, as
+// amended 2026-10-14).
+export function analyseJsonEntry(
+  projectDir,
+  s,
+  { root = pluginRoot(), home = homedir(), renderRoot = root, harness = null } = {},
+) {
   const path = join(projectDir, s.file);
   const pointer = s.marker?.pointer || "statusLine.command";
   const entryKey = pointer.split(".")[0];
@@ -263,7 +290,7 @@ export function analyseJsonEntry(projectDir, s, { root = pluginRoot(), home = ho
   a.ours =
     statusLineIsOurWiring(a.curCmd, projectDir, home, root) ||
     statusLineIsOurWiring(a.curCmd, projectDir, home, renderRoot);
-  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home).command;
+  a.desired = desiredStatusLineCommand(projectDir, renderRoot, home, harness?.id).command;
   if (!a.curEntry) return { ...a, state: "ours-absent" };
   if (!a.ours) return { ...a, state: "theirs", reason: "a status line we did not write owns the slot" };
   if (a.curCmd === a.desired) return { ...a, state: "ours-current" };
@@ -317,7 +344,7 @@ export function analyseStampedFile(
   const tpl = readText(src);
   if (!tpl.present || tpl.text === null)
     return { ...a, state: "unparseable", refusal: `the source ${s.source} is missing from the plugin at ${root}` };
-  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir);
+  const rendered = renderStatusLineLauncher(tpl.text, renderRoot, projectDir, process.env, harness);
   if (rendered === null)
     return { ...a, state: "unparseable", refusal: "the launcher template is not one this installer knows how to fill" };
   const pkg = pluginVersionAt(root, harness) || "0.0.0";
@@ -791,7 +818,7 @@ export function surfaceStates(
     const hasOurs = states.some(
       (x) =>
         (x.kind === "exclusive" && ["current", "stale"].includes(x.state)) ||
-        (x.kind === "shared" && ["ours-current", "ours-stale"].includes(x.state)),
+        (x.kind === "shared" && ["ours-current", "ours-stale", "ours-newer"].includes(x.state)),
     );
     if (detected.includes(m.id) || hasOurs) {
       out.used.push(m.id);

package/node_modules/projectstore/scripts/touch-session.mjs

@@ -33,6 +33,7 @@
 // user's tool call.
 
 import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 import {
   readConfig,
   readStdinJson,
@@ -43,7 +44,8 @@ import {
   sessionFilePath,
   projectRoot,
   appendActivity,
-  isInsideVault,
+  vaultLocation,
+  vaultRootOf,
   pointerPatchFor,
   readSessionState,
   writeSessionState,
@@ -91,7 +93,7 @@ function layoutOnce(cfg) {
   return LAYOUT;
 }
 
-function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir = null) {
+function anchorOffer(cfg, proj, sid, rel, toolName, isSubagent, sessionsDir = null) {
   // The two gates. The pointer patch below deliberately has neither: it answers
   // "what am I looking at", for which a Read is a fine answer. A NAME is a
   // 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
   // tally and logs nothing for one (generation spec, contract 18).
   if (!speakingHarness()?.capabilities?.session_rename) return null;
 
-  const rel = filePath.slice(cfg.vault_path.length + 1);
   let hit;
   try {
     hit = anchorKeyOf(rel, layoutOnce(cfg));
@@ -181,11 +182,11 @@ function anchorOffer(cfg, proj, sid, filePath, toolName, isSubagent, sessionsDir
 // old status, and a close is the last touch a story gets (ADR-006 decision 1,
 // amended 2026-10-12). Any other tool's (a Read) is made on PreToolUse.
 // Returns the nudge's line, or null.
-function patchPointer(cfg, proj, sid, vaultPaths, toolName) {
+function patchPointer(cfg, proj, sid, placed, toolName) {
   const cur = readSessionState(proj, sid) || {};
   let patch = null;
-  for (const filePath of vaultPaths) {
-    const p = pointerPatchFor(cfg.vault_path, filePath, { ...cur, ...patch });
+  for (const { path, loc } of placed) {
+    const p = pointerPatchFor(cfg.vault_path, path, { ...cur, ...patch }, undefined, { loc });
     if (p) patch = { ...(patch || {}), ...p };
   }
 
@@ -193,7 +194,12 @@ function patchPointer(cfg, proj, sid, vaultPaths, toolName) {
   if (isWriteTool(toolName || "") && cfg.guard !== "off") {
     const last = cur.nudged_at ? Date.parse(cur.nudged_at) : 0;
     if (Date.now() - last > NUDGE_INTERVAL_MS) {
-      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.`;
+      // A reconcile acts on the bound vault, so an edit in a worktree's copy
+      // is reconciled there once it is merged, not now.
+      const inCopy = placed.some(({ loc }) => loc.root !== vaultRootOf(cfg.vault_path));
+      nudge = inCopy
+        ? `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.`
+        : `projectstore: vault file edited directly — if this bypassed a ${commandForm("*")} command, run ${commandForm("reconcile")} (or doctor) afterwards so the board/indexes stay in sync.`;
       patch = { ...(patch || {}), nudged_at: new Date().toISOString() };
     }
   }
@@ -246,7 +252,7 @@ async function entryBranch(cfg, proj, sid, filePath, input) {
 
   let verdict = readOpenStoryCache(proj, sid);
   if (verdict === null) {
-    verdict = await resolveOpenStory(cfg.vault_path);
+    verdict = await resolveOpenStory(cfg.vault_path, { storyRoot: readSessionState(proj, sid)?.story_root });
     writeOpenStoryCache(proj, sid, verdict);
   }
   // Reached either from a fresh sweep that hit its budget with reads still
@@ -312,7 +318,16 @@ async function main() {
   const filePaths = toolPaths(input);
   if (!filePaths.length) return;
 
-  const vaultPaths = filePaths.filter((p) => isInsideVault(p, cfg.vault_path));
+  // The vault side: any copy of the vault (a worktree included), with a
+  // relative tool path (Codex's apply_patch) taken against the payload's cwd.
+  // The entry rule below keeps the raw paths.
+  const cwd = input.cwd || proj;
+  const placed = [];
+  for (const p of filePaths) {
+    const abs = isAbsolute(p) ? p : resolve(cwd, p);
+    const loc = vaultLocation(abs, cfg.vault_path);
+    if (loc) placed.push({ path: abs, loc });
+  }
   const writes = isWriteTool(input.tool_name || "");
 
   if (event === "PostToolUse") {
@@ -321,9 +336,9 @@ async function main() {
     // false" is a failed call; every other shape passes.
     const response = input.tool_response;
     const failed = response && typeof response === "object" && response.success === false;
-    if (writes && !failed && vaultPaths.length) {
+    if (writes && !failed && placed.length) {
       try {
-        const nudge = patchPointer(cfg, proj, sid, vaultPaths, input.tool_name);
+        const nudge = patchPointer(cfg, proj, sid, placed, input.tool_name);
         if (nudge) messages.push(nudge);
       } catch {}
     }
@@ -345,12 +360,12 @@ async function main() {
 
   const messages = [];
   // A Read's pointer patch; a write's waits for PostToolUse (patchPointer).
-  if (!writes && vaultPaths.length) {
+  if (!writes && placed.length) {
     try {
-      patchPointer(cfg, proj, sid, vaultPaths, input.tool_name);
+      patchPointer(cfg, proj, sid, placed, input.tool_name);
     } catch {}
   }
-  for (const filePath of vaultPaths) {
+  for (const { path: filePath, loc } of placed) {
     try {
       appendActivity(cfg.vault_path, sid, filePath, input.tool_name);
     } catch {}
@@ -360,7 +375,7 @@ async function main() {
           cfg,
           proj,
           sid,
-          filePath,
+          loc.rel,
           input.tool_name,
           Boolean(input.agent_id || input.agent_type),
           process.env.PROJECTSTORE_SESSIONS_DIR || null,

package/node_modules/projectstore/scripts/version-guard.mjs

@@ -16,7 +16,15 @@
 // running it before a manual publish does not, because publish #1 is not
 // tag-triggered and nothing else covers it.
 //
-// Exit 0 when everything agrees, 1 on disagreement or a malformed manifest.
+// Then, with or without --tag, that the version has its release notes
+// (PS-HARNESS: "A release tag shows on every surface…"): the file
+// packaging/release-notes/v<version>.md, headed `# v<version> — <title>`, with
+// a body. The release workflow makes the GitHub Release from that file, so a
+// version without one is refused here — in the release PR, by test.yml and
+// `npm run release:check` — rather than on the tag.
+//
+// Exit 0 when everything agrees, 1 on disagreement, a malformed manifest or
+// missing notes.
 // Output is JSON on stdout, always, so a workflow step can quote it.
 
 import { readFileSync, existsSync, readdirSync } from "node:fs";
@@ -198,6 +206,44 @@ export function checkVersions({ root = ROOT, tag = null } = {}) {
   };
 }
 
+// The release notes (PS-HARNESS: "A release tag shows on every surface…").
+// Under packaging/, which never ships: the notes are the GitHub Release's
+// source, read from the repository by the release workflow.
+export const RELEASE_NOTES_DIR = "packaging/release-notes";
+export const releaseNotesPath = (version) => `${RELEASE_NOTES_DIR}/v${version}.md`;
+
+// The heading is the release's title as GitHub shows it, `v0.30.4 — <title>`
+// (an em dash, as every release title since v0.6.0 carries), and the body is
+// what the release says. Both must be there: a heading alone is the "tagged
+// without release notes" of 0.28.0 again.
+export function checkReleaseNotes({ root = ROOT, version }) {
+  const rel = releaseNotesPath(version);
+  const refuse = (what) => ({ ok: false, error: `${rel}: ${what}`, notes: rel });
+  if (!existsSync(resolve(root, rel))) return refuse("missing — the release workflow makes the GitHub Release from it");
+  const [first = "", ...rest] = readFileSync(resolve(root, rel), "utf8").split("\n");
+  const heading = first.replace(/\r$/, "");
+  // The version the heading names, up to a space or the dash: `# v0.30.4—x`
+  // names 0.30.4 and fails the shape, not the version.
+  const named = /^# v([^\s\u2014]+)/.exec(heading)?.[1];
+  if (named !== undefined && named !== version) return refuse(`the heading names v${named}, not v${version}`);
+  const prefix = `# v${version} — `;
+  if (!heading.startsWith(prefix) || !heading.slice(prefix.length).trim())
+    return refuse(`the first line must be "# v${version} — <title>"`);
+  if (!rest.join("\n").trim()) return refuse("no body under the heading — the notes are the release's text");
+  return { ok: true, notes: rel };
+}
+
+// The whole guard: the versions, then the notes for the version they agree
+// on. `checkVersions` stays as it was, so its callers (the packaging and
+// shells contracts) keep their scratch roots without notes.
+export function runGuard({ root = ROOT, tag = null } = {}) {
+  const v = checkVersions({ root, tag });
+  if (!v.ok) return v;
+  const n = checkReleaseNotes({ root, version: v.version });
+  if (!n.ok) return { ...n, version: v.version, checked: v.checked };
+  return { ...v, notes: n.notes };
+}
+
 // Everything at the repository root that is deliberately NOT in the tarball.
 // This list is the whole point of the tree check below: `npm pack` can only
 // report what `files[]` already allows, so comparing pack output against the
@@ -303,7 +349,7 @@ async function main(argv) {
     return;
   }
 
-  const result = checkVersions({ tag });
+  const result = runGuard({ tag });
   process.stdout.write(JSON.stringify(result) + "\n");
   if (!result.ok) process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.30.3",
+  "version": "0.30.5",
   "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.30.3"
+    "projectstore": "=0.30.5"
   },
   "bundleDependencies": [
     "projectstore"