pi-better-goal 0.1.16 → 0.1.18

package/README.md

@@ -16,6 +16,7 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 - 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 that holds after repeated identical outcomes.
+- An observable-progress stall state for active goals.
 
 ## Install
 

package/package.json

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

package/src/goal-clock.ts

@@ -81,20 +81,19 @@ export function renderGoalClockLine(
   const timing = goalTiming(goal, now);
   const heading = `goal ${goal.status}`;
   const active = formatClockDuration(timing.activeSeconds);
-  const fixedWidth = visibleWidth(`▸ ${heading} ${active} `);
+  const fixedWidth = visibleWidth(`${heading} ${active} `);
   if (fixedWidth >= width) {
-    return truncateToWidth(`▸ ${heading} ${active}`, width);
+    return truncateToWidth(`${heading} ${active}`, width);
   }
   const objective = truncateToWidth(goal.objective, width - fixedWidth);
-  return styleGoalRailLine("▸", heading, `${active} ${objective}`, fg);
+  return styleGoalRailLine(heading, `${active} ${objective}`, fg);
 }
 
 function styleGoalRailLine(
-  marker: string,
   heading: string,
   tail: string,
   fg?: (color: string, value: string) => string,
 ): string {
-  if (!fg) return `${marker} ${heading} ${tail}`;
-  return `${fg("dim", marker)} ${fg("warning", heading)} ${fg("dim", tail)}`;
+  if (!fg) return `${heading} ${tail}`;
+  return `${fg("warning", heading)} ${fg("dim", tail)}`;
 }

package/src/goal-state.ts

@@ -29,6 +29,8 @@ export interface ContinuationState {
   goalId: string;
   lastEvidenceSignature: string | null;
   lastEvidenceSummary: string;
+  /** Millisecond timestamp of the last changed foreground or external evidence. */
+  lastProgressAt?: number;
   noProgressRetries: number;
   blocked: boolean;
   updatedAt: number;
@@ -81,6 +83,7 @@ function isContinuationState(value: unknown): value is ContinuationState {
     typeof candidate.goalId === "string" &&
     (candidate.lastEvidenceSignature === null || typeof candidate.lastEvidenceSignature === "string") &&
     typeof candidate.lastEvidenceSummary === "string" &&
+    (candidate.lastProgressAt === undefined || (typeof candidate.lastProgressAt === "number" && Number.isFinite(candidate.lastProgressAt))) &&
     typeof candidate.noProgressRetries === "number" &&
     Number.isInteger(candidate.noProgressRetries) &&
     candidate.noProgressRetries >= 0 &&
@@ -178,6 +181,7 @@ export function createContinuationState(goalId: string, now = unixSeconds()): Co
     goalId,
     lastEvidenceSignature: null,
     lastEvidenceSummary: "",
+    lastProgressAt: now * 1000,
     noProgressRetries: 0,
     blocked: false,
     updatedAt: now,

package/src/index.ts

@@ -21,6 +21,7 @@ import {
   validateTokenBudget,
 } from "./goal-state.js";
 import { continuationEvidence, type ContinuationEvidence } from "./continuation.js";
+import { observeGoalStall } from "./stall.js";
 import {
   goalClockRefreshDelayMs,
   goalTiming,
@@ -82,7 +83,11 @@ function continuationPrompt(goal: GoalSnapshot): string {
   ].join("\n");
 }
 
-function formatGoal(goal: GoalSnapshot | null, continuation: ReturnType<typeof currentContinuationState> = null): string {
+function formatGoal(
+  goal: GoalSnapshot | null,
+  continuation: ReturnType<typeof currentContinuationState> = null,
+  stall = observeGoalStall(goal, continuation),
+): string {
   if (!goal) {
     return "No goal is set.";
   }
@@ -98,6 +103,7 @@ function formatGoal(goal: GoalSnapshot | null, continuation: ReturnType<typeof c
     `Tokens used: ${goal.usage.tokensUsed}`,
     `Active time: ${timing.activeSeconds}s`,
     `Elapsed time: ${timing.elapsedSeconds}s`,
+    `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
   ].join("\n");
 }
@@ -309,10 +315,16 @@ export default function (pi: ExtensionAPI): void {
     if (ctx.hasUI) {
       const goal = getGoal(ctx);
       const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
+      const goalStall = observeGoalStall(goal, continuation, {
+        foregroundRunning,
+        backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
+      });
       const status = snapshot.backgroundRunning
         ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
         : continuation?.blocked
           ? "waiting: no progress"
+          : goalStall?.state === "stalled"
+            ? "goal stalled"
           : undefined;
       try {
         ctx.ui.setStatus(EXTENSION_NAME, status);
@@ -407,7 +419,8 @@ export default function (pi: ExtensionAPI): void {
       const current = getGoal(ctx);
 
       if (!trimmed) {
-        ctx.ui.notify(formatGoal(current, current ? currentContinuationState(ctx, current.goalId) : null), "info");
+        const continuation = current ? currentContinuationState(ctx, current.goalId) : null;
+        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning })), "info");
         return;
       }
 
@@ -477,9 +490,13 @@ export default function (pi: ExtensionAPI): void {
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
       const goal = getGoal(ctx);
       const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
+      const stall = observeGoalStall(goal, continuation, {
+        foregroundRunning,
+        backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
+      });
       return {
-        content: [{ type: "text", text: formatGoal(goal, continuation) }],
-        details: { goal, continuation, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
+        content: [{ type: "text", text: formatGoal(goal, continuation, stall) }],
+        details: { goal, continuation, stall, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
       };
     },
   });
@@ -607,13 +624,17 @@ export default function (pi: ExtensionAPI): void {
       const repeated = previous.lastEvidenceSignature === evidence.signature;
       const noProgressRetries = repeated ? previous.noProgressRetries + 1 : 0;
       const blocked = repeated && noProgressRetries >= MAX_NO_PROGRESS_RETRIES;
+      const now = Date.now();
       appendContinuationState({
         goalId: goal.goalId,
         lastEvidenceSignature: evidence.signature,
         lastEvidenceSummary: evidence.summary,
+        ...(repeated
+          ? (previous.lastProgressAt !== undefined ? { lastProgressAt: previous.lastProgressAt } : {})
+          : { lastProgressAt: now }),
         noProgressRetries,
         blocked,
-        updatedAt: Math.floor(Date.now() / 1000),
+        updatedAt: Math.floor(now / 1000),
       });
       if (blocked) {
         refreshGoalWidget?.();

package/src/shared-stall-detector.ts

@@ -0,0 +1,69 @@
+// Generated from packages/stall-detector/index.ts. Do not edit directly.
+export interface StallThresholds {
+  /** Age of observable progress before work becomes quiet. */
+  quietMs: number;
+  /** Age of observable progress before work becomes stalled. */
+  stallMs: number;
+}
+
+export type StallState = "healthy" | "quiet" | "stalled" | "unknown";
+
+export interface StallObservation {
+  state: StallState;
+  /** Most recent meaningful evidence, falling back to the start time. */
+  observedAt?: number;
+  ageMs?: number;
+  thresholds: StallThresholds;
+}
+
+export interface ObserveStallInput {
+  now: number;
+  /** Explicit meaningful progress, never a timer tick or metadata write. */
+  lastProgressAt?: number;
+  /** Fallback anchor for work that has not produced progress yet. */
+  startedAt?: number;
+  /** Known active phases that explain a lack of observable progress. */
+  exempt?: boolean;
+  thresholds?: Partial<StallThresholds>;
+}
+
+export const DEFAULT_STALL_THRESHOLDS: Readonly<StallThresholds> = Object.freeze({
+  quietMs: 60_000,
+  stallMs: 5 * 60_000,
+});
+
+function positiveMs(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+/** Normalize caller config and ensure quiet never exceeds the stall threshold. */
+export function resolveStallThresholds(partial?: Partial<StallThresholds> | null): StallThresholds {
+  const quietMs = positiveMs(partial?.quietMs, DEFAULT_STALL_THRESHOLDS.quietMs);
+  const stallMs = positiveMs(partial?.stallMs, DEFAULT_STALL_THRESHOLDS.stallMs);
+  return { quietMs: Math.min(quietMs, stallMs), stallMs: Math.max(quietMs, stallMs) };
+}
+
+/**
+ * Classify the age of observable progress. This is deliberately observational:
+ * it does not claim a live process is broken and never performs recovery.
+ */
+export function observeStall(input: ObserveStallInput): StallObservation {
+  const thresholds = resolveStallThresholds(input.thresholds);
+  const observedAt = input.lastProgressAt ?? input.startedAt;
+  if (typeof observedAt !== "number" || !Number.isFinite(observedAt)) {
+    return { state: "unknown", thresholds };
+  }
+
+  const ageMs = Math.max(0, input.now - observedAt);
+  if (input.exempt) {
+    return { state: ageMs >= thresholds.quietMs ? "quiet" : "healthy", observedAt, ageMs, thresholds };
+  }
+  if (ageMs >= thresholds.stallMs) {
+    return { state: "stalled", observedAt, ageMs, thresholds };
+  }
+  if (ageMs >= thresholds.quietMs) {
+    return { state: "quiet", observedAt, ageMs, thresholds };
+  }
+  return { state: "healthy", observedAt, ageMs, thresholds };
+}

package/src/stall.ts

@@ -0,0 +1,34 @@
+import { observeStall, type StallObservation, type StallThresholds } from "./shared-stall-detector.js";
+import type { ContinuationState } from "./goal-state.js";
+import type { GoalSnapshot } from "./types.js";
+
+function durationEnv(name: string): number | undefined {
+  const raw = process.env[name];
+  if (!raw || raw.trim() === "") return undefined;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : undefined;
+}
+
+export function goalStallThresholds(): Partial<StallThresholds> {
+  const thresholds: Partial<StallThresholds> = {};
+  const quietMs = durationEnv("PI_BETTER_STALL_QUIET_MS");
+  const stallMs = durationEnv("PI_BETTER_STALL_MS");
+  if (quietMs !== undefined) thresholds.quietMs = quietMs;
+  if (stallMs !== undefined) thresholds.stallMs = stallMs;
+  return thresholds;
+}
+
+export function observeGoalStall(
+  goal: GoalSnapshot | null,
+  continuation: ContinuationState | null,
+  options: { now?: number; foregroundRunning?: boolean; backgroundRunning?: boolean } = {},
+): StallObservation | null {
+  if (!goal) return null;
+  return observeStall({
+    now: options.now ?? Date.now(),
+    ...(continuation?.lastProgressAt !== undefined ? { lastProgressAt: continuation.lastProgressAt } : {}),
+    startedAt: goal.createdAt * 1000,
+    exempt: goal.status !== "active" || options.foregroundRunning === true || options.backgroundRunning === true,
+    thresholds: goalStallThresholds(),
+  });
+}