pi-agent-replicate 0.0.0-stage → 1.4.1

package/pi-extension/subagents/completion.js

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+const ABORT_MESSAGE = "Aborted while waiting for subagent to finish";
+const TERMINAL_SENTINEL = /__SUBAGENT_DONE_(\d+)__/;
+export function interpretExitSidecar(data) {
+    const payload = data;
+    if (payload?.type === "ping") {
+        return {
+            reason: "ping",
+            exitCode: 0,
+            ping: {
+                ...(typeof payload.id === "string"
+                    ? { id: payload.id }
+                    : {}),
+                name: typeof payload.name === "string" ? payload.name : "subagent",
+                message: typeof payload.message === "string" ? payload.message : "",
+            },
+        };
+    }
+    if (payload?.type === "error") {
+        const errorMessage = typeof payload.errorMessage === "string" && payload.errorMessage.trim()
+            ? payload.errorMessage
+            : "Subagent exited with stopReason=error (no errorMessage in sidecar).";
+        return { reason: "error", exitCode: 1, errorMessage };
+    }
+    if (payload?.type === "done")
+        return {
+            reason: "done",
+            exitCode: 0,
+            ...(typeof payload.summary === "string" && payload.summary.trim() ? { summary: payload.summary } : {}),
+        };
+    return {
+        reason: "error",
+        exitCode: 1,
+        errorMessage: "Invalid subagent completion sidecar: unsupported payload type.",
+    };
+}
+/** Read completion evidence without acknowledging or removing it. */
+export function readExitSidecar(sessionFile) {
+    if (!sessionFile)
+        return null;
+    const exitFile = `${sessionFile}.exit`;
+    if (!existsSync(exitFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(exitFile, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Remove completion evidence only after durable result and inbox publication. */
+export function acknowledgeExitSidecar(sessionFile) {
+    rmSync(`${sessionFile}.exit`, { force: true });
+}
+/** Remove only the exact help evidence that was durably published. */
+export function acknowledgePingSidecar(sessionFile, pingId) {
+    const payload = readExitSidecar(sessionFile);
+    if (payload == null || typeof payload !== "object")
+        return;
+    const candidate = payload;
+    if (candidate.type !== "ping" || candidate.id !== pingId)
+        return;
+    rmSync(`${sessionFile}.exit`, { force: true });
+}
+function consumeExitSidecar(sessionFile) {
+    const payload = readExitSidecar(sessionFile);
+    return payload == null ? null : interpretExitSidecar(payload);
+}
+function terminalExitCode(screen) {
+    const match = screen.match(TERMINAL_SENTINEL);
+    return match ? Number.parseInt(match[1], 10) : null;
+}
+/** Keep the last concrete error block, not shell prompts or unrelated startup warnings. */
+function failureDiagnostic(output) {
+    const lines = output.replace(/\r/g, "").split("\n");
+    const start = lines.map(line => /^\s*(?:[A-Za-z]*Error:|Failed to load extension|Cannot find module)/.test(line)).lastIndexOf(true);
+    if (start < 0)
+        return undefined;
+    const block = lines.slice(start);
+    const end = block.findIndex(line => /^\s*(?:Warning:|Hint:)/.test(line) || TERMINAL_SENTINEL.test(line));
+    return block.slice(0, end < 0 ? block.length : end).join("\n").trim().slice(0, 8192) || undefined;
+}
+function completionArtifact(options) {
+    return consumeExitSidecar(options.resolveSessionFile?.() ?? options.sessionFile);
+}
+async function waitForDisappearanceArtifacts(signal, options) {
+    const immediate = completionArtifact(options);
+    if (immediate)
+        return immediate;
+    const graceMs = Math.max(0, options.paneDisappearanceGraceMs ?? 500);
+    const deadline = Date.now() + graceMs;
+    while (Date.now() < deadline) {
+        const remaining = deadline - Date.now();
+        await abortableDelay(Math.min(25, remaining), signal);
+        const result = completionArtifact(options);
+        if (result)
+            return result;
+    }
+    return null;
+}
+function abortableDelay(milliseconds, signal) {
+    if (signal.aborted)
+        return Promise.reject(new Error(ABORT_MESSAGE));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error(ABORT_MESSAGE));
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export async function waitForCompletion(signal, options) {
+    const startedAt = Date.now();
+    for (;;) {
+        if (signal.aborted)
+            throw new Error(ABORT_MESSAGE);
+        const sidecarResult = completionArtifact(options);
+        if (sidecarResult)
+            return sidecarResult;
+        try {
+            const exitCode = terminalExitCode(await options.readTerminalTail());
+            if (exitCode !== null) {
+                // The shell sentinel can race the child-side exit sidecar. Give the
+                // durable intent a short chance to win so an explicit final summary is
+                // not mistaken for a previously delivered settled turn.
+                const sidecarResult = options.sessionFile
+                    ? await waitForDisappearanceArtifacts(signal, options)
+                    : null;
+                if (sidecarResult)
+                    return sidecarResult;
+                if (options.confirmTerminalExit && !await options.confirmTerminalExit()) {
+                    await abortableDelay(options.intervalMs, signal);
+                    continue;
+                }
+                let errorMessage;
+                if (options.readFailureOutput) {
+                    try {
+                        errorMessage = failureDiagnostic(await options.readFailureOutput());
+                    }
+                    catch { /* Confirmed exit still reports without an invented diagnostic. */ }
+                }
+                if (options.confirmTerminalExit && !await options.confirmTerminalExit()) {
+                    await abortableDelay(options.intervalMs, signal);
+                    continue;
+                }
+                return { reason: "sentinel", exitCode, ...(errorMessage ? { errorMessage } : {}) };
+            }
+        }
+        catch {
+            // Terminal reads are only sentinel/output probes; Herdr status is polled
+            // independently below, even when terminal reads succeed.
+        }
+        if (options.inspectPane) {
+            let inspection;
+            try {
+                inspection = await options.inspectPane();
+            }
+            catch {
+                inspection = { kind: "unavailable", error: "inspectPane threw" };
+            }
+            const observedAt = Date.now();
+            options.onPaneInspection?.(inspection, observedAt);
+            if (inspection.kind === "missing") {
+                // Pane closure and atomic artifact publication are separate operations.
+                // Allow a short bounded grace window before declaring evidence lost.
+                const racedCompletion = await waitForDisappearanceArtifacts(signal, options);
+                if (racedCompletion)
+                    return racedCompletion;
+                return {
+                    reason: "error",
+                    exitCode: 1,
+                    errorMessage: "Subagent pane disappeared before completion evidence was recorded.",
+                    paneDisappeared: true,
+                };
+            }
+        }
+        options.onTick?.(Math.floor((Date.now() - startedAt) / 1000));
+        await abortableDelay(options.intervalMs, signal);
+    }
+}

package/pi-extension/subagents/completion.ts

@@ -0,0 +1,229 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+
+const ABORT_MESSAGE = "Aborted while waiting for subagent to finish";
+const TERMINAL_SENTINEL = /__SUBAGENT_DONE_(\d+)__/;
+
+export interface CompletionResult {
+  reason: "done" | "ping" | "sentinel" | "error";
+  exitCode: number;
+  ping?: { id?: string; name: string; message: string };
+  summary?: string;
+  errorMessage?: string;
+  /** Confirmed Herdr pane absence without a completion artifact. */
+  paneDisappeared?: true;
+}
+
+export interface CompletionOptions {
+  intervalMs: number;
+  readTerminalTail: () => Promise<string>;
+  /** Replica-only diagnostic read after confirmed exit, never a failure trigger itself. */
+  readFailureOutput?: () => Promise<string>;
+  /** Revalidate replica process exit after races with sidecars or replacement startup. */
+  confirmTerminalExit?: () => boolean | Promise<boolean>;
+  inspectPane?: () => Promise<import("./lifecycle.ts").PaneInspection>;
+  /** Bounded artifact grace after terminal or pane completion evidence. Default: 500ms. */
+  paneDisappearanceGraceMs?: number;
+  onPaneInspection?: (
+    inspection: import("./lifecycle.ts").PaneInspection,
+    observedAt: number,
+  ) => void;
+  sessionFile?: string;
+  /** Resolve the current file after a same-session process handoff. */
+  resolveSessionFile?: () => string;
+  onTick?: (elapsedSeconds: number) => void;
+}
+
+export function interpretExitSidecar(data: unknown): CompletionResult {
+  const payload = data as {
+    type?: unknown;
+    name?: unknown;
+    message?: unknown;
+    summary?: unknown;
+    errorMessage?: unknown;
+  };
+
+  if (payload?.type === "ping") {
+    return {
+      reason: "ping",
+      exitCode: 0,
+      ping: {
+        ...(typeof (payload as { id?: unknown }).id === "string"
+          ? { id: (payload as { id: string }).id }
+          : {}),
+        name: typeof payload.name === "string" ? payload.name : "subagent",
+        message: typeof payload.message === "string" ? payload.message : "",
+      },
+    };
+  }
+
+  if (payload?.type === "error") {
+    const errorMessage =
+      typeof payload.errorMessage === "string" && payload.errorMessage.trim()
+        ? payload.errorMessage
+        : "Subagent exited with stopReason=error (no errorMessage in sidecar).";
+    return { reason: "error", exitCode: 1, errorMessage };
+  }
+
+  if (payload?.type === "done") return {
+    reason: "done",
+    exitCode: 0,
+    ...(typeof payload.summary === "string" && payload.summary.trim() ? { summary: payload.summary } : {}),
+  };
+
+  return {
+    reason: "error",
+    exitCode: 1,
+    errorMessage: "Invalid subagent completion sidecar: unsupported payload type.",
+  };
+}
+
+/** Read completion evidence without acknowledging or removing it. */
+export function readExitSidecar(sessionFile: string | undefined): unknown | null {
+  if (!sessionFile) return null;
+  const exitFile = `${sessionFile}.exit`;
+  if (!existsSync(exitFile)) return null;
+  try { return JSON.parse(readFileSync(exitFile, "utf8")); }
+  catch { return null; }
+}
+
+/** Remove completion evidence only after durable result and inbox publication. */
+export function acknowledgeExitSidecar(sessionFile: string): void {
+  rmSync(`${sessionFile}.exit`, { force: true });
+}
+
+
+/** Remove only the exact help evidence that was durably published. */
+export function acknowledgePingSidecar(sessionFile: string, pingId: string | undefined): void {
+  const payload = readExitSidecar(sessionFile);
+  if (payload == null || typeof payload !== "object") return;
+  const candidate = payload as { type?: unknown; id?: unknown };
+  if (candidate.type !== "ping" || candidate.id !== pingId) return;
+  rmSync(`${sessionFile}.exit`, { force: true });
+}
+
+function consumeExitSidecar(sessionFile: string | undefined): CompletionResult | null {
+  const payload = readExitSidecar(sessionFile);
+  return payload == null ? null : interpretExitSidecar(payload);
+}
+
+function terminalExitCode(screen: string): number | null {
+  const match = screen.match(TERMINAL_SENTINEL);
+  return match ? Number.parseInt(match[1], 10) : null;
+}
+
+/** Keep the last concrete error block, not shell prompts or unrelated startup warnings. */
+function failureDiagnostic(output: string): string | undefined {
+  const lines = output.replace(/\r/g, "").split("\n");
+  const start = lines.map(line => /^\s*(?:[A-Za-z]*Error:|Failed to load extension|Cannot find module)/.test(line)).lastIndexOf(true);
+  if (start < 0) return undefined;
+  const block = lines.slice(start);
+  const end = block.findIndex(line => /^\s*(?:Warning:|Hint:)/.test(line) || TERMINAL_SENTINEL.test(line));
+  return block.slice(0, end < 0 ? block.length : end).join("\n").trim().slice(0, 8192) || undefined;
+}
+function completionArtifact(options: CompletionOptions): CompletionResult | null {
+  return consumeExitSidecar(options.resolveSessionFile?.() ?? options.sessionFile);
+}
+
+async function waitForDisappearanceArtifacts(
+  signal: AbortSignal,
+  options: CompletionOptions,
+): Promise<CompletionResult | null> {
+  const immediate = completionArtifact(options);
+  if (immediate) return immediate;
+
+  const graceMs = Math.max(0, options.paneDisappearanceGraceMs ?? 500);
+  const deadline = Date.now() + graceMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    await abortableDelay(Math.min(25, remaining), signal);
+    const result = completionArtifact(options);
+    if (result) return result;
+  }
+  return null;
+}
+
+function abortableDelay(milliseconds: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) return Promise.reject(new Error(ABORT_MESSAGE));
+
+  return new Promise<void>((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error(ABORT_MESSAGE));
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, milliseconds);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function waitForCompletion(
+  signal: AbortSignal,
+  options: CompletionOptions,
+): Promise<CompletionResult> {
+  const startedAt = Date.now();
+
+  for (;;) {
+    if (signal.aborted) throw new Error(ABORT_MESSAGE);
+
+    const sidecarResult = completionArtifact(options);
+    if (sidecarResult) return sidecarResult;
+
+    try {
+      const exitCode = terminalExitCode(await options.readTerminalTail());
+      if (exitCode !== null) {
+        // The shell sentinel can race the child-side exit sidecar. Give the
+        // durable intent a short chance to win so an explicit final summary is
+        // not mistaken for a previously delivered settled turn.
+        const sidecarResult = options.sessionFile
+          ? await waitForDisappearanceArtifacts(signal, options)
+          : null;
+        if (sidecarResult) return sidecarResult;
+        if (options.confirmTerminalExit && !await options.confirmTerminalExit()) {
+          await abortableDelay(options.intervalMs, signal);
+          continue;
+        }
+        let errorMessage: string | undefined;
+        if (options.readFailureOutput) {
+          try { errorMessage = failureDiagnostic(await options.readFailureOutput()); }
+          catch { /* Confirmed exit still reports without an invented diagnostic. */ }
+        }
+        if (options.confirmTerminalExit && !await options.confirmTerminalExit()) {
+          await abortableDelay(options.intervalMs, signal);
+          continue;
+        }
+        return { reason: "sentinel", exitCode, ...(errorMessage ? { errorMessage } : {}) };
+      }
+    } catch {
+      // Terminal reads are only sentinel/output probes; Herdr status is polled
+      // independently below, even when terminal reads succeed.
+    }
+
+    if (options.inspectPane) {
+      let inspection: import("./lifecycle.ts").PaneInspection;
+      try {
+        inspection = await options.inspectPane();
+      } catch {
+        inspection = { kind: "unavailable", error: "inspectPane threw" };
+      }
+      const observedAt = Date.now();
+      options.onPaneInspection?.(inspection, observedAt);
+      if (inspection.kind === "missing") {
+        // Pane closure and atomic artifact publication are separate operations.
+        // Allow a short bounded grace window before declaring evidence lost.
+        const racedCompletion = await waitForDisappearanceArtifacts(signal, options);
+        if (racedCompletion) return racedCompletion;
+        return {
+          reason: "error",
+          exitCode: 1,
+          errorMessage: "Subagent pane disappeared before completion evidence was recorded.",
+          paneDisappeared: true,
+        };
+      }
+    }
+
+    options.onTick?.(Math.floor((Date.now() - startedAt) / 1000));
+    await abortableDelay(options.intervalMs, signal);
+  }
+}

package/pi-extension/subagents/delivery-drain.js

@@ -0,0 +1,15 @@
+/** Wait without a deadline until durable descendant state reports drained. */
+export async function waitForDeliveryDrain(options) {
+    if (options.isDrained())
+        return;
+    const now = options.now ?? Date.now;
+    const delay = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const waitedSince = now();
+    options.onWaitOpen?.({ waitedSince });
+    while (!options.isDrained()) {
+        if (options.signal?.aborted)
+            throw options.signal.reason ?? new Error("Drain wait aborted");
+        await delay(50);
+    }
+    options.onWaitRelease?.({ waitedSince, waitedMs: Math.max(0, now() - waitedSince) });
+}

package/pi-extension/subagents/delivery-drain.ts

@@ -0,0 +1,20 @@
+/** Wait without a deadline until durable descendant state reports drained. */
+export async function waitForDeliveryDrain(options: {
+  isDrained: () => boolean;
+  delay?: (ms: number) => Promise<void>;
+  now?: () => number;
+  onWaitOpen?: (info: { waitedSince: number }) => void;
+  onWaitRelease?: (info: { waitedSince: number; waitedMs: number }) => void;
+  signal?: AbortSignal;
+}): Promise<void> {
+  if (options.isDrained()) return;
+  const now = options.now ?? Date.now;
+  const delay = options.delay ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const waitedSince = now();
+  options.onWaitOpen?.({ waitedSince });
+  while (!options.isDrained()) {
+    if (options.signal?.aborted) throw options.signal.reason ?? new Error("Drain wait aborted");
+    await delay(50);
+  }
+  options.onWaitRelease?.({ waitedSince, waitedMs: Math.max(0, now() - waitedSince) });
+}

package/pi-extension/subagents/delivery-files.js

@@ -0,0 +1,86 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, writeSync, } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+function fsyncDirectory(path) {
+    const fd = openSync(path, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function deliveryIdFromFile(path) {
+    try {
+        const header = readFileSync(path, "utf8").split(/\r?\n\r?\n/, 1)[0] ?? "";
+        return /^delivery[\s_-]+id\s*[:=]\s*(.+)$/im.exec(header)?.[1]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function files(path) {
+    try {
+        return readdirSync(path).filter((name) => /^\d+-[^/]+\.md$/.test(name));
+    }
+    catch {
+        return [];
+    }
+}
+function existingDelivery(path, deliveryId) {
+    for (const filename of files(path)) {
+        if (deliveryIdFromFile(join(path, filename)) !== deliveryId)
+            continue;
+        const sequence = Number.parseInt(filename, 10);
+        return { path: join(path, filename), sequence, filename };
+    }
+    return undefined;
+}
+function nextSequence(path) {
+    return files(path).reduce((max, filename) => {
+        const sequence = Number.parseInt(filename, 10);
+        return Number.isFinite(sequence) ? Math.max(max, sequence) : max;
+    }, 0) + 1;
+}
+function resultContents(input, sequence) {
+    return [
+        `Status: ${input.status}`,
+        `Agent name: ${input.agentName}`,
+        `Child session id: ${input.childSessionId}`,
+        `Time: ${new Date(input.now).toISOString()}`,
+        `Delivery sequence: ${sequence}`,
+        `Delivery id: ${input.deliveryId}`,
+        "",
+        input.answer ?? "Nothing was captured for this delivery.",
+    ].join("\n");
+}
+/** Materialize one immutable result file, recovering the same delivery after races or restart. */
+export function materializeResultFile(input) {
+    const sessionsDir = isAbsolute(input.sessionsDir) ? input.sessionsDir : resolve(input.sessionsDir);
+    const directory = join(sessionsDir, input.childSessionId);
+    mkdirSync(directory, { recursive: true });
+    for (;;) {
+        const recovered = existingDelivery(directory, input.deliveryId);
+        if (recovered)
+            return recovered;
+        const sequence = nextSequence(directory);
+        const filename = `${String(sequence).padStart(2, "0")}-${input.status}.md`;
+        const path = join(directory, filename);
+        let fd;
+        try {
+            fd = openSync(path, "wx", 0o600);
+            writeSync(fd, resultContents(input, sequence), undefined, "utf8");
+            fsyncSync(fd);
+            closeSync(fd);
+            fd = undefined;
+            fsyncDirectory(directory);
+            return { path, sequence, filename };
+        }
+        catch (error) {
+            if (fd !== undefined)
+                closeSync(fd);
+            if (error.code === "EEXIST")
+                continue;
+            throw error;
+        }
+    }
+}

package/pi-extension/subagents/delivery-files.ts

@@ -0,0 +1,105 @@
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  writeSync,
+} from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import type { DeliveryStatus } from "./delivery-payload.ts";
+
+export interface ResultFileInput {
+  sessionsDir: string;
+  childSessionId: string;
+  deliveryId: string;
+  status: DeliveryStatus;
+  agentName: string;
+  answer?: string;
+  now: number;
+}
+
+export interface ResultFileHandle {
+  path: string;
+  sequence: number;
+  filename: string;
+}
+
+function fsyncDirectory(path: string): void {
+  const fd = openSync(path, "r");
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function deliveryIdFromFile(path: string): string | undefined {
+  try {
+    const header = readFileSync(path, "utf8").split(/\r?\n\r?\n/, 1)[0] ?? "";
+    return /^delivery[\s_-]+id\s*[:=]\s*(.+)$/im.exec(header)?.[1]?.trim();
+  } catch {
+    return undefined;
+  }
+}
+
+function files(path: string): string[] {
+  try { return readdirSync(path).filter((name) => /^\d+-[^/]+\.md$/.test(name)); }
+  catch { return []; }
+}
+
+function existingDelivery(path: string, deliveryId: string): ResultFileHandle | undefined {
+  for (const filename of files(path)) {
+    if (deliveryIdFromFile(join(path, filename)) !== deliveryId) continue;
+    const sequence = Number.parseInt(filename, 10);
+    return { path: join(path, filename), sequence, filename };
+  }
+  return undefined;
+}
+
+function nextSequence(path: string): number {
+  return files(path).reduce((max, filename) => {
+    const sequence = Number.parseInt(filename, 10);
+    return Number.isFinite(sequence) ? Math.max(max, sequence) : max;
+  }, 0) + 1;
+}
+
+function resultContents(input: ResultFileInput, sequence: number): string {
+  return [
+    `Status: ${input.status}`,
+    `Agent name: ${input.agentName}`,
+    `Child session id: ${input.childSessionId}`,
+    `Time: ${new Date(input.now).toISOString()}`,
+    `Delivery sequence: ${sequence}`,
+    `Delivery id: ${input.deliveryId}`,
+    "",
+    input.answer ?? "Nothing was captured for this delivery.",
+  ].join("\n");
+}
+
+/** Materialize one immutable result file, recovering the same delivery after races or restart. */
+export function materializeResultFile(input: ResultFileInput): ResultFileHandle {
+  const sessionsDir = isAbsolute(input.sessionsDir) ? input.sessionsDir : resolve(input.sessionsDir);
+  const directory = join(sessionsDir, input.childSessionId);
+  mkdirSync(directory, { recursive: true });
+
+  for (;;) {
+    const recovered = existingDelivery(directory, input.deliveryId);
+    if (recovered) return recovered;
+
+    const sequence = nextSequence(directory);
+    const filename = `${String(sequence).padStart(2, "0")}-${input.status}.md`;
+    const path = join(directory, filename);
+    let fd: number | undefined;
+    try {
+      fd = openSync(path, "wx", 0o600);
+      writeSync(fd, resultContents(input, sequence), undefined, "utf8");
+      fsyncSync(fd);
+      closeSync(fd);
+      fd = undefined;
+      fsyncDirectory(directory);
+      return { path, sequence, filename };
+    } catch (error) {
+      if (fd !== undefined) closeSync(fd);
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") continue;
+      throw error;
+    }
+  }
+}

package/pi-extension/subagents/delivery-log.js

@@ -0,0 +1,51 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+const ALLOWED_FIELDS = [
+    "childId",
+    "deliveryId",
+    "status",
+    "resultPath",
+    "phase",
+    "error",
+    "waitedSince",
+    "waitedMs",
+    "attempt",
+    "cause",
+    "reason",
+    "surface",
+];
+function normalizeError(value) {
+    if (value == null)
+        return undefined;
+    return value instanceof Error ? value.message : String(value);
+}
+/** Create a contained append-only JSON-lines delivery recorder. */
+export function createDeliveryLog(options) {
+    const now = options.now ?? Date.now;
+    return {
+        record(event, fields = {}) {
+            try {
+                mkdirSync(dirname(options.logPath), { recursive: true });
+                const record = {
+                    version: 1,
+                    time: new Date(now()).toISOString(),
+                    event,
+                };
+                for (const key of ALLOWED_FIELDS) {
+                    if (!(key in fields))
+                        continue;
+                    const value = key === "error" ? normalizeError(fields[key]) : fields[key];
+                    if (value !== undefined)
+                        record[key] = value;
+                }
+                appendFileSync(options.logPath, `${JSON.stringify(record)}\n`, "utf8");
+            }
+            catch (error) {
+                try {
+                    options.onFailure?.(error);
+                }
+                catch { /* containment sink is best effort */ }
+            }
+        },
+    };
+}