@nredd/pi-subagents 0.22.0-nredd.7 → 0.22.0-nredd.9

package/src/child-context.ts

@@ -4,7 +4,13 @@ import { AsyncLocalStorage } from "node:async_hooks";
  * Marks resource loading/session construction performed for a subagent. This is
  * async-context-local so concurrent top-level extension work is unaffected.
  */
-const childSessionContext = new AsyncLocalStorage<boolean>();
+// Pi reloads extension modules with jiti's module cache disabled. The parent
+// runner and the discovered child extension can therefore hold different module
+// instances, but must consult the same async-local session marker.
+const contextKey = Symbol.for("pi-subagents:child-session-context");
+const globals = globalThis as typeof globalThis & { [contextKey]?: AsyncLocalStorage<boolean> };
+const childSessionContext = globals[contextKey] ?? new AsyncLocalStorage<boolean>();
+globals[contextKey] = childSessionContext;
 
 export function inChildSessionContext(): boolean {
   return childSessionContext.getStore() === true;
@@ -13,3 +19,15 @@ export function inChildSessionContext(): boolean {
 export function runInChildSessionContext<T>(fn: () => Promise<T>): Promise<T> {
   return childSessionContext.run(true, fn);
 }
+
+/**
+ * Make every future `reload()` of a child session's loader run in the child
+ * context. A session reload (e.g. an extension calling `ctx.reload()`) calls
+ * `loader.reload()` again and re-runs each extension factory, long after the
+ * construction-time {@link runInChildSessionContext} has exited.
+ */
+export function bindChildResourceLoader<T extends { reload(): Promise<void> }>(loader: T): T {
+  const reload = loader.reload.bind(loader);
+  loader.reload = () => runInChildSessionContext(reload);
+  return loader;
+}

package/src/completion-outbox.ts

@@ -27,18 +27,28 @@ export const NOTIFICATION_HOLD_MS = 200;
 export interface OutboxMessage {
   content: string;
   details: NotificationDetails;
+  /** Agents whose whole result the content carries: sending it reads their result. */
+  delivered?: string[];
+  /** Agents whose whole result the content carries, failures included: the parent has seen it, though it stays unread in FleetView. */
+  noticed?: string[];
 }
 
 /**
  * A notification for one or more agents, built when they finished: a resume
  * before the send must not rewrite it. Reading an agent's result cancels its
- * id, and an item left with none is dropped; `build` gets the ids still pending.
+ * id, and an item left with none is dropped; `build` gets the ids still pending
+ * and the result length the batch allots each (see `notification-result.ts`).
  */
 export interface OutboxItem {
   ids: string[];
-  build(ids: readonly string[]): OutboxMessage;
+  /** Each agent's full result length, for the batch to split its budget by. */
+  resultChars?: Readonly<Record<string, number>>;
+  build(ids: readonly string[], caps: Readonly<Record<string, number>>): OutboxMessage;
 }
 
+/** Result length per agent of one batch, from each agent's full length. */
+export type ResultAllotment = (chars: Readonly<Record<string, number>>) => Record<string, number>;
+
 export class CompletionOutbox {
   private items: OutboxItem[] = [];
   private timer: TimerHandle | undefined;
@@ -50,6 +60,8 @@ export class CompletionOutbox {
     private parentRunning: () => boolean,
     /** Shared with the scheduler by hosts that control time in-process. */
     private clock: Clock = realClock,
+    /** Splits a batch's result budget; by default nothing is allotted and each item keeps its own cap. */
+    private allot: ResultAllotment = () => ({}),
   ) {}
 
   /** A newer completion of the same agent (a resume) replaces its pending one. */
@@ -101,7 +113,10 @@ export class CompletionOutbox {
     this.timer = undefined;
     const items = this.items;
     this.items = [];
-    const messages = items.map(item => item.build(item.ids));
+    const chars: Record<string, number> = {};
+    for (const item of items) for (const id of item.ids) if (item.resultChars?.[id] !== undefined) chars[id] = item.resultChars[id];
+    const caps = this.allot(chars);
+    const messages = items.map(item => item.build(item.ids, caps));
     return messages.length > 0 ? combine(messages) : undefined;
   }
 
@@ -118,8 +133,12 @@ export class CompletionOutbox {
 function combine(messages: OutboxMessage[]): OutboxMessage {
   if (messages.length === 1) return messages[0];
   const [first, ...rest] = messages.flatMap(({ details: { others, ...own } }) => [own, ...(others ?? [])]);
+  const delivered = messages.flatMap(m => m.delivered ?? []);
+  const noticed = messages.flatMap(m => m.noticed ?? []);
   return {
     content: `${messages.length} background tasks finished.\n\n${messages.map(m => m.content).join("\n\n")}`,
     details: { ...first, others: rest },
+    ...(delivered.length > 0 ? { delivered } : {}),
+    ...(noticed.length > 0 ? { noticed } : {}),
   };
 }

package/src/cross-extension-rpc.ts

@@ -14,8 +14,9 @@
  */
 
 import { isTopLevelAgent } from "./agent-manager.js";
-import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { checkModelScope } from "./model-scope.js";
+import type { ModelRegistry } from "./model-resolver.js";
+import { selectModel } from "./model-selection.js";
+import { planSteerBlocked, planSteerRefusal } from "./plan-mode-children.js";
 import type { AgentRecord } from "./types.js";
 
 /** Minimal event bus interface needed by the RPC handlers. */
@@ -39,11 +40,11 @@ export interface SpawnCapable {
   awaitStartup(id: string): Promise<void>;
   abort(id: string): boolean;
   /**
-   * The record behind an id, for the stop handler's ownership check. Narrowed
-   * to the two fields `isTopLevelAgent` reads, so the RPC layer keeps its
-   * deliberately shallow view of the manager.
+   * The record behind an id, for the stop and steer handlers' ownership check
+   * and the steer handler's Plan check. Narrowed to the fields those read, so
+   * the RPC layer keeps its deliberately shallow view of the manager.
    */
-  getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId"> | undefined;
+  getRecord(id: string): Pick<AgentRecord, "parentAgentId" | "workflowId" | "status" | "planGate"> | undefined;
   /**
    * Mark a settled agent's result as read by the caller, suppressing the
    * completion notification — what `get_subagent_result` does when it returns
@@ -58,6 +59,7 @@ export interface SpawnCapable {
 }
 
 export interface RpcDeps {
+  homeDir?: string;
   events: EventBus;
   pi: unknown;                    // passed through to manager.spawn
   getCtx: () => unknown | undefined;  // returns current ExtensionContext
@@ -112,13 +114,9 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
       const ctx = getCtx();
       if (!ctx) throw new Error("No active session");
 
-      // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
-      // forward serializable values, so options.model can be a string like
-      // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
-      // — same pattern the scheduler path already uses — so the spawned
-      // agent's auth lookup doesn't crash with "No API key found for
-      // undefined".
-      let normalizedOptions = options ?? {};
+      // Validate serializable overrides through the shared selector. Preserve
+      // the raw request for spawn, which records its source and outcome.
+      const normalizedOptions = options ?? {};
       // `!= null` on purpose: a JSON-forwarding caller can serialize an unset
       // field as null, and the runner reads `options.model ?? default`, so null
       // means "inherit" — not an override to resolve or scope-check.
@@ -131,34 +129,12 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
         if (!modelRegistry) {
           throw new Error(`Model override "${label}" provided but ctx.modelRegistry is unavailable`);
         }
-        let model = override;
-        if (typeof override === "string") {
-          const resolved = resolveModel(override, modelRegistry);
-          if (typeof resolved === "string") {
-            // resolveModel returns a human-readable error string when the
-            // input doesn't match any available model. Surface it instead of
-            // silently falling back so the caller sees the auth/typo issue.
-            throw new Error(resolved);
-          }
-          model = resolved;
-          normalizedOptions = { ...normalizedOptions, model: resolved };
-        }
-
-        // A model on the RPC payload is an orchestrator-level choice, exactly
-        // like Agent({ model }) — so it gets the Agent tool's hard error, never
-        // the frontmatter warn (#240). The check reads the RESOLVED model:
-        // resolveModel is fuzzy, so a bare "sonnet" can land on a provider the
-        // caller never named. Frontmatter-pinned and parent-inherited models are
-        // resolved later, in agent-runner, and keep warn-and-proceed.
-        const verdict = checkModelScope({
-          model,
-          cwd: cwd ?? process.cwd(),
-          modelRegistry,
-          callerSupplied: true,
-          agentLabel: type,
-          modelInput: label,
+        const selection = selectModel({
+          homeDir: deps.homeDir,
+          agentType: type, paramModel: override, parentModel: undefined,
+          registry: modelRegistry, cwd: cwd ?? process.cwd(),
         });
-        if (verdict.kind === "error") throw new Error(verdict.message);
+        if (typeof selection === "string") throw new Error(selection);
       }
 
       const id = manager.spawn(pi, ctx, type, prompt, normalizedOptions);
@@ -177,10 +153,11 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   // a live hole: no RPC hands out agent ids, so a caller has no ordinary way to
   // name one it does not own — but the guard is cheap and the id may leak some
   // other way. Same refuse-what-we-should-not-touch stance as `consume` below.
-  const assertOwned = (agentId: string): void => {
+  const assertOwned = (agentId: string) => {
     const record = manager.getRecord(agentId);
     if (!record) throw new Error("Agent not found");
     if (!isTopLevelAgent(record)) throw new Error("Agent is owned by another agent or workflow");
+    return record;
   };
 
   const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
@@ -212,7 +189,9 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
   const unsubSteer = handleRpc<{ requestId: string; agentId: string; message: unknown }>(
     events, "subagents:rpc:steer", ({ agentId, message }) => {
       if (typeof message !== "string" || message.trim().length === 0) throw new Error("Steer message must be a non-empty string");
-      assertOwned(agentId);
+      const record = assertOwned(agentId);
+      // Same refusal as `steer_subagent`, so another extension cannot steer a pre-Plan agent into edits.
+      if (planSteerBlocked(record, events)) throw new Error(planSteerRefusal(agentId));
       if (!manager.steer(agentId, message)) throw new Error("Agent is not running");
     },
   );

package/src/custom-agents.ts

@@ -4,8 +4,10 @@
 
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, join } from "node:path";
-import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+import { errorMessage } from "./error-message.js";
+import { resolveAgentDir } from "./home-paths.js";
 import {
   isPackageResourceExcluded,
   isProjectTrusted,
@@ -55,6 +57,8 @@ export interface LoadCustomAgentsOptions {
    * answer is recorded.
    */
   projectTrusted?: boolean;
+  /** Home directory for the default global agent directory. Defaults at call time. */
+  homeDir?: string;
 }
 
 /**
@@ -94,16 +98,17 @@ export function loadCustomAgents(
   strict = false,
   opts: LoadCustomAgentsOptions = {},
 ): Map<string, AgentConfig> {
-  const globalDir = join(getAgentDir(), "agents");
+  const globalDir = join(resolveAgentDir(opts.homeDir), "agents");
   const workspaceProjectDir = join(cwd, ".agents", "agents");
   const projectDir = join(cwd, ".pi", "agents");
 
   const projectTrusted = opts.projectTrusted ?? isProjectTrusted();
-  const pkgDirs = opts.packageDirs ?? packageAgentDirs(cwd, { projectTrusted });
-  const pkgFiles = opts.packageFiles ?? packageAgentFiles(cwd, { projectTrusted });
+  const discovery = { projectTrusted, homeDir: opts.homeDir };
+  const pkgDirs = opts.packageDirs ?? packageAgentDirs(cwd, discovery);
+  const pkgFiles = opts.packageFiles ?? packageAgentFiles(cwd, discovery);
   // `!./agents/wip.md` alongside `./agents` excludes one file out of a directory
   // that is only enumerated here, so the check has to run per file.
-  const excluded: Excluder = opts.packageExcluded ?? (path => isPackageResourceExcluded(path, cwd, "agents", { projectTrusted }));
+  const excluded: Excluder = opts.packageExcluded ?? (path => isPackageResourceExcluded(path, cwd, "agents", discovery));
 
   const agents = new Map<string, AgentConfig>();
   for (const dir of pkgDirs) loadFromDir(dir, agents, "package", strict, excluded); // lowest priority
@@ -286,7 +291,7 @@ function readAgentFile(path: string, strict: boolean): { frontmatter: Record<str
   try {
     return parseAgentFrontmatter<Record<string, unknown>>(readFileSync(path, "utf-8"));
   } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
+    const reason = errorMessage(err);
     if (strict) throw new Error(`${path}: ${reason}`);
     warnIfNew(`Skipping agent file ${path}: ${reason}`);
     return undefined;

package/src/default-agents.ts

@@ -6,7 +6,17 @@
 
 import type { AgentConfig } from "./types.js";
 
-const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+/**
+ * Tool surface shared by Explore and Plan. `bash` is left out because a prompt cannot
+ * make an unrestricted shell read-only, and extensions are off because extension tools
+ * can run commands or write. A `.pi/agents/<Name>.md` override can opt back in with an
+ * explicit `extensions:` list.
+ */
+const READ_ONLY_SURFACE: Pick<AgentConfig, "builtinToolNames" | "extensions" | "skills"> = {
+  builtinToolNames: ["read", "grep", "find", "ls"],
+  extensions: false,
+  skills: true,
+};
 
 export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
   [
@@ -31,13 +41,9 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       name: "Explore",
       displayName: "Explore",
       description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.",
-      builtinToolNames: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
-      // Fast/cheap portable default for read-only search. A target-local alias
-      // can select its canonical provider; otherwise fuzzy resolution finds a
-      // matching enabled model under any provider.
-      model: "claude-haiku-4-5",
+      ...READ_ONLY_SURFACE,
+      // Bind the role per machine, not to a provider or model generation.
+      model: "@cheap",
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
@@ -51,13 +57,10 @@ You are STRICTLY PROHIBITED from:
 - Using redirect operators (>, >>, |) or heredocs to write to files
 - Running ANY commands that change system state
 
-Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
-
 # Tool Usage
-- Use the find tool for file pattern matching (NOT the bash find command)
-- Use the grep tool for content search (NOT bash grep/rg command)
-- Use the read tool for reading files (NOT bash cat/head/tail)
-- Use Bash ONLY for read-only operations
+- Use the find tool for file pattern matching
+- Use the grep tool for content search
+- Use the read tool for reading files
 - Make independent tool calls in parallel for efficiency
 - Adapt search approach based on thoroughness level specified
 
@@ -76,9 +79,7 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
       name: "Plan",
       displayName: "Plan",
       description: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
-      builtinToolNames: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
+      ...READ_ONLY_SURFACE,
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a software architect and planning specialist.
 Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
@@ -106,10 +107,9 @@ You are STRICTLY PROHIBITED from:
 - Follow existing patterns where appropriate
 
 # Tool Usage
-- Use the find tool for file pattern matching (NOT the bash find command)
-- Use the grep tool for content search (NOT bash grep/rg command)
-- Use the read tool for reading files (NOT bash cat/head/tail)
-- Use Bash ONLY for read-only operations
+- Use the find tool for file pattern matching
+- Use the grep tool for content search
+- Use the read tool for reading files
 
 # Output Format
 - Use absolute file paths

package/src/detached-results.ts

@@ -13,7 +13,9 @@ import { createHash } from "node:crypto";
 import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import type { AgentRecord } from "./types.js";
+import type { EvictedNote } from "./agent-manager.js";
+import type { NoticeParts } from "./notification-result.js";
+import type { AgentRecord, AgentTombstone } from "./types.js";
 import type { AgentActivity } from "./ui/agent-widget.js";
 
 /** One finished agent, in the shape `session_start` needs to re-announce it. */
@@ -25,6 +27,14 @@ export interface DetachedResult {
   details: unknown;
   /** History entry for a result that finished detached; absent if already appended. */
   record?: Record<string, unknown>;
+  /** The `subagents:completed`/`subagents:failed` event the live path would have emitted, replayed on delivery. */
+  lifecycle?: { channel: "subagents:completed" | "subagents:failed"; data: Record<string, unknown> };
+  /** What the reopened session keeps so these agents' ids still answer after their records are gone. */
+  evicted?: EvictedNote[];
+  /** Reopenable sessions among them, so a steer or resume of these ids continues the saved conversation. */
+  tombstones?: AgentTombstone[];
+  /** A full-result notice's parts, so delivery clips it against its batch's budget; `content` is the fallback. */
+  notice?: NoticeParts & { footer: string };
 }
 
 const SINK_KEY = Symbol.for("pi-subagents:detached-sink");
@@ -96,7 +106,8 @@ export function watchDetached(sessionFile: string, onSpooled: () => void): () =>
 export interface RunningDetached {
   record: AgentRecord;
   activity?: AgentActivity;
-  abort(): boolean;
+  /** `by` as for `AgentManager.abort`: `"parent"` for `stop_subagent`, omitted for a human. */
+  abort(by?: AgentRecord["stoppedBy"]): boolean;
   steer(message: string): boolean;
 }
 
@@ -127,6 +138,11 @@ export function unregisterRunningDetached(sessionFile: string, id: string): void
   if (byId?.size === 0) running().delete(sessionFile);
 }
 
+/** Every orphan still running in the process with the session file it is registered (and wakes) under. */
+export function listAllRunningDetached(): Array<{ sessionFile: string; agent: RunningDetached }> {
+  return [...running()].flatMap(([sessionFile, byId]) => [...byId.values()].map((agent) => ({ sessionFile, agent })));
+}
+
 /** Orphans still running for `sessionFile`, in registration order. */
 export function listRunningDetached(sessionFile: string | undefined): RunningDetached[] {
   if (sessionFile === undefined) return [];

package/src/enabled-models.ts

@@ -28,7 +28,7 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { resolveAgentDir } from "./home-paths.js";
 import type { ModelEntry } from "./model-resolver.js";
 
 /** Minimal registry shape — only the methods resolveEnabledModels actually calls. */
@@ -38,10 +38,10 @@ export interface ModelRegistryRef {
 }
 
 /** Paths to pi's settings.json files: [project, global] (project takes precedence). */
-function settingsPaths(cwd: string): [project: string, global: string] {
+function settingsPaths(cwd: string, homeDir?: string): [project: string, global: string] {
   return [
     join(cwd, ".pi", "settings.json"),
-    join(getAgentDir(), "settings.json"),
+    join(resolveAgentDir(homeDir), "settings.json"),
   ];
 }
 
@@ -63,8 +63,8 @@ function readField(path: string): string[] | undefined {
  * (and matches our own loadSettings precedence in src/settings.ts).
  * Returns undefined when neither file has the field.
  */
-export function readEnabledModels(cwd: string): string[] | undefined {
-  const [project, global] = settingsPaths(cwd);
+export function readEnabledModels(cwd: string, homeDir?: string): string[] | undefined {
+  const [project, global] = settingsPaths(cwd, homeDir);
   return readField(project) ?? readField(global);
 }
 
@@ -102,11 +102,12 @@ export function resolveEnabledModels(
   patterns: string[] | undefined,
   registry: ModelRegistryRef,
   cwd: string = process.cwd(),
+  homeDir?: string,
 ): Set<string> | undefined {
   // Fast path: check cache (stat both project and global settings.json files)
   const patternsKey = JSON.stringify(patterns);
-  const [project, global] = settingsPaths(cwd);
-  const fileHash = `${hashOf(project)};${hashOf(global)}`;
+  const [project, global] = settingsPaths(cwd, homeDir);
+  const fileHash = `${project}:${hashOf(project)};${global}:${hashOf(global)}`;
 
   if (fileHash === cachedHash && patternsKey === cachedPatternsKey) {
     return cachedAllowed;

package/src/enterprise-local.ts

@@ -8,7 +8,8 @@
 
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { errorMessage } from "./error-message.js";
+import { resolveAgentDir } from "./home-paths.js";
 
 const MANIFEST_VERSION = 1;
 const MANIFEST_NAME = "enterprise.local.json";
@@ -21,16 +22,16 @@ export interface EnterpriseLocalManifest {
 }
 
 /** Return the target-local manifest path without reading it. */
-export function enterpriseLocalPath(): string {
-  return join(getAgentDir(), MANIFEST_NAME);
+export function enterpriseLocalPath(homeDir?: string): string {
+  return join(resolveAgentDir(homeDir), MANIFEST_NAME);
 }
 
 /**
  * Read and minimally validate the machine-local manifest. It never exposes its
  * contents in diagnostics: providers can include command-backed credentials.
  */
-export function readEnterpriseLocalManifest(): EnterpriseLocalManifest | undefined {
-  const path = enterpriseLocalPath();
+export function readEnterpriseLocalManifest(homeDir?: string): EnterpriseLocalManifest | undefined {
+  const path = enterpriseLocalPath(homeDir);
   if (!existsSync(path)) return undefined;
 
   try {
@@ -59,7 +60,7 @@ export function readEnterpriseLocalManifest(): EnterpriseLocalManifest | undefin
     }
     return manifest as unknown as EnterpriseLocalManifest;
   } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
+    const reason = errorMessage(error);
     console.warn(`[pi-subagents] Ignoring invalid ${path}: ${reason}`);
     return undefined;
   }

package/src/error-message.ts

@@ -0,0 +1,11 @@
+/**
+ * error-message.ts — the text a caught value reports.
+ *
+ * `catch` binds `unknown`: an `Error` gives its message, and anything else a
+ * caller threw (a string, a rejected non-Error) is stringified as-is.
+ */
+
+/** The message of `error` when it is an `Error`, else `String(error)`. */
+export function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/git-path.ts

@@ -0,0 +1,66 @@
+/**
+ * git-path.ts -- decode the C-style quoted paths git prints without `-z`.
+ *
+ * `pi.exec` decodes each stdout chunk as UTF-8 on its own, so a multibyte
+ * character split across two chunks becomes U+FFFD. With `core.quotePath=true`
+ * git escapes every non-ASCII byte (and control characters, `"` and `\`) as
+ * `"..."` with octal escapes, so a listing read without `-z` is pure ASCII and
+ * survives any chunking; this module turns it back into the real path.
+ */
+
+const SIMPLE_ESCAPES: Record<string, number> = {
+  a: 0x07,
+  b: 0x08,
+  f: 0x0c,
+  n: 0x0a,
+  r: 0x0d,
+  t: 0x09,
+  v: 0x0b,
+  '"': 0x22,
+  "\\": 0x5c,
+};
+
+const UTF8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+/** Args that make `git` quote every non-ASCII path byte; put them before the subcommand. */
+export const QUOTE_PATH_ARGS = ["-c", "core.quotePath=true"];
+
+/**
+ * Decode one path as git prints it: a plain name is returned as is, a `"..."` name is
+ * unescaped to bytes and decoded as UTF-8. Throws on anything that cannot name a file
+ * as a JS string: raw non-ASCII (the listing was not quoted, so it may be mis-decoded),
+ * a malformed escape, or bytes that are not valid UTF-8.
+ */
+export function unquoteGitPath(text: string): string {
+  const quoted = text.length >= 2 && text.startsWith('"') && text.endsWith('"');
+  const body = quoted ? text.slice(1, -1) : text;
+  for (let i = 0; i < body.length; i++) {
+    if (body.charCodeAt(i) > 0x7f) throw new Error(`git printed a non-ASCII path unquoted (${JSON.stringify(text)}); it may be mis-decoded`);
+  }
+  if (!quoted) return text;
+  const bytes: number[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const char = body.charAt(i);
+    if (char === '"') throw new Error(`malformed quoted git path ${JSON.stringify(text)}`);
+    if (char !== "\\") {
+      bytes.push(body.charCodeAt(i));
+      continue;
+    }
+    const next = body.charAt(i + 1);
+    const octal = /^[0-3][0-7]{2}$/.test(body.slice(i + 1, i + 4)) ? body.slice(i + 1, i + 4) : undefined;
+    if (octal) {
+      bytes.push(Number.parseInt(octal, 8));
+      i += 3;
+    } else if (next in SIMPLE_ESCAPES) {
+      bytes.push(SIMPLE_ESCAPES[next] as number);
+      i += 1;
+    } else {
+      throw new Error(`malformed escape in quoted git path ${JSON.stringify(text)}`);
+    }
+  }
+  try {
+    return UTF8.decode(Uint8Array.from(bytes));
+  } catch {
+    throw new Error(`git path ${JSON.stringify(text)} is not valid UTF-8 and cannot be inspected`);
+  }
+}

package/src/group-join.ts

@@ -15,7 +15,6 @@ interface AgentGroup {
   agentIds: Set<string>;
   completedRecords: Map<string, AgentRecord>;
   timeoutHandle?: ReturnType<typeof setTimeout>;
-  delivered: boolean;
   /** Shorter timeout for stragglers after a partial delivery. */
   isStraggler: boolean;
 }
@@ -40,7 +39,6 @@ export class GroupJoinManager {
       groupId,
       agentIds: new Set(agentIds),
       completedRecords: new Map(),
-      delivered: false,
       isStraggler: false,
     };
     this.groups.set(groupId, group);
@@ -61,7 +59,7 @@ export class GroupJoinManager {
     if (!groupId) return 'pass';
 
     const group = this.groups.get(groupId);
-    if (!group || group.delivered) return 'pass';
+    if (!group) return 'pass';
 
     group.completedRecords.set(record.id, record);
 
@@ -83,7 +81,6 @@ export class GroupJoinManager {
   }
 
   private onTimeout(group: AgentGroup): void {
-    if (group.delivered) return;
     group.timeoutHandle = undefined;
 
     // Partial delivery — some agents still running
@@ -112,18 +109,15 @@ export class GroupJoinManager {
       clearTimeout(group.timeoutHandle);
       group.timeoutHandle = undefined;
     }
-    group.delivered = true;
     this.deliverCb([...group.completedRecords.values()], partial);
-    this.cleanupGroup(group.groupId);
+    this.cleanupGroup(group);
   }
 
-  private cleanupGroup(groupId: string): void {
-    const group = this.groups.get(groupId);
-    if (!group) return;
+  private cleanupGroup(group: AgentGroup): void {
     for (const id of group.agentIds) {
       this.agentToGroup.delete(id);
     }
-    this.groups.delete(groupId);
+    this.groups.delete(group.groupId);
   }
 
   /** Check if an agent is in a group. */

package/src/home-paths.ts

@@ -0,0 +1,27 @@
+/** User-scoped paths. Omitted homes keep Pi's call-time runtime defaults. */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Mirror Pi's agent-dir override semantics without changing the process environment. */
+export function resolveAgentDir(homeDir?: string): string {
+  if (homeDir === undefined) return getAgentDir();
+  const configured = process.env.PI_CODING_AGENT_DIR;
+  if (!configured) return join(homeDir, ".pi", "agent");
+  return normalizeHomePath(configured, homeDir);
+}
+
+/** Pi's normalizePath is not exported by its public package entry point. */
+export function normalizeHomePath(path: string, homeDir = homedir()): string {
+  // Match Pi's native normalization of Git Bash, WSL and Cygwin drive paths.
+  if (process.platform === "win32" && path.startsWith("/") && !path.startsWith("//") && !path.includes("\\")) {
+    const [, letter, remainder] = path.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i) ?? [];
+    if (letter) path = `${letter.toUpperCase()}:\\${remainder?.replaceAll("/", "\\") ?? ""}`;
+  }
+  if (path === "~") return homeDir;
+  if (path.startsWith("~/") || (process.platform === "win32" && path.startsWith("~\\"))) {
+    return join(homeDir, path.slice(2));
+  }
+  return path.startsWith("file://") ? fileURLToPath(path) : path;
+}