projectstore-claude 0.30.4 → 0.30.5

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.30.4",
+      "version": "0.30.5",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.30.4",
+  "version": "0.30.5",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/docs/how-it-works.md

@@ -76,6 +76,13 @@ corrupt pointer shows an error marker, never a false "no work". The renderer als
 drops a `.last-render.json` breadcrumb so `doctor` can detect session-id
 divergence between the status line process and the hooks.
 
+A session that works the vault through **git worktrees** — a `.worktrees/x/`
+folder inside it, or a checkout elsewhere — gets the same pointer: the hooks
+recognise any worktree of the vault's repository by reading git's own files, and
+the pointer remembers which copy the story lives in, so the band and the status
+line read the story there until it is merged and closed on the bound vault.
+Edits made through the shell are not seen; a Read of the story sets the pointer.
+
 ## Surviving `/compact`
 
 Continuity across a compaction is delivered by **SessionStart**, not by

package/node_modules/projectstore/harnesses/claude-code.json

@@ -115,7 +115,7 @@
     "_root_placeholder_literal_comment": "true = the harness passes the placeholder through as literal text and the installer must substitute an absolute path; false = the harness expands it. Claude Code expands ${CLAUDE_PLUGIN_ROOT}, so false. Measured value for Codex comes from the spike."
   },
   "output_channels": {
-    "_comment": "Per-event output channels (generation spec, contract 17). `fields` are the hookSpecificOutput keys the event honours; `system_message` is the top-level systemMessage; `decision` names the decision object where one exists. `evidence` is `measured` only where this repository's own hooks observe the fact, `documented` where the Claude Code hooks reference says so and we never emit it.",
+    "_comment": "Per-event output channels (generation spec, contract 17). `fields` are the hookSpecificOutput keys the event honours; `system_message` is the top-level systemMessage; `decision` names the decision object where one exists; an optional `input_fields` lists the stdin keys; Stop's `carrier` is the shape the entry reminder's Stop carrier prints (additionalContext | block | null) — our choice where both are honoured. `evidence` is `measured` only where this repository's own hooks observe the fact, `documented` where the Claude Code hooks reference says so and we never emit it.",
     "SessionStart": {
       "fields": [
         "additionalContext"
@@ -179,9 +179,10 @@
       ],
       "system_message": null,
       "decision": "block",
+      "carrier": "additionalContext",
       "evidence": "measured",
       "min_version": "2.1.163",
-      "note": "additionalContext on Stop CONTINUES the turn (2.1.163 changelog) — hooks/session-stop.mjs runs a create-then-emit election because of it. Below 2.1.163 only decision:block + reason exists."
+      "note": "additionalContext on Stop CONTINUES the turn (2.1.163 changelog) — hooks/session-stop.mjs runs a create-then-emit election because of it. Below 2.1.163 only decision:block + reason exists. Both shapes are honoured here; the carrier is context, so the reminder reads as context, not as a new turn."
     },
     "SubagentStop": {
       "fields": [

package/node_modules/projectstore/harnesses/codex.json

@@ -29,7 +29,7 @@
     ],
     "shared_env_reason": "Codex sets Claude Code's plugin-root names too, for compatibility — measured in every one of the 759 captured hook payloads. Without declaring them, a Codex session scores a strong detection hit for claude-code, ties with codex, and loses the tie to manifest filename order. A variable two harnesses both set identifies neither, so these are demoted to weak for every manifest (generation spec, contract 1, amended 2026-09-08).",
     "session_env": [],
-    "session_env_reason": "Deliberately empty, though measured. Codex's exec tool sets CODEX_THREAD_ID and CODEX_SESSION_ID in every command (measured 2026-10-05, codex-cli 0.160.0; CODEX_SANDBOX* depend on the sandbox mode), and CODEX_HOME never appeared in a hook environment. Declaring them would identify a session, but session_env also defers the registration and the layout move inside a session (insideHostSession), which would stop the doctor skill's upgrade --json fix from running there. Splitting identity from deferral is the question of *Codex hook contract measured in a live session* (PS-HARNESS); until then a core run from a rendered skill is identified by the shell that bundles it (generation spec, contract 18). The deferral half of that split is registration_defer_env below (the maintainer's decision of 2026-10-08).",
+    "session_env_reason": "Deliberately empty, though measured. Codex's exec tool sets CODEX_THREAD_ID and CODEX_SESSION_ID in every command (measured 2026-10-05, codex-cli 0.160.0; CODEX_SANDBOX* depend on the sandbox mode), and CODEX_HOME never appeared in a hook environment. Declaring them would identify a session, but session_env also defers the registration and the layout move inside a session (insideHostSession), which would stop the doctor skill's upgrade --json fix from running there. It stays empty, decided 2026-10-15 at the close of *Codex hook contract measured in a live session* (PS-HARNESS): a core run from a rendered skill is identified by the shell that bundles it — what it prints (generation spec, contract 18) and which overlay it reads (layout spec, contract 2, as amended 2026-10-15). The deferral half of that split is registration_defer_env below (the maintainer's decision of 2026-10-08).",
     "registration_defer_env": [
       "CODEX_THREAD_ID"
     ],
@@ -72,9 +72,9 @@
     "_root_placeholder_literal_comment": "true: Codex substitutes nothing in a hook command string. It does not need to — the hook process receives PLUGIN_ROOT in its environment (measured). The generator therefore renders an absolute interpreter and an absolute script path; a bare `node` is a PATH gamble."
   },
   "output_channels": {
-    "_comment": "Per-event payload fields, captured from live firings. `fields` here are the STDIN keys the event delivers — Codex's documented output channels (additionalContext and a decision object) are not yet measured, so `decision` stays null and `system_message` null rather than false.",
+    "_comment": "Per-event channels (generation spec, contract 17, as amended 2026-10-15). `fields` are the hookSpecificOutput keys the event honours — the output side, as on every manifest; `input_fields` are the stdin keys it delivers, captured from live firings (759 on 2026-09-07/08; Run 4 of *Codex hook contract measured in a live session*, codex-cli 0.162.1, 2026-10-15, traces t1–t7). `decision` names the decision object where one exists; Stop's `carrier` is the shape the entry reminder's Stop carrier prints (additionalContext | block | null). `system_message` stays null: documented, not measured. `evidence` is about the output side.",
     "SessionStart": {
-      "fields": [
+      "input_fields": [
         "session_id",
         "transcript_path",
         "cwd",
@@ -83,13 +83,16 @@
         "permission_mode",
         "source"
       ],
+      "fields": [
+        "additionalContext"
+      ],
       "system_message": null,
       "decision": null,
       "evidence": "measured",
-      "note": "additionalContext reaches the model: asked to name the vault and count its ADRs without reading files, the model answered from the skeleton and was right."
+      "note": "additionalContext reaches the model: asked to name the vault and count its ADRs without reading files, the model answered from the skeleton and was right; Run 4 saw it as a developer-role message at `startup` and again after `compact` (t1, t2:7)."
     },
     "UserPromptSubmit": {
-      "fields": [
+      "input_fields": [
         "session_id",
         "turn_id",
         "transcript_path",
@@ -99,12 +102,16 @@
         "permission_mode",
         "prompt"
       ],
+      "fields": [
+        "additionalContext"
+      ],
       "system_message": null,
       "decision": null,
-      "evidence": "measured"
+      "evidence": "measured",
+      "note": "additionalContext reaches the model (Run 4, t1). Not registered by projectstore."
     },
     "PreToolUse": {
-      "fields": [
+      "input_fields": [
         "session_id",
         "turn_id",
         "transcript_path",
@@ -116,13 +123,16 @@
         "tool_input",
         "tool_use_id"
       ],
+      "fields": [
+        "additionalContext"
+      ],
       "system_message": null,
       "decision": null,
-      "evidence": "measured",
-      "note": "372 firings. Codex has a dedicated PermissionRequest event, so whether a decision returned from PreToolUse is honoured is unmeasured and must not be assumed."
+      "evidence": "documented",
+      "note": "input_fields measured (372 firings; Run 4 t1:3); tool_name is `apply_patch` for edits and `Bash` for shell commands. Codex has a dedicated PermissionRequest event, so whether a decision returned from PreToolUse is honoured is unmeasured and must not be assumed."
     },
     "PostToolUse": {
-      "fields": [
+      "input_fields": [
         "session_id",
         "turn_id",
         "transcript_path",
@@ -135,13 +145,16 @@
         "tool_response",
         "tool_use_id"
       ],
+      "fields": [
+        "additionalContext"
+      ],
       "system_message": null,
       "decision": null,
       "evidence": "measured",
-      "note": "371 firings. tool_response is NOT one shape: 368 strings and 3 content-block arrays (all webrun). Claude Code sends an object. Nothing may depend on it."
+      "note": "371 firings. tool_response is NOT one shape: 368 strings and 3 content-block arrays (all webrun). Claude Code sends an object. Nothing may depend on it. additionalContext reaches the model (Run 4, t1); PostToolUse does not fire for a failed apply_patch (t1:5)."
     },
     "Stop": {
-      "fields": [
+      "input_fields": [
         "session_id",
         "turn_id",
         "transcript_path",
@@ -152,12 +165,29 @@
         "stop_hook_active",
         "last_assistant_message"
       ],
+      "fields": [],
       "system_message": null,
-      "decision": null,
+      "decision": "block",
+      "carrier": "block",
       "evidence": "measured",
-      "note": "stop_hook_active is present, so hooks/session-stop.mjs's loop guard ports unchanged. last_assistant_message has no Claude Code counterpart."
+      "note": "Codex's Stop output schema denies unknown fields: hookSpecificOutput is refused with `hook: Stop Failed` (Run 4, t3c). decision:block with a reason is honoured: the reason enters the same turn as a user-role <hook_prompt> (rollout item HookPrompt), and Stop fires again with stop_hook_active true (t4:3, t4:4). In a headless `codex exec` the model's answer to it becomes the run's last message; another hook's continue:false takes precedence. last_assistant_message has no Claude Code counterpart."
     },
-    "PreCompact": null
+    "PreCompact": {
+      "input_fields": [
+        "session_id",
+        "turn_id",
+        "transcript_path",
+        "cwd",
+        "hook_event_name",
+        "model",
+        "trigger"
+      ],
+      "fields": [],
+      "system_message": null,
+      "decision": null,
+      "evidence": "documented",
+      "note": "trigger is `auto` on an automatic compaction, and PostCompact follows (Run 4, t2:5–6). No permission_mode. Whether a systemMessage reaches anyone on Codex is unmeasured."
+    }
   },
   "surfaces": {
     "agents": {

package/node_modules/projectstore/hooks/band.tsx

@@ -25,6 +25,7 @@ import {
   AGENT_PREFIX,
   LINGER_MS,
   countsText,
+  focusRoots,
   goalForms,
   goalOf,
   heartbeatFile,
@@ -98,7 +99,7 @@ type Band = {
   shownKey: string
   stories: Map<string, { sig: string } & Stories>
   shipped: Map<string, Json>
-  place: { vault: string | null; kinds: string[] }
+  place: { vault: string | null; kinds: string[]; roots: string[] }
 }
 
 function newBand(): Band {
@@ -112,7 +113,7 @@ function newBand(): Band {
     shownKey: '',
     stories: new Map(),
     shipped: new Map(),
-    place: { vault: null, kinds: [] },
+    place: { vault: null, kinds: [], roots: [] },
   }
 }
 
@@ -260,7 +261,7 @@ async function scan($: EngineInterface, b: Band, root: string, sid: string | nul
   const vault = typeof binding.vault_path === 'string' ? binding.vault_path : null
   if (!vault) return null
   const lay = await layoutOf($, b, typeof binding.layout === 'string' ? binding.layout : 'engineering')
-  b.place = { vault, kinds: lay.kinds }
+  b.place = { vault, kinds: lay.kinds, roots: [vault] }
   const band: Json = binding.band && typeof binding.band === 'object' ? binding.band : {}
   if (band.enabled === false || !lay.epics) return null
   const lang = typeof binding.language === 'string' ? binding.language : 'en'
@@ -273,14 +274,24 @@ async function scan($: EngineInterface, b: Band, root: string, sid: string | nul
   if (pointer === UNREADABLE) return null
   const own = pointer && isEpicName(pointer.active_epic) ? (pointer.active_epic as string) : null
   const pin = isEpicName(band.epic) ? (band.epic as string) : null
-  let focus: { id: string; why: 'this' | 'pinned' } | null = null
-  if (own && (await isDir($, `${vault}/${lay.epics}/${own}`))) focus = { id: own, why: 'this' }
-  else if (pin && (await isDir($, `${vault}/${lay.epics}/${pin}`))) focus = { id: pin, why: 'pinned' }
+  // This session's epic is read from the copy of the vault its story lives in
+  // (the pointer's story_root, a worktree) when that copy has the epic, else
+  // from the vault; the pin always from the vault (issue #87).
+  const roots = focusRoots(pointer as Json | null, vault)
+  b.place = { vault, kinds: lay.kinds, roots }
+  let focus: { id: string; why: 'this' | 'pinned'; base: string } | null = null
+  if (own)
+    for (const base of roots)
+      if (await isDir($, `${base}/${lay.epics}/${own}`)) {
+        focus = { id: own, why: 'this', base }
+        break
+      }
+  if (!focus && pin && (await isDir($, `${vault}/${lay.epics}/${pin}`))) focus = { id: pin, why: 'pinned', base: vault }
   if (!focus) return null
 
   // The focused epic's epic.md that cannot be read draws nothing: never the
   // pin in its place.
-  const epicDir = `${vault}/${lay.epics}/${focus.id}`
+  const epicDir = `${focus.base}/${lay.epics}/${focus.id}`
   const text = await readText($, `${epicDir}/epic.md`)
   if (text === null) return null
   const fm = parseFrontmatter(text).data as Json
@@ -594,7 +605,7 @@ export const register: Register = on => {
       try {
         const agent = (await read($, crew)).find(a => a.id === id)
         const v = agent?.status === 'running' ? await read($, view) : null
-        const step = agent?.status === 'running' && v ? stepOf(e as unknown as Json, b.place.vault, v.words) : null
+        const step = agent?.status === 'running' && v ? stepOf(e as unknown as Json, b.place.roots, v.words) : null
         if (step && (await read($, steps))[id] !== step) await update($, steps, d => ({ ...d, [id]: step }))
       } catch {
         // A step the band failed to note never holds up the tool.

package/node_modules/projectstore/hooks/session-stop.mjs

@@ -8,20 +8,31 @@
 // hands the writing to subagents — whose calls count toward the score but are
 // never the audience — and then answers the user. Stop fires exactly there.
 //
-// Two things about Stop that shape this file:
+// What Stop may print is the harness's, read from its manifest
+// (output_channels.Stop.carrier — generation spec, contract 17; entry spec,
+// contract 14, as amended 2026-10-15):
 //
-//  * `additionalContext` on Stop CONTINUES the turn. So this hook must run the
-//    same create-then-emit election as the PostToolUse branch, not merely read
-//    the markers: a guard that only checks would emit, the turn would continue,
-//    the model would finish again, Stop would fire again — forever. Creating
-//    the marker before emitting is what makes the second firing impossible.
-//  * `stop_hook_active` is set while a Stop hook is already driving the turn.
-//    Honouring it is belt and braces; the election is the load-bearing guard.
+//  * Claude Code (2.1.163+) honours `additionalContext` on Stop, and it
+//    CONTINUES the turn: the reminder arrives as context.
+//  * Codex refuses `hookSpecificOutput` on Stop — its Stop schema denies
+//    unknown fields, and the hook reads `Failed` — and honours only a block
+//    decision, whose reason enters the same turn as a user-role hook prompt
+//    (measured 2026-10-15, codex-cli 0.162.1).
+//  * The carrier comes from the harness that IDENTIFIES itself (forced, a
+//    parent's decision, a strong signal or a session marker); nothing
+//    identified, or no carrier measured, is silence. It is read before the
+//    vault and before the election, so a harness that cannot carry the
+//    reminder never spends it.
+//
+// Either channel continues the turn, so the model finishes again and Stop
+// fires again. That is why this hook runs the same create-then-emit election
+// as the PostToolUse branch, not merely a read of the markers: creating the
+// marker before emitting is what makes the second firing impossible.
+// `stop_hook_active` (true on the continued Stop — measured on Codex) is belt
+// and braces; the election is the load-bearing guard.
 //
 // Not SubagentStop: it fires once per subagent and its continuation belongs to
 // the subagent, which is the actor that cannot open a story.
-//
-// Requires Claude Code 2.1.163+, where additionalContext on Stop is honoured.
 
 import {
   readConfig,
@@ -37,6 +48,8 @@ import {
   appendEntryLog,
   entryReminderText,
   ENTRY_THRESHOLD,
+  stopCarrier,
+  readSessionState,
 } from "../scripts/lib.mjs";
 
 async function main() {
@@ -46,6 +59,10 @@ async function main() {
   // — fd 0 is empty on a second read.
   const input = adoptHookInput(readStdinJson());
 
+  // Which shape this harness accepts, before anything is read or written.
+  const carrier = stopCarrier();
+  if (!carrier) return;
+
   const cfg = readConfig();
   if (!cfg || cfg.guard === "off") return;
 
@@ -62,7 +79,8 @@ async function main() {
 
   let verdict = readOpenStoryCache(proj, sid);
   if (verdict === null) {
-    verdict = await resolveOpenStory(cfg.vault_path);
+    // The session's own worktree copy counts too (its pointer's story_root).
+    verdict = await resolveOpenStory(cfg.vault_path, { storyRoot: readSessionState(proj, sid)?.story_root });
     writeOpenStoryCache(proj, sid, verdict);
   }
   // Nothing written to stdout yet, so exiting here cannot truncate anything.
@@ -70,15 +88,20 @@ async function main() {
   if (verdict !== false) return;
 
   if (!electEmitter(proj, sid)) return;
-  appendEntryLog(proj, { at: new Date().toISOString(), session_id: sid, score, via: "Stop" });
-  process.stdout.write(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: "Stop",
-        additionalContext: entryReminderText(score),
-      },
-    }) + "\n",
-  );
+  appendEntryLog(proj, { at: new Date().toISOString(), session_id: sid, score, via: "Stop", channel: carrier });
+  const text = entryReminderText(score);
+  // A block prints the bytes Codex honoured — one object, no newline (Run 4,
+  // t4); context prints what it always printed.
+  if (carrier === "block") process.stdout.write(JSON.stringify({ decision: "block", reason: text }));
+  else
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "Stop",
+          additionalContext: text,
+        },
+      }) + "\n",
+    );
 }
 
 main().catch(() => {

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.30.4",
+  "version": "0.30.5",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/band-shared.mjs

@@ -383,7 +383,21 @@ export function phraseOf(role, subject, description, w) {
 }
 
 const lastSegment = (p) => String(p).replace(/\/+$/, "").split("/").pop();
-const vaultRel = (vault, p) => (vault && p.startsWith(`${vault}/`) ? p.slice(vault.length + 1) : lastSegment(p));
+// A path inside one of the roots (a worktree's copy of the vault first, then
+// the vault) reads as its path in there; anything else as its last segment.
+const vaultRel = (roots, p) => {
+  for (const r of [].concat(roots || [])) if (r && p.startsWith(`${r}/`)) return p.slice(r.length + 1);
+  return lastSegment(p);
+};
+
+// The roots this session's paths are read against: the copy of the vault its
+// pointer's story lives in (story_root, a worktree — PS-PRESENCE, issue #87),
+// then the bound vault. The band never resolves git itself; it reads this.
+export function focusRoots(pointer, vault) {
+  const own = pointer && typeof pointer.story_root === "string" && pointer.story_root ? pointer.story_root : null;
+  if (!vault) return own ? [own] : [];
+  return own && own !== vault ? [own, vault] : [vault];
+}
 
 // `node /x/reconcile.mjs --a` reads `reconcile`, `git diff --stat` reads `git diff`.
 export function commandWord(command) {
@@ -401,7 +415,8 @@ export function commandWord(command) {
 const QUIET = /^(echo|printf|true|sleep|:)(\s|$)/;
 
 // An agent's last step from its latest tool call, or null when the call says
-// nothing worth a row (an echo, a tool the band does not name).
+// nothing worth a row (an echo, a tool the band does not name). `vault` is the
+// vault path or the roots focusRoots gives.
 export function stepOf(call, vault, w) {
   const tool = typeof call.tool === "string" ? call.tool : "";
   const path =

package/node_modules/projectstore/scripts/band.mjs

@@ -116,6 +116,9 @@ export function applyBand(plan) {
   return { wrote: true };
 }
 
+const SESSION_HINT =
+  "a Read or an edit of a story file through a file tool sets this session's epic and story; edits made through the shell are not seen";
+
 const REASONS = Object.freeze({
   harness: "this harness has no band",
   off: "switched off (projectstore band on)",
@@ -135,11 +138,20 @@ export function bandStatus(projectDir, cfg, { env = process.env, now = Date.now(
   const keys = bandKeys(cfg);
   const sessionId = hostSessionId(env, harness);
   let sessionEpic = null;
+  let sessionStory = null;
+  let sessionRoot = null;
   let heartbeat = "none";
   if (sessionId) {
     try {
       const p = JSON.parse(readFileSync(sessionStatePath(projectDir, sessionId), "utf8"));
-      if (p && isEpicName(p.active_epic)) sessionEpic = p.active_epic;
+      if (p && isEpicName(p.active_epic)) {
+        sessionEpic = p.active_epic;
+        if (typeof p.active_story === "string" && p.active_story)
+          sessionStory = typeof p.story_title === "string" && p.story_title ? p.story_title : p.active_story;
+        // The copy of the vault the story lives in, when it is a worktree's.
+        // A removed worktree is not named: the band and the refresh fall back too.
+        if (typeof p.story_root === "string" && p.story_root && existsSync(p.story_root)) sessionRoot = p.story_root;
+      }
     } catch {}
     const name = heartbeatFile(sessionId);
     if (name) {
@@ -169,6 +181,11 @@ export function bandStatus(projectDir, cfg, { env = process.env, now = Date.now(
     pin_exists: pinExists,
     session_id: sessionId,
     session_epic: sessionEpic,
+    session_story: sessionStory,
+    session_root: sessionRoot,
+    // How a session gets its epic, whenever it has none — pinned or not
+    // (issue #87 had a pin and no word on how to set its own).
+    session_hint: sessionId && !sessionEpic ? SESSION_HINT : null,
     heartbeat,
     drawing,
     yielding: drawing,
@@ -180,7 +197,8 @@ export function bandStatus(projectDir, cfg, { env = process.env, now = Date.now(
 export function renderBandStatus(s) {
   const lines = [
     `band: ${s.enabled ? "on" : "off"}${s.pin ? ` · pinned ${s.pin}${s.pin_exists ? "" : " (missing)"}` : ""}`,
-    `session: ${s.session_id ? `${s.session_id.slice(0, 8)}… · ${s.session_epic ? `epic ${s.session_epic}` : "no epic of its own"}` : "session unknown"}`,
+    `session: ${s.session_id ? `${s.session_id.slice(0, 8)}… · ${s.session_epic ? `epic ${s.session_epic}${s.session_story ? ` · story ${s.session_story}` : ""}${s.session_root ? ` · in ${s.session_root}` : ""}` : "no epic of its own"}` : "session unknown"}`,
+    ...(s.session_hint ? [`  ${s.session_hint}`] : []),
     `heartbeat: ${s.heartbeat} · the status line ${s.yielding ? "is giving way to the band" : "shows its own line"}`,
   ];
   if (s.reason_text) lines.push(`not drawing: ${s.reason_text}`);

package/node_modules/projectstore/scripts/doctor.mjs

@@ -102,6 +102,7 @@ import {
   packageCommand,
   invocation,
   harnessForOverlay,
+  activeHarness,
 } from "./harness.mjs";
 import { effortSpec } from "./models.mjs";
 
@@ -943,17 +944,22 @@ export function checkOverlays(cfg, proj, { root = pluginRoot(), home = homedir()
     // 2026-10-03 amendment, finding 7).
     const remedy = layoutRemedy(proj, { root, home });
     // The block and its move are the source harness's — a pre-0.28 binding
-    // and that harness's command — so its fact under any other listener.
+    // and that harness's command — so its fact under any other listener. The
+    // move writes the source harness's overlay, whoever listens: since the
+    // overlay follows the shell that bundles the core (layout spec, contract 2,
+    // as amended 2026-10-15), the listener's `where` would name another file.
+    const src = sourceHarness();
+    const dest = relative(proj, layoutPaths(proj).overlay(src?.runtime?.overlay || src?.id));
     out.push(
       aboutHarness(
         finding(
           "install",
           "warn",
           "agents-in-binding",
-          `${b} still carries an agents block — since 0.28 the models live in ${where} (the layout ADR); nothing reads it there. ${remedyWords(remedy, proj, "Move it")}`,
+          `${b} still carries an agents block — since 0.28 the models live in ${dest} (the layout ADR); nothing reads it there. ${remedyWords(remedy, proj, "Move it")}`,
           b,
         ),
-        sourceHarness(),
+        src,
         speaker,
       ),
     );
@@ -1362,10 +1368,15 @@ export function checkOverrideCopies(proj, home = homedir(), harness = speakingHa
 // The variable names come from the manifest (runtime.agent_overrides); the
 // overlay is read only when one is set, so a clean startup reads nothing.
 export function checkEnvEffort(proj = null) {
+  // The variable is the active harness's (agentOverrides keys on detection), so
+  // the overlay it outranks is that harness's too — not the listener's, which
+  // in a shell's tree can be another harness (layout spec, contract 2, as
+  // amended 2026-10-15).
+  const h = activeHarness();
   return agentOverrides()
     .filter((o) => o.kind === "effort")
     .map((o) => {
-      const ov = proj ? readOverlayAt(proj) : null;
+      const ov = proj ? readOverlayAt(proj, h?.runtime?.overlay || h?.id) : null;
       const set = ov
         ? [
             ...(ov.efforts.default ? ["agents.default.effort"] : []),

package/node_modules/projectstore/scripts/harness.mjs

@@ -411,6 +411,46 @@ export function activeHarness(env = process.env, dir = MANIFEST_DIR) {
   return loadHarness(detectHarnessId(env, dir), dir) || sourceHarness(dir);
 }
 
+// ─── The Stop carrier (generation spec, contract 17; entry spec, contract 14,
+// as amended 2026-10-15) ────────────────────────────────────────────────
+//
+// The shape the entry reminder's Stop carrier prints, from the manifest of the
+// harness that IDENTIFIES itself — a forced harness, a parent's decision, a
+// strong signal or a session marker. Never detection's cwd folder, weak ranking or source
+// fallback: a wrong answer here is a hook the host refuses (Codex's Stop schema
+// denies hookSpecificOutput, measured 2026-10-15), and a refused print would
+// still spend the session's reminder. Nothing identified, or no carrier
+// measured, is null: the hook stays silent.
+export const STOP_CARRIERS = Object.freeze(["additionalContext", "block"]);
+export function stopCarrier(env = process.env, dir = MANIFEST_DIR) {
+  const id = identifiedHarnessId(env, dir);
+  const carrier = id ? loadHarness(id, dir)?.output_channels?.Stop?.carrier : null;
+  return STOP_CARRIERS.includes(carrier) ? carrier : null;
+}
+
+// What is wrong with a manifest's Stop row, or null. The carrier is our choice
+// and must be one its row supports: context needs `additionalContext` among the
+// honoured fields, a block needs the block decision, and a carrier is only
+// ever chosen from a measured row. Shared by the manifest check and its
+// planted fixtures.
+export function stopCarrierProblem(manifest) {
+  const row = manifest?.output_channels?.Stop;
+  if (row === null || row === undefined) return null;
+  if (typeof row !== "object") return "output_channels.Stop is not an object";
+  if (!("carrier" in row)) return "output_channels.Stop has no carrier (null when none is measured)";
+  if (![...STOP_CARRIERS, null].includes(row.carrier))
+    return `output_channels.Stop.carrier ${JSON.stringify(row.carrier)} is not one of ${STOP_CARRIERS.join(", ")} or null`;
+  if (![null, "block"].includes(row.decision))
+    return `output_channels.Stop.decision ${JSON.stringify(row.decision)} is not null or "block"`;
+  if (row.carrier === null) return null;
+  if (row.evidence !== "measured") return "output_channels.Stop.carrier is set on a row that is not measured";
+  if (row.carrier === "additionalContext" && !(row.fields || []).includes("additionalContext"))
+    return "output_channels.Stop.carrier is additionalContext, but its fields do not honour it";
+  if (row.carrier === "block" && row.decision !== "block")
+    return 'output_channels.Stop.carrier is block, but its decision is not "block"';
+  return null;
+}
+
 // ─── Who a message is for (generation spec, contract 18) ───────────────
 //
 // The core prints for ONE harness at a time, and a command it names must be
@@ -765,9 +805,20 @@ export function shellHarnessId(env = process.env, dir = MANIFEST_DIR) {
 
 // The overlay a harness reads: <project>/.projectstore/harness/<overlay>.json —
 // the manifest's runtime.overlay, the harness id by convention (the layout ADR,
-// decision 3). Null only when no manifest at all can be found.
-export function overlayId(env = process.env, dir = MANIFEST_DIR) {
-  const h = activeHarness(env, dir);
+// decision 3). Whose (layout spec, contract 2, as amended 2026-10-15): the
+// harness that identifies itself; else the shell that bundles this core; else
+// the shell the environment names; else detectHarnessId's answer (the cwd's
+// harness folder, the weak ranking, the source harness). Contract 18's middle
+// rungs with detection's tail: a rendered skill's exec tool carries no variable
+// of its harness, and the cwd's folder would answer for it. --harness stays the
+// caller's (cli.mjs runAgents). Null only when no manifest at all can be found.
+export function overlayId(env = process.env, dir = MANIFEST_DIR, { core } = {}) {
+  const id =
+    identifiedHarnessId(env, dir) ||
+    bundlingShellHarnessId({ core, dir }) ||
+    shellHarnessId(env, dir) ||
+    detectHarnessId(env, dir);
+  const h = loadHarness(id, dir) || sourceHarness(dir);
   return h?.runtime?.overlay || h?.id || null;
 }
 

package/node_modules/projectstore/scripts/lib.mjs

@@ -24,7 +24,7 @@ import { join, dirname, basename, resolve, relative, isAbsolute } from "node:pat
 import { fileURLToPath } from "node:url";
 import { hostname, homedir } from "node:os";
 import { createHash, randomUUID } from "node:crypto";
-import { parseFrontmatter } from "./stages.mjs";
+import { parseFrontmatter, stageOf } from "./stages.mjs";
 import { storyKeyOf } from "./band-shared.mjs";
 import {
   projectRoot as harnessProjectRoot,
@@ -53,6 +53,7 @@ import {
   packageCommand,
   whichOnPath,
   hostSessionId,
+  stopCarrier,
 } from "./harness.mjs";
 
 // ─── Paths ─────────────────────────────────────────────────────────────
@@ -184,6 +185,7 @@ export {
   overlayId,
   speakingHarness,
   whichOnPath,
+  stopCarrier,
 };
 
 // A hook's payload carries the `cwd` of the session that fired it, and on a
@@ -2581,10 +2583,16 @@ export async function gatherVaultFacts(cfg, opts = {}) {
       return;
     }
     const entries = await readActivityAsync(vault, sessionId, readFile);
-    const rel = entries
-      .filter((e) => e && typeof e.path === "string" && isInsideVault(e.path, vault))
-      .map((e) => e.path.slice(vault.length + 1))
-      .filter(Boolean);
+    // Through the vault's worktrees too: a worktree's copy reads as its path
+    // inside the vault, once, newest first.
+    const rel = [
+      ...new Set(
+        entries
+          .filter((e) => e && typeof e.path === "string")
+          .map((e) => vaultLocation(e.path, vault)?.rel)
+          .filter(Boolean),
+      ),
+    ];
     continuity.paths = rel;
     continuity.total = rel.length;
     continuity.artifact = resolveInFlightArtifact(entries, layout, vault);
@@ -2983,8 +2991,10 @@ export function resolveInFlightArtifact(activity, layout, vaultPath) {
   // the newest one — no sort, and no second definition of "newest".
   for (const e of activity) {
     if (!e || !e.path || !isWriteTool(e.tool)) continue;
-    if (!isInsideVault(e.path, root)) continue;
-    const rel = e.path.slice(root.length + 1);
+    // A worktree's copy counts as the vault, by its path inside that copy.
+    const loc = vaultLocation(e.path, root);
+    if (!loc || !loc.rel) continue;
+    const rel = loc.rel;
     if (folders.some((p) => rel === p || rel.startsWith(p + "/"))) return rel;
   }
   return null;
@@ -2996,6 +3006,132 @@ export function isInsideVault(filePath, vaultPath) {
   return norm === vaultPath || norm.startsWith(vaultPath + "/");
 }
 
+// ─── Where a path sits in the vault, worktrees included ────────────────
+//
+// (PS-PRESENCE: "A session working in a worktree of the vault gets its epic
+// and story on the band…", issue #87.) A vault edited only through git
+// worktrees — `<vault>/.worktrees/x/` or a checkout elsewhere — was invisible
+// to every check that matched a prefix on vault_path. vaultLocation answers
+// `{ root, rel }`: the copy of the vault that holds the file (the bound
+// checkout, or a worktree's copy) and the path inside it; null when the file
+// is not in the vault.
+//
+// The prefix still answers first and is never taken away: a path under
+// vault_path is in the vault as today, nested foreign repositories included.
+// The resolver only ADDS placements, by reading git's own files on disk — it
+// runs on every tool call, so it spawns nothing:
+//  * a `.git` directory is its own common dir;
+//  * a `.git` file says `gitdir: <path>` (relative to the file's directory for
+//    submodules and worktree.useRelativePaths); the gitdir's `commondir`
+//    (relative to the gitdir) names the common dir, and without one — a
+//    --separate-git-dir checkout, a submodule — the gitdir is the common dir;
+//  * both sides go through realpath: git writes /private/tmp where a vault may
+//    be bound as /tmp or through a symlink.
+// A worktree belongs to the vault when its common dir is the vault's AND the
+// file lies under the worktree's copy of the vault's place in its repository
+// (`vaultSub`): a vault kept as a folder of the project's repository shares
+// the project's common dir, and a project worktree's src/ is not the vault.
+// Anything unreadable answers with the prefix alone.
+
+const VAULT_REPO = new Map();
+export function resetVaultLocation() {
+  VAULT_REPO.clear();
+}
+
+function gitIdentity(entry) {
+  try {
+    if (statSync(entry).isDirectory()) {
+      const real = realpathSync(entry);
+      return { gitdir: real, common: real };
+    }
+    const m = readFileSync(entry, "utf8").match(/^gitdir:\s*(.+?)\s*$/m);
+    if (!m) return null;
+    const gitdir = resolve(dirname(entry), m[1]);
+    let common = gitdir;
+    try {
+      common = resolve(gitdir, readFileSync(join(gitdir, "commondir"), "utf8").trim());
+    } catch {}
+    return { gitdir: realpathSync(gitdir), common: realpathSync(common) };
+  } catch {
+    return null;
+  }
+}
+
+// The nearest directory at or above `start` holding a `.git` entry; with
+// `below`, only directories strictly inside it are considered.
+function nearestGit(start, below = null) {
+  let d = start;
+  for (;;) {
+    if (below !== null && !d.startsWith(below + "/")) return null;
+    if (existsSync(join(d, ".git"))) return d;
+    const up = dirname(d);
+    if (up === d) return null;
+    d = up;
+  }
+}
+
+function vaultRepo(vault) {
+  if (VAULT_REPO.has(vault)) return VAULT_REPO.get(vault);
+  let out = null;
+  try {
+    const real = realpathSync(vault);
+    const top = nearestGit(real);
+    const id = top ? gitIdentity(join(top, ".git")) : null;
+    if (id) out = { ...id, sub: real === top ? "" : real.slice(top.length + 1) };
+  } catch {}
+  VAULT_REPO.set(vault, out);
+  return out;
+}
+
+// The bound vault's path as the resolver compares it: no trailing slash (a
+// hand-edited binding may carry one).
+export function vaultRootOf(vaultPath) {
+  return vaultPath && vaultPath.length > 1 ? vaultPath.replace(/\/+$/, "") : vaultPath;
+}
+
+export function vaultLocation(filePath, vaultPath, { cwd } = {}) {
+  if (!filePath || !vaultPath) return null;
+  const vault = vaultRootOf(vaultPath);
+  // resolve() also folds `//` and `..`, so a root is always a clean path.
+  const norm = resolve(cwd || process.cwd(), filePath);
+  const under = (p, root) => p === root || p.startsWith(root + "/");
+  const relOf = (p, root) => (p === root ? "" : p.slice(root.length + 1));
+  const copyOf = (top, repo) => (repo.sub ? join(top, repo.sub) : top);
+
+  if (under(norm, vault)) {
+    // A worktree kept inside the vault folder answers for its own copy.
+    const top = nearestGit(dirname(norm), vault);
+    if (top) {
+      const repo = vaultRepo(vault);
+      const id = repo ? gitIdentity(join(top, ".git")) : null;
+      if (id && id.common === repo.common && id.gitdir !== repo.gitdir) {
+        const root = copyOf(top, repo);
+        if (under(norm, root)) return { root, rel: relOf(norm, root) };
+      }
+    }
+    return { root: vault, rel: relOf(norm, vault) };
+  }
+
+  // Outside the prefix: a new file's walk starts at its nearest existing parent.
+  let start = dirname(norm);
+  while (!existsSync(start)) {
+    const up = dirname(start);
+    if (up === start) return null;
+    start = up;
+  }
+  const top = nearestGit(start);
+  if (!top) return null;
+  const repo = vaultRepo(vault);
+  if (!repo) return null;
+  const id = gitIdentity(join(top, ".git"));
+  if (!id || id.common !== repo.common) return null;
+  const root = copyOf(top, repo);
+  if (!under(norm, root)) return null;
+  // The bound checkout spelled another way (/private/var for /var, a symlink).
+  if (id.gitdir === repo.gitdir) return { root: vault, rel: relOf(norm, root) };
+  return { root, rel: relOf(norm, root) };
+}
+
 // ─── Per-session project-side state (statusline pointer — ADR-006) ─────
 //
 // <project>/.claude/.projectstore/state/<session_id>.json holds this
@@ -3094,13 +3230,29 @@ export function writeSessionState(projectDir, sessionId, patch) {
 // written as null (every reader treats it as absent): a touch of another
 // epic clears the previous epic's story, and an unreadable story names no
 // stale title. Null when the file is not under an epic.
-export function pointerPatchFor(vaultPath, filePath, cur, read = (p) => readFileSync(p, "utf8")) {
-  const m = filePath.slice(vaultPath.length + 1).match(/^epics\/([^/]+)\/(.+)$/);
+//
+// The file may sit in a worktree of the vault (vaultLocation): the epic is
+// matched on its path inside that copy, epic.md is read from the same copy,
+// and `story_root` records the copy — null for the bound checkout — so the
+// band and SessionStart's refresh read the story where it lives. It is written
+// with the story fields: on a story touch, or when the epic changes. A touch
+// of the same epic's other files (reading the bound checkout's epic.md for
+// its goal) leaves it, or the band would look for the story where it is not.
+export function pointerPatchFor(
+  vaultPath,
+  filePath,
+  cur,
+  read = (p) => readFileSync(p, "utf8"),
+  { loc = vaultLocation(filePath, vaultPath) } = {},
+) {
+  if (!loc) return null;
+  const m = loc.rel.match(/^epics\/([^/]+)\/(.+)$/);
   if (!m) return null;
   const [, epicId, inEpic] = m;
+  const storyRoot = loc.root === vaultRootOf(vaultPath) ? null : loc.root;
   const patch = { active_epic: epicId };
   try {
-    const { data } = parseFrontmatter(read(join(vaultPath, "epics", epicId, "epic.md")));
+    const { data } = parseFrontmatter(read(join(loc.root, "epics", epicId, "epic.md")));
     if (data.title) patch.epic_title = String(data.title);
   } catch {}
   const key = storyKeyOf(inEpic);
@@ -3112,8 +3264,9 @@ export function pointerPatchFor(vaultPath, filePath, cur, read = (p) => readFile
     patch.active_story = key;
     patch.story_title = data && data.title ? String(data.title) : null;
     patch.story_status = data && data.status ? String(data.status) : null;
+    patch.story_root = storyRoot;
   } else if (!cur || cur.active_epic !== epicId) {
-    Object.assign(patch, { active_story: null, story_title: null, story_status: null });
+    Object.assign(patch, { active_story: null, story_title: null, story_status: null, story_root: storyRoot });
   }
   return patch;
 }
@@ -3140,12 +3293,14 @@ export function storyFileFor(vaultPath, epicId, key) {
 export function refreshSessionPointer(projectDir, cfg, path, { env = process.env } = {}) {
   const vault = cfg.vault_path;
   const abs = isAbsolute(path) ? resolve(path) : join(vault, path);
-  const rel = abs.startsWith(`${vault}/`) ? abs.slice(vault.length + 1) : null;
+  // A worktree of the vault is the vault too: a close made there refreshes.
+  const loc = vaultLocation(abs, vault);
+  const rel = loc && loc.rel ? loc.rel : null;
   if (!rel) return { refusal: { code: "NOT_IN_VAULT", message: `${path} is not inside the bound vault (${vault})` } };
   if (!existsSync(abs)) return { refusal: { code: "NOT_FOUND", message: `${rel} does not exist in the vault` } };
   const sessionId = hostSessionId(env);
   const cur = sessionId ? readSessionState(projectDir, sessionId) : null;
-  const patch = pointerPatchFor(vault, abs, cur);
+  const patch = pointerPatchFor(vault, abs, cur, undefined, { loc });
   if (!patch || !patch.active_story)
     return { refusal: { code: "NOT_A_STORY", message: `${rel} is not a story file under an epic` } };
   if (!sessionId) return { session: null, refreshed: false, reason: "no-session", path: rel };
@@ -3159,6 +3314,7 @@ export function refreshSessionPointer(projectDir, cfg, path, { env = process.env
       active_story: next.active_story ?? null,
       story_title: next.story_title ?? null,
       story_status: next.story_status ?? null,
+      story_root: next.story_root ?? null,
     },
   };
 }
@@ -3174,35 +3330,51 @@ export function refreshSessionPointer(projectDir, cfg, path, { env = process.env
 export async function refreshStoryPointer(projectDir, vaultPath, sessionId, opts = {}) {
   const cur = readSessionState(projectDir, sessionId);
   if (!cur || !cur.active_epic || !cur.active_story) return "unchanged";
-  const file = storyFileFor(vaultPath, cur.active_epic, cur.active_story);
-  if (!file && !existsSync(join(vaultPath, "epics", cur.active_epic, "epic.md"))) return "unknown";
-  let title = null;
-  let status = null;
-  if (file) {
+  // The copy the story was last touched in (a worktree of the vault), while it
+  // exists; a removed worktree falls back to the bound checkout.
+  const root =
+    typeof cur.story_root === "string" && cur.story_root && cur.story_root !== vaultRootOf(vaultPath)
+      ? cur.story_root
+      : null;
+  const rootLive = root ? existsSync(root) : false;
+  const mainFile = storyFileFor(vaultPath, cur.active_epic, cur.active_story);
+  const rootFile = rootLive ? storyFileFor(root, cur.active_epic, cur.active_story) : null;
+  let patch;
+  if (!mainFile && !rootFile) {
+    const epicIn = (r) => existsSync(join(r, "epics", cur.active_epic, "epic.md"));
+    if (!epicIn(vaultPath) && !(rootLive && epicIn(root))) return "unknown";
+    patch = { active_story: null, story_title: null, story_status: null, story_root: rootLive ? root : null };
+  } else {
     const readFile = opts.readFile || ((p) => readFileAsync(p, "utf8"));
     let timer = null;
     const deadline = new Promise((resolve) => {
       timer = setTimeout(() => resolve(null), opts.budgetMs ?? 200);
     });
-    let text;
+    const readOne = (f) =>
+      f
+        ? Promise.resolve()
+            .then(() => readFile(f))
+            .then(String, () => null)
+        : Promise.resolve("");
+    let texts;
     try {
-      text = await Promise.race([
-        Promise.resolve()
-          .then(() => readFile(file))
-          .then(String, () => null),
-        deadline,
-      ]);
+      texts = await Promise.race([Promise.all([readOne(mainFile), readOne(rootFile)]), deadline]);
     } finally {
       if (timer) clearTimeout(timer);
     }
-    if (text === null) return "unknown";
-    const { data } = parseFrontmatter(text);
-    title = data.title ? String(data.title) : null;
-    status = data.status ? String(data.status) : null;
-  }
-  const patch = file
-    ? { story_title: title, story_status: status }
-    : { active_story: null, story_title: null, story_status: null };
+    if (texts === null || texts.some((t) => t === null)) return "unknown";
+    const fields = (text) => {
+      const { data } = parseFrontmatter(text);
+      return { title: data.title ? String(data.title) : null, status: data.status ? String(data.status) : null };
+    };
+    const main = mainFile ? fields(texts[0]) : null;
+    const copy = rootFile ? fields(texts[1]) : null;
+    // A story closed on the bound checkout wins over a stale worktree copy
+    // (the merge brought `done`); otherwise the copy being worked wins.
+    const useMain = main && (!copy || stageOf(main.status) === "done");
+    const pick = useMain ? main : copy;
+    patch = { story_title: pick.title, story_status: pick.status, story_root: useMain ? null : root };
+  }
   const same = Object.entries(patch).every(([k, v]) => (cur[k] ?? null) === v);
   if (same) return "unchanged";
   writeSessionState(projectDir, sessionId, patch);
@@ -3290,7 +3462,6 @@ export const ENTRY_IGNORE = [
 
 export function isSourcePath(absPath, projectDir, vaultPath) {
   if (!absPath || !projectDir) return false;
-  if (vaultPath && isInsideVault(absPath, vaultPath)) return false;
   const root = projectDir.endsWith("/") ? projectDir.slice(0, -1) : projectDir;
   if (!absPath.startsWith(root + "/")) return false;
   // Matched project-relative, never absolute: SOURCE_IGNORE is
@@ -3298,7 +3469,10 @@ export function isSourcePath(absPath, projectDir, vaultPath) {
   // project that merely lives under a directory called `build`.
   const rel = absPath.slice(root.length + 1);
   if (!rel) return false;
-  return !ENTRY_IGNORE.some((re) => re.test(rel));
+  if (ENTRY_IGNORE.some((re) => re.test(rel))) return false;
+  // Last, because it walks the disk: a file in the vault — a worktree's copy
+  // of it included (contract 1, as amended 2026-10-15) — is never source.
+  return !(vaultPath && vaultLocation(absPath, vaultPath));
 }
 
 export function scoreDir(projectDir, sessionId) {
@@ -3383,7 +3557,14 @@ export function listVaultStoryFiles(vaultPath) {
 export async function resolveOpenStory(vaultPath, opts = {}) {
   const budgetMs = opts.budgetMs ?? 200;
   const readFile = opts.readFile || ((p) => readFileAsync(p, "utf8"));
-  const files = listVaultStoryFiles(vaultPath);
+  // The session's own worktree copy first (its pointer's story_root), then the
+  // bound checkout: a story open where this session works it counts as open.
+  const storyRoot = opts.storyRoot;
+  const own =
+    typeof storyRoot === "string" && storyRoot && storyRoot !== vaultRootOf(vaultPath) && existsSync(storyRoot)
+      ? listVaultStoryFiles(storyRoot)
+      : [];
+  const files = [...own, ...listVaultStoryFiles(vaultPath)];
   if (!files.length) return false;
 
   let timer = null;
@@ -3581,12 +3762,12 @@ export const ENTRY_THRESHOLD = 3;
 // Normative text. Three properties it must keep, whatever the wording: it shows
 // the evidence (the count), it names the action, and it grants the exit — so a
 // false positive costs a glance rather than an argument.
-export function entryReminderText(n) {
+export function entryReminderText(n, { env = process.env } = {}) {
   return [
     `**projectstore**: this session has written to ${n} source files and no story`,
     "is in progress. If this is feature-sized work, open it in the vault before",
-    `going further — \`${commandForm("story", { args: '<EPIC> "<title>"' })}\`, or`,
-    `\`${commandForm("epic")}\` if it needs a new one. If it is a one-off fix, carry`,
+    `going further — \`${commandForm("story", { args: '<EPIC> "<title>"', env })}\`, or`,
+    `\`${commandForm("epic", { env })}\` if it needs a new one. If it is a one-off fix, carry`,
     "on — this fires once.",
   ].join("\n");
 }

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.4",
+  "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.4"
+    "projectstore": "=0.30.5"
   },
   "bundleDependencies": [
     "projectstore"