pi-better-harness 0.27.2 → 0.28.1

package/README.md

@@ -68,11 +68,12 @@ The bundled harness provides **Tool output: Normal / Minimal** in
 `/harness-settings`. `/tool-output minimal`, `/tool-output normal`, and
 `/tool-output` (toggle) remain compatibility shortcuts to the same preference.
 Minimal mode folds each tool call into a single-line header, including running
-calls. Each row has a single tool-specific icon: accent-colored while running,
-muted when completed, and error-colored when failed. Tool names stay muted;
-inline command/path arguments use the theme's distinct dim tone. Running and
-failed calls retain text labels so state never depends on color alone. Activity
-stays quieter than conversation text. Tool rows are indented two columns past
+calls. The tool-specific icon and tool name share a state color: accent while
+running, muted when completed, and error-colored when failed. In fullscreen Pi, a soft highlight travels through visible running names; inline
+command/path arguments stay dim. Scrollback terminals keep static state colors.
+Choose **Tool animation: Off** in `/harness-settings` for static running headers.
+Running and failed calls retain text labels so state never depends on color or
+motion alone. Tool rows are indented two columns past
 the assistant text padding. Long
 headers are truncated to the terminal width; result bodies,
 images, boxes, and tool spacers are hidden. Built-in, extension, and MCP calls
@@ -130,8 +131,10 @@ to the `/agents` catalog. `/sandbox`, `/subagents settings`, `/agents`, and
 `/goal settings` remain available in standalone installations.
 Packages without a settings screen are not listed. Pi's `/settings` is unchanged.
 
-The hub includes **Tool output** when the bundled renderer extension is loaded.
-Changes apply immediately and also save the default for future sessions.
+The hub includes **Tool output** and **Tool animation** when the bundled renderer
+extension is loaded. Changes apply immediately and save the default for future
+sessions. The animation preference is stored in `piBetterHarness.toolAnimation`;
+normal output and expanded tool details are never animated.
 The hub also owns **Completions while busy**, shared by Subagents and Background
 Tasks. Choose **Wait until idle** (the default) or **Steer active run**. Changes
 apply immediately and autosave to the current session branch, including across

package/extensions/minimal-output/hook.ts

@@ -5,8 +5,10 @@ import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { stripVTControlCharacters } from "node:util";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { supportsToolShimmer, toolIdentity } from "./tool-identity.ts";
+import { toolVisibility, type ViewportUI } from "./tool-visibility.ts";
 
-interface ToolUI {
+interface ToolUI extends ViewportUI {
   requestRender(): void;
   children?: TranscriptComponent[];
   handleViewportInput?(data: string): unknown;
@@ -70,6 +72,8 @@ interface ToolPrototype {
 }
 interface HookState {
   enabled: boolean;
+  animationEnabled: boolean;
+  stopAnimation(): void;
   owners: number;
   redraw(collapse?: boolean): void;
   restore(): void;
@@ -79,6 +83,7 @@ interface HookState {
 }
 export interface MinimalOutputHook {
   setEnabled(enabled: boolean): void;
+  setAnimationEnabled(enabled: boolean): void;
   completeRun(): void;
   restoreCompletedCalls(ids: Iterable<string>): void;
   dispose(): void;
@@ -146,7 +151,7 @@ function harnessCallDetail(name: string, input: unknown): string | undefined {
   }
 }
 
-function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3): string[] {
+function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3, animationTime?: number): string[] {
   if (width <= 0) return [];
   // Render the call alone at a wider width so terminal wrapping becomes truncation.
   const header = Boolean(component.getCallRenderer?.()) && component.callRendererComponent?.render(Math.max(4096, width + 1))
@@ -170,7 +175,7 @@ function compactCall(component: ToolComponent, width: number, theme?: Theme, ind
   const icon = TOOL_ICONS[component.toolName] ?? "\u25c7";
   const title = ` ${icon} ${label}`;
   const styled = theme
-    ? ` ${theme.fg(failed ? "error" : running ? "accent" : "muted", icon)} ${theme.fg("muted", label)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
+    ? ` ${toolIdentity(icon, label, failed ? "error" : running ? "accent" : "muted", theme, animationTime)}${detail ? `  ${theme.fg("dim", detail)}` : ""}${theme.fg(failed ? "error" : "dim", suffix)}`
     : `${title}${detail ? `  ${detail}` : ""}${suffix}`;
   return [truncateToWidth(`${" ".repeat(Math.min(indent, Math.max(0, width - 1)))}${styled}`, width)];
 }
@@ -304,6 +309,50 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     };
     const seen = new WeakSet<ToolComponent>();
     const components = new Set<WeakRef<ToolComponent>>();
+    const animationReferences = new WeakMap<ToolComponent, WeakRef<ToolComponent>>();
+    const animated = new Map<WeakRef<ToolComponent>, number>();
+    const settled = new WeakSet<ToolComponent>();
+    let animationTimer: ReturnType<typeof setInterval> | undefined;
+    const stopAnimation = () => {
+      if (animationTimer !== undefined) clearInterval(animationTimer);
+      animationTimer = undefined;
+      animated.clear();
+    };
+    const canAnimate = (component: ToolComponent) => {
+      const theme = getTheme?.();
+      return state!.enabled && state!.animationEnabled && component.ui.mode === "fullscreen"
+        && !!theme && supportsToolShimmer(theme)
+        && !component.expanded && !component.result?.isError && (!component.result || component.isPartial)
+        && !settled.has(component);
+    };
+    const pruneAnimation = () => {
+      for (const [reference, lastRender] of animated) {
+        const component = reference.deref();
+        if (!component || !canAnimate(component) || Date.now() - lastRender > 400
+          || toolVisibility(component.ui, component) !== true) animated.delete(reference);
+      }
+      if (!animated.size) stopAnimation();
+    };
+    const animationTime = (component: ToolComponent, width: number, indent: number) => {
+      if (width <= indent + 3 || !canAnimate(component) || toolVisibility(component.ui, component) === false) return undefined;
+      let reference = animationReferences.get(component);
+      if (!reference) { reference = new WeakRef(component); animationReferences.set(component, reference); }
+      animated.set(reference, Date.now());
+      if (animationTimer === undefined) {
+        animationTimer = setInterval(() => {
+          pruneAnimation();
+          const uis = new Set<ToolUI>();
+          for (const reference of animated.keys()) {
+            const component = reference.deref();
+            if (!component) continue;
+            uis.add(component.ui);
+          }
+          for (const ui of uis) ui.requestRender();
+        }, 80);
+        animationTimer.unref?.();
+      }
+      return toolVisibility(component.ui, component) === true ? Date.now() : undefined;
+    };
     let completed = new Map<string, object>();
     let groups = new WeakMap<ToolComponent, ToolGroup>();
     let layouts = new WeakMap<ToolComponent, { parent: TranscriptComponent; anchor?: TranscriptComponent }>();
@@ -344,11 +393,15 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
     };
     state = {
       enabled: false,
+      animationEnabled: true,
+      stopAnimation,
       owners: 0,
       completeRun() {
+        stopAnimation();
         const run = {};
         for (const reference of components) {
           const component = reference.deref();
+          if (component) settled.add(component);
           if (component?.result && !component.isPartial && !completed.has(component.toolCallId)) {
             completed.set(component.toolCallId, run);
             if (this.enabled) component.setExpanded(false);
@@ -357,6 +410,11 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         this.redraw();
       },
       restoreCompletedCalls(ids) {
+        stopAnimation();
+        for (const reference of components) {
+          const component = reference.deref();
+          if (component) settled.add(component);
+        }
         const history = {};
         completed = new Map(Array.from(ids, id => [id, history]));
         groups = new WeakMap();
@@ -372,8 +430,10 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
           else component.invalidate();
           component.ui.requestRender();
         }
+        pruneAnimation();
       },
       restore() {
+        stopAnimation();
         clearHover();
         for (const [ui, { original, wrapper }] of inputWrappers) {
           if (ui.handleViewportInput === wrapper) ui.handleViewportInput = original;
@@ -498,6 +558,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
           this.ui.handleViewportInput = wrapper;
         }
         if (!seen.has(this)) { seen.add(this); components.add(new WeakRef(this)); }
+        pruneAnimation();
         if (!current.enabled || this.expanded) return originals.updateDisplay.apply(this, args);
         const showImages = this.showImages;
         const lastRenderer = this.resultRendererComponent;
@@ -517,6 +578,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         if (args[0] === false && !mouseHandling && group) group.open = false;
         const result = originals.setExpanded.apply(this, args);
         if (group) group.expanded += Number(this.expanded) - Number(wasExpanded);
+        pruneAnimation();
         return result;
       },
       getResultRenderer(this: ToolComponent, ...args: unknown[]) {
@@ -531,7 +593,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
         const padding = layout?.anchor?.outputPad ?? 1;
         const indent = Number.isFinite(padding) ? Math.max(0, Math.floor(padding)) + 2 : 3;
         const group = groupFor(this, layout?.parent);
-        if (!group) return highlight(this, compactCall(this, width, getTheme?.(), indent), width);
+        if (!group) return highlight(this, compactCall(this, width, getTheme?.(), indent, animationTime(this, width, indent)), width);
         const open = group.open || group.expanded > 0;
         const first = group.members[0] === this;
         const lines: string[] = [];
@@ -591,6 +653,12 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
       current.enabled = enabled;
       current.redraw(enabled);
     },
+    setAnimationEnabled(enabled) {
+      if (disposed) return;
+      current.animationEnabled = enabled;
+      if (!enabled) current.stopAnimation();
+      current.redraw();
+    },
     dispose() {
       if (disposed) return;
       disposed = true;

package/extensions/minimal-output/index.ts

@@ -10,6 +10,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   let enabled = false;
   let running = false;
   let initialDefault: boolean | undefined;
+  let motionEnabled = true;
 
   function defaultEnabled(): boolean {
     if (initialDefault !== undefined) return initialDefault;
@@ -52,6 +53,16 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
       enabled = false;
       ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
     }
+    try {
+      const motion = readHarnessSetting<{ version?: unknown; enabled?: unknown }>("toolAnimation");
+      if (motion !== undefined && (motion?.version !== 1 || typeof motion.enabled !== "boolean")) {
+        throw new Error("Invalid tool-animation default in global settings.json.");
+      }
+      motionEnabled = motion?.enabled !== false;
+    } catch (error) {
+      motionEnabled = false;
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom" && entry.customType === ENTRY) {
         const data = entry.data as { version?: unknown; enabled?: unknown } | undefined;
@@ -60,6 +71,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
     // Observe transcript components from startup, so the toggle also redraws existing rows.
     if (await ensureHook(ctx)) {
+      hook!.setAnimationEnabled(motionEnabled);
       hook!.restoreCompletedCalls(ctx.sessionManager.getBranch().flatMap(entry =>
         entry.type === "message" && entry.message.role === "toolResult" ? [entry.message.toolCallId] : []));
       if (enabled) collapseTools(ctx);
@@ -93,7 +105,21 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     id: "tool-output", label: "Tool output", values: ["Normal", "Minimal"],
     get: () => enabled ? "Minimal" : "Normal", change,
   };
-  const register = () => pi.events.emit("harness-settings:register", setting);
+  const animationSetting: SettingsControl = {
+    id: "tool-animation", label: "Tool animation", values: ["Shimmer", "Off"],
+    get: () => motionEnabled ? "Shimmer" : "Off",
+    async change(value, ctx) {
+      if (value !== "Shimmer" && value !== "Off") throw new Error("Invalid tool animation mode.");
+      if (!await ensureHook(ctx)) throw new Error("Tool animation settings are unavailable in this Pi runtime.");
+      updateHarnessSetting("toolAnimation", () => ({ version: 1, enabled: value === "Shimmer" }));
+      motionEnabled = value === "Shimmer";
+      hook!.setAnimationEnabled(motionEnabled);
+    },
+  };
+  const register = () => {
+    pi.events.emit("harness-settings:register", setting);
+    pi.events.emit("harness-settings:register", animationSetting);
+  };
   let stopSettings: (() => void) | undefined;
   const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
   subscribe();
@@ -115,6 +141,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     enabled = false;
     running = false;
     initialDefault = undefined;
+    motionEnabled = true;
   });
 
   pi.registerCommand("tool-output", {

package/extensions/minimal-output/tool-identity.ts

@@ -0,0 +1,66 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+type RGB = [number, number, number];
+interface ConcreteColor { kind: string; index?: number; r?: number; g?: number; b?: number }
+const concreteColors = (theme: Theme) => (theme as Theme & { colors?: Record<string, ConcreteColor> }).colors;
+const PERIOD = 2400;
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+function themeRgb(theme: Theme, token: "accent" | "text"): RGB | undefined {
+  const color = concreteColors(theme)?.[token];
+  if (color?.kind === "rgb" && color.r !== undefined && color.g !== undefined && color.b !== undefined) {
+    return [color.r, color.g, color.b];
+  }
+  return rgb(theme.getFgAnsi(token));
+}
+
+export function supportsToolShimmer(theme: Theme): boolean {
+  const base = themeRgb(theme, "accent");
+  const light = themeRgb(theme, "text");
+  const accent = concreteColors(theme)?.accent;
+  return (!!base && !!light && base.some((value, index) => value !== light[index]))
+    || (accent?.kind === "indexed" && accent.index !== undefined && accent.index >= 0 && accent.index < 16);
+}
+
+function rgb(ansi: string): RGB | undefined {
+  const direct = /\x1b\[38;2;(\d+);(\d+);(\d+)m/.exec(ansi);
+  if (direct) return [Number(direct[1]), Number(direct[2]), Number(direct[3])];
+  const indexed = /\x1b\[38;5;(\d+)m/.exec(ansi);
+  if (!indexed) return undefined;
+  const index = Number(indexed[1]);
+  // The first 16 colors are terminal-defined; keep them untouched rather than guess.
+  if (index < 16 || index > 255) return undefined;
+  if (index >= 232) { const gray = 8 + (index - 232) * 10; return [gray, gray, gray]; }
+  const cube = index - 16;
+  const channel = (value: number) => value === 0 ? 0 : 55 + value * 40;
+  return [channel(Math.floor(cube / 36)), channel(Math.floor(cube / 6) % 6), channel(cube % 6)];
+}
+
+function foreground(color: RGB, mode: "truecolor" | "256color"): string {
+  if (mode === "truecolor") return `\x1b[38;2;${color.join(";")}m`;
+  const channel = (value: number) => Math.max(0, Math.min(5, Math.round((value - 55) / 40)));
+  const index = 16 + channel(color[0]) * 36 + channel(color[1]) * 6 + channel(color[2]);
+  return `\x1b[38;5;${index}m`;
+}
+
+export function toolIdentity(icon: string, label: string, tone: "accent" | "muted" | "error", theme: Theme, time?: number): string {
+  if (tone !== "accent" || time === undefined) return theme.fg(tone, `${icon} ${label}`);
+  const base = themeRgb(theme, "accent");
+  const light = themeRgb(theme, "text");
+  if (!supportsToolShimmer(theme)) return theme.fg(tone, `${icon} ${label}`);
+  const letters = Array.from(graphemes.segment(label), part => part.segment);
+  const radius = Math.max(2, Math.min(4, letters.length / 3));
+  const position = (time % PERIOD) / PERIOD * (letters.length + radius * 2) - radius;
+  const mode = theme.getColorMode();
+  const name = letters.map((letter, index) => {
+    const distance = Math.abs(index - position) / radius;
+    const shine = distance < 1 ? (1 + Math.cos(distance * Math.PI)) * 0.48 : 0;
+    if (!base || !light) {
+      const intensity = shine > 0.72 ? "\x1b[1m" : shine > 0.18 ? "" : "\x1b[2m";
+      return `\x1b[22m${intensity}${letter}`;
+    }
+    const color = base.map((value, channel) => Math.round(value + (light[channel] - value) * shine)) as RGB;
+    return `${foreground(color, mode)}${letter}`;
+  }).join("");
+  return theme.fg(tone, `${icon} \x1b[22m${name}\x1b[22m`);
+}

package/extensions/minimal-output/tool-visibility.ts

@@ -0,0 +1,61 @@
+interface Rect { x: number; y: number; width: number; height: number }
+interface LegacyComponent {
+  mouseLayout?: { children: { component: LegacyComponent; height: number }[] };
+  paddingX?: number;
+  paddingY?: number;
+}
+interface LayoutBox {
+  component: LegacyComponent;
+  rect: Rect;
+  clip: Rect;
+  children: LayoutBox[];
+  lineOffset?: number;
+}
+export interface ViewportUI { mode?: string; currentLayout?: { root: LayoutBox }; hasOverlay?(): boolean; hasActiveSelection?(): boolean }
+const frames = new WeakMap<ViewportUI, { root: LayoutBox; known: Set<object>; visible: Set<object> }>();
+
+function intersects(a: Rect, b: Rect): boolean {
+  return a.width > 0 && a.height > 0 && b.width > 0 && b.height > 0
+    && a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+
+// The guarded fullscreen adapter uses the last painted layout, never calls render()
+// to measure visibility, and leaves scrollback hosts on static state colors.
+export function toolVisibility(ui: ViewportUI, component: object): boolean | undefined {
+  if (ui.mode !== "fullscreen" || ui.hasOverlay?.() || ui.hasActiveSelection?.()) return false;
+  const root = ui.currentLayout?.root;
+  if (!root) return undefined;
+  if (!root.rect || !root.clip || !Array.isArray(root.children)) return false;
+  let frame = frames.get(ui);
+  if (frame?.root !== root) {
+    frame = { root, known: new Set(), visible: new Set() };
+    const current = frame;
+    const legacy = (child: LegacyComponent, rect: Rect, clip: Rect) => {
+      if (!child || typeof child !== "object") return;
+      current.known.add(child);
+      if (!intersects(rect, clip)) return;
+      current.visible.add(child);
+      const children = child.mouseLayout?.children;
+      if (!children) return;
+      const paddingY = child.paddingY ?? 0;
+      const paddingX = child.paddingX ?? 0;
+      if (children.reduce((height, entry) => height + entry.height, 0) + paddingY * 2 !== rect.height) return;
+      let y = rect.y + paddingY;
+      for (const entry of children) {
+        legacy(entry.component, { x: rect.x + paddingX, y, width: Math.max(0, rect.width - paddingX * 2), height: entry.height }, clip);
+        y += entry.height;
+      }
+    };
+    const visit = (box: LayoutBox) => {
+      if (!box?.component || !box.rect || !box.clip || !Array.isArray(box.children)) return;
+      current.known.add(box.component);
+      if (!intersects(box.rect, box.clip)) return;
+      current.visible.add(box.component);
+      if (box.children.length) for (const child of box.children) visit(child);
+      else legacy(box.component, { ...box.rect, y: box.rect.y - (box.lineOffset ?? 0) }, box.clip);
+    };
+    visit(root);
+    frames.set(ui, frame);
+  }
+  return frame.known.has(component) ? frame.visible.has(component) : undefined;
+}

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

@@ -18,7 +18,7 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.
-- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (60s through 600s by default), followed by a hold recoverable with `/goal resume`. Delays saturate at Node's timer limit, and observed background drains reset progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
+- A progress-aware follow-up loop with ten identical no-progress retries and linear backoff (60s through 600s by default), followed by a sticky hold recoverable with `/goal resume` or `alt+g`. Conversation, changed callback results, and background drains do not reopen an exhausted hold. Delays saturate at Node's timer limit, and observed background drains reset non-held progress before callback turns can cancel the wake. Pi's network retry policy remains independent.
 - An observable-progress stall state for active goals.
 
 ## Settings Storage
@@ -44,7 +44,7 @@ metadata:
   workflow-role: coordinator
 ```
 
-Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit (or use `/workflow clear` to release it manually). Completing an active goal also releases ownership.
+Invoke the skill with Pi's `/skill:name` command, or supervise it with `/goal /skill:name task`. The goal extension resolves the command against Pi's registry, persists its source, and expands the skill on kickoff and continuation (including after session resume). A bound command that disappears or changes source pauses the goal. `/goal /template task` also re-expands prompt templates on continuation; `/goal /extension-command task` dispatches the extension command once, then continues with ordinary goal supervision to avoid repeating side effects. Plain-language goals work as before. This command binding requires Pi 0.84.4 or later. Legacy slash-shaped goals without a binding pause on resume rather than running without the skill. `/workflow` shows a coordinator skill owner; call `release_workflow` after the workflow's completion audit, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator, preserving its objective and incomplete status. Reinvoke the skill explicitly before `/goal resume`; automatic continuation cannot reacquire ownership. Unrelated ordinary Goals are unchanged. Completing an active goal also releases ownership.
 
 A skill that is only an alias of a coordinator declares the target instead of a role:
 

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

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

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

@@ -257,6 +257,7 @@ function formatGoal(
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
     settings,
+    ...(continuation?.blocked && goal.status === "active" ? ["Resume: /goal resume or alt+g"] : []),
     ...(goal.status === "paused"
       ? [agentResumable(goal, preferences.conversationalResume)
         ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
@@ -432,10 +433,11 @@ export default function (pi: ExtensionAPI): void {
     if (!isPokeable(goal)) {
       return;
     }
-    setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
+    const held = currentContinuationState(ctx, goal.goalId)?.blocked === true;
+    setGoal(goalWithStatus(goal, "paused", undefined, held ? undefined : "interrupt"), ctx, "runtime");
     notifyGoal(ctx, currentPermissionHold(ctx, goal.goalId).blockers.length > 0
       ? "Goal remains permission-held. Use /goal resume or alt+g for one same-scope retry."
-      : preferences.conversationalResume
+      : preferences.conversationalResume && !held
       ? 'Goal paused. Say "go" to resume it, or use /goal resume.'
       : "Goal paused. Use /goal resume or alt+g to resume it.");
   };
@@ -446,13 +448,20 @@ export default function (pi: ExtensionAPI): void {
     escapeAbortSuppression.execution === executionGeneration;
 
   /** Why a paused goal cannot become active again, or null when it can. */
-  const resumeBlocker = (goal: GoalSnapshot): string | null => {
+  const resumeBlocker = (goal: GoalSnapshot, ctx: ExtensionContext): string | null => {
     if (!goal.command && skillCommandName(goal.objective)) {
       return "Invoke the skill directly; this legacy slash-command goal cannot resume as plain text.";
     }
     if (goal.command && !commandAvailable(pi, goal.command)) {
       return `Cannot resume: /${goal.command.name} is no longer registered at its original source.`;
     }
+    if (goal.command?.source === "skill") {
+      const owner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
+      const activeOwner = getWorkflow(ctx);
+      if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) {
+        return `Reinvoke /${goal.command.name} before resuming its workflow goal.`;
+      }
+    }
     return null;
   };
 
@@ -469,7 +478,10 @@ export default function (pi: ExtensionAPI): void {
     if (!current || (current.status !== "paused" && !held)) {
       return { ok: false, message: "Only paused or no-progress-held goals can be resumed." };
     }
-    const blocker = resumeBlocker(current);
+    if (source === "tool" && currentContinuationState(ctx, current.goalId)?.blocked) {
+      return { ok: false, message: "Only /goal resume or alt+g can reopen a no-progress hold." };
+    }
+    const blocker = resumeBlocker(current, ctx);
     if (blocker) {
       return { ok: false, message: blocker };
     }
@@ -544,7 +556,7 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     if (currentPermissionHold(ctx, goal.goalId).blockers.length > 0) return;
-    if (kind === "continuation" && currentContinuationState(ctx, goal.goalId)?.blocked) {
+    if (currentContinuationState(ctx, goal.goalId)?.blocked) {
       return;
     }
     const signature = `${goal.goalId}:${kind}`;
@@ -575,6 +587,7 @@ export default function (pi: ExtensionAPI): void {
       const current = currentGoalSnapshot(ctx);
       return isPokeable(current) && current.goalId === goalId &&
         currentPermissionHold(ctx, goalId).blockers.length === 0 &&
+        !currentContinuationState(ctx, goalId)?.blocked &&
         continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
     };
     const goal = currentGoalSnapshot(ctx);
@@ -637,7 +650,8 @@ export default function (pi: ExtensionAPI): void {
     const goal = currentGoalSnapshot(ctx);
     const wakePlan = planBackgroundDrainWake(backgroundDrainTracker, goal, snapshot);
     backgroundDrainTracker = wakePlan.nextTracker;
-    if (isPokeable(goal) && wakePlan.wakeSignature && currentPermissionHold(ctx, goal.goalId).blockers.length === 0) {
+    if (isPokeable(goal) && wakePlan.wakeSignature && currentPermissionHold(ctx, goal.goalId).blockers.length === 0 &&
+        !currentContinuationState(ctx, goal.goalId)?.blocked) {
       // Persist external progress now: a foreground/callback turn may cancel its delayed wake.
       clearIdleContinuation();
       resetContinuationState(goal);
@@ -1101,13 +1115,25 @@ export default function (pi: ExtensionAPI): void {
   pi.registerTool({
     name: "release_workflow",
     label: "Release Workflow",
-    description: "Release the active skill-owned workflow after its final handoff and completion audit.",
+    description: "Release the active skill-owned workflow after its final handoff and completion audit. Its bound active Goal pauses; explicitly reinvoke the skill before resuming that Goal.",
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const owner = getWorkflow(ctx);
       if (!owner) return { content: [{ type: "text", text: "No workflow owns this session." }], details: { released: false } };
+      const goal = getGoal(ctx);
+      let resumeCommand: string | undefined;
+      if (goal?.status === "active" && goal.command?.source === "skill") {
+        const boundOwner = workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath);
+        if (boundOwner?.name === owner.name && boundOwner.path === owner.path) {
+          setGoal(goalWithStatus(goal, "paused"), ctx, "tool");
+          resumeCommand = goal.command.name;
+        }
+      }
       recordWorkflow(null);
-      return { content: [{ type: "text", text: `Released ${owner.name} workflow ownership.` }], details: { released: true, owner: owner.name } };
+      return {
+        content: [{ type: "text", text: `Released ${owner.name} workflow ownership.${resumeCommand ? ` Its Goal is paused, not complete. Reinvoke /${resumeCommand} before /goal resume.` : ""}` }],
+        details: { released: true, owner: owner.name, goalPaused: resumeCommand !== undefined },
+      };
     },
   });
 
@@ -1211,7 +1237,8 @@ export default function (pi: ExtensionAPI): void {
     // A paused goal stays paused while the user talks: the message is ordinary
     // conversation. Only /goal resume, the hotkey, or goal_resume resume it.
     const goal = getGoal(ctx);
-    if (goal?.status === "active" && currentPermissionHold(ctx, goal.goalId).blockers.length === 0) {
+    if (goal?.status === "active" && currentPermissionHold(ctx, goal.goalId).blockers.length === 0 &&
+        !currentContinuationState(ctx, goal.goalId)?.blocked) {
       executionGeneration += 1;
       clearIdleContinuation();
       lastAgentEvidence = null;
@@ -1243,6 +1270,9 @@ export default function (pi: ExtensionAPI): void {
     const questionInstruction = snapshot.backgroundRunning
       ? " A blocking user question (ask_user_question) holds this whole turn until the user answers, and background completions wait behind it. Harvest finished background results before asking, and ask only when the answer is needed to proceed."
       : "";
+    const heldInstruction = goal?.status === "active" && currentContinuationState(ctx, goal.goalId)?.blocked
+      ? "Automatic Goal continuation is held for no progress. Answer the current user message or inspect delivered background results without restarting autonomous Goal work. Only /goal resume or alt+g reopens this hold."
+      : "";
 
     if (owner) {
       if (!workflowAvailable(owner)) {
@@ -1266,7 +1296,8 @@ export default function (pi: ExtensionAPI): void {
             : "") +
           `Active workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
           (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
-          (questionInstruction ? `\n\n${questionInstruction.trim()}` : ""),
+          (questionInstruction ? `\n\n${questionInstruction.trim()}` : "") +
+          (heldInstruction ? `\n\n${heldInstruction}` : ""),
       };
     }
 
@@ -1277,7 +1308,7 @@ export default function (pi: ExtensionAPI): void {
     return {
       systemPrompt:
         `${event.systemPrompt}\n\n` +
-        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}${questionInstruction}` +
+        `Pi Better Goal active objective: ${goal.objective}. ${heldInstruction || "Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit."}${backgroundInstruction}${questionInstruction}` +
         (permissionPrompt ? `\n\n${permissionPrompt}` : ""),
     };
   });
@@ -1408,6 +1439,7 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     const previous = currentContinuationState(ctx, goal.goalId) ?? createContinuationState(goal.goalId);
+    if (previous.blocked) return;
     const repeated = previous.lastEvidenceSignature === evidence.signature;
     const noProgressRetries = repeated ? previous.noProgressRetries + 1 : 0;
     const blocked = repeated && noProgressRetries >= MAX_NO_PROGRESS_RETRIES;
@@ -1428,7 +1460,7 @@ export default function (pi: ExtensionAPI): void {
       if (ctx.hasUI) {
         ctx.ui.setStatus(EXTENSION_NAME, "waiting: no progress");
         ctx.ui.notify(
-          `Goal automatic continuation is waiting after ${noProgressRetries} identical retries (${evidence.summary}). New input or background activity will resume it.`,
+          `Goal automatic continuation is waiting after ${noProgressRetries} identical retries (${evidence.summary}). Use /goal resume or alt+g to resume it.`,
           "warning",
         );
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.27.2",
+  "version": "0.28.1",
   "description": "Pi extension bundle for a write sandbox, subagents, background tasks, SSH, goals, and structured plans.",
   "license": "MIT",
   "type": "module",
@@ -54,7 +54,7 @@
   },
   "dependencies": {
     "pi-better-background-tasks": "0.8.0",
-    "pi-better-goal": "0.8.2",
+    "pi-better-goal": "0.8.3",
     "pi-better-plan": "0.8.0",
     "pi-better-sandbox": "0.12.0",
     "pi-better-ssh": "0.1.2",