@6reduk/workspace-pipeline 0.1.0

package/docs/repository-recovery.md

@@ -0,0 +1,204 @@
+# Repository recovery — development checkpoint
+
+Repository recovery does not install providers or automatically replay/undo effects.
+Use `finalize` for verified completed operations, `recover-locks` for native-verified
+stopped-owner retirement, and `abandon` for an explicit decision to preserve the
+observed partial state without claiming completion. See the sections below and
+[manual decision boundaries](repository-manual-recovery.md) for unbound/torn inputs.
+Author checks and independent S7 acceptance remain separate.
+
+Run from any directory, naming the wrapper explicitly:
+
+```powershell
+workspace-pipeline repositories status --workspace "C:\Work\MyWorkspace"
+workspace-pipeline repositories finalize --workspace "C:\Work\MyWorkspace"
+```
+
+Both commands are read-only and print JSON. Save the complete finalize JSON to a
+private UTF-8 file, inspect its operation and blockers, then explicitly apply:
+
+```powershell
+workspace-pipeline repositories finalize --workspace "C:\Work\MyWorkspace" --apply --preview "C:\Private\finalize-preview.json"
+```
+
+The preview must still match the workspace, retained inputs, evidence and observed
+repository contents. Apply does not refresh an outdated preview or fetch source.
+If a previous attempt already wrote the exact completion receipt but did not move
+the pending marker, the preview selects receipt resumption. No repository effect
+is repeated. Missing/damaged historical inputs or conflicting evidence are errors,
+not permission to guess. Old installations without retained inputs are not silently
+migrated by these commands.
+
+New operations save execution inputs under `.pipeline/repository-inputs/`, before
+repository effects. Keep this directory private and do not remove its files while
+an operation is unresolved. `logs list` shows the locations. S7 history is currently
+protected when pending or referenced; `logs clean --repositories` can select only
+native-verified unreferenced completed groups with explicit age/count/run limits.
+Ordinary `logs clean` keeps its existing separate scope. Do not manually
+delete pending markers or lock directories to make `doctor` report success.
+
+`no-pending-marker` means exactly that; it does not certify historical completion,
+provider readiness or game runtime. A blocker means further recovery is needed;
+this command never grants itself authority to resolve it. `--json` is redundant
+but accepted because JSON is already the default output.
+
+## Local recovery ownership
+
+Recovery writers use an ephemeral local IPC lease: a Windows named pipe, or a
+Linux abstract socket. This is not TCP and does not expose a data protocol. Process
+exit releases the kernel-owned endpoint; progress remains in existing durable
+records. Different recoverers cannot simply adopt a dead owner's directory.
+Persistent pending guards continue to protect ordinary lifecycle writers.
+
+The current implementation supports this primitive on Windows/Linux only; other
+platforms fail explicitly. Windows synthetic tests exist; Linux runtime validation
+is still pending. It is not a distributed lock for shared/network filesystems and
+does not isolate arbitrary editors or hostile processes running as the same user.
+See [Node IPC documentation](https://nodejs.org/api/net.html#ipc-support).
+
+Never interpret an old approval or a stopped PID alone as permission to continue.
+Repeated continuation requires a new exact observed-state approval. Remaining
+bootstrap and partial-effect routes are described below. The Windows ownership checkpoint
+was independently reviewed; this is not full S7 acceptance.
+
+Existing wrapper roots and ancestors must not be links/junctions/reparse aliases;
+they are rejected, not assigned a second lease identity. Persistent record names
+retain their existing spelling; this change does not rename historical records.
+
+`recovery-lease.busy-or-access-denied` means the OS returned EACCES: contention
+and a permission problem cannot be distinguished safely here. No lock is stolen.
+Errors ending in `status-required` identify lease loss or release-phase failure,
+possibly after durable effects completed. Inspect status and retained records before
+retrying; the error does not mean rollback occurred. A simultaneous callback and
+release failure is reported separately, without leaking raw OS error text.
+
+## Stopped-owner lock recovery
+
+For an evidenced, completed repository operation whose locks were retained by a
+stopped process, select the exact journal UUID from its pending/completion record
+or `logs list`. Do not choose an operation by timestamp or assume the newest UUID.
+
+```text
+workspace-pipeline repositories recover-locks --workspace <absolute-wrapper> --journal <journal-uuid>
+workspace-pipeline repositories recover-locks --workspace <absolute-wrapper> --journal <journal-uuid> --apply --preview <absolute-preview.json>
+```
+
+The first command is read-only. Save its complete JSON privately in UTF-8 and
+inspect it before the second command. The preview identifies initial retirement,
+interrupted retirement or repeated continuation, binds retained inputs and exact
+observed state, and blocks live/unknown owners. Apply rechecks under native kernel
+ownership. Original locks/owner records are retained, not recursively deleted.
+The command neither replays repository effects nor configures providers. A pending
+finalization remains a separate `repositories finalize` action after locks retire.
+
+Repeated continuation now writes `continuation-NNNNNN.json` inside the existing
+resumption directory **before** remaining recovery actions. These are immutable
+authorization records, not additional locks. Each binds the fresh observation and
+the hashes of preceding records. Completion retains the directory under the original
+lock-recovery archive; `logs list` reports that protected archive. An already-complete
+native continuation is read-only and does not append another approval. Active chains
+are bounded to 128 records / 32 MiB and individual records to the normal input cap;
+limit errors stop before another append, without deleting history.
+
+This route is deliberately limited to evidenced completed repository effects.
+Incomplete bootstrap creation, missing old retained inputs, uncertain effects and
+partial authorization-file writes still require separate handling. An error never
+authorizes blind lock removal or replay. S7 retention and those recovery routes
+are not declared complete.
+
+## Interrupted bootstrap recovery
+
+New bootstrap recovery attempts preserve the complete original request beside the
+recovery owner, before relocating the original lock. If that recovery process dies,
+the following command reconstructs the remaining actions without source acquisition:
+
+```text
+workspace-pipeline repositories continue-bootstrap --workspace <absolute-wrapper>
+workspace-pipeline repositories continue-bootstrap --workspace <absolute-wrapper> --apply --preview <absolute-preview.json>
+```
+
+Save and inspect the first command's JSON privately in UTF-8. The second command
+rechecks that exact preview under exclusive recovery ownership. Only a stopped,
+local owner is eligible. Continuation does not recreate the wrapper or replay a
+repository operation. It may finish moving the original intent/lock, persist the
+exact recovery receipt, and archive the recovery gate. It preserves foreign data
+and refuses inconsistent, missing, duplicated or damaged evidence.
+
+The original request and subsequent approvals are retained in the sibling directory
+`.wpc-bootstrap-recovery-<initial-reconciliation-hash>`. `logs list` shows its path
+as protected recovery evidence, outside completed-transaction cleanup. To inspect completed
+history, add `--initial sha256:<initial-reconciliation-hash>` explicitly. Completed
+verification performs no write; subsequent legitimate wrapper changes may invalidate
+the old completion observation and are not silently ignored.
+
+The active guard admits at most 64 continuation approvals and a bounded 16 MiB
+inventory; each input is still subject to the normal per-record size cap. Reaching
+a limit does not authorize deleting active history. A crash before the original
+request is fully published, legacy owner-only guards, torn approvals, or wrapper
+creation without a consistent receipt are still unsupported recovery cases. They
+remain fail-closed, not guessed or auto-replayed. See the manual decision boundary.
+
+## Explicit abandonment of an unfinished repository operation
+
+`repositories abandon --workspace <absolute-wrapper>` produces a private exact
+preview for **preserve current state, abandon the old request**. Save and inspect
+the preview, then use the same command with `--apply --preview <file>`. It records
+target/source trees, all retained metadata, marker/input hashes and stopped lock
+owners. A changed tree requires a new preview. Missing/torn owner information or
+unknown/live owners cannot be approved through this command.
+
+The operation does not retry clone/init/move, delete repository data, restore the
+old state, or claim completion. It archives the pending marker and any known stopped
+locks in `.wpc-repository-resolution-<uuid>` beside the wrapper. The archive retains
+the exact decision and a receipt with `completed:false`. An ephemeral recovery lease
+and durable recovery gate protect the remaining moves. A new init/adopt preview is
+required afterwards; choose `keep` for retained usable repositories or separately
+resolve unwanted partial data. A partial clone is not converted into a verified clone.
+
+After interruption, run `repositories continue-abandon --workspace <wrapper>
+--attempt <uuid>` for a fresh preview, then add `--apply --preview <file>`. The old
+request and subsequent approvals remain immutable. Completed-history verification
+is not a certification of later changes to the repository. If publication stopped
+before a complete guard/request exists, consult the manual decision boundary; no
+automatic deletion or request reconstruction is attempted.
+
+## Shared execution and its ownership boundary
+
+Initial recovery and continuation share the same remaining-action engine within
+each domain (bootstrap archival and paired repository-lock retirement). Approval
+and ownership acquisition remain distinct: the initial call verifies its own live
+gate owner; continuation requires the prior recorded owner to have stopped and
+retains fresh approval. Both use the kernel lease and recheck evidence between
+effects. A shared engine does not authorize replay of uncertain effects or repair
+of incomplete records. Paired retirement rechecks the repository subject before
+moving the second lock, not only after both moves.
+
+## Stopped owner before the bootstrap request
+
+One early state has a deliberately narrow archival route: the wrapper is absent,
+the bootstrap lock contains only a valid `owner.json`, and its local process is
+confirmed stopped. No operation request or intent may be present.
+
+```text
+workspace-pipeline repositories retire-bootstrap --workspace <absolute-wrapper>
+workspace-pipeline repositories retire-bootstrap --workspace <absolute-wrapper> --apply --preview <absolute-preview.json>
+```
+
+Save/inspect the first command's private UTF-8 JSON before apply. It names the exact
+history destination `.wpc-bootstrap-abandoned-<attempt-uuid>` next to the wrapper.
+Apply retains that preview before moving the entire old lock into `history/lock`.
+The original lock blocks ordinary creators until the single final rename; the
+existing kernel lease excludes competing recovery writers. No extra recovery lock,
+repository replay, wrapper creation, deletion or claim of historical success occurs.
+
+If interrupted before that rename, the old lock still blocks writers. Inspect a
+**new preview** to attempt archival again; it chooses a new history location and
+does not overwrite the earlier incomplete history. After the rename, only the
+selected original lock's preserved history can be verified. This does not certify
+the current wrapper state: another legitimate creator may already have started.
+
+`logs list` reports attributable history as protected; unreadable/empty abandoned
+history appears as a diagnostic with its location. Do not delete active records to
+clear a blocker. These records remain protected recovery evidence. Empty, torn, foreign,
+live or unknown owner records, recovery gates, existing wrappers and any intent or
+extra lock files are outside this route and remain blocked.

package/docs/repository-retention.md

@@ -0,0 +1,46 @@
+# Repository execution history cleanup
+
+Repository setup records are a separate cleanup domain from configuration journals.
+List locations with `workspace-pipeline logs list --workspace <absolute-wrapper>`.
+Record contents may contain private paths/configuration; keep previews and receipts
+private. Listing never deletes anything.
+
+```text
+workspace-pipeline logs clean --repositories --workspace <absolute-wrapper> --max-age-days 30 --keep-last 20 --max-delete 5
+workspace-pipeline logs clean --repositories --workspace <absolute-wrapper> --apply --preview <private-saved-preview.json>
+```
+
+Numbers above are examples, not defaults. All three limits are required; age OR
+count makes an otherwise eligible group a candidate, and `max-delete` caps complete
+groups per invocation. Local latest file modification time is the conservative age
+anchor, not an invented execution date. A future timestamp protects the group.
+The flag is required for both invocations; it cannot be mixed with receipt cleanup
+options or policy commands. Existing startup policy remains configuration-journal
+policy, not implicit repository cleanup authorization. There is no background job.
+
+Only internally consistent completed transaction groups (journal, inputs,
+authorization when present, result evidence and completion records) are eligible.
+Referenced, active, pending, uncertain, malformed and current-run records are
+protected. The scan checks bounded metadata and retained recovery references,
+including escaped JSON UUIDs and hashes; it does not reread current game content
+or assume it still equals an old completed operation. Unknown transaction formats
+and uninspectable metadata fail closed. A pending configuration transaction also
+blocks cleanup. Opaque retained records are reference roots, not deletion targets.
+
+Bootstrap, ancestor, abandonment and lock-recovery histories remain protected
+evidence. Repository cleanup receipts are also retained; this command does not
+erase its own audit trail or unrelated configuration receipts. Age/count limits
+may remain exceeded when records are protected. Inspect protection reasons rather
+than deleting locks or inputs to force eligibility.
+
+Apply holds the workspace lock and recovery lease, rechecks the exact selection
+and references, records an execution receipt under `.pipeline/repository-cleanup/`,
+and removes only listed files and empty group directories. It prints the receipt
+path before deletion and reports partial failures. Deletion is not recoverable.
+An interrupted cleanup is not auto-replayed: preserve its receipt and inspect the
+reported current file/remaining groups before making a new decision.
+
+Current scan bounds: 20,000 metadata entries, 128 MiB total, 8 MiB per file plus
+the normal JSON input cap. Bound failures are explicit blockers, never partial
+successful scans. No repository/code/assets, provider configs, installed snapshots
+or backups are cleanup targets.

package/docs/repository-transport-budgets.md

@@ -0,0 +1,26 @@
+# Repository clone transport budgets
+
+S7 repository acquisition is separate from S2 pipeline-package acquisition. Every
+local and remote clone preview binds `packLimit`, `gitMs`, and `acquisitionMs`.
+Current defaults and upper ceilings are 100 GiB of stored Git objects, 30 minutes
+per Git command, and two hours for each acquisition/materialization Git sequence.
+Smaller internal budgets are validated and bound in the same preview. They cannot
+be increased during apply without a fresh preview. These are ceilings, not disk
+reservations, download-size predictions, throughput guarantees, or total-workspace
+execution deadlines. A remote preparation and subsequent local materialization
+are distinct sequences and each can retain its object store after failure.
+
+The live object monitor and final size check enforce the pack budget, with possible
+monitor-interval overshoot. Timeout termination remains owned-process-only and an
+unconfirmed termination remains an error. No retry or full-history fallback is
+added. Source records and repository output are retained for explicit recovery.
+
+Committed-tree listing has a separate 256 MiB bounded output allowance, followed
+by the existing 200,000-entry and 100 GiB content checks. This does not permit
+unbounded buffering or weaken path, Git mode, LFS, filter, or inventory checks.
+Tests at/over transport ceilings use numeric boundaries and synthetic subprocess
+results; they do not claim a real 100 GiB download or two-hour runtime exercise.
+
+S2 remains 256 MiB stored objects, 120 seconds per Git command, 300 seconds total
+acquisition, and its original package blob/tree/output limits. Supplying repository
+budgets to the S2 runner does not enable the S7 transport profile.

package/docs/retention.md

@@ -0,0 +1,237 @@
+# Technical journal retention
+
+The internal `scanRetention(workspace, {policy, now, currentRuns})` API produces
+a read-only filesystem preview. Explicit CLI cleanup is available; automatic
+startup deletion is not enabled.
+Policy requires explicit `maxAgeDays`, `maxJournals`, `maxDeletesPerRun`; no defaults
+are silently selected by a pipeline package.
+
+The scan reports absolute journal/recovery paths, status, byte counts, exact file
+hash/mtime inventory and protection reasons without returning record contents.
+Age uses local metadata modification time, not an inferred activation timestamp.
+The active transaction is always selected by explicit state/record bindings.
+
+Current state/current run, incomplete records, corrupt/unknown/orphan evidence
+and retained references are protected. References are conservatively collected
+from record paths: even an eligible record protects the history it references.
+Ambiguous inventory or state protects all groups. Only unreferenced completed
+groups can be selected by age OR count, oldest first, subject to the per-run cap.
+Protected entries still contribute to totals and unmet limits.
+
+The scanner inspects exact UUID groups, permits only sequential JSON event names
+and recovery.json, refuses links/foreign files, bounds reads to 10,000 files and
+64 MiB, and repeats inventory, hashes, timestamps, history and state checks.
+This is not an atomic filesystem snapshot. The locked cleanup executor revalidates
+before mutation and preserves diagnostics for partial deletion.
+
+Backups, snapshots, repositories, provider configs and project documentation are
+outside deletion scope. Do not remove `.pipeline` wholesale. The preview's
+`applySupported` and `automaticActions` remain false: it is a proposal, not an
+execution capability. `applyRetention` performs its own locked validation.
+
+## CLI usage (development checkout)
+
+`logs list` also includes a `repositories` section for the S7 repository journals,
+evidence, authorization chains, completion records and bootstrap/recovery locations.
+This includes `.pipeline/repository-lock-recoveries/<digest>/` archives; their
+original owner records and recovery receipts remain protected from cleanup.
+It reports absolute paths only, not record contents. `validation: locations-only`
+means directory discovery, NOT semantic validation of journal chains or proof of a
+completed operation. Its `complete` flag describes this bounded listing only.
+
+S7 entries have `deletionEligible: false` and are not selected by `logs clean` yet.
+Do not manually clear a pending marker or bootstrap/recovery lock to bypass an
+unfinished operation. S7 age/count/per-run retention remains unimplemented.
+Sibling `.wpc-bootstrap-history-*` entries are attributed using the exact workspace
+in their owner record; malformed associations are reported as incomplete. Enumeration
+is bounded to 1,000 relevant entries/candidates and 100,000 parent directory names;
+exceeding a limit is incomplete, not an empty successful listing. Links are not followed.
+
+Run from the CLI repository, replacing `C:/Work/Game` with your wrapper:
+
+```powershell
+node ./src/cli.js logs list --workspace "C:/Work/Game"
+node ./src/cli.js logs clean --workspace "C:/Work/Game" --max-age-days 30 --keep-last 20 --max-delete 5 | Set-Content -Encoding utf8 "C:/Work/cleanup-preview.json"
+```
+
+The numbers are examples, not defaults. List chooses no retention policy and
+never deletes. Inspect the saved preview: selected IDs, absolute paths, byte
+counts and protection reasons. Then explicitly apply that same file:
+
+```powershell
+node ./src/cli.js logs clean --workspace "C:/Work/Game" --apply --preview "C:/Work/cleanup-preview.json"
+```
+
+Changed state, records, timestamps or inventory invalidate the preview. Generate
+and inspect a fresh one rather than forcing it. `--apply` cannot be mixed with
+policy flags and does not silently substitute a newly computed selection.
+
+## Deletion and failure reports
+
+Only enumerated event/recovery files and then empty group directories are
+removed. No recursive deletion is used. Each remaining recovery record and state
+is checked before every file deletion to detect new references; this conservative
+check has cost proportional to selected files times retained records, bounded by
+scan limits and the user deletion cap. It is not a linear-cost guarantee or an
+OS-wide defense against hostile concurrent filesystem writers.
+
+Progress is emitted as JSON on stderr; final JSON is on stdout. The receipt path
+is under `.pipeline/cleanup/<run-id>.json`. Receipts record selected file hashes,
+confirmed deletions, reclaimed bytes, current intent and failures. These receipts
+describe attempted/deleted paths; unlike operational recovery records, they are
+not dependencies requiring deleted file contents to remain. Deletion is not
+recoverable by this CLI. A crash may leave an intent without confirmation;
+do not treat that as successful cleanup. Partial groups are protected by later
+scans; locks are never stolen and cleanup does not auto-resume or roll back.
+
+Exit 0 means the requested cleanup completed, 1 means an incomplete/failed result,
+2 means invocation/preflight failure. Output transport can fail independently of
+filesystem completion; check the receipt rather than blindly retrying. Cleanup
+receipts from actual deletions are retained under v1; only an explicitly selected combined v2 policy
+or manual combined preview may rotate eligible completed receipts.
+
+## Setup/update startup integration (internal coordinator)
+
+The trusted caller may pass `retention: {preview, approval}` alongside the
+`report` option to `applyLifecycle`. The approval is the separate exact cleanup
+approval `{decision: 'approve', previewDigest: preview.digest}`; approving the
+installation alone does not authorize deleting history. The saved preview shows
+all three user limits. No policy is loaded from the pipeline supplier and there
+are no implicit numeric defaults. A separately enabled local automatic policy is
+described below; combining it with this manual startup option is rejected.
+
+The coordinator holds one workspace lock, preflights the main operation before
+cleanup, announces the validated policy, applies the exact cleanup, then repeats
+history and installation checks before any setup/update target writes. The new
+operation's journal is created only after cleanup; existing active/pending
+history is protected by the scanner. Read-only commands never enter this path.
+
+Results contain a separate `cleanup` result including its receipt path when
+available. Cleanup failure or a failed cleanup report prevents the main operation
+from starting (`status: 'not-started'`). If cleanup succeeds but setup/update
+subsequently fails, the completed cleanup remains reported separately; it is not
+rolled back or presented as successful installation. Invalid main approval fails
+before cleanup. Locks are released normally; abandoned locks are not reclaimed.
+
+Public setup/update use this coordinator and the separately configured local
+retention policy. They do not accept implicit cleanup defaults.
+
+## Local automatic policy
+
+`.pipeline/retention.json` is user-owned wrapper metadata, not pipeline content.
+Missing means disabled, with no limits invented. Invalid existing bytes block
+mutating startup instead of falling back to defaults. A strict v1 record contains
+`schemaVersion: 1`, `kind: "workspace-retention-policy"`, the absolute `workspace`,
+`mode` (`automatic` or `disabled`), and `journals` with all three existing limits.
+Unknown fields, duplicates and unsafe numeric values are rejected. Copying the
+file to a different workspace does not grant cleanup there. Schema version is
+data compatibility, not a project-task gate.
+
+Development-checkout commands (example numbers are not defaults):
+
+```powershell
+node ./src/cli.js logs policy show --workspace "C:/Work/Game"
+node ./src/cli.js logs policy set --workspace "C:/Work/Game" --mode automatic --max-age-days 30 --keep-last 20 --max-delete 5 | Set-Content -Encoding utf8 "C:/Work/policy-preview.json"
+node ./src/cli.js logs policy set --workspace "C:/Work/Game" --apply --preview "C:/Work/policy-preview.json"
+node ./src/cli.js logs policy disable --workspace "C:/Work/Game" | Set-Content -Encoding utf8 "C:/Work/disable-preview.json"
+node ./src/cli.js logs policy disable --workspace "C:/Work/Game" --apply --preview "C:/Work/disable-preview.json"
+```
+
+Inspect the preview before apply. Enabling automatic mode authorizes **future**
+eligible journal deletions within the chosen limits. These configuration commands
+do not delete history or install a pipeline. Writes verify exact before bytes
+under lock. Disabling preserves limits; absent policy is already disabled.
+
+The internal setup/update coordinator reads this file after main preflight and
+selects eligible groups afresh. Policy path/hash, limits, protected count and
+unmet totals are reported before removal. Receipts distinguish `workspace-policy`
+authority (exact policy hash) from `approve` (exact manual preview digest).
+The executor checks policy bytes at deletion boundaries; drift stops cleanup.
+There is one bounded pass per invocation, with no automatic + manual double budget.
+Read-only commands never run it. Supplier configuration is not read as user policy.
+The file/digest is not tamper-proof against a process already able to write the
+user’s filesystem. Policy itself is not part of immutable deployment approval.
+
+## Combined receipt retention (explicit v2 opt-in)
+
+`planCombinedRetention` independently computes age/count candidates for journals
+and receipts, then merges them oldest-first under one deletion cap. Typed identities
+keep equal UUIDs across classes distinct. This pure output is not deletion permission.
+`scanCleanupReceipts` inspects bounded local receipts and operational references,
+then rechecks hashes, inventory and history. Only known, internally consistent
+completed receipts qualify; current, incomplete, unknown and linked records stay
+protected. Missing reference evidence prevents usable cleanup inventory.
+
+`scanCombinedRetention` binds both inventories. The common executor deletes the
+selected typed items under one lock and one cap, retaining its own current receipt.
+Receipt descriptors describe deleted bytes and do not create immortal dependencies.
+Failed/partial/unknown records remain protected. Drift, including policy changes,
+stops the pass. No recursive deletion, implicit retry or budget reset is used.
+
+Add BOTH `--receipt-max-age-days N` and `--keep-receipts N` to a `logs clean`
+preview or `logs policy set` preview. `--max-delete N` is then the combined cap:
+one journal/recovery group or one receipt counts as one item. Apply still uses
+only `--apply --preview <file>`. `logs list` shows both inventories read-only.
+
+V2 local policy keeps `journals: {maxAgeDays, maxJournals}` and adds
+`cleanupReceipts: {maxAgeDays, maxReceipts}` plus top-level `maxDeletesPerRun`.
+The schemaVersion is 2; v1 is not rewritten or expanded automatically. Disable
+preserves the schema/limits; an explicit v1 set-preview can withdraw receipt
+authority. These versions are CLI metadata, not project governance gates.
+
+Both v1 and v2 create no cleanup receipt if nothing is selected, returning null
+receiptPath/runId and zero counts. This deliberately changes v1 no-work output:
+callers must respect receiptCreated:false rather than assuming a receipt path.
+A successful combined pass creates a schema-2 receipt; later scans validate its
+typed inventory and completion before it can become eligible. Current-run and
+operationally referenced receipts remain protected. Full release certification
+still requires independent review and packaged/live-provider tests.
+
+## Receipt scan bound and manual recovery
+
+The receipt scanner accepts at most 1,000 directory entries (also bounded by
+64 MiB). Above that, retention-receipts.limit blocks logs list and combined v2
+cleanup previews; it does not certify a partial inventory. V1 can still accumulate
+receipts from real deletions. Use explicit v2 receipt rotation before reaching
+this bound. Skipping empty v1 receipts does not cure an already oversized directory.
+
+There is no automatic overflow recovery or force-clean command. Manual recovery
+is an administrator operation, not permission to delete files by age/name:
+
+1. Stop CLI/harness writers for this workspace and establish that no writer is
+   alive. An existing lock requires its documented owner/liveness investigation;
+   do not remove it merely to get past this limit.
+2. Back up the workspace metadata securely. Receipts and scratch bytes can contain
+   private paths/configuration; do not upload them. Record exact paths and hashes.
+3. Inspect candidate receipt JSON individually using the current strict completion
+   validation, and inspect ALL state, transaction/recovery, journal and retained
+   receipt references. Only known, valid, completed, unreferenced receipts qualify.
+   Empty legacy v1 receipts still require those checks. Unknown, partial, linked,
+   referenced or corrupt entries remain in place. If reference independence cannot
+   be established, stop and obtain expert repair; the scan limit is not a waiver.
+4. With explicit approval of an exact path/hash list, move only those qualifying
+   receipt files to a private quarantine OUTSIDE the workspace until the directory
+   has at most 1,000 entries. Recheck hashes and references immediately before
+   moving. Use exact literal paths, never wildcards, recursive deletion or moving
+   the whole .pipeline directory. Keep the quarantine and move manifest recoverable.
+5. Rerun doctor and logs list. Resolve diagnostics before writes, then preview and
+   approve a combined v2 policy with explicit receipt limits. Do not blindly restore
+   quarantined files into a now changed workspace or delete the quarantine as part
+   of this procedure.
+
+## Scratch files left by a crash
+
+Replacement writes may leave .wpc-<uuid>.tmp beside a target; pending-state writes
+may leave .pipeline/.switch-state-<uuid>.tmp or .pipeline/.continuation-state-<uuid>.tmp.
+They may contain partial or complete private configuration bytes. They are not
+deployment state, not eligible journal receipts, and are intentionally not removed
+by logs clean or pipeline removal. A name match or old timestamp proves nothing.
+
+For manual cleanup, first stop writers and resolve pending recovery/locks. Establish
+the exact file's provenance from the interrupted operation, verify it is a regular
+non-linked file, ensure no live writer or recovery step needs it, and compare the
+actual target/state against the approved recovery result. If uncertain, leave it.
+After exact path/hash approval, move only verified leftovers to secure quarantine
+outside the workspace and rerun doctor. Preserve unknown files, provider settings,
+backups and snapshots. No blanket .tmp deletion is safe, and this CLI does not
+currently automate scratch inventory or reclamation.

package/docs/source.md

@@ -0,0 +1,50 @@
+# Git pipeline sources (library and CLI)
+
+The installer reads committed pipeline bytes, not working-tree changes. Local
+refs are interpreted in isolated preparation storage; final snapshots contain
+independent files. Source repositories, their refs/index/config and user credentials
+are not modified. No checkout, smudge filter, automatic history fallback or pipeline
+script execution is performed.
+
+## Remote commit pins
+
+A full lowercase commit ID is a valid source selector, but the remote server must
+permit fetching that object. Some servers reject a SHA that is not an advertised
+branch/tag tip, even if it is an ancestor of a visible branch. This is a server
+capability/access boundary, not permission to choose a different commit.
+
+`source.unadvertised-commit` means Git emitted the recognized refusal to request an
+unadvertised object. Use an advertised branch/tag pointing to the intended commit,
+a local repository containing that commit, or ask the repository administrator
+about the server policy. The installer does not change server settings, retry with
+full history, or silently substitute the latest revision.
+
+Unknown/localized server errors, connection and authorization failures remain
+`source.git-failed`; they must not be diagnosed as an unadvertised-commit refusal
+without the specific diagnostic. Raw Git stderr is never returned. Both successful
+tip pins and permitted non-tip pins remain supported. Live host/account behavior
+is separate from synthetic transport tests.
+
+## Errors and local recovery metadata
+
+- `source.missing-repository`: local source realpath failed with ENOENT.
+- `source.repository-unavailable`: another local source resolution failure.
+- `source.io` / `snapshot.io`: other unclassified preparation I/O failure, without
+  embedding raw filesystem error messages or the source path.
+- After creation, failures expose `error.preparation` and/or `error.snapshotPath`
+  as exact generated temporary roots. A root not yet created has no such field.
+  These paths are machine-local recovery metadata, not portable manifests; keep
+  them out of shared/public diagnostics. They do not authorize recursive deletion
+  without ownership and current path checks. No automatic cleanup is performed.
+- `source.termination-unconfirmed` preserves the owned root `processId` and does
+  not claim all descendants stopped. Do not retry or activate the result; inspect
+  process identity before later cleanup because a PID may have been reused.
+
+256 MiB is a stop/reject threshold on fetched object storage, not a disk quota.
+Transient overshoot between measurements is possible; oversized results are never
+returned for installation. Raw file, inventory, manifest and path limits also apply.
+
+The optional fourth `runGit` argument is a trusted code-only runtime seam used by
+unit tests to simulate process-control failures. It is not manifest configuration
+and must not be populated from pipeline/user data. Tests use simulated processes
+for kill-failure branches, avoiding real unkillable helpers.