dsh-pstack 0.2.0 → 0.2.1

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { c as VENDORED_SKILLS_ROOT, i as PORT_ROOT, n as HARNESS_DOC_PATH, o as SKILLS_ROOT, r as PACKAGE_ROOT, s as SKILL_ROOTS, t as AUTHORED_SKILLS_ROOT } from "./paths-BT77khwm.mjs";
+import { c as VENDORED_SKILLS_ROOT, i as PORT_ROOT, n as HARNESS_DOC_PATH, o as SKILLS_ROOT, r as PACKAGE_ROOT, s as SKILL_ROOTS, t as AUTHORED_SKILLS_ROOT } from "./paths-yji9SNak.mjs";
 import { TOOL_NAME, apply as apply$1, createPstackSkillTool, readSkillResource, renderLoadedSkill } from "./skill.mjs";
 import { basename, join } from "node:path";
 import { readFileSync, readdirSync } from "node:fs";

package/dist/{paths-BT77khwm.mjs → paths-yji9SNak.mjs}

@@ -25,7 +25,6 @@ const SKILLS_ROOT = join(PORT_ROOT, "skills");
 const VENDORED_SKILLS_ROOT = join(DIST_ROOT, "skills", "vendored");
 /** Absolute path of the skills authored in this repository. */
 const AUTHORED_SKILLS_ROOT = join(DIST_ROOT, "skills", "authored");
-join(PORT_ROOT, "agents");
 /** Absolute path of the `poteto-mode` instructions injected into a poteto-agent brief. */
 const POTETO_MODE_SKILL_PATH = join(SKILLS_ROOT, "poteto-mode", "SKILL.md");
 /** Absolute path of the shipped harness mapping document. */

package/dist/pstack/docs/harness/dsh.md

@@ -16,7 +16,7 @@ pstack skills use Cursor names. In DeepSeek Harness, read this file once per ses
 
 | Cursor | DeepSeek Harness |
 | --- | --- |
-| `subagent_type: generalPurpose` | `agent: "general"`. A plain child that joins the parent agent preset and inherits its tools. Every call must also pass `description`, `prompt`, `role`, `roleIndex`, `reasoningEffort`, `cwd`, and `maxDepth`; no argument has an implicit default. Pass `null` for `role`, `roleIndex`, `reasoningEffort`, or `cwd` when the setting is unused; `roleIndex` requires a non-null role, and a non-null `cwd` must be inside the Session directory or a separate Git worktree. `maxDepth` is a non-negative integer and may only lower the `pstack-subagent` row's configured cap (2 by default). A reasoning effort is one token, exactly as the target model advertises. Choose `agent` explicitly; never pass a DSH agent-preset id in its place. |
+| `subagent_type: generalPurpose` | `agent: "general"`. A plain child that joins the parent agent preset and inherits its tools. Every call must also pass `description`, `prompt`, `role`, `roleIndex`, `reasoningEffort`, and `cwd`; only `maxDepth` is optional. Pass `null` for `role`, `roleIndex`, `reasoningEffort`, or `cwd` when the setting is unused; `roleIndex` requires a non-null role, and a non-null `cwd` must be inside the Session directory or a separate Git worktree. `maxDepth` is optional: omit it or pass null for the safe default of 1 (the child exists but cannot start its own children); pass 2 or more, within the `pstack-subagent` row's configured cap (2 by default), to let it delegate further. A `0` is treated as 1, because a child is already depth 1 and `0` can never start one. A reasoning effort is one token, exactly as the target model advertises. Choose `agent` explicitly; never pass a DSH agent-preset id in its place. |
 | `poteto-agent`, `comment-sicko` | `agent: "poteto-agent"`, `agent: "comment-sicko"`. The package declares both as `@deepseek-ai/dsh-agent-preset` rows: `poteto-agent` injects the pstack persona and the absolute `poteto-mode` instruction path; `comment-sicko` mounts the comment reviewer preset. These are not `subagent_type` values. |
 | `readonly: true` | No per-call field. Use `agent: "comment-sicko"` for the comment reviewer: its preset disables `write` and `edit` but keeps `bash`, so treat the no-write rule as a review constraint and check `git status` after it reports. For any other read-only brief, say "do not edit files" and check `git status`. Prose is not a sandbox. |
 | `readonly: false` | `agent: "general"`. The child keeps the parent's tools, including mounted MCP tools. |
@@ -35,7 +35,7 @@ pstack skills use Cursor names. In DeepSeek Harness, read this file once per ses
 | A `grok-*`, `gpt-*`, or other non-Claude slug | Pass `role: null` so the child inherits the parent route, and say so. A role line with `inherit-parent` or `auto` does the same. |
 | `auto` or `inherit-parent` | Pass `role: null`, or write the role value as `inherit-parent` or `auto`. `pstack_subagent` sends no route override and the child inherits the parent route. |
 | The `pstack-models.mdc` rule, `~/.cursor/rules/pstack-models.mdc` | `$DSH_HOME/pstack-models.mdc`. `pstack_subagent` re-reads it on every delegation, so an edit affects the next child and never a running child. A missing file makes every role inherit the parent route; an unreadable file is an error; a malformed line is reported at its line number. Role names come from the pstack role manifest, not free text. |
-| A role value `<model> <effort>`, such as `opus high` | `<provider>/<model> [effort]`, such as `provider/model [high]`. Split at the first `/`; the bracketed effort must be a token the model advertises. A comma-separated value is a list: `arena runners`, `architect runners`, and `interrogate reviewers` are automatic panels that start one child per entry; `arena cross-judge pool` and `swarm workers` select one entry by `roleIndex` (null selects the first), and `swarm workers` is the default route for every worker unless a race assigns one per arm. |
+| A role value `<model> <effort>`, such as `opus high` | `<provider>/<model> [effort]`, such as `provider/model [high]`. Split at the first `/`; the bracketed effort must be a token the model advertises. A comma-separated value is a list: `arena runners`, `architect runners`, and `interrogate reviewers` are automatic panels that start one child per entry; `arena cross-judge pool` and `swarm workers` select one entry by `roleIndex` (null selects the first), and `swarm workers` is the default route for every worker unless a race assigns one per arm. Call `pstack_roles` first when a role may hold a list; it reports the role's `shape`, `autoPanel`, and whether `roleIndex` applies. |
 
 ## setup-pstack
 
@@ -86,13 +86,13 @@ The following DSH plugins are disabled by default. `OPT-07` is stable; the other
 | ID | Plugin packages | Capability when enabled | When not enabled |
 | --- | --- | --- | --- |
 | OPT-01 | `@deepseek-ai/dsh-experimental-worktree` and `@deepseek-ai/dsh-experimental-tool-worktree` | `create_worktree` creates a local branch and checkout for `/arena`, `/swarm`, and `/architect`. `from` reads local refs without fetching. | Use `git worktree add` through `bash`, then pass the resulting path to the child as `cwd`. There is no cloud VM; the bundle does not create one worktree per subagent, and each `create_worktree` call changes the Session directory. Skipped in DeepSeek Harness: Use a Cursor cloud agent dashboard or dedicated cloud machine. DeepSeek Harness provides only local worktree isolation. |
-| OPT-02 | `@deepseek-ai/dsh-experimental-forge-bundle` | PR panels, checks, reviews, ready state, merge, and Session binding for `/babysit`, `/shipping`, and `/autopilot-*`. | Use `gh` through `bash`; the bundle covers GitHub only and needs a logged-in `gh`. It has no stack or queued-stack verdict, so keep the bundled `watch-pr` for those. The optional bundle adds no model-side change-request tool. |
-| OPT-03 | `@deepseek-ai/dsh-browser-use` and exactly one of `@deepseek-ai/dsh-experimental-browser-use-stagehand-native`, `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp`, or `@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp` | Browser navigation, input, screenshots, and ARIA snapshots. Stagehand also provides act, observe, and extract operations. The providers share one provider slot; screenshots need an image-capable model. | Use project-owned browser scripts through `bash` when available. Otherwise print `Skipped in DeepSeek Harness: Drive the browser UI or capture browser evidence. No browser provider is enabled.` Keep static source inspection and any non-browser verification. |
-| OPT-04 | `@deepseek-ai/dsh-cua-bundle` | Clicking, typing, screenshots, and permission pages for macOS desktop applications in a PTC Session. Windows support is incomplete. | Use a project-owned desktop driver through `bash` when available. Otherwise print `Skipped in DeepSeek Harness: Drive the desktop application or capture desktop evidence. No computer-use provider is enabled.` |
-| OPT-05 | `@deepseek-ai/dsh-experimental-terminal-bundle` | Six global tools keep a shell or REPL alive across calls for CLI and TUI verification. They are added to every Agent, do not cover a GUI, and record no video; clean up persistent state, and expect switching to invalidate the KV cache. | Run foreground commands or background jobs through `bash`. Preserve input, output, and exit codes in the evidence. |
+| OPT-02 | `@deepseek-ai/dsh-experimental-forge-bundle` | PR panels, checks, reviews, ready state, merge, Session binding, and a new-worktree option when starting a Session for `/babysit`, `/shipping`, and `/autopilot-*`. | Use `gh` through `bash`; the bundle covers GitHub only and needs a logged-in `gh`. It has no stack or queued-stack verdict and no `origin` CLI, so keep the bundled `watch-pr` for those. The optional bundle adds no model-side change-request tool. |
+| OPT-03 | `@deepseek-ai/dsh-browser-use` and exactly one of `@deepseek-ai/dsh-experimental-browser-use-stagehand-native`, `@deepseek-ai/dsh-experimental-browser-use-playwright-mcp`, or `@deepseek-ai/dsh-experimental-browser-use-chrome-devtools-mcp` | Browser navigation, input, screenshots, and ARIA snapshots. Stagehand also provides act, observe, and extract operations. The providers share one provider slot and expose different tool names and selectors; screenshots need an image-capable model. | Use project-owned browser scripts through `bash` when available. Otherwise print `Skipped in DeepSeek Harness: Drive the browser UI or capture browser evidence. No browser provider is enabled.` Keep static source inspection and any non-browser verification. |
+| OPT-04 | `@deepseek-ai/dsh-cua-bundle` | Clicking, typing, screenshots, permission pages, and session-level authorization for macOS desktop applications in a PTC Session. Install it on demand; Windows support is incomplete, and it uses the single computer-use provider slot. | Use a project-owned desktop driver through `bash` when available. Otherwise print `Skipped in DeepSeek Harness: Drive the desktop application or capture desktop evidence. No computer-use provider is enabled.` |
+| OPT-05 | `@deepseek-ai/dsh-experimental-terminal-bundle` | Six global tools keep a shell or REPL alive across calls, support background send, and isolate terminals by owner for CLI and TUI verification. They are added to every Agent, do not cover a GUI, and record no video; clean up persistent state, and expect switching to invalidate the KV cache. | Run foreground commands or background jobs through `bash`. Preserve input, output, and exit codes in the evidence. |
 | OPT-06 | `@deepseek-ai/dsh-experimental-session-search` | `session_search`, `session_event_search`, `session_trace`, `session_event_trace`, and `session_event_read` search and inspect Sessions with exact `cwd` equality. Subagent transcript coverage is not confirmed. | Use a resume note or evidence supplied by the user. Print `Skipped in DeepSeek Harness: Search or read the earlier Session transcript. Session-search tools are not enabled.` Do not infer historical results from the current conversation. |
 | OPT-07 | `@deepseek-ai/dsh-mcp-client` | Configured MCP tools appear as `mcp__<server>__<tool>` for `/why` and `/teach`. No server is configured by default, and DSH does not discover evidence categories. | Inspect local files and use standard search or fetch tools. Mark each missing MCP evidence category as not searched. |
 | OPT-08 | `@deepseek-ai/dsh-experimental-agent-team-profile` | Lead and teammate roles, a shared task board, nine team tools, and a Web roster for `/orchestrate` and `/autopilot-*`. There is no pstack PR frontier, ledger, or stack verdict. | Use `pstack_subagent`, `workflow`, and `todo_write`. Do not enable Agent Teams and `pstack_subagent` in one profile. Agent Teams disables `subagent` and `subagent_fork` and replaces the global child controls. |
-| OPT-09 | `@deepseek-ai/dsh-experimental-ralph-bundle` | A foreground `ralph` loop starts a fresh child each round for `/autonomous-run`. It is not a persistent loop in the same Session and has no event watcher. | Use `create_goal` with `schedule_create` or a background `bash` watcher. This fallback does not subscribe to forge events. |
+| OPT-09 | `@deepseek-ai/dsh-experimental-ralph-bundle` | A foreground `ralph` loop starts a fresh child each round and carries a structured handoff for `/autonomous-run`. It is not a persistent loop in the same Session and has no event watcher. | Use `create_goal` with `schedule_create` or a background `bash` watcher. This fallback does not subscribe to forge events. |
 
 Browser-use needs its base package and one provider. Stagehand also needs Chromium and a supported non-DeepSeek model. Computer-use covers only macOS PTC Sessions. These optional tools do not record video; use an external recorder or ffmpeg when a step requires video, and report that dependency separately.

package/dist/remote.d.mts

@@ -1,5 +1,5 @@
 import { CatalogueResult } from "./models.mjs";
-import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-DZwTn2wF.mjs";
+import { n as SaveRoleRequest, r as SaveRoleResult, t as RoleFileSnapshot } from "./role-wire-CAJsVA6e.mjs";
 import { RemoteResult, TypertRemoteContribution, TypertRemoteInfo } from "@deepseek-ai/dsh-typert-protocol";
 /** npm package that owns these methods. */
 export declare const REMOTE_PACKAGE = "dsh-pstack";

package/dist/remote.mjs

@@ -1,3 +1,4 @@
+import { a as isRoleKey } from "./role-manifest-79cnFfDM.mjs";
 // src/remote.ts
 /** npm package that owns these methods. */
 const REMOTE_PACKAGE = "dsh-pstack";
@@ -70,7 +71,7 @@ function parseRoleFileIssue(value) {
 }
 function parseRoleView(value, index) {
 	const record = parseRecord(value, `roles[${index}]`);
-	if (typeof record["key"] !== "string") throw new TypeError(`roles[${index}].key must be a string`);
+	if (typeof record["key"] !== "string" || !isRoleKey(record["key"])) throw new TypeError(`roles[${index}].key is not in the role manifest`);
 	if (record["shape"] !== "single" && record["shape"] !== "list") throw new TypeError(`roles[${index}].shape is unknown`);
 	if (typeof record["configured"] !== "boolean") throw new TypeError(`roles[${index}].configured must be a boolean`);
 	const routes = record["routes"];

package/dist/role-catalog.d.mts

@@ -0,0 +1,35 @@
+import { _ as ToolsHost, g as ToolDefinition } from "./host-contract-CUPSpeNk.mjs";
+import { n as RoleSpec, r as RoleValueShape } from "./role-manifest-8OERX9-s.mjs";
+/** Cordis row name, used by Loader diagnostics. */
+export declare const name = "pstack-role-catalog";
+/** The row only needs the tool registry. */
+export declare const inject: string[];
+/** Model-facing tool name. */
+export declare const TOOL_NAME = "pstack_roles";
+/** Whether `roleIndex` may be passed for a role. */
+export type RoleIndexApplicability = "not-applicable" | "optional";
+export interface RoleCapability {
+  /** The exact key to pass as `role`. */
+  readonly role: string;
+  /** One route, or a comma-separated list of routes. */
+  readonly shape: RoleValueShape;
+  /** A list role that starts one child per entry automatically. */
+  readonly autoPanel: boolean;
+  /** `optional` only for a list role that is not an automatic panel. */
+  readonly roleIndex: RoleIndexApplicability;
+  /** How this role expands into children. */
+  readonly usage: string;
+}
+/** Derive one role's capability from its manifest entry. */
+export declare function roleCapability(spec: RoleSpec): RoleCapability;
+/** Every role's capability, in manifest order. */
+export declare function roleCapabilities(): readonly RoleCapability[];
+/** Render the capability list for the model. */
+export declare function renderRoleCapabilities(roles: readonly RoleCapability[]): string;
+export declare function createPstackRoleCatalogTool(): ToolDefinition;
+/** The slice of the Cordis context this row uses. */
+export interface PstackRoleCatalogHost {
+  readonly tools: ToolsHost;
+}
+/** Register `pstack_roles`. */
+export declare function apply(ctx: PstackRoleCatalogHost): void;

package/dist/role-catalog.mjs

@@ -0,0 +1,122 @@
+import { r as ROLE_MANIFEST } from "./role-manifest-79cnFfDM.mjs";
+// src/role-catalog.ts
+/** Cordis row name, used by Loader diagnostics. */
+const name = "pstack-role-catalog";
+/** The row only needs the tool registry. */
+const inject = ["tools"];
+/** Model-facing tool name. */
+const TOOL_NAME = "pstack_roles";
+/** Derive one role's capability from its manifest entry. */
+function roleCapability(spec) {
+	if (spec.autoPanel) return {
+		role: spec.key,
+		shape: spec.shape,
+		autoPanel: true,
+		roleIndex: "not-applicable",
+		usage: "one child per configured entry"
+	};
+	if (spec.shape === "list") return {
+		role: spec.key,
+		shape: spec.shape,
+		autoPanel: false,
+		roleIndex: "optional",
+		usage: "one child, choosing one configured entry"
+	};
+	return {
+		role: spec.key,
+		shape: spec.shape,
+		autoPanel: false,
+		roleIndex: "not-applicable",
+		usage: "one child on the role's single route"
+	};
+}
+/** Every role's capability, in manifest order. */
+function roleCapabilities() {
+	return ROLE_MANIFEST.map(roleCapability);
+}
+/** Render the capability list for the model. */
+function renderRoleCapabilities(roles) {
+	return [
+		"pstack roles. Pass the exact `role` key. `roleIndex` is null unless the role is a list that is not an automatic panel.",
+		"",
+		...roles.map((role) => `- ${role.role} — shape=${role.shape}${role.autoPanel ? ", autoPanel=true" : ""}; roleIndex=${role.roleIndex}; ${role.usage}`)
+	].join("\n");
+}
+const OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: { roles: {
+		type: "array",
+		description: "One capability record per role, in manifest order.",
+		items: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				role: {
+					type: "string",
+					description: "The exact key to pass as `role`."
+				},
+				shape: {
+					type: "string",
+					enum: ["single", "list"],
+					description: "One route, or a comma-separated list of routes."
+				},
+				autoPanel: {
+					type: "boolean",
+					description: "A list role that starts one child per configured entry."
+				},
+				roleIndex: {
+					type: "string",
+					enum: ["not-applicable", "optional"],
+					description: "`optional` only for a list role that is not an automatic panel; otherwise pass null."
+				},
+				usage: {
+					type: "string",
+					description: "How this role expands into children."
+				}
+			},
+			required: [
+				"role",
+				"shape",
+				"autoPanel",
+				"roleIndex",
+				"usage"
+			]
+		}
+	} },
+	required: ["roles"]
+};
+const TOOL_DESCRIPTION = [
+	"List every pstack role with its `shape` and `autoPanel`, so a `pstack_subagent` call passes the right `role` and `roleIndex` before it starts.",
+	"",
+	"Read-only. It reports the role manifest, not the routes in `$DSH_HOME/pstack-models.mdc`; use `pstack_models` for the routes this deployment actually serves.",
+	"",
+	"`roleIndex` applies only to a list role that is not an automatic panel: `arena cross-judge pool` and `swarm workers`. Pass `null` for every single role and for an automatic panel (`arena runners`, `architect runners`, `interrogate reviewers`), which starts one child per configured entry."
+].join("\n");
+function createPstackRoleCatalogTool() {
+	return {
+		name: TOOL_NAME,
+		description: TOOL_DESCRIPTION,
+		parameters: {
+			type: "object",
+			additionalProperties: false,
+			properties: {}
+		},
+		output: {
+			schema: OUTPUT_SCHEMA,
+			render: (_args, value) => [{
+				type: "text",
+				text: renderRoleCapabilities(value.roles)
+			}]
+		},
+		isConcurrencySafe: () => true,
+		async execute() {
+			return { roles: roleCapabilities() };
+		}
+	};
+}
+/** Register `pstack_roles`. */
+function apply(ctx) {
+	ctx.tools.register(createPstackRoleCatalogTool());
+}
+export { TOOL_NAME, apply, createPstackRoleCatalogTool, inject, name, renderRoleCapabilities, roleCapabilities, roleCapability };

package/dist/{role-config-NNn5r1JX.mjs → role-config-a4JpVdc-.mjs}

@@ -1,108 +1,97 @@
+import { i as findRoleSpec, n as PSTACK_MODELS_FILENAME, o as normalizeRoleName, r as ROLE_MANIFEST, t as INHERIT_PARENT_ALIASES } from "./role-manifest-79cnFfDM.mjs";
 import { join, resolve } from "node:path";
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-// src/internal/role-manifest.ts
-/**
-* File name the role configuration lives under inside `$DSH_HOME`.
-*
-* It keeps the upstream name `pstack-models.mdc`, so a reader moving from the Cursor docs
-* recognizes it, but stores it directly under `$DSH_HOME`; DSH does not load `.mdc` files
-* on its own, and `pstack_subagent` is the only reader.
-*/
-const PSTACK_MODELS_FILENAME = "pstack-models.mdc";
-/** Values that resolve to "send no `agentOptions` and inherit the parent route". */
-const INHERIT_PARENT_ALIASES = ["inherit-parent", "auto"];
-/** The 17 roles, in manifest order. */
-const ROLE_MANIFEST = [
-	{
-		key: "feature, refactoring",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "bug-fix",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "perf-issue",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "hillclimb",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "judgment and prose",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "hardest tasks",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "how explorer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "how explainer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "why investigators",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "why synthesizer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "reflect tooling",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "reflect judgment, divergent, synthesizer",
-		shape: "single",
-		autoPanel: false
-	},
-	{
-		key: "arena runners",
-		shape: "list",
-		autoPanel: true
-	},
-	{
-		key: "arena cross-judge pool",
-		shape: "list",
-		autoPanel: false
-	},
-	{
-		key: "swarm workers",
-		shape: "list",
-		autoPanel: false
-	},
-	{
-		key: "architect runners",
-		shape: "list",
-		autoPanel: true
-	},
-	{
-		key: "interrogate reviewers",
-		shape: "list",
-		autoPanel: true
+// src/internal/role-grammar.ts
+function frontmatterBodyStart(lines) {
+	if (lines[0]?.trim() !== "---") return 0;
+	for (let index = 1; index < lines.length; index += 1) if (lines[index]?.trim() === "---") return index + 1;
+	return 0;
+}
+/** One line grammar for role parsing and byte-preserving updates. */
+function scanRoleDocument(text) {
+	const lines = text.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	const bodyStart = frontmatterBodyStart(lines);
+	const scanned = [];
+	let offset = 0;
+	for (let index = 0; index < lines.length; index += 1) {
+		const rawLine = lines[index];
+		const line = index + 1 - bodyStart;
+		const contentEnd = offset + rawLine.length - (rawLine.endsWith("\r") ? 1 : 0);
+		if (index < bodyStart) {
+			scanned.push({
+				kind: "blank",
+				line
+			});
+			offset += rawLine.length + 1;
+			continue;
+		}
+		const trimmed = rawLine.trim();
+		if (trimmed === "") scanned.push({
+			kind: "blank",
+			line
+		});
+		else if (trimmed.startsWith("#")) {
+			const match = /^#\s*budget:\s*(.+)$/i.exec(trimmed);
+			scanned.push({
+				kind: "comment",
+				line,
+				...match === null ? {} : { budget: match[1].trim() }
+			});
+		} else {
+			const separator = trimmed.indexOf(":");
+			if (separator === -1) scanned.push({
+				kind: "malformed",
+				line,
+				rawLine: trimmed
+			});
+			else {
+				const rawKey = trimmed.slice(0, separator).trim();
+				const key = normalizeRoleName(rawKey);
+				const spec = findRoleSpec(key);
+				if (key === "") scanned.push({
+					kind: "malformed",
+					line,
+					rawLine: ""
+				});
+				else if (spec === void 0) scanned.push({
+					kind: "unknown-role",
+					line,
+					rawKey
+				});
+				else {
+					const valueText = rawLine.slice(0, contentEnd - offset);
+					const sourceSeparator = valueText.indexOf(":");
+					const afterSeparator = valueText.slice(sourceSeparator + 1);
+					const rawValue = afterSeparator.trim();
+					const valueLeading = rawValue === "" ? 0 : afterSeparator.length - afterSeparator.trimStart().length;
+					const valueTrailing = rawValue === "" ? 0 : afterSeparator.length - afterSeparator.trimEnd().length;
+					const valueStart = offset + sourceSeparator + 1 + valueLeading;
+					const valueEnd = contentEnd - valueTrailing;
+					scanned.push({
+						kind: "role",
+						line,
+						rawKey,
+						key,
+						rawValue,
+						spec,
+						valueStart,
+						valueEnd
+					});
+				}
+			}
+		}
+		offset += rawLine.length + 1;
 	}
-];
-/** Exact manifest lookup. Callers normalize the key first. */
-function findRoleSpec(key) {
-	return ROLE_MANIFEST.find((role) => role.key === key);
+	return { lines: scanned };
+}
+/** Replace only the winning role's value, retaining every other source byte. */
+function updateRoleDocument(text, spec, value) {
+	const winning = scanRoleDocument(text).lines.findLast((line) => line.kind === "role" && line.key === spec.key);
+	if (winning?.kind === "role") return `${text.slice(0, winning.valueStart)}${value}${text.slice(winning.valueEnd)}`;
+	const eol = text.includes("\r\n") ? "\r\n" : "\n";
+	return `${text}${text === "" || text.endsWith("\n") ? "" : eol}${spec.key}: ${value}${eol}`;
 }
 // src/internal/role-config.ts
 /**
@@ -149,49 +138,36 @@ function parseRoleConfiguration(text, path) {
 	const issues = [];
 	const roles = /* @__PURE__ */ new Map();
 	let budget;
-	stripFrontmatter(text).split("\n").forEach((rawLine, index) => {
-		const line = index + 1;
-		const trimmed = rawLine.trim();
-		if (trimmed === "") return;
-		if (trimmed.startsWith("#")) {
-			const match = /^#\s*budget:\s*(.+)$/i.exec(trimmed);
-			if (match !== null) budget = match[1].trim();
-			return;
-		}
-		const separator = trimmed.indexOf(":");
-		if (separator === -1) {
-			issues.push({
-				line,
-				message: `expected \`<role>: <value>\`, found ${JSON.stringify(trimmed)}`
-			});
-			return;
+	for (const scanned of scanRoleDocument(text).lines) {
+		const { line } = scanned;
+		if (scanned.kind === "blank") continue;
+		if (scanned.kind === "comment") {
+			if (scanned.budget !== void 0) budget = scanned.budget;
+			continue;
 		}
-		const rawKey = trimmed.slice(0, separator).trim();
-		const rawValue = trimmed.slice(separator + 1).trim();
-		const key = normalizeRoleName(rawKey);
-		if (key === "") {
+		if (scanned.kind === "malformed") {
 			issues.push({
 				line,
-				message: "the role key is empty"
+				message: scanned.rawLine === "" ? "the role key is empty" : `expected \`<role>: <value>\`, found ${JSON.stringify(scanned.rawLine)}`
 			});
-			return;
+			continue;
 		}
-		const spec = findRoleSpec(key);
-		if (spec === void 0) {
+		if (scanned.kind === "unknown-role") {
 			issues.push({
 				line,
-				message: unknownRoleMessage(rawKey, key)
+				message: unknownRoleMessage(scanned.rawKey, normalizeRoleName(scanned.rawKey))
 			});
-			return;
+			continue;
 		}
-		const parsed = parseRouteValue(rawValue);
+		const { rawKey, spec } = scanned;
+		const parsed = parseRouteValue(scanned.rawValue);
 		const entryIssues = [...parsed.issues];
 		if (spec.shape === "single" && parsed.routes.length > 1) entryIssues.push("a single-route role cannot hold a comma-separated list");
 		for (const issue of entryIssues) issues.push({
 			line,
 			message: `${rawKey}: ${issue}`
 		});
-		if (parsed.routes.length === 0) return;
+		if (parsed.routes.length === 0) continue;
 		const previous = roles.get(spec.key);
 		if (previous !== void 0) issues.push({
 			line,
@@ -205,7 +181,7 @@ function parseRoleConfiguration(text, path) {
 			routes: parsed.routes,
 			issues: entryIssues
 		});
-	});
+	}
 	return budget === void 0 ? {
 		status: "loaded",
 		path,
@@ -335,10 +311,6 @@ var RoleNameError = class extends Error {
 		this.name = "RoleNameError";
 	}
 };
-/** Normalize a role name for lookup. Case, spacing, spacing around a comma, and a trailing colon are formatting. */
-function normalizeRoleName(raw) {
-	return raw.normalize("NFC").trim().toLowerCase().replace(/\s+/g, " ").replace(/\s*,\s*/g, ", ").replace(/:+$/, "").trim();
-}
 /** Resolve a role name, or throw a diagnostic that names the near misses. */
 function requireRole(raw) {
 	const spec = findRoleSpec(normalizeRoleName(raw));
@@ -394,14 +366,6 @@ function editDistance(left, right) {
 	}
 	return previous[right.length];
 }
-function stripFrontmatter(text) {
-	const normalized = text.replaceAll("\r\n", "\n");
-	if (!normalized.startsWith("---\n")) return normalized;
-	const end = normalized.indexOf("\n---", 3);
-	if (end === -1) return normalized;
-	const after = normalized.indexOf("\n", end + 1);
-	return after === -1 ? "" : normalized.slice(after + 1);
-}
 function isMissingFile(error) {
 	return typeof error === "object" && error !== null && error.code === "ENOENT";
 }
@@ -412,4 +376,4 @@ function describeError(error) {
 	}
 	return String(error);
 }
-export { resolveDshHome as a, ROLE_MANIFEST as c, requireRole as i, findRoleSpec as l, normalizeRoleName as n, selectRoleRoutes as o, readRoleConfiguration as r, INHERIT_PARENT_ALIASES as s, modelsFilePath as t };
+export { selectRoleRoutes as a, resolveDshHome as i, readRoleConfiguration as n, updateRoleDocument as o, requireRole as r, modelsFilePath as t };