docs - zygaena/zyginit

root / docs
docs Plain Text 17222 lines 642.8 KB
# zyginit — Architecture and Design

**Status:** Implementation complete — testing on Hammerhead pending
**Date:** 2026-03-05
**RFE Filed:** `reef-lang/bugs/RFE-001-init-system-requirements.md`
**Reef 0.4.0:** Released 2026-03-05 — all 8 RFE-001 items implemented

## Problem Statement

SMF (Service Management Facility) is architecturally overcomplex for Hammerhead's needs:

- **XML service definitions** — verbose, hard to read/write, depends on libxml2
- **libxml2 dependency** — maintenance status uncertain, large dependency for service config
- **Architectural complexity** — 3 cooperating daemons (svc.startd, svc.configd, master restarter)
  plus SQLite repository, door-based IPC, and XML-based service manifests
- **Difficult to modify** — tightly coupled components make changes risky

## Proposed Replacement: zyginit

A single-process service manager and supervisor written in Reef, with:

- **TOML-based service definitions** — clean, readable, no XML
- **Symlink-based enable/disable** — no database, inspectable with `ls`
- **Dependency graph resolution** with parallel startup
- **Service supervision** with automatic restart
- **Hammerhead process contract integration** — kernel-level tracking of all service descendants
- **Administrative CLI** (`zygctl`) for service control via Unix domain socket

### Naming

| Component | Name | Description |
|-----------|------|-------------|
| Daemon | `zyginit` | PID 1, the init process |
| CLI | `zygctl` | Admin tool (start/stop/status/enable/disable) |
| Config dir | `/etc/zyginit/` | Service TOML definitions |
| Enable dir | `/etc/zyginit/enabled.d/` | Symlinks to enabled services |
| Socket | `/var/run/zyginit.sock` | Unix domain socket for zygctl |
| Diagnostics | `/var/run/zyginit/` | Optional runtime state (tmpfs) |

### Why Reef

- Compiles to native code via C/GCC — suitable for PID 1
- FFI to C is clean — can call libcontract and all POSIX APIs directly
- Result/Option error handling is correct for systems code
- Writing the init in Reef differentiates Zygaena/Hammerhead
- Reef already powers the Coral package manager — proven for systems programming

## Architecture

```
                    +-----------+
                    |  zygctl   |  (Reef CLI tool)
                    +-----+-----+
                          | Unix socket (/var/run/zyginit.sock)
                    +-----v-----+
                    |  zyginit  |  (PID 1, Reef)
                    |           |
                    | +-------+ |
                    | | event  | |  poll() on: contract bundle fd,
                    | | loop   | |  unix socket fd, signal pipe fd
                    | +---+---+ |
                    |     |     |
                    | +---v---+ |
                    | | dep   | |  topological sort of service graph
                    | | graph | |  built from TOML at boot
                    | +---+---+ |
                    |     |     |
                    | +---v--------+ |
                    | | contract   | |  libcontract FFI:
                    | | manager    | |  template → fork → adopt → events
                    | +------------+ |
                    +-------+-------+
                            |
            +-------+-------+-------+-------+
            |       |       |       |       |
         sshd    cron    fmd   network   ...
       (contract) (contract) (contract) (contract)
```

## Service Definition Format (TOML)

Service definitions are TOML files in `/etc/zyginit/`. Most services are purely
declarative. For complex startup logic (database initialization, network setup),
the `exec.start` field can point to a shell script in the service's subdirectory.

### Simple service (declarative)

```toml
# /etc/zyginit/sshd.toml
[service]
name = "sshd"
description = "Secure Shell Daemon"
type = "daemon"           # daemon | oneshot | transient

[exec]
start = "/usr/lib/ssh/sshd -D"

[stop]
method = "contract"       # contract (default) | exec
signal = "TERM"
timeout = 60

[dependencies]
requires = ["network", "filesystem"]
after = ["name-services"]
conflicts = ["other-mta"]    # mutually exclusive; never run together

[contract]
param = ["inherit", "noorphan"]
fatal = ["empty", "hwerr"]

[restart]
on = "failure"            # always | failure | never
delay = 5
max_retries = 3
```

### Complex service (script escape hatch)

For services requiring complex startup logic, the TOML definition points to
scripts in a subdirectory matching the service name:

```toml
# /etc/zyginit/postgresql.toml
[service]
name = "postgresql"
description = "PostgreSQL Database Server"
type = "daemon"

[exec]
start = "/etc/zyginit/postgresql/start.sh"
stop = "/etc/zyginit/postgresql/stop.sh"

[dependencies]
requires = ["filesystem", "network"]
```

```
/etc/zyginit/
├── postgresql.toml
└── postgresql/
    ├── start.sh              # handles initdb, pg_upgrade, etc.
    └── stop.sh               # clean shutdown with pg_ctl
```

### TOML schema fields (planned — needs further discussion)

Additional fields under consideration:

- `exec.user`, `exec.group` — privilege separation (run as non-root)
- `exec.working_directory` — chdir before exec
- `exec.environment` — env vars: `["KEY=value", ...]`
- `security.zone`, `security.chroot` — containment
- `limits.max_fds`, `limits.max_memory` — resource controls
- `logging.stdout`, `logging.stderr` — output destination (file, syslog)
- `service.milestone` — grouping: `single-user`, `multi-user`, `network`

## State Management

### Design Rationale

Research of other init systems informed the design:

| System | Enable/Disable | State DB | Boot Order |
|--------|---------------|----------|------------|
| **systemd** | Symlinks in `.wants/` dirs | None | In-memory from unit files |
| **dinit** | Symlinks in `waits-for.d/` | None | In-memory from service files |
| **OpenRC** | Symlinks in runlevel dirs | None | In-memory (cached to `/run`) |
| **SMF** | SQLite property | SQLite | In-memory from repository |

Every modern init except SMF uses symlinks for enable/disable state and builds
the dependency graph in memory at boot. SMF's SQLite repository is the #1 source
of boot failures ("repository corruption"). zyginit follows the simpler pattern.

### Enabled/Disabled State (symlinks)

Enabled state is managed via symlinks in `/etc/zyginit/enabled.d/`:

```
/etc/zyginit/
├── sshd.toml
├── cron.toml
├── network.toml
├── filesystem.toml
├── postgresql.toml
├── postgresql/
│   ├── start.sh
│   └── stop.sh
└── enabled.d/                   # symlinks = what starts at boot
    ├── sshd → ../sshd.toml
    ├── cron → ../cron.toml
    ├── network → ../network.toml
    └── filesystem → ../filesystem.toml
```

| Operation | What happens |
|-----------|-------------|
| `zygctl enable sshd` | Creates symlink `enabled.d/sshd → ../sshd.toml` |
| `zygctl disable sshd` | Removes symlink `enabled.d/sshd` |
| `zygctl start sshd` | Starts service now (transient — does not persist across reboot) |
| `zygctl stop sshd` | Stops service now |
| `zygctl status` | Reads in-memory state from zyginit over Unix socket |

Benefits:
- Inspectable with `ls /etc/zyginit/enabled.d/`
- Editable with `ln -s` and `rm` — no special tools required
- Always on root filesystem — available at PID 1 startup
- No corruption risk — no database to corrupt

### Boot Order (derived from TOML)

No pre-computed boot order is stored. At boot, zyginit:

1. Scans `enabled.d/` symlinks → list of enabled services
2. Reads each service's TOML → extracts `[dependencies]`
3. Topological sort → parallel startup order
4. Starts services respecting dependency constraints

For <100 services, TOML parsing and topo sort complete in milliseconds.

### Runtime State (in-memory + optional tmpfs)

Service runtime state (PIDs, running/stopped/failed, restart counters, exit codes)
lives **in memory** inside the zyginit process. Accessible via `zygctl status`
over the Unix domain socket.

Optionally, zyginit writes diagnostic state to `/var/run/zyginit/` (tmpfs) for
crash recovery analysis. This is not required for operation — if zyginit restarts,
it re-scans TOML definitions and re-adopts existing process contracts.

### Filesystem Summary

| Path | Filesystem | Available | Purpose |
|------|-----------|-----------|---------|
| `/etc/zyginit/*.toml` | root | Always | Service definitions |
| `/etc/zyginit/enabled.d/` | root | Always | Enabled symlinks |
| `/var/run/zyginit.sock` | tmpfs | After tmpfs mount | CLI communication |
| `/var/run/zyginit/` | tmpfs | After tmpfs mount | Diagnostic state (optional) |

## Hammerhead Process Contracts

Process contracts are a Hammerhead kernel mechanism (not available on Linux) accessed
via the contract filesystem (`/system/contract/`):

1. Before fork(), open `/system/contract/process/template` and configure
2. After fork(), all child processes (and their children) belong to a contract
3. Contract owner receives events: empty (all exited), core dump, hardware error, fatal signal
4. Can signal ALL processes in a contract atomically — no orphaned grandchildren
5. On init restart, existing contracts are re-adopted — services keep running

The C API (libcontract) is fd-based: open/ioctl/close on ctfs paths. No complex
struct layouts — integer fds, integer flags, and string FMRIs. Clean for Reef FFI.

## Boot Sequence

1. Kernel execs `/sbin/init` → zyginit (PID 1)
2. Scan `/etc/zyginit/enabled.d/` → list of enabled services
3. Read each service's TOML → extract `[dependencies]`
4. Topological sort → boot order
5. Start services in parallel, respecting dependency order
6. Mount tmpfs, create `/var/run/zyginit.sock`
7. Enter poll(2) event loop: contract events, Unix socket, signal pipe

## Reef Language Requirements

Filed as **RFE-001** with the Reef team (`~/repos/reef-lang/bugs/RFE-001-init-system-requirements.md`).

**Response received** (`reef-lang/bugs/RFE-001-response.md`): All 8 items accepted
for Reef 0.4.0. Estimated ~4 weeks. Key findings from Reef team:

- **GC is not a blocker** — no auto-triggered STW pauses; signal change is 2 lines
- **fork/exec already exist** in C runtime — just need stdlib wiring
- **TOML parser already exists** — `encoding/toml.reef` (~560 lines)
- **Cooperative yield points** already exist (`--quantum-checks` flag)

### Revised Priority (per Reef team analysis)

| # | Enhancement | Effort | Status |
|---|------------|--------|--------|
| 1 | Process management (fork/exec/setsid) | Low | Reef 0.4.0 |
| 2 | File descriptor operations | Low | Reef 0.4.0 |
| 3 | String array marshaling | Low-Med | Reef 0.4.0 |
| 4 | Signal enhancements | Low-Med | Reef 0.4.0 |
| 5 | Unix domain sockets | Low | Reef 0.4.0 |
| 6 | Event loop / poll | Low | Reef 0.4.0 |
| 7 | TOML parser enhancements | Minimal | Reef 0.4.0 |
| 8 | GC mode (configurable signals + --no-gc) | Medium | Reef 0.4.0 |

### Open Questions (from Reef team — resolved)

1. **poll(2) vs event ports**: poll(2) in stdlib, event ports via `extern "C"`.
   Poll is sufficient for 3-4 fds.
2. **fork() + Active Objects**: Single-threaded poll loop — no AO conflict.
3. **GC signal preference**: SIGRTMIN+0/SIGRTMIN+1 — no collision with standard signals.

### Reef Team Recommendations

1. Use `extern "C"` for Hammerhead-specific code (libcontract, ctfs) — keep in Hammerhead, not Reef stdlib
2. Start prototyping now with `process_spawn_shell()` + FFI declarations
3. Test with current GC — likely zero pauses for bounded working set
4. Use existing TOML parser (`import encoding.toml`) immediately

## Phased Approach

### Phase A: Interim (Now)
- Keep SMF operational — it works, it's built, it boots
- libxml2 now builds from source in hammerhead (commit 3b7533657)
- Begin zyginit prototype using existing Reef 0.4.0 capabilities
- Test TOML parser with service definition format

### Phase B: Prototype
- Build zyginit prototype with basic service supervision
- Test with a handful of services on standalone VM
- Keep SMF as fallback

### Phase C: Migration
- Convert all SMF service manifests to TOML definitions
- Boot with zyginit as PID 1
- Validate with hh-audit

### Phase D: SMF Removal
- Remove svc.startd, svc.configd, master restarter
- Remove libscf, libxml2 dependency (if no other consumers)
- Remove SMF manifest infrastructure from build

## FMA Integration

FMA (Fault Management Architecture) is independent of SMF and will be retained:
- Kernel drivers post ereport events via sysevent
- fmd daemon runs diagnosis engines (CPU retire, disk fault, ZFS degraded)
- fmd is a service managed by the init system — works with any init
- No architectural coupling to SMF

## References

- Hammerhead `libcontract(3LIB)`, `contract(5)`, `process(5)`
- `cmd/svc/startd/contract.c`, `method.c`, `restarter.c`
- dinit comparison: https://davmac.org/projects/dinit/
- Reef RFE: `~/repos/reef-lang/bugs/RFE-001-init-system-requirements.md`
- Reef 0.4.0 changelog: `~/repos/reef-lang/docs/changelog-0.4.0.md`
# zyginit Implementation Plan

**Status:** Complete — All 7 phases implemented, plus post-phase enhancements
**Date:** 2026-03-06
**Author:** Chris Tusa / Claude

## Project Layout

Following Coral's conventions (`source_dirs = ["src"]`, `entry = "src/main.reef"`):

```
zyginit/
├── reef.toml                # Reef manifest
├── SRCHEADER.txt            # Leafscale source header template
├── CLAUDE.md                # Project context
├── .hgignore                # Mercurial ignore
├── src/
│   ├── main.reef            # Entry point — event loop (Phase 5)
│   ├── config.reef          # TOML parser + ServiceDef types (Phase 1)
│   ├── depgraph.reef        # Dependency graph + topo sort (Phase 2)
│   ├── contract.reef        # Hammerhead process contract FFI (Phase 3)
│   ├── supervisor.reef      # Service lifecycle management (Phase 4)
│   └── socket.reef          # Unix domain socket server (Phase 6)
├── docs/
│   ├── DESIGN.md            # Architecture and design
│   └── IMPLEMENTATION_PLAN.md  # This file
├── services/
│   └── examples/            # Example TOML service definitions
├── tests/
│   └── (test TOML files, test programs)
├── stub/                    # Original Rust-like stubs (design reference only)
└── tools/
    └── zygctl/              # Separate CLI binary
        ├── reef.toml
        └── src/
            └── main.reef
```

## Phase Dependency Graph

```
Phase 1: config.reef (TOML parsing, ServiceDef types)
    │
    ▼
Phase 2: depgraph.reef (dependency graph, topo sort)
    │
    ├──────────────────────┐
    ▼                      ▼
Phase 3: contract.reef   Phase 6: socket.reef
    │                      │
    ▼                      │
Phase 4: supervisor.reef ◄─┘
    │
    ▼
Phase 5: main.reef (event loop wiring)
    │
    ▼
Phase 7: tools/zygctl (separate binary)
```

## Phase 1: config.reef — TOML Config Parser

**Purpose:** Parse `/etc/zyginit/*.toml` service definitions into ServiceDef structs.
**Testable on Linux:** Yes — fully portable.

### Imports

```reef
import encoding.toml as toml
import io.file as file
import core.str
```

### Types

```reef
type ServiceDef = struct
    name: string
    description: string
    service_type: int          // 1=daemon, 2=oneshot, 3=transient

    start_cmd: string
    stop_cmd: string           // empty if not specified

    stop_method: int           // 1=contract, 2=exec
    stop_signal: string        // "TERM", "HUP", etc.
    stop_timeout: int          // seconds, default 60

    requires: [string]         // hard dependencies
    requires_count: int
    after: [string]            // ordering dependencies
    after_count: int

    contract_param: [string]
    contract_param_count: int
    contract_fatal: [string]
    contract_fatal_count: int

    restart_policy: int        // 1=always, 2=failure, 3=never
    restart_delay: int         // seconds, default 5
    max_retries: int           // -1 = unlimited, default 3
end ServiceDef
```

### Functions

- `new_service_def(): ServiceDef` — create with defaults
- `parse_toml_array(value, result, max): int` — parse `["a", "b"]` inline arrays
- `parse_service_type(type_str): int` — "daemon"→1, "oneshot"→2, "transient"→3
- `parse_restart_policy(policy_str): int` — "always"→1, "failure"→2, "never"→3
- `parse_stop_method(method_str): int` — "contract"→1, "exec"→2
- `parse_service(filepath, svc): bool` — parse one TOML file into ServiceDef
- `scan_enabled(config_dir, paths, max): int` — list enabled.d/ entries
- `load_enabled_services(config_dir, services, max): int` — load all enabled services

### Key Implementation Notes

- Reef's TOML parser flattens sections: `[service]` + `name = "sshd"` → key `"service.name"`
- Inline arrays like `requires = ["a", "b"]` need custom parsing (Coral has proven pattern)
- No readlink needed: symlink name in enabled.d maps directly to `<name>.toml`

## Phase 2: depgraph.reef — Dependency Graph + Topological Sort

**Purpose:** Build DAG from service dependencies, compute parallel boot tiers.
**Testable on Linux:** Yes — fully portable.

### Imports

```reef
import collections.hashmap as hashmap
import core.str
```

### Types

```reef
type DepGraph = struct
    names: [string]
    count: int
    name_map: hashmap.HashMap[int]  // name → index
    deps: [int]                     // flattened adjacency (MAX_SERVICES * MAX_DEPS)
    dep_count: [int]                // deps per node
    in_degree: [int]                // for topo sort
end DepGraph
```

### Functions

- `new_depgraph(): DepGraph`
- `add_service(graph, name): int` — returns assigned index
- `add_dependency(graph, name, dep_name): bool`
- `build_graph(graph, services, count): bool` — populate from ServiceDef array
- `topo_sort(graph, tiers, tier_counts, max_tiers): int` — Kahn's algorithm
- `has_cycle(graph): bool`

### Algorithm: Kahn's Topological Sort

1. Find all nodes with in_degree == 0 → tier 0
2. Remove those nodes, decrement in_degree of dependents
3. Nodes reaching in_degree 0 form next tier
4. Repeat until all placed
5. Remaining nodes with in_degree > 0 → cycle error

Output: flat `tiers[string]` array + `tier_counts[int]` array. Services within a
tier can start in parallel.

## Phase 3: contract.reef — Hammerhead Process Contract FFI

**Purpose:** Reef wrappers around libcontract for kernel-level service process tracking.
**Testable on Linux:** No — Hammerhead only. Compile-test only on Linux.

### FFI Declarations

```reef
extern "C" fn ct_tmpl_activate(fd: int): int
extern "C" fn ct_tmpl_clear(fd: int): int
extern "C" fn ct_tmpl_set_informative(fd: int, events: int): int
extern "C" fn ct_tmpl_set_critical(fd: int, events: int): int
extern "C" fn ct_pr_tmpl_set_fatal(fd: int, events: int): int
extern "C" fn ct_pr_tmpl_set_param(fd: int, params: int): int
extern "C" fn ct_status_read(fd: int, detail: int, statp: pointer): int
extern "C" fn ct_status_free(statp: pointer)
extern "C" fn ct_status_get_id(statp: pointer): int
extern "C" fn ct_ctl_abandon(fd: int): int
extern "C" fn ct_ctl_adopt(fd: int): int
extern "C" fn sigsend(idtype: int, id: int, sig: int): int
```

### Types

```reef
type Contract = struct
    id: int
    service_name: string
    bundle_fd: int
end Contract
```

### Functions

- `setup_template(): int` — open/configure/activate contract template
- `get_latest_contract(): int` — read contract ID after fork
- `clear_template(tmpl_fd): int`
- `open_bundle(): int` — open bundle fd for poll()
- `kill_contract(contract_id, sig): int` — signal all processes in contract
- `abandon_contract(contract_id): int`
- `adopt_contract(contract_id): int` — re-adopt after zyginit restart

### Build Note

Requires `-l contract` linker flag on Hammerhead.

### Risk: ct_status_read pointer semantics

`ct_status_read` takes pointer-to-opaque-pointer. Needs `unsafe` block and careful
FFI handling. Must prototype on Hammerhead VM.

## Phase 4: supervisor.reef — Service Lifecycle Management

**Purpose:** Fork/exec services within contracts, manage state machine, restart policies.
**Testable on Linux:** Partial — fork/exec works, contracts do not.

### Imports

```reef
import config
import contract
import sys.process as process
import sys.fd as fd
import sys.signal as signal
import collections.hashmap as hashmap
import core.str
```

### Types

```reef
// State constants: DISABLED=0, WAITING=1, STARTING=2, RUNNING=3,
//                  STOPPING=4, STOPPED=5, FAILED=6, MAINTENANCE=7

type ServiceRuntime = struct
    def: config.ServiceDef
    state: int
    contract_id: int           // -1 if none
    pid: int                   // -1 if none
    restart_count: int
    last_exit_code: int        // -1 if not exited
    last_start_time: int
    stop_requested_time: int
end ServiceRuntime

type ServiceTable = struct
    runtimes: [ServiceRuntime]
    count: int
    name_map: hashmap.HashMap[int]      // name → index
    contract_map: hashmap.HashMap[int]  // contract_id_str → index
end ServiceTable
```

### Functions

- `new_service_table(max): ServiceTable`
- `add_service(table, def): int`
- `find_service(table, name): int`
- `find_by_contract(table, contract_id): int`
- `start_service(table, idx): bool` — fork, contract setup, exec
- `stop_service(table, idx): bool` — signal or exec stop command
- `handle_contract_event(table, contract_id, exit_code)` — apply restart policy
- `check_stop_timeouts(table)` — escalate to SIGKILL if timeout exceeded
- `check_restart_delays(table)` — restart services whose delay has elapsed
- `state_name(state): string` — human-readable state
- `get_status_line(table, idx): string`

### start_service() Flow

1. `contract.setup_template()` → template fd
2. `process.process_fork()` → pid
3. Child: `process.process_setsid()`, parse args, `process.process_exec()`
4. Parent: `contract.get_latest_contract()` → contract_id
5. `contract.clear_template(tmpl_fd)`
6. Update runtime: state=RUNNING, pid, contract_id, timestamp

### Restart Policy Logic (handle_contract_event)

- `RESTART_ALWAYS` → schedule restart after delay
- `RESTART_FAILURE` → restart only if exit_code != 0
- `RESTART_NEVER` → mark STOPPED
- Check max_retries → MAINTENANCE if exceeded

## Phase 5: main.reef — Event Loop

**Purpose:** Wire all modules together into the main poll(2) event loop.
**Testable on Linux:** Partial — poll/signals/sockets yes, contracts no.

### Imports

```reef
import config
import depgraph
import contract
import supervisor
import socket
import sys.process as process
import sys.signal as signal
import sys.poll as poll
import sys.fd as fd
```

### Main Procedure Flow

1. Load config: `config.load_enabled_services()`
2. Build dependency graph: `depgraph.build_graph()` + `depgraph.topo_sort()`
3. Create service table: `supervisor.new_service_table()`
4. Start services tier by tier
5. Set up event sources:
   - Contract bundle fd: `contract.open_bundle()`
   - Signal self-pipe: `signal.selfpipe_create()` for SIGCHLD, SIGTERM, SIGHUP
   - Unix socket: `socket.create_socket()`
6. Main loop: `poll.poll_wait()` with 1s timeout
   - Contract events → `supervisor.handle_contract_event()`
   - Signals → reap children, shutdown, reload
   - Socket → `socket.handle_client()`
   - Periodic: check stop timeouts, restart delays

### Build Command

```bash
reefc build --gc-signals rtmin         # Linux dev
reefc build --gc-signals rtmin -l contract  # Hammerhead production
```

## Phase 6: socket.reef — Unix Domain Socket Server

**Purpose:** Accept zygctl connections, dispatch commands, send responses.
**Testable on Linux:** Yes — fully portable.

### Imports

```reef
import net.unix as unix
import supervisor
import config
import core.str
```

### Protocol

- **Request:** `COMMAND [ARG]\n` (newline-terminated text)
- **Response:** Plain text lines, connection closed after response

### Commands

| Command | Description |
|---------|-------------|
| `status` | List all services with state |
| `status <name>` | Status of one service |
| `start <name>` | Start a service (transient) |
| `stop <name>` | Stop a service |
| `restart <name>` | Stop then start |
| `enable <name>` | Create symlink in enabled.d |
| `disable <name>` | Remove symlink from enabled.d |
| `list` | List all known service definitions |

### Functions

- `create_socket(): int` — bind and listen on `/var/run/zyginit.sock`
- `handle_client(server_fd, table)` — accept, read, dispatch, respond, close
- `parse_command(input, arg_out): string`
- `cmd_status(table, arg): string`
- `cmd_start(table, name): string`
- `cmd_stop(table, name): string`
- `cmd_restart(table, name): string`
- `cmd_enable(name): string`
- `cmd_disable(name): string`
- `cmd_list(table): string`
- `destroy_socket()` — cleanup

## Phase 7: tools/zygctl — CLI Tool

**Purpose:** Admin CLI that connects to zyginit over Unix domain socket.
**Testable on Linux:** Yes.

### Layout

```
tools/zygctl/
├── reef.toml            # entry = "src/main.reef", output = "zygctl"
└── src/
    └── main.reef
```

### Imports

```reef
import sys.args as args
import net.unix as unix
import core.str
```

### Usage

```
zygctl status              # list all services
zygctl status <name>       # status of one service
zygctl start <name>        # start a service (transient)
zygctl stop <name>         # stop a service
zygctl restart <name>      # restart a service
zygctl enable <name>       # enable at boot (creates symlink)
zygctl disable <name>      # disable at boot (removes symlink)
zygctl list                # list all service definitions
```

### Implementation

1. Parse args
2. For enable/disable: operate locally on symlinks (no daemon needed)
3. All other commands: connect to `/var/run/zyginit.sock`, send command, print response

## Platform Testing Strategy

| Phase | Linux | Hammerhead (standalone VM) |
|-------|-------|------------------------|
| 1 | Full test with example TOML | Same |
| 2 | Full test with mock graphs | Same |
| 3 | Compile only | Full test |
| 4 | fork/exec without contracts | Full test |
| 5 | Poll loop without contracts | Full test |
| 6 | Full test | Same |
| 7 | Full test | Same |

## Risk Items

1. **ct_status_read pointer semantics** — pointer-to-pointer FFI, prototype on Hammerhead
2. **TOML inline array parsing** — stdlib doesn't parse natively, use Coral's proven pattern
3. **Contract event binary format** — reading from bundle fd needs Hammerhead struct parsing
4. **String splitting** — verify `str.split()` availability in Reef 0.4.0 stdlib
5. **HashMap with struct values** — may need index-based indirection instead of `HashMap[ServiceDef]`
# zyginit Release Notes

## 0.2.7 — 2026-07-21

**Bug-fix release.** Fixes bug 004 — running the `zyginit` binary as a
non-PID-1 process (classically `zyginit -v` to check the version) fell through
into supervisor mode and **clobbered the live PID-1 control socket**, silently
breaking `zygctl` control of the running system until reboot. Three defenses:

- **Version flags exit safely.** `-v`, `-V`, and `--version` print the version
  and exit — but only when not running as PID 1. The Hammerhead kernel passes
  `-v` (verbose) as a boot-arg to init, so that path must never short-circuit,
  or PID 1 would return from `main()` and be re-exec'd in a loop.
- **The control socket is guarded.** `create_socket` now `connect()`-probes the
  path and refuses to unlink/rebind a socket a live server is already listening
  on; a non-PID-1 instance that cannot own the socket exits cleanly. PID 1
  keeps running without a control socket rather than halting.
- **Non-PID-1 supervisor mode is opt-in.** A non-PID-1 run now requires
  `--supervisor-test`; a bare `zyginit ...` on a host where zyginit already
  owns PID 1 refuses and exits before any setup. The integration harnesses and
  the CLAUDE.md dev-run invocation pass the flag.

Builds clean and passes the full integration suite (104/104) on **Reef 0.7.7**;
no source changes were required for the 0.7.7 toolchain (its newly-rejected
program shapes are all Active-Object-related, which zyginit does not use).

## 0.2.6 — 2026-07-21

**Bug-fix release.** Fixes bug 003 — spurious `exit=-1` service failures in
first-boot reports on Hammerhead. Root-cause analysis found `exit=-1` was
never an exec-failure code (a real exec failure exits 127); it was the
"could not resolve an exit code" sentinel, produced by two distinct defects:

- **Exec robustness / no silent failure.** Under first-boot I/O contention
  (devfsadm + ZFS pool-finalize) the child's exec of a valid start command
  could transiently fail, and the child then exited silently with an empty
  per-service log. The child now retries `process_exec` (5×, 100 ms backoff)
  and, on final failure, records the reason to both the per-service
  `<name>.log` (fd 2, survives a privilege drop) and a new central
  `/var/log/zyginit/zyginit.log`, then exits 127.
- **Reap-race reconciliation** (the actual source of `-1`). The
  contract-empty event on the bundle fd can beat the child's exit-status
  posting; `handle_contract_event` used to commit the `-1` sentinel and tear
  down tracking, after which the catch-all reaper discarded the real code. It
  now defers when there is no hint, no resolvable code yet, and a child is
  still tracked (`rt.pid > 0`), so the unconditional `reap_children`
  re-dispatches with the true code within ~1 s. This fixes both the 127→-1
  masking and the independent false-positive where an exit-0 oneshot that
  lost the race was reported FAILED.

New central operational log: `/var/log/zyginit/zyginit.log` (distinct from
the per-service logs). Adds integration Suite 9b (spawn-failure capture);
97/97 tests pass. The reap-race half rides the Hammerhead contract path
(not exercised by the Linux stubs) and awaits an hh-alpha first boot to
confirm in situ.

## 0.2.5 — 2026-07-17

**Reef 0.7.6 migration; no init-engine behavior change.** Migrated the suite
to Reef 0.7.6: `Result`/`Option` idioms, TOML inline arrays, and the
`socket` → `ctlsocket` module rename (avoids a clash with the stdlib
`net.socket`, which `net.unix` now imports). Internal/tooling release — no
source tarball was cut for 0.2.5.

## 0.2.4 — 2026-06-13

**Service mutual exclusion.** Adds the `[dependencies].conflicts` array:
mutually-exclusive services both fail if both are enabled, and a start is
refused if a conflicting peer is already running. Boot-time resolution fails
both sides and surfaces the reason in `zygctl status`. A one-sided
declaration is enforced symmetrically (both directions).

## 0.2.3 — 2026-06-02

**Boot/shutdown progress gauge relocated into the header divider.** The gauge
previously lived on the volatile last screen row, where interleaved
kernel/daemon writes would scroll it off. It now paints into the header's
horizontal rule. `fmt_progress_bar` and `PROGRESS_WIDTH` were removed and
`fmt_divider_gauge` added in `src/ui.reef`; two screen rows are reclaimed for
the rolling tape.

## 0.2.2 — 2026-05-21

**Repo content reshape; no behavioral change.** zyginit is now
strictly engine + examples + schema docs. The in-repo `services/hammerhead/`
tree (22 production service TOMLs) has been removed — distros own all
service-definition policy in their own overlay trees. The Hammerhead
team has absorbed the prior set into `base/usr/src/zyginit/overrides/`.

The `examples/` directory is slimmed to four heavily-commented
canonical examples:

- `daemon-with-restart/` — long-running daemon with `[restart]` policy
- `oneshot-setup/` — type="oneshot" with `[dependencies].requires`
- `task-with-condition/` — type="task" with `[condition].exists_file`
- `with-stop-script/` — `[exec].stop` + companion `stop.sh`

`scripts/install-to-be.sh` was deleted; its "deploy our services to
a BE" purpose evaporates in an engine-only world. (Distros can ship
their own equivalent.)

`docs/SMF_MIGRATION.md` has been rewritten as a methodology guide
(how to convert an SMF manifest to a zyginit TOML) rather than a
catalog of our specific conversions.

Tarball: ~22 KB smaller than 0.2.1. No `clang` / `reefc` / API changes.

## 0.2.1 — 2026-05-15

Patch release with two operational improvements:

- `type = "transient"` in 0.1.x-style TOMLs no longer silently demotes
  to `daemon`. The parser now treats it as `task` (the renamed type) and
  emits a deprecation warning. This prevents a service that should run
  as a task from hanging in STATE_STARTING after an incomplete upgrade.
- Missing `/etc/zyginit/services/` directory at boot now produces a
  distinct, actionable log message instead of silently entering the
  idle loop. The operator is told to run the migration tool from a
  recovery medium.

## 0.2.0 — 2026-05-15

**Breaking change.** The filesystem layout under `/etc/zyginit/` is
restructured. Operators upgrading from 0.1.x MUST run the migration
tool before installing 0.2.0 binaries:

    /path/to/scripts/migrate-layout.sh --dry-run    # preview
    /path/to/scripts/migrate-layout.sh --apply      # apply

The tool is idempotent (safe to re-run) and refuses to proceed if
both old and new layouts coexist for the same service.

### New: per-service directory layout

Each service is self-contained:

    /etc/zyginit/services/<name>/
    ├── service.toml
    ├── start.sh          (optional)
    └── stop.sh           (optional)

`enabled.d/<name>` symlinks target `../services/<name>/` (the
directory), not `../<name>.toml` (the file).

### New: `type = "task"` service type

For services that may run for a while but are expected to eventually
exit cleanly — platform probes, one-time setup work, etc. Replaces
the previously-unused `type = "transient"`.

    [service]
    name = "acpihpd"
    type = "task"

Semantics:
- Exit 0 → STATE_STOPPED (counts as online in the boot banner)
- Exit ≠ 0 → STATE_FAILED (counts as failed)
- Never restarts
- Skips the daemonize handshake (tasks don't double-fork)

### New: `[condition]` block

Declarative pre-flight gating. Services whose conditions fail at
startup go into a new SKIPPED state — they don't fork, don't fail,
don't loop. Supported keys:

    [condition]
    exists_file     = "/dev/acpihp"
    exists_file_any = ["/dev/acpihp", "/dev/acpi"]
    command         = "/usr/sbin/acpi_probe"     # 5-second timeout

All specified keys must pass (AND). Absent keys are no-ops. The
command form is bounded by a 5-second timeout.

### New: SKIPPED state in `zygctl status`

Skipped services render with the `·` (dim) glyph and the skip reason
in the NOTES column. The boot banner and final card include a
"skipped" counter alongside online/failed.

### Hammerhead vendoring

The Hammerhead team runs the migration tool against their override
tree in `base/usr/src/zyginit/overrides/` as part of consuming this
source drop. Follow the same dry-run → apply pattern.

### Other changes

- Renamed `SERVICE_TYPE_TRANSIENT` → `SERVICE_TYPE_TASK` in the API.
- `type = "transient"` in TOML produces a deprecation warning and is treated as `type = "task"` (see 0.2.1).

## 0.1.8 — 2026-05-14

Late-failure race fix. A 1-second settle period after the last tier
catches daemons that fork successfully but die immediately (e.g.,
acpihpd on Hammerhead without ACPI hardware).

## 0.1.7 — 2026-05-14

Boot screen no longer scrolls the `[Z]` banner off the top of the
framebuffer. Drop the trailing newline that was advancing the cursor
past the last row.

## 0.1.6 — 2026-05-14

illumos build fix: `<sys/termios.h>` now explicitly included for
`struct winsize` and `TIOCGWINSZ`. Linux's `<sys/ioctl.h>` pulls
those in transitively; illumos doesn't.

## 0.1.5 — 2026-05-14

(Broken on illumos: missing `<sys/termios.h>` for TIOCGWINSZ — use
0.1.6+.) Spinner-in-tape redesign (option B): each tape row tracks
its own `active` flag, lifecycle procs update rows in place,
parallel-startup ready. TIOCGWINSZ for dynamic screen size. Oneshot
single-count fix. Dynamic SERVICE column in `zygctl status`.

## 0.1.4 — 2026-05-14

Framebuffer-first mode detection (PID 1 + isatty + no TERM defaults
to truecolor). Sets TERM=sun-color in zyginit env so children
inherit it. Plain-mode emit no longer mislabels event types.

## 0.1.3 — 2026-05-12

Initial visual pass: `[Z]` sigil, palette, rolling tape, progress
bar, spinner, final cards, mirrored shutdown UI, `zygctl status`
banner+table.
# SMF Migration — Handoff to Hammerhead

This document hands off the remaining SMF-removal work from the zyginit project to
the Hammerhead team. It covers source vendoring, build integration, the decision
process for converting each SMF manifest to a zyginit TOML service definition,
worked examples, anti-patterns drawn from the iter 1-20 development history,
per-category guidance, and a coarse catalog of all 128 manifests found on
`hh-prototest` as of 2026-05-02.

**See also:** `docs/DESIGN.md` for the zyginit architecture reference;
`docs/ROADMAP.md` for the forward-looking task checklist.

---

## 1. Handoff Brief

*This section orients the Hammerhead team on what zyginit has done, what is left,
and where to ask questions.*

### What zyginit has done (through rev 82)

zyginit is a working replacement for `svc.startd`, `svc.configd`, and the SMF
master restarter — a single Reef process that acts as PID 1, supervises services
defined in TOML files, and exposes an administrative socket for `zygctl`.

As of rev 82 (2026-05-02), zyginit boots Hammerhead to a fully-functional
multi-user state on `hh-prototest` (192.168.122.50) without any SMF
infrastructure running:

- **Multi-user boot** — all tier-0 through tier-7 services start cleanly.
- **Single-user mode** — boot arg `-s` or runtime `zygctl single` drops to
  `/sbin/sh` on `/dev/console`.
- **Runtime runlevel transitions** — `zygctl single` / `zygctl multi` (and the
  `init s` / `init 3` sysv wrappers) work bidirectionally.
- **Clean shutdown** — `zygctl halt` / `reboot` / `poweroff` perform a
  reverse-tier stop, ZFS sync, `umountall -l`, and `uadmin` from a forked
  non-PID-1 child.
- **utmpx integration** — `who -b`, `who -r`, and `uptime` report correctly.
- **~18 core services converted** — the methodology is established for the
  full Hammerhead service set. The production TOMLs now live in Hammerhead's
  overlay tree at `base/usr/src/zyginit/overrides/` (absorbed during Phase D).
  See the worked examples in Section 3 and the catalog in Section 7 for
  the conversion patterns.

### What the Hammerhead team must do

1. **Vendor zyginit source** into `hammerhead-userland` (see Section 5 for the
   file-by-file layout and build instructions).
2. **Wire the build** to produce `/sbin/init` (zyginit), `/sbin/zygctl`, and
   `/sbin/sysv-wrapper` with its symlinks.
3. **Source the production TOMLs** from Hammerhead's overlay tree at
   `base/usr/src/zyginit/overrides/` (already absorbed during Phase D);
   install them to `/etc/zyginit/` and symlink in `enabled.d/`.
4. **Validate** that the vendored source builds and boots identically to
   `hh-prototest` before starting new conversions.
5. **Convert the remaining ~110 SMF manifests** using the decision tree in
   Section 2, the worked examples in Section 3, the per-category guidance in
   Section 6, and the catalog in Section 7.
6. **Remove SMF infrastructure** — `svc.startd`, `svc.configd`, master restarter
   binaries, manifest infrastructure, and `libscf`-only consumers — from
   `hammerhead-userland` packaging.

### Done criteria for "SMF removal complete"

- Hammerhead boots to multi-user without `svc.startd` or `svc.configd` ever
  being invoked (verify with `pgrep -fl svc.startd`; expect zero results).
- `libscf` is not linked into any binary in the default boot path (acceptable to
  keep `libscf` installed for optional/zports consumers, but no required boot
  service calls into it).
- All zyginit-managed services continue to work at least as well as the
  SMF-managed equivalents they replaced.
- Manifest XML files and `svc:/` repository infrastructure are removed from
  default packaging (they may be retained in a `smf-compat` optional package
  for administrators who need to run SMF tooling temporarily).
- `halt`, `reboot`, `poweroff`, and `init <N>` reach the hardware-level
  operation cleanly.

### Coordination

- **Questions about existing zyginit behavior** — open an issue against the
  zyginit repo. Include the service name, the symptom, and the hh-prototest log
  output.
- **TOML fields that don't fit a service's needs** — file an RFE against zyginit.
  Do not work around missing features in the service scripts; get the runtime
  feature first.
- **Hammerhead team's scope** — modifying `hammerhead-userland` is the
  Hammerhead team's job. The zyginit CLAUDE.md constraint "DO NOT modify
  Hammerhead source code" applies to the zyginit-project Claude, not to the
  Hammerhead Claude. The Hammerhead Claude should freely modify its own tree.

**See also:** Section 5 (Integration with Hammerhead), `docs/ROADMAP.md`
"SMF Removal from Hammerhead."

---

## 2. Decision Tree

*This section is the core reference for every manifest conversion. Walk each
manifest through the three steps in order.*

### Step 1 — Should this service exist on Hammerhead at all?

```
Does Hammerhead ship this functionality?
   |
   +-- No: deprecated, SPARC-only, SMF infrastructure, or NIS/iSCSI/etc.
   |     --> DROP. Remove from packaging; do not write a TOML.
   |         The catalog (Section 7) lists the obvious drops.
   |
   +-- Possibly, but as an optional zports add-on (Kerberos KDC, iSNS, etc.)
   |     --> DEFER. Out of scope for hammerhead-userland; leave for zports.
   |
   +-- Yes, ships in hammerhead-userland
         --> Continue to Step 2.
```

**Mandatory: do not skip Step 1.** Converting a service "because it exists" is
the single biggest source of wasted effort. The 128 manifests include services
Hammerhead does not and should never ship (SMF infrastructure, SPARC platform
code, NIS, iSCSI target, Trusted Extensions label daemon, etc.). These are
straightforward drops.

### Step 2 — Is the service coupled to SMF infrastructure at runtime?

```
Does the daemon call into svc.configd / libscf / the SMF repository door
at runtime (not just at startup)?
   |
   +-- Yes, fundamentally requires libscf or the repository for ongoing
   |   operation (e.g., svc.startd, svc.configd themselves)
   |     --> DROP (if it IS SMF) or INVESTIGATE (if it merely uses libscf).
   |         For investigate: look for a foreground/standalone mode flag.
   |         Coordinate with the daemon's upstream if none exists.
   |
   +-- Yes at startup, but the daemon has a non-SMF mode flag
   |   (-d, -f, -D, or similar) that skips the startup gate and the
   |   daemonize double-fork
   |     --> CONVERT using the foreground-mode pattern. See Example 1.
   |         Known flags on Hammerhead daemons:
   |           dlmgmtd   -d   (debug/foreground; bypasses SMF_FMRI gate)
   |           ipmgmtd   -f   (identical pattern)
   |           sshd      -D   (standard OpenSSH; no daemonize)
   |           syslogd   -d   (foreground; standard illumos)
   |           fmd       -f   (foreground; from fmd source)
   |         Check each daemon's man page and source before assuming
   |         SMF coupling is unavoidable.
   |
   +-- No SMF coupling, or coupling is purely cosmetic (e.g., SMF_FMRI
       env var used only for a cache-file name)
         --> Continue to Step 3.
```

**Getting Step 2 wrong was the entire iter 1-5 dead end.** When dlmgmtd was
started without its foreground flag, it failed silently — no error on stderr
(daemonize had already closed fd 2), and the network never came up. See
`memory/pid1_boot_iter11_15.md` for the full diagnosis.

### Step 3 — What runs the service today?

```
What does the SMF exec_method actually invoke?
   |
   +-- Direct daemon binary (no method script)
   |     --> CONVERT with a simple TOML. exec.start = the binary + args.
   |         Most daemons with exec=':kill' for stop use the contract
   |         signal by default — omit [stop] unless you need custom signal.
   |
   +-- /lib/svc/method/<name> shell script
   |     |
   |     +-- Script is trivial (rm a FIFO, mkdir, then exec the daemon)
   |     |     --> INLINE the setup into a wrapper start.sh. See Example 2.
   |     |         Services that take this path: cron (rm FIFO + exec),
   |     |         syslogd (touch /var/adm/messages + exec), console-login
   |     |         (write utmpx entry + exec ttymon).
   |     |
   |     +-- Script sources /lib/svc/share/smf_include.sh AND calls
   |     |   smf_present() or smf_clear_method_context()
   |     |     --> Check if smf_present() branch is the failure path only.
   |     |         If so, the script works fine without configd (smf_present
   |     |         returns false; the relevant branch is skipped). Test
   |     |         carefully. Many scripts are safe even with smf_include.sh.
   |     |
   |     +-- Script does substantial, maintained setup work
   |           --> KEEP the method script as exec.start. Add SMF_FMRI to
   |               [exec] environment if the script requires it for
   |               non-configd purposes (e.g., FIFO name, log prefix).
   |               See Example 2 alternate form.
   |
   +-- Oneshot configuration command (mountall, swapadd, dumpadm, coreadm)
   |     --> CONVERT as type = "oneshot". See the worked examples in
   |         Section 3 and the Hammerhead overrides for root-fs, swap,
   |         filesystem patterns.
   |         Onshots use restart.on = "never".
   |
   +-- inetd-managed service (not a standalone daemon)
         --> DROP unless there is a strong reason to keep inetd.
             Hammerhead does not run inetd. If the underlying
             functionality is needed (e.g., legacy RPC), the service
             needs its own TOML as a standalone daemon.
```

### Field-by-field translation table

| SMF manifest element | TOML field | Notes |
|---|---|---|
| `<service name='X'>` | `[service] name` | Strip the category prefix (e.g., `network/ssh` → `"sshd"`) |
| `<template><common_name>` | `[service] description` | Plain string; omit XML whitespace |
| SMF behavior class | `[service] type` | Map: continuous daemon → `"daemon"`; fire-and-forget → `"oneshot"`; transient SMF → `"transient"` |
| `<exec_method name='start' exec='...'>` | `[exec] start` | Replace with binary + foreground flag if Step 2 says foreground-mode; or use method script path if Step 3 says keep |
| `<exec_method name='stop' exec=':kill'>` | (omit — default) | `:kill` in SMF = send contract signal; zyginit does this by default via `[stop] method = "contract"` |
| `<exec_method name='stop' exec='some-cmd'>` | `[stop] method = "exec"` + `[exec] stop = "some-cmd"` | For custom stop scripts |
| `<dependency type='service' ...><service_fmri value='svc:/X'>` | `[dependencies] requires = ["X"]` | Translate FMRI basename; drop all SMF-internal dependencies (milestone/*, system/svc/*, restarter) |
| `<dependency type='path' ...>` | `[dependencies] requires = ["filesystem"]` | Path deps mean "filesystem is up"; map to the filesystem service |
| `<property_group name='startd'><propval name='duration' value='transient'>` | `[service] type = "oneshot"` | SMF transient duration = zyginit oneshot |
| `<property_group name='general'><propval name='enabled'>` | (not in TOML) | Enabled state is set by the operator via symlink in `/etc/zyginit/enabled.d/` |
| Restart policy | `[restart] on = "always\|failure\|never"` | SMF `ignore_error` → `on = "failure"`; SMF restart contract → `on = "always"` |
| `<property_group name='startd'><propval name='ignore_error' value='core,signal'>` | `[restart] on = "failure"` | Core + signal ignores = only restart on clean failure |
| `<method_context><method_credential user='X' group='Y'>` | `[exec] user = "X"` and `[exec] group = "Y"` | Drop privileges before exec |
| `<method_context working_directory='/'>` | `[exec] working_directory = "/"` | Inherited if omitted; specify if non-root |
| Contract params | `[contract] param = [...]` | Defaults (`["inherit", "noorphan"]`) are correct for most services |

**See also:** `docs/man/man5/zyginit.5` for the authoritative field-by-field
TOML format reference; this table covers patterns and translation, not syntax.

---

## 3. Worked Examples

*This section walks three representative manifests through the full
conversion process.*

---

### Example 1 — Foreground-mode conversion: dlmgmtd

**Manifest:** `/lib/svc/manifest/network/dlmgmt.xml`
**Result:** `base/usr/src/zyginit/overrides/dlmgmtd/service.toml` (Hammerhead overlay tree)
**Pattern:** foreground-mode (Decision Tree Step 2, middle branch)

#### Original manifest (key lines)

```xml
<service name='network/datalink-management' type='service' version='1'>
    <dependent name='dlmgmt-device-system' grouping='require_all'
        restart_on='none'>
        <service_fmri value='svc:/system/device/local' />
    </dependent>
    <exec_method type='method' name='start'
        exec='/lib/svc/method/svc-dlmgmtd' timeout_seconds='60' />
    <exec_method type='method' name='stop' exec=':kill' timeout_seconds='3' />
```

`/lib/svc/method/svc-dlmgmtd` checks for `SMF_FMRI` and calls `dlmgmtd`
with no additional flags — dlmgmtd daemonizes on its own.

#### Decision-tree walk

- **Step 1:** Yes, Hammerhead ships dlmgmtd. It is required for `ifconfig plumb`
  and `dladm` to work at all on illumos; libdladm resolves link names through
  dlmgmtd's door.
- **Step 2:** Yes, dlmgmtd checks `getenv("SMF_FMRI")` at startup to derive a
  cache-file name, then calls `daemonize()`. Without the foreground flag, both
  checks happen even when started outside SMF. But `dlmgmtd -d` skips both:
  the debug-mode branch in `dlmgmt_main.c` bypasses the `SMF_FMRI` check and
  the `dlmgmt_daemonize()` call entirely. The door is still created at the same
  path. This is the foreground-mode pattern — use `-d`.
- **Step 3:** not reached (Step 2 resolved it).

#### Resulting TOML

The production TOML in the Hammerhead overlay tree captures these decisions.
Its comment block reads as follows (inlined here for reference):

```toml
# dlmgmtd — Datalink management daemon
#
# Runs in `-d` (debug) mode, which on dlmgmtd means "single foreground
# process, no double-fork daemonize." Three reasons we use it:
#   1. Skips the SMF_FMRI startup gate (debug mode bypasses the check).
#   2. Keeps stderr connected to our log; without it dlmgmtd's daemonize
#      runs fdwalk(closefunc), closing fd 2 — any startup error then
#      goes to syslog, which isn't running yet at this tier.
#   3. zyginit's contract tracks a single PID instead of dealing with
#      the parent-exits-0-after-handshake daemonize pattern.
# Cosmetic effect: the cache file is named "dlmgmtd.debug.cache" instead
# of "network-datalink-management:default.cache". Nothing external reads
# this file — only dlmgmtd itself, for fast restart state recovery.

[service]
name = "dlmgmtd"
description = "Datalink management daemon (foreground)"
type = "daemon"

[exec]
start = "/sbin/dlmgmtd -d"

[dependencies]
requires = ["filesystem"]

[restart]
on = "failure"
delay = 5
max_retries = 3

[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

#### Key field mapping decisions

- `name` — FMRI basename `network/datalink-management` collapsed to `dlmgmtd`.
- `exec.start` — direct binary + flag; method script path dropped entirely.
- `dependencies.requires = ["filesystem"]` — the SMF `<dependent>` blocks on
  `network/physical` are dropped (SMF-internal ordering, not real deps).
- `stop` — omitted; SMF's `:kill` = zyginit's default contract signal.
- `contract.fatal = ["hwerr"]` not `["hwerr", "empty"]` — the daemonize
  handshake transiently empties the contract; zyginit handles that correctly.

Verify after boot: `pgrep -fl dlmgmtd` shows `dlmgmtd -d`; `ls /etc/svc/volatile/dladm/dlmgmt_door` shows the door; `dladm show-phys` returns the NIC list.

**See also:** `memory/pid1_boot_iter11_15.md` for the diagnostic history;
`base/usr/src/zyginit/overrides/ipmgmtd/service.toml` (Hammerhead overlay) for
the identical pattern applied to ipmgmtd.

---

### Example 2 — Method-script wrap: cron

**Manifest:** `/lib/svc/manifest/system/cron.xml`
**Result:** `base/usr/src/zyginit/overrides/cron/service.toml` + `start.sh` (Hammerhead overlay tree)
**Pattern:** trivial method-script inlined (Decision Tree Step 3, inline branch)

#### Original manifest (key lines)

```xml
<service name='system/cron' type='service' version='1'>
    <dependency name='usr' type='service' grouping='require_all' restart_on='none'>
        <service_fmri value='svc:/system/filesystem/local' />
    </dependency>
    <dependency name='ns' type='service' grouping='require_all' restart_on='none'>
        <service_fmri value='svc:/milestone/name-services' />
    </dependency>
    <exec_method type='method' name='start' exec='/lib/svc/method/svc-cron'
        timeout_seconds='60'>
        <method_context><method_credential user='root' group='root' /></method_context>
    </exec_method>
    <exec_method type='method' name='stop' exec=':kill' timeout_seconds='60' />
```

`/lib/svc/method/svc-cron` sources `smf_include.sh` (for `$SMF_EXIT_*`
constants and `smf_zonename` — no configd call), removes `/etc/cron.d/FIFO` if
stale, and runs `/usr/sbin/cron &`.

#### Decision-tree walk

- **Step 1:** Yes, Hammerhead ships cron. Required for log rotation and
  scheduled tasks.
- **Step 2:** No SMF coupling. `svc-cron` sources `smf_include.sh` only for
  `$SMF_EXIT_*` constants and `smf_zonename` (which calls `/sbin/zonename` — no
  configd). The exit codes are not observed by zyginit's contract model anyway.
  No configd calls anywhere.
- **Step 3:** Method script. Assessment: trivial. The script does two things
  before starting cron: check for a stale FIFO and remove it. The `pgrep` guard
  is irrelevant under zyginit (supervisor doesn't double-start). The `cron &`
  backgrounding is replaced by `exec /usr/sbin/cron` in the wrapper.

#### Two valid TOML forms

**Form A — Inline the setup in a wrapper start.sh (production choice):**

```toml
[service]
name = "cron"
description = "cron daemon"
type = "daemon"

[exec]
start = "/etc/zyginit/cron/start.sh"

[dependencies]
requires = ["syslogd"]

[restart]
on = "failure"
delay = 5
max_retries = 3

[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

With `start.sh` (lives alongside `service.toml` in the Hammerhead overlay):

```sh
#!/bin/zsh
# Clean up stale FIFO before starting cron.
# /usr/sbin/cron creates /etc/cron.d/FIFO at startup and refuses to
# start if the file already exists — mirrors svc-cron's behavior.
set -e
/bin/rm -f /etc/cron.d/FIFO
exec /usr/sbin/cron
```

**Form B — Use method script directly (transitional):**

```toml
[exec]
start = "/lib/svc/method/svc-cron"
environment = ["SMF_FMRI=svc:/system/cron:default"]
```

Choose Form A when the setup is short and you want to decouple from SMF method
script files (the preferred end state — `/lib/svc/method/svc-cron` will be
removed). Choose Form B as a transitional step when the method script does
substantial correct setup and does not call `smf_present()` in any required
code path.

#### Key field mapping decisions

- `dependencies.requires = ["syslogd"]` — SMF's milestone deps (`filesystem/local`,
  `name-services`) are replaced with direct deps on zyginit services. Drop all
  milestone FMRI references; they don't exist in zyginit.
- `type = "daemon"` — continuous daemon; SMF's `<single_instance/>` is implicit.
- `stop` omitted; `working_directory` and `user/group = root` omitted (defaults).

**See also:** `base/usr/src/zyginit/overrides/syslogd/` (Hammerhead overlay) for
the same pattern (touch log file + exec daemon);
`base/usr/src/zyginit/overrides/console-login/` for a more involved wrapper
(write utmpx entry + exec ttymon).

---

### Example 3 — Drop: svc.startd / system/svc/restarter

**Manifest:** `/lib/svc/manifest/system/svc/restarter.xml`
**Result:** DROP — no TOML.
**Pattern:** Decision Tree Step 1, no branch.

#### Original manifest (key lines)

```xml
<service name='system/svc/restarter' type='restarter' version='1'>
    <create_default_instance enabled='true' />
    <exec_method type='method' name='start' exec=':true' timeout_seconds='0' />
    <exec_method type='method' name='stop'  exec=':true' timeout_seconds='0' />
```

FMRI: `svc:/system/svc/restarter:default`. The exec methods are `:true` because
the kernel never invokes them — `init` starts svc.startd directly, and this
manifest exists only so svc.startd can store its own properties in the
SMF repository.

#### Decision-tree walk

- **Step 1:** No. This manifest IS SMF. zyginit replaces the functionality of
  `svc.startd`, `svc.configd`, and the master restarter framework entirely.
  There is nothing to convert. DROP.

#### The cascade

Every other SMF manifest on the system has at least one `<dependency>` block
referencing SMF-internal FMRIs. When you convert those services, drop all such
references. They are not real ordering constraints between daemons — they are
SMF's internal "this-service-needs-the-SMF-infrastructure" boilerplate.

Common SMF-internal FMRIs to drop from `requires` when converting:

```text
svc:/system/svc/restarter:default     (the restarter framework itself)
svc:/milestone/single-user:default    (SMF single-user milestone)
svc:/milestone/multi-user:default     (SMF multi-user milestone)
svc:/milestone/name-services:default  (SMF name-services milestone)
svc:/milestone/network:default        (SMF network milestone)
svc:/milestone/sysconfig:default      (SMF sysconfig milestone)
svc:/system/manifest-import:default   (SMF manifest import oneshot)
svc:/system/early-manifest-import:default
```

Replace the real ordering constraints (filesystem, syslogd, dlmgmtd, etc.)
with bare service names pointing at the corresponding zyginit-managed services.

#### Companion drops

The following manifests are all SMF infrastructure and must be dropped along
with the restarter:

| Manifest | FMRI | Reason |
|---|---|---|
| `system/svc/restarter.xml` | `svc:/system/svc/restarter:default` | Is svc.startd |
| `system/svc/global.xml` | `svc:/system/svc/global:default` | SMF global property store |
| `system/early-manifest-import.xml` | `svc:/system/early-manifest-import:default` | SMF import at boot |
| `system/manifest-import.xml` | `svc:/system/manifest-import:default` | SMF import daemon |

The SMF binaries to remove from `hammerhead-userland` packaging:
`/lib/svc/bin/svc.startd`, `/lib/svc/bin/svc.configd`,
`/usr/sbin/svcadm`, `/usr/sbin/svccfg`, `/usr/sbin/svcs`,
`/usr/sbin/svcprop`. The `/lib/svc/share/smf_include.sh` helper library
can remain if any method scripts continue to be used during the transition
(Form B of method-wrap); remove it when all method scripts are replaced.

**See also:** Section 6 "Per-Category Guidance" for the full `system/svc/`
category drop rule.

---

## 4. Anti-patterns and Gotchas

*This section documents known failure modes from the iter 1-20 development
history. Each entry gives the symptom, root cause, and fix.*

### 1. configd-coupled daemons degrade silently

**Symptom:** Service starts (fork succeeds, contract created), but functionality
is absent — `dladm show-phys` returns empty, `ifconfig plumb` returns
"no such interface."

**Cause:** Daemon checks `getenv("SMF_FMRI")` or calls into `libscf` at startup.
Without `svc.configd` running, the check fails or the call blocks/returns
error, and the daemon silently skips its initialization. No log output because
the daemon's `daemonize()` call has already closed stderr (fd 2) before the
error is reached.

**Fix:** Use the daemon's foreground/debug flag (see Decision Tree Step 2).
In foreground mode the SMF_FMRI check is bypassed AND stderr stays connected
to zyginit's log, so startup errors are visible. **Never start a configd-coupled
daemon without its foreground flag.**

Reference: `memory/pid1_boot_iter11_15.md` (dlmgmtd and ipmgmtd diagnosis).

### 2. Foreground-flag names vary by daemon

**Symptom:** You know a foreground mode exists but can't find the right flag.

**Cause:** There is no standard flag name. Each daemon chose its own.

**Fix:** Check the daemon's man page, its `main()` usage string, and
(for open-source daemons) its source. Known Hammerhead flags:

| Daemon | Flag | Effect |
|---|---|---|
| `dlmgmtd` | `-d` | foreground, no daemonize, bypass SMF_FMRI gate |
| `ipmgmtd` | `-f` | identical pattern |
| `sshd` | `-D` | foreground, no daemonize (standard OpenSSH) |
| `syslogd` | `-d` | foreground (standard illumos) |
| `fmd` | `-f` | foreground (Fault Manager Daemon) |
| `inetd` | n/a | SMF_FMRI env var required instead |

For daemons where no foreground flag exists, consider Form B method-wrap
(keep the SMF method script) as a transitional option.

### 3. soconfig must run before any network sockets

**Symptom:** `socket(AF_INET, ...)` returns `EAFNOSUPPORT` even though the
network interface is up.

**Cause:** illumos sockfs's protocol map is not populated until `soconfig -d /etc/sock2path.d` runs. SMF's `system/device/local` did this; without it `AF_INET` is unknown to the kernel.

**Fix:** The Hammerhead overlay `devfs/start.sh` runs `soconfig` in the devfs tier.
All services that need networking depend (directly or transitively) on `devfs`.
Reference: `memory/pid1_boot_iter11_15.md`, iter 11.

### 4. Daemonize handshake: supervisor sees "stopped (exit 0)"

**Symptom:** `zygctl status` shows a daemon as `STOPPED` right after start even though it is running.

**Cause:** Double-fork daemonize — the wrapper parent exits 0 while the daemon child is alive in the contract.

**Fix:** zyginit (rev 78+) detects the handshake: `type = "daemon"` + parent exits 0 + contract still has processes → clear `rt.pid` but keep the contract. Ensure TOML says `type = "daemon"`, not `"oneshot"`.
Reference: `memory/pid1_boot_iter16.md`.

### 5. /var/run is not tmpfs in the current zyginit BE

**Symptom:** Stale socket, PID, or lock files survive reboots.

**Cause:** Standard illumos mounts `/var/run` as tmpfs via `fs-minimal`. zyginit's `filesystem/start.sh` does not yet do this.

**Fix (short-term):** Add `rm -f /var/run/<svc>.pid` in affected `start.sh` wrappers. Long-term: add `mount -F tmpfs swap /var/run` to `filesystem/start.sh`. `socket.reef` already handles stale socket recovery via unlink-before-bind.

### 6. utmpx record positioning for who(1) -r

**Symptom:** `who -r` reports the wrong runlevel after a `zygctl single` / `zygctl multi` transition.

**Cause:** `pututxline(3C)` appends a new `RUN_LVL` record unless `getutxid` positions the cursor on an existing one first. `who -r` reads only the first matching record.

**Fix:** Call `getutxid` before `pututxline`. The `zyginit_write_runlvl_utmpx` helper in `src/helpers.c` does this correctly; use it.
Reference: `memory/pid1_boot_iter18.md`.

### 7. Do not set ZFS readonly=on during shutdown

**Symptom:** After `zygctl reboot`, the next boot sees pre-shutdown state — stale socket, daemons appear wrong.

**Cause:** `zfs set readonly=on` on the live root mid-shutdown makes all subsequent writes (including socket unlink and log writes) silently fail. ZFS records the pre-readonly txg; next boot sees it.

**Fix:** Remove `readonly=on` from any stop script. ZFS is transactionally consistent; `zpool sync` + `umountall -l` + kernel's `vfs_syncall` (in `mdboot`) is sufficient. `root-fs/stop.sh` was corrected in rev 82.
Reference: `memory/pid1_shutdown_fix.md`, bug #2.

### 8. uadmin must not be called from PID 1

**Symptom:** `zygctl reboot` completes the shutdown log but does not reset the hardware. The kernel re-execs `/sbin/init`; uptime does not reset; orphaned daemons collide with the new instance.

**Cause:** `uadmin` called from PID 1 hits the `restart_init` path — the kernel re-execs init before `mdboot()` fires the hardware reset.

**Fix:** Fork a child; call `uadmin` from the child (non-PID-1). Parent enters infinite sleep. This mirrors `cmd/svc/startd/graph.c:do_uadmin`. See `src/main.reef` shutdown sequence.
Reference: `memory/pid1_shutdown_fix.md`, bug #1.

### 9. /etc/hosts: localhost only, no hostname entry

**Symptom:** SSH login takes ~20 seconds even with the network up.

**Cause:** The bare Hammerhead BE ships `/etc/hosts` with only `localhost`. `sshd` does a reverse DNS lookup on the client address; without a local entry or working resolver, it times out.

**Fix (operator):** Add the system's IP and hostname to `/etc/hosts`.
**Fix (upstream):** File as a Hammerhead base-system bug; the install or `identity` service should populate `/etc/hosts`. Not a zyginit issue.

---

## 5. Integration with Hammerhead

*This section specifies how to vendor zyginit into `hammerhead-userland` and
wire it into the Hammerhead build.*

### 5.1 Source layout

Recommended target layout in the Hammerhead source tree (BSD/illumos convention
for `cmd/` userland utilities):

```
usr/src/cmd/init/
    src/                  <- zyginit Reef source files
    src/helpers.c         <- required C helper (non-optional)
    services/             <- service TOML definitions and start/stop scripts
    reef.toml             <- reefc project config

usr/src/cmd/zygctl/
    src/                  <- zygctl Reef source files
    src/symlink_wrapper.c <- required C helper for zygctl

usr/src/cmd/sysv-wrapper/
    wrapper.c
    Makefile
    <- builds /sbin/sysv-wrapper; Makefile install creates symlinks

usr/src/man/man5/
    zyginit.5

usr/src/man/man8/
    zyginit.8
    zygctl.8
```

The sync mechanism (git submodule, source snapshot, or fetch-and-extract)
is the Hammerhead team's call. A simple approach: tag zyginit releases in its
repo, fetch a source archive at a known tag, unpack under `usr/src/cmd/init/`.

### 5.2 File-by-file source mapping

| zyginit repo path | Hammerhead target | Notes |
|---|---|---|
| `src/*.reef` | `usr/src/cmd/init/src/` | All Reef source files |
| `src/helpers.c` | `usr/src/cmd/init/src/` | Required for link |
| `src/contract_linux_stubs.c` | DROP | Linux-only stubs; not for Hammerhead |
| Hammerhead overlay tree (`base/usr/src/zyginit/overrides/`) | `usr/src/cmd/init/services/` | Production service definitions (already in-tree; deploy from Hammerhead side) |
| `reef.toml` | `usr/src/cmd/init/reef.toml` | reefc project config |
| `tools/zygctl/src/` | `usr/src/cmd/zygctl/src/` | zygctl Reef source |
| `tools/zygctl/src/symlink_wrapper.c` | `usr/src/cmd/zygctl/src/` | Required for zygctl link |
| `tools/zygctl/reef.toml` | `usr/src/cmd/zygctl/reef.toml` | zygctl reefc config |
| `tools/sysv-wrapper/wrapper.c` | `usr/src/cmd/sysv-wrapper/` | sysv-init compat wrapper |
| `tools/sysv-wrapper/Makefile` | `usr/src/cmd/sysv-wrapper/` | Builds + installs symlinks |
| `docs/man/man5/zyginit.5` | `usr/src/man/man5/` | |
| `docs/man/man8/zyginit.8` | `usr/src/man/man8/` | |
| `docs/man/man8/zygctl.8` | `usr/src/man/man8/` | |

### 5.3 Build invocation

The Hammerhead master build must invoke these steps for `usr/src/cmd/init/`:

```sh
# Build helpers.o
gcc -c src/helpers.c -o build/helpers.o

# Build zyginit daemon (produces build/zyginit)
reefc build -l contract --obj build/helpers.o

# Install
cp build/zyginit /sbin/init
```

For `usr/src/cmd/zygctl/`:

```sh
gcc -c src/symlink_wrapper.c -o build/symlink_wrapper.o
reefc build --obj build/symlink_wrapper.o
cp build/zygctl /sbin/zygctl
```

For `usr/src/cmd/sysv-wrapper/`:

```sh
make
make install
# Creates /sbin/sysv-wrapper and symlinks:
#   /sbin/halt -> /sbin/sysv-wrapper
#   /sbin/reboot -> /sbin/sysv-wrapper
#   /sbin/poweroff -> /sbin/sysv-wrapper
#   /sbin/telinit -> /sbin/sysv-wrapper
```

Service files must be installed to `/etc/zyginit/`. Source them from the
Hammerhead overlay tree (`base/usr/src/zyginit/overrides/`):

```sh
# Install per-service directory (contains service.toml + start.sh / stop.sh)
cp -r overrides/<svc>/ /etc/zyginit/services/<svc>/

# Enable services by symlinking into enabled.d/
ln -s /etc/zyginit/services/<svc> /etc/zyginit/enabled.d/<svc>
```

The `enabled.d/` naming convention uses the service name as the symlink name.
Tier ordering is derived from `[dependencies]` in the TOML; see the
`base/usr/src/zyginit/overrides/` tree for the current tier assignments.

### 5.4 Reef compiler dependency

Hammerhead's build requires `reefc`. Options:

1. **Bootstrap from Reef repo** — clone `~/repos/reef-lang/` (or the Reef
   upstream repo) and build `reefc` as part of the Hammerhead build setup.
   Required version: Reef 0.4.0+.
2. **Pre-built reefc** — package a pre-built `reefc` binary for the Hammerhead
   build host (the `hammerhead-build` VM at 192.168.122.66 already has
   a working `reefc`). Simpler short-term; breaks if the build host is
   reprovisioned.

`clang` is not available on Hammerhead (standard Hammerhead build host uses
`gcc`); use `gcc` for `helpers.c` and `symlink_wrapper.c`.

### 5.5 First migration step (concrete deliverable)

Before starting any new manifest conversions, complete this validation
sequence:

1. **Vendor zyginit source** at a known rev into `usr/src/cmd/init/` and
   `usr/src/cmd/zygctl/` and `usr/src/cmd/sysv-wrapper/`.
2. **Wire the build** to produce `/sbin/init`, `/sbin/zygctl`, and
   `/sbin/sysv-wrapper`.
3. **Deploy the production TOMLs** from Hammerhead's overlay tree
   (`base/usr/src/zyginit/overrides/`) into `/etc/zyginit/` and
   symlink them in `enabled.d/`.
4. **Build a Hammerhead BE** with the new binaries and service definitions.
5. **Boot hh-prototest** from the new BE; verify all 18 services reach
   `RUNNING` in `zygctl status`; verify SSH is reachable; verify console
   login works.
6. **Only then** begin the per-manifest conversion work using the decision
   tree and catalog.

Starting new conversions before step 5 is validated means any new issue
could be caused by the vendoring/build change rather than the conversion.

### 5.6 SMF removal step

Removing SMF infrastructure is a separate Hammerhead task after all needed
services have been converted. The sequence:

1. Remove `svc.startd` and `svc.configd` binaries from the build and packaging.
2. Remove SMF manifest XML files from `/lib/svc/manifest/` packaging.
3. Remove `libscf` linkage from any binary that links it but can be updated
   (check with `ldd -r /sbin/init` and any other boot-path binary).
4. Remove `svcadm`, `svccfg`, `svcs`, `svcprop` from the default packaging
   (optionally retain in a `smf-compat` package for administrators).
5. Verify boot still works end-to-end.

### 5.7 Upstream sync workflow

When zyginit ships new features (new TOML fields, runtime improvements):

1. Fetch the zyginit repo at a new tag or commit hash.
2. Refresh the vendored source under `usr/src/cmd/init/`.
3. Resolve any local Hammerhead patches that conflict.
4. Rebuild and test on `hh-prototest`.
5. Record the sync point (commit hash / rev number) in Hammerhead's
   changelog entry.

**See also:** Section 2 (Decision Tree), `docs/man/man5/zyginit.5`.

---

## 6. Per-Category Guidance

*This section gives top-down guidance for each SMF manifest tree category.
Read once for orientation, then drop into the catalog appendix (Section 7)
for per-manifest decisions.*

### `milestone/`

**Default: DROP all.** The six milestone manifests (`single-user`, `multi-user`,
`multi-user-server`, `network`, `name-services`, `sysconfig`) are SMF's
internal synchronization fences. zyginit replaces them with tier-ordered
service startup. When converting other manifests, drop all `<dependency>`
references to milestone FMRIs; replace with direct deps on the zyginit-managed
services that actually matter for ordering.

### `platform/`

**Default: keep amd64; drop all others.** There is only one platform manifest
on `hh-prototest`: `platform/amd64/acpihpd.xml` (ACPI hotplug daemon).
Hammerhead is amd64-only; no sun4u/sun4v entries exist on this system.
`acpihpd` is an amd64-platform-specific daemon for hotplug events —
investigate whether Hammerhead ships the hardware that needs it;
`needs-investigation` until confirmed.

### `network/`

**Selective.** Core networking (dlmgmtd, ipmgmtd — already converted, sshd)
are kept. The decision landscape:

- **Already converted:** dlmgmtd, ipmgmtd, sshd.
- **Consolidated into `network.toml`:** loopback, physical, initial, netmask,
  service, routing-setup — all collapsed into the single `network` oneshot.
- **Needs investigation:** NFS (does Hammerhead ship NFS client? server?),
  DNS resolver (likely needed; investigate whether to use a standalone
  `resolv.conf` or run `nscd`), ipfilter (does Hammerhead use it?),
  IPsec (policy and algs may be needed).
- **Drop:** NIS (`/network/nis/` — deprecated everywhere), iSCSI target/initiator
  (storage-specific; defer to zports), iSNS server, SMB client/server (defer),
  Kerberos KDC components (server-role only; defer to zports), LDAP client
  (environment-specific), loadbalancer (ilbd), Trusted Networking (tnctl/tnd
  — Trusted Extensions, which Hammerhead does not ship).
- **Drop inetd:** Hammerhead does not run inetd. The `inetd.xml` and
  `inetd-upgrade.xml` manifests are dropped. If any inetd-managed service is
  needed, write a standalone TOML for it.

### `system/`

The largest category; mixed disposition:

- **Already converted:** cron, cryptosvc (as `crypto`), devfs (devices-local),
  filesystem (local-fs + minimal-fs + root-fs), fmd, identity, pfexecd,
  syseventd, system-log (as `syslogd`), utmp (as `utmpd`), zones is pending.
- **Keep and convert:** coreadm, dumpadm, hotplug (if hardware warrants it),
  intrd (interrupt balancer daemon), keymap, power (powerd), rbac (config
  oneshot), scheduler, vtdaemon (VT multiplexer).
- **Needs investigation:** auditd (does Hammerhead ship BSM auditing?), idmap
  (identity mapping — needed if SMB/NFS Kerberos are used), name-service-cache
  (nscd), pools (resource pools — does Hammerhead use them?), rcap (resource
  capping), zonestat (zone statistics — relevant once zones are enabled).
- **Drop:** All of `system/svc/` (SMF infrastructure itself), `manifest-import`,
  `early-manifest-import`, `logadm-upgrade` (upgrade artifact), `boot-archive`
  and `boot-archive-update` (SMF-managed tasks; zyginit doesn't use
  boot-archive service), `update-man-index` (defer), `extended-accounting`
  (rarely used), `fcoe_initiator` / `fcoe_target` (storage-specific), IBSRP
  target (InfiniBand SRP — hardware-specific), `i2csimd` (platform-specific
  sensor daemon from a test tree), `labeld` (Trusted Extensions label daemon —
  Hammerhead does not ship TX), `tsol-zones` (Trusted Extensions zones), `ndmp`
  (backup protocol — defer to zports), `stmf` (SCSI Target Mode Framework —
  storage specific), `vscan` (virus scan framework — defer), `ipagent` (from
  a specific Nexenta/Triton context — likely irrelevant), `hostid` (sets
  hardware hostid; verify if Hammerhead needs it), `process-security` (noop
  service — just drop).

### `system/filesystem/`

**Default: all converted or redundant.** All four filesystem-related manifests
(`minimal-fs`, `local-fs`, `root-fs`, `usr-fs`) are collapsed into zyginit's
`filesystem.toml` and `root-fs.toml` onshots. `autofs` should be dropped
unless Hammerhead actively uses automounting. `vscan` is dropped.

### `system/fm/`

`fmd.xml` is already converted. `notify-params.xml` and `smtp-notify.xml` are
SMF notification hooks — drop or defer; zyginit has no equivalent mechanism.

### `system/device/`

`devices-local.xml` is the basis for the Hammerhead `devfs` service (the
devfsadm + soconfig oneshot; see `base/usr/src/zyginit/overrides/devfs/`).
`devices-audio.xml` can be method-wrapped or
dropped depending on whether Hammerhead ships audio support. `mpxio-upgrade.xml`
is an upgrade artifact; drop.

**See also:** Section 7 (Catalog Appendix) for per-manifest classification.

---

## 7. Catalog Appendix

*This appendix is a snapshot of all 128 SMF manifests found in
`/lib/svc/manifest/` and `/var/svc/manifest/` on `hh-prototest` as of
2026-05-02. It is a starting-point reference, not a living index — as
Hammerhead evolves, this catalog will drift from the actual source tree.*

*Classifications: `already-converted` (TOML exists in Hammerhead's overlay tree
at `base/usr/src/zyginit/overrides/`), `drop` (should not be in Hammerhead),
`foreground` (use daemon's foreground flag), `method-wrap` (keep the SMF method
script as exec.start), or `needs-investigation` (Hammerhead-team policy decision
required).*

| Manifest path | Category | Classification | Note |
|---|---|---|---|
| `/lib/svc/manifest/milestone/multi-user-server.xml` | milestone | drop | SMF milestone — no zyginit equivalent; referenced `<dependency>` blocks must be dropped from other conversions |
| `/lib/svc/manifest/milestone/multi-user.xml` | milestone | drop | SMF milestone — tier ordering replaces it |
| `/lib/svc/manifest/milestone/name-services.xml` | milestone | drop | SMF milestone — no zyginit equivalent |
| `/lib/svc/manifest/milestone/network.xml` | milestone | drop | SMF milestone — `network.toml` replaces it |
| `/lib/svc/manifest/milestone/single-user.xml` | milestone | drop | SMF milestone — `single-user-shell.toml` and runlevel mode replace it |
| `/lib/svc/manifest/milestone/sysconfig.xml` | milestone | drop | SMF milestone — exec=:true; purely a dependency fence |
| `/lib/svc/manifest/platform/amd64/acpihpd.xml` | platform | needs-investigation | ACPI hotplug daemon; amd64-specific; method script `/lib/svc/method/svc-acpihpd`; determine if Hammerhead hardware needs hotplug events |
| `/lib/svc/manifest/network/bridge.xml` | network | needs-investigation | Bridge networking daemon; determine if Hammerhead uses software bridging |
| `/lib/svc/manifest/network/dlmgmt.xml` | network | already-converted | Hammerhead overrides as `dlmgmtd`; foreground flag `-d` |
| `/lib/svc/manifest/network/dns/client.xml` | network | needs-investigation | DNS client configuration service (exec=:true — just stores resolver config in SMF repo); in zyginit world resolv.conf is written directly by the installer; determine if a service is needed |
| `/lib/svc/manifest/network/dns/install.xml` | network | drop | Install-time DNS setup artifact |
| `/lib/svc/manifest/network/dns/multicast.xml` | network | needs-investigation | mDNS daemon (`/usr/lib/inet/mdnsd`); determine if Hammerhead needs mDNS |
| `/lib/svc/manifest/network/forwarding.xml` | network | needs-investigation | IPv4/IPv6 forwarding toggle; determine if Hammerhead acts as a router |
| `/lib/svc/manifest/network/ibd-post-upgrade.xml` | network | drop | InfiniBand IPoIB upgrade artifact |
| `/lib/svc/manifest/network/inetd-upgrade.xml` | network | drop | inetd upgrade artifact; Hammerhead does not run inetd |
| `/lib/svc/manifest/network/inetd.xml` | network | drop | Hammerhead does not run inetd; existing `inetd.toml` in repo is an experiment, not production |
| `/lib/svc/manifest/network/ipfilter.xml` | network | needs-investigation | IP packet filter daemon; determine if Hammerhead uses ipfilter for firewall |
| `/lib/svc/manifest/network/ipsec/ipsecalgs.xml` | network | needs-investigation | IPsec algorithm loader (`ipsecalgs -s`); needed if Hammerhead uses IPsec; simple oneshot |
| `/lib/svc/manifest/network/ipsec/manual-key.xml` | network | needs-investigation | IPsec manual key management; needs-investigation if IPsec is used |
| `/lib/svc/manifest/network/ipsec/policy.xml` | network | needs-investigation | IPsec policy loader; simple oneshot if used |
| `/lib/svc/manifest/network/ipsec/tcpkey.xml` | network | needs-investigation | TCP MD5 key loading; obscure; likely drop |
| `/lib/svc/manifest/network/iscsi/iscsi-initiator.xml` | network | drop | iSCSI initiator; storage-specific; defer to zports |
| `/lib/svc/manifest/network/iscsi/iscsi-target.xml` | network | drop | iSCSI target; storage-specific; defer to zports |
| `/lib/svc/manifest/network/isns_server.xml` | network | drop | iSNS server; storage-specific; defer to zports |
| `/lib/svc/manifest/network/ldap/client.xml` | network | drop | LDAP client; enterprise-specific; defer to zports or site customization |
| `/lib/svc/manifest/network/loadbalancer/ilbd.xml` | network | drop | illumos load balancer daemon; Hammerhead does not ship this use case |
| `/lib/svc/manifest/network/network-initial.xml` | network | drop | Consolidated into `network.toml` |
| `/lib/svc/manifest/network/network-install.xml` | network | drop | Install-time artifact |
| `/lib/svc/manifest/network/network-ipmgmt.xml` | network | already-converted | Hammerhead overrides as `ipmgmtd`; foreground flag `-f` |
| `/lib/svc/manifest/network/network-ipmp.xml` | network | needs-investigation | IP Multipathing daemon (`in.mpathd`); needed if Hammerhead uses IPMP for NIC bonding |
| `/lib/svc/manifest/network/network-ipqos.xml` | network | needs-investigation | IP Quality of Service configuration; determine if Hammerhead uses IPQoS |
| `/lib/svc/manifest/network/network-iptun.xml` | network | needs-investigation | IP tunnel interfaces (GRE, etc.); determine if Hammerhead uses IP tunnels |
| `/lib/svc/manifest/network/network-location.xml` | network | drop | Network location/profile management (NWAM); Hammerhead uses static config |
| `/lib/svc/manifest/network/network-loopback.xml` | network | drop | Consolidated into `network.toml` |
| `/lib/svc/manifest/network/network-netmask.xml` | network | drop | Consolidated into `network.toml`; netmask config read directly |
| `/lib/svc/manifest/network/network-physical.xml` | network | drop | Consolidated into `network.toml` |
| `/lib/svc/manifest/network/network-routing-setup.xml` | network | drop | Consolidated into `network.toml`; static routing via `/etc/defaultrouter` |
| `/lib/svc/manifest/network/network-service.xml` | network | drop | Consolidated into `network.toml` |
| `/lib/svc/manifest/network/nfs/cbd.xml` | network | needs-investigation | NFS v4 callback daemon; needed only if NFS client is active |
| `/lib/svc/manifest/network/nfs/client.xml` | network | needs-investigation | NFS client; determine if Hammerhead ships NFS client support |
| `/lib/svc/manifest/network/nfs/mapid.xml` | network | needs-investigation | NFS v4 user/group ID mapping; needed with NFS v4 |
| `/lib/svc/manifest/network/nfs/nfslogd.xml` | network | needs-investigation | NFS logging daemon; server-side; drop unless NFS server is shipped |
| `/lib/svc/manifest/network/nfs/nlockmgr.xml` | network | needs-investigation | NFS lock manager; needed with NFS client or server |
| `/lib/svc/manifest/network/nfs/rquota.xml` | network | needs-investigation | Remote quota daemon; server-side; likely drop |
| `/lib/svc/manifest/network/nfs/server.xml` | network | needs-investigation | NFS server; determine if Hammerhead ships NFS server |
| `/lib/svc/manifest/network/nfs/status.xml` | network | needs-investigation | NFS status monitor; needed with NFS client or server |
| `/lib/svc/manifest/network/routing/legacy-routing.xml` | network | drop | Legacy in.routed/in.rdisc; Hammerhead uses static routing |
| `/lib/svc/manifest/network/routing/ndp.xml` | network | needs-investigation | IPv6 NDP daemon (`in.ndpd`); needed for IPv6 operation |
| `/lib/svc/manifest/network/routing/ripng.xml` | network | drop | RIPng routing daemon; dynamic routing; not needed for base system |
| `/lib/svc/manifest/network/rpc/bind.xml` | network | already-converted | Hammerhead overrides as `rpcbind`; direct exec `/usr/sbin/rpcbind` |
| `/lib/svc/manifest/network/rpc/gss.xml` | network | drop | GSSAPI daemon; needed only with Kerberos/NFS |
| `/lib/svc/manifest/network/rpc/smserver.xml` | network | drop | Removable media RPC service; obsolete |
| `/lib/svc/manifest/network/security/kadmin.xml` | network | drop | Kerberos admin server; server-role; defer to zports |
| `/lib/svc/manifest/network/security/krb5_prop.xml` | network | drop | Kerberos slave propagation; server-role |
| `/lib/svc/manifest/network/security/krb5kdc.xml` | network | drop | Kerberos KDC; server-role; defer to zports |
| `/lib/svc/manifest/network/security/ktkt_warn.xml` | network | drop | Kerberos ticket warning daemon; drop unless Kerberos client is used |
| `/lib/svc/manifest/network/shares/group.xml` | network | drop | Share group management (NFS/SMB shares); defer to zports |
| `/lib/svc/manifest/network/shares/reparsed.xml` | network | drop | Reparse point daemon (CIFS/SMB); drop |
| `/lib/svc/manifest/network/smb/client.xml` | network | drop | SMB client (smbfs); defer to zports |
| `/lib/svc/manifest/network/smb/server.xml` | network | drop | SMB server (smbd); defer to zports |
| `/lib/svc/manifest/network/ssh.xml` | network | already-converted | Hammerhead overrides as `sshd`; foreground flag `-D` |
| `/lib/svc/manifest/network/tnctl.xml` | network | drop | Trusted Extensions network control; TX not shipped in Hammerhead |
| `/lib/svc/manifest/network/tnd.xml` | network | drop | Trusted Extensions network daemon; TX not shipped in Hammerhead |
| `/lib/svc/manifest/network/varpd.xml` | network | needs-investigation | Virtual ARP daemon for overlay networking (VXLAN); determine if Hammerhead ships overlay networking |
| `/lib/svc/manifest/network/wpa.xml` | network | needs-investigation | WPA supplicant daemon; determine if Hammerhead supports Wi-Fi |
| `/lib/svc/manifest/system/auditd.xml` | system | needs-investigation | BSM audit daemon; determine if Hammerhead ships BSM auditing; method-wrap `/lib/svc/method/svc-auditd` if kept |
| `/lib/svc/manifest/system/auditset.xml` | system | needs-investigation | Audit policy oneshot; companion to auditd; same decision |
| `/lib/svc/manifest/system/boot-archive-update.xml` | system | drop | Updates boot archive after upgrade; SMF-infrastructure concern |
| `/lib/svc/manifest/system/boot-archive.xml` | system | drop | Checks boot archive consistency; zyginit does not manage boot archive |
| `/lib/svc/manifest/system/boot-config.xml` | system | drop | SMF boot config property store; no zyginit equivalent needed |
| `/lib/svc/manifest/system/consadm.xml` | system | needs-investigation | Console administration (alternate console); determine if needed |
| `/lib/svc/manifest/system/console-login.xml` | system | already-converted | Hammerhead overrides as `console-login`; complex wrapper writes utmpx entry before exec of ttymon |
| `/lib/svc/manifest/system/coreadm.xml` | system | method-wrap | `coreadm -U` to apply coreadm configuration; simple oneshot; inline `coreadm -U` directly in a TOML oneshot |
| `/lib/svc/manifest/system/cron.xml` | system | already-converted | Hammerhead overrides as `cron`; start.sh removes stale FIFO |
| `/lib/svc/manifest/system/cryptosvc.xml` | system | already-converted | Hammerhead overrides as `crypto`; `cryptoadm` oneshot |
| `/lib/svc/manifest/system/device/devices-audio.xml` | system | needs-investigation | Audio device setup; determine if Hammerhead ships audio support |
| `/lib/svc/manifest/system/device/devices-local.xml` | system | already-converted | Hammerhead overrides as `devfs`; start.sh runs devfsadm + soconfig |
| `/lib/svc/manifest/system/device/mpxio-upgrade.xml` | system | drop | MPXIO upgrade artifact |
| `/lib/svc/manifest/system/dumpadm.xml` | system | method-wrap | `svc-dumpadm` applies crash dump configuration; oneshot; wrap or inline `/usr/sbin/dumpadm -r /` |
| `/lib/svc/manifest/system/early-manifest-import.xml` | system | drop | SMF manifest import; exec=:true; no-op without SMF repo |
| `/lib/svc/manifest/system/extended-accounting.xml` | system | needs-investigation | Process/task/flow accounting via `acctadm`; rare use case |
| `/lib/svc/manifest/system/fcoe_initiator.xml` | system | drop | FCoE initiator; storage-specific; defer to zports |
| `/lib/svc/manifest/system/fcoe_target.xml` | system | drop | FCoE target; storage-specific; defer to zports |
| `/lib/svc/manifest/system/filesystem/autofs.xml` | system | drop | Automounter; not needed unless Hammerhead actively uses autofs |
| `/lib/svc/manifest/system/filesystem/local-fs.xml` | system | already-converted | Consolidated into Hammerhead overrides `filesystem` |
| `/lib/svc/manifest/system/filesystem/minimal-fs.xml` | system | already-converted | Consolidated into Hammerhead overrides `filesystem`; `/var/run` tmpfs mount is a follow-up |
| `/lib/svc/manifest/system/filesystem/root-fs.xml` | system | already-converted | Hammerhead overrides as `root-fs`; ZFS readonly assertion |
| `/lib/svc/manifest/system/filesystem/usr-fs.xml` | system | already-converted | Consolidated into Hammerhead overrides `filesystem` |
| `/lib/svc/manifest/system/filesystem/vscan.xml` | system | drop | Virus scan framework; defer to zports |
| `/lib/svc/manifest/system/fm/notify-params.xml` | system | drop | SMF notification hooks (exec=:true); no zyginit equivalent |
| `/lib/svc/manifest/system/fm/smtp-notify.xml` | system | needs-investigation | SMTP fault notification daemon; determine if Hammerhead ships this; foreground check: try `smtp-notify` without args |
| `/lib/svc/manifest/system/fmd.xml` | system | already-converted | Hammerhead overrides as `fmd`; foreground flag `-f` |
| `/lib/svc/manifest/system/hostid.xml` | system | needs-investigation | Sets hardware hostid via `svc-hostid` script; verify if Hammerhead needs a hostid set at boot |
| `/lib/svc/manifest/system/hotplug.xml` | system | needs-investigation | Hotplug daemon (`hotplugd` via `svc-hotplug`); determine if Hammerhead hardware needs it |
| `/lib/svc/manifest/system/i2csimd.xml` | system | drop | I2C sensor daemon from a test harness (`/opt/i2c-tests/`); not part of base system |
| `/lib/svc/manifest/system/ibsrp/target.xml` | system | drop | InfiniBand SRP target; hardware-specific; defer to zports |
| `/lib/svc/manifest/system/identity.xml` | system | already-converted | Hammerhead overrides as `identity`; sets hostname/nodename |
| `/lib/svc/manifest/system/idmap.xml` | system | needs-investigation | Identity mapping daemon (`idmapd`); needed with SMB or Kerberos |
| `/lib/svc/manifest/system/intrd.xml` | system | foreground | Interrupt distribution daemon; `svc-intrd` calls `/usr/lib/intrd`; check `intrd` source for `-f` or `-d` flag; method-wrap if no flag |
| `/lib/svc/manifest/system/ipagent.xml` | system | drop | Triton/SmartOS IP agent; not part of base Hammerhead |
| `/lib/svc/manifest/system/keymap.xml` | system | method-wrap | Keyboard map configuration; `keymap` script applies console keymap; simple oneshot via method-wrap or inline |
| `/lib/svc/manifest/system/labeld.xml` | system | drop | Trusted Extensions label daemon; TX not shipped in Hammerhead |
| `/lib/svc/manifest/system/logadm-upgrade.xml` | system | drop | Log rotation config upgrade artifact |
| `/lib/svc/manifest/system/manifest-import.xml` | system | drop | SMF manifest import daemon |
| `/lib/svc/manifest/system/name-service-cache.xml` | system | needs-investigation | nscd name service cache daemon; determine if Hammerhead needs nscd |
| `/lib/svc/manifest/system/ndmp.xml` | system | drop | NDMP backup protocol; defer to zports |
| `/lib/svc/manifest/system/pfexecd.xml` | system | already-converted | Hammerhead overrides as `pfexecd`; direct exec `/usr/lib/pfexecd` |
| `/lib/svc/manifest/system/picl.xml` | system | drop | PICL platform information daemon; Sun hardware-specific; not relevant for x86 virtual hardware |
| `/lib/svc/manifest/system/pools.xml` | system | needs-investigation | Resource pools (FSSv2); determine if Hammerhead uses resource pools |
| `/lib/svc/manifest/system/power.xml` | system | already-converted | Hammerhead overrides as `powerd`; direct exec or method-wrap `svc-power` |
| `/lib/svc/manifest/system/process-security.xml` | system | drop | Noop service (exec=:true); no functionality |
| `/lib/svc/manifest/system/rbac.xml` | system | method-wrap | RBAC database initialization; `svc-rbac start` oneshot; method-wrap or inline `/usr/sbin/svcadm` alternative — check what `svc-rbac` actually does |
| `/lib/svc/manifest/system/rcap.xml` | system | needs-investigation | Resource capping daemon (`rcapd`); determine if Hammerhead uses resource capping |
| `/lib/svc/manifest/system/resource-mgmt.xml` | system | needs-investigation | Resource management configuration; companion to pools and rcap |
| `/lib/svc/manifest/system/rmtmpfiles.xml` | system | method-wrap | Removes tmp files at boot (`rmtmpfiles` oneshot); simple method-wrap or inline `/bin/rm -rf /tmp/*` equivalent |
| `/lib/svc/manifest/system/sar.xml` | system | needs-investigation | System activity reporter (sar/sa); determine if Hammerhead ships `sar` |
| `/lib/svc/manifest/system/scheduler.xml` | system | method-wrap | Sets default scheduler class (`svc-scheduler`); oneshot; inspect `svc-scheduler` and inline if trivial |
| `/lib/svc/manifest/system/stmf.xml` | system | drop | SCSI Target Mode Framework; storage-specific; defer to zports |
| `/lib/svc/manifest/system/svc/global.xml` | system | drop | SMF global property store |
| `/lib/svc/manifest/system/svc/restarter.xml` | system | drop | IS svc.startd; zyginit replaces it |
| `/lib/svc/manifest/system/sysevent.xml` | system | already-converted | Hammerhead overrides as `syseventd`; method-wrap `svc-syseventd` |
| `/lib/svc/manifest/system/system-log.xml` | system | already-converted | Hammerhead overrides as `syslogd`; foreground flag `-d`; start.sh touches `/var/adm/messages` first |
| `/lib/svc/manifest/system/tsol-zones.xml` | system | drop | Trusted Extensions zones; TX not shipped in Hammerhead |
| `/lib/svc/manifest/system/update-man-index.xml` | system | drop | Man page index update; not needed at every boot |
| `/lib/svc/manifest/system/utmp.xml` | system | already-converted | Hammerhead overrides as `utmpd`; method-wrap `svc-utmpd` |
| `/lib/svc/manifest/system/vtdaemon.xml` | system | method-wrap | Virtual terminal multiplexer; `vtdaemon` script; determine if Hammerhead uses VTs; method-wrap if kept |
| `/lib/svc/manifest/system/zones.xml` | system | needs-investigation | Zones boot/halt service; zyginit will need a `zones` oneshot for `autoboot=true` zones; see `docs/DESIGN.md` Zones section |
| `/lib/svc/manifest/system/zonestat.xml` | system | needs-investigation | Zone statistics daemon (`zonestatd`); needed once zones are enabled |

**Catalog summary:**

| Classification | Count |
|---|---|
| `already-converted` | 19 |
| `drop` | 61 |
| `foreground` | 1 |
| `method-wrap` | 7 |
| `needs-investigation` | 40 |
| **Total** | **128** |

---

## 8. Format Reference Pointer

*This section points to the authoritative TOML format documentation.*

The zyginit service definition format — all valid fields, their types,
defaults, and semantics — is documented in `docs/man/man5/zyginit.5`.

The decision tree (Section 2) and catalog appendix (Section 7) use
field names from that reference. If a field name here appears to conflict
with what `man zyginit.5` says, the man page is authoritative.

For runtime behavior, signal handling, and socket protocol, see
`docs/man/man8/zyginit.8` and `docs/man/man8/zygctl.8`.

---

## 9. Glossary

*Definitions of SMF concepts that appear in this document for readers
without an illumos background.*

**BE (Boot Environment):** A ZFS dataset snapshot that represents a complete,
bootable OS image. Hammerhead supports multiple BEs; `beadm` (or direct
`zpool set bootfs`) selects which one the kernel boots.

**Contract (process contract):** A Hammerhead kernel mechanism that groups
related processes. When all processes in a contract exit, the kernel fires a
contract event. zyginit uses contracts to track service processes and detect
daemon exit without polling. See `docs/DESIGN.md` Contracts section.

**FMRI (Fault Management Resource Identifier):** SMF's naming scheme for
services, e.g., `svc:/network/ssh:default`. zyginit uses bare names (e.g.,
`sshd`) in TOML files instead.

**libcontract:** The Hammerhead userland library for managing process contracts.
zyginit links against it (`-l contract`). Not available on Linux.

**libscf (Service Configuration Facility):** The Hammerhead userland library
for reading and writing the SMF repository. Calls into `svc.configd` via a
door. A daemon that calls `scf_handle_create()` at startup requires configd
to be running.

**Manifest:** An XML file that describes an SMF service — its name, method
(start/stop command), dependencies, and properties. Stored in
`/lib/svc/manifest/`. zyginit replaces manifests with TOML files in
`/etc/zyginit/`.

**Method (SMF method):** The start, stop, or refresh command for an SMF
service, optionally implemented as a shell script in `/lib/svc/method/`.
The equivalent in zyginit is `[exec] start` and `[exec] stop`.

**Profile (SMF profile):** An XML file that selects which services are enabled
by default. zyginit replaces profiles with symlinks in `/etc/zyginit/enabled.d/`.

**Repository:** The SMF configuration database managed by `svc.configd`.
Stored in `/etc/svc/repository.db` (SQLite). zyginit has no database — service
state is in-memory only; configuration is in TOML files.

**Restarter:** In SMF, a service that manages other services. The master
restarter is `svc.startd`. zyginit is a single-process init that plays the
role of the restarter for all services.

**soconfig:** A Hammerhead utility (`/sbin/soconfig`) that loads the sockfs
protocol-to-module mapping from `/etc/sock2path.d/`. Must run before any
`socket(AF_INET, ...)` call succeeds. See Anti-patterns section 3.

**uadmin:** The Hammerhead system call for administrative operations including
halt, reboot, and poweroff. Must be called from a non-PID-1 process to avoid
the `restart_init` race. See Anti-patterns section 8.
# zyginit Administration Guide

## Overview

zyginit is the init daemon and service supervisor for Zygaena/Hammerhead.
It manages system services from boot to shutdown using TOML-based service
definitions, symlink-based enable/disable, and Hammerhead process contracts
for reliable service tracking.

This guide covers day-to-day administration: writing service definitions,
managing services with `zygctl`, understanding the boot sequence, and
troubleshooting.

## Quick Start

Check the status of all services:

```
$ zygctl status
sshd running pid=1234 ctid=7 uptime=2h30m restarts=0
cron running pid=1235 ctid=8 uptime=2h30m restarts=0
filesystem stopped exit=0
network stopped exit=0
```

Start or stop a service:

```
# zygctl start sshd
sshd started

# zygctl stop sshd
sshd stopping
```

Enable a service to start at boot:

```
# zygctl enable sshd
# zygctl disable sshd
```

List all known service definitions:

```
$ zygctl list
sshd (daemon)
cron (daemon)
network (oneshot)
filesystem (oneshot)
```

## Service Definitions

Service definitions are TOML files in `/etc/zyginit/`. Each file
describes a single service.

### Directory Layout

```
/etc/zyginit/
├── sshd.toml               # Service definition
├── cron.toml
├── syslog.toml
├── network.toml
├── network/                 # Scripts for complex startup
│   └── start.sh
├── filesystem.toml
├── filesystem/
│   └── start.sh
└── enabled.d/               # Symlinks = what starts at boot
    ├── sshd -> ../sshd.toml
    ├── cron -> ../cron.toml
    ├── syslog -> ../syslog.toml
    ├── network -> ../network.toml
    └── filesystem -> ../filesystem.toml
```

### Enabling and Disabling

A service starts at boot only if it has a symlink in `enabled.d/`. The
symlink name must match the service name (without `.toml`):

```
# Enable:
ln -s ../sshd.toml /etc/zyginit/enabled.d/sshd

# Disable:
rm /etc/zyginit/enabled.d/sshd
```

Or use `zygctl`:

```
# zygctl enable sshd
# zygctl disable sshd
```

Enabling does not start the service immediately. Disabling does not stop
it. Use `zygctl start` and `zygctl stop` for immediate control.

### Reloading Configuration

After enabling or disabling services, tell zyginit to re-scan the
`enabled.d/` directory:

```
# zygctl reload
```

Newly-enabled services are started; disabled services are stopped. This
is equivalent to sending SIGHUP to the zyginit process.

### Viewing Service Logs

zyginit captures stdout and stderr from each service to per-service log
files under `/var/run/zyginit/log/`. Log files are truncated on each
service start, so only the most recent output is available.

```
$ zygctl log sshd
```

This is useful for diagnosing startup failures. For long-term logging,
services should use syslog or their own logging mechanism.

## Writing Service Definitions

### Service Types

| Type | Description | Boot behavior | Restart |
|------|-------------|---------------|---------|
| `daemon` | Long-running process | Started and monitored | Per restart policy |
| `oneshot` | Runs once at boot | Runs, then "done" | Never |
| `transient` | On-demand only | Not started at boot | Per restart policy |

### Complete TOML Schema

```toml
[service]
name = "string"           # Required. Unique identifier.
description = "string"    # Optional. Human-readable.
type = "daemon"           # Required. daemon | oneshot | transient

[exec]
start = "command"         # Required. Command to start the service.
stop = "command"          # Optional. Only used with method = "exec".
working_directory = "/path"  # Optional. chdir before exec.
user = "username"         # Optional. Drop privileges to this user.
group = "groupname"       # Optional. Override primary group.
environment = ["K=V"]     # Optional. Set env vars before exec.

[stop]
method = "contract"       # Optional. contract (default) | exec
signal = "TERM"           # Optional. Signal name without SIG prefix.
timeout = 60              # Optional. Seconds before SIGKILL.

[dependencies]
requires = ["svc1"]       # Optional. Must be running first.
after = ["svc2"]          # Optional. Ordering only, not hard dep.

[contract]
param = ["inherit", "noorphan"]   # Optional. Contract parameters.
fatal = ["empty", "hwerr"]        # Optional. Fatal event types.

[restart]
on = "failure"            # Optional. always | failure (default) | never
delay = 5                 # Optional. Seconds between restarts.
max_retries = 3           # Optional. -1 = unlimited.
```

### Simple Daemon

Most daemons need only a few lines. Defaults handle the rest:

```toml
# /etc/zyginit/cron.toml
[service]
name = "cron"
description = "Clock Daemon"
type = "daemon"

[exec]
start = "/usr/sbin/cron"

[dependencies]
requires = ["filesystem"]
after = ["syslog"]
```

This uses all defaults: contract-based stop with SIGTERM, 60-second
timeout, restart on failure with 5-second delay and 3 retries.

### Foreground Daemons

zyginit tracks service processes via contracts. Daemons should run in the
foreground (not fork into the background) so that zyginit can monitor the
actual process. Most daemons support a foreground flag:

| Daemon | Foreground flag |
|--------|-----------------|
| sshd | `-D` |
| ntpd | `-n` |
| syslogd | `-d` (debug/foreground) |

Example:

```toml
[exec]
start = "/usr/lib/ssh/sshd -D"
```

If a daemon does not support foreground mode, zyginit's contract mechanism
still tracks all descendant processes, including the backgrounded child.

### Oneshot Services

Oneshot services run a command once at boot. They are useful for setup
tasks like mounting filesystems, configuring network interfaces, or
setting the hostname.

```toml
# /etc/zyginit/hostname.toml
[service]
name = "hostname"
description = "Set System Hostname"
type = "oneshot"

[exec]
start = "/usr/bin/hostname myhost"

[dependencies]
requires = ["root-fs"]

[restart]
on = "never"
```

A oneshot service with exit code 0 enters the `stopped` state. A non-zero
exit puts it in the `failed` state.

### Script Escape Hatch

For complex startup logic, put scripts in a subdirectory matching the
service name:

```
/etc/zyginit/
├── network.toml
└── network/
    └── start.sh
```

```toml
# network.toml
[service]
name = "network"
description = "Network Interface Configuration"
type = "oneshot"

[exec]
start = "/etc/zyginit/network/start.sh"
```

The start script can use `ipadm`, `dladm`, and other tools to
configure interfaces. Keep scripts simple and idempotent where possible.

### Custom Stop Commands

Some services need a specific shutdown procedure (e.g., databases):

```toml
[exec]
start = "/etc/zyginit/postgresql/start.sh"
stop = "/etc/zyginit/postgresql/stop.sh"

[stop]
method = "exec"
timeout = 120
```

When `method = "exec"`, zyginit runs the stop command instead of
signaling the process contract. The timeout still applies; if the stop
command does not complete in time, zyginit sends SIGKILL.

### Working Directory

Use `working_directory` to change to a specific directory before starting
the service. Useful for applications that expect to run from a particular
path:

```toml
[exec]
start = "/usr/lib/myapp/bin/server"
working_directory = "/var/lib/myapp"
```

### Environment Variables

Set environment variables for the service process using the `environment`
array. Each entry has the form `KEY=value`:

```toml
[exec]
start = "/usr/lib/postgresql/bin/postgres -D /var/lib/pgsql/data"
environment = ["PGDATA=/var/lib/pgsql/data", "LANG=en_US.UTF-8", "TZ=US/Pacific"]
```

These variables are set in the child process before exec and do not
affect zyginit itself or other services.

### Privilege Separation

Run services as a non-root user with the `user` and `group` fields.
Before executing the start command, zyginit drops privileges by calling
`setgid()`, `initgroups()`, and `setuid()` in the correct order:

```toml
[exec]
start = "/usr/lib/ssh/sshd -D"
user = "sshd"
group = "sshd"
```

If only `user` is specified, the primary group is determined from the
user's passwd entry. If both `user` and `group` are specified, the
group overrides the user's primary group.

If the user or group lookup fails, the service start fails and the
error is logged.

### Dependencies

Dependencies control boot order. There are two kinds:

**`requires`** — Hard dependencies. The listed services must be running
before this service starts. If a required service is not enabled, zyginit
prints a warning.

**`after`** — Soft ordering. The listed services should start first, but
if they are not enabled, this service starts anyway.

```toml
[dependencies]
requires = ["network", "filesystem"]
after = ["name-services", "syslog"]
```

zyginit performs a topological sort to group services into parallel boot
tiers. Services within the same tier can start concurrently.

### Restart Policies

For daemon services, the restart policy determines what happens when the
process exits:

| Policy | Behavior |
|--------|----------|
| `always` | Restart regardless of exit code |
| `failure` | Restart only on non-zero exit (default) |
| `never` | Do not restart |

The `delay` field sets the wait time (seconds) between restarts. The
`max_retries` field sets the maximum consecutive restart attempts before
the service enters `maintenance` state. Set `max_retries = -1` for
unlimited.

```toml
[restart]
on = "always"
delay = 10
max_retries = -1
```

### Process Contract Parameters

The `[contract]` section controls Hammerhead kernel process contracts.
Most services should use the defaults:

```toml
[contract]
param = ["inherit", "noorphan"]
fatal = ["empty", "hwerr"]
```

| Parameter | Description |
|-----------|-------------|
| `inherit` | Child processes inherit the contract |
| `noorphan` | Kill orphans when contract is abandoned |
| `pgrponly` | Track only the process group leader |
| `regent` | Contract owner acts as regent |

| Fatal event | Description |
|-------------|-------------|
| `empty` | All processes in the contract exited |
| `hwerr` | Hardware error detected |
| `core` | A process produced a core dump |
| `signal` | A process was killed by a signal |

## Boot Sequence

When zyginit starts as PID 1, the boot proceeds as follows:

1. **Scan** `/etc/zyginit/enabled.d/` for symlinks
2. **Parse** each linked TOML file to load service definitions
3. **Build** a dependency graph from `requires` and `after` declarations
4. **Sort** the graph into parallel boot tiers (topological sort)
5. **Start** services tier by tier
6. **Open** the control socket at `/var/run/zyginit.sock`
7. **Enter** the main event loop

The event loop monitors three sources via `poll(2)`:

- **Process contracts** — service exit events from the kernel
- **Signal pipe** — SIGCHLD, SIGTERM, SIGHUP
- **Control socket** — commands from `zygctl`

Every loop iteration also checks for stop timeouts (escalate to SIGKILL)
and restart delays (restart services whose delay has elapsed).

## Shutdown

When zyginit receives SIGTERM or SIGINT, it performs a graceful shutdown:

1. Stop accepting new `zygctl` connections
2. Stop all running services in reverse boot order
3. Wait for each service to exit (respecting stop timeouts)
4. Clean up the control socket
5. Exit

## Troubleshooting

### Service in maintenance state

A service enters maintenance when it has exceeded `max_retries`. To
recover:

```
# zygctl restart myservice
```

Investigate the cause of repeated failures before restarting. Check
service logs, file permissions, and dependency availability.

### Service won't start

Check the service output log for error messages:

```
$ zygctl log myservice
```

Also check that:
- The TOML file exists in `/etc/zyginit/`
- The TOML syntax is valid
- The `start` command path exists and is executable
- All `requires` dependencies are enabled and running
- The service name matches the filename (without `.toml`)
- If `user`/`group` is specified, the user and group exist on the system

### Cannot connect to zyginit

If `zygctl` reports "cannot connect":
- Verify zyginit is running: `ps -ef | grep zyginit`
- Check the socket exists: `ls -la /var/run/zyginit.sock`
- If using a custom socket path, set `ZYGINIT_SOCKET`

### Orphaned processes

On Hammerhead, process contracts prevent orphans. The `noorphan` contract
parameter (default) ensures all descendant processes are killed when a
service's contract is abandoned.

On systems without contract support, zyginit tracks only the direct child
PID and cannot guarantee cleanup of grandchild processes.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `ZYGINIT_CONFIG_DIR` | `/etc/zyginit` | Service definition directory |
| `ZYGINIT_SOCKET` | `/var/run/zyginit.sock` | Control socket path |
| `ZYGINIT_LOG_DIR` | `/var/run/zyginit/log` | Per-service log directory |

These are primarily useful for development and testing. In production,
the defaults should be used.
.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGINIT 5
.Os Hammerhead
.Sh NAME
.Nm zyginit
.Nd service definition format for zyginit
.Sh DESCRIPTION
Service definitions for
.Xr zyginit 8
are TOML files stored in
.Pa /etc/zyginit/ .
Each file describes a single service: its type, how to start and stop it,
its dependencies on other services, process contract parameters, and
restart policy.
.Pp
Services are enabled for boot by creating a symlink in the
.Pa /etc/zyginit/enabled.d/
subdirectory.
See
.Xr zygctl 8
for commands to manage the enabled set.
.Sh FILE FORMAT
Each service definition is a TOML file with the following sections.
.Ss [service]
Required.
Identifies the service.
.Bl -tag -width "description"
.It Sy name Pq string, required
A unique identifier for the service.
This name is used in dependency declarations, symlinks, and
.Xr zygctl 8
commands.
Must match the filename without the
.Pa .toml
extension.
.It Sy description Pq string, optional
A human-readable description of the service.
.It Sy type Pq string, required
The service type.
One of:
.Bl -tag -width "transient" -compact
.It Cm daemon
A long-running process monitored continuously.
.It Cm oneshot
A short-lived process that runs once at boot.
.It Cm transient
A process started on demand, not at boot.
.El
.El
.Ss [exec]
Required.
Defines the commands used to start and optionally stop the service.
.Bl -tag -width "start"
.It Sy start Pq string, required
The command to execute when starting the service.
This may be a direct path to a daemon binary with arguments,
or a path to a shell script for services requiring complex startup logic.
.Pp
For daemon services, the command should run in the foreground
.Pq not daemonize itself
so that
.Xr zyginit 8
can track the process.
.It Sy stop Pq string, optional
A command to execute when stopping the service.
Only used when
.Sy [stop] method
is set to
.Cm exec .
If not specified, the service is stopped by signaling its process contract.
.It Sy working_directory Pq string, optional
Change to this directory before executing the start command.
Useful for services that expect to run from a specific path.
.It Sy user Pq string, optional
Run the service as this user.
The daemon looks up the user's UID and primary GID via
.Xr getpwnam 3 ,
then drops privileges with
.Xr setgid 2 ,
.Xr initgroups 3 ,
and
.Xr setuid 2
before executing the start command.
.It Sy group Pq string, optional
Run the service with this group.
Overrides the user's primary group if both
.Sy user
and
.Sy group
are specified.
.It Sy environment Pq array of strings, optional
Environment variables to set before executing the start command.
Each entry has the form
.Dq KEY=value .
Example:
.Bd -literal -offset indent
environment = ["LANG=en_US.UTF-8", "TZ=US/Pacific"]
.Ed
.El
.Ss [stop]
Optional.
Controls how the service is stopped.
.Bl -tag -width "timeout"
.It Sy method Pq string
The stop method.
One of:
.Bl -tag -width "contract" -compact
.It Cm contract
Send a signal to all processes in the service's contract.
This is the default and preferred method.
.It Cm exec
Execute the command specified in
.Sy [exec] stop .
.El
Default:
.Cm contract .
.It Sy signal Pq string
The signal to send when using the
.Cm contract
stop method.
Specified without the
.Dq SIG
prefix.
Common values:
.Cm TERM , HUP , INT , KILL , USR1 , USR2 .
.Pp
Default:
.Cm TERM .
.It Sy timeout Pq integer
The number of seconds to wait for the service to stop before
escalating to
.Dv SIGKILL .
.Pp
Default: 60.
.El
.Ss [dependencies]
Optional.
Declares relationships with other services.
.Bl -tag -width "requires"
.It Sy requires Pq array of strings
Services that must be running before this service can start.
If a required service fails or is not enabled,
.Xr zyginit 8
will print a warning during boot.
.Pp
Example:
.Dl requires = ["network", "filesystem"]
.It Sy after Pq array of strings
Services that should be started before this service, but are not
hard dependencies.
If an
.Cm after
service is not enabled, this service still starts normally.
.Pp
Example:
.Dl after = ["syslog", "name-services"]
.It Sy conflicts Pq array of strings
Services that must never run at the same time as this one.
The relation is symmetric: declaring the conflict on either service is enough.
If two conflicting services are both enabled at boot,
.Em both
are marked failed (zyginit never auto-selects a winner).
At runtime,
.Xr zygctl 8
.Cm start
is refused if a conflicting service is already running.
.Pp
Example:
.Dl conflicts = ["sendmail"]
.El
.Ss [contract]
Optional.
Controls Hammerhead process contract parameters.
See
.Xr contract 5
for details.
.Bl -tag -width "param"
.It Sy param Pq array of strings
Contract parameter flags.
Supported values:
.Bl -tag -width "noorphan" -compact
.It Cm inherit
Child processes inherit the contract.
.It Cm noorphan
Orphaned processes are killed when the contract is abandoned.
.It Cm pgrponly
Only the process group leader is tracked.
.It Cm regent
The contract owner acts as regent for the child.
.El
.Pp
Default:
.Cm inherit , noorphan .
.It Sy fatal Pq array of strings
Events that are considered fatal for the contract.
Supported values:
.Bl -tag -width "signal" -compact
.It Cm empty
All processes in the contract have exited.
.It Cm core
A process produced a core dump.
.It Cm hwerr
A hardware error was detected.
.It Cm signal
A process was killed by a fatal signal.
.El
.Pp
Default:
.Cm empty , hwerr .
.El
.Ss [restart]
Optional.
Controls the restart policy for daemon services.
Ignored for oneshot services.
.Bl -tag -width "max_retries"
.It Sy on Pq string
When to restart the service.
One of:
.Bl -tag -width "failure" -compact
.It Cm always
Restart regardless of exit status.
.It Cm failure
Restart only if the exit status is non-zero.
.It Cm never
Do not restart.
.El
.Pp
Default:
.Cm failure .
.It Sy delay Pq integer
The number of seconds to wait before restarting.
.Pp
Default: 5.
.It Sy max_retries Pq integer
The maximum number of consecutive restart attempts before
placing the service into
.Sy maintenance
state.
Set to \-1 for unlimited retries.
.Pp
Default: 3.
.El
.Sh DIRECTORY LAYOUT
.Bd -literal -offset indent
/etc/zyginit/
\(ba\(em sshd.toml              # Service definition
\(ba\(em cron.toml
\(ba\(em network.toml
\(ba\(em filesystem.toml
\(ba\(em network/               # Scripts for complex services
\(ba   \(em start.sh
\(ba\(em enabled.d/             # Symlinks to enabled services
    \(ba\(em sshd -> ../sshd.toml
    \(em cron -> ../cron.toml
.Ed
.Ss Script Escape Hatch
For services requiring complex startup logic
.Pq database initialization, multi-step network configuration ,
the
.Sy [exec] start
field can point to a shell script in a subdirectory matching the
service name:
.Bd -literal -offset indent
/etc/zyginit/
\(ba\(em postgresql.toml
\(em postgresql/
    \(ba\(em start.sh
    \(em stop.sh
.Ed
.Sh EXAMPLES
.Ss Simple Daemon
A long-running daemon with standard restart behavior:
.Bd -literal -offset indent
[service]
name = "sshd"
description = "Secure Shell Daemon"
type = "daemon"

[exec]
start = "/usr/lib/ssh/sshd -D"

[stop]
method = "contract"
signal = "TERM"
timeout = 60

[dependencies]
requires = ["network", "filesystem"]
after = ["name-services"]

[contract]
param = ["inherit", "noorphan"]
fatal = ["empty", "hwerr"]

[restart]
on = "failure"
delay = 5
max_retries = 3
.Ed
.Ss Oneshot Service
A boot-time task that runs once:
.Bd -literal -offset indent
[service]
name = "filesystem"
description = "Local Filesystem Mounts"
type = "oneshot"

[exec]
start = "/etc/zyginit/filesystem/start.sh"

[dependencies]
requires = ["root-fs"]

[restart]
on = "never"
.Ed
.Ss Service with Custom Stop Command
.Bd -literal -offset indent
[service]
name = "postgresql"
description = "PostgreSQL Database Server"
type = "daemon"

[exec]
start = "/etc/zyginit/postgresql/start.sh"
stop = "/etc/zyginit/postgresql/stop.sh"

[stop]
method = "exec"
timeout = 120

[dependencies]
requires = ["filesystem", "network"]

[restart]
on = "failure"
delay = 10
max_retries = 3
.Ed
.Ss Minimal Service
Only the required fields:
.Bd -literal -offset indent
[service]
name = "myapp"
description = "My Application"
type = "daemon"

[exec]
start = "/usr/local/bin/myapp"
.Ed
.Pp
This service uses all defaults: contract stop method with SIGTERM,
60-second timeout, restart on failure with 5-second delay and
3 maximum retries.
.Sh SEE ALSO
.Xr zyginit 8 ,
.Xr zygctl 8 ,
.Xr contract 5 ,
.Xr toml 5
.Sh HISTORY
The
.Nm
service definition format first appeared in Zygaena/Hammerhead as part of the
.Xr zyginit 8
init system.
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com
.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGCTL 8
.Os Hammerhead
.Sh NAME
.Nm zygctl
.Nd administrative control utility for zyginit
.Sh SYNOPSIS
.Nm
.Ar command
.Op Ar argument
.Sh DESCRIPTION
.Nm
is the administrative command-line interface for the
.Xr zyginit 8
service supervisor.
It communicates with the running
.Nm zyginit
daemon over a Unix domain socket to query service status,
start and stop services, and manage the enabled service set.
.Pp
Commands that modify the enabled service set
.Pq Cm enable , Cm disable
operate directly on the filesystem and do not require the daemon to be running.
All other commands connect to the daemon socket.
.Sh COMMANDS
.Bl -tag -width "restart"
.It Cm status Op Ar name
Display the status of all services, or of the named service if
.Ar name
is given.
Output includes the service name, current state, and if running,
the process ID and contract ID.
.It Cm start Ar name
Start the named service.
If the service is already running, a message is printed and no
action is taken.
.It Cm stop Ar name
Stop the named service.
The stop method is determined by the service definition: either
a contract-wide signal or execution of a stop command.
If the service does not stop within its configured timeout, it
is forcibly terminated with
.Dv SIGKILL .
.It Cm restart Ar name
Restart the named service.
If the service is running, it is stopped first.
If the service is stopped or in maintenance, it is started immediately.
.It Cm list
List all loaded service definitions with their type
.Pq daemon, oneshot, transient .
.It Cm enable Ar name
Enable a service for automatic start at boot.
Creates a symlink in
.Pa /etc/zyginit/enabled.d/
pointing to the service's TOML definition.
The service is not started immediately; use
.Cm start
to start it now.
.It Cm disable Ar name
Disable a service from automatic start at boot.
Removes the symlink from
.Pa /etc/zyginit/enabled.d/ .
The service is not stopped immediately; use
.Cm stop
to stop it now.
.It Cm log Ar name
Display the output log for the named service.
Service stdout and stderr are captured to per-service log files under
.Pa /var/run/zyginit/log/ .
Log files are truncated on each service start, so only the most recent
output is shown.
Useful for diagnosing startup failures.
.It Cm reload
Reload the service configuration.
The daemon re-scans
.Pa /etc/zyginit/enabled.d/
and compares with the current service table.
Newly-enabled services are started; disabled services are stopped.
This is equivalent to sending
.Dv SIGHUP
to the
.Xr zyginit 8
process.
.It Cm replace Op Fl -wait Ns = Ns Ar N
Replace the running
.Xr zyginit 8
process via in-place
.Xr execve 2
of
.Pa /sbin/init .
All running services keep running across the swap; their process
contracts, restart counters, and uptimes are preserved via a state
file at
.Pa /var/run/zyginit/state.toml .
The operator must drop the new binary at
.Pa /sbin/init
.Em before
issuing this command;
.Nm
does not stage or copy binaries.
.Pp
With
.Fl -wait Ns = Ns Ar N ,
poll up to
.Ar N
seconds for any service in a transient state
.Pq starting , stopping , waiting
to stabilize before refusing.
Default is
.Ar N
=
.Sy 0
(refuse immediately).
Useful for automation: run
.Nm
.Cm replace Fl -wait Ns = Ns Sy 60
to either succeed within a minute or fail with a known upper bound on
time.
.Pp
The replace flow is operator-driven only; it does not cover crash
recovery.
See
.Xr zyginit 8
for the full mechanism.
.It Cm version
Print the version of
.Nm .
.It Cm help
Print a summary of available commands.
.El
.Sh ENVIRONMENT
.Bl -tag -width "ZYGINIT_CONFIG_DIR"
.It Ev ZYGINIT_SOCKET
Path to the
.Xr zyginit 8
control socket.
Default:
.Pa /var/run/zyginit.sock
.It Ev ZYGINIT_LOG_DIR
Path to the per-service log directory.
Used by the
.Cm log
command.
Default:
.Pa /var/run/zyginit/log
.It Ev ZYGINIT_CONFIG_DIR
Path to the service definition directory.
Used by the
.Cm enable
and
.Cm disable
commands to locate TOML files and the
.Pa enabled.d/
subdirectory.
Default:
.Pa /etc/zyginit
.El
.Sh EXIT STATUS
.Nm
exits 0 on success.
If it cannot connect to the daemon socket, a diagnostic message is
printed to standard error.
.Sh EXAMPLES
Show the status of all services:
.Bd -literal -offset indent
$ zygctl status
sshd running pid=1234 ctid=7
cron running pid=1235 ctid=8
filesystem stopped
.Ed
.Pp
Show the status of a single service:
.Bd -literal -offset indent
$ zygctl status sshd
sshd running pid=1234 ctid=7
.Ed
.Pp
Stop and disable a service:
.Bd -literal -offset indent
# zygctl stop sshd
sshd stopping
# zygctl disable sshd
.Ed
.Pp
Enable and start a service:
.Bd -literal -offset indent
# zygctl enable sshd
# zygctl start sshd
sshd started
.Ed
.Pp
List all loaded service definitions:
.Bd -literal -offset indent
$ zygctl list
sshd (daemon)
cron (daemon)
network (oneshot)
filesystem (oneshot)
.Ed
.Sh SEE ALSO
.Xr zyginit 8 ,
.Xr zyginit 5
.Sh HISTORY
.Nm
first appeared in Zygaena/Hammerhead alongside
.Xr zyginit 8 .
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com
.\"
.\" Copyright (c) 2025-2026, Leafscale, LLC.  All rights reserved.
.\" Use is subject to license terms.
.\"
.Dd March 6, 2026
.Dt ZYGINIT 8
.Os Hammerhead
.Sh NAME
.Nm zyginit
.Nd init daemon and service supervisor for Zygaena/Hammerhead
.Sh SYNOPSIS
.Nm
.Sh DESCRIPTION
.Nm
is the init daemon (PID 1) and service supervisor for the
Zygaena/Hammerhead operating system.
It replaces SMF
.Pq Service Management Facility
with a single-process, TOML-configured service manager.
.Pp
At boot,
.Nm
performs the following sequence:
.Bl -enum
.It
Scans the enabled services directory for symlinks
.Pq see Sx CONFIGURATION .
.It
Reads each service's TOML definition to extract dependencies.
.It
Performs a topological sort to determine parallel boot tiers.
.It
Starts services tier by tier, respecting dependency order.
.It
Opens a Unix domain socket for
.Xr zygctl 8
communication.
.It
Enters the main event loop, monitoring process contracts, signals,
and the control socket via
.Xr poll 2 .
.El
.Pp
.Nm
supervises all managed services.
When a service exits, the restart policy defined in its TOML definition
determines whether the service is restarted, placed into maintenance,
or left stopped.
.Ss Service Types
.Nm
supports three service types:
.Bl -tag -width "transient"
.It Sy daemon
A long-running process.
.Nm
monitors the process via a Hammerhead process contract and applies the
restart policy when it exits.
.It Sy oneshot
A short-lived process that runs once at boot
.Pq e.g., mounting filesystems, configuring network interfaces .
Once it exits successfully, the service is considered
.Dq done .
A non-zero exit places the service into the
.Sy failed
state.
.It Sy transient
A process started on demand via
.Xr zygctl 8
that is not started automatically at boot.
.El
.Ss Service States
Each managed service is in one of the following states:
.Bl -tag -width "maintenance"
.It Sy disabled
The service is not enabled for boot
.Pq no symlink in Ar enabled.d .
.It Sy waiting
The service is waiting to start
.Pq dependency not yet met or restart delay pending .
.It Sy starting
The service is being started
.Pq fork/exec in progress .
.It Sy running
The service process is alive and being monitored.
.It Sy stopping
A stop has been requested; waiting for the process to exit.
.It Sy stopped
The service has exited and will not be restarted.
.It Sy failed
The service exited abnormally
.Pq oneshot with non-zero exit, or unrecoverable error .
.It Sy maintenance
The service has exceeded its maximum restart count.
Administrative intervention is required.
Use
.Xr zygctl 8
to clear and restart.
.El
.Ss Process Contracts
On Hammerhead,
.Nm
uses kernel process contracts
.Pq see Xr contract 5
to track all descendants of a service process.
This ensures that orphaned grandchild processes are properly managed
and that
.Nm
receives notification when all processes in a service's contract have exited.
.Pp
When
.Nm
is restarted
.Pq e.g., for an upgrade ,
it re-adopts existing contracts so that running services are not disrupted.
.Pp
On systems without process contract support,
.Nm
falls back to direct PID-based monitoring via
.Xr waitpid 2 .
.Ss Signal Handling
.Nm
handles the following signals:
.Bl -tag -width "SIGCHLD"
.It Dv SIGTERM , Dv SIGINT
Initiate graceful shutdown.
All running services are stopped in reverse boot order.
.It Dv SIGHUP
Reload service configuration.
The daemon re-scans
.Pa /etc/zyginit/enabled.d/
and compares with the current service table.
Newly-enabled services are started; disabled services are stopped.
This is equivalent to the
.Cm reload
command in
.Xr zygctl 8 .
.It Dv SIGCHLD
Reap exited child processes and dispatch to the service supervisor.
.It Dv SIGPIPE
Ignored.
.El
.Sh CONFIGURATION
.Nm
reads its service definitions from
.Pa /etc/zyginit/ .
Each service is defined by a TOML file in that directory.
See
.Xr zyginit 5
for the full service definition format.
.Ss Enabling and Disabling Services
Services are enabled by creating a symlink in the
.Pa enabled.d
subdirectory:
.Bd -literal -offset indent
/etc/zyginit/enabled.d/sshd -> ../sshd.toml
.Ed
.Pp
To enable a service:
.Bd -literal -offset indent
# zygctl enable sshd
.Ed
.Pp
To disable:
.Bd -literal -offset indent
# zygctl disable sshd
.Ed
.Pp
These operations can also be performed manually with
.Xr ln 1
and
.Xr rm 1 .
.Sh ENVIRONMENT
.Bl -tag -width "ZYGINIT_CONFIG_DIR"
.It Ev ZYGINIT_CONFIG_DIR
Path to the service definition directory.
Default:
.Pa /etc/zyginit
.It Ev ZYGINIT_SOCKET
Path to the Unix domain socket for
.Xr zygctl 8
communication.
Default:
.Pa /var/run/zyginit.sock
.It Ev ZYGINIT_LOG_DIR
Path to the per-service log directory.
Service stdout and stderr are captured here.
Default:
.Pa /var/run/zyginit/log
.El
.Sh FILES
.Bl -tag -width "/etc/zyginit/enabled.d/"
.It Pa /sbin/init
The init daemon binary
.Pq kernel exec target on Hammerhead .
.It Pa /etc/zyginit/
Directory containing service definition TOML files.
.It Pa /etc/zyginit/enabled.d/
Symlinks to enabled service definitions.
Only services with a symlink here are started at boot.
.It Pa /var/run/zyginit.sock
Unix domain socket for administrative communication.
Created after tmpfs is mounted.
.It Pa /var/run/zyginit/log/
Per-service output log directory.
Each service's stdout and stderr are captured to
.Pa <name>.log
in this directory.
Log files are truncated on each service start.
.El
.Sh LIVE REPLACE
.Nm
supports operator-driven, in-place replacement of the PID-1 process
via
.Xr execve 2
without disturbing running services.
The operator drops a new binary at
.Pa /sbin/init
and runs
.Xr zygctl 8
.Cm replace .
The running
.Nm
serializes its in-memory service-supervision state to
.Pa /var/run/zyginit/state.toml
\(em
service name, contract ID, restart count, uptime
\(em
unlinks the control socket, then
.Xr execve 2 Ns 's
.Pa /sbin/init .
PID-1 in-place
.Xr execve 2
preserves
.Va proc_t.p_ct_process ,
so the kernel-level contract ownership survives the swap; the new
.Nm
process re-reads
.Pa /var/run/zyginit/state.toml ,
re-establishes its userspace bookkeeping, and continues supervising.
.Pp
The boot-id sentinel
.Pq Pa /proc/1/stat
field 22 on Linux;
.Pa /proc/1/psinfo
.Va pr_start.tv_sec
on Hammerhead
is read at startup by the new
.Nm
to detect stale state files left over from before a real reboot.
PID 1's process start time survives
.Xr execve 2
.Pq same proc_t
but changes on real reboot
.Pq new PID 1 .
A mismatch causes the new
.Nm
to ignore (and delete) the file and proceed as a fresh boot.
.Pp
This mechanism is for live upgrades only; it does not cover crash
recovery, since
.Nm
crashing as PID 1 is already a system-level event.
See
.Xr zygctl 8
.Cm replace
for invocation details.
.Sh EXAMPLES
Start
.Nm
in non-init mode for testing
.Pq not as PID 1 :
.Bd -literal -offset indent
# ZYGINIT_CONFIG_DIR=/etc/zyginit zyginit
.Ed
.Sh SEE ALSO
.Xr zygctl 8 ,
.Xr zyginit 5 ,
.Xr contract 5
.Sh HISTORY
.Nm
first appeared in Zygaena/Hammerhead as a replacement for SMF
.Pq Service Management Facility .
.Sh AUTHORS
.An Chris Tusa Aq Mt chris.tusa@leafscale.com
# Operator gotcha: do not invoke `/sbin/init` (zyginit) from a shell

## TL;DR

**Never run `/sbin/init` (or anything that exec's the zyginit binary)
from a shell on a running zyginit system.** Running it even with a
no-op-looking flag like `--version` will silently break the admin
socket and lock you out of `zygctl`, `halt`, `reboot`, `poweroff`,
and `init <runlevel>`. Recovery is a hard power-cycle.

Disposition: **documentation-only**. The behaviour is a side-effect of
zyginit's stale-socket recovery (anti-pattern #5 in `docs/SMF_MIGRATION.md`),
which is correct for PID 1 but unsafe for non-PID-1 invocations. We
work around this by simply not running `/sbin/init` manually.

## What happens

When `zyginit` is invoked as a non-PID-1 process, it correctly detects
"non-init mode" and exits without taking over service supervision —
but on the way through it runs the early socket-setup path, which
unlinks `/var/run/zyginit.sock` and binds a new socket of its own.
When the process exits the new socket is closed; the filesystem path
is now a dead-end socket file with no listener.

PID 1's listening socket fd is still healthy, but its admin path is
no longer reachable by name. From that moment until reboot:

- `zygctl <anything-going-through-the-socket>` fails with
  `cannot connect to zyginit at /var/run/zyginit.sock`
- `/sbin/halt`, `/sbin/reboot`, `/sbin/poweroff`, `/sbin/init <runlevel>`
  all fail too — `sysv-wrapper` exec's `/sbin/zygctl <verb>`, which
  hits the same broken socket
- `init q` cannot signal PID 1 to re-bind, because the signalling
  path goes through the same socket

Service supervision (the actual PID 1 work) continues uninterrupted.
The kernel and the running daemons are unaffected. It is a soft
brick of the *admin plane* only.

## Reproducer

```bash
ssh root@hh-target
zygctl status                # works
/sbin/init --version         # appears to print a version banner
zygctl status                # fails
ls -la /var/run/zyginit.sock # mtime is "now", but path is dead
pgrep -fl zyginit            # only PID 1 — no rogue running
```

## Recovery

Hard power-cycle from the hypervisor or the physical box. On libvirt:

```sh
virsh destroy hh-target && virsh start hh-target
```

`virsh reboot` (ACPI shutdown) does not work — zyginit has no
ACPI button-press handler at present, so the kernel never sees the
shutdown request.

## Why this is filed as a note rather than a bug

The unlink-then-bind behaviour is correct for PID 1 (per
anti-pattern #5 in `docs/SMF_MIGRATION.md`). The non-PID-1 path
wandering through the same setup code is a code-organisation issue
that could be fixed in zyginit, but the workaround (don't exec
`/sbin/init` from a shell) is trivial — administrators should never
need to invoke the init binary directly anyway. The zyginit team
can address this whenever the early-startup code gets reworked;
until then this note exists so that anyone who hits the footgun
has a path to recovery.

## Cross-references

- `docs/SMF_MIGRATION.md` anti-pattern #5 — explains the unlink-then-bind
  pattern and why it exists for PID 1.
- `tools/sysv-wrapper/wrapper.c` — confirms `halt`, `reboot`, `poweroff`,
  `telinit`, `init <runlevel>` all funnel through `/sbin/zygctl`, so
  the socket clobber breaks the whole sysv-init compat layer
  simultaneously.

## History

First hit on hh-prototest 2026-05-05 during the Hammerhead-team
integration walk. Recovered via `virsh destroy && virsh start`.
Filed by Chris Tusa (christusa@gmail.com).
# PID-1 Boot Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Boot hh-prototest with zyginit as PID 1, replacing SMF's boot chain with 21 zyginit-managed services, with clean shutdown orchestration and safe BE-based rollback.

**Architecture:** Two code phases (zyginit/zygctl changes for shutdown orchestration + uadmin FFI; zygctl subcommand additions), one content phase (21 TOMLs + method scripts in `services/hammerhead/`), one deployment phase (BE-based install on hh-prototest), one validation phase (Phase A dry run + Phase B PID-1 boot + rollback drill).

**Tech Stack:** Reef 0.5.9, reefc, libcontract (Hammerhead), Mercurial, ZFS Boot Environments, libvirt/KVM, zsh method scripts, TOML service definitions.

**Spec:** `docs/superpowers/specs/2026-04-24-pid1-boot-design.md`

---

## File Structure

**Code to create:**
- `src/shutdown.reef` — new module: `uadmin`-based shutdown primitives, `AD_*` constants, PID-1 detection
- `services/hammerhead/` — staging tree for production Hammerhead service definitions (distinct from `services/examples/` which is Linux learning scaffolding)
- `services/hammerhead/<svc>.toml` — 21 TOML files
- `services/hammerhead/<svc>/start.sh` and `<svc>/stop.sh` — method scripts for non-trivial services
- `services/hammerhead/enabled.d/<svc>` → `../<svc>.toml` — 21 symlinks
- `scripts/install-to-be.sh` — dev-host utility: installs zyginit binaries + config tree into a mounted BE at a given path
- `tests/integration/test_shutdown.sh` — new integration test focused on shutdown orchestration

**Code to modify:**
- `src/main.reef` — PID-1 detection, shutdown-type tracking, call `sync + zyginit_shutdown()` at end of PID-1 shutdown
- `src/supervisor.reef` — extend shutdown path to walk tiers in reverse and invoke `stop_cmd` for oneshots that declared one
- `src/socket.reef` — parse halt/reboot/poweroff/single/multiuser commands, set shutdown flags
- `src/helpers.c` — add `zyginit_shutdown(int fcn)` wrapper around `uadmin(2)`
- `src/contract_linux_stubs.c` — add stub `zyginit_shutdown` returning -1
- `tools/zygctl/src/main.reef` — new subcommands: halt, reboot, poweroff, single (stub), multiuser (stub)
- `tests/integration/run_tests.sh` — source or call the new shutdown-orchestration tests
- `reef.toml` — build command comments updated if helpers.c surface grows (likely no change)

Each phase's tasks assume earlier phases are complete and committed.

---

## Phase 1 — Core zyginit code changes

### Task 1: Add `zyginit_shutdown()` C wrapper around uadmin(2)

**Files:**
- Modify: `src/helpers.c`
- Modify: `src/contract_linux_stubs.c`

- [ ] **Step 1: Add uadmin include and wrapper to `src/helpers.c`**

Append at the bottom of `src/helpers.c` (after the `zyginit_drop_privileges` function):

```c
/* Shutdown wrapper — uadmin(A_SHUTDOWN, fcn, 0). On Hammerhead this is the
 * primitive init uses to halt, reboot, or poweroff the system. fcn is one of:
 *   AD_HALT     (0) — stop scheduler, wait for operator
 *   AD_BOOT     (1) — reboot
 *   AD_POWEROFF (6) — ACPI/BMC chassis off
 * Returns 0 on success, -1 on error (errno set). On success, does not return
 * for AD_BOOT / AD_POWEROFF; for AD_HALT the kernel enters a halted state.
 */
#include <sys/uadmin.h>
int zyginit_shutdown(int fcn) {
    return uadmin(A_SHUTDOWN, fcn, 0);
}
```

- [ ] **Step 2: Add Linux stub to `src/contract_linux_stubs.c`**

Append at the bottom of `src/contract_linux_stubs.c`:

```c
/* Shutdown stub — on Linux we never actually uadmin; return -1 so the
 * calling code path is exercised without side effects. */
int zyginit_shutdown(int fcn) { return -1; }
```

- [ ] **Step 3: Rebuild on Linux to verify it compiles**

Run:
```bash
cd /home/ctusa/repos/zyginit
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
```

Expected: both compile with no errors. If clang errors on `<sys/uadmin.h>` on Linux, that's expected for the `helpers.c` side — the header isn't on Linux. In that case, guard with `#ifdef __sun`:

```c
#ifdef __sun
#include <sys/uadmin.h>
int zyginit_shutdown(int fcn) {
    return uadmin(A_SHUTDOWN, fcn, 0);
}
#else
int zyginit_shutdown(int fcn) { (void)fcn; return -1; }
#endif
```

If that's needed, remove the stub from `contract_linux_stubs.c` (it'd be a duplicate symbol).

- [ ] **Step 4: Verify on Hammerhead (ssh to hh-prototest)**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 \
  'grep -E "A_SHUTDOWN|AD_HALT|AD_BOOT|AD_POWEROFF" /usr/include/sys/uadmin.h'
```

Expected output should confirm the constant values:
```
#define A_SHUTDOWN      2
#define AD_HALT         0
#define AD_BOOT         1
#define AD_POWEROFF     6
```

(A_SHUTDOWN = 2 on illumos, not 1 as might be assumed from older references.
The code uses the symbolic constant so this value never appears in Reef/C
source; the header does the resolution at compile time.)

- [ ] **Step 5: Commit**

```bash
hg commit -m "shutdown FFI: add zyginit_shutdown() wrapping uadmin(A_SHUTDOWN, fcn, 0)

Adds the C wrapper used by zyginit to halt, reboot, or poweroff the system
once all services are stopped. Linux gets a stub returning -1.

No Reef-side caller yet — wiring comes in later tasks."
```

---

### Task 2: Create `src/shutdown.reef` with FFI extern and AD_* constants

**Files:**
- Create: `src/shutdown.reef`

- [ ] **Step 1: Write the new module**

Write to `src/shutdown.reef`:

```reef
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ `/ /_/ ___/ ___/ __ `/ / _ \
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zyginit
   Filename: shutdown.reef
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: PID-1 shutdown primitives — uadmin(2) FFI and shutdown-type
             constants.

******************************************************************************/

module shutdown

export
    // Shutdown function codes (sys/uadmin.h A_SHUTDOWN fcn values)
    fn AD_HALT(): int
    fn AD_BOOT(): int
    fn AD_POWEROFF(): int

    // Symbolic shutdown-type codes used internally by zyginit.
    // These are NOT the uadmin AD_* codes — they're zyginit's own
    // enum for distinguishing what a shutdown was triggered as,
    // before it's mapped to AD_* at the actual uadmin call site.
    fn SHUT_NONE(): int
    fn SHUT_HALT(): int
    fn SHUT_REBOOT(): int
    fn SHUT_POWEROFF(): int

    // Map our internal type to the uadmin fcn code.
    fn to_ad_code(shut_type: int): int

    // Call uadmin(A_SHUTDOWN, fcn, 0). Returns 0 on success, -1 on error.
    // Only succeeds when running as PID 1.
    fn do_shutdown(fcn: int): int
end export

extern "C" fn zyginit_shutdown(fcn: int): int

fn AD_HALT(): int     return 0 end AD_HALT
fn AD_BOOT(): int     return 1 end AD_BOOT
fn AD_POWEROFF(): int return 6 end AD_POWEROFF

fn SHUT_NONE(): int     return 0 end SHUT_NONE
fn SHUT_HALT(): int     return 1 end SHUT_HALT
fn SHUT_REBOOT(): int   return 2 end SHUT_REBOOT
fn SHUT_POWEROFF(): int return 3 end SHUT_POWEROFF

fn to_ad_code(shut_type: int): int
    if shut_type == SHUT_HALT()
        return AD_HALT()
    elif shut_type == SHUT_REBOOT()
        return AD_BOOT()
    elif shut_type == SHUT_POWEROFF()
        return AD_POWEROFF()
    end if
    // Default to halt for unknown / NONE
    return AD_HALT()
end to_ad_code

fn do_shutdown(fcn: int): int
    return zyginit_shutdown(fcn)
end do_shutdown

end module
```

- [ ] **Step 2: Build on Linux to verify module compiles**

```bash
cd /home/ctusa/repos/zyginit
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Expected: build completes. If build errors about shutdown.reef not being found, ensure it's under `src/` which is in `source_dirs` in `reef.toml`.

Note: main.reef / supervisor.reef / etc. don't import `shutdown` yet, so this only validates the module compiles standalone. (Dead-code elimination may not compile it at all — that's OK for this step; we'll exercise it in later tasks.)

- [ ] **Step 3: Commit**

```bash
hg commit -m "src/shutdown.reef: new module with uadmin FFI + shutdown-type enum

Adds AD_HALT/AD_BOOT/AD_POWEROFF constants matching sys/uadmin.h, a
separate SHUT_* internal enum for tracking what kind of shutdown was
requested, and a do_shutdown() entry point that calls through the
zyginit_shutdown() C wrapper. No callers yet."
```

---

### Task 3: Add PID-1 detection helper

**Files:**
- Modify: `src/main.reef`

- [ ] **Step 1: Add `is_pid_1()` helper near the top of main.reef**

Open `src/main.reef`. After the `MAX_SERVICES()` function (around line 50), add:

```reef
// Returns true when running as PID 1 (i.e., actual init). When not PID 1,
// the integration-test path: SIGTERM → stop services → normal exit
// (no uadmin call). When PID 1, shutdown must call uadmin or the kernel
// panics.
fn is_pid_1(): bool
    return process.getpid() == 1
end is_pid_1
```

- [ ] **Step 2: Add startup banner line so PID-1 mode is visible in logs**

Find the startup block in `main()` (search for `"zyginit v"`). Add a line right after the version banner:

```reef
    println("zyginit v" + VERSION() + " starting")

    if is_pid_1()
        println("zyginit: running as PID 1 (init mode)")
    else
        println("zyginit: running as PID " + int_to_str(process.getpid()) + " (non-init mode)")
    end if
```

Remove any duplicate "running as PID ..." prints if they exist.

- [ ] **Step 3: Rebuild and run integration tests (should still be 57/57)**

```bash
cd /home/ctusa/repos/zyginit
rm -f build/zyginit
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/run_tests.sh 2>&1 | tail -5
```

Expected: `Results: 57 passed, 0 failed (of 57)`. The test harness runs zyginit as a regular user process, so `is_pid_1()` returns false and behavior is unchanged.

- [ ] **Step 4: Commit**

```bash
hg commit -m "main.reef: add is_pid_1() helper and startup banner

Sets up the PID-1 detection used by later tasks to decide whether
shutdown ends with uadmin() or a normal process exit."
```

---

### Task 4: Extend supervisor shutdown to run oneshot stop commands in reverse tier order

**Files:**
- Modify: `src/supervisor.reef`
- Modify: `src/main.reef`

This is the biggest code change in Phase 1. Shutdown currently walks services in the order they were added to the table and only stops `STATE_RUNNING` services. We need tier-ordered reverse walk that also runs `exec.stop` commands for oneshots that declared one.

- [ ] **Step 1: Add a `stop_oneshot` supervisor function**

Open `src/supervisor.reef`. The existing `stop_service` function (around line 423) handles daemons with stop.method=contract. Add a new function below it that handles oneshot teardown:

```reef
// Run a oneshot's declared exec.stop command synchronously.
// Used during shutdown to reverse setup that the matching exec.start did.
// Does nothing if no stop command is declared.
// Returns true if stop was attempted (whether or not it succeeded).
fn stop_oneshot(table: ServiceTable, idx: int): bool
    let rt = supervisor.get_runtime(table, idx)
    let def = supervisor.rt_def(rt)
    let name = config.svc_name(def)
    let stop_cmd = config.svc_stop_cmd(def)

    if str.length(stop_cmd) == 0
        // Nothing to reverse — normal for oneshots with no teardown.
        return false
    end if

    println("supervisor: running stop for " + name + " (" + stop_cmd + ")")

    // Parse stop_cmd into program + args (same pattern as start).
    let parts = new [string](32)
    let argc = str.split(stop_cmd, ' ', parts, 32)
    if argc <= 0
        println("supervisor: " + name + ": empty stop command, skipping")
        return false
    end if

    let program = parts[0]
    let argv = new [string](argc)
    mut i = 0
    while i < argc
        argv[i] = parts[i]
        i = i + 1
    end while

    let pid = process.process_spawn(program, argv)
    if pid < 0
        println("supervisor: " + name + ": stop spawn failed")
        return true
    end if

    // Block until the stop command exits. Oneshot stops are expected to be
    // short (umount, swap -d, etc.) — they must complete before we proceed.
    let exit_code = process.process_wait(pid)
    if exit_code != 0
        println("supervisor: " + name + ": stop exited non-zero (" + int_to_str(exit_code) + ")")
    end if
    return true
end stop_oneshot
```

Export it in the module's `export` block (near the top of supervisor.reef, alongside `stop_service`):

```reef
    fn stop_oneshot(table: ServiceTable, idx: int): bool
```

- [ ] **Step 2: Replace `shutdown_services` in main.reef with a tier-reversed walk**

Open `src/main.reef`. Find `proc shutdown_services(table: supervisor.ServiceTable)` (around line 283). Replace with:

```reef
// Stop all services in reverse tier order.
// - Daemons in RUNNING: stop via contract SIGTERM (existing stop_service path).
// - Oneshots in STOPPED with a declared exec.stop: run the stop command.
// - Oneshots without stop: skip.
proc shutdown_services(table: supervisor.ServiceTable,
                       tiers: [string], tier_counts: [int], num_tiers: int)
    println("zyginit: stopping all services...")

    // Compute total offsets per tier so we can scan each tier's slice.
    let offsets = new [int](num_tiers)
    mut off = 0
    mut i = 0
    while i < num_tiers
        offsets[i] = off
        off = off + tier_counts[i]
        i = i + 1
    end while

    // Walk tiers in reverse.
    mut tier = num_tiers - 1
    while tier >= 0
        let tier_off = offsets[tier]
        let tier_sz = tier_counts[tier]
        println("zyginit: shutting down tier " + int_to_str(tier) +
                " (" + int_to_str(tier_sz) + " services)")

        mut j = 0
        while j < tier_sz
            let name = tiers[tier_off + j]
            let idx = supervisor.find_service(table, name)
            if idx >= 0
                let rt = supervisor.get_runtime(table, idx)
                let state = supervisor.rt_state(rt)
                if state == supervisor.STATE_RUNNING()
                    // Running daemon: issue contract stop.
                    supervisor.stop_service(table, idx)
                elif state == supervisor.STATE_STOPPED()
                    // Oneshot that already exited: run its stop if declared.
                    let _ = supervisor.stop_oneshot(table, idx)
                end if
            end if
            j = j + 1
        end while

        // Between tiers: wait for daemons in this tier to reach STOPPED
        // so we don't teardown upstream deps while downstream is still
        // alive. Simple: loop with a short sleep until all RUNNING in
        // this tier are gone, with a safety deadline.
        mut remaining = 1
        mut waits = 0
        while remaining > 0 and waits < 60
            remaining = 0
            mut k = 0
            while k < tier_sz
                let name2 = tiers[tier_off + k]
                let idx2 = supervisor.find_service(table, name2)
                if idx2 >= 0
                    let rt2 = supervisor.get_runtime(table, idx2)
                    if supervisor.rt_state(rt2) == supervisor.STATE_STOPPING()
                        remaining = remaining + 1
                    end if
                end if
                k = k + 1
            end while
            if remaining > 0
                clock.sleep_millis(500)
                // Also reap any child exits that happened during the wait.
                reap_children(table)
                waits = waits + 1
            end if
        end while

        if remaining > 0
            println("zyginit: tier " + int_to_str(tier) +
                    " shutdown timed out with " + int_to_str(remaining) +
                    " services still STOPPING; proceeding anyway")
        end if

        tier = tier - 1
    end while

    println("zyginit: all service tiers stopped")
end shutdown_services
```

Find the caller of `shutdown_services` in `main()` (search for `shutdown_services(table)`). Update the call site to pass the tier arrays (which are already computed at startup — pass the same ones that were used for `start_services_by_tier`):

```reef
    // ---- Shutdown ----
    println("")
    shutdown_services(table, tiers, tier_counts, num_tiers)
```

Make sure `tiers`, `tier_counts`, and `num_tiers` are still in scope at that point; if they were declared inside an inner block, promote them to the outer scope.

- [ ] **Step 3: Add `clock` import in main.reef if not already present**

Near the top imports of `main.reef`:

```reef
import time.clock as clock
```

(If already imported, skip.)

- [ ] **Step 4: Rebuild and run integration tests**

```bash
cd /home/ctusa/repos/zyginit
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/run_tests.sh 2>&1 | tail -5
```

Expected: `Results: 57 passed, 0 failed (of 57)`. Oneshot stops aren't exercised by existing tests (no example service declares `exec.stop`), so this step only validates nothing regressed.

- [ ] **Step 5: Commit**

```bash
hg commit -m "supervisor: shutdown in reverse tier order + oneshot stop commands

Shutdown now walks computed tiers from last to first:
  - RUNNING daemons get stopped via contract SIGTERM (unchanged)
  - STOPPED oneshots with exec.stop declared run their stop command
  - Waits up to 30s per tier for daemons to finish STOPPING before
    moving to the prior tier

This makes it safe to define stop.sh for services like filesystem
(umountall) and root-fs (remount ro) and have them run in the right
order during shutdown."
```

---

### Task 5: Add shutdown-type tracking + sync + uadmin call for PID 1

**Files:**
- Modify: `src/main.reef`

- [ ] **Step 1: Import shutdown module and add global shutdown-type variable**

Near the top imports of `main.reef`, add:

```reef
import shutdown
```

Below the existing mutable globals (e.g., `g_signal_pipe_read`), add:

```reef
// Requested shutdown type (set by signal handler or socket command).
// SHUT_NONE = no shutdown in progress.
mut g_shutdown_type: int = 0   // = shutdown.SHUT_NONE() — but can't call fn in init
```

Reef may not allow calling a function in a global initializer; using `0` which matches SHUT_NONE by definition.

- [ ] **Step 2: Modify `handle_signals` to set shutdown type**

Find `fn handle_signals` (around line 211). Update the SIGTERM/SIGINT branch:

```reef
fn handle_signals(table: supervisor.ServiceTable): bool
    // SIGTERM / SIGINT — initiate shutdown
    if signal.signal_received(signal.SIGTERM()) or signal.signal_received(signal.SIGINT())
        println("zyginit: received shutdown signal")
        // Default: halt (conservative). Socket commands can override.
        if g_shutdown_type == shutdown.SHUT_NONE()
            g_shutdown_type = shutdown.SHUT_HALT()
        end if
        return false
    end if

    // SIGHUP — reload config
    if signal.signal_received(signal.SIGHUP())
        println("zyginit: SIGHUP received, reloading configuration")
        reload_services(table)
    end if

    // SIGCHLD — reap exited children
    if signal.signal_received(signal.SIGCHLD())
        reap_children(table)
    end if

    return true
end handle_signals
```

- [ ] **Step 3: Call sync + uadmin at end of main() when PID 1**

At the very end of `main()`, after `shutdown_services` and any cleanup prints, add:

```reef
    println("zyginit: shutdown complete")

    // As PID 1, we MUST NOT return normally — kernel panics on "init died".
    // Call sync() then uadmin() based on the requested shutdown type.
    if is_pid_1()
        let shut_type = g_shutdown_type
        if shut_type == shutdown.SHUT_NONE()
            shut_type = shutdown.SHUT_HALT()   // defensive default
        end if

        println("zyginit: sync()")
        // No direct sync() FFI yet; the stop scripts handle umount + sync as
        // part of filesystem/stop.sh. Add explicit sync in a later iteration
        // if needed.

        let fcn = shutdown.to_ad_code(shut_type)
        println("zyginit: uadmin(A_SHUTDOWN, " + int_to_str(fcn) + ", 0)")
        let rc = shutdown.do_shutdown(fcn)
        // uadmin does not return on AD_BOOT/AD_POWEROFF; for AD_HALT the
        // kernel halts the CPU. If rc >= 0 we never reach here; if rc < 0
        // something went wrong — loop forever to avoid returning from PID 1.
        println("zyginit: uadmin returned " + int_to_str(rc) + " (errno check needed)")
        while true
            clock.sleep_seconds(3600)
        end while
    end if
    // Non-PID-1 path falls through and returns from main() normally.
```

- [ ] **Step 4: Add explicit sync() FFI**

Add to `src/helpers.c`:

```c
#include <unistd.h>
void zyginit_sync(void) {
    sync();
}
```

And add a Reef extern + wrapper in `src/shutdown.reef`, inside the export block:

```reef
    proc do_sync()
```

And the implementation (before `end module`):

```reef
extern "C" proc zyginit_sync()

proc do_sync()
    zyginit_sync()
end do_sync
```

Update the Linux stub in `src/contract_linux_stubs.c` — we CAN call sync on Linux (POSIX), but to keep stubs minimal and deterministic on the dev host, add:

```c
void zyginit_sync(void) { /* sync() is POSIX but we no-op on Linux dev to keep tests deterministic */ }
```

Actually — **keep it real**. Remove the Linux stub; let both Linux and Hammerhead call the real POSIX `sync()`. So instead:

- Leave `zyginit_sync` defined only in `src/helpers.c` (portable — POSIX)
- Do NOT add a stub version in `contract_linux_stubs.c`

Now update the `main()` shutdown block to call `shutdown.do_sync()` instead of the placeholder comment:

```reef
        println("zyginit: sync()")
        shutdown.do_sync()
```

- [ ] **Step 5: Build and test**

```bash
cd /home/ctusa/repos/zyginit
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/run_tests.sh 2>&1 | tail -5
```

Expected: `Results: 57 passed, 0 failed (of 57)`. Non-PID-1 code path is unchanged; tests don't trip the new uadmin branch.

- [ ] **Step 6: Commit**

```bash
hg commit -m "shutdown: PID-1 calls sync + uadmin; non-PID-1 exits normally

Adds g_shutdown_type tracking (set by signal handler, eventually also
by socket commands). At end of main():
  - PID 1: sync() then uadmin(A_SHUTDOWN, fcn, 0); fcn from shutdown type
  - non-PID-1: return from main() (existing behavior)

Also adds zyginit_sync() (POSIX sync(2)) in helpers.c, exposed via
shutdown module.

Defensive infinite loop after uadmin returns in error — prevents
kernel panic from PID 1 exit on unexpected uadmin failure."
```

---

### Task 6: Socket handler sets shutdown type for halt/reboot/poweroff

**Files:**
- Modify: `src/socket.reef`
- Modify: `src/main.reef`

zygctl will send commands like `halt\n` or `reboot\n`. The socket handler needs to map them to the appropriate `g_shutdown_type` and trigger the shutdown flow (same way SIGTERM does).

- [ ] **Step 1: Expose a setter for `g_shutdown_type` from main.reef**

In `src/main.reef`, below the variable definition, add:

```reef
// Setter for socket handler to request a specific shutdown type.
// Must be called before handle_signals sees a SIGTERM (or the socket
// handler itself triggers the shutdown via signal_pipe_notify).
proc request_shutdown(shut_type: int)
    g_shutdown_type = shut_type
    signal_pipe_notify()
end request_shutdown
```

Also export it at the top of the module so socket.reef can call it. In the `export` block of `main.reef` (if main.reef has one; if not, proc visibility may already be module-level — check existing `reload_services` export):

```reef
    proc request_shutdown(shut_type: int)
```

Alternatively, if cross-module proc calls are awkward, move the shutdown request flag into `socket.reef`'s existing reload-flag pattern. Prefer the cleaner direct call if it works.

- [ ] **Step 2: Add halt/reboot/poweroff/single/multiuser command handlers to socket.reef**

Open `src/socket.reef`. Find the command dispatch (search for `"status"` or `"start"` to locate the parser). Add new command cases:

```reef
    elif cmd == "halt"
        main.request_shutdown(shutdown.SHUT_HALT())
        return "halting\n"
    elif cmd == "reboot"
        main.request_shutdown(shutdown.SHUT_REBOOT())
        return "rebooting\n"
    elif cmd == "poweroff"
        main.request_shutdown(shutdown.SHUT_POWEROFF())
        return "powering off\n"
    elif cmd == "single"
        return "error: single-user mode not yet implemented\n"
    elif cmd == "multiuser"
        return "error: multi-user target not yet implemented\n"
```

Add imports at the top of socket.reef:

```reef
import main
import shutdown
```

If a circular import (main imports socket, socket imports main) causes build failure, move `request_shutdown` to `shutdown.reef` and have it directly touch a global, or use an indirection via a shared "shutdown_state" module. First check whether the circular import is a problem; Reef may handle it.

- [ ] **Step 3: Rebuild + test**

```bash
cd /home/ctusa/repos/zyginit
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/run_tests.sh 2>&1 | tail -5
```

Expected: 57/57 pass. New commands aren't yet exercised by existing tests.

- [ ] **Step 4: Commit**

```bash
hg commit -m "socket: accept halt/reboot/poweroff/single/multiuser commands

halt/reboot/poweroff set g_shutdown_type and kick the signal pipe to
wake the event loop, matching the SIGTERM path. single/multiuser
return a 'not implemented' error (stubs for future runlevel support)."
```

---

## Phase 2 — zygctl subcommands

### Task 7: Add halt/reboot/poweroff subcommands to zygctl

**Files:**
- Modify: `tools/zygctl/src/main.reef`

- [ ] **Step 1: Add subcommand dispatch**

Open `tools/zygctl/src/main.reef`. Find the subcommand dispatch (typically an if/elif chain matching `args.get(1)` against `"status"`, `"start"`, etc.). Add:

```reef
    elif cmd == "halt"
        send_command_and_print("halt")
    elif cmd == "reboot"
        send_command_and_print("reboot")
    elif cmd == "poweroff"
        send_command_and_print("poweroff")
    elif cmd == "single"
        println("zygctl: single-user mode not yet implemented")
        println("zygctl: reserved for future runlevel support")
        process.exit_now(1)
    elif cmd == "multiuser"
        println("zygctl: multi-user target not yet implemented")
        println("zygctl: reserved for future runlevel support")
        process.exit_now(1)
```

If a `send_command_and_print` helper doesn't exist, use the same socket-call + response-print pattern as existing commands (e.g., look at how `"reload"` is implemented and mirror it).

- [ ] **Step 2: Update help text**

Find the `help` command output (typically a `println` of each subcommand). Add the new ones in a sensible grouping:

```reef
    println("  halt              Cleanly stop all services and halt the system")
    println("  reboot            Cleanly stop all services and reboot")
    println("  poweroff          Cleanly stop all services and power off")
    println("  single            (not yet implemented) Enter single-user mode")
    println("  multiuser         (not yet implemented) Enter multi-user target")
```

- [ ] **Step 3: Build zygctl**

```bash
cd /home/ctusa/repos/zyginit/tools/zygctl
reefc build --obj build/symlink_wrapper.o
./build/zygctl help 2>&1 | grep -E "halt|reboot|poweroff|single|multiuser"
```

Expected: all five new commands visible in help output.

- [ ] **Step 4: Commit**

```bash
cd /home/ctusa/repos/zyginit
hg commit -m "zygctl: add halt/reboot/poweroff + single/multiuser stubs

halt/reboot/poweroff send the matching socket command to zyginit.
single/multiuser are explicit stubs printing 'not yet implemented';
they're in help so the command surface is stable for future expansion."
```

---

### Task 8: Integration test for clean-shutdown orchestration

**Files:**
- Create: `tests/integration/test_shutdown.sh`
- Modify: `tests/integration/run_tests.sh`

This is a new shell-based black-box integration test covering the new shutdown path. Runs zyginit in non-PID-1 mode, starts test services, issues `zygctl halt`, and verifies the expected shutdown log.

- [ ] **Step 1: Write the new test script**

Write to `tests/integration/test_shutdown.sh`:

```bash
#!/bin/sh
# tests/integration/test_shutdown.sh
# Verifies tier-reversed shutdown walk and oneshot stop command invocation.

set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
ZYGINIT="$PROJECT_DIR/build/zyginit"
ZYGCTL="$PROJECT_DIR/tools/zygctl/build/zygctl"

TEST_DIR=$(mktemp -d /tmp/zyginit-shutdown-test.XXXXXX)
trap "rm -rf $TEST_DIR; kill %1 2>/dev/null || true" EXIT

CONFIG_DIR="$TEST_DIR/config"
ENABLED_DIR="$CONFIG_DIR/enabled.d"
BIN_DIR="$TEST_DIR/bin"
LOG_DIR="$TEST_DIR/log"

mkdir -p "$CONFIG_DIR" "$ENABLED_DIR" "$BIN_DIR" "$LOG_DIR"

# Trivial oneshot: start prints "START alpha", stop prints "STOP alpha"
cat > "$BIN_DIR/alpha-start" <<EOF
#!/bin/sh
echo "START alpha" >> "$LOG_DIR/trace"
EOF
cat > "$BIN_DIR/alpha-stop" <<EOF
#!/bin/sh
echo "STOP alpha" >> "$LOG_DIR/trace"
EOF
chmod +x "$BIN_DIR/alpha-start" "$BIN_DIR/alpha-stop"

cat > "$CONFIG_DIR/alpha.toml" <<EOF
[service]
name = "alpha"
type = "oneshot"
[exec]
start = "$BIN_DIR/alpha-start"
stop = "$BIN_DIR/alpha-stop"
[restart]
on = "never"
EOF

ln -sf ../alpha.toml "$ENABLED_DIR/alpha"

# Start zyginit in background
ZYGINIT_CONFIG_DIR="$CONFIG_DIR" \
  ZYGINIT_SOCKET="$TEST_DIR/zyginit.sock" \
  ZYGINIT_LOG_DIR="$LOG_DIR/zyg" \
  "$ZYGINIT" > "$LOG_DIR/zyginit.out" 2>&1 &
ZPID=$!

# Wait for socket to appear
for i in 1 2 3 4 5; do
    [ -S "$TEST_DIR/zyginit.sock" ] && break
    sleep 1
done
[ -S "$TEST_DIR/zyginit.sock" ] || { echo "FAIL: socket never appeared"; exit 1; }

# Give alpha oneshot a moment to run
sleep 1

# Confirm START alpha ran
grep -q "START alpha" "$LOG_DIR/trace" || { echo "FAIL: alpha start didn't run"; exit 1; }

# Issue halt via zygctl
ZYGINIT_SOCKET="$TEST_DIR/zyginit.sock" "$ZYGCTL" halt

# Wait for zyginit to exit (non-PID-1 path returns from main)
for i in 1 2 3 4 5; do
    kill -0 $ZPID 2>/dev/null || break
    sleep 1
done

# Confirm STOP alpha ran during shutdown
grep -q "STOP alpha" "$LOG_DIR/trace" || {
    echo "FAIL: alpha stop didn't run during shutdown"
    echo "trace contents:"
    cat "$LOG_DIR/trace"
    exit 1
}

echo "PASS: oneshot stop command runs at shutdown"
```

- [ ] **Step 2: Wire it into `run_tests.sh`**

Open `tests/integration/run_tests.sh`. Near the end, before the final summary, add a line that sources / calls the new test. Mirror whatever pattern the existing suite uses (suite-based structure). Simplest: at the bottom, before the final `echo`:

```bash
# Shutdown orchestration tests
if bash "$SCRIPT_DIR/test_shutdown.sh" >> "$LOG_DIR/shutdown.log" 2>&1; then
    echo "  PASS: shutdown orchestration"
    PASS=$((PASS + 1))
    TOTAL=$((TOTAL + 1))
else
    echo "  FAIL: shutdown orchestration — see $LOG_DIR/shutdown.log"
    FAIL=$((FAIL + 1))
    TOTAL=$((TOTAL + 1))
fi
```

Adjust variable names to match the existing suite's counters.

- [ ] **Step 3: Make new test executable and run full suite**

```bash
chmod +x tests/integration/test_shutdown.sh
./tests/integration/run_tests.sh 2>&1 | tail -10
```

Expected: `Results: 58 passed, 0 failed (of 58)` — 57 old + 1 new shutdown test.

- [ ] **Step 4: Commit**

```bash
hg commit -m "tests: add integration test for oneshot stop at shutdown

Covers the new tier-reversed shutdown walk and exec.stop invocation
for oneshots. Uses a trivial alpha oneshot that appends 'START alpha'
/ 'STOP alpha' to a trace file. The test asserts 'STOP alpha' appears
after 'zygctl halt'."
```

---

## Phase 3 — TOML and method script authoring

All services go under `services/hammerhead/` in the repo. `scripts/install-to-be.sh` (Task 20) will copy them to `/etc/zyginit/` on the target.

### Task 9: Create `services/hammerhead/` dir and root-fs service

**Files:**
- Create: `services/hammerhead/root-fs.toml`
- Create: `services/hammerhead/root-fs/stop.sh`
- Create: `services/hammerhead/enabled.d/root-fs` (symlink)

- [ ] **Step 1: Create directory structure**

```bash
cd /home/ctusa/repos/zyginit
mkdir -p services/hammerhead/enabled.d
mkdir -p services/hammerhead/root-fs
```

- [ ] **Step 2: Write root-fs.toml**

Write to `services/hammerhead/root-fs.toml`:

```toml
# root-fs — Remount / read-write after kernel boot
#
# Tier 0: no dependencies. First oneshot to run.
# Reverses at shutdown: remount read-only before uadmin.

[service]
name = "root-fs"
description = "Remount root filesystem read-write"
type = "oneshot"

[exec]
start = "/usr/sbin/mount -o remount,rw /"
stop = "/etc/zyginit/root-fs/stop.sh"

[restart]
on = "never"
```

- [ ] **Step 3: Write root-fs/stop.sh**

Write to `services/hammerhead/root-fs/stop.sh`:

```zsh
#!/bin/zsh
# root-fs stop — remount / read-only before halt/poweroff/reboot
#
# Must run AFTER filesystem/stop.sh (which umounts non-root filesystems).
# Tier ordering guarantees this: root-fs is Tier 0, filesystem is Tier 2,
# so shutdown hits filesystem first, root-fs last.

set -e
set -u

/usr/sbin/mount -o remount,ro /

exit 0
```

- [ ] **Step 4: Make script executable, create enabled symlink**

```bash
chmod +x services/hammerhead/root-fs/stop.sh
ln -sf ../root-fs.toml services/hammerhead/enabled.d/root-fs
```

- [ ] **Step 5: Verify TOML parses via a dry-run zyginit invocation**

```bash
cd /home/ctusa/repos/zyginit
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 1
tools/zygctl/build/zygctl -s /tmp/zyg-dry.sock list 2>/dev/null || \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list
kill %1 2>/dev/null
grep -E "root-fs|error|warn" /tmp/zyg-dry.log
```

Expected: `root-fs (oneshot)` appears in `zygctl list`; no parse errors.

- [ ] **Step 6: Commit**

```bash
hg add services/hammerhead/root-fs.toml services/hammerhead/root-fs/stop.sh \
       services/hammerhead/enabled.d/root-fs
hg commit -m "services/hammerhead: add root-fs (Tier 0)

First of the 21 consolidated services. Oneshot that remounts / rw at
boot and remounts ro at shutdown (via stop.sh). No dependencies."
```

---

### Task 10: Tier 1 services — devfs, swap, crypto

**Files:**
- Create: `services/hammerhead/devfs.toml`
- Create: `services/hammerhead/swap.toml`
- Create: `services/hammerhead/swap/stop.sh`
- Create: `services/hammerhead/crypto.toml`
- Create: `services/hammerhead/crypto/start.sh`
- Create: 3 symlinks under `services/hammerhead/enabled.d/`

- [ ] **Step 1: devfs (inline, no script)**

Write `services/hammerhead/devfs.toml`:

```toml
# devfs — Populate /dev with devfsadm

[service]
name = "devfs"
description = "Dynamic /dev population"
type = "oneshot"

[exec]
start = "/usr/sbin/devfsadm"

[dependencies]
requires = ["root-fs"]

[restart]
on = "never"
```

- [ ] **Step 2: swap (inline start, stop.sh)**

Write `services/hammerhead/swap.toml`:

```toml
# swap — Enable swap devices from /etc/vfstab

[service]
name = "swap"
description = "Enable swap devices"
type = "oneshot"

[exec]
start = "/usr/sbin/swapadd -a"
stop = "/etc/zyginit/swap/stop.sh"

[dependencies]
requires = ["root-fs"]

[restart]
on = "never"
```

Write `services/hammerhead/swap/stop.sh`:

```zsh
#!/bin/zsh
# swap stop — disable all swap devices before halt/reboot

set -e
set -u

# swap -l lists active entries with the device path in column 1
# (skipping the header line). Disable each.
if /usr/sbin/swap -l >/dev/null 2>&1; then
    /usr/sbin/swap -l | awk 'NR>1 {print $1}' | while read dev; do
        /usr/sbin/swap -d "$dev" || true
    done
fi

exit 0
```

- [ ] **Step 3: crypto (start.sh)**

Write `services/hammerhead/crypto.toml`:

```toml
# crypto — Initialize Kernel Cryptographic Framework

[service]
name = "crypto"
description = "Kernel cryptographic framework"
type = "oneshot"

[exec]
start = "/etc/zyginit/crypto/start.sh"

[dependencies]
requires = ["root-fs"]

[restart]
on = "never"
```

Write `services/hammerhead/crypto/start.sh`:

```zsh
#!/bin/zsh
# crypto — configure the Kernel Cryptographic Framework
#
# The kernel crypto framework is loaded at boot via kcf module; this
# oneshot applies userland configuration (kcfd persistent state).
# cryptoadm refresh reloads the kernel policy from /etc/crypto/*.conf

set -e
set -u

/usr/sbin/cryptoadm refresh

exit 0
```

- [ ] **Step 4: Create enabled.d symlinks**

```bash
cd services/hammerhead
chmod +x swap/stop.sh crypto/start.sh
ln -sf ../devfs.toml enabled.d/devfs
ln -sf ../swap.toml enabled.d/swap
ln -sf ../crypto.toml enabled.d/crypto
```

- [ ] **Step 5: Dry-run verify**

```bash
cd /home/ctusa/repos/zyginit
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 1
ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list | head
kill %1 2>/dev/null
```

Expected: devfs, swap, crypto all appear in list; no parse errors.

- [ ] **Step 6: Commit**

```bash
hg add services/hammerhead/devfs.toml \
       services/hammerhead/swap.toml services/hammerhead/swap/stop.sh \
       services/hammerhead/crypto.toml services/hammerhead/crypto/start.sh \
       services/hammerhead/enabled.d/devfs \
       services/hammerhead/enabled.d/swap \
       services/hammerhead/enabled.d/crypto
hg commit -m "services/hammerhead: add Tier 1 (devfs, swap, crypto)"
```

---

### Task 11: Tier 2 services — filesystem, identity, sysconfig

**Files:**
- Create: `services/hammerhead/filesystem.toml`, `filesystem/start.sh`, `filesystem/stop.sh`
- Create: `services/hammerhead/identity.toml`, `identity/start.sh`
- Create: `services/hammerhead/sysconfig.toml`, `sysconfig/start.sh`
- Create: 3 symlinks

- [ ] **Step 1: filesystem**

Write `services/hammerhead/filesystem.toml`:

```toml
# filesystem — Mount all local filesystems from /etc/vfstab + ZFS

[service]
name = "filesystem"
description = "Local filesystem mounts and ZFS imports"
type = "oneshot"

[exec]
start = "/etc/zyginit/filesystem/start.sh"
stop = "/etc/zyginit/filesystem/stop.sh"

[dependencies]
requires = ["root-fs", "devfs"]

[restart]
on = "never"
```

Write `services/hammerhead/filesystem/start.sh`:

```zsh
#!/bin/zsh
# filesystem — mount local filesystems + import ZFS pools
#
# mountall -l mounts all local-type entries from /etc/vfstab (idempotent
# — skips already-mounted). zpool import -a imports any pools on attached
# disks. ZFS filesystems with mountpoint set auto-mount.

set -e
set -u

# Mount everything in /etc/vfstab with mount-at-boot = yes, excluding /
/usr/sbin/mountall -l

# Import all ZFS pools visible to the system
/usr/sbin/zpool import -a || true

# Auto-mount ZFS filesystems with canmount=on
/usr/sbin/zfs mount -a

exit 0
```

Write `services/hammerhead/filesystem/stop.sh`:

```zsh
#!/bin/zsh
# filesystem — umount everything except / before root-fs goes read-only
#
# umountall -l unmounts all local-type filesystems that are NOT /.
# ZFS pools export is handled implicitly by umount of their mountpoints.

set -e
set -u

# Best-effort: anything that can't umount (busy) is logged but doesn't
# block shutdown — ZFS in-kernel state will still checkpoint correctly.
/usr/sbin/umountall -l || true

# Explicitly sync ZFS before root goes ro
/usr/sbin/zpool sync || true

exit 0
```

- [ ] **Step 2: identity**

Write `services/hammerhead/identity.toml`:

```toml
# identity — Set hostname, domain, and hostid from /etc files

[service]
name = "identity"
description = "Hostname, domain, hostid"
type = "oneshot"

[exec]
start = "/etc/zyginit/identity/start.sh"

[dependencies]
requires = ["filesystem"]

[restart]
on = "never"
```

Write `services/hammerhead/identity/start.sh`:

```zsh
#!/bin/zsh
# identity — configure hostname, domain, hostid
#
# Reads /etc/nodename, /etc/defaultdomain, /etc/hostid. All optional —
# missing files fall back to system default. Does NOT generate missing
# hostid — that's a separate first-boot setup concern out of scope here.

set -e
set -u

if [[ -r /etc/nodename ]]; then
    /usr/bin/hostname "$(cat /etc/nodename)"
fi

if [[ -r /etc/defaultdomain ]]; then
    /usr/bin/domainname "$(cat /etc/defaultdomain)"
fi

# hostid is already loaded by the kernel from /etc/hostid; nothing to do
# unless we later want to generate it on first boot. Flag for follow-up.

exit 0
```

- [ ] **Step 3: sysconfig**

Write `services/hammerhead/sysconfig.toml`:

```toml
# sysconfig — Misc one-time boot configuration (grab-bag)

[service]
name = "sysconfig"
description = "Misc boot config: core, dump, keymap, scheduler, rctl, tmp cleanup"
type = "oneshot"

[exec]
start = "/etc/zyginit/sysconfig/start.sh"

[dependencies]
requires = ["filesystem"]

[restart]
on = "never"
```

Write `services/hammerhead/sysconfig/start.sh`:

```zsh
#!/bin/zsh
# sysconfig — misc one-time boot configuration
#
# Each command is deliberately wrapped in || true for commands where a
# specific failure (no device present, no config file, etc.) is acceptable.
# A truly mandatory setting would be its own service.

set -u
# Note: NOT using set -e here — individual failures are handled per-command.

# Core files: enable per-process pattern, apply config from /etc/coreadm.conf
/usr/bin/coreadm --init 2>/dev/null || true

# Crash dump: use configured dump device (set once per system, may be a zvol)
/usr/sbin/dumpadm -u 2>/dev/null || true

# Keyboard map from /etc/default/kbd (console only; tty layout)
if [[ -x /usr/bin/kbd ]]; then
    /usr/bin/kbd -s 2>/dev/null || true
fi

# Scheduler default dispatch table (TS = time-share, usual default)
/usr/sbin/dispadmin -d TS 2>/dev/null || true

# Resource controls (/etc/project-based rctls) — reload into kernel
if [[ -x /usr/sbin/rctladm ]]; then
    /usr/sbin/rctladm -u 2>/dev/null || true
fi

# Clean up /tmp on boot (tmpfs is usually empty after reboot but defend)
if [[ -d /tmp ]]; then
    /usr/bin/find /tmp -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
fi

exit 0
```

- [ ] **Step 4: Create symlinks, make scripts executable**

```bash
cd services/hammerhead
chmod +x filesystem/start.sh filesystem/stop.sh identity/start.sh sysconfig/start.sh
ln -sf ../filesystem.toml enabled.d/filesystem
ln -sf ../identity.toml enabled.d/identity
ln -sf ../sysconfig.toml enabled.d/sysconfig
```

- [ ] **Step 5: Dry-run verify all 7 services parse and tier correctly**

```bash
cd /home/ctusa/repos/zyginit
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 1
ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list
kill %1 2>/dev/null
grep -E "tier|error|warn" /tmp/zyg-dry.log
```

Expected: 7 services listed (root-fs, devfs, swap, crypto, filesystem, identity, sysconfig); tier output shows filesystem/identity/sysconfig in tier 2; no parse errors.

- [ ] **Step 6: Commit**

```bash
hg add services/hammerhead/filesystem.toml \
       services/hammerhead/filesystem/start.sh \
       services/hammerhead/filesystem/stop.sh \
       services/hammerhead/identity.toml \
       services/hammerhead/identity/start.sh \
       services/hammerhead/sysconfig.toml \
       services/hammerhead/sysconfig/start.sh \
       services/hammerhead/enabled.d/filesystem \
       services/hammerhead/enabled.d/identity \
       services/hammerhead/enabled.d/sysconfig
hg commit -m "services/hammerhead: add Tier 2 (filesystem, identity, sysconfig)"
```

---

### Task 12: Tier 3 — dlmgmtd, ipmgmtd, network

**Files:**
- Create: `services/hammerhead/dlmgmtd.toml`
- Create: `services/hammerhead/ipmgmtd.toml`
- Create: `services/hammerhead/network.toml`, `network/start.sh`
- Create: 3 symlinks

- [ ] **Step 1: dlmgmtd + ipmgmtd daemons (inline, no script)**

Write `services/hammerhead/dlmgmtd.toml`:

```toml
# dlmgmtd — Datalink management daemon

[service]
name = "dlmgmtd"
description = "Datalink management daemon"
type = "daemon"

[exec]
start = "/sbin/dlmgmtd"

[dependencies]
requires = ["filesystem"]

[restart]
on = "failure"
delay = 5
max_retries = 3

[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

Write `services/hammerhead/ipmgmtd.toml`:

```toml
# ipmgmtd — IP interface management daemon

[service]
name = "ipmgmtd"
description = "IP interface management daemon"
type = "daemon"

[exec]
start = "/lib/inet/ipmgmtd"

[dependencies]
requires = ["filesystem", "dlmgmtd"]

[restart]
on = "failure"
delay = 5
max_retries = 3

[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

- [ ] **Step 2: network (script — brings up lo0, physical, DHCP)**

Write `services/hammerhead/network.toml`:

```toml
# network — Bring up loopback, physical interfaces, routes
#
# Consolidates SMF's network/loopback, network/physical, network/initial,
# network/netmask, network/service, network/routing-setup. Runs DHCP
# request for interfaces configured for DHCP; ipadm create-addr -T dhcp
# implicitly spawns /sbin/dhcpagent (we don't manage it as a service).

[service]
name = "network"
description = "Bring up network interfaces and routes"
type = "oneshot"

[exec]
start = "/etc/zyginit/network/start.sh"

[dependencies]
requires = ["identity", "dlmgmtd", "ipmgmtd"]

[restart]
on = "never"
```

Write `services/hammerhead/network/start.sh`:

```zsh
#!/bin/zsh
# network — configure loopback, physical interfaces, routes
#
# Idempotent: check-before-create pattern for interfaces since
# ipadm create-if fails if the interface already exists.

set -e
set -u

# --- Loopback ---
# lo0 is auto-plumbed by the kernel on boot but ipadm wants explicit
# IP objects. Check first because create-if errors if already present.
if ! /usr/sbin/ipadm show-if lo0 >/dev/null 2>&1; then
    /usr/sbin/ipadm create-if lo0
fi
if ! /usr/sbin/ipadm show-addr lo0/v4 >/dev/null 2>&1; then
    /usr/sbin/ipadm create-addr -T static -a 127.0.0.1/8 lo0/v4
fi
if ! /usr/sbin/ipadm show-addr lo0/v6 >/dev/null 2>&1; then
    /usr/sbin/ipadm create-addr -T static -a ::1/128 lo0/v6
fi

# --- Physical interfaces ---
# For each datalink that's UP (not loopback), create an ipadm interface
# and request a DHCP lease. On hh-prototest this is typically 'vioif0'.
# Real production systems would look up /etc/hostname.<if> or similar,
# but for first-boot-test we assume one physical NIC and DHCP.
for link in $(/usr/sbin/dladm show-link -p -o link 2>/dev/null); do
    # Skip loopback and any link that's not 'up' (as reported by dladm)
    if [[ "$link" == "lo0" ]]; then
        continue
    fi
    if ! /usr/sbin/ipadm show-if "$link" >/dev/null 2>&1; then
        /usr/sbin/ipadm create-if "$link"
    fi
    if ! /usr/sbin/ipadm show-addr "$link/v4" >/dev/null 2>&1; then
        # -T dhcp implicitly spawns /sbin/dhcpagent if not already running
        /usr/sbin/ipadm create-addr -T dhcp "$link/v4" || true
    fi
done

# --- Routes ---
# Default route from DHCP is installed automatically by dhcpagent on
# lease acquisition. Static routes from /etc/inet/static_routes if present.
if [[ -r /etc/inet/static_routes ]]; then
    while read line; do
        case "$line" in
            \#*|'') continue;;
            *) /usr/sbin/route -f add $line || true;;
        esac
    done < /etc/inet/static_routes
fi

exit 0
```

- [ ] **Step 3: Symlinks + executable**

```bash
cd services/hammerhead
chmod +x network/start.sh
ln -sf ../dlmgmtd.toml enabled.d/dlmgmtd
ln -sf ../ipmgmtd.toml enabled.d/ipmgmtd
ln -sf ../network.toml enabled.d/network
```

- [ ] **Step 4: Dry-run verify**

```bash
cd /home/ctusa/repos/zyginit
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 1
ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list
kill %1 2>/dev/null
```

Expected: 10 services now listed (root-fs, devfs, swap, crypto, filesystem, identity, sysconfig, dlmgmtd, ipmgmtd, network); tiers 0-3 populated.

- [ ] **Step 5: Commit**

```bash
hg add services/hammerhead/dlmgmtd.toml \
       services/hammerhead/ipmgmtd.toml \
       services/hammerhead/network.toml \
       services/hammerhead/network/start.sh \
       services/hammerhead/enabled.d/dlmgmtd \
       services/hammerhead/enabled.d/ipmgmtd \
       services/hammerhead/enabled.d/network
hg commit -m "services/hammerhead: add Tier 3 (dlmgmtd, ipmgmtd, network)"
```

---

### Task 13: Tier 4 daemons (7 files)

**Files:**
- Create: 7 TOML files for `syseventd`, `fmd`, `syslogd`, `utmpd`, `pfexecd`, `powerd`, `rpcbind`
- Create: 7 symlinks

All follow the same daemon template. Writing them in one shot.

- [ ] **Step 1: Write all 7 TOMLs**

For each service, write the file below. Paths come from the `ps -ef` capture we have from hh-prototest.

`services/hammerhead/syseventd.toml`:
```toml
[service]
name = "syseventd"
description = "Sysevent framework daemon"
type = "daemon"
[exec]
start = "/usr/lib/sysevent/syseventd"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/fmd.toml`:
```toml
[service]
name = "fmd"
description = "Fault Manager Daemon"
type = "daemon"
[exec]
start = "/usr/lib/fm/fmd/fmd"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/syslogd.toml`:
```toml
[service]
name = "syslogd"
description = "System log daemon"
type = "daemon"
[exec]
start = "/usr/sbin/syslogd"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/utmpd.toml`:
```toml
[service]
name = "utmpd"
description = "utmpx monitor daemon"
type = "daemon"
[exec]
start = "/usr/lib/utmpd"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/pfexecd.toml`:
```toml
[service]
name = "pfexecd"
description = "Profile exec daemon (RBAC privilege execution)"
type = "daemon"
[exec]
start = "/usr/lib/pfexecd"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/powerd.toml`:
```toml
[service]
name = "powerd"
description = "Power management daemon"
type = "daemon"
[exec]
start = "/usr/lib/power/powerd"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/rpcbind.toml`:
```toml
[service]
name = "rpcbind"
description = "RPC portmapper"
type = "daemon"
[exec]
start = "/usr/sbin/rpcbind"
[dependencies]
requires = ["network"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

- [ ] **Step 2: Create symlinks**

```bash
cd services/hammerhead
for s in syseventd fmd syslogd utmpd pfexecd powerd rpcbind; do
    ln -sf ../$s.toml enabled.d/$s
done
```

- [ ] **Step 3: Dry-run verify**

```bash
cd /home/ctusa/repos/zyginit
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 1
ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list | wc -l
kill %1 2>/dev/null
```

Expected: 17 services listed (10 prior + 7 new).

- [ ] **Step 4: Commit**

```bash
hg add services/hammerhead/{syseventd,fmd,syslogd,utmpd,pfexecd,powerd,rpcbind}.toml \
       services/hammerhead/enabled.d/{syseventd,fmd,syslogd,utmpd,pfexecd,powerd,rpcbind}
hg commit -m "services/hammerhead: add Tier 4 daemons (syseventd, fmd, syslogd, utmpd, pfexecd, powerd, rpcbind)"
```

---

### Task 14: Tier 5 daemons — cron, inetd, sshd, console-login

**Files:**
- Create: 4 TOML files
- Create: 4 symlinks

- [ ] **Step 1: Write the 4 TOMLs**

`services/hammerhead/cron.toml`:
```toml
[service]
name = "cron"
description = "cron daemon"
type = "daemon"
[exec]
start = "/usr/sbin/cron"
[dependencies]
requires = ["syslogd"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/inetd.toml`:
```toml
[service]
name = "inetd"
description = "Internet services daemon"
type = "daemon"
[exec]
start = "/usr/lib/inet/inetd start"
[dependencies]
requires = ["rpcbind", "syslogd"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/sshd.toml`:
```toml
[service]
name = "sshd"
description = "Secure Shell daemon"
type = "daemon"
[exec]
start = "/usr/lib/ssh/sshd -D"
[dependencies]
requires = ["syslogd", "pfexecd"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

`services/hammerhead/console-login.toml`:
```toml
[service]
name = "console-login"
description = "Console login (ttymon on /dev/console)"
type = "daemon"
[exec]
start = "/usr/lib/saf/ttymon -g -d /dev/console -l console -m ldterm,ttcompat -h -p 'hammerhead console login: '"
[dependencies]
requires = ["syslogd", "utmpd"]
[restart]
on = "failure"
delay = 5
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
```

- [ ] **Step 2: Symlinks**

```bash
cd services/hammerhead
for s in cron inetd sshd console-login; do
    ln -sf ../$s.toml enabled.d/$s
done
```

- [ ] **Step 3: Full dry-run verify — all 21 services**

```bash
cd /home/ctusa/repos/zyginit
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 2
ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list | wc -l
grep -E "tier|error|warn|cycle" /tmp/zyg-dry.log
kill %1 2>/dev/null
```

Expected:
- `wc -l` output = 21
- Log shows 6 tiers (0-5), no cycle detection errors, no warnings
- No missing-dependency warnings (every `requires` resolves)

- [ ] **Step 4: Commit**

```bash
hg add services/hammerhead/{cron,inetd,sshd,console-login}.toml \
       services/hammerhead/enabled.d/{cron,inetd,sshd,console-login}
hg commit -m "services/hammerhead: add Tier 5 (cron, inetd, sshd, console-login)

All 21 zyginit services now authored. Dry-run parse confirms the full
dependency graph resolves into 6 tiers with no cycles."
```

---

## Phase 4 — Deployment tooling

### Task 15: Write install-to-be.sh

**Files:**
- Create: `scripts/install-to-be.sh`

- [ ] **Step 1: Write the installer script**

Write to `scripts/install-to-be.sh`:

```bash
#!/bin/sh
# install-to-be.sh — Install zyginit binaries + config tree into a
# mounted Boot Environment (or any target root).
#
# Usage: install-to-be.sh <target-root>
#
#   e.g., after `beadm create zyginit && beadm mount zyginit /mnt`:
#       install-to-be.sh /mnt
#
# Copies:
#   /sbin/zyginit (built binary)  → <target>/sbin/zyginit
#   /sbin/zygctl  (built binary)  → <target>/sbin/zygctl
#   services/hammerhead/*.toml    → <target>/etc/zyginit/*.toml
#   services/hammerhead/<svc>/    → <target>/etc/zyginit/<svc>/
#   services/hammerhead/enabled.d → <target>/etc/zyginit/enabled.d/
#
# Preserves existing <target>/sbin/init as <target>/sbin/init.smf and
# replaces it with a symlink to /sbin/zyginit.

set -e
set -u

if [ $# -ne 1 ]; then
    echo "usage: $0 <target-root>" >&2
    exit 1
fi

TARGET="$1"
REPO="$(cd "$(dirname "$0")/.." && pwd)"

if [ ! -d "$TARGET" ]; then
    echo "error: $TARGET does not exist or is not a directory" >&2
    exit 1
fi

if [ ! -x "$REPO/build/zyginit" ]; then
    echo "error: $REPO/build/zyginit not built yet" >&2
    exit 1
fi

if [ ! -x "$REPO/tools/zygctl/build/zygctl" ]; then
    echo "error: $REPO/tools/zygctl/build/zygctl not built yet" >&2
    exit 1
fi

echo "installing zyginit into $TARGET..."

# Binaries
install -m 0755 "$REPO/build/zyginit" "$TARGET/sbin/zyginit"
install -m 0755 "$REPO/tools/zygctl/build/zygctl" "$TARGET/sbin/zygctl"

# Config tree
mkdir -p "$TARGET/etc/zyginit"
mkdir -p "$TARGET/etc/zyginit/enabled.d"

# Copy TOMLs (flat files at top of services/hammerhead/)
for t in "$REPO"/services/hammerhead/*.toml; do
    cp "$t" "$TARGET/etc/zyginit/"
done

# Copy per-service script subdirs (root-fs/, swap/, crypto/, filesystem/,
# identity/, sysconfig/, network/) — anything that exists gets copied
for d in "$REPO"/services/hammerhead/*/; do
    [ "$(basename "$d")" = "enabled.d" ] && continue
    dname="$(basename "$d")"
    mkdir -p "$TARGET/etc/zyginit/$dname"
    cp -r "$d"* "$TARGET/etc/zyginit/$dname/" 2>/dev/null || true
    chmod -R +x "$TARGET/etc/zyginit/$dname"
done

# Symlinks in enabled.d (recreate since cp doesn't preserve across fs)
for l in "$REPO"/services/hammerhead/enabled.d/*; do
    name="$(basename "$l")"
    ln -sf "../$name.toml" "$TARGET/etc/zyginit/enabled.d/$name"
done

# Runtime dirs
mkdir -p "$TARGET/var/run/zyginit/log"

# Replace /sbin/init
if [ -e "$TARGET/sbin/init" ] && [ ! -L "$TARGET/sbin/init" ]; then
    # Preserve original (won't overwrite if already preserved)
    if [ ! -e "$TARGET/sbin/init.smf" ]; then
        mv "$TARGET/sbin/init" "$TARGET/sbin/init.smf"
        echo "  preserved original /sbin/init as /sbin/init.smf"
    fi
fi
ln -sf /sbin/zyginit "$TARGET/sbin/init"
echo "  installed /sbin/init → /sbin/zyginit"

echo "zyginit install complete in $TARGET"
echo ""
echo "verify:"
echo "  ls -la $TARGET/sbin/init"
echo "  ls $TARGET/etc/zyginit/enabled.d/"
```

- [ ] **Step 2: Make executable and add to repo**

```bash
cd /home/ctusa/repos/zyginit
chmod +x scripts/install-to-be.sh
hg add scripts/install-to-be.sh
```

- [ ] **Step 3: Commit**

```bash
hg commit -m "scripts/install-to-be.sh: deploy zyginit + hammerhead service set to a target root

Takes a target directory (typically a mounted BE) and installs:
  - /sbin/zyginit, /sbin/zygctl binaries
  - /etc/zyginit/ config tree (TOMLs + per-service script dirs + enabled.d)
  - /var/run/zyginit/log/ runtime dir
  - /sbin/init symlinked to /sbin/zyginit (old init preserved as init.smf)

Used by Phase B to populate a fresh Boot Environment."
```

---

## Phase 5 — Phase A non-PID-1 dry run on hh-prototest

### Task 16: Ship code + configs to hh-prototest

**Files:**
- N/A (operational only)

- [ ] **Step 1: Rebuild zyginit on Hammerhead**

```bash
cd /home/ctusa/repos/zyginit
tar --exclude='*/build/*' --exclude='.hg' -czf - \
    src services/hammerhead scripts reef.toml tools 2>/dev/null | \
  ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 \
    "cd /root/zyginit && tar -xzf -"

ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 \
  'cd /root/zyginit && gcc -c src/helpers.c -o build/helpers.o && reefc build -l contract --obj build/helpers.o 2>&1 | tail -3'
```

Expected: Build clean on Hammerhead.

- [ ] **Step 2: Rebuild zygctl on Hammerhead**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 \
  'cd /root/zyginit/tools/zygctl && reefc build 2>&1 | tail -3'
```

Expected: Build clean (zygctl doesn't need -l contract).

- [ ] **Step 3: Stage configs to /tmp/zyginit-dry on VM**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
set -e
rm -rf /tmp/zyginit-dry
cp -r /root/zyginit/services/hammerhead /tmp/zyginit-dry
ls /tmp/zyginit-dry/enabled.d/ | wc -l
EOF
```

Expected: 21 symlinks listed.

- [ ] **Step 4: Commit (nothing to commit; operational step)**

No commit. Continue.

---

### Task 17: Dry-run parse + dependency graph verification

**Files:**
- N/A (operational + diagnostic)

- [ ] **Step 1: Start zyginit in non-PID-1 mode on hh-prototest with the real TOML set**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
mkdir -p /tmp/zyg-run
ZYGINIT_CONFIG_DIR=/tmp/zyginit-dry \
  ZYGINIT_SOCKET=/tmp/zyg-run/zyginit.sock \
  ZYGINIT_LOG_DIR=/tmp/zyg-run/log \
  /root/zyginit/build/zyginit > /tmp/zyg-run/zyginit.out 2>&1 &
echo "started PID=$!"
sleep 3
ZYGINIT_SOCKET=/tmp/zyg-run/zyginit.sock /root/zyginit/tools/zygctl/build/zygctl list
echo "--- boot order tiers from zyginit log ---"
grep -E "tier [0-9]+" /tmp/zyg-run/zyginit.out
echo "--- errors / warnings ---"
grep -iE "error|warn|fail|cycle" /tmp/zyg-run/zyginit.out || echo "(none)"
EOF
```

Expected:
- `zygctl list` shows all 21 services
- 6 tiers (0-5) enumerated
- No errors / warnings

**STOP IF:** parse errors, cycle detection, missing dependency messages appear. Debug the TOMLs before proceeding.

- [ ] **Step 2: Start a test daemon to verify supervision on Hammerhead**

The real services would conflict with SMF's running copies. Use a scratch test service:

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
mkdir -p /tmp/zyg-test/enabled.d
cat > /tmp/zyg-test/watchdog.toml <<TOML
[service]
name = "watchdog"
type = "daemon"
[exec]
start = "/bin/sleep 300"
[restart]
on = "failure"
delay = 2
max_retries = 3
[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]
TOML
ln -sf ../watchdog.toml /tmp/zyg-test/enabled.d/watchdog

# Stop any previous dry-run zyginit
pkill -f '/root/zyginit/build/zyginit' 2>/dev/null
sleep 1
rm -rf /tmp/zyg-run
mkdir -p /tmp/zyg-run

ZYGINIT_CONFIG_DIR=/tmp/zyg-test \
  ZYGINIT_SOCKET=/tmp/zyg-run/zyginit.sock \
  ZYGINIT_LOG_DIR=/tmp/zyg-run/log \
  /root/zyginit/build/zyginit > /tmp/zyg-run/zyginit.out 2>&1 &
sleep 3

echo "--- initial status ---"
ZYGINIT_SOCKET=/tmp/zyg-run/zyginit.sock /root/zyginit/tools/zygctl/build/zygctl status

# Kill the sleep — should trigger restart
WPID=$(pgrep -f '/bin/sleep 300' | head -1)
echo "killing watchdog PID $WPID"
kill $WPID
sleep 3

echo "--- after kill (should show restart count 1) ---"
ZYGINIT_SOCKET=/tmp/zyg-run/zyginit.sock /root/zyginit/tools/zygctl/build/zygctl status

# Clean halt
ZYGINIT_SOCKET=/tmp/zyg-run/zyginit.sock /root/zyginit/tools/zygctl/build/zygctl halt
sleep 2

echo "--- zyginit output ---"
cat /tmp/zyg-run/zyginit.out
EOF
```

Expected:
- First status: watchdog RUNNING
- After kill: restart count = 1, watchdog back to RUNNING (or WAITING briefly)
- Halt cleanly exits zyginit, output shows "stopping all services" → "shutdown complete"
- NO uadmin call (non-PID-1 path)

- [ ] **Step 3: Commit (nothing to commit; operational)**

No commit. Document results in the team report.

---

## Phase 6 — Phase B PID-1 boot in a fresh BE

### Task 18: Create BE and install zyginit

**Files:**
- N/A (operational)

- [ ] **Step 1: Verify all pre-reqs installed on VM**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
echo "--- zyginit binary ---"
ls -la /root/zyginit/build/zyginit
echo "--- zygctl binary ---"
ls -la /root/zyginit/tools/zygctl/build/zygctl
echo "--- service set ---"
ls /root/zyginit/services/hammerhead/*.toml | wc -l
echo "--- install script ---"
ls -la /root/zyginit/scripts/install-to-be.sh
EOF
```

Expected: 21 TOMLs, both binaries, install script present.

- [ ] **Step 2: Create and mount the new BE**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
set -e
beadm create zyginit
beadm mount zyginit /mnt
beadm list
EOF
```

Expected: BE `zyginit` created, mounted at /mnt. `beadm list` shows it mounted but not active.

- [ ] **Step 3: Run the installer into /mnt**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 \
  'cd /root/zyginit && ./scripts/install-to-be.sh /mnt'
```

Expected output:
```
installing zyginit into /mnt...
  preserved original /sbin/init as /sbin/init.smf
  installed /sbin/init → /sbin/zyginit
zyginit install complete in /mnt
```

- [ ] **Step 4: Sanity-check the install**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
ls -la /mnt/sbin/init /mnt/sbin/init.smf /mnt/sbin/zyginit /mnt/sbin/zygctl
ls /mnt/etc/zyginit/enabled.d/ | wc -l
ls /mnt/etc/zyginit/*.toml | wc -l
EOF
```

Expected:
- `/mnt/sbin/init` is a symlink to `/sbin/zyginit`
- `/mnt/sbin/init.smf` is the original init binary
- 21 enabled.d symlinks
- 21 TOML files

- [ ] **Step 5: Umount and activate the BE**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
beadm umount zyginit
beadm activate zyginit
beadm list
EOF
```

Expected: `zyginit` BE shows as `R` (activated for reboot). `hammerhead` BE shows as `N` (currently running, not active for reboot).

---

### Task 19: Boot into zyginit BE and run success checklist

**Files:**
- N/A (operational + validation)

- [ ] **Step 1: Open a console session on the dev host (keep ssh open too)**

From a second terminal on the dev host:
```bash
virsh --connect=qemu:///system console hh-prototest
```

Leave this open; it's our diagnostic channel if zyginit wedges.

- [ ] **Step 2: Reboot into the zyginit BE**

From the existing ssh session:
```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 'init 6'
```

Watch the virsh console for boot output. Expected sequence (from zyginit):
- `zyginit v0.1.0 starting`
- `zyginit: running as PID 1 (init mode)`
- Tier-by-tier service startup
- `zyginit: entering event loop`

**If boot wedges:** reboot the VM, pick `hammerhead` from GRUB menu on reboot. Debug from there.

- [ ] **Step 3: SSH in and run success checklist (§9.A-D of spec)**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
echo "--- A. boot complete ---"
uptime
ps -ef | head -1
ps -ef | grep zyginit | grep -v grep

echo "--- B. service states ---"
/sbin/zygctl list
echo "---"
/sbin/zygctl status

echo "--- C. functional tests ---"
dladm show-link
ipadm show-addr
ping -c 2 192.168.122.1 || echo "ping failed"
zfs list
logger -p user.info "zyginit-first-boot marker"
tail -5 /var/adm/messages || echo "messages unavailable"

echo "--- D. zygctl end-to-end ---"
/sbin/zygctl status cron
/sbin/zygctl stop cron
/sbin/zygctl status cron
/sbin/zygctl start cron
/sbin/zygctl status cron
/sbin/zygctl log sshd | head -5
EOF
```

Check each line against the spec's §9 checklist. Record results.

- [ ] **Step 4: Document pass/fail**

Write results to `docs/superpowers/specs/2026-04-24-pid1-boot-results.md` (new file):

```markdown
# PID-1 Boot — Phase B Test Results

**Date:** <actual date>
**BE:** `zyginit`
**Host:** hh-prototest (192.168.122.197)

## Success Criteria (from spec §9)

### A. Boot completes
- [x/ ] No kernel panic
- [x/ ] zyginit event loop entered
- [x/ ] All tiers completed within 60s
- [x/ ] Console login prompt appears

### B. Service states
- (fill in)

### C. Functional tests
- (fill in)

### D. zygctl operations
- (fill in)
```

Commit this file regardless of outcome — it's the test log.

---

### Task 20: Test clean shutdown (halt, reboot, poweroff)

**Files:**
- N/A (operational)

- [ ] **Step 1: Test zygctl halt**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 '/sbin/zygctl halt'
```

Watch console. Expected:
- Reverse-tier shutdown log (`tier 5 → 4 → 3 → 2 → 1 → 0`)
- Daemons stop via contract
- Oneshot stop scripts run (swap -d, filesystem umountall, root-fs remount ro)
- `zyginit: uadmin(A_SHUTDOWN, 0, 0)` logged
- VM halts; `virsh list` shows `running` but kernel is halted (CPU stopped)

If the VM remains in `running` state but unresponsive, that's AD_HALT behavior — expected.

- [ ] **Step 2: Forced reboot from host, reboot into zyginit BE again**

```bash
virsh --connect=qemu:///system destroy hh-prototest   # force power-off since halt has no kernel running
virsh --connect=qemu:///system start hh-prototest
```

Wait for it to come up. Should boot back into zyginit BE (it's still activated).

- [ ] **Step 3: Test zygctl reboot**

```bash
ssh ... 'uname -a; /sbin/zygctl reboot'
```

Expected:
- Reverse-tier shutdown
- `uadmin(AD_BOOT)` logged
- VM reboots automatically
- Comes back up through zyginit BE (still active)

- [ ] **Step 4: Test zygctl poweroff**

```bash
ssh ... '/sbin/zygctl poweroff'
```

Expected:
- Reverse-tier shutdown
- `uadmin(AD_POWEROFF)` logged
- VM transitions to `shut off` in libvirt (`virsh list --all`)

- [ ] **Step 5: Check ZFS pool clean after each shutdown type**

```bash
virsh start hh-prototest
# wait for boot
ssh ... 'zpool status -x'
```

Expected: `all pools are healthy`. No `replay required`, no degraded devices.

- [ ] **Step 6: Append results to the test results file and commit**

Update `docs/superpowers/specs/2026-04-24-pid1-boot-results.md` with §E checklist outcomes.

```bash
hg commit docs/superpowers/specs/2026-04-24-pid1-boot-results.md \
    -m "docs: Phase B PID-1 boot test results — shutdown path"
```

---

### Task 21: Test rollback paths

**Files:**
- N/A (operational)

- [ ] **Step 1: Boot back into the original `hammerhead` BE from GRUB**

Reboot the VM, intercept the GRUB menu via `virsh console`, select `hammerhead` BE.

Expected: SMF-based boot. `svcs -a | wc -l` returns ~142 (original count). Everything working as before zyginit.

- [ ] **Step 2: Switch back to zyginit BE**

From within the `hammerhead` BE:
```bash
ssh ... 'beadm list'         # verify zyginit BE still present
ssh ... 'beadm activate zyginit && init 6'
```

Expected: reboots back into zyginit BE.

- [ ] **Step 3: Disk-level restore drill**

Shut down the VM, restore the pre-change disk, verify it boots normally, then restore the experimental disk back.

```bash
virsh --connect=qemu:///system shutdown hh-prototest   # or force destroy if needed
# wait for shut off
sudo cp /var/lib/libvirt/images/hh-prototest-backup-2026-04-24-pre-zyginit-pid1.qcow2 \
        /tmp/hh-prototest-experimental.qcow2
sudo cp /var/lib/libvirt/images/hh-prototest.qcow2 \
        /var/lib/libvirt/images/hh-prototest-experimental.qcow2.bak
sudo cp /var/lib/libvirt/images/hh-prototest-backup-2026-04-24-pre-zyginit-pid1.qcow2 \
        /var/lib/libvirt/images/hh-prototest.qcow2
virsh start hh-prototest
# wait for boot — should be the pre-zyginit state
ssh ... 'uptime; beadm list'
```

Expected: VM is in pre-zyginit state (only `hammerhead` BE present, no `zyginit` BE).

- [ ] **Step 4: Restore the experimental disk**

```bash
virsh --connect=qemu:///system shutdown hh-prototest
# wait for shut off
sudo cp /var/lib/libvirt/images/hh-prototest-experimental.qcow2.bak \
        /var/lib/libvirt/images/hh-prototest.qcow2
virsh start hh-prototest
```

Expected: back to the zyginit + hammerhead BE state.

- [ ] **Step 5: Record rollback drill results in the results file and commit**

Update `docs/superpowers/specs/2026-04-24-pid1-boot-results.md` with §F checklist outcomes. Commit.

---

## Phase 6.5 — BSD-pivot v2 service set (after iter 5 hit configd wall)

**Context:** Iter 1-5 of Task 19 (revs 24–50) exec'd the v1 21-service set on hh-prototest and surfaced that `dlmgmtd`, `ipmgmtd`, `inetd`, `rpcbind`, and `fmd` are tightly coupled to `svc.configd` via `libscf`. Setting `SMF_FMRI` in the env bypasses their refusal-to-start banner, but `scf_handle_decode_fmri()` still fails without `/etc/svc/volatile/repository_door`, leaving the daemons running but degraded — `ipmgmtd` doesn't open its door socket, `ipadm` errors with "Could not open handle to library", `lo0` is never plumbed, `rpcbind` cascades into "could not find loopback transports", and the entire network stack stays dead.

**Pivot:** Spec §1.1 (revision 2026-04-25) drops the 5 configd-coupled daemons and moves the network tier to direct `ifconfig` invocation, BSD-style — matching IRIX 6.5's `/etc/init.d/network` pattern (`/sbin/ifconfig` plumbs interfaces directly via DLPI, no `ipmgmtd` registry needed; verified on hh-prototest in spec §13). The new default service count is **15**: tier 0 root-fs (1) → tier 1 devfs/swap/crypto (3) → tier 2 filesystem/identity/sysconfig (3) → tier 3 network (1) → tier 4 syseventd/syslogd/utmpd/pfexecd (4) → tier 5 cron/sshd/console-login (3).

**This phase produces the diff** against the on-disk v1 service set: 4 `enabled.d/` symlinks dropped, `network.toml` deps loosened, `network/start.sh` rewritten as a `/etc/hostname.<if>` parser, new `network/stop.sh`, sample interface-config files, then iter 6 boot test against the slimmed set.

**Carry-forwards from iter 1-5 already on disk** (do not redo): rev 43 (root-fs ZFS dispatch), rev 44 (argv[0] supervisor fix), rev 45 (PID-1 fd setup), rev 47 (tier-ordering enforcement), rev 48 (persistent log dir), rev 49 (path corrections for `/bin/hostname`, `/sbin/swapadd`), rev 50 (cron FIFO at `/etc/cron.d/FIFO`).

### Task 22: Drop configd-coupled symlinks from `enabled.d/`

**Files:**
- Delete: `services/hammerhead/enabled.d/dlmgmtd`
- Delete: `services/hammerhead/enabled.d/ipmgmtd`
- Delete: `services/hammerhead/enabled.d/inetd`
- Delete: `services/hammerhead/enabled.d/rpcbind`

The TOML files themselves stay in `services/hammerhead/` — they're now opt-in via `zygctl enable <svc>` per spec §4.7. (`fmd` and `powerd` already have no symlink as of iter 5; nothing to do for those.)

- [ ] **Step 1: Verify pre-state**

Run: `ls services/hammerhead/enabled.d/ | wc -l`
Expected: `19`

Run: `ls services/hammerhead/enabled.d/ | sort`
Expected to include `dlmgmtd`, `ipmgmtd`, `inetd`, `rpcbind` among the 19.

- [ ] **Step 2: Remove the four symlinks**

```bash
hg remove services/hammerhead/enabled.d/dlmgmtd \
         services/hammerhead/enabled.d/ipmgmtd \
         services/hammerhead/enabled.d/inetd \
         services/hammerhead/enabled.d/rpcbind
```

- [ ] **Step 3: Verify post-state**

Run: `ls services/hammerhead/enabled.d/ | wc -l`
Expected: `15`

Run: `ls services/hammerhead/enabled.d/ | sort`
Expected (alphabetical): `console-login cron crypto devfs filesystem identity network pfexecd root-fs sshd swap sysconfig syseventd syslogd utmpd`

- [ ] **Step 4: Commit**

```bash
hg commit -m "services/hammerhead: drop configd-coupled daemons from default enabled set

Iter 1-5 found that dlmgmtd/ipmgmtd/inetd/rpcbind require svc.configd
via libscf for property reads. Without configd, scf_handle_decode_fmri()
fails and the daemons silently degrade (ipmgmtd's door never opens, ipadm
errors out, lo0 never plumbs, rpcbind cascades). Spec §1.1 v2 BSD-pivot
drops them in favor of direct ifconfig invocation. TOMLs retained for
opt-in via zygctl enable."
```

---

### Task 23: Update `network.toml` to drop dlmgmtd/ipmgmtd dependencies

**Files:**
- Modify: `services/hammerhead/network.toml`

`network.toml` currently lists `requires = ["identity", "dlmgmtd", "ipmgmtd"]`. After Task 22 those services aren't enabled, so the dependency edges would dangle. The replacement also drops the v1 comment block referring to `ipadm create-addr`.

- [ ] **Step 1: Replace the file contents**

Write `services/hammerhead/network.toml`:

```toml
# network — Bring up loopback, physical interfaces, routes (BSD-pivot v2)
#
# Direct /sbin/ifconfig invocation, no ipmgmtd or dlmgmtd. Reads
# /etc/hostname.<if> for each physical interface (line-oriented format
# documented in start.sh) and /etc/defaultrouter for static default
# routes. DHCP is handled via `ifconfig <if> dhcp start`, which forks
# /sbin/dhcpagent directly.
#
# Replaces the v1 SMF stack (network/loopback, network/physical,
# network/initial, network/netmask, network/service, network/routing-setup,
# dlmgmtd, ipmgmtd) with a single oneshot using only DLPI primitives.

[service]
name = "network"
description = "Bring up network interfaces and routes (BSD-style)"
type = "oneshot"

[exec]
start = "/etc/zyginit/network/start.sh"
stop = "/etc/zyginit/network/stop.sh"

[dependencies]
requires = ["identity"]

[restart]
on = "never"
```

- [ ] **Step 2: Verify TOML still parses (Linux dry-run)**

Run from repo root:
```bash
ZYGINIT_CONFIG_DIR=$PWD/services/hammerhead \
  ZYGINIT_SOCKET=/tmp/zyg-dry.sock \
  ./build/zyginit > /tmp/zyg-dry.log 2>&1 &
sleep 1
ZYGINIT_SOCKET=/tmp/zyg-dry.sock tools/zygctl/build/zygctl list | grep network
kill %1 2>/dev/null
```

Expected: line of form `network <tier> <state> ...` printed; no `requires unknown service` errors in `/tmp/zyg-dry.log`.

- [ ] **Step 3: Commit**

```bash
hg commit services/hammerhead/network.toml \
    -m "services/hammerhead/network: drop dlmgmtd/ipmgmtd deps; declare stop script"
```

---

### Task 24: Rewrite `network/start.sh` as `/etc/hostname.<if>` parser

**Files:**
- Modify: `services/hammerhead/network/start.sh` (full rewrite)

The v1 script used `ipadm create-if` / `ipadm create-addr` which both go through `ipmgmtd`. The v2 script invokes `/sbin/ifconfig` directly — operates at DLPI/kernel-ioctl layer, no daemon registry needed (verified in spec §13). Line forms supported (per spec §4.4):

| Line | Action |
|---|---|
| (empty/whitespace-only file) | `ifconfig <if> plumb up` |
| `# …` or blank line | skipped |
| `dhcp` | `ifconfig <if> plumb`; `ifconfig <if> dhcp start` |
| `inet <addr>/<prefix>` | `ifconfig <if> inet <addr>/<prefix> up` |
| `inet <addr> netmask <mask>` | `ifconfig <if> inet <addr> netmask <mask> up` |
| `addif <addr>/<prefix>` | additional alias address (`ifconfig <if> addif`) |
| `inet6 <addr>/<prefix>` | `ifconfig <if> inet6 <addr>/<prefix> up` |
| `up` / `down` | explicit link state |

- [ ] **Step 1: Replace the file contents**

Write `services/hammerhead/network/start.sh`:

```zsh
#!/bin/zsh
# network/start.sh — BSD-style interface/route bring-up (v2)
#
# No ipmgmtd, no dlmgmtd. Uses /sbin/ifconfig directly for plumbing,
# /sbin/dhcpagent (forked by ifconfig dhcp start) for DHCP, and
# /usr/sbin/route for static routes from /etc/defaultrouter.
#
# Walks /etc/hostname.<if> files (one per interface to configure). Each
# file is line-oriented; see the case statement below for supported syntax.

set -e
set -u

# Enable [[:space:]]## "one or more" repetition in pattern matching.
setopt EXTENDED_GLOB

IFCONFIG=/sbin/ifconfig
ROUTE=/usr/sbin/route

# --- Force-load IP STREAMS modules ---
# zyginit's tier ordering runs network/start.sh before SMF's traditional
# autoload triggers fire, so socket(PF_INET) returns EAFNOSUPPORT until
# the ip / ip6 drivers are explicitly loaded. modload is idempotent:
# returns success on already-loaded modules.
/sbin/modload /kernel/drv/ip || true
/sbin/modload /kernel/drv/ip6 || true

# --- Loopback ---
# Plumb lo0 explicitly (the kernel auto-attaches it but we want predictable
# state). `ifconfig lo0 plumb` is idempotent — repeats just succeed.
$IFCONFIG lo0 plumb || true
$IFCONFIG lo0 inet 127.0.0.1 netmask 255.0.0.0 up || true
$IFCONFIG lo0 inet6 ::1/128 up || true

# --- Physical interfaces ---
# Each /etc/hostname.<if> file marks an interface to configure (BSD style).
# The configure_interface() helper plumbs the named link and applies the
# directives in the file.
configure_interface() {
    local iface="$1"
    local cfgfile="/etc/hostname.${iface}"

    if [[ ! -e "$cfgfile" ]]; then
        # No config — leave the interface untouched. (Operator can plumb
        # by-hand or add a config file and re-run; this matches OpenBSD.)
        return 0
    fi

    # Plumb first; downstream lines may add addresses to it.
    $IFCONFIG "$iface" plumb || true

    # If the config file has no non-comment content, just bring it up.
    if ! grep -Eq '^[[:space:]]*[^#[:space:]]' "$cfgfile" 2>/dev/null; then
        $IFCONFIG "$iface" up
        return 0
    fi

    # Walk the file line by line.
    while IFS= read -r line || [[ -n "$line" ]]; do
        # Strip comments, then leading and trailing whitespace.
        # `[[:space:]]##` is zsh extended glob for "one or more whitespace
        # chars" — covers tab-indented lines and multi-space margins that
        # an editor might insert. EXTENDED_GLOB is enabled at script top;
        # the `\#` escape is needed because EXTENDED_GLOB makes bare `#` a
        # pattern operator.
        line="${line%%\#*}"
        line="${line##[[:space:]]##}"
        line="${line%%[[:space:]]##}"
        [[ -z "$line" ]] && continue

        # Split on first whitespace into verb + rest.
        local verb="${line%%[[:space:]]*}"
        local rest=""
        if [[ "$line" == *[[:space:]]* ]]; then
            rest="${line#*[[:space:]]}"
        fi

        # ${=rest} forces word-splitting on $rest — necessary because
        # ifconfig args like `192.168.122.50/24 up` need to arrive as
        # separate arguments, not one quoted string.
        case "$verb" in
            dhcp)
                $IFCONFIG "$iface" dhcp start
                ;;
            inet)
                # `inet <addr>/<prefix>` or `inet <addr> netmask <mask>`
                $IFCONFIG "$iface" inet ${=rest} up
                ;;
            addif)
                $IFCONFIG "$iface" addif ${=rest} up
                ;;
            inet6)
                $IFCONFIG "$iface" inet6 ${=rest} up
                ;;
            up|down)
                $IFCONFIG "$iface" "$verb"
                ;;
            *)
                print -u2 "network: ignoring unknown directive in $cfgfile: $line"
                ;;
        esac
    done < "$cfgfile"
}

# Iterate /etc/hostname.<if> files — the BSD-style marker for "configure
# this interface." Iter 7 boot showed /dev/net/ enumeration silently
# skipped vioif0 on Hammerhead (the directory either doesn't exist or
# doesn't contain DLPI link nodes for virtio NICs); switching to
# hostname.* lookup is both more portable and closer to OpenBSD's
# original semantics.
for cfg in /etc/hostname.*(N); do
    fname="${cfg:t}"
    # ${cfg:t} returns "hostname.vioif0"; strip the prefix.
    iface="${fname#hostname.}"
    # Defensively skip loopback (we already handled lo0 above).
    [[ "$iface" == "lo0" ]] && continue
    configure_interface "$iface"
done

# --- Static default routes ---
# /etc/defaultrouter is one IPv4 address per line. DHCP-acquired routes
# don't need this file; only set one when the operator opts in.
if [[ -r /etc/defaultrouter ]]; then
    while IFS= read -r line || [[ -n "$line" ]]; do
        # Same trim treatment as the hostname.<if> parser. `\#` is
        # escaped because EXTENDED_GLOB is set script-wide.
        line="${line%%\#*}"
        line="${line##[[:space:]]##}"
        line="${line%%[[:space:]]##}"
        [[ -z "$line" ]] && continue
        $ROUTE -n add default "$line" || true
    done < /etc/defaultrouter
fi

exit 0
```

- [ ] **Step 2: Make sure it's still executable**

```bash
chmod +x services/hammerhead/network/start.sh
ls -l services/hammerhead/network/start.sh
```

Expected: mode `-rwxr-xr-x` (or compatible).

- [ ] **Step 3: Sanity-check syntax with `zsh -n`**

```bash
zsh -n services/hammerhead/network/start.sh
```

Expected: no output (clean parse). If your dev host doesn't have `zsh`, skip — the test VM will be the source of truth.

- [ ] **Step 4: Commit**

```bash
hg commit services/hammerhead/network/start.sh \
    -m "services/hammerhead/network/start.sh: BSD-style /etc/hostname.<if> parser

Drops ipadm/dladm in favor of direct /sbin/ifconfig invocation. Walks
/dev/net/ for physical links, reads /etc/hostname.<if> per interface
(line-oriented: dhcp / inet ADDR/PREFIX / addif / inet6 / up / down),
and /etc/defaultrouter for static defaults. Verified in spec §13 that
ifconfig plumb/inet/dhcp all work without ipmgmtd."
```

---

### Task 25: Author `network/stop.sh`

**Files:**
- Create: `services/hammerhead/network/stop.sh`

Symmetric reversal: kill any `dhcpagent` we forked, then unplumb non-loopback interfaces. Called during shutdown via the `[exec] stop = ...` line added in Task 23.

- [ ] **Step 1: Write the file**

Write `services/hammerhead/network/stop.sh`:

```zsh
#!/bin/zsh
# network/stop.sh — reverse of start.sh (BSD-pivot v2)
#
# Releases DHCP leases and unplumbs all configured non-loopback interfaces.
# Best-effort: each command may fail (e.g., interface already torn down,
# dhcpagent already gone) and we continue regardless. ZFS sync happens
# in main.reef after this runs.

set -u
# NOTE: no `set -e` — every step is best-effort during shutdown.

IFCONFIG=/sbin/ifconfig

# Release any DHCP leases first so the server marks them free.
if [[ -d /dev/net ]]; then
    for dev in /dev/net/*(N); do
        link="${dev:t}"
        [[ "$link" == "lo0" ]] && continue
        # `dhcp release` is idempotent — silently no-op if no lease.
        $IFCONFIG "$link" dhcp release 2>/dev/null || true
    done
fi

# Kill the dhcpagent itself. It manages all leases globally, so one kill
# tears down every interface's state at once.
pkill -TERM -x dhcpagent 2>/dev/null || true

# Unplumb. inet6 first (Hammerhead requires this ordering for clean teardown).
if [[ -d /dev/net ]]; then
    for dev in /dev/net/*(N); do
        link="${dev:t}"
        [[ "$link" == "lo0" ]] && continue
        $IFCONFIG "$link" inet6 unplumb 2>/dev/null || true
        $IFCONFIG "$link" unplumb 2>/dev/null || true
    done
fi

exit 0
```

- [ ] **Step 2: Make executable**

```bash
chmod +x services/hammerhead/network/stop.sh
```

- [ ] **Step 3: Syntax check**

```bash
zsh -n services/hammerhead/network/stop.sh
```

Expected: no output.

- [ ] **Step 4: Commit**

```bash
hg add services/hammerhead/network/stop.sh
hg commit -m "services/hammerhead/network: add stop.sh — release DHCP, unplumb interfaces"
```

---

### Task 26: Author sample `/etc/hostname.<if>` and `/etc/defaultrouter` files

**Files:**
- Create: `services/hammerhead/examples/etc-hostname.vioif0-static`
- Create: `services/hammerhead/examples/etc-hostname.vioif0-dhcp`
- Create: `services/hammerhead/examples/etc-defaultrouter`

These are reference templates the operator copies onto the test VM during iter 6 install. They don't ship via `install-to-be.sh` (that would clobber operator network config); they're versioned artifacts the operator manually drops into `/etc/` on the target BE.

The hh-prototest VM lives on `192.168.122.0/24` behind libvirt's dnsmasq. `192.168.122.50` is inside libvirt's default dnsmasq pool (`192.168.122.2`–`192.168.122.254`); before iter 6 boot, the operator must reserve `.50` via `<host>` in `virsh net-edit default` or shrink the pool's `<range>` to exclude it. The static sample's header comment documents both options.

- [ ] **Step 1: Create the examples directory**

```bash
mkdir -p services/hammerhead/examples
```

- [ ] **Step 2: Write the static-IP sample**

Write `services/hammerhead/examples/etc-hostname.vioif0-static`:

```
# /etc/hostname.vioif0 — static IPv4 for hh-prototest libvirt VM.
# Copy to /etc/hostname.vioif0 on the target BE.
#
# 192.168.122.50 is INSIDE libvirt's default dnsmasq pool
# (192.168.122.2-192.168.122.254). Before iter 6 boot, prevent
# collision via one of:
#   1. Add a host reservation to the libvirt network XML:
#      virsh net-edit default
#      <dhcp> ... <host mac='52:54:00:...' name='hh-prototest' ip='192.168.122.50'/>
#   2. Shrink the dnsmasq range, e.g.
#      <range start='192.168.122.100' end='192.168.122.254'/>
#   3. Use an address outside the libvirt subnet entirely (requires extra routing).
#
# See spec §4.4 for the full /etc/hostname.<if> grammar.
inet 192.168.122.50/24
```

- [ ] **Step 3: Write the DHCP sample**

Write `services/hammerhead/examples/etc-hostname.vioif0-dhcp`:

```
# /etc/hostname.vioif0 — DHCP-acquired address for hh-prototest
# Copy to /etc/hostname.vioif0 on the target BE.
#
# Caveat (spec §4.4): /sbin/dhcpagent links libipadm.so.1 which talks to
# ipmgmtd's door. Without ipmgmtd running, lease application may degrade.
# Use the static sample first to derisk; switch to this once iter 6
# proves DHCP-without-ipmgmtd works.
dhcp
```

- [ ] **Step 4: Write the defaultrouter sample**

Write `services/hammerhead/examples/etc-defaultrouter`:

```
# /etc/defaultrouter — one IPv4 default-gateway address per line.
# Copy to /etc/defaultrouter on the target BE *only* when using the
# static-IP sample; DHCP supplies the route automatically.
#
# 192.168.122.1 is libvirt's default-network virtual router.
192.168.122.1
```

- [ ] **Step 5: Commit**

```bash
hg add services/hammerhead/examples/
hg commit -m "services/hammerhead/examples: sample /etc/hostname.<if> and /etc/defaultrouter

For hh-prototest libvirt VM (192.168.122.0/24). Static-IP sample uses
.50 (inside default dnsmasq pool — header comment documents the
required reservation/range-shrink); DHCP sample documents the libipadm
caveat from spec §4.4. Operator copies these onto the target BE during
iter 6."
```

---

### Task 27: Iter 6 boot test — static-IP first, DHCP follow-up

**Files:**
- N/A (operational)
- Modify: `docs/superpowers/specs/2026-04-24-pid1-boot-results.md` (the test log file from Task 19, if it exists; create otherwise)

This task replaces the boot procedure originally captured in Task 19 + Task 20, now operating on the v2 service set. The recovery ladder from spec §8.4 still applies; the disk-level backup (`hh-prototest-backup-2026-04-24-pre-zyginit-pid1.qcow2`) and the ~75s recovery cycle are proven.

- [ ] **Step 1: Restore from disk backup if the BE from iter 5 is dirty**

If the on-disk hh-prototest qcow2 is in a known-bad state from iter 5:

```bash
virsh --connect=qemu:///system destroy hh-prototest 2>/dev/null || true
sudo cp /var/lib/libvirt/images/hh-prototest-backup-2026-04-24-pre-zyginit-pid1.qcow2 \
        /var/lib/libvirt/images/hh-prototest.qcow2
virsh --connect=qemu:///system start hh-prototest
```

Wait for SSH to be reachable: `until ssh -o ConnectTimeout=2 -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 'true' 2>/dev/null; do sleep 5; done`.

If iter 5's disk is salvageable (boots into `hammerhead` BE cleanly), skip this step.

- [ ] **Step 2: Build fresh binaries on the dev host and ship them**

```bash
cd /home/ctusa/repos/zyginit
# Hammerhead build target — see CLAUDE.md / MEMORY.md
reefc build -l contract
(cd tools/zygctl && clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o && reefc build --obj build/symlink_wrapper.o)
rsync -a build/zyginit tools/zygctl/build/zygctl services/ scripts/ \
    -e 'ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519' \
    root@192.168.122.197:/root/zyginit/
```

Expected: 15 TOMLs in `/root/zyginit/services/hammerhead/`, 15 enabled.d entries, both binaries fresh.

- [ ] **Step 3: Create fresh BE and install**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
set -e
# If a stale 'zyginit' BE exists from iter 5, destroy it first.
beadm list | awk '$1 == "zyginit" {print "exists"}' | grep -q exists && {
    beadm activate hammerhead
    beadm destroy -F zyginit
}
beadm create zyginit
beadm mount zyginit /mnt
cd /root/zyginit && ./scripts/install-to-be.sh /mnt
ls /mnt/etc/zyginit/enabled.d/ | wc -l
EOF
```

Expected last line: `15`.

- [ ] **Step 4: Drop the static-IP `/etc/hostname.vioif0` and `/etc/defaultrouter` onto the new BE**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
cp /root/zyginit/services/hammerhead/examples/etc-hostname.vioif0-static /mnt/etc/hostname.vioif0
cp /root/zyginit/services/hammerhead/examples/etc-defaultrouter /mnt/etc/defaultrouter
cat /mnt/etc/hostname.vioif0 /mnt/etc/defaultrouter
EOF
```

Expected: contents of both sample files printed.

- [ ] **Step 5: Activate and reboot**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 <<'EOF'
beadm umount zyginit
beadm activate zyginit
beadm list
EOF
```

In a separate terminal, attach the console (so we can watch the boot):
```bash
virsh --connect=qemu:///system console hh-prototest
```

Then reboot:
```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.197 'init 6'
```

- [ ] **Step 6: Verify SSH comes up at 192.168.122.50**

The static IP is `.50`, NOT `.197`. After reboot:

```bash
until ssh -o ConnectTimeout=2 -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.50 'true' 2>/dev/null; do
    sleep 3
done
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.50 \
    'ifconfig -a; route -n get default; /sbin/zygctl list'
```

Expected:
- `vioif0: ... inet 192.168.122.50 netmask ffffff00 ...`
- `route ... default 192.168.122.1` reachable
- `zygctl list` shows 15 services, all `RUNNING` (daemons) or `STOPPED exit=0` (oneshots), none in `MAINTENANCE`.

- [ ] **Step 7: Run §9.A-D success checklist**

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.50 <<'EOF'
echo "--- A. boot ---"
uptime
ps -p 1 -o pid,comm
ps -ef | grep -E 'zyginit|sshd|cron' | grep -v grep

echo "--- B. service states ---"
/sbin/zygctl list

echo "--- C. functional ---"
ifconfig vioif0
ping -c 2 192.168.122.1 || echo "ping failed"
zfs list | head -5
logger -p user.info "iter6-static marker"
tail -5 /var/adm/messages 2>/dev/null || echo "messages unavailable"

echo "--- D. zygctl e2e ---"
/sbin/zygctl status cron
/sbin/zygctl stop cron
/sbin/zygctl status cron
/sbin/zygctl start cron
/sbin/zygctl status cron
EOF
```

Record pass/fail for each line in `docs/superpowers/specs/2026-04-24-pid1-boot-results.md`. Spec §9 is the source of truth for what counts as pass.

- [ ] **Step 8: Iter 6 DHCP variant (only if Step 7 fully passes)**

Switch the interface to DHCP and reboot:

```bash
ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.122.50 <<'EOF'
cp /root/zyginit/services/hammerhead/examples/etc-hostname.vioif0-dhcp /etc/hostname.vioif0
rm -f /etc/defaultrouter
init 6
EOF
```

After reboot, the VM may come up at `192.168.122.197` (its previous DHCP lease), at any other address libvirt's dnsmasq hands out, or — if DHCP-via-dhcpagent degrades without ipmgmtd — without an address at all.

Probe behavior:
```bash
# Watch the libvirt DHCP leases:
virsh --connect=qemu:///system net-dhcp-leases default
# And the console for ifconfig errors during boot.
```

Three outcomes:
1. **DHCP works** → record pass in spec §13 ("DHCP-via-dhcpagent without ipmgmtd: confirmed"); update `examples/etc-hostname.vioif0-dhcp` comment to remove the caveat.
2. **DHCP partially works** (lease acquired, address not applied) → log the failure mode, leave the static sample as the documented default, file follow-up to investigate `dhcpagent -a -f` adopt mode.
3. **DHCP fails entirely** → log, revert to the static sample with concrete commands:
   ```bash
   cp /root/zyginit/services/hammerhead/examples/etc-hostname.vioif0-static /etc/hostname.vioif0
   cp /root/zyginit/services/hammerhead/examples/etc-defaultrouter /etc/defaultrouter
   ```
   Then document in spec §13 / §11 that DHCP needs a separate design.

- [ ] **Step 9: Update the test results file**

Write or extend `docs/superpowers/specs/2026-04-24-pid1-boot-results.md` with iter 6 outcomes (sections A through F per spec §9). Commit:

```bash
hg add docs/superpowers/specs/2026-04-24-pid1-boot-results.md 2>/dev/null || true
hg commit docs/superpowers/specs/2026-04-24-pid1-boot-results.md \
    -m "docs: iter 6 PID-1 boot results — v2 BSD-pivot service set"
```

- [ ] **Step 10: Run shutdown + rollback drills (Task 20 + Task 21)**

Tasks 20 and 21 still apply unchanged for v2 — they exercise `zygctl halt`/`reboot`/`poweroff` and the BE rollback path. Run them now against the iter-6 BE and append results to the same `2026-04-24-pid1-boot-results.md` file.

---

## Phase 7 — Wrap-up

### Task 28: Update CLAUDE.md, README.md, ROADMAP.md with results

**Files:**
- Modify: `CLAUDE.md`
- Modify: `README.md`
- Modify: `ROADMAP.md`

- [ ] **Step 1: Mark PID-1 boot as complete in ROADMAP.md**

Open `ROADMAP.md`. Find the "PID 1 Boot Testing" section. Change the unchecked items under it to `[x]` for the ones that passed in the iter-6 boot test (per the results file from Task 27).

- [ ] **Step 2: Add a note in CLAUDE.md about the new service set**

Under the source layout section, add:

```
- `services/hammerhead/` — Production Hammerhead service set (15 services
  enabled by default after the v2 BSD-pivot; 6 more TOMLs ship for opt-in
  via `zygctl enable`. Distinct from `services/examples/` Linux scaffolding.)
- `services/hammerhead/examples/` — Reference `/etc/hostname.<if>` and
  `/etc/defaultrouter` templates for hh-prototest; operator-copied, not
  shipped via install-to-be.sh.
```

- [ ] **Step 3: Commit**

```bash
hg commit CLAUDE.md README.md ROADMAP.md \
    -m "docs: mark PID-1 boot milestone complete; document services/hammerhead/ v2"
```

---

## Self-Review

After writing the plan, cross-check each spec section against tasks:

**Spec coverage:**
- §1.1 BSD-pivot rationale → Phase 6.5 prelude documents the configd wall and §1.1's three-choice decision
- §3.1 Components → Task 15 (installer copies binaries + config tree); unchanged in v2
- §3.2 Boot sequence → Tasks 9-14 + Task 23 (TOMLs); §3.2's tier ordering is enforced by rev 47, not re-implemented in v2
- §3.3 PID-1 vs non-PID-1 → Tasks 3, 5 (detection + branching)
- §4 Service set v2 (15 services) → Tasks 22-26 produce the diff from v1's 21-service set; the 4 dropped enabled.d entries align with §4.7/§4.8
- §4.4 `/etc/hostname.<if>` line forms → Task 24's case statement implements every row of the spec table (dhcp / inet / addif / inet6 / up / down)
- §4.4 `/etc/defaultrouter` → Task 24's tail block reads it; Task 26 ships a sample
- §4.7 Optional-but-not-enabled set → Task 22 keeps the 4 TOMLs in `services/hammerhead/` while removing only the symlinks
- §5 Schema usage → Tasks 9-14 + Task 23 (TOML content)
- §6 Script conventions → Tasks 24, 25 follow the `#!/bin/zsh` + `set -e -u` template; Task 25 deliberately drops `set -e` per the convention's "best-effort during shutdown" allowance
- §7 Shutdown orchestration → Tasks 1-6 (code changes), Task 8 (integration test); v2 adds `network/stop.sh` (Task 25) which is invoked by the existing reverse-tier walk
- §8 Rollout phases → Phase 5 (dry run), Phase 6 + 6.5 (BE boot), Task 21 (rollback drill); Task 27 Step 1 reuses §8.4's disk-restore recovery
- §9 Success criteria → Tasks 19-21 + Task 27 Step 7-10 run the checklist
- §11 Deferrals → Task 7 ships `single`/`multiuser` stubs; Task 27 Step 8 outcomes feed §11's "configd-coupled daemons re-add" deferral
- §13 Open questions → Task 27 Step 8 empirically resolves the DHCP-without-ipmgmtd question

**Placeholder scan:** none — all TOMLs, scripts, and code blocks contain actual content. Task 27 Steps 7-8 do reference "record results" actions, but the recording targets are concrete (specific spec sections / file path).

**Type consistency:** shutdown-type constants (SHUT_HALT=1, SHUT_REBOOT=2, SHUT_POWEROFF=3) unchanged in v2. The `network` service name (depended on by syseventd/syslogd/utmpd/pfexecd in tier 4) is preserved across Task 23 — only the inner `requires` list of `network.toml` itself changes. `network/start.sh` and `network/stop.sh` paths match the `[exec] start/stop` lines in the revised TOML.

**Scope check:** Phase 6.5 is contained within the existing PID-1-boot milestone; the v2 pivot replaces 4 enabled-set members and one start.sh, but doesn't introduce a new subsystem. Single plan remains correct.

---

## Plan complete

Plan saved to `docs/superpowers/plans/2026-04-24-pid1-boot.md`.
# Contract Re-adoption (Live Replace) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Spec:** `docs/superpowers/specs/2026-05-02-contract-readoption-design.md` (rev 84).

**Goal:** Allow `zygctl replace` to upgrade the running zyginit PID-1 process via in-place `execve("/sbin/init", ...)` while preserving every running service across the swap, with state-file handoff for in-memory bookkeeping.

**Architecture:** New `src/replace.reef` module owns the state-file format, serialization, recovery, and pre-condition check. `main.reef` gains a `replace_self` proc (outgoing flow: drain, write state, unlink socket, exec) and an `apply_recovered_state` proc (incoming flow: stitch state.toml against current `enabled.d/`, register `contract_map`, idempotent post-recovery empty-contract check). `socket.reef` adds a `replace [--wait=N]` command. `contract.reef` adds an `is_contract_empty` helper. `zygctl.reef` adds the `replace` subcommand. **No `ct_ctl_adopt` call is needed**: PID-1 in-place execve preserves `proc_t.p_ct_process` so kernel-level contract ownership survives automatically; only userspace bookkeeping needs rebuilding.

**Tech Stack:** Reef 0.4.0+, Hammerhead libcontract, POSIX FFI, TOML (existing `encoding.toml` parser), Mercurial (`hg`) for VCS.

**Conventions** — pulled from CLAUDE.md / SRCHEADER.txt. **All new source files MUST start with the SRCHEADER.txt template** with `${project}=zyginit`, `${file.name}` = the filename, `${file.description}` filled in. **VCS is `hg` not `git`.** **License is CDDL-1.0.** **"Hammerhead" not "illumos"** in code/comments. **No emojis** in source.

**Build commands** (used in test/verify steps throughout):

```bash
# Linux dev (stubs the contract bindings)
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o

# zygctl Linux
cd tools/zygctl
clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o
reefc build --obj build/symlink_wrapper.o
cd ../..
```

---

## File structure

| File | Action | Responsibility |
|---|---|---|
| `src/helpers.c` | Modify | Add `zyginit_read_boot_time` C helper. |
| `src/replace.reef` | Create (~250 lines) | State-file format, serialize, recover, pre-condition check. |
| `src/contract.reef` | Modify (+~25 lines) | Add `is_contract_empty(ctid): bool` helper. |
| `src/contract_linux_stubs.c` | Modify (+5 lines) | Linux stub for `is_contract_empty`. |
| `src/socket.reef` | Modify (+~50 lines) | Add `replace [--wait=N]` command, flag, accessors. |
| `src/main.reef` | Modify (+~120 lines) | Add `apply_recovered_state`, `replace_self`, integrate into startup + event loop. |
| `tools/zygctl/src/zygctl.reef` | Modify (+~30 lines) | Add `replace [--wait=N]` subcommand. |
| `utils/replace_probe/` | Create | Standalone Reef program for state-file format unit tests, modeled on `utils/contract_probe/`. |
| `tests/integration/run_tests.sh` | Modify | Add Linux integration scenarios (smoke + pre-condition refusal). |
| `tests/integration/test_replace_hammerhead.md` | Create | Manual checklist for Hammerhead `hh-prototest` validation. |
| `man/zygctl.8` | Modify | Document `zygctl replace [--wait=N]`. |
| `man/zyginit.8` | Modify | Document state.toml file path + replace flow at a high level. |

---

## Task 1: Add `zyginit_read_boot_time` C helper

**Files:**
- Modify: `src/helpers.c` (append a new function near the existing utmpx writers around line 150)

The helper reads `BOOT_TIME` from `/var/adm/utmpx` and returns its `ut_tv.tv_sec` as `int`, or `-1` if not found / not readable. This becomes the boot-id sentinel that survives execve and lets the new zyginit detect a stale state.toml from before a real reboot.

- [ ] **Step 1: Read existing helpers.c around the BOOT_TIME writer to confirm placement and headers**

Run: `grep -n 'BOOT_TIME\|getutxent\|setutxent\|endutxent' src/helpers.c`
Expected: see `BOOT_TIME` referenced in `zyginit_write_boot_utmpx`, header `utmpx.h` already included.

- [ ] **Step 2: Add the read helper after `zyginit_write_runlvl_utmpx`**

Append to `src/helpers.c`:

```c
/* Read the BOOT_TIME utmpx record's tv_sec value, used as the boot-id
 * sentinel for the live-replace state file. PID-1 in-place execve
 * preserves the same proc_t but the kernel does not preserve a "boot
 * id" anywhere obvious — utmpx BOOT_TIME survives because it lives in
 * /var/adm/utmpx, written by zyginit_write_boot_utmpx() at boot. A
 * real reboot writes a new BOOT_TIME with a different tv_sec, so
 * comparing against it lets the new zyginit detect a stale state file.
 *
 * Returns the BOOT_TIME tv_sec on success, or -1 if the file is not
 * readable, has no BOOT_TIME entry, or any utmpx call fails.
 */
int zyginit_read_boot_time(void) {
    struct utmpx *up;
    int result = -1;

    setutxent();
    while ((up = getutxent()) != NULL) {
        if (up->ut_type == BOOT_TIME) {
            result = (int) up->ut_tv.tv_sec;
            break;
        }
    }
    endutxent();
    return result;
}
```

- [ ] **Step 3: Build helpers.o on Linux to verify it compiles**

Run: `clang -c src/helpers.c -o build/helpers.o`
Expected: no errors, no warnings. (`utmpx.h` is in libc; on Linux it's `glibc`'s utmpx.)

- [ ] **Step 4: Commit**

```bash
hg add src/helpers.c
hg commit -m "helpers: add zyginit_read_boot_time for live-replace boot-id check"
```

(Note: `hg add` is a no-op for already-tracked files, but harmless.)

---

## Task 2: Skeleton `src/replace.reef` module

**Files:**
- Create: `src/replace.reef`

Empty-bodied module with SRCHEADER, FFI extern, and the export block that subsequent tasks will fill in. Establishing the surface up front lets later tasks be small and incremental.

- [ ] **Step 1: Create the file with header and module declaration**

Write `src/replace.reef`:

```reef
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ `/ /_/ ___/ ___/ __ `/ / _ \
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zyginit
   Filename: replace.reef
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Live-replace state-file handoff (operator-driven PID-1 upgrade)

******************************************************************************/

// Live-replace operator flow: zygctl replace -> old zyginit serializes
// runtime state to /var/run/zyginit/state.toml, execs /sbin/init in
// place; new zyginit reads state.toml, validates boot_time matches
// current utmpx BOOT_TIME (else stale across a real reboot), and
// rebuilds the contract_map / runtime fields in supervisor.ServiceTable.
//
// PID-1 in-place execve preserves proc_t.p_ct_process at the kernel
// level, so contract ownership survives automatically — no
// ct_ctl_adopt call is needed. This module owns userspace bookkeeping.

module replace

import config
import supervisor
import io.file
import sys.fd as fd
import sys.env as sysenv
import core.str
import encoding.toml
import time.time as time

export
    type RecoveredService
    type RecoveredState

    // Accessors — RecoveredState
    fn rs_count(s: RecoveredState): int
    fn rs_service(s: RecoveredState, idx: int): RecoveredService
    fn rs_boot_time(s: RecoveredState): int
    fn rs_is_empty(s: RecoveredState): bool

    // Accessors — RecoveredService
    fn svc_name(rs: RecoveredService): string
    fn svc_contract_id(rs: RecoveredService): int
    fn svc_restart_count(rs: RecoveredService): int
    fn svc_last_start_time(rs: RecoveredService): int
    fn svc_last_exit_code(rs: RecoveredService): int

    // Outgoing flow — write state, return true on success
    fn serialize_state(table: supervisor.ServiceTable, boot_time: int): bool

    // Incoming flow — read state file. Returns an empty RecoveredState
    // if the file is missing, corrupt, or has a mismatched boot_time.
    fn recover_state(current_boot_time: int): RecoveredState

    // Pre-condition check. Returns "" if all services are stable, else
    // a comma-separated "name:state" list suitable for logging.
    fn check_preconditions(table: supervisor.ServiceTable): string

    // FFI for boot-time sentinel (helpers.c)
    fn read_boot_time(): int

    // Constants
    fn STATE_FILE_PATH(): string
    fn STATE_TMP_PATH(): string
    fn STATE_DIR(): string
end export

// FFI — implemented in helpers.c
extern "C" fn zyginit_read_boot_time(): int
extern "C" fn zyginit_fsync_path(path: string): int

// FFI — POSIX
extern "C" fn open(path: string, flags: int, mode: int): int
extern "C" fn close(fd: int): int
extern "C" fn rename(oldpath: string, newpath: string): int
extern "C" fn unlink(path: string): int

// Reads utmpx BOOT_TIME via the C helper. Returns -1 if unavailable.
fn read_boot_time(): int
    return zyginit_read_boot_time()
end read_boot_time

// File-system layout. Keep grouped here so a future tmpfs migration
// only edits one place.
fn STATE_DIR(): string
    return sysenv.get_env_or("ZYGINIT_RUN_DIR", "/var/run/zyginit")
end STATE_DIR

fn STATE_FILE_PATH(): string
    return str.concat(STATE_DIR(), "/state.toml")
end STATE_FILE_PATH

fn STATE_TMP_PATH(): string
    return str.concat(STATE_DIR(), "/state.toml.tmp")
end STATE_TMP_PATH

end module
```

- [ ] **Step 2: Add to `reef.toml` if it lists modules explicitly (it doesn't currently — `source_dirs = ["src"]`); confirm with build**

Run: `clang -c src/helpers.c -o build/helpers.o && clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o && reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o`
Expected: build fails with errors about missing function bodies (`rs_count`, `serialize_state`, etc. are exported but not yet implemented). This is expected — subsequent tasks fill them in.

If reefc complains about exporting types/fns without bodies in the same module, comment out the export block temporarily by wrapping it in `/* ... */` (Reef does not support `/* */` comments — use line `//` per item) until enough is in place. The skeleton below in Task 3+ will populate types and fn bodies in the order needed to keep the build happy.

If `reefc` allows undefined exports as forward declarations, the build will fail on the first reference site instead — that's fine, fix it as the next task adds bodies.

- [ ] **Step 3: Commit even though build is incomplete**

```bash
hg add src/replace.reef
hg commit -m "replace: skeleton module with FFI declarations and exports"
```

---

## Task 3: Define `RecoveredService` and `RecoveredState` types

**Files:**
- Modify: `src/replace.reef`

Add the types and trivial accessors. After this task the module compiles even with stub bodies for the larger fns.

- [ ] **Step 1: Add type definitions before the `end module` at the bottom of `src/replace.reef`**

```reef
// ============================================================================
// Types
// ============================================================================

type RecoveredService = struct
    name: string
    contract_id: int
    restart_count: int
    last_start_time: int
    last_exit_code: int
end RecoveredService

type RecoveredState = struct
    boot_time: int
    services: [RecoveredService]
    count: int
end RecoveredState

fn new_recovered_state(): RecoveredState
    return RecoveredState{
        boot_time: 0 - 1,
        services: new [RecoveredService](0),
        count: 0
    }
end new_recovered_state

// ============================================================================
// Accessors
// ============================================================================

fn rs_count(s: RecoveredState): int
    return s.count
end rs_count

fn rs_service(s: RecoveredState, idx: int): RecoveredService
    return s.services[idx]
end rs_service

fn rs_boot_time(s: RecoveredState): int
    return s.boot_time
end rs_boot_time

fn rs_is_empty(s: RecoveredState): bool
    return s.count == 0
end rs_is_empty

fn svc_name(rs: RecoveredService): string
    return rs.name
end svc_name

fn svc_contract_id(rs: RecoveredService): int
    return rs.contract_id
end svc_contract_id

fn svc_restart_count(rs: RecoveredService): int
    return rs.restart_count
end svc_restart_count

fn svc_last_start_time(rs: RecoveredService): int
    return rs.last_start_time
end svc_last_start_time

fn svc_last_exit_code(rs: RecoveredService): int
    return rs.last_exit_code
end svc_last_exit_code
```

- [ ] **Step 2: Add stub bodies for the three larger fns so the module compiles. They are filled in by Tasks 4, 5, and 6.**

```reef
// ============================================================================
// Outgoing — stub (filled by Task 4)
// ============================================================================

fn serialize_state(table: supervisor.ServiceTable, boot_time: int): bool
    return false
end serialize_state

// ============================================================================
// Incoming — stub (filled by Task 5)
// ============================================================================

fn recover_state(current_boot_time: int): RecoveredState
    return new_recovered_state()
end recover_state

// ============================================================================
// Pre-condition check — stub (filled by Task 6)
// ============================================================================

fn check_preconditions(table: supervisor.ServiceTable): string
    return ""
end check_preconditions
```

- [ ] **Step 3: Build**

Run: `clang -c src/helpers.c -o build/helpers.o && clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o && reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o`
Expected: build succeeds. zyginit binary produced at `build/zyginit`. The replace module is compiled but unused.

- [ ] **Step 4: Commit**

```bash
hg commit -m "replace: types, accessors, and stub bodies for serialize/recover/check"
```

---

## Task 4: Implement `serialize_state` (TDD via `utils/replace_probe`)

**Files:**
- Create: `utils/replace_probe/reef.toml`
- Create: `utils/replace_probe/src/main.reef`
- Modify: `src/replace.reef` (replace the stub `serialize_state` body)

Round-trip is verified in Task 5 (after `recover_state` is implemented). For now, the probe just calls `serialize_state` against a synthetic table and dumps the resulting file to stdout for visual inspection.

- [ ] **Step 1: Scaffold `utils/replace_probe/`**

Create `utils/replace_probe/reef.toml`:

```toml
[package]
name = "replace_probe"
version = "0.1.0"
author = "Chris Tusa <chris.tusa@leafscale.com>"
description = "Unit-test probe for zyginit live-replace state-file format"
license = "CDDL-1.0"

[build]
entry = "src/main.reef"
output = "replace_probe"
output_dir = "build"
source_dirs = ["src", "../../src"]

# This probe round-trips state.toml serialization without needing a
# running zyginit. Models utils/contract_probe.
#
# Linux: clang -c ../../src/helpers.c -o build/helpers.o && \
#        clang -c ../../src/contract_linux_stubs.c -o build/contract_linux_stubs.o && \
#        reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Create `utils/replace_probe/src/main.reef` (test harness — exercises serialize and, in Task 5, also recover):

```reef
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ `/ /_/ ___/ ___/ __ `/ / _ \
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zyginit
   Filename: main.reef
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Probe — round-trip the state.toml format through replace.reef

******************************************************************************/

import config
import supervisor
import replace
import core.str
import sys.env as sysenv

mut g_pass: int = 0
mut g_fail: int = 0

proc check(label: string, ok: bool)
    if ok
        g_pass = g_pass + 1
        println("  PASS: " + label)
    else
        g_fail = g_fail + 1
        println("  FAIL: " + label)
    end if
end check

// Build a synthetic ServiceTable with known data. Uses minimal
// ServiceDef fields — enough for serialize/recover round-trip.
fn build_synthetic_table(): supervisor.ServiceTable
    let table = supervisor.new_service_table(8)

    // sshd: RUNNING with restart_count=2 and last_exit_code=0
    let def_sshd = config.new_service_def_minimal("sshd")
    let idx_sshd = supervisor.add_service(table, def_sshd)
    supervisor.set_runtime_for_test(table, idx_sshd, supervisor.STATE_RUNNING(),
        100, 23, 2, 0, 1746204051)

    // syslogd: RUNNING with no restarts
    let def_syslog = config.new_service_def_minimal("syslogd")
    let idx_syslog = supervisor.add_service(table, def_syslog)
    supervisor.set_runtime_for_test(table, idx_syslog, supervisor.STATE_RUNNING(),
        101, 17, 0, 0 - 1, 1746204047)

    // cron: STOPPED — must NOT be serialized
    let def_cron = config.new_service_def_minimal("cron")
    let idx_cron = supervisor.add_service(table, def_cron)
    supervisor.set_runtime_for_test(table, idx_cron, supervisor.STATE_STOPPED(),
        0 - 1, 0 - 1, 0, 0, 0)

    return table
end build_synthetic_table

proc test_serialize()
    println("== serialize_state ==")

    // Use $TMPDIR to avoid touching /var/run during dev tests.
    let tmpdir = sysenv.get_env_or("TMPDIR", "/tmp")
    sysenv.set_env("ZYGINIT_RUN_DIR", str.concat(tmpdir, "/replace_probe"))

    let table = build_synthetic_table()
    let ok = replace.serialize_state(table, 1746204000)
    check("serialize returns true on writable dir", ok)

    // (Round-trip assertions added in Task 5.)
end test_serialize

proc main()
    test_serialize()

    println("")
    println("--- " + int_to_str(g_pass) + " passed, " + int_to_str(g_fail) + " failed ---")
    if g_fail > 0
        sysenv.exit(1)
    end if
end main

fn int_to_str(n: int): string
    if n == 0
        return "0"
    end if
    mut value = n
    mut neg = false
    if n < 0
        value = 0 - n
        neg = true
    end if
    mut result = ""
    while value > 0
        let digit = value % 10
        result = str.concat(str.substring("0123456789", digit, 1), result)
        value = value / 10
    end while
    if neg
        result = str.concat("-", result)
    end if
    return result
end int_to_str
```

The probe references three new helpers in `supervisor` and `config` that don't exist yet:
- `config.new_service_def_minimal(name): ServiceDef` — constructs a ServiceDef with `name` set and other fields at default. Add it as a tiny `#[cfg(test)]`-equivalent helper at the bottom of `config.reef`'s export block, but unconditionally exported (Reef has no cfg-test gate).
- `supervisor.set_runtime_for_test(table, idx, state, pid, ctid, restarts, last_exit, last_start)` — directly writes the runtime fields on a `ServiceRuntime`, bypassing the normal start/stop lifecycle. Add to `supervisor.reef`'s export block.

- [ ] **Step 2: Add `config.new_service_def_minimal` to `src/config.reef`**

Locate the export block in `src/config.reef`, add the line `fn new_service_def_minimal(name: string): ServiceDef` to it. Find the place where `ServiceDef` is constructed (search for `ServiceDef{`) and add this fn body near it:

```reef
// Test/probe helper — minimal ServiceDef used by utils/replace_probe.
// Not used by production zyginit code paths.
fn new_service_def_minimal(name: string): ServiceDef
    return ServiceDef{
        name: name,
        description: "",
        type_: SERVICE_TYPE_DAEMON(),
        start_cmd: "/bin/true",
        stop_cmd: "",
        working_dir: "",
        user: "",
        group: "",
        environment: new [string](0),
        environment_count: 0,
        stop_method: STOP_METHOD_CONTRACT(),
        stop_signal: "TERM",
        stop_timeout: 60,
        requires: new [string](0),
        requires_count: 0,
        after: new [string](0),
        after_count: 0,
        contract_params: 0,
        contract_fatal: 0,
        restart_policy: RESTART_FAILURE(),
        restart_delay: 5,
        max_retries: 0 - 1,
        runlevel_mode: RUNLEVEL_MODE_MULTI()
    }
end new_service_def_minimal
```

Field names and constants in this constructor must match the actual `ServiceDef` struct in `config.reef`. Open the file, find `type ServiceDef = struct`, and copy the field list verbatim — adjust the constructor above if names differ. (Some fields may not exist in the struct as written here; that's OK — adapt to the real fields.)

- [ ] **Step 3: Add `supervisor.set_runtime_for_test` to `src/supervisor.reef`**

Add to the export block: `proc set_runtime_for_test(table: ServiceTable, idx: int, state: int, pid: int, contract_id: int, restart_count: int, last_exit_code: int, last_start_time: int)`. Then add the body near the other accessors:

```reef
// Test/probe helper — directly write runtime fields on a ServiceRuntime,
// bypassing the normal start/stop lifecycle. Used only by
// utils/replace_probe; production code goes through start_service /
// handle_contract_event.
proc set_runtime_for_test(table: ServiceTable, idx: int, state: int, pid: int,
                          contract_id: int, restart_count: int,
                          last_exit_code: int, last_start_time: int)
    let rt = table.runtimes[idx]
    rt.state = state
    rt.pid = pid
    rt.contract_id = contract_id
    rt.restart_count = restart_count
    rt.last_exit_code = last_exit_code
    rt.last_start_time = last_start_time
    table.runtimes[idx] = rt

    // Also register contract mapping so apply_recovered_state can find
    // it later if the test exercises recovery.
    if contract_id >= 0
        table.contract_map.set(int_to_str_helper(contract_id), idx)
    end if
end set_runtime_for_test

// Local helper — int_to_str is private in this module; if not already
// present scan for it. (It exists at line ~870 as a private fn — reuse.)
fn int_to_str_helper(n: int): string
    return int_to_str(n)
end int_to_str_helper
```

- [ ] **Step 4: Implement `serialize_state` in `src/replace.reef`**

Replace the stub. The body opens a tmp file, writes the boot_time line then a `[[service]]` block per RUNNING service, fsyncs, closes, renames to the final path, fsyncs the parent dir.

```reef
fn serialize_state(table: supervisor.ServiceTable, boot_time: int): bool
    let tmp_path = STATE_TMP_PATH()
    let final_path = STATE_FILE_PATH()
    let dir_path = STATE_DIR()

    // O_WRONLY|O_CREAT|O_TRUNC = 0x301 on Hammerhead/Linux for the values
    // we use in fd.O_*. Using fd module's helpers keeps this portable.
    let flags = fd.O_WRONLY() + fd.O_CREAT() + fd.O_TRUNC()
    let out = fd.fd_open(tmp_path, flags, 384)   // mode 0600

    if out < 0
        println("replace: serialize: cannot open " + tmp_path)
        return false
    end if

    // Write boot_time header
    let header = str.concat("boot_time = ", int_to_str(boot_time))
    fd.fd_write(out, str.concat(header, "\n"))

    // Iterate services — only RUNNING ones go in. Skip the rest.
    let count = supervisor.service_count(table)
    mut i = 0
    while i < count
        let rt = supervisor.get_runtime(table, i)
        if supervisor.rt_state(rt) == supervisor.STATE_RUNNING()
            let def = supervisor.rt_def(rt)
            fd.fd_write(out, "\n[[service]]\n")
            fd.fd_write(out, str.concat("name = \"", str.concat(config.svc_name(def), "\"\n")))
            fd.fd_write(out, str.concat("contract_id = ", str.concat(int_to_str(supervisor.rt_contract_id(rt)), "\n")))
            fd.fd_write(out, str.concat("restart_count = ", str.concat(int_to_str(supervisor.rt_restart_count(rt)), "\n")))
            fd.fd_write(out, str.concat("last_start_time = ", str.concat(int_to_str(supervisor.rt_last_start_time(rt)), "\n")))
            fd.fd_write(out, str.concat("last_exit_code = ", str.concat(int_to_str(supervisor.rt_last_exit_code(rt)), "\n")))
        end if
        i = i + 1
    end while

    // fsync + close
    if fd.fd_fsync(out) < 0
        fd.fd_close(out)
        unlink(tmp_path)
        return false
    end if
    fd.fd_close(out)

    // Atomic rename
    if rename(tmp_path, final_path) != 0
        unlink(tmp_path)
        return false
    end if

    // fsync the parent dir so the rename is durable
    let _ = zyginit_fsync_path(dir_path)

    return true
end serialize_state

// Local int_to_str — same shape as in supervisor.reef. Replicate to
// keep the module standalone.
fn int_to_str(n: int): string
    if n == 0
        return "0"
    end if
    mut value = n
    mut neg = false
    if n < 0
        value = 0 - n
        neg = true
    end if
    mut result = ""
    while value > 0
        let digit = value % 10
        result = str.concat(str.substring("0123456789", digit, 1), result)
        value = value / 10
    end while
    if neg
        result = str.concat("-", result)
    end if
    return result
end int_to_str
```

The `fd.fd_fsync` call may not exist if Reef's `sys.fd` doesn't expose it — if reefc errors on that name, replace with a direct `extern "C" fn fsync(fd: int): int` declaration in this module and call it as `fsync(out)`.

- [ ] **Step 5: Build the main project to verify replace.reef compiles**

Run: `clang -c src/helpers.c -o build/helpers.o && clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o && reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o`
Expected: success.

- [ ] **Step 6: Build the probe**

Run:
```bash
cd utils/replace_probe
mkdir -p build
clang -c ../../src/helpers.c -o build/helpers.o
clang -c ../../src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
cd ../..
```
Expected: success.

- [ ] **Step 7: Run the probe and inspect the file**

Run:
```bash
mkdir -p /tmp/replace_probe
./utils/replace_probe/build/replace_probe
cat /tmp/replace_probe/state.toml
```

Expected:
- "PASS: serialize returns true on writable dir"
- File contents:
  ```
  boot_time = 1746204000

  [[service]]
  name = "sshd"
  contract_id = 23
  restart_count = 2
  last_start_time = 1746204051
  last_exit_code = 0

  [[service]]
  name = "syslogd"
  contract_id = 17
  restart_count = 0
  last_start_time = 1746204047
  last_exit_code = -1
  ```
- `cron` (STATE_STOPPED) is **not** in the output.

- [ ] **Step 8: Commit**

```bash
hg add utils/replace_probe/reef.toml utils/replace_probe/src/main.reef
hg commit -m "replace: implement serialize_state + replace_probe round-trip harness"
```

---

## Task 5: Implement `recover_state` (TDD via `utils/replace_probe`)

**Files:**
- Modify: `src/replace.reef` (replace the stub `recover_state` body)
- Modify: `utils/replace_probe/src/main.reef` (add round-trip + edge-case assertions)

`recover_state` reads the state.toml file via the existing `encoding.toml` parser, validates `boot_time`, and returns either an empty `RecoveredState` (if file missing/corrupt/stale) or a populated one. The empty/stale path also deletes the file.

- [ ] **Step 1: Implement `recover_state`**

Replace the stub in `src/replace.reef`:

```reef
fn recover_state(current_boot_time: int): RecoveredState
    let path = STATE_FILE_PATH()

    if not file.fileExists(path)
        return new_recovered_state()
    end if

    let content = file.readFile(path)
    if str.length(content) == 0
        // Treat empty as missing
        let _ = unlink(path)
        return new_recovered_state()
    end if

    // Parse via encoding.toml. Section-array entries flatten to
    // dotted-key arrays; the parser exposes them via toml.get_array.
    // The helper below wraps a parse + extraction.
    let parsed = toml.parse(content)
    if not toml.parse_ok(parsed)
        println("replace: recover: parse error in " + path + " — ignoring")
        let _ = unlink(path)
        return new_recovered_state()
    end if

    let saved_boot = toml.get_int_or(parsed, "boot_time", 0 - 1)
    if saved_boot != current_boot_time or current_boot_time < 0
        println("replace: recover: stale state file (boot_time " + int_to_str(saved_boot) +
                " != current " + int_to_str(current_boot_time) + "); ignoring")
        let _ = unlink(path)
        return new_recovered_state()
    end if

    let n = toml.array_count(parsed, "service")
    let arr = new [RecoveredService](n)
    mut i = 0
    while i < n
        let prefix = str.concat("service.", int_to_str(i))
        arr[i] = RecoveredService{
            name: toml.get_string_or(parsed, str.concat(prefix, ".name"), ""),
            contract_id: toml.get_int_or(parsed, str.concat(prefix, ".contract_id"), 0 - 1),
            restart_count: toml.get_int_or(parsed, str.concat(prefix, ".restart_count"), 0),
            last_start_time: toml.get_int_or(parsed, str.concat(prefix, ".last_start_time"), 0),
            last_exit_code: toml.get_int_or(parsed, str.concat(prefix, ".last_exit_code"), 0 - 1)
        }
        i = i + 1
    end while

    // State file consumed — delete to avoid panic-restart loops.
    let _ = unlink(path)

    return RecoveredState{
        boot_time: saved_boot,
        services: arr,
        count: n
    }
end recover_state
```

The `toml.parse_ok`, `toml.get_int_or`, `toml.get_string_or`, `toml.array_count` helper names are placeholders — open `~/repos/reef-lang/stdlib/encoding/toml.reef` (or wherever the project's encoding.toml lives — try `grep -rn 'module toml' ~/repos/reef-lang/`) and use the actual function names. The existing `config.load_enabled_services` in `src/config.reef` is a working example of how to walk a parsed TOML array — copy its access pattern verbatim if the helper names above don't exist.

- [ ] **Step 2: Extend the probe with round-trip + edge-case assertions**

Replace `test_serialize()` in `utils/replace_probe/src/main.reef` with:

```reef
proc test_round_trip()
    println("== round-trip ==")
    let tmpdir = sysenv.get_env_or("TMPDIR", "/tmp")
    sysenv.set_env("ZYGINIT_RUN_DIR", str.concat(tmpdir, "/replace_probe"))

    // Make sure the state dir exists
    let _ = io.dir.create_dir_all(str.concat(tmpdir, "/replace_probe"))

    let table = build_synthetic_table()
    let serialized = replace.serialize_state(table, 1746204000)
    check("serialize returns true", serialized)

    let recovered = replace.recover_state(1746204000)
    check("recover boot_time matches", replace.rs_boot_time(recovered) == 1746204000)
    check("recover count == 2 (running only)", replace.rs_count(recovered) == 2)

    // Find services by name (order is implementation-defined)
    mut found_sshd = false
    mut found_syslog = false
    mut i = 0
    while i < replace.rs_count(recovered)
        let svc = replace.rs_service(recovered, i)
        let name = replace.svc_name(svc)
        if name == "sshd"
            found_sshd = true
            check("sshd contract_id = 23", replace.svc_contract_id(svc) == 23)
            check("sshd restart_count = 2", replace.svc_restart_count(svc) == 2)
            check("sshd last_exit_code = 0", replace.svc_last_exit_code(svc) == 0)
        elif name == "syslogd"
            found_syslog = true
            check("syslogd contract_id = 17", replace.svc_contract_id(svc) == 17)
            check("syslogd last_exit_code = -1", replace.svc_last_exit_code(svc) == 0 - 1)
        end if
        i = i + 1
    end while
    check("found sshd", found_sshd)
    check("found syslogd", found_syslog)

    // After recover_state, state.toml is deleted
    check("state.toml deleted after recovery", not io.file.fileExists(replace.STATE_FILE_PATH()))
end test_round_trip

proc test_stale_boot_time()
    println("== stale state file ==")
    let tmpdir = sysenv.get_env_or("TMPDIR", "/tmp")
    sysenv.set_env("ZYGINIT_RUN_DIR", str.concat(tmpdir, "/replace_probe"))

    let table = build_synthetic_table()
    let _ = replace.serialize_state(table, 1746204000)

    // Recover with DIFFERENT boot_time -> stale -> empty + deleted
    let recovered = replace.recover_state(1746999999)
    check("stale file -> empty state", replace.rs_is_empty(recovered))
    check("stale file deleted", not io.file.fileExists(replace.STATE_FILE_PATH()))
end test_stale_boot_time

proc test_missing_file()
    println("== missing state file ==")
    let tmpdir = sysenv.get_env_or("TMPDIR", "/tmp")
    sysenv.set_env("ZYGINIT_RUN_DIR", str.concat(tmpdir, "/replace_probe_missing"))

    // Make sure file definitely doesn't exist
    let _ = io.dir.create_dir_all(str.concat(tmpdir, "/replace_probe_missing"))
    let _ = unlink(replace.STATE_FILE_PATH())

    let recovered = replace.recover_state(1746204000)
    check("missing file -> empty state", replace.rs_is_empty(recovered))
end test_missing_file

extern "C" fn unlink(path: string): int

proc main()
    test_round_trip()
    test_stale_boot_time()
    test_missing_file()

    println("")
    println("--- " + int_to_str(g_pass) + " passed, " + int_to_str(g_fail) + " failed ---")
    if g_fail > 0
        sysenv.exit(1)
    end if
end main
```

Add `import io.dir` and `import io.file` near the top of the probe.

- [ ] **Step 3: Build and run**

Run:
```bash
cd utils/replace_probe
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./build/replace_probe
cd ../..
```

Expected output ends with `--- 11 passed, 0 failed ---` (1 from serialize + 10 from round_trip / stale / missing — adjust if asserts differ).

If it fails, the most likely cause is the TOML parser helper names. Read `encoding.toml`'s actual API and adjust `recover_state`.

- [ ] **Step 4: Commit**

```bash
hg commit -m "replace: implement recover_state with round-trip + edge-case probe tests"
```

---

## Task 6: Implement `check_preconditions` (TDD)

**Files:**
- Modify: `src/replace.reef` (replace the stub `check_preconditions`)
- Modify: `utils/replace_probe/src/main.reef` (add precondition tests)

- [ ] **Step 1: Implement**

Replace the stub:

```reef
fn check_preconditions(table: supervisor.ServiceTable): string
    let count = supervisor.service_count(table)
    mut report = ""
    mut found = 0
    mut i = 0
    while i < count
        let rt = supervisor.get_runtime(table, i)
        let st = supervisor.rt_state(rt)
        if st == supervisor.STATE_STARTING() or st == supervisor.STATE_STOPPING() or st == supervisor.STATE_WAITING()
            let entry = str.concat(config.svc_name(supervisor.rt_def(rt)),
                str.concat(":", supervisor.state_name(st)))
            if found > 0
                report = str.concat(report, ", ")
            end if
            report = str.concat(report, entry)
            found = found + 1
        end if
        i = i + 1
    end while
    return report
end check_preconditions
```

Note: `STATE_WAITING` is currently used both for "not yet started" services at boot and for "scheduled-for-restart". For the precondition check we want only the latter (a transient mid-restart state) — but the state machine doesn't distinguish them. Conservative: treat all WAITING as transient. Operators using `replace` on a fresh boot before services have started would otherwise see "blocked"; that's an acceptable false positive.

- [ ] **Step 2: Add probe assertions**

Append to `utils/replace_probe/src/main.reef`:

```reef
proc test_preconditions()
    println("== preconditions ==")
    let table = supervisor.new_service_table(8)

    // sshd RUNNING — stable
    let def_sshd = config.new_service_def_minimal("sshd")
    let idx_sshd = supervisor.add_service(table, def_sshd)
    supervisor.set_runtime_for_test(table, idx_sshd, supervisor.STATE_RUNNING(),
        100, 23, 0, 0 - 1, 1746204051)

    let r1 = replace.check_preconditions(table)
    check("all-RUNNING -> empty report", str.length(r1) == 0)

    // Add a STOPPING service
    let def_cron = config.new_service_def_minimal("cron")
    let idx_cron = supervisor.add_service(table, def_cron)
    supervisor.set_runtime_for_test(table, idx_cron, supervisor.STATE_STOPPING(),
        101, 24, 0, 0 - 1, 1746204060)

    let r2 = replace.check_preconditions(table)
    check("STOPPING -> non-empty report", str.length(r2) > 0)
    check("report mentions cron", str.index_of(r2, "cron") >= 0)
    check("report mentions stopping", str.index_of(r2, "stopping") >= 0)
end test_preconditions
```

Add `test_preconditions()` to `proc main()`.

- [ ] **Step 3: Build and run**

Run:
```bash
cd utils/replace_probe
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./build/replace_probe
cd ../..
```

Expected: tests pass.

- [ ] **Step 4: Commit**

```bash
hg commit -m "replace: implement check_preconditions with transient-state detection"
```

---

## Task 7: Add `contract.is_contract_empty` helper

**Files:**
- Modify: `src/contract.reef`
- Modify: `src/contract_linux_stubs.c`

`is_contract_empty(ctid)` reads contract status via `ct_status_read` on `/system/contract/process/<id>/status`, then checks the member-count via `ct_status_get_nmembers`. Returns `true` if the contract has zero members (or the status read fails — caller treats unknown as "assume empty for safety").

- [ ] **Step 1: Add the FFI for nmembers and the helper**

In `src/contract.reef`, add to the FFI declarations near the other `ct_status_*` lines:

```reef
extern "C" fn ct_status_get_nmembers(stathdl: pointer): int
```

Add to the export block:

```reef
fn is_contract_empty(contract_id: int): bool
```

Add the body near `adopt_contract`:

```reef
// Check whether a contract has zero member processes. Used by the
// post-recovery idempotency step in main.apply_recovered_state — if a
// contract was reported in state.toml but the kernel says it's empty,
// the service exited during the exec gap and we should apply restart
// policy as if a contract-empty event arrived.
//
// Returns true if the contract has zero members OR if the status
// read fails (treat unknown as empty so the recovery path applies
// restart policy rather than leaving a phantom service in RUNNING).
fn is_contract_empty(contract_id: int): bool
    let status_path = str.concat(str.concat("/system/contract/process/", int_to_str(contract_id)), "/status")
    let st_fd = open(status_path, O_RDONLY())
    if st_fd < 0
        return true
    end if

    unsafe
        let stathdl_buf = new [pointer](1)
        let rc = ct_status_read(st_fd, CTD_COMMON(), stathdl_buf)
        close(st_fd)

        if rc != 0
            return true
        end if

        let stathdl = stathdl_buf[0]
        let nmembers = ct_status_get_nmembers(stathdl)
        ct_status_free(stathdl)

        return nmembers == 0
    end unsafe
end is_contract_empty
```

- [ ] **Step 2: Add the Linux stub**

In `src/contract_linux_stubs.c`, append:

```c
int ct_status_get_nmembers(void *stathdl) { (void)stathdl; return 0; }
```

- [ ] **Step 3: Build**

Run: `clang -c src/helpers.c -o build/helpers.o && clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o && reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o`
Expected: success.

- [ ] **Step 4: Commit**

```bash
hg commit -m "contract: add is_contract_empty helper for post-recovery empty-contract check"
```

---

## Task 8: Add socket `replace` command + flag plumbing

**Files:**
- Modify: `src/socket.reef`

Add a `g_replace_requested` flag and a `g_replace_wait` int, accessors, and the command handler. Mirror the existing `g_reload_requested` pattern.

- [ ] **Step 1: Add accessors to the export block**

In `src/socket.reef`, add to the existing export block (near `reload_requested` line 37):

```reef
    fn replace_requested(): bool
    proc clear_replace_flag()
    fn replace_wait_seconds(): int
```

- [ ] **Step 2: Add the globals and accessors**

Near the existing `mut g_reload_requested: bool = false` declaration (around line 49), add:

```reef
// Replace flag — set by "replace" command, checked by main event loop
mut g_replace_requested: bool = false
mut g_replace_wait: int = 0

fn replace_requested(): bool
    return g_replace_requested
end replace_requested

proc clear_replace_flag()
    g_replace_requested = false
    g_replace_wait = 0
end clear_replace_flag

fn replace_wait_seconds(): int
    return g_replace_wait
end replace_wait_seconds
```

- [ ] **Step 3: Add the command handler in `dispatch_command`**

Insert in `dispatch_command` (around line 184, after the reload branch):

```reef
    elif command == "replace"
        // Optional --wait=N argument
        mut wait_seconds = 0
        if str.length(arg) > 0
            // Parse --wait=N
            if str.starts_with(arg, "--wait=")
                let val = str.substring(arg, 7, str.length(arg) - 7)
                wait_seconds = parse_int_or(val, 0)
            else
                return "error: replace: unknown argument: " + arg + "\n"
            end if
        end if
        g_replace_requested = true
        g_replace_wait = wait_seconds
        return str.concat("replace queued (wait=", str.concat(int_to_str(wait_seconds), ")\n"))
```

- [ ] **Step 4: Add the `parse_int_or` helper if not present**

Search for it: `grep -n 'parse_int_or\|fn parse_int' src/socket.reef`. If absent, add at the bottom of the file:

```reef
fn parse_int_or(s: string, default_val: int): int
    let n = str.length(s)
    if n == 0
        return default_val
    end if
    mut result = 0
    mut i = 0
    while i < n
        let c = str.char_at(s, i)
        if c < '0' or c > '9'
            return default_val
        end if
        result = result * 10 + (c - '0')
        i = i + 1
    end while
    return result
end parse_int_or
```

If `str.starts_with` doesn't exist, write it inline using `str.substring(arg, 0, 7) == "--wait="`.

- [ ] **Step 5: Update the `cmd_help` line to mention replace**

Find `cmd_help` (around line 413) and add `replace [--wait=N]` to the comma-separated command list.

- [ ] **Step 6: Build**

Run: full Linux build command.
Expected: success.

- [ ] **Step 7: Smoke test the socket command**

Run:
```bash
TEST=$(mktemp -d)
ZYGINIT_CONFIG_DIR=$TEST/cfg ZYGINIT_SOCKET=$TEST/sock ZYGINIT_LOG_DIR=$TEST/log mkdir -p $TEST/cfg/enabled.d
ZYGINIT_CONFIG_DIR=$TEST/cfg ZYGINIT_SOCKET=$TEST/sock ZYGINIT_LOG_DIR=$TEST/log ./build/zyginit &
ZPID=$!
sleep 0.5
echo 'replace --wait=10' | nc -U $TEST/sock
kill $ZPID 2>/dev/null
rm -rf $TEST
```

Expected: `replace queued (wait=10)`. (Don't worry that the daemon doesn't actually replace — the actual flow lands in Task 11 once `replace_self` is wired up. This test only verifies the command parses and the flag is set.)

- [ ] **Step 8: Commit**

```bash
hg commit -m "socket: add replace [--wait=N] command + flag plumbing"
```

---

## Task 9: Add `apply_recovered_state` proc in `main.reef`

**Files:**
- Modify: `src/main.reef`

This is the incoming-side stitching logic. For each entry in the recovered state, find the service by name, populate runtime fields, register the contract_map entry, and run the post-recovery `is_contract_empty` check.

- [ ] **Step 1: Add the proc near `reload_services`**

Find `reload_services` (around line 328) and insert before it:

```reef
// Apply state from a previous zyginit instance (live-replace).
// For each entry in `recovered`, locate the service in `table` and
// patch in runtime fields. Services in state.toml that are no longer
// in enabled.d/ get their contract abandoned but their member
// processes left running. After patching, run the post-recovery
// empty-contract check to catch services that exited during the
// exec gap.
proc apply_recovered_state(table: supervisor.ServiceTable,
                           recovered: replace.RecoveredState)
    if replace.rs_is_empty(recovered)
        return
    end if

    let n = replace.rs_count(recovered)
    println("zyginit: replace: applying " + int_to_str(n) + " recovered services")

    mut i = 0
    while i < n
        let rs = replace.rs_service(recovered, i)
        let name = replace.svc_name(rs)
        let ctid = replace.svc_contract_id(rs)

        let idx = supervisor.find_service(table, name)
        if idx < 0
            // Operator removed the symlink between old start and replace.
            // Don't kill — abandon the contract; member processes
            // continue running unsupervised.
            let abrc = contract.abandon_contract(ctid)
            println("zyginit: replace: orphaned " + name +
                    " (no longer enabled, contract " + int_to_str(ctid) +
                    " abandon rc=" + int_to_str(abrc) + ")")
            i = i + 1
            continue
        end if

        // Patch runtime fields. PID is unknown (not serialized); contract
        // path is sufficient for supervision.
        supervisor.set_runtime_for_test(table, idx, supervisor.STATE_RUNNING(),
            0 - 1, ctid,
            replace.svc_restart_count(rs),
            replace.svc_last_exit_code(rs),
            replace.svc_last_start_time(rs))

        println("zyginit: replace: re-attached " + name +
                " (ctid=" + int_to_str(ctid) +
                ", restarts=" + int_to_str(replace.svc_restart_count(rs)) + ")")

        // Idempotency: did the contract go empty during the exec gap?
        if contract.is_contract_empty(ctid)
            println("zyginit: replace: " + name +
                    " contract empty post-recovery, applying restart policy")
            supervisor.handle_contract_event(table, ctid, 0 - 1)
        end if

        i = i + 1
    end while
end apply_recovered_state
```

`supervisor.set_runtime_for_test` is the same helper added in Task 4 — its name communicates "test/probe usage" but it does exactly what `apply_recovered_state` needs (write the runtime fields directly). Acceptable. If the name bothers you, rename to `supervisor.adopt_runtime` and update both call sites.

- [ ] **Step 2: Add the import at the top of `main.reef`**

Find the imports block (top of file). Add:

```reef
import replace
```

- [ ] **Step 3: Build**

Run: full Linux build.
Expected: success.

- [ ] **Step 4: Commit**

```bash
hg commit -m "main: add apply_recovered_state proc for live-replace stitching"
```

---

## Task 10: Add `replace_self` proc in `main.reef`

**Files:**
- Modify: `src/main.reef`

The outgoing-side flow. Pre-condition check (with optional `--wait` poll), state-file write, socket unlink, exec.

- [ ] **Step 1: Add FFI and helpers near the top of `main.reef`**

If not already present, add to the extern block:

```reef
extern "C" fn zyginit_fsync_path(path: string): int
extern "C" fn unlink(path: string): int
```

- [ ] **Step 2: Add the proc near `apply_recovered_state`**

```reef
// Operator-driven live replace. Triggered by zygctl replace; the
// socket handler sets g_replace_requested and we pick it up on the
// next event-loop tick. After this returns successfully, control
// transfers to the new /sbin/init process; this fn does not return
// on success.
//
// On precondition failure or any I/O error before exec, we log and
// return false; the caller clears the flag and continues normally.
proc replace_self(table: supervisor.ServiceTable, boot_time: int, wait_seconds: int)
    println("zyginit: replace: requested (wait=" + int_to_str(wait_seconds) + ")")

    // Pre-condition check, with optional wait window
    mut elapsed = 0
    mut report = replace.check_preconditions(table)
    while str.length(report) > 0 and elapsed < wait_seconds
        clock.sleep_seconds(1)
        elapsed = elapsed + 1
        report = replace.check_preconditions(table)
    end while

    if str.length(report) > 0
        println("zyginit: replace: blocked: " + report)
        return
    end if

    // Final draining of pending contract events — services may have just
    // exited and their state hasn't been recorded yet.
    // (Reuse the existing handle_contract_events drain logic if exposed;
    // otherwise the post-recovery is_contract_empty check on the new
    // side covers any miss.)

    // Serialize state
    if not replace.serialize_state(table, boot_time)
        println("zyginit: replace: state serialization failed; aborting")
        return
    end if
    println("zyginit: replace: state written to " + replace.STATE_FILE_PATH())

    // Unlink socket. Proceed even on failure — new zyginit will overwrite.
    // zyginit_fsync_path falls back to fsyncing the parent dir when
    // the path itself doesn't exist, which is exactly what we want
    // after unlink — the socket's parent dir gets the rename committed.
    let sock_path = SOCKET_PATH()
    let urc = unlink(sock_path)
    if urc != 0
        println("zyginit: replace: warning: socket unlink failed (rc=" + int_to_str(urc) + ")")
    end if
    let _ = zyginit_fsync_path(sock_path)

    // Exec /sbin/init. argv[0] should match what the kernel originally
    // exec'd us with; we pass "/sbin/init" verbatim.
    let target = "/sbin/init"
    let argv = new [string](1)
    argv[0] = target

    println("zyginit: replace: execve " + target)
    process.process_exec(target, argv)

    // If we reach here, exec failed. We have already written state.toml
    // and unlinked the socket — recovery requires reboot.
    println("zyginit: replace: FATAL: execve returned (kernel could not load " + target + ")")
end replace_self
```

The "drain pending contract events" comment block is intentional — the current code path for handling bundle events lives in the main loop. If you want to drain them once more here, factor that out into a `proc drain_bundle_events(table, bundle_fd)` and call it; otherwise rely on the post-recovery `is_contract_empty` check (which is sufficient per the spec).

- [ ] **Step 3: Build**

Expected: success.

- [ ] **Step 4: Commit**

```bash
hg commit -m "main: add replace_self proc for live-replace outgoing flow"
```

---

## Task 11: Wire `main.reef` startup + event loop

**Files:**
- Modify: `src/main.reef`

Two integration points:
- **Startup:** call `replace.recover_state` and `apply_recovered_state` between Phase 3 (table built) and Phase 6 (start_services_by_tier).
- **Event loop:** check `socket.replace_requested()` and call `replace_self`.

Also: capture `g_boot_time` once during PID-1 init so it's available to both call sites.

- [ ] **Step 1: Add `g_boot_time` global**

Near the top of `main.reef` with the other `mut g_*` globals, add:

```reef
mut g_boot_time: int = 0 - 1
```

- [ ] **Step 2: Capture boot_time at the start of `main()` after writing the BOOT_TIME utmpx record**

Right after the existing `let _ = zyginit_write_boot_utmpx()` at line ~725:

```reef
        // Cache the BOOT_TIME we just wrote so live-replace can use
        // it as the boot-id sentinel. Read it back from utmpx (rather
        // than time_now() locally) so the value matches what the new
        // zyginit will read after exec.
        g_boot_time = replace.read_boot_time()
        if g_boot_time < 0
            // Fallback: use time_now(). This degrades the staleness
            // check (a real reboot might collide if seconds-resolution
            // happens to repeat), but it's better than refusing all
            // replaces.
            g_boot_time = time.time_now()
            println("zyginit: warning: utmpx BOOT_TIME read failed; using time_now() = " + int_to_str(g_boot_time))
        end if
```

For non-PID-1 supervisor mode, `g_boot_time` stays at -1; replace.serialize_state still writes "-1" and the new instance reads "-1" — they match, and the path is intentionally permissive in supervisor mode.

Actually — set it for non-PID-1 too:

```reef
    // (After the if is_pid_1() block)
    if g_boot_time < 0
        g_boot_time = time.time_now()
    end if
```

- [ ] **Step 3: Insert recovery between Phase 3 and Phase 6**

After the `i + 1` add_service loop (around line 778) and before signal init:

```reef
    // ---- Phase 3.5: Apply state from previous zyginit (live replace) ----

    let recovered = replace.recover_state(g_boot_time)
    if not replace.rs_is_empty(recovered)
        apply_recovered_state(table, recovered)
    end if
```

This lands AFTER `add_service` so all services are registered, BEFORE `start_services_by_tier` so re-attached services are skipped (they're in `STATE_RUNNING` and `start_service` only acts on `STATE_WAITING`).

- [ ] **Step 4: Add the replace check in the main event loop**

Find the existing reload check (around line 858-862):

```reef
        // Check for reload requested via socket
        if socket.reload_requested()
            socket.clear_reload_flag()
            println("zyginit: reload requested via socket")
            reload_services(table)
        end if
```

Add immediately after:

```reef
        // Check for replace requested via socket
        if socket.replace_requested()
            let wait = socket.replace_wait_seconds()
            socket.clear_replace_flag()
            replace_self(table, g_boot_time, wait)
            // If replace_self exec'd successfully, we never get here.
            // If it returned, log and continue running normally.
        end if
```

- [ ] **Step 5: Build the project AND zygctl**

Run:
```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```
Expected: success, `build/zyginit` produced.

- [ ] **Step 6: Smoke test in supervisor mode**

```bash
TEST=$(mktemp -d)
mkdir -p $TEST/cfg/enabled.d $TEST/log
ZYGINIT_CONFIG_DIR=$TEST/cfg ZYGINIT_SOCKET=$TEST/sock ZYGINIT_LOG_DIR=$TEST/log ZYGINIT_RUN_DIR=$TEST/run ./build/zyginit > $TEST/zyginit.log 2>&1 &
ZPID=$!
sleep 0.5
echo 'replace' | nc -U $TEST/sock
sleep 0.5
# zyginit should have logged "zyginit: replace: state written..." and
# attempted execve /sbin/init (which fails on Linux dev because
# /sbin/init isn't this binary). Acceptable failure.
cat $TEST/zyginit.log
kill $ZPID 2>/dev/null
rm -rf $TEST
```

Expected log lines:
- `zyginit: replace: requested (wait=0)`
- `zyginit: replace: state written to /tmp/.../state.toml` (or the ZYGINIT_RUN_DIR you set)
- `zyginit: replace: execve /sbin/init`
- `zyginit: replace: FATAL: execve returned ...` (only if /sbin/init isn't usable as a Linux binary in this dev environment)

The integration test will refine this in Task 13.

- [ ] **Step 7: Commit**

```bash
hg commit -m "main: wire live-replace into startup recovery and event loop"
```

---

## Task 12: Add `zygctl replace` subcommand

**Files:**
- Modify: `tools/zygctl/src/zygctl.reef`

- [ ] **Step 1: Locate the command dispatch**

Open `tools/zygctl/src/zygctl.reef` and find the dispatch (search for `"reload"` — there'll be a similar pattern for the existing socket-relayed commands).

- [ ] **Step 2: Add `replace` to the dispatch**

Pattern: build the command line (`replace` + optional `--wait=N`), connect to socket, send, read response, print, handle `EPIPE` / connection-closed cleanly.

```reef
    elif cmd == "replace"
        // Optional --wait=N
        mut payload = "replace"
        let argc = sys.args.count()
        if argc >= 3
            let wait_arg = sys.args.get(2)
            if str.starts_with(wait_arg, "--wait=")
                payload = str.concat(payload, str.concat(" ", wait_arg))
            else
                println("zygctl: replace: unknown argument: " + wait_arg)
                println("zygctl: usage: zygctl replace [--wait=N]")
                process.exit_now(2)
            end if
        end if

        let response = send_command(payload)
        if str.length(response) == 0
            // Connection closed without a response — the server proceeded
            // to exec immediately. Treat as success.
            println("replace: socket closed (process replaced)")
        else
            print(response)
        end if
```

`send_command` is the existing helper that connects to the socket and reads the response — adapt to whatever name is in use. If the existing pattern doesn't gracefully handle "connection closed without bytes received", treat that as a successful replace and print the documented message.

- [ ] **Step 3: Update help text**

Find the help text in zygctl.reef (likely a `cmd_help` proc) and add `replace [--wait=N]` to the list.

- [ ] **Step 4: Build zygctl**

Run:
```bash
cd tools/zygctl
clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o
reefc build --obj build/symlink_wrapper.o
cd ../..
```

Expected: success, `tools/zygctl/build/zygctl` produced.

- [ ] **Step 5: Smoke test**

```bash
TEST=$(mktemp -d)
mkdir -p $TEST/cfg/enabled.d $TEST/log
ZYGINIT_CONFIG_DIR=$TEST/cfg ZYGINIT_SOCKET=$TEST/sock ZYGINIT_LOG_DIR=$TEST/log ZYGINIT_RUN_DIR=$TEST/run ./build/zyginit > $TEST/zyginit.log 2>&1 &
ZPID=$!
sleep 0.5
ZYGINIT_SOCKET=$TEST/sock ./tools/zygctl/build/zygctl replace --wait=5
sleep 0.5
cat $TEST/zyginit.log
kill $ZPID 2>/dev/null
rm -rf $TEST
```

Expected zygctl output: `replace queued (wait=5)` OR `replace: socket closed (process replaced)`.

- [ ] **Step 6: Commit**

```bash
hg commit -m "zygctl: add replace [--wait=N] subcommand"
```

---

## Task 13: Linux integration smoke tests

**Files:**
- Modify: `tests/integration/run_tests.sh`

Add new test scenarios after the existing tests. Linux can't exercise actual contract adoption (stubs return -1), but it CAN verify:
- `replace` command parses and acks
- Pre-condition failures are reported
- State file writes correctly
- The exec attempt fires (it'll fail because `/sbin/init` isn't this binary on a Linux dev box, but that's a known Linux-only failure)

- [ ] **Step 1: Locate where new test sections are appended in run_tests.sh**

`grep -n '^section ' tests/integration/run_tests.sh | tail` will show the existing section markers. Insert a new section block before the final summary.

- [ ] **Step 2: Add the replace command-parse test**

Append before the final summary:

```bash
section "replace command — basic parsing"

# Start a fresh zyginit
start_zyginit
mkdir -p "$TEST_DIR/run"
export ZYGINIT_RUN_DIR="$TEST_DIR/run"
restart_zyginit_with_run_dir() {
    stop_zyginit
    "$ZYGINIT" >> "$DAEMON_LOG" 2>&1 &
    DAEMON_PID=$!
    wait_for_socket
}
restart_zyginit_with_run_dir

# zygctl replace with no args
out=$("$ZYGCTL" replace 2>&1 || true)
assert_contains "$out" "replace queued" "replace acks with no args"

# zygctl replace --wait=10
out=$("$ZYGCTL" replace --wait=10 2>&1 || true)
assert_contains "$out" "replace queued (wait=10)" "replace acks with --wait=10"

# Check state.toml was written before exec attempt
sleep 0.2
if [ -f "$TEST_DIR/run/state.toml" ]; then
    pass "state.toml present after replace"
else
    # Either still waiting OR exec succeeded and the new instance deleted it.
    # Since /sbin/init exec fails on Linux dev, the file should still be there
    # if the test sequence was fast.
    fail "state.toml missing after replace" "file present" "missing"
fi

# Verify state.toml contents
if [ -f "$TEST_DIR/run/state.toml" ]; then
    out=$(cat "$TEST_DIR/run/state.toml")
    assert_contains "$out" "boot_time =" "state.toml has boot_time"
fi
```

You may need to adapt `start_zyginit` / `stop_zyginit` / `wait_for_socket` to use `ZYGINIT_RUN_DIR`. Check the existing helpers in run_tests.sh for the pattern.

- [ ] **Step 3: Add the precondition refusal test**

Append:

```bash
section "replace — refuses on transient state"

# Set up a service whose start.sh hangs for 10s, so the service stays
# in STATE_STARTING long enough for us to issue a replace.
mkdir -p "$BIN_DIR"
cat > "$BIN_DIR/slow-start.sh" <<'EOF'
#!/bin/sh
sleep 10
EOF
chmod +x "$BIN_DIR/slow-start.sh"

cat > "$ENABLED_DIR/slow.toml" <<EOF
[service]
name = "slow"
type = "daemon"

[exec]
start = "$BIN_DIR/slow-start.sh"

[restart]
on = "never"
EOF

ln -sf "$ENABLED_DIR/slow.toml" "$ENABLED_DIR/../slow.toml" 2>/dev/null || true

# Reload to pick up the new service
"$ZYGCTL" reload >/dev/null 2>&1
sleep 0.2

# Issue replace — should ack but be refused on the server side
out=$("$ZYGCTL" replace 2>&1 || true)
assert_contains "$out" "replace queued" "replace acks even when refused"

# Server should log "replace: blocked" since slow service is in STARTING
sleep 0.5
log=$(cat "$DAEMON_LOG")
assert_contains "$log" "replace: blocked" "server logs blocked refusal"
```

- [ ] **Step 4: Run the test suite**

Run: `tests/integration/run_tests.sh`
Expected: all existing tests pass (regression check) plus the new replace tests pass.

- [ ] **Step 5: Commit**

```bash
hg commit -m "tests: add Linux integration coverage for zygctl replace"
```

---

## Task 14: Hammerhead test plan + man page updates

**Files:**
- Create: `tests/integration/test_replace_hammerhead.md`
- Modify: `man/zygctl.8`
- Modify: `man/zyginit.8`

Hammerhead testing is manual — it requires `hh-prototest` and exercises the actual contract-driven supervision path. Document the test cases as a checklist the operator runs by hand.

- [ ] **Step 1: Create the Hammerhead test checklist**

Write `tests/integration/test_replace_hammerhead.md`:

````markdown
# Live Replace — Hammerhead Test Checklist

Manual checklist for validating `zygctl replace` on `hh-prototest`
(192.168.122.50). Companion to the spec at
`docs/superpowers/specs/2026-05-02-contract-readoption-design.md`.

## Build + deploy

```bash
# From dev host
scp src/replace.reef src/main.reef src/contract.reef src/socket.reef \
    src/contract_linux_stubs.c src/helpers.c \
    root@192.168.122.50:/root/zyginit/src/
scp tools/zygctl/src/zygctl.reef \
    root@192.168.122.50:/root/zyginit/tools/zygctl/src/

# On hh-prototest
ssh root@192.168.122.50 'cd /root/zyginit && \
    gcc -c src/helpers.c -o build/helpers.o && \
    reefc build -l contract --obj build/helpers.o && \
    cp build/zyginit /sbin/init.new && mv /sbin/init.new /sbin/init && \
    cd tools/zygctl && \
    gcc -c src/symlink_wrapper.c -o build/symlink_wrapper.o && \
    reefc build --obj build/symlink_wrapper.o && \
    cp build/zygctl /sbin/zygctl'
```

After the binary swap, the running zyginit is still the OLD one. The
first `zygctl replace` will swap to the new binary.

## Test cases

### 1. Smoke: replace into the same binary

- [ ] `zygctl status` — note all PIDs and ctids; capture uptimes
- [ ] `zygctl replace` — should print `replace queued (wait=0)` then close
- [ ] Wait ~1 second; `zygctl status` again
- [ ] **All services have the same PIDs** (kernel-level continuity)
- [ ] **All services have the same contract IDs**
- [ ] **Uptimes are continuous** (delta from last_start_time, not reset)
- [ ] **The SSH session driving this test is still alive**
- [ ] `who -b` and `who -r` still report the same boot_time / runlevel

### 2. Pre-condition refusal

- [ ] `zygctl restart sshd` (puts sshd briefly in STOPPING/STARTING)
- [ ] Immediately: `zygctl replace`
- [ ] Expect server log line: `zyginit: replace: blocked: sshd:stopping`
- [ ] Verify the running zyginit did NOT exec (check uptime via /proc/1/start)

### 3. `--wait=N` success

- [ ] `zygctl restart syslogd && zygctl replace --wait=10`
- [ ] Replace should succeed once syslogd stabilizes
- [ ] Confirm syslogd's restart_count incremented and is preserved post-replace

### 4. Dirty disable

- [ ] `rm /etc/zyginit/enabled.d/cron.toml`  (no `zygctl reload`)
- [ ] `zygctl replace`
- [ ] After replace, `zygctl status` does NOT list cron
- [ ] But: `pgrep cron` still shows the cron pid running (process not killed)
- [ ] Server log shows `zyginit: replace: orphaned cron`

### 5. Crash during exec gap

- [ ] Pick a service with `restart.on = "always"`, e.g. sshd
- [ ] `pkill -9 -f "sshd -D"` (or whatever the daemon's argv looks like)
- [ ] Within ~0.5 seconds: `zygctl replace`
- [ ] After replace, server log includes `zyginit: replace: sshd contract empty post-recovery, applying restart policy`
- [ ] sshd is restarted with restart_count incremented

### 6. Stale state.toml across real reboot

- [ ] `cp /var/run/zyginit/state.toml /tmp/saved-state.toml` while a replace
      hasn't been issued (file may not exist; create one by issuing replace
      first then copy quickly before the new zyginit deletes it)
- [ ] `zygctl reboot` (real reboot)
- [ ] After boot: `cp /tmp/saved-state.toml /var/run/zyginit/state.toml`
- [ ] Stop+start zyginit somehow OR observe that the next replace handles it
- [ ] Server log includes `replace: stale state file (boot_time ...)`
- [ ] state.toml is deleted after that read

### 7. Repeated replace

- [ ] Note sshd's restart_count and uptime
- [ ] `zygctl replace` × 5 in a row, ~5 seconds apart
- [ ] After all 5: restart_count is unchanged (replace doesn't bump it)
- [ ] Uptime is continuous from the original start (no resets)
- [ ] No leftover state.toml.tmp files in /var/run/zyginit/

## Reverting

If a replace puts the system in a bad state and SSH is still alive:

```bash
mv /sbin/init.bak /sbin/init  # if you saved the old binary
zygctl replace                # swap back to known-good
```

If SSH is dead but the VM is still running, `virsh reset hh-prototest`
will reboot. The new binary at /sbin/init persists (filesystem-level
swap), so a reboot uses the new binary cleanly — re-test from cold boot.
````

- [ ] **Step 2: Update `man/zygctl.8`**

Add a `replace` entry in the COMMANDS section. Example pattern (adapt to existing groff macros):

```groff
.TP
.B replace [--wait=N]
Replace the running zyginit process via in-place
.BR execve (2)
of
.IR /sbin/init .
Preserves all running services across the swap. With
.BR --wait=N ,
poll up to N seconds for any transient-state service to stabilize
before refusing. The operator must drop the new binary at
.I /sbin/init
before issuing this command. See
.BR zyginit (8)
for the live-replace mechanism.
```

- [ ] **Step 3: Update `man/zyginit.8`**

Add a "LIVE REPLACE" section describing:
- The state-file path (`/var/run/zyginit/state.toml`)
- The exec target is hard-wired to `/sbin/init`
- The boot-id sentinel (utmpx BOOT_TIME)
- That the design is operator-driven and does NOT cover crash recovery

Refer to the spec for full details.

- [ ] **Step 4: Verify man pages render**

Run:
```bash
man -l man/zygctl.8 | head -50
man -l man/zyginit.8 | head -50
```

Expected: no troff errors, the `replace` entry appears in zygctl.8.

- [ ] **Step 5: Commit**

```bash
hg add tests/integration/test_replace_hammerhead.md
hg commit -m "docs: Hammerhead replace test checklist + man page updates"
```

---

## Done — final verification

After all 14 tasks land:

- [ ] **Linux build clean:**
  ```bash
  clang -c src/helpers.c -o build/helpers.o
  clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
  reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
  cd tools/zygctl && reefc build --obj build/symlink_wrapper.o && cd ../..
  ```

- [ ] **All Linux integration tests pass:** `tests/integration/run_tests.sh`

- [ ] **Replace-probe tests pass:** `cd utils/replace_probe && ./build/replace_probe && cd ../..`

- [ ] **Spec coverage check** — re-read the spec, point at a task for each requirement:
  - §3 "no `adopt_contract`" → Task 9 (no adopt call in apply_recovered_state) ✓
  - §4 module split → Tasks 1-12 cover all five files ✓
  - §5 state file format → Tasks 4, 5 ✓
  - §5.2 boot-id staleness check → Tasks 1, 5 ✓
  - §5.3 atomic write → Task 4 ✓
  - §6.1 zygctl interface → Task 12 ✓
  - §6.2 --wait=N → Tasks 8, 10 ✓
  - §6.3 pre-conditions → Tasks 6, 10 ✓
  - §7.2 algorithm → Task 9 ✓
  - §7.3 config divergence → Task 9 (orphan abandon path) ✓
  - §8 error handling → Tasks 4, 5, 9, 10 (defensive throughout) ✓
  - §9.1 Linux tests → Task 13 ✓
  - §9.2 Hammerhead tests → Task 14 ✓
  - §11 decisions table → spec already mapped to design choices, reflected in implementation ✓

- [ ] **Hammerhead deploy + run the manual checklist** in `tests/integration/test_replace_hammerhead.md`. Capture results in a memory note (`pid1_replace_iter1.md` or similar).

---

## Non-trivial gotchas to watch for

- **Reef stdlib API names** in this plan (`toml.parse_ok`, `toml.get_int_or`, `fd.fd_fsync`, `str.starts_with`, `str.char_at`, `process.exit_now`) are best-effort. The implementer should grep the actual Reef stdlib (`~/repos/reef-lang/`) and use the real names, adjusting code locally. The shapes are right; only the spellings may differ.

- **`set_runtime_for_test` naming**. The proc is used by both the probe (legitimate test usage) and `apply_recovered_state` (production path). If the name bothers a reviewer, rename to `supervisor.adopt_runtime` and update both call sites. The function does what the production path needs; the test-y name is cosmetic.

- **`STATE_WAITING` ambiguity**. Conservative interpretation: refuse replace whenever any service is in WAITING. This includes the boot-time "not-yet-started" case, which can't actually happen at the point a replace is issued (since the table is fully started before the event loop entry that processes the replace flag). False positives only land in pathological timing. Document in commit message if concerns surface.

- **utmpx BOOT_TIME is read-once on Hammerhead** if the file is on a not-yet-mounted filesystem. The fallback to `time.time_now()` covers this gap, but means a panic-restart followed by a real reboot followed by another zyginit start will see different boot_times — that's CORRECT behavior (real reboot must invalidate state.toml).

- **`process.process_exec` argv handling**. Reef's `process_exec` may or may not require argv terminated by a sentinel. Match the pattern used elsewhere in the codebase (e.g., `start_service` in supervisor.reef). The existing pattern there uses `[string]` arrays — same pattern in `replace_self`.

- **socket.reef `cmd` parsing**. The existing dispatch only takes one string argument; for `--wait=N` we need to parse it from the `arg` string. Confirm by reading the existing handler shape; if `arg` is the rest of the line after the verb, the impl above is correct.
# Versioning and Release Tarball — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Wire a single canonical version through the zyginit suite (zyginit + zygctl + sysv-wrapper), give every binary a `--version` flag, and add scripts to bump the version and produce a source release tarball for vendoring into Hammerhead.

**Architecture:** Root `reef.toml` `[package].version` is canonical. `scripts/bump-version.sh` rewrites it plus four derived files (`tools/zygctl/reef.toml`, `src/version.reef`, `tools/zygctl/src/version.reef`, `tools/sysv-wrapper/version.h`) in lock-step. The two Reef binaries import a `version` module that exposes `pub fn VERSION(): string`. The C wrapper includes `version.h` and prints `<argv0-basename> <ZYGINIT_VERSION>`. `scripts/make-release.sh` produces `releases/zyginit-<version>-source.tar.xz` plus a `.sha256` companion, modeled on Coral's `make-release.sh`.

**Tech Stack:** Reef 0.4.0+ (compiled via `reefc`), C (POSIX), POSIX shell (`/bin/sh`), Mercurial (`hg`) for VCS, GNU `tar` with `--transform`/`--exclude`, `sha256sum`.

**Spec:** `docs/superpowers/specs/2026-05-05-versioning-and-release-tarball-design.md`

**Working version:** Throughout this plan, examples use `0.1.0` as the **current** version (matching today's `reef.toml`). Bump examples use `0.2.0` as the **next** version. The actual version in source after these tasks is unchanged at `0.1.0` — bumping to `0.2.0` is a separate, post-implementation step the maintainer runs.

---

## File Structure

**New files:**
- `src/version.reef` — generated; defines `module version` with `pub fn VERSION(): string`
- `tools/zygctl/src/version.reef` — generated; same shape as above
- `tools/sysv-wrapper/version.h` — generated; defines `ZYGINIT_VERSION` macro
- `scripts/bump-version.sh` — rewrites all five version locations
- `scripts/make-release.sh` — creates source tarball + sha256

**Modified files:**
- `src/main.reef` — drop inline `VERSION()` (lines 67-69); `import version`; add early `--version` flag handling
- `src/socket.reef` — `import version`; replace literal `"zyginit 0.1.0\n"` (line 248)
- `tools/zygctl/src/main.reef` — `import version`; replace literal `"zygctl 0.1.0"` (line 55)
- `tools/sysv-wrapper/wrapper.c` — `#include "version.h"`; add `--version`/`-V` handling
- `tools/sysv-wrapper/Makefile` — add `version.h` to `wrapper.o` dependencies
- `tests/integration/run_tests.sh` — add `--version` assertions for both binaries

---

## Task 1: Add `version` module to zyginit core

**Files:**
- Create: `src/version.reef`
- Modify: `src/main.reef:35` (add import), `src/main.reef:67-69` (drop inline `VERSION()`), `src/main.reef:835-849` (add `--version` flag handling)
- Modify: `src/socket.reef:23` (add import after existing imports), `src/socket.reef:248` (replace literal)

- [ ] **Step 1: Create `src/version.reef` with the canonical version constant**

```reef
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ `/ /_/ ___/ ___/ __ `/ / _ \
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zyginit
   Filename: version.reef
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Generated version constant. Do not edit by hand — regenerated
             by scripts/bump-version.sh.

******************************************************************************/

module version

pub fn VERSION(): string
    return "0.1.0"
end VERSION

end module
```

- [ ] **Step 2: Wire `src/main.reef` to use the module and handle `--version`**

Edit `src/main.reef`. Add `import version` after line 36 (after the `import core.str` line):

```reef
import core.str
import version
```

Delete lines 67-69 (the existing inline `VERSION()` definition):

```reef
fn VERSION(): string
    return "0.1.0"
end VERSION
```

Replace the call at line 843 (`println("zyginit v" + VERSION() + " starting")`) with:

```reef
println("zyginit v" + version.VERSION() + " starting")
```

Add `--version` flag handling at the top of `main()`. Find the current start of `proc main()` (around line 835) and insert this block as the **very first** statements in `main()`, before the `is_pid_1()` check:

```reef
proc main()
    // --version / -V short-circuits before any PID-1 setup. Manual invocations
    // (zyginit --version on a shell) have stdio fds; the kernel never passes
    // --version when exec'ing init as PID 1 (it passes -s, -m, etc. instead).
    if args.has_flag("version")
        println("zyginit " + version.VERSION())
        return
    end if

    // PID-1 fd setup MUST run before any println — when the kernel exec()s
    // init, stdin/stdout/stderr are not preopened. See setup_pid1_console
    // for the full explanation.
    if is_pid_1()
        let _ = setup_pid1_console()
    end if
    ...
```

- [ ] **Step 3: Wire `src/socket.reef` to use the module**

Edit `src/socket.reef`. Add `import version` after line 31 (after the existing `import core.str`):

```reef
import core.str
import version
```

Replace line 248:

```reef
        return "zyginit 0.1.0\n"
```

With:

```reef
        return "zyginit " + version.VERSION() + "\n"
```

- [ ] **Step 4: Build zyginit and confirm the new module compiles**

Run:
```
cd /home/ctusa/repos/zygaena-project/zyginit
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Expected: build succeeds, produces `build/zyginit`. If reefc reports `undefined symbol: VERSION`, search for stray callers of the old `VERSION()` (without the `version.` prefix); the only callers in-tree are the two we just edited.

- [ ] **Step 5: Verify `--version` works**

Run:
```
./build/zyginit --version
```

Expected output, exit 0:
```
zyginit 0.1.0
```

If the binary prints "zyginit v0.1.0 starting" instead of returning, the early-exit block in Step 2 wasn't placed before the PID-1 fd setup; move it to the top of `main()`.

- [ ] **Step 6: Verify socket version path**

There's no easy unit test for the socket dispatcher; instead, rebuild was the type check. Confirm with `grep`:

```
grep -n 'version.VERSION' src/socket.reef
```

Expected: one match on the line we edited (around line 248). The grep failing to match means the edit didn't land.

- [ ] **Step 7: Commit**

```
hg add src/version.reef
hg ci -m 'version: introduce version module; remove inline VERSION() and socket literal'
```

---

## Task 2: Add `version` module to zygctl

**Files:**
- Create: `tools/zygctl/src/version.reef`
- Modify: `tools/zygctl/src/main.reef:27` (add import), `tools/zygctl/src/main.reef:55` (replace literal)

- [ ] **Step 1: Create `tools/zygctl/src/version.reef`**

```reef
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ `/ /_/ ___/ ___/ __ `/ / _ \
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zygctl
   Filename: version.reef
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Generated version constant. Do not edit by hand — regenerated
             by scripts/bump-version.sh.

******************************************************************************/

module version

pub fn VERSION(): string
    return "0.1.0"
end VERSION

end module
```

Note `Project: zygctl` — distinct from the zyginit-core copy.

- [ ] **Step 2: Wire `tools/zygctl/src/main.reef` to use it**

Edit `tools/zygctl/src/main.reef`. Add `import version` after line 26 (after `import core.str`):

```reef
import core.str
import version
```

Replace line 55:

```reef
        println("zygctl 0.1.0")
```

With:

```reef
        println("zygctl " + version.VERSION())
```

- [ ] **Step 3: Build zygctl**

Run:
```
cd /home/ctusa/repos/zygaena-project/zyginit/tools/zygctl
clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o
reefc build --obj build/symlink_wrapper.o
```

Expected: build succeeds, produces `tools/zygctl/build/zygctl`.

- [ ] **Step 4: Verify `--version` works**

Run from `tools/zygctl/`:
```
./build/zygctl --version
```

Expected output, exit 0:
```
zygctl 0.1.0
```

Also confirm the bare `version` subcommand still works:
```
./build/zygctl version
```

Expected (same output):
```
zygctl 0.1.0
```

- [ ] **Step 5: Commit**

```
hg add tools/zygctl/src/version.reef
hg ci -m 'zygctl: use version module instead of literal'
```

---

## Task 3: Add `version.h` and `--version` to sysv-wrapper

**Files:**
- Create: `tools/sysv-wrapper/version.h`
- Modify: `tools/sysv-wrapper/wrapper.c` (add `#include`, add flag handling at top of `main()`)
- Modify: `tools/sysv-wrapper/Makefile` (depend on `version.h`)

- [ ] **Step 1: Create `tools/sysv-wrapper/version.h`**

```c
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ `/ /_/ ___/ ___/ __ `/ / _ \
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zyginit
   Filename: version.h
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Generated version constant. Do not edit by hand — regenerated
             by scripts/bump-version.sh.

******************************************************************************/

#ifndef ZYGINIT_VERSION_H
#define ZYGINIT_VERSION_H
#define ZYGINIT_VERSION "0.1.0"
#endif
```

- [ ] **Step 2: Edit `tools/sysv-wrapper/wrapper.c` to add `--version` handling**

Add the include after line 30 (after `#include <errno.h>`):

```c
#include <errno.h>
#include "version.h"
```

In `main()`, add a `--version` short-circuit **before** the `argv0_copy = strdup(argv[0])` line (currently line 84). The check has to come after computing `me` (the basename), so the printout can use the personality name.

The cleanest restructure: keep the existing basename computation, then add the flag check immediately after `me = basename(argv0_copy);`. Replace the block at lines 80-101 with:

```c
        const char *me;
        char *argv0_copy;

        /* basename(3) on illumos modifies its argument, so duplicate first */
        argv0_copy = strdup(argv[0]);
        if (argv0_copy == NULL) {
                (void) fprintf(stderr, "out of memory\n");
                return (1);
        }
        me = basename(argv0_copy);

        if (argc >= 2 &&
            (strcmp(argv[1], "--version") == 0 ||
             strcmp(argv[1], "-V") == 0)) {
                (void) printf("%s %s\n", me, ZYGINIT_VERSION);
                free(argv0_copy);
                return (0);
        }

        if (strcmp(me, "init") == 0 || strcmp(me, "telinit") == 0)
                return (init_dispatch(argc, argv));
        if (strcmp(me, "halt") == 0)
                return (run_zygctl("halt"));
        if (strcmp(me, "reboot") == 0)
                return (run_zygctl("reboot"));
        if (strcmp(me, "poweroff") == 0)
                return (run_zygctl("poweroff"));

        (void) fprintf(stderr, "sysv-wrapper: unknown invocation '%s'\n", me);
        return (1);
```

(Existing run_zygctl paths leak `argv0_copy` already — preserving that to minimize unrelated changes.)

- [ ] **Step 3: Edit `tools/sysv-wrapper/Makefile` to depend on `version.h`**

Replace the build rule:

```make
sysv-wrapper: wrapper.c
	$(CC) $(CFLAGS) -o $@ $<
```

With:

```make
sysv-wrapper: wrapper.c version.h
	$(CC) $(CFLAGS) -o $@ wrapper.c
```

(Switched `$<` to explicit `wrapper.c` because `$<` would only refer to `wrapper.c`, but adding a second prerequisite makes the explicit form clearer.)

- [ ] **Step 4: Build sysv-wrapper**

Run from `tools/sysv-wrapper/`:
```
make clean && make
```

Expected: produces `./sysv-wrapper`, no warnings.

- [ ] **Step 5: Verify `--version` for each personality**

Run:
```
./sysv-wrapper --version
ln -sf sysv-wrapper /tmp/halt && /tmp/halt --version
ln -sf sysv-wrapper /tmp/reboot && /tmp/reboot --version
ln -sf sysv-wrapper /tmp/poweroff && /tmp/poweroff --version
ln -sf sysv-wrapper /tmp/telinit && /tmp/telinit --version
rm -f /tmp/halt /tmp/reboot /tmp/poweroff /tmp/telinit
```

Expected (one line per invocation, exit 0 each):
```
sysv-wrapper 0.1.0
halt 0.1.0
reboot 0.1.0
poweroff 0.1.0
telinit 0.1.0
```

- [ ] **Step 6: Commit**

```
hg add tools/sysv-wrapper/version.h
hg ci -m 'sysv-wrapper: add --version (and -V) flag'
```

---

## Task 4: Write `scripts/bump-version.sh`

**Files:**
- Create: `scripts/bump-version.sh`
- Test (one-shot, not committed): `/tmp/bump-test.sh`

- [ ] **Step 1: Write a one-shot test harness for the bump script**

This isn't a permanent test — just a sanity check we run before committing the script. Create `/tmp/bump-test.sh`:

```sh
#!/bin/sh
# Sanity test for scripts/bump-version.sh.
# Snapshots all five version locations, runs the script, verifies all
# five rewrite to the new version, then restores from snapshot.
set -e

cd /home/ctusa/repos/zygaena-project/zyginit

# Snapshot
cp reef.toml /tmp/bump.snap.root.toml
cp tools/zygctl/reef.toml /tmp/bump.snap.zygctl.toml
cp src/version.reef /tmp/bump.snap.zyginit.version.reef
cp tools/zygctl/src/version.reef /tmp/bump.snap.zygctl.version.reef
cp tools/sysv-wrapper/version.h /tmp/bump.snap.sysv.h

# Run
./scripts/bump-version.sh 9.9.9

# Verify
fail=0
grep -q '^version = "9.9.9"' reef.toml || { echo FAIL: root reef.toml; fail=1; }
grep -q '^version = "9.9.9"' tools/zygctl/reef.toml || { echo FAIL: zygctl reef.toml; fail=1; }
grep -q 'return "9.9.9"' src/version.reef || { echo FAIL: src/version.reef; fail=1; }
grep -q 'return "9.9.9"' tools/zygctl/src/version.reef || { echo FAIL: zygctl version.reef; fail=1; }
grep -q '#define ZYGINIT_VERSION "9.9.9"' tools/sysv-wrapper/version.h || { echo FAIL: sysv version.h; fail=1; }

# Restore
cp /tmp/bump.snap.root.toml reef.toml
cp /tmp/bump.snap.zygctl.toml tools/zygctl/reef.toml
cp /tmp/bump.snap.zyginit.version.reef src/version.reef
cp /tmp/bump.snap.zygctl.version.reef tools/zygctl/src/version.reef
cp /tmp/bump.snap.sysv.h tools/sysv-wrapper/version.h
rm -f /tmp/bump.snap.*

if [ $fail -eq 0 ]; then
    echo "PASS: bump-version rewrote all five files"
else
    echo "FAIL"
    exit 1
fi
```

`chmod +x /tmp/bump-test.sh`. Don't run it yet — the script doesn't exist.

- [ ] **Step 2: Run the test to confirm it fails**

```
/tmp/bump-test.sh
```

Expected: error message that `./scripts/bump-version.sh` is not found.

- [ ] **Step 3: Write `scripts/bump-version.sh`**

Create `scripts/bump-version.sh` with mode 0755:

```sh
#!/bin/sh
#
# Bump the canonical zyginit version.
#
# Usage: ./scripts/bump-version.sh <new-version>
#
# Rewrites in lock-step:
#   - reef.toml                          (canonical)
#   - tools/zygctl/reef.toml
#   - src/version.reef                   (regenerated)
#   - tools/zygctl/src/version.reef      (regenerated)
#   - tools/sysv-wrapper/version.h       (regenerated)
#
# Does NOT auto-commit. Review with `hg diff` and commit by hand.
#

set -e

if [ $# -ne 1 ]; then
    echo "usage: $0 <new-version>" >&2
    exit 1
fi

NEW="$1"

# Validate semver shape (no pre-release suffix yet — see plan §10).
echo "$NEW" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' || {
    echo "error: '$NEW' is not in MAJOR.MINOR.PATCH form" >&2
    exit 1
}

SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
ROOT=$(dirname "$SCRIPT_DIR")
cd "$ROOT"

CURRENT=$(grep '^version' reef.toml | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
if [ -z "$CURRENT" ]; then
    echo "error: could not read current version from reef.toml" >&2
    exit 1
fi

if [ "$CURRENT" = "$NEW" ]; then
    echo "error: version is already $NEW" >&2
    exit 1
fi

echo "zyginit: bumping $CURRENT -> $NEW"

# 1. Root reef.toml — sed in place. Match only the first 'version = "..."'
#    in the [package] table (top of file).
echo "  rewriting reef.toml"
sed -i "0,/^version = \"[^\"]*\"/s//version = \"$NEW\"/" reef.toml

# 2. tools/zygctl/reef.toml
echo "  rewriting tools/zygctl/reef.toml"
sed -i "0,/^version = \"[^\"]*\"/s//version = \"$NEW\"/" tools/zygctl/reef.toml

# 3. src/version.reef — full regenerate.
echo "  regenerating src/version.reef"
gen_reef_module zyginit src/version.reef "$NEW"

# 4. tools/zygctl/src/version.reef — full regenerate.
echo "  regenerating tools/zygctl/src/version.reef"
gen_reef_module zygctl tools/zygctl/src/version.reef "$NEW"

# 5. tools/sysv-wrapper/version.h — full regenerate.
echo "  regenerating tools/sysv-wrapper/version.h"
gen_c_header tools/sysv-wrapper/version.h "$NEW"

echo "done. review with 'hg diff' and commit:"
echo "  hg ci -m 'Bump version to $NEW'"
```

Then add the helper functions ABOVE the `set -e` line (so they're defined before use). Insert this block right after the comment header, before `set -e`:

```sh
# ----------------------------------------------------------------------------
# Helpers for regenerating templated files.
# ----------------------------------------------------------------------------

gen_reef_module() {
    project="$1"
    path="$2"
    version="$3"
    cat > "$path" <<EOF
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ \`/ /_/ ___/ ___/ __ \`/ / _ \\
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: $project
   Filename: version.reef
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Generated version constant. Do not edit by hand — regenerated
             by scripts/bump-version.sh.

******************************************************************************/

module version

pub fn VERSION(): string
    return "$version"
end VERSION

end module
EOF
}

gen_c_header() {
    path="$1"
    version="$2"
    cat > "$path" <<EOF
/******************************************************************************
                __               ____                __
               / /   ___  ____ _/ __/_____________ _/ /__
              / /   / _ \/ __ \`/ /_/ ___/ ___/ __ \`/ / _ \\
             / /___/  __/ /_/ / __(__  ) /__/ /_/ / /  __/
            /_____/\___/\__,_/_/ /____/\___/\__,_/_/\___/

    (C)opyright 2025-2026, Leafscale, LLC -  https://www.leafscale.com

    Project: zyginit
   Filename: version.h
    Authors: Chris Tusa <chris.tusa@leafscale.com>
    License: <see LICENSE file included with this source code>
Description: Generated version constant. Do not edit by hand — regenerated
             by scripts/bump-version.sh.

******************************************************************************/

#ifndef ZYGINIT_VERSION_H
#define ZYGINIT_VERSION_H
#define ZYGINIT_VERSION "$version"
#endif
EOF
}
```

`chmod +x scripts/bump-version.sh`.

- [ ] **Step 4: Run the test**

```
/tmp/bump-test.sh
```

Expected: `PASS: bump-version rewrote all five files`. The script also restored the snapshot, so `hg status` should show no changes.

If the test reports a `FAIL: <file>` line, inspect that file by hand: the `sed` substitution may not have matched (e.g., if reef.toml's `version` line has a different indentation), or the `cat <<EOF` heredoc had a quoting issue (backticks in the ASCII art are escaped as `\``).

- [ ] **Step 5: Negative tests**

```
./scripts/bump-version.sh                # missing arg
./scripts/bump-version.sh 1.2            # bad shape
./scripts/bump-version.sh 0.1.0          # same as current
```

Expected: each prints an error to stderr and exits non-zero. Run `hg status` after each — should show no changes.

- [ ] **Step 6: Commit**

```
hg add scripts/bump-version.sh
hg ci -m 'scripts: add bump-version.sh for in-lockstep version updates'
```

Delete the throwaway test:
```
rm -f /tmp/bump-test.sh
```

---

## Task 5: Write `scripts/make-release.sh`

**Files:**
- Create: `scripts/make-release.sh`
- Test (one-shot, not committed): inline at end of step 4

- [ ] **Step 1: Write `scripts/make-release.sh` (modeled on Coral's)**

Create `scripts/make-release.sh` with mode 0755:

```sh
#!/bin/sh
#
# Create a source release tarball for the zyginit suite.
#
# Usage: ./scripts/make-release.sh [version-override]
#
# Reads the canonical version from reef.toml unless an override is given.
# Produces:
#   releases/zyginit-<version>-source.tar.xz
#   releases/zyginit-<version>-source.tar.xz.sha256
#

set -e

SCRIPT_DIR=$(cd "$(dirname "$0")" && pwd)
ROOT=$(dirname "$SCRIPT_DIR")
cd "$ROOT"

if [ -n "$1" ]; then
    VERSION="$1"
else
    VERSION=$(grep '^version' reef.toml | head -1 | sed 's/.*"\([^"]*\)".*/\1/')
fi

if [ -z "$VERSION" ]; then
    echo "error: could not determine version" >&2
    exit 1
fi

NAME="zyginit-${VERSION}-source"
RELEASES="releases"
TARBALL="${RELEASES}/${NAME}.tar.xz"

echo "Creating release: $NAME"
mkdir -p "$RELEASES"

tar \
    --exclude='build' \
    --exclude='build/*' \
    --exclude='tools/*/build' \
    --exclude='tools/*/build/*' \
    --exclude='releases' \
    --exclude='.hg' \
    --exclude='.hgignore' \
    --exclude='.hgtags' \
    --exclude='resume' \
    --exclude='ss' \
    --exclude='stub' \
    --exclude='*.o' \
    --exclude='*.a' \
    --exclude='*.swp' \
    --transform "s,^,${NAME}/," \
    -cJf "$TARBALL" \
    reef.toml \
    README.md \
    ROADMAP.md \
    CLAUDE.md \
    SRCHEADER.txt \
    src \
    docs \
    tests \
    services \
    tools \
    utils \
    scripts

echo "Created: $TARBALL"
ls -la "$TARBALL"

sha256sum "$TARBALL" > "${TARBALL}.sha256"
echo "Checksum: ${TARBALL}.sha256"
cat "${TARBALL}.sha256"
```

`chmod +x scripts/make-release.sh`.

- [ ] **Step 2: Run it**

```
./scripts/make-release.sh
```

Expected stdout (with `0.1.0` from current reef.toml):
```
Creating release: zyginit-0.1.0-source
Created: releases/zyginit-0.1.0-source.tar.xz
-rw-r--r-- 1 ctusa ctusa <size> <date> releases/zyginit-0.1.0-source.tar.xz
Checksum: releases/zyginit-0.1.0-source.tar.xz.sha256
<hash>  releases/zyginit-0.1.0-source.tar.xz
```

- [ ] **Step 3: Verify tarball contents**

```
tar tJf releases/zyginit-0.1.0-source.tar.xz | head -30
tar tJf releases/zyginit-0.1.0-source.tar.xz | grep -c '^zyginit-0.1.0-source/'
```

The first command shows the top of the listing — every entry MUST start with `zyginit-0.1.0-source/`. The second prints the total entry count.

Also confirm the excludes worked:

```
tar tJf releases/zyginit-0.1.0-source.tar.xz | grep -E '\.hg|/build/|/releases/|/resume/|/ss/|/stub/|\.o$|\.a$' && echo FAIL || echo OK
```

Expected: `OK`. Any line printed by `grep` indicates an exclude that didn't take.

- [ ] **Step 4: Verify the tarball is buildable as-is**

```
mkdir -p /tmp/release-check
tar xJf releases/zyginit-0.1.0-source.tar.xz -C /tmp/release-check
cd /tmp/release-check/zyginit-0.1.0-source
clang -c src/helpers.c -o build/helpers.o 2>/dev/null || \
    (mkdir -p build && clang -c src/helpers.c -o build/helpers.o)
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./build/zyginit --version
cd /home/ctusa/repos/zygaena-project/zyginit
rm -rf /tmp/release-check
```

Expected: `zyginit 0.1.0`, exit 0. This is the smoke test that the tarball is self-sufficient.

- [ ] **Step 5: Verify checksum file is well-formed**

```
sha256sum -c releases/zyginit-0.1.0-source.tar.xz.sha256
```

Expected: `releases/zyginit-0.1.0-source.tar.xz: OK`.

- [ ] **Step 6: Add `releases/` to `.hgignore`**

Check whether `releases/` is already ignored:

```
hg status releases/
```

If `hg status` lists the new tarball as untracked (`?`), add it to `.hgignore`. The existing `.hgignore` uses `syntax: glob` (already declared at the top), so append the line:

```
releases/
```

Verify by re-running `hg status releases/` — it should now show no output (the directory is ignored).

- [ ] **Step 7: Commit (script and `.hgignore` only — not the tarball)**

```
hg status
hg add scripts/make-release.sh
# Only `hg add .hgignore` if it's not already tracked.
hg ci -m 'scripts: add make-release.sh for source tarball generation'
```

`hg status` after commit should show only the untracked `releases/` directory if `.hgignore` worked, or nothing if `releases/` is empty/absent.

---

## Task 6: Add `--version` integration tests

**Files:**
- Modify: `tests/integration/run_tests.sh` (add new section)

- [ ] **Step 1: Add a `version` test section near the bottom of `run_tests.sh`**

Find the last `section "..."` block in `tests/integration/run_tests.sh`. Add a new section just before the final summary print. Search for a stable anchor like `printf "\n=== Summary ===\n"` or wherever the final `PASS=`/`FAIL=` rollup happens, and add this block immediately before it:

```sh
# ============================================================================
section "Version reporting"
# ============================================================================

# Both binaries should respond to --version (and `version` subcommand for zygctl)
# with a single line "<binary> <version>" matching reef.toml.

EXPECTED_VERSION=$(grep '^version' "$PROJECT_DIR/reef.toml" | head -1 | sed 's/.*"\([^"]*\)".*/\1/')

OUT="$("$ZYGINIT" --version 2>&1)"
assert_equals "$OUT" "zyginit $EXPECTED_VERSION" "zyginit --version output"

OUT="$(zygctl --version)"
assert_equals "$OUT" "zygctl $EXPECTED_VERSION" "zygctl --version output"

OUT="$(zygctl version)"
assert_equals "$OUT" "zygctl $EXPECTED_VERSION" "zygctl version subcommand output"
```

(The script already has `EXPECTED_VERSION` as a fresh variable name; if there's a collision, rename to `_VERSION`. The `zygctl()` shell function on line 109 already wraps the binary call, so `zygctl --version` here uses that wrapper.)

- [ ] **Step 2: Run the integration tests**

```
./tests/integration/run_tests.sh
```

Expected: total test count increased by 3, all passing. The tail of the output should include:

```
=== Version reporting ===
  PASS: zyginit --version output
  PASS: zygctl --version output
  PASS: zygctl version subcommand output
```

If `zyginit --version` fails by printing the startup banner instead of returning, Task 1 Step 2's flag short-circuit was placed in the wrong spot — re-check that it's the first thing in `main()`.

- [ ] **Step 3: Commit**

```
hg ci -m 'tests/integration: assert --version output for zyginit and zygctl'
```

---

## Task 7: End-to-end bump rehearsal (no commit)

This task verifies the whole pipeline works together: bump → build → release → install-check. It's a rehearsal — we don't commit the bumped version. Use `9.9.9` so it's obviously a test value.

**Files:** No persistent changes.

- [ ] **Step 1: Snapshot current state**

```
hg status   # should be clean before starting
```

If not clean, stop and resolve before proceeding.

- [ ] **Step 2: Bump to a sentinel version**

```
./scripts/bump-version.sh 9.9.9
hg diff --stat
```

Expected diff: 5 files changed (`reef.toml`, `tools/zygctl/reef.toml`, `src/version.reef`, `tools/zygctl/src/version.reef`, `tools/sysv-wrapper/version.h`), each with a small change.

- [ ] **Step 3: Build all three binaries with the new version**

```
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o && reefc build --obj build/symlink_wrapper.o)
(cd tools/sysv-wrapper && make clean && make)
```

Expected: all three succeed.

- [ ] **Step 4: Verify all three report 9.9.9**

```
./build/zyginit --version
./tools/zygctl/build/zygctl --version
./tools/sysv-wrapper/sysv-wrapper --version
```

Expected:
```
zyginit 9.9.9
zygctl 9.9.9
sysv-wrapper 9.9.9
```

- [ ] **Step 5: Make a release tarball at 9.9.9**

```
./scripts/make-release.sh
ls -la releases/zyginit-9.9.9-source.tar.xz releases/zyginit-9.9.9-source.tar.xz.sha256
```

Expected: both files present. Filename includes `9.9.9`.

- [ ] **Step 6: Roll back the bump**

```
hg revert reef.toml tools/zygctl/reef.toml src/version.reef tools/zygctl/src/version.reef tools/sysv-wrapper/version.h
rm -f releases/zyginit-9.9.9-source.tar.xz releases/zyginit-9.9.9-source.tar.xz.sha256
hg status
```

Expected: `hg status` clean, releases dir contains no `9.9.9` artifacts.

- [ ] **Step 7: No commit**

This is a rehearsal. The actual first version bump is left to the maintainer to perform when they're ready to cut a real release.

---

## Final Verification Checklist

- [ ] `./build/zyginit --version` prints `zyginit 0.1.0`
- [ ] `./tools/zygctl/build/zygctl --version` prints `zygctl 0.1.0`
- [ ] `./tools/zygctl/build/zygctl version` prints `zygctl 0.1.0`
- [ ] `./tools/sysv-wrapper/sysv-wrapper --version` prints `sysv-wrapper 0.1.0`
- [ ] `halt --version` (via symlink) prints `halt 0.1.0`
- [ ] `./scripts/bump-version.sh 9.9.9` rewrites all five files; rehearsal then reverted
- [ ] `./scripts/make-release.sh` produces `releases/zyginit-0.1.0-source.tar.xz` + `.sha256`
- [ ] Extracted tarball builds cleanly with `reefc build` and yields a working `zyginit --version`
- [ ] `tests/integration/run_tests.sh` passes with three new assertions
- [ ] `hg log --limit 6` shows six commits in the order: version module, zygctl, sysv-wrapper, bump-version, make-release, integration tests
# zyginit Visual Pass Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Implement the unified visual identity defined in `docs/superpowers/specs/2026-05-12-zyginit-visual-pass-design.md`: boot rolling tape, progress bar, spinner, final cards, shutdown mirror, and `zygctl status` banner.

**Architecture:** Single new module `src/ui.reef` owns all rendering — palette, glyphs, sigil, TTY/TERM detection, ANSI sequences, rolling tape state, progress bar, spinner. Existing `println` lifecycle sites in `main.reef` and `supervisor.reef` route through it. zygctl client detects its own TTY and asks the daemon for `STATUS PLAIN` when piped. A `--ui-demo <scenario>` flag on zyginit drives snapshot-based tests against canned event sequences (no daemon needed).

**Tech Stack:** Reef 0.4+; FFI via `extern "C"` to a new `zyginit_isatty` helper in `src/helpers.c`; SGR / VT100 sequences for rich rendering; existing integration shell harness for end-to-end tests; Mercurial for VCS.

---

## File Structure

**Create:**
- `src/ui.reef` — rendering module (all UI state and procedures)
- `tests/integration/snapshots/` — golden output files for snapshot tests
- `tests/integration/ui_tests.sh` — shell-based snapshot test runner

**Modify:**
- `src/helpers.c` — add `zyginit_isatty(int fd)` (returns 1/0)
- `src/main.reef` — wire `ui_init`, `ui_boot_start`, `ui_tier_start/done`, `ui_boot_complete`, `ui_shutdown_start/complete`, `ui_tick`; add `--ui-demo <scenario>` flag dispatch
- `src/supervisor.reef` — replace ~8 lifecycle `println` sites with `ui_event_*` calls
- `src/socket.reef` — `cmd_status` / `cmd_list` delegate to `ui_render_*`; parse `PLAIN` modifier
- `tools/zygctl/src/main.reef` — pre-flight `detect_rich_mode`; send `STATUS` or `STATUS PLAIN`
- `tests/integration/run_tests.sh` — `export ZYGINIT_NO_UI=1` for diff stability
- `reef.toml`, `tools/zygctl/reef.toml`, `tools/sysv-wrapper/Makefile`, `src/version.reef`, `tools/zygctl/src/version.reef` — version bump 0.1.2 → 0.1.3 via the existing `scripts/bump-version.sh`

**Branching:** all work on a fresh Mercurial bookmark `visual-pass` off rev 122.

---

## Task 1: ui.reef skeleton + isatty C helper + `--ui-demo` flag

**Files:**
- Create: `src/ui.reef`
- Modify: `src/helpers.c` (append `zyginit_isatty`)
- Modify: `src/main.reef` (argv parsing for `--ui-demo`)
- Test: `tests/integration/ui_tests.sh` (new)

- [ ] **Step 1: Write the failing snapshot test for `--ui-demo skeleton`**

Create `tests/integration/ui_tests.sh`:

```sh
#!/bin/sh
# Snapshot tests for the ui.reef renderer.
# Each scenario invokes `zyginit --ui-demo <name>` and diffs against a golden file.
set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
ZYGINIT="$PROJECT_DIR/build/zyginit"
SNAP_DIR="$SCRIPT_DIR/snapshots"

mkdir -p "$SNAP_DIR"
PASS=0
FAIL=0

check_scenario() {
    name=$1
    env_prefix=$2
    expected="$SNAP_DIR/$name.txt"
    got=$(mktemp)
    eval "$env_prefix $ZYGINIT --ui-demo $name" > "$got" 2>&1
    if [ ! -f "$expected" ]; then
        cp "$got" "$expected"
        echo "  [created]  $name"
        PASS=$((PASS+1))
        rm -f "$got"
        return
    fi
    if diff -u "$expected" "$got" > /dev/null; then
        echo "  [pass]     $name"
        PASS=$((PASS+1))
    else
        echo "  [FAIL]     $name"
        diff -u "$expected" "$got" || true
        FAIL=$((FAIL+1))
    fi
    rm -f "$got"
}

echo "ui snapshot tests"
check_scenario skeleton "ZYGINIT_NO_UI=1"

echo
echo "passed: $PASS  failed: $FAIL"
[ "$FAIL" -eq 0 ]
```

Then make it executable: `chmod +x tests/integration/ui_tests.sh`

- [ ] **Step 2: Run the test to confirm it fails**

Run: `./tests/integration/ui_tests.sh`
Expected: FAIL — `build/zyginit` either doesn't exist or doesn't recognize `--ui-demo`. Either is the failing condition we want.

- [ ] **Step 3: Add the `zyginit_isatty` C helper**

In `src/helpers.c`, append after the existing helpers (before the final closing line):

```c
/* zyginit_isatty: thin wrapper around isatty(3) so Reef FFI sees an int
 * return. Returns 1 if fd is a terminal, 0 otherwise. */
#include <unistd.h>
int zyginit_isatty(int fd) {
    return isatty(fd) ? 1 : 0;
}
```

- [ ] **Step 4: Create `src/ui.reef` skeleton**

Create `src/ui.reef`:

```reef
/* SRCHEADER goes here — copy from project root SRCHEADER.txt, fill in:
   Project: zyginit, Filename: ui.reef,
   Description: Unified visual rendering: palette, glyphs, sigil,
                rolling tape, progress bar, spinner, final cards. */

module ui

import core.str as str
import sys.env as env

// Render modes. Decided once at startup by ui_init().
fn MODE_PLAIN(): int        return 0   end MODE_PLAIN
fn MODE_RICH_ASCII(): int   return 1   end MODE_RICH_ASCII
fn MODE_RICH_16(): int      return 2   end MODE_RICH_16
fn MODE_RICH_TRUE(): int    return 3   end MODE_RICH_TRUE

mut g_mode: int = 0
mut g_failed: bool = false   // set if write() to /dev/console errors

extern "C" fn zyginit_isatty(fd: int): int

proc ui_init(rich_mode: int)
    g_mode = rich_mode
    g_failed = false
end ui_init

fn ui_mode(): int
    return g_mode
end ui_mode

// Scenario dispatcher for --ui-demo. Called from main.reef.
// Returns 0 on success, 1 if the scenario name is unknown.
fn ui_demo(scenario: string): int
    if scenario == "skeleton"
        println("ui.reef skeleton ok, mode=" + int_to_str(g_mode))
        return 0
    end if
    println("ui.reef: unknown demo scenario: " + scenario)
    return 1
end ui_demo

end module
```

- [ ] **Step 5: Wire `--ui-demo` into `src/main.reef`**

Find the argv parsing block near the top of `main()` in `src/main.reef`. Before the existing `--version` check, add:

```reef
// --ui-demo <scenario>: run a canned UI scenario for snapshot testing.
if args.has_flag(argv, "--ui-demo")
    let scenario = args.get_flag_value(argv, "--ui-demo")
    ui.ui_init(ui.MODE_PLAIN())
    process.exit(ui.ui_demo(scenario))
end if
```

And add `import ui` to the imports near the top of `src/main.reef`.

- [ ] **Step 6: Build and re-run the test**

```sh
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Expected: snapshot is auto-created on first run. Output line: `ui.reef skeleton ok, mode=0`.

- [ ] **Step 7: Commit**

```sh
hg add src/ui.reef tests/integration/ui_tests.sh tests/integration/snapshots/skeleton.txt
hg commit -m "ui: skeleton + --ui-demo flag + isatty C helper"
```

---

## Task 2: `detect_rich_mode` and plain-mode line renderer

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Add failing snapshot tests for plain-mode scenarios**

In `tests/integration/ui_tests.sh`, add after the `skeleton` check:

```sh
check_scenario plain_boot "ZYGINIT_NO_UI=1 TERM=xterm-256color"
check_scenario detect_no_color "NO_COLOR=1 TERM=xterm-256color"
check_scenario detect_dumb "TERM=dumb"
check_scenario detect_sun "TERM=sun"
check_scenario detect_sun_color "TERM=sun-color"
```

- [ ] **Step 2: Run tests to confirm failure**

Run: `./tests/integration/ui_tests.sh`
Expected: FAILs — scenarios are unknown.

- [ ] **Step 3: Implement `detect_rich_mode` and plain-mode emitter in `src/ui.reef`**

Add to `src/ui.reef` (after the mode constants, before `ui_init`):

```reef
fn detect_rich_mode(): int
    if env.has_env("ZYGINIT_NO_UI")     return MODE_PLAIN()     end if
    if env.has_env("NO_COLOR")          return MODE_PLAIN()     end if
    // PID check: non-PID-1 zyginit instances always emit plain.
    // sys.process.getpid is imported at top of file.
    if process.getpid() != 1
        // Allow override for unit tests via --ui-demo: caller calls ui_init() directly.
        // detect_rich_mode is only invoked from boot path in main.reef.
        return MODE_PLAIN()
    end if
    if zyginit_isatty(1) == 0           return MODE_PLAIN()     end if
    let term = env.get_env_or("TERM", "")
    if str.length(term) == 0            return MODE_PLAIN()     end if
    if term == "dumb"                   return MODE_PLAIN()     end if
    if env.has_env("ZYGINIT_ASCII")     return MODE_RICH_ASCII() end if
    if term == "sun-color"              return MODE_RICH_TRUE() end if
    if str.index_of(term, "256color") >= 0
        return MODE_RICH_TRUE()
    end if
    return MODE_RICH_16()
end detect_rich_mode
```

Add `import sys.process as process` at the top of `src/ui.reef`.

Then add a plain-mode emitter:

```reef
// Plain-mode line: "  <elapsed-s>  <level>  <event>     <name>  [k=v ...]"
// Used for boot/shutdown tape entries in MODE_PLAIN and as fallback.
fn fmt_plain_event(elapsed_ms: int, level: string, event: string,
                   name: string, kv: string): string
    let secs = int_to_str(elapsed_ms / 1000)
    let frac = int_to_str((elapsed_ms mod 1000) / 10)   // 2-digit decimal
    let pad = ""
    if str.length(frac) < 2
        pad = "0"
    end if
    mut line = str.concat("  ", secs)
    line = str.concat(line, ".")
    line = str.concat(line, pad)
    line = str.concat(line, frac)
    line = str.concat(line, "  ")
    line = str.concat(line, level)
    line = str.concat(line, "  ")
    line = str.concat(line, event)
    line = str.concat(line, "  ")
    line = str.concat(line, name)
    if str.length(kv) > 0
        line = str.concat(line, "  ")
        line = str.concat(line, kv)
    end if
    return line
end fmt_plain_event
```

- [ ] **Step 4: Add demo scenarios to `ui_demo`**

Replace the `ui_demo` body in `src/ui.reef`:

```reef
fn ui_demo(scenario: string): int
    if scenario == "skeleton"
        println("ui.reef skeleton ok, mode=" + int_to_str(g_mode))
        return 0
    end if
    if scenario == "plain_boot"
        println(fmt_plain_event(40, "info", "started", "root-fs", ""))
        println(fmt_plain_event(120, "info", "started", "crypto", "dur_ms=80"))
        println(fmt_plain_event(310, "info", "started", "devfs", "dur_ms=190"))
        println(fmt_plain_event(5020, "err",  "failed",  "network", "exit=1 dur_ms=4023"))
        return 0
    end if
    if str.index_of(scenario, "detect_") == 0
        // Override g_mode by calling detect_rich_mode under the test env.
        g_mode = detect_rich_mode()
        println("mode=" + int_to_str(g_mode))
        return 0
    end if
    println("ui.reef: unknown demo scenario: " + scenario)
    return 1
end ui_demo
```

- [ ] **Step 5: Build and re-run tests**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Expected snapshots get auto-created. Verify their content by hand:

```sh
cat tests/integration/snapshots/plain_boot.txt
```

Should show 4 lines, last one being the failed network event. Check the detect snapshots match expectations:
- `detect_no_color.txt`: `mode=0`
- `detect_dumb.txt`: `mode=0`
- `detect_sun.txt`: `mode=2` (RICH_16)
- `detect_sun_color.txt`: `mode=3` (RICH_TRUE)

If any are wrong, fix `detect_rich_mode` and re-run.

- [ ] **Step 6: Commit**

```sh
hg add tests/integration/snapshots/*.txt
hg commit -m "ui: detect_rich_mode + plain-mode line formatter + snapshot tests"
```

---

## Task 3: Rich primitives — palette, glyphs, sigil

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Add failing snapshots for color and glyph helpers**

In `tests/integration/ui_tests.sh`:

```sh
check_scenario palette_true "TERM=xterm-256color"
check_scenario palette_16   "TERM=sun"
check_scenario glyphs_unicode "TERM=xterm-256color"
check_scenario glyphs_ascii   "TERM=xterm-256color ZYGINIT_ASCII=1"
check_scenario sigil_rich   "TERM=sun-color"
```

- [ ] **Step 2: Run tests — confirm failure**

Run: `./tests/integration/ui_tests.sh`
Expected: 5 new FAILs.

- [ ] **Step 3: Add palette + glyph + sigil functions to `src/ui.reef`**

```reef
// SGR escape sequences. CSI is "\e[", reset is "\e[0m".
fn esc_reset(): string return "\x1b[0m" end esc_reset

// 16-color foreground codes.
fn sgr_steel(): string  return "\x1b[37m"   end sgr_steel    // white
fn sgr_teal(): string   return "\x1b[36m"   end sgr_teal     // cyan
fn sgr_ok(): string     return "\x1b[32m"   end sgr_ok       // green
fn sgr_warn(): string   return "\x1b[33m"   end sgr_warn     // yellow
fn sgr_fail(): string   return "\x1b[31m"   end sgr_fail     // red
fn sgr_mute(): string   return "\x1b[2m"    end sgr_mute     // dim

// Truecolor foreground codes.
fn sgr_steel_true(): string return "\x1b[38;2;110;123;139m"  end sgr_steel_true
fn sgr_teal_true(): string  return "\x1b[38;2;0;106;111m"    end sgr_teal_true
fn sgr_ok_true(): string    return "\x1b[38;2;46;139;87m"    end sgr_ok_true
fn sgr_warn_true(): string  return "\x1b[38;2;255;191;0m"    end sgr_warn_true
fn sgr_fail_true(): string  return "\x1b[38;2;200;32;31m"    end sgr_fail_true

// Wrap text in the given palette token, honoring g_mode.
fn paint(token: string, text: string): string
    if g_mode == MODE_PLAIN()  return text  end if
    mut on = ""
    if g_mode == MODE_RICH_TRUE()
        if token == "frame"  on = sgr_steel_true()
        else if token == "accent" on = sgr_teal_true()
        else if token == "ok" on = sgr_ok_true()
        else if token == "warn" on = sgr_warn_true()
        else if token == "fail" on = sgr_fail_true()
        else if token == "mute" on = sgr_mute()
        end if
    else
        if token == "frame"  on = sgr_steel()
        else if token == "accent" on = sgr_teal()
        else if token == "ok" on = sgr_ok()
        else if token == "warn" on = sgr_warn()
        else if token == "fail" on = sgr_fail()
        else if token == "mute" on = sgr_mute()
        end if
    end if
    return str.concat(str.concat(on, text), esc_reset())
end paint

// Glyphs. Selected by g_mode.
fn glyph_ok(): string
    if g_mode == MODE_RICH_ASCII() return "#" end if
    if g_mode == MODE_PLAIN()      return "ok" end if
    return "●"
end glyph_ok

fn glyph_fail(): string
    if g_mode == MODE_RICH_ASCII() return "X" end if
    if g_mode == MODE_PLAIN()      return "fail" end if
    return "✕"
end glyph_fail

fn glyph_pending(): string
    if g_mode == MODE_RICH_ASCII() return "." end if
    if g_mode == MODE_PLAIN()      return "pending" end if
    return "·"
end glyph_pending

// Static starting glyph used when not animating (rare, e.g. snapshots).
fn glyph_starting(): string
    if g_mode == MODE_RICH_ASCII() return "o" end if
    if g_mode == MODE_PLAIN()      return "starting" end if
    return "◉"
end glyph_starting

// Sigil. Always "[Z]", colored c.accent in rich modes.
fn sigil(): string
    return paint("accent", "[Z]")
end sigil
```

- [ ] **Step 4: Add demo scenarios for the primitives**

In `ui_demo`, add before the final `unknown` line:

```reef
    if scenario == "palette_true" or scenario == "palette_16"
        g_mode = detect_rich_mode()
        println(paint("frame",  "frame text"))
        println(paint("accent", "accent text"))
        println(paint("ok",     "ok text"))
        println(paint("warn",   "warn text"))
        println(paint("fail",   "fail text"))
        println(paint("mute",   "mute text"))
        return 0
    end if
    if scenario == "glyphs_unicode" or scenario == "glyphs_ascii"
        g_mode = detect_rich_mode()
        println(glyph_ok() + " " + glyph_starting() + " " +
                glyph_fail() + " " + glyph_pending())
        return 0
    end if
    if scenario == "sigil_rich"
        g_mode = detect_rich_mode()
        println(sigil() + " zyginit 0.1.3")
        return 0
    end if
```

- [ ] **Step 5: Build and verify snapshots**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

By-hand sanity:
- `palette_true.txt` contains `\x1b[38;2;` truecolor escapes.
- `palette_16.txt` contains `\x1b[37m` etc — no truecolor.
- `glyphs_unicode.txt`: `● ◉ ✕ ·`
- `glyphs_ascii.txt`: `# o X .`
- `sigil_rich.txt` starts with `\x1b[38;2;0;106;111m[Z]\x1b[0m`.

- [ ] **Step 6: Commit**

```sh
hg add tests/integration/snapshots/*.txt
hg commit -m "ui: palette + glyph + sigil primitives with mode-aware fallback"
```

---

## Task 4: Boot header + rolling tape

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Failing snapshot for boot tape scenario**

In `tests/integration/ui_tests.sh`:

```sh
check_scenario boot_tape_rich  "TERM=xterm-256color"
check_scenario boot_tape_ascii "TERM=xterm ZYGINIT_ASCII=1"
check_scenario boot_tape_plain "ZYGINIT_NO_UI=1"
```

Run: `./tests/integration/ui_tests.sh` → FAIL.

- [ ] **Step 2: Implement tape state + header + emit_started/failed**

Add to `src/ui.reef`:

```reef
// Layout constants.
fn TAPE_HEIGHT(): int return 12 end TAPE_HEIGHT
fn LINE_WIDTH(): int  return 78 end LINE_WIDTH

// Boot/shutdown phase tracker for the header.
mut g_phase: string = ""        // "boot" | "shutdown"
mut g_runlevel: string = ""
mut g_num_svc: int = 0
mut g_num_tiers: int = 0
mut g_cur_tier: int = 0
mut g_done: int = 0
mut g_failed_count: int = 0
mut g_failed_first: string = ""
mut g_failed_first_exit: int = 0
mut g_boot_start_ms: int = 0    // monotonic ms at boot start

// Rolling tape: ring buffer of TAPE_HEIGHT lines.
type TapeLine = struct
    elapsed_ms: int
    glyph: string
    name: string
    note: string
end TapeLine

mut g_tape: [TapeLine] = new [TapeLine](12)
mut g_tape_head: int = 0
mut g_tape_count: int = 0

// time_now_ms: monotonic milliseconds. Wraps sys.time.time_now_ms when
// available; for the demo path we read a static counter.
extern "C" fn zyginit_monotonic_ms(): int

proc tape_push(elapsed_ms: int, glyph: string, name: string, note: string)
    let slot = g_tape_head mod TAPE_HEIGHT()
    g_tape[slot] = TapeLine{ elapsed_ms: elapsed_ms, glyph: glyph,
                             name: name, note: note }
    g_tape_head = g_tape_head + 1
    if g_tape_count < TAPE_HEIGHT()
        g_tape_count = g_tape_count + 1
    end if
end tape_push

// Format a tape row (mode-aware coloring on the glyph).
fn fmt_tape_row(line: TapeLine): string
    let secs = line.elapsed_ms / 1000
    let frac = (line.elapsed_ms mod 1000) / 10
    mut sf = int_to_str(frac)
    if str.length(sf) < 2  sf = str.concat("0", sf)  end if
    let elapsed = int_to_str(secs) + "." + sf
    // Pad elapsed to 6 cols right-aligned.
    mut pad = ""
    let pad_n = 6 - str.length(elapsed)
    mut i = 0
    while i < pad_n
        pad = str.concat(pad, " ")
        i = i + 1
    end while
    mut row = pad + elapsed + "  " + line.glyph + "  " + line.name
    if str.length(line.note) > 0
        row = str.concat(row, "  ")
        row = str.concat(row, paint("mute", "(" + line.note + ")"))
    end if
    return row
end fmt_tape_row

// Header banner + summary + failed-line + divider. 4 rows.
fn fmt_header(elapsed_ms: int): string
    let secs = elapsed_ms / 1000
    let frac = (elapsed_ms mod 1000) / 100
    let elapsed = int_to_str(secs) + "." + int_to_str(frac) + "s"
    let phase_label = g_phase + " · " + g_runlevel
    mut out = "  " + sigil() + " zyginit 0.1.3 · " + paint("frame", phase_label)
    out = str.concat(out, "  ")
    // pad to ~LINE_WIDTH then append elapsed
    out = str.concat(out, paint("accent", "elapsed " + elapsed))
    out = str.concat(out, "\n")
    out = str.concat(out, "  ")
    out = str.concat(out, paint("frame",
        int_to_str(g_num_svc) + " services · tier " + int_to_str(g_cur_tier)
        + " · " + int_to_str(g_done) + " done · "
        + int_to_str(g_failed_count) + " failed"))
    out = str.concat(out, "\n  ")
    if g_failed_count == 0
        out = str.concat(out, paint("mute", "failed: none"))
    else if g_failed_count == 1
        out = str.concat(out, paint("fail",
            "failed: " + g_failed_first + "  exit=" + int_to_str(g_failed_first_exit)))
    else
        out = str.concat(out, paint("fail",
            "failed: " + int_to_str(g_failed_count) + " services"))
    end if
    out = str.concat(out, "\n  ")
    mut div = ""
    mut k = 0
    while k < 62
        div = str.concat(div, "─")
        k = k + 1
    end while
    out = str.concat(out, paint("accent", div))
    return out
end fmt_header

// Render the entire screen for the current state.
fn render_boot_screen(elapsed_ms: int): string
    if g_mode == MODE_PLAIN()
        // Plain mode: no fixed regions; tape rows printed live as events fire.
        return ""
    end if
    mut out = fmt_header(elapsed_ms) + "\n"
    let start = g_tape_head - g_tape_count
    mut i = 0
    while i < TAPE_HEIGHT()
        if i < g_tape_count
            let slot = (start + i) mod TAPE_HEIGHT()
            out = str.concat(out, fmt_tape_row(g_tape[slot]))
        end if
        out = str.concat(out, "\n")
        i = i + 1
    end while
    return out
end render_boot_screen

// Lifecycle entry points.
proc ui_boot_start(num_svc: int, num_tiers: int, runlevel: string)
    g_phase = "boot"
    g_runlevel = runlevel
    g_num_svc = num_svc
    g_num_tiers = num_tiers
    g_cur_tier = 0
    g_done = 0
    g_failed_count = 0
    g_failed_first = ""
    g_failed_first_exit = 0
    g_tape_head = 0
    g_tape_count = 0
    g_boot_start_ms = zyginit_monotonic_ms()
end ui_boot_start

proc ui_tier_start(tier: int)
    g_cur_tier = tier
end ui_tier_start

proc ui_tier_done(tier: int)
    // Header repaint happens on next emit/tick.
end ui_tier_done

proc ui_event_started(name: string, dur_ms: int)
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    g_done = g_done + 1
    tape_push(elapsed, paint("ok", glyph_ok()), name, "")
    emit_or_redraw(elapsed)
end ui_event_started

proc ui_event_failed(name: string, exit_code: int, dur_ms: int)
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    g_done = g_done + 1
    g_failed_count = g_failed_count + 1
    if g_failed_count == 1
        g_failed_first = name
        g_failed_first_exit = exit_code
    end if
    tape_push(elapsed, paint("fail", glyph_fail()), name,
              "exit=" + int_to_str(exit_code))
    emit_or_redraw(elapsed)
end ui_event_failed

// In plain mode: print one line. In rich mode: clear screen and redraw.
proc emit_or_redraw(elapsed_ms: int)
    if g_mode == MODE_PLAIN()
        // Find the most recent tape row and emit it as a plain line.
        if g_tape_count == 0  return  end if
        let last = (g_tape_head - 1) mod TAPE_HEIGHT()
        let line = g_tape[last]
        let level = "info"
        let event = "started"
        // Crude: failure glyph means we render as failed.
        if str.index_of(line.glyph, glyph_fail()) >= 0
            println(fmt_plain_event(elapsed_ms, "err", "failed",
                line.name, line.note))
        else
            println(fmt_plain_event(elapsed_ms, "info", "started",
                line.name, line.note))
        end if
        return
    end if
    // Rich mode: CSI 2J (clear) + CSI H (home).
    print("\x1b[2J\x1b[H")
    print(render_boot_screen(elapsed_ms))
end emit_or_redraw
```

Add `zyginit_monotonic_ms` to `src/helpers.c`:

```c
#include <time.h>
int zyginit_monotonic_ms(void) {
    struct timespec ts;
    if (clock_gettime(CLOCK_MONOTONIC, &ts) != 0) return 0;
    return (int)((ts.tv_sec * 1000) + (ts.tv_nsec / 1000000));
}
```

- [ ] **Step 3: Add boot_tape demo scenario**

In `ui_demo`:

```reef
    if scenario == "boot_tape_rich" or scenario == "boot_tape_ascii" or
       scenario == "boot_tape_plain"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        // Hand-rolled event sequence so snapshots are deterministic.
        // Override monotonic_ms by setting g_boot_start_ms to 0 and emitting
        // explicit elapsed values via direct tape_push.
        g_boot_start_ms = 0
        let elapsed_seq = [40, 160, 310, 490, 1040, 1080, 1360, 1550]
        let name_seq = ["root-fs", "crypto", "devfs", "swap",
                        "filesystem", "identity", "sysconfig", "dlmgmtd"]
        mut i = 0
        while i < 8
            g_done = g_done + 1
            tape_push(elapsed_seq[i], paint("ok", glyph_ok()), name_seq[i], "")
            i = i + 1
        end while
        // Inject one failure.
        g_failed_count = 1
        g_failed_first = "network"
        g_failed_first_exit = 1
        g_cur_tier = 5
        g_done = g_done + 1
        tape_push(5020, paint("fail", glyph_fail()), "network", "exit=1")
        // Render once.
        if g_mode == MODE_PLAIN()
            // Plain: re-emit the 9 events.
            let levels = ["info","info","info","info","info","info","info","info","err"]
            let evs    = ["started","started","started","started",
                          "started","started","started","started","failed"]
            let allnames = ["root-fs","crypto","devfs","swap",
                            "filesystem","identity","sysconfig","dlmgmtd","network"]
            let allelap  = [40,160,310,490,1040,1080,1360,1550,5020]
            mut j = 0
            while j < 9
                let kv = ""
                let kv2 = if evs[j] == "failed" then "exit=1" else "" end
                println(fmt_plain_event(allelap[j], levels[j], evs[j],
                                        allnames[j], kv2))
                j = j + 1
            end while
        else
            print(render_boot_screen(5020))
        end if
        return 0
    end if
```

(Note: the `if ... then ... else ... end` ternary form may differ in Reef
syntax; if it doesn't compile, fall back to a small helper that returns the
right string.)

- [ ] **Step 4: Build, run, sanity-check snapshots**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Inspect:
- `boot_tape_rich.txt` — should show the 4-row header with truecolor escapes around `[Z]`, the `failed: network exit=1` line in red, and a tape with 9 rows. The `network` row has the `✕` glyph in red.
- `boot_tape_ascii.txt` — same shape but `#` and `X` glyphs, no truecolor escapes (16-color only).
- `boot_tape_plain.txt` — 9 plain machine-parseable lines; no escapes.

If the rendered tape is misaligned, fix `fmt_tape_row` padding before moving on.

- [ ] **Step 5: Commit**

```sh
hg add tests/integration/snapshots/boot_tape_*.txt
hg commit -m "ui: boot header + rolling tape + emit_or_redraw"
```

---

## Task 5: Progress bar

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Failing snapshot for progress bar**

In `tests/integration/ui_tests.sh`:

```sh
check_scenario progress_rich  "TERM=xterm-256color"
check_scenario progress_ascii "TERM=xterm ZYGINIT_ASCII=1"
check_scenario progress_full  "TERM=xterm-256color"   # 17/17 done
```

Run → FAIL.

- [ ] **Step 2: Implement `fmt_progress_bar` and append to `render_boot_screen`**

Add to `src/ui.reef`:

```reef
fn PROGRESS_WIDTH(): int return 36 end PROGRESS_WIDTH

fn fmt_progress_bar(done: int, total: int): string
    if g_mode == MODE_PLAIN()  return ""  end if
    let width = PROGRESS_WIDTH()
    mut filled = 0
    if total > 0
        filled = (done * width) / total
    end if
    if filled > width  filled = width  end if
    let pct = if total > 0 then (done * 100) / total else 0 end
    mut bar = ""
    if g_mode == MODE_RICH_ASCII()
        // [#########          ] form
        bar = str.concat(bar, "[")
        mut i = 0
        while i < (width - 2)
            if i < ((filled * (width - 2)) / width)
                bar = str.concat(bar, "#")
            else
                bar = str.concat(bar, " ")
            end if
            i = i + 1
        end while
        bar = str.concat(bar, "]")
    else
        mut i = 0
        while i < width
            if i < filled
                bar = str.concat(bar, paint("accent", "█"))
            else
                bar = str.concat(bar, paint("mute", "░"))
            end if
            i = i + 1
        end while
    end if
    return "  " + bar + "  " + int_to_str(done) + "/" + int_to_str(total)
                + "  " + int_to_str(pct) + "%"
end fmt_progress_bar
```

Modify `render_boot_screen` to append:

```reef
    // Inside render_boot_screen, after the tape loop, before return:
    mut div = ""
    mut k = 0
    while k < 62
        div = str.concat(div, "─")
        k = k + 1
    end while
    out = str.concat(out, "  ")
    out = str.concat(out, paint("accent", div))
    out = str.concat(out, "\n")
    out = str.concat(out, fmt_progress_bar(g_done, g_num_svc))
    out = str.concat(out, "\n")
    return out
```

- [ ] **Step 3: Add `progress_*` demo scenarios**

```reef
    if scenario == "progress_rich" or scenario == "progress_ascii"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        g_done = 12
        g_failed_count = 1
        print(fmt_progress_bar(g_done, g_num_svc))
        return 0
    end if
    if scenario == "progress_full"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        g_done = 17
        print(fmt_progress_bar(g_done, g_num_svc))
        return 0
    end if
```

- [ ] **Step 4: Build and inspect**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Check `progress_rich.txt` shows `█████████████░░░░...  12/17  70%`.
Check `progress_ascii.txt` shows `[####################          ]  12/17  70%`.
Check `progress_full.txt` shows `█` x 36 + `  17/17  100%`.

- [ ] **Step 5: Commit**

```sh
hg add tests/integration/snapshots/progress_*.txt
hg commit -m "ui: progress bar with block + ASCII fallback forms"
```

---

## Task 6: Spinner + ui_tick

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Failing snapshot for spinner frames**

```sh
check_scenario spinner_forward  "TERM=xterm-256color"
check_scenario spinner_reverse  "TERM=xterm-256color"
check_scenario spinner_in_tape  "TERM=xterm-256color"
```

Run → FAIL.

- [ ] **Step 2: Implement spinner state**

Add to `src/ui.reef`:

```reef
mut g_tick: int = 0
mut g_starting_name: string = ""    // service in STARTING state, if any
mut g_stopping_name: string = ""    // service in STOPPING state, if any

fn N_FRAMES(): int return 4 end N_FRAMES

fn ui_spinner_frame(reverse: bool): string
    let frames = ["/", "-", "\\", "|"]
    if reverse
        return frames[(N_FRAMES() - 1) - (g_tick mod N_FRAMES())]
    end if
    return frames[g_tick mod N_FRAMES()]
end ui_spinner_frame

proc ui_tick()
    g_tick = g_tick + 1
    if g_mode == MODE_PLAIN()  return  end if
    if str.length(g_starting_name) == 0 and str.length(g_stopping_name) == 0
        return
    end if
    // Just redraw the screen on each tick — the tape's last row holds the
    // currently-starting/stopping service, so its glyph updates.
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    print("\x1b[2J\x1b[H")
    print(render_boot_screen(elapsed))
end ui_tick

proc ui_event_starting(name: string)
    g_starting_name = name
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    tape_push(elapsed, paint("warn", ui_spinner_frame(false)), name, "starting")
    emit_or_redraw(elapsed)
end ui_event_starting

proc ui_event_stopping(name: string)
    g_stopping_name = name
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    tape_push(elapsed, paint("warn", ui_spinner_frame(true)), name, "stopping")
    emit_or_redraw(elapsed)
end ui_event_stopping
```

When `ui_event_started` or `ui_event_failed` fires, clear `g_starting_name`:

```reef
// At the top of ui_event_started and ui_event_failed:
g_starting_name = ""
```

And update `render_boot_screen` so the *active* spinner row's glyph reflects the current frame. The cleanest approach: when rendering the tape, if a row's `name` matches `g_starting_name`, replace its glyph with `paint("warn", ui_spinner_frame(false))`; if it matches `g_stopping_name`, use reverse.

Modify `fmt_tape_row` to accept and re-paint the spinner row, or — simpler — keep a separate `g_active_glyph` that `ui_tick` updates and that the renderer reads when emitting the matching row:

```reef
// In fmt_tape_row, before assembling `row`:
mut glyph = line.glyph
if str.length(g_starting_name) > 0 and line.name == g_starting_name
    glyph = paint("warn", ui_spinner_frame(false))
end if
if str.length(g_stopping_name) > 0 and line.name == g_stopping_name
    glyph = paint("warn", ui_spinner_frame(true))
end if
let row = pad + elapsed + "  " + glyph + "  " + line.name
```

(Update the assembled `row` accordingly.)

- [ ] **Step 3: Add spinner demo scenarios**

```reef
    if scenario == "spinner_forward"
        g_mode = detect_rich_mode()
        mut i = 0
        while i < 8
            g_tick = i
            print(ui_spinner_frame(false))
            i = i + 1
        end while
        println("")
        return 0
    end if
    if scenario == "spinner_reverse"
        g_mode = detect_rich_mode()
        mut i = 0
        while i < 8
            g_tick = i
            print(ui_spinner_frame(true))
            i = i + 1
        end while
        println("")
        return 0
    end if
    if scenario == "spinner_in_tape"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        g_boot_start_ms = 0
        // 3 done, 1 starting (deterministic frame 2 = "\\")
        tape_push(40, paint("ok", glyph_ok()), "root-fs", "")
        tape_push(160, paint("ok", glyph_ok()), "crypto", "")
        tape_push(310, paint("ok", glyph_ok()), "devfs", "")
        g_done = 3
        ui_event_starting("network")
        g_tick = 2  // force frame "\\"
        print("\x1b[2J\x1b[H")
        print(render_boot_screen(2100))
        return 0
    end if
```

- [ ] **Step 4: Build and verify**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Sanity:
- `spinner_forward.txt`: `/-\|/-\|`
- `spinner_reverse.txt`: `|\-/|\-/`
- `spinner_in_tape.txt`: tape rows show `root-fs ●`, `crypto ●`, `devfs ●`, then `network \` (frame index 2) with `(starting)` note.

- [ ] **Step 5: Commit**

```sh
hg add tests/integration/snapshots/spinner_*.txt
hg commit -m "ui: spinner with reverse rotation for stopping state"
```

---

## Task 7: Boot final card

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Failing snapshots**

```sh
check_scenario final_card_ok      "TERM=xterm-256color"
check_scenario final_card_failed  "TERM=xterm-256color"
```

- [ ] **Step 2: Implement `ui_boot_complete`**

Add to `src/ui.reef`:

```reef
type BootStats = struct
    elapsed_ms: int
    online: int
    failed: int
    slowest: [string]      // up to 3 entries: "name N.NNs"
end BootStats

proc ui_boot_complete(stats: BootStats)
    if g_mode == MODE_PLAIN()
        println(fmt_plain_event(stats.elapsed_ms, "info", "boot_complete",
                "summary", "online=" + int_to_str(stats.online)
                + " failed=" + int_to_str(stats.failed)))
        return
    end if
    // Clear screen, paint final card.
    print("\x1b[2J\x1b[H")
    let secs = stats.elapsed_ms / 1000
    let frac = (stats.elapsed_ms mod 1000) / 100
    let elapsed = int_to_str(secs) + "." + int_to_str(frac) + "s"
    let summary_count = int_to_str(stats.online + stats.failed)
    mut out = "  " + sigil() + " zyginit 0.1.3 · " +
              paint("frame", g_runlevel) + "  " +
              paint("accent", "boot " + elapsed) + "\n"
    out = str.concat(out, "  " + paint("frame",
        summary_count + " services — " + int_to_str(stats.online) + " online, "
        + int_to_str(stats.failed) + " failed") + "\n")
    out = str.concat(out, "\n")
    if stats.failed == 0
        out = str.concat(out, "  " + paint("ok", "all services online") + "\n")
    else if stats.failed == 1
        out = str.concat(out, "  " + paint("fail", "failed: " + g_failed_first +
            "  exit=" + int_to_str(g_failed_first_exit)) + "\n")
        out = str.concat(out, "      " +
            paint("accent", "→ zygctl log " + g_failed_first) +
            paint("mute", "    to see why") + "\n")
    else
        out = str.concat(out, "  " + paint("fail",
            "failed: " + int_to_str(stats.failed) + " services") + "\n")
        out = str.concat(out, "      " +
            paint("accent", "→ zygctl status") +
            paint("mute", "    to see them") + "\n")
    end if
    mut div = ""
    mut k = 0
    while k < 62
        div = str.concat(div, "─")
        k = k + 1
    end while
    out = str.concat(out, "  " + paint("accent", div) + "\n")
    if str.length_array(stats.slowest) > 0
        mut slow = "slowest:"
        mut i = 0
        while i < str.length_array(stats.slowest) and i < 3
            slow = str.concat(slow, "  ")
            slow = str.concat(slow, stats.slowest[i])
            i = i + 1
        end while
        out = str.concat(out, "  " + paint("frame", slow) + "\n")
    end if
    print(out)
end ui_boot_complete
```

(Note: `str.length_array` may be spelled `len()` in Reef — verify against `~/repos/reef-lang/docs/`. If different, swap to the correct name.)

- [ ] **Step 3: Add demo scenarios**

```reef
    if scenario == "final_card_ok"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        let stats = BootStats{
            elapsed_ms: 8300, online: 17, failed: 0,
            slowest: ["dlmgmtd 1.2s", "filesystem 0.55s", "sshd 0.37s"]
        }
        ui_boot_complete(stats)
        return 0
    end if
    if scenario == "final_card_failed"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        g_failed_first = "network"
        g_failed_first_exit = 1
        let stats = BootStats{
            elapsed_ms: 8300, online: 16, failed: 1,
            slowest: ["network 5.02s", "filesystem 0.55s", "sshd 0.37s"]
        }
        ui_boot_complete(stats)
        return 0
    end if
```

- [ ] **Step 4: Build and verify**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Inspect both snapshots by hand for layout and color escapes.

- [ ] **Step 5: Commit**

```sh
hg add tests/integration/snapshots/final_card_*.txt
hg commit -m "ui: boot final card (success and failure variants)"
```

---

## Task 8: Shutdown mirror + final card

**Files:**
- Modify: `src/ui.reef`
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Failing snapshots**

```sh
check_scenario shutdown_mirror   "TERM=xterm-256color"
check_scenario shutdown_final    "TERM=xterm-256color"
```

- [ ] **Step 2: Implement shutdown procs**

Add to `src/ui.reef`:

```reef
mut g_shutdown_reason: string = ""

proc ui_shutdown_start(reason: string)
    g_phase = "shutdown"
    g_shutdown_reason = reason
    g_runlevel = "stopping for " + reason
    g_done = 0       // counts services that have reached STOPPED
    g_failed_count = 0
    g_failed_first = ""
    g_failed_first_exit = 0
    g_tape_head = 0
    g_tape_count = 0
    g_boot_start_ms = zyginit_monotonic_ms()
end ui_shutdown_start

proc ui_event_stopped(name: string, dur_ms: int)
    g_stopping_name = ""
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    g_done = g_done + 1
    tape_push(elapsed, paint("mute", glyph_pending()), name, "")
    emit_or_redraw(elapsed)
end ui_event_stopped

proc ui_shutdown_complete(reason: string, elapsed_ms: int)
    if g_mode == MODE_PLAIN()
        println(fmt_plain_event(elapsed_ms, "info", "shutdown_complete",
                reason, "down=" + int_to_str(g_done)))
        return
    end if
    print("\x1b[2J\x1b[H")
    let secs = elapsed_ms / 1000
    let frac = (elapsed_ms mod 1000) / 100
    let elapsed = int_to_str(secs) + "." + int_to_str(frac) + "s"
    mut out = "  " + sigil() + " zyginit 0.1.3 · " +
              paint("frame", reason + " complete") + "  " +
              paint("accent", reason + " " + elapsed) + "\n"
    let stat = if g_failed_count == 0 then "stopped cleanly"
               else "stopped (" + int_to_str(g_failed_count) +
                    " force-killed)" end
    out = str.concat(out, "  " + paint("frame",
        int_to_str(g_num_svc) + " services " + stat) + "\n")
    mut div = ""
    mut k = 0
    while k < 62
        div = str.concat(div, "─")
        k = k + 1
    end while
    out = str.concat(out, "  " + paint("accent", div) + "\n")
    out = str.concat(out, "  " + paint("mute",
        "invoking uadmin(A_SHUTDOWN, AD_BOOT)") + "\n")
    print(out)
end ui_shutdown_complete
```

The progress bar already works in shutdown direction because it computes
`done / total`. Update `fmt_progress_bar` to show "down" when `g_phase == "shutdown"`:

```reef
    let label = if g_phase == "shutdown" then " down" else "" end
    return "  " + bar + "  " + int_to_str(done) + "/" + int_to_str(total)
                + label + "  " + int_to_str(pct) + "%"
```

- [ ] **Step 3: Add demo scenarios**

```reef
    if scenario == "shutdown_mirror"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        ui_shutdown_start("reboot")
        g_boot_start_ms = 0
        tape_push(40,  paint("mute", glyph_pending()), "sshd", "")
        tape_push(160, paint("mute", glyph_pending()), "console-login", "")
        tape_push(310, paint("mute", glyph_pending()), "cron", "")
        ui_event_stopping("syslogd")
        g_tick = 3   // force last frame "/"
        g_done = 4
        g_cur_tier = 6
        print("\x1b[2J\x1b[H")
        print(render_boot_screen(480))
        return 0
    end if
    if scenario == "shutdown_final"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        ui_shutdown_start("reboot")
        g_num_svc = 17
        g_done = 17
        ui_shutdown_complete("reboot", 2100)
        return 0
    end if
```

- [ ] **Step 4: Build and verify**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Inspect:
- `shutdown_mirror.txt` — reverse spinner on `syslogd` row (frame `/`), header says "stopping for reboot".
- `shutdown_final.txt` — final card with "reboot complete" and "stopped cleanly".

- [ ] **Step 5: Commit**

```sh
hg add tests/integration/snapshots/shutdown_*.txt
hg commit -m "ui: shutdown mirror + shutdown final card"
```

---

## Task 9: `zygctl status` server-side rendering + PLAIN modifier

**Files:**
- Modify: `src/ui.reef` (add `ui_render_status`)
- Modify: `src/socket.reef` (delegate `cmd_status`)
- Modify: `tests/integration/run_tests.sh` (add tests, set ZYGINIT_NO_UI=1)

- [ ] **Step 1: Failing test in the integration harness**

In `tests/integration/run_tests.sh`, add toward the end (after existing tests):

```sh
echo "TEST: zygctl status renders banner+table when not piped"
$ZYGINIT &
sleep 0.5
out=$(script -qfc "$ZYGCTL status" /dev/null 2>&1)
echo "$out" | grep -q "\[Z\] zyginit" || fail "expected [Z] sigil in TTY status output"
echo "$out" | grep -q "SERVICE" || fail "expected SERVICE column header"
pass

echo "TEST: zygctl status returns plain when piped"
out=$($ZYGCTL status | cat)
echo "$out" | grep -q "\[Z\]" && fail "did not expect sigil in piped output"
echo "$out" | grep -q "SERVICE" || fail "expected SERVICE column header even in plain"
pass
```

And ensure `ZYGINIT_NO_UI` is unset for these specific tests (the boot UI of the daemon is irrelevant — only the rendered status response).

- [ ] **Step 2: Run integration suite — confirm failure**

```sh
./tests/integration/run_tests.sh
```

Expected: the two new tests fail (sigil absent because the renderer hasn't been wired).

- [ ] **Step 3: Add `ui_render_status` to `src/ui.reef`**

```reef
fn ui_render_status(table: supervisor.ServiceTable,
                    want_banner: int, plain: int): string
    let count = supervisor.service_count(table)
    let prev_mode = g_mode
    if plain != 0
        g_mode = MODE_PLAIN()
    end if
    mut out = ""
    // Compute summary counts.
    mut online = 0
    mut failed = 0
    mut i = 0
    while i < count
        let rt = supervisor.get_runtime(table, i)
        let st = supervisor.rt_state(rt)
        if st == supervisor.STATE_RUNNING()
            online = online + 1
        else if st == supervisor.STATE_FAILED() or
                st == supervisor.STATE_MAINTENANCE()
            failed = failed + 1
        end if
        i = i + 1
    end while
    if want_banner != 0 and g_mode != MODE_PLAIN()
        out = str.concat(out, "  " + sigil() + " zyginit 0.1.3 · ")
        out = str.concat(out, paint("frame", "multi-user · " +
            int_to_str(count) + " services · " +
            int_to_str(online) + " online, " +
            int_to_str(failed) + " failed") + "\n")
        mut div = ""
        mut k = 0
        while k < 62
            div = str.concat(div, "─")
            k = k + 1
        end while
        out = str.concat(out, "  " + paint("accent", div) + "\n")
    end if
    // Column header.
    out = str.concat(out, "  ")
    out = str.concat(out, paint("frame",
        pad_right("SERVICE", 14) +
        pad_right("STATE", 11) +
        pad_right("PID", 7) +
        pad_right("CTID", 7) +
        pad_right("UPTIME", 10) +
        "NOTES"))
    out = str.concat(out, "\n")
    // Service rows.
    mut j = 0
    while j < count
        let rt = supervisor.get_runtime(table, j)
        out = str.concat(out, fmt_status_row(rt))
        out = str.concat(out, "\n")
        j = j + 1
    end while
    g_mode = prev_mode
    return out
end ui_render_status

fn fmt_status_row(rt): string
    // Implementation detail: read fields from the runtime struct (consult
    // src/supervisor.reef for accessor names). Output one row:
    //    name        glyph state    pid    ctid    uptime    notes
    // For plain mode: no glyph, no escapes.
    // Re-use the existing supervisor.format_duration() helper for uptime.
    // …pseudo-code body…
    return "  …"
end fmt_status_row

fn pad_right(s: string, n: int): string
    let extra = n - str.length(s)
    if extra <= 0  return s  end if
    mut out = s
    mut i = 0
    while i < extra
        out = str.concat(out, " ")
        i = i + 1
    end while
    return out
end pad_right
```

Fill in `fmt_status_row` body using the existing runtime accessors in
`src/supervisor.reef:835` (`get_status_line`). Reuse its logic for
uptime / exit_code / restart_count, but format as columns with the glyph in
the STATE column. State → glyph mapping:

- `STATE_RUNNING` → `glyph_ok()` + " running"
- `STATE_EXITED` (oneshot success) → `glyph_ok()` + " online"
- `STATE_STARTING` → `glyph_starting()` + " starting"
- `STATE_STOPPING` → `glyph_starting()` + " stopping"
- `STATE_STOPPED` → `glyph_pending()` + " stopped"
- `STATE_FAILED` → `glyph_fail()` + " failed"
- `STATE_MAINTENANCE` → `glyph_fail()` + " maint."

- [ ] **Step 4: Wire `cmd_status` to delegate**

Add a single-row renderer to `src/ui.reef` (avoids needing a "subtable"
abstraction):

```reef
fn ui_render_status_one(table: supervisor.ServiceTable, idx: int,
                        plain: int): string
    let prev_mode = g_mode
    if plain != 0  g_mode = MODE_PLAIN()  end if
    let rt = supervisor.get_runtime(table, idx)
    let row = fmt_status_row(rt) + "\n"
    g_mode = prev_mode
    return row
end ui_render_status_one
```

Then in `src/socket.reef`, replace the body of `cmd_status` (around line 261):

```reef
fn cmd_status(table: supervisor.ServiceTable, arg: string): string
    let count = supervisor.service_count(table)
    if str.length(arg) > 0
        let idx = supervisor.find_service(table, arg)
        if idx < 0
            return "error: unknown service: " + arg + "\n"
        end if
        return ui.ui_render_status_one(table, idx, 1)
    end if
    if count == 0
        return "no services loaded\n"
    end if
    return ui.ui_render_status(table, 1, 0)
end cmd_status
```

- [ ] **Step 5: Add the `STATUS PLAIN` wire modifier**

In `src/socket.reef`, find the request parser (the dispatch around
`cmd_status` / `cmd_list`). Adjust to accept a trailing `PLAIN` token:

```reef
// Existing dispatch (rough shape):
//   "STATUS" → cmd_status(table, "")
//   "STATUS sshd" → cmd_status(table, "sshd")
// New:
//   "STATUS PLAIN" → cmd_status_plain(table, "")
//   "STATUS PLAIN sshd" → cmd_status_plain(table, "sshd")
fn cmd_status_plain(table: supervisor.ServiceTable, arg: string): string
    if str.length(arg) > 0
        let idx = supervisor.find_service(table, arg)
        if idx < 0  return "error: unknown service: " + arg + "\n"  end if
        let one_table = supervisor.subtable(table, idx)
        return ui.ui_render_status(one_table, 0, 1)
    end if
    return ui.ui_render_status(table, 0, 1)
end cmd_status_plain
```

Update the request tokenizer to recognize `STATUS PLAIN` before falling
through to `STATUS`.

- [ ] **Step 6: Build + run the integration suite**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
```

Both new tests should pass; existing 44 should remain green.

- [ ] **Step 7: Commit**

```sh
hg commit -m "ui+socket: zygctl status banner+table + STATUS PLAIN modifier"
```

- [ ] **Step 8: Add `ui_render_list` and wire `cmd_list`**

`zygctl list` keeps its minimal one-line-per-service shape but adds a
small enhancement: enabled state, and color on the type chip when not
plain. Add to `src/ui.reef`:

```reef
fn ui_render_list(table: supervisor.ServiceTable, plain: int): string
    let count = supervisor.service_count(table)
    if count == 0  return "no services loaded\n"  end if
    let prev_mode = g_mode
    if plain != 0  g_mode = MODE_PLAIN()  end if
    mut out = ""
    mut i = 0
    while i < count
        let rt = supervisor.get_runtime(table, i)
        let def = supervisor.rt_def(rt)
        let name = config.svc_name(def)
        let stype = config.service_type_name(config.svc_type(def))
        let enabled = supervisor.rt_enabled(rt)
        let chip = paint("accent", stype)
        let enabled_str = if enabled then "enabled" else "disabled" end
        out = str.concat(out, name)
        out = str.concat(out, " (")
        out = str.concat(out, chip)
        out = str.concat(out, ", ")
        out = str.concat(out, enabled_str)
        out = str.concat(out, ")\n")
        i = i + 1
    end while
    g_mode = prev_mode
    return out
end ui_render_list
```

If `supervisor.rt_enabled` doesn't exist, fall back to `true` (every
service in the table is enabled, since that's how it got loaded).

In `src/socket.reef`, replace `cmd_list` body:

```reef
fn cmd_list(table: supervisor.ServiceTable): string
    return ui.ui_render_list(table, 0)
end cmd_list

fn cmd_list_plain(table: supervisor.ServiceTable): string
    return ui.ui_render_list(table, 1)
end cmd_list_plain
```

Add `LIST PLAIN` to the request tokenizer alongside `STATUS PLAIN`.

- [ ] **Step 9: Build + verify list rendering**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/run_tests.sh
```

The existing `zygctl list` tests should still pass (the response now
contains `(type, enabled)` instead of `(type)` — if any test does an exact
string match, update it to match the new shape).

- [ ] **Step 10: Commit**

```sh
hg commit -m "ui+socket: zygctl list enabled chip + LIST PLAIN modifier"
```

---

## Task 10: zygctl client pre-flight + STATUS PLAIN / LIST PLAIN dispatch

**Files:**
- Modify: `tools/zygctl/src/main.reef`

- [ ] **Step 1: Failing assertion is already in place from Task 9**

(Both tests added in Task 9 still need the client side to dispatch correctly. The server side renders correctly only if asked.)

- [ ] **Step 2: Add `detect_rich_mode` equivalent in zygctl client**

In `tools/zygctl/src/main.reef`, add near the top (above `cmd_status` /
client dispatch):

```reef
extern "C" fn zyginit_isatty(fd: int): int

fn client_should_be_plain(): bool
    if env.has_env("NO_COLOR")  return true  end if
    if zyginit_isatty(1) == 0   return true  end if
    let term = env.get_env_or("TERM", "")
    if str.length(term) == 0    return true  end if
    if term == "dumb"           return true  end if
    return false
end client_should_be_plain
```

Note: `zygctl` already links `symlink_wrapper.c`. Add the `zyginit_isatty`
function to that same file (it's a thin POSIX call, no special wiring):

```c
#include <unistd.h>
int zyginit_isatty(int fd) {
    return isatty(fd) ? 1 : 0;
}
```

- [ ] **Step 3: Update the `status` dispatch in `tools/zygctl/src/main.reef`**

Find where `status` builds its socket request (~line 60 area, exact line
depends on current rev). Replace with:

```reef
    if cmd == "status"
        mut req = "STATUS"
        if client_should_be_plain()
            req = "STATUS PLAIN"
        end if
        if str.length(arg) > 0
            req = req + " " + arg
        end if
        send_to_socket(req)
        return
    end if
    if cmd == "list"
        mut req = "LIST"
        if client_should_be_plain()
            req = "LIST PLAIN"
        end if
        send_to_socket(req)
        return
    end if
```

(`send_to_socket` is whatever helper the existing code uses for the same
purpose — keep the same call site.)

- [ ] **Step 4: Build + run**

```sh
(cd tools/zygctl && clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
```

The two zygctl status tests from Task 9 should now both pass.

- [ ] **Step 5: Commit**

```sh
hg commit -m "zygctl: TTY-aware dispatch (STATUS vs STATUS PLAIN)"
```

---

## Task 11: Wire ui_* calls into main.reef and supervisor.reef

**Files:**
- Modify: `src/main.reef`
- Modify: `src/supervisor.reef`

- [ ] **Step 1: Run the existing integration suite — capture baseline**

```sh
./tests/integration/run_tests.sh 2>&1 | tail -5
```

Should currently report 46 passing (44 original + 2 from Task 9).

- [ ] **Step 2: In `src/main.reef`, replace the boot-banner prints with ui calls**

Find the section in `src/main.reef:main()` where the daemon prints
`zyginit v0.1.3 starting`, `running as PID 1`, `booting into multi-user`,
`loaded N services`, etc. Replace with:

```reef
    let rich_mode = ui.detect_rich_mode()
    ui.ui_init(rich_mode)

    // Existing dep graph loading happens here…
    let svc_count = supervisor.service_count(g_table)
    let num_tiers = depgraph.tier_count(g_boot_order)
    let runlevel = if g_single_user then "single-user" else "multi-user" end
    ui.ui_boot_start(svc_count, num_tiers, runlevel)
```

Keep the existing `zyginit: …` warning/error prints — those route to log
files in rich mode (or stay on-console in plain mode, which is fine).

- [ ] **Step 3: Wrap each tier in `ui_tier_start` / `ui_tier_done`**

Find the tier-iteration loop (`for each tier in g_boot_order …`). Insert
calls:

```reef
    mut tier = 0
    while tier < num_tiers
        ui.ui_tier_start(tier)
        // …existing per-tier service start logic…
        ui.ui_tier_done(tier)
        tier = tier + 1
    end while
```

- [ ] **Step 4: Add `ui_tick` to the main poll loop**

In the steady-state poll loop, after `poll()` returns:

```reef
    ui.ui_tick()
```

This is cheap (no-op once boot completes and there are no STARTING/STOPPING
services).

- [ ] **Step 5: Call `ui_boot_complete` once all tiers finish**

After the tier loop and before "entering event loop":

```reef
    let stats = build_boot_stats(g_table, ...)  // collect online/failed/slowest
    ui.ui_boot_complete(stats)
```

`build_boot_stats` is a small helper that scans the service table and
computes online count, failed count, and the 3 slowest services by start
time. Add it inline in `main.reef`.

- [ ] **Step 6: Wire shutdown**

Find the existing `shutdown_services` / shutdown sequence. Wrap:

```reef
    ui.ui_shutdown_start(g_shutdown_reason)
    // …existing reverse-tier stop loop…
    ui.ui_shutdown_complete(g_shutdown_reason, total_elapsed_ms)
```

For each stop, in `supervisor.reef` (next step), `ui_event_stopping` and
`ui_event_stopped` will fire.

- [ ] **Step 7: In `src/supervisor.reef`, route lifecycle prints**

Find these lines (approximate refs from rev 122):

- `supervisor: started ${name}` near line 456 → replace with `ui.ui_event_started(name, dur_ms)`
- `supervisor: stopping ${name} (signal)` near line 490 → replace with `ui.ui_event_stopping(name)`
- `supervisor: ${name} stopped` near line 622 → replace with `ui.ui_event_stopped(name, dur_ms)`
- `supervisor: ${name} stopped (exit ${code})` near line 653 → replace with `ui.ui_event_failed(name, exit_code, dur_ms)` when exit_code != 0
- `supervisor: ${name} completed (oneshot)` near line 610 → `ui.ui_event_started(name, dur_ms)` (oneshot completion is "online")
- `supervisor: ${name} failed (oneshot, exit N)` near line 613 → `ui.ui_event_failed(...)`

Add `import ui` at the top of `src/supervisor.reef`.

For warning prints (`supervisor: ${name} stop timed out, killing`,
`entered maintenance`, `scheduled for restart`, etc.) — keep them as
`println` for now. They land in the log file under rich mode and on the
console under plain mode.

- [ ] **Step 8: Build and run integration suite**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
```

Expected: 46 pass. The integration harness sets `ZYGINIT_NO_UI=1` (added in
Task 12 below — set it manually for this run if needed), forcing plain
mode, so the assertions on string outputs don't shift.

- [ ] **Step 9: Run `./tests/integration/ui_tests.sh`**

All previous snapshots should still match.

- [ ] **Step 10: Commit**

```sh
hg commit -m "main+supervisor: route lifecycle prints through ui.reef"
```

---

## Task 12: Version bump, integration test hygiene, hh-prototest smoke

**Files:**
- Modify: `tests/integration/run_tests.sh` (set `ZYGINIT_NO_UI=1`)
- Run: `scripts/bump-version.sh 0.1.3`
- Modify: spec/plan dates / status if needed

- [ ] **Step 1: Force plain mode in the integration harness**

In `tests/integration/run_tests.sh`, near the existing `export ZYGINIT_*`
block:

```sh
export ZYGINIT_NO_UI=1
```

This keeps the boot UI from polluting integration-test output. The two
`zygctl status` tests added in Task 9 explicitly *unset* this var before
testing the rich vs plain dispatch.

- [ ] **Step 2: Verify the integration harness still passes end-to-end**

```sh
./tests/integration/run_tests.sh
./tests/integration/ui_tests.sh
```

Both should pass.

- [ ] **Step 3: Bump version 0.1.2 → 0.1.3**

```sh
./scripts/bump-version.sh 0.1.3
hg diff --stat
```

Expected: changes in `reef.toml`, `tools/zygctl/reef.toml`,
`tools/sysv-wrapper/Makefile`, `src/version.reef`,
`tools/zygctl/src/version.reef`. Verify with:

```sh
grep -nE 'version|VERSION' reef.toml tools/zygctl/reef.toml \
    src/version.reef tools/zygctl/src/version.reef
```

All should show `0.1.3`.

- [ ] **Step 4: Update spec doc-string references in `src/ui.reef`**

Any hardcoded `0.1.3` strings in the demo scenarios are intentional —
verify they still match by running the snapshot suite. If the snapshots
were captured at 0.1.2, the version-string change will produce diffs.
Re-run with snapshot regeneration:

```sh
rm tests/integration/snapshots/*.txt
./tests/integration/ui_tests.sh   # regenerates
hg diff tests/integration/snapshots/ | head -50
```

Confirm the only changes are `0.1.2 → 0.1.3` in the version strings.
Commit the regenerated snapshots.

- [ ] **Step 5: Hammerhead deploy + smoke test on hh-prototest**

```sh
# From dev host:
scp src/ui.reef src/helpers.c src/main.reef src/supervisor.reef \
    src/socket.reef tools/zygctl/src/main.reef tools/zygctl/src/symlink_wrapper.c \
    root@192.168.122.50:/root/zyginit/src/  # adjust paths per file

# Or rsync the whole tree:
rsync -av --exclude build/ . root@192.168.122.50:/root/zyginit/

# On hh-prototest:
ssh root@192.168.122.50 <<'EOF'
    cd /root/zyginit
    gcc -c src/helpers.c -o build/helpers.o
    reefc build -l contract --obj build/helpers.o
    cp build/zyginit /sbin/init.new
    mv /sbin/init.new /sbin/init
    cd tools/zygctl
    gcc -c src/symlink_wrapper.c -o build/symlink_wrapper.o
    reefc build --obj build/symlink_wrapper.o
    cp build/zygctl /sbin/zygctl.new
    mv /sbin/zygctl.new /sbin/zygctl
EOF

# Reboot the VM (init 6 from PID-1 zyginit is a real reboot now):
virsh --connect=qemu:///system reset hh-prototest

# Watch the boot via virsh console (or video out if you can capture):
virsh --connect=qemu:///system console hh-prototest
```

Verify visually:
- The boot screen shows the `[Z]` sigil, rolling tape, and progress bar
  in 256-color (Hammerhead framebuffer = `TERM=sun-color`).
- After all tiers complete, the final card appears with `boot N.Ns` and a
  summary line.
- `console-login` overwrites the card with the `Login:` prompt.
- Once logged in: `zygctl status` shows the banner+table in 256-color.

If anything looks wrong, capture screenshots and iterate. Note that polled
I/O is slow — pauses of ~100ms per redraw are expected and not a regression.

- [ ] **Step 6: Test shutdown**

From the SSH session on hh-prototest:

```sh
zygctl reboot
```

Expected screen: "stopping for reboot" header, services tick from `●` → `·`
in reverse tier order, final card "reboot complete · stopped cleanly", then
the kernel reset takes over.

- [ ] **Step 7: Commit and tag**

```sh
hg commit -m "release: bump to 0.1.3 (visual pass)"
hg tag v0.1.3
```

- [ ] **Step 8: Update auto-memory**

After deploy succeeds, the user will likely want a memory note. The plan
ends here; the user updates `MEMORY.md` and adds a `visual_pass.md` memory
file if they want to record the milestone.

---

## Self-review notes

- **Spec coverage:** every section of the design spec has at least one task implementing it. §4.3 spinner → Task 6. §5.1 boot tape → Task 4. §5.2 final card → Task 7. §5.3 shutdown mirror → Task 8. §5.5 `zygctl status` → Task 9 + 10. §6 render policy → Task 2 (`detect_rich_mode`). §7 error handling → covered inline in `emit_or_redraw` and the `g_failed` flag. §8 data flow → Task 11.
- **No placeholders:** every step has a concrete file path, code block, or shell command.
- **Type consistency:** `BootStats` defined in Task 7; `TapeLine` in Task 4; both used by name in later tasks.
- **Tests-first:** every task starts with a failing test (snapshot or integration).
- **Frequent commits:** every task ends with a focused `hg commit`.
- **YAGNI:** no speculative features. Spinner is event-driven, not timer-driven. No `tier_name` field. No graphical splash.
- **DRY:** `paint`, `glyph_*`, `fmt_plain_event`, `pad_right` factored once; reused everywhere.
# zyginit 0.2.0 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Ship 0.2.0 per `docs/superpowers/specs/2026-05-14-zyginit-0.2.0-design.md` — per-service directory layout, functional `task` type, `[condition]` block with SKIPPED state, plus migration tool. Hard-cut release.

**Architecture:** Three integrated changes that share the same `service.toml` schema. Layout reshape comes first (everything downstream consumes it); `task` semantics and `[condition]` block are independent additions to the supervisor and config parser. New UI counter (`g_skipped`) and event proc (`ui_event_skipped`). All work on Mercurial bookmark `visual-pass` on top of rev 166 (current tip after the spec commit).

**Tech Stack:** Reef 0.4+ (compiles to C via reefc), POSIX shell for the migration tool, Mercurial for VCS.

---

## File Structure

**Create:**
- `scripts/migrate-layout.sh` — migration tool (POSIX shell)
- `tests/integration/migrate_layout_tests.sh` — migration tool tests (POSIX shell)
- `tests/integration/fixtures/old-layout/` — fixture tree for migration tests
- `src/condition.reef` — new module: condition evaluation (`evaluate_conditions`, `ConditionResult`)

**Modify:**
- `src/config.reef` — rename `SERVICE_TYPE_TRANSIENT` → `SERVICE_TYPE_TASK`, add `[condition]` parser, change `scan_services` to walk `services/*/service.toml`, change `scan_enabled` to dereference directory symlinks with escape check
- `src/supervisor.reef` — add `task` branch in `handle_contract_event`; add `STATE_SKIPPED` constant + `skip_reason` field on `ServiceRuntime`; wire `evaluate_conditions` into `start_service`
- `src/ui.reef` — add `g_skipped` counter + `ui_event_skipped` proc; update `fmt_header` and `ui_boot_complete` to show skipped count; update `render_boot_screen` progress-bar denominator
- `src/ui_render.reef` — add `STATE_SKIPPED` mapping to `state_color` / `state_glyph` / `state_label`; show `skip_reason` in NOTES column
- `src/main.reef` — fatal error when `services/` directory missing; reset `g_skipped` alongside other counters
- `tools/zygctl/src/main.reef` — `enable`/`disable` create/remove symlinks targeting `../services/<name>/` (directory), not `<name>.toml` (file)
- `services/hammerhead/` — migrated to new layout in one commit
- `examples/` — migrated to new layout (or relocated under services/) in same commit
- `tests/integration/ui_tests.sh` — add 5 new scenarios (`task_ok`, `task_failed`, `boot_with_skipped`, `final_card_with_skipped`, `status_skipped`)
- `tests/integration/run_tests.sh` — adapt fixtures to new layout where needed
- `reef.toml`, `tools/zygctl/reef.toml`, `tools/sysv-wrapper/version.h`, `src/version.reef`, `tools/zygctl/src/version.reef` — version bump 0.1.8 → 0.2.0 via `scripts/bump-version.sh`

---

## Task 1: Migration tool

**Files:**
- Create: `scripts/migrate-layout.sh`
- Create: `tests/integration/migrate_layout_tests.sh`
- Create: `tests/integration/fixtures/old-layout/` (test fixture tree)

- [ ] **Step 1: Create the test fixture tree**

```sh
mkdir -p tests/integration/fixtures/old-layout/enabled.d
cat > tests/integration/fixtures/old-layout/cron.toml <<'EOF'
[service]
name = "cron"
type = "daemon"

[exec]
start = "/usr/sbin/cron"
EOF

cat > tests/integration/fixtures/old-layout/filesystem.toml <<'EOF'
[service]
name = "filesystem"
type = "oneshot"

[exec]
start = "./start.sh"
EOF

mkdir -p tests/integration/fixtures/old-layout/filesystem
cat > tests/integration/fixtures/old-layout/filesystem/start.sh <<'EOF'
#!/bin/sh
mount -a
EOF
chmod +x tests/integration/fixtures/old-layout/filesystem/start.sh

# Symlink in enabled.d targeting the old <name>.toml form
ln -s ../cron.toml tests/integration/fixtures/old-layout/enabled.d/cron
ln -s ../filesystem.toml tests/integration/fixtures/old-layout/enabled.d/filesystem
```

- [ ] **Step 2: Write the failing test harness**

Create `tests/integration/migrate_layout_tests.sh`:

```sh
#!/bin/sh
# Tests for scripts/migrate-layout.sh
set -e

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
PROJECT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
TOOL="$PROJECT_DIR/scripts/migrate-layout.sh"
FIXTURE_SRC="$SCRIPT_DIR/fixtures/old-layout"

PASS=0
FAIL=0

pass() { echo "  [pass]   $1";  PASS=$((PASS+1)); }
fail() { echo "  [FAIL]   $1"; echo "    $2"; FAIL=$((FAIL+1)); }

setup_tmp() {
    TMP=$(mktemp -d /tmp/migrate-test.XXXXXX)
    cp -a "$FIXTURE_SRC"/. "$TMP"/
    echo "$TMP"
}

# --- Test 1: --dry-run does not modify anything ---
TMP=$(setup_tmp)
BEFORE=$(find "$TMP" | sort)
"$TOOL" --dry-run --config-dir "$TMP" > /dev/null
AFTER=$(find "$TMP" | sort)
if [ "$BEFORE" = "$AFTER" ]; then
    pass "dry-run leaves tree unchanged"
else
    fail "dry-run leaves tree unchanged" "tree changed"
fi
rm -rf "$TMP"

# --- Test 2: --apply migrates flat layout to per-service directories ---
TMP=$(setup_tmp)
"$TOOL" --apply --config-dir "$TMP" > /dev/null
if [ -f "$TMP/services/cron/service.toml" ] && \
   [ -f "$TMP/services/filesystem/service.toml" ] && \
   [ -f "$TMP/services/filesystem/start.sh" ]; then
    pass "apply creates services/<name>/service.toml"
else
    fail "apply creates services/<name>/service.toml" "missing expected files"
fi
rm -rf "$TMP"

# --- Test 3: --apply retargets enabled.d symlinks to directories ---
TMP=$(setup_tmp)
"$TOOL" --apply --config-dir "$TMP" > /dev/null
target=$(readlink "$TMP/enabled.d/cron")
case "$target" in
    *services/cron) pass "enabled.d symlink targets directory" ;;
    *)              fail "enabled.d symlink targets directory" "got '$target'" ;;
esac
rm -rf "$TMP"

# --- Test 4: --apply is idempotent ---
TMP=$(setup_tmp)
"$TOOL" --apply --config-dir "$TMP" > /dev/null
SECOND=$("$TOOL" --apply --config-dir "$TMP" 2>&1)
if echo "$SECOND" | grep -q "already migrated\|nothing to migrate\|no changes"; then
    pass "apply is idempotent"
else
    fail "apply is idempotent" "second run did not report no-op"
fi
rm -rf "$TMP"

# --- Test 5: refuses when both old and new layout coexist ---
TMP=$(setup_tmp)
mkdir -p "$TMP/services/cron"
cp "$TMP/cron.toml" "$TMP/services/cron/service.toml"
# Now both $TMP/cron.toml and $TMP/services/cron/service.toml exist
set +e
"$TOOL" --apply --config-dir "$TMP" > /dev/null 2>&1
rc=$?
set -e
if [ "$rc" -ne 0 ]; then
    pass "refuses on ambiguous old+new coexistence"
else
    fail "refuses on ambiguous old+new coexistence" "exit was 0"
fi
rm -rf "$TMP"

echo
echo "passed: $PASS  failed: $FAIL"
[ "$FAIL" -eq 0 ]
```

Make it executable: `chmod +x tests/integration/migrate_layout_tests.sh`.

- [ ] **Step 3: Run tests to confirm they fail**

Run: `./tests/integration/migrate_layout_tests.sh`
Expected: FAILs — `scripts/migrate-layout.sh` doesn't exist yet.

- [ ] **Step 4: Implement the migration tool**

Create `scripts/migrate-layout.sh`:

```sh
#!/bin/sh
#
# Migrate a 0.1.x /etc/zyginit/ tree to the 0.2.0 per-service directory layout.
# Idempotent. Dry-run by default. Run with --apply to actually move files.
#
set -e

usage() {
    cat <<EOF
Usage: $0 [--dry-run|--apply] [--config-dir <path>]

  --dry-run         Print planned moves and exit (default)
  --apply           Perform the moves
  --config-dir DIR  Target directory (default /etc/zyginit/)
  -h, --help        Show this help
EOF
}

MODE=dry-run
CONFIG_DIR=/etc/zyginit

while [ $# -gt 0 ]; do
    case "$1" in
        --dry-run)    MODE=dry-run; shift ;;
        --apply)      MODE=apply; shift ;;
        --config-dir) CONFIG_DIR="$2"; shift 2 ;;
        -h|--help)    usage; exit 0 ;;
        *)            echo "error: unknown arg: $1" >&2; usage >&2; exit 2 ;;
    esac
done

if [ ! -d "$CONFIG_DIR" ]; then
    echo "error: $CONFIG_DIR is not a directory" >&2
    exit 1
fi

cd "$CONFIG_DIR"

# Ambiguity check: refuse if any service has BOTH <name>.toml at top level
# AND services/<name>/service.toml.
AMBIGUOUS=""
if [ -d services ]; then
    for f in *.toml; do
        [ -f "$f" ] || continue
        name="${f%.toml}"
        if [ -f "services/$name/service.toml" ]; then
            AMBIGUOUS="$AMBIGUOUS $name"
        fi
    done
fi
if [ -n "$AMBIGUOUS" ]; then
    echo "error: ambiguous layout — both old <name>.toml and services/<name>/service.toml exist for:$AMBIGUOUS" >&2
    echo "       Resolve manually before re-running." >&2
    exit 3
fi

# Plan moves
PLAN_FILE=$(mktemp /tmp/migrate-plan.XXXXXX)
trap 'rm -f "$PLAN_FILE"' EXIT

COUNT=0
for f in *.toml; do
    [ -f "$f" ] || continue
    name="${f%.toml}"
    echo "mkdir -p services/$name" >> "$PLAN_FILE"
    echo "mv $f services/$name/service.toml" >> "$PLAN_FILE"
    if [ -d "$name" ] && [ ! -L "$name" ]; then
        # Move helper scripts (start.sh, stop.sh, etc.) into the new dir
        for sf in "$name"/*; do
            [ -e "$sf" ] || continue
            base=$(basename "$sf")
            echo "mv $name/$base services/$name/$base" >> "$PLAN_FILE"
        done
        echo "rmdir $name" >> "$PLAN_FILE"
    fi
    COUNT=$((COUNT + 1))
done

# Plan enabled.d symlink retarget
if [ -d enabled.d ]; then
    for link in enabled.d/*; do
        [ -L "$link" ] || continue
        target=$(readlink "$link")
        case "$target" in
            *.toml)
                name=$(basename "$link")
                echo "ln -sfn ../services/$name $link" >> "$PLAN_FILE"
                ;;
        esac
    done
fi

# Plan examples/ migration (same convention as services/)
if [ -d examples ]; then
    for f in examples/*.toml; do
        [ -f "$f" ] || continue
        name=$(basename "${f%.toml}")
        echo "mkdir -p examples/$name" >> "$PLAN_FILE"
        echo "mv $f examples/$name/service.toml" >> "$PLAN_FILE"
    done
fi

if [ ! -s "$PLAN_FILE" ]; then
    echo "no changes — tree already in 0.2.0 layout"
    exit 0
fi

if [ "$MODE" = "dry-run" ]; then
    echo "PLANNED MOVES ($COUNT services):"
    cat "$PLAN_FILE"
    echo
    echo "Re-run with --apply to perform these moves."
    exit 0
fi

# Apply
echo "Applying $COUNT services..."
while IFS= read -r line; do
    eval "$line"
done < "$PLAN_FILE"
echo "Migration complete."
```

Make it executable: `chmod +x scripts/migrate-layout.sh`.

- [ ] **Step 5: Run tests to confirm they pass**

Run: `./tests/integration/migrate_layout_tests.sh`
Expected: 5/5 pass.

- [ ] **Step 6: Commit**

```sh
hg add scripts/migrate-layout.sh tests/integration/migrate_layout_tests.sh tests/integration/fixtures/
hg commit -m "scripts: migrate-layout.sh + tests — converts 0.1.x flat layout to 0.2.0 per-service dirs"
```

---

## Task 2: Layout parser in config.reef

**Files:**
- Modify: `src/config.reef`

The current parser scans `<config_dir>/*.toml` and uses the basename as the service name. New behavior: scan `<config_dir>/services/<name>/service.toml`; service name comes from the directory name.

- [ ] **Step 1: Identify current scan functions**

Read `src/config.reef` and find:
- The function that scans the config directory for service TOML files (likely `scan_services`, `load_services_from_dir`, or similar)
- The function that scans `enabled.d/` and dereferences symlinks

Note their current signatures and the call sites in `src/main.reef`.

- [ ] **Step 2: Rewrite the services scanner to walk `services/`**

Replace the implementation that walks `*.toml` at top level with one that walks `services/*/service.toml`. Reef-flavored:

```reef
fn scan_services_dir(config_dir: string, table: ServiceTable): int
    let services_root = str.concat(config_dir, "/services")
    if !io.dir.exists(services_root)
        // Fatal: empty boot
        println("zyginit: FATAL: services/ directory not found at " + services_root)
        println("zyginit: run scripts/migrate-layout.sh to convert a 0.1.x tree")
        return 0
    end if
    let dirs = io.dir.list(services_root)
    let n = array_length(dirs)   // or whatever Reef's array-length idiom is
    mut count = 0
    mut i = 0
    while i < n
        let name = dirs[i]
        let svc_dir = str.concat(str.concat(services_root, "/"), name)
        let toml_path = str.concat(svc_dir, "/service.toml")
        if !io.file.exists(toml_path)
            println("zyginit: services/" + name + "/ missing service.toml — skipping")
            i = i + 1
            continue
        end if
        let result = parse_service_toml(toml_path, name, svc_dir)
        if result.ok
            add_to_table(table, result.svc)
            count = count + 1
        else
            println("zyginit: services/" + name + "/service.toml parse error: " + result.error)
        end if
        i = i + 1
    end while
    return count
end scan_services_dir
```

`parse_service_toml(toml_path, name, svc_dir)` is the existing TOML parser plumbing renamed/restructured to:
- Take the **directory** path (`svc_dir`) so it can resolve `./start.sh`-style paths to absolute (`<svc_dir>/start.sh`).
- Use **name** as the service identifier (not a field in the TOML; if the TOML has `[service].name`, ignore or warn that it's unused now).

Match the project's existing parser style; this is a refactor rather than a from-scratch rewrite.

- [ ] **Step 3: Update path resolution for `./*.sh`**

In whatever section of `parse_service_toml` builds the executable path from `exec.start`, add: if the path starts with `./`, prepend `<svc_dir>/`. Absolute paths (starting with `/`) are unchanged.

```reef
fn resolve_exec_path(raw: string, svc_dir: string): string
    if str.starts_with(raw, "./")
        let rel = str.substring(raw, 2, str.length(raw) - 2)
        return str.concat(str.concat(svc_dir, "/"), rel)
    end if
    return raw
end resolve_exec_path
```

Apply to both `exec.start` and (if present) `exec.stop`.

- [ ] **Step 4: Rewrite enabled.d scanner with symlink dereference + escape check**

Update `scan_enabled_dir` (or equivalent) to:
- List `<config_dir>/enabled.d/`
- For each entry, `readlink` it (use `os.fs.readlink` or whatever Reef stdlib provides; add a C helper `zyginit_readlink` if needed)
- Resolve to an absolute path
- Verify it points inside `<config_dir>/services/`
- Reject (with warning log) if it escapes or is dangling

```reef
fn scan_enabled_dir(config_dir: string): [string]
    let enabled_root = str.concat(config_dir, "/enabled.d")
    let services_prefix = str.concat(config_dir, "/services/")
    let result = new [string](MAX_SERVICES)
    mut count = 0
    if !io.dir.exists(enabled_root)
        return result   // no enabled.d means nothing enabled
    end if
    let entries = io.dir.list(enabled_root)
    mut i = 0
    while i < array_length(entries)
        let entry = entries[i]
        let link_path = str.concat(str.concat(enabled_root, "/"), entry)
        let target = zyginit_readlink_resolved(link_path)
        if str.length(target) == 0
            println("zyginit: enabled.d/" + entry + " is dangling — ignoring")
            i = i + 1
            continue
        end if
        if !str.starts_with(target, services_prefix)
            println("zyginit: enabled.d/" + entry + " escapes services/ — ignoring")
            i = i + 1
            continue
        end if
        result[count] = entry
        count = count + 1
        i = i + 1
    end while
    return result
end scan_enabled_dir
```

If Reef stdlib doesn't have a "resolve a symlink to an absolute canonical path" function, add a C helper:

```c
/* in src/helpers.c */
#include <stdlib.h>
#include <limits.h>
static char zyginit_readlink_buf[PATH_MAX];
char *zyginit_readlink_resolved(char *path) {
    char *resolved = realpath(path, zyginit_readlink_buf);
    return resolved ? resolved : (char*)"";
}
```

And extern declare in config.reef:

```reef
extern "C" fn zyginit_readlink_resolved(path: string): string
```

- [ ] **Step 5: Build + verify**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Existing tests will FAIL at this point because the in-repo `services/hammerhead/` tree is still in the old layout. That's expected — Task 3 migrates it.

- [ ] **Step 6: Commit**

```sh
hg commit -m "config: scan services/<name>/service.toml; enabled.d symlinks target directories"
```

---

## Task 3: Migrate in-repo `services/hammerhead/` and `examples/`

**Files:**
- Modify: `services/hammerhead/*` (extensive)
- Modify: `examples/*` (if present)
- Modify: any test fixtures referencing the old layout

- [ ] **Step 1: Dry-run the migration on the in-repo tree**

```sh
./scripts/migrate-layout.sh --dry-run --config-dir services/hammerhead/
```

Verify the planned moves match the spec's per-service-directory layout. If the output looks right, proceed.

- [ ] **Step 2: Apply the migration**

```sh
./scripts/migrate-layout.sh --apply --config-dir services/hammerhead/
```

Verify each service is now `services/hammerhead/services/<name>/service.toml` plus any helper scripts in the same directory. The `services/hammerhead/services/<name>` nesting is intentional — `services/hammerhead/` is the deploy-root, and the per-service layout starts inside it.

- [ ] **Step 3: Migrate the examples directory if present**

```sh
ls examples/ 2>/dev/null && ./scripts/migrate-layout.sh --apply --config-dir examples/ || echo "no examples/ at top level"
```

If examples live under `services/hammerhead/examples/` instead, migrate that location.

- [ ] **Step 4: Update integration test fixtures**

In `tests/integration/run_tests.sh`, the harness creates temporary services at runtime. Find the section that writes `<TMP>/<name>.toml` and update it to write `<TMP>/services/<name>/service.toml`. Use a small helper at the top of the test script:

```sh
create_service() {
    name=$1
    toml_content=$2
    mkdir -p "$CONFIG_DIR/services/$name"
    printf '%s\n' "$toml_content" > "$CONFIG_DIR/services/$name/service.toml"
}

enable_service() {
    name=$1
    ln -sfn "../services/$name" "$ENABLED_DIR/$name"
}
```

Then update every existing test that calls `cat > "$CONFIG_DIR/<name>.toml"` to use `create_service` and every `ln -s` in `enabled.d/` to use `enable_service`.

- [ ] **Step 5: Build + run all tests**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
./tests/integration/ui_tests.sh
./tests/integration/migrate_layout_tests.sh
```

All should pass. If integration tests fail, the most likely cause is a missed test-fixture update — grep for `\.toml` in `tests/integration/run_tests.sh` to find any stragglers.

- [ ] **Step 6: Commit**

```sh
hg addremove   # picks up the moves
hg commit -m "services+tests: migrate in-repo trees to 0.2.0 per-service layout"
```

---

## Task 4: Update `zygctl enable`/`disable` symlink targets

**Files:**
- Modify: `tools/zygctl/src/main.reef` (and possibly `src/socket.reef` for the server-side equivalent if zygctl delegates)

- [ ] **Step 1: Find current enable/disable logic**

In `tools/zygctl/src/main.reef`, find the function that handles `zygctl enable <name>`. Currently it creates a symlink `<config_dir>/enabled.d/<name>` → `../<name>.toml`.

- [ ] **Step 2: Add a failing integration test**

In `tests/integration/run_tests.sh`, add (in the appropriate test suite around enable/disable):

```sh
echo "TEST: zygctl enable creates directory-target symlink"
create_service test-svc 'foo'
$ZYGCTL enable test-svc
target=$(readlink "$ENABLED_DIR/test-svc")
case "$target" in
    *services/test-svc) pass "zygctl enable targets directory" ;;
    *)                  fail "zygctl enable targets directory" "got: $target" ;;
esac
$ZYGCTL disable test-svc
```

(You'll need to wire `pass`/`fail` into the existing harness shape, or use whatever pattern the surrounding tests use.)

- [ ] **Step 3: Run test to confirm it fails**

```sh
./tests/integration/run_tests.sh
```

Expected: the new test fails (current zygctl creates a `<name>.toml` symlink, not a directory).

- [ ] **Step 4: Update the symlink target**

In `tools/zygctl/src/main.reef`, change the symlink-create call:

```reef
// Old:
let target = str.concat("../", str.concat(name, ".toml"))

// New:
let target = str.concat("../services/", name)
```

The link path stays the same (`enabled.d/<name>`).

- [ ] **Step 5: Build + run**

```sh
(cd tools/zygctl && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
```

Test should now pass.

- [ ] **Step 6: Commit**

```sh
hg commit -m "zygctl: enable/disable target services/<name>/ directory instead of <name>.toml"
```

---

## Task 5: Rename `TRANSIENT` → `TASK` + supervisor branch

**Files:**
- Modify: `src/config.reef`
- Modify: `src/supervisor.reef`

- [ ] **Step 1: Add a failing test for task semantics**

Add to `tests/integration/run_tests.sh` (in a new test suite or appropriate existing one):

```sh
echo "=== Task type semantics ==="

create_service task-success "$(cat <<'EOF'
[service]
type = "task"

[exec]
start = "/bin/true"
EOF
)"
enable_service task-success

create_service task-failure "$(cat <<'EOF'
[service]
type = "task"

[exec]
start = "/bin/false"
EOF
)"
enable_service task-failure

start_daemon
sleep 2

out=$($ZYGCTL status)
echo "$out" | grep -q "task-success.*stopped" && \
    pass "task exit 0 = stopped" || \
    fail "task exit 0 = stopped" "got: $(echo "$out" | grep task-success)"

echo "$out" | grep -q "task-failure.*failed" && \
    pass "task exit !=0 = failed" || \
    fail "task exit !=0 = failed" "got: $(echo "$out" | grep task-failure)"

# Verify no restart attempt — restart_count should be 0
echo "$out" | grep -E "task-failure.*restarts=" && \
    fail "task does not restart" "restarts field present" || \
    pass "task does not restart"

stop_daemon
```

(Use whatever start_daemon / stop_daemon helpers the existing tests use.)

- [ ] **Step 2: Run tests to confirm failure**

```sh
./tests/integration/run_tests.sh
```

Expected: the task-related assertions fail (parser rejects `type = "task"` or the supervisor doesn't handle it).

- [ ] **Step 3: Rename in `src/config.reef`**

```sh
hg cat -r tip src/config.reef | grep -n TRANSIENT
```

Find every occurrence of `SERVICE_TYPE_TRANSIENT` and `"transient"` in `src/config.reef`. Replace:
- `SERVICE_TYPE_TRANSIENT` → `SERVICE_TYPE_TASK` (function name + every call site)
- `"transient"` string literal in `service_type_name` and the parser → `"task"`

In the parser:

```reef
// Old:
if type_str == "transient"
    return SERVICE_TYPE_TRANSIENT()
end if

// New:
if type_str == "task"
    return SERVICE_TYPE_TASK()
end if
```

For `type = "transient"` in TOML: reject with a clear error message:

```reef
if type_str == "transient"
    println("error: type='transient' is no longer supported — rename to 'task' in your TOML")
    return SERVICE_TYPE_DAEMON()   // safe fallback to keep parser going
end if
```

- [ ] **Step 4: Add the supervisor task branch**

In `src/supervisor.reef`, find `handle_contract_event` and the point right after the exit-code resolution block (around line 598 in 0.1.8). Insert:

```reef
let svc_type = config.svc_type(def)

// Task: may run for any duration. Exit 0 = STOPPED (counts as online).
// Exit ≠ 0 = FAILED. Never restarts. Skips daemonize handshake.
if svc_type == config.SERVICE_TYPE_TASK()
    let dur_ms = (time.time_now() - rt.last_start_time) * 1000
    let ec = if exit_code >= 0 then exit_code else 0 end if
    rt.pid = 0 - 1
    rt.contract_id = 0 - 1
    rt.last_exit_code = ec
    table.contract_map.remove(int_to_str(contract_id))
    if ec == 0
        rt.state = STATE_STOPPED()
        table.runtimes[idx] = rt
        ui.ui_event_stopped(name, dur_ms)
    else
        rt.state = STATE_FAILED()
        table.runtimes[idx] = rt
        ui.ui_event_failed(name, ec, dur_ms)
    end if
    return
end if
```

This **must** be placed BEFORE the existing daemonize-handshake check (the `if svc_type == config.SERVICE_TYPE_DAEMON() and hint_exit_code >= 0 and exit_code == 0 ...` block).

- [ ] **Step 5: Build + run all tests**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
./tests/integration/ui_tests.sh
```

All should pass including the new task tests.

- [ ] **Step 6: Commit**

```sh
hg commit -m "config+supervisor: rename TRANSIENT to TASK with real semantics (exit 0 = stopped, exit != 0 = failed, no restart)"
```

---

## Task 6: `[condition]` schema and `evaluate_conditions`

**Files:**
- Create: `src/condition.reef`
- Modify: `src/config.reef` (parser additions)

- [ ] **Step 1: Define the ConditionResult type and entry signature**

Create `src/condition.reef`. Copy the SRCHEADER from existing modules; fill in:
- Project: `zyginit`
- Filename: `condition.reef`
- Description: `Evaluate [condition] blocks: exists_file, exists_file_any, command. Returns pass/fail + reason.`

Skeleton:

```reef
module condition

import core.str as str
import io.file as file
import sys.process as process

export
    type ConditionResult
    fn  evaluate_conditions(def: config.ServiceDef): ConditionResult
    fn  cond_passed(r: ConditionResult): bool
    fn  cond_reason(r: ConditionResult): string
end export

type ConditionResult = struct
    passed: bool
    reason: string
end ConditionResult

fn cond_passed(r: ConditionResult): bool
    return r.passed
end cond_passed

fn cond_reason(r: ConditionResult): string
    return r.reason
end cond_reason
```

- [ ] **Step 2: Add the parser for `[condition]` to config.reef**

In `src/config.reef`, extend `ServiceDef` with optional fields:

```reef
type ServiceDef = struct
    // ... existing fields ...
    cond_exists_file: string         // empty if not set
    cond_exists_file_any: [string]
    cond_exists_file_any_count: int  // companion length field
    cond_command: string             // empty if not set
end ServiceDef
```

In the TOML parser, find the section that walks parsed keys after `[exec]` and `[stop]` etc. Add a handler for `[condition]`:

```reef
// Inside the parse loop, when section == "condition":
if key == "exists_file"
    def.cond_exists_file = value_str
elif key == "exists_file_any"
    let arr = parse_string_array(value)
    def.cond_exists_file_any = arr
    def.cond_exists_file_any_count = array_length(arr)
elif key == "command"
    def.cond_command = value_str
else
    println("warning: unknown [condition] key: " + key)
end if
```

Match the existing TOML-parser shape; the project already has similar handlers for `[exec]`, `[restart]`, etc.

- [ ] **Step 3: Add accessor fns to ServiceDef**

In `src/config.reef`:

```reef
fn svc_cond_exists_file(svc: ServiceDef): string
    return svc.cond_exists_file
end svc_cond_exists_file

fn svc_cond_exists_file_any(svc: ServiceDef): [string]
    return svc.cond_exists_file_any
end svc_cond_exists_file_any

fn svc_cond_exists_file_any_count(svc: ServiceDef): int
    return svc.cond_exists_file_any_count
end svc_cond_exists_file_any_count

fn svc_cond_command(svc: ServiceDef): string
    return svc.cond_command
end svc_cond_command
```

Export each.

- [ ] **Step 4: Implement `evaluate_conditions` in condition.reef**

```reef
fn evaluate_conditions(def: config.ServiceDef): ConditionResult
    // exists_file
    let f = config.svc_cond_exists_file(def)
    if str.length(f) > 0
        if !file.exists(f)
            return ConditionResult{
                passed: false,
                reason: str.concat("missing ", f)
            }
        end if
    end if

    // exists_file_any
    let n = config.svc_cond_exists_file_any_count(def)
    if n > 0
        let paths = config.svc_cond_exists_file_any(def)
        mut found = false
        mut i = 0
        while i < n
            if file.exists(paths[i])
                found = true
            end if
            i = i + 1
        end while
        if !found
            return ConditionResult{
                passed: false,
                reason: "none of exists_file_any paths exist"
            }
        end if
    end if

    // command (with 5-second timeout)
    let cmd = config.svc_cond_command(def)
    if str.length(cmd) > 0
        let rc = run_command_with_timeout(cmd, 5)
        if rc != 0
            if rc == TIMEOUT_RC()
                return ConditionResult{ passed: false, reason: "command timeout" }
            elif rc == NOT_FOUND_RC()
                return ConditionResult{ passed: false, reason: str.concat("command not found: ", cmd) }
            elif rc == EXEC_FAILED_RC()
                return ConditionResult{ passed: false, reason: "command exec failed" }
            else
                return ConditionResult{
                    passed: false,
                    reason: str.concat("command exit=", int_to_str(rc))
                }
            end if
        end if
    end if

    return ConditionResult{ passed: true, reason: "" }
end evaluate_conditions

fn TIMEOUT_RC(): int     return 0 - 2 end TIMEOUT_RC
fn NOT_FOUND_RC(): int   return 0 - 3 end NOT_FOUND_RC
fn EXEC_FAILED_RC(): int return 0 - 4 end EXEC_FAILED_RC

// Runs command via a new C helper that handles fork/exec/timeout/wait.
// Returns: 0 on success, command's exit code, TIMEOUT_RC if exceeded,
// NOT_FOUND_RC if no such binary, EXEC_FAILED_RC on other exec error.
extern "C" fn run_command_with_timeout(cmd: string, timeout_sec: int): int
```

- [ ] **Step 5: Add the C helper `run_command_with_timeout`**

In `src/helpers.c`, append:

```c
#include <sys/wait.h>
#include <signal.h>
#include <errno.h>
/* Run a command with a timeout in seconds. Returns:
 *   command's exit code on normal completion (0 = success),
 *   -2 if timeout exceeded (child killed),
 *   -3 if command binary not found,
 *   -4 on other exec failure.
 * The cmd string is run via /bin/sh -c so $PATH lookup works. */
int run_command_with_timeout(char *cmd, int timeout_sec) {
    pid_t pid = fork();
    if (pid < 0) return -4;
    if (pid == 0) {
        /* child */
        execl("/bin/sh", "sh", "-c", cmd, (char *)0);
        _exit(127);   /* exec failed */
    }
    /* parent */
    time_t deadline = time(0) + timeout_sec;
    int status;
    for (;;) {
        pid_t r = waitpid(pid, &status, WNOHANG);
        if (r == pid) {
            if (WIFEXITED(status)) {
                int ec = WEXITSTATUS(status);
                if (ec == 127) return -3;
                return ec;
            }
            return -4;   /* signaled */
        }
        if (r < 0) return -4;
        if (time(0) >= deadline) {
            kill(pid, SIGKILL);
            waitpid(pid, &status, 0);
            return -2;
        }
        struct timespec ts = { 0, 50 * 1000 * 1000 };   /* 50ms */
        nanosleep(&ts, 0);
    }
}
```

- [ ] **Step 6: Build + unit-test via --ui-demo or direct config-parse test**

Build:

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Since `evaluate_conditions` is a pure function, the easiest test is to wire a quick demo scenario in `ui_demo` (or add a small assertion in the integration harness). For now, just confirm the build succeeds. Real coverage comes in Task 8.

- [ ] **Step 7: Commit**

```sh
hg add src/condition.reef
hg commit -m "condition: [condition] block schema + evaluate_conditions (exists_file, exists_file_any, command with timeout)"
```

---

## Task 7: STATE_SKIPPED + `ui_event_skipped` + wire into start_service

**Files:**
- Modify: `src/supervisor.reef`
- Modify: `src/ui.reef`

- [ ] **Step 1: Add STATE_SKIPPED constant + skip_reason field**

In `src/supervisor.reef`:

```reef
fn STATE_SKIPPED(): int return 7 end STATE_SKIPPED   // pick an unused state value
```

Add it to the state-name mapping function (the one that returns strings for states).

Extend `ServiceRuntime` struct with:

```reef
skip_reason: string
```

Initialize to `""` in the existing constructor / table init logic.

- [ ] **Step 2: Add `ui_event_skipped` to ui.reef**

In `src/ui.reef`, alongside other lifecycle procs:

```reef
mut g_skipped: int = 0   // declared next to g_done/g_failed_count

proc ui_event_skipped(name: string, reason: string)
    let elapsed = zyginit_monotonic_ms() - g_boot_start_ms
    g_skipped = g_skipped + 1
    let note = str.concat("skipped: ", reason)
    tape_push(elapsed, paint("mute", glyph_pending()), name, note, 0)
    if g_mode == MODE_PLAIN()
        let kv = str.concat("reason=", reason)
        println(fmt_plain_event(elapsed, "info", "skipped", name, kv))
    else
        emit_redraw(elapsed)
    end if
end ui_event_skipped
```

Export `ui_event_skipped` and `g_skipped` access if needed.

Also reset `g_skipped = 0` in `ui_boot_start` and `ui_shutdown_start` alongside the other resets.

- [ ] **Step 3: Wire condition evaluation into start_service**

In `src/supervisor.reef`, find the top of `start_service`. After the initial state read but BEFORE the fork, insert:

```reef
let cond_result = condition.evaluate_conditions(def)
if condition.cond_passed(cond_result) == false
    rt.state = STATE_SKIPPED()
    rt.skip_reason = condition.cond_reason(cond_result)
    table.runtimes[idx] = rt
    ui.ui_event_skipped(name, rt.skip_reason)
    return true   // not an error from the caller's perspective
end if
```

Add `import condition` at the top of `src/supervisor.reef`.

- [ ] **Step 4: Build**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

- [ ] **Step 5: Add integration tests for SKIPPED**

In `tests/integration/run_tests.sh`:

```sh
echo "=== [condition] block — SKIPPED state ==="

create_service skip-missing-file "$(cat <<'EOF'
[service]
type = "daemon"

[exec]
start = "/bin/sleep 1000"

[condition]
exists_file = "/this/path/definitely/does/not/exist"
EOF
)"
enable_service skip-missing-file

create_service skip-cmd-fail "$(cat <<'EOF'
[service]
type = "daemon"

[exec]
start = "/bin/sleep 1000"

[condition]
command = "/bin/false"
EOF
)"
enable_service skip-cmd-fail

start_daemon
sleep 2

out=$($ZYGCTL status)
echo "$out" | grep -q "skip-missing-file.*skipped" && \
    pass "missing file → skipped" || \
    fail "missing file → skipped" "got: $(echo "$out" | grep skip-missing-file)"

echo "$out" | grep -q "skip-cmd-fail.*skipped" && \
    pass "command exit non-zero → skipped" || \
    fail "command exit non-zero → skipped" "got: $(echo "$out" | grep skip-cmd-fail)"

# Reason text appears in NOTES
echo "$out" | grep -q "skip-missing-file.*missing" && \
    pass "reason text in status" || \
    fail "reason text in status" "got: $(echo "$out" | grep skip-missing-file)"

stop_daemon
```

- [ ] **Step 6: Run + verify**

```sh
./tests/integration/run_tests.sh
```

Some may still fail (because the UI render for SKIPPED isn't in ui_render.reef yet — that's Task 8). The supervisor-level tests should pass.

- [ ] **Step 7: Commit**

```sh
hg commit -m "supervisor+ui: STATE_SKIPPED + skip_reason + ui_event_skipped — conditions evaluated before fork"
```

---

## Task 8: UI integration — banner, progress bar, final card, zygctl status

**Files:**
- Modify: `src/ui.reef`
- Modify: `src/ui_render.reef`

- [ ] **Step 1: Update banner to show skipped count**

In `src/ui.reef`, find `fmt_header`. The summary line currently reads:

```
23 services · tier 5 · 12 done · 1 failed
```

Modify to include skipped:

```reef
out = str.concat(out, paint("frame",
    str.concat(str.concat(int_to_str(g_num_svc), " services · tier "),
    str.concat(str.concat(int_to_str(g_cur_tier), " · "),
    str.concat(str.concat(int_to_str(g_done), " done · "),
    str.concat(str.concat(int_to_str(g_failed_count), " failed · "),
    str.concat(int_to_str(g_skipped), " skipped")))))))
```

- [ ] **Step 2: Update progress bar denominator**

In `src/ui.reef`, find `render_boot_screen`. The progress bar call is:

```reef
out = str.concat(out, fmt_progress_bar(g_done, g_num_svc))
```

`g_done` already counts STARTED + FAILED. Add `g_skipped`:

```reef
out = str.concat(out, fmt_progress_bar(g_done + g_skipped, g_num_svc))
```

- [ ] **Step 3: Update final card summary line**

In `src/ui.reef`, find `ui_boot_complete`. The summary line currently:

```reef
"17 services — 16 online, 1 failed"
```

Modify the BootStats struct (in ui.reef) to include `skipped: int`. Update the line to:

```reef
out = str.concat(out, "  ")
out = str.concat(out, paint("frame",
    str.concat(str.concat(summary_count, " services — "),
    str.concat(str.concat(int_to_str(stats.online), " online, "),
    str.concat(str.concat(int_to_str(stats.failed), " failed, "),
    str.concat(int_to_str(stats.skipped), " skipped"))))))
```

- [ ] **Step 4: Update build_boot_stats in main.reef**

In `src/main.reef`, find `build_boot_stats`. Add a SKIPPED counter:

```reef
fn build_boot_stats(table: supervisor.ServiceTable, boot_elapsed_ms: int): ui.BootStats
    let count = supervisor.service_count(table)
    mut online = 0
    mut failed = 0
    mut skipped = 0
    mut i = 0
    while i < count
        let rt = supervisor.get_runtime(table, i)
        let st = supervisor.rt_state(rt)
        if st == supervisor.STATE_RUNNING()  online = online + 1  end if
        if st == supervisor.STATE_STOPPED()
            if supervisor.rt_last_exit_code(rt) == 0  online = online + 1  end if
        end if
        if st == supervisor.STATE_FAILED() or st == supervisor.STATE_MAINTENANCE()
            failed = failed + 1
        end if
        if st == supervisor.STATE_SKIPPED()  skipped = skipped + 1  end if
        i = i + 1
    end while
    let slow = new [string](3)
    return ui.BootStats{
        elapsed_ms: boot_elapsed_ms,
        online: online,
        failed: failed,
        skipped: skipped,
        slowest: slow,
        slowest_count: 0
    }
end build_boot_stats
```

- [ ] **Step 5: Update ui_render.reef state mapping**

In `src/ui_render.reef`, find `state_color`, `state_glyph`, `state_label`. Add SKIPPED:

```reef
// In state_color:
if state == supervisor.STATE_SKIPPED() return "mute" end if

// In state_glyph:
if state == supervisor.STATE_SKIPPED() return glyph_pending() end if

// In state_label:
if state == supervisor.STATE_SKIPPED() return " skipped" end if
```

In `fmt_status_row`, ensure the NOTES column picks up `rt.skip_reason` when state is SKIPPED. Add right above the `last_exit > 0` block:

```reef
if state == supervisor.STATE_SKIPPED()
    let reason = supervisor.rt_skip_reason(rt)
    if str.length(reason) > 0
        notes = reason
    end if
end if
```

(`supervisor.rt_skip_reason` is a new accessor — add it next to the other `rt_*` accessors and export it.)

Update the banner in `ui_render_status` to show `skipped` count alongside online/failed. Same shape as boot banner.

- [ ] **Step 6: Build + run all tests**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && reefc build --obj build/symlink_wrapper.o)
./tests/integration/run_tests.sh
./tests/integration/ui_tests.sh
./tests/integration/migrate_layout_tests.sh
```

All should pass. Existing snapshot tests may regenerate because the banner now has an extra ` · 0 skipped` segment. Regenerate them deliberately:

```sh
rm tests/integration/snapshots/{boot_tape_*,shutdown_*,final_card_*}.txt
./tests/integration/ui_tests.sh
hg diff tests/integration/snapshots/ | head -40   # confirm only banner diffs
```

If diffs look right (only the new ` · N skipped` text and the progress bar denominator), commit them.

- [ ] **Step 7: Commit**

```sh
hg commit -m "ui+ui_render: g_skipped counter, banner, progress denominator, final card, status table"
```

---

## Task 9: New UI snapshot scenarios

**Files:**
- Modify: `src/ui.reef` (demo scenarios)
- Modify: `tests/integration/ui_tests.sh`

- [ ] **Step 1: Add the 5 new check_scenario lines**

In `tests/integration/ui_tests.sh`:

```sh
check_scenario task_ok                "ZYGINIT_FORCE_80x25=1 TERM=xterm-256color"
check_scenario task_failed            "ZYGINIT_FORCE_80x25=1 TERM=xterm-256color"
check_scenario boot_with_skipped      "ZYGINIT_FORCE_80x25=1 TERM=xterm-256color"
check_scenario final_card_with_skipped "ZYGINIT_FORCE_80x25=1 TERM=xterm-256color"
check_scenario status_skipped         "ZYGINIT_FORCE_80x25=1 TERM=xterm-256color"
```

- [ ] **Step 2: Run tests — confirm 5 FAILs**

```sh
./tests/integration/ui_tests.sh
```

Expected: 5 unknown scenarios.

- [ ] **Step 3: Implement the demo scenarios in ui.reef's ui_demo**

```reef
    if scenario == "task_ok"
        g_mode = detect_rich_mode()
        ui_boot_start(5, 2, "multi-user")
        g_boot_start_ms = 0
        tape_push(40,  paint("ok", glyph_ok()), "root-fs",  "", 0)
        tape_push(160, paint("ok", glyph_ok()), "task-svc", "", 0)
        g_done = 2
        let stats = BootStats{
            elapsed_ms: 200, online: 5, failed: 0, skipped: 0,
            slowest: new [string](3), slowest_count: 0
        }
        ui_boot_complete(stats)
        return 0
    end if

    if scenario == "task_failed"
        g_mode = detect_rich_mode()
        ui_boot_start(5, 2, "multi-user")
        g_boot_start_ms = 0
        tape_push(40,  paint("ok",   glyph_ok()),   "root-fs",  "", 0)
        tape_push(160, paint("fail", glyph_fail()), "task-svc", "exit=1", 0)
        g_done = 2
        g_failed_count = 1
        g_failed_first = "task-svc"
        g_failed_first_exit = 1
        let stats = BootStats{
            elapsed_ms: 200, online: 4, failed: 1, skipped: 0,
            slowest: new [string](3), slowest_count: 0
        }
        ui_boot_complete(stats)
        return 0
    end if

    if scenario == "boot_with_skipped"
        g_mode = detect_rich_mode()
        ui_boot_start(5, 2, "multi-user")
        g_boot_start_ms = 0
        tape_push(40,  paint("ok",   glyph_ok()),      "root-fs", "", 0)
        tape_push(160, paint("mute", glyph_pending()), "acpihpd", "skipped: missing /dev/acpihp", 0)
        tape_push(310, paint("ok",   glyph_ok()),      "cron",    "", 0)
        g_done = 2
        g_skipped = 1
        // Render the screen mid-boot (not the final card)
        print(str.concat(str.concat(zyginit_esc_str(), "[2J"),
              str.concat(zyginit_esc_str(), "[H")))
        print(render_boot_screen(400))
        return 0
    end if

    if scenario == "final_card_with_skipped"
        g_mode = detect_rich_mode()
        ui_boot_start(23, 9, "multi-user")
        let stats = BootStats{
            elapsed_ms: 8300, online: 19, failed: 0, skipped: 4,
            slowest: new [string](3), slowest_count: 0
        }
        ui_boot_complete(stats)
        return 0
    end if

    if scenario == "status_skipped"
        // Renders just the zygctl status banner + table with one skipped row.
        // Use the same fixture pattern as the existing status scenarios.
        // (Implementation depends on how existing status demos are structured —
        // mirror that shape and inject one row with state=SKIPPED.)
        g_mode = detect_rich_mode()
        // ... see existing status snapshot demos for the pattern ...
        return 0
    end if
```

For the `status_skipped` scenario specifically: look at how the existing status snapshots (if any) are generated. If there isn't a `--ui-demo` mode for the status table yet, this scenario may need to build a small `ServiceTable` mock — defer this specific scenario to a later iteration if it requires significant scaffolding. Document it as a known gap in the task report.

- [ ] **Step 4: Build, run, inspect snapshots**

```sh
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./tests/integration/ui_tests.sh
```

Inspect each new snapshot:

```sh
cat tests/integration/snapshots/task_ok.txt
cat tests/integration/snapshots/boot_with_skipped.txt
# etc.
```

Verify the visual shape matches the spec mockups in §7.

- [ ] **Step 5: Commit**

```sh
hg add tests/integration/snapshots/task_*.txt tests/integration/snapshots/boot_with_skipped.txt tests/integration/snapshots/final_card_with_skipped.txt tests/integration/snapshots/status_skipped.txt
hg commit -m "ui-tests: 5 new snapshot scenarios — task ok/failed, boot/final with skipped, status skipped"
```

---

## Task 10: Version bump + release

**Files:**
- Modify: `reef.toml`, `src/version.reef`, `tools/zygctl/reef.toml`, `tools/zygctl/src/version.reef`, `tools/sysv-wrapper/version.h` (via bump-version.sh)

- [ ] **Step 1: Bump version 0.1.8 → 0.2.0**

```sh
./scripts/bump-version.sh 0.2.0
hg diff --stat
```

Confirm 5 files changed.

- [ ] **Step 2: Regenerate version-stamped snapshots**

```sh
grep -l "0\.1\.8" tests/integration/snapshots/*.txt | xargs rm 2>/dev/null
```

- [ ] **Step 3: Rebuild + full test pass**

```sh
clang -c src/helpers.c -o build/helpers.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
(cd tools/zygctl && reefc build --obj build/symlink_wrapper.o)
./tests/integration/ui_tests.sh         # regenerates and validates
./tests/integration/run_tests.sh
./tests/integration/migrate_layout_tests.sh
```

All must pass.

- [ ] **Step 4: Commit + tag + release tarball**

```sh
hg commit -m "release: bump to 0.2.0 (per-service layout + task type + [condition] block)"
hg tag v0.2.0
./scripts/make-release.sh
cp releases/zyginit-0.2.0-source.tar.xz releases/zyginit-0.2.0-source.tar.xz.sha256 ~/reef-releases/
cat ~/reef-releases/zyginit-0.2.0-source.tar.xz.sha256
hg log -l 5 --template '{rev}: {desc|firstline}\n'
```

- [ ] **Step 5: Update release notes**

Append to (or create) `docs/RELEASE_NOTES.md`:

```markdown
## 0.2.0 — 2026-05-14

**Breaking change.** Filesystem layout for `/etc/zyginit/` is restructured.
Operators upgrading from 0.1.x MUST run the migration tool before installing
0.2.0 binaries:

```
/path/to/scripts/migrate-layout.sh --dry-run    # preview
/path/to/scripts/migrate-layout.sh --apply      # apply
```

The tool is idempotent and refuses to proceed on ambiguous starting state.

### New: per-service directory layout

Each service is now self-contained:

```
/etc/zyginit/services/<name>/
├── service.toml
├── start.sh
└── stop.sh
```

`enabled.d/<name>` symlinks target `../services/<name>/` (the directory).

### New: `type = "task"` service type

For services that may run for a while but are expected to eventually exit
cleanly (e.g., platform probes, one-time-but-slow setup tasks). Exit 0 =
STOPPED (counts as online), exit ≠ 0 = FAILED, never restarts. Replaces
the previously-unused `type = "transient"`.

### New: `[condition]` block

Declarative pre-flight gating. Supports `exists_file`, `exists_file_any`,
`command` (with 5-second timeout). Services with failing conditions enter
the new SKIPPED state — no failure, no restart loop.

```toml
[condition]
exists_file = "/dev/acpihp"
```

### Hammerhead vendoring

The Hammerhead team runs the migration tool against their override tree
in `base/usr/src/zyginit/overrides/` as part of consuming this drop.
```

- [ ] **Step 6: Commit release notes**

```sh
hg add docs/RELEASE_NOTES.md   # if newly created
hg commit -m "docs: release notes for 0.2.0"
```

---

## Self-review notes

- **Spec coverage:** every spec section has at least one task. §4 layout → Tasks 2+3+4. §5 task type → Task 5. §6 condition block → Tasks 6+7. §7 UI → Task 8. §8 migration tool → Task 1. §9 data flow → covered across Tasks 2/5/7. §10 error handling → covered inline in each task. §11 testing → Tasks 1/3/5/7/8/9. §12 phased delivery → Tasks 1–10 maps roughly to the spec's Phase 1–7.
- **No placeholders:** every step has concrete file paths, code blocks, and shell commands. Task 9 step 3 acknowledges that `status_skipped` may need scaffolding that doesn't yet exist; the implementer should document it as a deferral if needed rather than guessing.
- **Type consistency:** `ConditionResult` defined in Task 6 step 1, used in Task 7. `BootStats.skipped: int` added in Task 8 step 3, used in build_boot_stats step 4. `STATE_SKIPPED()` defined Task 7 step 1, mapped in Task 8 step 5. `rt_skip_reason` accessor introduced Task 8 step 5; field added to ServiceRuntime Task 7 step 1.
- **Tests-first:** every task begins with a failing test (snapshot or integration).
- **Frequent commits:** every task ends with one `hg commit`.
- **YAGNI:** no extra condition kinds, no transitional layout reader, no `[assert]` block, no auto-migrate at boot.
- **DRY:** `evaluate_conditions` factored once; banner skipped counter added once and consumed by `fmt_header`, `ui_render_status`, and `ui_boot_complete`.
# Progress Gauge in Header Divider — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Relocate the boot/shutdown progress indicator from the last row of the screen into the existing top divider of the boot header, fixing the disappear-during-scroll artifact and reclaiming two rows of vertical tape space.

**Architecture:** All changes are local to `src/ui.reef`. A new pure function `fmt_divider_gauge(done, total)` renders the gauge as part of the divider. `fmt_header()` calls it instead of `make_divider()` for its trailing rule. `render_boot_screen()` drops its bottom divider and bottom progress bar (those rows are reclaimed by the tape). `ui_boot_complete()` and `ui_shutdown_complete()` already exist and continue to paint their final cards unchanged; the gauge only runs during the live boot/shutdown screen.

**Tech Stack:** Reef 0.4.0+, GCC/Clang for `helpers.c`, Mercurial (`hg`) for version control, manual visual validation via the existing `--ui-demo <scenario>` scenario harness in `ui_demo()` at `src/ui.reef:852`.

**Spec:** `docs/superpowers/specs/2026-06-01-progress-in-divider-design.md` (rev 188, amended rev 189, simplified rev 190).

**Build commands (used throughout):**

- **Linux dev** (with stubs — verifies rendering, not contracts):

  ```bash
  clang -c src/helpers.c -o build/helpers.o
  clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
  reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
  ```

  Result: `build/zyginit` executable.

- **Hammerhead** (real binary for hh-prototest deploy):

  ```bash
  gcc -c src/helpers.c -o build/helpers.o
  reefc build -l contract --obj build/helpers.o
  ```

- **Run a scenario:**

  ```bash
  ./build/zyginit --ui-demo <scenario_name>
  ```

**VCS:** Mercurial. `hg add <file>` for new files, `hg commit -m "<msg>"`. Do **not** use `git`.

---

### Task 1: Add gauge scenarios to the demo harness (failing test)

**Files:**

- Modify: `src/ui.reef:950-963` (the existing `progress_*` scenario blocks inside `ui_demo()`)

The existing scenarios at lines 950-963 call `fmt_progress_bar(g_done, g_num_svc)`. Don't touch those yet — Task 5 will rewrite them. Instead, **add new scenarios** to the same `ui_demo` chain so the build will fail until `fmt_divider_gauge` exists.

- [ ] **Step 1: Add three new scenarios just after the existing `progress_full` block at line 963.**

Insert before the `if scenario == "spinner_forward"` block:

```reef
    if scenario == "gauge_live_31" or scenario == "gauge_live_31_ascii"
        if scenario == "gauge_live_31_ascii"
            g_mode = MODE_RICH_ASCII()
        else
            g_mode = detect_rich_mode()
            if g_mode == MODE_PLAIN()  g_mode = MODE_RICH_TRUE()  end if
        end if
        ui_detect_winsize()
        println(fmt_divider_gauge(31, 100))
        return 0
    end if
    if scenario == "gauge_live_100"
        g_mode = detect_rich_mode()
        if g_mode == MODE_PLAIN()  g_mode = MODE_RICH_TRUE()  end if
        ui_detect_winsize()
        println(fmt_divider_gauge(100, 100))
        return 0
    end if
    if scenario == "gauge_live_0"
        g_mode = detect_rich_mode()
        if g_mode == MODE_PLAIN()  g_mode = MODE_RICH_TRUE()  end if
        ui_detect_winsize()
        println(fmt_divider_gauge(0, 100))
        return 0
    end if
```

Three scenarios: 31% (representative live state), 100% (boundary), 0% (boundary). `gauge_live_31_ascii` exercises the `MODE_RICH_ASCII` branch. The `if g_mode == MODE_PLAIN() ... = MODE_RICH_TRUE()` override is needed because demo runs on a non-TTY (when piped to `cat` for inspection) and otherwise short-circuits to plain mode — same pattern used by the existing `progress_*` scenarios indirectly via `detect_rich_mode()`.

- [ ] **Step 2: Run the Linux dev build to verify it fails.**

```bash
cd /home/ctusa/repos/zygaena-project/zyginit
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Expected: compile or link error referencing `fmt_divider_gauge` not defined (Reef reports this at type-check stage). If the build accidentally succeeds, the scenario string was probably mistyped — re-check the inserted block.

- [ ] **Step 3: Commit the failing test.**

```bash
hg commit -m "test(ui): add gauge_live_* scenarios for fmt_divider_gauge (build fails)

Three new scenarios in ui_demo:
- gauge_live_31, gauge_live_31_ascii — representative live state, both
  rich-color and rich-ascii rendering paths
- gauge_live_100 — full-bar boundary
- gauge_live_0  — empty-bar boundary

Build fails because fmt_divider_gauge does not exist yet."
```

---

### Task 2: Implement `fmt_divider_gauge` (make scenarios pass)

**Files:**

- Modify: `src/ui.reef` — add export declaration and function body. The function replaces both `make_divider()` (semantically) and `fmt_progress_bar()` (visually).

- [ ] **Step 1: Add the export declaration.**

Edit `src/ui.reef` line 54 area (the `export` block). Insert a new line just after `fn fmt_progress_bar(done: int, total: int): string`:

```reef
    fn fmt_divider_gauge(done: int, total: int): string
```

So lines 54-55 read:

```reef
    fn fmt_progress_bar(done: int, total: int): string
    fn fmt_divider_gauge(done: int, total: int): string
```

(We'll delete `fmt_progress_bar` in Task 5; for now both coexist.)

- [ ] **Step 2: Implement the function. Insert it immediately before `fmt_progress_bar` at line 393.**

```reef
// Render the boot/shutdown header's bottom rule as a divider with an
// embedded progress gauge. Replaces both make_divider() (in fmt_header)
// and fmt_progress_bar() (in render_boot_screen). Total visual width =
// g_line_width - 16 (matches make_divider). Brackets + 26-cell inner
// content + equal lpad/rpad of dashes. Narrow-terminal fallback drops
// the brackets and shows just "── NN% ──".
fn fmt_divider_gauge(done: int, total: int): string
    if g_mode == MODE_PLAIN()  return ""  end if

    let total_width = g_line_width - 16
    let bar_width = 20
    let inner_width = 26              // bar(20) + "  "(2) + "NNN%"(4)
    let bracket_width = inner_width + 2   // 28: '[' + inner + ']'

    mut filled = 0
    if total > 0
        filled = (done * bar_width) / total
    end if
    if filled > bar_width  filled = bar_width  end if
    if filled < 0  filled = 0  end if

    mut pct = 0
    if total > 0
        pct = (done * 100) / total
    end if
    if pct > 100  pct = 100  end if
    if pct < 0  pct = 0  end if

    // pct_field: right-aligned 3 cells + '%' = 4 cells. E.g. "  3%", " 31%", "100%".
    let pct_str = int_to_str(pct)
    let pct_len = str.length(pct_str)
    mut pct_field = ""
    mut pp = 0
    while pp < (3 - pct_len)
        pct_field = str.concat(pct_field, " ")
        pp = pp + 1
    end while
    pct_field = str.concat(pct_field, pct_str)
    pct_field = str.concat(pct_field, "%")

    // Narrow-terminal fallback: not enough room for brackets + padding.
    if total_width < bracket_width + 2
        // Emit "── NN% ──" centered in total_width.
        let label = str.concat(" ", str.concat(pct_field, " "))
        let label_len = 1 + 4 + 1   // " " + "NNN%" + " "
        mut pad = 0
        if total_width > label_len
            pad = total_width - label_len
        end if
        let lpad_n = pad / 2
        let rpad_n = pad - lpad_n
        mut out = ""
        mut a = 0
        while a < lpad_n
            out = str.concat(out, "─")
            a = a + 1
        end while
        out = str.concat(out, label)
        a = 0
        while a < rpad_n
            out = str.concat(out, "─")
            a = a + 1
        end while
        return paint("accent", out)
    end if

    // Full layout: lpad + '[' + bar + "  " + pct_field + ']' + rpad
    let pad_total = total_width - bracket_width
    let lpad_n = pad_total / 2
    let rpad_n = pad_total - lpad_n

    // Build the bar. Painting per-cell to support per-mode chars.
    mut bar = ""
    mut i = 0
    while i < bar_width
        if g_mode == MODE_RICH_ASCII()
            if i < filled
                bar = str.concat(bar, "#")
            else
                bar = str.concat(bar, " ")
            end if
        else
            if i < filled
                bar = str.concat(bar, paint("accent", "█"))
            else
                bar = str.concat(bar, paint("mute", "░"))
            end if
        end if
        i = i + 1
    end while

    // Assemble. Brackets, pct, and pad chars all painted "accent".
    mut out = ""
    mut j = 0
    while j < lpad_n
        out = str.concat(out, "─")
        j = j + 1
    end while
    out = paint("accent", out)
    out = str.concat(out, paint("accent", "["))
    out = str.concat(out, bar)
    out = str.concat(out, "  ")
    out = str.concat(out, paint("accent", pct_field))
    out = str.concat(out, paint("accent", "]"))
    mut rpad = ""
    j = 0
    while j < rpad_n
        rpad = str.concat(rpad, "─")
        j = j + 1
    end while
    out = str.concat(out, paint("accent", rpad))
    return out
end fmt_divider_gauge
```

Notes for the implementer:

- `paint()` returns the input text unchanged when the mode doesn't support color (e.g., `MODE_RICH_ASCII`); the ANSI escapes are only added in `MODE_RICH_16` / `MODE_RICH_TRUE`. So calling `paint("accent", "─")` is safe across modes.
- The "─" character (U+2500) is used in **all** rich modes including `MODE_RICH_ASCII`, matching the pre-existing `make_divider()` behavior. (`make_divider` does not differentiate modes.) Only the bar fill character differentiates rich-ascii (`#`/space) from rich-color (`█`/`░`).
- `str.length()` returns the byte length of the string. For ASCII content (`pct_field`), byte length equals visual cell count — safe.
- The narrow-terminal fallback is exercised only when `total_width < 30` (i.e., `g_line_width < 46`). At the project's minimum `g_line_width = 40` (clamped in `ui_detect_winsize` at line 691-693), `total_width = 24`, which **does** hit the fallback. Verify visually.

- [ ] **Step 3: Rebuild.**

```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```

Expected: clean build.

- [ ] **Step 4: Run the three new scenarios and visually inspect.**

```bash
./build/zyginit --ui-demo gauge_live_31
./build/zyginit --ui-demo gauge_live_31_ascii
./build/zyginit --ui-demo gauge_live_100
./build/zyginit --ui-demo gauge_live_0
```

Expected output shapes (terminal width 80, so `g_line_width = 78`, `total_width = 62`):

- **gauge_live_31** — colored 8-cell fill out of 20, ` 31%` label:
  ```
  ─────────────────[████████░░░░░░░░░░░░  31%]─────────────────
  ```
- **gauge_live_31_ascii** — ASCII `#`/space, same layout, no ANSI escapes:
  ```
  -----------------[########            31%]-----------------
  ```
  (Hyphens shown here for clarity — the actual output uses `─`. Run with `| cat -v` to see escape sequences are absent.)
- **gauge_live_100** — full bar, `100%`:
  ```
  ─────────────────[████████████████████  100%]─────────────────
  ```
- **gauge_live_0** — empty bar, `  0%`:
  ```
  ─────────────────[░░░░░░░░░░░░░░░░░░░░    0%]─────────────────
  ```

If output looks off, inspect by piping through `cat -v` to see escape sequences explicitly. Common issues to check: bar width (must be exactly 20 cells of fill+empty), pct field width (must be exactly 4 cells: 3-digit number + `%`), brackets present, total visual width consistent across scenarios.

- [ ] **Step 5: Commit.**

```bash
hg commit -m "feat(ui): implement fmt_divider_gauge

Renders the boot/shutdown header rule as a divider with embedded
progress gauge: [bar  NN%] flanked by '─' padding. Falls back to a
narrow-terminal layout (no brackets, just '── NN% ──') when
g_line_width < 46. ASCII mode uses #/space for fill; rich mode uses
█/░ painted accent/mute."
```

---

### Task 3: Wire `fmt_divider_gauge` into `fmt_header`

**Files:**

- Modify: `src/ui.reef:357-389` (`fmt_header` function)

The header today ends with a cosmetic divider from `make_divider()`. Replace that call with `fmt_divider_gauge(g_done + g_skipped, g_num_svc)`. Also add the elapsed-suppress conditional.

- [ ] **Step 1: Update `fmt_header` to suppress the `elapsed Xs` field once boot has visually completed.**

Find lines 365-366 in `src/ui.reef`:

```reef
    out = str.concat(out, "   ")
    out = str.concat(out, paint("accent", str.concat("elapsed ", elapsed)))
```

Wrap them in a phase-aware conditional. Replace with:

```reef
    let boot_visually_done = (g_phase == "boot") and
                             ((g_done + g_skipped + g_failed_count) >= g_num_svc) and
                             (g_num_svc > 0)
    if not boot_visually_done
        out = str.concat(out, "   ")
        out = str.concat(out, paint("accent", str.concat("elapsed ", elapsed)))
    end if
```

Reef uses `not`, `and`, `or` for boolean operators (verified at `src/ui.reef:527` `if not has_active_tape_row()` and line 869 `or scenario ==`). The `==` / `>=` operators are numeric comparison as used at line 375.

- [ ] **Step 2: Replace the trailing `make_divider()` call with the new gauge.**

Find lines 386-387:

```reef
    out = str.concat(out, "\n  ")
    out = str.concat(out, paint("accent", make_divider()))
```

Replace with:

```reef
    out = str.concat(out, "\n  ")
    out = str.concat(out, fmt_divider_gauge(g_done + g_skipped, g_num_svc))
```

Note: `fmt_divider_gauge` returns already-painted text — do **not** wrap in `paint("accent", ...)`.

- [ ] **Step 3: Rebuild and exercise the existing full-header scenarios.**

```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./build/zyginit --ui-demo boot_tape_rich
```

Expected: the four-line header now ends with the gauge divider (e.g. `─────[███...░░░  47%]──────`) instead of a plain `─────────` line. The bottom of the screen still shows the old divider+progress_bar pair — those go in Task 4. The `elapsed Xs` field on header line 1 should still be present (the scenario doesn't reach 100%).

- [ ] **Step 4: Verify the elapsed-suppress branch.**

Run `boot_tape_ascii` (ends at 9/9 in some scenarios) or check `final_card_ok` — though the latter exits through `ui_boot_complete()` which doesn't call `fmt_header`. Easiest verification: temporarily add a one-off scenario that calls `ui_boot_start(5, 1, "multi-user")`, sets `g_done = 5`, then `print(fmt_header(5000))`. Confirm header line 1 omits `elapsed Xs`. Roll that scenario back before commit (it's a debug aid, not part of the deliverable).

- [ ] **Step 5: Commit.**

```bash
hg commit -m "feat(ui): wire fmt_divider_gauge into header trailing rule

fmt_header() now renders its trailing rule via fmt_divider_gauge
instead of make_divider, so the boot screen header carries the live
progress gauge. Also suppress the 'elapsed Xs' field on header line 1
once boot is visually complete (g_done + g_skipped + g_failed_count
>= g_num_svc), avoiding stale-timer visual noise during the brief
window before ui_boot_complete fires the final card."
```

---

### Task 4: Strip bottom divider and bottom progress bar from `render_boot_screen`

**Files:**

- Modify: `src/ui.reef:499-521` (`render_boot_screen` function)
- Modify: `src/ui.reef:682` (`g_tape_height` calculation)

- [ ] **Step 1: Remove the bottom divider concat and the bottom progress_bar concat.**

Find lines 513-520:

```reef
        i = i + 1
    end while
    out = str.concat(out, str.concat("  ", paint("accent", make_divider())))
    out = str.concat(out, "\n")
    out = str.concat(out, fmt_progress_bar(g_done + g_skipped, g_num_svc))
    // No trailing newline: total height is exactly g_screen_rows. A trailing
    // \n would advance the cursor past the bottom edge and scroll the [Z]
    // banner off the top of the screen.
    return out
```

Replace with:

```reef
        i = i + 1
    end while
    // No trailing newline: total height is exactly g_screen_rows. A trailing
    // \n would advance the cursor past the bottom edge and scroll the [Z]
    // banner off the top of the screen. The progress gauge lives in the
    // header rule (see fmt_divider_gauge), not on the last row.
    return out
```

Result: the tape loop is the last content; no trailing divider or progress bar.

- [ ] **Step 2: Reduce `g_tape_height` reserve from 6 to 4.**

Find line 681-682:

```reef
    // Tape height = screen rows - (header 4 + progress 2) with breathing room
    g_tape_height = g_screen_rows - 6
```

Replace with:

```reef
    // Tape height = screen rows - (header 4 rows including gauge divider).
    // Gauge lives inside the header, not on a separate trailing row.
    g_tape_height = g_screen_rows - 4
```

Leave the clamps (`< 4`, `> 32`) on lines 683-688 unchanged.

- [ ] **Step 3: Rebuild and verify full layout.**

```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
./build/zyginit --ui-demo boot_tape_rich
```

Expected: 4-row header ending with the gauge divider, followed immediately by the tape rows (no trailing divider, no trailing progress bar). The tape should have 2 more rows than before (because `g_tape_height` is +2).

- [ ] **Step 4: Compare row count visually.**

Count rows of the output. On a 25-row default terminal: 4 header rows + 21 tape rows = 25 total. Before the change: 4 header + 19 tape + 1 bottom divider + 1 progress = 25. Either way the total is 25; the change is two more tape slots.

- [ ] **Step 5: Commit.**

```bash
hg commit -m "feat(ui): strip bottom divider + progress bar from render_boot_screen

Both are obsolete now that fmt_header's trailing rule carries the gauge.
Tape height adjusted from g_screen_rows-6 to g_screen_rows-4 to claim
the reclaimed rows.

Fixes the disappearing-progress-bar artifact: the gauge no longer
lives on the volatile last row of the screen."
```

---

### Task 5: Convert legacy `progress_*` scenarios; delete dead code

**Files:**

- Modify: `src/ui.reef:950-963` (legacy scenarios)
- Modify: `src/ui.reef:54` (export of `fmt_progress_bar`)
- Modify: `src/ui.reef:391-439` (definitions of `PROGRESS_WIDTH` and `fmt_progress_bar`)

- [ ] **Step 1: Rewrite the three legacy scenarios to use the gauge.**

Find lines 950-963:

```reef
    if scenario == "progress_rich" or scenario == "progress_ascii"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        g_done = 12
        g_failed_count = 1
        print(fmt_progress_bar(g_done, g_num_svc))
        return 0
    end if
    if scenario == "progress_full"
        g_mode = detect_rich_mode()
        ui_boot_start(17, 8, "multi-user")
        g_done = 17
        print(fmt_progress_bar(g_done, g_num_svc))
        return 0
    end if
```

Replace with:

```reef
    if scenario == "progress_rich" or scenario == "progress_ascii"
        if scenario == "progress_ascii"
            g_mode = MODE_RICH_ASCII()
        else
            g_mode = detect_rich_mode()
            if g_mode == MODE_PLAIN()  g_mode = MODE_RICH_TRUE()  end if
        end if
        ui_detect_winsize()
        ui_boot_start(17, 8, "multi-user")
        g_done = 12
        g_failed_count = 1
        println(fmt_divider_gauge(g_done + g_skipped, g_num_svc))
        return 0
    end if
    if scenario == "progress_full"
        g_mode = detect_rich_mode()
        if g_mode == MODE_PLAIN()  g_mode = MODE_RICH_TRUE()  end if
        ui_detect_winsize()
        ui_boot_start(17, 8, "multi-user")
        g_done = 17
        println(fmt_divider_gauge(g_done + g_skipped, g_num_svc))
        return 0
    end if
```

Same scenario names, same semantic intent (visualize boot progress at 12/17 with one failure, then at 17/17 full), but now using the new gauge. Switched `print` → `println` to match the new gauge scenarios (terminal-friendly).

- [ ] **Step 2: Delete `PROGRESS_WIDTH()` and `fmt_progress_bar()`.**

Find lines 391-439 and delete the entire block:

```reef
fn PROGRESS_WIDTH(): int return 36 end PROGRESS_WIDTH

fn fmt_progress_bar(done: int, total: int): string
    if g_mode == MODE_PLAIN()  return ""  end if
    let width = PROGRESS_WIDTH()
    mut filled = 0
    if total > 0
        filled = (done * width) / total
    end if
    if filled > width  filled = width  end if
    mut pct = 0
    if total > 0
        pct = (done * 100) / total
    end if
    mut bar = ""
    if g_mode == MODE_RICH_ASCII()
        let inner = width - 2
        let inner_filled = (filled * inner) / width
        bar = str.concat(bar, "[")
        mut i = 0
        while i < inner
            if i < inner_filled
                bar = str.concat(bar, "#")
            else
                bar = str.concat(bar, " ")
            end if
            i = i + 1
        end while
        bar = str.concat(bar, "]")
    else
        mut i = 0
        while i < width
            if i < filled
                bar = str.concat(bar, paint("accent", "█"))
            else
                bar = str.concat(bar, paint("mute", "░"))
            end if
            i = i + 1
        end while
    end if
    mut label = ""
    if g_phase == "shutdown"  label = " down"  end if
    return str.concat(
        str.concat("  ", bar),
        str.concat(
            str.concat(str.concat("  ", int_to_str(done)),
                       str.concat("/", int_to_str(total))),
            str.concat(label, str.concat("  ", str.concat(int_to_str(pct), "%")))))
end fmt_progress_bar
```

The block ends at the `end fmt_progress_bar` line (line 439). Delete everything from `fn PROGRESS_WIDTH(): int` through `end fmt_progress_bar` inclusive.

- [ ] **Step 3: Remove the export declaration for `fmt_progress_bar`.**

Find line 54:

```reef
    fn fmt_progress_bar(done: int, total: int): string
```

Delete this entire line. The line below (`fn fmt_divider_gauge(...)`) remains.

- [ ] **Step 4: Grep to confirm no remaining callers.**

```bash
grep -rn "fmt_progress_bar\|PROGRESS_WIDTH" src/
```

Expected: **no output**. If any reference remains, that's a real bug — track it down before continuing.

- [ ] **Step 5: Rebuild and run all gauge-related scenarios.**

```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o

./build/zyginit --ui-demo gauge_live_0
./build/zyginit --ui-demo gauge_live_31
./build/zyginit --ui-demo gauge_live_31_ascii
./build/zyginit --ui-demo gauge_live_100
./build/zyginit --ui-demo progress_rich
./build/zyginit --ui-demo progress_ascii
./build/zyginit --ui-demo progress_full
./build/zyginit --ui-demo boot_tape_rich
./build/zyginit --ui-demo boot_tape_ascii
```

Expected: clean build, all scenarios render correctly. `boot_tape_*` shows the full new layout (header + gauge divider + 8 tape rows, no trailing divider/progress).

- [ ] **Step 6: Commit.**

```bash
hg commit -m "refactor(ui): drop fmt_progress_bar and PROGRESS_WIDTH

Both obsolete after the gauge moved into fmt_divider_gauge. Legacy
progress_rich / progress_ascii / progress_full scenarios converted
to exercise fmt_divider_gauge instead. No remaining callers.

grep -rn 'fmt_progress_bar\\|PROGRESS_WIDTH' src/ → empty."
```

---

### Task 6: Full Linux dev validation sweep

**Files:**

- None modified. Pure validation pass.

- [ ] **Step 1: Run every existing UI scenario and confirm nothing regressed.**

```bash
SCENARIOS=(skeleton plain_boot palette_true palette_16 \
           glyphs_unicode glyphs_ascii sigil_rich \
           boot_tape_rich boot_tape_ascii boot_tape_plain \
           progress_rich progress_ascii progress_full \
           spinner_forward spinner_reverse spinner_in_tape \
           final_card_ok final_card_failed \
           gauge_live_0 gauge_live_31 gauge_live_31_ascii gauge_live_100)

for s in "${SCENARIOS[@]}"; do
    echo "--- $s ---"
    ./build/zyginit --ui-demo "$s"
    echo
done
```

For each scenario, eyeball the output. Specific things to verify:

- `boot_tape_rich`: header ends with gauge divider showing 8/17 → `(8*100)/17 = 47%` fill.
- `final_card_ok` / `final_card_failed`: unchanged from before (these go through `ui_boot_complete`, not the live boot screen).
- `boot_tape_plain`: still emits plain text lines (no gauge — `MODE_PLAIN`).

- [ ] **Step 2: Verify narrow-terminal fallback.**

```bash
stty cols 40
./build/zyginit --ui-demo gauge_live_31
stty cols 80   # restore
```

Expected: gauge renders as `── 31% ──`-style narrow form, no brackets, no bar.

If `stty cols 40` doesn't propagate to the child process (depends on shell + TTY semantics), an alternative: temporarily edit `ui_detect_winsize()` to force `g_line_width = 24`, run the scenario, then revert.

- [ ] **Step 3: No commit needed** — validation pass, no files changed.

---

### Task 7: Hammerhead build, deploy, and live verification

**Files:**

- None modified. Deploy and verify on the test VM.

- [ ] **Step 1: Build for Hammerhead from the dev host.**

The dev host doesn't have GCC for Hammerhead targets — push source to the VM and build there. Two options: build remotely (preferred — fewer moving parts) or build locally with a cross-compiler. Use remote:

```bash
# From dev host:
scp src/ui.reef root@192.168.122.50:/root/zyginit/src/
```

(Only `ui.reef` changed.)

- [ ] **Step 2: Build on hh-prototest and replace `/sbin/init`.**

```bash
ssh root@192.168.122.50 'cd /root/zyginit && \
    gcc -c src/helpers.c -o build/helpers.o && \
    reefc build -l contract --obj build/helpers.o && \
    cp build/zyginit /sbin/init.new && \
    mv /sbin/init.new /sbin/init'
```

Expected: clean build (no warnings about unused `fmt_progress_bar`), file replaced atomically via rename.

- [ ] **Step 3: Force a cold reboot via virsh.**

`init 6` from non-PID-1 zyginit doesn't reboot — it spawns a supervisor-mode child. Use virsh:

```bash
virsh --connect=qemu:///system reset hh-prototest
```

- [ ] **Step 4: Observe the boot console via virt-viewer / virsh console.**

Open the VM console (`virsh --connect=qemu:///system console hh-prototest`, or VNC via virt-manager). Expected during boot:

- 4-row header (sigil line, counts line, failed line, gauge divider)
- Gauge fills as services start across tiers
- Tape rows occupy everything below the divider
- **No** disappearing-bar artifact — kernel printks (if any) scroll lower content but the gauge stays put in row 4

Once boot completes, the final card appears (existing behavior, unchanged).

- [ ] **Step 5: Test shutdown.**

```bash
ssh root@192.168.122.50 'zygctl halt'
```

Expected: shutdown screen renders with gauge filling 0→100% as services stop. Once all services are stopped, the shutdown final card replaces the screen ("reboot complete · invoking uadmin..."). System reboots cleanly.

After the reboot, SSH back in and verify `who -b` and `uptime` report correct times (sanity check that shutdown didn't corrupt anything).

- [ ] **Step 6: Force-scroll test — confirm the bug is fixed.**

The original bug surfaces during boot when something else writes to `/dev/console` between zyginit redraws. Easiest reproducer is the cold-boot path itself (Step 4): kernel printks and driver messages naturally interleave with zyginit's tape updates. Watch the VM console during boot.

Expected: the gauge in the divider stays visible across console churn. It may flicker on redraw (as zyginit clears and repaints), but it does **not** disappear off the bottom of the screen as the pre-fix bar did. If you want a deliberate stress test, induce a one-shot kernel message in a non-PID-1 supervisor instance:

```bash
ssh root@192.168.122.50 '
    ZYGINIT_CONFIG_DIR=/etc/zyginit /sbin/init &
    sleep 1
    echo "test message" > /dev/console
    sleep 1
    kill %1
'
```

The gauge should remain on row 4 across the `echo > /dev/console` write.

- [ ] **Step 7: Commit the source changes if not already committed and tag.**

All file changes were committed in earlier tasks. Final action is a single sanity commit if any final tweaks were needed, then tag:

```bash
hg log -l 8 --template '{rev}: {desc|firstline}\n'   # confirm clean history
```

No tag yet — that's a release decision; leave for the user.

---

## Self-Review

**Spec coverage:**

- §1 problem statement → addressed by entire plan, especially Tasks 3–4 (relocating gauge out of last row).
- §2 goals (stability, no-twitch, reclaim space, shutdown symmetry, no plain/ASCII regression) → all covered.
- §4 visual mockups → Tasks 2, 3, 4 deliver §4.2; §4.4 covered by the unchanged `ui_shutdown_complete` plus the gauge running during stop sequence.
- §5 rendering rules (geometry, ASCII vs rich, narrow fallback) → Task 2.
- §6 state changes (none) → respected: no new `g_*` flags introduced.
- §7 files touched (only `src/ui.reef`) → all task edits target `src/ui.reef`.
- §8 backwards compat (plain mode unchanged) → preserved (`MODE_PLAIN()` early-out in `fmt_divider_gauge`); legacy `progress_*` scenarios rewritten to use new gauge but keep the same scenario names so any external test scripts continue to find them.
- §9 testing — manual on hh-prototest → Task 7.

**Placeholder scan:** No "TBD", no "implement later", no "similar to Task N", no skeleton steps. Every code block is complete.

**Type consistency:** `fmt_divider_gauge(done: int, total: int): string` used consistently in export declaration, function body, and three caller sites (Tasks 1, 3, 5). `g_done`, `g_skipped`, `g_failed_count`, `g_num_svc`, `g_phase`, `g_mode` all reference existing state in `src/ui.reef`. `MODE_PLAIN`, `MODE_RICH_ASCII`, `MODE_RICH_TRUE`, `detect_rich_mode`, `ui_detect_winsize`, `ui_boot_start`, `paint`, `str.concat`, `str.length`, `int_to_str` all exist (verified by grep). `paint()` signature is `(token: string, text: string): string`.

**Scope:** Single focused UI change. One file. Seven tasks of escalating commitment (test → impl → wire → strip → cleanup → validate → deploy). Self-contained.
# `conflicts` (Service Mutual Exclusion) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a `conflicts` field to the `[dependencies]` block so two services can be declared mutually exclusive — at boot, both-enabled conflicting services fail; at runtime, starting a service whose conflicting peer is running is refused.

**Architecture:** Two non-overlapping enforcement points funnel through known code. A boot-only pre-flight (`resolve_conflicts` in `main.reef`) marks both members of any active conflicting pair `FAILED` before any fork. A runtime guard inside `supervisor.start_service` (the single choke point for every start) refuses a start when a conflicting peer is `RUNNING`/`STARTING`. A symmetric helper `conflicts_with` backs both. `conflicts` is mutual exclusion, not ordering — it never enters `depgraph.reef`.

**Tech Stack:** Reef (`.reef` → C → native via `reefc`); POSIX shell integration tests; Linux dev build (clang + contract stubs). No Hammerhead VM required.

**Spec:** `docs/superpowers/specs/2026-06-13-conflicts-design.md`

---

## Reef / build orientation (read once)

- Reef structs are **value types**: to mutate a runtime you read it, change fields, write it back — e.g. `let rt = table.runtimes[idx]` … `rt.state = …` … `table.runtimes[idx] = rt`. See `start_service` at `src/supervisor.reef:327` for the canonical pattern.
- Blocks close with `end <kw>` (`end if`, `end fn`, `end while`, `end proc`). `fn` returns a value; `proc` does not. `mut` = mutable, `let` = immutable.
- String building uses `core.str` — `str.concat(a, b)` (already imported as `str` in `supervisor.reef`). `socket.reef` builds strings with the `+` operator (both work; match the file you're editing).
- **Build (Linux dev):**
  ```bash
  clang -c src/helpers.c -o build/helpers.o
  clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
  reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
  ```
  zygctl (needed for the integration suite):
  ```bash
  cd tools/zygctl && clang -c src/symlink_wrapper.c -o build/symlink_wrapper.o && reefc build --obj build/symlink_wrapper.o && cd ../..
  ```
- **Run the integration suite:** `./tests/integration/run_tests.sh`
- **VCS is Mercurial.** Commit with `hg commit -m "..."`. New files need `hg add <path>` first. Every source file must carry the `SRCHEADER.txt` header — but in this plan we only *edit* existing `.reef` files (which already have headers) and add a shell test + docs, so no new `.reef` headers are introduced.

---

## File Map

| File | Change |
|------|--------|
| `src/config.reef` | Add `conflicts`/`conflicts_count` to `ServiceDef`, init, accessors, TOML parse branch |
| `src/supervisor.reef` | `conflicts_with`, `conflicting_running_peer`, `service_name_at`, `mark_conflict_failed`; runtime guard in `start_service` |
| `src/main.reef` | `resolve_conflicts` + `warn_unknown_conflicts` procs; call before boot tier-start; skip non-`WAITING` services in `start_services_by_tier` |
| `src/ui_render.reef` | Show the stored reason for `FAILED` rows in `zygctl status` |
| `src/socket.reef` | `cmd_start` returns the specific conflict message |
| `tests/integration/run_tests.sh` | `create_service_with_conflicts` helper + new "Service conflicts" suite |
| `docs/DESIGN.md`, `docs/man/man5/zyginit.5`, `CLAUDE.md`, `ROADMAP.md` | Document `conflicts`; check roadmap box |

---

## Task 1: Parse `conflicts` and expose accessors (`config.reef`)

Pure data plumbing — no observable behavior yet, so its "test" is: the project still builds and the existing suite stays green. (The repo has no Reef unit-test harness; `conflicts` parsing is verified end-to-end by Task 2's boot test, which cannot pass unless the array parses correctly.)

**Files:**
- Modify: `src/config.reef` (struct ~178, init ~219, accessors ~302, parser ~614)

- [ ] **Step 1: Add struct fields**

In `type ServiceDef = struct` (`src/config.reef`), immediately after:
```
    after: [string]
    after_count: int
```
add:
```
    conflicts: [string]
    conflicts_count: int
```

- [ ] **Step 2: Initialize in `new_service_def()`**

In the `ServiceDef{ ... }` literal, immediately after:
```
        after: new [string](16),
        after_count: 0,
```
add:
```
        conflicts: new [string](16),
        conflicts_count: 0,
```

- [ ] **Step 3: Add accessors**

After the `svc_after_count` accessor, add:
```
fn svc_conflicts(svc: ServiceDef): [string]
    return svc.conflicts
end svc_conflicts

fn svc_conflicts_count(svc: ServiceDef): int
    return svc.conflicts_count
end svc_conflicts_count
```

- [ ] **Step 4: Add TOML parse branch**

In the `[dependencies]` parsing area, immediately after the `dependencies.after` block:
```
    if toml.toml_has_key(keys, vals, count, "dependencies.after")
        let after_str = toml.toml_get(keys, vals, count, "dependencies.after")
        svc.after_count = parse_toml_array(after_str, svc.after, 16)
    end if
```
add:
```
    if toml.toml_has_key(keys, vals, count, "dependencies.conflicts")
        let conf_str = toml.toml_get(keys, vals, count, "dependencies.conflicts")
        svc.conflicts_count = parse_toml_array(conf_str, svc.conflicts, 16)
    end if
```

- [ ] **Step 5: Build**

Run:
```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```
Expected: build succeeds, `build/zyginit` produced.

- [ ] **Step 6: Verify no regression**

Run: `./tests/integration/run_tests.sh`
Expected: same pass count as before this task (all green). If zygctl isn't built yet, build it per the orientation block first.

- [ ] **Step 7: Commit**

```bash
hg commit src/config.reef -m "config: parse [dependencies] conflicts array"
```

---

## Task 2: Boot-time resolution — fail both (`supervisor.reef` + `main.reef` + `ui_render.reef`)

First observable behavior. TDD: add the boot test (red), implement, go green.

**Files:**
- Modify: `tests/integration/run_tests.sh` (helper + new suite)
- Modify: `src/supervisor.reef` (`conflicts_with`, `mark_conflict_failed`, `service_name_at`)
- Modify: `src/main.reef` (`resolve_conflicts`, `warn_unknown_conflicts`, call site, tier-start state guard)
- Modify: `src/ui_render.reef` (status reason for `FAILED`)

- [ ] **Step 1: Add the test helper**

In `tests/integration/run_tests.sh`, after the `create_service_with_env()` helper, add:
```bash
# Create a service with a [dependencies] conflicts array.
# Usage: create_service_with_conflicts <name> <type> <cmd> "\"other\""
create_service_with_conflicts() {
    local name="$1"
    local type="$2"
    local cmd="$3"
    local conflicts="$4"

    mkdir -p "$CONFIG_DIR/services/$name"
    cat > "$CONFIG_DIR/services/$name/service.toml" << TOML
[service]
description = "Test service: $name"
type = "$type"

[exec]
start = "$cmd"

[dependencies]
conflicts = [$conflicts]

[restart]
on = "never"
TOML
}
```

- [ ] **Step 2: Add the boot-resolution test section**

Append a new section near the other suites (after the "Restart policies" section). Use a fresh config dir like the other sections do:
```bash
# ============================================================================
# Test Suite: Service conflicts
# ============================================================================
section "Service conflicts"

rm -rf "$CONFIG_DIR"
mkdir -p "$CONFIG_DIR" "$ENABLED_DIR"

# Two daemons that declare each other as conflicting; both enabled.
create_service_with_conflicts "mailer-a" "daemon" "$BIN_DIR/sleeper.sh" "\"mailer-b\""
create_service "mailer-b" "daemon" "$BIN_DIR/sleeper.sh"
enable_service "mailer-a"
enable_service "mailer-b"

start_daemon

# Boot resolution: both enabled + conflicting => start neither, fail both.
output=$(zygctl status mailer-a)
assert_contains "$output" "failed" "conflict: mailer-a failed at boot"
assert_contains "$output" "conflicts with" "conflict: mailer-a status shows reason"
output=$(zygctl status mailer-b)
assert_contains "$output" "failed" "conflict: mailer-b failed at boot"

stop_daemon
```

- [ ] **Step 3: Run the suite — confirm the new asserts FAIL**

Run: `./tests/integration/run_tests.sh`
Expected: the four new `conflict:` asserts FAIL (both services currently start and report `running`, never `failed`). Existing tests still pass.

- [ ] **Step 4: Add `conflicts_with` to `supervisor.reef`**

After `service_count` (`src/supervisor.reef:294`), add:
```
// True if services a and b are declared mutually exclusive. Symmetric: a
// conflict declared on either side counts for both. Self-comparison and
// unknown names never match.
fn conflicts_with(table: ServiceTable, a_idx: int, b_idx: int): bool
    if a_idx == b_idx
        return false
    end if
    let a_def = table.runtimes[a_idx].def
    let b_def = table.runtimes[b_idx].def
    let a_name = config.svc_name(a_def)
    let b_name = config.svc_name(b_def)

    let a_conf = config.svc_conflicts(a_def)
    let a_n = config.svc_conflicts_count(a_def)
    mut i = 0
    while i < a_n
        if a_conf[i] == b_name
            return true
        end if
        i = i + 1
    end while

    let b_conf = config.svc_conflicts(b_def)
    let b_n = config.svc_conflicts_count(b_def)
    i = 0
    while i < b_n
        if b_conf[i] == a_name
            return true
        end if
        i = i + 1
    end while

    return false
end conflicts_with
```

- [ ] **Step 5: Add `service_name_at` and `mark_conflict_failed` to `supervisor.reef`**

Directly after `conflicts_with`, add:
```
// Name of the service at idx (convenience for callers outside this module).
fn service_name_at(table: ServiceTable, idx: int): string
    return config.svc_name(table.runtimes[idx].def)
end service_name_at

// Mark a service FAILED because of a conflict, recording the reason for
// `zygctl status`. The skip_reason field doubles as a generic status reason.
proc mark_conflict_failed(table: ServiceTable, idx: int, other_name: string)
    let rt = table.runtimes[idx]
    rt.state = STATE_FAILED()
    rt.skip_reason = str.concat("conflicts with ", other_name)
    table.runtimes[idx] = rt
end mark_conflict_failed
```

- [ ] **Step 6: Add `resolve_conflicts` + `warn_unknown_conflicts` to `main.reef`**

In `src/main.reef`, after the `start_services_by_tier` proc (ends at `:366`), add:
```
// Warn (once, at boot) about conflict targets that name a non-existent service.
proc warn_unknown_conflicts(table: supervisor.ServiceTable, def: config.ServiceDef)
    let conf = config.svc_conflicts(def)
    let n = config.svc_conflicts_count(def)
    mut k = 0
    while k < n
        if supervisor.find_service(table, conf[k]) < 0
            println("zyginit: warning: " + config.svc_name(def) +
                    " conflicts with unknown service: " + conf[k])
        end if
        k = k + 1
    end while
end warn_unknown_conflicts

// Boot-only pre-flight: for every pair of services that are both active in the
// current runlevel and declared mutually exclusive, mark BOTH failed before any
// fork. zyginit never auto-picks a winner. Runtime conflicts (zygctl start,
// runlevel transitions) are handled by the guard in supervisor.start_service.
proc resolve_conflicts(table: supervisor.ServiceTable)
    let n = supervisor.service_count(table)
    mut i = 0
    while i < n
        let rt_i = supervisor.get_runtime(table, i)
        let def_i = supervisor.rt_def(rt_i)
        if supervisor.rt_state(rt_i) == supervisor.STATE_WAITING() and service_in_runlevel(def_i, g_runlevel)
            warn_unknown_conflicts(table, def_i)
            mut j = i + 1
            while j < n
                let rt_j = supervisor.get_runtime(table, j)
                let def_j = supervisor.rt_def(rt_j)
                if supervisor.rt_state(rt_j) == supervisor.STATE_WAITING() and service_in_runlevel(def_j, g_runlevel) and supervisor.conflicts_with(table, i, j)
                    let name_i = config.svc_name(def_i)
                    let name_j = config.svc_name(def_j)
                    supervisor.mark_conflict_failed(table, i, name_j)
                    supervisor.mark_conflict_failed(table, j, name_i)
                    if ui.ui_mode() == ui.MODE_PLAIN()
                        println("zyginit: conflict: " + name_i + " and " + name_j +
                                " are mutually exclusive; failing both")
                    end if
                end if
                j = j + 1
            end while
        end if
        i = i + 1
    end while
end resolve_conflicts
```
(`main.reef` already imports `config`, `supervisor`, and `ui`, and defines `service_in_runlevel` at `:187` and `g_runlevel` at `:167`.)

- [ ] **Step 7: Call `resolve_conflicts` before the boot tier-start**

In `src/main.reef`, in the "Phase 6: Start services" block, the boot call is at `:1093`:
```
        ui.ui_boot_start(svc_count_clamped, num_tiers, runlevel_name)
        start_services_by_tier(table, tiers, tier_counts, num_tiers)
```
Insert the pre-flight between those two lines:
```
        ui.ui_boot_start(svc_count_clamped, num_tiers, runlevel_name)
        resolve_conflicts(table)
        start_services_by_tier(table, tiers, tier_counts, num_tiers)
```
Do NOT add it to the runlevel-transition reuse of `start_services_by_tier` (`:862`); transitions are runtime and rely on the `start_service` guard (Task 3).

- [ ] **Step 8: Make the tier-start loop skip already-FAILED services**

In `start_services_by_tier` (`src/main.reef:278`), the start condition currently is:
```
                if service_in_runlevel(def, g_runlevel) and state != supervisor.STATE_RUNNING()
                    supervisor.start_service(table, idx)
```
A conflict-failed service has `state == FAILED` (not `RUNNING`), so it would otherwise be (re)started. Tighten the condition to only start `WAITING` services:
```
                if service_in_runlevel(def, g_runlevel) and state == supervisor.STATE_WAITING()
                    supervisor.start_service(table, idx)
```
This is safe for the runlevel-transition reuse: newly-active services are `WAITING` (or `mark_runlevel_filtered`), and the existing `elif ... state == STATE_WAITING()` branch below is unaffected.

- [ ] **Step 9: Show the stored reason for FAILED rows in status (`ui_render.reef`)**

In `src/ui_render.reef`, the notes block in `fmt_status_row` (`:168`) currently begins:
```
    if state == supervisor.STATE_SKIPPED()
        let reason = supervisor.rt_skip_reason(rt)
        if str.length(reason) > 0
            notes = reason
        end if
    elif last_exit >= 0 and state != supervisor.STATE_RUNNING() and state != supervisor.STATE_WAITING()
```
Replace the first `if` branch so a `FAILED` service with a stored reason shows it too:
```
    let reason = supervisor.rt_skip_reason(rt)
    if state == supervisor.STATE_SKIPPED() and str.length(reason) > 0
        notes = reason
    elif state == supervisor.STATE_FAILED() and str.length(reason) > 0
        notes = reason
    elif last_exit >= 0 and state != supervisor.STATE_RUNNING() and state != supervisor.STATE_WAITING()
```
(A normally-failed daemon has `reason == ""`, so it still falls through to the `exit=` branch.)

- [ ] **Step 10: Build**

Run:
```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```
Expected: build succeeds.

- [ ] **Step 11: Run the suite — boot asserts now PASS**

Run: `./tests/integration/run_tests.sh`
Expected: the four `conflict:` boot asserts now PASS; all previously-passing tests still pass.

- [ ] **Step 12: Commit**

```bash
hg add tests/integration/run_tests.sh
hg commit src/supervisor.reef src/main.reef src/ui_render.reef tests/integration/run_tests.sh \
    -m "supervisor: boot-time conflict resolution (fail both); status shows reason"
```

---

## Task 3: Runtime guard — refuse (`supervisor.reef` + `socket.reef`)

**Files:**
- Modify: `tests/integration/run_tests.sh` (extend the "Service conflicts" section)
- Modify: `src/supervisor.reef` (`conflicting_running_peer` + guard in `start_service`)
- Modify: `src/socket.reef` (`cmd_start` specific message)

- [ ] **Step 1: Add the runtime-refusal test**

In `tests/integration/run_tests.sh`, inside the "Service conflicts" section, **before** the final `stop_daemon`, append a fresh-config runtime scenario:
```bash
# --- Runtime refusal: starting a service whose conflicting peer runs is refused.
stop_daemon
rm -rf "$CONFIG_DIR"
mkdir -p "$CONFIG_DIR" "$ENABLED_DIR"

# Only svc-a is enabled at boot; svc-b conflicts with it and is started by hand.
create_service "svc-a" "daemon" "$BIN_DIR/sleeper.sh"
create_service_with_conflicts "svc-b" "daemon" "$BIN_DIR/sleeper.sh" "\"svc-a\""
enable_service "svc-a"
enable_service "svc-b"
# Disable svc-b's autostart by NOT enabling it... but boot resolution would fail
# both if both enabled. Instead enable only svc-a; add svc-b via reload-less path:
disable_service "svc-b"

start_daemon

output=$(zygctl status svc-a)
assert_contains "$output" "running" "runtime: svc-a is running"

# Enable svc-b and reload so it joins the table as WAITING, then try to start it.
enable_service "svc-b"
zygctl reload > /dev/null 2>&1
sleep 1
output=$(zygctl start svc-b)
assert_contains "$output" "conflicts with running service" "runtime: start svc-b refused"
output=$(zygctl status svc-a)
assert_contains "$output" "running" "runtime: svc-a still running after refusal"

stop_daemon
```
Note: `reload` adds the newly-enabled `svc-b` as `WAITING` without auto-starting it through the boot pre-flight, which is exactly the runtime path we want to exercise. If `reload` auto-starts new services in this codebase, the `zygctl start svc-b` still exercises the guard because the start is attempted while `svc-a` runs; assert on the refusal message regardless.

- [ ] **Step 2: Run the suite — runtime asserts FAIL**

Run: `./tests/integration/run_tests.sh`
Expected: the two new `runtime:` asserts FAIL (`start svc-b` currently succeeds).

- [ ] **Step 3: Add `conflicting_running_peer` to `supervisor.reef`**

Directly after `conflicts_with` (added in Task 2), add:
```
// Index of a RUNNING/STARTING service that conflicts with idx, or -1 if none.
// Shared by the start guard and by zygctl start for messaging.
fn conflicting_running_peer(table: ServiceTable, idx: int): int
    mut i = 0
    while i < table.count
        if i != idx and conflicts_with(table, idx, i)
            let st = table.runtimes[i].state
            if st == STATE_RUNNING() or st == STATE_STARTING()
                return i
            end if
        end if
        i = i + 1
    end while
    return 0 - 1
end conflicting_running_peer
```

- [ ] **Step 4: Add the guard inside `start_service`**

In `start_service` (`src/supervisor.reef`), immediately after the `[condition]` evaluation block closes (`end if` at `:341`) and **before** `ui.ui_event_starting(name)` (`:344`), insert:
```
    // Conflict guard: refuse to start when a mutually-exclusive peer is already
    // running or starting. Leaves this service's state unchanged. Covers
    // zygctl start, runlevel transitions, and restarts (all funnel here).
    let conflict_peer = conflicting_running_peer(table, idx)
    if conflict_peer >= 0
        let other = config.svc_name(table.runtimes[conflict_peer].def)
        if ui.ui_mode() == ui.MODE_PLAIN()
            println(str.concat(str.concat("supervisor: cannot start ", name),
                    str.concat(": conflicts with running service ", other)))
        end if
        return false
    end if
```

- [ ] **Step 5: Return the specific message from `cmd_start` (`socket.reef`)**

In `src/socket.reef`, in `cmd_start`, after the `already running` check and before `if supervisor.start_service(table, idx)` (`:318`), insert:
```
    let conflict_peer = supervisor.conflicting_running_peer(table, idx)
    if conflict_peer >= 0
        let other = supervisor.service_name_at(table, conflict_peer)
        return "error: cannot start " + name + ": conflicts with running service " + other + "\n"
    end if
```

- [ ] **Step 6: Build**

Run:
```bash
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```
Expected: build succeeds.

- [ ] **Step 7: Run the suite — runtime asserts now PASS**

Run: `./tests/integration/run_tests.sh`
Expected: the `runtime:` asserts now PASS; everything else still green.

- [ ] **Step 8: Commit**

```bash
hg commit src/supervisor.reef src/socket.reef tests/integration/run_tests.sh \
    -m "supervisor: refuse start when a conflicting peer is running"
```

---

## Task 4: Symmetry verification

The symmetric relation is already implemented in `conflicts_with` (it checks both directions). This task adds a regression test proving one-sided declaration is enforced both ways — no implementation change expected.

**Files:**
- Modify: `tests/integration/run_tests.sh` (extend the "Service conflicts" section)

- [ ] **Step 1: Add the symmetry test**

In the "Service conflicts" section, before its final `stop_daemon`, append:
```bash
# --- Symmetry: declare the conflict on ONE side only; both still fail at boot.
stop_daemon
rm -rf "$CONFIG_DIR"
mkdir -p "$CONFIG_DIR" "$ENABLED_DIR"

# only one-side declares the conflict
create_service_with_conflicts "sym-a" "daemon" "$BIN_DIR/sleeper.sh" "\"sym-b\""
create_service "sym-b" "daemon" "$BIN_DIR/sleeper.sh"
enable_service "sym-a"
enable_service "sym-b"

start_daemon

output=$(zygctl status sym-a)
assert_contains "$output" "failed" "symmetry: sym-a failed (declared side)"
output=$(zygctl status sym-b)
assert_contains "$output" "failed" "symmetry: sym-b failed (non-declared side)"

stop_daemon
```

- [ ] **Step 2: Run the suite — symmetry asserts PASS**

Run: `./tests/integration/run_tests.sh`
Expected: both `symmetry:` asserts PASS with no code change (the boot section's `mailer-*` services already declared one-sided, but this makes symmetry explicit). All tests green.

- [ ] **Step 3: Commit**

```bash
hg commit tests/integration/run_tests.sh \
    -m "test: conflicts symmetry — one-sided declaration enforced both ways"
```

---

## Task 5: Documentation

**Files:**
- Modify: `docs/DESIGN.md` (`:103-105`), `docs/man/man5/zyginit.5` (`:160`), `CLAUDE.md` (Service Definition Schema `[dependencies]`), `ROADMAP.md` (`:150`)

- [ ] **Step 1: `docs/DESIGN.md` schema reference**

In the `[dependencies]` example (`:103-105`):
```
[dependencies]
requires = ["network", "filesystem"]
after = ["name-services"]
```
add a `conflicts` line:
```
[dependencies]
requires = ["network", "filesystem"]
after = ["name-services"]
conflicts = ["other-mta"]    # mutually exclusive; never run together
```

- [ ] **Step 2: `zyginit.5` man page**

In `docs/man/man5/zyginit.5`, the `[dependencies]` list ends at `:160-161`:
```
.Dl after = ["syslog", "name-services"]
.El
```
Insert a `conflicts` entry before `.El`:
```
.Dl after = ["syslog", "name-services"]
.It Sy conflicts Pq array of strings
Services that must never run at the same time as this one.
The relation is symmetric: declaring the conflict on either service is enough.
If two conflicting services are both enabled at boot,
.Em both
are marked failed (zyginit never auto-selects a winner).
At runtime,
.Xr zygctl 8
.Cm start
is refused if a conflicting service is already running.
.Pp
Example:
.Dl conflicts = ["sendmail"]
.El
```

- [ ] **Step 3: `CLAUDE.md` quick-reference schema**

In `CLAUDE.md`, the Service Definition Schema `[dependencies]` block:
```
[dependencies]
requires = ["svc1", "svc2"]  # must be running
after = ["svc3"]             # ordering only (not hard dependency)
```
add:
```
[dependencies]
requires = ["svc1", "svc2"]  # must be running
after = ["svc3"]             # ordering only (not hard dependency)
conflicts = ["svc4"]         # mutually exclusive — both fail if both enabled; start refused if peer running
```

- [ ] **Step 4: `ROADMAP.md` — check the box**

At `ROADMAP.md:150`, change:
```
- [ ] **`conflicts`** — prevent two services from running simultaneously
      (e.g., sendmail vs postfix)
```
to:
```
- [x] **`conflicts`** — prevent two services from running simultaneously
      (e.g., sendmail vs postfix). Symmetric; both fail if both enabled at
      boot, runtime start refused if a conflicting peer is running.
```

- [ ] **Step 5: Commit**

```bash
hg commit docs/DESIGN.md docs/man/man5/zyginit.5 CLAUDE.md ROADMAP.md \
    -m "docs: document [dependencies] conflicts field"
```

---

## Final verification

- [ ] **Full suite green**

Run: `./tests/integration/run_tests.sh`
Expected: all suites pass, including the new "Service conflicts" section (boot fail-both, runtime refusal, symmetry). Note the new total in the summary line.

- [ ] **Clean build from scratch**

Run:
```bash
rm -f build/zyginit
clang -c src/helpers.c -o build/helpers.o
clang -c src/contract_linux_stubs.c -o build/contract_linux_stubs.o
reefc build --obj build/helpers.o --obj build/contract_linux_stubs.o
```
Expected: `build/zyginit` builds with no warnings about `conflicts`.

---

## Notes / decisions carried from the spec

- **Two mechanisms, non-overlapping:** after `resolve_conflicts` runs at boot, no conflicting pair both survive as `WAITING`, so the `start_service` guard never trips spuriously during the boot tier loop.
- **Runlevel transitions** use the runtime guard (refuse), not the boot pre-flight — consistent with the "refuse at runtime" semantic.
- **`skip_reason` reuse:** the field stores the conflict reason for `FAILED` services. Kept the field name to minimize diff; `ui_render` now surfaces it for `FAILED` as well as `SKIPPED`. If a future change wants a cleaner name, rename `skip_reason` → `status_reason` across `supervisor.reef` + `ui_render.reef` in one pass.
- **Cascade is intended:** a service that `requires` a conflict-failed service will itself fail to start (existing dependency behavior). Documented, not worked around.
- **`conflicts` is never a graph edge** — `depgraph.reef` is untouched.
# PID-1 Boot Design

**Date:** 2026-04-24
**Revision:** 2026-04-25 — BSD-pivot (post iter 1-5 findings)
**Status:** Revised; iter 6 implementation pending against the new service set
**Scope:** First boot of zyginit as PID 1 on Hammerhead (hh-prototest VM), replacing the SMF-managed boot chain with a zyginit-managed BSD-style boot.

## 1. Goal

Boot hh-prototest with `/sbin/init` pointing at zyginit, bringing the system to a state where the operator can SSH in and use the box. Deliver a small **BSD-style** service set (≈15 services) that uses direct command invocation (`ifconfig`, `dhcpagent`) instead of supervising SMF-coupled control-plane daemons. Tested rollback path via ZFS Boot Environments.

## 1.1 Design revision: BSD pivot (2026-04-25)

The original 21-service design (preserved in §4 history at the bottom of this doc) tried to supervise the existing illumos control-plane daemons — `dlmgmtd`, `ipmgmtd`, `inetd`, `rpcbind`, `fmd` — directly. Iter 1-5 (rev 24 through rev 50) surfaced a fundamental issue: these daemons are tightly coupled to **`svc.configd`** for their persistent property store via `libscf`. Setting `SMF_FMRI` in the environment bypasses their refusal-to-start banner, but they then silently degrade because `scf_handle_decode_fmri()` fails (no `/etc/svc/volatile/repository_door`), leaving them running but useless — `ipmgmtd` doesn't open its door socket; `ipadm` consequently fails with "Could not open handle to library"; `lo0` is never plumbed; `rpcbind` cascades into "could not find loopback transports"; the whole network stack is dead.

We had three choices:

- **A: Run `configd` under zyginit** — keeps the SMF property-store daemon alive, drops only `svc.startd`. Gets the daemons working but admits SMF is too entangled to fully escape.
- **B: Use `/lib/svc/method/*` scripts as zyginit's exec.start** — same effective coupling to `configd` as A; just hides it behind shell wrappers.
- **C: Pivot to BSD-style direct invocation** — drop the configd-coupled daemons entirely. Use `/sbin/ifconfig` directly to plumb interfaces and configure addresses. Use `/sbin/dhcpagent` directly for DHCP. Skip `inetd`/`rpcbind`/`fmd` for the default service set.

We chose **C**. Hammerhead retains the BSD primitives that make this work:

- `/sbin/ifconfig` exists and successfully plumbs interfaces without needing `ipmgmtd`
- `/etc/hostname.<if>` files supported (BSD-style interface naming/config)
- `/sbin/dhcpagent` is callable directly
- `/etc/init.d/`, `/etc/rc[0-3].d/` directories present (we won't use them, but the convention is there)

Reference for the approach: IRIX 6.5's `/etc/init.d/network` script (`os_research/irix-6517-src/eoe/cmd/initpkg/init.d/network`) does exactly this — `IFCONFIG=/usr/etc/ifconfig`, `ROUTE=/usr/etc/route`, flat-file configuration in `/etc/config/`, no daemon-based registry. zyginit-on-Hammerhead becomes essentially a Reef rewrite of pre-SMF Solaris boot semantics, replacing what IRIX/Solaris-9 did with shell.

Lessons from iter 1-5 also drove these other concrete fixes that survive in v2:

- **fd-setup at PID 1**: kernel doesn't preopen 0/1/2; zyginit must `open(/dev/console)` and `dup2()` onto 0/1/2 before any I/O (rev 45)
- **argv[0] in supervisor**: must include the program name as argv[0] when execvp'ing (rev 44)
- **root-fs ZFS/UFS dispatch**: `mount -o remount,rw /` errors on ZFS root; use `zfs set readonly=off` (rev 43)
- **Tier ordering enforcement**: between tiers, wait for oneshots to STOPPED and daemons to RUNNING before starting next tier (rev 47)
- **Persistent log dir**: `/var/log/zyginit/` (not `/var/run`) so logs survive reboot for diagnosis (rev 48)
- **Hammerhead path corrections**: `/bin/hostname` (not `/usr/bin/`), `/sbin/swapadd` (no `-a`), `/sbin/dumpadm`, etc.
- **cron FIFO is at `/etc/cron.d/FIFO`**, not `/var/run/cron_fifo`

A useful diagnostic capability also fell out: with the VM shut down, the BE's logs are readable from the dev host via `qemu-nbd` + zfsonlinux read-only import, then mounting `hhtest/ROOT/zyginit` to read `/var/log/zyginit/*.log`. This bypasses the GRUB-cant-pick-BE limitation on this Hammerhead version.

## 2. Non-goals

- **SMF removal from the BE.** Phase C, separate milestone. First boot leaves SMF binaries installed-but-unused. We just don't *invoke* them from zyginit's service set.
- **Supervising configd-coupled daemons.** `dlmgmtd`, `ipmgmtd`, `inetd`, `rpcbind`, `fmd` are explicitly out of zyginit's default service set. They depend on a running `svc.configd` that we no longer launch. They remain available on the BE for an admin who chooses to set up SMF separately.
- **Modern illumos datalink/IP management semantics.** No `dladm show-link`/`ipadm show-addr` integration. Configuration is via flat files (`/etc/hostname.<if>`, `/etc/defaultrouter`, `/etc/resolv.conf`). For laptops with WiFi roaming, link aggregation, IPMP, or VNICs for zones, this design is insufficient — those workflows need the SMF stack.
- **On-demand network services (inetd-style).** No `inetd` in the default set. Services that historically ran under `inetd` (telnet, rsh, finger, etc.) are not started. SSH is direct.
- **NFS / RPC.** `rpcbind` not started; no NFS in scope.
- **Fault management.** `fmd` not started; FMA events are not collected.
- **Single-user mode / runlevels.** `zygctl single` and `zygctl multiuser` remain stubs.
- **Crash-recovery re-adoption.** `ct_ctl_adopt` requires descendant relationship; only PID-1 in-place re-exec is supported.
- **`/sbin/halt`, `/sbin/reboot`, `/sbin/poweroff`, `/usr/sbin/shutdown` integration.** Continue to call `uadmin` directly. Clean shutdown goes through `zygctl`.
- **Name services (NSS), NTP, performance targets.** Deferred.

## 3. Architecture

### 3.1 Components

| Component | Path | Type | Purpose |
|---|---|---|---|
| `zyginit` | `/sbin/zyginit` | ELF binary | Init daemon (PID 1) |
| `zygctl` | `/sbin/zygctl` | ELF binary | Admin CLI |
| Config tree | `/etc/zyginit/` | Directory | Service TOMLs, per-service script dirs, `enabled.d/` symlink farm |
| Runtime tree | `/var/run/zyginit/` | Directory | Per-service log files, socket, transient state |
| Control socket | `/var/run/zyginit.sock` | Unix socket | zygctl ↔ zyginit IPC |

### 3.2 Boot sequence at runtime

1. Kernel execs `/sbin/init` (symlink to `/sbin/zyginit`)
2. zyginit detects PID (`getpid() == 1`) and enters PID-1 mode
3. zyginit scans `/etc/zyginit/enabled.d/` for symlinks
4. zyginit parses each TOML referenced; builds in-memory `ServiceDef` set
5. zyginit builds dependency graph via topological sort into tier ordering
6. zyginit starts services tier by tier:
   - Within a tier: sequential start (parallel start is a future optimization)
   - Between tiers: wait for all members of tier N to reach terminal state (RUNNING for daemons, STOPPED+exit=0 for oneshots) before starting tier N+1
7. zyginit opens event loop on: contract bundle fd, signal self-pipe, zygctl socket
8. System is "up" when all enabled services have started successfully

### 3.3 PID-1 vs non-PID-1 behavior

| Condition | Trigger | Behavior |
|---|---|---|
| PID 1 | SIGTERM / SIGINT | Halt: stop services in reverse tier order, sync, `uadmin(A_SHUTDOWN, AD_HALT, 0)` |
| PID 1 | `zygctl halt` | As above |
| PID 1 | `zygctl reboot` | Stop services, sync, `uadmin(A_SHUTDOWN, AD_BOOT, 0)` |
| PID 1 | `zygctl poweroff` | Stop services, sync, `uadmin(A_SHUTDOWN, AD_POWEROFF, 0)` |
| not PID 1 | SIGTERM / SIGINT | Stop services, return from `main()` (normal process exit) |
| not PID 1 | `zygctl halt` | Stop services, exit |
| not PID 1 | `zygctl reboot` / `poweroff` | Refuse ("not PID 1") — safety rail for dev/test |

## 4. Service set (BSD-pivot, v2)

15 zyginit services in `enabled.d/` by default (counted across §4.1–§4.6). Replaces the 21-service v1 design (full v1 service table viewable in `hg log -p` for this file) by dropping the configd-coupled daemons in favor of direct command invocation.

### 4.1 Tier 0 — no dependencies

| Service | Type | Script | Stop |
|---|---|---|---|
| `root-fs` | oneshot | `/etc/zyginit/root-fs/start.sh` (ZFS or UFS root: `zfs set readonly=off` or `mount -F ufs -o remount,rw /`) | `/etc/zyginit/root-fs/stop.sh` (matching readonly=on / remount,ro) |

### 4.2 Tier 1 — requires root-fs

| Service | Type | Script | Stop |
|---|---|---|---|
| `devfs` | oneshot | inline: `/usr/sbin/devfsadm` | — |
| `swap` | oneshot | inline: `/sbin/swapadd` (no `-a`; reads `/etc/vfstab`) | `/etc/zyginit/swap/stop.sh` (`swap -d` each active entry) |
| `crypto` | oneshot | `/etc/zyginit/crypto/start.sh` (`cryptoadm refresh`) | — |

### 4.3 Tier 2 — requires tier 1

| Service | Type | Script | Stop |
|---|---|---|---|
| `filesystem` | oneshot | `/etc/zyginit/filesystem/start.sh` (`mountall -l` + `zpool import -a` + `zfs mount -a`) | `/etc/zyginit/filesystem/stop.sh` (`umountall -l` + `zpool sync`) |
| `identity` | oneshot | `/etc/zyginit/identity/start.sh` (`hostname` from `/etc/nodename`) | — |
| `sysconfig` | oneshot | `/etc/zyginit/sysconfig/start.sh` (coreadm, dumpadm, keymap, scheduler, rctl, rmtmpfiles) | — |

### 4.4 Tier 3 — requires filesystem + identity

| Service | Type | Script | Stop |
|---|---|---|---|
| `network` | oneshot | `/etc/zyginit/network/start.sh` — **direct `ifconfig` invocation, no `ipmgmtd`**: plumb lo0, walk `/etc/hostname.<if>` files for each physical interface, `ifconfig <if> dhcp` (which forks `dhcpagent` directly) or static address per file content, install default route from `/etc/defaultrouter` if present | `/etc/zyginit/network/stop.sh` (kill dhcpagent, ifconfig unplumb interfaces) |

**Critical change from v1:** no `dlmgmtd` or `ipmgmtd` services. `ifconfig` plumbs interfaces directly via DLPI. `dhcpagent` is invoked directly via `ifconfig <if> dhcp start`, not via `ipadm -T dhcp`. This matches IRIX 6.5's `/etc/init.d/network` pattern (`IFCONFIG=/usr/etc/ifconfig`, `ROUTE=/usr/etc/route`).

#### `/etc/hostname.<if>` file format (OpenBSD-inspired, illumos-translated)

Verified on hh-prototest: `/sbin/ifconfig` is fully operational without `ipmgmtd` (plumb, address assignment, link state — all work). The OpenBSD `hostname.if(5)` format is line-oriented with each line being ifconfig args. We adopt the same line-oriented convention but translate to illumos's ifconfig syntax, since OpenBSD-specific keywords like `inet alias` map to illumos's `addif`.

Line forms supported by zyginit's `network/start.sh`:

| Line | Action |
|---|---|
| (empty file or whitespace) | `ifconfig <if> plumb up` — interface up, no address |
| `# comment` or blank line | skipped |
| `dhcp` | `ifconfig <if> plumb`; `ifconfig <if> dhcp start` (best effort — see DHCP caveat) |
| `inet <addr>/<prefix>` | `ifconfig <if> inet <addr>/<prefix> up` |
| `inet <addr> netmask <mask>` | `ifconfig <if> inet <addr> netmask <mask> up` |
| `addif <addr>/<prefix>` | additional alias address (illumos `addif`); requires interface already plumbed by an earlier line |
| `inet6 <addr>/<prefix>` | `ifconfig <if> inet6 <addr>/<prefix> up` (deferred to post-first-boot) |
| `up` / `down` | set link state explicitly |

Examples:

```
# /etc/hostname.vioif0 — DHCP via dhcpagent (best effort without ipmgmtd)
dhcp
```

```
# /etc/hostname.vioif0 — static IPv4
inet 192.168.122.50/24
```

```
# /etc/hostname.vioif0 — static IPv4 + alias
inet 192.168.122.50/24
addif 192.168.122.51/24
```

#### Default route

`/etc/defaultrouter` (one IPv4 address per line). `network/start.sh` runs `route -n add default <addr>` for each. Optional — DHCP-acquired routes don't need this file.

#### DHCP caveat

`dhcpagent` is linked against `libipadm.so.1`, which talks to `ipmgmtd`'s door for persistent state. Without `ipmgmtd` running:
- `dhcpagent` itself runs (self-contained DHCP state machine)
- DHCP request/response on the wire works (uses raw sockets, not libipadm)
- **Applying the lease to the interface** uses libipadm → ipmgmtd, which may degrade

Empirical test required on hh-prototest in iter 6 boot. If DHCP-via-ifconfig fails without ipmgmtd, fallback options:
1. Manually invoke `dhcpagent -a -f` (adopt mode + foreground) and configure interface from received lease via direct DLPI ioctl
2. Static IP only for the test VM (configure libvirt to have a known static address, set `/etc/hostname.vioif0` to `inet 192.168.122.50/24`)
3. Patch dhcpagent / replace with dhclient if available

The implementation plan should boot-test with static IP first to derisk the rest of the boot, then attempt DHCP as a follow-up.

### 4.5 Tier 4 — requires network (configd-free system daemons)

All daemons. All use `stop.method = "contract"` (default). `restart.on = "failure"`, `delay = 5`, `max_retries = 3`.

| Service | exec.start | Note |
|---|---|---|
| `syseventd` | `/usr/lib/sysevent/syseventd` | Kernel event delivery; doesn't read SMF properties |
| `syslogd` | `/usr/sbin/syslogd` | Reads `/etc/syslog.conf` directly; SMF-property reads degrade to defaults |
| `utmpd` | `/usr/lib/utmpd` | Cleans stale utmpx entries; no configd dependency |
| `pfexecd` | `/usr/lib/pfexecd` | RBAC profile-exec helper; reads `/etc/security/`, no configd |

### 4.6 Tier 5 — user-facing services

| Service | exec.start | Note |
|---|---|---|
| `cron` | `/etc/zyginit/cron/start.sh` | wrapper: `rm -f /etc/cron.d/FIFO; exec /usr/sbin/cron` |
| `sshd` | `/usr/lib/ssh/sshd -D` | `-D` keeps it foreground; reads `/etc/ssh/sshd_config` |
| `console-login` | `/etc/zyginit/console-login/start.sh` | wrapper exec'ing ttymon with properly-quoted prompt |

### 4.7 Optional / installable — TOMLs ship but symlinks not in `enabled.d/` by default

These TOMLs exist in `services/hammerhead/` but are NOT enabled by default. An admin can enable them via `zygctl enable <svc>` on hardware/configurations where they make sense:

| Service | When to enable |
|---|---|
| `powerd` | Real hardware with `/dev/srn` (not VMs) |
| `fmd` | When fault management is wanted (requires configd workaround or future SMF-coexistence design) |
| `dlmgmtd` / `ipmgmtd` / `inetd` / `rpcbind` | Only after a separate "run minimal SMF infrastructure under zyginit" design is implemented |

### 4.8 Dropped from the v1 design (configd-coupled, requires separate design to revisit)

These daemons require `svc.configd` running for `libscf` calls to succeed. They are intentionally absent from the BSD-pivot v2 service set:

- `dlmgmtd` — datalink management. Replaced by direct `ifconfig` plumbing. Drawback: no `dladm show-link` queries; persistent datalink state across reboots is via `/etc/hostname.<if>` instead.
- `ipmgmtd` — IP interface management. Replaced by direct `ifconfig`/`route` invocation. Drawback: no `ipadm` queries.
- `inetd` — on-demand service launching. Modern illumos `inetd` reads from configd. No replacement for first boot; can be re-added when needed (e.g., via `xinetd` or by accepting configd dependency).
- `rpcbind` — only needed for NFS/RPC; deferred until NFS is in scope.
- `fmd` — fault management daemon; heavy SMF coupling. Deferred.

### 4.9 SMF infrastructure (subsumed; no replacement)

- `svc.startd`, `svc.configd` — replaced by zyginit (or absent in v2)
- `manifest-import`, `early-manifest-import` — no XML manifests
- `boot-archive`, `boot-archive-update` — SMF-specific
- `logadm-upgrade`, `update-man-index` — admin/cron concerns, not init's
- All 7 SMF milestones (virtual groupings) — zyginit's dependency graph replaces these

### 4.10 Currently-disabled SMF services — also not resurrected in zyginit

Mirrors v1: `name-service-cache`, `rbac`, `process-security`, `auditd`, NFS/DNS/LDAP stacks all stay disabled.

## 5. TOML schema usage

Uses the schema already documented in `docs/DESIGN.md` §"Service Definition Format". The following subset is in active use for the 21 services:

```toml
[service]
name = "..."
description = "..."
type = "daemon" | "oneshot"

[exec]
start = "command or /etc/zyginit/<svc>/start.sh"

[dependencies]
requires = ["..."]
after = ["..."]

# Daemons only:
[stop]
method = "contract"          # default; may be omitted
signal = "TERM"              # default; may be omitted
timeout = 60                 # default; may be omitted

[restart]
on = "failure"
delay = 5
max_retries = 3

[contract]
param = ["inherit", "noorphan"]
fatal = ["hwerr"]

# Oneshots with reversal:
[exec]
stop = "/etc/zyginit/<svc>/stop.sh"

[restart]
on = "never"
```

**Defaults and omissions:**
- Omitted `exec.user` / `exec.group` → inherits from zyginit → root when PID 1. Explicit and documented so there's no ambiguity.
- Omitted `[stop]` block → uses contract-signal defaults (TERM, 60s timeout).
- Omitted `[contract]` block → uses template defaults from `setup_template()` in `contract.reef`.

**Deferred schema fields** (supported by zyginit, unused in first boot):
- `exec.user`, `exec.group`, `exec.working_directory`, `exec.environment` — none of the 21 services need privilege drop or per-service env
- `security.*`, `limits.*` — not implemented / not in first boot

**`contract.param = ["inherit", "noorphan"]` note:**
The NOORPHAN flag means that if zyginit-as-PID-1 dies without cleanly abandoning contracts, children receive SIGHUP. This is correct for PID-1 re-exec (kernel sees the same process, no SIGHUP fires). It is **incompatible** with a crash-recovery path that promotes a fresh zyginit PID — but such a path is an explicit non-goal per §2.

## 6. Method script conventions

All scripts live under `/etc/zyginit/<svc>/start.sh` (and optional `stop.sh`) unless the service is trivial enough for an inline TOML command.

**Template:**
```zsh
#!/bin/zsh
# <service> — <one-line purpose>
# Invoked by zyginit via exec.start in /etc/zyginit/<service>.toml

set -e
set -u

# ... steps ...

exit 0
```

**Conventions:**
1. Shebang: `#!/bin/zsh` (consistent with Hammerhead's shell policy; zsh is the system default, ksh93 is being phased out)
2. Error handling: `set -e` (POSIX-style — preferred over `setopt ERR_EXIT` for cross-shell readability) + `set -u`
3. Non-interactive only: no `read`, no tty-dependent behavior
4. Self-contained: no `source`ing of SMF helper scripts (`/lib/svc/share/*.sh`)
5. No SMF API calls: no `svcprop`, `svcadm`, `svccfg`. Config input comes via `exec.environment` in the TOML.
6. Explicit `exit 0` on success (not relying on implicit last-command exit)
7. Use `|| true` deliberately per-command where a specific failure is acceptable (e.g., `dumpadm -d /path || true` if the dump device doesn't exist yet)
8. Idempotent when the action allows: prefer `mount -o remount,rw /` (idempotent) over raw `mount` commands. Use "check then do" patterns for inherently non-idempotent operations (`ipadm show-if lo0 2>/dev/null || ipadm create-if lo0`).

**Execution environment zyginit provides to scripts:**
- Fresh process (fork + exec)
- Working dir: `/` unless TOML sets `exec.working_directory`
- Environment: minimal (PATH, HOME, etc.) plus whatever `exec.environment` specifies
- stdout/stderr: redirected to `/var/run/zyginit/log/<svc>.log`, truncated per start
- User: inherited from zyginit (root at PID 1) unless `exec.user` set

## 7. Shutdown orchestration

Shutdown is a first-class concern, not deferred. Unclean shutdown can corrupt ZFS; we do it right from the first boot.

### 7.1 Shutdown triggers

| Source | Type |
|---|---|
| `zygctl halt` | halt |
| `zygctl reboot` | reboot |
| `zygctl poweroff` | poweroff |
| SIGTERM / SIGINT (PID 1) | halt (conservative default) |
| SIGTERM / SIGINT (not PID 1) | exit (integration test path) |

Shutdown type is communicated to zyginit via the socket protocol (for zygctl commands) or inferred from signal source.

### 7.2 Shutdown walk

1. Set `shutdown_requested = true`, `shutdown_type = <type>`
2. Break out of main event loop
3. Walk services **in reverse tier order** (not insertion order)
4. For each service in the tier:
   - **Daemons** in `STATE_RUNNING`: `stop_service()` → SIGTERM via contract, wait for contract EMPTY event, mark `STATE_STOPPED`
   - **Oneshots** in `STATE_STOPPED` with `exec.stop` defined (or `/etc/zyginit/<svc>/stop.sh` present): fork/exec the stop command; wait for exit
   - **Oneshots** without stop: skip (no reversal defined)
5. Wait for all services in tier N to reach `STATE_STOPPED` before moving to tier N-1
6. After tier 0 is drained: `sync()` (flush pending writes)
7. Call `uadmin(A_SHUTDOWN, <fcn>, 0)`:
   - `AD_HALT` (0) — halt, operator decides next step physically
   - `AD_BOOT` (1) — reboot immediately
   - `AD_POWEROFF` (6) — ACPI/BMC chassis off

### 7.3 Stop scripts concretely required

| Service | stop.sh action |
|---|---|
| `root-fs` | `mount -o remount,ro /` (called after filesystem/stop.sh has umounted everything else) |
| `filesystem` | `umountall -l` |
| `swap` | `swap -d` each entry |

Other services either use the contract-signal daemon default or have nothing to reverse.

### 7.4 Required code changes

**`supervisor.reef`:**
- Extend shutdown path to walk tiers in reverse
- For each tier: first send stops to all daemons, wait for them to exit, then run stop scripts for oneshots that have them
- Currently `shutdown_services` skips `STATE_STOPPED` services — this must change

**`main.reef`:**
- Track `shutdown_type` variable (halt / reboot / poweroff)
- After `shutdown_services()`: call `sync()`, then `zyginit_shutdown(<fcn>)`

**FFI: `helpers.c` and `contract.reef` (or new `shutdown.reef`)**:
- `int zyginit_shutdown(int fcn)` → wraps `uadmin(A_SHUTDOWN, fcn, 0)`
- `extern "C" fn zyginit_shutdown(fcn: int): int`

**Linux stub**: `contract_linux_stubs.c` gets a matching stub returning -1 (should never actually fire on Linux).

**`zygctl`** gets three new subcommands: `halt`, `reboot`, `poweroff`. Each sends a specific command over the socket; zyginit sets `shutdown_type` accordingly.

**`zygctl`** also gets two stub subcommands: `single`, `multiuser`. Both print "not yet implemented — reserved for future runlevel support" and exit 1. Documented in `zygctl --help` so the surface is stable.

## 8. Rollout phases

### 8.1 Phase A — non-PID-1 dry run

Run zyginit on the live hh-prototest system alongside SMF, using a scratch config directory.

```sh
ZYGINIT_CONFIG_DIR=/tmp/zyginit-dry \
  /path/to/zyginit
```

**Goals:**
- TOMLs parse cleanly
- Dependency graph builds without cycles; tier order matches the spec
- zyginit supervises one or two non-conflicting test daemons (e.g., a second sshd on port 2222)
- Clean shutdown via SIGTERM works without uadmin (non-PID-1 path)

**Out of scope for Phase A:**
- Destructive oneshots (filesystem, network, devfs) — they'd conflict with SMF-managed copies. Skip these in the dry run.

### 8.2 Phase B — PID-1 boot in a fresh Boot Environment

1. `beadm create zyginit`
2. `beadm mount zyginit /mnt`
3. Install into `/mnt`:
   - `/mnt/sbin/zyginit`, `/mnt/sbin/zygctl`
   - `/mnt/etc/zyginit/*.toml` (21 files)
   - `/mnt/etc/zyginit/<svc>/start.sh` + `stop.sh` as specified above
   - `/mnt/etc/zyginit/enabled.d/` symlinks for all 21
   - Preserve old init: `mv /mnt/sbin/init /mnt/sbin/init.smf`
   - New init: `ln -s /sbin/zyginit /mnt/sbin/init`
4. `beadm umount zyginit; beadm activate zyginit; init 6`

### 8.3 Phase C — SMF removal (deferred, separate milestone)

Optional follow-up once Phase B is stable:
- In the zyginit BE: remove `/lib/svc/bin/svc.startd`, `/lib/svc/bin/svc.configd`, `/lib/svc/method/*`, `/etc/svc/`
- Activate, reboot, prove the system still works without SMF
- This is when "zyginit replaces SMF" is literally true.

### 8.4 Failure recovery ladder

In order of cost:

1. `zygctl reboot` → pick `hammerhead` BE from GRUB menu (seconds)
2. If GRUB menu inaccessible: boot into rescue media / single-user from install media, mount original BE, activate it
3. If the pool is damaged: `sudo cp hh-prototest-backup-2026-04-24-pre-zyginit-pid1.qcow2 hh-prototest.qcow2` on the dev host (2-3 min with VM shut down)
4. Last resort: VM rebuild from scratch (~20 min)

Disk-level backup captured at rev 21. Recovery drill is part of §9.F.

## 9. Success criteria for Phase B

Literal checklist run after first boot into the zyginit BE.

### A. Boot completes
- [ ] No `kernel panic: init died`
- [ ] `zyginit: entering event loop` appears on console
- [ ] Every tier finishes within 60s total
- [ ] Console login prompt appears on `/dev/console`

### B. Expected service states
- [ ] All 21 services present in `zygctl list`
- [ ] Tier 0-3 oneshots: `STOPPED` with `exit=0`
- [ ] Tier 3-5 daemons: `RUNNING`
- [ ] No service in `MAINTENANCE`

### C. Services actually functional
- [ ] `ssh zygaena@192.168.122.197` from dev host
- [ ] `logger -p user.info test` → visible in `/var/adm/messages` (syslogd)
- [ ] `dladm show-link` lists physical interface `up`
- [ ] `ipadm show-addr` lists lo0 + physical interface with IPv4 addresses
- [ ] `ping 192.168.122.1` succeeds
- [ ] `crontab -l` runs for root
- [ ] `zfs list` works, `hhtest` pool mounted

### D. zygctl end-to-end
- [ ] `zygctl status cron` shows `RUNNING` with uptime > 0
- [ ] `zygctl stop cron` → `STOPPED`, then `zygctl start cron` → `RUNNING`
- [ ] `zygctl log sshd` returns without error
- [ ] `zygctl reload` succeeds (SIGHUP path)

### E. Clean shutdown
- [ ] `zygctl halt`: reverse-tier-order stop output in console; system halted cleanly
- [ ] `zygctl reboot`: cycles; comes back via zyginit again
- [ ] `zygctl poweroff`: VM transitions to `shut off` in libvirt
- [ ] After any zygctl shutdown: `zpool status` clean, no replay-required flags

### F. Rollback confirmed
- [ ] 3 clean reboot cycles into the zyginit BE
- [ ] Reboot into original `hammerhead` BE from GRUB → SMF comes up normally
- [ ] `beadm activate hammerhead` from zyginit BE → reboot → lands on `hammerhead` BE
- [ ] Disk-level restore drill executed at least once (time to recovery measured)

### G. Explicit non-requirements
- No boot-time performance gate (measured for baseline only)
- No stability soak
- No DNS / hostname resolution testing
- No NTP / time sync
- No name services (NSS beyond /etc/passwd, /etc/hosts, /etc/group)
- No `zygctl single` / `zygctl multiuser` functionality (stubs only)
- No SMF removal (Phase C)

## 10. Observability during test

- Console access via `virsh console hh-prototest` for live boot watching.
- `/var/log/zyginit/<svc>.log` per-service logs (rev 48 changed default from `/var/run/zyginit/log` to `/var/log/zyginit` so logs survive reboot).
- **Out-of-band log access:** with VM shut down, mount the BE's qcow2 from the dev host:
  ```
  virsh destroy hh-prototest
  sudo qemu-nbd -c /dev/nbd0 -r /var/lib/libvirt/images/hh-prototest.qcow2
  sudo zpool import -R /tmp/hh-mnt -o readonly=on -N -f -d /dev/nbd0p2 hhtest
  sudo zfs mount hhtest/ROOT/zyginit
  # logs at /tmp/hh-mnt/var/log/zyginit/
  ```
  Restore: `zfs umount`, `zpool export hhtest`, `qemu-nbd -d /dev/nbd0`. Proven across 3 iterations.
- Capture console screenshot at each iter for visual cross-check.

## 11. Explicit deferrals (captured for future work)

Each of the following is a known follow-up, documented here so future milestones inherit the boundary:

- **configd-coupled daemons re-add**: if `dlmgmtd`/`ipmgmtd`/`inetd`/`rpcbind`/`fmd` are needed, design either a "minimal SMF infrastructure under zyginit" (configd as a zyginit-supervised daemon) or a per-daemon configd-bypass shim.
- **Runlevel targets**: `zygctl single`, `zygctl multiuser` stubs shipped; implementation needs a target-set schema extension (e.g., `service.runlevels = ["single", "multiuser"]`).
- **Milestone-style virtual services**: systemd-target equivalent; probably needed to implement runlevels cleanly.
- **`/sbin/halt`, `/sbin/reboot`, `/sbin/poweroff`, `/usr/sbin/shutdown` wrappers**: replace with versions that route through `zygctl`.
- **`init <n>` runlevel compatibility**: unsupported; use zygctl.
- **Crash-recovery re-adoption**: architecturally not supported (illumos descendant requirement); documented.
- **NOORPHAN revisit**: current template is correct for PID-1 re-exec; revisit only if a non-exec crash-recovery goal is added.
- **GC tuning under sustained uptime**: track separately.
- **SMF removal from disk**: Phase C — once zyginit is stable, optionally remove `/lib/svc/`, `/etc/svc/` from the BE entirely.
- **Boot performance targets**: no gate.
- **Additional services** (resource limits, audit, DNS, NFS, zones): add as needed post-first-boot.
- **Hostid persistence**: first boot reads `/etc/hostid`; generation logic (for first-ever boot) not yet implemented.
- **Modern datalink/IP semantics**: BSD-pivot loses `dladm`/`ipadm` query interfaces. For zone hosts, laptops, multi-homed servers, this design is insufficient; revisit when those use cases are in scope.

## 12. Pre-requisites completed before this spec

- **Contract probe**: 16/16 FFI probes pass on hh-prototest (rev 19)
- **contract.reef bugs fixed**: P_CTID 14→13, ctl fd O_WRONLY (rev 18)
- **Path rename**: `/etc/zyginit.d/` → `/etc/zyginit/` (rev 20, 21)
- **Signal handling fix**: dead-code flag-clearing block removed (rev 15)
- **Build split**: `helpers.c` / `contract_linux_stubs.c` separated (rev 16)
- **Disk backup**: `hh-prototest-backup-2026-04-24-pre-zyginit-pid1.qcow2` captured on dev host

**Pre-requisites added during iter 1-5 of v1 (kept in v2):**
- **fd-setup at PID 1** (rev 45): `setup_pid1_console()` opens `/dev/console` and dup2's onto 0/1/2 before any I/O
- **argv[0] fix** (rev 44): supervisor.start_service includes program name as argv[0]
- **uadmin/sync wiring** (rev 24-31): full PID-1 shutdown path
- **Tier-ordering enforcement** (rev 47): supervisor waits for tier N to settle before starting N+1
- **Persistent log dir** (rev 48): `/var/log/zyginit/` default
- **root-fs ZFS/UFS dispatch** (rev 43): correct readonly toggle per fstype
- **zygctl shutdown commands** (rev 33-34): halt/reboot/poweroff + single/multiuser stubs
- **Path corrections in scripts** (rev 49-50): `/bin/hostname`, `/bin/rm`, `/sbin/swapadd` (no `-a`), `/sbin/dumpadm`, etc.

## 13. Open questions / defer to implementation

Most v1 open questions are now answered (uadmin constants verified; ipmgmtd path verified; ttymon argv conventions known). v2 open questions answered through 2026-04-25 hh-prototest probing:

- ✅ **`ifconfig` capability without ipmgmtd**: `ifconfig lo0:99 plumb`, `ifconfig lo0:99 inet 127.99.0.1 netmask 255.0.0.0 up`, and `ifconfig lo0:99 unplumb` all worked silently while ipmgmtd was running. `ifconfig` operates at the DLPI/kernel-ioctl layer for plumbing; ipmgmtd integration is for *persistent state*, not for runtime configuration.
- ✅ **`ifconfig <if> dhcp <subcommand>` syntax**: per ifconfig(8) man page on hh-prototest, supported subcommands are `start | stop | drop | extend | inform | ping | release | status`. `ifconfig vioif0 dhcp status` returned valid info while pinging the running dhcpagent on TCP 4999.
- ✅ **`/etc/hostname.<if>` parsing**: Hammerhead's `ifconfig` does NOT read this file directly. The file is consumed by SMF method scripts. zyginit's `network/start.sh` will parse the file itself (line-oriented format documented in §4.4).
- ✅ **`/etc/defaultrouter`**: empty/absent on hh-prototest (DHCP supplies the route). Format: one IPv4 address per line. `network/start.sh` reads when present and DHCP isn't in use.

Remaining for iter 6 to empirically verify:

- ⚠ **DHCP-via-dhcpagent without ipmgmtd running**: dhcpagent links libipadm which talks to ipmgmtd. Plan: try `ifconfig <if> dhcp start` after starting dhcpagent fresh under zyginit; if it works, ship as default; if it fails, ship static-IP-only and document. The test VM has a libvirt-supplied dnsmasq DHCP server on 192.168.122.0/24 — perfect environment to verify.
- ⚠ **First-boot fallback**: if DHCP fails, our test config will use a static IP (e.g., `inet 192.168.122.50/24`) chosen outside libvirt's dnsmasq pool to avoid conflicts.
# Contract Re-adoption (Live Replace) Design

**Date:** 2026-05-02
**Status:** Approved (brainstorm complete); implementation plan to follow
**Scope:** Live in-place replacement of the running zyginit PID-1 process — replacing the `/sbin/init` binary while preserving every running service across the swap. Operator-driven only; not a crash-recovery design.

## 1. Goal

Allow an operator (or automation tool) to upgrade the running zyginit binary without rebooting and without dropping any service. After the operation, every previously-RUNNING service continues to run with the same contract ID, accumulated `restart_count`, and continuous `last_start_time` (uptime). The connection between zyginit and supervised services is preserved across the exec; the only thing replaced is the program text and in-memory state of PID 1 itself.

The verb the operator uses is `zygctl replace`. The mechanism is `execve("/sbin/init", ...)` against the same proc-table slot, with a state-file handoff for in-memory bookkeeping.

## 2. Non-goals

- **Crash recovery.** If zyginit segfaults / panics, the kernel's `restart_init` re-execs `/sbin/init` in a tight loop, but the contracts are not preserved across that path (NOORPHAN templates would have killed members already). PID 1 dying is a much larger issue than this design solves; we explicitly do not try.
- **Live binary swap.** `zygctl replace` does not copy or stage a binary. The operator (or package manager / configuration management tool) is expected to drop the new binary at `/sbin/init` first, then call `zygctl replace`. We hard-wire the exec target.
- **Switching to a different init system.** `zygctl replace` always execs `/sbin/init` with no path argument. Switching init systems is a rescue-media operation.
- **Signal-driven trigger.** No SIGUSR2 handler. Socket is the only path. (Revisit only if a real demand surfaces; see §10.)
- **Crash-recovery argv-scan / proc-walk.** No fallback that reconstructs identity from `/proc/<pid>/psinfo`. State file is the only source of truth.
- **Recovery for transient-state services** (`STARTING`, `STOPPING`, `WAITING`-for-restart). `replace` refuses on transient state by default; with `--wait=N` it polls for stability before refusing. `--force` is **not** in scope for v1.
- **Preserving in-flight zygctl connections.** Clients lose their connection at exec; that's expected. Operators reconnect for follow-up commands.

## 3. Why this works on Hammerhead — the key insight

On illumos / Hammerhead, process contracts are tracked on the process structure (`proc_t.p_ct_process` / `p_ct_equiv`). When a process calls `execve()`, the kernel replaces the program text and (re-)initializes most of `proc_t`, but **the proc-table slot and contract ownership survive**. This is what makes live replace possible: PID 1 is the same `proc_t` before and after the exec, so all contracts it held continue to be held by it.

Consequence: the new zyginit **does not need `ct_ctl_adopt`**. Adoption is for the SMF-startd model — a non-PID-1 supervisor dies and its successor (a fresh process with a different `proc_t`) needs to claim the orphan-inherited contracts. For PID-1 in-place exec, kernel-level ownership is automatic; we only need to rebuild the userspace bookkeeping (which contract belongs to which service, and what runtime fields to carry over).

The bundle fd (`/system/contract/process/bundle`) does close at exec (we don't try to inherit it via FD_CLOEXEC manipulation), so the new zyginit re-opens it. Events that fire during the gap between old-process exec and new-process bundle re-open are recovered via a post-startup `ct_status_read` check on each known contract — if the contract is already empty, we synthesize an empty event into the existing `handle_contract_event` path. This is idempotent regardless of whether the gap actually missed any events.

## 4. Architecture

```
                  Operator
                     |
                     v
              zygctl replace
              [--wait=N]
                     |
              +------+-------+
              |   socket     |   "replace queued"
              |   (sock.reef)|----------------> zygctl prints, exits
              +------+-------+
                     |  set replace_requested flag
                     v
            main.reef event loop
                     |
                     v
              replace_self()
                     |
   +-----------------+-----------------+
   | 1. preconditions (--wait optional)|
   | 2. drain pending bundle events    |
   | 3. write state.toml (atomic)      |
   | 4. unlink socket                  |
   | 5. close internal fds             |
   | 6. execve("/sbin/init", argv)     |
   +-----------------+-----------------+
                     |
                     v
          /// SAME proc_t, new program text ///
                     |
                     v
            new main() startup
                     |
   +-----------------+-----------------+
   | 1. setup_pid1_console (as today)  |
   | 2. recover_state(boot_time)       |
   |    — reads state.toml, validates  |
   |      boot_time, returns entries   |
   | 3. load enabled.d/ TOML (as today)|
   | 4. apply_recovered_state(table,   |
   |       recovered)                  |
   | 5. tier-by-tier start_service     |
   |    (skips entries already RUNNING)|
   +-----------------+-----------------+
                     |
                     v
              normal main loop
```

**Module split:**

| File | Change | Why |
|---|---|---|
| `src/replace.reef` | new (~200 lines) | Holds the state-file format, serialization, and recovery logic. Keeps `main.reef` lean. |
| `src/main.reef` | +60 lines | `replace_self`, `apply_recovered_state`, integration with main loop and startup. |
| `src/socket.reef` | +30 lines | `replace [--wait=N]` command handler, `replace_requested()` / `clear_replace_flag()` / `replace_wait_seconds()` accessors. |
| `src/contract.reef` | +20 lines | `is_contract_empty(ctid): bool` helper wrapping `ct_status_read` + member-count check. |
| `tools/zygctl/src/zygctl.reef` | +20 lines | `replace [--wait=N]` subcommand. |

No new C helpers. No FFI additions (`adopt_contract` already exists but is not used by this flow; it stays for potential future uses).

## 5. State file format

**Location:** `/var/run/zyginit/state.toml`. Same directory currently used for the socket. On the current zyginit-only BE, `/var/run` is persistent across real reboots (not yet tmpfs); the boot-id check (§5.2) makes stale post-reboot files harmless.

**Format:** TOML, parseable by the existing `encoding.toml` parser.

```toml
boot_time = 1746204000

[[service]]
name = "sshd"
contract_id = 23
restart_count = 0
last_start_time = 1746204051
last_exit_code = -1

[[service]]
name = "syslogd"
contract_id = 17
restart_count = 1
last_start_time = 1746204047
last_exit_code = 0
```

### 5.1 What is and isn't serialized

Serialized:
- `boot_time` — PID 1's process start time, read from `/proc/1/stat` (Linux) or `/proc/1/psinfo` (Hammerhead). Survives `execve` but changes on real reboot. Used as a staleness sentinel — see §5.2.
- For each service in `STATE_RUNNING`:
  - `name` — the canonical service name (matches `enabled.d/` symlink basename).
  - `contract_id` — kernel-assigned contract ID.
  - `restart_count` — accumulated restart counter (for `max_retries` accounting).
  - `last_start_time` — Unix timestamp of the most recent start.
  - `last_exit_code` — most recent exit code (or `-1` if never exited).

Not serialized:
- `pid` — recoverable from contract status if needed; not needed for the contract-driven supervision path.
- `state` — only `RUNNING` services serialize (per §6 pre-conditions); the field is implicit.
- `stop_requested_time`, `restart_scheduled_time` — only meaningful in transient states, which we refuse.
- `def` (the parsed TOML ServiceDef) — the new zyginit re-reads `enabled.d/` from disk, so the def comes from current TOML on the new side. This means a TOML edit between old-start and replace takes effect on next restart. (See §7.3 for the divergence handling.)

### 5.2 Boot-id staleness check

The boot-id sentinel is PID 1's process start time, read from `/proc/1/stat` field 22 (Linux: jiffies-since-boot) or `/proc/1/psinfo pr_start.tv_sec` (illumos/Hammerhead: Unix timestamp) via `zyginit_read_pid1_start()` in `helpers.c`. This value survives `execve` (same `proc_t` slot) but changes on real reboot (new PID 1). If `state.toml.boot_time != current.boot_time`, the file is from a different system uptime — most likely a stale file left over from before a real reboot. We log `"replace: stale state file (boot_time mismatch); ignoring"`, delete the file, and proceed as a fresh boot.

**Why not utmpx BOOT_TIME?** The original design used `utmpx BOOT_TIME` as the sentinel. This was found to be incorrect: `pututxline` with `ut_type = BOOT_TIME` *updates* the existing matching record (by design, to support `who -b`), rather than appending a new one. After a live replace, the new zyginit's startup call to `zyginit_write_boot_utmpx()` overwrites the original BOOT_TIME with a fresh timestamp. The new zyginit then reads its own updated timestamp as the current boot_time — which matches the new timestamp it just wrote — while state.toml has the old timestamp from before the replace. Result: mismatch, state.toml discarded, recovery fails silently. `/proc/1/start` avoids this entirely: no write occurs to it at startup, and it is immutable for the life of the PID 1 proc_t.

This guards against the edge case where contract IDs are re-used after a real reboot (the kernel does recycle them) and we'd otherwise adopt the wrong contract. The check is cheap (one integer comparison) and correct in the common case (replace = same boot_time; reboot = different boot_time).

The state file is **deleted by the new zyginit after a successful read**, regardless of whether all entries were applied successfully. This way, a panic-restart loop (kernel re-execing `/sbin/init` repeatedly) does not keep trying to apply long-dead entries.

### 5.3 Atomic write

Writing follows the standard pattern, using the existing `zyginit_fsync_path` C helper:

1. `open("/var/run/zyginit/state.toml.tmp", O_WRONLY|O_CREAT|O_TRUNC, 0600)`
2. Write boot_time + each service entry. (Reef-side TOML emit is straightforward; we don't need the full encoding.toml emit machinery, just print to fd.)
3. `fsync(fd)`, `close(fd)`.
4. `rename("/var/run/zyginit/state.toml.tmp", "/var/run/zyginit/state.toml")`.
5. `zyginit_fsync_path("/var/run/zyginit")` — fsync the parent directory so the rename is durable.

Any failure aborts the replace (we do not exec). At most we leave a `.tmp` file, which is overwritten on the next attempt and never read.

## 6. Operator interface

### 6.1 `zygctl replace`

```
zygctl replace [--wait=N]
```

- Connects to `/var/run/zyginit.sock`.
- Sends `replace [--wait=N]\n`.
- Reads reply (`replace queued (wait=N)\n` or an error).
- Prints reply, exits 0 on success, non-zero on parse error from server.
- The TCP/Unix-socket connection itself drops mid-response if the server proceeds to exec. zygctl treats `EPIPE` / connection-closed-after-ack as success and prints `replace: socket closed (process replaced)\n`.

### 6.2 `--wait=N`

If any service is in a transient state (`STARTING`, `STOPPING`, `WAITING`-for-restart), the server polls once per second for up to `N` seconds, checking whether all services are in stable states (`RUNNING`, `STOPPED`, `FAILED`, `MAINTENANCE`, `DISABLED`). If stability is reached within the window, replace proceeds. If not, replace is refused with `"replace blocked: <name>:<state>, ..."` logged to syslog (and to stderr if attached). Default is `--wait=0` (refuse immediately).

The wait happens server-side after the ack to the client, so the zygctl client doesn't have to hold a connection open — automation can `zygctl replace --wait=120` and either get a clean dropped connection (success) or, if the wait times out without exec'ing, can detect the failure by reconnecting and inspecting service states.

### 6.3 Pre-conditions in detail

Before exec, zyginit checks:

1. **No service is in a transient state.** (After `--wait` window if specified.)
2. **`state.toml.tmp` write succeeds**, including fsync.
3. **`rename` to `state.toml` succeeds**, including parent-dir fsync.

If any of these fail, replace aborts cleanly and the running zyginit continues. The flag is cleared, no exec happens, and the failure is logged. The operator can retry.

The socket unlink and fd cleanup happen *after* a successful state write — they are last-mile actions before exec, and we don't fail the replace if they error (we log and proceed).

## 7. Recovery flow (new zyginit)

### 7.1 Startup sequence

```
main():
    parse argv, kernel boot args
    if pid == 1: setup_pid1_console()
    boot_time = read_boot_time()       // /proc/1/start (pid1 start time) or time_now()

    recovered = replace.recover_state(boot_time)

    config = load_enabled_dir("/etc/zyginit/enabled.d")
    table = build_service_table(config)

    apply_recovered_state(table, recovered)    // <-- new step

    // Enter normal startup: tier-by-tier start_service
    // (services already in STATE_RUNNING are skipped)

    main_loop()
```

### 7.2 `apply_recovered_state` algorithm

For each `rs` in `recovered.services`:

```
idx = supervisor.find_service(table, rs.name)

if idx < 0:
    // Service was in state.toml but is no longer in enabled.d/.
    // Operator removed it dirty (manual symlink removal between old start
    // and replace). Don't kill — let the process exit on its own and the
    // kernel reap the contract. We just stop tracking it.
    contract.abandon_contract(rs.contract_id)
    log("replace: orphaned " + rs.name + " (no longer enabled)")
    continue

// Found in current table — patch in runtime fields.
rt = table.runtimes[idx]
rt.state = STATE_RUNNING
rt.contract_id = rs.contract_id
rt.pid = -1                     // unknown; not needed
rt.restart_count = rs.restart_count
rt.last_start_time = rs.last_start_time
rt.last_exit_code = rs.last_exit_code
table.runtimes[idx] = rt
table.contract_map.set(int_to_str(rs.contract_id), idx)

// Idempotency: did the contract go empty during the exec gap?
if contract.is_contract_empty(rs.contract_id):
    log("replace: " + rs.name + " contract empty post-recovery, applying restart policy")
    supervisor.handle_contract_event(table, rs.contract_id, -1)
    // existing logic resolves to STOPPED or scheduled-for-restart
```

### 7.3 Config divergence between old start and replace

Three cases the new zyginit must handle:

| Case | Detection | Action |
|---|---|---|
| Service in state.toml AND in current `enabled.d/` | `find_service` returns valid idx | Adopt: patch runtime fields, register in `contract_map`. Use **current** TOML for future supervision (so an edit takes effect on next restart). |
| Service in state.toml, NOT in current `enabled.d/` | `find_service` returns -1 | Abandon contract, log warning. Member processes continue running but unsupervised; kernel reaps the contract on their exit. |
| Service in current `enabled.d/`, NOT in state.toml | Not in recovered list | Treated as a freshly-enabled service. Tier-by-tier startup will `start_service` it normally on first event-loop tick. |

This means automation flows like `coral install some-service-package; zygctl replace` work correctly — the newly-installed service appears in `enabled.d/` and gets started by the new zyginit even though the old one never knew about it.

### 7.4 No `adopt_contract` calls

As established in §3, contract ownership survives execve at the kernel level. The new zyginit's bookkeeping is entirely in userspace: rebuild `contract_map`, populate `ServiceRuntime` fields. The `contract.adopt_contract` FFI remains in the codebase for potential future use (e.g., a non-PID-1 zyginit "supervisor mode" recovery flow) but is not exercised by this design.

## 8. Error handling

### 8.1 Pre-exec (in old zyginit)

Every pre-exec failure aborts the replace cleanly — old zyginit returns to its main loop with the flag cleared.

| Failure | Behavior |
|---|---|
| Service in transient state, `--wait` exhausted | Log `"replace blocked: <name>:<state>, ..."`. Clear flag. Return to main loop. |
| `state.toml.tmp` open / write / fsync fails | Log error with errno, unlink any partial `.tmp`. Return to main loop. |
| `rename(state.toml.tmp, state.toml)` fails | Log error. Return to main loop. Stale `state.toml` from prior aborted attempt has the wrong boot_time and is harmless. |
| `unlink("/var/run/zyginit.sock")` fails | Log warning, **proceed to exec**. New zyginit's `unix_listen` will overwrite the path. |
| `process.process_exec()` returns | Means kernel couldn't load `/sbin/init` (binary missing or corrupt). Log fatal. Old zyginit is in an unrecoverable state (state.toml written, socket unlinked). Fall through to the existing PID-1 infinite-sleep handling. Operator's recourse is reboot. Should never reach this in practice. |

### 8.2 Post-exec (in new zyginit)

Failures here are per-entry — one bad entry doesn't stop other recoveries.

| Failure | Behavior |
|---|---|
| `state.toml` missing | Treated as fresh boot. Not an error; no log. |
| `state.toml` parse error / corrupt | Log warning, treat as missing. Surviving contracts (if any) become orphans. |
| `state.toml.boot_time != current` | Log info, delete file, treat as missing. |
| Service in state.toml but not in current `enabled.d/` | Abandon contract, log warning. (See §7.3.) |
| `is_contract_empty(ctid)` post-recovery returns true | Synthesize a contract event; existing `handle_contract_event` applies restart policy. |
| `ct_status_read` returns error (contract gone, `ENOENT`) | Treat as empty / missing. Service starts fresh on first tick. |

After all entries are processed (success or otherwise), `state.toml` is deleted. This breaks panic-restart loops where the same bad state would otherwise be re-applied repeatedly.

### 8.3 Panic safety

`recover_state` and `apply_recovered_state` are written defensively. Any unexpected condition is logged and skipped — never panicked on. A bad state.toml entry must never prevent the new zyginit from completing startup.

## 9. Testing

### 9.1 Linux dev (no contract FFI)

The Linux contract stubs return -1 for all contract calls, so end-to-end re-adoption can't run on Linux. What we *can* unit-test:

- **State serialization round-trip** (`tests/test_replace.reef`): build a synthetic `ServiceTable` with services in known states, call `serialize_state`, read back with `recover_state`, assert all fields match. Cover empty table, all-RUNNING, mixed states (only RUNNING entries serialize), boot-id mismatch (ignored), corrupt TOML (ignored).
- **Pre-condition check**: factor the transient-state scan into an exported `check_replace_preconditions(table) -> string` (empty on OK, error message otherwise). Test transient states individually and combined.
- **Stitching logic**: unit-test `apply_recovered_state` covering the three cases of §7.3. Linux contract stubs let `is_contract_empty` always return false; we exercise the in-state-and-enabled and in-state-not-enabled branches.
- **Integration smoke** (`tests/integration/run_tests.sh`): start zyginit-as-supervisor (`ZYGINIT_CONFIG_DIR=/tmp/...`), run a few oneshot+daemon services, run `zygctl replace`. On Linux, contract-driven supervision is partially stubbed but the exec path itself runs. Assert the second zyginit instance starts, its log shows `"replace: stale state file"` or `"replace: <name> contract empty post-recovery"` per stub returns, and no crash.

### 9.2 Hammerhead (`hh-prototest`)

Real validation. Deploy via the iter 11+ procedure (`scp` source, `gcc helpers.c`, `reefc build`, `mv build/zyginit /sbin/init.new && mv /sbin/init.new /sbin/init`).

Test cases:

1. **Smoke** — multi-user up; `zygctl replace`; confirm:
    - Connection drops with the documented message.
    - Within ~1s, `zygctl status` works again.
    - All services still running, **same PIDs**, **same contract IDs**, restart counts preserved.
    - Uptimes preserved (continuous, not reset).
    - **The SSH session driving the test stays alive across the replace.** This is the highest-signal check.
    - `who -b` and `who -r` still report correctly.
2. **Transient-state refusal** — start a service with a slow `start.sh` (or watch for the WAITING window during a restart); run `zygctl replace` during the transient window; confirm refusal with the right error.
3. **`--wait=N` success** — same scenario with `--wait=10`; confirm replace proceeds once the service stabilizes.
4. **Dirty disable** — `rm /etc/zyginit/enabled.d/<svc>` (without `zygctl reload`); `zygctl replace`; confirm orphan path runs (contract abandoned, process keeps running, log message).
5. **Crash during exec gap** — `kill -9 <pid>` immediately before `zygctl replace`; confirm new zyginit's `is_contract_empty` post-recovery catches the empty contract and applies restart policy.
6. **Stale state.toml after real reboot** — write a state.toml file, do a real reboot, file persists in `/var/run/zyginit/`; confirm boot-id mismatch is detected, file deleted, fresh boot proceeds.
7. **Repeated replace** — `zygctl replace` 5 times in succession; confirm restart counts accumulate correctly (no resets), uptimes grow continuously, no state-file leakage.

### 9.3 Out of scope for testing

- Crash recovery (operator-driven only).
- Replace under heavy load (we accept some bundle events will land post-exec; the post-recovery status check covers it).
- Concurrent `replace` invocations (single-shot flag; second invocation between flag-set and exec is silently dropped — operator error).

## 10. Deferred / open questions

These are intentionally not in scope for v1, but flagged so we can revisit:

- **`zygctl replace --force`** — accept transient states by re-driving them (re-issue stop, re-arm restart timer, etc.). Adds significant recovery complexity. Defer until there's demonstrated automation demand.
- **SIGUSR2 fallback** — operator-side trigger if the socket is wedged. The reload path (SIGHUP) shows that signal-driven flag-setting works; we just don't yet need the additional reachable code path for replace. Defer.
- **Socket access tightening** — orthogonal to this design, but the socket is currently created with default permissions. It should be 0600 root-only. File as a separate hardening item.
- **Bundle fd inheritance** — clearing FD_CLOEXEC and passing the fd through exec would close the (already-handled) gap window completely. Adds complexity for an already-mitigated case. Defer indefinitely.
- **`/var/run/zyginit/` to tmpfs** — once `fs-minimal` is added back to the boot chain, `state.toml` automatically becomes ephemeral and the boot-id check becomes belt-and-suspenders. Tracked separately under §"Important Notes" in CLAUDE.md.
- **utmpx BOOT_TIME as sentinel (rejected)** — utmpx BOOT_TIME's `pututxline` updates rather than appends, so the new zyginit overwrites the original timestamp at startup, defeating the staleness check. `/proc/1/start` naturally survives execve but changes on real reboot. See §5.2 for full rationale.

## 11. Summary of decisions

| Decision | Choice | Rationale |
|---|---|---|
| Trigger model | Operator-driven only (live upgrade) | Crash recovery is a much harder problem; PID 1 dying is already catastrophic. |
| Trigger interface | `zygctl replace` (socket only) | Smallest blast radius; signal fallback defers cleanly. |
| Verb | `replace` | Operator-readable; covers upgrade + memory hygiene + state reset reasons; no overload with existing commands. |
| Exec target | Hard-wired to `/sbin/init` | Security: never accept attacker-controllable exec paths in PID-1. |
| Identity mapping | State file (single TOML) | Preserves runtime fields (`restart_count` especially); deterministic; matches deliberate-handover model. |
| Pre-condition check | Refuse on transient state by default; `--wait=N` for automation | Eliminates an entire class of recovery bugs; automation has a clean knob. |
| Bundle fd | Reopen, fix gap via post-recovery `is_contract_empty` | Idempotent, no fd-passing protocol needed. |
| Config divergence | Stitch state.toml against current `enabled.d/`, abandon orphans | Permissive without complexity; supports `coral install + replace` automation. |
| Adoption | **No `adopt_contract` call** | PID-1 in-place execve preserves kernel-level contract ownership; only userspace bookkeeping needs rebuilding. |
| State file location | `/var/run/zyginit/state.toml` | Existing runtime tree; boot-id check makes it safe across real reboots. |

## 12. Why keep this in the Hammerhead-userland package?

Hammerhead's primary upgrade workflow is BE-based: `pkg update` → new BE → `beadm activate` → reboot. In that workflow, `zygctl replace` is bypassed — the new zyginit comes up as a fresh PID 1 in the new BE. So why ship the feature?

**Linux port.** zyginit is written in Reef which compiles to native C; a Linux port is realistic. Linux package managers (`apt`, `yum`, `dnf`) operate on an in-place upgrade model where daemons need a way to reload their own binary without restarting the system. systemd's `systemctl daemon-reexec` exists for exactly this reason. If zyginit lands on Linux, `zygctl replace` becomes a primary feature.

**Live patching trajectory.** A system that supports live kernel patching (kpatch-style) has implicit cultural pressure to support live userland patching for critical daemons. zyginit being live-upgradeable is a natural fit for that posture if Hammerhead develops it.

**Mechanism reuse.** Several pieces (`contract.is_contract_empty`, `supervisor.adopt_runtime`, the state-file pattern in `utils/replace_probe`) have potential consumers beyond this feature — shutdown verification, future crash-recovery work, generic state-file testing patterns.

The feature stays; the trigger is documented as Hammerhead-secondary, Linux-primary.
# SMF Migration Handoff Document — Design

**Date:** 2026-05-04
**Status:** Approved (brainstorm complete); implementation plan to follow
**Scope:** A single Markdown document at `docs/SMF_MIGRATION.md` that hands off the remaining SMF-removal and zyginit-integration work from the zyginit project to the Hammerhead-project Claude (or Hammerhead human engineers). No tooling. No code.

## 1. Goal

Hand off the remaining SMF removal work to the Hammerhead team (or a Hammerhead-project Claude agent) with everything they need to:

1. Vendor zyginit source from this repo into Hammerhead's source tree as part of `hammerhead-userland`.
2. Wire zyginit into Hammerhead's master build, install paths, and packaging.
3. Migrate the existing 18 zyginit-converted services (currently in `services/hammerhead/`) into Hammerhead's source tree as the starting point.
4. Convert the remaining ~110 SMF manifests using the patterns documented in this work, the existing converted services as references, and project judgment about what Hammerhead actually ships.
5. Remove SMF infrastructure (`svc.startd`, `svc.configd`, master restarter, libscf consumers, manifest packaging) from `hammerhead-userland`.

The deliverable is **one Markdown document**. zyginit ships docs and patterns; Hammerhead does the OS-level execution.

## 2. Non-goals

- **No `smf-to-toml` conversion tool.** A Claude agent doing the conversion in-place can do both the mechanical XML-to-TOML translation AND the per-service judgment that a tool can't. Avoiding the tool also keeps zyginit free of a Python runtime dependency and aligns with the structural rule "DO NOT modify Hammerhead source code" — the Hammerhead Claude does that work in its own project.
- **No per-service detailed catalog with full recommendations.** zyginit doesn't know what Hammerhead ships; per-service decisions stay with the Hammerhead team. The doc provides a coarse one-line classification per manifest and lets the Hammerhead Claude finish each per-service decision with full local context.
- **No format reference duplication.** TOML field-by-field details stay in `man/zyginit.5`. The migration doc references it.
- **No build-system implementation.** The doc describes what the Hammerhead build needs to do; the Hammerhead Claude integrates it with the actual build conventions in their tree.
- **No Coral packaging for zyginit.** zyginit is part of `hammerhead-userland` (BSD-style base system), built into the OS by Hammerhead's master build.
- **No automated catalog maintenance.** The catalog is a snapshot of one Hammerhead manifest tree at one point in time; it is archival once the migration is complete.

## 3. Document structure

The single Markdown file at `docs/SMF_MIGRATION.md`, ~600-800 lines. Top-level sections:

```
1. Handoff Brief                       (~100 lines)
2. Decision Tree                       (~150 lines)
3. Worked Examples                     (~200 lines)
4. Anti-patterns & Gotchas             (~100 lines)
5. Integration with Hammerhead         (~150 lines)
6. Per-Category Guidance               (~100 lines)
7. Catalog Appendix                    (~200 lines, table format)
8. Format Reference Pointer            (~10 lines)
9. Glossary                            (~30 lines)
```

The doc is intended for both human engineers and AI agents working on the Hammerhead source tree. Format optimized for human readability; structured enough that a Claude agent can load it as context and act on it.

The file lives at `docs/SMF_MIGRATION.md` (top-level under `docs/`, alongside `DESIGN.md`). The spec for THIS doc lives at `docs/superpowers/specs/2026-05-04-smf-migration-doc-design.md`. The migration doc itself stays at the top level to signal "this is a real artifact for the Hammerhead team," not a planning artifact.

## 4. Section content

### 4.1 Handoff Brief

Sets up the context for the Hammerhead Claude. Includes:

- What zyginit has done so far (the iter 1-20 work; the contract-readoption feature; the 18 converted services in the boot chain on `hh-prototest`).
- What's left for the Hammerhead team to do (source vendoring, build integration, migrate the 18 existing TOMLs, convert the remaining ~110 manifests, remove SMF infrastructure).
- Coordination points: when to bounce a question back to the zyginit project (e.g., "the existing patterns don't fit this service" → file a zyginit issue; we extend the format/runtime if needed).
- Out-of-scope reminders ("DO NOT modify Hammerhead source from inside zyginit's tree" — this constraint is for the zyginit-project Claude, not the Hammerhead Claude; the Hammerhead Claude WILL modify Hammerhead source — that is its job).
- Done criteria for "SMF removal complete": Hammerhead boots and reaches multi-user without `svc.startd` / `svc.configd` ever being invoked; libscf-only consumers gone or stubbed; manifest infrastructure removed from packaging; existing zyginit-supervised services continue to work.

### 4.2 Decision Tree

The most consequential single piece of the doc — what the Hammerhead Claude leans on for every manifest. Three top-level exits per manifest:

```
Step 1: Should this service exist on Hammerhead at all?
   ├── No (deprecated, replaced)
   │     → DROP. Remove from package; do not write a TOML.
   ├── Yes, but as zports add-on, not base
   │     → DEFER. Out of scope for hammerhead-userland.
   └── Yes, ships in hammerhead-userland → continue to Step 2

Step 2: Is the service tightly coupled to SMF infrastructure
        (svc.configd / libscf / repository_door)?
   ├── Yes, fundamentally requires libscf at runtime
   │     → INVESTIGATE. Find a foreground/standalone mode, or
   │       coordinate with the daemon's upstream to add one.
   ├── Yes, but the daemon has a non-SMF mode flag (-d, -f, -D)
   │     → CONVERT (foreground-mode pattern). See Example 1.
   └── No, or coupling is incidental → continue to Step 3

Step 3: What runs the service today?
   ├── Direct daemon binary, no SMF method script
   │     → CONVERT (full-TOML pattern, simplest case)
   ├── /lib/svc/method/<name> shell script that does setup before exec
   │     ├── Trivial setup → INLINE into TOML's exec.start
   │     ├── Substantial setup (sources lib/svc/share/*.sh) → KEEP
   │       method script as exec.start. See Example 2.
   ├── Oneshot configuration step (mountall, swapadd, dumpadm)
   │     → CONVERT as oneshot service. See services/hammerhead/
   │       root-fs, swap, filesystem.
   └── inetd-managed service
         → DROP unless strong reason to keep. We don't run inetd.
```

Within "CONVERT," a field-by-field translation table maps SMF manifest XML elements to TOML fields:

| SMF concept | TOML field | Notes |
|---|---|---|
| `<service name='X'>` | `[service] name = "X"` | Strip category prefix |
| `<template>` short_description | `[service] description` | Plain string |
| `<service_bundle type='manifest'>` | `[service] type = "daemon\|oneshot\|transient"` | Map by behavior |
| `<exec_method type='start'>` | `[exec] start = "..."` | Replace method-script if Step 2 said foreground-mode |
| `<exec_method type='stop'>` | `[stop] method = "exec"` + `[exec] stop = "..."` | `:kill` in SMF maps to `[stop] method = "contract"` |
| `<dependency type='service'>` | `[dependencies] requires = [...]` | Translate FMRI to bare name; drop SMF-internal deps |
| `<dependency type='path'>` | `[dependencies] requires = ["filesystem"]` | Path deps mostly map to "filesystem is up" |
| `<property_group name='startd'>` `duration` | `[service] type` | transient vs daemon |
| `<property_group name='general'>` `enabled` | not in TOML | Operator decides via symlink in `enabled.d/` |
| Contract behavior | `[contract] param = [...]`, `fatal = [...]` | Defaults usually fine |
| Restart-on-error | `[restart] on = "always\|failure\|never"` | SMF's `ignore_error` maps to `on = "failure"` |

Anti-patterns explicitly called out:
- "Just convert it because it exists" — Step 1 audit is mandatory.
- "Wrap the method script verbatim" — many method scripts source `lib/svc/share/smf_include.sh` and call `smf_present`; wrapping reintroduces configd coupling.
- "Skip Step 2 because it's complicated" — getting Step 2 wrong was the entire iter 1-5 dead end.

### 4.3 Worked Examples

Three examples, each ~60-80 lines, structured identically.

**Example 1: foreground-mode conversion (canonical).** Subject: `dlmgmtd` (`/lib/svc/manifest/network/dlmgmt.xml`). Walks through: original SMF manifest, decision-tree walk (Step 1 keep, Step 2 yes-coupled-but-has-`-d`-flag), the resulting `services/hammerhead/dlmgmtd.toml`, why-we-made-each-choice (the existing comment block on dlmgmtd.toml is the educational artifact), and the iter 11-15 confirmation that `dladm`/`ipadm` work.

**Example 2: SMF method-script wrap.** Subject: `system/cron`. Original manifest with the `<exec_method type='start'>/lib/svc/method/svc-cron start</exec_method>` line. Decision-tree walk (Step 1 keep, Step 2 not coupled, Step 3 method-script trivial). Two valid TOMLs side-by-side: the inlined version vs the wrap version. Show that both are correct; explain when you'd pick which. Show the existing `services/hammerhead/cron.toml` as the production choice.

**Example 3: drop.** Subject: `system/svc/restarter`. The classic must-drop. Original manifest showing FMRI (`svc:/system/svc/restarter:default`) and exec method (`/lib/svc/bin/svc.startd`). Decision-tree walk: Step 1 NO — this IS SMF; zyginit replaces it. Document the cascade: most other manifests reference this in `<dependency>` blocks; when those services get converted, those dependencies are dropped (they were SMF-internal, not real ordering constraints). Other must-drop companions: `svc.configd`, the master restarter framework as a whole.

What's not in the worked examples (but pointed to from elsewhere in the doc):
- Oneshot conversions (root-fs, swap, filesystem) → already in `services/hammerhead/`; doc points there.
- Daemonize-handshake-needing services (syslogd, utmpd) → covered in Anti-patterns rather than as a worked example.
- Network-config-style → already in `services/hammerhead/network.toml`; pointer rather than walk-through.

### 4.4 Anti-patterns & Gotchas

A short section drawn from the iter notes already in memory. Each gotcha gets ~3-4 lines: symptom, cause, fix. Cross-reference into the iter notes (`pid1_boot_iter11_15.md`, etc.) so the Hammerhead Claude can pull more context.

Topics:
1. configd-coupled daemons silently degrade (iter 1-5, BSD pivot).
2. Daemonize handshake (iter 16, supervisor handles it but expect log noise).
3. Foreground-flag names vary (`dlmgmtd -d`, `ipmgmtd -f`, `sshd -D`, `syslogd -d`, `fmd -f`).
4. soconfig at boot — without it, `socket(AF_INET)` returns EAFNOSUPPORT.
5. `/var/run` not yet tmpfs in zyginit BE — files persist across reboots; follow-up to mount it.
6. utmpx record positioning — `pututxline` updates an existing matching record, doesn't append. Live-replace boot-id sentinel must come from `/proc/1/start`, not utmpx.
7. Don't `zfs set readonly=on` on the live root during shutdown (iter 19-20).
8. uadmin must not be called from PID 1; fork a child (iter 19-20).
9. `/etc/hosts` install bug — base ships only `localhost`, not actual hostname; causes 20-second login delays via DNS timeout. Flagged today as upstream Hammerhead bug.

### 4.5 Integration with Hammerhead build

Substantive section. zyginit is part of `hammerhead-userland` (BSD-style base system); Hammerhead's master build pulls and builds zyginit alongside other userland components. zyginit repo continues as upstream development repo; periodic syncs into Hammerhead.

Subsections:

1. **Source layout decision.** Recommended target path: `usr/src/cmd/init/` (BSD-tree convention; same place `cmd/init/init.c` lives in standard illumos). zygctl to `usr/src/cmd/zygctl/`. sysv-wrapper to `usr/src/cmd/sysv-wrapper/`. Sync mechanism (git submodule, source snapshot, fetch-and-extract) is the Hammerhead team's call.
2. **File-by-file mapping** (explicit table):
   ```
   zyginit-repo/src/*.reef                  → usr/src/cmd/init/src/
   zyginit-repo/src/helpers.c               → usr/src/cmd/init/src/
   zyginit-repo/src/contract_linux_stubs.c  → DROP (Hammerhead doesn't need Linux stubs)
   zyginit-repo/services/hammerhead/*       → usr/src/cmd/init/services/
   zyginit-repo/tools/zygctl/src/           → usr/src/cmd/zygctl/src/
   zyginit-repo/tools/zygctl/src/symlink_wrapper.c → same
   zyginit-repo/tools/sysv-wrapper/         → usr/src/cmd/sysv-wrapper/
   zyginit-repo/man/man8/*                  → usr/src/man/man8/
   ```
3. **Build invocation** — what the build needs to do:
   - `reefc build -l contract --obj <helpers.o>` → produces `/sbin/init`
   - `reefc build` for zygctl → produces `/sbin/zygctl`
   - `make` for sysv-wrapper → produces `/sbin/sysv-wrapper` plus argv[0] symlinks (`/sbin/halt`, `/sbin/reboot`, `/sbin/poweroff`, `/sbin/telinit`)
   - Install service TOMLs to `/etc/zyginit/`
   - Install start.sh / stop.sh scripts to `/etc/zyginit/<svc>/`
   - Install man pages
   - Drop `svc.startd`, `svc.configd`, master restarter from the build (the actual SMF removal step)
4. **Reef compiler dependency** — Hammerhead's build needs `reefc`. Either bootstrap from Reef repo or assume a pre-built reefc. Hammerhead team's call.
5. **First migration step (concrete deliverable):** copy the existing `services/hammerhead/*.toml` (and start.sh / stop.sh subdirs) from the zyginit repo into Hammerhead's source tree. This gets the iter 18-20 boot chain into Hammerhead's source as the starting point, before any of the ~110-manifest conversion work begins. Order:
   1. Vendor zyginit source into Hammerhead tree
   2. Wire up the build to produce `/sbin/init`
   3. Vendor the existing 18 TOMLs
   4. Validate: build a Hammerhead BE; boot; verify all 18 services come up (matches current hh-prototest behavior)
   5. THEN start the per-manifest conversion of the remaining manifests using the decision tree
6. **Upstream-sync workflow** — when zyginit ships new features, the Hammerhead team:
   - Re-fetches zyginit repo at a known tag/commit
   - Refreshes the vendored source under `usr/src/cmd/init/`
   - Resolves any local Hammerhead patches that conflict
   - Rebuilds and tests
   - Documents the sync point (commit hash) in Hammerhead's changelog

### 4.6 Per-Category Guidance

Walks the SMF manifest tree top-down, gives recommendations per category. The Hammerhead Claude reads this once for orientation, then drops into the catalog appendix for per-manifest decisions.

Structure mirrors the actual filesystem at `/lib/svc/manifest/`:
- `application/` — mostly Hammerhead-irrelevant; drop or defer to zports.
- `network/` — selective: keep DNS resolver consideration, NFS only if shipped, drop NIS/iSCSI/loadbalancer/SMB.
- `platform/` — keep amd64-specific bits; drop sun4u/sun4v (SPARC; Hammerhead is amd64-only).
- `system/` — keep core (devfs, filesystem, fmd-if-FMA-wanted, ipfilter); DROP ALL `system/svc/*` (this is SMF infrastructure itself).

Each category gets ~3-5 lines: what's there, default recommendation, per-category gotchas. Cross-reference into the catalog appendix for individual manifests.

### 4.7 Catalog Appendix

The 128 manifests as a sortable, scannable Markdown table. Format:

```
| Manifest path | Category | Classification | Note |
|---|---|---|---|
| /lib/svc/manifest/system/cron.xml | system | already-converted | services/hammerhead/cron.toml |
| /lib/svc/manifest/system/svc/restarter.xml | system | drop | This IS svc.startd; we replace it |
| /lib/svc/manifest/system/fm/fmd.xml | system | foreground | fmd -f flag; needs verification |
...
```

Five classifications:
- `already-converted` — TOML exists in current `services/hammerhead/`; just migrate to Hammerhead source tree.
- `drop` — service should not be in Hammerhead at all.
- `foreground` — convert via foreground-mode pattern (decision tree Step 2).
- `method-wrap` — keep the SMF method script as exec.start (decision tree Step 3).
- `needs-investigation` — depends on a Hammerhead-team policy decision.

The "Note" column carries the why — for `already-converted` it's a path pointer; for `drop` a one-line reason; for `foreground` the candidate flag; for `method-wrap` the method script path; for `needs-investigation` the open question.

**Generation effort:** populating the catalog is the substantive zyginit-side work — open each XML, fill in classification + note. Most entries are obvious; a handful need real thought. Output is a static Markdown table.

**Maintenance posture:** the catalog is a snapshot of one Hammerhead manifest tree. As Hammerhead evolves upstream, the catalog drifts. The doc explicitly notes this is a starting-point snapshot, not a living index.

### 4.8 Format Reference Pointer

Single short section: "For TOML field-by-field reference, see `man/zyginit.5`. The format reference is authoritative there; this doc covers patterns and decisions, not syntax."

### 4.9 Glossary

Five-to-ten-line definitions of SMF concepts that show up in the doc but may be unfamiliar to non-illumos hands or AI agents whose training data is light on Solaris:
- FMRI, Manifest, Method, Profile, Repository, Restarter, Contract, libscf, libcontract, BE / Boot Environment, soconfig.

## 5. Audience and writing style

The doc is written for both human engineers and AI agents working on the Hammerhead source tree. Format:

- Markdown, GitHub-flavored, no emojis.
- Headings to two levels (`##`, `###`) for navigation; deeper structure via lists.
- Code blocks (```` ``` ````) for TOML, XML, and shell snippets.
- Cross-references to other files use repo-relative paths (e.g., `services/hammerhead/dlmgmtd.toml`, `man/zyginit.5`, `pid1_boot_iter11_15.md`).
- Each major section ends with a "see also" line pointing to related sections.
- The catalog appendix uses Markdown tables (not flat lists).
- Each subsection starts with a one-sentence purpose statement so readers can skim.

Optimizing for human readability also serves AI agents well; no separate "agent-friendly" tracks.

## 6. Implementation effort

Approximate: 4-6 hours of focused work for a Claude agent to write this doc end-to-end:

- Sections 1, 2, 4, 5, 6, 8, 9 — straightforward writeup of decisions already made; ~2-3 hours.
- Section 3 (worked examples) — requires walking through the actual XML manifests for dlmgmtd, cron, and svc.startd; ~1 hour.
- Section 7 (catalog) — open each of 128 manifests on hh-prototest, classify, fill in notes; ~2-3 hours.

Spec self-review after writing: ~30 minutes.

## 7. Decisions summary

| Decision | Choice | Rationale |
|---|---|---|
| Tooling | None (no `smf-to-toml` translator) | Claude does both mechanical and judgment work in one pass; tool would duplicate the mechanical part and add a Python dependency. |
| Format | Single Markdown doc at `docs/SMF_MIGRATION.md` | Simpler than two coupled docs; one source of truth for the handoff. |
| Depth | Middle ground (~5-7 pages prose + catalog appendix) | Decision tree + 2-3 worked examples + anti-patterns + per-category guidance. Format reference stays in `man/zyginit.5`. |
| Catalog | Coarse classification per manifest (5 classes) | One-line annotations for all 128; per-service detailed decisions stay with Hammerhead team. |
| Tool language | N/A (no tool) | — |
| Integration model | zyginit vendored into `hammerhead-userland` (OpenBSD-style base) | Per user direction; not Coral-packaged; zyginit repo continues as upstream. |
| Audience | Both human engineers and AI agents | Single doc serves both; readability optimized for humans. |
# Versioning and Release Tarball — Design

**Date:** 2026-05-05
**Status:** Approved (brainstorm complete); implementation plan to follow
**Scope:** Establish a single canonical version for the zyginit suite (zyginit + zygctl + sysv-wrapper), wire `--version` flags into all three binaries, and add scripts to bump the version and produce a source release tarball for vendoring into Hammerhead.

## 1. Goal

Hammerhead consumes zyginit as a **vendored source drop** into `hammerhead-userland` (per `docs/SMF_MIGRATION.md`). To make that drop reproducible and auditable, zyginit needs:

1. A single canonical version, tracked in source.
2. A scripted bump that updates every place the version appears, in lock-step.
3. A scripted release that produces `releases/zyginit-<version>-source.tar.xz` plus a `.sha256` companion.
4. A runtime `--version` flag on every shipped binary, so an installed Hammerhead system can answer "which zyginit am I running?".

This work intentionally mirrors Coral's `scripts/make-release.sh` pattern (single tarball, sha256, `--transform`-prefixed paths) — the Hammerhead team gets a consistent shape across Zygaena projects.

## 2. Non-goals

- **No CI/CD release automation.** Bump and release are run by hand by a maintainer; no GitHub/Hg-server hooks, no signing, no upload step.
- **No reproducible-build flags** (`--mtime`, `--owner=0`, `--sort=name`). Coral doesn't bother and Hammerhead's packaging step is what produces the OS-level reproducible artifact. Adding these is a trivial follow-up if needed.
- **No multi-tarball releases.** The whole suite (zyginit + zygctl + sysv-wrapper) ships and versions together, in one tarball.
- **No `CHANGELOG.md` integration.** The bump script doesn't touch a changelog. (We can add this later; there is no changelog file today to integrate with.)
- **No GPG signing.** Hammerhead handles signing at the OS package layer.

## 3. Versioning policy

Semver: `MAJOR.MINOR.PATCH`.

| Bump | Reason |
|---|---|
| MAJOR | Incompatible socket protocol change, incompatible service-definition (TOML) schema change, removal of a published `zygctl` subcommand |
| MINOR | Backward-compatible additions: new service-definition fields with defaults, new `zygctl` subcommands, new runlevel features |
| PATCH | Bug fixes only; no API or protocol changes |

While zyginit is pre-1.0, breaking changes may land in MINOR per semver convention. Once 1.0 ships (target: when SMF removal from Hammerhead is complete and the suite has been running unmodified for one release cycle), strict semver applies.

## 4. Source of truth

The root `reef.toml` `[package].version` is **canonical**. Every other location is **derived** and regenerated by the bump script.

Today's drift inventory (rev 82, version `0.1.0`) — the bump script must keep these all consistent:

| # | Location | Form |
|---|---|---|
| 1 | `reef.toml` (root) | `version = "0.1.0"` (canonical) |
| 2 | `tools/zygctl/reef.toml` | `version = "0.1.0"` |
| 3 | `src/version.reef` (new, generated) | `pub fn VERSION(): string` returning `"0.1.0"` |
| 4 | `tools/zygctl/src/version.reef` (new, generated) | same |
| 5 | `tools/sysv-wrapper/version.h` (new, generated) | `#define ZYGINIT_VERSION "0.1.0"` |

Generated files (`version.reef` × 2 and `version.h`) **are committed** to the repository so a tarball recipient can build without rerunning the bump script. They carry a "Generated by scripts/bump-version.sh — do not edit by hand" comment.

## 5. `scripts/bump-version.sh`

**Usage:** `scripts/bump-version.sh <new-version>`

**Behavior:**

1. Validates `<new-version>` matches `^[0-9]+\.[0-9]+\.[0-9]+$`. Refuses if not.
2. Reads current version from root `reef.toml`. Refuses if `<new-version>` equals current.
3. Rewrites all five locations listed in §4.
4. Prints a summary diff (`hg diff --stat`) and a suggested commit command:
   ```
   $ hg ci -m 'Bump version to <new-version>'
   ```
5. Does **not** auto-commit. The maintainer reviews and commits by hand.

**Generated file templates:**

`src/version.reef` (and identical-content `tools/zygctl/src/version.reef`):
```reef
/* SRCHEADER... */

module version

// Generated by scripts/bump-version.sh — do not edit by hand.
pub fn VERSION(): string
    return "0.1.0"
end VERSION

end module
```

`tools/sysv-wrapper/version.h`:
```c
/* SRCHEADER... */
/* Generated by scripts/bump-version.sh — do not edit by hand. */
#ifndef ZYGINIT_VERSION_H
#define ZYGINIT_VERSION_H
#define ZYGINIT_VERSION "0.1.0"
#endif
```

Both templates use the project's standard `SRCHEADER.txt` header. The bump script fills in `${project}` from each subproject's own `reef.toml` `[package].name` (i.e., `zyginit` for `src/version.reef`, `zygctl` for `tools/zygctl/src/version.reef`), `${file.name}` from the filename, and `${file.description}` with a fixed string ("Generated version constant").

## 6. `scripts/make-release.sh`

**Usage:** `scripts/make-release.sh [version-override]`

**Behavior** (mirrors Coral's `make-release.sh`):

1. Reads version from root `reef.toml`, or uses `[version-override]` if provided.
2. Creates `releases/` if missing.
3. Produces `releases/zyginit-<version>-source.tar.xz` via `tar --transform "s,^,zyginit-<version>-source/," -cJf ...`.
4. Generates `releases/zyginit-<version>-source.tar.xz.sha256`.
5. Prints final paths and the sha256.

**Tarball contents** (top-level paths, `--transform`-prefixed into `zyginit-<version>-source/`):

| Include | Why |
|---|---|
| `reef.toml` | Build manifest (carries the canonical version) |
| `README.md` | Project orientation |
| `ROADMAP.md` | Forward-looking roadmap |
| `CLAUDE.md` | Project context (useful even outside Claude — accurate in-tree docs) |
| `SRCHEADER.txt` | Source-header template (referenced by all source files) |
| `src/` | Main daemon Reef source |
| `docs/` | Architecture docs (`DESIGN.md`, `SMF_MIGRATION.md`, etc.) |
| `tests/` | Unit + integration tests |
| `services/` | Example + Hammerhead service TOMLs (the v2 BSD-pivot tree) |
| `tools/` | `zygctl/`, `sysv-wrapper/` (subprojects) |
| `utils/` | `contract_probe` and any other utility tools |
| `scripts/` | `bump-version.sh`, `make-release.sh`, `install-to-be.sh` |

**Tarball excludes:**

| Exclude | Why |
|---|---|
| `build/` (root and any `tools/*/build/`) | Build artifacts |
| `releases/` | Output of this very script — don't ship past tarballs |
| `.hg/`, `.hgignore`, `.hgtags` | VCS metadata |
| `*.o`, `*.a` | Compiled object files |
| `*.swp` | Editor cruft |
| `resume/` | Local scratch / resume notes (per user instruction) |
| `ss/` | Local scratch (per user instruction) |
| `stub/` | Old Rust-like design archeology, kept for reference only (per `CLAUDE.md`) |

`tar`'s `--exclude` patterns are passed in for each item. The exclusion of `tools/*/build/` is critical — the global `build/` exclude only covers the repo-root build dir.

## 7. Code changes (one-time)

These ride along with the introduction of the bump/release scripts:

| File | Change |
|---|---|
| `src/main.reef:67-69` | Drop the inline `fn VERSION(): string` definition; `import version` and use `version.VERSION()` |
| `src/socket.reef:248` | Replace literal `"zyginit 0.1.0\n"` with `"zyginit " + version.VERSION() + "\n"` |
| `tools/zygctl/src/main.reef:54-57` | Replace literal `"zygctl 0.1.0"` with `"zygctl " + version.VERSION()` |
| `tools/zygctl/src/main.reef` | Add `import version` |
| `tools/sysv-wrapper/wrapper.c` | Add `--version` / `-V` handling: prints `"<argv[0]-basename> <ZYGINIT_VERSION>\n"` and exits 0. `#include "version.h"`. |
| `tools/sysv-wrapper/Makefile` | Add `version.h` to the dependency list of `wrapper.o` |

The argv[0]-basename trick in sysv-wrapper means `halt --version` prints `halt 0.1.0`, `reboot --version` prints `reboot 0.1.0`, etc. — consistent with how each personality identifies itself in normal output.

## 8. Output format

A single line, `<binary> <version>`, exit 0. Matches Coral and the GNU/BSD common case:

```
$ zyginit --version
zyginit 0.1.0
$ zygctl --version
zygctl 0.1.0
$ halt --version
halt 0.1.0
```

`zygctl version` (no dashes — already a subcommand) continues to work and prints the same line. Both `zygctl --version` and `zygctl version` are **strictly local** — they print zygctl's compiled-in version and never round-trip the socket. This is the standard Unix convention and keeps the answer trustworthy when the daemon is wedged.

Querying the running daemon's version (useful during a partial upgrade) is an existing socket command (`socket.reef:247`) but is currently unreachable from zygctl. Wiring up a separate `zygctl daemon-version` subcommand to surface it is **out of scope** for this design — see §10.

## 9. End-to-end workflow

Maintainer cuts release `0.2.0`:

```
$ scripts/bump-version.sh 0.2.0
zyginit: bumping 0.1.0 -> 0.2.0
  rewriting reef.toml
  rewriting tools/zygctl/reef.toml
  regenerating src/version.reef
  regenerating tools/zygctl/src/version.reef
  regenerating tools/sysv-wrapper/version.h
done. review with `hg diff` and commit:
  hg ci -m 'Bump version to 0.2.0'

$ hg diff --stat
 reef.toml                          | 2 +-
 tools/zygctl/reef.toml             | 2 +-
 src/version.reef                   | 2 +-
 tools/zygctl/src/version.reef      | 2 +-
 tools/sysv-wrapper/version.h       | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

$ hg ci -m 'Bump version to 0.2.0'

$ scripts/make-release.sh
Creating release: zyginit-0.2.0-source
Created: releases/zyginit-0.2.0-source.tar.xz
-rw-r--r-- 1 ctusa ctusa 1234567 May  5 15:30 releases/zyginit-0.2.0-source.tar.xz
Checksum: releases/zyginit-0.2.0-source.tar.xz.sha256
abc123...  releases/zyginit-0.2.0-source.tar.xz
```

Hammerhead then consumes the tarball + sha256 into `hammerhead-userland`, per the integration steps in `docs/SMF_MIGRATION.md`.

## 10. Open questions / future work

- **`scripts/install-to-be.sh`** already exists. Out of scope for this design — it's an in-place dev install, not a release artifact path.
- **Reproducible tarballs** (`--mtime`, `--sort=name`, `--owner=0`, `--group=0`). Add when the Hammerhead build needs byte-identical tarballs across maintainer machines.
- **`CHANGELOG.md`** — add when there's enough release history to warrant one. The first one or two release notes can live in commit messages.
- **GPG signing** — Hammerhead handles this at the OS package layer; no zyginit-side signing planned.
- **Pre-release versions** (e.g., `0.2.0-rc1`). Not supported by the regex in §5. Add when needed.
- **`zygctl daemon-version` subcommand.** The socket already exposes a `version` command (`socket.reef:247`) that returns the running daemon's version, but no client surfaces it. Add a `zygctl daemon-version` (or similar) subcommand to make partial-upgrade diagnosis easy. Until then, `socket.reef`'s `version` handler stays as accessible-but-unused (an `echo version | nc -U /var/run/zyginit.sock` still works).
# zyginit Visual Pass — Design

**Date:** 2026-05-12
**Status:** Approved (brainstorm complete); implementation plan to follow
**Scope:** Unified visual identity across the boot console, `zygctl`, and shutdown. New `src/ui.reef` module owns palette, glyphs, sigil, TTY/TERM detection, ANSI rendering, rolling tape, progress bar, and spinner. Existing `println` lifecycle sites in `main.reef` / `supervisor.reef` are routed through it. Graceful fallback to ASCII glyphs on dumb terminals and to plain line-by-line output when non-TTY, `NO_COLOR`, or supervisor mode.

## 1. Goals

1. **Unified identity.** Same `[Z]` sigil, six-color palette, and four-state glyph set on every visible surface: boot console, shutdown console, `zygctl status`.
2. **Restrained brand.** No banner ASCII art, no friendly tier names, no animations beyond a single spinner glyph. The boot screen feels structured and tidy, not theatrical.
3. **Make tiers visible.** zyginit is the only init that exposes dependency tiers as a first-class concept. The boot UI uses them as the structural backbone of progress reporting.
4. **Graceful degrade.** Truecolor on Hammerhead framebuffer, 16-color baseline on serial consoles, ASCII glyphs on dumb terminals, plain machine-parseable lines when non-TTY or `NO_COLOR`.
5. **Hammerhead-tem-safe.** No animation faster than the main event loop wake-up cadence, no terminal queries (`CSI 6n` etc.), no concurrent writers to `/dev/console`. zyginit owns the screen.

## 2. Non-goals

- **No splash screen / Plymouth-equivalent.** Tem is polled I/O — text-mode only.
- **No friendly tier names.** Tiers are displayed as bare `tier N`. Adding a `tier_name` TOML field was considered and rejected.
- **No mouse, no Unicode line-drawing reliance.** Box-drawing chars (`──` divider) are the only Unicode used in the frame; everything else has an ASCII fallback.
- **No new process or binary.** Rendering happens in-process inside zyginit; `zygctl` prints the daemon's pre-rendered response verbatim.
- **No restructure of the zyginit ↔ zygctl module boundary.** They stay separate Reef projects with separate `reef.toml`.
- **No `zygctl list` banner.** `list` is the catalog command, used in scripts more than `status` — stays minimal.
- **No animation under heavy load.** Spinner ticks are event-driven (one per main-loop wake-up), not timer-based.

## 3. Architecture

### 3.1 New module: `src/ui.reef`

Single new file. Owns:

- Palette + truecolor / 16-color SGR selection
- Glyph set + ASCII fallback
- TTY / TERM / `NO_COLOR` detection
- ANSI cursor positioning helpers
- Header + rolling tape + progress bar state
- `[Z]` sigil
- Spinner frame index

### 3.2 Public surface (Reef pseudo-signatures)

```
// Lifecycle
proc ui_init(rich_mode: int)
proc ui_boot_start(num_svc: int, num_tiers: int, runlevel: string)
proc ui_tier_start(tier: int)
proc ui_tier_done(tier: int)
proc ui_event_starting(name: string)
proc ui_event_started(name: string, dur_ms: int)
proc ui_event_failed(name: string, exit_code: int, dur_ms: int)
proc ui_event_stopping(name: string)
proc ui_event_stopped(name: string, dur_ms: int)
proc ui_boot_complete(stats: BootStats)
proc ui_shutdown_start(reason: string)
proc ui_shutdown_complete(reason: string, elapsed_ms: int)

// Spinner
proc ui_tick()                          // advance spinner frame, redraw active rows
fn   ui_spinner_frame(reverse: bool): string

// On-demand rendering (for zygctl status/list)
fn   ui_render_status(table: ServiceTable, want_banner: int, plain: int): string
fn   ui_render_list(table: ServiceTable): string
```

### 3.3 Call-site changes

- **`src/main.reef`** — invoke `ui_init` immediately after `setup_pid1_console`. Wrap dep-graph load with `ui_boot_start`. Wrap each tier loop with `ui_tier_start` / `ui_tier_done`. Call `ui_boot_complete` after all tiers. Add `ui_tick` to the main poll loop. Bracket shutdown with `ui_shutdown_start` / `ui_shutdown_complete`.
- **`src/supervisor.reef`** — replace ~8 lifecycle `println` calls (started, stopped, failed, stop-timeout, scheduled-for-restart, entered-maintenance) with `ui_event_*` calls. Warning/debug prints stay as-is.
- **`src/socket.reef`** — `cmd_status` and `cmd_list` delegate to `ui_render_status` / `ui_render_list`. New `PLAIN` modifier on the wire forces banner-off + escape-free output.
- **`tools/zygctl/src/main.reef`** — pre-flight: detect `isatty(STDOUT_FILENO)` + `NO_COLOR` + `TERM`. Send `STATUS PLAIN` or `STATUS` to the daemon accordingly. Print the response verbatim.

### 3.4 What stays unchanged

- Service stdout/stderr capture to `/var/log/zyginit/<name>.log` (per-service log files) is unchanged.
- Existing socket protocol commands keep their text shape; `PLAIN` is an additive modifier.
- `zygctl list` keeps its existing minimal one-line-per-service shape.
- The supervisor state machine (8 states), restart policies, contract handling — none of it changes.

## 4. Visual elements

### 4.1 Palette

Six tokens. Truecolor on `TERM=sun-color` or `*-256color`; 16-color baseline otherwise.

| Token | Truecolor | 16-color fallback | Used for |
|-------|-----------|-------------------|----------|
| `c.frame` | `#6E7B8B` steel grey | `white` | header text, column labels |
| `c.accent` | `#006A6F` teal | `cyan` | `[Z]` sigil, dividers, "elapsed", progress-bar filled |
| `c.ok` | `#2E8B57` sea green | `green` | `●` online / running |
| `c.warn` | `#FFBF00` amber | `yellow` | `◉` / spinner — starting / stopping |
| `c.fail` | `#C8201F` signal red | `red` | `✕` failed / maintenance |
| `c.mute` | default fg + `\e[2m` (dim attr) | `dim` | `·` pending / stopped, progress-bar empty |

### 4.2 Glyphs

| State | Unicode | ASCII (TERM=dumb or `ZYGINIT_ASCII=1`) | Color |
|-------|---------|----------------------------------------|-------|
| online / running | `●` | `#` | `c.ok` |
| starting | spinner (see 4.3) | spinner | `c.warn` |
| stopping | spinner reversed | spinner reversed | `c.warn` |
| failed / maintenance | `✕` | `X` | `c.fail` |
| pending / stopped | `·` | `.` | `c.mute` |

Box-drawing divider: `──────`. Same character in rich and ASCII modes; tem renders it from the sun-color font.

### 4.3 Spinner

Frame set: `[ "/", "-", "\\", "|" ]` (same in rich and ASCII modes).

- **Starting state:** frames advance forward — `/ → - → \ → |` — index `g_tick mod 4`.
- **Stopping state:** frames advance in reverse — `| → \ → - → /` — index `(N_FRAMES - 1) - (g_tick mod 4)`.
- **`g_tick`** is incremented by `ui_tick()`, which is called once per main-loop wake-up. No separate timer thread. Spinner advances on any signal, contract event, socket activity, or poll timeout (200ms boot-mode default).
- Services that transition `STARTING → RUNNING` in under one tick never visibly spin; their row appears with `●` directly. No special case.
- Spinner is colored `c.warn`.

### 4.4 Sigil

`[Z]` rendered in `c.accent`, prefixed to every banner (boot, shutdown, `zygctl status`). No other sigil variants.

## 5. Layouts

All layouts assume 80×24 minimum. Wider terminals leave whitespace; narrower terminals trigger truncation (see §7.2).

### 5.1 Boot rolling tape — during boot

Total: 18 rows. 4 header + 12 tape + 2 progress.

```
  [Z] zyginit 0.1.2 · multi-user                       elapsed  6.2s
  17 services · tier 5 · 12 done · 1 failed
  failed: network                                       exit=1
  ──────────────────────────────────────────────────────────────
   0.49  ●  swap
   1.04  ●  filesystem
   1.08  ●  identity
   1.36  ●  sysconfig
   1.55  ●  dlmgmtd
   1.78  ●  ipmgmtd
   2.10  /  network         (starting)
   ...
  ──────────────────────────────────────────────────────────────
  █████████████░░░░░░░░░░░░░░░░░░░░░░░  12/17  70%
```

Header (rows 1–3) repainted on tier transition and on any change to fail count. The `failed:` line shows up to one currently-failed service; on a second failure it becomes `failed: 2 services` and the user reads `zygctl status` for detail. If zero failures, the line shows `failed: none`.

Tape (rows 5–16) is a 12-line rolling window. New event lines append at the bottom; oldest scrolls off the top. Each line is `<elapsed-since-boot>  <glyph>  <name>  (<state-note>)` where state-note is `(starting)` / `(stopping)` for in-progress services and absent for terminal states.

Progress bar (row 18):
- 36-cell width
- Filled `█` in `c.accent`; empty `░` in `c.mute`
- Counter: `<online + failed> / <total>` — failures DO count toward the bar's "done" tally so it can reach 100%. The header tracks failure visibility separately.
- Percent: `floor(done / total * 100)`
- ASCII fallback: `[####################          ]  12/17  70%` — 30-cell width inside brackets

### 5.2 Boot final card — boot complete → login

When the last tier completes, header and tape are erased and the final card is painted:

```
  [Z] zyginit 0.1.2 · multi-user                        boot 8.3s
  17 services — 16 online, 1 failed

  failed: network                                       exit=1
      → zygctl log network    to see why
  ──────────────────────────────────────────────────────────────
  slowest:  network 5.02s  filesystem 0.55s  sshd 0.37s
```

- "boot 8.3s" replaces "elapsed 6.2s" in the header.
- Up to 3 slowest services listed on the bottom line.
- Progress bar is removed (its information is now in the second line).
- Card stays visible until `console-login`'s ttymon paints `Login:` underneath it. No timer, no clear.
- If there are zero failures, the `failed:` and hint lines are replaced with a blank line + `all services online`.

### 5.3 Shutdown mirror — during shutdown

Mirrors §5.1 with shape adjustments:

```
  [Z] zyginit 0.1.2 · stopping for reboot              elapsed 1.4s
  17 services · tier 7 · 13 down · 0 failed
  ──────────────────────────────────────────────────────────────
   0.04  ·  sshd
   0.16  ·  console-login
   0.31  ·  cron
   0.48  |  syslogd     (stopping)
   ...
  ──────────────────────────────────────────────────────────────
  ░░░░░░░░░░░░░░░░░░░░██████████████████  13/17 down  76%
```

- Header subtitle uses `<N> down` instead of `<N> done`.
- Failures during shutdown are services that returned non-zero from their stop method or hit the stop-timeout → SIGKILL escalation; still surfaced in the `failed:` line.
- Reverse spinner: stopping services render `| \ - /`.
- Progress bar fills from right to left, signaling "winding down". Filled cells are still `c.accent`; the bar's "done" count is services that have reached the `STOPPED` state (success or kill).

### 5.4 Shutdown final card

```
  [Z] zyginit 0.1.2 · halt complete                    halt 2.1s
  17 services stopped cleanly
  ──────────────────────────────────────────────────────────────
  invoking uadmin(A_SHUTDOWN, AD_BOOT)
```

- Variant for non-clean: `17 services stopped (2 force-killed)`.
- Subtitle uses `halt` / `reboot` / `poweroff` depending on reason.
- Card stays visible until the forked uadmin child causes the kernel to reset the screen.

### 5.5 `zygctl status` — banner + table

```
  [Z] zyginit 0.1.2 · multi-user · 17 services · 16 online, 1 failed
  ──────────────────────────────────────────────────────────────
  SERVICE        STATE       PID    CTID   UPTIME    NOTES
  root-fs        ● online                            (oneshot)
  crypto         ● online                            (oneshot)
  dlmgmtd        ● running   1234   42     2h15m
  network        ✕ failed                            exit=1 restarts=3
  sshd           ● running   1280   51     2h15m
```

- Banner: same shape as boot/shutdown, no "elapsed" since this is a snapshot.
- Single-service form (`zygctl status sshd`) returns only the table row — no banner.
- Plain mode: no banner, no escapes, columns space-aligned, single trailing newline per row.
- Column widths: `SERVICE` is dynamic (max name length, clamped 8–24); `STATE` is fixed 10 chars including glyph; `PID` 6, `CTID` 6, `UPTIME` 9, `NOTES` is rest-of-line.

### 5.6 `zygctl list` — unchanged shape

Stays minimal:

```
$ zygctl list
root-fs (oneshot)
crypto (oneshot)
dlmgmtd (daemon)
network (oneshot)
sshd (daemon)
...
```

Reason: `list` is used in scripts more than `status`. Adding a banner adds noise. Color is applied to the type chip only when isatty.

## 6. Render policy

Decided once at startup by `ui_init()` via `detect_rich_mode()`. Stored in module state. No mid-run mode flips.

```
detect_rich_mode() -> int:
    if env("ZYGINIT_NO_UI") set    → MODE_PLAIN
    if env("NO_COLOR") set         → MODE_PLAIN          (https://no-color.org)
    if getpid() != 1               → MODE_PLAIN          (supervisor mode)
    if !isatty(STDOUT_FILENO)      → MODE_PLAIN
    let term = env("TERM")
    if term in {"", "dumb"}        → MODE_PLAIN
    if env("ZYGINIT_ASCII") set    → MODE_RICH_ASCII     (glyphs → /-\| ASCII)
    if term contains "256color"
       or term == "sun-color"      → MODE_RICH_TRUE      (truecolor SGR)
    else                           → MODE_RICH_16        (16-color SGR baseline)
```

| Mode | Header & tape | Color | Glyphs | Spinner | Progress bar |
|------|---------------|-------|--------|---------|--------------|
| `MODE_PLAIN` | Plain lines | none | text labels | none | none |
| `MODE_RICH_ASCII` | Drawn | 16-color | ASCII (`#`, `o`/spinner, `X`, `.`) | yes | bracket form |
| `MODE_RICH_16` | Drawn | 16-color SGR | Unicode (`●`, `◉`/spinner, `✕`, `·`) | yes | block form |
| `MODE_RICH_TRUE` | Drawn | 24-bit SGR | Unicode (`●`, `◉`/spinner, `✕`, `·`) | yes | block form |

zygctl runs its own `detect_rich_mode()` against its stdout. When client detects `MODE_PLAIN`, it sends `STATUS PLAIN` / `LIST PLAIN` to the daemon; the daemon renders banner-free, escape-free output for that one response.

Plain mode line shape (machine-parseable):

```
<elapsed-s>  <level>  <event>     <name>     [k=v ...]
       6.21  info     started     crypto     dur_ms=120
       7.14  info     starting    network
       7.20  err      failed      network    exit=1 dur_ms=4023
      11.42  info     stopping    sshd
      11.55  info     stopped     sshd       dur_ms=130
```

Level mapping: `started` / `starting` / `stopping` / `stopped` → `info`; `failed` → `err`; supervisor warnings (stop-timeout, entered-maintenance) → `warn`. Used by integration tests and any external log scraper. Same content as the rich-mode tape, no escapes.

## 7. Error handling

### 7.1 Write failures

If a `write(2)` to `/dev/console` returns an error, `ui.reef` sets a sticky `g_ui_failed` flag and downgrades to `MODE_PLAIN` for the rest of the session. PID 1 must not crash because the screen got weird.

### 7.2 Terminal width

Width is assumed 80 cols. No `CSI 6n` queries (fragile on `/dev/console`). Layouts fit 80×24 with margin.

If `COLUMNS` env var is set (zygctl client, set by the user's shell), zygctl-side rendering uses it; the daemon doesn't see it. The daemon renders for 80 cols always.

Service names longer than the `SERVICE` column width are truncated with `…` (Unicode) or `..` (ASCII).

### 7.3 Concurrent writers

Per Hammerhead's tem note ("/dev/console write path is serialized") — zyginit owns the screen during boot and shutdown. Per-service stdout/stderr already redirect to per-service log files in the supervisor's child-setup; that path is unchanged. Any rogue code that writes directly to `/dev/console` would interleave — same as today.

### 7.4 Service starts faster than one tick

The row appears with `●` directly. No spinner ever shown for that service. Correct behavior; no special case needed.

### 7.5 Boot fails before `ui_init`

If `setup_pid1_console` or kernel handover fails, `ui_init` never runs. All output falls back to whatever the pre-existing `println` path does, which is the current shape — flat lines to `/dev/console`. No regression.

## 8. Data flow

### 8.1 Boot

```
main.reef:
  setup_pid1_console()
  ui_init(detect_rich_mode())
  load services + build depgraph
  ui_boot_start(num_svc, num_tiers, runlevel)
  for each tier:
      ui_tier_start(tier)
      for each service in tier:
          supervisor.start_service(...)
              → fork/exec, set state=STARTING
              → ui_event_starting(name)        // appends spinner row to tape
      while tier has services in STARTING:
          poll() returns (signal/contract/socket/timeout 200ms)
          ui_tick()                             // advance spinner, redraw spinner rows
          handle contract events:
              service became RUNNING → ui_event_started(name, dur_ms)
              service exited 0 (oneshot) → ui_event_started(name, dur_ms)
              service failed → ui_event_failed(name, exit, dur_ms)
      ui_tier_done(tier)                        // header repaint
  ui_boot_complete(stats)                       // header + tape erased, final card painted
  enter steady-state event loop
```

Steady-state: no UI updates. Console keeps the final card frozen until `console-login`'s ttymon writes underneath it.

### 8.2 Shutdown (symmetric)

```
main.reef on SIGTERM / socket shutdown command:
  ui_shutdown_start(reason)                     // "stopping for reboot" / "halt" / "poweroff"
  for each tier in REVERSE order:
      for each service in tier (reverse):
          supervisor.stop_service(...)
              → state=STOPPING, signal sent
              → ui_event_stopping(name)         // reverse-spinner row
      poll-and-tick until tier drained
      ui_tier_done(tier)
  ui_shutdown_complete(reason, elapsed_ms)      // final card
  fork child → uadmin                           // existing flow unchanged
```

### 8.3 zygctl status

```
zygctl client:
  rich = detect_rich_mode()
  if rich == MODE_PLAIN:
      send "STATUS PLAIN"
  else:
      send "STATUS"
  print response verbatim

zyginit socket handler:
  cmd_status(table, arg, plain_flag):
      if plain_flag or arg != "":
          return ui_render_status(table, want_banner=0, plain=1)
      return ui_render_status(table, want_banner=1, plain=0)
      // when plain=0, the function reads g_render_mode from ui module state
```

The server already knows its own render mode from `ui_init`; the `PLAIN` keyword from the client just forces plain output for that one response (covers the case where zygctl is on a TTY but redirecting output, or vice versa).

## 9. Testing

| Layer | Where | How |
|-------|-------|-----|
| `detect_rich_mode()` | Linux dev | Unit test with env-var / isatty fixtures across all 5 mode outcomes |
| Rendering (plain) | Linux dev | Snapshot tests: feed event sequence, assert exact string output |
| Rendering (rich) | Linux dev | Snapshot tests: feed events, assert escape sequences against golden files |
| `ui_spinner_frame(reverse)` | Linux dev | Unit: assert frame string for `g_tick` in `{0,1,2,3,4,5,6,7}` and both reverse settings |
| Boot tape rolling | Linux dev | Feed 30 events into a 12-line tape, assert visible-window content |
| Progress bar | Linux dev | Unit: assert fill width and percent for `(done, total)` pairs |
| Integration tests | Linux dev | Existing 44 tests get `ZYGINIT_NO_UI=1` to force plain mode for diff stability |
| `zygctl STATUS PLAIN` | Linux dev | Add to existing socket integration tests |
| Framebuffer visual | `hh-prototest` | Manual smoke + capture; one golden screenshot per layout (boot tape, boot final, shutdown mirror, shutdown final, zygctl status) |
| Serial console | `hh-prototest` serial | Visual confirmation that 16-color path renders identically modulo color depth |
| Sub-tick service | Linux dev | A oneshot that exits before first `ui_tick`; assert row goes straight to `●` (no spinner glyph) |
| Write failure | Linux dev | Mock write() to return error mid-boot; assert downgrade to plain and no crash |

## 10. Open boundary cases

These were considered and resolved during brainstorming; documented here so the implementation plan inherits the decisions.

1. **Tier names** — bare `tier N`. No `tier_name` TOML field. (Rejected: too much schema and config-churn for limited value.)
2. **`zygctl replace`** — does not render the rich UI. Replace is a developer/operator action, not a lifecycle one; stays plain-line per existing behavior.
3. **Runlevel transitions** (`zygctl single` / `multi`, `init s` / `init 3`) — do not render the rich UI. These are mid-session events; spawning a rich UI mid-session would interleave with whatever is already on the console. Plain lines, as today.
4. **Reload** (`zygctl reload`) — plain lines, as today.
5. **`zygctl log <name>`** — pass-through of the per-service log file. No color, no decoration.
6. **`zygctl list`** — keeps existing minimal shape. (No banner; type chip is the only color application.)
7. **Failure visibility in progress bar** — failed services count toward the bar's "done" tally so the bar can reach 100%. Failures are visible in the header's `failed:` line, not by holding the bar back.
8. **Final card timing** — no timer; final card persists until `console-login`'s ttymon paints `Login:` underneath. If `console-login` is disabled or fails to start, the card persists indefinitely. This is fine.

## 11. Phased delivery (preview for implementation plan)

The implementation plan will likely split this into ~5 phases. Sketch:

- **Phase 1.** New `src/ui.reef` skeleton; `detect_rich_mode()`; palette / glyph / sigil primitives; plain-mode pass-through.
- **Phase 2.** Boot rolling tape + header + progress bar; integrate with `main.reef` boot path.
- **Phase 3.** Spinner + `ui_tick` integration; verify forward/reverse rotation.
- **Phase 4.** Shutdown mirror + final cards (boot + shutdown).
- **Phase 5.** `zygctl status` server-side rendering + `STATUS PLAIN` wire modifier; client-side `detect_rich_mode` and dispatch.

Each phase ships independently with the existing build/deploy procedure (Linux dev for stubs + tests, then `hh-prototest` for visual smoke).
# zyginit 0.2.0 — Design

**Date:** 2026-05-14
**Status:** Approved (brainstorm complete); implementation plan to follow
**Scope:** Three integrated changes shipped as a single MAJOR release (pre-1.0 MINOR per semver): per-service directory layout, `task` service type made functionally distinct from `daemon`, and a new `[condition]` block for declarative platform/runtime gating with a SKIPPED state.

## 1. Goals

1. **Clean `/etc/zyginit/` layout** — each service self-contained in `services/<name>/` with a canonical `service.toml` plus optional `start.sh`/`stop.sh`. Eliminates the current ~50+ item flat directory mixing `<name>.toml` files with per-service helper-script directories at the same level.
2. **`task` type made functional** — currently the supervisor only branches on `daemon` vs `oneshot`; `transient` (formerly the third constant) was a no-op alias for `daemon`. 0.2.0 renames `transient` to `task` and gives it real semantics: may run for a while, exit 0 = STOPPED (counts as online), exit ≠ 0 = FAILED, never restarts.
3. **`[condition]` block** — declarative pre-flight checks. Services with failing conditions enter a new SKIPPED state instead of restart-looping or self-disabling via `zygctl disable`.
4. **Migration tool** — `scripts/migrate-layout.sh` converts an existing 0.1.x `/etc/zyginit/` in place. Idempotent, dry-run-by-default. Required on every 0.1.x → 0.2.0 upgrade since 0.2.0 has no backward-compat reader.

## 2. Non-goals

- **No backward compat with 0.1.x layout in the daemon.** Hard-cut. zyginit 0.2.0 reads only the new layout; an unmigrated tree results in an empty boot with a loud fatal log.
- **No automatic upgrade-on-first-boot migration in PID 1.** Operators run the migration tool out of band before installing the 0.2.0 binary. PID-1 risk on a failed migration would be unacceptable.
- **No `[assert]` block** (systemd's "fail-don't-skip" variant). Defer to a future release if a real use case emerges.
- **No condition kinds beyond `exists_file`, `exists_file_any`, `command`.** Defer `env_set`, `virtualization`, `zone`, `kernel_version_min`, etc. The minimal set covers acpihpd-style "platform doesn't support this" cases.
- **No new `zygctl` subcommands.** Existing surface is sufficient.
- **No `service.toml` schema field for the service name.** Name comes from the directory name. One source of truth.

## 3. Version

**0.2.0.** Service-definition filesystem layout changing is an incompatible schema break per the project's versioning policy (`docs/superpowers/specs/2026-05-05-versioning-and-release-tarball-design.md`). Pre-1.0 MINOR is permitted to break per semver convention. Tag `v0.2.0` points at the release commit.

## 4. Filesystem layout

### 4.1 New canonical layout

```
/etc/zyginit/
├── services/
│   ├── <name>/
│   │   ├── service.toml          # canonical filename inside every dir
│   │   ├── start.sh              # optional, executable
│   │   └── stop.sh               # optional, executable
│   └── ... (one directory per service)
├── enabled.d/
│   └── <name> -> ../services/<name>/   # symlink targets the directory
├── examples/
│   └── <name>/
│       └── service.toml
└── zyginit.toml                   # reserved for future; optional
```

### 4.2 Symlink target

`enabled.d/<name>` symlinks point at `../services/<name>/` — the **directory**, not the `service.toml` inside it. Rationale:
- Enables future per-service drop-in overrides (a `services/<name>/drop-ins/` directory or similar) without changing the enable mechanism.
- One symlink per service regardless of how many files live inside.
- Consistent with the "service = directory" mental model.

### 4.3 Path resolution within a service

Paths in `service.toml` that begin with `./` resolve relative to the service's directory. So `exec.start = "./start.sh"` means `services/<name>/start.sh`. Absolute paths (`/usr/sbin/dlmgmtd`) are unchanged.

## 5. `task` type

### 5.1 Name change

The constant `SERVICE_TYPE_TRANSIENT()` is renamed to `SERVICE_TYPE_TASK()` in `src/config.reef`. Integer value is preserved (the constant was unused in any on-disk state). `service_type_name(SERVICE_TYPE_TASK())` returns `"task"`. The TOML parser accepts `type = "task"` and rejects `type = "transient"` with a clear error.

### 5.2 Semantics

A `task` service:
- May run for any duration (unlike `oneshot`, which the operator expects to exit quickly).
- Is supervised normally during its run (process contract, state RUNNING, etc.).
- On clean exit (status 0): state transitions to STOPPED, `ui_event_stopped` fires, counted as **online** by the boot stats (per the existing `STATE_STOPPED + last_exit_code == 0 → online` rule from 0.1.x).
- On error exit (status ≠ 0): state transitions to FAILED, `ui_event_failed` fires, counted as **failed**.
- **Never restarts.** The `[restart]` block, if present with `on ≠ "never"`, is ignored at runtime with a config-load-time warning.
- **Skips the daemonize handshake.** Tasks don't double-fork; the entering-RUNNING-then-exiting pattern is the task's normal completion, not a daemon ready signal.

### 5.3 Supervisor branch

`src/supervisor.reef:handle_contract_event`, inserted right after the exit-code resolution and **before** the existing daemonize-handshake check:

```reef
let svc_type = config.svc_type(def)

if svc_type == config.SERVICE_TYPE_TASK()
    let dur_ms = (time.time_now() - rt.last_start_time) * 1000
    let ec = if exit_code >= 0 then exit_code else 0 end if
    rt.pid = 0 - 1
    rt.contract_id = 0 - 1
    rt.last_exit_code = ec
    table.contract_map.remove(int_to_str(contract_id))
    if ec == 0
        rt.state = STATE_STOPPED()
        table.runtimes[idx] = rt
        ui.ui_event_stopped(name, dur_ms)
    else
        rt.state = STATE_FAILED()
        table.runtimes[idx] = rt
        ui.ui_event_failed(name, ec, dur_ms)
    end if
    return
end if
```

A `task` whose contract empties without a known exit code (the `hint_exit_code == -1` path) is best-effort treated as `exit 0` — the contract emptied cleanly and we have no signal of failure.

## 6. `[condition]` block

### 6.1 Schema

Optional block in `service.toml`:

```toml
[condition]
exists_file     = "/dev/acpihp"
exists_file_any = ["/dev/acpi", "/dev/acpihp"]
command         = "/usr/sbin/acpi_probe"
```

**Semantics:**
- All specified keys must pass (AND).
- Absent keys are no-ops.
- `exists_file_any = []` (empty list) is vacuously true.
- Missing `command` binary or exec failure: condition fails with reason `"command not found"` or `"command exec failed"`.
- `command` exit 0 = pass. Any non-zero exit = fail (reason includes the exit code).
- `command` runtime is bounded by a **5-second timeout**. Exceeded: kill the probe, condition fails with reason `"command timeout"`.

### 6.2 Evaluation timing

Conditions evaluate in `supervisor.start_service`, **before** the fork:

```reef
proc start_service(table: ServiceTable, idx: int): bool
    let rt = table.runtimes[idx]
    let def = rt.def
    let name = config.svc_name(def)

    let cond_result = evaluate_conditions(def)
    if cond_result.passed == false
        rt.state = STATE_SKIPPED()
        rt.skip_reason = cond_result.reason
        table.runtimes[idx] = rt
        ui.ui_event_skipped(name, cond_result.reason)
        return true
    end if

    // existing fork + exec path
    ...
end start_service
```

Conditions re-evaluate on every call to `start_service`. So `zygctl restart acpihpd` on a host where the condition still fails produces a fresh SKIPPED. A service SKIPPED on boot N can become RUNNING on boot N+1 if its condition becomes true.

### 6.3 Implementation location

`evaluate_conditions(def: ServiceDef): ConditionResult` lives in `src/config.reef` (or a new `src/condition.reef` if it grows beyond ~80 lines). Returns `{passed: bool, reason: string}` where reason is the human-readable cause.

### 6.4 New state

`STATE_SKIPPED()` is added to the runtime state enum in `src/supervisor.reef`. New field `skip_reason: string` on `ServiceRuntime`. State display:

| State | Glyph | Color | Label |
|-------|-------|-------|-------|
| `STATE_SKIPPED()` | `·` (Unicode) / `.` (ASCII) | `c.mute` | `" skipped"` |

The glyph is the same as STATE_STOPPED's; the label differs (`" skipped"` vs `" stopped"`). The reason text appears in the tape note and `zygctl status` NOTES column.

## 7. UI integration

### 7.1 New banner counter

`g_skipped: int` global in `ui.reef`. Reset in `ui_boot_start`. Incremented by `ui_event_skipped`. Shown in the boot/shutdown header summary line:

```
23 services · tier 5 · 19 done · 0 failed · 4 skipped
```

The boot final card:

```
[Z] zyginit 0.2.0 · multi-user                       boot 8.3s
23 services — 19 online, 0 failed, 4 skipped

all services online
─────────────────────────────────────
slowest:  dlmgmtd 1.2s  filesystem 0.55s  sshd 0.37s
```

When skipped > 0 and failed > 0: existing "failed: ..." line above the divider remains; skipped count appears in the summary headline.

### 7.2 New event proc

`ui_event_skipped(name: string, reason: string)`:
- Increments `g_skipped`.
- In rich mode: pushes a tape row with glyph `paint("mute", glyph_pending())`, name, and note `str.concat("skipped: ", reason)`. Calls `emit_redraw`.
- In plain mode: emits `<elapsed-s>  info  skipped  <name>  reason=<reason>`.

### 7.3 Progress bar

Skipped services count toward the **denominator advance** so the bar reaches 100% naturally:

```
counter = g_done + g_skipped    (where g_done already includes failed)
total   = g_num_svc
```

The label appended to the bar in shutdown mode (`" down"`) stays unchanged. In boot mode the bar's right-side counter reads `<counter>/<total>  <percent>%`.

### 7.4 `zygctl status`

Skipped services render in the table:

```
acpihpd       · skipped                              no /dev/acpihp
```

State column shows the dim glyph and `" skipped"` label. NOTES column shows the reason. Banner summary line includes the skipped count.

### 7.5 `zygctl list`

Skipped state isn't a "list" property (the list is the catalog, not the runtime state). `zygctl list` output is unchanged.

## 8. Migration

### 8.1 Tool

`scripts/migrate-layout.sh` is a portable POSIX shell script delivered in the release tarball.

**Modes:**
- `--dry-run` (default): prints the planned moves to stdout and exits 0.
- `--apply`: performs the moves.
- `--config-dir <path>`: target directory (default `/etc/zyginit/`).

**Operation:**
1. Discover top-level `<name>.toml` files in `<config_dir>/`.
2. For each, plan: `mkdir -p services/<name>/`, `mv <name>.toml services/<name>/service.toml`.
3. If `<config_dir>/<name>/` exists with helper scripts, plan: `mv <name>/* services/<name>/`.
4. For each `enabled.d/<name>` symlink: plan retarget to `../services/<name>/`.
5. Idempotent: skips any service that's already migrated (already has `services/<name>/service.toml`).

**Safety:**
- If both old (`<name>.toml`) and new (`services/<name>/service.toml`) layouts exist for the same service, refuse to proceed. Operator must resolve the ambiguity manually.
- All moves are atomic (`mv` within the same filesystem).
- The script is idempotent; safe to re-run.

### 8.2 In-repo `services/hammerhead/` tree

Gets the same migration before the 0.2.0 release tarball is built. The tree currently has 17 services in the old flat layout; the migration is a one-shot reshape in a single commit during implementation.

The `examples/` directory follows the same convention: each example becomes `examples/<name>/service.toml`. The migration tool walks `examples/` too. Operators copying an example into a real config can do a flat directory copy without renaming files.

### 8.3 Hammerhead-side overrides

`base/usr/src/zyginit/overrides/` on the Hammerhead side currently uses the same flat layout. The Hammerhead team runs the migration tool against their override tree as part of consuming the 0.2.0 source drop. Release notes call this out.

### 8.4 Release-note guidance

The 0.2.0 release notes include:

1. **Run the migration tool before swapping binaries:**
   ```sh
   /path/to/migrate-layout.sh --dry-run    # preview
   /path/to/migrate-layout.sh --apply      # apply
   ```
2. **Then swap `/sbin/init` and `/sbin/zygctl`** as in prior 0.1.x deployments.
3. **Reboot.** If something goes wrong, the operator boots from a recovery medium and reverts `/sbin/init` to the prior version (the new layout is forward-compatible-only with 0.1.x binaries on the original `<name>.toml` flat tree — operator would need to reverse the migration too).

## 9. Data flow (boot)

```
main.reef on PID 1 boot:
  setup_pid1_console()
  ui_init(detect_rich_mode_for_main())
  ui_detect_winsize()
  if !exists(<config_dir>/services/)
    println FATAL: services/ directory missing — run scripts/migrate-layout.sh
    enter idle loop
  end if
  load_services_from_layout()         // walks services/*/service.toml
  scan_enabled_dir(enabled.d/)        // dereferences directory symlinks
  build_dep_graph(...)
  ui_boot_start(num_svc, num_tiers, runlevel)
  for each tier:
    ui_tier_start(tier)
    for each service in tier:
      supervisor.start_service(...)
        // condition evaluation BEFORE fork
        evaluate_conditions(def)
        if !passed:
          state = SKIPPED
          ui_event_skipped(name, reason)
          continue
        // type dispatch
        if type == TASK:
          fork+exec; on exit handle via task branch (see §5.3)
        elif type == DAEMON:
          fork+exec; daemonize handshake path as today
        elif type == ONESHOT:
          fork+exec; oneshot completion path as today
    poll-and-tick until tier settles
    ui_tier_done(tier)
  boot_settle_period (1s, from 0.1.8)
  build_boot_stats(table) → includes online/failed/skipped/slowest
  ui_boot_complete(stats)
  enter main event loop
```

## 10. Error handling

### 10.1 Layout discovery

- **`services/<name>/` exists but no `service.toml`** — warning, skip directory, continue.
- **`services/<name>/service.toml` parse error** — fatal-tier log, omit from table, continue with other services.
- **`enabled.d/<name>` symlink target doesn't exist** — warning, ignore, continue.
- **`enabled.d/<name>` symlink target escapes `services/`** (target path doesn't start with `<config_dir>/services/`) — warning, ignore, continue. Defensive: prevents arbitrary-path read via a malicious enabled.d symlink.
- **No `services/` directory at all** — fatal log, empty boot, idle loop (operator must migrate).

### 10.2 Condition evaluation

- **`exists_file` to a missing file** — condition fails, reason `"missing /path"`.
- **`exists_file_any` with all missing** — condition fails, reason `"none of [paths] exist"`.
- **`command` binary missing** — condition fails, reason `"command not found: /path"`.
- **`command` fork failure** — condition fails, reason `"command exec failed"`.
- **`command` exit non-zero** — condition fails, reason `"command exit=<code>"`.
- **`command` exceeds 5-second timeout** — kill probe, condition fails, reason `"command timeout"`.

### 10.3 Task handling

- **Task fork fails** — `ui_event_failed`, no restart attempt. Same as daemon fork failure.
- **Task contract empties with `exit_code = -1`** — treat as exit 0 (best-effort), state STOPPED.
- **Task with `[restart] on = "always"`** — config-load-time warning logged; supervisor still doesn't restart it.

### 10.4 Migration tool

- **Both old and new layouts exist for the same service** — refuse to proceed, exit non-zero with clear message.
- **Cross-filesystem `mv` would be required** — refuse, advise operator to ensure `<config_dir>` is on a single filesystem.
- **Permission denied** — exit non-zero with the offending path.

## 11. Testing

See Brainstorm Section 6 in the chat history for the full test matrix. Highlights:

- **Layout parser unit tests** — name resolution from directory, parse-error containment, skip-directory-without-toml.
- **Symlink resolution tests** — happy path, dangling, escape rejection.
- **Migration tool tests** — dry-run, apply, idempotent, ambiguity rejection.
- **`task` type tests** — exit 0 → STOPPED+online, exit 1 → FAILED, no restart loop, fork failure handling.
- **`[condition]` block tests** — each kind in pass and fail, command timeout, binary missing, multi-kind AND.
- **UI snapshot tests** — `task_ok`, `task_failed`, `boot_with_skipped`, `final_card_with_skipped`, `status_skipped`.
- **Hammerhead VM smoke test** — manual on `hh-prototest`, includes running the migration tool against the live config before swapping binaries.

## 12. Phased delivery (preview for implementation plan)

The plan will likely break into ~6-8 phases:

- **Phase 1.** Migration tool (`scripts/migrate-layout.sh`) with dry-run + apply + idempotent + ambiguity refusal. Plus Linux-dev unit tests for the tool against fixtures.
- **Phase 2.** Layout parser changes — `scan_services_dir`, symlink-target dereference, escape rejection. Update `services/hammerhead/` tree in this repo via the migration tool.
- **Phase 3.** `task` type — rename `TRANSIENT` → `TASK`, parser update, supervisor branch.
- **Phase 4.** `[condition]` block — schema, `evaluate_conditions`, `STATE_SKIPPED()`, `skip_reason`, `ui_event_skipped`, `g_skipped` counter.
- **Phase 5.** UI integration — banner counter, final-card summary, `zygctl status` skipped row, progress-bar denominator update.
- **Phase 6.** Integration tests + snapshot tests for all the new scenarios.
- **Phase 7.** Version bump 0.1.8 → 0.2.0, tag, release tarball, release-note guidance for Hammerhead consumers.

Each phase ships as one or more focused commits; all tests must pass at the end of each phase before moving to the next.
# Progress Gauge in Header Divider — Design

**Date:** 2026-06-01
**Status:** Approved (brainstorm complete); implementation plan to follow
**Scope:** Relocate the boot/shutdown progress indicator from the last row of the screen into the existing horizontal divider in the boot header. Eliminates a long-standing "progress bar disappears and reappears" artifact and reclaims two rows of vertical space for the rolling tape. Symmetric treatment for shutdown.

## 1. Problem

The boot screen rendered by `render_boot_screen()` in `src/ui.reef` ends with a horizontal divider plus a separate progress bar row, occupying the bottom two rows of the screen. The progress bar is the very last row — the file's own comment at `src/ui.reef:517-519` notes that the layout fits exactly `g_screen_rows` and cannot afford even a trailing newline.

Between zyginit's `\e[2J\e[H` redraws, any other writer to the console — a kernel `printk`, a daemon's startup stderr, a not-yet-suppressed driver message — scrolls the screen up. The last row is the first thing to scroll off. The user sees the progress bar disappear, then reappear on the next redraw, then disappear again. The artifact is endemic to placing dynamic content on the last row of a shared console.

## 2. Goals

1. **Stability under concurrent writers.** Move the progress indicator out of the most-volatile screen row.
2. **No layout twitch at boot completion.** The transition from live gauge to final boot-time label must not shift any surrounding glyph.
3. **Reclaim vertical space.** Eliminate both the bottom cosmetic divider and the bottom progress row — give those rows to the rolling tape.
4. **Symmetric shutdown.** Apply the same treatment to the shutdown screen; same bug exists there.
5. **No regressions in plain or ASCII mode.** `MODE_PLAIN` continues to emit line-by-line events; `MODE_RICH_ASCII` continues to use only ASCII characters.

## 3. Non-goals

- **No new TOML schema fields.** This is purely a console-rendering change.
- **No `zygctl` protocol changes.** `zygctl status` is rendered by `src/ui_render.reef` and is not touched.
- **No palette, sigil, or glyph changes.** The visual pass shipped in 0.1.3 stays as-is; only layout moves.
- **No animation changes.** Spinner cadence, tape-row behavior, and tier-progression logic are unchanged.
- **No supervision or dependency-graph changes.** Pure UI work.

## 4. Visual design

### 4.1 Before

```
  [Z] zyginit 0.2.2 · multi-user   elapsed 2.4s
  20 services · tier 3 · 8 done · 0 failed · 0 skipped
  failed: none
  ─────────────────────────────────────────       (top divider — cosmetic)
  [tape row 1]
  …
  [tape row N]
  ─────────────────────────────────────────       (bottom divider — cosmetic)
  ████░░░░░░░░░░░░░  8/20  31%                    (progress bar — last row, scrolls off)
```

### 4.2 After — boot in progress

```
  [Z] zyginit 0.2.2 · multi-user   elapsed 2.4s
  20 services · tier 3 · 8 done · 0 failed · 0 skipped
  failed: none
  ─────[████████░░░░░░░░░░  31%]───────────       (gauge inside divider)
  [tape row 1]
  …
  [tape row N+2]                                  (+2 rows reclaimed)
```

### 4.3 After — boot complete

The existing `ui_boot_complete()` at `src/ui.reef:708` clears the screen and paints a separate "final card" (sigil, version, `boot Xs`, online/failed/skipped summary, optional failure hint, slowest-services list). **The final card is unchanged** by this work. The new divider gauge therefore runs only during the live boot screen; the boot post-label (`[ boot 10.0s ]`) is rendered in code but is only momentarily visible — within one frame, the final card replaces the boot screen.

The `elapsed Xs` field on header line 1 is dropped from the boot screen once `g_done + g_skipped + g_failed_count == g_num_svc` (i.e., the boot has visually completed even if the final-card transition hasn't fired yet). This avoids showing a stale `elapsed 9.8s` while the gauge reads 100% in the brief window before the final card.

### 4.4 Shutdown

Symmetric with boot. `ui_shutdown_complete()` at `src/ui.reef:818` already paints a shutdown final card after the last service stops (sigil, `reboot X.Ys`, "invoking uadmin..." line). **The shutdown final card is unchanged.** The new divider gauge runs only during the live shutdown screen as services stop:

```
  ─────[█████████████░░░░░░░  65%]──────────       (during stop sequence)
```

Header content (status lines, failure summary) above the divider is unchanged.

## 5. Rendering rules

A new function `fmt_divider_gauge(done: int, total: int): string` replaces:

- The `make_divider()` call at the end of `fmt_header()` (the top divider).
- The bottom divider line in `render_boot_screen()`.
- The `fmt_progress_bar()` line in `render_boot_screen()`.

Width: identical to today's `make_divider()` — `g_line_width - 16` cells of total divider width, with the leading two-space indent preserved. The brackets plus their inner content consume 28 cells (`[` + 26 inner + `]`); the remaining `g_line_width - 44` cells are split equally between left and right padding (odd cell goes right).

**Narrow-terminal fallback.** If `g_line_width < 46` (i.e., `total_width < 30`) the bracket pair plus at least one flanking dash on each side won't fit. In that case `fmt_divider_gauge()` degrades to a label-only divider — no bracket pair, just `<lpad>── 31% ──<rpad>`. This path is exercised only on artificially small consoles; the Hammerhead framebuffer and standard serial console widths (80+) always hit the full layout.

The layout inside the divider (full path) is:

```
  <lpad>[<content>]<rpad>
```

Where:

- **Brackets** are literal `[` and `]`, painted with the `accent` color.
- **lpad / rpad** are `─` chars in `MODE_RICH`, `-` chars in `MODE_RICH_ASCII`, painted `accent`. Padding is distributed equally on both sides; if total padding is odd, the extra cell goes to the right side.
- **content** has a fixed inner width so the bracket positions never move between live and post-complete renders. Inner width = bar(20) + two-space gap + 4-char `NNN%` field = 26 cells.

### 5.1 Live content

```
<bar>  <pct>%
```

- **bar**: 20 cells. In `MODE_RICH`: `█` (accent) for filled, `░` (mute) for empty. In `MODE_RICH_ASCII`: `#` for filled, space for empty. Filled count = `(done * 20) / total`, clamped to `[0, 20]`.
- **pct**: integer `(done * 100) / total`, clamped to `[0, 100]`, right-aligned in a 3-cell field, followed by `%`. So `"  3%"`, `" 31%"`, `"100%"` all consume 4 cells.

### 5.2 Plain mode

`MODE_PLAIN` continues to emit one line per event via `fmt_plain_event()` and ignores the divider gauge entirely. `fmt_divider_gauge()` returns `""` in plain mode, same as `fmt_progress_bar()` does today.

## 6. State changes

**None.** Both `ui_boot_complete()` (`src/ui.reef:708`) and `ui_shutdown_complete()` (`src/ui.reef:818`) already exist and paint final cards that replace the live screen. The new divider gauge is purely a transform on existing counters (`g_done`, `g_skipped`, `g_num_svc`), so no new `g_*` flags are required.

Header behavior:

- `fmt_header()` drops the `elapsed Xs` field from line 1 when `g_done + g_skipped + g_failed_count >= g_num_svc` during the boot phase. This is a pure boolean check on existing counters; no new flag. During shutdown the elapsed field is left as-is (the shutdown final card carries the timer once complete).

## 7. Files touched

- **`src/ui.reef`** — only file touched.
  - New: `fmt_divider_gauge(done, total)` — main rendering function. Includes the narrow-terminal fallback in §5.
  - Update: `fmt_header()` — conditional `elapsed Xs` (suppressed when `g_done + g_skipped + g_failed_count >= g_num_svc` and phase is boot); divider line now calls `fmt_divider_gauge(g_done + g_skipped, g_num_svc)`.
  - Update: `render_boot_screen()` at `src/ui.reef:499` — remove the bottom divider concatenation and the `fmt_progress_bar()` call. Trailing-newline accounting recomputed so total height still equals `g_screen_rows`.
  - Update: tape height calculation at `src/ui.reef:682` — `g_tape_height = g_screen_rows - 6` becomes `g_screen_rows - 4` (header is 4 rows including the gauge divider; no trailing rows).
  - Update: scenario harness in `ui_demo()` — the existing `progress_rich`, `progress_ascii`, `progress_full` scenarios at lines 950-963 currently call `fmt_progress_bar()`; convert them to exercise `fmt_divider_gauge()` instead. Add fresh `gauge_full_screen_boot` scenario for full-layout visual check.
  - Delete: `fmt_progress_bar()` (lines 393-439), `PROGRESS_WIDTH()` (line 391). No remaining callers after the harness conversion.

- **`src/main.reef`** — no changes. `ui_boot_complete()` and `ui_shutdown_complete()` already wired.
- **`src/shutdown.reef`** — no changes.

- **`src/ui_render.reef`** — no changes. `zygctl status` rendering is independent.

## 8. Backwards compatibility

- **`MODE_PLAIN` output** — unchanged. Same line-per-event format consumers parse today.
- **`MODE_RICH_ASCII` output** — gauge characters (`#`, space) and divider characters (`-`) are pure ASCII. No new Unicode dependencies.
- **`MODE_RICH` output** — gauge characters (`█`, `░`) and divider character (`─`) were already in use in the prior layout. No new code points.
- **Screen-height math** — assumes `g_screen_rows >= 5` (1 header line + 3 status lines + at least 1 tape row). Already an existing assumption; no change.
- **External consumers** — none. `zygctl status`, scripted log parsers, and the syslog stream all read `MODE_PLAIN` or daemon log output, not the framebuffer rendering.

## 9. Testing

Manual on `hh-prototest` (the Hammerhead VM at 192.168.122.50):

1. **Cold boot.** Confirm gauge fills as tiers progress; confirm post-boot label `boot Xs` appears after the last tier; confirm `elapsed Xs` disappears from header line 1.
2. **Boot under noise.** Trigger a kernel printk during boot (e.g. a `dladm` configure with verbose driver). Confirm gauge stays visible across the scroll.
3. **Shutdown.** `zygctl halt`. Confirm gauge inverse-fills; confirm `down Xs` label appears before reboot.
4. **Single-user boot.** `boot -s`. Confirm gauge still renders correctly in the smaller service set.
5. **Plain mode.** `ZYGINIT_NO_UI=1`, `NO_COLOR=1`, non-TTY redirect, or running non-PID-1. Confirm line-per-event output is unchanged.
6. **ASCII mode.** `TERM=dumb` (or any non-color-capable terminal that doesn't trip the plain-mode fallback). Confirm `#` / space gauge renders inside the divider.

No unit tests added — the boot UI has historically been validated visually on the test VM. Existing integration tests in `tests/integration/` continue to cover supervisor behavior independently.

## 10. Open questions

None. All decisions made during brainstorming:

- Gauge style: block fill (`█`/`░` in rich, `#`/space in ASCII) — matches the prior progress bar's character set.
- `elapsed Xs` on header line 1: shown only while boot is in progress; dropped once all services have resolved (done/failed/skipped sum reaches total).
- Boot completion: existing `ui_boot_complete()` final card kept as-is. The new gauge runs only during the live boot screen.
- Shutdown: same treatment as boot. Existing `ui_shutdown_complete()` final card kept as-is. Gauge fills 0→100% as services stop, then the final card replaces the screen.
# Design: `conflicts` — service mutual exclusion

**Date:** 2026-06-13
**Status:** Approved (design phase)
**Roadmap item:** Near Term — Linux Development → Dependency Ordering Improvements → `conflicts`

## Summary

Add a `conflicts` field to a service's `[dependencies]` block that declares two
services as mutually exclusive — they may never run at the same time. This is the
inverse of `requires`: where `requires` pulls a dependency *in*, `conflicts` keeps
a peer *out*.

Motivating example: two services that bind the same resource (e.g. `sendmail` vs
`postfix` on port 25) should never both be running.

The feature is fully developable and testable in Linux dev mode — it touches the
config parser, the supervisor start path, and a new boot-time pre-flight pass. It
deliberately does **not** touch `depgraph.reef`: a conflict is mutual exclusion,
not an ordering relation, so it never becomes a topo-sort edge.

## Semantics (decided)

| Question | Decision |
|----------|----------|
| Runtime: `zygctl start B` while conflicting `A` is running | **Refuse.** Fail the start with a clear message; leave `A` running. No auto-eviction. |
| Boot: both conflicting services enabled and in the active set | **Start neither; mark both `FAILED`** with reason `"conflicts with <other>"`. zyginit never auto-picks a winner. |
| Declaration symmetry | **Symmetric.** Declaring `conflicts` on *either* side makes the pair mutually exclusive in both directions. |

**Cascade (accepted consequence):** a service that `requires` a conflict-failed
service will itself fail to start (existing behavior — a required dependency that
is not running blocks its dependents). For a deterministic init this is correct:
fail loudly and visibly rather than limp along on an arbitrary choice.

## Architecture

The single most important code fact: **every service start flows through
`supervisor.start_service(table, idx)` (`src/supervisor.reef:327`)** — boot tiers
(`main.reef:start_services_by_tier`), `zygctl start` (`socket.reef:cmd_start`),
runlevel transitions, and restarts all call it. That gives us one choke point for
the runtime guard, and a separate one-shot pre-flight for the boot case.

Two enforcement points, cleanly scoped and non-overlapping:

1. **Boot-time resolution** (`resolve_conflicts`) — a pre-flight pass that runs
   once, before the tier-start loop. Detects pairs where *both* members are active
   and fails both up front.
2. **Runtime guard** — inside `start_service`, refuses to start a service when a
   conflicting peer is already `RUNNING` or `STARTING`.

After the pre-flight runs at boot, no conflicting pair both survive into the active
set, so the runtime guard never trips spuriously during boot. The two mechanisms
do not overlap.

### Component 1: Schema & parsing (`src/config.reef`)

- Add to `ServiceDef`:
  - `conflicts: [string]`
  - `conflicts_count: int`
- `new_service_def()` initializes `conflicts: new [string](16)`, `conflicts_count: 0`
  (mirrors `requires`).
- Accessors `svc_conflicts(svc): [string]` and `svc_conflicts_count(svc): int`.
- Parse branch mirroring the `dependencies.requires` block at `config.reef:606`:
  ```
  if toml.toml_has_key(keys, vals, count, "dependencies.conflicts")
      let conf_str = toml.toml_get(keys, vals, count, "dependencies.conflicts")
      svc.conflicts_count = parse_toml_array(conf_str, svc.conflicts, 16)
  end if
  ```

### Component 2: The symmetric relation (helper)

A single helper expresses the mutual relation so both enforcement points agree:

```
fn conflicts_with(table, a_idx, b_idx): bool
```

Returns true if `a` lists `b` in its `conflicts`, **or** `b` lists `a` in its
`conflicts` (symmetry). Comparison is by service name. Self-reference
(`a == b`) returns false. Names that do not resolve to a known service are
ignored (warned once during the pre-flight pass, same spirit as
`depgraph`'s "requires unknown service" warning).

Lives in `supervisor.reef` (it operates over the runtime table). Both
`resolve_conflicts` and the `start_service` guard call it.

### Component 3: Boot-time resolution (`resolve_conflicts`)

- New proc in `supervisor.reef`, invoked from `main.reef` immediately before
  `start_services_by_tier`.
- For each unordered pair `(i, j)` of services that are **both in the active set**
  and `conflicts_with(table, i, j)`: set both `runtimes[i]` and `runtimes[j]` to
  `STATE_FAILED()` with a stored reason `"conflicts with <other-name>"`.
- A service already failed by an earlier pair stays failed (three-way mutual
  conflicts → all involved fail). Order-independent.
- The tier-start loop must skip services that are not in a startable state
  (already-`FAILED`/`SKIPPED` services are not forked). Verify
  `start_services_by_tier` honors this; if it currently starts unconditionally,
  add the state guard.

### Component 4: Runtime guard (inside `start_service`)

- Insert immediately after the `[condition]` evaluation block
  (`supervisor.reef:341`), before contract template setup / fork.
- Scan the table: if any service `j` with `conflicts_with(table, idx, j)` is in
  `STATE_RUNNING()` or `STATE_STARTING()`, abort:
  - do **not** change `idx`'s state (leave it `STOPPED`/`WAITING`),
  - surface `"cannot start <name>: conflicts with running service <other>"`
    (println in plain mode; returned to the socket caller for `zygctl`),
  - `return false`.
- Because all start paths funnel through `start_service`, this covers `zygctl
  start` and runlevel transitions with no extra code at those call sites.

### Component 5: Reporting

- The failure/refusal reason is stored on the service runtime and shown in
  `zygctl status`. Reuse the existing status-reason mechanism rather than adding
  a parallel field — the exact field name (`skip_reason` vs. a new
  `status_reason`) is confirmed against the `ServiceRuntime` struct during
  implementation; if `skip_reason` is `SKIPPED`-specific, a small rename to a
  generic reason field is acceptable and preferred over a second parallel field.
- Boot case: two `FAILED` rows, each reading `conflicts with <other>`.
- Runtime case: the refusal message is returned on the `zygctl start` connection;
  the target service's status is unchanged.

## Error handling & edge cases

- **Unknown conflict target** (names a service that doesn't exist): warn once
  during `resolve_conflicts`, then ignore. Never fatal.
- **Self-conflict** (`A` lists `A`): ignored.
- **Duplicate / both-sided declaration** (`A` lists `B` and `B` lists `A`):
  harmless — the symmetric helper already treats it as one relation.
- **Three+ way mutual conflict:** every service involved in any active conflicting
  pair is failed. Deterministic and order-independent.
- **Conflict with a disabled / non-active service:** no effect — only services in
  the active set participate in boot resolution, and only `RUNNING`/`STARTING`
  peers trip the runtime guard.

## Testing (Linux dev mode, `tests/integration/`)

New suite plus a parser check:

1. **Boot resolution:** enable two services that conflict; assert both end in
   `FAILED` with a `conflicts with` reason, and neither process ran.
2. **Runtime refusal:** start `A`; `zygctl start B`; assert the refusal message,
   that `B` did not start, and that `A` is still `RUNNING`.
3. **Symmetry:** declare `conflicts` on one side only; assert enforcement holds
   regardless of which service starts first.
4. **Parser** (`config.reef` test path): a TOML with
   `[dependencies] conflicts = ["x", "y"]` parses to `conflicts_count == 2` with
   the right names.

## Documentation

- `docs/DESIGN.md` — add `conflicts` to the `[dependencies]` schema reference.
- `zyginit.5` man page — document the field and its three semantics.
- `CLAUDE.md` — add `conflicts` to the `[dependencies]` block in the Service
  Definition Schema quick reference.
- `ROADMAP.md` — check the `conflicts` box under Dependency Ordering Improvements.

No new file added to `examples/` — the 4 canonical examples stay as-is; the
schema docs carry the `conflicts` reference.

## Out of scope (YAGNI)

- systemd-style auto-eviction (stopping the running peer to start a new one) —
  explicitly rejected in favor of "refuse."
- Conflicts as graph edges / ordering — a conflict is exclusion, not order.
- `conflicts` participating in dependency resolution or milestones.