@gobing-ai/spur 0.4.20 → 0.4.21

package/.claude-plugin/marketplace.json

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

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.20",
+    "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.33",
-        "@gobing-ai/ts-ai-runner": "^0.5.33",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.33",
-        "@gobing-ai/ts-infra": "^0.5.33",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.33",
-        "@gobing-ai/ts-rule-engine": "^0.5.33",
-        "@gobing-ai/ts-runtime": "^0.5.33",
-        "@gobing-ai/ts-utils": "^0.5.33",
+        "@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.20",
+    "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/skills/fleet-join/SKILL.md

@@ -26,7 +26,44 @@ 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.
+
+## 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**
@@ -39,7 +76,13 @@ the work is done.
 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
@@ -49,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)
 
@@ -66,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,11 +228,19 @@ 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