@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/room-unread.ts

@@ -0,0 +1,173 @@
+/**
+ * What this agent has and has not read in its room (item ce1ffca1; brief 4d258656,
+ * decision c4c6190f). Lives in the existing room copy, never a second store.
+ *
+ * Two bookmarks, kept apart on purpose:
+ * - "read": the exact message versions `read_room_context` handed to the model.
+ *   Only the reader writes it. A wake, a notice or the agent's own reply never do.
+ * - "presented": what a notice has TOLD the model exists. It decides whether a
+ *   mid-turn notice has anything new to say; it never marks anything read.
+ * The coverage checkpoint ("saved locally through here") is a third, separate fact.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readSync } from "node:fs";
+import type { DatabaseSync } from "node:sqlite";
+import { hasAssistantSpeech as hasVisibleText } from "./assistant-speech.ts";
+import type { StoredRoomRecord } from "./room-store.ts";
+
+/** Additive table: older caches simply have nothing read yet. */
+export const ROOM_MARKS_TABLE = "CREATE TABLE IF NOT EXISTS room_marks (kind TEXT NOT NULL, id TEXT NOT NULL, version TEXT NOT NULL, PRIMARY KEY (kind, id))";
+export type RoomMarkKind = "read" | "presented" | "own";
+export interface RoomMarks { read: Map<string, string>; presented: Set<string>; own: Set<string> }
+type Db = Pick<DatabaseSync, "prepare" | "exec">;
+
+/**
+ * Who "this agent" is. Exact ids come from Pi's own post receipts. The label
+ * covers rows posted before this attachment's copy existed (every attach starts
+ * a fresh copy); it is set only when the connection has a codename, because a
+ * bare tool name would also match every other Pi the owner runs.
+ */
+export interface RoomSelf { connectionId: string; ownIds: ReadonlySet<string>; label: string | null }
+export type RoomMessageChange = "new" | "updated";
+export interface RoomWaitingMessage {
+	message_id: string;
+	sequence: number;
+	created_at: string;
+	change: RoomMessageChange;
+	for_you: boolean;
+	author: string;
+	kind: string;
+	version: string;
+	/** Presentation identity: a growing unread bubble is one key; a change after a read is a new one. */
+	key: string;
+}
+export interface RoomUnreadSummary {
+	unread: number;
+	updated: number;
+	for_you: number;
+	oldest_unread_at: string | null;
+	by_author: Array<{ author: string; kind: string; messages: number }>;
+}
+export interface RoomUnreadState { self: RoomSelf; marks: RoomMarks; waiting: RoomWaitingMessage[] }
+
+/** The version a reader saw: what a person sees (text and attachments), never lifecycle state. */
+export function roomMessageVersion(r: Pick<StoredRoomRecord, "content" | "attachments">): string {
+	return createHash("sha256").update(JSON.stringify([r.content, r.attachments.map(a => [a.resource_id, a.filename, a.type])])).digest("hex").slice(0, 32);
+}
+
+export function isOwnRoomMessage(r: Pick<StoredRoomRecord, "message_id" | "actor">, self: RoomSelf): boolean {
+	if (self.ownIds.has(r.message_id)) return true;
+	if (r.actor.kind !== "agent" || !self.label) return false;
+	// The server labels an agent's posts "Tool · Codename (Owner)".
+	return r.actor.display_name === self.label || r.actor.display_name.startsWith(`${self.label} (`);
+}
+
+/**
+ * A real message is judged by what a person in the room sees. Text (or an
+ * attachment) from a person, another agent or the in-session AI counts whether
+ * final or still in progress; system lines (presence markers, notices), empty
+ * rows in any state, deleted rows and this agent's own rows never do.
+ */
+export function isRealRoomMessage(r: StoredRoomRecord, self: RoomSelf): boolean {
+	if (r.state === "deleted" || r.actor.kind === "system") return false;
+	if (isOwnRoomMessage(r, self)) return false;
+	return hasVisibleText(r.content) || r.attachments.length > 0;
+}
+
+/** Oldest first, in the room's stable total order. A changed read message is "updated", never unread again. */
+export function waitingRoomMessages(records: Iterable<StoredRoomRecord>, read: ReadonlyMap<string, string>, self: RoomSelf): RoomWaitingMessage[] {
+	const waiting: RoomWaitingMessage[] = [];
+	for (const r of records) {
+		if (!isRealRoomMessage(r, self)) continue;
+		const version = roomMessageVersion(r);
+		const seen = read.get(r.message_id);
+		if (seen === version) continue;
+		const change: RoomMessageChange = seen === undefined ? "new" : "updated";
+		waiting.push({
+			message_id: r.message_id, sequence: r.order.sequence, created_at: r.order.created_at, change,
+			for_you: r.addressee.kind === "connection" && r.addressee.connection_id === self.connectionId,
+			author: r.actor.display_name, kind: r.actor.kind, version,
+			key: change === "new" ? roomPresentedKey(r.message_id) : `updated:${r.message_id}:${seen}`,
+		});
+	}
+	return waiting.sort((a, b) => a.sequence - b.sequence);
+}
+
+/** A command Pi was woken with has been TOLD, so it never makes a notice fresh. It stays unread until read. */
+export function roomPresentedKey(messageId: string): string { return `new:${messageId.toLowerCase()}`; }
+
+/** The commands one delivery hands the model, by exact id: the queue item's list or bundle, and the primary. */
+export function deliveredCommandKeys(primaryMessageId: string | undefined, details: unknown): string[] {
+	const ids = new Set<string>();
+	if (primaryMessageId) ids.add(primaryMessageId.toLowerCase());
+	const d = details as { command_message_ids?: unknown; bundle?: { commands?: unknown } } | null | undefined;
+	const listed = Array.isArray(d?.command_message_ids) ? d.command_message_ids
+		: Array.isArray(d?.bundle?.commands) ? d.bundle.commands.map(c => (c as { id?: unknown } | null)?.id) : [];
+	for (const id of listed) if (typeof id === "string" && id) ids.add(id.toLowerCase());
+	return [...ids].map(roomPresentedKey);
+}
+
+/** Counts only. Author labels are participant-written data; callers encode them as JSON. */
+export function summarizeRoomUnread(waiting: readonly RoomWaitingMessage[]): RoomUnreadSummary {
+	const authors = new Map<string, { author: string; kind: string; messages: number }>();
+	for (const w of waiting) {
+		const author = w.author; const k = JSON.stringify([w.kind, author]);
+		const entry = authors.get(k) ?? { author, kind: w.kind, messages: 0 };
+		entry.messages++; authors.set(k, entry);
+	}
+	return {
+		unread: waiting.filter(w => w.change === "new").length,
+		updated: waiting.filter(w => w.change === "updated").length,
+		for_you: waiting.filter(w => w.for_you).length,
+		oldest_unread_at: waiting.find(w => w.change === "new")?.created_at ?? null,
+		by_author: [...authors.values()].sort((a, b) => b.messages - a.messages || a.author.localeCompare(b.author)),
+	};
+}
+
+/** Something waiting that no notice has told the model about yet. */
+export function hasUnpresented(state: Pick<RoomUnreadState, "waiting" | "marks">): boolean {
+	return state.waiting.some(w => !state.marks.presented.has(w.key));
+}
+
+export function readRoomMarks(db: Db): RoomMarks {
+	const marks: RoomMarks = { read: new Map(), presented: new Set(), own: new Set() };
+	if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='room_marks'").get()) return marks;
+	for (const row of db.prepare("SELECT kind, id, version FROM room_marks").all()) {
+		const id = String(row.id);
+		if (row.kind === "read") marks.read.set(id, String(row.version));
+		else if (row.kind === "presented") marks.presented.add(id);
+		else if (row.kind === "own") marks.own.add(id);
+	}
+	return marks;
+}
+
+/** Caller owns the transaction. A read mark records the version handed over, replacing an older one. */
+export function writeRoomMarks(db: Db, kind: RoomMarkKind, entries: ReadonlyArray<readonly [string, string]>): void {
+	const upsert = db.prepare("INSERT INTO room_marks VALUES (?,?,?) ON CONFLICT(kind, id) DO UPDATE SET version=excluded.version");
+	for (const [id, version] of entries) upsert.run(kind, id, version);
+}
+
+/** One full pass over the saved copy. Callers cache it by the file change counter. */
+export function loadRoomUnread(db: Db, connectionId: string): RoomUnreadState {
+	const marks = readRoomMarks(db);
+	const row = db.prepare("SELECT value FROM meta WHERE key='self_label'").get();
+	const selfLabel = row ? JSON.parse(String(row.value)) as unknown : null;
+	const self: RoomSelf = { connectionId: connectionId.toLowerCase(), ownIds: marks.own, label: typeof selfLabel === "string" && selfLabel ? selfLabel : null };
+	const records = db.prepare("SELECT body FROM messages WHERE state<>'deleted' ORDER BY sequence").all().map(r => JSON.parse(String(r.body)) as StoredRoomRecord);
+	return { self, marks, waiting: waitingRoomMessages(records, marks.read, self) };
+}
+
+/**
+ * SQLite's file change counter (header bytes 24-27) moves on every committed
+ * write in rollback-journal mode, which the room copy uses. Reading it is the
+ * cheap "has the local copy changed?" check on Pi's per-tool-call path.
+ */
+export function roomFileChangeCounter(path: string): number | null {
+	let fd: number | undefined;
+	try {
+		fd = openSync(path, "r");
+		const header = Buffer.alloc(4);
+		return readSync(fd, header, 0, 4, 24) === 4 ? header.readUInt32BE(0) : null;
+	} catch { return null; }
+	finally { if (fd !== undefined) closeSync(fd); }
+}

package/extensions/core/session-events.ts

@@ -0,0 +1,62 @@
+/** Historical record events, never current state or command authority (81a0cccd). */
+import { advertisesRoomContext } from "./room-context.ts";
+
+type Actor = { kind: "agent" | "person" | "platform"; label: string };
+type Base = { id: string; at: string; kind: "task" | "memory" | "artifact"; record_id: string };
+export type SessionEvent = Base & (
+	| { event: "produced" | "retracted" | "archived"; actor: Actor | null }
+	| { event: "referenced"; message_id: string }
+	| { event: "lifecycle_changed"; from: string; to: string }
+	| { event: "superseded"; by: string | null; actor: Actor | null }
+);
+export interface SessionEvents {
+	version: 1; advisory: true; status: "available" | "unchanged" | "unavailable";
+	as_of: string; revision: string | null; events: SessionEvent[]; truncated: boolean;
+}
+function bad(): never { throw new Error("invalid session events"); }
+function object(x: unknown): Record<string, unknown> { if (!x || typeof x !== "object" || Array.isArray(x)) bad(); return x as Record<string, unknown>; }
+function text(x: unknown): string { if (typeof x !== "string" || !x) bad(); return x; }
+function uuid(x: unknown): string { const s = text(x); if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(s)) bad(); return s; }
+function date(x: unknown): string { const s = text(x); if (!/^\d{4}-\d\d-\d\dT.*(?:Z|[+-]\d\d:\d\d)$/.test(s) || !Number.isFinite(Date.parse(s))) bad(); return s; }
+function actor(x: unknown): Actor | null {
+	if (x === null) return null;
+	const a = object(x); if (a.kind !== "agent" && a.kind !== "person" && a.kind !== "platform") bad();
+	return { kind: a.kind, label: text(a.label) };
+}
+export function advertisesSessionEvents(resource: unknown): boolean {
+	try {
+		for (const item of object(resource).contents as unknown[]) {
+			if (!advertisesRoomContext({ contents: [item] })) continue;
+			const c = object(JSON.parse(text(object(item).text))); const a = object(c.activation);
+			const r = object(a.session_events_requires);
+			if (c.kind === "devspec.product.remote_ingress_contract" && a.session_events_negotiation_argument === "session_events_version" && a.session_events_revision_argument === "session_events_revision" && r.room_context_version === 1 && r.session_events_version === 1) return true;
+		}
+	} catch { /* Older advertisement: keep the existing room lane. */ }
+	return false;
+}
+/** Ignore additive fields; an unknown variant rejects only this advisory section. */
+export function parseSessionEvents(value: unknown): SessionEvents {
+	const s = object(value);
+	if (s.version !== 1 || s.advisory !== true || !["available", "unchanged", "unavailable"].includes(String(s.status)) || typeof s.truncated !== "boolean" || !Array.isArray(s.events) || s.events.length > 2000) bad();
+	const revision = s.revision === null ? null : text(s.revision);
+	if (revision !== null && !/^sha256:[a-f0-9]{64}$/.test(revision)) bad();
+	if (s.status === "unavailable" ? revision !== null || s.events.length > 0 || s.truncated : revision === null) bad();
+	if (s.status === "unchanged" && s.events.length) bad();
+	const seen = new Set<string>();
+	const events = s.events.map((value): SessionEvent => {
+		const e = object(value); const id = text(e.id);
+		if (id.length > 200 || seen.has(id)) bad(); seen.add(id);
+		if (e.kind !== "task" && e.kind !== "memory" && e.kind !== "artifact") bad();
+		const base: Base = { id, at: date(e.at), kind: e.kind, record_id: uuid(e.record_id) };
+		switch (e.event) {
+			case "produced": case "retracted": case "archived": return { ...base, event: e.event, actor: actor(e.actor) };
+			case "referenced": return { ...base, event: e.event, message_id: uuid(e.message_id) };
+			case "lifecycle_changed":
+				if (e.kind !== "task") bad();
+				return { ...base, event: e.event, from: text(e.from), to: text(e.to) };
+			case "superseded": return { ...base, event: e.event, by: e.by === null ? null : uuid(e.by), actor: actor(e.actor) };
+			default: return bad();
+		}
+	});
+	return { version: 1, advisory: true, status: s.status as SessionEvents["status"], as_of: date(s.as_of), revision, events, truncated: s.truncated };
+}

package/extensions/core/session-polls.ts

@@ -0,0 +1,292 @@
+/**
+ * Strict top-level session_polls projection on changed poll_connection packages
+ * (item 66bd18f6 / 852eab6b). Presence is advisory read-awareness only.
+ */
+
+export const SESSION_POLL_PROJECTION_VERSION = 1 as const;
+/**
+ * Version 2 (item bba35976) is never missing while the session has polls: the newest
+ * that fit the text budget, the totals, and a continuation naming where the rest
+ * are. Version 1 refused outright past 16 active polls, so a busy room arrived as
+ * no polls at all.
+ */
+export const SESSION_POLL_PROJECTION_VERSION_2 = 2 as const;
+export const SESSION_POLL_CONTINUATION = "Call manage_poll list to read every poll in this session." as const;
+export const SESSION_POLL_MAX_ACTIVE = 16;
+export const SESSION_POLL_MAX_ENDED = 5;
+export const SESSION_POLL_MAX_OPTIONS = 30;
+export const SESSION_POLL_MAX_QUESTION_CHARS = 400;
+export const SESSION_POLL_MAX_LABEL_CHARS = 80;
+export const SESSION_POLL_MAX_VOTER_CHARS = 80;
+export const SESSION_POLL_MAX_TOTAL_TEXT_CHARS = 16_384;
+export const SESSION_POLL_AUTHORITY_NOTE =
+	"Advisory read-awareness only. Presence does not authorize execution or mutation; manage_poll still requires a capability-authenticated caller identity and expected_revision. Votes are not commands and do not keep Working on." as const;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export interface SessionPollOptionProjection {
+	label: string;
+	human_vote_count: number;
+	percent: number;
+	voters: string[];
+}
+
+export interface SessionPollProjection {
+	id: string;
+	question: string;
+	status: "active" | "ended";
+	revision: number;
+	multi_select: boolean;
+	allow_write_in: boolean;
+	recommendation: string | null;
+	human_voter_count: number;
+	winning_labels: string[];
+	options: SessionPollOptionProjection[];
+}
+
+export interface SessionPollsProjectionV1 {
+	version: typeof SESSION_POLL_PROJECTION_VERSION;
+	advisory: true;
+	authority_note: typeof SESSION_POLL_AUTHORITY_NOTE;
+	inventory: {
+		active_returned: number;
+		ended_returned: number;
+		truncated_ended: boolean;
+	};
+	polls: SessionPollProjection[];
+}
+
+export interface SessionPollsProjectionV2 {
+	version: typeof SESSION_POLL_PROJECTION_VERSION_2;
+	advisory: true;
+	authority_note: typeof SESSION_POLL_AUTHORITY_NOTE;
+	inventory: {
+		active_total: number;
+		active_returned: number;
+		truncated_active: boolean;
+		ended_total: number;
+		ended_returned: number;
+		truncated_ended: boolean;
+		continuation: typeof SESSION_POLL_CONTINUATION | null;
+	};
+	polls: SessionPollProjection[];
+}
+
+export type SessionPollsProjection = SessionPollsProjectionV1 | SessionPollsProjectionV2;
+
+type Row = Record<string, unknown>;
+
+function fail(path: string, message: string): never {
+	throw new Error(`${path}: ${message}`);
+}
+
+function record(value: unknown, path: string): Row {
+	if (!value || typeof value !== "object" || Array.isArray(value)) fail(path, "expected object");
+	return value as Row;
+}
+
+function exactKeys(value: Row, keys: readonly string[], path: string): void {
+	const actual = Object.keys(value).sort();
+	const expected = [...keys].sort();
+	if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
+		fail(path, `expected exactly ${expected.join(", ")}`);
+	}
+}
+
+function boundedString(value: unknown, path: string, max: number): string {
+	if (typeof value !== "string" || value.length === 0 || value.length > max) {
+		fail(path, `expected non-empty string <= ${max} characters`);
+	}
+	return value;
+}
+
+function uuid(value: unknown, path: string): string {
+	const parsed = boundedString(value, path, 64);
+	if (!UUID_RE.test(parsed)) fail(path, "expected UUID");
+	return parsed;
+}
+
+function integer(value: unknown, path: string, minimum = 0, maximum = Number.MAX_SAFE_INTEGER): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+		fail(path, `expected integer ${minimum}..${maximum}`);
+	}
+	return value;
+}
+
+function boolean(value: unknown, path: string): boolean {
+	if (typeof value !== "boolean") fail(path, "expected boolean");
+	return value;
+}
+
+function option(value: unknown, path: string): SessionPollOptionProjection {
+	const row = record(value, path);
+	exactKeys(row, ["label", "human_vote_count", "percent", "voters"], path);
+	if (!Array.isArray(row.voters) || row.voters.length > 32) fail(`${path}.voters`, "expected <= 32 voter names");
+	return {
+		label: boundedString(row.label, `${path}.label`, SESSION_POLL_MAX_LABEL_CHARS),
+		human_vote_count: integer(row.human_vote_count, `${path}.human_vote_count`),
+		percent: integer(row.percent, `${path}.percent`, 0, 100),
+		voters: row.voters.map((name, index) => boundedString(name, `${path}.voters[${index}]`, SESSION_POLL_MAX_VOTER_CHARS)),
+	};
+}
+
+function poll(value: unknown, path: string): SessionPollProjection {
+	const row = record(value, path);
+	exactKeys(row, [
+		"id", "question", "status", "revision", "multi_select", "allow_write_in",
+		"recommendation", "human_voter_count", "winning_labels", "options",
+	], path);
+	if (row.status !== "active" && row.status !== "ended") fail(`${path}.status`, "expected active or ended");
+	if (!Array.isArray(row.winning_labels) || row.winning_labels.length > SESSION_POLL_MAX_OPTIONS) {
+		fail(`${path}.winning_labels`, `expected <= ${SESSION_POLL_MAX_OPTIONS} labels`);
+	}
+	if (!Array.isArray(row.options) || row.options.length < 2 || row.options.length > SESSION_POLL_MAX_OPTIONS) {
+		fail(`${path}.options`, `expected 2..${SESSION_POLL_MAX_OPTIONS} options`);
+	}
+	const recommendation = row.recommendation === null
+		? null
+		: boundedString(row.recommendation, `${path}.recommendation`, SESSION_POLL_MAX_LABEL_CHARS);
+	return {
+		id: uuid(row.id, `${path}.id`),
+		question: boundedString(row.question, `${path}.question`, SESSION_POLL_MAX_QUESTION_CHARS),
+		status: row.status,
+		revision: integer(row.revision, `${path}.revision`, 1),
+		multi_select: boolean(row.multi_select, `${path}.multi_select`),
+		allow_write_in: boolean(row.allow_write_in, `${path}.allow_write_in`),
+		recommendation,
+		human_voter_count: integer(row.human_voter_count, `${path}.human_voter_count`),
+		winning_labels: row.winning_labels.map((label, index) =>
+			boundedString(label, `${path}.winning_labels[${index}]`, SESSION_POLL_MAX_LABEL_CHARS)),
+		options: row.options.map((entry, index) => option(entry, `${path}.options[${index}]`)),
+	};
+}
+
+function pollTextChars(polls: readonly SessionPollProjection[]): number {
+	return polls.reduce((sum, item) => sum +
+		item.question.length +
+		(item.recommendation?.length ?? 0) +
+		item.winning_labels.reduce((n, label) => n + label.length, 0) +
+		item.options.reduce((n, option) => n + option.label.length + option.voters.reduce((v, name) => v + name.length, 0), 0), 0);
+}
+
+/** Parse a complete strict v1 or v2 inventory or throw without producing a partial projection. */
+export function parseSessionPollsProjection(value: unknown, path = "session_polls"): SessionPollsProjection {
+	const row = record(value, path);
+	exactKeys(row, ["version", "advisory", "authority_note", "inventory", "polls"], path);
+	if (row.version !== SESSION_POLL_PROJECTION_VERSION && row.version !== SESSION_POLL_PROJECTION_VERSION_2) {
+		fail(`${path}.version`, "unknown projection version");
+	}
+	if (row.advisory !== true) fail(`${path}.advisory`, "projection must be advisory");
+	if (row.authority_note !== SESSION_POLL_AUTHORITY_NOTE) fail(`${path}.authority_note`, "unknown authority note");
+	if (row.version === SESSION_POLL_PROJECTION_VERSION_2) return parseV2(row, path);
+	const inventory = record(row.inventory, `${path}.inventory`);
+	exactKeys(inventory, ["active_returned", "ended_returned", "truncated_ended"], `${path}.inventory`);
+	const maxPolls = SESSION_POLL_MAX_ACTIVE + SESSION_POLL_MAX_ENDED;
+	if (!Array.isArray(row.polls) || row.polls.length < 1 || row.polls.length > maxPolls) {
+		fail(`${path}.polls`, `expected 1..${maxPolls} polls`);
+	}
+	const polls = row.polls.map((entry, index) => poll(entry, `${path}.polls[${index}]`));
+	const activeReturned = integer(inventory.active_returned, `${path}.inventory.active_returned`, 0, SESSION_POLL_MAX_ACTIVE);
+	const endedReturned = integer(inventory.ended_returned, `${path}.inventory.ended_returned`, 0, SESSION_POLL_MAX_ENDED);
+	const truncatedEnded = boolean(inventory.truncated_ended, `${path}.inventory.truncated_ended`);
+	const active = polls.filter((item) => item.status === "active").length;
+	const ended = polls.filter((item) => item.status === "ended").length;
+	if (active !== activeReturned || ended !== endedReturned) fail(`${path}.inventory`, "inventory must match compact polls");
+	if (pollTextChars(polls) > SESSION_POLL_MAX_TOTAL_TEXT_CHARS) fail(`${path}.polls`, "poll projection text exceeds safe bound");
+	return {
+		version: SESSION_POLL_PROJECTION_VERSION,
+		advisory: true,
+		authority_note: SESSION_POLL_AUTHORITY_NOTE,
+		inventory: {
+			active_returned: activeReturned,
+			ended_returned: endedReturned,
+			truncated_ended: truncatedEnded,
+		},
+		polls,
+	};
+}
+
+/**
+ * v2's counts must tell the truth about what was left out: truncated exactly when
+ * fewer were returned than exist, and the continuation exactly when anything was,
+ * so a partial list can never pass for a complete one.
+ */
+function parseV2(row: Row, path: string): SessionPollsProjectionV2 {
+	const inventory = record(row.inventory, `${path}.inventory`);
+	exactKeys(inventory, [
+		"active_total", "active_returned", "truncated_active",
+		"ended_total", "ended_returned", "truncated_ended", "continuation",
+	], `${path}.inventory`);
+	if (!Array.isArray(row.polls)) fail(`${path}.polls`, "expected an array");
+	const polls = row.polls.map((entry, index) => poll(entry, `${path}.polls[${index}]`));
+	if (new Set(polls.map((item) => item.id)).size !== polls.length) fail(`${path}.polls`, "duplicate poll id");
+	const activeTotal = integer(inventory.active_total, `${path}.inventory.active_total`);
+	const activeReturned = integer(inventory.active_returned, `${path}.inventory.active_returned`, 0, activeTotal);
+	const endedTotal = integer(inventory.ended_total, `${path}.inventory.ended_total`);
+	const endedReturned = integer(inventory.ended_returned, `${path}.inventory.ended_returned`, 0, Math.min(endedTotal, SESSION_POLL_MAX_ENDED));
+	const truncatedActive = boolean(inventory.truncated_active, `${path}.inventory.truncated_active`);
+	const truncatedEnded = boolean(inventory.truncated_ended, `${path}.inventory.truncated_ended`);
+	if (activeTotal + endedTotal === 0) fail(`${path}.inventory`, "an inventory with no polls is omitted, not sent");
+	if (truncatedActive !== activeReturned < activeTotal || truncatedEnded !== endedReturned < endedTotal) {
+		fail(`${path}.inventory`, "truncation flags must match the totals");
+	}
+	const continuation = (truncatedActive || truncatedEnded) ? SESSION_POLL_CONTINUATION : null;
+	if (inventory.continuation !== continuation) fail(`${path}.inventory.continuation`, "continuation must be present exactly when polls were left out");
+	const active = polls.filter((item) => item.status === "active").length;
+	const ended = polls.filter((item) => item.status === "ended").length;
+	if (active !== activeReturned || ended !== endedReturned) fail(`${path}.inventory`, "inventory must match compact polls");
+	if (pollTextChars(polls) > SESSION_POLL_MAX_TOTAL_TEXT_CHARS) fail(`${path}.polls`, "poll projection text exceeds safe bound");
+	return {
+		version: SESSION_POLL_PROJECTION_VERSION_2,
+		advisory: true,
+		authority_note: SESSION_POLL_AUTHORITY_NOTE,
+		inventory: {
+			active_total: activeTotal,
+			active_returned: activeReturned,
+			truncated_active: truncatedActive,
+			ended_total: endedTotal,
+			ended_returned: endedReturned,
+			truncated_ended: truncatedEnded,
+			continuation,
+		},
+		polls,
+	};
+}
+
+/** Compact deterministic delivery-tail serialization. Votes are never commands. */
+export function serializeSessionPollsProjection(projection: SessionPollsProjection | null): string {
+	if (!projection) return "";
+	if (projection.version === SESSION_POLL_PROJECTION_VERSION_2) return serializeV2(projection);
+	if (projection.polls.length === 0) return "";
+	const lines = ["== SESSION POLLS ==", projection.authority_note];
+	for (const item of projection.polls) lines.push(...pollLines(item));
+	if (projection.inventory.truncated_ended) {
+		lines.push("Ended history is newest-first and bounded; call manage_poll list for the rest.");
+	}
+	return lines.join("\n");
+}
+
+/** The same text the server gives its own model for v2 (item 66bd18f6: one reducer). */
+function serializeV2(projection: SessionPollsProjectionV2): string {
+	const inv = projection.inventory;
+	const lines = ["== SESSION POLLS ==", projection.authority_note];
+	for (const item of projection.polls) lines.push(...pollLines(item));
+	if (inv.truncated_active) lines.push(`Showing the ${inv.active_returned} newest of ${inv.active_total} active polls.`);
+	if (inv.truncated_ended) lines.push(`Showing the ${inv.ended_returned} most recently ended of ${inv.ended_total} ended polls.`);
+	if (inv.continuation) lines.push(inv.continuation);
+	return lines.join("\n");
+}
+
+function pollLines(item: SessionPollProjection): string[] {
+	const optionText = item.options
+		.map((option) => `${option.label}: ${option.human_vote_count}${option.voters.length ? ` (${option.voters.join(", ")})` : ""}`)
+		.join("; ");
+	const rec = item.recommendation ? ` | recommendation=${item.recommendation}` : "";
+	const winners = item.status === "ended" && item.winning_labels.length > 0
+		? ` | ${item.winning_labels.length > 1 ? "tied" : "winner"}=${item.winning_labels.join(", ")}`
+		: "";
+	return [
+		`- "${item.question}" | poll_id=${item.id} | revision=${item.revision} | ${item.status}${item.multi_select ? " | multi-select" : ""}${item.allow_write_in ? " | write-in" : ""} | voters=${item.human_voter_count}${rec}${winners}`,
+		`  ${optionText}`,
+	];
+}

package/extensions/core/settings.ts

@@ -0,0 +1,39 @@
+/**
+ * DevSpec Pi — package settings (persisted at <pi-agent-dir>/devspec/settings.json).
+ *
+ * autoBond (default true): interactive sessions bond as DevSpec capacity on
+ * launch — the zero-command behavior (VISION.md principle 6). Headless modes
+ * never auto-bond regardless; scripts and one-shot runs stay explicit.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { devspecDir } from "./config.ts";
+
+export interface DevspecSettings {
+	autoBond: boolean;
+	/** Owner messages abort a running turn (item f5bbc8f8). Default on. */
+	preemptOwner: boolean;
+}
+
+const DEFAULTS: DevspecSettings = { autoBond: true, preemptOwner: true };
+
+function settingsPath(): string {
+	return join(devspecDir(), "settings.json");
+}
+
+export async function loadSettings(): Promise<DevspecSettings> {
+	try {
+		const raw = JSON.parse(await readFile(settingsPath(), "utf8")) as Partial<DevspecSettings>;
+		return { ...DEFAULTS, ...raw };
+	} catch {
+		return { ...DEFAULTS };
+	}
+}
+
+export async function saveSettings(patch: Partial<DevspecSettings>): Promise<DevspecSettings> {
+	const next = { ...(await loadSettings()), ...patch };
+	await mkdir(devspecDir(), { recursive: true, mode: 0o700 });
+	await writeFile(settingsPath(), `${JSON.stringify(next, null, 2)}\n`);
+	return next;
+}