Skip to content

prose: document ant node dismiss and node status health/eviction output#71

Merged
JimCollinson merged 6 commits into
mainfrom
claude/prose-2026-07-13-cli-node-dismiss
Jul 14, 2026
Merged

prose: document ant node dismiss and node status health/eviction output#71
JimCollinson merged 6 commits into
mainfrom
claude/prose-2026-07-13-cli-node-dismiss

Conversation

@JimCollinson

@JimCollinson JimCollinson commented Jul 13, 2026

Copy link
Copy Markdown
Collaborator

Draft prose PR from the daily upstream-drift sweep. ant-client added a node-management command and expanded the ant node status output; this documents both on the CLI command reference. This revision corrects the default data-directory root in the JSON example.

Upstream

  • ant-client: 95a23be → bcab72a (audited at bcab72ae72f72abcc47bdae1387ebc1deeea6106)

Source artifacts inspected

  • ant-cli/src/commands/node/status.rs, ant-cli/src/commands/node/dismiss.rs
  • ant-core/src/config.rs (data_dir() → Linux ~/.local/share/ant)
  • ant-core/src/node/registry.rs (addservice_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.md only.

Review findings addressed in this revision

  1. Default data_dir root (High)config::data_dir() resolves to ~/.local/share/ant on Linux (config.rs:8,23, test data_dir_ends_with_ant), so the CLI-generated default is <data>/ant/nodes/node-{id}. The example candidate data_dir is 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/node3 and the .../nodes/node-{id} path shape (registry.rs:88, mod.rs:260-266); the audited dismiss output ✓ Dismissed node 3 (node3); reclaimed_bytes framed 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 a candidate is valid, plus one evicted node; total_running: 2, total_stopped: 1); health-null semantics; the dismiss safety warning; field optionality; the outcome-oriented dismiss heading with a **Command:** line; the bcab72a / 2026-07-13 verification stamp; and the one-file scope.

Verification run

  • python3 scripts/sweep_poll.py: status: "ok"; docs/cli/command-reference.md not drifted on this branch.
  • JSON example re-validated with json.loads; candidate data_dir asserted equal to /home/alice/.local/share/ant/nodes/node-2; no share/autonomi residue.
  • Path root cross-checked against config.rs at the pinned SHA.
  • No #### headings; no prohibited words in the additions.
  • markdownlint / link-check: skipped — not installed/configured in-repo.
  • Only docs/cli/command-reference.md changed; no skill body change, so no linked release is included.

Uncertainties
None. Illustrative values (byte counts, timestamps, PIDs, the /home/alice home 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.

claude and others added 6 commits July 13, 2026 09:13
…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
JimCollinson marked this pull request as ready for review July 14, 2026 08:14
@JimCollinson
JimCollinson merged commit fe99127 into main Jul 14, 2026
5 checks passed
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.

2 participants