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

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." A sister bug affected hand-quoted
`displayName: "{{ agent_name }}"` lines in 1es-base.yml:37 and
stage-base.yml:6: an agent name containing an embedded `"` would
produce `displayName: "My "special" agent"` — invalid YAML.

Introduce a single `{{ pipeline_name }}` template marker that emits
the front-matter agent name plus the `-$(BuildID)` suffix as a YAML
double-quoted scalar with proper escaping for `\`, `"`, `\n`, `\r`,
`\t`, and ASCII control characters. The new `yaml_double_quoted`
helper does the encoding; `$(...)` ADO macros pass through untouched
because `$` has no special meaning inside a YAML double-quoted scalar.

The marker replaces:

  * `{{ agent_name }}-$(BuildID)` on the top-level `name:` line in
    base.yml and 1es-base.yml,
  * hand-quoted `displayName: "{{ agent_name }}"` on the stage display
    name line in 1es-base.yml and stage-base.yml.

The stage `displayName:` now carries the `-$(BuildID)` suffix as well.
This is a small cosmetic change — stage labels in the ADO UI read e.g.
"My agent-12345" instead of "My agent" — but it provides a clear visual
link between the stage label and the build run.

Other usages of `{{ agent_name }}` are unchanged. The marker is still
used inside src/data/threat-analysis.md (a markdown body, not parsed
as YAML), which is the only remaining safe substitution position.

Tests:

  * 8 new unit tests for `yaml_double_quoted` cover plain strings, the
    original colon bug, backslash / embedded-quote / control-character
    escaping, ADO macro passthrough, and unicode.
  * 2 new integration tests
    (`test_compiled_yaml_survives_tricky_agent_name_{standalone,1es}`)
    compile fixtures whose names contain both embedded `"` and `:`,
    parse the output via serde_yaml, and assert the escaped forms
    appear verbatim in the generated `name:` and `displayName:` lines.
  * `test_compiled_yaml_structure` updated to require the new marker.
  * All 26 smoke-suite lock files in tests/safe-outputs regenerated
    with properly quoted names.
  * docs/template-markers.md documents the new marker and tightens the
    `{{ agent_name }}` warning to make clear it's only safe in
    non-YAML positions.

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

Author: jamesadevine

docs/template-markers.md

@@ -97,7 +97,46 @@ This distinction allows resources (like templates) to be available as pipeline r
 
 ## {{ agent_name }}
 
-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.
+Should be replaced with the human-readable name from the front matter
+(e.g., `Daily Code Review`). The value is substituted **as-is**, with
+no quoting or escaping — front-matter `name` values are free-form and
+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). Every YAML position inside the generated pipelines
+> that takes the agent name uses
+> [`{{ pipeline_name }}`](#-pipeline_name-) instead, which emits a
+> fully-quoted-and-escaped double-quoted YAML scalar so colons,
+> embedded `"`, and other plain-scalar-unsafe characters in the agent
+> name cannot break parsing.
+
+## {{ pipeline_name }}
+
+Should be replaced with the front-matter agent name plus the
+`-$(BuildID)` suffix, always emitted as a **YAML double-quoted
+scalar** with proper escaping for `\`, `"`, `\n`, `\r`, `\t`, and other
+ASCII control characters. Used for every `name:` and `displayName:`
+position in the generated YAML that takes the agent name.
+
+For an agent named `My "special": agent`, this expands to:
+
+```yaml
+name: "My \"special\": agent-$(BuildID)"
+```
+
+`$(BuildID)` is an ADO macro and is expanded at queue time after YAML
+parsing; `$` has no special meaning inside a YAML double-quoted scalar
+so the macro passes through untouched.
+
+This marker is used:
+
+- in `src/data/base.yml` and `src/data/1es-base.yml` for the top-level
+  pipeline `name:` line (the ADO run name),
+- in `src/data/1es-base.yml` and `src/data/stage-base.yml` for the
+  stage `displayName:` (so the stage label includes the build number,
+  giving a clear visual link between the ADO UI stage label and the
+  underlying run).
 
 ## {{ engine_install_steps }}
 

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,14 @@ 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);
+    // Display string for every "name:"/"displayName:" position in the
+    // generated YAML that takes the agent name. Always emitted as a YAML
+    // double-quoted scalar with the `-$(BuildID)` suffix so:
+    //   * colons and embedded `"` in the agent name can't break parsing,
+    //   * ADO appends the build number to every run name, and
+    //   * stage labels link visibly to the build via the same suffix.
+    let pipeline_name =
+        yaml_double_quoted(&format!("{}-$(BuildID)", front_matter.name));
 
     // 3. Run extension validations
     for ext in extensions {
@@ -3069,6 +3111,7 @@ pub async fn compile_shared(
         ("{{ checkout_repositories }}", &checkout_steps),
         ("{{ agent }}", &agent_name),
         ("{{ agent_name }}", &front_matter.name),
+        ("{{ pipeline_name }}", &pipeline_name),
         ("{{ agent_description }}", &front_matter.description),
         ("{{ engine_run }}", &engine_run),
         ("{{ engine_run_detection }}", &engine_run_detection),
@@ -3996,6 +4039,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_name }}
 {{ parameters }}
 {{ schedule }}
 {{ pr_trigger }}
@@ -34,7 +34,7 @@ extends:
       runPrerequisitesOnImage: false # Pool image has 1ES prerequisites preinstalled
     stages:
       - stage: AgentStage
-        displayName: "{{ agent_name }}"
+        displayName: {{ pipeline_name }}
         jobs:
           {{ setup_job }}
 

src/data/base.yml

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

src/data/stage-base.yml

@@ -3,7 +3,7 @@
 
 stages:
 - stage: {{ stage_prefix }}
-  displayName: "{{ agent_name }}"
+  displayName: {{ pipeline_name }}
   jobs:
     {{ setup_job }}
     - job: {{ stage_prefix }}_Agent

tests/compiler_tests.rs

@@ -69,7 +69,7 @@ fn assert_required_markers(content: &str) {
         "{{ checkout_repositories }}",
         "{{ allowed_domains }}",
         "{{ source_path }}",
-        "{{ agent_name }}",
+        "{{ pipeline_name }}",
         "{{ engine_run }}",
         "{{ compiler_version }}",
         "{{ integrity_check }}",
@@ -3528,6 +3528,46 @@ 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
+/// 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.
+#[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.
+    assert!(
+        compiled.contains(r#"name: "My \"special\": agent with quotes-$(BuildID)""#),
+        "standalone output should contain escaped pipeline name; got:\n{compiled}"
+    );
+}
+
+#[test]
+fn test_compiled_yaml_survives_tricky_agent_name_1es() {
+    let compiled = compile_fixture("tricky-name-1es-agent.md");
+    assert_valid_yaml(&compiled, "tricky-name-1es-agent.md");
+
+    // Top-level pipeline name AND the 1ES stage displayName both go through
+    // the same `{{ pipeline_name }}` marker, so both carry the `-$(BuildID)`
+    // suffix and the escaped quotes.
+    assert!(
+        compiled.contains(r#"name: "My \"special\": agent with quotes (1ES)-$(BuildID)""#),
+        "1ES output should contain escaped pipeline name; got:\n{compiled}"
+    );
+    assert!(
+        compiled.contains(r#"displayName: "My \"special\": agent with quotes (1ES)-$(BuildID)""#),
+        "1ES output should contain escaped stage displayName; got:\n{compiled}"
+    );
+}
+
 /// Test that the minimal standalone fixture produces valid YAML with correct structure
 #[test]
 fn test_standalone_minimal_compiled_output_is_valid_yaml() {

tests/fixtures/tricky-name-1es-agent.md

@@ -0,0 +1,15 @@
+---
+name: 'My "special": agent with quotes (1ES)'
+description: "Fixture covering YAML escaping for embedded \" and : in name (1ES target)"
+target: 1es
+permissions:
+  read: my-read-arm-connection
+---
+
+## Tricky-Name Agent (1ES)
+
+Fixture used by `tests/compiler_tests.rs` to verify that agent names
+containing embedded double quotes and colons survive YAML escaping for
+the 1ES target, where the stage's `displayName:` is generated via
+`{{ agent_display_name }}` and the top-level pipeline `name:` is
+generated via `{{ pipeline_display_name }}`.

tests/fixtures/tricky-name-agent.md

@@ -0,0 +1,14 @@
+---
+name: 'My "special": agent with quotes'
+description: "Fixture covering YAML escaping for embedded \" and : in name"
+target: standalone
+permissions:
+  read: my-read-arm-connection
+---
+
+## Tricky-Name Agent
+
+Fixture used by `tests/compiler_tests.rs` to verify that agent names
+containing embedded double quotes and colons survive YAML escaping in
+both the top-level `name:` line (via `{{ pipeline_display_name }}`) and
+any `displayName:` positions (via `{{ agent_display_name }}`).