pi-gauntlet 4.4.3 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v4.5.0 - 2026-07-30
+
+Recover stalled automatic handoffs without weakening gauntlet gates (#3). The existing
+phase-tracker now sends one branch-local, fire-and-forget continuation nudge when an
+`agent_settled` event leaves either `plan -> implement` or `verify -> ship` pending. The
+handler requires brainstorming entry, no active phase, a non-aborted stop, an exact
+recognized edge, an unspent ancestry-local attempt, and a final idle check. Recovery
+messages persist their edge in custom-message details, so repeated settlements and session
+reconstruction do not re-trigger the same unchanged handoff.
+
+The implementation remains deliberately narrow: no transition engine, retry loop, timer,
+settings key, phase mutation, or older-host fallback. Prompt wording now reinforces both
+automatic handoffs, while specification approval and the final branch disposition remain
+human gates. Pure classifier tests and real extension event tests cover edge selection,
+persistence, abort/idleness guards, competing-handler ordering, and one-shot behavior.
+
 ## v4.4.3 - 2026-07-19
 
 Brainstorming is the sole gauntlet entry point (#2): gate all three phase-tracker

package/README.md

@@ -41,6 +41,8 @@ Concretely, one change through the gauntlet:
 4. **verify**: a whole-diff code review, then the **conformance gate** - a subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a dense list - one line per decision, plain-language, with its recommended choice inline. Reply `1` to take every recommendation, or `2:` with per-item overrides; a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
 5. **`finishing-a-development-branch`**: squash, PR, keep, or discard. **Human gate 2** - the only other decision you make.
 
+Only the machine-owned `plan -> implement` and `verify -> ship` handoffs receive a branch-local one-shot nudge after an unexpected settled stop; it is fire-and-forget, does not bypass either human gate, and older Pi hosts without `agent_settled` retain existing behavior.
+
 ```mermaid
 flowchart LR
     R([request]) --> B[brainstorm<br/>+ spec]

package/extensions/lib/phase-tracker-helpers.test.ts

@@ -14,8 +14,51 @@ import {
   markerBlockReason,
   transitionPhaseState,
   markerGuardApplies,
+  recoverableEdge,
+  type RecoveryPhaseMap,
+  type RecoveryPhaseStatus,
 } from "./phase-tracker-helpers.ts";
 
+const recoveryPhases = (
+  overrides: Partial<Record<keyof RecoveryPhaseMap, RecoveryPhaseStatus>> = {},
+): RecoveryPhaseMap =>
+  Object.fromEntries(
+    (["brainstorm", "plan", "implement", "verify", "ship"] as const).map((phase) => [
+      phase,
+      { status: overrides[phase] ?? "pending" },
+    ]),
+  ) as RecoveryPhaseMap;
+
+test("recoverableEdge: recognizes only the two authorized edges", () => {
+  assert.equal(recoverableEdge(recoveryPhases({ plan: "complete" })), "plan-implement");
+  assert.equal(recoverableEdge(recoveryPhases({ verify: "complete" })), "verify-ship");
+});
+
+test("recoverableEdge: rejects any active phase", () => {
+  for (const phase of ["brainstorm", "plan", "implement", "verify", "ship"] as const) {
+    const recoverable: Partial<Record<keyof RecoveryPhaseMap, RecoveryPhaseStatus>> = phase === "verify" || phase === "ship" ? { plan: "complete" } : { verify: "complete" };
+    assert.equal(recoverableEdge(recoveryPhases(recoverable)), phase === "verify" || phase === "ship" ? "plan-implement" : "verify-ship");
+    assert.equal(recoverableEdge(recoveryPhases({ ...recoverable, [phase]: "in_progress" })), undefined);
+  }
+});
+
+test("recoverableEdge: rejects invalid source and destination states", () => {
+  for (const status of ["pending", "in_progress", "skipped"] as const) {
+    assert.equal(recoverableEdge(recoveryPhases({ plan: status })), undefined);
+    assert.equal(recoverableEdge(recoveryPhases({ verify: status })), undefined);
+  }
+  for (const status of ["in_progress", "complete", "skipped"] as const) {
+    assert.equal(recoverableEdge(recoveryPhases({ plan: "complete", implement: status })), undefined);
+    assert.equal(recoverableEdge(recoveryPhases({ verify: "complete", ship: status })), undefined);
+  }
+});
+
+test("recoverableEdge: rejects unrelated and ambiguous phase maps", () => {
+  assert.equal(recoverableEdge(recoveryPhases()), undefined);
+  assert.equal(recoverableEdge(recoveryPhases({ brainstorm: "complete", implement: "complete" })), undefined);
+  assert.equal(recoverableEdge(recoveryPhases({ plan: "complete", verify: "complete" })), undefined);
+});
+
 test("checkSubstep: in_progress -> ok", () => {
   assert.deepEqual(checkSubstep("in_progress"), { ok: true });
 });

package/extensions/lib/phase-tracker-helpers.ts

@@ -10,6 +10,21 @@ export const CONTEXT_DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replac
 
 export type SubstepCheck = { ok: true } | { ok: false; error: string };
 
+export type RecoveryEdge = "plan-implement" | "verify-ship";
+export type RecoveryPhaseStatus = "pending" | "in_progress" | "complete" | "skipped";
+export type RecoveryPhaseMap = Record<
+  "brainstorm" | "plan" | "implement" | "verify" | "ship",
+  { status: RecoveryPhaseStatus }
+>;
+
+export function recoverableEdge(phases: RecoveryPhaseMap): RecoveryEdge | undefined {
+  if (Object.values(phases).some((phase) => phase.status === "in_progress")) return undefined;
+  const planImplement = phases.plan.status === "complete" && phases.implement.status === "pending";
+  const verifyShip = phases.verify.status === "complete" && phases.ship.status === "pending";
+  if (planImplement === verifyShip) return undefined;
+  return planImplement ? "plan-implement" : "verify-ship";
+}
+
 export function checkSubstep(phaseStatus: string): SubstepCheck {
   if (phaseStatus === "in_progress") return { ok: true };
   return { ok: false, error: `substep requires an in_progress phase (status is ${phaseStatus})` };

package/extensions/phase-tracker.test.ts

@@ -0,0 +1,159 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import registerPhaseTracker from "./phase-tracker.ts";
+
+const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
+type Phase = (typeof PHASES)[number];
+type Status = "pending" | "in_progress" | "complete" | "skipped";
+
+const phases = (overrides: Partial<Record<Phase, Status>> = {}) =>
+  Object.fromEntries(PHASES.map((phase) => [phase, { status: overrides[phase] ?? "pending" }])) as Record<
+    Phase,
+    { status: Status }
+  >;
+
+const phaseResult = (action: string, state: Record<Phase, { status: Status }>) => ({
+  type: "message",
+  message: { role: "toolResult", toolName: "phase_tracker", details: { action, phases: state } },
+});
+
+const assistant = (stopReason = "stop") => ({ type: "message", message: { role: "assistant", stopReason } });
+
+const enteredBranch = (state: Record<Phase, { status: Status }>, extra: unknown[] = []) => [
+  phaseResult("start", phases({ brainstorm: "in_progress" })),
+  phaseResult("complete", state),
+  ...extra,
+];
+
+function harness(options: { branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
+  const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
+  const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
+  const sent: { message: any; options: any }[] = [];
+  let idle = options.idle ?? true;
+  const ctx = {
+    cwd: process.cwd(),
+    hasUI: false,
+    isIdle: () => idle,
+    sessionManager: { getBranch: () => options.branch ?? [] },
+  };
+  const pi = {
+    on(event: string, handler: (event: unknown, context: unknown) => unknown) {
+      const registered = handlers.get(event) ?? [];
+      registered.push(handler);
+      handlers.set(event, registered);
+    },
+    registerTool(tool: { name: string; execute: (...args: any[]) => unknown }) {
+      tools.push(tool);
+    },
+    sendMessage(message: unknown, sendOptions: unknown) {
+      sent.push({ message, options: sendOptions });
+      if (options.sendThrows) throw new Error("send failed");
+    },
+  };
+  if (options.beforeSettled) pi.on("agent_settled", () => options.beforeSettled!(next => (idle = next)));
+  registerPhaseTracker(pi as any);
+  const emit = async (event: string) => {
+    for (const handler of handlers.get(event) ?? []) await handler({ type: event }, ctx);
+  };
+  return { emit, sent, tools, setIdle: (next: boolean) => (idle = next) };
+}
+
+const settle = async (h: ReturnType<typeof harness>) => {
+  await h.emit("session_start");
+  await h.emit("agent_settled");
+};
+
+test("agent_settled nudges each exact edge with persisted details", async () => {
+  for (const [state, edge, skill] of [
+    [phases({ brainstorm: "complete", plan: "complete" }), "plan-implement", "/skill:subagent-driven-development"],
+    [
+      phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" }),
+      "verify-ship",
+      "/skill:finishing-a-development-branch",
+    ],
+  ] as const) {
+    const h = harness({ branch: enteredBranch(state, [assistant()]) });
+    await settle(h);
+    assert.equal(h.sent.length, 1);
+    assert.deepEqual(h.sent[0].options, { triggerTurn: true });
+    assert.equal(h.sent[0].message.customType, "pi-gauntlet-transition-recovery");
+    assert.equal(h.sent[0].message.display, true);
+    assert.deepEqual(h.sent[0].message.details, { piGauntletRecoveryEdge: edge });
+    assert.match(h.sent[0].message.content, new RegExp(skill.replace(/[/-]/g, "\\$&")));
+  }
+});
+
+test("repeated settlement and persisted matching recovery details suppress a second nudge", async () => {
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  const h = harness({ branch: enteredBranch(state, [assistant()]) });
+  await settle(h);
+  await h.emit("agent_settled");
+  assert.equal(h.sent.length, 1);
+
+  const restored = harness({
+    branch: enteredBranch(state, [
+      { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: { piGauntletRecoveryEdge: "plan-implement" } },
+      assistant(),
+    ]),
+  });
+  await settle(restored);
+  assert.equal(restored.sent.length, 0);
+});
+
+test("foreign or malformed custom-message details do not suppress recovery", async () => {
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  for (const entry of [
+    { type: "custom_message", customType: "other", details: { piGauntletRecoveryEdge: "plan-implement" } },
+    { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: null },
+    { type: "custom_message", customType: "pi-gauntlet-transition-recovery", details: { piGauntletRecoveryEdge: "nope" } },
+  ]) {
+    const h = harness({ branch: enteredBranch(state, [entry, assistant()]) });
+    await settle(h);
+    assert.equal(h.sent.length, 1);
+  }
+});
+
+test("only brainstorming-entered, non-aborted settled flows recover", async () => {
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  const cold = harness({ branch: [phaseResult("complete", state), assistant()] });
+  await settle(cold);
+  assert.equal(cold.sent.length, 0);
+
+  const branch = enteredBranch(state, [assistant("aborted")]);
+  const aborted = harness({ branch });
+  await settle(aborted);
+  assert.equal(aborted.sent.length, 0);
+  branch.push(assistant());
+  await aborted.emit("agent_settled");
+  assert.equal(aborted.sent.length, 1);
+});
+
+test("active phases, non-idleness, and earlier competing handlers do not spend recovery", async () => {
+  for (const phase of PHASES) {
+    const h = harness({ branch: enteredBranch(phases({ brainstorm: phase === "brainstorm" ? "in_progress" : "complete", plan: phase === "plan" ? "in_progress" : "complete", implement: phase === "implement" ? "in_progress" : "pending", verify: phase === "verify" ? "in_progress" : "pending", ship: phase === "ship" ? "in_progress" : "pending" }), [assistant()]) });
+    await settle(h);
+    assert.equal(h.sent.length, 0, phase);
+  }
+
+  const state = phases({ brainstorm: "complete", plan: "complete" });
+  const notIdle = harness({ branch: enteredBranch(state, [assistant()]), idle: false });
+  await settle(notIdle);
+  notIdle.setIdle(true);
+  await notIdle.emit("agent_settled");
+  assert.equal(notIdle.sent.length, 1);
+
+  const ordered = harness({
+    branch: enteredBranch(state, [assistant()]),
+    beforeSettled: setIdle => setIdle(false),
+  });
+  await settle(ordered);
+  assert.equal(ordered.sent.length, 0);
+});
+
+test("a throwing send spends the in-memory edge", async () => {
+  const h = harness({ branch: enteredBranch(phases({ brainstorm: "complete", plan: "complete" }), [assistant()]), sendThrows: true });
+  await h.emit("session_start");
+  await assert.rejects(h.emit("agent_settled"), /send failed/);
+  await h.emit("agent_settled");
+  assert.equal(h.sent.length, 1);
+});

package/extensions/phase-tracker.ts

@@ -31,9 +31,11 @@ import {
   nextGauntletEntered,
   parseGitCommit,
   phaseLabel,
+  recoverableEdge,
   resolveRepoDir,
   STMT_START,
   transitionPhaseState,
+  type RecoveryEdge,
 } from "./lib/phase-tracker-helpers.ts";
 
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
@@ -80,6 +82,18 @@ const SHIP_ADVISORY =
   "menu is the human gate that resolves any carried-open decision. Only reopen verify if\n" +
   "a `fix` gap was left unresolved (neither fixed nor deferred).";
 
+const RECOVERY_CUSTOM_TYPE = "pi-gauntlet-transition-recovery";
+const RECOVERY_MESSAGES: Record<RecoveryEdge, string> = {
+  "plan-implement": "Continue the approved workflow now. Invoke /skill:subagent-driven-development.",
+  "verify-ship": "Continue the approved workflow now. Invoke /skill:finishing-a-development-branch.",
+};
+
+const recoveryEdgeFromDetails = (details: unknown): RecoveryEdge | undefined => {
+  if (!details || typeof details !== "object") return undefined;
+  const edge = (details as { piGauntletRecoveryEdge?: unknown }).piGauntletRecoveryEdge;
+  return edge === "plan-implement" || edge === "verify-ship" ? edge : undefined;
+};
+
 // --- Flow guards (spec 2026-06-17-gauntlet-flow-guards) ---
 
 const GUARD_PHASES: Phase[] = ["brainstorm", "plan", "implement"];
@@ -242,6 +256,7 @@ export default function (pi: ExtensionAPI) {
   let phases: PhaseMap = emptyPhases();
   let conformanceDispatched = false;
   let gauntletEntered = false;
+  const attemptedRecoveryEdges = new Set<RecoveryEdge>();
 
   // Warn-once-per-phase ledger; cleared on every phase transition and on reconstruct.
   const firedGuards = new Map<string, boolean>();
@@ -286,13 +301,29 @@ export default function (pi: ExtensionAPI) {
     }
   };
 
+  const branchLatestAssistantStopReason = (ctx: ExtensionContext): string | undefined => {
+    let stopReason: string | undefined;
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "assistant") stopReason = entry.message.stopReason;
+    }
+    return stopReason;
+  };
+
   const reconstructState = (ctx: ExtensionContext) => {
     phases = emptyPhases();
     conformanceDispatched = false;
     gauntletEntered = false;
+    attemptedRecoveryEdges.clear();
     firedGuards.clear();
     pendingGuardWarnings.clear();
     for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "custom_message") {
+        if (entry.customType === RECOVERY_CUSTOM_TYPE) {
+          const edge = recoveryEdgeFromDetails(entry.details);
+          if (edge) attemptedRecoveryEdges.add(edge);
+        }
+        continue;
+      }
       if (entry.type !== "message") continue;
       const msg = entry.message;
       if (msg.role !== "toolResult") continue;
@@ -330,6 +361,23 @@ export default function (pi: ExtensionAPI) {
     });
   }
 
+  pi.on("agent_settled", (_event, ctx) => {
+    const latestAssistantStopReason = branchLatestAssistantStopReason(ctx);
+    if (!gauntletEntered || latestAssistantStopReason === "aborted") return;
+    const edge = recoverableEdge(phases);
+    if (!edge || attemptedRecoveryEdges.has(edge) || !ctx.isIdle()) return;
+    attemptedRecoveryEdges.add(edge);
+    pi.sendMessage(
+      {
+        customType: RECOVERY_CUSTOM_TYPE,
+        content: RECOVERY_MESSAGES[edge],
+        display: true,
+        details: { piGauntletRecoveryEdge: edge },
+      },
+      { triggerTurn: true },
+    );
+  });
+
   pi.on("tool_call", async (event, ctx) => {
     // D3.b: one fresh settings read per event, lazily, only if a guard needs it.
     const addGuardWarning = (id: string, text: string) => {

package/extensions/test-support/pi-stubs.mjs

@@ -0,0 +1,41 @@
+const sources = {
+  "@earendil-works/pi-ai": `export const StringEnum = (values, options = {}) => ({ values, ...options });`,
+  "@earendil-works/pi-coding-agent": `
+    export class SettingsManager {
+      static create() { return new SettingsManager(); }
+      getGlobalSettings() { return {}; }
+      getProjectSettings() { return {}; }
+      drainErrors() { return []; }
+    }
+    export const getAgentDir = () => "/tmp/pi-gauntlet-test-agent";
+  `,
+  "@earendil-works/pi-tui": `
+    export class Text {
+      constructor(text) { this.text = text; }
+    }
+  `,
+  "@sinclair/typebox": `
+    const schema = (...args) => ({ args });
+    export const Type = {
+      Object: schema,
+      Optional: schema,
+      String: schema,
+      Boolean: schema,
+      Union: schema,
+      Null: schema,
+    };
+  `,
+};
+
+export async function resolve(specifier, context, nextResolve) {
+  if (specifier in sources) return { url: `pi-gauntlet-test:${encodeURIComponent(specifier)}`, shortCircuit: true };
+  return nextResolve(specifier, context);
+}
+
+export async function load(url, context, nextLoad) {
+  if (url.startsWith("pi-gauntlet-test:")) {
+    const specifier = decodeURIComponent(url.slice("pi-gauntlet-test:".length));
+    return { format: "module", source: sources[specifier], shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.4.3",
+  "version": "4.5.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/subagent-driven-development/SKILL.md

@@ -30,7 +30,8 @@ You are the **orchestrator**. You read the plan, dispatch, review the review, de
 - A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
 - A reviewer finds issues the implementer cannot resolve in two attempts
 - A ⚠️ workflow warning fires
-- You hit the end of the plan (then stop and report — see [After All Tasks](#after-all-tasks-complete))
+
+Reaching the end of the plan is not a pause: continue through verification and invoke `/skill:finishing-a-development-branch` as defined in [After All Tasks](#after-all-tasks-complete).
 
 Periodic "should I continue?" prompts add latency without adding safety. The plan is the contract; execute it.
 

package/skills/writing-plans/SKILL.md

@@ -231,7 +231,7 @@ Then auto-select the execution mode and proceed — no pause, no picker. The mod
 - **If any wave contains ≥2 tasks → Parallel-Wave Mode.** The strengthened Wave Grouping contract (files + runtime-resource disjoint) guarantees every multi-task wave is parallel-safe.
 - **Otherwise (pure dependency chain, one task per wave) → Sequential Mode.**
 
-Announce the selected mode in one line (transparency), then auto-invoke `/skill:subagent-driven-development` in this session. Do not wait for confirmation — the spec gate already happened, and the plan is a mechanical derivative. The only pauses from here are in-flight STOPs (`BLOCKED` / `NEEDS_CONTEXT`) and the end gate, both owned by the executor.
+Auto-invoke `/skill:subagent-driven-development` in this session. Do not wait for confirmation — the spec gate already happened, and the plan is a mechanical derivative. The only pauses from here are in-flight STOPs (`BLOCKED` / `NEEDS_CONTEXT`) and the end gate, both owned by the executor.
 
 ## Red Flags — STOP