projectstore-claude 0.30.3 → 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.3",
+      "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.3",
+  "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/commands/agents.md

@@ -12,7 +12,10 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
 1. **Ask** via AskUserQuestion: "Register projectstore's agents in
    CLAUDE.md/AGENTS.md so every session routes to them (critic after
    authoring artifacts, planner before implementing, reviewer before commit)?
-   [Yes / No]". On No, stop.
+   [Yes / No]". On No, stop. When the block is already there marked newer
+   than this copy's template (doctor's info, or `status` showing
+   `ours-newer`), name both numbers in the question: registering writes this
+   copy's older block over the one marked vN.
 2. **Run the verb** and print its output verbatim:
    ```bash
    node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" install --harness claude-code --surface agents_block --project "${CLAUDE_PROJECT_DIR}"
@@ -53,7 +56,7 @@ subcommand (`.projectstore/projectstore.json`; else point to `/projectstore:bind
 
 Run `node "${CLAUDE_PLUGIN_ROOT}/bin/projectstore.mjs" plan --json --surface agents_block --project "${CLAUDE_PROJECT_DIR}"`
 and report each item's `state` from `result.items[]` — the bin wraps the plan in its envelope (`ours-current`, `ours-stale` with its reason,
-`ours-absent`, or a refusal). Then:
+`ours-newer` — marked above this copy's template: install, upgrade and setup leave it, and a named run such as `register` writes this copy's over it — `ours-absent`, or a refusal). Then:
 
 - Block: present in which file, marker version vs the installed template, agent
   names vs the layout roster.

package/node_modules/projectstore/commands/doctor.md

@@ -42,6 +42,10 @@ You are running projectstore diagnostics (ADR-005: umbrella doctor).
      the verb adds the import. For another harness the finding names its own
      `--harness`; relay that command. Never Edit or Write the block yourself —
      the verb is its only writer (install spec, contract 6).
+   - `agents-block` **info** that the block is "marked vN, newer than this
+     copy's vM" → **report only.** Install, upgrade and setup leave such a block as it is (install spec, contract 6 as amended
+     2026-10-14). Relay the finding and its command verbatim; run it only if
+     the user asks, because it writes this copy's older block over the one marked vN.
    - `statusline` issues → offer running `/projectstore:statusline on|off`,
      which installs or removes the entry and the launcher behind a preview
      (the SessionStart hook only refreshes an entry that already exists), and

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.3",
+  "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/convergence.mjs

@@ -56,6 +56,7 @@ import {
   writeFileAtomic,
   envFlag,
   isEphemeralRoot,
+  COPY_UPDATE_STEPS,
 } from "./lib.mjs";
 import { loadHarness, loadHarnesses } from "./harness.mjs";
 import { analysePortableRegistration, portableRegistrationPaths } from "./portable-registration.mjs";
@@ -348,6 +349,34 @@ function runArgs({ harnesses = [], surfaces = null, register = true } = {}) {
   ].join(" ");
 }
 
+// The run a deferral sends to a terminal (the install spec, contract 6, as
+// amended 2026-10-14): the run's own verb for one harness, its --surface
+// selection, --global for a global removal, and setup's --channel npm when
+// that was the answer for the harness whose channel it is (setup's rule 13 —
+// a keep is never repeated). `plan` writes nothing, so it names install. One
+// builder for a deferred row's reason and setup's DONE, so the two agree.
+export function terminalRun({
+  verb = "install",
+  harness = null,
+  version = null,
+  surfaces = null,
+  globalRemoval = false,
+  channel = null,
+} = {}) {
+  const run = verb === "plan" ? "install" : verb;
+  const hostRegistration = Object.values(harness?.surfaces || {}).some(
+    (s) => s && typeof s === "object" && s.format === "host-plugin-registration",
+  );
+  const args = [
+    runArgs({ harnesses: harness ? [harness.id] : [], surfaces }),
+    globalRemoval ? "--global" : "",
+    run === "setup" && channel === "npm" && hostRegistration ? "--channel npm" : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return coreCommand(run, { version, args });
+}
+
 // Stop when the registry's latest is at least a newer copy this project runs
 // — the newest such copy is named. A copy the latest does not reach, or no
 // answer, proceeds: the rows say which case it was (proceedCase). `read` is
@@ -577,9 +606,15 @@ export async function readKeepPlan(copy, { harness, projectDir, env, run, budget
     ...(Array.isArray(result.refusals) ? result.refusals : []),
     ...items.filter((i) => i.action === "refuse").map((i) => i.reason),
   ].filter((x) => typeof x === "string" && x);
+  // A deferred row's reason may carry its run on the lines after its prose
+  // (the install spec, contract 6, as amended 2026-10-14): only the prose is
+  // quoted inside our own sentence, never another copy's command.
   const deferred = items
     .filter((i) => i.deferred === true)
-    .map((i) => ({ surface: String(i.surface ?? ""), reason: typeof i.reason === "string" ? i.reason : null }));
+    .map((i) => ({
+      surface: String(i.surface ?? ""),
+      reason: typeof i.reason === "string" ? i.reason.split("\n")[0] : null,
+    }));
   return {
     argv,
     envelope: true,
@@ -603,6 +638,26 @@ export function ownUpgrade(copy, harness) {
   };
 }
 
+// Whether a kept copy is behind the running package (the install spec,
+// contract 21, rule 9, as amended 2026-10-14): semver precedence, rc
+// included. Never for a copy or a run with no semver version recorded — a
+// recorded "unknown" or a sha must not rank.
+export function copyBehind(copy, version) {
+  return isSemver(copy?.version) && isSemver(version) && cmpPrecedence(copy.version, version) < 0;
+}
+
+// What the keep says when its copy is behind: the project's surfaces are at
+// the running version until the copy updates, and the update in the copy's
+// channel. With a step, the copy's own upgrade runs after this run's agents
+// block, and a copy shipped before this rule plans the block back.
+export function behindAdvice(copy, version, { step = false } = {}) {
+  const head = `${copy.key} ${copy.version} is older than this package (${version})`;
+  const middle = step
+    ? `its own upgrade runs after this run's agents block and may plan the block back to its own version; until it updates, its doctor may call the block stale, and the next run may plan the block again`
+    : `until it updates, the agents block and anything else this run writes for the project are at ${version}, and its own doctor may call the block stale`;
+  return `${head}: ${middle}. Update it (${COPY_UPDATE_STEPS}).`;
+}
+
 // This checkout's npm registration enabled beside the kept copy: the keep
 // changes no registration, so it stays; its uninstall (rule 4) drops it.
 export function npmRowBeside({ harness, id, surface }) {