@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/hooks/careful-guard.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+/**
+ * careful-guard — PreToolUse guard for destructive shell commands (task 0215, R3).
+ *
+ * Warn (permission `ask`) before a `Bash` tool call runs a destructive command — `rm -rf`
+ * (any flag spelling, including the POSIX uppercase `-R`), `DROP TABLE`/`DROP DATABASE`/
+ * `TRUNCATE`, `git push --force`/`-f`/`+refspec`, `git reset --hard`, `git checkout .`/
+ * `git restore .`, `kubectl delete`, `docker system prune`. The operator can confirm to
+ * proceed. Pure pattern-match + decision, no domain logic (mirrors `task-write-guard`).
+ *
+ * **Safe exceptions:** `rm -rf` of well-known build/dependency caches (`node_modules`, `dist`,
+ * `.next`, `coverage`, `build`, `.turbo`, `.cache`) passes without a warning — deleting a rebuildable
+ * cache is routine, not dangerous.
+ *
+ * **Fail-open contract:** every error path — unparseable payload, non-Bash tool, empty command —
+ * emits an `allow` decision. A broken guard must never wedge an agent tool call.
+ *
+ * **Escape hatch:** `SPUR_CAREFUL=off` short-circuits to allow.
+ */
+
+interface ToolPayload {
+    tool_name?: string;
+    tool_input?: { command?: string };
+}
+
+type Decision = 'allow' | 'ask';
+
+function preToolUseDecision(decision: Decision, reason?: string): never {
+    const hookSpecificOutput: Record<string, unknown> = {
+        hookEventName: 'PreToolUse',
+        permissionDecision: decision,
+    };
+    if (reason !== undefined) hookSpecificOutput.permissionDecisionReason = reason;
+    const out: Record<string, unknown> = { hookSpecificOutput };
+    if (reason !== undefined) out.systemMessage = reason;
+    process.stdout.write(JSON.stringify(out));
+    process.exit(0);
+}
+
+/** Well-known rebuildable caches a `rm -rf` may target without a warning. */
+const SAFE_RM_TARGET =
+    /^(?:\.?\/)?(?:[\w.@-]+\/)*(?:node_modules|dist|\.next|coverage|build|\.turbo|\.cache|\.parcel-cache|out)\/?\*?$/;
+
+/**
+ * Expand an argument string into the set of flags it sets, splitting short-flag
+ * clusters into their individual letters: `-Rf --force` → `{R, f, --force}`.
+ *
+ * Matching flags with ad-hoc regexes per call site is what let `rm -R` through —
+ * `-\w*r` only ever matched the lowercase spelling, even though `man rm` defines
+ * `-r` as "Equivalent to -R". Parsing once, case-preserved, makes that class of
+ * miss unrepresentable: a caller names every spelling it cares about explicitly.
+ */
+function parseFlags(args: string): Set<string> {
+    const flags = new Set<string>();
+    for (const token of args.trim().split(/\s+/)) {
+        if (token.length < 2 || !token.startsWith('-') || token === '--') continue;
+        if (token.startsWith('--')) {
+            flags.add(token.split('=')[0] as string); // `--force=x` → `--force`
+            continue;
+        }
+        for (const ch of token.slice(1)) flags.add(ch);
+    }
+    return flags;
+}
+
+/** True when a `rm` invocation is both recursive and forced (any flag spelling). */
+function isRecursiveForceRm(args: string): boolean {
+    const flags = parseFlags(args);
+    // POSIX rm accepts -r and -R interchangeably; --recursive is the GNU long form.
+    const recursive = flags.has('r') || flags.has('R') || flags.has('--recursive');
+    const force = flags.has('f') || flags.has('--force');
+    return recursive && force;
+}
+
+/** True when every non-flag target of a `rm` invocation is a known-safe cache path. */
+function rmTargetsAllSafe(args: string): boolean {
+    const targets = args
+        .trim()
+        .split(/\s+/)
+        .filter((t) => t.length > 0 && !t.startsWith('-'));
+    if (targets.length === 0) return false;
+    return targets.every((t) => SAFE_RM_TARGET.test(t));
+}
+
+/** Always-warn destructive patterns (no safe exception). */
+const DESTRUCTIVE: Array<{ label: string; re: RegExp }> = [
+    {
+        label: 'a SQL DROP/TRUNCATE (DROP TABLE/DATABASE, TRUNCATE)',
+        re: /\b(?:DROP\s+(?:TABLE|DATABASE)|TRUNCATE(?:\s+TABLE)?)\b/i,
+    },
+    { label: 'a force push (git push --force / -f)', re: /\bgit\s+push\b[^\n]*(?:--force(?!-with-lease)|\s-f\b)/i },
+    {
+        // `git push origin +main` forces that ref without any --force flag.
+        label: 'a force push via a + refspec (git push … +ref)',
+        re: /\bgit\s+push\b[^\n]*\s\+[\w./-]+/i,
+    },
+    { label: 'a hard reset (git reset --hard)', re: /\bgit\s+reset\b[^\n]*--hard\b/i },
+    {
+        label: 'a working-tree discard (git checkout . / git restore .)',
+        re: /\bgit\s+(?:checkout|restore)\s+(?:--\s+)?\.(?:\s|$)/i,
+    },
+    { label: 'a cluster delete (kubectl delete)', re: /\bkubectl\s+delete\b/i },
+    { label: 'a docker prune (docker system prune)', re: /\bdocker\s+system\s+prune\b/i },
+];
+
+/** Return a human label for the destructive command, or null when the command is safe. */
+function classifyCommand(command: string): string | null {
+    for (const rmMatch of command.matchAll(/\brm\b([^\n&|;]*)/g)) {
+        const args = rmMatch[1] ?? '';
+        if (isRecursiveForceRm(args) && !rmTargetsAllSafe(args)) {
+            return 'a recursive force remove (rm -rf)';
+        }
+    }
+    for (const { label, re } of DESTRUCTIVE) {
+        if (re.test(command)) return label;
+    }
+    return null;
+}
+
+async function main(): Promise<void> {
+    if (process.env.SPUR_CAREFUL === 'off') preToolUseDecision('allow');
+
+    const stdinText = await Bun.stdin.text();
+    let payload: ToolPayload;
+    try {
+        payload = JSON.parse(stdinText) as ToolPayload;
+    } catch {
+        preToolUseDecision('allow'); // unparseable payload — fail open
+    }
+
+    if (payload.tool_name !== 'Bash') preToolUseDecision('allow');
+
+    const command = payload.tool_input?.command ?? '';
+    if (command.trim() === '') preToolUseDecision('allow');
+
+    const hit = classifyCommand(command);
+    if (hit !== null) {
+        preToolUseDecision(
+            'ask',
+            `This command looks like ${hit} — a destructive operation. Confirm you intend to run it. ` +
+                'Set SPUR_CAREFUL=off to disable this guard.',
+        );
+    }
+    preToolUseDecision('allow');
+}
+
+if (import.meta.main) void main();

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

@@ -0,0 +1,325 @@
+#!/usr/bin/env bun
+/**
+ * context-post-tool — PostToolUse hook for indexed-context
+ * (matcher: Bash|Grep|Glob|Read|Write|Edit — task 0248).
+ *
+ * Appends one event line to `token-ledger.jsonl` per tool call: path and/or short
+ * summary, action, and token estimate. Reads session ID (+ optional agent/model)
+ * from `.spur/context/.session.json`.
+ *
+ * Token cascade (task 0246): tool_response.content → Write tool_input.content →
+ * Edit old/new strings → Read file stat → omit tokens (never store 0 for unknown).
+ *
+ * Redaction (task 0248): store summary only (never full stdout); cap text ~4 KiB;
+ * strip obvious secret patterns. Bash tokens estimate from capped stdout/stderr length.
+ *
+ * **Fail-open contract:** every error path exits 0 with no output.
+ *
+ * Self-contained by design (task 0232/0246/0248). Installed hook configs use
+ * `superskill hook run sp context-post-tool`.
+ */
+
+import { appendFileSync, existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Tools recorded by this hook (must match hooks.json PostToolUse matcher). */
+export const ALLOWED_TOOLS = new Set(['Bash', 'Grep', 'Glob', 'Read', 'Write', 'Edit']);
+
+/** Max stored summary / token-estimate input size (bytes). Task 0248 ~2–4 KiB. */
+export const REDACTION_CAP_BYTES = 4096;
+
+/** Max command/pattern summary length before ellipsis (chars). */
+export const SUMMARY_MAX_CHARS = 200;
+
+interface ToolPayload {
+    session_id?: string;
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        content?: string;
+        old_string?: string;
+        new_string?: string;
+        /** Bash */
+        command?: string;
+        /** Grep / Glob (Claude Code shapes vary) */
+        pattern?: string;
+        glob_pattern?: string;
+        glob?: string;
+        path?: string;
+    };
+    tool_response?: {
+        content?: string | unknown;
+        filePath?: string;
+        stdout?: string;
+        stderr?: string;
+    };
+}
+
+interface SessionFile {
+    session?: string;
+    agent?: string;
+    model?: string;
+}
+
+/** Estimate tokens from raw byte count: Math.ceil(bytes / 4). */
+export function estimateTokens(text: string): number {
+    return Math.ceil(new TextEncoder().encode(text).length / 4);
+}
+
+/** Scrub secret-like patterns without size capping. */
+export function scrubSecrets(text: string): string {
+    let s = text;
+    // 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
+    // whole run rather than a single alphanumeric block — anchoring on `[A-Za-z0-9]{8,}`
+    // alone stopped at the first hyphen and let every Anthropic key through, which is
+    // the most likely secret to appear in a Claude-agent harness.
+    s = s.replace(/\bsk-[A-Za-z0-9_-]{8,}/g, 'sk-***');
+    s = s.replace(/\bAKIA[0-9A-Z]{16}\b/g, 'AKIA***');
+    // Provider token prefixes with a fixed, unambiguous shape.
+    s = s.replace(/\bgithub_pat_[A-Za-z0-9_]{20,}/g, 'github_pat_***');
+    s = s.replace(/\bgh[pousr]_[A-Za-z0-9]{20,}/g, (m) => `${m.slice(0, 4)}***`);
+    // Key=value style secrets (value = rest of non-space token). The key may carry a
+    // prefix (`ANTHROPIC_API_KEY`, `GITHUB_TOKEN`): `_` is a word character, so a
+    // leading `\b` would not match there and every namespaced env var leaked. Allow an
+    // optional `WORD_`-style prefix instead of requiring a boundary.
+    // The whole key (prefix included) is captured so the ledger still says *which*
+    // variable was scrubbed — `ANTHROPIC_API_KEY=***`, not a bare `API_KEY=***`.
+    s = s.replace(
+        /\b((?:[A-Za-z0-9]+[_-])*(?:api[_-]?key|password|passwd|secret|token|access[_-]?key|private[_-]?key))\s*[:=]\s*\S+/gi,
+        '$1=***',
+    );
+    // Authorization: <scheme> <credentials...>
+    s = s.replace(/\bAuthorization\s*:\s*\S+(?:\s+\S+)*/gi, 'Authorization: ***');
+    // PEM private key blocks — redact the payload, keep the header as a marker.
+    s = s.replace(
+        /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----[\s\S]*?(?:-----END (?:[A-Z ]+ )?PRIVATE KEY-----|$)/g,
+        '[private-key-redacted]',
+    );
+    // Collapse long base64 only when + / or = present (avoid pure a-z body blobs)
+    s = s.replace(/\b[A-Za-z0-9+/]{80,}={0,2}\b/g, (m) => (/[+/=]/.test(m) ? '[base64-redacted]' : m));
+    return s;
+}
+
+/**
+ * Cap text to {@link REDACTION_CAP_BYTES} and scrub obvious secret patterns.
+ * Used for any stored summary fragments — never full env dumps.
+ */
+export function redactText(text: string, capBytes: number = REDACTION_CAP_BYTES): string {
+    const s = scrubSecrets(text);
+    const bytes = new TextEncoder().encode(s);
+    if (bytes.length <= capBytes) return s;
+    // Truncate on byte boundary then append marker
+    let end = capBytes;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+    return `${new TextDecoder().decode(bytes.subarray(0, end))}…[truncated]`;
+}
+
+/** Byte length after scrub + hard cap (no truncation marker) — for token estimates. */
+export function cappedByteLength(text: string, capBytes: number = REDACTION_CAP_BYTES): number {
+    const scrubbed = scrubSecrets(text);
+    return Math.min(new TextEncoder().encode(scrubbed).length, capBytes);
+}
+
+/** Truncate a one-line summary for the ledger (after light redaction). */
+export function truncateSummary(text: string, maxChars: number = SUMMARY_MAX_CHARS): string {
+    const cleaned = redactText(text.replace(/\s+/g, ' ').trim(), REDACTION_CAP_BYTES);
+    if (cleaned.length <= maxChars) return cleaned;
+    return `${cleaned.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+/**
+ * Map platform tool name → ledger `type` (task 0248 R2).
+ * Edit stays `write` with action=edit (0245/0246 convention).
+ */
+export function mapToolType(toolName: string): string {
+    switch (toolName) {
+        case 'Read':
+            return 'read';
+        case 'Write':
+        case 'Edit':
+            return 'write';
+        case 'Bash':
+            return 'bash';
+        case 'Grep':
+            return 'grep';
+        case 'Glob':
+            return 'glob';
+        default:
+            return toolName.toLowerCase();
+    }
+}
+
+/**
+ * Short summary for Bash/Grep/Glob (command truncated, pattern, path glob).
+ * Not full stdout. Returns undefined when nothing useful to store.
+ */
+export function buildToolSummary(toolName: string, toolInput: ToolPayload['tool_input']): string | undefined {
+    if (!toolInput) return undefined;
+    if (toolName === 'Bash') {
+        const cmd = typeof toolInput.command === 'string' ? toolInput.command : '';
+        if (!cmd.trim()) return undefined;
+        return truncateSummary(cmd);
+    }
+    if (toolName === 'Grep') {
+        const pattern = typeof toolInput.pattern === 'string' ? toolInput.pattern : '';
+        const path = typeof toolInput.path === 'string' ? toolInput.path : '';
+        const glob =
+            (typeof toolInput.glob === 'string' && toolInput.glob) ||
+            (typeof toolInput.glob_pattern === 'string' && toolInput.glob_pattern) ||
+            '';
+        const parts = [pattern && `/${pattern}/`, path, glob].filter(Boolean);
+        if (parts.length === 0) return undefined;
+        return truncateSummary(parts.join(' '));
+    }
+    if (toolName === 'Glob') {
+        const pattern =
+            (typeof toolInput.pattern === 'string' && toolInput.pattern) ||
+            (typeof toolInput.glob_pattern === 'string' && toolInput.glob_pattern) ||
+            (typeof toolInput.glob === 'string' && toolInput.glob) ||
+            '';
+        const path = typeof toolInput.path === 'string' ? toolInput.path : '';
+        const parts = [pattern, path].filter(Boolean);
+        if (parts.length === 0) return undefined;
+        return truncateSummary(parts.join(' in '));
+    }
+    return undefined;
+}
+
+/** Response text used only for size/token estimate — never written to the ledger. */
+function responseTextForEstimate(toolResponse: ToolPayload['tool_response']): string {
+    if (!toolResponse) return '';
+    const parts: string[] = [];
+    if (typeof toolResponse.content === 'string') parts.push(toolResponse.content);
+    if (typeof toolResponse.stdout === 'string') parts.push(toolResponse.stdout);
+    if (typeof toolResponse.stderr === 'string') parts.push(toolResponse.stderr);
+    return parts.join('\n');
+}
+
+/**
+ * Token cascade (tasks 0246 / 0248). Returns undefined when unknown — callers omit
+ * the field rather than writing tokens: 0.
+ *
+ * Bash: capped stdout/stderr length. Grep/Glob: capped result size or undefined.
+ */
+export function resolveTokenEstimate(
+    toolName: string,
+    toolInput: ToolPayload['tool_input'],
+    toolResponse: ToolPayload['tool_response'],
+): number | undefined {
+    // Bash: estimate from capped response only (never uncapped multi-MB stdout).
+    if (toolName === 'Bash') {
+        const raw = responseTextForEstimate(toolResponse);
+        if (raw.length === 0) return undefined;
+        return Math.ceil(cappedByteLength(raw) / 4);
+    }
+
+    // Grep / Glob: result size after cap, or omit when empty.
+    if (toolName === 'Grep' || toolName === 'Glob') {
+        const raw = responseTextForEstimate(toolResponse);
+        if (raw.length === 0) return undefined;
+        return Math.ceil(cappedByteLength(raw) / 4);
+    }
+
+    const responseContent = toolResponse?.content;
+    if (typeof responseContent === 'string' && responseContent.length > 0) {
+        return estimateTokens(responseContent);
+    }
+    if (toolName === 'Write' && typeof toolInput?.content === 'string' && toolInput.content.length > 0) {
+        return estimateTokens(toolInput.content);
+    }
+    if (toolName === 'Edit') {
+        const parts = [toolInput?.old_string ?? '', toolInput?.new_string ?? ''].join('');
+        if (parts.length > 0) return estimateTokens(parts);
+    }
+    if (toolName === 'Read' && typeof toolInput?.file_path === 'string' && toolInput.file_path) {
+        try {
+            if (existsSync(toolInput.file_path)) {
+                const size = statSync(toolInput.file_path).size;
+                if (size > 0) return Math.ceil(size / 4);
+            }
+        } catch {
+            /* fail-open: skip stat */
+        }
+    }
+    return undefined;
+}
+
+function readSessionFile(dir: string): SessionFile {
+    const sessionFile = join(dir, '.session.json');
+    if (!existsSync(sessionFile)) return {};
+    try {
+        return JSON.parse(readFileSync(sessionFile, 'utf-8')) as SessionFile;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Core record path (testable). Returns the written event, or null when nothing was logged
+ * (unknown tool, missing session, missing path/summary, I/O failure).
+ */
+export function recordToolUseEvent(
+    contextDir: string,
+    payload: ToolPayload,
+    now: () => Date = () => new Date(),
+): Record<string, unknown> | null {
+    const toolName = payload.tool_name ?? '';
+    if (!ALLOWED_TOOLS.has(toolName)) return null;
+
+    const filePath = payload.tool_input?.file_path ?? '';
+    const summary = buildToolSummary(toolName, payload.tool_input);
+
+    // Read/Write/Edit still require a path; Bash/Grep/Glob require a short summary.
+    if (toolName === 'Read' || toolName === 'Write' || toolName === 'Edit') {
+        if (!filePath) return null;
+    } else if (!summary) {
+        return null;
+    }
+
+    const sessionMeta = readSessionFile(contextDir);
+    const session = sessionMeta.session ?? '';
+    if (!session) return null;
+
+    const tokens = resolveTokenEstimate(toolName, payload.tool_input, payload.tool_response);
+    const ts = now().toISOString();
+    const type = mapToolType(toolName);
+    const action = toolName === 'Write' ? 'create' : toolName === 'Edit' ? 'edit' : undefined;
+
+    const event: Record<string, unknown> = { ts, session, type };
+    if (filePath) event.file = filePath;
+    if (summary) event.summary = summary;
+    if (tokens !== undefined) event.tokens = tokens;
+    if (action) event.action = action;
+
+    // Best-effort identity fields — never block logging.
+    if (typeof payload.session_id === 'string' && payload.session_id) {
+        event.sessionId = payload.session_id;
+    }
+    if (typeof sessionMeta.agent === 'string' && sessionMeta.agent) event.agent = sessionMeta.agent;
+    if (typeof sessionMeta.model === 'string' && sessionMeta.model) event.model = sessionMeta.model;
+
+    try {
+        appendFileSync(join(contextDir, 'token-ledger.jsonl'), `${JSON.stringify(event)}\n`);
+    } catch {
+        return null;
+    }
+
+    return event;
+}
+
+// Entrypoint — thin wrapper; logic lives in {@link recordToolUseEvent} for unit coverage.
+if (import.meta.main) {
+    void (async () => {
+        const dir = join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context');
+        try {
+            const stdinText = await Bun.stdin.text();
+            const payload = JSON.parse(stdinText) as ToolPayload;
+            recordToolUseEvent(dir, payload);
+        } catch {
+            /* fail-open: malformed stdin / I/O */
+        }
+        process.exit(0);
+    })();
+}

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

@@ -0,0 +1,182 @@
+#!/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.
+ *
+ * Self-contained by design (task 0232/0246).
+ */
+
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { resolveAgentHint, resolveModelHint } from './agent-hint';
+
+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` (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.
+ */
+export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = process.env): 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 = process.env,
+    now: () => Date = () => new Date(),
+): 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);
+    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;
+
+    const ledgerPath = join(dir, 'token-ledger.jsonl');
+    try {
+        appendFileSync(ledgerPath, `${JSON.stringify(startEvent)}\n`);
+    } catch {
+        return null;
+    }
+
+    return sessionId;
+}
+
+// Entrypoint — kept minimal so unit coverage focuses on pure helpers above.
+if (import.meta.main) {
+    try {
+        recordSessionStart(join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context'));
+    } catch {
+        /* fail-open */
+    }
+    process.exit(0);
+}