Skip to content

feat: add ataegina status [--json] (read-only liveness)#29

Merged
noahhyden merged 1 commit into
mainfrom
feat/status-json
Jul 19, 2026
Merged

feat: add ataegina status [--json] (read-only liveness)#29
noahhyden merged 1 commit into
mainfrom
feat/status-json

Conversation

@noahhyden

Copy link
Copy Markdown
Owner

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). status is that query.

Per surface it reports:

  • running — a live server ataegina launched holds the port
  • foreign — 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 port

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:

{"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 shared db sub-object into emit_db_json (now used by both ports and status). Also backfills the in-script --help (usage()) for ports --json and up --wait — the prior two PRs updated the man page/README but not usage().

Discipline

  • Spec: docs/design/agent-native.md.
  • Tests-first: tests/status.bats — 10 tests. stopped/foreign/unknown hermetically via a fake ss (no real socket); a read-only assertion (status must not create the log dir, unlike up); db object; per-worktree index/ports; arg validation; completion. Plus an integration test proving a real python server we launch reads as running.
  • Live verification: drove the binary for stopped (human + python -m json.tool) and confirmed the real-server running path end-to-end.
  • Mutation red-teaming: swap foreignrunning, pid-always-null, and not-listening→running — each caught by a distinct test.
  • Coverage: the only non-hermetic branch is running (needs a real owned process), covered by the integration job; ~20 lines of headroom over the 99% gate (was 99.84%).
  • Docs: README table, man page, CHANGELOG, bash+zsh completion, and usage(). Checksum regenerated.

🤖 Generated with Claude Code

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>
@noahhyden
noahhyden merged commit 6a1a7be into main Jul 19, 2026
8 checks passed
@noahhyden
noahhyden deleted the feat/status-json branch July 19, 2026 23:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant