@gobing-ai/spur 0.4.0 → 0.4.2

package/plugins/sp/commands/dev-runall.md

@@ -1,7 +1,7 @@
 ---
 description: Run a batch of tasks through their pipelines in dependency-correct order — resolve a set, topo-sort, run each via task-pipeline.yaml, emit a batch report
 role: planner
-argument-hint: "--tasks <selector> [--feature <id>] [--mode <sequential|parallel>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary]"
+argument-hint: "--tasks <selector> [--feature <id>] [--mode <sequential|parallel|auto>] [--concurrency <n>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary] [--defer-gate]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -15,10 +15,10 @@ Wraps the **sp:spur-dev** skill.
 | --- | --- | --- |
 | `--tasks` `<selector>` | Task selector to run. | required |
 | `--feature` `<id>` | Restrict to a feature. | omitted |
-| `--mode` `<sequential\|parallel>` | Batch execution order. | sequential |
+| `--mode` `<sequential\|parallel\|auto>` | Batch execution order. `auto` computes the frozen batch's dependency waves and runs parallel only when a wave holds ≥2 independent tasks (see below). | sequential |
 | `--keep-going` | Continue past per-task failures. | off |
 | `--auto` | Skip objective HITL gates. | off |
-| `--agent` `<inline\|auto\|name>` | Who runs each task's pipeline stages. Interactive sequential omit/`inline` uses the host-session driver with unified inline semantics (task 0687 — see below)). `auto`, a name, parallel mode, and headless invocation use subprocesses. The opt-in `fleet` selector (0942) maps each task run to `executor: 'fleet'` so `agent.run` stages dispatch through the fleet control plane (ADR-126) instead of a subprocess. | omit |
+| `--agent` `<inline\|auto\|name>` | Who runs each task's pipeline stages. Interactive sequential omit/`inline` uses the host-session driver with unified inline semantics (task 0687 — see below). `auto`, a name, parallel mode, and headless invocation use subprocesses. The opt-in `fleet` selector (0942) maps each task run to `executor: 'fleet'` so `agent.run` stages dispatch through the fleet control plane (ADR-126) instead of a subprocess. | omit |
 | `--json` | Emit structured JSON. | off |
 | `--wrap` | Run the wrap hop **once for the batch** over the `done` subset only (Step 6 of execution-batch.md): `vars.feature` is passed only when every frozen task is `done`/`cancelled`; an empty done subset skips the wrap with a reason. The `--agent` selector is preserved into the `/sp:dev-wrap` handoff when supplied; omission remains omission. | off |
 | `--next` | Chain-to-completion via the next-router. | off |
@@ -26,24 +26,26 @@ Wraps the **sp:spur-dev** skill.
 | `--worktree` `[<name>]` | Run the batch in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. | off |
 | `--no-summary` | Skip the measured execution summary (one row per task run: time, wait, tool calls, total / non-cached tokens) printed after the batch report. | off (summary printed) |
 | `--concurrency` `<n>` | Parallel-mode worker bound: at most `<n>` task pipelines run at once (task 0931); a dependent starts only after its in-set dependencies are integrated onto the base ref. No-op in sequential mode (ignored). | 2 |
+| `--defer-gate` | Opt-in parallel-batch gate policy (task 1111): each task's `test` hop runs the light tier and writes `DEFERRED`; the batch runs one integrated full gate on the base ref before the feature sync. Requires `--mode parallel`, or `--mode auto` resolved to parallel (dropped with a note otherwise); default off. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
 ```
-/sp:dev-runall --tasks <selector> [--feature <id>] [--mode <sequential|parallel>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary]
+/sp:dev-runall --tasks <selector> [--feature <id>] [--mode <sequential|parallel|auto>] [--concurrency <n>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary] [--defer-gate]
 ```
 
 Flags: `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`,
 or `ready`), `--feature <id>` (sugar for `feature:<id>`; when the effective selector is
-feature-derived, `dev-runall` runs `spur feature check <id> --strict --json` **once** before
+feature-derived, `dev-runall` runs `spur feature check <id> --fix --json` then `spur feature check <id> --strict --json` **once** before
 resolving tasks — a non-zero strict check aborts the batch with verdict `aborted` and the
-structured findings, before any task pipeline action, task 0510 R2; scoped: `L4.scenario-unverified`
-(the expected pre-run state of any not-yet-run feature) is reported verbatim but does not abort —
+structured findings, before any task pipeline action, task 0510 R2; scoped: `L4.scenario-unverified` and `L4.verifying-incomplete-tasks`
+(expected pre-run states of a not-yet-run or reopened feature) are reported verbatim but do not abort (the non-aborting set is
+`NON_ABORTING_PREFLIGHT_CODES` in `plugins/sp/scripts/batch-preflight.ts`; `--fix` repairs land in the report's `autoRepairs`) —
 any other strict error aborts), `--mode`
-`<sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset —
-see `execution-batch.md` § Parallel isolation), `--concurrency <n>`
+`<sequential|parallel|auto>` (default `sequential`; `parallel` fans out a proven-independent subset —
+see `execution-parallel-isolation.md`; `auto` picks one per batch — see below), `--concurrency <n>`
 (parallel-mode worker bound — at most <n> task pipelines at once, default 2; a dependent task starts
 only after its in-set dependencies are **integrated** onto the base ref), `--keep-going`
 (batch failure policy — skip a failed task's in-batch dependents, continue independents; default
@@ -58,10 +60,19 @@ report as JSON), `--wrap` (trigger
 `--worktree` `[<name>]` (run the batch in an isolated git worktree —
 FF-merge onto the base ref on full success, retain intact on any failure/halt/non-FF; bare form
 creates a fresh tree, `<name>` form adopts an existing worktree by name/path/branch; see
-`execution-batch.md` § Worktree isolation).
+`execution-worktree-setup.md` + `execution-worktree-landing.md`).
+
+**`--mode auto` (smart scheduling).** Ordering is always dependency-correct — every mode
+topo-sorts the frozen set with `batch-plan.mjs order` (deterministic, never hand-sorted). `auto`
+additionally reads that schedule's dependency waves (tasks declaring the same file are serialized)
+and decides once, before the first task: `parallel` when some wave holds ≥2 independent tasks and
+`--concurrency` ≥2; otherwise `sequential` in the host session. `--worktree` or explicit
+`--agent inline` pins `sequential`. The batch report records `mode: auto → <resolved>` and why.
+Default stays `sequential`: parallel costs ~N× tokens, worktree setup and subprocess executors, which
+a dependency chain never pays back. Rules: execution-batch.md § 2.4a.
 
 **`--worktree` and parallel mode.** `--worktree --mode parallel` is **rejected** — parallel mode
-already isolates each task in its own worktree (see `execution-batch.md` § Parallel isolation), and
+already isolates each task in its own worktree (see `execution-parallel-isolation.md`), and
 reuse mode (`--worktree <name>`) has no per-task meaning. Run parallel batches without
 `--worktree`, or run them sequentially with it.
 
@@ -81,16 +92,22 @@ advancing the feature lifecycle). **was: `--next` deliberately omitted; the old
 = batch failure policy (does a failure halt the batch or skip dependents?);
 `--continue` = resume from
 checkpoint against the batch's original frozen identity — persisted plan membership, worktree
-marker, identity-filtered checkpoints as hints (execution-batch.md § Batch continuation, task
+marker, identity-filtered checkpoints as hints (execution-batch-continuation.md, task
 0919); `--next`
 = chain each task to terminal status + batch-once wrap. See `dev-operations.md` § runall for the
 full distinction.
 
 ## Implementation
 
+- **Bootstrap reads (1128):** before the first dispatch, read [SKILL.md § Bootstrap reads](../skills/spur-dev/SKILL.md#bootstrap-reads) and load only that mode's files — the section whose trigger has not fired is on demand.
+- **Publish the visible batch plan first (1105):** publish `A Prepare batch` (A1–A4) and `Z Batch
+  report` before the first task, then one letter per task from `batch-plan.mjs waves` after
+  freeze/order and digit children from `batch-plan.mjs task-children` at task start —
+  [execution-batch.md](../skills/spur-dev/references/execution-batch.md#27-visible-batch-plan-1105-r3)
+  § 2.7 Visible batch plan.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md); the resolved selector applies uniformly — eligible `agent.run` stages dispatch once to a native subagent with host fallback (0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.
-- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — bootstrap checklist, quick readiness before isolation, workflow inventory before YAML, comprehensive checks at owning boundaries (task 0814 R1/R3/R4/R7/R8).
-- Interactive sequential omit/inline: `Skill(skill="sp:spur-dev", args="runall-inline $ARGUMENTS")`.
-- Explicit executor or parallel mode: `Skill(skill="sp:spur-dev", args="runall $ARGUMENTS")` → `sp:super-planner` agent.
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — publish the generated plan first, quick readiness before isolation, digest binding, comprehensive checks at owning boundaries (task 0814 R1/R3/R4/R7/R8; 1105 R1).
+- Interactive sequential omit/inline, and `--mode auto` without an explicit executor: `Skill(skill="sp:spur-dev", args="runall-inline $ARGUMENTS")` — auto resolves in the host after freeze/order (§ 2.4a) and hands a parallel resolution to the `runall` path with the frozen explicit WBS list.
+- Explicit executor (any mode, including `auto`) or parallel mode: `Skill(skill="sp:spur-dev", args="runall $ARGUMENTS")` → `sp:super-planner` agent.
 - After the batch report, print the [execution summary](../skills/spur-dev/references/dev-operations.md#execution-summary) over every attempted run unless
   `--no-summary`.

package/plugins/sp/hooks/context-owner.ts

@@ -0,0 +1,56 @@
+/**
+ * context-owner — host-native session ownership identity shared by the indexed-context hooks
+ * (task 1159).
+ *
+ * Extracted from `context-session-start`/`context-session-stop` so the Claude stdin-payload →
+ * owner derivation is a pure, importable function. A hook's `if (import.meta.main)` entrypoint runs
+ * in a subprocess whose body Bun's coverage never attributes, so any real logic left there is
+ * untestable; this module keeps that logic where a unit test can reach it.
+ *
+ * Standalone-safe (sp-plugin-standalone): no imports, so a hook bundles it as a relative path and
+ * `context-session-stop` stays free of the session-start module's heavier dependency surface.
+ */
+
+/**
+ * Who owns a session ledger pointer (task 1159): the host that opened the session plus that host's
+ * own native session id — Claude's hook payload `session_id`, Pi's `ctx.sessionManager.getSessionId()`.
+ * Deliberately **not** the ledger id (shared by every nested run), `process.pid` (a fresh hook process
+ * per event) or `SPUR_RUN_ID` (present on nested children too): none of those separate owner from
+ * child, so none may gate teardown; the host-native id can.
+ */
+export interface SessionOwner {
+    host: 'claude' | 'pi';
+    sessionId: string;
+}
+
+/**
+ * Claude hook identity (task 1159): the payload's `session_id`, falling back to
+ * `CLAUDE_CODE_SESSION_ID` only when the payload id is absent or empty (some Claude hook payloads
+ * omit `session_id`). Returns null when neither yields a nonempty id — the pointer is then written
+ * ownerless, so a later shutdown cannot prove ownership of it (bounded legacy policy in
+ * context-session-stop).
+ */
+export function claudeSessionOwner(payload: unknown, env: NodeJS.ProcessEnv): SessionOwner | null {
+    const raw = payload && typeof payload === 'object' ? (payload as { session_id?: unknown }).session_id : undefined;
+    const fromPayload = typeof raw === 'string' ? raw.trim() : '';
+    const fromEnv = (env.CLAUDE_CODE_SESSION_ID ?? '').trim();
+    const sessionId = fromPayload.length > 0 ? fromPayload : fromEnv;
+    return sessionId.length > 0 ? { host: 'claude', sessionId } : null;
+}
+
+/**
+ * Derive the Claude owner from a raw hook stdin payload (task 1159).
+ *
+ * Malformed or empty stdin carries no payload identity, so it degrades to the env-only fallback
+ * rather than throwing — both hooks keep their fail-open contract. Behaviour is identical to the
+ * former inline `JSON.parse(await Bun.stdin.text())` try/catch in each entrypoint.
+ */
+export function claudeHookOwnerFromPayloadText(text: string, env: NodeJS.ProcessEnv): SessionOwner | null {
+    let payload: unknown;
+    try {
+        payload = JSON.parse(text) as unknown;
+    } catch {
+        payload = undefined;
+    }
+    return claudeSessionOwner(payload, env);
+}

package/plugins/sp/hooks/context-post-tool.ts

@@ -72,6 +72,29 @@ export function estimateTokens(text: string): number {
 /** Scrub secret-like patterns without size capping. */
 export function scrubSecrets(text: string): string {
     let s = text;
+    // Quoted JSON fields first (task 1158): in `{"password": "…"}` the key is itself
+    // quoted, so the bare `key=value` pass below never sees a separator directly after
+    // the key and would persist the value verbatim. Match the quoted sensitive key, keep
+    // it, and replace the entire value. The key may be spelled three ways in real Bash:
+    // `"key"`, `'key'`, and the shell-escaped `\"key\"` inside a double-quoted argument
+    // (`curl -d "{\"password\":\"…\"}"`); the value may be quoted the same way or left
+    // unquoted (`{"password": 12345}`). Escape-aware: a `\"` or `\\` inside a value is
+    // content, never a terminator, and an unterminated value (including a trailing lone
+    // backslash) is redacted through end-of-input so a truncated command cannot leak a
+    // suffix. In the shell-escaped opener form the JSON quote shows up in three raw
+    // spellings: a terminator `\"`, a JSON-level escaped quote `\\\"` (escaped
+    // backslash + escaped quote) that is value content, and a bare `"` that is neither.
+    // That form gets a dedicated alternative whose body consumes `\\\"` as content and
+    // stops only at a clean `\"` terminator; when no clean terminator follows it fails
+    // closed and redacts through end-of-input, so a bare `"` cannot end the value early
+    // and leak its suffix. Runs before
+    // Bearer/`key=` passes so the whole value is replaced, not prefixed. The key must end
+    // on a sensitive word, so `token_count`, `tokens`, `tokenizer` and
+    // `authorization_header` stay readable.
+    s = s.replace(
+        /((\\?(["']))(?:[A-Za-z0-9]+[_-])*(?:api[_-]?key|password|passwd|secret|token|access[_-]?key|private[_-]?key|authorization)\2\s*:\s*)(?:\\\3(?:[^"\\]|\\\\(?:\\\3)|\\[^"])*(?:\\\3|[\s\S]*$)|"(?:[^"\\]|\\.)*(?:"|\\?$)|'(?:[^'\\]|\\.)*(?:'|\\?$)|[^\s,}\][{"']+)/gi,
+        '$1"***"',
+    );
     // Bearer / API key prefixes first (before generic key=value)
     s = s.replace(/\bBearer\s+[A-Za-z0-9._\-+=/]+/gi, 'Bearer ***');
     // `sk-` keys. Segments may be hyphen-separated (`sk-ant-api03-…`), so match the

package/plugins/sp/hooks/context-session-start.ts

@@ -4,8 +4,10 @@
  * context-session-start — SessionStart hook for indexed-context.
  *
  * Generates a session ID, writes `.spur/context/.session.json` (tracking the current session
- * for PostToolUse and Stop hooks), and appends a `session_start` event to
- * `token-ledger.jsonl`. Task 0246: best-effort agent/model hints on session file + event.
+ * for PostToolUse and Stop hooks), and appends a `session_start` event to `token-ledger.jsonl`.
+ * Task 0246: best-effort agent/model hints on session file + event. Task 1159: the pointer records
+ * the host-native {@link SessionOwner} that created it, so a nested child can reuse the ledger for
+ * tool recording without being able to tear it down.
  *
  * **Fail-open contract:** every error path exits 0 with no output.
  *
@@ -13,13 +15,19 @@
  */
 
 import { execSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getEnvVar, getEnvVars } from '../lib/env';
 import { resolveAgentHint, resolveModelHint } from './agent-hint';
+import { claudeHookOwnerFromPayloadText, type SessionOwner } from './context-owner';
 import { checkContextFreshness } from './context-post-tool';
 
 export { resolveAgentHint, resolveModelHint } from './agent-hint';
+export type { SessionOwner } from './context-owner';
+// Owner identity + Claude payload derivation live in ./context-owner (pure, unit-testable);
+// re-exported here because this module stays the hook surface consumers reach for.
+export { claudeHookOwnerFromPayloadText, claudeSessionOwner } from './context-owner';
 
 /**
  * Ancestor-run marker exported by `@gobing-ai/ts-ai-runner` ≥ 0.4.15 (`AGENT_RUN_ID_ENV`).
@@ -64,38 +72,29 @@ interface SessionFileBody {
  * Return the id of the session already in flight, or null when a new one should be minted.
  *
  * **Why this exists (0398 R3).** `SessionStart` fires in every nested `agent.run` subprocess, not
- * once per host session. Each firing used to mint a fresh `session-<date>-<HHMM>` id, append a
+ * once per host session. Each firing used to mint a fresh `session-<date>-<HHMM>` id (now
+ * seconds-plus-random, 1166), append a
  * `session_start` row, and overwrite the `.session.json` pointer that `context-post-tool` reads —
  * so a single pipeline run registered as dozens of sessions and orphaned the parent's event
  * stream. The H6 corpus shows the signature: 332 `session_start` against 157 `session_end` over
  * 18 days, 298 distinct ids, 39 starts in a 2-day window that held a handful of real sessions.
  *
- * **Two signals, in precedence order.**
- *
- * 1. {@link AGENT_RUN_ID_ENV} present → this process is a descendant of an agent run, definitively.
- *    Reuse the recorded session with no time bound: a pipeline step legitimately runs for the full
- *    `implementTimeoutMs` (30 min) and longer batches run for hours, so any wall-clock window would
- *    eventually split a run that is demonstrably still in flight.
- * 2. No marker → fall back to the {@link SESSION_REUSE_IDLE_MS} window on the `started` stamp, for
- *    hosts that nest without propagating a correlation.
- *
- * A crashed session leaves a stale `.session.json`; on path 2 the idle window retires it. On path 1
- * a stale file is only reachable from inside a live agent run, where reusing it is the correct
- * answer anyway.
+ * **Two signals, in precedence order.** (1) {@link AGENT_RUN_ID_ENV} present → definitively a
+ * descendant of an agent run: reuse the recorded session with no time bound, because a pipeline step
+ * legitimately runs for the full `implementTimeoutMs` (45 min) and longer batches for hours, so any
+ * wall-clock window would eventually split a run that is still in flight. (2) No marker → fall back
+ * to the {@link SESSION_REUSE_IDLE_MS} window on the `started` stamp, for hosts that nest without
+ * propagating a correlation. A crashed session leaves a stale `.session.json`: on (2) the idle window
+ * retires it, on (1) a stale file is only reachable from inside a live agent run, where reusing it is
+ * the correct answer anyway.
  */
 export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = getEnvVars()): string | null {
-    let raw: string;
-    try {
-        raw = readFileSync(join(dir, '.session.json'), 'utf-8');
-    } catch {
-        return null; // no in-flight session (or unreadable) → mint a new one
-    }
-
     let body: SessionFileBody;
     try {
-        body = JSON.parse(raw) as SessionFileBody;
+        // No in-flight session, unreadable file or corrupt pointer → mint a new one.
+        body = JSON.parse(readFileSync(join(dir, '.session.json'), 'utf-8')) as SessionFileBody;
     } catch {
-        return null; // corrupt pointer → mint a new one
+        return null;
     }
 
     if (typeof body.session !== 'string' || body.session.length === 0) return null;
@@ -121,12 +120,17 @@ export function resolveActiveSession(dir: string, now: Date, env: NodeJS.Process
  *
  * Idempotent per in-flight session (0398 R3): when `resolveActiveSession` finds one, this returns
  * that id and writes nothing — no ledger row, no pointer rewrite.
+ *
+ * Ownership (task 1159): a **new** pointer records a valid `owner` only; a reused start never
+ * rewrites the pointer, so a nested child cannot take ownership from the parent that opened it,
+ * and only the recorded owner's shutdown can finalize the ledger.
  */
 export function recordSessionStart(
     dir: string,
     env: NodeJS.ProcessEnv = getEnvVars(),
     now: () => Date = () => new Date(),
     agentFallback?: string,
+    owner?: SessionOwner,
 ): string | null {
     try {
         mkdirSync(dir, { recursive: true });
@@ -139,7 +143,11 @@ export function recordSessionStart(
     const active = resolveActiveSession(dir, at, env);
     if (active !== null) return active;
     const pad = (n: number) => String(n).padStart(2, '0');
-    const sessionId = `session-${at.toISOString().slice(0, 10)}-${pad(at.getHours())}${pad(at.getMinutes())}`;
+    // Uniqueness suffix (1166): minute-granular ids collided when a session started in the same
+    // minute an earlier one ended, and the frozen end algorithm then suppressed the new session's
+    // `session_end` row as a duplicate. Seconds + a random suffix make collisions practically
+    // impossible; the id stays an opaque ledger key everywhere else.
+    const sessionId = `session-${at.toISOString().slice(0, 10)}-${pad(at.getHours())}${pad(at.getMinutes())}${pad(at.getSeconds())}-${randomUUID().slice(0, 8)}`;
     const ts = at.toISOString();
     const agent = resolveAgentHint(env, agentFallback);
     const model = resolveModelHint(env);
@@ -153,6 +161,9 @@ export function recordSessionStart(
     };
     if (agent) sessionBody.agent = agent;
     if (model) sessionBody.model = model;
+    const ownerId = typeof owner?.sessionId === 'string' ? owner.sessionId.trim() : '';
+    const host = owner?.host;
+    if (ownerId !== '' && (host === 'claude' || host === 'pi')) sessionBody.owner = { host, sessionId: ownerId };
 
     const sessionFile = join(dir, '.session.json');
     try {
@@ -194,10 +205,21 @@ export function recordSessionStart(
     return sessionId;
 }
 
-// Entrypoint — kept minimal so unit coverage focuses on pure helpers above.
+/**
+ * Open (or reuse) the session for a raw Claude stdin payload (task 1159, testable half).
+ *
+ * Malformed/absent text still opens the session ownerless (legacy policy); the dir resolution lives
+ * here rather than in the entrypoint so the untestable subprocess body stays a few lines.
+ */
+export function recordSessionStartFromPayloadText(text: string, env: NodeJS.ProcessEnv = getEnvVars()): string | null {
+    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
+    return recordSessionStart(dir, env, undefined, undefined, claudeHookOwnerFromPayloadText(text, env) ?? undefined);
+}
+
+// Entrypoint — thin stdin adapter; logic lives in the exported helpers above (task 1159 coverage).
 if (import.meta.main) {
     try {
-        recordSessionStart(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
+        recordSessionStartFromPayloadText(await Bun.stdin.text());
     } catch {
         /* fail-open */
     }

package/plugins/sp/hooks/context-session-stop.ts

@@ -8,6 +8,11 @@
  * per-turn and tore down after turn 1), and on Pi/omp it maps to `session_shutdown` — off the
  * `agent_end`/Stop event where blocking gates (e.g. cc/anti-hallucination) live and would collide.
  *
+ * **Owner-gated finalization (task 1159).** A nested `agent.run` reuses its parent's pointer but
+ * used to finalize and delete it on its own shutdown, so every later parent tool event landed in a
+ * dead ledger. Shutdown now proceeds only when the caller's host-native identity equals the owner
+ * recorded on the pointer, so a child's shutdown is a no-op.
+ *
  * **Fail-open contract:** every error path — missing `.spur/context/`, missing/unparseable
  * `.session.json`, write failure — exits 0 with no output.
  *
@@ -17,7 +22,11 @@
 
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { getEnvVar } from '../lib/env';
+import { getEnvVar, getEnvVars } from '../lib/env';
+import { claudeHookOwnerFromPayloadText } from './context-owner';
+// Type-only import: erased at bundle time, so this hook keeps its minimal
+// node:fs/node:path/env dependency surface (sp-plugin-standalone contract).
+import type { SessionOwner } from './context-session-start';
 
 interface LedgerEvent {
     session: string;
@@ -25,16 +34,51 @@ interface LedgerEvent {
     tokens?: number;
 }
 
+interface SessionPointer {
+    session?: unknown;
+    owner?: unknown;
+}
+
+/** Parse and validate an owner read from the pointer or supplied by a caller. */
+function validSessionOwner(raw: unknown): SessionOwner | null {
+    if (!raw || typeof raw !== 'object') return null;
+    const host = (raw as { host?: unknown }).host;
+    const sessionId = (raw as { sessionId?: unknown }).sessionId;
+    if (host !== 'claude' && host !== 'pi') return null;
+    if (typeof sessionId !== 'string') return null;
+    const trimmed = sessionId.trim();
+    return trimmed.length > 0 ? { host, sessionId: trimmed } : null;
+}
+
+function sameOwner(a: SessionOwner, b: SessionOwner): boolean {
+    return a.host === b.host && a.sessionId === b.sessionId;
+}
+
+/** Read and validate the private session pointer, or null when absent/corrupt. */
+function readPointer(sessionFile: string): SessionPointer | null {
+    if (!existsSync(sessionFile)) return null;
+    try {
+        return JSON.parse(readFileSync(sessionFile, 'utf-8')) as SessionPointer;
+    } catch {
+        return null;
+    }
+}
+
 /** Scan the token-ledger JSONL for this session's events and compute rollup totals. */
 function computeSessionTotals(
     ledgerPath: string,
     sessionId: string,
 ): { reads: number; writes: number; tokens: number } {
-    if (!existsSync(ledgerPath)) return { reads: 0, writes: 0, tokens: 0 };
     let reads = 0;
     let writes = 0;
     let tokens = 0;
-    for (const line of readFileSync(ledgerPath, 'utf-8').split('\n')) {
+    let lines: string[];
+    try {
+        lines = readFileSync(ledgerPath, 'utf-8').split('\n');
+    } catch {
+        return { reads, writes, tokens }; // missing/unreadable ledger → zero totals
+    }
+    for (const line of lines) {
         if (!line.trim()) continue;
         try {
             const evt = JSON.parse(line) as LedgerEvent;
@@ -49,43 +93,86 @@ function computeSessionTotals(
     return { reads, writes, tokens };
 }
 
-/**
- * Finalize one session (task 0969 R3): read the `.session.json` pointer, compute the session's
- * rollup totals, append the `session_end` row, remove the pointer (best-effort) and return the
- * event. Shared by this hook's entrypoint and Pi's `session_shutdown` so both hosts roll up
- * identically. Returns null on every fail-open path.
- */
-export function recordSessionEnd(dir: string, now: () => Date = () => new Date()): Record<string, unknown> | null {
-    const sessionFile = join(dir, '.session.json');
-    if (!existsSync(sessionFile)) return null;
-
-    let sessionId = '';
+/** Return the existing `session_end` row for `sessionId`, or null when the ledger has none. */
+function findSessionEnd(ledgerPath: string, sessionId: string): Record<string, unknown> | null {
+    let lines: string[];
     try {
-        const session = JSON.parse(readFileSync(sessionFile, 'utf-8')) as { session?: string };
-        sessionId = session.session ?? '';
+        lines = readFileSync(ledgerPath, 'utf-8').split('\n');
     } catch {
         return null;
     }
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+            const evt = JSON.parse(line) as Record<string, unknown>;
+            if (evt.type === 'session_end' && evt.session === sessionId) return evt;
+        } catch {
+            // skip unparseable lines
+        }
+    }
+    return null;
+}
+
+/**
+ * Finalize one session (task 0969 R3; owner-gated task 1159): read the `.session.json` pointer,
+ * compute the session's rollup totals, append the `session_end` row, remove the pointer
+ * (best-effort) and return the event. Shared by this hook's entrypoint and Pi's `session_shutdown`
+ * so both hosts roll up identically. Returns null on every fail-open path.
+ *
+ * `caller` is the identity of the process firing shutdown. Finalization requires it to be a valid
+ * identity that **equals** the pointer's recorded owner; a missing/mismatched/malformed caller, a
+ * legacy ownerless pointer or a corrupt pointer all return null with no writes and no removal.
+ * Ownerless pointers stay readable and reusable for tool recording — the bounded legacy policy is
+ * that an unattributable session is retired by the existing idle-start expiry, never claimed here.
+ *
+ * Repeat safety: before appending, an existing `session_end` row for the ledger suppresses a
+ * second one, so a replay after a failed pointer cleanup neither duplicates the row nor strands the
+ * pointer. Removal re-reads the pointer and requires both the ledger id and the owner to be
+ * unchanged, so a pointer replaced since the first read is left untouched.
+ */
+export function recordSessionEnd(
+    dir: string,
+    now: () => Date = () => new Date(),
+    caller?: SessionOwner,
+): Record<string, unknown> | null {
+    const sessionFile = join(dir, '.session.json');
+    const pointer = readPointer(sessionFile);
+    if (!pointer) return null;
 
+    const sessionId = typeof pointer.session === 'string' ? pointer.session : '';
     if (!sessionId) return null;
 
-    const totals = computeSessionTotals(join(dir, 'token-ledger.jsonl'), sessionId);
+    // Ownership gate: only the identity recorded at creation may finalize or remove.
+    const pointerOwner = validSessionOwner(pointer.owner);
+    const callerOwner = validSessionOwner(caller);
+    if (!pointerOwner || !callerOwner || !sameOwner(pointerOwner, callerOwner)) return null;
 
-    const event = {
-        ts: now().toISOString(),
-        session: sessionId,
-        type: 'session_end' as const,
-        totals,
-    };
+    const ledgerPath = join(dir, 'token-ledger.jsonl');
 
-    try {
-        appendFileSync(join(dir, 'token-ledger.jsonl'), `${JSON.stringify(event)}\n`);
-    } catch {
-        return null;
+    let event: Record<string, unknown>;
+    const existing = findSessionEnd(ledgerPath, sessionId);
+    if (existing) {
+        // Replay: the end row survived an earlier failed pointer cleanup. Retry the removal below
+        // without appending a duplicate.
+        event = existing;
+    } else {
+        const totals = computeSessionTotals(ledgerPath, sessionId);
+        event = { ts: now().toISOString(), session: sessionId, type: 'session_end', totals };
+        try {
+            appendFileSync(ledgerPath, `${JSON.stringify(event)}\n`);
+        } catch {
+            return null; // retain the pointer so a later owning shutdown can retry
+        }
     }
 
+    // Remove only the exact pointer finalized above: re-read and require the ledger id and owner
+    // to be unchanged, so a pointer replaced during recording survives.
     try {
-        rmSync(sessionFile, { force: true });
+        const current = readPointer(sessionFile);
+        const currentOwner = current ? validSessionOwner(current.owner) : null;
+        if (current?.session === sessionId && currentOwner && sameOwner(currentOwner, pointerOwner)) {
+            rmSync(sessionFile, { force: true });
+        }
     } catch {
         // cleanup is best-effort
     }
@@ -93,10 +180,24 @@ export function recordSessionEnd(dir: string, now: () => Date = () => new Date()
     return event;
 }
 
-// Entrypoint: run the shared core, then exit 0 (fail-open) as this hook always has.
+/**
+ * Finalize the session for a raw Claude stdin payload (task 1159, testable half).
+ *
+ * Malformed/absent text carries no identity, so shutdown fails closed; the dir resolution lives here
+ * rather than in the entrypoint so the untestable subprocess body stays a few lines.
+ */
+export function recordSessionEndFromPayloadText(
+    text: string,
+    env: NodeJS.ProcessEnv = getEnvVars(),
+): Record<string, unknown> | null {
+    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
+    return recordSessionEnd(dir, undefined, claudeHookOwnerFromPayloadText(text, env) ?? undefined);
+}
+
+// Entrypoint — thin stdin adapter (fail-open); logic lives in the exported core above.
 if (import.meta.main) {
     try {
-        recordSessionEnd(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
+        recordSessionEndFromPayloadText(await Bun.stdin.text());
     } catch {
         /* fail-open: every error path exits 0 */
     }

package/plugins/sp/hooks/pi/guard-extension.ts

@@ -26,11 +26,11 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { getEnvVar, getEnvVars } from '../../lib/env';
 import { reportLifecycleHook } from '../agent-lifecycle';
 import { recordToolUseEvent, type ToolPayload } from '../context-post-tool';
-import { recordSessionStart } from '../context-session-start';
+import { recordSessionStart, type SessionOwner } from '../context-session-start';
 import { recordSessionEnd } from '../context-session-stop';
 import { classifyCommand } from '../destructive-policy';
 import { couldBeTaskFile } from '../task-file-policy';
@@ -44,6 +44,16 @@ const spurContextDir = (): string => join(process.cwd(), '.spur', 'context');
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
+/**
+ * Pi session owner identity (task 1159): the extension's own session-manager id, stable for the
+ * life of the Pi session and distinct from any nested child session. Read here — not from a PID or
+ * `SPUR_RUN_ID` — so a nested child's `session_shutdown` cannot claim the parent's pointer.
+ */
+function piSessionOwner(ctx: ExtensionContext): SessionOwner | null {
+    const sessionId = ctx.sessionManager.getSessionId().trim();
+    return sessionId.length > 0 ? { host: 'pi', sessionId } : null;
+}
+
 type TaskOwnership = 'owned' | 'unowned' | 'unknown';
 
 /**
@@ -238,32 +248,35 @@ export default function (pi: ExtensionAPI): void {
     });
 
     // ── context-post-tool: shared recordToolUseEvent (task 0969 R1) ──
-    pi.on('tool_result', async (event) => {
+    pi.on('tool_result', async (event, ctx) => {
         try {
             const payload = normalizePiToolEvent(
                 event.toolName,
                 event.input as Record<string, unknown> | undefined,
                 (event as { content?: unknown }).content,
             );
-            if (payload) recordToolUseEvent(spurContextDir(), payload);
+            // Host-native session id, as Claude's payload carries (H21 parity).
+            const sessionId = piSessionOwner(ctx)?.sessionId;
+            if (payload)
+                recordToolUseEvent(spurContextDir(), sessionId ? { ...payload, session_id: sessionId } : payload);
         } catch {
             // fail-open
         }
     });
 
     // ── context-session-start: shared recordSessionStart (R2) ────────
-    pi.on('session_start', async () => {
+    pi.on('session_start', async (_event, ctx) => {
         try {
-            recordSessionStart(spurContextDir(), getEnvVars(), undefined, 'pi');
+            recordSessionStart(spurContextDir(), getEnvVars(), undefined, 'pi', piSessionOwner(ctx) ?? undefined);
         } catch {
             // fail-open
         }
     });
 
     // ── context-session-stop: shared recordSessionEnd (R3) ──────────
-    pi.on('session_shutdown', async () => {
+    pi.on('session_shutdown', async (_event, ctx) => {
         try {
-            recordSessionEnd(spurContextDir());
+            recordSessionEnd(spurContextDir(), undefined, piSessionOwner(ctx) ?? undefined);
         } catch {
             // fail-open
         }