@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/command-offer.ts

@@ -0,0 +1,88 @@
+import { parseIngressAttachment, type IngressAttachment } from './remote-payload.ts';
+import { MAX_ATTACHMENTS, MAX_TOTAL_ATTACHMENT_BYTES } from './attachment-limits.ts';
+
+export interface CommandOffer {
+	version: 1;
+	connection_id: string;
+	source_session_id: string;
+	attachment_id: string;
+	source_message_id: string;
+	blocking_attempt_id: string;
+	attachments: IngressAttachment[];
+}
+export interface CommandOfferScope {
+	nativeSessionId: string;
+	connectionId: string;
+	sessionId: string;
+	attachmentId: string;
+}
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const keys = ['version', 'connection_id', 'source_session_id', 'attachment_id', 'source_message_id', 'blocking_attempt_id', 'attachments'];
+/** Offers contain no executable text or provenance and never enter model context. */
+export function parseCommandOfferPoll(value: unknown, scope: CommandOfferScope): { supported: boolean; stale: boolean; offer: CommandOffer | null } {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid command offer response');
+	const root = value as Record<string, unknown>;
+	if (root.command_offer_version === undefined) return { supported: false, stale: false, offer: null };
+	if (root.command_offer_version !== 1 || typeof root.command_handoff_stale !== 'boolean') throw new Error('Unsupported command offer response');
+	if (root.command_offer === null) return { supported: true, stale: root.command_handoff_stale, offer: null };
+	const raw = root.command_offer;
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('Invalid command offer');
+	const row = raw as Record<string, unknown>;
+	if (Object.keys(row).length !== keys.length || Object.keys(row).some(key => !keys.includes(key)) || row.version !== 1) throw new Error('Invalid command offer fields');
+	for (const key of keys.slice(1, -1)) if (typeof row[key] !== 'string' || !uuid.test(row[key] as string)) throw new Error('Invalid command offer identity');
+	if (row.connection_id !== scope.connectionId || row.source_session_id !== scope.sessionId || row.attachment_id !== scope.attachmentId) throw new Error('Command offer attachment changed');
+	if (!Array.isArray(row.attachments) || row.attachments.length > MAX_ATTACHMENTS) throw new Error('Invalid command offer attachments');
+	const attachments = row.attachments.map((item, index) => parseIngressAttachment(item, `command offer.attachments[${index}]`));
+	if (attachments.reduce((sum, item) => sum + (item.size_bytes ?? 0), 0) > MAX_TOTAL_ATTACHMENT_BYTES) throw new Error('Command offer attachment budget exceeded');
+	return { supported: true, stale: root.command_handoff_stale, offer: { version: 1,
+		connection_id: row.connection_id as string, source_session_id: row.source_session_id as string,
+		attachment_id: row.attachment_id as string, source_message_id: row.source_message_id as string,
+		blocking_attempt_id: row.blocking_attempt_id as string, attachments } };
+}
+
+export function commandOfferAction(input: {
+	current: boolean; exactInteractionApplied: boolean; foregroundIdle: boolean;
+	hasPendingMessages: boolean; preemptEnabled: boolean; abortAlreadyRequested: boolean;
+}): 'ignore' | 'wait' | 'abort' | 'ready' {
+	if (!input.current || !input.exactInteractionApplied) return 'ignore';
+	if (input.foregroundIdle) return input.hasPendingMessages ? 'wait' : 'ready';
+	return input.preemptEnabled && !input.abortAlreadyRequested ? 'abort' : 'wait';
+}
+
+export const COMMAND_PREEMPT_ENTRY = 'devspec-command-preemption';
+/** Negative cancellation budget only; journal/history can NEVER authorize work. */
+export class CommandPreemptionBudget {
+	private sources = new Set<string>();
+	private scope: string | null = null;
+	bind(scope: CommandOfferScope | null, entries: readonly unknown[]): void {
+		const key = scope ? JSON.stringify(scope) : null;
+		if (key === this.scope) return;
+		this.scope = key; this.sources.clear();
+		if (!scope) return;
+		for (const raw of entries) {
+			const entry = raw as { type?: unknown; customType?: unknown; data?: Record<string, unknown> };
+			const data = entry?.data;
+			if (entry?.type !== 'custom' || entry.customType !== COMMAND_PREEMPT_ENTRY || !data || data.version !== 1 ||
+				data.nativeSessionId !== scope.nativeSessionId || data.connectionId !== scope.connectionId ||
+				data.sessionId !== scope.sessionId || data.attachmentId !== scope.attachmentId ||
+				typeof data.sourceMessageId !== 'string' || !uuid.test(data.sourceMessageId)) continue;
+			if (data.phase === 'canonical_received') { this.sources.delete(data.sourceMessageId); continue; }
+			if (data.phase !== undefined && data.phase !== 'abort_requested') continue;
+			if (this.sources.size < 1000) this.sources.add(data.sourceMessageId);
+		}
+	}
+	has(source: string): boolean { return this.sources.has(source); }
+	request(source: string, scope: CommandOfferScope, append: (type: string, data: unknown) => void): boolean {
+		if (this.scope !== JSON.stringify(scope) || !uuid.test(source) || this.has(source) || this.sources.size >= 1000) return false;
+		append(COMMAND_PREEMPT_ENTRY, { version: 1, phase: 'abort_requested', ...scope, sourceMessageId: source });
+		this.sources.add(source);
+		return true;
+	}
+	/** Retires only the cancellation budget, not an application/execution ACK. */
+	received(source: string, scope: CommandOfferScope, append: (type: string, data: unknown) => void): boolean {
+		if (this.scope !== JSON.stringify(scope) || !this.sources.has(source)) return false;
+		append(COMMAND_PREEMPT_ENTRY, { version: 1, phase: 'canonical_received', ...scope, sourceMessageId: source });
+		this.sources.delete(source);
+		return true;
+	}
+}

package/extensions/core/command-runner.ts

@@ -0,0 +1,62 @@
+/**
+ * In-process access to Pi's command context (items e82a690a, 6beb89c6).
+ *
+ * ctx.reload() and ctx.navigateTree() exist only on ExtensionCommandContext.
+ * The pump/event ctx is ExtensionContext and does not have them. sendUserMessage("/devspec.reload")
+ * is not a substitute: it calls prompt({ expandPromptTemplates: false }) and
+ * skips _tryExecuteExtensionCommand, so the slash becomes a user prompt.
+ *
+ * ExtensionRunner.createCommandContext() is the official factory the TUI
+ * uses. We remember the live runner via the public bindCommandContext hook
+ * (called on session_start and after every reload) and then call
+ * createCommandContext().reload() — the same handleReloadCommand path — or
+ * createCommandContext().navigateTree(), the same path as /tree.
+ */
+
+import { ExtensionRunner } from "@earendil-works/pi-coding-agent";
+
+const GLOBAL_KEY = "__devspecPiExtensionRunner";
+
+/** The part of Pi's command context the owner's controls use. */
+export type CommandContextLike = {
+	reload?: () => Promise<void>;
+	navigateTree?: (targetId: string, options?: { summarize?: boolean }) => Promise<{ cancelled: boolean }>;
+	waitForIdle?: () => Promise<void>;
+};
+
+type RunnerLike = {
+	createCommandContext?: () => CommandContextLike;
+};
+
+function store(): { current: RunnerLike | null } {
+	const g = globalThis as unknown as Record<string, { current: RunnerLike | null } | undefined>;
+	if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = { current: null };
+	return g[GLOBAL_KEY] as { current: RunnerLike | null };
+}
+
+let patched = false;
+
+/** Install once per process. Safe to call from every extension file. */
+export function rememberExtensionRunner(): void {
+	if (patched) return;
+	const proto = ExtensionRunner.prototype as unknown as {
+		bindCommandContext?: (actions?: unknown) => void;
+	};
+	const original = proto.bindCommandContext;
+	if (typeof original !== "function") return;
+	patched = true;
+	proto.bindCommandContext = function (this: RunnerLike, actions?: unknown) {
+		store().current = this;
+		return original.call(this, actions);
+	};
+}
+
+export function extensionCommandContext(): CommandContextLike | null {
+	const runner = store().current;
+	if (!runner || typeof runner.createCommandContext !== "function") return null;
+	try {
+		return runner.createCommandContext();
+	} catch {
+		return null;
+	}
+}

package/extensions/core/command-turn.ts

@@ -0,0 +1,88 @@
+/**
+ * Mechanical binding between a poll-delivered owner command and the exact Pi
+ * user message that starts its model turn.
+ *
+ * Pi's sendUserMessage API does not accept opaque metadata, so the adapter
+ * retains immutable server identity out-of-band until Pi emits the exact user
+ * message back through message_start. Matching the complete text (not a preview
+ * or content hash) keeps repeated owner messages as separate segments.
+ *
+ * Lifetime (item 6f4136d8): a binding is valid from remember() until its
+ * message_start take(). Anything still pending after its command closes is a
+ * stray that a later terminal input with identical text must never inherit.
+ * Callers drop those via forgetByCommand() on completion and clear() on every
+ * authority rotation (stop, revive/replacement, attach change).
+ */
+export interface CanonicalQueueItem {
+	hiddenContent: string;
+	details: unknown;
+}
+
+export interface CommandTurnBinding {
+	turnId: string;
+	commandMessageId: string;
+	canonicalQueueItem?: CanonicalQueueItem;
+	/**
+	 * Every command this delivery carries, oldest first, with its own delivery
+	 * provenance_ref and message id (item 7a4d04fd): the host opens each one's
+	 * request when the message starts, so every write the turn makes, and every
+	 * wake its work causes, names the sender it serves.
+	 */
+	requests?: CommandRequestRef[];
+}
+
+export interface CommandRequestRef {
+	provenanceRef: string;
+	messageId: string;
+	/** The connection's owner sent it (owner authority), so it is the owner's own request. */
+	fromOwner?: boolean;
+}
+
+export class CommandTurnBindings {
+	private pending: Array<{ message: string; binding: CommandTurnBinding }> = [];
+
+	remember(
+		message: string,
+		turnId: string | undefined,
+		commandMessageId: string | undefined,
+		canonicalQueueItem?: CanonicalQueueItem,
+		requests?: readonly CommandRequestRef[],
+	): void {
+		if (!turnId || !commandMessageId) return;
+		this.pending.push({ message, binding: { turnId, commandMessageId, ...(canonicalQueueItem ? { canonicalQueueItem } : {}), ...(requests?.length ? { requests: requests.map((ref) => ({ ...ref })) } : {}) } });
+		if (this.pending.length > 128) this.pending.shift();
+	}
+
+	peek(message: string): CommandTurnBinding | undefined {
+		return this.pending.find((entry) => entry.message === message)?.binding;
+	}
+
+	take(message: string): CommandTurnBinding | undefined {
+		const index = this.pending.findIndex((entry) => entry.message === message);
+		if (index === -1) return undefined;
+		const [entry] = this.pending.splice(index, 1);
+		return entry?.binding;
+	}
+
+	forget(message: string, turnId: string | undefined, commandMessageId: string | undefined): void {
+		if (!turnId || !commandMessageId) return;
+		const index = this.pending.findIndex((entry) =>
+			entry.message === message &&
+			entry.binding.turnId === turnId &&
+			entry.binding.commandMessageId === commandMessageId
+		);
+		if (index !== -1) this.pending.splice(index, 1);
+	}
+
+	forgetByCommand(turnId: string | undefined, commandMessageId: string | undefined): void {
+		if (!turnId) return;
+		this.pending = this.pending.filter((entry) =>
+			entry.binding.turnId !== turnId ||
+			(commandMessageId !== undefined && entry.binding.commandMessageId !== commandMessageId)
+		);
+	}
+
+	clear(): void {
+		this.pending = [];
+	}
+}

package/extensions/core/commit-ledger.ts

@@ -0,0 +1,195 @@
+/**
+ * DevSpec Pi — the mechanical commit ledger (item efe7e0a7).
+ *
+ * An agent that commits through the bash tool should never TRANSCRIBE a commit
+ * SHA — it should HAVE it. Ali watched a hand-typed SHA land wrong past the
+ * short prefix (2026-08-12): "it should be mechanical, impossible to get
+ * wrong." So: the extension recognizes ordinary Git commit/merge result output,
+ * keeps the resulting SHAs, and can corroborate an explicitly supplied full object.
+ * Missing/short hints stay missing/short: only the server's scoped evidence can
+ * select an implementation commit or establish project-wide prefix uniqueness.
+ *
+ * Same principle class as mechanical-only delivery (cc9e8c43): when the system
+ * knows the SHA, it says it — never the model's job to remember or transcribe.
+ * This is accuracy assistance, not provenance-source proof. Like all cross-extension
+ * state, the ledger lives on globalThis
+ * (jiti gives every extension file a fresh module graph).
+ */
+
+import { execFileSync } from "node:child_process";
+
+export interface LedgerCommit {
+	/** Full SHA when the repo resolved it; the short SHA otherwise. */
+	sha: string;
+	shortSha: string;
+	branch: string;
+	at: number;
+	/** Actual commit-object message observed after a recognized Pi Bash commit. */
+	commitMessage?: string;
+}
+
+const GLOBAL_KEY = "__devspecPiCommitLedger";
+const MAX_ENTRIES = 20;
+/** Retain recent explicit-object metadata for 30 minutes; never infer work identity. */
+const RECENT_MS = 30 * 60 * 1000;
+
+interface LedgerStore {
+	commits: LedgerCommit[];
+}
+
+function store(): LedgerStore {
+	const g = globalThis as unknown as Record<string, LedgerStore | undefined>;
+	if (!g[GLOBAL_KEY]) g[GLOBAL_KEY] = { commits: [] };
+	return g[GLOBAL_KEY] as LedgerStore;
+}
+
+export function recentCommits(): LedgerCommit[] {
+	return store().commits.map((commit) => ({ ...commit }));
+}
+
+export function recordObservedCommit(entry: LedgerCommit): void {
+	const s = store();
+	const existing = s.commits.findIndex((c) => c.sha === entry.sha);
+	if (existing >= 0) s.commits.splice(existing, 1);
+	s.commits.push(entry);
+	if (s.commits.length > MAX_ENTRIES) s.commits.splice(0, s.commits.length - MAX_ENTRIES);
+}
+
+/** A resolver answers the full SHA for a rev, or null when it cannot. */
+export type GitResolver = (rev: string) => string | null;
+
+/** The real resolver: ask the repo at `cwd`. Worktrees share the object
+ *  store, so a commit made in a linked worktree resolves from the main one. */
+const GIT_REVISION = /^(?:HEAD|[0-9a-f]{7,40}(?:\^\{commit\})?)$/;
+const COMMIT_SHA_INPUT = /^[0-9a-f]{7,40}$/;
+
+export function repoResolver(cwd: string): GitResolver {
+	return (rev: string) => {
+		// rev-parse accepts revision syntax powerful enough to reach reflogs and,
+		// when interpolated into a shell, arbitrary commands. This resolver needs
+		// only HEAD or a hexadecimal commit candidate with an optional peel.
+		if (!GIT_REVISION.test(rev)) return null;
+		try {
+			const out = execFileSync("git", ["rev-parse", "--verify", rev], {
+				cwd,
+				stdio: ["ignore", "pipe", "ignore"],
+			})
+				.toString()
+				.trim();
+			return /^[0-9a-f]{40}$/.test(out) ? out : null;
+		} catch {
+			return null;
+		}
+	};
+}
+
+/** Read the immutable commit object's message without a shell. */
+export function repoCommitMessage(cwd: string, sha: string): string | null {
+	if (!/^[0-9a-f]{40}$/u.test(sha)) return null;
+	try {
+		return execFileSync("git", ["show", "-s", "--format=%B", sha], {
+			cwd,
+			stdio: ["ignore", "pipe", "ignore"],
+		}).toString().replace(/\n+$/u, "");
+	} catch {
+		return null;
+	}
+}
+
+/** Attach the immutable commit message to one already captured ledger entry. */
+export function annotateCommitMessage(sha: string, message: string): LedgerCommit | null {
+	const entry = store().commits.find((commit) => commit.sha === sha);
+	if (!entry) return null;
+	entry.commitMessage = message;
+	return { ...entry };
+}
+
+const COMMIT_LINE = /^\[([^\s\]]+)\s+([0-9a-f]{7,10})\]/m;
+const GIT_WRITE = /\bgit\s+(commit|merge)\b/;
+const NO_NEW_COMMIT = /Already up to date|nothing to commit|nothing added to commit/i;
+
+/** Parse the commit summary line git prints: `[branch shortsha] subject`. */
+export function parseCommitOutput(output: string): { branch: string; shortSha: string } | null {
+	const m = COMMIT_LINE.exec(output);
+	if (!m) return null;
+	return { branch: m[1], shortSha: m[2] };
+}
+
+/**
+ * The watcher entry point — call from tool_execution_end for successful bash
+ * calls. Returns the captured commit, or null when the command left no new
+ * commit (non-git commands, failed writes, "Already up to date" merges).
+ */
+export function captureGitCommit(command: string, output: string, resolve: GitResolver): LedgerCommit | null {
+	if (!GIT_WRITE.test(command)) return null;
+	if (NO_NEW_COMMIT.test(output)) return null;
+
+	const parsed = parseCommitOutput(output);
+	if (parsed) {
+		const full = resolve(parsed.shortSha) ?? parsed.shortSha;
+		const entry: LedgerCommit = { sha: full, shortSha: parsed.shortSha, branch: parsed.branch, at: Date.now() };
+		recordObservedCommit(entry);
+		return entry;
+	}
+
+	// Merge output does not identify the resulting object. Without a first-class
+	// Git hook or a before/after observation, resolving HEAD could capture an old
+	// commit after arbitrary Bash text. Fail open: require an explicit SHA later.
+	return null;
+}
+
+export type CommitShaVerdict = {
+	ok: true;
+	/** The sha to send, or null to send none (the server's own fill runs). */
+	sha: string | null;
+	/** Retained result shape; caller hints are never locally auto-filled. */
+	autoFilled: boolean;
+	/**
+	 * True for every short hint or an uncorroborated full object. Local prefix
+	 * matches cannot establish uniqueness across the project. Hints pass to the
+	 * server unchanged for scoped resolution/provisional storage (ADR 60efaed0).
+	 * A local miss is never an identity verdict in a multi-repo project.
+	 */
+	unverified?: boolean;
+	commitMessage?: string;
+} | { ok: false; error: string };
+
+function ledgerVerdict(commit: LedgerCommit, input: string): CommitShaVerdict {
+	return {
+		ok: true,
+		sha: input,
+		autoFilled: false,
+		...(commit.commitMessage ? { commitMessage: commit.commitMessage } : {}),
+	};
+}
+
+/**
+ * Validate commit_sha shape before record_implementation. A full object can
+ * carry locally corroborated message bytes, never authorship or round proof.
+ * A sole recent commit is NOT an item/claim binding (P7 / e47fcd4e: report-only
+ * P6 inherited the preceding P4 commit). A cwd or ledger prefix match is NOT
+ * project-wide uniqueness. Preserve omissions and every supplied hint's bytes
+ * for the server's scoped resolver. Only malformed normalized shapes refuse;
+ * local misses, ambiguous prefixes and absent hints always remain fail-open.
+ */
+export function validateCommitSha(input: string | undefined, resolve: GitResolver, now: number = Date.now()): CommitShaVerdict {
+	if (input == null || (typeof input === "string" && !input.trim())) {
+		return { ok: true, sha: null, autoFilled: false, unverified: true };
+	}
+	const normalized = typeof input === "string" ? input.trim().toLowerCase() : "";
+	if (!COMMIT_SHA_INPUT.test(normalized)) {
+		return {
+			ok: false,
+			error: "commit_sha must contain 7–40 hexadecimal characters; revision syntax and shell text are not accepted.",
+		};
+	}
+	if (normalized.length < 40) return { ok: true, sha: input, autoFilled: false, unverified: true };
+
+	const recent = recentCommits().filter((c) => now - c.at <= RECENT_MS);
+	const hit = recent.find((c) => c.sha === normalized);
+	if (hit) return ledgerVerdict(hit, input);
+
+	const resolved = resolve(`${normalized}^{commit}`);
+	if (resolved === normalized) return { ok: true, sha: input, autoFilled: false };
+	return { ok: true, sha: input, autoFilled: false, unverified: true };
+}

package/extensions/core/commit-stamp.ts

@@ -0,0 +1,98 @@
+/**
+ * Host side of commit tag stamping (DevSpec item df71ab6c).
+ *
+ * Pi's git stand-in tags a plain commit with the claimed task's
+ * `[devspec:<uuid>]` (runtime/commit-stamp.mjs). This module decides what the
+ * stand-in is armed with for one Bash call, and words what the model is told
+ * about each commit it made. How tags link commits to work is the served
+ * contract's commit_provenance_contract; nothing here blocks a commit.
+ */
+
+import { createHash } from "node:crypto";
+import { getBond } from "./bond-state.ts";
+import { gitObserverActive, type CommitStampReport, type CommitStampScope } from "./git-observer.ts";
+import type { ObservedClaim } from "./work-state.ts";
+
+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 CommitStampDeps {
+	/** This conversation's observed claims. */
+	claims(sessionId: string): ObservedClaim[];
+	/** The raw `git remote get-url origin` of a directory, or null. */
+	originUrl(cwd: string): Promise<string | null>;
+	/** The project a directory positively belongs to (pin or server-verified remote), or null. */
+	resolveProject(cwd: string): Promise<string | null>;
+}
+
+/**
+ * Whether Pi can tag this conversation's commits at all: a working git stand-in
+ * (POSIX today, so not native Windows) and a bonded connection it arms per call.
+ * Without it, the model is told to write the tag itself (c4b14794).
+ */
+export function commitTaggingAvailable(): boolean {
+	const bond = getBond();
+	return gitObserverActive() && Boolean(bond?.projectId && bond.connectionCapability);
+}
+
+export function originFingerprint(url: string): string {
+	return createHash("sha256").update(url.trim()).digest("hex");
+}
+
+/**
+ * What to arm the stand-in with, or null when no task is claimed in this project.
+ * The task id goes only with exactly one claim. The origin fingerprint goes only
+ * when the call's own directory is verified to belong to the project; the stand-in
+ * also accepts a pin naming the project, and leaves every other repository alone.
+ */
+export async function commitStampScope(input: { sessionId: string; projectId: string; cwd: string }, deps: CommitStampDeps): Promise<CommitStampScope | null> {
+	if (!UUID.test(input.projectId)) return null;
+	const projectId = input.projectId.toLowerCase();
+	const claims = deps.claims(input.sessionId)
+		.filter((claim) => UUID.test(claim.taskId) && (!claim.projectId || claim.projectId.toLowerCase() === projectId));
+	const taskIds = [...new Set(claims.map((claim) => claim.taskId.toLowerCase()))];
+	if (taskIds.length === 0) return null;
+	let remoteSha256: string | null = null;
+	try {
+		const url = await deps.originUrl(input.cwd);
+		if (url?.trim() && (await deps.resolveProject(input.cwd))?.toLowerCase() === projectId) remoteSha256 = originFingerprint(url);
+	} catch { remoteSha256 = null; }
+	return { projectId, claimCount: taskIds.length, taskId: taskIds.length === 1 ? taskIds[0]! : null, remoteSha256 };
+}
+
+const REASON_WORDS: Readonly<Record<string, string>> = {
+	amend: "it amends an earlier commit",
+	fixup: "it is a fixup commit",
+	squash: "it is a squash commit",
+	reuse_message: "it reuses another commit's message",
+	no_edit: "it keeps an earlier commit's message",
+	edit: "its message is edited in an editor",
+	editor: "its message was written in an editor",
+	template: "its message starts from a template",
+	interactive: "it was made interactively",
+	unrecognised_option: "it uses a git commit option Pi does not read",
+	conflicting_messages: "it names its message more than once",
+	not_plain_commit: "it was not run as a plain git commit",
+	message_file_unreadable: "Pi could not read its message file",
+	message_unreadable: "Pi could not read its message",
+	terminal_stdin: "its message was typed at a terminal",
+	no_subject: "its message has no line the tag could go on",
+};
+
+/**
+ * The line the model reads under the command's output, or null. A commit outside
+ * the project, or one that already names a task, needs nothing said.
+ */
+export function commitStampNote(commit: { sha: string; stamp?: CommitStampReport }): string | null {
+	const stamp = commit.stamp;
+	if (!stamp) return null;
+	const short = commit.sha.slice(0, 7);
+	if (stamp.outcome === "stamped" && stamp.task) {
+		return `DevSpec: Pi added [devspec:${stamp.task}] to the message of commit ${short}, for the one task claimed in this conversation.`;
+	}
+	if (stamp.reason === "outside_project" || stamp.reason === "has_reference") return null;
+	if (stamp.reason === "several_claims") {
+		return `DevSpec: Pi did not add a task tag to commit ${short}: ${stamp.claims} tasks are claimed in this conversation, so it cannot tell which one this commit is for. Write the right task's [devspec:<full-uuid>] into the message yourself.`;
+	}
+	const why = (stamp.reason && REASON_WORDS[stamp.reason]) ?? "its message could not be changed safely";
+	return `DevSpec: Pi did not add [devspec:${stamp.task}] to commit ${short}, because ${why}. If this commit is for that task, write the tag into its message yourself.`;
+}

package/extensions/core/config.ts

@@ -0,0 +1,63 @@
+/**
+ * DevSpec Pi — shared configuration.
+ *
+ * Endpoint, environment variables, and on-disk locations. Everything here is
+ * pure and dependency-free so it loads in any mode (tui / rpc / json / print)
+ * and under `node --test` (erasable TypeScript only).
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * DevSpec's hostnames are split by role: the machine API (MCP) lives on the
+ * `api.` host, human-facing pages (settings, handoff) on the `app.` host, and
+ * the marketing site stays on the bare `devspec.ai` apex. Staging mirrors the
+ * same split on `devspecstaging.com`. Never derive one host from another.
+ */
+
+/** Prod MCP endpoint (stateless Streamable HTTP, POST-only, bearer auth). */
+export const DEFAULT_MCP_URL = "https://api.devspec.ai/api/mcp";
+
+/** Staging MCP endpoint — active development happens here (dev Clerk/Supabase). */
+export const STAGING_MCP_URL = "https://api.devspecstaging.com/api/mcp";
+
+/**
+ * The Agent setup page (`/settings/agents`): where users create, reveal and
+ * revoke their account-wide access token in the DevSpec web app (app host, not
+ * the API). Customer copy links to it by URL rather than naming a menu path.
+ */
+export const AGENTS_SETTINGS_URL = "https://app.devspec.ai/settings/agents";
+export const STAGING_AGENTS_SETTINGS_URL = "https://app.devspecstaging.com/settings/agents";
+
+/** Env var that always wins over the on-disk token store (CI / cloud workers). */
+export const TOKEN_ENV_VAR = "DEVSPEC_MCP_TOKEN";
+
+/** Full endpoint override (any environment). Wins over DEVSPEC_ENV. */
+export const URL_ENV_VAR = "DEVSPEC_MCP_URL";
+
+/** Environment shorthand: "staging" selects the staging endpoint. */
+export const ENV_ENV_VAR = "DEVSPEC_ENV";
+
+/** Pi's config dir — honors PI_CODING_AGENT_DIR like pi itself does. */
+export function agentDir(): string {
+	return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+/** Our private corner of the pi config dir. */
+export function devspecDir(): string {
+	return join(agentDir(), "devspec");
+}
+
+export function mcpUrl(): string {
+	const override = process.env[URL_ENV_VAR];
+	if (override && override.trim()) return override.trim();
+	const env = process.env[ENV_ENV_VAR];
+	if (env && env.trim().toLowerCase() === "staging") return STAGING_MCP_URL;
+	return DEFAULT_MCP_URL;
+}
+
+/** The Agent setup page matching the effective endpoint (for login guidance). */
+export function agentsSettingsUrl(): string {
+	return mcpUrl() === STAGING_MCP_URL ? STAGING_AGENTS_SETTINGS_URL : AGENTS_SETTINGS_URL;
+}

package/extensions/core/connection-context.ts

@@ -0,0 +1,28 @@
+import type { BondState } from './bond-state.ts';
+import { repositoryContextMessage } from './repository-context.ts';
+
+const fields = ['owner_custom_instructions', 'owner_agent_rules', 'project_custom_instructions', 'project_agent_rules'] as const;
+/** Absent means unchanged; null explicitly clears. Never adopt another project's context. */
+export function applyConnectionContext(bond: BondState, value: unknown): BondState {
+	if (!value || typeof value !== 'object' || Array.isArray(value)) return bond;
+	const payload = value as Record<string, unknown>;
+	if (typeof payload.project_id === 'string' && bond.projectId && payload.project_id !== bond.projectId) throw new Error('Connection context belongs to a different project.');
+	const instructions = { ...bond.instructions };
+	if (payload.instructions_unchanged !== true) for (const key of fields) {
+		if (payload[key] === null) delete instructions[key];
+		else if (typeof payload[key] === 'string') instructions[key] = payload[key];
+	}
+	return { ...bond, instructions,
+		...(bond.projectId && Object.hasOwn(payload, 'repository_context') ? {
+			repositoryContext: repositoryContextMessage(payload.repository_context, bond.projectId, bond.projectName),
+		} : {}),
+	};
+}
+
+export const INSTRUCTION_CONTEXT_MESSAGE = 'devspec-instruction-context';
+/** Full immutable rule snapshot. Changes append at the tail, never rewrite the system prefix. */
+export function instructionContextMessage(bond: BondState): string {
+	const instructions = Object.fromEntries(fields.filter(key => key !== 'owner_custom_instructions').map(key => [key,bond.instructions?.[key] ?? null]));
+	const json = JSON.stringify({project_id:bond.projectId ?? null,...instructions},null,2).replaceAll('<','\\u003c').replaceAll('>','\\u003e');
+	return `DevSpec project and owner instruction snapshot. This replaces earlier values of these fields for this project; null means no instruction in that field. Authority and precedence remain defined by devspec://product/implementation-contract.\n<devspec-instruction-tiers>\n${json}\n</devspec-instruction-tiers>`;
+}