disk_actions

How it works

Both actions are reads and change nothing. smart lists the physical drives the OS exposes and reports each one’s model, transport (bus) and media type; on Windows, NVMe drives also answer a SMART/Health query whose critical-warning flags become a health verdict, with the raw wear and spare-capacity percentages alongside. volumes lists logical volumes and, for each, the physical drive that backs it and the mount points or drive letters it serves. On Windows smart probes PhysicalDrive0 to PhysicalDrive63; on macOS both actions walk the IOKit registry; Linux returns a single placeholder row and an UNAVAILABLE status.

volumes is deliberately not a third volume inventory: hardware.disks already lists physical devices and filesystem_posture.mounts already lists mounts. This action carries only the join between them, which is what lets a failing-drive alert name the drive letters or mount points it affects. Where a mechanism is unavailable (Linux) or is reachable only through a private OS interface (macOS health), the leg says so in its result rather than guessing.

partitions and topology read nothing yet: on every OS each answers with exactly one status|<action>|unsupported|<os>:planned row from the shared planned-leg reporter (agents/shared/planned_leg.hpp), until their leg PRs land (partitions on every OS; topology on Linux for LVM/md/multipath and on macOS for APFS containers; Windows has no topology source ruled yet).

flowchart LR
  OP["Operator or workflow"] --> SRV["Server: Inventory Read, concurrency per device"]
  SRV -- "gRPC mTLS" --> HOST["Agent plugin host"] --> EX["disk_actions.execute"]
  EX --> WIN["Windows: storage IOCTLs on drive and volume handles"]
  EX --> MAC["macOS: IOKit registry reads and getmntinfo_r_np"]
  EX --> LIN["Linux: placeholder row and UNAVAILABLE"]
  WIN & MAC & LIN --> ROWS["Pipe rows and typed result status"]
  ROWS -- "CommandResponse" --> RS[("ResponseStore")]
  RS --> API["REST /api/responses"]

What you can decide with it

How health is derived. For an NVMe drive the plugin reads the SMART/Health log page and looks only at its critical-warning byte. If bit 0 (available spare below threshold) or bit 2 (reliability degraded) is set, health is failing. If any other bit is set (temperature, media read-only, volatile-memory backup failed, or a bit the plugin does not know), it is warning. If no bit is set it is ok. pct_used and spare_pct are reported but never change the verdict, so a drive at 100 percent or more of its rated endurance with no warning flag still reads ok; set your own wear threshold on pct_used if you want one.

What a missing failing does and does not prove. Only Windows NVMe drives are ever judged. SATA and USB drives, virtual machine disks and every drive on macOS report unknown, and Linux reports unsupported, so the absence of a failing row says nothing about those devices. Alert on failing and warning, and track the unknown and unsupported rows separately to see which devices the fleet cannot judge. ok means the drive reported no critical warning at read time, not that it will not fail.

Diagrams

From a drive to a health value

flowchart TD
  S["smart: one row per drive"] --> O{"Which OS?"}
  O -- "Linux" --> L["Placeholder row, health unsupported"]
  O -- "macOS" --> M["health unknown, detail says whether the device advertises SMART"]
  O -- "Windows" --> B{"Is the bus NVMe?"}
  B -- "no: SATA, USB, SAS, virtual or unknown" --> U1["health unknown, no wear figures"]
  B -- "yes" --> P{"Did the SMART/Health log page come back?"}
  P -- "no" --> U2["health unknown, CONSTRAINED windows:nvme_health"]
  P -- "yes" --> C{"Critical-warning byte"}
  C -- "bit 0 or bit 2 set" --> F["failing"]
  C -- "any other bit set" --> W["warning"]
  C -- "no bit set" --> OK["ok"]

Wear (pct_used) and spare (spare_pct) come from the same log page and are printed on the row, but the decision uses the critical-warning byte alone. Every path that cannot read the page ends in unknown, never in ok.

How volumes joins volumes to drives

flowchart TD
  WV["Windows: volume GUID path from FindFirstVolumeW"] --> WM["Drive letters and mount folders for the volume"]
  WV --> WE["Disk extents of the volume"]
  WE --> WD["PhysicalDriveN, several when the volume is spanned"]
  MP["macOS: IOMedia partition, for example disk3s1"] --> MW["Walk the IOKit providers to the first whole IOMedia"]
  MW --> MD["Physical disk, for example disk0, not the synthesized APFS container"]
  MP --> MM["Mount points matched by BSD name through getmntinfo_r_np"]
  WM & WD --> ROW["volume row: volume, mount_points, device, fstype, total_bytes"]
  MM & MD --> ROW

On Windows the physical drive comes from the volume’s disk extents, so a spanned or striped volume names every drive it touches. On macOS the drive comes from walking the IOKit provider chain, because trimming the BSD name would stop at a synthesized APFS container that is not a physical device. A whole disk that serves no mount point is left out, since it carries no join.

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• partitions / Windows — not read yet: one unsupported status row, windows:planned
• partitions / macOS — not read yet: one unsupported status row, macos:planned
• partitions / Linux — not read yet: one unsupported status row, linux:planned
• smart / Windows — the device handle is opened with zero access rights, which an unprivileged service account may do; wear and spare figures come from the NVMe SMART/Health log and are therefore reported only for NVMe devices, with SATA and USB drives reporting identity and media type but ‘unknown’ health
• smart / macOS — reports device identity (model, medium type) and whether the device advertises NVMe SMART, but NOT the health attributes themselves: wear, available spare and the critical-warning flag are reachable only through Apple’s private IONVMeSMARTUserClient selector interface, which is undocumented and version-fragile, so health reports ‘unknown’ on this platform rather than a guess
• smart / Linux — not implemented in this change: no mechanism could be bound, because every Linux host available for the spike exposed virtualised disks only (WSL2 reports four ‘Virtual Disk’ SCSI nodes and no /dev/nvme* character devices), and shipping an NVME_IOCTL_ADMIN_CMD path written from documentation but never exercised is exactly how a dead leg reaches production. Binding it needs a Linux host with real storage, or a VM with disk passthrough; neither was reachable when this shipped
• topology / Windows — not read yet: one unsupported status row, windows:planned
• topology / macOS — not read yet: one unsupported status row, macos:planned
• topology / Linux — not read yet: one unsupported status row, linux:planned
• volumes / Windows — maps volumes to the physical drives backing them; a volume spanning several drives (a spanned or striped dynamic volume) reports every drive it touches, and a volume with no assigned drive letter or mount point reports ’-’ for mount points rather than being omitted
• volumes / macOS — one row per IOMedia object, keyed on that object’s BSD name, carrying the physical whole disk that backs it and any mount points it serves; the physical disk is resolved by walking the IOKit provider chain, so a volume inside a synthesized APFS container correctly reports the underlying drive rather than the container; a media object that maps nothing — a whole disk serving no mount point — is omitted, because this action carries only the physical-to-logical join and such a row has no join to carry
• volumes / Linux — not implemented in this change: the physical-to-logical join is only meaningful alongside a bound smart leg, and the Linux smart leg is deferred with it

Privileges and prerequisites

The two planned actions read nothing on any OS and need no grant. No external binaries, no subprocesses, no network access. Do not change the Windows drive open to GENERIC_READ: that breaks the leg under an unprivileged account.

Data contract

Inputs

No action takes parameters.

Outputs

Pipe-delimited rows, one per drive or volume. Field 0 is a literal discriminator (smart or volume; the planned actions answer one status row, status|<action>|unsupported|<os>:planned, and their final partition and topology row schemas are declared in disk_actions_legs.hpp) that precedes the columns below; every row of a kind has the same field count, with - where a value is inapplicable or was not read. - never means zero, and a macOS smart row always has - for pct_used and spare_pct. Every free-text field (device, model, volume, mount points, filesystem, detail) passes through safe_output_field, which rewrites \ as /; bus, media and health are fixed vocabularies and the numeric fields are digits, so they need no escaping. Windows volume GUID paths read //?/Volume{…}/ and drive letters C:/. A leg that finds nothing still emits one placeholder row so zero rows can never be misread as “no disks”: a smart placeholder carries health=unsupported, a volume placeholder carries volume=-, and both are accompanied by a typed status, which is the authoritative signal.

crossplatform.storage.partitions — row_kind|disk|partition|size_bytes|type|mount_points|detail

crossplatform.storage.smart — device|model|bus|media|health|pct_used|spare_pct|detail

crossplatform.storage.topology — row_kind|kind|name|uuid|members|detail

crossplatform.storage.volumes — volume|mount_points|device|fstype|total_bytes|detail

Result status

Surfaced as plugin_result_status on the command response.

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response, land in the ResponseStore (90-day default retention), and are queryable at /api/responses/{id}, aggregatable (smart by health, volumes by device) and exportable as JSON from /api/responses/{id}/export.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics. Nothing runs on a schedule.
• Sensitivity. Rows identify hardware, not people: drive models, volume GUIDs and BSD names are device-level identifiers (asset-inventory class, like device_ci), and nothing in them names a user, a file or an application.
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("crossplatform.storage.smart"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.
• Siblings: device.hardware.disks (physical inventory), crossplatform.storage.mounts (logical mounts, true filesystem capacity), crossplatform.storage.free.

Sample output

Windows — captured: windows Windows 11 Pro 10.0.26200 · bare-metal · 2026-09-07 · interactive user (elevated) · leg-hash 3abb2323b0be

== action=smart
smart|PhysicalDrive0|Samsung SSD 970 EVO Plus 250GB|nvme|ssd|ok|5|100|-
smart|PhysicalDrive1|Samsung SSD 970 EVO Plus 1TB|nvme|ssd|ok|1|100|-
[result_status] UNDECLARED / UNKNOWN

== action=volumes
volume|//?/Volume{0a35801e-3f40-4114-a073-3d7ea1dd7664}/|-|PhysicalDrive0|NTFS|524288000|-
volume|//?/Volume{c9a5f911-4689-41b2-b774-5b0e25b60e10}/|C:/|PhysicalDrive0|NTFS|248158093312|-
volume|//?/Volume{daa59534-884a-4ce4-8fc8-4244f7bbe7ae}/|-|PhysicalDrive0|NTFS|967835648|-
volume|//?/Volume{785383ef-b682-41d9-9b28-27c4b8882d65}/|D:/|PhysicalDrive1|NTFS|1000187363328|-
volume|//?/Volume{b188886e-39bb-4915-a893-d61a3ca3c707}/|-|PhysicalDrive0|FAT32|272629760|-
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 · leg-hash 3abb2323b0be

== action=smart
smart|disk0|APPLE SSD AP0512Z|nvme|ssd|unknown|-|-|device advertises SMART; health attributes are not read on macOS (they require Apple's private IONVMeSMARTUserClient interface)
[result_status] CONSTRAINED / PARTIAL / macos:iokit:health_unread

== action=volumes
volume|disk0s1|-|disk0|-|524288000|-
volume|disk0s3|-|disk0|-|5368664064|-
volume|disk0s2|-|disk0|-|494384795648|-
volume|disk1|-|disk0|-|524288000|-
volume|disk2|-|disk0|-|5368664064|-
volume|disk3|-|disk0|-|494384795648|-
volume|disk1s1|/System/Volumes/iSCPreboot|disk0|apfs|524288000|-
volume|disk1s4|-|disk0|-|524288000|-
volume|disk1s2|/System/Volumes/xarts|disk0|apfs|524288000|-
volume|disk1s3|/System/Volumes/Hardware|disk0|apfs|524288000|-
volume|disk2s1|-|disk0|-|5368664064|-
volume|disk2s2|-|disk0|-|5368664064|-
… 12 of 19 rows shown
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash 3abb2323b0be

== action=smart
smart|-|-|unknown|unknown|unsupported|-|-|drive health is not implemented on Linux in this release; no mechanism was bound against real hardware
[result_status] UNAVAILABLE / PARTIAL / linux:smart

== action=volumes
volume|-|-|-|-|-|physical-to-logical volume mapping is not implemented on Linux in this release; it ships with the smart leg it exists to support
[result_status] UNAVAILABLE / PARTIAL / linux:volumes

Caveats and known gaps

1. health is the drive’s own critical-warning flag, and only Windows NVMe drives have one. Wear and spare percentages never feed the verdict, so a heavily worn drive with no warning flag reads ok. SATA, USB and virtual machine disks report unknown because IOCTL_STORAGE_PREDICT_FAILURE is deliberately not used as a fallback (it fails on NVMe), so a missing failing is not evidence of a healthy drive.
2. macOS reports identity only. health is always unknown and pct_used and spare_pct are always -, because the attributes sit behind Apple’s private IONVMeSMARTUserClient interface, which the plugin does not use; every macOS smart run is also CONSTRAINED with macos:iokit:health_unread.
3. Linux is declared, not implemented. Both actions return one placeholder row (health=unsupported, or volume=-) and UNAVAILABLE, and the definitions target Windows and macOS only. A Linux leg would bind the NVMe admin get-log-page call, whose log page the Windows decoder already reads, and has not been measured on real storage. partitions and topology are advertised planned on all three OSes, though Windows has no LVM/md topology source and macOS has no multipath; the leg PRs move such legs to a typed unsupported with a reason, so until then <os>:planned means “not read”, never “this host has no partitions”.
4. No deadline on Windows device I/O. DeviceIoControl is synchronous with no timeout, so a wedged device or a disconnected network LUN can park the dispatch worker that called it. The 64-drive probe limit and suppression of the not-ready-volume dialog bound the ordinary case, not a driver that never returns.
5. total_bytes is media capacity, not filesystem capacity. On macOS every APFS volume in a container reports the container’s size, and unmounted members and containers appear with - mount points; on Windows it is the sum of the volume’s disk extents. Use crossplatform.storage.mounts for real capacity.

Source and tests

• Plugin: agents/plugins/disk_actions/src/disk_actions_legs.hpp · agents/plugins/disk_actions/src/disk_actions_linux.cpp · agents/plugins/disk_actions/src/disk_actions_macos.cpp · agents/plugins/disk_actions/src/disk_actions_parsers.hpp · agents/plugins/disk_actions/src/disk_actions_plugin.cpp · agents/plugins/disk_actions/src/disk_actions_win.cpp
• Definitions: content/definitions/disk_actions.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_disk_actions.hpp
• Tests: tests/test_disk_actions_definition.py · tests/unit/test_disk_actions_local_dispatcher.cpp
• Privilege row: docs/agent-privilege-model.md