owlrunkit 0.15.0 → 0.16.0

package/scripts/runkit-contract/runkit-cli.mjs

@@ -52,12 +52,29 @@ import {
   restoreLeaseWithinControlTransaction,
   withControlTransaction,
 } from "./lease-lifecycle.mjs";
-import { writeJsonExclusiveAtomically } from "./provenance-common.mjs";
+import {
+  relativeToWorkspace,
+  safeRelativePath,
+  writeJsonExclusiveAtomically,
+} from "./provenance-common.mjs";
 import { createDeliveryFromLease } from "./delivery-create.mjs";
 import {
   activeAcceptedGate,
   runHighLevelVerify,
 } from "./lifecycle-orchestration.mjs";
+import {
+  finalizeFormalChecksV1,
+  recordFormalCheckV1,
+  resumeCompletedFormalFinishV1,
+  validateLegacyVerificationSideEffectsV1,
+} from "./formal-workflow.mjs";
+import {
+  freezeSourceCandidateV1,
+  freezeSourceCandidateV2,
+  materializeSourceCandidateV2,
+  verifySourceCandidateV1,
+  verifySourceCandidateV2,
+} from "./source-candidate.mjs";
 import { buildInspectSummary, formatInspectHuman } from "./inspect-presentation.mjs";
 import { attestQuickReceiptDetails } from "./quick-attest.mjs";
 import { readLocalQuickMetrics } from "./quick-metrics.mjs";
@@ -68,10 +85,42 @@ import {
   importOfflineReceipt,
 } from "./offline-store.mjs";
 import {
+  applyDetectedProfilesV2,
   detectProfiles,
+  detectProfilesV2,
   resolveProfilesImpact,
   validateProfiles,
 } from "./profile-onboarding.mjs";
+import {
+  discoverFleet,
+  registerFleetCoverageRoot,
+} from "./fleet-discovery.mjs";
+import { routeRunKitAssuranceV1 } from "./assurance-router.mjs";
+import { deriveHumanStatusFromInspectV1 } from "./human-status.mjs";
+import {
+  closeDeploymentExecuteChildRun,
+  createDeploymentExecuteChildRun,
+  createDeploymentExecuteLineageFromActiveRun,
+  createDeploymentPrepareReceipt,
+  createDeploymentPrepareReceiptFromClosedRun,
+  inspectDeploymentOwnerDecisionStateV1,
+} from "./deployment-workflow.mjs";
+import {
+  createRemoteDeploymentStageJournalV1,
+  executeRemoteDeployment,
+  validateRemoteDeploymentManifest,
+} from "./remote-deployment.mjs";
+import { createRemoteProcessAdapterV1 } from "./remote-process-adapter.mjs";
+import {
+  builtInSshRemoteAdapterIdentityV1,
+  createSshRemoteAdapterV1,
+} from "./ssh-remote-adapter.mjs";
+import { inspectProjectControlState } from "./project-control-state.mjs";
+import {
+  applyCoreSuccessorPlanV1,
+  createCoreSuccessorPlanFromFleetV1,
+  resumeCoreSuccessorPlanV1,
+} from "./core-successor.mjs";
 import {
   formatDoctorHuman,
   readAdoptionReadiness,
@@ -92,6 +141,8 @@ Usage:
 Start here:
   owlrunkit doctor --workspace .
   owlrunkit profiles detect --workspace . --dry-run
+  owlrunkit profiles detect --workspace . --apply
+  owlrunkit assurance route --workspace . --request <risk-facts.json>
   owlrunkit adopt --workspace . --exact owlrunkit@${CORE_VERSION}
 
 Quick Verification
@@ -99,11 +150,25 @@ Quick Verification
   Low-risk, source-bound reusable evidence without writer leases or acceptance.
 
 Formal Delivery
-  owlrunkit start --workspace . --run-id <id> --goal <file> \\
-    --work-item <id> --owned-path <path>
+  owlrunkit formal <start|check|finish> --workspace . --run-id <id> [...]
   Use for multi-writer, long-running, migration, integration, release, funds,
   production, or formal acceptance work.
 
+Frozen dirty source
+  owlrunkit candidate <freeze|verify|materialize> --workspace . [...]
+
+Two-stage deployment
+  owlrunkit deployment prepare --workspace . --run-id <accepted-run> --artifact <file> --media-type <type> --owner-decision <decision-v1.json> --output <receipt>
+  owlrunkit deployment execute --workspace . [--resume] --prepare <receipt> --owner-decision <decision-v1.json> --owner-authority <signed-v2.json> --manifest <remote.json>
+
+Fleet and status
+  owlrunkit fleet register-root --fleet-root <directory>
+  owlrunkit fleet discover
+  owlrunkit status --workspace .
+
+Core successor
+  owlrunkit core-successor <plan|apply|resume> --workspace . [...]
+
 Other onboarding commands:
   owlrunkit profiles validate --workspace .
   owlrunkit profiles impact --workspace . --changed <path>
@@ -111,9 +176,132 @@ Other onboarding commands:
 
 Quick receipts cannot become Formal acceptance.
 Formal accepted does not grant Git or release authority.
-Those always require separate explicit authorization.
 `;
 
+const COMMAND_HELP = Object.freeze({
+  assurance: `Usage:
+  owlrunkit assurance route --workspace <directory> --request <risk-facts.json>
+
+Selects none, Quick, or Formal from structured risk facts. It does not grant
+repository, release, deployment, or destructive authority.
+`,
+  "assurance route": `Usage:
+  owlrunkit assurance route --workspace <directory> --request <risk-facts.json>
+
+Required:
+  --request <file>       Structured assurance risk facts.
+`,
+  fleet: `Usage:
+  owlrunkit fleet register-root --fleet-root <directory>
+  owlrunkit fleet discover [--fleet-root <directory>] [--fleet-manifest <file>]
+`,
+  "fleet register-root": `Usage:
+  owlrunkit fleet register-root --fleet-root <directory>
+
+Registers one durable fleet coverage root for later no-argument discovery.
+`,
+  "fleet discover": `Usage:
+  owlrunkit fleet discover [--fleet-root <directory>] [--fleet-manifest <file>]
+    [--workspace-root <directory>]
+
+With no source option, discovers the complete fleet inside registered roots.
+`,
+  profiles: `Usage:
+  owlrunkit profiles detect --workspace <directory> [--dry-run | --apply]
+  owlrunkit profiles validate --workspace <directory>
+  owlrunkit profiles impact --workspace <directory> --changed <path>
+`,
+  "profiles detect": `Usage:
+  owlrunkit profiles detect --workspace <directory> [--dry-run | --apply]
+
+--dry-run reports deterministic candidates. --apply atomically adopts only a
+high-confidence unambiguous profile.
+`,
+  formal: `Usage:
+  owlrunkit formal start --workspace <directory> --run-id <id> [...]
+  owlrunkit formal check --workspace <directory> --run-id <id> -- <command>
+  owlrunkit formal finish --workspace <directory> --run-id <id>
+`,
+  "formal start": `Usage:
+  owlrunkit formal start --workspace <directory> --run-id <id>
+    --goal <goal.json> --work-item <id> --owned-path <path>
+
+Creates the execution and exact writer lease.
+`,
+  "formal check": `Usage:
+  owlrunkit formal check --workspace <directory> --run-id <id>
+    --work-item <id> --check-id <id> --cwd <directory> -- <command> [args...]
+`,
+  "formal finish": `Usage:
+  owlrunkit formal finish --workspace <directory> --run-id <id>
+
+Runs the final source, evidence, permission, closeout, and lease-release path.
+`,
+  candidate: `Usage:
+  owlrunkit candidate freeze --workspace <directory> --run-id <id>
+    --from-lease <id> --candidate-id <id>
+  owlrunkit candidate verify --workspace <directory> --candidate <file>
+  owlrunkit candidate materialize --workspace <directory> --candidate <file>
+    --target-workspace <directory>
+`,
+  "candidate freeze": `Usage:
+  owlrunkit candidate freeze --workspace <directory> --run-id <id>
+    --from-lease <id> --candidate-id <id>
+
+Freezes the exact dirty source manifest, including deletions and renames.
+`,
+  "candidate verify": `Usage:
+  owlrunkit candidate verify --workspace <directory> --candidate <file>
+`,
+  "candidate materialize": `Usage:
+  owlrunkit candidate materialize --workspace <directory> --candidate <file>
+    --target-workspace <directory>
+`,
+  deployment: `Usage:
+  owlrunkit deployment prepare --workspace <directory> --run-id <accepted-run>
+    --artifact <file> --media-type <type> --owner-decision <decision-v1.json> --output <receipt>
+  owlrunkit deployment execute --workspace <directory> --prepare <receipt>
+    --owner-decision <decision-v1.json> --owner-authority <signed-v2.json> --manifest <remote.json> [--resume]
+`,
+  "deployment prepare": `Usage:
+  owlrunkit deployment prepare --workspace <directory> --run-id <accepted-run>
+    --artifact <file> --media-type <type> --owner-decision <decision-v1.json> --output <receipt>
+`,
+  "deployment execute": `Usage:
+  owlrunkit deployment execute --workspace <directory> --prepare <receipt>
+    --owner-decision <decision-v1.json> --owner-authority <signed-v2.json> --manifest <remote.json> [--resume]
+
+The default happy path creates and closes the deployment child, goal, lease,
+profile, preflight, lineage, and result. --request is an advanced legacy path.
+`,
+  "core-successor": `Usage:
+  owlrunkit core-successor plan --workspace <directory> --plan-id <id> [...]
+  owlrunkit core-successor apply --workspace <directory> --plan <file>
+    --owner-authority <signed-v2.json> --receipt-id <id>
+  owlrunkit core-successor resume --workspace <directory> --plan <file>
+    --owner-authority <signed-v2.json> [...]
+`,
+  "core-successor plan": `Usage:
+  owlrunkit core-successor plan --workspace <directory> --plan-id <id>
+    --run-id <id> --from-lease <id> --candidate-id <id>
+    [--fleet-root <directory> | --fleet-manifest <file>]
+`,
+  "core-successor apply": `Usage:
+  owlrunkit core-successor apply --workspace <directory> --plan <file>
+    --owner-authority <signed-v2.json> --receipt-id <id>
+`,
+  "core-successor resume": `Usage:
+  owlrunkit core-successor resume --workspace <directory> --plan <file>
+    --owner-authority <signed-v2.json> [--from-receipt <file>]
+`,
+  status: `Usage:
+  owlrunkit status --workspace <directory> [--json]
+
+Shows completed milestones, current state, remaining gates, and the next allowed
+action without granting any authority.
+`,
+});
+
 function withHumanOutput(result, humanOutput) {
   Object.defineProperty(result, "humanOutput", {
     configurable: false,
@@ -216,6 +404,38 @@ function requireOption(options, name) {
   return value;
 }
 
+function readWorkspaceArtifact(root, value, label) {
+  const relativePath = safeRelativePath(value, label);
+  return readJson(realpathSync(path.join(root, relativePath)));
+}
+
+function writeWorkspaceArtifact(root, value, label, artifact) {
+  const relativePath = safeRelativePath(value, label);
+  const outputPath = path.join(root, relativePath);
+  writeJsonExclusiveAtomically(outputPath, artifact);
+  return relativeToWorkspace(root, outputPath);
+}
+
+function writeOrVerifyWorkspaceArtifact(root, value, label, artifact) {
+  const relativePath = safeRelativePath(value, label);
+  const outputPath = path.join(root, relativePath);
+  const expectedBytes = Buffer.from(`${JSON.stringify(artifact, null, 2)}\n`);
+  if (!pathEntryExists(outputPath)) {
+    writeJsonExclusiveAtomically(outputPath, artifact);
+    return relativeToWorkspace(root, outputPath);
+  }
+  const stat = lstatSync(outputPath);
+  if (
+    stat.isSymbolicLink()
+    || !stat.isFile()
+    || realpathSync(outputPath) !== outputPath
+    || !readFileSync(outputPath).equals(expectedBytes)
+  ) {
+    throw new Error(`${label} existing artifact does not match exact bytes.`);
+  }
+  return relativeToWorkspace(root, outputPath);
+}
+
 function safeRunId(value) {
   if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) || value === "." || value === "..") {
     throw new Error("run-id must use letters, digits, dot, underscore, or hyphen without path separators.");
@@ -249,6 +469,97 @@ function sha256(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+function exactRegularFile(filePath, expectedSha256, label) {
+  const resolved = realpathSync(filePath);
+  if (resolved !== filePath) {
+    throw new Error(`${label} must already use its canonical real path.`);
+  }
+  const stat = lstatSync(resolved);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`${label} must be a regular non-symlink file.`);
+  }
+  if (sha256(readFileSync(resolved)) !== expectedSha256) {
+    throw new Error(`${label} hash mismatch.`);
+  }
+  return resolved;
+}
+
+function declaredAdapterIdentity(adapter) {
+  return {
+    adapterId: adapter.adapterId,
+    version: adapter.version,
+    executable: adapter.executable,
+    sha256: adapter.sha256,
+  };
+}
+
+function createDeclaredRemoteAdapter(manifest, workspaceRoot) {
+  const { normalized } = validateRemoteDeploymentManifest(manifest);
+  const declaration = normalized.adapter;
+  if (declaration.kind !== "builtin_ssh") {
+    exactRegularFile(
+      declaration.executable,
+      declaration.sha256,
+      "Remote deployment adapter executable",
+    );
+    return createRemoteProcessAdapterV1({
+      identity: declaredAdapterIdentity(declaration),
+      workspaceRoot,
+    });
+  }
+  const builtInIdentity = builtInSshRemoteAdapterIdentityV1();
+  if (
+    JSON.stringify(declaredAdapterIdentity(declaration))
+    !== JSON.stringify(builtInIdentity)
+  ) {
+    throw new Error(
+      "Built-in SSH adapter declaration does not match this exact OwlRunKit Core.",
+    );
+  }
+  exactRegularFile(
+    declaration.executable,
+    declaration.sha256,
+    "Built-in SSH adapter module",
+  );
+  const knownHostsPath = exactRegularFile(
+    declaration.knownHostsPath,
+    normalized.target.hostKeySha256,
+    "Built-in SSH known_hosts file",
+  );
+  const sshExecutable = exactRegularFile(
+    declaration.sshExecutable,
+    declaration.sshExecutableSha256,
+    "Built-in SSH executable",
+  );
+  const credential = declaration.authentication.mode === "agent"
+    ? {
+        ref: normalized.credentialRef,
+        mode: "agent",
+      }
+    : {
+        ref: normalized.credentialRef,
+        mode: "identity_file",
+        identityFile: {
+          path: exactRegularFile(
+            declaration.authentication.identityFile.path,
+            declaration.authentication.identityFile.sha256,
+            "Built-in SSH identity file",
+          ),
+          sha256: declaration.authentication.identityFile.sha256,
+        },
+      };
+  return createSshRemoteAdapterV1({
+    target: normalized.target,
+    credential,
+    knownHostsPath,
+    workspaceRoot,
+    remoteHelper: declaration.remoteHelper,
+    stageContracts: declaration.stageContracts,
+    sshExecutable,
+    sshExecutableSha256: declaration.sshExecutableSha256,
+  });
+}
+
 function writeJson(filePath, value, flag = "wx") {
   writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { flag });
 }
@@ -811,6 +1122,10 @@ function inspect(options) {
   if (!configGate.valid) controlIssues.push(...configGate.issues);
   const config = controlIssues.length === 0 ? candidateConfig : null;
   const current = currentCoreIdentity();
+  const sharedControl = inspectProjectControlState({
+    workspaceRoot: root,
+    currentCore: current,
+  });
   const configCore = config
     ? validateExecutionPin({ expected: config.core, actual: current })
     : { status: "invalid_config", exitCode: 2, issues: [...controlIssues] };
@@ -819,7 +1134,7 @@ function inspect(options) {
     ? readdirSync(executionsRoot, { withFileTypes: true }).sort((left, right) => compareCodeUnits(left.name, right.name))
     : [];
   const runIds = executionEntries.map((entry) => entry.name);
-  const executions = executionEntries.map((entry) => {
+  const inspectedExecutions = executionEntries.map((entry) => {
     const runId = entry.name;
     const executionRoot = runtimePath(root, "executions", runId);
     const entryIssues = [];
@@ -907,11 +1222,57 @@ function inspect(options) {
       },
     };
   });
+  const sharedByRunId = new Map(
+    sharedControl.executions.map((execution) => [execution.runId, execution]),
+  );
+  const lifecycleParityIssues = [];
+  const executions = inspectedExecutions.map((execution) => {
+    const shared = sharedByRunId.get(execution.runId);
+    if (!shared) {
+      lifecycleParityIssues.push(
+        `Shared lifecycle state is missing execution: ${execution.runId}`,
+      );
+      return execution;
+    }
+    return {
+      ...execution,
+      lifecycle: shared.lifecycle,
+      historical: shared.historical,
+      closeout: {
+        ...execution.closeout,
+        ...(shared.closeout.statusCode === undefined
+          ? {}
+          : {
+            statusCode: shared.closeout.statusCode,
+            businessGoalIncomplete:
+              shared.closeout.businessGoalIncomplete,
+            replacementPlanRequired:
+              shared.closeout.replacementPlanRequired,
+            nextAllowedAction: shared.closeout.nextAllowedAction,
+          }),
+      },
+      recovery: {
+        ...execution.recovery,
+        lease: structuredClone(shared.lease),
+      },
+      controlState: {
+        lifecycle: shared.lifecycle,
+        historical: shared.historical,
+        closeout: structuredClone(shared.closeout),
+        lease: structuredClone(shared.lease),
+      },
+    };
+  });
   const invalidClosedIssues = executions
     .filter((execution) => execution.lifecycle === "closed" && execution.closeout?.status === "invalid")
     .flatMap((execution) => execution.closeout.issues ?? []);
-  const recoveryControlIssues = [...controlIssues, ...invalidClosedIssues];
-  const activeRunIds = executions.filter((execution) => execution.lifecycle !== "closed").map((execution) => execution.runId);
+  const recoveryControlIssues = [
+    ...controlIssues,
+    ...invalidClosedIssues,
+    ...sharedControl.issues,
+    ...lifecycleParityIssues,
+  ];
+  const activeRunIds = [...sharedControl.activeRunIds];
   const selectedRun = activeRunIds.length === 1
     ? executions.find((execution) => execution.runId === activeRunIds[0])
     : null;
@@ -946,7 +1307,9 @@ function inspect(options) {
           nextAllowedAction: "select_active_execution",
           authorizationGranted: false,
         };
-  if (recoveryControlIssues.length > 0 && activeRunIds.length > 0) {
+  if (sharedControl.status === "invalid") {
+    recovery = structuredClone(sharedControl.recovery);
+  } else if (recoveryControlIssues.length > 0 && activeRunIds.length > 0) {
     recovery = { ...recovery, nextAllowedAction: "repair_execution_artifacts" };
   }
   const result = {
@@ -959,6 +1322,7 @@ function inspect(options) {
     runtimeRoot: RUNTIME_ROOT,
     config,
     configCore,
+    controlState: sharedControl,
     controlIssues: recoveryControlIssues,
     runIds,
     executions,
@@ -1047,6 +1411,13 @@ function closeout(options) {
       sourceFingerprint: gate.sourceFingerprint,
       verificationContextFingerprint: gate.verificationContextFingerprint,
       selectedProfileIds: [...gate.selectedProfileIds],
+      ...(gate.lineage.active.receipt.sourceArtifact === undefined
+        ? {}
+        : {
+          sourceArtifact: structuredClone(
+            gate.lineage.active.receipt.sourceArtifact,
+          ),
+        }),
       leaseState: "released",
       releasedLeaseIds,
     };
@@ -1175,27 +1546,68 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       }, `owlrunkit ${CORE_VERSION}\n`);
     }
     const separatorIndex = rest.indexOf("--");
-    if (separatorIndex >= 0 && command !== "verify" && command !== "quick-verify") {
-      throw new Error("Only runkit verify accepts an exact command after --.");
+    const acceptsExactCommand = command === "verify"
+      || command === "quick-verify"
+      || (command === "formal" && rest[0] === "check");
+    if (separatorIndex >= 0 && !acceptsExactCommand) {
+      throw new Error("Only verify, quick-verify, and formal check accept an exact command after --.");
     }
     const optionValues = separatorIndex >= 0 ? rest.slice(0, separatorIndex) : rest;
     const commandArgv = separatorIndex >= 0 ? rest.slice(separatorIndex + 1) : [];
-    const nested = new Set(["lease", "delivery", "profiles"]).has(command);
+    const nested = new Set([
+      "assurance",
+      "candidate",
+      "core-successor",
+      "delivery",
+      "deployment",
+      "fleet",
+      "formal",
+      "lease",
+      "profiles",
+    ]).has(command);
     const [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
+    const helpRequested = optionValues.includes("--help")
+      || optionValues.includes("-h");
+    if (helpRequested) {
+      const normalizedAction = action === "--help" || action === "-h"
+        ? null
+        : action;
+      const help = COMMAND_HELP[
+        normalizedAction ? `${command} ${normalizedAction}` : command
+      ];
+      if (help) {
+        return withHumanOutput({
+          status: "help",
+          exitCode: 0,
+          authorizationGranted: false,
+        }, help);
+      }
+    }
     const options = parseOptions(nested ? nestedOptions : optionValues, {
       multi: command === "profiles" && action === "impact"
         ? ["changed"]
-        : (command === "lease" && action === "acquire") || command === "start"
+        : (command === "fleet" && action === "discover")
+          || (command === "core-successor" && action === "plan")
+          ? ["fleet-root", "workspace-root"]
+        : (command === "lease" && action === "acquire")
+          || command === "start"
+          || (command === "formal" && action === "start")
           ? ["owned-path"]
           : [],
       boolean: command === "inspect"
         ? ["json", "verbose", "history"]
         : command === "init"
           ? ["json"]
-          : command === "doctor" || command === "adopt"
+          : command === "doctor" || command === "adopt" || command === "status"
             ? ["json"]
-          : command === "profiles"
-            ? ["json", "dry-run"]
+        : command === "profiles"
+            ? ["json", "dry-run", "apply"]
+        : command === "candidate"
+          ? ["delivery-v1"]
+        : command === "core-successor" && action === "resume"
+          ? ["adopt-orphan-success-receipts"]
+        : command === "deployment" && action === "execute"
+          ? ["resume"]
         : new Set(["quick-verify", "quick-attest", "quick-metrics"]).has(command)
           ? ["json", "local"]
           : [],
@@ -1228,17 +1640,671 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         ? result
         : withHumanOutput(result, formatAdoptionHuman(result));
     }
+    if (command === "assurance") {
+      if (action !== "route") {
+        throw new Error("Usage: owlrunkit assurance route --request <risk-facts.json>");
+      }
+      const requestPath = realpathSync(requireOption(options, "request"));
+      return routeRunKitAssuranceV1(readJson(requestPath));
+    }
+    if (command === "fleet") {
+      if (action === "register-root") {
+        const registered = await registerFleetCoverageRoot({
+          fleetRoot: requireOption(options, "fleet-root"),
+        });
+        return {
+          ...registered,
+          exitCode: 0,
+        };
+      }
+      if (action !== "discover") {
+        throw new Error("Usage: owlrunkit fleet <register-root|discover> [--fleet-root <directory> | --fleet-manifest <file> | --workspace-root <directory>]");
+      }
+      const discovered = await discoverFleet({
+        fleetRoots: options["fleet-root"] ?? null,
+        fleetManifestPath: options["fleet-manifest"] ?? null,
+        workspaceRoots: options["workspace-root"] ?? null,
+      });
+      return {
+        ...discovered,
+        status: discovered.complete ? "discovered" : "incomplete",
+        exitCode: discovered.complete ? 0 : 2,
+      };
+    }
+    if (command === "core-successor") {
+      const root = workspace(options);
+      if (action === "plan") {
+        const fleetDiscoveryRequest = options["fleet-manifest"]
+          ? { fleetManifestPath: options["fleet-manifest"] }
+          : options["fleet-root"]
+            ? { fleetRoots: options["fleet-root"] }
+            : options["workspace-root"]
+              ? { workspaceRoots: options["workspace-root"] }
+              : {};
+        return await createCoreSuccessorPlanFromFleetV1({
+          controllerWorkspaceRoot: root,
+          planId: requireOption(options, "plan-id"),
+          ...(options.output ? { planPath: options.output } : {}),
+          sourceCandidateRequest: {
+            runId: safeRunId(requireOption(options, "run-id")),
+            workItemId: requireOption(options, "from-lease"),
+            candidateId: requireOption(options, "candidate-id"),
+          },
+          fleetDiscoveryRequest,
+        });
+      }
+      if (action === "apply") {
+        return await applyCoreSuccessorPlanV1({
+          controllerWorkspaceRoot: root,
+          planPath: requireOption(options, "plan"),
+          receiptId: requireOption(options, "receipt-id"),
+          ...(options.output ? { receiptPath: options.output } : {}),
+          ownerAuthority: readJson(
+            realpathSync(requireOption(options, "owner-authority")),
+          ),
+        });
+      }
+      if (action === "resume") {
+        const planPath = requireOption(options, "plan");
+        const adoptOrphans = options["adopt-orphan-success-receipts"] === true;
+        const receiptId = adoptOrphans
+          ? requireOption(options, "receipt-id")
+          : null;
+        return await resumeCoreSuccessorPlanV1({
+          controllerWorkspaceRoot: root,
+          planPath,
+          ...(options["from-receipt"]
+            ? { fromReceiptPath: options["from-receipt"] }
+            : {}),
+          ...(adoptOrphans
+            ? {
+                receiptId,
+                adoptOrphanSuccessReceipts: true,
+                ...(options.output ? { receiptPath: options.output } : {}),
+              }
+            : {}),
+          ownerAuthority: readJson(
+            realpathSync(requireOption(options, "owner-authority")),
+          ),
+        });
+      }
+      throw new Error(
+        "Usage: owlrunkit core-successor <plan|apply|resume> [options]",
+      );
+    }
+    if (command === "deployment") {
+      const root = workspace(options);
+      if (action === "prepare") {
+        let ownerDecision = null;
+        if (!options.request) {
+          const decisionRelativePath = safeRelativePath(
+            requireOption(options, "owner-decision"),
+            "deployment Owner decision",
+          );
+          const decisionPath = realpathSync(
+            path.join(root, decisionRelativePath),
+          );
+          if (decisionPath !== path.resolve(root, decisionRelativePath)) {
+            throw new Error(
+              "Deployment Owner decision must be a regular workspace file without symlink traversal.",
+            );
+          }
+          ownerDecision = readJson(decisionPath);
+        }
+        const receipt = options.request
+          ? createDeploymentPrepareReceipt(
+              readJson(realpathSync(requireOption(options, "request"))),
+            )
+          : createDeploymentPrepareReceiptFromClosedRun({
+              workspaceRoot: root,
+              prepareRunId: safeRunId(requireOption(options, "run-id")),
+              artifactPath: requireOption(options, "artifact"),
+              mediaType: requireOption(options, "media-type"),
+              ownerDecision,
+            });
+        const receiptPath = writeWorkspaceArtifact(
+          root,
+          requireOption(options, "output"),
+          "deployment prepare output",
+          receipt,
+        );
+        return {
+          status: "deployment_prepared",
+          exitCode: 0,
+          receiptPath,
+          receiptSha256: receipt.receiptSha256,
+          authorizationGranted: false,
+        };
+      }
+      if (action === "execute") {
+        const prepareReceipt = readWorkspaceArtifact(
+          root,
+          requireOption(options, "prepare"),
+          "deployment prepare receipt",
+        );
+        const manifestPath = realpathSync(requireOption(options, "manifest"));
+        const manifestBytes = readFileSync(manifestPath);
+        const manifest = JSON.parse(manifestBytes.toString("utf8"));
+        const automatic = options.request === undefined;
+        const resuming = options.resume === true;
+        if (resuming && !automatic) {
+          throw new Error(
+            "deployment execute --resume cannot be combined with --request.",
+          );
+        }
+        let generated = null;
+        let executeRequest;
+        if (automatic) {
+          const authorityRelativePath = safeRelativePath(
+            requireOption(options, "owner-authority"),
+            "deployment Owner authority",
+          );
+          const authorityPath = realpathSync(
+            path.join(root, authorityRelativePath),
+          );
+          if (authorityPath !== path.resolve(root, authorityRelativePath)) {
+            throw new Error(
+              "Deployment Owner authority must be a regular workspace file without symlink traversal.",
+            );
+          }
+          const ownerAuthority = {
+            path: authorityRelativePath,
+            sha256: sha256(readFileSync(authorityPath)),
+          };
+          const decisionRelativePath = safeRelativePath(
+            requireOption(options, "owner-decision"),
+            "deployment Owner decision",
+          );
+          const decisionPath = realpathSync(
+            path.join(root, decisionRelativePath),
+          );
+          if (decisionPath !== path.resolve(root, decisionRelativePath)) {
+            throw new Error(
+              "Deployment Owner decision must be a regular workspace file without symlink traversal.",
+            );
+          }
+          const ownerDecision = {
+            path: decisionRelativePath,
+            sha256: sha256(readFileSync(decisionPath)),
+          };
+          if (resuming) {
+            const runId = safeRunId(manifest.deploymentId);
+            const deploymentRoot = `${RUNTIME_ROOT}/deployments/${runId}`;
+            const executeRequestPath = `${deploymentRoot}/execute-request.json`;
+            const existingRequest = readWorkspaceArtifact(
+              root,
+              executeRequestPath,
+              "deployment execute request",
+            );
+            if (
+              existingRequest.executeRunId !== runId
+              || JSON.stringify(existingRequest.ownerAuthority)
+                !== JSON.stringify(ownerAuthority)
+              || existingRequest.ownerDecision?.path
+                !== ownerDecision.path
+            ) {
+              throw new Error(
+                "Deployment resume Owner authority or child request drifted.",
+              );
+            }
+            generated = {
+              runId,
+              executeRequest: existingRequest,
+              executeRequestPath,
+              lineagePath: `${deploymentRoot}/lineage.json`,
+              resultPath: `${deploymentRoot}/result.json`,
+            };
+          } else {
+            generated = createDeploymentExecuteChildRun({
+              workspaceRoot: root,
+              prepareReceipt,
+              remoteManifest: manifest,
+              ownerAuthority,
+              ownerDecision,
+            });
+          }
+          executeRequest = generated.executeRequest;
+        } else {
+          executeRequest = readJson(
+            realpathSync(requireOption(options, "request")),
+          );
+        }
+        const lineageOutput = automatic
+          ? generated.lineagePath
+          : requireOption(options, "lineage-output");
+        const resultOutput = automatic
+          ? generated.resultPath
+          : requireOption(options, "output");
+        let detectedSupersession = null;
+        try {
+          if (automatic) {
+            const initialDecisionState = inspectDeploymentOwnerDecisionStateV1({
+              workspaceRoot: root,
+              descriptor: executeRequest.ownerDecision,
+              expectedDecisionSha256:
+                prepareReceipt.ownerDecision?.decisionSha256,
+            });
+            if (initialDecisionState.status === "superseded") {
+              detectedSupersession = {
+                priorDecision: {
+                  decisionSha256:
+                    prepareReceipt.ownerDecision.decisionSha256,
+                },
+                replacementDecision: initialDecisionState.decision,
+              };
+              const error = new Error("owner_decision_superseded");
+              error.code = "owner_decision_superseded";
+              error.replacementDecision = initialDecisionState.decision;
+              throw error;
+            }
+          }
+          const lineage = createDeploymentExecuteLineageFromActiveRun({
+            workspaceRoot: root,
+            prepareReceipt,
+            executeRequest,
+            remoteManifest: manifest,
+            remoteManifestBytes: manifestBytes,
+            verifyOwnerAuthority:
+              runtimeHooks.verifyOwnerDeploymentAuthority,
+          });
+          const lineagePath = resuming
+            ? writeOrVerifyWorkspaceArtifact(
+                root,
+                lineageOutput,
+                "deployment lineage output",
+                lineage,
+              )
+            : writeWorkspaceArtifact(
+                root,
+                lineageOutput,
+                "deployment lineage output",
+                lineage,
+              );
+          if (
+            manifest.deploymentLineageSha256 !== null
+            && manifest.deploymentLineageSha256 !== lineage.lineageSha256
+          ) {
+            throw new Error("Remote deployment manifest lineage does not match the execute lineage.");
+          }
+          const boundManifest = {
+            ...manifest,
+            deploymentLineageSha256: lineage.lineageSha256,
+          };
+          if (
+            JSON.stringify(boundManifest.target) !== JSON.stringify(lineage.target.value)
+            || JSON.stringify(boundManifest.artifact) !== JSON.stringify(lineage.parent.artifact)
+          ) {
+            throw new Error("Remote deployment manifest target or artifact does not match the execute lineage.");
+          }
+          const remoteAdapter = createDeclaredRemoteAdapter(
+            boundManifest,
+            root,
+          );
+          const executeRequestPath = automatic
+            ? path.join(root, generated.executeRequestPath)
+            : realpathSync(requireOption(options, "request"));
+          const stageJournal = createRemoteDeploymentStageJournalV1({
+            journalRoot: path.join(
+              root,
+              RUNTIME_ROOT,
+              "deployments",
+              executeRequest.executeRunId,
+              "stage-journal",
+            ),
+            binding: {
+              deploymentId: executeRequest.executeRunId,
+              deploymentLineageSha256: lineage.lineageSha256,
+              remoteManifestSha256: sha256(manifestBytes),
+              executeRequestSha256: sha256(readFileSync(executeRequestPath)),
+              adapterIdentity: remoteAdapter.identity,
+            },
+          });
+          const result = await executeRemoteDeployment({
+            manifest: boundManifest,
+            adapter: remoteAdapter,
+            permissions: lineage.permissions,
+            stageJournal,
+            beforeStageGuard() {
+              const decisionState = inspectDeploymentOwnerDecisionStateV1({
+                workspaceRoot: root,
+                descriptor: executeRequest.ownerDecision,
+                expectedDecisionSha256:
+                  lineage.ownerDecision.decisionSha256,
+              });
+              if (decisionState.status === "superseded") {
+                detectedSupersession = {
+                  priorDecision: {
+                    decisionSha256:
+                      lineage.ownerDecision.decisionSha256,
+                  },
+                  replacementDecision: decisionState.decision,
+                };
+                const error = new Error("owner_decision_superseded");
+                error.code = "owner_decision_superseded";
+                throw error;
+              }
+              const currentLineage = createDeploymentExecuteLineageFromActiveRun({
+                workspaceRoot: root,
+                prepareReceipt,
+                executeRequest,
+                remoteManifest: manifest,
+                remoteManifestBytes: manifestBytes,
+                verifyOwnerAuthority:
+                  runtimeHooks.verifyOwnerDeploymentAuthority,
+              });
+              if (currentLineage.lineageSha256 !== lineage.lineageSha256) {
+                throw new Error(
+                  "Deployment child control state drifted during remote execution.",
+                );
+              }
+            },
+          });
+          if (result.status === "reconciliation_required") {
+            return {
+              ...result,
+              exitCode: 2,
+              runId: executeRequest.executeRunId,
+              executeRequestPath: generated?.executeRequestPath ?? null,
+              lineagePath,
+              resultPath: null,
+              stageJournalPath: relativePath(root, stageJournal.journalRoot),
+              closeoutDecision: null,
+              childRemainsActive: true,
+            };
+          }
+          if (automatic && result.status === "deployed") {
+            const finalLineage = createDeploymentExecuteLineageFromActiveRun({
+              workspaceRoot: root,
+              prepareReceipt,
+              executeRequest,
+              remoteManifest: manifest,
+              remoteManifestBytes: manifestBytes,
+              verifyOwnerAuthority:
+                runtimeHooks.verifyOwnerDeploymentAuthority,
+            });
+            if (finalLineage.lineageSha256 !== lineage.lineageSha256) {
+              throw new Error(
+                "Deployment child control state drifted before closeout.",
+              );
+            }
+          }
+          const resultPath = resuming
+            ? writeOrVerifyWorkspaceArtifact(
+                root,
+                resultOutput,
+                "remote deployment result output",
+                result,
+              )
+            : writeWorkspaceArtifact(
+                root,
+                resultOutput,
+                "remote deployment result output",
+                result,
+              );
+          const closeout = automatic
+            ? closeDeploymentExecuteChildRun({
+                workspaceRoot: root,
+                prepareReceipt,
+                executeRequest,
+                result,
+                resultPath,
+                ...(detectedSupersession === null
+                  ? {}
+                  : { supersession: detectedSupersession }),
+              })
+            : null;
+          return {
+            ...result,
+            exitCode: result.status === "deployed" ? 0 : 2,
+            runId: executeRequest.executeRunId,
+            executeRequestPath: generated?.executeRequestPath ?? null,
+            lineagePath,
+            resultPath,
+            ...(closeout ?? {}),
+          };
+        } catch (error) {
+          if (!automatic) throw error;
+          if (
+            error?.code === "owner_decision_superseded"
+            && detectedSupersession !== null
+          ) {
+            const result = {
+              schemaVersion: "OwlCodaRunKitDeploymentWorkflowFailureV1",
+              deploymentId: executeRequest.executeRunId,
+              status: "failed",
+              completedStages: [],
+              stoppedAtStage: "control_preflight",
+              failureCode: "owner_decision_superseded",
+              authorizationGranted: false,
+            };
+            const resultPath = resuming
+              ? writeOrVerifyWorkspaceArtifact(
+                root,
+                resultOutput,
+                "remote deployment result output",
+                result,
+              )
+              : writeWorkspaceArtifact(
+                root,
+                resultOutput,
+                "remote deployment result output",
+                result,
+              );
+            const closeout = closeDeploymentExecuteChildRun({
+              workspaceRoot: root,
+              prepareReceipt,
+              executeRequest,
+              result,
+              resultPath,
+              supersession: detectedSupersession,
+            });
+            return {
+              ...result,
+              exitCode: 2,
+              runId: executeRequest.executeRunId,
+              executeRequestPath: generated.executeRequestPath,
+              lineagePath: generated.lineagePath,
+              resultPath,
+              issues: [error.message],
+              ...closeout,
+            };
+          }
+          if (resuming) {
+            return {
+              schemaVersion: "OwlCodaRunKitDeploymentWorkflowFailureV1",
+              deploymentId: executeRequest.executeRunId,
+              status: "failed",
+              completedStages: [],
+              stoppedAtStage: "control_preflight",
+              failureCode: "deployment_resume_control_preflight_failed",
+              exitCode: 2,
+              runId: executeRequest.executeRunId,
+              executeRequestPath: generated.executeRequestPath,
+              lineagePath: generated.lineagePath,
+              resultPath: null,
+              closeoutDecision: null,
+              childRemainsActive: true,
+              issues: [error instanceof Error ? error.message : String(error)],
+              authorizationGranted: false,
+            };
+          }
+          const result = {
+            schemaVersion: "OwlCodaRunKitDeploymentWorkflowFailureV1",
+            deploymentId: executeRequest.executeRunId,
+            status: "failed",
+            completedStages: [],
+            stoppedAtStage: "control_preflight",
+            failureCode: "deployment_control_preflight_failed",
+            authorizationGranted: false,
+          };
+          const resultPath = writeWorkspaceArtifact(
+            root,
+            resultOutput,
+            "remote deployment result output",
+            result,
+          );
+          const closeout = closeDeploymentExecuteChildRun({
+            workspaceRoot: root,
+            prepareReceipt,
+            executeRequest,
+            result,
+            resultPath,
+          });
+          return {
+            ...result,
+            exitCode: 2,
+            runId: executeRequest.executeRunId,
+            executeRequestPath: generated.executeRequestPath,
+            lineagePath: generated.lineagePath,
+            resultPath,
+            issues: [error instanceof Error ? error.message : String(error)],
+            ...closeout,
+          };
+        }
+      }
+      throw new Error("Usage: owlrunkit deployment <prepare|execute> [options]");
+    }
+    if (command === "formal") {
+      if (action === "start") {
+        return startExecution({
+          ...options,
+          "work-item": options["work-item"] ?? "delivery",
+        });
+      }
+      if (action === "check") {
+        return recordFormalCheckV1({
+          workspaceRoot: workspace(options),
+          runId: safeRunId(requireOption(options, "run-id")),
+          workItemId: options["from-lease"] ?? "delivery",
+          checkId: requireOption(options, "check-id"),
+          cwd: options.cwd ?? ".",
+          commandArgv,
+        });
+      }
+      if (action === "finish") {
+        const decision = options.decision ?? "accepted";
+        if (!new Set(["accepted", "rejected", "blocked"]).has(decision)) {
+          throw new Error("decision must be accepted, rejected, or blocked.");
+        }
+        const root = workspace(options);
+        const runId = safeRunId(requireOption(options, "run-id"));
+        const finalizeId = options["finalize-id"] ?? "formal-final";
+        const resumed = resumeCompletedFormalFinishV1({
+          workspaceRoot: root,
+          runId,
+          finalizeId,
+          decision,
+        });
+        if (resumed !== null) return resumed;
+        let finalized = null;
+        if (decision === "accepted") {
+          finalized = finalizeFormalChecksV1({
+            workspaceRoot: root,
+            runId,
+            finalizeId,
+          });
+          if (finalized.status !== "accepted_passed") return finalized;
+        }
+        const finished = finishExecution({
+          ...options,
+          decision,
+        });
+        if (finished.status !== "finished") return finished;
+        return {
+          status: "formal_finished",
+          exitCode: 0,
+          runId: finished.runId,
+          decision,
+          snapshotCount: finalized?.snapshotCount ?? 0,
+          staleCheckCount: finalized?.staleCheckCount ?? 0,
+          sourceFingerprint: finalized?.sourceFingerprint ?? null,
+          activeReceiptSha256: finished.activeReceiptSha256,
+          closeoutArtifactSha256: finished.closeoutArtifactSha256,
+          releasedLeaseIds: finished.releasedLeaseIds,
+          authorizationGranted: false,
+        };
+      }
+      throw new Error("Usage: owlrunkit formal <start|check|finish> [options]");
+    }
+    if (command === "candidate") {
+      if (action === "freeze") {
+        const freezeCandidate = options["delivery-v1"] === true
+          ? freezeSourceCandidateV1
+          : freezeSourceCandidateV2;
+        return freezeCandidate({
+          workspaceRoot: workspace(options),
+          runId: safeRunId(requireOption(options, "run-id")),
+          workItemId: requireOption(options, "from-lease"),
+          candidateId: requireOption(options, "candidate-id"),
+        });
+      }
+      if (action === "verify") {
+        const root = workspace(options);
+        const candidatePath = requireOption(options, "candidate");
+        const candidate = readWorkspaceArtifact(
+          root,
+          candidatePath,
+          "source candidate",
+        );
+        if (candidate.schemaVersion === "OwlCodaRunKitSourceCandidateV2") {
+          return verifySourceCandidateV2({
+            workspaceRoot: root,
+            candidatePath,
+          });
+        }
+        return verifySourceCandidateV1({
+          workspaceRoot: root,
+          candidatePath,
+        });
+      }
+      if (action === "materialize") {
+        return materializeSourceCandidateV2({
+          workspaceRoot: workspace(options),
+          candidatePath: requireOption(options, "candidate"),
+          targetWorkspaceRoot: requireOption(options, "target-workspace"),
+        });
+      }
+      throw new Error("Usage: owlrunkit candidate <freeze|verify|materialize> [options]");
+    }
     if (command === "start") return startExecution(options);
     if (command === "plan") {
       const root = workspace(options);
       return withControlTransaction(root, () => plan(options));
     }
     if (command === "inspect") return inspect(options);
+    if (command === "status") {
+      const inspected = inspect({ ...options, json: true });
+      const status = deriveHumanStatusFromInspectV1(inspected);
+      return options.json === true
+        ? { ...status, exitCode: status.overall === "blocked" ? 2 : 0 }
+        : withHumanOutput(
+            { ...status, exitCode: status.overall === "blocked" ? 2 : 0 },
+            [
+              status.headline,
+              `Stage: ${status.stage}`,
+              `Completed: ${status.completedSteps.length > 0 ? status.completedSteps.join(", ") : "none"}`,
+              `Source/data readiness: ${status.milestones.sourceData.status}`,
+              `Release package: ${status.milestones.releasePackage.status}`,
+              `Remote/VM write: ${status.milestones.remoteVmWrite.status}`,
+              `Remaining gates: ${status.remainingGateCount}`,
+              `Next: ${status.nextAllowedAction}`,
+              "",
+            ].join("\n"),
+          );
+    }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");
       if (action === "detect") {
-        if (options["dry-run"] !== true) throw new Error("profiles detect requires --dry-run.");
-        return detectProfiles({ workspaceRoot: root });
+        if (options.apply === true && options["dry-run"] === true) {
+          throw new Error("profiles detect accepts either --apply or --dry-run, not both.");
+        }
+        if (options["dry-run"] === true) {
+          return detectProfiles({ workspaceRoot: root });
+        }
+        const detection = detectProfilesV2({ workspaceRoot: root });
+        return options.apply === true
+          ? applyDetectedProfilesV2({ workspaceRoot: root, detection })
+          : detection;
       }
       if (action === "validate") return validateProfiles({ workspaceRoot: root });
       if (action === "impact") {
@@ -1280,12 +2346,17 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       });
     }
     if (command === "verify") {
+      const root = workspace(options);
+      const cwd = options.cwd ?? ".";
+      validateLegacyVerificationSideEffectsV1({
+        commandArgv,
+      });
       return runHighLevelVerify({
-        workspaceRoot: workspace(options),
+        workspaceRoot: root,
         runId: safeRunId(requireOption(options, "run-id")),
         workItemId: requireOption(options, "from-lease"),
         verificationId: requireOption(options, "verification-id"),
-        cwd: options.cwd ?? ".",
+        cwd,
         commandArgv,
       });
     }
@@ -1384,7 +2455,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       return withControlTransaction(root, () => closeout(options));
     }
     if (command === "finish") return finishExecution(options);
-    throw new Error("Usage: owlrunkit <init|doctor|adopt|profiles|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
+    throw new Error("Usage: owlrunkit <init|doctor|adopt|assurance|fleet|profiles|status|formal|candidate|deployment|core-successor|start|verify|repair|offline-export|offline-import|quick-verify|quick-attest|quick-metrics|finish|plan|inspect|lease|delivery|coverage-adopt|resume|verify-plan|resource-preflight|snapshot|visual-smoke|finalize|ready-for-commit|closeout> [options]");
   } catch (error) {
     return {
       status: "invalid_input",
@@ -1414,7 +2485,12 @@ if (isDirectExecution(import.meta.url)) {
     && !argv.includes("--json")
     && process.stdout.isTTY === true;
   process.stdout.write(
-    typeof result.humanOutput === "string" && (!onboardingHumanCommand || interactiveOnboarding)
+    typeof result.humanOutput === "string"
+      && (
+        result.status === "help"
+        || !onboardingHumanCommand
+        || interactiveOnboarding
+      )
       ? result.humanOutput
       : humanInspect
         ? formatInspectHuman(result)