pi-pier 0.3.0 → 0.3.1

package/src/renderers.ts

@@ -1,66 +1,51 @@
 /**
- * TUI renderers for pier's own session custom entries and reminder messages.
- *
- * Why: pier persists authority in the session JSONL (todo edits, subagent registry,
- * terminal registry, role manifests, soft-approvals) and injects reminder messages.
- * Without a renderer those transcript rows are raw JSON, which buries the one line
- * that matters. The line builders here are pure (unit-tested); the component is a
- * thin string array plus an ANSI-aware truncator, so this module needs no pi-tui
- * import and degrades to "no renderer" on older pi builds.
+ * TUI renderers for pier'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 { TODO_EDIT_CUSTOM_TYPE, type TodoEditPayload } from './todo-core.ts';
 import { SUBS_CUSTOM_TYPE, type SubsRegistry } from './subagent-core.ts';
 import { TERMINALS_CUSTOM_TYPE, TERM_REMINDER_CUSTOM_TYPE, type TerminalsRegistry } from './terminal-core.ts';
 import { TODO_REMINDER_CUSTOM_TYPE } from './todo-reminder-core.ts';
 
-// Width handling lives in its own module so the ask_user_question UI can reuse it
-// without pulling the todo/subagent/terminal cores into its import graph.
-import { charWidth, styledWidth, truncateStyled } from './ansi-text.ts';
-export { charWidth, styledWidth, truncateStyled };
+// Width handling lives in ansi-text.ts so ask_user_question can reuse it without this import graph.
+import { truncateStyled } from './ansi-text.ts';
 
 /** Role manifest entry is written by index.ts; keep the literal here to avoid an import cycle. */
 export const ROLE_MANIFEST_CUSTOM_TYPE = 'pi-herdr.role-manifest';
-/** Soft-approval trace written by the worker manifest gate in index.ts. */
+/** Soft-approval trace from the worker manifest gate in index.ts. */
 export const APPROVAL_NEEDED_CUSTOM_TYPE = 'pi-herdr.approval-needed';
 
-/** Structural subset of pi's Theme that the builders actually use. */
+/** Structural subset of pi's Theme actually used here. */
 export interface RenderTheme {
   fg(color: string, text: string): string;
   bold(text: string): string;
 }
 
-/** Structural subset of pi's Component; enough for `registerEntryRenderer`. */
 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: (entry: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent | undefined,
-  ): void;
-  registerMessageRenderer?(
-    customType: string,
-    renderer: (message: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent | undefined,
-  ): void;
+  registerEntryRenderer?(customType: string, renderer: Renderer): void;
+  registerMessageRenderer?(customType: string, renderer: Renderer): void;
 }
 
-/* ── Pure line builders ────────────────────────────────────────────── */
+function clip(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
 
-/** Component wrapper: render is a no-op transform except for width clipping. */
-export function card(lines: readonly string[]): RenderComponent {
+function card(lines: readonly string[]): RenderComponent {
   return {
     render: (width: number) => lines.map((line) => truncateStyled(line, width)),
     invalidate() { /* No cached state. */ },
   };
 }
 
-export function clip(text: string, max: number): string {
-  const flat = text.replace(/\s+/g, ' ').trim();
-  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
-}
-
 const EDIT_VERB: Record<string, string> = {
   done: '✓ done',
   drop: '■ dropped',
@@ -68,7 +53,7 @@ const EDIT_VERB: Record<string, string> = {
   rm: '✗ removed',
 };
 
-export function formatEditCounts(edits: ReadonlyArray<{ op: string }>): string {
+function formatEditCounts(edits: ReadonlyArray<{ op: string }>): string {
   const counts = new Map<string, number>();
   for (const edit of edits) counts.set(edit.op, (counts.get(edit.op) ?? 0) + 1);
   return [...counts.entries()]
@@ -76,7 +61,7 @@ export function formatEditCounts(edits: ReadonlyArray<{ op: string }>): string {
     .join(' · ');
 }
 
-export function todoEditLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+function todoEditLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
   const payload = data as TodoEditPayload | undefined;
   const edits = Array.isArray(payload?.edits) ? payload.edits : [];
   if (edits.length === 0) return [theme.fg('dim', 'todo · no edits')];
@@ -88,44 +73,64 @@ export function todoEditLines(data: unknown, theme: RenderTheme, expanded: boole
   ];
 }
 
-export function subsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
-  const subs = (data as SubsRegistry | undefined)?.subs;
-  if (!Array.isArray(subs) || subs.length === 0) return [theme.fg('dim', 'subagents · none')];
-  const running = subs.filter((s) => s.status === 'running').length;
-  const head = `${theme.fg('accent', theme.bold('subagents'))} ${theme.fg('dim', `· ${subs.length} tracked`)}${running ? ` ${theme.fg('success', `${running} running`)}` : ''}`;
+/** Registry card, shared by the subagent and terminal registries: a titled count line plus one row
+ *  per entry when expanded; an empty or malformed registry renders one dim placeholder. */
+function registryLines<T>(
+  items: readonly T[] | undefined,
+  theme: RenderTheme,
+  expanded: boolean,
+  card: { label: string; unit: string; badge?: string; row: (item: T) => string },
+): string[] {
+  if (!items || items.length === 0) return [theme.fg('dim', `${card.label} · none`)];
+  const head = `${theme.fg('accent', theme.bold(card.label))} ${theme.fg('dim', `· ${items.length} ${card.unit}`)}${card.badge ? ` ${theme.fg('success', card.badge)}` : ''}`;
   if (!expanded) return [head];
-  return [
-    head,
-    ...subs.map((sub) => theme.fg(
-      'dim',
-      `  ${sub.status === 'running' ? '●' : '○'} ${sub.paneId} · ${sub.status} · ${clip(String(sub.description ?? ''), 70)}`,
-    )),
-  ];
+  return [head, ...items.map((item) => theme.fg('dim', card.row(item)))];
+}
+
+function subsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+  const subs = (data as SubsRegistry | undefined)?.subs;
+  const running = Array.isArray(subs) ? subs.filter((sub) => sub.status === 'running').length : 0;
+  return registryLines(Array.isArray(subs) ? subs : undefined, theme, expanded, {
+    label: 'subagents',
+    unit: 'tracked',
+    ...(running ? { badge: `${running} running` } : {}),
+    row: (sub) => `  ${sub.status === 'running' ? '●' : '○'} ${sub.paneId} · ${sub.status} · ${clip(String(sub.description ?? ''), 70)}`,
+  });
 }
 
-export function terminalsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
+function terminalsLines(data: unknown, theme: RenderTheme, expanded: boolean): string[] {
   const terminals = (data as TerminalsRegistry | undefined)?.terminals;
-  if (!Array.isArray(terminals) || terminals.length === 0) return [theme.fg('dim', 'terminals · none')];
-  const head = `${theme.fg('accent', theme.bold('terminals'))} ${theme.fg('dim', `· ${terminals.length} open`)}`;
-  if (!expanded) return [head];
-  return [
-    head,
-    ...terminals.map((t) => theme.fg('dim', `  ${t.paneId} · ${clip(String(t.label ?? t.cwd ?? ''), 70)}`)),
-  ];
+  return registryLines(Array.isArray(terminals) ? terminals : undefined, theme, expanded, {
+    label: 'terminals',
+    unit: 'open',
+    row: (t) => `  ${t.paneId} · ${clip(String(t.label ?? t.cwd ?? ''), 70)}`,
+  });
 }
 
-export function roleManifestLines(data: unknown, theme: RenderTheme): string[] {
-  const rec = (data ?? {}) as { role?: unknown; manifestVersion?: unknown; tools?: unknown; permissions?: unknown };
+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' || v === 'ask').length;
   const tail = gates > 0 ? theme.fg('warning', ` · ${gates} gated`) : '';
-  return [`${theme.fg('accent', theme.bold('role'))} ${role} ${theme.fg('dim', `v${version} · ${tools} tools`)}${tail}`];
+  // 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}`];
 }
 
-export function approvalLines(data: unknown, theme: RenderTheme): string[] {
+function approvalLines(data: unknown, theme: RenderTheme): string[] {
   const rec = (data ?? {}) as { role?: unknown; tool?: unknown };
   const role = typeof rec.role === 'string' ? rec.role : '?';
   const tool = typeof rec.tool === 'string' ? rec.tool : '?';
@@ -133,7 +138,7 @@ export function approvalLines(data: unknown, theme: RenderTheme): string[] {
 }
 
 /** Reminder custom messages carry the full injected text; restyle without altering it. */
-export function reminderLines(message: unknown, theme: RenderTheme, label: string, expanded: boolean): string[] {
+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)
     : '';
@@ -143,53 +148,37 @@ export function reminderLines(message: unknown, theme: RenderTheme, label: strin
   return [head, ...content.split('\n').map((line) => theme.fg('dim', line))];
 }
 
-/* ── Installation ──────────────────────────────────────────────────── */
+type LineBuilder = (data: unknown, theme: RenderTheme, expanded: boolean) => string[];
 
-function entryCard(
-  build: (data: unknown, theme: RenderTheme, expanded: boolean) => string[],
-): (entry: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent {
-  return (entry, options, theme) => card(build((entry as { data?: unknown } | undefined)?.data, theme, options.expanded));
-}
-
-function messageCard(
-  build: (message: unknown, theme: RenderTheme, expanded: boolean) => string[],
-): (message: unknown, options: { expanded: boolean }, theme: RenderTheme) => RenderComponent {
-  return (message, options, theme) => card(build(message, theme, options.expanded));
-}
-
-/**
- * Register pier's transcript renderers. Returns the custom types actually registered,
- * so the caller can log coverage and tests can assert the degrade path.
- *
- * Why best-effort: entry/message renderers are display-only. A pi build without the
- * API (pre-0.80.4) or a throwing renderer must never break tool registration, so each
- * registration is individually guarded.
- */
+/** Register pier'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: (data: unknown, theme: RenderTheme, expanded: boolean) => string[]): void => {
+  const entry = (type: string, build: LineBuilder): void => {
     if (typeof api.registerEntryRenderer !== 'function') return;
     try {
-      api.registerEntryRenderer(type, entryCard(build));
+      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: (msg: unknown, theme: RenderTheme, expanded: boolean) => string[]): void => {
+  const message = (type: string, build: LineBuilder): void => {
     if (typeof api.registerMessageRenderer !== 'function') return;
     try {
-      api.registerMessageRenderer(type, messageCard(build));
+      api.registerMessageRenderer(type, (msg, options, theme) => card(build(msg, theme, options.expanded)));
       registered.push(type);
     } catch {
-      /* Best effort; the message still reaches the model. */
+      /* A throwing renderer must not break message registration. */
     }
   };
 
-  entry(TODO_EDIT_CUSTOM_TYPE, (data, theme, expanded) => todoEditLines(data, theme, expanded));
-  entry(SUBS_CUSTOM_TYPE, (data, theme, expanded) => subsLines(data, theme, expanded));
-  entry(TERMINALS_CUSTOM_TYPE, (data, theme, expanded) => terminalsLines(data, theme, expanded));
+  entry(TODO_EDIT_CUSTOM_TYPE, todoEditLines);
+  entry(SUBS_CUSTOM_TYPE, subsLines);
+  entry(TERMINALS_CUSTOM_TYPE, terminalsLines);
   entry(ROLE_MANIFEST_CUSTOM_TYPE, (data, theme) => roleManifestLines(data, theme));
   entry(APPROVAL_NEEDED_CUSTOM_TYPE, (data, theme) => approvalLines(data, theme));
   message(TODO_REMINDER_CUSTOM_TYPE, (msg, theme, expanded) => reminderLines(msg, theme, 'todo reminder', expanded));

package/src/role-loader.ts

@@ -1,21 +1,16 @@
 /**
- * Layer 2 Week 1: load role manifests (2026-08-18); v1.1 (2026-08-22) adds two user-directory layers.
+ * Role manifest loading, three layers in order: workspace `<cwd>/.pi-herdr/roles/` (travels with the clone)
+ * → user `~/.pi/agent/herdr-pi/roles/` → bundled `src/roles/`.
  *
- * Lookup order (v1.1, user-approved):
- *  1. Workspace-level `<cwd>/.pi-herdr/roles/<name>.json` (travels with the clone and is team-shared)
- *  2. User-global `~/.pi/agent/herdr-pi/roles/<name>.json` (personal preference across repositories)
- *  3. Bundled `src/roles/` as the fallback shipped with this package
+ * 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.
  *
- * Built-in names remain reserved (master / worker-default): reject collisions in user/workspace layers—D83 mirror.
- * Tests and the D82 stance are anchored to bundled manifests; allowing overrides would break those guarantees.
- *
- * Role names are restricted to [a-z0-9-]—this prevents path traversal and avoids touching disk for invalid names.
- * The manifest role field must match the filename to prevent attaching the wrong manifest.
- * Validation failures are classified as: unreadable = ROLE_NOT_FOUND (reported only after trying every layer);
- * parsed but invalid JSON/validation/name = INVALID_ROLE_CONFIG (report immediately at the hit layer rather than
- * silently falling through, because silence would hide a user editing a manifest incorrectly).
+ * 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 } from 'node:fs';
+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';
@@ -23,7 +18,6 @@ import { userRolesDir, workspaceRolesDir as layoutWorkspaceRolesDir } from './st
 
 export { userRolesDir };
 
-/** Bundled manifest directory (`src/roles/`). */
 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). */
@@ -31,7 +25,6 @@ export function workspaceRolesDir(baseDir?: string): string {
   return layoutWorkspaceRolesDir(baseDir ?? process.cwd());
 }
 
-/** Reserved built-in names (no user layer may override them). */
 export const RESERVED_ROLE_NAMES: readonly string[] = ['master', 'worker-default'];
 
 const ROLE_NAME_RE = /^[a-z0-9-]+$/;
@@ -65,36 +58,50 @@ const defaultLayerRead: LayerReader = (dir, fileName) => {
 export interface LoadRoleOptions {
   /** Inject one reader (legacy shape: only the bundled layer is hit, for test compatibility). */
   read?: RoleReader;
-  /** Inject layered readers (v1.1). */
   layerRead?: LayerReader;
   /** Base directory for the workspace layer (defaults to process.cwd()). */
   baseDir?: string;
-  /**
-   * Direct built-in lookup: used by master's self-application (WS-D7). Reserved names skip user layers and
-   * collision checks and always load the bundled manifest. Otherwise, a workspace master.json could cause
-   * self-application to fail open and silently lose master's manifest (the boundary caught by d11 live testing).
-   */
+  /** 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;
 }
 
-/** Resolve lookup layers in order: workspace → user-global → bundled (each layer has {label, dir}). */
-export function roleLayers(opts?: { baseDir?: string }): Array<{ label: string; dir: string }> {
+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 (.pi-herdr/roles/)', dir: workspaceRolesDir(base) },
-    { label: `user (${'~/.pi/agent/herdr-pi/roles/'})`, dir: userRolesDir() },
+    // userDir lets tests isolate from the real ~/.pi.
+    { label: `user (${'~/.pi/agent/herdr-pi/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 不存在或名字非法（[a-z0-9-]+）: ${JSON.stringify(name)}`);
   }
   const fileName = `${name}.json`;
 
-  // Legacy single reader: use bundled-layer semantics so existing tests/composer injection paths remain intact.
   if (opts?.read && !opts.layerRead) {
     let text: string;
     try {
@@ -109,11 +116,9 @@ export function loadRoleConfig(name: string, opts?: LoadRoleOptions): RoleManife
   const layerRead = opts?.layerRead ?? defaultLayerRead;
   let layers = roleLayers({ baseDir: opts?.baseDir });
 
-  // Direct built-in lookup (self-application): inspect only the bundled layer, ignoring user-layer bait/collisions.
   if (opts?.builtinDirect && RESERVED_ROLE_NAMES.includes(name)) {
     layers = [layers[2]];
   } else if (RESERVED_ROLE_NAMES.includes(name)) {
-    // Reserved built-in name: reject workspace/user collisions instead of silently overriding built-in semantics.
     for (const layer of layers.slice(0, 2)) {
       if (layerRead(layer.dir, fileName) != null) {
         throw new RoleLoaderError(

package/src/role-manifest.ts

@@ -1,11 +1,8 @@
 /**
- * Layer 2 Week 1: role manifest types and validator (D76 v2; 2026-08-18).
- *
- * Mirrors the contract in `schemas/role-manifest.schema.json` (the JSON Schema is the contract document;
- * runtime validation is hand-written with zero dependencies so workers carry no ajv overhead).
- *
- * Strict contract: report unknown top-level keys to prevent typos such as "rulez" from silently failing;
- * collect all errors in one pass so manifests can be repaired efficiently.
+ * Role manifest file format + validator; the contract document is `schemas/role-manifest.schema.json`.
+ * Validation is hand-written with zero dependencies so workers carry no ajv overhead. Strict: unknown
+ * top-level keys are reported (a typo like "rulez" must not silently fail) and every issue is
+ * collected in one pass so a manifest can be repaired in one go.
  */
 export type PermissionAction = 'allow' | 'ask' | 'deny';
 export type TodosMode = 'serial' | 'parallel';
@@ -14,24 +11,20 @@ export type UnknownToolStance = 'allow' | 'deny';
 
 export interface RoleManifest {
   role: string;
-  /** Semantic version x.y.z (for tracing manifest evolution; P2). */
   version: string;
-  /**
-   * WS-D10: route models by role using `provider/model` (advisor delegates higher-level third-party judgment).
-   * Omitted means follow the process default (master/worker leave it unset); spawn injects `--provider/--model`.
-   */
+  /** WS-D10: `provider/model` routing by role; omitted means follow the process default (spawn injects `--provider/--model`). */
   model?: string;
   description?: string;
+  /** P0 per-role guidelines (RFC §4.6): constraints a tool set cannot express; injected as a prompt section. */
+  guidelines?: string[];
   manifest: {
-    /** Baseline tools (non-empty; must include todo_write + ask_user_question for coordination). */
     tools: string[];
     /** Three-state permissions; `*` supplies the default; omitted means `{"*":"allow"}`. */
     rules?: Record<string, PermissionAction>;
     /**
-     * D82 unknownTools: stance for tools outside the manifest (default deny is the safe default).
-     * master/worker = allow (user-installed extensions are visible and usable by default—install grants access);
-     * custom roles default to deny. `*` in rules and this stance cover separate axes: visibility vs enforcement.
-     * Excluded families (such as worker's subagent/terminal) need explicit deny to remain blocked under allow.
+     * D82 stance for tools outside the manifest (default deny; master/worker = allow — install grants
+     * the user's extension access). Separate axis from `rules['*']`: visibility vs enforcement.
+     * Excluded families (worker's subagent/terminal) need an explicit deny to stay blocked under allow.
      */
     unknownTools?: UnknownToolStance;
   };
@@ -64,35 +57,41 @@ export function validateRoleManifest(input: unknown): ValidateResult {
     return { ok: false, code: 'INVALID_ROLE_CONFIG', issues: ['role 档案必须是 JSON 对象'] };
   }
 
-  /* ── Top-level keys ── */
-  const KNOWN_TOP = new Set(['role', 'version', 'model', 'description', 'manifest', 'services']);
+  const KNOWN_TOP = new Set(['role', 'version', 'model', 'description', 'guidelines', 'manifest', 'services']);
   for (const k of Object.keys(input)) {
     if (!KNOWN_TOP.has(k)) issues.push(`未知顶层键 "${k}"（契约外字段，检查拼写）`);
   }
 
-  /* ── role name ── */
   if (typeof input.role !== 'string' || !ROLE_NAME_RE.test(input.role)) {
     issues.push(`role 必须是 [a-z0-9-]+ 字符串，收到 ${JSON.stringify(input.role)}`);
   }
 
-  /* ── version (P2 semver) ── */
   if (typeof input.version !== 'string' || !SEMVER_RE.test(input.version)) {
     issues.push(`version 必须是 x.y.z 三段数字（如 1.0.0），收到 ${JSON.stringify(input.version)}`);
   }
 
-  /* ── model (WS-D10: provider/model role routing; optional) ── */
   if (input.model !== undefined) {
     if (typeof input.model !== 'string' || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(input.model)) {
       issues.push(`model 必须是 provider/model 形态（如 opencode-go/muse-spark-1.2-contributor），收到 ${JSON.stringify(input.model)}`);
     }
   }
 
-  /* ── optional description ── */
   if (input.description !== undefined && typeof input.description !== 'string') {
     issues.push('description 必须是字符串');
   }
 
-  /* ── manifest ── */
+  if (input.guidelines !== undefined) {
+    if (!Array.isArray(input.guidelines)) {
+      issues.push('guidelines 必须是字符串数组');
+    } else if (input.guidelines.length === 0) {
+      issues.push('guidelines 为空数组时请直接省略该字段');
+    } else if (!input.guidelines.every((g) => typeof g === 'string' && g.trim() !== '')) {
+      issues.push('guidelines 的每一项必须是非空字符串');
+    } else if (input.guidelines.length > 20) {
+      issues.push('guidelines 最多 20 条（prompt 预算保护）');
+    }
+  }
+
   const m = input.manifest;
   if (!isPlainObject(m)) {
     issues.push('manifest 必须是对象');
@@ -102,12 +101,10 @@ export function validateRoleManifest(input: unknown): ValidateResult {
       if (!KNOWN_MANIFEST.has(k)) issues.push(`manifest 内未知键 "${k}"`);
     }
 
-    // D82 unknownTools: enum validation; omitted means deny (safe default).
     if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
       issues.push(`manifest.unknownTools 必须是 allow/deny，收到 ${JSON.stringify(m.unknownTools)}`);
     }
 
-    // tools must be a unique, non-empty string array containing coordination tools; an empty array also reports the omissions.
     const tools = m.tools;
     if (!Array.isArray(tools) || !tools.every((t) => typeof t === 'string' && TOOL_KEY_RE.test(t))) {
       issues.push('manifest.tools 必须是非空字符串数组（工具名 [a-z0-9_-]）');
@@ -122,7 +119,6 @@ export function validateRoleManifest(input: unknown): ValidateResult {
       }
     }
 
-    // rules accept three-state values; each key must be a tool name or *.
     if (m.rules !== undefined) {
       if (!isPlainObject(m.rules)) {
         issues.push('manifest.rules 必须是对象');
@@ -137,7 +133,6 @@ export function validateRoleManifest(input: unknown): ValidateResult {
     }
   }
 
-  /* ── services ── */
   if (input.services !== undefined) {
     if (!isPlainObject(input.services)) {
       issues.push('services 必须是对象');

package/src/role-state.ts

@@ -0,0 +1,119 @@
+/**
+ * P0 (RFC docs/rfc-pi-0.86-dynamic-tools.md §4): mutable role state for mid-session switching. pi
+ * 0.86 records `setActiveTools` deltas in the transcript, so a switch survives resume and branch
+ * navigation; this module owns pier's half — replaying the gate manifest from the last
+ * `pi-herdr.role-manifest` entry and planning the active-set transition.
+ */
+import type { PermissionAction, UnknownToolStance } from './role-manifest.ts';
+import type { RuntimeRoleManifest } from './tool-gate.ts';
+import { filterToolsByStance } from './tool-gate.ts';
+
+/** Shape persisted in ROLE_MANIFEST_CUSTOM_TYPE entries: the runtime manifest plus the payload version and
+ *  the switch provenance. `version` is the payload discriminator and `manifestVersion` the manifest semver
+ *  — replay must not confuse the two. */
+export type RoleManifestRecord = Omit<RuntimeRoleManifest, 'version'> & {
+  version: 1;
+  manifestVersion?: string;
+  /** 'switch' records a mid-session switch; the session_start anchor write omits it (env origin). */
+  origin?: 'switch';
+  switchedBy?: string;
+  ts?: number;
+};
+
+/** State carried across a process for the armed role system; manifest==null means unarmed (bare pi). */
+export interface RoleState {
+  manifest: RuntimeRoleManifest | null;
+  origin: 'env' | 'switch';
+  switchedBy: string | null;
+  switchedAt: number | null;
+}
+
+export function initialRoleState(manifest: RuntimeRoleManifest | null): RoleState {
+  return { manifest, origin: 'env', switchedBy: null, switchedAt: null };
+}
+
+/** Last `pi-herdr.role-manifest` record on the branch, or null. Session entries are pi JSONL objects
+ *  ({ type: 'custom', customType, data }); unknown shapes are skipped, not fatal — replay must never break
+ *  session startup. */
+export function latestRoleManifestRecord(entries: readonly unknown[]): RoleManifestRecord | null {
+  let found: RoleManifestRecord | null = null;
+  for (const raw of entries) {
+    const entry = raw as { type?: unknown; customType?: unknown; data?: unknown };
+    if (entry?.type !== 'custom' || entry.customType !== 'pi-herdr.role-manifest') continue;
+    const data = entry.data as Partial<RoleManifestRecord> | undefined;
+    if (
+      !data ||
+      typeof data.role !== 'string' ||
+      !Array.isArray(data.tools) ||
+      !data.tools.every((t) => typeof t === 'string')
+    ) {
+      continue;
+    }
+    const guidelines = Array.isArray(data.guidelines)
+      ? data.guidelines.filter((g): g is string => typeof g === 'string')
+      : [];
+    const rawPermissions = data.permissions;
+    found = {
+      version: 1,
+      role: data.role,
+      manifestVersion: typeof data.manifestVersion === 'string' ? data.manifestVersion : undefined,
+      tools: data.tools as string[],
+      permissions:
+        rawPermissions && typeof rawPermissions === 'object' && !Array.isArray(rawPermissions)
+          ? (rawPermissions as RuntimeRoleManifest['permissions'])
+          : {},
+      unknownTools: data.unknownTools === 'allow' ? 'allow' : 'deny',
+      guidelines: guidelines.length > 0 ? guidelines : undefined,
+      origin: data.origin === 'switch' ? 'switch' : undefined,
+      switchedBy: typeof data.switchedBy === 'string' ? data.switchedBy : undefined,
+      ts: typeof data.ts === 'number' ? data.ts : undefined,
+    };
+  }
+  return found;
+}
+
+export function manifestFromRecord(rec: RoleManifestRecord): RuntimeRoleManifest {
+  return {
+    role: rec.role,
+    version: rec.manifestVersion,
+    tools: rec.tools,
+    permissions: rec.permissions,
+    unknownTools: rec.unknownTools,
+    ...(rec.guidelines && rec.guidelines.length > 0 ? { guidelines: rec.guidelines } : {}),
+  };
+}
+
+/** Whether the record differs from the state that would be written now (drives change-only writes). */
+export function roleRecordDiffers(rec: RoleManifestRecord | null, state: RoleState): boolean {
+  const m = state.manifest;
+  if (!m) return false;
+  if (!rec) return true;
+  return rec.role !== m.role || JSON.stringify(rec.tools) !== JSON.stringify(m.tools);
+}
+
+/** Switch plan: widening (needs human confirm when driven by /pier-role) + diff summary. */
+export interface RoleSwitchPlan {
+  widening: boolean;
+  added: string[];
+  removed: string[];
+}
+
+export function planRoleSwitch(oldTools: readonly string[], newTools: readonly string[]): RoleSwitchPlan {
+  const oldSet = new Set(oldTools);
+  const newSet = new Set(newTools);
+  const added = newTools.filter((t) => !oldSet.has(t));
+  const removed = oldTools.filter((t) => !newSet.has(t));
+  return { widening: added.length > 0, added, removed };
+}
+
+/** Active set for a switch, over ALL registered tools rather than the current active set: a switch may
+ *  re-admit tools an earlier session_start prune removed, which intersection semantics would lose. Stance
+ *  handling is shared with planActiveTools (tool-gate.ts); the empty result is NOT a no-op here — a switch
+ *  to a role with no overlap is a legitimate shrink. */
+export function planSwitchActiveTools(
+  manifestTools: readonly string[],
+  registeredToolNames: readonly string[],
+  opts?: { unknownTools?: UnknownToolStance; permissions?: Record<string, PermissionAction> },
+): string[] {
+  return filterToolsByStance(manifestTools, registeredToolNames, opts);
+}