prose: document ant node dismiss and node status health/eviction output#71
Merged
Merged
Conversation
…tput ant-client added the `ant node dismiss <node_id>` command and folded a fleet-health summary plus node-eviction reporting into `ant node status`. Document both on the CLI command reference and refresh its verification stamp to the audited head SHA. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018k8QXTGkcfKXvycW1CAwRn
Address review of the CLI command reference: - Qualify `health` null and the terminal fleet-health summary: null also occurs when the daemon is running but the snapshot cannot be retrieved. - Correct `ant node dismiss` semantics: not evicted-only. Daemon running removes any non-running node (and refuses a running one); daemon stopped removes the registry entry directly and does not stop a running process. - Add a full JSON schema and a valid example for `ant --json node status`, with actual lowercase wire values for statuses and health levels and verified total_running/total_stopped count semantics. - Explain automatic eviction (stops node, deletes data dir, retains the registry record) and the dismiss-then-add recovery path. - Replace the inline-code dismiss heading with an outcome-oriented heading plus the literal `ant node dismiss <NODE_ID>` syntax, matching the reference-page convention. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018k8QXTGkcfKXvycW1CAwRn
…very Address remaining review of the CLI command reference: - Rebuild the `ant --json node status` example to a source-consistent state: two running nodes sharing a partition plus one evicted node, so the disk-space check can legitimately name a candidate (source only emits a candidate when at least two running nodes share a partition and the level is not green). Totals, health, candidate, and the summary/reason strings now match the health and eviction `format!` templates in ant-core. - Correct eviction and recovery guidance: eviction attempts cleanup; deletion can fail, leaving an Evicted record with reclaimed_bytes 0 and a manual-cleanup reason. Dismissing removes only the registry entry and does not reclaim space; free space manually when cleanup did not, and add a replacement node only after capacity is available. - Mark candidate/partition/available_bytes/eviction_threshold_bytes as optional and omitted when not applicable; describe the supported check type directly without time-relative wording. - behaviour -> behavior; "currently running" -> "running". - Add audited expected output for `ant node dismiss 3`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018k8QXTGkcfKXvycW1CAwRn
…me the node daemon
Address review of the CLI command reference:
- Use the CLI-generated identifiers in the status JSON example and dismiss
output: service names node1/node2/node3 and the default data directory
.../nodes/node-2 (ant-core registry assigns node{id}; node_data_dir builds
<data>/nodes/node-{id}). Dismiss output is now the audited
"Dismissed node 3 (node3)".
- Clarify that reclaimed_bytes is the recorded pre-deletion size estimate for
the cleanup attempt, not a measurement of free space now available; direct
readers to check actual free disk space before adding a replacement node.
- Replace the ambiguous bare "the daemon" with "node daemon" in the new prose
to name the interface explicitly, matching the node daemon sections.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018k8QXTGkcfKXvycW1CAwRn
config::data_dir() resolves to ~/.local/share/ant on Linux (config.rs), so the
CLI-generated default node data directory is <data>/ant/nodes/node-{id}. Fix the
example candidate path from .../autonomi/nodes/node-2 to .../ant/nodes/node-2.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018k8QXTGkcfKXvycW1CAwRn
JimCollinson
marked this pull request as ready for review
July 14, 2026 08:14
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.
Draft prose PR from the daily upstream-drift sweep.
ant-clientadded a node-management command and expanded theant node statusoutput; this documents both on the CLI command reference. This revision corrects the default data-directory root in the JSON example.Upstream
95a23be → bcab72a(audited atbcab72ae72f72abcc47bdae1387ebc1deeea6106)Source artifacts inspected
ant-cli/src/commands/node/status.rs,ant-cli/src/commands/node/dismiss.rsant-core/src/config.rs(data_dir()→ Linux~/.local/share/ant)ant-core/src/node/registry.rs(add→service_name = format!("node{id}")),ant-core/src/node/mod.rs(node_data_dir→<data>/nodes/node-{id})ant-core/src/node/types.rs,ant-core/src/node/daemon/health.rs,ant-core/src/node/daemon/disk.rs,ant-core/src/node/daemon/supervisor.rs(evict_node)Files changed in this PR
docs/cli/command-reference.mdonly.Review findings addressed in this revision
data_dirroot (High) —config::data_dir()resolves to~/.local/share/anton Linux (config.rs:8,23, testdata_dir_ends_with_ant), so the CLI-generated default is<data>/ant/nodes/node-{id}. The example candidatedata_diris now/home/alice/.local/share/ant/nodes/node-2(corrected from.../autonomi/nodes/node-2).Earlier rounds (still in place): CLI-generated identifiers
node1/node2/node3and the.../nodes/node-{id}path shape (registry.rs:88,mod.rs:260-266); the audited dismiss output✓ Dismissed node 3 (node3);reclaimed_bytesframed as the recorded pre-deletion estimate (not proof of current free space), with readers directed to check actual free disk space before adding a replacement; "node daemon" terminology throughout the new prose; the source-consistent example state (two running nodes sharing a partition so acandidateis valid, plus one evicted node;total_running: 2,total_stopped: 1); health-nullsemantics; the dismiss safety warning; field optionality; the outcome-oriented dismiss heading with a**Command:**line; thebcab72a/2026-07-13verification stamp; and the one-file scope.Verification run
python3 scripts/sweep_poll.py:status: "ok";docs/cli/command-reference.mdnot drifted on this branch.json.loads; candidatedata_dirasserted equal to/home/alice/.local/share/ant/nodes/node-2; noshare/autonomiresidue.config.rsat the pinned SHA.####headings; no prohibited words in the additions.docs/cli/command-reference.mdchanged; no skill body change, so no linked release is included.Uncertainties
None. Illustrative values (byte counts, timestamps, PIDs, the
/home/alicehome prefix) are examples; the data-root segment (ant), identifiers, path shape, field names, types, wire values, count semantics, and the reason/summary/output strings are taken from source.