feat(workspace): add configurable HAPI Recycle Bin for deleted files

[techotaku39]

Problem / Motivation

HAPI's session Files → Directories view and file preview currently support browsing, reading, copying paths, and downloading files, but they do not provide a recoverable delete action.

The existing upload/delete endpoint only removes temporary uploaded attachments; it is not intended for workspace files. When using HAPI remotely from a phone or browser, deleting a file requires returning to the terminal, and permanent deletion creates an unnecessary risk of accidental data loss.

Proposal

Add a machine-local HAPI Recycle Bin, based on the Recycle Bin design described in #1176.

Normal file deletion should move the item into the HAPI Recycle Bin instead of permanently removing it. The default retention period should be 30 days and configurable through the HAPI configuration file.

The Recycle Bin should be a virtual HAPI-managed surface, not a normal directory exposed inside the workspace tree.

Initial scope

The initial implementation focuses on moving individual files from the file preview into a machine-local HAPI Recycle Bin, then listing, restoring, and permanently deleting them.

Directory deletion, batch operations, and general copy/move workflows are follow-up features and are not part of this implementation. The implementation may introduce reusable Runner-side file-operation primitives so these future features can build on the same authorization, locking, and task model.

Proposed UX

• Add a Move to Recycle Bin action to the file preview toolbar.
• The trash icon in the file preview should perform the move action; it should not navigate to the Recycle Bin.
• Add a separate Recycle Bin button near the file browser toolbar, next to actions such as search, sorting, and refresh.
• The Recycle Bin button opens a machine-scoped Recycle Bin view and may display the number of deleted items.
• Before moving an item, show a confirmation dialog containing:
  • the full original path;
  • the machine/workspace scope;
  • the effective retention period;
  • an explicit statement that the item can be restored before expiration.
• After a successful move, return to the file list or preview origin and refresh directory, search, and Git status data.
• The operation must not automatically stage, commit, or otherwise modify Git history.

Recycle Bin behavior

Each recycle entry should retain enough metadata to identify and restore the item:

• original authorized path;
• deletion time;
• file type;
• size;
• unique recycle entry ID;
• expiration time.

The Recycle Bin should support:

• listing deleted entries;
• read-only preview where practical;
• restoring to the original authorized path;
• restoring to another authorized destination;
• explicit conflict handling when the original path is occupied;
• permanently deleting a selected entry;
• emptying the entire Recycle Bin after an explicit confirmation;
• automatic cleanup of expired entries.

The effective retention period must be read from configuration rather than hard-coded in the Web UI. The UI should display the actual configured value.

Security requirements

All operations must be authorized by the Runner and bound to legitimate HAPI scopes:

• Session Repository paths must be derived from the authenticated session rather than trusted from an arbitrary client path.
• Workspace paths must remain inside the configured Workspace Roots.
• Paths must be canonicalized and revalidated at the point of use.
• Symlink escapes must be rejected.
• .git metadata must not become accessible through the Recycle Bin or generic file operations.
• Concurrent Agent/user changes must not silently overwrite or delete unrelated data.
• Side-effecting operations must not replay automatically after Runner restart.
• The Hub must not persist file contents or sensitive host paths beyond the metadata required for the operation.

Acceptance criteria

• A user can move an individual file from the file preview into the HAPI Recycle Bin.
• The default retention period is 30 days and can be changed through configuration.
• The effective retention period is shown in the confirmation dialog or Recycle Bin view.
• The Recycle Bin is available through a dedicated virtual UI surface.
• Deleted entries can be restored before expiration.
• Restore conflicts require an explicit user choice.
• Permanent deletion and empty-bin actions require confirmation.
• Expired entries are cleaned up automatically.
• Out-of-scope paths, symlink escapes, and protected .git paths are rejected.
• Directory/search/Git state is refreshed after a successful operation.
• Focused Runner, Hub, shared-contract, and Web tests cover deletion, restoration, expiration, conflicts, and authorization boundaries.

Follow-up work

Copying and moving files or directories, batch operations, and a full Destination Picker should be tracked as separate follow-up issues and PRs.

Related Issues / PRs

• Refs Spec: 完成 HAPI Git、文件与 Managed Provider Profile 管理闭环 #1176 — HAPI management specification and Recycle Bin design.
• Refs feat(workspace): add scoped file and Git controls #1092 — Open PR proposing workspace file operations, including permanent delete, move, and copy.

This issue proposes recoverable deletion as a separate behavior. It does not assume that PR #1092 has been merged, and it does not silently change that PR's permanent-delete proposal.

[github-actions]

Thanks — this is a well-scoped standalone feature request. No HAPI Recycle Bin implementation was found in the current source.

The existing upload-delete flow should remain separate: the Hub resolves an authenticated active session, and the Runner handler only accepts paths inside that session upload directory before calling rm. It is not a workspace-file operation.

The repository already has a machine-scoped Hub → Runner RPC path and a canonical workspace-root policy. That is the appropriate existing boundary to extend for machine-local recycle entry lifecycle. One security gap to account for: the current session validatePath helper performs lexical resolve containment only; it does not canonicalize symlinks. Recycle side effects therefore need point-of-use canonicalization/revalidation and an explicit .git deny rule rather than relying on that helper alone. I did not find an existing generic .git protection rule or recycle-bin contract.

The Web surfaces also match the proposed insertion points: the file preview toolbar currently exposes copy-path and download actions, while the Files page toolbar contains search/sort and refresh.

Relevant code:

• web/src/routes/sessions/file.tsx:372 - file preview action toolbar; currently copy path and download only.
• web/src/routes/sessions/files.tsx:498 - Files toolbar with search/sort and refresh controls.
• hub/src/web/routes/sessions.ts:323 - upload deletion endpoint, scoped through an active session.
• cli/src/modules/common/handlers/uploads.ts:261 - validates the upload-directory boundary, then permanently removes the upload.
• shared/src/rpcMethods.ts:1 - current RPC registry; no recycle list/move/restore/purge methods exist.
• cli/src/api/machinePathPolicy.ts:38 - machine-scoped workspace-root policy with realpath canonicalization.
• cli/src/modules/common/pathSecurity.ts:14 - session path validation is lexical containment only.
• cli/src/persistence.ts:14 - Runner-local settings schema; no retention setting exists today.

Need more info:

• Should retention be stored per Runner in $HAPI_HOME/settings.json, or centrally in Hub settings?
• For restore conflicts, which explicit choices are in initial scope: cancel, overwrite, and/or restore with a new name?
• For “restore to another destination,” should the initial UI accept a manually entered authorized path, or should that operation be deferred with the Destination Picker follow-up?

---

HAPI Bot

[techotaku39]

Thanks for the review. The initial-scope decisions are:

1. Retention configuration belongs to the Runner that owns the files, in that Runner's $HAPI_HOME/settings.json (for example, recycleBinRetentionDays, defaulting to 30). It should not be a single Hub-global value, because different Runner machines may have different storage policies. The Hub may later expose an authenticated UI/RPC to update the Runner setting, but the Runner remains the source of truth and performs expiry cleanup.

2. Restore conflicts should support all three choices:

   • cancel and leave the recycle entry untouched;
   • overwrite the existing target after an explicit confirmation;
   • restore with a new name, using a generated suffix such as (restored) and allowing the user to edit it where practical.

3. The initial UI should restore to the original authorized path only. If that path is occupied, the three conflict choices above apply. Restoring to another authorized directory can be deferred to the follow-up Destination Picker work, which can also support the broader copy/move workflows.

This keeps the first implementation focused while preserving the security boundary: all restore targets must still be validated by the Runner against the legitimate Workspace Root / Session Repository scope, with symlink escapes and protected .git paths rejected.