feat(cli): follow a run, wait for one, and tail the log (#6813)

* feat(cli): follow a run, wait for one, and tail the log

Three commands the surface was missing, each polling or streaming something
the generated command layer cannot express.

`workflows run --follow` renders the SSE the execute route already emits, so
a multi-minute agent run stops printing nothing until it ends. It rides on
the generated `run` leaf rather than a sibling command — same operation, one
different response encoding — and delegates to the handler it replaced, so
every non-follow invocation still runs the generated path. Answer text,
thinking and tool calls go to stderr; only the final envelope reaches
stdout, so redirecting still yields the result. Reasoning and tool frames
need the `X-Sim-Stream-Protocol` header, which is sent only when asked for,
because negotiating also switches answer text to live chunks the server may
retract.

`workflows runs wait` closes the loop `--async` opens. Terminal is
completed, failed or cancelled; `redacting` is not, since a run whose output
is still being scrubbed is not yet a run you can read. A time pause keeps
polling because the server resumes it, and a human pause stops with the
resume command rather than burning the bound and calling it a timeout.
Distinct exit codes keep cancelled and paused from reading as failure. The
bound is `--wait-timeout` and not `--timeout`, because SIM_TIMEOUT_SECONDS
already bounds one request and two knobs of the same name hide each other.

`logs follow` tails runs as they arrive. Dedup keys on run id, not on the
timestamp: a schedule fan-out starts many runs in the same millisecond, so a
timestamp watermark either drops the siblings or reprints them. JSON output
is one object per line, because a follow never closes an array, and the
table header is printed once so columns stay aligned across polls.

* fix(cli): disclose a truncated burst, and clear a stale retry notice

Two review findings in `logs follow`, both verified against the code first.

The page budget bounds one poll so an enormous burst cannot stall the follow,
but on reaching it the live cursor was discarded: the remainder is older than
everything collected and the next poll restarts at the newest page, so those
runs were never printed and nothing said so. The budget stays — draining
without one trades a bounded poll for unbounded buffering in a process meant
to run for hours — but hitting it now warns on stderr, naming the count and
pointing at `sim logs list`. That notice is written even off a terminal,
because a piped log is where an unexplained hole is hardest to spot.

The retry notice was cleared after the empty-rows check, so a poll that
recovered but found nothing left "retrying in Ns…" on screen while the follow
was already healthy. Clearing now happens as soon as a poll succeeds.

The second test needed two failures to be worth anything: the teardown clears
the line either way, so what separates fixed from broken is whether a bare
erase lands before the second notice or only at the end. The first version
passed against the bug.

* test(cli): pin that a mixed page is the watermark, not a truncation

A page holding a run already printed proves the follow caught up, so the
truncation warning must not fire there — that is how every healthy poll
terminates, and warning would report a hole on the ordinary path. The
straggler sharing that page is still collected, because the filter takes
every unprinted row on it rather than only those above the known one.

* fix(cli): say when the requested backlog was larger than a page holds

The logs API clamps `limit` into 1–1000 rather than rejecting it, so
`logs follow -n 5000` came back with 1000 rows, anchored the floor to that
partial page, and said nothing. The seed already knew — it computes whether
a live cursor remained — but the caller discarded the answer.

Guarded on both halves. Fewer rows than asked for is only a shortfall when
more were waiting: a workspace holding ten runs answers `-n 50` with ten and
nothing is missing, so warning on the row count alone would fire on every
small workspace. The cursor is what separates the two.

Author: waleedlatif1

apps/docs/content/docs/en/cli/logs.mdx

@@ -66,3 +66,25 @@ sim logs list [options]
 | `--folder <value...>` | No | Folder path as shown in the app; the leading / is optional (space-separated, or @path / @- with one value per line). |
 
 </CommandTable>
+
+## Watch runs as they arrive, printing each new run once
+
+```bash
+sim logs follow [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <id>` | No | Only follow runs of this workflow (repeatable). Defaults to ``. |
+| `--folder <path>` | No | Only follow runs of workflows in this folder (repeatable). Defaults to ``. |
+| `--trigger <type>` | No | Only follow runs with this trigger type (repeatable). Defaults to ``. |
+| `--level <level>` | No | Only follow runs at this severity. Accepted values: `info`, `error`. |
+| `--details <level>` | No | Response detail level; full names each run’s workflow. Accepted values: `basic`, `full`. Defaults to `full`. |
+| `-n, --lines <count>` | No | Recent runs to print before watching. Defaults to `10`. |
+| `--interval <seconds>` | No | Seconds between polls. Defaults to `3`. |
+
+</CommandTable>

apps/docs/content/docs/en/cli/reference.mdx

@@ -1538,6 +1538,30 @@ sim logs list [options]
 
 </CommandTable>
 
+### sim logs follow
+
+Watch runs as they arrive, printing each new run once
+
+```bash
+sim logs follow [options]
+```
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <id>` | No | Only follow runs of this workflow (repeatable). Defaults to ``. |
+| `--folder <path>` | No | Only follow runs of workflows in this folder (repeatable). Defaults to ``. |
+| `--trigger <type>` | No | Only follow runs with this trigger type (repeatable). Defaults to ``. |
+| `--level <level>` | No | Only follow runs at this severity. Accepted values: `info`, `error`. |
+| `--details <level>` | No | Response detail level; full names each run’s workflow. Accepted values: `basic`, `full`. Defaults to `full`. |
+| `-n, --lines <count>` | No | Recent runs to print before watching. Defaults to `10`. |
+| `--interval <seconds>` | No | Seconds between polls. Defaults to `3`. |
+
+</CommandTable>
+
 ## sim mcp-servers
 
 Also spelled `sim mcp-server`.
@@ -3190,6 +3214,35 @@ sim workflows runs resume <runId> [options]
 
 </CommandTable>
 
+### sim workflows runs wait
+
+Wait for a run to reach a terminal state, then show it
+
+```bash
+sim workflows runs wait <runId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | Yes | Unique workflow run identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--wait-timeout <seconds>` | No | Give up after this many seconds, or 0 to wait indefinitely (default: 3600). Bounds the whole wait; SIM_TIMEOUT_SECONDS bounds one request. |
+
+</CommandTable>
+
 ### sim workflows create
 
 Create Workflow
@@ -3389,6 +3442,9 @@ sim workflows run <id> [options]
 | `--include-file-base64` | No | Inline eligible output files as base64 content. Rejected when `async` is true. |
 | `--no-include-file-base64` | No | Send --include-file-base64 as false. |
 | `--base64-max-bytes <value>` | No | Maximum total bytes of file content to inline as base64. Rejected when `async` is true. |
+| `--follow` | No | Stream the run as it happens; progress on stderr, result on stdout. The stream reports only success and output, so the result omits the run id and timings a non-streaming run returns. |
+| `--include-thinking` | No | Show model reasoning while following (requires --follow). |
+| `--include-tool-calls` | No | Show tool calls while following (requires --follow). |
 
 </CommandTable>
 

apps/docs/content/docs/en/cli/workflows.mdx

@@ -117,6 +117,33 @@ Resume a paused run (output is included in JSON or YAML output)
 
 </CommandTable>
 
+## Wait for a run to reach a terminal state, then show it
+
+```bash
+sim workflows runs wait <runId> [options]
+```
+
+**Arguments**
+
+<CommandTable>
+
+| Argument | Required | Description |
+| --- | --- | --- |
+| `runId` | Yes | Unique workflow run identifier. |
+
+</CommandTable>
+
+**Options**
+
+<CommandTable>
+
+| Option | Required | Description |
+| --- | --- | --- |
+| `--workflow <workflowId>` | Yes | Workflow ID. |
+| `--wait-timeout <seconds>` | No | Give up after this many seconds, or 0 to wait indefinitely (default: 3600). Bounds the whole wait; SIM_TIMEOUT_SECONDS bounds one request. |
+
+</CommandTable>
+
 ## Create workflow
 
 ```bash
@@ -300,6 +327,9 @@ sim workflows run <id> [options]
 | `--include-file-base64` | No | Inline eligible output files as base64 content. Rejected when `async` is true. |
 | `--no-include-file-base64` | No | Send --include-file-base64 as false. |
 | `--base64-max-bytes <value>` | No | Maximum total bytes of file content to inline as base64. Rejected when `async` is true. |
+| `--follow` | No | Stream the run as it happens; progress on stderr, result on stdout. The stream reports only success and output, so the result omits the run id and timings a non-streaming run returns. |
+| `--include-thinking` | No | Show model reasoning while following (requires --follow). |
+| `--include-tool-calls` | No | Show tool calls while following (requires --follow). |
 
 </CommandTable>
 

packages/sim-cli/src/commands/protocol/index.ts

@@ -2,8 +2,11 @@ import { Command } from 'commander'
 import { attachFileGet } from './files-get'
 import { attachFileUpload } from './files-upload'
 import { attachKnowledgeDocumentUpload } from './knowledge-document-upload'
+import { attachLogsFollow } from './logs-follow'
 import { attachResourceDirectoryCommands } from './resource-directory'
 import { attachTableImport } from './tables-import'
+import { attachWorkflowRunFollow } from './workflow-run-follow'
+import { attachWorkflowRunWait } from './workflow-run-wait'
 
 function group(program: Command, name: string): Command {
   const existing = program.commands.find((command) => command.name() === name)
@@ -43,10 +46,18 @@ export function attachProtocolCommands(program: Command): void {
     createFolder: 'createTableFolder',
   })
 
-  attachResourceDirectoryCommands(group(program, 'workflows'), {
+  const workflows = group(program, 'workflows')
+  attachResourceDirectoryCommands(workflows, {
     kind: 'workflow',
     resources: 'listWorkflows',
     folders: 'listWorkflowFolders',
     createFolder: 'createWorkflowFolder',
   })
+  // Both augment commands the generated pass already built — `run` gains
+  // `--follow`, and `runs` gains `wait` — so they must attach after it, which is
+  // the order `buildProgram` calls them in.
+  attachWorkflowRunFollow(workflows)
+  attachWorkflowRunWait(group(workflows, 'runs'))
+
+  attachLogsFollow(group(program, 'logs'))
 }