@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -52,6 +52,12 @@ Flag → vars: `--auto` sets `profile=auto`, `idea_approved=true`, `design_appro
 
 ## Implementation
 
+- **Publish the generated plan first (1105):** your first tool call — before invoking the skill or
+  reading any reference — is `spur workflow show idea-pipeline.yaml --no-logo --format todo --json`
+  (the CLI resolves the project→registered→shared layer); then publish every `.plan` row's `text`
+  verbatim as the host todo list (the `steps[]` inventory when `.plan` is `null`) before the
+  pipeline's first stage — [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md)
+  run setup step 5.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - Omitted/`inline`: drive `idea-pipeline.yaml` through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md). Do not launch `spur workflow run`, `spur agent run`, or a native subagent unless the operator explicitly requests delegation.
 - `auto`/name: launch `spur workflow run idea-pipeline.yaml --async`, observe with one `workflow trace --follow`, and only report cancellation as stopped when `workflow cancel --json` returns `killed: true`.

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

@@ -1,7 +1,7 @@
 ---
 description: Fan out independent tasks or investigations in parallel via subagents — choose the right pattern and synthesize results
 role: planner
-argument-hint: "--tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json]"
+argument-hint: "--tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json] [--defer-gate]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -18,14 +18,20 @@ Wraps the **sp:parallel-execution** skill.
 | `--mode` `<fan-out\|review-panel\|investigation>` | Fan-out pattern. | fan-out |
 | `--agent` `<inline\|auto\|name>` | Who runs each dispatched slice. Parallel fan-out is dispatch, so explicit `--agent inline` runs the batch **sequentially in the host session** with a printed notice (zero dispatch); omit keeps the default fan-out semantics; `auto` tier-resolves an executor; a name pins that executor. | omit |
 | `--json` | Emit structured JSON. | off |
+| `--defer-gate` | Opt-in parallel-batch gate policy (task 1111): each task's `test` hop runs the light tier and writes `DEFERRED`; the batch runs one integrated full gate on the base ref before the feature sync. Requires `--mode parallel`; default off. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-parallel --tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json]
+/sp:dev-parallel --tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json] [--defer-gate]
 
 ## Implementation
 
+- **Publish the visible batch plan first (1105):** as the batch orchestrator, publish `A Prepare
+  batch` (A1–A4) and `Z Batch report` before the first task, then one letter per task from
+  `batch-plan.mjs waves` after freeze/order and digit children from `batch-plan.mjs task-children` at
+  task start — [execution-batch.md](../skills/spur-dev/references/execution-batch.md#27-visible-batch-plan-1105-r3)
+  § 2.7 Visible batch plan.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface) before choosing native subagents or `spur agent run`.
 - `Skill(skill="sp:parallel-execution", args="$ARGUMENTS")`

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

@@ -41,6 +41,12 @@ contract as `/sp:dev-idea`). If passed, ignore them with a one-line notice.
 
 ## Implementation
 
+- **Publish the generated plan first (1105):** your first tool call — before invoking the skill or
+  reading any reference — is `spur workflow show idea-pipeline.yaml --no-logo --format todo --json`
+  (the CLI resolves the project→registered→shared layer); then publish every `.plan` row's `text`
+  verbatim as the host todo list (the `steps[]` inventory when `.plan` is `null`) before the
+  pipeline's first stage — [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md)
+  run setup step 5.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - Omitted/`inline`: drive `idea-pipeline.yaml` through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md). Do not launch `spur workflow run`, `spur agent run`, or a native subagent unless the operator explicitly requests delegation.
 - `auto`/name: launch `spur workflow run idea-pipeline.yaml --async`, observe with one `workflow trace --follow`, and only report cancellation as stopped when `workflow cancel --json` returns `killed: true`.

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,23 @@ 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. The transcript resolves from `--transcript`, else
+`CLAUDE_CODE_SESSION_ID`, else `PI_SESSION_FILE` (the pi host sets it and no Claude session id); a
+skill-injected `<skill name="…">` body counts as activity in `injectedPrompts`, never as a segment.
 
 ## 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 +35,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,22 +21,34 @@ 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
 
+- **Bootstrap reads (1128):** before the first dispatch, read [SKILL.md § Bootstrap reads](../skills/spur-dev/SKILL.md#bootstrap-reads) and load only that mode's files — everything else under `references/` is on demand.
+- **Publish the generated plan first (1105):** your first tool call — before invoking the skill,
+  reading any reference, or showing the task — is `spur workflow show task-pipeline.yaml --no-logo
+  --format todo --json` (the CLI resolves the project→registered→shared layer); then publish every
+  `.plan` row's `text` verbatim as the host todo list (the `steps[]` inventory when `.plan` is
+  `null`) before readiness, Git, or isolation work —
+  [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8)
+  step 1 / [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md) run
+  setup step 5.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
-- 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 their owning boundaries (task 0814 R1/R3/R4/R7/R8).
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — publish the generated plan first, quick readiness before isolation, digest binding, comprehensive checks at their owning boundaries (task 0814 R1/R3/R4/R7/R8; 1105 R1).
 - Full pipeline (default `--mode full`): interactive omit/`--agent inline` uses the
   [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md) via
   `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:**
 
@@ -52,7 +64,8 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 base ref on full success, retain intact on any failure/halt/non-FF; bare form creates a fresh tree,
 `<name>` form adopts an existing worktree by name/path/branch). The lifecycle — dirty-tree precheck,
 creation or adoption, crash-safe `.spur/run/` marker, merge-or-retain, `--continue` re-entry — is
-`execution-batch.md` § Worktree isolation applied to a batch of one: marker `command` is `dev-run`
+`execution-worktree-setup.md` (creation/adoption, WT-1…WT-3b) + `execution-worktree-landing.md`
+(WT-4/WT-5) applied to a batch of one: marker `command` is `dev-run`
 and `selector` is the `<wbs>`, the derived branch is `sp/run-<wbs>-<short-id>`, and the success
 condition is the task reaching terminal `done` with no failed stage. A failing gate, a non-PASS
 verify verdict, or a HITL pause that ends the run all take the retention path.

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] [--defer-gate]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -24,25 +24,28 @@ 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 |
+| `--defer-gate` | Opt-in parallel-batch gate policy (task 1111): each task's `test` hop runs the light tier and writes `DEFERRED`; the batch runs one integrated full gate on the base ref before the feature sync. Requires `--mode parallel`; default off. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## 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] [--defer-gate]
 ```
 
 Flags: `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`,
 or `ready`), `--feature <id>` (sugar for `feature:<id>`; when the effective selector is
-feature-derived, `dev-runall` runs `spur feature check <id> --strict --json` **once** before
+feature-derived, `dev-runall` runs `spur feature check <id> --fix --json` then `spur feature check <id> --strict --json` **once** before
 resolving tasks — a non-zero strict check aborts the batch with verdict `aborted` and the
-structured findings, before any task pipeline action, task 0510 R2; scoped: `L4.scenario-unverified`
-(the expected pre-run state of any not-yet-run feature) is reported verbatim but does not abort —
+structured findings, before any task pipeline action, task 0510 R2; scoped: `L4.scenario-unverified` and `L4.verifying-incomplete-tasks`
+(expected pre-run states of a not-yet-run or reopened feature) are reported verbatim but do not abort (the non-aborting set is
+`NON_ABORTING_PREFLIGHT_CODES` in `plugins/sp/scripts/batch-preflight.ts`; `--fix` repairs land in the report's `autoRepairs`) —
 any other strict error aborts), `--mode`
 `<sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset —
-see `execution-batch.md` § Parallel isolation), `--concurrency <n>`
+see `execution-parallel-isolation.md`), `--concurrency <n>`
 (parallel-mode worker bound — at most <n> task pipelines at once, default 2; a dependent task starts
 only after its in-set dependencies are **integrated** onto the base ref), `--keep-going`
 (batch failure policy — skip a failed task's in-batch dependents, continue independents; default
@@ -57,10 +60,10 @@ report as JSON), `--wrap` (trigger
 `--worktree` `[<name>]` (run the batch in an isolated git worktree —
 FF-merge onto the base ref on full success, retain intact on any failure/halt/non-FF; bare form
 creates a fresh tree, `<name>` form adopts an existing worktree by name/path/branch; see
-`execution-batch.md` § Worktree isolation).
+`execution-worktree-setup.md` + `execution-worktree-landing.md`).
 
 **`--worktree` and parallel mode.** `--worktree --mode parallel` is **rejected** — parallel mode
-already isolates each task in its own worktree (see `execution-batch.md` § Parallel isolation), and
+already isolates each task in its own worktree (see `execution-parallel-isolation.md`), and
 reuse mode (`--worktree <name>`) has no per-task meaning. Run parallel batches without
 `--worktree`, or run them sequentially with it.
 
@@ -80,14 +83,22 @@ advancing the feature lifecycle). **was: `--next` deliberately omitted; the old
 = batch failure policy (does a failure halt the batch or skip dependents?);
 `--continue` = resume from
 checkpoint against the batch's original frozen identity — persisted plan membership, worktree
-marker, identity-filtered checkpoints as hints (execution-batch.md § Batch continuation, task
+marker, identity-filtered checkpoints as hints (execution-batch-continuation.md, task
 0919); `--next`
 = chain each task to terminal status + batch-once wrap. See `dev-operations.md` § runall for the
 full distinction.
 
 ## Implementation
 
+- **Bootstrap reads (1128):** before the first dispatch, read [SKILL.md § Bootstrap reads](../skills/spur-dev/SKILL.md#bootstrap-reads) and load only that mode's files — the section whose trigger has not fired is on demand.
+- **Publish the visible batch plan first (1105):** publish `A Prepare batch` (A1–A4) and `Z Batch
+  report` before the first task, then one letter per task from `batch-plan.mjs waves` after
+  freeze/order and digit children from `batch-plan.mjs task-children` at task start —
+  [execution-batch.md](../skills/spur-dev/references/execution-batch.md#27-visible-batch-plan-1105-r3)
+  § 2.7 Visible batch plan.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md); the resolved selector applies uniformly — eligible `agent.run` stages dispatch once to a native subagent with host fallback (0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.
-- 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).
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — publish the generated plan first, quick readiness before isolation, digest binding, comprehensive checks at owning boundaries (task 0814 R1/R3/R4/R7/R8; 1105 R1).
 - 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/context-session-start.ts

@@ -74,7 +74,7 @@ interface SessionFileBody {
  *
  * 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
+ *    `implementTimeoutMs` (45 min) and longer batches run for hours, so any wall-clock window would
  *    eventually split a run that is demonstrably still in flight.
  * 2. No marker → fall back to the {@link SESSION_REUSE_IDLE_MS} window on the `started` stamp, for
  *    hosts that nest without propagating a correlation.

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