pi-better-goal 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# pi-better-goal
+
+`pi-better-goal` is a Pi package that provides a `/goal` runtime with background-aware continuation for async subagents.
+
+It ships one extension that:
+
+- reads `pi-better-subagents` durable run metadata from the temp registry
+- treats current-parent `running` and `orphaned` subagents as active background work
+- owns `/goal` plus the `get_goal` and `update_goal` tools; only `/goal <objective>` can create a goal
+- shows the current goal with active and elapsed clocks in a right-aligned widget above custom footers such as `pi-observability`
+- publishes a typed activity snapshot on `pi.events`
+- adds goal-aware prompt context while background work is active, so foreground idleness is not confused with goal completion
+- sends a hidden follow-up when active background work drains to zero, including `callback:false` subagent runs
+- provides a `/better-activity` command and `get_background_activity` tool for inspection
+
+Goal state is stored as `pi-better-goal` custom entries in the Pi session. Existing `pi-codex-goal` entries are read for compatibility, but new state is written by this package.
+
+## Commands And Tools
+
+```text
+/goal
+/goal <objective>
+/goal pause
+/goal resume
+/goal clear
+/goal complete
+/better-activity
+```
+
+Model-callable tools:
+
+- `get_goal`
+- `update_goal`
+- `get_background_activity`
+
+## Goal Clock
+
+Only `/goal <objective>` can create or replace a goal; there is no model-callable
+goal creation tool. The right-aligned widget below the editor shows the objective,
+status, active time, and total elapsed time. Active time stops while paused. Both
+clocks freeze when the goal is completed and remain visible until the goal is
+cleared or replaced.
+
+The widget does not replace Pi's footer, so custom footer extensions such as
+`pi-observability` retain ownership of their layout and lifecycle.
+
+Set `PI_BETTER_GOAL_DISABLE_WAKE=1` to disable hidden background-drain wakeups.
+
+## Install Locally
+
+From this directory:
+
+```sh
+npm install
+pi install .
+```
+
+For a one-off run:
+
+```sh
+pi -e .
+```
+
+## Event Contract
+
+The extension emits these events on `pi.events`:
+
+- `pi-better-goal:ready` with `{ version }`
+- `pi-better-goal:activity` with an `ActivitySnapshot`
+- `pi-better-goal:terminal-attention` when terminal or unhealthy background work needs attention
+
+Other extensions can register providers by emitting `pi-better-goal:register-provider` with:
+
+```ts
+{
+  id: "provider-id",
+  label: "Provider label",
+  getActivity(ctx) {
+    return {
+      providerId: "provider-id",
+      label: "Provider label",
+      items: [
+        { id: "work-1", status: "running", active: true }
+      ]
+    };
+  }
+}
+```
+
+The built-in provider id is `subagents`.
+
+## Status Semantics
+
+For `pi-better-subagents`, active background work is:
+
+- `running`
+- `orphaned`
+
+`orphaned` is active but unhealthy. `completed`, `failed`, `killed`, `lost`, and `exited` are non-active terminal states. Batches are represented as normal per-run items; batch metadata is display-only.
+
+## Validation
+
+```sh
+npm run verify
+```

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "pi-better-goal",
+  "version": "0.1.0",
+  "description": "Background activity bridge for Pi goal continuations and async subagents.",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "goal",
+    "subagents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1aboveio/pi-better-harness.git",
+    "directory": "packages/pi-better-goal"
+  },
+  "bugs": {
+    "url": "https://github.com/1aboveio/pi-better-harness/issues"
+  },
+  "homepage": "https://github.com/1aboveio/pi-better-harness/tree/main/packages/pi-better-goal#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --import tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
+    "@types/node": "^25.0.0",
+    "tsx": "^4.22.3",
+    "typebox": "^1.1.39",
+    "typescript": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/src/activity.ts

@@ -0,0 +1,158 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type {
+  ActivityCategory,
+  ActivitySnapshot,
+  BackgroundActivityProvider,
+  BackgroundProviderSnapshot,
+  BackgroundWorkItem,
+  GoalSnapshot,
+} from "./types.js";
+
+export interface BackgroundDrainTracker {
+  goalId: string;
+  activeSignature: string;
+}
+
+export interface BackgroundDrainPlan {
+  nextTracker: BackgroundDrainTracker | null;
+  wakeSignature: string | null;
+}
+
+export function activeItems(snapshot: ActivitySnapshot): BackgroundWorkItem[] {
+  return snapshot.providers.flatMap((provider) => provider.items.filter((item) => item.active));
+}
+
+export function attentionItems(snapshot: ActivitySnapshot): BackgroundWorkItem[] {
+  return snapshot.providers.flatMap((provider) => provider.items.filter((item) => item.attention));
+}
+
+export function activeSignature(snapshot: ActivitySnapshot): string {
+  return activeItems(snapshot)
+    .map((item) => `${item.id}:${item.status}`)
+    .sort()
+    .join("|");
+}
+
+export function terminalAttentionSignature(snapshot: ActivitySnapshot): string {
+  return attentionItems(snapshot)
+    .map((item) => `${item.id}:${item.status}`)
+    .sort()
+    .join("|");
+}
+
+export function planBackgroundDrainWake(
+  tracker: BackgroundDrainTracker | null,
+  goal: GoalSnapshot | null,
+  snapshot: ActivitySnapshot,
+): BackgroundDrainPlan {
+  if (goal?.status !== "active") {
+    return { nextTracker: null, wakeSignature: null };
+  }
+
+  const active = activeSignature(snapshot);
+  if (active) {
+    return {
+      nextTracker: { goalId: goal.goalId, activeSignature: active },
+      wakeSignature: null,
+    };
+  }
+
+  if (!snapshot.backgroundRunning && tracker?.goalId === goal.goalId && tracker.activeSignature) {
+    return {
+      nextTracker: null,
+      wakeSignature: `${goal.goalId}:${tracker.activeSignature}`,
+    };
+  }
+
+  return { nextTracker: tracker?.goalId === goal.goalId ? tracker : null, wakeSignature: null };
+}
+
+export function summarizeActiveBackground(snapshot: ActivitySnapshot): string {
+  const active = activeItems(snapshot);
+  if (active.length === 0) {
+    return "No active background work.";
+  }
+  return active
+    .map((item) => {
+      const label = item.label ? `${item.label} (${item.id})` : item.id;
+      const health = item.unhealthy ? ", unhealthy" : "";
+      return `${label}: ${item.status}${health}`;
+    })
+    .join("; ");
+}
+
+export async function collectActivitySnapshot(
+  ctx: ExtensionContext,
+  providers: Iterable<BackgroundActivityProvider>,
+  foregroundRunning: boolean,
+  now = Date.now(),
+): Promise<ActivitySnapshot> {
+  const providerSnapshots: BackgroundProviderSnapshot[] = [];
+
+  for (const provider of providers) {
+    try {
+      const snapshot = await provider.getActivity(ctx);
+      const normalized: BackgroundProviderSnapshot = {
+        providerId: snapshot.providerId || provider.id,
+        items: snapshot.items,
+      };
+      const label = snapshot.label ?? provider.label;
+      if (label !== undefined) {
+        normalized.label = label;
+      }
+      providerSnapshots.push(normalized);
+    } catch (error) {
+      const failedSnapshot: BackgroundProviderSnapshot = {
+        providerId: provider.id,
+        items: [
+          {
+            id: `${provider.id}:provider-error`,
+            status: "failed",
+            active: false,
+            terminal: true,
+            attention: true,
+            details: {
+              error: error instanceof Error ? error.message : String(error),
+            },
+          },
+        ],
+      };
+      if (provider.label !== undefined) {
+        failedSnapshot.label = provider.label;
+      }
+      providerSnapshots.push(failedSnapshot);
+    }
+  }
+
+  const activeBackgroundCount = providerSnapshots.reduce(
+    (sum, provider) => sum + provider.items.filter((item) => item.active).length,
+    0,
+  );
+  const unhealthyBackgroundCount = providerSnapshots.reduce(
+    (sum, provider) => sum + provider.items.filter((item) => item.active && item.unhealthy).length,
+    0,
+  );
+  const terminalAttentionCount = providerSnapshots.reduce(
+    (sum, provider) => sum + provider.items.filter((item) => !item.active && item.attention).length,
+    0,
+  );
+
+  const category: ActivityCategory = foregroundRunning
+    ? "foreground-running"
+    : activeBackgroundCount > 0
+      ? "background-running"
+      : "idle-waiting";
+
+  return {
+    version: 1,
+    category,
+    foregroundRunning,
+    backgroundRunning: activeBackgroundCount > 0,
+    activeBackgroundCount,
+    unhealthyBackgroundCount,
+    terminalAttentionCount,
+    providers: providerSnapshots,
+    generatedAt: now,
+  };
+}

package/src/goal-clock.ts

@@ -0,0 +1,76 @@
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { GoalSnapshot } from "./types.js";
+
+export interface GoalTiming {
+  activeSeconds: number;
+  elapsedSeconds: number;
+}
+
+export function goalTiming(goal: GoalSnapshot, now = Math.floor(Date.now() / 1000)): GoalTiming {
+  const activeDelta =
+    goal.status === "active" && goal.activeStartedAt !== null
+      ? Math.max(0, now - goal.activeStartedAt)
+      : 0;
+  const end = goal.completedAt ?? now;
+
+  return {
+    activeSeconds: goal.usage.activeSeconds + activeDelta,
+    elapsedSeconds: Math.max(0, end - goal.createdAt),
+  };
+}
+
+export function formatClockDuration(totalSeconds: number): string {
+  const seconds = Math.max(0, Math.floor(totalSeconds));
+  const hours = Math.floor(seconds / 3_600);
+  const minutes = Math.floor((seconds % 3_600) / 60);
+  const remainder = seconds % 60;
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${remainder.toString().padStart(2, "0")}`;
+  }
+  return `${minutes}:${remainder.toString().padStart(2, "0")}`;
+}
+
+export function formatGoalClock(
+  goal: GoalSnapshot,
+  now = Math.floor(Date.now() / 1000),
+): string {
+  const timing = goalTiming(goal, now);
+  return (
+    `Goal [${goal.status}]: ${goal.objective}` +
+    ` | active ${formatClockDuration(timing.activeSeconds)}` +
+    ` | elapsed ${formatClockDuration(timing.elapsedSeconds)}`
+  );
+}
+
+export function renderGoalClockLine(
+  goal: GoalSnapshot,
+  width: number,
+  now = Math.floor(Date.now() / 1000),
+  fg?: (color: string, value: string) => string,
+): string {
+  if (width <= 0) {
+    return "";
+  }
+
+  const timing = goalTiming(goal, now);
+  const heading = `goal ${goal.status}`;
+  const active = formatClockDuration(timing.activeSeconds);
+  const fixedWidth = visibleWidth(`▸ ${heading} ${active} `);
+  if (fixedWidth >= width) {
+    return truncateToWidth(`▸ ${heading} ${active}`, width);
+  }
+  const objective = truncateToWidth(goal.objective, width - fixedWidth);
+  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)}`;
+}

package/src/goal-state.ts

@@ -0,0 +1,217 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { EXTENSION_NAME, type GoalSnapshot, type GoalStatus } from "./types.js";
+
+const LEGACY_GOAL_ENTRY_TYPE = "pi-codex-goal";
+const MAX_OBJECTIVE_CHARS = 8000;
+
+interface SessionEntryLike {
+  type: string;
+  customType?: string;
+  data?: unknown;
+}
+
+interface GoalLike {
+  goalId: string;
+  objective: string;
+  status: GoalStatus;
+  tokenBudget?: number | null;
+  usage?: { tokensUsed?: number; activeSeconds?: number };
+  createdAt?: number;
+  updatedAt?: number;
+  activeStartedAt?: number | null;
+  completedAt?: number | null;
+}
+
+export type GoalEntrySource = "command" | "tool" | "runtime";
+
+export type GoalCustomEntry =
+  | {
+      version: 1;
+      kind: "set";
+      source: GoalEntrySource;
+      goal: GoalSnapshot;
+      at: number;
+    }
+  | {
+      version: 1;
+      kind: "clear";
+      source: GoalEntrySource;
+      clearedGoalId: string | null;
+      at: number;
+    };
+
+function isGoalStatus(value: unknown): value is GoalStatus {
+  return value === "active" || value === "paused" || value === "budgetLimited" || value === "complete";
+}
+
+function isGoalLike(value: unknown): value is GoalLike {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value as Partial<GoalLike>;
+  return (
+    typeof candidate.goalId === "string" &&
+    typeof candidate.objective === "string" &&
+    isGoalStatus(candidate.status)
+  );
+}
+
+function unixSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+function nextGoalId(): string {
+  return `goal_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function normalizeGoal(goal: GoalLike): GoalSnapshot {
+  const now = unixSeconds();
+  const createdAt = typeof goal.createdAt === "number" ? goal.createdAt : now;
+  const updatedAt = typeof goal.updatedAt === "number" ? goal.updatedAt : createdAt;
+  return {
+    goalId: goal.goalId,
+    objective: goal.objective,
+    status: goal.status,
+    tokenBudget: typeof goal.tokenBudget === "number" ? goal.tokenBudget : null,
+    usage: {
+      tokensUsed: typeof goal.usage?.tokensUsed === "number" ? goal.usage.tokensUsed : 0,
+      activeSeconds: typeof goal.usage?.activeSeconds === "number" ? goal.usage.activeSeconds : 0,
+    },
+    createdAt,
+    updatedAt,
+    activeStartedAt:
+      typeof goal.activeStartedAt === "number"
+        ? goal.activeStartedAt
+        : goal.status === "active"
+          ? updatedAt
+          : null,
+    completedAt:
+      typeof goal.completedAt === "number"
+        ? goal.completedAt
+        : goal.status === "complete"
+          ? updatedAt
+          : null,
+  };
+}
+
+export function createGoalSnapshot(
+  objective: string,
+  tokenBudget: number | null = null,
+  now = unixSeconds(),
+): GoalSnapshot {
+  return {
+    goalId: nextGoalId(),
+    objective,
+    status: "active",
+    tokenBudget,
+    usage: { tokensUsed: 0, activeSeconds: 0 },
+    createdAt: now,
+    updatedAt: now,
+    activeStartedAt: now,
+    completedAt: null,
+  };
+}
+
+export function validateObjective(objective: string): string | null {
+  if (objective.trim().length === 0) {
+    return "Goal objective cannot be empty.";
+  }
+  if (objective.length > MAX_OBJECTIVE_CHARS) {
+    return `Goal objective is too long; limit is ${MAX_OBJECTIVE_CHARS} characters.`;
+  }
+  return null;
+}
+
+export function validateTokenBudget(tokenBudget: number | null | undefined): string | null {
+  if (tokenBudget === null || tokenBudget === undefined) {
+    return null;
+  }
+  if (!Number.isInteger(tokenBudget) || tokenBudget <= 0) {
+    return "Token budget must be a positive integer when provided.";
+  }
+  return null;
+}
+
+export function goalSetEntry(goal: GoalSnapshot, source: GoalEntrySource): GoalCustomEntry {
+  return { version: 1, kind: "set", source, goal, at: unixSeconds() };
+}
+
+export function goalClearEntry(clearedGoalId: string | null, source: GoalEntrySource): GoalCustomEntry {
+  return { version: 1, kind: "clear", source, clearedGoalId, at: unixSeconds() };
+}
+
+export function goalWithStatus(
+  goal: GoalSnapshot,
+  status: GoalStatus,
+  now = unixSeconds(),
+): GoalSnapshot {
+  const accruedActiveSeconds =
+    goal.status === "active" && goal.activeStartedAt !== null
+      ? Math.max(0, now - goal.activeStartedAt)
+      : 0;
+  const usage = {
+    ...goal.usage,
+    activeSeconds: goal.usage.activeSeconds + accruedActiveSeconds,
+  };
+
+  if (status === "active") {
+    return {
+      ...goal,
+      status,
+      usage,
+      updatedAt: now,
+      activeStartedAt: goal.status === "active" ? goal.activeStartedAt : now,
+      completedAt: null,
+    };
+  }
+
+  return {
+    ...goal,
+    status,
+    usage,
+    updatedAt: now,
+    activeStartedAt: null,
+    completedAt: status === "complete" ? now : null,
+  };
+}
+
+export function reconstructGoalSnapshot(entries: Iterable<SessionEntryLike>): GoalSnapshot | null {
+  let goal: GoalSnapshot | null = null;
+
+  for (const entry of entries) {
+    if (
+      entry.type !== "custom" ||
+      (entry.customType !== EXTENSION_NAME && entry.customType !== LEGACY_GOAL_ENTRY_TYPE)
+    ) {
+      continue;
+    }
+    if (!entry.data || typeof entry.data !== "object") {
+      continue;
+    }
+    const data = entry.data as { kind?: unknown; goal?: unknown; status?: unknown };
+    if (data.kind === "clear") {
+      goal = null;
+      continue;
+    }
+    if (data.kind === "set" && isGoalLike(data.goal)) {
+      goal = normalizeGoal(data.goal);
+      continue;
+    }
+    if (data.kind === "usage" && goal && isGoalStatus(data.status)) {
+      goal = {
+        ...goal,
+        status: data.status,
+        activeStartedAt:
+          data.status === "active" ? (goal.activeStartedAt ?? goal.updatedAt) : null,
+        completedAt: data.status === "complete" ? goal.updatedAt : null,
+      };
+    }
+  }
+
+  return goal;
+}
+
+export function currentGoalSnapshot(ctx: ExtensionContext): GoalSnapshot | null {
+  return reconstructGoalSnapshot(ctx.sessionManager.getBranch() as Iterable<SessionEntryLike>);
+}

package/src/index.ts

@@ -0,0 +1,546 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+import {
+  collectActivitySnapshot,
+  planBackgroundDrainWake,
+  summarizeActiveBackground,
+  terminalAttentionSignature,
+  type BackgroundDrainTracker,
+} from "./activity.js";
+import {
+  createGoalSnapshot,
+  currentGoalSnapshot,
+  goalClearEntry,
+  goalSetEntry,
+  goalWithStatus,
+  validateObjective,
+  validateTokenBudget,
+} from "./goal-state.js";
+import { goalTiming, renderGoalClockLine } from "./goal-clock.js";
+import { collectSubagentActivity } from "./subagents.js";
+import {
+  EVENT_ACTIVITY,
+  EVENT_READY,
+  EVENT_REGISTER_PROVIDER,
+  EVENT_TERMINAL_ATTENTION,
+  EXTENSION_NAME,
+  EXTENSION_VERSION,
+  type ActivitySnapshot,
+  type BackgroundActivityProvider,
+  type GoalSnapshot,
+} from "./types.js";
+
+const POLL_INTERVAL_MS = 2_000;
+const DEFAULT_IDLE_CONTINUATION_DELAY_MS = 30_000;
+const WAKE_DISABLED =
+  process.env.PI_BETTER_GOAL_DISABLE_WAKE === "1" ||
+  process.env.PI_BETTER_EXTENSION_DISABLE_WAKE === "1";
+const IDLE_CONTINUATION_DELAY_MS = parseDurationEnv(
+  process.env.PI_BETTER_GOAL_IDLE_CONTINUATION_DELAY_MS,
+  DEFAULT_IDLE_CONTINUATION_DELAY_MS,
+);
+
+function parseDurationEnv(raw: string | undefined, fallback: number): number {
+  if (raw === undefined || raw.trim() === "") {
+    return fallback;
+  }
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function continuationPrompt(goal: GoalSnapshot): string {
+  return [
+    "Continue working toward the active thread goal.",
+    "",
+    `Goal: ${goal.objective}`,
+    "",
+    "Keep working through clear low-risk next steps. Do not stop at a plan. Mark the goal complete only after an evidence-backed completion audit proves no required work remains.",
+  ].join("\n");
+}
+
+function formatGoal(goal: GoalSnapshot | null): string {
+  if (!goal) {
+    return "No goal is set.";
+  }
+  const budget = goal.tokenBudget === null ? "none" : String(goal.tokenBudget);
+  const timing = goalTiming(goal);
+  return [
+    `Goal: ${goal.objective}`,
+    `Status: ${goal.status}`,
+    `Token budget: ${budget}`,
+    `Tokens used: ${goal.usage.tokensUsed}`,
+    `Active time: ${timing.activeSeconds}s`,
+    `Elapsed time: ${timing.elapsedSeconds}s`,
+  ].join("\n");
+}
+
+function formatSnapshot(snapshot: ActivitySnapshot): string {
+  const providers = snapshot.providers.map((provider) => {
+    const active = provider.items.filter((item) => item.active).length;
+    const attention = provider.items.filter((item) => item.attention).length;
+    return `${provider.label ?? provider.providerId}: ${active} active, ${attention} attention`;
+  });
+  return [
+    `Activity: ${snapshot.category}`,
+    `Foreground running: ${snapshot.foregroundRunning}`,
+    `Background active: ${snapshot.activeBackgroundCount}`,
+    `Background unhealthy: ${snapshot.unhealthyBackgroundCount}`,
+    `Terminal attention: ${snapshot.terminalAttentionCount}`,
+    ...providers,
+  ].join("\n");
+}
+
+export default function (pi: ExtensionAPI): void {
+  const providers = new Map<string, BackgroundActivityProvider>();
+  providers.set("subagents", {
+    id: "subagents",
+    label: "Subagents",
+    getActivity: () => collectSubagentActivity(),
+  });
+
+  let currentCtx: ExtensionContext | undefined;
+  let foregroundRunning = false;
+  let pollTimer: ReturnType<typeof setInterval> | undefined;
+  let collecting = false;
+  let latestSnapshot: ActivitySnapshot | null = null;
+  let backgroundDrainTracker: BackgroundDrainTracker | null = null;
+  let lastWakeSignature = "";
+  let lastAttentionSignature = "";
+  let continuationQueuedFor: string | null = null;
+  let idleContinuationTimer: ReturnType<typeof setTimeout> | undefined;
+  let idleContinuationSignature = "";
+
+  const getGoal = (ctx: ExtensionContext): GoalSnapshot | null => currentGoalSnapshot(ctx);
+
+  const setGoal = (goal: GoalSnapshot, ctx: ExtensionContext, source: "command" | "tool" | "runtime"): void => {
+    pi.appendEntry(EXTENSION_NAME, goalSetEntry(goal, source));
+    continuationQueuedFor = null;
+    backgroundDrainTracker = null;
+    clearIdleContinuation();
+  };
+
+  const clearGoal = (ctx: ExtensionContext, source: "command" | "tool" | "runtime"): void => {
+    const current = getGoal(ctx);
+    pi.appendEntry(EXTENSION_NAME, goalClearEntry(current?.goalId ?? null, source));
+    continuationQueuedFor = null;
+    backgroundDrainTracker = null;
+    clearIdleContinuation();
+  };
+
+  const queueGoalContinuation = (goal: GoalSnapshot): void => {
+    if (goal.status !== "active" || continuationQueuedFor === goal.goalId) {
+      return;
+    }
+    clearIdleContinuation();
+    continuationQueuedFor = goal.goalId;
+    pi.sendMessage(
+      {
+        customType: EXTENSION_NAME,
+        content: continuationPrompt(goal),
+        display: false,
+        details: { kind: "continuation", goalId: goal.goalId },
+      },
+      { triggerTurn: true, deliverAs: "followUp" },
+    );
+  };
+
+  function clearIdleContinuation(): void {
+    if (idleContinuationTimer) {
+      clearTimeout(idleContinuationTimer);
+      idleContinuationTimer = undefined;
+    }
+    idleContinuationSignature = "";
+  }
+
+  const scheduleIdleContinuation = (
+    goal: GoalSnapshot,
+    ctx: ExtensionContext,
+    kind: "continuation" | "background-drained",
+    snapshot?: ActivitySnapshot,
+  ): void => {
+    if (WAKE_DISABLED || goal.status !== "active" || continuationQueuedFor === goal.goalId) {
+      return;
+    }
+    const signature = `${goal.goalId}:${kind}`;
+    if (idleContinuationTimer && idleContinuationSignature === signature) {
+      return;
+    }
+    clearIdleContinuation();
+    idleContinuationSignature = signature;
+    idleContinuationTimer = setTimeout(() => {
+      idleContinuationTimer = undefined;
+      idleContinuationSignature = "";
+      void sendIdleContinuationAfterAudit(goal.goalId, ctx, kind, snapshot);
+    }, IDLE_CONTINUATION_DELAY_MS);
+    idleContinuationTimer.unref?.();
+  };
+
+  const sendIdleContinuationAfterAudit = async (
+    goalId: string,
+    ctx: ExtensionContext,
+    kind: "continuation" | "background-drained",
+    priorSnapshot?: ActivitySnapshot,
+  ): Promise<void> => {
+    const goal = currentGoalSnapshot(ctx);
+    if (goal?.status !== "active" || goal.goalId !== goalId || continuationQueuedFor === goal.goalId || foregroundRunning) {
+      return;
+    }
+    const snapshot = await collectActivitySnapshot(ctx, providers.values(), foregroundRunning);
+    latestSnapshot = snapshot;
+    pi.events.emit(EVENT_ACTIVITY, snapshot);
+    if (snapshot.foregroundRunning || snapshot.backgroundRunning) {
+      return;
+    }
+
+    continuationQueuedFor = goal.goalId;
+    const content = kind === "background-drained"
+      ? "Background activity for the active goal is no longer running. Inspect any subagent callbacks or final results, then continue the completion audit before marking the goal complete.\n\n" +
+        continuationPrompt(goal)
+      : continuationPrompt(goal);
+    pi.sendMessage(
+      {
+        customType: EXTENSION_NAME,
+        content,
+        display: false,
+        details: kind === "background-drained"
+          ? { kind, snapshot: priorSnapshot ?? snapshot }
+          : { kind, goalId: goal.goalId },
+      },
+      { triggerTurn: true, deliverAs: "followUp" },
+    );
+  };
+
+  const startOrReplaceGoal = (
+    objective: string,
+    tokenBudget: number | null,
+    ctx: ExtensionContext,
+    source: "command",
+  ): GoalSnapshot => {
+    const objectiveError = validateObjective(objective);
+    if (objectiveError) {
+      throw new Error(objectiveError);
+    }
+    const budgetError = validateTokenBudget(tokenBudget);
+    if (budgetError) {
+      throw new Error(budgetError);
+    }
+    const goal = createGoalSnapshot(objective.trim(), tokenBudget);
+    setGoal(goal, ctx, source);
+    queueGoalContinuation(goal);
+    return goal;
+  };
+
+  const publishSnapshot = async (ctx: ExtensionContext): Promise<ActivitySnapshot> => {
+    const snapshot = await collectActivitySnapshot(ctx, providers.values(), foregroundRunning);
+    latestSnapshot = snapshot;
+    pi.events.emit(EVENT_ACTIVITY, snapshot);
+
+    const attention = terminalAttentionSignature(snapshot);
+    if (attention && attention !== lastAttentionSignature) {
+      lastAttentionSignature = attention;
+      pi.events.emit(EVENT_TERMINAL_ATTENTION, snapshot);
+    }
+
+    if (!WAKE_DISABLED) {
+      const goal = currentGoalSnapshot(ctx);
+      const wakePlan = planBackgroundDrainWake(backgroundDrainTracker, goal, snapshot);
+      backgroundDrainTracker = wakePlan.nextTracker;
+      if (goal?.status === "active" && wakePlan.wakeSignature) {
+        const wakeSignature = wakePlan.wakeSignature;
+        if (wakeSignature !== lastWakeSignature) {
+          lastWakeSignature = wakeSignature;
+          scheduleIdleContinuation(goal, ctx, "background-drained", snapshot);
+        }
+      }
+    }
+
+    if (snapshot.foregroundRunning || snapshot.backgroundRunning) {
+      clearIdleContinuation();
+    }
+
+    if (ctx.hasUI) {
+      const status = snapshot.backgroundRunning
+        ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
+        : undefined;
+      try {
+        ctx.ui.setStatus(EXTENSION_NAME, status);
+      } catch {
+        // UI status is best-effort only.
+      }
+    }
+
+    return snapshot;
+  };
+
+  const collectIfPossible = (): void => {
+    const ctx = currentCtx;
+    if (!ctx || collecting) {
+      return;
+    }
+    collecting = true;
+    void publishSnapshot(ctx).finally(() => {
+      collecting = false;
+    });
+  };
+
+  const startPolling = (): void => {
+    if (pollTimer) {
+      return;
+    }
+    pollTimer = setInterval(collectIfPossible, POLL_INTERVAL_MS);
+    pollTimer.unref?.();
+    collectIfPossible();
+  };
+
+  const stopPolling = (): void => {
+    if (!pollTimer) {
+      return;
+    }
+    clearInterval(pollTimer);
+    pollTimer = undefined;
+  };
+
+  const installGoalWidget = (ctx: ExtensionContext): void => {
+    if (!ctx.hasUI) {
+      return;
+    }
+    ctx.ui.setWidget(
+      EXTENSION_NAME,
+      (tui, theme) => {
+        const timer = setInterval(() => tui.requestRender(), 1_000);
+        timer.unref?.();
+        return {
+          dispose() {
+            clearInterval(timer);
+          },
+          invalidate() {},
+          render(width: number): string[] {
+            const goal = getGoal(ctx);
+            if (!goal) {
+              return [];
+            }
+            const fg = typeof theme?.fg === "function"
+              ? (color: string, value: string) => theme.fg(color as never, value)
+              : undefined;
+            return [renderGoalClockLine(goal, width, undefined, fg)];
+          },
+        };
+      },
+      { placement: "aboveEditor" },
+    );
+  };
+
+  pi.events.on(EVENT_REGISTER_PROVIDER, (provider) => {
+    const candidate = provider as Partial<BackgroundActivityProvider> | undefined;
+    if (!candidate || typeof candidate.id !== "string" || typeof candidate.getActivity !== "function") {
+      return;
+    }
+    providers.set(candidate.id, candidate as BackgroundActivityProvider);
+    collectIfPossible();
+  });
+
+  pi.registerCommand("goal", {
+    description: "Create, inspect, pause, resume, clear, or complete the active goal",
+    handler: async (args, ctx) => {
+      currentCtx = ctx;
+      const trimmed = args.trim();
+      const current = getGoal(ctx);
+
+      if (!trimmed) {
+        ctx.ui.notify(formatGoal(current), "info");
+        return;
+      }
+
+      if (trimmed === "pause") {
+        if (!current || current.status !== "active") {
+          ctx.ui.notify("Only active goals can be paused.", "warning");
+          return;
+        }
+        setGoal(goalWithStatus(current, "paused"), ctx, "command");
+        ctx.ui.notify("Goal paused.", "info");
+        return;
+      }
+
+      if (trimmed === "resume") {
+        if (!current || current.status !== "paused") {
+          ctx.ui.notify("Only paused goals can be resumed.", "warning");
+          return;
+        }
+        const goal = goalWithStatus(current, "active");
+        setGoal(goal, ctx, "command");
+        queueGoalContinuation(goal);
+        ctx.ui.notify("Goal resumed.", "info");
+        return;
+      }
+
+      if (trimmed === "clear") {
+        clearGoal(ctx, "command");
+        ctx.ui.notify("Goal cleared.", "info");
+        return;
+      }
+
+      if (trimmed === "complete") {
+        if (!current) {
+          ctx.ui.notify("No goal is set.", "warning");
+          return;
+        }
+        setGoal(goalWithStatus(current, "complete"), ctx, "command");
+        ctx.ui.notify("Goal marked complete.", "info");
+        return;
+      }
+
+      if (current && current.status !== "complete" && ctx.hasUI) {
+        const replace = await ctx.ui.confirm(
+          "Replace active goal?",
+          `Current goal: ${current.objective}`,
+        );
+        if (!replace) {
+          return;
+        }
+      }
+
+      try {
+        const goal = startOrReplaceGoal(trimmed, null, ctx, "command");
+        ctx.ui.notify(`Goal set: ${goal.objective}`, "info");
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "get_goal",
+    label: "Get Goal",
+    description: "Inspect the current pi-better-goal objective, status, and timing.",
+    promptSnippet: "Inspect the current goal, status, token budget, tokens used, active time, and total elapsed time.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const goal = getGoal(ctx);
+      return {
+        content: [{ type: "text", text: formatGoal(goal) }],
+        details: { goal, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "update_goal",
+    label: "Update Goal",
+    description: "Mark the current pi-better-goal objective complete after a completion audit.",
+    promptSnippet: "Mark the current Codex-style goal complete after verification.",
+    parameters: Type.Object({
+      status: Type.String({ description: "Only 'complete' is accepted." }),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const input = params as { status: string };
+      if (input.status !== "complete") {
+        return {
+          content: [{ type: "text", text: "Only status:'complete' is accepted." }],
+          details: { ok: false, goal: getGoal(ctx) },
+        };
+      }
+      const current = getGoal(ctx);
+      if (!current) {
+        return {
+          content: [{ type: "text", text: "No goal is set." }],
+          details: { ok: false, goal: null },
+        };
+      }
+      if (current.status === "complete") {
+        return {
+          content: [{ type: "text", text: "Goal already complete." }],
+          details: { ok: true, goal: current },
+        };
+      }
+      const goal = goalWithStatus(current, "complete");
+      setGoal(goal, ctx, "tool");
+      return {
+        content: [{ type: "text", text: "Goal marked complete." }],
+        details: { ok: true, goal },
+      };
+    },
+  });
+
+  pi.registerCommand("better-activity", {
+    description: "Show foreground/background activity known to pi-better-goal",
+    handler: async (_args, ctx) => {
+      currentCtx = ctx;
+      const snapshot = await publishSnapshot(ctx);
+      ctx.ui.notify(formatSnapshot(snapshot), snapshot.backgroundRunning ? "info" : "info");
+    },
+  });
+
+  pi.registerTool({
+    name: "get_background_activity",
+    label: "Get Background Activity",
+    description: "Inspect foreground/background activity known to pi-better-goal.",
+    promptSnippet: "Inspect active background work such as async subagents",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      currentCtx = ctx;
+      const snapshot = await publishSnapshot(ctx);
+      return {
+        content: [{ type: "text", text: formatSnapshot(snapshot) }],
+        details: snapshot,
+      };
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    currentCtx = ctx;
+    foregroundRunning = !ctx.isIdle();
+    pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
+    installGoalWidget(ctx);
+    startPolling();
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    currentCtx = ctx;
+    const goal = currentGoalSnapshot(ctx);
+    const snapshot = await publishSnapshot(ctx);
+    if (goal?.status !== "active") {
+      return;
+    }
+
+    const backgroundInstruction = snapshot.backgroundRunning
+      ? ` The goal still has delegated background work running (${summarizeActiveBackground(snapshot)}). Foreground idleness alone is not goal completion; do not mark the goal complete until delegated background work reaches a terminal state and its result or failure has been inspected.`
+      : "";
+    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}`,
+    };
+  });
+
+  pi.on("agent_start", async (_event, ctx) => {
+    currentCtx = ctx;
+    foregroundRunning = true;
+    clearIdleContinuation();
+    continuationQueuedFor = null;
+    await publishSnapshot(ctx);
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    currentCtx = ctx;
+    foregroundRunning = false;
+    const snapshot = await publishSnapshot(ctx);
+    const goal = getGoal(ctx);
+    if (goal?.status === "active" && !snapshot.backgroundRunning) {
+      scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
+    }
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    stopPolling();
+    foregroundRunning = false;
+    clearIdleContinuation();
+    currentCtx = undefined;
+    try {
+      ctx.ui.setStatus(EXTENSION_NAME, undefined);
+      ctx.ui.setWidget(EXTENSION_NAME, undefined);
+    } catch {
+      // Best-effort cleanup.
+    }
+  });
+}

package/src/subagents.ts

@@ -0,0 +1,134 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { BackgroundProviderSnapshot, BackgroundWorkItem } from "./types.js";
+
+export type SubagentRunStatus = "running" | "completed" | "failed" | "killed" | "orphaned" | "lost";
+export type SubagentEffectiveStatus = SubagentRunStatus | "exited";
+
+export interface SubagentRunMeta {
+  id: string;
+  name?: string;
+  status: SubagentRunStatus;
+  pid: number;
+  spawnPid: number;
+  model?: string;
+  cwd: string;
+  promptPreview: string;
+  startedAt: number;
+  endedAt?: number;
+  callback?: boolean;
+  batchId?: string;
+  batchName?: string;
+}
+
+export interface CollectSubagentActivityOptions {
+  baseDir?: string;
+  parentPid?: number;
+  processExists?: (pid: number) => boolean;
+}
+
+export function defaultSubagentBaseDir(): string {
+  return join(tmpdir(), "pi-better-subagents");
+}
+
+export function defaultProcessExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    return code === "EPERM";
+  }
+}
+
+export function effectiveSubagentStatus(
+  meta: Pick<SubagentRunMeta, "status" | "pid">,
+  processExists: (pid: number) => boolean = defaultProcessExists,
+): SubagentEffectiveStatus {
+  if (meta.status !== "running") {
+    return meta.status;
+  }
+  return processExists(meta.pid) ? "running" : "exited";
+}
+
+export function isCurrentParentSubagent(
+  meta: Pick<SubagentRunMeta, "spawnPid">,
+  parentPid = process.pid,
+): boolean {
+  return meta.spawnPid === parentPid;
+}
+
+export function readSubagentMetas(baseDir = defaultSubagentBaseDir()): SubagentRunMeta[] {
+  const runsDir = join(baseDir, "runs");
+  if (!existsSync(runsDir)) {
+    return [];
+  }
+
+  const metas: SubagentRunMeta[] = [];
+  for (const id of readdirSync(runsDir)) {
+    try {
+      const raw = readFileSync(join(runsDir, id, "meta.json"), "utf8");
+      const meta = JSON.parse(raw) as SubagentRunMeta;
+      if (typeof meta.id === "string" && typeof meta.status === "string") {
+        metas.push(meta);
+      }
+    } catch {
+      // Ignore partially-written or stale run directories.
+    }
+  }
+
+  return metas.sort((left, right) => right.startedAt - left.startedAt);
+}
+
+export function subagentStatusToItem(
+  meta: SubagentRunMeta,
+  status: SubagentEffectiveStatus,
+): BackgroundWorkItem {
+  const active = status === "running" || status === "orphaned";
+  const unhealthy = status === "orphaned";
+  const terminal = !active;
+  const attention = status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited";
+
+  const item: BackgroundWorkItem = {
+    id: meta.id,
+    status,
+    active,
+    unhealthy,
+    terminal,
+    attention,
+    startedAt: meta.startedAt,
+    details: {
+      callback: meta.callback !== false,
+      batchId: meta.batchId,
+      batchName: meta.batchName,
+      model: meta.model,
+      cwd: meta.cwd,
+      promptPreview: meta.promptPreview,
+    },
+  };
+  if (meta.name !== undefined) {
+    item.label = meta.name;
+  }
+  if (meta.endedAt !== undefined) {
+    item.endedAt = meta.endedAt;
+  }
+  return item;
+}
+
+export function collectSubagentActivity(
+  options: CollectSubagentActivityOptions = {},
+): BackgroundProviderSnapshot {
+  const parentPid = options.parentPid ?? process.pid;
+  const processExists = options.processExists ?? defaultProcessExists;
+  const metas = readSubagentMetas(options.baseDir).filter((meta) =>
+    isCurrentParentSubagent(meta, parentPid),
+  );
+
+  return {
+    providerId: "subagents",
+    label: "Subagents",
+    items: metas.map((meta) => subagentStatusToItem(meta, effectiveSubagentStatus(meta, processExists))),
+  };
+}

package/src/types.ts

@@ -0,0 +1,81 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const EXTENSION_NAME = "pi-better-goal";
+export const EXTENSION_VERSION = "0.1.0";
+
+export const EVENT_READY = "pi-better-goal:ready";
+export const EVENT_REGISTER_PROVIDER = "pi-better-goal:register-provider";
+export const EVENT_ACTIVITY = "pi-better-goal:activity";
+export const EVENT_TERMINAL_ATTENTION = "pi-better-goal:terminal-attention";
+
+export type ActivityCategory =
+  | "foreground-running"
+  | "background-running"
+  | "idle-waiting"
+  | "complete";
+
+export type BackgroundWorkStatus =
+  | "running"
+  | "orphaned"
+  | "completed"
+  | "failed"
+  | "killed"
+  | "lost"
+  | "exited"
+  | string;
+
+export interface BackgroundWorkItem {
+  id: string;
+  label?: string;
+  status: BackgroundWorkStatus;
+  active: boolean;
+  unhealthy?: boolean;
+  terminal?: boolean;
+  attention?: boolean;
+  startedAt?: number;
+  endedAt?: number;
+  details?: Record<string, unknown>;
+}
+
+export interface BackgroundProviderSnapshot {
+  providerId: string;
+  label?: string;
+  items: BackgroundWorkItem[];
+}
+
+export interface BackgroundActivityProvider {
+  id: string;
+  label?: string;
+  getActivity(ctx: ExtensionContext): BackgroundProviderSnapshot | Promise<BackgroundProviderSnapshot>;
+}
+
+export interface ActivitySnapshot {
+  version: 1;
+  category: ActivityCategory;
+  foregroundRunning: boolean;
+  backgroundRunning: boolean;
+  activeBackgroundCount: number;
+  unhealthyBackgroundCount: number;
+  terminalAttentionCount: number;
+  providers: BackgroundProviderSnapshot[];
+  generatedAt: number;
+}
+
+export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
+
+export interface GoalUsage {
+  tokensUsed: number;
+  activeSeconds: number;
+}
+
+export interface GoalSnapshot {
+  goalId: string;
+  objective: string;
+  status: GoalStatus;
+  tokenBudget: number | null;
+  usage: GoalUsage;
+  createdAt: number;
+  updatedAt: number;
+  activeStartedAt: number | null;
+  completedAt: number | null;
+}