[BobbyHo]

TL;DR

Both Agent Relay modules start the worker as soon as the workspace agent runs its start scripts, which can be before the template has cloned a repository or installed tools. The fix is a coder_script_order rule beside the module call, but neither README said so, and the module cannot declare the rule itself. This PR adds a "Start the worker after your setup" section to both READMEs, with the rule, its requirements and what happens when setup fails, and bumps both modules to 1.0.1. No Terraform changes.

Refs https://linear.app/codercom/issue/RELAY-67/start-the-cursor-worker-only-after-the-workspace-agent-is-ready

How to navigate this PR

• Docs only. Two READMEs change and nothing else.
• Reading order:
  1. registry/coder/modules/agent-relay-cursor/README.md: the new section after Requirements, the extra sentence on the repo-scoped pools bullet, and the version pins.
  2. registry/coder/modules/agent-relay-claude-code/README.md: the same section with the runner's names, and the version pins.
• Check that the rule in each section is the one the Coder docs show, with the module's own name in run.

Implementation

• Both READMEs gain a "Start the worker after your setup" (Cursor) or "Start the runner after your setup" (Claude Code) section after Requirements. It explains why the start step cannot wait on its own, shows a coder_script plus a coder_script_order rule, and lists five notes: the Coder and provider versions, that startup_script cannot be ordered, what requires = "success" and "completion" do with a failed setup, the 15-minute limit on pending, and that a cli_binary wrapper is not needed.
• The Cursor section's wrapper note also says why a wrapper is a trap: the status script recognises the worker by the binary's basename, so a wrapper not named agent reads as orphaned. The Claude Code status script checks liveness by pid only, so its note stops at "not needed".
• The Cursor "Repo-scoped pools" bullet now ends with a link to the new section.
• Both sections link the example templates in the Agent Relay repository under example/templates, added in coder/agent-relay#157. The link resolves once that PR merges, so this PR should land after it, or the link can be dropped from the first release.
• Version pins in every example block move from 1.0.0 to 1.0.1 in both READMEs. main.tf is untouched, so 1.0.1 behaves exactly like 1.0.0.
• The "three ordered startup steps" sentence under Scripts and logs is unchanged. That ordering is between the module's own steps and is not what the new section is about.

Expected Output

• A template author who copies the section's block gets a worker that starts only after coder_script.setup finishes.
• With the default requires, a failed setup skips the module's scripts, the worker never starts, and Agent Relay fails the session about a minute after the agent reports the failure (coder/agent-relay#155).
• With requires = "completion", the worker starts even when setup fails.
• On Coder older than 2.39.0 or provider older than 2.20.0, the rule is ignored without an error and the worker starts right away.
• A workspace whose setup keeps the start step pending for 15 minutes is deleted by Agent Relay.
• registry.coder.com shows the new section on both module pages after the 1.0.1 release.

Testing

• bun x prettier --check on both READMEs passes.
• go build ./cmd/readmevalidation && ./readmevalidation passes.
• .github/scripts/version-bump.sh --ci patch origin/main passes, so the pins match a patch bump.
• No Terraform or test changes, so main.tftest.hcl and main.test.ts are unchanged and were not rerun.

[linear-code]

RELAY-67

[github-actions]

Module Scorecard Check

coder/agent-relay-claude-code: 63 → 70

✅ Score improvement: 63 → 70 (+7).

Theme	Before	After
Presentation & Onboarding	6 / 17	12 / 17
Integration	10 / 25	10 / 25
Credential Hygiene	20 / 20	20 / 20
Restricted-Environment	12 / 20	12 / 20
Engineering Quality	10 / 10	10 / 10
Overall	63 / 100	70 / 100

Full scorecard for this PR

Presentation & Onboarding	Agent Integration	Credential Hygiene	Restricted-Environment Readiness	Engineering Quality	Overall
12 / 17	10 / 25	20 / 20	12 / 20	10 / 10	70 / 100

Drilldown

Presentation & Onboarding — 12 / 17

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README documents multiple modes with defaults: default install (install_cli = true), bake-into-image (install_cli = false + cli_binary), additional_args, release_idle_session_min override, health_port override, and the required coder_script_order setup example. Each is paired with a working snippet.
Visual preview	5	0	No image, GIF, or video anywhere in README.

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	The work-order JWT never becomes a Terraform input/parameter by design — it arrives as an agent-injected ephemeral workspace secret (SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET), explicitly kept out of parameters/state ("Parameters" section, main.tf comments). No module variable carries a secret, and no inline secrets appear in any README example.
Non-hardcoded auth path	4	4	README's "Requirements" section documents the ephemeral-secret delivery path as the only supported auth path, explicitly warning against the old agent_relay_credential parameter approach.

Restricted-Environment Readiness — 12 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	5	0	install.sh.tftpl hardcodes curl https://claude.ai/install.sh -fsSL | bash. No module variable overrides this download URL; cli_binary only overrides the binary path/name, not the install source.
Bring-your-own binary	10	10	install_cli = false is a first-class, thoroughly documented path ("Bake the CLI into the image and set this to false for faster workspaces"), with cli_binary to point at a custom location, and tests confirm the skip-install behavior.
Egress transparency	3	0	No dedicated network/offline/air-gapped section. The install URL only appears inside the install.sh.tftpl script comments, not in a README section enumerating endpoints.
Runs without sudo	2	2	All scripts (cleanup.sh.tftpl, install.sh.tftpl, start.sh.tftpl, status.sh.tftpl, session_attached.sh.tftpl) run as the invoking user with no sudo calls anywhere.

Engineering Quality — 10 / 10

Criterion	Max	Score	Notes
Input quality	6	6	Every variable has a clear description and sensible default; several have validation blocks (cli_binary regex, exit_if_unused_min, release_idle_session_min bounds, health_port range, additional_args reserved-flag and newline checks).
Test coverage	4	4	main.tftest.hcl covers parameter contract and rendering logic extensively (20+ runs); main.test.ts runs real container end-to-end scenarios (install skip/download, lifecycle states, cleanup races, stale PID handling, idle release, additional_args injection).

Agent Integration — 10 / 25

Criterion	Max	Score	Notes
AI governance	10	0	No mention of Coder AI Gateway or Agent Firewall anywhere in the README; the module integrates with Anthropic's own Agent Relay instead, which is a separate product concern.
Dashboard entry point	5	0	No coder_app resource or documented dashboard entry point. README explicitly advises against exposing the health port via coder_app ("Do not publish health_port through a coder_app").
Session continuity	5	5	"Idle session release" section explicitly documents session continuity: a released session "parks server-side" and "resumes on a fresh runner on the user's next message."
Managed configuration	5	5	base_dir variable is a documented, configurable workdir setting ("Directory the runner checks sessions out under... Created at start"), satisfying the workdir-config form of this criterion.

Overall — 70 / 100

Raw 64 / 92 → round(64 / 92 × 100) = 70

coder/agent-relay-cursor: 59 → 74

✅ Score improvement: 59 → 74 (+15).

Theme	Before	After
Presentation & Onboarding	6 / 17	12 / 17
Integration	5 / 25	12.5 / 25
Credential Hygiene	20 / 20	20 / 20
Restricted-Environment	13.5 / 20	13.5 / 20
Engineering Quality	10 / 10	10 / 10
Overall	59 / 100	74 / 100

Full scorecard for this PR

Presentation & Onboarding	Agent Integration	Credential Hygiene	Restricted-Environment Readiness	Engineering Quality	Overall
12 / 17	12.5 / 25	20 / 20	13.5 / 20	10 / 10	74 / 100

Drilldown

Presentation & Onboarding — 12 / 17

Criterion	Max	Score	Notes
Configuration-mode examples	12	12	README documents the major modes with examples: basic module call with install_cli, additional_args, management_addr, computer_use/share_desktop (in Requirements), and script ordering via coder_script_order. Each has sensible defaults and a concrete Terraform snippet.
Visual preview	5	0	No image, GIF, or video embedded in the README. Only an icon reference (../../../../.icons/cursor.svg), which does not count.

Credential Hygiene — 20 / 20

Criterion	Max	Score	Notes
Secrets marked sensitive	16	16	The worker token is never a module input or build parameter. Agent Relay delivers it as an ephemeral workspace secret injected as AGENT_RELAY_CURSOR_TOKEN, written to a 0600 file, and passed via --auth-token-file. README examples contain no inline secrets. The module has no secret inputs to mark sensitive = true because none exist by construction.
Non-hardcoded auth path	4	4	README documents the full non-hardcoded path: service-account API key stays in Agent Relay, Cursor mints a session token per claim, relay sends it as an ephemeral workspace secret, module writes it to a file and uses --auth-token-file. No raw keys in templates.

Restricted-Environment Readiness — 13.5 / 20

Criterion	Max	Score	Notes
Mirrorable artifact source	5	0	The CLI download URL https://cursor.com/install is hardcoded in install.sh.tftpl. No module input variable overrides this URL. install_cli only toggles the download; cli_binary overrides the binary path, not the download source. No variable can point the install at an internal mirror.
Bring-your-own binary	10	10	install_cli = false is documented as the way to disable download entirely when the CLI is baked into the image ("Bake the CLI into the image and set this to false for faster workspaces"). The install step is a no-op when the binary is already on PATH.
Egress transparency	3	1.5	No dedicated network/offline/air-gapped README section. Endpoints (cursor.com/install, cursor.com/agents/<id>, cursor:// deeplink) are scattered across Requirements and examples. Per the anchor, at most half.
Runs without sudo	2	2	All scripts (cleanup.sh.tftpl, install.sh.tftpl, start.sh.tftpl, status.sh.tftpl, session_attached.sh.tftpl) run as the unprivileged agent user and never invoke sudo. Verified from source.

Engineering Quality — 10 / 10

Criterion	Max	Score	Notes
Input quality	6	6	Inputs have clear descriptions, sensible defaults, and validation: cli_binary (regex), management_addr (regex + port range), additional_args (non-empty, no newlines, reserved-flag rejection), share_desktop (requires computer_use), serving_log_pattern (non-empty).
Test coverage	4	4	main.tftest.hcl covers the parameter contract, script rendering, and business logic (dispatched detection, flag wiring, validation failures). main.test.ts exercises end-to-end behavior in throwaway containers with a stub agent binary, covering supervisor lifecycle, pid reuse, SIGKILL escalation, and generation fencing.

Agent Integration — 12.5 / 25

Criterion	Max	Score	Notes
AI governance	10	5	Agent Relay (Coder's AI Gateway for agents) is documented: auth via service-account API key and per-claim session tokens, routing via pool dispatch, and policy via the parameter contract and reaping. Agent Firewall is not mentioned anywhere. Exactly one of the two documented → half.
Dashboard entry point	5	5	coder_app resources for "Open in Cursor Web" and "Open in Cursor Desktop" are built in and documented, with the conditional behavior (no buttons for hand-created workspaces) explained.
Session continuity	5	2.5	The idle-release timeout keeps the worker connected after a session ends, waiting for a follow-up, which is documented. However, the README does not document resuming sessions across reconnects or a persistent session manager (tmux/screen/boo); on agent restart the cleanup actually stops the previous worker. Partial.
Managed configuration	5	0	No documented support for managed MCP, settings, policies, or workdir config. additional_args is a raw passthrough, not managed configuration.

Overall — 74 / 100

Raw 68 / 92 → round(68 / 92 × 100) = 74

Tip

You can run this locally by telling your agent: "review this module against .github/scorecard/SCORECARD.md".

---

Scored against SCORECARD.md with solstice-1. Language-model scores are advisory.

[BobbyHo]

/coder-agents-review Please limit the review to P0, P1, and P2 issues only.