@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/dispatch.ts

@@ -0,0 +1,108 @@
+/**
+ * DevSpec Pi — owner-scoped automation-run envelopes (pure, unit-tested).
+ *
+ * `poll_connection.dispatches[]` and `get_connection_dispatch` are transport
+ * names retained by the server API. Their only executable payload in Pi is a
+ * typed automation run. Task work is selected and reserved locally; it
+ * never enters this path.
+ */
+
+import { AUTOMATION_RUN_PREFIX } from "./turn-lifecycle.ts";
+
+const WAKE_KEYS = [
+	"id",
+	"kind",
+	"run_id",
+	"automation_id",
+	"automation_name",
+	"trigger_kind",
+	"owner",
+	"permission",
+	"queued_at",
+	"delivery_connection_id",
+	"requester",
+] as const;
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+function text(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function isOwner(value: unknown): value is { user_id: string; display_name: string } {
+	const owner = asRecord(value);
+	return Boolean(
+		owner &&
+		Object.keys(owner).length === 2 &&
+		text(owner.user_id) &&
+		text(owner.display_name),
+	);
+}
+
+/** Only this typed envelope may enter the remote automation queue. */
+export function isAutomationRunEnvelope(value: unknown): boolean {
+	const root = asRecord(value);
+	if (!root) return false;
+	if (Object.keys(root).length !== WAKE_KEYS.length || WAKE_KEYS.some((key) => !Object.hasOwn(root, key))) {
+		return false;
+	}
+	const pressed = root.trigger_kind === "pressed";
+	const requesterOk = pressed
+		? Boolean(asRecord(root.requester) && text(asRecord(root.requester)?.user_id))
+		: root.requester === null;
+	return root.kind === "automation_run" &&
+		Boolean(text(root.id)) &&
+		root.run_id === root.id &&
+		Boolean(text(root.automation_id)) &&
+		Boolean(text(root.automation_name)) &&
+		(root.trigger_kind === "scheduled" || root.trigger_kind === "event" || root.trigger_kind === "pressed") &&
+		isOwner(root.owner) &&
+		(root.permission === "look_only" || root.permission === "can_commit" || root.permission === "can_push") &&
+		Boolean(text(root.queued_at)) &&
+		Boolean(text(root.delivery_connection_id)) &&
+		requesterOk;
+}
+
+/** Exact server-owned retry identity for a typed automation run. */
+export function automationRunId(value: unknown): string | undefined {
+	if (!isAutomationRunEnvelope(value)) return undefined;
+	const root = asRecord(value);
+	return text(root?.run_id) ?? text(root?.id);
+}
+
+export function formatAutomationRunMessage(value: unknown, codename: string): string {
+	const runId = automationRunId(value);
+	if (!runId) throw new Error("automation run envelope requires a run id");
+	const root = asRecord(value) ?? {};
+	const name = text(root.automation_name) ?? "automation";
+	const ownerName = isOwner(root.owner) ? root.owner.display_name : "the owner";
+	const started =
+		root.trigger_kind === "pressed"
+			? "Someone pressed Run."
+			: root.trigger_kind === "scheduled"
+				? "This run started on a schedule."
+				: "This run started because of an event.";
+	const permission =
+		root.permission === "can_push"
+			? "You MAY edit, commit and push."
+			: root.permission === "can_commit"
+				? "You MAY edit and commit locally, but MUST NOT push."
+				: "This automation is LOOK ONLY — investigate and report; do not edit, commit or push.";
+	return [
+		`${AUTOMATION_RUN_PREFIX} to ${codename}]`,
+		`DevSpec automation run ${runId} (${name}) is ready.`,
+		started,
+		`Owner: ${ownerName}`,
+		`Permission: ${permission}`,
+		"Claim it with claim_automation_run to receive the instruction, then record_automation_run truthfully.",
+		"",
+		"Automation run envelope:",
+		"```json",
+		JSON.stringify(value, null, 2),
+		"```",
+	].join("\n");
+}

package/extensions/core/duck.ts

@@ -0,0 +1,128 @@
+/**
+ * DevSpec Pi — the DevSpec mark, drawn for a terminal.
+ *
+ * The mark is a rubber duck (rubber-duck debugging). It is stored as a pixel
+ * map, one character per pixel, and rendered with half-block glyphs so a single
+ * terminal row carries TWO pixel rows: `▀` paints the top half, `▄` the bottom,
+ * `█` both. Terminal cells are roughly twice as tall as they are wide, so this
+ * makes the pixels come out square and the art keeps its proportions.
+ *
+ * To redraw the duck, edit PIXELS — it is the picture, at 1:1. Trailing blanks
+ * are optional; every row is padded to WIDTH at render time so callers can rely
+ * on each line occupying exactly WIDTH columns (the brand header sets the
+ * wordmark beside the duck and needs that guarantee).
+ *
+ * Only `▀ ▄ █` and space are used. Glyphs like `●` are East-Asian *Ambiguous*
+ * width and render double-wide on terminals configured for CJK, which shears
+ * the row it sits in — do not reintroduce one.
+ *
+ * Colours are 24-bit ANSI emitted directly: pi's theme only exposes named
+ * palette slots, and "duck yellow" is not a palette slot.
+ */
+
+/** Ink for each pixel character, as 24-bit ANSI "r;g;b" components. */
+const INK: Record<string, string> = {
+	Y: "255;209;60", // body yellow
+	S: "231;172;32", // wing shade
+	O: "247;147;26", // beak orange
+	D: "40;30;20", //   eye
+};
+
+const BLANK = " ";
+const RESET = "\x1b[0m";
+
+/** The mark, one character per pixel. Two rows per rendered line. */
+const PIXELS: readonly string[] = [
+	"",
+	"    YYYYYY",
+	"   YYYYYYYY",
+	"  YYYYDYYYY",
+	"OOOOYYYYYYY",
+	" OOOYYYYYYY",
+	"   YYYYYYYY       YYY",
+	"    YYYYYY  YYYYYYYYYY",
+	"    YYYYYYYYYYYYYYYYYY",
+	"     YYYYYYYYYYYYYYYY",
+	"      YYYYYYYYYYSSSYY",
+	"     YYYYSSSSSSSSSSYY",
+	"     YYYYYSSSSSSSSYY",
+	"      YYYYSSSSSSSYY",
+	"       YYYYYYYYYYY",
+	"         YYYYYY",
+];
+
+/** Columns each rendered line occupies. */
+export const WIDTH = PIXELS.reduce((w, row) => Math.max(w, row.length), 0);
+
+/** Rendered lines the mark occupies (two pixel rows per line). */
+export const HEIGHT = Math.ceil(PIXELS.length / 2);
+
+function pixelAt(row: string, column: number): string {
+	return row[column] ?? BLANK;
+}
+
+/**
+ * Render one line from a pair of pixel rows.
+ *
+ * Escape codes are only emitted when the colour actually changes, and the
+ * background is cleared explicitly when leaving a two-tone cell — otherwise it
+ * would bleed across the rest of the line.
+ */
+function renderPair(top: string, bottom: string): string {
+	let out = "";
+	let fg = "";
+	let bg = "";
+
+	for (let column = 0; column < WIDTH; column++) {
+		const t = pixelAt(top, column);
+		const b = pixelAt(bottom, column);
+
+		let glyph = BLANK;
+		let wantFg = "";
+		let wantBg = "";
+
+		if (t !== BLANK && b !== BLANK) {
+			if (t === b) {
+				glyph = "█";
+				wantFg = INK[t] ?? "";
+			} else {
+				glyph = "▀";
+				wantFg = INK[t] ?? "";
+				wantBg = INK[b] ?? "";
+			}
+		} else if (t !== BLANK) {
+			glyph = "▀";
+			wantFg = INK[t] ?? "";
+		} else if (b !== BLANK) {
+			glyph = "▄";
+			wantFg = INK[b] ?? "";
+		}
+
+		if (wantFg !== fg) {
+			out += wantFg ? `\x1b[38;2;${wantFg}m` : "\x1b[39m";
+			fg = wantFg;
+		}
+		if (wantBg !== bg) {
+			out += wantBg ? `\x1b[48;2;${wantBg}m` : "\x1b[49m";
+			bg = wantBg;
+		}
+		out += glyph;
+	}
+
+	return out + RESET;
+}
+
+/** The mark as HEIGHT lines, each exactly WIDTH columns wide. */
+export function renderDuck(): string[] {
+	const lines: string[] = [];
+	for (let row = 0; row < PIXELS.length; row += 2) {
+		lines.push(renderPair(PIXELS[row] ?? "", PIXELS[row + 1] ?? ""));
+	}
+	return lines;
+}
+
+/** Visible width of a string, ignoring ANSI escape sequences. */
+export function visibleWidth(text: string): number {
+	// eslint-disable-next-line no-control-regex
+	return text.replace(/\x1b\[[0-9;]*m/g, "").length;
+}

package/extensions/core/git-observer.ts

@@ -0,0 +1,382 @@
+/**
+ * Session-scoped Pi Git observation runtime (item 2c971806).
+ *
+ * The model Bash command is not parsed. A private PATH prefix routes ordinary `git`
+ * argv through the package shim for that one tool execution. Connection/project
+ * identity stays host-side in this frozen envelope and never reaches child processes.
+ * When the host arms stamping (df71ab6c), the shim also receives the project id,
+ * the claim count, the one claimed task id and a fingerprint of the verified origin
+ * remote — never a credential — and tags plain commits by runtime/commit-stamp.mjs.
+ */
+
+import { execFileSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+
+const GLOBAL_KEY = "__devspecPiGitObserver";
+const MAX_JOURNAL_BYTES = 1024 * 1024;
+const MAX_ENVELOPES = 100;
+const ENVELOPE_TTL_MS = 30 * 60 * 1000;
+const FULL_SHA = /^[0-9a-f]{40}$/u;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
+export interface FrozenGitObservationEnvelope {
+	observationId: string;
+	generation: string;
+	piSessionId: string;
+	toolCallId: string;
+	connectionId: string;
+	projectId: string;
+	/** Host-only binding, never included in the shim environment or journal. */
+	connectionCapability?: string;
+	transport?: { tokenHash: string; endpoint: string };
+	createdAt: number;
+}
+
+/** What the host armed the shim with for one tool call (df71ab6c). */
+export interface CommitStampScope {
+	projectId: string;
+	/** Claimed tasks of this conversation in that project; 1 is the only count that stamps. */
+	claimCount: number;
+	/** The one claimed task, exactly when claimCount is 1. */
+	taskId: string | null;
+	/** sha256 of the verified origin URL (`git remote get-url origin`, trimmed), or null. */
+	remoteSha256: string | null;
+}
+
+/** What the shim did about the task tag of one observed commit. */
+export interface CommitStampReport {
+	outcome: "stamped" | "skipped";
+	reason: string | null;
+	task: string | null;
+	claims: number;
+}
+
+export interface ObservedGitCommit {
+	envelope: FrozenGitObservationEnvelope;
+	sha: string;
+	branch: string | null;
+	worktree: string;
+	previousHead: string | null;
+	amend: boolean;
+	observedAt: string;
+	/** Present when stamping was armed for the call that made this commit. */
+	stamp?: CommitStampReport;
+}
+
+interface GitObserverGeneration {
+	id: string;
+	piSessionId: string;
+	dir: string;
+	shimPath: string;
+	journalPath: string;
+	realGit: string;
+	journalOffset: number;
+	envelopes: Map<string, FrozenGitObservationEnvelope>;
+	processed: Set<string>;
+	active: boolean;
+}
+
+interface GitObserverStore {
+	current: GitObserverGeneration | null;
+}
+
+function store(): GitObserverStore {
+	const g = globalThis as unknown as Record<string, GitObserverStore | undefined>;
+	if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = { current: null };
+	return g[GLOBAL_KEY] as GitObserverStore;
+}
+
+function findRealGit(): string | null {
+	try {
+		const command = process.platform === "win32" ? "where" : "which";
+		const candidates = execFileSync(command, process.platform === "win32" ? ["git.exe"] : ["-a", "git"], {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 5000,
+			windowsHide: true,
+		}).trim().split(/\r?\n/u);
+		// Skip our own observer shims: with a stale shim dir on PATH, plain
+		// `which git` returns the shim and delegation recurses without bound
+		// (item 8729992e). The first non-shim candidate is the real Git.
+		for (const candidate of candidates) {
+			if (candidate && !basename(dirname(candidate)).startsWith("devspec-pi-git-") && existsSync(candidate)) return candidate;
+		}
+		return null;
+	} catch {
+		return null;
+	}
+}
+
+function shellQuote(value: string): string {
+	return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+/**
+ * Native Windows (c4b14794): Pi's bash tool runs Git Bash, or another bash on PATH
+ * such as MSYS2 or Cygwin. Those shells read PATH in POSIX form, so the stand-in's
+ * directory is converted with the shell's own cygpath when the call starts; a shell
+ * without it (the legacy WSL bash.exe, which runs Linux git anyway) keeps its PATH
+ * and git runs unobserved, exactly as before. Windows paths handed to node keep
+ * their drive letters, with forward slashes so sh never reads a backslash escape.
+ */
+function windowsPathForShell(path: string): string {
+	return path.replaceAll("\\", "/");
+}
+
+/**
+ * Whether the bash Pi will run on Windows can reach the stand-in: Pi takes Git
+ * Bash from Program Files first, then the first bash.exe on PATH. Git Bash,
+ * MSYS2 and Cygwin ship cygpath beside their bash; the legacy WSL bash.exe does
+ * not (and runs Linux git), so there Pi stays unobserved and says so (c4b14794).
+ * A shell set by hand in Pi's settings is not consulted.
+ */
+export function windowsShellHasCygpath(env: NodeJS.ProcessEnv = process.env): boolean {
+	const gitBash = [env.ProgramFiles, env["ProgramFiles(x86)"]]
+		.filter((base): base is string => Boolean(base))
+		.map((base) => join(base, "Git", "bin", "bash.exe"))
+		.find((path) => existsSync(path));
+	let shell = gitBash ?? null;
+	if (!shell) {
+		try {
+			shell = execFileSync("where", ["bash.exe"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000, windowsHide: true })
+				.trim().split(/\r?\n/u).find((path) => path && existsSync(path)) ?? null;
+		} catch { shell = null; }
+	}
+	if (!shell) return false;
+	return [dirname(shell), join(dirname(dirname(shell)), "usr", "bin")].some((dir) => existsSync(join(dir, "cygpath.exe")));
+}
+
+function pathAssignment(dir: string): string {
+	if (process.platform !== "win32") return `export PATH=${shellQuote(dir)}:"$PATH"`;
+	return `__devspec_pi_git_dir="$(/usr/bin/cygpath -u ${shellQuote(windowsPathForShell(dir))} 2>/dev/null)" && [ -n "$__devspec_pi_git_dir" ] && export PATH="$__devspec_pi_git_dir:$PATH"; unset __devspec_pi_git_dir`;
+}
+
+function cleanupGeneration(generation: GitObserverGeneration | null): void {
+	if (!generation) return;
+	generation.active = false;
+	generation.envelopes.clear();
+	try { rmSync(generation.dir, { recursive: true, force: true }); } catch { /* best effort */ }
+}
+
+export function initializeGitObserver(piSessionId: string, preserveReload = false): boolean {
+	const state = store();
+	if (process.platform === "win32" && !windowsShellHasCygpath()) {
+		state.current = null;
+		return false;
+	}
+	if (preserveReload && state.current?.active && state.current.piSessionId === piSessionId) return true;
+	cleanupGeneration(state.current);
+	const realGit = findRealGit();
+	if (!realGit) {
+		state.current = null;
+		return false;
+	}
+	try {
+		const dir = mkdtempSync(join(tmpdir(), "devspec-pi-git-"));
+		chmodSync(dir, 0o700);
+		const shimPath = join(dir, "git");
+		const modulePath = join(dir, "git-observer-shim.mjs");
+		const source = fileURLToPath(new URL("../../runtime/git-observer-shim.mjs", import.meta.url));
+		copyFileSync(source, modulePath);
+		chmodSync(modulePath, 0o600);
+		// The shim imports its stamping rules from beside itself (df71ab6c).
+		const stampModulePath = join(dir, "commit-stamp.mjs");
+		copyFileSync(fileURLToPath(new URL("../../runtime/commit-stamp.mjs", import.meta.url)), stampModulePath);
+		chmodSync(stampModulePath, 0o600);
+		// Use the exact host runtime, never /usr/bin/env node or the mutated PATH.
+		// On Windows the same sh script is what Git Bash runs for `git`.
+		const runtime = process.platform === "win32" ? windowsPathForShell(process.execPath) : process.execPath;
+		const shimModule = process.platform === "win32" ? windowsPathForShell(modulePath) : modulePath;
+		writeFileSync(shimPath, `#!/bin/sh\nexec ${shellQuote(runtime)} ${shellQuote(shimModule)} "$@"\n`, { mode: 0o700 });
+		chmodSync(shimPath, 0o700);
+		const journalPath = join(dir, "observations.jsonl");
+		writeFileSync(journalPath, "", { mode: 0o600 });
+		state.current = {
+			id: randomUUID(),
+			piSessionId,
+			dir,
+			shimPath,
+			journalPath,
+			realGit,
+			journalOffset: 0,
+			envelopes: new Map(),
+			processed: new Set(),
+			active: true,
+		};
+		return true;
+	} catch {
+		cleanupGeneration(state.current);
+		state.current = null;
+		return false;
+	}
+}
+
+/** Whether this Pi process has a working git stand-in. */
+export function gitObserverActive(): boolean {
+	return store().current?.active === true;
+}
+
+export function shutdownGitObserver(reason: "quit" | "reload" | "new" | "resume" | "fork"): void {
+	if (reason === "reload") return;
+	const state = store();
+	cleanupGeneration(state.current);
+	state.current = null;
+}
+
+/** Return a generic shell prefix; the original command is never inspected. */
+export function prepareGitObservation(params: {
+	toolCallId: string;
+	piSessionId: string;
+	connectionId: string;
+	projectId: string;
+	connectionCapability?: string;
+	transport?: { tokenHash: string; endpoint: string };
+	stamp?: CommitStampScope | null;
+}): { observationId: string; prefix: string } | null {
+	const generation = store().current;
+	if (!generation?.active || generation.piSessionId !== params.piSessionId) return null;
+	if (!UUID.test(params.connectionId) || !UUID.test(params.projectId)) return null;
+
+	const observationId = randomUUID();
+	generation.envelopes.set(observationId, Object.freeze({
+		observationId,
+		generation: generation.id,
+		piSessionId: params.piSessionId,
+		toolCallId: params.toolCallId,
+		connectionId: params.connectionId,
+		projectId: params.projectId,
+		...(params.connectionCapability ? { connectionCapability: params.connectionCapability } : {}),
+		...(params.transport ? { transport: Object.freeze({ ...params.transport }) } : {}),
+		createdAt: Date.now(),
+	}));
+	while (generation.envelopes.size > MAX_ENVELOPES) {
+		const oldest = generation.envelopes.keys().next().value;
+		if (!oldest) break;
+		generation.envelopes.delete(oldest);
+	}
+
+	const assignments = [
+		pathAssignment(generation.dir),
+		`export DEVSPEC_PI_REAL_GIT=${shellQuote(generation.realGit)}`,
+		`export DEVSPEC_PI_GIT_OBSERVER_DIR=${shellQuote(generation.dir)}`,
+		`export DEVSPEC_PI_GIT_OBSERVER_JOURNAL=${shellQuote(generation.journalPath)}`,
+		`export DEVSPEC_PI_GIT_OBSERVER_GENERATION=${shellQuote(generation.id)}`,
+		`export DEVSPEC_PI_GIT_OBSERVATION_ID=${shellQuote(observationId)}`,
+		`export DEVSPEC_PI_GIT_OBSERVER_SESSION=${shellQuote(params.piSessionId)}`,
+		// Always set or cleared, so a value exported by an enclosing session can
+		// never arm stamping for this one.
+		...stampAssignments(params.stamp ?? null),
+	];
+	return { observationId, prefix: `${assignments.join("; ")}\n` };
+}
+
+const STAMP_ENV_NAMES = ["DEVSPEC_PI_STAMP_PROJECT", "DEVSPEC_PI_STAMP_CLAIMS", "DEVSPEC_PI_STAMP_TASK", "DEVSPEC_PI_STAMP_REMOTE_SHA256"] as const;
+const SHA256 = /^[0-9a-f]{64}$/u;
+
+function stampAssignments(stamp: CommitStampScope | null): string[] {
+	const valid = stamp && UUID.test(stamp.projectId) && Number.isSafeInteger(stamp.claimCount) && stamp.claimCount >= 1 &&
+		(stamp.claimCount === 1 ? Boolean(stamp.taskId && UUID.test(stamp.taskId)) : stamp.taskId === null) &&
+		(stamp.remoteSha256 === null || SHA256.test(stamp.remoteSha256));
+	if (!stamp || !valid) return [`unset ${STAMP_ENV_NAMES.join(" ")}`];
+	return [
+		`export DEVSPEC_PI_STAMP_PROJECT=${shellQuote(stamp.projectId.toLowerCase())}`,
+		`export DEVSPEC_PI_STAMP_CLAIMS=${shellQuote(String(stamp.claimCount))}`,
+		stamp.taskId ? `export DEVSPEC_PI_STAMP_TASK=${shellQuote(stamp.taskId.toLowerCase())}` : "unset DEVSPEC_PI_STAMP_TASK",
+		stamp.remoteSha256 ? `export DEVSPEC_PI_STAMP_REMOTE_SHA256=${shellQuote(stamp.remoteSha256)}` : "unset DEVSPEC_PI_STAMP_REMOTE_SHA256",
+	];
+}
+
+function stampReport(value: unknown): CommitStampReport | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const row = value as Record<string, unknown>;
+	if (row.v !== 1 || (row.outcome !== "stamped" && row.outcome !== "skipped")) return undefined;
+	if (row.reason !== null && (typeof row.reason !== "string" || !/^[a-z_]{1,40}$/u.test(row.reason))) return undefined;
+	if (row.task !== null && (typeof row.task !== "string" || !UUID.test(row.task))) return undefined;
+	if (!Number.isSafeInteger(row.claims) || (row.claims as number) < 1) return undefined;
+	if (row.outcome === "stamped" && (row.task === null || row.reason !== null)) return undefined;
+	return { outcome: row.outcome, reason: row.reason as string | null, task: row.task as string | null, claims: row.claims as number };
+}
+
+function validJournalRow(value: unknown): value is {
+	v: 1;
+	generation: string;
+	observationId: string;
+	sha: string;
+	branch: string | null;
+	worktree: string;
+	previousHead: string | null;
+	amend: boolean;
+	observedAt: string;
+} {
+	if (!value || typeof value !== "object") return false;
+	const row = value as Record<string, unknown>;
+	return row.v === 1 && typeof row.generation === "string" && UUID.test(String(row.observationId ?? "")) &&
+		typeof row.sha === "string" && FULL_SHA.test(row.sha) &&
+		(row.branch === null || (typeof row.branch === "string" && row.branch.length <= 255)) &&
+		typeof row.worktree === "string" && row.worktree.length > 0 && row.worktree.length <= 4096 &&
+		(row.previousHead === null || (typeof row.previousHead === "string" && FULL_SHA.test(row.previousHead))) &&
+		typeof row.amend === "boolean" && typeof row.observedAt === "string";
+}
+
+export function drainGitObservations(now = Date.now()): ObservedGitCommit[] {
+	const generation = store().current;
+	if (!generation?.active) return [];
+	for (const [id, envelope] of generation.envelopes) {
+		if (now - envelope.createdAt > ENVELOPE_TTL_MS) generation.envelopes.delete(id);
+	}
+	try {
+		const data = readFileSync(generation.journalPath);
+		if (generation.journalOffset > data.byteLength) generation.journalOffset = 0;
+		if (data.byteLength > MAX_JOURNAL_BYTES) {
+			// Drop the oversized generation slice at a tool boundary and recover for
+			// future observations instead of remaining permanently disabled.
+			writeFileSync(generation.journalPath, "", { mode: 0o600 });
+			generation.journalOffset = 0;
+			return [];
+		}
+		const tail = data.subarray(generation.journalOffset).toString("utf8");
+		const lastNewline = tail.lastIndexOf("\n");
+		if (lastNewline < 0) return [];
+		generation.journalOffset += Buffer.byteLength(tail.slice(0, lastNewline + 1));
+		const observed: ObservedGitCommit[] = [];
+		for (const line of tail.slice(0, lastNewline).split("\n")) {
+			if (!line || line.length > 4096) continue;
+			let parsed: unknown;
+			try { parsed = JSON.parse(line); } catch { continue; }
+			if (!validJournalRow(parsed) || parsed.generation !== generation.id) continue;
+			const processedKey = `${parsed.observationId}:${parsed.sha}:${parsed.worktree}`;
+			if (generation.processed.has(processedKey)) continue;
+			const envelope = generation.envelopes.get(parsed.observationId);
+			if (!envelope || envelope.generation !== generation.id || envelope.piSessionId !== generation.piSessionId) continue;
+			generation.processed.add(processedKey);
+			while (generation.processed.size > 500) {
+				const oldest = generation.processed.values().next().value;
+				if (!oldest) break;
+				generation.processed.delete(oldest);
+			}
+			observed.push({
+				envelope,
+				sha: parsed.sha,
+				branch: parsed.branch,
+				worktree: parsed.worktree,
+				previousHead: parsed.previousHead,
+				amend: parsed.amend,
+				observedAt: parsed.observedAt,
+				...(() => { const stamp = stampReport((parsed as { stamp?: unknown }).stamp); return stamp ? { stamp } : {}; })(),
+			});
+		}
+		return observed;
+	} catch {
+		return [];
+	}
+}
+
+export function resetGitObserverForTests(): void {
+	const state = store();
+	cleanupGeneration(state.current);
+	state.current = null;
+}

package/extensions/core/github-identity.ts

@@ -0,0 +1,26 @@
+/**
+ * The GitHub identity link at connect (ADR "Protecting intent" §14; server side
+ * c45f75d4; Pi side 306fb64a). For a project whose repositories are on GitHub,
+ * `register_connection` returns `github_identity`: `linked` with the person's
+ * GitHub login(s), or `link_required` with one link to open. Linking is one
+ * click through DevSpec's own GitHub App, identity only: DevSpec keeps no token.
+ *
+ * DevSpec builds the link and decides when to offer it. Pi only shows it to the
+ * person at the terminal, because the person, not the model, opens it.
+ */
+
+/** What Pi shows the person when the link is needed, or null when nothing is. */
+export function githubIdentityNotice(value: unknown): string | null {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+	const prompt = value as { status?: unknown; url?: unknown };
+	if (prompt.status !== "link_required" || typeof prompt.url !== "string") return null;
+	let url: URL;
+	try {
+		url = new URL(prompt.url);
+	} catch {
+		return null;
+	}
+	// Only a web link is offered to be opened; anything else is not shown.
+	if (url.protocol !== "https:" && !(url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1"))) return null;
+	return `DevSpec: this project's repositories are on GitHub. Link your GitHub account so your pull requests and commits show as yours. GitHub confirms who you are, and DevSpec keeps no access to your account: ${url.toString()}`;
+}