@gobing-ai/spur 0.4.19 → 0.4.21

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.4.19",
+            "version": "0.4.21",
             "source": "./plugins/sp"
         }
     ]

package/config/config.example.yaml

@@ -58,6 +58,10 @@ bootstrap:
         command: >-
           spur --no-logo history import --source all &&
           spur --no-logo workflow run config/workflows/history-anatomy.yaml --quiet
+        # Without this the chain inherits the 10-minute scheduler default and dies mid-validate.
+        # 1h45m: enrich (45-52 min on a slow executor) + validate, still below the server
+        # queue's 2h visibility timeout.
+        timeoutMs: 6300000
 
 # ── Spur app section (validated by spurConfigSchema in
 # @gobing-ai/spur-config) ──

package/config/workflows/task-pipeline.yaml

@@ -660,19 +660,27 @@ states:
                 # feature credit) is owned by `plugins/sp/agents/super-reviewer.md` Output Format,
                 # which this pointer names.
                 input: >-
-                    /sp:dev-review --tasks ${vars.wbs} --auto --focus ${vars.reviewFocus} Answer contract (full: super-reviewer Output
-                    Format). Two artifacts: the `## Review` section (deriveReviewConfidence) and your captured answer
-                    (`spur task verdict` input). The answer has one `Confidence: HIGH|MEDIUM|LOW` line, EVIDENCE-derived
-                    (deriveVerifyConfidence), never the section's disposition level. End with one `Verdict: PASS|PARTIAL|FAIL` line after `| Req | Status | Evidence |` (one row per requirement; MET | PARTIAL | UNMET) and `| AC | Status |
-                    Evidence Type | Evidence |` (one row per AC; MET | PARTIAL | UNMET | N/A). Evidence types (`+` ok): test
-                    | command | static-ref | manual-review | llm-judge | n/a. Evidence cells cite a repo-root-relative `path:line`
-                    (never `/tmp`: out-of-repo blocks done) or a named check. AC rows
-                    key on the task's identities or a declared `AC-N` alias; a linked scenario covers its task and a task-local criterion
-                    needs no feature credit. Open P1-P3 blocks completion.
+                    /sp:dev-review --tasks ${vars.wbs} --auto --focus ${vars.reviewFocus}
+                    Answer contract: super-reviewer Output Format. Emit the machine-linted artifact, not a prose summary.
+                    `## Review`: deriveReviewConfidence. Captured answer (`spur task verdict`) has one `Confidence: HIGH|MEDIUM|LOW`
+                    line (deriveVerifyConfidence), never the section's disposition level.
+                    End with one `Verdict: PASS|PARTIAL|FAIL` line (plain, final) after
+                    `| Req | Status | Evidence |` (one row per requirement; MET | PARTIAL | UNMET) and
+                    `| AC | Status | Evidence Type | Evidence |` (one row per AC; MET | PARTIAL | UNMET | N/A).
+                    Evidence types (`+` ok): test | command | static-ref | manual-review | llm-judge | n/a.
+                    Cite repo-root-relative `path:line` (never `/tmp`) or named checks. AC rows use the task's identities or
+                    a declared `AC-N` alias; a linked scenario covers its task; a task-local criterion needs no feature credit.
+                    Open P1-P3 blocks completion.
+                    Also write it to `.spur/run/${vars.__runId}-review-cert.md`.
                 # The captured review answer is the run's certification input (and the
                 # `task verdict` input below): expectFile fails the step when no answer landed.
                 answerFile: .spur/run/${vars.__runId}-review-answer.txt
                 expectFile: .spur/run/${vars.__runId}-review-answer.txt
+                # The reviewer WRITES this one itself (see (c2)); declared so the composition lint can
+                # see the run path the prompt names (1233 R2).
+                inputs:
+                    - path: .spur/run/${vars.__runId}-review-cert.md
+                      kind: artifact
                 # Declared Layer-1 role (0538 R2/0710 R7): routing reason; no executor pin — role routing feeds the distinctness gate.
                 role: reviewer
                 # B7 R3/R6 (0894): declared fresh policy (reviewer default) — the action
@@ -683,6 +691,16 @@ states:
                 priority: ${vars.taskPriority}
                 compareExecutorWith: implement
                 timeoutMs: ${vars.stepTimeoutMs}
+          # (c2) The reviewer is asked to WRITE its canonical artifact to `-review-cert.md`, because
+          # the captured answer above is the agent's stdout: a reviewer that writes the artifact and
+          # then narrates its summary has the artifact overwritten by the narration, and the verdict
+          # lint fails work that is actually complete (four such runs in the G74 batch, 2026-10-24).
+          # The agent-written cert wins; when it is absent or empty the captured answer is used, so
+          # this is a strict widening of accepted inputs, never a new failure mode.
+          - kind: shell
+            options:
+                command: >-
+                    A=".spur/run/$__runId-review-answer.txt"; C=".spur/run/$__runId-review-cert.md"; [ -s "$C" ] || cp "$A" "$C" 2>/dev/null; exit 0
           # (d) `spur task verdict` owns the answer lint and the verdict derivation (task 1003
           # R2): one complete requirement row per declared requirement, AC identities resolved,
           # status/evidence vocabularies accepted, hedged or uncited evidence rejected. It
@@ -694,7 +712,7 @@ states:
             options:
                 id: review-verdict
                 executable: "${vars.spurBin}"
-                args: ["task", "verdict", "${vars.wbs}", "--from-answer", ".spur/run/${vars.__runId}-review-answer.txt"]
+                args: ["task", "verdict", "${vars.wbs}", "--from-answer", ".spur/run/${vars.__runId}-review-cert.md"]
                 resultFile: .spur/run/${vars.__runId}-review-verdict.status
                 softFail: true
           # (e) one fold, one token: PASS requires the typed verdict PASS, the artifact's own

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.4.19",
+    "version": "0.4.21",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -58,14 +58,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.5.32",
-        "@gobing-ai/ts-ai-runner": "^0.5.32",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.32",
-        "@gobing-ai/ts-infra": "^0.5.32",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.32",
-        "@gobing-ai/ts-rule-engine": "^0.5.32",
-        "@gobing-ai/ts-runtime": "^0.5.32",
-        "@gobing-ai/ts-utils": "^0.5.32",
+        "@gobing-ai/ts-db": "^0.7.1",
+        "@gobing-ai/ts-ai-runner": "^0.7.1",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.7.1",
+        "@gobing-ai/ts-infra": "^0.7.1",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.7.1",
+        "@gobing-ai/ts-rule-engine": "^0.7.1",
+        "@gobing-ai/ts-runtime": "^0.7.1",
+        "@gobing-ai/ts-utils": "^0.7.1",
         "@types/bun": "1.4.3",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "sp",
-    "version": "0.4.19",
+    "version": "0.4.21",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics."
 }

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

@@ -37,7 +37,7 @@ 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. */
+/** Preview length for legacy queued snapshots; an owned handoff carries the full body. */
 export const GUEST_STOP_BODY_CHARS = 140;
 
 /** Hard per-invocation timeout for a `spur` child the hook shells out to. */
@@ -108,20 +108,41 @@ export function stopDecisionFor(
     } catch {
         return null;
     }
-    const list = Array.isArray(rows) ? rows : undefined;
+    const payload = rows !== null && typeof rows === 'object' && 'data' in rows ? rows.data : rows;
+    const list = Array.isArray(payload)
+        ? payload
+        : payload !== null && typeof payload === 'object' && 'messages' in payload && Array.isArray(payload.messages)
+          ? payload.messages
+          : undefined;
     if (list === undefined) return null;
+    const handedOff = payload !== null && typeof payload === 'object' && 'pending' in payload;
     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);
+        .filter((row) => row !== null && typeof row === 'object')
+        .map((row) => row as { id?: unknown; from_id?: unknown; fromId?: unknown; body?: unknown; status?: unknown })
+        .filter(
+            (row) =>
+                typeof row.body === 'string' &&
+                (row.status === undefined ||
+                    (handedOff
+                        ? ['queued', 'claimed', 'delivered'].includes(String(row.status))
+                        : row.status === 'queued')),
+        )
+        .slice(0, handedOff ? undefined : 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 body = handedOff
+            ? String(row.body ?? '')
+            : String(row.body ?? '')
+                  .replace(/\s+/g, ' ')
+                  .trim();
+        const id = typeof row.id === 'string' ? ` [${row.id}]` : '';
+        const preview =
+            !handedOff && body.length > GUEST_STOP_BODY_CHARS
+                ? `${body.slice(0, GUEST_STOP_BODY_CHARS)}… (read the full message with spur message show ${String(row.id ?? '<msgId>')} --json)`
+                : body;
+        return `- ${from}${id}: ${preview}`;
     });
     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 });
@@ -155,11 +176,10 @@ export function runFleetGuestStop(payload: GuestStopPayload, deps: GuestStopDeps
             guest.id,
             '--timeout',
             String(deps.probeMs ?? GUEST_STOP_PROBE_MS),
+            '--json',
         ]);
         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);
+        return stopDecisionFor(guest.id, probe.stdout, deps.maxMessages);
     } catch {
         return null;
     }

package/plugins/sp/skills/fleet-join/SKILL.md

@@ -26,17 +26,63 @@ Pick the role whose work this session can actually do. `--session-id` defaults t
 `CLAUDE_CODE_SESSION_ID`, which is what the Stop hook matches against — without it the hook cannot
 find this session, though the `wait --inbox` loop still works.
 
-## Pull loop
+**Renewal is automatic (G75 R1, task 1279).** `join` records the *agent* process that launched this
+session — never the short-lived CLI pid — and starts one detached renewer that heartbeats the lease
+every third of the TTL. Long work with no `wait --inbox` in between no longer lets the lease expire.
+The record says which happened: `identity: 'verified'` with a `pid`/`processStartedAt` means renewal
+is running; `identity: 'unverified'` with `pid: null` means no agent ancestor could be proved, so
+nothing renews and the session must keep looping `wait --inbox` to stay joined. A rejoin from the
+same session reuses the running renewer instead of starting a second one.
 
-`spur agent wait --inbox <id> --timeout 540000` returns **0** the moment queued work exists and
-**1** on timeout. Each call heartbeats the lease, so a looping session stays joined. The Bash tool's
+## Binding a declared member (opt-in, fenced)
+
+```bash
+spur agent join --role coder --member <declared-member-id> --json
+```
+
+`--member` binds this session to one **declared** member instead of joining as a plain guest: the
+record id becomes the member id, so `wait --inbox <member-id>` addresses the declared member's inbox,
+and a supervised spawn or fleet dispatch sees the member busy through its own occupant row. It exits 2
+with a named reason for an unknown/disabled member, a role mismatch, an executor that cannot attest
+the stage capabilities, a live occupant, or a concurrent binder that lost the race. Guests without
+`--member` are unchanged — and still excluded from role selection.
+
+### Attached lifecycle reports carry the binding pin (task 1282)
+
+A bound occupant's lifecycle reports must present the host binding pin or they are refused (exit 2):
+
+```bash
+spur agent report --state working --seq <ns> --pin <ownerEpoch>:<occupancyGeneration> --json
+```
+
+The first pin-matched report completes the handshake (the host's strategy then treats this member as
+stage-visible); later reports never move it. A pin mismatch means the occupant generation moved —
+re-read `spur agent list --specs --json` instead of retrying. Plain guests keep reporting without a pin.
+
+## Pull loop (the default path — hooks are acceleration only)
+
+The durable inbox loop below is what makes a guest work on **every** host, hooks installed or not.
+Never substitute it with repeated model turns or terminal polling while the session is busy: each
+`wait --inbox` call is one bounded pull, and the session does the work between pulls.
+
+`spur agent wait --inbox <id> --timeout 540000 --json` returns **0** with up to five claimed messages
+in `{ id, pending, messages }`, settling their delivery after the output handoff. It returns **1**
+on timeout. An output failure releases the exact claims for retry; inbox listing itself never
+consumes messages. Each call heartbeats the lease, so a looping session stays joined. The Bash tool's
 own ~10-minute limit is why the timeout stays under it: one bounded call per turn, re-armed after
 the work is done.
 
-1. `spur agent wait --inbox <id> --timeout 540000 --json` → exit 0 means work is waiting.
-2. `spur message inbox --agent <id> --json` → read the messages.
+1. `spur agent wait --inbox <id> --timeout 540000 --json` → exit 0 hands this session `messages`.
+2. Read the returned messages, including their IDs. `spur message show <id> --json` can reread one;
+   `spur message inbox --agent <id> --json` is a non-consuming historical view.
 3. Do the work the message asks for.
-4. `spur message reply <msgId> "<result>"` → reply to each one.
+4. `spur message reply <msgId> "<result>"` → reply to each one. A bound occupant answering a **stage
+   request** (a `fleet:task:<requestId>:<attempt>` keyed message) MUST make the reply body the JSON
+   correlation payload — `{ "requestId": …, "attempt": …, "ownerEpoch": …, "occupancyGeneration": …,
+   "artifact": "<path or summary>" }` — with the values from the request and its own binding. The
+   host certifies the turn on that payload alone; a plain-text reply never completes a stage and the
+   request is retried to someone else. Do not answer stage requests for a binding you no longer hold:
+   a stale epoch/generation in the payload is fenced off, not promoted.
 5. Re-arm: go back to step 1 while the operator wants this session in the fleet.
 
 ## Leave
@@ -46,8 +92,29 @@ spur agent leave --json                     # the guest joined by this session
 spur agent leave my-session --json           # an explicit id
 ```
 
-Leaving releases the lease immediately. If the session dies without leaving, the lease expires and
-the reconciler pass retires the guest — pending work is never lost, it returns to `queued`.
+Leaving releases the lease immediately. A **bound** occupant's leave drains first: it stops new
+assignment, waits up to the drain grace (default 30s, `--drain-timeout <ms>` to bound it) for the
+in-flight turn to settle, then retires the record. A turn that does not settle in time is never
+failed by the leave — it stays outcome-unknown and resumable; nothing is killed. If the session dies
+without leaving, the lease expires and the reconciler pass retires the guest — pending work is never
+lost, it returns to `queued`.
+
+## Host capabilities (probed, not assumed)
+
+`bun run fleet-e2e --host-probe` writes `docs/reports/fleet-host-capabilities.json`: one row per
+host×mode with the installed binary path/version, the wake channel and the exact `--help` line that
+proves it. Anything unproven is `pull-only` with a reason.
+
+| Host | Interactive wake | Headless |
+| --- | --- | --- |
+| Codex | `app-server` (a reachable App Server connection) | `pull-only` |
+| Claude Code | `hook` (the Stop callback below) | `pull-only` |
+| Pi | `rpc` | `pull-only` |
+
+These values are **installed-host evidence**, so re-read the report instead of trusting this table
+after an upgrade. A `pull-only` row is not a defect: the loop above is the portable contract, and the
+hook/RPC/App Server channels only shorten the wait. `--real-hosts --agents <csv>` is the opt-in lane
+that drives a real host end to end; the default lane never launches one.
 
 ## Stop-hook delivery (opportunistic)
 
@@ -63,3 +130,5 @@ so the pull loop above — not the hook — is what makes a guest work anywhere.
 - Guests are **not** supervised: do not expect restart, pid ownership, or `--drain` injection.
 - Never dispatch a stage to a guest id: `spur agent run --spec <guest-id>` is refused on purpose.
 - Never hold the write slot through a guest: the guest lease is the only heartbeat (R5).
+- Renewal stops itself on agent-process death, a reused pid, a lost fence or `leave`. There is no
+  command to stop it and no daemon behind it: it lives no longer than the agent that joined.

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -26,7 +26,7 @@ that before using `run` for fan-out dispatch.
 | `trace <runId>` | Print one execution record's lineage — the run, its dispatch parents, agent session ids and streams (1076 R4, ADR-132) | `--follow` `--timeout <ms>` `--json` |
 | `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur self serve`) | `--specs` `--server <url>` `--json` |
 | `report` | Report a fleet member lifecycle state (`working`/`idle`/`blocked`) from a host hook (G73 R1/R2, task 1080) | `--state <state>` `--seq <ns>` `--spec <id>` `--json` |
-| `join` | Join the fleet as a guest occupant — a live session that pulls its own work (G73 R2, task 1081) | `--role <name>` `--id <id>` `--session-id <sid>` `--pid <n>` `--executor <name>` `--json` |
+| `join` | Join the fleet as a guest occupant — a live session that pulls its own work (G73 R2, task 1081); `--member` binds a declared member instead (G75 R3, task 1281) | `--role <name>` `--id <id>` `--member <id>` `--session-id <sid>` `--pid <n>` `--executor <name>` `--json` |
 | `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to `queued` | `[id]` `--session-id <sid>` `--json` |
 | `status` | Agent specs with live process status and member session (requires `spur self serve`) | `--server <url>` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
@@ -228,21 +228,31 @@ returns its claimed messages to `queued` and removes the record.
 | `--session-id <sid>` | Host session id (defaults to `CLAUDE_CODE_SESSION_ID`) |
 | `--pid <n>` | Process id to record |
 | `--executor <name>` | Executor name to record (informational — a guest is never dispatched to) |
+| `--member <id>` | Bind a **declared member** instead of joining as a guest (G75 R3, task 1281): resolves the enabled member, checks role/executor, requires a capability proof, and takes the fenced occupant of `guest:<member-id>`. The record id becomes the member id, so `wait --inbox <member-id>` addresses the declared member's inbox. Exits 2 with `unknown-member`, `disabled-member`, `role-mismatch`, `capability-unattested`, `live-occupant` or `collision`. Without it, `join` is unchanged |
 | `--json` | Machine-readable result |
 
 A guest carrying no executor attestation is never a stage target: `spur agent run --spec <guest-id>`
 is refused (R3), and `requiresCapabilities` stages therefore can never reach one.
 
+`--member <id>` inverts that for exactly one declared id: the binding takes the member's occupant row
+at generation `max+1` and the `guest:<member-id>` claim, so a supervised spawn or strategy dispatch
+sees the member busy through the same `hasRunning` check it already uses — no dual writers. Every
+renew re-checks both the claim epoch and that generation, so a taken-over member refuses the stale
+binder's claim/accept. `memberBinding.stageEligible` is `false` when the binder's host has only the
+`pull-only` wake channel (`bun run fleet-e2e --host-probe`), i.e. it may receive messages but no stage.
+
 ## `wait --inbox <id>` - the guest pull primitive (G73 R4)
 
 ```bash
 spur agent wait --inbox reviewer-g1 --timeout 540000 --json
 ```
 
-Returns `0` as soon as queued inbox work exists for the guest and `1` on timeout or when the id is
-not a joined guest — never a silent hang. Every call heartbeats the guest's lease, so a session that
-keeps looping stays joined; the timeout stays under the Bash tool's ~10-minute limit. The
-`fleet-join` skill loops it (wait → `spur message inbox --agent <id>` → work → `spur message reply`),
+Returns `0` after handing off up to five queued messages, with `{ id, pending, messages }` in JSON;
+`pending` is the handed-off batch count. Exact claims settle as delivered after output succeeds and
+release for retry if output fails; further queued work stays for the next pull. Returns `1` on timeout
+or when the id is not a joined guest. Every call heartbeats the guest's lease, so a session that keeps
+looping stays joined; the timeout stays under the Bash tool's ~10-minute limit. The
+`fleet-join` skill loops it (wait → work from returned messages → `spur message reply`),
 and the `fleet-guest-stop` plugin hook delivers the same messages at a turn boundary on hosts that
 support a blocking Stop hook.
 

package/schemas/spur-config.schema.json

@@ -120,6 +120,11 @@
                                         "type": "string",
                                         "minLength": 1,
                                         "description": "Five-field cron expression (minute hour day-of-month month day-of-week) evaluated in local time. Mutually exclusive with `intervalMinutes`."
+                                    },
+                                    "timeoutMs": {
+                                        "type": ["integer", "null"],
+                                        "minimum": 1,
+                                        "description": "Total child budget for this job in milliseconds. At the deadline the runtime SIGTERMs the owned process group, then SIGKILLs after the scheduler grace. `null` is explicit unlimited; absent falls back to the global scheduler default (10 min). Keep a model-driven chain below the server queue's 2 h visibility timeout so it fails its own attempt instead of being re-delivered."
                                     }
                                 },
                                 "oneOf": [