@gobing-ai/spur 0.4.19 → 0.4.20

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.4.19",
+            "version": "0.4.20",
             "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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.4.19",
+    "version": "0.4.20",
     "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.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",
         "@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.20",
     "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

@@ -28,13 +28,16 @@ find this session, though the `wait --inbox` loop still works.
 
 ## Pull loop
 
-`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
+`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.
 5. Re-arm: go back to step 1 while the operator wants this session in the fleet.

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

@@ -239,10 +239,12 @@ is refused (R3), and `requiresCapabilities` stages therefore can never reach one
 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": [