pi-pier 0.2.7 → 0.3.1

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(
@@ -143,7 +148,8 @@ function parseAndValidate(name: string, fileName: string, text: string, layerLab
     throw new RoleLoaderError('INVALID_ROLE_CONFIG', `role "${name}"（${layerLabel}）不是合法 JSON: ${(err as Error).message}`);
   }
   const result = validateRoleManifest(parsed);
-  if (!result.ok) {
+  // `ok === false` (instead of `!ok`) is required to narrow without strictNullChecks.
+  if (result.ok === false) {
     throw new RoleLoaderError(
       'INVALID_ROLE_CONFIG',
       `role "${name}"（${layerLabel}）校验失败:\n${result.issues.map((i) => `  - ${i}`).join('\n')}`,

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;
   };
@@ -58,45 +51,47 @@ function isPlainObject(v: unknown): v is Record<string, unknown> {
   return typeof v === 'object' && v !== null && !Array.isArray(v);
 }
 
-function isPosInt(v: unknown): boolean {
-  return typeof v === 'number' && Number.isInteger(v) && v > 0;
-}
-
 export function validateRoleManifest(input: unknown): ValidateResult {
   const issues: string[] = [];
   if (!isPlainObject(input)) {
     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 必须是对象');
@@ -106,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_-]）');
@@ -126,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 必须是对象');
@@ -141,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);
+}

package/src/routing-telemetry.ts

@@ -0,0 +1,136 @@
+/**
+ * Phase 0 routing telemetry (RFC docs/rfc-jev-role-routing.md §8): observation only, zero behavior
+ * change. Three row kinds answer the decision questions before the grants collapse (phase 1) and the
+ * jev router (phase 2) are built — spawn profile, deny hits, axis usage.
+ *
+ * Privacy contract: task text NEVER enters telemetry — only taskSha8 (correlatable, not reversible)
+ * and tool/role names. Planners are pure and sessionId-free; the central append (index.ts) stamps the
+ * session id once, and every append is best-effort.
+ */
+import { createHash } from 'node:crypto';
+
+type SpawnProfileRecord = {
+  kind: 'spawn';
+  ts: number;
+  roleExplicit: boolean;
+  role: string;
+  /** Model-suggested extras from the spawn `allowed_tools` param. */
+  allowedTools: string[];
+  manifestTools: string[];
+  /** sha256(task)[0:8] — correlates spawns without persisting the task text. */
+  taskSha8: string;
+};
+
+type DenyHitRecord = {
+  kind: 'deny';
+  ts: number;
+  role: string;
+  tool: string;
+};
+
+type AxisUsageRecord = {
+  kind: 'axis-usage';
+  ts: number;
+  files: number;
+  parsed: number;
+  invalid: number;
+  askEntries: number;
+  stanceAllow: number;
+  stanceDeny: number;
+  /** [role, tool] pairs carrying an explicit deny — the clamp-table design data. */
+  explicitDenies: Array<[string, string]>;
+};
+/** sessionId-free: the central append stamps it into RoutingTelemetryRow. */
+export type RoutingTelemetryRecord = SpawnProfileRecord | DenyHitRecord | AxisUsageRecord;
+
+export type RoutingTelemetryRow =
+  | ({ sessionId: string } & SpawnProfileRecord)
+  | ({ sessionId: string } & DenyHitRecord)
+  | ({ sessionId: string } & AxisUsageRecord);
+
+export function taskFingerprint(task: string): string {
+  return createHash('sha256').update(task).digest('hex').slice(0, 8);
+}
+
+export function planSpawnProfileRow(opts: {
+  now: number;
+  roleExplicit: boolean;
+  role: string;
+  allowedTools: readonly string[];
+  manifestTools: readonly string[];
+  task: string;
+}): SpawnProfileRecord {
+  return {
+    kind: 'spawn',
+    ts: opts.now,
+    roleExplicit: opts.roleExplicit,
+    role: opts.role,
+    allowedTools: [...opts.allowedTools],
+    manifestTools: [...opts.manifestTools],
+    taskSha8: taskFingerprint(opts.task),
+  };
+}
+
+export function planDenyHitRow(opts: {
+  now: number;
+  role: string;
+  tool: string;
+}): DenyHitRecord {
+  return { kind: 'deny', ts: opts.now, role: opts.role, tool: opts.tool };
+}
+
+/**
+ * Fold role-file texts into the axis-usage summary. A malformed file counts as invalid and never
+ * fails the scan. Shapes are mirrored, not imported, so telemetry cannot break on schema drift.
+ */
+export function scanRoleAxisUsage(opts: {
+  now: number;
+  files: ReadonlyArray<{ name: string; text: string }>;
+}): AxisUsageRecord {
+  let parsed = 0;
+  let invalid = 0;
+  let askEntries = 0;
+  let stanceAllow = 0;
+  let stanceDeny = 0;
+  const explicitDenies: Array<[string, string]> = [];
+  for (const file of opts.files) {
+    let doc: {
+      role?: unknown;
+      manifest?: { unknownTools?: unknown; rules?: Record<string, unknown> | undefined };
+    };
+    try {
+      doc = JSON.parse(file.text) as typeof doc;
+    } catch {
+      invalid += 1;
+      continue;
+    }
+    // Schema contract: only role + manifest are required. `rules` may be omitted (implicit
+    // {"*":"allow"}) and unknownTools defaults to deny, so a minimal role still counts as parsed.
+    if (typeof doc.role !== 'string' || typeof doc.manifest !== 'object' || doc.manifest === null) {
+      invalid += 1;
+      continue;
+    }
+    parsed += 1;
+    if (doc.manifest.unknownTools === 'allow') stanceAllow += 1;
+    else stanceDeny += 1;
+    const rules =
+      typeof doc.manifest.rules === 'object' && doc.manifest.rules !== null
+        ? doc.manifest.rules
+        : ({ '*': 'allow' } as Record<string, unknown>);
+    for (const [tool, action] of Object.entries(rules)) {
+      if (action === 'ask') askEntries += 1;
+      else if (action === 'deny' && tool !== '*') explicitDenies.push([doc.role, tool]);
+    }
+  }
+  return {
+    kind: 'axis-usage',
+    ts: opts.now,
+    files: opts.files.length,
+    parsed,
+    invalid,
+    askEntries,
+    stanceAllow,
+    stanceDeny,
+    explicitDenies,
+  };
+}

package/src/runtime-policy.ts

@@ -1,66 +1,48 @@
 /**
- * Centralized runtime policy and timeouts.
- * 
- * Why: Prevents drift between hardcoded literals and environment overrides;
- * makes timing behavior explicit and testable.
+ * Every field is fed by the `PIER_OPTIONS` registry, so the numbers cannot drift from
+ * `/pier-config doctor`; an out-of-range value warns and falls back to the registry default.
  */
+import { PIER_OPTIONS, pierOption, type PolicyField } from './pier-options.ts';
 
 export interface RuntimePolicy {
-  /** Subagent overall timeout (ms) */
   readonly subagentTimeoutMs: number
-  /** Subagent GC tick interval (ms) */
   readonly gcTickMs: number
-  /** Poll interval for subagent state observation (ms) */
   readonly pollIntervalMs: number
-  /** Stale check cadence (turns) */
-  readonly staleCadenceTurns: number
-  /** Settlement notice window / machine-inject grace / takeover idle (ms) */
+  /** Settlement notice window / machine-inject grace / takeover idle */
   readonly settlementWindowMs: number
-  /** Post-settle observation window before auto-consume (ms) */
+  /** Post-settle observation window before auto-consume */
   readonly observationWindowMs: number
-  /** Foreground patience before background promotion (ms) */
   readonly foregroundPatienceMs: number
-  /** Default session TTL (seconds) */
   readonly sessionTtlSeconds: number
-  /** Terminal read maximum bytes */
-  readonly terminalReadMaxBytes: number
-  /** Git operation timeout (ms) */
   readonly gitTimeoutMs: number
-  /** Subagent pane pipe readiness wait (ms) */
+  /** Subagent pane pipe readiness wait */
   readonly readinessTimeoutMs: number
 }
 
-function parseEnvInt(key: string, defaultValue: number, min: number = 0): number {
-  const raw = process.env[key]
-  if (!raw) return defaultValue
-  
-  const parsed = Number.parseInt(raw, 10)
-  if (!Number.isFinite(parsed) || parsed < min) {
-    console.warn(`Invalid ${key}="${raw}", using default ${defaultValue}`)
-    return defaultValue
+function policyValue(field: PolicyField): number {
+  const spec = PIER_OPTIONS.find((o) => o.policy === field);
+  if (!spec) throw new Error(`no PIER_OPTIONS entry feeds RuntimePolicy.${field}`);
+  const fallback = Number(spec.fallback);
+  const raw = pierOption(spec.name);
+  if (raw === undefined) return fallback;
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < (spec.min ?? 0)) {
+    console.warn(`Invalid ${spec.name}="${raw}", using default ${spec.fallback}`);
+    return fallback;
   }
-  
-  return parsed
+  return parsed;
 }
 
 export function createRuntimePolicy(overrides?: Partial<RuntimePolicy>): RuntimePolicy {
-  return {
-    subagentTimeoutMs: overrides?.subagentTimeoutMs ?? parseEnvInt('PIER_SUBAGENT_TIMEOUT_MS', 600_000, 1000),
-    gcTickMs: overrides?.gcTickMs ?? parseEnvInt('PIER_GC_TICK_MS', 30_000, 1000),
-    pollIntervalMs: overrides?.pollIntervalMs ?? parseEnvInt('PIER_POLL_INTERVAL_MS', 30_000, 1000),
-    staleCadenceTurns: overrides?.staleCadenceTurns ?? parseEnvInt('PIER_STALE_CADENCE_TURNS', 3, 1),
-    settlementWindowMs: overrides?.settlementWindowMs ?? parseEnvInt('PIER_SETTLEMENT_WINDOW_MS', 60_000, 0),
-    observationWindowMs: overrides?.observationWindowMs ?? parseEnvInt('PIER_OBSERVATION_WINDOW_MS', 30_000, 0),
-    foregroundPatienceMs: overrides?.foregroundPatienceMs ?? parseEnvInt('PIER_FOREGROUND_PATIENCE_MS', 300_000, 0),
-    sessionTtlSeconds: overrides?.sessionTtlSeconds ?? parseEnvInt('PIER_SESSION_TTL_SECONDS', 600, 0),
-    terminalReadMaxBytes: overrides?.terminalReadMaxBytes ?? parseEnvInt('TERM_READ_MAX', 4096, 1),
-    gitTimeoutMs: overrides?.gitTimeoutMs ?? parseEnvInt('PIER_GIT_TIMEOUT_MS', 10_000, 1),
-    readinessTimeoutMs: overrides?.readinessTimeoutMs ?? parseEnvInt('PIER_READY_TIMEOUT_MS', 30_000, 1000),
+  const policy = {} as { -readonly [K in keyof RuntimePolicy]: number };
+  for (const spec of PIER_OPTIONS) {
+    if (spec.policy) policy[spec.policy] = policyValue(spec.policy);
   }
+  for (const [key, value] of Object.entries(overrides ?? {})) {
+    if (typeof value === 'number') policy[key as keyof RuntimePolicy] = value;
+  }
+  return policy;
 }
 
-/**
- * Singleton runtime policy for production use.
- * Tests should inject via createRuntimePolicy().
- */
+/** Singleton for production; tests inject via createRuntimePolicy(). */
 export const runtimePolicy = createRuntimePolicy()