Confine cleanup and use held session locks

docs/internal/fileops.md

@@ -18,6 +18,19 @@ writer receives a `fileops`-owned, already-open sibling temporary file rather
 than a mutable destination path. Callers still own remote object selection,
 validation, conflict handling, and final mode.
 
+Directory promotion keeps the verified destination parent open while it creates
+the temporary tree, copies regular source entries, and performs the platform
+no-replace rename. Platforms without a verified handle-relative atomic
+no-replace primitive reject promotion before writing a temporary tree.
+
+## Cleanup Contract
+
+`RemoveAllUnderRoot` accepts an explicit root and a proper descendant. It opens
+the root and each target ancestor without following symlinks, then removes the
+tree through those directory handles. It rejects root deletion and any symlink
+encountered in the target path or tree; repeated removal of a missing target is
+successful. Command and post-publish policy remains owned by `internal/app`.
+
 ## Replacement Contract
 
 `ReplaceFileAtomic` requires an existing destination directory. It creates a

docs/internal/workspace.md

@@ -13,8 +13,9 @@ previous-cache path construction. `SessionPathsFor` provides the session-scoped
 path model, and layout creation goes through `EnsureLayoutFor`. Callers should
 consume those helpers instead of rebuilding relative paths.
 
-`internal/pathsafe` and application cleanup helpers enforce confinement for
-relative destinations and deletion targets.
+`internal/pathsafe` validates relative destinations. `internal/fileops` opens
+cleanup roots and their descendants through no-follow directory handles before
+removing them.
 
 `internal/fileops` owns the ordinary workspace mode contract. On POSIX,
 `WorkspaceDirectoryMode` is setgid `02775` and `WorkspaceFileMode` is `0664`.
@@ -43,8 +44,11 @@ existing destination. Exact physical paths belong in
 
 ## Locking
 
-`artifacts.LocalStore` enforces the single-writer session lock via `.lock`
-(`ErrLockConflict` on contention).
+`artifacts.LocalStore` enforces the single-writer session lock via an
+operating-system lock held on `.lock` (`ErrLockConflict` on contention). The
+file retains owner metadata after release or process death; its existence is
+not evidence that a lock is active. Command and restore flows wait for this
+lock only while their context remains active, and report a release failure.
 
 ## Cleanup Semantics
 
@@ -54,10 +58,11 @@ Automatic post-publish cleanup:
 - requires `uploaded=true` and `current_pointer_written=true` metadata;
 - consumes the resolved cleanup policy described in
   [Configuration](../config.md);
-- refuses unsafe deletes (root delete, out-of-root delete, symlink paths).
+- refuses unsafe deletes (root delete, out-of-root delete, and symlinked
+  ancestors or entries).
 
-Manual cleanup uses the same scoped-target checks. Invocation syntax and exact
-deletion scope belong in [CLI](../cli.md#clean) and
+Manual cleanup uses the same root-confined deletion mechanism. Invocation
+syntax and exact deletion scope belong in [CLI](../cli.md#clean) and
 [Operations](../operations.md#cleanup).
 
 ## Invariants
@@ -75,10 +80,10 @@ deletion scope belong in [CLI](../cli.md#clean) and
 - Run-local materialization: `internal/stage/run_local.go`
 - Immutable bundle promotion: `internal/fileops/directory.go`
 - Workspace modes: `internal/fileops/modes.go`
-- Cleanup confinement: `internal/app/cleanup_targets.go`,
-  `internal/app/post_publish_cleanup.go`
+- Cleanup confinement: `internal/fileops/cleanup.go`,
+  `internal/app/cleanup_targets.go`, `internal/app/post_publish_cleanup.go`
 - Tests: `internal/artifacts/paths_model_test.go`,
   `internal/artifacts/local_test.go`, `internal/stage/run_local_test.go`,
   `internal/fileops/directory_test.go`, `internal/fileops/modes_posix_test.go`,
-  `internal/app/cleanup_targets_test.go`,
+  `internal/fileops/cleanup_test.go`, `internal/app/cleanup_targets_test.go`,
   `internal/app/post_publish_cleanup_test.go`