pi-async 0.2.0 → 0.3.0

package/extensions/index.ts

@@ -1,65 +1,164 @@
+import { homedir } from "node:os";
 import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { clearTaskActivity, raiseTaskActivity, reportActivity } from "../src/core/bus.ts";
 import { sendCompletionNotification } from "../src/core/notify.ts";
 import { TaskRegistry } from "../src/core/registry.ts";
+import { isTerminal, type TaskSnapshot } from "../src/core/task.ts";
 import { SettleGuard } from "../src/guard/settle-guard.ts";
-import { registerTools } from "../src/tools/index.ts";
+import { registerTools, type ToolContext } from "../src/tools/index.ts";
 import { registerRail } from "../src/tui/rail.ts";
-import { disposeStatus, initStatus } from "../src/tui/status.ts";
+import { initStatus } from "../src/tui/status.ts";
 import { registerPanelCommands } from "../src/tui/panel.ts";
 import { bindTuiHost } from "../src/tui/host.ts";
-import { isTerminal } from "../src/core/task.ts";
 
 export type PiCtx = ExtensionAPI;
 
+/** Structural view of pi's session manager: 0.3.0 only reads dir + id (validated at runtime). */
+type SessionManagerLike = {
+  getSessionDir?: () => string | undefined;
+  getSessionId?: () => string | undefined;
+};
+
 type RuntimeContext = PiCtx & {
   cwd?: string;
-  pid?: number;
-  sessionId?: string;
-  getSessionId?: () => string | undefined;
-  sessionManager?: { getSessionId?: () => string | undefined };
-  mode?: string;
+  sessionManager?: SessionManagerLike;
   on?: (event: string, handler: (...args: unknown[]) => unknown) => unknown;
   registerTool?: (...args: unknown[]) => unknown;
+  registerMessageRenderer?: (...args: unknown[]) => unknown;
 };
 
-function registryDataDir(pi: PiCtx): string {
-  const context = pi as RuntimeContext;
-  const pid = Number.isInteger(context.pid) && (context.pid ?? 0) > 0 ? context.pid ?? process.pid : process.pid;
-  const sessionId = context.sessionManager?.getSessionId?.() ?? context.getSessionId?.() ?? context.sessionId;
-  const safeSessionId = (sessionId || String(process.pid)).replace(/[^\w.-]/g, "_");
-  const cwd = typeof context.cwd === "string" && context.cwd.length > 0 ? context.cwd : process.cwd();
-  return join(cwd, ".pi", "async", `${safeSessionId}-${pid}`);
+/**
+ * Session-scoped data directory (D-16 / PLAN §2.8):
+ * `<sessionDir>/pi-async/<sessionId>`, or undefined when the host exposes no
+ * session directory (degraded hosts, factory-time calls) so the caller can
+ * fall back to the library default. Nothing is created here — the registry
+ * creates directories lazily on first persist/configure (D-04).
+ */
+function sessionDataDir(ctx?: { sessionManager?: SessionManagerLike }): string | undefined {
+  const dir = ctx?.sessionManager?.getSessionDir?.();
+  const sessionId = ctx?.sessionManager?.getSessionId?.();
+  if (typeof dir !== "string" || dir.length === 0) return undefined;
+  if (typeof sessionId !== "string" || sessionId.length === 0) return undefined;
+  return join(dir, "pi-async", sessionId);
 }
 
-/** Previous init generation; /reload re-runs init without session_shutdown (#44). */
+/** Library fallback when no session directory is available: per-process `~/.pi/async/<pid>`. */
+function fallbackDataDir(): string {
+  return join(homedir(), ".pi", "async", String(process.pid));
+}
+
+/**
+ * Previous init generation. Retired (guard disposed, registry suspended — never
+ * killed) at the start of the next init: `/reload` must be able to adopt the
+ * running tasks, and a timer that outlives the invalidated ctx would crash the
+ * whole process (#44 / crash 2026-10-21). Killing is reserved for
+ * `session_shutdown` with quit/new/fork.
+ */
 let activeRegistry: TaskRegistry | undefined;
-let activeDisposeTui: (() => void) | undefined;
+
+/** Previous generation's settle guard; disposed up front instead of trusting a teardown event. */
+let activeGuard: SettleGuard | undefined;
+
+/** One-line card for completion notifications (PLAN §2.8), rendered from message.details. */
+function formatDuration(ms: number): string {
+  return `${(Math.max(0, ms) / 1000).toFixed(1)}s`;
+}
+
+function firstContentLine(content: unknown): string {
+  if (typeof content === "string") {
+    return content.split(/\r?\n/).find((line) => line.trim().length > 0)?.trim() ?? "";
+  }
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (!block || typeof block !== "object") continue;
+      const text = (block as { text?: unknown }).text;
+      if (typeof text !== "string") continue;
+      const line = text.split(/\r?\n/).find((candidate) => candidate.trim().length > 0);
+      if (line) return line.trim();
+    }
+  }
+  return "";
+}
+
+/**
+ * `✓ name (completed, 1.2s) · exit 0` / `✗ name (failed, 1.2s) · exit 7 · kill timeout`.
+ * Duration comes from the live snapshot (details does not carry timings); without
+ * a snapshot the duration is omitted. Falls back to the message content's first
+ * line when the custom message carries no details.
+ */
+function notificationCard(message: unknown, registry: TaskRegistry): string {
+  const details = (message as { details?: unknown })?.details;
+  if (!details || typeof details !== "object") {
+    return firstContentLine((message as { content?: unknown })?.content) || "async task notification";
+  }
+  const d = details as { taskId?: unknown; name?: unknown; status?: unknown; exitCode?: unknown; killKind?: unknown; failureKind?: unknown };
+  const taskId = typeof d.taskId === "string" ? d.taskId : undefined;
+  const snapshot: TaskSnapshot | undefined = taskId ? registry.get(taskId) : undefined;
+  const status = typeof d.status === "string" ? d.status : snapshot?.status ?? "unknown";
+  const name = typeof d.name === "string" ? d.name : snapshot?.name ?? "async task";
+  const finishedAt = snapshot?.finishedAt;
+  const duration = finishedAt === undefined ? "" : `, ${formatDuration(finishedAt - (snapshot?.startedAt ?? snapshot?.createdAt ?? finishedAt))}`;
+  const parts = [`${status === "completed" ? "✓" : "✗"} ${name} (${status}${duration})`];
+  const exitCode = typeof d.exitCode === "number" ? d.exitCode : snapshot?.exitCode;
+  if (exitCode !== undefined) parts.push(`exit ${exitCode}`);
+  const killKind = typeof d.killKind === "string" ? d.killKind : undefined;
+  const failureKind = typeof d.failureKind === "string" ? d.failureKind : undefined;
+  if (killKind) parts.push(`kill ${killKind}`);
+  else if (failureKind) parts.push(`failure ${failureKind}`);
+  return parts.join(" · ");
+}
 
 /** Wire the task runtime to the host API, degrading optional Pi features gracefully. */
 export async function init(pi: PiCtx): Promise<void> {
-  // Reload replaces the extension runtime; retire the previous generation first so
-  // its processes, watch loops, and timers are released (pi docs: cleanup must be
-  // idempotent across reload / session replacement / exit).
-  if (activeRegistry) {
+  // Retire the previous generation first: dispose its guard and SUSPEND its registry
+  // (timers/watches stopped, processes left running) so a /reload can adopt the work
+  // from disk. Never kill here — killing is quit/new/fork's job (PLAN §2.8).
+  const previousGuard = activeGuard;
+  const previousRegistry = activeRegistry;
+  activeGuard = undefined;
+  activeRegistry = undefined;
+  if (previousGuard) {
     try {
-      activeDisposeTui?.();
-    } catch { /* best effort */ }
-    activeDisposeTui = undefined;
+      previousGuard.dispose();
+    } catch (error) {
+      console.error("pi-async: previous settle guard disposal during reload failed", error);
+    }
+  }
+  if (previousRegistry) {
     try {
-      await activeRegistry.shutdown();
+      await previousRegistry.suspend();
     } catch (error) {
-      console.error("pi-async: previous registry shutdown during reload failed", error);
+      console.error("pi-async: previous registry suspension during reload failed", error);
     }
-    activeRegistry = undefined;
   }
-  const registry = new TaskRegistry({ dataDir: registryDataDir(pi) });
+
+  const context = pi as RuntimeContext;
+  // The factory creates the registry only — no mkdir, no reloadFromDisk, no timers.
+  // Data dir and cwd land in `configure()` on the first session/tool context (D-04).
+  // Real pi exposes no sessionManager at factory time, so this is usually the library
+  // fallback until the first session ctx arrives (PLAN §2.8: "no sessionManager → fallback").
+  const factoryDataDir = sessionDataDir(context) ?? fallbackDataDir();
+  const registry = new TaskRegistry({ dataDir: factoryDataDir });
   activeRegistry = registry;
-  // NOTE: pi's factory-time ExtensionAPI exposes no `mode`/`ui` — those live on
-  // event-handler contexts (pi.on("session_start", (event, ctx) => ...)). TUI
-  // registration must therefore bind lazily from the first event context.
+  // NOTE: pi's factory-time ExtensionAPI exposes no `mode`/`ui`/`sessionManager` — those live on
+  // event-handler contexts (pi.on("session_start", (event, ctx) => ...)), so data dir, cwd and TUI
+  // binding are resolved lazily from the first ctx.
+  let configured = false;
   let tui = false;
+
+  /** One-time `configure({dataDir, cwd})` from whatever ctx is available (session event or tool call). */
+  const ensureConfigured = (ctx?: { cwd?: string; sessionManager?: SessionManagerLike }): void => {
+    if (configured) return;
+    configured = true;
+    try {
+      registry.configure({ dataDir: sessionDataDir(ctx) ?? factoryDataDir, cwd: typeof ctx?.cwd === "string" && ctx.cwd.length > 0 ? ctx.cwd : undefined });
+    } catch (error) {
+      // configure() is contractually non-throwing (D-05); never let a wiring hiccup break a tool call.
+      console.error("pi-async: registry configure failed", error);
+    }
+  };
+
   const bindTui = (ctx: unknown): void => {
     if (!bindTuiHost(ctx)) return;
     tui = true;
@@ -68,18 +167,53 @@ export async function init(pi: PiCtx): Promise<void> {
     registerPanelCommands(pi, registry);
   };
 
+  // First session_start / message_start: configure → resend missed notifications, and bind
+  // the TUI synchronously on the first TUI-capable ctx (pi exposes ui only on event ctxs).
+  // Idempotent: repeated events neither re-configure nor re-send.
+  let startup: Promise<void> | undefined;
+  const onLifecycle = (ctx: unknown): Promise<void> => {
+    if (!startup) {
+      ensureConfigured(ctx as RuntimeContext);
+      startup = (async () => {
+        try {
+          await registry.resendUnnotified();
+        } catch (error) {
+          console.error("pi-async: re-sending missed notifications failed", error);
+        }
+      })();
+    }
+    bindTui(ctx);
+    return startup;
+  };
+
   registry.setEvents({
     onFinalize: (snapshot) => {
       clearTaskActivity(pi, snapshot.taskId);
       reportActivity(pi, registry.activeCount());
       if (tui) initStatus(pi, registry);
       if (snapshot.metadata.notifyOnCompletion === false) return;
+      let outputTail = "";
+      let truncated = false;
+      try {
+        const logSlice = registry.logs(snapshot.taskId, { maxBytes: 8192, tail: true });
+        outputTail = logSlice.text;
+        truncated = logSlice.truncated;
+      } catch (error) {
+        // Out-of-dataDir outputFile (D-11) must not crash finalization or the notification path.
+        console.error(`pi-async: could not read output for ${snapshot.taskId}`, error);
+      }
       const outputFile = String(snapshot.metadata.outputFile ?? "");
-      const logSlice = registry.logs(snapshot.taskId, { maxBytes: 8192, tail: true });
-      const outputTail = logSlice.text;
-      const guidance = snapshot.status === "failed" ? `Inspect task output with async_logs (taskId: ${snapshot.taskId}).` : undefined;
-      const summaryTruncated = snapshot.metadata.capped === true || logSlice.truncated;
-      void sendCompletionNotification(pi, registry, {
+      // `lost` = adopted after /reload but the exit status was never observed; saying only "failed"
+      // would misreport a normal reload ending. `startError` (W1a) explains a failed spawn/delayed start.
+      const startError = typeof snapshot.metadata.startError === "string" && snapshot.metadata.startError.length > 0
+        ? snapshot.metadata.startError
+        : undefined;
+      const failureNotes: string[] = [];
+      if (snapshot.failureKind === "lost") failureNotes.push("Exit status unknown after session reload; output may be incomplete.");
+      if (startError !== undefined) failureNotes.push(`Start error: ${startError}`);
+      if (snapshot.status === "failed") failureNotes.push(`Inspect task output with async_logs (taskId: ${snapshot.taskId}).`);
+      const guidance = failureNotes.length > 0 ? failureNotes.join(" ") : undefined;
+      const payload = {
         taskId: snapshot.taskId,
         name: snapshot.name,
         status: snapshot.status,
@@ -89,8 +223,16 @@ export async function init(pi: PiCtx): Promise<void> {
         ...(guidance ? { guidance } : {}),
         ...(snapshot.killKind ? { killKind: snapshot.killKind } : {}),
         ...(snapshot.failureKind ? { failureKind: snapshot.failureKind } : {}),
-        ...(summaryTruncated ? { summaryTruncated: true } : {}),
-      }, { triggerTurn: snapshot.metadata.triggerOnCompletion !== false })
+        ...(truncated || snapshot.metadata.capped === true ? { summaryTruncated: true } : {}),
+      };
+      // Honest notification (PLAN §2.4/§2.8): no fake retries here. A failed send keeps
+      // notified=false / notifyAttempts>0 in the registry and is re-sent at the next session_start.
+      void sendCompletionNotification(pi, registry, payload, { triggerTurn: snapshot.metadata.triggerOnCompletion !== false })
+        .then((outcome) => {
+          if (outcome === "failed") {
+            console.error(`pi-async: completion notification failed for ${snapshot.taskId}; it will be re-sent on the next session_start`);
+          }
+        })
         .catch((error: unknown) => console.error(`pi-async: completion notification failed for ${snapshot.taskId}`, error));
     },
     onStateChange: (snapshot) => {
@@ -102,34 +244,44 @@ export async function init(pi: PiCtx): Promise<void> {
     },
   });
 
-  try {
-    await registry.reloadFromDisk();
-  } catch (error) {
-    console.error("pi-async: failed to reload task state; continuing with an empty registry", error);
+  if (typeof context.registerTool === "function") registerTools(pi, registry, ensureConfigured);
+
+  // Completion notification card (PLAN §2.8). Local component implementation: the TUI lane owns
+  // src/tui/*, so this renderer must not import from there.
+  if (typeof context.registerMessageRenderer === "function") {
+    context.registerMessageRenderer("async-task-notification", (message: unknown) => ({
+      render: () => [notificationCard(message, registry)],
+      invalidate: () => undefined,
+    }));
   }
 
-  const context = pi as RuntimeContext;
-  if (typeof context.registerTool === "function") registerTools(pi, registry);
-  // Bind TUI surfaces from the first event context (factory API has no mode/ui).
   if (typeof context.on === "function") {
-    context.on("session_start", (_event: unknown, ctx: unknown) => bindTui(ctx));
-    context.on("message_start", (_event: unknown, ctx: unknown) => bindTui(ctx));
-  }
-  if (typeof context.on === "function") new SettleGuard(pi, registry).register();
+    context.on("session_start", (_event: unknown, ctx: unknown) => onLifecycle(ctx));
+    context.on("message_start", (_event: unknown, ctx: unknown) => onLifecycle(ctx));
 
-  activeDisposeTui = () => {
-    if (tui) disposeStatus();
-  };
+    // agent_settled / agent_before_settle are registered by SettleGuard itself.
+    activeGuard = new SettleGuard(pi, registry);
+    activeGuard.register();
+  }
 
   let shutdownPromise: Promise<void> | undefined;
   if (typeof context.on === "function") {
-    context.on("session_shutdown", async () => {
-      if (!shutdownPromise) shutdownPromise = (async () => {
-        activeDisposeTui?.();
-        activeDisposeTui = undefined;
-        if (activeRegistry === registry) activeRegistry = undefined;
-        await registry.shutdown();
-      })();
+    context.on("session_shutdown", async (event: unknown) => {
+      if (!shutdownPromise) {
+        shutdownPromise = (async () => {
+          // D-16 / PLAN §2.8: reload + resume suspend (next generation adopts from disk);
+          // quit/new/fork (and an unknown/undefined reason) shut down and kill.
+          const reason = (event as { reason?: string } | undefined)?.reason;
+          const suspendOnly = reason === "reload" || reason === "resume";
+          if (activeRegistry === registry) activeRegistry = undefined;
+          try {
+            if (suspendOnly) await registry.suspend();
+            else await registry.shutdown();
+          } catch (error) {
+            console.error(`pi-async: session shutdown (${String(reason ?? "unknown")}) failed`, error);
+          }
+        })();
+      }
       await shutdownPromise;
     });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-async",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Pi extension for async shell tasks: background/delayed/sync modes, output-matching watches, event-driven waiting, settle guard for legion children, and a TUI task rail — completion notifications wake your session.",
   "type": "module",
   "license": "MIT",
@@ -44,7 +44,9 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types --test tests/*.test.ts"
+    "test": "node --experimental-strip-types --test tests/*.test.ts",
+    "verify": "npm run typecheck && npm test",
+    "prepublishOnly": "npm run verify"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^1.2.0",

package/src/core/duration.ts

@@ -6,11 +6,15 @@ import type { TaskSnapshot } from "./task.ts";
  * - end base = finishedAt ?? now (terminal states freeze; live tasks tick)
  * - three tiers: Ns / Mm Ss / Hh Mm
  */
-export function formatDuration(task: TaskSnapshot, now: number): string {
-  if (task.status === "pending") return "—";
-  const end = task.finishedAt ?? now;
-  const seconds = Math.floor(Math.max(0, end - (task.startedAt ?? task.createdAt)) / 1000);
+export function formatElapsedMs(ms: number): string {
+  const seconds = Math.floor(Math.max(0, ms) / 1000);
   if (seconds < 60) return `${seconds}s`;
   const minutes = Math.floor(seconds / 60);
   return minutes < 60 ? `${minutes}m ${seconds % 60}s` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
 }
+
+export function formatDuration(task: TaskSnapshot, now: number): string {
+  if (task.status === "pending") return "—";
+  const end = task.finishedAt ?? now;
+  return formatElapsedMs(end - (task.startedAt ?? task.createdAt));
+}

package/src/core/env.ts

@@ -21,3 +21,114 @@ export function envNumber(name: string, fallback: number, opts?: EnvNumberOpts):
   if (opts?.max !== undefined && parsed > opts.max) return fallback;
   return parsed;
 }
+
+/** Child environment inheritance policy (REV-16). `safe` is the default. */
+export type EnvPolicy = "safe" | "all" | "none";
+
+/** Keys whose inheritance would silently change how the child resolves code (REV-16). */
+const DANGEROUS_KEYS: ReadonlySet<string> = new Set([
+  "PATH",
+  "LD_PRELOAD",
+  "LD_LIBRARY_PATH",
+  "NODE_OPTIONS",
+  "BASH_ENV",
+  "ENV",
+  "SHELLOPTS",
+  "PYTHONPATH",
+  "GIT_SSH_COMMAND",
+]);
+
+/** Suffix families treated as credentials under `safe` inheritance. */
+const SENSITIVE_SUFFIX = /_(API_KEY|TOKEN|SECRET|PASSWORD)$/i;
+const SENSITIVE_SUBSTRING = /CREDENTIAL/i;
+const SENSITIVE_EXPLICIT: ReadonlySet<string> = new Set([
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SESSION_TOKEN",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "NPM_TOKEN",
+]);
+
+/** `none` keeps only what a POSIX shell needs to start at all. */
+const NONE_ALLOWED: ReadonlySet<string> = new Set(["PATH", "HOME", "SHELL", "TERM", "LANG", "TMPDIR", "USER"]);
+
+/** Host-only tuning knob: never leaks into a child, under any policy. */
+export const INTERNAL_MAX_OUTPUT_ENV = "PI_ASYNC_INTERNAL_MAX_OUTPUT_BYTES";
+
+function isSensitiveKey(key: string): boolean {
+  if (SENSITIVE_EXPLICIT.has(key) || SENSITIVE_SUFFIX.test(key) || SENSITIVE_SUBSTRING.test(key)) return true;
+  // npm reads credentials from lower-case `npm_config_*` keys (e.g. npm_config__authToken).
+  return key.toLowerCase().startsWith("npm_config_") && /(auth|token|password)/i.test(key);
+}
+
+function noneAllows(key: string): boolean {
+  return NONE_ALLOWED.has(key) || key.startsWith("LC_");
+}
+
+function assignDefined(target: Record<string, string>, source: NodeJS.ProcessEnv | Record<string, string>): void {
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue;
+    target[key] = String(value);
+  }
+}
+
+/**
+ * Reject explicit overrides of process-resolution keys (`PATH`, `NODE_OPTIONS`, …).
+ *
+ * Exported so task-submission paths (e.g. delayed tasks, which spawn later) can fail fast
+ * instead of surfacing the error only when the process is finally started. Applied by every
+ * inheritance policy.
+ */
+export function assertSafeEnvKeys(extra: Record<string, string> | undefined, policyName?: EnvPolicy): void {
+  if (!extra) return;
+  const policyContext = policyName ? ` under env policy "${policyName}"` : "";
+  for (const key of Object.keys(extra)) {
+    if (!DANGEROUS_KEYS.has(key)) continue;
+    throw new Error(
+      `Refusing to set dangerous environment variable ${key} for an async task: ` +
+        `explicit overrides of process-resolution keys are rejected${policyContext}. ` +
+        `The inherited ${key} is used instead.`,
+    );
+  }
+}
+
+/**
+ * Build the child environment for a task (pure: never mutates `base` or `extra`).
+ *
+ * - `safe`  (default): inherit `base` minus credential-ish keys; extra ordinary keys override.
+ * - `all`   : legacy `{...base, ...extra}`.
+ * - `none`  : only PATH/HOME/SHELL/TERM/LANG/LC_-prefixed/TMPDIR/USER from `base`, plus extra ordinary keys.
+ *
+ * In every policy an explicit dangerous key (`PATH`, `NODE_OPTIONS`, …) in `extra` throws,
+ * and the internal output-cap knob is always stripped.
+ */
+export function buildChildEnv(
+  base: NodeJS.ProcessEnv,
+  extra: Record<string, string> | undefined,
+  policy: EnvPolicy,
+): Record<string, string> {
+  assertSafeEnvKeys(extra, policy);
+  const env: Record<string, string> = {};
+  switch (policy) {
+    case "all":
+      assignDefined(env, base);
+      break;
+    case "none":
+      for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || !noneAllows(key)) continue;
+        env[key] = String(value);
+      }
+      break;
+    case "safe":
+    default:
+      for (const [key, value] of Object.entries(base)) {
+        if (value === undefined || isSensitiveKey(key)) continue;
+        env[key] = String(value);
+      }
+      break;
+  }
+  assignDefined(env, extra ?? {});
+  delete env[INTERNAL_MAX_OUTPUT_ENV];
+  return env;
+}

package/src/core/notify.ts

@@ -11,6 +11,12 @@ export interface NotifyPayload {
   summaryTruncated?: boolean;
 }
 
+/**
+ * Honest notification outcome (PLAN §2.3): `queued` only means the host accepted the message,
+ * not that the model read it. There is no ack, so there is no "delivered" state and no retry loop.
+ */
+export type NotifyOutcome = "queued" | "skipped" | "failed";
+
 /** XML 1.0 Char excludes C0 (except TAB/LF/CR), lone surrogates, and U+FFFE/FFFF (#19). */
 const ILLEGAL_XML = /[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]/g;
 
@@ -31,27 +37,69 @@ export function buildNotificationXml(p: NotifyPayload): string {
   return `<async-task-notification>${fields.map(([tag, value]) => `<${tag}>${escapeXml(value)}</${tag}>`).join("")}</async-task-notification>`;
 }
 
+/** Structured twin of the XML body, consumed by the TUI message renderer (PLAN §2.3). */
+function buildNotificationDetails(p: NotifyPayload): Record<string, unknown> {
+  return {
+    taskId: p.taskId,
+    name: p.name,
+    status: p.status,
+    ...(p.exitCode === undefined ? {} : { exitCode: p.exitCode }),
+    ...(p.killKind === undefined ? {} : { killKind: p.killKind }),
+    ...(p.failureKind === undefined ? {} : { failureKind: p.failureKind }),
+    ...(p.summary === undefined ? {} : { summary: p.summary }),
+    ...(p.summaryTruncated === undefined ? {} : { summaryTruncated: p.summaryTruncated }),
+    outputFile: p.outputFile,
+    ...(p.guidance === undefined ? {} : { guidance: p.guidance }),
+  };
+}
+
+/** `sendMessage` is `void` in older pi hosts and `Promise<void>` in newer ones (both shapes ship). */
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  (typeof value === "object" ? value !== null : typeof value === "function") &&
+  typeof (value as PromiseLike<unknown>).then === "function";
+
+/**
+ * Send a completion notification exactly once per undelivered task.
+ *
+ * Order (PLAN §2.3 / D-01): skip checks → in-memory claim (concurrency dedupe only) →
+ * persist the attempt → send `sendMessage` (awaited only when the host returns a promise) →
+ * latch `notified` on success or drop the claim on failure (`notified` stays false so
+ * `resendUnnotified` can retry later).
+ */
 export async function sendCompletionNotification(
   pi: PiCtx,
   registry: TaskRegistry,
   p: NotifyPayload,
   options: { triggerTurn?: boolean } = {},
-): Promise<boolean> {
-  if (registry.get(p.taskId)?.outputConsumed || !registry.claimNotification(p.taskId)) return false;
+): Promise<NotifyOutcome> {
+  const task = registry.get(p.taskId);
+  // skipped: nothing to notify about (unknown/consumed task) or the caller opted out.
+  if (!task || task.outputConsumed || task.metadata.notifyOnCompletion === false) return "skipped";
+  // The claim is memory-only (D-01): losing it to a concurrent sender means skipped, not failed.
+  if (!registry.claimNotification(p.taskId)) return "skipped";
+  // Persist the attempt before the send so a failed host call stays visible after reload/restart.
+  registry.noteNotifyAttempt(p.taskId);
   // SAFETY: The pi extension API provides sendMessage in supported hosts; detect it at runtime for other contexts.
+  // The result is typed `unknown` on purpose: pi 1.2/1.3 declare `sendMessage(...): void` while 1.5+ declares
+  // `Promise<void>`. A `void` return means "handed to the host"; a promise still has to settle before we
+  // can honestly call it queued — and awaiting it keeps a rejection from escaping as unhandledRejection.
   const target = pi as unknown as { sendMessage?: (message: unknown, options: unknown) => unknown };
-  if (!target.sendMessage) { registry.rollbackNotification(p.taskId); return false; }
-  for (let attempt = 0; attempt < 3; attempt++) {
-    try {
-      await target.sendMessage(
-        { customType: "async-task-notification", content: buildNotificationXml(p) },
-        { deliverAs: "followUp", ...(options.triggerTurn === false ? {} : { triggerTurn: true }) },
-      );
-      return true;
-    } catch {
-      if (attempt < 2) await Promise.resolve();
-    }
+  if (!target.sendMessage) {
+    registry.releaseNotification(p.taskId);
+    return "failed";
+  }
+  try {
+    // No retry loop and no rollback — the host offers no ack, so retrying only duplicates messages.
+    const result = target.sendMessage(
+      { customType: "async-task-notification", content: buildNotificationXml(p), details: buildNotificationDetails(p) },
+      { deliverAs: "followUp", ...(options.triggerTurn === false ? {} : { triggerTurn: true }) },
+    );
+    if (isThenable(result)) await result;
+  } catch {
+    // Sync throw or rejected promise: same honest outcome, `notified` stays false.
+    registry.releaseNotification(p.taskId);
+    return "failed";
   }
-  registry.rollbackNotification(p.taskId);
-  return false;
+  registry.markNotified(p.taskId);
+  return "queued";
 }