feat(workflows): cloud-connect fix workflows (claude hang + utils bundling)

[khaliqgant]

Summary

Adds two agent-relay workflows under workflows/cloud-connect/ that fix regressions in agent-relay cloud connect <provider> and install regression guards so they don't reship.

• fix-cloud-connect-claude-hang.ts — agent-relay cloud connect anthropic prints "Starting interactive authentication..." and hangs. Root cause is in src/cli/lib/ssh-interactive.ts: (1) stream.on('data', ...) is registered AFTER stream.write, so bytes emitted synchronously on shell open are dropped; (2) ; exit $? wrapper races with the Ink TUI's final alternate-screen-buffer flush. The workflow extracts a pure formatShellInvocation helper, reorders the shell callback, replaces the payload with exec <cmd>, and writes vitest unit tests with a mock ssh2 Client that exercise the handler-order regression, the exec prefix, and synchronous early data capture.

• fix-agent-relay-utils-bundling.ts — npx agent-relay cloud connect openai fails with ERR_MODULE_NOT_FOUND: Cannot find package '@agent-relay/utils', but agent-relay --version / --help pass because the existing post-publish verifier never exercises a code path that imports @agent-relay/utils. bundledDependencies lists @agent-relay/utils, but at npm pack time node_modules/@agent-relay/utils is a workspace symlink and npm pack doesn't follow symlinks out of the package root, so the tarball silently ships nothing under node_modules/@agent-relay/. The workflow adds scripts/prepack-materialize-workspaces.mjs to replace those symlinks with real directories before pack, scripts/verify-bundled-deps.mjs wired into prepack + prepublishOnly as a fail-fast guard, and a new Test 6 in scripts/post-publish-verify/verify-install.sh that require.resolves @agent-relay/utils from the installed package and dynamic-imports the cloud-connect code path.

Both workflows follow the 80-100 pattern (test-fix-rerun, verify gates, typecheck, regression suite) so they stay useful as permanent regression-detection workflows, not one-shot fixers. The companion server-side fix for the openai PATH-propagation hang landed in AgentWorkforce/cloud#151.

Also unignores /workflows/cloud-connect/ in .gitignore alongside the existing ci/, refactor/, and relayauth-integration/ exceptions.

Test plan

• cd relay && agent-relay run workflows/cloud-connect/fix-cloud-connect-claude-hang.ts runs to completion with all steps green
• cd relay && agent-relay run workflows/cloud-connect/fix-agent-relay-utils-bundling.ts runs to completion with all steps green
• agent-relay cloud connect anthropic successfully opens the claude TUI instead of hanging
• npx agent-relay cloud connect openai reaches codex login without ERR_MODULE_NOT_FOUND
• Post-publish verification Test 6 fails cleanly if @agent-relay/utils is ever unresolvable from the installed package

🤖 Generated with Claude Code

---

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 4 additional findings.

[xkonjin]

Nice work on the cloud connect bundling fix. A few observations:

Potential issue in prepack-materialize-workspaces.mjs:
The script uses a mix of sync and async realpath APIs. The comment mentions using realpathSync but the code shows await import('node:fs/promises')).realpath(dst). Consider standardizing on fs.realpathSync for consistency since the rest of the script uses sync APIs.

Race condition concern in ssh-interactive.ts:
The fix moves stream event handlers before the write call, which is good. However, the timer is now started after stdin.resume() but before the stream.write(). If the remote side responds very quickly (within microseconds), the timeout might not be active yet. Consider starting the timer before or immediately alongside stdin setup.

Test coverage:
The new ssh-interactive.test.ts covers the handler-order regression well. Consider adding a test case for the timeout timer initialization order to prevent future regressions.

vitest.config.ts changes:
The new workspaceAliases approach is cleaner than the hardcoded alias list. Make sure all packages listed in workspacePackages are actually built before this config is used, or you may get resolve errors during test runs if a package has not been compiled yet.

Overall solid fix for a tricky bundling issue.

[xkonjin]

Test review

[xkonjin]

Code Review: Fix cloud connect claude hang

Overall: This is a well-structured fix for a race condition in the SSH interactive session handling. The reordering of event handlers and the switch from ; exit $? to exec pattern eliminates the data-listener race (H1) and shell-exit race (H2).

What looks good

1. Handler ordering fix: Moving stream.on('data', ...) before stream.write() is the correct fix for the race where early TUI output could be dropped before the listener attached.

2. exec pattern: Using exec <command> instead of <command>; exit $? eliminates the shell-teardown race. The PTY now closes when the CLI exits naturally.

3. Exported testable helper: formatShellInvocation is pure, simple, and directly testable. Good separation of concerns.

4. Test coverage: The new unit tests verify the handler-order regression (H1) and the shell invocation format. Mocking ssh2 is appropriate here.

Suggestions

1. Comment the handler-order invariant
Consider adding a code comment explaining why stream.on('data') must precede stream.write():

// Attach data listener BEFORE writing to avoid dropping early shell output
// that may be emitted synchronously when the shell spawns.
stream.on('data', ...);
stream.write(formatShellInvocation(command));

2. Edge case: command with shell metacharacters
formatShellInvocation blindly wraps the command. If command contains shell metacharacters (e.g., claude; rm -rf /), the behavior changes with exec. Consider whether input validation is needed upstream.

3. Verify no other callers need updating
Search for other stream.write patterns with exit $? in the codebase — the same bug may exist elsewhere in SSH-related code.

Security

No new security issues. The change eliminates a shell wrapper, which is slightly safer.

Test coverage

Good regression tests. Consider adding:

• Test for command with quotes/special characters
• Test for the timeout path (timer firing before completion)

Verdict: Approve.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 13 additional findings in Devin Review.

[devin-ai-integration]

🔴 Materializer omits bin/ directory, losing @agent-relay/sdk broker binary

The prepack-materialize-workspaces.mjs script hardcodes copying only package.json, dist/, and README.md from each symlinked workspace package. However, @agent-relay/sdk declares "files": ["dist", "bin", "README.md", "package.json"] (packages/sdk/package.json), and its bin/ directory contains the platform-specific agent-relay-broker binary (populated by the build:rust script that runs before the materializer in the prepack chain). The getBrokerBinaryPath() resolver in packages/sdk/src/broker-path.ts:68 looks for the binary at resolve(currentModuleDir, '..', 'bin') — i.e. the SDK's own bin/ directory. Because the materializer doesn't copy bin/, the bundled node_modules/@agent-relay/sdk/bin/ will be absent in the published tarball, and the primary broker binary resolution path will silently fail. The root package.json files array does not include packages/sdk/bin either, so the binary has no other packaging route into the tarball.

Suggested change

	const distSrc = join(realPath, 'dist');
	if (existsSync(distSrc)) {
	cpSync(distSrc, join(dst, 'dist'), { recursive: true });
	}
	const readmeSrc = join(realPath, 'README.md');
	if (existsSync(readmeSrc)) {
	cpSync(readmeSrc, join(dst, 'README.md'));
	}
	const distSrc = join(realPath, 'dist');
	if (existsSync(distSrc)) {
	cpSync(distSrc, join(dst, 'dist'), { recursive: true });
	}
	const binSrc = join(realPath, 'bin');
	if (existsSync(binSrc)) {
	cpSync(binSrc, join(dst, 'bin'), { recursive: true });
	}
	const readmeSrc = join(realPath, 'README.md');
	if (existsSync(readmeSrc)) {
	cpSync(readmeSrc, join(dst, 'README.md'));
	}

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[xkonjin]

Solid, well-scoped PR — the bundling fix addresses a real regression and the ssh-interactive refactor closes a race condition. Feedback below:

Bundling / packaging:

1. prepack-materialize-workspaces.mjs idempotency edge case: The script skips already-materialized dirs via .materialized marker, but if a developer runs npm install after materialization, npm may restore symlinks while the .materialized marker is still present. The next prepack would silently skip the stale real-dir. Consider checking lstatSync(dst).isSymbolicLink() even when the marker exists, or documenting that npm install after prepack requires manual git checkout node_modules/.

2. verify-bundled-deps.mjs symlink check: Good. But it only checks root-level symlinks. If node_modules/@agent-relay/utils/node_modules/.bin/ contains symlinks (common), they are irrelevant to bundledDependencies but worth keeping in mind. Not blocking.

3. Coverage thresholds: The vitest.config.ts excludes packages/cloud/src/workflows.ts, packages/cloud/src/api-client.ts, and packages/telemetry/** from coverage. Make sure these exclusions are intentional and temporary — if they're permanently dead code, consider deleting them instead.

SSH interactive / claude hang:

4. formatShellInvocation escaping bug: The implementation handles single quotes via replace(/'/g, "'\\''"), which is correct for POSIX sh -c. But it does not escape backslashes before single quotes. A command like echo 'it\'s working' would break the quoting. This is a minor edge case, but since the function is now exported and tested, consider documenting the limitation or handling \\' sequences.

5. authDetected logic change: The return expression now requires execResult?.authDetected === true and no longer falls back to exitCode === 0. This is the correct fix for the zsh exec failure case, but verify that all callers supply non-empty successPatterns — otherwise a successful auth with no pattern will now report authDetected: false. The tests show callers do supply patterns, but worth a quick audit.

6. Missing test for cleanup() on stream.error: The runInteractiveSession tests are great for the H1 race, but there's no test verifying that a stream error mid-session calls cleanup(), restores raw mode, and rejects. A future refactor could regress this. Consider adding one.

Approve with nits — the bundling and claude-hang fixes are both high-value and low-risk.