From e81267945abc04887f3ea68f6525c36d97b0a4e9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 2 Aug 2026 12:22:54 +0800
Subject: [PATCH] docs(host): refresh the stale agentFor resume-on-miss comment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The commands entry's inline comment described the old routing shape
("clients only send a sessionId for a published session") without the
ownership fence that agentFor now applies on every path — the fence's
contract home is the api/commands.ts module JSDoc, so trim the duplicate
and point at the routing shape only, keeping one home per fact.
---
 packages/host/apiproxy/src/api-proxy.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/packages/host/apiproxy/src/api-proxy.ts b/packages/host/apiproxy/src/api-proxy.ts
index 501390e488..0827762a8a 100644
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -1202,13 +1202,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
           ? undefined
           : (await persistence.list()).find(header => header.id === sessionId)
         if (persistence !== undefined && stored !== undefined) {
-          if (stored.cwd !== cwd) {
-            throw new SessionCwdConflict(sessionId, cwd, stored.cwd)
-          }
           const inspected = await persistence.inspect(sessionId)
+          // Ownership first: explicit-id adoption of a session-backed
+          // subagent must answer `agent-busy` regardless of the requested
+          // cwd (the api/commands.ts contract), not a cwd conflict.
           if (hasSubagentOwner({ header: inspected.meta, events: inspected.events }, undefined)) {
             throw new SubagentSessionOwnership(sessionId)
           }
+          if (inspected.meta.cwd !== cwd) {
+            throw new SessionCwdConflict(sessionId, cwd, inspected.meta.cwd)
+          }
           return (await ctx.agents.resume({
             resumeSessionId: sessionId,
             agentOptions,