@dieulc/workflow 0.10.0 → 0.11.0

package/review.ts

@@ -1612,8 +1612,11 @@ export function reviewFooterSegment(
   paused: boolean,
   /** A round owns the turn before its first state event (cold boot). */
   starting = false,
+  /** The reviewer finished; the plan is waiting for Approve/Revise. */
+  handoff = false,
 ): string {
   if (paused) return "🔍 review paused — /review-resume to continue";
+  if (handoff) return "🔍 review · awaiting decision";
   if (!state) return starting ? "🔍 review · starting" : "";
   return reviewStateSummary(state);
 }
@@ -1632,6 +1635,8 @@ export function reviewStatusVisible(input: {
   roundInFlight?: boolean;
   roundActive?: boolean;
   paused?: boolean;
+  /** The reviewer finished and the browser/inline handoff owns the turn. */
+  handoff?: boolean;
   /**
    * The retained round state's phase, when one exists. A retained *terminal*
    * phase must not make the line visible during a new round's cold boot
@@ -1640,6 +1645,7 @@ export function reviewStatusVisible(input: {
   phase?: ReviewPhase;
 }): boolean {
   if (input.paused === true) return true;
+  if (input.handoff === true) return true;
   if (input.roundInFlight !== true && input.roundActive !== true) return false;
   // `undefined` means the round has not emitted a state yet; there is nothing
   // stale to paint and the lock/working message still describe the round.
@@ -1659,11 +1665,13 @@ export function reviewStatusText(input: {
   roundInFlight?: boolean;
   roundActive?: boolean;
   paused?: boolean;
+  handoff?: boolean;
 }): string {
   const visible = reviewStatusVisible({
     roundInFlight: input.roundInFlight,
     roundActive: input.roundActive,
     paused: input.paused,
+    handoff: input.handoff,
     phase: input.state?.phase,
   });
   return visible
@@ -1671,6 +1679,7 @@ export function reviewStatusText(input: {
         input.state,
         input.paused === true,
         input.roundInFlight === true,
+        input.handoff === true,
       )
     : "";
 }
@@ -1723,18 +1732,77 @@ export function nextReviewRound(input: {
   return { round, allowed: round <= max };
 }
 
-// ── Mode-switch lock (plan 2026-10-25) ───────────────────────────────
+// ── Review turn + mode-switch lock (plan 2026-11-14) ─────────────────
 //
-// While a review owns the turn, mode transitions are refused: switching to
-// Build mid-review would swap the tool set and suspend the reviewer, and
-// switching to Default would leave the reviewer running outside Plan Mode.
-// The lock is a PROJECTION over existing state (never persisted), so every
-// existing exit — land, fail, pause/resume, abort, suspend, teardown —
-// releases it automatically. The post-review handoff prompt is deliberately
-// NOT part of the lock: the independent reviewer has already finished.
+// Review is an exclusive turn, not a background job: from the moment the
+// planner hands its plan to the reviewer until the browser/inline decision is
+// applied, no prompt and no mode transition is accepted. The turn is an
+// explicit state (unlike the old derived lock) because the handoff phase has
+// no running child session and must still be locked.
+//
+//   idle -> running -> paused -> running -> ... -> handoff -> transition -> idle
+//                 \-> handoff (reviewer failed/skipped) -> transition -> idle
+//
+// `transition` is the short, internal window while a decision stops the
+// reviewer, applies Build/Plan and sends the follow-up. It is locked so a
+// queued prompt cannot race the mode change.
+
+/** The exclusive Review turn. `idle` means no review owns the session. */
+export type ReviewTurnPhase =
+  | "idle"
+  | "running"
+  | "paused"
+  | "handoff"
+  | "transition";
+
+export function reviewTurnOwns(phase: ReviewTurnPhase): boolean {
+  return phase !== "idle";
+}
+
+/** Commands a user may run while Review owns the turn. */
+export function reviewInputAllowed(text: string): boolean {
+  const value = text.trim();
+  if (!value.startsWith("/")) return false;
+  return (
+    /^\/review(?:\s|-|$)/i.test(value) ||
+    /^\/model(?:\s|$)/i.test(value) ||
+    /^\/thinking(?:\s|$)/i.test(value) ||
+    /^\/profile(?:\s|$)/i.test(value) ||
+    /^\/role(?:\s|$)/i.test(value)
+  );
+}
+
+export type ReviewInputDecision =
+  | { action: "allow" }
+  | { action: "block"; notice: string };
+
+/** One decision for `pi.on("input")`; pure so the matrix is testable. */
+export function reviewInputDecision(
+  text: string,
+  phase: ReviewTurnPhase,
+): ReviewInputDecision {
+  if (!reviewTurnOwns(phase)) return { action: "allow" };
+  if (reviewInputAllowed(text)) return { action: "allow" };
+  const state =
+    phase === "paused"
+      ? "paused"
+      : phase === "handoff"
+        ? "awaiting a decision"
+        : phase === "transition"
+          ? "applying the decision"
+          : "running";
+  return {
+    action: "block",
+    notice: `Review is ${state} — prompts are locked. /review-pause, /review-resume, /review-abort, or change model/profile.`,
+  };
+}
 
 /** Which mode-switch lock is active, if any. Derived, never persisted. */
-export type ReviewModeLockKind = "running" | "paused";
+export type ReviewModeLockKind =
+  | "running"
+  | "paused"
+  | "handoff"
+  | "transition";
 
 export interface ReviewModeLockInput {
   /** `activeReview !== undefined` — set before the child session boots. */
@@ -1745,6 +1813,10 @@ export interface ReviewModeLockInput {
   paused?: boolean;
   /** The gated handoff phase; `"auditing"` counts as running. */
   gatePhase?: ReviewHandoffPhase;
+  /** The browser/inline decision owns the session. */
+  handoff?: boolean;
+  /** A decision is being applied (stop reviewer -> mode -> follow-up). */
+  transition?: boolean;
 }
 
 /**
@@ -1767,9 +1839,30 @@ export function reviewModeLockKind(
   }
   if (input.gatePhase === "paused") return "paused";
   if (input.gatePhase === "auditing") return "running";
+  if (input.transition === true) return "transition";
+  if (input.handoff === true) return "handoff";
   return undefined;
 }
 
+/**
+ * The narrower "a reviewer round or pause owns the turn" predicate.
+ * Decision handlers must use this (not the full lock): the handoff they are
+ * about to consume is not a stale decision.
+ */
+export function reviewRoundOwnsTurn(input: {
+  roundInFlight?: boolean;
+  roundActive?: boolean;
+  paused?: boolean;
+  gatePhase?: ReviewHandoffPhase;
+}): boolean {
+  return (
+    input.paused === true ||
+    input.roundInFlight === true ||
+    input.roundActive === true ||
+    input.gatePhase === "auditing"
+  );
+}
+
 /**
  * Phase to use when `/review-resume` starts a paused gated round.
  * A gated pause becomes an active audit again; a manual review (idle gate)
@@ -1803,9 +1896,16 @@ export function reviewHandoffParks(input: {
 
 /** One short notice for a blocked mode transition. */
 export function reviewModeLockNotice(kind: ReviewModeLockKind): string {
-  return kind === "paused"
-    ? "Review is paused — mode switching stays locked. /review-resume to continue, /review-abort to stop, /review-mode off to end review."
-    : "Review is running — mode switching is locked. ESC or /review-pause to pause, /review-resume to continue, /review-abort to stop, /review-mode off to end review.";
+  if (kind === "paused") {
+    return "Review is paused — mode switching stays locked. /review-resume to continue, /review-abort to stop.";
+  }
+  if (kind === "handoff") {
+    return "Review decision pending — mode switching is locked. Approve or annotate in the review tab, or /review-abort to skip.";
+  }
+  if (kind === "transition") {
+    return "Review decision is being applied — mode switching is briefly locked.";
+  }
+  return "Review is running — mode switching is locked. ESC or /review-pause to pause, /review-resume to continue, /review-abort to stop.";
 }
 
 /** Footer marker appended to the single `"workflow"` status while locked. */
@@ -1874,23 +1974,80 @@ export function truncateErrorText(input: unknown, max: number = MAX_ERROR_TEXT):
 }
 
 /**
- * Extract the provider error message when a run stopped on an error: scan an
- * `agent_end` event's messages from the end for the last assistant message
- * with `stopReason === "error"`. Structural on purpose — SDK message shapes
- * are not imported here. Returns undefined for clean runs and junk input.
+ * True when an error text describes an *abort*, not a provider failure.
+ *
+ * Review Mode deliberately aborts the reviewer's tail after `review_pass_done`
+ * (and on pause/teardown). Node rejects an aborted operation with its default
+ * reason (`DOMException: This operation was aborted`); provider SDKs use
+ * `Request was aborted`; the Pi SDK's backoff cancellation reports
+ * `Retry cancelled`. The SDK's `lazyStream` setup path can record any of those
+ * as a `stopReason: "error"` assistant message, so a stop-reason check alone
+ * is not enough to tell an abort from a provider fault.
+ *
+ * Timeouts are deliberately NOT aborts: `AbortSignal.timeout()` rejects with
+ * `The operation was aborted due to timeout`, which is a transient provider
+ * failure and must keep its recovery semantics.
+ *
+ * Matching is anchored at the start of the flattened text so a provider payload
+ * that merely mentions "aborted" is not downgraded. Pure and total.
  */
-export function lastAssistantErrorStop(messages: unknown): string | undefined {
-  if (!Array.isArray(messages)) return undefined;
+export function isAbortStopText(input: unknown): boolean {
+  const text =
+    typeof input === "string" ? input.replace(/\s+/g, " ").trim() : "";
+  if (!text) return false;
+  // Checked first: "The operation was aborted due to timeout" is a timeout.
+  if (/\b(?:timed?\s*out|timeout)\b/i.test(text)) return false;
+  // `AgentSession._finishCancelledRetry()` reports a cancelled backoff this
+  // way; it is our own abort, never provider health.
+  if (/^retry\s+cancell?ed\b/i.test(text)) return true;
+  return (
+    /^(?:this|the|request|operation|signal)\b[^.\n]{0,40}abort(?:ed|ing)?\b/i.test(
+      text,
+    ) ||
+    /^abort(?:ed)?\s*error\b/i.test(text) ||
+    /^aborted\b/i.test(text)
+  );
+}
+
+/** How the reviewer's last assistant message stopped. */
+export type ReviewStopClassification =
+  | { kind: "clean" }
+  | { kind: "aborted"; message?: string }
+  | { kind: "provider-error"; message: string };
+
+/**
+ * Classify the outcome of a child run from an `agent_end` event's messages.
+ *
+ * Structural on purpose — SDK message shapes are not imported here. Scans
+ * backwards to the last assistant message (the only one that decides the run's
+ * outcome); a missing assistant message or junk input is `clean`. An error stop
+ * with an abort-shaped message is `aborted` even when the SDK labelled it
+ * `error` (its setup path does not check the abort signal), so callers never
+ * report a host cancellation as provider health.
+ */
+export function classifyAssistantStop(
+  messages: unknown,
+): ReviewStopClassification {
+  if (!Array.isArray(messages)) return { kind: "clean" };
   for (let i = messages.length - 1; i >= 0; i--) {
     const rec = messages[i] as Record<string, unknown> | null | undefined;
     if (!rec || typeof rec !== "object") continue;
     if (rec.role !== "assistant") continue;
-    // Last assistant message reached: a non-error stop means a clean run.
-    if (rec.stopReason !== "error") return undefined;
-    const err = typeof rec.errorMessage === "string" ? rec.errorMessage : "";
-    return err || "unknown provider error";
+    // Last assistant message reached: this one decides the run outcome.
+    const stopReason = rec.stopReason;
+    if (stopReason === "aborted") {
+      const message =
+        typeof rec.errorMessage === "string" ? rec.errorMessage.trim() : "";
+      return message ? { kind: "aborted", message } : { kind: "aborted" };
+    }
+    if (stopReason !== "error") return { kind: "clean" };
+    const err = typeof rec.errorMessage === "string" ? rec.errorMessage.trim() : "";
+    if (isAbortStopText(err)) {
+      return err ? { kind: "aborted", message: err } : { kind: "aborted" };
+    }
+    return { kind: "provider-error", message: err || "unknown provider error" };
   }
-  return undefined;
+  return { kind: "clean" };
 }
 
 /**
@@ -1902,14 +2059,19 @@ export function lastAssistantErrorStop(messages: unknown): string | undefined {
  * - `exhaust` → the retry budget ran out (`auto_retry_end`, `success: false`);
  *   the run is about to settle on an error. `message` may be empty when the
  *   event carries no `finalError` — callers then keep their earlier message.
- * - `stop`    → the run itself ended with `stopReason === "error"` on its last
- *   assistant message (auto-retry disabled, or a non-retryable failure).
+ * - `stop`    → the run itself ended on a provider error
+ *   (`stopReason === "error"` with a non-abort message; auto-retry disabled,
+ *   or a non-retryable failure).
+ * - `aborted` → the run ended on an abort (`stopReason === "aborted"`, or an
+ *   error stop whose message is abort-shaped — the SDK's setup path mislabels
+ *   a host cancellation as `error`). Never provider health.
  * - `none`    → anything else, including a retry that recovered.
  */
 export type ReviewProviderFailure =
   | { kind: "retry"; message: string; retries: number }
   | { kind: "exhaust"; message: string; retries: number }
   | { kind: "stop"; message: string }
+  | { kind: "aborted"; message?: string }
   | { kind: "none" };
 
 /** Structural decode of one provider-failure event. Never throws. */
@@ -1923,6 +2085,8 @@ export function readProviderErrorEvent(
     const message =
       typeof e.errorMessage === "string" ? e.errorMessage.trim() : "";
     if (!message) return { kind: "none" };
+    // A cancelled retry is our own abort, not provider health.
+    if (isAbortStopText(message)) return { kind: "none" };
     return {
       kind: "retry",
       message,
@@ -1932,6 +2096,7 @@ export function readProviderErrorEvent(
   if (type === "auto_retry_end") {
     if (e.success !== false) return { kind: "none" };
     const message = typeof e.finalError === "string" ? e.finalError.trim() : "";
+    if (isAbortStopText(message)) return { kind: "none" };
     return {
       kind: "exhaust",
       message,
@@ -1939,9 +2104,14 @@ export function readProviderErrorEvent(
     };
   }
   if (type === "agent_end") {
-    const message = lastAssistantErrorStop(e.messages);
-    if (message === undefined) return { kind: "none" };
-    return { kind: "stop", message };
+    const stop = classifyAssistantStop(e.messages);
+    if (stop.kind === "aborted") {
+      return stop.message
+        ? { kind: "aborted", message: stop.message }
+        : { kind: "aborted" };
+    }
+    if (stop.kind !== "provider-error") return { kind: "none" };
+    return { kind: "stop", message: stop.message };
   }
   return { kind: "none" };
 }
@@ -2094,18 +2264,25 @@ function providerErrorOps(
     const ops: ReviewTranscriptOp[] = [
       { op: "new", kind: "status", text: "reviewer run ended" },
     ];
-    const failed = lastAssistantErrorStop(e.messages);
-    if (failed) {
+    // An abort is our own cancellation (pass complete / pause / teardown),
+    // never provider health. The SDK's setup path can label it `error` with an
+    // abort-shaped message, so classification cannot rely on `stopReason`.
+    const stop = classifyAssistantStop(e.messages);
+    if (stop.kind === "provider-error") {
       ops.push({
         op: "new",
         kind: "error",
-        text: `reviewer run ended on a provider error: ${truncateErrorText(failed)}`,
+        text: `reviewer run ended on a provider error: ${truncateErrorText(
+          stop.message,
+        )}`,
       });
     }
     return ops;
   }
   if (type === "auto_retry_start") {
     const msg = typeof e.errorMessage === "string" ? e.errorMessage : "";
+    // A cancelled backoff is an abort, not a provider notice.
+    if (isAbortStopText(msg)) return [];
     return [
       {
         op: "new",
@@ -2122,6 +2299,7 @@ function providerErrorOps(
     // retry recovered; the earlier notice already covers that case.
     if (e.success === false) {
       const detail = truncateErrorText(e.finalError);
+      if (isAbortStopText(detail)) return [];
       return [
         {
           op: "new",