create-agdf 0.14.5 → 0.20.1

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/cli/validation-handlers.js

@@ -1,27 +1,153 @@
+import { recordGateApprovalCommand, resolveControlCommandTarget } from "../control-command.js";
+import { COOPERATIVE_ASSURANCE } from "#agdf-core/control-state/approval-command-contract.js";
+import { readFileSync, lstatSync, openSync, fstatSync, closeSync, constants } from "node:fs";
+import { commandGroupRoutes } from './command-registry.js';
+import { RUN_COMMAND_LIMITS } from '#agdf-core/control-state/run-command-contract.js';
+import { executeControlMaintenance } from "./control-maintenance-command.js";
+import { createRun } from "#agdf-core/control-state/run-state-repository.js";
+import { extractField } from "#agdf-core/control-evaluation/verified-change.js";
+import { ARTEFACT_TEMPLATE_IDS, resolveArtefactTemplatePath } from "#agdf-core/resources/artefact-templates.js";
+import { prepareRunPresentation } from "#agdf-core/control-state/run-presentation.js";
 import {
   buildStatusCard,
   evaluateGateCheck,
   printApprovalEnvelope,
   postApprovalTransition,
   printGateCheckReport,
-} from "../control-evaluation/gate-check.js";
-import { evaluateDeliveryMap, printDeliveryMapReport } from "../control-evaluation/delivery-map.js";
-import { evaluateDoctor, printDoctorReport } from "../control-evaluation/doctor.js";
+} from "#agdf-core/control-evaluation/gate-check.js";
+import { evaluateDeliveryMap, printDeliveryMapReport } from "#agdf-core/control-evaluation/delivery-map.js";
+import { evaluateDoctor, printDoctorReport } from "#agdf-core/control-evaluation/doctor.js";
 import { executeDeliveryPathSearch } from "./delivery-path-search-command.js";
+import { resolveTaskTarget } from "#agdf-core/task-target-resolution.js";
+import { renderSkillDispatchRecovery, renderTaskTargetOrientation, renderSourceRevision } from "#agdf-core/interaction-presentation.js";
+import { interactionLocales, pluginDefinition } from "./runtime-context.js";
+import { serializeSkillDispatchResult } from "#agdf-core/skill-dispatch/contract.js";
+import { createCoreServices } from "#agdf-core";
+import { resources } from "../runtime/control-context.js";
+import { approveRunGate, recordRunRevision } from "#agdf-core/control-state/run-recording.js";
+import { reopenPrdRevision, previewSourceRevision, applySourceRevision, inspectSourceRevision, recoverSourceRevision } from "#agdf-core/control-state/run-revision.js";
+import { readRuntimeContract, readSkillRuntimeContracts } from "./contract-command.js";
+import { recordRunStep } from "#agdf-core/control-state/run-steps.js";
+import { policyForRunContent } from "#agdf-core/control-evaluation/run-step-policy.js";
+import { cliGitObservation } from "../control-evaluation/git-observation.js";
+import { resolveRepositoryContext } from "../repository-context.js";
+import { applyRunRecovery, inspectRunRecovery, previewRunRecovery } from "../control-state/run-recovery.js";
 
-const deliveryMapDependencies = Object.freeze({ evaluateDoctor, buildStatusCard, postApprovalTransition });
+const evaluateDoctorWithCliGit = (target, selection) => evaluateDoctor(target, selection, cliGitObservation);
+const evaluateGateWithCliGit = (target, selection) => evaluateGateCheck(target, selection, cliGitObservation);
+const resolveTaskTargetWithCliGit = (input) => resolveTaskTarget(input, {
+  resolveRepositoryContext: (directory) => resolveRepositoryContext(directory),
+});
+const deliveryMapDependencies = Object.freeze({ evaluateDoctor: evaluateDoctorWithCliGit, buildStatusCard, postApprovalTransition });
 
 export function createValidationHandlers(io = console) {
+  const executeSkillDispatch = createCoreServices({ resources, observers: {
+    evaluateGateCheck: evaluateGateWithCliGit,
+    resolveTaskTarget: resolveTaskTargetWithCliGit,
+    readSkillRuntimeContracts,
+  } }).dispatch;
   return new Map([
+    ...Object.entries(commandGroupRoutes).map(([route, group]) => [route, options => {
+      let fd;
+      try {
+        const stat = lstatSync(options.commandFile);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > RUN_COMMAND_LIMITS.input_bytes) throw Error('command_file_invalid');
+        fd = openSync(options.commandFile, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const actual = fstatSync(fd);
+        if (!actual.isFile() || actual.dev !== stat.dev || actual.ino !== stat.ino || actual.size > RUN_COMMAND_LIMITS.input_bytes) throw Error('command_file_invalid');
+        const bytes = readFileSync(fd);
+        if (bytes.length > RUN_COMMAND_LIMITS.input_bytes) throw Error('command_file_invalid');
+        const input = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        const result = createCoreServices({ resources }).command(group, input);
+        io.log(JSON.stringify(result));
+        return ['accepted', 'already_applied'].includes(result.outcome) ? 0 : 2;
+      } catch (error) { io.error(error.message); return 1; }
+      finally { if (fd !== undefined) closeSync(fd); }
+    }]),
+    ["control-maintenance", (options) => executeControlMaintenance(options, io)],
+    ["run-create", (options) => {
+      try {
+        const path = createRun(options.dir, options.runId);
+        const revisionId = extractField(readFileSync(path, "utf8"), "revision_id");
+        io.log(path);
+        io.log(`revision_id: ${revisionId}`);
+        // The plugin-owned template is the only authoring source; repository scaffold copies are
+        // derived references. Run creation itself never fails on template availability.
+        let urTemplate = null;
+        try { urTemplate = resolveArtefactTemplatePath(ARTEFACT_TEMPLATE_IDS.UR); } catch {}
+        const templateSource = urTemplate
+          ? `the plugin-owned UR template at ${urTemplate}`
+          : "the plugin-owned UR template supplied as template_path by the bound ur-definition dispatch";
+        io.log(`Next: write .agdf/control/artefacts/${options.runId}/UR.md from ${templateSource}, then record it with run-step --run ${options.runId} --revision ${revisionId} --step ur --title "<short requirement title>".`);
+        return 0;
+      } catch (error) {
+        io.error(error instanceof Error ? error.message : String(error));
+        return 1;
+      }
+    }],
+    ["run-present", (options) => {
+      const result = prepareRunPresentation(options.dir, { runId: options.runId, gate: options.gate,
+        revisionId: options.revisionId, language: options.language?.chat_language }, { evaluateGateCheck: evaluateGateWithCliGit });
+      io.log(JSON.stringify(result, null, 2));
+      return result.outcome === "prepared" ? 0 : 2;
+    }],
+    ["target-check", (options) => {
+      const report = resolveTaskTargetWithCliGit({
+        targetSource: options.targetSource,
+        primaryTarget: options.primaryTarget,
+        workingDirectory: options.workingDirectory,
+        targetChanged: options.targetChanged,
+        candidates: options.targetCandidates,
+        evidenceSources: options.evidenceSources,
+      });
+      const taskTargetOrientation = renderTaskTargetOrientation(report, {
+        registry: interactionLocales,
+        requestedLocale: options.language?.chat_language,
+      });
+      io.log(JSON.stringify({ ...report, task_target_orientation: taskTargetOrientation }, null, 2));
+      return report.resolution_state === "resolved" ? 0 : 2;
+    }],
+    ["skill-dispatch", (options) => {
+      const result = executeSkillDispatch({
+        skillSet: pluginDefinition.skillSet,
+        interactionLocales,
+        skillId: options.skillId,
+        surface: options.surface,
+        presentationLanguage: options.language?.chat_language,
+        workingDirectory: options.workingDirectory,
+        targetSource: options.targetSource,
+        primaryTarget: options.primaryTarget,
+        runId: options.runId,
+        intake: options.intake,
+        intakeMode: options.intakeMode,
+        ...(options.urAction !== undefined ? { urAction: options.urAction } : {}),
+        ...(options.prdAction !== undefined ? { prdAction: options.prdAction } : {}),
+        ...(options.sdAction !== undefined ? { sdAction: options.sdAction } : {}),
+        ...(options.tpAction !== undefined ? { tpAction: options.tpAction } : {}),
+        ...(options.revisionId ? { expectedRevisionId: options.revisionId } : {}),
+        continueDelivery: options.continueDelivery,
+        expectedVersion: pluginDefinition.version,
+      });
+      io.log(serializeSkillDispatchResult(result, {
+        outputTooLargeRecovery: renderSkillDispatchRecovery(
+          { code: "output_too_large" },
+          { registry: interactionLocales, requestedLocale: options.language?.chat_language },
+        ),
+      }));
+      return ["control_result", "skill_continuation", "intake_continuation"].includes(result.outcome) ? 0 : 2;
+    }],
     ["doctor", (options) => {
-      const report = evaluateDoctor(options.dir, options);
+      const report = evaluateDoctorWithCliGit(options.dir, options);
       printDoctorReport(report, options.json, io);
       return report.status === "block" ? 2 : 0;
     }],
     ["gate-check", (options) => {
-      const report = evaluateGateCheck(options.dir, options);
+      const selection = options.languageExplicit
+        ? { ...options, presentationLanguage: options.language?.chat_language }
+        : options;
+      const report = evaluateGateWithCliGit(options.dir, selection);
       if (options.approvalEnvelope) {
-        const output = printApprovalEnvelope(report, { io, reEvaluate: () => evaluateGateCheck(options.dir, options) });
+        const output = printApprovalEnvelope(report, { io, reEvaluate: () => evaluateGateWithCliGit(options.dir, selection) });
         return output.status === "blocked" ? 2 : 0;
       }
       const presentationRendered = printGateCheckReport(report, options.json, options.statusCard, io);
@@ -33,6 +159,78 @@ export function createValidationHandlers(io = console) {
       printDeliveryMapReport(report, options.json, io);
       return report.status === "block" ? 2 : 0;
     }],
+    ["contract", (options) => {
+      const result = readRuntimeContract(options.contractModule);
+      if (!result.ok) {
+        io.error(`${result.reason}: ${options.contractModule}. Available modules: ${result.modules.join(", ")}`);
+        return 1;
+      }
+      io.log(options.json ? JSON.stringify({ module: result.module, content: result.content }) : result.content.replace(/\n$/u, ""));
+      return 0;
+    }],
+    ["run-update", (options) => {
+      const result = recordRunRevision(options.dir, { runId: options.runId, revisionId: options.revisionId });
+      io.log(JSON.stringify(result, null, 2));
+      return result.outcome === "rejected" ? 2 : 0;
+    }],
+    ["run-revise", (options) => {
+      const operation = { preview: previewSourceRevision, apply: applySourceRevision, inspect: inspectSourceRevision, recover: recoverSourceRevision }[options.revisionMode] ?? reopenPrdRevision;
+      const result = operation(options.dir, { runId: options.runId, revisionId: options.revisionId,
+        operationId: options.operationId, sourceGate: options.sourceGate, evidence: options.stepFields?.evidence, previewDigest: options.previewDigest });
+      io.log(options.revisionMode && !options.json ? renderSourceRevision(result, interactionLocales, options.language.chat_language,
+        { ...options, target: options.dir }).markdown : JSON.stringify(result, null, 2));
+      return ["rejected", "recovery_required"].includes(result.outcome) ? 2 : 0;
+    }],
+    ["run-step", (options) => {
+      const result = recordRunStep(options.dir, {
+        runId: options.runId,
+        revisionId: options.revisionId,
+        step: options.runStep,
+        ...(options.gate ? { gate: options.gate } : {}),
+        ...options.stepFields,
+      }, { policy: policyForRunContent });
+      io.log(JSON.stringify(result, null, 2));
+      return result.outcome === "rejected" ? 2 : 0;
+    }],
+    ["run-approve", (options) => {
+      let result;
+      if (options.assurance !== undefined && options.assurance !== "cooperative_local") {
+        result = { schema_version: "1", outcome: "rejected", run_id: options.runId,
+          reason: "unsupported_authority", assurance: COOPERATIVE_ASSURANCE };
+      } else if (options.operationId !== undefined) {
+        result = recordGateApprovalCommand(options.dir, {
+          schema_version: "1", action: "record_gate_approval",
+          target_id: resolveControlCommandTarget(options.dir).target_id, run_id: options.runId,
+          gate: options.gate, expected_revision_id: options.revisionId,
+          presentation_id: options.presentationId, response: options.response,
+          operation_id: options.operationId, assurance: options.assurance ?? "cooperative_local",
+        });
+      } else result = { ...approveRunGate(options.dir, {
+        runId: options.runId,
+        gate: options.gate,
+        revisionId: options.revisionId,
+        response: options.response,
+        presentationId: options.presentationId,
+      }, { evaluateGateCheck: evaluateGateWithCliGit }), assurance: COOPERATIVE_ASSURANCE };
+      io.log(JSON.stringify(result, null, 2));
+      return ["approved", "accepted", "already_applied"].includes(result.outcome) ? 0 : 2;
+    }],
+    ["run-recovery", (options) => {
+      try {
+        const result = options.recoveryAction === "inspect"
+          ? inspectRunRecovery(options.dir, options.runId)
+          : options.recoveryAction === "preview"
+            ? previewRunRecovery(options.dir, options.runId)
+            : applyRunRecovery(options.dir, { runId: options.runId,
+              previewId: options.recoveryPreviewId, confirmation: options.recoveryConfirmation });
+        io.log(JSON.stringify(result, null, 2));
+        return 0;
+      } catch (error) {
+        io.log(JSON.stringify({ schema_version: "1", outcome: "blocked", run_id: options.runId,
+          action: options.recoveryAction, reason: error instanceof Error ? error.message : String(error) }, null, 2));
+        return 2;
+      }
+    }],
     ["delivery-path-search", async (options) => {
       try {
         const result = await executeDeliveryPathSearch(options, io);

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-command.js

@@ -0,0 +1,4 @@
+// Public synchronous ESM surface. Import reads package-owned metadata only; all target access and
+// Git observations begin with an explicit invocation. Cooperative replies are not identity proof.
+export { CONTROL_COMMAND_SCHEMA_VERSION, resolveControlCommandTarget } from "#agdf-core/control-state/approval-command-contract.js";
+export { recordGateApprovalCommand } from "./runtime/control-command-service.js";

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-evaluation/git-observation.js

@@ -0,0 +1,22 @@
+import { execFileSync } from "node:child_process";
+
+export function gitPathList(targetDir, args, exec = execFileSync) {
+  try {
+    return exec("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+      .split("\n")
+      .map((item) => item.trim())
+      .filter(Boolean);
+  } catch {
+    return null;
+  }
+}
+
+export function gitValue(targetDir, args, exec = execFileSync) {
+  try {
+    return exec("git", args, { cwd: targetDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export const cliGitObservation = Object.freeze({ gitPathList, gitValue });

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-maintenance/interaction.js

@@ -0,0 +1,28 @@
+import { createInterface } from "node:readline/promises";
+import process from "node:process";
+import { interactionLocales } from "#agdf-core/resources/context.js";
+import { selectControlMigration, selectControlRepair } from "#agdf-core/control-maintenance/interaction.js";
+export * from "#agdf-core/control-maintenance/interaction.js";
+export async function promptControlMigration(plan, {
+  input = process.stdin, output = process.stdout, registry = interactionLocales, language = "en",
+} = {}) {
+  const prompt = createInterface({ input, output });
+  try {
+    return await selectControlMigration(plan, { registry, language,
+      write(value) { output.write(`${value}\n`); },
+      readChoice({ prompt: question }) { return prompt.question(question); },
+    });
+  } finally { prompt.close(); }
+}
+
+export async function promptControlRepair(value, {
+  input = process.stdin, output = process.stdout, registry = interactionLocales, language = "en", phase = "offer",
+} = {}) {
+  const prompt = createInterface({ input, output });
+  try {
+    return await selectControlRepair(value, { registry, language, phase,
+      write(text) { output.write(`${text}\n`); },
+      readChoice({ prompt: question }) { return prompt.question(question); },
+    });
+  } finally { prompt.close(); }
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-maintenance/repair.js

@@ -0,0 +1,4 @@
+import { inspectControlRepair as inspect, repairInstallationControl as repair } from "#agdf-core/control-maintenance/repair.js";
+import { readGitOriginals } from "../runtime/git-originals.js";
+export const inspectControlRepair = (root, options = {}) => inspect(root, { readGitOriginals, ...options });
+export const repairInstallationControl = (control, options = {}) => repair(control, { readGitOriginals, ...options });

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-maintenance/service.js

@@ -0,0 +1,3 @@
+import { runControlMaintenance as run } from "#agdf-core/control-maintenance/service.js";
+import { readGitOriginals } from "../runtime/git-originals.js";
+export const runControlMaintenance = (target, options = {}) => run(target, { readGitOriginals, ...options });

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-maintenance/startup.js

@@ -0,0 +1,25 @@
+import { spawnSync } from "node:child_process";
+import { assertMaintenanceResult } from "#agdf-core/control-maintenance/contract.js";
+
+// Read through the fixed, identity-checked validator. Never execute report/diagnostic text.
+export function inspectStartupCompatibility({ target, executable, validator, env, deadline, run = spawnSync, now = Date.now }) {
+  const unavailable = { target, inspection_state: "unavailable", status: "unavailable", counts: null, authorizes: false };
+  const timeout = deadline - now();
+  if (timeout <= 0) return unavailable;
+  try {
+    const child = run(executable, [validator, "control-maintenance", "--dir", target, "--json"], {
+      cwd: target, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
+      timeout, maxBuffer: 1024 * 1024,
+    });
+    if (child.error || ![0, 2].includes(child.status)) return unavailable;
+    const report = assertMaintenanceResult(JSON.parse(child.stdout), target);
+    if (report.operation !== "inspect" || report.inspection_state !== "complete"
+        || report.maintenance_outcome !== "not_started" || report.compatibility.changes.length || report.compatibility.repair) return unavailable;
+    return { target, inspection_state: "complete", status: report.compatibility.status, counts: report.counts, authorizes: false };
+  } catch { return unavailable; }
+}
+
+export function startupMaintenanceInvocation(facts, { executable, validator, language = "en" }) {
+  if (!["migration_required", "repair_required", "unavailable"].includes(facts.status)) return null;
+  return { executable, argv: [validator, "control-maintenance", "--dir", facts.target, "--guided", "--language", language], authorizes: false };
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/control-state/run-recovery.js

@@ -0,0 +1,5 @@
+import { inspectRunRecovery as inspect, previewRunRecovery as preview } from "#agdf-core/control-state/run-recovery.js";
+import { readGitHistory } from "../runtime/git-history.js";
+export { applyRunRecovery, inspectSelfReferenceRecovery } from "#agdf-core/control-state/run-recovery.js";
+export const inspectRunRecovery = (root, runId, options = {}) => inspect(root, runId, { readGitHistory, ...options });
+export const previewRunRecovery = (root, runId, options = {}) => preview(root, runId, { readGitHistory, ...options });

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/claude.js

@@ -1,5 +1,5 @@
-import { execFileSync } from "node:child_process";
-import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+import { execHostFileSync } from "../../host-command.js";
+import { evaluatorOutputSchema, validateEvaluation } from "#agdf-core/delivery-path-search/contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
 import { buildEvaluatorPrompt } from "./prompt.js";
 
@@ -7,7 +7,7 @@ export function claudeEvaluator(options = {}) {
   const claudeBin = options.claudeBin ?? "claude";
   let runtime = "claude version unavailable";
   try {
-    runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    runtime = execHostFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {}
 
   return {

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/codex.js

@@ -1,8 +1,8 @@
-import { execFileSync } from "node:child_process";
+import { execHostFileSync } from "../../host-command.js";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { evaluatorOutputSchema, validateEvaluation } from "../contracts.js";
+import { evaluatorOutputSchema, validateEvaluation } from "#agdf-core/delivery-path-search/contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
 import { buildEvaluatorPrompt } from "./prompt.js";
 
@@ -10,7 +10,7 @@ export function codexEvaluator(options = {}) {
   const codexBin = options.codexBin ?? "codex";
   let runtime = "codex version unavailable";
   try {
-    runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    runtime = execHostFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
   } catch {}
 
   return {

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/opencode.js

@@ -1,6 +1,6 @@
-import { execFileSync, spawnSync } from "node:child_process";
+import { execHostFileSync, spawnHostSync } from "../../host-command.js";
 import process from "node:process";
-import { validateEvaluation } from "../contracts.js";
+import { validateEvaluation } from "#agdf-core/delivery-path-search/contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
 import { buildEvaluatorPrompt } from "./prompt.js";
 
@@ -80,7 +80,7 @@ function terminalPermissionDecision(permissions, permissionName) {
 
 export function preflightOpenCodeEvaluator(options = {}) {
   const executable = options.openCodeBin ?? process.env.AGDF_OPENCODE_BIN ?? "opencode";
-  const run = options.execFileSync ?? execFileSync;
+  const run = options.execFileSync ?? execHostFileSync;
   const cwd = options.cwd ?? process.cwd();
   const agentName = options.agentName ?? OPENCODE_EVALUATOR_AGENT;
   const env = openCodePermissionEnvironment(options.env ?? process.env);
@@ -100,7 +100,7 @@ export function preflightOpenCodeEvaluator(options = {}) {
         cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
       });
     } else {
-      const helpProbe = (options.spawnSync ?? spawnSync)(executable, ["run", "--help"], {
+      const helpProbe = (options.spawnSync ?? spawnHostSync)(executable, ["run", "--help"], {
         cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 5000,
       });
       if (helpProbe.error || helpProbe.status !== 0) throw helpProbe.error ?? new Error(helpProbe.stderr || "OpenCode run help failed.");

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/evaluators/protocol.js

@@ -1,4 +1,4 @@
-import { validateEvaluation } from "../contracts.js";
+import { validateEvaluation } from "#agdf-core/delivery-path-search/contracts.js";
 
 export function fixtureEvaluator(evaluations) {
   return {

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/generators/claude.js

@@ -1,12 +1,12 @@
-import { execFileSync } from "node:child_process";
-import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { execHostFileSync } from "../../host-command.js";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "#agdf-core/delivery-path-search/contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
 
 export function claudeGenerator(options = {}) {
   const claudeBin = options.claudeBin ?? "claude";
   const execute = options.execute ?? guardedExecFileSync;
   let runtime = options.runtime ?? "claude version unavailable";
-  if (!options.runtime) try { runtime = execFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  if (!options.runtime) try { runtime = execHostFileSync(claudeBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
   return {
     name: "claude",
     metadata: { name: "claude", runtime, model: options.model ?? "configured-default" },

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/generators/codex.js

@@ -1,15 +1,15 @@
-import { execFileSync } from "node:child_process";
+import { execHostFileSync } from "../../host-command.js";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { generatorOutputSchema, validateGeneratorRequest, validateGeneratorResponse } from "#agdf-core/delivery-path-search/contracts.js";
 import { guardedExecFileSync } from "../transports/read-only-guard.js";
 
 export function codexGenerator(options = {}) {
   const codexBin = options.codexBin ?? "codex";
   const execute = options.execute ?? guardedExecFileSync;
   let runtime = options.runtime ?? "codex version unavailable";
-  if (!options.runtime) try { runtime = execFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
+  if (!options.runtime) try { runtime = execHostFileSync(codexBin, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); } catch {}
   return {
     name: "codex",
     metadata: { name: "codex", runtime, model: options.model ?? "configured-default" },

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/generators/protocol.js

@@ -1,4 +1,4 @@
-import { validateGeneratorRequest, validateGeneratorResponse } from "../contracts.js";
+import { validateGeneratorRequest, validateGeneratorResponse } from "#agdf-core/delivery-path-search/contracts.js";
 
 export function fixtureGenerator(response, metadata = { name: "fixture-generator" }) {
   return {

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/surfaces/capabilities.js

@@ -1,4 +1,4 @@
-import { validateEnforcement } from "../contracts.js";
+import { validateEnforcement } from "#agdf-core/delivery-path-search/contracts.js";
 
 export function enforcementForSurface(surface, evidence = [], context = {}) {
   const defaults = {

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/delivery-path-search/transports/read-only-guard.js

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import { execHostFileSync } from "../../host-command.js";
 
 export function repositoryState(cwd) {
   try {
@@ -17,7 +18,7 @@ export function guardedExecFileSync(file, args, options = {}) {
   let output;
   let failure;
   try {
-    output = execFileSync(file, args, {
+    output = execHostFileSync(file, args, {
       ...options,
       encoding: options.encoding ?? "utf8",
       stdio: options.stdio ?? ["ignore", "pipe", "pipe"],

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/host-adapters/claude/session-command.js

@@ -0,0 +1,2 @@
+import { environmentSessionCommand } from "../session-command.js";
+export const sessionCommand = (_root, platform) => environmentSessionCommand("claude", platform);

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/host-adapters/codex/session-command.js

@@ -0,0 +1,7 @@
+import { environmentSessionCommand } from "../session-command.js";
+
+// Shared hooks.json: Claude Code runs `command` everywhere (PowerShell on Windows resolves only plain
+// ${CLAUDE_PLUGIN_ROOT}); Codex aliases it to PLUGIN_ROOT and uses commandWindows on Windows.
+export const sessionCommand = (_root, platform) => platform === "win32"
+  ? environmentSessionCommand("codex", platform)
+  : "node \"${CLAUDE_PLUGIN_ROOT}/runtime/agdf-session-check.js\"";

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/host-adapters/copilot/session-command.js

@@ -0,0 +1 @@
+export const sessionCommand = () => 'node "${PLUGIN_ROOT}/runtime/agdf-session-check.js"';

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/host-adapters/opencode/session-command.js

@@ -0,0 +1 @@
+export const sessionCommand = () => "plugin:agdf:automatic-runtime-checks";

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/host-adapters/session-command.js

@@ -0,0 +1,11 @@
+export function environmentSessionCommand(surface, platform) {
+  const [primary, fallback] = surface === "claude"
+    ? ["CLAUDE_PLUGIN_ROOT", "PLUGIN_ROOT"]
+    : ["PLUGIN_ROOT", "CLAUDE_PLUGIN_ROOT"];
+  if (platform === "win32") {
+    const primaryValue = `[Environment]::GetEnvironmentVariable('${primary}')`;
+    const fallbackValue = `[Environment]::GetEnvironmentVariable('${fallback}')`;
+    return `node \"$(if (${primaryValue}) { ${primaryValue} } else { ${fallbackValue} })\\runtime\\agdf-session-check.js\"`;
+  }
+  return `node \"\${${primary}:-\${${fallback}}}/runtime/agdf-session-check.js\"`;
+}

package/generated/plugins/copilot/agdf/runtime/create-agdf/lib/host-command.js

@@ -0,0 +1,112 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { win32 } from "node:path";
+import process from "node:process";
+
+// Host CLIs installed through npm on Windows are .cmd shims, which execFile cannot start (ENOENT for
+// the bare name, EINVAL for the shim itself since CVE-2024-27980). Recognized npm shims start their
+// target directly, so no argument passes through cmd.exe; any other shim fails closed.
+const LAUNCHABLE_EXTENSIONS = new Set([".com", ".exe"]);
+const SHIM_EXTENSIONS = new Set([".bat", ".cmd"]);
+const SHIM_BOILERPLATE = new Set([
+  "@echo off", "goto start", ":find_dp0", "set dp0=%~dp0", "exit /b", ":start", "setlocal", "call :find_dp0",
+  "endlocal", "exit /b %errorlevel%",
+  "if exist \"%dp0%\\node.exe\" (", "set \"_prog=%dp0%\\node.exe\"", ") else (", "set \"_prog=node\"",
+  "set pathext=%pathext:;.js;=;%", ")",
+]);
+const LAUNCH_PREFIX = /^endlocal & goto #_undefined_# 2>nul \|\| title %comspec% & /i;
+const DIRECT_LAUNCH = /^"%dp0%\\([^"%*]+)"\s+%\*$/i;
+const NODE_LAUNCH = /^"%_prog%"\s+((?:[^\s"%*]+\s+)*?)"%dp0%\\([^"%*]+)"\s+%\*$/i;
+
+// Like Node's spawn on Windows, the lexicographically first case-insensitive match wins, so
+// { ...process.env, PATH } resolves against the PATH the child process will actually receive.
+function envValue(env, name) {
+  const key = Object.keys(env).filter((candidate) => candidate.toUpperCase() === name).sort()[0];
+  return key === undefined ? undefined : env[key];
+}
+
+function isFile(path, fs) {
+  try {
+    return fs.statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function unsupportedShim(path) {
+  const error = new Error(`AGDF_HOST_COMMAND_UNSUPPORTED_SHIM: ${path} is not a recognized npm command shim; AGDF does not start host commands through cmd.exe.`);
+  error.code = "AGDF_HOST_COMMAND_UNSUPPORTED_SHIM";
+  return error;
+}
+
+export function findWindowsCommand(command, { env = process.env, fs = { statSync }, extensions } = {}) {
+  const candidates = extensions ?? (envValue(env, "PATHEXT") || ".COM;.EXE;.BAT;.CMD").split(";")
+    .map((extension) => extension.trim().toLowerCase())
+    .filter((extension) => LAUNCHABLE_EXTENSIONS.has(extension) || SHIM_EXTENSIONS.has(extension));
+  const directories = (envValue(env, "PATH") || "").split(";")
+    .map((directory) => directory.trim().replace(/^"(.*)"$/, "$1"))
+    .filter((directory) => directory && win32.isAbsolute(directory));
+  for (const directory of directories) {
+    for (const extension of candidates) {
+      const candidate = win32.join(directory, `${command}${extension}`);
+      if (isFile(candidate, fs)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function parseNpmCmdShim(shimPath, content) {
+  const lines = content.replace(/\r\n/g, "\n").split("\n").map((line) => line.trim()).filter(Boolean);
+  const launches = lines.filter((line) => line.includes("%*"));
+  if (launches.length !== 1 || lines.some((line) => !line.includes("%*") && !SHIM_BOILERPLATE.has(line.toLowerCase()))) return null;
+  const directory = win32.dirname(shimPath);
+  const launch = launches[0].replace(LAUNCH_PREFIX, "");
+  const direct = launch.match(DIRECT_LAUNCH);
+  if (direct) {
+    return LAUNCHABLE_EXTENSIONS.has(win32.extname(direct[1]).toLowerCase())
+      ? { executable: win32.resolve(directory, direct[1]), prefixArgs: [] }
+      : null;
+  }
+  const viaNode = launch.match(NODE_LAUNCH);
+  if (!viaNode || !lines.some((line) => line.toLowerCase() === "set \"_prog=node\"")) return null;
+  return {
+    node: win32.join(directory, "node.exe"),
+    prefixArgs: [...viaNode[1].split(/\s+/).filter(Boolean), win32.resolve(directory, viaNode[2])],
+  };
+}
+
+export function resolveHostCommand(command, {
+  env = process.env, platform = process.platform, execPath = process.execPath, fs = { readFileSync, statSync },
+} = {}) {
+  const unresolved = { executable: command, prefixArgs: [] };
+  if (platform !== "win32") return unresolved;
+  const explicitShim = /[\\/]/.test(command) && SHIM_EXTENSIONS.has(win32.extname(command).toLowerCase());
+  if (!explicitShim && (/[\\/]/.test(command) || win32.extname(command))) return unresolved;
+  if (explicitShim && !isFile(command, fs)) {
+    throw Object.assign(new Error(`spawn ${command} ENOENT`), { code: "ENOENT", syscall: `spawn ${command}`, path: command });
+  }
+  const found = explicitShim ? command : findWindowsCommand(command, { env, fs });
+  if (!found) return unresolved;
+  if (LAUNCHABLE_EXTENSIONS.has(win32.extname(found).toLowerCase())) return { executable: found, prefixArgs: [] };
+  const shim = parseNpmCmdShim(found, fs.readFileSync(found, "utf8"));
+  if (!shim) throw unsupportedShim(found);
+  if (shim.executable) return { executable: shim.executable, prefixArgs: [] };
+  const node = isFile(shim.node, fs) ? shim.node
+    : findWindowsCommand("node", { env, fs, extensions: [".com", ".exe"] }) ?? execPath;
+  return { executable: node, prefixArgs: shim.prefixArgs };
+}
+
+export function execHostFileSync(command, args = [], options = {}) {
+  const { executable, prefixArgs } = resolveHostCommand(command, { env: options.env ?? process.env });
+  return execFileSync(executable, [...prefixArgs, ...args], options);
+}
+
+export function spawnHostSync(command, args = [], options = {}) {
+  let resolved;
+  try {
+    resolved = resolveHostCommand(command, { env: options.env ?? process.env });
+  } catch (error) {
+    return { pid: 0, output: [null, "", ""], stdout: "", stderr: "", status: null, signal: null, error };
+  }
+  return spawnSync(resolved.executable, [...resolved.prefixArgs, ...args], options);
+}