@bermudi/pi-delegate 0.1.11 → 0.1.13

package/settings.ts

@@ -4,15 +4,15 @@ import * as path from "node:path";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { VALID_THINKING } from "./constants.ts";
 
-export interface AgentOverride {
-  model?: string;
-  thinking?: ThinkingLevel;
-  tools?: string[];
-}
+/**
+ * One-release compatibility bridge for delegate overrides formerly stored in
+ * Pi's user/project settings.json. Only model and thinking are bridged; tools
+ * remain operator-controlled because project files must not restore shell
+ * capability. Modern delegate.json values win field-by-field.
+ */
 
-export interface DelegateSettings {
-  agentOverrides?: Record<string, AgentOverride>;
-  agentOverridesByParentModel?: Record<string, Record<string, AgentOverride>>;
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 /** Read and validate a JSON settings object, returning null on I/O or parse errors. */
@@ -44,8 +44,104 @@ export function readDelegateSettingsFile(
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
+interface LegacyDetectionCacheEntry {
+  signature: string;
+  carriesDelegateBlock: boolean;
+}
+
+const legacyDetectionCache = new Map<string, LegacyDetectionCacheEntry>();
+const warnedLegacyDetectionFailures = new Set<string>();
+
+/** A cheap file identity used to invalidate cached misses and parse failures
+ * when a settings file is created or edited. */
+function settingsFileSignature(filePath: string): string {
+  try {
+    const stat = fs.statSync(filePath);
+    return [
+      "present",
+      stat.dev,
+      stat.ino,
+      stat.size,
+      stat.mtimeMs,
+      stat.ctimeMs,
+      stat.mode,
+    ].join(":");
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return "missing";
+    }
+    // An inaccessible or otherwise unstatable file is not a stable miss. Let
+    // the read path report it on each attempt rather than hiding a later fix.
+    return `unstatable:${Date.now()}`;
+  }
+}
+
+function settingsCarryDelegateBlock(filePath: string): boolean {
+  const key = path.resolve(filePath);
+  const signature = settingsFileSignature(key);
+  const cached = legacyDetectionCache.get(key);
+  if (cached?.signature === signature) return cached.carriesDelegateBlock;
+
+  const parsed = readDelegateSettingsFile(key);
+  const carriesDelegateBlock = parsed !== null && isRecord(parsed.delegate);
+  legacyDetectionCache.set(key, { signature, carriesDelegateBlock });
+  return carriesDelegateBlock;
+}
+
+/** Paths of pi settings files (user + nearest project `.pi/settings.json`)
+ *  that still carry a `delegate` block. Fail-open: never throws. */
+export function findLegacyDelegateSettings(cwd: string): string[] {
+  const paths: string[] = [];
+  try {
+    const userPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    if (settingsCarryDelegateBlock(userPath)) paths.push(userPath);
+
+    // Nearest `.pi` directory walking up from cwd — the same discovery the
+    // old loader used, so a project that relied on overrides is still caught.
+    let dir = path.resolve(cwd);
+    const root = path.resolve("/");
+    for (;;) {
+      if (fs.existsSync(path.join(dir, ".pi"))) {
+        const projectPath = path.join(dir, ".pi", "settings.json");
+        if (settingsCarryDelegateBlock(projectPath)) paths.push(projectPath);
+        break;
+      }
+      if (dir === root) break;
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch (error) {
+    // Detection is best-effort and must never block a dispatch, but silently
+    // losing the migration signal would make ignored legacy overrides hard to
+    // diagnose. Report each affected cwd once to avoid warning floods when a
+    // dispatch resolves several tasks in the same project.
+    if (!warnedLegacyDetectionFailures.has(cwd)) {
+      warnedLegacyDetectionFailures.add(cwd);
+      const detail = error instanceof Error ? error.message : String(error);
+      console.warn(
+        `[delegate] could not check for legacy delegate settings from '${cwd}': ${detail}. Overrides in pi settings.json may be ignored; move them to ~/.pi/agent/delegate.json.`,
+      );
+    }
+  }
+  return paths;
+}
+
+const warnedLegacySources = new Set<string>();
+
+/** Shape returned by the temporary compatibility loader. */
+export interface DelegateSettings {
+  agentOverrides?: Record<string, AgentOverride>;
+  agentOverridesByParentModel?: Record<string, Record<string, AgentOverride>>;
+}
+
+export interface AgentOverride {
+  model?: string;
+  thinking?: ThinkingLevel;
 }
 
 function normalizeOverride(
@@ -79,21 +175,9 @@ function normalizeOverride(
       }
       result.thinking = value as ThinkingLevel;
     } else if (key === "tools") {
-      if (
-        !Array.isArray(value) ||
-        value.some((tool) => typeof tool !== "string")
-      ) {
-        console.warn(
-          `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: tools must be a string array.`,
-        );
-        return null;
-      }
-      result.tools = [...value];
-    } else if (key === "skills") {
       console.warn(
-        `[delegate] ignoring unsupported skills override for agent '${agentName}' in ${source}: per-agent skill filtering is not supported.`,
+        `[delegate] ignoring legacy tools override for agent '${agentName}' in ${source}: the temporary compatibility bridge honors only model and thinking.`,
       );
-      return null;
     } else {
       console.warn(
         `[delegate] ignoring malformed settings override for agent '${agentName}' in ${source}: unknown field '${key}'.`,
@@ -115,7 +199,7 @@ function normalizeOverrides(
     return {};
   }
 
-  const result: Record<string, AgentOverride> = {};
+  const result = Object.create(null) as Record<string, AgentOverride>;
   const seenNames = new Map<string, string>();
   for (const [agentName, value] of Object.entries(raw)) {
     const normalizedAgentName = agentName.trim();
@@ -150,7 +234,10 @@ function normalizeOverridesByParentModel(
     return {};
   }
 
-  const result: Record<string, Record<string, AgentOverride>> = {};
+  const result = Object.create(null) as Record<
+    string,
+    Record<string, AgentOverride>
+  >;
   const seenModels = new Map<string, string>();
   for (const [parentModel, overrides] of Object.entries(raw)) {
     const normalizedParentModel = parentModel.trim();
@@ -176,13 +263,9 @@ function normalizeOverridesByParentModel(
   return result;
 }
 
-function getDelegateSettings(filePath: string): DelegateSettings | null {
+function readLegacyDelegateSettings(filePath: string): DelegateSettings | null {
   const settings = readDelegateSettingsFile(filePath);
-  if (
-    !settings?.delegate ||
-    typeof settings.delegate !== "object" ||
-    Array.isArray(settings.delegate)
-  ) {
+  if (!isRecord(settings?.delegate)) {
     if (settings?.delegate !== undefined) {
       console.warn(
         `[delegate] ignoring malformed delegate settings in ${filePath}: expected an object.`,
@@ -190,35 +273,74 @@ function getDelegateSettings(filePath: string): DelegateSettings | null {
     }
     return null;
   }
-  const raw = settings.delegate as Record<string, unknown>;
+
   const result: DelegateSettings = {};
-  if (raw.agentOverrides !== undefined) {
-    result.agentOverrides = normalizeOverrides(raw.agentOverrides, filePath);
+  if (settings.delegate.agentOverrides !== undefined) {
+    result.agentOverrides = normalizeOverrides(
+      settings.delegate.agentOverrides,
+      filePath,
+    );
   }
-  if (raw.agentOverridesByParentModel !== undefined) {
+  if (settings.delegate.agentOverridesByParentModel !== undefined) {
     result.agentOverridesByParentModel = normalizeOverridesByParentModel(
-      raw.agentOverridesByParentModel,
+      settings.delegate.agentOverridesByParentModel,
       filePath,
     );
   }
   return result;
 }
 
-const delegateSettingsCache = new Map<string, DelegateSettings | null>();
+function mergeOverride(
+  base: AgentOverride | undefined,
+  override: AgentOverride | undefined,
+): AgentOverride {
+  return { ...(base ?? {}), ...(override ?? {}) };
+}
 
-/** Load merged delegate settings: project overrides user.
- * Result is cached per cwd until the next delegate dispatch clears it. */
+function mergeOverrides(
+  user: Record<string, AgentOverride> | undefined,
+  project: Record<string, AgentOverride> | undefined,
+): Record<string, AgentOverride> {
+  const result = Object.create(null) as Record<string, AgentOverride>;
+  for (const name of new Set([
+    ...Object.keys(user ?? {}),
+    ...Object.keys(project ?? {}),
+  ])) {
+    result[name] = mergeOverride(user?.[name], project?.[name]);
+  }
+  return result;
+}
+
+function mergeParentModelOverrides(
+  user: Record<string, Record<string, AgentOverride>> | undefined,
+  project: Record<string, Record<string, AgentOverride>> | undefined,
+): Record<string, Record<string, AgentOverride>> {
+  const result = Object.create(null) as Record<
+    string,
+    Record<string, AgentOverride>
+  >;
+  for (const model of new Set([
+    ...Object.keys(user ?? {}),
+    ...Object.keys(project ?? {}),
+  ])) {
+    result[model] = mergeOverrides(user?.[model], project?.[model]);
+  }
+  return result;
+}
+
+/**
+ * Temporary compatibility reader. It accepts a working directory and returns
+ * the merged view (project fields override user fields). Deliberately rereads
+ * the two small JSON files: this bridge lasts one release, and avoiding a cache
+ * makes file create/edit/delete visible on the very next dispatch.
+ */
 export function loadDelegateSettings(cwd: string): DelegateSettings | null {
   const key = path.resolve(cwd);
-  const cached = delegateSettingsCache.get(key);
-  if (cached !== undefined) return cached;
-
   const userPath = path.join(os.homedir(), ".pi", "agent", "settings.json");
-  // Look for project root by finding .pi/ directory, not just .pi/agents/
-  let projectPath: string | null = null;
+  let projectPath: string | undefined;
   let dir = key;
   const root = path.resolve("/");
-  while (true) {
+  for (;;) {
     if (fs.existsSync(path.join(dir, ".pi"))) {
       projectPath = path.join(dir, ".pi", "settings.json");
       break;
@@ -229,13 +351,12 @@ export function loadDelegateSettings(cwd: string): DelegateSettings | null {
     dir = parent;
   }
 
-  const user = getDelegateSettings(userPath);
-  const project = projectPath ? getDelegateSettings(projectPath) : null;
-
+  const user = readLegacyDelegateSettings(userPath);
+  const project = projectPath ? readLegacyDelegateSettings(projectPath) : null;
   if (!user && !project) {
-    delegateSettingsCache.set(key, null);
     return null;
   }
+
   const result: DelegateSettings = {
     ...(user?.agentOverrides || project?.agentOverrides
       ? {
@@ -255,46 +376,43 @@ export function loadDelegateSettings(cwd: string): DelegateSettings | null {
         }
       : {}),
   };
-  delegateSettingsCache.set(key, result);
   return result;
 }
 
-function mergeOverride(
-  base: AgentOverride | undefined,
-  override: AgentOverride | undefined,
-): AgentOverride {
-  return { ...(base ?? {}), ...(override ?? {}) };
-}
-
-function mergeOverrides(
-  user: Record<string, AgentOverride> | undefined,
-  project: Record<string, AgentOverride> | undefined,
-): Record<string, AgentOverride> {
-  const result: Record<string, AgentOverride> = {};
-  for (const name of new Set([
-    ...Object.keys(user ?? {}),
-    ...Object.keys(project ?? {}),
-  ])) {
-    result[name] = mergeOverride(user?.[name], project?.[name]);
-  }
-  return result;
-}
-
-function mergeParentModelOverrides(
-  user: Record<string, Record<string, AgentOverride>> | undefined,
-  project: Record<string, Record<string, AgentOverride>> | undefined,
-): Record<string, Record<string, AgentOverride>> {
-  const result: Record<string, Record<string, AgentOverride>> = {};
-  for (const model of new Set([
-    ...Object.keys(user ?? {}),
-    ...Object.keys(project ?? {}),
-  ])) {
-    result[model] = mergeOverrides(user?.[model], project?.[model]);
+/** Warn (once per cwd) when pi settings files still carry a legacy `delegate`
+ * block. The same message goes to stderr and, when available, the TUI. Keys
+ * include both cwd and source so a newly-created project setting is not hidden
+ * by an earlier user-setting warning. */
+export function warnLegacyDelegateSettingsMoved(
+  cwd: string,
+  notify?: (message: string) => void,
+): void {
+  const cwdKey = path.resolve(cwd);
+  const paths = findLegacyDelegateSettings(cwd);
+  if (paths.length === 0) return;
+  for (const filePath of paths) {
+    const warningKey = `${cwdKey}\0${filePath}`;
+    if (warnedLegacySources.has(warningKey)) continue;
+    warnedLegacySources.add(warningKey);
+    const message =
+      `[delegate] TEMPORARY legacy compatibility: using model/thinking overrides from ${filePath}. ` +
+      "Move user-global overrides to ~/.pi/agent/delegate.json. Project-local overrides have no future config-file equivalent; use .pi/agents/*.md or explicit task model/thinking fields. " +
+      "Legacy settings compatibility is available for v0.1.12 only and will be removed in v0.1.13. Legacy tools overrides are not honored.";
+    console.warn(message);
+    try {
+      notify?.(message);
+    } catch (error) {
+      console.error(
+        "[delegate] legacy settings TUI notification failed",
+        error,
+      );
+    }
   }
-  return result;
 }
 
-/** Clear settings read from earlier delegate calls so edits are visible. */
+/** @deprecated Clear the set of cwd's already warned about legacy settings. */
 export function clearDelegateSettingsCache(): void {
-  delegateSettingsCache.clear();
+  warnedLegacySources.clear();
+  warnedLegacyDetectionFailures.clear();
+  legacyDetectionCache.clear();
 }

package/shared-write-safety.ts

@@ -0,0 +1,273 @@
+import { execFile } from "node:child_process";
+import * as fs from "node:fs";
+import { mapConcurrent } from "./concurrency.ts";
+import { isPathWithinDirectoryLexical } from "./trusted-paths.ts";
+import type { ResolvedTask } from "./types.ts";
+
+const GIT_TIMEOUT_MS = 5_000;
+const PREFLIGHT_CONCURRENCY = 4;
+const NON_MUTATING_TOOLS = new Set([
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "web_search",
+]);
+const GIT_REDIRECTS = ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR"] as const;
+
+export interface SharedWriteScope {
+  kind: "git" | "directory";
+  root: string;
+  /** Additional physical roots reachable from the task cwd. Present only
+   * while resolving admissions; conflict results expose the witness root. */
+  roots?: ReachRoot[];
+}
+
+interface ReachRoot {
+  kind: "git" | "directory";
+  root: string;
+}
+
+export interface SharedWriteConflict {
+  scope: SharedWriteScope;
+  taskIndexes: number[];
+}
+
+export class SharedWriteSafetyError extends Error {}
+
+class GitScopeError extends Error {
+  constructor(
+    message: string,
+    readonly stderr: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+}
+
+function gitRepositoryRoot(cwd: string, signal?: AbortSignal): Promise<string> {
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(([key]) => !key.startsWith("GIT_")),
+  );
+  return new Promise((resolve, reject) => {
+    execFile(
+      "git",
+      ["rev-parse", "--show-toplevel"],
+      {
+        cwd,
+        signal,
+        timeout: GIT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+        env: {
+          ...env,
+          LC_ALL: "C",
+          LANG: "C",
+          GIT_OPTIONAL_LOCKS: "0",
+          GIT_DISCOVERY_ACROSS_FILESYSTEM: "1",
+        },
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(
+            new GitScopeError(error.message, stderr.trim(), { cause: error }),
+          );
+          return;
+        }
+        resolve(stdout.trim());
+      },
+    );
+  });
+}
+
+/** Resolve a primary write boundary and, for an external core.worktree, the
+ * physical cwd that remains reachable. Plain directories use the task cwd.
+ * Only Git's explicit "not a repository" permits directory fallback. */
+export async function resolveSharedWriteScope(
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<SharedWriteScope> {
+  let physicalCwd: string;
+  try {
+    physicalCwd = await fs.promises.realpath(cwd);
+  } catch (error) {
+    throw new SharedWriteSafetyError(
+      `Could not resolve task directory '${cwd}'.`,
+      { cause: error },
+    );
+  }
+
+  try {
+    const root = await gitRepositoryRoot(physicalCwd, signal);
+    if (!root) {
+      throw new SharedWriteSafetyError(
+        `Git returned an empty repository root for '${physicalCwd}'.`,
+      );
+    }
+    const physicalRoot = await fs.promises.realpath(root);
+    const roots: ReachRoot[] = [{ kind: "git", root: physicalRoot }];
+    if (!isPathWithinDirectoryLexical(physicalRoot, physicalCwd)) {
+      roots.push({ kind: "directory", root: physicalCwd });
+    }
+    return { kind: "git", root: physicalRoot, roots };
+  } catch (error) {
+    if (
+      error instanceof GitScopeError &&
+      /not a git repository/i.test(error.stderr)
+    ) {
+      return { kind: "directory", root: physicalCwd };
+    }
+    if (error instanceof SharedWriteSafetyError) throw error;
+    const detail =
+      error instanceof GitScopeError
+        ? error.stderr || error.message
+        : error instanceof Error
+          ? error.message
+          : String(error);
+    throw new SharedWriteSafetyError(
+      `Could not safely determine the Git root for '${physicalCwd}': ${detail}`,
+      { cause: error },
+    );
+  }
+}
+
+export function isSharedWriter(task: ResolvedTask): boolean {
+  return (
+    task.workspace === "shared" &&
+    task.tools.some((tool) => !NON_MUTATING_TOOLS.has(tool))
+  );
+}
+
+function reachRoots(scope: SharedWriteScope): ReachRoot[] {
+  return scope.roots ?? [{ kind: scope.kind, root: scope.root }];
+}
+
+function rootsOverlap(left: ReachRoot, right: ReachRoot): boolean {
+  return (
+    isPathWithinDirectoryLexical(left.root, right.root) ||
+    isPathWithinDirectoryLexical(right.root, left.root)
+  );
+}
+
+function shallower(left: ReachRoot, right: ReachRoot): ReachRoot {
+  return isPathWithinDirectoryLexical(left.root, right.root) ? left : right;
+}
+
+function overlapWitness(
+  left: SharedWriteScope,
+  right: SharedWriteScope,
+): ReachRoot | undefined {
+  let witness: ReachRoot | undefined;
+  for (const leftRoot of reachRoots(left)) {
+    for (const rightRoot of reachRoots(right)) {
+      if (!rootsOverlap(leftRoot, rightRoot)) continue;
+      const candidate = shallower(leftRoot, rightRoot);
+      if (
+        witness === undefined ||
+        isPathWithinDirectoryLexical(candidate.root, witness.root)
+      ) {
+        witness = candidate;
+      }
+    }
+  }
+  return witness;
+}
+
+/** Find connected overlapping writer scopes while preserving task order.
+ * Unknown tools fail closed as mutating. This is an in-process admission
+ * boundary, not filesystem confinement or a claim about external processes. */
+export async function findSharedWriteConflicts(
+  tasks: readonly ResolvedTask[],
+  signal?: AbortSignal,
+): Promise<SharedWriteConflict[]> {
+  const candidates = tasks
+    .map((task, taskIndex) => ({ task, taskIndex }))
+    .filter(({ task }) => isSharedWriter(task));
+  if (candidates.length < 2) return [];
+
+  const redirects = GIT_REDIRECTS.filter(
+    (name) => process.env[name] !== undefined,
+  );
+  if (
+    redirects.length &&
+    candidates.some(({ task }) => task.tools.includes("bash"))
+  ) {
+    throw new SharedWriteSafetyError(
+      `Could not safely verify a bash-capable shared-write batch while ${redirects.join(", ")} redirects Git repository context.`,
+    );
+  }
+
+  const uniqueCwds = [...new Set(candidates.map(({ task }) => task.cwd))];
+  const scopes = await mapConcurrent(uniqueCwds, PREFLIGHT_CONCURRENCY, (cwd) =>
+    resolveSharedWriteScope(cwd, signal),
+  );
+  const byCwd = new Map(
+    uniqueCwds.map((cwd, index) => [cwd, scopes[index]!] as const),
+  );
+  const resolved = candidates.map(({ task, taskIndex }) => ({
+    taskIndex,
+    scope: byCwd.get(task.cwd)!,
+  }));
+
+  const parents = resolved.map((_, index) => index);
+  const find = (index: number): number => {
+    while (parents[index] !== index) {
+      parents[index] = parents[parents[index]!]!;
+      index = parents[index]!;
+    }
+    return index;
+  };
+  const union = (left: number, right: number): void => {
+    const a = find(left);
+    const b = find(right);
+    if (a !== b) parents[b] = a;
+  };
+  for (let left = 0; left < resolved.length; left++) {
+    for (let right = left + 1; right < resolved.length; right++) {
+      if (
+        overlapWitness(resolved[left]!.scope, resolved[right]!.scope) !==
+        undefined
+      ) {
+        union(left, right);
+      }
+    }
+  }
+
+  const components = new Map<number, number[]>();
+  for (let index = 0; index < resolved.length; index++) {
+    const root = find(index);
+    const members = components.get(root);
+    if (members) members.push(index);
+    else components.set(root, [index]);
+  }
+
+  const conflicts: SharedWriteConflict[] = [];
+  for (const members of components.values()) {
+    if (members.length < 2) continue;
+    let witness: ReachRoot | undefined;
+    for (let left = 0; left < members.length; left++) {
+      for (let right = left + 1; right < members.length; right++) {
+        const candidate = overlapWitness(
+          resolved[members[left]!]!.scope,
+          resolved[members[right]!]!.scope,
+        );
+        if (
+          candidate &&
+          (witness === undefined ||
+            isPathWithinDirectoryLexical(candidate.root, witness.root))
+        ) {
+          witness = candidate;
+        }
+      }
+    }
+    if (!witness) {
+      throw new SharedWriteSafetyError(
+        "Invariant violation: connected writer scopes have no overlap witness.",
+      );
+    }
+    conflicts.push({
+      scope: { kind: witness.kind, root: witness.root },
+      taskIndexes: members.map((index) => resolved[index]!.taskIndex),
+    });
+  }
+  return conflicts;
+}