pi-goal-list-loop-audit 0.28.21 → 0.28.22

package/extensions/goal-loop-core.ts

@@ -156,6 +156,16 @@ export interface Goal {
   stopReason?: string;
   pauseReason?: string;
   pauseSuggestedAction?: string;
+  /** v0.28.22: pause classification — drives the widget/status rendering
+   * (a decision pause, an operational failure, a time-gated wait, and a
+   * generic block must not look alike). Undefined = legacy flat card. */
+  pauseKind?: "decision" | "error" | "wait" | "blocked";
+  /** v0.28.22: decision pauses — the options the user picks between. */
+  pauseOptions?: string[];
+  /** v0.28.22: 1-based index into pauseOptions the agent recommends. */
+  pauseRecommended?: number;
+  /** v0.28.22: ISO time a wait-pause becomes resumable (countdown shown). */
+  pauseResumeAt?: string;
   /** v0.28.1 (S1/S2): stale-handle interrupt marker. Set INSTEAD of pausing
    * when pi invalidates the extension handle mid-goal — the goal stays
    * active so a fresh session auto-resumes it via the restore gate. Cleared

package/extensions/goal-loop-display.ts

@@ -107,6 +107,18 @@ const paint = (theme: DisplayTheme | undefined, color: DisplayColor, text: strin
 const ERROR_PAUSE = /token limit|stalled|infra|auditor.*fail/i;
 const pauseIsError = (g: Goal): boolean => ERROR_PAUSE.test(g.pauseReason ?? "");
 
+/** v0.28.22: the rendering class of a pause — declared kind wins; legacy
+ * pauses (no kind) fall back to the error-regex so old states still
+ * classify sensibly. */
+type PauseKind = "decision" | "error" | "wait" | "blocked";
+const pauseKind = (g: Goal): PauseKind | undefined => g.pauseKind ?? (pauseIsError(g) ? "error" : undefined);
+
+/** v0.28.22: "06:40 UTC" from an ISO string (wait-pause countdown). */
+const shortClock = (iso: string): string => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? iso.slice(0, 16) : d.toISOString().slice(11, 16) + " UTC";
+};
+
 // ---- status line (one-liner, always-on) ----
 
 export interface AuditDisplayProgress {
@@ -150,6 +162,13 @@ export function buildStatusText(state: State, audit?: AuditDisplayProgress | nul
     return `glla: ${paint(theme, "accent", "auditing…")}${tool}${heldSuffix}`;
   }
   if (g.status === "paused") {
+    // v0.28.22: the status line names the ACTIONABILITY, not the reason —
+    // "decision needed" / "action needed" / "waiting" tell you at a glance
+    // whether the session needs you. Legacy pauses keep the reason dump.
+    const kind = pauseKind(g);
+    if (kind === "decision") return `glla: ${g.policy} ${paint(theme, "accent", "⏸ decision needed")}${heldSuffix}`;
+    if (kind === "error") return `glla: ${g.policy} ${paint(theme, "error", `⏸ action needed — ${truncate(g.pauseReason ?? "", 30)}`)}${heldSuffix}`;
+    if (kind === "wait") return `glla: ${g.policy} ${paint(theme, "dim", `⏳ waiting${g.pauseResumeAt ? ` · resumes ${shortClock(g.pauseResumeAt)}` : ""}`)}${heldSuffix}`;
     const label = `${g.policy} paused ⏸ ${truncate(g.pauseReason ?? "", 40)}`;
     return `glla: ${paint(theme, pauseIsError(g) ? "error" : "warning", label)}${heldSuffix}`;
   }
@@ -274,14 +293,38 @@ function goalLines(g: Goal, state: State, audit: AuditDisplayProgress | null | u
     return lines;
   }
   if (g.status === "paused" && g.pauseReason) {
-    const isErr = pauseIsError(g);
+    const kind = pauseKind(g);
+    const isErr = kind === "error";
     const budget = budgetFor(width, 3, 60);
-    // v0.27.1: wrap reason + suggested action over up to 3 lines each
-    // (see wrap()); before, both were truncated at ~60 chars and the actual
-    // question in a decision-pause never reached the user.
-    wrap(g.pauseReason, budget, 3).forEach((w, i) => {
-      lines.push(`${i === 0 ? "├─" : "│ "} ${paint(theme, isErr ? "error" : "warning", w)}`);
+    // v0.28.22: actionability banner — a decision pause, an operational
+    // failure, and a time-gated wait must not look alike (user report:
+    // "if something actionable is going on it can be hard to tell").
+    if (kind === "decision") lines.push(`├─ ${paint(theme, "accent", "decision needed — your call unblocks this")}`);
+    else if (kind === "error") lines.push(`├─ ${paint(theme, "error", "action needed — this won't fix itself")}`);
+    else if (kind === "wait") lines.push(`├─ ${paint(theme, "dim", "waiting — nothing for you to do")}`);
+    // v0.27.1: wrap reason + suggested action (see wrap()). v0.28.22:
+    // decision/wait reasons cap at 2 lines — the options/countdown below
+    // carry the actionable content; error reasons keep 3.
+    const reasonPaint = isErr ? "error" : kind === "wait" ? "dim" : "warning";
+    wrap(g.pauseReason, budget, kind === "decision" || kind === "wait" ? 2 : 3).forEach((w, i) => {
+      lines.push(`${i === 0 ? "├─" : "│ "} ${paint(theme, reasonPaint, w)}`);
     });
+    // v0.28.22: decision options — one numbered line each (Claude Code /
+    // muselinn-Ask convention), the recommended one accented and flagged.
+    if (kind === "decision" && g.pauseOptions && g.pauseOptions.length > 0) {
+      g.pauseOptions.slice(0, 6).forEach((opt, i) => {
+        const rec = g.pauseRecommended === i + 1;
+        const text = `${i + 1}. ${truncate(opt, budget - 4)}${rec ? " ◂ recommended" : ""}`;
+        lines.push(`│  ${paint(theme, rec ? "accent" : "dim", text)}`);
+      });
+      if (g.pauseOptions.length > 6) lines.push(`│  ${paint(theme, "dim", `… and ${g.pauseOptions.length - 6} more`)}`);
+    }
+    // v0.28.22: wait countdown — when the pause lifts on its own.
+    if (kind === "wait" && g.pauseResumeAt) {
+      const ms = Date.parse(g.pauseResumeAt) - now;
+      const when = Number.isNaN(ms) ? g.pauseResumeAt : ms <= 0 ? "now" : `${shortClock(g.pauseResumeAt)} (in ${fmtElapsed(ms)})`;
+      lines.push(`├─ ${paint(theme, "dim", `resumes ${when} — or /goal resume now`)}`);
+    }
     // v0.27.1: what survives the pause — the first question at a pause is
     // "did I lose the work?". Answer it on the card.
     // v0.27.9: when the goal has no telemetry yet (restored-in-fresh-session
@@ -300,7 +343,9 @@ function goalLines(g: Goal, state: State, audit: AuditDisplayProgress | null | u
     if (g.pauseSuggestedAction) {
       lines.push(`├─ ${paint(theme, "dim", truncate(savedLine, budget))}`);
       const wrapped = wrap(g.pauseSuggestedAction, budget, 3);
-      wrapped.forEach((w, i) => lines.push(`${i === wrapped.length - 1 ? "└─" : "│ "} ${paint(theme, "dim", w)}`));
+      // v0.28.22: for ACTION NEEDED pauses the action is the point — pop it.
+      const actionPaint = kind === "error" ? "warning" : "dim";
+      wrapped.forEach((w, i) => lines.push(`${i === wrapped.length - 1 ? "└─" : "│ "} ${paint(theme, actionPaint, w)}`));
     } else {
       lines.push(`└─ ${paint(theme, "dim", truncate(savedLine, budget))}`);
     }

package/extensions/loops/goal.ts

@@ -498,6 +498,7 @@ function escalateSendRearmStorm(ctx: ExtensionContext, kind: "continuation" | "l
   if (state.goal && state.goal.status === "active") {
     updateGoal({
       status: "paused",
+      pauseKind: "error",
       pauseReason: `send-retry storm: ${mins}m of 50ms re-arms — the session never went idle for the continuation`,
       pauseSuggestedAction: "The session never went idle for the send (wedged queue or permanently busy). Restart pi, then /goal resume.",
     }, ctx);
@@ -521,6 +522,7 @@ function escalateStallNow(ctx: ExtensionContext, threshold: number): boolean {
   if (state.goal && state.goal.status === "active") {
     updateGoal({
       status: "paused",
+      pauseKind: "error",
       pauseReason: `stalled: ${threshold} continuation refires landed no turn`,
       pauseSuggestedAction: "The continuation chain is broken in this process (wedged message queue or stale API). Restart pi, then /goal resume.",
     }, ctx);
@@ -1259,7 +1261,7 @@ async function cmdResume(ctx: ExtensionContext): Promise<void> {
   const usage = state.goal.usage
     ? { tokensUsed: state.goal.usage.tokensUsed, tokensLimit: freshLimit }
     : undefined;
-  updateGoal({ status: "active", pauseReason: undefined, pauseSuggestedAction: undefined, ...(staleEntry ? { interruptedAt: nowIso(), interruptedReason: "resumed in a stale session" } : {}), ...(usage ? { usage } : {}) }, ctx);
+  updateGoal({ status: "active", pauseReason: undefined, pauseSuggestedAction: undefined, pauseKind: undefined, pauseOptions: undefined, pauseRecommended: undefined, pauseResumeAt: undefined, ...(staleEntry ? { interruptedAt: nowIso(), interruptedReason: "resumed in a stale session" } : {}), ...(usage ? { usage } : {}) }, ctx);
   if (staleEntry) return;
   // v0.22.5: say what was resumed — with a non-empty list this also resumes
   // the queue (the active goal IS the list's head item).
@@ -2050,10 +2052,10 @@ async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
   const sub = (parts[0] ?? "").toLowerCase();
   const rest = args.trim().slice(sub.length).trim();
 
-  if (!sub) {
-    // /loop with no args → resume a held loop if one is waiting; otherwise
-    // draft the loop config (metric design is the whole game for a
-    // long-running loop; never start one blind).
+  if (!sub || sub === "resume") {
+    // /loop with no args (or /loop resume, v0.28.22) → resume a held loop
+    // if one is waiting; otherwise draft the loop config (metric design is
+    // the whole game for a long-running loop; never start one blind).
     if (isLoopActive()) {
       ctx.ui.notify("A loop is already active — /loop status to inspect, /loop stop to end it.", "info");
       return;
@@ -2063,7 +2065,7 @@ async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
       // v0.28.14: one-active-thing — a held loop must not resume over an
       // active goal/list-item (this was the last unguarded stacking path).
       if (state.goal && state.goal.status === "active") {
-        ctx.ui.notify("A goal is active — the held loop stays held. /goal pause or /goal cancel it first, then /loop to resume.", "warning");
+        ctx.ui.notify("A goal is active — the held loop stays held. /goal pause or /goal cancel it first, then /loop resume.", "warning");
         return;
       }
       state.loop = { ...stored, active: true, stopReason: undefined };
@@ -2075,6 +2077,10 @@ async function cmdLoop(args: string, ctx: ExtensionContext): Promise<void> {
       );
       return;
     }
+    if (sub === "resume") {
+      ctx.ui.notify("No held loop to resume. /loop to draft one, or /loop start \"<target>\" for an infinite metricless loop.", "info");
+      return;
+    }
     await startDrafting(ctx, "loop");
     return;
   }
@@ -2440,6 +2446,7 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
         updateGoal({
           status: "paused",
           auditHistory: history,
+          pauseKind: "decision",
           pauseReason: `auditor verdict: IMPOSSIBLE — ${reason}`,
           pauseSuggestedAction: "The auditor says this goal can never be satisfied as stated. /goal tweak the objective (or /goal cancel), then /goal resume.",
         }, ctx);
@@ -2472,6 +2479,8 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
             status: "paused",
             auditHistory: history,
             auditInfraStreak: undefined, // quota reached the auditor — infra streak broken
+            pauseKind: "wait",
+            pauseResumeAt: new Date(Date.now() + quota.retryAfterSec * 1000).toISOString(),
             pauseReason: `auditor quota: ${result.error}`,
             pauseSuggestedAction: `Quota auto-retry in ${retryMin}m — or /goal resume to retry now`,
           }, ctx);
@@ -2506,6 +2515,7 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
             status: "paused",
             auditHistory: history,
             auditInfraStreak: infraStreak,
+            pauseKind: "error",
             pauseReason: `auditor infrastructure failed ${infraStreak}× in a row — the auditor model is likely broken (last: ${result.error.slice(0, 120)})`,
             pauseSuggestedAction: "Fix the auditor model (/glla model=provider/id) or restart pi, then /goal resume. Your work was NOT judged.",
           }, ctx);
@@ -2612,6 +2622,7 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
         updateGoal({
           status: "paused",
           auditHistory: history,
+          pauseKind: "decision",
           pauseReason: `auditor disapproved ${trailingDisapprovals}× consecutively (cap ${auditCap})`,
           pauseSuggestedAction: "Read the audit history (/goal status), fix the actual gap or /goal tweak the objective, then /goal resume. Raise the cap with /glla auditcap=N.",
         }, ctx);
@@ -2646,20 +2657,28 @@ function registerAgentTools(pi: any, ctx: ExtensionContext): void {
   pi.registerTool(defineTool({
     name: "pause_goal",
     label: "Pause goal",
-    description: "Pause the active goal with a reason and suggested action. Use when blocked on user input or unable to make progress.",
+    description: "Pause the active goal with a reason and suggested action. Use when blocked on user input or unable to make progress. When the user must CHOOSE between options, pass kind=\"decision\" with the options list (recommended = 1-based index of the best one) — decision pauses render as a prominent DECISION NEEDED card. Time-gated waits (retry at a specific time) use kind=\"wait\" with resumeAt (ISO). Operational failures use kind=\"error\".",
     parameters: Type.Object({
       reason: Type.String({ description: "Why the work is paused" }),
       suggestedAction: Type.Optional(Type.String({ description: "What the user should do next" })),
+      kind: Type.Optional(Type.Union([Type.Literal("decision"), Type.Literal("error"), Type.Literal("wait"), Type.Literal("blocked")], { description: "Pause class: decision (user picks an option), error (operational failure), wait (time-gated), blocked (generic)" })),
+      options: Type.Optional(Type.Array(Type.String(), { description: "For kind=decision: the options the user picks between (one line each)" })),
+      recommended: Type.Optional(Type.Number({ description: "For kind=decision: 1-based index of the recommended option" })),
+      resumeAt: Type.Optional(Type.String({ description: "For kind=wait: ISO time the pause lifts (countdown is shown)" })),
     }),
     async execute(_id, params, _signal, _onUpdate, execCtx) {
       const foreign1 = foreignToolGuard(execCtx);
       if (foreign1) return { content: [{ type: "text", text: foreign1 }], details: {} };
-      const p = params as { reason: string; suggestedAction?: string };
+      const p = params as { reason: string; suggestedAction?: string; kind?: "decision" | "error" | "wait" | "blocked"; options?: string[]; recommended?: number; resumeAt?: string };
       if (!state.goal) return { content: [{ type: "text", text: "No active goal." }], details: {} };
       updateGoal({
         status: "paused",
         pauseReason: p.reason,
         pauseSuggestedAction: p.suggestedAction,
+        pauseKind: p.kind,
+        pauseOptions: p.kind === "decision" && p.options && p.options.length > 0 ? p.options : undefined,
+        pauseRecommended: p.kind === "decision" && p.recommended && p.recommended >= 1 ? Math.floor(p.recommended) : undefined,
+        pauseResumeAt: p.kind === "wait" && p.resumeAt ? p.resumeAt : undefined,
       }, ctx);
       // v0.27.1: surface the FULL pause contract — reason AND suggested
       // action. Before, the action only appeared in /goal status and the
@@ -4462,7 +4481,7 @@ export default function (pi: ExtensionAPI): void {
         state.loop = { ...l, active: false, stopReason: HELD_ON_RESTORE };
         persistState(ctx);
         ctx.ui.notify(
-          `Loop held on restore: ${l.target.slice(0, 60)} — /loop to resume, /glla autoresume=on to auto-resume on session load in this project.`,
+          `Loop held on restore: ${l.target.slice(0, 60)} — /loop resume to continue, /glla autoresume=on to auto-resume on session load in this project.`,
           "info",
         );
       }
@@ -4492,6 +4511,7 @@ export default function (pi: ExtensionAPI): void {
         const resumeHint = `${resumeCmd} to continue${queued > 0 ? ` (+${queued} waiting in the list)` : ""} · /glla autoresume=on to auto-resume in this project`;
         updateGoal({
           status: "paused",
+          pauseKind: "blocked",
           pauseReason: "restored on session load — held for explicit resume",
           pauseSuggestedAction: resumeHint,
         }, ctx);
@@ -4522,6 +4542,7 @@ export default function (pi: ExtensionAPI): void {
     if (state.loop && state.goal && state.goal.status === "active") {
       updateGoal({
         status: "paused",
+        pauseKind: "decision",
         pauseReason: "held on session load — the loop owns the active slot (one active thing at a time)",
         pauseSuggestedAction: "/loop to work the loop, or /loop stop then /goal resume to work the goal",
       }, ctx);
@@ -4617,6 +4638,7 @@ export default function (pi: ExtensionAPI): void {
         if (state.goal) {
           updateGoal({
             status: "paused",
+            pauseKind: "decision",
             pauseReason: `stalled: ${HEARTBEAT_MAX_NUDGES} consecutive unproductive turns (no tools, short or repetitive)`,
             pauseSuggestedAction: "Inspect the goal — /goal resume to retry, /goal tweak to narrow it, /goal cancel to abort.",
           }, ctx);
@@ -4664,6 +4686,7 @@ export default function (pi: ExtensionAPI): void {
         updateGoal({
           usage: { tokensUsed: used, tokensLimit: limit },
           status: "paused",
+          pauseKind: "error",
           pauseReason: `token limit exceeded (${used.toLocaleString()} > ${limit.toLocaleString()})`,
           pauseSuggestedAction: "/glla tokenlimit=<n> to raise the cap (or 0 to disable), then /goal resume",
         }, ctx);
@@ -4687,6 +4710,8 @@ export default function (pi: ExtensionAPI): void {
         const reason = `5 consecutive errors${detail}`;
         updateGoal({
           status: "paused",
+          pauseKind: "wait",
+          pauseResumeAt: new Date(Date.now() + 60_000).toISOString(),
           pauseReason: reason,
           pauseSuggestedAction: "Transient provider flake? The goal auto-resumes once in 60s if still paused for this reason — or /goal resume now.",
         }, ctx);
@@ -4714,6 +4739,7 @@ export default function (pi: ExtensionAPI): void {
       if (consecutiveAbortIterations >= 5) {
         updateGoal({
           status: "paused",
+          pauseKind: "blocked",
           pauseReason: "5 consecutive aborts (user interrupted)",
           pauseSuggestedAction: "You interrupted 5 turns in a row — the goal stays paused until you /goal resume (or /goal cancel).",
         }, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-goal-list-loop-audit",
-  "version": "0.28.21",
+  "version": "0.28.22",
   "description": "Goal. Loop. Audit. Done. \u2014 a pi-coding-agent extension that supervises long-running work, with isolated auditor on each completion. Beat bamboozling by design: the auditor runs in a fresh session with no extensions, no skills, no editor \u2014 only the read tools needed to verify your goal.",
   "license": "MIT",
   "author": "dracon",

package/schemas/goal.schema.json

@@ -46,6 +46,10 @@
     "stopReason": { "type": "string" },
     "pauseReason": { "type": "string" },
     "pauseSuggestedAction": { "type": "string" },
+    "pauseKind": { "type": "string", "enum": ["decision", "error", "wait", "blocked"] },
+    "pauseOptions": { "type": "array", "items": { "type": "string" } },
+    "pauseRecommended": { "type": "number" },
+    "pauseResumeAt": { "type": "string" },
     "interruptedAt": { "type": "string" },
     "interruptedReason": { "type": "string" },
     "auditInfraStreak": { "type": "number" },