Skip to content

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

Merged
tzarebczan merged 5 commits into
tzarebczan:mainfrom
huntharo:feat/agent-removal-review-list
Oct 17, 2026
Merged

tzarebczan merged 5 commits into
tzarebczan:mainfrom
huntharo:feat/agent-removal-review-list

Conversation

@huntharo

@huntharo huntharo commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Fork PR: huntharo#78

Follow-up to #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), the object at the path (device, inode and creation time recorded when the agent asked; something made there since is left alone), protected folders, and the volume. If the volume check changed, the item stays waiting with the new facts. If DiskHound can't read the list of volumes, it can't tell whether another volume is mounted inside, so the item is locked and can only be skipped.

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 synchronous, and main's before-quit flushes a pending one, so a request queued just before quit survives. 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 (unless the volume facts or the file at a path changed).

Scenario Budget
agent-removals-request (20 items) 1 write + rename; 20 a day = 9.6 MB/day with a week of busy history (478 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
agent-removals-quit-pending (quit inside the debounce) 1 write + rename, synchronous
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,295 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 on 4d066a4, and the 11 agent specs again on 88b2cc7:
    • 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 #74. From Update DiskHound's MCP server to SDK 1.32.1 #74, the trailing-space and argument-cap tests now check the review queue, and the declined-dialog tests are gone with the dialog.
  • 88b2cc7 addresses the Codex review: file identity at Remove, failing closed without a volume list, the synchronous quit flush, re-asks that leave a request decided, and gio's creatable shared .Trash.

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.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-15T15:53:34.094065Z 4d066a4 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@tzarebczan

Copy link
Copy Markdown
Owner

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4d066a47ca

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/mcp/removalReview.ts Resolved
Comment thread src/mcp/trashSupport.ts Resolved
Comment thread src/mcp/electronHost.ts Resolved
Comment thread src/mcp/removalQueue.ts Resolved
Comment thread src/mcp/trashSupport.ts Resolved
huntharo and others added 4 commits October 15, 2026 12:07
- Approval leaves alone a file or folder made again at the same path:
  the host records device, inode and creation time when the agent asks,
  and Remove compares them (creation time catches ext4 reusing an inode).
- When the list of volumes can't be read, the item is locked: DiskHound
  can't tell whether another volume is mounted inside, so it removes
  nothing. It can be skipped, and once the volumes read again the item
  comes back with the new facts.
- The review list is written synchronously, and main's before-quit
  flushes it, so a request queued just before quit isn't lost.
- A request whose last waiting item moves to a newer request is marked
  decided, so it ages out like any other. A repeat with new volume facts
  or another file at a path replaces the old item instead of being a
  no-op.
- On Linux, a sticky shared .Trash without the user's folder counts when
  gio can make that folder there.
- An item an agent adds while the review sheet is open starts unticked,
  with a note, so Remove never runs something the user hasn't looked at.
- On Windows, an item that may not fit the Recycle Bin starts unticked:
  Windows deletes what the bin can't hold instead of recycling it.
- A debounce timer that fires during an approval leaves the write to the
  batch's end, so an approval stays one write.
- A path inside another path in the same request is listed under "not
  added" with its parent, instead of vanishing from the result.
- diskhound_status repeats the platform note on why freed space can lag
  after the user removes something, as the old tool results did.
- A failed measurement shows its error in the sheet; small reuse and
  simplification in the waiting counts.
The line read the deleted and moved rows from the pushed list, which
arrives up to 100 ms after the result and also holds items decided in
an earlier approval. On a slow Windows runner it said "Deleted 1: 0 B
free now". The approval's own counts carry the bytes, as the toast uses.
A zero birth time is not a creation time on Linux statx, so identity uses the change time and a reused inode is left alone. Volume facts are read again immediately before each item, and a path that is now a mount point stays locked. Permanent delete does not walk into a directory on another device. Quit waits until an in-flight approval has written its decisions.

@tzarebczan tzarebczan left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The five Codex items stay closed. The three later holes are closed on c0f9749: a zero birth time uses ctime so a reused inode is left alone, volume facts are read again immediately before each item and a path that is now a mount stays locked, permanent delete does not walk onto another device, and quit waits until the approval's decisions are written.

CI is green, including Windows E2E.

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