create-agdf 0.13.7 → 0.14.1

package/lib/cli/application.js

@@ -1,4 +1,6 @@
 import { join } from "node:path";
+import { emitKeypressEvents } from "node:readline";
+import { createInterface } from "node:readline/promises";
 import process from "node:process";
 import {
   createRun,
@@ -15,6 +17,7 @@ import {
 } from "../installers/opencode.js";
 import {
   installClaudeGlobalPlugin,
+  installCopilotGlobalPlugin,
   installCodexGlobalPlugin,
 } from "../installers/plugin-installers.js";
 import {
@@ -26,8 +29,9 @@ import {
 } from "../lifecycle/operations.js";
 import { printGeneralStatus, printLifecycleResult } from "../lifecycle/presentation.js";
 import { createLifecycleResult, globalInstallRestartAction, lifecycleFailure } from "../lifecycle/result.js";
+import { prepareInstallConsent, persistInstallConsent, retainCurrentInstallConsent, runtimeCheckStatus, setRuntimeChecksManual } from "../runtime-check-consent/service.js";
 import { evaluateGeneralStatus } from "../lifecycle/status.js";
-import { agdfFragmentPath, generatedFilesForTarget } from "../scaffold/plan.js";
+import { generatedFilesForTarget } from "../scaffold/plan.js";
 import { printNextSteps } from "../scaffold/presentation.js";
 import { assertGeneratedWritePlan, writeGeneratedFile } from "../scaffold/write.js";
 import { renderUsage, resolveCommand, validateCommandOptions } from "./command-registry.js";
@@ -35,19 +39,19 @@ import { CliUsageError, parseArgs } from "./parse-args.js";
 import { pluginDefinition } from "./runtime-context.js";
 import { createValidationHandlers } from "./validation-handlers.js";
 
-function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
+function createHandlers({ io, env, exec, packagedCopilotExec, prepare, openCodePackageSource, copilotSettingsPath, askRuntimeCheckDecision, interactive }) {
   const installerAdapters = {
     ...(exec ? { exec } : {}),
+    ...(packagedCopilotExec ? { packagedCopilotExec } : {}),
     ...(prepare ? { prepare } : {}),
+    ...(copilotSettingsPath ? { copilotSettingsPath } : {}),
     ...(env.AGDF_DATA_DIR ? { dataRoot: env.AGDF_DATA_DIR } : {}),
   };
   const scaffoldHandler = (options) => runScaffold(options, io);
   return new Map([
     ...createValidationHandlers(io),
     ["codex-repo", scaffoldHandler],
-    ["copilot", scaffoldHandler],
     ["opencode-repo", scaffoldHandler],
-    ["both", scaffoldHandler],
     ["init", scaffoldHandler],
     ["config", scaffoldHandler],
     ["run-create", (options) => {
@@ -75,19 +79,42 @@ function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
       const report = evaluateGeneralStatus(options.dir, {
         ...options,
         configDir: env.OPENCODE_CONFIG_DIR || defaultOpenCodeConfigDir(),
+        dataRoot: env.AGDF_DATA_DIR,
       }, { exec });
       printGeneralStatus(report, { json: options.json, io });
       return report.installation.status === "healthy" ? 0 : 1;
     }],
+    ["runtime-checks", (options) => {
+      const report = options.runtimeChecksAction === "manual"
+        ? setRuntimeChecksManual({ dataRoot: env.AGDF_DATA_DIR, surface: options.surface })
+        : runtimeCheckStatus(env.AGDF_DATA_DIR, options.surface);
+      if (options.runtimeChecksAction === "enable") {
+        report.next_action = `Rerun npx --yes @agdf/cli@latest ${options.surface} --runtime-checks ${options.runtimeChecksAction}; installation ownership and capability identity are revalidated before consent is persisted.`;
+      }
+      io.log(options.json ? JSON.stringify(report, null, 2) : [
+        "AGDF automatic runtime checks",
+        `Requested: ${report.requested}`,
+        `Effective: ${report.effective}`,
+        `Reason: ${report.reason}`,
+        ...(report.next_action ? [`Next action: ${report.next_action}`] : []),
+      ].join("\n"));
+      return report.effective === "enabled" || report.effective === "manual" ? 0 : 1;
+    }],
     ["disable", (options) => runDisable(options, { io, exec })],
     ["uninstall", (options) => runUninstall(options, { io, env, exec })],
-    ["codex", (options) => {
+    ["codex", async (options) => {
       try {
+        const consent = await installConsentDecision("codex", options, { io, askRuntimeCheckDecision, interactive, dataRoot: installerAdapters.dataRoot });
+        if (consent.decision === "cancel") return printCancelledConsent("codex", options, io);
+        printInstallProgress("codex", options, io, interactive);
         const installed = installCodexGlobalPlugin(installerAdapters);
+        const finalizedConsent = finalizeInstallConsent(consent, { surface: "codex", installed, dataRoot: installerAdapters.dataRoot });
         printLifecycleResult(installResult(installed, {
           restartRequired: true,
-          nextAction: globalInstallRestartAction(options.target).text,
-        }), { json: options.json, io });
+          nextAction: installNextAction("codex", finalizedConsent.state, globalInstallRestartAction(options.target).text),
+          runtimeChecks: finalizedConsent.state,
+          consentFailure: finalizedConsent.failure,
+        }), { json: options.json, compact: !options.verbose, io });
         printVerboseHostOutput(installed, options, io);
         return 0;
       } catch (error) {
@@ -95,13 +122,19 @@ function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
         return 1;
       }
     }],
-    ["claude", (options) => {
+    ["claude", async (options) => {
       try {
+        const consent = await installConsentDecision("claude", options, { io, askRuntimeCheckDecision, interactive, dataRoot: installerAdapters.dataRoot });
+        if (consent.decision === "cancel") return printCancelledConsent("claude", options, io);
+        printInstallProgress("claude", options, io, interactive);
         const installed = installClaudeGlobalPlugin(installerAdapters);
+        const finalizedConsent = finalizeInstallConsent(consent, { surface: "claude", installed, dataRoot: installerAdapters.dataRoot });
         printLifecycleResult(installResult(installed, {
           restartRequired: true,
           nextAction: globalInstallRestartAction(options.target).text,
-        }), { json: options.json, io });
+          runtimeChecks: finalizedConsent.state,
+          consentFailure: finalizedConsent.failure,
+        }), { json: options.json, compact: !options.verbose, io });
         printVerboseHostOutput(installed, options, io);
         return 0;
       } catch (error) {
@@ -109,9 +142,62 @@ function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
         return 1;
       }
     }],
-    ["opencode", (options) => {
+    ["copilot", async (options) => {
+      const surface = "copilot";
+      try {
+        const consent = await installConsentDecision(surface, options, { io, askRuntimeCheckDecision, interactive, dataRoot: installerAdapters.dataRoot });
+        if (consent.decision === "cancel") return printCancelledConsent(surface, options, io);
+        printInstallProgress(surface, options, io, interactive);
+        const installed = installCopilotGlobalPlugin({
+          ...installerAdapters,
+        });
+        const finalizedConsent = finalizeInstallConsent(consent, { surface, installed, dataRoot: installerAdapters.dataRoot });
+        if (installed.declarativeConfigured) {
+          printLifecycleResult(createLifecycleResult({
+            operation: "install", result: "partial", surface, scope: "global",
+            version: { expected: installed.expectedVersion, installed: null, status: "unknown" },
+            verification: { status: "configured_pending_restart", evidence: installed.evidence },
+            installation: { status: "configured_pending_restart" },
+            activation: { status: "pending_restart" },
+            runtime_checks: finalizedConsent.state,
+            restart: { required: true, reason: "host_reload" },
+            next_action: { kind: "restart", text: "Restart GitHub Copilot. Then verify AGDF in Plugins and the agdf- skills in a fresh session." },
+          }), { json: options.json, compact: !options.verbose, io });
+          return 0;
+        }
+        if (installed.manualHandoff) {
+          printLifecycleResult(createLifecycleResult({
+            operation: "install", result: "partial", surface, scope: "global",
+            version: { expected: installed.expectedVersion, installed: null, status: "unknown" },
+            verification: { status: "unavailable", evidence: installed.evidence },
+            installation: { status: "not_verified" },
+            activation: { status: "not_verified" },
+            runtime_checks: finalizedConsent.state,
+            restart: { required: false, reason: "none" },
+            next_action: { kind: "manual_install", text: `In GitHub Copilot, run /plugins install ${installed.pluginRoot}. Then run /restart and verify /plugins list and /skills list.` },
+            failure: { phase: "executable", message: "Copilot CLI was not available; no plugin installation was performed." },
+          }), { json: options.json, compact: !options.verbose, io });
+          return 1;
+        }
+        printLifecycleResult(installResult(installed, {
+          restartRequired: true,
+          nextAction: installNextAction(surface, finalizedConsent.state, globalInstallRestartAction(surface).text),
+          runtimeChecks: finalizedConsent.state,
+          consentFailure: finalizedConsent.failure,
+        }), { json: options.json, compact: !options.verbose, io });
+        printVerboseHostOutput(installed, options, io);
+        return installed.verificationStatus === "healthy" ? 0 : 1;
+      } catch (error) {
+        printInstallFailure(surface, error, options, io, "copilot");
+        return 1;
+      }
+    }],
+    ["opencode", async (options) => {
       const configDir = options.dirExplicit ? options.dir : defaultOpenCodeConfigDir();
       try {
+        const consent = await installConsentDecision("opencode", options, { io, askRuntimeCheckDecision, interactive, dataRoot: installerAdapters.dataRoot });
+        if (consent.decision === "cancel") return printCancelledConsent("opencode", options, io);
+        printInstallProgress("opencode", options, io, interactive);
         const result = runLifecyclePhase("plugin_operation", () => installOpenCodeGlobalPlugin(configDir, { packageSource: openCodePackageSource }));
         runLifecyclePhase("global_surface", () => installOpenCodeGlobalSurface(configDir));
         const report = runLifecyclePhase("verification", () => evaluateOpenCodeStatus(options.dir, configDir, result.transition));
@@ -128,9 +214,18 @@ function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
               kind: "recovery",
               text: `Retry the OpenCode installation to align @opencode-ai/plugin to ${result.sdk_alignment.target_version || "the exact host version"}; observed SDK: ${result.sdk_alignment.installed_version || "unknown"}.`,
             };
+        const finalizedConsent = finalizeInstallConsent(consent, {
+              surface: "opencode",
+              installed: {
+                pluginRoot: result.installed_package.root,
+                digest: result.installed_package.digest,
+                sourceDigest: result.package_source.digest || result.installed_package.digest,
+              },
+              dataRoot: installerAdapters.dataRoot,
+            });
         printLifecycleResult(createLifecycleResult({
           operation: result.transition.status === "updated" ? "update" : "install",
-          result: verificationHealthy ? "success" : "partial",
+          result: verificationHealthy && !finalizedConsent.failure ? "success" : "partial",
           surface: options.target,
           scope: "global",
           version: {
@@ -154,9 +249,11 @@ function createHandlers({ io, env, exec, prepare, openCodePackageSource }) {
             ],
           },
           restart: { required: true, reason: "host_reload" },
+          runtime_checks: finalizedConsent.state,
           next_action: nextAction,
-        }), { json: options.json, io });
-        if (!options.json) {
+          failure: finalizedConsent.failure,
+        }), { json: options.json, compact: !options.verbose, io });
+        if (options.verbose && !options.json) {
           io.log(`OpenCode host / plugin SDK: ${report.host.installed_version || "unknown"} / ${report.plugin_sdk.installed_version || "unknown"} (${report.host_sdk_version.status}; ${report.host_sdk_version.policy})`);
           io.log(`Plugin SDK alignment: ${result.sdk_alignment.status} (target ${result.sdk_alignment.target_version || "unknown"}; installed ${result.sdk_alignment.installed_version || "unknown"})`);
           io.log(`Experimental hook declarations: ${report.experimental_hooks.aggregate} (SDK declaration evidence; live invocation not observed)`);
@@ -180,10 +277,20 @@ function runLifecyclePhase(phase, operation) {
   }
 }
 
-function installResult(installed, { restartRequired, nextAction }) {
+function installNextAction(surface, runtimeChecks, fallback) {
+  if (surface === "codex" && runtimeChecks.requested === "enabled" && runtimeChecks.effective === "decision_required") {
+    return "Restart Codex, then approve the AGDF session hook when Codex asks.";
+  }
+  if (surface === "copilot" && runtimeChecks.requested === "enabled" && runtimeChecks.effective === "decision_required") {
+    return "Restart GitHub Copilot, then review the AGDF session hook when Copilot asks.";
+  }
+  return fallback;
+}
+
+function installResult(installed, { restartRequired, nextAction, runtimeChecks, consentFailure }) {
   return createLifecycleResult({
     operation: installed.operation ?? "install",
-    result: "success",
+    result: consentFailure ? "partial" : "success",
     surface: installed.surface,
     scope: "global",
     version: { expected: installed.expectedVersion, installed: installed.installedVersion, status: installed.installedVersion ? "verified" : "unknown" },
@@ -191,18 +298,120 @@ function installResult(installed, { restartRequired, nextAction }) {
     installation: { status: installed.verificationStatus },
     activation: { status: restartRequired ? "pending_restart" : "active" },
     delivery: { status: "not_evaluated" },
+    runtime_checks: runtimeChecks,
     restart: { required: restartRequired, reason: restartRequired ? "host_reload" : "none" },
     next_action: { kind: restartRequired ? "restart" : "prompt", text: nextAction },
+    failure: consentFailure,
   });
 }
 
+function finalizeInstallConsent(consent, input) {
+  if (!consent.persist) return {
+    state: consent.retained && consent.decision === "enable"
+      ? { requested: "enabled", effective: "decision_required", reason: "host_permission_unverified" }
+      : { requested: "manual", effective: "manual", reason: "consent_not_provided" },
+    failure: null,
+  };
+  try {
+    return { state: persistInstallConsent({ ...input, decision: consent.decision }), failure: null };
+  } catch (error) {
+    return {
+      state: { requested: consent.decision === "enable" ? "enabled" : "manual", effective: "failed", reason: "configuration_invalid" },
+      failure: { phase: "runtime_check_permission", message: error.message },
+    };
+  }
+}
+
+async function installConsentDecision(surface, options, { io, askRuntimeCheckDecision, interactive, dataRoot }) {
+  if (options.runtimeChecksDecision !== undefined) return prepareInstallConsent(surface, options);
+  if (!interactive || options.json || typeof askRuntimeCheckDecision !== "function") {
+    return prepareInstallConsent(surface, options);
+  }
+  const retained = retainCurrentInstallConsent(surface, dataRoot);
+  const disclosure = prepareInstallConsent(surface, { ...options, runtimeChecksDecision: "manual" }).disclosure;
+  printInstallConsentDisclosure(disclosure, retained, io);
+  const answer = await askRuntimeCheckDecision(disclosure);
+  return prepareInstallConsent(surface, { ...options, runtimeChecksDecision: answer });
+}
+
+function printInstallConsentDisclosure(disclosure, retained, io) {
+  const host = installSurfaceLabel(disclosure.surface);
+  io.log("");
+  io.log(`AGDF ${pluginDefinition.version} for ${host}`);
+  io.log(`Applies to this ${host} installation for your user account.`);
+  io.log("");
+  io.log(`Let AGDF check your project status automatically ${disclosure.when}?`);
+  if (retained) {
+    io.log(retained.decision === "enable"
+      ? "Your previous choice: automatic checks requested"
+      : "Your previous choice: manual checks");
+    if (retained.decision === "enable") io.log(`${host} permission: checked after installation`);
+  }
+  io.log("");
+  io.log("Safe by design");
+  io.log("  Reads only AGDF runtime information and .agdf/control in this project");
+  io.log("  Changes no project files and uses no network");
+  io.log("  Never approves AGDF work");
+  io.log("");
+  io.log(`AGDF saves your choice. ${host} remains in control of permission.`);
+  io.log("You choose again for every install or update and whenever the check changes.");
+  io.log(`Turn it off anytime: ${disclosure.revocation}`);
+  io.log("");
+  io.log("Choose");
+  io.log("  [1] Yes, check automatically");
+  io.log("  [2] No automatic checks");
+  io.log("      AGDF still works. Checks run when you request them.");
+  io.log("  [D] Show technical details");
+  io.log("  [Esc] Cancel installation");
+}
+
+function installSurfaceLabel(surface) {
+  if (surface === "claude") return "Claude Code";
+  if (surface === "copilot") return "GitHub Copilot";
+  if (surface === "opencode") return "OpenCode";
+  return "Codex";
+}
+
+function printInstallProgress(surface, options, io, interactive) {
+  if (!interactive || options.json) return;
+  io.log("");
+  io.log(`Setting up AGDF ${pluginDefinition.version} for ${installSurfaceLabel(surface)}...`);
+}
+
+function installConsentTechnicalDetails(disclosure) {
+  return [
+    "",
+    "Technical details",
+    `  Applies to: ${disclosure.installation_scope}`,
+    `  Runs: ${disclosure.runs} ${disclosure.when}`,
+    `  Reads: ${disclosure.reads}`,
+    `  Saves: ${disclosure.writes}`,
+    `  Permission control: ${disclosure.permission_owner}`,
+    `  Command: ${disclosure.executable}`,
+    `  Renewal: ${disclosure.renewal}`,
+    "",
+  ];
+}
+
+function printCancelledConsent(surface, options, io) {
+  const report = createLifecycleResult({
+    operation: "install", result: "preview", surface, scope: "global",
+    verification: { status: "unknown", evidence: ["cancelled_before_mutation"] },
+    runtime_checks: { requested: "cancelled", effective: "cancelled", reason: "consent_not_provided" },
+    restart: { required: false },
+    next_action: { kind: "none", text: "Installation was cancelled before any plugin or permission mutation." },
+  });
+  printLifecycleResult(report, { json: options.json, compact: true, io });
+  return 0;
+}
+
 function printVerboseHostOutput(installed, options, io) {
   if (!options.verbose || options.json || !installed.nativeOutput?.length) return;
   io.log("Host command output:");
   for (const output of installed.nativeOutput) io.log(output);
 }
 
-function printInstallFailure(surface, error, options, io) {
+function printInstallFailure(surface, error, options, io, command = surface) {
   const report = lifecycleFailure({
     operation: "install",
     surface,
@@ -210,7 +419,7 @@ function printInstallFailure(surface, error, options, io) {
     phase: error.phase || "plugin_operation",
     message: error.message,
     evidence: [error.evidence ?? {}],
-    nextAction: `Resolve the ${error.phase || "plugin operation"} failure and rerun npx --yes @agdf/cli@latest ${surface}.`,
+    nextAction: `Resolve the ${error.phase || "plugin operation"} failure and rerun npx --yes @agdf/cli@latest ${command}.`,
   });
   if (options.json) printLifecycleResult(report, { json: true, io });
   else {
@@ -291,7 +500,6 @@ function runUninstall(options, { io, env, exec }) {
 
 function runScaffold(options, io) {
   const files = generatedFilesForTarget(options.target, options.dir, options.force, options.language);
-  const wroteAgentsFragment = files.some((file) => file.path === agdfFragmentPath);
   let removedOpenCodeAgents = [];
 
   try {
@@ -306,7 +514,7 @@ function runScaffold(options, io) {
     return 1;
   }
 
-  printNextSteps(options.target, options.dir, files, wroteAgentsFragment, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
+  printNextSteps(options.target, options.dir, files, removedOpenCodeAgents, { verbose: options.verbose, json: options.json, io });
   return 0;
 }
 
@@ -342,9 +550,72 @@ export async function runCli(argv = process.argv.slice(2), adapters = {}) {
   }
   const command = resolveCommand(options.target);
   if (!command) throw new Error(`No handler is registered for ${options.target}.`);
-  const handler = createHandlers({ io, env, exec: adapters.exec, prepare: adapters.prepare, openCodePackageSource: adapters.openCodePackageSource }).get(command.handler);
+  const handler = createHandlers({
+    io,
+    env,
+    exec: adapters.exec,
+    packagedCopilotExec: adapters.packagedCopilotExec,
+    prepare: adapters.prepare,
+    openCodePackageSource: adapters.openCodePackageSource,
+    copilotSettingsPath: adapters.copilotSettingsPath,
+    askRuntimeCheckDecision: adapters.askRuntimeCheckDecision ?? defaultAskRuntimeCheckDecision,
+    interactive: adapters.interactive ?? (Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY)),
+  }).get(command.handler);
   if (!handler) throw new Error(`No implementation is registered for ${command.name}.`);
   return await handler(options);
 }
 
 export const main = runCli;
+
+async function defaultAskRuntimeCheckDecision(disclosure) {
+  if (process.stdin.isTTY && typeof process.stdin.setRawMode === "function") {
+    return askRuntimeCheckDecisionByKey(process.stdin, process.stdout, disclosure);
+  }
+  const prompt = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    while (true) {
+      const answer = (await prompt.question("Choice (1/2/D/cancel): ")).trim().toLowerCase();
+      if (["1", "e", "enable"].includes(answer)) return "enable";
+      if (["2", "m", "manual"].includes(answer)) return "manual";
+      if (["d", "details"].includes(answer)) {
+        for (const line of installConsentTechnicalDetails(disclosure)) process.stdout.write(`${line}\n`);
+        continue;
+      }
+      if (["c", "cancel"].includes(answer)) return "cancel";
+      process.stdout.write("Press 1, 2 or D, or type cancel.\n");
+    }
+  } finally {
+    prompt.close();
+  }
+}
+
+export async function askRuntimeCheckDecisionByKey(input, output, disclosure) {
+  const wasRaw = Boolean(input.isRaw);
+  emitKeypressEvents(input);
+  output.write("Choice: ");
+  if (!wasRaw) input.setRawMode(true);
+  input.resume();
+
+  return await new Promise((resolve) => {
+    const finish = (decision) => {
+      input.off("keypress", onKeypress);
+      if (!wasRaw) input.setRawMode(false);
+      input.pause();
+      output.write(`${decision}\n`);
+      resolve(decision);
+    };
+    const onKeypress = (character, key = {}) => {
+      if (key.name === "escape" || (key.ctrl && key.name === "c")) return finish("cancel");
+      const choice = String(character || "").toLowerCase();
+      if (["1", "e"].includes(choice)) return finish("enable");
+      if (["2", "m"].includes(choice)) return finish("manual");
+      if (choice === "c") return finish("cancel");
+      if (choice === "d" && disclosure) {
+        output.write(`details\n${installConsentTechnicalDetails(disclosure).join("\n")}Choice: `);
+        return;
+      }
+      output.write("\nPress 1, 2, D or Esc.\nChoice: ");
+    };
+    input.on("keypress", onKeypress);
+  });
+}

package/lib/cli/command-registry.js

@@ -13,14 +13,14 @@ export const commandRegistry = Object.freeze([
   command("codex", { preferred: [""], scaffold: [""] }),
   command("codex-repo", { preferred: [""], scaffold: [""] }),
   command("claude", { preferred: [""], scaffold: [""] }),
-  command("copilot", { preferred: [""], scaffold: [""] }),
+  command("copilot", { preferred: [""] }),
   command("opencode", { preferred: [""], scaffold: [""] }),
   command("opencode-status", { preferred: [""], scaffold: [""] }),
   command("status", { preferred: [" [--surface <surface>] [--run <run_id>] [--json]"] }),
+  command("runtime-checks", { preferred: [" <status|enable|manual> --surface <codex|claude|copilot|opencode> [--json]"] }),
   command("disable", { preferred: [" --surface <surface> [--scope repository] [--dir <path>]"] }),
   command("uninstall", { preferred: [" --surface <surface> --scope global [--confirm]"] }),
   command("opencode-repo", { preferred: [""], scaffold: [""] }),
-  command("both", { scaffold: [""] }),
   command("init", { preferred: [""], scaffold: [""] }),
   command("config", { scaffold: [" --language de"] }),
   command("doctor", { local: [""], scaffold: [""], legacy: [" --json"] }),
@@ -65,6 +65,12 @@ export function validateCommandOptions(options) {
     throw new Error("uninstall requires explicit --scope global");
   }
   if (options.confirm && options.target !== "uninstall") throw new Error("--confirm is supported only by uninstall");
+  if (options.runtimeChecksDecision && !["codex", "claude", "copilot", "opencode"].includes(options.target)) {
+    throw new Error("--runtime-checks is supported only by codex, claude, copilot and opencode installation commands");
+  }
+  if (options.target === "runtime-checks" && !["codex", "claude", "copilot", "opencode"].includes(options.surface)) {
+    throw new Error("runtime-checks requires --surface codex, claude, copilot or opencode");
+  }
   if (options.approvalEnvelope && options.target !== "gate-check") throw new Error("--approval-envelope is supported only by gate-check");
   if (options.approvalEnvelope && (options.json || options.statusCard || options.allActive)) {
     throw new Error("--approval-envelope cannot be combined with --json, --status-card or --all-active");
@@ -120,6 +126,8 @@ Options:
   --scope <repository|global>
                  Select the lifecycle mutation scope
   --confirm      Apply a previously previewed global uninstall plan
+  --runtime-checks <enable|manual|cancel>
+                 Make the installation-time automatic-check decision explicitly; no TTY defaults to manual
   --fixture <path>
                  Use deterministic evaluator/candidate fixtures instead of a live evaluator
   --persist      Persist the redacted Delivery Path Search result under the current scope

package/lib/cli/parse-args.js

@@ -45,6 +45,8 @@ export function parseArgs(argv, dependencies = {}) {
   let allActive = false;
   let scope;
   let confirm = false;
+  let runtimeChecksDecision;
+  let runtimeChecksAction;
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -60,6 +62,14 @@ export function parseArgs(argv, dependencies = {}) {
     if (arg === "--all-active") { allActive = true; continue; }
     if (arg === "--confirm") { confirm = true; continue; }
 
+    if (arg === "--runtime-checks") {
+      const next = requiredValue(args, i, arg);
+      if (!["enable", "manual", "cancel"].includes(next)) throw new CliUsageError("--runtime-checks must be enable, manual or cancel.");
+      runtimeChecksDecision = next;
+      i += 1;
+      continue;
+    }
+
     if (arg === "--run") {
       runId = requiredValue(args, i, arg);
       i += 1;
@@ -119,6 +129,11 @@ export function parseArgs(argv, dependencies = {}) {
       target = arg;
       continue;
     }
+    if (!arg.startsWith("-") && target === "runtime-checks" && !runtimeChecksAction) {
+      if (!["status", "enable", "manual"].includes(arg)) throw new CliUsageError("runtime-checks action must be status, enable or manual.");
+      runtimeChecksAction = arg;
+      continue;
+    }
     throw new CliUsageError(`Unknown argument: ${arg}`);
   }
 
@@ -147,6 +162,8 @@ export function parseArgs(argv, dependencies = {}) {
       allActive,
       scope,
       confirm,
+      runtimeChecksDecision,
+      runtimeChecksAction: runtimeChecksAction ?? "status",
       generatorModel,
       maxGeneratedCandidates,
       generationTimeoutMs,

package/lib/installers/copilot-precedence.js

@@ -0,0 +1,34 @@
+function skillNames(values, field) {
+  if (!Array.isArray(values) || values.some((value) => typeof value !== "string" || !value.trim())) {
+    throw new Error(`AGDF_COPILOT_PRECEDENCE_INVALID: ${field}`);
+  }
+  const normalized = values.map((value) => value.trim());
+  if (new Set(normalized).size !== normalized.length) throw new Error(`AGDF_COPILOT_PRECEDENCE_DUPLICATE: ${field}`);
+  return new Set(normalized);
+}
+
+export function diagnoseCopilotSkillPrecedence({ declaredPluginSkills, projectSkills = [], personalSkills = [] } = {}) {
+  const plugin = skillNames(declaredPluginSkills, "declaredPluginSkills");
+  const project = skillNames(projectSkills, "projectSkills");
+  const personal = skillNames(personalSkills, "personalSkills");
+  const skills = [...plugin].sort().map((name) => {
+    const projectMatch = project.has(name);
+    const personalMatch = personal.has(name);
+    return Object.freeze({
+      name,
+      effective_source: projectMatch ? "project" : personalMatch ? "personal" : "plugin",
+      plugin_loaded: !projectMatch && !personalMatch,
+      collisions: Object.freeze([
+        ...(projectMatch ? ["project"] : []),
+        ...(personalMatch ? ["personal"] : []),
+      ]),
+      mutation: "none",
+    });
+  });
+  return Object.freeze({
+    schema_version: 1,
+    precedence: Object.freeze(["project", "personal", "plugin"]),
+    skills: Object.freeze(skills),
+    destructive_override: false,
+  });
+}

package/lib/installers/copilot-settings.js

@@ -0,0 +1,84 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import process from "node:process";
+import { renameSyncWithRetry } from "../fs-swap.js";
+
+export function defaultCopilotSettingsPath({ env = process.env, home = homedir() } = {}) {
+  return join(resolve(env.COPILOT_HOME || join(home, ".copilot")), "settings.json");
+}
+
+export function readCopilotSettings(path = defaultCopilotSettingsPath()) {
+  if (!existsSync(path)) return { exists: false, settings: {} };
+  const stats = lstatSync(path);
+  if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("AGDF_COPILOT_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");
+    if (settings.enabledPlugins !== undefined
+        && (!settings.enabledPlugins || typeof settings.enabledPlugins !== "object" || Array.isArray(settings.enabledPlugins))) {
+      throw new Error("enabledPlugins must be an object");
+    }
+    return { exists: true, settings };
+  } catch (error) {
+    throw new Error(`AGDF_COPILOT_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 configureCopilotDeclarativePlugin({ path = defaultCopilotSettingsPath(), pluginRoot }) {
+  if (typeof pluginRoot !== "string" || !pluginRoot.trim() || !isAbsolute(pluginRoot)) {
+    throw new Error("AGDF_COPILOT_PLUGIN_SPEC_INVALID");
+  }
+  const spec = resolve(pluginRoot);
+  if (!existsSync(spec) || !lstatSync(spec).isDirectory() || lstatSync(spec).isSymbolicLink()) {
+    throw new Error("AGDF_COPILOT_PLUGIN_SPEC_UNAVAILABLE");
+  }
+  const before = readCopilotSettings(path);
+  const next = structuredClone(before.settings);
+  next.enabledPlugins = { ...(next.enabledPlugins ?? {}), [spec]: true };
+  atomicSettingsWrite(path, next);
+  const verified = readCopilotSettings(path);
+  if (verified.settings.enabledPlugins?.[spec] !== true) throw new Error("AGDF_COPILOT_SETTINGS_VERIFICATION_FAILED");
+  return {
+    status: "configured_pending_restart",
+    reason: "host_activation_unverified",
+    path,
+    spec,
+    rollback() {
+      if (before.exists) atomicSettingsWrite(path, before.settings);
+      else rmSync(path, { force: true });
+    },
+  };
+}
+
+export function revokeCopilotDeclarativePlugin({ path = defaultCopilotSettingsPath(), pluginRoot }) {
+  const before = readCopilotSettings(path);
+  if (!before.exists) return { status: "not_configured", path };
+  const spec = resolve(pluginRoot);
+  const next = structuredClone(before.settings);
+  if (next.enabledPlugins && Object.hasOwn(next.enabledPlugins, spec)) {
+    delete next.enabledPlugins[spec];
+    if (Object.keys(next.enabledPlugins).length === 0) delete next.enabledPlugins;
+    atomicSettingsWrite(path, next);
+  }
+  return { status: "removed", path, spec };
+}