@lesliechan721/aw 0.1.0-beta.6 → 0.1.0-beta.60

package/dist/src/utils/native-cli.js

@@ -1,12 +1,32 @@
 import { execFile } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { observeProcessTree, terminateProcessTree, } from './process-tree.js';
+import path from 'node:path';
+import { createWindowsJobInvocation, observeProcessTree, prepareWindowsJobHelper, terminateProcessTree, } from './process-tree.js';
+import { getCodexHome } from './state-paths.js';
+import { resolveWindowsClaudeCommand } from './windows-claude-shim.js';
+import { resolveWindowsNpmCommand } from './windows-npm-shim.js';
 const NATIVE_CLI_TIMEOUT_ENV = 'AW_NATIVE_CLI_TIMEOUT_MS';
 const DEFAULT_NATIVE_CLI_TIMEOUT_MS = 60_000;
 const MIN_NATIVE_CLI_TIMEOUT_MS = 1_000;
 const MAX_NATIVE_CLI_TIMEOUT_MS = 600_000;
 const NATIVE_CLI_CLEANUP_TIMEOUT_MS = 4_500;
+const NATIVE_CLI_PROCESS_GROUP_TERM_GRACE_MS = 100;
+const NATIVE_CLI_PROCESS_GROUP_POLL_MS = 25;
+const NATIVE_CLI_PROCESS_GROUP_VERIFY_MS = 4_000;
 const NATIVE_CLI_PROCESS_MARKER_ENV = 'AW_NATIVE_CLI_PROCESS_MARKER';
+export const SYSTEM_CODEX_MANAGER = {
+    kind: 'system',
+    version: 'unknown',
+    command: 'codex',
+    argsPrefix: [],
+};
+export class CodexProjectConfigNotEffectiveError extends Error {
+    code = 'codexProjectConfigNotEffective';
+    constructor(pluginId) {
+        super(`codexProjectConfigNotEffective: Codex did not apply the expected project activation for ${pluginId}.`);
+        this.name = 'CodexProjectConfigNotEffectiveError';
+    }
+}
 function renderNativeCliCleanupError(error) {
     return error.message
         .replace(/^Native CLI cleanup unconfirmed:\s*/u, '')
@@ -19,6 +39,7 @@ export class NativeCliError extends Error {
     stderr;
     reason;
     cleanupError;
+    operationDiagnostic;
     constructor(options) {
         const renderedArgs = options.invocation.args.join(' ');
         const detail = options.stderr.trim() ||
@@ -36,15 +57,49 @@ export class NativeCliError extends Error {
         this.reason = options.reason ?? 'exit';
         this.cleanupError = options.cleanupError;
         this.cause = options.cause;
+        const causeCode = readNativeCliErrorCode(options.cause);
+        const safeCauseCode = causeCode === 'ENOENT' || causeCode === 'EACCES' || causeCode === 'EPERM'
+            ? causeCode : undefined;
+        this.operationDiagnostic = {
+            code: safeCauseCode === 'ENOENT' ? 'nativeCliExecutableMissing'
+                : this.reason === 'timeout' ? 'nativeCliTimedOut' : 'nativeCliFailed',
+            safeMessage: causeCode === 'ENOENT' ? 'The required platform CLI is not installed or cannot be found.'
+                : this.reason === 'timeout' ? 'The platform CLI timed out.'
+                    : 'The platform CLI exited unsuccessfully.',
+            exitCode: options.exitCode,
+            ...(safeCauseCode === undefined ? {} : {
+                cause: { code: safeCauseCode, safeMessage: `The platform CLI reported ${safeCauseCode}.` },
+            }),
+        };
     }
 }
 let nativeCliRunnerOverrideForTests = null;
+const nativeCliRunnerBases = new WeakMap();
+export function retainNativeCliRunnerBackend(wrapper, base) {
+    nativeCliRunnerBases.set(wrapper, base);
+    return wrapper;
+}
+function usesDefaultNativeCliBackend(runner) {
+    const seen = new Set();
+    while (nativeCliRunnerBases.has(runner) && !seen.has(runner)) {
+        seen.add(runner);
+        runner = nativeCliRunnerBases.get(runner);
+    }
+    return runner === execFileNativeCliRunner;
+}
 export function setNativeCliRunnerOverrideForTests(runner) {
     nativeCliRunnerOverrideForTests = runner;
 }
 export function getDefaultNativeCliRunner() {
     return nativeCliRunnerOverrideForTests ?? execFileNativeCliRunner;
 }
+/** Prepare outside the AW_HOME write lock. Injected runners own their admission. */
+export async function prepareNativeCliExecution(options = {}) {
+    if (process.platform !== 'win32'
+        || !usesDefaultNativeCliBackend(options.runner ?? getDefaultNativeCliRunner()))
+        return;
+    await prepareWindowsJobHelper();
+}
 function readNativeCliErrorCode(error) {
     if (!error || typeof error !== 'object') {
         return undefined;
@@ -105,7 +160,57 @@ function isTimeoutLikeError(error, timeoutMs) {
 const defaultNativeCliExecFile = (command, args, options, callback) => execFile(command, args, options, (error, stdout, stderr) => {
     callback(error, stdout, stderr);
 });
-function settleNativeCliTerminationCleanup(child, terminateProcessTreeImpl, observation, requireConfirmedCleanup) {
+function delayNativeCliCleanup(delayMs) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, delayMs);
+    });
+}
+function isProcessGroupMissing(error) {
+    return Boolean(error &&
+        typeof error === 'object' &&
+        'code' in error &&
+        error.code === 'ESRCH');
+}
+function isPosixProcessInspectionUnavailableError(error) {
+    return /POSIX (?:process (?:identity|marker) lookup|termination (?:audit|verification)) failed/u
+        .test(error.message);
+}
+async function terminateNativeCliProcessGroup(pid, killProcess) {
+    const groupPid = -pid;
+    const signalGroup = (signal) => {
+        try {
+            killProcess(groupPid, signal);
+        }
+        catch (error) {
+            if (isProcessGroupMissing(error)) {
+                return;
+            }
+            throw new Error(`Native CLI cleanup unconfirmed: could not signal process group ${signal}.`, { cause: error });
+        }
+    };
+    const groupExists = () => {
+        try {
+            killProcess(groupPid, 0);
+            return true;
+        }
+        catch (error) {
+            if (isProcessGroupMissing(error)) {
+                return false;
+            }
+            throw new Error('Native CLI cleanup unconfirmed: could not verify process group exit.', { cause: error });
+        }
+    };
+    signalGroup('SIGTERM');
+    await delayNativeCliCleanup(NATIVE_CLI_PROCESS_GROUP_TERM_GRACE_MS);
+    signalGroup('SIGKILL');
+    for (let elapsedMs = 0; groupExists(); elapsedMs += NATIVE_CLI_PROCESS_GROUP_POLL_MS) {
+        if (elapsedMs >= NATIVE_CLI_PROCESS_GROUP_VERIFY_MS) {
+            throw new Error('Native CLI cleanup unconfirmed: process group is still running.');
+        }
+        await delayNativeCliCleanup(NATIVE_CLI_PROCESS_GROUP_POLL_MS);
+    }
+}
+function settleNativeCliTerminationCleanup(child, terminateProcessTreeImpl, observation, requireConfirmedCleanup, allowUnobservedWindowsProcessOnNormalCompletion, processGroup, allowUnavailablePosixAudit, processTreeAuditPreparationError, killProcess) {
     let directKillAttempted = false;
     const killDirectChild = () => {
         if (directKillAttempted) {
@@ -148,7 +253,42 @@ function settleNativeCliTerminationCleanup(child, terminateProcessTreeImpl, obse
         timeout.unref();
         let cleanup;
         try {
-            cleanup = terminateProcessTreeImpl(childPid, () => killDirectChild(), {}, { observation, requireConfirmedCleanup });
+            cleanup = processGroup
+                ? (async () => {
+                    let processGroupError;
+                    try {
+                        await terminateNativeCliProcessGroup(childPid, killProcess);
+                    }
+                    catch (error) {
+                        processGroupError = error instanceof Error
+                            ? error
+                            : new Error('Native CLI cleanup unconfirmed: process-group cleanup rejected.');
+                    }
+                    let auditError = processTreeAuditPreparationError;
+                    if (observation) {
+                        try {
+                            await terminateProcessTreeImpl(childPid, () => killDirectChild(), {}, { observation, requireConfirmedCleanup: true });
+                        }
+                        catch (error) {
+                            auditError = error instanceof Error
+                                ? error
+                                : new Error('Native CLI cleanup unconfirmed: cleanup audit rejected.');
+                        }
+                    }
+                    if (processGroupError)
+                        throw processGroupError;
+                    if (auditError &&
+                        !(allowUnavailablePosixAudit && isPosixProcessInspectionUnavailableError(auditError))) {
+                        throw auditError;
+                    }
+                })()
+                : terminateProcessTreeImpl(childPid, () => killDirectChild(), {}, {
+                    observation,
+                    requireConfirmedCleanup,
+                    ...(allowUnobservedWindowsProcessOnNormalCompletion
+                        ? { allowUnobservedWindowsProcessOnNormalCompletion: true }
+                        : {}),
+                });
         }
         catch (error) {
             finish(error instanceof Error
@@ -180,10 +320,50 @@ export function createExecFileNativeCliRunner(dependencies = {}) {
     const observeProcessTreeImpl = dependencies.observeProcessTree ??
         (dependencies.terminateProcessTree ? undefined : observeProcessTree);
     const terminateProcessTreeImpl = dependencies.terminateProcessTree ?? terminateProcessTree;
+    const platform = dependencies.platform ?? process.platform;
+    const killProcess = dependencies.killProcess ?? process.kill;
+    const createWindowsJobInvocationImpl = dependencies.createWindowsJobInvocation;
+    const usesDefaultWindowsJob = !dependencies.execFile && !createWindowsJobInvocationImpl;
     return async (invocation) => {
         if (invocation.signal?.aborted) {
             throw createAbortedNativeCliError(invocation);
         }
+        let executableCommand = invocation.command;
+        let executableArgs = invocation.args;
+        const commandName = normalizeNativeCliCommandName(invocation.command);
+        if (platform === 'win32'
+            && (createWindowsJobInvocationImpl || usesDefaultWindowsJob)
+            && (commandName === 'claude' || commandName === 'codex')) {
+            const commandOptions = {
+                command: invocation.command,
+                cwd: invocation.cwd,
+                env: invocation.env,
+            };
+            const resolved = commandName === 'claude'
+                ? await resolveWindowsClaudeCommand(commandOptions)
+                : await resolveWindowsNpmCommand({
+                    ...commandOptions,
+                    packageName: '@openai/codex',
+                    binName: 'codex',
+                    displayName: 'Codex',
+                });
+            executableCommand = resolved.command;
+            executableArgs = [...resolved.argsPrefix, ...invocation.args];
+        }
+        const windowsJobInvocation = platform === 'win32'
+            ? createWindowsJobInvocationImpl
+                ? createWindowsJobInvocationImpl(executableCommand, executableArgs)
+                : usesDefaultWindowsJob
+                    ? createWindowsJobInvocation(executableCommand, executableArgs, {
+                        helperPath: await prepareWindowsJobHelper(),
+                    })
+                    : undefined
+            : undefined;
+        const cleanupStrategy = windowsJobInvocation
+            ? 'windows-job'
+            : platform !== 'win32'
+                ? 'process-group'
+                : isAgentNativeCliInvocation(invocation) ? 'on-demand-tree' : 'observed-tree';
         return new Promise((resolve, reject) => {
             let settled = false;
             let terminationReason;
@@ -194,15 +374,38 @@ export function createExecFileNativeCliRunner(dependencies = {}) {
             let streamedStderr = '';
             let timeout;
             let processTreeObservation;
+            let processTreeCleanup;
+            let processTreeAuditPreparationError;
+            let completionStarted = false;
+            let windowsJobCloseTimer;
             let detachOutputListeners = () => { };
             const abortListener = () => {
                 startTermination('aborted', invocation.signal?.reason);
             };
+            const cleanupProcessTree = (requireConfirmedCleanup, allowUnobservedWindowsProcessOnNormalCompletion = false, allowUnavailablePosixAudit = false, auditTrustedPosixFailure = false) => {
+                if (cleanupStrategy === 'process-group' &&
+                    (!trustedAgentCli || auditTrustedPosixFailure) &&
+                    processTreeObservation === undefined &&
+                    child.pid !== undefined) {
+                    try {
+                        processTreeObservation = observeProcessTreeImpl?.(child.pid, processMarker);
+                    }
+                    catch (error) {
+                        processTreeAuditPreparationError = new Error('Native CLI cleanup unconfirmed: POSIX process marker lookup failed.', { cause: error });
+                    }
+                }
+                processTreeCleanup ??= settleNativeCliTerminationCleanup(child, terminateProcessTreeImpl, processTreeObservation, requireConfirmedCleanup, allowUnobservedWindowsProcessOnNormalCompletion, cleanupStrategy === 'process-group', allowUnavailablePosixAudit, processTreeAuditPreparationError, killProcess);
+                return processTreeCleanup;
+            };
             const clearLifecycle = () => {
                 if (timeout) {
                     clearTimeout(timeout);
                     timeout = undefined;
                 }
+                if (windowsJobCloseTimer) {
+                    clearTimeout(windowsJobCloseTimer);
+                    windowsJobCloseTimer = undefined;
+                }
                 invocation.signal?.removeEventListener('abort', abortListener);
                 detachOutputListeners();
                 processTreeObservation?.dispose();
@@ -255,17 +458,113 @@ export function createExecFileNativeCliRunner(dependencies = {}) {
                     clearTimeout(timeout);
                     timeout = undefined;
                 }
+                if (cleanupStrategy === 'windows-job') {
+                    try {
+                        if (child.exitCode == null &&
+                            child.signalCode == null &&
+                            child.kill('SIGKILL') === false) {
+                            throw new Error('Windows Job helper did not accept termination.');
+                        }
+                    }
+                    catch (error) {
+                        finishTermination(error instanceof Error
+                            ? error
+                            : new Error('Windows Job helper termination failed.'));
+                        return;
+                    }
+                    windowsJobCloseTimer = setTimeout(() => finishTermination(new Error('Windows Job helper exit could not be confirmed.')), NATIVE_CLI_CLEANUP_TIMEOUT_MS);
+                    windowsJobCloseTimer.unref();
+                    return;
+                }
+                if (cleanupStrategy === 'on-demand-tree' && child.pid !== undefined) {
+                    try {
+                        processTreeObservation = (observeProcessTreeImpl ?? observeProcessTree)(child.pid, processMarker);
+                    }
+                    catch (error) {
+                        child.stdout?.destroy?.();
+                        child.stderr?.destroy?.();
+                        try {
+                            child.kill('SIGKILL');
+                        }
+                        catch {
+                            // The direct child can exit before fallback termination runs.
+                        }
+                        finishTermination(error instanceof Error
+                            ? error
+                            : new Error('Native CLI cleanup unconfirmed: process observation threw.'));
+                        return;
+                    }
+                }
                 Promise.resolve()
-                    .then(() => settleNativeCliTerminationCleanup(child, terminateProcessTreeImpl, processTreeObservation, (child.exitCode != null || child.signalCode != null) && callbackOutput === undefined))
+                    .then(() => cleanupProcessTree(cleanupStrategy === 'observed-tree'
+                    ? (child.exitCode != null || child.signalCode != null) && callbackOutput === undefined
+                    : true, false, false, true))
                     .then(finishTermination);
             }
+            const finishCallback = (cleanupError) => {
+                if (terminationReason)
+                    return;
+                const output = callbackOutput ?? { stdout: streamedStdout, stderr: streamedStderr };
+                const childFailed = child.exitCode != null && child.exitCode !== 0 || child.signalCode != null;
+                if (callbackError || childFailed) {
+                    const callbackExitCode = callbackError && typeof callbackError === 'object' &&
+                        typeof callbackError.code === 'number'
+                        ? callbackError.code
+                        : undefined;
+                    const exitCode = callbackExitCode !== undefined
+                        ? callbackExitCode
+                        : child.exitCode != null
+                            ? child.exitCode
+                            : isAbortLikeError(callbackError) ||
+                                isTimeoutLikeError(callbackError, invocation.timeoutMs)
+                                ? 124
+                                : 1;
+                    rejectOnce(new NativeCliError({
+                        invocation,
+                        exitCode,
+                        ...output,
+                        cause: callbackError ?? new Error(`Command exited with ${child.signalCode ?? `code ${exitCode}`}.`),
+                        cleanupError,
+                    }));
+                    return;
+                }
+                if (cleanupError) {
+                    rejectOnce(new NativeCliError({
+                        invocation,
+                        exitCode: 1,
+                        ...output,
+                        cause: cleanupError,
+                        cleanupError,
+                        reason: 'exit',
+                    }));
+                    return;
+                }
+                resolveOnce({ exitCode: 0, ...output });
+            };
+            const startCompletion = (allowUnobservedWindowsProcessOnNormalCompletion = false) => {
+                if (settled || terminationReason || completionStarted)
+                    return;
+                completionStarted = true;
+                if (timeout) {
+                    clearTimeout(timeout);
+                    timeout = undefined;
+                }
+                void cleanupProcessTree(true, allowUnobservedWindowsProcessOnNormalCompletion, platform !== 'win32' && callbackError == null &&
+                    (child.exitCode == null || child.exitCode === 0) && child.signalCode == null, platform !== 'win32' && trustedAgentCli && Boolean(callbackError
+                    || child.exitCode != null && child.exitCode !== 0
+                    || child.signalCode != null)).then(finishCallback);
+            };
             const processMarker = randomUUID();
-            child = execFileImpl(invocation.command, invocation.args, {
-                cwd: invocation.cwd,
+            const trustedAgentCli = isAgentNativeCliInvocation(invocation);
+            child = execFileImpl(windowsJobInvocation?.command ?? executableCommand, windowsJobInvocation?.args ?? executableArgs, {
+                cwd: platform === 'win32' && invocation.cwd !== undefined
+                    ? path.win32.toNamespacedPath(invocation.cwd)
+                    : invocation.cwd,
                 env: {
                     ...(invocation.env ?? process.env),
                     [NATIVE_CLI_PROCESS_MARKER_ENV]: processMarker,
                 },
+                detached: platform !== 'win32',
                 windowsHide: true,
             }, (error, stdout, stderr) => {
                 if (settled) {
@@ -274,30 +573,29 @@ export function createExecFileNativeCliRunner(dependencies = {}) {
                 callbackError = error;
                 callbackOutput = { stdout, stderr };
                 if (terminationReason) {
+                    if (cleanupStrategy === 'windows-job') {
+                        if (windowsJobCloseTimer) {
+                            clearTimeout(windowsJobCloseTimer);
+                            windowsJobCloseTimer = undefined;
+                        }
+                        finishTermination();
+                    }
                     return;
                 }
-                if (!error) {
-                    resolveOnce({
-                        exitCode: 0,
-                        stdout,
-                        stderr,
-                    });
+                if (cleanupStrategy === 'windows-job') {
+                    queueMicrotask(() => finishCallback());
                     return;
                 }
-                const exitCode = typeof error.code === 'number'
-                    ? (error.code)
-                    : isAbortLikeError(error) || isTimeoutLikeError(error, invocation.timeoutMs)
-                        ? 124
-                        : 1;
-                rejectOnce(new NativeCliError({
-                    invocation,
-                    exitCode,
-                    stdout,
-                    stderr,
-                    cause: error,
-                }));
+                if (cleanupStrategy === 'on-demand-tree') {
+                    queueMicrotask(() => finishCallback());
+                    return;
+                }
+                queueMicrotask(() => startCompletion(platform === 'win32' &&
+                    error === null &&
+                    (child.exitCode == null || child.exitCode === 0) &&
+                    child.signalCode == null));
             });
-            if (child.pid !== undefined) {
+            if (cleanupStrategy === 'observed-tree' && child.pid !== undefined) {
                 processTreeObservation = observeProcessTreeImpl?.(child.pid, processMarker);
             }
             const stdoutListener = (chunk) => {
@@ -312,6 +610,13 @@ export function createExecFileNativeCliRunner(dependencies = {}) {
                 child.stdout?.removeListener?.('data', stdoutListener);
                 child.stderr?.removeListener?.('data', stderrListener);
             };
+            if (cleanupStrategy !== 'on-demand-tree' && cleanupStrategy !== 'windows-job') {
+                child.once('exit', () => {
+                    if (!terminationReason) {
+                        startCompletion(platform === 'win32' && child.exitCode === 0 && child.signalCode == null);
+                    }
+                });
+            }
             if (invocation.timeoutMs && invocation.timeoutMs > 0) {
                 child.once('spawn', () => {
                     if (settled || terminationReason) {
@@ -337,6 +642,9 @@ function normalizeNativeCliCommandName(command) {
     return baseName.replace(/\.(?:bat|cmd|com|exe)$/u, '');
 }
 function isAgentNativeCliInvocation(invocation) {
+    if (invocation.agentKind !== undefined) {
+        return true;
+    }
     const commandName = normalizeNativeCliCommandName(invocation.command);
     return commandName === 'codex' || commandName === 'claude';
 }
@@ -372,54 +680,114 @@ export async function runNativeCli(invocation, runner) {
     const resolvedInvocation = applyAgentNativeCliDefaultTimeout(invocation);
     return (runner ?? getDefaultNativeCliRunner())(resolvedInvocation);
 }
-export function buildCodexPluginAddInvocation(pluginId, cwd, env) {
+function buildCodexInvocation(manager, args, cwd, env) {
     return {
-        command: 'codex',
-        args: ['plugin', 'add', pluginId],
+        command: manager.command,
+        args: [...manager.argsPrefix, ...args],
+        agentKind: 'codex',
         cwd,
-        env,
+        env: {
+            ...env,
+            CODEX_HOME: getCodexHome(env),
+        },
     };
 }
-export function buildCodexPluginListInvocation(cwd, env) {
-    return {
-        command: 'codex',
-        args: ['plugin', 'list'],
-        cwd,
-        env,
-    };
+export function buildCodexPluginAddInvocation(manager, pluginId, cwd, env) {
+    return buildCodexInvocation(manager, ['plugin', 'add', pluginId], cwd, env);
 }
-export function buildCodexPluginRemoveInvocation(pluginId, cwd, env) {
-    return {
-        command: 'codex',
-        args: ['plugin', 'remove', pluginId],
-        cwd,
-        env,
-    };
+export function buildCodexPluginListJsonInvocation(manager, marketplaceName, cwd, env) {
+    return buildCodexInvocation(manager, ['plugin', 'list', '--marketplace', marketplaceName, '--json'], cwd, env);
 }
-export function buildCodexMarketplaceAddInvocation(awHome, cwd, env) {
+export function buildCodexProjectPluginListInvocations(manager, options) {
     return {
-        command: 'codex',
-        args: ['plugin', 'marketplace', 'add', awHome],
-        cwd,
-        env,
+        exact: buildCodexPluginListJsonInvocation(manager, options.marketplaceName, options.exactCwd, options.env),
+        neutral: buildCodexPluginListJsonInvocation(manager, options.marketplaceName, options.neutralCwd, options.env),
     };
 }
-export function buildCodexMarketplaceListInvocation(cwd, env) {
+function readCodexPluginListEntry(value, index) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`codexPluginListInvalid: installed[${index}] must be an object.`);
+    }
+    const record = value;
+    const pluginId = record.pluginId;
+    if (typeof pluginId !== 'string'
+        || pluginId !== pluginId.trim()
+        || !/^[^@\s]+@[^@\s]+$/u.test(pluginId)) {
+        throw new Error(`codexPluginListInvalid: installed[${index}].pluginId must be an exact namespaced ID.`);
+    }
+    if (record.installed !== true) {
+        throw new Error(`codexPluginListInvalid: installed[${index}].installed must be true.`);
+    }
+    if (typeof record.enabled !== 'boolean') {
+        throw new Error(`codexPluginListInvalid: installed[${index}].enabled must be boolean.`);
+    }
+    if (record.version !== undefined && typeof record.version !== 'string') {
+        throw new Error(`codexPluginListInvalid: installed[${index}].version must be string.`);
+    }
+    const source = record.source;
+    if (source !== undefined && (!source || typeof source !== 'object' || Array.isArray(source))) {
+        throw new Error(`codexPluginListInvalid: installed[${index}].source must be an object.`);
+    }
+    const pluginPath = source && typeof source === 'object'
+        ? source.path
+        : undefined;
+    if (pluginPath !== undefined && typeof pluginPath !== 'string') {
+        throw new Error(`codexPluginListInvalid: installed[${index}].source.path must be string.`);
+    }
     return {
-        command: 'codex',
-        args: ['plugin', 'marketplace', 'list'],
-        cwd,
-        env,
+        pluginId,
+        enabled: record.enabled,
+        ...(typeof record.version === 'string' ? { version: record.version } : {}),
+        ...(typeof pluginPath === 'string' ? { path: pluginPath } : {}),
     };
 }
-export function buildCodexMarketplaceRemoveInvocation(marketplaceName, cwd, env) {
+export function parseCodexPluginListJson(stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        throw new Error('codexPluginListInvalid: Codex plugin list did not return JSON.');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('codexPluginListInvalid: expected a Codex 0.151 plugin list object.');
+    }
+    const record = value;
+    if (!Array.isArray(record.installed) || !Array.isArray(record.available)) {
+        throw new Error('codexPluginListInvalid: expected installed[] and available[].');
+    }
+    return record.installed.map(readCodexPluginListEntry);
+}
+function isCodexPluginActive(entries, pluginId) {
+    const matches = entries.filter((entry) => entry.pluginId === pluginId);
+    if (matches.length > 1) {
+        throw new Error(`codexPluginListInvalid: duplicate plugin ID ${pluginId}.`);
+    }
+    return matches.length === 1 && matches[0].enabled;
+}
+export function postcheckCodexProjectPluginActivation(options) {
+    const exactActive = isCodexPluginActive(parseCodexPluginListJson(options.exactResult.stdout), options.pluginId);
+    const neutralActive = isCodexPluginActive(parseCodexPluginListJson(options.neutralResult.stdout), options.pluginId);
+    if (exactActive !== (options.userEnabled || options.projectEnabled)
+        || neutralActive !== options.userEnabled) {
+        throw new CodexProjectConfigNotEffectiveError(options.pluginId);
+    }
     return {
-        command: 'codex',
-        args: ['plugin', 'marketplace', 'remove', marketplaceName],
-        cwd,
-        env,
+        effective: true,
+        pluginId: options.pluginId,
+        exactActive,
+        neutralActive,
     };
 }
+export function buildCodexPluginRemoveInvocation(manager, pluginId, cwd, env) {
+    return buildCodexInvocation(manager, ['plugin', 'remove', pluginId], cwd, env);
+}
+export function buildCodexMarketplaceAddInvocation(manager, awHome, cwd, env) {
+    return buildCodexInvocation(manager, ['plugin', 'marketplace', 'add', awHome], cwd, env);
+}
+export function buildCodexMarketplaceRemoveInvocation(manager, marketplaceName, cwd, env) {
+    return buildCodexInvocation(manager, ['plugin', 'marketplace', 'remove', marketplaceName], cwd, env);
+}
 export async function runNativeCliChecked(invocation, runner) {
     const result = await runNativeCli(invocation, runner);
     if (result.exitCode !== 0) {