create-agdf 0.14.4 → 0.20.0

package/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/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/lib/host-adapters/claude/loaded-sessions.js

@@ -0,0 +1,45 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import process from "node:process";
+import { claudeConfigDir } from "./plugin-mcp.js";
+
+// Claude Code marks every session that loaded a plugin version with `.in_use/<pid>` in its cache.
+// A running session keeps files of the AGDF marketplace and cache open; on Windows those handles
+// can block or break an in-place update, so the installer reports live sessions before the swap.
+export function loadedClaudeSessions({ env = process.env, isAlive = processAlive } = {}) {
+  const pluginCache = join(claudeConfigDir(env), "plugins", "cache", "agdf", "agdf");
+  if (!existsSync(pluginCache)) return [];
+  const sessions = [];
+  for (const version of safeList(pluginCache)) {
+    for (const entry of safeList(join(pluginCache, version, ".in_use"))) {
+      const pid = Number(entry);
+      if (Number.isInteger(pid) && pid > 0 && pid !== process.pid && isAlive(pid)) sessions.push({ pid, version });
+    }
+  }
+  return sessions;
+}
+
+export function loadedSessionEvidence(sessions) {
+  if (sessions.length === 0) return [];
+  return [`claude_sessions_with_agdf:${sessions.map((session) => session.pid).join(",")}`];
+}
+
+export function loadedSessionLockHint(error, sessions) {
+  if (sessions.length === 0 || !["EPERM", "EBUSY", "EACCES"].includes(error?.code)) return error;
+  error.message = `${error.message} Claude Code sessions with AGDF loaded are still running (pid ${sessions.map((session) => session.pid).join(", ")}); close them and run the installation again.`;
+  error.evidence = { ...(error.evidence ?? {}), claude_sessions_with_agdf: sessions.map((session) => session.pid).join(",") };
+  return error;
+}
+
+function safeList(path) {
+  try { return readdirSync(path); } catch { return []; }
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "EPERM";
+  }
+}

package/lib/host-adapters/claude/marketplace.js

@@ -0,0 +1,2 @@
+// Claude exposes a plain array; shared ownership classification validates it.
+export const marketplaceEntries = parsed => parsed;

package/lib/host-adapters/claude/permission-rules.js

@@ -0,0 +1,20 @@
+// Earlier releases wrote one exact Bash or PowerShell permission rule that runs the plugin-relative
+// agdf-session-check.js through a PLUGIN_ROOT variable. Claude Code runs plugin hooks without any
+// permission rule, so these rules are only recognised and revoked, never written.
+const LEGACY_RUNTIME_CHECK_RULE = /^(?:Bash|PowerShell)\(node "[^"]*PLUGIN_ROOT[^"]*[\\/]runtime[\\/]agdf-session-check\.js"\)$/u;
+
+export function ownedRuntimeCheckRules(settings) {
+  const allow = settings?.permissions?.allow;
+  return Array.isArray(allow) ? allow.filter((rule) => typeof rule === "string" && LEGACY_RUNTIME_CHECK_RULE.test(rule)) : [];
+}
+
+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);
+    // A block emptied by revocation means nothing; dropping it lets uninstall leave no AGDF trace.
+    if (next.permissions.allow.length === 0) delete next.permissions.allow;
+    if (Object.keys(next.permissions).length === 0) delete next.permissions;
+  }
+  return next;
+}

package/lib/host-adapters/claude/plugin-mcp.js

@@ -0,0 +1,40 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import process from "node:process";
+import { claudePluginDataRoot } from "../../mcp-lifecycle/plugin-runtime.js";
+import { runMcpLifecycle } from "../../mcp-lifecycle/service.js";
+
+// The AGDF MCP server ships with the Claude plugin (see mcp/claude.mcp.json). These helpers only
+// prewarm its runtime in ${CLAUDE_PLUGIN_DATA} and retire what earlier releases registered outside
+// the plugin, which `claude plugin uninstall` would otherwise leave behind.
+
+export function claudeConfigDir(env = process.env) {
+  return resolve(env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude"));
+}
+
+export function prepareClaudePluginMcp({ exec, env = process.env, pluginRoot, execPath = process.execPath }) {
+  const dataRoot = claudePluginDataRoot({ claudeConfigDir: claudeConfigDir(env) });
+  try {
+    exec(execPath, [join(pluginRoot, "mcp", "agdf-mcp-launch.js"), "--prepare"], {
+      env: { ...env, CLAUDE_PLUGIN_DATA: dataRoot },
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return ["claude_plugin_mcp:prepared"];
+  } catch {
+    return ["claude_plugin_mcp:deferred_to_first_start"];
+  }
+}
+
+export function migrateLegacyClaudeMcpRegistration({ exec, env = process.env, mcpLifecycle = runMcpLifecycle }) {
+  let output;
+  try { output = String(exec("claude", ["mcp", "get", "agdf"], { encoding: "utf8", stdio: "pipe" }) ?? ""); } catch { return []; }
+  // Only a user-scope registration of the AGDF-owned server is migrated; everything else is left alone.
+  if (!/^\s*Scope:\s*User config/mu.test(output) || !/agdf-mcp\.js --surface claude\s*$/mu.test(output)) return [];
+  try {
+    const report = mcpLifecycle({ action: "disable", surface: "claude", scope: "user", target: homedir(), env, exec });
+    return [`legacy_user_mcp_registration:${report.result}`];
+  } catch {
+    return ["legacy_user_mcp_registration:retained"];
+  }
+}