feat(cli): forge try — instant-gratification onboarding (#350)

[initializ-mk]

Implements #350: a single forge try command that takes a first-time user from install to talking to a working agent whose loop they can watch, in under 60 seconds, with zero required decisions.

Stacked on #351 (keyless weather skill). The first commit (fix(skills): weather … wttr.in) belongs to #351 and dedupes on rebase once #351 lands on main — the demo hero needs a keyless weather skill. Review the seven forge try commits.

What it does

$ forge try
  Using OpenAI (signed in).
  Agent: quickstart · skills: weather · tools: http_request, datetime_now, math_calculate

you › what's the weather in Tokyo, should I pack an umbrella?
  ▸ tool   weather_current(location=Tokyo)
  ▸ egress wttr.in   ✓ allowed
  ◂ 18C, light rain this evening
agent › 18C in Tokyo with light rain tonight. Yes, take the umbrella.
  audit  {"tools":["weather_current"],"egress":["wttr.in:allow"]}

The differentiator: the agent's own audit stream (tool calls, egress checks, guardrail blocks) renders inline — the same signal the enterprise story rests on, surfaced as first-run delight.

Design (per the plan, locked)

• In-process, not HTTP. No A2A server, daemon, or port binding. A new runtime.LocalSession assembles the same coreruntime.LLMExecutor forge run uses (builtin tools + vendored skills, egress-enforced client + subprocess proxy, audit + progress hooks, provider client) minus the server/scheduler/MCP/memory. No second executor — a trimmed bootstrap around the shared sub-builders; Run() is untouched (zero risk to the server path).
• Ephemeral by default. Scaffolds into a temp dir cleaned on exit; --keep writes ./forge-quickstart. No secrets on disk for the ephemeral run.
• Reuses scaffold() via two initOptions fields (OutputDir, Preset) — no forked init logic.
• Credential auto-resolution layered over existing resolution: flags → env key (ANTHROPIC>OPENAI>GEMINI) → saved OpenAI OAuth → local Ollama → picker (TTY) → actionable error (no TTY).
• Renderer consumes existing audit events only (no new constants); lives in forge-cli, degrades to plain text (NO_COLOR / non-TTY). --quiet hides it, --audit shows full NDJSON.

Phases (one commit each)

1. Command skeleton + demo preset + ephemeral scaffold
2. Model credential auto-resolution
3. In-process REPL driving the executor
4. Visible-loop renderer
5. First-run polish + graduation hook
6. Docs: quick-start leads with forge try; pipeline moved to new ship-to-production.md
7. Tests

Verification

• Real turn via a mock OpenAI server (LocalSession makes the LLM call, history accumulates); end-to-end test renders a real datetime_now tool call.
• 12 renderer unit tests (event→line mapping, truncation, quiet, --audit echo, no-color); resolveTryProvider ordering + workspace-lifecycle tests.
• go build ./..., go vet ./..., go test ./forge-cli/... all green; gofmt + golangci-lint clean; docs broken-link check clean; no channels in the quick start.

Out of scope (named, not built)

Hosted metered demo key, forge try --ui, a second demo agent — all deferred per the plan.

[initializ-mk]

Review: forge try — instant-gratification onboarding

Reviewed the seven forge try commits (skipped the leading #351 weather commit — already reviewed on #351; it dedupes on rebase as noted). Strong, well-architected PR; the security-critical claims hold up under tracing. Merge-ready — findings are one cross-PR merge-coordination item and four low/nit polish items.

What I verified holds (the parts that matter)

• Genuinely reuses the shared executor, not a fork. LocalSession assembles the same coreruntime.LLMExecutor via the runner's sub-builders; Store is nil so history stays in memory and nothing persists. The "no second executor, Run() untouched" claim is accurate.
• Egress is actually wired, not just constructed. buildTryEgress builds both the in-process enforced client (installed on ctx via WithEgressClient in RunTurn) and the subprocess proxy, both emitting egress_allowed/egress_blocked. This is exactly the "works in isolation vs. where it's mounted" trap this line of work keeps hitting — avoided here.
• The paste-key secret doesn't leak into skill subprocesses. I chased this: try.go does os.Setenv on the pasted key, but SkillCommandExecutor.Run builds a minimal allowlisted env (clean slice, PATH+HOME, then only the skill's declared env vars + proxy/trace/OTel). The weather skill declares env.required: [], so it gets neither the key nor the ambient env. No leak in the shipped demo.
• Fail-closed where it counts: no credential + no TTY → actionable error + exit 1; ephemeral temp dir removed via defer RemoveAll(base); no secrets on disk for the ephemeral run. CI fully green.

Findings (see inline)

1. Medium (cross-PR merge coordination): buildTryEgress is a fourth copy of the egress-construction pattern, on the pre-#348 signature — compiles today only because #348 isn't merged; when #348 lands this won't compile until updated, and until then forge try silently ignores allowed_private_cidrs.
2. Low: egress-resolve failure falls back to a fully-unenforced http.DefaultClient (fail-open).
3. Low/nit: the paste-key comment claims the key is persisted under --keep, but the code never writes it to disk (the safe behavior) — reconcile comment + graduation text.
4. Nit: --yes is a dead flag (parsed, never read).
5. Nit (UX): Ctrl-C at the you › input prompt doesn't exit — signal.NotifyContext catches SIGINT but scanner.Scan() isn't ctx-aware, so it hangs until Enter/Ctrl-D. Honestly documented (Ctrl-D / /exit), but Ctrl-C is a reflex in a hero demo. Consider reading stdin in a goroutine and selecting on ctx.Done().

Nice work — the audit-stream-as-first-run-delight framing is a genuinely good idea, and the reuse discipline (one executor, trimmed bootstrap) is exactly right.

[initializ-mk]

Medium (cross-PR merge coordination). This block (security.Resolve at L205, NewEgressEnforcer here at L224, NewEgressProxy at L240) is a fourth copy of the egress-construction pattern, and it's on the pre-#348 signature — Resolve 5-arg, NewEgressEnforcer 4-arg, NewEgressProxy 2-arg. It compiles today only because #348 isn't merged yet. The moment #348 lands (which adds allowedPrivateCIDRs to all three), this file won't compile until updated, and until then forge try will silently ignore allowed_private_cidrs where the server path honors it. Since you own both PRs: land #348 first and rebase this onto it (threading allowedPrivateCIDRs through buildTryEgress), or track it as a required follow-up. Also directly reinforces #348's "consolidate the copies" note — this is now the copy most likely to diverge, since its comment says it "mirrors Run()'s egress setup" but it's a hand-maintained duplicate.

[initializ-mk]

Low. On a security.Resolve error this returns http.DefaultClient — a fully unenforced client — with only a Warn. That's a fail-open on a security path. Effectively unreachable for the fixed quickstart preset (its scaffolded egress config resolves fine), but the wrong default direction: a future config change that makes Resolve fail would silently drop egress enforcement entirely. Prefer a deny-all / empty-allowlist enforced client here so the failure mode stays closed.

[initializ-mk]

Low/nit — comment vs. code. This says the pasted key is "written to disk solely under --keep, via the scaffold env path," but it isn't: the key goes into res.EnvOverrides (session-only, consumed by NewLocalSession), while opts.EnvVars is always map[string]string{} — so the key is never persisted, even under --keep. The never-persist behavior is the correct, safe one and matches the PR's "no secrets on disk" promise, so just fix the comment. Worth surfacing the consequence in the graduation text too: forge try --keep + a pasted key writes ./forge-quickstart with no credential, so a later forge serve there needs the env var set by hand.

[initializ-mk]

Nit — dead flag. f.yes is parsed here but never read anywhere in runTry/downstream. It's advertised in --help ("assume yes to prompts") but does nothing. Either wire it (e.g. auto-select the picker's recommended default so --yes is truly non-interactive) or drop the flag.

[initializ-mk]

Addressed the review in a16dc14:

• Finding 2 (Low, fail-open egress) — fixed. buildTryEgress now fails closed on a security.Resolve error: it returns an allowlist enforcer with no allowed domains (blocks all egress) instead of the unenforced http.DefaultClient. A future config that makes Resolve fail can no longer silently drop enforcement.
• Finding 3 (Low/nit, paste-key comment) — fixed. Corrected the comment to state the key is session-only (res.EnvOverrides, consumed by NewLocalSession) and never written to disk, even under --keep, and noted the consequence: a kept agent has no credential on disk, so a later forge serve there needs the env var set by hand.
• Finding 4 (Nit, dead --yes flag) — dropped it (struct field, flag registration, and parse all removed); --help no longer advertises it.
• Finding 5 (Nit/UX, Ctrl-C at prompt) — fixed. tryREPL now reads stdin on a goroutine and selects on ctx.Done() / EOF / the line, so Ctrl-C at you › exits cleanly instead of hanging until Enter.
• Finding 1 (Medium, feat(security): allowed_private_cidrs — narrow the private-IP block (PR 1/2 for #337) #348 coupling) — feat(security): allowed_private_cidrs — narrow the private-IP block (PR 1/2 for #337) #348 is still open, so I can't rebase onto it yet; buildTryEgress compiles against current main. Added an explicit NOTE (#348 coupling) at the construction site flagging that these are the pre-feat(security): allowed_private_cidrs — narrow the private-IP block (PR 1/2 for #337) #348 signatures and must thread allowedPrivateCIDRs when feat(security): allowed_private_cidrs — narrow the private-IP block (PR 1/2 for #337) #348 lands (else forge try would silently ignore allowed_private_cidrs). Tracking it as a required rebase step — will thread the CIDRs through when feat(security): allowed_private_cidrs — narrow the private-IP block (PR 1/2 for #337) #348 merges.

Build/vet/lint clean; cmd + runtime + tryview suites green. Thanks for the careful trace on the egress-mount and paste-key-leak paths.

[initializ-mk]

Re-review: fix commit a16dc140 — all actionable findings resolved

Verified each finding against the fix diff. CI fully green (all 6 builds, Lint, Test, Integration, Doc-link).

Finding 2 (Low — fail-open egress) — ✅ resolved

On security.Resolve error, buildTryEgress now returns a deny-all enforced client (NewEgressEnforcer(nil, ModeAllowlist, nil, allowPrivateIPs) — allowlist mode with no domains blocks everything) instead of the unenforced http.DefaultClient. Fail-closed, exactly as recommended. The allowPrivateIPs computation was correctly hoisted above the error branch so both paths share it.

Finding 4 (dead --yes) — ✅ resolved

Removed from the struct, init(), and parseTryFlags — no longer advertised in --help.

Finding 3 (paste-key comment) — ✅ resolved

Comment rewritten accurately: the key is session-only (res.EnvOverrides, consumed by NewLocalSession), never written to disk even under --keep, and it now spells out the consequence (a kept agent has no on-disk credential; a later forge serve needs the env var set by hand).

Finding 5 (Ctrl-C at the you › prompt) — ✅ resolved, correctly

stdin now reads on a goroutine feeding a lines channel; the REPL selects on ctx.Done() (Ctrl-C → newline + return), eof (Ctrl-D → return), or a line. The one-read goroutine leak on exit is real but harmless (the process is exiting) and honestly acknowledged in the comment. Mid-turn cancellation and graduation-on-exit both still work.

Finding 1 (#348 coupling) — appropriately deferred with an explicit NOTE

You can't rebase onto an unmerged branch, so the right move is what was done: a prominent in-code NOTE on buildTryEgress documenting that the three constructors are on pre-#348 signatures and must thread allowedPrivateCIDRs when #348 lands, cross-referencing #348's consolidation note. Keeps the landmine visible for whoever merges #348 second.

Verdict: all fixes correct, nothing dangling. Merge-ready (modulo the #348 sequencing the NOTE now tracks).

One optional residual, non-blocking and on an effectively-unreachable branch (the fixed preset always resolves): on the resolve-error path the in-process client is now fail-closed, but it still returns proxyURL="", so skill subprocesses would run unproxied rather than blocked. Fully fail-closing that dead branch would mean refusing to start when egress can't resolve — reasonable to leave as-is behind the NOTE.