hz

hz is the reactive local planner for cloud launches. Planning happens in a continuous reactive loop that supports investigation, targeted clarification, native plan editing, and explicit finalization — all while keeping local state authoritative until the user approves.

Core commands

hz plan

hz plan "<task>" --repo <path> starts or resumes a local planning session in a deterministic launch bucket:

• Fresh runs enter the reactive planner loop, show live progress during turns, and create mutable planner state.
• Interrupted sessions resume from the exact working state (open items, diagnostics, investigation findings) rather than regenerating approximations.
• Approval is required to finalize: this produces mission-draft.json, plan-history.json, finalized plannerPlan (embedded inside mission-draft.json), and infrastructure artifacts.
• Superseding revisions rotate history and clear stale downstream state before execution continues.

hz mission run

hz mission run "<task>" --repo <path> uses the same normalized request identity as hz plan:

• Resumes partial planning if no finalized draft exists.
• Reuses finalized local drafts without replanning or mutating mission-draft/plan-history.
• Continues into upload, mission creation, and monitoring after finalization.

Both commands avoid retired /plan/* routes in the normal planning flow.

Local artifacts

Planning state is stored under ~/.hz/cloud-launches/<request-id>/:

| Artifact | Purpose | |----------|---------| | request.json | Normalized request identity and launch bootstrap metadata | | planner-state.json | Mutable planner state: milestones, work items, assertions, dependencies, clarification items, diagnostics, investigation findings | | mission-draft.json | Finalized mission snapshot (created only on approval) | | plan-history.json | Finalized revision history and supersession lineage | | infrastructure/ | Generated deployables, TDD skills, and idempotent init scripts |

Resume, reuse, and supersession all hang off deterministic launch identity derived from normalized task text plus sorted, deduped absolute repo paths.

Auth and environment

Planning uses the existing CLI auth surface:

• HZ_API_KEY, or
• hz auth login (stores auth in ~/.hz/config.json)

An explicitly empty HZ_API_KEY is treated as an error.

Optional remote sync (finalized-only)

If both of these are set, hz plan will sync the finalized local plan after approval:

• HZ_STATE_STORE_URL
• HZ_STATE_STORE_MISSION_ID (target mission-scoped store identifier)

Optional overrides:

• HZ_STATE_STORE_TOKEN (otherwise HZ_API_KEY is reused)
• HZ_STATE_STORE_STEP_ID
• HZ_STATE_STORE_WORKER_SESSION_ID

Rules:

• Sync runs only after local finalization.
• Sync uses mission-scoped /missions/{missionId}/plan routes with optimistic versioning.
• Read-back is verified after PUT.
• Retries are bounded.
• Sync failures warn, but the local draft remains authoritative and retryable later.
• Retired /plan/* routes are not used in normal flow.

Build and test

npm install
npm run typecheck
npm run build
npm test

Built-binary sanity checks:

node dist/hz.mjs plan --help
node dist/hz.mjs mission run --help

Architecture invariants

1. Local state is authoritative until explicit finalization.
2. Working state and finalized artifacts are separate surfaces — downstream consumers only see finalized outputs.
3. Reactive editing preserves stable IDs for unchanged entities across edits and superseding revisions.
4. Blocking diagnostics prevent finalization.
5. Normal planning flow makes zero requests under /plan/.
6. hz plan and hz mission run agree on request identity, resume, and reuse semantics.
7. Remote sync is finalized-only — the mission-planner store is a finalized snapshot + step-state store, not a live remote planner.

Notes for developers

• Planner decisions and validation outcomes are persisted so interruptions are recoverable and inspectable.
• Mutable planner state is distinct from bootstrap state (request.json) and finalized artifacts (mission-draft.json).
• Review-only planner state (e.g., planningReview) is excluded from downstream mission payloads and remote sync.
• Step-state sync uses version-aware rebasing when the same worker session spans superseding syncs.
• The deployed mission-store verification path uses a dedicated mission ID; retired routes currently return 404/405 (functionally equivalent to the ideal 410 Gone contract).