fix(compile): enforce ADO build-number rules for pipeline_agent_name (#576)

* fix(compile): sanitize build-number pipeline agent name marker

Agent-Logs-Url: https://github.com/githubnext/ado-aw/sessions/3a09eb36-5df5-4c49-a3c8-da542bb240d1

Co-authored-by: jamesadevine <4742697+jamesadevine@users.noreply.github.com>

* fix(tests): update lock pipeline names for sanitized build-number marker

Agent-Logs-Url: https://github.com/githubnext/ado-aw/sessions/3a09eb36-5df5-4c49-a3c8-da542bb240d1

Co-authored-by: jamesadevine <4742697+jamesadevine@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jamesadevine <4742697+jamesadevine@users.noreply.github.com>

Author: Copilot

docs/template-markers.md

@@ -105,7 +105,7 @@ have not been validated against YAML scalar rules.
 > ⚠️ This marker is only safe inside a position that is **not parsed as
 > YAML** (currently only `src/data/threat-analysis.md`, which is a
 > markdown body). YAML positions inside the generated pipelines use
-> [`{{ pipeline_name }}`](#-pipeline_name-) (top-level `name:` line)
+> [`{{ pipeline_agent_name }}`](#-pipeline_agent_name-) (top-level `name:` line)
 > or [`{{ agent_display_name }}`](#-agent_display_name-)
 > (`displayName:` positions). Both emit a fully-quoted-and-escaped
 > double-quoted YAML scalar, so colons, embedded `"`, and other
@@ -129,24 +129,27 @@ For an agent named `My "special": agent`, this expands to:
 Used in `src/data/1es-base.yml` (1ES stage display name) and
 `src/data/stage-base.yml` (stage-target stage display name). The marker
 deliberately does **not** include the `-$(BuildID)` suffix that
-[`{{ pipeline_name }}`](#-pipeline_name-) carries — stage labels are
+[`{{ pipeline_agent_name }}`](#-pipeline_agent_name-) carries — stage labels are
 static and don't need per-run uniqueness.
 
-## {{ pipeline_name }}
+## {{ pipeline_agent_name }}
 
-Should be replaced with the front-matter agent name plus the
-`-$(BuildID)` suffix, always emitted as a **YAML double-quoted scalar**
-with the same escaping rules as `{{ agent_display_name }}`. Used only
-for the top-level pipeline `name:` line, which in Azure DevOps is the
-build-number format string. The `-$(BuildID)` suffix is the
+Should be replaced with a sanitized front-matter agent name plus the
+`-$(BuildID)` suffix, emitted as a **YAML double-quoted scalar**. Used
+only for the top-level pipeline `name:` line, which in Azure DevOps is
+the build-number format string. The marker strips build-number-invalid
+characters (`"`, `/`, `:`, `<`, `>`, `\`, `|`, `?`, `@`, `*`), trims
+trailing `.` from the name fragment, and enforces the 255-character
+build-number limit when combined with the `-$(BuildID)` suffix. The
+suffix is the
 [varying token ADO requires](https://learn.microsoft.com/azure/devops/pipelines/process/run-number)
 to give each run a unique display name in the runs view; without it,
 every run shows the same name.
 
 For an agent named `Daily safe-output smoke: noop`, this expands to:
 
 ```yaml
-name: "Daily safe-output smoke: noop-$(BuildID)"
+name: "Daily safe-output smoke noop-$(BuildID)"
 ```
 
 `$(BuildID)` is an ADO macro and is expanded at queue time after YAML

src/compile/common.rs

@@ -996,6 +996,40 @@ pub fn sanitize_filename(name: &str) -> String {
         .join("-")
 }
 
+const ADO_BUILD_NUMBER_MAX_LEN: usize = 255;
+const ADO_BUILD_ID_SUFFIX: &str = "-$(BuildID)";
+
+/// Sanitize front-matter agent name for ADO build-number format strings.
+///
+/// Rules enforced:
+/// - Remove characters disallowed by Azure DevOps build numbers:
+///   `"`, `/`, `:`, `<`, `>`, `\`, `|`, `?`, `@`, `*`
+/// - Trim leading/trailing whitespace
+/// - Ensure the resulting build number format (`<name>-$(BuildID)`) fits in 255 chars
+/// - Ensure the name fragment does not end with `.`
+fn sanitize_pipeline_agent_name(name: &str) -> String {
+    let mut sanitized = String::with_capacity(name.len());
+    for ch in name.trim().chars() {
+        if matches!(ch, '"' | '/' | ':' | '<' | '>' | '\\' | '|' | '?' | '@' | '*') {
+            continue;
+        }
+        sanitized.push(ch);
+    }
+
+    let mut sanitized = sanitized.trim().trim_end_matches('.').to_string();
+    let max_agent_len = ADO_BUILD_NUMBER_MAX_LEN.saturating_sub(ADO_BUILD_ID_SUFFIX.len());
+    if sanitized.chars().count() > max_agent_len {
+        sanitized = sanitized.chars().take(max_agent_len).collect();
+        sanitized = sanitized.trim_end_matches('.').to_string();
+    }
+
+    if sanitized.is_empty() {
+        "pipeline".to_string()
+    } else {
+        sanitized
+    }
+}
+
 /// Emit `s` as a YAML double-quoted scalar (always quoted, never plain).
 ///
 /// We always quote because the value is substituted into YAML positions
@@ -2894,12 +2928,15 @@ pub async fn compile_shared(
     let checkout_self = generate_checkout_self();
     let agent_name = sanitize_filename(&front_matter.name);
     // Top-level pipeline `name:` value (the ADO build-number format).
-    // Always quoted so colons / embedded `"` in the agent name can't
-    // break parsing. Includes `-$(BuildID)` because ADO needs a varying
-    // token in the build-number format — without one, every run shows
-    // the same name in the runs view.
-    let pipeline_name =
-        yaml_double_quoted(&format!("{}-$(BuildID)", front_matter.name));
+    // We sanitize invalid build-number characters from the agent name and
+    // always quote the final scalar for YAML safety. Includes `-$(BuildID)`
+    // because ADO needs a varying token in the build-number format —
+    // without one, every run shows the same name in the runs view.
+    let pipeline_name = yaml_double_quoted(&format!(
+        "{}{}",
+        sanitize_pipeline_agent_name(&front_matter.name),
+        ADO_BUILD_ID_SUFFIX
+    ));
     // Stage / job `displayName:` value. Always quoted (same escaping
     // rationale as `pipeline_name`) but with NO BuildID suffix — stage
     // labels are static and shouldn't carry per-run uniqueness suffixes.
@@ -3118,6 +3155,9 @@ pub async fn compile_shared(
         ("{{ agent }}", &agent_name),
         ("{{ agent_name }}", &front_matter.name),
         ("{{ agent_display_name }}", &agent_display_name),
+        ("{{ pipeline_agent_name }}", &pipeline_name),
+        // Backward-compatible alias for templates that still reference the
+        // older marker name.
         ("{{ pipeline_name }}", &pipeline_name),
         ("{{ agent_description }}", &front_matter.description),
         ("{{ engine_run }}", &engine_run),
@@ -4046,6 +4086,36 @@ mod tests {
         assert_eq!(sanitize_filename("test_case"), "test-case");
     }
 
+    // ─── sanitize_pipeline_agent_name ───────────────────────────────────────
+
+    #[test]
+    fn test_sanitize_pipeline_agent_name_removes_invalid_build_number_chars() {
+        assert_eq!(
+            sanitize_pipeline_agent_name(r#"Daily safe-output smoke: "noop" @nightly"#),
+            "Daily safe-output smoke noop nightly"
+        );
+    }
+
+    #[test]
+    fn test_sanitize_pipeline_agent_name_trims_trailing_dot() {
+        assert_eq!(sanitize_pipeline_agent_name("Agent name."), "Agent name");
+    }
+
+    #[test]
+    fn test_sanitize_pipeline_agent_name_enforces_length_budget() {
+        let input = "x".repeat(ADO_BUILD_NUMBER_MAX_LEN);
+        let sanitized = sanitize_pipeline_agent_name(&input);
+        assert_eq!(
+            sanitized.chars().count(),
+            ADO_BUILD_NUMBER_MAX_LEN - ADO_BUILD_ID_SUFFIX.len()
+        );
+    }
+
+    #[test]
+    fn test_sanitize_pipeline_agent_name_fallback_when_empty_after_sanitize() {
+        assert_eq!(sanitize_pipeline_agent_name(":@?*"), "pipeline");
+    }
+
     // ─── yaml_double_quoted ──────────────────────────────────────────────────
 
     #[test]

src/data/1es-base.yml

@@ -2,7 +2,7 @@
 # This template extends the 1ES Unofficial Pipeline Template with Copilot CLI,
 # AWF network isolation, and MCP Gateway — matching the standalone pipeline model.
 
-name: {{ pipeline_name }}
+name: {{ pipeline_agent_name }}
 {{ parameters }}
 {{ schedule }}
 {{ pr_trigger }}

src/data/base.yml

@@ -1,5 +1,5 @@
 
-name: {{ pipeline_name }}
+name: {{ pipeline_agent_name }}
 {{ parameters }}
 resources:
   repositories:

tests/compiler_tests.rs

@@ -69,7 +69,7 @@ fn assert_required_markers(content: &str) {
         "{{ checkout_repositories }}",
         "{{ allowed_domains }}",
         "{{ source_path }}",
-        "{{ pipeline_name }}",
+        "{{ pipeline_agent_name }}",
         "{{ engine_run }}",
         "{{ compiler_version }}",
         "{{ integrity_check }}",
@@ -3531,22 +3531,21 @@ fn test_1es_compiled_output_is_valid_yaml() {
 /// Names with embedded `"` and `:` must survive YAML escaping in both
 /// the top-level `name:` line and any `displayName:` positions.
 ///
-/// Regression: until `{{ pipeline_name }}` was introduced both positions
+/// Regression: until `{{ pipeline_agent_name }}` was introduced both positions
 /// used a bare `{{ agent_name }}` substitution which broke if the
 /// front-matter name contained colons (`name: a: b` parsed as a YAML
 /// mapping) or embedded double quotes (`displayName: "a "b" c"` parsed
 /// as broken scalars). Now both positions go through `yaml_double_quoted`
-/// via a single `{{ pipeline_name }}` marker.
+/// via a dedicated pipeline name marker.
 #[test]
 fn test_compiled_yaml_survives_tricky_agent_name_standalone() {
     let compiled = compile_fixture("tricky-name-agent.md");
     assert_valid_yaml(&compiled, "tricky-name-agent.md");
 
-    // The top-level pipeline name must contain the escaped form of the
-    // embedded `"` (rendered as `\"`) AND retain the colon.
+    // Build-number names must strip invalid characters such as `"` and `:`.
     assert!(
-        compiled.contains(r#"name: "My \"special\": agent with quotes-$(BuildID)""#),
-        "standalone output should contain escaped pipeline name; got:\n{compiled}"
+        compiled.contains(r#"name: "My special agent with quotes-$(BuildID)""#),
+        "standalone output should contain sanitized pipeline name; got:\n{compiled}"
     );
 }
 
@@ -3559,8 +3558,8 @@ fn test_compiled_yaml_survives_tricky_agent_name_1es() {
     // the ADO build-number format needs a varying token; the stage
     // displayName does NOT carry the suffix (stage labels are static).
     assert!(
-        compiled.contains(r#"name: "My \"special\": agent with quotes (1ES)-$(BuildID)""#),
-        "1ES output should contain escaped pipeline name; got:\n{compiled}"
+        compiled.contains(r#"name: "My special agent with quotes (1ES)-$(BuildID)""#),
+        "1ES output should contain sanitized pipeline name; got:\n{compiled}"
     );
     assert!(
         compiled.contains(r#"displayName: "My \"special\": agent with quotes (1ES)""#),