create-agdf 0.13.6 → 0.13.8

package/lib/installers/local-marketplace.js

@@ -7,7 +7,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { dirname, isAbsolute, join, posix, relative, resolve, sep, win32 } from "node:path";
 import process from "node:process";
 import { generatedRoot, packageRoot, pluginDefinition } from "../cli/runtime-context.js";
 import { renameSyncWithRetry } from "../fs-swap.js";
@@ -40,6 +40,11 @@ function semverBase(version) {
   return version.split("+")[0];
 }
 
+function isSemanticVersion(version) {
+  return typeof version === "string"
+    && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(version);
+}
+
 export function codexLocalInstallVersion(version, sourceDigest) {
   if (!/^[a-f0-9]{64}$/.test(sourceDigest)) throw new Error("AGDF local source digest must be a deterministic SHA-256 value.");
   return `${semverBase(version)}+codex.local-${sourceDigest.slice(0, 12)}`;
@@ -60,15 +65,20 @@ function readJson(path, label) {
   }
 }
 
+function pathForPlatform(platform = process.platform) {
+  return platform === "win32" ? win32 : posix;
+}
+
 export function defaultAgdfDataRoot({ env = process.env, platform = process.platform, home = homedir() } = {}) {
-  if (env.AGDF_DATA_DIR) return resolve(env.AGDF_DATA_DIR);
-  if (platform === "darwin") return join(home, "Library", "Application Support", "agdf");
-  if (platform === "win32") return join(env.LOCALAPPDATA || env.APPDATA || join(home, "AppData", "Local"), "agdf");
-  return join(env.XDG_DATA_HOME || join(home, ".local", "share"), "agdf");
+  const targetPath = pathForPlatform(platform);
+  if (env.AGDF_DATA_DIR) return targetPath.resolve(env.AGDF_DATA_DIR);
+  if (platform === "darwin") return targetPath.join(home, "Library", "Application Support", "agdf");
+  if (platform === "win32") return targetPath.join(env.LOCALAPPDATA || env.APPDATA || targetPath.join(home, "AppData", "Local"), "agdf");
+  return targetPath.join(env.XDG_DATA_HOME || targetPath.join(home, ".local", "share"), "agdf");
 }
 
 export function localMarketplaceRoot(options = {}) {
-  return join(defaultAgdfDataRoot(options), "marketplaces", MARKETPLACE_ID);
+  return pathForPlatform(options.platform).join(defaultAgdfDataRoot(options), "marketplaces", MARKETPLACE_ID);
 }
 
 function ownership(root, { allowBuilding = false } = {}) {
@@ -134,6 +144,7 @@ function claudeMarketplace(definition = pluginDefinition) {
 function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVersion = expectedVersion, sourceDigest = "", {
   requireInstallationProvenance = false,
   allowLegacyProvenanceForMigration = false,
+  allowPreProvenanceShape = false,
 } = {}) {
   const definition = readJson(join(pluginRoot, "meta", "agdf-plugin.definition.json"), "built plugin definition");
   const runtime = readJson(join(pluginRoot, "runtime", "runtime-manifest.json"), "built runtime manifest");
@@ -150,8 +161,11 @@ function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVe
   if (definition.version !== expectedVersion || runtime.version !== expectedVersion) {
     throw new Error(`Built plugin version mismatch: expected ${expectedVersion}, definition ${definition.version}, runtime ${runtime.version}`);
   }
+  const profile = validateDistributionProfiles(definition);
+  const isPreProvenanceShape = allowPreProvenanceShape
+    && !Object.hasOwn(definition, "distributionProfiles");
   let provenance = null;
-  if (validateDistributionProfiles(definition).status !== "matched"
+  if (profile.status !== "matched"
       && requireInstallationProvenance
       && allowLegacyProvenanceForMigration) {
     provenance = inspectInstallationProvenance(pluginRoot, {
@@ -161,7 +175,7 @@ function validateBuiltPlugin(pluginRoot, expectedVersion, expectedCodexInstallVe
       allowLegacy: true,
     });
   }
-  if (validateDistributionProfiles(definition).status !== "matched" && provenance?.status !== "legacy") {
+  if (profile.status !== "matched" && provenance?.status !== "legacy" && !isPreProvenanceShape) {
     throw new Error("Built plugin distribution profile contract is invalid.");
   }
   if (codex.version !== expectedCodexInstallVersion) {
@@ -212,6 +226,49 @@ function validateMarketplaceRoot(root, definition = pluginDefinition) {
   return Object.freeze({ codexShape });
 }
 
+function classifyExistingMarketplace(stableRoot, marker) {
+  const existingPluginRoot = join(stableRoot, "plugins", MARKETPLACE_ID);
+  const existingCodexInstallVersion = marker.codex_install_version ?? marker.version;
+  if (!isSemanticVersion(marker.version)
+      || !/^[a-f0-9]{64}$/.test(marker.plugin_digest ?? "")) {
+    throw new Error(`Refusing invalid AGDF marketplace ownership evidence: ${stableRoot}`);
+  }
+  const definition = readJson(
+    join(existingPluginRoot, "meta", "agdf-plugin.definition.json"),
+    "built plugin definition",
+  );
+  const hasCurrentProvenance = existsSync(join(existingPluginRoot, INSTALLATION_PROVENANCE_FILE));
+  const hasLegacyProvenance = existsSync(join(existingPluginRoot, LEGACY_LOCAL_INSTALL_FILE));
+  const preProvenanceCandidate = !hasCurrentProvenance
+    && !hasLegacyProvenance
+    && !Object.hasOwn(definition, "distributionProfiles");
+  const existingDefinition = validateBuiltPlugin(
+    existingPluginRoot,
+    marker.version,
+    existingCodexInstallVersion,
+    marker.source_digest ?? "",
+    preProvenanceCandidate
+      ? { allowPreProvenanceShape: true }
+      : { requireInstallationProvenance: true, allowLegacyProvenanceForMigration: true },
+  );
+  const marketplace = validateMarketplaceRoot(stableRoot, existingDefinition);
+  if (digestDirectory(existingPluginRoot) !== marker.plugin_digest) {
+    throw new Error(`Refusing tampered AGDF marketplace root: ${stableRoot}`);
+  }
+  return Object.freeze({
+    classification: preProvenanceCandidate
+      ? "owned_pre_provenance_rebuild"
+      : "current_or_marker_migration",
+    definition: existingDefinition,
+    marketplace,
+  });
+}
+
+function invalidExistingMarketplace(error) {
+  error.existingClassification = "invalid_or_unowned";
+  return error;
+}
+
 function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot) {
   const parent = dirname(stableRoot);
   if (existsSync(backupRoot)) {
@@ -252,25 +309,28 @@ export function prepareLocalMarketplace({
   mkdirSync(parent, { recursive: true });
   recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failedRoot);
 
-  const existing = existsSync(stableRoot) ? ownership(stableRoot) : null;
+  let existing = null;
+  if (existsSync(stableRoot)) {
+    try {
+      existing = ownership(stableRoot);
+    } catch (error) {
+      throw invalidExistingMarketplace(error);
+    }
+  }
   const targetCodexRegistrationRevision = codexRegistrationRevision
     ?? existing?.codex_registration_revision
     ?? 0;
   let existingMarketplace = null;
+  let existingClassification = "none";
   if (existing) {
-    const existingPluginRoot = join(stableRoot, "plugins", MARKETPLACE_ID);
-    const existingCodexInstallVersion = existing.codex_install_version ?? existing.version;
-    const existingDefinition = validateBuiltPlugin(
-      existingPluginRoot,
-      existing.version,
-      existingCodexInstallVersion,
-      existing.source_digest ?? "",
-      { requireInstallationProvenance: true, allowLegacyProvenanceForMigration: true },
-    );
-    existingMarketplace = validateMarketplaceRoot(stableRoot, existingDefinition);
-    if (digestDirectory(existingPluginRoot) !== existing.plugin_digest) {
-      throw new Error(`Refusing tampered AGDF marketplace root: ${stableRoot}`);
+    let classified;
+    try {
+      classified = classifyExistingMarketplace(stableRoot, existing);
+    } catch (error) {
+      throw invalidExistingMarketplace(error);
     }
+    existingClassification = classified.classification;
+    existingMarketplace = classified.marketplace;
   }
   mkdirSync(stageRoot, { recursive: false });
   try {
@@ -338,6 +398,8 @@ export function prepareLocalMarketplace({
         codexInstallVersion,
         sourceDigest,
         digest: pluginDigest,
+        runtimeDigest: runtimeManifest.digest,
+        existingClassification,
         changed: false,
         commit() {},
         rollback() {},
@@ -359,6 +421,8 @@ export function prepareLocalMarketplace({
       codexInstallVersion,
       sourceDigest,
       digest: pluginDigest,
+      runtimeDigest: runtimeManifest.digest,
+      existingClassification,
       changed: true,
       commit() {
         if (closed) return;

package/lib/installers/opencode.js

@@ -6,6 +6,7 @@ import process from "node:process";
 import { generatedRoot, pluginDefinition } from "../cli/runtime-context.js";
 import { evaluateOpenCodeRepositoryActivation } from "./opencode-activation.js";
 import { resolveLocalValidator } from "../runtime/local-validator.js";
+import { digestDirectory } from "../runtime/plugin-provenance.js";
 import { validateLocalOpenCodePackageSource } from "./local-development.js";
 
 const contractModules = ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"];
@@ -17,6 +18,7 @@ const globalOpenCodeRuntimeContractOwnershipMarker = "<!-- AGDF-GLOBAL-RUNTIME-C
 const globalOpenCodeValidatorOwnershipMarker = "// AGDF-GLOBAL-LOCAL-VALIDATOR";
 const globalOpenCodeAgentOwnershipMarker = `<!-- AGDF-GLOBAL-AGENT: ${pluginDefinition.opencode.evaluatorAgentName} -->`;
 const globalOpenCodeValidatorPackageOwner = "create-agdf";
+export const openCodePluginEntrypoint = `./node_modules/${pluginDefinition.opencode.npmPackage}/opencode-plugin.js`;
 const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_NPM_CLI_PATH || "" : "";
 const npmCommand = testNpmCliPath ? process.execPath : process.platform === "win32" ? process.execPath : "npm";
 const npmPrefixArgs = testNpmCliPath ? [testNpmCliPath] : process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
@@ -67,10 +69,14 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     throw openCodeLifecycleError("configuration", `Refusing to update OpenCode config with non-array plugin field: ${configPath}`, { configPath });
   }
 
-  const plugins = [...(config.plugin ?? [])];
-  const alreadyInstalled = plugins.includes(pluginDefinition.opencode.npmPackage);
+  const plugins = (config.plugin ?? []).map((entry) => (
+    entry === pluginDefinition.opencode.npmPackage || entry.startsWith(`${pluginDefinition.opencode.npmPackage}@`)
+      ? openCodePluginEntrypoint
+      : entry
+  ));
+  const alreadyInstalled = plugins.includes(openCodePluginEntrypoint);
   if (!alreadyInstalled) {
-    plugins.push(pluginDefinition.opencode.npmPackage);
+    plugins.push(openCodePluginEntrypoint);
   }
 
   const nextConfig = {
@@ -128,6 +134,10 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     throw openCodeLifecycleError("configuration", `Failed to write OpenCode config ${configPath}: ${error.message}`, { configPath });
   }
   const installedPackage = resolveOpenCodePackage(configDir);
+  if (!installedPackage.loadable || !installedPackage.package_root) {
+    throw openCodeLifecycleError("verification", "Installed OpenCode AGDF package is not loadable after installation.", { configDir });
+  }
+  const installedPackageDigest = digestDirectory(installedPackage.package_root);
   const sdkAlignment = alignOpenCodePluginSdk(configDir);
 
   return {
@@ -135,6 +145,7 @@ export function installOpenCodeGlobalPlugin(configDir, dependencies = {}) {
     added: !alreadyInstalled,
     transition: openCodePackageTransition(previousPackage, installedPackage),
     sdk_alignment: sdkAlignment,
+    installed_package: { root: installedPackage.package_root, digest: installedPackageDigest },
     package_source: localPackageSource
       ? { kind: "local_checkout", path: localPackageSource.tarball, digest: localPackageSource.digest, version: localPackageSource.version }
       : { kind: "registry", path: "", digest: "", version: pluginDefinition.version },
@@ -736,7 +747,8 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
   const configPath = join(configDir, "opencode.json");
   const configState = readOpenCodeConfig(configPath);
   const plugins = Array.isArray(configState.config.plugin) ? configState.config.plugin : [];
-  const globalConfigured = plugins.includes(pluginDefinition.opencode.npmPackage);
+  const globalConfigured = plugins.includes(openCodePluginEntrypoint);
+  const legacyPluginConfigured = plugins.some((entry) => entry === pluginDefinition.opencode.npmPackage || entry.startsWith(`${pluginDefinition.opencode.npmPackage}@`));
   const packageState = resolveOpenCodePackage(configDir);
   const packageVersionStatus = openCodePackageVersionStatus(packageState);
   const globalNativeSurface = evaluateGlobalOpenCodeSurface(configDir);
@@ -754,7 +766,9 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
   const findings = [];
   if (!configState.exists) findings.push("OpenCode global config not found.");
   if (configState.parseError) findings.push(`OpenCode global config is not valid JSON: ${configState.parseError}`);
-  if (!globalConfigured) findings.push(`OpenCode global config does not include ${pluginDefinition.opencode.npmPackage}.`);
+  if (!globalConfigured) findings.push(legacyPluginConfigured
+    ? `OpenCode global config still uses the host-managed npm cache entry for ${pluginDefinition.opencode.npmPackage}; rerun installation to bind the verified local package entrypoint.`
+    : `OpenCode global config does not include ${openCodePluginEntrypoint}.`);
   if (!packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is not loadable from the OpenCode config directory.`);
   if (packageVersionStatus === "outdated") findings.push(`${pluginDefinition.opencode.npmPackage} version ${packageState.installed_version} is outdated; expected ${pluginDefinition.version}.`);
   if (packageVersionStatus === "unknown" && packageState.loadable) findings.push(`${pluginDefinition.opencode.npmPackage} is loadable but its installed version is unknown.`);
@@ -783,6 +797,8 @@ export function evaluateOpenCodeStatus(targetDir, configDir = defaultOpenCodeCon
       exists: configState.exists,
       parse_error: configState.parseError,
       plugin_configured: globalConfigured,
+      plugin_entrypoint: openCodePluginEntrypoint,
+      legacy_plugin_configured: legacyPluginConfigured,
     },
     package: {
       name: pluginDefinition.opencode.npmPackage,

package/lib/installers/plugin-installers.js

@@ -27,8 +27,13 @@ export function installCodexGlobalPlugin({ exec = execFileSync, prepare = prepar
         ...(transaction.pluginRoot ? [`staged_plugin_root:${transaction.pluginRoot}`, "staged_installation_provenance:matched"] : []),
         ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
         ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
+        ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
         ...(expectedInstallVersion === expectedVersion ? [] : [`canonical_version:${expectedVersion}`, `local_install_version:${expectedInstallVersion}`]),
       ],
+      pluginRoot: transaction.pluginRoot ?? null,
+      digest: transaction.digest ?? null,
+      runtimeDigest: transaction.runtimeDigest ?? null,
+      sourceDigest: transaction.sourceDigest ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {
@@ -73,8 +78,13 @@ export function installClaudeGlobalPlugin({ exec = execFileSync, prepare = prepa
         ...(transaction.pluginRoot ? [`staged_plugin_root:${transaction.pluginRoot}`, "staged_installation_provenance:matched"] : []),
         ...(transaction.sourceDigest ? [`source_digest:${transaction.sourceDigest}`] : []),
         ...(transaction.digest ? [`plugin_digest:${transaction.digest}`] : []),
+        ...(transaction.existingClassification === "owned_pre_provenance_rebuild" ? ["marketplace_recovery:owned_pre_provenance_rebuild", "loaded_session:restart_required"] : []),
         ...(installedVersion ? [] : ["host_did_not_expose_version"]),
       ],
+      pluginRoot: transaction.pluginRoot ?? null,
+      digest: transaction.digest ?? null,
+      runtimeDigest: transaction.runtimeDigest ?? null,
+      sourceDigest: transaction.sourceDigest ?? null,
       nativeOutput: nativeOutput.filter(Boolean).map(String),
     };
   } catch (error) {

package/lib/lifecycle/presentation.js

@@ -9,6 +9,9 @@ const surfaceLabels = Object.freeze({
 function titleFor(report) {
   if (report.result === "failed") return "AGDF installation failed";
   if (report.result === "partial") return "AGDF installation partially completed";
+  if (report.result === "preview") return report.operation === "uninstall"
+    ? "AGDF uninstall preview"
+    : "AGDF installation cancelled";
   if (report.operation === "repository_setup") return "AGDF repository setup complete";
   return "AGDF installation complete";
 }
@@ -28,18 +31,55 @@ export function lifecycleCardLines(report) {
     `Installation: ${report.installation.status}`,
     `Activation: ${report.activation.status}`,
     `Repository delivery: ${report.delivery.status}`,
+    `Automatic runtime checks: requested=${report.runtime_checks.requested}; effective=${report.runtime_checks.effective}; reason=${report.runtime_checks.reason}`,
     `Verification: ${report.verification.status}`,
     `Restart required: ${report.restart.required ? "yes" : "no"}${report.restart.reason !== "none" ? ` (${report.restart.reason})` : ""}`,
     `Next action: ${report.next_action.text}`,
   ];
 }
 
-export function printLifecycleResult(report, { json = false, io = console } = {}) {
+function friendlyRuntimeCheckState(report) {
+  if (report.runtime_checks.requested === "cancelled") return "Cancelled";
+  if (report.runtime_checks.effective === "enabled") return "On";
+  if (report.runtime_checks.effective === "manual") return "Manual";
+  if (report.runtime_checks.effective === "decision_required") return `Waiting for ${surfaceLabels[report.surface]} permission`;
+  if (report.runtime_checks.effective === "renewal_required") return "Needs your review";
+  if (["degraded", "failed", "unavailable"].includes(report.runtime_checks.effective)) return "Not available; use manual checks";
+  return report.runtime_checks.requested === "enabled" ? "Requested; verification pending" : "Not configured";
+}
+
+function compactVersionLine(report) {
+  if (report.version.transition === "updated" && report.version.previous && report.version.installed) {
+    return `Updated: ${report.version.previous} -> ${report.version.installed} (${report.version.status})`;
+  }
+  if (report.version.installed) return `Version: ${report.version.installed} (${report.version.status})`;
+  if (report.version.expected) return `Version: not verified (expected ${report.version.expected})`;
+  return "Version: not verified";
+}
+
+export function compactLifecycleCardLines(report) {
+  if (report.result === "preview") return [
+    titleFor(report),
+    "No changes were made.",
+    `Next: ${report.next_action.text}`,
+  ];
+  return [
+    report.result === "success"
+      ? `AGDF ${report.operation === "update" ? "updated" : "installed"} for ${surfaceLabels[report.surface]}`
+      : titleFor(report),
+    compactVersionLine(report),
+    `Installation: ${report.installation.status === "healthy" ? "Ready" : report.installation.status}`,
+    `Automatic checks: ${friendlyRuntimeCheckState(report)}`,
+    `Next: ${report.next_action.text}`,
+  ];
+}
+
+export function printLifecycleResult(report, { json = false, compact = false, io = console } = {}) {
   if (json) {
     io.log(JSON.stringify(report, null, 2));
     return;
   }
-  for (const line of lifecycleCardLines(report)) io.log(line);
+  for (const line of compact ? compactLifecycleCardLines(report) : lifecycleCardLines(report)) io.log(line);
   if (report.failure) io.log(`Failure phase: ${report.failure.phase}: ${report.failure.message}`);
   if (report.retained.length) {
     io.log("Retained:");
@@ -56,5 +96,6 @@ export function printGeneralStatus(report, { json = false, io = console } = {})
   io.log(`Installation: ${report.installation.status}${report.installation.version ? ` (${report.installation.version})` : ""}`);
   io.log(`Repository: ${report.repository.status}`);
   io.log(`Delivery: ${report.delivery.status}${report.delivery.current_gate ? ` (${report.delivery.current_gate})` : ""}`);
+  io.log(`Automatic runtime checks: requested=${report.runtime_checks.requested}; effective=${report.runtime_checks.effective}; reason=${report.runtime_checks.reason}`);
   io.log(`Next action: ${report.next_action.text}`);
 }

package/lib/lifecycle/result.js

@@ -39,6 +39,15 @@ export function createLifecycleResult(input = {}) {
     delivery: {
       status: text(input.delivery?.status) || "not_evaluated",
     },
+    runtime_checks: {
+      requested: text(input.runtime_checks?.requested) || "unknown",
+      effective: text(input.runtime_checks?.effective) || "unknown",
+      reason: text(input.runtime_checks?.reason) || "not_evaluated",
+      capability_identity: text(input.runtime_checks?.capability_identity) || null,
+      verification: text(input.runtime_checks?.verification) || "not_evaluated",
+      mutation: text(input.runtime_checks?.mutation) || "none",
+      rollback: text(input.runtime_checks?.rollback) || "none",
+    },
     restart: {
       required: Boolean(input.restart?.required),
       reason: text(input.restart?.reason) || "none",

package/lib/lifecycle/status.js

@@ -6,6 +6,7 @@ import { evaluateGateCheck } from "../control-evaluation/gate-check.js";
 import { evaluateOpenCodeStatus } from "../installers/opencode.js";
 import { inspectPluginSurface } from "../installers/plugin-installers.js";
 import { inspectGeneratedRepositoryMarketplace } from "../runtime/plugin-provenance.js";
+import { runtimeCheckStatus } from "../runtime-check-consent/service.js";
 
 function deliveryStatus(targetDir, selection, dependencies) {
   const controlDir = join(targetDir, ".agdf", "control");
@@ -95,6 +96,9 @@ export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}
   }
   const repository = repositoryStatus(targetDir, surface);
   const delivery = deliveryStatus(targetDir, { runId: options.runId }, deps);
+  const runtimeChecks = ["codex", "claude", "opencode"].includes(surface)
+    ? runtimeCheckStatus(options.dataRoot, surface)
+    : { requested: "unknown", effective: "unavailable", reason: "unsupported_host_capability" };
   const nextText = surface === "multiple"
     ? "Multiple AGDF host surfaces were detected; rerun status with an explicit --surface."
     : surface === "generic"
@@ -112,5 +116,5 @@ export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}
     : delivery.status === "not_configured"
     ? "Start a new task; status created no run and requires no approval. Initialize durable control only when the repository needs it."
     : "Continue with the reported delivery next step.";
-  return { schema_version: 1, installation, repository, delivery, next_action: { kind: "action", text: nextText } };
+  return { schema_version: 1, installation, repository, delivery, runtime_checks: runtimeChecks, next_action: { kind: "action", text: nextText } };
 }

package/lib/runtime-check-consent/adapters.js

@@ -0,0 +1,42 @@
+function fixedCommand(command) {
+  if (typeof command !== "string" || !command.trim() || /[\n\r;&|*?]/.test(command)) {
+    throw new Error("AGDF_RUNTIME_CHECK_COMMAND_NOT_EXACT");
+  }
+  return command.trim();
+}
+
+export function codexRuntimeCheckEvidence({ capabilityIdentity, observedIdentity, hookEnabled, reviewRequired = false }) {
+  if (hookEnabled && observedIdentity === capabilityIdentity) return { status: "enabled", capability_identity: capabilityIdentity, reason: "none" };
+  if (observedIdentity && observedIdentity !== capabilityIdentity) return { status: "renewal_required", reason: "capability_identity_changed" };
+  return { status: "decision_required", reason: reviewRequired ? "host_review_required" : "host_permission_unverified" };
+}
+
+export function claudePermissionRule({ platform, command }) {
+  const exact = fixedCommand(command);
+  return platform === "win32" ? `PowerShell(${exact})` : `Bash(${exact})`;
+}
+
+export function applyClaudeExactRule(settings, { rule, deny = [], ask = [] }) {
+  if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("AGDF_CLAUDE_SETTINGS_INVALID");
+  if ([...deny, ...ask].includes(rule)) return { status: "degraded", reason: "host_permission_conflict", settings };
+  const next = structuredClone(settings);
+  next.permissions ??= {};
+  if (Array.isArray(next.permissions.allow) && next.permissions.allow.some((entry) => entry.includes("*") || entry !== entry.trim())) {
+    throw new Error("AGDF_CLAUDE_BROAD_OR_MALFORMED_RULE");
+  }
+  next.permissions.allow = [...new Set([...(next.permissions.allow ?? []), rule])];
+  return { status: "configured", reason: "none", settings: next };
+}
+
+export function revokeClaudeExactRule(settings, rule) {
+  const next = structuredClone(settings);
+  if (Array.isArray(next.permissions?.allow)) next.permissions.allow = next.permissions.allow.filter((entry) => entry !== rule);
+  return next;
+}
+
+export function openCodeRuntimeCheckEvidence({ capabilityIdentity, observedIdentity, packageLoadable, hookObserved }) {
+  if (!packageLoadable) return { status: "unavailable", reason: "unsupported_host_capability" };
+  if (observedIdentity !== capabilityIdentity) return { status: "renewal_required", reason: "installed_identity_mismatch" };
+  if (!hookObserved) return { status: "degraded", reason: "host_permission_unverified" };
+  return { status: "enabled", capability_identity: capabilityIdentity, reason: "none" };
+}

package/lib/runtime-check-consent/claude-settings.js

@@ -0,0 +1,71 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { renameSyncWithRetry } from "../fs-swap.js";
+import { applyClaudeExactRule, revokeClaudeExactRule } from "./adapters.js";
+
+export function defaultClaudeSettingsPath({ env = process.env, home = homedir() } = {}) {
+  return join(resolve(env.CLAUDE_CONFIG_DIR || join(home, ".claude")), "settings.json");
+}
+
+export function readClaudeSettings(path = defaultClaudeSettingsPath()) {
+  if (!existsSync(path)) return { exists: false, settings: {} };
+  const stats = lstatSync(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("AGDF_CLAUDE_SETTINGS_UNOWNED_PATH");
+  try {
+    const settings = JSON.parse(readFileSync(path, "utf8"));
+    if (!settings || typeof settings !== "object" || Array.isArray(settings)) throw new Error("not an object");
+    return { exists: true, settings };
+  } catch (error) {
+    throw new Error(`AGDF_CLAUDE_SETTINGS_INVALID: ${error.message}`);
+  }
+}
+
+function atomicSettingsWrite(path, settings) {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.agdf-tmp-${process.pid}`;
+  const backup = `${path}.agdf-backup-${process.pid}`;
+  const hadPrevious = existsSync(path);
+  const mode = hadPrevious ? lstatSync(path).mode & 0o777 : 0o600;
+  writeFileSync(temp, `${JSON.stringify(settings, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode });
+  if (process.platform !== "win32") chmodSync(temp, mode);
+  try {
+    if (hadPrevious && process.platform === "win32") renameSyncWithRetry(path, backup);
+    renameSyncWithRetry(temp, path);
+    if (hadPrevious && process.platform === "win32") rmSync(backup, { force: true });
+  } catch (error) {
+    try { rmSync(temp, { force: true }); } catch {}
+    if (hadPrevious && process.platform === "win32" && existsSync(backup) && !existsSync(path)) renameSyncWithRetry(backup, path);
+    throw error;
+  }
+}
+
+export function configureClaudeExactRuntimeRule({ path = defaultClaudeSettingsPath(), rule }) {
+  const before = readClaudeSettings(path);
+  const permissions = before.settings.permissions ?? {};
+  const applied = applyClaudeExactRule(before.settings, {
+    rule,
+    deny: Array.isArray(permissions.deny) ? permissions.deny : [],
+    ask: Array.isArray(permissions.ask) ? permissions.ask : [],
+  });
+  if (applied.status !== "configured") return { ...applied, path, rollback() {} };
+  atomicSettingsWrite(path, applied.settings);
+  return {
+    status: "configured",
+    reason: "host_permission_unverified",
+    path,
+    rollback() {
+      if (before.exists) atomicSettingsWrite(path, before.settings);
+      else rmSync(path, { force: true });
+    },
+  };
+}
+
+export function revokeClaudeRuntimeRule({ path = defaultClaudeSettingsPath(), rule }) {
+  const before = readClaudeSettings(path);
+  if (!before.exists) return { status: "manual", reason: "configuration_missing", path };
+  const next = revokeClaudeExactRule(before.settings, rule);
+  atomicSettingsWrite(path, next);
+  return { status: "manual", reason: "consent_not_provided", path };
+}

package/lib/runtime-check-consent/contract.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+
+const OPERATIONS = Object.freeze([
+  "resolve-local-runtime",
+  "inspect-control-state",
+  "render-bounded-orientation",
+]);
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+
+export function validateRuntimeCheckCapability(capability) {
+  if (capability?.schemaVersion !== 1 || capability.capabilityId !== "automatic-runtime-checks") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: schema or capability id");
+  }
+  if (!Number.isInteger(capability.adapterContractVersion) || capability.adapterContractVersion < 1) {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: adapter contract version");
+  }
+  if (capability.entrypoint !== "runtime/agdf-session-check.js") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: fixed entrypoint required");
+  }
+  if (JSON.stringify(capability.operations) !== JSON.stringify(OPERATIONS)) {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: closed operation vocabulary required");
+  }
+  const constraints = capability.constraints ?? {};
+  if (constraints.arguments !== "forbidden" || constraints.filesystemWrites !== "forbidden"
+      || constraints.network !== "forbidden" || constraints.gateAuthority !== "none") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: read-only constraints required");
+  }
+  const surfaces = capability.surfaces ?? {};
+  if (surfaces.codex !== "native-hook-review" || surfaces.claude !== "exact-command-rule"
+      || surfaces.opencode !== "plugin-internal"
+      || surfaces["portable-skills"] !== "manual-external-required") {
+    throw new Error("AGDF_RUNTIME_CHECK_CAPABILITY_INVALID: surface contract");
+  }
+  return capability;
+}
+
+export function runtimeCheckCapabilityIdentity({ capability, surface, runtimeDigest, sourceDigest, command }) {
+  validateRuntimeCheckCapability(capability);
+  if (!["codex", "claude", "opencode"].includes(surface)) throw new Error("AGDF_RUNTIME_CHECK_SURFACE_INVALID");
+  for (const [name, value] of Object.entries({ runtimeDigest, sourceDigest })) {
+    if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) throw new Error(`AGDF_RUNTIME_CHECK_IDENTITY_INVALID: ${name}`);
+  }
+  if (typeof command !== "string" || !command.trim()) throw new Error("AGDF_RUNTIME_CHECK_IDENTITY_INVALID: command");
+  const payload = stable({
+    schema_version: 1,
+    surface,
+    capability,
+    runtime_digest: runtimeDigest,
+    source_digest: sourceDigest,
+    command: command.trim(),
+  });
+  return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+
+export function fixedRuntimeCheckCommand(surface, pluginRoot, platform = process.platform) {
+  if (surface === "opencode") return "plugin:agdf:automatic-runtime-checks";
+  if (surface === "codex" || surface === "claude") {
+    return platform === "win32"
+      ? "node \"$([Environment]::GetEnvironmentVariable('PLUGIN_ROOT') + [Environment]::GetEnvironmentVariable('CLAUDE_PLUGIN_ROOT'))\\runtime\\agdf-session-check.js\""
+      : "node \"${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/runtime/agdf-session-check.js\"";
+  }
+  const normalizedRoot = platform === "win32" ? pluginRoot.replaceAll("/", "\\") : pluginRoot;
+  return `node \"${normalizedRoot}${platform === "win32" ? "\\" : "/"}runtime${platform === "win32" ? "\\" : "/"}agdf-session-check.js\"`;
+}
+
+export const runtimeCheckOperations = OPERATIONS;

package/lib/runtime-check-consent/coordinator.js

@@ -0,0 +1,37 @@
+export const RUNTIME_CHECK_DECISIONS = Object.freeze(["enable", "manual", "cancel"]);
+
+export function resolveRuntimeCheckDecision({ explicitValue, interactive = false, ask }) {
+  if (explicitValue !== undefined) {
+    if (!RUNTIME_CHECK_DECISIONS.includes(explicitValue)) throw new Error("AGDF_RUNTIME_CHECK_DECISION_INVALID");
+    return explicitValue;
+  }
+  if (!interactive || typeof ask !== "function") return "manual";
+  const answer = ask({
+    question: "Allow this AGDF installation to run narrow local read-only checks automatically?",
+    options: [...RUNTIME_CHECK_DECISIONS],
+    default: null,
+  });
+  if (!RUNTIME_CHECK_DECISIONS.includes(answer)) return "cancel";
+  return answer;
+}
+
+export function consentDisclosure(surface) {
+  const permissionOwner = surface === "codex" ? "Codex native hook trust"
+    : surface === "claude" ? "Claude Code user permission settings"
+    : "OpenCode plugin and explicit permission configuration";
+  return Object.freeze({
+    surface,
+    installation_scope: "global user installation",
+    runs: "one argument-free local session check",
+    when: "at session start",
+    executable: "runtime/agdf-session-check.js inside the installed AGDF runtime",
+    reads: "AGDF runtime identity and .agdf/control state in the current repository",
+    writes: "one AGDF-owned intent receipt and, only where supported, one exact host permission rule",
+    network: "none",
+    permission_owner: permissionOwner,
+    renewal: "material command, runtime, source, scope or adapter identity change requires renewed consent",
+    revocation: `npx --yes @agdf/cli@latest runtime-checks manual --surface ${surface}`,
+    gate_authority: "none",
+    choices: [...RUNTIME_CHECK_DECISIONS],
+  });
+}