@oh-my-pi/pi-coding-agent 17.2.1 → 17.2.2

package/dist/types/session/codex-auto-reset.d.ts

@@ -1,111 +1,229 @@
 /**
- * Pure decision predicate for auto-redeeming a saved OpenAI Codex rate-limit
- * reset, plus the process-wide coordinator that serializes attempts.
+ * Pool-wide planner for spending saved OpenAI Codex rate-limit resets, plus
+ * the process-wide coordinator that serializes attempts.
  *
- * WHY THIS IS REACTIVE-ONLY (never proactive):
- * The only trustworthy "blocked right now" signal is a live 429 /
- * `usage_limit_reached` from a request authenticated as the session's active
- * Codex credential. The session hook calls this predicate from the usage-limit
- * branch of the retry pipeline, *after* free remedies (sibling-account switch)
- * fail and *before* model fallback. A proactive surface (the status-line usage
- * poll) cannot be used: at `used_percent < 100` the account is not actually
- * limited, so redeeming would be a credit-wasting no-op; at exactly 100 the
- * user may be idle, so the freshly-reset weekly window would tick away with
- * nobody working. Saved resets are a scarce, ~monthly, effectively
- * irreversible resource — every gate here is biased to precision over recall:
- * we would rather miss a redeem than waste a credit.
+ * A saved reset is a scarce, ~monthly credit — but it is also perishable:
+ * every credit carries an `expiresAt`, and an expired credit is worth exactly
+ * nothing. The planner therefore balances two failure modes instead of only
+ * one: wasting a credit on a window that would have healed anyway, and letting
+ * a credit die unspent. Two rules, evaluated over EVERY stored Codex account
+ * (not just the session's active one):
+ *
+ * - `expiring-credit` (salvage; any trigger): the account's soonest available
+ *   credit expires within `salvageHorizonMs` and the weekly window is at least
+ *   {@link SALVAGE_MIN_USED_FRACTION} used, so redeeming restores real quota.
+ *   The `keepCredits` reserve is deliberately ignored here — reserving a
+ *   credit that is about to expire preserves nothing. If the window resets
+ *   naturally before the credit expires, the next sweep sees a mostly-free
+ *   window and skips: the credit had nothing left to restore. The backend may
+ *   refuse a partial-usage consume with `nothing_to_reset`; that outcome is
+ *   NON-terminal — the episode is deferred (not buried), so the credit is
+ *   retried as usage grows or a window exhausts before expiry.
+ * - `blocked-account` (restore; `blocked` trigger only): a live 429 blocked
+ *   the turn and no sibling credential could take over, so the pool is dry.
+ *   Candidates are accounts with at least one genuinely exhausted chat window
+ *   — 5h primary or weekly secondary. A banked reset clears the account's
+ *   chat rate limits generally, not just the weekly window: OpenAI's own
+ *   client consumes one for a 5h-only block while the weekly window still has
+ *   ~80% headroom (openai/codex#28525). The natural unblock is the LATEST
+ *   reset among the exhausted windows (the account stays blocked until every
+ *   one rolls over) and must be far enough away to justify the spend, with
+ *   credits above the reserve. One candidate is redeemed — active account
+ *   first, then the account whose credit dies soonest — and the redeem clears
+ *   its credential blocks so the retry's re-rank picks it up.
+ *
+ * TRIGGERS: `blocked` runs from the usage-limit branch of the retry pipeline
+ * after sibling switch fails, on force-refreshed reports (the cached snapshot
+ * predates the 429 that got us there). `sweep` piggybacks on every successful
+ * usage-report fetch — the status line polls every 5 minutes while the TUI is
+ * open — so expiring credits are caught even when nothing is blocked.
  *
  * THE DECISION-2 TRAP (status MUST NOT be used to find the blocker):
  * `openai-codex.ts` applies the top-level `rate_limit.limit_reached` flag to
  * BOTH the primary (5h) and secondary (weekly) `buildUsageLimit` calls, so when
  * an account is blocked, *both* limit entries carry `status: "exhausted"`
  * regardless of which window is actually at 100%. Only `amount.usedFraction`
- * disambiguates which window is the real blocker. This module therefore keys
- * eligibility off exact limit ids (`openai-codex:primary` /
- * `openai-codex:secondary`) and `usedFraction`, never off `status`.
+ * disambiguates. This module keys eligibility off exact limit ids
+ * (`openai-codex:primary` / `openai-codex:secondary`) and `usedFraction`,
+ * never off `status`, so the plan names the true blocking window(s) and their
+ * real unblock time. Whether a short wait (e.g. a 5h-only block) is worth a
+ * credit is the `minBlockedMinutes` knob's call, not hardcoded fiat.
  *
- * ANTI-WASTE GATES (in evaluation order): the policy must not be set to "no";
- * the active model must be Codex (not Spark — a Spark block lives on a
- * separate meter and it is unknown whether a credit even resets it); a fresh
- * usage report for the active account must confirm `limitReached`; the WEEKLY
- * (secondary) window must be genuinely exhausted — a 5h-only block self-heals
- * within the hour, so a credit spent there buys nothing; the natural reset must be far
- * enough away to justify spending a ~30-day credit yet within one plausible
- * window length; a credit must be verifiably available above the reserve; and
- * the same block episode must not have been attempted already (debounce +
- * per-account cooldown). All of this is pure — no fetches, no IO. The only
- * stateful piece is the {@link CodexAutoRedeemCoordinator} container, whose
- * read-only views are passed in so the predicate itself stays deterministic.
+ * All of this is pure — no fetches, no IO. The only stateful piece is the
+ * {@link CodexAutoRedeemCoordinator} container, whose read-only views are
+ * passed in so the planner itself stays deterministic.
  */
-import type { OAuthAccountIdentity, ResetCreditTarget, UsageReport } from "@oh-my-pi/pi-ai";
+import type { OAuthAccountIdentity, ResetCreditAccountStatus, ResetCreditTarget, UsageReport } from "@oh-my-pi/pi-ai";
 import type { CodexAutoRedeemMode } from "../config/settings-schema.js";
-/** Weekly window counts as exhausted at `usedFraction >= 0.999` (used_percent >= 99.9). */
-export declare const WEEKLY_EXHAUSTED_MIN_FRACTION = 0.999;
+/** A chat window counts as exhausted at `usedFraction >= 0.999` (used_percent >= 99.9). */
+export declare const WINDOW_EXHAUSTED_MIN_FRACTION = 0.999;
 /** A weekly reset can never be more than one window length (7d) away; +1h slack for skew. */
-export declare const MAX_PLAUSIBLE_REMAINING_MS: number;
+export declare const MAX_PLAUSIBLE_WEEKLY_REMAINING_MS: number;
+/** A 5h reset can never be more than one window length (5h) away; +1h slack for skew. */
+export declare const MAX_PLAUSIBLE_PRIMARY_REMAINING_MS: number;
+/** Below this usage on BOTH chat windows a salvaged reset restores too little to bother (and risks a `nothing_to_reset` no-op). */
+export declare const SALVAGE_MIN_USED_FRACTION = 0.25;
+/** Retry spacing after a non-terminal consume outcome (`nothing_to_reset`, transport failure). */
+export declare const REDEEM_RETRY_DEFER_MS: number;
 /** Report must be no older than the 5-min usage cache TTL plus slack. */
 export declare const REPORT_FRESHNESS_MS: number;
-/** Per-account cooldown that catches blockKey drift across a minute boundary. */
+/** Per-account cooldown that catches attempt-key drift across a minute boundary. */
 export declare const ATTEMPT_COOLDOWN_MS = 60000;
-/** Minute bucket for blockKey, absorbing `reset_after_seconds`-derived jitter. */
+/** Minute bucket for attempt keys, absorbing `reset_after_seconds`/expiry jitter. */
 export declare const DEBOUNCE_BUCKET_MS = 60000;
+/** Floor between salvage sweeps; dedupe keys make sweeps idempotent, this just avoids useless re-planning. */
+export declare const SWEEP_MIN_INTERVAL_MS = 60000;
 export declare function shouldEvaluateCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean;
 export declare function shouldPromptCodexAutoRedeem(mode: CodexAutoRedeemMode): boolean;
-export type CodexAutoRedeemSkipReason = "disabled" | "wrong-provider" | "spark-model" | "no-identity" | "no-report" | "stale-report" | "not-limit-reached" | "weekly-not-exhausted" | "no-reset-time" | "reset-too-soon" | "reset-implausible" | "credits-unknown" | "reserve" | "already-attempted" | "cooldown";
-export interface CodexAutoRedeemInput {
+/** What woke the planner. `sweep` may only salvage; `blocked` may also restore. */
+export type CodexResetTrigger = "blocked" | "sweep";
+/** Why one account produced no action (or, with `accountKey: "*"`, a whole rule was off). */
+export type CodexResetSkipReason = "disabled" | "wrong-provider" | "spark-model" | "no-identity" | "stale-report" | "not-limit-reached" | "no-exhausted-window" | "deferred" | "no-reset-time" | "reset-too-soon" | "reset-implausible" | "credits-unknown" | "no-credits" | "reserve" | "no-expiring-credit" | "window-mostly-free" | "already-attempted" | "cooldown";
+export interface CodexResetPlanInput {
     nowMs: number;
-    /** `this.model.provider`. */
+    trigger: CodexResetTrigger;
+    /** `this.model.provider` — gates the `blocked-account` rule only. */
     provider: string;
-    /** `this.model.id`. */
+    /** `this.model.id` — gates the `blocked-account` rule only. */
     modelId: string;
     settings: {
-        autoRedeem: boolean;
+        enabled: boolean;
+        /** `blocked-account`: skip when the natural unblock is closer than this. */
         minBlockedMinutes: number;
+        /** `blocked-account`: never spend below this many remaining credits. */
         keepCredits: number;
+        /** `expiring-credit`: salvage window; `<= 0` disables the rule. */
+        salvageHorizonMs: number;
     };
-    /** `getOAuthAccountIdentity("openai-codex", sessionId)`, captured at hook entry before any await. */
+    /** Active account (marks the preferred restore candidate); may be undefined. */
     identity: OAuthAccountIdentity | undefined;
-    /** `session.fetchUsageReports()` (≤5-min cache). */
+    /** Usage reports for ALL stored accounts (one per account for Codex). */
     reports: UsageReport[] | null;
-    attemptedBlockKeys: ReadonlySet<string>;
+    attemptedKeys: ReadonlySet<string>;
+    /** Episodes parked by a non-terminal consume outcome, keyed by attempt key (epoch ms). */
+    deferredUntilByKey: ReadonlyMap<string, number>;
     lastAttemptAtByAccount: ReadonlyMap<string, number>;
+    /**
+     * Live 429 evidence for the ACTIVE account: absolute epoch ms when the
+     * provider said the account unblocks, derived from the usage-limit error's
+     * parsed retry hint AT THE ERROR (absolute, so slow usage IO between the
+     * error and planning cannot drift it). Authoritative when the usage report
+     * is stale or missing — the report layer can adopt a pre-block in-flight
+     * fetch or serve the last-good snapshot when `/wham/usage` fails (it is
+     * IP-throttled, so failure right after a 429 is common), and such a
+     * snapshot still shows `limitReached: false` with healthy windows. With no
+     * usable report at all, a candidate is synthesized from `identity` and the
+     * redeem re-checks credits live. Only used on `blocked`.
+     */
+    activeBlockUnblockAtMs?: number;
 }
-export interface CodexAutoRedeemRedeemDecision {
-    redeem: true;
+/** One credit to spend. `redeemResetCredit` picks the account's soonest-expiring credit. */
+export interface CodexResetAction {
+    reason: "blocked-account" | "expiring-credit";
     target: ResetCreditTarget;
     accountKey: string;
-    blockKey: string;
-    weeklyResetAtMs: number;
-    remainingMs: number;
-    availableCount: number;
+    /** Once-per-episode dedupe key; record in `attemptedKeys` BEFORE consuming. */
+    attemptKey: string;
+    /** Human label for notices/prompts (email preferred). */
+    label: string;
+    /** Redeemable credits per the report; undefined for a synthesized live-429 candidate. */
+    availableCount?: number;
+    weeklyUsedFraction?: number;
+    /** `blocked-account`: ms until the natural unblock (latest exhausted-window reset). */
+    remainingMs?: number;
+    /** `blocked-account`: the exhausted chat windows a redeem would clear. */
+    blockedWindows?: ("5h" | "weekly")[];
+    /** `expiring-credit`: the fuller chat window a redeem restores (for messaging). */
+    salvageWindow?: "5h" | "weekly";
+    /** `expiring-credit`: used fraction of {@link CodexResetAction.salvageWindow}. */
+    salvageUsedFraction?: number;
+    /** `expiring-credit`: ms until the credit expires. */
+    expiresInMs?: number;
+    /** True when this is the session's active account. */
+    active: boolean;
+}
+export interface CodexResetSkip {
+    /** Normalized account key, or `"*"` for a rule-wide gate. */
+    accountKey: string;
+    rule: "blocked-account" | "expiring-credit" | "account";
+    reason: CodexResetSkipReason;
+}
+export interface CodexResetPlan {
+    /** At most one `blocked-account` action (first), then salvages by soonest expiry. */
+    actions: CodexResetAction[];
+    /** Diagnostics for `logger.debug` and tests. */
+    skipped: CodexResetSkip[];
 }
-export type CodexAutoRedeemDecision = CodexAutoRedeemRedeemDecision | {
-    redeem: false;
-    reason: CodexAutoRedeemSkipReason;
-};
 /**
- * Decide whether to auto-redeem a saved Codex reset for the active account.
+ * Plan which saved Codex resets to spend right now. Pure: a function of the
+ * snapshot inputs only. Callers execute the returned actions in order,
+ * re-checking `attemptedKeys` immediately before each consume.
+ */
+export declare function planCodexResetRedemptions(input: CodexResetPlanInput): CodexResetPlan;
+/** One attempt per (account, weekly-reset-minute) block episode. */
+export declare function blockedAttemptKey(accountKey: string, weeklyResetsAtMs: number): string;
+/** One attempt per (account, credit-expiry-minute) salvage episode. */
+export declare function salvageAttemptKey(accountKey: string, creditExpiresAtMs: number): string;
+/**
+ * Overlay LIVE per-account credit state (from the dedicated
+ * `rate-limit-reset-credits` route) onto usage reports before a blocked pass.
  *
- * Pure: every gate below is a function of the snapshot inputs only. Order
- * matters — cheapest / most-decisive gates first so the common "not eligible"
- * paths short-circuit before any account/report matching.
+ * `/wham/usage` credit counts can be stale or pre-feature, and the usage
+ * provider only consults the live detail endpoint when the usage payload
+ * already reports a POSITIVE count — a stale ZERO is never corrected there.
+ * Live data therefore replaces the report's credit block wholesale; accounts
+ * with no live row (or a failed lookup) get the block stripped, so the planner
+ * treats them as `credits-unknown` instead of trusting a stale count: siblings
+ * stay conservative while the active account can still be synthesized from
+ * live 429 evidence (the redeem re-lists atomically either way).
+ */
+export declare function overlayLiveResetCredits(reports: UsageReport[] | null, statuses: readonly ResetCreditAccountStatus[]): UsageReport[] | null;
+/**
+ * Whether a consume outcome permanently settles its episode. Terminal codes
+ * either spent the credit (`reset`), or prove this credit can never be spent
+ * (`already_redeemed`, `no_credit` — a live listing that really had nothing).
+ * Everything else — `nothing_to_reset` (limits not constrained enough right
+ * now), `credit_list_failed` (flaky listing), thrown transport failures,
+ * unknown codes — leaves the credit banked: the executor releases the attempt
+ * key and
+ * defers the episode by {@link REDEEM_RETRY_DEFER_MS} instead of burying a
+ * live credit for the rest of the process.
  */
-export declare function evaluateCodexAutoRedeem(input: CodexAutoRedeemInput): CodexAutoRedeemDecision;
+export declare function isTerminalRedeemOutcome(code: string): boolean;
 /**
  * Process-wide (NOT per-session) coordinator state. Parallel subagent sessions
  * share the same Codex accounts and must not race a double-spend, so this is a
  * single shared container, not a per-session field.
  *
- * - `attemptedBlockKeys`: one attempt EVER per block episode, regardless of
- *   outcome — recorded before calling the consume so exceptions can't re-enter.
+ * - `attemptedKeys`: one attempt per episode key — recorded before calling the
+ *   consume so exceptions can't re-enter. Non-terminal outcomes (see
+ *   {@link isTerminalRedeemOutcome}) release the key again and park the
+ *   episode in `deferredUntilByKey` instead.
+ * - `deferredUntilByKey`: earliest retry time for episodes whose consume was
+ *   refused non-terminally (`nothing_to_reset`, transport failure).
  * - `lastAttemptAtByAccount`: per-account cooldown timestamps (epoch ms),
- *   catching blockKey drift across a minute boundary.
- * - `inFlightByAccount`: serializes per account — a second session for the same
- *   account adopts the in-flight promise instead of starting a second consume.
+ *   catching attempt-key drift across a minute boundary.
+ * - `inFlightByAccount`: serializes blocked passes per account — a second
+ *   session for the same account adopts the in-flight promise instead of
+ *   starting a second consume.
+ * - `sweepInFlight` / `lastSweepAt` / `sweepPromise`: re-entrancy guard, floor,
+ *   and settlement handle for the salvage sweep (a redeem refreshes usage,
+ *   which would recurse into a sweep; the promise lets tests and diagnostics
+ *   await a fire-and-forget sweep instead of polling).
+ * - `notifiedKeys`: headless "run /usage reset" notices already emitted, so a
+ *   5-minute sweep cadence can't spam the transcript.
  */
 export interface CodexAutoRedeemCoordinator {
-    attemptedBlockKeys: Set<string>;
+    attemptedKeys: Set<string>;
+    deferredUntilByKey: Map<string, number>;
     lastAttemptAtByAccount: Map<string, number>;
     inFlightByAccount: Map<string, Promise<boolean>>;
+    sweepInFlight: boolean;
+    lastSweepAt: number;
+    /** Settlement of the most recently scheduled sweep (never rejects). */
+    sweepPromise: Promise<void> | undefined;
+    notifiedKeys: Set<string>;
 }
+/** Fresh, empty coordinator: backs the process-wide default; inject one per test for isolation. */
+export declare function createCodexAutoRedeemCoordinator(): CodexAutoRedeemCoordinator;
 export declare const defaultCodexAutoRedeemCoordinator: CodexAutoRedeemCoordinator;

package/dist/types/session/session-storage.d.ts

@@ -6,14 +6,17 @@ export interface SessionStorageStat {
 }
 export interface SessionStorageWriter {
     /**
-     * Append one newline-terminated line. File and memory storage perform the
-     * write synchronously in-body; indexed backends queue in call order.
+     * Append one newline-terminated line. File storage batches same-turn appends
+     * until its microtask boundary; memory storage updates in-body; indexed
+     * backends queue in call order.
      *
      * `line` MUST include the trailing newline.
      */
     append(line: string): Promise<void>;
     /** Resolve once all queued appends complete. No fsync. */
     flush(): Promise<void>;
+    /** Drain synchronously flushable queued work when the backend supports it. No fsync. */
+    flushSync?(): void;
     /** False once close() has begun/finished. */
     isOpen(): boolean;
     close(): Promise<void>;

package/dist/types/session/session-tools.d.ts

@@ -50,6 +50,7 @@ interface SessionToolsOptions {
     ensureWriteRegistered?: () => Promise<boolean>;
     rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{
         systemPrompt: string[];
+        xdevCatalogNames?: readonly string[];
     }>;
     getLocalCalendarDate?: () => string;
     getMcpServerInstructions?: () => Map<string, string> | undefined;
@@ -159,7 +160,7 @@ export declare class SessionTools {
      */
     resetAnnouncedMounts(): void;
     /** Consumes the hidden notice for unannounced `xd://` mount changes. */
-    takePendingXdevMountNotice(): CustomMessage<XdevMountNoticeDetails> | undefined;
+    takePendingXdevMountNotice(baseCatalogDelivered: boolean): CustomMessage<XdevMountNoticeDetails> | undefined;
     /** Rediscovers reloadable skills and refreshes prompt metadata. */
     refreshSkills(): Promise<void>;
     /** Selects enabled tools, ignoring names absent from the registry. */

package/dist/types/session/turn-recovery.d.ts

@@ -46,7 +46,13 @@ export interface TurnRecoveryHost {
     sessionMessageAlreadyPersisted(message: AssistantMessage): boolean;
     setModelWithProviderSessionReset(model: Model): Promise<void>;
     resetCurrentResponsesProviderSession(reason: string): void;
-    maybeAutoRedeemCodexReset(): Promise<boolean>;
+    /**
+     * Spend a saved Codex reset for the blocked pool, if eligible.
+     * `activeBlockUnblockAtMs` is the absolute unblock time parsed from the
+     * live usage-limit error — authoritative for the active account when the
+     * usage report still shows a pre-block snapshot.
+     */
+    maybeAutoRedeemCodexReset(activeBlockUnblockAtMs?: number): Promise<boolean>;
     runAutoCompaction(reason: "overflow" | "threshold" | "idle" | "incomplete", willRetry: boolean, deferred?: boolean, allowDefer?: boolean, options?: {
         autoContinue?: boolean;
         triggerContextTokens?: number;

package/dist/types/system-prompt.d.ts

@@ -148,6 +148,14 @@ export interface BuildSystemPromptOptions {
 export interface BuildSystemPromptResult {
     /** Ordered system prompt blocks. Providers should preserve entries as distinct messages/blocks. */
     systemPrompt: string[];
+    /**
+     * Names of `xd://` devices whose catalog/protocol section this prompt renders.
+     * Empty/undefined when no catalog was emitted (no mounted devices, or a custom
+     * prompt template that omits the section). Lets the session fold these devices
+     * into its announced-mount baseline so a same-turn mount notice does not re-list
+     * a catalog the prompt already carries (issue #7139).
+     */
+    xdevCatalogNames?: readonly string[];
 }
 /** Build the system prompt with tools, guidelines, and context */
 export declare function buildSystemPrompt(options?: BuildSystemPromptOptions): Promise<BuildSystemPromptResult>;

package/dist/types/task/executor.d.ts

@@ -250,6 +250,33 @@ export declare function finalizeSubprocessOutput(args: FinalizeSubprocessOutputA
 export declare function createMCPProxyTools(mcpManager: MCPManager): CustomTool[];
 export declare function createSubagentSettings(baseSettings: Settings, overrides?: Partial<Record<SettingPath, unknown>>, inheritedServiceTier?: ServiceTierByFamily | null): Settings;
 export type AbortReason = "signal" | "terminate" | "timeout" | "budget";
+/** Inputs for {@link attachIrcWakeTurnMonitor}. */
+export interface IrcWakeTurnMonitorOptions {
+    /** Registry id of the kept-alive subagent whose autonomous IRC wake turns are monitored. */
+    id: string;
+    index?: number;
+    agent: AgentDefinition;
+    description?: string;
+    modelOverride?: string | string[];
+    eventBus?: EventBus;
+    parentToolCallId?: string;
+    /** Fallback session file when the registry ref carries none. */
+    sessionFile?: string;
+    maxRuntimeMs?: number;
+    outputSchema?: unknown;
+    outputSchemaMode?: StructuredSubagentSchemaMode;
+    outputSchemaSource?: StructuredSubagentSchemaSource;
+    artifactsDir?: string;
+}
+/**
+ * Bracket a kept-alive subagent's autonomous IRC wake turns with a task run
+ * monitor so RPC/collab subscribers see the same `subagent_lifecycle` /
+ * `subagent_progress` frames a first run emits. Shared by the live executor
+ * reviver and the persisted cold-revive path so a resumed process's parked
+ * subagents are not blind spots. The observer runs after the session has
+ * flushed its post-prompt settle (see {@link AgentSession.setIrcWakeTurnObserver}).
+ */
+export declare function attachIrcWakeTurnMonitor(session: AgentSession, options: IrcWakeTurnMonitorOptions): void;
 /**
  * Settle a subagent's registry lifecycle after a run: terminal teardown for
  * hard aborts, unregister for one-shot helpers, park for isolated runs, and

package/dist/types/task/persisted-revive.d.ts

@@ -3,6 +3,7 @@ import type { Settings } from "../config/settings.js";
 import type { PersistedSubagentReviverFactory } from "../registry/agent-lifecycle.js";
 import type { AgentSession } from "../session/agent-session.js";
 import type { AuthStorage } from "../session/auth-storage.js";
+import type { EventBus } from "../utils/event-bus.js";
 /**
  * Ambient context the reviver needs at revive time. The top-level session is
  * kept LIVE (cwd / artifact manager read on demand) so a later `/new` or cwd
@@ -16,6 +17,12 @@ export interface PersistedSubagentReviveContext {
     settings: Settings;
     /** LSP policy of the top-level session; revived subagents inherit it rather than defaulting on. */
     enableLsp: boolean;
+    /**
+     * Shared event bus feeding RPC/collab subagent subscriptions. Passed through
+     * to the wake-turn monitor so an IRC send to a cold-revived subagent emits
+     * the same lifecycle/progress frames a live run does.
+     */
+    eventBus?: EventBus;
 }
 /**
  * Build the factory the {@link AgentLifecycleManager} uses to cold-revive a

package/dist/types/tools/bash-interceptor.d.ts

@@ -21,4 +21,4 @@ export interface InterceptionResult {
  * @param availableTools Set of tool names that are available
  * @returns InterceptionResult indicating if the command should be blocked
  */
-export declare function checkBashInterception(command: string, availableTools: string[], rules?: BashInterceptorRule[]): InterceptionResult;
+export declare function checkBashInterception(command: string, availableTools: string[], rules?: BashInterceptorRule[], originalCommand?: string): InterceptionResult;

package/dist/types/tools/browser/attach.d.ts

@@ -16,12 +16,20 @@ export declare function findReusableCdp(exe: string, signal?: AbortSignal): Prom
     cdpUrl: string;
     pid: number;
 } | null>;
+export declare function shouldPreserveConnectedBrowserFocus(target?: string): boolean;
 /**
  * Pick the best page target on an attached browser. Prefer discoverable page
  * targets first so Chromium/Edge attach flows that hide pages from
  * `browser.pages()` can still return a usable tab.
+ *
+ * `preferVisible` is for attaching to a browser a human is using: among equally
+ * usable tabs, take the one that is actually foregrounded rather than whichever
+ * target CDP happens to enumerate first.
  */
-export declare function pickElectronTarget(browser: Browser, matcher?: string): Promise<Page>;
+export declare function pickElectronTarget(browser: Browser, options?: {
+    matcher?: string;
+    preferVisible?: boolean;
+}): Promise<Page>;
 /**
  * SIGTERM the process tree, wait briefly, then SIGKILL anything still alive.
  * Single-process variant for our own spawned children.

package/dist/types/tools/browser/launch.d.ts

@@ -27,7 +27,26 @@ export interface LaunchHeadlessOptions {
     /** Additional exact Puppeteer default arguments to suppress. */
     ignoreDefaultArgs?: readonly string[];
 }
-export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<Browser>;
+/** Result of a headless Chromium launch. */
+export interface LaunchHeadlessResult {
+    browser: Browser;
+    /**
+     * OMP-owned temporary Chromium profile directory to remove after the browser
+     * process tree exits, or `undefined` when the caller supplied its own
+     * `--user-data-dir` (which OMP must not delete).
+     */
+    userDataDir?: string;
+}
+export declare function launchHeadlessBrowser(opts: LaunchHeadlessOptions): Promise<LaunchHeadlessResult>;
+/**
+ * Remove an OMP-owned headless Chromium profile directory, tolerating the brief
+ * window on Windows in which Chromium (or an orphaned browser subprocess) still
+ * holds the profile lock. The shared temp remover centralizes retry handling
+ * for EBUSY/EPERM/ENOTEMPTY; if the directory is still busy afterwards we warn
+ * and leave it for a later cleanup pass rather than throwing — a shutdown cleanup
+ * failure must never crash the process (issue #7058).
+ */
+export declare function removeUserDataDir(dir: string): Promise<void>;
 export declare function applyViewport(page: Page, viewport?: {
     width: number;
     height: number;

package/dist/types/tools/browser/registry.d.ts

@@ -25,6 +25,8 @@ export interface PuppeteerBrowserHandle extends BrowserHandleCommon {
     browser: Browser;
     cdpUrl?: string;
     pid?: number;
+    /** OMP-owned temp Chromium profile directory removed on dispose (headless launches). */
+    userDataDir?: string;
     subprocess?: Subprocess;
     stealth: {
         browserSession: CDPSession | null;

package/dist/types/tools/browser/tab-protocol.d.ts

@@ -59,12 +59,20 @@ export type WorkerInitPayload = {
     safeDir: string;
     targetId: string;
     dialogs?: "accept" | "dismiss";
+    url?: string;
+    waitUntil?: "load" | "domcontentloaded" | "networkidle0" | "networkidle2";
+    timeoutMs: number;
     /**
      * Post-timeout recycle: before adopting the page, dismiss any open JS dialog and
      * stop a pending navigation so a blocked target cannot stall worker init (which
      * previously force-killed the tab). Never set for first-time Electron attach.
      */
     recover?: boolean;
+    /**
+     * Whether the worker may raise this tab before capturing a screenshot. Unset
+     * behaves as `true`; the supervisor clears it for browsers we did not launch.
+     */
+    activateForScreenshot?: boolean;
 };
 export type ToolReply = {
     ok: true;

package/dist/types/tools/browser/tab-supervisor.d.ts

@@ -47,6 +47,7 @@ interface TabSessionBase<TBrowser extends BrowserHandle = BrowserHandle> {
 export interface WorkerTabSession extends TabSessionBase<PuppeteerBrowserHandle> {
     backend: "worker";
     worker: WorkerHandle;
+    activateForScreenshot: boolean;
 }
 export interface CmuxTabSession extends TabSessionBase<CmuxBrowserHandle> {
     backend: "cmux";

package/dist/types/tools/browser/tab-worker.d.ts

@@ -1,5 +1,5 @@
 import type { HTMLElement } from "linkedom";
-import type { ElementHandle } from "puppeteer-core";
+import type { ElementHandle, Page } from "puppeteer-core";
 import type { Transport } from "./tab-protocol.js";
 declare module "puppeteer-core" {
     interface Frame {
@@ -15,6 +15,7 @@ declare global {
     var innerHeight: number;
     var document: {
         elementFromPoint(x: number, y: number): Element | null;
+        readonly visibilityState: "visible" | "hidden";
     };
 }
 export interface OpTimeouts {
@@ -66,6 +67,7 @@ export interface InflightOp {
 }
 /** Human-readable label for a screenshot op, used in op tracking + timeout errors. */
 export declare function describeScreenshot(opts?: ScreenshotOptions): string;
+export declare function preparePageForScreenshot(page: Pick<Page, "bringToFront" | "evaluate">, signal: AbortSignal | undefined, activate: boolean): Promise<void>;
 /** Summarize still-running helpers (oldest first) so a cell timeout names what stalled. */
 export declare function describeInflight(inflight: Map<number, InflightOp>): string;
 export declare class WorkerCore {

package/dist/types/tools/shell-tokenize.d.ts

@@ -12,3 +12,14 @@
  * cannot find the structure they need.
  */
 export declare function tokenizeShellSegments(command: string): string[][];
+/**
+ * Returns the original text of flat shell command segments. Unlike
+ * `tokenizeShellSegments`, this preserves quoting and escaping so the results
+ * are safe to match against user-configured regular expressions.
+ *
+ * The extractor deliberately declines to split syntax whose execution context
+ * cannot be determined with this small scanner (heredocs, command substitution,
+ * backticks, grouping, and malformed quoting). Callers must still check the
+ * complete input in that case.
+ */
+export declare function extractFlatShellCommandSegments(command: string): string[];

package/dist/types/utils/image-loading.d.ts

@@ -48,6 +48,8 @@ export declare class ImageInputTooLargeError extends Error {
     readonly maxBytes: number;
     constructor(bytes: number, maxBytes: number);
 }
+/** Converts an image to PNG, rejecting when the runtime cannot decode or encode it. */
+export declare function convertImageToPng(image: ImageContent): Promise<ImageContent>;
 export declare function ensureSupportedImageInput(image: ImageContent): Promise<ImageContent | null>;
 export interface NormalizeModelContextImagesOptions {
     /** Model the images are bound for; used to derive encoder constraints (WebP exclusion for Ollama). */

package/dist/types/web/search/providers/duckduckgo.d.ts

@@ -2,6 +2,15 @@ import type { AuthStorage } from "@oh-my-pi/pi-ai";
 import type { SearchResponse } from "../../../web/search/types.js";
 import type { SearchParams } from "./base.js";
 import { SearchProvider } from "./base.js";
+/**
+ * Map a parsed `lang:` locale onto DuckDuckGo's documented `kl` values.
+ *
+ * Shared queries use `language-region` order while DDG generally uses
+ * `region-language`. Provider-specific exceptions resolve through
+ * {@link DDG_LOCALE_ALIASES}; all other values must survive the documented
+ * allowlist after swapping or the caller keeps its default region.
+ */
+export declare function localeToKl(lang: string | undefined): string | undefined;
 /** Execute a DuckDuckGo web search via the no-JS HTML frontend. */
 export declare function searchDuckDuckGo(params: SearchParams): Promise<SearchResponse>;
 /** Search provider for DuckDuckGo (no API key required). */

package/dist/types/web/search/types.d.ts

@@ -26,7 +26,7 @@ export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
 }, {
     readonly value: "xai";
     readonly label: "xAI";
-    readonly description: "Grok web search via xAI Responses API (requires XAI_API_KEY)";
+    readonly description: "Grok web search via xAI Responses API (uses SuperGrok/X Premium+ OAuth via /login xai-oauth, or XAI_API_KEY)";
 }, {
     readonly value: "zai";
     readonly label: "Z.AI";
@@ -128,7 +128,7 @@ export declare const SEARCH_PROVIDER_CHOICES: ({
 } | {
     readonly value: "xai";
     readonly label: "xAI";
-    readonly description: "Grok web search via xAI Responses API (requires XAI_API_KEY)";
+    readonly description: "Grok web search via xAI Responses API (uses SuperGrok/X Premium+ OAuth via /login xai-oauth, or XAI_API_KEY)";
 } | {
     readonly value: "zai";
     readonly label: "Z.AI";