create-agdf 0.9.3 → 0.9.6

package/lib/installers/opencode.js

@@ -15,12 +15,28 @@ const testNpmCliPath = process.env.NODE_ENV === "test" ? process.env.AGDF_TEST_N
 const npmCommand = testNpmCliPath ? process.execPath : process.platform === "win32" ? process.execPath : "npm";
 const npmPrefixArgs = testNpmCliPath ? [testNpmCliPath] : process.platform === "win32" ? [join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js")] : [];
 
+export function openCodeNpmInvocation(args) {
+  return { executable: npmCommand, args: [...npmPrefixArgs, ...args] };
+}
+
+function openCodeLifecycleError(phase, message, evidence = {}) {
+  const error = new Error(message);
+  error.name = "LifecycleAdapterError";
+  error.phase = phase;
+  error.evidence = evidence;
+  return error;
+}
+
 export function defaultOpenCodeConfigDir() {
   return process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode");
 }
 
 export function installOpenCodeGlobalPlugin(configDir) {
-  assertGlobalOpenCodeSurfaceWritable(configDir);
+  try {
+    assertGlobalOpenCodeSurfaceWritable(configDir);
+  } catch (error) {
+    throw openCodeLifecycleError("ownership_preflight", error.message, { configDir });
+  }
   const previousPackage = resolveOpenCodePackage(configDir);
   const configPath = join(configDir, "opencode.json");
   let config = {};
@@ -29,12 +45,12 @@ export function installOpenCodeGlobalPlugin(configDir) {
     try {
       config = JSON.parse(readFileSync(configPath, "utf8"));
     } catch {
-      throw new Error(`Refusing to update unreadable OpenCode config: ${configPath}`);
+      throw openCodeLifecycleError("configuration", `Refusing to update unreadable OpenCode config: ${configPath}`, { configPath });
     }
   }
 
   if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
-    throw new Error(`Refusing to update OpenCode config with non-array plugin field: ${configPath}`);
+    throw openCodeLifecycleError("configuration", `Refusing to update OpenCode config with non-array plugin field: ${configPath}`, { configPath });
   }
 
   const plugins = [...(config.plugin ?? [])];
@@ -50,7 +66,7 @@ export function installOpenCodeGlobalPlugin(configDir) {
   };
 
   if (nextConfig.instructions !== undefined && !Array.isArray(nextConfig.instructions)) {
-    throw new Error(`Refusing to update OpenCode config with non-array instructions field: ${configPath}`);
+    throw openCodeLifecycleError("configuration", `Refusing to update OpenCode config with non-array instructions field: ${configPath}`, { configPath });
   }
   nextConfig.instructions = [...(nextConfig.instructions ?? [])];
   if (!nextConfig.instructions.includes("AGDF.md")) nextConfig.instructions.push("AGDF.md");
@@ -71,14 +87,22 @@ export function installOpenCodeGlobalPlugin(configDir) {
   mkdirSync(configDir, { recursive: true });
   try {
     const packageSpecifier = `${pluginDefinition.opencode.npmPackage}@${pluginDefinition.version}`;
-    execFileSync(npmCommand, [...npmPrefixArgs, "install", "--silent", "--save-prod", "--save-exact", packageSpecifier], {
+    const invocation = openCodeNpmInvocation(["install", "--silent", "--save-prod", "--save-exact", packageSpecifier]);
+    execFileSync(invocation.executable, invocation.args, {
       cwd: configDir,
       stdio: "pipe",
     });
   } catch (error) {
-    throw new Error(`Failed to install ${pluginDefinition.opencode.npmPackage} into the OpenCode config directory: ${(error.stderr || error.message).toString().trim()}`);
+    throw openCodeLifecycleError("plugin_operation", `Failed to install ${pluginDefinition.opencode.npmPackage} into the OpenCode config directory: ${(error.stderr || error.message).toString().trim()}`, {
+      executable: npmCommand,
+      args: [...npmPrefixArgs, "install"],
+    });
+  }
+  try {
+    writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+  } catch (error) {
+    throw openCodeLifecycleError("configuration", `Failed to write OpenCode config ${configPath}: ${error.message}`, { configPath });
   }
-  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
   const installedPackage = resolveOpenCodePackage(configDir);
 
   return {

package/lib/installers/plugin-installers.js

@@ -3,48 +3,77 @@ import { pluginDefinition } from "../cli/runtime-context.js";
 
 export function installCodexGlobalPlugin({ exec = execFileSync, io = console } = {}) {
   const expectedVersion = pluginDefinition.version;
-
-  try {
-    exec("codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
-    exec("codex", ["plugin", "marketplace", "upgrade", "agdf"], { stdio: "inherit" });
-    exec("codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], { stdio: "inherit" });
-    const listOutput = exec("codex", ["plugin", "list"], { encoding: "utf8", stdio: "pipe" });
-    const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
-    if (installedVersion !== expectedVersion) {
-      throw new Error(versionMismatchMessage("Codex", "agdf@agdf", expectedVersion, installedVersion, "codex plugin marketplace upgrade agdf && codex plugin add agdf --marketplace agdf"));
-    }
-    io.log(`AGDF Codex plugin version verified: ${installedVersion}.`);
-  } catch (error) {
-    if (error.message?.startsWith("AGDF Codex plugin version mismatch")) throw error;
-    throw new Error(`Failed to install the AGDF Codex plugin. Make sure the Codex CLI is installed and available on PATH, then rerun this command. ${commandErrorText(error)}`.trim());
+  runPluginPhase(exec, "codex", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], "marketplace", { stdio: "inherit" });
+  runPluginPhase(exec, "codex", ["plugin", "marketplace", "upgrade", "agdf"], "marketplace", { stdio: "inherit" });
+  runPluginPhase(exec, "codex", ["plugin", "add", "agdf", "--marketplace", "agdf"], "plugin_operation", { stdio: "inherit" });
+  const listOutput = runPluginPhase(exec, "codex", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
+  const installedVersion = pluginVersionFromList(listOutput, "agdf@agdf");
+  if (installedVersion !== expectedVersion) {
+    throw lifecycleAdapterError("version", versionMismatchMessage("Codex", "agdf@agdf", expectedVersion, installedVersion, "codex plugin marketplace upgrade agdf && codex plugin add agdf --marketplace agdf"));
   }
+  return { surface: "codex", expectedVersion, installedVersion, verificationStatus: "healthy", evidence: ["codex plugin list"] };
 }
 
 export function installClaudeGlobalPlugin({ exec = execFileSync, io = console } = {}) {
   const expectedVersion = pluginDefinition.version;
+  runPluginPhase(exec, "claude", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], "marketplace", { stdio: "inherit" });
+  runPluginPhase(exec, "claude", ["plugin", "marketplace", "update", "agdf"], "marketplace", { stdio: "inherit" });
+  const beforeList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
+  const alreadyInstalled = pluginListHasPlugin(beforeList, "agdf@agdf");
+  runPluginPhase(exec, "claude", ["plugin", alreadyInstalled ? "update" : "install", "agdf@agdf"], "plugin_operation", { stdio: "inherit" });
+  const afterList = runPluginPhase(exec, "claude", ["plugin", "list"], "verification", { encoding: "utf8", stdio: "pipe" });
+  const installedVersion = pluginVersionFromList(afterList, "agdf@agdf");
+  if (installedVersion && installedVersion !== expectedVersion) {
+    throw lifecycleAdapterError("version", versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "claude plugin marketplace update agdf && claude plugin update agdf@agdf"));
+  }
+  return {
+    surface: "claude",
+    expectedVersion,
+    installedVersion,
+    verificationStatus: installedVersion ? "healthy" : "degraded",
+    evidence: ["claude plugin list", ...(installedVersion ? [] : ["host_did_not_expose_version"])],
+  };
+}
+
+export function inspectPluginSurface(surface, exec = execFileSync) {
+  const executable = surface === "claude" ? "claude" : "codex";
+  const pluginId = "agdf@agdf";
+  try {
+    const output = exec(executable, ["plugin", "list"], { encoding: "utf8", stdio: "pipe" });
+    const installed = pluginListHasPlugin(output, pluginId);
+    const version = installed ? pluginVersionFromList(output, pluginId) : "";
+    return {
+      status: !installed ? "not_installed" : version === pluginDefinition.version ? "healthy" : "degraded",
+      surface,
+      version: version || null,
+      expected_version: pluginDefinition.version,
+      evidence: [`${executable} plugin list`, ...(installed && !version ? ["host_did_not_expose_version"] : [])],
+    };
+  } catch (error) {
+    return { status: "unknown", surface, version: null, expected_version: pluginDefinition.version, evidence: [commandErrorText(error)] };
+  }
+}
 
+function runPluginPhase(exec, executable, args, phase, options) {
   try {
-    exec("claude", ["plugin", "marketplace", "add", "arndtgold/ai-native-governance-delivery-framework"], { stdio: "inherit" });
-    exec("claude", ["plugin", "marketplace", "update", "agdf"], { stdio: "inherit" });
-    const beforeList = exec("claude", ["plugin", "list"], { encoding: "utf8", stdio: "pipe" });
-    const alreadyInstalled = pluginListHasPlugin(beforeList, "agdf@agdf");
-    exec("claude", ["plugin", alreadyInstalled ? "update" : "install", "agdf@agdf"], { stdio: "inherit" });
-    const afterList = exec("claude", ["plugin", "list"], { encoding: "utf8", stdio: "pipe" });
-    const installedVersion = pluginVersionFromList(afterList, "agdf@agdf");
-    if (installedVersion) {
-      if (installedVersion !== expectedVersion) {
-        throw new Error(versionMismatchMessage("Claude Code", "agdf@agdf", expectedVersion, installedVersion, "claude plugin marketplace update agdf && claude plugin update agdf@agdf"));
-      }
-      io.log(`AGDF Claude Code plugin version verified: ${installedVersion}.`);
-    } else {
-      io.log("AGDF Claude Code plugin installed or updated. Claude Code did not expose a plugin version in `claude plugin list`; verify with `claude plugin list` after restart if needed.");
-    }
+    return exec(executable, args, options);
   } catch (error) {
-    if (error.message?.startsWith("AGDF Claude Code plugin version mismatch")) throw error;
-    throw new Error(`Failed to install the AGDF Claude Code plugin. Make sure the Claude Code CLI is installed and available on PATH, then rerun this command. ${commandErrorText(error)}`.trim());
+    const effectivePhase = error?.code === "ENOENT" ? "executable" : phase;
+    throw lifecycleAdapterError(effectivePhase, commandErrorText(error) || `${executable} ${args.join(" ")} failed`, {
+      executable,
+      args,
+    });
   }
 }
 
+function lifecycleAdapterError(phase, message, evidence = {}) {
+  const error = new Error(message);
+  error.name = "LifecycleAdapterError";
+  error.phase = phase;
+  error.evidence = evidence;
+  return error;
+}
+
 function commandErrorText(error) {
   return (error.stderr || error.stdout || error.message || "").toString().trim();
 }

package/lib/lifecycle/operations.js

@@ -0,0 +1,177 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pluginDefinition } from "../cli/runtime-context.js";
+import { evaluateOpenCodeStatus, openCodeNpmInvocation } from "../installers/opencode.js";
+import { inspectPluginSurface } from "../installers/plugin-installers.js";
+
+const CODEX_DISABLE_MARKER = "# AGDF-OWNED-REPOSITORY-PLUGIN-STATE";
+
+function pluginSection(content, selector) {
+  const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return content.match(new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`))?.[0] ?? "";
+}
+
+function repositorySelector(targetDir) {
+  return existsSync(join(targetDir, ".agents", "plugins", "marketplace.json")) ? "agdf@agdf-repo" : "agdf@agdf";
+}
+
+export function planRepositoryDisable(targetDir, surface) {
+  if (surface !== "codex") {
+    throw new Error(`Repository disable is not supported safely for ${surface}; no files were changed.`);
+  }
+  const path = join(targetDir, ".codex", "config.toml");
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const selector = repositorySelector(targetDir);
+  const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const sectionPattern = new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`);
+  const currentSection = pluginSection(existing, selector);
+  const enabledMatches = [...currentSection.matchAll(/^enabled\s*=\s*(true|false)\s*$/gm)];
+  if (currentSection && enabledMatches.length !== 1) {
+    throw new Error(`Refusing to modify ambiguous AGDF plugin state in ${path}.`);
+  }
+  const section = currentSection
+    ? currentSection.replace(/^enabled\s*=\s*(true|false)\s*$/m, "enabled = false")
+    : `${CODEX_DISABLE_MARKER}\n[plugins.${JSON.stringify(selector)}]\nenabled = false`;
+  const content = currentSection
+    ? existing.replace(sectionPattern, section).replace(/\s*$/, "\n")
+    : `${existing.replace(/\s*$/, "")}${existing.trim() ? "\n\n" : ""}${section}\n`;
+  return Object.freeze({
+    operation: "disable",
+    surface,
+    scope: "repository",
+    mutations: Object.freeze([{ kind: "write", path, content, ownership: currentSection ? "exact_plugin_section" : "agdf_marker" }]),
+    retained: Object.freeze([join(targetDir, ".agdf", "control"), "global AGDF plugin availability"]),
+    expected: Object.freeze({ repository_status: "disabled" }),
+  });
+}
+
+export function verifyRepositoryDisabled(targetDir) {
+  const path = join(targetDir, ".codex", "config.toml");
+  if (!existsSync(path)) return { status: "failed", evidence: [`missing:${path}`] };
+  const selector = repositorySelector(targetDir);
+  const section = pluginSection(readFileSync(path, "utf8"), selector);
+  const matches = [...section.matchAll(/^enabled\s*=\s*(true|false)\s*$/gm)];
+  return matches.length === 1 && matches[0][1] === "false"
+    ? { status: "healthy", evidence: [`${path}:${selector}:enabled=false`] }
+    : { status: "failed", evidence: [`postcondition_failed:${path}:${selector}`] };
+}
+
+export function verifyGlobalUninstall(plan, targetDir, { configDir, exec, inspect = inspectPluginSurface, evaluateOpenCode = evaluateOpenCodeStatus } = {}) {
+  if (plan.surface === "opencode") {
+    const report = evaluateOpenCode(targetDir, configDir);
+    const remainingOwnedFiles = plan.mutations
+      .filter((mutation) => mutation.kind === "remove")
+      .map((mutation) => mutation.path)
+      .filter((path) => existsSync(path));
+    return report.status === "not_configured" && remainingOwnedFiles.length === 0
+      ? { status: "healthy", evidence: [report.global_config.path, "marker_owned_global_files_removed"] }
+      : { status: "failed", evidence: [report.global_config.path, ...remainingOwnedFiles.map((path) => `still_present:${path}`)] };
+  }
+  const report = inspect(plan.surface, exec);
+  return report.status === "not_installed"
+    ? { status: "healthy", evidence: report.evidence }
+    : { status: "failed", evidence: [...report.evidence, `observed:${report.status}`] };
+}
+
+export function planGlobalUninstall(surface, { configDir } = {}) {
+  if (surface === "codex") {
+    return nativeUninstallPlan(surface, "codex", ["plugin", "remove", "agdf@agdf"]);
+  }
+  if (surface === "claude") {
+    return nativeUninstallPlan(surface, "claude", ["plugin", "uninstall", "agdf@agdf", "--scope", "user"]);
+  }
+  if (surface === "opencode") {
+    if (!configDir) throw new Error("OpenCode uninstall requires its explicit config directory.");
+    const configPath = join(configDir, "opencode.json");
+    if (!existsSync(configPath)) throw new Error(`OpenCode config not found: ${configPath}`);
+    let config;
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      throw new Error(`Refusing to modify unreadable OpenCode config: ${configPath}`);
+    }
+    if (config.plugin !== undefined && !Array.isArray(config.plugin)) {
+      throw new Error(`Refusing to modify OpenCode config with non-array plugin field: ${configPath}`);
+    }
+    const next = { ...config };
+    next.plugin = (config.plugin ?? []).filter((entry) => entry !== pluginDefinition.opencode.npmPackage);
+    if (Array.isArray(config.instructions)) next.instructions = config.instructions.filter((entry) => entry !== "AGDF.md");
+    const npm = openCodeNpmInvocation(["uninstall", "--silent", pluginDefinition.opencode.npmPackage]);
+    const mutations = [
+      { kind: "write", path: configPath, content: `${JSON.stringify(next, null, 2)}\n`, ownership: "exact_known_entries" },
+      { kind: "command", executable: npm.executable, args: npm.args, cwd: configDir },
+    ];
+    const retained = ["repository AGDF files", ".agdf/control"];
+    for (const candidate of openCodeOwnedGlobalFiles(configDir)) {
+      if (!existsSync(candidate.path)) continue;
+      const content = readFileSync(candidate.path, "utf8");
+      if (candidate.owned(content)) mutations.push({ kind: "remove", path: candidate.path, ownership: "agdf_marker" });
+      else retained.push(candidate.path);
+    }
+    return Object.freeze({
+      operation: "uninstall",
+      surface,
+      scope: "global",
+      mutations: Object.freeze(mutations),
+      retained: Object.freeze(retained),
+      expected: Object.freeze({ installation_status: "not_installed" }),
+    });
+  }
+  throw new Error(`Global uninstall is not supported for ${surface}.`);
+}
+
+function openCodeOwnedGlobalFiles(configDir) {
+  const firstLine = (marker) => (content) => content.split(/\r?\n/)[0] === marker;
+  const afterFrontmatter = (marker) => (content) => {
+    const lines = content.split(/\r?\n/);
+    const end = lines.findIndex((line, index) => index > 0 && line === "---");
+    return end >= 0 && lines[end + 1] === marker;
+  };
+  const files = [
+    { path: join(configDir, pluginDefinition.opencode.instructionsFileName), owned: firstLine("<!-- AGDF-GLOBAL-INSTRUCTIONS -->") },
+    { path: join(configDir, pluginDefinition.opencode.runtimeContractFileName), owned: firstLine("<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->") },
+  ];
+  for (const moduleName of ["gate-transition.md", "interaction.md", "modes.md", "quality.md", "context-graph.md", "control-scaffold.md", "closeout.md"]) {
+    files.push({ path: join(configDir, "contracts", moduleName), owned: firstLine("<!-- AGDF-GLOBAL-RUNTIME-CONTRACT -->") });
+  }
+  for (const skill of pluginDefinition.skillSet) {
+    const name = `${pluginDefinition.opencode.globalSkillPrefix}${skill.slug}`;
+    const marker = `<!-- AGDF-GLOBAL-SKILL: ${name} -->`;
+    files.push({ path: join(configDir, "skills", name, "SKILL.md"), owned: afterFrontmatter(marker) });
+  }
+  return files;
+}
+
+function nativeUninstallPlan(surface, executable, args) {
+  return Object.freeze({
+    operation: "uninstall",
+    surface,
+    scope: "global",
+    mutations: Object.freeze([{ kind: "command", executable, args: Object.freeze(args) }]),
+    retained: Object.freeze(["repository AGDF files", ".agdf/control", "ambiguous configuration"]),
+    expected: Object.freeze({ installation_status: "not_installed" }),
+  });
+}
+
+export function applyLifecyclePlan(plan, { exec = execFileSync } = {}) {
+  const completed = [];
+  for (const mutation of plan.mutations) {
+    try {
+      if (mutation.kind === "write") {
+        mkdirSync(dirname(mutation.path), { recursive: true });
+        writeFileSync(mutation.path, mutation.content, "utf8");
+        completed.push({ kind: "write", path: mutation.path });
+      } else if (mutation.kind === "remove") {
+        rmSync(mutation.path);
+        completed.push({ kind: "remove", path: mutation.path });
+      } else if (mutation.kind === "command") {
+        exec(mutation.executable, mutation.args, { cwd: mutation.cwd, stdio: "inherit" });
+        completed.push({ kind: "command", executable: mutation.executable, args: mutation.args });
+      }
+    } catch (error) {
+      return { status: completed.length ? "partial" : "failed", completed, error, retained: [...plan.retained] };
+    }
+  }
+  return { status: "success", completed, error: null, retained: [...plan.retained] };
+}

package/lib/lifecycle/presentation.js

@@ -0,0 +1,52 @@
+import { interactionLocales } from "../cli/runtime-context.js";
+
+function copy(locale) {
+  const language = String(locale ?? "").toLowerCase().split("-")[0];
+  return (interactionLocales.locales[language] ?? interactionLocales.locales[interactionLocales.fallbackLocale]).primary.lifecycleResult;
+}
+
+export function lifecycleCardLines(report, locale = "en") {
+  const c = copy(locale);
+  const version = report.version.transition === "updated" && report.version.previous && report.version.installed
+    ? `${report.version.previous} -> ${report.version.installed}`
+    : report.version.installed || (report.version.expected ? `${c.unknown}; expected ${report.version.expected}` : c.unknown);
+  const versionStatus = report.version.transition && report.version.transition !== "updated"
+    ? `${report.version.status}; transition ${report.version.transition}`
+    : report.version.status;
+  return [
+    c.title,
+    `${c.result}: ${report.result}`,
+    `${c.surface}: ${report.surface}`,
+    `${c.scope}: ${report.scope}`,
+    `${c.version}: ${version} (${versionStatus})`,
+    `${c.verification}: ${report.verification.status}`,
+    `${c.restart}: ${report.restart.required ? c.yes : c.no}${report.restart.reason !== "none" ? ` (${report.restart.reason})` : ""}`,
+    `${c.next}: ${report.next_action.text}`,
+  ];
+}
+
+export function printLifecycleResult(report, { json = false, locale = "en", io = console } = {}) {
+  if (json) {
+    io.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  for (const line of lifecycleCardLines(report, locale)) io.log(line);
+  if (report.failure) io.log(`Failure phase: ${report.failure.phase}: ${report.failure.message}`);
+  if (report.retained.length) {
+    io.log("Retained:");
+    for (const item of report.retained) io.log(`- ${typeof item === "string" ? item : JSON.stringify(item)}`);
+  }
+}
+
+export function printGeneralStatus(report, { json = false, locale = "en", io = console } = {}) {
+  if (json) {
+    io.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  const c = copy(locale);
+  io.log(c.statusTitle);
+  io.log(`${c.installation}: ${report.installation.status}${report.installation.version ? ` (${report.installation.version})` : ""}`);
+  io.log(`${c.repository}: ${report.repository.status}`);
+  io.log(`${c.delivery}: ${report.delivery.status}${report.delivery.current_gate ? ` (${report.delivery.current_gate})` : ""}`);
+  io.log(`${c.next}: ${report.next_action.text}`);
+}

package/lib/lifecycle/result.js

@@ -0,0 +1,69 @@
+const OPERATIONS = new Set(["install", "update", "status", "disable", "uninstall", "repository_setup"]);
+const RESULTS = new Set(["success", "partial", "failed", "preview"]);
+const SCOPES = new Set(["global", "repository"]);
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function createLifecycleResult(input = {}) {
+  const result = {
+    schema_version: 1,
+    operation: text(input.operation),
+    result: text(input.result),
+    surface: text(input.surface),
+    scope: text(input.scope),
+    version: {
+      expected: text(input.version?.expected) || null,
+      installed: text(input.version?.installed) || null,
+      previous: text(input.version?.previous) || null,
+      status: text(input.version?.status) || "unknown",
+      transition: text(input.version?.transition) || null,
+    },
+    verification: {
+      status: text(input.verification?.status) || "unknown",
+      evidence: [...(input.verification?.evidence ?? [])].map(String),
+    },
+    restart: {
+      required: Boolean(input.restart?.required),
+      reason: text(input.restart?.reason) || "none",
+    },
+    next_action: {
+      kind: text(input.next_action?.kind) || "none",
+      text: text(input.next_action?.text) || "No further action required.",
+    },
+    changes: [...(input.changes ?? [])],
+    retained: [...(input.retained ?? [])],
+    failure: input.failure ?? null,
+  };
+  assertLifecycleResult(result);
+  return Object.freeze(result);
+}
+
+export function assertLifecycleResult(value) {
+  if (value?.schema_version !== 1) throw new Error("Lifecycle result requires schema_version 1.");
+  if (!OPERATIONS.has(value.operation)) throw new Error(`Unsupported lifecycle operation: ${value.operation || "missing"}.`);
+  if (!RESULTS.has(value.result)) throw new Error(`Unsupported lifecycle result: ${value.result || "missing"}.`);
+  if (!value.surface) throw new Error("Lifecycle result requires a surface.");
+  if (!SCOPES.has(value.scope)) throw new Error(`Unsupported lifecycle scope: ${value.scope || "missing"}.`);
+  if (!value.next_action || Array.isArray(value.next_action) || !text(value.next_action.text)) {
+    throw new Error("Lifecycle result requires exactly one next action.");
+  }
+  if (value.version.status === "verified" && !value.version.installed) {
+    throw new Error("A verified lifecycle version requires an observed installed version.");
+  }
+  if (value.result === "failed" && !value.failure) throw new Error("Failed lifecycle results require failure evidence.");
+  return value;
+}
+
+export function lifecycleFailure({ operation, surface, scope, phase, message, evidence = [], nextAction }) {
+  return createLifecycleResult({
+    operation,
+    result: "failed",
+    surface,
+    scope,
+    verification: { status: "degraded", evidence },
+    next_action: { kind: "recovery", text: nextAction },
+    failure: { phase, message },
+  });
+}

package/lib/lifecycle/status.js

@@ -0,0 +1,108 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pluginDefinition } from "../cli/runtime-context.js";
+import { evaluateDoctor } from "../control-evaluation/doctor.js";
+import { evaluateGateCheck } from "../control-evaluation/gate-check.js";
+import { evaluateOpenCodeStatus } from "../installers/opencode.js";
+import { inspectPluginSurface } from "../installers/plugin-installers.js";
+
+function deliveryStatus(targetDir, selection, dependencies) {
+  const controlDir = join(targetDir, ".agdf", "control");
+  const hasLiveControl = existsSync(join(controlDir, "runs"))
+    || (existsSync(join(controlDir, "AGDF_RUN.md")) && existsSync(join(controlDir, "MASTER_BACKLOG.md")));
+  if (!hasLiveControl) {
+    return { status: "not_configured", run_id: null, current_gate: null, evidence: [] };
+  }
+  try {
+    const doctor = dependencies.evaluateDoctor(targetDir, selection);
+    const gate = dependencies.evaluateGateCheck(targetDir, selection);
+    return {
+      status: gate.status === "blocked" || doctor.status === "block" ? "blocked" : gate.status === "complete" ? "complete" : "open",
+      run_id: selection.runId || null,
+      current_gate: gate.current_gate || null,
+      evidence: [`doctor:${doctor.status}`, `gate-check:${gate.status}`],
+    };
+  } catch (error) {
+    return { status: "unknown", run_id: selection.runId || null, current_gate: null, evidence: [error.message] };
+  }
+}
+
+function repositoryStatus(targetDir, surface) {
+  if (surface === "codex") {
+    const marketplace = join(targetDir, ".agents", "plugins", "marketplace.json");
+    const disabled = join(targetDir, ".codex", "config.toml");
+    const config = existsSync(disabled) ? readFileSync(disabled, "utf8") : "";
+    const isDisabled = ["agdf@agdf-repo", "agdf@agdf"].some((selector) => {
+      const escaped = JSON.stringify(selector).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const section = config.match(new RegExp(`\\[plugins\\.${escaped}\\][\\s\\S]*?(?=\\n\\[|$)`))?.[0] ?? "";
+      return /^enabled\s*=\s*false\s*$/m.test(section);
+    });
+    return { status: isDisabled ? "disabled" : existsSync(marketplace) ? "active" : "not_configured", scope: "repository", evidence: [marketplace] };
+  }
+  if (surface === "opencode") {
+    const instructions = join(targetDir, ".opencode", pluginDefinition.opencode.instructionsFileName);
+    return { status: existsSync(instructions) ? "active" : "not_configured", scope: "repository", evidence: [instructions] };
+  }
+  return { status: "unknown", scope: "repository", evidence: [] };
+}
+
+function inspectInstallation(surface, targetDir, options, deps, exec) {
+  if (surface === "opencode") {
+    const report = deps.evaluateOpenCodeStatus(targetDir, options.configDir);
+    return {
+      status: report.status === "configured" && report.package.version_status === "current" ? "healthy" : report.status === "configured" ? "degraded" : "not_installed",
+      surface,
+      version: report.package.installed_version,
+      evidence: [report.global_config.path],
+    };
+  }
+  if (["codex", "claude"].includes(surface)) return deps.inspectPluginSurface(surface, exec);
+  return { status: "unknown", surface, version: null, evidence: [`unsupported_status_probe:${surface}`] };
+}
+
+export function evaluateGeneralStatus(targetDir, options = {}, dependencies = {}) {
+  const deps = {
+    evaluateDoctor: dependencies.evaluateDoctor ?? evaluateDoctor,
+    evaluateGateCheck: dependencies.evaluateGateCheck ?? evaluateGateCheck,
+    evaluateOpenCodeStatus: dependencies.evaluateOpenCodeStatus ?? evaluateOpenCodeStatus,
+    inspectPluginSurface: dependencies.inspectPluginSurface ?? inspectPluginSurface,
+  };
+  let surface = options.surface && options.surface !== "generic" ? options.surface : null;
+  let installation;
+  if (surface) {
+    installation = inspectInstallation(surface, targetDir, options, deps, dependencies.exec);
+  } else {
+    const probes = ["codex", "claude", "opencode"].map((candidate) => inspectInstallation(candidate, targetDir, options, deps, dependencies.exec));
+    const observed = probes.filter((probe) => ["healthy", "degraded"].includes(probe.status));
+    if (observed.length === 1) {
+      installation = observed[0];
+      surface = installation.surface;
+    } else {
+      surface = observed.length > 1 ? "multiple" : "generic";
+      installation = {
+        status: "unknown",
+        surface,
+        version: null,
+        evidence: probes.flatMap((probe) => probe.evidence.map((item) => `${probe.surface}:${item}`)),
+      };
+    }
+  }
+  const repository = repositoryStatus(targetDir, surface);
+  const delivery = deliveryStatus(targetDir, { runId: options.runId }, deps);
+  const nextText = surface === "multiple"
+    ? "Multiple AGDF host surfaces were detected; rerun status with an explicit --surface."
+    : surface === "generic"
+    ? "No installed AGDF host surface could be selected safely; rerun status with an explicit --surface."
+    : installation.status !== "healthy"
+    ? `Run npx --yes @agdf/cli@latest ${surface} to install or repair AGDF.`
+    : repository.status === "disabled"
+    ? "Restart the host to apply the repository-local disable; the healthy global AGDF installation remains available."
+    : repository.status === "not_configured"
+    ? `Run npx --yes @agdf/cli@latest ${surface === "codex" ? "codex-repo" : `${surface}-repo`} in this repository.`
+    : delivery.status === "blocked"
+    ? "Resolve the reported delivery blocker without changing the healthy installation."
+    : delivery.status === "not_configured"
+    ? "Start a new task; status created no run and requires no approval. Initialize durable control only when the repository needs it."
+    : "Continue with the reported delivery next step.";
+  return { schema_version: 1, installation, repository, delivery, next_action: { kind: "action", text: nextText } };
+}

package/lib/scaffold/presentation.js

@@ -1,5 +1,8 @@
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pluginDefinition } from "../cli/runtime-context.js";
+import { printLifecycleResult } from "../lifecycle/presentation.js";
+import { createLifecycleResult } from "../lifecycle/result.js";
 import { agdfFragmentPath, openCodeConfigFragmentPath } from "./plan.js";
 
 const pluginInstallCommand = "npx --yes @agdf/cli@latest claude";
@@ -27,6 +30,27 @@ export function printNextSteps(target, destination, files, wroteAgentsFragment,
     for (const preserved of preservedFiles) io.log(`- ${preserved}`);
   }
 
+  if (target === "codex-repo") {
+    const verified = files.every((file) => {
+      const path = join(destination, file.path);
+      return existsSync(path) && readFileSync(path, "utf8") === file.content;
+    });
+    printLifecycleResult(createLifecycleResult({
+      operation: "repository_setup",
+      result: verified ? "success" : "partial",
+      surface: "codex",
+      scope: "repository",
+      version: { expected: pluginDefinition.version, status: "expected" },
+      verification: { status: verified ? "healthy" : "degraded", evidence: files.map((file) => file.path) },
+      restart: { required: true, reason: "host_reload_and_repository_plugin_activation" },
+      next_action: {
+        kind: "host_action",
+        text: "Restart Codex, open /plugins, select This repository and install agdf; then start a new task with: Run an AGDF gate check for this request.",
+      },
+    }), { locale: JSON.parse(files.find((file) => file.path === join(".agdf", "control", "config.json"))?.content ?? "{}").chat_language, io });
+    return;
+  }
+
   io.log("");
   io.log("Next steps:");
   const languageConfig = files.find((file) => file.path === join(".agdf", "control", "config.json"));
@@ -48,7 +72,7 @@ export function printNextSteps(target, destination, files, wroteAgentsFragment,
   if (wroteAgentsFragment) {
     io.log(`- Existing AGENTS.md detected. Merge ${agdfFragmentPath} into your current AGENTS.md before using Copilot with AGDF.`);
   }
-  if (target === "codex-repo" || target === "both") {
+  if (target === "both") {
     io.log("- Restart Codex in this repository, open /plugins, select This repository and install agdf.");
     io.log("- Start a new Codex thread in this repository and ask: Run an AGDF gate check for this request.");
   }