@gobing-ai/spur 0.4.1 → 0.4.3

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

@@ -0,0 +1,196 @@
+/**
+ * context-session-stop — SessionEnd hook 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.
+ *
+ * **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.
+ *
+ * Self-contained by design (task 0232). Installed hook configs use the portable
+ * `superskill hook run sp context-session-stop` entrypoint.
+ *
+ * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/hooks/context-session-stop.ts` keeps the argv/stdin adapter.
+ */
+
+import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+// 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-owner';
+import { claudeHookOwnerFromPayloadText } from './context-owner';
+import { getEnvVar, getEnvVars } from './env';
+
+interface LedgerEvent {
+    session: string;
+    type: string;
+    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 } {
+    let reads = 0;
+    let writes = 0;
+    let tokens = 0;
+    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;
+            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 };
+}
+
+/** 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 {
+        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;
+
+    // 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 ledgerPath = join(dir, 'token-ledger.jsonl');
+
+    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 {
+        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
+    }
+
+    return event;
+}
+
+/**
+ * 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);
+}

package/plugins/sp/lib/dogfood-pipeline.ts

@@ -0,0 +1,265 @@
+/**
+ * dogfood pipeline-driving detection — the pure detector core.
+ *
+ * Extracted from `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts` (task 1173, plan
+ * P7/ADR-130): the reusable detection logic lives in lib, and the script keeps only the live
+ * Phase 1.0 CLI gate. Callers and tests may keep importing the script — it re-exports this module.
+ *
+ * Contract (0274 §3 dogfood-pipeline-detect, 0277 R1):
+ *   - Word-boundary matchers with `-` treated as a word char (NOT a boundary).
+ *     A token counts only when it is a distinct hyphen-word, not when it is a
+ *     substring of a longer alphanumeric or hyphen run. This removes the
+ *     leading-space dependency of the @1.1 prose detector.
+ *   - Two token shapes, both with strict `[^\w-]` boundaries:
+ *       (a) complete tokens — `--next`, `dev-run`, `dev-runall`, `dev-wrap`,
+ *           `dev-wrapall`, `dev-idea` — matched as whole hyphen-words so the
+ *           slash form `/sp:dev-run` matches on its `dev-run` tail whether or
+ *           not it is preceded by a space, but `--next` does NOT match inside
+ *           `--next-gen` (the trailing `-gen` breaks the boundary).
+ *       (b) bare nouns — `run`, `runall`, `wrap`, `wrapall`, `idea` — matched
+ *           only as standalone words, so `run` matches in
+ *           `bun ... task run 0042` but NOT inside `runaway`/`prerun`, and
+ *           `idea` does NOT match inside `idealist`/`ideal`.
+ *   - Listing both shapes is what makes the detector leading-space invariant
+ *     (the slash form is caught by its `dev-*` tail; the bare noun is caught
+ *     when it appears as its own word) without letting `run` leak into every
+ *     `-run-` identifier.
+ *
+ * Non-goals of detectPipelineDriving: decides ambiguity only. It does NOT decide
+ * observe vs fix — any explicit `--max-retry` value proceeds regardless.
+ * Implement-heavy advisory is a separate helper (detectImplementHeavy).
+ */
+
+/**
+ * Tokens whose presence makes a testee pipeline-driving. Ordered for stable
+ * diagnostics. Two shapes per the contract above: complete `dev-*` / `--next`
+ * tokens first, then bare nouns.
+ */
+const PIPELINE_TOKENS = [
+    '--next',
+    'dev-runall',
+    'dev-wrapall',
+    'dev-refineall',
+    'dev-verifyall',
+    'dev-run',
+    'dev-wrap',
+    'dev-idea',
+    'refineall',
+    'verifyall',
+    'runall',
+    'wrapall',
+    'run',
+    'wrap',
+    'idea',
+] as const;
+
+/** Refuse message when pipeline-driving and `--max-retry` was not passed (exact string). */
+export const PIPELINE_DRIVING_REFUSE_MESSAGE =
+    '⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)';
+
+/**
+ * Refuse message when the testee carries a mutating `--fix` mode (`--fix all` /
+ * `--fix blockers-first`) and `--max-retry` was not passed. A mutating fix mode
+ * mutates the working tree independent of pipeline-driving (task 0293 R1/R2):
+ * `--max-retry 0` bounds the **driver** only — the testee's own `--fix` pass
+ * still mutates the tree — so the message must not imply otherwise.
+ */
+export const MUTATING_FIX_REFUSE_MESSAGE =
+    '⚠ mutating --fix mode detected (--fix all | --fix blockers-first); pass --max-retry 0 (observe-only for the driver; the testee still mutates the tree) or --max-retry N (fix mode, driver + testee both mutate)';
+
+/** Advisory when pipeline-driving + implement-heavy derived steps (exact string). */
+export const IMPLEMENT_HEAVY_ADVISORY_MESSAGE =
+    '⚠ implement-heavy pipeline dogfood: prefer --max-retry 0 (observe-only) or step-split; operator --max-retry N overrides';
+
+/**
+ * Tokens that mark a derived step as implement-heavy (mutates product/code or
+ * drives a mutating pipeline leg). Deliberately excludes verify/review/unit-only
+ * surfaces even when they carry `--next`.
+ */
+const IMPLEMENT_HEAVY_TOKENS = [
+    'dev-runall',
+    'dev-wrapall',
+    'dev-run',
+    'dev-wrap',
+    'dev-idea',
+    'runall',
+    'wrapall',
+    // bare `run` / `wrap` / `idea` — only when not clearly a non-mutating surface
+    'run',
+    'wrap',
+    'idea',
+    'implement',
+] as const;
+
+/**
+ * A verify/review surface stops being non-mutating the moment it carries a
+ * repair mode: `--fix all` / `--fix blockers-first` applies Edit/Write repairs
+ * to the working tree (0280 dogfood, finding P2). `--fix none` stays
+ * observational. Boundary-guarded so `--prefix all` / `--focus all` never match.
+ * Exported so the Phase 1.0 gate and tests share one matcher (task 0293 R1/R4).
+ */
+export function hasMutatingFixMode(step: string): boolean {
+    return /(?<![\w-])--fix[=\s]+(all|blockers-first)(?![\w-])/i.test(step);
+}
+
+/**
+ * Match a token at a word boundary. A "word boundary" here is the position
+ * between a non-`[\w-]` char (or string start) and the token, and between the
+ * token and a non-`[\w-]` char (or string end). Treating `-` as a word char
+ * is what makes `--next` reject `--next-gen` and `dev-run` reject `dev-runner`.
+ */
+function tokenMatches(testee: string, token: string): boolean {
+    const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // (?<![\w-]) — not preceded by a word char or hyphen.
+    // (?![\w-])  — not followed by a word char or hyphen.
+    const re = new RegExp(`(?<![\\w-])${escaped}(?![\\w-])`, 'i');
+    return re.test(testee);
+}
+
+/**
+ * Returns whether the testee string is pipeline-driving (contains any of the
+ * pipeline-driving tokens as a distinct hyphen-word). Machine-checked
+ * counterpart of the prose list in SKILL.md §Pipeline-driving detection and
+ * dev-dogfood.md.
+ */
+export function detectPipelineDriving(testee: string): boolean {
+    if (typeof testee !== 'string' || testee.length === 0) {
+        return false;
+    }
+    return PIPELINE_TOKENS.some((token) => tokenMatches(testee, token));
+}
+
+/**
+ * True when a single step label (or the whole testee) is implement-heavy —
+ * it chains into real implementation / wrap / idea work, not verify-only.
+ *
+ * Non-mutating surfaces (`dev-verify`, `dev-review`, `dev-unit`, plain
+ * `dev-refine` without a further run) are never implement-heavy even if
+ * pipeline-driving via `--next` — UNLESS they carry a mutating repair mode
+ * (`--fix all` / `--fix blockers-first`), which turns the verify/review leg
+ * into a tree-mutating fix pass (0280 dogfood, finding P2).
+ */
+export function isImplementHeavyStep(step: string): boolean {
+    if (typeof step !== 'string' || step.length === 0) return false;
+    // Explicit non-mutating surfaces win unless a mutating token co-occurs.
+    const nonMutatingOnly =
+        tokenMatches(step, 'dev-verify') || tokenMatches(step, 'dev-review') || tokenMatches(step, 'dev-unit');
+    const hasMutating = IMPLEMENT_HEAVY_TOKENS.some((token) => tokenMatches(step, token)) || hasMutatingFixMode(step);
+    if (nonMutatingOnly && !hasMutating) return false;
+    // refine alone is planning, not implement-heavy; refine+run/--next chain is.
+    if (tokenMatches(step, 'dev-refine') && !hasMutating && !tokenMatches(step, '--next')) {
+        return false;
+    }
+    if (tokenMatches(step, 'dev-refine') && tokenMatches(step, '--next')) {
+        // refine --next chains into run → implement-heavy
+        return true;
+    }
+    return hasMutating;
+}
+
+/**
+ * True when the testee is implement-heavy: it carries a pipeline-driving token,
+ * a mutating `--fix` mode, OR at least one derived step (or the testee itself
+ * when no steps given) is implement-heavy. Used for the W8 Phase 1 advisory
+ * after step derivation.
+ *
+ * Task 0293 R3: a mutating `--fix` mode alone is implement-heavy even with no
+ * pipeline token — the verify/review leg itself becomes a tree-mutating fix
+ * pass.
+ */
+export function detectImplementHeavy(testee: string, derivedSteps: string[] = []): boolean {
+    if (isImplementHeavyStep(testee)) return true;
+    if (!detectPipelineDriving(testee)) return false;
+    return derivedSteps.some((step) => isImplementHeavyStep(step));
+}
+
+export interface GateResult {
+    pipelineDriving: boolean;
+    mutatingFix: boolean;
+    maxRetryPresent: boolean;
+    implementHeavy: boolean;
+    refuse: boolean;
+    advisory: boolean;
+    message: string | null;
+    exitCode: 0 | 1 | 2;
+}
+
+/**
+ * Phase 1.0 + W8 gate decision. Pure — no I/O. The CLI wrapper prints and exits.
+ *
+ * Refuse condition (task 0293 R1) is the union of two **independent** mutation
+ * sources, each gated on `!maxRetryPresent`:
+ *
+ *   1. pipeline-driving testee (`--next`, `dev-run`, …) — refuses because the
+ *      testee chains lifecycle legs whose cumulative blast radius the driver
+ *      cannot pre-attribute.
+ *   2. mutating `--fix` mode (`--fix all` / `--fix blockers-first`) — refuses
+ *      because the testee itself applies Edit/Write repairs even with no
+ *      pipeline token. `--max-retry 0` bounds the **driver** only; the testee
+ *      still mutates (honesty note in MUTATING_FIX_REFUSE_MESSAGE).
+ *
+ * Pipeline-driving is reported first when both co-occur (its refuse message is
+ * the superset — chain + tree mutation).
+ */
+export function evaluateDogfoodGate(
+    testee: string,
+    options: { maxRetryPresent?: boolean; steps?: string[] } = {},
+): GateResult {
+    const maxRetryPresent = options.maxRetryPresent === true;
+    const steps = options.steps ?? [];
+    const pipelineDriving = detectPipelineDriving(testee);
+    const mutatingFix = hasMutatingFixMode(testee);
+    const implementHeavy = detectImplementHeavy(testee, steps);
+
+    if (pipelineDriving && !maxRetryPresent) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: true,
+            advisory: false,
+            message: PIPELINE_DRIVING_REFUSE_MESSAGE,
+            exitCode: 2,
+        };
+    }
+
+    if (mutatingFix && !maxRetryPresent) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: true,
+            advisory: false,
+            message: MUTATING_FIX_REFUSE_MESSAGE,
+            exitCode: 2,
+        };
+    }
+
+    if (implementHeavy) {
+        return {
+            pipelineDriving,
+            mutatingFix,
+            maxRetryPresent,
+            implementHeavy,
+            refuse: false,
+            advisory: true,
+            message: IMPLEMENT_HEAVY_ADVISORY_MESSAGE,
+            exitCode: 0,
+        };
+    }
+
+    return {
+        pipelineDriving,
+        mutatingFix,
+        maxRetryPresent,
+        implementHeavy,
+        refuse: false,
+        advisory: false,
+        message: null,
+        exitCode: 0,
+    };
+}
+
+export { PIPELINE_TOKENS };