pi-better-goal 0.10.0 → 0.10.2

package/README.md

@@ -21,6 +21,12 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - 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.
 
+## Optional Harness-Owned Outcome & Todo
+
+When `pi-better-harness` is installed, its optional **Outcome & Todo** runtime owns the session's structured outcome and checklist. Goal keeps its own objective, clocks, pause and permission holds, workflow gates, background wake behavior, and continuation policy; it also sends lifecycle requests to the Harness runtime so a bound outcome starts, pauses, resumes, and completes with the Goal. When the runtime is present, Goal stops adding its own active-objective text to avoid duplicating the Harness-owned outcome, whether Outcome & Todo is enabled or off.
+
+`/goal` does not install, enable, or configure Outcome & Todo. Install Harness and enable **Outcome & Todo** in `/harness-settings` if you want that shared outcome and checklist. Without Harness, this package keeps its standalone prompts and behavior unchanged. The stored Goal objective remains the raw original trigger (for example, a bound command invocation) so `/goal resume` can re-enter the work; it is not the authoritative business outcome when Harness owns one.
+
 ## Settings Storage
 
 Goal preferences are saved only in Pi's global `~/.pi/agent/settings.json` under
@@ -59,7 +65,7 @@ After every successful context compaction (Pi's `session_compact` event) while a
 
 ### Scheduler-backed workflow gates
 
-A coordinator that ships the resolve-issues scheduler (`scripts/next-actions.mjs` in its skill directory, or in a sibling `resolve-issues` skill) keeps its Goal from ending while the run still has work. The extension runs `node next-actions.mjs --run <run dir> --slots 1 --peek --json` (read-only, 20-second timeout), where the run directory is the folder of the task plan bound through `update_plan`. Every gate fails open: if the scheduler is missing, errors, times out, prints bad output, or no plan is bound yet, the call proceeds and its result carries a warning, so nothing deadlocks.
+A coordinator that ships the resolve-issues scheduler (`scripts/next-actions.mjs` in its skill directory, or in a sibling `resolve-issues` skill) keeps its Goal from ending while the run still has work. The extension first runs `node next-actions.mjs --run <run dir> --slots 1 --peek --json` (read-only, 20-second timeout), where the run directory is the folder of the task plan bound through `update_plan`. For completion and handback only, if the sole due action is `sync`, it reruns with `--sync` to obtain a fresh issue tree. This live check has a four-minute timeout to accommodate the tree fetcher's network attempts and follow-ups. Because `--peek` suppresses scheduler bookkeeping but not issue-tree cache writes, the live check uses a temporary copy of the scheduler's plan, tree, bookkeeping, review, and result inputs; it does not write the bound run. Heartbeat probes never request live synchronization. A failed or incomplete tree fetch that produces `sync` still refuses completion or handback; cached evidence is not treated as live. Every gate retains its fail-open behavior for execution failures: if the scheduler is missing, errors, times out, prints bad output, or no plan is bound yet, the call proceeds and its result carries a warning, so nothing deadlocks.
 
 - **Completion.** `update_goal` complete is refused, with each due action (action, unit, first 200 characters of detail), unless the scheduler reports `finish` and nothing else is due (an empty due list means workers are still running, so it is refused too). The Goal stays active.
 - **Pause.** `release_workflow` is refused unless every unfinished unit is quiet (nothing due for it) or blocked `human-decision` with `humanItem` 2-5. A unit blocked `retry-ci` or any other reason the run retries itself, or a `human-decision` item 1, is named in the refusal and the Goal stays active.

package/package.json

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

package/src/index.ts

@@ -42,6 +42,7 @@ import { collectSubagentActivity } from "./subagents.js";
 import { currentWorkflowOwner, skillCommandName, workflowEntry, workflowOwnerFromSkill, WORKFLOW_ENTRY_TYPE } from "./workflow.js";
 import { completionGate, pauseGate, schedulerWaitUntil } from "./workflow-gates.js";
 import { workflowRehydrateMessage, WORKFLOW_REHYDRATE_MESSAGE_TYPE } from "./rehydrate.js";
+import { requestTaskContext } from "./task-context.js";
 import {
   EVENT_ACTIVITY,
   EVENT_READY,
@@ -103,11 +104,11 @@ export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true
   return agentResumable(goal, conversationalResume) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
 }
 
-function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): string {
+function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean, includeObjective = true): string {
   return [
     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}`,
+      ? `Pi Better Goal is paused because its workflow handed back unfinished work for the user's answer.${includeObjective ? ` Goal: ${goal.objective}` : ""}`
+      : `Pi Better Goal is paused because the user pressed escape.${includeObjective ? ` 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");
@@ -407,6 +408,17 @@ export default function (pi: ExtensionAPI): void {
     const previous = getGoal(ctx);
     const wasVisible = previous !== null && isGoalClockVisible(previous);
     pi.appendEntry(EXTENSION_NAME, goalSetEntry(goal, source));
+    // Bridge lifecycle after the raw Goal entry is durable. Harness may own the
+    // structured outcome, but Goal still owns its trigger, clocks, pauses, and wakes.
+    if (!previous || previous.goalId !== goal.goalId) {
+      requestTaskContext(pi, "start", goal);
+    } else if (goal.status === "complete") {
+      requestTaskContext(pi, "complete", goal);
+    } else if (goal.status === "paused" || goal.status === "budgetLimited") {
+      requestTaskContext(pi, "pause", goal);
+    } else if (goal.status === "active" && previous.status !== "active") {
+      requestTaskContext(pi, "resume", goal);
+    }
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
     clearIdleContinuation();
@@ -422,6 +434,8 @@ export default function (pi: ExtensionAPI): void {
     lastAgentEvidence = null;
     const current = getGoal(ctx);
     const wasVisible = current !== null && isGoalClockVisible(current);
+    // Clearing pauses a Harness-bound outcome; it never deletes or completes it.
+    if (current) requestTaskContext(pi, "pause", current);
     pi.appendEntry(EXTENSION_NAME, goalClearEntry(current?.goalId ?? null, source));
     if (getWorkflow(ctx)) recordWorkflow(null);
     continuationQueuedFor = null;
@@ -868,6 +882,11 @@ export default function (pi: ExtensionAPI): void {
             }
             const nextRenderDelay = goalClockRefreshDelayMs(goal);
             if (nextRenderDelay !== null) scheduler.schedule(nextRenderDelay);
+            // Schedule before handing visual ownership to Harness so its header
+            // keeps ticking. An absent display response preserves standalone Goal.
+            if (requestTaskContext(pi, "inspect", goal, width).display === true) {
+              return [];
+            }
             const fg = typeof theme?.fg === "function"
               ? (color: string, value: string) => theme.fg(color as never, value)
               : undefined;
@@ -1318,6 +1337,9 @@ export default function (pi: ExtensionAPI): void {
     currentCtx = ctx;
     const goal = currentGoalSnapshot(ctx);
     const owner = getWorkflow(ctx);
+    // A defined `enabled` means a Harness runtime is present, even when
+    // Outcome & Todo is off. Then Harness owns the structured outcome text.
+    const harnessPresent = requestTaskContext(pi, "inspect", goal).enabled !== undefined;
     const snapshot = await publishSnapshot(ctx);
     if (!snapshot) return;
     const permissions = goal ? currentPermissionHold(ctx, goal.goalId) : null;
@@ -1330,7 +1352,7 @@ export default function (pi: ExtensionAPI): void {
       return { systemPrompt: `${event.systemPrompt}\n\n${permissionPrompt}` };
     }
     const pausedInstruction = permissionPrompt || (goal?.status === "paused" && (goal.pauseReason === "interrupt" || goal.pauseReason === "handback")
-      ? pausedGoalPrompt(goal, preferences.conversationalResume) : "");
+      ? pausedGoalPrompt(goal, preferences.conversationalResume, !harnessPresent) : "");
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }
@@ -1363,7 +1385,11 @@ export default function (pi: ExtensionAPI): void {
               : "While the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n")
             : "") +
           `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.` : "") +
+          (isPokeable(goal)
+            ? harnessPresent
+              ? "\n\nComplete the goal only after the workflow completion audit."
+              : `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.`
+            : "") +
           (questionInstruction ? `\n\n${questionInstruction.trim()}` : "") +
           (heldInstruction ? `\n\n${heldInstruction}` : ""),
       };
@@ -1373,6 +1399,15 @@ export default function (pi: ExtensionAPI): void {
     const backgroundInstruction = snapshot.backgroundRunning
       ? ` The goal still has delegated background work running (${summarizeActiveBackground(snapshot)}). Foreground idleness alone is not goal completion; keep any structured plan current and do not mark verification, the plan, or the goal complete until every relevant delegated task reaches a terminal state and its result or failure has been inspected and integrated.`
       : "";
+    if (harnessPresent) {
+      // Harness owns the outcome text. Retain only the Goal-specific guidance
+      // that the Outcome & Todo prompt cannot replace.
+      const retained = [heldInstruction, backgroundInstruction.trim(), questionInstruction.trim(), permissionPrompt]
+        .filter((part) => part.length > 0);
+      return retained.length > 0
+        ? { systemPrompt: `${event.systemPrompt}\n\n${retained.join("\n\n")}` }
+        : undefined;
+    }
     return {
       systemPrompt:
         `${event.systemPrompt}\n\n` +

package/src/task-context.ts

@@ -0,0 +1,50 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { GoalSnapshot } from "./types.js";
+
+/** Synchronous request bus shared with an installed `pi-better-harness` runtime. */
+export const TASK_CONTEXT_EVENT = "pi-better-harness:task-context";
+
+export type TaskContextAction = "inspect" | "start" | "pause" | "resume" | "complete";
+
+/**
+ * Mutable request. A present Harness runtime sets `enabled` to a boolean even
+ * when Outcome & Todo is off. Without Harness the field stays undefined, which
+ * lets Goal retain its standalone behavior.
+ */
+export interface TaskContextRequest {
+  action: TaskContextAction;
+  goalId?: string;
+  /** Current widget width on a visual ownership inspection. */
+  width?: number;
+  /** The raw original goal trigger; only start requests carry it. */
+  objective?: string;
+  /** Hooks authority: a present Harness runtime sets this even when Outcome & Todo is off. */
+  enabled?: boolean;
+  /**
+   * Visual ownership. A Harness runtime sets this on `inspect` responses when
+   * its combined Todo header is rendering the requested `goalId`. It is
+   * independent of `enabled` and stays undefined without Harness, so Goal keeps
+   * its standalone clock widget whenever that header does not own the goal.
+   */
+  display?: boolean;
+}
+
+/**
+ * Emit one task-context request and return it so the caller can inspect the
+ * Harness-owned `enabled` field after synchronous listeners run.
+ */
+export function requestTaskContext(
+  pi: Pick<ExtensionAPI, "events">,
+  action: TaskContextAction,
+  goal?: GoalSnapshot | null,
+  width?: number,
+): TaskContextRequest {
+  const request: TaskContextRequest = { action };
+  if (width !== undefined) request.width = width;
+  if (goal) {
+    request.goalId = goal.goalId;
+    if (action === "start") request.objective = goal.objective;
+  }
+  pi.events.emit(TASK_CONTEXT_EVENT, request);
+  return request;
+}

package/src/workflow-gates.ts

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
-import { readFileSync, statSync } from "node:fs";
+import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 import type { WorkflowOwner } from "./workflow.js";
@@ -8,6 +9,8 @@ import type { WorkflowOwner } from "./workflow.js";
 const WORKFLOW_PLAN_ENTRY = "pi-better-workflow-plan";
 const WORKFLOW_ENTRY = "pi-better-workflow";
 export const SCHEDULER_TIMEOUT_MS = 20_000;
+// Live tree queries allow three 60-second attempts plus follow-ups; cached probes stay cheap.
+const SCHEDULER_SYNC_TIMEOUT_MS = 240_000;
 const DETAIL_LIMIT = 200;
 
 /** Scheduler locations relative to the owner's skill directory, in precedence order. */
@@ -100,9 +103,13 @@ function parseSchedulerOutput(stdout: string): SchedulerRun {
  * are due and 2 on a usage or plan error, so only the latter, a timeout, or bad output is a failure.
  */
 export function runScheduler(script: string, runDir: string, timeoutMs = SCHEDULER_TIMEOUT_MS): Promise<SchedulerRun> {
+  return executeScheduler(script, runDir, timeoutMs);
+}
+
+function executeScheduler(script: string, runDir: string, timeoutMs: number, live = false, cwd = runDir): Promise<SchedulerRun> {
   return new Promise((resolve) => {
-    execFile("node", [script, "--run", runDir, "--slots", "1", "--peek", "--json"],
-      { cwd: runDir, timeout: timeoutMs, encoding: "utf8", windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
+    execFile("node", [script, "--run", runDir, "--slots", "1", "--peek", "--json", ...(live ? ["--sync"] : [])],
+      { cwd, timeout: timeoutMs, encoding: "utf8", windowsHide: true, maxBuffer: 8 * 1024 * 1024 },
       (error, stdout, stderr) => {
         if (error) {
           // An exit status of 1 means "actions due"; any other failure (exit 2, timeout, spawn error) is real.
@@ -117,6 +124,27 @@ export function runScheduler(script: string, runDir: string, timeoutMs = SCHEDUL
   });
 }
 
+async function settlementScheduler(script: string, runDir: string, timeoutMs?: number): Promise<SchedulerRun> {
+  const cached = await runScheduler(script, runDir, timeoutMs);
+  if (!cached.ok || cached.due.length !== 1 || cached.due[0]!.action !== "sync") return cached;
+
+  // --peek suppresses seen bookkeeping, not syncRun's issue-tree write. Give the live
+  // probe private inputs; keep cwd so relative workspace paths retain their meaning.
+  let snapshot: string | undefined;
+  try {
+    snapshot = mkdtempSync(join(tmpdir(), "pi-goal-scheduler-"));
+    for (const name of ["task-plan.json", "issue-tree.json", "next-actions-seen.json", "reviews", "results"]) {
+      const source = join(runDir, name);
+      if (existsSync(source)) cpSync(source, join(snapshot, name), { recursive: true, dereference: true });
+    }
+    return await executeScheduler(script, snapshot, timeoutMs ?? SCHEDULER_SYNC_TIMEOUT_MS, true, runDir);
+  } catch (error) {
+    return { ok: false, reason: `could not prepare the live scheduler check (${String(error).slice(0, DETAIL_LIMIT)})` };
+  } finally {
+    if (snapshot) rmSync(snapshot, { recursive: true, force: true });
+  }
+}
+
 interface PlannedRun {
   runDir: string;
   script: string;
@@ -147,7 +175,7 @@ export async function completionGate(
 ): Promise<GateVerdict> {
   const located = locateRun(entries, owner);
   if ("warning" in located) return unchecked(located.warning);
-  const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
+  const run = await settlementScheduler(located.script, located.runDir, options.timeoutMs);
   if (!run.ok) return unchecked(`could not check the ${owner.name} run (${run.reason})`);
   const open = run.due.filter((action) => action.action !== "finish");
   if (open.length === 0 && run.due.length > 0) return { allow: true };
@@ -190,7 +218,7 @@ export async function pauseGate(
   if ("warning" in located) return unchecked(located.warning);
   const units = readUnits(located.runDir);
   if (!units) return unchecked(`could not read the ${owner.name} task plan`);
-  const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
+  const run = await settlementScheduler(located.script, located.runDir, options.timeoutMs);
   if (!run.ok) return unchecked(`could not check the ${owner.name} run (${run.reason})`);
 
   const refusals: string[] = [];