@gobing-ai/spur 0.3.98 → 0.4.0

package/plugins/sp/README.md

@@ -273,6 +273,7 @@ plugins/sp/
 ├── commands/                        # Slash-command wrappers — the SSOT (hand-editable thin wrappers; see Commands below)
 ├── agents/                          # 4 specialist subagents (expert-spur, super-coder, super-planner, super-reviewer)
 ├── hooks/                           # hooks.json + task-write-guard.{ts,test.ts} + context-{session-start,post-tool,session-stop}.ts
+│                                    # + agent-lifecycle.{ts,test.ts} + fleet-guest-stop.{ts,test.ts} (fleet member/guest hooks)
 │                                    # + careful-guard.{ts,test.ts} + context-hooks.test.ts + token-estimate.test.ts
 │                                    # + shared policy modules: agent-hint.ts, destructive-policy.{ts,test.ts}, task-file-policy.{ts,test.ts}
 │                                    # + pi/guard-extension.{ts,test.ts} (plugin.json `extensions.pi` entry point)
@@ -342,6 +343,7 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `reverse-engineering`       | 1.1   | Codebase analysis / HLD generation / audit — depth-driven reverse engineering with orthogonal mode, focus, and format controls; backs `/sp:dev-reverse`                                                                                    |
 | `issue-finding`             | 2.0   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; **legacy path** — superseded by `history-anatomy` for indexed reporting; backs no current command; directly invocable as sp:issue-finding |
 | `conflict-finding`          | 1.0   | Authority-aware semantic audit — four-pillar (source/task/feature/authority) conflict discovery, claim-specific authority resolution, reproducible evidence, confirmed owner-routed remediation; backs `/sp:dev-find-conflict`             |
+| `fleet-join`                | 1.0   | Guest fleet occupancy — join as a live guest occupant, loop `spur agent wait --inbox` to pull work, reply through `spur message reply`, then leave; G73 (task 1081)                                                                          |
 | `next-feature`              | 1.0   | Prompt-first feature frontier prioritizer — sync-first precondition, B3 actionability gate (cited, never restated), tiered rubric over measured signals, D1–D4 defect proposals conforming to the restructure map schema; backs `/sp:dev-find-next` |
 | `pr-reviewing`              | 1.0   | GitHub Codex PR review — PR prepare/reuse, `@codex review` request with per-HEAD dedupe, bounded polling, findings normalization, validated fix + re-review; spine SSOT `pr-review.yaml` + `scripts/pr-reviewing.ts`; backs `/sp:dev-pr-review`     |
 | `indexed-context`           | 1.0   | Cross-agent project context — anatomy/learnings/pitfalls/buglog/memory in `.spur/context/`; hook-tracked token-ledger; graceful degradation on agents without hooks                                                                        |
@@ -473,13 +475,16 @@ the agent provides an isolated context window.
 #### 4. Hooks (`hooks/`)
 
 Event-driven enforcement that runs automatically without user invocation. `hooks.json` registers
-four handlers:
+six handlers across seven events:
 
 | Event          | Matcher                               | Handler                                        | Timeout |
 | -------------- | ------------------------------------- | ---------------------------------------------- | ------- |
 | `PreToolUse`   | `Write\|Edit`                         | `superskill hook run sp task-write-guard`      | 10s     |
 | `PostToolUse`  | `Bash\|Grep\|Glob\|Read\|Write\|Edit` | `superskill hook run sp context-post-tool`     | 10s     |
 | `SessionStart` | —                                     | `superskill hook run sp context-session-start` | 15s     |
+| `SessionStart`, `UserPromptSubmit`, `Stop` | —         | `superskill hook run sp agent-lifecycle`       | 5s      |
+| `Notification` | `permission_prompt`                   | `superskill hook run sp agent-lifecycle`       | 5s      |
+| `Stop`         | —                                     | `superskill hook run sp fleet-guest-stop`      | 10s     |
 | `SessionEnd`   | —                                     | `superskill hook run sp context-session-stop`  | 15s     |
 
 **Write guard.** The `PreToolUse` hook fires on every `Write`/`Edit` tool call and checks whether
@@ -493,6 +498,11 @@ estimates the token cost of each matched tool call and appends it to `.spur/cont
 (with redaction of sensitive argument fields), `context-session-start` seeds the indexed-context
 hint on first launch, and `context-session-stop` closes out the session record.
 
+**Fleet hooks (1080/1081).** `agent-lifecycle` reports member state in the background via
+`spur agent report --state working|idle|blocked` (a permission prompt is `blocked`) — only when
+`SPUR_SPEC_ID` is set, so outside a fleet it makes no call. `fleet-guest-stop` delivers pending
+inbox work to a session joined as a fleet guest at turn end; any other session passes through.
+
 **Available but unwired:** `careful-guard.ts` ships in `hooks/` (with tests) as an opt-in
 `PreToolUse` guard that asks before destructive shell commands (`rm -rf`, `DROP TABLE`,
 `git push --force`, …) — it is **not** registered in `hooks.json`. Fail-open by contract; escape
@@ -511,6 +521,7 @@ hold `SKILL.md` and prompt-side companions only.
 | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `hooks/task-write-guard.ts`                          | Compatibility shim for older installs that still execute the script path directly. Forwards stdin to the stable PATH command `superskill hook run sp task-write-guard`, mirrors parseable PreToolUse decisions, and fails open if the runtime is unavailable. Performs no source-tree CLI lookup. |
 | `hooks/context-*.ts`                                 | Runtime for the three registered context hooks (session-start, post-tool, session-stop) — token-cost estimation + ledger append for `sp:indexed-context`                                                                                                                                          |
+| `hooks/{agent-lifecycle,fleet-guest-stop}.ts`       | Fleet hooks (1080/1081): member lifecycle reports via `spur agent report`; turn-end inbox delivery to joined guests |
 | `hooks/careful-guard.ts`                             | Opt-in destructive-command guard (unwired — see Hooks above)                                                                                                                                                                                                                                      |
 | `scripts/batch-preflight.ts`                         | Pure TABLE A STOP evaluation for `super-planner` — skip doomed pipeline launches without spawning a Skill subprocess; recovery hints map stuck statuses to a single `/sp:dev-*` hop                                                                                                               |
 | `scripts/workflow-step-profile.ts`                   | Thin glue over the generated lib bundle (`lib/step-profile.generated.mjs` from `packages/app/src/workflow/step-profile.ts`) — read-only step profile from `spur workflow trace`: per node and action-kind durations, idle gaps, session mode and `cacheHit` coverage, plus the ADR-115 cache-window flags `sp:spur-doctor` turns into workflow-optimization proposals |
@@ -518,6 +529,8 @@ hold `SKILL.md` and prompt-side companions only.
 | `scripts/dogfood-testing/validate-report.ts`         | Pure `validateReport(md)` — footer-mandatory + 7-check finalize-or-abort contract with stable error codes                                                                                                                                                                                         |
 | `scripts/daily-summary/{daily-summary,logger}.ts`    | ccusage + git-history orchestration helpers for `sp:daily-summary`                                                                                                                                                                                                                                |
 | `scripts/task-diffstat.ts`                           | 0943 triage-lane diffstat producer — numstat + untracked scan vs the run base; writes `<wbs>-diffstat.json` with the sensitive-path flag; fails safe (sensitive)                                                       |
+| `scripts/run-summary.ts`                             | Measured execution summary `/sp:dev-run` / `/sp:dev-runall` print by default (`--no-summary` skips) — windows the host transcript by `spur workflow progress` attempt timestamps; per stage/run time, wait, tool calls, total / non-cached tokens; `n/a` for subprocess windows |
+| `scripts/session-timeline.ts`                        | Measured Time/Wait/Token evidence for `sp:session-review` — reads the active Claude Code transcript read-only, one segment per operator prompt, usage deduplicated by message id, tokens split total / non-cached; `{available:false}` exit 0 when no transcript |
 | `scripts/commands/validate-flag-contracts.ts`        | Mechanical consistency gate — compares flag claims across command files, flag-glossary, cross-cutting, dev-operations, and ADR; reports disagreements                                                                                    |
 | `*.test.ts`                                          | Unit suites — in `hooks/` for guards, in `tests/<skill>/` per ADR-031 pairing                                                                                                                                                                                                                     |
 

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);
+}