@gobing-ai/spur 0.4.1 → 0.4.3

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

@@ -1,203 +1,17 @@
 #!/usr/bin/env bun
-
 /**
- * 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.
- *
- * **Fail-open contract:** every error path exits 0 with no output.
+ * context-session-start — installed SessionStart entry for indexed-context.
  *
- * Self-contained by design (task 0232/0246).
+ * Task 1174: the session open + ownership logic lives in `plugins/sp/lib/context-session-start.ts`;
+ * this file is the argv/stdin adapter. Malformed/absent stdin still opens the session ownerless
+ * (legacy policy) and every error path exits 0 with no output.
  */
 
-import { execSync } from 'node:child_process';
-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 { checkContextFreshness } from './context-post-tool';
-
-export { resolveAgentHint, resolveModelHint } from './agent-hint';
-
-/**
- * Ancestor-run marker exported by `@gobing-ai/ts-ai-runner` ≥ 0.4.15 (`AGENT_RUN_ID_ENV`).
- *
- * `AiRunner` sets this in the agent subprocess environment whenever the caller supplies an
- * `AgentRunCorrelation`, which Spur's pipeline always does
- * (`packages/app/src/workflow/actions/agent-run.ts:148-152`) as does `spur agent run`
- * (`packages/app/src/services/agent-service.ts:661`). execa's `extendEnv` default propagates it
- * transitively, so every descendant of an agent run — including the hook subprocesses the host
- * fires inside it — inherits the same value. Its mere presence answers "am I nested?" exactly.
- *
- * Deliberately a string literal rather than an import: this hook is self-contained by design
- * (tasks 0232/0246) and runs both as a standalone script and from Superskill's bundled runner, so
- * it must not depend on the workspace's module graph. The name is a published contract on the
- * ts-ai-runner side, so a literal here is a stable coupling, not a guess.
- */
-export const AGENT_RUN_ID_ENV = 'SPUR_RUN_ID';
-
-/**
- * Fallback idle window for hosts and code paths that do **not** propagate a run correlation
- * (task 0398 R3).
- *
- * Only consulted when {@link AGENT_RUN_ID_ENV} is absent. With ts-ai-runner ≥ 0.4.15 the
- * agent-run path is detected exactly, so this no longer covers the case that motivated it — it
- * remains as a backstop for nested `SessionStart` fires that arrive outside a correlated run
- * (a host that spawns its own helper processes, or an `agent.run` invoked without a correlation).
- *
- * ponytail: still a wall-clock heuristic on that residual path — two genuinely distinct
- * uncorrelated sessions started inside the window merge into one ledger session. Kept because
- * deleting it would regress every non-correlated nesting path back to the original bug, and the
- * set of hosts is not enumerable from here. Delete it once every nesting path is known to carry a
- * correlation.
- */
-export const SESSION_REUSE_IDLE_MS = 4 * 60 * 60 * 1000;
-
-interface SessionFileBody {
-    session?: unknown;
-    started?: unknown;
-}
-
-/**
- * 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
- * `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` (45 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.
- */
-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;
-    } catch {
-        return null; // corrupt pointer → mint a new one
-    }
-
-    if (typeof body.session !== 'string' || body.session.length === 0) return null;
-
-    // Signal 1 — exact ancestry. No `started` parse, no time bound.
-    const runId = env[AGENT_RUN_ID_ENV];
-    if (typeof runId === 'string' && runId.trim().length > 0) return body.session;
-
-    // Signal 2 — residual heuristic for uncorrelated nesting.
-    if (typeof body.started !== 'string') return null;
-
-    const started = Date.parse(body.started);
-    if (Number.isNaN(started)) return null;
-
-    const idleMs = now.getTime() - started;
-    if (idleMs < 0 || idleMs > SESSION_REUSE_IDLE_MS) return null; // stale or clock-skewed → new
-
-    return body.session;
-}
-
-/**
- * Core session-start path (testable). Returns session id on success, null on I/O failure.
- *
- * Idempotent per in-flight session (0398 R3): when `resolveActiveSession` finds one, this returns
- * that id and writes nothing — no ledger row, no pointer rewrite.
- */
-export function recordSessionStart(
-    dir: string,
-    env: NodeJS.ProcessEnv = getEnvVars(),
-    now: () => Date = () => new Date(),
-    agentFallback?: string,
-): string | null {
-    try {
-        mkdirSync(dir, { recursive: true });
-    } catch {
-        return null;
-    }
-
-    const at = now();
-
-    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())}`;
-    const ts = at.toISOString();
-    const agent = resolveAgentHint(env, agentFallback);
-    const model = resolveModelHint(env);
-
-    const sessionBody: Record<string, unknown> = {
-        session: sessionId,
-        started: ts,
-        reads: 0,
-        writes: 0,
-        tokens: 0,
-    };
-    if (agent) sessionBody.agent = agent;
-    if (model) sessionBody.model = model;
-
-    const sessionFile = join(dir, '.session.json');
-    try {
-        writeFileSync(sessionFile, JSON.stringify(sessionBody));
-    } catch {
-        return null;
-    }
-
-    const startEvent: Record<string, unknown> = { ts, session: sessionId, type: 'session_start' };
-    if (agent) startEvent.agent = agent;
-    if (model) startEvent.model = model;
-
-    // Freshness check (task 0711 R4): report whether the context indexes were
-    // regenerated at the current HEAD. Best-effort, fail-open — git failures
-    // yield head=null, which marks stale only via the sidecar's own defects.
-    let headCommit: string | null = null;
-    try {
-        const out = execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
-        const trimmed = out.trim();
-        headCommit = trimmed.length > 0 ? trimmed : null;
-    } catch {
-        headCommit = null;
-    }
-    let freshnessRaw: string | null = null;
-    try {
-        freshnessRaw = readFileSync(join(dir, '.freshness.json'), 'utf-8');
-    } catch {
-        freshnessRaw = null;
-    }
-    startEvent.contextFreshness = checkContextFreshness(freshnessRaw, headCommit);
-
-    const ledgerPath = join(dir, 'token-ledger.jsonl');
-    try {
-        appendFileSync(ledgerPath, `${JSON.stringify(startEvent)}\n`);
-    } catch {
-        return null;
-    }
-
-    return sessionId;
-}
+import { recordSessionStartFromPayloadText } from '../lib/context-session-start';
 
-// Entrypoint — kept minimal so unit coverage focuses on pure helpers above.
 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

@@ -1,102 +1,17 @@
 #!/usr/bin/env bun
 /**
- * context-session-stop — SessionEnd hook for indexed-context (session teardown).
+ * context-session-stop — installed SessionEnd entry for indexed-context (session teardown).
  *
- * Scans `token-ledger.jsonl` for the current session's events, computes rollup totals, appends
- * a `session_end` event, and cleans up `.session.json`. Registered on SessionEnd (not Stop) so it
- * runs once at true session teardown: on Claude Code the rollup counts the whole session (Stop fired
- * 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.
- *
- * **Fail-open contract:** every error path — missing `.spur/context/`, missing/unparseable
- * `.session.json`, write failure — exits 0 with no output.
- *
- * Self-contained by design (task 0232). Installed hook configs use the portable
- * `superskill hook run sp context-session-stop` entrypoint.
- */
-
-import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
-import { join } from 'node:path';
-import { getEnvVar } from '../lib/env';
-
-interface LedgerEvent {
-    session: string;
-    type: string;
-    tokens?: number;
-}
-
-/** 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')) {
-        if (!line.trim()) continue;
-        try {
-            const evt = JSON.parse(line) as LedgerEvent;
-            if (evt.session !== sessionId) continue;
-            if (evt.type === 'read') reads++;
-            else if (evt.type === 'write') writes++;
-            if (evt.tokens) tokens += evt.tokens;
-        } catch {
-            // skip unparseable lines
-        }
-    }
-    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.
+ * Task 1174: the owner-gated finalization logic lives in `plugins/sp/lib/context-session-stop.ts`;
+ * this file is the argv/stdin adapter. Every error path exits 0 with no output, and a nested
+ * `agent.run`'s shutdown stays a no-op because the owner gate lives in the core, not here.
  */
-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 = '';
-    try {
-        const session = JSON.parse(readFileSync(sessionFile, 'utf-8')) as { session?: string };
-        sessionId = session.session ?? '';
-    } catch {
-        return null;
-    }
-
-    if (!sessionId) return null;
-
-    const totals = computeSessionTotals(join(dir, 'token-ledger.jsonl'), sessionId);
-
-    const event = {
-        ts: now().toISOString(),
-        session: sessionId,
-        type: 'session_end' as const,
-        totals,
-    };
-
-    try {
-        appendFileSync(join(dir, 'token-ledger.jsonl'), `${JSON.stringify(event)}\n`);
-    } catch {
-        return null;
-    }
-
-    try {
-        rmSync(sessionFile, { force: true });
-    } catch {
-        // cleanup is best-effort
-    }
-
-    return event;
-}
+import { recordSessionEndFromPayloadText } from '../lib/context-session-stop';
 
-// Entrypoint: run the shared core, then exit 0 (fail-open) as this hook always has.
 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,14 +26,15 @@ 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 type { SessionOwner } from '../../lib/context-owner';
+import { recordToolUseEvent, type ToolPayload } from '../../lib/context-post-tool';
+import { recordSessionStart } from '../../lib/context-session-start';
+import { recordSessionEnd } from '../../lib/context-session-stop';
+import { classifyCommand } from '../../lib/destructive-policy';
 import { getEnvVar, getEnvVars } from '../../lib/env';
+import { couldBeTaskFile } from '../../lib/task-file-policy';
 import { reportLifecycleHook } from '../agent-lifecycle';
-import { recordToolUseEvent, type ToolPayload } from '../context-post-tool';
-import { recordSessionStart } from '../context-session-start';
-import { recordSessionEnd } from '../context-session-stop';
-import { classifyCommand } from '../destructive-policy';
-import { couldBeTaskFile } from '../task-file-policy';
 
 // ─── Constants ───────────────────────────────────────────────────────────
 
@@ -44,6 +45,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 +249,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
         }

package/plugins/sp/hooks/task-write-guard.ts

@@ -21,7 +21,7 @@
 
 import { spawnSync } from 'node:child_process';
 import { getEnvVar } from '../lib/env';
-import { couldBeTaskFile } from './task-file-policy';
+import { couldBeTaskFile } from '../lib/task-file-policy';
 
 interface ToolPayload {
     tool_name?: string;

package/plugins/sp/{hooks → lib}/agent-hint.ts

@@ -1,4 +1,4 @@
-import { getEnvVars } from '../lib/env';
+import { getEnvVars } from './env';
 /**
  * Shared host-agent identification helpers — the **only** host-agent detection path
  * in the sp plugin hooks.

package/plugins/sp/lib/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);
+}