create-agdf 0.20.2 → 0.31.0

package/lib/host-adapters/codex/plugin.js

@@ -1,13 +1,14 @@
 import process from "node:process";
 import { inspectPluginList } from "../../installers/plugin-command.js";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from 'node:os';
 import { join } from "node:path";
 import { inspectGeneratedRepositoryMarketplace } from "#agdf-core/runtime/plugin-provenance.js";
 import { execHostFileSync } from "../../host-command.js";
 import { pluginDefinition } from "../../cli/runtime-context.js";
 import { historicalEvidenceEntries, rollbackMarketplaceFilesystem, captureOptions, runPluginPhase, lifecycleAdapterError, pluginVersionFromList, versionMismatchMessage, recoveryAttempt } from "../../installers/plugin-command.js";
 import { CODEX_REGISTRATION_REVISION, isCodexLocalInstallVersion } from "./identity.js";
-import { classifyMarketplaceList, inspectLocalMarketplaceProjection, prepareLocalMarketplace, inspectCodexOwnedManifestRepair } from "../../installers/local-marketplace.js";
+import { classifyMarketplaceList, inspectLocalMarketplaceProjection, prepareLocalMarketplace, inspectCodexOwnedManifestRepair, inspectPlanningMarketplace } from "../../installers/local-marketplace.js";
 import { migrateLegacyCodexMcpRegistration, prepareCodexPluginMcp } from "./plugin-mcp.js";
 import { ownedFileSnapshot } from "../../lifecycle/owned-mutation.js";
 import { inspectCodexCockpitAdmission, inspectCodexSetup } from '../../mcp-lifecycle/adapters/codex.js';
@@ -24,7 +25,10 @@ export function installCodexGlobalPlugin({
   migrateMcp = migrateLegacyCodexMcpRegistration,
   prepareMcp = prepareCodexPluginMcp,
   target,
+  packageSelection = 'core',
 } = {}) {
+  if (packageSelection === 'planning') return installCodexPlanningPlugin({ exec, prepare, dataRoot, env });
+  if (packageSelection !== 'core') throw Error('AGDF_PACKAGE_SELECTION_INVALID');
   const expectedVersion = pluginDefinition.version;
   const nativeOutput = [];
   if (target) target = realpathSync(target);
@@ -104,6 +108,49 @@ export function installCodexGlobalPlugin({
   }
 }
 
+function installCodexPlanningPlugin({ exec, prepare, dataRoot, env }) {
+  const list = runPluginPhase(exec, 'codex', ['plugin', 'list'], 'verification', { ...captureOptions(), maxBuffer: CODEX_PLUGIN_LIST_MAX_BUFFER });
+  const coreSelector = ['agdf@agdf-repo', 'agdf@agdf'].find(selector => pluginVersionFromList(list, selector));
+  const coreVersion = coreSelector && pluginVersionFromList(list, coreSelector);
+  if (!coreVersion || !/^[0-9A-Za-z.+-]+$/u.test(coreVersion)) throw Error('AGDF_PLANNING_CORE_REQUIRED');
+  const marketplace = coreSelector.split('@')[1];
+  const coreRoot = join(env.CODEX_HOME || join(homedir(), '.codex'), 'plugins/cache', marketplace, 'agdf', coreVersion);
+  let capability;
+  try { capability = JSON.parse(readFileSync(join(coreRoot, 'meta/agdf-plugin.definition.json'), 'utf8')).planning; } catch {}
+  if (capability?.schema !== 'planned-ur-v1' || capability.protocol_version !== 1 || capability.authoring_owner !== 'ur-definition') throw Error('AGDF_PLANNING_COMPATIBLE_CORE_REQUIRED');
+  const transaction = prepare({ packageSelection: 'planning', expectedVersion: pluginDefinition.version, ...(dataRoot ? { dataRoot } : {}) });
+  const output = runPluginPhase(exec, 'codex', ['plugin', 'marketplace', 'list', '--json'], 'marketplace', captureOptions());
+  const entries = JSON.parse(output)?.marketplaces;
+  if (!Array.isArray(entries)) throw Error('AGDF_PLANNING_MARKETPLACE_UNKNOWN');
+  const matches = entries.filter(entry => entry?.name === 'agdf-planning');
+  if (matches.length > 1) throw Error('AGDF_PLANNING_MARKETPLACE_UNKNOWN');
+  const previous = matches[0], previousRoot = previous?.marketplaceSource?.source ?? previous?.source?.source ?? previous?.marketplaceSource?.path ?? previous?.source?.path ?? previous?.path;
+  if (previous) {
+    if (typeof previousRoot !== 'string') throw Error('AGDF_PLANNING_MARKETPLACE_UNKNOWN');
+    inspectPlanningMarketplace(previousRoot); // Foreign catalogs are never replaced.
+  }
+  let added = false, removed = false;
+  try {
+    if (previousRoot !== transaction.root) {
+      if (previousRoot) { runPluginPhase(exec, 'codex', ['plugin', 'marketplace', 'remove', 'agdf-planning', '--json'], 'marketplace', captureOptions()); removed = true; }
+      runPluginPhase(exec, 'codex', ['plugin', 'marketplace', 'add', transaction.root, '--json'], 'marketplace', captureOptions()); added = true;
+    }
+    runPluginPhase(exec, 'codex', ['plugin', 'add', 'agdf-planning@agdf-planning', '--json'], 'plugin_operation', captureOptions());
+    const observed = runPluginPhase(exec, 'codex', ['plugin', 'list'], 'verification', { ...captureOptions(), maxBuffer: CODEX_PLUGIN_LIST_MAX_BUFFER });
+    const installedVersion = pluginVersionFromList(observed, 'agdf-planning@agdf-planning');
+    if (installedVersion !== transaction.codexInstallVersion) throw Error('AGDF_PLANNING_VERSION_UNCONFIRMED');
+    return { surface: 'codex', operation: 'install', expectedVersion: transaction.codexInstallVersion, installedVersion,
+      verificationStatus: 'configured_pending_restart', pluginRoot: transaction.pluginRoot, digest: transaction.digest, sourceDigest: transaction.sourceDigest,
+      runtimeDigest: null, evidence: ['optional_planning_only', 'compatible_core_metadata', 'codex plugin list', 'fresh_session_capability_check_required'], nativeOutput: [] };
+  } catch (error) {
+    const evidence = [], recovery = recoveryAttempt(exec, 'codex', evidence);
+    if (added) recovery(['plugin', 'marketplace', 'remove', 'agdf-planning', '--json']);
+    if (removed) recovery(['plugin', 'marketplace', 'add', previousRoot, '--json']);
+    error.recovery = evidence;
+    throw error;
+  }
+}
+
 function migrateMarketplace({ exec, output, root, nativeOutput, migration, refreshOwnedLocal = false }) {
   const classification = classifyMarketplaceList("codex", output, root);
   Object.assign(migration, classification);

package/lib/install-setup/contract.js

@@ -2,7 +2,7 @@ import { INSTALL_SETUP_STATES, INSTALL_ACTIONS, INSTALL_FAILURE_PHASES, INSTALL_
 import { isAbsolute } from "node:path";
 import { assertLifecycleResult } from "../lifecycle/result.js";
 import { mcpCapabilityProfileContract } from "../mcp-lifecycle/profile.js";
-import { assertControlMigration, uncheckedControl } from "./control-migration.js";
+import { assertControlCompatibility, uncheckedControl } from "./control-compatibility.js";
 
 const SURFACES = new Set(mcpCapabilityProfileContract.surfaces);
 const SETUP_REQUESTS = new Set(["plugin_only", "full", "cancel"]);
@@ -130,7 +130,7 @@ export function deriveInstallSetupState({ setup_request: setupRequest, surface,
   if (!pluginVerified(plugin)) return "failed";
   if (failure?.phase === "runtime_check_permission") return "partial";
   if (!failure && control?.status === "repair_required") return "control_repair_required";
-  if (!failure && control?.status === "migration_required") return "control_migration_required";
+  if (!failure && control?.status === "unsupported") return "control_unsupported";
   const state = mcpState(mcp);
   if (setupRequest === "plugin_only") {
     if (state === "plugin_managed" && !failure && codexHookReviewPending(surface, runtimeChecks)) {
@@ -165,7 +165,7 @@ export function createInstallSetupPreflight(input = {}) {
   const pluginConfiguration = input.plugin_configuration ?? null;
   const invocationDirectorySource = input.invocation_directory_source ?? "none";
   const fullBlockReason = input.full_block_reason ?? "none";
-  const control = assertControlMigration(input.control ?? uncheckedControl());
+  const control = assertControlCompatibility(input.control ?? uncheckedControl());
   const scopeStateValid = (state) => plainObject(state)
     && Object.keys(state).every((key) => [
       "status", "capability", "selected_status", "effective_source", "registration_path",
@@ -236,7 +236,7 @@ export function createInstallSetupResult(input = {}) {
   const requestedScope = input.requested_scope ?? null;
   const effectiveScope = input.effective_scope ?? null;
   const invocationDirectorySource = input.invocation_directory_source ?? "none";
-  const control = assertControlMigration(input.control ?? uncheckedControl());
+  const control = assertControlCompatibility(input.control ?? uncheckedControl());
   if (!SETUP_REQUESTS.has(input.setup_request) || !SURFACES.has(input.surface)
       || !(target === null || (typeof target === "string" && isAbsolute(target)))
       || !TARGET_SOURCES.has(input.target_source)

package/lib/install-setup/{control-migration.js → control-compatibility.js}

@@ -1,5 +1,4 @@
-export { CONTROL_MIGRATION_STATUSES, uncheckedControl, inspectControlMigration, assertControlMigration } from "#agdf-core/control-maintenance/compatibility.js";
-export { migrateInstallationControl } from "#agdf-core/control-maintenance/migration.js";
+export { CONTROL_COMPATIBILITY_STATUSES, uncheckedControl, inspectControlCompatibility, assertControlCompatibility } from "#agdf-core/control-maintenance/compatibility.js";
 
 export function installationControlTarget(options) {
   if (options.controlDir) return { root: options.controlDir, writable: true };

package/lib/install-setup/interaction.js

@@ -1,4 +1,3 @@
-export { selectControlMigration, promptControlMigration, selectControlRepair, promptControlRepair } from "../control-maintenance/interaction.js";
 import { createInterface } from "node:readline/promises";
 import process from "node:process";
 import { interactionLocales } from "../cli/runtime-context.js";

package/lib/install-setup/presentation.js

@@ -1,5 +1,4 @@
-export { renderControlMigration, renderControlMigrationDecision, renderControlRepairOffer, renderControlRepairPlan } from "#agdf-core/control-maintenance/presentation.js";
-import { renderControlMigration } from "#agdf-core/control-maintenance/presentation.js";
+import { renderControlCompatibility } from "#agdf-core/control-maintenance/presentation.js";
 import { interactionLocales } from "../cli/runtime-context.js";
 import { localePack } from "#agdf-core/interaction-presentation.js";
 
@@ -235,7 +234,7 @@ export function renderInstallSetupPreflight(preflight, { registry = interactionL
     `${labels.packageAcquisition}: ${preflight.package_acquisition_required ? value.required : value.not_required}`,
     `${labels.removal}: ${preflight.removal_overview}`,
     `${labels.authorizes}: ${preflight.authorizes}`,
-    renderControlMigration(preflight.control, { registry, language }),
+    renderControlCompatibility(preflight.control, { registry, language }),
     "",
   ];
   for (const option of options) {
@@ -326,7 +325,7 @@ export function renderInstallSetupText(report, { registry = interactionLocales,
     `${labels.failure}: ${failure}`,
     `${labels.authorizes}: ${report.authorizes}`,
     `${labels.nextAction}: ${projected.next_action.text}`,
-    renderControlMigration(report.control, { registry, language, details: verbose }),
+    renderControlCompatibility(report.control, { registry, language, details: verbose }),
   ].join("\n");
 }
 

package/lib/install-setup/service.js

@@ -4,8 +4,7 @@ import { inspectGlobalInstallationStatus } from "../lifecycle/status.js";
 import { runMcpLifecycle } from "../mcp-lifecycle/service.js";
 import { pluginDefinition } from "../cli/runtime-context.js";
 import { codexHookReviewPending, codexPendingHookAction, createInstallSetupPreflight, createInstallSetupResult } from "./contract.js";
-import { inspectControlMigration, installationControlTarget, migrateInstallationControl } from "./control-migration.js";
-import { repairInstallationControl } from "./control-repair.js";
+import { inspectControlCompatibility, installationControlTarget } from "./control-compatibility.js";
 
 const SURFACES = new Set(["codex", "claude", "copilot", "opencode"]);
 const SCOPE_DECISIONS = new Set(["project", "user", "back", "cancel"]);
@@ -170,7 +169,7 @@ export function inspectInstallSetup({ options, interactive = false, env = proces
     removal_overview: `npx --yes @agdf/cli@latest uninstall --surface ${options.target} --scope global`,
     full_available: fullAvailable,
     full_block_reason: blockReason,
-    control: inspectControlMigration(installationControlTarget(options).root),
+    control: inspectControlCompatibility(installationControlTarget(options).root),
     authorizes: false,
   });
   PREFLIGHT_MCP_REPORTS.set(preflight, Object.freeze({ ...reports }));
@@ -289,8 +288,8 @@ function completedResult({ selection, selectedScope, preflight, pluginReport, ru
     nextAction = codexPendingHookAction(runtimeChecks?.state ?? runtimeChecks);
   }
   const target = full ? preflight.target : null;
-  if (!failure && control?.status === "migration_required") nextAction = "migrate_control";
-  if (!failure && control?.status === "repair_required") nextAction = "repair_control";
+  if (!failure && control?.status === "unsupported") nextAction = "inspect_control";
+  if (!failure && control?.status === "repair_required") nextAction = "inspect_control";
   const targetSource = full
     ? preflight.target_source === "interactive_invocation_cwd_proposal" ? "interactive_invocation_cwd_selection" : preflight.target_source
     : "none";
@@ -327,9 +326,6 @@ export async function runInstallSetup({ options, interactive = false, env = proc
   installPlugin,
   createPluginFailure,
   finalizeRuntimeChecks,
-  confirmControlMigration,
-  chooseControlRepair,
-  confirmControlRepair,
 } = {}) {
   if (!SURFACES.has(options?.target) || typeof installPlugin !== "function") {
     throw new Error("AGDF_INSTALL_SETUP_INPUT_INVALID");
@@ -426,16 +422,7 @@ export async function runInstallSetup({ options, interactive = false, env = proc
     });
   }
   const controlTarget = installationControlTarget(options);
-  const batchConfirmation = effectiveInteractive ? confirmControlMigration : undefined;
-  let control = pluginHealthy(pluginReport)
-    ? await migrateInstallationControl(controlTarget.root, {
-      mode: options.controlMigration === "inspect" || (!controlTarget.writable && !batchConfirmation) ? "inspect" : "safe",
-      confirmMigration: batchConfirmation,
-    })
-    : preflight.control;
-  if (pluginHealthy(pluginReport) && effectiveInteractive && options.controlMigration !== "inspect") {
-    control = await repairInstallationControl(control, { chooseRepair: chooseControlRepair, confirmRepair: confirmControlRepair });
-  }
+  const control = pluginHealthy(pluginReport) ? inspectControlCompatibility(controlTarget.root) : preflight.control;
   const report = completedResult({ selection, selectedScope, preflight, pluginReport, runtimeChecks, mcpReport, control });
   return Object.freeze({ report, preflight, plugin_payload: pluginPayload ?? null });
 }

package/lib/installers/local-marketplace.js

@@ -1,3 +1,7 @@
+import { isRunOwnedDataPath } from '#agdf-core/control-state/run-identity.js';
+import { ownerPlacement, assertOwnerPlacement } from '#agdf-core/owner-placement.js';
+import { fsyncDirectory } from '#agdf-core/owned-file-lock.js';
+import { randomUUID } from 'node:crypto';
 import { CODEX_REGISTRATION_REVISION, codexLocalInstallVersion, isCodexLocalInstallVersion, marketplaceEntries as codexMarketplaceEntries } from "../host-adapters/codex/identity.js";
 import { marketplaceEntries as claudeMarketplaceEntries } from "../host-adapters/claude/marketplace.js";
 export { CODEX_REGISTRATION_REVISION, codexLocalInstallVersion, isCodexLocalInstallVersion } from "../host-adapters/codex/identity.js";
@@ -55,7 +59,12 @@ function rootIdentity(path) {
 }
 
 function assertTransactionBackupIdentity(path, transaction) {
-  if (rootIdentity(path) !== transaction.previous_root_identity || !transaction.previous_root_identity) {
+  if (transaction.schema_version === 2) {
+    const stable = path.endsWith('.backup') ? path.slice(0, -7) : path;
+    try { assertOwnerPlacement(transaction.previous_root_identity, path, 'marketplace-publication', stable); }
+    catch (cause) { throw new Error(`AGDF marketplace backup identity changed: ${path}`, { cause }); }
+    if (digestDirectory(path) !== transaction.previous_root_digest) throw Error('AGDF_MARKETPLACE_PRIOR_BYTES_CHANGED');
+  } else if (rootIdentity(path) !== transaction.previous_root_identity || !transaction.previous_root_identity) {
     throw new Error(`AGDF marketplace backup identity changed: ${path}`);
   }
 }
@@ -447,11 +456,21 @@ function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failed
   const parent = dirname(stableRoot);
   const transaction = existsSync(transactionPath)
     ? readOptionalJson(transactionPath) : null;
-  if (existsSync(transactionPath) && (transaction?.schema_version !== 1
+  if (transaction?.phase === 'legacy_settlement') {
+    if (transaction.legacy_settlement?.step !== 'completed') throw Error('AGDF_LEGACY_SETTLEMENT_RECOVERY_REQUIRED');
+    validateLegacySettlement(transaction, stableRoot, failedRoot);
+    if (existsSync(failedRoot) || existsSync(backupRoot) || existsSync(stageRoot)) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+    rmSync(transactionPath); fsyncDirectory(parent);
+    return;
+  }
+  if (existsSync(transactionPath) && (![1, 2].includes(transaction?.schema_version)
       || transaction.owner !== "create-agdf" || !["prepared", "committed", "cockpit_qualification_pending"].includes(transaction.phase)
       || typeof transaction.plugin_digest !== "string" || typeof transaction.version !== "string"
       || typeof transaction.profile_id !== "string"
-      || (transaction.previous_root_identity !== null && typeof transaction.previous_root_identity !== "string"))) {
+      || (transaction.schema_version === 1 && transaction.previous_root_identity !== null && typeof transaction.previous_root_identity !== "string")
+      || (transaction.schema_version === 2 && transaction.previous_root_identity !== null
+        && (!transaction.previous_root_identity || transaction.previous_root_identity.role !== 'marketplace-publication'
+          || !/^[a-f0-9]{64}$/.test(transaction.previous_root_digest))))) {
     throw new Error(`Invalid AGDF marketplace transaction marker: ${transactionPath}`);
   }
   if (transaction?.phase === 'cockpit_qualification_pending') {
@@ -484,7 +503,10 @@ function recoverInterruptedTransaction(stableRoot, stageRoot, backupRoot, failed
     renameSyncWithRetry(backupRoot, stableRoot);
     if (existsSync(failedRoot)) removeOwnedRoot(failedRoot, parent);
   } else if (transaction?.phase === "prepared" && existsSync(stableRoot)) {
-    if (rootIdentity(stableRoot) !== transaction.previous_root_identity) {
+    const isPrevious = transaction.schema_version === 2 && transaction.previous_root_identity !== null
+      ? (() => { try { assertTransactionBackupIdentity(stableRoot, transaction); return true; } catch { return false; } })()
+      : rootIdentity(stableRoot) === transaction.previous_root_identity;
+    if (!isPrevious) {
       if (transaction.previous_root_identity !== null) {
         throw new Error(`AGDF marketplace prior backup missing: ${backupRoot}`);
       }
@@ -673,13 +695,14 @@ function prepareLocalMarketplaceFromSource({
     }
 
     const transaction = {
-      schema_version: 1,
+      schema_version: 2,
       owner: "create-agdf",
       phase: "prepared",
       profile_id: profileId,
       version: expectedVersion,
       plugin_digest: pluginDigest,
-      previous_root_identity: rootIdentity(stableRoot),
+      previous_root_identity: existsSync(stableRoot) ? ownerPlacement(stableRoot, 'marketplace-publication') : null,
+      previous_root_digest: existsSync(stableRoot) ? digestDirectory(stableRoot) : null,
     };
     atomicWrite(transactionPath, `${JSON.stringify(transaction)}\n`);
     if (existsSync(stableRoot)) renameSyncWithRetry(stableRoot, backupRoot);
@@ -763,6 +786,8 @@ function prepareLocalMarketplaceFromSource({
 }
 
 export function prepareLocalMarketplace(options = {}) {
+  if (options.packageSelection === 'planning') return preparePlanningMarketplace(options);
+  if (options.packageSelection !== undefined && options.packageSelection !== 'core') throw Error('AGDF_PACKAGE_SELECTION_INVALID');
   if (!options.snapshotSource) return prepareLocalMarketplaceFromSource(options);
   if (Object.hasOwn(options, "codexInstallVersion")) {
     throw new Error("AGDF snapshot preparation owns the Codex local install version.");
@@ -789,6 +814,82 @@ export function prepareLocalMarketplace(options = {}) {
   }
 }
 
+// The known skill-only extension shares source capture and publication primitives
+// with Core. Content-addressed roots are immutable: updating the native catalog
+// never replaces a Core installation, and no second runtime is assembled here.
+export function inspectPlanningMarketplace(root) {
+  if (!isAbsolute(root) || realpathSync(root) !== resolve(root)) throw Error('AGDF_PLANNING_MARKETPLACE_UNSAFE');
+  const marker = readJson(join(root, OWNERSHIP_FILE), 'planning marketplace ownership');
+  const pluginRoot = join(root, 'plugins/agdf-planning');
+  const names = readdirSync(root).sort();
+  if (names.join() !== '.agdf-owned.json,.agents,plugins' || readdirSync(join(root, 'plugins')).join() !== 'agdf-planning'
+    || readdirSync(join(root, '.agents')).join() !== 'plugins' || readdirSync(join(root, '.agents/plugins')).join() !== 'marketplace.json') throw Error('AGDF_PLANNING_MARKETPLACE_UNCONFIRMED');
+  if (Object.keys(marker).sort().join() !== 'canonical_version,kind,owner,plugin_digest,schema_version,source_digest,version'
+    || marker.schema_version !== 1 || marker.owner !== 'create-agdf' || marker.kind !== 'planning-marketplace'
+    || !/^[a-f0-9]{64}$/u.test(marker.source_digest ?? '') || digestDirectory(pluginRoot) !== marker.plugin_digest
+    || typeof marker.canonical_version !== 'string' || !isCodexLocalInstallVersion(marker.canonical_version, marker.version, marker.source_digest)
+    || JSON.stringify(readJson(join(root, '.agents/plugins/marketplace.json'), 'planning marketplace')) !== JSON.stringify(planningCatalog()))
+    throw Error('AGDF_PLANNING_MARKETPLACE_UNCONFIRMED');
+  validatePlanningSource(pluginRoot, marker.version);
+  return { ...marker, root, pluginRoot };
+}
+function planningCatalog() {
+  return { name: 'agdf-planning', interface: { displayName: 'AGDF Planning' }, plugins: [{ name: 'agdf-planning',
+    source: { source: 'local', path: './plugins/agdf-planning' }, policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' }, category: 'Productivity' }] };
+}
+function validatePlanningSource(root, expectedVersion) {
+  const manifest = readJson(join(root, 'plugin.json'), 'planning portable manifest');
+  const native = readJson(join(root, '.codex-plugin/plugin.json'), 'planning Codex manifest');
+  const definition = readJson(join(root, 'meta/agdf-planning.definition.json'), 'planning definition');
+  if (manifest.name !== 'agdf-planning' || manifest.version !== expectedVersion || native.name !== manifest.name || native.version !== manifest.version
+    || definition.core_capability?.schema !== 'planned-ur-v1' || definition.core_capability.protocol_version !== 1
+    || definition.core_capability.authoring_owner !== 'ur-definition' || native.mcpServers || native.hooks
+    || !existsSync(join(root, 'skills/planning/SKILL.md'))) throw Error('AGDF_PLANNING_PACKAGE_INVALID');
+  const visit = directory => {
+    for (const name of readdirSync(directory)) {
+      const path = join(directory, name), stat = lstatSync(path);
+      if (stat.isSymbolicLink() || !stat.isDirectory() && !stat.isFile() || stat.isFile() && stat.size > 131072
+        || ['runtime', 'mcp', 'hooks', 'control', 'templates', 'mcp.json', '.mcp.json'].includes(name)) throw Error('AGDF_PLANNING_PACKAGE_INVALID');
+      if (stat.isDirectory()) visit(path);
+    }
+  };
+  visit(root);
+}
+export function preparePlanningMarketplace({ dataRoot = defaultAgdfDataRoot(), expectedVersion = pluginDefinition.version,
+  planningRoot = join(generatedRoot, 'plugins/agdf-planning') } = {}) {
+  validatePlanningSource(planningRoot, expectedVersion);
+  const snapshot = captureLocalPluginSnapshot({ builtPluginRoot: planningRoot, expectedVersion, profileId: 'planning',
+    adapters: { digest: digestDirectory } });
+  try {
+    mkdirSync(resolve(dataRoot), { recursive: true });
+    const parent = join(realpathSync(resolve(dataRoot)), 'marketplaces', 'agdf-planning');
+    mkdirSync(parent, { recursive: true });
+    if (realpathSync(parent) !== parent) throw Error('AGDF_PLANNING_MARKETPLACE_UNSAFE');
+    const root = join(parent, snapshot.sourceDigest), version = snapshot.codexInstallVersion;
+    return withOwnedFileLock(join(parent, '.publication'), () => {
+      if (existsSync(root)) {
+        const known = inspectPlanningMarketplace(root);
+        if (known.source_digest !== snapshot.sourceDigest || known.version !== version) throw Error('AGDF_PLANNING_MARKETPLACE_UNCONFIRMED');
+      } else {
+        const stage = mkdtempSync(join(parent, '.stage-')), pluginRoot = join(stage, 'plugins/agdf-planning');
+        cpSync(snapshot.pluginRoot, pluginRoot, { recursive: true });
+        if (digestDirectory(pluginRoot) !== snapshot.sourceDigest) throw localInstallSourceUnstable('planning-copy');
+        for (const path of ['plugin.json', '.codex-plugin/plugin.json']) {
+          const file = join(pluginRoot, path); writeJson(file, { ...readJson(file, 'planning manifest'), version });
+        }
+        writeJson(join(stage, '.agents/plugins/marketplace.json'), planningCatalog());
+        writeJson(join(stage, OWNERSHIP_FILE), { schema_version: 1, owner: 'create-agdf', kind: 'planning-marketplace',
+          source_digest: snapshot.sourceDigest, plugin_digest: digestDirectory(pluginRoot), version, canonical_version: expectedVersion });
+        inspectPlanningMarketplace(stage); fsyncDirectory(stage);
+        renameSyncWithRetry(stage, root); fsyncDirectory(parent);
+      }
+      const known = inspectPlanningMarketplace(root);
+      return Object.freeze({ ...known, codexInstallVersion: version, sourceDigest: snapshot.sourceDigest, digest: known.plugin_digest,
+        changed: false, commit() {}, rollback() {} });
+    });
+  } finally { snapshot.cleanup(); }
+}
+
 export function prepareCopilotMarketplace(options = {}) {
   const { codexInstallVersion, ...copilotOptions } = options;
   return prepareLocalMarketplace({
@@ -974,7 +1075,7 @@ export function settleCodexCockpitPublication({ pluginRoot, target, sourceDigest
   const transactionPath = `${stableRoot}.transaction.json`, backupRoot = `${stableRoot}.backup`, failedRoot = `${stableRoot}.failed`;
   return withOwnedFileLock(`${stableRoot}.cockpit-settle`, () => {
   const transaction = readOptionalJson(transactionPath);
-  if (transaction?.schema_version !== 1 || transaction.owner !== 'create-agdf' || transaction.profile_id !== 'runtime-plugin'
+  if (![1, 2].includes(transaction?.schema_version) || transaction.owner !== 'create-agdf' || transaction.profile_id !== 'runtime-plugin'
     || transaction.phase !== 'cockpit_qualification_pending' || transaction.cockpit_target !== target
     || transaction.source_digest !== sourceDigest) throw Error('AGDF_COCKPIT_SETTLEMENT_CONFLICT');
   if (action === 'rollback' && transaction.previous_source_digest !== previousSourceDigest
@@ -1009,7 +1110,7 @@ export function settleCodexCockpitPublication({ pluginRoot, target, sourceDigest
       throw Error('AGDF_COCKPIT_FINAL_EVIDENCE_REQUIRED');
     for (const ref of finalEvidence.evidence) {
       const path = resolve(target, ref.path);
-      if (!pathInside(join(target, '.agdf/control/artefacts'), path) || digest(path) !== ref.digest)
+      if (!isRunOwnedDataPath(relative(target, path).split('\\').join('/')) || digest(path) !== ref.digest)
         throw Error('AGDF_COCKPIT_FINAL_EVIDENCE_REQUIRED');
     }
     const runtime = inspectMcpExecutableRoot({ root: finalEvidence.runtime_root, expectedVersion: transaction.version });
@@ -1043,3 +1144,156 @@ export function settleCodexCockpitPublication({ pluginRoot, target, sourceDigest
   return { status: 'restored', source_digest: transaction.previous_source_digest };
   });
 }
+
+// Explicit compatibility recovery for an original schema-1 publication whose
+// mount-session device number changed. Automatic schema-1 predicates stay exact.
+const settlementHash = value => createHash('sha256').update(value).digest('hex');
+function settlementFile(path, limit = 65536) {
+  let stat;
+  try { stat = lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > limit || realpathSync(path) !== resolve(path))
+    throw Error('AGDF_LEGACY_SETTLEMENT_UNSAFE');
+  return readFileSync(path);
+}
+function settlementPaths({ pluginRoot, target, hostHome = homedir() }) {
+  if (!isAbsolute(pluginRoot ?? '') || !isAbsolute(target ?? '') || realpathSync(target) !== target || !isAbsolute(hostHome))
+    throw Error('AGDF_LEGACY_SETTLEMENT_INPUT_INVALID');
+  const stable = dirname(dirname(pluginRoot));
+  if (join(stable, 'plugins', MARKETPLACE_ID) !== pluginRoot) throw Error('AGDF_LEGACY_SETTLEMENT_INPUT_INVALID');
+  return { stable, backup: stable + '.backup', failed: stable + '.failed', stage: stable + '.stage',
+    journal: stable + '.transaction.json', configurations: [...new Set([join(target, '.codex/config.toml'), join(hostHome, '.codex/config.toml')])] };
+}
+function configurationSnapshot(paths) {
+  return paths.map(path => { const bytes = settlementFile(path, 4 * 1024 ** 2); return { path, digest: bytes === null ? null : settlementHash(bytes) }; });
+}
+function settlementWitness(reference, target) {
+  if (!reference || !isAbsolute(reference.path ?? '') || !/^sha256:[a-f0-9]{64}$/.test(reference.digest ?? '')
+    || !(pathInside(join(target, 'probe-results'), reference.path) || isRunOwnedDataPath(relative(target, reference.path).split('\\').join('/'))))
+    throw Error('AGDF_LEGACY_SETTLEMENT_WITNESS_REQUIRED');
+  const bytes = settlementFile(reference.path);
+  if (!bytes || 'sha256:' + settlementHash(bytes) !== reference.digest) throw Error('AGDF_LEGACY_SETTLEMENT_WITNESS_CHANGED');
+  const value = JSON.parse(bytes);
+  if (value.kind !== 'isolated_update_prerequisite_preview' || value.live_mutation !== false
+    || !['stable', 'backup', 'transaction'].every(k => /^[a-f0-9]{64}$/.test(value.before?.[k] ?? '') && value.before[k] === value.after?.[k]))
+    throw Error('AGDF_LEGACY_SETTLEMENT_WITNESS_REQUIRED');
+  return value;
+}
+export function inspectLegacyCodexCockpitSettlement(options = {}) {
+  const paths = settlementPaths(options), bytes = settlementFile(paths.journal), transaction = bytes && JSON.parse(bytes);
+  if (transaction?.schema_version !== 1 || transaction.owner !== 'create-agdf' || transaction.profile_id !== 'runtime-plugin'
+    || transaction.phase !== 'cockpit_qualification_pending' || transaction.cockpit_target !== options.target
+    || transaction.source_digest !== options.sourceDigest || transaction.previous_source_digest !== options.previousSourceDigest
+    || !/^[1-9][0-9]*:[1-9][0-9]*$/.test(transaction.previous_root_identity ?? '')
+    || existsSync(paths.failed) || existsSync(paths.stage)) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+  const witness = settlementWitness(options.witness, options.target);
+  if (JSON.stringify(witness.live_transition) !== JSON.stringify(transaction)
+    || witness.before.transaction !== settlementHash(bytes) || witness.before.stable !== digestDirectory(paths.stable)
+    || witness.before.backup !== digestDirectory(paths.backup)) throw Error('AGDF_LEGACY_SETTLEMENT_WITNESS_CHANGED');
+  assertTransactionStablePayload(paths.stable, transaction);
+  const prior = ownership(paths.backup);
+  if (prior.source_digest !== transaction.previous_source_digest || digestDirectory(join(paths.backup, 'plugins', MARKETPLACE_ID)) !== prior.plugin_digest)
+    throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+  const binding = ownerPlacement(paths.backup, 'marketplace-publication', paths.stable);
+  if (binding.directory_ino !== transaction.previous_root_identity.split(':')[1]) throw Error('AGDF_LEGACY_SETTLEMENT_PRIOR_REPLACED');
+  const body = { schema_version: 1, kind: 'legacy_publication_settlement_preview', action: 'rollback', target: options.target,
+    paths, source_digest: transaction.source_digest, previous_source_digest: transaction.previous_source_digest,
+    original_journal_digest: settlementHash(bytes), original_identity: transaction.previous_root_identity,
+    current_identity: rootIdentity(paths.backup), previous_binding: binding,
+    current_binding: ownerPlacement(paths.stable, 'marketplace-publication'),
+    previous_digest: witness.before.backup, current_digest: witness.before.stable,
+    witness: options.witness, configurations: configurationSnapshot(paths.configurations),
+    configuration_effect: 'preserve exact current configuration; rollback changes only the owned marketplace publication', authorizes: false };
+  const preview_digest = 'sha256:' + settlementHash(JSON.stringify(body));
+  return { ...body, preview_digest, required_confirmation: `Restore previous AGDF publication: ${preview_digest}` };
+}
+function validateLegacySettlement(transaction, stable, failed) {
+  const recovery = transaction?.legacy_settlement;
+  if (transaction?.schema_version !== 1 || transaction.phase !== 'legacy_settlement' || !recovery || recovery.schema_version !== 1
+    || !['confirmed', 'restoring', 'cleanup', 'completed'].includes(recovery.step)) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+  const { digest: seal, ...body } = recovery;
+  const originalBytes = Buffer.from(recovery.original_bytes ?? '', 'base64');
+  if (seal !== settlementHash(JSON.stringify(body)) || settlementHash(originalBytes) !== recovery.preview.original_journal_digest
+    || recovery.confirmation_digest !== settlementHash(`Restore previous AGDF publication: ${recovery.preview.preview_digest}`)
+    || recovery.preview.paths.stable !== stable || recovery.preview.paths.failed !== failed
+    || transaction.source_digest !== recovery.preview.source_digest || transaction.previous_source_digest !== recovery.preview.previous_source_digest)
+    throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+  const original = JSON.parse(originalBytes), witness = settlementWitness(recovery.preview.witness, recovery.preview.target);
+  const { phase: _phase, legacy_settlement: _recovery, ...retained } = transaction;
+  const { phase: _originalPhase, ...originalFields } = original;
+  const { preview_digest, required_confirmation: _confirmation, ...previewBody } = recovery.preview;
+  if (JSON.stringify(retained) !== JSON.stringify(originalFields)
+    || preview_digest !== 'sha256:' + settlementHash(JSON.stringify(previewBody))
+    || original.cockpit_target !== recovery.preview.target || original.previous_root_identity.split(':')[1] !== recovery.preview.previous_binding.directory_ino)
+    throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+  if (JSON.stringify(witness.live_transition) !== JSON.stringify(original) || original.phase !== 'cockpit_qualification_pending'
+    || witness.before.transaction !== recovery.preview.original_journal_digest || witness.before.backup !== recovery.preview.previous_digest
+    || witness.before.stable !== recovery.preview.current_digest
+    || JSON.stringify(configurationSnapshot(recovery.preview.paths.configurations)) !== JSON.stringify(recovery.preview.configurations))
+    throw Error('AGDF_LEGACY_SETTLEMENT_WITNESS_CHANGED');
+  if (recovery.step === 'completed') {
+    assertOwnerPlacement(recovery.preview.previous_binding, stable, 'marketplace-publication', stable);
+    if (digestDirectory(stable) !== recovery.preview.previous_digest) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+  }
+  return recovery;
+}
+export function settleLegacyCodexCockpitPublication(options = {}) {
+  const paths = settlementPaths(options), checkpoint = options.checkpoint ?? (() => {});
+  return withOwnedFileLock(paths.stable + '.cockpit-settle', () => {
+    let transaction = JSON.parse(settlementFile(paths.journal)), recovery;
+    const resumed = transaction.phase === 'legacy_settlement';
+    const historicalEffect = resumed && transaction.legacy_settlement?.step === 'completed';
+    const save = step => {
+      const { digest: _old, ...previous } = recovery;
+      const body = { ...previous, step }; recovery = { ...body, digest: settlementHash(JSON.stringify(body)) };
+      transaction = { ...transaction, phase: 'legacy_settlement', legacy_settlement: recovery };
+      atomicWrite(paths.journal, JSON.stringify(transaction) + '\n'); fsyncDirectory(dirname(paths.journal));
+    };
+    if (transaction.phase === 'legacy_settlement') {
+      recovery = validateLegacySettlement(transaction, paths.stable, paths.failed);
+      if (options.previewDigest !== recovery.preview.preview_digest || options.confirmation !== `Restore previous AGDF publication: ${options.previewDigest}`)
+        throw Error('AGDF_LEGACY_SETTLEMENT_CONFIRMATION_REQUIRED');
+      if (options.target !== recovery.preview.target || options.sourceDigest !== recovery.preview.source_digest
+        || options.previousSourceDigest !== recovery.preview.previous_source_digest
+        || JSON.stringify(options.witness) !== JSON.stringify(recovery.preview.witness)
+        || JSON.stringify(paths) !== JSON.stringify(recovery.preview.paths)) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+    } else {
+      const preview = inspectLegacyCodexCockpitSettlement(options);
+      if (options.previewDigest !== preview.preview_digest || options.confirmation !== preview.required_confirmation)
+        throw Error('AGDF_LEGACY_SETTLEMENT_CONFIRMATION_REQUIRED');
+      recovery = { schema_version: 1, operation_id: randomUUID(), step: 'confirmed', preview,
+        original_bytes: settlementFile(paths.journal).toString('base64'), confirmation_digest: settlementHash(options.confirmation) };
+      save('confirmed'); checkpoint('confirmed');
+    }
+    const preview = recovery.preview;
+    if (recovery.step !== 'completed') {
+      // The same fixed objects may be at their declared before/after rename roles.
+      if (existsSync(paths.backup)) {
+        assertOwnerPlacement(preview.previous_binding, paths.backup, 'marketplace-publication', paths.stable);
+        if (digestDirectory(paths.backup) !== preview.previous_digest) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+        if (existsSync(paths.stable)) {
+          if (existsSync(paths.failed)) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+          assertOwnerPlacement(preview.current_binding, paths.stable, 'marketplace-publication');
+          if (digestDirectory(paths.stable) !== preview.current_digest) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+          save('restoring'); renameSyncWithRetry(paths.stable, paths.failed); fsyncDirectory(dirname(paths.stable)); checkpoint('current_moved');
+        }
+        assertOwnerPlacement(preview.current_binding, paths.failed, 'marketplace-publication', paths.stable);
+        if (digestDirectory(paths.failed) !== preview.current_digest) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+        renameSyncWithRetry(paths.backup, paths.stable); fsyncDirectory(dirname(paths.stable)); checkpoint('previous_restored');
+      }
+      assertOwnerPlacement(preview.previous_binding, paths.stable, 'marketplace-publication');
+      if (digestDirectory(paths.stable) !== preview.previous_digest) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+      if (!existsSync(paths.failed) && recovery.step !== 'cleanup') throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+      if (existsSync(paths.failed)) {
+        assertOwnerPlacement(preview.current_binding, paths.failed, 'marketplace-publication', paths.stable);
+        if (digestDirectory(paths.failed) !== preview.current_digest) throw Error('AGDF_LEGACY_SETTLEMENT_CONFLICT');
+        save('cleanup'); checkpoint('before_cleanup'); removeOwnedRoot(paths.failed, dirname(paths.stable)); checkpoint('after_cleanup');
+      }
+      save('completed'); checkpoint('completed');
+    }
+    validateLegacySettlement(transaction, paths.stable, paths.failed);
+    return { status: 'restored', source_digest: preview.previous_source_digest, operation_id: recovery.operation_id,
+      preview_digest: preview.preview_digest, original_journal_digest: preview.original_journal_digest,
+      original_journal_base64: recovery.original_bytes, journal: paths.journal, witness: preview.witness,
+      configurations: preview.configurations, recovery_retained: true, historical_effect: historicalEffect, recovered: resumed, authorizes: false };
+  });
+}

package/lib/lifecycle/codex-startup-status.js

@@ -0,0 +1,29 @@
+import { observeCodexOrigins } from '../mcp-lifecycle/adapters/codex-origin-probe.js';
+import { CODEX_MCP_STARTUP_ARGS } from '../host-adapters/codex/mcp-startup.js';
+
+// Transient host observations. Installation, registration and actual catalog
+// readiness remain separate facts; this function grants no authority.
+export async function inspectCodexStartup({ target, native = false, env = process.env },
+  { observe = observeCodexOrigins, now = Date.now } = {}) {
+  const deadline = now() + 45000;
+  const configuration = await observe({ target, mode: 'configuration', env, timeoutMs: 15000 });
+  let catalog = { status: 'not_observed', reason: 'native_not_requested', providers: [] };
+  if (native) {
+    const remaining = deadline - now();
+    const result = remaining > 0 ? await observe({ target, mode: 'catalog', all: true, env, timeoutMs: remaining })
+      : { status: 'unavailable', reason: 'timeout' };
+    const providers = (result.providers ?? []).filter(row => row.server_id === 'agdf' && row.plugin_id === 'agdf@agdf');
+    const ready = result.status === 'observed' && providers.length === 1
+      && ['agdf_inspect', 'agdf_project'].every(name => providers[0].tools.includes(name))
+      && !['failed', 'starting', 'connecting'].includes(providers[0].runtime_status);
+    catalog = { status: ready ? 'discovered_ready' : 'unavailable',
+      reason: ready ? null : result.reason ?? 'owned_required_tools_unavailable',
+      requested: true, invocation_override: [...CODEX_MCP_STARTUP_ARGS], providers,
+      teardown: result.status === 'observed' ? 'confirmed' : 'unconfirmed' };
+  }
+  return { schema_version: 1, authorizes: false, configuration, catalog,
+    next_action: catalog.status === 'discovered_ready'
+      ? 'Inspect project-state for the confirmed Git root; initialize only with deliberate setup intent.'
+      : native ? 'Inspect the reported Codex startup cause and supported MCP registration status. Preserve configuration and original operation identity.'
+        : 'Registration is not catalog readiness. Use status --surface codex --dir ABSOLUTE --native --json for an explicit bounded catalog observation.' };
+}

package/lib/lifecycle/presentation.js

@@ -140,5 +140,11 @@ export function printGeneralStatus(report, { json = false, io = console } = {})
   io.log(`Automatic runtime checks: requested=${report.runtime_checks.requested}; effective=${report.runtime_checks.effective}; reason=${report.runtime_checks.reason}`);
   if (report.runtime_checks.verification) io.log(`Automatic-check verification: ${report.runtime_checks.verification}`);
   io.log(`MCP: ${report.mcp?.result ?? report.mcp?.status ?? "not_checked"}`);
+  if (report.codex_startup) {
+    const { configuration, catalog, next_action } = report.codex_startup;
+    io.log(`Codex startup configuration: ${configuration.status}; wait_ms=${configuration.wait_ms ?? 'unknown'}; origin=${configuration.origin?.kind ?? 'unknown'}; reason=${configuration.reason ?? 'none'}`);
+    io.log(`Codex native catalog: ${catalog.status}; reason=${catalog.reason ?? 'none'}`);
+    io.log(`Codex next action: ${next_action}`);
+  }
   io.log(`Next action: ${report.next_action.text}`);
 }