pi-daddy 0.40.1 → 0.41.1

package/extensions/activity-timeline.ts

@@ -3,6 +3,7 @@ import { createHash, randomUUID } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ENV_EPISODE_ID } from "../src/kernel/env-names.ts";
 import { Type } from "typebox";
 import {
   ActivityTimelineRecorder,
@@ -13,6 +14,7 @@ import {
 
 export interface ActivitySessionState {
   activityRootId?: string;
+  episodeId?: string;
   activity?: ActivityIdentity & { taskId?: string };
 }
 interface HookContext {
@@ -44,15 +46,19 @@ export function registerActivityTimeline(pi: ExtensionAPI, session?: ActivitySes
     }
   };
   const current = (ctx: HookContext): ActivityTimelineRecorder => {
-    const env =
-      session?.activityRootId && !process.env.PI_DADDY_ACTIVITY_ROOT
-        ? { ...process.env, PI_DADDY_ACTIVITY_ROOT: session.activityRootId }
-        : process.env;
+    const env = {
+      ...process.env,
+      ...(session?.activityRootId && !process.env.PI_DADDY_ACTIVITY_ROOT
+        ? { PI_DADDY_ACTIVITY_ROOT: session.activityRootId }
+        : {}),
+      ...(session?.episodeId ? { [ENV_EPISODE_ID]: session.episodeId } : {}),
+    };
     // session_start binds reload ownership after this hook registration; re-create before the first turn
     // if that binding recovered a prior root identity rather than the factory's provisional UUID.
     if (
       !recorder ||
-      (!process.env.PI_DADDY_ACTIVITY_ROOT && session?.activityRootId && recorder.rootId !== session.activityRootId)
+      (!process.env.PI_DADDY_ACTIVITY_ROOT && session?.activityRootId && recorder.rootId !== session.activityRootId) ||
+      (session?.episodeId !== undefined && recorder.episodeId !== session.episodeId)
     )
       recorder = new ActivityTimelineRecorder(ctx.cwd, env);
     return recorder;

package/extensions/advisor-session.ts

@@ -33,6 +33,7 @@ export function createAdvisorSession(input: {
   block: unknown;
   ledgerPath?: string;
   env?: NodeJS.ProcessEnv;
+  episodeId?: string;
 }): AdvisorSession {
   const env = input.env ?? process.env;
   const settings = advisorSettingsFrom(input.block, env);
@@ -58,6 +59,8 @@ export function createAdvisorSession(input: {
       decider,
       record,
       enabled: settings.enabled,
+      taskEgress: settings.taskEgress,
+      ...(input.episodeId ? { episodeId: input.episodeId } : {}),
       ...(settings.timeoutMs ? { timeoutMs: settings.timeoutMs } : {}),
     }),
   };

package/extensions/chain-ledger.ts

@@ -21,6 +21,7 @@ export async function recordChainRefusal(input: {
   await appendRecord(
     { path: input.session.ledgerPath, strict: true },
     buildRecord({
+      episodeId: input.session.episodeId,
       executionId: input.executionId,
       parentExecutionId: input.parentExecutionId,
       parentId: input.session.ownSpawnId,

package/extensions/context-shape.ts

@@ -7,7 +7,12 @@
  * first. This shape exists to tell the model what the parameter is for.
  */
 import { Type } from "typebox";
-import { CONTEXT_MODES } from "../src/kernel/context-handoff.ts";
+import {
+  CONTEXT_MODES,
+  DEFAULT_CONTEXT_TURNS,
+  MAX_CONTEXT_FILES,
+  MAX_CONTEXT_TURNS,
+} from "../src/kernel/context-handoff.ts";
 
 export function contextShape() {
   return Type.Object({
@@ -18,13 +23,23 @@ export function contextShape() {
           "What of YOUR session this sub-agent receives. none: nothing beyond its definition and the task. " +
           "files: the contents of paths you name. pruned: recent turns of your session plus turns naming those " +
           "files. summary: what you write in 'summary'. fork: your whole session (needs a human's approval). " +
-          "A definition's allowed-tools caps this; asking for more than it permits is refused.",
+          "A definition's allowed-tools caps this; asking for more than it permits is refused. If the child has " +
+          "read tools in the same workspace, prefer none and ask it to inspect the checkout instead of embedding files.",
       },
     ),
     files: Type.Optional(
-      Type.Array(Type.String(), { description: "Repository-relative paths, for files and pruned." }),
+      Type.Array(Type.String({ minLength: 1 }), {
+        maxItems: MAX_CONTEXT_FILES,
+        description: `At most ${MAX_CONTEXT_FILES} repository-relative paths, for files and pruned.`,
+      }),
     ),
     summary: Type.Optional(Type.String({ description: "What the sub-agent needs to know, in your own words." })),
-    turns: Type.Optional(Type.Number({ description: "For pruned: how many recent turns to keep. Default 6." })),
+    turns: Type.Optional(
+      Type.Integer({
+        minimum: 1,
+        maximum: MAX_CONTEXT_TURNS,
+        description: `For pruned: how many recent turns to keep. Default ${DEFAULT_CONTEXT_TURNS}.`,
+      }),
+    ),
   });
 }

package/extensions/delegation-ledger.ts

@@ -29,6 +29,7 @@ export async function recordDelegationDecision(input: {
   await appendRecord(
     { path: ledgerPath, strict: true },
     buildRecord({
+      episodeId: session.episodeId,
       executionId: ids.executionId,
       parentExecutionId: ids.parentExecutionId,
       parentId: ids.parentId,

package/extensions/effort-advice.ts

@@ -38,6 +38,7 @@ export async function adviseEffort(input: {
   model?: string;
   registry: { find(provider: string, modelId: string): unknown };
   task: string;
+  executionId?: string;
   agent?: string;
   signal?: AbortSignal;
 }): Promise<string | undefined> {
@@ -52,14 +53,13 @@ export async function adviseEffort(input: {
   // ledger line to be told the only thing that could be said.
   if (levels.length < 2) return undefined;
 
+  const task = advisor.task(input.task);
   const advice = await advisor.ask(
     EFFORT_PURPOSE,
     {
-      // The task text is what the decision is actually about, and it is the one thing this package has never
-      // stored (ADR-0021). It is sent to the advisor because an advisor cannot judge a task it cannot see, and it
-      // is NOT recorded: `createAdvisor` writes the question keys and the answer, never the state. An operator who
-      // is not willing to send task text to a third party leaves the advisor off, which is the default.
-      state: { task: input.task, ...(input.agent ? { definition: input.agent } : {}) },
+      // Raw text is a separate opt-in from enabling the advisor. By default `advisor.task` returns only structural
+      // facts; raw mode preserves the prior request, including the definition name.
+      state: { task, ...(typeof task === "string" && input.agent ? { definition: input.agent } : {}) },
       questions: {
         effort: {
           kind: "choice",
@@ -70,6 +70,7 @@ export async function adviseEffort(input: {
       },
     },
     input.signal,
+    input.executionId,
   );
   const chosen = advice?.answers.effort;
   // Belt and braces: `parseAnswer` already refuses a choice outside the options it was given, so this can only

package/extensions/execute-child.ts

@@ -22,6 +22,7 @@ import { resolveWorkspace } from "../src/executors/herdr-cli.ts";
 import { HerdrWriterCloseError, runHerdrPane } from "../src/executors/run-herdr.ts";
 import { GovernanceRefusal, refusal, type StructuredRefusal } from "../src/kernel/refusals.ts";
 import { ENV_HERDR_KEEP_PANE, type GrantsSession } from "./session.ts";
+import { ENV_EPISODE_ID } from "../src/kernel/env-names.ts";
 import { releaseDelegationWorkspace, type PreparedWorkspace } from "./workspace-runtime.ts";
 import { ActivityTimelineRecorder, ENV_ACTIVITY_PARENT_TASK } from "../src/products/activity-timeline.ts";
 export interface DelegationOutcome {
@@ -120,6 +121,7 @@ export async function executePlannedChild(input: {
       "PI_DADDY_ACTIVITY_ROOT",
       "PI_DADDY_ACTIVITY_TASK",
       ENV_ACTIVITY_PARENT_TASK,
+      ENV_EPISODE_ID,
     ]) {
       const value = plan.env[name];
       if (value) env[name] = value;
@@ -177,6 +179,7 @@ export async function executePlannedChild(input: {
         await appendLedgerEvent(
           { path: ledgerPath, strict: true },
           buildChildLifecycleEvent({
+            episodeId: session.episodeId,
             executionId,
             parentExecutionId,
             childId,
@@ -192,6 +195,7 @@ export async function executePlannedChild(input: {
         await releaseDelegationWorkspace({
           prepared: preparedWorkspace,
           childId,
+          episodeId: session.episodeId,
           executionId,
           parentExecutionId,
           reason: "ledger-failed",
@@ -252,6 +256,7 @@ export async function executePlannedChild(input: {
             onFailure: (cause) => teardownFailures.push(`child runtime identity record failed: ${String(cause)}`),
           },
           buildChildLifecycleEvent({
+            episodeId: session.episodeId,
             executionId,
             parentExecutionId,
             childId,
@@ -337,6 +342,7 @@ export async function executePlannedChild(input: {
         truncated: output.truncated,
         failed: childFailed,
       });
+      const usageObservation = await activitySession.usage();
       releaseReason = output.timedOut ? "timeout" : output.aborted ? "cancelled" : childFailed ? "failed" : "completed";
       if (activityStarted)
         try {
@@ -366,6 +372,7 @@ export async function executePlannedChild(input: {
               onFailure: (cause) => teardownFailures.push(`child lifecycle record failed: ${String(cause)}`),
             },
             buildChildLifecycleEvent({
+              episodeId: session.episodeId,
               executionId,
               parentExecutionId,
               childId,
@@ -379,6 +386,9 @@ export async function executePlannedChild(input: {
               idleTimeoutMs: configuredIdleMs,
               reason:
                 output.spawnError ?? (output.timedOut ? (output.idle ? "idle-timeout" : "wall-clock") : undefined),
+              ...(usageObservation.usage
+                ? { usage: usageObservation.usage }
+                : { usageUnavailable: usageObservation.unavailable! }),
               correlation: plan.correlation,
               now: new Date(),
             }),
@@ -462,6 +472,7 @@ export async function executePlannedChild(input: {
         failed: true,
       });
       retainWriterLease = Boolean(writerLease && isHerdrWriterCloseFailure(error));
+      const usageObservation = await activitySession.usage();
       if (ledgerPath && !terminalAttempted) {
         // Best-effort: this records the failure, so it must not REPLACE the failure. A strict append that
         // throws here would discard the original error — including HerdrWriterCloseError, whose whole
@@ -474,6 +485,7 @@ export async function executePlannedChild(input: {
               onFailure: (cause) => teardownFailures.push(`child lifecycle record failed: ${String(cause)}`),
             },
             buildChildLifecycleEvent({
+              episodeId: session.episodeId,
               executionId,
               parentExecutionId,
               childId,
@@ -486,6 +498,9 @@ export async function executePlannedChild(input: {
                   : error instanceof Error
                     ? error.name
                     : "unknown executor error",
+              ...(usageObservation.usage
+                ? { usage: usageObservation.usage }
+                : { usageUnavailable: usageObservation.unavailable! }),
               correlation: plan.correlation,
               now: new Date(),
             }),
@@ -536,6 +551,7 @@ export async function executePlannedChild(input: {
         await releaseDelegationWorkspace({
           prepared: preparedWorkspace,
           childId,
+          episodeId: session.episodeId,
           executionId,
           parentExecutionId,
           ledgerPath,

package/extensions/grant-store-refusal.ts

@@ -22,6 +22,7 @@ export async function reportGrantStoreRefusal(session: GrantsSession, ui: Refusa
     await appendRecord(
       { path: session.ledgerPath, strict: true },
       buildRecord({
+        episodeId: session.episodeId,
         executionId: newExecutionId(),
         parentExecutionId: null,
         parentId: session.ownSpawnId,

package/extensions/grants-command.ts

@@ -32,8 +32,8 @@ export interface GrantsCommandContext {
    * sentence from the one the session banner printed. Two spellings of one fact is R-28.
    */
   executor: ExecutorChoice;
-  /** ADR-0077: which advisor is in force, or why none is. Reported because an advisor sends task text out. */
-  advisor: { decider: string; refusal?: string };
+  /** ADR-0077: which advisor and task-egress mode are in force, or why none is. */
+  advisor: { decider: string; taskEgress: "digest" | "raw"; refusal?: string };
   /** ADR-0042: which ids this session pinned, so a routing refusal is discoverable before it happens. */
   workspacePin?: ReadonlyMap<string, string>;
   /** Registry ids this machine has never accepted: present, not routable, and worth naming (rule 8). */
@@ -384,10 +384,10 @@ export const grantsCommand = {
       `  depth      ${depth} of max ${maxDepth}${maxDepth <= 0 ? " (spawning disabled)" : ""}`,
       // Rule 8's loud half, which review found missing: an operator who upgraded from 0.34.0, or who mistyped the
       // variable, saw an advisor silently absent and nothing saying why. This is also where an operator sees that
-      // task text leaves the machine, which no other surface says.
+      // which representation of the task leaves the machine, which no other status surface says.
       advisor.decider === "none"
         ? `  advisor    off${advisor.refusal ? ` — ${advisor.refusal}` : ""}`
-        : `  advisor    ${advisor.decider} — a delegation with no thinking level sends it the task text; ` +
+        : `  advisor    ${advisor.decider} — task egress ${advisor.taskEgress}; ` +
           `a pruned context handoff also sends session turns`,
       `  ledger     ${ledgerPath || "(not recording — set PI_DADDY_LEDGER)"}`,
       `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +

package/extensions/grants.ts

@@ -35,7 +35,7 @@ import { registerDelegationTools } from "./delegation.ts";
 import { grantsCommand } from "./grants-command.ts";
 import { runInit } from "./init-command.ts";
 import { planWithApprovals } from "./run-delegation.ts";
-import { createGrantsSession, loadProjectDefinitions, type GrantsSession } from "./session.ts";
+import { createGrantsSession, loadProjectDefinitions, reconcileAdvisorSession, type GrantsSession } from "./session.ts";
 import { acceptWorkspaces } from "../src/governance/workspace-acceptance.ts";
 import { loadWorkspaceRegistry } from "../src/kernel/workspace.ts";
 import { bindReloadLifecycle } from "./reload-environment.ts";
@@ -93,6 +93,7 @@ export default function (pi: ExtensionAPI) {
     // execution tree across workspaces. Resolve it once at the root's actual pi cwd; descendants inherit
     // this absolute identity verbatim, and resolve(abs) remains abs at every deeper session start.
     if (session.ledgerPath) session.ledgerPath = resolve(ctx.cwd, session.ledgerPath);
+    reconcileAdvisorSession(session, reload.environment);
     try {
       // ADR-0076 PR 3d: a pre-format project ledger is imported once into the record envelope, bodies verbatim, each
       // record marked with its source line; the old file is left untouched. Happens before any spawn can append.
@@ -341,6 +342,7 @@ export default function (pi: ExtensionAPI) {
       await appendRecord(
         { path: session.ledgerPath, strict: true },
         buildRecord({
+          episodeId: session.episodeId,
           parentId: `d${session.depth}`,
           childId: `${event.toolName}@d${session.depth + 1}`,
           depth: session.depth + 1,
@@ -378,6 +380,7 @@ export default function (pi: ExtensionAPI) {
           ledgerPath: session.ledgerPath,
           advisor: {
             decider: session.advisorSession.deciderName,
+            taskEgress: session.advisorSession.settings.taskEgress,
             ...(session.advisorSession.settings.refusal ? { refusal: session.advisorSession.settings.refusal } : {}),
           },
           ...(session.workspacePin ? { workspacePin: session.workspacePin } : {}),

package/extensions/pruning-advice.ts

@@ -36,6 +36,9 @@ export async function advisePruning(input: {
   session: { advisorSession: { advisor: Advisor }; parentSession?: ParentTurnSource };
   granted: ContextRequest;
   task: string;
+  executionId?: string;
+  /** The current delegation call, excluded from advisor input because its arguments contain the raw task. */
+  toolCallId?: string;
   signal?: AbortSignal;
 }): Promise<string[] | undefined> {
   if (input.granted.mode !== "pruned" || !input.session.parentSession) return undefined;
@@ -44,7 +47,12 @@ export async function advisePruning(input: {
     ...(input.granted.turns !== undefined ? { turns: input.granted.turns } : {}),
     ...(input.granted.files !== undefined ? { files: input.granted.files } : {}),
   }).kept;
-  if (candidates.length < 2) return undefined;
+  const privateIds = new Set(
+    input.toolCallId ? all.filter((turn) => turn.toolCallIds.includes(input.toolCallId!)).map((turn) => turn.id) : [],
+  );
+  const privateCandidates = candidates.filter((turn) => privateIds.has(turn.id));
+  const candidatesForAdvice = candidates.filter((turn) => !privateCandidates.includes(turn));
+  if (candidatesForAdvice.length < 2) return undefined;
   // **Judge the MOST RECENT candidates, and keep the rest unjudged.** This was `> MAX_JUDGED_TURNS` → give up
   // entirely, which was fine while the rule offered six turns and became a silent feature death the moment
   // `DEFAULT_CONTEXT_TURNS` rose to 20: every default request would have exceeded the bound, so the pruning
@@ -54,16 +62,18 @@ export async function advisePruning(input: {
   // Judging a SUBSET is still only narrowing — an unjudged turn is kept, never dropped — so the attenuation
   // property is untouched. The recent end is judged because that is where the rule's own recall is
   // concentrated, and because a turn adjacent to the task is the one a wrong answer costs most.
-  const unjudged = candidates.slice(0, Math.max(0, candidates.length - MAX_JUDGED_TURNS));
-  const judged = candidates.slice(unjudged.length);
+  const unjudged = candidatesForAdvice.slice(0, Math.max(0, candidatesForAdvice.length - MAX_JUDGED_TURNS));
+  const judged = candidatesForAdvice.slice(unjudged.length);
 
+  const task = input.session.advisorSession.advisor.task(input.task);
+  const taskDescription = typeof task === "string" ? task.slice(0, 2000) : JSON.stringify(task);
   const questions: Record<string, Question> = {};
   for (const [index, turn] of judged.entries())
     questions[`turn${index}`] = {
       kind: "noul",
       // Both bounded: the task is embedded once per candidate, so an unbounded task became a request twelve times
       // its size, on a two-second budget and the operator's key.
-      instructions: `Would a sub-agent doing this task be helped by seeing this part of the parent's session?\n\nTASK: ${input.task.slice(0, 2000)}\n\nPART:\n${turn.text.slice(0, 2000)}`,
+      instructions: `Would a sub-agent doing this task be helped by seeing this part of the parent's session?\n\nTASK: ${taskDescription}\n\nPART:\n${turn.text.slice(0, 2000)}`,
       whenTrue: "It bears on the task: a decision, a constraint, a fact the task depends on.",
       whenFalse: "It does not: unrelated work, chatter, or something the task already states.",
     };
@@ -74,12 +84,14 @@ export async function advisePruning(input: {
     // task and one turn rather than the whole session. Nothing here is recorded — `createAdvisor` writes keys.
     { state: {}, questions },
     input.signal,
+    input.executionId,
   );
   if (!advice) return undefined;
   // Every candidate or none. A response missing eleven of twelve answers would otherwise read as "drop eleven",
   // which is a narrowing nobody asked for rather than the "unrecognised response means no advice" contract.
   if (judged.some((_, index) => advice.answers[`turn${index}`]?.kind !== "noul")) return undefined;
   const kept = [
+    ...privateCandidates.map((turn) => turn.id),
     ...unjudged.map((turn) => turn.id),
     ...judged.filter((_, index) => (advice.answers[`turn${index}`] as { value: boolean }).value).map((turn) => turn.id),
   ];
@@ -88,12 +100,31 @@ export async function advisePruning(input: {
   return kept.length === 0 ? undefined : kept;
 }
 
-function turnsOf(session: ParentTurnSource): Array<{ id: string; text: string }> {
+function turnsOf(session: ParentTurnSource): Array<{ id: string; text: string; toolCallIds: string[] }> {
   try {
     return session
       .getEntries()
       .filter((entry) => entry.type === "message")
-      .map((entry) => ({ id: entry.id, text: JSON.stringify((entry as { message?: unknown }).message ?? entry) }));
+      .map((entry) => {
+        const message = (entry as { message?: unknown }).message ?? entry;
+        const content =
+          typeof message === "object" && message !== null && Array.isArray((message as { content?: unknown }).content)
+            ? (message as { content: unknown[] }).content
+            : [];
+        return {
+          id: entry.id,
+          text: JSON.stringify(message),
+          toolCallIds: content
+            .filter(
+              (part): part is { type: "toolCall"; id: string } =>
+                typeof part === "object" &&
+                part !== null &&
+                (part as { type?: unknown }).type === "toolCall" &&
+                typeof (part as { id?: unknown }).id === "string",
+            )
+            .map((part) => part.id),
+        };
+      });
   } catch {
     return [];
   }

package/extensions/reload-environment.ts

@@ -5,6 +5,7 @@ export interface ReloadLifecycle {
   root: Record<string, string | undefined>;
   published?: Record<string, string | undefined>;
   activityRootId?: string;
+  episodeId?: string;
   /**
    * The destination pin this owner settled on (ADR-0042), which must survive an extension reload.
    *

package/extensions/run-delegation.ts

@@ -242,7 +242,7 @@ export async function runOneDelegation(
     approvalFacts?: ApprovalLedgerFacts;
   } = {},
 ): Promise<DelegationOutcome> {
-  const { onProgress, preApproved, taskFrom, taskFromExecutionId, approvalFacts } = options;
+  const { toolCallId, onProgress, preApproved, taskFrom, taskFromExecutionId, approvalFacts } = options;
   // pi resolves a BARE model id to an unauthenticated provider and the child dies at startup — the id
   // alone is not enough, it must be qualified with its provider (`Model<Api>` carries both).
   const defaultModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
@@ -303,6 +303,7 @@ export async function runOneDelegation(
       model: spec.model ?? defaultModel,
       registry: ctx.modelRegistry,
       task: spec.task,
+      executionId: ids.executionId,
       agent: spec.agent,
       signal,
     });
@@ -311,6 +312,8 @@ export async function runOneDelegation(
     session,
     base: extra,
     task: spec.task,
+    executionId: ids.executionId,
+    toolCallId,
     blocked: Boolean(executorRefusal || modelRefusal),
     preview: () => planWithApprovals(session, request, extra, null, signal, preApproved).then((r) => r.plan),
     ...(signal ? { signal } : {}),
@@ -332,6 +335,7 @@ export async function runOneDelegation(
           spec: { ...spec.workspace, access: governedWorkspaceAccess(spec.workspace.access, plan.requested) },
           correlation: spec.correlation,
           childId: ids.childId,
+          episodeId: session.episodeId,
           executionId: ids.executionId,
           parentExecutionId: ids.parentExecutionId,
           signal,
@@ -403,6 +407,7 @@ export async function runOneDelegation(
       await releaseDelegationWorkspace({
         prepared: preparedWorkspace,
         childId: ids.childId,
+        episodeId: session.episodeId,
         executionId: ids.executionId,
         parentExecutionId: ids.parentExecutionId,
         ledgerPath: session.ledgerPath,
@@ -451,6 +456,8 @@ export async function handoffPlanContext(input: {
   session: Parameters<typeof advisePruning>[0]["session"];
   base: Record<string, unknown>;
   task: string;
+  executionId?: string;
+  toolCallId?: string;
   /** A refusal is already certain, so nothing may be asked. */
   blocked: boolean;
   /** Plans with no human in the loop; its result decides whether an advisor is consulted at all. */
@@ -464,6 +471,8 @@ export async function handoffPlanContext(input: {
     session: input.session,
     granted: plan.handoff as Parameters<typeof advisePruning>[0]["granted"],
     task: input.task,
+    ...(input.executionId ? { executionId: input.executionId } : {}),
+    ...(input.toolCallId ? { toolCallId: input.toolCallId } : {}),
     ...(input.signal ? { signal: input.signal } : {}),
   });
   return ids ? { ...input.base, handoffTurnIds: ids } : { ...input.base };

package/extensions/session-environment.ts

@@ -1,6 +1,7 @@
 import { parseInherited } from "../src/kernel/approval.ts";
 import { DELEGATE_CAPABILITY } from "../src/kernel/delegate.ts";
 import { budgetFromEnv } from "../src/kernel/fanout.ts";
+import { isEpisodeId } from "../src/kernel/episode-id.ts";
 import { WILDCARD } from "../src/kernel/pi-tools.ts";
 import {
   depthConfig,
@@ -9,6 +10,7 @@ import {
   ENV_APPROVED,
   ENV_DEPTH,
   ENV_EXECUTION_ID,
+  ENV_EPISODE_ID,
   ENV_FANOUT,
   ENV_GATED,
   ENV_GRANT,
@@ -45,6 +47,13 @@ export function reconcileSessionEnvironment(
   session.executor = chooseExecutor(environment[ENV_HERDR], null);
   session.ownSpawnId = environment[ENV_PARENT_ID]?.trim() || `d${session.depth}`;
   session.ownExecutionId = environment[ENV_EXECUTION_ID]?.trim() || undefined;
+  const inheritedEpisodeId = environment[ENV_EPISODE_ID]?.trim();
+  session.episodeId = isEpisodeId(inheritedEpisodeId)
+    ? inheritedEpisodeId
+    : isEpisodeId(lifecycle.episodeId)
+      ? lifecycle.episodeId
+      : session.episodeId;
+  lifecycle.episodeId = session.episodeId;
   session.fanoutBudget = budgetFromEnv(environment[ENV_FANOUT]);
   session.mayDelegate =
     !session.governed || session.inherited.includes(DELEGATE_CAPABILITY) || session.inherited.includes(WILDCARD);

package/extensions/session.ts

@@ -14,6 +14,7 @@
  * copy of `ownGrant` before observation is exactly how a stale upper bound would become an enforced one.
  */
 import { randomUUID } from "node:crypto";
+import { isEpisodeId, newEpisodeId } from "../src/kernel/episode-id.ts";
 import { parseInherited, type InheritableApproval } from "../src/kernel/approval.ts";
 import type { ApprovalBinding } from "../src/kernel/correlation.ts";
 import { createApprovalGateProvider } from "../src/governance/approval-prompt.ts";
@@ -100,7 +101,7 @@ import {
   ENV_ACTIVITY_ROOT,
   ENV_ACTIVITY_TASK,
 } from "../src/products/activity-timeline.ts";
-import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE, ENV_ADVISOR } from "../src/kernel/env-names.ts";
+import { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE, ENV_ADVISOR, ENV_EPISODE_ID } from "../src/kernel/env-names.ts";
 export { ENV_HERDR_KEEP_PANE, ENV_GOVERNANCE } from "../src/kernel/env-names.ts";
 import { adoptLegacyEnvironment } from "../src/kernel/env-names.ts";
 
@@ -148,6 +149,8 @@ export interface GrantsSession extends NativeSessionHost {
   ownSpawnId: string;
   /** Unique identity when this session is itself a governed child; roots have no governed parent. */
   ownExecutionId?: string;
+  /** Stable identity shared by this root session and every descendant. */
+  episodeId: string;
   /** Descendants this subtree may still create — the cardinality bound ADR-0008 never had. */
   fanoutBudget: number;
   /** Whether delegation tools are active. Reconciled against the owner-bound root at session_start. */
@@ -407,6 +410,13 @@ export function createGrantsSession(
   const environment = lifecycle ? process.env : started!.environment;
   const activityRootId = activeLifecycle.activityRootId ?? randomUUID();
   activeLifecycle.activityRootId = activityRootId;
+  const inheritedEpisodeId = environment[ENV_EPISODE_ID];
+  const episodeId = isEpisodeId(inheritedEpisodeId)
+    ? inheritedEpisodeId
+    : activeLifecycle.episodeId && isEpisodeId(activeLifecycle.episodeId)
+      ? activeLifecycle.episodeId
+      : newEpisodeId();
+  activeLifecycle.episodeId = episodeId;
   // Local governance is on unless PI_DADDY_GOVERNANCE opts out; explicit inherited grants still win.
   // The factory precedes ctx, so its cwd/store identity is reconciled at session_start.
   const grantRaw = environment[ENV_GRANT];
@@ -435,7 +445,8 @@ export function createGrantsSession(
   // Read from `storeCwd` for `loadStoredGrantStateSync`'s reason: this factory runs before any hook, so `ctx.cwd`
   // does not exist yet. Reading a workspace-writable file here is safe precisely because it can only narrow.
   const advisorSession = createAdvisorSession({
-    block: projectAdvisorBlock(storeCwd),
+    block: projectAdvisorBlock(storeCwd, environment),
+    episodeId,
     ...(storedLedger ? { ledgerPath: storedLedger } : {}),
   });
   const session: GrantsSession = {
@@ -469,6 +480,7 @@ export function createGrantsSession(
     // every level restarting at `d0` and the ledger becoming unjoinable.
     ownSpawnId: environment[ENV_PARENT_ID]?.trim() || `d${depth}`,
     ownExecutionId: environment[ENV_EXECUTION_ID]?.trim() || undefined,
+    episodeId,
     // The cardinality bound ADR-0008 never had: it attenuates downward like depth, so a subtree can never
     // create more descendants than its root was given — with no shared state, no lock and no counter file.
     fanoutBudget: budgetFromEnv(environment[ENV_FANOUT]),
@@ -501,6 +513,7 @@ export function createGrantsSession(
     catalogReady: Promise.resolve(emptyCatalog),
     delegationContext: async (approved?: InheritableApproval[]) => ({
       ownGrant: session.ownGrant,
+      episodeId: session.episodeId,
       depth: session.depth,
       maxDepth: session.maxDepth,
       gated: session.gated,
@@ -559,6 +572,7 @@ export function createGrantsSession(
     publishChildEnv: () => {
       const env = childEnv({
         ownGrant: session.ownGrant,
+        episodeId: session.episodeId,
         depth: session.depth,
         maxDepth: session.maxDepth,
         gated: session.gated,
@@ -586,10 +600,19 @@ export function createGrantsSession(
  * Unreadable, absent or malformed all yield undefined: this file is the reviewable record, not authority, and the
  * only thing it can do to an advisor is turn one off. A parse failure therefore costs nothing worth reporting.
  */
-function projectAdvisorBlock(cwd: string): unknown {
+export function reconcileAdvisorSession(session: GrantsSession, environment: NodeJS.ProcessEnv): void {
+  session.advisorSession = createAdvisorSession({
+    block: projectAdvisorBlock(session.storeCwd, environment),
+    episodeId: session.episodeId,
+    ...(session.ledgerPath ? { ledgerPath: session.ledgerPath } : {}),
+    env: environment,
+  });
+}
+
+function projectAdvisorBlock(cwd: string, env: NodeJS.ProcessEnv = process.env): unknown {
   // Only when an advisor could exist at all. This runs in every session including every child, before any hook, and
   // a child can never use the result because `PI_DADDY_ADVISOR` is stripped from it.
-  if (!process.env[ENV_ADVISOR]?.trim()) return undefined;
+  if (!env[ENV_ADVISOR]?.trim()) return undefined;
   try {
     const path = projectSettingsPath(cwd);
     // Bounded and type-checked first: this is the third unbounded session-start read AGENTS.md warns about, and the

package/extensions/workspace-runtime.ts

@@ -69,6 +69,7 @@ export async function prepareDelegationWorkspace(input: {
   spec: DelegationWorkspaceSpec;
   correlation?: CorrelationMetadata;
   childId: string;
+  episodeId?: string;
   executionId: string;
   parentExecutionId: string | null;
   signal?: AbortSignal;
@@ -120,6 +121,7 @@ export async function prepareDelegationWorkspace(input: {
       await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          ...(input.episodeId ? { episodeId: input.episodeId } : {}),
           executionId: input.executionId,
           parentExecutionId: input.parentExecutionId,
           childId: input.childId,
@@ -146,6 +148,7 @@ export async function prepareDelegationWorkspace(input: {
       await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          ...(input.episodeId ? { episodeId: input.episodeId } : {}),
           executionId: input.executionId,
           parentExecutionId: input.parentExecutionId,
           childId: input.childId,
@@ -174,6 +177,7 @@ export async function prepareDelegationWorkspace(input: {
 export async function releaseDelegationWorkspace(input: {
   prepared: PreparedWorkspace | undefined;
   childId: string;
+  episodeId?: string;
   executionId: string;
   parentExecutionId: string | null;
   ledgerPath?: string;
@@ -195,6 +199,7 @@ export async function releaseDelegationWorkspace(input: {
     await appendLedgerEvent(
       { path: input.ledgerPath, strict: true },
       buildWorkspaceLeaseEvent({
+        ...(input.episodeId ? { episodeId: input.episodeId } : {}),
         executionId: input.executionId,
         parentExecutionId: input.parentExecutionId,
         childId: input.childId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.40.1",
+  "version": "0.41.1",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",