pi-better-harness 0.40.5 → 0.41.0

package/README.md

@@ -252,6 +252,7 @@ Use the installer when you want every core extension with standalone package ide
 | Recommended install | `npx pi-better-harness install` |
 | Write sandbox on macOS | Seatbelt (`sandbox-exec`), ships with the OS |
 | Write sandbox on Linux | Bubblewrap — install `bubblewrap` |
+| Linked-worktree project context | A Pi host that applies `systemPromptOptions` after `before_agent_start` (Pi 1.x); older hosts keep the loaded prompt |
 | Development runtime | Node.js 22+ |
 
 ## Update Or Remove

package/extensions/project-context/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Load project context from the linked worktree that owns the working directory.
+ *
+ * A linked worktree is its own project root: its context file is the one Pi
+ * should send, without the main checkout's file that ancestor loading also
+ * collects. The global context file under the agent directory is kept, because
+ * it does not belong to either checkout.
+ *
+ * Filters only, and returns nothing, so Pi keeps publishing prompt sections and
+ * the cached prompt prefix (ADR 0016, ADR 0021).
+ */
+
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { restrictContextFilesToWorktree } from "../worktree-context.ts";
+
+export default function projectContextExtension(pi: ExtensionAPI): void {
+    pi.on("before_agent_start", (event) => {
+        restrictContextFilesToWorktree(event.systemPromptOptions, getAgentDir());
+    });
+}

package/extensions/task-context/workflow-plan-update.ts

@@ -52,7 +52,7 @@ const FLEET_STATUS_ALIASES: Record<string, string> = { "n/a": "not-applicable" }
 
 const ROW_PROTECTED = new Set(["id"]);
 const RUN_PROTECTED = new Set([
-  "runId", "planRevision", "updatedAt", "startedAt", "units", "issues", "components", "fleet", "decisions",
+  "runId", "runDir", "planRevision", "updatedAt", "startedAt", "units", "issues", "components", "fleet", "decisions",
 ]);
 const PROFILING_RESERVED = new Set([
   "ts", "runId", "planRevision", "event", "changes", "decision", "scope", "unit", "component", "stage", "logAheadRevision",
@@ -80,7 +80,7 @@ export function applyRushPlanUpdate(
 
   const originalText = readFileSync(file, "utf8");
   const original: unknown = JSON.parse(originalText);
-  const current = projectRushPlan(original, runId);
+  const current = projectRushPlan(original, runId, dirname(file));
   if (update.revision !== undefined && update.revision !== current.planRevision) {
     throw new Error(`Rush plan revision mismatch: expected ${update.revision}, found ${current.planRevision}. Read the plan with get_todo and retry.`);
   }
@@ -117,7 +117,7 @@ export function applyRushPlanUpdate(
   const revision = current.planRevision + 1;
   next.planRevision = revision;
   next.updatedAt = ts;
-  const projected = projectRushPlan(next, runId);
+  const projected = projectRushPlan(next, runId, dirname(file));
 
   const extra = update.profiling ?? {};
   if (!isRecord(extra)) throw new Error("workflow.profiling must be an object of extra event fields.");

package/extensions/task-context/workflow-plan.ts

@@ -63,15 +63,31 @@ export const MAX_RUSH_PLAN_BYTES = 2_000_000;
 
 export function readRushPlan(path: string, cwd: string): RushPlan {
   const { file, runId } = resolveRushPlanFile(path, cwd);
-  return projectRushPlan(JSON.parse(readFileSync(file, "utf8")), runId);
+  return projectRushPlan(JSON.parse(readFileSync(file, "utf8")), runId, dirname(file));
 }
 
 /** Validate a parsed task-plan.json document and project the fields the plan view shows. */
-export function projectRushPlan(data: unknown, runId: string): RushPlan {
-  if (!isRecord(data) || data.runId !== runId || !Number.isSafeInteger(data.planRevision) ||
-      (data.planRevision as number) < 0 || !isRecord(data.fleet)) {
+export function projectRushPlan(data: unknown, runId: string, expectedRunDir?: string): RushPlan {
+  if (!isRecord(data) || !Number.isSafeInteger(data.planRevision) ||
+      (data.planRevision as number) < 0) {
     throw new Error("Invalid Rush plan identity or revision.");
   }
+  // Current preflight plans carry runDir instead of duplicating its basename
+  // in runId. The caller has already confined the file to the run directory.
+  const validIdentity = data.runId === undefined
+    ? typeof data.runDir === "string" && isAbsolute(data.runDir) && basename(data.runDir) === runId
+    : data.runId === runId;
+  if (!validIdentity) throw new Error("Invalid Rush plan identity or revision.");
+  if (expectedRunDir !== undefined && data.runDir !== undefined) {
+    let matches = false;
+    try {
+      matches = typeof data.runDir === "string" && isAbsolute(data.runDir)
+        && realpathSync(data.runDir) === realpathSync(expectedRunDir);
+    } catch { /* An unavailable run directory cannot establish identity. */ }
+    if (!matches) throw new Error("Invalid Rush plan identity or revision: runDir does not match the plan directory.");
+  }
+  const persistedFleet = data.fleet === undefined ? {} : data.fleet;
+  if (!isRecord(persistedFleet)) throw new Error("Invalid Rush fleet stages.");
   const persistedUnits = Array.isArray(data.issues) ? data.issues : data.units;
   if (!Array.isArray(persistedUnits)) throw new Error("Invalid Rush plan units.");
   const issues = persistedUnits.map((unit: unknown) => {
@@ -90,13 +106,13 @@ export function projectRushPlan(data: unknown, runId: string): RushPlan {
     };
   });
   const fleet: RushPlan["fleet"] = {};
-  for (const [stage, value] of Object.entries(data.fleet)) {
+  for (const [stage, value] of Object.entries(persistedFleet)) {
     const status = typeof value === "string" ? value : isRecord(value) ? value.status : undefined;
     if (typeof status !== "string") throw new Error("Invalid Rush fleet stage.");
     fleet[stage] = { status };
   }
   return {
-    runId: data.runId as string,
+    runId,
     planRevision: data.planRevision as number,
     issues,
     fleet,

package/extensions/tool-call-guard/index.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { SettingsControl } from "../settings/registry.ts";
+import { readHarnessSetting, updateHarnessSetting } from "../shared-harness-settings.ts";
+import { blockReason, detectForegroundWait, type WaitMatch } from "./waits.ts";
+
+const SETTING_KEY = "toolCallGuard";
+
+interface GuardSetting { version?: unknown; enabled?: unknown }
+
+/**
+ * Block a foreground command that waits on an external system.
+ *
+ * Returns the block result from `tool_call`, which pi turns into a failed tool result carrying
+ * `reason`. Nothing is executed. `isEnabled` is read per call so the setting takes effect
+ * without reloading the extension.
+ */
+export function installToolCallGuard(
+  pi: ExtensionAPI,
+  isEnabled: () => boolean,
+  onBlock?: (match: WaitMatch, command: string) => void,
+): void {
+  pi.on("tool_call", (event) => {
+    if (!isEnabled()) return;
+    if (event.toolName !== "bash") return;
+    // `input` is the current SDK field; older typings and some hosts expose `args`.
+    const payload = event as { input?: { command?: unknown }; args?: { command?: unknown } };
+    const command = payload.input?.command ?? payload.args?.command;
+    if (typeof command !== "string") return;
+    const match = detectForegroundWait(command);
+    if (!match) return;
+    onBlock?.(match, command);
+    return { block: true, reason: blockReason(match) };
+  });
+}
+
+export default function toolCallGuardExtension(pi: ExtensionAPI): void {
+  let enabled = true;
+
+  const read = (): void => {
+    const value = readHarnessSetting<GuardSetting>(SETTING_KEY);
+    if (value !== undefined && (value?.version !== 1 || typeof value.enabled !== "boolean")) {
+      throw new Error("Invalid tool-call guard setting in global settings.json.");
+    }
+    enabled = value?.enabled !== false;
+  };
+
+  const setting: SettingsControl = {
+    id: "tool-call-guard", label: "Tool call guard", values: ["On", "Off"],
+    get: () => enabled ? "On" : "Off",
+    change(value: string, _ctx: ExtensionCommandContext) {
+      if (value !== "On" && value !== "Off") throw new Error("Invalid tool-call guard value.");
+      updateHarnessSetting(SETTING_KEY, () => ({ version: 1, enabled: value === "On" }));
+      enabled = value === "On";
+    },
+  };
+
+  const register = () => pi.events.emit("harness-settings:register", setting);
+  let stopSettings: (() => void) | undefined;
+  const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
+
+  subscribe();
+  register();
+  installToolCallGuard(pi, () => enabled);
+
+  pi.on("session_start", () => {
+    subscribe();
+    try { read(); }
+    catch {
+      // A malformed value must not take the session down; fall back to guarding.
+      enabled = true;
+    }
+    register();
+  });
+
+  pi.on("session_shutdown", () => {
+    stopSettings?.();
+    stopSettings = undefined;
+  });
+}

package/extensions/tool-call-guard/waits.ts

@@ -0,0 +1,59 @@
+/**
+ * Recognise a foreground command that waits on something outside this machine.
+ *
+ * The guard keys off command shape rather than duration: a five minute test run belongs in the
+ * foreground where its output streams, while `gh pr checks --watch` can only end when GitHub
+ * says so. Duration cannot tell those apart, and blocking the first would be wrong.
+ */
+export interface WaitMatch {
+  /** Which rule matched, quoted back to the caller so the block is explainable. */
+  rule: string;
+  /** What the command is waiting for. */
+  waitsOn: string;
+}
+
+/** A foreground pause shorter than this is ordinary command flow, not a wait. */
+export const SLEEP_THRESHOLD_SECONDS = 3;
+
+const RULES: readonly { rule: RegExp; waitsOn: string }[] = [
+  { rule: /\bgh\s+pr\s+checks\b[^\n]*--watch\b/, waitsOn: "a pull request's checks" },
+  { rule: /\bgh\s+run\s+(?:view|watch)\b[^\n]*--watch\b/, waitsOn: "a workflow run" },
+  { rule: /\bgh\s+run\s+watch\b/, waitsOn: "a workflow run" },
+  { rule: /\bgh\s+workflow\s+run\b[^\n]*--watch\b/, waitsOn: "a workflow run" },
+  // A helper script whose name starts with watch- polls an external system, whatever its flags.
+  { rule: /\bwatch[-_][\w.-]*/, waitsOn: "an external state change" },
+  // --watch and --until only mean polling on provider CLIs; `git log --until` is a plain filter.
+  { rule: /\b(?:gh|github|glab)\b[^\n]*--(?:watch|until)\b/, waitsOn: "an external state change" },
+  { rule: /(?:^|[;&|]\s*)watch\s+\S/, waitsOn: "a repeating command" },
+  { rule: /\btail\s+-[a-zA-Z]*[fF]/, waitsOn: "a growing file" },
+  { rule: /\bdocker\s+(?:logs|events)\b[^\n]*\s-f\b/, waitsOn: "a container's log stream" },
+  { rule: /\bkubectl\b[^\n]*(?:--watch\b|\s-w\b)/, waitsOn: "cluster state" },
+  // A poll loop only counts when its body actually waits on something.
+  { rule: /\b(?:until|while)\b[^\n]*\b(?:sleep|curl|gh\s|docker\s|kubectl\s|pg_isready)\b/, waitsOn: "a repeated external check" },
+];
+
+const SLEEP = /(?:^|[;&|(]\s*|\bsudo\s+)sleep\s+(\d+(?:\.\d+)?)/;
+
+export function detectForegroundWait(command: string): WaitMatch | undefined {
+  for (const { rule, waitsOn } of RULES) {
+    if (rule.test(command)) return { rule: rule.source, waitsOn };
+  }
+  const sleep = SLEEP.exec(command);
+  if (sleep) {
+    const seconds = Number(sleep[1]);
+    if (Number.isFinite(seconds) && seconds > SLEEP_THRESHOLD_SECONDS) {
+      return { rule: SLEEP.source, waitsOn: `${seconds} seconds of wall clock` };
+    }
+  }
+  return undefined;
+}
+
+/** The message the model reads instead of the command's output. */
+export function blockReason(match: WaitMatch): string {
+  return [
+    `This command waits on ${match.waitsOn}, so it belongs in a background task.`,
+    "Spawn it with bg_task_spawn, then call wait_for_operations to park until it reports; a background task survives the end of the turn, while a foreground wait does not.",
+    "Read bg_task_status and bg_task_log for the verdict.",
+    'To run this command in the foreground anyway, set Tool call guard to Off in Harness settings.',
+  ].join(" ");
+}

package/extensions/worktree-context.ts

@@ -0,0 +1,157 @@
+/**
+ * Project context follows the linked worktree that owns the working directory.
+ *
+ * Pi loads one global context file from the agent directory and one file from
+ * every ancestor of the working directory. In a linked worktree (`git worktree
+ * add`) those ancestors include the main checkout, so the worktree inherits its
+ * instructions in addition to its own. The worktree is the project context root:
+ * keep the global file and files at or below the worktree root, drop everything
+ * loaded above it. A worktree without its own context file therefore starts
+ * without the main checkout's file instead of falling back to it.
+ *
+ * This module only filters. It never adds a context file or a prompt section, so
+ * `--no-context-files` keeps its empty list, and it returns nothing to Pi, so
+ * guidance keeps arriving as sections (ADR 0016, ADR 0021). A host that
+ * rebuilds the prompt from `systemPromptOptions` after the `before_agent_start`
+ * handlers applies the filtered list; on a host that does not rebuild, the
+ * mutation is inert rather than a whole-prompt return.
+ *
+ * Subagent children use a vendored copy of this file
+ * (`packages/pi-better-subagents/shared-worktree-context.ts`) because a
+ * standalone Subagents install has no Harness package.
+ */
+
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+
+/** The subset of a loaded context file this module needs to read. */
+export interface ProjectContextFile {
+    path: string;
+}
+
+/** The subset of Pi's structured prompt options this module edits. */
+export interface ProjectContextOptions {
+    /** Working directory the prompt was built for. Falls back to `process.cwd()`. */
+    cwd?: string;
+    contextFiles?: ProjectContextFile[];
+}
+
+interface GitPaths {
+    /** Directory holding the `.git` file or directory found for the working tree. */
+    repoDir: string;
+    /** Git directory for this working tree (`.git/worktrees/<name>` when linked). */
+    gitDir: string;
+    /** Git directory holding the shared object database and administrative state. */
+    commonGitDir: string;
+}
+
+function canonicalizePath(path: string): string {
+    try {
+        return realpathSync(path);
+    } catch {
+        return path;
+    }
+}
+
+/** Compare paths the way the host does: resolved, and case-folded on Windows. */
+function comparisonKey(path: string): string {
+    const resolved = resolve(path);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+/** True when `child` is `parent` or inside it. */
+function isPathWithin(parent: string, child: string): boolean {
+    const parentKey = comparisonKey(parent);
+    const childKey = comparisonKey(child);
+    if (childKey === parentKey) return true;
+    return childKey.startsWith(parentKey.endsWith(sep) ? parentKey : `${parentKey}${sep}`);
+}
+
+/** Find the nearest working tree above `startDir` without running Git. */
+function findGitPaths(startDir: string): GitPaths | undefined {
+    let dir = resolve(startDir);
+    while (true) {
+        const gitPath = join(dir, ".git");
+        if (existsSync(gitPath)) {
+            try {
+                const stat = statSync(gitPath);
+                if (stat.isFile()) {
+                    const content = readFileSync(gitPath, "utf8").trim();
+                    if (!content.startsWith("gitdir: ")) return undefined;
+                    const gitDir = resolve(dir, content.slice(8).trim());
+                    if (!existsSync(join(gitDir, "HEAD"))) return undefined;
+                    // A linked worktree has `commondir`; a submodule's gitdir has none,
+                    // and keeps ordinary ancestor inheritance.
+                    const commonDirPath = join(gitDir, "commondir");
+                    const commonGitDir = existsSync(commonDirPath)
+                        ? resolve(gitDir, readFileSync(commonDirPath, "utf8").trim())
+                        : gitDir;
+                    return { repoDir: dir, gitDir, commonGitDir };
+                }
+                if (stat.isDirectory()) {
+                    if (!existsSync(join(gitPath, "HEAD"))) return undefined;
+                    return { repoDir: dir, gitDir: gitPath, commonGitDir: gitPath };
+                }
+            } catch {
+                return undefined;
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir) return undefined;
+        dir = parent;
+    }
+}
+
+/**
+ * The linked worktree root that owns `cwd`, or undefined for an ordinary
+ * checkout. Returned canonicalized, because a worktree's `.git` file records the
+ * real path while `cwd` may still be a symlink (macOS `/tmp` → `/private/tmp`).
+ */
+export function findLinkedWorktreeRoot(cwd: string): string | undefined {
+    const gitPaths = findGitPaths(canonicalizePath(cwd));
+    // Only a shared object store makes this a worktree; the main checkout, a
+    // separate `.git` directory and a submodule keep ordinary inheritance.
+    if (!gitPaths || gitPaths.gitDir === gitPaths.commonGitDir) return undefined;
+    return canonicalizePath(gitPaths.repoDir);
+}
+
+/**
+ * Where Pi selected a context file, canonicalized through its directory only.
+ *
+ * Resolving the whole path would follow a filename symlink to its target, which
+ * inverts both cases that matter: a worktree `AGENTS.md` linking to the main
+ * checkout's file would look like inherited context, and the main checkout's
+ * `AGENTS.md` linking back into the worktree would look local. The boundary is
+ * the location the loader selected, so resolve the containing directory (macOS
+ * `/tmp` → `/private/tmp`, a symlinked cwd, a symlinked agent directory) and
+ * keep the selected filename itself.
+ */
+function selectedContextPath(filePath: string): string {
+    return join(canonicalizePath(dirname(filePath)), basename(filePath));
+}
+
+/**
+ * Drop project context loaded above the linked worktree that owns `cwd`.
+ *
+ * The global file Pi selected under `agentDir` always survives, even when that
+ * filename is a symlink to a file outside the agent directory, because the
+ * global selection is not inherited checkout context. Outside a linked worktree
+ * this is a no-op, so ordinary repositories keep every ancestor file. A host
+ * that hands over no prompt options is left unchanged. Mutates
+ * `options.contextFiles` in place because Pi hands the handler its mutable
+ * prompt options.
+ */
+export function restrictContextFilesToWorktree(options: ProjectContextOptions | undefined, agentDir: string): void {
+    if (!options) return;
+    const files = options.contextFiles;
+    if (!files || files.length === 0) return;
+    const worktreeRoot = findLinkedWorktreeRoot(options.cwd ?? process.cwd());
+    if (!worktreeRoot) return;
+    const allowedRoots = [worktreeRoot, canonicalizePath(agentDir)];
+    const kept = files.filter((file) => {
+        const path = selectedContextPath(file.path);
+        return allowedRoots.some((root) => isPathWithin(root, path));
+    });
+    if (kept.length === files.length) return;
+    options.contextFiles = kept;
+}

package/node_modules/pi-better-goal/README.md

@@ -65,10 +65,12 @@ After every successful context compaction (Pi's `session_compact` event) while a
 
 ### Scheduler-backed workflow gates
 
-A coordinator that ships the resolve-issues scheduler (`scripts/next-actions.mjs` in its skill directory, or in a sibling `resolve-issues` skill) keeps its Goal from ending while the run still has work. The extension first runs `node next-actions.mjs --run <run dir> --slots 1 --peek --json` (read-only, 20-second timeout), where the run directory is the folder of the task plan bound through `update_plan`. For completion and handback only, if the sole due action is `sync`, it reruns with `--sync` to obtain a fresh issue tree. This live check has a four-minute timeout to accommodate the tree fetcher's network attempts and follow-ups. Because `--peek` suppresses scheduler bookkeeping but not issue-tree cache writes, the live check uses a temporary copy of the scheduler's plan, tree, bookkeeping, review, and result inputs; it does not write the bound run. Heartbeat probes never request live synchronization. A failed or incomplete tree fetch that produces `sync` still refuses completion or handback; cached evidence is not treated as live. Every gate retains its fail-open behavior for execution failures: if the scheduler is missing, errors, times out, prints bad output, or no plan is bound yet, the call proceeds and its result carries a warning, so nothing deadlocks.
+A coordinator that ships the resolve-issues scheduler (`scripts/next-actions.mjs` in its skill directory, or in a sibling `resolve-issues` skill) keeps its Goal from ending while the run still has work. The extension first runs `node next-actions.mjs --run <run dir> --slots 1 --peek --json` (read-only, 20-second timeout), where the run directory is the folder of the task plan bound through `update_todo` with `workflow.path` and `workflow.revision`. For completion and handback only, if the sole due action is `sync`, it reruns with `--sync` to obtain a fresh issue tree. This live check has a four-minute timeout to accommodate the tree fetcher's network attempts and follow-ups. Because `--peek` suppresses scheduler bookkeeping but not issue-tree cache writes, the live check uses a temporary copy of the scheduler's plan, tree, bookkeeping, review, and result inputs; it does not write the bound run. Heartbeat probes never request live synchronization. A failed or incomplete tree fetch that produces `sync` still refuses completion or handback; cached evidence is not treated as live. Output that is not a well-formed due list is a failure, not an empty run: a due entry without an `action` invalidates the whole answer instead of being dropped, so it cannot hide due work.
 
-- **Completion.** `update_goal` complete is refused, with each due action (action, unit, first 200 characters of detail), unless the scheduler reports `finish` and nothing else is due (an empty due list means workers are still running, so it is refused too). The Goal stays active.
-- **Pause.** `release_workflow` is refused unless every unfinished unit is quiet (nothing due for it) or blocked `human-decision` with `humanItem` 2-5. A unit blocked `retry-ci` or any other reason the run retries itself, or a `human-decision` item 1, is named in the refusal and the Goal stays active.
+How a gate reports an unverifiable run follows the workflow that owns it. The issue workflows (`rush-issues` and `resolve-issues`) always have a scheduler available (rush-issues through its `resolve-issues` dependency), so only that scheduler can declare their run finished: a missing plan, a missing scheduler, a scheduler error, a timeout, or invalid output refuses completion and leaves the Goal active and the workflow bound. A coordinator that ships no scheduler, such as a release workflow, has no run authority to consult, so its completion gate keeps the fail-open warning that avoids deadlocking it.
+
+- **Completion.** `update_goal` complete is refused, with each due action (action, unit, first 200 characters of detail), unless the scheduler reports `finish` and nothing else is due (an empty due list means workers are still running, so it is refused too). An unverifiable issue-workflow run is refused as well, with the step that restores it: bind the task plan with `update_todo({workflow:{path,revision}})`, rebind the run with `/skill:<coordinator>`, or fix the scheduler. The Goal stays active.
+- **Pause.** `release_workflow` is refused unless every unfinished unit is quiet (nothing due for it) or blocked `human-decision` with `humanItem` 2-5. A unit blocked `retry-ci` or any other reason the run retries itself, or a `human-decision` item 1, is named in the refusal and the Goal stays active. Execution failures keep the fail-open warning here, so a genuine human hold can always hand the run back.
 - **Auto-bind.** Invoking `/skill:rush-issues` or `/skill:resolve-issues` with no active goal (none, or a completed one) creates and activates a Goal whose objective is the invocation text, exactly as `/goal <invocation>` would, without sending the command a second time. A paused or active Goal is left alone.
 - **Wait timer.** When the scheduler's only due action is `wait` with a "next automatic attempt is at <ISO time>" detail, the next automatic continuation is scheduled for that time (at most the maximum timer delay, at least 5 seconds) and the wake-up is not counted as a no-progress retry. Other due work, or an unparseable time, uses the ordinary retry schedule. `autoContinue` off disables this timer.
 

package/node_modules/pi-better-goal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.12.1",
+  "version": "0.12.2",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-goal/src/index.ts

@@ -42,7 +42,7 @@ import {
 import { createRenderScheduler } from "./shared-render-scheduler.js";
 import { initializeNavigatorPanels, setNavigatorPanel } from "./shared-navigator-panels.js";
 import { collectSubagentActivity } from "./subagents.js";
-import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
+import { currentWorkflowOwner, ISSUE_WORKFLOW_SKILLS, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
 import { completionGate, pauseGate, schedulerWaitUntil, operationResumeSchedulerGate } from "./workflow-gates.js";
 import { workflowRehydrateMessage, WORKFLOW_REHYDRATE_MESSAGE_TYPE } from "./rehydrate.js";
 import { requestTaskContext } from "./task-context.js";
@@ -66,7 +66,7 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** Never re-poll a workflow's scheduler sooner than this, even when its stated attempt time has passed. */
 const MIN_WAIT_DELAY_MS = 5_000;
 /** Workflow skills whose invocation binds a goal when none is active, so the run cannot stop silently. */
-const AUTO_BIND_SKILLS = new Set(["rush-issues", "resolve-issues"]);
+const AUTO_BIND_SKILLS = ISSUE_WORKFLOW_SKILLS;
 const WAKE_DISABLED =
   process.env.PI_BETTER_GOAL_DISABLE_WAKE === "1" ||
   process.env.PI_BETTER_EXTENSION_DISABLE_WAKE === "1";

package/node_modules/pi-better-goal/src/workflow-gates.ts

@@ -3,7 +3,7 @@ import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
-import type { WorkflowOwner } from "./workflow.js";
+import { ISSUE_WORKFLOW_SKILLS, type WorkflowOwner } from "./workflow.js";
 
 /** Branch entry the plan extension writes when it binds a workflow-owned task plan. */
 const WORKFLOW_PLAN_ENTRY = "pi-better-workflow-plan";
@@ -88,13 +88,18 @@ function parseSchedulerOutput(stdout: string): SchedulerRun {
     return { ok: false, reason: "the scheduler printed output that is not JSON" };
   }
   if (!isRecord(parsed) || !Array.isArray(parsed.due)) return { ok: false, reason: "the scheduler output has no due list" };
-  const due = parsed.due.flatMap((item): SchedulerAction[] => isRecord(item) && typeof item.action === "string"
-    ? [{
+  const due: SchedulerAction[] = [];
+  for (const item of parsed.due) {
+    // A malformed entry could hide due work, so it invalidates the answer instead of being dropped.
+    if (!isRecord(item) || typeof item.action !== "string") {
+      return { ok: false, reason: "the scheduler output has a due entry without an action" };
+    }
+    due.push({
       action: item.action,
       unit: item.unit === null || item.unit === undefined ? null : String(item.unit),
       detail: typeof item.detail === "string" ? item.detail : "",
-    }]
-    : []);
+    });
+  }
   return { ok: true, due };
 }
 
@@ -114,6 +119,10 @@ function executeScheduler(script: string, runDir: string, timeoutMs: number, liv
         if (error) {
           // An exit status of 1 means "actions due"; any other failure (exit 2, timeout, spawn error) is real.
           if ((error as { code?: unknown }).code !== 1) {
+            if ((error as { killed?: unknown }).killed === true) {
+              resolve({ ok: false, reason: `the scheduler timed out after ${timeoutMs} ms` });
+              return;
+            }
             const detail = String(stderr).trim().split("\n")[0] || error.message;
             resolve({ ok: false, reason: `the scheduler failed (${detail.slice(0, DETAIL_LIMIT)})` });
             return;
@@ -150,11 +159,14 @@ interface PlannedRun {
   script: string;
 }
 
-function locateRun(entries: Iterable<EntryLike>, owner: WorkflowOwner): PlannedRun | { warning: string } {
+/** The run a gate would check, or what it could not locate, so each gate decides how to report it. */
+type RunLocation = PlannedRun | { missing: "scheduler" | "plan"; problem: string };
+
+function locateRun(entries: Iterable<EntryLike>, owner: WorkflowOwner): RunLocation {
   const script = findScheduler(owner);
-  if (!script) return { warning: `${owner.name} ships no scheduler, so the run was not checked` };
+  if (!script) return { missing: "scheduler", problem: `${owner.name} ships no scheduler` };
   const plan = boundPlanPath(entries, owner);
-  if (!plan) return { warning: `no task plan is bound for ${owner.name} yet, so the run was not checked` };
+  if (!plan) return { missing: "plan", problem: `no task plan is bound for ${owner.name} yet` };
   return { runDir: dirname(plan), script };
 }
 
@@ -167,16 +179,50 @@ function describe(action: SchedulerAction): string {
   return `- ${action.action}${action.unit ? ` (unit ${action.unit})` : ""}: ${detail}`;
 }
 
-/** Completion is allowed only when the scheduler reports `finish` and nothing else is due. */
+/** Coordinators whose runs the resolve-issues scheduler drives, so only it can declare the run finished. */
+function schedulerOwnsCompletion(owner: WorkflowOwner): boolean {
+  return ISSUE_WORKFLOW_SKILLS.has(owner.name);
+}
+
+function unverifiedCompletion(owner: WorkflowOwner, problem: string, recovery: string): GateVerdict {
+  return {
+    allow: false,
+    due: [],
+    message: `Goal not marked complete: ${problem}, so the run's completion is not verified. ${recovery} ` +
+      `The ${owner.name} workflow stays bound and the Goal stays active.`,
+  };
+}
+
+/**
+ * Completion is allowed only when the scheduler reports `finish` and nothing else is due. For the
+ * issue workflows an unavailable plan or scheduler never counts as permission: the run has a
+ * completion authority, and only that authority may declare it finished. Any other coordinator has
+ * no scheduler to consult, so its gate keeps the fail-open warning that avoids deadlocking it.
+ */
 export async function completionGate(
   entries: Iterable<EntryLike>,
   owner: WorkflowOwner,
   options: { timeoutMs?: number } = {},
 ): Promise<GateVerdict> {
+  const owned = schedulerOwnsCompletion(owner);
   const located = locateRun(entries, owner);
-  if ("warning" in located) return unchecked(located.warning);
+  if ("missing" in located) {
+    if (!owned) return unchecked(`${located.problem}, so the run was not checked`);
+    const recovery = located.missing === "plan"
+      ? `Bind the run's task plan with update_todo({workflow:{path,revision}}), or rebind the run with /skill:${owner.name}, ` +
+        "then call update_goal again once the scheduler reports finish."
+      : `Restore the run's scheduler or rebind the run with /skill:${owner.name}, ` +
+        "then call update_goal again once the scheduler reports finish.";
+    return unverifiedCompletion(owner, located.problem, recovery);
+  }
   const run = await settlementScheduler(located.script, located.runDir, options.timeoutMs);
-  if (!run.ok) return unchecked(`could not check the ${owner.name} run (${run.reason})`);
+  if (!run.ok) {
+    const problem = `the ${owner.name} run could not be checked (${run.reason})`;
+    if (!owned) return unchecked(problem);
+    return unverifiedCompletion(owner, problem,
+      `Fix the scheduler, or rebind the run with /skill:${owner.name} if its plan moved, ` +
+      "then call update_goal again once the scheduler reports finish.");
+  }
   const open = run.due.filter((action) => action.action !== "finish");
   if (open.length === 0 && run.due.length > 0) return { allow: true };
   if (open.length === 0) {
@@ -215,7 +261,7 @@ export async function pauseGate(
   options: { timeoutMs?: number } = {},
 ): Promise<GateVerdict> {
   const located = locateRun(entries, owner);
-  if ("warning" in located) return unchecked(located.warning);
+  if ("missing" in located) return unchecked(`${located.problem}, so the run was not checked`);
   const units = readUnits(located.runDir);
   if (!units) return unchecked(`could not read the ${owner.name} task plan`);
   const run = await settlementScheduler(located.script, located.runDir, options.timeoutMs);
@@ -271,7 +317,7 @@ export async function operationResumeSchedulerGate(
   options: { timeoutMs?: number } = {},
 ): Promise<OperationResumeSchedulerGate> {
   const located = locateRun(entries, owner);
-  if ("warning" in located) return { ok: false, reason: located.warning };
+  if ("missing" in located) return { ok: false, reason: `${located.problem}, so the run was not checked` };
   const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
   if (!run.ok) return { ok: false, reason: `Workflow admission evidence unavailable: ${run.reason}` };
   return { ok: true, waitUntil: waitUntil(run.due) };
@@ -284,7 +330,7 @@ export async function schedulerWaitUntil(
   options: { timeoutMs?: number } = {},
 ): Promise<number | undefined> {
   const located = locateRun(entries, owner);
-  if ("warning" in located) return undefined;
+  if ("missing" in located) return undefined;
   const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
   return run.ok ? waitUntil(run.due) : undefined;
 }

package/node_modules/pi-better-goal/src/workflow.ts

@@ -3,6 +3,13 @@ import { parse } from "yaml";
 
 export const WORKFLOW_ENTRY_TYPE = "pi-better-workflow";
 
+/**
+ * Coordinators whose runs the resolve-issues scheduler drives, so only its next-actions scheduler can
+ * declare the run finished. Other coordinators (a release workflow, say) ship no scheduler, and their
+ * completion gates keep the fail-open behavior that avoids deadlocking them.
+ */
+export const ISSUE_WORKFLOW_SKILLS: ReadonlySet<string> = new Set(["rush-issues", "resolve-issues"]);
+
 export interface WorkflowOwner {
   name: string;
   path: string;