owlrunkit 0.20.0 → 0.21.0

package/scripts/runkit-contract/inspect-presentation.mjs

@@ -176,6 +176,62 @@ export function buildInspectSummary(
   };
 }
 
+function compactWarningSummary(projectDriver) {
+  const byCode = new Map();
+  for (const warning of projectDriver?.warnings ?? []) {
+    const current = byCode.get(warning.code) ?? {
+      code: warning.code,
+      count: 0,
+      blocking: warning.blocking === true,
+    };
+    current.count += 1;
+    current.blocking ||= warning.blocking === true;
+    byCode.set(warning.code, current);
+  }
+  return {
+    count: [...byCode.values()].reduce((total, group) => total + group.count, 0),
+    groups: [...byCode.values()].sort((left, right) => compareCodeUnits(left.code, right.code)),
+  };
+}
+
+export function buildInspectCompactV1(inspected) {
+  const projectDriver = inspected.projectDriver ?? null;
+  const summary = inspected.summary;
+  return {
+    schemaVersion: "OwlCodaRunKitInspectCompactV1",
+    status: "inspected_compact",
+    exitCode: inspected.exitCode,
+    projectTruthHash: projectDriver?.projectTruthHash ?? null,
+    progress: {
+      overall: projectDriver?.overall ?? null,
+      completedWorkItems: projectDriver?.counts?.completed ?? null,
+      totalWorkItems: projectDriver?.counts?.total ?? null,
+    },
+    dominantGap: {
+      code: summary.dominantGap.code,
+      reason: summary.dominantGap.reasons[0] ?? null,
+    },
+    ownerAgentId: projectDriver?.nextActorId
+      ?? projectDriver?.dominantGap?.agentId
+      ?? null,
+    nextAction: summary.recommendedNextAction ?? summary.nextAllowedAction,
+    warningSummary: compactWarningSummary(projectDriver),
+    execution: {
+      state: summary.currentExecution.state,
+      openCount: summary.currentExecution.openCount,
+      activeLeaseCount: summary.leases.activeCount,
+    },
+    authorityBoundary: {
+      git: false,
+      release: false,
+      deployment: false,
+      production: false,
+      business: false,
+    },
+    authorizationGranted: false,
+  };
+}
+
 function value(value) {
   if (value === null || value === undefined || value === "") return "none";
   return String(value);

package/scripts/runkit-contract/install-codex-skill.mjs

@@ -786,6 +786,7 @@ export async function runCli(argv = process.argv.slice(2)) {
         workspaceRoots: options.workspace ?? null,
         fleetManifestPath: options["fleet-manifest"] ?? null,
         fleetRoots: options["fleet-root"] ?? null,
+        fleetRegistryPath: options.registry ?? null,
       });
       return { exitCode: 0, ...output };
     }

package/scripts/runkit-contract/onboarding-bootstrap.mjs

@@ -46,6 +46,16 @@ const TRANSACTION_PATHS = Object.freeze([
   "adoption",
 ]);
 
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+}
+
+function requestedSuccessorSpec(value) {
+  return /^owlrunkit@[0-9]+\.[0-9]+\.[0-9]+$/u.test(value ?? "")
+    ? value
+    : null;
+}
+
 function pathEntryExists(filePath) {
   try {
     lstatSync(filePath);
@@ -301,6 +311,7 @@ export async function planOnboardingBootstrapV1({
 } = {}) {
   const root = resolveBoundedWorkspaceRoot(workspaceRoot);
   const issueCodes = [];
+  const requestedSuccessor = requestedSuccessorSpec(exactSpec);
   if (exactSpec !== EXACT_SPEC) issueCodes.push("bootstrap_exact_spec_required");
   const local = readLocalInstallBinding({ workspaceRoot: root });
   if (local.status !== "bound") {
@@ -385,6 +396,8 @@ export async function planOnboardingBootstrapV1({
     issueCodes: [...new Set(issueCodes)].sort(),
     nextCommand: issueCodes.length === 0
       ? `npx --no-install owlrunkit bootstrap --workspace ${JSON.stringify(root)} --exact ${EXACT_SPEC} --apply`
+      : issueCodes.includes("bootstrap_exact_spec_required") && requestedSuccessor !== null
+        ? `cd ${shellQuote(root)} && npm install --save-exact ${requestedSuccessor} && npx --no-install owlrunkit bootstrap --workspace ${shellQuote(root)} --exact ${requestedSuccessor} --dry-run`
       : "repair bootstrap preflight issues and rerun --dry-run",
     authorizationGranted: false,
   };
@@ -573,6 +586,7 @@ export async function applyOnboardingBootstrapV1({
       "doctor",
       () => runDoctor({
         workspaceRoot: root,
+        discoverSharedSkill: true,
         registryUrl: OFFICIAL_NPM_REGISTRY,
         registryClient,
       }),
@@ -677,6 +691,7 @@ export function formatOnboardingBootstrapHumanV1(result) {
   const issues = result.issueCodes?.join(", ") || "unknown issue";
   return [
     `Bootstrap blocked: ${issues}`,
+    ...(result.nextCommand ? [`Repair: ${result.nextCommand}`] : []),
     `Rollback: ${result.rollbackOutcome ?? "not_required"}.`,
     ...(result.receiptPath ? [`Receipt: ${result.receiptPath}`] : []),
     "No Git, release, deployment, production, or business authority was granted.",

package/scripts/runkit-contract/onboarding-doctor.mjs

@@ -1,12 +1,15 @@
 import {
   closeSync,
+  existsSync,
   fstatSync,
   lstatSync,
   openSync,
   readSync,
   realpathSync,
 } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
+import { userInfo } from "node:os";
 
 import {
   CORE_VERSION,
@@ -20,12 +23,19 @@ import {
 } from "./registry-adoption-gate.mjs";
 import { resolveProjectCli } from "./project-cli-resolver.mjs";
 import { inspectProjectControlState } from "./project-control-state.mjs";
+import {
+  inspectFleetForSkillChange,
+  inspectInstalledSkillCompatibility,
+} from "./install-codex-skill.mjs";
 
 const PACKAGE_NAME = "owlrunkit";
 const EXPECTED_VERSION = CORE_VERSION;
 const MAX_JSON_BYTES = 1_048_576;
 const MAX_JSON_DEPTH = 64;
 const MAX_JSON_NODES = 50_000;
+const PACKAGE_SKILL_RELATIVE = path.join(
+  "integrations", "codex", "skills", "owlcoda-runkit",
+);
 
 class StrictJsonParser {
   constructor(text, { maxDepth = MAX_JSON_DEPTH, maxNodes = MAX_JSON_NODES } = {}) {
@@ -286,6 +296,81 @@ export function readWorkspaceJsonBounded(root, relativePath, options) {
   return text === null ? null : parseJsonStrict(text, options);
 }
 
+function parsedSkillRoot(requestedRoot) {
+  if (typeof requestedRoot !== "string" || requestedRoot.length === 0) return null;
+  try {
+    const root = realpathSync(requestedRoot);
+    const skillText = readWorkspaceFileBounded(root, "SKILL.md");
+    const config = readWorkspaceJsonBounded(
+      root,
+      path.join("assets", "templates", "config.json"),
+    );
+    const version = skillText.match(/standalone `owlrunkit@(\d+\.\d+\.\d+)`/u)?.[1] ?? null;
+    const configCoreVersion = config?.core?.coreVersion ?? null;
+    return {
+      root,
+      skillPath: path.join(root, "SKILL.md"),
+      version,
+      configCoreVersion,
+      status: version !== null && configCoreVersion === version ? "readable" : "invalid",
+    };
+  } catch {
+    return {
+      root: path.resolve(requestedRoot),
+      skillPath: path.resolve(requestedRoot, "SKILL.md"),
+      version: null,
+      configCoreVersion: null,
+      status: "invalid",
+    };
+  }
+}
+
+function discoveredSharedSkillRoot() {
+  const requested = process.env.OWLCODA_RUNKIT_PROCESS_SKILL_ROOT;
+  if (typeof requested === "string" && requested.length > 0) return requested;
+  const candidates = [
+    path.join(homedir(), ".agents", "skills", "owlcoda-runkit"),
+    path.join(homedir(), ".codex", "skills", "owlcoda-runkit"),
+  ];
+  return candidates.find(candidate => existsSync(candidate)) ?? null;
+}
+
+export function inspectDoctorSkillStateV1({ packageRoot, sharedSkillRoot } = {}) {
+  const packageSkill = typeof packageRoot === "string"
+    ? parsedSkillRoot(path.join(packageRoot, PACKAGE_SKILL_RELATIVE))
+    : null;
+  const selectedSharedRoot = sharedSkillRoot ?? discoveredSharedSkillRoot();
+  const sharedSkill = selectedSharedRoot === null ? null : parsedSkillRoot(selectedSharedRoot);
+  const warningCodes = [];
+  if (sharedSkill === null) warningCodes.push("shared_skill_not_found");
+  else if (sharedSkill.status !== "readable") warningCodes.push("shared_skill_invalid");
+  else if (packageSkill?.status === "readable" && sharedSkill.version !== packageSkill.version) {
+    warningCodes.push("shared_skill_version_drift");
+  }
+  const packageIssueCodes = [];
+  if (packageSkill?.status !== "readable") warningCodes.push("package_skill_unavailable");
+  const skillDrift = warningCodes.includes("shared_skill_version_drift");
+  return {
+    schemaVersion: "OwlCodaRunKitDoctorSkillStateV1",
+    packageVersion: packageSkill?.version ?? null,
+    configCoreVersion: packageSkill?.configCoreVersion ?? null,
+    packageSkillVersion: packageSkill?.version ?? null,
+    packageSkillPath: packageSkill?.skillPath ?? null,
+    processSkillVersion: sharedSkill?.version ?? null,
+    processSkillPath: sharedSkill?.skillPath ?? null,
+    loadedSkillVersion: "unknown",
+    skillDrift,
+    blocking: false,
+    issueCodes: packageIssueCodes,
+    warningCodes,
+    recommendedAction: skillDrift
+      ? `Start a new Agent session and load the package-bound Skill at ${packageSkill.skillPath}.`
+      : warningCodes.length > 0
+        ? `Use the package-bound Skill at ${packageSkill?.skillPath ?? "the installed package"}.`
+        : "none",
+  };
+}
+
 async function readResponseJsonBounded(response) {
   if (!response.body) throw new Error("registry response body is missing");
   const reader = response.body.getReader();
@@ -577,7 +662,13 @@ function configCheck(root) {
     );
     if (config === null) return { status: "missing" };
     const gate = validateProjectConfigV2(config);
-    return gate.valid ? { status: "ok" } : { status: "invalid", issues: gate.issues };
+    return gate.valid
+      ? {
+          status: "ok",
+          coreVersion: config.core.coreVersion,
+          coreManifestSha256: config.core.coreManifestSha256,
+        }
+      : { status: "invalid", issues: gate.issues };
   } catch {
     return { status: "invalid" };
   }
@@ -689,11 +780,17 @@ export function readAdoptionReadiness({ workspaceRoot } = {}) {
   return adoptionCheck(root);
 }
 
-export async function runDoctor({
+async function buildDoctorReport({
   workspaceRoot,
+  sharedSkillRoot,
+  discoverSharedSkill = false,
   registryUrl,
   timeoutMs = 1_500,
   registryClient,
+  includeSharedSkill = false,
+  skillRoot = path.join(userInfo().homedir, ".agents", "skills", "owlcoda-runkit"),
+  skillInspector = inspectInstalledSkillCompatibility,
+  skillFleetInspector = inspectFleetForSkillChange,
 } = {}) {
   const root = resolveBoundedWorkspaceRoot(workspaceRoot);
   const core = currentCoreIdentity();
@@ -715,6 +812,72 @@ export async function runDoctor({
   const profiles = await doctorProfilesCheck(root);
   const adoption = adoptionCheck(root, installed);
   const runtimeIsolation = runtimeIsolationCheck(root);
+  const skill = includeSharedSkill && (sharedSkillRoot !== undefined || discoverSharedSkill)
+    ? {
+        ...inspectDoctorSkillStateV1({
+          packageRoot: installed.status === "bound" ? installed.packageRoot : undefined,
+          sharedSkillRoot,
+        }),
+        packageVersion: installed.status === "bound" ? installed.version : null,
+        configCoreVersion: config.status === "ok" ? config.coreVersion : null,
+      }
+    : includeSharedSkill
+      ? {
+        schemaVersion: "OwlCodaRunKitDoctorSkillStateV1",
+        packageVersion: installed.status === "bound" ? installed.version : null,
+        configCoreVersion: core.coreVersion,
+        packageSkillVersion: null,
+        packageSkillPath: null,
+        processSkillVersion: null,
+        processSkillPath: null,
+        loadedSkillVersion: "unknown",
+        skillDrift: false,
+        blocking: false,
+        issueCodes: [],
+        warningCodes: [],
+        recommendedAction: "none",
+      }
+      : null;
+  let sharedSkill = null;
+  if (includeSharedSkill) {
+    let inspectedSkill;
+    try {
+      inspectedSkill = await skillInspector({ targetRoot: skillRoot });
+    } catch (error) {
+      inspectedSkill = {
+        status: "invalid",
+        installedSkillVersion: null,
+        issues: [error instanceof Error ? error.message : String(error)],
+      };
+    }
+    let activationBlockedReason = null;
+    if (inspectedSkill.status !== "valid") {
+      try {
+        await skillFleetInspector();
+      } catch (error) {
+        activationBlockedReason = error instanceof Error ? error.message : String(error);
+      }
+    }
+    const sharedSkillDrift = inspectedSkill.status === "version_mismatch";
+    sharedSkill = {
+      status: inspectedSkill.status === "valid"
+        ? "valid"
+        : sharedSkillDrift
+          ? "expected_nonblocking_drift"
+          : "unavailable_nonblocking",
+      blocking: false,
+      projectCliVersion: installed.version ?? null,
+      projectCoreVersion: core.coreVersion,
+      sharedSkillVersion: inspectedSkill.installedSkillVersion ?? null,
+      issueCodes: [...new Set(inspectedSkill.issues ?? [])].sort(),
+      activationBlockedReason,
+      recommendedAction: inspectedSkill.status === "valid"
+        ? null
+        : activationBlockedReason?.startsWith("skill_update_blocked_active_execution:")
+          ? "wait_for_active_execution_or_lease_then_refresh_shared_skill"
+          : "run_fleet_safe_shared_skill_refresh",
+    };
+  }
   const checks = {
     node: {
       status: nodeOk ? "ok" : "unsupported",
@@ -744,6 +907,8 @@ export async function runDoctor({
       detected: readProjectScripts(root),
     },
     runtimeIsolation,
+    ...(skill === null ? {} : { skill }),
+    ...(sharedSkill === null ? {} : { sharedSkill }),
     lifecycle: {
       status: lifecycle.status,
       activeRunIds: lifecycle.activeRunIds,
@@ -762,6 +927,7 @@ export async function runDoctor({
   if (installed.status !== "bound") {
     issueCodes.push(...(installed.issueCodes ?? ["registry_install_binding_mismatch"]));
   }
+  issueCodes.push(...(skill?.issueCodes ?? []));
   if (
     registry.status === "registry_verified"
     && (
@@ -779,11 +945,14 @@ export async function runDoctor({
     ...runtimeIsolation.affectedScripts
       .map(({ script, tool }) => `runkit_runtime_collection_risk:${tool}:${script}`),
     ...(profileLauncherWarningCount > 0 ? ["profile_launcher_warnings"] : []),
+    ...(skill?.warningCodes ?? []),
   ].sort();
   const lifecycleNextAction = lifecycle.recovery.nextAllowedAction;
-  const maintenanceNextAction = profileLauncherWarningCount > 0
-    ? "review_profile_launchers"
-    : null;
+  const maintenanceNextAction = skill?.skillDrift
+    ? "reload_package_bound_skill"
+    : profileLauncherWarningCount > 0
+      ? "review_profile_launchers"
+      : null;
   const nextAllowedAction = uniqueIssues.length === 0
     ? lifecycleNextAction !== "plan_new_execution"
       ? lifecycleNextAction
@@ -802,7 +971,9 @@ export async function runDoctor({
               ? "repair_execution_artifacts"
             : "repair_registry_binding";
   return {
-    schemaVersion: "OwlCodaRunKitDoctorReportV1",
+    schemaVersion: includeSharedSkill
+      ? "OwlCodaRunKitDoctorReportV2"
+      : "OwlCodaRunKitDoctorReportV1",
     status: uniqueIssues.length === 0 ? "ready" : "issues_found",
     checks,
     issueCodes: uniqueIssues,
@@ -810,7 +981,9 @@ export async function runDoctor({
     profileLauncherWarnings: {
       count: profileLauncherWarningCount,
       blocking: false,
-      recommendedAction: maintenanceNextAction,
+      recommendedAction: profileLauncherWarningCount > 0
+        ? "review_profile_launchers"
+        : null,
     },
     lifecycleNextAction,
     maintenanceNextAction,
@@ -819,6 +992,14 @@ export async function runDoctor({
   };
 }
 
+export async function runDoctor(options = {}) {
+  return buildDoctorReport({ ...options, includeSharedSkill: false });
+}
+
+export async function runDoctorV2(options = {}) {
+  return buildDoctorReport({ ...options, includeSharedSkill: true });
+}
+
 export function formatDoctorHuman(report) {
   const otherWarnings = report.warningCodes.filter(
     (code) => code !== "profile_launcher_warnings",
@@ -828,9 +1009,22 @@ export function formatDoctorHuman(report) {
     `Node: ${report.checks.node.status} (${report.checks.node.version})`,
     `Core: ${report.checks.core.status} (${report.checks.core.version})`,
     `Installed package: ${report.checks.installedPackage.status}`,
+    ...(report.checks.skill
+      ? [
+          `Skill: package ${report.checks.skill.packageSkillVersion ?? "unknown"}; process ${report.checks.skill.processSkillVersion ?? "unknown"}${report.checks.skill.skillDrift ? " (drift, non-blocking)" : ""}; loaded ${report.checks.skill.loadedSkillVersion}.`,
+          `Package-bound Skill: ${report.checks.skill.packageSkillPath ?? "unavailable"}`,
+          `Process-wide Skill: ${report.checks.skill.processSkillPath ?? "unavailable"}`,
+        ]
+      : []),
     `Registry: ${report.checks.registry.status}`,
     `Profiles: ${report.checks.profiles.status}`,
     `Adoption: ${report.checks.adoption.status}`,
+    ...(report.checks.sharedSkill
+      ? [`Shared Skill: ${report.checks.sharedSkill.status} (${report.checks.sharedSkill.sharedSkillVersion ?? "missing"}; project Core ${report.checks.sharedSkill.projectCoreVersion})`]
+      : []),
+    ...(report.checks.sharedSkill?.activationBlockedReason
+      ? [`Shared Skill activation: ${report.checks.sharedSkill.activationBlockedReason}`]
+      : []),
     `Lifecycle: ${report.checks.lifecycle.status}`,
     ...(report.issueCodes.length > 0 ? [`Issues: ${report.issueCodes.join(", ")}`] : []),
     ...(report.profileLauncherWarnings.count > 0

package/scripts/runkit-contract/profile-onboarding.mjs

@@ -1826,6 +1826,12 @@ export function reconcileProfilesV2({
     authorizationGranted: false,
   };
   if (!apply || proposedProfilesSha256 === currentProfilesSha256) return plan;
+  if (normalizationOnly) {
+    return {
+      ...plan,
+      status: "profiles_already_current",
+    };
+  }
 
   let runtimeRoot;
   let receiptRoot;

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

@@ -15,10 +15,18 @@ const MAX_CORE_TOTAL_BYTES = 67_108_864;
 const PACKAGE_NAME = "owlrunkit";
 const OFFICIAL_CLI_ENTRYPOINT =
   "scripts/runkit-contract/runkit-bootstrap.mjs";
-const SELF_NORMALIZED_QUICK_CORE_VERSIONS = new Set(["0.19.2", "0.20.0"]);
+const SELF_NORMALIZED_QUICK_CORE_VERSIONS = new Set([
+  "0.19.2",
+  "0.20.0",
+  "0.20.1",
+  "0.21.0",
+]);
 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.20.0", new Set([
+    "sha256:30098aa9344c17c1ed0b5ed45ef1c590b3214b824402f584029c1ecb38ca7a70",
+  ])],
   ["0.19.2", new Set([
     "sha256:c46ae9d8ed0572e5636ab5725f922f8db3ee5bf0f966b200bce7b2287c9267c8",
   ])],

package/scripts/runkit-contract/quick-metrics.mjs

@@ -22,12 +22,13 @@ const INVALID_ATTESTATION_ISSUES = new Set([
   "attestation_material_missing",
   "receipt_material_hash_mismatch",
 ]);
-const V3_MUTATION_ISSUES = new Set([
+const SUCCESSOR_MUTATION_ISSUES = new Set([
   "source_mutated_during_verification",
   "bound_ignored_path_mutated_during_verification",
   "dependency_environment_mutated_during_verification",
   "consumer_source_mutated_during_verification",
   "quick_isolation_cleanup_failed",
+  "foreign_workspace_mutated_during_verification",
 ]);
 
 function readHistoricalReceipt(receiptPath) {
@@ -38,11 +39,14 @@ function readHistoricalReceipt(receiptPath) {
     && quickSnapshotFingerprintValid(receipt.workspaceAfter);
   const sourceChanged = receipt.workspaceBefore.sourceFingerprint
     !== receipt.workspaceAfter.sourceFingerprint;
-  const receiptV3 = receipt.schemaVersion === "OwlCodaQuickVerificationReceiptV3";
+  const successorReceipt = [
+    "OwlCodaQuickVerificationReceiptV3",
+    "OwlCodaQuickVerificationReceiptV4",
+  ].includes(receipt.schemaVersion);
   const mutationBindingValid = receipt.mutationDecision === "source_unchanged"
-    ? !sourceChanged && !receipt.issueCodes.some(issue => V3_MUTATION_ISSUES.has(issue))
-    : receiptV3
-      ? receipt.issueCodes.some(issue => V3_MUTATION_ISSUES.has(issue))
+    ? !sourceChanged && !receipt.issueCodes.some(issue => SUCCESSOR_MUTATION_ISSUES.has(issue))
+    : successorReceipt
+      ? receipt.issueCodes.some(issue => SUCCESSOR_MUTATION_ISSUES.has(issue))
       : sourceChanged && receipt.issueCodes.includes("source_mutated_during_verification");
   if (!snapshotsValid || !mutationBindingValid) {
     throw new Error("quick_receipt_source_binding_invalid");