pi-daddy 0.27.3 → 0.28.0

package/extensions/activity-timeline.ts

@@ -0,0 +1,90 @@
+/** Pi hook wiring for local activity observation. It neither decides grants nor adds child authority. */
+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 { Type } from "typebox";
+import { ActivityTimelineRecorder, ENV_ACTIVITY_TASK, type ActivityIdentity, type ActivitySkill } from "../src/activity-timeline.ts";
+
+export interface ActivitySessionState { activityRootId?: string; activity?: ActivityIdentity & { taskId?: string } }
+interface HookContext { cwd: string; model?: { id?: string }; thinkingLevel?: string; ui: { notify(message: string, level?: "info" | "warning" | "error"): void } }
+const digest = (text: string) => createHash("sha256").update(text).digest("hex");
+
+/**
+ * Register observation hooks. `lifecycleTool` is false in a leaf observer injected with `-e`: that
+ * extension has no tools at all, so a child without tool:delegate receives no widened surface.
+ */
+export function registerActivityTimeline(pi: ExtensionAPI, session?: ActivitySessionState, lifecycleTool = true): void {
+  let recorder: ActivityTimelineRecorder | undefined, pendingFinal: string | undefined, finalizedUser: string | undefined;
+  let paths = new Map<string, string>(), available = new Map<string, ActivitySkill>();
+  let reported = false;
+  const report = (ctx: HookContext | undefined, error: unknown) => { if (!reported && ctx) { reported = true; ctx.ui.notify(`pi-daddy activity: observation unavailable (${error instanceof Error ? error.message : String(error)}); governance is unchanged.`, "warning"); } };
+  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;
+    // 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)) recorder = new ActivityTimelineRecorder(ctx.cwd, env);
+    return recorder;
+  };
+  const skills = async (event: unknown, target: ActivityTimelineRecorder) => {
+    available = new Map();
+    const entries = ((event as { systemPromptOptions?: { skills?: Array<{ name?: string; filePath?: string }> } }).systemPromptOptions?.skills ?? []);
+    for (const item of entries) {
+      if (!item.name || !item.filePath) continue;
+      const source = await readFile(item.filePath, "utf8");
+      if (Buffer.byteLength(source) > 256 * 1024) continue;
+      const fact = { name: item.name, source: item.filePath, digest: digest(source) };
+      available.set(resolve(item.filePath), fact); await target.skill("skill_available", fact);
+    }
+  };
+  if (lifecycleTool) pi.registerTool({
+    name: "activity_lifecycle", label: "Activity lifecycle",
+    description: "Declare a runtime skill active, finished, or superseded for the local activity timeline. This is not compliance evidence.",
+    parameters: Type.Object({ state: Type.Union([Type.Literal("active"), Type.Literal("finished"), Type.Literal("superseded")]), name: Type.String({ minLength: 1, maxLength: 128 }), source: Type.String({ minLength: 1, maxLength: 1024 }), digest: Type.String({ pattern: "^[a-f0-9]{64}$" }) }),
+    async execute(_id, params) { const kind = params.state === "active" ? "skill_active" : params.state === "finished" ? "skill_finished" : "skill_superseded"; await recorder?.skill(kind, { name: params.name, source: params.source, digest: params.digest }); return { content: [{ type: "text", text: `Activity recorded: ${params.name} ${params.state}.` }], details: {} }; },
+  });
+  pi.on("session_start", (_event, ctx: HookContext) => {
+    try {
+      recorder = current(ctx);
+      // A leaf observer attaches to the parent-owned child event; a root gets a stable session identity.
+      if (process.env[ENV_ACTIVITY_TASK]) recorder.attach(process.env[ENV_ACTIVITY_TASK]!);
+      const identity: ActivityIdentity = { rootId: recorder.rootId, path: recorder.path, ...(recorder.task ? { taskId: recorder.task } : {}) };
+      if (session) session.activity = identity;
+      ctx.ui.notify(recorder.enabled ? `pi-daddy activity: local observation on (${recorder.contentEnabled ? "private prompt/final content" : "metadata only"}); governance is unchanged.` : "pi-daddy activity: observation off; governance is unchanged.", "info");
+    } catch (error) { report(ctx, error); }
+    return undefined;
+  });
+  pi.on("before_agent_start", async (event, ctx: HookContext) => {
+    try {
+      const target = current(ctx);
+      // An injected leaf observer must not fabricate a second child task; its parent-owned execution seam
+      // already wrote task_started. Root turns always get a fresh task id under their stable root identity.
+      if (!process.env[ENV_ACTIVITY_TASK]) {
+        const taskId = await target.start(finalizedUser ?? (event as { prompt?: string }).prompt ?? "", ctx.model?.id, ctx.thinkingLevel);
+        finalizedUser = undefined;
+        if (session?.activity) session.activity = { rootId: target.rootId, path: target.path, ...(taskId ? { taskId } : {}) };
+      }
+      await skills(event, target);
+    } catch (error) { report(ctx, error); }
+    return undefined;
+  });
+  pi.on("message_end", (event) => {
+    const message = (event as { message?: { role?: string; content?: string | Array<{ type?: string; text?: string }> } }).message;
+    const text = typeof message?.content === "string" ? message.content : Array.isArray(message?.content) ? message!.content.filter(part => part.type === "text").map(part => part.text ?? "").join("") : "";
+    if (message?.role === "user") finalizedUser = text;
+    if (message?.role === "assistant") pendingFinal = text;
+    return undefined;
+  });
+  pi.on("tool_execution_start", (event) => { const value = event as { toolCallId?: string; args?: { path?: unknown } }; if (value.toolCallId && typeof value.args?.path === "string") paths.set(value.toolCallId, value.args.path); return undefined; });
+  pi.on("tool_execution_end", async (event) => {
+    try { const value = event as { isError?: boolean; toolName?: string; toolCallId?: string }; const path = value.toolCallId ? paths.get(value.toolCallId) : undefined; if (value.toolCallId) paths.delete(value.toolCallId); const skill = path ? available.get(resolve(path)) : undefined; if (!value.isError && value.toolName === "read" && skill) await recorder?.skill("skill_read", skill); } catch { /* observation cannot affect tool execution */ }
+    return undefined;
+  });
+  pi.on("agent_settled", async (event, ctx: HookContext) => {
+    try { if (recorder && !process.env[ENV_ACTIVITY_TASK]) await recorder.finish(pendingFinal, (event as { cancelled?: boolean; error?: unknown }).cancelled ? "cancelled" : (event as { error?: unknown }).error ? "failed" : "completed"); pendingFinal = undefined; } catch (error) { report(ctx, error); }
+    return undefined;
+  });
+}
+
+/** A no-tool observer used for governed leaves that intentionally do not load grants.ts. */
+export default function activityObserver(pi: ExtensionAPI): void { registerActivityTimeline(pi, undefined, false); }

package/extensions/execute-child.ts

@@ -12,7 +12,7 @@ import { GovernanceRefusal, refusal, type StructuredRefusal } from "../src/refus
 import { ENV_HERDR_KEEP_PANE, type GrantsSession } from "./session.ts";
 import { releaseDelegationWorkspace, type PreparedWorkspace } from "./workspace-runtime.ts";
 import { beginDeclaredWorkAttempt } from "./work-runtime.ts";
-
+import { ActivityTimelineRecorder, ENV_ACTIVITY_PARENT_TASK } from "../src/activity-timeline.ts";
 export interface DelegationOutcome {
   ok: boolean;
   text: string;
@@ -30,7 +30,6 @@ export interface DelegationOutcome {
   /** A loud best-effort post-execution observation failure; execution ownership is still settled. */
   control?: "failed";
 }
-
 /**
  * The upstream controller's token, honoured ONLY when the child otherwise exited cleanly non-zero.
  *
@@ -65,7 +64,6 @@ export function isHerdrWriterCloseFailure(error: unknown): boolean {
   return error instanceof HerdrWriterCloseError ||
     hasFinalizerError(error, (value) => value instanceof HerdrWriterCloseError);
 }
-
 export interface ChildProgressUpdate {
   chunk?: string;
   snapshot?: string[];
@@ -73,7 +71,6 @@ export interface ChildProgressUpdate {
   agentName?: string;
   state?: "starting" | "running" | "completed" | "failed";
 }
-
 /**
  * Execute one already-approved plan, record lifecycle, and release any workspace lease on every path
  * EXCEPT a failed herdr writer-tab close, which deliberately retains the lease because the pane may
@@ -102,6 +99,9 @@ async function executeChildBody(input: {
 }): Promise<DelegationOutcome> {
   const { session, plan, childId, executionId, parentExecutionId, preparedWorkspace, signal, onProgress } = input;
   const ledgerPath = session.ledgerPath;
+  let activityParent: string | undefined, activity = new ActivityTimelineRecorder(input.cwd), activityStarted = false, activityFinished = false;
+  try { const env = { ...process.env }; for (const name of ["PI_DADDY_ACTIVITY_PATH", "PI_DADDY_ACTIVITY_ROOT", "PI_DADDY_ACTIVITY_TASK", ENV_ACTIVITY_PARENT_TASK]) { const value = plan.env[name]; if (value) env[name] = value; } activity = new ActivityTimelineRecorder(input.cwd, env); activityParent = plan.env[ENV_ACTIVITY_PARENT_TASK]; } catch {}
+  try { await activity.childStarted(executionId, activityParent, input.agent ?? "governed child", (plan.args.at(-1) ?? "").trimStart()); activityStarted = true; } catch {}
   const configuredTimeoutMs = timeoutFromEnv(process.env[ENV_CHILD_TIMEOUT]);
   const startedAt = new Date();
   const deadlineAt = new Date(startedAt.getTime() + configuredTimeoutMs).toISOString();
@@ -237,6 +237,7 @@ async function executeChildBody(input: {
     retention.finish({ code: output.code, signal: output.signal ?? null, timedOut: output.timedOut,
       aborted: output.aborted, truncated: output.truncated, failed: childFailed });
     releaseReason = output.timedOut ? "timeout" : output.aborted ? "cancelled" : childFailed ? "failed" : "completed";
+    if (activityStarted) try { await activity.childFinished(executionId, activityParent, input.agent ?? "governed child", output.text, childFailed ? output.aborted ? "cancelled" : "failed" : "completed"); activityFinished = true; } catch { /* observation does not control execution */ }
     if (workAttempt) try { workTerminalAttempted = true; await workAttempt.finish(childFailed ? "failed" : "completed"); }
     catch (error) { teardownFailures.push(`declared work terminal record failed: ${String(error)}`); }
     if (ledgerPath) {
@@ -321,6 +322,7 @@ async function executeChildBody(input: {
     await teardown();
     return withTeardownNotes(succeeded);
   } catch (error) {
+    if (activityStarted && !activityFinished) try { await activity.childFinished(executionId, activityParent, input.agent ?? "governed child", "", signal?.aborted ? "cancelled" : "failed"); } catch { /* observation does not control execution */ }
     retention.finish({ code: null, signal: null, timedOut: false, aborted: Boolean(signal?.aborted), truncated: false, failed: true });
     if (workAttempt && !workTerminalAttempted) try { workTerminalAttempted = true; await workAttempt.finish("failed"); }
     catch (cause) { teardownFailures.push(`declared work terminal record failed: ${String(cause)}`); }
@@ -350,7 +352,6 @@ async function executeChildBody(input: {
     // collected into an array nothing read.
     throw errorWithTeardownNotes(error, teardownFailures);
   }
-
   /**
    * Surfaces a teardown failure WITHOUT discarding the result. The child already ran; telling the
    * orchestrator "ledger write failed" and nothing else made a completed delegation indistinguishable
@@ -374,7 +375,6 @@ function errorWithTeardownNotes(error: unknown, notes: readonly string[]): unkno
   if (error instanceof Error) return new Error([error.message, ...notes].join("; "), { cause: error });
   return error;
 }
-
   function withTeardownNotes(outcome: DelegationOutcome): DelegationOutcome {
     const observed = { ...outcome, retention: retention.status() };
     if (teardownFailures.length === 0) return observed;

package/extensions/grants-command.ts

@@ -63,7 +63,7 @@ export interface GrantsCommandContext {
    */
   runInit: () => Promise<void>;
   /** Open or reuse the read-only Herdr dashboard; injected so this diagnostic never becomes enforcement. */
-  openDashboard: () => Promise<{ kind: "opened" | "reused"; paneId: string; visibleBesideCaller: boolean }>;
+  openDashboard: () => Promise<{ kind: "opened" | "reused"; paneId: string; visibleBesideCaller: boolean } | { kind: "fallback"; frame: string; visibleBesideCaller: false }>;
   /** Explicit same-process production host lifecycle; owns no model call and never cancels a child on stop. */
   runHost: (target: string) => Promise<string>;
   variantRuns: Map<string, VariantRunAccounting>;

package/extensions/grants-connected-command.ts

@@ -1,6 +1,6 @@
 export interface GrantsConnectedCommandContext {
  runHost:(target:string)=>Promise<string>;
- openDashboard:()=>Promise<{kind:"opened"|"reused";paneId:string;visibleBesideCaller:boolean}>;
+ openDashboard:()=>Promise<{kind:"opened"|"reused";paneId:string;visibleBesideCaller:boolean}|{kind:"fallback";frame:string;visibleBesideCaller:false}>;
  ui:{notify(message:string,level:"info"|"error"):void};
 }
 /** Host lifecycle and pane placement live together; neither belongs in the capability-report renderer. */
@@ -11,7 +11,7 @@ export async function handleConnectedCommand(sub:string|undefined,target:string|
   return true;
  }
  if(sub==="dashboard"){
-  try{const opened=await ctx.openDashboard();ctx.ui.notify(`grants: dashboard ${opened.kind} in Herdr pane ${opened.paneId} without changing focus`+(opened.visibleBesideCaller?".":" (the existing pane is in another tab)."),"info");}
+  try{const opened=await ctx.openDashboard();ctx.ui.notify(opened.kind==="fallback"?opened.frame:`grants: dashboard ${opened.kind} in Herdr pane ${opened.paneId} without changing focus`+(opened.visibleBesideCaller?".":" (the existing pane is in another tab)."),"info");}
   catch(error){ctx.ui.notify(`grants: dashboard unavailable — ${error instanceof Error?error.message:String(error)}`,"error");}
   return true;
  }

package/extensions/grants.ts

@@ -20,7 +20,6 @@
  * spawn triggered the human prompt, and `childEnv` clamps it to the grant again on the way out. Each
  * child derives its own grant from the tool array of its first provider request.
  */
-
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -51,9 +50,10 @@ import { createDailyDashboardSession } from "./daily-dashboard-session.ts";
 import { createWorkSession } from "./work-session.ts";
 import { createLearningSession } from "./learning-session.ts";
 import { replacePublishedDailyWork, type PublishedDailyWork } from "./daily-work-session.ts";
+import { defaultActivityTimelinePath } from "../src/activity-timeline.ts";
+import { registerActivityTimeline } from "./activity-timeline.ts";
 export default function (pi: ExtensionAPI) {
   // The path pi loads as the extension, so a child granted `tool:delegate` can be started with `-e <this>`.
-  // Only this file can say so about itself, which is why the session takes it rather than deriving it.
   const extensionPath = (() => {
     try {
       return fileURLToPath(import.meta.url);
@@ -61,8 +61,10 @@ export default function (pi: ExtensionAPI) {
       return undefined;
     }
   })();
-  const session = createGrantsSession(extensionPath);
+  const observerExtensionPath = fileURLToPath(new URL("./activity-timeline.ts", import.meta.url));
+  const session = createGrantsSession(extensionPath, undefined, observerExtensionPath);
   associateOrdinaryHost(pi,session);
+  registerActivityTimeline(pi, session);
   const dailyHost=createDailyDashboardSession({ordinary:()=>ordinaryChildrenFor(pi),declared:()=>session.declaredWork,rebind:state=>{session.declaredWork=state;},cwd:()=>session.cwd,env:process.env,author:"local-operator"});
   const dashboardPluginRoot = fileURLToPath(new URL("../herdr-plugin/", import.meta.url));
   const dashboardPaths = defaultDashboardPaths(
@@ -74,7 +76,6 @@ export default function (pi: ExtensionAPI) {
   const publishedDailyWork: PublishedDailyWork = {};
   const workSession=createWorkSession(session,dailyHost,()=>replacePublishedDailyWork(process.env,publishedDailyWork,session.declaredWork));
   const learningSession=createLearningSession(dailyHost);
-
   pi.on("session_start", async (_event, ctx) => {
     // Real SDK contexts always supply SessionManager. The fallback keeps lightweight wiring fixtures
     // isolated; it cannot carry state into another extension instance.
@@ -207,7 +208,7 @@ export default function (pi: ExtensionAPI) {
           env: process.env,
           pid: process.pid,
           cwd: ctx.cwd,
-          ledgerPath: session.ledgerPath,
+          ledgerPath: session.ledgerPath ?? defaultActivityTimelinePath(ctx.cwd),
           pluginRoot: dashboardPluginRoot,
           preferencePath: dashboardPaths.preferencePath,
           paneStatePath: dashboardPaths.paneStatePath,
@@ -385,7 +386,7 @@ export default function (pi: ExtensionAPI) {
             env: process.env,
             pid: process.pid,
             cwd: ctx.cwd,
-            ledgerPath: session.ledgerPath,
+            ledgerPath: session.ledgerPath ?? defaultActivityTimelinePath(ctx.cwd),
             pluginRoot: dashboardPluginRoot,
             paneStatePath: dashboardPaths.paneStatePath,
           }),

package/extensions/reload-environment.ts

@@ -1,7 +1,7 @@
 import { GRANT_ENV_KEYS } from "../src/propagation.ts";
 
 /** The root baseline and latest child publication for one real Pi session owner. */
-export interface ReloadLifecycle { root: Record<string, string | undefined>; published?: Record<string, string | undefined> }
+export interface ReloadLifecycle { root: Record<string, string | undefined>; published?: Record<string, string | undefined>; activityRootId?: string }
 type SessionOwner = object;
 
 interface ReloadState {

package/extensions/session-environment.ts

@@ -10,7 +10,7 @@ import { storedGrantSessionState } from "./stored-grant-session.ts";
 import { chooseExecutor, ENV_HERDR } from "../src/executor.ts";
 import { ENV_ALLOW_UNRESOLVED_MODELS } from "../src/model-preflight.ts";
 import type { ReloadLifecycle } from "./reload-environment.ts";
-import type { GrantsSession } from "./session.ts";
+import { ENV_GOVERNANCE, type GrantsSession } from "./session.ts";
 
 /** Rebuild every authority-bearing factory input once session_start identifies its real SDK owner. */
 export function reconcileSessionEnvironment(
@@ -21,8 +21,9 @@ export function reconcileSessionEnvironment(
   const bounds = depthConfig(environment[ENV_DEPTH], environment[ENV_MAX_DEPTH]);
   const ledgerRaw = environment[ENV_LEDGER];
   session.ledgerFromEnvironment = ledgerRaw !== undefined;
-  session.governed = stored.governed;
-  session.inherited = stored.inherited;
+  const governanceOff = environment[ENV_GOVERNANCE]?.trim() === "off" || environment[ENV_GOVERNANCE]?.trim() === "0";
+  session.governed = !governanceOff;
+  session.inherited = governanceOff ? stored.inherited : stored.governed ? stored.inherited : [WILDCARD];
   session.depth = bounds.depth;
   session.maxDepth = bounds.maxDepth;
   session.malformedBounds = bounds.malformed;
@@ -35,6 +36,8 @@ export function reconcileSessionEnvironment(
   session.mayDelegate = !session.governed || session.inherited.includes(DELEGATE_CAPABILITY) || session.inherited.includes(WILDCARD);
   session.allowUnresolvedModels = environment[ENV_ALLOW_UNRESOLVED_MODELS] === "1";
   session.reloadLifecycle = lifecycle;
+  session.activityRootId = lifecycle.activityRootId ?? session.activityRootId;
+  lifecycle.activityRootId = session.activityRootId;
   session.inheritedApprovals = parseInherited(environment[ENV_APPROVED]);
   session.ownGrant = deriveOwnGrant(session.inherited, null);
   session.observed = false;

package/extensions/session-report.ts

@@ -183,6 +183,7 @@ export async function reportSessionStart(session: GrantsSession, ctx: SessionRep
     ctx.ui.notify(`grants: executor — ${session.executor.disclosure}`, "error");
   }
 
+  if (!session.governed) info.push("grants: governance off by PI_DADDY_GOVERNANCE; observation and the local timeline remain independent.");
   if (session.governed) {
     info.push(
       `grants: depth ${session.depth}/${session.maxDepth}, holding [${session.ownGrant.join(", ") || "nothing"}]`,

package/extensions/session.ts

@@ -13,7 +13,7 @@
  * module reads them **through this object**, live, rather than capturing a copy at load time; capturing a
  * copy of `ownGrant` before observation is exactly how a stale upper bound would become an enforced one.
  */
-
+import { randomUUID } from "node:crypto";
 import { parseInherited, type InheritableApproval } from "../src/approval.ts";
 import type { ApprovalBinding } from "../src/correlation.ts";
 import { createApprovalGateProvider } from "../src/approval-prompt.ts";
@@ -81,19 +81,10 @@ export { ENV_HERDR } from "../src/executor.ts";
 export { ENV_HERDR_WORKSPACE } from "../src/herdr-cli.ts";
 /** Keep each child's pane after it finishes, for inspection. Off by default: fan-out would flood it. */
 export const ENV_HERDR_KEEP_PANE = "PI_GRANTS_HERDR_KEEP_PANE";
-
+export const ENV_GOVERNANCE = "PI_DADDY_GOVERNANCE";
 export interface VariantRunAccounting {runId:string;primaryExecutionId:string;shadowExecutionIds:string[];state:"running"|"settled";outcomes:null|{executionId:string;role:"primary"|"shadow";ok:boolean;reason:string|null}[]}
 export interface GrantsSession extends NativeSessionHost {
-  /**
-   * False when neither `PI_GRANTS_GRANT` nor a stored grant applies: the session holds the wildcard and
-   * nothing is governed.
-   *
-   * **Mutable, because `/grants init` makes an ungoverned session governed mid-run.** The first version of
-   * ADR-0030 left this readonly on the reasoning that a store is read at creation and `init` only runs where
-   * one exists — which is false for the first `init` in a directory, the most common case there is. The
-   * session then bounded every spawn by the new grant while `/grants` reported "inactive", so the status
-   * line contradicted the enforcer. Found by running it.
-   */
+  /** False only for the explicit PI_DADDY_GOVERNANCE opt-out; otherwise roots are observed-bound. */
   governed: boolean;
   /** The upper bound handed down by the delegator, before this session's own tools are observed. */
   inherited: Capability[];
@@ -133,6 +124,11 @@ export interface GrantsSession extends NativeSessionHost {
   readonly modelResolutionCache: Map<string, boolean>;
   /** Path to this extension, so a child granted `tool:delegate` can delegate in turn. */
   readonly extensionPath?: string;
+  /** Hook-only observer path for leaf children; it exposes no tools. */
+  readonly observerExtensionPath?: string;
+  /** Stable root identity plus current turn, used only to join local activity facts. */
+  activityRootId: string;
+  activity?: { rootId: string; path: string; taskId?: string };
   declaredWork?: DeclaredWorkState; // Explicit operator selection; absence leaves execution visibly unbound.
   /** Primary-return fan-outs retained by this original session; bounded and human-readable via /grants variants. */
   readonly variantRuns: Map<string, VariantRunAccounting>;
@@ -171,7 +167,6 @@ export interface GrantsSession extends NativeSessionHost {
    * but non-deterministically: the same delegation succeeded or failed on timing alone.
    */
   catalogReady: Promise<Catalog>;
-
   /**
    * The one place a delegation context is built — and therefore the one place each field is spelled.
    *
@@ -185,7 +180,6 @@ export interface GrantsSession extends NativeSessionHost {
    * diagnostic that disagrees with enforcement is not expressible.
    */
   delegationContext(approved?: InheritableApproval[]): Promise<DelegationContext>;
-
   /**
    * Publish what children inherit. Written once at session start, and republished whenever this
    * session's own approvals change (see `obtainApprovals`) — never once per spawn. That distinction is
@@ -215,7 +209,6 @@ export interface GrantsSession extends NativeSessionHost {
   adoptGrant(grant: Capability[], projectLedger?: string): void;
   reconcileEnvironment(environment: NodeJS.ProcessEnv, lifecycle: ReloadLifecycle): void;
 }
-
 /**
  * Parse the environment once and build the session every other module reads through.
  *
@@ -244,30 +237,23 @@ export async function loadProjectDefinitions(session: GrantsSession, cwd: string
   });
   session.catalog = await session.catalogReady;
 }
-
-export function createGrantsSession(extensionPath: string | undefined, lifecycle?: ReloadLifecycle): GrantsSession {
+export function createGrantsSession(extensionPath: string | undefined, lifecycle?: ReloadLifecycle, observerExtensionPath?: string): GrantsSession {
   const started = lifecycle ? undefined : beginExtensionLifecycle();
   const activeLifecycle = lifecycle ?? started!.lifecycle;
   const environment = lifecycle ? process.env : started!.environment;
-  // Governance is opt-in: with PI_GRANTS_GRANT unset AND no stored grant for this directory, the session
-  // holds the wildcard and nothing is blocked. This extension must never silently tighten a normal
-  // workflow.
-  //
-  // **Two sources, and the environment always wins** (ADR-0030). The variable is how a CHILD is governed
-  // and how CI is configured, so a store that could override it would let a directory quietly widen or
-  // narrow a child its parent had already bounded. The store is consulted only when the variable is absent,
-  // which is exactly the case it was added for: a human at a terminal who ran `/grants init` here.
-  //
-  // `process.cwd()` rather than `ctx.cwd`, because this runs in the extension factory — before any hook,
-  // and therefore before `ctx` exists. That ordering is forced by S-5: whether `delegate` is registered at
-  // all is decided here, and a grant arriving later could not inform it. `session_start` re-checks the two
-  // against each other and says so if they differ, which is the only case this can get wrong.
+  const activityRootId = activeLifecycle.activityRootId ?? randomUUID();
+  activeLifecycle.activityRootId = activityRootId;
+  // 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];
   const storeCwd = process.cwd();
   // One root-only store read supplies both decisions made by `/grants init`. A child always has ENV_GRANT,
   // so it cannot activate a ledger merely because its routed cwd happens to have a v2 store (ADR-0037).
   const storedState = storedGrantSessionState(grantRaw, storeCwd);
-  const { governed, inherited, refusal: grantStoreRefusal } = storedState;
+  const governanceOff = environment[ENV_GOVERNANCE]?.trim() === "off" || environment[ENV_GOVERNANCE]?.trim() === "0";
+  const governed = governanceOff ? false : true;
+  const inherited = governanceOff ? storedState.inherited : storedState.governed ? storedState.inherited : [WILDCARD];
+  const grantStoreRefusal = storedState.refusal;
   const ledgerRaw = environment[ENV_LEDGER];
   // Capture provenance before publishChildEnv writes this session's derived default into process.env. A later
   // `/grants init` for ctx.cwd must not mistake our own publication for an operator override.
@@ -278,7 +264,6 @@ export function createGrantsSession(extensionPath: string | undefined, lifecycle
   const bounds = depthConfig(environment[ENV_DEPTH], environment[ENV_MAX_DEPTH]);
   const { depth, maxDepth } = bounds;
   const emptyCatalog = makeCatalog([]);
-
   const session: GrantsSession = {
     governed,
     inherited,
@@ -319,6 +304,8 @@ export function createGrantsSession(extensionPath: string | undefined, lifecycle
     nativeSessionRoot: nativeSessionRootFromEnv(process.env),
     modelResolutionCache: new Map<string, boolean>(),
     extensionPath,
+    observerExtensionPath,
+    activityRootId,
     variantRuns: new Map(),
     reloadLifecycle: activeLifecycle,
     sessionApprovals: new Set<string>(),
@@ -339,6 +326,8 @@ export function createGrantsSession(extensionPath: string | undefined, lifecycle
       gated: session.gated,
       ledgerPath: session.ledgerPath,
       extensionPath: session.extensionPath,
+      observerExtensionPath: session.observerExtensionPath,
+      activity: session.activity,
       catalog: await session.catalogReady,
       // R-32: where each granted skill lives, so `planSpawn` can pass `--skill` for those and only those.
       // Derived from the catalog's own `source`, so it cannot drift from what was discovered.
@@ -355,10 +344,8 @@ export function createGrantsSession(extensionPath: string | undefined, lifecycle
       interactive: session.executor.kind === "herdr",
       ...(approved ? { approved } : {}),
     }),
-
     storeCwd,
     ...(grantStoreRefusal ? { grantStoreRefusal } : {}),
-
     adoptGrant: (grant: Capability[], projectLedger?: string) => {
       // Governed too, not just bounded. A session that starts with no grant and then runs `/grants init` is
       // governed from that moment: every spawn is bounded by what was just stored. Leaving this false made
@@ -373,7 +360,6 @@ export function createGrantsSession(extensionPath: string | undefined, lifecycle
       }
       session.publishChildEnv();
     },
-
     reconcileEnvironment: (environment, lifecycle) => reconcileSessionEnvironment(session, environment, lifecycle),
     publishChildEnv: () => {
       const env = childEnv({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.27.3",
+  "version": "0.28.0",
   "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",
@@ -258,7 +258,7 @@
     "test": "node scripts/unit-tests.ts",
     "test:dashboard-pty": "if [ \"$(uname -s)\" = Linux ]; then python3 test/dashboard-cli-pty.py; else echo 'dashboard PTY probe requires Unix pty/Unix sockets'; fi",
     "test:integration": "node --test test-integration/*.it.ts",
-    "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts",
+    "test:integration:ci": "node --test test-integration/approval.it.ts test-integration/governance.it.ts test-integration/activity.it.ts",
     "contracts:generate": "node scripts/generate-ledger-v3-contract.ts",
     "contracts:generate:v4": "node scripts/generate-ledger-v4-contract.ts contracts/ledger/v4",
     "prepack": "npm run build",

package/src/activity-timeline.ts

@@ -0,0 +1,133 @@
+/** Durable, local-only activity facts. Timeline events never infer skill compliance or provider reasoning. */
+import { createHash, randomUUID } from "node:crypto";
+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";
+
+export const ACTIVITY_TIMELINE_VERSION = 1 as const;
+export const ENV_ACTIVITY_TIMELINE = "PI_DADDY_ACTIVITY_TIMELINE";
+export const ENV_ACTIVITY_CONTENT = "PI_DADDY_ACTIVITY_CONTENT";
+/** Per-child transport; these are observation identities, not capability authority. */
+export const ENV_ACTIVITY_PATH = "PI_DADDY_ACTIVITY_PATH";
+export const ENV_ACTIVITY_ROOT = "PI_DADDY_ACTIVITY_ROOT";
+export const ENV_ACTIVITY_TASK = "PI_DADDY_ACTIVITY_TASK";
+export const ENV_ACTIVITY_PARENT_TASK = "PI_DADDY_ACTIVITY_PARENT_TASK";
+const MAX_EVENT_BYTES = 16 * 1024, MAX_CONTENT_BYTES = 256 * 1024;
+const DIGEST = /^[a-f0-9]{64}$/, REF = /^content\/[a-f0-9]{64}$/;
+export type TimelineFilter = "everything" | "agents" | "skills" | "needs-you";
+export interface ContentReference { digest: string; bytes: number; ref?: string }
+export interface ActivitySkill { name: string; source: string; digest: string }
+export interface ActivityEvent {
+  version: 1; id: string; kind: string; at: string; rootId: string; taskId: string; parentTaskId?: string;
+  agentId?: string; agent?: string; outcome?: string; model?: string; thinking?: string;
+  prompt?: ContentReference; final?: ContentReference; skill?: ActivitySkill;
+}
+export interface TimelineSkill extends ActivitySkill { available: boolean; read: boolean; active: boolean; superseded: boolean }
+export interface TimelineTask {
+  id: string; rootId: string; parentTaskId?: string; startedAt: string; endedAt?: string;
+  status: "active" | "finished" | "failed" | "cancelled" | "needs-you";
+  model?: string; thinking?: string; prompt?: ContentReference; final?: ContentReference;
+  skills: TimelineSkill[]; agents: Array<{ id: string; parentTaskId?: string; agent: string; state: string }>;
+}
+export interface ActivityTimeline { tasks: TimelineTask[]; refusals: string[] }
+export interface ActivityIdentity { rootId: string; path: string; taskId?: string; parentTaskId?: string }
+
+const sha = (value: string) => createHash("sha256").update(value).digest("hex");
+const validId = (value: unknown) => typeof value === "string" && value.length > 0 && value.length <= 200;
+/** Stable, unambiguous local selector: encoded root identity and task id, separated once by `:`. */
+export const activityTaskKey = (rootId: string, taskId: string) => `${encodeURIComponent(rootId)}:${encodeURIComponent(taskId)}`;
+function taskFromKey(value: string): { rootId: string; taskId: string } | null {
+  const parts = value.split(":"); if (parts.length !== 2 || value.length > 1400) return null;
+  try { const [rootId, taskId] = parts.map(decodeURIComponent); return validId(rootId) && validId(taskId) && value === activityTaskKey(rootId, taskId) ? { rootId, taskId } : null; } catch { return null; }
+}
+function validRef(value: unknown): value is ContentReference {
+  const ref = value as ContentReference | null;
+  return !!ref && typeof ref === "object" && DIGEST.test(String(ref.digest)) && Number.isSafeInteger(ref.bytes) && ref.bytes >= 0 &&
+    (ref.ref === undefined || (ref.bytes <= MAX_CONTENT_BYTES && REF.test(ref.ref)));
+}
+function eventOf(value: unknown): ActivityEvent | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const event = value as Partial<ActivityEvent>;
+  if (event.version !== 1 || !validId(event.id) || !validId(event.kind) || !validId(event.rootId) || !validId(event.taskId) ||
+      typeof event.at !== "string" || !Number.isFinite(Date.parse(event.at))) return null;
+  if ((event.parentTaskId && !validId(event.parentTaskId)) || (event.agentId && !validId(event.agentId)) ||
+      (event.agent && !validId(event.agent)) || (event.prompt && !validRef(event.prompt)) || (event.final && !validRef(event.final))) return null;
+  if (event.skill && (!validId(event.skill.name) || typeof event.skill.source !== "string" || event.skill.source.length > 2048 || !DIGEST.test(event.skill.digest))) return null;
+  return event as ActivityEvent;
+}
+export function parseActivityTimeline(text: string): ActivityTimeline {
+  const tasks = new Map<string, TimelineTask>(), refusals: string[] = [];
+  for (const [index, raw] of text.split("\n").entries()) {
+    if (!raw.trim()) continue;
+    let event: ActivityEvent | null = null;
+    try { event = eventOf(JSON.parse(raw)); } catch { /* reported below */ }
+    if (!event) { refusals.push(`line ${index + 1}: invalid or unsafe timeline event`); continue; }
+    const key = `${event.rootId}\0${event.taskId}`;
+    let task = tasks.get(key);
+    if (!task) { task = { id: event.taskId, rootId: event.rootId, parentTaskId: event.parentTaskId, startedAt: event.at, status: "active", skills: [], agents: [] }; tasks.set(key, task); }
+    if (event.kind === "task_started") { task.model = event.model; task.thinking = event.thinking; task.prompt = event.prompt; task.parentTaskId = event.parentTaskId ?? task.parentTaskId; }
+    if (event.kind === "task_finished") { task.endedAt = event.at; task.final = event.final; task.status = event.outcome === "cancelled" ? "cancelled" : ["failed", "error"].includes(event.outcome ?? "") ? "failed" : "finished"; }
+    if (event.kind === "needs_you") task.status = "needs-you";
+    if (event.skill) {
+      let skill = task.skills.find(value => value.name === event!.skill!.name && value.digest === event!.skill!.digest && value.source === event!.skill!.source);
+      if (!skill) { skill = { ...event.skill, available: false, read: false, active: false, superseded: false }; task.skills.push(skill); }
+      if (event.kind === "skill_available") skill.available = true;
+      if (event.kind === "skill_read") skill.read = true;
+      if (event.kind === "skill_active") skill.active = true;
+      if (event.kind === "skill_finished") skill.active = false;
+      if (event.kind === "skill_superseded") { skill.superseded = true; skill.active = false; }
+    }
+    if (event.kind === "agent_started" && event.agentId) task.agents.push({ id: event.agentId, parentTaskId: event.parentTaskId, agent: event.agent ?? "unknown", state: "active" });
+    if (event.kind === "agent_finished" && event.agentId) { const agent = task.agents.find(value => value.id === event!.agentId); if (agent) agent.state = event.outcome ?? "finished"; }
+  }
+  return { tasks: [...tasks.values()].sort((a, b) => a.startedAt.localeCompare(b.startedAt)), refusals };
+}
+function mark(status: TimelineTask["status"]): string { return status === "active" ? "●" : status === "needs-you" ? "!" : status === "failed" || status === "cancelled" ? "×" : "✓"; }
+export function renderActivityTimeline(timeline: ActivityTimeline, options: { filter?: TimelineFilter; details?: boolean; content?: { taskKey: string; field: "prompt" | "final"; text: string } } = {}): string {
+  const filter = options.filter ?? "everything", lines = ["PI-DADDY ACTIVITY", ""];
+  const tasks = timeline.tasks.filter(task => filter === "everything" || filter === "needs-you" && task.status === "needs-you" || filter === "agents" && task.agents.length > 0 || filter === "skills" && task.skills.length > 0);
+  for (const task of tasks) {
+    lines.push(`${task.parentTaskId ? "  └─ " : ""}${mark(task.status)} ${task.id}  ${task.status}${task.model ? ` · ${task.model}` : ""}${task.thinking ? ` · requested thinking ${task.thinking}` : ""}`);
+    if (filter !== "agents") for (const skill of task.skills) lines.push(`  skill ${skill.name} · ${skill.available ? "available" : "availability unknown"}; ${skill.read ? "read" : "not observed read"}; ${skill.active ? "declared active" : "not declared active"}${skill.superseded ? "; superseded" : ""}`);
+    if (filter !== "skills") for (const agent of task.agents) lines.push(`  agent ${agent.agent} · ${agent.state}${agent.parentTaskId ? ` · parent ${agent.parentTaskId}` : ""}`);
+    if (options.details && (task.prompt || task.final)) { const key = activityTaskKey(task.rootId, task.id); lines.push(`  private details: p ${key} (submitted prompt) · f ${key} (final response)`); }
+  }
+  if (options.content) lines.push("", `PRIVATE ${options.content.field.toUpperCase()} · ${options.content.taskKey}`, options.content.text);
+  if (!tasks.length) lines.push("No activity recorded yet.");
+  if (timeline.refusals.length) lines.push(...timeline.refusals.map(refusal => `timeline refusal: ${refusal}`));
+  lines.push("", "Filters: Everything · Agents · Skills · Needs-you. Type p <root-id:task-id> or f <root-id:task-id> after d Details; shorthand task ids are refused. Read is observation; active is a declaration; neither proves compliance.");
+  return lines.join("\n");
+}
+export const defaultActivityTimelinePath = (cwd: string) => join(cwd, ".pi", "pi-daddy", "activity.jsonl");
+export function activityIdentity(cwd: string, env: NodeJS.ProcessEnv = process.env): ActivityIdentity {
+  const configured = env[ENV_ACTIVITY_TIMELINE]?.trim(), transported = env[ENV_ACTIVITY_PATH]?.trim();
+  const path = transported ? resolve(transported) : configured && configured !== "1" && configured !== "off" && configured !== "0" ? resolve(cwd, configured) : defaultActivityTimelinePath(cwd);
+  return { rootId: env[ENV_ACTIVITY_ROOT]?.trim() || randomUUID(), path, ...(env[ENV_ACTIVITY_TASK]?.trim() ? { taskId: env[ENV_ACTIVITY_TASK].trim() } : {}), ...(env[ENV_ACTIVITY_PARENT_TASK]?.trim() ? { parentTaskId: env[ENV_ACTIVITY_PARENT_TASK].trim() } : {}) };
+}
+export class ActivityTimelineRecorder {
+  readonly enabled: boolean; readonly contentEnabled: boolean; readonly path: string; readonly rootId: string; private taskId?: string;
+  constructor(cwd: string, env: NodeJS.ProcessEnv = process.env) { const configured = env[ENV_ACTIVITY_TIMELINE]?.trim(); this.enabled = configured !== "off" && configured !== "0"; this.contentEnabled = env[ENV_ACTIVITY_CONTENT]?.trim() !== "metadata-only" && env[ENV_ACTIVITY_CONTENT]?.trim() !== "off"; const identity = activityIdentity(cwd, env); this.path = identity.path; this.rootId = identity.rootId; this.taskId = identity.taskId; }
+  get task(): string | undefined { return this.taskId; }
+  attach(taskId: string): void { this.taskId = taskId; }
+  async start(prompt: string, model?: string, thinking?: string, parentTaskId?: string): Promise<string | undefined> { if (!this.enabled) return undefined; this.taskId = randomUUID(); await this.append("task_started", { parentTaskId, model, thinking, prompt: await this.content(prompt) }); return this.taskId; }
+  async childStarted(taskId: string, parentTaskId: string | undefined, agent: string, prompt: string, model?: string, thinking?: string): Promise<void> { if (!this.enabled) return; this.taskId = taskId; await this.append("task_started", { parentTaskId, agentId: taskId, agent, model, thinking, prompt: await this.content(prompt) }); await this.append("agent_started", { parentTaskId, agentId: taskId, agent }); }
+  async childFinished(taskId: string, parentTaskId: string | undefined, agent: string, final: string, outcome: "completed" | "failed" | "cancelled"): Promise<void> { if (!this.enabled) return; this.taskId = taskId; await this.append("agent_finished", { parentTaskId, agentId: taskId, agent, outcome }); await this.finish(final, outcome); }
+  async finish(final: string | undefined, outcome: "completed" | "failed" | "cancelled" = "completed"): Promise<void> { if (this.enabled && this.taskId) await this.append("task_finished", { outcome, ...(final === undefined ? {} : { final: await this.content(final) }) }); }
+  async skill(kind: "skill_available" | "skill_read" | "skill_active" | "skill_finished" | "skill_superseded", skill: ActivitySkill): Promise<void> { if (this.taskId) await this.append(kind, { skill }); }
+  async append(kind: string, fields: Omit<Partial<ActivityEvent>, "version" | "id" | "kind" | "at" | "rootId" | "taskId">): Promise<void> { if (!this.enabled || !this.taskId) return; const event: ActivityEvent = { version: 1, id: randomUUID(), kind, at: new Date().toISOString(), rootId: this.rootId, taskId: this.taskId, ...fields }; const text = JSON.stringify(event); if (Buffer.byteLength(text) > MAX_EVENT_BYTES) throw Error("activity timeline event exceeds bound"); await mkdir(dirname(this.path), { recursive: true, mode: 0o700 }); await appendFile(this.path, `${text}\n`, { mode: 0o600 }); }
+  private async content(value: string): Promise<ContentReference> { const digest = sha(value), bytes = Buffer.byteLength(value); if (!this.contentEnabled || bytes > MAX_CONTENT_BYTES) return { digest, bytes }; const root = join(dirname(this.path), "content"), target = join(root, digest); await mkdir(root, { recursive: true, mode: 0o700 }); try { await readFile(target, "utf8"); } catch { const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`; await writeFile(temporary, value, { encoding: "utf8", mode: 0o600 }); await rename(temporary, target); } return { digest, bytes, ref: `content/${digest}` }; }
+}
+export async function readActivityContent(timelinePath: string, reference: ContentReference): Promise<string> {
+  if (!validRef(reference) || !reference.ref) throw Error("TIMELINE_REFERENCE_INVALID");
+  const root = resolve(dirname(timelinePath), "content"), target = resolve(dirname(timelinePath), reference.ref);
+  if (!target.startsWith(`${root}${sep}`) || await realpath(root) !== root) throw Error("TIMELINE_REFERENCE_INVALID");
+  const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try { const before = await handle.stat(); if (!before.isFile() || before.nlink !== 1 || before.size > MAX_CONTENT_BYTES) throw Error("TIMELINE_REFERENCE_INVALID"); const value = await handle.readFile("utf8"), after = await handle.stat(); if (after.size !== before.size || Buffer.byteLength(value) !== reference.bytes || sha(value) !== reference.digest) throw Error("TIMELINE_REFERENCE_TAMPERED"); return value; } finally { await handle.close(); }
+}
+export async function detailForTimeline(timelinePath: string, taskKey: string, field: "prompt" | "final"): Promise<{ taskKey: string; field: "prompt" | "final"; text: string }> {
+  const identity = taskFromKey(taskKey); if (!identity) throw Error("TIMELINE_DETAIL_INVALID");
+  const timeline = parseActivityTimeline(await readFile(timelinePath, "utf8"));
+  const task = timeline.tasks.find(value => value.rootId === identity.rootId && value.id === identity.taskId);
+  const reference = task?.[field]; if (!reference) throw Error("TIMELINE_DETAIL_UNAVAILABLE");
+  return { taskKey, field, text: await readActivityContent(timelinePath, reference) };
+}