feat(scripts): consolidate session-startup checks into a single script

[marcoaperez]

AGENTS.md's "Session startup" section currently asks the agent to run four separate checks each session — git update, environment/sandbox detection, plug-in detection, PROJECT.md presence — each a separate round-trip before the first useful prompt.

What this adds

session_start.py runs all of them in one call, fault-tolerant (each check returns OK/WARN/FAIL/SKIP and a crash in one check never takes down the rest), with a compact one-line-per-check summary and a --json mode for programmatic use:

agentic-fm session start — 2026-07-06 22:07
  [  OK] git        up to date with origin/main
  [  OK] env        native macOS with osascript
  [  OK] companion  companion v0.8.0 · no plug-in → OSS path
  [SKIP] project    no PROJECT.md (normal in collaborator clones)
  [SKIP] context    CONTEXT.json absent (normal until a solution has been explored)
Verdict: ready

Adds one more check not currently documented as part of startup: CONTEXT.json presence, age, and task description, so a stale or missing CONTEXT.json is flagged up front instead of surfacing later as a confusing missing-reference error.

AGENTS.md gets an additive callout pointing at the script; the existing manual steps are left in place as the reference for what each check means and as a fallback when the script isn't available.

stdlib only, no new dependencies.

Test plan

• Ran against this repo — all 5 checks report correctly
• --json mode produces valid, well-shaped JSON
• --strict exits 1 only when a check FAILs (not on WARN/SKIP)

[agentic-fm]

Thanks for this, @marcoaperez — I ran it and it works well: each check is isolated and fault-tolerant, the summary is clean, and it correctly degrades in a sandboxed/broken-git environment. I want it in.

One gap before merge. session_start.py's companion check hardcodes :8765 (it probes both http://127.0.0.1:8765 and http://local.hub:8765), so it breaks for anyone who runs the companion on a non-default port — and some users do change it. Right now there is no clean config the companion server reads for this: the port lives in a COMPANION_BIND_HOST env var + a --port argument + a hardcoded DEFAULT_PORT, while automation.json carries a separate top-level companion_url that isn't wired to any of it.

We are going to add a proper companion config in agent/config/ as the single source for the companion host/port. Could you update session_start.py to:

1. accept an optional --companion-url (or --port) argument, and
2. source the address from config — fall back to automation.json's existing companion_url, then to :8765 — instead of hardcoding the two URLs?

That makes the check correct for custom ports and forward-compatible with the config we are adding. Everything else looks good; happy to land it once the port is no longer hardcoded. 🙏

[agentic-fm]

The canonical companion config this PR was waiting on has landed in acc480e — agent/config/companion.json is now the single source of truth for the companion host/port, replacing the drift-prone hardcodings.

What changes for this PR: the session-start companion check should stop hardcoding :8765 and instead use client-reach resolution:

--companion-url / --port flag → COMPANION_URL env → agent/config/companion.json (companion.advertise_host + companion.port) → legacy automation.json companion_url (deprecation window) → local.hub:8765 fallback.

deploy.py already implements this exact chain as _resolve_companion_url() (and companion_server.py has _load_companion_config() for the read) — please mirror/reuse those rather than re-deriving, so all consumers resolve identically. The resolution model and precedence are documented in agent/docs/COMPANION_SERVER.md.

This unblocks the PR — please rebase onto acc480e, repoint the hardcoded probe, and add the --companion-url/--port overrides at the top of the chain.

[petrowsky]

@marcoaperez Simply point your agent at this PR if you're using gh and it should be able to do a refactor.