Allow Remove-Worktree to terminate processes blocking removal

#174: approved guarded-removal contract

Approved by the maintainer on 2026-09-14. Implementation is authorized on a
separate branch and PR. These decisions supersede the original removal-first
proposal and the later hold/restore recommendation.

Goal and explicit limits

Add Remove-Worktree -KillBlockingProcess for actual worktree removal, disk-space
reclamation, and normal backing-branch cleanup. Calls without the switch retain
their existing behavior, output, platform support and confirmation semantics.

The new mode performs preflight before any destructive action. It is not a
transaction, snapshot, backup or rollback mechanism. Once confirmed Git deletion
starts, it is irreversible and may partially delete files or unregister the
worktree before returning an error. Preserve the remaining files and backing
branch on such failure, report the actual partial outcome, and stop. Do not
automatically retry Git removal, reconstruct data, or recursively clean a residual
directory.

Require cooperating applications to stop writing. Preflight and revalidation
detect conflicts but cannot establish isolation against all concurrent writers
or prevent every new lock/I/O failure. Termination can lose unsaved application
memory and interrupt unrelated work in the same process. Make these limits
visible in help and confirmation.

Initial supported scope

• Windows, local NTFS, ordinary registered linked worktrees.
• Resolve through the existing worktree guard, then verify filesystem and Git
  identities/containment. Reject main/root worktrees and the caller's current
  directory or its ancestors.
• Reject links/reparse points, nested repositories/submodules, unsupported
  storage layouts, and inaccessible or incomplete scans. Do not follow a link
  outside the target or silently fall back to ordinary removal.
• No automatic elevation, debug-privilege enabling, service shutdown, broad
  process-name termination, arbitrary handle closure or recovery journals.
• On non-Windows, reject the enabled switch before mutation. Ordinary removal
  remains portable.

Preflight and confirmation

1. Capture the resolved worktree identity, registration, original directory,
   branch full ref and expected OID, and keep/delete intent.
2. Inspect the supported scope and live sharing conflicts using documented APIs.
   Do not infer a locking cause from Git's generic exit code or localized output.
3. Use Restart Manager only for confidently identified, in-boundary file-resource
   associations. It identifies resource users, not exact causal locking handles.
   The maintainer accepts individually confirmed file-associated candidates;
   do not claim all resource users are proven blockers.
4. Unresolved directory-only locks, ambiguous association, unsupported targets,
   incomplete scans, protected processes or missing safety metadata stop the
   operation before Git deletion. Report why manual intervention is needed.
5. Collect approval for the planned worktree removal and each known required
   process termination before terminating the first process. A declined known
   prerequisite stops the operation without deleting the worktree or branch.
   Do not use approval for one PID as approval for another or for new candidates.
6. Revalidate identities, resource associations and protection eligibility
   immediately before each approved termination. Retain and use the verified
   process handle so PID reuse cannot select a different process.
7. Reinspect before deletion. New/unresolved conflicts stop the operation;
   do not silently expand the termination set or enter a kill/retry loop.

SupportsShouldProcess remains authoritative. Use a separate high-impact
decision for each destructive action, without duplicate nested prompts.
-Force retains its existing Git meaning and is never consent to kill, bypass
confirmation, override safety exclusions or increase retries.

Process safeguards and wait bounds

• Exclude the current process, its ancestors, critical/system/protected processes,
  services and identities whose safety cannot be confidently established.
• Limit eligible applications to the supported same-user/session safety contract;
  unknown identity, ancestry or protection information is a denial.
• Match PID and creation time through the retained handle. Disclose PID, name,
  executable path when accessible, and associated resource information.
• No blanket process-tree kill, RmShutdown, or automatic application restart.
• Wait at most 10 seconds per process and 30 seconds total for exit.
  An asynchronous termination request alone is not proof of exit.
• A failure, timeout, changed candidate or uncertain exit stops before Git
  deletion. Report any processes already terminated; that cannot be rolled back.

Removal and branch cleanup

• After successful preflight, approvals, necessary terminations and revalidation,
  attempt ordinary Git worktree removal once.
• Preserve existing explicit Git -Force semantics. No additional force flag,
  fallback delete or automatic retry.
• Delete the local backing branch only after verified successful directory and
  registration removal, and only if its captured identity is still valid.
• If the branch changes or its identity cannot be established, preserve it and
  report that branch cleanup needs a separate decision.
• For an unchanged branch, retain current cleanup semantics, including unmerged
  branch deletion unless -KeepBranch or explicit -RemoveBranch:$false is set.
  Detached worktrees do not delete branches; remote refs are never targets.
• Do not delete a replacement ref based only on an old name. Conditional deletion,
  worktree-use checks and branch-config cleanup must not be presented as a single
  atomic transaction. Fail closed when the approved identity cannot be preserved.

Preview, structured output and errors

-WhatIf may perform Restart Manager diagnostics and its temporary Windows
bookkeeping, closing the diagnostic session afterward. It must not create
persistent recovery state, terminate processes, invoke destructive Git removal,
write refs or change branches. Disclose incomplete discovery and never describe
preview as completed removal.

The opt-in mode emits structured evidence and outcomes for discovered candidates,
termination and removal. Preserve PowerShell error records; no success-shaped
fallbacks, warning-only hidden failures or optimistic success based on absence.
Distinguish preflight refusal, termination failure, removal failure/partial state,
successful removal and deferred branch cleanup.

Required validation

Use Pester 6.2+ deterministic fixtures and only owned temporary repositories and
controlled child processes. Never terminate shared editors, shells, build tools,
services or unrelated processes during development.

Cover scope/platform refusal, complete/incomplete scans, no blocker, file-associated
child, directory-only/unidentified blocker, per-process refusal, current/ancestor/
protected/system process, PID reuse, association changes, termination failure,
per-process/total timeouts, post-termination conflict, successful removal, partial
Git deletion/unregistration, no residual retry, changed/replaced branch,
keep/detached behavior, preview, and unchanged ordinary removal.

Read-only diagnostics must not accidentally run Git mutators or load optional
Windows interop on unrelated portable module imports. Update help, README and
the owning module's unreleased changelog. No version bump in the implementation PR.

Related evidence

• Earlier investigation and incompatible guarantees
• Full alternatives and API research

The earlier documents remain historical evidence. They do not authorize a
hold/restore subsystem or override this approved irreversible-removal contract.

Start by locating the existing Remove-Worktree entry point and owning module, then read its help, README, and unreleased changelog. Use Pester 6.2+ with only owned temporary repositories and controlled child processes; done requires the specified refusal, termination, removal, preview, branch-cleanup, and unchanged ordinary-removal cases to pass.