pilotctl: render next-steps after every appstore call

[Alexgodoroja]

What & why

Autonomous agents install an app and stop caring, because nothing in a call's output tells them where the flow goes. The product demo covers install→first-call, once. This covers every call after it: each pilotctl appstore call now ends by naming the small set of recommended next commands for where the agent stands — the next step on success, and the specific fix on failure (needs_signup → the gateway, 402 → balance, missing param → a corrected call).

This is the client half. The authoring half (schema, validation, CI gates, and the 19 backfilled graphs) is app-template#89. This PR is inert until an app's metadata.json actually carries a next_steps — nothing regresses when the field is absent, which is every app today.

$ pilotctl appstore call io.pilot.primitive primitive.send_email '{...}'
{ "needs_signup": true, "activate": "primitive.signup", ... }
next: you called primitive.send_email but this host has no account yet — the call
      soft-failed and nothing was sent; sign up once and it works from then on
  1. pilotctl appstore call io.pilot.primitive primitive.signup '{}'
     why: free, zero-argument, idempotent — then re-run the call above unchanged (required first)

Design

The data lives in the sha-verified metadata; this is only the insertion mechanism. Same discipline as the product-demo render: a pure resolver + renderer that knows nothing about any specific app, plus the hook.

• No network on the call path. The graph is cached to $APP/next-steps.json at install, out of the already-sha-verified metadata.json. Every call is a local file read — no fetch, no DNS, no added latency, works offline. A call is the hottest path in the app store; it must not grow a network dependency to print a hint.
• stderr, never stdout. stdout is the call's JSON result and agents pipe it into jq; one line of prose there breaks the very workflow this exists to encourage. Verified jq still parses cleanly. --json callers get a structured next_steps object instead of prose (on the error envelope for a failed call; on stderr for a successful one).
• Failure steps drain through fatalHint via a package var, so they land after the error they fix — the same pattern motd's importantUpdate already uses, and necessary because only fatalHint knows where output ends (it owns the exit).
• No trust surface added. The bytes came out of the sha-pinned metadata; $APP already holds the app's signed manifest. A graph produces text, never an action — nothing here ever executes a recommended command.
• Fail-silent, recover()-guarded. Absent, malformed, future-schema or unmatched → the call behaves exactly as today. A hint is a nicety; a call is not. PILOT_NEXT_STEPS=off opts out.

Matching is over the outcome PAYLOAD

match tests the error text on failure and the result body on success. That is load-bearing, not a nicety: the scaffold's requireKey soft-fails an unauthenticated call with exit 0 and {"needs_signup":true}, and the CLI adapter wraps a non-zero tool exit into a successful call with {"exit":1,"stderr":...}. An outcome-only matcher would stay silent for precisely the cold agent who most needs the gateway named.

Note appstore call has exactly two observable outcomes — exit 0, or exit 1 via fatalHint. The exit code carries no classification, so everything finer must come from the payload.

Precedence

An edge that matched the actual situation beats one that merely matched the method name. Every discriminated edge outranks every undiscriminated one, however exact its from. This is a regression fix: scoring originally ranked from-exact above a match, so a cold agent calling primitive.send_email got the flow edge ("read your inbox") instead of the gateway ("sign up first").

The resolver is a deliberate duplicate of app-template's nextsteps.Resolve (pilotctl must not depend on that module — the same call appstore_demo.go's ProductDemo mirror makes). The cost of duplication is drift, and drift happened immediately: the two diverged on exactly the shadowing case, because the parity test didn't cover it. TestResolveMatchesAppTemplateSemantics now pins the shared cases, and I verified by mutation that re-introducing the old scoring fails the suite.

Verification

• go test ./cmd/pilotctl/ green; gofmt/go vet clean.
• Proven end-to-end against the live daemon and real apps, with the real authored graphs: a cold primitive.send_email renders the signup gateway marked (required first); a real sqlite.query missing-param failure renders the fix, and the recommended command then works.
• Verified stdout still parses under jq, --json emits a structured envelope, and PILOT_NEXT_STEPS=off suppresses.