@devspecai/pi-plugin 0.0.0-stage → 0.10.3

package/extensions/core/work-state.ts

@@ -0,0 +1,179 @@
+/**
+ * Process-local observations used for status and one advisory provenance nudge.
+ *
+ * This is deliberately not authority. A server-confirmed claim is useful
+ * coordination context, but no filesystem, shell, commit, push, or completion
+ * path asks this store for permission. globalThis joins Pi's separate jiti
+ * module graphs without persisting state across processes.
+ */
+
+export interface ObservedClaim {
+	sessionId: string;
+	taskId: string;
+	projectId?: string;
+	observedAt: number;
+}
+
+interface WorkStateStore {
+	claims: Map<string, ObservedClaim>;
+	nudgedProjects: Set<string>;
+}
+
+const WORK_STATE_KEY = Symbol.for("devspec.pi.work-state.v2");
+const FULL_TASK_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const TERMINAL_WORK_VERBS = new Set(["record_implementation", "release_work_item", "fail_work_item"]);
+const MAX_OBSERVED_CLAIMS = 100;
+
+function store(): WorkStateStore {
+	const root = globalThis as typeof globalThis & { [WORK_STATE_KEY]?: WorkStateStore };
+	const current = root[WORK_STATE_KEY];
+	if (!current || !(current.claims instanceof Map) || !(current.nudgedProjects instanceof Set)) {
+		root[WORK_STATE_KEY] = { claims: new Map(), nudgedProjects: new Set() };
+	}
+	return root[WORK_STATE_KEY]!;
+}
+
+function exactNonEmpty(value: unknown): string | undefined {
+	return typeof value === "string" && value.length > 0 && value === value.trim() ? value : undefined;
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+	return value !== null && typeof value === "object" && !Array.isArray(value)
+		? value as Record<string, unknown>
+		: null;
+}
+
+function resultDetails(value: unknown): Record<string, unknown> | null {
+	const root = record(value);
+	if (!root) return null;
+	return record(root.details) ?? root;
+}
+
+function responseProjectId(details: Record<string, unknown>): string | undefined {
+	const direct = exactNonEmpty(details.project_id);
+	if (direct) return direct;
+	const task = record(details.task);
+	const item = record(details.item);
+	return exactNonEmpty(task?.project_id) ??
+		exactNonEmpty(item?.project_id) ??
+		exactNonEmpty(record(item?.task)?.project_id);
+}
+
+function responseTaskId(details: Record<string, unknown>): string | undefined {
+	const direct = exactNonEmpty(details.task_id) ?? exactNonEmpty(details.id);
+	if (direct) return direct;
+	const task = record(details.task);
+	const item = record(details.item);
+	return exactNonEmpty(task?.id) ??
+		exactNonEmpty(item?.id) ??
+		exactNonEmpty(record(item?.task)?.id);
+}
+
+function matchingResponseItemId(args: Record<string, unknown>, details: Record<string, unknown>): string | undefined {
+	const requested = exactNonEmpty(args.task_id);
+	const confirmed = responseTaskId(details);
+	return requested && FULL_TASK_ID.test(requested) && confirmed === requested ? confirmed : undefined;
+}
+
+function hasNegativeMarker(details: Record<string, unknown>): boolean {
+	return details.error != null || details.isError === true || details.ok === false ||
+		details.success === false || details.claimed === false || details.blocked === true ||
+		details.is_blocked === true;
+}
+
+function terminalSucceeded(name: string, details: Record<string, unknown>): boolean {
+	if (hasNegativeMarker(details)) return false;
+	if (name === "record_implementation") {
+		return details.implementation_recorded === true || details.lifecycle === "implemented";
+	}
+	if (name === "release_work_item") {
+		return details.success === true && (
+			exactNonEmpty(details.released_at) !== undefined || typeof details.was_claimed === "boolean"
+		);
+	}
+	if (name === "fail_work_item") {
+		return details.failed === true || details.agent_activity === "failed";
+	}
+	return false;
+}
+
+function claimKey(sessionId: string, taskId: string): string {
+	return `${sessionId}\0${taskId}`;
+}
+
+export function listObservedClaims(sessionId?: string): ObservedClaim[] {
+	return [...store().claims.values()]
+		.filter((claim) => !sessionId || claim.sessionId === sessionId)
+		.map((claim) => ({ ...claim }));
+}
+
+export function hasObservedClaim(sessionId: string, projectId?: string): boolean {
+	return listObservedClaims(sessionId).some((claim) => !projectId || claim.projectId === projectId);
+}
+
+/**
+ * Consume only structured successful DevSpec results. The boolean means a claim
+ * was newly observed and is used for footer display; it grants no permission.
+ */
+export function observeSuccessfulWorkResult(
+	name: string,
+	args: Record<string, unknown>,
+	result: unknown,
+	sessionId: string,
+	projectId?: string,
+): boolean {
+	const exactSessionId = exactNonEmpty(sessionId);
+	const details = resultDetails(result);
+	if (!exactSessionId || !details) return false;
+	const taskId = matchingResponseItemId(args, details);
+	if (!taskId) return false;
+	const resolvedProjectId = exactNonEmpty(projectId) ?? responseProjectId(details);
+
+	if (name === "claim_work_item") {
+		if (details.claim_success !== true || hasNegativeMarker(details)) return false;
+		const current = store();
+		current.claims.set(claimKey(exactSessionId, taskId), {
+			sessionId: exactSessionId,
+			taskId,
+			...(resolvedProjectId ? { projectId: resolvedProjectId } : {}),
+			observedAt: Date.now(),
+		});
+		while (current.claims.size > MAX_OBSERVED_CLAIMS) {
+			const oldest = current.claims.keys().next().value;
+			if (typeof oldest !== "string") break;
+			current.claims.delete(oldest);
+		}
+		return true;
+	}
+
+	if (!TERMINAL_WORK_VERBS.has(name) || !terminalSucceeded(name, details)) return false;
+	store().claims.delete(claimKey(exactSessionId, taskId));
+	return false;
+}
+
+/** Returns true exactly once per Pi session and explicit project association. */
+export function markProjectNudged(sessionId: string, projectId: string): boolean {
+	const exactSessionId = exactNonEmpty(sessionId);
+	const exactProjectId = exactNonEmpty(projectId);
+	if (!exactSessionId || !exactProjectId) return false;
+	const key = `${exactSessionId}\0${exactProjectId}`;
+	const current = store();
+	if (current.nudgedProjects.has(key)) return false;
+	// Session ids are unique and /reload stays in the same process. Retaining the
+	// spent key is what makes "at most one" absolute for that session/project.
+	current.nudgedProjects.add(key);
+	return true;
+}
+
+export function unmarkProjectNudged(sessionId: string, projectId: string): void {
+	const exactSessionId = exactNonEmpty(sessionId);
+	const exactProjectId = exactNonEmpty(projectId);
+	if (!exactSessionId || !exactProjectId) return;
+	store().nudgedProjects.delete(`${exactSessionId}\0${exactProjectId}`);
+}
+
+export function resetWorkStateForTests(): void {
+	const current = store();
+	current.claims.clear();
+	current.nudgedProjects.clear();
+}

package/extensions/devspec-adapter-guard.ts

@@ -0,0 +1,106 @@
+/** Prevent a second DevSpec connection without touching another host's MCP configuration. */
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	getAdapterGuardState, recordAdapterGuard, toolsToDeactivate, isAdapterSource,
+	SUPPRESSION_NOTICE, SUPPRESSION_AGENT_GUIDANCE, type DevspecServerHit,
+} from "./core/adapter-overlap.ts";
+import { configPaths, migrateLegacyOverlay, disableEffectiveNativeDuplicates, disableAdapterDuplicates, type AdapterConfigApi } from "./core/mcp-config-guard.ts";
+import { mcpUrl } from "./core/config.ts";
+import { debugRemote } from "./core/debug.ts";
+
+export default function (pi: ExtensionAPI) {
+	let explained = false;
+	let changed = false;
+	let failed = false;
+	let hits: DevspecServerHit[] = [];
+	let nativeHits: DevspecServerHit[] = [];
+	let adapterHits: DevspecServerHit[] = [];
+	function duplicateTools() {
+		if (!nativeHits.length && !adapterHits.length) return [];
+		const tools = pi.getAllTools();
+		return [
+			...toolsToDeactivate(tools.filter((tool) => tool.sourceInfo?.path === "builtin:mcp"), nativeHits.map((hit) => hit.name)),
+			...toolsToDeactivate(tools.filter((tool) => isAdapterSource(tool.sourceInfo)), adapterHits.map((hit) => hit.name)),
+		];
+	}
+
+	function deactivate(): void {
+		const names = new Set(duplicateTools());
+		// Config preflight prevents first registration. This also removes cached adapter
+		// declarations on the migration run; never overwrite another extension's tools.
+		const active = pi.getActiveTools();
+		const next = active.filter((name) => !names.has(name));
+		if (next.length !== active.length) pi.setActiveTools(next);
+	}
+
+	async function prepare(ctx: ExtensionContext): Promise<void> {
+		changed = false; failed = false; hits = []; nativeHits = []; adapterHits = [];
+		const trusted = ctx.isProjectTrusted();
+		try {
+			const paths = configPaths(getAgentDir(), ctx.cwd, trusted);
+			for (const path of paths) changed = migrateLegacyOverlay(path.native, path.adapter) || changed;
+			if (pi.getCommands().some((command) => command.name === "mcp" && command.sourceInfo?.path === "builtin:mcp")) {
+				const native = disableEffectiveNativeDuplicates(paths.map((path) => path.native), mcpUrl());
+				nativeHits = native.hits; hits.push(...native.hits); changed = native.changed || changed;
+			}
+			// Only consult shared/Claude configurations when the adapter is actually loaded.
+			// Resolve its PUBLIC config export from the loaded extension's own location,
+			// not our dependency graph and not a guessed global npm installation.
+			const adapter = pi.getCommands().find((command) => command.name === "mcp-adapter" || (command.name === "mcp" && isAdapterSource(command.sourceInfo)));
+			if (adapter && trusted) {
+				const source = adapter.sourceInfo?.path;
+				if (!source) throw new Error("Adapter source unavailable");
+				const entry = createRequire(source).resolve("pi-mcp-adapter/config");
+				const api = await import(pathToFileURL(entry).href) as AdapterConfigApi;
+				const flag = pi.getFlag("mcp-config");
+				const result = disableAdapterDuplicates(api, ctx.cwd, mcpUrl(), typeof flag === "string" ? flag : undefined);
+				adapterHits = result.hits; hits.push(...result.hits); changed = result.changed || changed;
+			}
+		} catch (error) {
+			failed = true;
+			// Config/error text can contain credentials. Never log it.
+			debugRemote("adapter guard failed", { errorPresent: Boolean(error) });
+		}
+		recordAdapterGuard({ suppressed: hits, persisted: !failed, overlayPath: null });
+	}
+
+	// Pi loads user extensions before its built-in MCP extension. Prepare only
+	// after project trust; never inspect a project's configuration during factory load.
+	pi.on("session_start", async (_event, ctx) => {
+		explained = false;
+		listenForAdapterCalls();
+		await prepare(ctx);
+		deactivate();
+		if (failed) ctx.ui.notify("DevSpec could not check duplicate MCP settings. Review Pi’s /mcp settings and any conflicting or malformed MCP files. If you use pi-mcp-adapter, update it to 4.0 or later, then reload. No shared MCP configuration was changed.", "warning");
+		else if (changed && ctx.hasUI && ctx.mode === "tui") {
+			ctx.ui.notify(hits.length ? SUPPRESSION_NOTICE : "Updated legacy Pi MCP settings. Shared MCP configuration and other agents are unchanged.", "info");
+		}
+		changed = false;
+	});
+	// An adapter loaded before us can already have cached registrations/connections.
+	// Block its resolved calls (including proxy/script routes), not just declarations.
+	let unsubscribe: (() => void) | undefined;
+	function listenForAdapterCalls() {
+		unsubscribe ??= pi.events.on("pi-mcp-adapter:tool-approval-request", (raw: unknown) => {
+			const request = raw as { serverName?: string; claim?: (handler: () => string) => boolean };
+			if (adapterHits.some((hit) => hit.name === request?.serverName) && typeof request.claim === "function") request.claim(() => "deny");
+		});
+	}
+	pi.on("session_shutdown", async () => { unsubscribe?.(); unsubscribe = undefined; });
+	pi.on("tool_call", async (event) => {
+		const names = duplicateTools().filter((name) => name === event.toolName);
+		const resource = ["read_mcp_resource", "list_mcp_resources", "list_mcp_resource_templates"].includes(event.toolName);
+		if (names.length || (resource && nativeHits.some((hit) => hit.name === (event.input as Record<string, unknown>).server))) {
+			return { block: true, reason: "Use the native DevSpec tools instead of the duplicate MCP connection." };
+		}
+	});
+	pi.on("tool_result", async () => { deactivate(); });
+	pi.on("before_agent_start", async () => {
+		deactivate();
+		if (explained || getAdapterGuardState().suppressed.length === 0) return;
+		explained = true;
+		return { message: { customType: "devspec-mcp-guard", content: SUPPRESSION_AGENT_GUIDANCE, display: false } };
+	});
+}

package/extensions/devspec-auth.ts

@@ -0,0 +1,191 @@
+/**
+ * DevSpec Pi — authentication extension.
+ *
+ * Commands:
+ *   /devspec.login [token]   — verify + store a token (paste from DevSpec's
+ *                              Agent setup page), or use DEVSPEC_MCP_TOKEN
+ *   /devspec.logout          — remove the stored token
+ *   /devspec.status          — show connection state
+ *
+ * On session start: resolves the token, shows connection state in the footer,
+ * and verifies once per process (never on a timer — rate budget matters).
+ *
+ * Headless (print/json modes): no prompts, no status line; login explains the
+ * env-var path instead. See VISION.md principle 2 (headless-first).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAdapterGuardState, SUPPRESSION_NOTICE } from "./core/adapter-overlap.ts";
+import { clearAuth, resolveEndpoint, resolveToken, saveAuth } from "./core/auth-store.ts";
+import { agentsSettingsUrl, mcpUrl, TOKEN_ENV_VAR } from "./core/config.ts";
+import { DevspecAuthError, resetClientCache, verifyToken } from "./core/client.ts";
+import { unwrapMcpResult } from "./core/result.ts";
+
+const STATUS_KEY = "devspec";
+
+/** Process-local verification state — verify at most once per process. */
+let verifiedPrincipal: string | null = null;
+let verifyAttempted = false;
+let verifiedConnection = false;
+
+function setStatus(ctx: ExtensionContext, text: string | undefined): void {
+	if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, text);
+}
+
+function readablePrincipal(value: unknown): string | null {
+	if (typeof value !== "string") return null;
+	const name = value.trim();
+	// Identity is display data, not response syntax or terminal control output.
+	// Do not impose a length cap or silently crop a person's name (6673868e).
+	if (!name || /^[{\[]/.test(name) || /[\u0000-\u001f\u007f-\u009f]/.test(name)) return null;
+	return name;
+}
+
+/** Only structured identity fields, never an arbitrary first response line. */
+export function principalFrom(result: unknown): string | null {
+	const { details, isError } = unwrapMcpResult(result);
+	if (isError) return null;
+	if (details && typeof details === "object") {
+		const d = details as Record<string, unknown>;
+		// connected_as is verify_agent_connection's current wire field. Keep the
+		// explicit older identity shapes, but never fall back to its message text.
+		for (const key of ["connected_as", "name", "user_name", "display_name", "email", "principal"]) {
+			const name = readablePrincipal(d[key]);
+			if (name) return name;
+		}
+		if (details && typeof (d.user as unknown) === "object" && d.user !== null) {
+			const u = d.user as Record<string, unknown>;
+			return readablePrincipal(u.name) ?? readablePrincipal(u.email);
+		}
+	}
+	return null;
+}
+
+async function doLogin(token: string, ctx: ExtensionContext): Promise<boolean> {
+	try {
+		const result = await verifyToken(token);
+		const { isError, text } = unwrapMcpResult(result);
+		if (isError) {
+			ctx.ui.notify(`DevSpec login failed: ${text}`, "error");
+			return false;
+		}
+		const principal = principalFrom(result);
+		verifiedPrincipal = principal;
+		verifyAttempted = true;
+		verifiedConnection = true;
+		await saveAuth({ token, url: mcpUrl(), principal: principal ?? undefined, verifiedAt: new Date().toISOString() });
+		setStatus(ctx, undefined); // Successful identity is available in /devspec.status, not the footer.
+		const extra = getAdapterGuardState().suppressed.length > 0 ? ` ${SUPPRESSION_NOTICE}` : "";
+		ctx.ui.notify(`Connected to DevSpec${principal ? ` as ${principal}` : ""}.${extra}`, "info");
+		return true;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		ctx.ui.notify(`DevSpec login failed: ${message}`, "error");
+		return false;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("devspec.login", {
+		description: `Connect to DevSpec. Paste an access token from ${agentsSettingsUrl()} (or set ${TOKEN_ENV_VAR}).`,
+		handler: async (args, ctx) => {
+			const envToken = process.env[TOKEN_ENV_VAR];
+			let token = args.trim();
+
+			if (!token && envToken) {
+				token = envToken.trim();
+				ctx.ui.notify(`Using token from ${TOKEN_ENV_VAR}.`, "info");
+			}
+
+			if (!token) {
+				if (!ctx.hasUI) {
+					// Headless: no prompt possible. Tell the operator the env path.
+					ctx.ui.notify(
+						`DevSpec login: set ${TOKEN_ENV_VAR} (mint one at ${agentsSettingsUrl()}) and re-run.`,
+						"warning",
+					);
+					return;
+				}
+				const entered = await ctx.ui.input(
+					"Connect to DevSpec",
+					`Paste an access token from ${agentsSettingsUrl()}`,
+				);
+				token = (entered ?? "").trim();
+				if (!token) {
+					ctx.ui.notify("DevSpec login cancelled.", "info");
+					return;
+				}
+			}
+
+			await doLogin(token, ctx);
+		},
+	});
+
+	pi.registerCommand("devspec.logout", {
+		description: "Remove the stored DevSpec token from this machine.",
+		handler: async (_args, ctx) => {
+			await clearAuth();
+			resetClientCache();
+			verifiedPrincipal = null;
+			verifyAttempted = false;
+			verifiedConnection = false;
+			setStatus(ctx, undefined);
+			ctx.ui.notify(
+				`DevSpec token removed.${process.env[TOKEN_ENV_VAR] ? ` Note: ${TOKEN_ENV_VAR} is still set in the environment.` : ""}`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("devspec.status", {
+		description: "Show DevSpec connection state (token source, principal, endpoint).",
+		handler: async (_args, ctx) => {
+			const resolved = await resolveToken();
+			if (!resolved) {
+				ctx.ui.notify(
+					`DevSpec: not connected. Run /devspec.login or set ${TOKEN_ENV_VAR}. Tokens: ${agentsSettingsUrl()}`,
+					"warning",
+				);
+				return;
+			}
+			const who = verifiedPrincipal ?? (verifiedConnection ? "connected" : "not verified this session");
+			const endpoint = await resolveEndpoint();
+			ctx.ui.notify(
+				`DevSpec: token from ${resolved.source === "env" ? TOKEN_ENV_VAR : "login store"} · ${who} · ${endpoint}`,
+				"info",
+			);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const resolved = await resolveToken();
+		if (!resolved) {
+			setStatus(ctx, undefined);
+			if (ctx.hasUI && ctx.mode === "tui") {
+				ctx.ui.notify(`DevSpec: not connected — /devspec.login (tokens: ${agentsSettingsUrl()})`, "warning");
+			}
+			return;
+		}
+
+		setStatus(ctx, "DevSpec: …");
+
+		// Verify once per process, in the background — never block startup,
+		// never on a timer (the per-token rate budget is shared across plugins).
+		if (!verifyAttempted) {
+			verifyAttempted = true;
+			void verifyToken(resolved.token)
+				.then((result) => {
+					const { isError } = unwrapMcpResult(result);
+					if (isError) throw new DevspecAuthError("verify returned error");
+					verifiedPrincipal = principalFrom(result);
+					verifiedConnection = true;
+					setStatus(ctx, undefined);
+				})
+				.catch(() => {
+					setStatus(ctx, "DevSpec: offline?");
+				});
+		} else {
+			setStatus(ctx, undefined);
+		}
+	});
+}

package/extensions/devspec-brand.ts

@@ -0,0 +1,140 @@
+/**
+ * DevSpec Pi — brand header.
+ *
+ * Shows the DevSpec duck when pi launches (TUI only; headless modes never
+ * render a header). Toggle with /devspec.logo — persisted in
+ * <pi-agent-dir>/devspec/brand.json.
+ *
+ * The duck itself lives in core/duck.ts. This module only lays it out: the
+ * wordmark sits beside the mark when there is room for a lockup, drops below it
+ * when there isn't, and the mark is dropped entirely on a terminal too narrow
+ * to hold it — art that wraps looks worse than no art.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { VERSION } from "@earendil-works/pi-coding-agent";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { devspecDir } from "./core/config.ts";
+import { HEIGHT, renderDuck, WIDTH } from "./core/duck.ts";
+
+const TEAL = "\x1b[38;2;45;212;191m"; // brightened #0F766E brand teal for terminal
+const DIM = "\x1b[38;2;130;130;130m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+
+/** Columns between the mark and the wordmark in the side-by-side lockup. */
+const GAP = "  ";
+
+/**
+ * Approved terminal adaptation of the public brand family (de447cb7).
+ * Keep it short: its length sets the width at which the tagline can sit
+ * beside the mark. Narrower terminals retain the existing name-only fallback.
+ */
+export const TAGLINE = "Your team’s knowledge, where you build.";
+
+/**
+ * Pick the first rendering whose plain text fits `available` columns, or "" if
+ * none does. Each candidate is [rendered-with-colour, plain-for-measuring].
+ */
+function fit(candidates: readonly (readonly [string, string])[], available: number): string {
+	for (const [rendered, plain] of candidates) {
+		if (plain.length <= available) return rendered;
+	}
+	return "";
+}
+
+/**
+ * Wordmark + subtitle, each trimmed to what fits in `available` columns. Detail
+ * is shed longest-first — the tagline goes before the name, the pi version
+ * before the help hint — and a line that cannot fit at all comes back empty for
+ * the caller to drop.
+ */
+function textLines(available: number): [string, string] {
+	const wordmark = fit(
+		[
+			[`${TEAL}${BOLD}DevSpec${RESET}${DIM} · ${TAGLINE}${RESET}`, `DevSpec · ${TAGLINE}`],
+			[`${TEAL}${BOLD}DevSpec${RESET}`, "DevSpec"],
+		],
+		available,
+	);
+	const subtitle = fit(
+		[
+			[`${DIM}on pi v${VERSION} · /devspec.help${RESET}`, `on pi v${VERSION} · /devspec.help`],
+			[`${DIM}/devspec.help${RESET}`, "/devspec.help"],
+		],
+		available,
+	);
+	return [wordmark, subtitle];
+}
+
+/** Vertically centre the two text lines against the mark. */
+const TEXT_ROW = Math.max(0, Math.floor((HEIGHT - 2) / 2));
+
+export function renderHeader(width: number): string[] {
+	if (width < WIDTH) {
+		return [...textLines(width).filter(Boolean), ""];
+	}
+
+	const lines = renderDuck();
+	const beside = Math.max(0, width - WIDTH - GAP.length);
+	const [wordmark, subtitle] = textLines(beside);
+
+	// Lockup: wordmark beside the mark, but only if the name itself fits there.
+	if (wordmark) {
+		lines[TEXT_ROW] = `${lines[TEXT_ROW]}${GAP}${wordmark}`;
+		if (subtitle) lines[TEXT_ROW + 1] = `${lines[TEXT_ROW + 1]}${GAP}${subtitle}`;
+		return [...lines, ""];
+	}
+
+	return [...lines, ...textLines(width).filter(Boolean), ""];
+}
+
+function brandFilePath(): string {
+	return join(devspecDir(), "brand.json");
+}
+
+async function loadBrandPref(): Promise<boolean> {
+	try {
+		const raw = JSON.parse(await readFile(brandFilePath(), "utf8"));
+		return raw.showHeader !== false; // default: show
+	} catch {
+		return true;
+	}
+}
+
+async function saveBrandPref(showHeader: boolean): Promise<void> {
+	const { mkdir } = await import("node:fs/promises");
+	await mkdir(devspecDir(), { recursive: true });
+	await writeFile(brandFilePath(), JSON.stringify({ showHeader }) + "\n");
+}
+
+function applyHeader(ctx: ExtensionContext, show: boolean): void {
+	if (ctx.mode !== "tui") return;
+	if (!show) {
+		ctx.ui.setHeader(undefined);
+		return;
+	}
+	ctx.ui.setHeader((_tui, _theme) => ({
+		render(width: number): string[] {
+			return renderHeader(width);
+		},
+		invalidate() {},
+	}));
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", async (_event, ctx) => {
+		applyHeader(ctx, await loadBrandPref());
+	});
+
+	pi.registerCommand("devspec.logo", {
+		description: "Toggle the DevSpec duck header on startup.",
+		handler: async (_args, ctx) => {
+			const next = !(await loadBrandPref());
+			await saveBrandPref(next);
+			applyHeader(ctx, next);
+			ctx.ui.notify(`DevSpec header ${next ? "on" : "off"}.`, "info");
+		},
+	});
+}