fix(agents): build every onboarding prompt from one discovery-first builder

[roodboi]

Final behavior

Issue: HACK-1137 (unit E2).

• hack init --with, hack agent onboard, hack agent init and the hack-init MCP prompt all call one builder in src/agents/onboarding-prompt.ts (buildOnboardingPrompt). Each one embeds the same repo inventory from buildInitAssistantReport (the corrected W12/fix(agents): correct onboarding inventory and harden onboarding prompt #291 inventory: bun.lock/bun.lockb, nested workspace lockfiles and package-manager conflicts, non-JS runtimes, runtime pins by name, and explicit discovery limits).
• Discovery first: a ## Repo inventory (pre-computed by Hack) section comes before Phase 1. Phase 1 now starts by confirming that inventory.
• Each prompt is exactly frame.before + core + frame.after. renderOnboardingCore produces the core, which is byte-identical for every entry point on the same repo. renderOnboardingFrame owns the only per-entry text. That text is fixed and never repeats repo values:
  • init --with: one leading line that says whether this run scaffolded .hack/ or skipped init because .hack/ already existed.
  • agent init: keeps its trailing hack agent patterns pointer.
  • agent onboard and MCP: no framing. The MCP message envelope is unchanged.
• Repo state alone sets mode, project name and dev host: existing-project when a .hack/ project is found (values from its config), otherwise new-project. The repo root is the enclosing hack project root, or the hack init root when there is no project.
• init-assistant.ts no longer assembles a prompt. It exports renderInitAssistantInventory, and only the builder calls it.
• MCP hack-init gains an optional repoRoot argument. Relative values resolve against the session cwd. With repoRoot, the prompt matches hack agent onboard for that repo, and mode/projectName/devHost are ignored. Without it, nothing is scanned (the server cwd may be HOME or /) and the core states Not run: … named no repoRoot. Inventory failures return closed, value-free protocol errors that never echo the path, config values or the underlying message: E_PROJECT_NOT_FOUND: Path not found., or <HackErrorCode>: hack-init could not inventory the repo..

Behavior changes to review

• hack init --with after a fresh scaffold now hands off in existing-project mode, with the header "adopt the existing hack setup" and the instruction "refine .hack/, do not re-run init". Before, it said "stand up hack" and told the agent to run hack init --auto. The framing line says the scaffold is new. A post-init handoff always runs with .hack/ present, so this is the only way it can share a core with agent onboard.
• An existing setup with no configured dev_host now shows the placeholder <dev_host> instead of a guessed <slug>.hack or the new-project <project>.hack.local default. The removed resolveExistingInitHost was the only producer of the guess.
• hack agent init now reads .hack/ config (name/dev host), so a malformed config fails it the same way it already failed hack agent onboard.
• agent onboard, init --with and the MCP prompt now include package.json script commands (the inventory's dev and setup scripts), which only agent init showed before.

No canonical guidance render changed (the /hack-init skill, plugins and instruction sources are untouched), so plugin generation, fingerprints and the revision are unchanged. The CLI surface is unchanged, so docs/reference/cli.md was not regenerated. Docs updated: docs/guides/agent-first-setup.md and docs/agent-guidance.md.

Validation

• New tests/onboarding-entry-parity.test.ts:
  • The CLI entry points run as source-CLI children through privateCliEnv (private HOME, isolated Docker client, empty PATH, HACK_NO_INTERACTIVE=1). The MCP prompt runs in-process over InMemoryTransport, so it also runs in CI.
  • On a fixture repo before init, agent onboard, agent init and MCP (absolute and relative repoRoot) all equal frame + renderOnboardingCore(collectOnboardingContext(repo)).
  • After init --auto --with claude (scaffolded) and a second init --auto --with codex (existing), both handoffs plus agent onboard, agent init --path apps/web and MCP (with conflicting caller mode, name and host) equal one shared core.
  • Content: the corrected inventory lines and explicit limits are present. Pin values and env-file contents are absent.
  • MCP parity without repoRoot (the not-run core). Closed MCP refusals (missing path; native marker) never echo the path.
  • Static guard: only the builder module renders the core or inventory, and the three callers use buildOnboardingPrompt(.
• Updated tests: onboarding-prompt, init-assistant, setup, init-with-command.
• bun test on 15 focused files: onboarding, init-assistant, setup, init-with-command, agent-onboard-command, mcp-prompts, onboarding-handoff, integration-ownership, cli-spawn-env-isolation, agent-instruction-source, agent-plugin-generation, mcp, mcp-session-context, mcp-inspect-tools. Result: 163 pass, 0 fail.
• bun run --cwd packages/cli typecheck: 0 errors. bun run --cwd packages/cli check: 0 errors (the existing warnings are not in changed files). The changed tests were linted explicitly and are clean.

Negative controls (source mutations, each restored afterward)

Each mutation below was killed by the parity test file:

• agent onboard renders without the inventory (the pre-change shape): parity test fails, and so does the static guard.
• agent init wraps the shared prompt in its own title: parity test fails.
• init --with frames an existing .hack/ as freshly scaffolded: parity test fails.
• MCP ignores repoRoot: parity and refusal tests fail.
• MCP caller projectName leaks into the repo-derived core: parity test fails.
• An MCP refusal echoes the caller path: the refusal test fails.

The in-file negative-control test also checks that a dropped inventory signal, a missing inventory, a leaked frame, or a missing frame each produce a parity issue.

One mutation survived, as expected. Having agent init pass the hack init root instead of startDir is equivalent behavior: the builder resolves the enclosing project root itself.

Remaining gaps

• The full bun test suite (CI mode) had not finished locally when this PR opened, so hosted CI is the gate for the rest of the suite.
• No real agent client (Claude Code or Codex) was launched with the new prompt. The tests cover only the printed fallback and the MCP protocol response.
• MCP repoRoot scanning is bounded only by the inventory's existing scan caps. A caller who passes / or HOME gets the same scan cost that hack agent init --path / has today.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}