@bermudi/pi-delegate 0.1.13 → 0.1.14

package/tickets.ts

@@ -94,8 +94,13 @@ export const ticketRegistry = new TicketRegistry();
 
 /** Generate a short human-copyable identifier for an async ticket. */
 export function generateTicketId(): string {
-  // 8-char alphanumeric, no lookalikes
-  return Math.random().toString(36).slice(2, 10);
+  // Retry on the extremely unlikely collision rather than allowing Map.set()
+  // in dispatch to replace a still-retained ticket.
+  let id: string;
+  do {
+    id = Math.random().toString(36).slice(2, 10);
+  } while (!id || ticketRegistry.has(id));
+  return id;
 }
 
 /** Remove completed tickets after their retention TTL. Running tickets have no
@@ -220,13 +225,19 @@ export function resolveFinalTicketStatus(
 export function formatCompletedTicket(
   ticket: AsyncTicket,
 ): AgentToolResult<DelegateDetails> {
+  // Shutdown can make a ticket terminal while its workers are still unwinding.
+  // Do not freeze that partial projection: late TaskResults must appear in a
+  // later poll once the worker-settled barrier has resolved. Tickets created
+  // before this marker existed (including simple fixtures) are already safe to
+  // memoize because only live async dispatches explicitly set it false.
+  const canMemoize = ticket.workersSettled !== false;
+  if (canMemoize && ticket.formattedResult) return ticket.formattedResult;
+
   const parts: string[] = [];
   const succeeded = ticket.results.filter(
     (r) => r && !("error" in r && r.error),
   ).length;
-  const elapsedTotal = ticket.completedAt
-    ? ticket.completedAt - ticket.created
-    : 0;
+  const elapsedTotal = (ticket.completedAt ?? Date.now()) - ticket.created;
   // Surface the overall ticket status so a failed/cancelled batch is not
   // mistaken for success. "done" tickets keep the original header; others
   // get an explicit status tag up front.
@@ -280,7 +291,7 @@ export function formatCompletedTicket(
     );
   }
 
-  return {
+  const formatted: AgentToolResult<DelegateDetails> = {
     content: [{ type: "text", text: parts.join("\n\n") }],
     details: {
       tasks: ticket.tasks,
@@ -297,10 +308,13 @@ export function formatCompletedTicket(
       // the human sees which ticket they polled, even in the rich tree path.
       ticketId: ticket.id,
       status: ticket.status,
+      elapsedMs: elapsedTotal,
       overlapWarning: overlapWarning || undefined,
       dispatchWarning: ticket.dispatchWarning,
     },
   };
+  if (canMemoize) ticket.formattedResult = formatted;
+  return formatted;
 }
 
 // ── Waiter helpers ─────────────────────────────────────────────────────────
@@ -340,6 +354,7 @@ function buildWaitDetails(ticket: AsyncTicket): DelegateDetails {
     parentModel: ticket.parentModelId,
     ticketId: ticket.id,
     status: ticket.status,
+    elapsedMs: (ticket.completedAt ?? Date.now()) - ticket.created,
     overlapWarning: overlapWarning || undefined,
     dispatchWarning: ticket.dispatchWarning,
   };
@@ -427,6 +442,9 @@ function settleWaiter(
   if (w.settled) return;
   w.settled = true;
   w.clearDeadline?.();
+  w.clearDeadline = undefined;
+  w.removeAbortListener?.();
+  w.removeAbortListener = undefined;
   w.resolve(result);
 }
 
@@ -573,6 +591,7 @@ export function deliverTicketResults(
           ...formatted.details,
           ticketId: ticket.id,
           status: ticket.status,
+          crossLeafDelivery: crossLeaf,
         },
       },
       crossLeaf
@@ -626,6 +645,7 @@ export function handlePoll(
         // (friction #2). The LLM-facing content still names the ticket id too.
         ticketId: ticket.id,
         status: ticket.status,
+        elapsedMs: Date.now() - ticket.created,
         overlapWarning: snapshot.overlapWarning || undefined,
         dispatchWarning: ticket.dispatchWarning,
       },
@@ -747,13 +767,13 @@ export function handleWait(
     };
 
     if (signal) {
-      signal.addEventListener(
-        "abort",
-        () => {
-          abortWaiter(waiter, ticket);
-        },
-        { once: true },
-      );
+      const onAbort = () => {
+        abortWaiter(waiter, ticket);
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      waiter.removeAbortListener = () => {
+        signal.removeEventListener("abort", onAbort);
+      };
     }
 
     if (

package/tools.ts

@@ -35,10 +35,11 @@ const PROVIDER_TOOLS: Readonly<Record<string, readonly string[]>> = {
 };
 
 export function availableToolNames(modelProvider?: string): string[] {
-  return [
-    ...Object.keys(TOOL_FACTORIES),
-    ...(modelProvider ? (PROVIDER_TOOLS[modelProvider] ?? []) : []),
-  ];
+  const providerTools =
+    modelProvider && Object.hasOwn(PROVIDER_TOOLS, modelProvider)
+      ? PROVIDER_TOOLS[modelProvider]
+      : undefined;
+  return [...Object.keys(TOOL_FACTORIES), ...(providerTools ?? [])];
 }
 
 /** Expand tool-group shorthands (`*`, `ro`) into concrete tool lists.

package/types.ts

@@ -70,6 +70,7 @@ export interface TicketWaiter {
   resolve: (result: AgentToolResult<DelegateDetails>) => void;
   reject: (reason: unknown) => void;
   clearDeadline?: () => void;
+  removeAbortListener?: () => void;
   settled: boolean;
 }
 
@@ -112,6 +113,10 @@ export interface AsyncTicket {
   /** Immutable dispatch-scoped delegate.json snapshot used by async workers and
    *  later result formatting. */
   config?: import("./config.ts").DelegateConfig;
+  /** Memoized terminal projection, populated only after workers settle. Besides
+   * avoiding repeated work, this keeps repeated poll/wait calls from creating
+   * duplicate output spill files without freezing a shutdown-time partial result. */
+  formattedResult?: AgentToolResult<DelegateDetails>;
 }
 
 /** Live parent settings captured when a delegate call starts. The built-in
@@ -156,10 +161,45 @@ export interface ResolvedTask {
   providerExtensionSources?: string;
 }
 
+export interface FileAttributionPathSignature {
+  /** Absolute component inspected while resolving the pre-execution target. */
+  path: string;
+  /** Filesystem identity. Strings avoid precision loss on platforms whose
+   * inode/device values exceed JavaScript's safe integer range. */
+  dev: string;
+  ino: string;
+  birthtimeMs: number;
+  kind: "directory" | "symlink" | "other";
+  /** Exact link text, present only for symlinks. */
+  symlinkTarget?: string;
+}
+
+export interface FileAttribution {
+  /** Absolute path spelled by the tool call. This remains associated with the
+   * physical snapshot so a later symlink cannot change what the call targeted. */
+  lexicalPath: string;
+  /** Physical target captured synchronously at tool_execution_start. Consumers
+   * must not resolve this path again against the mutable post-execution tree. */
+  preExecutionPhysicalPath?: string;
+  /** Identity/signature chain used to obtain the physical snapshot. It covers
+   * every existing resolved component, including the leaf, plus the exact text
+   * of each followed symlink. In-place mutation preserves the leaf identity;
+   * replacement makes attribution uncertain. */
+  preExecutionPathSignatures?: FileAttributionPathSignature[];
+  /** Which explicit native tool supplied this evidence. */
+  provenance: "edit" | "write";
+  /** Canonicalization was incomplete, ambiguous, or its signature chain changed
+   * after execution. Such evidence is retained conservatively even when its
+   * lexical path is in a disposable workspace. */
+  uncertain: boolean;
+}
+
 export interface ToolActivity {
   id: string;
   name: string;
   args: Record<string, unknown>;
+  /** Structured edit/write attribution captured before execution. */
+  fileAttribution?: FileAttribution;
   result?: {
     content: Array<{ type: string; text?: string }>;
     isError: boolean;
@@ -171,6 +211,8 @@ export interface ToolActivity {
 }
 
 /** Stable machine-readable reason for a task failure.
+ *  - `cancelled`: the caller or async-ticket controller requested cancellation.
+ *    This must not be inferred from provider error text such as "Aborted".
  *  - `stalled`: inactivity watchdog fired; the prompt was cooperatively aborted.
  *  - `model_error`: the failure is attributable to the resolved model/provider
  *    (account usage limit, quota exhausted, auth lost) — not transient for that
@@ -179,7 +221,8 @@ export interface ToolActivity {
  *  - `deadline_exceeded`: the task's `deadlineMs` wall-clock budget expired
  *    (measured from when the task left the concurrency queue). The prompt was
  *    cooperatively aborted; completed side effects are not rolled back. */
-export type TaskFailureKind = "stalled" | "model_error" | "deadline_exceeded";
+export type TaskFailureKind =
+  "cancelled" | "stalled" | "model_error" | "deadline_exceeded";
 
 export interface TaskProgress {
   id?: string;
@@ -192,6 +235,8 @@ export interface TaskProgress {
   toolUses: number;
   error?: string;
   failureKind?: TaskFailureKind;
+  /** Terminal lower-bound result returned after quiescence abandonment. */
+  incomplete?: "quiescence_abandoned";
   model?: string;
   lastActivityAt?: number;
   activities: ToolActivity[];
@@ -208,6 +253,10 @@ export interface DelegateDetails {
   ticketId?: string;
   /** Terminal/live ticket status when this result comes from an async ticket. */
   status?: AsyncTicket["status"];
+  /** Actual batch wall time for stable rendering outside the live tool context. */
+  elapsedMs?: number;
+  /** Async result arrived on a different session-tree leaf than it was spawned on. */
+  crossLeafDelivery?: boolean;
   /** Global overlap warning derived from result.attributedFiles, surfaced in both
    *  the textual content and the custom TUI. */
   overlapWarning?: string;
@@ -222,19 +271,24 @@ export interface TaskResult {
   error?: string;
   /** Stable machine-readable failure reason; error remains human-facing. */
   failureKind?: TaskFailureKind;
+  /** The task returned while its quarantined AgentSession could still run.
+   * Output, file evidence, token usage, and cost are lower bounds rather than
+   * final accounting. */
+  incomplete?: "quiescence_abandoned";
   durationMs: number;
   /** Display token count for the task, derived from the compaction-inclusive
    *  session-stat delta. This matches `usage.totalTokens`; the usage object
    *  additionally preserves the provider breakdown and cost. */
   tokens: number;
-  /** Full provider Usage consumed by this task, including compacted-away
-   *  history. Always present (`emptyUsage()` on no-op/early-failure paths) so a
-   *  sync delegate call can fold subagent spend into the parent's session
-   *  total. Aggregate `cost.total` is accurate; the per-component cost fields
-   *  stay 0 because `getSessionStats()` exposes only the aggregate cost — and
-   *  Pi sums `cost.total` for nested usage anyway. */
+  /** Full provider Usage observed for this task, including compacted-away
+   *  history. Always present (`emptyUsage()` on no-op/early-failure paths).
+   *  When `incomplete` is absent, sync delegate can fold it into the parent and
+   *  aggregate `cost.total` is final. For an abandoned task it is only a lower
+   *  bound and dispatch omits top-level nested usage. Per-component cost fields
+   *  stay 0 because `getSessionStats()` exposes only aggregate cost. */
   usage: Usage;
-  /** Scratch results are excluded from shared-file conflict detection and never resumable. */
+  /** Scratch is never resumable. Its certain internal writes are excluded from
+   * shared-file conflict detection; external or uncertain evidence is retained. */
   workspace?: WorkspaceMode;
   sessionFile?: string;
   /** All files the subagent is known to have touched, including bash mutations
@@ -245,6 +299,9 @@ export interface TaskResult {
    *  for overlap detection so concurrent tasks in the same repo do not
    *  fabricate false conflicts from shared git snapshots. */
   attributedFiles?: string[];
+  /** Provenance-bearing evidence behind attributedFiles. Optional for legacy
+   * callers/tests that only provide the projected string list. */
+  fileAttributions?: FileAttribution[];
   /** Git-native proposal/reconciliation outcome for workspace:"isolated". */
   integration?: TaskIntegration;
 }
@@ -259,6 +316,15 @@ export type TaskIntegrationStatus =
 interface TaskIntegrationFiles {
   proposedFiles: string[];
   appliedFiles: string[];
+  /** Cleanup is separate from the integration outcome: a proposal can remain
+   * successfully applied even when a disposable worktree cannot be removed. */
+  cleanupIssue?: {
+    status: "deferred" | "failed";
+    reason: string;
+    /** Stable recovery marker. It may disappear after a deferred cleanup
+     * succeeds, but is retained when cleanup fails. */
+    recoveryPath?: string;
+  };
 }
 
 interface TaskIntegrationWithoutRecovery extends TaskIntegrationFiles {
@@ -278,6 +344,9 @@ export type TaskIntegration =
     })
   | (TaskIntegrationWithoutRecovery & {
       status: "discarded";
+      /** Reporting-only issues encountered while classifying a failed task's
+       * paths. They do not turn the discarded proposal into an apply failure. */
+      classificationIssues?: Array<{ path: string; reason: string }>;
     })
   | (TaskIntegrationFiles & {
       status: "conflict";

package/utils.ts

@@ -58,8 +58,129 @@ export function extractTextFromPartialResult(
 
 /** Strip ANSI escape sequences from text. */
 export function stripAnsi(text: string): string {
-  // eslint-disable-next-line no-control-regex
-  return text.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+  // A scanner keeps malformed, unterminated control strings linear-time.
+  // Regexes with lazy "anything until ST" branches become quadratic on input
+  // containing many unterminated OSC/DCS introducers.
+  let clean = "";
+  for (let index = 0; index < text.length;) {
+    const code = text.charCodeAt(index);
+
+    if (code === 0x1b) {
+      const next = text.charCodeAt(index + 1);
+      if (next === 0x5d) {
+        index = skipControlString(text, index + 2, true);
+        continue;
+      }
+      if (next === 0x50 || next === 0x58 || next === 0x5e || next === 0x5f) {
+        index = skipControlString(text, index + 2, false);
+        continue;
+      }
+      if (next === 0x5b) {
+        index = skipCsi(text, index + 2);
+        continue;
+      }
+      if (next === 0x5c) {
+        // Preserve a boundary for a standalone 7-bit ST just as for C1 ST,
+        // so removing it cannot concatenate attacker-controlled words.
+        clean += " ";
+        index += 2;
+        continue;
+      }
+
+      // Generic ESC sequence: intermediates followed by one final byte.
+      index++;
+      while (index < text.length) {
+        const value = text.charCodeAt(index);
+        if (value < 0x20 || value > 0x2f) break;
+        index++;
+      }
+      if (index < text.length) {
+        const final = text.charCodeAt(index);
+        if (final >= 0x30 && final <= 0x7e) index++;
+      }
+      continue;
+    }
+
+    if (code === 0x9d) {
+      index = skipControlString(text, index + 1, true);
+      continue;
+    }
+    if (code === 0x90 || code === 0x98 || code === 0x9e || code === 0x9f) {
+      index = skipControlString(text, index + 1, false);
+      continue;
+    }
+    if (code === 0x9b) {
+      index = skipCsi(text, index + 1);
+      continue;
+    }
+    if (code === 0x9c) {
+      // Preserve a boundary for a stray terminator so sanitization cannot
+      // concatenate attacker-controlled words around the removed control.
+      clean += " ";
+      index++;
+      continue;
+    }
+
+    clean += text[index]!;
+    index++;
+  }
+  return clean;
+}
+
+function skipControlString(
+  text: string,
+  index: number,
+  bellTerminates: boolean,
+): number {
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    if ((bellTerminates && code === 0x07) || code === 0x9c) return index + 1;
+    if (
+      code === 0x1b &&
+      index + 1 < text.length &&
+      text.charCodeAt(index + 1) === 0x5c
+    ) {
+      return index + 2;
+    }
+    index++;
+  }
+  return index;
+}
+
+function skipCsi(text: string, index: number): number {
+  while (index < text.length) {
+    const code = text.charCodeAt(index);
+    // A malformed CSI must not consume diagnostic layout while searching for
+    // a final byte. Leave common layout controls for the outer sanitizer.
+    if (code === 0x09 || code === 0x0a || code === 0x0d) return index;
+    index++;
+    if (code >= 0x40 && code <= 0x7e) break;
+  }
+  return index;
+}
+
+/**
+ * Remove terminal controls from untrusted multiline text while preserving its
+ * line and ordinary whitespace structure for markdown/plain-text rendering.
+ */
+export function sanitizeTerminalText(text: string): string {
+  return (
+    stripAnsi(text)
+      .replace(/\r\n?|\u2028|\u2029/g, "\n")
+      .replace(/[\u0000-\u0009\u000b-\u001f\u007f-\u009f]+/g, " ")
+      // Invisible bidi marks, embeddings/overrides, and isolates can reorder
+      // attacker-controlled terminal text without changing its stored spelling.
+      .replace(/[\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, "")
+  );
+}
+
+/**
+ * Flatten untrusted text for one terminal row. ANSI sequences and terminal
+ * controls are removed before whitespace is normalized, so callers can safely
+ * truncate and store the result without preserving a partial escape sequence.
+ */
+export function sanitizeTerminalLine(text: string): string {
+  return sanitizeTerminalText(text).replace(/\s+/g, " ").trim();
 }
 
 /** Resolve carriage-return progress bars to their final line state. */

package/workspace.ts

@@ -1,7 +1,9 @@
 import { execFile } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { revalidateFileAttribution } from "./file-tracking.ts";
 import { scheduleDeadline } from "./timer.ts";
+import type { FileAttribution } from "./types.ts";
 
 const SCRATCH_CONTAINER_NAME = ".pi-delegate-scratch";
 const SCRATCH_LEASE_PREFIX = "lease-";
@@ -29,6 +31,17 @@ export interface ScratchWorkspace {
    * compare with the host path they actually touched.
    */
   resolveAttributedPath(candidate: string): Promise<string | undefined>;
+  /** Project structured attribution without re-resolving its execution-time
+   * physical snapshot. Uncertain internal evidence is retained. */
+  resolveFileAttribution?(
+    attribution: FileAttribution,
+  ): Promise<FileAttribution | undefined>;
+  /** Project the lexical touched-path half of structured attribution. A
+   * certainly attributed copied symlink is suppressed only when both link
+   * identities remain stable while their matching targets are read. */
+  resolveAttributedLexicalTouch?(
+    attribution: FileAttribution,
+  ): Promise<string | undefined>;
   /** True when the existing path resolves inside the disposable tree. */
   isDisposablePath(candidate: string): Promise<boolean>;
   cleanup(): Promise<void>;
@@ -186,6 +199,30 @@ function isWithin(root: string, candidate: string): boolean {
   );
 }
 
+function errnoOf(error: unknown): string {
+  return error instanceof Error && "code" in error
+    ? String((error as NodeJS.ErrnoException).code ?? "UNKNOWN")
+    : "UNKNOWN";
+}
+
+function logScratchProjectionFailure(
+  operation: "lstat" | "readlink",
+  candidate: string,
+  error: unknown,
+): void {
+  const safeCandidate = JSON.stringify(candidate)
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+  console.error(
+    `[delegate] scratch attribution ${operation} failed for ${safeCandidate} (errno=${errnoOf(error)}); retaining lexical source evidence`,
+  );
+}
+
+function isExpectedPathRace(error: unknown): boolean {
+  const code = errnoOf(error);
+  return code === "ENOENT" || code === "ENOTDIR" || code === "EINVAL";
+}
+
 function isProcessAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -794,6 +831,100 @@ export async function createScratchWorkspace(
       return isWithin(completedRoot, absolute) ? undefined : absolute;
     }
   };
+  const mapDisposableLexically = (candidate: string): string => {
+    const absolute = path.resolve(candidate);
+    return isWithin(completedRoot, absolute)
+      ? path.join(sourceRoot!, path.relative(completedRoot, absolute))
+      : absolute;
+  };
+  const resolveFileAttribution = async (
+    original: FileAttribution,
+  ): Promise<FileAttribution | undefined> => {
+    const attribution = revalidateFileAttribution(original);
+    const physical = attribution.preExecutionPhysicalPath;
+    // A certain physical snapshot inside scratch is disposable. Crucially, do
+    // not realpath it now: the tool may have replaced that node with a symlink.
+    if (
+      physical &&
+      !attribution.uncertain &&
+      isWithin(completedRoot, physical)
+    ) {
+      return undefined;
+    }
+    return {
+      ...attribution,
+      lexicalPath: mapDisposableLexically(attribution.lexicalPath),
+      preExecutionPhysicalPath: physical
+        ? mapDisposableLexically(physical)
+        : undefined,
+    };
+  };
+  const resolveAttributedLexicalTouch = async (
+    original: FileAttribution,
+  ): Promise<string | undefined> => {
+    const attribution = revalidateFileAttribution(original);
+    const lexical = path.resolve(attribution.lexicalPath);
+    if (!isWithin(completedRoot, lexical)) return lexical;
+    const source = path.join(
+      sourceRoot!,
+      path.relative(completedRoot, lexical),
+    );
+    // Suppression is an optimization for a copied, unchanged symlink node. An
+    // uncertain attribution cannot prove that the lexical node was harmless.
+    if (attribution.uncertain) return source;
+
+    const inspect = async (
+      candidate: string,
+    ): Promise<fs.Stats | undefined> => {
+      try {
+        return await fs.promises.lstat(candidate);
+      } catch (error) {
+        if (!isExpectedPathRace(error)) {
+          logScratchProjectionFailure("lstat", candidate, error);
+        }
+        return undefined;
+      }
+    };
+    const [scratchStat, sourceStat] = await Promise.all([
+      inspect(lexical),
+      inspect(source),
+    ]);
+    if (scratchStat?.isSymbolicLink() && sourceStat?.isSymbolicLink()) {
+      const readStableLink = async (
+        candidate: string,
+        before: fs.Stats,
+      ): Promise<string | undefined> => {
+        let target: string;
+        try {
+          target = await fs.promises.readlink(candidate);
+        } catch (error) {
+          if (!isExpectedPathRace(error)) {
+            logScratchProjectionFailure("readlink", candidate, error);
+          }
+          return undefined;
+        }
+        const after = await inspect(candidate);
+        return after?.isSymbolicLink() && sameFileIdentity(before, after)
+          ? target
+          : undefined;
+      };
+      const [scratchTarget, sourceTarget] = await Promise.all([
+        readStableLink(lexical, scratchStat),
+        readStableLink(source, sourceStat),
+      ]);
+      // A readlink or identity race is not evidence that the nodes matched.
+      // Keep the lexical source path rather than dropping it.
+      if (
+        scratchTarget !== undefined &&
+        sourceTarget !== undefined &&
+        scratchTarget === sourceTarget
+      ) {
+        return undefined;
+      }
+    }
+    // This is evidence about the lexical node, not its current target.
+    return source;
+  };
   return {
     sourceRoot: sourceRoot!,
     sourceCwd: sourceCwd!,
@@ -806,6 +937,8 @@ export async function createScratchWorkspace(
     },
     resolveReportedPath,
     resolveAttributedPath,
+    resolveFileAttribution,
+    resolveAttributedLexicalTouch,
     async isDisposablePath(candidate: string): Promise<boolean> {
       return (await resolveAttributedPath(candidate)) === undefined;
     },