status: what is really running

status reads the worktree, its manifest and its runs, then returns the runtime facts as they are. It is the one command a session opens with, and it is allowed to say it cannot see.

Four facts, not one

The product keeps apart things a shell one-liner collapses. A live process, a bound port, a passing health check and an exit reason are four different facts, and none of them implies the next.

hello-worktree · main

api      running   :21730   health 200
worker   running   no port

2 services · manifest oberth.yaml

Read the table

The human table is ordered by project, service, dependencies, code and failure reason. Each service line carries both the declared port and the current runtime fact; the failure section shows only the most recent exit while it is still that service's current last_exit.

• A portless worker is printed as no port. It is observed through its run record, not through a listener.
• port: auto before assignment prints auto port unassigned; it is not a failure.
• Only listeners the manifest did not declare are listed separately. A port that belongs to a service appears with that service.
• code_changed_since_start says the process is running older code than the checkout, with a restart hint. It is a code fact, not a runtime failure.

For agents: --brief and --json

oberth status --json --brief

--json's top-level object is worktree. --brief keeps only runtime facts, so it is the cheapest place to start; the full read adds the git summary, drafts, the change list and per-service manifest fields.

• worktree.identity is the wt_… value used by down --identity and by data paths.
• worktree.services[] carries running, port_actual, health_status, pid and run_id.
• exits[] carries the reason, the exit code and a hint that points at evidence that really exists.
• observation appears only when the listener table is untrustworthy; its silence means the table was usable.

When observation fails

A sandbox, a permission wall or a platform change can break the listener scan. The engine then reports observation_empty, observation_unrecognized, observation_incomplete, observation_blind or observation_bind_denied. None of those codes means “nothing is listening”, and still less “not running”. The human table says listening unknown; a port: auto candidate is verified by binding rather than by trusting an empty table.

oberth doctor --only listener_observation

Run it in the same kind of process that failed. If the result is blind, retry from a normal terminal, or run oberth serve --detach there and retry; do not loop the same start inside the sandbox and read timeouts as failures.

What status never says