owlrunkit 0.16.0 → 0.17.0

package/scripts/runkit-contract/formal-workflow.mjs

@@ -6,6 +6,7 @@ import {
   realpathSync,
 } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   acceptedCloseoutVerificationIssues,
@@ -33,6 +34,16 @@ import {
 } from "./source-candidate.mjs";
 import { validateReceiptLineage } from "./receipt-lineage.mjs";
 import { verificationContextFingerprint } from "./verification-context.mjs";
+import {
+  runVerificationEnvelopeV1,
+  validateVerificationEnvelopeV1,
+  verifyVerificationEnvelopeReceiptV1,
+} from "./verification-envelope.mjs";
+
+const VERIFICATION_ENVELOPE_CHECKER = fileURLToPath(new URL(
+  "./verification-envelope-check.mjs",
+  import.meta.url,
+));
 
 const FORBIDDEN_EXTERNAL_TOOLS = new Set([
   "curl",
@@ -623,6 +634,184 @@ export function recordFormalCheckV1(options) {
   );
 }
 
+async function recordFormalEnvelopeCheckWithinControlTransaction({
+  workspaceRoot,
+  runId,
+  workItemId,
+  checkId,
+  envelope,
+  hooks = {},
+}) {
+  safeIdentifier(checkId, "checkId");
+  const root = realpathSync(workspaceRoot);
+  const { executionRoot, pinGate } = loadActiveExecution(root, runId);
+  if (pinGate.status !== "valid") return { ...pinGate, authorizationGranted: false };
+  const validatedEnvelope = validateVerificationEnvelopeV1({
+    workspaceRoot: root,
+    envelope,
+  });
+  const receiptPath = path.join(checkRoot(executionRoot), `${checkId}.json`);
+  const candidateResult = resumeOrFreezeCandidate({
+    workspaceRoot: root,
+    executionRoot,
+    runId,
+    workItemId,
+    checkId,
+  });
+  const candidate = candidateResult.candidate;
+  if (candidate.status !== "source_candidate_frozen") return candidate;
+  hooks.afterCandidatePersist?.();
+  const candidateDocument = readJson(path.join(root, candidate.candidatePath));
+  const envelopePath = path.join(
+    executionRoot,
+    "formal-envelopes",
+    `${checkId}.json`,
+  );
+  const envelopeResult = writeOrResumeExactJson(
+    envelopePath,
+    validatedEnvelope.envelope,
+    "Formal Verification Envelope",
+  );
+  const envelopeArtifactRoot = path.join(
+    executionRoot,
+    "verification-envelopes",
+    checkId,
+  );
+  const envelopeReceipt = await runVerificationEnvelopeV1({
+    workspaceRoot: root,
+    envelope: envelopeResult.value,
+    artifactRoot: envelopeArtifactRoot,
+  });
+  hooks.afterEnvelopePersist?.();
+  const commandArgv = [
+    realpathSync(process.execPath),
+    VERIFICATION_ENVELOPE_CHECKER,
+    "--workspace",
+    root,
+    "--receipt",
+    envelopeReceipt.receiptPath,
+  ];
+  const verificationCommandPolicy = {
+    schemaVersion: "OwlCodaRunKitFormalVerificationCommandPolicyV1",
+    mode: "verification_envelope_v1",
+    riskClassification: "enforced_verification_envelope",
+    profileCommandIds: [],
+    executable: commandArgv[0],
+    argv: commandArgv.slice(1),
+    envelopeSha256: validatedEnvelope.envelopeSha256,
+    envelopeReceiptSha256: envelopeReceipt.receiptSha256,
+    authorizationGranted: false,
+  };
+  const context = derivedVerificationContext(root);
+  const request = {
+    schemaVersion: "OwlCodaRunKitSnapshotRequestV1",
+    snapshotId: `${checkId}-snapshot`,
+    mode: "project",
+    targetRoot: root,
+    cwd: ".",
+    executable: verificationCommandPolicy.executable,
+    argv: verificationCommandPolicy.argv,
+    launcherVersion: "owlrunkit-formal-envelope-v1",
+    toolVersions: structuredClone(context.toolchains),
+    selectedPaths: candidateDocument.sourceManifest.entries
+      .filter((entry) => entry.operation !== "deleted")
+      .map((entry) => entry.path)
+      .sort(),
+    statusMode: "porcelain-v1-z-untracked-all-runkit-excluded",
+    verificationContext: context,
+  };
+  const requestPath = path.join(
+    executionRoot,
+    "formal-check-requests",
+    `${checkId}.json`,
+  );
+  const requestResult = writeOrResumeExactJson(
+    requestPath,
+    request,
+    "Formal check request",
+  );
+  hooks.afterRequestPersist?.();
+  const snapshotResult = resumeSnapshot({
+    workspaceRoot: root,
+    executionRoot,
+    runId,
+    request: requestResult.value,
+    candidateDocument,
+  });
+  const snapshot = snapshotResult.snapshot;
+  hooks.afterSnapshotPersist?.();
+  const savedSnapshot = readJson(path.join(root, snapshot.snapshotPath));
+  const existingReceipt = existsSync(receiptPath)
+    ? readRegularJson(receiptPath, "Formal check receipt")
+    : null;
+  const sequence = existingReceipt?.sequence
+    ?? readChecks(executionRoot).length + 1;
+  const status = snapshot.status === "snapshot_passed"
+    && envelopeReceipt.formalEligible
+    ? "formal_check_passed"
+    : "formal_check_failed";
+  const receipt = {
+    schemaVersion: "OwlCodaRunKitFormalCheckV1",
+    runId,
+    checkId,
+    sequence,
+    status,
+    candidatePath: candidate.candidatePath,
+    candidateSha256: candidate.candidateSha256,
+    payloadSha256: candidate.payloadSha256,
+    sourceFingerprint: candidate.sourceFingerprint,
+    verificationContext: context,
+    verificationContextFingerprint: verificationContextFingerprint(context),
+    snapshotRequestPath: relativeToWorkspace(root, requestPath),
+    snapshotPath: snapshot.snapshotPath,
+    commandExitCode: savedSnapshot.command.exitCode,
+    verificationCommandPolicy: {
+      schemaVersion: verificationCommandPolicy.schemaVersion,
+      mode: verificationCommandPolicy.mode,
+      riskClassification: verificationCommandPolicy.riskClassification,
+      profileCommandIds: verificationCommandPolicy.profileCommandIds,
+      envelopeSha256: verificationCommandPolicy.envelopeSha256,
+      envelopeReceiptSha256: verificationCommandPolicy.envelopeReceiptSha256,
+      authorizationGranted: false,
+    },
+    envelopePath: relativeToWorkspace(root, envelopePath),
+    envelopeSha256: validatedEnvelope.envelopeSha256,
+    envelopeReceiptPath: relativeToWorkspace(root, envelopeReceipt.receiptPath),
+    envelopeReceiptSha256: envelopeReceipt.receiptSha256,
+    envelopeFormalEligible: envelopeReceipt.formalEligible,
+    finalized: false,
+    authorizationGranted: false,
+  };
+  const receiptResult = writeOrResumeExactJson(
+    receiptPath,
+    receipt,
+    "Formal check receipt",
+  );
+  hooks.afterReceiptPersist?.();
+  return {
+    ...receiptResult.value,
+    exitCode: status === "formal_check_passed" ? 0 : 2,
+    checkReceiptPath: relativeToWorkspace(root, receiptPath),
+    resumed: candidateResult.resumed
+      || envelopeResult.resumed
+      || envelopeReceipt.resumed
+      || requestResult.resumed
+      || snapshotResult.resumed
+      || receiptResult.resumed,
+  };
+}
+
+export function recordFormalEnvelopeCheckV1(options) {
+  const workspaceRoot = realpathSync(options.workspaceRoot);
+  return withControlTransaction(
+    workspaceRoot,
+    () => recordFormalEnvelopeCheckWithinControlTransaction({
+      ...options,
+      workspaceRoot,
+    }),
+  );
+}
+
 function finalizeFormalChecksWithinControlTransaction({
   workspaceRoot,
   runId,
@@ -651,6 +840,18 @@ function finalizeFormalChecksWithinControlTransaction({
   if (latest.status !== "formal_check_passed" || selected.length === 0) {
     throw new Error("Formal finish requires the latest source to have a passed check.");
   }
+  for (const check of selected) {
+    if (!check.envelopeReceiptPath) continue;
+    const verifiedEnvelope = verifyVerificationEnvelopeReceiptV1({
+      workspaceRoot: root,
+      receiptPath: path.join(root, check.envelopeReceiptPath),
+    });
+    if (!verifiedEnvelope.formalEligible
+      || verifiedEnvelope.receiptSha256 !== check.envelopeReceiptSha256
+      || verifiedEnvelope.envelopeSha256 !== check.envelopeSha256) {
+      throw new Error(`Formal finish requires a valid Formal-eligible envelope receipt: ${check.checkId}.`);
+    }
+  }
   const request = {
     schemaVersion: "OwlCodaRunKitFinalizeRequestV1",
     receiptId: `${finalizeId}-receipt`,

package/scripts/runkit-contract/lifecycle-orchestration.mjs

@@ -486,6 +486,7 @@ export function activeAcceptedGate({ workspaceRoot, runId }) {
     }
   }
   const distinctMatchingPackets = collapseByteIdenticalDeliveryCandidates(matchingPackets);
+  const declaredSourceArtifact = validated.active.receipt.sourceArtifact;
   let matchingCandidate = null;
   if (distinctMatchingPackets.length === 0) {
     const candidateRoot = path.join(executionRoot, "source-candidates");
@@ -524,7 +525,12 @@ export function activeAcceptedGate({ workspaceRoot, runId }) {
       candidates.map(({ candidate }) => candidate.sourceManifest.sha256),
     );
     if (manifestFingerprints.size === 1) {
-      [matchingCandidate] = candidates;
+      matchingCandidate = candidates.find(({ candidatePath }) => (
+        declaredSourceArtifact?.kind === "source_candidate_v2"
+        && declaredSourceArtifact.path
+          === relativeToWorkspace(workspaceRoot, candidatePath)
+        && declaredSourceArtifact.sha256 === sha256(readFileSync(candidatePath))
+      )) ?? candidates[0];
     }
   }
   if (
@@ -537,7 +543,6 @@ export function activeAcceptedGate({ workspaceRoot, runId }) {
     throw new Error("Accepted finish requires one fresh source binding matching the active verification gate; source drift remains unresolved.");
   }
   const [matchingPacket] = distinctMatchingPackets;
-  const declaredSourceArtifact = validated.active.receipt.sourceArtifact;
   if (declaredSourceArtifact !== undefined) {
     const selectedPath = matchingCandidate === null
       ? matchingPacket.packetPath

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

@@ -18,6 +18,9 @@ const OFFICIAL_CLI_ENTRYPOINT =
 const EXACT_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$/;
 const SHA256_REF = /^sha256:[a-f0-9]{64}$/;
 const TRUSTED_PRIOR_CORE_IDENTITIES = new Map([
+  ["0.16.0", new Set([
+    "sha256:320fb1d97b4459d1a14b0b67807dcf2bc6b03970492cb9fb2c6245b17912c81e",
+  ])],
   ["0.15.1", new Set([
     "sha256:e8ca57522a8e473da356ceb3768bb650267894638d450d5e49463ab6f51c752b",
   ])],

package/scripts/runkit-contract/project-control-parser.mjs

@@ -140,7 +140,40 @@ function allowedKeys(value, expected) {
   return Object.keys(value).every(key => expected.includes(key));
 }
 
-function inspectLeases(root, executionRoot, runId, contract) {
+function validateHistoricalLeaseOwnedPaths(paths, contract) {
+  try {
+    return contract.validateLeaseOwnedPaths(paths);
+  } catch {
+    if (!Array.isArray(paths) || paths.length === 0) throw new Error("invalid");
+    const normalized = [...new Set(paths.map(value => {
+      if (
+        typeof value !== "string"
+        || value.length === 0
+        || path.isAbsolute(value)
+        || path.win32.isAbsolute(value)
+        || value.includes("\\")
+      ) throw new Error("invalid");
+      const segments = value.split("/");
+      if (segments.some(segment => (
+        segment.length === 0 || segment === "." || segment === ".."
+      ))) throw new Error("invalid");
+      if (
+        value.startsWith(`${contract.runtimeRoot}/`)
+        && value !== `${contract.runtimeRoot}/profiles.json`
+      ) throw new Error("invalid");
+      return value;
+    }))].sort(compareCodeUnits);
+    return normalized;
+  }
+}
+
+function inspectLeases(
+  root,
+  executionRoot,
+  runId,
+  contract,
+  { historicalAccepted = false, expectedReleasedLeaseIds = null } = {},
+) {
   const leasesRoot = path.join(executionRoot, "leases");
   if (!hasFilesystemEntry(leasesRoot)) {
     return {
@@ -200,7 +233,9 @@ function inspectLeases(root, executionRoot, runId, contract) {
       issues.push(`Lease attempt is invalid: ${runId}/${entry.name}`);
     }
     try {
-      const ownedPaths = contract.validateLeaseOwnedPaths(lease.ownedPaths);
+      const ownedPaths = historicalAccepted
+        ? validateHistoricalLeaseOwnedPaths(lease.ownedPaths, contract)
+        : contract.validateLeaseOwnedPaths(lease.ownedPaths);
       if (ownedPaths.some(ownedPath => (
         ownedPath.includes("*")
         && (!ownedPath.endsWith("/**") || ownedPath.slice(0, -3).includes("*"))
@@ -232,6 +267,14 @@ function inspectLeases(root, executionRoot, runId, contract) {
     .map(lease => lease.workItemId)
     .filter(workItemId => typeof workItemId === "string")
     .sort(compareCodeUnits);
+  if (
+    historicalAccepted
+    && Array.isArray(expectedReleasedLeaseIds)
+    && JSON.stringify(releasedWorkItemIds)
+      !== JSON.stringify([...expectedReleasedLeaseIds].sort(compareCodeUnits))
+  ) {
+    issues.push(`Historical accepted released lease binding mismatch: ${runId}`);
+  }
   return {
     status: issues.length > 0
       ? "invalid"
@@ -337,6 +380,11 @@ function inspectCloseout(root, executionRoot, runId, pin, contract) {
       }
       : {}),
     core: issues.length === 0 ? closeout.artifact.core : null,
+    releasedLeaseIds: issues.length === 0
+      && payload.decision === "accepted"
+      && Array.isArray(payload.verification?.releasedLeaseIds)
+      ? [...payload.verification.releasedLeaseIds]
+      : null,
     issues,
   };
 }
@@ -746,7 +794,18 @@ export function parseProjectControlState({
       && contract.validateExecutionPin({ expected: pin, actual: currentCore }).status !== "valid";
     const preserveHistoricalLeases = lifecycle === "closed"
       && new Set(["blocked", "rejected"]).has(closeout.decision);
-    const inspectedLease = inspectLeases(root, executionRoot, runId, contract);
+    const inspectedLease = inspectLeases(
+      root,
+      executionRoot,
+      runId,
+      contract,
+      {
+        historicalAccepted: historical
+          && lifecycle === "closed"
+          && closeout.decision === "accepted",
+        expectedReleasedLeaseIds: closeout.releasedLeaseIds,
+      },
+    );
     const lease = preserveHistoricalLeases && inspectedLease.status !== "invalid"
       ? {
           ...inspectedLease,

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

@@ -65,6 +65,7 @@ import {
 import {
   finalizeFormalChecksV1,
   recordFormalCheckV1,
+  recordFormalEnvelopeCheckV1,
   resumeCompletedFormalFinishV1,
   validateLegacyVerificationSideEffectsV1,
 } from "./formal-workflow.mjs";
@@ -93,7 +94,10 @@ import {
 } from "./profile-onboarding.mjs";
 import {
   discoverFleet,
+  inspectFleetRegistry,
   registerFleetCoverageRoot,
+  replaceFleetRegistry,
+  rollbackFleetRegistry,
 } from "./fleet-discovery.mjs";
 import { routeRunKitAssuranceV1 } from "./assurance-router.mjs";
 import { deriveHumanStatusFromInspectV1 } from "./human-status.mjs";
@@ -132,6 +136,13 @@ import {
   runRegistryAdoption,
 } from "./registry-adoption.mjs";
 import { OFFICIAL_NPM_REGISTRY } from "./registry-adoption-gate.mjs";
+import {
+  appendTeamProjectEventV1,
+  buildTeamProjectTakeoverV1,
+  formatTeamProjectStatusHumanV1,
+  initializeTeamProjectV1,
+  readTeamProjectStatusV1,
+} from "./team-project.mjs";
 
 const TOP_LEVEL_HELP = `OwlRunKit ${CORE_VERSION}
 
@@ -162,20 +173,21 @@ Two-stage deployment
   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 .
-
+  owlrunkit fleet <register-root|inspect-registry> [options]
+  owlrunkit fleet replace-registry --request <file> --receipt <file> [--dry-run]
+  owlrunkit fleet rollback-registry --receipt <file> --rollback-receipt <file>
+  owlrunkit fleet discover; owlrunkit status --workspace .
+
+Agent team projects
+  owlrunkit project <init|assign|checkpoint|handoff|decision|capture|status|takeover> [options]
+  Durable Agent work, dependencies, decisions, gates, progress, and handoffs.
 Core successor
   owlrunkit core-successor <plan|apply|resume> --workspace . [...]
 
 Other onboarding commands:
-  owlrunkit profiles validate --workspace .
-  owlrunkit profiles impact --workspace . --changed <path>
+  owlrunkit profiles validate --workspace .; owlrunkit profiles impact --workspace . --changed <path>
   owlrunkit inspect --workspace . --json
-
-Quick receipts cannot become Formal acceptance.
-Formal accepted does not grant Git or release authority.
+Formal accepted does not grant Git or release authority; Quick cannot become Formal.
 `;
 
 const COMMAND_HELP = Object.freeze({
@@ -193,12 +205,33 @@ Required:
 `,
   fleet: `Usage:
   owlrunkit fleet register-root --fleet-root <directory>
+  owlrunkit fleet inspect-registry [--registry <file>]
+  owlrunkit fleet replace-registry --request <file> --receipt <file> [--registry <file>] [--dry-run]
+  owlrunkit fleet rollback-registry --receipt <file> --rollback-receipt <file> [--registry <file>]
   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 inspect-registry": `Usage:
+  owlrunkit fleet inspect-registry [--registry <file>]
+
+Reads the exact registry bytes, hashes, roots, and membership without mutation.
+`,
+  "fleet replace-registry": `Usage:
+  owlrunkit fleet replace-registry --request <file> --receipt <file>
+    [--registry <file>] [--dry-run]
+
+Atomically replaces a registry from an exact preimage and evidence-bound fleet
+membership. Coverage reduction requires explicit exclusion evidence.
+`,
+  "fleet rollback-registry": `Usage:
+  owlrunkit fleet rollback-registry --receipt <replacement-receipt.json>
+    --rollback-receipt <file> [--registry <file>]
+
+Restores the exact preimage recorded by a replacement receipt.
 `,
   "fleet discover": `Usage:
   owlrunkit fleet discover [--fleet-root <directory>] [--fleet-manifest <file>]
@@ -230,7 +263,12 @@ 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...]
+    --work-item <id> --check-id <id> --envelope <verification-envelope.json>
+  owlrunkit formal check --workspace <directory> --run-id <id>
+    --work-item <id> --check-id <id> --cwd <directory> -- <built-in-command> [args...]
+
+Verification Envelopes admit real project commands only when file, network,
+process, environment, output, timeout, and cleanup constraints are enforced.
 `,
   "formal finish": `Usage:
   owlrunkit formal finish --workspace <directory> --run-id <id>
@@ -299,6 +337,24 @@ profile, preflight, lineage, and result. --request is an advanced legacy path.
 
 Shows completed milestones, current state, remaining gates, and the next allowed
 action without granting any authority.
+`,
+  project: `Usage:
+  owlrunkit project init --workspace <directory> --definition <project.json>
+  owlrunkit project <assign|checkpoint|handoff|decision|capture> --workspace <directory> --request <event.json>
+  owlrunkit project status --workspace <directory> [--json]
+  owlrunkit project takeover --workspace <directory> --agent <id> [--json]
+
+Project status is derived from durable work items, Agent assignments,
+dependencies, decisions, checkpoints, integration gates, and evidence refs.
+No self-reported percentage is accepted.
+`,
+  "project status": `Usage:
+  owlrunkit project status --workspace <directory> [--json]
+`,
+  "project takeover": `Usage:
+  owlrunkit project takeover --workspace <directory> --agent <id> [--json]
+
+Builds a read-only blank-session recovery packet for one Agent.
 `,
 });
 
@@ -1564,6 +1620,7 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       "formal",
       "lease",
       "profiles",
+      "project",
     ]).has(command);
     const [action, ...nestedOptions] = nested ? optionValues : [null, ...optionValues];
     const helpRequested = optionValues.includes("--help")
@@ -1598,10 +1655,14 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         ? ["json", "verbose", "history"]
         : command === "init"
           ? ["json"]
+        : command === "project" && new Set(["status", "takeover"]).has(action)
+          ? ["json"]
           : command === "doctor" || command === "adopt" || command === "status"
             ? ["json"]
         : command === "profiles"
             ? ["json", "dry-run", "apply"]
+        : command === "fleet" && action === "replace-registry"
+          ? ["dry-run"]
         : command === "candidate"
           ? ["delivery-v1"]
         : command === "core-successor" && action === "resume"
@@ -1651,19 +1712,50 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
       if (action === "register-root") {
         const registered = await registerFleetCoverageRoot({
           fleetRoot: requireOption(options, "fleet-root"),
+          fleetRegistryPath: options.registry,
         });
         return {
           ...registered,
           exitCode: 0,
         };
       }
+      if (action === "inspect-registry") {
+        return {
+          ...await inspectFleetRegistry({
+            fleetRegistryPath: options.registry,
+          }),
+          exitCode: 0,
+        };
+      }
+      if (action === "replace-registry") {
+        return {
+          ...await replaceFleetRegistry({
+            replacementRequestPath: requireOption(options, "request"),
+            receiptPath: options.receipt,
+            dryRun: options["dry-run"] === true,
+            fleetRegistryPath: options.registry,
+          }),
+          exitCode: 0,
+        };
+      }
+      if (action === "rollback-registry") {
+        return {
+          ...await rollbackFleetRegistry({
+            replacementReceiptPath: requireOption(options, "receipt"),
+            rollbackReceiptPath: requireOption(options, "rollback-receipt"),
+            fleetRegistryPath: options.registry,
+          }),
+          exitCode: 0,
+        };
+      }
       if (action !== "discover") {
-        throw new Error("Usage: owlrunkit fleet <register-root|discover> [--fleet-root <directory> | --fleet-manifest <file> | --workspace-root <directory>]");
+        throw new Error("Usage: owlrunkit fleet <register-root|inspect-registry|replace-registry|rollback-registry|discover>");
       }
       const discovered = await discoverFleet({
         fleetRoots: options["fleet-root"] ?? null,
         fleetManifestPath: options["fleet-manifest"] ?? null,
         workspaceRoots: options["workspace-root"] ?? null,
+        fleetRegistryPath: options.registry ?? null,
       });
       return {
         ...discovered,
@@ -2172,10 +2264,30 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
         });
       }
       if (action === "check") {
+        const workItemId = options["work-item"] ?? options["from-lease"] ?? "delivery";
+        if (
+          options["work-item"] !== undefined
+          && options["from-lease"] !== undefined
+          && options["work-item"] !== options["from-lease"]
+        ) {
+          throw new Error("formal check work-item and legacy from-lease must match.");
+        }
+        if (options.envelope !== undefined) {
+          if (commandArgv.length > 0) {
+            throw new Error("formal check accepts either --envelope or an exact built-in command, not both.");
+          }
+          return await recordFormalEnvelopeCheckV1({
+            workspaceRoot: workspace(options),
+            runId: safeRunId(requireOption(options, "run-id")),
+            workItemId,
+            checkId: requireOption(options, "check-id"),
+            envelope: readJson(realpathSync(requireOption(options, "envelope"))),
+          });
+        }
         return recordFormalCheckV1({
           workspaceRoot: workspace(options),
           runId: safeRunId(requireOption(options, "run-id")),
-          workItemId: options["from-lease"] ?? "delivery",
+          workItemId,
           checkId: requireOption(options, "check-id"),
           cwd: options.cwd ?? ".",
           commandArgv,
@@ -2292,6 +2404,43 @@ export async function runCli(argv = process.argv.slice(2), runtimeHooks = {}) {
             ].join("\n"),
           );
     }
+    if (command === "project") {
+      const root = requireOption(options, "workspace");
+      if (action === "init") {
+        return initializeTeamProjectV1({
+          workspaceRoot: root,
+          definition: readJson(realpathSync(requireOption(options, "definition"))),
+        });
+      }
+      if (new Set(["assign", "checkpoint", "handoff", "decision", "capture"]).has(action)) {
+        return appendTeamProjectEventV1({
+          workspaceRoot: root,
+          event: readJson(realpathSync(requireOption(options, "request"))),
+        });
+      }
+      if (action === "status") {
+        const status = readTeamProjectStatusV1({ workspaceRoot: root });
+        return options.json === true
+          ? status
+          : withHumanOutput(status, formatTeamProjectStatusHumanV1(status));
+      }
+      if (action === "takeover") {
+        const takeover = buildTeamProjectTakeoverV1({
+          workspaceRoot: root,
+          agentId: requireOption(options, "agent"),
+        });
+        return options.json === true
+          ? takeover
+          : withHumanOutput(takeover, [
+              `${takeover.projectId}: ${takeover.objective}`,
+              `Agent: ${takeover.agentId}`,
+              `Responsibility: ${takeover.currentResponsibility?.workItemId ?? "none"}`,
+              `Next: ${takeover.nextAction ?? "none"}`,
+              "",
+            ].join("\n"));
+      }
+      throw new Error("Usage: owlrunkit project <init|assign|checkpoint|handoff|decision|capture|status|takeover> [options]");
+    }
     if (command === "profiles") {
       const root = requireOption(options, "workspace");
       if (action === "detect") {
@@ -2455,7 +2604,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|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]");
+    throw new Error("Usage: owlrunkit <init|doctor|adopt|assurance|fleet|profiles|project|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",