@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/devspec-commit-ledger.ts

@@ -0,0 +1,477 @@
+/**
+ * DevSpec Pi — mechanical commit ledger + host-observed provenance.
+ *
+ * Direct commits are observed by the private session Git shim (item 2c971806).
+ * The older command/output recognizer remains as a conservative fallback. Neither
+ * path blocks Git, parses Bash policy, or grants authority. The shim tags a plain
+ * commit with the one claimed task's reference (item df71ab6c, owner-approved),
+ * and each commit's outcome is told to the model under the command's output.
+ */
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveToken, resolveEndpoint } from "./core/auth-store.ts";
+import { getBond } from "./core/bond-state.ts";
+import {
+	DevspecAuthError,
+	DevspecRateLimitError,
+	callDevspec,
+	isRecoverableTransportError,
+	type CallOptions,
+} from "./core/client.ts";
+import {
+	annotateCommitMessage,
+	captureGitCommit,
+	recordObservedCommit,
+	repoCommitMessage,
+	repoResolver,
+	type LedgerCommit,
+} from "./core/commit-ledger.ts";
+import { debugRemote } from "./core/debug.ts";
+import { unwrapMcpResult } from "./core/result.ts";
+import {
+	drainGitObservations,
+	initializeGitObserver,
+	prepareGitObservation,
+	shutdownGitObserver,
+	type FrozenGitObservationEnvelope,
+	type ObservedGitCommit,
+} from "./core/git-observer.ts";
+import { resolveGitRemote, resolveProjectPin, sanitizeGitRemoteForTransport } from "./core/project-scope.ts";
+import { commitStampNote, commitStampScope, type CommitStampDeps } from "./core/commit-stamp.ts";
+import { listObservedClaims } from "./core/work-state.ts";
+import { resolveNudgeProject } from "./devspec-provenance-assistance.ts";
+
+function commandOf(args: unknown): string {
+	const a = args as { command?: unknown } | null;
+	return typeof a?.command === "string" ? a.command : "";
+}
+
+function outputOf(result: unknown): string {
+	const r = result as { content?: Array<{ type?: string; text?: string }> } | null;
+	if (!r || !Array.isArray(r.content)) return "";
+	return r.content
+		.filter((p) => p && p.type === "text" && typeof p.text === "string")
+		.map((p) => p.text as string)
+		.join("\n");
+}
+
+const FULL_SHA = /^[0-9a-f]{40}$/u;
+const FULL_PROJECT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+const REPORT_QUEUE_KEY = "__devspecPiCommitReportQueue";
+const MAX_REPORTS = 100;
+const REPORT_TTL_MS = 24 * 60 * 60 * 1000;
+
+export interface FrozenCommitAttribution {
+	connectionId: string;
+	projectId: string;
+	/** Hidden transport capability frozen host-side; never exported to the shim. */
+	connectionCapability?: string;
+	observationId?: string;
+	/** Captured before Bash; hashes only, no bearer passed to child processes. */
+	transport?: { tokenHash: string; endpoint: string };
+	/** Captured once when the proved observation is enqueued, not on retry. */
+	repository?: { remote: string | null; pin: string | null };
+}
+
+interface ReporterDeps {
+	resolveToken(): Promise<{ token: string } | null>;
+	resolveEndpoint(): Promise<string>;
+	resolveGitRemote(cwd: string): Promise<string | null>;
+	resolveProjectPin(cwd: string): Promise<string | null>;
+	call(
+		token: string,
+		name: string,
+		args: Record<string, unknown>,
+		options?: CallOptions,
+	): Promise<unknown>;
+}
+
+const reporterDeps: ReporterDeps = {
+	resolveToken,
+	resolveEndpoint,
+	resolveGitRemote,
+	resolveProjectPin,
+	call: callDevspec,
+};
+
+export type CommitReportOutcome = "sent" | "permanent_rejection" | "transient_failure";
+
+export function commitTokenHash(token: string): string {
+	return createHash("sha256").update(token).digest("hex");
+}
+
+/** Capture host auth before execution. A later login cannot adopt its observations. */
+export async function captureCommitTransport(deps: ReporterDeps = reporterDeps): Promise<FrozenCommitAttribution["transport"] | null> {
+	try {
+		const [auth, endpoint] = await Promise.all([deps.resolveToken(), deps.resolveEndpoint()]);
+		if (!auth?.token || !endpoint) return null;
+		return Object.freeze({ tokenHash: commitTokenHash(auth.token), endpoint });
+	} catch { return null; }
+}
+
+/** Freeze actual observed-worktree scope once; no shell parsing or cwd guessing. */
+export async function captureCommitRepository(cwd: string, projectId: string, deps: ReporterDeps = reporterDeps): Promise<FrozenCommitAttribution["repository"] | null> {
+	try {
+		const [rawPin, rawRemote] = await Promise.all([deps.resolveProjectPin(cwd), deps.resolveGitRemote(cwd)]);
+		const remote = sanitizeGitRemoteForTransport(rawRemote);
+		if (rawRemote && !remote) return null;
+		if (rawPin && rawPin !== projectId) return null;
+		const pin = rawPin === projectId ? rawPin : null;
+		return remote || pin ? Object.freeze({ remote, pin }) : null;
+	} catch { return null; }
+}
+
+/** Report one mechanically proved commit using identity frozen before execution. */
+export async function reportCapturedCommit(
+	commit: LedgerCommit,
+	cwd: string,
+	attribution: FrozenCommitAttribution,
+	deps: ReporterDeps = reporterDeps,
+): Promise<CommitReportOutcome> {
+	if (!FULL_SHA.test(commit.sha) || !FULL_PROJECT_ID.test(attribution.connectionId) || !FULL_PROJECT_ID.test(attribution.projectId) ||
+		!attribution.connectionCapability || !attribution.transport || !attribution.repository) {
+		// Old reload-surviving entries cannot acquire today's missing binding.
+		return "permanent_rejection";
+	}
+	const resolved = await deps.resolveToken().catch(() => null);
+	if (!resolved?.token) return "transient_failure";
+	const endpoint = await deps.resolveEndpoint().catch(() => null);
+	if (!endpoint) return "transient_failure";
+	if (commitTokenHash(resolved.token) !== attribution.transport.tokenHash || endpoint !== attribution.transport.endpoint) return "permanent_rejection";
+
+	try {
+		const repository = await captureCommitRepository(cwd, attribution.projectId, deps);
+		if (!repository || repository.remote !== attribution.repository.remote || repository.pin !== attribution.repository.pin) return "permanent_rejection";
+		const { remote, pin } = attribution.repository;
+
+		const response = await deps.call(
+			resolved.token,
+			"report_commit_provenance",
+			{
+				connection_id: attribution.connectionId,
+				commit_sha: commit.sha,
+				branch: commit.branch,
+				...(attribution.observationId ? { observation_id: attribution.observationId } : {}),
+				...(remote ? { git_remote: remote } : {}),
+				...(!remote && pin ? { pinned_project_id: pin } : {}),
+			},
+			{
+				lane: "work",
+				timeoutMs: 10_000,
+				retry: "never",
+				endpoint: attribution.transport.endpoint,
+				connectionCapability: attribution.connectionCapability,
+			},
+		);
+		const result = unwrapMcpResult(response);
+		const details = result.details as { recorded?: unknown; conflict?: unknown } | null;
+		if (result.isError || details?.recorded === false || details?.conflict === true) return "permanent_rejection";
+		return details?.recorded === true ? "sent" : "transient_failure";
+	} catch (error) {
+		if (error instanceof DevspecRateLimitError || error instanceof DevspecAuthError || isRecoverableTransportError(error)) {
+			return "transient_failure";
+		}
+		return "permanent_rejection";
+	}
+}
+
+interface QueuedReport {
+	key: string;
+	commit: LedgerCommit;
+	cwd: string;
+	attribution: FrozenCommitAttribution;
+	createdAt: number;
+	attempts: number;
+	nextAttemptAt: number;
+}
+
+interface ReportQueueStore {
+	items: QueuedReport[];
+	flushing: Promise<void> | null;
+	retryTimer: ReturnType<typeof setTimeout> | null;
+}
+
+function reportQueue(): ReportQueueStore {
+	const g = globalThis as unknown as Record<string, ReportQueueStore | undefined>;
+	if (!g[REPORT_QUEUE_KEY]) g[REPORT_QUEUE_KEY] = { items: [], flushing: null, retryTimer: null };
+	return g[REPORT_QUEUE_KEY] as ReportQueueStore;
+}
+
+export function enqueueCommitReport(commit: LedgerCommit, cwd: string, attribution: FrozenCommitAttribution): void {
+	const queue = reportQueue();
+	const key = `${attribution.connectionId}:${commit.sha}`;
+	if (queue.items.some((item) => item.key === key)) return;
+	const now = Date.now();
+	queue.items.push({ key, commit: { ...commit }, cwd, attribution: {
+		...attribution,
+		...(attribution.transport ? { transport: Object.freeze({ ...attribution.transport }) } : {}),
+		...(attribution.repository ? { repository: Object.freeze({ ...attribution.repository }) } : {}),
+	}, createdAt: now, attempts: 0, nextAttemptAt: now });
+	if (queue.items.length > MAX_REPORTS) {
+		debugRemote("commit provenance delivery", { capacity: queue.items.length - MAX_REPORTS });
+		queue.items.splice(0, queue.items.length - MAX_REPORTS);
+	}
+}
+
+function scheduleCommitReportRetry(at: number): void {
+	const queue = reportQueue();
+	if (queue.retryTimer) clearTimeout(queue.retryTimer);
+	const delay = Math.max(0, at - Date.now());
+	queue.retryTimer = setTimeout(() => {
+		queue.retryTimer = null;
+		void flushCommitReports();
+	}, delay);
+	queue.retryTimer.unref?.();
+}
+
+export function cancelCommitReportRetryTimer(): void {
+	const queue = reportQueue();
+	if (queue.retryTimer) clearTimeout(queue.retryTimer);
+	queue.retryTimer = null;
+}
+
+export function resetCommitReportQueueForTests(): void {
+	const queue = reportQueue();
+	cancelCommitReportRetryTimer();
+	queue.items = [];
+	queue.flushing = null;
+}
+
+export function flushCommitReports(now = Date.now(), deps: ReporterDeps = reporterDeps): Promise<void> {
+	const queue = reportQueue();
+	if (queue.flushing) return queue.flushing;
+	queue.flushing = (async () => {
+		const priorCount = queue.items.length;
+		queue.items = queue.items.filter((item) => now - item.createdAt <= REPORT_TTL_MS && item.attempts < 5);
+		if (priorCount !== queue.items.length) debugRemote("commit provenance delivery", { expired: priorCount - queue.items.length });
+		for (const item of [...queue.items]) {
+			if (item.nextAttemptAt > now) {
+				scheduleCommitReportRetry(item.nextAttemptAt);
+				break;
+			}
+			item.attempts += 1;
+			const outcome = await reportCapturedCommit(item.commit, item.cwd, item.attribution, deps);
+			if (outcome === "sent" || outcome === "permanent_rejection") {
+				debugRemote("commit provenance delivery", { sent: outcome === "sent", dropped: outcome === "permanent_rejection" });
+				queue.items = queue.items.filter((candidate) => candidate.key !== item.key);
+				continue;
+			}
+			// One reload-safe scheduled retry; lifecycle bursts cannot consume attempts.
+			debugRemote("commit provenance delivery", { retry: item.attempts });
+			const backoff = Math.min(30_000, 1000 * (2 ** Math.max(0, item.attempts - 1)));
+			item.nextAttemptAt = Date.now() + backoff + Math.floor(Math.random() * 250);
+			scheduleCommitReportRetry(item.nextAttemptAt);
+			break;
+		}
+	})().finally(() => { queue.flushing = null; });
+	return queue.flushing;
+}
+
+function gitOutput(cwd: string, args: string[]): string | null {
+	try {
+		return execFileSync("git", args, {
+			cwd,
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 3000,
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+
+/** Independently corroborate child journal data from immutable Git state. */
+export function corroborateObservedCommit(observed: ObservedGitCommit, now = Date.now()): boolean {
+	const head = gitOutput(observed.worktree, ["rev-parse", "--verify", "HEAD^{commit}"])?.toLowerCase();
+	if (head !== observed.sha || observed.sha === observed.previousHead) return false;
+	const postLine = gitOutput(observed.worktree, ["rev-list", "--parents", "-n", "1", observed.sha]);
+	if (!postLine) return false;
+	const postParents = postLine.split(/\s+/u).slice(1);
+	if (observed.previousHead === null) {
+		if (observed.amend || postParents.length !== 0) return false;
+	} else if (observed.amend) {
+		const priorLine = gitOutput(observed.worktree, ["rev-list", "--parents", "-n", "1", observed.previousHead]);
+		if (!priorLine) return false;
+		const priorParents = priorLine.split(/\s+/u).slice(1);
+		if (postParents.length !== priorParents.length || postParents.some((parent, index) => parent !== priorParents[index])) return false;
+	} else if (postParents.length !== 1 || postParents[0] !== observed.previousHead) {
+		return false;
+	}
+	const reflog = gitOutput(observed.worktree, ["reflog", "show", "-2", "--format=%H%x09%gs%x09%ct", "HEAD"]);
+	if (!reflog) return false;
+	const entries = reflog.split("\n").filter(Boolean).map((line) => line.split("\t"));
+	const [reflogSha = "", action = "", reflogEpoch = ""] = entries[0] ?? [];
+	const priorReflogSha = entries[1]?.[0]?.toLowerCase() ?? null;
+	const expectedAction = observed.previousHead === null ? /^commit \(initial\):/u : observed.amend ? /^commit \(amend\):/u : /^commit:/u;
+	if (reflogSha.toLowerCase() !== observed.sha || !expectedAction.test(action)) return false;
+	if (observed.previousHead === null ? entries.length !== 1 : priorReflogSha !== observed.previousHead) return false;
+	const reflogMs = Number.parseInt(reflogEpoch, 10) * 1000;
+	const committedMs = Number.parseInt(gitOutput(observed.worktree, ["show", "-s", "--format=%ct", observed.sha]) ?? "", 10) * 1000;
+	const earliest = observed.envelope.createdAt - 2000;
+	return Number.isFinite(reflogMs) && Number.isFinite(committedMs) &&
+		reflogMs >= earliest && reflogMs <= now + 2000 && committedMs >= earliest && committedMs <= now + 2000;
+}
+
+const stampDeps: CommitStampDeps = {
+	claims: (sessionId) => listObservedClaims(sessionId),
+	originUrl: (cwd) => Promise.resolve(gitOutput(cwd, ["remote", "get-url", "origin"])),
+	resolveProject: (cwd) => resolveNudgeProject(cwd),
+};
+
+/** Lines for the model, per tool call, from the commits that call made (df71ab6c). */
+const STAMP_NOTES_KEY = "__devspecPiCommitStampNotes";
+function stampNotes(): Map<string, string[]> {
+	const g = globalThis as unknown as Record<string, Map<string, string[]> | undefined>;
+	if (!(g[STAMP_NOTES_KEY] instanceof Map)) g[STAMP_NOTES_KEY] = new Map();
+	return g[STAMP_NOTES_KEY] as Map<string, string[]>;
+}
+
+function noteStampOutcome(observed: ObservedGitCommit): void {
+	const note = commitStampNote(observed);
+	if (!note) return;
+	const notes = stampNotes();
+	notes.set(observed.envelope.toolCallId, [...(notes.get(observed.envelope.toolCallId) ?? []), note]);
+	while (notes.size > 50) {
+		const oldest = notes.keys().next().value;
+		if (!oldest) break;
+		notes.delete(oldest);
+	}
+}
+
+/** Take the lines for one tool call, once. */
+export function takeCommitStampNotes(toolCallId: string): string[] {
+	const notes = stampNotes();
+	const lines = notes.get(toolCallId) ?? [];
+	notes.delete(toolCallId);
+	return lines;
+}
+
+async function ledgerAndQueue(observed: ObservedGitCommit): Promise<void> {
+	if (!corroborateObservedCommit(observed)) return;
+	noteStampOutcome(observed);
+	const message = repoCommitMessage(observed.worktree, observed.sha);
+	const commit: LedgerCommit = {
+		sha: observed.sha,
+		shortSha: observed.sha.slice(0, 7),
+		branch: observed.branch ?? "HEAD",
+		at: Date.parse(observed.observedAt) || Date.now(),
+		...(message !== null ? { commitMessage: message } : {}),
+	};
+	recordObservedCommit(commit);
+	const repository = await captureCommitRepository(observed.worktree, observed.envelope.projectId);
+	if (!repository || !observed.envelope.transport || !observed.envelope.connectionCapability) return;
+	enqueueCommitReport(commit, observed.worktree, {
+		connectionId: observed.envelope.connectionId,
+		projectId: observed.envelope.projectId,
+		observationId: observed.envelope.observationId,
+		connectionCapability: observed.envelope.connectionCapability,
+		transport: observed.envelope.transport,
+		repository,
+	});
+	debugRemote("commit ledger captured");
+}
+
+export default function (pi: ExtensionAPI) {
+	const pending = new Map<string, {
+		command: string;
+		cwd: string;
+		attribution: FrozenCommitAttribution | null;
+		piSessionId: string;
+	}>();
+	const injectedOriginal = new Map<string, string>();
+
+	pi.on("session_start", (event, ctx) => {
+		initializeGitObserver(ctx.sessionManager.getSessionId(), event.reason === "reload");
+	});
+
+	pi.on("tool_execution_start", (event, ctx) => {
+		if (event.toolName !== "bash") return;
+		const bond = getBond();
+		pending.set(event.toolCallId, {
+			command: commandOf(event.args),
+			cwd: ctx.cwd,
+			attribution: bond?.projectId ? {
+				connectionId: bond.connectionId,
+				projectId: bond.projectId,
+				...(bond.connectionCapability ? { connectionCapability: bond.connectionCapability } : {}),
+			} : null,
+			piSessionId: ctx.sessionManager.getSessionId(),
+		});
+		while (pending.size > 50) {
+			const oldest = pending.keys().next().value;
+			if (!oldest) break;
+			pending.delete(oldest);
+		}
+	});
+
+	pi.on("tool_call", async (event) => {
+		if (event.toolName !== "bash") return;
+		const start = pending.get(event.toolCallId);
+		if (!start?.attribution?.connectionCapability || typeof event.input.command !== "string") return;
+		const transport = await captureCommitTransport();
+		const bond = getBond();
+		if (!transport || bond?.connectionId !== start.attribution.connectionId || bond?.projectId !== start.attribution.projectId ||
+			bond?.connectionCapability !== start.attribution.connectionCapability) return;
+		// Stamping is armed only while a task is claimed; a failure arms nothing.
+		const stamp = await commitStampScope({ sessionId: start.piSessionId, projectId: start.attribution.projectId, cwd: start.cwd }, stampDeps).catch(() => null);
+		const prepared = prepareGitObservation({
+			toolCallId: event.toolCallId,
+			piSessionId: start.piSessionId,
+			connectionId: start.attribution.connectionId,
+			projectId: start.attribution.projectId,
+			connectionCapability: start.attribution.connectionCapability,
+			transport,
+			stamp,
+		});
+		if (!prepared) return;
+		injectedOriginal.set(event.toolCallId, event.input.command);
+		event.input.command = `${prepared.prefix}${event.input.command}`;
+	});
+
+	pi.on("tool_result", async (event) => {
+		if (event.toolName !== "bash") return;
+		const original = injectedOriginal.get(event.toolCallId);
+		if (original) {
+			// Keep extension/tool-result observers on the model-authored command shape.
+			event.input.command = original;
+			injectedOriginal.delete(event.toolCallId);
+		}
+		for (const observed of drainGitObservations()) await ledgerAndQueue(observed);
+		void flushCommitReports();
+		// What happened to each commit's task tag, where the model reads the output.
+		const notes = takeCommitStampNotes(event.toolCallId);
+		if (notes.length > 0) return { content: [...event.content, { type: "text" as const, text: notes.join("\n") }] };
+		return undefined;
+	});
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		const start = pending.get(event.toolCallId);
+		pending.delete(event.toolCallId);
+		if (!start || event.isError) return;
+		// Conservative fallback for existing readable summary output.
+		const captured = captureGitCommit(start.command, outputOf(event.result), repoResolver(ctx.cwd));
+		if (!captured) return;
+		const message = repoCommitMessage(ctx.cwd, captured.sha);
+		if (message !== null) annotateCommitMessage(captured.sha, message);
+		// Legacy output parsing is ledger convenience only. It is not causal proof
+		// and must never emit plugin_observed provenance.
+		debugRemote("commit ledger captured");
+	});
+
+	pi.on("agent_settled", async () => {
+		for (const observed of drainGitObservations()) await ledgerAndQueue(observed);
+		void flushCommitReports();
+	});
+
+	pi.on("session_shutdown", async (event) => {
+		for (const observed of drainGitObservations()) await ledgerAndQueue(observed);
+		await Promise.race([
+			flushCommitReports(),
+			new Promise<void>((resolve) => setTimeout(resolve, 1500)),
+		]);
+		if (event.reason !== "reload") cancelCommitReportRetryTimer();
+		shutdownGitObserver(event.reason);
+	});
+}

package/extensions/devspec-context.ts

@@ -0,0 +1,146 @@
+/**
+ * DevSpec Pi — context injection (Phase 3).
+ *
+ * Appends the DevSpec workflow block to the system prompt on every turn via
+ * before_agent_start, but only when a DevSpec token resolves (logged-out
+ * sessions stay pristine). Local file read only — no network per turn.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveToken } from "./core/auth-store.ts";
+import { getBond } from "./core/bond-state.ts";
+import { buildDevspecInstructions } from "./core/instructions.ts";
+import { commitTaggingAvailable } from "./core/commit-stamp.ts";
+import { noteInjectedContext, noteStaticContextBudget } from "./core/context-budget.ts";
+import { REPOSITORY_CONTEXT_MESSAGE, repositorySnapshotNeeded } from "./core/repository-context.ts";
+import { INSTRUCTION_CONTEXT_MESSAGE, instructionContextMessage } from "./core/connection-context.ts";
+
+/** Extra block while this session is bonded as remote capacity. Exported for unit tests (byte-stability pins). */
+export function buildBondedInstructions(): string | null {
+	const bond = getBond();
+	if (!bond) return null;
+	// Identity is named, never discovered (item 9dcbd157): the room's title +
+	// id and the owner's name ride the bonded block, refreshed only on attach
+	// transitions (and the slow title-retry), so the prompt stays byte-stable
+	// between them — the prefix-cache rule is safe.
+	const where = bond.sessionId
+		? `, attached to session ${bond.sessionTitle ? `“${bond.sessionTitle}” ` : ""}(id ${bond.sessionId})`
+		: ", sessionless";
+	const lines = [
+		`You are bonded to DevSpec as remote capacity (${bond.codename ?? bond.connectionId})${where}.`,
+		// Single addressee rule (item 5987cc24): the sender of each command is who
+		// gets addressed by name — never a bond/session "owner" title, which
+		// collides whenever a shared session's participants differ from the
+		// connection owner. Static text, so the prefix-cache rule still holds.
+		`Address the sender of each command by name (the requester named on the turn); "the owner" is a structural role, not a way to talk about a person.`,
+		"Messages prefixed [DevSpec remote — message from ...] are server-authorized remote commands delivered via the bond. Owner authority and delegated project scope differ; mutable runtime policy is served at devspec://product/remote-ingress-contract, and any delegated scope instruction is delivered with its exact command turn.",
+		"Your conversational text is delivered to the DevSpec session mechanically — never call tools to post it yourself. For non-trivial work, begin with one concise user-facing sentence confirming what you understood and what you will do next before using tools; add another progress message only at a meaningful boundary (for example, delegating, starting a long check, or becoming blocked). Do not narrate individual tools. Finish with the canonical answer.",
+		"If you need the requester before you can finish, ask with manage_directed_question and stop. The server ends Working unless you pass keep_turn because you still have work.",
+	];
+	// Mutable rule text is a persisted tail snapshot, not a rewritten system prefix.
+	// Sender response style remains on its own per-command lane.
+	lines.push("Project and owner rules arrive in DevSpec instruction-context snapshots; use the latest snapshot under the served implementation contract's precedence.");
+	return lines.join("\n");
+}
+
+function serializedChars(value: unknown): number {
+	try {
+		return JSON.stringify(value)?.length ?? 0;
+	} catch {
+		return 0;
+	}
+}
+
+function contentChars(values: unknown): number {
+	if (!Array.isArray(values)) return 0;
+	return values.reduce((sum, value) => sum + serializedChars(value), 0);
+}
+
+export default function (pi: ExtensionAPI) {
+	// Independent of room attachment: sessionless agents need the same project facts.
+	// Pi persists returned custom messages, so resume/reload reuses an identical snapshot.
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const content = getBond()?.repositoryContext;
+		if (!content || !repositorySnapshotNeeded(ctx.sessionManager.getBranch(), content)) return;
+		return { message: { customType: REPOSITORY_CONTEXT_MESSAGE, content, display: false } };
+	});
+	pi.on("before_agent_start", async (_event, ctx) => {
+		const bond = getBond();
+		if (!bond) return;
+		const content = instructionContextMessage(bond);
+		if (!repositorySnapshotNeeded(ctx.sessionManager.getBranch(), content, INSTRUCTION_CONTEXT_MESSAGE)) return;
+		return { message: { customType: INSTRUCTION_CONTEXT_MESSAGE, content, display: false } };
+	});
+	// The room digest is a one-shot orientation message: injected once per
+	// session instance, the first turn after the pump's cold-start sync.
+	let digestInjected = false;
+	// The attach-time bond context (item 9dcbd157) is one-shot PER ATTACH —
+	// re-attaching to a different room must inject its block again, so track
+	// the injected block, not a boolean.
+	let injectedAttachContext: string | null = null;
+
+	// One-shot means once per branch, not once per process: after the conversation
+	// moves to a branch without them (the owner's Clear, item 6beb89c6, or /tree),
+	// the next turn adds them again.
+	pi.on("session_tree", (_event, ctx) => {
+		const branch = ctx.sessionManager.getBranch();
+		const holds = (customType: string) => branch.some((entry) =>
+			entry.type === "custom_message" && (entry as { customType?: string }).customType === customType);
+		if (!holds("devspec-attach-context")) injectedAttachContext = null;
+		if (!holds("devspec-room-orientation")) digestInjected = false;
+	});
+
+	pi.on("before_agent_start", async (event, _ctx) => {
+		const resolved = await resolveToken();
+		if (!resolved) return undefined;
+		// Stable for a bonded session; it changes only when the git stand-in or the bond does.
+		let prompt = `${event.systemPrompt}\n\n${buildDevspecInstructions({ commitTagging: commitTaggingAvailable() })}`;
+		const bonded = buildBondedInstructions();
+		if (bonded) prompt += `\n\n### DevSpec remote (bonded)\n${bonded}`;
+
+		const activeNames = new Set(pi.getActiveTools());
+		const activeTools = pi.getAllTools().filter((tool) => activeNames.has(tool.name));
+		const options = event.systemPromptOptions as { contextFiles?: unknown[]; skills?: unknown[] } | undefined;
+		noteStaticContextBudget({
+			systemPromptChars: prompt.length,
+			activeToolCount: activeTools.length,
+			activeToolDefinitionChars: serializedChars(activeTools.map((tool) => ({
+				name: tool.name,
+				description: tool.description,
+				parameters: tool.parameters,
+				promptGuidelines: tool.promptGuidelines,
+			}))),
+			contextFileCount: options?.contextFiles?.length ?? 0,
+			contextFileChars: contentChars(options?.contextFiles),
+			skillCount: options?.skills?.length ?? 0,
+			skillChars: contentChars(options?.skills),
+		});
+
+		const bond = getBond();
+		if (bond?.attachContext && bond.attachContext !== injectedAttachContext) {
+			injectedAttachContext = bond.attachContext;
+			noteInjectedContext("attach", bond.attachContext.length);
+			return {
+				systemPrompt: prompt,
+				message: {
+					customType: "devspec-attach-context",
+					content: bond.attachContext,
+					display: false,
+				},
+			};
+		}
+		if (bond?.roomDigest && !digestInjected) {
+			digestInjected = true;
+			noteInjectedContext("roomDigest", bond.roomDigest.length);
+			return {
+				systemPrompt: prompt,
+				message: {
+					customType: "devspec-room-orientation",
+					content: bond.roomDigest,
+					display: false,
+				},
+			};
+		}
+		return { systemPrompt: prompt };
+	});
+}