pi-daddy 0.27.4 → 0.32.0

package/src/products/activity-timeline.ts

@@ -0,0 +1,679 @@
+/** 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";
+import { activityTimelinePath } from "../kernel/project-paths.ts";
+import { appendRecord, readRecords } from "../governance/record.ts";
+
+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;
+  agent?: 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[] = [];
+  // ADR-0076 PR 3d: the timeline is record envelopes of kind "activity"; bodies are the events. Everything
+  // before the first damaged line is read and the damage is one refusal naming its line, never its bytes.
+  const read = readRecords(text);
+  for (const [index, record] of read.records.entries()) {
+    let event: ActivityEvent | null = null;
+    try {
+      event = record.kind === "activity" ? eventOf(record.body) : null;
+    } 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.agent = event.agent ?? task.agent;
+      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";
+    }
+  }
+  if (read.damage) refusals.push(`line ${read.damage.line}: timeline damaged (${read.damage.reason})`);
+  return {
+    tasks: [...tasks.values()].sort(
+      (a, b) =>
+        a.startedAt.localeCompare(b.startedAt) ||
+        activityTaskKey(a.rootId, a.id).localeCompare(activityTaskKey(b.rootId, b.id)),
+    ),
+    refusals,
+  };
+}
+
+/** Session-local aliases never derive from private prompt text and never renumber after a refresh. */
+export class ActivityTimelineAliases {
+  private readonly roots = new Map<string, string>();
+  private readonly tasks = new Map<string, string>();
+  private readonly selectors = new Map<string, string>();
+  selector(task: Pick<TimelineTask, "rootId" | "id">): string {
+    let root = this.roots.get(task.rootId);
+    if (!root) {
+      root = `r${this.roots.size + 1}`;
+      this.roots.set(task.rootId, root);
+    }
+    const key = activityTaskKey(task.rootId, task.id);
+    let child = this.tasks.get(key);
+    if (!child) {
+      const count = [...this.tasks.keys()].filter((value) => taskFromKey(value)?.rootId === task.rootId).length;
+      child = `t${count + 1}`;
+      this.tasks.set(key, child);
+    }
+    const selector = `${root}/${child}`;
+    this.selectors.set(selector, key);
+    return selector;
+  }
+  resolve(selector: string): string | undefined {
+    return this.selectors.get(selector);
+  }
+}
+export function resolveActivityTaskSelector(
+  timeline: ActivityTimeline,
+  selector: string,
+  aliases?: ActivityTimelineAliases,
+): string | undefined {
+  const key = aliases?.resolve(selector) ?? selector,
+    identity = taskFromKey(key);
+  return identity && timeline.tasks.some((task) => task.rootId === identity.rootId && task.id === identity.taskId)
+    ? key
+    : undefined;
+}
+
+const ANSI_SGR = /\u001b\[[0-9;]*m/g;
+const WIDE_CELL = /\p{Extended_Pictographic}|[\u2E80-\u9FFF\uF900-\uFAFF]/u;
+/** Render controls as literal escapes; only content newlines retain their structural meaning. */
+function visualizeControls(value: string, preserveNewlines = false): string {
+  let output = "";
+  for (let index = 0; index < value.length;) {
+    const codePoint = value.codePointAt(index);
+    if (codePoint === undefined) break;
+    const char = String.fromCodePoint(codePoint),
+      next = index + char.length;
+    if (char === "\r" && value[next] === "\n") {
+      output += preserveNewlines ? "\n" : "\\n";
+      index = next + 1;
+      continue;
+    }
+    if (char === "\n") {
+      output += preserveNewlines ? "\n" : "\\n";
+      index = next;
+      continue;
+    }
+    if (codePoint < 0x20 || codePoint === 0x7f) output += `\\x${codePoint.toString(16).padStart(2, "0")}`;
+    else if ((codePoint >= 0x80 && codePoint <= 0x9f) || /\p{Cf}/u.test(char))
+      output += `\\u{${codePoint.toString(16)}}`;
+    else output += char;
+    index = next;
+  }
+  return output;
+}
+function clean(value: string | undefined): string {
+  return visualizeControls(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+function cellWidth(value: string): number {
+  return [...value.replace(ANSI_SGR, "")].reduce((sum, char) => sum + (WIDE_CELL.test(char) ? 2 : 1), 0);
+}
+function wrapDetailLine(value: string, width: number): string[] {
+  if (value.length === 0) return [""];
+  const lines: string[] = [];
+  let line = "",
+    cells = 0;
+  for (const char of value) {
+    const next = WIDE_CELL.test(char) ? 2 : 1;
+    if (cells + next > width && line) {
+      lines.push(line);
+      line = "";
+      cells = 0;
+    }
+    line += char;
+    cells += next;
+  }
+  lines.push(line);
+  return lines;
+}
+function safeDetailLines(value: string, width: number): string[] {
+  return visualizeControls(value, true)
+    .split("\n")
+    .flatMap((line) => wrapDetailLine(line, width));
+}
+function truncate(value: string, width: number): string {
+  if (cellWidth(value) <= width) return value;
+  const target = Math.max(0, width - 1);
+  let cells = 0,
+    output = "",
+    styled = false;
+  for (let index = 0; index < value.length;) {
+    if (value[index] === "\u001b") {
+      const match = /^\u001b\[([0-9;]*)m/.exec(value.slice(index));
+      if (match) {
+        output += match[0];
+        styled = match[1] !== "0" && match[1] !== "";
+        index += match[0].length;
+        continue;
+      }
+    }
+    const codePoint = value.codePointAt(index);
+    if (codePoint === undefined) break;
+    const char = String.fromCodePoint(codePoint),
+      next = WIDE_CELL.test(char) ? 2 : 1;
+    if (cells + next > target) break;
+    output += char;
+    cells += next;
+    index += char.length;
+  }
+  return `${output}…${styled ? "\u001b[0m" : ""}`;
+}
+function paint(value: string, color: number, enabled: boolean): string {
+  return enabled ? `\u001b[${color}m${value}\u001b[0m` : value;
+}
+
+interface ActivityRenderOptions {
+  filter?: TimelineFilter;
+  details?: boolean;
+  history?: boolean;
+  color?: boolean;
+  width?: number;
+  aliases?: ActivityTimelineAliases;
+  content?: { taskKey: string; field: "prompt" | "final"; text: string };
+}
+function taskKey(task: Pick<TimelineTask, "rootId" | "id">): string {
+  return `${task.rootId}\0${task.id}`;
+}
+function isAttention(task: TimelineTask): boolean {
+  return task.status !== "finished";
+}
+function stateLine(task: TimelineTask, child: boolean): { text: string; color: number } {
+  if (task.status === "active") return { text: "AGENT ACTIVE", color: 36 };
+  if (task.status === "needs-you") return { text: "WAIT NEEDS YOU", color: 33 };
+  if (task.status === "failed") return { text: child ? "FAIL CHILD FAILED" : "FAIL PARENT TURN FAILED", color: 31 };
+  if (task.status === "cancelled")
+    return { text: child ? "WAIT CHILD CANCELLED" : "WAIT PARENT TURN CANCELLED", color: 33 };
+  return { text: child ? "DONE CHILD COMPLETED" : "DONE PARENT TURN ENDED", color: 32 };
+}
+
+/** Render only local observation. “Completed” and “ended” never mean accepted. */
+export function renderActivityTimeline(timeline: ActivityTimeline, options: ActivityRenderOptions = {}): string {
+  const color = options.color === true && Boolean(process.stdout.isTTY) && process.env.NO_COLOR === undefined;
+  const width = Math.max(10, options.width ?? 80),
+    filter = options.filter ?? "everything",
+    aliases = options.aliases ?? new ActivityTimelineAliases();
+  const byKey = new Map(timeline.tasks.map((task) => [taskKey(task), task]));
+  const children = new Map<string, TimelineTask[]>(),
+    roots: TimelineTask[] = [];
+  for (const task of timeline.tasks) {
+    const parent = task.parentTaskId ? byKey.get(`${task.rootId}\0${task.parentTaskId}`) : undefined;
+    if (parent) {
+      const list = children.get(taskKey(parent)) ?? [];
+      list.push(task);
+      children.set(taskKey(parent), list);
+    } else roots.push(task);
+  }
+  for (const list of children.values())
+    list.sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.id.localeCompare(b.id));
+  roots.sort(
+    (a, b) =>
+      a.startedAt.localeCompare(b.startedAt) ||
+      activityTaskKey(a.rootId, a.id).localeCompare(activityTaskKey(b.rootId, b.id)),
+  );
+  const matching = (task: TimelineTask): boolean =>
+    filter === "everything"
+      ? true
+      : filter === "agents"
+        ? Boolean(task.agent || task.agents.length)
+        : filter === "skills"
+          ? task.skills.length > 0
+          : task.status === "needs-you";
+  const shown = new Set<string>();
+  for (const task of timeline.tasks)
+    if (matching(task)) {
+      let current: TimelineTask | undefined = task,
+        seen = new Set<string>();
+      while (current && !seen.has(taskKey(current))) {
+        shown.add(taskKey(current));
+        seen.add(taskKey(current));
+        current = current.parentTaskId ? byKey.get(`${current.rootId}\0${current.parentTaskId}`) : undefined;
+      }
+    }
+  const hasAttention = (task: TimelineTask, seen = new Set<string>()): boolean => {
+    const key = taskKey(task);
+    if (seen.has(key)) return true;
+    seen.add(key);
+    return isAttention(task) || (children.get(key) ?? []).some((child) => hasAttention(child, seen));
+  };
+  const choose = (tasks: TimelineTask[], limit: number): { shown: TimelineTask[]; hidden: number } => {
+    const important = tasks.filter((task) => hasAttention(task)),
+      quiet = tasks.filter((task) => !hasAttention(task));
+    const kept = options.history ? quiet : quiet.slice(-limit);
+    return {
+      shown: [...important, ...kept].sort((a, b) => a.startedAt.localeCompare(b.startedAt) || a.id.localeCompare(b.id)),
+      hidden: quiet.length - kept.length,
+    };
+  };
+  const lines = [paint("PI-DADDY ACTIVITY", 36, color), ""];
+  const renderTask = (task: TimelineTask, prefix: string, branch: string): void => {
+    const key = taskKey(task),
+      directChildren = (children.get(key) ?? []).filter((child) => shown.has(taskKey(child)));
+    if (!shown.has(key)) return;
+    const child = Boolean(task.parentTaskId && byKey.has(`${task.rootId}\0${task.parentTaskId}`));
+    const state = stateLine(task, child),
+      selector = aliases.selector(task);
+    const heading = clean(task.agent) || (child ? "Governed child" : "User turn");
+    const meta = [task.model && `model ${clean(task.model)}`, task.thinking && `thinking ${clean(task.thinking)}`]
+      .filter(Boolean)
+      .join(" · ");
+    lines.push(
+      `${prefix}${branch}${paint(child ? "AGENT" : "USER", child ? 36 : 34, color)} ${heading} [${selector}] · ${paint(state.text, state.color, color)}${meta ? ` · ${meta}` : ""}`,
+    );
+    const failedChildren = directChildren.filter((value) => value.status === "failed").length;
+    if (failedChildren)
+      lines.push(
+        `${prefix}${branch ? "   " : ""}  ${paint(`FAIL OBSERVED CHILD FAILURES: ${failedChildren} failed (not accepted)`, 31, color)}`,
+      );
+    const visibleSkills = task.skills.filter(
+      (skill) => options.details || filter === "skills" || skill.read || skill.active || skill.superseded,
+    );
+    for (const skill of visibleSkills) {
+      const availabilityOnly = skill.available && !skill.read && !skill.active && !skill.superseded;
+      const description = availabilityOnly
+        ? "available only"
+        : `read ${skill.read ? "yes" : "no"} · declared active ${skill.active ? "yes" : "no"}${skill.superseded ? " · superseded" : ""}`;
+      lines.push(
+        `${prefix}${branch ? "   " : ""}  ${paint("SKILL", 35, color)} ${clean(skill.name) || "unnamed"} · ${description}`,
+      );
+    }
+    if (options.details || filter === "agents")
+      for (const agent of task.agents)
+        lines.push(
+          `${prefix}${branch ? "   " : ""}  ${paint("AGENT", 36, color)} ${clean(agent.agent) || "unknown"} · observed ${clean(agent.state) || "unknown"}`,
+        );
+    if (options.details && (task.prompt || task.final))
+      lines.push(
+        `${prefix}${branch ? "   " : ""}  DETAILS p|f ${selector} · legacy ${activityTaskKey(task.rootId, task.id)}`,
+      );
+    const selected = choose(directChildren, 2);
+    if (selected.hidden > 0)
+      lines.push(
+        `${prefix}${branch ? "   " : ""}  ${paint(`… ${selected.hidden} quiet completed child task${selected.hidden === 1 ? "" : "s"} hidden`, 90, color)}`,
+      );
+    selected.shown.forEach((value, index) =>
+      renderTask(
+        value,
+        `${prefix}${branch === "" ? "" : branch === "└─ " ? "   " : "│  "}`,
+        index === selected.shown.length - 1 ? "└─ " : "├─ ",
+      ),
+    );
+  };
+  const selectedRoots = choose(
+    roots.filter((task) => shown.has(taskKey(task))),
+    3,
+  );
+  if (selectedRoots.hidden > 0)
+    lines.push(
+      paint(
+        `… ${selectedRoots.hidden} quiet completed root task${selectedRoots.hidden === 1 ? "" : "s"} hidden`,
+        90,
+        color,
+      ),
+    );
+  for (const root of selectedRoots.shown) renderTask(root, "", "");
+  if (!selectedRoots.shown.length) lines.push("No matching local activity recorded yet.");
+  if (timeline.refusals.length)
+    lines.push(...timeline.refusals.map((refusal) => paint(`FAIL timeline refusal: ${clean(refusal)}`, 31, color)));
+  if (options.content)
+    lines.push(
+      "",
+      `${paint("PRIVATE", 34, color)} ${options.content.field.toUpperCase()} · ${clean(options.content.taskKey)}`,
+      ...safeDetailLines(options.content.text, width),
+    );
+  lines.push(
+    "",
+    "Keys: d details · h history · Everything|Agents|Skills|Needs-you · p|f <r#/t# or root:task>. Read and declared active are observations, not compliance or acceptance.",
+  );
+  return lines.map((line) => truncate(line, width)).join("\n");
+}
+
+export const defaultActivityTimelinePath = (cwd: string) => activityTimelinePath(cwd);
+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 appendRecord(this.path, "activity", event); // ADR-0076 PR 3d: envelope, lock, damage refusal
+  }
+  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) };
+}