@gobing-ai/spur 0.3.99 → 0.4.0

package/plugins/sp/agents/super-reviewer.md

@@ -165,6 +165,16 @@ fails it. One explicit mapping, no transcription step anywhere downstream:
 Severity words stay visible in the same cell — the mapping adds the machine-readable label, it does
 not replace the semantics.
 
+**Disposition column (1089, E71).** The findings table carries a `Disposition` cell. It is not
+cosmetic: the record stage's residual sweep reads these rows (`parseReviewFindings` in
+`packages/app/src/services/residual-scan.ts`), and a `P1`–`P3` row with no disposition classifies as
+**blocking**, which downgrades a PASS verdict to PARTIAL and closes the `done` gate. A finding you
+resolved inside the same task therefore says so in that cell — `RESOLVED`/`FIXED`/`DONE` (optionally
+with the commit) drops the row from the sweep; `DEFER(<reason>)` reclassifies a P3 as deferrable
+(never P1/P2). Prose such as "Closed." inside the *Finding* cell does not count — the sweep reads
+the cell, not the sentence. `OPEN` states "still live", and `ACCEPTED` marks a non-blocking P4
+observation you are deliberately not acting on; both behave as an ordinary open row.
+
 **Section-relative headings.** In WBS mode (standalone or pipeline) the report body is written
 *into* the task's `### Review` section, so every heading inside it MUST be `####` or deeper. A
 `##`/`###` heading in the body becomes a new top-level task section and corrupts the document. With
@@ -173,19 +183,17 @@ shallower.
 
 ```markdown
 #### Review Report — <wbs|path>
-
 **Scope:** <wbs diff | path glob>
 **Dimensions:** functional, security, efficiency, correctness, usability, architecture
 **Verdict:** PASS | PARTIAL | FAIL
-
 ##### Findings (ranked)
 
-| # | Priority | Dimension | Finding | Location |
-|---|----------|-----------|---------|----------|
-| 1 | P1 (blocker) | security | SQL injection in query builder | `src/api/users.ts:42` |
-| 2 | P2 (major) | architecture | Shallow pass-through UserService | `src/services/users.ts:15` |
-| 3 | P3 (minor) | correctness | Missing error branch in createUser | `src/api/users.ts:48` |
-| 4 | P4 (advisory) | usability | `createUser` error text omits the field name | `src/api/users.ts:51` |
+| # | Priority | Dimension | Finding | Location | Disposition |
+|---|----------|-----------|---------|----------|-------------|
+| 1 | P1 (blocker) | security | SQL injection in query builder | `src/api/users.ts:42` | OPEN |
+| 2 | P2 (major) | architecture | Shallow pass-through UserService | `src/services/users.ts:15` | OPEN |
+| 3 | P3 (minor) | correctness | Missing error branch in createUser | `src/api/users.ts:48` | RESOLVED (fixed in <sha>) |
+| 4 | P4 (advisory) | usability | `createUser` error text omits the field name | `src/api/users.ts:51` | ACCEPTED |
 
 ##### Functional Traceability
 
@@ -197,14 +205,20 @@ shallower.
 **Next:** <one-line action>
 ```
 
+The **Verdict line is machine-read** by the task pipeline (session finding after 1088): `review →
+verify|approve` requires a line matching `Verdict: PASS` (plain or bold), and ANYTHING ELSE —
+FAIL, PARTIAL, a missing line, a line split across two lines — routes the run into
+`review-fail-triage` and its bounded repair hop. Keep it on one line, in that shape, in every
+review answer; never restate it as prose only.
+
 **No findings.** Never invent a defect to populate the table. Emit one substantive `P4 (advisory)`
 row that states what was reviewed and what was found — placeholder cells (empty, `—`, `n/a`) are
 rejected by the checker, and so they should be:
 
 ```markdown
-| # | Priority | Dimension | Finding | Location |
-|---|----------|-----------|---------|----------|
-| 1 | P4 (advisory) | — | No P1–P3 findings: 6 changed files reviewed across all six dimensions; R1–R3 traceable to tests | `packages/app/src/workflow/proof-input-fingerprint.ts:102-160` |
+| # | Priority | Dimension | Finding | Location | Disposition |
+|---|----------|-----------|---------|----------|-------------|
+| 1 | P4 (advisory) | — | No P1–P3 findings: 6 changed files reviewed across all six dimensions; R1–R3 traceable to tests | `packages/app/src/workflow/proof-input-fingerprint.ts:102-160` | ACCEPTED |
 ```
 
 ## Out of scope

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

@@ -1,8 +1,8 @@
 ---
 description: Generate changelog from git commits
 role: scribe
-argument-hint: "[--since <tag|commit>] [--until <tag|commit>] [--version <version>]"
-allowed-tools: ["Bash", "Read"]
+argument-hint: "[<file>] [--since <tag|commit>] [--until <tag|commit>] [--version <version>]"
+allowed-tools: ["Bash", "Read", "Edit"]
 ---
 
 # Dev Changelog
@@ -13,6 +13,7 @@ Implements an inline procedure — see [dev-operations.md](../skills/spur-dev/re
 
 | Flag | Description | Default |
 | --- | --- | --- |
+| `<file>` | Optional positional target (e.g. `CHANGELOG.md`); the new section is inserted above its newest release. | stdout |
 | `--since` `<tag\|commit>` | Start of the commit range. | latest tag |
 | `--until` `<tag\|commit>` | End of the commit range. | HEAD |
 | `--version` `<version>` | Override the detected release version. | detected |
@@ -21,9 +22,9 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Usage
 
-/sp:dev-changelog [--since <tag|commit>] [--until <tag|commit>] [--version <version>]
+/sp:dev-changelog [<file>] [--since <tag|commit>] [--until <tag|commit>] [--version <version>]
 
 ## Implementation
 
-Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#8-changelog) (changelog).
+Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#8-changelog) (changelog). This is a docs-only generator: run no quality gates (lint, tests, `spur-check`, rules, citation checks).
 

package/plugins/sp/commands/dev-review-session.md

@@ -1,7 +1,7 @@
 ---
-description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. With --triage: apply pure-doc / one-to-two-line fixes inline, then file remaining findings as one or more implement-ready tasks. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved, triage findings"
+description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. With --fix auto (alias --triage): apply pure-doc / one-to-two-line fixes inline, then file remaining findings as one or more implement-ready tasks. With --fix all: fix every actionable finding inline and file no task. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved, triage findings"
 role: reviewer
-argument-hint: "[<focus>] [--triage]"
+argument-hint: "[<focus>] [--fix <none|auto|all>] [--triage]"
 allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
 ---
 
@@ -10,17 +10,21 @@ allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
 Wraps the **sp:session-review** skill for a lightweight review of the active host session. By
 default it is report-only: current conversation plus read-only repository evidence, run inline so
 the session context is preserved — no workflow launch, history import, task creation, or
-remediation. With `--triage`, it first triages the findings, then applies direct fixes (pure
+remediation. With `--fix auto`, it first triages the findings, then applies direct fixes (pure
 documentation work and one-to-two-line fixes) inline and files everything remaining as one or more
-implement-ready tasks for further fixing. The result includes a non-overlapping time breakdown with durations in
-`M:SS` or `H:MM:SS` form and `n/a` for unavailable measurements.
+implement-ready tasks for further fixing; `--triage` is an alias of `--fix auto`. With `--fix all`,
+it defers nothing: every actionable finding is fixed inline and no task is filed. The result includes a non-overlapping time breakdown —
+work time, operator wait, tool calls and tokens (total / non-cached) per stage, measured from the host transcript by
+`session-timeline.mjs` — with durations in `M:SS` or `H:MM:SS` form and `n/a` only when that
+measurement is unavailable.
 
 ## Argument Flags
 
 | Flag | Description | Default |
 | --- | --- | --- |
 | `[<focus>]` | Optional question or operation to emphasize without excluding material session outcomes. | full active session |
-| `--triage` | After the report: bucket findings → apply pure-doc / 1–2-line fixes inline → file the remainder as one or more implement-ready tasks. | off (report-only) |
+| `--fix` `<none\|auto\|all>` | Remediation after the report. `none`: report-only. `auto`: bucket findings → apply pure-doc / 1–2-line fixes inline → file the remainder as one or more implement-ready tasks. `all`: fix every actionable finding inline, file no task. | none |
+| `--triage` | Alias of `--fix auto`; an explicit `--fix` wins when both are passed. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
@@ -29,7 +33,8 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ```
 /sp:dev-review-session
 /sp:dev-review-session "why the verification loop repeated"
-/sp:dev-review-session --triage
+/sp:dev-review-session --fix auto        # same as --triage
+/sp:dev-review-session --fix all
 /sp:dev-review-session "F95 findings" --triage
 ```
 

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

@@ -1,7 +1,7 @@
 ---
 description: Run a task — full pipeline (precheck→implement→test→review→approve→verify→record→done) or single-step (implement)
 role: coder
-argument-hint: "<wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]"
+argument-hint: "<wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]] [--no-summary]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill"]
 ---
 
@@ -21,12 +21,13 @@ Wraps the **sp:spur-dev** and **sp:code-implementation** skills.
 | `--wrap` | Run the wrap hop after the main step. The `--agent` selector is preserved into the `/sp:dev-wrap <wbs>` handoff when supplied; omission remains omission. The wrap hop is workflow-backed and reports its trigger-3 subprocess override. | off |
 | `--continue` | Resume an interrupted task from its checkpoint. | off |
 | `--worktree` `[<name>]` | Run the task pipeline 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. Full mode only. | off |
+| `--no-summary` | Skip the measured execution summary (per-stage time, wait, tool calls, total / non-cached tokens) printed after a full-mode run. | off (summary printed) |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-run <wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]
+/sp:dev-run <wbs> [--mode <full|implement>] [--agent <inline|auto|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]] [--no-summary]
 
 ## Implementation
 
@@ -37,6 +38,8 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
   `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")`; `--agent auto` or a named executor
   uses `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` and the workflow subprocess path.
 - Implement step only (`--mode implement`): `Skill(skill="sp:code-implementation", args="$ARGUMENTS")`
+- After a full-mode run settles (done, failed or paused), print the
+  [execution summary](../skills/spur-dev/references/dev-operations.md#execution-summary) unless `--no-summary`.
 
 **Flags:**
 

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>]]"
+argument-hint: "--tasks <selector> [--feature <id>] [--mode <sequential|parallel>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -24,6 +24,7 @@ Wraps the **sp:spur-dev** skill.
 | `--next` | Chain-to-completion via the next-router. | off |
 | `--continue` | Resume an interrupted batch. | off |
 | `--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 |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
@@ -31,7 +32,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ## Usage
 
 ```
-/sp:dev-runall --tasks <selector> [--feature <id>] [--mode <sequential|parallel>] [--keep-going] [--auto] [--agent <inline|auto|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]]
+/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]
 ```
 
 Flags: `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`,
@@ -91,3 +92,5 @@ full distinction.
 - 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.
+- 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/agent-lifecycle.ts

@@ -0,0 +1,155 @@
+#!/usr/bin/env bun
+
+/**
+ * agent-lifecycle — report this member's lifecycle state from host hooks (G73 R4, task 1080).
+ *
+ * A fleet member that blocks on a human (a permission prompt) looks exactly like an
+ * idle one to the strategy, which then dispatches work at a member that cannot run it.
+ * The host's own hook events say otherwise, so this hook maps them to a
+ * `spur agent report --state … --seq …` call.
+ *
+ * **Fail-open contract (R4):** outside a fleet (`SPUR_SPEC_ID` unset) the hook exits
+ * without any CLI call, every error path exits 0, and the report runs in a detached,
+ * unref'd child — the agent never waits on it.
+ *
+ * Event → state:
+ *   SessionStart      → idle      (docs.claude.com/en/docs/claude-code/hooks)
+ *   UserPromptSubmit  → working
+ *   Notification      → blocked   (matcher `permission_prompt`: the host fires it once a
+ *                                  tool-use/sandbox approval prompt has waited ~6 s)
+ *   Stop              → idle
+ *   agent_start       → working   (Pi, ADR-129 — same core from the extension)
+ *   agent_settled     → idle
+ *
+ * Self-contained by design: hooks are bundled standalone at install time, so this file
+ * imports only `node:*` builtins and relative paths (plugin-standalone contract).
+ */
+
+import { spawn } from 'node:child_process';
+import { getEnvVars } from '../lib/env';
+
+/** Lifecycle states `spur agent report` accepts — mirrors MEMBER_LIFECYCLE_STATES in the domain. */
+export type MemberLifecycleState = 'working' | 'idle' | 'blocked';
+
+/** The env var that marks a run as a fleet member (stamped by the supervisor and AgentService). */
+export const SPEC_ID_ENV = 'SPUR_SPEC_ID';
+
+/** The host hook payload fields this hook reads. */
+export interface LifecycleHookPayload {
+    hook_event_name?: unknown;
+    notification_type?: unknown;
+}
+
+/**
+ * Map one host event to the state to report; `null` means this event reports nothing.
+ *
+ * The Notification type check is a second filter, not the primary one: the host matches
+ * `matcher: "permission_prompt"` before the hook runs, so a host that omits the field still
+ * reports `blocked`. It exists so a widened or mis-abbreviated matcher cannot report a
+ * member blocked for an unrelated alert (idle/auth/elicitation prompts are not work blockers).
+ */
+export function lifecycleStateFor(
+    eventName: unknown,
+    notificationType: unknown = undefined,
+): MemberLifecycleState | null {
+    switch (eventName) {
+        case 'SessionStart':
+            return 'idle';
+        case 'UserPromptSubmit':
+            return 'working';
+        case 'Notification':
+            return notificationType === undefined || notificationType === 'permission_prompt' ? 'blocked' : null;
+        case 'Stop':
+            return 'idle';
+        // Pi event names (ADR-129) — the extension calls this same core.
+        case 'agent_start':
+            return 'working';
+        case 'agent_settled':
+            return 'idle';
+        default:
+            return null;
+    }
+}
+
+/**
+ * Monotonic-enough report sequence (G73 Q&A, CLOSED): wall-clock nanoseconds plus the
+ * sub-millisecond part of the monotonic clock. Ties lose under the strict `>` rule, which
+ * is the intended stale-drop behavior.
+ */
+export function reportSeq(now: number = Date.now(), hrtimeNs: bigint = process.hrtime.bigint()): string {
+    return (BigInt(now) * 1_000_000n + (hrtimeNs % 1_000_000n)).toString();
+}
+
+/** Dispatch seam — tests inject a recorder instead of spawning. */
+export type LifecycleSpawn = (argv: readonly string[]) => void;
+
+/** The one child we ever spawn: detached + unref'd + silent, so the agent is never delayed. */
+const spawnDetached: LifecycleSpawn = (argv) => {
+    const [command, ...args] = argv;
+    if (command === undefined) return;
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.unref();
+};
+
+/** Injectable seams for tests. */
+export interface ReportDeps {
+    spawnDetached?: LifecycleSpawn;
+    /** Environment to read `SPUR_SPEC_ID` from; defaults to the live env. */
+    env?: Record<string, string | undefined>;
+    /** Fixed sequence for a deterministic assertion. */
+    seq?: string;
+}
+
+/** Outcome of one hook invocation — returned for tests, ignored by the entrypoint. */
+export interface ReportOutcome {
+    reported: boolean;
+    state?: MemberLifecycleState;
+    reason?: string;
+}
+
+/**
+ * Report the payload's lifecycle state to the fleet, or explain why nothing was reported.
+ * Never throws: a hook that fails must not fail the agent's turn.
+ */
+export function reportLifecycleHook(payload: LifecycleHookPayload, deps: ReportDeps = {}): ReportOutcome {
+    const env = deps.env ?? getEnvVars();
+    const specId = env[SPEC_ID_ENV];
+    if (typeof specId !== 'string' || specId === '') {
+        return { reported: false, reason: 'outside a fleet (no SPUR_SPEC_ID)' };
+    }
+    const state = lifecycleStateFor(payload.hook_event_name, payload.notification_type);
+    if (state === null) {
+        return { reported: false, reason: 'event reports no lifecycle state' };
+    }
+    const seq = deps.seq ?? reportSeq();
+    try {
+        (deps.spawnDetached ?? spawnDetached)(['spur', 'agent', 'report', '--state', state, '--seq', seq]);
+    } catch (error) {
+        return { reported: false, state, reason: error instanceof Error ? error.message : 'spawn failed' };
+    }
+    return { reported: true, state };
+}
+
+/**
+ * Parse a hook stdin payload. An empty payload is an empty object; malformed JSON throws
+ * and is caught by {@link runHookFromStdin} — the fail-open boundary, not this parser.
+ */
+export function parseHookPayload(raw: string): LifecycleHookPayload {
+    if (raw.trim() === '') return {};
+    return JSON.parse(raw) as LifecycleHookPayload;
+}
+
+/** One hook invocation from raw stdin — the whole entrypoint behavior, minus the exit. */
+export function runHookFromStdin(raw: string, deps: ReportDeps = {}): ReportOutcome {
+    try {
+        return reportLifecycleHook(parseHookPayload(raw), deps);
+    } catch {
+        return { reported: false, reason: 'fail-open: unreadable payload' };
+    }
+}
+
+// Entrypoint — minimal so unit coverage focuses on the pure helpers above.
+if (import.meta.main) {
+    runHookFromStdin(await Bun.stdin.text());
+    process.exit(0);
+}

package/plugins/sp/hooks/fleet-guest-stop.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env bun
+
+/**
+ * fleet-guest-stop — deliver pending fleet inbox work to a joined guest session at turn end
+ * (G73 R4, task 1081).
+ *
+ * A guest pulls its own work; this hook is the accelerant that makes the pull arrive at a turn
+ * boundary instead of only when the `fleet-join` skill's `wait --inbox` loop wakes. It is
+ * deliberately conservative:
+ *
+ * - **Only a joined session blocks.** The hook matches the hook payload's `session_id` against
+ *   `.spur/run/guests/*.json`; no match ⇒ exit 0 with no output (the agent finishes normally).
+ * - **Never loops.** A host that reports `stop_hook_active` (Codex) is already continuing → exit 0.
+ * - **Fail-open.** Every error path exits 0 silently; a hook must never fail the agent's turn.
+ * - **Bounded.** The pending check is `spur agent wait --inbox <id> --timeout 2000`, which also
+ *   heartbeats the guest lease (R5), and the reason names at most the first few messages.
+ *
+ * Block contract (both hosts that support it): exit 0 with JSON on stdout —
+ * `{"decision":"block","reason":"<non-empty>"}`. Claude Code uses the reason as the stop reason;
+ * Codex turns it into the next user prompt. Hosts that drop the Stop event (`codex exec` on
+ * 0.160.0 — see `docs/plans/2026-10-05-codex-guest-spike.md`) simply never call it.
+ *
+ * Self-contained by design: hooks are bundled standalone at install time, so this file imports
+ * only `node:*` builtins and relative paths (plugin-standalone contract).
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getEnvVar } from '../lib/env';
+
+/** Budget for the pending-work probe; the hook must never noticeably slow a turn. */
+export const GUEST_STOP_PROBE_MS = 2000;
+
+/** How many pending messages the delivered reason names. */
+export const GUEST_STOP_MAX_MESSAGES = 5;
+
+/** Characters of each message body the reason carries. */
+export const GUEST_STOP_BODY_CHARS = 140;
+
+/** Hard per-invocation timeout for a `spur` child the hook shells out to. */
+export const GUEST_STOP_CLI_TIMEOUT_MS = 5000;
+
+/** The hook payload fields this hook reads (Claude Code and Codex both send `session_id`). */
+export interface GuestStopPayload {
+    session_id?: unknown;
+    stop_hook_active?: unknown;
+}
+
+/** The guest record fields the hook needs. */
+export interface GuestStopRecord {
+    id: string;
+    sessionId?: string;
+}
+
+/** Injection seam for tests: run a `spur` invocation, returning exit code and stdout. */
+export type GuestStopCli = (args: readonly string[]) => { status: number | null; stdout: string };
+
+const defaultCli: GuestStopCli = (args) => {
+    const result = spawnSync('spur', [...args], { encoding: 'utf-8', timeout: GUEST_STOP_CLI_TIMEOUT_MS });
+    return { status: result.status, stdout: result.stdout ?? '' };
+};
+
+/**
+ * Guest records under `<cwd>/.spur/run/guests/`. Unreadable or malformed records are skipped —
+ * a broken record must not block a session's turn.
+ */
+export function readGuestRecords(cwd: string): GuestStopRecord[] {
+    const dir = join(cwd, '.spur', 'run', 'guests');
+    if (!existsSync(dir)) return [];
+    const records: GuestStopRecord[] = [];
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.json')) continue;
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, name), 'utf-8')) as Record<string, unknown>;
+            if (typeof parsed.id !== 'string') continue;
+            records.push({
+                id: parsed.id,
+                ...(typeof parsed.sessionId === 'string' ? { sessionId: parsed.sessionId } : {}),
+            });
+        } catch {
+            // Skip the unreadable record.
+        }
+    }
+    return records;
+}
+
+/** The guest joined by this host session, or null. */
+export function guestForSession(records: readonly GuestStopRecord[], sessionId: unknown): GuestStopRecord | null {
+    if (typeof sessionId !== 'string' || sessionId === '') return null;
+    return records.find((record) => record.sessionId === sessionId) ?? null;
+}
+
+/**
+ * Build the Stop decision for a pending message list. Returns the JSON line to print, or null
+ * when there is nothing to deliver (no messages / unparseable output).
+ */
+export function stopDecisionFor(
+    guestId: string,
+    inboxJson: string,
+    maxMessages: number = GUEST_STOP_MAX_MESSAGES,
+): string | null {
+    let rows: unknown;
+    try {
+        rows = JSON.parse(inboxJson);
+    } catch {
+        return null;
+    }
+    const list = Array.isArray(rows) ? rows : undefined;
+    if (list === undefined) return null;
+    const pending = list
+        .map((row) => row as { from_id?: unknown; fromId?: unknown; body?: unknown; status?: unknown })
+        .filter((row) => row.body !== undefined && (row.status === undefined || row.status === 'queued'))
+        .slice(0, maxMessages);
+    if (pending.length === 0) return null;
+    const lines = pending.map((row) => {
+        const from =
+            typeof row.from_id === 'string' ? row.from_id : typeof row.fromId === 'string' ? row.fromId : 'fleet';
+        const body = String(row.body ?? '')
+            .replace(/\s+/g, ' ')
+            .trim();
+        return `- ${from}: ${body.length > GUEST_STOP_BODY_CHARS ? `${body.slice(0, GUEST_STOP_BODY_CHARS)}…` : body}`;
+    });
+    const reason = `Pending fleet messages for ${guestId}:\n${lines.join('\n')}\n\nHandle them, then \`spur message reply <msgId> …\` and continue.`;
+    return JSON.stringify({ decision: 'block', reason });
+}
+
+/** Injectable seams for the hook entrypoint. */
+export interface GuestStopDeps {
+    cwd?: string;
+    cli?: GuestStopCli;
+    probeMs?: number;
+    maxMessages?: number;
+}
+
+/**
+ * One hook invocation: return the stdout line to print, or null for a silent exit 0.
+ * Never throws.
+ */
+export function runFleetGuestStop(payload: GuestStopPayload, deps: GuestStopDeps = {}): string | null {
+    try {
+        // A host that already continued this turn must not continue it again.
+        if (payload.stop_hook_active === true) return null;
+        const cwd = deps.cwd ?? getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd();
+        const guest = guestForSession(readGuestRecords(cwd), payload.session_id);
+        if (guest === null) return null;
+        const cli = deps.cli ?? defaultCli;
+        // `wait --inbox` returns 0 only when queued work exists, and it heartbeats the lease.
+        const probe = cli([
+            'agent',
+            'wait',
+            '--inbox',
+            guest.id,
+            '--timeout',
+            String(deps.probeMs ?? GUEST_STOP_PROBE_MS),
+        ]);
+        if (probe.status !== 0) return null;
+        const inbox = cli(['message', 'inbox', '--agent', guest.id, '--json']);
+        if (inbox.status !== 0) return null;
+        return stopDecisionFor(guest.id, inbox.stdout, deps.maxMessages);
+    } catch {
+        return null;
+    }
+}
+
+// Entrypoint — minimal so unit coverage focuses on the pure helpers above.
+export function runStopFromStdin(raw: string, deps: GuestStopDeps = {}): string | null {
+    try {
+        const payload = raw.trim() === '' ? {} : (JSON.parse(raw) as GuestStopPayload);
+        return runFleetGuestStop(payload, deps);
+    } catch {
+        return null;
+    }
+}
+
+if (import.meta.main) {
+    const line = runStopFromStdin(await Bun.stdin.text());
+    if (line !== null) process.stdout.write(`${line}\n`);
+    process.exit(0);
+}

package/plugins/sp/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-    "description": "Spur (sp) plugin hooks — task corpus write protection + indexed-context token-ledger tracking.",
+    "description": "Spur (sp) plugin hooks — task corpus write protection + indexed-context token-ledger tracking + fleet lifecycle reporting.",
     "hooks": {
         "PreToolUse": [
             {
@@ -32,6 +32,50 @@
                         "type": "command",
                         "command": "superskill hook run sp context-session-start",
                         "timeout": 15
+                    },
+                    {
+                        "type": "command",
+                        "command": "superskill hook run sp agent-lifecycle",
+                        "timeout": 5
+                    }
+                ]
+            }
+        ],
+        "UserPromptSubmit": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "superskill hook run sp agent-lifecycle",
+                        "timeout": 5
+                    }
+                ]
+            }
+        ],
+        "Notification": [
+            {
+                "matcher": "permission_prompt",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "superskill hook run sp agent-lifecycle",
+                        "timeout": 5
+                    }
+                ]
+            }
+        ],
+        "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "superskill hook run sp agent-lifecycle",
+                        "timeout": 5
+                    },
+                    {
+                        "type": "command",
+                        "command": "superskill hook run sp fleet-guest-stop",
+                        "timeout": 10
                     }
                 ]
             }

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

@@ -10,6 +10,7 @@
  *   - context-post-tool (tool_result → shared recordToolUseEvent)
  *   - context-session-start (session_start → shared recordSessionStart)
  *   - context-session-stop  (session_shutdown → shared recordSessionEnd)
+ *   - agent-lifecycle       (agent_start/agent_settled → shared reportLifecycleHook, G73 R4)
  *
  * The ledger and session cores are shared with the Claude hooks (task 0969): this
  * extension only normalizes Pi event shapes and adapts them to those cores.
@@ -27,6 +28,7 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import type { ExtensionAPI } 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 { recordSessionEnd } from '../context-session-stop';
@@ -266,4 +268,23 @@ export default function (pi: ExtensionAPI): void {
             // fail-open
         }
     });
+
+    // ── agent-lifecycle: fleet lifecycle reporting (G73 R4, task 1080) ──
+    // Pi has no native `blocked` signal (herdr finding P2), so only working/idle are
+    // reported here; a no-op outside a fleet, like every other hook path.
+    pi.on('agent_start', async () => {
+        try {
+            reportLifecycleHook({ hook_event_name: 'agent_start' });
+        } catch {
+            // fail-open
+        }
+    });
+
+    pi.on('agent_settled', async () => {
+        try {
+            reportLifecycleHook({ hook_event_name: 'agent_settled' });
+        } catch {
+            // fail-open
+        }
+    });
 }