@aeondave/pi-persona 1.15.2

package/src/core/session-identity.ts

@@ -0,0 +1,89 @@
+/**
+ * Pure session identity primitives.
+ *
+ * A session identity is a small personal handle for one Pi session.  It is deliberately
+ * independent from the active persona, an agent role, and the Exocom registry.  The extension
+ * adapter owns persistence and host lifecycle; this module only defines the bounded data shape and
+ * the rules used when data crosses that boundary.
+ */
+
+import { sanitizeDisplayLabel } from "./display-label.ts";
+import { stripTerminalControls } from "./fence.ts";
+
+export const IDENTITY_ENTRY_CUSTOM_TYPE = "pi-persona:identity";
+export const IDENTITY_CONTEXT_CUSTOM_TYPE = "pi-persona:identity-context";
+export const MAX_IDENTITY_NAME_CHARS = 32;
+
+export interface SessionIdentityEntryData {
+	version: 1;
+	sessionId: string;
+	name: string;
+}
+
+const GENERIC_IDENTITY_NAMES = new Set(["unnamed", "agent", "supervisor", "pi"]);
+
+/** Canonical comparison key for a human-provided label. */
+export function identityNameKey(value: unknown): string {
+	if (typeof value !== "string") return "";
+	return stripTerminalControls(value)
+		.normalize("NFKC")
+		.trim()
+		.toLocaleLowerCase("en-US")
+		.replace(/[\s_-]+/gu, "-");
+}
+
+/** Whether a name is reserved by the generic runtime or by a discovered persona/agent. */
+export function isReservedIdentityName(name: unknown, reservedNames: readonly string[] = []): boolean {
+	const key = identityNameKey(name);
+	if (!key) return false;
+	if (GENERIC_IDENTITY_NAMES.has(key)) return true;
+	return reservedNames.some((reserved) => {
+		const reservedKey = identityNameKey(reserved);
+		return reservedKey !== "" && (reservedKey === key || identityNameKey(sanitizeDisplayLabel(reserved, "", MAX_IDENTITY_NAME_CHARS)) === key);
+	});
+}
+
+/**
+ * Reduce a candidate to a short, printable display label.  `undefined` means the value cannot be
+ * used as an identity.  The explicit empty fallback is intentional: `sanitizeDisplayLabel`'s
+ * normal fallback is useful for UI labels but would turn an empty identity into "agent".
+ */
+export function sanitizeIdentityName(value: unknown, reservedNames: readonly string[] = []): string | undefined {
+	if (typeof value !== "string") return undefined;
+	const visible = stripTerminalControls(value.slice(0, 4096)).normalize("NFKC").trim();
+	if (!visible) return undefined;
+	const safe = sanitizeDisplayLabel(visible, "", MAX_IDENTITY_NAME_CHARS);
+	if (!safe || isReservedIdentityName(safe, reservedNames)) return undefined;
+	return safe;
+}
+
+/** Make a distinct provisional handle from a session id without consulting any name catalog. */
+export function provisionalIdentityName(sessionId: string): string {
+	const alphanumeric = sessionId.normalize("NFKC").replace(/[^A-Za-z0-9]/g, "");
+	return `pi-${(alphanumeric.slice(-8) || "unknown")}`;
+}
+
+/** Read the newest valid identity entry on the selected session branch. */
+export function findStoredIdentity(
+	entries: readonly unknown[],
+	sessionId: string,
+	reservedNames: readonly string[] = [],
+): string | undefined {
+	if (!sessionId) return undefined;
+	let found: string | undefined;
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const item = entry as { type?: unknown; customType?: unknown; data?: unknown };
+		if (item.type !== "custom" || item.customType !== IDENTITY_ENTRY_CUSTOM_TYPE) continue;
+		if (!item.data || typeof item.data !== "object") continue;
+		const data = item.data as Partial<SessionIdentityEntryData>;
+		if (data.version !== 1 || data.sessionId !== sessionId || typeof data.name !== "string") continue;
+		const safe = sanitizeIdentityName(data.name, reservedNames);
+		if (safe) found = safe;
+	}
+	return found;
+}
+
+export function makeIdentityEntry(sessionId: string, name: string): SessionIdentityEntryData {
+	return { version: 1, sessionId, name };
+}

package/src/core/time.ts

@@ -0,0 +1,202 @@
+/**
+ * Time awareness — the readings that give the model back a clock, and the one rule that decides
+ * how precise each of them may be.
+ *
+ * Nothing in pi's base prompt carries a date or a time, so from inside a turn five minutes of work
+ * and five hours look identical: a supervisor cannot tell how long it has been on a problem, and a
+ * peer reply that took twenty minutes reads exactly like an instant one. This module renders the
+ * durations that fix that. Pure (every clock is an argument), so none of it needs a real one.
+ *
+ * The rule, which is why the tail and session-anchor renderings have different granularities:
+ *
+ *   - Text APPENDED to the conversation TAIL (a tool result, a delivered message) is written once
+ *     and never re-sent as the provider's cached prefix, so precision there is free —
+ *     {@link formatDuration} and {@link peerSentLabel} may say "2m 5s".
+ *   - Text in the SYSTEM PROMPT is re-sent every turn and IS the cached prefix. The session anchor
+ *     therefore uses a deliberately coarse ladder ({@link sessionElapsedLabel}) that steps a couple
+ *     of dozen times a DAY. The fresh current clock is delivered separately in the per-run tail, so
+ *     it can carry seconds without invalidating the cached system prefix. The companion
+ *     pi-persona-mind module makes the same trade for its stable age reading.
+ *
+ * Both readings state an elapsed time as fact, so both refuse the inputs that would turn that
+ * statement into a lie — see {@link parseInstant} and the plausibility bound each one applies.
+ */
+
+/**
+ * Compact wall-clock duration for a TAIL surface: "<1s", "43s", "2m 5s", "2h 5m", "3d 4h". Two
+ * units at most — this rides on reports the supervisor reads every time a leg lands.
+ */
+export function formatDuration(ms: number): string {
+	if (!Number.isFinite(ms) || ms < 0) return "?"; // corrupt/absent input — never render "NaNs"
+	const seconds = Math.floor(ms / 1_000);
+	if (seconds < 1) return "<1s";
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) {
+		const rest = seconds % 60;
+		return rest > 0 ? `${minutes}m ${rest}s` : `${minutes}m`;
+	}
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) {
+		const rest = minutes % 60;
+		return rest > 0 ? `${hours}h ${rest}m` : `${hours}h`;
+	}
+	const days = Math.floor(hours / 24);
+	const rest = hours % 24;
+	return rest > 0 ? `${days}d ${rest}h` : `${days}d`;
+}
+
+/**
+ * An ISO-8601 instant that names exactly one moment: a calendar date — which ECMA-262 fixes to UTC
+ * midnight — optionally followed by a time that MUST carry "Z" or a numeric offset. Anchored at
+ * both ends and free of nested quantifiers, so it stays linear on hostile input; matching a zone
+ * loosely at the tail would read the "-20" of a bare date as an offset.
+ */
+const QUALIFIED_INSTANT = /^[+-]?\d{4,6}-\d{2}-\d{2}(?:[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:[Zz]|[+-]\d{2}:?\d{2}|[+-]\d{2}))?$/;
+
+/**
+ * Parse an instant that is about to be stated as fact, or NaN.
+ *
+ * `Date.parse` silently reads a date-time with no zone ("2026-08-20T11:40:00") as the RECEIVER's
+ * LOCAL time, so the identical string yields a different instant on every machine — two peers
+ * would print two different ages for the same message, each equally confident. An unqualified
+ * string is not a slightly-wrong time, it is an unknown one, so it is refused here rather than
+ * guessed at.
+ */
+export function parseInstant(value: unknown): number {
+	if (typeof value !== "string" || !QUALIFIED_INSTANT.test(value)) return Number.NaN;
+	return Date.parse(value);
+}
+
+/** What the delivery header says when the peer's own timestamp cannot be believed. */
+const UNKNOWN_SENT = "sent at an unknown time (peer clock)";
+/** Two machines' clocks routinely differ by seconds. That is skew, not a claim about the future. */
+const CLOCK_SKEW_TOLERANCE_MS = 60_000;
+/** The widest transit age this header will state as fact. An exocom peer is a LIVE instance in
+ *  this workspace; past this, the sender's clock — not the network — is the explanation. */
+const MAX_PLAUSIBLE_SENT_AGE_MS = 30 * 86_400_000;
+/** The widest session age the anchor will state as fact. A header a year old is not a long
+ *  session, it is a corrupt or misread one; every real session sits far below this. */
+const MAX_PLAUSIBLE_SESSION_AGE_MS = 365 * 86_400_000;
+
+/**
+ * How long ago an inbound peer message was sent, for the delivery header.
+ *
+ * `ts` is authenticated as coming from that peer (it is inside the signed canonical payload), but
+ * its VALUE is the peer's own: its clock may be wrong, or it may simply lie. So the age is measured
+ * against the RECEIVER's clock, and anything we cannot believe — a future time beyond ordinary
+ * skew, an absurd age, a string with no zone, an unparseable one — degrades to one honest label
+ * instead of being rendered as fact ("sent 1096d ago" is a peer-authored claim wearing the
+ * harness's voice). Inside the believable window the age is still the peer's claim, only a
+ * plausible one: bounding the range narrows what a peer can assert, it does not authenticate it.
+ * The result is always a single line: the header it lands on must stay one.
+ */
+export function peerSentLabel(ts: unknown, now: number): string {
+	const sent = parseInstant(ts);
+	if (!Number.isFinite(sent) || !Number.isFinite(now)) return UNKNOWN_SENT;
+	const age = now - sent;
+	if (age < -CLOCK_SKEW_TOLERANCE_MS || age > MAX_PLAUSIBLE_SENT_AGE_MS) return UNKNOWN_SENT;
+	// Tolerated skew lands here too: a message "from the future" by a few seconds just arrived.
+	if (age <= 1_000) return "sent just now";
+	return `sent ${formatDuration(age)} ago`;
+}
+
+/**
+ * The session anchor's elapsed reading — COARSE on purpose, because it is re-sent every turn as
+ * part of the cached system prefix.
+ *
+ * The ladder: one bucket for the first quarter hour, then quarter hours to the first hour, then
+ * whole hours, then days-plus-hours. Worst case for a DAY of continuous work is 27 changes (3
+ * quarter-hour steps + 23 hourly ones + the step into day form), i.e. 27 prefix invalidations where a
+ * minute-granular label would force 1440 — 15 of them in the first 12 hours, and 24/day from day two
+ * on. Each of those 27 buys real signal, since "how long have I been on this"
+ * is a pacing question and nobody paces on minutes after the first hour. Inside any one bucket the
+ * rendered anchor is byte-identical, so an hour of turns re-sends the same bytes.
+ */
+export function sessionElapsedLabel(elapsedMs: number): string {
+	if (!Number.isFinite(elapsedMs)) return "<15m";
+	// A clock that moved backwards (an NTP correction, a session file written by a machine running
+	// ahead of this one) makes `elapsedMs` negative, which falls into the floor bucket below. It
+	// understates; it never invents hours that did not pass.
+	const minutes = Math.floor(elapsedMs / 60_000);
+	if (minutes < 15) return "<15m";
+	if (minutes < 60) return `${Math.floor(minutes / 15) * 15}m`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h`;
+	return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+}
+
+/** The shape this module needs from pi's `SessionHeader` — nothing else, so it stays pure. */
+export interface SessionAnchorHeader {
+	timestamp?: unknown;
+}
+
+export interface ClockSnapshotLocal {
+	/** IANA/local display name. Omit to use the explicit UTC default. */
+	timeZone?: string;
+	/** Local UTC offset in minutes east of UTC. Omit to use the explicit UTC default. */
+	offsetMinutes?: number;
+}
+
+function pad2(value: number): string {
+	return String(value).padStart(2, "0");
+}
+
+/**
+ * Fresh per-run clock text. The epoch and optional local projection are injected so this helper is
+ * deterministic and stays independent of the host timezone. Callers that want the operator's
+ * local zone should resolve it at the runtime boundary and pass both fields.
+ */
+export function buildClockSnapshot(now: number, local?: ClockSnapshotLocal): string | undefined {
+	if (!Number.isFinite(now)) return undefined;
+	const date = new Date(now);
+	if (!Number.isFinite(date.getTime())) return undefined;
+	const utc = date.toISOString().replace(/\.\d{3}Z$/, "Z");
+	const offsetMinutes = local?.offsetMinutes ?? 0;
+	if (!Number.isInteger(offsetMinutes) || Math.abs(offsetMinutes) > 24 * 60) return undefined;
+	const offsetSign = offsetMinutes >= 0 ? "+" : "-";
+	const absoluteOffset = Math.abs(offsetMinutes);
+	const offset = `${offsetSign}${pad2(Math.floor(absoluteOffset / 60))}:${pad2(absoluteOffset % 60)}`;
+	// Project through UTC getters after applying the selected offset.
+	const localDate = new Date(now + offsetMinutes * 60_000);
+	if (!Number.isFinite(localDate.getTime())) return undefined;
+	const zone = local?.timeZone ?? "UTC";
+	const localIso = `${localDate.getUTCFullYear()}-${pad2(localDate.getUTCMonth() + 1)}-${pad2(localDate.getUTCDate())}` +
+		`T${pad2(localDate.getUTCHours())}:${pad2(localDate.getUTCMinutes())}:${pad2(localDate.getUTCSeconds())}${offset}`;
+	return `Current clock: UTC ${utc}; local ${localIso} (${zone}; UTC${offset}).`;
+}
+
+/**
+ * The one-line session time anchor for the cached system prompt, or undefined when there is no
+ * believable start to report.
+ *
+ * WHY the system prompt: the prompt is re-composed and re-sent every turn rather than summarized,
+ * so an anchor placed there cannot be compacted away — the same fact placed in the conversation
+ * tail would be. WHY the header's timestamp: it is the first entry of the append-only session file,
+ * so after `/resume` it is still the ORIGINAL start. That is what makes this answer "how long have
+ * I been on this problem" across restarts and not merely across turns. (Branching mints a NEW
+ * session file with a fresh header, so the reading restarts there — correctly, since that is a new
+ * session; the line claims the life of THIS session, not of the one it was cut from.)
+ *
+ * The absolute start is a constant for the life of the session, so it costs the prompt cache
+ * nothing and it is the half that actually survives; the elapsed reading is bucketed
+ * ({@link sessionElapsedLabel}) so it flips rarely. Use {@link buildClockSnapshot} for the fresh
+ * second-precision reading in a per-run tail.
+ */
+export function buildSessionAnchor(header: SessionAnchorHeader | null | undefined, now: number): string | undefined {
+	const started = parseInstant(header?.timestamp);
+	if (!Number.isFinite(started) || !Number.isFinite(now)) return undefined;
+	// Parseable is not believable. An epoch-zero or year-0001 header parses cleanly and would put
+	// "you have been on it 20685d 12h" into the system prompt as fact; a start in the future is the
+	// same failure with the sign flipped. Both are corruption, not a long session — so neither gets
+	// an anchor, by the same rule that governs the unparseable case above.
+	const elapsed = now - started;
+	if (elapsed < -CLOCK_SKEW_TOLERANCE_MS || elapsed > MAX_PLAUSIBLE_SESSION_AGE_MS) return undefined;
+	// Minute precision, UTC: unambiguous wherever the session is resumed, and constant — seconds
+	// would add churn to the one part of this line that is supposed to never change.
+	const absolute = `${new Date(started).toISOString().slice(0, 16)}Z`;
+	return (
+		`[pi-persona] Session clock — this session started ${absolute} and you have been on it ${sessionElapsedLabel(elapsed)}. ` +
+		"That is the whole life of THIS session, and it survives compaction and restarts; the reading is deliberately coarse, so pace yourself by it rather than measure with it."
+	);
+}

package/src/core/timer.ts

@@ -0,0 +1,221 @@
+/**
+ * `TimerScheduler` — the pure kernel behind the supervisor-armable `timer` tool.
+ *
+ * Problem it solves: a supervisor that must WAIT for a fixed wall-clock moment (a scheduled event,
+ * a service window, a scheduled re-check) has no cheap way to "sleep and resume". The
+ * MCP/transport layer caps a blocking tool call at ~20-60s, so a 50-minute wait degenerates into
+ * dozens of token-burning polls. The fix is an ALARM, not a sleep: arm a timer that, when it
+ * expires, WAKES the session by injecting a follow-up (the extension routes the fire through the
+ * same idle-delivery notifier that surfaces async-run completions — an idle delivery always starts
+ * a fresh turn, so the supervisor resumes on its own).
+ *
+ * This module is pure (injected clock + setTimer/clearTimer + an onFire sink), so scheduling,
+ * validation, cancellation and listing are unit-tested without a live model or real wall clock.
+ * The extension owns the side effects (the actual timer + the wake delivery).
+ */
+
+/** A scheduled wakeup. `message` is what gets injected into the session when it fires. */
+export interface TimerEntry {
+	id: string;
+	label: string;
+	/** Absolute wall-clock fire time (epoch ms). */
+	fireAtEpochMs: number;
+	/** When the timer was armed (epoch ms) — for the "armed Xs ago" view. */
+	armedAtEpochMs: number;
+	/** Receiver wall-clock observed when this fired. Present on the wake copy, absent while armed. */
+	observedAtEpochMs?: number;
+	/** The follow-up text delivered to the session on fire. */
+	message: string;
+}
+
+export interface TimerArmRequest {
+	/** Human label for the alarm (e.g. "status review"). Optional; defaults to the id. */
+	label?: string;
+	/** The follow-up injected into the session when the timer fires. Required, non-empty. */
+	message: string;
+	/** Fire after this many ms from now. Exactly one of delayMs / atEpochMs must be given. */
+	delayMs?: number;
+	/** Fire at this absolute epoch-ms. Exactly one of delayMs / atEpochMs must be given. */
+	atEpochMs?: number;
+}
+
+/** A read-only snapshot of an armed timer, with the live remaining time. */
+export interface TimerView {
+	id: string;
+	label: string;
+	fireAtEpochMs: number;
+	remainingMs: number;
+	message: string;
+}
+
+export interface TimerArmResult {
+	ok: boolean;
+	error?: string;
+	entry?: TimerEntry;
+	/** Delay measured by the scheduler's injected clock at arm time. */
+	remainingMs?: number;
+}
+
+export interface TimerSchedulerDeps {
+	/** Current wall-clock (epoch ms). Injected so tests control the clock. */
+	now: () => number;
+	/** Schedule a callback after `ms`; returns an opaque handle. */
+	setTimer: (fn: () => void, ms: number) => unknown;
+	/** Cancel a scheduled callback by its handle. */
+	clearTimer: (handle: unknown) => void;
+	/** Called exactly once when a timer expires (never for a cancelled one). */
+	onFire: (entry: TimerEntry) => void;
+	/** Minimum accepted delay (ms). Default 1000 — sub-second alarms are pointless here. */
+	minDelayMs?: number;
+	/** Maximum accepted delay (ms). Default 24h — guards against a runaway/typo alarm. */
+	maxDelayMs?: number;
+	/** Maximum simultaneously armed timers. Default 32 — the tool is model-callable, so a
+	 *  looping supervisor must not pin thousands of live OS timers. */
+	maxArmed?: number;
+	/** Maximum follow-up message length (chars). Default 4000 — the stored message is
+	 *  re-injected into context at fire time, so it is a budget, not a document. */
+	maxMessageChars?: number;
+}
+
+const DEFAULT_MIN_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 24 * 60 * 60 * 1_000;
+const DEFAULT_MAX_ARMED = 32;
+const DEFAULT_MAX_MESSAGE_CHARS = 4_000;
+
+interface Scheduled {
+	entry: TimerEntry;
+	handle: unknown;
+}
+
+export class TimerScheduler {
+	private readonly deps: TimerSchedulerDeps;
+	private readonly minDelayMs: number;
+	private readonly maxDelayMs: number;
+	private readonly maxArmed: number;
+	private readonly maxMessageChars: number;
+	private readonly timers = new Map<string, Scheduled>();
+	private seq = 0;
+
+	constructor(deps: TimerSchedulerDeps) {
+		this.deps = deps;
+		this.minDelayMs = deps.minDelayMs ?? DEFAULT_MIN_DELAY_MS;
+		this.maxDelayMs = deps.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+		this.maxArmed = deps.maxArmed ?? DEFAULT_MAX_ARMED;
+		this.maxMessageChars = deps.maxMessageChars ?? DEFAULT_MAX_MESSAGE_CHARS;
+	}
+
+	/** Arm a new alarm. Returns the entry on success, or a reason on rejection. */
+	arm(req: TimerArmRequest): TimerArmResult {
+		const message = (req.message ?? "").trim();
+		if (!message) return { ok: false, error: "timer needs a non-empty message (the follow-up injected when it fires)." };
+		if (message.length > this.maxMessageChars) {
+			return { ok: false, error: `timer message is too long (${message.length} chars; maximum ${this.maxMessageChars}). The follow-up is re-injected into context at fire time — keep it a pointer, not a document.` };
+		}
+		if (this.timers.size >= this.maxArmed) {
+			return { ok: false, error: `too many armed timers (${this.timers.size}; maximum ${this.maxArmed}). Cancel or let some fire before arming more.` };
+		}
+
+		const hasDelay = req.delayMs !== undefined;
+		const hasAt = req.atEpochMs !== undefined;
+		if (hasDelay === hasAt) {
+			return { ok: false, error: "timer needs exactly one of { delayMs } or { atEpochMs }." };
+		}
+
+		const now = this.deps.now();
+		if (!Number.isFinite(now)) return { ok: false, error: "timer clock is not a finite number." };
+		const fireAt = hasDelay ? now + (req.delayMs as number) : (req.atEpochMs as number);
+		if (!Number.isFinite(fireAt)) return { ok: false, error: "timer fire time is not a finite number." };
+
+		const delay = fireAt - now;
+		if (delay < this.minDelayMs) {
+			return { ok: false, error: `timer fires too soon (in ${delay}ms; minimum ${this.minDelayMs}ms). For an absolute time, check it is in the future.` };
+		}
+		if (delay > this.maxDelayMs) {
+			return { ok: false, error: `timer fires too far out (in ${delay}ms; maximum ${this.maxDelayMs}ms).` };
+		}
+
+		const id = `timer-${++this.seq}`;
+		const entry: TimerEntry = {
+			id,
+			label: (req.label ?? "").trim() || id,
+			fireAtEpochMs: fireAt,
+			armedAtEpochMs: now,
+			message,
+		};
+		const handle = this.deps.setTimer(() => this.fire(id), delay);
+		this.timers.set(id, { entry, handle });
+		return { ok: true, entry, remainingMs: delay };
+	}
+
+	/** Cancel an armed alarm by id. Returns false if unknown (already fired or never existed). */
+	cancel(id: string): boolean {
+		const scheduled = this.timers.get(id);
+		if (!scheduled) return false;
+		this.deps.clearTimer(scheduled.handle);
+		this.timers.delete(id);
+		return true;
+	}
+
+	/** Cancel every armed alarm (reload/dispose hygiene — never leak a timer across sessions). */
+	cancelAll(): void {
+		for (const scheduled of this.timers.values()) this.deps.clearTimer(scheduled.handle);
+		this.timers.clear();
+	}
+
+	/** Snapshot of all armed alarms, soonest first, with live remaining time. */
+	list(): TimerView[] {
+		const now = this.deps.now();
+		return [...this.timers.values()]
+			.map((s) => ({
+				id: s.entry.id,
+				label: s.entry.label,
+				fireAtEpochMs: s.entry.fireAtEpochMs,
+				remainingMs: Math.max(0, s.entry.fireAtEpochMs - now),
+				message: s.entry.message,
+			}))
+			.sort((a, b) => a.fireAtEpochMs - b.fireAtEpochMs);
+	}
+
+	/** Number of currently armed alarms. */
+	get size(): number {
+		return this.timers.size;
+	}
+
+	/** Current wall-clock reading from the scheduler's injected clock. */
+	now(): number {
+		return this.deps.now();
+	}
+
+	private fire(id: string): void {
+		const scheduled = this.timers.get(id);
+		if (!scheduled) return; // cancelled between expiry and callback — nothing to do
+		this.timers.delete(id);
+		const observedAtEpochMs = this.deps.now();
+		this.deps.onFire(Number.isFinite(observedAtEpochMs) ? { ...scheduled.entry, observedAtEpochMs } : scheduled.entry);
+	}
+}
+
+/** Render a fired-timer batch into one wake message for the supervisor. Exported for reuse + test. */
+export function renderTimerFire(entries: TimerEntry[]): string {
+	if (entries.length === 0) return "";
+	const head = `[pi-persona] ⏰ ${entries.length} timer${entries.length === 1 ? "" : "s"} fired — resuming:`;
+	const blocks = entries.map((e) => {
+		const due = new Date(e.fireAtEpochMs).toISOString();
+		const observed = Number.isFinite(e.observedAtEpochMs)
+			? `; observed ${new Date(e.observedAtEpochMs as number).toISOString()}`
+			: "";
+		return `• ${e.label} (${e.id}) — due ${due}${observed}: ${e.message}`;
+	});
+	return [head, ...blocks].join("\n");
+}
+
+/** Compact human-readable duration for the `list` view (e.g. "49m 12s", "1h 03m"). */
+export function formatRemaining(ms: number): string {
+	const s = Math.max(0, Math.round(ms / 1000));
+	const h = Math.floor(s / 3600);
+	const m = Math.floor((s % 3600) / 60);
+	const sec = s % 60;
+	if (h > 0) return `${h}h ${String(m).padStart(2, "0")}m`;
+	if (m > 0) return `${m}m ${String(sec).padStart(2, "0")}s`;
+	return `${sec}s`;
+}

package/src/core/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared primitive types and small validators used across pi-persona.
+ *
+ * Pure module — no Pi imports. Keep this to genuinely cross-cutting primitives;
+ * module-specific types live with their module.
+ */
+
+import type { Permission } from "./permissions.ts";
+
+export type { Permission };
+
+/** Pi reasoning/effort levels (mirrors `@earendil-works/pi-ai`'s `ThinkingLevel`). Keep in lockstep
+ *  with upstream: `max` was added in pi 0.80.6 (above `xhigh`). If pi's union widens again, add the
+ *  new level here too — `pi.getThinkingLevel()` returns the upstream union, so a missing member here
+ *  is a hard compile error where the host reads it (see `PersonaHost.getThinkingLevel`). */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export function isThinkingLevel(x: unknown): x is ThinkingLevel {
+	return typeof x === "string" && (THINKING_LEVELS as readonly string[]).includes(x);
+}
+
+/** How a persona/agent body combines with the base system prompt. */
+export type SystemPromptMode = "append" | "replace";
+
+export function asSystemPromptMode(x: unknown, fallback: SystemPromptMode): SystemPromptMode {
+	return x === "append" || x === "replace" ? x : fallback;
+}