fix(orchestration): fence dispatch CLI preamble

src/main/runtime/orchestration/__snapshots__/preamble.test.ts.snap

@@ -10,6 +10,7 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
 
 === CLI COMMANDS ===
 
+\`\`\`sh
   # Report the terminal task outcome (REQUIRED exactly once).
   #
   # RULE: --body must be a 3-sentence executive summary (what you did,
@@ -71,6 +72,7 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
 
   # Check for messages from the coordinator:
   orca orchestration check --terminal term_WORKER
+\`\`\`
 
 === AFTER YOU SEND worker_done ===
 

src/main/runtime/orchestration/preamble.test.ts

@@ -1,4 +1,6 @@
 import { spawnSync } from 'node:child_process'
+import remarkParse from 'remark-parse'
+import { unified } from 'unified'
 import { describe, expect, it } from 'vitest'
 import { buildDispatchPreamble } from './preamble'
 
@@ -23,6 +25,12 @@ function afterWorkerDoneSection(result: string) {
   return result.slice(sectionStart, sectionEnd)
 }
 
+function cliFence(result: string): string {
+  const match = result.match(/=== CLI COMMANDS ===\n\n```sh\n([\s\S]*?)\n```/)
+  expect(match).not.toBeNull()
+  return match?.[1] ?? ''
+}
+
 describe('buildDispatchPreamble', () => {
   it('substitutes template variables', () => {
     const result = buildDispatchPreamble(baseParams())
@@ -58,25 +66,22 @@ describe('buildDispatchPreamble', () => {
     { timeout: 15_000 },
     () => {
       const result = buildDispatchPreamble(baseParams())
-      // Why: feeding `bash -n` the full preamble falsely fails on apostrophes
-      // in the surrounding prose. Slice between the CLI markers and strip
-      // shell-style comment lines so we only syntax-check the commands.
-      const cliStart = result.indexOf('=== CLI COMMANDS ===')
-      const cliEnd = result.indexOf('=== AFTER YOU SEND worker_done ===')
-      expect(cliStart).toBeGreaterThan(-1)
-      expect(cliEnd).toBeGreaterThan(cliStart)
-      const block = result.slice(cliStart, cliEnd)
-      const stripped = block
-        .split('\n')
-        .filter((line) => !line.trim().startsWith('#'))
-        .filter((line) => !line.trim().startsWith('==='))
-        .join('\n')
-
-      const check = spawnSync('bash', ['-n'], { input: stripped, encoding: 'utf8' })
+      const check = spawnSync('bash', ['-n'], { input: cliFence(result), encoding: 'utf8' })
       expect(check.status).toBe(0)
     }
   )
 
+  it('fences shell comments so Markdown does not promote them to headings', () => {
+    const result = buildDispatchPreamble(baseParams())
+    const tree = unified().use(remarkParse).parse(result)
+    const headings = tree.children.filter((node) => node.type === 'heading')
+    const codeBlocks = tree.children.filter((node) => node.type === 'code')
+
+    expect(headings).toHaveLength(0)
+    expect(codeBlocks).toHaveLength(1)
+    expect(codeBlocks[0]).toMatchObject({ lang: 'sh', value: cliFence(result) })
+  })
+
   it('includes heartbeat CLI block with taskId and dispatchId and 5-minute cadence', () => {
     const result = buildDispatchPreamble(baseParams())
     expect(result).toContain('--type heartbeat')

src/main/runtime/orchestration/preamble.ts

@@ -59,6 +59,7 @@ export function buildDispatchPreamble(params: PreambleParams): string {
     ? ` --dispatch-capability ${params.dispatchCapability}`
     : ''
 
+  // Why: fencing keeps shell comments executable to agents without turning them into Chat UI headings.
   const header = `You are working inside Orca, a multi-agent IDE. You are a dispatched worker.
 Your coordinator's terminal handle is: ${params.coordinatorHandle}
 Your task ID is: ${params.taskId}
@@ -68,6 +69,7 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
 
 === CLI COMMANDS ===
 
+\`\`\`sh
   # Report the terminal task outcome (REQUIRED exactly once).
   #
   # RULE: --body must be a 3-sentence executive summary (what you did,
@@ -129,6 +131,7 @@ Slack, GitHub comments, or any other channel to reach a human during the run.
 
   # Check for messages from the coordinator:
   ${cli} orchestration check --terminal ${params.workerHandle}
+\`\`\`
 
 ${postDoneInstructions}`