@zq-silk/yui 0.16.0 → 0.99.0

package/dist/controller/structuredProviderObservation.js

@@ -14,6 +14,33 @@ let deliveryFailure;
 // Only live diagnostics for this process's immutable files, not another queue.
 // No payload, retry, or authoritative delivery state is kept in this map.
 const emittedEvents = new Map();
+/** Retained in the existing Host Inbox; it never settles a Turn or a resource. */
+export async function publishStructuredProviderDiagnostic(input) {
+    const diagnostic = input.diagnostic;
+    const adapterId = requireIdentity(input.environment.YUI_ADAPTER_ID, "Agent adapter id");
+    const owner = describeHostIdentity(input.environment, adapterId, diagnostic.nativeSessionId);
+    const failure = diagnostic.failure;
+    await persistAndApply(input.home, [observation({
+            kind: diagnostic.attemptId === undefined ? "conversation.observed" : "observer.health",
+            sequence: nextStructuredSequence(), ordinal: 0,
+            observedAt: new Date().toISOString(),
+            fence: {
+                ...owner, driverId: builtinAgentDriverRegistry().requireByAdapterId(adapterId).id,
+                nativeSessionId: diagnostic.nativeSessionId, conversationId: diagnostic.nativeSessionId,
+                ...(diagnostic.attemptId === undefined ? {} : { receiptId: diagnostic.attemptId }),
+                ...(diagnostic.nativeTurnId === undefined ? {} : { nativeTurnId: diagnostic.nativeTurnId })
+            },
+            payload: {
+                ...(diagnostic.attemptId === undefined ? { recoverability: "unknown" } : {}),
+                sourceId: failure.phase === "host-stop" ? "host-cleanup" : "provider-channel",
+                observerStatus: "unavailable", observerDetail: failure.detail,
+                failure: { error: standardAgentError({
+                        source: "host", phase: failure.phase, message: failure.detail, raw: failure.raw ?? failure.detail,
+                        inputDisposition: failure.inputDisposition, sessionDisposition: failure.sessionDisposition
+                    }) }
+            }
+        })], input.environment);
+}
 /** A live transport observation, independent of Provider state and Run truth. */
 export function structuredProviderEventDelivery(home, environment, nativeSessionId) {
     try {

package/dist/controller/updateReconciliation.js

@@ -3,6 +3,14 @@ import { acquireHomeLifecycleLock } from "../core/controllerServer.js";
 import { cleanControllerResource } from "./resourceCleanupLinux.js";
 import { scanControllerResourceInventory } from "./resourceInventoryLinux.js";
 const MAX_RECONCILIATION_PASSES = 4;
+export class UpdateControllerReconciliationError extends Error {
+    result;
+    constructor(message, result, options) {
+        super(message, options);
+        this.result = result;
+        this.name = "UpdateControllerReconciliationError";
+    }
+}
 /**
  * Reconcile only Controller-owned resources for the Home being updated.
  *
@@ -12,21 +20,49 @@ const MAX_RECONCILIATION_PASSES = 4;
  * and inode fingerprints. Agent, tmux, app, and foreign-Home resources are
  * deliberately outside this operation.
  */
-export async function reconcileControllerResourcesForUpdate(home, environment = process.env, tmuxBin) {
+export async function reconcileControllerResourcesForUpdate(home, environment = process.env, tmuxBin, ports = {
+    scan: scanControllerResourceInventory,
+    clean: cleanControllerResource,
+    acquireLock: acquireHomeLifecycleLock
+}) {
     const resolvedHome = resolve(home);
-    const releaseLock = await acquireHomeLifecycleLock(resolvedHome, {
-        removeStaleOwner: true
-    });
     const cleaned = new Set();
-    try {
-        for (let pass = 0; pass < MAX_RECONCILIATION_PASSES; pass += 1) {
-            const snapshot = await scanControllerResourceInventory({
-                currentHome: resolvedHome,
-                scope: "current",
-                environment,
+    const attempts = [];
+    let remaining = [];
+    let observedAt;
+    let observationError;
+    let lockReleaseError;
+    const result = () => ({
+        home: resolvedHome, cleaned: [...cleaned], attempts: [...attempts], remaining: [...remaining],
+        ...(observedAt === undefined ? {} : { observedAt }),
+        ...(observationError === undefined ? {} : { observationError }),
+        ...(lockReleaseError === undefined ? {} : { lockReleaseError })
+    });
+    const scan = async () => {
+        try {
+            const snapshot = await ports.scan({
+                currentHome: resolvedHome, scope: "current", environment,
                 ...(tmuxBin === undefined ? {} : { tmuxBin })
             });
+            if (snapshot.scope === "current" && resolve(snapshot.currentHome) === resolvedHome) {
+                remaining = controllerResources(snapshot, resolvedHome);
+                observedAt = snapshot.observedAt;
+            }
             assertCertainSnapshot(snapshot, resolvedHome);
+            observationError = undefined;
+            return snapshot;
+        }
+        catch (error) {
+            observationError = messageOf(error);
+            throw error;
+        }
+    };
+    let releaseLock;
+    let failure;
+    try {
+        releaseLock = await ports.acquireLock(resolvedHome, { removeStaleOwner: true });
+        for (let pass = 0; pass < MAX_RECONCILIATION_PASSES; pass += 1) {
+            const snapshot = await scan();
             const resources = controllerResources(snapshot, resolvedHome);
             const controllers = resources.filter(({ kind }) => kind === "controller");
             const current = controllers.filter(({ state }) => state === "current");
@@ -50,36 +86,52 @@ export async function reconcileControllerResourcesForUpdate(home, environment =
             }
             const candidates = [...historicalCleanup, ...staleArtifactCleanup];
             if (candidates.length === 0) {
-                return { cleaned: [...cleaned] };
+                break;
             }
             for (const candidate of candidates) {
                 try {
-                    await cleanControllerResource(candidate, { environment, ...(tmuxBin === undefined ? {} : { tmuxBin }) });
+                    await ports.clean(candidate, { environment, ...(tmuxBin === undefined ? {} : { tmuxBin }) });
                     cleaned.add(candidate.id);
+                    attempts.push({ resource: candidate, outcome: "cleaned" });
+                    remaining = remaining.filter(({ id }) => id !== candidate.id);
                 }
                 catch (error) {
                     // A concurrent exact cleanup that already reached the desired state
                     // is harmless. Anything still present or reclassified is a real
                     // ownership change and must remain a user-visible blocker.
-                    const afterFailure = await scanControllerResourceInventory({
-                        currentHome: resolvedHome,
-                        scope: "current",
-                        environment
-                    });
-                    assertCertainSnapshot(afterFailure, resolvedHome);
+                    const attempt = { resource: candidate, outcome: "unknown", error: messageOf(error) };
+                    attempts.push(attempt);
+                    // If this observation also fails, keep BOTH failures and the exact
+                    // attempted identity. Failure to observe absence is never success.
+                    const afterFailure = await scan();
                     if (!controllerResources(afterFailure, resolvedHome).some(({ id }) => id === candidate.id)) {
                         cleaned.add(candidate.id);
+                        attempts[attempts.length - 1] = { ...attempt, outcome: "absent" };
                         continue;
                     }
                     throw reconciliationBlocked(`resource ${candidate.id} changed or could not be cleaned: ${messageOf(error)}`);
                 }
             }
+            if (pass === MAX_RECONCILIATION_PASSES - 1) {
+                throw reconciliationBlocked("Controller resources did not converge after bounded cleanup");
+            }
         }
-        throw reconciliationBlocked("Controller resources did not converge after bounded cleanup");
+    }
+    catch (error) {
+        failure = error;
     }
     finally {
-        await releaseLock();
+        try {
+            await releaseLock?.();
+        }
+        catch (error) {
+            lockReleaseError = messageOf(error);
+            failure ??= error;
+        }
     }
+    if (failure !== undefined)
+        throw new UpdateControllerReconciliationError(messageOf(failure), result(), { cause: failure });
+    return result();
 }
 function assertCertainSnapshot(snapshot, resolvedHome) {
     if (snapshot.scope !== "current"

package/dist/doctor/doctor.js

@@ -694,7 +694,8 @@ function checkAgent(agent, executor, environment) {
             detail: [
                 `start resume interrupt nativeSession=${snapshot.lifecycle.nativeSessionDiscovery}`,
                 `preInputReady=${snapshot.lifecycle.preInputReadiness.status}`,
-                `fields=${available}/${degraded}/${unavailable}`,
+                `fields(help-observed/static-or-unverified/unavailable)=${available}/${degraded}/${unavailable}`,
+                "installation/help inspection only; no model or account capability query",
                 ...snapshot.warnings.map((warning) => `warning=${warning}`)
             ].join(" ")
         }

package/dist/executor/agentAdapter.js

@@ -6,11 +6,12 @@ import { ownedArgumentsForAdapter, validateAgentAdvancedArguments, validateAgent
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { discoverAcpConfiguration, discoverClaudeConfiguration, discoverCodexConfiguration } from "./agentConfigurationProbe.js";
 import { builtinAgentDriverRegistry } from "../runtime/builtinAgentDrivers.js";
-const SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
-const APPROVALS = ["untrusted", "on-request", "never"];
+import { CODEX_SANDBOXES as SANDBOXES, CODEX_APPROVALS as APPROVALS, configurationFieldsFromHelp, configurationFieldWarnings, staticAgentConfigurationFields, STATIC_CONFIGURATION_NOTICE } from "./agentConfigurationFields.js";
 const PROBE_TIMEOUT_MS = 2_000;
 const PROBE_MAX_BYTES = 1024 * 1024;
-const CODEX_TESTED_THROUGH_VERSION = "0.150.1";
+// Offline producer/type evidence, not a claim of live account/model testing.
+// Keep the existing minimum support floors separate: see provider-protocol-contracts.md.
+const AUDITED_PRODUCER_VERSIONS = { codex: "0.153.4", claude: "2.1.270" };
 class BaseAdapter {
     launchContextArgs(_input) {
         return [];
@@ -556,7 +557,7 @@ export function inspectAgentCapabilities(agent, optionsOrNow = {}) {
     const at = now.toISOString();
     const adapter = resolveAgentAdapter(agent.adapterId);
     validateAgentBaseArguments(agent.adapterId, agent.baseArgs);
-    const versionRun = run(agent.command, ["--version"]);
+    const versionRun = run(agent.command, [...agent.baseArgs, "--version"]);
     const failure = failed(versionRun);
     if (failure !== undefined) {
         const missing = versionRun.error?.code === "ENOENT";
@@ -583,7 +584,7 @@ export function inspectAgentCapabilities(agent, optionsOrNow = {}) {
             probedAt: at
         }, fields, at, [`Installed version ${version} is not supported by adapter ${adapter.id}.`]);
     }
-    const help = run(agent.command, ["--help"]);
+    const help = run(agent.command, [...agent.baseArgs, "--help"]);
     const helpFailure = failed(help);
     if (helpFailure !== undefined) {
         return snapshot(agent, adapter, {
@@ -593,114 +594,45 @@ export function inspectAgentCapabilities(agent, optionsOrNow = {}) {
         }, fields, at);
     }
     const helpOutput = output(help.stdout, help.stderr);
-    fields = fromHelp(agent.adapterId, helpOutput);
+    const helpFields = configurationFieldsFromHelp(agent.adapterId, helpOutput);
+    fields = capabilityFields(helpFields);
+    warnings.push(...configurationFieldWarnings(helpFields));
     const missing = missingRequiredCapabilities(adapter.id, helpOutput);
     if (missing.length > 0) {
         return snapshot(agent, adapter, {
             status: "unsupported-version", command: agent.command, version,
             reason: `${adapter.label} CLI is missing required capabilities: ${missing.join(", ")}.`,
             probedAt: at
-        }, fields, at);
+        }, fields, at, warnings);
     }
-    if (adapter.id === "codex"
-        && compareVersions(version, CODEX_TESTED_THROUGH_VERSION) > 0) {
-        warnings.push(`Installed Codex version ${version} is newer than the latest tested version `
-            + `${CODEX_TESTED_THROUGH_VERSION}; required capabilities were detected.`);
+    const audited = adapter.id === "acp" ? undefined : AUDITED_PRODUCER_VERSIONS[adapter.id];
+    if (audited !== undefined && compareVersions(version, audited) > 0) {
+        warnings.push(`Installed ${adapter.label} version ${version} is newer than the latest audited producer `
+            + `${audited}; required CLI flags were detected, not live protocol compatibility.`);
     }
     return snapshot(agent, adapter, {
         status: "installed", command: agent.command, version, probedAt: at
     }, fields, at, warnings);
 }
 function baseline(id) {
-    // ACP negotiates its whole configurable surface per Session, so a static
-    // baseline can only say which axes exist — never which values one Agent
-    // accepts. Model, effort and mode are all `degraded` for exactly that reason:
-    // they are configurable and the enumeration comes from the live Session, so
-    // promising values here would be inventing them.
-    if (id === "acp")
-        return [
-            field("model", "enum", "degraded", true),
-            field("effort", "enum", "degraded", true),
-            field("permission.strategy", "enum", "available", false, ["default", "bypass", "configured"]),
-            // The exact mode ids belong to the Agent, and only a live Session lists
-            // them. `configured` carries whichever id the user names.
-            field("permission.mode", "enum", "degraded", true),
-            // Configurable, but only reaches an Agent that advertises
-            // `sessionCapabilities.additionalDirectories` at `initialize`. A static
-            // baseline cannot see that handshake, so it reports the field as degraded
-            // rather than promising delivery it cannot guarantee.
-            field("additionalDirectories", "path-list", "degraded", true)
-        ];
-    if (id === "codex")
-        return [
-            field("model", "enum", "degraded", true), field("effort", "enum", "unavailable", true),
-            field("permission.strategy", "enum", "available", false, ["default", "bypass", "configured"]),
-            field("permission.sandbox", "enum", "available", false, SANDBOXES),
-            field("permission.approval", "enum", "available", false, APPROVALS),
-            field("profile", "string", "available", true), field("search", "boolean", "available", false, ["true"]),
-            field("additionalDirectories", "path-list", "available", true)
-        ];
-    return [
-        field("model", "enum", "degraded", true, ["fable", "opus", "sonnet"]),
-        field("effort", "enum", "unavailable", true),
-        field("permission.strategy", "enum", "available", false, ["default", "bypass", "configured"]),
-        field("permission.mode", "enum", "unavailable", true),
-        field("permission.allowedTools", "string-list", "available", true),
-        field("permission.disallowedTools", "string-list", "available", true),
-        field("additionalDirectories", "path-list", "available", true), field("settingsFile", "path", "available", true),
-        field("settingsSources", "string-list", "degraded", false, ["user", "project", "local"])
-    ];
-}
-function fromHelp(id, help) {
-    const fields = baseline(id);
-    // Nothing in an ACP Agent's `--help` describes the protocol it speaks, so
-    // there is nothing here to refine: the baseline is already the whole truth.
-    if (id === "acp")
-        return fields;
-    const replacements = id === "codex"
-        ? [permissionStrategyField(help, "--dangerously-bypass-approvals-and-sandbox"),
-            choiceField("permission.sandbox", help, "--sandbox", SANDBOXES),
-            choiceField("permission.approval", help, "--ask-for-approval", APPROVALS)]
-        : [choiceField("model", help, "--model", ["fable", "opus", "sonnet"], true),
-            choiceField("effort", help, "--effort", [], true),
-            permissionStrategyField(help, "--dangerously-skip-permissions"),
-            choiceField("permission.mode", help, "--permission-mode", [], true),
-            choiceField("settingsSources", help, "--setting-sources", ["user", "project", "local"])];
-    const byKey = new Map(replacements.map((value) => [value.key, value]));
-    return fields.map((value) => byKey.get(value.key) ?? value);
-}
-function permissionStrategyField(help, bypassFlag) {
-    const choices = [
-        "default",
-        ...(help.includes(bypassFlag) ? ["bypass"] : []),
-        "configured"
-    ];
-    return field("permission.strategy", "enum", choices.includes("bypass") ? "available" : "degraded", false, choices);
-}
-function choiceField(key, help, flag, fallback, custom = false) {
-    const choices = helpChoices(help, flag);
-    return field(key, key === "settingsSources" ? "string-list" : "enum", choices.length > 0 ? "available" : fallback.length > 0 ? "degraded" : "unavailable", custom, choices.length > 0 ? choices : fallback);
-}
-function field(key, kind, status, allowCustom, choices) {
-    return { key, kind, status, allowCustom, ...(choices === undefined ? {} : { choices: [...choices] }) };
-}
-function helpChoices(help, flag) {
-    const lines = help.replace(/\r\n/g, "\n").split("\n");
-    const start = lines.findIndex((line) => line.includes(flag));
-    if (start < 0)
-        return [];
-    let end = start + 1;
-    while (end < lines.length && !/^\s{2,}(?:-[A-Za-z](?:,\s*)?|--)[\w-]/.test(lines[end]))
-        end += 1;
-    const body = /(?:\[possible values:\s*([^\]]+)\]|\(choices:\s*([^)]*)\)|\(([^)]*)\))/i
-        .exec(lines.slice(start, end).join("\n"));
-    return [...new Set((body?.[1] ?? body?.[2] ?? body?.[3] ?? "").replace(/["']/g, "").split(",")
-            .map((value) => value.trim().replace(/\.$/, "")).filter((value) => /^[\w.+-]+$/.test(value)))];
+    return capabilityFields(staticAgentConfigurationFields(id));
+}
+function capabilityFields(fields) {
+    const kinds = {
+        profile: "string", search: "boolean", additionalDirectories: "path-list", settingsFile: "path",
+        settingsSources: "string-list", "permission.allowedTools": "string-list", "permission.disallowedTools": "string-list"
+    };
+    return fields.map(field => ({
+        key: field.key, kind: kinds[field.key] ?? "enum", allowCustom: field.allowCustom,
+        status: field.available === true ? "available" : field.available === false ? "unavailable" : "degraded",
+        choices: field.choices.map(choice => choice.value)
+    }));
 }
 function snapshot(agent, adapter, installation, fields, at, warnings = []) {
     return { schemaVersion: 1, agentId: agent.id, adapterId: agent.adapterId, installation,
         lifecycle: { start: true, resume: true, nativeSessionDiscovery: adapter.capabilities.nativeSessionDiscovery,
-            interrupt: true, preInputReadiness: adapter.capabilities.preInputReadiness }, fields, warnings, refreshedAt: at };
+            interrupt: true, preInputReadiness: adapter.capabilities.preInputReadiness }, fields,
+        warnings: [...new Set([STATIC_CONFIGURATION_NOTICE, ...warnings])], refreshedAt: at };
 }
 function runProbe(command, args) {
     const result = spawnSync(command, [...args], { encoding: "utf8", shell: false, timeout: PROBE_TIMEOUT_MS,

package/dist/executor/agentConfigurationCatalog.js

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
 import { redactAgentErrorText } from "../runtime/agentError.js";
+import { staticAgentConfigurationFields, STATIC_CONFIGURATION_NOTICE } from "./agentConfigurationFields.js";
 const DEFAULT_TIMEOUT_MS = 8_000;
 export class AgentConfigurationCatalogService {
     yuiHome;
@@ -119,71 +120,14 @@ export class AgentConfigurationCatalogService {
     }
 }
 export function fallbackAgentConfigurationCatalog(agent) {
-    const choice = (value) => ({ value, label: value });
-    const common = [
-        field("model", [], true),
-        field("effort", [], true)
-    ];
-    // The fallback exists for when the probe could not run, so it must still be
-    // this Agent's own shape. Falling through to Claude's fields handed the
-    // caller a catalog whose `adapterId` contradicted the Agent it described.
-    if (agent.adapterId === "acp") {
-        return {
-            schemaVersion: 1,
-            agentId: agent.id,
-            adapterId: "acp",
-            models: [],
-            fields: [
-                ...common,
-                field("permission.strategy", [choice("default"), choice("bypass"), choice("configured")], false),
-                // The mode ids come from a live Session, so an offline catalog can only
-                // say the axis exists. Listing candidates here would invent an Agent's
-                // vocabulary from a build-time guess.
-                field("permission.mode", [], true)
-            ],
-            warnings: ["Runtime configuration catalog is unavailable."]
-        };
-    }
-    return agent.adapterId === "codex"
-        ? {
-            schemaVersion: 1,
-            agentId: agent.id,
-            adapterId: "codex",
-            models: [],
-            fields: [
-                ...common,
-                field("permission.strategy", ["default", "bypass", "configured"].map(choice), false),
-                field("permission.sandbox", [
-                    "read-only", "workspace-write", "danger-full-access"
-                ].map(choice), false),
-                field("permission.approval", [
-                    "untrusted", "on-request", "never"
-                ].map(choice), false),
-                field("search", [choice("true")], false),
-                field("profile", [], true),
-                field("additionalDirectories", [], true)
-            ],
-            warnings: ["Runtime configuration catalog is unavailable."]
-        }
-        : {
-            schemaVersion: 1,
-            agentId: agent.id,
-            adapterId: "claude",
-            models: [],
-            fields: [
-                ...common,
-                field("permission.strategy", ["default", "bypass", "configured"].map(choice), false),
-                field("permission.mode", [
-                    "acceptEdits", "auto", "bypassPermissions", "manual", "dontAsk", "plan"
-                ].map(choice), true),
-                field("permission.allowedTools", [], true),
-                field("permission.disallowedTools", [], true),
-                field("settingsSources", ["user", "project", "local"].map(choice), false),
-                field("settingsFile", [], true),
-                field("additionalDirectories", [], true)
-            ],
-            warnings: ["Runtime configuration catalog is unavailable."]
-        };
+    return {
+        schemaVersion: 1,
+        agentId: agent.id,
+        adapterId: agent.adapterId,
+        models: [],
+        fields: staticAgentConfigurationFields(agent.adapterId),
+        warnings: ["Runtime configuration catalog is unavailable.", STATIC_CONFIGURATION_NOTICE]
+    };
 }
 export function configurationField(catalog, key) {
     return catalog.fields.find((candidate) => candidate.key === key);
@@ -232,9 +176,6 @@ export function validateAgentLaunchConfiguration(catalog, config) {
             + `Inspect current options: yui config agent capabilities ${catalog.agentId}.`);
     }
 }
-function field(key, choices, allowCustom) {
-    return { key, choices, allowCustom };
-}
 function catalogFingerprint(input, environment) {
     const bindings = input.agent.environment.map((binding) => ({
         target: binding.target,
@@ -259,6 +200,10 @@ function catalogFingerprint(input, environment) {
             }
             : null;
     return createHash("sha256").update(JSON.stringify({
+        // Old derived caches may contain guessed help values. They cannot establish
+        // the current discovery contract. No durable record or cache shape changes.
+        discoveryContract: "explicit-native-enumeration",
+        agentId: input.agent.id,
         // The component, not just the plan: two ACP products answer the same
         // handshake differently, so a cache keyed on the plan alone would serve one
         // product's capabilities for the other.

package/dist/executor/agentConfigurationFields.js

@@ -0,0 +1,120 @@
+// These are Yui's accepted configuration values, not a native capability probe.
+// Keep existing explicit configuration legal; current native choices come from
+// help and requirements, and may be a smaller set.
+export const CODEX_SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
+export const CODEX_APPROVALS = ["untrusted", "on-request", "never"];
+export const STATIC_CONFIGURATION_NOTICE = "Static adapter configuration contracts are not native enumeration or proof of Provider acceptance; see field reasons.";
+export function staticAgentConfigurationFields(id) {
+    const fields = [
+        staticField("model", [], true, "Model values require native metadata; custom IDs remain explicit input."),
+        staticField("effort", [], true, "Effort values depend on the selected native model."),
+        staticField("permission.strategy", ["default", "bypass", "configured"], false, "These are Yui strategies, not Provider modes.")
+    ];
+    if (id === "codex")
+        return [
+            ...fields,
+            staticField("permission.sandbox", CODEX_SANDBOXES, false),
+            staticField("permission.approval", CODEX_APPROVALS, false, "Native versions may retire values accepted by the adapter."),
+            staticField("search", ["true"], false),
+            staticField("profile", [], true),
+            staticField("additionalDirectories", [], true)
+        ];
+    if (id === "acp")
+        return [
+            ...fields,
+            staticField("permission.mode", [], true, "Mode IDs are enumerated per Session and checked at launch."),
+            staticField("additionalDirectories", [], true, "Delivery requires the Agent's initialize capability; it is unverified offline.")
+        ];
+    return [
+        ...fields,
+        staticField("permission.mode", [], true, "No native modes were enumerated."),
+        staticField("permission.allowedTools", [], true),
+        staticField("permission.disallowedTools", [], true),
+        staticField("settingsSources", ["user", "project", "local"], false),
+        staticField("settingsFile", [], true),
+        staticField("additionalDirectories", [], true)
+    ];
+}
+function staticField(key, values, allowCustom, detail = "") {
+    return {
+        key, choices: values.map(value => ({ value, label: value })), allowCustom,
+        reason: `Static adapter configuration contract; native support is unverified.${detail ? ` ${detail}` : ""}`
+    };
+}
+/** One help interpretation shared by installation inspection and live probes. */
+export function configurationFieldsFromHelp(id, help) {
+    const fields = staticAgentConfigurationFields(id);
+    if (id === "acp")
+        return fields;
+    const bypassFlag = id === "codex"
+        ? "--dangerously-bypass-approvals-and-sandbox" : "--dangerously-skip-permissions";
+    const replacements = [
+        {
+            ...staticField("permission.strategy", [
+                "default", ...(configurationFlagAvailable(help, bypassFlag) ? ["bypass"] : []), "configured"
+            ], false),
+            reason: `Static Yui strategies; ${bypassFlag} ${configurationFlagAvailable(help, bypassFlag) ? "reported" : "not reported"} by native --help. This does not confirm account policy.`
+        },
+        ...(id === "codex"
+            ? [
+                helpChoiceField("permission.sandbox", help, "--sandbox", false, CODEX_SANDBOXES),
+                helpChoiceField("permission.approval", help, "--ask-for-approval", false, CODEX_APPROVALS)
+            ]
+            : [
+                helpChoiceField("permission.mode", help, "--permission-mode", true),
+                helpChoiceField("effort", help, "--effort", true),
+                // The CLI's description often names settings sources without an enum.
+                // Retain the explicit static contract, never relabel it as discovery.
+                ...(configurationHelpChoices(help, "--setting-sources").length === 0 ? []
+                    : [helpChoiceField("settingsSources", help, "--setting-sources", false)])
+            ])
+    ];
+    const byKey = new Map(replacements.map(value => [value.key, value]));
+    return fields.map(value => byKey.get(value.key) ?? value);
+}
+function helpChoiceField(key, help, flag, allowCustom, supported) {
+    const reported = configurationHelpChoices(help, flag);
+    const values = supported === undefined ? reported : reported.filter(value => supported.includes(value));
+    return {
+        key, choices: values.map(value => ({ value, label: value })), allowCustom,
+        available: values.length > 0,
+        reason: values.length > 0
+            ? `Native --help ${flag} enumeration${supported === undefined ? "" : ", limited to adapter-supported values"}.`
+            : `Native enumeration unavailable: ${flag} values were not reported or are not supported by this adapter.`
+    };
+}
+export function configurationFieldWarnings(fields) {
+    return [
+        STATIC_CONFIGURATION_NOTICE,
+        ...fields.filter(field => field.available === false)
+            .map(field => `${field.key}: ${field.reason ?? "Native capability unavailable."}`)
+    ];
+}
+/** Read only an explicit native enum. Prose examples and missing fields are not choices. */
+export function configurationHelpChoices(help, flag) {
+    const section = helpSection(help, flag);
+    if (section === undefined)
+        return [];
+    const inline = /(?:\[possible values:\s*([^\]]+)\]|\(choices:\s*([^)]*)\))/i.exec(section);
+    const declared = inline?.[1] ?? inline?.[2];
+    const bullets = declared === undefined && /Possible values:/i.test(section)
+        ? [...section.matchAll(/^\s*-\s*([\w.+-]+)\s*:/gm)].map(match => match[1] ?? "")
+        : [];
+    return [...new Set((declared ?? bullets.join(",")).replace(/["']/g, "").split(",")
+            .map(value => value.trim().replace(/\.$/, "")).filter(value => /^[\w.+-]+$/.test(value)))];
+}
+export function configurationFlagAvailable(help, flag) {
+    return helpSection(help, flag) !== undefined;
+}
+function helpSection(help, flag) {
+    const lines = help.replace(/\r\n/g, "\n").split("\n");
+    const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const declaration = new RegExp(`^\\s*(?:-[A-Za-z],?\\s+)?${escaped}(?=[\\s=,<\\[]|$)`);
+    const start = lines.findIndex(line => declaration.test(line));
+    if (start < 0)
+        return undefined;
+    let end = start + 1;
+    while (end < lines.length && !/^\s*(?:-[A-Za-z],?\s+|--)[\w-]/.test(lines[end]))
+        end++;
+    return lines.slice(start, end).join("\n");
+}