@kky42/pi-goal 1.0.0

package/src/goal-runtime-event-handler-types.ts

@@ -0,0 +1,166 @@
+import type {
+  AgentEndEvent,
+  BeforeAgentStartEvent,
+  ContextEvent,
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionEvent,
+  ExtensionHandler,
+  InputEvent,
+  InputEventResult,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
+  SessionShutdownEvent,
+  SessionStartEvent,
+  SessionTreeEvent,
+  TurnEndEvent,
+  TurnStartEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import type { GoalRuntimeState } from "./goal-runtime-state.js";
+import type { GoalStateController } from "./goal-state-controller.js";
+import type { AssistantErrorMessage } from "./recovery.js";
+
+export type ContextEventResult = { messages?: ContextEvent["messages"] };
+export type MessageStartEvent = Extract<ExtensionEvent, { type: "message_start" }>;
+export type ToolExecutionEndEvent = Extract<ExtensionEvent, { type: "tool_execution_end" }>;
+
+export interface GoalRuntimeEventHandlers {
+  onInput: ExtensionHandler<InputEvent, InputEventResult>;
+  onContext: ExtensionHandler<ContextEvent, ContextEventResult | undefined>;
+  onSessionStart: ExtensionHandler<SessionStartEvent>;
+  onSessionTree: ExtensionHandler<SessionTreeEvent>;
+  onBeforeAgentStart: ExtensionHandler<BeforeAgentStartEvent, undefined>;
+  onMessageStart: ExtensionHandler<MessageStartEvent>;
+  onTurnStart: ExtensionHandler<TurnStartEvent>;
+  onToolExecutionEnd: ExtensionHandler<ToolExecutionEndEvent>;
+  onTurnEnd: ExtensionHandler<TurnEndEvent>;
+  onAgentEnd: ExtensionHandler<AgentEndEvent>;
+  onSessionBeforeCompact: ExtensionHandler<SessionBeforeCompactEvent>;
+  onSessionCompact: ExtensionHandler<SessionCompactEvent>;
+  onSessionShutdown: ExtensionHandler<SessionShutdownEvent>;
+}
+
+export interface GoalRuntimeStatusPort {
+  refreshUi: (ctx: ExtensionContext) => void;
+  stopStatusRefresh: () => void;
+}
+
+export interface GoalRuntimeContinuationPort {
+  bindPassthroughContinuationInputToTurn: (turnIndex: number) => void;
+  clearContinuationState: () => void;
+  clearContinuationStateFor: (goalId: string) => void;
+  clearContinuationTimer: () => void;
+  clearPassthroughContinuationInput: () => void;
+  continuationGoalIdFromRuntimePrompt: (prompt: string) => string | null;
+  notePassthroughContinuationInput: (input: string) => void;
+  requestContinuation: (ctx: ExtensionContext) => void;
+}
+
+export interface GoalAccountingPort {
+  accountProgress: (
+    ctx: ExtensionContext,
+    includeActiveElapsed: boolean,
+    completedTurnTokens: number,
+    forceFlush?: boolean,
+  ) => void;
+  beginAccounting: () => void;
+}
+
+export interface RecoveryRuntimePort {
+  finishSuccessfulAssistantTurn: (
+    message: TurnEndEvent["message"],
+    ctx: ExtensionContext,
+    options: { continueGoal: boolean },
+  ) => void;
+  handlePersistentAssistantError: (message: AssistantErrorMessage, ctx: ExtensionContext) => void;
+  handleSilentContextOverflow: (ctx: ExtensionContext) => void;
+  onSessionCompact: () => void;
+  onUserInput: () => void;
+}
+
+export interface StaleQueuedWorkEffectContext {
+  status: GoalRuntimeStatusPort;
+  clearActiveAccounting: () => void;
+}
+
+export interface GoalRuntimeInputContextHandlerContext extends StaleQueuedWorkEffectContext {
+  runtimeState: Pick<GoalRuntimeState, "currentTurnIndex" | "staleQueuedWorkGuard">;
+  stateController: Pick<
+    GoalStateController,
+    "getGoal" | "isCurrentActiveGoalId" | "persistHostOverflowUserReset"
+  >;
+  continuation: GoalRuntimeContinuationPort;
+  recoveryRuntime: Pick<RecoveryRuntimePort, "onUserInput">;
+  resetErrorRecovery: () => void;
+}
+
+export interface GoalRuntimeTurnHandlerContext extends StaleQueuedWorkEffectContext {
+  runtimeState: Pick<GoalRuntimeState, "currentTurnIndex" | "staleQueuedWorkGuard">;
+  stateController: Pick<
+    GoalStateController,
+    "beginOverflowRecovery" | "flushGoalPersistence" | "maybeFlushRuntimePersistence" | "pauseForAbort"
+  >;
+  continuation: Pick<GoalRuntimeContinuationPort, "bindPassthroughContinuationInputToTurn">;
+  goalAccounting: GoalAccountingPort;
+  recoveryRuntime: Pick<RecoveryRuntimePort, "finishSuccessfulAssistantTurn">;
+}
+
+export interface GoalRuntimeAgentHandlerContext extends StaleQueuedWorkEffectContext {
+  runtimeState: Pick<GoalRuntimeState, "staleQueuedWorkGuard">;
+  stateController: Pick<GoalStateController, "beginOverflowRecovery" | "flushGoalPersistence" | "pauseForAbort">;
+  continuation: Pick<
+    GoalRuntimeContinuationPort,
+    "clearPassthroughContinuationInput" | "requestContinuation"
+  >;
+  goalAccounting: Pick<GoalAccountingPort, "accountProgress">;
+  recoveryRuntime: Pick<
+    RecoveryRuntimePort,
+    "handlePersistentAssistantError" | "handleSilentContextOverflow"
+  >;
+  resetErrorRecovery: () => void;
+}
+
+export interface GoalRuntimeSessionHandlerContext extends StaleQueuedWorkEffectContext {
+  runtimeState: Pick<GoalRuntimeState, "recoveryState" | "staleQueuedWorkGuard">;
+  stateController: Pick<
+    GoalStateController,
+    "applyGoalTransition" | "flushGoalPersistence" | "getGoal" | "reloadFromSession" | "resumePausedGoal"
+  >;
+  continuation: Pick<
+    GoalRuntimeContinuationPort,
+    "clearContinuationTimer" | "clearPassthroughContinuationInput" | "requestContinuation"
+  >;
+  goalAccounting: GoalAccountingPort;
+  recoveryRuntime: Pick<RecoveryRuntimePort, "onSessionCompact">;
+  resetErrorRecovery: () => void;
+}
+
+export interface GoalRuntimeOverflowRecoveryContext {
+  stateController: Pick<GoalStateController, "beginOverflowRecovery">;
+  recoveryRuntime: Pick<
+    RecoveryRuntimePort,
+    "handlePersistentAssistantError" | "handleSilentContextOverflow"
+  >;
+}
+
+export interface GoalRuntimeEventContext {
+  pi: ExtensionAPI;
+  runtimeState: GoalRuntimeState;
+  stateController: GoalStateController;
+  continuation: GoalRuntimeContinuationPort;
+  goalAccounting: GoalAccountingPort;
+  recoveryRuntime: RecoveryRuntimePort;
+  status: GoalRuntimeStatusPort;
+  clearActiveAccounting: () => void;
+  resetErrorRecovery: () => void;
+}
+
+export type QueuedGoalWorkMessage = {
+  role: string;
+  customType?: string;
+  details?: unknown;
+  content?: unknown;
+};
+
+export type QueuedGoalWorkMessageIdResolver = (message: QueuedGoalWorkMessage) => string | null;

package/src/goal-runtime-event-handlers.ts

@@ -0,0 +1,31 @@
+import { createAgentEventHandlers } from "./goal-runtime-agent-handlers.js";
+import { createInputContextEventHandlers } from "./goal-runtime-input-context-handlers.js";
+import { createSessionEventHandlers } from "./goal-runtime-session-handlers.js";
+import { createTurnEventHandlers } from "./goal-runtime-turn-handlers.js";
+import { createQueuedGoalWorkMessageIdResolver } from "./goal-runtime-event-utils.js";
+import type {
+  GoalRuntimeEventContext,
+  GoalRuntimeEventHandlers,
+} from "./goal-runtime-event-handler-types.js";
+
+export type {
+  ContextEventResult,
+  GoalRuntimeEventHandlers,
+  MessageStartEvent,
+  ToolExecutionEndEvent,
+} from "./goal-runtime-event-handler-types.js";
+
+export function createGoalRuntimeEventHandlers(
+  context: GoalRuntimeEventContext,
+): GoalRuntimeEventHandlers {
+  const queuedGoalWorkMessageIdForRuntime = createQueuedGoalWorkMessageIdResolver(
+    context.continuation,
+  );
+
+  return {
+    ...createInputContextEventHandlers(context, queuedGoalWorkMessageIdForRuntime),
+    ...createTurnEventHandlers(context),
+    ...createAgentEventHandlers(context),
+    ...createSessionEventHandlers(context),
+  };
+}

package/src/goal-runtime-event-utils.ts

@@ -0,0 +1,93 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type {
+  GoalRuntimeContinuationPort,
+  GoalRuntimeOverflowRecoveryContext,
+  QueuedGoalWorkMessage,
+  QueuedGoalWorkMessageIdResolver,
+  StaleQueuedWorkEffectContext,
+} from "./goal-runtime-event-handler-types.js";
+import { extensionQueuedGoalWorkMessageIdForRuntime } from "./queued-goal-work.js";
+import {
+  isAssistantContextOverflow,
+  isContextOverflowError,
+  isErrorAssistantMessage,
+  type AssistantErrorMessage,
+} from "./recovery.js";
+import type { StaleQueuedWorkEffect, StaleQueuedWorkPlan } from "./stale-queued-work-guard.js";
+
+export function applyStaleQueuedWorkEffects(
+  effects: readonly StaleQueuedWorkEffect[],
+  ctx: ExtensionContext,
+  context: StaleQueuedWorkEffectContext,
+): void {
+  for (const effect of effects) {
+    switch (effect.type) {
+      case "clearAccounting":
+        context.clearActiveAccounting();
+        break;
+      case "refreshUi":
+        context.status.refreshUi(ctx);
+        break;
+      case "abort":
+        ctx.abort();
+        break;
+      default: {
+        const _exhaustive: never = effect;
+        throw new Error(`Unhandled stale queued-work effect: ${String(_exhaustive)}`);
+      }
+    }
+  }
+}
+
+export function runStaleQueuedWorkPlan(
+  plan: StaleQueuedWorkPlan,
+  ctx: ExtensionContext,
+  context: StaleQueuedWorkEffectContext,
+): boolean {
+  applyStaleQueuedWorkEffects(plan.effects, ctx, context);
+  return plan.skip;
+}
+
+export function createQueuedGoalWorkMessageIdResolver(
+  continuation: GoalRuntimeContinuationPort,
+): QueuedGoalWorkMessageIdResolver {
+  return (message: QueuedGoalWorkMessage): string | null =>
+    extensionQueuedGoalWorkMessageIdForRuntime(
+      message,
+      continuation.continuationGoalIdFromRuntimePrompt,
+    );
+}
+
+export function getContextWindow(ctx: ExtensionContext): number {
+  return ctx.model?.contextWindow ?? 0;
+}
+
+export function recordAssistantContextOverflow(
+  message: AssistantErrorMessage,
+  ctx: ExtensionContext,
+  context: GoalRuntimeOverflowRecoveryContext,
+): boolean {
+  if (!isAssistantContextOverflow(message, getContextWindow(ctx))) {
+    return false;
+  }
+
+  context.stateController.beginOverflowRecovery(ctx);
+  if (isErrorAssistantMessage(message)) {
+    context.recoveryRuntime.handlePersistentAssistantError(message, ctx);
+  } else {
+    context.recoveryRuntime.handleSilentContextOverflow(ctx);
+  }
+  return true;
+}
+
+export function handleAgentErrorMessage(
+  message: AssistantErrorMessage,
+  ctx: ExtensionContext,
+  context: GoalRuntimeOverflowRecoveryContext,
+): void {
+  recordAssistantContextOverflow(message, ctx, context);
+  if (!isContextOverflowError(message.errorMessage)) {
+    context.recoveryRuntime.handlePersistentAssistantError(message, ctx);
+  }
+}

package/src/goal-runtime-events.ts

@@ -0,0 +1,24 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import type { GoalRuntimeController } from "./goal-runtime-controller.js";
+
+export function registerGoalRuntimeEvents(
+  pi: ExtensionAPI,
+  controller: GoalRuntimeController,
+): void {
+  pi.on("input", (event, ctx) => controller.onInput(event, ctx));
+  pi.on("context", (event, ctx) => controller.onContext(event, ctx));
+  pi.on("session_start", (event, ctx) => controller.onSessionStart(event, ctx));
+  pi.on("session_tree", (event, ctx) => controller.onSessionTree(event, ctx));
+  pi.on("before_agent_start", (event, ctx) => controller.onBeforeAgentStart(event, ctx));
+  pi.on("message_start", (event, ctx) => controller.onMessageStart(event, ctx));
+  pi.on("turn_start", (event, ctx) => controller.onTurnStart(event, ctx));
+  pi.on("tool_execution_end", (event, ctx) => controller.onToolExecutionEnd(event, ctx));
+  pi.on("turn_end", (event, ctx) => controller.onTurnEnd(event, ctx));
+  pi.on("agent_end", (event, ctx) => controller.onAgentEnd(event, ctx));
+  pi.on("session_before_compact", (event, ctx) =>
+    controller.onSessionBeforeCompact(event, ctx),
+  );
+  pi.on("session_compact", (event, ctx) => controller.onSessionCompact(event, ctx));
+  pi.on("session_shutdown", (event, ctx) => controller.onSessionShutdown(event, ctx));
+}

package/src/goal-runtime-input-context-handlers.ts

@@ -0,0 +1,144 @@
+import type {
+  BeforeAgentStartEvent,
+  ContextEvent,
+  ExtensionHandler,
+  InputEvent,
+  InputEventResult,
+} from "@earendil-works/pi-coding-agent";
+
+import { continuationGoalIdFromPrompt } from "./prompts.js";
+import { applyQueuedGoalProviderContextRewrites, extensionQueuedGoalWorkMessageId } from "./queued-goal-work.js";
+import { isActiveGoalQueuedDetails, isCommandResumeQueuedGoalMessage } from "./queued-goal-messages.js";
+import { applyStaleQueuedWorkEffects } from "./goal-runtime-event-utils.js";
+import type {
+  ContextEventResult,
+  GoalRuntimeInputContextHandlerContext,
+  MessageStartEvent,
+  QueuedGoalWorkMessageIdResolver,
+} from "./goal-runtime-event-handler-types.js";
+
+function goalIdFromQueuedDetails(details: unknown): string | null {
+  return isActiveGoalQueuedDetails(details) ? details.goalId : null;
+}
+
+function goalIdFromEventDetails(event: unknown): string | null {
+  if (!event || typeof event !== "object") {
+    return null;
+  }
+  const candidate = event as { details?: unknown; message?: { details?: unknown } };
+  return goalIdFromQueuedDetails(candidate.details) ?? goalIdFromQueuedDetails(candidate.message?.details);
+}
+
+export function createInputContextEventHandlers(
+  deps: GoalRuntimeInputContextHandlerContext,
+  queuedGoalWorkMessageIdForRuntime: QueuedGoalWorkMessageIdResolver,
+) {
+  const { runtimeState, stateController, continuation, recoveryRuntime, status, resetErrorRecovery } = deps;
+
+  return {
+    onInput: (async (event, ctx) => {
+      continuation.clearPassthroughContinuationInput();
+      const continuationGoalId = goalIdFromEventDetails(event) ?? continuationGoalIdFromPrompt(event.text);
+
+      if (event.source !== "extension") {
+        recoveryRuntime.onUserInput();
+        applyStaleQueuedWorkEffects(
+          runtimeState.staleQueuedWorkGuard.planUserInputClearAbort().effects,
+          ctx,
+          deps,
+        );
+        if (continuationGoalId !== null) {
+          continuation.notePassthroughContinuationInput(event.text);
+        }
+        return undefined;
+      }
+
+      if (continuationGoalId === null) {
+        return undefined;
+      }
+
+      applyStaleQueuedWorkEffects(
+        runtimeState.staleQueuedWorkGuard.planExtensionContinuationClearAbort().effects,
+        ctx,
+        deps,
+      );
+      continuation.clearContinuationStateFor(continuationGoalId);
+      if (stateController.isCurrentActiveGoalId(continuationGoalId)) {
+        return { action: "continue" } as const;
+      }
+
+      status.refreshUi(ctx);
+      return { action: "handled" } as const;
+    }) satisfies ExtensionHandler<InputEvent, InputEventResult>,
+
+    onContext: (async (event, ctx) => {
+      const { messages, changed } = applyQueuedGoalProviderContextRewrites(event.messages, {
+        goal: stateController.getGoal(),
+        resolveStaleQueuedGoalWorkMessageId: queuedGoalWorkMessageIdForRuntime,
+        resolveActiveContinuationQueuedGoalWorkMessageId: extensionQueuedGoalWorkMessageId,
+      });
+
+      const contextAbortPlan = runtimeState.staleQueuedWorkGuard.planContextAbort(
+        runtimeState.currentTurnIndex,
+      );
+      if (contextAbortPlan !== null) {
+        applyStaleQueuedWorkEffects(contextAbortPlan.effects, ctx, deps);
+      }
+
+      return changed ? { messages } : undefined;
+    }) satisfies ExtensionHandler<ContextEvent, ContextEventResult | undefined>,
+
+    onBeforeAgentStart: (async (event, ctx) => {
+      const continuationGoalId =
+        goalIdFromEventDetails(event) ?? continuation.continuationGoalIdFromRuntimePrompt(event.prompt);
+      if (continuationGoalId !== null) {
+        continuation.clearContinuationStateFor(continuationGoalId);
+        if (!stateController.isCurrentActiveGoalId(continuationGoalId)) {
+          runtimeState.staleQueuedWorkGuard.noteStaleWorkStarted(continuationGoalId);
+          status.refreshUi(ctx);
+          return undefined;
+        }
+        applyStaleQueuedWorkEffects(
+          runtimeState.staleQueuedWorkGuard.planBeforeAgentStartClearAbort().effects,
+          ctx,
+          deps,
+        );
+      } else {
+        applyStaleQueuedWorkEffects(
+          runtimeState.staleQueuedWorkGuard.planBeforeAgentStartClearAbort().effects,
+          ctx,
+          deps,
+        );
+        continuation.clearContinuationState();
+      }
+      return undefined;
+    }) satisfies ExtensionHandler<BeforeAgentStartEvent, undefined>,
+
+    onMessageStart: (async (event, _ctx) => {
+      if (event.message.role === "user") {
+        stateController.persistHostOverflowUserReset(false);
+      }
+
+      const queuedGoalId = queuedGoalWorkMessageIdForRuntime(event.message);
+      if (queuedGoalId === null) {
+        if (event.message.role === "user" || event.message.role === "custom") {
+          runtimeState.staleQueuedWorkGuard.noteRunnableWorkStarted();
+          continuation.clearContinuationState();
+        }
+        return;
+      }
+
+      continuation.clearContinuationStateFor(queuedGoalId);
+      if (stateController.isCurrentActiveGoalId(queuedGoalId)) {
+        stateController.persistHostOverflowUserReset(false);
+        runtimeState.staleQueuedWorkGuard.noteRunnableWorkStarted();
+        if (isCommandResumeQueuedGoalMessage(event.message)) {
+          resetErrorRecovery();
+        }
+        return;
+      }
+
+      runtimeState.staleQueuedWorkGuard.noteStaleWorkStarted(queuedGoalId);
+    }) satisfies ExtensionHandler<MessageStartEvent>,
+  };
+}

package/src/goal-runtime-session-handlers.ts

@@ -0,0 +1,131 @@
+import type {
+  ExtensionContext,
+  ExtensionHandler,
+  SessionBeforeCompactEvent,
+  SessionCompactEvent,
+  SessionShutdownEvent,
+  SessionStartEvent,
+  SessionTreeEvent,
+} from "@earendil-works/pi-coding-agent";
+
+import { recoveryPhaseBlocksContinuation } from "./recovery-machine.js";
+import { isRecoveryPendingAttention, reasonFromRecoveryPendingAttention } from "./recovery.js";
+import { applyStaleQueuedWorkEffects, runStaleQueuedWorkPlan } from "./goal-runtime-event-utils.js";
+import type { GoalRuntimeSessionHandlerContext } from "./goal-runtime-event-handler-types.js";
+
+export function createSessionEventHandlers(deps: GoalRuntimeSessionHandlerContext) {
+  const {
+    runtimeState,
+    stateController,
+    continuation,
+    goalAccounting,
+    recoveryRuntime,
+    status,
+    resetErrorRecovery,
+  } = deps;
+
+  return {
+    onSessionStart: (async (event, ctx) => {
+      stateController.reloadFromSession(ctx);
+      goalAccounting.beginAccounting();
+      const goal = stateController.getGoal();
+      const pausedGoal = goal?.status === "paused" ? goal : null;
+      if (event.reason === "resume" && pausedGoal && ctx.hasUI) {
+        const shouldResume = await ctx.ui.confirm(
+          "Resume paused goal?",
+          `Goal: ${pausedGoal.objective}`,
+        );
+        if (shouldResume) {
+          stateController.resumePausedGoal(ctx);
+          goalAccounting.beginAccounting();
+          const resumedGoal = stateController.getGoal();
+          if (resumedGoal?.status === "active") {
+            continuation.requestContinuation(ctx);
+          }
+          return;
+        }
+      }
+      continuation.requestContinuation(ctx);
+    }) satisfies ExtensionHandler<SessionStartEvent>,
+
+    onSessionTree: (async (_event, ctx) => {
+      stateController.reloadFromSession(ctx);
+      goalAccounting.beginAccounting();
+      continuation.requestContinuation(ctx);
+    }) satisfies ExtensionHandler<SessionTreeEvent>,
+
+    onSessionBeforeCompact: (async (_event, ctx) => {
+      if (
+        runStaleQueuedWorkPlan(
+          runtimeState.staleQueuedWorkGuard.planSessionBeforeCompact(),
+          ctx,
+          deps,
+        )
+      ) {
+        return;
+      }
+
+      goalAccounting.accountProgress(ctx, false, 0, true);
+      stateController.flushGoalPersistence("runtime");
+    }) satisfies ExtensionHandler<SessionBeforeCompactEvent>,
+
+    onSessionCompact: (async (_event, ctx) => {
+      if (runStaleQueuedWorkPlan(runtimeState.staleQueuedWorkGuard.planSessionCompact(), ctx, deps)) {
+        return;
+      }
+
+      stateController.flushGoalPersistence("runtime");
+      recoveryRuntime.onSessionCompact();
+      status.refreshUi(ctx);
+      if (!recoveryPhaseBlocksContinuation(runtimeState.recoveryState.phase)) {
+        continuation.requestContinuation(ctx);
+      }
+    }) satisfies ExtensionHandler<SessionCompactEvent>,
+
+    onSessionShutdown: (async (_event, ctx) => {
+      continuation.clearPassthroughContinuationInput();
+      applyStaleQueuedWorkEffects(runtimeState.staleQueuedWorkGuard.planSessionShutdown().effects, ctx, deps);
+
+      goalAccounting.accountProgress(ctx, false, 0, true);
+      stateController.flushGoalPersistence("runtime");
+      continuation.clearContinuationTimer();
+      if (hasPendingRecoveryAttention(deps)) {
+        pauseForPendingRecoveryShutdown(ctx, deps);
+      } else {
+        resetErrorRecovery();
+      }
+      status.stopStatusRefresh();
+    }) satisfies ExtensionHandler<SessionShutdownEvent>,
+  };
+}
+
+function hasPendingRecoveryAttention({ runtimeState, stateController }: GoalRuntimeSessionHandlerContext): boolean {
+  const goal = stateController.getGoal();
+  return Boolean(
+    goal?.status === "active" && isRecoveryPendingAttention(runtimeState.recoveryState.attention),
+  );
+}
+
+function pauseForPendingRecoveryShutdown(
+  ctx: ExtensionContext,
+  deps: GoalRuntimeSessionHandlerContext,
+): void {
+  const { runtimeState, stateController } = deps;
+  const goal = stateController.getGoal();
+  if (!goal || goal.status !== "active" || !runtimeState.recoveryState.attention) {
+    return;
+  }
+
+  const reason = reasonFromRecoveryPendingAttention(runtimeState.recoveryState.attention);
+  if (!reason) {
+    return;
+  }
+
+  stateController.applyGoalTransition(
+    {
+      kind: "recovery_shutdown_pause",
+      recoveryReason: reason,
+    },
+    ctx,
+  );
+}

package/src/goal-runtime-state.ts

@@ -0,0 +1,22 @@
+import { createAccountingState, type AccountingState } from "./goal-accounting.js";
+import { createGoalRecoveryMachine, type GoalRecoveryMachineState } from "./recovery-machine.js";
+import {
+  createStaleQueuedWorkGuard,
+  type StaleQueuedWorkGuard,
+} from "./stale-queued-work-guard.js";
+
+export interface GoalRuntimeState {
+  accounting: AccountingState;
+  recoveryState: GoalRecoveryMachineState;
+  currentTurnIndex: number | null;
+  staleQueuedWorkGuard: StaleQueuedWorkGuard;
+}
+
+export function createGoalRuntimeState(): GoalRuntimeState {
+  return {
+    accounting: createAccountingState(),
+    recoveryState: createGoalRecoveryMachine(),
+    currentTurnIndex: null,
+    staleQueuedWorkGuard: createStaleQueuedWorkGuard(),
+  };
+}

package/src/goal-runtime-status.ts

@@ -0,0 +1,62 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { formatFooterStatus } from "./format.js";
+import type { GoalRecoveryMachineState } from "./recovery-machine.js";
+import type { ThreadGoal } from "./types.js";
+
+export interface StatusContext {
+  ui: Pick<ExtensionContext["ui"], "setStatus">;
+}
+
+interface GoalRuntimeStatusDeps {
+  getGoalForDisplay: () => ThreadGoal | null;
+  getGoalStatus: () => ThreadGoal["status"] | null;
+  getRecoveryAttention: () => GoalRecoveryMachineState["attention"];
+}
+
+export function createGoalRuntimeStatus(deps: GoalRuntimeStatusDeps) {
+  let statusContext: StatusContext | null = null;
+  let statusRefreshTimer: ReturnType<typeof setInterval> | null = null;
+
+  const stopStatusRefresh = (): void => {
+    if (statusRefreshTimer) {
+      clearInterval(statusRefreshTimer);
+      statusRefreshTimer = null;
+    }
+  };
+
+  const syncStatusRefresh = (): void => {
+    if (deps.getGoalStatus() === "active" && statusContext && !statusRefreshTimer) {
+      statusRefreshTimer = setInterval(() => {
+        if (!statusContext || deps.getGoalStatus() !== "active") {
+          stopStatusRefresh();
+          return;
+        }
+        statusContext.ui.setStatus(
+          "codex-goal",
+          formatFooterStatus(deps.getGoalForDisplay(), deps.getRecoveryAttention()),
+        );
+      }, 1_000);
+      statusRefreshTimer.unref?.();
+      return;
+    }
+
+    if (deps.getGoalStatus() !== "active") {
+      stopStatusRefresh();
+    }
+  };
+
+  const refreshUi = (ctx: StatusContext): void => {
+    statusContext = ctx;
+    ctx.ui.setStatus(
+      "codex-goal",
+      formatFooterStatus(deps.getGoalForDisplay(), deps.getRecoveryAttention()),
+    );
+    syncStatusRefresh();
+  };
+
+  return {
+    refreshUi,
+    stopStatusRefresh,
+  };
+}