Deploy Fishhawk locally

scripts/dev owns the whole bring-up. Do not hand-roll docker compose + go build + fishhawkd serve — scripts/dev adds the port preflight, GitSHA stamping, migrations, the /healthz nonce identity gate, and the MCP-shim banner. Run everything from the repo root (main checkout, not a .claude/worktrees/* checkout unless the user asks).

0. Stop if you are a run agent

reload (especially reload --force) restarts the fishhawkd that a run's own runner talks to, and k8s upgrades and restarts the cluster deployment. Before anything else:

top=$(git rev-parse --show-toplevel) && "$top/scripts/is-run-agent"

Continue only if it prints operator and exits 0. On any other result, stop, do nothing, and report its output to the user. That includes run-agent: …, a git error (you are not in a repository checkout), and a missing script (this checkout predates the guard). The contract lives in scripts/README.md § "is-run-agent".

Pulling main after a merge is the sync-main skill, not this one.

1. Pick the target

If the intent is ambiguous between process and k8s, use the process mode (up) — it is the daily dev loop. Never run make nuke (drops volumes) unless the user explicitly asks to destroy data.

Plain up is a no-op when fishhawkd is already running — it prints fishhawkd already running and does not rebuild. To pick up code changes, use reload.

2. Preflight (run before up/reload/k8s)

docker info >/dev/null 2>&1 && echo docker-ok || echo docker-DOWN
test -f .env && echo env-ok || echo env-MISSING
pgrep -fl '[f]ishhawk-runner .*--run-id' || echo no-live-runner
git status --short | head
uptime

• Docker down → open -a Docker, then poll until docker info succeeds (a bounded until-loop, not one long sleep).
• .env missing → cp .env.example .env; FISHHAWKD_DATABASE_URL already matches docker-compose.yml. Tell the user which optional blocks (GitHub App, OAuth) are unset; fishhawkd starts without them but logs warnings. Never print secret values from .env.
• Live runner → reload restarts fishhawkd and can strand that run's stage in running. reload refuses on its own; STOP and ask the user before passing --force. Same if the user has an in-flight fishhawk_await_* on another run.
• Want to wait instead of forcing → scripts/dev reload --when-quiet. It waits, bounded, until no runner is live and no reload-relevant restart blocker is reported, then runs the normal guards. reload ignores undispatched_child; only post-merge refuses on it. Knobs and exit codes: scripts/README.md § "reload --when-quiet".
• Dirty tree → fine for up/reload (binaries get stamped -dirty). Pulling main after a merge is the sync-main skill.
• Load average far above core count → warn the user; a starved host makes the readiness gate flaky (see operations).

3. Deploy

Run the chosen command with a generous timeout: the first build of five binaries can take a few minutes, and k8s builds an image. If your shell tool caps command duration below ~10 minutes, run it in the background and wait for it to exit.

Success markers in the output:

• postgres: ready|running and rustfs: ready|running
• rebuilt N of 5 binaries: …
• listener identity nonce-verified
• fishhawkd started (pid N) — logs: logs/fishhawkd.log
• k8s: /healthz gate + image-identity gate pass

Then verify independently:

curl -fsS "http://${FISHHAWKD_ADDR:-localhost:8080}/healthz" | python3 -m json.tool

(Read FISHHAWKD_ADDR from .env if set — e.g. 127.0.0.1:8080.) Confirm git_sha matches git rev-parse --short HEAD (with -dirty on a dirty tree).

4. Report

One short block: mode, URL, pid, git_sha, which binaries rebuilt, and the MCP banner verbatim if one printed — it is the only thing the user must act on:

• ACTION REQUIRED / shim-rebuilt banner → the user must reconnect their MCP client (/mcp in Claude Code).
• auto-swap / schema_major_shim → expectation only; verify with fishhawk_doctor (spec.valid: true) or a version-returning tool reflecting the new GitSHA. If stale: bin/fishhawk-mcp-shim --status, then reconnect the MCP client.
• fishhawk-runner is spawned fresh from bin/ per stage, and reload rebuilds it (--all). If the change touched runner stages, confirm bin/fishhawk-runner version shows the new GitSHA. Never restart fishhawkd alone: a stale runner silently ignores new stage instructions (#4183).

Troubleshooting

References

• scripts/dev (_usage for every subcommand), scripts/README.md
• scripts/README.md § Rebuild matrix and activation; operations for host/container traps
• scripts/README.md § "scripts/dev lifecycle" (readiness nonce gate, MCP banner, schema-major banner, sweep, ZERR trap), § "Live-run guard for reload / post-merge" (the reload half), § "Restart-blocker guard for reload / post-merge" and § "reload --when-quiet", § "Local k8s ergonomics"
• docs/deploy/kubernetes.md, docs/local-tls.md (FISHHAWK_DEV_TLS=1), docs/local-webhook-relay.md (FISHHAWK_DEV_WEBHOOK_RELAY=1)