takomi 2.1.44 → 2.1.45

package/.pi/extensions/takomi-subagents/detached-results.ts

@@ -0,0 +1,940 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TakomiSubagentToolParams } from "./tool-runner";
+import { loadPiSubagentsInternals } from "./pi-subagents-internal";
+import {
+  finalAnswer,
+  resolvedChecklist,
+  sanitizeUntrustedText,
+  sanitizeUntrustedValue,
+  type TakomiUxTask,
+  withTakomiUxDetails,
+} from "./subagent-ux";
+
+const SESSION_ENTRY_TYPE = "takomi-detached-launch";
+const SESSION_ENTRY_VERSION = 2;
+const MAX_PROVENANCE_BYTES = 4 * 1024;
+const MAX_RESTORED_LAUNCHES = 32;
+const MAX_RESULT_BYTES = 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 64 * 1024;
+const MAX_PENDING_COMPLETIONS = 32;
+const MAX_PENDING_COMPLETION_BYTES = 1024 * 1024;
+const PENDING_COMPLETION_TTL_MS = 30 * 1000;
+const NATIVE_NOTIFY_UNSUBSCRIBE_KEY = "__pi_subagents_notify_unsubscribe__";
+const NATIVE_NOTIFY_SEEN_KEY = "__pi_subagents_notify_seen__";
+const TAKOMI_NOTIFY_HANDLER_KEY = "__takomi_detached_notify_handler__";
+const TRUSTED_LAUNCHES_KEY = "__takomi_detached_trusted_launches__";
+const NOTIFY_TTL_MS = 10 * 60 * 1000;
+
+type NativeResult = {
+  content?: Array<{ type?: string; text?: string }>;
+  details?: Record<string, any>;
+  isError?: boolean;
+};
+
+type DetachedResultChild = {
+  agent?: string;
+  output?: string;
+  error?: string;
+  success?: boolean;
+  exitCode?: number | null;
+  sessionFile?: string;
+  sessionPath?: string;
+  model?: string;
+  attemptedModels?: string[];
+  modelAttempts?: unknown[];
+  artifactPaths?: {
+    inputPath?: string;
+    outputPath?: string;
+    jsonlPath?: string;
+    metadataPath?: string;
+  };
+  acceptance?: Record<string, any>;
+};
+
+export type DetachedCompletionPayload = {
+  id?: string;
+  runId?: string;
+  mode?: "single" | "parallel" | "chain";
+  state?: "complete" | "failed" | "paused";
+  success?: boolean;
+  summary?: string;
+  results?: DetachedResultChild[];
+  asyncDir?: string;
+  sessionId?: string;
+  cwd?: string;
+  sessionFile?: string;
+  artifactsDir?: string;
+  workflowGraph?: unknown;
+  outputs?: unknown;
+  durationMs?: number;
+  exitCode?: number;
+  agent?: string;
+  taskIndex?: number;
+  totalTasks?: number;
+};
+
+type SessionIdentity = {
+  id: string;
+  nativeId: string;
+  file?: string;
+  parent?: string;
+};
+
+type ChecklistProvenance = "trusted-launch" | "unavailable-after-restart";
+
+type DetachedLaunch = {
+  id: string;
+  asyncDir: string;
+  asyncRoot: string;
+  resultRoot: string;
+  artifactRoots: string[];
+  sessionRoots: string[];
+  workspaceRoot: string;
+  runCwd: string;
+  session: SessionIdentity;
+  mode: "single" | "parallel" | "chain";
+  tasks: TakomiUxTask[];
+  checklistProvenance: ChecklistProvenance;
+};
+
+type PendingCompletion = { id: string; payload: DetachedCompletionPayload; receivedAt: number };
+type DetachedLaunchRoots = { asyncRoot: string; resultRoot: string; artifactRoots: string[] };
+
+type DetachedStore = {
+  identity?: { workspaceRoot: string; session: SessionIdentity };
+  launches: Map<string, DetachedLaunch>;
+  completions: Map<string, DetachedCompletionPayload>;
+  pending: PendingCompletion[];
+  notified: Set<string>;
+};
+
+export type ProvenanceState = "not-needed" | "complete" | "missing" | "permission" | "io" | "oversized" | "truncated" | "corrupt" | "rejected";
+
+export type DetachedOutputProvenance = {
+  source: "payload" | "artifact" | "summary" | "none";
+  fallbackState: ProvenanceState;
+  path?: string;
+  bytesRead?: number;
+  error?: string;
+};
+
+type PathProvenance = { state: ProvenanceState; path?: string; error?: string };
+
+const stores = new WeakMap<object, DetachedStore>();
+
+function storeFor(pi: object): DetachedStore {
+  const existing = stores.get(pi);
+  if (existing) return existing;
+  const created: DetachedStore = { launches: new Map(), completions: new Map(), pending: [], notified: new Set() };
+  stores.set(pi, created);
+  return created;
+}
+
+function asRecord(value: unknown): Record<string, any> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, any> : {};
+}
+
+function trustedLaunches(): Map<string, DetachedLaunch> {
+  const globalStore = globalThis as Record<string, unknown>;
+  const existing = globalStore[TRUSTED_LAUNCHES_KEY];
+  if (existing instanceof Map) return existing as Map<string, DetachedLaunch>;
+  const created = new Map<string, DetachedLaunch>();
+  globalStore[TRUSTED_LAUNCHES_KEY] = created;
+  return created;
+}
+
+function trustedLaunchKey(workspaceRoot: string, session: SessionIdentity, id: string): string {
+  return JSON.stringify([workspaceRoot, session.id, session.nativeId, session.file, session.parent, id]);
+}
+
+export function classifyPathError(error: unknown): "missing" | "permission" | "io" {
+  const code = typeof error === "object" && error !== null && "code" in error
+    ? String((error as NodeJS.ErrnoException).code ?? "")
+    : "";
+  if (code === "ENOENT" || code === "ENOTDIR") return "missing";
+  if (code === "EACCES" || code === "EPERM") return "permission";
+  return "io";
+}
+
+function completionId(payload: DetachedCompletionPayload): string | undefined {
+  const id = typeof payload.id === "string" && payload.id.trim() ? payload.id.trim() : undefined;
+  const runId = typeof payload.runId === "string" && payload.runId.trim() ? payload.runId.trim() : undefined;
+  if (id && runId && id !== runId) return undefined;
+  return runId ?? id;
+}
+
+function isPathInside(root: string, candidate: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+async function canonicalPotentialPath(value: string): Promise<string> {
+  const absolute = path.resolve(value);
+  let cursor = absolute;
+  const suffix: string[] = [];
+  while (true) {
+    try {
+      const real = await fs.realpath(cursor);
+      return path.resolve(real, ...suffix.reverse());
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
+      const parent = path.dirname(cursor);
+      if (parent === cursor) return absolute;
+      suffix.push(path.basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+
+async function canonicalExistingDirectory(value: string, label: string): Promise<string> {
+  const real = await fs.realpath(path.resolve(value));
+  const stat = await fs.stat(real);
+  if (!stat.isDirectory()) throw new Error(`${label} is not a directory.`);
+  return real;
+}
+
+async function canonicalSessionIdentity(ctx: ExtensionContext): Promise<SessionIdentity> {
+  const id = ctx.sessionManager.getSessionId();
+  const rawFile = ctx.sessionManager.getSessionFile();
+  const header = ctx.sessionManager.getHeader?.() as { parentSession?: unknown } | undefined;
+  const file = rawFile ? await canonicalPotentialPath(rawFile) : undefined;
+  const parent = typeof header?.parentSession === "string" && header.parentSession.trim()
+    ? await canonicalPotentialPath(header.parentSession)
+    : undefined;
+  return {
+    id,
+    nativeId: file ?? id,
+    ...(file ? { file } : {}),
+    ...(parent ? { parent } : {}),
+  };
+}
+
+function sameSession(a: SessionIdentity, b: SessionIdentity): boolean {
+  return a.id === b.id && a.nativeId === b.nativeId && a.file === b.file && a.parent === b.parent;
+}
+
+async function currentRoots(session: SessionIdentity, workspaceRoot: string): Promise<DetachedLaunchRoots & { sessionRoots: string[] }> {
+  const internals = await loadPiSubagentsInternals();
+  const nativeSessionRoot = session.file
+    ? await canonicalPotentialPath(path.join(path.dirname(session.file), path.basename(session.file, ".jsonl")))
+    : undefined;
+  const conversationSessionRoot = await validatePathWithin(
+    workspaceRoot,
+    path.join(workspaceRoot, ".pi", "takomi", "subagent-conversations"),
+    { mustExist: false, label: "conversation session root" },
+  );
+  return {
+    asyncRoot: await canonicalPotentialPath(internals.ASYNC_DIR),
+    resultRoot: await canonicalPotentialPath(internals.RESULTS_DIR),
+    artifactRoots: [await canonicalPotentialPath(internals.TEMP_ARTIFACTS_DIR)],
+    sessionRoots: [nativeSessionRoot, conversationSessionRoot].filter((root): root is string => Boolean(root)),
+  };
+}
+
+function exactOrUniqueLaunch(entries: Map<string, DetachedLaunch>, requested: string): DetachedLaunch | undefined {
+  const exact = entries.get(requested);
+  if (exact) return exact;
+  const matches = [...entries.values()].filter((launch) => launch.id.startsWith(requested));
+  return matches.length === 1 ? matches[0] : undefined;
+}
+
+function textContent(result: NativeResult): string {
+  return result.content?.filter((part) => part?.type === "text").map((part) => part.text ?? "").join("\n") ?? "";
+}
+
+function fieldFromContent(result: NativeResult, label: string): string | undefined {
+  const escaped = label.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return textContent(result).match(new RegExp(`^${escaped}:\\s+(.+)$`, "m"))?.[1]?.trim();
+}
+
+function resultPathForLaunch(launch: DetachedLaunch, result: NativeResult): string {
+  return fieldFromContent(result, "Result") ?? path.join(launch.resultRoot, `${launch.id}.json`);
+}
+
+async function validatePathWithin(root: string, candidate: string, options: { mustExist: boolean; label: string }): Promise<string> {
+  const canonicalRoot = await canonicalPotentialPath(root);
+  const lexical = path.resolve(candidate);
+  if (!isPathInside(canonicalRoot, lexical)) throw new Error(`${options.label} escapes its approved root.`);
+  const canonical = options.mustExist ? await fs.realpath(lexical) : await canonicalPotentialPath(lexical);
+  if (!isPathInside(canonicalRoot, canonical)) throw new Error(`${options.label} escapes its approved root through a symlink.`);
+  return canonical;
+}
+
+async function validateAgainstRoots(roots: string[], candidate: string, options: { mustExist: boolean; label: string }): Promise<string> {
+  let firstError: unknown;
+  for (const root of roots) {
+    try {
+      return await validatePathWithin(root, candidate, options);
+    } catch (error) {
+      firstError ??= error;
+    }
+  }
+  if (firstError) throw firstError;
+  throw new Error(`${options.label} has no approved root.`);
+}
+
+async function readBounded(filePath: string, maxBytes: number): Promise<{ text?: string; bytesRead: number; truncated: boolean; error?: string; errorState?: ProvenanceState }> {
+  let handle: fs.FileHandle | undefined;
+  try {
+    handle = await fs.open(filePath, "r");
+    const stat = await handle.stat();
+    if (!stat.isFile()) return { bytesRead: 0, truncated: false, error: "not a regular file", errorState: "io" };
+    const bytesToRead = Math.min(stat.size, maxBytes + 1);
+    const buffer = Buffer.alloc(bytesToRead);
+    const { bytesRead } = await handle.read(buffer, 0, bytesToRead, 0);
+    const truncated = stat.size > maxBytes || bytesRead > maxBytes;
+    const usable = buffer.subarray(0, Math.min(bytesRead, maxBytes));
+    try {
+      const decoder = new TextDecoder("utf-8", { fatal: true });
+      // When the byte bound cuts through a multibyte scalar, streaming decode
+      // intentionally retains that incomplete suffix instead of calling it corrupt.
+      const text = truncated ? decoder.decode(usable, { stream: true }) : decoder.decode(usable);
+      return { text, bytesRead: usable.length, truncated };
+    } catch {
+      return { bytesRead: usable.length, truncated, error: "invalid UTF-8", errorState: "corrupt" };
+    }
+  } catch (error) {
+    return {
+      bytesRead: 0,
+      truncated: false,
+      error: error instanceof Error ? error.message : String(error),
+      errorState: classifyPathError(error),
+    };
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+async function readResultPayload(launch: DetachedLaunch, candidate: string): Promise<{ payload?: DetachedCompletionPayload; state: DetachedOutputProvenance["fallbackState"]; error?: string }> {
+  let canonical: string;
+  try {
+    canonical = await validatePathWithin(launch.resultRoot, candidate, { mustExist: true, label: "result path" });
+    if (path.basename(canonical) !== `${launch.id}.json`) {
+      return { state: "rejected", error: "result filename does not exactly match the launched run id" };
+    }
+  } catch (error) {
+    const state = classifyPathError(error);
+    return { state: state === "io" ? "rejected" : state, error: error instanceof Error ? error.message : String(error) };
+  }
+  const read = await readBounded(canonical, MAX_RESULT_BYTES);
+  if (read.error) return { state: read.errorState ?? "io", error: read.error };
+  if (read.truncated) return { state: "oversized", error: `result exceeds ${MAX_RESULT_BYTES} bytes` };
+  try {
+    const parsed = JSON.parse(read.text ?? "");
+    return parsed && typeof parsed === "object"
+      ? { payload: sanitizeUntrustedValue(parsed) as DetachedCompletionPayload, state: "complete" }
+      : { state: "corrupt", error: "result JSON is not an object" };
+  } catch (error) {
+    return { state: "corrupt", error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+async function validatePayloadIdentity(launch: DetachedLaunch, payload: DetachedCompletionPayload): Promise<string | undefined> {
+  const id = completionId(payload);
+  if (!id || id !== launch.id) return "completion run id does not exactly match a known launch";
+  if (typeof payload.sessionId !== "string") return "completion session identity is missing";
+  const payloadSessionId = launch.session.file ? await canonicalPotentialPath(payload.sessionId) : payload.sessionId;
+  if (payloadSessionId !== launch.session.nativeId) return "completion session identity does not match the launch session";
+  if (typeof payload.cwd !== "string") return "completion workspace identity is missing";
+  try {
+    const cwd = await canonicalExistingDirectory(payload.cwd, "completion cwd");
+    if (cwd !== launch.runCwd) return "completion cwd identity does not match the launched run";
+    if (!isPathInside(launch.workspaceRoot, cwd)) return "completion cwd escapes the launch workspace";
+    if (typeof payload.asyncDir !== "string") return "completion asyncDir identity is missing";
+    const asyncDir = await validatePathWithin(launch.asyncRoot, payload.asyncDir, { mustExist: true, label: "completion asyncDir" });
+    if (asyncDir !== launch.asyncDir) return "completion asyncDir does not match the launched run";
+    if (payload.artifactsDir) {
+      const artifactsDir = await validateAgainstRoots(launch.artifactRoots, payload.artifactsDir, { mustExist: false, label: "completion artifactsDir" });
+      if (!launch.artifactRoots.includes(artifactsDir)) return "completion artifact root does not match an approved launch root";
+    }
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  return undefined;
+}
+
+async function validatedChildSession(payload: DetachedCompletionPayload, child: DetachedResultChild, launch: DetachedLaunch): Promise<{ sessionFile?: string; sessionPath?: string; provenance: PathProvenance }> {
+  const fallback = payload.results?.length === 1 ? payload.sessionFile : undefined;
+  const candidates = [child.sessionFile, child.sessionPath, fallback].filter((value): value is string => typeof value === "string" && value.trim().length > 0);
+  if (!candidates.length) return { provenance: { state: "missing", error: "child session path is missing" } };
+  if (!launch.sessionRoots.length) return { provenance: { state: "rejected", error: "no approved child session root is available" } };
+  let firstError: unknown;
+  for (const candidate of candidates) {
+    try {
+      const canonical = await validateAgainstRoots(launch.sessionRoots, candidate, { mustExist: true, label: "child session path" });
+      return { sessionFile: canonical, sessionPath: canonical, provenance: { state: "complete", path: canonical } };
+    } catch (error) {
+      firstError ??= error;
+    }
+  }
+  const classified = classifyPathError(firstError);
+  const message = firstError instanceof Error ? firstError.message : String(firstError);
+  return { provenance: { state: classified === "io" ? "rejected" : classified, error: message } };
+}
+
+async function outputForChild(
+  payload: DetachedCompletionPayload,
+  child: DetachedResultChild,
+  launch: DetachedLaunch,
+): Promise<{ output: string; provenance: DetachedOutputProvenance; artifactPaths?: DetachedResultChild["artifactPaths"] }> {
+  const direct = typeof child.output === "string" ? sanitizeUntrustedText(child.output).trim() : "";
+  const safeArtifactPaths: DetachedResultChild["artifactPaths"] = {};
+  let rejectedPathError: string | undefined;
+  let rejectedPathState: ProvenanceState = "rejected";
+  for (const [name, value] of Object.entries(child.artifactPaths ?? {})) {
+    if (typeof value !== "string") continue;
+    try {
+      (safeArtifactPaths as Record<string, string>)[name] = await validateAgainstRoots(launch.artifactRoots, value, {
+        mustExist: false,
+        label: `artifact ${name}`,
+      });
+    } catch (error) {
+      if (!rejectedPathError) {
+        rejectedPathError = error instanceof Error ? error.message : String(error);
+        const code = typeof error === "object" && error !== null && "code" in error;
+        rejectedPathState = code ? classifyPathError(error) : "rejected";
+      }
+    }
+  }
+  if (direct) {
+    return {
+      output: direct,
+      provenance: { source: "payload", fallbackState: "not-needed" },
+      ...(Object.keys(safeArtifactPaths).length ? { artifactPaths: safeArtifactPaths } : {}),
+    };
+  }
+
+  const outputPath = safeArtifactPaths.outputPath;
+  if (outputPath) {
+    let canonical: string;
+    try {
+      canonical = await validateAgainstRoots(launch.artifactRoots, outputPath, { mustExist: true, label: "output artifact" });
+    } catch (error) {
+      const summary = typeof payload.summary === "string" ? sanitizeUntrustedText(payload.summary).trim() : "";
+      const classified = classifyPathError(error);
+      return {
+        output: summary,
+        provenance: {
+          source: summary ? "summary" : "none",
+          fallbackState: classified === "io" ? "rejected" : classified,
+          path: outputPath,
+          error: error instanceof Error ? error.message : String(error),
+        },
+        artifactPaths: safeArtifactPaths,
+      };
+    }
+    const read = await readBounded(canonical, MAX_ARTIFACT_BYTES);
+    const artifactText = sanitizeUntrustedText(read.text ?? "").trim();
+    if (!read.error && artifactText) {
+      return {
+        output: artifactText,
+        provenance: {
+          source: "artifact",
+          fallbackState: read.truncated ? "truncated" : "complete",
+          path: canonical,
+          bytesRead: read.bytesRead,
+          ...(read.truncated ? { error: `output artifact exceeds ${MAX_ARTIFACT_BYTES} bytes` } : {}),
+        },
+        artifactPaths: safeArtifactPaths,
+      };
+    }
+    const summary = typeof payload.summary === "string" ? sanitizeUntrustedText(payload.summary).trim() : "";
+    return {
+      output: summary,
+      provenance: {
+        source: summary ? "summary" : "none",
+        fallbackState: read.errorState ?? "corrupt",
+        path: canonical,
+        bytesRead: read.bytesRead,
+        error: read.error ?? "output artifact is empty or invalid text",
+      },
+      artifactPaths: safeArtifactPaths,
+    };
+  }
+
+  const summary = typeof payload.summary === "string" ? sanitizeUntrustedText(payload.summary).trim() : "";
+  return {
+    output: summary,
+    provenance: {
+      source: summary ? "summary" : "none",
+      fallbackState: rejectedPathError ? rejectedPathState : "missing",
+      ...(rejectedPathError ? { error: rejectedPathError } : { error: "no output artifact path was provided" }),
+    },
+    ...(Object.keys(safeArtifactPaths).length ? { artifactPaths: safeArtifactPaths } : {}),
+  };
+}
+
+function resultStatus(payload: DetachedCompletionPayload, child: DetachedResultChild): "completed" | "failed" {
+  if (child.success === false || child.exitCode !== undefined && child.exitCode !== null && child.exitCode !== 0) return "failed";
+  if (child.success === true || child.exitCode === 0) return "completed";
+  return payload.state === "failed" ? "failed" : "completed";
+}
+
+/** Convert an authenticated native completion into the foreground Details shape. */
+export async function normalizeDetachedCompletion(
+  payload: DetachedCompletionPayload,
+  launch: DetachedLaunch,
+): Promise<Record<string, unknown> | undefined> {
+  if (!Array.isArray(payload.results) || payload.results.length === 0) return undefined;
+  const durationMs = typeof payload.durationMs === "number" ? payload.durationMs : 0;
+  const results = await Promise.all(payload.results.map(async (rawChild, index) => {
+    const child = sanitizeUntrustedValue(rawChild);
+    const task = launch.tasks[index];
+    const [resolvedOutput, resolvedSession] = await Promise.all([
+      outputForChild(payload, child, launch),
+      validatedChildSession(payload, child, launch),
+    ]);
+    const status = resultStatus(payload, child);
+    const exitCode = typeof child.exitCode === "number" ? child.exitCode : status === "completed" ? 0 : 1;
+    return {
+      agent: child.agent ?? task?.agent ?? `step-${index + 1}`,
+      task: task?.task ?? "Detached async task",
+      exitCode,
+      error: child.error,
+      ...(resolvedSession.sessionFile ? { sessionFile: resolvedSession.sessionFile, sessionPath: resolvedSession.sessionPath } : {}),
+      takomiDetachedSession: resolvedSession.provenance,
+      model: child.model,
+      attemptedModels: child.attemptedModels,
+      modelAttempts: child.modelAttempts,
+      artifactPaths: resolvedOutput.artifactPaths,
+      acceptance: child.acceptance,
+      finalOutput: resolvedOutput.output,
+      takomiDetachedOutput: resolvedOutput.provenance,
+      usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+      progress: {
+        index,
+        agent: child.agent ?? task?.agent ?? `step-${index + 1}`,
+        task: task?.task ?? "Detached async task",
+        status,
+        recentTools: [],
+        recentOutput: [],
+        toolCount: 0,
+        tokens: 0,
+        durationMs,
+        ...(child.error ? { error: child.error } : {}),
+      },
+    };
+  }));
+  return withTakomiUxDetails({
+    mode: payload.mode ?? launch.mode,
+    runId: launch.id,
+    results,
+    asyncDir: launch.asyncDir,
+    ...(payload.workflowGraph ? { workflowGraph: payload.workflowGraph } : {}),
+    ...(payload.outputs ? { outputs: payload.outputs } : {}),
+    ...(payload.artifactsDir ? { artifacts: { dir: payload.artifactsDir, files: results.map((row) => row.artifactPaths).filter(Boolean) } } : {}),
+    takomiDetached: {
+      workspaceRoot: launch.workspaceRoot,
+      runCwd: launch.runCwd,
+      sessionId: launch.session.id,
+      sessionNativeId: launch.session.nativeId,
+      runId: launch.id,
+      asyncDir: launch.asyncDir,
+      resultRoot: launch.resultRoot,
+      checklistProvenance: launch.checklistProvenance,
+    },
+  }, launch.tasks);
+}
+
+type PersistedLaunchLookup = { version: number; id: string };
+
+function launchEntryData(launch: DetachedLaunch): PersistedLaunchLookup {
+  return { version: SESSION_ENTRY_VERSION, id: launch.id };
+}
+
+function boundedLaunchEntry(launch: DetachedLaunch): boolean {
+  return Buffer.byteLength(JSON.stringify(launchEntryData(launch)), "utf8") <= MAX_PROVENANCE_BYTES;
+}
+
+export async function initializeDetachedSession(pi: ExtensionAPI, ctx: ExtensionContext): Promise<void> {
+  const store = storeFor(pi);
+  store.launches.clear();
+  store.completions.clear();
+  store.pending = [];
+  store.notified.clear();
+  const workspaceRoot = await canonicalExistingDirectory(ctx.cwd, "workspace root");
+  const session = await canonicalSessionIdentity(ctx);
+  const roots = await currentRoots(session, workspaceRoot);
+  store.identity = { workspaceRoot, session };
+
+  const entries = ctx.sessionManager.getBranch?.() ?? ctx.sessionManager.getEntries();
+  const ids: string[] = [];
+  for (const entry of entries) {
+    const record = asRecord(entry);
+    if (record.type !== "custom" || record.customType !== SESSION_ENTRY_TYPE) continue;
+    const data = asRecord(record.data);
+    if (data.version !== SESSION_ENTRY_VERSION || typeof data.id !== "string") continue;
+    const id = data.id.trim();
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) continue;
+    if (Buffer.byteLength(JSON.stringify(data), "utf8") > MAX_PROVENANCE_BYTES) continue;
+    ids.push(id);
+  }
+
+  for (const id of ids.slice(-MAX_RESTORED_LAUNCHES)) {
+    try {
+      const asyncDir = await validatePathWithin(roots.asyncRoot, path.join(roots.asyncRoot, id), { mustExist: true, label: "restored asyncDir" });
+      if (path.basename(asyncDir) !== id) continue;
+      const trusted = trustedLaunches().get(trustedLaunchKey(workspaceRoot, session, id));
+      if (trusted) {
+        const rootsMatch = trusted.asyncRoot === roots.asyncRoot
+          && trusted.resultRoot === roots.resultRoot
+          && trusted.artifactRoots.length === roots.artifactRoots.length
+          && trusted.artifactRoots.every((root, index) => root === roots.artifactRoots[index])
+          && trusted.sessionRoots.length === roots.sessionRoots.length
+          && trusted.sessionRoots.every((root, index) => root === roots.sessionRoots[index]);
+        if (rootsMatch && trusted.workspaceRoot === workspaceRoot && sameSession(trusted.session, session) && trusted.asyncDir === asyncDir) {
+          store.launches.set(id, trusted);
+          await flushPendingForLaunch(pi, id);
+          continue;
+        }
+      }
+      // Session files are not integrity protected. A restart may restore only the
+      // lookup id; roots and workspace are re-derived, and checklist/task claims
+      // deliberately remain unavailable rather than trusted from persisted data.
+      store.launches.set(id, {
+        id,
+        asyncDir,
+        asyncRoot: roots.asyncRoot,
+        resultRoot: roots.resultRoot,
+        artifactRoots: roots.artifactRoots,
+        sessionRoots: roots.sessionRoots,
+        workspaceRoot,
+        runCwd: workspaceRoot,
+        session,
+        mode: "single",
+        tasks: [],
+        checklistProvenance: "unavailable-after-restart",
+      });
+      await flushPendingForLaunch(pi, id);
+    } catch {
+      // Missing, escaped, or stale native run directories fail closed.
+    }
+  }
+}
+
+export async function rememberDetachedLaunch(
+  pi: ExtensionAPI,
+  result: NativeResult,
+  tasks: TakomiUxTask[],
+  ctx: ExtensionContext,
+  workspaceRoot: string,
+  expectedRunCwd: string = workspaceRoot,
+): Promise<void> {
+  const id = typeof result.details?.asyncId === "string"
+    ? result.details.asyncId.trim()
+    : typeof result.details?.runId === "string" ? result.details.runId.trim() : "";
+  if (!id || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) throw new Error("Native async launch returned an invalid run id.");
+  if (result.details?.runId && result.details.runId !== id) throw new Error("Native async launch returned conflicting run ids.");
+  if (typeof result.details?.asyncDir !== "string") throw new Error("Native async launch did not return asyncDir provenance.");
+
+  const canonicalWorkspace = await canonicalExistingDirectory(workspaceRoot, "workspace root");
+  const runCwd = await canonicalExistingDirectory(expectedRunCwd, "run cwd");
+  if (!isPathInside(canonicalWorkspace, runCwd)) throw new Error("Native run cwd escapes the canonical workspace root.");
+  const session = await canonicalSessionIdentity(ctx);
+  const roots = await currentRoots(session, canonicalWorkspace);
+  const asyncRoot = roots.asyncRoot;
+  const resultRoot = roots.resultRoot;
+  const asyncDir = await validatePathWithin(asyncRoot, result.details.asyncDir, { mustExist: true, label: "launch asyncDir" });
+  if (path.basename(asyncDir) !== id) throw new Error("Native asyncDir does not exactly match the launched run id.");
+  const artifactRoots = roots.artifactRoots;
+  const launch: DetachedLaunch = {
+    id,
+    asyncDir,
+    asyncRoot,
+    resultRoot,
+    artifactRoots,
+    sessionRoots: roots.sessionRoots,
+    workspaceRoot: canonicalWorkspace,
+    runCwd,
+    session,
+    mode: result.details?.mode === "parallel" || result.details?.mode === "chain" ? result.details.mode : "single",
+    tasks: sanitizeUntrustedValue(tasks),
+    checklistProvenance: "trusted-launch",
+  };
+  if (!boundedLaunchEntry(launch)) throw new Error(`Detached launch provenance exceeds ${MAX_PROVENANCE_BYTES} bytes.`);
+  const store = storeFor(pi);
+  if (!store.identity || store.identity.workspaceRoot !== canonicalWorkspace || !sameSession(store.identity.session, session)) {
+    store.launches.clear();
+    store.completions.clear();
+    store.identity = { workspaceRoot: canonicalWorkspace, session };
+  }
+  store.launches.set(id, launch);
+  trustedLaunches().set(trustedLaunchKey(canonicalWorkspace, session, id), launch);
+  pi.appendEntry(SESSION_ENTRY_TYPE, launchEntryData(launch));
+  await flushPendingForLaunch(pi, id);
+}
+
+async function captureForKnownLaunch(pi: ExtensionAPI, data: unknown): Promise<{ launch?: DetachedLaunch; payload?: DetachedCompletionPayload; error?: string }> {
+  if (!data || typeof data !== "object") return { error: "completion payload is not an object" };
+  const payload = sanitizeUntrustedValue(data) as DetachedCompletionPayload;
+  const id = completionId(payload);
+  if (!id) return { error: "completion payload has missing or conflicting run ids" };
+  const launch = storeFor(pi).launches.get(id);
+  if (!launch) return { error: "completion run id is not an exact known launch" };
+  const identityError = await validatePayloadIdentity(launch, payload);
+  if (identityError) return { launch, error: identityError };
+  storeFor(pi).completions.set(id, payload);
+  return { launch, payload };
+}
+
+export async function captureDetachedCompletion(pi: ExtensionAPI, data: unknown): Promise<boolean> {
+  const captured = await captureForKnownLaunch(pi, data);
+  return Boolean(captured.payload);
+}
+
+function prunePending(store: DetachedStore, now = Date.now()): void {
+  store.pending = store.pending.filter((item) => now - item.receivedAt <= PENDING_COMPLETION_TTL_MS);
+  if (store.pending.length > MAX_PENDING_COMPLETIONS) store.pending.splice(0, store.pending.length - MAX_PENDING_COMPLETIONS);
+}
+
+function queuePendingCompletion(pi: ExtensionAPI, data: unknown): boolean {
+  if (!data || typeof data !== "object") return false;
+  try {
+    if (Buffer.byteLength(JSON.stringify(data), "utf8") > MAX_PENDING_COMPLETION_BYTES) return false;
+  } catch {
+    return false;
+  }
+  const payload = sanitizeUntrustedValue(data) as DetachedCompletionPayload;
+  const id = completionId(payload);
+  if (!id || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) return false;
+  if (!Array.isArray(payload.results) || payload.results.length === 0) return false;
+  if (typeof payload.sessionId !== "string" || typeof payload.cwd !== "string" || typeof payload.asyncDir !== "string") return false;
+  const store = storeFor(pi);
+  prunePending(store);
+  store.pending.push({ id, payload, receivedAt: Date.now() });
+  prunePending(store);
+  return true;
+}
+
+async function flushPendingForLaunch(pi: ExtensionAPI, id: string): Promise<void> {
+  const store = storeFor(pi);
+  prunePending(store);
+  const matches = store.pending.filter((item) => item.id === id);
+  store.pending = store.pending.filter((item) => item.id !== id);
+  for (const item of matches) await notifyDetachedCompletion(pi, item.payload, false);
+}
+
+export function clearDetachedResults(pi: ExtensionAPI): void {
+  const store = stores.get(pi);
+  if (store) {
+    for (const launch of store.launches.values()) {
+      const key = trustedLaunchKey(launch.workspaceRoot, launch.session, launch.id);
+      if (trustedLaunches().get(key) === launch) trustedLaunches().delete(key);
+    }
+    store.launches.clear();
+    store.completions.clear();
+    store.pending = [];
+    store.notified.clear();
+  }
+  stores.delete(pi);
+}
+
+function statusIdentityError(result: NativeResult, launch: DetachedLaunch): string | undefined {
+  const run = fieldFromContent(result, "Run");
+  if (!run || run !== launch.id) return "status payload run id does not exactly match the known launch";
+  const dir = fieldFromContent(result, "Dir");
+  if (dir && path.resolve(dir) !== launch.asyncDir) return "status payload asyncDir does not match the known launch";
+  return undefined;
+}
+
+function withHydrationState(nativeResult: NativeResult, launch: DetachedLaunch | undefined, state: string, error?: string): NativeResult {
+  return {
+    ...nativeResult,
+    details: {
+      ...(nativeResult.details ?? {}),
+      takomiDetachedHydration: {
+        state,
+        ...(launch ? { runId: launch.id } : {}),
+        ...(error ? { error: sanitizeUntrustedText(error) } : {}),
+      },
+    },
+  };
+}
+
+export async function resolveDetachedStatusResult(
+  pi: ExtensionAPI,
+  params: TakomiSubagentToolParams,
+  nativeResult: NativeResult,
+): Promise<NativeResult> {
+  const requested = params.id?.trim();
+  if (!requested) return nativeResult;
+  const store = storeFor(pi);
+  const launch = exactOrUniqueLaunch(store.launches, requested);
+  if (!launch) return withHydrationState(nativeResult, undefined, "rejected", "status id is unknown or prefix-ambiguous");
+  const statusError = statusIdentityError(nativeResult, launch);
+  if (statusError) return withHydrationState(nativeResult, launch, "rejected", statusError);
+
+  let payload = store.completions.get(launch.id);
+  if (!payload) {
+    const read = await readResultPayload(launch, resultPathForLaunch(launch, nativeResult));
+    if (!read.payload) return withHydrationState(nativeResult, launch, read.state, read.error);
+    const identityError = await validatePayloadIdentity(launch, read.payload);
+    if (identityError) return withHydrationState(nativeResult, launch, "rejected", identityError);
+    payload = read.payload;
+    store.completions.set(launch.id, payload);
+  }
+
+  const details = await normalizeDetachedCompletion(payload, launch);
+  if (!details) return withHydrationState(nativeResult, launch, "corrupt", "completion has no result children");
+  const rows = (details as any).results ?? [];
+  if (!rows.some((row: any) => finalAnswer(row).trim().length > 0)) {
+    return withHydrationState(nativeResult, launch, "missing", "completion has no useful final output");
+  }
+  return { ...nativeResult, details };
+}
+
+function notificationChecklist(details: Record<string, any>): string {
+  if (details.takomiDetached?.checklistProvenance === "unavailable-after-restart") {
+    return "Checklist unavailable after restart";
+  }
+  const rows = Array.isArray(details.results) ? details.results : [];
+  const tasks = Array.isArray(details.takomiUx?.tasks) ? details.takomiUx.tasks as TakomiUxTask[] : [];
+  const all = rows.flatMap((row: any, index: number) => resolvedChecklist(tasks[index]?.checklist ?? [], [row.finalOutput ?? ""]));
+  const done = all.filter((item) => item.done).length;
+  return `Checklist provenance: ${done}/${all.length}`;
+}
+
+function boundNotificationLine(value: string, maxCharacters: number): string {
+  const normalized = sanitizeUntrustedText(value).replace(/\s+/g, " ").trim();
+  const characters = [...normalized];
+  return characters.length <= maxCharacters ? normalized : `${characters.slice(0, Math.max(1, maxCharacters - 1)).join("")}…`;
+}
+
+function notificationAnswerParts(answers: string[]): { opening: string; remaining: string[] } {
+  const firstLines = answers[0]!.split(/\r?\n/);
+  const openingIndex = firstLines.findIndex((line) => line.trim().length > 0);
+  const rawOpening = openingIndex >= 0 ? firstLines[openingIndex]!.trim() : answers[0]!.trim();
+  const opening = boundNotificationLine(rawOpening, 240);
+  const firstRemaining = openingIndex >= 0
+    ? [...firstLines.slice(0, openingIndex), ...firstLines.slice(openingIndex + 1)].join("\n").trim()
+    : "";
+  return { opening, remaining: [firstRemaining, ...answers.slice(1)].filter((answer) => answer.trim().length > 0) };
+}
+
+function notificationFallback(details: Record<string, any>): string | undefined {
+  const rows = Array.isArray(details.results) ? details.results : [];
+  const fallbacks = rows.map((row: any) => row.takomiDetachedOutput as DetachedOutputProvenance | undefined)
+    .filter((item): item is DetachedOutputProvenance => item !== undefined && item.fallbackState !== "not-needed");
+  if (!fallbacks.length) return undefined;
+  const first = fallbacks[0]!;
+  return `output ${first.source} fallback: ${first.fallbackState}`;
+}
+
+function acceptanceLabel(details: Record<string, any>): string | undefined {
+  const statuses = [...new Set((details.results ?? []).map((row: any) => row.acceptance?.status).filter((value: unknown): value is string => typeof value === "string"))];
+  return statuses.length ? `acceptance ${statuses.join(", ")}` : undefined;
+}
+
+function pruneSeen(seen: Map<string, number>, now: number): void {
+  for (const [key, timestamp] of seen) if (now - timestamp > NOTIFY_TTL_MS) seen.delete(key);
+}
+
+function claimNativeCompletionKey(id: string): boolean {
+  const globalStore = globalThis as Record<string, unknown>;
+  const existing = globalStore[NATIVE_NOTIFY_SEEN_KEY];
+  const seen = existing instanceof Map ? existing as Map<string, number> : new Map<string, number>();
+  globalStore[NATIVE_NOTIFY_SEEN_KEY] = seen;
+  const now = Date.now();
+  pruneSeen(seen, now);
+  const key = `id:${id}`;
+  if (seen.has(key)) return false;
+  seen.set(key, now);
+  return true;
+}
+
+async function notifyDetachedCompletion(pi: ExtensionAPI, data: unknown, allowQueue = true): Promise<void> {
+  const captured = await captureForKnownLaunch(pi, data);
+  if (!captured.launch || !captured.payload) {
+    if (allowQueue && captured.error === "completion run id is not an exact known launch") queuePendingCompletion(pi, data);
+    return;
+  }
+  const details = await normalizeDetachedCompletion(captured.payload, captured.launch);
+  if (!details) return;
+  const rows = (details as any).results as any[];
+  const answers = rows.map((row) => finalAnswer(row)).filter((answer) => answer.trim().length > 0);
+  if (!answers.length) return;
+  const checklistProvenance = notificationChecklist(details as Record<string, any>);
+  const fallback = notificationFallback(details as Record<string, any>);
+  const acceptance = acceptanceLabel(details as Record<string, any>);
+  const answerParts = notificationAnswerParts(answers);
+  const firstLine = `${checklistProvenance} · ${answerParts.opening}`;
+  const remainingPreview = [
+    ...answerParts.remaining,
+    acceptance,
+    fallback ? `Fallback provenance: ${fallback}` : undefined,
+  ].filter((line): line is string => Boolean(line)).join("\n");
+  const resultPreview = [firstLine, remainingPreview || undefined].filter(Boolean).join("\n");
+  const status = captured.payload.state === "paused"
+    ? "paused"
+    : captured.payload.success === false || captured.payload.state === "failed" ? "failed" : "completed";
+  const agent = captured.payload.agent ?? (rows.map((row) => row.agent).filter(Boolean).join(", ") || "unknown");
+  if (!claimNativeCompletionKey(captured.launch.id)) return;
+  storeFor(pi).notified.add(captured.launch.id);
+  const content = [
+    `Background task ${status}: **${agent}**`,
+    "",
+    resultPreview,
+  ].join("\n");
+  pi.sendMessage({
+    customType: "subagent-notify",
+    content,
+    display: true,
+    details: {
+      agent,
+      status,
+      resultPreview,
+      durationMs: captured.payload.durationMs,
+    },
+  }, { triggerTurn: true });
+}
+
+/**
+ * Replace pi-subagents' notifier through its own reload-safe registration slot.
+ * The native message renderer remains authoritative; Takomi only enriches the
+ * one native custom message and claims the same shared completion dedupe key.
+ */
+export function registerDetachedCompletionNotifications(pi: ExtensionAPI): () => void {
+  const globalStore = globalThis as Record<string, unknown>;
+  const staleTakomiCleanup = globalStore[TAKOMI_NOTIFY_HANDLER_KEY];
+  if (typeof staleTakomiCleanup === "function") {
+    try { staleTakomiCleanup(); } catch {}
+  }
+  const previous = globalStore[NATIVE_NOTIFY_UNSUBSCRIBE_KEY];
+  if (typeof previous === "function") {
+    try { previous(); } catch {}
+  }
+
+  let active = true;
+  const unsubscribeEvent = pi.events.on("subagent:async-complete", (payload) => (
+    notifyDetachedCompletion(pi, payload).catch((error) => {
+      console.error("Takomi detached completion notification failed:", error);
+    })
+  ));
+  const softNativeSlot = () => {
+    // Native may register after Takomi. Let registration finish, then remove that
+    // duplicate handler and reclaim the shared slot while this handler survives.
+    queueMicrotask(() => {
+      if (!active) return;
+      const replacement = globalStore[NATIVE_NOTIFY_UNSUBSCRIBE_KEY];
+      if (replacement !== softNativeSlot && typeof replacement === "function") {
+        try { replacement(); } catch {}
+      }
+      if (active) globalStore[NATIVE_NOTIFY_UNSUBSCRIBE_KEY] = softNativeSlot;
+    });
+  };
+  const cleanup = () => {
+    if (!active) return;
+    active = false;
+    unsubscribeEvent();
+    const store = stores.get(pi);
+    if (store) store.pending = [];
+    if (globalStore[NATIVE_NOTIFY_UNSUBSCRIBE_KEY] === softNativeSlot) delete globalStore[NATIVE_NOTIFY_UNSUBSCRIBE_KEY];
+    if (globalStore[TAKOMI_NOTIFY_HANDLER_KEY] === cleanup) delete globalStore[TAKOMI_NOTIFY_HANDLER_KEY];
+  };
+  globalStore[TAKOMI_NOTIFY_HANDLER_KEY] = cleanup;
+  globalStore[NATIVE_NOTIFY_UNSUBSCRIBE_KEY] = softNativeSlot;
+  return cleanup;
+}