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`

docs/operations.md

@@ -133,8 +133,8 @@ record does not fall back to the earlier outputs. The earlier run manifest and
 immutable bundle remain available for inspection, but downstream resolution
 requires a new current successful extraction record.
 
-Atomic Notarius bundle promotion is supported on Linux, macOS, and Windows.
-On other operating systems, extraction fails before copying the bundle into a
+Atomic Notarius bundle promotion is supported on Linux and macOS. On Windows
+and other operating systems, extraction fails before copying the bundle into a
 temporary promotion tree because Narratio has no verified atomic no-replace
 directory primitive there. This is an extraction limitation, not a broader
 platform-support guarantee for every Narratio workflow.
@@ -329,6 +329,8 @@ Rules:
 
 - `clean` deletes work/spool session state;
 - cache is preserved unless `--clear-cache` is set;
+- each deletion is confined beneath its configured workspace, spool, or cache
+  root and refuses symlinked paths;
 - automatic post-publish cleanup is gated by successful publish commit plus:
   - `pipeline.spool.delete_audio_after_publish=true`
   - `pipeline.workspace.cleanup_after_publish=true`

docs/roadmap/implementation.md

@@ -20,7 +20,7 @@ All stages are pending when this plan is created.
 | 2 | Enforce safe identifiers and fuzz path/source contracts | COR-002, TST-013 | Completed |
 | 3 | Consolidate crash-durable atomic file replacement | RSK-002, DUP-001, DUP-005 | Completed |
 | 4 | Add confined destination and download/install capabilities | COR-003, DUP-003, TST-003 | Completed |
-| 5 | Confine recursive cleanup and replace sentinel locks | RSK-003 | Pending |
+| 5 | Confine recursive cleanup and replace sentinel locks | RSK-003 | Completed |
 | 6 | Harden API-key file acquisition | RSK-010 | Pending |
 | 7 | Bound and verify external result acquisition | RSK-013, TST-007 | Pending |
 | 8 | Terminate owned subprocess trees | RSK-011 | Pending |

docs/troubleshooting.md

@@ -299,7 +299,7 @@ Symptom:
 Likely causes:
 
 - another process is running for the same session;
-- stale lock left by interrupted process.
+- a process still holds the operating-system lock while it is shutting down.
 
 Diagnostics:
 
@@ -311,7 +311,8 @@ ps aux | grep narratio
 Safe fix:
 
 - wait for active process completion;
-- remove stale lock only after confirming no live process owns it.
+- retry after an interrupted holder has exited; the kernel releases its lock
+  even though the `.lock` metadata file remains for inspection.
 
 Relevant reference: [Operations: Local State Layout](./operations.md#local-state-layout).