Overview

Adds a coder_script_order resource that lets templates declare ordering dependencies between coder_script resources across modules, and enforces them in the agent so a script waits for its declared predecessors before running. The ordering is also recorded in the unit graph so it shows up in coder exp sync timeline.

Target HCL:

coder_script_order "startup" {
  rule {
    run   = [coder_script.install.id]
    after = [coder_script.clone.id]
    state = "completes" # or "starts"
  }
}

A rule means: every script in run waits for every script in after to reach state ("completes" -> completed, "starts" -> started; default completes). Multiple coder_script_order blocks are additive.

This is the new tip of the sync-units stack (#27149 → #27150 → #27152 → #27153 → #27154 → this).

How it works (end to end)

• proto: ScriptDependency {resource_address, required_status} added to provisionersdk Script and to the agent WorkspaceAgentScript.
• provisioner (provisioner/terraform/resources.go): a new pass over coder_script_order resources resolves each rule's run/after coder_script.<name>.id references to the scripts' Terraform resource_address and records dependencies on the referenced run scripts. Unknown references and invalid state values are rejected with a clear error.
• database: dependencies are stored denormalized as a jsonb column on workspace_agent_scripts (migration 000544). The agent consumes them by resource address, which avoids a UUID join table and insert-order resolution.
• provisionerdserver / manifest / SDK: dependencies are persisted on insert and threaded back out through the agent manifest and codersdk.
• agent (agent/agentscripts): each script is registered as a sync unit, the declared ordering edges are added, and run() gates execution by waiting until the script's unit is ready. unit.Manager gains WaitUntilReady (broadcast-based) for this.

Design notes

• Fail-open timeout: a script waits for its dependencies bounded by a timeout (default 5m). On timeout it logs a warning and runs anyway, so a stuck or missing dependency cannot hang workspace startup forever. Missing/typo references resolve to an unregistered unit that never becomes ready and therefore hit this path.
• "starts" state matches the dependency's status exactly. If a dependency advances started → completed before the dependent re-checks, a "starts" dependency can be momentarily unsatisfied; the fail-open timeout mitigates this. "completes" is the default and common case.
• REST omits dependencies: db2sdk.go's WorkspaceAgentScript was intentionally left unchanged. The agent manifest is the only consumer of this field; it is not part of the REST workspace-agent representation.
• Cron/repeat scripts: a completed unit that re-runs flips back to started, briefly making dependents "not ready". Acceptable for startup ordering.

Cross-repo dependency

The provisioner keys off the coder_script_order type name in Terraform state, so parsing is developed and tested here against tfjson/inline ConvertState fixtures. End-to-end CI that runs real Terraform needs the resource in the pinned provider, so full green depends on the companion terraform-provider-coder PR being released and a provider version bump. Kept as a draft until then.

Tests

• agent/unit: WaitUntilReady (ready, blocks-then-unblocks, ctx cancel, unregistered).
• agent/agentscripts: edges added from manifest, unmet dependency waits then unblocks, timeout fail-open.
• provisioner/terraform: coder_script_order → Dependencies (completes/starts/invalid/unknown reference).
• coderd/provisionerdserver + coderd/agentapi + codersdk/agentsdk: round-trip of dependencies through DB, manifest, and proto conversion.

Generated by Coder Agents on behalf of @SasSwart.