piher 0.0.0-stage → 0.2.0

package/src/role-manifest.ts

@@ -0,0 +1,163 @@
+/**
+ * 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.
+ */
+import { isPlainObject } from './guards.ts';
+
+export type PermissionAction = 'allow' | 'deny';
+/** D82: stance for unknown tools—visibility is a trust relationship (user→master via install; master→delegated via mirror). */
+export type UnknownToolStance = 'allow' | 'deny';
+/** pi's thinking levels, ascending. `--thinking` on the child's argv; never carried in its runtime env. */
+export const THINKING_LEVELS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** S9/S54: a worker's lifetime is the role's — `one-shot` settles, reports and exits, `persistent` stays for `send`. */
+export const LIFECYCLES = ['persistent', 'one-shot'] as const;
+export type Lifecycle = (typeof LIFECYCLES)[number];
+
+export interface RoleManifest {
+  role: string;
+  version: string;
+  /** WS-D10: `provider/model` routing by role; omitted means follow the process default (spawn injects `--provider/--model`). */
+  model?: string;
+  /** Thinking level for the child launch (spawn injects `--thinking`); omitted means the process default. */
+  thinking?: ThinkingLevel;
+  description?: string;
+  /** P0 per-role guidelines (RFC §4.6): constraints a tool set cannot express; injected as a prompt section. */
+  guidelines?: string[];
+  /** Prose too long for a bullet: injected after `guidelines` in the same `piher-role` prompt section. */
+  instructions?: string;
+  /** Lifetime of a worker of this role (S9); omitted means `persistent`. Never a per-spawn choice. */
+  lifecycle?: Lifecycle;
+  /** `false` keeps the role launchable by name but out of the master's role catalog (internal/experimental). */
+  modelInvocable?: boolean;
+  manifest: {
+    tools: string[];
+    /** Three-state permissions; `*` supplies the default; omitted means `{"*":"allow"}`. */
+    rules?: Record<string, PermissionAction>;
+    /**
+     * 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;
+  };
+}
+
+export type ValidateResult =
+  | { ok: true; value: RoleManifest }
+  | { ok: false; code: 'INVALID_ROLE_CONFIG'; issues: string[] };
+
+const ROLE_NAME_RE = /^[a-z0-9-]+$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const TOOL_KEY_RE = /^[a-z0-9_*-]+$/;
+const ACTIONS: readonly PermissionAction[] = ['allow', 'deny'];
+
+
+export function validateRoleManifest(input: unknown): ValidateResult {
+  const issues: string[] = [];
+  if (!isPlainObject(input)) {
+    return { ok: false, code: 'INVALID_ROLE_CONFIG', issues: ['role manifest must be a JSON object'] };
+  }
+
+  const KNOWN_TOP = new Set(['role', 'version', 'model', 'thinking', 'description', 'guidelines', 'instructions', 'modelInvocable', 'lifecycle', 'manifest']);
+  for (const k of Object.keys(input)) {
+    if (!KNOWN_TOP.has(k)) issues.push(`unknown top-level key "${k}" (not in the contract; check spelling)`);
+  }
+
+  if (typeof input.role !== 'string' || !ROLE_NAME_RE.test(input.role)) {
+    issues.push(`role must be a [a-z0-9-]+ string, got ${JSON.stringify(input.role)}`);
+  }
+
+  if (typeof input.version !== 'string' || !SEMVER_RE.test(input.version)) {
+    issues.push(`version must be three dot-separated numbers x.y.z (e.g. 1.0.0), got ${JSON.stringify(input.version)}`);
+  }
+
+  if (input.model !== undefined) {
+    if (typeof input.model !== 'string' || !/^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/.test(input.model)) {
+      issues.push(`model must be in provider/model form (e.g. opencode-go/muse-spark-1.2-contributor), got ${JSON.stringify(input.model)}`);
+    }
+  }
+
+  if (input.description !== undefined && typeof input.description !== 'string') {
+    issues.push('description must be a string');
+  }
+
+  if (input.thinking !== undefined) {
+    if (typeof input.thinking !== 'string' || !THINKING_LEVELS.includes(input.thinking as ThinkingLevel)) {
+      issues.push(`thinking must be one of ${THINKING_LEVELS.join('/')}, got ${JSON.stringify(input.thinking)}`);
+    }
+  }
+
+  if (input.lifecycle !== undefined) {
+    if (typeof input.lifecycle !== 'string' || !LIFECYCLES.includes(input.lifecycle as Lifecycle)) {
+      issues.push(`lifecycle must be one of ${LIFECYCLES.join('/')}, got ${JSON.stringify(input.lifecycle)}`);
+    }
+  }
+
+  if (input.instructions !== undefined) {
+    if (typeof input.instructions !== 'string' || input.instructions.trim() === '') {
+      issues.push('instructions must be a non-empty string (omit it instead of passing an empty one)');
+    }
+  }
+
+  if (input.modelInvocable !== undefined && typeof input.modelInvocable !== 'boolean') {
+    issues.push(`modelInvocable must be a boolean, got ${JSON.stringify(input.modelInvocable)}`);
+  }
+
+  if (input.guidelines !== undefined) {
+    if (!Array.isArray(input.guidelines)) {
+      issues.push('guidelines must be an array of strings');
+    } else if (input.guidelines.length === 0) {
+      issues.push('omit guidelines entirely instead of passing an empty array');
+    } else if (!input.guidelines.every((g) => typeof g === 'string' && g.trim() !== '')) {
+      issues.push('every guidelines entry must be a non-empty string');
+    } else if (input.guidelines.length > 20) {
+      issues.push('at most 20 guidelines (prompt budget protection)');
+    }
+  }
+
+  const m = input.manifest;
+  if (!isPlainObject(m)) {
+    issues.push('manifest must be an object');
+  } else {
+    const KNOWN_MANIFEST = new Set(['tools', 'rules', 'unknownTools']);
+    for (const k of Object.keys(m)) {
+      if (!KNOWN_MANIFEST.has(k)) issues.push(`unknown key "${k}" in manifest`);
+    }
+
+    if (m.unknownTools !== undefined && m.unknownTools !== 'allow' && m.unknownTools !== 'deny') {
+      issues.push(`manifest.unknownTools must be allow/deny, got ${JSON.stringify(m.unknownTools)}`);
+    }
+
+    const tools = m.tools;
+    if (!Array.isArray(tools) || tools.length === 0 || !tools.every((t) => typeof t === 'string' && TOOL_KEY_RE.test(t))) {
+      issues.push('manifest.tools must be a non-empty array of strings (tool names [a-z0-9_-])');
+    } else {
+      const seen = new Set<string>();
+      for (const t of tools) {
+        if (seen.has(t)) issues.push(`duplicate entry in manifest.tools "${t}"`);
+        seen.add(t);
+      }
+    }
+
+    if (m.rules !== undefined) {
+      if (!isPlainObject(m.rules)) {
+        issues.push('manifest.rules must be an object');
+      } else {
+        for (const [k, v] of Object.entries(m.rules)) {
+          if (!TOOL_KEY_RE.test(k)) issues.push(`rules key "${k}" is not a valid tool name ([a-z0-9_-] or *)`);
+          if (v === 'ask') {
+            issues.push(`rules["${k}"]: "ask" is not a permission — piher ships no human-gate tool, so use "allow" or "deny"`);
+          } else if (!ACTIONS.includes(v as PermissionAction)) {
+            issues.push(`rules["${k}"] must be one of ${ACTIONS.join('/')}, got ${JSON.stringify(v)}`);
+          }
+        }
+      }
+    }
+  }
+
+  if (issues.length > 0) return { ok: false, code: 'INVALID_ROLE_CONFIG', issues };
+  return { ok: true, value: input as unknown as RoleManifest };
+}

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 piher's half — replaying the gate manifest from the last
+ * `piher.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 `piher.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 !== 'piher.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 /piher-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/roles/master.json

@@ -0,0 +1,23 @@
+{
+  "role": "master",
+  "version": "1.0.0",
+  "description": "Master role: the pane that delegates. Core tools (subagent/bg_job) + pi built-ins + web_search, and unknownTools=allow under D82 so a newly installed extension tool is visible without editing this file. An `ask` rule is invalid: no permission can hand a decision to a human mid-call.",
+  "manifest": {
+    "unknownTools": "allow",
+    "tools": [
+      "subagent",
+      "bg_job",
+      "read",
+      "grep",
+      "glob",
+      "bash",
+      "pwsh",
+      "edit",
+      "write",
+      "web_search"
+    ],
+    "rules": {
+      "*": "allow"
+    }
+  }
+}

package/src/roles/worker-default.json

@@ -0,0 +1,23 @@
+{
+  "role": "worker-default",
+  "version": "1.0.0",
+  "description": "Default worker role (D83 inheritance): mirrors master.tools minus subagent and bg_job (no nesting, the worker owns no other worker); the excluded families are also denied explicitly, so the ban survives the D82 unknownTools=allow stance.",
+  "manifest": {
+    "unknownTools": "allow",
+    "tools": [
+      "read",
+      "grep",
+      "glob",
+      "bash",
+      "pwsh",
+      "edit",
+      "write",
+      "web_search"
+    ],
+    "rules": {
+      "subagent": "deny",
+      "bg_job": "deny",
+      "*": "allow"
+    }
+  }
+}

package/src/runtime-policy.ts

@@ -0,0 +1,45 @@
+/**
+ * Every field is fed by the `OPTION_SPECS` registry, so the numbers cannot drift from
+ * `/piher-config doctor`; an out-of-range value warns and falls back to the registry default.
+ */
+import { OPTION_SPECS, optionValue, type PolicyField } from './options.ts';
+
+export interface RuntimePolicy {
+  readonly subagentTimeoutMs: number
+  readonly gcTickMs: number
+  readonly pollIntervalMs: number
+  /** Post-settle window before auto-consume */
+  readonly settleWindowMs: number
+  readonly sessionTtlSeconds: number
+  readonly gitTimeoutMs: number
+  /** Subagent pane pipe readiness wait */
+  readonly readinessTimeoutMs: number
+}
+
+function policyValue(field: PolicyField): number {
+  const spec = OPTION_SPECS.find((o) => o.policy === field);
+  if (!spec) throw new Error(`no OPTION_SPECS entry feeds RuntimePolicy.${field}`);
+  const fallback = Number(spec.fallback);
+  const raw = optionValue(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;
+}
+
+export function createRuntimePolicy(overrides?: Partial<RuntimePolicy>): RuntimePolicy {
+  const policy = {} as { -readonly [K in keyof RuntimePolicy]: number };
+  for (const spec of OPTION_SPECS) {
+    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 for production; tests inject via createRuntimePolicy(). */
+export const runtimePolicy = createRuntimePolicy()

package/src/session-state.ts

@@ -0,0 +1,19 @@
+/**
+ * piher's per-session state root: `<sessionDir>/piher/<sessionId>/`, the one place the extension owns
+ * beside pi's transcript. The worker marker and the session's task view live here, written in place
+ * rather than appended to the session, which is an immutable log with no replace.
+ */
+import { dirname, join } from 'node:path';
+import { bareSessionId } from './session-tail.ts';
+import { isValidSessionId } from './storage-layout.ts';
+
+/** `<sessionDir>/piher/<sessionId>/<name>`; a bare id (`PI_SESSION_FILE=oneshot-sess-0001`, no transcript
+ *  directory) has nowhere to sit, so no state file — callers must then fall back to what they have. */
+export function sessionStatePath(sessionFile: string | null | undefined, name: string): string | null {
+  if (!sessionFile || typeof sessionFile !== 'string') return null;
+  const dir = dirname(sessionFile);
+  if (dir === '' || dir === '.') return null;
+  const id = bareSessionId(sessionFile);
+  if (!isValidSessionId(id)) return null;
+  return join(dir, 'piher', id, name);
+}

package/src/session-tail.ts

@@ -0,0 +1,276 @@
+/**
+ * Tail parsing for pi session JSONL (pure): child-agent results come from the child session file,
+ * not pane text. Depends only on the pi session format:
+ *   line = {type, id, parentId, message:{role, content:[{type:'text',text}...], timestamp, stopReason}}
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { piSessionDirCandidates, sessionDirName, isValidSessionId } from './storage-layout.ts';
+
+export { sessionDirName };
+
+export interface SessionMessageLike {
+  role?: string;
+  content?: Array<{ type?: string; text?: string } | unknown> | unknown;
+  timestamp?: number;
+  stopReason?: string;
+}
+
+export interface SessionEntryLike {
+  type?: string;
+  message?: SessionMessageLike | unknown;
+  [k: string]: unknown;
+}
+export function parseSessionEntries(text: string): SessionEntryLike[] {
+  const entries: SessionEntryLike[] = [];
+  for (const line of (text ?? '').split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const obj = JSON.parse(t);
+      if (obj && typeof obj === 'object') entries.push(obj as SessionEntryLike);
+    } catch {
+    }
+  }
+  return entries;
+}
+
+function messageOf(entry: SessionEntryLike): SessionMessageLike | null {
+  if (entry.type !== 'message') return null;
+  const m = entry.message;
+  if (typeof m !== 'object' || m === null) return null;
+  return m as SessionMessageLike;
+}
+
+function textOf(m: SessionMessageLike): string {
+  const content = m.content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((c) => {
+      if (typeof c === 'object' && c !== null && (c as { type?: string }).type === 'text') {
+        return (c as { text?: string }).text ?? '';
+      }
+      return '';
+    })
+    .join('\n')
+    .trim();
+}
+/** Latest finalized assistant text (`stopReason === 'stop'`), excluding toolUse intermediates;
+ * `sinceTs` filters out messages predating the injection point. */
+export function lastAssistantText(
+  entries: readonly SessionEntryLike[],
+  opts: { sinceTs?: number } = {},
+): { text: string; timestamp: number } | null {
+  let best: { text: string; timestamp: number } | null = null;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m || m.role !== 'assistant') continue;
+    if (m.stopReason !== 'stop') continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (opts.sinceTs !== undefined && ts < opts.sinceTs) continue;
+    if (!best || ts >= best.timestamp) best = { text: textOf(m), timestamp: ts };
+  }
+  return best;
+}
+/**
+ * Newest assistant text after `sinceTs` with no stopReason filter: a turn can end by hitting the token
+ * cap or by an abort, and those words are still the report the master should receive instead of
+ * "left no closing message".
+ */
+export function lastAssistantAnyText(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): string | null {
+  let best: { text: string; timestamp: number } | null = null;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m || m.role !== 'assistant') continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    const text = textOf(m).trim();
+    if (!text) continue;
+    if (!best || ts >= best.timestamp) best = { text, timestamp: ts };
+  }
+  return best?.text ?? null;
+}
+
+/** Return whether any assistant message occurs after the injection point, regardless of stopReason. */
+export function hasAssistantAfter(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): boolean {
+  return entries.some((e) => {
+    const m = messageOf(e);
+    return !!m && m.role === 'assistant' && (typeof m.timestamp === 'number' ? m.timestamp : 0) >= sinceTs;
+  });
+}
+/**
+ * Whether the NEWEST assistant message after `sinceTs` ended its turn: a worker between tool calls
+ * has "an assistant message" but has NOT finished, so announcing it settled loses supervision of
+ * live work. `stopReason === 'toolUse'` means tools were requested; a non-string stopReason (still
+ * streaming / older shapes) counts as "not ended" on purpose.
+ */
+export function lastAssistantTurnEnded(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): boolean {
+  let newest: { ts: number; stopReason: unknown } | null = null;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m || m.role !== 'assistant') continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    if (!newest || ts >= newest.ts) newest = { ts, stopReason: m.stopReason };
+  }
+  if (!newest) return false;
+  const sr = newest.stopReason;
+  return typeof sr === 'string' && sr !== 'toolUse' && sr !== 'pending';
+}
+/** Whether an initiated toolCall still lacks a result after injection (a task waiting on the tool's
+ * own completion), meaning settlement has not completed. */
+export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs: number): boolean {
+  let depth = 0;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m) continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    if (m.role === 'assistant') {
+      const content = m.content;
+      if (Array.isArray(content)) {
+        depth += content.filter((c) => typeof c === 'object' && c !== null && (c as { type?: string }).type === 'toolCall').length;
+      }
+    }
+    if (m.role === 'toolResult') depth -= 1;
+  }
+  return depth > 0;
+}
+
+/**
+ * Why a turn ended with nothing to say, in words the master can act on. A refused tool is the case
+ * that matters: piher's gate refuses it, the model stops, and without this the master waited the whole
+ * vacuum budget for a report that was never coming.
+ */
+export function explainSilentEnd(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): string | null {
+  let refusal: string | null = null;
+  let failed = false;
+  for (const entry of entries) {
+    const m = messageOf(entry);
+    if (!m) continue;
+    const ts = typeof m.timestamp === 'number' ? m.timestamp : 0;
+    if (ts < sinceTs) continue;
+    if (m.role === 'toolResult') {
+      const hit = /role "([^"]+)" does not permit tool "([^"]+)"/.exec(textOf(m));
+      if (hit) refusal = `the \`${hit[1]}\` manifest does not permit \`${hit[2]}\``;
+    }
+    if (m.role === 'assistant' && m.stopReason === 'error') failed = true;
+  }
+  if (refusal) {
+    return `It stopped after a refused tool call: ${refusal}. Fix the role profile or the task, then continue it.`;
+  }
+  return failed ? 'Its turn ended with an error and no message.' : null;
+}
+
+/** Derived settlement state of one child session, from the inject point onward. */
+export interface SubSessionState {
+  text: string | null;
+  pendingTool: boolean;
+  activity: boolean;
+  turnEnded: boolean;
+  /** Nothing to say, but there is a reason the master can act on: a refused tool, an errored turn. */
+  why?: string | null;
+}
+
+/** Closing text is terminal by construction (lastAssistantText requires stopReason 'stop'); an
+ * assistant message alone is not a settlement — the turn must have ENDED. */
+export function deriveSubSessionState(
+  entries: readonly SessionEntryLike[],
+  sinceTs: number,
+): SubSessionState {
+  const r = lastAssistantText(entries, { sinceTs });
+  if (r?.text) return { text: r.text, pendingTool: false, activity: true, turnEnded: true, why: null };
+  if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true, turnEnded: false, why: null };
+  if (hasAssistantAfter(entries, sinceTs)) {
+    const turnEnded = lastAssistantTurnEnded(entries, sinceTs);
+    // An ended turn always has words to deliver, even when they did not come from a clean 'stop'
+    // (token cap, abort). Without this the poller saw "turn ended, no text" and announced
+    // "It left no closing message" for a worker that had answered.
+    const any = turnEnded ? lastAssistantAnyText(entries, sinceTs) : null;
+    if (any) return { text: any, pendingTool: false, activity: true, turnEnded: true, why: null };
+    return { text: null, pendingTool: false, activity: true, turnEnded, why: explainSilentEnd(entries, sinceTs) };
+  }
+  return { text: null, pendingTool: false, activity: false, turnEnded: false, why: null };
+}
+
+/** Newest `limit` session files under cwd's session dir (pi core's name first, then piher's old encodings). */
+export function listSessionFiles(cwd: string, agentDir: string, limit = 4): string[] {
+  const files: Array<{ file: string; mtime: number }> = [];
+  for (const name of piSessionDirCandidates(cwd)) {
+    const dir = path.join(agentDir, name);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const fileName of names) {
+      if (!fileName.endsWith('.jsonl')) continue;
+      const full = path.join(dir, fileName);
+      try {
+        files.push({ file: full, mtime: fs.statSync(full).mtimeMs });
+      } catch {
+        /* vanished between readdir and stat */
+      }
+    }
+  }
+  files.sort((a, b) => b.mtime - a.mtime);
+  return files.slice(0, limit).map((f) => f.file);
+}
+
+/** Locate a session file by id (`<ts>_<id>.jsonl`): pi core's directory name first, then piher's
+ * legacy flattened dirs. */
+export function sessionFileById(cwd: string, agentDir: string, id: string): string | null {
+  const suffix = `_${id}.jsonl`;
+  for (const name of piSessionDirCandidates(cwd)) {
+    const dir = path.join(agentDir, name);
+    let names: string[];
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const fileName of names) {
+      if (fileName.endsWith(suffix)) return path.join(dir, fileName);
+    }
+  }
+  return null;
+}
+
+/**
+ * Normalize a session path or id to the bare id used across piher state (`<timestamp>_<uuid>.jsonl`
+ * → `<uuid>`; `sub-session.jsonl` stays whole). Only pi's real transcript prefix is stripped, so
+ * arbitrary ids like PI_SESSION_FILE=sess_idx_prune survive untouched. Same-normalization comparisons
+ * (own session vs candidate paths) must go through here.
+ */
+export function bareSessionId(raw: string): string {
+  const base = raw.replaceAll('\\', '/').split('/').pop()!.replace(/\.jsonl$/, '');
+  const stripped = base.replace(/^\d{4}-\d{2}-\d{2}T[\d-]+Z_/, '');
+  return isValidSessionId(stripped) ? stripped : base;
+}
+
+/** Herdr reports session ids and paths interchangeably: accept a `.jsonl` path as-is, else map the id. */
+export function resolveSessionFileValue(cwd: string, agentDir: string, value: string | null | undefined): string | null {
+  if (!value) return null;
+  return /\.jsonl$/i.test(value) ? value : sessionFileById(cwd, agentDir, value);
+}
+
+export function readSessionFile(file: string): SessionEntryLike[] | null {
+  try {
+    return parseSessionEntries(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}