create-agdf 0.20.1 → 0.30.0

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}`);
 }

package/lib/mcp-decision-protocol.js

@@ -0,0 +1,40 @@
+import { RUN_COMMAND_GROUPS, RUN_COMMAND_LIMITS } from '#agdf-core/control-state/run-command-schema.js';
+
+// Optional UI composition is deliberately outside the default headless import
+// closure. Full and thin UI fronts share this one structural contract.
+const unwrapped = () => { throw Object.assign(Error('generation_unavailable'), { code: 'generation_unavailable', dispatch: 'not_dispatched' }); };
+
+import { decisionActionDefinition, validateDecisionAction, DECISION_VIEW_DEFINITION, validateDecisionView } from '#agdf-core/control-state/decision-action-contract.js';
+import { COCKPIT_READ_DEFINITION, parseCockpitArguments } from '#agdf-core/control-inspect/cockpit-contract.js';
+
+export function composeMcpDecisionProtocol({ runtime, ui, prepared = unwrapped, open = unwrapped, read = unwrapped, action = unwrapped, close = () => {} } = {}) {
+  const groups = runtime.trustedContext.commandGroups;
+  const facade = decisionActionDefinition(groups);
+  const tools = [...runtime.tools];
+  if (groups.includes('agdf_prepare')) tools.push({ name: DECISION_VIEW_DEFINITION.name, definition: DECISION_VIEW_DEFINITION, requiresUi: true, parentOwned: true,
+    parse: input => { if (validateDecisionView(input).length) throw Error('decision_schema_invalid'); return input; },
+    execute: async (input, signal, host) => {
+      const remembered = prepared(input);
+      if (!remembered) return { schema_version: '1', outcome: 'rejected', reason: 'delivery_state_unavailable', authorizes: false };
+      const opened = await open(remembered.input, remembered.result, host);
+      return { schema_version: '1', outcome: opened._meta ? 'accepted' : 'rejected', reason: opened.app_reason ?? null,
+        app_capability: opened.app_capability, authorizes: false, ...(opened._meta ? { _meta: opened._meta } : {}) };
+    }, serialize: JSON.stringify });
+  tools.push({ name: COCKPIT_READ_DEFINITION.name, definition: COCKPIT_READ_DEFINITION, requiresUi: true, parentOwned: true,
+    parse: parseCockpitArguments, execute: (input, signal, host) => read(input, signal, host), serialize: value => JSON.stringify(value) });
+  if (facade) tools.push({ name: facade.name, definition: facade, requiresUi: true, parentOwned: true,
+    parse: input => { if (validateDecisionAction(input, facade.inputSchema.properties.action.enum).length) throw Error('decision_schema_invalid'); return input; },
+    execute: (input, signal, host) => action(input, host), serialize: value => JSON.stringify(value) });
+  const bytes = tools.filter(tool => Object.hasOwn(RUN_COMMAND_GROUPS, tool.name) || tool.name === facade?.name || tool.name === DECISION_VIEW_DEFINITION.name)
+    .reduce((sum, tool) => sum + Buffer.byteLength(JSON.stringify(tool.definition)), 0);
+  if (bytes > RUN_COMMAND_LIMITS.aggregate_definition_bytes) { void close(); throw Error('command_aggregate_definition_budget_exceeded'); }
+  return Object.freeze({ ...runtime, tools: Object.freeze(tools), ui, mode: 'decision',
+    tool: name => tools.find(tool => tool.name === name) ?? null,
+    failure(code, name, input, dispatch) {
+      return name === 'agdf_decision_action' ? { schema_version: '1', outcome: dispatch?.dispatch === 'not_dispatched' ? 'rejected' : 'effect_unknown',
+        reason: code, operation_id: input?.operation_id ?? null, authorizes: false, recovery: 'Inspect the original UUID; do not infer non-execution or submit another decision.' }
+        : ['agdf_cockpit_read', 'agdf_decision_view'].includes(name) ? { schema_version: '1', outcome: 'rejected', reason: code, authorizes: false } : runtime.failure(code, name, input, dispatch);
+    },
+  });
+}
+