xy/docs/superpowers/specs/2026-08-07-xy-readiness-gate-design.md

xy — Readiness Gate (wait-for)

Date: 2026-08-07 Status: Approved — ready for implementation planning

Problem

Since start-on-login landed, xy daemon runs from a launchd agent at login. Docker-backed servers (gitea, signoz) race OrbStack and lose.

Measured on this machine 2026-08-07: OrbStack's process started at 12:47:56 and created ~/.orbstack/run/docker.sock at 12:48:14 — 18 seconds later. OrbStack is a BTM login item, not a LaunchAgent, so it is not even guaranteed to begin before the agent does.

Against that, docker run fails instantly while the socket is absent, and the default restart budget is backoff-initial 1s, backoff-max 30s, max-retries-per-minute 5. Attempts therefore land at t=0, 1, 3, 7, 15s; the fifth trips the cap and policy::decide returns MarkFailed, which is terminal. A docker-backed server gives up ~15 seconds after the daemon starts and stays down until a manual xy start.

The 2026-08-07 log shows this nearly firing during a reload: socket error at 10:47:58, recovery at 10:48:15 — 17 seconds, right at the edge.

Widening the retry budget per-server would paper over it. The real defect is that a server with an unmet infrastructure dependency consumes its crash-retry budget while waiting for something that was never its own fault.

Goals

• Let a server declare a precondition that must hold before it is spawned.
• Waiting must never consume the crash-retry budget.
• Waiting must be visible and self-explaining, not indistinguishable from a hang.
• Waiting must stay responsive to stop / shutdown.

Non-goals (deferred)

• Ordering between supervised servers (depends-on <name>). The conditions here can express it (tcp 127.0.0.1:3928) without a dependency graph.
• Liveness probes on an already-running server. This gate is start-time only; HTTP health probes remain a non-goal from the MVP spec.
• Re-checking the condition while a server runs.

Decisions

Three condition kinds

wait-for {
    path "~/.orbstack/run/docker.sock"
    timeout "120s"
    interval "1s"
}

path, tcp, and command are all supported:

Kind	Ready when
path "<p>"	the path exists
tcp "<host:port>"	a TCP connection succeeds
command "<c>" args "…"	the process exits 0

Exactly one condition per wait-for block. Zero or more than one is a parse error, so xy reload exits 3 and changes nothing — matching how invalid config already behaves.

path values get a leading ~/ expanded at parse time from $HOME, since the motivating case is literally ~/.orbstack/run/docker.sock. $HOME rather than etcetera::home_dir() deliberately: xy-protocol is a leaf crate with no directory dependencies, and adding one for a two-line prefix substitution is not worth it. If $HOME is unset the literal path is kept, which simply never exists and surfaces as a normal timeout. The expanded path is what xy status displays, so there is no ambiguity about what was checked.

Note the KDL shape of the command kind: command and args are sibling nodes inside the block, mirroring the top level, not one node with trailing arguments:

wait-for {
    command "docker"
    args "info"
}

so the parser accumulates them separately and combines them after the loop. args without command is a parse error.

The command kind is bounded by the poll interval: each invocation is run under a timeout of interval and a non-exit is treated as not-ready, so a hung docker info cannot wedge the poll loop.

Timeout marks the server Failed without spawning

On timeout, the server goes to Failed and nothing is spawned. xy status names the condition that timed out.

Rejected: spawning anyway on timeout, which reintroduces exactly the retry-burn this feature removes; and waiting forever, which turns a typo in a path into a server that sits in waiting with nothing ever surfacing.

Waiting never touches the retry window

RetryWindow::record continues to be called only for real process exits. This is the property that fixes the reported bug: a cold Docker costs patience, not retry budget.

Every start is gated

The gate runs for the initial start, the explicit restart command, and the automatic post-crash respawn. If Docker dies and takes the container with it, the respawn should wait for Docker again rather than burn retries.

New Waiting state, reason on status only

ServerState gains Waiting — an additive enum variant, backward compatible on the wire. xy list shows a plain waiting to keep the table narrow; xy status <name> renders what it is blocked on and for how long:

$ xy status gitea
  state:    waiting
  wait-for: path /Users/olsson/.orbstack/run/docker.sock
            43s elapsed, timeout 120s

Rejected: reusing Starting, which is indistinguishable from a slow-starting process — the exact ambiguity this feature exists to remove.

Elapsed time is computed at read time from a carried Instant, never precomputed at publish time. This is the rule established by the 2026-08-07 uptime bug, where a value snapshotted into the watch channel froze at 0.

Schema

xy-protocol/src/config.rs:

pub enum WaitCondition {
    Path(PathBuf),
    Tcp(String),
    Command { command: PathBuf, args: Vec<String> },
}

pub struct WaitForConfig {
    pub condition: WaitCondition,
    pub timeout: Duration,   // default 120s
    pub interval: Duration,  // default 1s
}

ServerConfig gains #[serde(default)] pub wait_for: Option<WaitForConfig>. Absent wait-for means no gate and behaviour identical to today.

Supervisor

The gate lives inside do_start, before the spawn. This is the one structural change worth calling out: do_start currently returns std::io::Result<S::Child>, which cannot express the gate's outcomes. It becomes:

enum StartFailure {
    Spawn(std::io::Error),
    WaitTimedOut,
    Cancelled,   // Stop arrived while waiting
    Shutdown,    // Shutdown arrived while waiting
}

async fn do_start(&mut self, cause: StartCause) -> Result<S::Child, StartFailure>

All three call sites are updated. Shutdown must propagate a return from run, exactly as the backoff sleep already does. Cancelled settles the server in Stopped — a stop issued during a wait leaves it stopped, not failed, since the user asked for it. WaitTimedOut settles in Failed.

The poll loop is interruptible. It selects over the interval sleep and self.cmd_rx, the same shape as the existing backoff sleep (commit b366df0, "make backoff sleep interruptible by Stop/Shutdown"). Without this, xy stop on a waiting server would block for up to the full timeout.

Status carries the wait progress rather than a rendered string:

pub struct WaitProgress {
    pub description: String,
    pub started_at: Instant,
    pub timeout: Duration,
}

with Status.waiting: Option<WaitProgress>. Handlers derive elapsed_secs when building the RPC response. StatusDetail gains wait_for: Option<WaitInfo { description, elapsed_secs, timeout_secs }>.

Testing

TDD throughout.

• Config parse tests per condition kind; defaults applied; ~ expanded; zero conditions and two conditions both rejected.
• Condition checks in isolation: path present/absent; TCP against a listener bound to an ephemeral port, and against a closed port; command exiting 0, exiting non-zero, and one that hangs past interval.
• Supervisor: condition already met spawns immediately; timeout yields Failed with no spawn and an untouched retry window (the regression assertion for the reported bug); Stop during a wait cancels promptly rather than after the timeout; Shutdown during a wait returns.
• Formatting: waiting in the list table; xy status renders the description and a growing elapsed value.
• Integration: a server whose wait-for path can never exist reaches Failed after a short configured timeout without ever spawning.

Timeouts and intervals in tests are milliseconds, so no test waits on wall time.

Documentation

README.md gains a wait-for section with the three condition kinds and the OrbStack example, plus a note that waiting does not consume the restart budget.

Rollout

Once shipped, gitea.kdl and signoz.kdl each gain:

wait-for {
    path "~/.orbstack/run/docker.sock"
    timeout "180s"
}

Until then those two servers remain vulnerable at every login. The interim mitigation, if wanted, is backoff-max "15s" and max-retries-per-minute 20 in both files.