From b35717396e5d7f48654809230bb2ea1ecc5b6cba Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 6 May 2026 13:20:51 -0700 Subject: [PATCH] docs(portal): document runner action state --- CHANGELOG.md | 1 + README.md | 7 +++++-- docs/commands/list.md | 5 +++-- docs/features/blacksmith-testbox.md | 9 ++++++--- docs/features/coordinator.md | 6 ++++-- docs/orchestrator.md | 8 +++++--- docs/providers/blacksmith-testbox.md | 6 ++++++ 7 files changed, 30 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a78f41..48e206e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ - Added `provider: daytona` for Daytona sandbox leases using Daytona's SDK/toolbox for sync and command execution, with short-lived SSH access available through `crabbox ssh`. - Added `provider: islo` for delegated Islo sandbox runs using the Islo Go SDK. - Added best-effort GitHub Actions run and workflow links for external Blacksmith Testbox rows in the portal. +- Added GitHub Actions status badges, stuck filters, and copyable local stop commands for external Blacksmith Testbox rows in the portal. ### Changed diff --git a/README.md b/README.md index ae556aa..d921f20 100644 --- a/README.md +++ b/README.md @@ -160,8 +160,11 @@ blacksmith: `crabbox list --provider blacksmith-testbox` also refreshes muted external runner rows in the portal lease table from the current all-status Testbox list when coordinator auth is configured. When GitHub is reachable, Crabbox also -links those rows back to the inferred Actions run and workflow. Those rows are -visibility-only records for Blacksmith-owned Testboxes, not Crabbox leases. +links those rows back to the inferred Actions run and workflow, surfaces the +Actions status/conclusion, flags long-queued or long-running rows as `stuck`, +and exposes a copyable local `crabbox stop --provider blacksmith-testbox ...` +command. Those rows are visibility-only records for Blacksmith-owned Testboxes, +not Crabbox leases. Optional Daytona sandbox: diff --git a/docs/commands/list.md b/docs/commands/list.md index f98bdc2..1cf7aab 100644 --- a/docs/commands/list.md +++ b/docs/commands/list.md @@ -24,8 +24,9 @@ When coordinator auth is configured, the same list command also refreshes owner-scoped external runner rows in the portal lease table from the current all-status Blacksmith list. Crabbox also attempts to infer the matching GitHub Actions run/workflow from the row's repo, workflow, ref, and created time. -Missing runners from later syncs are marked stale rather than treated as Crabbox -leases. +The portal shows that Actions status, tags long-queued or long-running workflow +owners as `stuck`, and exposes a copyable local stop command. Missing runners +from later syncs are marked stale rather than treated as Crabbox leases. In `daytona` and `islo` modes, rendering is core-owned: human output and `--json` use the normalized Crabbox lease view. diff --git a/docs/features/blacksmith-testbox.md b/docs/features/blacksmith-testbox.md index 69d5f35..34cda85 100644 --- a/docs/features/blacksmith-testbox.md +++ b/docs/features/blacksmith-testbox.md @@ -100,9 +100,12 @@ also performs a best-effort sync of the current all-status Blacksmith list into the portal lease table. Those muted rows are owner-scoped visibility records for Blacksmith-owned Testboxes. When the row includes enough context, Crabbox queries GitHub Actions and links the row to the closest workflow run plus the workflow -definition. They are not Crabbox leases, do not expose box access actions, do -not heartbeat, do not participate in Crabbox expiry or cost control, and become -stale when a later sync does not see the runner. +definition. The portal also renders the Actions status/conclusion, adds a +`stuck` filter for long-queued or long-running workflow owners, and offers a +copyable local `crabbox stop --provider blacksmith-testbox ...` command for +operator cleanup. They are not Crabbox leases, do not expose box access actions, +do not heartbeat, do not participate in Crabbox expiry or cost control, and +become stale when a later sync does not see the runner. ## Auth diff --git a/docs/features/coordinator.md b/docs/features/coordinator.md index 67b7bea..b2c1522 100644 --- a/docs/features/coordinator.md +++ b/docs/features/coordinator.md @@ -66,8 +66,10 @@ normal users. It defaults to active leases when any are active, and falls back t all visible leases when the active list is empty. External runner rows, currently Blacksmith Testboxes synced from the CLI's current all-status list, render in the same grid as muted, disabled rows with search, pagination, status/provider -filters, inferred GitHub Actions run/workflow links when available, and stale -markers when the next sync no longer sees a previously visible runner. +filters, inferred GitHub Actions run/workflow links and status badges when +available, `stuck` markers for long-queued or long-running Actions owners, a +copyable local stop command, and stale markers when the next sync no longer sees +a previously visible runner. `/portal/leases/{id-or-slug}` is the authenticated lease detail page. It shows the lease state, bridge status, compact provider/target badges, latest Linux diff --git a/docs/orchestrator.md b/docs/orchestrator.md index d157773..e7aad71 100644 --- a/docs/orchestrator.md +++ b/docs/orchestrator.md @@ -50,9 +50,11 @@ Direct-provider mode does not have a central heartbeat or alarm. It labels machi Delegated external runners, such as Blacksmith Testboxes, are visibility-only records in the coordinator. `crabbox list --provider blacksmith-testbox` syncs the current all-status Blacksmith table into muted `/portal` lease-grid rows, -adds inferred GitHub Actions run/workflow links when available, and a later sync -marks missing runners stale. They do not heartbeat and do not participate in -Crabbox lease expiry, cleanup, or cost accounting. +adds inferred GitHub Actions run/workflow links and status/conclusion badges +when available, and a later sync marks missing runners stale. Long-queued or +long-running Actions owners are tagged as `stuck`, but these rows do not +heartbeat and do not participate in Crabbox lease expiry, cleanup, or cost +accounting. ## Cleanup diff --git a/docs/providers/blacksmith-testbox.md b/docs/providers/blacksmith-testbox.md index a8ce7db..1a89d16 100644 --- a/docs/providers/blacksmith-testbox.md +++ b/docs/providers/blacksmith-testbox.md @@ -80,6 +80,12 @@ blacksmith testbox stop ... Crabbox stores a per-Testbox SSH key locally, claims the Testbox for the current repo, maps IDs to friendly slugs, and prints a normal Crabbox timing summary. +When coordinator auth is configured, `crabbox list --provider blacksmith-testbox` +also syncs visibility-only Testbox rows into the portal lease table. If Crabbox +can infer the owning GitHub Actions run, the portal links the row to the run and +workflow, shows the Actions status/conclusion, flags long-queued or long-running +rows as `stuck`, and exposes a copyable local stop command. + ## Capabilities - SSH: no Crabbox SSH lease.