bug(agents): model routing breaks block scalar descriptions and empties them

[Rogercode97]

Before submitting

• I searched open and closed issues and did not find a report of this problem.
• I reviewed this report and removed credentials, tokens, private paths, hostnames, and other sensitive data.

Problem

On every session start, gentle-pi rewrites agent model routing into the wrong position inside an agent definition whose description is a YAML block scalar. The model: key lands between the description: > header and its indented continuation lines, so the description parses as an empty string and its text is folded into the model value.

Observed on a real run against a project whose .agents/agents/ set declares description: > in 18 of 18 files:

description: >
model: deepseek/deepseek-v4-flash
  Adversarial review lens evaluating security risks, data exposure, and permission flaws.

which parses as:

description: ''
model: 'deepseek/deepseek-v4-flash Adversarial review lens evaluating security risks, data exposure, and permission flaws.'

Every discovered agent definition using a block scalar description is silently left with an empty description and a garbage model id.

This is not limited to one adapter. The packaged agent sets use description: > as follows: antigravity 18/18, claude 13/19, cursor 10/16, kimi 10/16, kiro 13/19.

Steps to reproduce

1. Define an agent whose frontmatter uses a block scalar description:

---
name: review-risk
description: >
  Adversarial review lens evaluating security risks.
subagent: true
---

2. Give it a routing entry, e.g. through /gentle:models or a model_profiles entry in .pi/subagents.json.
3. Start a Pi session in that project.

Actual result: the definition is rewritten at the next session start into the broken frontmatter above.

Root cause in extensions/gentle-ai.ts (main @ db788aef):

const descriptionIndex = lines.findIndex((line) => line.startsWith("description:"));
const insertIndex = descriptionIndex >= 0 ? descriptionIndex + 1 : Math.min(1, lines.length);
lines.splice(insertIndex, 0, ...toInsert);

descriptionIndex + 1 is the first line of the block scalar, not the first key after it. The same logic existed a second time in lib/sdd-preflight.ts as updateAgentFrontmatterRouting.

The trigger is pi.on("session_start") -> applySavedModelConfig -> applyModelConfig. It does not require a model change.

Expected and actual behavior

Expected:

Routing keys are inserted after the block scalar's continuation lines, and a definition that already carries correct routing is left untouched.

Actual:

Routing keys are inserted inside the block scalar, so the description becomes empty and its text is folded into the model value on every session start.

gentle-pi version

2.5.0 (main @ db788ae)

Pi version

0.85.1

Operating system

Other

Relevant logs or error output (optional)

$ git diff .agents/agents/sdd-init.md
@@ -2,8 +2,8 @@
 name: sdd-init
 role: "SDD Stack Initializer"
 description: >
-  Initialize SDD context, detect project stack, testing capabilities, and bootstrap persistence backend.
 model: deepseek/deepseek-v4-flash
+  Initialize SDD context, detect project stack, testing capabilities, and bootstrap persistence backend.
 subagent: true

Parsed with PyYAML:

description repr: ''
model       repr: 'deepseek/deepseek-v4-flash Initialize SDD context, detect project stack, testing capabilities, and bootstrap persistence backend.'

Against the current implementation, a 12-case regression suite fails 5 cases. A local fix on branch fix/agent-frontmatter-block-scalar consolidates both writers into lib/agent-frontmatter.ts and inserts routing keys after the block scalar continuation lines.

[Rogercode97]

A fix for this is ready locally on branch fix/agent-frontmatter-block-scalar (commit 5b2dc33e).

What the bugfix does

Both writers now share a single block-scalar-aware insertion point in a new lib/agent-frontmatter.ts. The rule is:

const BLOCK_SCALAR_DESCRIPTION_PATTERN = /^description:\s*[>|][0-9+-]*\s*$/;

// A `description: >` block scalar owns every following blank or indented line,
// so the routing keys belong after the last continuation line, not at
// `descriptionIndex + 1`.
if (!BLOCK_SCALAR_DESCRIPTION_PATTERN.test(lines[descriptionIndex])) {
  return descriptionIndex + 1;
}
let insertIndex = descriptionIndex + 1;
for (let index = insertIndex; index < lines.length; index += 1) {
  const line = lines[index];
  if (line.trim() === "") continue;
  if (line.startsWith(" ") || line.startsWith("\t")) {
    insertIndex = index + 1;
    continue;
  }
  break;
}
return insertIndex;

A plain scalar description keeps its previous insertion point, and an empty routing list still only strips existing keys, so the asset-drift comparison path is behaviourally unchanged.

The duplicate writer in lib/sdd-preflight.ts (updateAgentFrontmatterRouting) is removed; its two call sites now use the shared function. extensions/gentle-ai.ts keeps updateFrontmatterRouting as a thin wrapper that builds the routing lines from the entry.

Evidence

• New tests/agent-frontmatter.test.ts, 12 cases: block, literal, chomped and plain scalar descriptions, idempotence, key replacement, and body preservation. Against the previous implementation 5 of the 12 fail; against the fix all 12 pass.
• End-to-end with the real module over the 19 real agent files: re-applying routing to already-correct content is a no-op in 19/19, an empty routing list leaves the file untouched in 19/19, and a simulated clean install (content with the routing key stripped) regenerates valid YAML that is byte-identical to the correct content in 19/19.
• tests/sdd-preflight.test.ts, tests/package-manifest.test.ts and tests/gentle-ai.test.ts: 122/122 pass.
• Observed cause of the corruption, parsed from a damaged file: description becomes '' and model becomes 'deepseek/deepseek-v4-flash <the description text>'.

The consolidation into one module is my call rather than a requirement of the fix, because the same wrong insertion rule existed in two copies. I can rework this as a minimal in-place fix in the two existing files, or open a PR from a fork, whichever shape you prefer.

[Rogercode97]

Opened PR #969 with the consolidated fix and regression test suite.

It moves routing updates into , preserves folded/literal block scalar descriptions (including trailing blank continuation lines), and passes the full test suite (125/125 tests passing).