Waiting and Following

Deployment checks need an observed condition; live investigations need new records. A condition wait observes state until it is satisfied. Cursor following repeatedly reads records after an opaque position. Start with a connected CLI and tools advertising the required inputs; the two operations use different meanings of wait.

Gate Readiness

If discovery advertises the application group app, wait for readiness before sending test traffic:

arkoren app:ready --wait --timeout 30s

Proceed only after successful completion. An immediate app:ready can exit 0 with ready: false; it is an observation, not a shell gate. The wait does not start the application or run dependency checks.

Choose the condition that matches your next action. app:started --wait means startup completed, not that dependencies are healthy. With registered checks, app:healthy --wait requires a recent successful background pass. Without checks, health can already be ok; that says nothing about unregistered dependencies. Readiness observes whether the application can receive traffic.

Choose Failure Policy

Healthy and ready waits normally allow failed checks to recover within the budget. If deployment should stop on a fresh failed background pass, opt into fail-fast behavior:

arkoren app:healthy --wait --timeout 30s --fail-fast

An already cached failed pass ends this attempt if it is still fresh. Pending or stale health keeps waiting. --fail-fast requires wait=true and is not an input to started. Omit it when recovery within the budget is expected.

These are passive observations. If you intend to execute checks now, use the explicit app:health --fresh operation described in Application Diagnosis.

Bound Waiting

The CLI grants a condition-wait budget only when the discovered tool is annotated read-only, declares a boolean wait property, and receives JSON true in the final merged input. timeout configures the budget only if its advertised type is string. Omitted or zero duration selects 30s, not an unlimited wait.

One budget counts from before discovery and input processing through connection retries, execution, and owned session cleanup. The server receives the remaining duration, not a fresh full timeout. An explicitly non-string JSON timeout is left for server validation, not repaired. Non-string or undeclared timeout properties otherwise remain ordinary tool data.

The ordinary 10s per-request deadline is replaced by this total budget unless you explicitly set --request-timeout. An explicit setting can impose a shorter per-request limit; --request-timeout=0 removes that limit, not the total budget. Session cleanup has a separate one-second maximum and also honors cancellation and the remaining budget. Cleanup does not replace a selected result or stdout failure.

Before discovery, conventional-looking arguments provide only provisional connection hints. Schema parsing still owns tokens: a string property can consume a literal --wait or --input as its value without enabling either behavior. Only the final parsed input determines execution retry eligibility.

Eligible waiting reads can retry broken transports within the budget. Discovery backoff starts at 50ms, grows by 1.5, and caps at 500ms; execution retries pause 50ms. HTTP, authentication, certificate-verification, protocol, and tool failures are terminal. Actions and follow calls are never replayed automatically.

Application condition failures include condition_timeout, condition_stopped, and condition_failed. Their safe details are defined in Diagnostic Tools. A client deadline can expire before the server’s failure response arrives, so handle ordinary timeout errors too.

Follow Records

To observe warnings produced while reproducing an issue, start a live tail. This example assumes discovery advertises app:logs with follow: true:

arkoren app:logs --level warn --follow --no-color

The first call establishes an empty tail anchor; it does not print existing history. Subsequent tools/call requests send the returned opaque cursor with an idle wait of at most 25s. Available pages drain immediately. This is long polling, not a separate diagnostic SSE endpoint.

Follow prints compact newline-delimited JSON (NDJSON), one record per line, without page envelopes or saved cursor checkpoints. Loss and generation changes produce notice objects on the same stdout stream. For example, separate polls might report:

{"dropped":12}
{"instance_changed":true}

Consumers must distinguish notices from application records. A notice can also contain truncated: true, and one notice can combine fields. A replaced or reset store establishes a fresh tail rather than replaying the new generation’s history.

--request-timeout does not limit follow requests. Interrupt the process to stop it. A broken connection ends follow instead of silently reconnecting; restarting the CLI establishes a new tail and can miss records between runs.

Retain History

If you need recent context, request a bounded snapshot before reproducing the problem:

arkoren app:logs --level warn --limit 100

This prints one JSON result, not a live stream. A snapshot followed by a new --follow invocation is not an atomic handoff: records can fall between them. For controlled continuation, use ordinary calls with --cursor and retain the returned cursor according to the cursor contract. The CLI’s --follow mode always chooses a fresh tail rather than resuming your saved position.

Capture limits, ring eviction, and caller visibility bound the available evidence. Empty history does not prove an operation never occurred. Protect captured output like application logs.

Check Completion

Use a condition wait rather than status as a readiness gate. Check the process exit status even if stdout already contains data. Clean follow cancellation exits 0; a broken pipe or short write exits 1 and takes precedence over cancellation or the remote verdict. Output failure does not undo remote effects.

For all command flags and statuses, use CLI Reference.