fix(compile): quote pipeline name in generated YAML to handle colons

Front-matter agent names like 'Daily safe-output smoke: noop' produced invalid YAML when substituted bare into the top-level 'name:' line: ADO YAML parsers (and yaml.safe_load) saw the second colon as a mapping indicator and rejected the file with 'Mapping values are not allowed in this context.'

Fix by introducing a new {{ pipeline_display_name }} marker that emits the full '<name>-$(BuildID)' value as a YAML double-quoted scalar with proper escaping for backslashes, embedded double quotes, and ASCII control characters. The marker replaces {{ agent_name }}-$(BuildID) in src/data/base.yml and src/data/1es-base.yml. Other usages of {{ agent_name }} (inside already-quoted displayName fields and markdown bodies) are unchanged.

Includes 8 new unit tests for yaml_double_quoted covering plain strings, the original colon bug, backslash/quote/control-char escaping, ADO macro passthrough, and unicode. Test_compiled_yaml_structure updated to require the new marker. docs/template-markers.md documents the new marker and warns against using {{ agent_name }} in unquoted YAML positions.

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

Author: jamesadevine

docs/template-markers.md

@@ -99,6 +99,34 @@ This distinction allows resources (like templates) to be available as pipeline r
 
 Should be replaced with the human-readable name from the front matter (e.g., "Daily Code Review"). This is used for display purposes like stage names.
 
+> ⚠️ This marker is only safe inside an **already-quoted YAML scalar**
+> (e.g. `displayName: "{{ agent_name }}"`) or a markdown body. For the
+> top-level pipeline `name:` line, use
+> [`{{ pipeline_display_name }}`](#-pipeline_display_name-) instead — it
+> emits the value as a quoted scalar so colons and other plain-scalar-
+> unsafe characters in the agent name don't break YAML parsing.
+
+## {{ pipeline_display_name }}
+
+Should be replaced with the top-level pipeline `name:` value, including
+the `-$(BuildID)` suffix that ADO appends to every run, always emitted
+as a **YAML double-quoted scalar**. For an agent named
+`Daily safe-output smoke: noop`, this expands to:
+
+```yaml
+name: "Daily safe-output smoke: noop-$(BuildID)"
+```
+
+The quoting is unconditional because front-matter `name` values are
+free-form and frequently contain colons (which would otherwise be
+parsed as YAML mapping indicators). `$(...)` ADO macros pass through
+untouched — `$` has no special meaning inside a YAML double-quoted
+scalar and ADO expands the macro at queue time after YAML parsing.
+
+This marker is intended only for the top-level `name:` line in
+`src/data/base.yml` and `src/data/1es-base.yml`; the job- and
+stage-level templates don't have a top-level pipeline name field.
+
 ## {{ engine_install_steps }}
 
 Should be replaced with engine-specific pipeline steps to install the engine binary. Generated by `Engine::install_steps()`. For Copilot, this produces:

src/compile/common.rs

@@ -996,6 +996,40 @@ pub fn sanitize_filename(name: &str) -> String {
         .join("-")
 }
 
+/// Emit `s` as a YAML double-quoted scalar (always quoted, never plain).
+///
+/// We always quote because the value is substituted into YAML positions
+/// where colons and other plain-scalar-unsafe characters are common in
+/// agent names (e.g. `"Daily safe-output smoke: noop"`). A bare scalar
+/// like `name: Daily safe-output smoke: noop-$(BuildID)` is invalid YAML
+/// because the second colon is interpreted as a mapping indicator.
+///
+/// `$(...)` ADO macros pass through untouched — `$` has no special meaning
+/// inside a YAML double-quoted scalar and ADO expands the macro at queue
+/// time after YAML parsing.
+///
+/// `reject_pipeline_injection` already strips newlines and template /
+/// pipeline-command sequences from front-matter `name` values, so the
+/// escape table only has to cover `\` and `"`. Tabs and ASCII control
+/// characters are escaped too as a belt-and-braces measure.
+pub fn yaml_double_quoted(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 2);
+    out.push('"');
+    for ch in s.chars() {
+        match ch {
+            '\\' => out.push_str("\\\\"),
+            '"' => out.push_str("\\\""),
+            '\n' => out.push_str("\\n"),
+            '\r' => out.push_str("\\r"),
+            '\t' => out.push_str("\\t"),
+            c if (c as u32) < 0x20 => out.push_str(&format!("\\x{:02x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+    out
+}
+
 /// Default self-hosted pool for 1ES templates.
 pub const DEFAULT_ONEES_POOL: &str = "AZS-1ES-L-MMS-ubuntu-22.04";
 /// Default Microsoft-hosted VM image for non-1ES templates.
@@ -2856,6 +2890,12 @@ pub async fn compile_shared(
     let checkout_steps = generate_checkout_steps(&front_matter.checkout);
     let checkout_self = generate_checkout_self();
     let agent_name = sanitize_filename(&front_matter.name);
+    // Top-level pipeline `name:` value in the generated YAML. Always emitted
+    // as a YAML double-quoted scalar because the front-matter `name` is
+    // free-form and frequently contains colons. The `-$(BuildID)` suffix is
+    // embedded so ADO appends the build ID to every run.
+    let pipeline_display_name =
+        yaml_double_quoted(&format!("{}-$(BuildID)", front_matter.name));
 
     // 3. Run extension validations
     for ext in extensions {
@@ -3069,6 +3109,7 @@ pub async fn compile_shared(
         ("{{ checkout_repositories }}", &checkout_steps),
         ("{{ agent }}", &agent_name),
         ("{{ agent_name }}", &front_matter.name),
+        ("{{ pipeline_display_name }}", &pipeline_display_name),
         ("{{ agent_description }}", &front_matter.description),
         ("{{ engine_run }}", &engine_run),
         ("{{ engine_run_detection }}", &engine_run_detection),
@@ -3996,6 +4037,69 @@ mod tests {
         assert_eq!(sanitize_filename("test_case"), "test-case");
     }
 
+    // ─── yaml_double_quoted ──────────────────────────────────────────────────
+
+    #[test]
+    fn test_yaml_double_quoted_plain_string() {
+        assert_eq!(yaml_double_quoted("hello"), r#""hello""#);
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_string_with_colon_is_safe() {
+        // The bug this helper exists to fix: an agent name like
+        // "Daily safe-output smoke: noop" must not be emitted bare in the
+        // top-level pipeline `name:` line, where the second colon would
+        // be parsed as a YAML mapping indicator.
+        assert_eq!(
+            yaml_double_quoted("Daily safe-output smoke: noop-$(BuildID)"),
+            r#""Daily safe-output smoke: noop-$(BuildID)""#
+        );
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_escapes_backslash() {
+        assert_eq!(yaml_double_quoted(r"a\b"), r#""a\\b""#);
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_escapes_double_quote() {
+        assert_eq!(yaml_double_quoted(r#"say "hi""#), r#""say \"hi\"""#);
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_escapes_whitespace_controls() {
+        assert_eq!(yaml_double_quoted("a\nb"), r#""a\nb""#);
+        assert_eq!(yaml_double_quoted("a\rb"), r#""a\rb""#);
+        assert_eq!(yaml_double_quoted("a\tb"), r#""a\tb""#);
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_escapes_other_control_chars() {
+        // Bell (0x07) is a low ASCII control char — should escape as \x07.
+        assert_eq!(yaml_double_quoted("a\u{0007}b"), r#""a\x07b""#);
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_passes_through_ado_macros() {
+        // $(BuildID), $(Build.SourcesDirectory) etc. have no special meaning
+        // inside a YAML double-quoted scalar; ADO expands them at queue time
+        // after YAML parsing.
+        assert_eq!(
+            yaml_double_quoted("$(Build.BuildId)/$(System.JobId)"),
+            r#""$(Build.BuildId)/$(System.JobId)""#
+        );
+    }
+
+    #[test]
+    fn test_yaml_double_quoted_passes_through_unicode() {
+        // Non-ASCII characters pass through as-is — YAML 1.2 supports UTF-8
+        // in double-quoted scalars natively.
+        assert_eq!(
+            yaml_double_quoted("résumé — 你好"),
+            r#""résumé — 你好""#
+        );
+    }
+
     // ─── generate_pr_trigger ─────────────────────────────────────────────────
 
     #[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: {{ agent_name }}-$(BuildID)
+name: {{ pipeline_display_name }}
 {{ parameters }}
 {{ schedule }}
 {{ pr_trigger }}

src/data/base.yml

@@ -1,5 +1,5 @@
 
-name: {{ agent_name }}-$(BuildID)
+name: {{ pipeline_display_name }}
 {{ parameters }}
 resources:
   repositories:

tests/compiler_tests.rs

@@ -69,7 +69,7 @@ fn assert_required_markers(content: &str) {
         "{{ checkout_repositories }}",
         "{{ allowed_domains }}",
         "{{ source_path }}",
-        "{{ agent_name }}",
+        "{{ pipeline_display_name }}",
         "{{ engine_run }}",
         "{{ compiler_version }}",
         "{{ integrity_check }}",