@clipboard-health/groundcrew 4.50.3 → 4.50.4

package/README.md

@@ -112,7 +112,7 @@ crew task get <TASK> [--source <name>] [--prompt]        # inspect one task or i
 crew task create "Title" --source <name> [--agent <name>] # create a source task
 crew task done <TASK> [--allow-dirty]                    # mark a no-PR task done
 crew task validate [<source>]                            # validate task content
-crew status [<TASK>]                                   # inspect current state or one task
+crew status [<TASK>] [--json [--local-only]]           # inspect current state, or emit it as JSON
 crew run [--watch]                                       # one-shot or --watch forever
 crew start <TASK>                                      # provision + launch one task now
 crew stop <TASK> [--reason <text>]                     # stop workspace, keep worktree
@@ -127,6 +127,50 @@ crew completions <bash|zsh|fish>                        # print a shell completi
 
 See [command details](./docs/commands.md) for status output, doctor behavior, and the stop/resume workflow.
 
+### Status snapshots for external monitors
+
+`crew status --json` prints two documents and writes them beside the log file:
+
+```text
+<state-dir>/status-local.json     # worktrees, run states, sessions, git status
+<state-dir>/status-remote.json    # board, pull requests
+```
+
+The two are split by cost. The local tier is local subprocess work, so it is
+safe to poll every few seconds. The remote tier is network-bound and
+rate-limited, so poll it near your `pollIntervalMilliseconds`.
+
+```bash
+crew status --json                # both tiers
+crew status --json --local-only   # local tier only; never touches the network
+```
+
+`--local-only` is a guarantee about that invocation, not a computed outcome, so
+a monitor's fast loop cannot stall on a slow board or a `gh` timeout.
+
+Three rules a reader must honor:
+
+- **Subtract locally.** `status-remote.json` ships board classification without
+  the local worktree subtraction. Remove tasks present in the local document
+  from `inProgress`, `queueReady`, and `queueBlocked` yourself. Precomputing
+  that join would report a just-dispatched task as still queued until the next
+  slow poll, which is a false statement rather than stale data.
+- **Join pull requests on the worktree directory.** `pullRequestsByWorktree` is
+  keyed by absolute worktree path, not by task, because a task with two
+  worktrees has two branches. An empty or missing entry means no pull requests
+  were found, or the `gh` lookup for that worktree failed; the two are not
+  distinguishable.
+- **Read the right timestamp.** `payload.capturedAt` describes the last
+  successful fetch; `lastAttemptAt` describes the most recent try. Read
+  `lastAttemptStatus` to answer "is the board healthy", and `capturedAt` to
+  answer "how old is this queue". A failed fetch keeps the previous payload, so
+  last-known-good data survives an outage while the document still says the
+  board is unreachable.
+
+Durations are never stored, only start instants, so a reader must derive
+elapsed time itself. A cached duration would show a frozen clock, which reads
+as "the agent stopped working" when it did not.
+
 ## Configuration
 
 Workspace settings and at least one enabled agent are required; everything else has a default.

package/dist/cli.js

@@ -144,7 +144,7 @@ const SUBCOMMANDS = {
     },
     status: {
         summary: "Print read-only groundcrew state, or one task's local/Linear status",
-        usage: "[<task>]",
+        usage: "[<task>] [--json [--local-only]]",
         invoke: statusCli,
     },
     cleanup: {

package/dist/commands/status.d.ts

@@ -1,6 +1,22 @@
+/**
+ * Renderers for `crew status`. Three output modes share this file.
+ *
+ * With no task it renders the inventory: it calls the collectors in
+ * statusCollect.ts, joins the two tiers with joinStatus, and prints text.
+ * With a task it renders that one task, doing its own I/O rather than using
+ * the collectors, because it reads the whole log where they read a tail.
+ * With --json it prints and persists the wire documents from statusSnapshot.ts.
+ * Text mode persists nothing.
+ *
+ * @see README.md#status-snapshots-for-external-monitors for the reader contract.
+ */
 import { type ResolvedConfig } from "../lib/config.ts";
 export interface StatusOptions {
     task?: string;
+    /** Emit the snapshot documents as JSON and persist them. */
+    json?: boolean;
+    /** Collect the local tier only. Guarantees this run makes no network call. */
+    localOnly?: boolean;
 }
 export declare function status(config: ResolvedConfig, options?: StatusOptions): Promise<void>;
 export declare function statusCli(argv: string[]): Promise<void>;

package/dist/commands/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAenE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAosBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AA0CnE,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4DAA4D;IAC5D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AA0hBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAM7D"}