pi-daddy 0.19.0 → 0.20.1

package/src/ledger-v3-validation.ts

@@ -0,0 +1,266 @@
+import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
+import { isExecutionId } from "./execution-id.ts";
+import { REFUSAL_CODES } from "./refusals.ts";
+import { isWorkflowFactId, isWorkflowIdentifier, workflowFactStateMatches } from "./workflow-fact-id.ts";
+import { isLedgerCapabilityIdentifier, isLedgerDisplayIdentifier } from "./ledger-identifiers.ts";
+
+export type LedgerV3Object = Record<string, unknown>;
+
+const SHA256_RE = /^[a-f0-9]{64}$/i;
+const EXECUTORS = new Set(["process", "herdr"]);
+const APPROVAL_SOURCES = new Set(["prompt", "session", "persisted", "inherited"]);
+const APPROVAL_SCOPES = new Set(["once", "session", "always"]);
+const GATE_OUTCOMES = new Set(["declined", "dismissed", "no-ui", "error"]);
+const LEASE_OUTCOMES = new Set([
+  "acquired", "uncontended", "refused", "released", "released-unrecorded", "lost", "retained", "timeout", "recovered",
+]);
+const PROCESS_SIGNALS = new Set([
+  "SIGABRT", "SIGALRM", "SIGBUS", "SIGCHLD", "SIGCONT", "SIGFPE", "SIGHUP", "SIGILL", "SIGINT", "SIGIO",
+  "SIGIOT", "SIGKILL", "SIGPIPE", "SIGPOLL", "SIGPROF", "SIGPWR", "SIGQUIT", "SIGSEGV", "SIGSTKFLT",
+  "SIGSTOP", "SIGSYS", "SIGTERM", "SIGTRAP", "SIGTSTP", "SIGTTIN", "SIGTTOU", "SIGUNUSED", "SIGURG",
+  "SIGUSR1", "SIGUSR2", "SIGVTALRM", "SIGWINCH", "SIGXCPU", "SIGXFSZ", "SIGBREAK", "SIGLOST", "SIGINFO",
+]);
+
+const FIELDS = {
+  capability_decision: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "parentId", "childId", "depth",
+    "agentType", "requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked", "blocked",
+    "reason", "approved", "approvalSource", "approvalSources", "approvalScopes", "approvalExpiresAt",
+    "approvalUses", "approvalScope", "humanDenied", "gateOutcome", "definitionDigest", "executor", "taskFrom",
+    "taskFromExecutionId", "taskDigest", "correlation", "refusal",
+  ]),
+  workspace_lease: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "workspaceId", "root",
+    "access", "outcome", "recovered", "releaseReason", "refusal", "correlation",
+  ]),
+  child_lifecycle: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "state", "executor",
+    "exitCode", "signal", "timedOut", "aborted", "truncated", "reason", "deadlineAt", "herdrPaneId",
+    "herdrAgentName", "correlation",
+  ]),
+  check_receipt: new Set([
+    "ledgerVersion", "event", "ts", "executionId", "parentExecutionId", "childId", "receiptId", "workspaceId",
+    "checkId", "treeSha", "correlation",
+  ]),
+  workflow_fact: new Set([
+    "ledgerVersion", "event", "ts", "factId", "source", "provenance", "kind", "subject", "state", "correlation",
+  ]),
+} as const;
+type EventKind = keyof typeof FIELDS;
+
+export function isLedgerObject(value: unknown): value is LedgerV3Object {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/** Ledger timestamp profile: JSON Schema `date-time`, narrowed to seconds 00-59 for JS date arithmetic. */
+export function isTimestamp(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/.exec(value);
+  if (!match) return false;
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText, , offsetHourText, offsetMinuteText] = match;
+  const year = Number(yearText);
+  const month = Number(monthText);
+  const day = Number(dayText);
+  const hour = Number(hourText);
+  const minute = Number(minuteText);
+  const second = Number(secondText);
+  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59) return false;
+  const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  if (day < 1 || day > days[month - 1]) return false;
+  return offsetHourText === undefined || (Number(offsetHourText) <= 23 && Number(offsetMinuteText) <= 59);
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function optional(event: LedgerV3Object, field: string, valid: (value: unknown) => boolean): boolean {
+  return !Object.hasOwn(event, field) || valid(event[field]);
+}
+
+function stringMap(value: unknown, valid: (entry: unknown) => boolean): boolean {
+  return isLedgerObject(value) && Object.values(value).every(valid);
+}
+
+function capabilityMap(value: unknown, valid: (entry: unknown) => boolean): boolean {
+  return isLedgerObject(value) && Object.keys(value).every(isLedgerCapabilityIdentifier) && Object.values(value).every(valid);
+}
+
+function validCorrelation(value: unknown): boolean {
+  if (!isLedgerObject(value)) return false;
+  try {
+    const normalised = normaliseCorrelation(value as CorrelationMetadata);
+    // `normaliseCorrelation` drops nulls. The closed schema does not, so equality is part of validation.
+    return JSON.stringify(normalised) === JSON.stringify(value);
+  } catch {
+    return false;
+  }
+}
+
+function validRefusal(value: unknown): boolean {
+  if (!isLedgerObject(value) || Object.keys(value).some((key) => !["code", "message", "details"].includes(key))) return false;
+  if (!REFUSAL_CODES.includes(value.code as never) || typeof value.message !== "string") return false;
+  return optional(value, "details", (details) => isLedgerObject(details) && Object.values(details).every(
+    (entry) => entry === null || ["string", "number", "boolean"].includes(typeof entry),
+  ));
+}
+
+function validDefinitionDigest(value: unknown): boolean {
+  return isLedgerObject(value) &&
+    Object.keys(value).every((key) => ["name", "source", "sha256"].includes(key)) &&
+    typeof value.name === "string" && typeof value.source === "string" && SHA256_RE.test(String(value.sha256));
+}
+
+function validApprovalUse(value: unknown): boolean {
+  return isLedgerObject(value) && Object.keys(value).every((key) => ["max", "remaining"].includes(key)) &&
+    Number.isInteger(value.max) && (value.max as number) >= 0 &&
+    Number.isInteger(value.remaining) && (value.remaining as number) >= 0;
+}
+
+function validateBase(event: LedgerV3Object): string | null {
+  if (!isTimestamp(event.ts)) return "ts must be an RFC 3339 timestamp";
+  if (!isExecutionId(event.executionId)) return "executionId is missing or invalid";
+  if (event.parentExecutionId !== null && !isExecutionId(event.parentExecutionId)) {
+    return "parentExecutionId must be an execution id or null";
+  }
+  if (event.parentExecutionId === event.executionId) return "an execution cannot be its own parent";
+  if (!isLedgerDisplayIdentifier(event.childId)) return "childId is missing or invalid";
+  return null;
+}
+
+function validateCapabilityDecision(event: LedgerV3Object): string | null {
+  if (!isLedgerDisplayIdentifier(event.parentId) || !Number.isInteger(event.depth) || (event.depth as number) < 0) {
+    return "capability decision identity is invalid";
+  }
+  for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
+    if (!isStringArray(event[field]) || !event[field].every(isLedgerCapabilityIdentifier)) {
+      return `capability decision ${field} must contain capability identifiers`;
+    }
+  }
+  if (typeof event.blocked !== "boolean" || !EXECUTORS.has(String(event.executor)) || !SHA256_RE.test(String(event.taskDigest))) {
+    return "capability decision required fields are invalid";
+  }
+  if (!optional(event, "agentType", isLedgerDisplayIdentifier) ||
+      !optional(event, "reason", (value) => typeof value === "string") ||
+      !optional(event, "approved", (value) => isStringArray(value) && value.every(isLedgerCapabilityIdentifier)) ||
+      !optional(event, "approvalSource", (value) => APPROVAL_SOURCES.has(String(value))) ||
+      !optional(event, "approvalSources", (value) => capabilityMap(value, (entry) => APPROVAL_SOURCES.has(String(entry)))) ||
+      !optional(event, "approvalScopes", (value) => capabilityMap(value, (entry) => APPROVAL_SCOPES.has(String(entry)))) ||
+      !optional(event, "approvalExpiresAt", (value) => capabilityMap(value, isTimestamp)) ||
+      !optional(event, "approvalUses", (value) => capabilityMap(value, validApprovalUse)) ||
+      !optional(event, "approvalScope", (value) => APPROVAL_SCOPES.has(String(value))) ||
+      !optional(event, "humanDenied", (value) => value === true) ||
+      !optional(event, "gateOutcome", (value) => GATE_OUTCOMES.has(String(value))) ||
+      !optional(event, "definitionDigest", validDefinitionDigest) ||
+      !optional(event, "taskFrom", isLedgerDisplayIdentifier) ||
+      !optional(event, "taskFromExecutionId", isExecutionId) ||
+      !optional(event, "correlation", validCorrelation) ||
+      !optional(event, "refusal", validRefusal)) {
+    return "capability decision optional fields are invalid";
+  }
+  return null;
+}
+
+function validateWorkspaceLease(event: LedgerV3Object): string | null {
+  if (!isLedgerDisplayIdentifier(event.workspaceId) || !isNonEmptyString(event.root) ||
+      !["read", "write"].includes(String(event.access)) || !LEASE_OUTCOMES.has(String(event.outcome))) {
+    return "workspace lease required fields are invalid";
+  }
+  if (!optional(event, "recovered", (value) => value === true || value === false || value === "unknown") ||
+      !optional(event, "releaseReason", (value) => typeof value === "string") ||
+      !optional(event, "refusal", validRefusal) || !optional(event, "correlation", validCorrelation)) {
+    return "workspace lease optional fields are invalid";
+  }
+  return null;
+}
+
+function validateChildLifecycle(event: LedgerV3Object): string | null {
+  if (!["starting", "running", "completed", "failed"].includes(String(event.state)) || !EXECUTORS.has(String(event.executor))) {
+    return "child lifecycle required fields are invalid";
+  }
+  if (["starting", "running"].includes(String(event.state)) && !isTimestamp(event.deadlineAt)) {
+    return "deadlineAt is required and must be an RFC 3339 timestamp for a non-terminal lifecycle";
+  }
+  if (!optional(event, "deadlineAt", isTimestamp) ||
+      !optional(event, "exitCode", (value) => value === null || Number.isInteger(value)) ||
+      !optional(event, "signal", (value) => value === null || PROCESS_SIGNALS.has(String(value))) ||
+      !optional(event, "timedOut", (value) => value === true) ||
+      !optional(event, "aborted", (value) => value === true) ||
+      !optional(event, "truncated", (value) => value === true) ||
+      !optional(event, "reason", (value) => typeof value === "string") ||
+      !optional(event, "correlation", validCorrelation)) {
+    return "child lifecycle optional fields are invalid";
+  }
+  if (!optional(event, "herdrPaneId", isLedgerDisplayIdentifier) ||
+      !optional(event, "herdrAgentName", isLedgerDisplayIdentifier)) {
+    return "Herdr runtime identity is invalid";
+  }
+  if (Object.hasOwn(event, "herdrPaneId") !== Object.hasOwn(event, "herdrAgentName")) {
+    return "Herdr runtime identity must be paired";
+  }
+  if (Object.hasOwn(event, "herdrPaneId") && event.executor !== "herdr") {
+    return "Herdr runtime identity requires the Herdr executor";
+  }
+  return null;
+}
+
+function validateCheckReceipt(event: LedgerV3Object): string | null {
+  if (!SHA256_RE.test(String(event.receiptId)) || !isLedgerDisplayIdentifier(event.workspaceId) ||
+      !isLedgerDisplayIdentifier(event.checkId) || !isNonEmptyString(event.treeSha) ||
+      !optional(event, "correlation", validCorrelation)) {
+    return "check receipt required fields are invalid";
+  }
+  return null;
+}
+
+function validateWorkflowFact(event: LedgerV3Object): string | null {
+  if (!isTimestamp(event.ts) || !isWorkflowFactId(event.factId) ||
+      !isWorkflowIdentifier(event.source) || !isWorkflowIdentifier(event.subject) ||
+      !["planned", "observed", "controller_validated"].includes(String(event.provenance)) ||
+      !["workflow_phase", "inline_skill", "transition"].includes(String(event.kind)) ||
+      !["pending", "observed", "started", "completed", "blocked"].includes(String(event.state)) ||
+      !validCorrelation(event.correlation) ||
+      !isNonEmptyString((event.correlation as LedgerV3Object).run_id)) {
+    return "workflow fact required fields are invalid";
+  }
+  return workflowFactStateMatches(event.provenance, event.state)
+    ? null
+    : "workflow fact provenance contradicts its state";
+}
+
+/** Exact, content-free runtime validation for one closed ledger v3 event. */
+export function validateLedgerV3Event(event: LedgerV3Object): string | null {
+  if (event.ledgerVersion !== 3) return "unsupported ledger version";
+  const kind = event.event;
+  if (typeof kind !== "string" || !Object.hasOwn(FIELDS, kind)) return "unknown ledger event discriminator";
+  const allowed = FIELDS[kind as EventKind];
+  if (Object.keys(event).some((field) => !allowed.has(field))) return "ledger v3 contains an unsupported field";
+  if (kind === "workflow_fact") return validateWorkflowFact(event);
+  const base = validateBase(event);
+  if (base) return base;
+  if (kind === "capability_decision") return validateCapabilityDecision(event);
+  if (kind === "workspace_lease") return validateWorkspaceLease(event);
+  if (kind === "child_lifecycle") return validateChildLifecycle(event);
+  return validateCheckReceipt(event);
+}
+
+/** Ensure a public builder cannot emit bytes the closed v3 reader would reject. */
+export function assertLedgerV3Wire<T extends object>(event: T): T {
+  let wire: unknown;
+  try {
+    wire = JSON.parse(JSON.stringify(event));
+  } catch (error) {
+    throw new TypeError(`invalid ledger v3 event: ${String(error)}`);
+  }
+  if (!isLedgerObject(wire)) throw new TypeError("invalid ledger v3 event: event is not a JSON object");
+  const invalid = validateLedgerV3Event(wire);
+  if (invalid) throw new TypeError(`invalid ledger v3 event: ${invalid}`);
+  return event;
+}

package/src/ledger.ts

@@ -32,27 +32,33 @@ import type { CorrelationMetadata } from "./correlation.ts";
 import type { StructuredRefusal } from "./refusals.ts";
 // Type-only, so the cycle with ./ledger-events.ts is erased at runtime.
 import type { RuntimeLedgerEvent } from "./ledger-events.ts";
+import { assertExecutionId } from "./execution-id.ts";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
 
-export const LEDGER_VERSION = 2 as const;
+export const LEDGER_VERSION = 3 as const;
 export const LEDGER_EVENT_KINDS = [
-  "capability_decision", "workspace_lease", "child_lifecycle", "check_receipt",
+  "capability_decision", "workspace_lease", "child_lifecycle", "check_receipt", "workflow_fact",
 ] as const;
 export type LedgerEventKind = typeof LEDGER_EVENT_KINDS[number];
 export const LEDGER_GATE_OUTCOMES = ["declined", "dismissed", "no-ui", "error"] as const;
 export type LedgerGateOutcome = typeof LEDGER_GATE_OUTCOMES[number];
 
 export interface LedgerEventBase {
-  /** Optional only on the legacy-compatible `GrantRecord` public type; every v2 event builder writes it. */
+  /** Optional only on the legacy-compatible `GrantRecord` public type; every v3 event builder writes it. */
   ledgerVersion?: typeof LEDGER_VERSION;
   event?: LedgerEventKind;
   ts: string;
+  /** Unique execution occurrence. Optional only for legacy, unversioned GrantRecord values. */
+  executionId?: string;
+  /** Explicit execution parent; null means the delegating session is not itself a governed child. */
+  parentExecutionId?: string | null;
   childId?: string;
   correlation?: CorrelationMetadata;
 }
 
 export interface GrantRecord extends LedgerEventBase {
   /**
-   * Present only when a trusted `taskDigest` was supplied — that is what makes a line v2. `buildRecord`
+   * Present only when a trusted `taskDigest` was supplied — that is what makes a line v3. `buildRecord`
    * does NOT always emit it, and the comment here used to say it did while the emission site 200 lines
    * down said the opposite. Two comments asserting contradictory facts about one field is R-28's shape.
    */
@@ -165,6 +171,8 @@ export interface GrantRecord extends LedgerEventBase {
    * `definitionDigest` names its instructions, and neither says where the TASK came from.
    */
   taskFrom?: string;
+  /** Unique occurrence whose output composed this task; taskFrom remains the readable logical position. */
+  taskFromExecutionId?: string;
   /** Trusted SHA-256 of the exact task; task text remains forbidden (ADR-0034). */
   taskDigest?: string;
   /** Stable machine-readable refusal accompanying `reason`. */
@@ -189,6 +197,10 @@ export interface LedgerOptions {
 }
 
 export function buildRecord(args: {
+  /** Required whenever taskDigest makes this an explicit v3 event. */
+  executionId?: string;
+  /** Required (including explicit null) whenever taskDigest makes this an explicit v3 event. */
+  parentExecutionId?: string | null;
   parentId: string;
   childId: string;
   depth: number;
@@ -208,15 +220,21 @@ export function buildRecord(args: {
   definitionDigest?: DefinitionDigest;
   /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
   executor: ExecutorKind;
-  /** The child whose output composed this task (ADR-0033). Absent for anything but a chain step. */
+  /** The logical child whose output composed this task (ADR-0033). */
   taskFrom?: string;
+  /** The unique occurrence whose output composed this task. */
+  taskFromExecutionId?: string;
   taskDigest?: string;
   correlation?: CorrelationMetadata;
   refusal?: StructuredRefusal;
   now: Date;
 }): GrantRecord {
-  if (args.taskDigest !== undefined && !/^[a-f0-9]{64}$/i.test(args.taskDigest)) {
-    throw new TypeError("taskDigest must be a SHA-256 hex digest");
+  if (args.taskDigest !== undefined) {
+    if (!/^[a-f0-9]{64}$/i.test(args.taskDigest)) throw new TypeError("taskDigest must be a SHA-256 hex digest");
+    assertExecutionId(args.executionId);
+    if (args.parentExecutionId !== null) assertExecutionId(args.parentExecutionId, "parentExecutionId");
+    if (args.parentExecutionId === args.executionId) throw new TypeError("an execution cannot be its own parent");
+    if (args.taskFromExecutionId !== undefined) assertExecutionId(args.taskFromExecutionId, "taskFromExecutionId");
   }
   if (args.definitionDigest && !/^[a-f0-9]{64}$/i.test(args.definitionDigest.sha256)) {
     throw new TypeError("definitionDigest.sha256 must be a SHA-256 hex digest");
@@ -227,10 +245,17 @@ export function buildRecord(args: {
   const distinct = [...new Set(Object.values(sources))];
   const scopes = args.approvalScopes ?? {};
   const distinctScopes = [...new Set(Object.values(scopes))];
-  return {
-    // A trusted task digest is what distinguishes a v2 capability event from the legacy construction API.
+  const record: GrantRecord = {
+    // A trusted task digest is what distinguishes a v3 capability event from the legacy construction API.
     // Production delegation always supplies it; old TypeScript callers remain able to append legacy lines.
-    ...(args.taskDigest !== undefined ? { ledgerVersion: LEDGER_VERSION, event: "capability_decision" as const } : {}),
+    ...(args.taskDigest !== undefined
+      ? {
+          ledgerVersion: LEDGER_VERSION,
+          event: "capability_decision" as const,
+          executionId: args.executionId,
+          parentExecutionId: args.parentExecutionId,
+        }
+      : {}),
     ts: args.now.toISOString(),
     parentId: args.parentId,
     childId: args.childId,
@@ -238,6 +263,7 @@ export function buildRecord(args: {
     agentType: args.agentType,
     executor: args.executor,
     ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
+    ...(args.taskFromExecutionId ? { taskFromExecutionId: args.taskFromExecutionId } : {}),
     ...(args.taskDigest !== undefined ? { taskDigest: args.taskDigest } : {}),
     ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
     ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
@@ -265,6 +291,8 @@ export function buildRecord(args: {
     ...(args.gateOutcome && args.gateOutcome !== "granted" ? { gateOutcome: args.gateOutcome } : {}),
     ...(args.definitionDigest ? { definitionDigest: args.definitionDigest } : {}),
   };
+  if (args.taskDigest !== undefined) assertLedgerV3Wire(record);
+  return record;
 }
 
 // R-49: the lock moved to `src/file-lock.ts` so the approvals store could use the SAME one rather than
@@ -334,3 +362,14 @@ export {
   type WorkspaceLeaseOutcome,
   type WorkspaceRecovery,
 } from "./ledger-events.ts";
+
+export {
+  WORKFLOW_FACT_KINDS,
+  WORKFLOW_FACT_PROVENANCE,
+  WORKFLOW_FACT_STATES,
+  buildWorkflowFactEvent,
+  type WorkflowFactEvent,
+  type WorkflowFactKind,
+  type WorkflowFactProvenance,
+  type WorkflowFactState,
+} from "./workflow-facts.ts";

package/src/propagation.ts

@@ -46,6 +46,8 @@ export const ENV_FANOUT = "PI_GRANTS_FANOUT";
  * Without it every level restarts at `d0` and the ledger cannot be joined into a tree across processes.
  */
 export const ENV_PARENT_ID = "PI_GRANTS_PARENT_ID";
+/** Unique identity of this governed execution occurrence; unlike ENV_PARENT_ID it is never reused. */
+export const ENV_EXECUTION_ID = "PI_GRANTS_EXECUTION_ID";
 export const ENV_DEPTH = "PI_GRANTS_DEPTH";
 export const ENV_MAX_DEPTH = "PI_GRANTS_MAX_DEPTH";
 export const ENV_GATED = "PI_GRANTS_GATED";
@@ -68,6 +70,7 @@ export const GRANT_ENV_KEYS = [
   ENV_APPROVED,
   ENV_FANOUT,
   ENV_PARENT_ID,
+  ENV_EXECUTION_ID,
 ] as const;
 
 export const parseList = (raw: string | undefined): Capability[] =>

package/src/run-child.ts

@@ -13,6 +13,15 @@ import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
 import { parseBound } from "./propagation.ts";
 
+interface RunChildTestControl { hardDeadlineAtAfterSpawn(): number }
+const TEST_CONTROL = Symbol.for("pi-daddy.internal.run-child-test-control");
+
+function currentRunChildTestControl(): RunChildTestControl | undefined {
+  if (process.env.NODE_TEST_CONTEXT !== "child-v8") return undefined;
+  const storage = (globalThis as Record<symbol, { getStore(): RunChildTestControl | undefined }>)[TEST_CONTROL];
+  return storage?.getStore();
+}
+
 /**
  * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
  *
@@ -64,9 +73,11 @@ export interface ChildRunRequest {
   signal?: AbortSignal;
   /** Hard cap on captured output. Beyond it the child is killed and the result flagged. */
   maxOutputBytes?: number;
-  /** Wall-clock cap. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. */
+  /** Soft wall-clock cap. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. */
   timeoutMs?: number;
   killGraceMs?: number;
+  /** Absolute epoch-millisecond hard cap: SIGKILL fires here even when the SIGTERM grace has not elapsed. */
+  hardDeadlineAt?: number;
   /**
    * Called with each chunk as it arrives, for the parent's progress display (ADR-0032).
    *
@@ -106,9 +117,11 @@ export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
 export const DEFAULT_KILL_GRACE_MS = 5000;
 
 export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
+  const testControl = currentRunChildTestControl();
   const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
   const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const killGraceMs = request.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  const hardDeadlineAt = request.hardDeadlineAt;
 
   // A-R3: checked BEFORE spawning. `AbortSignal` does not replay, so a listener attached after an
   // `await` cannot observe an abort that already happened — and the child would then run to completion
@@ -160,6 +173,16 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       timers.push(setTimeout(() => child.kill("SIGKILL"), killGraceMs));
     };
 
+    // A timer phase may run before libuv delivers an exit that the OS already observed, especially after the
+    // controller event loop was blocked across the deadline. Give pending child-process events one turn to
+    // publish exitCode/signalCode before deciding that a governed PID is still live.
+    const controlIfRunning = (control: () => void) => {
+      setImmediate(() => {
+        if (done || child.exitCode !== null || child.signalCode !== null) return;
+        control();
+      });
+    };
+
     /** How much of `text` the progress display has already been shown. */
     let emittedUpTo = 0;
 
@@ -225,11 +248,20 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
     child.stderr?.on("data", capture);
 
     timers.push(
-      setTimeout(() => {
+      setTimeout(() => controlIfRunning(() => {
         timedOut = true;
         stop();
-      }, timeoutMs),
+      }), timeoutMs),
     );
+    const activeHardDeadlineAt = testControl?.hardDeadlineAtAfterSpawn() ?? hardDeadlineAt;
+    if (activeHardDeadlineAt !== undefined) {
+      // Independent of the soft timer and measured from the recorded epoch, not from `spawn`: neither a
+      // delayed soft callback nor spawn/setup time may start a fresh grace period beyond the lifecycle bound.
+      timers.push(setTimeout(() => controlIfRunning(() => {
+        timedOut = true;
+        child.kill("SIGKILL");
+      }), Math.max(0, activeHardDeadlineAt - Date.now())));
+    }
 
     const onAbort = () => {
       aborted = true;

package/src/run-herdr.ts

@@ -98,6 +98,8 @@ export interface HerdrRunRequest {
    * name a human can switch to **while the child is alive**, which is the whole point of the pane surviving.
    */
   onPane?: (paneId: string, agentName: string) => void;
+  /** Called only after agent start and prompt both succeed; pane creation alone is still `starting`. */
+  onRunning?: (paneId: string, agentName: string) => void;
   /** Security hook for attaching a writer lease to the tab. Unlike display callbacks, errors fail the run. */
   onTab?: (tabId: string) => void;
   /** Close even a settled pane before releasing a writer lease; no post-lease prompt may remain live. */
@@ -300,6 +302,13 @@ export async function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunRe
 
     const prompted = parseReply(await exec(["agent", "prompt", agentName, request.prompt]));
     if (prompted.error) return { ...empty, spawnError: `herdr agent prompt failed: ${prompted.error}` };
+    if (request.onRunning) {
+      try {
+        request.onRunning(paneId, agentName);
+      } catch {
+        /* display/observation only */
+      }
+    }
 
     const settled = await waitForSettled(exec, { ...request, name: agentName }, before, deadline, maxOutputBytes);
     if (settled.aborted || settled.timedOut) {

package/src/workflow-fact-id.ts

@@ -0,0 +1,16 @@
+const WORKFLOW_FACT_ID_RE = /^fact:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const WORKFLOW_IDENTIFIER_RE = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+
+export function isWorkflowFactId(value: unknown): value is string {
+  return typeof value === "string" && WORKFLOW_FACT_ID_RE.test(value);
+}
+
+export function isWorkflowIdentifier(value: unknown): value is string {
+  return typeof value === "string" && WORKFLOW_IDENTIFIER_RE.test(value);
+}
+
+export function workflowFactStateMatches(provenance: unknown, state: unknown): boolean {
+  return (provenance === "planned" && state === "pending") ||
+    (provenance === "observed" && state === "observed") ||
+    (provenance === "controller_validated" && ["started", "completed", "blocked"].includes(String(state)));
+}

package/src/workflow-facts.ts

@@ -0,0 +1,65 @@
+import { LEDGER_VERSION } from "./ledger.ts";
+import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
+import { isWorkflowFactId, isWorkflowIdentifier, workflowFactStateMatches } from "./workflow-fact-id.ts";
+import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
+
+export const WORKFLOW_FACT_PROVENANCE = ["planned", "observed", "controller_validated"] as const;
+export type WorkflowFactProvenance = typeof WORKFLOW_FACT_PROVENANCE[number];
+export const WORKFLOW_FACT_KINDS = ["workflow_phase", "inline_skill", "transition"] as const;
+export type WorkflowFactKind = typeof WORKFLOW_FACT_KINDS[number];
+export const WORKFLOW_FACT_STATES = ["pending", "observed", "started", "completed", "blocked"] as const;
+export type WorkflowFactState = typeof WORKFLOW_FACT_STATES[number];
+
+export interface WorkflowFactEvent {
+  ledgerVersion: typeof LEDGER_VERSION;
+  event: "workflow_fact";
+  ts: string;
+  factId: string;
+  /** Package/controller identifier, not free-form display text. */
+  source: string;
+  provenance: WorkflowFactProvenance;
+  kind: WorkflowFactKind;
+  /** Phase, skill, or transition identifier. Never task text. */
+  subject: string;
+  state: WorkflowFactState;
+  /** run_id is required by the builder; other values remain non-authoritative labels. */
+  correlation: CorrelationMetadata;
+}
+
+export function buildWorkflowFactEvent(args: {
+  factId: string;
+  source: string;
+  provenance: WorkflowFactProvenance;
+  kind: WorkflowFactKind;
+  subject: string;
+  state: WorkflowFactState;
+  correlation: CorrelationMetadata;
+  now: Date;
+}): WorkflowFactEvent {
+  if (!isWorkflowFactId(args.factId)) throw new TypeError("factId must be a pi-daddy workflow fact id");
+  if (!isWorkflowIdentifier(args.source)) throw new TypeError("workflow fact source must be an identifier");
+  if (!WORKFLOW_FACT_PROVENANCE.includes(args.provenance)) throw new TypeError("workflow fact provenance is not recognised");
+  if (!WORKFLOW_FACT_KINDS.includes(args.kind)) throw new TypeError("workflow fact kind is not recognised");
+  if (!isWorkflowIdentifier(args.subject)) throw new TypeError("workflow fact subject must be an identifier, not task text");
+  if (!WORKFLOW_FACT_STATES.includes(args.state)) throw new TypeError("workflow fact state is not recognised");
+  const correlation = normaliseCorrelation(args.correlation);
+  if (!correlation?.run_id) throw new TypeError("workflow facts require correlation.run_id");
+  if (!workflowFactStateMatches(args.provenance, args.state)) {
+    const expected = args.provenance === "planned" ? "pending" : args.provenance === "observed"
+      ? "observed" : "started, completed, or blocked";
+    throw new TypeError(`${args.provenance.replaceAll("_", "-")} workflow facts must use ${expected}`);
+  }
+  const event: WorkflowFactEvent = {
+    ledgerVersion: LEDGER_VERSION,
+    event: "workflow_fact",
+    ts: args.now.toISOString(),
+    factId: args.factId,
+    source: args.source,
+    provenance: args.provenance,
+    kind: args.kind,
+    subject: args.subject,
+    state: args.state,
+    correlation,
+  };
+  return assertLedgerV3Wire(event);
+}