@bermudi/pi-delegate 0.1.1 → 0.1.3

package/extension.ts

@@ -19,61 +19,195 @@ import {
 import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
 import { invalidateHostDepsCache } from "./host.ts";
+import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
 import {
   activeTicketSummary,
   clearDelegateStatusContext,
   describeActiveTickets,
   guardSessionReplacement,
+  guardTreeNavigation,
   notifyActiveTicketsOnSettled,
   syncDelegateStatus,
 } from "./status.ts";
+import {
+  beginCall,
+  closeTelemetry,
+  getTelemetryGeneration,
+  prepareTelemetryForSession,
+  sealTelemetryWrites,
+} from "./telemetry.ts";
 import type { DelegateArguments } from "./types.ts";
 
+const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 10_000;
+let shutdownDrainTimeoutMs = DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
+
+type ShutdownDrainResult =
+  { drained: true; failures: unknown[] } | { drained: false; failures: [] };
+
+/** Wait for shutdown workers without allowing a stuck provider/tool to hold
+ * Pi's reload or exit hostage. The allSettled promise is intentionally left
+ * attached after timeout so a late rejection cannot become unhandled. */
+export async function drainAsyncTickets(
+  completions: readonly Promise<void>[],
+  timeoutMs = shutdownDrainTimeoutMs,
+): Promise<ShutdownDrainResult> {
+  if (!completions.length) return { drained: true, failures: [] };
+
+  const drain = Promise.allSettled(completions).then((results) => ({
+    drained: true as const,
+    failures: results
+      .filter(
+        (result): result is PromiseRejectedResult =>
+          result.status === "rejected",
+      )
+      .map((result) => result.reason),
+  }));
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<ShutdownDrainResult>((resolve) => {
+    timer = setTimeout(
+      () => resolve({ drained: false, failures: [] }),
+      timeoutMs,
+    );
+  });
+  const result = await Promise.race([drain, timeout]);
+  if (timer !== undefined) clearTimeout(timer);
+  return result;
+}
+
+/** Wait for another shutdown cleanup operation without allowing a stuck
+ * session lock to hold reload/quit forever. Rejection is consumed here; the
+ * caller reports it when it wins the race, and a late rejection stays handled.
+ */
+async function boundedShutdownCleanup(
+  cleanup: Promise<void>,
+  timeoutMs = shutdownDrainTimeoutMs,
+): Promise<"settled" | "timed-out" | "failed"> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const outcome = cleanup.then(
+    () => "settled" as const,
+    () => "failed" as const,
+  );
+  const timeout = new Promise<"timed-out">((resolve) => {
+    timer = setTimeout(() => resolve("timed-out"), timeoutMs);
+  });
+  const result = await Promise.race([outcome, timeout]);
+  if (timer !== undefined) clearTimeout(timer);
+  return result;
+}
+
+/** @internal Test-only timeout override. */
+export function _setShutdownDrainTimeoutForTesting(
+  timeoutMs: number | undefined,
+): void {
+  shutdownDrainTimeoutMs = timeoutMs ?? DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
+}
+
 /** Register the delegate tool and clean up its parent-session resources. */
 export default function delegateExtension(pi: ExtensionAPI): void {
+  // A /reload can reuse this module instance after the previous runtime closed
+  // its SQLite handle. Permit the new runtime to open a fresh backend; stale
+  // workers from the old runtime remain blocked from reopening it.
+  prepareTelemetryForSession();
+
   pi.registerTool({
     name: "delegate",
     label: "Delegate to Subagents",
     description:
-      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async returns a ticket.",
+      "Run parallel subagents via tasks:[{prompt}]. Sync returns results; async=ticket. tasks:[]=full manual.",
     parameters: delegateArgumentsSchema,
     // Runs before schema validation — recovers stringified `tasks` arrays
     // (a common model mistake that would otherwise be rejected upstream).
     prepareArguments: normalizeDelegateArguments,
 
     async execute(_id, params: DelegateArguments, signal, onUpdate, ctx) {
+      const parentModelId = ctx.model?.id;
+      const tasks = params.tasks ?? [];
+      const parentSessionFile = (
+        ctx as { sessionManager?: { getSessionFile?(): string | undefined } }
+      ).sessionManager?.getSessionFile?.();
+
+      let mode: string;
+      if (params.ticketAction) {
+        mode = params.ticketAction;
+      } else if (tasks.length === 0) {
+        mode = "manual";
+      } else if (params.async) {
+        mode = "async";
+      } else {
+        mode = "sync";
+      }
+      const taskCount = params.ticketAction ? 0 : tasks.length;
+      const callSpan = beginCall({
+        parentModel: parentModelId,
+        mode,
+        taskCount,
+        parentSessionFile,
+      });
+
+      function failCall(): void {
+        callSpan.finish({
+          status: "failed",
+          totalTokens: 0,
+          totalCost: 0,
+          wallMs: Date.now() - callSpan.startedAt,
+        });
+      }
+
+      function succeedCall(): void {
+        callSpan.finish({
+          status: "success",
+          totalTokens: 0,
+          totalCost: 0,
+          wallMs: Date.now() - callSpan.startedAt,
+        });
+      }
+
       // Guard against pi dropping/renaming a symbol this extension imports
       // before any operation-specific validation or early return.
       const compatError = hostCompatError();
-      if (compatError) return compatError;
-
-      const parentModelId = ctx.model?.id;
-      const tasks = params.tasks ?? [];
+      if (compatError) {
+        failCall();
+        return compatError;
+      }
 
       const operationResult = validateDelegateOperationResult(
         params,
         parentModelId,
       );
-      if (operationResult) return operationResult;
+      if (operationResult) {
+        failCall();
+        return operationResult;
+      }
 
       // ── Poll action ───────────────────────────────────────────────────
-      if (params.action === "poll") {
-        return handlePoll(params, ctx);
+      if (params.ticketAction === "poll") {
+        const result = handlePoll(params, ctx);
+        succeedCall();
+        return result;
       }
 
       // ── Cancel action ─────────────────────────────────────────────────
-      if (params.action === "cancel") {
+      if (params.ticketAction === "cancel") {
         const result = handleCancel(params);
         // A forced cancel flips the ticket to "cancelling" — keep the
         // footer status in step (deduped; the preview path is a no-op).
         syncDelegateStatus(ctx);
+        succeedCall();
         return result;
       }
 
       // ── Wait action ────────────────────────────────────────────────────
-      if (params.action === "wait") {
-        return handleWait(params, signal, onUpdate, ctx);
+      if (params.ticketAction === "wait") {
+        try {
+          const result = await handleWait(params, signal, onUpdate, ctx);
+          succeedCall();
+          return result;
+        } catch (err) {
+          failCall();
+          throw err;
+        }
       }
 
       // Agent discovery is intentionally parent-cwd-scoped: agent profiles are a
@@ -85,6 +219,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
 
       // ── Help mode ─────────────────────────────────────────────────
       if (!tasks.length) {
+        succeedCall();
         return {
           content: [{ type: "text", text: getSubagentManualMarkdown(agents) }],
           details: {
@@ -106,25 +241,38 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       // across dispatches: edits to auth/models/settings/context files must be
       // visible without restarting Pi.
       invalidateHostDepsCache();
-      return dispatchDelegate({
-        pi,
-        params,
-        ctx,
-        agents,
-        parentModelId,
-        parentDefaults: {
-          thinking: pi.getThinkingLevel(),
-          tools: pi.getActiveTools(),
-        },
-        signal,
-        onUpdate,
-      });
+      try {
+        return await dispatchDelegate({
+          pi,
+          params,
+          ctx,
+          agents,
+          parentModelId,
+          parentDefaults: {
+            thinking: pi.getThinkingLevel(),
+            tools: pi.getActiveTools(),
+          },
+          signal,
+          onUpdate,
+          callSpan,
+        });
+      } catch (err) {
+        failCall();
+        throw err;
+      }
     },
 
     renderCall: renderDelegateCall,
     renderResult: renderDelegateResult,
   });
 
+  // A reload may rebuild the extension runtime without re-invoking this
+  // module's default export. Re-open telemetry only after the prior shutdown
+  // handler has drained old workers and closed its connection.
+  pi.on("session_start", () => {
+    prepareTelemetryForSession();
+  });
+
   // ── Background-work visibility (see status.ts) ──────────────────────────
   // The turn settling with live tickets is the "looks idle but isn't" moment:
   // warn once per ticket. The footer status carries it from there.
@@ -140,51 +288,150 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     guardSessionReplacement(ctx, "fork"),
   );
 
+  // /tree navigation stays inside the same session: nothing is torn down and
+  // live tickets keep running, but their results would land on the branch the
+  // user moves to. Ask first, and record the new leaf either way so delivery
+  // can detect the mismatch (issue #30). `session_tree` also fires for
+  // extension-driven ctx.navigateTree, which never reaches the guard.
+  pi.on("session_before_tree", (_event, ctx) => guardTreeNavigation(ctx));
+  pi.on("session_tree", (event, ctx) => {
+    recordTreeNavigation(event.newLeafId);
+    syncDelegateStatus(ctx);
+  });
+
   // ── Session shutdown: abort tickets and dispose live pooled sessions ──
   pi.on("session_shutdown", async (event, ctx) => {
-    // Quit and /reload kill background work with no cancellable hook, so
-    // leave a trace. For quit the TUI is already stopped — stderr lands in
-    // the scrollback. For reload the TUI survives — warn in place. Switch
-    // and fork already passed the confirm guard above.
-    const active = activeTicketSummary();
-    if (active.tickets.length) {
-      if (event.reason === "quit") {
+    const shutdownGeneration = getTelemetryGeneration();
+    const shutdownDeadline = Date.now() + shutdownDrainTimeoutMs;
+    const ticketCompletions: Promise<void>[] = [];
+    let drainAttempted = false;
+    let telemetrySealed = false;
+
+    try {
+      // Quit and /reload kill background work with no cancellable hook, so
+      // leave a trace. For quit the TUI is already stopped — stderr lands in
+      // the scrollback. For reload the TUI survives — warn in place. Switch
+      // and fork already passed the confirm guard above.
+      const active = activeTicketSummary();
+      if (active.tickets.length) {
+        if (event.reason === "quit") {
+          console.error(
+            `[delegate] pi exited with ${describeActiveTickets(active)} — aborted.`,
+          );
+        } else if (event.reason === "reload") {
+          try {
+            ctx.ui.notify(
+              `[delegate] reload aborted ${describeActiveTickets(active)}`,
+              "warning",
+            );
+          } catch (error) {
+            console.error(
+              "[delegate] reload shutdown notification failed",
+              error,
+            );
+          }
+        }
+      }
+
+      for (const ticket of ticketRegistry.values()) {
+        if (ticket.status === "running" || ticket.status === "cancelling") {
+          cancelTicketForShutdown(ticket);
+        }
+        // Include already-cancelled tickets too: a repeated shutdown event can
+        // race the first handler while its workers are still unwinding.
+        if (ticket.completion) ticketCompletions.push(ticket.completion);
+      }
+      syncDelegateStatus(ctx);
+      // The runtime is invalidated right after this handler returns; aborted
+      // tickets keep unwinding asynchronously and must find no cached ctx (or
+      // captured pi) to touch. The cancelled completion path still writes one
+      // final aggregate after late task results arrive, but never delivers UI.
+      clearDelegateStatusContext();
+      // A replacement session starts on its own leaf; stale tracking would make
+      // every ticket look cross-leaf (or, worse, look same-leaf by accident).
+      resetLeafTracking();
+      // Do NOT clear the ticket registry here — completed tickets are retained
+      // until their TTL cleanup. Pooled AgentSessions, however, own listeners
+      // and must be disposed before the parent session exits.
+      //
+      // Start pooled cleanup before waiting for ticket completion. Its immediate
+      // abort requests can help a worker blocked on a pooled session unwind;
+      // SQLite still stays open until both cleanup paths finish.
+      let poolCleanup: Promise<void>;
+      try {
+        poolCleanup = closeAllPooledAgents();
+      } catch (error) {
+        console.error("[delegate] pooled-session shutdown start failed", error);
+        poolCleanup = Promise.resolve();
+      }
+      // Drain cooperatively, but never let a provider/tool hold reload or
+      // quit forever. A timed-out old runtime is sealed before a new one can
+      // reopen telemetry; its eventual task completion remains harmless.
+      drainAttempted = true;
+      const drain = await drainAsyncTickets(
+        ticketCompletions,
+        Math.max(0, shutdownDeadline - Date.now()),
+      );
+      if (!drain.drained) {
         console.error(
-          `[delegate] pi exited with ${describeActiveTickets(active)} — aborted.`,
+          `[delegate] async-ticket shutdown drain exceeded ${shutdownDrainTimeoutMs}ms; continuing without late results`,
         );
-      } else if (event.reason === "reload") {
-        ctx.ui.notify(
-          `[delegate] reload aborted ${describeActiveTickets(active)}`,
-          "warning",
+        // Seal immediately, before waiting on pooled-session cleanup. A worker
+        // that finishes during that second phase belongs to the old runtime
+        // and must not write into a freshly reopened backend.
+        telemetrySealed = sealTelemetryWrites(shutdownGeneration);
+      } else if (drain.failures.length) {
+        console.error(
+          "[delegate] async-ticket cleanup failed during shutdown:",
+          drain.failures,
         );
       }
-    }
-    for (const ticket of ticketRegistry.values()) {
-      cancelTicketForShutdown(ticket);
-    }
-    syncDelegateStatus(ctx);
-    // The runtime is invalidated right after this handler returns; aborted
-    // tickets keep unwinding asynchronously and must find no cached ctx (or
-    // captured pi) to touch. See the "cancelled"-at-entry guard in dispatch.
-    clearDelegateStatusContext();
-    // Do NOT clear the ticket registry here — completed tickets are retained
-    // until their TTL cleanup. Pooled AgentSessions, however, own listeners
-    // and must be disposed before the parent session exits.
-    //
-    // closeAllPooledAgents attempts every session (Promise.allSettled) before
-    // aggregating failures into an AggregateError, so swallowing here does not
-    // abandon remaining cleanup. Catch and log so a wedged session's failure
-    // stays observable instead of becoming an unhandled rejection — pi.on is
-    // EventEmitter-style and does not surface handler rejections — and so
-    // shutdown completes even when one pooled session failed to abort/dispose.
-    try {
-      await closeAllPooledAgents();
-    } catch (error) {
-      const failures = error instanceof AggregateError ? error.errors : [error];
-      console.error(
-        "[delegate] pooled-session cleanup failed during shutdown:",
-        failures,
+
+      // closeAllPooledAgents attempts every session (Promise.allSettled) before
+      // aggregating failures into an AggregateError, so swallowing here does
+      // not abandon remaining cleanup.
+      const poolResult = await boundedShutdownCleanup(
+        poolCleanup,
+        Math.max(0, shutdownDeadline - Date.now()),
       );
+      if (poolResult === "timed-out") {
+        console.error(
+          `[delegate] pooled-session shutdown cleanup exceeded ${shutdownDrainTimeoutMs}ms; continuing`,
+        );
+      } else if (poolResult === "failed") {
+        // closeAllPooledAgents aggregates every session failure before
+        // rejecting, so the rejection is already a complete diagnostic.
+        try {
+          await poolCleanup;
+        } catch (error) {
+          const failures =
+            error instanceof AggregateError ? error.errors : [error];
+          console.error(
+            "[delegate] pooled-session cleanup failed during shutdown:",
+            failures,
+          );
+        }
+      }
+    } catch (error) {
+      // pi.on is EventEmitter-style and does not surface handler rejections.
+      // Keep shutdown moving, but leave the failure visible.
+      console.error("[delegate] shutdown cleanup failed", error);
+    } finally {
+      if (!drainAttempted) {
+        // An unexpected earlier cleanup failure must not leave a worker with an
+        // unhandled rejection, but this fallback is bounded too.
+        await drainAsyncTickets(
+          ticketCompletions,
+          Math.max(0, shutdownDeadline - Date.now()),
+        );
+      }
+      // Once the bounded drain expires, old workers may still unwind. Seal
+      // their generation before closing SQLite so a later runtime cannot
+      // receive stale task/call writes.
+      if (!telemetrySealed) {
+        telemetrySealed = sealTelemetryWrites(shutdownGeneration);
+      }
+      closeTelemetry(shutdownGeneration);
     }
   });
 }

package/file-tracking.ts

@@ -2,9 +2,19 @@ import { execFile } from "node:child_process";
 import * as path from "node:path";
 import type { ToolActivity } from "./types.ts";
 
-/** Return absolute paths reported as changed by Git in the task cwd.
- * Git failures degrade to an empty set because file tracking is observational. */
-export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
+/**
+ * Return absolute paths reported as changed by Git in the task cwd.
+ *
+ * Touched-file tracking is best-effort, not authoritative. On success this
+ * returns the set of changed paths (possibly empty for a clean repo). On
+ * failure (non-git directory, git unavailable, timeout) it returns `undefined`
+ * so callers can tell "git failed" from "clean repo". A failed baseline
+ * suppresses git-based attribution in the runner; only explicit edit/write tool
+ * activity is captured by {@link extractTouchedFromActivities}.
+ */
+export async function getGitChangedFiles(
+  cwd: string,
+): Promise<Set<string> | undefined> {
   try {
     const runGit = (args: string[]) =>
       new Promise<string>((resolve, reject) => {
@@ -37,11 +47,22 @@ export async function getGitChangedFiles(cwd: string): Promise<Set<string>> {
     }
     return files;
   } catch {
-    return new Set();
+    return undefined;
   }
 }
 
-/** Extract file paths mutated by edit/write from the activity log. */
+/**
+ * Extract file paths from explicit edit/write tool calls in the activity log.
+ *
+ * This is the reliable, activity-based contribution to touched-file tracking.
+ * Only completed, successful tool calls are counted: an activity must have a
+ * terminal `result` and `result.isError` must be false. Interrupted or in-flight
+ * calls (no `result`) and failed calls (`result.isError` true) are skipped,
+ * because they did not actually mutate the file. bash mutations are NOT captured
+ * here; they are only captured by git diff when the task cwd is inside a git
+ * repo with git available. The combined touchedFiles list is therefore a lower
+ * bound: absence does not mean a file was unchanged.
+ */
 export function extractTouchedFromActivities(
   activities: ToolActivity[],
   cwd: string,
@@ -49,6 +70,7 @@ export function extractTouchedFromActivities(
   const files = new Set<string>();
   for (const a of activities) {
     if (a.name !== "edit" && a.name !== "write") continue;
+    if (!a.result || a.result.isError) continue;
     const raw = a.args?.path ?? a.args?.file_path ?? a.args?.filePath;
     if (typeof raw !== "string" || !raw) continue;
     files.add(path.resolve(cwd, raw));

package/format.ts

@@ -185,6 +185,11 @@ export function trunc(s: string, n: number): string {
   return s.length <= n ? s : s.slice(0, n - 1) + "…";
 }
 
+/** Render an optional task `id` in a compact, visually distinct form. */
+export function formatTaskId(id: string | undefined): string {
+  return id ? ` #${id}` : "";
+}
+
 /**
  * Extract a single-line preview of agent output for collapsed final display.
  *
@@ -340,7 +345,7 @@ function isResumableSessionFile(sessionFile: string): boolean {
  * path that didn't exist on disk.
  *
  * Emits:
- *   [FAILED|ABORTED: <error> · session: <shortpath> · touched: <files>]
+ *   [FAILED|ABORTED: <error> · session: <shortpath> · touched (best-effort): <files>]
  *   <partial output, when available>
  *   → To retry: delegate({ tasks: [{ resumeFrom: "<path>", prompt: "continue" }] })
  *
@@ -351,12 +356,12 @@ function isResumableSessionFile(sessionFile: string): boolean {
  */
 export function formatFailedTask(r: TaskResult, cwd?: string): string[] {
   const parts: string[] = [];
-  const isAbort = /abort/i.test(r.error ?? "");
+  const isAbort = r.error === "Aborted";
   // Empty string is falsy but not nullish — `||` covers both undefined and "".
   const failParts = [r.error || "unknown error"];
   if (r.sessionFile) failParts.push(`session: ${shortenPath(r.sessionFile)}`);
   const touched = cwd ? relativeTouchedSummary(r.touchedFiles, cwd) : null;
-  if (touched) failParts.push(`touched: ${touched}`);
+  if (touched) failParts.push(`touched (best-effort): ${touched}`);
   parts.push(`[${isAbort ? "ABORTED" : "FAILED"}: ${failParts.join(" · ")}]`);
 
   // Surface partial assistant output even when the task did not complete.
@@ -398,7 +403,7 @@ export function formatFailedTask(r: TaskResult, cwd?: string): string[] {
  * Emits:
  *   === <agent>: <truncated prompt> ===
  *   [WARNING: <w>]  (per warning, if any)
- *   [FAILED: ...] / [OK | <duration> | <tokens> tokens · <sessionFile> · touched: <files>]
+ *   [FAILED: ...] / [OK | <duration> | <tokens> tokens · <sessionFile> · touched (best-effort): <files>]
  *
  *   <output>  (success body only)
  *
@@ -410,10 +415,10 @@ export function formatCompletedTask(
   result: TaskResult,
 ): string[] {
   const parts: string[] = [];
-  // `|| task.action` covers action-only tasks (close/list/...) where prompt is
+  // `|| task.sessionAction` covers action-only tasks (close/list/...) where prompt is
   // empty. Async prompt tasks always set prompt, so this is a no-op there.
   parts.push(
-    `=== ${result.agent}: ${trunc(task.prompt || task.action || "", 80)} ===`,
+    `=== ${result.agent}${formatTaskId(result.id ?? task.id)}: ${trunc(task.prompt || task.sessionAction || "", 80)} ===`,
   );
   if (task.warnings?.length) {
     for (const w of task.warnings) parts.push(`[WARNING: ${w}]`);
@@ -426,7 +431,7 @@ export function formatCompletedTask(
     ];
     if (result.sessionFile) meta.push(shortenPath(result.sessionFile));
     const touched = relativeTouchedSummary(result.touchedFiles, task.cwd);
-    if (touched) meta.push(`touched: ${touched}`);
+    if (touched) meta.push(`touched (best-effort): ${touched}`);
     parts.push(
       `[${meta.join(" · ")}]\n\n${renderOutputForLLM(result.output, result.agent)}`,
     );
@@ -504,3 +509,37 @@ export function relativeTouchedSummary(
     .filter((f) => f && !f.startsWith(".."));
   return rel.length ? rel.join(", ") : null;
 }
+
+/** Find absolute paths directly attributed to more than one task result.
+ *
+ *  Overlap is computed from {@link TaskResult.attributedFiles} (edit/write
+ *  tool calls), not from {@link TaskResult.touchedFiles}, so concurrent tasks
+ *  in the same repository do not fabricate false conflicts from shared
+ *  repository-wide git snapshots. */
+export function findTouchedOverlaps(
+  results: readonly { attributedFiles?: string[] }[],
+): string[] {
+  const counts = new Map<string, number>();
+  for (const r of results) {
+    for (const f of r.attributedFiles ?? []) {
+      counts.set(f, (counts.get(f) ?? 0) + 1);
+    }
+  }
+  return [...counts.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([file]) => file)
+    .sort();
+}
+
+/**
+ * Format a post-dispatch overlap warning, or null when there is no overlap.
+ *
+ * The warning is deliberately conservative: it only reports paths that two or
+ * more tasks claimed to touch. It does NOT claim that disjoint touchedFiles
+ * mean there was no conflict, and it does NOT claim filesystem isolation or
+ * rollback.
+ */
+export function formatTouchedOverlapWarning(overlaps: string[]): string | null {
+  if (!overlaps.length) return null;
+  return `WARNING: These tasks reported touching the same file(s): ${overlaps.join(", ")}. Delegate does not isolate or serialize file access and does not roll back completed writes.`;
+}

package/leaf.ts

@@ -0,0 +1,48 @@
+/**
+ * Session-tree leaf affinity for async tickets.
+ *
+ * An async ticket outlives the turn that spawned it. `/tree` navigation moves
+ * the session to a different leaf **within the same session file**: no
+ * `session_shutdown` fires, the extension runtime stays live, and the ticket
+ * keeps running. When it finishes, `deliverTicketResults` wakes the agent at
+ * whatever leaf is active *now* — which may be a branch that knows nothing
+ * about the task. See GitHub issue #30.
+ *
+ * pi exposes no "what leaf am I on?" query, so the current leaf has to be
+ * tracked from the `session_tree` event (`newLeafId`). That event also fires
+ * for extension-driven `ctx.navigateTree`, so this tracking covers navigation
+ * that never passed the `session_before_tree` confirm guard.
+ *
+ * State is runtime-scoped: `resetLeafTracking()` on session shutdown, since a
+ * replacement session starts on its own (unknown) leaf.
+ */
+import type { AsyncTicket } from "./types.ts";
+
+/** Leaf the session is currently on. `undefined` means no navigation has been
+ *  observed by this runtime — i.e. the leaf the session opened on. */
+let currentLeafId: string | null | undefined;
+
+/** Record a completed `/tree` navigation. */
+export function recordTreeNavigation(newLeafId: string | null): void {
+  currentLeafId = newLeafId;
+}
+
+/** Leaf id to stamp on a ticket at spawn time. */
+export function getCurrentLeafId(): string | null | undefined {
+  return currentLeafId;
+}
+
+export function resetLeafTracking(): void {
+  currentLeafId = undefined;
+}
+
+/** True when the session has navigated away from the leaf that spawned this
+ *  ticket, so delivering its result would wake the agent on a foreign branch.
+ *
+ *  Navigating away and back to the spawn leaf yields a fresh leaf id and is
+ *  therefore reported as cross-leaf. That false positive is deliberate: the
+ *  cross-leaf path only downgrades delivery to non-waking, and reconstructing
+ *  true leaf identity across a round trip is not worth the complexity. */
+export function isCrossLeafTicket(ticket: AsyncTicket): boolean {
+  return ticket.spawnLeafId !== currentLeafId;
+}