@dougbots/avenor-pi 0.16.1 → 0.17.0

package/README.md

@@ -14,6 +14,10 @@ which avenor
 export AVENOR_BIN=~/.botfiles/bin/avenor
 ```
 
+You also need Pi 1.4.0 or newer (`pi --version`). Busy-session delivery depends on
+the `agent_before_settle` hook, so a notice raised while you were busy needs that
+version to reach you. A missing notification is not a lost run.
+
 ## Installation
 
 ### From npm (once published)
@@ -144,8 +148,9 @@ Each roster entry must contain `backend` and at least one of `agent` or `model`.
 Beyond the tools, the extension integrates with Pi's TUI and event system:
 
 - **Status widget** — persistent widget showing all active runs with status, phase, and permission state
-- **Footer status** — active runs and polling error counts shown in the Pi footer bar
-- **Polling diagnostics** — bounded polling errors are emitted on `avenor:poll:error` for companion extensions
+- **Footer status** — the `avenor` status key carries active runs, the live agent-tree total, the unread notice count, and the current poll-failure count (see [Completion notices](#completion-notices))
+- **Completion notices** — one notice per finished run, delivered immediately when your session is idle and batched into a single continuation when it was busy
+- **Polling diagnostics** — bounded polling errors are emitted on `avenor:poll:error` for companion extensions; a completion-notice delivery that exhausts its retries is emitted separately on `avenor:delivery:error`
 - **Live progress** — blocking `avenor_spawn` calls stream progress updates via `onUpdate`
 - **Context enrichment** — active sub-agents are automatically surfaced in the system prompt via `before_agent_start`
 - **Custom rendering** — The Pi extension renders all Avenor tool calls and results as themed, bounded summaries. Results have collapsed and expanded views.
@@ -155,6 +160,56 @@ Beyond the tools, the extension integrates with Pi's TUI and event system:
   - `/avenor-watch <run_id>` — open a live event feed overlay
   - `/avenor-cancel <run_id>` — cancel a running sub-agent
 
+### Completion notices
+
+A fire-and-forget spawn (`wait: false`) promises one thing: you hear about the
+run when it ends. Each finished run produces one notice — label, terminal
+status, bounded output preview — and where it lands depends on your session at
+that moment.
+
+- **Idle.** The notice is sent as a user message and starts its own turn. It
+  counts as unread until Pi confirms the message landed, and while compaction is
+  running the send waits for it to finish. A send that is accepted but never
+  confirmed is sent at most three times; once that budget is spent the notice
+  stays unread for the next settlement and the failure is emitted on
+  `avenor:delivery:error`.
+- **Busy.** The notice is queued and the footer shows `unread:N`. The next
+  settlement that completes normally appends each queued notice as an
+  `avenor-completion` custom message under a single continuation, so three runs
+  finishing while you work mean three messages and one wake-up. A settlement
+  that ends in abort or error delivers nothing; the notices wait.
+
+Every terminal status queues a notice — `done`, `failed`, `timeout`, `killed`.
+
+`avenor_result` and a blocking `avenor_spawn` (`wait: true`) own delivery while
+they run; `avenor_result` takes the label you spawned with, so you need not keep
+the id. A `ready` result consumes the run: the queued notice is dropped,
+`unread:N` falls by one, and nothing arrives for it later. A result that is not
+`ready` — interrupted by a sibling's stopping point, timed out, or reporting a
+pending permission — consumes nothing, and its notice arrives on the normal
+schedule. A blocking spawn that reaches completion returns the result inline and
+removes the notice; the footer can show a transient `unread:N` for that run while
+the wait is in flight.
+
+#### Footer status
+
+One string under the status key `avenor`, in this order:
+
+| Token | Meaning |
+|---|---|
+| `🟢 label — running [phase] 🔒 +2` | one per non-terminal run: status emoji, label, status, phase label, `🔒` for a pending permission, `+N` for that run's active descendants |
+| `total:N` | direct active runs plus discovered active descendants; present only when active descendants exist |
+| `unread:N` | notices not yet delivered: queued for a settlement, or in flight for an idle session |
+| `errors:N` | recent poll failures; cleared by a cycle that adds no new error |
+
+Missing `unread:N` or `errors:N` means zero. Without `total:N`, count the active run lines. `unread:N` counts notices,
+not runs, and can stay set after the last run exits — an otherwise idle session
+can still advertise `unread:1` until you consume or receive that notice.
+`total:N` tracks live runs and disappears with them. `errors:N` outlives them
+too: it clears when a later poll cycle adds no new error, so it counts recent
+failures rather than a consecutive streak. The bounded history behind
+`/avenor-errors` is longer than `errors:N`; running that command clears both.
+
 ### Tool-result channels
 
 Pi returns JSON model content in `content[0].text` and structured `details` for

package/dist/index.d.ts

@@ -37,7 +37,11 @@ declare const CHANNEL_POLL_COMPLETED: "avenor:poll:completed";
 declare const CHANNEL_RUN_TERMINAL: "avenor:run:terminal";
 /** Emitted when a best-effort polling operation fails. */
 declare const CHANNEL_POLL_ERROR: "avenor:poll:error";
+/** Emitted when a completion-notice delivery fails permanently. */
+declare const CHANNEL_DELIVERY_ERROR: "avenor:delivery:error";
 type PollErrorSource = 'singleton-list' | 'run-status' | 'spawn-status';
+/** Delivery paths whose retries can be exhausted. */
+type DeliveryErrorSource = 'idle-send';
 interface PollErrorPayload {
   /** Polling operation that failed. */
   readonly source: PollErrorSource;
@@ -60,6 +64,31 @@ interface PollErrorPayloadInput {
   readonly count: number;
   readonly timestamp: number;
 }
+interface DeliveryErrorPayload {
+  /** Delivery path that failed. */
+  readonly source: DeliveryErrorSource;
+  /** Run whose completion notice is stuck unread. */
+  readonly runId: string;
+  /** Label of the run, as shown in completion notices. */
+  readonly label: string;
+  /** Human-readable failure description. */
+  readonly message: string;
+  /** Bounded, sanitized error text suitable for debug consumers. */
+  readonly error: string;
+  /** Delivery attempts made for this notice. */
+  readonly attempts: number;
+  /** Wall-clock timestamp in epoch milliseconds. */
+  readonly timestamp: number;
+}
+interface DeliveryErrorPayloadInput {
+  readonly source: DeliveryErrorSource;
+  readonly runId: string;
+  readonly label: string;
+  readonly message: string;
+  readonly error: unknown;
+  readonly attempts: number;
+  readonly timestamp: number;
+}
 type AvenorRunStatus = Readonly<Omit<RunStatusEntry, 'supervisorId' | 'pid' | 'permissionDescription'> & {
   supervisorKey: string;
 }>;
@@ -79,7 +108,7 @@ interface RunTerminalPayload {
   readonly label: string;
   readonly agent: string;
   readonly status: string;
-  /** Number of active descendants when the run was removed, if available. */
+  /** Number of active descendants last seen for the run, if available. */
   readonly nestedCount?: number;
   readonly backend?: string;
 }
@@ -98,6 +127,7 @@ interface AvenorEventMap {
   [CHANNEL_POLL_COMPLETED]: PollCompletedPayload;
   [CHANNEL_RUN_TERMINAL]: RunTerminalPayload;
   [CHANNEL_POLL_ERROR]: PollErrorPayload;
+  [CHANNEL_DELIVERY_ERROR]: DeliveryErrorPayload;
 }
 type AvenorEventChannel = keyof AvenorEventMap;
 type AvenorEventBus = Pick<EventBus, 'emit' | 'on'>;
@@ -113,6 +143,8 @@ declare function onAvenorEvent<K extends AvenorEventChannel>(bus: Pick<EventBus,
 declare function createPollCompletedPayload(entries: readonly RunStatusEntry[], timestamp: number, generation: number): PollCompletedPayload;
 /** Copy and freeze a terminal payload before publishing it. */
 declare function createRunTerminalPayload(payload: RunTerminalPayloadInput): RunTerminalPayload;
+/** Copy, bound, sanitize, and freeze a delivery failure before publishing it. */
+declare function createDeliveryErrorPayload(payload: DeliveryErrorPayloadInput): DeliveryErrorPayload;
 /** Copy, bound, sanitize, and freeze a polling error before publishing it. */
 declare function createPollErrorPayload(payload: PollErrorPayloadInput): PollErrorPayload;
 //#endregion
@@ -167,10 +199,13 @@ declare function buildInspectPayload(result: InspectResult): Record<string, unkn
 interface ExtensionOptions {
   /** Polling cadence; injectable so tests can drive deterministic ticks. */
   pollIntervalMs?: number;
+  /** How long an unconfirmed idle completion send waits before re-arming;
+   * injectable so tests can exercise the timeout without fixed sleeps. */
+  idleSendTimeoutMs?: number;
   /** Overrides broker-credential autodetection for sub-agent broker mode (tests). */
   subAgentEnv?: SubAgentEnv | null;
 }
 declare function createExtension(deps?: ExtensionDeps, options?: ExtensionOptions): (pi: ExtensionAPI) => Promise<void>;
 declare const _default: (pi: ExtensionAPI) => Promise<void>;
 //#endregion
-export { type AvenorEventBus, type AvenorEventChannel, type AvenorEventMap, type AvenorRunStatus, CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, ExtensionDeps, ExtensionOptions, type PollCompletedPayload, type PollErrorPayload, type PollErrorPayloadInput, type PollErrorSource, type RunTerminalPayload, type RunTerminalPayloadInput, buildCompletionText, buildInspectPayload, compactWhitespace, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, _default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };
+export { type AvenorEventBus, type AvenorEventChannel, type AvenorEventMap, type AvenorRunStatus, CHANNEL_DELIVERY_ERROR, CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, type DeliveryErrorPayload, type DeliveryErrorPayloadInput, type DeliveryErrorSource, ExtensionDeps, ExtensionOptions, type PollCompletedPayload, type PollErrorPayload, type PollErrorPayloadInput, type PollErrorSource, type RunTerminalPayload, type RunTerminalPayloadInput, buildCompletionText, buildInspectPayload, compactWhitespace, createDeliveryErrorPayload, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, _default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };

package/dist/index.js

@@ -106,6 +106,14 @@ async function postBroker(env, path, body, fetchImpl = fetch, signal) {
 	if (!res.ok) throw await codedError(path, res);
 	return res.json();
 }
+/**
+* Publish the harness's own user-defined session name for this run, or clear it
+* with an empty name. The broker stores it apart from any model-set rename and
+* prefers it, so peers see the name the human gave the session.
+*/
+async function publishHarnessName(env, name, fetchImpl = fetch) {
+	await postBroker(env, "/session_name", { name: name ?? "" }, fetchImpl);
+}
 /** Authenticated GET; broker credentials travel in headers, never the URL. */
 async function getBroker(env, path, fetchImpl = fetch, signal) {
 	const res = await fetchImpl(`${env.brokerUrl}${path}`, {
@@ -536,7 +544,13 @@ function createBrokerChildBroker(env, fetchImpl = fetch) {
 			}
 		},
 		async peers() {
-			return { peers: peerRecords(await getBroker(env, "/sessions", fetchImpl)) };
+			const body = await getBroker(env, "/sessions", fetchImpl);
+			const peers = peerRecords(body);
+			const detail = body !== null && typeof body === "object" ? body.peers_error : void 0;
+			return typeof detail === "string" && detail ? {
+				peers,
+				detail
+			} : { peers };
 		},
 		async rename(req) {
 			try {
@@ -1136,21 +1150,6 @@ function formatRunLine(entry) {
 	const phase = entry.phaseLabel ? ` (${entry.phaseLabel})` : "";
 	return `${emoji} ${entry.label} (${entry.agent}) — ${entry.status}${phase}${perm}`;
 }
-/**
-* decideCompletion determines whether to skip or send the completion
-* steering message for a tracked run that has reached terminal status.
-*
-* The message is delivered on the same terminal tick — never deferred to a
-* later cycle — so a run that is the last live one still gets its completion.
-* `blocking` suppresses it while avenor_result is awaiting (it will deliver
-* the result itself and set `consumed`), and `consumed` suppresses it once
-* avenor_result has already returned the result successfully.
-*/
-function decideCompletion(run) {
-	if (run.blocking) return "skip";
-	if (run.consumed) return "skip";
-	return "send";
-}
 //#endregion
 //#region src/nested-count.ts
 const NESTED_DIAL_TIMEOUT_MS = 2e3;
@@ -1303,6 +1302,8 @@ const CHANNEL_POLL_COMPLETED = "avenor:poll:completed";
 const CHANNEL_RUN_TERMINAL = "avenor:run:terminal";
 /** Emitted when a best-effort polling operation fails. */
 const CHANNEL_POLL_ERROR = "avenor:poll:error";
+/** Emitted when a completion-notice delivery fails permanently. */
+const CHANNEL_DELIVERY_ERROR = "avenor:delivery:error";
 /** Maximum sanitized error text exposed to companion extensions. */
 const POLL_ERROR_TEXT_CHARS = 600;
 function sanitizeAndBoundText(value) {
@@ -1360,6 +1361,18 @@ function createRunTerminalPayload(payload) {
 		...payload.backend !== void 0 && { backend: payload.backend }
 	});
 }
+/** Copy, bound, sanitize, and freeze a delivery failure before publishing it. */
+function createDeliveryErrorPayload(payload) {
+	return Object.freeze({
+		source: payload.source,
+		runId: payload.runId,
+		label: payload.label,
+		message: sanitizeAndBoundText(payload.message),
+		error: sanitizeAndBoundText(payload.error),
+		attempts: payload.attempts,
+		timestamp: payload.timestamp
+	});
+}
 /** Copy, bound, sanitize, and freeze a polling error before publishing it. */
 function createPollErrorPayload(payload) {
 	return Object.freeze({
@@ -1920,6 +1933,8 @@ function asStatusResult(raw) {
 	return raw;
 }
 const POLL_INTERVAL_MS = 3e3;
+const IDLE_SEND_TIMEOUT_MS = 1e4;
+const MAX_IDLE_SEND_ATTEMPTS = 3;
 const INSPECT_LIMIT = 128;
 const COMPLETION_OUTPUT_CHARS = 600;
 const INSPECT_JSON_STRING_CHARS = 600;
@@ -2092,6 +2107,7 @@ function trackedRunKey(supervisorId, runId) {
 function createExtension(deps = defaultDeps, options = {}) {
 	return async function(pi) {
 		const pollIntervalMs = options.pollIntervalMs ?? POLL_INTERVAL_MS;
+		const idleSendTimeoutMs = options.idleSendTimeoutMs ?? IDLE_SEND_TIMEOUT_MS;
 		let telemetryGeneration = 0;
 		const trackedRuns = /* @__PURE__ */ new Map();
 		let pollingActive = false;
@@ -2101,6 +2117,8 @@ function createExtension(deps = defaultDeps, options = {}) {
 		let pollingErrorCount = 0;
 		const pollingErrors = [];
 		let lastStatusEntries = [];
+		let sessionGeneration = 0;
+		let compacting = false;
 		let lastTurnSocketClosed = false;
 		const pendingWaits = /* @__PURE__ */ new Set();
 		/** The agent-facing prose clause for a stopping point. A synthetic status
@@ -2174,12 +2192,16 @@ function createExtension(deps = defaultDeps, options = {}) {
 			};
 		}
 		/** Build the early return for a wait interrupted by a sibling stopping
-		* point. When the awaited run itself has since reached a stopping point
-		* (possible when the caller omitted supervisor_id and the registry key
-		* diverged), deliver its real state instead of an interruption notice. */
+		* point. When the awaited run itself has since reached a stopping point,
+		* deliver its real state instead of an interruption notice. The probe and
+		* redelivery use the caller's original run reference, matching the non-
+		* interrupted path: a label may resolve canonically to a newer run than
+		* the one this call first bound to, and the reconciliation below handles
+		* that divergence the same way. A caller that omitted supervisor_id still
+		* probes through the bound run's supervisor. */
 		async function resultAfterInterrupt(params, stop, tracked) {
-			const runId = tracked?.runId ?? params.run_id;
-			const supervisorId = tracked?.supervisorId ?? params.supervisor_id;
+			const runId = params.run_id;
+			const supervisorId = params.supervisor_id ?? tracked?.supervisorId;
 			let current;
 			try {
 				current = asStatusResult(await deps.statusTool({
@@ -2229,6 +2251,35 @@ function createExtension(deps = defaultDeps, options = {}) {
 				subAgentPollTimer = null;
 			}
 		}
+		let publishedSessionName = null;
+		let publishChain = Promise.resolve();
+		let refusedSessionName = null;
+		function publishSessionName(ctx) {
+			if (!subAgentEnv) return publishChain;
+			const env = subAgentEnv;
+			const manager = ctx.sessionManager;
+			if (!manager || typeof manager.getSessionName !== "function") return publishChain;
+			const name = manager.getSessionName();
+			if (publishedSessionName && publishedSessionName.name === name) return publishChain;
+			if (refusedSessionName === name) return publishChain;
+			const attempt = { name };
+			publishedSessionName = attempt;
+			publishChain = publishChain.then(async () => {
+				try {
+					await publishHarnessName(env, name);
+					refusedSessionName = null;
+				} catch (error) {
+					if (error instanceof BrokerHttpError && error.status === 400 && error.code === "invalid-name") {
+						refusedSessionName = name;
+						console.error("[avenor] session_name_set refused:", error.message);
+						return;
+					}
+					if (publishedSessionName === attempt) publishedSessionName = null;
+					console.error("[avenor] session_name_set failed:", error instanceof Error ? error.message : error);
+				}
+			});
+			return publishChain;
+		}
 		async function startSubAgentPoll() {
 			if (!subAgentEnv) return;
 			stopSubAgentPoll();
@@ -2313,6 +2364,40 @@ function createExtension(deps = defaultDeps, options = {}) {
 			if (pollingErrors.length > MAX_POLL_ERRORS) pollingErrors.shift();
 			emitAvenorEvent(pi.events, CHANNEL_POLL_ERROR, payload);
 		}
+		/** A delivery that exhausted its retries is not a polling failure: emit
+		* it on its own channel so `avenor:poll:error` consumers keep a pure
+		* polling contract. The unread notice is the persistent user-facing
+		* surface; this event is the companion-extension signal. */
+		function recordDeliveryError(run, attempts) {
+			emitAvenorEvent(pi.events, CHANNEL_DELIVERY_ERROR, createDeliveryErrorPayload({
+				source: "idle-send",
+				runId: run.runId,
+				label: run.label,
+				message: "idle completion send was never confirmed",
+				error: /* @__PURE__ */ new Error(`no message_end after ${attempts} attempts`),
+				attempts,
+				timestamp: Date.now()
+			}));
+			console.error(`[avenor] idle completion send for run "${run.label}" was never confirmed after ${attempts} attempts; the notice stays unread`);
+		}
+		/** Latch the per-notice retry budget as spent and report the exhausted
+		* delivery. Idempotent, so the timeout re-arm and the compaction
+		* hand-back cannot double-report the same notice. */
+		function capIdleSend(run) {
+			if (!run.idleSend || run.idleSend.capped) return;
+			run.idleSend.capped = true;
+			recordDeliveryError(run, run.idleSend.attempts);
+		}
+		/** Hand an unconfirmed idle send back to the poll: clear the in-flight
+		* mark and latch the budget when it is spent. Shared by the poll-tick
+		* timeout and the compaction hand-back, which must stay in lockstep. */
+		function rearmIdleSend(run) {
+			const idle = run.idleSend;
+			if (!idle) return;
+			idle.inFlight = false;
+			idle.sentAt = void 0;
+			if (idle.attempts >= MAX_IDLE_SEND_ATTEMPTS) capIdleSend(run);
+		}
 		function clearPollingErrors() {
 			pollingErrorCount = 0;
 			pollingErrors.length = 0;
@@ -2321,38 +2406,75 @@ function createExtension(deps = defaultDeps, options = {}) {
 		function upsertTrackedRun(run, status, blocking = false) {
 			const key = trackedRunKey(run.supervisorId, run.runId);
 			const current = trackedRuns.get(key);
-			trackedRuns.set(key, {
+			const tracked = current ?? {
 				runId: run.runId,
-				agent: run.agent ?? status?.agent ?? current?.agent ?? "unknown",
-				label: run.label ?? status?.label ?? current?.label ?? run.runId,
-				supervisorId: run.supervisorId ?? current?.supervisorId,
-				runtimeId: run.runtimeId ?? status?.runtime_id ?? current?.runtimeId,
-				startTime: current?.startTime ?? Date.now(),
-				lastStatus: status ?? current?.lastStatus,
-				blocking: current?.blocking ?? blocking,
-				permissionNotified: current?.permissionNotified,
-				consumed: current?.consumed
-			});
+				startTime: Date.now(),
+				agent: "unknown",
+				label: run.label ?? run.runId
+			};
+			tracked.runId = run.runId;
+			tracked.agent = run.agent ?? status?.agent ?? current?.agent ?? tracked.agent;
+			tracked.label = run.label ?? status?.label ?? current?.label ?? tracked.label;
+			tracked.supervisorId = run.supervisorId ?? current?.supervisorId;
+			tracked.runtimeId = run.runtimeId ?? status?.runtime_id ?? current?.runtimeId;
+			if (!current) tracked.startTime = Date.now();
+			tracked.lastStatus = status ?? current?.lastStatus;
+			tracked.blocking = current?.blocking ?? blocking;
+			trackedRuns.set(key, tracked);
+		}
+		function findTrackedByLabel(label, supervisorId) {
+			let match;
+			for (const run of trackedRuns.values()) {
+				if (supervisorId !== void 0 && run.supervisorId !== supervisorId) continue;
+				if (run.label !== label) continue;
+				if (match) return void 0;
+				match = run;
+			}
+			return match;
 		}
 		/**
-		* Look a run up in the per-supervisor tracking namespace. When a
-		* supervisor is supplied, resolve exactly. Without one, prefer the
+		* Resolve a canonical run id in the per-supervisor tracking namespace.
+		* When a supervisor is supplied, resolve exactly. Without one, prefer the
 		* singleton namespace and only fall back to a run id walk when it is
 		* unambiguous across supervisors. Duplicate run ids across supervisors
 		* without an explicit supervisor return undefined so callers never bind
 		* flags or telemetry to the wrong supervisor's run.
 		*/
-		function getTrackedRun(runId, supervisorId) {
-			if (supervisorId !== void 0) return trackedRuns.get(trackedRunKey(supervisorId, runId));
-			const singleton = trackedRuns.get(trackedRunKey(void 0, runId));
-			if (singleton) return singleton;
-			let match;
-			for (const run of trackedRuns.values()) {
-				if (run.runId !== runId) continue;
-				if (match) return void 0;
-				match = run;
+		function trackedRunsById(runId, supervisorId) {
+			if (supervisorId !== void 0) {
+				const exact = trackedRuns.get(trackedRunKey(supervisorId, runId));
+				return exact ? [exact] : [];
 			}
-			return match;
+			const singleton = trackedRuns.get(trackedRunKey(void 0, runId));
+			if (singleton) return [singleton];
+			const matches = [];
+			for (const run of trackedRuns.values()) if (run.runId === runId) matches.push(run);
+			return matches;
+		}
+		function getTrackedRunById(runId, supervisorId) {
+			const matches = trackedRunsById(runId, supervisorId);
+			return matches.length === 1 ? matches[0] : void 0;
+		}
+		/**
+		* Resolve a user-supplied run reference. A canonical identity always wins;
+		* a label is only a fallback, and an ambiguous canonical id never falls
+		* through to a label.
+		*/
+		function getTrackedRun(runId, supervisorId) {
+			const exact = getTrackedRunById(runId, supervisorId);
+			if (exact) return exact;
+			if (trackedRunsById(runId, supervisorId).length > 1) return void 0;
+			return findTrackedByLabel(runId, supervisorId);
+		}
+		/** Resolve the tracked run a successful result belongs to from the
+		* canonical run id the result tool reports, accepting a runtime-id alias
+		* for the label-resolved run. */
+		function reconcileResultRun(tracked, result, supervisorId) {
+			const runId = result.run_id;
+			if (!runId) return tracked;
+			if (tracked && (tracked.runId === runId || tracked.runtimeId === runId)) return tracked;
+			const namespace = tracked?.supervisorId ?? supervisorId;
+			return trackedRuns.get(trackedRunKey(namespace, runId));
 		}
 		async function resolveFinalOutput(run, status) {
 			const preview = finalOutputPreview(status);
@@ -2368,6 +2490,67 @@ function createExtension(deps = defaultDeps, options = {}) {
 				return;
 			}
 		}
+		/**
+		* Fire-and-forget delivery. Pi's extension-facing `sendUserMessage` returns
+		* void and the runtime swallows async rejections, so a send is only known to
+		* have landed when the user message comes back through `message_end`. Only a
+		* synchronous throw is observable here.
+		*/
+		function sendUserMessageLogged(text, failureLog) {
+			try {
+				pi.sendUserMessage(text, { deliverAs: "followUp" });
+			} catch (err) {
+				console.error(failureLog, err);
+			}
+		}
+		function clearPendingNotices() {
+			for (const run of trackedRuns.values()) {
+				run.pendingNotice = void 0;
+				run.idleSend = void 0;
+			}
+		}
+		/**
+		* Emit the single terminal event for a tracked run. Every terminal path
+		* (poll, blocking spawn, avenor_result) goes through here so the event-once
+		* guard and payload shape stay identical. A tracked run emits at most once;
+		* an untracked run emits with the canonical result identity, unguarded.
+		*
+		* @returns whether the event was emitted, so callers can gate one-time
+		*   side effects.
+		*/
+		function emitRunTerminal(input) {
+			const { run } = input;
+			if (!run) {
+				if (!input.runId) return false;
+				emitAvenorEvent(pi.events, CHANNEL_RUN_TERMINAL, createRunTerminalPayload({
+					runId: input.runId,
+					supervisorId: input.supervisorId,
+					runtimeId: input.runtimeId,
+					label: input.label,
+					agent: input.agent,
+					status: input.status,
+					nestedCount: input.nestedCount,
+					backend: input.backend
+				}));
+				return true;
+			}
+			if (run.terminalEventEmitted) return false;
+			run.terminalEventEmitted = true;
+			emitAvenorEvent(pi.events, CHANNEL_RUN_TERMINAL, createRunTerminalPayload({
+				runId: run.runId,
+				supervisorId: run.supervisorId,
+				runtimeId: input.runtimeId,
+				label: input.label,
+				agent: input.agent,
+				status: input.status,
+				nestedCount: input.nestedCount,
+				backend: input.backend
+			}));
+			return true;
+		}
+		function sendCompletionNotice(notice) {
+			sendUserMessageLogged(notice.text, "avenor tick: sendUserMessage failed");
+		}
 		async function pollRuns() {
 			const errorCountAtPollStart = pollingErrorCount;
 			const liveMap = /* @__PURE__ */ new Map();
@@ -2460,7 +2643,11 @@ function createExtension(deps = defaultDeps, options = {}) {
 			if (nestedPids.length > 0) {
 				const nestedCounts = await Promise.all(nestedPids.map((pid) => countNestedRuns(pid, deps.dial)));
 				let idx = 0;
-				for (const entry of entries) if (entry.backend === "pi" && entry.pid && !isTerminalStatus(entry.status)) entry.nestedCount = nestedCounts[idx++] ?? 0;
+				for (const entry of entries) if (entry.backend === "pi" && entry.pid && !isTerminalStatus(entry.status)) {
+					entry.nestedCount = nestedCounts[idx++] ?? 0;
+					const tracked = trackedRuns.get(trackedRunKey(entry.supervisorId, entry.runId));
+					if (tracked) tracked.nestedCount = entry.nestedCount;
+				}
 			}
 			if (pollingErrorCount === errorCountAtPollStart) pollingErrorCount = 0;
 			return entries;
@@ -2469,17 +2656,24 @@ function createExtension(deps = defaultDeps, options = {}) {
 			lastStatusEntries = entries;
 			if (!sessionCtx) return;
 			const lines = renderStatusLines(entries);
+			let unread = 0;
+			for (const run of trackedRuns.values()) if (run.pendingNotice) unread++;
 			const errorSuffix = pollingErrorCount > 0 ? `errors:${pollingErrorCount}` : "";
+			const unreadSuffix = unread > 0 ? `unread:${unread}` : "";
 			if (lines.length > 0) {
 				sessionCtx.ui.setWidget("avenor-status", lines);
 				const statusStr = lines.map((line) => line.slice(0, 60)).join("  ");
 				const nestedTotal = entries.filter((e) => !isTerminalStatus(e.status)).reduce((sum, e) => sum + (e.nestedCount ?? 0), 0);
 				const total = lines.length + nestedTotal;
-				const statusWithTotal = [nestedTotal > 0 ? `${statusStr}  total:${total}` : statusStr, errorSuffix].filter(Boolean).join("  ");
+				const statusWithTotal = [
+					nestedTotal > 0 ? `${statusStr}  total:${total}` : statusStr,
+					unreadSuffix,
+					errorSuffix
+				].filter(Boolean).join("  ");
 				sessionCtx.ui.setStatus("avenor", statusWithTotal);
 			} else {
 				sessionCtx.ui.setWidget("avenor-status", void 0);
-				sessionCtx.ui.setStatus("avenor", errorSuffix);
+				sessionCtx.ui.setStatus("avenor", [unreadSuffix, errorSuffix].filter(Boolean).join("  "));
 			}
 		}
 		function startPolling() {
@@ -2500,12 +2694,20 @@ function createExtension(deps = defaultDeps, options = {}) {
 				});
 				if (!pollingActive || generation !== pollingGeneration) return;
 				updateWidget(entries);
+				let widgetDirty = false;
+				const sessionAtPollStart = sessionGeneration;
 				emitAvenorEvent(pi.events, CHANNEL_POLL_COMPLETED, createPollCompletedPayload(entries, Date.now(), ++telemetryGeneration));
 				for (const entry of entries) {
 					const entryKey = trackedRunKey(entry.supervisorId, entry.runId);
 					const run = trackedRuns.get(entryKey);
 					if (!run) continue;
 					const prevStatus = prevStatuses.get(entryKey);
+					const idle = run.idleSend;
+					if (idle?.inFlight && idle.sentAt !== void 0 && Date.now() - idle.sentAt >= idleSendTimeoutMs) {
+						rearmIdleSend(run);
+						widgetDirty = true;
+					}
+					if (run.idleSend?.inFlight && isTerminalStatus(entry.status)) continue;
 					const wasStopped = prevStatus?.status !== void 0 && isTerminalStatus(prevStatus.status) || !!prevStatus?.pendingPermission;
 					if ((entry.pendingPermission || isTerminalStatus(entry.status)) && !wasStopped) interruptPendingWaits({
 						runId: entry.runId,
@@ -2513,45 +2715,61 @@ function createExtension(deps = defaultDeps, options = {}) {
 						status: isTerminalStatus(entry.status) ? entry.status : "waiting"
 					}, entryKey);
 					if (isTerminalStatus(entry.status)) {
-						if (decideCompletion(run) === "skip") {
-							if (run.consumed) trackedRuns.delete(entryKey);
-							continue;
-						}
-						if (!(prevStatus?.status !== void 0 && isTerminalStatus(prevStatus.status))) sessionCtx?.ui.notify(`Sub-agent "${entry.label}" finished: ${entry.status}`, entry.status === "done" ? "info" : "warning");
-						const finalOutput = await resolveFinalOutput(run, run.lastStatus);
-						try {
-							pi.sendUserMessage(buildCompletionText({
-								runId: run.runId,
-								label: run.label
-							}, run.lastStatus, finalOutput), { deliverAs: "followUp" });
-						} catch (err) {
-							console.error("avenor tick: sendUserMessage failed", err);
-						}
-						emitAvenorEvent(pi.events, CHANNEL_RUN_TERMINAL, createRunTerminalPayload({
-							runId: entry.runId,
-							supervisorId: entry.supervisorId,
+						const finalOutput = run.pendingNotice ? void 0 : await resolveFinalOutput(run, run.lastStatus);
+						if (sessionAtPollStart !== sessionGeneration) continue;
+						if (trackedRuns.get(entryKey) !== run) continue;
+						const wasTerminalBefore = prevStatus?.status !== void 0 && isTerminalStatus(prevStatus.status);
+						if (emitRunTerminal({
+							run,
 							runtimeId: entry.runtimeId,
 							label: entry.label,
 							agent: entry.agent,
 							status: entry.status,
-							nestedCount: entry.nestedCount,
+							nestedCount: entry.nestedCount ?? run.nestedCount,
 							backend: entry.backend
-						}));
-						trackedRuns.delete(entryKey);
-					} else if (entry.pendingPermission && !run.blocking && !run.permissionNotified) {
-						run.permissionNotified = true;
-						if (run.lastStatus) try {
-							pi.sendUserMessage(buildWaitingText({
+						})) {
+							if (!wasTerminalBefore && !run.blocking) sessionCtx?.ui.notify(`Sub-agent "${entry.label}" finished: ${entry.status}`, entry.status === "done" ? "info" : "warning");
+						}
+						const notice = run.pendingNotice ?? {
+							status: entry.status,
+							text: buildCompletionText({
 								runId: run.runId,
-								label: run.label,
-								agent: run.agent
-							}, run.lastStatus), { deliverAs: "followUp" });
-						} catch (err) {
-							console.error("avenor tick: sendUserMessage for permission failed", err);
+								label: run.label
+							}, run.lastStatus, finalOutput)
+						};
+						if (run.blocking) {
+							if (!run.pendingNotice) {
+								run.pendingNotice = notice;
+								widgetDirty = true;
+							}
+							continue;
+						}
+						if (sessionCtx?.isIdle() === true && !compacting && !run.idleSend?.capped) {
+							run.pendingNotice = notice;
+							run.idleSend = {
+								inFlight: true,
+								sentAt: Date.now(),
+								attempts: (run.idleSend?.attempts ?? 0) + 1,
+								capped: false
+							};
+							widgetDirty = true;
+							sendCompletionNotice(notice);
+							continue;
+						} else if (!run.pendingNotice) {
+							run.pendingNotice = notice;
+							widgetDirty = true;
 						}
+					} else if (entry.pendingPermission && !run.blocking && !run.permissionNotified) {
+						run.permissionNotified = true;
+						if (run.lastStatus) sendUserMessageLogged(buildWaitingText({
+							runId: run.runId,
+							label: run.label,
+							agent: run.agent
+						}, run.lastStatus), "avenor tick: sendUserMessage for permission failed");
 					} else if (!entry.pendingPermission && run.permissionNotified) run.permissionNotified = false;
 				}
-				if (entries.some((entry) => !isTerminalStatus(entry.status)) && pollingActive && generation === pollingGeneration) setTimeout(() => {
+				if (widgetDirty) updateWidget(entries);
+				if ((entries.some((entry) => !isTerminalStatus(entry.status)) || Array.from(trackedRuns.values()).some((run) => run.idleSend?.inFlight)) && pollingActive && generation === pollingGeneration) setTimeout(() => {
 					tick().catch((err) => {
 						pollingActive = false;
 						console.error("avenor polling loop failed", err);
@@ -2846,10 +3064,16 @@ function createExtension(deps = defaultDeps, options = {}) {
 		});
 		pi.on("session_start", async (_event, ctx) => {
 			sessionCtx = ctx;
+			sessionGeneration++;
+			compacting = false;
+			clearPendingNotices();
+			if (trackedRuns.size > 0) startPolling();
 			lastStatusEntries = [];
 			lastTurnSocketClosed = false;
 			pollingErrorCount = 0;
 			pollingErrors.length = 0;
+			publishedSessionName = null;
+			publishSessionName(ctx);
 			if (!isSubAgentBrokerMode) startHostAskPoll();
 			startSubAgentPoll();
 		});
@@ -2859,6 +3083,8 @@ function createExtension(deps = defaultDeps, options = {}) {
 			disposeHostProviders();
 			hostPendingAsks.clear();
 			subAgentPendingAsks.clear();
+			sessionGeneration++;
+			clearPendingNotices();
 			await stopPolling();
 			for (const wait of [...pendingWaits]) {
 				pendingWaits.delete(wait);
@@ -2870,7 +3096,36 @@ function createExtension(deps = defaultDeps, options = {}) {
 			}
 			sessionCtx = null;
 		});
-		pi.on("before_agent_start", async () => {
+		pi.on("message_end", (event) => {
+			if (event.message?.role !== "user") return;
+			const text = extractTurnText([event.message]).text;
+			if (text === "") return;
+			const matches = [...trackedRuns].filter(([, run]) => run.pendingNotice?.text === text);
+			let targets = matches.filter(([, run]) => run.idleSend?.inFlight);
+			if (targets.length === 0) targets = matches.filter(([, run]) => run.idleSend !== void 0);
+			for (const [key, run] of targets) {
+				run.pendingNotice = void 0;
+				run.idleSend = void 0;
+				trackedRuns.delete(key);
+			}
+			if (targets.length > 0) updateWidget(lastStatusEntries);
+		});
+		pi.on("session_before_compact", () => {
+			compacting = true;
+		});
+		const resumeAfterCompaction = () => {
+			compacting = false;
+			for (const run of trackedRuns.values()) {
+				if (run.permissionNotified && run.lastStatus?.pending_permission) run.permissionNotified = false;
+				if (!run.idleSend) continue;
+				rearmIdleSend(run);
+			}
+			if (Array.from(trackedRuns.values()).some((run) => run.pendingNotice || !run.permissionNotified && !!run.lastStatus?.pending_permission)) startPolling();
+		};
+		pi.on("session_compact", resumeAfterCompaction);
+		pi.on("before_agent_start", async (_event, ctx) => {
+			publishSessionName(ctx);
+			compacting = false;
 			if (trackedRuns.size === 0) return;
 			const active = (await pollRuns()).filter((entry) => !isTerminalStatus(entry.status));
 			if (active.length === 0) return;
@@ -2884,6 +3139,38 @@ function createExtension(deps = defaultDeps, options = {}) {
 				display: true
 			} };
 		});
+		pi.on("agent_before_settle", async (event) => {
+			if (event.outcome !== "completed") return;
+			const deliverable = [];
+			for (const run of trackedRuns.values()) {
+				if (!run.pendingNotice) continue;
+				if (run.idleSend?.inFlight) continue;
+				deliverable.push({
+					run,
+					notice: run.pendingNotice
+				});
+			}
+			if (deliverable.length === 0) return;
+			for (const { run } of deliverable) {
+				run.pendingNotice = void 0;
+				trackedRuns.delete(trackedRunKey(run.supervisorId, run.runId));
+			}
+			updateWidget(lastStatusEntries);
+			return {
+				entries: [...event.entries, ...deliverable.map(({ run, notice }) => ({
+					type: "custom_message",
+					customType: "avenor-completion",
+					content: notice.text,
+					display: true,
+					details: {
+						run_id: run.runId,
+						supervisor_id: run.supervisorId,
+						status: notice.status
+					}
+				}))],
+				continue: true
+			};
+		});
 		pi.registerMessageRenderer("avenor-active-runs", (message, _options, theme) => {
 			const lines = message.content.split("\n");
 			let text = "";
@@ -3022,7 +3309,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 						}).catch(() => void 0));
 						if (probed && (isTerminalStatus(probed.status) || probed.status === "waiting")) waitStatus = probed;
 						else {
-							const tracked = getTrackedRun(result.run_id, supervisorId);
+							const tracked = getTrackedRunById(result.run_id, supervisorId);
 							if (tracked) tracked.blocking = false;
 							return {
 								content: [{
@@ -3041,7 +3328,8 @@ function createExtension(deps = defaultDeps, options = {}) {
 							};
 						}
 					} else {
-						trackedRuns.delete(trackedRunKey(supervisorId, result.run_id));
+						const runKey = trackedRunKey(supervisorId, result.run_id);
+						trackedRuns.delete(runKey);
 						return {
 							content: [{
 								type: "text",
@@ -3066,10 +3354,13 @@ function createExtension(deps = defaultDeps, options = {}) {
 						...spawnIdentityMetadata(hostParams)
 					}
 				};
-				upsertTrackedRun(runRef, status, wait);
+				if (trackedRuns.has(trackedRunKey(supervisorId, result.run_id))) upsertTrackedRun(runRef, status, wait);
 				if (status.status === "waiting") {
-					const tracked = getTrackedRun(result.run_id, supervisorId);
-					if (tracked) tracked.permissionNotified = true;
+					const tracked = getTrackedRunById(result.run_id, supervisorId);
+					if (tracked) {
+						tracked.permissionNotified = true;
+						tracked.blocking = false;
+					}
 					return {
 						content: [{
 							type: "text",
@@ -3093,16 +3384,19 @@ function createExtension(deps = defaultDeps, options = {}) {
 						runId: result.run_id,
 						supervisorId
 					}, status);
-					emitAvenorEvent(pi.events, CHANNEL_RUN_TERMINAL, createRunTerminalPayload({
-						runId: result.run_id,
-						supervisorId,
+					const runKey = trackedRunKey(supervisorId, result.run_id);
+					const tracked = trackedRuns.get(runKey);
+					emitRunTerminal({
+						run: tracked,
 						runtimeId: status.runtime_id ?? runRef.runtimeId,
 						label,
 						agent: params.agent,
 						status: status.status,
+						nestedCount: tracked?.nestedCount,
 						backend: status.backend
-					}));
-					trackedRuns.delete(trackedRunKey(supervisorId, result.run_id));
+					});
+					trackedRuns.delete(runKey);
+					updateWidget(lastStatusEntries);
 					return {
 						content: [{
 							type: "text",
@@ -3120,6 +3414,8 @@ function createExtension(deps = defaultDeps, options = {}) {
 						}
 					};
 				}
+				const fallthrough = getTrackedRunById(result.run_id, supervisorId);
+				if (fallthrough) fallthrough.blocking = false;
 				return {
 					content: [{
 						type: "text",
@@ -3205,6 +3501,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 				const previousBlocking = tracked?.blocking;
 				if (tracked) tracked.blocking = true;
 				let completed = false;
+				let resultRun = tracked;
 				const blockingWait = params.wait ?? true ? createInterruptibleWait(trackedRunKey(tracked?.supervisorId ?? params.supervisor_id, tracked?.runId ?? params.run_id), signal) : void 0;
 				try {
 					let result;
@@ -3221,18 +3518,30 @@ function createExtension(deps = defaultDeps, options = {}) {
 						result = await resultAfterInterrupt(params, blockingWait.stopped, tracked);
 					}
 					completed = result.ready;
+					resultRun = reconcileResultRun(tracked, result, params.supervisor_id);
 					if (completed) {
-						if (tracked) tracked.consumed = true;
-						emitAvenorEvent(pi.events, CHANNEL_RUN_TERMINAL, createRunTerminalPayload({
-							runId: params.run_id,
-							supervisorId: tracked?.supervisorId ?? params.supervisor_id,
-							runtimeId: tracked?.runtimeId ?? result.runtime_id,
-							label: tracked?.label ?? result.label ?? params.run_id,
-							agent: tracked?.agent ?? "unknown",
-							status: result.status ?? "done"
-						}));
-						if (tracked) trackedRuns.delete(trackedRunKey(tracked.supervisorId, tracked.runId));
-					} else if (tracked && result.status === "waiting") tracked.permissionNotified = true;
+						const idMatches = trackedRunsById(params.run_id, params.supervisor_id).length;
+						const labelMatches = [...trackedRuns.values()].filter((run) => (params.supervisor_id === void 0 || run.supervisorId === params.supervisor_id) && run.label === params.run_id).length;
+						emitRunTerminal({
+							run: resultRun,
+							runId: idMatches > 1 || idMatches === 0 && labelMatches > 1 ? void 0 : result.run_id ?? params.run_id,
+							supervisorId: params.supervisor_id,
+							runtimeId: resultRun?.runtimeId ?? result.runtime_id,
+							label: resultRun?.label ?? result.label ?? params.run_id,
+							agent: resultRun?.agent ?? "unknown",
+							status: result.status ?? "done",
+							nestedCount: resultRun?.nestedCount,
+							backend: resultRun?.lastStatus?.backend
+						});
+						if (resultRun) {
+							trackedRuns.delete(trackedRunKey(resultRun.supervisorId, resultRun.runId));
+							updateWidget(lastStatusEntries);
+							if (tracked && resultRun !== tracked) {
+								const trackedKey = trackedRunKey(tracked.supervisorId, tracked.runId);
+								if (trackedRuns.get(trackedKey) === tracked) tracked.blocking = previousBlocking ?? false;
+							}
+						} else if (tracked && trackedRuns.get(trackedRunKey(tracked.supervisorId, tracked.runId)) === tracked) tracked.blocking = previousBlocking ?? false;
+					} else if (resultRun && result.status === "waiting") resultRun.permissionNotified = true;
 					return {
 						content: [{
 							type: "text",
@@ -3242,7 +3551,7 @@ function createExtension(deps = defaultDeps, options = {}) {
 					};
 				} finally {
 					blockingWait?.dispose();
-					if (!completed && tracked && getTrackedRun(params.run_id, params.supervisor_id) === tracked) tracked.blocking = previousBlocking ?? false;
+					if (!completed && tracked && trackedRuns.get(trackedRunKey(tracked.supervisorId, tracked.runId)) === tracked) tracked.blocking = previousBlocking ?? false;
 				}
 			},
 			renderCall(args, theme, context) {
@@ -3832,4 +4141,4 @@ function createExtension(deps = defaultDeps, options = {}) {
 }
 var src_default = createExtension();
 //#endregion
-export { CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, buildCompletionText, buildInspectPayload, compactWhitespace, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, src_default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };
+export { CHANNEL_DELIVERY_ERROR, CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, buildCompletionText, buildInspectPayload, compactWhitespace, createDeliveryErrorPayload, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, src_default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dougbots/avenor-pi",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -35,15 +35,15 @@
     "dev": "tsdown --watch"
   },
   "dependencies": {
-    "@dougbots/avenor-core": "^0.16.1"
+    "@dougbots/avenor-core": "^0.17.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-coding-agent": ">=1.4.0",
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": "^1.4.0",
+    "@earendil-works/pi-tui": "^1.4.0",
     "@types/bun": "^1.3.12",
     "@types/node": "^25.8.0",
     "tsdown": "^0.22.0",