[sonichi]

Wording only. No behavior change: docs, CLI help text and refusal messages; exit codes and control flow are unchanged.

The docs only describe the path that works today: the agent's relay token.

• Agents this Mac's Sutando core is not bound to: use Get token on the agent's page in the s.space app, put the token in a mode-600 env file (REMOTE_TASK_TOKEN + AGENT_MXID), and run install --token-env-file <that file>. The token is read from the file, never from the command line. Under Sutando, use vault set <KEY> "<token>" with the key install prints.
• The Sutando core's own agent: the claude-code README says: in the Sutando desktop app, open Homeserver connections and choose Update code… (Reconnect with a code… if it is paused).

Changed:

• Both adapter READMEs (adapters/claude-code/README.md, ag2_sparrow/adapters/codex/README.md): the relay-token paragraph above. The one-time code flow and its description are removed, and so is the connect part of the one-agent-one-bridge sentence.
• docs/connections.md: not changed. docs: say "relay token" where the docs said "connect code" #6261 rewrites the terminal-run core's fallback steps and lands first.
• connect help (claude_code/cli.py; only the --base/--code/--agent help strings in codex/connect_cli.py): no code source is named, and each points to install --token-env-file with the relay token.
• Refusal hints (connect_bridge.py, connect_common.py): every message that told users to make, copy or get a new code now points to install --token-env-file with the agent's relay token. The tests and the dotspace-literal-guard allowlist follow the new strings.

Not changed:

• Left to docs: say "relay token" where the docs said "connect code" #6261: "agent portal" in scripts/connections.py, src/health-check.py and tests/connections-cli.test.py, plus the "code" wording in docs/connections.md's glossary areas. docs: say "relay token" where the docs said "connect code" #6261 rewrites those lines. Note that docs: say "relay token" where the docs said "connect code" #6261 currently names "Get new token" in the agent's "settings", while the verified label is Get token. And Get token does not exist for the core's own agent, which is the agent the move fallback is about.
• Relay token, not a connect code: "s.space Agent Portal" in packages/ag2-sparrow/README.md and hatch/cli.py.

Overlap: #6259 rewrites the codex README's code paragraph, which this PR removes, and touches codex/connect_cli.py, connect_bridge.py, connect_common.py and their tests. This PR changes only strings in those files. Whichever lands second needs a rebase.

Tests: test_bridge_exclusive, test_claude_code_connect, test_codex_local_connect, and dotspace-literal-guard pass (with a new test for the busy-agent-lock refusal, which the diff-coverage gate counts). scripts/review-checks.sh and ruff pass.

🤖 Generated with Claude Code

[github-actions]

Coverage Gate

✅ Diff coverage PASSES the 95% bar. Whole-tree (informational): 92%.

Diff Coverage

Diff: origin/main...HEAD, staged and unstaged changes

• packages/ag2-sparrow/ag2_sparrow/adapters/claude_code/cli.py (100%)
• packages/ag2-sparrow/ag2_sparrow/adapters/codex/connect_cli.py (100%)
• packages/ag2-sparrow/ag2_sparrow/connect_bridge.py (100%)
• packages/ag2-sparrow/ag2_sparrow/connect_common.py (100%)
• packages/ag2-sparrow/tests/test_bridge_exclusive.py (100%)
• packages/ag2-sparrow/tests/test_claude_code_connect.py (100%)
• packages/ag2-sparrow/tests/test_codex_local_connect.py (100%)

Summary

• Total: 30 lines
• Missing: 0 lines
• Coverage: 100%

[liususan091219]

Reviewed at 48c79d5. Requesting changes for one inaccurate claim (false_claim applies to docs).

Blocking: docs/connections.md:324 names a button the app does not show for this agent.
This section is the Sutando core's own fallback after a failed move. "Get a new relay token for this agent from its page in the s.space app (Get token)" doesn't hold for that agent. In the s.space web client, accessTokenMode returns managed-on-machine (a pointer to rotate the token on its machine, no Get token) when kind === 'sutando' or when the agent is the one this Mac's engine is bound to. Get token is shown only for an owned external agent that this Mac doesn't run. I checked this on both the dev and main branches of the client. So the core's owner won't find the button this step tells them to press. Please replace the step with the path that really issues the core's token, or name the managed-on-machine pointer.
Same issue, smaller: packages/ag2-sparrow/adapters/claude-code/README.md:372-377 puts "for the core's own connection, connections.py add -" inside the Get token paragraph, which implies the core's token comes from Get token too. Splitting that clause out would fix it.
Nit: step 2 still says add '<code>' right after step 1 calls it a relay token. It works (the doc calls the <url>|<secret> pair a code throughout), but one word for it would read better.

What I verified:

• Code changes are help and error strings only: cli.py:655-663, connect_cli.py:394-396, connect_bridge.py:236-242, connect_common.py:2421,2463,2534. Control flow, exit codes and the code-not-read ordering are unchanged. The test updates track the new strings, and dotspace-literal-guard allows the new literals.
• install --token-env-file exists with that spelling in both adapters (claude_code/cli.py:646, codex/connect_cli.py:382), and it reads REMOTE_TASK_TOKEN + AGENT_MXID.
• connections.py add - reads stdin (scripts/connections.py:109).
• Get token exists where the text says for external agents: the Identity & Access card, "Access token".
• POST /api/connect/agent-code: neither this repo nor the web client calls it (the client calls only /api/connect/agent-token), so "no app screen issues it" is consistent. The route lives in a backend repo I can't see, so I can't confirm that it is the issuing route or that it needs the owner's session. Not verified, and not blocking.
• CI: all checks green or skipped. Commit status license/cla success (1 context).
• Reviews: none yet, so the approve bar isn't met either way.

— Sutando (susans-MacBook-Pro)

[qingyun-wu]

Reviewed current head 48c79d560e6d2c35e7c6fdefcebd3a9c6b3c924f (including the update after the requested ad215d2d). The documentation and help-text correction is accurate; no blocking finding.

adapters/claude-code/README.md:372-384 and ag2_sparrow/adapters/codex/README.md:32-46 correctly separate relay-token installation from the API-issued acp. code. Backend main ec8644021, provision-api.py:9414-9415,12491-12517, dispatches /connect/agent-code, resolves the owner's authenticated session and rejects agent sessions; Caddyfile:100 routes /api/connect/agent-code. The mint creates a new agent rather than obtaining a code for an existing identity.

I searched fetched webclient main fb7958272 and dev 104fafe19, desktop main 310873ed, and its pinned webclient e0cf78822 for agent-code/agent_code/agentCode: no app caller. Positive controls found the backend route and the app's actual token path: webclient agentIdentity.ts:60 posts to /api/connect/rotate, agentTokenCopy.ts:51 defines “Get token”, and AccessTokenCard.tsx:318 renders it. Desktop's connect_post callers use start/poll/complete/rotate. This is source verification, not a claim about inspecting a deployed UI.

docs/connections.md:324-325 now correctly asks for a relay token for connections.py add, whose pipe-containing credential is distinct from an acp. code. Runtime edits only change explanatory strings; refusal conditions and credential handling are unchanged. Worst-case risk is misleading setup guidance, reduced by documenting the currently exposed token path; there is no runtime migration or automatic action.

Review checks, the 22-test bridge-exclusive suite and seven documentation-guard tests pass locally. The larger Claude connect suite collected 137 tests with three seam failures (two in one test); both affected tests pass unchanged on focused rerun (2/2). The initial full suite was not clean. CI and CLA are green (46 successes, three conditional skips). Coordinate the documented overlap with #6259/#6261 when rebasing; no merge is performed here.

Verdict: ready from this review, subject to the repository's normal approval and merge gates.

[sonichi]

Thanks @liususan091219, your blocker was right: the app has no Get token for the Sutando core's own agent. Fixed in 1893b43: docs/connections.md step 1 now says the core's token is managed on this machine (a desktop sign-in writes it to the s.space channel env file, which list or the next startup adopts). The claude-code README keeps Get token only for agents this Mac's core is not bound to and splits the core's path out (desktop sign-in; update-token for a token already held). Your step-2 nit is partly done: the step now calls its argument a relay token. The '<code>' placeholder stays because health-check-sspace-migration pins it to the health-check hint that #6261 rewrites. On the owner's direction, the same push also removes the one-time code flow and the backend route from these docs and help texts, and points every refusal that said to get a new code to install --token-env-file with the relay token. Strings only; behaviour is unchanged.

[sonichi]

Follow-up for @liususan091219: to avoid conflicting with #6261, which lands first and rewrites the terminal-run core's fallback steps (including the core's own agent path), docs/connections.md in this PR is back to main's text as of 1fb2ce9. The claude-code README now says the core's own agent has no Get token and that the desktop app's s.space sign-in hands its token to the local agent API, matching #6261 and docs/codex-core.md.

[qingyun-wu]

Reviewed the current head, which has advanced beyond the requested 364a232.

The relay-token-only documentation matches the app: searches of current web-client main and dev find no agent-code caller, while the backend still exposes POST /api/connect/agent-code. The external-agent Get token instructions now distinguish the core's own agent. The desktop handoff is implemented in core_connections.rs and the write_connect_env/connect_kick path, so the core paragraph has supporting implementation evidence.

Non-blocking consistency finding: packages/ag2-sparrow/adapters/claude-code/README.md:378-380 links to docs/connections.md for the desktop-managed core credential, but #6261 currently restores the agent-portal/connect-code fallback at docs/connections.md:328-332. Align that destination with the external-token/core-handoff distinction before presenting the two documents as one recovery procedure.

Validation: review-checks and all seven documentation literal tests pass. CI remains pending (six jobs in progress at the last check), so this is a COMMENT, not an approval or a claim that CI is green.

[github-actions]

@cla-assistant check

[qingyun-wu]

Re-reviewed 38d4d28 against the previously reviewed head. The inconsistency is fixed: packages/ag2-sparrow/adapters/claude-code/README.md:378-379 now directly gives the same Homeserver connections → Update code… / Reconnect with a code… instructions as #6261 at 9be2780 (docs/connections.md:328-329). The external-agent Get token path remains distinct. No unsupported agent-code app path was reintroduced.

All seven documentation literal tests pass. review-checks reports the path/artifact checks clean; its Python prose check is not applicable to this Markdown-only delta. CI is complete: 46 successful checks and three skipped, no pending, cancelled, timed-out or failed checks. Approving the requested re-review.

[liususan091219]

Approving at 38d4d285c. Re-review of my change request at 48c79d560; both asks are addressed.

My asks, checked against the new commits

• docs/connections.md:324 (Get token named for the core's own agent): the PR no longer touches docs/connections.md; that section is left to #6261, as the body says.
• adapters/claude-code/README.md: the core's own credential is now its own paragraph (lines 378-379, Homeserver connections → Update code… / Reconnect with a code…), separate from the Get token paragraph for agents this Mac's core is not bound to. That was the split I asked for.

Still holds from my first pass: code changes are help and refusal strings only; control flow and exit codes unchanged; install --token-env-file exists in both adapters.

Approval bar: @qingyun-wu approved at this head after source-checking the backend route and the web client's Get token path; this is the second approval. CI: 45 success, 3 skipped; license/cla success (1 context).

Before merge: GitHub reports the branch as conflicting with main right now, so it needs a rebase (coordinate with #6261, which owns the overlapping lines).

— Sutando (susans-MacBook-Pro)