pi-better-goal 0.10.4 → 0.12.0

package/package.json

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

package/src/index.ts

@@ -6,6 +6,7 @@ import { Type } from "typebox";
 import { commandAvailable, commandInvocation, resolveGoalCommand } from "./command-binding.js";
 import { goalPreferencesPath, readGoalPreferences, writeGoalPreference, type GoalPreferences } from "./preferences.js";
 import { createGoalSettingsPage } from "./settings-page.js";
+import { OPERATION_RESUME_ADMISSION, operationOwnerMatches, type OperationResumeRequest } from "./operation-admission.js";
 
 import {
   collectActivitySnapshot,
@@ -38,9 +39,10 @@ import {
   renderGoalClockLine,
 } from "./goal-clock.js";
 import { createRenderScheduler } from "./shared-render-scheduler.js";
+import { initializeNavigatorPanels, setNavigatorPanel } from "./shared-navigator-panels.js";
 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 { completionGate, pauseGate, schedulerWaitUntil, operationResumeSchedulerGate } from "./workflow-gates.js";
 import { workflowRehydrateMessage, WORKFLOW_REHYDRATE_MESSAGE_TYPE } from "./rehydrate.js";
 import { requestTaskContext } from "./task-context.js";
 import {
@@ -301,6 +303,7 @@ function formatSnapshot(snapshot: ActivitySnapshot): string {
 }
 
 export default function (pi: ExtensionAPI): void {
+  initializeNavigatorPanels(pi);
   const providers = new Map<string, BackgroundActivityProvider>();
   const providerUnsubscribers = new Map<string, () => void>();
   providers.set("subagents", {
@@ -311,6 +314,7 @@ export default function (pi: ExtensionAPI): void {
 
   let currentCtx: ExtensionContext | undefined;
   let executionGeneration = 0;
+  let operationAdmissionRevision = 0;
   let agentGeneration = -1;
   let turnGeneration = 0;
   let escapeAbortSuppression: { session: number; turn: number; execution: number } | undefined;
@@ -793,7 +797,8 @@ export default function (pi: ExtensionAPI): void {
     if (!ctx.hasUI) {
       return;
     }
-    ctx.ui.setWidget(
+    setNavigatorPanel(
+      ctx,
       EXTENSION_NAME,
       (tui, theme) => {
         const inputIsEditor = (): boolean => {
@@ -859,6 +864,51 @@ export default function (pi: ExtensionAPI): void {
     );
   };
 
+  const unsubscribeOperationAdmission = pi.events.on(OPERATION_RESUME_ADMISSION, (value) => {
+    const request = value as Partial<OperationResumeRequest> | undefined;
+    if (request?.version !== 1 || !request.owner || typeof request.reply !== "function") return;
+    const ctx = currentCtx;
+    const revision = executionGeneration;
+    const preferencesRevision = operationAdmissionRevision;
+    const reply = request.reply;
+    const held = (reason: string) => reply({ allowed: false, reason, revision: executionGeneration });
+    if (!operationOwnerMatches(ctx, request.owner) || !ctx) { held("Owning parent session or branch is inactive"); return; }
+    const goal = getGoal(ctx);
+    if ((request.owner.goalId ?? null) !== (goal?.goalId ?? null)) { held("Owning Goal is no longer current"); return; }
+    if (goal && !preferences.autoContinue) { held("Goal automatic continuation is disabled"); return; }
+    if (goal && !isPokeable(goal)) { held("Goal is not active"); return; }
+    if (goal && currentPermissionHold(ctx, goal.goalId).blockers.length) { held("Goal has an active permission hold"); return; }
+    if (goal && currentContinuationState(ctx, goal.goalId)?.blocked) { held("Goal continuation requires human resume"); return; }
+    if (goal && !boundCommandReady(goal, ctx)) { held("Bound workflow is not ready"); return; }
+    const workflow = getWorkflow(ctx);
+    void (workflow ? operationResumeSchedulerGate(ctx.sessionManager.getBranch(), workflow) : Promise.resolve({ ok: true as const, waitUntil: undefined })).then((gate) => {
+      if (ctx !== currentCtx || revision !== executionGeneration || preferencesRevision !== operationAdmissionRevision || !operationOwnerMatches(currentCtx, request.owner!)) {
+        held("Parent execution changed during resume admission"); return;
+      }
+      const latest = getGoal(ctx);
+      if ((request.owner!.goalId ?? null) !== (latest?.goalId ?? null)) { held("Owning Goal changed during resume admission"); return; }
+      if (latest && !preferences.autoContinue) { held("Goal automatic continuation is disabled"); return; }
+      if (latest && (!isPokeable(latest) || currentPermissionHold(ctx, latest.goalId).blockers.length || currentContinuationState(ctx, latest.goalId)?.blocked)) {
+        held("Goal became held during resume admission"); return;
+      }
+      if (!gate.ok) { held(gate.reason); return; }
+      if (gate.waitUntil && gate.waitUntil > Date.now()) { held("Workflow scheduler is waiting"); return; }
+      // An in-process capability lets the dispatcher validate this admission
+      // after its last await and immediately before releasing execution.
+      const isCurrent = (): boolean => {
+        if (ctx !== currentCtx || revision !== executionGeneration || preferencesRevision !== operationAdmissionRevision
+          || !operationOwnerMatches(currentCtx, request.owner!)) return false;
+        const active = getGoal(ctx);
+        if ((request.owner!.goalId ?? null) !== (active?.goalId ?? null)) return false;
+        if (JSON.stringify(getWorkflow(ctx)) !== JSON.stringify(workflow)) return false;
+        return !active || (preferences.autoContinue && isPokeable(active)
+          && !currentPermissionHold(ctx, active.goalId).blockers.length
+          && !currentContinuationState(ctx, active.goalId)?.blocked && boundCommandReady(active, ctx));
+      };
+      reply({ allowed: true, revision, isCurrent });
+    }, () => held("Workflow admission evidence is unavailable"));
+  });
+
   pi.events.on(EVENT_REGISTER_PROVIDER, (provider) => {
     const candidate = provider as Partial<BackgroundActivityProvider> | undefined;
     if (!candidate || typeof candidate.id !== "string" || typeof candidate.getActivity !== "function") {
@@ -877,6 +927,7 @@ export default function (pi: ExtensionAPI): void {
   const changePreference = async (ctx: ExtensionCommandContext, key: keyof GoalPreferences, enabled: boolean): Promise<void> => {
     const previous = preferences;
     preferences = writeGoalPreference(key, enabled);
+    operationAdmissionRevision += 1;
     if (previous.autoContinue !== preferences.autoContinue) clearIdleContinuation();
     syncResumeTool(getGoal(ctx));
     if (!previous.autoContinue && preferences.autoContinue) {
@@ -1573,6 +1624,7 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("session_shutdown", async (_event, ctx) => {
     if (typeof unsubscribeSettingsRequest === "function") unsubscribeSettingsRequest();
+    if (typeof unsubscribeOperationAdmission === "function") unsubscribeOperationAdmission();
 
     executionGeneration += 1;
     sessionGeneration += 1;
@@ -1589,7 +1641,7 @@ export default function (pi: ExtensionAPI): void {
     latestSnapshot = null;
     collectionPending = false;
     try {
-      ctx.ui.setWidget(EXTENSION_NAME, undefined);
+      setNavigatorPanel(ctx, EXTENSION_NAME, undefined);
     } catch {
       // Best-effort cleanup.
     }

package/src/operation-admission.ts

@@ -0,0 +1,16 @@
+import type {ExtensionContext} from '@earendil-works/pi-coding-agent';
+
+export const OPERATION_RESUME_ADMISSION='pi-better-goal:operation-resume-admission';
+export interface OperationResumeOwner {sessionId:string;workspace:string;branchId?:string|null;goalId?:string|null}
+export interface OperationResumeGate {allowed:boolean;reason?:string;revision:number;isCurrent?:()=>boolean}
+export interface OperationResumeRequest {version:1;owner:OperationResumeOwner;reply:(gate:OperationResumeGate)=>void}
+
+/** A recorded branch anchor remains valid on descendants, not on an abandoned fork. */
+export function operationOwnerMatches(ctx:ExtensionContext|undefined,owner:OperationResumeOwner):boolean {
+ if(!ctx||ctx.cwd!==owner.workspace)return false;
+ try{
+  if(ctx.sessionManager.getSessionId()!==owner.sessionId)return false;
+  if(owner.branchId&&!ctx.sessionManager.getBranch().some(entry=>entry.id===owner.branchId))return false;
+  return true;
+ }catch{return false;}
+}

package/src/shared-navigator-panels.ts

@@ -0,0 +1,250 @@
+// Generated from packages/navigator/panels.ts. Do not edit directly.
+import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { randomUUID } from "node:crypto";
+import { readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.js";
+
+export const NAVIGATOR_PANEL_WIDGET_KEY = "background-work-list";
+export const NAVIGATOR_ENTRY_TYPE = "pi-better-harness-navigator-panels";
+export const NAVIGATOR_STICKY_SETTING_ID = "navigator-sticky";
+type MouseEvent = { type: string; button: string; x: number; y: number; width: number; shift?: boolean; alt?: boolean; ctrl?: boolean };
+type PanelComponent = Component & { dispose?(): void; handleMouse?(event: MouseEvent): { handled: true; render: boolean } | undefined };
+export type NavigatorPanelFactory = (tui: TUI, theme: Theme) => PanelComponent;
+type Panel = { factory: NavigatorPanelFactory; component?: PanelComponent | undefined };
+type Preference = { version: 1; sticky: boolean };
+type Owner = { pi: ExtensionAPI; stop?: (() => void) | undefined };
+type State = {
+  panels: Map<string, Panel>;
+  owners: Map<ExtensionAPI, Owner>;
+  ctx?: ExtensionContext | undefined;
+  ui?: ExtensionContext["ui"] | undefined;
+  pi?: ExtensionAPI | undefined;
+  sticky: boolean;
+  mounted: boolean;
+  tui?: TUI | undefined;
+  theme?: Theme | undefined;
+  anchor?: string | undefined;
+  pendingAnchor: boolean;
+  generation: number;
+  ranges: Array<{ start: number; end: number; component: PanelComponent }>;
+  control?: { id: string; label: string; values: string[]; get(): string; change(value: string, ctx: ExtensionContext): void } | undefined;
+};
+const KEY = Symbol.for("pi-better-harness.navigator-panels.state");
+function state(): State {
+  const global = globalThis as typeof globalThis & { [KEY]?: State };
+  return global[KEY] ??= { panels: new Map(), owners: new Map(), sticky: true, mounted: false, pendingAnchor: false, generation: 0, ranges: [] };
+}
+function parsePreference(value: unknown): Preference {
+  if (value === undefined) return { version: 1, sticky: true };
+  const preference = value as Partial<Preference> | null;
+  if (!preference || preference.version !== 1 || typeof preference.sticky !== "boolean") {
+    throw new Error("Navigator preference must contain version 1 and a boolean sticky value.");
+  }
+  return { version: 1, sticky: preference.sticky };
+}
+function canScroll(pi: ExtensionAPI | undefined): boolean {
+  return typeof pi?.registerEntryRenderer === "function" && typeof pi?.appendEntry === "function";
+}
+function isTui(ctx: ExtensionContext | undefined): ctx is ExtensionContext {
+  return ctx?.mode === "tui" && ctx.hasUI && typeof ctx.ui?.setWidget === "function";
+}
+function disposePanels(s: State): void {
+  for (const panel of s.panels.values()) {
+    try { panel.component?.dispose?.(); } catch { /* stale UI cleanup is best effort */ }
+    panel.component = undefined;
+  }
+  s.ranges = [];
+}
+function orderedPanels(s: State): Panel[] {
+  const rank = (key: string) => key === "pi-better-goal" ? 0 : key === "pi-better-plan" ? 1 : 2;
+  return [...s.panels.entries()].sort(([a], [b]) => rank(a) - rank(b)).map(([, panel]) => panel);
+}
+function buildPanels(s: State): void {
+  if (!s.tui || !s.theme) return;
+  for (const panel of orderedPanels(s)) panel.component ??= panel.factory(s.tui, s.theme);
+}
+function renderPanels(s: State, width: number): string[] {
+  buildPanels(s);
+  const lines: string[] = [];
+  s.ranges = [];
+  for (const panel of orderedPanels(s)) {
+    if (!panel.component) continue;
+    const rendered = panel.component.render(width);
+    s.ranges.push({ start: lines.length, end: lines.length + rendered.length, component: panel.component });
+    lines.push(...rendered);
+  }
+  return lines;
+}
+function mouse(s: State, event: MouseEvent) {
+  const range = s.ranges.find(range => event.y >= range.start && event.y < range.end);
+  return range?.component.handleMouse?.({ ...event, y: event.y - range.start });
+}
+function restoreAnchor(ctx: ExtensionContext): string | undefined {
+  let anchor: string | undefined;
+  for (const entry of ctx.sessionManager?.getBranch?.() ?? []) {
+    if (entry.type !== "custom" || entry.customType !== NAVIGATOR_ENTRY_TYPE) continue;
+    const data = entry.data as { version?: unknown; anchor?: unknown } | undefined;
+    if (data?.version === 1 && typeof data.anchor === "string") anchor = data.anchor;
+  }
+  return anchor;
+}
+function appendAnchor(s: State): void {
+  if (s.sticky || s.anchor || !canScroll(s.pi)) return;
+  const anchor = randomUUID();
+  s.anchor = anchor;
+  try { s.pi!.appendEntry(NAVIGATOR_ENTRY_TYPE, { version: 1, anchor }); }
+  catch (error) { s.anchor = undefined; throw error; }
+}
+function scheduleAnchor(s: State): void {
+  if (s.anchor || s.pendingAnchor || s.sticky) return;
+  s.pendingAnchor = true;
+  const generation = s.generation;
+  // Session writes cannot run inside a component render. Empty sessions stay untouched.
+  queueMicrotask(() => {
+    if (generation !== s.generation) return;
+    s.pendingAnchor = false;
+    if (!s.sticky && s.panels.size) appendAnchor(s);
+  });
+}
+function clearHost(s: State): void {
+  s.generation++;
+  s.pendingAnchor = false;
+  try {
+    if (s.mounted && isTui(s.ctx)) s.ctx.ui.setWidget(NAVIGATOR_PANEL_WIDGET_KEY, undefined);
+  } catch { /* an old session context may already be detached */ }
+  disposePanels(s);
+  s.mounted = false;
+  s.tui = undefined;
+  s.theme = undefined;
+}
+function adoptContext(s: State, ctx: ExtensionContext): void {
+  if (s.ui && s.ui !== ctx.ui) {
+    clearHost(s);
+    s.panels.clear();
+    s.anchor = undefined;
+  }
+  s.ctx = ctx;
+  s.ui = ctx.ui;
+}
+function mountHost(s: State): void {
+  if (!isTui(s.ctx) || s.mounted || !s.panels.size) return;
+  s.mounted = true;
+  s.ctx.ui.setWidget(NAVIGATOR_PANEL_WIDGET_KEY, (tui, theme) => {
+    if (s.tui !== tui || s.theme !== theme) disposePanels(s);
+    s.tui = tui;
+    s.theme = theme;
+    buildPanels(s);
+    return {
+      render(width: number) {
+        const lines = renderPanels(s, width);
+        if (s.sticky) return lines;
+        if (lines.length) scheduleAnchor(s);
+        return [];
+      },
+      handleMouse: (event: MouseEvent) => s.sticky ? mouse(s, event) : undefined,
+      invalidate() {
+        for (const panel of s.panels.values()) panel.component?.invalidate();
+      },
+      dispose() { disposePanels(s); s.mounted = false; },
+    };
+  }, { placement: "aboveEditor" });
+}
+function changeSticky(value: string, ctx: ExtensionContext): void {
+  if (value !== "On" && value !== "Off") throw new Error("Sticky navigator expects On or Off.");
+  const s = state();
+  if (value === "Off" && !canScroll(s.pi)) {
+    throw new Error("Scrolling navigator requires a Pi version with registerEntryRenderer support.");
+  }
+  updateHarnessSetting("navigator", current => {
+    parsePreference(current);
+    return { version: 1, sticky: value === "On" };
+  });
+  adoptContext(s, ctx);
+  if (s.sticky && value === "Off") s.anchor = undefined;
+  s.sticky = value === "On";
+  refreshNavigatorPanels(ctx);
+}
+export function initializeNavigatorPanels(pi: ExtensionAPI): void {
+  const s = state();
+  if (s.owners.has(pi)) return;
+  s.pi = pi;
+  try { s.sticky = parsePreference(readHarnessSetting("navigator")).sticky; }
+  catch { s.sticky = true; }
+  if (!canScroll(pi)) s.sticky = true;
+  if (canScroll(pi)) pi.registerEntryRenderer(NAVIGATOR_ENTRY_TYPE, (entry) => {
+    const data = entry.data as { version?: number; anchor?: string } | undefined;
+    if (data?.version !== 1 || !data.anchor) return undefined;
+    // Pi reconstructs chat before session_start restores the visible branch.
+    // Keep the component mounted and resolve its active anchor at render time.
+    return {
+      render: width => !s.sticky && data.anchor === s.anchor ? renderPanels(s, width) : [],
+      handleMouse: event => !s.sticky && data.anchor === s.anchor ? mouse(s, event) : undefined,
+      invalidate() { for (const panel of s.panels.values()) panel.component?.invalidate(); },
+    } as PanelComponent;
+  });
+  s.control ??= {
+    id: NAVIGATOR_STICKY_SETTING_ID, label: "Sticky navigator", values: ["On", "Off"],
+    get: () => state().sticky ? "On" : "Off", change: changeSticky,
+  };
+  const owner: Owner = { pi };
+  s.owners.set(pi, owner);
+  // Use one stable contribution callback across vendored copies, but each owner
+  // cleans up its own event subscription when its extension is unloaded.
+  const register = () => pi.events?.emit?.("harness-settings:register", s.control);
+  owner.stop = pi.events?.on?.("harness-settings:request", register);
+  register();
+  pi.on("session_start", (_event, ctx) => {
+    adoptContext(s, ctx);
+    s.anchor = restoreAnchor(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    adoptContext(s, ctx);
+    s.anchor = restoreAnchor(ctx);
+    refreshNavigatorPanels(ctx);
+  });
+  pi.on("session_shutdown", () => {
+    owner.stop?.();
+    s.owners.delete(pi);
+    if (s.owners.size) return;
+    clearHost(s);
+    s.panels.clear();
+    s.anchor = undefined;
+    s.ctx = undefined;
+    s.ui = undefined;
+    s.pi = undefined;
+  });
+}
+export function setNavigatorPanel(
+  ctx: ExtensionContext, key: string, content: NavigatorPanelFactory | undefined,
+  _options?: { placement?: "aboveEditor" | "belowEditor" },
+): void {
+  const s = state();
+  if (!isTui(ctx)) return;
+  adoptContext(s, ctx);
+  s.panels.get(key)?.component?.dispose?.();
+  if (content) s.panels.set(key, { factory: content });
+  else s.panels.delete(key);
+  if (!s.panels.size) { clearHost(s); return; }
+  mountHost(s);
+  buildPanels(s);
+  s.tui?.requestRender?.();
+}
+export function refreshNavigatorPanels(ctx?: ExtensionContext): void {
+  const s = state();
+  if (ctx) adoptContext(s, ctx);
+  mountHost(s);
+  s.tui?.requestRender?.(true);
+}
+export function __resetNavigatorPanelsForTests(): void {
+  const s = state();
+  clearHost(s);
+  for (const owner of s.owners.values()) owner.stop?.();
+  s.owners.clear();
+  s.panels.clear();
+  s.pi = undefined;
+  s.ctx = undefined;
+  s.ui = undefined;
+  s.anchor = undefined;
+  s.sticky = true;
+  s.control = undefined;
+}

package/src/workflow-gates.ts

@@ -262,6 +262,21 @@ export function waitUntil(due: readonly SchedulerAction[]): number | undefined {
   return times.length > 0 ? Math.min(...times) : undefined;
 }
 
+export type OperationResumeSchedulerGate = { ok: true; waitUntil: number | undefined } | { ok: false; reason: string };
+
+/** Automatic worker admission cannot treat unavailable workflow evidence as permission. */
+export async function operationResumeSchedulerGate(
+  entries: Iterable<EntryLike>,
+  owner: WorkflowOwner,
+  options: { timeoutMs?: number } = {},
+): Promise<OperationResumeSchedulerGate> {
+  const located = locateRun(entries, owner);
+  if ("warning" in located) return { ok: false, reason: located.warning };
+  const run = await runScheduler(located.script, located.runDir, options.timeoutMs);
+  if (!run.ok) return { ok: false, reason: `Workflow admission evidence unavailable: ${run.reason}` };
+  return { ok: true, waitUntil: waitUntil(run.due) };
+}
+
 /** When the bound run next wants a continuation, or undefined when it is not only waiting. */
 export async function schedulerWaitUntil(
   entries: Iterable<EntryLike>,