@aeondave/pi-persona 1.16.1 → 1.16.2

package/AGENTS.md

@@ -115,6 +115,8 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   never double-reported; snapshots leave running children active. In interactive sessions `delegate`
   is background-by-default (`sync: true` opts a call out; headless `pi -p` defaults to sync so the
   single turn carries the result). An explicit `async` flag takes precedence over `sync` and the default.
+  Periodic async status is a durable, expandable operator-only entry, never a model wake or context
+  message; completions, asks, unread bus messages, and newly-stalled alerts keep their actionable paths.
   Message ids and run ids are separate: `intercom message { messageId }` retrieves retained bus
   text, `intercom result { to: runId }` retrieves a settled run. Both explicit and automatic inbox
   drains retain bounded history (256 messages / 256,000 body characters). Ask settlement clears

package/CHANGELOG.md

@@ -6,6 +6,16 @@ used in its [GitHub releases](https://github.com/AeonDave/pi-persona/releases).
 
 ## [Unreleased]
 
+## [1.16.2](https://github.com/AeonDave/pi-persona/releases/tag/v1.16.2) - 2026-10-08
+
+### Fixed
+
+- Keep routine async check-ins visible as durable, expandable operator status entries without starting
+  model turns; completion, ask, unread-message, and newly-stalled follow-ups remain actionable wakes.
+- Show periodic status while the supervisor is busy, without consuming pending actionable messages.
+- Keep stall/message delivery independent of status-card persistence failures and report those failures
+  non-fatally. Align supervisor guidance and documentation with the status-only check-in contract.
+
 ## [1.16.1](https://github.com/AeonDave/pi-persona/releases/tag/v1.16.1) - 2026-10-06
 
 ### Fixed

package/README.md

@@ -39,9 +39,9 @@ your customizations.
 | Install option | Command |
 |---|---|
 | This project only | `pi install -l npm:@aeondave/pi-persona` |
-| Pin this release | `pi install npm:@aeondave/pi-persona@1.16.1` |
+| Pin this release | `pi install npm:@aeondave/pi-persona@1.16.2` |
 | Update an unpinned install | `pi update npm:@aeondave/pi-persona` |
-| Git alternative | `pi install git:github.com/AeonDave/pi-persona@v1.16.1` |
+| Git alternative | `pi install git:github.com/AeonDave/pi-persona@v1.16.2` |
 
 Restart Pi after updating. For a pinned install, install the new version or tag explicitly.
 If switching from a Git install, remove that source first with
@@ -75,6 +75,10 @@ the outcome. This is one possible workflow, not a fixed pipeline; dependent step
 Interactive delegation runs in the background by default. Results return automatically when the
 supervisor is free; you can inspect or redirect a worker at any point.
 
+Periodic async status appears as a durable, expandable operator-only card (five minutes by default); it
+does not start a model turn or enter model context. Completions, blocking asks, unread worker messages,
+and newly stalled workers still use their actionable notification paths.
+
 Launch and control cards show the worker's name. Steering receipts preview the message sent;
 expand with `Ctrl+O` (the default binding) to read it in full. A queued message is not proof that
 the worker has acted on it.

package/docs/ARCHITECTURE.md

@@ -644,19 +644,19 @@ a local process able to modify that directory is already inside the trust bounda
   if delayed input hooks outlast the active run; no supported post-admission ordering guarantee
   has been established. The supervisor otherwise returns control and
   goes idle until a wake; the **peek watchdog** fires while async children run but stays SILENT unless
-  there is something to act on — a healthy background run should not interrupt. It surfaces on two independent
-  signals: a **fast** wakeup (`PI_PERSONA_PEEK_MS`, ~30s, `0` disables) when a child NEWLY crosses the
-  `STALL_FLAG_MS` (90s) stall window (a focused *possibly stuck* alert, framed patience-first — ask the
-  leg, don't probe its environment) or messages the supervisor; and a **slow routine check-in**
-  (`PI_PERSONA_CHECKIN_MS`, ~5 min, `0` disables) delivering the compact ProgressView digest — never
-  full transcripts — so the supervisor can catch a leg going off-track early. Live supervisor asks
+  there is something to act on — a healthy background run should not interrupt. It can start a model turn
+  only for actionable events: a **fast** wakeup (`PI_PERSONA_PEEK_MS`, ~30s, `0` disables) when a child NEWLY
+  crosses the `STALL_FLAG_MS` (90s) stall window (a focused *possibly stuck* alert, framed patience-first —
+  ask the leg, don't probe its environment); messages to the supervisor also wake it. The **slow routine status card**
+  (`PI_PERSONA_CHECKIN_MS`, ~5 min, `0` disables) is a durable, expandable operator-only session entry
+  with the compact ProgressView digest — never full transcripts — and does not start a model turn. Live supervisor asks
   are derived from the exact engine handle's optional `isWaitingForSupervisor` predicate: tree/F9/peek
   show waiting, and the watchdog suppresses false stalls until the ask settles. Parent clocks advance
   with child engine events (liveness, not proof of useful work); parents are waiting only when every
   live descendant branch is waiting.
-  Both let an idle
-  supervisor steer/stop a wedged or drifting child even with NO completion fired; the enforcing
-  backstop is the engines' hard wall-clock cap (above). The full digest is also on demand via `/peek`.
+  Stall alerts and live messages let an idle supervisor steer/stop a wedged child even with NO completion
+  fired; the enforcing backstop is the engines' hard wall-clock cap (above). The full digest is also on demand
+  via `/peek`.
   Progress tokens are labelled **cumulative input/output**, not context occupancy; cache-read/write
   accounting is separate. Do not infer a full context window from that counter. File age or line-count
   changes alone likewise do not establish a stall, a passing test or completed work.

package/docs/REFERENCE.md

@@ -147,8 +147,9 @@ session entry remain authoritative. `agent_name` is unavailable while Exocom is
 also rejects empty, unsafe, generic, or reserved persona/agent names.
 
 Naming needs one tool action, not a recurring prose confirmation. A stable system-level runtime rule
-also distinguishes skill-prefetch and routine check-ins from new user requests; it neither hides
-updates nor rewrites conversation history. After updating extension code, use Pi's `/reload` once
+distinguishes skill-prefetch bookkeeping from new user requests; it neither hides updates nor rewrites
+conversation history. Periodic async status is a durable operator-only entry, not a model wake or
+context message. After updating extension code, use Pi's `/reload` once
 delegated work has settled (or restart/resume); `/persona reload` reloads definitions only.
 
 With Exocom active, the corresponding tool is `exocom_name`. The first incoming peer wake can be the
@@ -446,7 +447,7 @@ from a different cwd. Pi owns `--model <provider/id>`, `--thinking
 | `PI_PERSONA_SEED` | off | `on` auto-installs bundled personas on first run |
 | `PI_PERSONA_BROKER` | on | `off` disables the cross-process comm plane for child, worktree, and MCP legs |
 | `PI_PERSONA_PEEK_MS` | 30000 | fast async stall/message wakeup tick; `0` disables it |
-| `PI_PERSONA_CHECKIN_MS` | 300000 | routine direction check-in while async children run; `0` disables it |
+| `PI_PERSONA_CHECKIN_MS` | 300000 | durable expandable operator status entry while async children run; does not start a model turn; `0` disables it |
 | `PI_PERSONA_AGENT_MAX_MS` | off | opt-in per-agent hard wall-clock cap; unset leaves healthy work running |
 | `PI_PERSONA_AGENT_STARTUP_MS` | 300000 | startup deadline for a child that makes no progress; `0` disables it. Like the idle window, a leg waiting on a supervisor reply is not idle: the watchdog re-arms while its ask is pending, instead of killing on a blind ceiling |
 | `PI_PERSONA_NUDGE` | on | `off` silences delegation and persistence nudges; synchronous checkpoints stay in model-visible tool results and are mirrored to durable, expandable TUI-only cards |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeondave/pi-persona",
-  "version": "1.16.1",
+  "version": "1.16.2",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
@@ -104,7 +104,7 @@
     "typescript": "^7.0.2"
   },
   "pi": {
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.16.1/assets/banner.png",
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.16.2/assets/banner.png",
     "video": "https://cdn.jsdelivr.net/gh/AeonDave/pi-persona@6655d281ce7965a75303dd704bd29db73db04070/assets/demo1.mp4",
     "extensions": [
       "./src/extension.ts"

package/personas/elite.md

@@ -228,8 +228,8 @@ the user with the packet — don't silently swap to route around it.
 ## Supervise async runs — trust the hand-off, don't hover
 A background leg reports back on its own the moment it finishes (`sync: true` to block instead) — so
 dispatch and keep working the thread you kept; you do NOT watch it or poll its progress. pi-persona
-wakes you when a leg stalls or messages you, and hands you an occasional check-in digest so you can
-catch one going off-track early — react to those; otherwise let a healthy run go, its result returns on
+wakes you when a leg newly stalls or messages you; periodic status cards are visible to the operator
+but do not interrupt your turn. React to actionable wakeups; otherwise let a healthy run go, its result returns on
 its own. A long scan, a big generation, or a blocking command looks identical to a stall from the
 outside, so default to patience. `steer` only on CONFIRMED drift (wrong target, rabbit hole, a
 sustained stall), and steer by asking the leg for a one-line status — never run commands in its

package/src/core/brief.ts

@@ -19,7 +19,7 @@ import { inventedExocomNameHint, inventedLegNameHint } from "./naming.ts";
 
 /** Stable protocol guidance, not a user-like reminder or the optional behavioral spine. */
 export const RUNTIME_CONTEXT_GUIDANCE =
-	"[pi-persona] Runtime context: identity metadata, skill-prefetch catalogs, clock snapshots and routine check-ins " +
+	"[pi-persona] Runtime context: identity metadata, skill-prefetch catalogs and clock snapshots " +
 	"are background context, not new user requests. Perform required setup once. Do not repeat identity confirmations " +
 	"or narrate unchanged setup/skill bookkeeping after each tool result. Apply relevant skill instructions; availability " +
 	"alone is not evidence that a skill was loaded or used. Report material changes, blockers and decisions. Explain " +
@@ -148,7 +148,7 @@ export function buildDelegationBrief(input: BriefInput): string | undefined {
 
 	const example = input.agents.some((a) => a.name === "operator") ? "operator" : (listed[0]?.name ?? "operator");
 	const delivery = input.asyncDefault
-		? "they run in the background and each result returns to you automatically as a follow-up — do useful independent work while children run; when only children remain, end your turn and let completion wake you. Do not monitor, poll, or automatically wait for all children (don't watch or poll a healthy leg). Join intentionally only when a result is needed before your next step; you're also woken if a child stalls or messages you, plus an occasional check-in to catch drift"
+		? "they run in the background and each result returns to you automatically as a follow-up — do useful independent work while children run; when only children remain, end your turn and let completion wake you. Do not monitor, poll, or automatically wait for all children (don't watch or poll a healthy leg). Join intentionally only when a result is needed before your next step; you're woken if a child newly stalls or messages you. Periodic status cards are for the operator and do not interrupt your work"
 		: "the call returns when they finish";
 	const callFields = [`agent: "${example}"`, `task: "<self-contained bounded task + success signal>"`];
 	if (input.requireBrief) {

package/src/core/config.ts

@@ -29,10 +29,10 @@ export interface PiPersonaConfig {
 	 *  healthy run never interrupts. On by default (30000); PI_PERSONA_PEEK_MS=0 opts out (the routine
 	 *  check-in below is independent). */
 	peekEveryMs: number;
-	/** Routine check-in interval (ms): how often, while async children run, the idle supervisor gets
-	 *  a compact progress digest so it can catch a leg going off-track (not stalled — just wrong) and
-	 *  step in early. Deliberately slow so it is an occasional glance, not a poll, and independent of
-	 *  the fast stall/message wakeup. 300000 (5 min) by default; PI_PERSONA_CHECKIN_MS=0 opts out. */
+	/** Routine check-in interval (ms): how often, while async children run, the operator gets a durable,
+	 *  expandable compact progress entry. It is status-only and does not start a model turn. Deliberately
+	 *  slow and independent of the fast stall/message wakeup. 300000 (5 min) by default;
+	 *  PI_PERSONA_CHECKIN_MS=0 opts out. */
 	checkInEveryMs: number;
 	/** Per-agent hard wall-clock cap (ms): an OPT-IN lifetime ceiling. When set (>0) it settles even
 	 *  a busy-but-non-converging child the idle watchdog (reset on every event) never catches.

package/src/engine/async.ts

@@ -547,19 +547,9 @@ export function buildPeekAlert(stuck: AsyncRun[], opts: { now: number }): string
 	].join("\n");
 }
 
-/**
- * The routine check-in: the full progress view ({@link buildPeekDigest}) plus a one-line framing that
- * this is an occasional glance, not a poll — step in only if a leg is off-track or wedged, otherwise
- * carry on. It fires on the slow check-in cadence (config.checkInEveryMs) and is the counterpart to the
- * fast {@link buildPeekAlert} stall signal: it catches a leg going the WRONG way (not stalled, just
- * wrong) before it burns the budget, without waking the supervisor every tick.
- */
+/** The operator-only periodic status card. It carries the progress digest without model instructions. */
 export function buildCheckIn(runs: AsyncRun[], opts: { now: number; stallMs: number; waitingForSupervisor?: ReadonlySet<string> }): string {
-	return (
-		`${buildPeekDigest(runs, opts)}\n\n` +
-		"Routine check-in — internal status update, not a new task: don't reply just to acknowledge unchanged progress. Continue your current " +
-		"work and step in only if a leg is off-track (wrong target, rabbit hole) or wedged. Each result returns to you on its own."
-	);
+	return `Async activity · routine check-in\n\n${buildPeekDigest(runs, opts)}`;
 }
 
 /**

package/src/extension.ts

@@ -181,6 +181,10 @@ interface NudgeEntry {
 	content: string;
 }
 
+interface CheckInEntry {
+	content: string;
+}
+
 /**
  * Keep the immediate operator-facing settlement toast and the semantic completion delivery on one
  * path. A supervisor-requested abort is terminal, but it is not an execution error: the tracker
@@ -335,9 +339,25 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		const hint = hasMore ? `\n${theme.fg("dim", expandDetailHint())}` : "";
 		return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
 	});
+	pi.registerEntryRenderer("pi-persona-status", (entry, { expanded }, theme) => {
+		const data = entry.data as CheckInEntry;
+		const full = sanitizeTerminalText(data.content || "Async activity · routine check-in");
+		const title = theme.fg("accent", theme.bold("pi-persona · async status"));
+		if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", full)}`, 0, 0);
+		// The entry title already labels this as async status. Spend the compact preview on the
+		// aggregate and first run row so the operator sees the selected alias and usage label.
+		const digestLines = full.split("\n").slice(1).filter((line) => line.trim().length > 0);
+		const preview = compactVisibleText(digestLines.slice(0, 2).join("\n") || full, { maxLines: 2, maxLineChars: 140 });
+		const hasMore = preview.truncated || digestLines.length > 2;
+		const hint = hasMore ? `\n${theme.fg("dim", expandDetailHint())}` : "";
+		return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
+	});
 	const appendNudgeEntry = (content: string): void => {
 		pi.appendEntry("pi-persona-nudge", { content } satisfies NudgeEntry);
 	};
+	const appendCheckInEntry = (content: string): void => {
+		pi.appendEntry("pi-persona-status", { content } satisfies CheckInEntry);
+	};
 	const appendCommandResult = (
 		label: string,
 		content: string,
@@ -1176,15 +1196,11 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		});
 	});
 
-	// Peek watchdog (the timed supervisor wakeup, on by default — PI_PERSONA_PEEK_MS=0 opts out): while
-	// async children run, a tick checks their progress but stays SILENT unless there is something to act
-	// on, so a healthy background run never interrupts the supervisor. It wakes on two signals: a leg
-	// that NEWLY looks stalled or an unread message (fast, PI_PERSONA_PEEK_MS granularity), and a routine
-	// direction check-in (slow, PI_PERSONA_CHECKIN_MS) to catch a leg going off-track. Bounded: unref'd,
-	// self-stops when no runs remain.
+	// Async-run watchdog: the fast PI_PERSONA_PEEK_MS cadence wakes the supervisor only for a newly-stalled
+	// leg or unread message. The slower PI_PERSONA_CHECKIN_MS cadence appends a durable operator-only status
+	// card; it does not start a model turn. Bounded: unref'd, self-stops when no runs remain.
 	let peekTimer: ReturnType<typeof setInterval> | undefined;
-	// When the supervisor was last woken about a run (a stall alert, a message, or a routine check-in).
-	// Gates the slow check-in cadence so it counts from the last time we actually surfaced something.
+	// Last time progress status was surfaced (a new stall alert or routine card), for the slow cadence.
 	let lastPeekAt = 0;
 	function stopPeek(): void {
 		if (peekTimer) {
@@ -1193,9 +1209,8 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 		}
 	}
 	function startPeek(): void {
-		// The two signals opt out independently: the fast stall/message wakeup follows PI_PERSONA_PEEK_MS,
-		// the routine check-in follows PI_PERSONA_CHECKIN_MS. The carrier timer runs while EITHER is on and
-		// ticks at the faster of the two (a disabled one is Infinity, so it never drives).
+		// Fast wakeups and routine cards opt out independently. The carrier timer runs while EITHER is on
+		// and ticks at the faster of the two (a disabled one is Infinity, so it never drives).
 		const fastMs = config.peekEveryMs > 0 ? config.peekEveryMs : Number.POSITIVE_INFINITY;
 		const checkMs = config.checkInEveryMs > 0 ? config.checkInEveryMs : Number.POSITIVE_INFINITY;
 		const tickMs = Math.min(fastMs, checkMs);
@@ -1207,31 +1222,42 @@ export default function piPersona(pi: ExtensionAPI, options: PiPersonaOptions =
 				stopPeek();
 				return;
 			}
-			// Only peek a free, unqueued supervisor: an idle delivery triggers a clean turn, while a
-			// busy one would pile up as a sticky follow-up. Skipping is safe — the next tick re-surfaces.
-			if (!canDeliverPersonaNotification(orchestrating, processingDeferredOrchestration, lastCtx?.isIdle?.() === true) || lastCtx?.hasPendingMessages?.() === true) return;
-			// The peek is NOT a poll. Two signals, two cadences: (1) the FAST wakeup (PI_PERSONA_PEEK_MS) —
-			// a leg that NEWLY crossed the stall window, or an unread sub-agent message — the "is it dead or
-			// wedged" check; (2) the SLOW routine check-in (PI_PERSONA_CHECKIN_MS) — a progress digest that
-			// catches a leg going off-track (not stalled, just wrong) early. A healthy, quiet run between
-			// check-ins produces no wakeup. Completions always arrive on their own (completionNotifier), and
-			// the full status view stays on demand via `/peek`.
 			const now = Date.now();
+			const dueCheckIn = config.checkInEveryMs > 0 && now - lastPeekAt >= config.checkInEveryMs;
+			// Routine status is durable operator history, not a model notification: append it on cadence even
+			// while a turn is busy or human input is queued. This keeps visibility independent of wake eligibility.
+			if (dueCheckIn) {
+				lastPeekAt = now;
+				try {
+					appendCheckInEntry(buildCheckIn(runs, { now, stallMs: STALL_FLAG_MS, waitingForSupervisor: waitingAsyncRunIds() }));
+				} catch (error) {
+					const detail = compactInlineText(error instanceof Error ? error.message : String(error), { maxChars: 120 });
+					const warning = `pi-persona: could not append async status entry${detail ? ` (${detail})` : ""}`;
+					let shown = false;
+					if (lastCtx?.hasUI) {
+						try { lastCtx.ui.notify(warning, "warning"); shown = true; } catch { /* session may be tearing down */ }
+					}
+					if (!shown || process.env.PI_PERSONA_DEBUG) {
+						try { process.stderr.write(`[pi-persona] ${warning}\n`); } catch { /* diagnostics must not block an actionable wake */ }
+					}
+				}
+			}
+			// Poll actionable model wakes only for a free supervisor. A busy/queued session keeps messages
+			// unread and leaves stall state untouched for the next tick, rather than stacking sticky follow-ups.
+			if (!canDeliverPersonaNotification(orchestrating, processingDeferredOrchestration, lastCtx?.isIdle?.() === true) || lastCtx?.hasPendingMessages?.() === true) return;
+			// The watchdog is not a model polling loop: the FAST path wakes on newly-stalled legs or unread
+			// progress messages. Completions arrive separately through completionNotifier; `/peek` remains on demand.
 			const fast = config.peekEveryMs > 0;
 			const waitingRuns = waitingAsyncRunIds();
 			const stuck = fast ? peekWatcher.poll(runs, now, STALL_FLAG_MS, waitingRuns) : [];
 			// Drain only progress messages; blocking asks (expectsReply) are surfaced by the intercom
 			// notifier and left for the `intercom inbox` tool — so peek never double-shows them.
 			const unread = fast ? bus.takeWhere(SUPERVISOR, (e) => !e.expectsReply) : [];
-			const dueCheckIn = config.checkInEveryMs > 0 && now - lastPeekAt >= config.checkInEveryMs;
-			if (stuck.length === 0 && unread.length === 0 && !dueCheckIn) return; // healthy + quiet ⇒ stay silent
+			if (stuck.length === 0 && unread.length === 0) return; // healthy + quiet ⇒ stay silent
 			const parts: string[] = [];
 			if (stuck.length > 0) parts.push(buildPeekAlert(stuck, { now }));
-			else if (dueCheckIn) parts.push(buildCheckIn(runs, { now, stallMs: STALL_FLAG_MS, waitingForSupervisor: waitingRuns }));
 			if (unread.length > 0) parts.push(`📨 from sub-agents:\n${fenceUntrusted(formatInbox(unread))}`);
-			// Reset the check-in cadence only on a PROGRESS surfacing (a stall alert or a check-in), NOT on a
-			// message-only wake — else a chatty child would postpone the routine off-track glance forever.
-			if (stuck.length > 0 || dueCheckIn) lastPeekAt = now;
+			if (stuck.length > 0) lastPeekAt = now; // message-only wakes do not postpone the routine status cadence
 			try {
 				sendPersonaFollowUp(pi, `[pi-persona] ${parts.join("\n\n")}`);
 			} catch {

package/src/telemetry/contract.ts

@@ -4,7 +4,7 @@ export const TELEMETRY_EVENT_NAME = "pi:telemetry" as const;
 export const LEGACY_TELEMETRY_EVENT_NAME = "pi-persona:telemetry" as const;
 export const LEGACY_TELEMETRY_VERSION = 1 as const;
 export const TELEMETRY_PRODUCER_ID = "pi-persona" as const;
-export const TELEMETRY_PRODUCER_VERSION = "1.16.1" as const;
+export const TELEMETRY_PRODUCER_VERSION = "1.16.2" as const;
 
 export type InstanceStatus = "active" | "idle" | "stopped" | "stale" | (string & {});
 export type AgentKind = "subagent" | "delegate" | "council" | "flow" | "phase" | (string & {});

package/src/tools/delegate-tool.ts

@@ -391,7 +391,7 @@ export function registerDelegateTool(pi: ExtensionAPI, d: DelegateToolDeps): voi
 			...(runSpec.model ? { model: runSpec.model } : {}),
 			detail: "queued",
 		});
-		d.startPeek(); // arm the timed supervisor wakeup while this run is in flight (no-op if PI_PERSONA_PEEK_MS=0)
+		d.startPeek(); // arm the async-run status/stall monitor (no-op if both cadences are disabled)
 		return id;
 	}