oira666_pi-limits-wait 0.5.6 → 0.5.8

package/README.md

@@ -55,6 +55,89 @@ Liveliness messages include the retry reason, the model, the remaining wait, and
 
 Interactive (TUI) behavior is unchanged: retry notices remain `warning`-level chat notifications with the live countdown, and no duplicate error notification is added because the terminal error event is already rendered in the transcript.
 
+### Structured status channel
+
+Since 0.5.7 the extension publishes a **second, machine-readable** `setStatus` entry beside the prose one, under its own key:
+
+```
+{"type":"extension_ui_request","id":"<uuid>","method":"setStatus",
+ "statusKey":"oira666.pi-limits-wait.json","statusText":"<minified JSON>"}
+```
+
+The prose key `oira666.pi-limits-wait` is **unchanged** in text, key, cadence and clearing semantics, so a host that only knows 0.5.6 is unaffected. The JSON key is published on exactly the same schedule as the prose notice (immediately when a wait starts, then every `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` seconds while waiting) and only in non-interactive (`rpc`/`json`) hosts. A blank/absent `statusText` under this key is the end-of-window marker.
+
+`statusText` is one minified JSON line:
+
+```json
+{"v":1,"ext":"0.5.7","event":"wait","waitId":"wait-mfk3z1-7","periodId":"period-3","reason":"rate-limit","message":"⏳ pi-limits-wait: rate limited on anthropic/claude-sonnet-4-5; still alive, waiting 12m 04s before the next retry. Why: HTTP 429 retry-after-ms 724000","error":"HTTP 429 retry-after-ms 724000","model":{"provider":"anthropic","id":"claude-sonnet-4-5"},"plannedDurationMs":1800000,"plannedDeadline":1786000000000,"startedAt":1785998200000,"remainingMs":724000,"attempt":null,"maxAttempts":null,"livelinessIntervalMs":15000,"controlFile":"/tmp/ram-pi-.../limits-wait.control"}
+```
+
+End of a wait (published once, immediately before both keys are cleared):
+
+```json
+{"v":1,"ext":"0.5.7","event":"wait_end","waitId":"wait-mfk3z1-7","reason":"rate-limit","message":"…","error":"…","plannedDurationMs":1800000,"plannedDeadline":1786000000000,"startedAt":1785998200000,"remainingMs":0,"attempt":null,"maxAttempts":null,"livelinessIntervalMs":15000,"controlFile":"…","outcome":"skipped","actualElapsedMs":41233}
+```
+
+Terminal give-up (the extension has stopped retrying and surfaces the final error):
+
+```json
+{"v":1,"ext":"0.5.7","event":"give_up","waitId":null,"reason":null,"message":"anthropic/claude-sonnet-4-5 failed and pi-limits-wait is not retrying: …","error":"…","plannedDurationMs":null,"plannedDeadline":null,"startedAt":null,"remainingMs":null,"attempt":null,"maxAttempts":null,"livelinessIntervalMs":15000,"controlFile":"…"}
+```
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `v` | `1` | Payload schema version. Bumped only on a breaking change. |
+| `ext` | string | Extension version that produced the frame, e.g. `"0.5.7"`. |
+| `event` | `"wait"` \| `"wait_end"` \| `"give_up"` | Liveliness tick, end of a wait, or terminal give-up. |
+| `waitId` | string \| null | Correlates every frame of one wait. `null` only for `give_up`. |
+| `periodId` | string (optional) | Retry-period id, when the wait belongs to one. |
+| `reason` | `"rate-limit"` \| `"overloaded"` \| `"authentication"` \| `"model-frozen"` \| `"network"` \| `"retry"` \| null | `null` only for `give_up`. |
+| `message` | string | The same human text published on the prose channel (≤500 chars, single line). |
+| `error` | string \| null | Normalised originating provider error (≤500 chars). |
+| `model` | `{provider,id}` (optional) | Model the wait applies to, when known. |
+| `plannedDurationMs` | number \| null | Planned wait length. |
+| `plannedDeadline` | number \| null | Epoch ms when the retry is planned. |
+| `startedAt` | number \| null | Epoch ms when the wait began. |
+| `remainingMs` | number \| null | `max(0, plannedDeadline - now)` at publish time; `0` on `wait_end`. |
+| `attempt` | number \| null | 1-based extension-created attempt. Only the unknown-error path counts attempts; classified waits send `null`. |
+| `maxAttempts` | number \| null | `PI_LIMITS_WAIT_MAX_RETRY + 1`, or `null` when not applicable. |
+| `livelinessIntervalMs` | number | Publishing interval, so a consumer can compute staleness itself. |
+| `controlFile` | string \| null | The path this process polls for skip tokens, or `null` when disabled. |
+| `outcome` | `"waited"` \| `"skipped"` \| `"aborted"` (optional) | `wait_end` only. |
+| `actualElapsedMs` | number (optional) | `wait_end` only. |
+
+Set `PI_LIMITS_WAIT_STATUS_JSON=false` to suppress this channel entirely and restore exact 0.5.6 wire behavior. `PI_LIMITS_WAIT_DISABLE_ALL_WAITING=true` also suppresses it (nothing is published and no control file is polled).
+
+The payload type is exported for TypeScript hosts:
+
+```ts
+import {
+  LIVELINESS_JSON_STATUS_KEY,
+  type LimitsWaitStatusPayload,
+} from "oira666_pi-limits-wait";
+```
+
+### Skipping a wait from the host
+
+In `rpc`/`json` mode there is no terminal, so the interactive "press Enter to retry now" affordance is unavailable. Instead, set `PI_LIMITS_WAIT_CONTROL_FILE` to an absolute path (one per pi process; the extension echoes it back as `controlFile` in every structured frame). While — and only while — a wait is in progress, the extension polls that path once per second from the countdown ticker it already runs. Signals are deliberately **not** used: `SIGUSR2` with no handler installed terminates the process, and a signal cannot carry a `waitId`.
+
+Write a token to make the extension stop waiting and retry immediately:
+
+```json
+{"action":"skip","waitId":"wait-mfk3z1-7","issuedAt":1785998240123,"by":"ramcore"}
+```
+
+- `action` must be `"skip"`; anything else is ignored.
+- `waitId` must equal the current wait's `waitId` (from the structured frame), or the wildcard `"*"` for "skip whichever wait is current".
+- `issuedAt` is epoch ms and must be `>= startedAt` of the current wait.
+- Writers should write a temp file and rename it into place (atomic move) so a partial read is impossible.
+
+The extension consumes a token by atomically renaming the canonical control path to a unique `.consumed-<waitId>-<random>` path in the same directory, then reading and validating that claimed file. It removes only the unique claimed path. A writer may therefore rename a newer token onto the canonical path immediately after the claim without cleanup deleting that replacement. An accepted claim settles the wait with `outcome: "skipped"` — the exact same path the Enter key uses, so the retry proceeds normally and a `wait_end` frame with `"outcome":"skipped"` is published. Polls are serialized; a slow filesystem operation cannot overlap the next one-second tick.
+
+Two content guards ensure a claimed leftover token can never skip a **later** legitimate wait: (a) `waitId` equality — a token written for wait *N* cannot match wait *N+1*'s freshly generated id; (b) `issuedAt >= startedAt` — a `"*"` token issued before this wait began is rejected. Claimed malformed, stale, and non-matching files are discarded, while any newer token at the canonical path is left untouched. The extension deliberately does not unlink the canonical path at wait start, because that would race with a token written microseconds earlier.
+
+A missing or unclaimable control path is silently ignored. If `PI_LIMITS_WAIT_CONTROL_FILE` is unset (or all waiting is disabled), no filesystem access happens at all.
+
 ## Wait event contract
 
 Every positive extension-managed wait emits public telemetry on Pi's shared event bus. Import the channel constant and payload union from the package entry point:
@@ -163,7 +246,9 @@ The extension rereads these files before every LLM call, so changes made during
 | `PI_LIMITS_WAIT_DISABLE_ALL_WAITING` | `false` | Master kill switch for this extension's error handling, retries, fallbacks, freezing, waiting, notifications, telemetry, and retry summaries. Set to `true` (also accepts `1`, `yes`, `on`) to leave only Anthropic OAuth system-prompt cleaning enabled; requests continue through Pi's normal runtime, including its normal Anthropic headers. This takes precedence over every setting below. |
 | `PI_LIMITS_WAIT_DEFAULT_WAITING` | `true` | Whether unclassified/unknown provider errors enter the wait-and-retry cycle. Set to `false` (also accepts `0`, `no`, `off`) to surface the error immediately. Rate-limit, overload, authentication, and network retry behavior is unchanged. |
 | `PI_LIMITS_WAIT_MAX_RETRY` | `999999` | Maximum extension-created retries for an unclassified/unknown provider error. The initial failed request and provider-internal retries do not count. HTTP 400/403 remain eligible. Must be a non-negative integer. |
-| `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` | `15` | Seconds between liveliness notifications published while waiting in non-interactive (`rpc`/`json`) modes. Must be a non-negative integer; values below 1 second are clamped to 1 second. Ignored in TUI mode. |
+| `PI_LIMITS_WAIT_LIVELINESS_INTERVAL` | `15` | Seconds between liveliness notifications published while waiting in non-interactive (`rpc`/`json`) modes. Must be a non-negative integer; values below 1 second are clamped to 1 second. Ignored in TUI mode. Also drives the structured status channel and is reported inside it as `livelinessIntervalMs`. |
+| `PI_LIMITS_WAIT_STATUS_JSON` | `true` | Whether the machine-readable status channel (`statusKey` `oira666.pi-limits-wait.json`) is published in non-interactive modes. Set to `false` (also accepts `0`, `no`, `off`) to restore exact 0.5.6 wire behavior. The prose channel is never affected. |
+| `PI_LIMITS_WAIT_CONTROL_FILE` | *(unset)* | Absolute path of the out-of-band control file polled once per second **while waiting**, used by the host to skip the current wait and retry immediately. Unset disables the feature and all filesystem access. See [Skipping a wait from the host](#skipping-a-wait-from-the-host). |
 | `PI_LIMITS_WAIT_RETRY_INTERVAL` | `5` | Seconds to wait between unclassified/unknown provider-error retries. Must be a non-negative integer (values above 2147483 are capped to Node's maximum reliable timer delay). This does not affect model-limit wait intervals. |
 | `PI_LIMITS_WAIT_FREEZING_ENABLED` | `true` | When a model keeps failing with a non-retryable error, it is normally "frozen" for 10 minutes and skipped in favour of other configured models. Set this to `false` (also accepts `0`, `no`, `off`) to disable freezing entirely: the extension will instead try each configured candidate once (after the bounded retries) and then surface the error, never blocking on a long "model-frozen" wait. Useful for non-interactive / subagent runs where no one can press Enter to skip. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-limits-wait",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "description": "Extension for PI that allows to automatically wait for limits to reset and retry the request",
   "type": "module",
   "exports": {

package/src/constants.ts

@@ -35,6 +35,12 @@ export const DEFAULT_UNKNOWN_ERROR_RETRY_INTERVAL_MS = 5 * 1_000; // 5 seconds
 export const LIVELINESS_STATUS_KEY = "oira666.pi-limits-wait";
 export const DEFAULT_LIVELINESS_INTERVAL_MS = 15 * 1_000; // 15 seconds
 
+/** Machine-readable sibling of LIVELINESS_STATUS_KEY. Compact JSON, never prose. */
+export const LIVELINESS_JSON_STATUS_KEY = "oira666.pi-limits-wait.json";
+/** Payload schema version for LIVELINESS_JSON_STATUS_KEY. Bump only on a breaking change. */
+export const LIVELINESS_JSON_VERSION = 1;
+export const EXTENSION_VERSION = "0.5.7";
+
 export const SETTINGS_FILE_NAME = "limits-wait.json";
 export const FALLBACK_MODELS_KEY = "fallback-models";
 export const DISABLE_ALL_WAITING_ENV_VAR = "PI_LIMITS_WAIT_DISABLE_ALL_WAITING";
@@ -43,3 +49,7 @@ export const DEFAULT_WAITING_ENV_VAR = "PI_LIMITS_WAIT_DEFAULT_WAITING";
 export const MAX_RETRY_ENV_VAR = "PI_LIMITS_WAIT_MAX_RETRY";
 export const RETRY_INTERVAL_ENV_VAR = "PI_LIMITS_WAIT_RETRY_INTERVAL";
 export const LIVELINESS_INTERVAL_ENV_VAR = "PI_LIMITS_WAIT_LIVELINESS_INTERVAL";
+/** Set to false/0/no/off to suppress the structured status channel. */
+export const STATUS_JSON_ENV_VAR = "PI_LIMITS_WAIT_STATUS_JSON";
+/** Absolute path of the out-of-band control file polled while waiting. Unset => no control. */
+export const CONTROL_FILE_ENV_VAR = "PI_LIMITS_WAIT_CONTROL_FILE";

package/src/index.ts

@@ -31,6 +31,26 @@ export {
 export {
   LIMITS_WAIT_EVENT_CHANNEL,
 } from "./telemetry.js";
+export {
+  CONTROL_FILE_ENV_VAR,
+  EXTENSION_VERSION,
+  LIVELINESS_JSON_STATUS_KEY,
+  LIVELINESS_JSON_VERSION,
+  LIVELINESS_STATUS_KEY,
+  STATUS_JSON_ENV_VAR,
+} from "./constants.js";
+export {
+  clearStatusJson,
+  controlFilePath,
+  publishStatusJson,
+  statusJsonEnabled,
+  statusPayload,
+} from "./status-json.js";
+export type {
+  LimitsWaitStatusContext,
+  LimitsWaitStatusEvent,
+  LimitsWaitStatusPayload,
+} from "./status-json.js";
 export type {
   LimitsWaitEndEventPayload,
   LimitsWaitEventPayload,
@@ -83,11 +103,16 @@ export default function (pi: ExtensionAPI) {
   const retrySummaries = new RetrySummaryCoordinator(pi);
   const releaseInterception = installModelRuntimeInterception(() => retrySummaries.createStream());
 
-  pi.on("model_select", (event) => {
+  pi.on("model_select", (event, ctx) => {
+    state.sharedCtx = ctx;
     if (consumeExpectedModelSelection(event.model)) return;
     if (isInternalSyntheticModel(event.model)) return;
     state.primaryModel = event.model;
     state.primaryThinkingLevel = pi.getThinkingLevel();
+    state.userModelSelectionGeneration++;
+    // A user-selected model takes precedence over a pending retry. Wake every
+    // wait so its stream can adopt the new primary model immediately.
+    for (const skip of [...state.activeWaitSkips]) skip();
   });
 
   pi.on("before_agent_start", (_event, ctx) => {
@@ -120,6 +145,7 @@ export default function (pi: ExtensionAPI) {
     state.ambientStatusCleanup?.();
     state.modelStatusCleanup?.();
     state.expectedModelSelections.clear();
+    state.activeWaitSkips.clear();
     state.sharedCtx = undefined;
     state.extensionApi = undefined;
   });

package/src/state.ts

@@ -16,6 +16,8 @@ export const state = {
   primaryModel: undefined as Model<Api> | undefined,
   primaryThinkingLevel: undefined as ModelThinkingLevel | undefined,
   expectedModelSelections: new Map<string, Set<symbol>>(),
+  userModelSelectionGeneration: 0,
+  activeWaitSkips: new Set<() => void>(),
   settingsSignature: undefined as string | undefined,
   rateLimitMemory: new Map<string, RateLimitMemory>(),
   nonRetryableFailureMemory: new Map<string, NonRetryableFailureMemory>(),
@@ -56,6 +58,8 @@ export function resetRuntimeStateForTests(models: FallbackModel[], ctx?: Extensi
   state.rateLimitMemory.clear();
   state.nonRetryableFailureMemory.clear();
   state.expectedModelSelections.clear();
+  state.userModelSelectionGeneration = 0;
+  state.activeWaitSkips.clear();
   state.ambientStatusCleanup?.();
   state.modelStatusCleanup?.();
 }

package/src/status-json.ts

@@ -0,0 +1,126 @@
+import {
+  CONTROL_FILE_ENV_VAR,
+  LIVELINESS_JSON_STATUS_KEY,
+  LIVELINESS_JSON_VERSION,
+  EXTENSION_VERSION,
+  STATUS_JSON_ENV_VAR,
+} from "./constants.js";
+import { state } from "./state.js";
+import type { LimitsWaitModel, LimitsWaitWaitOutcome } from "./telemetry.js";
+import type { RetryReason } from "./types.js";
+import { allWaitingDisabled, envBoolean, formatErrorDetail, isNonInteractiveHost } from "./ui.js";
+
+export type LimitsWaitStatusEvent = "wait" | "wait_end" | "give_up";
+
+/**
+ * Machine-readable sibling of the human liveliness notice. Serialised as one
+ * minified JSON line under LIVELINESS_JSON_STATUS_KEY. Field order matches the
+ * documented wire shape; consumers must parse, not pattern-match.
+ */
+export type LimitsWaitStatusPayload = {
+  v: typeof LIVELINESS_JSON_VERSION;
+  ext: string;
+  event: LimitsWaitStatusEvent;
+  waitId: string | null;
+  periodId?: string;
+  reason: RetryReason | null;
+  message: string;
+  error: string | null;
+  model?: LimitsWaitModel;
+  plannedDurationMs: number | null;
+  plannedDeadline: number | null;
+  startedAt: number | null;
+  remainingMs: number | null;
+  attempt: number | null;
+  maxAttempts: number | null;
+  livelinessIntervalMs: number;
+  controlFile: string | null;
+  outcome?: LimitsWaitWaitOutcome;
+  actualElapsedMs?: number;
+};
+
+/** Everything about a wait that does not change between publishes. */
+export type LimitsWaitStatusContext = Omit<
+  LimitsWaitStatusPayload,
+  "v" | "ext" | "event" | "message" | "remainingMs" | "outcome" | "actualElapsedMs"
+>;
+
+/** The structured channel is opt-out; the master kill switch always wins. */
+export function statusJsonEnabled(): boolean {
+  if (allWaitingDisabled()) return false;
+  return envBoolean(process.env[STATUS_JSON_ENV_VAR], true);
+}
+
+/** Absolute path of the out-of-band control file, or undefined when disabled. */
+export function controlFilePath(): string | undefined {
+  if (allWaitingDisabled()) return undefined;
+  return process.env[CONTROL_FILE_ENV_VAR]?.trim() || undefined;
+}
+
+export function statusPayload(
+  context: LimitsWaitStatusContext,
+  event: LimitsWaitStatusEvent,
+  message: string,
+  remainingMs: number | null,
+  extra?: { outcome?: LimitsWaitWaitOutcome; actualElapsedMs?: number },
+): LimitsWaitStatusPayload {
+  return {
+    v: LIVELINESS_JSON_VERSION,
+    ext: EXTENSION_VERSION,
+    event,
+    waitId: context.waitId,
+    ...(context.periodId ? { periodId: context.periodId } : {}),
+    reason: context.reason,
+    message: formatErrorDetail(message),
+    error: context.error,
+    ...(context.model ? { model: context.model } : {}),
+    plannedDurationMs: context.plannedDurationMs,
+    plannedDeadline: context.plannedDeadline,
+    startedAt: context.startedAt,
+    remainingMs,
+    attempt: context.attempt,
+    maxAttempts: context.maxAttempts,
+    livelinessIntervalMs: context.livelinessIntervalMs,
+    controlFile: context.controlFile,
+    ...(extra?.outcome ? { outcome: extra.outcome } : {}),
+    ...(extra?.actualElapsedMs === undefined ? {} : { actualElapsedMs: extra.actualElapsedMs }),
+  };
+}
+
+let statusJsonActive = false;
+
+/** No-op unless the host is non-interactive and the channel is enabled. */
+export function publishStatusJson(payload: LimitsWaitStatusPayload): void {
+  const ctx = state.sharedCtx;
+  if (!ctx || !isNonInteractiveHost() || !statusJsonEnabled()) return;
+  try {
+    ctx.ui.setStatus(LIVELINESS_JSON_STATUS_KEY, JSON.stringify(payload));
+    statusJsonActive = true;
+  } catch { /* UI unavailable */ }
+}
+
+/** Clear a status this instance published, even if its enable flags changed meanwhile. */
+export function clearStatusJson(): void {
+  if (!statusJsonActive) return;
+  const ctx = state.sharedCtx;
+  if (!ctx) return;
+  try {
+    ctx.ui.setStatus(LIVELINESS_JSON_STATUS_KEY, undefined);
+    statusJsonActive = false;
+  } catch { /* retain ownership so a later cleanup can retry */ }
+}
+
+/**
+ * Accept an out-of-band skip token only for the wait it was issued for.
+ * A claimed token is accepted only when waitId equality (or the explicit "*"
+ * wildcard) and issuedAt >= this wait's startedAt both hold. The caller
+ * discards every claimed file, valid or invalid, without touching a replacement
+ * at the canonical path.
+ */
+export function isSkipToken(token: unknown, waitId: string, startedAt: number): boolean {
+  if (!token || typeof token !== "object") return false;
+  const candidate = token as { action?: unknown; waitId?: unknown; issuedAt?: unknown };
+  if (candidate.action !== "skip") return false;
+  if (candidate.waitId !== waitId && candidate.waitId !== "*") return false;
+  return typeof candidate.issuedAt === "number" && candidate.issuedAt >= startedAt;
+}

package/src/stream.ts

@@ -198,6 +198,7 @@ export function streamWithLimitsRetry(
       : { model, reasoningEffort: state.primaryThinkingLevel };
     const nonRetryableAttempts = new Map<string, number>();
     const triedModels = new Set<string>();
+    let observedUserModelSelection = state.userModelSelectionGeneration;
 
     const prepareAttemptForPi = async (): Promise<boolean> => {
       const originalKey = modelKey(model);
@@ -214,14 +215,24 @@ export function streamWithLimitsRetry(
       return switchPiModel(attempt, signal, canSelect);
     };
 
-    const managedWait = async (reason: RetryReason, waitMs: number, error: string) =>
-      waitForRetry(reason, waitMs, signal, {
+    const managedWait = async (
+      reason: RetryReason,
+      waitMs: number,
+      error: string,
+      counters?: { attempt: number; maxAttempts: number },
+    ) => {
+      // The selection may have happened after this attempt started but before
+      // its failure reached us, when there was no active wait to wake.
+      if (observedUserModelSelection !== state.userModelSelectionGeneration) return "skipped" as const;
+      return waitForRetry(reason, waitMs, signal, {
         periodId: retryPeriod?.periodId,
         model: attempt.model,
         error,
         events: retryPeriod?.events,
+        ...(counters ?? {}),
         onEnd: (elapsedMs) => retryPeriod?.recordWait(elapsedMs),
       });
+    };
 
     const flush = (buffer: AssistantMessageEvent[]) => {
       for (const event of buffer) output.push(event);
@@ -244,6 +255,17 @@ export function streamWithLimitsRetry(
     };
 
     while (true) {
+      if (observedUserModelSelection !== state.userModelSelectionGeneration) {
+        observedUserModelSelection = state.userModelSelectionGeneration;
+        const selected = state.primaryModel ?? state.sharedCtx?.model;
+        if (selected) {
+          // User model selection always supersedes the retry/fallback attempt
+          // chosen before the wait. Subsequent retries start from that model.
+          attempt = configuredAttempt(selected);
+          triedModels.clear();
+        }
+      }
+
       if (signal?.aborted) {
         pushAbort("Operation aborted before provider attempt.");
         return;
@@ -524,6 +546,7 @@ export function streamWithLimitsRetry(
           // to non-interactive hosts for this request.
           notifyFinalFailure(
             `${formatModel(attempt.model)} failed and pi-limits-wait is not retrying: ${formatErrorDetail(failureMessage, Number.MAX_SAFE_INTEGER)}`,
+            failureMessage,
           );
           if (!committed) {
             if (buffer.length > 0) flush(buffer);
@@ -549,7 +572,10 @@ export function streamWithLimitsRetry(
           if (attempts < state.nonRetryableMaxAttempts) {
             notifyRetryingAfterError(attempt.model, state.nonRetryableRetryDelayMs, failureMessage);
             retryPeriod?.beginRetry(failureMessage);
-            const wait = await managedWait("retry", state.nonRetryableRetryDelayMs, failureMessage);
+            const wait = await managedWait("retry", state.nonRetryableRetryDelayMs, failureMessage, {
+              attempt: attempts,
+              maxAttempts: state.nonRetryableMaxAttempts,
+            });
             if (wait === "aborted" || signal?.aborted) {
               pushAbort("Request aborted while retrying after error.");
               return;
@@ -646,6 +672,7 @@ export function streamWithLimitsRetry(
     if (failure.stopReason === "error") {
       notifyFinalFailure(
         `${formatModel(model)} failed and pi-limits-wait is not retrying: ${formatErrorDetail(errorMessageWithCauses(error), Number.MAX_SAFE_INTEGER)}`,
+        errorMessageWithCauses(error),
       );
     } else clearLivelinessStatus();
     failure.errorMessage = errorMessageWithCauses(error);

package/src/telemetry.ts

@@ -54,6 +54,9 @@ export type WaitTelemetryOptions = {
   model?: Pick<Model<Api>, "provider" | "id">;
   error?: string;
   events?: EventBus;
+  /** Extension-created attempt counters, when the call site tracks them. */
+  attempt?: number;
+  maxAttempts?: number;
   onEnd?: (actualElapsedMs: number, outcome: LimitsWaitWaitOutcome) => void;
 };
 

package/src/ui.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rename, unlink } from "node:fs/promises";
 import {
   DEFAULT_LIVELINESS_INTERVAL_MS,
   DEFAULT_UNKNOWN_ERROR_MAX_RETRIES,
@@ -11,6 +13,14 @@ import {
   RETRY_INTERVAL_ENV_VAR,
 } from "./constants.js";
 import { state } from "./state.js";
+import {
+  clearStatusJson,
+  controlFilePath,
+  isSkipToken,
+  publishStatusJson,
+  statusPayload,
+  type LimitsWaitStatusContext,
+} from "./status-json.js";
 import {
   createWaitId,
   emitWaitTelemetry,
@@ -46,7 +56,7 @@ export function reasonLabel(reason: RetryReason): string {
   return "Rate limited";
 }
 
-function envBoolean(raw: string | undefined, defaultValue: boolean): boolean {
+export function envBoolean(raw: string | undefined, defaultValue: boolean): boolean {
   if (raw === undefined) return defaultValue;
   const value = raw.trim().toLowerCase();
   return !(value === "false" || value === "0" || value === "no" || value === "off");
@@ -128,19 +138,38 @@ export function clearLivelinessStatus(): void {
   const ctx = state.sharedCtx;
   if (!ctx || !isNonInteractiveHost()) return;
   try { ctx.ui.setStatus(LIVELINESS_STATUS_KEY, undefined); } catch { /* UI unavailable */ }
+  clearStatusJson();
+}
+
+/** Structured-channel context for an event that happens outside a wait. */
+function standaloneStatusContext(error?: string): LimitsWaitStatusContext {
+  return {
+    waitId: null,
+    reason: null,
+    error: error ? formatErrorDetail(error) : null,
+    plannedDurationMs: null,
+    plannedDeadline: null,
+    startedAt: null,
+    attempt: null,
+    maxAttempts: null,
+    livelinessIntervalMs: livelinessIntervalMs(),
+    controlFile: controlFilePath() ?? null,
+  };
 }
 
 /**
  * Terminal failure notice: the extension has stopped retrying. This is the only
  * place where an error-level notification is emitted.
  */
-export function notifyFinalFailure(message: string): void {
+export function notifyFinalFailure(message: string, error?: string): void {
   const ctx = state.sharedCtx;
   if (!ctx) return;
   clearLivelinessStatus();
   if (!isNonInteractiveHost()) return;
   // In TUI the terminal error event is already rendered in the transcript.
   try { ctx.ui.notify(message, "error"); } catch { /* UI unavailable */ }
+  publishStatusJson(statusPayload(standaloneStatusContext(error ?? message), "give_up", message, null));
+  clearStatusJson();
 }
 
 function livelinessText(
@@ -161,25 +190,28 @@ function livelinessText(
  * Returns a cleanup function.
  */
 function startLivelinessReporting(
+  context: LimitsWaitStatusContext,
   reason: RetryReason,
   deadline: number,
   model?: Pick<LimitsWaitModel, "provider" | "id">,
   error?: string,
-): () => void {
+): (clearStatus?: boolean) => void {
   if (!isNonInteractiveHost()) return () => undefined;
 
   const report = () => {
     const remaining = Math.max(0, deadline - Date.now());
-    notifyLiveliness(livelinessText(reason, remaining, model, error));
+    const message = livelinessText(reason, remaining, model, error);
+    notifyLiveliness(message);
+    publishStatusJson(statusPayload(context, "wait", message, remaining));
   };
   report();
   const ticker = setInterval(() => {
     if (Date.now() >= deadline) return;
     report();
   }, livelinessIntervalMs());
-  return () => {
+  return (clearStatus = true) => {
     clearInterval(ticker);
-    clearLivelinessStatus();
+    if (clearStatus) clearLivelinessStatus();
   };
 }
 
@@ -227,6 +259,41 @@ export function clearModelStatus(): void {
   state.modelStatusCleanup?.();
 }
 
+/**
+ * Atomically claim the canonical control path before inspecting its contents.
+ * The writer may immediately replace the canonical path; cleanup only ever
+ * touches the unique claimed path in the same directory.
+ */
+export async function claimControlFile(controlFile: string, waitId: string): Promise<string | undefined> {
+  const claimedFile = `${controlFile}.consumed-${waitId}-${randomUUID()}`;
+  try {
+    await rename(controlFile, claimedFile);
+    return claimedFile;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === "ENOENT") return undefined;
+    return undefined;
+  }
+}
+
+/** Coalesce timer ticks while an asynchronous filesystem poll is still running. */
+export function createSerializedAsyncRunner<T>(task: () => Promise<T>): {
+  run: () => Promise<T>;
+  pending: () => Promise<T> | undefined;
+} {
+  let inFlight: Promise<T> | undefined;
+  return {
+    run: () => {
+      if (inFlight) return inFlight;
+      const current = task().finally(() => {
+        if (inFlight === current) inFlight = undefined;
+      });
+      inFlight = current;
+      return current;
+    },
+    pending: () => inFlight,
+  };
+}
+
 export function waitForRetry(
   reason: RetryReason,
   waitMs: number,
@@ -253,41 +320,116 @@ export function waitForRetry(
   };
   emitWaitTelemetry(events, { ...common, phase: "start" } satisfies LimitsWaitWaitStartPayload);
 
+  // Resolved once per wait so a /reload picks up a new value.
+  const controlFile = controlFilePath();
+  const statusContext: LimitsWaitStatusContext = {
+    waitId,
+    ...(telemetry?.periodId ? { periodId: telemetry.periodId } : {}),
+    reason,
+    error: telemetry?.error ? formatErrorDetail(telemetry.error) : null,
+    ...(model ? { model } : {}),
+    plannedDurationMs: waitMs,
+    plannedDeadline,
+    startedAt,
+    attempt: telemetry?.attempt ?? null,
+    maxAttempts: telemetry?.maxAttempts ?? null,
+    livelinessIntervalMs: livelinessIntervalMs(),
+    controlFile: controlFile ?? null,
+  };
+
   return new Promise((resolve) => {
     const ctx = state.sharedCtx;
     let done = false;
-    const stopLiveliness = startLivelinessReporting(reason, plannedDeadline, model, telemetry?.error);
+    const stopLiveliness = startLivelinessReporting(statusContext, reason, plannedDeadline, model, telemetry?.error);
     let unsubInput: (() => void) | undefined;
     let ticker: ReturnType<typeof setInterval> | undefined;
     let timer: ReturnType<typeof setTimeout> | undefined;
 
     const onAbort = () => settle("aborted");
 
+    const skipWait = () => settle("skipped");
+
     function cleanup() {
       if (ticker) clearInterval(ticker);
       if (timer) clearTimeout(timer);
-      try { stopLiveliness(); } catch { /* UI unavailable */ }
+      state.activeWaitSkips.delete(skipWait);
+      try { stopLiveliness(false); } catch { /* UI unavailable */ }
       signal?.removeEventListener("abort", onAbort);
       try { unsubInput?.(); } catch { /* UI unavailable */ }
       try { ctx?.ui.setWorkingMessage(); } catch { /* UI unavailable */ }
       try { clearAmbientRetryStatus(); } catch { /* UI unavailable */ }
     }
 
-    function settle(outcome: LimitsWaitWaitOutcome) {
+    /**
+     * Out-of-band "retry now": atomically move the observed canonical path to
+     * a unique consumed path before reading it. Invalid claims are discarded;
+     * cleanup can therefore never unlink a newer token renamed into place.
+     */
+    let pendingClaim: Promise<void> | undefined;
+    async function pollControlFile(): Promise<boolean> {
+      if (!controlFile || done) return false;
+      let finishClaim!: () => void;
+      const claimBarrier = new Promise<void>((resolveClaim) => { finishClaim = resolveClaim; });
+      pendingClaim = claimBarrier;
+      const claimedFile = await claimControlFile(controlFile, waitId).finally(() => {
+        finishClaim();
+        if (pendingClaim === claimBarrier) pendingClaim = undefined;
+      });
+      if (!claimedFile) return false;
+
+      let accepted = false;
+      try {
+        const raw = await readFile(claimedFile, "utf8");
+        const token: unknown = JSON.parse(raw);
+        accepted = isSkipToken(token, waitId, startedAt);
+      } catch { /* unreadable and malformed claims are discarded */ }
+
+      await unlink(claimedFile).catch(() => undefined);
+      return accepted;
+    }
+    const controlPoll = createSerializedAsyncRunner(pollControlFile);
+
+    function settle(requestedOutcome: LimitsWaitWaitOutcome) {
       if (done) return;
       done = true;
+      const pendingPoll = controlPoll.pending();
+      const claimBarrier = pendingClaim;
       cleanup();
-      const endedAt = Date.now();
-      const actualElapsedMs = Math.max(0, endedAt - startedAt);
-      try { telemetry?.onEnd?.(actualElapsedMs, outcome); } catch { /* observational callback */ }
-      emitWaitTelemetry(events, {
-        ...common,
-        phase: "end",
-        endedAt,
-        actualElapsedMs,
-        outcome,
-      } satisfies LimitsWaitWaitEndPayload);
-      resolve(outcome);
+
+      void (async () => {
+        // Do not let wait N resolve (and wait N+1 begin) while N can still
+        // rename the canonical path. A token claimed at the deadline wins over
+        // the timer. Explicit skip/abort only drain the bounded claim phase;
+        // later reads and unique-path cleanup cannot affect a replacement.
+        let acceptedAtSettlement = false;
+        if (requestedOutcome === "waited") {
+          acceptedAtSettlement = await pendingPoll?.catch(() => false) ?? false;
+        } else {
+          await claimBarrier?.catch(() => undefined);
+        }
+        const outcome = acceptedAtSettlement ? "skipped" : requestedOutcome;
+        const endedAt = Date.now();
+        const actualElapsedMs = Math.max(0, endedAt - startedAt);
+        // Published before status cleanup so the consumer learns the outcome
+        // first and the cleared key stays the end-of-window marker.
+        publishStatusJson(statusPayload(
+          statusContext,
+          "wait_end",
+          livelinessText(reason, Math.max(0, plannedDeadline - endedAt), model, telemetry?.error),
+          0,
+          { outcome, actualElapsedMs },
+        ));
+        try { stopLiveliness(); } catch { /* UI unavailable */ }
+        try { telemetry?.onEnd?.(actualElapsedMs, outcome); } catch { /* observational callback */ }
+        emitWaitTelemetry(events, {
+          ...common,
+          phase: "end",
+          endedAt,
+          actualElapsedMs,
+          outcome,
+        } satisfies LimitsWaitWaitEndPayload);
+        resolve(outcome);
+      })();
     }
 
     if (signal?.aborted) {
@@ -295,10 +437,18 @@ export function waitForRetry(
       return;
     }
 
+    state.activeWaitSkips.add(skipWait);
+
     try {
       const unsubscribe = ctx?.ui.onTerminalInput((data) => {
         if (done) return undefined;
         if (data === "\r" || data === "\n") {
+          // Enter belongs to the editor whenever it contains text. In
+          // particular, slash-command autocomplete needs Enter to confirm and
+          // then execute a command; do not steal either press from it.
+          let editorText = "";
+          try { editorText = ctx?.ui.getEditorText() ?? ""; } catch { /* UI unavailable */ }
+          if (editorText.length > 0) return undefined;
           settle("skipped");
           return { consume: true };
         }
@@ -326,6 +476,10 @@ export function waitForRetry(
     tick();
     if (done) return;
     ticker = setInterval(() => {
+      const poll = controlPoll.run();
+      void poll.then((accepted) => {
+        if (accepted && !done) settle("skipped");
+      });
       if (Date.now() >= plannedDeadline) settle("waited");
       else tick();
     }, 1_000);