pi-daddy 0.40.1 → 0.41.0

package/src/advisors/decider.ts

@@ -35,10 +35,8 @@ export interface AdviceRequest {
    * What the advisor is told about the situation, composed by the caller.
    *
    * **Sent, never recorded.** The task is never STORED (ADR-0021) and that still holds — `createAdvisor` writes the
-   * question keys and the answers and never this object. But an advisor cannot judge a task it cannot see, so a
-   * caller that needs one judged does send it, and the operator's consent for that is the advisor being off by
-   * default. An earlier draft of this paragraph said the raw task "must not be shipped to a third party either",
-   * which the first decision point then did; the rule that survived review is the narrower and true one.
+   * question keys and the answers and never this object. Raw task text crosses only when the independent egress
+   * switch permits it; otherwise callers send a structural digest. Neither representation is copied into the record.
    */
   state: Readonly<Record<string, unknown>>;
   questions: Readonly<Record<string, Question>>;

package/src/advisors/settings.ts

@@ -25,9 +25,9 @@
 
 // Spelled once, in the kernel's table, so this layer cannot drift from the list `childEnv` refuses to write.
 export { ENV_ADVISOR_KEY as ADVISOR_KEY_ENV } from "../kernel/env-names.ts";
-import { ENV_ADVISOR, ENV_ADVISOR_KEY, ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
-import { DEFAULT_ADVICE_TIMEOUT_MS } from "./advisor.ts";
-export { ENV_ADVISOR_MODEL } from "../kernel/env-names.ts";
+import { ENV_ADVISOR, ENV_ADVISOR_KEY, ENV_ADVISOR_MODEL, ENV_ADVISOR_TASK_EGRESS } from "../kernel/env-names.ts";
+import { DEFAULT_ADVICE_TIMEOUT_MS, type TaskEgressMode } from "./advisor.ts";
+export { ENV_ADVISOR_MODEL, ENV_ADVISOR_TASK_EGRESS } from "../kernel/env-names.ts";
 export { ENV_ADVISOR } from "../kernel/env-names.ts";
 
 export interface AdvisorSettings {
@@ -37,11 +37,12 @@ export interface AdvisorSettings {
   /** Overrides the adapter's pinned model id; absent means the adapter's own default. */
   model?: string;
   timeoutMs?: number;
+  taskEgress: TaskEgressMode;
   /** Why an advisor is off when the settings asked for one on — reported, never silently applied. */
   refusal?: string;
 }
 
-export const ADVISOR_OFF: AdvisorSettings = Object.freeze({ enabled: false, decider: "none" });
+export const ADVISOR_OFF: AdvisorSettings = Object.freeze({ enabled: false, decider: "none", taskEgress: "digest" });
 
 /**
  * Read the `advisor` block of a project settings file. Absent is off; malformed is off WITH a reason.
@@ -103,6 +104,7 @@ export function advisorSettingsFrom(raw: unknown, env: NodeJS.ProcessEnv = proce
   return {
     enabled: true,
     decider: "jev",
+    taskEgress: env[ENV_ADVISOR_TASK_EGRESS]?.trim() === "raw" ? "raw" : "digest",
     ...(model ? { model } : {}),
     // Clamped, never raised: a longer bound is not a narrowing either, and a child-writable 30s would be a stall on
     // every delegation.

package/src/executors/activity-session.ts

@@ -8,10 +8,18 @@
  * already carries `--session` (native-session retention), that file is the probe; otherwise a private temporary
  * file is allocated for the run and removed afterwards.
  */
-import { mkdtemp, rm, stat } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { mkdtemp, readdir, rm, stat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import type { ChildUsageTotals } from "../governance/ledger-events.ts";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
+export interface ChildUsageObservation {
+  usage?: ChildUsageTotals;
+  unavailable?: "session-missing" | "session-invalid" | "usage-missing";
+}
+
 export interface ActivitySession {
   /** The child argv, with `--session <file>` in place of `--no-session` when a file was allocated here. */
   readonly args: string[];
@@ -19,6 +27,8 @@ export interface ActivitySession {
   readonly path: string;
   /** A marker that changes whenever pi appended to the file; `undefined` until the file exists. */
   probe(): Promise<string | undefined>;
+  /** Aggregate only the current child turn's usage; no transcript content leaves this reader. */
+  usage(): Promise<ChildUsageObservation>;
   /** Remove the temporary file, if this run allocated one. Never removes a retention target. */
   dispose(): Promise<void>;
 }
@@ -50,7 +60,13 @@ export async function activitySessionFor(planArgs: string[], executionId: string
   const fork = planArgs.indexOf("--fork");
   if (fork >= 0) {
     const dir = planArgs[planArgs.indexOf("--session-dir") + 1];
-    return { args: planArgs, path: dir, probe: probeDirectory(dir), dispose: async () => undefined };
+    return {
+      args: planArgs,
+      path: dir,
+      probe: probeDirectory(dir),
+      usage: () => readChildUsage(newestSessionFile(dir)),
+      dispose: async () => undefined,
+    };
   }
   const flag = planArgs.indexOf("--session");
   const probeFor = (path: string) => async () => {
@@ -63,7 +79,13 @@ export async function activitySessionFor(planArgs: string[], executionId: string
   };
   if (flag >= 0 && planArgs[flag + 1]) {
     const path = planArgs[flag + 1];
-    return { args: planArgs, path, probe: probeFor(path), dispose: async () => undefined };
+    return {
+      args: planArgs,
+      path,
+      probe: probeFor(path),
+      usage: () => readChildUsage(path),
+      dispose: async () => undefined,
+    };
   }
   // Private to this uid (mkdtemp is 0o700) and named by the execution so a leaked directory is attributable.
   const directory = await mkdtemp(join(tmpdir(), `pi-daddy-${executionId.replace(/[^a-zA-Z0-9_-]/g, "_")}-`));
@@ -77,6 +99,86 @@ export async function activitySessionFor(planArgs: string[], executionId: string
     args,
     path,
     probe: probeFor(path),
+    usage: () => readChildUsage(path),
     dispose: () => rm(directory, { recursive: true, force: true }).catch(() => undefined),
   };
 }
+
+async function newestSessionFile(directory: string): Promise<string | undefined> {
+  try {
+    const entries = await Promise.all(
+      (await readdir(directory))
+        .filter((name) => name.endsWith(".jsonl"))
+        .map(async (name) => ({ path: join(directory, name), modified: (await stat(join(directory, name))).mtimeMs })),
+    );
+    return entries.sort((a, b) => b.modified - a.modified)[0]?.path;
+  } catch {
+    return undefined;
+  }
+}
+
+const TOKEN_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const;
+const COST_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "total"] as const;
+
+async function readChildUsage(path: string | Promise<string | undefined>): Promise<ChildUsageObservation> {
+  const resolved = await path;
+  if (!resolved) return { unavailable: "session-missing" };
+  const totals = emptyUsage();
+  let found = false;
+  let reasoning = 0;
+  let sawReasoning = false;
+  try {
+    const lines = createInterface({ input: createReadStream(resolved, { encoding: "utf8" }), crlfDelay: Infinity });
+    for await (const line of lines) {
+      let entry: unknown;
+      try {
+        entry = JSON.parse(line);
+      } catch {
+        return { unavailable: "session-invalid" };
+      }
+      const message = object(object(entry)?.message);
+      if (!message) continue;
+      if (message.role === "user") {
+        Object.assign(totals, emptyUsage());
+        found = false;
+        reasoning = 0;
+        sawReasoning = false;
+        continue;
+      }
+      if (message.role !== "assistant" && message.role !== "toolResult") continue;
+      const usage = object(message.usage);
+      if (message.role === "toolResult" && !usage) continue;
+      const cost = object(usage?.cost);
+      if (!usage || !cost) return { unavailable: "session-invalid" };
+      if (!TOKEN_FIELDS.every((field) => nonNegative(usage[field]))) return { unavailable: "session-invalid" };
+      if (!COST_FIELDS.every((field) => nonNegative(cost[field]))) return { unavailable: "session-invalid" };
+      if (usage.reasoning !== undefined && !nonNegative(usage.reasoning)) return { unavailable: "session-invalid" };
+      for (const field of TOKEN_FIELDS) totals[field] += usage[field] as number;
+      for (const field of COST_FIELDS) totals.cost[field] += cost[field] as number;
+      if (usage.reasoning !== undefined) {
+        reasoning += usage.reasoning as number;
+        sawReasoning = true;
+      }
+      found = true;
+    }
+    return found ? { usage: { ...totals, ...(sawReasoning ? { reasoning } : {}) } } : { unavailable: "usage-missing" };
+  } catch {
+    return { unavailable: "session-missing" };
+  }
+}
+
+function emptyUsage(): ChildUsageTotals {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}
+
+const object = (value: unknown): Record<string, unknown> | undefined =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+const nonNegative = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0;

package/src/governance/ledger-events.ts

@@ -9,6 +9,7 @@ import type { ExecutorKind } from "../kernel/delegate-types.ts";
 import type { CorrelationMetadata } from "../kernel/correlation.ts";
 import type { StructuredRefusal } from "../kernel/refusals.ts";
 import { assertExecutionId } from "../kernel/execution-id.ts";
+import { assertEpisodeId } from "../kernel/episode-id.ts";
 import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
 
 export const WORKSPACE_ACCESSES = ["read", "write"] as const;
@@ -62,6 +63,22 @@ export const CHILD_PROCESS_SIGNALS = [
 ] as const satisfies readonly NodeJS.Signals[];
 export type ChildProcessSignal = (typeof CHILD_PROCESS_SIGNALS)[number];
 
+export interface ChildUsageTotals {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  reasoning?: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+
 /**
  * `released` is a handover this owner performed. FOUR members were added by the 0.18.0 review pass, and
  * they were not all previously recorded the same way — `uncontended` was recorded as an *acquisition*, and
@@ -123,6 +140,10 @@ export interface ChildLifecycleEvent extends LedgerEventBase {
   reason?: string;
   /** The inactivity bound (ms) that governed this child beside the `deadlineAt` ceiling (PR 3e). */
   idleTimeoutMs?: number;
+  /** Aggregate model usage read from the child's pi session file after it stopped. */
+  usage?: ChildUsageTotals;
+  /** Why totals could not be read; a fixed code, never transcript content. */
+  usageUnavailable?: "session-missing" | "session-invalid" | "usage-missing";
 }
 
 export type CapabilityDecisionEvent = GrantRecord & {
@@ -136,6 +157,7 @@ export type CapabilityDecisionEvent = GrantRecord & {
 export type RuntimeLedgerEvent = CapabilityDecisionEvent | WorkspaceLeaseEvent | ChildLifecycleEvent;
 
 export function buildWorkspaceLeaseEvent(args: {
+  episodeId?: string;
   executionId: string;
   parentExecutionId: string | null;
   childId: string;
@@ -154,6 +176,7 @@ export function buildWorkspaceLeaseEvent(args: {
     ledgerVersion: LEDGER_VERSION,
     event: "workspace_lease",
     ts: args.now.toISOString(),
+    ...(args.episodeId ? { episodeId: args.episodeId } : {}),
     executionId: args.executionId,
     parentExecutionId: args.parentExecutionId,
     childId: args.childId,
@@ -173,6 +196,7 @@ export function buildWorkspaceLeaseEvent(args: {
 }
 
 export function buildChildLifecycleEvent(args: {
+  episodeId?: string;
   executionId: string;
   parentExecutionId: string | null;
   childId: string;
@@ -188,6 +212,8 @@ export function buildChildLifecycleEvent(args: {
   aborted?: boolean;
   truncated?: boolean;
   reason?: string;
+  usage?: ChildUsageTotals;
+  usageUnavailable?: "session-missing" | "session-invalid" | "usage-missing";
   correlation?: CorrelationMetadata;
   now: Date;
 }): ChildLifecycleEvent {
@@ -196,6 +222,7 @@ export function buildChildLifecycleEvent(args: {
     ledgerVersion: LEDGER_VERSION,
     event: "child_lifecycle",
     ts: args.now.toISOString(),
+    ...(args.episodeId ? { episodeId: args.episodeId } : {}),
     executionId: args.executionId,
     parentExecutionId: args.parentExecutionId,
     childId: args.childId,
@@ -211,11 +238,18 @@ export function buildChildLifecycleEvent(args: {
     ...(args.aborted ? { aborted: true } : {}),
     ...(args.truncated ? { truncated: true } : {}),
     ...(args.reason ? { reason: args.reason } : {}),
+    ...(args.usage ? { usage: structuredClone(args.usage) } : {}),
+    ...(args.usageUnavailable ? { usageUnavailable: args.usageUnavailable } : {}),
     ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
   });
 }
 
-function assertEventIdentity(args: { executionId: string; parentExecutionId: string | null }): void {
+function assertEventIdentity(args: {
+  episodeId?: string;
+  executionId: string;
+  parentExecutionId: string | null;
+}): void {
+  if (args.episodeId !== undefined) assertEpisodeId(args.episodeId);
   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");

package/src/governance/ledger-v3-validation.ts

@@ -1,5 +1,6 @@
 import { normaliseCorrelation, type CorrelationMetadata } from "../kernel/correlation.ts";
 import { isExecutionId } from "../kernel/execution-id.ts";
+import { isEpisodeId } from "../kernel/episode-id.ts";
 import { REFUSAL_CODES } from "../kernel/refusals.ts";
 import { isLedgerCapabilityIdentifier, isLedgerDisplayIdentifier } from "../kernel/ledger-identifiers.ts";
 
@@ -77,6 +78,7 @@ const FIELDS = {
     "ledgerVersion",
     "event",
     "ts",
+    "episodeId",
     "executionId",
     "parentExecutionId",
     "parentId",
@@ -113,6 +115,7 @@ const FIELDS = {
     "ledgerVersion",
     "event",
     "ts",
+    "episodeId",
     "executionId",
     "parentExecutionId",
     "childId",
@@ -129,6 +132,7 @@ const FIELDS = {
     "ledgerVersion",
     "event",
     "ts",
+    "episodeId",
     "executionId",
     "parentExecutionId",
     "childId",
@@ -142,6 +146,8 @@ const FIELDS = {
     "reason",
     "deadlineAt",
     "idleTimeoutMs",
+    "usage",
+    "usageUnavailable",
     "herdrPaneId",
     "herdrAgentName",
     "correlation",
@@ -159,6 +165,9 @@ export function isNonEmptyString(value: unknown): value is string {
   return typeof value === "string" && value.length > 0;
 }
 
+const nonNegativeNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value) && value >= 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;
@@ -245,6 +254,7 @@ function validApprovalUse(value: unknown): boolean {
 
 function validateBase(event: LedgerV3Object): string | null {
   if (!isTimestamp(event.ts)) return "ts must be an RFC 3339 timestamp";
+  if (!optional(event, "episodeId", isEpisodeId)) return "episodeId is invalid";
   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";
@@ -317,6 +327,33 @@ function validateWorkspaceLease(event: LedgerV3Object): string | null {
   return null;
 }
 
+function validUsage(value: unknown): boolean {
+  if (
+    !isLedgerObject(value) ||
+    Object.keys(value).some(
+      (key) => !["input", "output", "cacheRead", "cacheWrite", "reasoning", "totalTokens", "cost"].includes(key),
+    )
+  )
+    return false;
+  const tokenFields = ["input", "output", "cacheRead", "cacheWrite", "totalTokens"];
+  if (
+    !tokenFields.every(
+      (field) => typeof value[field] === "number" && Number.isFinite(value[field]) && (value[field] as number) >= 0,
+    )
+  )
+    return false;
+  if (!optional(value, "reasoning", nonNegativeNumber)) return false;
+  const cost = value.cost;
+  if (
+    !isLedgerObject(cost) ||
+    Object.keys(cost).some((key) => !["input", "output", "cacheRead", "cacheWrite", "total"].includes(key))
+  )
+    return false;
+  return ["input", "output", "cacheRead", "cacheWrite", "total"].every(
+    (field) => typeof cost[field] === "number" && Number.isFinite(cost[field]) && (cost[field] as number) >= 0,
+  );
+}
+
 function validateChildLifecycle(event: LedgerV3Object): string | null {
   if (
     !["starting", "running", "completed", "failed"].includes(String(event.state)) ||
@@ -336,10 +373,17 @@ function validateChildLifecycle(event: LedgerV3Object): string | null {
     !optional(event, "aborted", (value) => value === true) ||
     !optional(event, "truncated", (value) => value === true) ||
     !optional(event, "reason", (value) => typeof value === "string") ||
+    !optional(event, "usage", validUsage) ||
+    !optional(event, "usageUnavailable", (value) =>
+      ["session-missing", "session-invalid", "usage-missing"].includes(String(value)),
+    ) ||
     !optional(event, "correlation", validCorrelation)
   ) {
     return "child lifecycle optional fields are invalid";
   }
+  if (Object.hasOwn(event, "usage") && Object.hasOwn(event, "usageUnavailable")) {
+    return "child lifecycle usage and usageUnavailable are mutually exclusive";
+  }
   if (
     !optional(event, "herdrPaneId", isLedgerDisplayIdentifier) ||
     !optional(event, "herdrAgentName", isLedgerDisplayIdentifier)

package/src/governance/ledger.ts

@@ -31,6 +31,7 @@ import type { StructuredRefusal } from "../kernel/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 "../kernel/execution-id.ts";
+import { assertEpisodeId } from "../kernel/episode-id.ts";
 import { assertLedgerV3Wire } from "./ledger-v3-validation.ts";
 
 export const LEDGER_VERSION = 3 as const;
@@ -44,6 +45,8 @@ export interface LedgerEventBase {
   ledgerVersion?: typeof LEDGER_VERSION;
   event?: LedgerEventKind;
   ts: string;
+  /** Stable root episode; absent only on records written before episode identity shipped. */
+  episodeId?: 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. */
@@ -206,6 +209,8 @@ export interface LedgerOptions {
 }
 
 export function buildRecord(args: {
+  /** Stable root episode; optional only for source compatibility with historical callers. */
+  episodeId?: string;
   /** Required whenever taskDigest makes this an explicit v3 event. */
   executionId?: string;
   /** Required (including explicit null) whenever taskDigest makes this an explicit v3 event. */
@@ -239,6 +244,7 @@ export function buildRecord(args: {
   refusal?: StructuredRefusal;
   now: Date;
 }): GrantRecord {
+  if (args.episodeId !== undefined) assertEpisodeId(args.episodeId);
   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);
@@ -267,6 +273,7 @@ export function buildRecord(args: {
         }
       : {}),
     ts: args.now.toISOString(),
+    ...(args.episodeId ? { episodeId: args.episodeId } : {}),
     parentId: args.parentId,
     childId: args.childId,
     depth: args.depth,
@@ -388,6 +395,7 @@ export {
   type ChildLifecycleEvent,
   type ChildLifecycleState,
   type ChildProcessSignal,
+  type ChildUsageTotals,
   type RuntimeLedgerEvent,
   type WorkspaceAccess,
   type WorkspaceLeaseEvent,

package/src/kernel/delegate-types.ts

@@ -59,6 +59,8 @@ export interface DelegationRequest {
 
 export interface DelegationContext {
   ownGrant: Capability[];
+  /** Stable identity shared by the root session and every descendant. */
+  episodeId?: string;
   depth: number;
   maxDepth: number;
   gated: Capability[];

package/src/kernel/delegate.ts

@@ -17,6 +17,7 @@ import {
   ENV_APPROVED,
   ENV_DEPTH,
   ENV_EXECUTION_ID,
+  ENV_EPISODE_ID,
   ENV_FANOUT,
   ENV_GATED,
   ENV_GRANT,
@@ -389,6 +390,7 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   if (ctx.fanoutBudget !== undefined) env[ENV_FANOUT] = String(ctx.fanoutBudget);
   if (ctx.childSpawnId) env[ENV_PARENT_ID] = ctx.childSpawnId;
   if (ctx.childExecutionId) env[ENV_EXECUTION_ID] = ctx.childExecutionId;
+  if (ctx.episodeId) env[ENV_EPISODE_ID] = ctx.episodeId;
   if (ctx.gated.length > 0) env[ENV_GATED] = ctx.gated.join(",");
   // Approvals ride down with the grant, but only ever for what this child actually received — so
   // `approved ⊆ grant` holds at every level (ADR-0010). Written even when empty, so this object states

package/src/kernel/env-names.ts

@@ -23,6 +23,7 @@ export const ENV_APPROVED = "PI_DADDY_APPROVED";
 export const ENV_FANOUT = "PI_DADDY_FANOUT";
 export const ENV_PARENT_ID = "PI_DADDY_PARENT_ID";
 export const ENV_EXECUTION_ID = "PI_DADDY_EXECUTION_ID";
+export const ENV_EPISODE_ID = "PI_DADDY_EPISODE_ID";
 
 // Operator preferences a child inherits unchanged. Still governance: they decide executor, deadlines, gates.
 export const ENV_HERDR = "PI_DADDY_HERDR";
@@ -64,6 +65,8 @@ export const ENV_ADVISOR_KEY = "PI_DADDY_ADVISOR_KEY";
 export const ENV_ADVISOR = "PI_DADDY_ADVISOR";
 /** Overrides the adapter's pinned model. In the environment, never the workspace file: a model is a destination. */
 export const ENV_ADVISOR_MODEL = "PI_DADDY_ADVISOR_MODEL";
+/** Exact `raw` opts into sending task text; absent or any other value uses a structural digest. */
+export const ENV_ADVISOR_TASK_EGRESS = "PI_DADDY_ADVISOR_TASK_EGRESS";
 
 /** Every variable that shapes governance. The `childEnv` hook may set none of these. */
 export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
@@ -76,6 +79,7 @@ export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
   ENV_FANOUT,
   ENV_PARENT_ID,
   ENV_EXECUTION_ID,
+  ENV_EPISODE_ID,
   ENV_HERDR,
   ENV_HERDR_WORKSPACE,
   ENV_HERDR_KEEP_PANE,
@@ -93,6 +97,7 @@ export const GOVERNANCE_ENV_KEYS: readonly string[] = Object.freeze([
   ENV_ADVISOR_KEY,
   ENV_ADVISOR,
   ENV_ADVISOR_MODEL,
+  ENV_ADVISOR_TASK_EGRESS,
 ]);
 
 /**

package/src/kernel/episode-id.ts

@@ -0,0 +1,18 @@
+import { randomUUID } from "node:crypto";
+
+/** Stable identity for one root session and every governed descendant it starts. */
+export type EpisodeId = `episode:${string}`;
+
+const EPISODE_ID_RE = /^episode:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isEpisodeId(value: unknown): value is EpisodeId {
+  return typeof value === "string" && EPISODE_ID_RE.test(value);
+}
+
+export function newEpisodeId(): EpisodeId {
+  return `episode:${randomUUID()}`;
+}
+
+export function assertEpisodeId(value: unknown, field = "episodeId"): asserts value is EpisodeId {
+  if (!isEpisodeId(value)) throw new TypeError(`${field} must be a pi-daddy episode id`);
+}

package/src/kernel/propagation.ts

@@ -33,12 +33,14 @@ import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
 import {
   ENV_ADVISOR_MODEL,
+  ENV_ADVISOR_TASK_EGRESS,
   ENV_ADVISOR_KEY,
   ENV_ADVISOR,
   ENV_GRANT,
   ENV_FANOUT,
   ENV_PARENT_ID,
   ENV_EXECUTION_ID,
+  ENV_EPISODE_ID,
   ENV_DEPTH,
   ENV_MAX_DEPTH,
   ENV_GATED,
@@ -51,6 +53,7 @@ export {
   ENV_FANOUT,
   ENV_PARENT_ID,
   ENV_EXECUTION_ID,
+  ENV_EPISODE_ID,
   ENV_DEPTH,
   ENV_MAX_DEPTH,
   ENV_GATED,
@@ -88,6 +91,7 @@ export const GRANT_ENV_KEYS = [
   // child. Named here rather than claimed away: "stripped from every child" would be false on that path.
   ENV_ADVISOR_KEY,
   ENV_ADVISOR,
+  ENV_ADVISOR_TASK_EGRESS,
   ENV_GRANT,
   ENV_DEPTH,
   ENV_MAX_DEPTH,
@@ -97,6 +101,7 @@ export const GRANT_ENV_KEYS = [
   ENV_FANOUT,
   ENV_PARENT_ID,
   ENV_EXECUTION_ID,
+  ENV_EPISODE_ID,
   // ADR-0042: a child must never keep its parent's unnarrowed pin, so it is stripped like every other
   // governance value and re-supplied only by the spawn plan.
   ENV_WORKSPACE_PIN,
@@ -262,6 +267,8 @@ export interface ChildEnvInput {
    * child then inherits no pin and can route nowhere — which is the fail-closed direction.
    */
   workspacePin?: WorkspacePins;
+  /** Stable identity shared by this root session and every descendant. */
+  episodeId?: string;
   /** This session's depth; children are one deeper. */
   depth: number;
   maxDepth: number;
@@ -342,6 +349,7 @@ export function childEnv(input: ChildEnvInput): Record<string, string> {
   env[ENV_APPROVED] = inheritApprovals(input.approved ?? [], inheritable).join(",");
   // Empty is an explicit one-run ledger opt-out and must overwrite a prior publication too.
   if (input.ledgerPath !== undefined) env[ENV_LEDGER] = input.ledgerPath;
+  if (input.episodeId !== undefined) env[ENV_EPISODE_ID] = input.episodeId;
   // ADR-0042. ALWAYS written when this session has any pin at all, empty string included, for the same reason
   // `ENV_APPROVED` is: an omitted key does not overwrite, so a child would inherit the PARENT's unnarrowed pin
   // through the process-global publication path. An empty value parses back as "a pin was established and you

package/src/products/activity-timeline.ts

@@ -4,6 +4,8 @@ import { constants } from "node:fs";
 import { appendFile, mkdir, open, readFile, realpath, rename, writeFile } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import { activityTimelinePath } from "../kernel/project-paths.ts";
+import { isEpisodeId, newEpisodeId } from "../kernel/episode-id.ts";
+import { ENV_EPISODE_ID } from "../kernel/env-names.ts";
 import { appendRecord, readRecords } from "../governance/record.ts";
 
 export const ACTIVITY_TIMELINE_VERSION = 1 as const;
@@ -35,6 +37,8 @@ export interface ActivityEvent {
   kind: string;
   at: string;
   rootId: string;
+  /** Added after v1 shipped; absent on retained events written before episode identity existed. */
+  episodeId?: string;
   taskId: string;
   parentTaskId?: string;
   agentId?: string;
@@ -541,6 +545,7 @@ export class ActivityTimelineRecorder {
   readonly contentEnabled: boolean;
   readonly path: string;
   readonly rootId: string;
+  readonly episodeId: string;
   private taskId?: string;
   constructor(cwd: string, env: NodeJS.ProcessEnv = process.env) {
     const configured = env[ENV_ACTIVITY_TIMELINE]?.trim();
@@ -550,6 +555,8 @@ export class ActivityTimelineRecorder {
     const identity = activityIdentity(cwd, env);
     this.path = identity.path;
     this.rootId = identity.rootId;
+    const inheritedEpisodeId = env[ENV_EPISODE_ID]?.trim();
+    this.episodeId = isEpisodeId(inheritedEpisodeId) ? inheritedEpisodeId : newEpisodeId();
     this.taskId = identity.taskId;
   }
   get task(): string | undefined {
@@ -620,6 +627,7 @@ export class ActivityTimelineRecorder {
       kind,
       at: new Date().toISOString(),
       rootId: this.rootId,
+      episodeId: this.episodeId,
       taskId: this.taskId,
       ...fields,
     };