owlrunkit 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.16.0
+
+- Adds a persistent coverage-root registry. After each fleet root is registered
+  once, ordinary discovery, shared Skill upgrades, and Core successor planning
+  automatically scan the complete registered scope. RunKit refuses unreachable
+  registered roots and does not claim to discover projects outside them.
+- Upgrades profile detection to emit high-confidence, exact project-local
+  npm, pnpm, Yarn, or Bun launchers that can be adopted atomically with
+  `profiles detect --apply`; a PATH-only manager remains review-required.
+- Adds deterministic assurance routing among No RunKit, Quick Verification,
+  and Formal Delivery based on explicit risk facts.
+- Adds the three-command Formal happy path: `formal start`, incremental
+  `formal check`, and one `formal finish` that performs the final source,
+  evidence, permission, closeout, and lease-release gates. Exact create-only
+  checks and finishes resume after interruption; mismatches fail closed.
+- Restricts Formal accepted checks to the mechanically safe built-in Node
+  syntax checker until a filesystem-write and network sandbox exists. Profile,
+  package-manager, wrapper, and custom commands fail before spawn; legacy
+  verification remains available without being treated as sandbox-equivalent.
+- Adds `SourceCandidateV2` for immutable dirty-worktree candidates with exact
+  owned-path closure, verification, and clean-workspace materialization.
+  Materialization now uses a sibling staging checkout, atomic target switch,
+  byte-exact rollback, and interruption recovery instead of incrementally
+  mutating the clean target. An accepted candidate, including deletion-only
+  and renamed changes, remains first-class through closeout, READY V2, release
+  successor verification, deployment prepare, and deployment lineage while
+  legacy DeliveryPacket runs remain compatible.
+- Adds fleet-safe Core successor planning and Owner-authorized apply, including
+  mixed prior Core identities, exact candidate materialization, and
+  append-only per-project migration receipts. Owner authorization is an
+  Ed25519-signed V2 artifact verified against the fixed user trust store.
+- Adds linked deployment prepare/execute contracts and a staged remote
+  deployment adapter with fixed machine identity, create-only upload, exact
+  deletion allowlists, before/after state, hash verification, and stage-specific
+  failure receipts. Deployment authority binds the full remote intent and is
+  revalidated with execution, lease, preflight, engine, and lineage state before
+  every remote stage.
+- Adds an independently hashed `OwnerDeploymentDecisionV1` for deployment
+  mode, existing assets, rollback and data authority, service activation,
+  baseline cut, and destructive scope. The decision is compiled against Goal,
+  prepare receipt, remote manifest, and signed Authority V2 before child or
+  lease creation, then revalidated before every remote stage.
+- Closes a child as blocked `closed_superseded` when its Owner decision changes,
+  preserving old evidence and reporting the business goal incomplete with a
+  replacement plan required. Exact same-decision resume remains supported;
+  permission, target, artifact, remote intent, data, rollback, service,
+  baseline, or destructive expansion requires new authority.
+- Adds a release identity gate that compares package version, computed Core,
+  public Attest, bundled Skill declaration and config, unpacked tarball copies,
+  release binding, and retained tarball bytes. A stale hash on any surface
+  blocks the release successor.
+- Makes the built-in argv-only SSH adapter selectable directly from the remote
+  deployment manifest, with exact bindings for the Core adapter, `known_hosts`,
+  SSH executable, opaque credential reference, target, and structured stage
+  contracts. Its caller-provided privileged remote helper is explicitly bound
+  by path, protocol, version, and fixed execute/reconcile capabilities, then
+  checked during identity preflight before any side effect. The npm package
+  does not install this VM prerequisite and does not claim out-of-the-box
+  privileged deployment. Existing external process-adapter manifests remain
+  compatible.
+- Adds create-only before/after journals for every remote stage invocation,
+  bound to the deployment lineage, remote manifest, execute request, and exact
+  adapter identity. `deployment execute --resume` reuses the existing child,
+  validates the complete journal, and reconciles remote truth instead of
+  creating a replacement execution.
+- Prevents interrupted install, service, and proxy stages from being replayed
+  without a successful read-only reconciliation. Unknown non-idempotent state
+  returns `reconciliation_required` and keeps the child control active; only
+  idempotent stages may be retried without proof.
+- Revalidates `known_hosts`, the SSH executable, and identity-file real paths
+  and hashes before every external SSH invocation. SSH and process transport
+  failures are recorded as indeterminate remote state rather than proven
+  failures.
+- Adds a concise human status projection that reports completed steps,
+  remaining gates, and the next allowed action.
+- Adds action-specific help for the new daily-use commands and makes the
+  automatic deployment child workflow the documented default; manually
+  assembled execute requests remain an advanced compatibility path.
+- Makes nested command help available through the published bootstrap before
+  project binding, rejects symlink traversal for READY evidence and retained
+  release artifacts, validates the complete READY lineage, and includes file
+  modes in SourceCandidate V2 release equivalence.
+- Makes the `owlrunkit` launcher prefer a project's exact locally bound CLI for
+  ordinary commands; bootstrap-only operations continue through the current
+  package. Delegation additionally requires the canonical official npm tarball
+  URL, canonical SHA-512 SRI, a bootstrap-trusted Core identity, and a matching
+  project Config, so a jointly forged local CLI and Config remain blocked.
+- Keeps the candidate unpublished, binds the rollback baseline to the exact
+  published `owlrunkit@0.15.1`, and grants no Git, publish, release, deploy, or
+  business authority.
+
 ## 0.15.1
 
 - Treats preserved active lease bytes in trusted `blocked` or `rejected`

package/README.md

@@ -1,105 +1,313 @@
 # OwlRunKit
 
 OwlRunKit is OwlCoda's project-owned execution and evidence engine, released
-with its own version lifecycle.
-
-It keeps bounded agent work inspectable and recoverable through goal
-contracts, exact writer leases, source-bound delivery packets, verification
-receipts, deterministic repair, accepted or blocked closeout, and explicit
-release authority.
+with its own version lifecycle. It makes the correct workflow the ordinary
+path: choose the assurance level, run bounded work, preserve source and
+evidence, then close out once.
 
 ## Install
 
 ```bash
-npm install --save-exact owlrunkit@0.15.1
+npm install --save-exact owlrunkit@0.16.0
 ```
 
-Check the ordinary CLI surface, then initialize a project:
+The `owlrunkit` bootstrap uses the project's exact locally bound CLI for
+ordinary project commands. The installed current package remains responsible
+for bootstrap operations such as initialization, adoption, and Core successor
+migration, so a global CLI does not reinterpret an older project's control
+state. Delegation is fail-closed: the lock entry must contain the canonical
+official npm tarball URL and SHA-512 SRI, the installed Core closure must match
+the current bootstrap Core or its embedded prior-release identity catalog, and
+the project Config must independently bind the same Core.
 
 ```bash
-owlrunkit --help
 owlrunkit --version
 owlrunkit init --workspace /absolute/path/to/project
 owlrunkit doctor --workspace /absolute/path/to/project
-owlrunkit profiles detect --workspace /absolute/path/to/project --dry-run
-owlrunkit adopt --workspace /absolute/path/to/project --exact owlrunkit@0.15.1
 ```
 
-`doctor` is read-only and distinguishes offline/DNS timeout, registry
-authentication, missing version, and local install binding failures. Profile
-detection is deterministic and dry-run only; use `profiles validate` and
-`profiles impact --changed` for supported profile checks. `adopt` writes typed
-evidence only after the exact installed package and lockfile match the official
-npm registry release.
-
-Core 0.15 keeps Contract v0.2 and all 0.13/0.14 project artifact schemas
-readable. `init` refreshes an older ConfigV2 Core binding with an append-only
-migration receipt only when the project has no active execution, active writer
-lease, or ambiguous control state. Otherwise the upgrade exits before changing
-the config or writing migration evidence. Legal refreshes preserve profiles,
-executions, receipts, and adoption evidence byte-for-byte. Existing profiles
-are never rewritten automatically; a fresh `profiles detect --dry-run` supplies
-safer, workspace-aware candidates for human review.
-Repeated Core refreshes create sequenced receipts without replacing an earlier
-migration event, and rejected Formal finalize gates retain their request-bound
-reason as append-only evidence.
-
-## Updating the process-wide Codex Skill
-
-Do not replace a shared installed Skill while any consuming project is active.
-For a changed Skill manifest, enumerate the complete consuming fleet with
-repeated `--workspace` arguments:
+## Detect and apply project profiles
+
+Preview deterministic, project-local commands, or atomically adopt only
+high-confidence candidates:
 
 ```bash
-node ./scripts/runkit-contract/install-codex-skill.mjs install \
-  --repository /absolute/path/to/owlrunkit-package \
-  --target /absolute/path/to/installed/owlcoda-runkit \
-  --archive /absolute/path/to/skill-archives \
-  --workspace /absolute/project-a \
-  --workspace /absolute/project-b
+owlrunkit profiles detect --workspace . --dry-run
+owlrunkit profiles detect --workspace . --apply
+owlrunkit profiles validate --workspace .
 ```
 
-The update is refused before global or project mutation if any listed project
-is active or invalid. A successful update records the exact prior Skill
-identity and each original project config in an append-only receipt. Restore
-that exact state with:
+`--apply` is create-only. It refuses ambiguous or low-confidence candidates,
+source drift, symlinks, and launchers that do not resolve to exact local files.
+It directly supports lock-bound npm plus exact project-installed pnpm, Yarn,
+and Bun launchers. A PATH-only package manager remains review-required. It
+never silently replaces an existing profile set.
+
+## Choose No RunKit, Quick, or Formal
+
+Route explicit risk facts before starting work:
 
 ```bash
-node ./scripts/runkit-contract/install-codex-skill.mjs restore \
-  --target /absolute/path/to/installed/owlcoda-runkit \
-  --archive /absolute/path/to/skill-archives \
-  --receipt /absolute/path/to/skill-upgrade-receipt.json
+owlrunkit assurance route --workspace . \
+  --request ./scripts/runkit-contract/templates/assurance-request.json
 ```
 
-`recover-active` is reserved for a fleet already drifted by an older unsafe
-replacement. It accepts only an archived Skill whose Core identity exactly
-matches every affected config and active execution pin, leaves all project
-bytes untouched, and writes a recovery receipt.
+- **No RunKit** is for work that needs neither a reusable receipt nor controlled
+  writes.
+- **Quick Verification** is for one low-risk, source-bound command that needs a
+  reusable receipt but no writer lease or Formal acceptance.
+- **Formal Delivery** is for multi-writer, long-running, migration, integration,
+  release, production, funds, destructive, or formally accepted work.
 
-Use Quick Verification for one low-risk source-bound command that needs a
-reusable receipt but no writer lease or Formal acceptance. Use Formal Delivery
-for multi-writer, long-running, migration, integration, release, production,
-funds, or formally accepted work. A Quick receipt cannot become Formal
-acceptance, and accepted never grants Git or release authority.
+The router fails closed to Formal when required risk facts are incomplete.
+Quick receipts cannot become Formal acceptance, and Formal acceptance does not
+grant Git, release, publish, deploy, or business authority.
 
-The package also includes the read-only verifier:
+Run Quick with:
 
 ```bash
-owlrunkit-attest /absolute/path/to/receipt.json
+owlrunkit quick-verify --workspace . -- npm test
 ```
 
-RunKit belongs to the OwlCoda product family and source repository, but its
-npm version is independent from the `owlcoda` CLI version.
+## Formal Delivery in three commands
+
+Given a Goal Contract and the paths this work item may write, the happy path is:
+
+```bash
+NODE_BIN="$(node -p 'process.execPath')"
+
+owlrunkit formal start --workspace . --run-id release-001 \
+  --goal .owlcoda/runkit/goal.json --owned-path 'src/**'
+
+owlrunkit formal check --workspace . --run-id release-001 \
+  --check-id source-syntax -- "$NODE_BIN" --check src/index.js
+
+owlrunkit formal finish --workspace . --run-id release-001 \
+  --decision accepted
+```
 
-RunKit does not grant Git, release, publish, deploy, or business authority.
-Those remain explicit external decisions even when verification passes.
+`formal start` creates the execution and exact writer lease. Each `formal check`
+adds source-bound evidence without rebuilding the execution. `formal finish`
+performs the final source-drift, evidence, permission, acceptance, closeout,
+and lease-release gates in one command. Create a related execution only when
+the authorized permission scope really changes. Repeating the same `check` or
+`finish` command resumes exact create-only artifacts after an interruption;
+different bytes fail closed.
+
+Formal accepted evidence currently admits only the built-in Node syntax check
+shown above: the exact `process.execPath`, `--check`, and an ordinary workspace
+file. Profile, package-manager, wrapper, and custom commands are rejected
+before spawn because RunKit does not yet enforce a filesystem-write and network
+sandbox for them. Existing full verification and legacy `verify` commands
+remain available for controlled execution, but their deny rules are not
+sandbox-equivalent and their output is not silently promoted into this Formal
+accepted-evidence path.
+
+Use `owlrunkit status --workspace .` for a concise human view of what is ready,
+what has not happened, how many gates remain, and the next allowed action.
+
+## Freeze a dirty worktree safely
+
+`SourceCandidateV2` makes a dirty but precisely bounded candidate a first-class
+artifact. It binds the baseline, exact owned-path closure, source manifest,
+and payload bytes without requiring a Git commit.
+
+```bash
+owlrunkit candidate freeze --workspace . --run-id release-001 \
+  --from-lease delivery --candidate-id rc-001
+owlrunkit candidate verify --workspace . \
+  --candidate .owlcoda/runkit/executions/release-001/source-candidates/rc-001.json
+owlrunkit candidate materialize --workspace . \
+  --candidate .owlcoda/runkit/executions/release-001/source-candidates/rc-001.json \
+  --target-workspace /absolute/clean/materialization
+```
+
+Materialization is create-only and verifies every byte. It applies payloads in
+a sibling staging checkout, then atomically switches the target directory.
+Write or mode failures roll back to the byte-exact clean target, and an
+interrupted switch is recovered from its transaction journal on the next
+invocation. Release reconstruction can therefore compare a clean workspace
+with the frozen candidate instead of requiring the working tree to be
+committed first.
+
+## Register and automatically discover a fleet
+
+Register every coverage root once. Later discovery and process-wide migration
+commands use the persistent registry automatically:
+
+```bash
+owlrunkit fleet register-root --fleet-root /absolute/projects
+owlrunkit fleet register-root --fleet-root /absolute/other-projects
+owlrunkit fleet discover
+```
+
+The registry lives under the user-owned OwlCoda home. RunKit recursively
+discovers projects inside every registered root, rejects an unreachable root,
+and freezes the exact workspace list before a shared Skill or Core change.
+Explicit `--fleet-root` and `--fleet-manifest` remain available for bounded
+one-off operations. Completeness is intentionally limited to registered roots;
+RunKit does not claim machine-wide protection for an unregistered location.
+
+## Upgrade a self-hosted Core
+
+Core successor separates an immutable candidate and fleet-wide plan from the
+Owner-authorized migration:
+
+```bash
+owlrunkit core-successor plan --workspace . --plan-id core-016 \
+  --run-id release-001 --from-lease delivery --candidate-id rc-001
+
+owlrunkit core-successor apply --workspace . \
+  --plan .owlcoda/runkit/core-successors/core-016/plan.json \
+  --owner-authority ./owner-core-successor-authority.json \
+  --receipt-id core-016-apply
+```
+
+Planning materializes the complete `SourceCandidateV2` in a clean workspace,
+requires its computed Core identity to equal the proposed successor, and freezes
+the automatically discovered registered fleet. Apply rediscovers the same
+fleet, verifies the frozen plan and Ed25519-signed Owner authority against the
+fixed user trust store, supports mixed prior Core identities, and writes
+append-only per-project migration receipts. Unsigned V1 authority is historical
+evidence only and cannot execute a migration.
+
+## Two-stage deployment and remote adapter
+
+Build and verification stay separate from the later permission to change a
+machine:
+
+```bash
+owlrunkit deployment prepare --workspace . --run-id build-001 \
+  --artifact dist/app.tgz --media-type application/gzip \
+  --owner-decision ./owner-deployment-decision.json \
+  --output .owlcoda/runkit/deployments/app-prepare.json
+
+owlrunkit deployment execute --workspace . \
+  --prepare .owlcoda/runkit/deployments/app-prepare.json \
+  --owner-decision ./owner-deployment-decision.json \
+  --owner-authority ./deployment-owner-authority.json \
+  --manifest ./remote-deployment-manifest.json
+
+# Resume the automatic child after an interrupted or indeterminate stage.
+owlrunkit deployment execute --workspace . --resume \
+  --prepare .owlcoda/runkit/deployments/app-prepare.json \
+  --owner-decision ./owner-deployment-decision.json \
+  --owner-authority ./deployment-owner-authority.json \
+  --manifest ./remote-deployment-manifest.json
+```
+
+`deployment_prepare` freezes the accepted source artifact, build artifact, and
+canonical `OwnerDeploymentDecisionV1` hash without granting deployment. The
+decision explicitly states clean install versus in-place update, existing
+asset and data authority, rollback semantics, service activation, baseline
+cut, and destructive scope; missing high-risk fields fail closed. A Formal
+`SourceCandidateV2`, including an
+ordinary modification or deletion-only candidate, remains the first-class
+source artifact through verification, accepted closeout, prepare, and lineage.
+Legacy accepted runs that use a DeliveryPacket remain compatible.
+`deployment_execute` requires a separate active execution
+and signed V2 Owner authority that binds the prepare receipt, independent Owner
+decision, and complete remote intent. Before creating the child or lease,
+RunKit compiles the decision against the Goal, prepare receipt, manifest, and
+authority. Conflicts stop before any executable child or remote command. The
+default command creates the child execution, goal, lease,
+profile, resource preflight, lineage, and result automatically. Supplying a
+fully assembled `--request`, `--lineage-output`, and `--output` remains an
+advanced compatibility path for controllers that already own those artifacts.
+
+The standard remote deployment adapter models first install and update
+separately. Its contract binds the VM host key and machine identity, create-only
+upload, ordered remote stages, before/after state, exact file hashes, explicit
+deletion allowlists, and remote smoke checks. A failure receipt identifies the
+exact stage reached; destructive deletion is impossible unless both the
+manifest and Owner-authorized execution permit it. Before every stage, RunKit
+revalidates the child execution, lease, preflight, engine pin, and lineage.
+
+Every external stage invocation has create-only before/after journal entries
+under the deployment child. The journal binds the deployment lineage, remote
+manifest, execute request, and adapter identity. Resume validates the complete
+journal and reconciles remote truth before proceeding. Interrupted upload,
+hash-check, identity, and smoke stages may be rerun because their contracts are
+idempotent. Interrupted install, service, or proxy stages are never replayed
+unless read-only reconciliation proves the expected state. Otherwise RunKit
+returns `reconciliation_required`, keeps the existing child and lease active,
+and requires the same `deployment execute --resume` path after the remote state
+is reconciled.
+
+`--resume` is limited to the same child and same Owner decision. If the bound
+decision is replaced by a decision that explicitly supersedes it, RunKit sends
+no remote command, releases the old child lease, and appends a blocked
+`closed_superseded` closeout with `businessGoalIncomplete=true` and
+`nextAllowedAction=plan_replacement_execution`. RunKit does not automatically
+invent the replacement execution. Qualification evidence may remain reusable,
+but rollback, remote intent, and Owner authority bound to the old decision do
+not.
+
+The remote manifest can select either adapter path:
+
+- `kind: "builtin_ssh"` uses RunKit's built-in, argv-only SSH adapter. The
+  manifest binds the exact Core adapter bytes, project-owned `known_hosts`
+  bytes through `target.hostKeySha256`, SSH executable bytes, opaque credential
+  reference and authentication mode, target identity, a caller-provided remote
+  helper path/protocol/version/capability descriptor, and structured install,
+  systemd, Nginx, and smoke contracts. Credential bytes are never written to
+  the manifest or result. Before every SSH or reconciliation invocation, RunKit
+  revalidates `known_hosts`, the SSH executable, and any identity file as
+  regular non-symlink files with the same real path and exact SHA-256 bytes.
+  Before upload or any later side effect, `identity_preflight` requires the
+  helper to return the exact declared protocol, version, and
+  `["execute", "reconcile"]` capability set. A mismatch fails closed.
+
+  This npm package is the SSH client and protocol enforcer; it does not contain
+  or install the privileged `owlrunkit-remote-helper` on a target VM. The
+  operator must install and audit that helper separately, then bind its exact
+  descriptor in the manifest. The handshake proves compatibility with the
+  trusted target response, not the provenance of a host already controlled by
+  an attacker. Therefore built-in SSH is not an out-of-the-box VM deployment
+  capability.
+- `kind: "process"` runs an exact externally supplied adapter executable and
+  preserves the existing JSON stage protocol. A transport timeout, nonzero exit,
+  or invalid output is indeterminate rather than a proven remote failure, so
+  the stage journal drives the same safe resume rules. Manifests created before
+  0.16 may omit `kind`; they remain process-adapter manifests.
+
+For `identity_file` authentication, the manifest contains only the canonical
+local file path and SHA-256 binding; the private key bytes are never persisted
+by RunKit. Agent authentication stores only its opaque `agent:`, `keychain:`,
+or `vault:` reference.
+
+## Shared Skill upgrades
+
+Process-wide Codex Skill updates automatically use the registered fleet:
+
+```bash
+node ./scripts/runkit-contract/install-codex-skill.mjs install \
+  --repository /absolute/path/to/owlrunkit-package \
+  --target /absolute/path/to/installed/owlcoda-runkit \
+  --archive /absolute/path/to/skill-archives
+```
+
+The installer stops before any mutation when the registry is missing, a
+registered root is unreachable, a discovered project is invalid, or the fleet
+contains active work. Historical closed leases remain evidence but do not
+masquerade as active writers. Restore and drift recovery remain receipt-bound
+and preserve project history.
+
+The package also includes the read-only verifier:
+
+```bash
+owlrunkit-attest /absolute/path/to/receipt.json
+```
 
 ## Requirements
 
 - Node.js 20.19 or newer
 - a local project directory
-- network access only for explicit `doctor` registry diagnostics and `adopt`;
-  normal verification and recovery remain local
+- network access only for explicit registry diagnostics and adoption; normal
+  verification, fleet discovery, recovery, and attestation remain local
+
+OwlRunKit belongs to the OwlCoda product family and source repository, but its
+npm version is independent from the `owlcoda` CLI version.
 
 ## License