Run Targets, Init Mandate, And Default-Run Integration

This backlog captures three intertwined make-target and manifest-policy requirements raised against the current Makefile and system-*.cue set. They share manifests, harness scripts, and review surface, so they should land as one mainline track rather than scattered fixes.

Policy Statements

1. make run-* targets only start QEMU. Any scripted input driving, transcript assertion, timeout-based pass/fail, log greps, or harness script wrapping must live outside the run-* recipe – either in a sibling test-* target or in a host harness invoked by the user directly.
2. init usage is MANDATORY in every boot manifest. The boot init binary must be init (the capos-init ELF). Service or demo binaries such as capos-shell, credential-store, terminal-session, network-client, revocable-read, memoryobject-shared-parent, and per-demo entrypoints must be declared as services and launched by init, never as the top-level init binary.
3. make run stays the default user-facing target demonstrating a sane, safe, full-featured (as of the current state) capOS instance. When a milestone introduces a user-visible common service or binary, it must be integrated into make run – either auto-started or advertised through MOTD instructions describing how the operator reaches it – as part of the milestone’s doc-update gate.

Current State

run-* recipes that contain test logic

Snapshot from Makefile at branch base. All targets in this list embed input drivers, asserts, or harness invocations and therefore violate policy 1:

• run-smoke, run-uefi, run-net
• run-spawn, run-shell, run-restricted-shell-launcher
• run-chat, run-adventure, run-terminal
• run-credential, run-login, run-login-setup, run-local-users
• run-tcp-listen-authority
• run-revocable-read, run-memoryobject-shared
• run-ssh-host-key, run-ssh-authorized-key, run-ssh-public-key-session, run-ssh-public-key-auth, run-ssh-feature-policy
• run-ringtap-failing-call
• run-measure

(run-network-client, run-telnet(-vm), and run-ssh-gateway-terminal-host(-vm) were on this list but are now exit-2 retirement stubs with no test logic, retired with the kernel socket owner.)

Compliant run-* recipes (QEMU-only):

• run – interactive, manifest-driven, terminal on stdio.
• run-display – interactive variant with QEMU display.

Manifests violating the init mandate

Init binary is something other than init:

• system-smoke.cue – init binary capos-shell
• system-shell.cue – init binary capos-shell
• system-login.cue – init binary capos-shell
• system-login-setup.cue – init binary capos-shell
• system-local-users.cue – init binary capos-shell
• system-credential.cue – init binary credential-store
• system-terminal.cue – init binary terminal-session
• system-revocable-read.cue – init binary revocable-read
• system-memoryobject-shared.cue – init binary memoryobject-shared-parent

Manifests already compliant: system.cue, system-adventure.cue, system-chat.cue, system-spawn.cue, system-measure.cue, system-restricted-shell-launcher.cue, system-tcp-listen-authority.cue, all remaining system-ssh-*.cue (system-telnet.cue, system-network-client.cue, and system-ssh-gateway-terminal-host.cue are removed with the kernel socket owner).

Default-run feature integration gap

make run boots system.cue, which already wires the anonymous shell, the login flow with the seeded password verifier in MOTD, the chat/adventure demos, chat/adventure spawn instructions, the host-local remote-session CapSet gateway, and (as of 2026-05-14 09:07 UTC) the self-served remote-session-web-ui service. The Telnet research demo is retired (the focused make run-telnet / system-telnet.cue path and its gateway demo are removed with the kernel socket owner). Milestones still absent from the default path or its MOTD are local-user setup, terminal-session focused proofs, SSH gateway terminal host, and any future SSH shell milestone.

The default make run recipe now attaches virtio-net with host-local remote CapSet forwarding to guest port 2327 and host-local web UI forwarding to guest port 8080. Both use the same ?=-overridable host port with fallback-to-free-port behavior implemented in tools/qemu-run-hostfwd.py. Other network-backed milestones, such as the SSH gateway terminal host and future SSH shell, still require their own safe default forwarding or an explicit deferral before they can be called integrated into make run.

Open Gates

Gate A: Naming and contract

• Decide the rename split. Pick one of the two consistent options and apply it uniformly: - Strict: run and run-display are the only run-* entrypoints; every other current run-* recipe (including run-uefi, run-net, run-measure) becomes test-* regardless of whether its body is reduced to a plain QEMU start, because the policy is enforced by name, not by current contents. - Permissive: any QEMU-only recipe against the default manifest with documented firmware/device flag variations may keep a run-* name, with test-* reserved for recipes that script input or assert output. Pick this only if the policy text in CLAUDE.md/REVIEW.md can spell out the boundary unambiguously so reviewers do not have to relitigate the split per target.
• Document the chosen policy in CLAUDE.md “Build and Test” section and REVIEW.md so future targets are added under the right prefix without case-by-case judgement.

Gate B: Init mandate enforcement

• For every non-compliant manifest above, restructure so the init binary is init and the previous top-level binary becomes a service. Preserve the focused-proof intent: the service receives the same scoped caps it had as init, init holds only the bootstrap authority needed to spawn and supervise it, and the smoke/proof transcript continues to assert the same boundary properties.
• Add a manifest-loader validation rule (or mkmanifest check) that rejects any manifest whose initConfig.init.binary is not init. The rule should also reject the field being missing. Update host tests to cover the negative case.
• Update every doc that currently describes shell-led or service-led manifests as having the service as init. A 2026-04-28 12:48 UTC docs pass reconciled the current default system.cue path as standalone-init-owned while preserving focused shell-led smoke descriptions where system-smoke.cue and system-shell.cue still boot capos-shell directly. Gate B remains open until the focused manifests themselves are migrated or documented as explicit exceptions, the loader/manifest validation rule lands, and a final re-grep confirms no stale default-boot wording remains.

Gate C: Test split

• Move every scripted input driver, transcript assertion, timeout wrapper, harness invocation, and log grep currently embedded in a run-* recipe into a new test-* recipe. The run-* side, where retained, becomes a one-line qemu-system-x86_64 ... $(QEMU_COMMON) $$serial_args invocation against the same ISO.
• Keep tools/qemu-*-smoke.sh, tools/qemu-*-harness.sh, and the ringtap viewer assertion out of run-* recipes. They are acceptable inside test-* recipes or as standalone host scripts.
• Update CI hooks, developer docs, and docs/tasks/README.md checkpoints that reference make run-<x> for verification to call make test-<x> instead. Audit the migrated review-finding task records, the REVIEW_FINDINGS.md tombstone history, and the recent changelog updates so historical entries stay accurate while new gates use the renamed targets.

Gate D: Default-run feature integration

• Define an integration checklist that every milestone’s doc-update step must satisfy before close: either auto-start the new user-visible service from system.cue with safe defaults, or extend the MOTD with a clear, copy-pasteable instruction block describing how to reach the feature from the default boot.
• Backfill the integration for already-shipped milestones whose user-visible services are still absent from make run: local-user setup, terminal-session, and the SSH gateway terminal host slice. The Telnet gateway remains a focused research fixture under make run-telnet and is deliberately absent from the default operator path. For each remaining milestone, either wire the service into system.cue (preserving the default-safe posture) or add a MOTD section with the exact command. Network-backed milestones must also record the QEMU device and forwarding posture. SSH gateway terminal-host integration remains deferred until its production/non-loopback gates pass or a separate host-local development forwarding rule is reviewed. A MOTD-only addition is not sufficient for a network-backed milestone.
• Add the integration checklist to the “Stage Implementation Workflow” section of CLAUDE.md so future milestones cannot land without it.

Interaction With Paused SSH Shell Gateway Milestone

docs/tasks/README.md currently pauses the SSH Shell Gateway behind Service Object Identity Migration. When SSH work resumes, it will still have a visible goal of make run-ssh-shell and additional make run-ssh-* proofs. Without an explicit checkpoint, that milestone can land more non-compliant run-* recipes (scripted host harnesses, transcript asserts, network-only smokes) before this backlog is applied.

• Before the SSH Shell Gateway milestone closes, add Gate A’s naming decision and Gate C’s test split as a milestone-level prerequisite: the user-visible target name (run-ssh-shell vs test-ssh-shell) and the location of any host harness must conform to the chosen rename split, and make run integration must be addressed under Gate D rather than left as a separate run-ssh-* recipe. Record the decision in the SSH milestone checkpoint or block its closeout.

Sequencing

Gate A is purely policy and naming and unblocks the others. Gate B (init mandate) and Gate C (test split) can proceed in parallel on separate branches per affected manifest area, because they touch different files: B rewrites system-*.cue and may add services to init/src/main.rs, while C touches Makefile and the tools/qemu-* harnesses. Gate D follows once the test split lands so MOTD updates land alongside system.cue changes without competing with make run’s recipe.

Out Of Scope

• Renaming or relocating tools/qemu-*-smoke.sh and tools/qemu-*-harness.sh scripts. They stay where they are; only their callers change.
• Producing a new test runner that aggregates all test-* targets. That is a separate CI ergonomics task.
• Reworking the focused-proof transcript content. The intent is to preserve current proof coverage, not extend it.