The worker-parked message names --local-agent only for 'flows run' on a spec path, and 'flows resume --local-agent' silently ignores the flag

[khaliqgant]

Context

When a run parks for want of an agent worker, the remedy is --local-agent. The park message names it only in one narrow case, and the obvious recovery command silently does nothing.

packages/sdk/src/cli/run.ts:627-640 builds the message:

Run "<id>" parked at step "<step>" (agent): no worker is attached for step type "agent".

and appends the flows run --local-agent '<path>' hint only when all of command === 'run', parkedStep.type === 'agent', !options.localAgent, and !isAuthoredFlowPath(base.path) hold.

Two consequences:

1. A .flow.ts author never sees the remedy. The omission is deliberate (the bare hint would be missing --input), but the result is a message that reads as your infrastructure is missing a worker rather than pass --local-agent.
2. flows resume never sees it either, because of the command === 'run' guard.

The second half: resume accepts the flag and ignores it

flows resume advertises [--local-agent] (packages/sdk/src/cli.ts:113) and honours it only on the authored-TS path (run.ts:187, attachLocalAgent). For a YAML/JSON spec run, resumeFlow falls through to client.runResume(...) at run.ts:209 with no attachLocalAgent call. The flag is parsed, accepted, and discarded — so:

flows resume --local-agent <run-id>

parks again with the identical message. The field report lost a cycle to this, reasonably assuming resume would honour a flag it visibly accepts. I hit the park myself on a JSON spec via flows run and did get the hint, which confirms the guard is what decides.

What to change

• Name the fix in every park-for-want-of-worker message, including authored TS and resume. For TS, emit the form that is actually correct (flows run --local-agent <path> --input <...>) rather than omitting the hint.
• Make flows resume --local-agent attach a worker on the non-authored path, or refuse it with --local-agent is admitted at run start; start a new run instead of silently parking again. Either is fine; accepting and ignoring is not.

Acceptance

• Parking a .flow.ts run at an agent step prints a runnable remedy.
• flows resume --local-agent <spec-run-id> either progresses the run or refuses with a message naming what to do instead. A test asserts it never parks with the identical message twice.

Out of scope

• Whether --local-agent should be the default (separate design question).
• The empty observer URL on --local-agent runs (flows: observer publisher for local runs — flows run --local-agent minted URL is empty (UX bug) #341).