fix(os-rv64): split firstboot and agent readiness markers

Author: lalalune

packages/chip/scripts/check_os_rv64_chip_boot_contract.py

@@ -267,7 +267,10 @@ def run_check(args: argparse.Namespace) -> dict[str, object]:
     agent_start_pos = marker_position(first_boot, "systemctl start")
     add_if(
         findings,
-        ready_pos is not None and agent_start_pos is not None and ready_pos < agent_start_pos,
+        "elizaos-ready" in first_boot
+        and ready_pos is not None
+        and agent_start_pos is not None
+        and ready_pos < agent_start_pos,
         "elizaos_ready_marker_before_agent_start",
         "`elizaos-ready` is emitted before the first-boot script attempts to start elizaos-agent.service",
         f"{rel(FIRST_BOOT)} READY_LINE offset={ready_pos} systemctl_start offset={agent_start_pos}",

packages/os/linux/variants/elizaos-debian-riscv64/STATUS.md

@@ -27,8 +27,8 @@ to see exactly what landed.
 | Piece                                 | Commit         | Owns                                                                                                                                                                                                                                                                                                                                                                                  |
 |---------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | 1. Build (Wave 4 live-build)          | `c4656f1810`   | `Dockerfile`, `build.sh`, `auto/config`, `config/package-lists/elizaos.list.chroot`, `config/hooks/normal/0010-elizaos-agent.hook.chroot`, `config/hooks/normal/0020-grub-efi-riscv64.hook.binary`, `config/includes.binary/extlinux/extlinux.conf`, `manifest.json.template`. End-to-end `lb config` → `lb build` → verify → checksum → manifest pipeline against Debian Trixie riscv64. |
-| 2. Boot (qemu-virt harness)           | `ebf816ea14`   | `Makefile` (boot targets), `scripts/qemu_virt_boot.sh`, `scripts/qemu_virt_smoke.py`, `scripts/test_qemu_virt_smoke.py`. Wraps `qemu-system-riscv64 -M virt`, emits an evidence JSON conforming to schema `eliza.os.linux.qemu_virt_boot.v1`, greps the serial transcript for the literal marker `elizaos-ready`.                                                                       |
-| 3. Userland (Wave 2B systemd bootstrap)| `31bd8f13ba`   | `config/hooks/normal/0030-elizaos-userland.hook.chroot`, `config/includes.chroot/etc/systemd/system/elizaos-{agent,first-boot}.service`, `config/includes.chroot/usr/lib/elizaos/first-boot.sh`, `config/package-lists/elizaos-runtime.list.chroot`, `docs/userland-startup.md`. Creates the `elizaos` system user, the state + config dirs, and writes the `elizaos-ready` line on `/dev/ttyS0`. |
+| 2. Boot (qemu-virt harness)           | `ebf816ea14`   | `Makefile` (boot targets), `scripts/qemu_virt_boot.sh`, `scripts/qemu_virt_smoke.py`, `scripts/test_qemu_virt_smoke.py`. Wraps `qemu-system-riscv64 -M virt`, emits an evidence JSON conforming to schema `eliza.os.linux.qemu_virt_boot.v1`, greps the serial transcript for the literal marker `elizaos-firstboot-ready`.                                                                       |
+| 3. Userland (Wave 2B systemd bootstrap)| `31bd8f13ba`   | `config/hooks/normal/0030-elizaos-userland.hook.chroot`, `config/includes.chroot/etc/systemd/system/elizaos-{agent,first-boot}.service`, `config/includes.chroot/usr/lib/elizaos/first-boot.sh`, `config/package-lists/elizaos-runtime.list.chroot`, `docs/userland-startup.md`. Creates the `elizaos` system user, the state + config dirs, and writes the `elizaos-firstboot-ready` line on `/dev/ttyS0`. |
 | 4. Gate (e2e runbook + release-check) | `cc10b9f001`   | `Makefile` (release-check targets), `docs/e2e-qemu-virt.md`, `scripts/check_release_manifest.py`, `scripts/test_check_release_manifest.py`. Fail-closed validator against `packages/os/release/schema/elizaos-os-release-manifest.schema.json`. BLOCKED informational by default; FAIL under `--strict`.                                                                              |
 
 ## Happy-path command sequence
@@ -82,9 +82,9 @@ make -C packages/os/linux/variants/elizaos-debian-riscv64 release-check-test
 | Row                          | Why it is BLOCKED                                                                                                                                                                                                                                                                                                                                                                                            | Owner / cross-link                                                                                                                                                          |
 |------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `lb build` run               | Multi-hour build, multi-GB pull from `deb.debian.org` Trixie riscv64 mirror. Cannot run from inside an interactive sub-agent; not committed as a binary artifact. Recipe in [`docs/e2e-qemu-virt.md`](docs/e2e-qemu-virt.md) step 2.                                                                                                                                                                          | builder host or CI; external dependency = Debian Trixie riscv64 mirror availability                                                                                         |
-| `qemu-virt-boot` transcript  | Requires the artifact above + `qemu-system-riscv64` on the host. Until the transcript exists, the `qemu-virt-boot` evidence row in `manifest.json.template` stays `status: missing` and `release-check` reports BLOCKED. No transcript is committed; no `boot_completed: true` is fabricated.                                                                                                                | this variant's `qemu_virt_boot.sh` + `qemu_virt_smoke.py`; consumes systemd `elizaos-ready` line from piece 3                                                                |
+| `qemu-virt-boot` transcript  | Requires the artifact above + `qemu-system-riscv64` on the host. Until the transcript exists, the `qemu-virt-boot` evidence row in `manifest.json.template` stays `status: missing` and `release-check` reports BLOCKED. No transcript is committed; no `boot_completed: true` is fabricated.                                                                                                                | this variant's `qemu_virt_boot.sh` + `qemu_virt_smoke.py`; consumes systemd `elizaos-firstboot-ready` line from piece 3                                                                |
 | `grub-efi-riscv64-boot`      | Hook `config/hooks/normal/0020-grub-efi-riscv64.hook.binary` stages `BOOTRISCV64.EFI` + `grub.cfg` but no boot transcript is captured. Same external dependency chain as the qemu-virt row.                                                                                                                                                                                                                  | chip-side BSP recipes: [`packages/chip/docs/sw/u-boot/README.md`](../../../../chip/docs/sw/u-boot/README.md), [`packages/chip/docs/android/riscv-bringup.md`](../../../../chip/docs/android/riscv-bringup.md) |
-| elizaOS agent binary         | First-boot unit can write `elizaos-ready` even when the agent is absent, but `/opt/elizaos/STATUS_LATER_AGENT_BINARY` stays present until the agent installer hook replaces the placeholder with a real `/opt/elizaos/bin/elizaos`. Until then `elizaos-agent.service` stays `failed (ExecStart not found)`.                                                                                                  | elizaOS agent-release pipeline (`packages/os/linux/agent/`); not in this variant's scope                                                                                    |
+| elizaOS agent binary         | First-boot unit can write `elizaos-firstboot-ready` even when the agent is absent, but `/opt/elizaos/STATUS_LATER_AGENT_BINARY` stays present until the agent installer hook replaces the placeholder with a real `/opt/elizaos/bin/elizaos`. Until then first boot enables `elizaos-agent.service` but does not start it and must not emit `elizaos-agent-ready`. | elizaOS agent-release pipeline (`packages/os/linux/agent/`); not in this variant's scope                                                                                    |
 | `u-boot-extlinux-boot`       | `not-required` for the GRUB EFI qemu-virt artifact. Staged for distroboot follow-up evidence only; not in scope for the current wave.                                                                                                                                                                                                                                                                        | chip BSP / U-Boot recipe ([`packages/chip/docs/sw/u-boot/README.md`](../../../../chip/docs/sw/u-boot/README.md))                                                            |
 | `hardware-board-boot`        | No silicon. No physical board. No host hardware available to this repo. `not-required` for the qemu-virt artifact; for any hardware variant it stays BLOCKED until the chip board bring-up team produces a transcripted boot on real silicon. No hardware claim is made by any of the four landing commits.                                                                                                  | chip board bring-up team (`packages/chip/docs/evidence/linux/`)                                                                                                             |
 

packages/os/linux/variants/elizaos-debian-riscv64/config/includes.chroot/usr/lib/elizaos/first-boot.sh

@@ -8,9 +8,9 @@
 #   2. Create /var/lib/elizaos (state) and /etc/elizaos (config) with the
 #      right ownership.
 #   3. Generate a stable instance UUID at /etc/elizaos/instance-id.
-#   4. Emit a single `elizaos-ready instance=<uuid>` line on the serial
-#      console (/dev/ttyS0) so the qemu-virt harness can detect boot
-#      completion deterministically.
+#   4. Emit a single `elizaos-firstboot-ready instance=<uuid>` line on the
+#      serial console (/dev/ttyS0) so the qemu-virt harness can detect OS
+#      first-boot completion deterministically.
 #   5. Enable elizaos-agent.service and start it when the agent binary exists.
 #   6. Disable this first-boot service so it does not run again.
 #
@@ -80,17 +80,17 @@ fi
 #    Best-effort: if /dev/ttyS0 is not present (e.g. on a board without a
 #    virt-style 16550), fall back to the kernel printk path so the line
 #    still ends up in dmesg.
-READY_LINE="elizaos-ready instance=${INSTANCE_UUID}"
+FIRSTBOOT_READY_LINE="elizaos-firstboot-ready instance=${INSTANCE_UUID}"
 if [ -w "${SERIAL_CONSOLE}" ]; then
     log "emitting ready marker on ${SERIAL_CONSOLE}"
-    printf '%s\n' "${READY_LINE}" > "${SERIAL_CONSOLE}"
+    printf '%s\n' "${FIRSTBOOT_READY_LINE}" > "${SERIAL_CONSOLE}"
 elif [ -w /dev/kmsg ]; then
     log "serial console ${SERIAL_CONSOLE} not writable; using /dev/kmsg"
-    printf '%s\n' "${READY_LINE}" > /dev/kmsg
+    printf '%s\n' "${FIRSTBOOT_READY_LINE}" > /dev/kmsg
 else
     log "WARN: neither ${SERIAL_CONSOLE} nor /dev/kmsg writable; ready marker only in journal"
 fi
-log "${READY_LINE}"
+log "${FIRSTBOOT_READY_LINE}"
 
 # 5. Enable the agent. Early RISC-V images intentionally ship with a
 #    STATUS_LATER placeholder until the agent binary is packaged, so do not
@@ -102,6 +102,17 @@ if [ -x "${AGENT_BIN}" ]; then
     timeout 10s systemctl start --no-block elizaos-agent.service || {
         log "WARN: elizaos-agent.service failed to queue"
     }
+    if timeout 30s sh -c 'until systemctl is-active --quiet elizaos-agent.service; do sleep 1; done'; then
+        AGENT_READY_LINE="elizaos-agent-ready instance=${INSTANCE_UUID}"
+        if [ -w "${SERIAL_CONSOLE}" ]; then
+            printf '%s\n' "${AGENT_READY_LINE}" > "${SERIAL_CONSOLE}"
+        elif [ -w /dev/kmsg ]; then
+            printf '%s\n' "${AGENT_READY_LINE}" > /dev/kmsg
+        fi
+        log "${AGENT_READY_LINE}"
+    else
+        log "WARN: elizaos-agent.service did not become active within 30s"
+    fi
 else
     log "agent binary missing at ${AGENT_BIN}; leaving elizaos-agent.service enabled but not started"
 fi

packages/os/linux/variants/elizaos-debian-riscv64/docs/e2e-qemu-virt.md

@@ -140,9 +140,11 @@ The boot harness writes a JSON evidence file conforming to the
 ```
 
 The transcript log must additionally contain the literal marker
-`elizaos-ready` — the elizaOS first-boot unit prints that line once the
-agent is up. If the marker is missing the release-manifest gate (Step 4)
-reports FAIL, not PASS.
+`elizaos-firstboot-ready` — the elizaOS first-boot unit prints that line once
+OS userland initialization has completed. Agent liveness is a separate
+`elizaos-agent-ready` marker and is not proven by the qemu-virt release gate.
+If the first-boot marker is missing the release-manifest gate (Step 4) reports
+FAIL, not PASS.
 
 Expected duration: **2 – 6 min** for an end-to-end boot once the
 guest kernel is cached. Allocate at least 2 GB of guest RAM and one
@@ -173,7 +175,7 @@ What the validator does:
 5. Asserts `boot_completed === true` and that `iso_sha256` matches
    the `sha256` on the parent manifest entry.
 6. Asserts the transcript referenced by `transcript_path` contains
-   the literal `elizaos-ready` marker.
+   the literal `elizaos-firstboot-ready` marker.
 7. Aggregates the result. `STATUS: BLOCKED` is informational;
    `STATUS: FAIL` is a release blocker.
 
@@ -223,9 +225,9 @@ Other external dependencies that this runbook does **not** unblock:
   riscv64 set is incomplete, `lb build` exits non-zero. The validator
   has no way to distinguish a mirror outage from a real config break;
   the failing `lb build` log is the source of truth.
-- **elizaOS agent binary publication.** The first-boot unit needs a
-  published agent. Until that ships, the `elizaos-ready` marker will
-  never appear and Step 3 stays BLOCKED.
+- **elizaOS agent binary publication.** The first-boot marker can appear before
+  the agent exists. Until the RV64 image packages `/opt/elizaos/bin/elizaos`,
+  no `elizaos-agent-ready` marker or agent health evidence should be claimed.
 - **Real board boot.** The qemu-virt boot is necessary but not
   sufficient. The `hardware-board-boot` row stays BLOCKED until the
   chip team produces a transcripted boot on real silicon.
@@ -239,7 +241,7 @@ Other external dependencies that this runbook does **not** unblock:
 | Evidence row missing the JSON file       | `BLOCKED: evidence file not present: <path>`                             |
 | `boot_completed=false` in evidence       | `FAIL: qemu-virt boot did not complete`                                  |
 | `iso_sha256` mismatch                    | `FAIL: iso_sha256 mismatch between manifest and evidence`                |
-| Transcript missing `elizaos-ready`       | `FAIL: transcript missing required marker: elizaos-ready`                |
+| Transcript missing `elizaos-firstboot-ready`       | `FAIL: transcript missing required marker: elizaos-firstboot-ready`                |
 | Schema OK, every row collected, marker present | `PASS: release manifest gate ok`                                   |
 
 `PASS` from this runbook means the qemu-virt half of the promotion

packages/os/linux/variants/elizaos-debian-riscv64/docs/userland-startup.md

@@ -29,7 +29,7 @@ elizaos-first-boot.service     (Type=oneshot, RemainAfterExit=yes)
         ├─ create /var/lib/elizaos (0750, elizaos:elizaos)
         ├─ create /etc/elizaos    (0750, root:elizaos)
         ├─ generate /etc/elizaos/instance-id (UUIDv4)
-        ├─ write "elizaos-ready instance=<uuid>" to /dev/ttyS0
+        ├─ write "elizaos-firstboot-ready instance=<uuid>" to /dev/ttyS0
         ├─ systemctl enable + start elizaos-agent.service
         ├─ touch /var/lib/elizaos/.first-boot-complete
         └─ systemctl disable elizaos-first-boot.service
@@ -67,14 +67,14 @@ The ordering guarantees that:
 The first-boot script writes a single line to `/dev/ttyS0`:
 
 ```
-elizaos-ready instance=<uuid>
+elizaos-firstboot-ready instance=<uuid>
 ```
 
 The `<uuid>` matches the contents of `/etc/elizaos/instance-id` and is
 generated once on the first successful boot. This is the **only**
 ready signal the qemu-virt harness depends on; do not relocate it,
-reformat it, or emit additional `elizaos-ready` lines from any other
-unit. The harness greps for `^elizaos-ready instance=` on the captured
+reformat it, or emit additional `elizaos-firstboot-ready` lines from any other
+unit. The harness greps for `^elizaos-firstboot-ready instance=` on the captured
 serial transcript.
 
 If `/dev/ttyS0` is not writable (e.g. on a real RISC-V dev board with
@@ -96,13 +96,13 @@ binary. Instead, the chroot hook
 drops a marker file at
 `/opt/elizaos/STATUS_LATER_AGENT_BINARY`.
 
-This separates two qualitatively different boot outcomes:
+This separates first-boot completion from agent liveness:
 
-| Outcome | `/opt/elizaos/STATUS_LATER_AGENT_BINARY` | `elizaos-ready` on `ttyS0` | `elizaos-agent.service` state |
-|---|---|---|---|
-| Boot fine, agent missing | present | **yes** | `failed` (ExecStart not found) |
-| Boot fine, agent live    | **absent** | **yes** | `active (running)` |
-| Boot broken              | irrelevant | **no**  | irrelevant |
+| Outcome | `/opt/elizaos/STATUS_LATER_AGENT_BINARY` | `elizaos-firstboot-ready` on `ttyS0` | `elizaos-agent-ready` on `ttyS0` | `elizaos-agent.service` state |
+|---|---|---|---|---|
+| Boot fine, agent missing | present | **yes** | **no** | not started |
+| Boot fine, agent live    | **absent** | **yes** | **yes** | `active (running)` |
+| Boot broken              | irrelevant | **no**  | **no** | irrelevant |
 
 When the build pipeline gains the ability to install a real elizaOS
 release artifact, the hook that lays the binary down at

packages/os/linux/variants/elizaos-debian-riscv64/scripts/check_release_manifest.py

@@ -18,7 +18,7 @@
                  in the default mode and exit 1 under ``--strict``.
 * ``FAIL``     — release blocker: schema mismatch, ``iso_sha256``
                  mismatch, ``boot_completed=false``, or a missing
-                 ``elizaos-ready`` marker in the transcript. Always
+                 ``elizaos-firstboot-ready`` marker in the transcript. Always
                  exit 1 regardless of ``--strict``.
 
 The validator deliberately uses the same vocabulary as the chip readiness
@@ -57,9 +57,10 @@
 # ``missing`` rows stay informational BLOCKED.
 PROMOTED_STATUSES: frozenset[str] = frozenset({"candidate", "published"})
 
-# Marker the elizaOS first-boot unit prints once the agent is up. The qemu-virt
-# boot transcript must contain this literal string for the gate to PASS.
-REQUIRED_TRANSCRIPT_MARKER = "elizaos-ready"
+# Marker the elizaOS first-boot unit prints once OS userland initialization
+# completes. Agent liveness is intentionally tracked by a separate
+# ``elizaos-agent-ready`` marker and is outside this qemu-virt release gate.
+REQUIRED_TRANSCRIPT_MARKER = "elizaos-firstboot-ready"
 GRUB_TRANSCRIPT_MARKERS: tuple[str, ...] = (
     "GNU GRUB",
     "Booting `elizaOS Live (RISC-V 64)'",