@monotykamary/pi-ledger 0.2.0 → 0.3.0

package/README.md

@@ -191,7 +191,11 @@ Idle with no output is wasted time.
   falls back to a `select` dialog; with **auto-extend** on, it skips the prompt
   and provisions a block silently. `agent_settled` fires once the run is fully settled (no
   auto-retry, compaction, or queued follow-up left), so the wizard never pops
-  mid-retry or mid-continuation. With credit, it stays silent and arms to fire
+  mid-retry or mid-continuation. When [@monotykamary/pi-retry](https://github.com/monotykamary/pi-retry) is installed, its
+  backoff sleep can make `agent_settled` fire mid-retry; pi-ledger captures
+  pi-retry's `started`/`completed`/`cancelled` events and defers the prompt
+  until the retry genuinely settles — it pops on `completed`, never on
+  `cancelled`, never while one is in flight. With credit, it stays silent and arms to fire
   when the engaged window's credit is exhausted; the exhaustion pop offers the
   next extension (the `extend + extend + extend` chain).
 - `/ledger-extend [m]` opens the wizard manually — with or without an open
@@ -396,7 +400,7 @@ current moment, including the in-progress open human window, from the sidecar
 
 ```bash
 pnpm install
-pnpm test            # vitest run (129 tests)
+pnpm test            # vitest run (140 tests)
 pnpm run typecheck   # tsc --noEmit
 pnpm run lint:dead   # knip
 ```

package/extensions/pi-ledger/__tests__/ledger.test.ts

@@ -23,6 +23,7 @@ import {
   fmtMoney,
   rehydrateFromSidecar,
   resolveExtensionBudget,
+  retryEventId,
   sidecarPathFor,
   type LedgerSettings,
   type ReceiptData,
@@ -2526,3 +2527,127 @@ describe('rehydrateFromSidecar — skip-billing guard', () => {
     expect(rehydrateFromSidecar([]).billingPaused).toBe(false);
   });
 });
+
+// ─── pi-retry capture (wizard gating) ────────────────────────────────────────
+// The engagement prompt (no rolling credit) lives at agent_settled. When
+// @monotykamary/pi-retry is installed, agent_settled can fire during a retry's
+// backoff sleep — before pi-retry has decided whether to re-prompt. pi-ledger
+// captures pi-retry's started/completed/cancelled events and DEFERS the prompt
+// until the retry settles, so the backoff is never billed as human time.
+// Mirrors localterm's agent-notify contract.
+
+describe('pi-retry capture (wizard gating)', () => {
+  let fixture: TestFixture;
+  let cacheDir: string;
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'pi-ledger-test-'));
+    process.env.XDG_CACHE_HOME = cacheDir;
+    fixture = createTestFixture();
+    await activateExtension(fixture);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    delete process.env.XDG_CACHE_HOME;
+    fs.rmSync(cacheDir, { recursive: true, force: true });
+  });
+
+  const STARTED = 'pi-retry:started';
+  const COMPLETED = 'pi-retry:completed';
+  const CANCELLED = 'pi-retry:cancelled';
+
+  it('pops the wizard at agent_settled when no pi-retry is active', () => {
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+    fixture.run('agent_settled', { type: 'agent_settled' });
+    expect(fixture.customSpy).toHaveBeenCalledTimes(1); // no credit → pop
+  });
+
+  it('defers the wizard while a pi-retry is in flight; pops on completed', () => {
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' });
+    fixture.run('agent_start', { type: 'agent_start' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    fixture.emitEvent(STARTED, { retryId: 1 });
+    fixture.run('agent_settled', { type: 'agent_settled' }); // retry in flight → defer
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+    fixture.emitEvent(COMPLETED, { retryId: 1 }); // retry settled → pop the deferred prompt
+    expect(fixture.customSpy).toHaveBeenCalledTimes(1);
+    expect(fixture.lastSidecarEvent('human-open')).toBeUndefined(); // still engagement-gated
+  });
+
+  it('waits for the final agent_settled when retry completion arrives first', () => {
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' });
+    fixture.run('agent_start', { type: 'agent_start' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    fixture.emitEvent(STARTED, { retryId: 2 });
+    fixture.run('agent_settled', { type: 'agent_settled' }); // retry in flight → defer
+    // the retry turn fires (a new run supersedes the stale deferred prompt)
+    fixture.run('agent_start', { type: 'agent_start' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    // retry completes BEFORE the run settles → pending was cleared by agent_start → no pop
+    fixture.emitEvent(COMPLETED, { retryId: 2 });
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+    fixture.run('agent_settled', { type: 'agent_settled' }); // now settled, no retry active → pop
+    expect(fixture.customSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('never pops when a pi-retry is cancelled', () => {
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' });
+    fixture.run('agent_start', { type: 'agent_start' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    fixture.emitEvent(STARTED, { retryId: 3 });
+    fixture.run('agent_settled', { type: 'agent_settled' }); // retry in flight → defer
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+    fixture.emitEvent(CANCELLED, { retryId: 3 }); // abort/session-change → drop the prompt
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+  });
+
+  it('ignores a completed event that does not match the active retry', () => {
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' });
+    fixture.run('agent_start', { type: 'agent_start' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    fixture.emitEvent(STARTED, { retryId: 4 });
+    fixture.run('agent_settled', { type: 'agent_settled' }); // defer (active id 4)
+    fixture.emitEvent(COMPLETED, { retryId: 999 }); // stray → ignored
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+    fixture.emitEvent(COMPLETED, { retryId: 4 }); // matching → pop
+    expect(fixture.customSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats a completed with no prior started as a no-op', () => {
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' });
+    fixture.emitEvent(COMPLETED, { retryId: 7 }); // no retry active → stray event
+    expect(fixture.customSpy).not.toHaveBeenCalled();
+  });
+
+  it('defers auto-extend too while a pi-retry is in flight; extends on completed', () => {
+    fixture.seedSidecar([
+      { kind: 'settings', settings: { ...DEFAULTS, autoExtend: true }, timestamp: 0 },
+    ]);
+    fixture.run('session_start', { type: 'session_start', reason: 'startup' }); // rehydrate → autoExtend on
+    fixture.run('agent_start', { type: 'agent_start' });
+    fixture.run('agent_end', { type: 'agent_end', messages: [] });
+    fixture.emitEvent(STARTED, { retryId: 5 });
+    fixture.run('agent_settled', { type: 'agent_settled' }); // retry in flight → defer auto-extend
+    expect(fixture.readSidecarEvents().filter((e) => e.kind === 'human-open')).toHaveLength(0);
+    fixture.emitEvent(COMPLETED, { retryId: 5 }); // settled → auto-extend provisions a block + engages
+    const open = fixture.lastSidecarEvent('human-open');
+    expect(open).toBeDefined();
+    expect(open!.engagedVia).toBe('extension'); // auto-extend engages via extension
+  });
+});
+
+describe('retryEventId', () => {
+  it('returns the retryId of a pi-retry event', () => {
+    expect(retryEventId({ retryId: 42 })).toBe(42);
+  });
+  it('returns undefined when retryId is absent or malformed', () => {
+    expect(retryEventId(undefined)).toBeUndefined();
+    expect(retryEventId(null)).toBeUndefined();
+    expect(retryEventId({})).toBeUndefined();
+    expect(retryEventId({ retryId: 'oops' })).toBeUndefined();
+  });
+});

package/extensions/pi-ledger/index.ts

@@ -72,6 +72,19 @@ const TPS_TELEMETRY_EVENT = 'tps:telemetry';
 /** Custom entry type written by @monotykamary/pi-tps into the session JSONL. */
 const TPS_CUSTOM_TYPE = 'tps';
 
+/** Custom events emitted by @monotykamary/pi-retry around its retry loop:
+ *  'started' (with a retryId) when the loop spins up, 'completed' when it
+ *  exits on success, 'cancelled' when it exits on abort/session-change.
+ *  pi-ledger subscribes so the engagement wizard does not pop mid-retry —
+ *  agent_settled can fire during a pi-retry backoff sleep (before pi-retry has
+ *  re-prompted), and popping then would bill the backoff as human time
+ *  (violating scale-to-zero: a slow/queued provider is a retry, not billable).
+ *  The prompt is deferred until the retry settles. Mirrors localterm's
+ *  agent-notify handshake. */
+const PI_RETRY_STARTED_EVENT = 'pi-retry:started';
+const PI_RETRY_COMPLETED_EVENT = 'pi-retry:completed';
+const PI_RETRY_CANCELLED_EVENT = 'pi-retry:cancelled';
+
 /** Minimum gap between streaming updates to count as an inference stall (ms). */
 const STALL_THRESHOLD_MS = 500;
 
@@ -847,6 +860,17 @@ function reveal(text: string): string {
   return ` data-reveal="${esc(text)}">`;
 }
 
+/** Pull the 'retryId' out of a @monotykamary/pi-retry event payload, or
+ *  'undefined' if it is absent/malformed. Used to match a 'completed'/
+ *  'cancelled' event back to its 'started' so pi-ledger only acts on its own
+ *  retry. Mirrors localterm's retry-event-id util. Pure.
+ *  @internal Exported for testing only. */
+export function retryEventId(event: unknown): number | undefined {
+  if (typeof event !== 'object' || event === null || !('retryId' in event)) return undefined;
+  const id = (event as { retryId?: unknown }).retryId;
+  return typeof id === 'number' ? id : undefined;
+}
+
 /**
  * Build a self-contained HTML receipt. White-on-white, Geist Mono, with
  * values that stream in autoregressively (char-by-char) on load.
@@ -1204,6 +1228,25 @@ export default function ledgerExtension(pi: ExtensionAPI) {
 
   let wizardTimer: ReturnType<typeof setTimeout> | null = null;
 
+  // pi-retry awareness: when @monotykamary/pi-retry is installed it emits
+  // pi-retry:started/completed/cancelled around its (possibly multi-attempt)
+  // retry loop. agent_settled can fire during a retry's backoff sleep —
+  // before pi-retry has decided whether to re-prompt — so without gating the
+  // wizard would pop mid-retry (billing the backoff as human time, violating
+  // scale-to-zero). We capture the active retryId and DEFER the settled
+  // prompt until the retry settles: pop only on 'completed', never on
+  // 'cancelled', and never while a retry is in flight. Mirrors localterm's
+  // agent-notify handshake.
+  let retryActiveId: number | undefined;
+  // The run settled (agent_settled fired, no rolling credit) but a retry was
+  // in flight, so the engagement prompt is pending until the retry completes.
+  // Cleared on pop, on agent_start (a new run supersedes the stale settled
+  // state), on retry cancelled, and at session boundaries.
+  let pendingSettledWizard: { ctx: ExtensionContext } | null = null;
+  // Unsubscribers for the pi-retry event capture (a session-scoped resource);
+  // torn down at session_shutdown. The factory re-binds on the next session.
+  let retryUnsubs: Array<() => void> = [];
+
   // Latest ctx (event-bus listeners for tps:telemetry don't receive one).
   let lastCtx: ExtensionContext | null = null;
 
@@ -1903,6 +1946,11 @@ export default function ledgerExtension(pi: ExtensionAPI) {
     // rule as an unclosed idle window: uncommitted, so not restored.
     pendingSteers = [];
     dequeuedBuffer = null;
+    // Reset pi-retry capture state — a fresh session has no in-flight retry and
+    // no deferred prompt (an unclosed prior session's retry could otherwise
+    // leak across the session boundary on a per-process extension instance).
+    retryActiveId = undefined;
+    pendingSettledWizard = null;
     // Wrap the input editor so keystrokes stage for billing: during a run they
     // feed a steer/followUp burst (committed on submit via `input`); between
     // turns the FIRST keystroke engages an idle window at its onset. Extends
@@ -1944,6 +1992,20 @@ export default function ledgerExtension(pi: ExtensionAPI) {
     // at shutdown was never committed, so it's abandoned and bills 0 (idle
     // with no output is wasted). Persisted as a close for replay cleanliness.
     closeHumanWindow(lastCtx, false);
+    // Tear down the pi-retry event capture (a session-scoped resource): the
+    // factory re-binds subscriptions on the next session, so unbind here to
+    // avoid leaking listeners across the session boundary. Reset the capture
+    // state too — no in-flight retry survives a session teardown.
+    for (const unsub of retryUnsubs) {
+      try {
+        unsub();
+      } catch {
+        // best-effort — ignore a stale bus
+      }
+    }
+    retryUnsubs = [];
+    retryActiveId = undefined;
+    pendingSettledWizard = null;
   });
 
   // ── Agent timing (tool execution) ─────────────────────────────────────
@@ -2044,6 +2106,41 @@ export default function ledgerExtension(pi: ExtensionAPI) {
   // extension load order — a 'fallback' may be corrected by a later 'tps'
   // entry for the same turnIndex (rehydrate keeps the last per turnIndex).
 
+  // ── pi-retry capture ─────────────────────────────────────────────────
+  // @monotykamary/pi-retry emits started/completed/cancelled around its
+  // (possibly multi-attempt) retry loop. agent_settled can land during a
+  // retry's backoff sleep — before pi-retry has re-prompted — so without this
+  // capture the engagement wizard would pop mid-retry, billing the backoff as
+  // human time (violating scale-to-zero: a slow/queued provider is a retry,
+  // not billable). Defer the settled prompt until the retry settles: pop on
+  // 'completed' (if still no credit), never on 'cancelled', never while one is
+  // in flight. Unsubscribed at session_shutdown (a session-scoped resource);
+  // the factory re-binds on the next session. Mirrors localterm's agent-notify.
+  retryUnsubs.push(
+    pi.events.on(PI_RETRY_STARTED_EVENT, (event: unknown) => {
+      retryActiveId = retryEventId(event);
+    })
+  );
+  retryUnsubs.push(
+    pi.events.on(PI_RETRY_COMPLETED_EVENT, (event: unknown) => {
+      if (retryEventId(event) !== retryActiveId) return;
+      retryActiveId = undefined;
+      const pending = pendingSettledWizard;
+      if (!pending) return;
+      pendingSettledWizard = null;
+      // Credit may have changed since settle (e.g. a mid-backoff /ledger-extend);
+      // with none, pop now that the retry has settled. With credit, stay quiet.
+      if (extensionBudgetMs <= 0) armWizardNow(pending.ctx);
+    })
+  );
+  retryUnsubs.push(
+    pi.events.on(PI_RETRY_CANCELLED_EVENT, (event: unknown) => {
+      if (retryEventId(event) !== retryActiveId) return;
+      retryActiveId = undefined;
+      pendingSettledWizard = null; // abort/session-change → no prompt
+    })
+  );
+
   pi.events.on(TPS_TELEMETRY_EVENT, (payload: unknown) => {
     const t = payload as TpsTelemetry | null;
     if (!t || !t.timing || !t.tokens || !t.model) return;
@@ -2159,6 +2256,11 @@ export default function ledgerExtension(pi: ExtensionAPI) {
     // If the human never engaged (no keystroke, no extension), there's no
     // window to close and the turn handoff bills nothing.
     closeHumanWindow(ctx, true);
+    // A new run supersedes any deferred settled prompt (a retry turn, a queued
+    // follow-up, or a fresh prompt all re-settle later — agent_settled
+    // re-evaluates then). Keeps a pi-retry that completes after a retry
+    // turn's agent_end from popping on a stale 'settled' until that run settles.
+    pendingSettledWizard = null;
   });
 
   pi.on('agent_end', (_event, ctx) => {
@@ -2208,7 +2310,22 @@ export default function ledgerExtension(pi: ExtensionAPI) {
     // after a retry storm exhausts — the last errored agent_end no longer
     // suppresses it, since the run has now settled and the human must take
     // over.
-    if (extensionBudgetMs <= 0) armWizardNow(ctx);
+    if (extensionBudgetMs <= 0) {
+      // @monotykamary/pi-retry (if installed) drives its own retry loop with
+      // backoff sleeps outside processEvents; pi-core's settlement detection
+      // can fire this agent_settled during that backoff — before pi-retry has
+      // decided whether to re-prompt. Popping then would bill the backoff as
+      // human time (violating scale-to-zero: a slow/queued provider is a
+      // retry, not billable). Defer: if a pi-retry is in flight, stage the
+      // prompt and pop when the retry settles (on pi-retry:completed); a
+      // cancelled retry never pops. With no pi-retry (or none active), pop now
+      // as before.
+      if (retryActiveId !== undefined) {
+        pendingSettledWizard = { ctx };
+      } else {
+        armWizardNow(ctx);
+      }
+    }
   });
 
   // The `input` event fires for every interactive submit that isn't a slash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-ledger",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Billing engine for the serverless agency — a pi extension that meters agentic dev work like cloud compute and invoices it like a timesheet.",
   "keywords": [
     "pi-package"