pi-orchestrator-config 4.25.0 → 4.26.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [4.26.1] - 2026-11-06
+
+- The tmp sweep carries no hardcoded control-file name list: it asks
+  `daemon-manager.isLiveLegacyDaemonFile()`, which owns the two legacy names, so a future daemon
+  writing to `.pi/run` can never require the sweep to be edited. A legacy `pidiff.port`/`pidiff.pid`
+  is kept only while its recorded PID is alive (`EPERM` counts as alive — another user's running
+  process), and a dead daemon's leftovers plus every `reload.*` marker are swept like any other
+  entry. Deleting a live daemon's lockfiles would make the next connect() spawn a duplicate on its
+  port.
+- A control file can no longer block or exhaust a session: `readLockfile` accepts only regular
+  files, so a project FIFO at `pidiff.port`/`pidiff.pid` is ignored, and the pid read is capped at
+  64 bytes so an oversized file is rejected without being read.
+
+## [4.26.0] - 2026-11-06
+
+- Async `chain` mode: steps run in sequence and each step's result is substituted into `{previous}`,
+  with per-step `taskId`/`cwd`, the step position in the status line and result header, a durable
+  `chain.json` for reload reporting, and stop-on-failure. `onComplete` receives `{ text, isError }` and
+  fires exactly once, so a retried reconciliation pass cannot spawn the next step twice.
+- A tool call pi rejects for invalid arguments now forces a retry. Such a call skips `tool_call` and
+  `tool_result`, so nothing told the model its action never ran and a turn could end silently. The guard
+  matches pi's own rejection preamble, keeps only the parameter diagnostics (argument values can hold
+  credentials and the system note is a provenance-marked channel), and names the likely mistake.
+- The UI bridge degrade path honours an approval again: without `ctx.ui.custom`, `confirm` returned a
+  boolean while the wrapper compared `"__confirmed__"`, so every prompt in that runtime cancelled.
+
 ## [4.25.0] - 2026-11-06
 
 - `.pi/tmp` is cleaned at session start: above `project_tmp_max_size` (default `2G`), entries older than

package/README.md

@@ -12,9 +12,9 @@ Single extension that provides:
 
 | Feature                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Subagent tool**             | Delegate tasks to specialist agents (single, parallel, chain, async modes); optional `model` param for model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| **Subagent tool**             | Delegate tasks to specialist agents (single, parallel, chain, async, and async-chain modes); optional `model` param for model override. Chains also run async: every step needs its own `taskId` and `cwd`, each step receives the previous step's output as `{previous}`, and a failed step stops the chain                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | **`list_models`**             | List available models and providers for subagent model override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| **Async background agents**   | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`: `x` kills, `Space` multi-selects, `a` kills all). On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `docs/cli-provider.md`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| **Async background agents**   | Spawn agents in background with `async: true` — results surface automatically when complete. Fullscreen overlay dashboard with live output, keyboard nav, and kill support (`/async-status`: `x` kills, `Space` multi-selects, `a` kills all). Async applies to chains too: step 1 spawns immediately and each step starts when the previous one ends. On **acpx** parents, optional async is coerced to sync; dream/cron need `internal_operations_provider` + `internal_operations_model`. `cli-*` providers support async natively (see `docs/cli-provider.md`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | **CLI / ACPX providers**      | Optional `cli_agents` / `acpx_agents` register `cli-*` / `acpx-*` via native `createProvider` (pi ≥ 0.84): `/login cli-<agent>` or `/login acpx-<agent>`, model refresh, filter when unavailable. Missing context window / maxTokens / cost filled from models.dev (`~/.pi/pi-config/models.dev.json`, 1-day refresh). Cold-start default restore (#753): gates `startup`\|`resume` (`new` only when no model is selected), empty `enabledModels`, trusted project merge — see `docs/cli-provider.md`. Headless Cursor `--approve-mcps` when `CLI_APPROVE_MCPS` is set (`false` opts out) or the process is a sidecar (`SIDECAR_PORT`; `startSidecar()` stamps it while running and restores it on `close()`). Executable sidecar consumers should call `bindSidecarListenExit()` so bind/`stopped` fatals exit 1. Headless Gemini defaults `GEMINI_CLI_TRUST_WORKSPACE=true` and preserves an explicit parent value (including `false`). |
 | **`/async-status` command**   | Show status of background agents — select one for live output streaming, multi-select and kill (`x`), or kill everything (`a`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | **`ask_user` tool**           | Structured user input with options and free-text — used by workflows                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

package/extensions/orchestrator/async-agents.ts

@@ -35,6 +35,7 @@ import { setSlot } from "./status-bar.js";
 import { getSetting } from "./project-settings.js";
 import { substituteSettingsPlaceholders } from "./rule-placeholders.js";
 import { isLiveExtensionCtx } from "../shared/live-ctx.js";
+import { sendSystemNote } from "../shared/system-note.js";
 
 const SETTINGS_KEYS: Record<string, unknown> = JSON.parse(
   fs.readFileSync(
@@ -66,7 +67,8 @@ export interface AsyncJob {
   delivered?: boolean;
   sideEffectsApplied?: boolean;
   fireAndForget?: boolean;
-  onComplete?: () => void;
+  /** One-shot: fires once with the ingested result text. Used by async chains to feed {previous}. */
+  onComplete?: (result: { text: string; isError: boolean }) => void;
   groupId?: string;
   taskId?: string;
   cwd?: string;
@@ -87,6 +89,26 @@ export interface AsyncJob {
  */
 export type AsyncKillOrigin = "user" | "orchestrator" | "task-system";
 
+/** Durable record of an async chain's position, written into each step's workerDir
+ *  as chain.json. The step's continuation lives in the onComplete closure, which a
+ *  reload destroys — this file is what lets restoration report the chain instead of
+ *  dropping it silently. */
+export interface AsyncChainState {
+  steps: Array<{ agent: string; task: string }>;
+  /** Index (0-based) of the step being spawned when this was written. */
+  index: number;
+  previous: string;
+  /** Set once restoration has reported this chain as interrupted. */
+  interruptedAt?: number;
+}
+
+function readChainState(workerDir: string): AsyncChainState | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(path.join(workerDir, "chain.json"), "utf-8"));
+    return Array.isArray(parsed?.steps) ? parsed as AsyncChainState : null;
+  } catch { return null; }
+}
+
 /** Human-readable attribution per origin. The single source for every surface. */
 export const KILL_ORIGIN_LABELS: Record<AsyncKillOrigin, string> = {
   user: "Killed by user",
@@ -99,6 +121,32 @@ function jobCwd(job: { cwd?: string; projectCwd?: string }): string {
   return job.cwd || job.projectCwd || process.cwd();
 }
 
+/** Fire the job's completion hook exactly once, with the already-ingested result.
+ *  Clearing it first stops the reconciliation pass from re-firing it (which would
+ *  spawn the next async-chain step twice after a failed delivery). */
+export function fireOnComplete(job: AsyncJob): void {
+  const cb = job.onComplete;
+  job.onComplete = undefined;
+  if (!cb) return;
+  try {
+    cb({ text: typeof job.output === "string" ? job.output : "", isError: job.status === "failed" });
+  } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
+}
+
+/** Fire every pending completion hook in one reconciliation pass.
+ *  Returns how many fired. Exported so the PASS is testable, not just the
+ *  single-job helper — the hook-once guarantee is a property of the loop. */
+export function firePendingCompletions(jobs: Iterable<AsyncJob>): number {
+  let fired = 0;
+  for (const job of jobs) {
+    if (!job.onComplete) continue;
+    fireOnComplete(job);
+    fired++;
+  }
+  if (fired > 0) log.info("fire_pending_completions", { fired });
+  return fired;
+}
+
 interface AsyncState {
   jobs: Map<string, AsyncJob>;
   poller: ReturnType<typeof setInterval> | null;
@@ -145,7 +193,7 @@ export function registerAsyncAgents(
     discoverAgents?: (cwd: string, scope: "both") => Pick<AgentDiscoveryResult, "agents">;
   } = {},
 ): {
-  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean; explicit?: { model?: string; provider?: string } }) => { id: string; error?: string; model?: string };
+  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: (result: { text: string; isError: boolean }) => void; persistSession?: boolean; explicit?: { model?: string; provider?: string }; chain?: AsyncChainState }) => { id: string; error?: string; model?: string };
   killAsyncAgent: (target: string, origin?: AsyncKillOrigin) => { killed: string[]; errors: string[] };
   getAsyncJobs: () => Array<{ id: string; agent: string; name?: string; task: string; status: string; startedAt: number }>;
 } {
@@ -625,9 +673,7 @@ export function registerAsyncAgents(
                   content: msgContent,
                   display: true,
                 }, { triggerTurn: true, deliverAs: "followUp" });
-                if (job.onComplete) {
-                  try { job.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
-                }
+                fireOnComplete(job);
                 job.delivered = true;
                 recordDelivered(job.id);
                 log.debug("reconcile_deliver_ok", job.id);
@@ -646,9 +692,7 @@ export function registerAsyncAgents(
               } catch {}
             }
           } else if (job.fireAndForget) {
-            if (job.onComplete) {
-              try { job.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
-            }
+            fireOnComplete(job);
             job.delivered = true;
           }
         }
@@ -719,12 +763,8 @@ export function registerAsyncAgents(
 
     // Skip delivery if ALL jobs in group are fire-and-forget
     if (groupJobs.every(j => j.fireAndForget)) {
-      for (const j of groupJobs) {
-        if (j.onComplete) {
-          try { j.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${j.id}: ${e?.message}`); }
-        }
-        j.delivered = true;
-      }
+      firePendingCompletions(groupJobs);
+      for (const j of groupJobs) j.delivered = true;
       // Clean up result files for fire-and-forget groups
       for (const j of groupJobs) {
         const rp = path.join(ASYNC_RESULTS_DIR, `${j.id}.json`);
@@ -986,10 +1026,8 @@ export function registerAsyncAgents(
         sendSucceeded = true; // fire-and-forget doesn't need sendMessage
       }
 
-      // Invoke onComplete callback if registered (e.g., dreaming → rebuildAndOrganize)
-      if (job.onComplete) {
-        try { job.onComplete(); } catch (e: any) { log.error(`onComplete callback failed for ${job.id}: ${e?.message}`); }
-      }
+      // Invoke onComplete callback if registered (e.g., dreaming, async chain step)
+      fireOnComplete(job);
       if (sendSucceeded) {
         job.delivered = true;
         // Persist delivered state so restore skips this job
@@ -1035,7 +1073,7 @@ export function registerAsyncAgents(
     task: string,
     cwd: string,
     agents: AgentConfig[],
-    options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: () => void; persistSession?: boolean; explicit?: { model?: string; provider?: string } },
+    options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; onComplete?: (result: { text: string; isError: boolean }) => void; persistSession?: boolean; explicit?: { model?: string; provider?: string }; chain?: AsyncChainState },
   ): { id: string; error?: string; model?: string } {
     const agent = agents.find(a => a.name === agentName);
     if (!agent) return { id: "", error: `Unknown agent: "${agentName}"` };
@@ -1070,6 +1108,12 @@ export function registerAsyncAgents(
       sessionId: getLiveAsyncCtx()?.sessionManager?.getSessionId?.() || null,
     }), { mode: 0o600 });
 
+    // Chain position — a reload drops the onComplete continuation, so restore reads
+    // this file to report the chain it can no longer resume instead of losing it.
+    if (options?.chain) {
+      fs.writeFileSync(path.join(workerDir, "chain.json"), JSON.stringify(options.chain), { mode: 0o600 });
+    }
+
     // Track reviewer spawn BEFORE building args — addReviewerPending sets status to
     // in_progress, so all reviewers in the same batch see consistent state.
     if (agentName.startsWith("code-reviewer-")) {
@@ -1516,6 +1560,22 @@ export function registerAsyncAgents(
           };
           asyncState.jobs.set(id, job);
           log.info(`restored job: ${id} state=${job.status}`);
+
+          // A chain's continuation lived in the onComplete closure this reload destroyed.
+          // chain.json records what was still pending — report it, never drop it silently.
+          const chain = readChainState(job.workerDir);
+          if (chain && chain.interruptedAt === undefined && chain.index + 1 < chain.steps.length) {
+            const remaining = [...new Set(chain.steps.slice(chain.index + 1).map(s => s.agent))];
+            log.error(`async_chain_interrupted: chain interrupted at step ${chain.index + 1} of ${chain.steps.length} (${job.agent}), remaining agents: ${remaining.join(", ")}`);
+            void sendSystemNote(
+              pi,
+              `🚨 Async chain interrupted at step ${chain.index + 1} of ${chain.steps.length} — the extension reloaded, so the chain cannot continue. Step ${chain.index + 1} (${job.agent}) may still be running; steps ${chain.index + 2}-${chain.steps.length} were never spawned. Remaining agents: ${remaining.join(", ")}. Re-run them with subagent(chain: ...).`,
+              { customType: "subagent-chain-error", triggerTurn: true, deliverAs: "followUp" },
+            ).catch((e: any) => log.error(`chain_interrupted note failed: ${e?.message || e}`));
+            // Durable so a second reload does not repeat the note.
+            chain.interruptedAt = Date.now();
+            try { fs.writeFileSync(path.join(job.workerDir, "chain.json"), JSON.stringify(chain), { mode: 0o600 }); } catch {}
+          }
         }
       }
     } catch (e: any) { log.error(`job restore failed: ${e?.message || e}`); }

package/extensions/orchestrator/index.ts

@@ -19,6 +19,7 @@ import { registerAskUser } from "./ask-user.js";
 import { registerAsyncAgents } from "./async-agents.js";
 import { registerDreaming } from "./dreaming.js";
 import { registerEnforcement } from "./enforcement.js";
+import { registerToolArgGuard } from "./tool-arg-guard.js";
 import { registerProjectSettings } from "./project-settings.js";
 import { registerRules } from "./rules.js";
 import { registerSessionValidation } from "./session-validation.js";
@@ -132,6 +133,8 @@ export default function (pi: ExtensionAPI) {
   registerProjectSettings(pi);
   registerTrail(pi);
   registerEnforcement(pi, IN_CONTAINER);
+  // A rejected-before-run tool call must force a retry, not end the turn silently.
+  registerToolArgGuard(pi);
   registerReviewUI(pi);
   registerRules(pi, getAsyncJobs);
 

package/extensions/orchestrator/subagent-tool.ts

@@ -31,6 +31,7 @@ import {
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
+import type { AsyncChainState } from "./async-agents.js";
 
 // Task store access via the pitasks module.
 // `taskStore` is `export let` — a live binding the pitasks extension assigns when it
@@ -107,6 +108,23 @@ const SYNC_TIME_EXCEEDED_ERROR = (seconds: number, limit: number, cwd: string) =
 };
 const MISSING_ESTIMATE_ERROR = "Missing required parameter: estimatedSeconds. Provide an estimated duration in seconds for sync agent tasks.";
 
+/** Cap for the {previous} substitution: the whole task becomes ONE argv entry, so a
+ *  large result would blow past ARG_MAX and fail the next step's spawn. */
+const MAX_PREVIOUS_CHARS = 32_000;
+
+/** Truncate a step result for the next step, saying how much was dropped. */
+function capPrevious(previous: string): string {
+  const dropped = previous.length - MAX_PREVIOUS_CHARS;
+  if (dropped <= 0) return previous;
+  return `${previous.slice(0, MAX_PREVIOUS_CHARS)}\n\n[truncated: ${dropped} of ${previous.length} chars dropped to keep the next step's task argument under the OS limit]`;
+}
+
+/** Substitute {previous} literally — String.replace would expand $&, $$, $' and $` in the result. */
+function withPrevious(task: string, previous: string): string {
+  if (!task.includes("{previous}")) return task;
+  return task.split("{previous}").join(capPrevious(previous));
+}
+
 let syncPenalty = 0;
 let lastSyncAgent = "";
 let lastSyncEstimate = 0;
@@ -139,6 +157,7 @@ const ChainItem = Type.Object({
   }),
   cwd: Type.String({ description: "Working directory" }),
   estimatedSeconds: Type.Number({ description: "Estimated step duration in seconds" }),
+  taskId: Type.Optional(Type.String({ description: "Task ID to auto-complete when this async chain step finishes" })),
 });
 // pi 1.5.0's StringEnum returns a pi-schema Schema, which TypeBox's Static cannot
 // read — params.agentScope degraded to `unknown`. Unsafe keeps the JSON-Schema
@@ -638,7 +657,7 @@ async function validateTaskId(taskId: string, _cwd: string, _sessionId?: string)
 
 export function registerSubagentTool(
   pi: ExtensionAPI,
-  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; persistSession?: boolean; explicit?: { model?: string; provider?: string } }) => { id: string; error?: string; model?: string },
+  spawnAsyncAgent: (agentName: string, task: string, cwd: string, agents: AgentConfig[], options?: { fireAndForget?: boolean; name?: string; parentModelId?: string; parentProvider?: string; groupId?: string; taskId?: string; persistSession?: boolean; explicit?: { model?: string; provider?: string }; chain?: AsyncChainState; onComplete?: (result: { text: string; isError: boolean }) => void }) => { id: string; error?: string; model?: string },
   killAsyncAgent: (target: string, origin?: AsyncKillOrigin) => { killed: string[]; errors: string[] },
 ): void {
   // Only the orchestrator (top-level pi) can spawn subagents.
@@ -668,6 +687,130 @@ export function registerSubagentTool(
     };
   }
 
+  /** Async chain — spawns step 1, and each step's completion hook spawns the next
+   *  with {previous} replaced by that step's result text. */
+  async function executeAsyncChain(
+    params: any,
+    agents: AgentConfig[],
+    mkd: (mode: "single" | "parallel" | "chain") => (results: SingleResult[]) => SubagentDetails,
+    parentModelId: string | undefined,
+    parentProvider: string | undefined,
+    ctx: any,
+    explicit?: { model?: string; provider?: string },
+  ) {
+    const steps = (params.chain ?? []) as Array<{ agent: string; task: string; cwd: string; taskId?: string }>;
+    const total = steps.length;
+    const fail = (text: string) => ({
+      content: [{ type: "text" as const, text }],
+      details: mkd("chain")([]),
+      isError: true,
+    });
+
+    if (total === 0) return fail("Error: chain array is empty — at least one step is required.");
+    for (let i = 0; i < total; i++) {
+      const s = steps[i];
+      if (!s.agent || !s.task) return fail(`Async chain step ${i + 1} requires both agent and task.`);
+      if (!s.cwd) return fail(`${MISSING_CWD_ERROR} (chain step ${i + 1}, agent: ${s.agent})`);
+      if (s.taskId == null) {
+        // Force a follow-up turn so the AI MUST deal with this error, as the other async paths do
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: Async chain call was REJECTED — missing taskId for step ${i + 1} (${s.agent}). NO agents were spawned. You MUST retry with a taskId on every chain step. Use TaskList to find task IDs; "-1" is only for a single read-only check.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
+        return fail(`Missing required parameter: taskId. Every async agent MUST have a taskId (chain step ${i + 1}, agent: ${s.agent}).\n\nIf this step is working on a task: pass the task ID (e.g., taskId: "5")\nIf it is only doing a single read-only check: pass taskId: "-1" (editing or PR work needs a real task id)`);
+      }
+      const taskErr = await validateTaskId(s.taskId, ctx.cwd, ctx.sessionManager?.getSessionId?.());
+      if (taskErr) {
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: ${taskErr} (chain step ${i + 1}, agent: ${s.agent}). NO agents were spawned. Fix the taskId and retry.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
+        return fail(`${taskErr} (chain step ${i + 1}, agent: ${s.agent})`);
+      }
+    }
+    if (syncPenalty > 0) {
+      log.info("sync_penalty_reset", "async chain used");
+      syncPenalty = 0;
+    }
+
+    /** Step names carry the position so the status line and result header say which step ran. */
+    const stepName = (i: number): string =>
+      i === 0 && params.name ? params.name : `${steps[i].agent} (chain ${i + 1}/${total})`;
+
+    /** A step's cwd may hold project agents the parent's cwd does not — discover per step. */
+    const stepAgents = (cwd: string): AgentConfig[] => discoverAgents(cwd, params.agentScope ?? "both").agents;
+
+    const spawnStep = (i: number, prev: string): { id: string; error?: string; model?: string } => {
+      const s = steps[i];
+      const name = stepName(i);
+      log.info("async_chain_step_spawn", { step: i + 1, total, agent: s.agent, name });
+      return spawnAsyncAgent(s.agent, withPrevious(s.task, prev), s.cwd, stepAgents(s.cwd), {
+        name,
+        parentModelId,
+        parentProvider,
+        taskId: s.taskId,
+        persistSession: params.persistSession,
+        explicit,
+        // Durable so a reload can report the chain it can no longer continue.
+        chain: {
+          steps: steps.map(st => ({ agent: st.agent, task: st.task })),
+          index: i,
+          previous: capPrevious(prev),
+        },
+        onComplete: (result) => {
+          if (result.isError) {
+            // Chain stops here — the delivered async result header names this step.
+            log.error("async_chain_step_failed", { step: i + 1, total, agent: s.agent, name, output: result.text.slice(0, 200) });
+            return;
+          }
+          log.info("async_chain_step_complete", { step: i + 1, total, agent: s.agent, name, output_chars: result.text.length });
+          if (i + 1 >= total) {
+            log.info("async_chain_done", { steps: total });
+            return;
+          }
+          log.info("async_chain_next_step", { from: i + 1, to: i + 2, agent: steps[i + 1].agent });
+          let next: { id: string; error?: string; model?: string };
+          try {
+            next = spawnStep(i + 1, result.text);
+          } catch (err) {
+            // A synchronous throw must not escape the completion hook — the chain is dead either way.
+            const reason = String((err as Error)?.message ?? err);
+            log.error("async_chain_next_step_spawn_failed", { step: i + 2, agent: steps[i + 1].agent, error: reason });
+            void sendSystemNote(
+              pi,
+              `🚨 Async chain stopped: step ${i + 2} (${steps[i + 1].agent}) could not be spawned after step ${i + 1} completed — ${reason}`,
+              { customType: "subagent-chain-error", triggerTurn: true, deliverAs: "followUp" },
+            );
+            return;
+          }
+          if (next.error) {
+            log.error("async_chain_next_step_spawn_failed", { step: i + 2, agent: steps[i + 1].agent, error: next.error });
+            void sendSystemNote(
+              pi,
+              `🚨 Async chain stopped: step ${i + 2} (${steps[i + 1].agent}) could not be spawned after step ${i + 1} completed — ${next.error}`,
+              { customType: "subagent-chain-error", triggerTurn: true, deliverAs: "followUp" },
+            );
+          } else {
+            log.info("async_chain_next_step_spawned", { step: i + 2, id: next.id });
+          }
+        },
+      });
+    };
+
+    const first = spawnStep(0, "");
+    if (first.error) return fail(`Async chain step 1 (${steps[0].agent}) failed to spawn: ${first.error}`);
+    const modelInfo = first.model ? ` (${first.model})` : "";
+    return {
+      content: [{
+        type: "text" as const,
+        text: `Async chain started: ${stepName(0)} [${first.id}]${modelInfo}\n${total} step(s) run in sequence — each step receives the previous step's output as {previous}.\nA failed step stops the chain and is named in its result.\nUse /async-status to check progress.`,
+      }],
+      details: mkd("chain")([]),
+    };
+  }
+
   async function executeAsync(
     params: any,
     agents: AgentConfig[],
@@ -678,11 +821,7 @@ export function registerSubagentTool(
     explicit?: { model?: string; provider?: string },
   ) {
     if (params.chain) {
-      return {
-        content: [{ type: "text" as const, text: "Async mode does not support chain. Use agent + task or tasks array." }],
-        details: mkd("single")([]),
-        isError: true,
-      };
+      return executeAsyncChain(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
     }
 
     // Parallel async — spawn each task as a separate async agent
@@ -1628,9 +1767,14 @@ export function registerSubagentTool(
         const violators = [...new Set(requested.filter(n => ASYNC_ONLY_AGENTS.has(n)))];
         if (violators.length > 0) {
           const inChain = params.chain?.some(s => ASYNC_ONLY_AGENTS.has(s.agent));
-          if (inChain) {
+          // An async chain satisfies the async-only requirement; anything that would run the
+          // steps in the foreground (sync chain, or an acpx parent that coerces async→sync) cannot.
+          if (inChain && (params.async !== true || !asyncOk)) {
+            const why = params.async !== true
+              ? "a sync chain runs its steps in the foreground"
+              : `the parent provider cannot spawn async agents (${parentProvider ?? "unknown"})`;
             return {
-              content: [{ type: "text", text: `These agents cannot be used in chain mode: ${violators.join(", ")}. Dispatch them as separate async tasks instead.` }],
+              content: [{ type: "text", text: `These agents can only run async, and ${why}: ${violators.join(", ")}. Async chain needs async: true on a provider that supports async agents.` }],
               details: mkd("single")([]),
               isError: true,
             };
@@ -1670,14 +1814,45 @@ export function registerSubagentTool(
         if (params.chain) for (const s of params.chain) requested.add(s.agent);
         if (params.tasks) for (const t of params.tasks) requested.add(t.agent);
         if (params.agent) requested.add(params.agent);
-        const projAgents = Array.from(requested)
-          .map((n) => agents.find((a) => a.name === n))
-          .filter((a): a is AgentConfig => a?.source === "project");
+        // A chain step carries its own cwd, so it can resolve a DIFFERENT project agent set
+        // than the parent's — including a project agent that shadows a user agent of the
+        // same name. Resolve every step against its own cwd or the approval is bypassed.
+        const projAgents: AgentConfig[] = [];
+        const sources: string[] = [];
+        for (const name of requested) {
+          const parentAgent = agents.find((a) => a.name === name);
+          if (parentAgent?.source === "project") {
+            projAgents.push(parentAgent);
+            if (discovery.projectAgentsDir) sources.push(discovery.projectAgentsDir);
+          }
+        }
+        // Async chains resolve agents per step, so a step's own cwd can contribute a
+        // project agent — including one that SHADOWS a parent user agent of the same name.
+        // Sync chains still resolve against the parent list, so asking about their steps
+        // would prompt for an agent that never runs.
+        if (params.async === true) {
+          // Structured key: a "@" join is ambiguous when a name or path contains "@".
+          const seen = new Set(projAgents.map((a) => JSON.stringify([a.name, discovery.projectAgentsDir ?? ""])));
+          for (const step of params.chain ?? []) {
+            if (!step.cwd || step.cwd === ctx.cwd) continue;
+            const stepDiscovery = discoverAgents(step.cwd, scope);
+            const stepAgent = stepDiscovery.agents.find((a) => a.name === step.agent);
+            if (stepAgent?.source !== "project") continue;
+            // Dedupe on name+directory: the same name in a second project dir is a
+            // DIFFERENT agent and its source must appear in the prompt.
+            const key = JSON.stringify([stepAgent.name, stepDiscovery.projectAgentsDir ?? ""]);
+            if (seen.has(key)) continue;
+            seen.add(key);
+            projAgents.push(stepAgent);
+            if (stepDiscovery.projectAgentsDir) sources.push(stepDiscovery.projectAgentsDir);
+          }
+        }
         if (projAgents.length > 0) {
+          const uniqueSources = [...new Set(sources)];
           const ok = await bridgedUi.confirm(
             ctx,
             "Run project-local agents?",
-            `Agents: ${projAgents.map((a) => a.name).join(", ")}\nSource: ${discovery.projectAgentsDir}`,
+            `Agents: ${projAgents.map((a) => a.name).join(", ")}\nSource: ${uniqueSources.join(", ")}`,
           );
           if (!ok)
             return {

package/extensions/orchestrator/tmp-cleanup.ts

@@ -15,6 +15,7 @@ import * as fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isLiveLegacyDaemonFile } from "../shared/daemon-manager.js";
 import { createLogger } from "../shared/logger.js";
 import { isPiOneshotInvocation } from "../shared/oneshot.js";
 import { getGlobalSettingsPath, getSettingDynamic, getSettingsPath, SETTINGS_KEYS } from "./project-settings.js";
@@ -29,21 +30,6 @@ const DAY_MS = 24 * 60 * 60 * 1000;
 /** Defaults live in `settings-keys.json` only — never restated here. */
 export const DEFAULT_MAX_SIZE = String(SETTINGS_KEYS.project_tmp_max_size.default);
 export const DEFAULT_RETENTION_DAYS = Number(SETTINGS_KEYS.project_tmp_retention_days.default);
-/**
- * Transitional debris from pre-#1020 daemons: `.pi/tmp` was the control-file home
- * before `.pi/run`, so a daemon started before the upgrade still holds its pid/port and
- * reload handshake here, and the read-both fallback (#1025) needs these files to find it.
- * Sweeping them would make the next connect() miss the live daemon and spawn a duplicate
- * on the same port. Never deleted, whatever their age; the set disappears once no
- * pre-upgrade daemon remains.
- */
-export const TMP_PROTECTED_NAMES = new Set([
-  "pidiff.pid",
-  "pidiff.port",
-  "reload.flag",
-  "reload.done",
-  "reload.pending",
-]);
 /** Lives in `.pi/run`, never in the swept dir. */
 export const TMP_SWEEP_LOCK = ".tmp-sweep.lock";
 /** A crashed sweep would otherwise block every later session forever. */
@@ -171,7 +157,14 @@ export async function sweepProjectTmp(opts: TmpSweepOptions): Promise<TmpSweepRe
   let total = 0;
   for (const name of names) {
     const target = path.join(base, name);
-    if (!isInside(base, target) || TMP_PROTECTED_NAMES.has(name)) continue;
+    if (!isInside(base, target)) continue;
+    // One exemption, decided by the daemon layer: a pre-`.pi/run` daemon that is still ALIVE
+    // owns its lockfile here, and sweeping it makes the next connect() spawn a duplicate on
+    // that port. A dead daemon's leftovers are throwaway like everything else (#1020).
+    if (isLiveLegacyDaemonFile(base, name)) {
+      log.debug("tmp_sweep_kept_live_legacy_daemon", { tmpDir: base, name });
+      continue;
+    }
     let stat: fs.Stats;
     try {
       stat = await fsp.lstat(target);

package/extensions/orchestrator/tool-arg-guard.ts

@@ -0,0 +1,84 @@
+/**
+ * Turn a rejected tool call back into a forced retry.
+ *
+ * Pi validates arguments BEFORE the lifecycle hooks: a call with invalid
+ * arguments skips `tool_call` and `tool_result` entirely (docs: "An unknown
+ * tool or invalid arguments skip `tool_call`"). Only `tool_execution_end`
+ * fires, with the error result and no `durationMs` — so nothing in the
+ * extension surface told the model its call never ran, and a turn could simply
+ * end with the intended action silently not performed (passing `path` to
+ * `bash`, or a `write` call with no `content`).
+ *
+ * This guard watches for exactly that shape and raises a system note with
+ * `triggerTurn`, so the agent must retry instead of stopping.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createLogger } from "../shared/logger.js";
+import { sendSystemNote } from "../shared/system-note.js";
+
+const log = createLogger("tool-arg-guard");
+
+/** Pi's own rejection preamble, anchored at the START of the result. An executed tool
+ *  that merely *prints* this phrase cannot match, which stops false retries. */
+const VALIDATION_FAILURE = /^\s*(?:Validation failed for tool\s+"[^"]+":|Unknown tool:)/i;
+
+/** Keep only the parameter diagnostics — never the caller-controlled argument values.
+ *  Those can hold credentials, and a system note is a provenance-marked channel. */
+export function rejectionReason(text: string): string {
+  const cut = text.split(/Received arguments:/i)[0];
+  return cut.trim().slice(0, 300);
+}
+
+/** Flatten a tool result into text without assuming one shape. */
+export function resultText(result: unknown): string {
+  if (typeof result === "string") return result;
+  if (Array.isArray(result)) {
+    return result
+      .map((part: any) => (typeof part === "string" ? part : typeof part?.text === "string" ? part.text : ""))
+      .filter(Boolean)
+      .join("\n");
+  }
+  if (result && typeof result === "object") {
+    const text = (result as any).text;
+    if (typeof text === "string") return text;
+    // pi's rejected-call result: { content: [{ type: "text", text }], details }
+    if (Array.isArray((result as any).content)) return resultText((result as any).content);
+    try {
+      return JSON.stringify(result);
+    } catch {
+      return "";
+    }
+  }
+  return "";
+}
+
+/** True only for pi's argument/unknown-tool rejection, never for a policy block.
+ *  The "never ran" signal (absent durationMs) proved unreliable — bash rejections can
+ *  carry it — so the wording is the contract: pi emits this text only when it rejected
+ *  the call before execution, while policy blocks use their own message. */
+export function isArgumentRejection(isError: boolean, text: string): boolean {
+  return isError && VALIDATION_FAILURE.test(text);
+}
+
+export function registerToolArgGuard(pi: ExtensionAPI): void {
+  pi.on("tool_execution_end", async (event: any) => {
+    // durationMs is absent when the tool never executed.
+    const text = resultText(event?.result).trim();
+    if (!isArgumentRejection(Boolean(event?.isError), text)) return;
+
+    const reason = rejectionReason(text);
+    log.warn("tool_call_rejected_before_run", {
+      tool: event?.toolName,
+      toolCallId: event?.toolCallId,
+      // Diagnostic only: recorded, not used to decide.
+      durationMs: event?.durationMs,
+      // Parameter diagnostics only — received argument values are deliberately dropped.
+      reason,
+    });
+    await sendSystemNote(
+      pi,
+      `🚨 Your ${event?.toolName} call was REJECTED before it ran — the tool did NOT execute, so the action you intended did not happen:\n\n${reason}\n\nRetry now with corrected arguments. A frequent cause is a wrong parameter name (e.g. sending "path" to bash instead of "command", or "write" with no "content").`,
+      { customType: "tool-arg-rejected", triggerTurn: true, deliverAs: "followUp" },
+    );
+  });
+}

package/extensions/shared/daemon-manager.ts

@@ -193,19 +193,36 @@ export function writeLockfile(lockDir: string, port: number, pid: number | null,
   } catch (e: any) { log(`writeLockfile error: ${e.message}`); }
 }
 
+/** A pid file holds digits and a newline; anything bigger is not one. */
+const MAX_PID_FILE_BYTES = 64;
+
+/** True for a path that exists and is a regular file. Lockfiles are never FIFOs, and reading
+ *  one would block the event loop, so every control-file read goes through this. */
+function isRegularFile(target: string): boolean {
+  try {
+    return fs.lstatSync(target).isFile();
+  } catch {
+    return false;
+  }
+}
+
 /** Read port from lockfile. Returns port number or null.
  *  `legacyDir` (`.pi/tmp`) is consulted only when the new dir has no lockfile:
- *  a daemon already running at upgrade time wrote its lockfile there (#1020). */
+ *  a daemon already running at upgrade time wrote its lockfile there (#1020).
+ *  Reading never moves or deletes anything — moving a live daemon's record is what the
+ *  sweep's liveness check exists to avoid. */
 export function readLockfile(lockDir: string, legacyDir?: string): { port: number; pid: number | null } | null {
   const read = (dir: string): { port: number; pid: number | null } | null => {
     try {
       const portFile = path.join(dir, "pidiff.port");
-      if (!fs.existsSync(portFile)) return null;
+      // Only a regular file is a lockfile: the dirs are project-controlled, and reading a
+      // FIFO here would block the event loop for the whole session.
+      if (!isRegularFile(portFile)) return null;
       const port = parseInt(fs.readFileSync(portFile, "utf-8").trim(), 10);
       if (isNaN(port)) return null;
       let pid: number | null = null;
       const pidFile = path.join(dir, "pidiff.pid");
-      if (fs.existsSync(pidFile)) {
+      if (isRegularFile(pidFile)) {
         pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
         if (isNaN(pid)) pid = null;
       }
@@ -215,6 +232,63 @@ export function readLockfile(lockDir: string, legacyDir?: string): { port: numbe
   return read(lockDir) ?? (legacyDir ? read(legacyDir) : null);
 }
 
+/** Read the pid from a lockfile, refusing anything but a regular file: the legacy dir is
+ *  project-controlled, and reading a FIFO there would block session startup. */
+function readLegacyPid(pidFile: string): number | null {
+  try {
+    const st = fs.lstatSync(pidFile);
+    if (!st.isFile()) {
+      log.debug("legacy_pid_not_a_regular_file", { pidFile });
+      return null;
+    }
+    // The file is project-controlled: a pid is a few bytes, so refuse anything larger rather
+    // than reading an arbitrary file into memory during session start.
+    if (st.size > MAX_PID_FILE_BYTES) {
+      log.debug("legacy_pid_file_too_large", { pidFile, size: st.size });
+      return null;
+    }
+    const pid = parseInt(fs.readFileSync(pidFile, "utf-8").trim(), 10);
+    if (isNaN(pid) || pid <= 0) {
+      log.debug("legacy_pid_unparseable", { pidFile });
+      return null;
+    }
+    return pid;
+  } catch (e: any) {
+    log.debug("legacy_pid_unreadable", { pidFile, error: e?.message });
+    return null;
+  }
+}
+
+/** True when the legacy `.pi/tmp` lockfile belongs to a LIVE process. `EPERM` means the
+ *  process exists under another user, so it counts as alive — treating it as dead would let
+ *  the sweep delete a running daemon's files. */
+export function legacyLockfileOwnerAlive(legacyDir: string): boolean {
+  const pid = readLegacyPid(path.join(legacyDir, "pidiff.pid"));
+  if (pid === null) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e: any) {
+    if (e?.code === "EPERM") {
+      log.debug("legacy_daemon_owned_by_another_user", { pid });
+      return true;
+    }
+    log.debug("legacy_daemon_not_running", { pid, code: e?.code });
+    return false;
+  }
+}
+
+/** Control files a pre-`.pi/run` daemon owns inside the legacy dir. Private: the sweep asks
+ *  `isLiveLegacyDaemonFile`, so neither module keeps a second copy of the names (#1020). */
+const LEGACY_CONTROL_FILES = new Set(["pidiff.port", "pidiff.pid"]);
+
+/** True when `name` is a legacy control file whose owner is still alive — the sweep's only
+ *  exemption. A dead daemon's leftovers are ordinary throwaway. */
+export function isLiveLegacyDaemonFile(legacyDir: string, name: string): boolean {
+  if (!LEGACY_CONTROL_FILES.has(name)) return false;
+  return legacyLockfileOwnerAlive(legacyDir);
+}
+
 /** First lockfile port (in `dirs` order) whose daemon answers /api/health, or
  *  null. Exported for testing. */
 export async function findLiveLockfile(dirs: string[]): Promise<number | null> {

package/extensions/shared/ui-bridge.ts

@@ -59,7 +59,10 @@ export function createBridgedUi(pi: ExtensionAPI): BridgedUi {
     if (typeof ctx.ui?.custom !== "function") {
       log.debug("bridged prompt degraded — no ui.custom", { method });
       if (method === "select") return await ctx.ui.select(title, options) as T | undefined;
-      if (method === "confirm") return (await ctx.ui.confirm(title, message)) as T | undefined;
+      // The confirm wrapper compares against the "__confirmed__"/"Yes" sentinels, so a raw
+      // boolean here was always rejected — every prompt without ui.custom cancelled, and an
+      // approval could never succeed. Translate the answer to the sentinel the caller expects.
+      if (method === "confirm") return ((await ctx.ui.confirm(title, message)) ? "__confirmed__" : "__denied__") as T | undefined;
       return await ctx.ui.input(title) as T | undefined;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-orchestrator-config",
-  "version": "4.25.0",
+  "version": "4.26.1",
   "description": "Orchestrator pattern for pi: specialist subagents, enforcement, code review loop, workflow commands",
   "keywords": [
     "pi-package"