pi-orchestrator-config 4.24.1 → 4.24.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [4.24.2] - 2026-11-04
+
+- Async work is tracked even when an agent starts it: the task trigger now covers work set in
+  motion by an async result, and `taskId: "-1"` is restricted to a single read-only check in
+  every place that taught the old habit.
+- Task-id validation actually runs. `pitasks` exports the store as a live binding that the
+  subagent tool used to snapshot before it was assigned, so an unknown id was accepted; the
+  store is now published on a symbol bridge and read at access time. Verified live: unknown
+  ids rejected, a real id and the read-only sentinel accepted.
+- Machine-generated notices declare their provenance: follow-ups are prefixed
+  "[system message — not written by the user]", so a guard rail cannot be read as user input.
+- Board updates are success-gated — a failed agent keeps its task open — and reconciling the
+  board before new dispatch is mandatory. Status reports derive from `TaskList`.
+
 ## [4.24.1] - 2026-11-03
 
 - Dreaming no longer stores re-derivable changelog: `[done]` takes non-derivable outcomes only (conclusions, measurements, root causes) and reorganizing prunes PR/version/ticket

package/extensions/orchestrator/subagent-tool.ts

@@ -16,6 +16,8 @@ import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import type { Message } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { createLogger } from "../shared/logger.js";
+import { sendSystemNote } from "../shared/system-note.js";
+import { publishedTaskStore } from "../shared/task-store-bridge.js";
 import { createBridgedUi } from "../shared/ui-bridge.js";
 import {
   getMarkdownTheme,
@@ -30,12 +32,44 @@ import {
 import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.js";
 
-// Task store access via shared instance from extensions/pitasks
-let _taskStore: any = null;
+// Task store access via the pitasks module.
+// `taskStore` is `export let` — a live binding the pitasks extension assigns when it
+// initializes. Copying the value at import time captured `undefined` and disabled
+// task-id validation for the whole session (issue #1016), so the binding is read fresh.
+let _pitasksModule: any = null;
+let _pitasksLoad: Promise<any> | null = null;
+async function pitasksModule(): Promise<any> {
+  if (_pitasksModule) return _pitasksModule;
+  if (!_pitasksLoad) {
+    _pitasksLoad = (async () => {
+      try {
+        _pitasksModule = await import("../pitasks/index.js");
+        return _pitasksModule;
+      } catch (err) {
+        log.warn(`[subagent] pitasks module unavailable: ${String((err as Error)?.message ?? err).slice(0, 120)}`);
+        _pitasksLoad = null; // retry on the next call
+        return null;
+      }
+    })();
+  }
+  return _pitasksLoad;
+}
+
+/** The live task store, or null while pitasks has not initialized it yet.
+ *  Read from the global symbol registry: this tool's module instance cannot see the
+ *  pitasks extension's `export let taskStore` binding (it snapshots `undefined`), which
+ *  is why task-id validation silently failed open (issue #1016). */
 async function getTaskStore(): Promise<any> {
-  if (_taskStore) return _taskStore;
-  try { const mod = await import("../pitasks/index.js"); _taskStore = mod.taskStore; } catch { /* ignore */ }
-  return _taskStore;
+  const published = publishedTaskStore();
+  if (published) return published;
+  // Fall back to the module binding for in-process loads that share this instance.
+  const mod = await pitasksModule();
+  const store = mod?.taskStore ?? null;
+  if (!store) {
+    // Validation is about to be skipped: that is a degraded state, not routine flow.
+    log.warn("task_store_unavailable", { note: "pitasks store not initialized — taskId validation skipped" });
+  }
+  return store;
 }
 import {
   decideAsyncLlmDispatch,
@@ -153,7 +187,7 @@ const SubagentParams = Type.Object({
     Type.String({ description: "Display name for async agents in status line and notifications (e.g., 'Dream', 'Code Review'). Defaults to agent name." }),
   ),
   taskId: Type.Optional(
-    Type.String({ description: "Task ID to auto-complete when this async agent finishes. Required for async agents — pass \"-1\" if not linked to any task." }),
+    Type.String({ description: "Task ID to auto-complete when this async agent finishes. Required for async agents — pass \"-1\" only for a single read-only check; an agent that edits, pushes, or drives a PR needs a real task id." }),
   ),
   asyncKill: Type.Optional(
     Type.String({ description: "Kill async agent(s) by name, id prefix, or 'all'. Returns which agents were killed." }),
@@ -577,22 +611,27 @@ export async function runSingleAgent(
   }
 }
 
-/** Validate that a taskId references an existing task in the pitasks store. */
-function validateTaskId(taskId: string, _cwd: string, _sessionId?: string): string | null {
+/** The message for a task id the store does not know; null when it is valid or exempt. */
+export function taskIdError(taskId: string, lookup: (id: string) => boolean): string | null {
+  if (taskId === "-1") return null;
+  return lookup(taskId)
+    ? null
+    : `Task #${taskId} not found. Verify the task ID exists (use TaskList to check), or pass taskId: "-1" for a read-only check (editing or PR work needs a real task id).`;
+}
+
+/** Validate that a taskId references an existing task. Awaits the store load, so the
+ *  first async call of a session validates too instead of failing open (issue #1016). */
+async function validateTaskId(taskId: string, _cwd: string, _sessionId?: string): Promise<string | null> {
   if (taskId === "-1") return null;
+  const store = await getTaskStore();
+  if (!store) return null; // pitasks genuinely unavailable — warned in getTaskStore
   try {
-    // Ensure store is loaded (async init may not have completed)
-    if (!_taskStore) {
-      getTaskStore().catch(() => {});
-    }
-    const store = _taskStore;
-    if (!store) {
-      // Store not loaded yet (async init) — fail open, skip validation
-      return null;
-    }
-    if (store.get(taskId)) return null;
-  } catch { return null; }
-  return `Task #${taskId} not found. Verify the task ID exists (use TaskList to check), or pass taskId: "-1" if not linked to a task.`;
+    return taskIdError(taskId, (id) => Boolean(store.get(id)));
+  } catch (err) {
+    // Same fail-open as before, but a broken store must not look like a valid id.
+    log.warn("task_id_validation_failed", { reason: String((err as Error)?.message ?? err).slice(0, 120) });
+    return null;
+  }
 }
 
 // ── Registration ─────────────────────────────────────────────────────────
@@ -629,7 +668,7 @@ export function registerSubagentTool(
     };
   }
 
-  function executeAsync(
+  async function executeAsync(
     params: any,
     agents: AgentConfig[],
     mkd: (mode: "single" | "parallel" | "chain") => (results: SingleResult[]) => SubagentDetails,
@@ -659,13 +698,13 @@ export function registerSubagentTool(
       }
       const noTaskId = params.tasks.filter((t: any) => (t as any).taskId == null);
       if (noTaskId.length > 0) {
-        const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nMissing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}\n\nIf an agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf an agent is NOT linked to any task: pass taskId: "-1"`;
+        const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nMissing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}\n\nIf an agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf an agent is only doing a single read-only check: pass taskId: "-1" (editing or PR work needs a real task id)`;
         // Force a follow-up turn so the AI MUST deal with this error
-        pi.sendMessage({
-          customType: "subagent-taskid-error",
-          content: `🚨 CRITICAL: Async subagent call was REJECTED — missing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}. NO agents were spawned. You MUST retry with taskId for each agent. Use TaskList to find task IDs, or pass taskId: "-1" if not linked.`,
-          display: true,
-        }, { triggerTurn: true, deliverAs: "followUp" });
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: Async subagent call was REJECTED — missing taskId for: ${noTaskId.map((t: any) => t.agent).join(", ")}. NO agents were spawned. You MUST retry with taskId for each agent. Use TaskList to find task IDs; "-1" is only for a single read-only check.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
         return {
           content: [{ type: "text" as const, text: errorMsg }],
           details: mkd("single")([]),
@@ -674,13 +713,13 @@ export function registerSubagentTool(
       }
       for (const t of params.tasks) {
         const tid = (t as any).taskId as string;
-        const taskErr = validateTaskId(tid, ctx.cwd, ctx.sessionManager?.getSessionId?.());
+        const taskErr = await validateTaskId(tid, ctx.cwd, ctx.sessionManager?.getSessionId?.());
         if (taskErr) {
-          pi.sendMessage({
-            customType: "subagent-taskid-error",
-            content: `🚨 CRITICAL: ${taskErr} (agent: ${t.agent}). NO agents were spawned. Fix the taskId and retry.`,
-            display: true,
-          }, { triggerTurn: true, deliverAs: "followUp" });
+          await sendSystemNote(
+            pi,
+            `🚨 CRITICAL: ${taskErr} (agent: ${t.agent}). NO agents were spawned. Fix the taskId and retry.`,
+            { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+          );
           return {
             content: [{ type: "text" as const, text: `${taskErr} (agent: ${t.agent})` }],
             details: mkd("single")([]),
@@ -747,13 +786,13 @@ export function registerSubagentTool(
       };
     }
     if (params.taskId == null) {
-      const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nIf this agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf this agent is NOT linked to any task: pass taskId: "-1"\n\nExample: subagent(agent="${params.agent}", task="...", async=true, name="${params.name}", taskId="-1")`;
+      const errorMsg = `Missing required parameter: taskId. Every async agent MUST have a taskId.\n\nIf this agent is working on a task: pass the task ID (e.g., taskId: "5")\nIf this agent is only doing a single read-only check: pass taskId: "-1" (editing or PR work needs a real task id)\n\nExample: subagent(agent="${params.agent}", task="...", async=true, name="${params.name}", taskId="-1")`;
       // Force a follow-up turn so the AI MUST deal with this error
-      pi.sendMessage({
-        customType: "subagent-taskid-error",
-        content: `🚨 CRITICAL: Async subagent call for "${params.agent}" was REJECTED — missing taskId. The agent was NOT spawned. You MUST retry the subagent call with taskId. Use TaskList to find the task ID, or pass taskId: "-1" if not linked to any task. Do NOT proceed without fixing this.`,
-        display: true,
-      }, { triggerTurn: true, deliverAs: "followUp" });
+      await sendSystemNote(
+        pi,
+        `🚨 CRITICAL: Async subagent call for "${params.agent}" was REJECTED — missing taskId. The agent was NOT spawned. You MUST retry the subagent call with taskId. Use TaskList to find the task ID; "-1" is only for a single read-only check. Do NOT proceed without fixing this.`,
+        { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+      );
       return {
         content: [{ type: "text" as const, text: errorMsg }],
         details: mkd("single")([]),
@@ -761,13 +800,13 @@ export function registerSubagentTool(
       };
     }
     {
-      const taskErr = validateTaskId(params.taskId, ctx.cwd, ctx.sessionManager?.getSessionId?.());
+      const taskErr = await validateTaskId(params.taskId, ctx.cwd, ctx.sessionManager?.getSessionId?.());
       if (taskErr) {
-        pi.sendMessage({
-          customType: "subagent-taskid-error",
-          content: `🚨 CRITICAL: ${taskErr} The agent was NOT spawned. Fix the taskId and retry.`,
-          display: true,
-        }, { triggerTurn: true, deliverAs: "followUp" });
+        await sendSystemNote(
+          pi,
+          `🚨 CRITICAL: ${taskErr} The agent was NOT spawned. Fix the taskId and retry.`,
+          { customType: "subagent-taskid-error", triggerTurn: true, deliverAs: "followUp" },
+        );
         return {
           content: [{ type: "text" as const, text: taskErr }],
           details: mkd("single")([]),
@@ -1689,7 +1728,7 @@ export function registerSubagentTool(
 
       // Async mode — spawn in background and return immediately
       if (params.async === true) {
-        const result = executeAsync(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
+        const result = await executeAsync(params, agents, mkd, parentModelId, parentProvider, ctx, explicit);
         if (capabilityNote && result.content?.[0]?.type === "text") {
           result.content[0].text = `${capabilityNote}\n\n${result.content[0].text}`;
         }

package/extensions/pitasks/index.ts

@@ -11,6 +11,7 @@ import { TaskStore } from "./task-store.js";
 import { TaskWidget } from "./task-widget.js";
 import { registerTaskTools } from "./task-tools.js";
 import { createLogger } from "../shared/logger.js";
+import { publishTaskStore } from "../shared/task-store-bridge.js";
 import { createBridgedUi } from "../shared/ui-bridge.js";
 import { getSetting } from "../orchestrator/project-settings.js";
 import { shouldSkipOneshotRegister } from "../shared/oneshot.js";
@@ -43,6 +44,11 @@ export function setTaskTelemetryActive(taskId: string, active = true): void {
 /** Exported store instance — set during extension init. */
 export let taskStore: TaskStore;
 
+// The store is published to other extension modules through the shared bridge: they
+// cannot read this `export let` binding (they would snapshot `undefined`), which silently
+// disabled task-id validation (issue #1016). Published once, from registration only —
+// the bridge's getter follows later store swaps, so the upgrade path needs no republish.
+
 /** Create a task directly — for use by other extensions (e.g., coms auto-create). */
 export function createTask(subject: string, description: string, createdBy?: any, metadata?: Record<string, any>): any {
 	return taskStore.create(subject, description, createdBy || { type: "local", origin: "system", session: "", project: "" }, undefined, metadata);
@@ -189,6 +195,8 @@ export default function (pi: ExtensionAPI) {
 	currentWidget?.dispose();
 	let store = new TaskStore(resolveStorePath());
 	taskStore = store;
+	// Registration is the only publish site: the getter follows store swaps.
+	publishTaskStore(() => taskStore);
 	currentStore = store;
 	const widget = new TaskWidget(store);
 	store.setOnChange(() => { widget.update(); broadcastTasks(); });

package/extensions/shared/system-note.ts

@@ -0,0 +1,44 @@
+/**
+ * Provenance-marked injections for content the user did NOT write.
+ *
+ * The transcript gives an extension no room to say "this is not the user's words":
+ * `pi.sendMessage` renders as `role: "custom"` and `pi.sendUserMessage` renders as a
+ * user turn, so machine text arrives looking exactly like something the user typed.
+ * A model reading it will answer "as you said" and attribute its own guard rails to the
+ * user (issue #1016 review, where a REJECTED call looked like a user message).
+ *
+ * Every message this module sends starts with MARKER, which is self-explanatory on
+ * purpose: no rule has to teach the model what it means.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createLogger } from "./logger.js";
+
+const log = createLogger("system-note");
+
+/** Prefix that identifies machine-generated text in the transcript. */
+export const SYSTEM_NOTE_MARKER = "[system message — not written by the user]";
+
+export interface SystemNoteOptions {
+  /** Stable kind for renderers/filters, e.g. "subagent-taskid-error". */
+  customType: string;
+  /** Start a turn from this message when the session is idle. */
+  triggerTurn?: boolean;
+  /** Delivery slot for a busy session. */
+  deliverAs?: "steer" | "followUp" | "nextTurn";
+  /** Render in the TUI transcript. */
+  display?: boolean;
+}
+
+/** Send machine-generated text, marked so it cannot be mistaken for user input. */
+export async function sendSystemNote(
+  pi: ExtensionAPI,
+  text: string,
+  options: SystemNoteOptions,
+): Promise<void> {
+  const body = text.startsWith(SYSTEM_NOTE_MARKER) ? text : `${SYSTEM_NOTE_MARKER}\n${text}`;
+  log.debug("send_system_note", { customType: options.customType, chars: body.length });
+  await pi.sendMessage(
+    { customType: options.customType, content: body, display: options.display ?? true },
+    { triggerTurn: options.triggerTurn, deliverAs: options.deliverAs },
+  );
+}

package/extensions/shared/task-store-bridge.ts

@@ -0,0 +1,43 @@
+/**
+ * Cross-module bridge for the pitasks store.
+ *
+ * `pitasks` exports `taskStore` as `export let`, assigned when the extension
+ * initializes. Another extension's module instance cannot read that binding: it
+ * snapshots `undefined` at import time, which silently disabled task-id validation
+ * (issue #1016). The store is therefore published on the global symbol registry, and
+ * the published object reads the live binding on every access — publishing once is
+ * enough, and a store swap needs no republish.
+ *
+ * Publish only from the instance that owns the store (pitasks registration), never from
+ * module-load code: a duplicate import would otherwise displace the real getter with one
+ * bound to a store that instance never creates.
+ *
+ * Same pattern as the pricing-provenance and session-cwd markers.
+ */
+import { createLogger } from "./logger.js";
+
+const log = createLogger("task-store-bridge");
+
+export const TASK_STORE_SYMBOL = Symbol.for("pi-config.taskStore");
+
+interface TaskStoreBridge {
+  readonly current: unknown;
+}
+
+/** Publish a getter over the live store binding. Called by the owning extension. */
+export function publishTaskStore(getStore: () => unknown): void {
+  (globalThis as Record<symbol, unknown>)[TASK_STORE_SYMBOL] = {
+    get current(): unknown {
+      return getStore();
+    },
+  } satisfies TaskStoreBridge;
+  log.debug("task_store_bridge_published", { at: Date.now() });
+}
+
+/** The published store, or null when the owning extension has not registered. */
+export function publishedTaskStore(): unknown {
+  const bridge = (globalThis as Record<symbol, unknown>)[TASK_STORE_SYMBOL] as TaskStoreBridge | undefined;
+  const store = bridge?.current ?? null;
+  log.debug("task_store_bridge_read", { found: Boolean(store) });
+  return store;
+}

package/package.json

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

package/rules/00-orchestrator-core.md

@@ -34,7 +34,8 @@ Outside slash commands, never use edit, write, or bash directly (except `codemod
 
 ## Before Implementation (MANDATORY)
 
-**For 2+ distinct actions, your first action is one `TaskBulkCreate` listing every step** — before the first edit or the first agent call (see `60-task-tracking.md`).
+**For 2+ distinct actions — requested, or set in motion by an async result — your first action is one `TaskBulkCreate` listing every step**
+— before the first edit or the first agent call (see `60-task-tracking.md`).
 
 Before ANY code changes, run the pre-implementation checklist:
 

package/rules/40-critical-rules.md

@@ -34,7 +34,7 @@ its output. Use it ONLY for work whose result nobody consumes — in pi-config,
 dreaming and nothing else. Every watcher, poll, and review agent exists to report
 something back, so leave `fireAndForget` unset for them. If you are about to set it,
 ask whether you will ever read the result; if yes, do not set it.
-**`taskId` is required on every async call** (use `-1` when unlinked) — a call without
+**`taskId` is required on every async call** (`-1` only for a single read-only check; anything that edits, pushes, or drives a PR needs a real task id) — a call without
 it is rejected, and the agent does not run.
 
 Do NOT write bash loops, sleep commands, or poll for results after spawning async agents.

package/rules/60-task-tracking.md

@@ -9,12 +9,13 @@
 
 ## When Tasks Are Required
 
-The request needs **2+ distinct actions** — then tasks are required:
+The request — **or work any step sets in motion** — needs **2+ distinct actions** — then tasks are required:
 
 - more than one file to change, or code plus tests plus docs
 - any workflow from `05-issue-first-workflow.md` or `20-code-review-loop.md`
 - the user lists several things to do ("do X, then Y", numbered items)
 - work conditioned on a future event ("after Qodo approves, deploy and test") — create the tasks now, put the trigger in the description, and block the dependents on it
+- an async result comes back with follow-up work — reacting only to finished agents still needs a board
 
 **No tasks:** a single-step action, a one-file/one-line change, a question, an explanation, read-only investigation.
 
@@ -22,6 +23,10 @@ The request needs **2+ distinct actions** — then tasks are required:
 
 Plan the whole job in **one `TaskBulkCreate` call** listing every step — not one `TaskCreate` per step, and not after the first edit. `TaskCreate` is for a single step added later.
 
+**Before dispatching new work, reconcile the board (MANDATORY):** complete, re-scope, or
+delete stale tasks. Dispatching over a task that is `in_progress` for work that already changed
+is a violation.
+
 When `TaskCreate`'s own tool description suggests per-step calls, **this rule wins**: one bulk call for the whole job.
 
 ## Granularity
@@ -31,10 +36,22 @@ One concrete action per task: which file, which change.
 - ❌ `Implement the fix` / `Create PR`
 - ✅ `Edit extensions/orchestrator/utils.ts — add timeout parameter to fetchData()` / `Create PR with the test plan`
 
+**Multi-issue work:** one task per **stage** per issue, named `#<n>: <stage>` (e.g.
+`#1016: contract test`). Later stages carry `blockedBy` in the bulk create — `addBlockedBy` is an
+update field, and stage ids only exist after the call returns, so wire them with `TaskUpdate` if
+the order was not set at creation. File-level detail lives in the description, not the subject.
+
 ## Lifecycle
 
 `in_progress` before starting a task, `completed` immediately after. Work in order. Never abandon a task — drop a stale one with `TaskUpdate status: "deleted"`.
 
+**When an async result arrives, update the board in that same turn:** on success complete the
+owning task, then plan any follow-up in one `TaskBulkCreate` and activate its first stage. A
+failed agent keeps its task open — the runtime never auto-completes a failure, and closing it
+would activate a stage whose input never arrived.
+
+Status reports come from `TaskList`, not recollection.
+
 ## Side Questions
 
 Answer the question, then resume the next unchecked task — the task list says where you left off.
@@ -44,14 +61,18 @@ Answer the question, then resume the next unchecked task — the task list says
 ## Async Agent taskId (MANDATORY — code-enforced)
 
 **Every async agent call MUST include `taskId`.** Enforced — calls without it are rejected.
-Pass the task ID (e.g., `"5"`) when linked to a task, or `"-1"` when not.
-Linked tasks auto-complete on agent success — no manual `TaskUpdate` needed.
+Pass the id of the task the agent performs (e.g. `"5"`). `"-1"` is only for a single read-only
+check that changes nothing: an agent that edits code, pushes, or drives a PR must carry a real
+task id, because an unlinked poll is work that never appears on the board.
 
 ```text
 subagent(agent="code-reviewer-quality", task="...", cwd="...", async=true, name="Review", taskId="5")
-subagent(agent="worker", task="...", cwd="...", async=true, name="Qodo Poll", taskId="-1")
+subagent(agent="worker", task="...", cwd="...", async=true, name="Read one file", taskId="-1")
 ```
 
-- ✅ **ALWAYS** pass `taskId` — auto-completes on success, stays `in_progress` on failure
-- ❌ **NEVER** manually `TaskUpdate` a task to `completed` if it has an async agent
+**Stage tasks are yours to close.** An agent links to the narrow task it performs; the stage
+completes when the stage's acceptance holds — binding a stage to a poll marks it done when
+only the poll finished.
+
+- ❌ **NEVER** let a narrow agent task stand in for a stage — auto-complete ends the task the agent was linked to
 - ❌ **NEVER** omit `taskId` — the call will fail