@bermudi/pi-delegate 0.1.12 → 0.1.14

package/README.md

@@ -67,21 +67,17 @@ across `.pi/agents/`, `~/.pi/agent/agents/`, `~/.agents/`, `.claude/agents/`,
 workspace — `scout` stays read-only and `reviewer` stays scratch unless the
 file explicitly sets `tools` or `workspace`. Fresh built-ins inherit the
 parent's exact model object and thinking level; an explicit `model`/`thinking`
-in the Markdown file replaces that inheritance. Task fields always win, and for
-`scout`/`coder`/`reviewer` overrides in `~/.pi/agent/delegate.json`
-(`agentOverrides` / `agentOverridesByParentModel`) win over the
-Markdown file, while `default` ignores overrides and uses only an explicit
-Markdown `model`/`thinking` when present. `delegate.json` is the permanent
-config file (user scope, global), and edits apply from the next delegate call.
-
-For the v0.1.12 migration release only, legacy user and nearest-project
-`settings.json` `delegate.agentOverrides` /
-`delegate.agentOverridesByParentModel` still supply `model` and `thinking`
-when a modern value is absent. Modern `delegate.json` wins field-by-field.
-Legacy `tools` is never honored because a project file must not restore shell
-capability. This bridge is removed in v0.1.13. Project-local replacements are
-`.pi/agents/*.md` profiles or explicit task `model`/`thinking` fields; there
-will be no new project-level delegate config file.
+in the Markdown file replaces that inheritance. Task fields always win. For
+each unset `model`, `thinking`, or `tools` field on
+`scout`/`coder`/`reviewer`, an exact-parent-model override in
+`agentOverridesByParentModel` wins over the unconditional `agentOverrides`,
+which wins over explicit Markdown frontmatter. `default` is the exception: it
+ignores both `delegate.json` override maps, but task fields still win and
+explicit `default.md` fields still override inherited parent values.
+`~/.pi/agent/delegate.json` is the only delegate config file (user scope,
+global), and edits apply from the next delegate call. Project-local
+configuration belongs in `.pi/agents/*.md` profiles or explicit task fields;
+Delegate ignores legacy `delegate` fields in project `.pi/settings.json`.
 
 ### Disposable scratch workspace
 
@@ -217,8 +213,9 @@ over an installed extension.
   model, tools, and thinking level; the Markdown body is its system prompt. A
   same-named file for a built-in (`default`/`scout`/`coder`/`reviewer`)
   overrides that built-in; a prompt-only override keeps the built-in's tools
-  and workspace, and an explicit `model`/`thinking` replaces parent inheritance
-  (for `default` settings are ignored, for others settings win over the file).
+  and workspace, and an explicit `model`/`thinking` replaces parent inheritance.
+  For `default`, the `delegate.json` override maps are ignored (task fields still
+  win); for the other built-ins, those maps win field-by-field over frontmatter.
 - **Ad-hoc subagent** — A subagent created from inline task fields instead of a
   named Markdown agent profile. In current output this is labeled `ad-hoc`.
 - **Inline task** — The task object itself when its configuration is supplied

package/delegate.ts

@@ -145,14 +145,6 @@ export {
   resolveModelRequest,
   findAvailableAlternative,
 } from "./model.ts";
-export {
-  readDelegateSettingsFile,
-  findLegacyDelegateSettings,
-  warnLegacyDelegateSettingsMoved,
-  loadDelegateSettings,
-  clearDelegateSettingsCache,
-} from "./settings.ts";
-export type { DelegateSettings } from "./settings.ts";
 export { resolveCwd, extractOutput, extractUsage } from "./utils.ts";
 export {
   decideSpill,

package/dispatch.ts

@@ -37,6 +37,8 @@ import {
 } from "./shared-write-safety.ts";
 import type { CallSpan } from "./telemetry.ts";
 import { prepareIsolatedBatch } from "./isolated-workspace.ts";
+import { sanitizeTerminalLine } from "./utils.ts";
+import { quarantinedTasks } from "./session-quarantine.ts";
 import type {
   AgentConfig,
   AsyncTicket,
@@ -110,7 +112,7 @@ export function initProgress(resolved: ResolvedTask[]): TaskProgress[] {
     id: t.id,
     index: i,
     agent: t.agentName,
-    task: trunc(t.prompt || t.sessionAction || "", 50),
+    task: trunc(sanitizeTerminalLine(t.prompt || t.sessionAction || ""), 50),
     status: "pending" as const,
     durationMs: 0,
     tokens: 0,
@@ -366,6 +368,12 @@ export async function dispatchDelegate(
             );
           }
         }
+        for (const quarantined of quarantinedTasks()) {
+          activeResolved.push(asAdmissionWriter(quarantined));
+          references.push(
+            `quarantined ${quarantined.agentName}${quarantined.id ? ` task #${quarantined.id}` : " task"}`,
+          );
+        }
 
         const incomingCount = resolved.length;
         const conflicts = (
@@ -646,6 +654,11 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
     ticketSignal,
   )
     .then(() => {
+      // mapConcurrentByModel is the worker-settled barrier. Publish that before
+      // terminal formatting/delivery so the final spill projection is safely
+      // memoized; shutdown may already have formatted an intentionally uncached
+      // partial snapshot while this flag was false.
+      ticket.workersSettled = true;
       // Shutdown marks the ticket terminal before cooperative worker aborts
       // have finished. Still write one final aggregate after every result has
       // landed; the immediate shutdown snapshot may have missed late usage.
@@ -673,6 +686,8 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
       finishLiveSettlement(ticket);
     })
     .catch((err) => {
+      // mapConcurrentByModel waits for all sibling workers before rejecting.
+      ticket.workersSettled = true;
       // Defense-in-depth — should not happen if individual tasks catch properly.
       // Even an unexpected worker rejection must leave the shutdown aggregate
       // with every result that did settle, without touching the stale UI.
@@ -713,6 +728,7 @@ export function dispatchAsync(input: AsyncDispatchInput): DelegateToolResult {
       parentModel: parentModelId,
       ticketId,
       status: ticket.status,
+      elapsedMs: Date.now() - ticket.created,
       dispatchWarning,
     },
   };
@@ -859,12 +875,18 @@ export async function dispatchSync(
       results: finalResults,
       progress,
       parentModel: parentModelId,
+      elapsedMs: elapsedTotal,
       overlapWarning: overlapWarning || undefined,
       dispatchWarning,
     },
     // Aggregate subagent spend so Pi folds it into the parent's
     // session/footer totals. Sync dispatch only — async results arrive via a
     // follow-up message that has no usage slot (see DelegateToolResult).
-    usage: sumUsage(finalResults.map((r) => r.usage)),
+    // A quarantined task can continue spending after this terminal snapshot.
+    // Omitting top-level usage avoids presenting a lower bound as final nested
+    // accounting to Pi; per-task results retain the observed lower bound.
+    ...(finalResults.some((r) => r.incomplete)
+      ? {}
+      : { usage: sumUsage(finalResults.map((r) => r.usage)) }),
   };
 }

package/extension.ts

@@ -16,7 +16,11 @@ import {
   dispatchDelegate,
   validateDelegateOperationResult,
 } from "./dispatch.ts";
-import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
+import {
+  renderAsyncDelegateMessage,
+  renderDelegateCall,
+  renderDelegateResult,
+} from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
 import { invalidateHostDepsCache } from "./host.ts";
 import { registerProviderExtensionNotifier } from "./provider-extensions.ts";
@@ -24,7 +28,6 @@ import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
 import { reconfigureGlobalConcurrency } from "./concurrency.ts";
 import { reloadDelegateConfig, getMaxConcurrent } from "./config.ts";
-import { warnLegacyDelegateSettingsMoved } from "./settings.ts";
 import {
   activeTicketSummary,
   clearDelegateStatusContext,
@@ -41,7 +44,7 @@ import {
   prepareTelemetryForSession,
   sealTelemetryWrites,
 } from "./telemetry.ts";
-import type { DelegateArguments } from "./types.ts";
+import type { DelegateArguments, DelegateDetails } from "./types.ts";
 
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 10_000;
 let shutdownDrainTimeoutMs = DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
@@ -115,6 +118,14 @@ export default function delegateExtension(pi: ExtensionAPI): void {
   // workers from the old runtime remain blocked from reopening it.
   prepareTelemetryForSession();
 
+  // Async completion arrives as a custom message after the original tool call
+  // has returned. Give it the same compact/expanded UI as sync results while
+  // leaving the full message intact for model context.
+  pi.registerMessageRenderer<DelegateDetails>(
+    "async_delegate_result",
+    renderAsyncDelegateMessage,
+  );
+
   pi.registerTool({
     name: "delegate",
     label: "Delegate to Subagents",
@@ -131,9 +142,6 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       // the global concurrency cap is reconfigured so hot-reloaded maxConcurrent
       // takes effect for subsequent acquisitions. A parse/read error keeps the
       // previous snapshot and warns instead of falling back to defaults.
-      warnLegacyDelegateSettingsMoved(ctx.cwd, (message) =>
-        ctx.ui.notify(message, "warning"),
-      );
       reloadDelegateConfig();
       reconfigureGlobalConcurrency(getMaxConcurrent());
 

package/file-tracking.ts

@@ -1,6 +1,253 @@
 import { execFile } from "node:child_process";
+import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ToolActivity } from "./types.ts";
+import type {
+  FileAttribution,
+  FileAttributionPathSignature,
+  ToolActivity,
+} from "./types.ts";
+
+function activityPath(
+  activity: Pick<ToolActivity, "args">,
+  cwd: string,
+): string | undefined {
+  const raw =
+    activity.args?.path ?? activity.args?.file_path ?? activity.args?.filePath;
+  return typeof raw === "string" && raw ? path.resolve(cwd, raw) : undefined;
+}
+
+function errnoOf(error: unknown): string {
+  return error instanceof Error && "code" in error
+    ? String((error as NodeJS.ErrnoException).code ?? "UNKNOWN")
+    : "UNKNOWN";
+}
+
+function safePathForLog(candidate: string): string {
+  const limit = 1_024;
+  const sanitized =
+    candidate.length > limit
+      ? `${candidate.slice(0, limit)}…[truncated ${candidate.length - limit} chars]`
+      : candidate;
+  // JSON escaping keeps model-supplied control characters out of the terminal.
+  return JSON.stringify(sanitized)
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+function logCanonicalizationFailure(candidate: string, error: unknown): void {
+  console.error(
+    `[delegate] could not canonicalize edit/write target ${safePathForLog(candidate)} (errno=${errnoOf(error)}); retaining uncertain lexical attribution`,
+  );
+}
+
+function statKind(stat: fs.Stats): FileAttributionPathSignature["kind"] {
+  if (stat.isDirectory()) return "directory";
+  if (stat.isSymbolicLink()) return "symlink";
+  return "other";
+}
+
+function signatureOf(
+  candidate: string,
+  stat: fs.Stats,
+  symlinkTarget?: string,
+): FileAttributionPathSignature {
+  return {
+    path: candidate,
+    dev: String(stat.dev),
+    ino: String(stat.ino),
+    birthtimeMs: stat.birthtimeMs,
+    kind: statKind(stat),
+    ...(symlinkTarget === undefined ? {} : { symlinkTarget }),
+  };
+}
+
+function sameSignature(
+  left: FileAttributionPathSignature,
+  right: FileAttributionPathSignature,
+): boolean {
+  return (
+    left.path === right.path &&
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.birthtimeMs === right.birthtimeMs &&
+    left.kind === right.kind &&
+    left.symlinkTarget === right.symlinkTarget
+  );
+}
+
+interface PhysicalSnapshot {
+  path?: string;
+  uncertain: boolean;
+  signatures: FileAttributionPathSignature[];
+}
+
+function pathParts(value: string): { root: string; parts: string[] } {
+  const absolute = path.resolve(value);
+  const root = path.parse(absolute).root;
+  return {
+    root,
+    parts: absolute.slice(root.length).split(path.sep).filter(Boolean),
+  };
+}
+
+/** Resolve one component at a time so the physical snapshot carries the exact
+ * ancestor/symlink identities that justified it. */
+function resolvePhysicalSnapshot(
+  value: string,
+  logCandidate: string,
+): PhysicalSnapshot {
+  let { root, parts } = pathParts(value);
+  let cursor = root;
+  let uncertain = false;
+  const signatures: FileAttributionPathSignature[] = [];
+  const followed = new Set<string>();
+  let symlinkExpansions = 0;
+
+  while (parts.length) {
+    const component = parts.shift()!;
+    const candidate = path.join(cursor, component);
+    let stat: fs.Stats;
+    try {
+      stat = fs.lstatSync(candidate);
+    } catch (error) {
+      const code = errnoOf(error);
+      if (code === "ENOENT" || code === "ENOTDIR") {
+        // A missing or unresolved component can be created or replaced before
+        // the tool opens it. Without an identity to guard that transition, the
+        // projected target must remain conservative even on a purely lexical
+        // path with no symlink seen yet.
+        return {
+          path: path.resolve(candidate, ...parts),
+          uncertain: true,
+          signatures,
+        };
+      }
+      logCanonicalizationFailure(logCandidate, error);
+      return { uncertain: true, signatures };
+    }
+
+    if (stat.isSymbolicLink()) {
+      symlinkExpansions++;
+      if (symlinkExpansions > 256) {
+        logCanonicalizationFailure(
+          logCandidate,
+          Object.assign(new Error("too many symbolic links"), {
+            code: "ELOOP",
+          }),
+        );
+        return { uncertain: true, signatures };
+      }
+      let target: string;
+      try {
+        target = fs.readlinkSync(candidate);
+        const afterRead = fs.lstatSync(candidate);
+        const before = signatureOf(candidate, stat, target);
+        const after = signatureOf(candidate, afterRead, target);
+        signatures.push(before);
+        if (!sameSignature(before, after) || !afterRead.isSymbolicLink()) {
+          uncertain = true;
+        }
+      } catch (error) {
+        const code = errnoOf(error);
+        if (code !== "ENOENT" && code !== "ENOTDIR" && code !== "EINVAL") {
+          logCanonicalizationFailure(logCandidate, error);
+        }
+        return { path: candidate, uncertain: true, signatures };
+      }
+      const cycleKey = `${candidate}\0${target}`;
+      if (followed.has(cycleKey)) {
+        logCanonicalizationFailure(
+          logCandidate,
+          Object.assign(new Error("symbolic link cycle"), { code: "ELOOP" }),
+        );
+        return { uncertain: true, signatures };
+      }
+      followed.add(cycleKey);
+      const targetPath = path.isAbsolute(target)
+        ? target
+        : path.resolve(path.dirname(candidate), target);
+      const targetParts = pathParts(targetPath);
+      root = targetParts.root;
+      cursor = root;
+      parts = [...targetParts.parts, ...parts];
+      continue;
+    }
+
+    // Every existing component is an identity guard, including the leaf. An
+    // in-place edit preserves the leaf identity; replacement or creation does
+    // not, and may redirect the write through a newly installed symlink.
+    signatures.push(signatureOf(candidate, stat));
+    cursor = candidate;
+  }
+
+  return { path: cursor, uncertain, signatures };
+}
+
+/**
+ * Capture edit/write attribution before tool work begins.
+ *
+ * The target is resolved component by component while recording the identity
+ * of every existing component, including the leaf, and the text of every
+ * followed symlink. Missing or dangling components retain their projected path
+ * but are uncertain because creation can redirect the eventual tool open.
+ * Non-ENOENT/ENOTDIR failures are actionable and logged with the lexical
+ * candidate and errno; callers retain that uncertain lexical evidence.
+ */
+export function snapshotPhysicalToolTarget(
+  activity: Pick<ToolActivity, "args" | "name">,
+  cwd: string,
+): FileAttribution | undefined {
+  if (activity.name !== "edit" && activity.name !== "write") return undefined;
+  const candidate = activityPath(activity, cwd);
+  if (!candidate) return undefined;
+
+  const snapshot = resolvePhysicalSnapshot(candidate, candidate);
+  const attribution: FileAttribution = {
+    lexicalPath: candidate,
+    preExecutionPhysicalPath: snapshot.path,
+    preExecutionPathSignatures: snapshot.signatures,
+    provenance: activity.name,
+    uncertain: snapshot.uncertain,
+  };
+  // Close lstat/readlink and component-walk races before execution starts. A
+  // later terminal revalidation performs the same check after execution.
+  return revalidateFileAttribution(attribution);
+}
+
+/** Revalidate the identities used by a pre-execution physical snapshot without
+ * re-resolving that snapshot through the mutable final tree. */
+export function revalidateFileAttribution(
+  attribution: FileAttribution,
+): FileAttribution {
+  if (
+    attribution.uncertain ||
+    !attribution.preExecutionPathSignatures?.length
+  ) {
+    return attribution;
+  }
+  for (const expected of attribution.preExecutionPathSignatures) {
+    try {
+      const stat = fs.lstatSync(expected.path);
+      let target: string | undefined;
+      if (stat.isSymbolicLink()) target = fs.readlinkSync(expected.path);
+      if (!sameSignature(expected, signatureOf(expected.path, stat, target))) {
+        return { ...attribution, uncertain: true };
+      }
+    } catch (error) {
+      const code = errnoOf(error);
+      if (code !== "ENOENT" && code !== "ENOTDIR" && code !== "EINVAL") {
+        logCanonicalizationFailure(attribution.lexicalPath, error);
+      }
+      return { ...attribution, uncertain: true };
+    }
+  }
+  return attribution;
+}
+
+/** Stable string projection used for overlap reporting. */
+export function projectedAttributionPath(attribution: FileAttribution): string {
+  return attribution.preExecutionPhysicalPath ?? attribution.lexicalPath;
+}
 
 /**
  * Return absolute paths reported as changed by Git in the task cwd.
@@ -54,26 +301,50 @@ export async function getGitChangedFiles(
 /**
  * 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.
+ * This is the conservative, activity-based contribution to touched-file
+ * tracking. Every started edit/write call with a usable path is counted:
+ * write/edit tools can mutate before returning an error, and cancellation can
+ * interrupt them after mutation but before a terminal result is emitted.
+ * 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 still a lower bound: absence does not mean a
+ * file was unchanged.
  */
 export function extractTouchedFromActivities(
   activities: ToolActivity[],
   cwd: string,
 ): string[] {
   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));
+  for (const activity of activities) {
+    if (activity.name !== "edit" && activity.name !== "write") continue;
+    const lexicalPath = activityPath(activity, cwd);
+    if (lexicalPath) files.add(lexicalPath);
   }
   return [...files];
 }
+
+/** Provenance-bearing edit/write evidence attributable to this run. */
+export function extractAttributedFromActivities(
+  activities: ToolActivity[],
+  cwd: string,
+): FileAttribution[] {
+  const files = new Map<string, FileAttribution>();
+  for (const activity of activities) {
+    if (activity.name !== "edit" && activity.name !== "write") continue;
+    const lexicalPath = activityPath(activity, cwd);
+    const attribution =
+      activity.fileAttribution ??
+      (lexicalPath
+        ? {
+            lexicalPath,
+            provenance: activity.name,
+            uncertain: true,
+          }
+        : undefined);
+    if (!attribution) continue;
+    const revalidated = revalidateFileAttribution(attribution);
+    const key = `${revalidated.provenance}\0${revalidated.lexicalPath}\0${revalidated.preExecutionPhysicalPath ?? ""}\0${revalidated.uncertain}`;
+    files.set(key, revalidated);
+  }
+  return [...files.values()];
+}