Skip to content

Queue agents' removals on a review list in DiskHound - #78

Closed
huntharo wants to merge 12 commits into
mainfrom
feat/agent-removal-review-list
Closed

huntharo wants to merge 12 commits into
mainfrom
feat/agent-removal-review-list

Conversation

@huntharo

@huntharo huntharo commented Oct 14, 2026 •

Copy link
Copy Markdown
Owner

Upstream PR: tzarebczan#75

Follow-up to tzarebczan#71 (AI agents over MCP). Agents' Trash and delete requests no longer pop a native dialog that takes focus and blocks the call. They go on a review list, and the user approves it in DiskHound when they're back.

Review list

Design: AI Agents (MCP) - Connect & Manage, turn 6 (build list rows AE–AG).

What the agent sees

  • diskhound_move_to_trash and diskhound_delete_permanently return as soon as the items are on the list: "Added 3 items (2.4 GB) to DiskHound's review list. Nothing has moved yet." Each item lists its size and whether the Trash can take it. Anything refused is listed with the reason. The text never says anything was removed.
  • diskhound_status reports what is waiting and how recent requests were decided: moved, moved to the Trash instead of deleted, deleted, partly removed, skipped, already gone, not allowed, or failed, with the reason for each.
  • A request outlives the agent's connection and a DiskHound restart. Role gating is unchanged: Operator asks for the Trash, Admin for a delete.

What the user sees

  • The header pill turns amber and counts waiting items. The popover, the tray menu ("Review agent requests (N)…") and Settings → AI Agents open the sheet. Nothing comes to the front on its own.
  • The sheet groups items by agent and reason. Each row has a checkbox (unticked = skipped), a Trash/Delete switch on delete requests where the Trash can take the item, and its size. "Measure what they free together" runs measureRemoval on the ticked set (not on Windows). The button says what it will do ("Move 3 to Trash · Delete 1").
  • After Remove, each row shows its result from the disk, and a toast sums it up.
  • Settings has "Confirm agents' removals: In DiskHound". The in-chat option is listed as "not yet": it needs MCP elicitation, stateful HTTP sessions, and the stdio helper relaying the question.

Trash support (src/mcp/trashSupport.ts)

Checked when the agent asks, and again on Remove:

  • macOS: /sbin/mount. Network volumes have no Trash, and read-only volumes are refused. Paths are matched by device. On macOS 26 the sealed system volume and the Data volume report the same device, so the writable entry wins (E2E caught this).
  • Linux: /proc/self/mountinfo with gio's rules. On the home device, the home Trash. Otherwise a usable .Trash/<uid> (sticky, not a symlink) or .Trash-<uid>, or a writable top where gio can make one. System mounts and x-gvfs-notrash have none.
  • Windows: one PowerShell call. Network and removable drives have no Recycle Bin. An item bigger than the drive's bin (MaxCapacity, or the 5% default) is "no", because Windows would delete it permanently. NukeOnDelete drives say so too.
  • A folder with another volume mounted inside is never shown as moving to the Trash. It starts unticked and names the volume. If ticked, DiskHound removes the largest subtrees around the mount and leaves the volume alone, for the Trash and for a delete. A path that is itself a mount point is refused.

On Remove, each item is checked again: the session (revoked → refused), its current role, the path's real location (changed → refused), protected folders, and the volume. If the volume check changed, the item stays waiting with the new facts.

One deviation from the design: 6d offers Delete only on delete requests. The task asked for "skip it, or delete that part permanently (if the role allows it)". So a Trash request on a volume without a Trash offers Delete, unticked, when the session's role grants files.delete. Trash requests are never turned into deletes otherwise.

Persistence and budgets

agent-removals.json in userData (0600). It is written atomically when an agent asks or the user decides, never on a timer. Writes are debounced at 500 ms and flushed at quit, and an approval's decisions are held and written once. Decided requests are kept for a week (at most 50). At most 500 items wait at once. An agent repeating a waiting request writes nothing.

Scenario Budget
agent-removals-request (20 items) 1 write + rename; 20 a day = 8.5 MB/day with a week of busy history (426 KB file)
agent-removals-burst (5 requests) 1 write + rename
agent-removals-approve (40 items) 1 write + rename
agent-removals-repeat (same request ×20) 0
agent-removals-load / -quit-clean 1 read on first use / 0
renderer-agent-removals-browse (pill → popover → sheet ×3, untick, switch) 0 IPC, 0 reads, 0 processes
renderer-agent-removals-approve (4 run, 1 skipped) 1 IPC; 1 policy read, 13 lstats, 1 unlink, 1 write + rename, 1 crash.log append

The same at the default and the 1-minute monitoring interval. The folders agents may never remove now resolve once per run, not on every request.

Scaling tests (N vs 8N): queue add/list, approve, removalUnits, and the sheet's grouping.

Docs

docs/mcp.md ("You approve every removal in DiskHound", with a new screenshot), skills/diskhound-free-up-space/SKILL.md (tell the user it's waiting; read diskhound_status before reporting), README, and e2e/AGENTS.md.

Testing

  • bun run test: 1,288 passed. bunx tsc --noEmit is clean.
  • New unit tests: removalQueue, trashSupport (macOS, Linux and Windows tables), removalReview (re-checks, revoked and lowered sessions, partial removal around a mount), and the scaling tests.
  • E2E (macOS, locally, 16 of 16 in agents.spec.ts, stdio-agent.spec.ts and shared-storage.spec.ts):
    • an Operator's Trash request approved from the sheet;
    • an Admin's three deletes: one unticked, one switched to the Trash, one deleted;
    • a request surviving the stdio agent hanging up;
    • a real volume mounted inside a folder (hdiutil attach -mountpoint on macOS, sudo -n mount -t tmpfs on Linux, skipped on Windows): unticked, not shown as moving to the Trash, and on approval the volume's contents stay.
  • stubTrash now records any native dialog, and the specs expect none.
  • Fork CI passed on Linux, Windows and macOS (unit, E2E, Rust) before the rebase onto Update DiskHound's MCP server to SDK 1.32.1 tzarebczan/diskhound#74. From Update DiskHound's MCP server to SDK 1.32.1 tzarebczan/diskhound#74, the trailing-space and argument-cap tests now check the review queue, and the declined-dialog tests are gone with the dialog.

tzarebczan and others added 12 commits October 14, 2026 17:19
Record 0 only holds the first $DATA run list once $MFT spills into
extension records. Read those records from the runs already in hand,
append the rest in starting-VCN order, and warn on stderr when the
joined map is still short of MftValidDataLength.
A non-resident $ATTRIBUTE_LIST is read in whole sectors, and only the
initialized prefix is parsed. A failed list or extension read warns and
continues with the runs already in hand.
A 1 MiB cap dropped every extension record past the prefix and the
scan still returned that partial map. Size the read from the list's
initialized length and its own runs. Above 32 MiB, keep record 0 and
warn instead of parsing a prefix.
… load

A non-resident list whose runs stop short of its initialized length was
parsed as a prefix, so later $DATA extension records disappeared. Keep
record 0 and warn instead. Rebuild the run map before each extension
read so an in-order chain is loaded in one pass.
Follow $MFT $ATTRIBUTE_LIST so fragmented MFT scans read the full table
SDK 1.32 accepts a tools/call or prompts/get that omits arguments, and
caps how many elements one call may carry. A registration's redirect
has to be an http loopback URL. Unapproved clients stay in memory and
are written only after the user approves.
Approving 256 clients and then choosing Forget revoked left those
records in the listener until the next launch, so a new registration
was refused. Drop forgotten records when the cap is full. A revoked
session still holds its slot, and a client that still has a session stays.
The stdio helper treated DiskHound's public OAuth name as proof it owned
port 51735, so another account could bind that port and collect a saved
token. It now requires an HMAC of a fresh nonce against the mode-0600
listener key, and the key itself is never sent.

agentPath no longer trims. A trailing space is part of the filename, and
the confirm dialog was being shown a different path.
A proof from an earlier call stayed valid, so the next request could
hand the bearer to whoever had since bound port 51735. The helper now
checks a fresh HMAC on the same connection that carries the token, and
it does that again for every request.

A connect failure before that POST still answers initialize locally and
keeps the saved token. A failure after the POST is reported as unknown.
The suite redirects HOME so the app does not write the runner's data
directory. The listener key is in that home, and the helper was still
looking in the runner's, so the approval window never opened.
Update DiskHound's MCP server to SDK 1.32.1
diskhound_move_to_trash and diskhound_delete_permanently no longer show a
native dialog that takes focus and blocks the call. They add items to a
review list and return at once, saying per item what was asked, its size,
and whether the Trash can take it. Nothing is removed until the user
approves the list in DiskHound, and diskhound_status reports what was
moved, deleted, skipped, refused or failed.

The list is agent-removals.json in userData: written only when an agent
asks or the user decides, debounced, atomic, and flushed at quit. A
request outlives the agent's connection and a restart. An agent repeating
a waiting request writes nothing, and at most 500 items wait at once.

The header pill turns amber and counts waiting items; the popover, tray
menu and Settings open the review sheet. It groups items by agent and
reason, with a checkbox per item, a delete-to-Trash switch, and what the
ticked items free together from the removal measurement. The list comes
with the agent snapshot, so browsing it reads nothing.

Before offering the Trash, DiskHound checks each item's volume: macOS and
Linux mount tables (gio's .Trash rules on Linux), and on Windows the
drive type and Recycle Bin size. A folder with another volume mounted
inside starts unticked, and removing it stops at the mount, for the Trash
and for a delete. On approval every item is checked again: the session
and its role, the path's real location, protected folders, and the
volume.

Settings has the "Confirm agents' removals" setting, with only
"In DiskHound" available for now.
@huntharo

Copy link
Copy Markdown
Owner Author

Superseded by tzarebczan#75

@huntharo huntharo closed this Oct 15, 2026
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