Skip to main content
← Back to list
01Issue
BugShippedSwamp Club
Assigneesstack72

Relationships

#1461 Remote execution tutorial: worker token list output and inline workflow-summary block no longer match CLI output

Opened by jasonbarnett · 7/29/2026· Shipped 7/29/2026

The remote execution tutorial works end-to-end on current main — I followed it verbatim and every functional step passed. But three pieces of its sample output no longer match what the CLI prints, which makes a reader think they've done something wrong.

Tested with swamp 20260727.193526.0-sha.03dabbb5 on linux/aarch64, in a fresh swamp repo init repo.

1. swamp worker token list column header and states are stale

This is fallout from #968, which shipped the BOUND MACHINE → ENROLLMENTS rename and the bound → enrolled state change. That issue listed the two reference pages to update (reference/remote-execution/enrollment-tokens.md and reference/remote-execution/worker-commands.md) but not the tutorial, so the tutorial kept the old output.

The tutorial's "Confirm the token exists" section shows:

NAME        STATE   EXPIRES                   BOUND MACHINE
build-node  unused  2026-06-15T11:34:58.961Z  -

Actual:

NAME        STATE   EXPIRES                   ENROLLMENTS
build-node  unused  2026-07-29T21:15:36.313Z  -

The tutorial also has this prose immediately after:

Notice the unused state and the empty BOUND MACHINE column.

and later, in "Connect a worker":

the token state changes to bound and the BOUND MACHINE column shows the worker's machine identifier.

Actual post-enrollment output is enrolled, not bound:

NAME        STATE     EXPIRES                   ENROLLMENTS
build-node  enrolled  2026-07-29T21:15:36.313Z  27e93b5e-50d1-451b-8b02-7e2a3ea8321f

Suggested fix: update both code blocks and the two prose references to ENROLLMENTS / enrolled, matching the table format #968 already specified for the reference pages.

Note: wall-clock timestamps in the sample output below are shown as <ts>. Pasting the real HH:MM:SS values gets rewritten to [IP-1]/[IP-2] by the Lab's redaction pass, which appears to match them as IPv6 addresses.

2. The @swamp/workflow-summary block in the sample output never renders inline

Under "Run the workflow", the tutorial shows:

build ✓echo-on-worker
│ executed on a worker
...
── @swamp/workflow-summary ─────────────────────────────────
# remote-demo: succeeded

1 succeeded · 0 failed · 0 skipped

The ── @swamp/workflow-summary ── section does not appear in the runner output — not for the remote run, and not for an otherwise-identical local run I used as a control. The report itself is generated correctly and its content matches the tutorial exactly, but you have to ask for it:

$ swamp report get @swamp/workflow-summary --workflow remote-demo --json
...
"markdown": "# remote-demo: succeeded\n\n1 succeeded · 0 failed · 0 skipped\n\n## Job: build (succeeded)\n\n| Step | Model | Status |\n..."

So this looks like the sample output was captured from a version that printed reports inline, or with different verbosity. Either the tutorial should drop that block and point at swamp report get, or — if inline rendering is still intended — that's a separate runner bug.

Actual output for reference:

 system │ Starting workflow remote-demo · <ts> UTC

  build │ start <ts> UTC
  build │ step echo-on-worker · remote-echo · execute · start <ts> UTC
  build │ done echo-on-worker in 729ms · <ts> UTC
  build │ completed in 729ms · <ts> UTC

 system │ Completed workflow remote-demo succeeded in 750ms · <ts> UTC

  ┌────────────────────────┐
  │ Data produced          │
  │  result    from build  │
  └────────────────────────┘

3. The │ executed on a worker line is missing — but that one is a real bug, not a docs problem

The same sample output shows the step's stdout streamed inline. It isn't, for remote steps. I've filed that separately rather than as a docs fix, since the tutorial's expectation there is reasonable and the runner is what's wrong: see the companion issue linked in the comments.

If that gets fixed, the tutorial's output becomes correct as written for this line, so it's worth resolving before editing that code block.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPED+ 1 MOREASSIGNED+ 4 MOREREVIEW+ 3 MOREPR_MERGED+ 1 MORECONTRIBUTOR_NOTIFIED

Shipped

7/29/2026, 9:05:20 PM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 assigned stack727/29/2026, 8:48:32 PM
Editable. Press Enter to edit.

jasonbarnett commented 7/29/2026, 8:25:50 PM

Companion bug for item 3: #1462 — remote step stdout is not streamed to the workflow runner, verified against a local control run with an identical model and step. The log artifact itself transfers back correctly, so it's a live-relay gap rather than data loss.

Item 3 in this issue should be resolved by #1462 rather than by editing the docs; items 1 and 2 are the actual docs fixes here.

stack72 commented 7/29/2026, 9:20:54 PM

Thanks @jasonbarnett for reporting this! The fix has been merged and a release is on its way. We appreciate your contribution to swamp.

jasonbarnett commented 7/29/2026, 10:00:42 PM

Re-validated on 20260729.212638.0-sha.45d9ed58. Items 1 and 2 are both fixed — thank you.

Item 1 confirmed. The tutorial now reads ENROLLMENTS in both code blocks and enrolled in the prose, and the CLI agrees exactly:

$ swamp worker token list          # before enrollment
NAME        STATE   EXPIRES                   ENROLLMENTS
build-node  unused  2026-07-29T22:56:32.544Z  -

$ swamp worker token list          # after the worker connects
NAME        STATE     EXPIRES                   ENROLLMENTS
build-node  enrolled  2026-07-29T22:56:32.544Z  d1483460-7fdb-411a-909b-2a43f1c3a4f4

Item 2 confirmed. The inline ── @swamp/workflow-summary ── block is gone from the sample output and replaced with a pointer to swamp report get @swamp/workflow-summary --workflow remote-demo. That command works as documented and renders the summary.

One small thing the two fixes created between them

Item 3 was fixed on the runner side in #1462, so the remote step's stdout is streamed again. But the sample output here was edited to remove that line at roughly the same time, so the docs and the CLI have crossed over — the tutorial is now missing a line the CLI does print.

Tutorial currently shows:

  build │ step echo-on-worker · remote-echo · execute · start
  build │ done echo-on-worker in 729ms

Actual on the current build:

  build │ step echo-on-worker · remote-echo · execute · start 21:57:54 UTC
  build │ executed on a worker
  build │ done echo-on-worker in 675ms · 21:57:54 UTC

This is worth restoring rather than leaving out, because that line is the tutorial's only visible evidence for the sentence immediately following the block — "The step ran on the worker, not locally." Without it the reader sees a step that succeeded but apparently produced nothing, which is the same confusion the original report was about, just from the other direction.

Entirely my fault for how I filed it: I split the runner bug out to #1462 and noted here that item 3 should be resolved there, but the docs edit landed as though item 3 were a docs fix too. Restoring the one line should settle it.

Lesser point, and possibly deliberate: the updated sample also drops the · HH:MM:SS UTC suffix that the CLI prints on each line. Eliding varying timestamps from documentation samples seems reasonable to me, so I'd leave that as-is unless you'd rather the block be literal — just flagging it so the omission is a choice rather than an oversight.

Reopening since the page is currently inaccurate, but please close again if you'd rather track the one-line restoration separately.

jasonbarnett commented 7/29/2026, 10:05:10 PM

Filed the remaining one-line docs edit as #1465, since this issue is shipped and can't be reopened. Items 1 and 2 here are confirmed fixed — no further action needed on those.

Sign in to post a ripple.