@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/context-budget.ts

@@ -0,0 +1,175 @@
+/**
+ * Privacy-safe context-budget attribution for DevSpec Pi.
+ *
+ * The store accepts numbers and generated/registered tool names only. Prompt,
+ * instruction, context-file, skill, argument, and result bodies never enter it.
+ * State lives on globalThis because Pi loads each extension file in an isolated
+ * jiti module graph.
+ */
+
+export interface StaticContextBudget {
+	systemPromptChars: number;
+	activeToolCount: number;
+	activeToolDefinitionChars: number;
+	contextFileCount: number;
+	contextFileChars: number;
+	skillCount: number;
+	skillChars: number;
+}
+
+export interface InjectedContextBudget {
+	attachChars: number;
+	roomDigestChars: number;
+	recallChars: number;
+	conflictNudgeChars: number;
+	totalChars: number;
+}
+
+export interface ToolResultBudget {
+	verb: string;
+	calls: number;
+	chars: number;
+	maxChars: number;
+}
+
+export interface ContextBudgetReport {
+	v: 1;
+	static: StaticContextBudget;
+	injected: InjectedContextBudget;
+	toolResults: {
+		calls: number;
+		chars: number;
+		maxChars: number;
+		byVerb: ToolResultBudget[];
+	};
+}
+
+export type InjectionKind = "attach" | "roomDigest" | "recall" | "conflictNudge";
+
+interface MutableState {
+	safeToolNames: Set<string>;
+	static: StaticContextBudget;
+	injected: Omit<InjectedContextBudget, "totalChars">;
+	toolResults: Map<string, Omit<ToolResultBudget, "verb">>;
+}
+
+const ZERO_STATIC: StaticContextBudget = {
+	systemPromptChars: 0,
+	activeToolCount: 0,
+	activeToolDefinitionChars: 0,
+	contextFileCount: 0,
+	contextFileChars: 0,
+	skillCount: 0,
+	skillChars: 0,
+};
+
+const ZERO_INJECTED: Omit<InjectedContextBudget, "totalChars"> = {
+	attachChars: 0,
+	roomDigestChars: 0,
+	recallChars: 0,
+	conflictNudgeChars: 0,
+};
+
+const STORE_KEY = Symbol.for("devspec.pi.context-budget.v1");
+
+function nonNegativeInteger(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value > 0
+		? Math.round(value)
+		: 0;
+}
+
+function newState(): MutableState {
+	return {
+		safeToolNames: new Set<string>(),
+		static: { ...ZERO_STATIC },
+		injected: { ...ZERO_INJECTED },
+		toolResults: new Map(),
+	};
+}
+
+function state(): MutableState {
+	const root = globalThis as typeof globalThis & { [STORE_KEY]?: MutableState };
+	if (!root[STORE_KEY]) root[STORE_KEY] = newState();
+	return root[STORE_KEY];
+}
+
+/** Replace the generated allowlist used for per-tool attribution. */
+export function registerContextBudgetToolNames(names: readonly string[]): void {
+	state().safeToolNames = new Set(names.filter((name) => /^[a-z][a-z0-9_]{0,79}$/.test(name)));
+}
+
+/** Latest static prompt/tool/resource footprint for the current agent run. */
+export function noteStaticContextBudget(value: Partial<StaticContextBudget>): void {
+	const current = state();
+	current.static = {
+		systemPromptChars: nonNegativeInteger(value.systemPromptChars),
+		activeToolCount: nonNegativeInteger(value.activeToolCount),
+		activeToolDefinitionChars: nonNegativeInteger(value.activeToolDefinitionChars),
+		contextFileCount: nonNegativeInteger(value.contextFileCount),
+		contextFileChars: nonNegativeInteger(value.contextFileChars),
+		skillCount: nonNegativeInteger(value.skillCount),
+		skillChars: nonNegativeInteger(value.skillChars),
+	};
+}
+
+/** Add one tail-injected context block by numeric size only. */
+export function noteInjectedContext(kind: InjectionKind, chars: number): void {
+	const n = nonNegativeInteger(chars);
+	if (!n) return;
+	const injected = state().injected;
+	if (kind === "attach") injected.attachChars += n;
+	else if (kind === "roomDigest") injected.roomDigestChars += n;
+	else if (kind === "recall") injected.recallChars += n;
+	else injected.conflictNudgeChars += n;
+}
+
+/** Add one model-visible DevSpec tool result. Unknown names fail closed. */
+export function noteModelToolResult(verb: string, chars: number): void {
+	const current = state();
+	if (!current.safeToolNames.has(verb)) return;
+	const n = nonNegativeInteger(chars);
+	const prior = current.toolResults.get(verb) ?? { calls: 0, chars: 0, maxChars: 0 };
+	current.toolResults.set(verb, {
+		calls: prior.calls + 1,
+		chars: prior.chars + n,
+		maxChars: Math.max(prior.maxChars, n),
+	});
+}
+
+/**
+ * Snapshot one settled run and clear only its dynamic injected/result counters.
+ * Static footprint remains as the last-known value for idle heartbeat refreshes.
+ */
+export function takeContextBudgetReport(): ContextBudgetReport {
+	const current = state();
+	// Every verb this run used: one numeric row each, so the report adds up to its totals.
+	const byVerb = [...current.toolResults.entries()]
+		.map(([verb, value]) => ({ verb, ...value }))
+		.sort((a, b) => b.chars - a.chars || a.verb.localeCompare(b.verb));
+	const injectedBase = { ...current.injected };
+	const injected: InjectedContextBudget = {
+		...injectedBase,
+		totalChars: Object.values(injectedBase).reduce((sum, value) => sum + value, 0),
+	};
+	const toolValues = [...current.toolResults.values()];
+	const report: ContextBudgetReport = {
+		v: 1,
+		static: { ...current.static },
+		injected,
+		toolResults: {
+			calls: toolValues.reduce((sum, value) => sum + value.calls, 0),
+			chars: toolValues.reduce((sum, value) => sum + value.chars, 0),
+			maxChars: toolValues.reduce((max, value) => Math.max(max, value.maxChars), 0),
+			byVerb,
+		},
+	};
+	current.injected = { ...ZERO_INJECTED };
+	current.toolResults.clear();
+	return report;
+}
+
+/** Test/reload helper; not used by the model surface. */
+export function resetContextBudgetState(): void {
+	const root = globalThis as typeof globalThis & { [STORE_KEY]?: MutableState };
+	root[STORE_KEY] = newState();
+}

package/extensions/core/control-result-outbox.ts

@@ -0,0 +1,80 @@
+import type { ModelCatalogSnapshot } from './model-catalog.ts';
+
+export const CONTROL_RESULT_ENTRY = 'devspec-control-result-v1';
+export type ControlResult = { status: 'completed' } | { status: 'failed'; error: 'model_catalog_unavailable' | 'control_failed' };
+export interface ProducedControlResult {
+  connectionId: string;
+  controlId: string;
+  result: ControlResult;
+  catalog?: ModelCatalogSnapshot;
+  collectionMs?: number;
+}
+export type ControlResultEntry =
+  | { phase: 'produced'; value: ProducedControlResult }
+  | { phase: 'acknowledged' | 'superseded'; connectionId: string; controlId: string };
+export type ControlDeliveryOutcome = 'acknowledged' | 'superseded';
+type Persist = (value: ControlResultEntry) => void;
+
+/** Session-journal-backed results: retry delivery, not execution (33d1e0a1). */
+export class ControlResultOutbox {
+  private pending = new Map<string, ProducedControlResult>();
+  private handled = new Set<string>();
+  private sending = false;
+
+  private key(connectionId: string, controlId: string): string { return JSON.stringify([connectionId, controlId]); }
+  has(connectionId: string, controlId: string): boolean { return this.handled.has(this.key(connectionId, controlId)); }
+  hasPending(connectionId: string): boolean { return [...this.pending.values()].some(value => value.connectionId === connectionId); }
+
+  produce(value: ProducedControlResult, persist: Persist): void {
+    const key = this.key(value.connectionId, value.controlId);
+    if (this.handled.has(key)) return;
+    // Retain in memory even when persistence throws; never execute twice in this runtime.
+    this.pending.set(key, value);
+    this.handled.add(key);
+    persist({ phase: 'produced', value });
+  }
+
+  static reconstruct(entries: readonly unknown[]): ControlResultOutbox {
+    const outbox = new ControlResultOutbox();
+    for (const raw of entries) {
+      if (!raw || typeof raw !== 'object') continue;
+      const entry = raw as { type?: unknown; customType?: unknown; data?: unknown };
+      if (entry.type !== 'custom' || entry.customType !== CONTROL_RESULT_ENTRY) continue;
+      const data = entry.data as ControlResultEntry | undefined;
+      if (!data || typeof data !== 'object') throw new Error('Invalid persisted CONTROL result');
+      if (data.phase === 'produced') {
+        const value = data.value;
+        if (!value || typeof value.connectionId !== 'string' || !value.connectionId || typeof value.controlId !== 'string' || !value.controlId ||
+          !value.result || (value.result.status !== 'completed' && !(value.result.status === 'failed' &&
+            (value.result.error === 'model_catalog_unavailable' || value.result.error === 'control_failed')))) {
+          throw new Error('Invalid persisted CONTROL result');
+        }
+        const key = outbox.key(value.connectionId, value.controlId);
+        if (!outbox.handled.has(key)) outbox.pending.set(key, value);
+        outbox.handled.add(key);
+      } else if ((data.phase === 'acknowledged' || data.phase === 'superseded') && typeof data.connectionId === 'string' && typeof data.controlId === 'string') {
+        const key = outbox.key(data.connectionId, data.controlId);
+        outbox.pending.delete(key);
+        outbox.handled.add(key);
+      } else throw new Error('Invalid persisted CONTROL result');
+    }
+    return outbox;
+  }
+
+  async drain(connectionId: string, send: (value: ProducedControlResult) => Promise<ControlDeliveryOutcome>, persist: Persist,
+    current: () => boolean = () => true): Promise<void> {
+    if (this.sending || !current()) return;
+    this.sending = true;
+    try {
+      for (const [key, value] of this.pending) {
+        if (value.connectionId !== connectionId || !current()) continue;
+        const outcome = await send(value);
+        if (!current()) return;
+        // Persist first. A crash or append failure retries result delivery only.
+        // A stale slot is superseded, not evidence this reply stored our result.
+        persist({ phase: outcome, connectionId, controlId: value.controlId });
+        this.pending.delete(key);
+      }
+    } finally { this.sending = false; }
+  }
+}

package/extensions/core/control.ts

@@ -0,0 +1,156 @@
+/**
+ * Owner-authority CONTROL execution (item c2cc8679 / d0d37274).
+ *
+ * Lifecycle only. Never authors conversational content.
+ */
+
+export const CONTROL_VERBS = ["abort", "set_model", "set_thinking", "compact", "clear", "reload", "list_models"] as const;
+export type ControlVerb = (typeof CONTROL_VERBS)[number];
+
+export interface ControlCommand {
+	id: string;
+	verb: ControlVerb;
+	issuedAt: string;
+	issuedByUserId: string;
+	args?: { model?: string; thinking?: string };
+}
+
+export function parseControlCommand(raw: unknown): ControlCommand | null {
+	if (!raw || typeof raw !== "object") return null;
+	const rec = raw as Record<string, unknown>;
+	if (typeof rec.id !== "string" || !rec.id.trim()) return null;
+	if (typeof rec.verb !== "string" || !(CONTROL_VERBS as readonly string[]).includes(rec.verb)) return null;
+	if (typeof rec.issuedAt !== "string") return null;
+	if (typeof rec.issuedByUserId !== "string") return null;
+	const argsRaw = rec.args && typeof rec.args === "object" ? (rec.args as Record<string, unknown>) : undefined;
+	return {
+		id: rec.id.trim(),
+		verb: rec.verb as ControlVerb,
+		issuedAt: rec.issuedAt,
+		issuedByUserId: rec.issuedByUserId,
+		args: argsRaw
+			? {
+					model: typeof argsRaw.model === "string" ? argsRaw.model : undefined,
+					thinking: typeof argsRaw.thinking === "string" ? argsRaw.thinking : undefined,
+				}
+			: undefined,
+	};
+}
+
+export interface ControlHost {
+	isIdle(): boolean;
+	abort(): void;
+	compact(): Promise<void> | void;
+	/** Empty this agent's conversation, keeping its session and DevSpec connection (item 6beb89c6). */
+	clear(): Promise<void> | void;
+	reload(): Promise<void> | void;
+	/** Set the requested level and read back the host's effective (possibly clamped) level. */
+	setThinkingLevel?(level: string): string;
+	setModel(modelId: string): Promise<boolean> | boolean;
+	notify(message: string): void;
+}
+
+/** Execute one CONTROL verb. Returns local feedback; the wire ack is consumption-only. */
+export async function executeControlCommand(cmd: ControlCommand, host: ControlHost): Promise<string> {
+	switch (cmd.verb) {
+		case "abort":
+			if (!host.isIdle()) host.abort();
+			return "aborted";
+		case "compact":
+			await host.compact();
+			return "compacted";
+		case "clear":
+			await host.clear();
+			return "cleared";
+		case "set_thinking": {
+			const level = cmd.args?.thinking;
+			if (!level) return "set_thinking missing level";
+			if (typeof host.setThinkingLevel !== "function") throw new Error("setThinkingLevel is not available");
+			const effectiveLevel = host.setThinkingLevel(level);
+			return `thinking=${effectiveLevel}`;
+		}
+		case "set_model": {
+			const model = cmd.args?.model;
+			if (!model) return "set_model missing model";
+			const ok = await host.setModel(model);
+			return ok ? `model=${model}` : `model not available: ${model}`;
+		}
+		case "reload":
+			await host.reload();
+			return "reloaded";
+		case "list_models":
+			return "listed";
+	}
+}
+
+/**
+ * Reload invalidates the pump ctx (Pi assertActive). The old lap must ack
+ * first so a revived bond cannot see the same pending CONTROL, then reload,
+ * then stop. Do not notify on the old ctx after a successful reload.
+ */
+export type ReloadLapStatus = "reloaded" | "ack_failed" | "reload_failed";
+
+export async function runReloadLap(opts: {
+	ack: () => Promise<void>;
+	reload: () => Promise<void>;
+}): Promise<{ status: ReloadLapStatus; error?: string }> {
+	try {
+		await opts.ack();
+	} catch (err) {
+		return { status: "ack_failed", error: err instanceof Error ? err.message : String(err) };
+	}
+	try {
+		await opts.reload();
+		return { status: "reloaded" };
+	} catch (err) {
+		return { status: "reload_failed", error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+/**
+ * Run Pi command-context reload (same as TUI /reload).
+ * Event/pump ctx does not have reload(); sendUserMessage("/devspec.reload")
+ * is not a substitute — it skips command execution (item e82a690a).
+ */
+export async function reloadWithContext(
+	ctx: { reload?: () => Promise<void> } | null | undefined,
+): Promise<void> {
+	const reload = ctx?.reload;
+	if (typeof reload !== "function") {
+		throw new Error("reload is not available on this context");
+	}
+	await reload.call(ctx);
+}
+
+/**
+ * Run Pi ctx.compact and wait for onComplete / onError.
+ * Fire-and-forget compact is how “requested” lied after a no-op.
+ */
+
+export function compactWithContext(
+	ctx: {
+		compact?: (opts?: {
+			onComplete?: (result: unknown) => void;
+			onError?: (error: Error) => void;
+		}) => void;
+	} | null | undefined,
+	timeoutMs = 60_000,
+): Promise<void> {
+	return new Promise((resolve, reject) => {
+		if (!ctx || typeof ctx.compact !== "function") {
+			reject(new Error("compact is not available on this context"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			reject(new Error(`compact timed out after ${timeoutMs}ms`));
+		}, timeoutMs);
+		const done = (fn: () => void) => {
+			clearTimeout(timer);
+			fn();
+		};
+		ctx.compact({
+			onComplete: () => done(() => resolve()),
+			onError: (error) => done(() => reject(error)),
+		});
+	});
+}

package/extensions/core/ctx-guard.ts

@@ -0,0 +1,33 @@
+/**
+ * Pi invalidates the extension runner after reload / session replacement.
+ * Accessors on the old ctx (hasUI, ui, cwd, …) throw assertActive.
+ * UI toasts and the footer are best-effort — never let that throw kill the process.
+ */
+
+const STALE_CTX_MARK = "stale after session replacement or reload";
+
+export function isStaleCtxError(err: unknown): boolean {
+	return err instanceof Error && err.message.includes(STALE_CTX_MARK);
+}
+
+/** Read hasUI without throwing when the runner has already been invalidated. */
+export function safeHasUI(ctx: { hasUI?: boolean } | null | undefined): boolean {
+	if (!ctx) return false;
+	try {
+		return Boolean(ctx.hasUI);
+	} catch (err) {
+		if (isStaleCtxError(err)) return false;
+		throw err;
+	}
+}
+
+/** Run a UI side-effect; swallow only the Pi stale-ctx class. */
+export function withLiveUi(ctx: { hasUI?: boolean } | null | undefined, fn: () => void): void {
+	if (!safeHasUI(ctx)) return;
+	try {
+		fn();
+	} catch (err) {
+		if (isStaleCtxError(err)) return;
+		throw err;
+	}
+}

package/extensions/core/debug.ts

@@ -0,0 +1,136 @@
+/**
+ * DevSpec Pi — debug log (shared, env-gated).
+ *
+ * DEVSPEC_DEBUG_REMOTE=1 appends privacy-safe pump/recall/lifecycle metadata
+ * to a platform-native temporary file. Cross-extension-file safe
+ * (append-only). Event labels and numeric/boolean field names are closed here;
+ * unknown runtime input is dropped. Prompt text, instructions, context
+ * contents, arguments, results, credentials, names and provider payloads have
+ * no representable field.
+ */
+
+import { appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const DEVSPEC_DEBUG_LOG_PATH = join(tmpdir(), "devspec-remote-debug.log");
+
+const DEBUG_FIELDS = {
+	"adapter guard applied": ["serverCount", "deactivatedTools"],
+	"adapter guard failed": ["errorPresent"],
+	"adapter guard get tools failed": ["errorPresent"],
+	"adapter guard persist failed": ["errorPresent"],
+	"adapter guard set active tools failed": ["errorPresent"],
+	"adapter guard turn failed": ["errorPresent"],
+	"attachment adopted from server": ["attached"],
+	"background observation": ["pendingBg", "unknown"],
+	"background observation persistence failed": ["errorPresent"],
+	"background observation reconciliation failed": ["errorPresent"],
+	"background task noted": ["pendingBg"],
+	"background task resolved from tool result": ["pendingBg"],
+	"canonical ingress rejected": ["errors", "errorPresent"],
+	"canonical ingress synced": ["cursorPresent"],
+	"commit ledger captured": [],
+	"commit provenance delivery": ["sent", "dropped", "expired", "capacity", "retry"],
+	"command offer preempt": ["settled"],
+	"command offer prepared": ["foregroundIdle", "pendingBg"],
+	"command handoff ready": ["pendingBg"],
+	"command offer preparation failed": ["errorPresent"],
+	"context budget": ["staticChars", "injectedChars", "resultCalls", "resultChars"],
+	"control completed": ["resultPresent"],
+	"control acknowledgement failed": ["errorPresent"],
+	"control catalogue collected": ["models", "collectionMs", "catalogBytes"],
+	"control result persistence failed": ["errorPresent"],
+	"control failed": ["messageChars"],
+	"control reload": ["succeeded", "errorPresent"],
+	"delivery boundary": ["completeTurn"],
+	"duplicate-tool recovery": ["count"],
+	"duplicate-tool recovery continue failed": ["errorPresent"],
+	"duplicate-tool recovery persist failed": ["errorPresent"],
+	"ensureTurn: not attached": [],
+	"ensureTurn: tracking (run-scoped)": [],
+	"interaction event application failed": ["errorPresent"],
+	"interaction event persistence confirmation failed": ["errorPresent"],
+	"interaction event exact-workflow guard rejected": ["errors"],
+	"interaction event payload rejected": ["errors", "errorPresent"],
+	"interaction preempt already aborted for event; awaiting idle": [],
+	"interaction apply deferred": ["busy", "occupancyBusy", "ctxIdle"],
+	"interaction authority revoked before agent start": [],
+	"stale tool receipt abort": [],
+	"message_end: no turn": [],
+	"notice reply": ["posted", "idempotent", "refused", "unconfirmed", "skipped", "notices"],
+	"optional room state rejected": ["sessionPolls", "stillToDiscuss", "sessionActivity", "noticeReply"],
+	"room storage unavailable": ["errorPresent"],
+	"poll recoverable": ["errors", "errorPresent"],
+	"poll recoverable server response": ["ended", "reasonPresent"],
+	"post delivery failed": ["skipped", "rejected", "malformed", "unknown"],
+	"post stored": ["idempotent"],
+	preempt: ["settled", "immediate"],
+	"preempt: aborting running turn for owner instruction": [],
+	"preempt: aborting exact question for validated command availability": [],
+	"preempt: aborting running turn for question answer": [],
+	"preempt: cleared stranded busy after unsettled abort": [],
+	"push channel closed": ["reasonPresent"],
+	"push channel connect failed": ["errorPresent"],
+	"push ended recoverable": ["reasonPresent"],
+	"ended from DevSpec — closing Pi": [],
+	"shutdown after End failed": ["errorPresent"],
+	"push reconnect attempt": ["attempt", "delayMs"],
+	"push reconnects exhausted — held long-poll fallback": [],
+	"push unavailable — held long-poll fallback": [],
+	"push wake": [],
+	recall: ["queryChars", "newHits"],
+	"request chain failed": ["open", "close", "restore", "persist"],
+	"request write unstamped": ["connectionChanged", "notRecorded", "errorPresent"],
+	"request launches restored": ["restored"],
+	"request launches ended after restore": ["ended"],
+	"request launches restore failed": ["errorPresent"],
+	"request launch record failed": ["errorPresent"],
+	"recall failed": ["errorPresent"],
+	"sender style repair": ["commands"],
+	"sender styles without a delivered command": ["count"],
+	"session agenda error": ["errorPresent"],
+	"session agenda fetch failed": ["resultChars"],
+	"session enriched": ["titlePresent", "ownerPresent", "tail", "agenda", "attachContext"],
+	"session enrich error": ["errorPresent"],
+	"session enrich fetch failed": ["resultChars"],
+	"settle segment": ["completeTurn", "trailChars", "planFinal", "planMirror", "answerChars", "pendingBg", "harness", "bound"],
+	"settle segment not attached": [],
+	"wake adopted command turn": [],
+	"settleTurn: no turn state": [],
+	"settleTurn: settle": ["answerChars", "pendingBg", "harness"],
+	speech: ["candidate", "process", "split", "chars", "tools", "closedStop"],
+	"system notice idle delivery failed": ["errorPresent"],
+	"system notice memory queue rejected": ["errors", "count"],
+	"system notice settle drain failed": ["errorPresent"],
+	"sync deferred: empty wake, still cursor-less": [],
+	synced: ["cursorPresent", "historical", "live"],
+	"synced with room digest": ["digestChars", "historical", "live"],
+} as const;
+
+type DebugEvent = keyof typeof DEBUG_FIELDS;
+type DebugField = number | boolean;
+type DebugFields<E extends DebugEvent> = Partial<Record<(typeof DEBUG_FIELDS)[E][number], DebugField>>;
+
+/** Pure runtime boundary used by tests and by the file writer. */
+export function formatDebugRecord(event: unknown, fields: unknown = {}): string | null {
+	if (typeof event !== "string" || !Object.hasOwn(DEBUG_FIELDS, event)) return null;
+	const allowed = new Set<string>(DEBUG_FIELDS[event as DebugEvent]);
+	if (!fields || typeof fields !== "object" || Array.isArray(fields)) return event;
+	const suffix = Object.entries(fields as Record<string, unknown>)
+		.filter(([key, value]) => allowed.has(key) && (typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value))))
+		.map(([key, value]) => `${key}=${value}`)
+		.join(" ");
+	return `${event}${suffix ? ` ${suffix}` : ""}`;
+}
+
+export function debugRemote<E extends DebugEvent>(event: E, fields: DebugFields<E> = {}): void {
+	if (!process.env.DEVSPEC_DEBUG_REMOTE) return;
+	const record = formatDebugRecord(event, fields);
+	if (!record) return;
+	try {
+		appendFileSync(DEVSPEC_DEBUG_LOG_PATH, `${new Date().toISOString()} ${record}\n`);
+	} catch {
+		/* debug never breaks anything */
+	}
+}

package/extensions/core/delivery-queue.ts

@@ -0,0 +1,92 @@
+export function nextDeliveryRetryDelayMs(
+	failureCount: number,
+	baseMs = 5_000,
+	maxMs = 60_000,
+): number {
+	const exponent = Math.max(0, Math.floor(failureCount) - 1);
+	return Math.min(baseMs * 2 ** exponent, maxMs);
+}
+
+/** Pump- and automation-run-scoped authority lease for one asynchronous delivery. */
+export interface DeliveryLease {
+	readonly generation: number;
+	readonly keyGeneration: number;
+	isCurrent(): boolean;
+	assertCurrent(): void;
+}
+
+export class StaleDeliveryError extends Error {
+	constructor() {
+		super("delivery authority expired before preparation completed");
+		this.name = "StaleDeliveryError";
+	}
+}
+
+/** Ordered, non-blocking automation delivery outside the remote pump loop. */
+export class DeliveryQueue {
+	private tail: Promise<void> = Promise.resolve();
+	private seen = new Set<string>();
+	private generation = 1;
+	private keyGenerations = new Map<string, number>();
+	private active = true;
+
+	private keyGeneration(key: string): number {
+		return this.keyGenerations.get(key) ?? 1;
+	}
+
+	/** Returns immediately; tasks execute serially in delivery order. */
+	enqueue(key: string, task: (lease: DeliveryLease) => Promise<void>, onError: (error: unknown) => void): boolean {
+		if (!this.active || !key || this.seen.has(key)) return false;
+		this.seen.add(key);
+		const generation = this.generation;
+		const keyGeneration = this.keyGeneration(key);
+		const isCurrent = () =>
+			this.active &&
+			this.generation === generation &&
+			this.keyGeneration(key) === keyGeneration;
+		const lease: DeliveryLease = {
+			generation,
+			keyGeneration,
+			isCurrent,
+			assertCurrent: () => {
+				if (!isCurrent()) throw new StaleDeliveryError();
+			},
+		};
+		this.tail = this.tail
+			.then(() => {
+				lease.assertCurrent();
+				return task(lease);
+			})
+			.catch((error) => {
+				// A stopped/replaced bond owns neither warnings nor retries. The new
+				// pump has a new queue and receives any still-live delivery itself.
+				if (!lease.isCurrent() || error instanceof StaleDeliveryError) return;
+				// A live inbox may offer the same automation run again after a transient
+				// send failure. Task work never enters this queue.
+				this.seen.delete(key);
+				onError(error);
+			});
+		return true;
+	}
+
+	/** Revoke in-flight and queued delivery for one automation-run identity only. */
+	invalidateKey(key: string): void {
+		if (!this.active || !key) return;
+		this.keyGenerations.set(key, this.keyGeneration(key) + 1);
+		this.seen.delete(key);
+	}
+
+	/** Revoke every in-flight and queued delivery owned by this pump generation. */
+	invalidate(): void {
+		if (!this.active) return;
+		this.active = false;
+		this.generation += 1;
+		this.seen.clear();
+		this.keyGenerations.clear();
+	}
+
+	/** Test/shutdown observation only; the pump never awaits this queue. */
+	idle(): Promise<void> {
+		return this.tail;
+	}
+}