piher 0.0.0-stage → 0.2.0

package/src/prompt-store.ts

@@ -0,0 +1,50 @@
+/** The prompt a task was spawned with, kept so a retry costs no tokens: an upstream failure (a
+ *  provider outage, a dropped stream) is nobody's fault in the task, and the master should not have to
+ *  regenerate a whole brief to try again. One file per task, next to piher's other user state. */
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function taskPromptsDir(): string {
+  // pi's own agent dir wins when set (a test home, a second profile), matching how piher locates
+  // sessions and roles elsewhere.
+  const base = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent');
+  return join(base, 'piher', 'prompts');
+}
+
+function promptPath(taskId: string): string {
+  // A task id is a uuid or a kebab slug; anything else cannot address a file here.
+  const safe = taskId.replace(/[^A-Za-z0-9._-]/g, '_');
+  return join(taskPromptsDir(), `${safe}.md`);
+}
+
+/** Best effort by design: a task that cannot be retried is a smaller problem than a spawn that fails
+ *  because a state file was unwritable. */
+export function saveTaskPrompt(taskId: string, prompt: string): void {
+  if (!taskId || prompt === '') return;
+  try {
+    mkdirSync(taskPromptsDir(), { recursive: true });
+    writeFileSync(promptPath(taskId), prompt, 'utf8');
+  } catch {
+    /* no stored prompt: `retry` reports it and the master sends the task explicitly */
+  }
+}
+
+export function readTaskPrompt(taskId: string): string | null {
+  const file = promptPath(taskId);
+  if (!existsSync(file)) return null;
+  try {
+    const text = readFileSync(file, 'utf8');
+    return text.trim() === '' ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+export function forgetTaskPrompt(taskId: string): void {
+  try {
+    rmSync(promptPath(taskId), { force: true });
+  } catch {
+    /* nothing to forget */
+  }
+}

package/src/renderers.ts

@@ -0,0 +1,195 @@
+/**
+ * TUI renderers for piher's own session custom entries and reminder messages: raw JSON rows bury the
+ * one line that matters. Pure string builders plus an ANSI-aware truncator, so no pi-tui import is
+ * needed and older pi builds degrade to "no renderer".
+ */
+
+import { DELEGATION_CUSTOM_TYPE } from './delegation-core.ts';
+import { SETTLEMENT_CUSTOM_TYPE, formatElapsed, type SettlementCard } from './settlement-card.ts';
+import { JOB_NOTICE_CUSTOM_TYPE, formatDuration } from './bg-job-core.ts';
+
+// Width handling lives in ansi-text.ts so the transcript cards need no pi-tui import.
+import { truncateStyled } from './ansi-text.ts';
+
+/** Role manifest entry is written by index-roles.ts; keep the literal here to avoid an import cycle. */
+export const ROLE_MANIFEST_CUSTOM_TYPE = 'piher.role-manifest';
+
+/** Structural subset of pi's Theme actually used here. */
+export interface RenderTheme {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+export interface RenderComponent {
+  render(width: number): string[];
+  invalidate(): void;
+}
+
+type Renderer = (payload: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent | undefined;
+
+export interface RendererApi {
+  registerEntryRenderer?(customType: string, renderer: Renderer): void;
+  registerMessageRenderer?(customType: string, renderer: Renderer): void;
+}
+
+function clip(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+function card(lines: readonly string[]): RenderComponent {
+  return {
+    render: (width: number) => lines.map((line) => truncateStyled(line, width)),
+    invalidate() { /* No cached state. */ },
+  };
+}
+
+/** First-frame delegation card in the worker's own transcript (RFC rfc-delegation-identity §2.3). */
+function delegationLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const rec = (data ?? {}) as {
+    parentPaneId?: unknown;
+    parentSessionId?: unknown;
+    taskId?: unknown;
+    description?: unknown;
+    role?: unknown;
+  };
+  const parent = typeof rec.parentPaneId === 'string' && rec.parentPaneId ? rec.parentPaneId : '?';
+  const head = `${theme.fg('accent', '⟵ delegated')} ${theme.fg('dim', `by master ${parent} · ${clip(String(rec.description ?? ''), 60)}`)}`;
+  if (!expanded) return [head];
+  const session = typeof rec.parentSessionId === 'string' && rec.parentSessionId ? rec.parentSessionId : '?';
+  const role = typeof rec.role === 'string' && rec.role ? rec.role : '?';
+  return [
+    head,
+    theme.fg('dim', `  task ${typeof rec.taskId === 'string' ? rec.taskId : '?'} · role ${role} · parent session ${session}`),
+  ];
+}
+
+function roleManifestLines(data: unknown, theme: RenderTheme): string[] {
+  const rec = (data ?? {}) as {
+    role?: unknown;
+    manifestVersion?: unknown;
+    tools?: unknown;
+    permissions?: unknown;
+    origin?: unknown;
+    switchedBy?: unknown;
+  };
+  const role = typeof rec.role === 'string' ? rec.role : '?';
+  const version = typeof rec.manifestVersion === 'string' || typeof rec.manifestVersion === 'number' ? String(rec.manifestVersion) : '?';
+  const tools = Array.isArray(rec.tools) ? rec.tools.length : 0;
+  const gates = Object.values((rec.permissions ?? {}) as Record<string, unknown>)
+    .filter((v) => v === 'deny').length;
+  const tail = gates > 0 ? theme.fg('warning', ` · ${gates} gated`) : '';
+  // P0: switch provenance — origin 'switch' marks a mid-session swap (vs the session_start anchor).
+  const switched =
+    rec.origin === 'switch'
+      ? theme.fg('accent', ` ⇄ ${typeof rec.switchedBy === 'string' && rec.switchedBy ? rec.switchedBy : '?'}`)
+      : '';
+  return [`${theme.fg('accent', theme.bold('role'))} ${role} ${theme.fg('dim', `v${version} · ${tools} tools`)}${tail}${switched}`];
+}
+
+/**
+ * Settlement card (S57): the header is what the transcript shows — name, role, outcome, elapsed —
+ * and the notice text it carries is never rewritten. Missing fields degrade to the plain content.
+ */
+function settlementLines(message: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const rec = (message ?? {}) as { content?: unknown; details?: unknown };
+  const details = (rec.details ?? {}) as Partial<SettlementCard>;
+  const content = typeof rec.content === 'string' ? rec.content : '';
+  if (typeof details.name !== 'string' || details.name === '') {
+    return reminderLines(message, theme, 'subagent settled', expanded);
+  }
+  const outcome = details.outcome === 'failed' || details.outcome === 'closed' ? details.outcome : 'settled';
+  const tone = outcome === 'failed' ? 'error' : outcome === 'closed' ? 'warning' : 'success';
+  const fields = [
+    details.role ?? 'task',
+    outcome,
+    typeof details.elapsedMs === 'number' ? formatElapsed(details.elapsedMs) : null,
+  ].filter((field): field is string => typeof field === 'string');
+  const head = `${theme.fg(tone, theme.bold('subagent'))} ${theme.bold(details.name)} ${theme.fg('dim', `· ${fields.join(' · ')}`)}`;
+  if (!expanded) return [head];
+  return [head, ...content.split('\n').map((line) => theme.fg('dim', line))];
+}
+
+/** Background job notice: the header is what the transcript shows (outcome, name, elapsed); the
+ *  body is the notice text minus its own headline, so the card never says the same thing twice. */
+function jobNoticeLines(message: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const rec = (message ?? {}) as { content?: unknown; details?: unknown };
+  const details = (rec.details ?? {}) as {
+    jobId?: unknown;
+    label?: unknown;
+    status?: unknown;
+    exitCode?: unknown;
+    durationMs?: unknown;
+    checkIn?: unknown;
+  };
+  const content = typeof rec.content === 'string' ? rec.content : '';
+  const id = typeof details.jobId === 'string' && details.jobId ? details.jobId : 'job';
+  const name = typeof details.label === 'string' && details.label ? ` ("${details.label}")` : '';
+  const failed = details.status === 'failed'
+    || (details.status === 'finished' && details.exitCode !== 0 && details.exitCode !== null);
+  const checkIn = details.checkIn === true;
+  const icon = checkIn ? theme.fg('warning', '⧗') : failed ? theme.fg('error', '✗') : theme.fg('success', '✓');
+  const outcome = checkIn
+    ? 'still running'
+    : details.status === 'stopped'
+      ? 'stopped'
+      : failed
+        ? `exit ${String(details.exitCode ?? '?')}`
+        : 'exit 0';
+  const elapsed = typeof details.durationMs === 'number' && details.durationMs >= 0
+    ? ` · ${formatDuration(details.durationMs)}`
+    : '';
+  const head = `${icon} ${theme.fg('accent', theme.bold('bg_job'))} ${theme.bold(id)}${name} ${theme.fg('dim', `· ${outcome}${elapsed}`)}`;
+  const body = content.split('\n').slice(1).filter((line) => line.trim() !== '');
+  if (body.length === 0) return [head];
+  if (expanded) return [head, ...body.map((line) => theme.fg('dim', `  ${line}`))];
+  const preview = body.slice(0, 4).map((line) => theme.fg('dim', `  ${clip(line, 110)}`));
+  const rest = body.length - preview.length;
+  return rest > 0 ? [...preview.length > 0 ? [head, ...preview] : [head], theme.fg('muted', `  … ${rest} more lines`)] : [head, ...preview];
+}
+
+/** Reminder custom messages carry the full injected text; restyle without altering it. */
+function reminderLines(message: unknown, theme: RenderTheme, label: string, expanded: boolean): string[] {
+  const content = typeof (message as { content?: unknown } | undefined)?.content === 'string'
+    ? String((message as { content: string }).content)
+    : '';
+  const firstLine = content.split('\n').find((line) => line.trim().length > 0) ?? label;
+  const head = `${theme.fg('warning', `↻ ${label}`)}`;
+  if (!expanded) return [head, theme.fg('dim', `  ${clip(firstLine, 110)}`)];
+  return [head, ...content.split('\n').map((line) => theme.fg('dim', line))];
+}
+
+type LineBuilder = (data: unknown, theme: RenderTheme, expanded: boolean) => string[];
+
+/** Register piher's transcript renderers and return the custom types actually registered, so the
+ *  caller can log coverage and tests can assert the degrade path. Each registration is individually
+ *  guarded: a pi build without the API must never break tool registration. */
+export function installRenderers(pi: unknown): string[] {
+  const api = pi as RendererApi;
+  const registered: string[] = [];
+  const entry = (type: string, build: LineBuilder): void => {
+    if (typeof api.registerEntryRenderer !== 'function') return;
+    try {
+      api.registerEntryRenderer(type, (entryData, options, theme) =>
+        card(build((entryData as { data?: unknown } | undefined)?.data, theme, options.expanded)));
+      registered.push(type);
+    } catch {
+      /* Older pi or a conflicting renderer: keep the default rendering. */
+    }
+  };
+  const message = (type: string, build: LineBuilder): void => {
+    if (typeof api.registerMessageRenderer !== 'function') return;
+    try {
+      api.registerMessageRenderer(type, (msg, options, theme) => card(build(msg, theme, options.expanded)));
+      registered.push(type);
+    } catch {
+      /* A throwing renderer must not break message registration. */
+    }
+  };
+
+  entry(DELEGATION_CUSTOM_TYPE, delegationLines);
+  entry(ROLE_MANIFEST_CUSTOM_TYPE, (data, theme) => roleManifestLines(data, theme));
+  message(SETTLEMENT_CUSTOM_TYPE, (msg, theme, expanded) => settlementLines(msg, theme, expanded));
+  message(JOB_NOTICE_CUSTOM_TYPE, (msg, theme, expanded) => jobNoticeLines(msg, theme, expanded));
+  return registered;
+}

package/src/role-catalog.ts

@@ -0,0 +1,99 @@
+/**
+ * The `piher-roles` prompt section: which roles a spawn can name, derived from the role manifests
+ * (never from prose). S20 — one line per visible role, ordered by layer then name, deduped by name,
+ * closing with the default line; `master` and `modelInvocable: false` roles are absent.
+ *
+ * A static skill file cannot enumerate roles that appear per workspace, and an action would spend a
+ * round trip on text that fits in the prompt for free — so the catalog is prompt-only (S21/S22).
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { RESERVED_ROLE_NAMES, roleLayers } from './role-loader.ts';
+
+/** Prompt-budget cap: past this the section says how many roles it left out. */
+export const CATALOG_MAX_ROLES = 12;
+/** The role piher composes when a spawn omits `role`. */
+export const DEFAULT_ROLE_NAME = 'worker-default';
+
+export interface CatalogEntry {
+  name: string;
+  /** Manifest `description`; absent when the file does not carry one. */
+  description?: string;
+  /** `false` keeps a role launchable by name but out of the catalog. */
+  modelInvocable?: boolean;
+  /** Layer index (0 = workspace, 1 = user); ordering and dedupe only — the lower layer wins. */
+  layer: number;
+}
+
+/**
+ * Reads the two spawnable layers (workspace → user). An unreadable or unparseable manifest is
+ * skipped: it cannot be spawned either, and the spawn error names it.
+ */
+export function catalogEntries(opts?: { baseDir?: string; userDir?: string }): CatalogEntry[] {
+  const entries: CatalogEntry[] = [];
+  roleLayers(opts).slice(0, 2).forEach((layer, layerIndex) => {
+    let files: string[];
+    try {
+      files = readdirSync(layer.dir);
+    } catch {
+      return; // Layer absent (the workspace one commonly is).
+    }
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      const name = file.slice(0, -'.json'.length);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(readFileSync(join(layer.dir, file), 'utf8'));
+      } catch {
+        continue;
+      }
+      if (typeof parsed !== 'object' || parsed === null) continue;
+      const rec = parsed as { description?: unknown; modelInvocable?: unknown };
+      entries.push({
+        name,
+        ...(typeof rec.description === 'string' ? { description: rec.description } : {}),
+        ...(typeof rec.modelInvocable === 'boolean' ? { modelInvocable: rec.modelInvocable } : {}),
+        layer: layerIndex,
+      });
+    }
+  });
+  return entries;
+}
+
+/** Renders the section body. Deterministic: same entries in, byte-identical text out. */
+export function renderRoleCatalog(
+  entries: readonly CatalogEntry[],
+  opts?: { maxRoles?: number; searchDirs?: readonly string[] },
+): string {
+  const max = opts?.maxRoles ?? CATALOG_MAX_ROLES;
+  const ordered = [...entries].sort((a, b) => a.layer - b.layer || a.name.localeCompare(b.name));
+  const seen = new Set<string>();
+  const visible: CatalogEntry[] = [];
+  for (const entry of ordered) {
+    if (seen.has(entry.name)) continue; // Higher layer wins.
+    seen.add(entry.name);
+    if (RESERVED_ROLE_NAMES.includes(entry.name)) continue; // master is the caller; worker-default is the default line.
+    if (entry.modelInvocable === false) continue;
+    visible.push(entry);
+  }
+
+  const lines = ['Roles a `subagent` spawn can name (`role` parameter):'];
+  for (const entry of visible.slice(0, max)) {
+    const description = entry.description?.replace(/\s+/g, ' ').trim();
+    lines.push(`- ${entry.name} — ${description || '(no description)'}`);
+  }
+  const hidden = visible.length - max;
+  if (hidden > 0) {
+    const where = opts?.searchDirs?.length
+      ? ` (${opts.searchDirs.join(', ')})`
+      : ' (`.piher/roles/`, `~/.pi/agent/piher/roles/`)';
+    lines.push(`- … ${hidden} more not listed here${where}; an unknown-role error names them all`);
+  }
+  lines.push(`- (default) — \`${DEFAULT_ROLE_NAME}\`, used when \`role\` is omitted`);
+  return lines.join('\n');
+}
+
+/** Every spawn-target directory a truncation notice can point at. */
+export function catalogSearchDirs(opts?: { baseDir?: string; userDir?: string }): string[] {
+  return roleLayers(opts).slice(0, 2).map((layer) => layer.dir);
+}

package/src/role-loader.ts

@@ -0,0 +1,196 @@
+/**
+ * Role manifest loading, three layers in order: workspace `<cwd>/.piher/roles/` (travels with the clone)
+ * → user `~/.pi/agent/piher/roles/` → bundled `src/roles/`.
+ *
+ * Reserved built-in names (master / worker-default) may not be overridden by a user layer: tests and the D82
+ * stance are anchored to the bundled manifests.
+ *
+ * Role names are restricted to [a-z0-9-] (no path traversal; invalid names never touch disk) and the manifest
+ * `role` field must match the filename. Errors: unreadable = ROLE_NOT_FOUND (only after every layer missed);
+ * parsed-but-invalid JSON/validation/name = INVALID_ROLE_CONFIG at the hit layer — falling through would
+ * silently hide a user editing a manifest incorrectly.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { validateRoleManifest, type RoleManifest } from './role-manifest.ts';
+import { userRolesDir, workspaceRolesDir as layoutWorkspaceRolesDir } from './storage-layout.ts';
+
+export { userRolesDir };
+
+export const ROLES_DIR = join(dirname(fileURLToPath(import.meta.url)), 'roles');
+
+/** Workspace-level directory (the default base is the process cwd, i.e. the master's working directory). */
+export function workspaceRolesDir(baseDir?: string): string {
+  return layoutWorkspaceRolesDir(baseDir ?? process.cwd());
+}
+
+export const RESERVED_ROLE_NAMES: readonly string[] = ['master', 'worker-default'];
+
+const ROLE_NAME_RE = /^[a-z0-9-]+$/;
+
+export class RoleLoaderError extends Error {
+  readonly code: 'ROLE_NOT_FOUND' | 'INVALID_ROLE_CONFIG' | 'ROLE_RESERVED';
+  readonly issues: readonly string[];
+  constructor(
+    code: 'ROLE_NOT_FOUND' | 'INVALID_ROLE_CONFIG' | 'ROLE_RESERVED',
+    message: string,
+    issues: readonly string[] = [],
+  ) {
+    super(message);
+    this.name = 'RoleLoaderError';
+    this.code = code;
+    this.issues = issues;
+  }
+}
+
+export type RoleReader = (fileName: string) => string;
+
+/** Single-layer reader (injectable; production uses existsSync + readFileSync for that directory). */
+export type LayerReader = (dir: string, fileName: string) => string | null;
+
+const defaultLayerRead: LayerReader = (dir, fileName) => {
+  const p = resolve(dir, fileName);
+  if (!existsSync(p)) return null;
+  return readFileSync(p, 'utf8');
+};
+
+export interface LoadRoleOptions {
+  /** Inject one reader (legacy shape: only the bundled layer is hit, for test compatibility). */
+  read?: RoleReader;
+  layerRead?: LayerReader;
+  /** Base directory for the workspace layer (defaults to process.cwd()). */
+  baseDir?: string;
+  /** Direct built-in lookup (master self-application, WS-D7): reserved names skip user layers and
+   *  collision checks and always load the bundled manifest — otherwise a workspace master.json could make
+   *  self-application fail open and silently lose master's manifest. */
+  builtinDirect?: boolean;
+}
+
+export function roleLayers(opts?: { baseDir?: string; userDir?: string }): Array<{ label: string; dir: string }> {
+  const base = opts?.baseDir && isAbsolute(opts.baseDir) ? opts.baseDir
+    : resolve(opts?.baseDir ?? process.cwd());
+  return [
+    { label: 'workspace (.piher/roles/)', dir: workspaceRolesDir(base) },
+    // userDir lets tests keep the real ~/.pi out of the search.
+    { label: `user (${'~/.pi/agent/piher/roles/'})`, dir: opts?.userDir ?? userRolesDir() },
+    { label: 'builtin (src/roles/)', dir: ROLES_DIR },
+  ];
+}
+
+  /** User-layer role names (workspace → user), deduped and sorted; built-ins are not listed — they are
+   *  exactly RESERVED_ROLE_NAMES, which no user layer may override. */
+export function listRoleNames(baseDir?: string, userDir?: string): string[] {
+  const names = new Set<string>();
+  for (const layer of roleLayers({ baseDir, userDir }).slice(0, 2)) {
+    let entries: string[];
+    try {
+      entries = readdirSync(layer.dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.endsWith('.json')) names.add(entry.slice(0, -'.json'.length));
+    }
+  }
+  return [...names].sort();
+}
+
+export function loadRoleConfig(name: string, opts?: LoadRoleOptions): RoleManifest {
+  if (typeof name !== 'string' || !ROLE_NAME_RE.test(name)) {
+    throw new RoleLoaderError('ROLE_NOT_FOUND', `role not found or invalid name ([a-z0-9-]+): ${JSON.stringify(name)}`);
+  }
+  const fileName = `${name}.json`;
+
+  if (opts?.read && !opts.layerRead) {
+    let text: string;
+    try {
+      text = opts.read(fileName);
+    } catch (err) {
+      const code = (err as { code?: unknown })?.code;
+      throw new RoleLoaderError('ROLE_NOT_FOUND', `role "${name}" not found (failed to read ${fileName}: ${typeof code === 'string' ? code : 'error'})`);
+    }
+    return parseAndValidate(name, fileName, text, 'builtin (src/roles/)');
+  }
+
+  const layerRead = opts?.layerRead ?? defaultLayerRead;
+  let layers = roleLayers({ baseDir: opts?.baseDir });
+
+  if (opts?.builtinDirect && RESERVED_ROLE_NAMES.includes(name)) {
+    layers = [layers[2]];
+  } else if (RESERVED_ROLE_NAMES.includes(name)) {
+    for (const layer of layers.slice(0, 2)) {
+      if (layerRead(layer.dir, fileName) != null) {
+        throw new RoleLoaderError(
+          'ROLE_RESERVED',
+          `role "${name}" is a reserved built-in name and cannot be defined in the ${layer.label} layer (built-in manifests take precedence; delete that file or rename it)`,
+        );
+      }
+    }
+  }
+
+  for (const layer of layers) {
+    const text = layerRead(layer.dir, fileName);
+    if (text == null) continue; // No manifest in this layer; try the next layer.
+    return parseAndValidate(name, fileName, text, layer.label); // At the hit layer, report errors immediately.
+  }
+  throw new RoleLoaderError(
+    'ROLE_NOT_FOUND',
+    `role "${name}" not found (searched layers: ${layers.map((l) => l.label).join(' → ')}; available roles: ${availableRoleNames(layerRead, layers, opts?.baseDir)})`,
+  );
+}
+
+/** Role names a caller can actually ask for: user layers only (built-ins are reserved), minus
+ *  `modelInvocable: false` ones, which are launchable by name but not advertised. */
+function availableRoleNames(
+  layerRead: LayerReader,
+  layers: Array<{ label: string; dir: string }>,
+  baseDir?: string,
+): string {
+  let names: string[] = [];
+  try {
+    names = listRoleNames(baseDir);
+  } catch {
+    return '(none)';
+  }
+  const visible = names.filter((n) => {
+    const fileName = `${n}.json`;
+    for (const layer of layers.slice(0, 2)) {
+      const text = layerRead(layer.dir, fileName);
+      if (text == null) continue;
+      try {
+        return JSON.parse(text)?.modelInvocable !== false;
+      } catch {
+        return true;
+      }
+    }
+    return true;
+  });
+  return visible.length > 0 ? visible.join(', ') : '(none)';
+}
+
+function parseAndValidate(name: string, fileName: string, text: string, layerLabel: string): RoleManifest {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new RoleLoaderError('INVALID_ROLE_CONFIG', `role "${name}" (${layerLabel}) is not valid JSON: ${(err as Error).message}`);
+  }
+  const result = validateRoleManifest(parsed);
+  // `ok === false` (instead of `!ok`) is required to narrow without strictNullChecks.
+  if (result.ok === false) {
+    throw new RoleLoaderError(
+      'INVALID_ROLE_CONFIG',
+      `role "${name}" (${layerLabel}) failed validation:\n${result.issues.map((i) => `  - ${i}`).join('\n')}`,
+      result.issues,
+    );
+  }
+  if (result.value.role !== name) {
+    throw new RoleLoaderError(
+      'INVALID_ROLE_CONFIG',
+      `role manifest name mismatch: role="${result.value.role}" in ${fileName} of ${layerLabel}`,
+      [`role field "${result.value.role}" does not match the requested "${name}"`],
+    );
+  }
+  return result.value;
+}