projectstore-claude 0.30.4 → 0.30.6

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/hooks.json

@@ -6,11 +6,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.mjs\""
           },
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-rules.mjs"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-rules.mjs\""
           }
         ]
       }
@@ -20,7 +20,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/touch-session.mjs"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/touch-session.mjs\""
           }
         ]
       }
@@ -31,7 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/touch-session.mjs"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/touch-session.mjs\""
           }
         ]
       }
@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/session-stop.mjs"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-stop.mjs\""
           }
         ]
       }
@@ -51,7 +51,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.mjs"
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.mjs\""
           }
         ]
       }

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

@@ -25,6 +25,7 @@ import {
   adoptHookInput,
   projectRoot,
   layoutPaths,
+  cachePaths,
   pickExisting,
   activeHarnessId,
   ensureStateRoot,
@@ -46,31 +47,48 @@ import {
 import { runStartupChecks } from "../scripts/doctor.mjs";
 import { resolveBinding, bindingOfferText } from "../scripts/worktree.mjs";
 
-// The marker lives under the harness's state directory; a legacy marker at
-// .claude/.projectstore-welcomed still counts while the window is open.
-function welcomedMarkerPath(proj) {
-  const p = layoutPaths(proj);
-  return pickExisting(p.welcomed(activeHarnessId()), p.legacy.welcomed);
+// The welcome has been seen, by this harness, when either marker exists: the
+// project's (state/<id>/welcomed, or the legacy .claude/.projectstore-welcomed
+// while the window is open) or the machine's (the user-level cache's
+// welcomed/<id>). Both branches read both; only the write follows the binding
+// (the story "Opening a project that is not bound writes nothing into it…",
+// decisions 1 and 2). So a project that holds a marker an unbound session of
+// 0.30.5 or earlier wrote is not welcomed again.
+//
+// The machine's marker is null with no cache root, and a home the platform
+// cannot answer for must not break startup either (skeleton spec, contract 17).
+function machineMarker(id) {
+  try {
+    return cachePaths().welcomed(id);
+  } catch {
+    return null;
+  }
 }
-function welcomedMarkerWritePath(proj) {
-  return layoutPaths(proj).welcomed(activeHarnessId());
+function welcomeSeen(proj, id) {
+  const p = layoutPaths(proj);
+  const machine = machineMarker(id);
+  return existsSync(pickExisting(p.welcomed(id), p.legacy.welcomed)) || (machine !== null && existsSync(machine));
 }
 
-// One-time orientation packet shown when projectstore first loads in a project.
-// Idempotent via a marker file at <project>/.claude/.projectstore-welcomed.
-// The welcome fires once per project, and a project can already be bound when
-// it does — a fresh install into a project someone bound first is the ordinary
+// One-time orientation packet shown when projectstore first loads. A bound
+// project shows it once per project; a project that is not bound shows it once
+// on this machine, because a user-scope install is on in every repository the
+// person opens, and writing a marker into each of them is a write into
+// projects nobody set up. A project can already be bound when the welcome
+// fires — a fresh install into a project someone bound first is the ordinary
 // case, not a corner (measured 2026-09-06: the first line a new user read told
 // them to bind a project whose vault the install preview had just named). So
-// the one instruction it carries branches on the binding; everything else is
-// the same message.
+// the one instruction it carries branches on the binding, and so does the
+// footer that says how often it appears; everything else is the same message.
 function buildWelcome(cfg = null) {
   const start =
     cfg && cfg.vault_path
       ? `**Already bound**: this project's vault is \`${truncFront(String(cfg.vault_path), PATH_CELL)}\`. Ask for what you want — the agent picks up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation, and you approve every write. If the vault has no folders yet, \`${commandForm("scaffold")}\` lays them out.`
       : `**To start using it**: run \`${commandForm("bind", { args: "<vault-path>" })}\` and point it at an Obsidian vault (or any folder). After that, the agent will pick up commands like \`${commandForm("adr")}\` and \`${commandForm("epic")}\` from the conversation; you only approve the writes.`;
   return [
-    "# 👋 projectstore is loaded for the first time in this project",
+    cfg
+      ? "# 👋 projectstore is loaded for the first time in this project"
+      : "# 👋 projectstore is loaded for the first time on this machine",
     "",
     "**What it does**: turns the conversation's decisions into a structured Obsidian-friendly markdown vault — ADRs, epics, stories, runbooks, research. Agent-maintained, you approve every write.",
     "",
@@ -80,7 +98,7 @@ function buildWelcome(cfg = null) {
     // a git marketplace's toggle means nothing to a harness installed from npm.
     ...updateHint().welcome,
     "",
-    "_This message appears once per project._",
+    cfg ? "_This message appears once per project._" : "_This message appears once on this machine._",
     "",
     "_If projectstore helps you ship, a [GitHub star](https://github.com/SmartAndPoint/ProjectStore) helps others discover it. No pressure._",
     "",
@@ -88,17 +106,30 @@ function buildWelcome(cfg = null) {
 }
 
 function showWelcomeOnce(proj, cfg = null) {
-  if (existsSync(welcomedMarkerPath(proj))) return "";
+  const id = activeHarnessId();
+  if (welcomeSeen(proj, id)) return "";
   const text = buildWelcome(cfg);
   try {
-    const marker = welcomedMarkerWritePath(proj);
-    // The state directory's own .gitignore, header included, even in an
-    // unbound project — and no sessions/ there: it is how a project uninstall
-    // recognises this marker as ours (install spec contract 13, as amended by
-    // the shell-fetch story).
-    ensureStateRoot(proj);
-    mkdirSync(dirname(marker), { recursive: true });
-    writeFileSync(marker, new Date().toISOString() + "\n", "utf8");
+    let marker = null;
+    if (cfg) {
+      // Bound: the project's marker, beside the launcher (layout spec contract
+      // 5). The state directory's own .gitignore comes with it, header
+      // included, and no sessions/: it is how a project uninstall recognises
+      // this marker as ours (install spec contract 13, as amended by the
+      // shell-fetch story).
+      ensureStateRoot(proj);
+      marker = layoutPaths(proj).welcomed(id);
+    } else {
+      // Not bound: the machine's marker, and nothing in the project. With no
+      // cache root (no usable home) nothing is written and the welcome shows
+      // again next time — startup never breaks over it (skeleton spec,
+      // contract 17).
+      marker = machineMarker(id);
+    }
+    if (marker) {
+      mkdirSync(dirname(marker), { recursive: true });
+      writeFileSync(marker, new Date().toISOString() + "\n", "utf8");
+    }
   } catch {}
   return text;
 }

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.6",
   "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",
@@ -17,7 +17,7 @@
     "agentic",
     "ai-agents"
   ],
-  "homepage": "https://github.com/SmartAndPoint/ProjectStore#readme",
+  "homepage": "https://projectstore.dev",
   "bugs": {
     "url": "https://github.com/SmartAndPoint/ProjectStore/issues"
   },
@@ -60,21 +60,20 @@
   "scripts": {
     "test": "node --test --import ./tests/fixtures/hermetic.mjs tests/*.test.mjs",
     "guard": "node scripts/version-guard.mjs",
+    "directory:check": "node packaging/directory-guard.mjs",
     "packlist": "node scripts/version-guard.mjs --write-packlist",
     "adapters": "node scripts/build-adapters.mjs --write",
     "adapters:check": "node scripts/build-adapters.mjs --check",
     "shells": "node packaging/shells.mjs --write",
     "shells:check": "node packaging/shells.mjs --check",
     "shells:build": "node packaging/shells.mjs --build --out dist",
-    "release:check": "npm run adapters:check && npm run guard && npm run shells:check && npm run lint && npm run format:check && npm test && npm pack --dry-run",
-    "lint": "eslint --max-warnings 0 bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs",
-    "format": "prettier --write bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs",
-    "format:check": "prettier --check bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs"
-  },
-  "devDependencies": {
-    "@eslint/js": "10.0.1",
-    "eslint": "10.12.0",
-    "eslint-plugin-n": "18.4.1",
-    "prettier": "3.9.10"
+    "release:check": "npm run adapters:check && npm run guard && npm run directory:check && npm run shells:check && npm run lint && npm run format:check && npm test && npm pack --dry-run",
+    "lint:setup": "npm ci --prefix tools/lint",
+    "prelint": "node tools/lint/setup-check.mjs",
+    "preformat": "node tools/lint/setup-check.mjs",
+    "preformat:check": "node tools/lint/setup-check.mjs",
+    "lint": "node tools/lint/node_modules/eslint/bin/eslint.js --max-warnings 0 bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs tools/lint/eslint.config.mjs tools/lint/setup-check.mjs",
+    "format": "node tools/lint/node_modules/prettier/bin/prettier.cjs --write bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs tools/lint/eslint.config.mjs tools/lint/setup-check.mjs",
+    "format:check": "node tools/lint/node_modules/prettier/bin/prettier.cjs --check bin scripts \"hooks/*.mjs\" \"packaging/**/*.mjs\" \"tests/**/*.mjs\" eslint.config.mjs tools/lint/eslint.config.mjs tools/lint/setup-check.mjs"
   }
 }

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/binding.mjs

@@ -20,7 +20,7 @@
 // project's decisions, not the vault's.
 //
 // Never reads ambient cwd or ambient env: the caller resolves the project
-// (cli.mjs's resolveProject) and supplies the author. Normative: the CLI
+// (verbs.mjs's resolveProject) and supplies the author. Normative: the CLI
 // story's slice-2 plan (PS-CORE); the fresh config's keys mirror
 // commands/bind.md step 3 (a test pins the two together).
 //