Phase 0: bootstrap install launcher

[JordanTheJet]

Phase 0 of the parent doc's delivery plan. The canonical distribution registry already exists as feat/bootstrap-install-manifest (10-target release registry + parity tests). The launcher itself is unbuilt.

Scope (per the parent doc "Bootstrap before ZeroClaw exists"):

• Generated launcher exposing exactly: bootstrap status, plan install, install, handoff
• Pinned official release origin; digest + signature verification; no arbitrary URL/command/asset/root
• Human decision required for install (harness or OS-mediated); never satisfiable by an MCP argument
• Handoff verifies product version, protocol range, capability digest, executable identity, then exits
• Parity tests against release matrix, install.sh, setup.bat, updater
• No config schema, provider catalog, or management authority in the launcher

Independent of phases 3–5; can start any time.

[JordanTheJet]

Phase 0 implemented on feat/bootstrap-launcher

Branch feat/bootstrap-launcher (3 commits, based on feat/bootstrap-install-manifest @ 324b1f26e). Not pushed; no PR yet.

New workspace crate crates/zeroclaw-bootstrap (publish = false, binary zeroclaw-bootstrap, ~1930 lines of source + ~1040 lines of tests). No new dependency enters the workspace graph — clap, reqwest, serde, serde_json, sha2, hex, flate2, tar, zip and tempfile were all already declared in the root package.

Surface

Exactly four subcommands, and no others:

status                                   detect platform, existing binary, verified version
plan   [--tag <TAG>]                     select one artifact; print version, channel, source,
                                         digest, signature status, install path, privilege
install --approve <PLAN_DIGEST> [--tag]  download and install exactly the approved artifact
handoff [--verify-only] [--expect-binary-sha256 <SHA256>]

There is no --url, --install-root, --prefix, --asset, --command, --config, or positional argument anywhere, and the launcher never reads or writes config.toml.

How the refusals are enforced

Most of them are structural rather than defensive, which is the part worth reviewing:

• No arbitrary URL. Every request is a PinnedUrl, and that type has no constructor accepting caller-supplied text. It can only be built from a compile-time origin constant plus a charset-validated ReleaseTag plus a registry-generated asset name. "Download from somewhere else" is unrepresentable, not merely rejected.
• Target/artifact mapping is generated. Everything comes from zeroclaw_dist::DIST_TARGETS — the triple list, the archive extension, the primary binary name. There is no second target table in the launcher to drift from the registry.
• Approval is a copied value. install recomputes the plan and requires a token equal to sha256(canonical plan). The canonical form covers tag, target, asset, both URLs, expected artifact digest, install dir, binary path, and privilege — so a re-pointed tag, a republished artifact, or a changed install root invalidates an existing approval instead of silently altering the install. The token is not derivable from the request, so a model can request an install but cannot satisfy the decision.
• Order of operations. approval → fetch → digest check → extract → write. No byte reaches the install path before the digest matches. Archive entries are additionally vetted for path traversal and link entries, and only the registry-named top-level binary is installed.
• Fail closed. Unsupported target, unpublished asset, malformed tag, digest mismatch, protocol-major mismatch, and incomplete advertisement are all distinct typed errors with no fallback path.
• No silent replacement. An existing binary whose --version cannot be established is reported UNVERIFIABLE and produces a repair recommendation. It is never overwritten and never executed further.

Host identity

Host triple comes from a build-script constant recording Cargo's own TARGET, so musl vs gnu and armv7 vs arm are exact. This deliberately avoids the divergence crates/zeroclaw-dist/tests/parity.rs already records for src/commands/update.rs, which has no libc input and mis-resolves musl hosts onto glibc archives.

What "verified" means right now — please read this before merging

Digest verification is real. Signature verification is not performed.

The launcher fetches SHA256SUMS from the pinned origin, looks up the artifact by exact file-name field, binds that digest into the approved plan, and hashes the download before installing. That establishes the bytes are the ones the release published.

It does not establish that the release is authentic. The checksum manifest is fetched over the same channel as the artifact, so an attacker controlling the origin controls both. Releases do carry GitHub-hosted SLSA provenance attestations (and SHA256SUMS is itself attested), but verifying them needs a Sigstore verifier the launcher deliberately does not carry. So plan reports:

signature         SLSA provenance published; NOT verified by this launcher
                  verify out of band with:
                    gh attestation verify <asset> --repo zeroclaw-labs/zeroclaw --signer-workflow ...

Closing that gap is a real follow-up, and it is a dependency decision (a Sigstore verifier is not a small dep). The checklist item "digest + signature verification" is therefore half done, and I did not want to imply otherwise in the output text.

Install locations — parity, not a new default

Unix families: $CARGO_HOME/bin (default $HOME/.cargo/bin), matching where install.sh puts a prebuilt binary. Windows: %USERPROFILE%\.zeroclaw\bin, matching setup.bat. Both per-user, so no elevation is ever requested. Flagging it explicitly because it is a deployment default: if the launcher should instead prefer ~/.local/bin on Unix for harness use, that is a one-line change but it should be a deliberate call.

Version selection

plan defaults to the launcher's own compiled version and accepts --tag. It deliberately does not resolve a moving releases/latest pointer the way install.sh and update.rs do, because a moving pointer cannot be approved in advance — the human approves a specific artifact digest.

Evidence

All gates green on the final tree:

Gate	Result
cargo fmt --all -- --check	clean
cargo clippy --workspace --all-targets -- -D warnings	clean
cargo test -p zeroclaw-bootstrap	71 passed, 0 failed
cargo test -p zeroclaw-dist (registry parity)	10 passed, 0 failed
cargo build --release -p zeroclaw-bootstrap	ok
cargo doc --no-deps -p zeroclaw-bootstrap	ok

No network in any test. The origin is an in-process map keyed by the exact URL the launcher constructs, and a NeverFetches fetcher proves the refusal paths abort before any download.

Two mutation checks, both confirmed and both restored byte-identical (install.rs sha256 3a7cdfb…b79fc before and after each):

1. Neutralised the digest comparison → refuses_an_artifact_whose_digest_does_not_match_the_approved_plan failed, and failed by installing the substituted payload.
2. Made a missing approval token return Ok(()) → refuses_an_install_with_no_approval_token and the_approval_check_is_independently_enforced both failed; the first tripped the NeverFetches guard, proving the unapproved path had proceeded to download.

Real-origin smoke check (manual, outside the test suite): plan against v0.8.4 resolved fac22f9af2f940fd3bb7e77deb42fac7d052dfc81212812694703f7c20d34edf for zeroclaw-aarch64-apple-darwin.tar.gz, matching the published SHA256SUMS line.

Not covered

• Signature/attestation verification, as above.
• Parity tests against install.sh / setup.bat / the updater. The launcher's mapping is generated from the registry, and the registry is already parity-checked against all three on the base branch, so the chain holds transitively. A launcher-specific parity test asserting the launcher's origin string equals install.sh's would still be worth adding; I did not add one because it would need to reach outside crates/zeroclaw-bootstrap.
• Windows and Android paths are untested at runtime. Plan/status logic for both is covered by unit tests, but the handoff stub server is a shell script, so those tests are Unix-only. The .zip extraction path has no test with a real zip fixture.
• zeroclaw control --mcp does not exist on this base branch (it lives on feat/control-mcp-readonly). Handoff is written against the control MCP protocol v1 spec — advertisement at result._meta.zeroclaw_control, fields zeroclaw_version / control_protocol_version / config_schema_version / capabilities / capability_digest — and tested against a stub emitting a canned initialize response. It has never been run against the real server. That integration wants a check once the branches meet.
• i18n. AGENTS.md routes user-facing CLI text through Fluent, but the launcher cannot depend on zeroclaw-runtime (it must run before ZeroClaw exists). Its strings are plain literals, as in xtask and tools/fill-translations. Flagging in case that needs a different answer.

Minor defect noticed, not fixed (out of lane)

install.sh:337 looks up the expected digest with grep "$asset_name" SHA256SUMS | awk '{print $1}'. That is a substring match, so an asset name that is a prefix of another published name would return two digests and the comparison would fail closed — safe today, but ambiguous. The launcher matches the exact file-name field instead.

[JordanTheJet]

Orchestrator verification of the launcher build: 71/71 tests and clippy re-run clean; --url injection rejected by the CLI surface; mutation checks (digest bypass, approval bypass) reviewed in the report with byte-identical restores.

Real-server handoff now verified (closing the report's biggest gap): zeroclaw-bootstrap handoff --verify-only --expect-binary-sha256 <digest> run against the actual zeroclaw control --mcp binary from feat/control-mcp-readonly @ 09dca5a reported: binary sha256 match, product 0.8.4 binary/advertisement agreement, control protocol 1.0 within accepted range >=1.0 <2.0, config schema 3, capability digest sha256:1c3d71e0…34a5 — identical to the digest observed in the live Claude Code/Codex sessions.

Branch pushed: feat/bootstrap-launcher @ 0a4b20f.

Remaining before this issue closes, needing Jordan:

• Signature stance: the launcher verifies SHA256SUMS but prints SLSA provenance published; NOT verified by this launcher rather than pulling in a Sigstore verifier — confirm or direct otherwise.
• Install location: $CARGO_HOME/bin (Unix) / %USERPROFILE%.zeroclaw\bin (Windows), parity with install.sh/setup.bat — confirm.
• No moving latest pointer (plan pins a tag) — confirm.
• Real-artifact install exercise + Windows/zip fixtures + a direct origin-parity assertion.

Also noted from the report: install.sh:337 matches SHA256SUMS by substring (safe today, fails closed, but ambiguous) — worth a one-line upstream fix someday.

[JordanTheJet]

Entry-point routing now names configure as the destination

status and handoff now express the first-run decision explicitly:
detect whether ZeroClaw is installed; installed → configure (via handoff
to the control server); absent → install first, then configure. A
machine-readable next action line (configure | install, derived
from the recommendation) lets a harness branch without parsing prose.

Absent branch (status):

  existing binary   none

  next action       install
  ZeroClaw is not installed — run `plan`, then `install`, then `handoff` to install and configure this instance

Installed branch (status):

  version           0.8.4 (verified)
  ...
  next action       configure
  ZeroClaw is installed — run `handoff` to connect to the control server and configure this instance

Handoff's verification summary now names the same destination and stays
honest about it — the control surface is read-only by default,
zeroclaw control genesis is the first step when there is no trust root
yet, and mutations require the separate operator enablement ceremony:

  next              configure this instance on the control server this hands off to:
                    run `zeroclaw control genesis` first if it has no trust root yet;
                    the surface is read-only until an operator enables mutations

A new crates/zeroclaw-bootstrap/README.md documents the full flow a
model-driven harness follows (status → branch → plan/human-approval/install
→ handoff → configure/genesis), referencing the launcher's operation names
and the control subcommands rather than duplicating any schema.

No new dependency, CLI flag, or arbitrary input was added; the refusal
surface is unchanged. Gates green: cargo fmt --all -- --check,
cargo clippy --workspace --all-targets -- -D warnings,
cargo test -p zeroclaw-bootstrap (73, up from 71), the zeroclaw-dist
registry parity tests, and cargo build --release -p zeroclaw-bootstrap.

[JordanTheJet]

zeroclaw-bootstrap mcp — the four operations as one stdio MCP surface

Landed on feat/bootstrap-launcher (additive; the status/plan/install/handoff CLI subcommands and install --approve <digest> are unchanged). A harness now has one uniform first-run interface: while ZeroClaw is absent this process speaks bootstrap-MCP over newline-delimited JSON-RPC 2.0 on stdio; on bootstrap.handoff it execs zeroclaw control --mcp, so the same pipe continues against the installed control server. Each tool delegates to the existing typed logic (status.rs / plan.rs / install.rs / handoff.rs) — no logic was rebuilt. Serde/serde_json only; no new dependency.

initialize advertises a pre-install surface distinct from the control server (_meta.zeroclaw_bootstrap: bootstrap_protocol_version: "1.0", surface: "pre-install-bootstrap", distinct_from: "zeroclaw-control", install_requires_human_presence: true). ping is a lifecycle method, not a tool.

tools/list (verbatim)

{
  "tools": [
    {
      "name": "bootstrap.status",
      "description": "Detect the host target and any binary already installed at the per-user install path (its version and sha256, or that it is absent or unverifiable), plus the next action (configure|install). Read-only.",
      "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
    },
    {
      "name": "bootstrap.plan",
      "description": "Resolve the one pinned install: version, channel, source origin, artifact digest, signature status, install path, privilege, and the plan digest a human copies to approve. Reads the release checksum manifest; downloads no artifact and writes nothing.",
      "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
    },
    {
      "name": "bootstrap.install",
      "description": "Return the exact terminal command a human runs to install (`zeroclaw-bootstrap install --approve <plan-digest>`). Installing changes the host and needs human presence, which the MCP pipe does not have, so this tool performs NO download and NO install and returns a human_approval_required result. No argument, including a correct plan digest, makes it install.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "approve": {
            "type": "string",
            "description": "Optional plan digest. Reported back as whether it matches the current plan; it NEVER authorizes an install — only a human typing the approval command at a terminal does."
          }
        },
        "additionalProperties": false
      }
    },
    {
      "name": "bootstrap.handoff",
      "description": "Verify the installed control server's identity (product version, control-protocol range, capability digest, executable identity) and, on success, replace this process with `zeroclaw control --mcp` so the same pipe becomes the control channel. With no verified binary it does NOT exec and returns a route-to-install result instead.",
      "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
    }
  ]
}

Why the MCP path cannot install

stdio is the JSON-RPC channel, so on the MCP path there is no TTY and no human-presence surface. bootstrap.install therefore never installs. It resolves the current plan (reading the checksum manifest, exactly as plan does — no artifact download, no filesystem write), computes the plan digest, and returns a typed human_approval_required result naming the exact command a human must type at a real terminal:

{
  "content": [{ "type": "text", "text": "Installation changes this host and is NOT performed over MCP … a human must run this exact command at a terminal:\n\n    zeroclaw-bootstrap install --approve sha256:…\n\nNo MCP argument — not even a correct plan digest — triggers an install …" }],
  "isError": false,
  "structuredContent": {
    "status": "human_approval_required",
    "performed_install": false,
    "approval_command": "zeroclaw-bootstrap install --approve sha256:…",
    "plan_digest": "sha256:…",
    "supplied_approval_matches_current_plan": true,
    "target": "…", "install_dir": "…", "binary_path": "…",
    "reason": "the MCP pipe is non-interactive and has no human-presence surface …"
  }
}

The property is structural, not a runtime check:

• There is no branch in the MCP install handler that calls install::install. The only code path that downloads and writes a binary is the CLI install subcommand, which reaches it through --approve <plan-digest> — a token the human copies across from plan, hashed over the exact plan, and not derivable from the request.
• The approve argument exists only to be reported back (supplied_approval_matches_current_plan). Passing the exact correct digest still returns human_approval_required and writes nothing — so "no argument makes it install" is demonstrable, not just asserted.
• The OS user-presence is the human typing zeroclaw-bootstrap install --approve … at a terminal. That is the presence surface; the MCP pipe is not.

bootstrap.handoff execs only after handoff::verify succeeds (product version, control-protocol range, capability digest, executable identity all agree). With no verified binary — absent, unverifiable, wrong protocol, or wrong product version — it does not exec and returns { "status": "route_to_install", "executed_handoff": false, "next_action": "install" }.

Evidence

• Gates green: cargo fmt --all --check; cargo clippy --workspace --all-targets -D warnings (29 members); cargo test -p zeroclaw-bootstrap 73 → 91; cargo test -p zeroclaw-dist (registry parity) 10; cargo build --release. No Cargo.toml/Cargo.lock change; the cli_surface refusal tests (no arbitrary URL/root/asset/command flag) still pass.
• Three mutation checks, each reverted byte-identical: making install install on a matching digest fails the install-invariant test ("MCP install must not write a binary"); letting handoff exec without a verified binary fails the route-to-install test; leaking a non-frame line to stdout fails the clean-frames test.