@zq-silk/yui 0.15.7 → 0.15.9

package/dist/execution/workItemMainRun.js

@@ -0,0 +1,141 @@
+import { isDeepStrictEqual } from "node:util";
+import { enqueueRoleRunDispatch } from "../coordination/workMailboxQueue.js";
+import { createRunInput } from "../context/runInputContract.js";
+import { contextSnapshotDeltaRefIds, freezeRunContextSnapshot } from "../context/runContextPack.js";
+import { contextSnapshotRef } from "../context/contextSnapshot.js";
+import { roleAgentSessionResumeMode } from "../executor/agentExecutor.js";
+import { resolveEffectiveLaunch } from "../executor/effectiveLaunch.js";
+import { createTaskEvent } from "../event/taskEvent.js";
+import { createRun } from "../agentRun/agentRun.js";
+import { currentWorkItemExecutionGroup } from "../workItem/workItem.js";
+export function selectedWorkItemSynthesisProducers(store, item, group, sourceRunIds) {
+    if (sourceRunIds.length === 0 || new Set(sourceRunIds).size !== sourceRunIds.length) {
+        throw new Error("Synthesis requires explicit, distinct source AgentRun references.");
+    }
+    return sourceRunIds.map((runId) => {
+        const run = store.getRun(item.taskId, runId);
+        const lane = group.lanes.find(({ id }) => id === run?.executionLaneId);
+        if (run === null
+            || lane === undefined
+            || !["completed", "failed"].includes(run.status)
+            || run.purpose !== "execution"
+            || run.workItemId !== item.id
+            || run.executionGroupId !== group.id
+            || run.executionLaneId !== lane.id
+            || run.roleName !== lane.roleName
+            || run.result === undefined) {
+            throw new Error(`Synthesis source is not an exact terminal Producer result: ${group.id}/${runId}.`);
+        }
+        return {
+            laneId: lane.id,
+            roleName: lane.roleName,
+            runId: run.id
+        };
+    });
+}
+/** Called within the caller's transaction after Task authority is checked. */
+export function dispatchWorkItemSynthesis(store, taskId, workItemId, sourceRunIds, now) {
+    const task = store.getTask(taskId);
+    if (task === null || task.status !== "active" || task.executionGate.state !== "enabled") {
+        throw new Error(`Task execution is not enabled: ${taskId}.`);
+    }
+    const item = store.getWorkItem(taskId, workItemId);
+    if (item === null || item.status !== "open") {
+        throw new Error(`WorkItem is not open: ${taskId}/${workItemId}.`);
+    }
+    const group = currentWorkItemExecutionGroup(item);
+    if (group === undefined)
+        throw new Error(`WorkItem has no ExecutionGroup: ${item.id}.`);
+    const producers = selectedWorkItemSynthesisProducers(store, item, group, sourceRunIds);
+    const existing = store.listRuns(taskId).some((run) => (run.purpose === "execution"
+        && run.workItemId === item.id
+        && run.sourceExecutionGroupId === group.id));
+    if (existing)
+        throw new Error(`Synthesis already exists for ${group.id}; retry its AgentRun explicitly.`);
+    if (item.assignee === undefined) {
+        throw new Error(`Replicated WorkItem has no main assignee: ${item.id}.`);
+    }
+    const role = store.getRole(taskId, item.assignee);
+    if (role === null)
+        throw new Error(`WorkItem main Role is missing: ${taskId}/${item.assignee}.`);
+    if (store.getActiveRun(taskId, role.name) !== null) {
+        throw new Error(`WorkItem main Role already has an active AgentRun: ${role.name}.`);
+    }
+    const workspace = role.name === "leader"
+        ? store.getTaskWorkspace(taskId)
+        : store.getWorkItemWorkspace(taskId, item.id);
+    if (workspace === null) {
+        throw new Error(`WorkItem main workspace is missing: ${taskId}/${item.id}.`);
+    }
+    const visibleProjectIds = workspace.entries.map(({ projectId }) => projectId).sort();
+    const taskProjectIds = task.projectBindings.map(({ projectId }) => projectId).sort();
+    const writableProjectIds = workspace.entries
+        .filter(({ access }) => access === "write")
+        .map(({ projectId }) => projectId)
+        .sort();
+    if (!isDeepStrictEqual(visibleProjectIds, taskProjectIds)
+        || !isDeepStrictEqual(writableProjectIds, [...item.writeProjectIds].sort())) {
+        throw new Error(`WorkItem main workspace does not match its approved scope: ${item.id}.`);
+    }
+    const effective = resolveEffectiveLaunch({
+        role,
+        purpose: "execution",
+        workspace,
+        workItemWriteProjectIds: item.writeProjectIds
+    });
+    const snapshot = freezeRunContextSnapshot(store, {
+        taskId,
+        roleName: role.name,
+        purpose: "execution",
+        workItemId: item.id,
+        sourceExecutionGroupId: group.id,
+        workspace
+    }, now, "leader", group.assignment.contextSnapshotRef, sourceRunIds);
+    const run = createRun(store.nextRunId(taskId), taskId, role.name, roleAgentSessionResumeMode(store.getTaskRoleSessionSet(taskId, role.name), effective.agentId, effective), createRunInput({
+        source: { type: "yui", channel: "workitem-dispatch" },
+        directive: synthesisDirective(group, producers),
+        contextSnapshotRef: contextSnapshotRef(snapshot),
+        deltaRefIds: contextSnapshotDeltaRefIds(store, snapshot)
+    }), now, {
+        workItemId: item.id,
+        sourceExecutionGroupId: group.id,
+        workspace,
+        effective
+    });
+    store.saveRun(run);
+    store.saveActiveRun(run);
+    enqueueRoleRunDispatch(store, {
+        taskId,
+        roleName: role.name,
+        runId: run.id,
+        reason: "workitem-synthesis-ready",
+        occurredAt: now
+    });
+    store.saveEvent(taskId, createTaskEvent(store.nextEventId(taskId), taskId, "run.dispatched", {
+        runId: run.id,
+        role: run.roleName,
+        purpose: run.purpose,
+        mode: run.mode,
+        agent: `${run.effective.agentId}/${run.effective.adapterId}`,
+        component: run.effective.component,
+        effectiveRevision: String(run.effective.sourceDesiredRevision),
+        profileAccess: run.effective.profileAccess,
+        effectivePermission: run.effective.permission.strategy,
+        writeProjectIds: run.effective.writeProjectIds.join(",") || "none",
+        workItemId: item.id,
+        sourceExecutionGroupId: group.id
+    }, now));
+    return run;
+}
+function synthesisDirective(group, producers) {
+    return [
+        "Synthesize the explicitly selected Producer results in the supplied order.",
+        "Expand each exact source AgentRun from the frozen Context Snapshot and consume its original result text plus Core-authored system evidence.",
+        "Do not rerun, retry, append, or abandon any Lane. Form the final WorkItem result from these records.",
+        JSON.stringify({
+            schemaVersion: 1,
+            sourceExecutionGroupId: group.id,
+            producers
+        }, null, 2)
+    ].join("\n\n");
+}

package/dist/executor/agentAdapter.js

@@ -1,10 +1,10 @@
 import { spawnSync } from "node:child_process";
 import { realpathSync, statSync } from "node:fs";
 import { isAbsolute, resolve } from "node:path";
-import { supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
+import { isAgentAdapterId, supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
 import { ownedArgumentsForAdapter, validateAgentAdvancedArguments, validateAgentBaseArguments } from "../agent/argumentPolicy.js";
 import { writeTextFileAtomically } from "../storage/durableFile.js";
-import { discoverClaudeConfiguration, discoverCodexConfiguration } from "./agentConfigurationProbe.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"];
@@ -61,6 +61,17 @@ class CodexAdapter extends BaseAdapter {
     discoverConfiguration(input) {
         return discoverCodexConfiguration(input);
     }
+    compileNew(input) {
+        const launch = super.compileNew(input);
+        const developerInstructions = codexSessionInstructions(input);
+        return {
+            ...launch,
+            codexThread: {
+                ...codexThreadOptions(input, this.canonicalizeConfig(input.config)),
+                ...(developerInstructions === undefined ? {} : { developerInstructions })
+            }
+        };
+    }
     validateStructured(config) {
         exact(config, ["adapterId", "model", "effort", "permission", "search", "profile",
             "additionalDirectories", "advanced"], "Codex Agent config");
@@ -125,23 +136,13 @@ class CodexAdapter extends BaseAdapter {
             "--config",
             `projects={${JSON.stringify(resolve(input.workspace))}={trust_level="trusted"}}`
         ];
-        const instructions = input.sessionManifestPath === undefined ? [
-            input.developerInstructions,
-            ...(input.skills === undefined || input.skills.length === 0
-                ? []
-                : [
-                    "Yui Role Skills are available at the paths below. Before performing work governed by one, read and follow its SKILL.md on demand; do not treat this list as a user message.",
-                    ...input.skills.map((skill) => `- ${skill.id}: ${skill.path}/SKILL.md`)
-                ])
-        ].filter((value) => value !== undefined && value.trim().length > 0) : [
-            `Yui managed Session. Read and follow the Session Manifest at ${input.sessionManifestPath} (digest ${input.sessionManifestDigest ?? "unknown"}). Load each Skill and Role Profile by its manifest path before acting; Task content is available only through the manifest's exact Context API.`
-        ];
-        if (instructions.length === 0)
+        const instructions = codexSessionInstructions(input);
+        if (instructions === undefined)
             return workspaceTrust;
         return [
             ...workspaceTrust,
             "--config",
-            `developer_instructions=${tomlString(instructions.join("\n"))}`
+            `developer_instructions=${tomlString(instructions)}`
         ];
     }
     compileResume(input) {
@@ -261,6 +262,7 @@ class ClaudeAdapter extends BaseAdapter {
             input.developerInstructions,
             ...(input.skills ?? []).map((skill) => [
                 `# Yui Skill: ${skill.id}`,
+                `Source: ${skill.path}/SKILL.md (resolve relative links from this directory).`,
                 skill.content
             ].join("\n\n"))
         ].filter((value) => value !== undefined && value.trim().length > 0);
@@ -300,6 +302,150 @@ class ClaudeAdapter extends BaseAdapter {
         };
     }
 }
+/**
+ * The Agent Client Protocol adapter.
+ *
+ * One adapter serves every ACP Agent. It deliberately compiles no arguments of
+ * its own: entering ACP mode is a per-product invocation detail that belongs in
+ * the Agent descriptor's `baseArgs`, and everything after startup is negotiated
+ * over the protocol. Adding a second ACP product therefore requires a new
+ * descriptor and no new code here.
+ */
+class AcpAdapter extends BaseAdapter {
+    id = "acp";
+    label = "Agent Client Protocol";
+    // The protocol version Yui implements. ACP Agents are versioned
+    // independently of their products, and `initialize` negotiates the real
+    // version at connect time, so no product's release number belongs here.
+    supportedVersion = "0.0.0";
+    capabilities = {
+        recover: true,
+        interrupt: true,
+        // ACP assigns the Session id in its `session/new` response.
+        nativeSessionDiscovery: "runtime",
+        preInputReadiness: driverPreInputReadiness("acp")
+    };
+    discoverConfiguration(input) {
+        return discoverAcpConfiguration(input);
+    }
+    validateStructured(config) {
+        exact(config, ["adapterId", "model", "effort", "permission", "additionalDirectories",
+            "settingsFile", "settingsSources", "advanced"], "ACP Agent config");
+        if (config.adapterId !== "acp")
+            throw new Error("ACP Agent config adapter is invalid.");
+        // Model and effort are session config options in ACP, so a value is legal
+        // here whatever this build knows about the product. Whether the Agent
+        // actually offers it is decided by the live option list at launch: the
+        // protocol enumerates the accepted values, and only that enumeration can
+        // answer it. Rejecting an unrecognised name here would require Yui to hold
+        // a model list per product, which is the fabricated authority this design
+        // avoids.
+        optionalText(config.model, "ACP model");
+        optionalText(config.effort, "ACP effort");
+        if (config.settingsFile !== undefined || config.settingsSources !== undefined) {
+            throw new Error("Yui's ACP client exposes no client-side settings configuration.");
+        }
+        // `additionalDirectories` is a real ACP session-lifecycle field, so a
+        // Project-backed workspace is configurable here. Whether it is actually
+        // sent is decided per connection: ACP requires Clients to send it only to
+        // an Agent that advertised `sessionCapabilities.additionalDirectories`, and
+        // only the live handshake knows that. Rejecting it here instead would make
+        // every multi-root Project launch fail before the Agent is even asked.
+        validatePaths(config.additionalDirectories, "ACP additional directory");
+        if (config.permission === undefined) {
+            throw new Error("ACP permission strategy is required.");
+        }
+        // `configured` carries the one mode id the user named; the other two
+        // strategies carry nothing, so an extra field would mean a caller expected a
+        // value this adapter never reads.
+        if (config.permission.strategy === "configured") {
+            exact(config.permission, ["strategy", "mode"], "ACP permission config");
+            // The mode is matched by exact id against what the Agent offers at launch.
+            // Yui keeps no per-product mode list, so any non-empty id is accepted here
+            // and verified there.
+            requireOneText(config.permission.mode, "ACP permission mode");
+        }
+        else {
+            exact(config.permission, ["strategy"], "ACP permission config");
+            if (config.permission.strategy !== "default" && config.permission.strategy !== "bypass") {
+                throw new Error("ACP permission strategy is invalid.");
+            }
+        }
+        advanced(this.id, config.advanced);
+    }
+    structuredArgs(_config) {
+        return [];
+    }
+    compileResume(input) {
+        // Reattaching is a `session/load` call inside the protocol, not a flag.
+        nativeId(input.nativeSessionId);
+        return this.compileNew(input);
+    }
+    compileManagedControl(input, _mode, _nativeSessionId) {
+        const config = this.canonicalizeConfig(input.config);
+        const bootstrap = acpSessionBootstrap(input);
+        const directories = config.additionalDirectories ?? [];
+        // What the Role asked for, in the form the Session applies. Only stated
+        // fields travel: an absent model is a request for the Agent's own default,
+        // and `default` permission deliberately sends no mode at all.
+        const desired = {
+            ...(config.model === undefined ? {} : { model: config.model }),
+            ...(config.effort === undefined ? {} : { effort: config.effort }),
+            ...(config.permission.strategy === "configured"
+                ? { permissionMode: config.permission.mode }
+                : config.permission.strategy === "bypass"
+                    ? { permissionBypass: true }
+                    : {})
+        };
+        const hasDesired = Object.keys(desired).length > 0;
+        return {
+            ...this.compileNew(input),
+            transport: "acp-stdio",
+            // ACP accepts no Yui flags, so everything a managed Session needs travels
+            // as protocol input. Omit the key entirely when there is nothing to say.
+            ...(directories.length === 0 && bootstrap === undefined && !hasDesired ? {} : {
+                acpSession: {
+                    ...(directories.length === 0 ? {} : { additionalDirectories: [...directories] }),
+                    ...(bootstrap === undefined ? {} : { sessionBootstrap: bootstrap }),
+                    ...(hasDesired ? { desiredConfiguration: desired } : {})
+                }
+            })
+        };
+    }
+}
+/**
+ * The instructions a managed ACP Session must read before it acts.
+ *
+ * ACP defines no system prompt and no equivalent of `--append-system-prompt`,
+ * so unlike Codex and Claude this text cannot be delivered at launch. It is
+ * carried to the Session and prepended to the first prompt instead. The
+ * manifest form stays a pointer rather than an inlined Task: content is read
+ * through the manifest's own Context API, exactly as the other adapters do.
+ */
+function acpSessionBootstrap(input) {
+    const sections = input.sessionManifestPath === undefined
+        ? [
+            input.developerInstructions,
+            ...(input.skills === undefined || input.skills.length === 0 ? [] : [
+                [
+                    "Yui Role Skills are available at the paths below. Before performing work "
+                        + "governed by one, read and follow its SKILL.md on demand; do not treat "
+                        + "this list as a user message.",
+                    ...input.skills.map((skill) => `- ${skill.id}: ${skill.path}/SKILL.md`)
+                ].join("\n")
+            ])
+        ]
+        : [
+            `Yui managed Session. Read and follow the Session Manifest at `
+                + `${input.sessionManifestPath} (digest ${input.sessionManifestDigest ?? "unknown"}). `
+                + "Load each Skill and Role Profile by its manifest path before acting; Task "
+                + "content is available only through the manifest's exact Context API."
+        ];
+    const bootstrap = sections
+        .filter((value) => value !== undefined && value.trim().length > 0)
+        .join("\n\n");
+    return bootstrap.length === 0 ? undefined : bootstrap;
+}
 function driverPreInputReadiness(adapterId) {
     const capability = builtinAgentDriverRegistry().requireByAdapterId(adapterId)
         .capabilities.observation.preInputReadiness;
@@ -316,7 +462,7 @@ function driverPreInputReadiness(adapterId) {
         });
 }
 const ADAPTERS = {
-    codex: new CodexAdapter(), claude: new ClaudeAdapter()
+    codex: new CodexAdapter(), claude: new ClaudeAdapter(), acp: new AcpAdapter()
 };
 function tomlString(value) {
     if (value.includes("\0"))
@@ -354,6 +500,19 @@ function codexThreadOptions(input, config) {
         ...(Object.keys(threadConfig).length === 0 ? {} : { config: threadConfig })
     };
 }
+function codexSessionInstructions(input) {
+    if (input.sessionManifestPath !== undefined) {
+        return `Yui managed Session. Read and follow the Session Manifest at ${input.sessionManifestPath} (digest ${input.sessionManifestDigest ?? "unknown"}). Load each Skill and Role Profile by its manifest path before acting; Task content is available only through the manifest's exact Context API.`;
+    }
+    const instructions = [
+        input.developerInstructions,
+        ...(input.skills === undefined || input.skills.length === 0 ? [] : [
+            "Yui Role Skills are available at the paths below. Before performing work governed by one, read and follow its SKILL.md on demand; do not treat this list as a user message.",
+            ...input.skills.map((skill) => `- ${skill.id}: ${skill.path}/SKILL.md`)
+        ])
+    ].filter((value) => value !== undefined && value.trim().length > 0);
+    return instructions.length === 0 ? undefined : instructions.join("\n");
+}
 function withoutCodexConfigOverride(argv, key) {
     const filtered = [];
     for (let index = 0; index < argv.length; index += 1) {
@@ -379,7 +538,10 @@ function sessionTitle(value) {
 }
 export { supportedAgentAdapterIds };
 export function findAgentAdapter(id) {
-    return id === "codex" || id === "claude" ? ADAPTERS[id] : null;
+    // `ADAPTERS` is keyed by the catalog, so it already answers this question.
+    // A second name list here would strand a catalogued adapter that has a real
+    // implementation sitting one line above.
+    return isAgentAdapterId(id) ? ADAPTERS[id] : null;
 }
 export function resolveAgentAdapter(id) {
     const adapter = findAgentAdapter(id);
@@ -450,6 +612,25 @@ export function inspectAgentCapabilities(agent, optionsOrNow = {}) {
     }, 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),
@@ -472,6 +653,10 @@ function baseline(id) {
 }
 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),
@@ -549,6 +734,12 @@ function compareVersions(leftVersion, rightVersion) {
     return 0;
 }
 function missingRequiredCapabilities(id, help) {
+    // An ACP Agent declares its capabilities in the `initialize` handshake, not
+    // in `--help`. Demanding Claude's flags of it reported a working Agent as a
+    // broken one, so ACP is required to expose no flags at all here; the real
+    // check is `discoverAcpConfiguration`, which speaks the protocol.
+    if (id === "acp")
+        return [];
     const required = id === "codex"
         ? [
             [/(?:^|\s)--config(?:\s|[=<,]|$)/m, "--config"],
@@ -572,6 +763,12 @@ function missingRequiredCapabilities(id, help) {
 }
 function cloneConfig(config, paths) {
     const advancedConfig = config.advanced?.rawArgs === undefined ? config.advanced : { rawArgs: [...config.advanced.rawArgs] };
+    if (config.adapterId === "acp") {
+        return { ...config,
+            permission: { ...config.permission },
+            ...(paths === undefined ? {} : { additionalDirectories: [...paths] }),
+            ...(advancedConfig === undefined ? {} : { advanced: advancedConfig }) };
+    }
     if (config.adapterId === "codex")
         return { ...config,
             permission: { ...config.permission },
@@ -588,9 +785,15 @@ function cloneConfig(config, paths) {
         ...(advancedConfig === undefined ? {} : { advanced: advancedConfig }) };
 }
 export function defaultRoleAgentConfig(adapterId) {
-    return adapterId === "codex"
-        ? { adapterId: "codex", permission: { strategy: "bypass" } }
-        : { adapterId: "claude", permission: { strategy: "bypass" } };
+    // Keyed by adapter, not a codex/else ternary: defaulting an unrecognized
+    // adapter to Claude's shape produced a config whose `adapterId` disagreed
+    // with the binding it was created for.
+    //
+    // ACP defaults to `default` rather than `bypass` because Yui answers ACP
+    // permission requests itself, and the answer it must never invent is "yes".
+    return adapterId === "acp"
+        ? { adapterId: "acp", permission: { strategy: "default" } }
+        : { adapterId, permission: { strategy: "bypass" } };
 }
 function validateSimplePermissionStrategy(value, label) {
     if (value !== "default" && value !== "bypass") {
@@ -638,6 +841,10 @@ function optionalText(value, label) {
     if (value !== undefined)
         text(value, label);
 }
+/** A required non-empty single-line value. */
+function requireOneText(value, label) {
+    text(value, label);
+}
 function optionalTexts(values, label) {
     if (values === undefined)
         return;

package/dist/executor/agentConfigurationCatalog.js

@@ -104,6 +104,26 @@ export function fallbackAgentConfigurationCatalog(agent) {
         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,
@@ -183,9 +203,15 @@ function catalogFingerprint(input, environment) {
         sourceName: binding.sourceName,
         value: environment[binding.sourceName] ?? null
     }));
-    const nativeRoot = input.agent.adapterId === "codex"
-        ? environment.CODEX_HOME ?? join(environment.HOME ?? homedir(), ".codex")
-        : environment.CLAUDE_CONFIG_DIR ?? join(environment.HOME ?? homedir(), ".claude");
+    // Which directory an ACP Agent keeps its own state in is that product's
+    // business, not the protocol's. Fingerprinting it against Claude's config
+    // root made unrelated Claude edits invalidate this cache; the executable
+    // path below is the honest identity for an Agent Yui only speaks to.
+    const nativeRoot = input.agent.adapterId === "acp"
+        ? null
+        : input.agent.adapterId === "codex"
+            ? environment.CODEX_HOME ?? join(environment.HOME ?? homedir(), ".codex")
+            : environment.CLAUDE_CONFIG_DIR ?? join(environment.HOME ?? homedir(), ".claude");
     const context = input.config?.adapterId === "codex"
         ? { profile: input.config.profile ?? null }
         : input.config?.adapterId === "claude"
@@ -195,6 +221,10 @@ function catalogFingerprint(input, environment) {
             }
             : null;
     return createHash("sha256").update(JSON.stringify({
+        // 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.
+        component: input.agent.component,
         adapterId: input.agent.adapterId,
         command: input.agent.command,
         baseArgs: input.agent.baseArgs,
@@ -239,7 +269,6 @@ function validateCatalog(value, agent) {
         || value.agentId !== agent.id
         || value.adapterId !== agent.adapterId
         || !Array.isArray(value.models)
-        || value.models.length === 0
         || !Array.isArray(value.fields)
         || !Array.isArray(value.warnings)) {
         throw new Error("Agent configuration model catalog is incomplete.");
@@ -248,6 +277,9 @@ function validateCatalog(value, agent) {
     unique(models.map(({ value: model }) => model), "model");
     const fields = value.fields.map(validateField);
     unique(fields.map(({ key }) => key), "configuration field");
+    if (models.length === 0 && !modelAxisIsAccountedFor(fields)) {
+        throw new Error("Agent configuration model catalog is incomplete.");
+    }
     const warnings = value.warnings.map((warning) => text(warning, "catalog warning"));
     return {
         schemaVersion: 1,
@@ -255,11 +287,101 @@ function validateCatalog(value, agent) {
         adapterId: agent.adapterId,
         ...(typeof value.cliVersion === "string"
             ? { cliVersion: text(value.cliVersion, "CLI version") } : {}),
+        // Carried through rather than dropped. This is the only record of what the
+        // Agent on the other end actually agreed to, and for a plan whose products
+        // are interchangeable it is the one fact that tells them apart. Rebuilding
+        // the catalog without it silently erased the probe's answer on both the
+        // live path and the cache read-back, leaving every consumer unable to
+        // distinguish "negotiated nothing" from "never asked".
+        ...(value.handshake === undefined
+            ? {}
+            : { handshake: validateHandshake(value.handshake) }),
         models,
         fields,
         warnings
     };
 }
+/**
+ * Whether an empty model list is an answer or a failure.
+ *
+ * Emptiness alone does not distinguish the two, so the `model` field's own
+ * contract decides. `available` is the field that carries a probe's explicit
+ * statement about an axis, and only a probe that states it has said anything
+ * about what an empty list means:
+ *
+ * - `available: false` — the axis does not exist for this Agent, and `reason`
+ *   says why. Nothing to enumerate.
+ * - `available: true` — the axis exists and its values are deliberately
+ *   enumerated later, with `allowCustom` letting a value be named before Yui has
+ *   the list. This is ACP: models live in the `configOptions` a Session returns,
+ *   so listing them at probe time would mean opening a real, possibly billed
+ *   Session to populate a menu. The probe reports the axis, defers the values,
+ *   and the configured model is verified against the Agent's own list at launch.
+ * - absent — the probe made no claim, which is the Codex and Claude shape. Those
+ *   probes enumerate models into the top-level `models` array on success, so an
+ *   empty array there means `model list` failed or returned nothing usable, and
+ *   the catalog really is incomplete.
+ *
+ * So an unstated `available` with no models stays a rejection, which is what
+ * keeps a genuinely broken Codex or Claude discovery from passing as an answer.
+ *
+ * The earlier form of this check accepted only the first case. It therefore
+ * rejected a valid ACP catalog and replaced it with the fallback, discarding the
+ * live handshake and the probe's own reasons — the failure mode the
+ * `available`/`reason` pair exists to prevent.
+ */
+function modelAxisIsAccountedFor(fields) {
+    const model = fields.find(({ key }) => key === "model");
+    if (model === undefined)
+        return false;
+    if (model.available === undefined)
+        return model.choices.length > 0;
+    // Stated either way, the field itself explains the empty list.
+    return true;
+}
+/**
+ * A handshake observation, kept in whichever of its three states it arrived in.
+ *
+ * Absence is meaningful and is preserved by the caller: it means no live
+ * connection produced this catalog. The two present states are distinguished
+ * here rather than merged, because `unsupported` ("this plan negotiates
+ * nothing") and an `observed` result with empty capabilities ("the Agent
+ * answered, and advertised none") are different answers that would otherwise
+ * be indistinguishable. An unrecognised status is rejected instead of being
+ * coerced into either one.
+ */
+function validateHandshake(value) {
+    if (!record(value))
+        throw new Error("Agent handshake observation is invalid.");
+    if (value.status === "unsupported") {
+        return {
+            status: "unsupported",
+            reason: text(value.reason, "handshake reason")
+        };
+    }
+    if (value.status !== "observed") {
+        throw new Error(`Agent handshake status is unsupported: ${String(value.status)}.`);
+    }
+    if (!Number.isSafeInteger(value.protocolVersion)) {
+        throw new Error("Agent handshake protocol version is invalid.");
+    }
+    const capabilities = array(value.capabilities, "handshake capabilities")
+        .map((capability) => text(capability, "handshake capability"));
+    unique(capabilities, "handshake capability");
+    const authMethods = array(value.authMethods, "handshake authentication methods")
+        .map((method) => text(method, "handshake authentication method"));
+    unique(authMethods, "handshake authentication method");
+    return {
+        status: "observed",
+        protocolVersion: value.protocolVersion,
+        // `unknown` is a real answer here — the Agent connected but did not name
+        // itself — so it is stored as given and never replaced by a guess.
+        agentName: text(value.agentName, "handshake Agent name"),
+        agentVersion: text(value.agentVersion, "handshake Agent version"),
+        capabilities: [...capabilities].sort(),
+        authMethods: [...authMethods].sort()
+    };
+}
 function validateModel(value) {
     if (!record(value) || typeof value.isDefault !== "boolean" || !Array.isArray(value.efforts)) {
         throw new Error("Agent configuration model entry is invalid.");