pi-pier 0.3.0 → 0.3.1

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,63 +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 { pierOption } from './pier-options.ts';
+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
-  /** 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
-  /** Git operation timeout (ms) */
   readonly gitTimeoutMs: number
-  /** Subagent pane pipe readiness wait (ms) */
+  /** Subagent pane pipe readiness wait */
   readonly readinessTimeoutMs: number
 }
 
-/** B10: read through the option catalog so the legacy `PI_HERDR_*` spelling keeps working. */
-function parseEnvInt(key: string, defaultValue: number, min: number = 0): number {
-  const raw = pierOption(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),
-    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),
-    gitTimeoutMs: overrides?.gitTimeoutMs ?? parseEnvInt('PIER_GIT_TIMEOUT_MS', 10_000, 1),
-    // A14: concurrent heavy workers can take far longer than 30s to boot; PIER_READY_TIMEOUT_MS overrides.
-    readinessTimeoutMs: overrides?.readinessTimeoutMs ?? parseEnvInt('PIER_READY_TIMEOUT_MS', 90_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()

package/src/session-tail.ts

@@ -1,15 +1,13 @@
 /**
- * Tail parsing for pi session JSONL (pure library, v1.1 result channel).
- *
- * Since v1.1 (DESIGN.md §12), child-agent results come from the child session file
- * rather than pane text, keeping the authoritative machine-readable source free of
- * echo contamination and scrollback blind spots. This module depends only on the
- * empirically observed pi session format (session-format documentation):
+ * 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 } from './storage-layout.ts';
+import { isValidSessionId } from './efficiency-store.ts';
+import { COMPACTION_INFLIGHT_TYPE, COMPACTION_SETTLED_TYPE } from './compact-coordinator.ts';
 
 export { sessionDirName };
 
@@ -25,7 +23,6 @@ export interface SessionEntryLike {
   message?: SessionMessageLike | unknown;
   [k: string]: unknown;
 }
-/** Parse line by line tolerantly, skipping malformed or non-JSON records. */
 export function parseSessionEntries(text: string): SessionEntryLike[] {
   const entries: SessionEntryLike[] = [];
   for (const line of (text ?? '').split(/\r?\n/)) {
@@ -35,7 +32,6 @@ export function parseSessionEntries(text: string): SessionEntryLike[] {
       const obj = JSON.parse(t);
       if (obj && typeof obj === 'object') entries.push(obj as SessionEntryLike);
     } catch {
-      /* Skip truncated or malformed records. */
     }
   }
   return entries;
@@ -61,10 +57,8 @@ function textOf(m: SessionMessageLike): string {
     .join('\n')
     .trim();
 }
-/**
- * Return the latest finalized assistant text (stopReason === 'stop'), excluding toolUse intermediates.
- * sinceTs filters out messages that predate the injection point.
- */
+/** 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 } = {},
@@ -91,16 +85,10 @@ export function hasAssistantAfter(
   });
 }
 /**
- * Return whether the NEWEST assistant message after `sinceTs` ended its turn.
- *
- * Why (A16): a worker sitting between tool calls (tool result already written, next assistant
- * message still streaming) has "an assistant message" but has NOT finished. Treating any assistant
- * message as activity made the poller announce such workers as finished — three real workers were
- * declared settled while still working on 2026-09-13 and one was later closed mid-task by GC.
- *
- * `stopReason === 'toolUse'` means the model requested tools, so the turn continues; a non-string
- * stopReason (message still streaming / older shapes) is treated as "not ended" on purpose — the
- * cost of waiting is small, the cost of a false settlement is losing supervision of live work.
+ * 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[],
@@ -118,11 +106,8 @@ export function lastAssistantTurnEnded(
   const sr = newest.stopReason;
   return typeof sr === 'string' && sr !== 'toolUse' && sr !== 'pending';
 }
-/**
- * Return whether an initiated toolCall still lacks a result after injection (for example,
- * ask_user_question waiting on human input), meaning settlement has not actually completed
- * (v1.3 M8 settlement-race fix). Parallel calls are tracked by depth.
- */
+/** Whether an initiated toolCall still lacks a result after injection (e.g. ask_user_question
+ * waiting on a human), meaning settlement has not completed. */
 export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs: number): boolean {
   let depth = 0;
   for (const entry of entries) {
@@ -141,33 +126,56 @@ export function hasPendingToolCall(entries: readonly SessionEntryLike[], sinceTs
   return depth > 0;
 }
 
-
-
 /** Derived settlement state of one child session, from the inject point onward. */
 export interface SubSessionState {
   text: string | null;
   pendingTool: boolean;
   activity: boolean;
   turnEnded: boolean;
+  /** True while the child is inside an OCC compaction cycle: from the inflight marker until an
+   * assistant message follows the settled marker. OCC's intentional abort lands as stopReason
+   * 'error', which the turnEnded check alone would misread as finished. */
+  compacting: boolean;
 }
 
 /**
- * Derive the settlement state from already-parsed entries.
- *
- * Closing text is by construction terminal (lastAssistantText requires stopReason 'stop').
- * A16: an assistant message alone is not a settlement; the turn must have ENDED.
+ * Whether the transcript currently sits inside an OCC compaction cycle. Last marker wins: inflight
+ * last means the summary request is running; settled last means the cycle is over — unless no
+ * assistant message follows it yet, in which case the worker is still machine-paused (not settled,
+ * not a user takeover). A cancelled cycle sends no continuation, so it is over at the marker.
  */
+export function compactionBusy(entries: readonly SessionEntryLike[]): boolean {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (!entry || entry.type !== 'custom') continue;
+    const customType = entry.customType;
+    if (customType === COMPACTION_INFLIGHT_TYPE) return true;
+    if (customType === COMPACTION_SETTLED_TYPE) {
+      // A cancel sends no continuation turn, so waiting for one would pin the worker as busy forever.
+      if ((entry.data as { outcome?: unknown } | undefined)?.outcome === 'cancelled') return false;
+      for (let j = i + 1; j < entries.length; j++) {
+        if (messageOf(entries[j])?.role === 'assistant') return false;
+      }
+      return true;
+    }
+  }
+  return false;
+}
+
+/** 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 compacting = compactionBusy(entries);
   const r = lastAssistantText(entries, { sinceTs });
-  if (r?.text) return { text: r.text, pendingTool: false, activity: true, turnEnded: true };
-  if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true, turnEnded: false };
+  if (r?.text) return { text: r.text, pendingTool: false, activity: true, turnEnded: true, compacting };
+  if (hasPendingToolCall(entries, sinceTs)) return { text: null, pendingTool: true, activity: true, turnEnded: false, compacting };
   if (hasAssistantAfter(entries, sinceTs)) {
-    return { text: null, pendingTool: false, activity: true, turnEnded: lastAssistantTurnEnded(entries, sinceTs) };
+    return { text: null, pendingTool: false, activity: true, turnEnded: lastAssistantTurnEnded(entries, sinceTs), compacting };
   }
-  return { text: null, pendingTool: false, activity: false, turnEnded: false };
+  return { text: null, pendingTool: false, activity: false, turnEnded: false, compacting };
 }
 
 /** Newest `limit` session files under cwd's session dir (pi core's name first, then pier's old encodings). */
@@ -195,10 +203,8 @@ export function listSessionFiles(cwd: string, agentDir: string, limit = 4): stri
   return files.slice(0, limit).map((f) => f.file);
 }
 
-/**
- * Locate a session file by id (`<ts>_<id>.jsonl`).
- * Searches pi core's own directory name first, then pier's legacy flattened dirs.
- */
+/** Locate a session file by id (`<ts>_<id>.jsonl`): pi core's directory name first, then pier'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)) {
@@ -216,6 +222,24 @@ export function sessionFileById(cwd: string, agentDir: string, id: string): stri
   return null;
 }
 
+/**
+ * Normalize a session path or id to the bare id used across herdr-pi 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'));

package/src/settle-wake-core.ts

@@ -1,16 +1,8 @@
 /**
- * Pure core for the settled-wake decision (prevents wake storms; evidenced by session 01a03bf0).
- *
- * Evidence chain: ESC abort → agent_settled → D96 "background subagents still running" notice
- * → sendUserMessage(followUp) (always starts a new run while idle) → master restarts → user presses ESC again → …
- * After 30 aborts, ESC never breaks the cycle; only Ctrl+C stops the process.
- * Natural settlement also forms a self-triggering loop: settle → notice → new run → settle → notice …
- *
- * Rules:
- *  - Abort suppression: when the previous assistant stopReason === 'aborted', this settled event injects no
- *    wake-up message (the user explicitly stopped it; settlement-buffered content waits for the next natural turn);
- *  - D96 deduplication: notify once for a given running paneId set; any set change (new subagent/settlement) resets it;
- *  - D96 cooldown: repeat a notice for the same set only after REPEAT_NOTICE_MS (otherwise the unchanged set is noise).
+ * Settled-wake decision (prevents wake storms): a settle wake that injects messages creates a
+ * self-triggering loop (settle → notice → new run → settle → …) that even ESC cannot break, so an
+ * aborted previous turn injects nothing and a running set is announced once, re-announced only after
+ * D96_REPEAT_NOTICE_MS or when the set changes.
  */
 
 export const ABORT_STOP_REASON = 'aborted';
@@ -19,39 +11,78 @@ export const ABORT_STOP_REASON = 'aborted';
 export const D96_REPEAT_NOTICE_MS = 10 * 60_000;
 
 export interface SettleWakeInput {
-  /** stopReason of the last assistant turn before this settlement (unknown = null, treated as natural completion). */
+  /** stopReason of the last assistant turn (null = treated as natural completion). */
   lastStopReason: string | null;
   /** True when abort was triggered intentionally by internal mechanisms like OCC. */
   intentionalAbort?: boolean;
-  /** Background subagents still running (empty means none). */
   running: ReadonlyArray<{ paneId: string }>;
-  /** Set key recorded for the previous D96 notice (none = null). */
   lastNoticeKey: string | null;
-  /** Timestamp of the previous D96 notice (epoch ms). */
   lastNoticeAt: number;
   now: number;
+  /**
+   * A compaction abort is already selected. turn_start clears intentionalAbort before agent_settled
+   * reads it, so this is the durable signal: do not inject a running-sub notice that compaction will abort.
+   */
+  compactionPending?: boolean;
 }
 
 export interface SettleWakePlan {
   /** false means this settlement stays silent and emits no wake-up message. */
   wake: boolean;
-  /** Whether to inject the D96 "still running" notice. */
+  /**
+   * Hand the settlement to the compaction coordinator. An OCC abort is silent (no wake) yet is the
+   * very settlement the selected compaction waits for; only a foreign (ESC) abort skips it.
+   */
+  compact: boolean;
   notice: boolean;
-  /** New set key (updated when notifying; empty running set → null). */
+  /** New set key; empty running set → null. */
   noticeKey: string | null;
   noticeAt: number;
 }
 
 export function planSettleWake(input: SettleWakeInput): SettleWakePlan {
+  if (input.compactionPending) {
+    return {
+      wake: false,
+      compact: true,
+      notice: false,
+      noticeKey: input.lastNoticeKey,
+      noticeAt: input.lastNoticeAt,
+    };
+  }
   if (input.intentionalAbort || input.lastStopReason === ABORT_STOP_REASON) {
-    return { wake: false, notice: false, noticeKey: input.lastNoticeKey, noticeAt: input.lastNoticeAt };
+    return {
+      wake: false,
+      compact: input.intentionalAbort === true,
+      notice: false,
+      noticeKey: input.lastNoticeKey,
+      noticeAt: input.lastNoticeAt,
+    };
   }
   const key = input.running.length === 0 ? null : input.running.map((s) => s.paneId).sort().join(',');
   if (key === null) {
-    return { wake: true, notice: false, noticeKey: null, noticeAt: input.lastNoticeAt };
+    return { wake: true, compact: true, notice: false, noticeKey: null, noticeAt: input.lastNoticeAt };
   }
   const newSet = key !== input.lastNoticeKey;
   const cooled = input.now - input.lastNoticeAt >= D96_REPEAT_NOTICE_MS;
   const notice = newSet || cooled;
-  return { wake: true, notice, noticeKey: key, noticeAt: notice ? input.now : input.lastNoticeAt };
+  return { wake: true, compact: true, notice, noticeKey: key, noticeAt: notice ? input.now : input.lastNoticeAt };
+}
+
+/**
+ * Whether a just-settled run may answer its pending machine request (the pipe settle fast-path).
+ * An OCC intentional abort and a still-running compaction both mean the continuation turn is
+ * coming: answering now reports "finished, no closing message" for live work and — worse —
+ * consumes the one-shot request plus the parent's claim latch, so the real closing message can
+ * never be delivered (observed: a worker mid-compaction announced finished; its final report
+ * never reached the parent). A user abort ('aborted') likewise settles a run that may re-run.
+ */
+export function shouldPushSettleReply(input: {
+  intentionalAbort?: boolean;
+  compactionInFlight?: boolean;
+  lastStopReason: string | null;
+}): boolean {
+  return !input.intentionalAbort
+    && !input.compactionInFlight
+    && input.lastStopReason !== ABORT_STOP_REASON;
 }