pi-better-harness 0.28.0 → 0.28.2

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. When the workflow is done, complete the goal (`update_goal`), which also releases ownership. When it hands back unfinished work, call `release_workflow`, or use `/workflow clear` to release ownership manually. `release_workflow` also pauses an active Goal bound to that coordinator as a handback, preserving its objective and incomplete status. Resuming that Goal (`/goal resume`, `alt+g`, or, with conversational resume on, the user's go-ahead such as "continue") rebinds the coordinator it was created with, provided the skill is still registered at its original source; automatic continuation and synthetic input never reacquire ownership. Unrelated ordinary Goals are unchanged.
 
 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.4",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

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

@@ -66,7 +66,7 @@ function isGoalStatus(value: unknown): value is GoalStatus {
 }
 
 function isPauseReason(value: unknown): value is GoalPauseReason {
-  return value === "interrupt" || value === "permission-blocker";
+  return value === "interrupt" || value === "permission-blocker" || value === "handback";
 }
 
 function isGoalLike(value: unknown): value is GoalLike {

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

@@ -87,7 +87,8 @@ const GOAL_RESUME_RULE =
 
 /** True when the agent may resume this goal with `goal_resume`. */
 export function agentResumable(goal: GoalSnapshot | null, conversationalResume = true): boolean {
-  return conversationalResume && goal?.status === "paused" && goal.pauseReason === "interrupt";
+  return conversationalResume && goal?.status === "paused" &&
+    (goal.pauseReason === "interrupt" || goal.pauseReason === "handback");
 }
 
 /** Footer status for a paused goal, telling the user how to resume it. */
@@ -98,7 +99,9 @@ export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true
 
 function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): string {
   return [
-    `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
+    goal.pauseReason === "handback"
+      ? `Pi Better Goal is paused because its workflow handed back unfinished work for the user's answer. Goal: ${goal.objective}`
+      : `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
     "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
     conversationalResume ? GOAL_RESUME_RULE : "Only the user can resume this goal, with /goal resume or alt+g. A conversational go-ahead does not resume it.",
   ].join("\n");
@@ -257,6 +260,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 +436,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,16 +451,29 @@ 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") {
+      try {
+        goalWorkflowOwner(goal);
+      } catch (error) {
+        return `Cannot resume: ${error instanceof Error ? error.message : String(error)} Reinvoke /${goal.command.name}.`;
+      }
+    }
     return null;
   };
 
+  /** The workflow a skill-bound goal owns, re-resolved from its registered skill; null for other goals. */
+  const goalWorkflowOwner = (goal: GoalSnapshot): ReturnType<typeof currentWorkflowOwner> =>
+    goal.command?.source === "skill"
+      ? workflowOwnerFromSkill(goal.command.name.slice("skill:".length), goal.command.path, registeredSkillPath)
+      : null;
+
   /**
    * The one resume path shared by `/goal resume`, the hotkey, and `goal_resume`:
    * reactivate a paused goal or reopen an active no-progress hold.
@@ -469,7 +487,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 };
     }
@@ -486,6 +507,11 @@ export default function (pi: ExtensionAPI): void {
       }
       pi.appendEntry(EXTENSION_NAME, permissionRecord(current.goalId, "permission-release"));
     }
+    // Resuming a skill-bound goal is explicit re-entry into its workflow: rebind the owner the
+    // goal was created with (released by a handback) before the continuation runs.
+    const owner = goalWorkflowOwner(current);
+    const activeOwner = getWorkflow(ctx);
+    if (owner && (activeOwner?.name !== owner.name || activeOwner.path !== owner.path)) recordWorkflow(owner);
     setGoal(goal, ctx, source);
     queueGoalContinuation(goal, ctx);
     return { ok: true, goal };
@@ -544,7 +570,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 +601,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 +664,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);
@@ -1035,8 +1063,8 @@ export default function (pi: ExtensionAPI): void {
     name: GOAL_RESUME_TOOL,
     label: "Resume Goal",
     description:
-      "Resume the goal the user paused with escape, exactly like /goal resume. " + GOAL_RESUME_RULE,
-    promptSnippet: "Resume the escape-paused goal, only on the user's clear go-ahead.",
+      "Resume the goal the user paused with escape, or one its workflow handed back, exactly like /goal resume. " + GOAL_RESUME_RULE,
+    promptSnippet: "Resume the escape-paused or handed-back goal, only on the user's clear go-ahead.",
     parameters: Type.Object({
       reason: Type.Optional(Type.String({ description: "Short quote or summary of the user's go-ahead." })),
     }),
@@ -1101,13 +1129,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 when it hands back unfinished work (a blocked unit awaiting the human). Its bound active Goal pauses; /goal resume rebinds the workflow. When the workflow is done, call update_goal complete instead, which also releases it.",
     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", undefined, "handback"), 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; the user's go-ahead or /goal resume rebinds /${resumeCommand}.` : ""}` }],
+        details: { released: true, owner: owner.name, goalPaused: resumeCommand !== undefined },
+      };
     },
   });
 
@@ -1211,7 +1251,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;
@@ -1234,7 +1275,7 @@ export default function (pi: ExtensionAPI): void {
     if (permissionPrompt && goal?.status === "paused") {
       return { systemPrompt: `${event.systemPrompt}\n\n${permissionPrompt}` };
     }
-    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && goal.pauseReason === "interrupt"
+    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && (goal.pauseReason === "interrupt" || goal.pauseReason === "handback")
       ? pausedGoalPrompt(goal, preferences.conversationalResume) : "");
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
@@ -1243,6 +1284,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 +1310,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 +1322,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 +1453,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 +1474,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/node_modules/pi-better-goal/src/types.ts

@@ -75,7 +75,8 @@ export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
  * requires those human controls, and releases just one same-scope retry while
  * keeping its separate blocker/release history.
  */
-export type GoalPauseReason = "interrupt" | "permission-blocker";
+/** Why a goal paused: escape, a permission hold, or a workflow handing back unfinished work for the user's answer. */
+export type GoalPauseReason = "interrupt" | "permission-blocker" | "handback";
 
 export interface GoalUsage {
   tokensUsed: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-harness",
-  "version": "0.28.0",
+  "version": "0.28.2",
   "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.4",
     "pi-better-plan": "0.8.0",
     "pi-better-sandbox": "0.12.0",
     "pi-better-ssh": "0.1.2",