feat: add ataegina status [--json] (read-only liveness)#29
Merged
Conversation
The side-effect-free "is my stack up, and where?" query an agent runs
before acting. Per surface it reports running (a live server ataegina
launched holds the port), foreign (something else holds it), unknown (held
but ownership unverifiable — often our own reparented daemon), or stopped.
Starts/stops nothing, opens no DB connection, and exits 0 regardless of
state (state is data, not failure). --json folds state+pid into the shared
slot shape; the db object is the same non-probed {name,url} as ports --json.
Reuses _ate_port_ownership + ate_port_pids for the classification, and
factors the shared db sub-object into emit_db_json (used by ports and
status). Also backfills the in-script `--help` for `ports --json` and
`up --wait`, which the prior two PRs added to the man page and README but
not to `usage()`.
Spec: docs/design/agent-native.md. Completion (bash+zsh), man page, README,
and CHANGELOG updated. New suite tests/status.bats (10 tests): stopped/
foreign/unknown states hermetically (fake `ss`), a read-only no-mutation
check, db + per-worktree index, arg validation, completion; plus an
integration test proving a real server we launched reads as `running`.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Third of five agent-native additions (
docs/design/agent-native.md). Agents need a side-effect-free way to ask "is my stack up, and where?" before acting, to stay idempotent (avoid double-up, know the pid/port).statusis that query.Per surface it reports:
running— a live server ataegina launched holds the portforeign— something ataegina did not launch holds it (a collision)unknown— the port is held but ownership can't be verified (often our own reparented daemon)stopped— nothing on the portStarts/stops nothing, opens no DB connection, and exits 0 regardless of state (state is data, not failure).
--jsonfoldsstate+pidinto the shared slot shape:{"index":1,"repo_root":"…","frontend":{"port":5174,"url":"…","state":"running","pid":1234},"backend":{"port":8001,"url":"…","state":"stopped","pid":null},"log_dir":"…","db":{"name":"myapp_wt1","url":"…"}}Reuses
_ate_port_ownership+ate_port_pids; factors the shareddbsub-object intoemit_db_json(now used by bothportsandstatus). Also backfills the in-script--help(usage()) forports --jsonandup --wait— the prior two PRs updated the man page/README but notusage().Discipline
docs/design/agent-native.md.tests/status.bats— 10 tests.stopped/foreign/unknownhermetically via a fakess(no real socket); a read-only assertion (status must not create the log dir, unlikeup); db object; per-worktree index/ports; arg validation; completion. Plus an integration test proving a real python server we launch reads asrunning.python -m json.tool) and confirmed the real-serverrunningpath end-to-end.foreign→running, pid-always-null, and not-listening→running— each caught by a distinct test.running(needs a real owned process), covered by the integration job; ~20 lines of headroom over the 99% gate (was 99.84%).usage(). Checksum regenerated.🤖 Generated with Claude Code