gsd-pi 2.76.0-dev.fe143342a → 2.77.0-dev.1d17f366c

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -7,13 +7,17 @@ import { isDbAvailable, getMilestoneSlices, getSliceTasks, type SliceRow } from
 import type { UokGraphNode } from "./contracts.js";
 
 const PLAN_V2_CLARIFY_ROUND_LIMIT = 3;
-const EXECUTION_ENTRY_PHASES: ReadonlySet<Phase> = new Set([
+export const EXECUTION_ENTRY_PHASES: ReadonlySet<Phase> = new Set([
   "executing",
   "summarizing",
   "validating-milestone",
   "completing-milestone",
 ]);
 
+export function isExecutionEntryPhase(phase: Phase): boolean {
+  return EXECUTION_ENTRY_PHASES.has(phase);
+}
+
 export interface PlanV2CompileResult {
   ok: boolean;
   reason?: string;
@@ -38,6 +42,37 @@ function hasFileContent(path: string | null): boolean {
   }
 }
 
+function getArtifactLookupBases(basePath: string): string[] {
+  const bases = [basePath];
+  const projectRoot = process.env.GSD_PROJECT_ROOT;
+  if (projectRoot && projectRoot.trim().length > 0 && projectRoot !== basePath) {
+    bases.push(projectRoot);
+  }
+  return bases;
+}
+
+function hasMilestoneFileContent(
+  basePath: string,
+  milestoneId: string,
+  suffix: string,
+): boolean {
+  const bases = getArtifactLookupBases(basePath);
+  for (const candidateBase of bases) {
+    if (hasFileContent(resolveMilestoneFile(candidateBase, milestoneId, suffix))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function hasFinalizedMilestoneContext(basePath: string, milestoneId: string): boolean {
+  return hasMilestoneFileContent(basePath, milestoneId, "CONTEXT");
+}
+
+export function isMissingFinalizedContextResult(result: PlanV2CompileResult): boolean {
+  return !result.ok && result.finalizedContextIncluded === false;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -48,10 +83,6 @@ function countSliceResearchArtifacts(basePath: string, milestoneId: string, slic
   return count;
 }
 
-function isExecutionEntryPhase(phase: Phase): boolean {
-  return EXECUTION_ENTRY_PHASES.has(phase);
-}
-
 export function compileUnitGraphFromState(basePath: string, state: GSDState): PlanV2CompileResult {
   const mid = state.activeMilestone?.id;
   if (!mid) return { ok: false, reason: "no active milestone" };
@@ -60,9 +91,9 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
   const slices = getMilestoneSlices(mid).sort((a, b) => Number(a.sequence ?? 0) - Number(b.sequence ?? 0));
   const nodes: UokGraphNode[] = [];
   const clarifyRoundLimit = PLAN_V2_CLARIFY_ROUND_LIMIT;
-  const draftContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT-DRAFT"));
-  const finalizedContextIncluded = hasFileContent(resolveMilestoneFile(basePath, mid, "CONTEXT"));
-  const researchSynthesized = hasFileContent(resolveMilestoneFile(basePath, mid, "RESEARCH"))
+  const draftContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT-DRAFT");
+  const finalizedContextIncluded = hasMilestoneFileContent(basePath, mid, "CONTEXT");
+  const researchSynthesized = hasMilestoneFileContent(basePath, mid, "RESEARCH")
     || countSliceResearchArtifacts(basePath, mid, slices) > 0;
 
   if (isExecutionEntryPhase(state.phase) && !finalizedContextIncluded) {

package/src/resources/extensions/gsd/uok/writer.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+import { atomicWriteSync } from "../atomic-write.js";
+import { gsdRoot } from "../paths.js";
+import type { WriteRecord, WriterToken } from "./contracts.js";
+
+interface SequenceState {
+  lastSequence: number;
+  updatedAt: string;
+}
+
+const activeTokens = new Map<string, WriterToken>();
+
+function tokenKey(basePath: string, turnId: string): string {
+  return `${basePath}:${turnId}`;
+}
+
+function sequencePath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-writer-sequence.json");
+}
+
+function readSequenceState(basePath: string): SequenceState {
+  const path = sequencePath(basePath);
+  if (!existsSync(path)) {
+    return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as Partial<SequenceState>;
+    return {
+      lastSequence: Number.isInteger(parsed.lastSequence) ? Number(parsed.lastSequence) : 0,
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date(0).toISOString(),
+    };
+  } catch {
+    return { lastSequence: 0, updatedAt: new Date(0).toISOString() };
+  }
+}
+
+function writeSequenceState(basePath: string, state: SequenceState): void {
+  atomicWriteSync(sequencePath(basePath), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
+export function acquireWriterToken(args: {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  owner?: WriterToken["owner"];
+}): WriterToken {
+  const key = tokenKey(args.basePath, args.turnId);
+  const existing = activeTokens.get(key);
+  if (existing) {
+    throw new Error(`Writer token already active for turn ${args.turnId}`);
+  }
+
+  const token: WriterToken = {
+    tokenId: randomUUID(),
+    traceId: args.traceId,
+    turnId: args.turnId,
+    acquiredAt: new Date().toISOString(),
+    owner: args.owner ?? "uok",
+  };
+  activeTokens.set(key, token);
+  return token;
+}
+
+export function releaseWriterToken(basePath: string, token: WriterToken): void {
+  const key = tokenKey(basePath, token.turnId);
+  const current = activeTokens.get(key);
+  if (current?.tokenId === token.tokenId) {
+    activeTokens.delete(key);
+  }
+}
+
+export function hasActiveWriterToken(basePath: string, turnId: string): boolean {
+  return activeTokens.has(tokenKey(basePath, turnId));
+}
+
+export function nextWriteRecord(args: {
+  basePath: string;
+  token: WriterToken;
+  category: WriteRecord["category"];
+  operation: WriteRecord["operation"];
+  path?: string;
+  metadata?: Record<string, unknown>;
+}): WriteRecord {
+  if (!hasActiveWriterToken(args.basePath, args.token.turnId)) {
+    throw new Error(`Writer token is not active for turn ${args.token.turnId}`);
+  }
+
+  const state = readSequenceState(args.basePath);
+  const sequence = state.lastSequence + 1;
+  const updatedAt = new Date().toISOString();
+  writeSequenceState(args.basePath, { lastSequence: sequence, updatedAt });
+
+  return {
+    writerToken: args.token,
+    sequence: {
+      traceId: args.token.traceId,
+      turnId: args.token.turnId,
+      sequence,
+    },
+    category: args.category,
+    operation: args.operation,
+    path: args.path,
+    ts: updatedAt,
+    metadata: args.metadata,
+  };
+}
+
+export function resetWriterTokensForTests(): void {
+  activeTokens.clear();
+}

package/src/resources/extensions/gsd/workflow-logger.ts

@@ -16,9 +16,17 @@
 // the start of each unit to prevent log bleed between units running in the same
 // Node process.
 
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import {
+  appendFileSync,
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+} from "node:fs";
 import { join } from "node:path";
 
+import { withFileLockSync } from "./file-lock.js";
 import { appendNotification } from "./notification-store.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -58,7 +66,9 @@ export type LogComponent =
   | "memory-embeddings" // Memory layer embedding generation
   | "memory-ingest"     // Memory layer ingestion pipeline
   | "memory-backfill"   // ADR-013: decisions->memories backfill
-  | "context-mode";    // Context-mode exec sandbox and compaction snapshot
+  | "context-mode"     // Context-mode exec sandbox and compaction snapshot
+  | "preflight"        // Clean-root preflight gate at milestone completion
+  | "postUnit";     // Post-unit processing (abandon detection, overrides)
 
 export interface LogEntry {
   ts: string;
@@ -312,8 +322,18 @@ function _push(
     try {
       const auditDir = join(_auditBasePath, ".gsd");
       mkdirSync(auditDir, { recursive: true });
+      const auditPath = join(auditDir, "audit-log.jsonl");
       const sanitized = _sanitizeForAudit(entry);
-      appendFileSync(join(auditDir, "audit-log.jsonl"), JSON.stringify(sanitized) + "\n", "utf-8");
+      // Ensure file exists so proper-lockfile can acquire a lock against it.
+      if (!existsSync(auditPath)) closeSync(openSync(auditPath, "a"));
+      // onLocked: "skip" — never block error logging on lock contention.
+      withFileLockSync(
+        auditPath,
+        () => {
+          appendFileSync(auditPath, JSON.stringify(sanitized) + "\n", "utf-8");
+        },
+        { onLocked: "skip" },
+      );
     } catch (auditErr) {
       // Best-effort — never let audit write failures bubble up
       _writeStderr(`[gsd:audit] failed to persist log entry: ${(auditErr as Error).message}\n`);

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -559,6 +559,7 @@ const SKIP_PATHS = [
   ".gsd/worktrees/",
   ".gsd/runtime/",
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/parallel/",
   ".gsd/journal/",

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -79,6 +79,35 @@ export interface NotifyCtx {
   ) => void;
 }
 
+// ─── Path Helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Worktree marker segment — present in any path produced by worktreePath().
+ * Used to strip the worktree suffix and recover the project root (#3729).
+ */
+const WORKTREE_MARKER = "/.gsd/worktrees/";
+
+/**
+ * Resolve the project root from session path state.
+ *
+ * Prefers `originalBasePath` (always the project root when set), but falls
+ * back to `basePath` when `originalBasePath` is falsy (e.g. fresh AutoSession
+ * with default empty string). If `basePath` itself is inside a worktree
+ * directory (contains `/.gsd/worktrees/`), strip that suffix to recover the
+ * actual project root — preventing double-nested worktree paths (#3729).
+ */
+export function resolveProjectRoot(
+  originalBasePath: string,
+  basePath: string,
+): string {
+  let resolved = originalBasePath || basePath;
+  const markerIdx = resolved.indexOf(WORKTREE_MARKER);
+  if (markerIdx !== -1) {
+    resolved = resolved.slice(0, markerIdx);
+  }
+  return resolved;
+}
+
 // ─── WorktreeResolver ──────────────────────────────────────────────────────
 
 export class WorktreeResolver {
@@ -99,12 +128,12 @@ export class WorktreeResolver {
 
   /** Original project root — always the non-worktree path. */
   get projectRoot(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   /** Path for auto.lock file — same as the old lockBase(). */
   get lockPath(): string {
-    return this.s.originalBasePath || this.s.basePath;
+    return resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
   }
 
   // ── Private Helpers ────────────────────────────────────────────────────
@@ -182,7 +211,10 @@ export class WorktreeResolver {
       return;
     }
 
-    const basePath = this.s.originalBasePath || this.s.basePath;
+    // Resolve the project root for worktree operations via shared helper.
+    // Handles the case where originalBasePath is falsy and basePath is itself
+    // a worktree path — prevents double-nested worktree paths (#3729).
+    const basePath = resolveProjectRoot(this.s.originalBasePath, this.s.basePath);
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
@@ -569,11 +601,13 @@ export class WorktreeResolver {
         }
       }
 
-      // Re-throw MergeConflictError so the auto loop can detect real code
-      // conflicts and stop instead of retrying forever (#2330).
-      if (err instanceof MergeConflictError) {
-        throw err;
-      }
+      // Restore state before re-throwing so callers always get a consistent
+      // session (#4380).
+      this.restoreToProjectRoot();
+      // Re-throw: MergeConflictError stops the auto loop (#2330); non-conflict
+      // errors (permission denied, filesystem failures) must also propagate so
+      // broken states are diagnosable (#4380).
+      throw err;
     }
 
     // Always restore basePath and rebuild — whether merge succeeded or failed
@@ -659,6 +693,8 @@ export class WorktreeResolver {
         error: msg,
       });
       ctx.notify(`Milestone merge failed (branch mode): ${msg}`, "warning");
+      // Re-throw all errors so callers can apply their own recovery logic (#4380).
+      throw err;
     }
   }
 
@@ -681,7 +717,16 @@ export class WorktreeResolver {
       currentMilestoneId,
       nextMilestoneId,
     });
-    this.mergeAndExit(currentMilestoneId, ctx);
+    try {
+      this.mergeAndExit(currentMilestoneId, ctx);
+    } catch (err) {
+      // mergeAndExit emits a warning and restores state when it fails during
+      // merge/cleanup. But if it throws before recovery runs (e.g., in
+      // validateMilestoneId or emitJournalEvent), basePath won't be restored
+      // to projectRoot — re-throw so we don't enter the next milestone with
+      // the current one unmerged.
+      if (this.s.basePath !== this.projectRoot) throw err;
+    }
     this.enterMilestone(nextMilestoneId, ctx);
   }
 }

package/src/resources/extensions/mcp-client/auth.ts

@@ -37,7 +37,18 @@ export type McpHttpAuthConfig = McpHttpAuthHeaders & McpHttpOAuthConfig;
 function resolveEnvValue(value: string): string {
 	return value.replace(
 		/\$\{([^}]+)\}/g,
-		(_match, varName) => process.env[varName] ?? "",
+		(_match, varName) => {
+			const resolved = process.env[varName];
+			if (resolved === undefined || resolved === "") {
+				// eslint-disable-next-line no-console
+				console.warn(
+					`[mcp-client auth] Environment variable "${varName}" referenced in MCP server config is unset. ` +
+					`Requests will go out with a malformed header and the remote server will likely reject them with 401.`,
+				);
+				return "";
+			}
+			return resolved;
+		},
 	);
 }
 

package/src/resources/extensions/mcp-client/index.ts

@@ -11,7 +11,7 @@
  *   mcp_call      — Call a tool on an MCP server (lazy connect)
  */
 
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 import {
 	truncateHead,
 	DEFAULT_MAX_BYTES,
@@ -33,6 +33,7 @@ import type { McpHttpAuthConfig } from "./auth.js";
 interface McpServerConfig {
 	name: string;
 	transport: "stdio" | "http" | "unknown";
+	sourcePath: string;
 	command?: string;
 	args?: string[];
 	env?: Record<string, string>;
@@ -58,8 +59,40 @@ interface ManagedConnection {
 // ─── Connection Manager ───────────────────────────────────────────────────────
 
 const connections = new Map<string, ManagedConnection>();
+const pendingConnections = new Map<string, Promise<Client>>();
 let configCache: McpServerConfig[] | null = null;
 const toolCache = new Map<string, McpToolSchema[]>();
+const trustedStdioServers = new Set<string>();
+
+const CHILD_ENV_ALLOWLIST = new Set([
+	"PATH",
+	"Path",
+	"HOME",
+	"USER",
+	"USERNAME",
+	"USERPROFILE",
+	"SHELL",
+	"TMPDIR",
+	"TEMP",
+	"TMP",
+	"SystemRoot",
+	"WINDIR",
+	"APPDATA",
+	"LOCALAPPDATA",
+	"XDG_CONFIG_HOME",
+	"XDG_CACHE_HOME",
+]);
+
+function stdioTrustKey(config: McpServerConfig): string {
+	return JSON.stringify({
+		name: config.name,
+		sourcePath: config.sourcePath,
+		command: config.command,
+		args: config.args ?? [],
+		cwd: config.cwd,
+		env: config.env ?? {},
+	});
+}
 
 function readConfigs(): McpServerConfig[] {
 	if (configCache) return configCache;
@@ -99,6 +132,7 @@ function readConfigs(): McpServerConfig[] {
 				servers.push({
 					name,
 					transport,
+					sourcePath: configPath,
 					...(hasCommand && {
 						command: config.command as string,
 						args: Array.isArray(config.args) ? (config.args as string[]) : undefined,
@@ -121,6 +155,54 @@ function readConfigs(): McpServerConfig[] {
 	return servers;
 }
 
+export function _buildMcpChildEnvForTest(configEnv: Record<string, string> | undefined): Record<string, string> {
+	const childEnv: Record<string, string> = {};
+	for (const key of CHILD_ENV_ALLOWLIST) {
+		const value = process.env[key];
+		if (typeof value === "string") childEnv[key] = value;
+	}
+	return {
+		...childEnv,
+		...(configEnv ? resolveEnv(configEnv) : {}),
+	};
+}
+
+export function _buildMcpTrustConfirmOptionsForTest(signal?: AbortSignal): { timeout: number; signal?: AbortSignal } {
+	return signal ? { timeout: 120_000, signal } : { timeout: 120_000 };
+}
+
+async function assertTrustedStdioServer(
+	config: McpServerConfig,
+	ctx?: ExtensionContext,
+	signal?: AbortSignal,
+): Promise<string | undefined> {
+	if (config.transport !== "stdio") return undefined;
+	const trustKey = stdioTrustKey(config);
+	if (trustedStdioServers.has(trustKey)) return undefined;
+
+	if (!ctx?.hasUI) {
+		throw new Error(
+			`MCP server "${config.name}" is a project-local stdio command from ${config.sourcePath}. ` +
+			"Run this from an interactive GSD session and approve the server before use.",
+		);
+	}
+
+	const commandLine = [config.command, ...(config.args ?? [])].filter(Boolean).join(" ");
+	const envKeys = Object.keys(config.env ?? {});
+	const envSummary = envKeys.length > 0
+		? `\n\nConfigured environment keys: ${envKeys.join(", ")}`
+		: "\n\nNo explicit environment keys configured.";
+	const approved = await ctx.ui.confirm(
+		`Trust MCP server "${config.name}"?`,
+		`Project config ${config.sourcePath} wants to start:\n\n${commandLine}${envSummary}\n\nOnly approve MCP servers you trust.`,
+		_buildMcpTrustConfirmOptionsForTest(signal),
+	);
+	if (!approved) {
+		throw new Error(`MCP server "${config.name}" was not approved by the user.`);
+	}
+	return trustKey;
+}
+
 function getServerConfig(name: string): McpServerConfig | undefined {
 	const trimmed = name.trim();
 	return readConfigs().find((s) =>
@@ -145,7 +227,7 @@ function resolveEnv(env: Record<string, string>): Record<string, string> {
 	return resolved;
 }
 
-async function getOrConnect(name: string, signal?: AbortSignal): Promise<Client> {
+async function getOrConnect(name: string, signal?: AbortSignal, ctx?: ExtensionContext): Promise<Client> {
 	const config = getServerConfig(name);
 	if (!config) throw new Error(`Unknown MCP server: "${name}". Use mcp_servers to list available servers.`);
 
@@ -154,14 +236,29 @@ async function getOrConnect(name: string, signal?: AbortSignal): Promise<Client>
 	const existing = connections.get(config.name);
 	if (existing) return existing.client;
 
+	const pending = pendingConnections.get(config.name);
+	if (pending) return pending;
+
+	const connectionPromise = connectServer(config, signal, ctx);
+	pendingConnections.set(config.name, connectionPromise);
+	try {
+		return await connectionPromise;
+	} finally {
+		pendingConnections.delete(config.name);
+	}
+}
+
+async function connectServer(config: McpServerConfig, signal?: AbortSignal, ctx?: ExtensionContext): Promise<Client> {
 	const client = new Client({ name: "gsd", version: "1.0.0" });
 	let transport: StdioClientTransport | StreamableHTTPClientTransport;
+	let approvedTrustKey: string | undefined;
 
 	if (config.transport === "stdio" && config.command) {
+		approvedTrustKey = await assertTrustedStdioServer(config, ctx, signal);
 		transport = new StdioClientTransport({
 			command: config.command,
 			args: config.args,
-			env: config.env ? { ...process.env, ...resolveEnv(config.env) } as Record<string, string> : undefined,
+			env: _buildMcpChildEnvForTest(config.env),
 			cwd: config.cwd,
 			stderr: "pipe",
 		});
@@ -179,9 +276,24 @@ async function getOrConnect(name: string, signal?: AbortSignal): Promise<Client>
 		throw new Error(`Server "${config.name}" has unsupported transport: ${config.transport}`);
 	}
 
-	await client.connect(transport, { signal, timeout: 30000 });
-	connections.set(config.name, { client, transport });
-	return client;
+	try {
+		await client.connect(transport, { signal, timeout: 30000 });
+		if (approvedTrustKey) trustedStdioServers.add(approvedTrustKey);
+		connections.set(config.name, { client, transport });
+		return client;
+	} catch (err) {
+		try {
+			await transport.close();
+		} catch {
+			// Best-effort cleanup after a failed or aborted connection attempt.
+		}
+		try {
+			await client.close();
+		} catch {
+			// Best-effort cleanup after a failed or aborted connection attempt.
+		}
+		throw err;
+	}
 }
 
 async function closeAll(): Promise<void> {
@@ -191,9 +303,16 @@ async function closeAll(): Promise<void> {
 		} catch {
 			// Best-effort cleanup
 		}
+		try {
+			await conn.transport.close();
+		} catch {
+			// Best-effort cleanup
+		}
 		connections.delete(name);
 	});
 	await Promise.allSettled(closing);
+	pendingConnections.clear();
+	trustedStdioServers.clear();
 	toolCache.clear();
 }
 
@@ -331,7 +450,7 @@ export default function (pi: ExtensionAPI) {
 			}),
 		}),
 
-		async execute(_id, params, signal) {
+		async execute(_id, params, signal, _onUpdate, ctx) {
 			try {
 				// Return cached tools if available
 				const cached = toolCache.get(params.server);
@@ -348,7 +467,7 @@ export default function (pi: ExtensionAPI) {
 					};
 				}
 
-				const client = await getOrConnect(params.server, signal);
+				const client = await getOrConnect(params.server, signal, ctx);
 				const result = await client.listTools(undefined, { signal, timeout: 30000 });
 				const tools: McpToolSchema[] = (result.tools ?? []).map((t) => ({
 					name: t.name,
@@ -423,9 +542,9 @@ export default function (pi: ExtensionAPI) {
 			),
 		}),
 
-		async execute(_id, params, signal) {
+		async execute(_id, params, signal, _onUpdate, ctx) {
 			try {
-				const client = await getOrConnect(params.server, signal);
+				const client = await getOrConnect(params.server, signal, ctx);
 				const result = await client.callTool(
 					{ name: params.tool, arguments: params.args ?? {} },
 					undefined,

package/src/resources/extensions/shared/cmux-events.ts

@@ -0,0 +1,59 @@
+// GSD-2 — Shared cmux event channel contracts
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+/**
+ * Neutral event channel module for gsd<->cmux IPC.
+ * Both gsd and cmux import from here — neither imports the other directly.
+ * Per ADR-006 Phase 0: event-based decoupling.
+ */
+
+export const CMUX_CHANNELS = {
+  SIDEBAR: "cmux:sidebar",
+  LOG: "cmux:log",
+  LIFECYCLE: "cmux:lifecycle",
+} as const;
+
+/** Migrated from cmux/index.ts (D-07) — shared by both gsd and cmux. */
+export type CmuxLogLevel = "info" | "progress" | "success" | "warning" | "error";
+
+// ── Structural types (D-05): cmux defines only what it needs ──
+
+export interface CmuxPreferencesInput {
+  cmux?: {
+    enabled?: boolean;
+    notifications?: boolean;
+    sidebar?: boolean;
+    splits?: boolean;
+    browser?: boolean;
+  };
+}
+
+export interface CmuxStateInput {
+  phase: string;
+  activeMilestone?: { id: string };
+  activeSlice?: { id: string };
+  activeTask?: { id: string };
+  progress?: {
+    milestones: { done: number; total: number };
+    slices?: { done: number; total: number };
+    tasks?: { done: number; total: number };
+  };
+}
+
+// ── Event payloads ──
+
+export interface CmuxSidebarEvent {
+  action: "sync" | "clear";
+  preferences?: CmuxPreferencesInput;
+  state?: CmuxStateInput;
+}
+
+export interface CmuxLogEvent {
+  preferences?: CmuxPreferencesInput;
+  message: string;
+  level: CmuxLogLevel;
+}
+
+export interface CmuxLifecycleEvent {
+  action: "markPromptShown";
+}

package/src/resources/extensions/shared/rtk-session-stats.ts

@@ -2,7 +2,6 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { gsdRoot } from "../gsd/paths.js";
 import { formatTokenCount } from "./format-utils.js";
 import { buildRtkEnv, isRtkEnabled, resolveRtkBinaryPath } from "./rtk.js";
 
@@ -46,7 +45,7 @@ interface BaselineStore {
 let cachedSummary: { at: number; binaryPath: string; summary: RtkGainSummary | null } | null = null;
 
 function getRuntimeDir(basePath: string): string {
-  return join(gsdRoot(basePath), "runtime");
+  return join(basePath, ".gsd", "runtime");
 }
 
 function getBaselinesPath(basePath: string): string {