feat(compile): introduce System phase so ado-script installs before user runtimes

ADO's NodeTool@0 prepends to PATH, so when both AdoScriptExtension (gate+import bundle, requires Node 20.x) and NodeExtension (user-pinned version) emit NodeTool@0 into the same Agent job, the LAST install wins on PATH. Previously AdoScript ran in the Tool phase, AFTER Runtime — so its hardcoded 20.x silently overrode the user's pinned version.

Introduces a new ExtensionPhase::System variant that sorts before Runtime. AdoScript moves to System: its NodeTool@0 install runs first, the resolver step uses it during a brief 20.x window, then the user's NodeExtension's NodeTool@0 runs and the user's version wins on PATH for everything after.

Adds test_node_runtime_install_orders_after_ado_script_so_user_version_wins pinning this ordering. Updates extension-count tests for the new phase. Refreshes ExtensionPhase docs and the collect_extensions ordering policy.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

src/compile/extensions/ado_script.rs

@@ -122,7 +122,15 @@ impl CompilerExtension for AdoScriptExtension {
     }
 
     fn phase(&self) -> ExtensionPhase {
-        ExtensionPhase::Tool
+        // System phase: ado-script's NodeTool@0 install + bundle download +
+        // resolver step must complete BEFORE any user-facing Runtime
+        // extension (e.g. NodeExtension) runs. Otherwise our Node 20
+        // install would prepend onto PATH after the user's pinned Node,
+        // silently overriding the user's choice for the rest of the
+        // Agent job. By running first, our install lives only during the
+        // brief window before the user's Runtime install, and the
+        // resolver step inside that window picks up our Node 20.
+        ExtensionPhase::System
     }
 
     fn setup_steps(&self, _ctx: &CompileContext) -> Result<Vec<String>> {
@@ -294,7 +302,11 @@ mod tests {
     fn name_and_phase() {
         let ext = ext_with(None, None, true);
         assert_eq!(ext.name(), "ado-script");
-        assert_eq!(ext.phase(), ExtensionPhase::Tool);
+        // System phase ensures NodeTool@0 install + bundle download +
+        // resolver run BEFORE user-facing Runtime extensions (e.g. the
+        // Node runtime), so the user's pinned Node version wins on PATH
+        // for the rest of the Agent job.
+        assert_eq!(ext.phase(), ExtensionPhase::System);
     }
 
     #[test]

src/compile/extensions/mod.rs

@@ -213,16 +213,32 @@ impl<'a> CompileContext<'a> {
 
 /// Execution phase for extension ordering.
 ///
-/// Extensions are collected and processed in phase order. Runtimes run
-/// before tools because tools may depend on runtimes (e.g., `uv` requires
-/// a Python runtime to already be installed).
+/// Extensions are collected and processed in phase order. The compiler
+/// emits steps in this order: **System → Runtime → Tool**.
+///
+/// - **System** is reserved for compiler-internal infrastructure that
+///   downstream phases assume is already in place (e.g.
+///   `AdoScriptExtension`'s prompt-file resolver). System steps emit
+///   their own self-contained tool installs and **must finish before
+///   any other phase runs**, so that later phases can override shared
+///   tool versions (notably the `node` on PATH).
+/// - **Runtime** installs language toolchains (Lean, Python, Node, etc.)
+///   for the user agent. A `NodeTool@0` here will land on top of any
+///   System-phase Node install, so the user's pinned version wins on
+///   PATH for everything after Runtime.
+/// - **Tool** is first-party tooling (azure-devops, cache-memory, …)
+///   that may depend on runtimes.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ExtensionPhase {
-    /// Language runtimes (Lean, Python, Node, etc.) — installed first.
-    Runtime = 0,
-    /// First-party tools (azure-devops, cache-memory, etc.) — may depend
-    /// on runtimes being available.
-    Tool = 1,
+    /// Compiler-internal infrastructure that everything else depends on.
+    /// Reserved for ado-aw's own extensions (e.g. ado-script). Not for
+    /// user-facing extension authors.
+    System = 0,
+    /// Language runtimes (Lean, Python, Node, etc.).
+    Runtime = 1,
+    /// First-party tools (azure-devops, cache-memory, etc.) — may
+    /// depend on runtimes being available.
+    Tool = 2,
 }
 
 /// Unified interface for runtimes and first-party tools to declare
@@ -624,9 +640,11 @@ extension_enum! {
 /// ## Ordering policy
 ///
 /// Extensions are sorted by [`ExtensionPhase`] before being returned:
-/// runtimes run before tools. This guarantees that runtime install steps
-/// execute before tool steps — critical when a tool depends on a runtime
-/// (e.g., a Python-based tool like `uv` needs the Python runtime first).
+/// **System → Runtime → Tool**. System owns compiler-internal
+/// infrastructure (ado-script bundle download + prompt resolver) that
+/// must complete before user-facing toolchains land — notably so that a
+/// later `NodeTool@0` from `NodeExtension` wins on PATH instead of
+/// being silently overridden by the System-phase Node install.
 ///
 /// Within the same phase, extensions preserve definition order
 /// (runtimes in `RuntimesConfig` field order, tools in `ToolsConfig`
@@ -641,6 +659,11 @@ pub fn collect_extensions(front_matter: &FrontMatter) -> Vec<Extension> {
     // (Setup job) and the runtime-import resolver (Agent job). Internal
     // gating on `filters:` and `inlined-imports` means the extension
     // emits no steps when neither feature is needed.
+    //
+    // Phase: `System` — so its `NodeTool@0` install + bundle download +
+    // resolver step run BEFORE any user-facing Runtime extension (e.g.
+    // `NodeExtension`). The user's pinned Node version then "wins last"
+    // on PATH for the rest of the Agent job.
     extensions.push(Extension::AdoScript(AdoScriptExtension {
         pr_filters: front_matter.pr_filters().cloned(),
         pipeline_filters: front_matter.pipeline_filters().cloned(),
@@ -696,7 +719,7 @@ pub fn collect_extensions(front_matter: &FrontMatter) -> Vec<Extension> {
     // ── Trigger filters + runtime imports are owned by AdoScriptExtension
     // pushed above; no separate trigger-filters extension push is needed.
 
-    // Enforce phase ordering: runtimes before tools.
+    // Enforce phase ordering: System → Runtime → Tool.
     // sort_by_key is stable, preserving definition order within the same phase.
     extensions.sort_by_key(|ext| ext.phase());
 

src/compile/extensions/tests.rs

@@ -101,7 +101,8 @@ fn test_collect_extensions_lean_enabled() {
             .unwrap();
     let exts = collect_extensions(&fm);
     assert_eq!(exts.len(), 4); // GitHub + SafeOutputs + ado-script + Lean
-    assert_eq!(exts[0].name(), "Lean 4"); // Runtime phase sorts first
+    assert_eq!(exts[0].name(), "ado-script"); // System phase sorts first
+    assert_eq!(exts[1].name(), "Lean 4"); // Runtime phase follows System
 }
 
 #[test]
@@ -141,24 +142,28 @@ fn test_collect_extensions_all_enabled() {
     .unwrap();
     let exts = collect_extensions(&fm);
     assert_eq!(exts.len(), 6); // GitHub + SafeOutputs + ado-script + Lean + AzureDevOps + CacheMemory
-    assert_eq!(exts[0].name(), "Lean 4"); // Runtime phase first
-    // All tool-phase extensions follow
-    assert!(exts[1..].iter().all(|e| e.phase() == ExtensionPhase::Tool));
+    assert_eq!(exts[0].name(), "ado-script"); // System phase first
+    assert_eq!(exts[1].name(), "Lean 4"); // Runtime phase next
+    // All trailing extensions are Tool phase
+    assert!(exts[2..].iter().all(|e| e.phase() == ExtensionPhase::Tool));
 }
 
 #[test]
 fn test_collect_extensions_runtimes_always_before_tools() {
-    // Verify the phase ordering policy: all Runtime-phase extensions
-    // must appear before any Tool-phase extensions, regardless of
-    // front matter field order.
+    // Verify the phase ordering policy: System → Runtime → Tool. All
+    // System-phase extensions appear first, then Runtime, then Tool —
+    // regardless of front matter field order.
     let (fm, _) = parse_markdown(
         "---\nname: test\ndescription: test\ntools:\n  azure-devops: true\n  cache-memory: true\nruntimes:\n  lean: true\n---\n",
     )
     .unwrap();
     let exts = collect_extensions(&fm);
     assert_eq!(exts.len(), 6); // GitHub + SafeOutputs + ado-script + Lean + AzureDevOps + CacheMemory
 
-    // Find the boundary: last Runtime and first Tool
+    // System sorts first
+    assert_eq!(exts[0].phase(), ExtensionPhase::System);
+
+    // Runtime extensions all sit between System and Tool
     let last_runtime_idx = exts
         .iter()
         .rposition(|e| e.phase() == ExtensionPhase::Runtime)
@@ -173,6 +178,17 @@ fn test_collect_extensions_runtimes_always_before_tools() {
         "Runtime extensions must come before Tool extensions. \
          Last runtime at index {last_runtime_idx}, first tool at index {first_tool_idx}"
     );
+
+    // System must come strictly before Runtime
+    let first_runtime_idx = exts
+        .iter()
+        .position(|e| e.phase() == ExtensionPhase::Runtime)
+        .expect("expected at least one Runtime extension");
+    assert!(
+        0 < first_runtime_idx,
+        "System extensions must come before any Runtime extension. \
+         First runtime at index {first_runtime_idx}"
+    );
 }
 
 // ── LeanExtension ──────────────────────────────────────────────

tests/compiler_tests.rs

@@ -4347,6 +4347,43 @@ fn test_neither_feature_active_emits_no_node_or_download_anywhere() {
     );
 }
 
+/// When a user pins a Node version via `runtimes.node:` AND runtime imports
+/// are active, both extensions emit `NodeTool@0` into the Agent job. ADO's
+/// `NodeTool@0` prepends to PATH, so the LAST install wins. The ado-script
+/// extension must run in the `System` phase so its Node 20.x install lands
+/// FIRST, and the user's Runtime-phase `NodeTool@0 22.x` lands second —
+/// the user's pinned version then wins on PATH for the rest of the job.
+#[test]
+fn test_node_runtime_install_orders_after_ado_script_so_user_version_wins() {
+    let yaml = compile_fixture("dedupe_node_runtime_and_imports.md");
+    let agent = extract_job_block(&yaml, "Agent").expect("Agent job should exist");
+
+    // Find offsets within the Agent block. The ado-script Node install
+    // is identifiable by its displayName; the user's runtime install
+    // carries the explicit user-pinned versionSpec.
+    let ado_script_install_idx = agent
+        .find("displayName: \"Install Node.js 20.x\"")
+        .expect("ado-script Node 20.x install step missing from Agent job");
+    let user_runtime_install_idx = agent
+        .find("'Install Node.js 22.x'")
+        .expect("user runtime Node 22.x install step missing from Agent job");
+
+    assert!(
+        ado_script_install_idx < user_runtime_install_idx,
+        "ado-script NodeTool@0 must precede user NodeTool@0 in the Agent job so the \
+         user's pinned Node version wins on PATH after both run. \
+         ado-script idx = {ado_script_install_idx}, user idx = {user_runtime_install_idx}"
+    );
+
+    // Both downloads of ado-script.zip remain unaffected (still exactly one
+    // in the Agent job in this fixture — no filters, so no Setup-side download).
+    assert_eq!(
+        yaml.matches("Download ado-aw scripts").count(),
+        1,
+        "Expected exactly one ado-script.zip download (Agent job only; no gate active)"
+    );
+}
+
 /// Tier 2 PR filter fixture produces valid YAML.
 #[test]
 fn test_pr_filter_tier2_compiled_output_is_valid_yaml() {

tests/fixtures/dedupe_node_runtime_and_imports.md

@@ -0,0 +1,11 @@
+---
+name: "Dedupe Node Runtime And Imports"
+description: "User pins Node 22 via runtime; ado-script must NOT override on PATH"
+runtimes:
+  node:
+    version: "22.x"
+---
+
+## Dedupe Node Runtime And Imports
+
+Used by `test_node_runtime_install_orders_after_ado_script_so_user_version_wins`.