pi-pier 0.3.0 → 0.3.1

package/src/index-gates.ts

@@ -0,0 +1,124 @@
+/**
+ * Human-gate reporting: coalesces every blocking prompt (pier's ask tool, pi's own ctx.ui dialogs,
+ * external herdr:blocked producers) into ONE blocked edge.
+ *
+ * Depth semantics: only the 0→1 transition reports blocked (and marks the ask flag); only the 1→0
+ * transition restores working/idle. While the depth is positive, working/idle reports are dropped
+ * so the pane stays blocked for the whole dialog. */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { HerdrClientLike } from './herdr-client.ts';
+
+/** pi surface pieces the gate runtime touches (ui_prompt events postdate the pinned devDependency). */
+type GatePi = ExtensionAPI & {
+  on?: (name: 'ui_prompt_start' | 'ui_prompt_end', handler: (event: unknown) => void) => void;
+};
+
+/** Only inherently human-blocking kinds open the gate; `custom` covers resident overlays too (D97). */
+const GATING_PROMPT_KINDS = new Set(['select', 'confirm', 'input', 'editor']);
+
+export interface GateRuntimeDeps {
+  pi: ExtensionAPI;
+  client: HerdrClientLike;
+  /** Collapse the todo widget to one line while a gate is open; restore on release. */
+  rerenderWidget: () => void;
+  /** True while an agent turn is active (drives the state reported on release). */
+  isAgentActive: () => boolean;
+  /** Idle activity text (idle role badge / current todo) reported with the idle state. */
+  idleMessage: () => string | null;
+  /** Working activity text (current todo) reported when a gate releases mid-turn. */
+  workingMessage: () => string | null;
+}
+
+export interface GateRuntime {
+  depth(): number;
+  /** Gate-aware agent-state report (blocked depth swallows working/idle). */
+  report(state: 'working' | 'idle', activity: string | null): void;
+  /** Open one gate; true when this call opened the outer one. */
+  enter(label: string | null): boolean;
+  /** Close one gate; an unmatched release is ignored. True when the outer gate closed. */
+  exit(): boolean;
+  /** enter/exit + publish the herdr:blocked edge for pier's own gates. */
+  publish(active: boolean, label: string | null): void;
+}
+
+export function createGateRuntime(d: GateRuntimeDeps): GateRuntime {
+  const { client } = d;
+  let blockedDepth = 0;
+
+  function report(state: 'working' | 'idle', activity: string | null): void {
+    if (!client.available || blockedDepth > 0) return;
+    const message = activity ?? (state === 'idle' ? d.idleMessage() : null);
+    client.reportAgent(state, message).catch(() => {});
+  }
+
+  function enter(label: string | null): boolean {
+    blockedDepth += 1;
+    if (blockedDepth > 1) return false;
+    if (client.available) client.reportAgent('blocked', label).catch(() => {});
+    // D95: human-gate marker lets the workbench heatmap distinguish ask from block.
+    if (label) void client.reportAskFlag(label).catch(() => {});
+    d.rerenderWidget();
+    return true;
+  }
+
+  function exit(): boolean {
+    if (blockedDepth === 0) return false;
+    blockedDepth -= 1;
+    d.rerenderWidget();
+    if (blockedDepth > 0) return false;
+    report(d.isAgentActive() ? 'working' : 'idle', d.isAgentActive() ? d.workingMessage() : null);
+    void client.reportAskFlag(null).catch(() => {});
+    return true;
+  }
+
+  // emit() is synchronous; this flag stops our own listener from double-counting depth.
+  let publishing = false;
+  function emitHerdrBlocked(active: boolean, label: string | null): void {
+    publishing = true;
+    try {
+      d.pi.events.emit(
+        'herdr:blocked',
+        active ? { active: true, ...(label ? { label } : {}) } : { active: false },
+      );
+    } finally {
+      publishing = false;
+    }
+  }
+
+  d.pi.events.on('herdr:blocked', (data) => {
+    if (publishing) return;
+    const active = typeof data === 'object' && data !== null && 'active' in data && data.active === true;
+    if (active) {
+      enter(typeof data === 'object' && 'label' in data && typeof data.label === 'string' ? data.label : null);
+    } else {
+      exit();
+    }
+  });
+
+  const gatePi = d.pi as GatePi;
+  gatePi.on?.('ui_prompt_start', (event) => {
+    const rec = (event ?? {}) as { kind?: unknown; title?: unknown };
+    const title = typeof rec.title === 'string' && rec.title.trim() ? rec.title.trim() : null;
+    const kind = typeof rec.kind === 'string' ? rec.kind : 'prompt';
+    if (!GATING_PROMPT_KINDS.has(kind)) return;
+    const label = title ?? kind;
+    // The ask tool opens its own gate first, so this is usually a nested no-op;
+    // prompts from other extensions or pi core open the gate here.
+    if (enter(label)) emitHerdrBlocked(true, label);
+  });
+  gatePi.on?.('ui_prompt_end', () => {
+    if (exit()) emitHerdrBlocked(false, null);
+  });
+
+  return {
+    depth: () => blockedDepth,
+    report,
+    enter,
+    exit,
+    publish(active: boolean, label: string | null): void {
+      if (active) enter(label);
+      else exit();
+      emitHerdrBlocked(active, label);
+    },
+  };
+}

package/src/index-locks.ts

@@ -1,10 +1,5 @@
-/**
- * M18 file write-lock installer (soft veto / hard block).
- *
- * Why: lock acquire/release/command lived in the composition root next to
- * unrelated session wiring. The installer owns the three pi hooks and the
- * held-lock set; fail-open on agent.list remains the collaboration policy.
- */
+/** M18 file write-lock installer (soft veto / hard block): owns the three pi hooks and the
+ *  held-lock set; fail-open on agent.list is the collaboration policy. */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import {
   acquireTokensFor,

package/src/index-master.ts

@@ -1,22 +1,21 @@
-/**
- * Master-process plugin mount (cordis loader + terminal/todo/subagent).
- *
- * Why: worker must never load bootstrap/subagent-scope (C3). This module is
- * dynamically imported only from the master branch of index.ts.
- */
+/** Master-process plugin mount (cordis loader + terminal/todo/subagent), dynamically imported from
+ *  the master branch of index.ts only: a worker must never load bootstrap/subagent-poller (C3). */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Server } from 'node:net';
 import { PiSurface } from './pi-surface.ts';
 import { createCordisApp } from './bootstrap.ts';
-import { disposeSessionRoot } from './subagent-scope.ts';
-import terminalPlugin from './core/terminal.ts';
-import todoPlugin from './core/todo.ts';
-import subagentPlugin from './core/subagent.ts';
+import { disposeSessionRoot } from './subagent-poller.ts';
+import terminalPlugin from './plugins/terminal.ts';
+import todoPlugin from './plugins/todo.ts';
+import subagentPlugin from './plugins/subagent.ts';
 import type { HerdrClientLike, HerdrEnv } from './herdr-client.ts';
+import type { JevRuntime } from './jev-client.ts';
+import type { RoutingTelemetryRecord } from './routing-telemetry.ts';
 import type { TodosService } from './todos-service.ts';
-import type { TodoUiSlot } from './core/todo.ts';
-import type { SubagentPortBox } from './subagent-port.ts';
+import type { TodoUiSlot } from './plugins/todo.ts';
+import type { SubagentPortBox } from './subagent-core.ts';
+import type { SubagentDeps } from './plugins/subagent.ts';
 
 export interface MasterPluginMount {
   pi: ExtensionAPI;
@@ -37,6 +36,10 @@ export interface MasterPluginMount {
   claimSettleNotice: (key: string) => boolean;
   isCompactionInFlight?: () => boolean;
   isIntentionalAbort?: () => boolean;
+  /** Optional jev seam for subagent settle attribution (fail-open when absent). */
+  jev?: { ask: JevRuntime['ask']; getMinConfidence: () => number };
+  /** Phase 0 routing telemetry append (RFC rfc-jev-role-routing §8); absent in tests. */
+  appendRoutingLog?: (row: RoutingTelemetryRecord) => void;
 }
 
 async function loadEntry(
@@ -62,8 +65,7 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
   // strip-types) and misses pi's typebox alias. HMR-only; production uses plugin().
   const useLoader = cordisApp.loaderReady && cordisApp.hmrActive;
 
-  // Pipe server is created in the common segment; closing it from a core
-  // plugin would kill it on hmr reload (d87).
+  // Pipe server is created in the common segment; closing it from a core plugin would kill it on hmr reload (d87).
   sessionRoot.effect(() => () => {
     if (m.pipeServerBox.current) {
       try { m.pipeServerBox.current.close(); } catch { /* already closed */ }
@@ -80,7 +82,7 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
   };
   sessionRoot.provide('pi-herdr.terminal-deps', terminalDeps);
 
-  await loadEntry(sessionRoot, useLoader, './core/terminal.ts', terminalPlugin);
+  await loadEntry(sessionRoot, useLoader, './plugins/terminal.ts', terminalPlugin);
 
   sessionRoot.provide('pi-herdr.todo-deps', {
     todos: m.todos,
@@ -99,8 +101,10 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
       isIntentionalAbort: m.isIntentionalAbort,
     },
   });
-  await loadEntry(sessionRoot, useLoader, './core/todo.ts', todoPlugin);
+  await loadEntry(sessionRoot, useLoader, './plugins/todo.ts', todoPlugin);
 
+  // D98 regression guard: `satisfies` makes tsc reject a missing/mistyped key here — the bag is
+  // consumed untyped by plugins/subagent.ts, and the fe99252 crash was exactly a dropped key.
   sessionRoot.provide('pi-herdr.subagent-deps', {
     client: m.client,
     env: m.env,
@@ -114,8 +118,10 @@ export async function mountMasterPlugins(m: MasterPluginMount): Promise<void> {
     withReconcileNotes: m.withReconcileNotes,
     claimSettleNotice: m.claimSettleNotice,
     terminalState: terminalDeps.state,
-  });
-  await loadEntry(sessionRoot, useLoader, './core/subagent.ts', subagentPlugin);
+    ...(m.jev ? { jev: m.jev } : {}),
+    ...(m.appendRoutingLog ? { logRouting: m.appendRoutingLog } : {}),
+  } satisfies SubagentDeps);
+  await loadEntry(sessionRoot, useLoader, './plugins/subagent.ts', subagentPlugin);
 
   m.pi.on('session_shutdown', () => {
     void disposeSessionRoot(sessionRoot);

package/src/index-notices.ts

@@ -1,14 +1,23 @@
 /**
- * D92 settlement-notice buffer (busy-run collapse).
- *
- * Why: `sendUserMessage(followUp)` only delivers when the agent has no more
- * tool calls — a long master run queues every settlement and floods at the
- * end. Buffer while busy; flush at turn_end (steer) / agent_settled (followUp).
- */
-import { NOTICE_MAX_SHOWN, collapseNotices } from './notice-buffer.ts';
+ * D92 settlement-notice buffer: `sendUserMessage(followUp)` only delivers when the agent has no
+ * more tool calls, so a long master run would queue every settlement and flood at the end. Buffer
+ * while busy; flush at turn_end (steer) / agent_settled (followUp), collapsing large batches. */
 
 export type NoticeSendMode = 'steer' | 'followUp';
 
+export const NOTICE_MAX_SHOWN = 3;
+
+/** Collapse a batch into one message body: empty → null; above the cap, the first max originals plus
+ *  a tail pointing at history / subagent list. A single-item batch stays byte-identical to the
+ *  direct-send format. */
+export function collapseNotices(contents: readonly string[], max = NOTICE_MAX_SHOWN): string | null {
+  if (contents.length === 0) return null;
+  if (contents.length <= max) return contents.join('\n\n');
+  const hidden = contents.length - max;
+  const tail = `…另有 ${hidden} 条结算未逐条展示。全量结果看 history 台账（路径公式见 subagent resume 工具描述）；在跑代理用 subagent list 查看。`;
+  return [...contents.slice(0, max), tail].join('\n\n');
+}
+
 export interface NoticeBuffer {
   deliverNotice(content: string, paneId?: string): Promise<void>;
   noticePending(): ReadonlySet<string>;
@@ -20,19 +29,18 @@ export function createNoticeBuffer(opts: {
   isBusy: () => boolean;
   send: (content: string, mode: NoticeSendMode) => Promise<void>;
   /**
-   * P0-2 (RFC docs/rfc-jev-integration.md §3): relevance reorder of a collapsed
-   * batch before truncation. Only consulted above the show cap; returning null
-   * (or omitting the hook) keeps arrival order. Implementations must not throw.
-   */
+   * P0-2 (RFC docs/rfc-jev-integration.md §3): relevance reorder of a collapsed batch before truncation.
+   * Only consulted above the show cap; returning null (or omitting the hook) keeps arrival order.
+   * Implementations must not throw. */
   rank?: (contents: readonly string[]) => Promise<readonly string[] | null>;
 }): NoticeBuffer {
-  const pending: string[] = [];
+  const pending: Array<{ content: string; paneId?: string }> = [];
   const pendingPaneIds = new Set<string>();
   return {
     async deliverNotice(content, paneId) {
       if (content !== '' && paneId !== undefined) pendingPaneIds.add(paneId);
       if (opts.isBusy()) {
-        pending.push(content);
+        pending.push({ content, paneId });
         return;
       }
       await opts.send(content, 'followUp');
@@ -41,12 +49,17 @@ export function createNoticeBuffer(opts: {
     noticePending: () => pendingPaneIds,
     async flush(mode) {
       if (pending.length === 0) return;
-      const batch = pending.splice(0);
+      const flushed = pending.splice(0);
+      const batch = flushed.map((n) => n.content);
       let ordered: readonly string[] = batch;
       if (opts.rank && batch.length > NOTICE_MAX_SHOWN) {
         ordered = (await opts.rank(batch)) ?? batch;
       }
-      pendingPaneIds.clear();
+      // Release only this batch's panes: a notice buffered during the rank await is still undelivered,
+      // and GC must keep its pane until it is.
+      for (const { paneId } of flushed) {
+        if (paneId !== undefined && !pending.some((n) => n.paneId === paneId)) pendingPaneIds.delete(paneId);
+      }
       const collapsed = collapseNotices(ordered);
       if (collapsed) await opts.send(collapsed, mode);
     },

package/src/index-pipe.ts

@@ -1,12 +1,7 @@
-/**
- * Common-segment pipe request handler (prompt / interrupt / reply).
- *
- * Why: index.ts owned the NDJSON switch next to session lifecycle. The
- * dispatch is a pure-ish adapter over the subagent port and notice buffer.
- */
+/** Common-segment pipe request handler (prompt / interrupt / reply) over the subagent port and notice buffer. */
 import { formatSettlementNotice } from './vocab.ts';
 import type { PipeRequest, PipeResponse } from './pipe-channel.ts';
-import type { SubagentPortBox } from './subagent-port.ts';
+import type { SubagentPortBox } from './subagent-core.ts';
 
 export interface MachineRequest {
   id: string;
@@ -24,6 +19,8 @@ export interface PipeHandlerSession {
   sendUserMessageAs: (content: string, mode: 'steer' | 'followUp') => Promise<void>;
   abort: () => void;
   setPendingMachineRequest: (req: MachineRequest | null) => void;
+  /** P0 (RFC §4.4): apply a role switch requested over the pipe (master → worker). */
+  applyRoleSwitch: (role: string, switchedBy: string) => Promise<{ ok: boolean; message: string }>;
 }
 
 export async function handlePipeRequest(
@@ -51,13 +48,21 @@ export async function handlePipeRequest(
       s.abort();
       s.setPendingMachineRequest(null);
       return { type: 'ok', id: req.id };
+    case 'role': {
+      const res = await s.applyRoleSwitch(req.role, s.paneId || 'pipe');
+      return res.ok
+        ? { type: 'ok', id: req.id, detail: res.message }
+        : { type: 'error', id: req.id, message: res.message };
+    }
     case 'reply': {
       s.port.current?.applyReplySession(req.paneId, req.sessionFile);
-      // B8: the claim key is `${paneId}:${requestId}` and the poll loop claims exactly the same shape
-      // (subagent-poll-loop.ts settle path). The two agree because a child echoes the id of the pipe
-      // request it answered (`id: req.id` in index.ts's settle push), and the parent hands that same
-      // id to startPoller (`prompt-<taskId>` / `fu-<ts>` in core/subagent.ts). Keep both sides in step:
-      // a mismatch here surfaces as two "finished" notices for one settlement.
+      // Consume before the finish notice: otherwise listRunningSubs still reports the pane and the
+      // next master settle injects "still running" for an agent just announced finished.
+      s.port.current?.consumeReply(req.paneId, req.text);
+      // B8: the claim key `${paneId}:${requestId}` must match the poll loop's (subagent-poller.ts):
+      // a child echoes the id of the pipe request it answered (`id: req.id` in index.ts's settle
+      // push) and the parent hands that same id to startPoller (`prompt-<taskId>` / `fu-<ts>`).
+      // A mismatch surfaces as two "finished" notices for one settlement.
       if (s.claimSettleNotice(`${req.paneId}:${req.id}`)) {
         const notes = s.port.current?.reconcileOnReply(req.paneId) ?? [];
         const statLine = await s.port.current?.settleStatLine(req.paneId) ?? null;

package/src/index-roles.ts

@@ -0,0 +1,306 @@
+/**
+ * Role runtime for the composition root: manifest state, mid-session switching,
+ * the mandatory tool gate, `/pier-role`, and branch replay.
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { composeForRole, toRuntimeManifest } from './manifest-compose.ts';
+import { planActiveTools, planToolGate, type RuntimeRoleManifest } from './tool-gate.ts';
+import {
+  initialRoleState,
+  latestRoleManifestRecord,
+  manifestFromRecord,
+  planRoleSwitch,
+  planSwitchActiveTools,
+  roleRecordDiffers,
+  type RoleState,
+} from './role-state.ts';
+import { RESERVED_ROLE_NAMES, listRoleNames, roleLayers } from './role-loader.ts';
+import { TodosService } from './todos-service.ts';
+import { APPROVAL_NEEDED_CUSTOM_TYPE, ROLE_MANIFEST_CUSTOM_TYPE } from './renderers.ts';
+import { planDenyHitRow, scanRoleAxisUsage, type RoutingTelemetryRecord } from './routing-telemetry.ts';
+import type { HerdrClientLike } from './herdr-client.ts';
+
+/**
+ * WS-D7: the master pane applies its own manifest through the same mandatory chain as
+ * subagents. The builtin `master` role is read directly so a workspace master.json decoy
+ * cannot affect self-application; a malformed manifest fails open to no-role state.
+ */
+export function composeMasterRuntime(): RuntimeRoleManifest | null {
+  try {
+    return toRuntimeManifest(composeForRole('master', [], { loadRoleOpts: { builtinDirect: true } }));
+  } catch (err) {
+    console.error(`[pi-herdr] master manifest invalid (fail-open): ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
+export interface RoleRuntimeDeps {
+  pi: ExtensionAPI;
+  /** D93 sidebar identity (`display_agent`) is a herdr RPC — pi's ExtensionAPI has no such method. */
+  client: HerdrClientLike;
+  /** Role-resolution base dir carried by the master at spawn (an isolate worker's own cwd resolves a different checkout). */
+  roleBase: string;
+  initialManifest: RuntimeRoleManifest | null;
+  isSubagent: boolean;
+  todos: TodosService;
+  /** Best-effort routing telemetry (RFC docs/rfc-jev-role-routing.md §8); observation only, never gates. */
+  appendRoutingLog: (row: RoutingTelemetryRecord) => void;
+}
+
+export interface RoleRuntime {
+  readonly state: RoleState;
+  idleBadge(): string | null;
+  /** Replay the branch-point role record and re-anchor side effects (D77 visible layer, sidebar identity, badge). */
+  syncFromBranch(ctx: unknown): void;
+  /** Phase 0 axis scan of the workspace+user role layers (master session_start only). */
+  scanRoleUsage(): void;
+  /** Mid-session switch: /pier-role (human) and the pipe `role` request (master). */
+  applyRoleSwitch(roleName: string, switchedBy: string): Promise<{ ok: boolean; message: string }>;
+}
+
+export function createRoleRuntime(d: RoleRuntimeDeps): RoleRuntime {
+  const { pi, client, todos, roleBase, appendRoutingLog } = d;
+  const roleState = initialRoleState(d.initialManifest);
+  let roleBadge: string | null = null;
+
+  /** D93: sidebar identity is the role name; null clears it. Best effort — herdr may be absent. */
+  const reportSidebarIdentity = (role: string): void => {
+    void client.reportDisplayAgent(role === 'worker-default' ? 'worker' : role).catch(() => {});
+  };
+
+  const setBadge = (m: RuntimeRoleManifest): string =>
+    (roleBadge = `role ${m.role} v${m.version ?? '?'} (${m.tools.length} tools)`);
+
+  /**
+   * Same-origin sync (RFC docs/rfc-pi-0.86-dynamic-tools.md §4.3): reconcile roleState against the CURRENT
+   * branch point on session_start (resume) and session_tree — pi's tool deltas revert the loadout at the
+   * branch point, so the gate manifest must follow or it would keep the post-switch tools. Replay only
+   * when the last record names a DIFFERENT role (name equality tolerates on-disk drift and keeps the env
+   * value authoritative on resume); the anchor entry is written only on change so resume replay still works. */
+  function syncFromBranch(ctx: unknown): void {
+    if (!roleState.manifest) return;
+    try {
+      const branchEntries =
+        (ctx as { sessionManager?: { getBranch?: () => readonly unknown[] } }).sessionManager?.getBranch?.() ?? [];
+      const record = latestRoleManifestRecord(branchEntries);
+      if (record && record.role !== roleState.manifest.role) {
+        roleState.manifest = manifestFromRecord(record);
+        roleState.origin = record.origin === 'switch' ? 'switch' : 'env';
+        roleState.switchedBy = record.switchedBy ?? null;
+        roleState.switchedAt = record.ts ?? null;
+        console.error(`[pi-herdr] role replay: ${record.role} (origin ${record.origin ?? 'env'}, switchedBy ${record.switchedBy ?? '?'})`);
+      }
+      if (roleRecordDiffers(record, roleState)) {
+        const m = roleState.manifest;
+        pi.appendEntry(ROLE_MANIFEST_CUSTOM_TYPE, {
+          version: 1,
+          role: m.role,
+          manifestVersion: m.version,
+          tools: m.tools,
+          permissions: m.permissions,
+          unknownTools: m.unknownTools ?? 'deny',
+          ...(m.guidelines?.length ? { guidelines: m.guidelines } : {}),
+          ...(roleState.origin === 'switch'
+            ? { origin: 'switch' as const, switchedBy: roleState.switchedBy ?? undefined }
+            : {}),
+          ts: Date.now(),
+        });
+      }
+    } catch {
+      /* Best effort recording; the mandatory layer does not depend on the session log. */
+    }
+    reportSidebarIdentity(roleState.manifest.role);
+    setBadge(roleState.manifest);
+    // D77 visible layer: hide tools outside the manifest AFTER all plugins load.
+    // Intersection semantics prevent clearing everything; master without a
+    // manifest stays full. setActiveTools persists as a tool delta (pi 0.86).
+    try {
+      const active = pi.getActiveTools();
+      const vis = planActiveTools(roleState.manifest.tools, active, {
+        unknownTools: roleState.manifest.unknownTools,
+        permissions: roleState.manifest.permissions,
+      });
+      if (vis && vis.changed) {
+        pi.setActiveTools(vis.next);
+        console.error(`[pi-herdr] D77 visible-layer: role ${roleState.manifest.role} tools ${active.length} → ${vis.next.length}`);
+      }
+    } catch {
+      /* Best effort visible layer; the mandatory layer remains active. */
+    }
+  }
+
+  /** Axis scan reads file TEXT of the two top layers; per-layer readdir is guarded (workspace layer is commonly absent). */
+  function scanRoleUsage(): void {
+    try {
+      const files: Array<{ name: string; text: string }> = [];
+      for (const layer of roleLayers({ baseDir: roleBase }).slice(0, 2)) {
+        let names: string[];
+        try {
+          names = readdirSync(layer.dir);
+        } catch {
+          continue;
+        }
+        for (const f of names) {
+          if (!f.endsWith('.json')) continue;
+          try {
+            files.push({ name: f, text: readFileSync(join(layer.dir, f), 'utf8') });
+          } catch {
+          }
+        }
+      }
+      appendRoutingLog(scanRoleAxisUsage({ now: Date.now(), files }));
+    } catch {
+    }
+  }
+
+  async function applyRoleSwitch(
+    roleName: string,
+    switchedBy: string,
+  ): Promise<{ ok: boolean; message: string }> {
+    const current = roleState.manifest;
+    if (!current) {
+      return { ok: false, message: 'Error: role system not armed (no manifest; bare pi sessions cannot switch roles)' };
+    }
+    const name = roleName.trim();
+    if (name === '') return { ok: false, message: 'Error: role name is required (see /pier-role with no argument)' };
+    if (name === current.role) return { ok: true, message: `role is already ${name}` };
+    let next: RuntimeRoleManifest;
+    try {
+      // Resolve against the spawn-inherited base, matching the initial manifest composition.
+      next = toRuntimeManifest(composeForRole(name, [], { loadRoleOpts: { baseDir: roleBase } }));
+    } catch (err) {
+      return { ok: false, message: `Error: role "${name}" unavailable: ${(err as Error).message}` };
+    }
+    const plan = planRoleSwitch(current.tools, next.tools);
+    // Universe = ALL registered tools: a switch may re-admit tools an earlier
+    // prune removed, which intersection semantics would lose.
+    const registered = pi.getAllTools().map((t) => t.name);
+    const nextActive = planSwitchActiveTools(next.tools, registered, {
+      unknownTools: next.unknownTools,
+      permissions: next.permissions,
+    });
+    pi.setActiveTools(nextActive);
+    // TodosService captured services.todos.mode at startup; a mode switch must reach it.
+    todos.config.allowParallelInProgress = TodosService.configFromRuntime(next, d.isSubagent).allowParallelInProgress;
+    roleState.manifest = next;
+    roleState.origin = 'switch';
+    roleState.switchedBy = switchedBy;
+    roleState.switchedAt = Date.now();
+    setBadge(next);
+    try {
+      pi.appendEntry(ROLE_MANIFEST_CUSTOM_TYPE, {
+        version: 1,
+        role: next.role,
+        manifestVersion: next.version,
+        tools: next.tools,
+        permissions: next.permissions,
+        unknownTools: next.unknownTools ?? 'deny',
+        ...(next.guidelines?.length ? { guidelines: next.guidelines } : {}),
+        origin: 'switch' as const,
+        switchedBy,
+        ts: Date.now(),
+      });
+    } catch {
+    }
+    reportSidebarIdentity(next.role);
+    const diff = [
+      plan.added.length ? `+${plan.added.join(', ')}` : null,
+      plan.removed.length ? `-${plan.removed.join(', ')}` : null,
+    ]
+      .filter(Boolean)
+      .join(' ');
+    return {
+      ok: true,
+      message: `role ${current.role} → ${next.role}${diff ? ` (${diff})` : ''}; active tools: ${nextActive.length}`,
+    };
+  }
+
+  /* Mandatory gate: outside-manifest tool → block + terminate the batch;
+   * ask → v1 soft-allow with a durable APPROVAL_NEEDED trace (V56). */
+  pi.on('tool_call', async (event: { toolName?: string }) => {
+    const manifest = roleState.manifest;
+    if (!manifest) return;
+    const tool = typeof event?.toolName === 'string' ? event.toolName : '';
+    const gate = planToolGate(tool, manifest);
+    if (gate.kind === 'deny') {
+      appendRoutingLog(planDenyHitRow({ now: Date.now(), role: manifest.role, tool }));
+      return { block: true, reason: gate.reason, terminate: true };
+    }
+    if (gate.kind === 'ask') {
+      console.error(`${gate.notice} (v1 soft-approval: allowed, hard gate lands in v2)`);
+      try {
+        pi.appendEntry(APPROVAL_NEEDED_CUSTOM_TYPE, { role: manifest.role, tool, ts: Date.now() });
+      } catch {
+      }
+    }
+    return undefined;
+  });
+
+  pi.registerCommand('pier-role', {
+    description:
+      'Show the current role + available role names, or switch: /pier-role <name> (widening beyond the current toolset asks for confirmation)',
+    handler: async (args: unknown, ctx: unknown) => {
+      const ui = (ctx as { ui?: { notify?: (t: string, l?: string) => void; confirm?: (t: string, m: string) => Promise<boolean> } }).ui;
+      const notify = (text: string, level: 'info' | 'error') => ui?.notify?.(text, level) ?? console.error(text);
+      const current = roleState.manifest;
+      if (!current) {
+        notify('Role system not armed (no manifest).', 'error');
+        return;
+      }
+      const name = typeof args === 'string' ? args.trim() : '';
+      if (name === '') {
+        const names = new Set<string>(RESERVED_ROLE_NAMES);
+        for (const n of listRoleNames(roleBase)) names.add(n);
+        notify(
+          `Current role: ${current.role} (origin: ${roleState.origin}). Available: ${[...names].sort().join(', ')}`,
+          'info',
+        );
+        return;
+      }
+      try {
+        const preview = toRuntimeManifest(composeForRole(name, [], { loadRoleOpts: { baseDir: roleBase } }));
+        const plan = planRoleSwitch(current.tools, preview.tools);
+        // Q2: humans may widen after confirm — the human is the final authority in the pane.
+        if (plan.widening && ui?.confirm) {
+          const okToWiden = await ui.confirm(
+            'Widen role toolset',
+            `Role "${name}" adds tools beyond the current set (${plan.added.join(', ')}). Switch anyway?`,
+          );
+          if (!okToWiden) {
+            notify('Role switch cancelled.', 'info');
+            return;
+          }
+        }
+      } catch (err) {
+        notify(`Error: role "${name}" unavailable: ${(err as Error).message}`, 'error');
+        return;
+      }
+      const res = await applyRoleSwitch(name, 'human');
+      notify(res.message, res.ok ? 'info' : 'error');
+    },
+  });
+
+  /* Per-role guidelines ride the before_agent_start prompt-section diff; writing
+   * the same string each turn is a no-op (pi diffs sections), removal cleans up. */
+  pi.on('before_agent_start', async (event) => {
+    const sections = event.systemPromptOptions?.sections;
+    if (!sections) return;
+    const m = roleState.manifest;
+    if (m?.guidelines?.length) {
+      const text = `Role "${m.role}" operating constraints:\n${m.guidelines.map((g) => `- ${g}`).join('\n')}`;
+      if (sections['pier-role'] !== text) sections['pier-role'] = text;
+    } else {
+      delete sections['pier-role'];
+    }
+  });
+
+  return {
+    state: roleState,
+    idleBadge: () => roleBadge,
+    syncFromBranch,
+    scanRoleUsage,
+    applyRoleSwitch,
+  };
+}