@jmoyers/harness 0.1.10 → 0.1.11

package/README.md

@@ -11,7 +11,7 @@ It is built for people who want to move faster than a single chat window: implem
 - Long-running work survives reconnects through a detached gateway.
 - Gateway control is resilient: lifecycle operations are lock-serialized per session, and missing stale records can be recovered automatically.
 - Fast left-rail navigation with automatic, readable thread titles.
-- Built-in GitHub PR actions (`Open PR` / `Create PR`) from inside Harness.
+- Built-in GitHub actions (`Open GitHub`, `Show My Open Pull Requests`, `Open PR`, `Create PR`) from inside Harness.
 
 ## Demo
 
@@ -58,13 +58,17 @@ For restart/load diagnostics, use a named session with a non-default gateway por
 - Thread-scoped command palette (`[+ thread]`) can launch/install supported agent CLIs per project.
 - Critique review actions are available from the global palette and run in a terminal thread.
 - `ctrl+g` opens the project’s critique thread (or creates one if needed).
+- `ctrl` and `cmd` shortcut chords are mirrored in both directions when your terminal/OS does not reserve the combination.
 - Theme selection is built in (`Set a Theme`) with OpenCode-compatible presets and live preview.
-- PR actions use either `GITHUB_TOKEN` or an authenticated `gh` CLI session.
+- API keys can be set directly from `ctrl+p` / `cmd+p` (`Set Anthropic API Key`, `Set OpenAI API Key`), with overwrite warning and paste-friendly entry.
+- `Create PR` uses either `GITHUB_TOKEN` or an authenticated `gh` CLI session.
 
 ## Configuration
 
 Runtime behavior is controlled by `harness.config.jsonc`.
 
+When upgrading from a workspace-local `.harness`, Harness automatically migrates legacy config into the global config location if that global config is still uninitialized (missing, empty, or default template), then removes stale local `.harness` folders once migration targets are confirmed.
+
 Common customizations:
 
 - Set install commands for `codex`, `claude`, `cursor`, and `critique`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmoyers/harness",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "repository": {
     "type": "git",

package/scripts/codex-live-mux-runtime.ts

@@ -25,7 +25,7 @@ import {
 } from '../src/config/config-core.ts';
 import { resolveHarnessRuntimePath } from '../src/config/harness-paths.ts';
 import { migrateLegacyHarnessLayout } from '../src/config/harness-runtime-migration.ts';
-import { loadHarnessSecrets } from '../src/config/secrets-core.ts';
+import { loadHarnessSecrets, upsertHarnessSecret } from '../src/config/secrets-core.ts';
 import { detectMuxGlobalShortcut, resolveMuxShortcutBindings } from '../src/mux/input-shortcuts.ts';
 import { createMuxInputModeManager } from '../src/mux/terminal-input-modes.ts';
 import type { buildWorkspaceRailViewRows } from '../src/mux/workspace-rail-model.ts';
@@ -92,6 +92,7 @@ import {
 } from '../src/mux/live-mux/layout.ts';
 import {
   normalizeGitHubRemoteUrl,
+  resolveGitHubDefaultBranchForActions,
   repositoryNameFromGitHubRemoteUrl,
   resolveGitHubTrackedBranchForActions,
   shouldShowGitHubPrActions,
@@ -244,6 +245,7 @@ interface RuntimeCommandMenuContext {
   readonly leftNavSelectionKind: WorkspaceModel['leftNavSelection']['kind'];
   readonly profileRunning: boolean;
   readonly statusTimelineRunning: boolean;
+  readonly githubRepositoryId: string | null;
   readonly githubRepositoryUrl: string | null;
   readonly githubDefaultBranch: string | null;
   readonly githubTrackedBranch: string | null;
@@ -271,6 +273,13 @@ interface ThemePickerSessionState {
   previewActionId: string | null;
 }
 
+interface AllowedCommandMenuApiKey {
+  readonly actionIdSuffix: string;
+  readonly envVar: 'ANTHROPIC_API_KEY' | 'OPENAI_API_KEY';
+  readonly displayName: string;
+  readonly aliases: readonly string[];
+}
+
 const DEFAULT_RESIZE_MIN_INTERVAL_MS = 33;
 const DEFAULT_PTY_RESIZE_SETTLE_MS = 75;
 const DEFAULT_STARTUP_SETTLE_QUIET_MS = 300;
@@ -290,6 +299,21 @@ const REPOSITORY_COLLAPSE_ALL_CHORD_PREFIX = Buffer.from([0x0b]);
 const UNTRACKED_REPOSITORY_GROUP_ID = 'untracked';
 const THEME_PICKER_SCOPE = 'theme-select';
 const THEME_ACTION_ID_PREFIX = 'theme.set.';
+const API_KEY_ACTION_ID_PREFIX = 'api-key.set.';
+const COMMAND_MENU_ALLOWED_API_KEYS: readonly AllowedCommandMenuApiKey[] = [
+  {
+    actionIdSuffix: 'anthropic',
+    envVar: 'ANTHROPIC_API_KEY',
+    displayName: 'Anthropic API Key',
+    aliases: ['anthropic api key', 'claude api key'],
+  },
+  {
+    actionIdSuffix: 'openai',
+    envVar: 'OPENAI_API_KEY',
+    displayName: 'OpenAI API Key',
+    aliases: ['openai api key', 'codex api key'],
+  },
+];
 const GIT_SUMMARY_LOADING: GitSummary = {
   branch: '(loading)',
   changedFiles: 0,
@@ -339,6 +363,15 @@ function parseGitHubPrUrl(result: Record<string, unknown>): string | null {
   return typeof url === 'string' ? url : null;
 }
 
+function parseGitHubUrl(result: Record<string, unknown>): string | null {
+  const url = result['url'];
+  if (typeof url !== 'string') {
+    return null;
+  }
+  const trimmed = url.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
 function commandMenuProjectPathTail(path: string): string {
   const normalized = path.trim().replaceAll('\\', '/').replace(/\/+$/u, '');
   if (normalized.length === 0) {
@@ -685,7 +718,7 @@ async function main(): Promise<number> {
       await startControlPlaneStreamServer({
         stateStorePath: resolveHarnessRuntimePath(
           options.invocationDirectory,
-          process.env.HARNESS_CONTROL_PLANE_DB_PATH ?? '.harness/control-plane.sqlite',
+          '.harness/control-plane.sqlite',
         ),
         codexTelemetry: loadedConfig.config.codex.telemetry,
         codexHistory: loadedConfig.config.codex.history,
@@ -793,7 +826,7 @@ async function main(): Promise<number> {
   workspace.taskPaneRepositoryEditClickState = null;
   workspace.homePaneDragState = null;
 
-  const sessionEnv = {
+  const sessionEnv: Record<string, string> = {
     ...sanitizeProcessEnv(),
     TERM: process.env.TERM ?? 'xterm-256color',
   };
@@ -1458,6 +1491,33 @@ async function main(): Promise<number> {
       activeDirectoryId === null
         ? null
         : (directoryRepositorySnapshotByDirectoryId.get(activeDirectoryId) ?? null);
+    let githubRepositoryId =
+      activeDirectoryId === null
+        ? null
+        : (repositoryAssociationByDirectoryId.get(activeDirectoryId) ?? null);
+    if (githubRepositoryId !== null) {
+      const associatedRepository = repositories.get(githubRepositoryId);
+      if (associatedRepository === undefined || associatedRepository.archivedAt !== null) {
+        githubRepositoryId = null;
+      }
+    }
+    const snapshotRemoteUrl = activeDirectoryRepositorySnapshot?.normalizedRemoteUrl ?? null;
+    if (githubRepositoryId === null && snapshotRemoteUrl !== null) {
+      const snapshotRemote = normalizeGitHubRemoteUrl(snapshotRemoteUrl);
+      if (snapshotRemote !== null) {
+        for (const repository of repositories.values()) {
+          if (repository.archivedAt !== null) {
+            continue;
+          }
+          if (normalizeGitHubRemoteUrl(repository.remoteUrl) === snapshotRemote) {
+            githubRepositoryId = repository.repositoryId;
+            break;
+          }
+        }
+      }
+    }
+    const githubRepositoryRecord =
+      githubRepositoryId === null ? null : (repositories.get(githubRepositoryId) ?? null);
     const githubProjectPrState =
       activeDirectoryId !== null &&
       commandMenuGitHubProjectPrState !== null &&
@@ -1491,8 +1551,12 @@ async function main(): Promise<number> {
       statusTimelineRunning: existsSync(
         resolveStatusTimelineStatePath(options.invocationDirectory, muxSessionName),
       ),
+      githubRepositoryId,
       githubRepositoryUrl: activeDirectoryRepositorySnapshot?.normalizedRemoteUrl ?? null,
-      githubDefaultBranch: activeDirectoryRepositorySnapshot?.defaultBranch ?? null,
+      githubDefaultBranch: resolveGitHubDefaultBranchForActions({
+        repositoryDefaultBranch: githubRepositoryRecord?.defaultBranch ?? null,
+        snapshotDefaultBranch: activeDirectoryRepositorySnapshot?.defaultBranch ?? null,
+      }),
       githubTrackedBranch: trackedBranchForActions,
       githubOpenPrUrl: githubProjectPrState?.openPrUrl ?? null,
       githubProjectPrLoading: githubProjectPrState?.loading ?? false,
@@ -1560,6 +1624,7 @@ async function main(): Promise<number> {
       resolveCommandMenuActions,
       getNewThreadPrompt: () => workspace.newThreadPrompt,
       getAddDirectoryPrompt: () => workspace.addDirectoryPrompt,
+      getApiKeyPrompt: () => workspace.apiKeyPrompt,
       getTaskEditorPrompt: () => workspace.taskEditorPrompt,
       getRepositoryPrompt: () => workspace.repositoryPrompt,
       getConversationTitleEdit: () => workspace.conversationTitleEdit,
@@ -2378,6 +2443,7 @@ async function main(): Promise<number> {
     }
     workspace.newThreadPrompt = null;
     workspace.addDirectoryPrompt = null;
+    workspace.apiKeyPrompt = null;
     workspace.taskEditorPrompt = null;
     workspace.repositoryPrompt = null;
     if (workspace.conversationTitleEdit !== null) {
@@ -2617,6 +2683,7 @@ async function main(): Promise<number> {
     }
     workspace.newThreadPrompt = null;
     workspace.addDirectoryPrompt = null;
+    workspace.apiKeyPrompt = null;
     workspace.taskEditorPrompt = null;
     workspace.repositoryPrompt = null;
     if (workspace.conversationTitleEdit !== null) {
@@ -2636,6 +2703,39 @@ async function main(): Promise<number> {
     markDirty();
   };
 
+  const openApiKeyPrompt = (apiKey: AllowedCommandMenuApiKey): void => {
+    workspace.newThreadPrompt = null;
+    workspace.addDirectoryPrompt = null;
+    workspace.taskEditorPrompt = null;
+    workspace.repositoryPrompt = null;
+    if (workspace.conversationTitleEdit !== null) {
+      stopConversationTitleEdit(true);
+    }
+    workspace.conversationTitleEditClickState = null;
+    const existingRaw = sessionEnv[apiKey.envVar] ?? process.env[apiKey.envVar];
+    const hasExistingValue = typeof existingRaw === 'string' && existingRaw.trim().length > 0;
+    workspace.apiKeyPrompt = {
+      keyName: apiKey.envVar,
+      displayName: apiKey.displayName,
+      value: '',
+      error: null,
+      hasExistingValue,
+    };
+    markDirty();
+  };
+
+  const persistApiKey = (keyName: string, value: string): void => {
+    const result = upsertHarnessSecret({
+      cwd: options.invocationDirectory,
+      key: keyName,
+      value,
+    });
+    sessionEnv[keyName] = value;
+    process.env[keyName] = value;
+    const action = result.replacedExisting ? 'updated' : 'saved';
+    setCommandNotice(`${keyName} ${action}`);
+  };
+
   const startThreadFromCommandMenu = (
     directoryId: string,
     agentType: ReturnType<typeof normalizeThreadAgentType>,
@@ -2739,7 +2839,7 @@ async function main(): Promise<number> {
     return [
       {
         id: 'critique.review.unstaged',
-        title: 'Critique AI Review: Unstaged Changes',
+        title: 'Critique AI Review: Unstaged Changes (git)',
         aliases: ['critique unstaged review', 'review unstaged diff', 'ai review unstaged'],
         keywords: ['critique', 'review', 'unstaged', 'diff', 'ai'],
         detail: 'runs critique review',
@@ -2749,7 +2849,7 @@ async function main(): Promise<number> {
       },
       {
         id: 'critique.review.staged',
-        title: 'Critique AI Review: Staged Changes',
+        title: 'Critique AI Review: Staged Changes (git)',
         aliases: ['critique staged review', 'review staged diff', 'ai review staged'],
         keywords: ['critique', 'review', 'staged', 'diff', 'ai'],
         detail: 'runs critique review --staged',
@@ -2759,7 +2859,7 @@ async function main(): Promise<number> {
       },
       {
         id: 'critique.review.base-branch',
-        title: 'Critique AI Review: Current Branch vs Base',
+        title: 'Critique AI Review: Current Branch vs Base (git)',
         aliases: ['critique base review', 'review against base branch', 'ai review base'],
         keywords: ['critique', 'review', 'base', 'branch', 'diff', 'ai'],
         detail: 'runs critique review <base> HEAD',
@@ -2902,6 +3002,21 @@ async function main(): Promise<number> {
     },
   });
 
+  commandMenuRegistry.registerProvider('api-key.set', () => {
+    return COMMAND_MENU_ALLOWED_API_KEYS.map(
+      (apiKey): RegisteredCommandMenuAction<RuntimeCommandMenuContext> => ({
+        id: `${API_KEY_ACTION_ID_PREFIX}${apiKey.actionIdSuffix}`,
+        title: `Set ${apiKey.displayName}`,
+        aliases: [...apiKey.aliases],
+        keywords: ['api', 'key', 'set', apiKey.envVar.toLowerCase()],
+        detail: apiKey.envVar,
+        run: () => {
+          openApiKeyPrompt(apiKey);
+        },
+      }),
+    );
+  });
+
   commandMenuRegistry.registerProvider('theme.set', () => {
     const selectedThemeName = getActiveMuxTheme().name;
     return muxThemePresetNames().map(
@@ -2951,10 +3066,10 @@ async function main(): Promise<number> {
     if (repositoryUrl === null) {
       return [];
     }
-    return [
+    const actions: RegisteredCommandMenuAction<RuntimeCommandMenuContext>[] = [
       {
         id: 'github.repo.open',
-        title: 'Open GitHub for This Repo',
+        title: 'Open GitHub for This Repo (git)',
         aliases: ['open github for this repo', 'open github repo', 'open repository on github'],
         keywords: ['github', 'repository', 'repo', 'open'],
         detail: repositoryUrl,
@@ -2968,6 +3083,41 @@ async function main(): Promise<number> {
         },
       },
     ];
+    if (context.githubRepositoryId !== null) {
+      const repositoryId = context.githubRepositoryId;
+      actions.push({
+        id: 'github.repo.my-prs.open',
+        title: 'Show My Open Pull Requests (git)',
+        aliases: ['show my open pull requests', 'my open pull requests', 'show my prs', 'my prs'],
+        keywords: ['github', 'pr', 'pull-request', 'open', 'my'],
+        detail: repositoryUrl,
+        run: async () => {
+          queueControlPlaneOp(async () => {
+            const result = await streamClient.sendCommand({
+              type: 'github.repo-my-prs-url',
+              repositoryId,
+            });
+            const parsedResult = asRecord(result);
+            if (parsedResult === null) {
+              setCommandNotice('github my open pull requests url unavailable');
+              return;
+            }
+            const myPrsUrl = parseGitHubUrl(parsedResult);
+            if (myPrsUrl === null) {
+              setCommandNotice('github my open pull requests url unavailable');
+              return;
+            }
+            const opened = openUrlInBrowser(myPrsUrl);
+            setCommandNotice(
+              opened
+                ? 'opened my open pull requests in browser'
+                : `open pull requests: ${myPrsUrl}`,
+            );
+          }, 'command-menu-open-my-open-prs');
+        },
+      });
+    }
+    return actions;
   });
 
   commandMenuRegistry.registerProvider('github.project-pr', (context) => {
@@ -2986,7 +3136,7 @@ async function main(): Promise<number> {
       return [
         {
           id: 'github.pr.open',
-          title: 'Open PR',
+          title: 'Open PR (git)',
           aliases: ['open pull request', 'open pr'],
           keywords: ['github', 'pr', 'open', 'pull-request'],
           detail: context.githubTrackedBranch ?? 'current project',
@@ -3040,7 +3190,7 @@ async function main(): Promise<number> {
       return [
         {
           id: 'github.pr.create',
-          title: 'Create PR',
+          title: 'Create PR (git)',
           aliases: ['create pull request', 'new pr'],
           keywords: ['github', 'pr', 'create', 'pull-request'],
           detail: context.githubTrackedBranch,
@@ -3494,6 +3644,7 @@ async function main(): Promise<number> {
     scheduleConversationTitlePersist,
     resolveCommandMenuActions,
     executeCommandMenuAction,
+    persistApiKey,
     requestStop,
     resolveDirectoryForAction,
     openNewThreadPrompt,

package/scripts/control-plane-daemon.ts

@@ -72,7 +72,7 @@ function parseArgs(argv: string[], invocationDirectory: string): DaemonOptions {
   const defaultAuthToken = process.env.HARNESS_CONTROL_PLANE_AUTH_TOKEN ?? null;
   const defaultStateDbPath = resolveHarnessRuntimePath(
     invocationDirectory,
-    process.env.HARNESS_CONTROL_PLANE_DB_PATH ?? '.harness/control-plane.sqlite',
+    '.harness/control-plane.sqlite',
   );
 
   let host = defaultHost;
@@ -117,7 +117,7 @@ function parseArgs(argv: string[], invocationDirectory: string): DaemonOptions {
       if (value === undefined) {
         throw new Error('missing value for --state-db-path');
       }
-      stateDbPath = value;
+      stateDbPath = resolveHarnessRuntimePath(invocationDirectory, value);
       idx += 1;
       continue;
     }
@@ -132,6 +132,17 @@ function parseArgs(argv: string[], invocationDirectory: string): DaemonOptions {
   if (!loopbackHosts.has(host) && authToken === null) {
     throw new Error('non-loopback hosts require --auth-token or HARNESS_CONTROL_PLANE_AUTH_TOKEN');
   }
+  const workspaceRuntimeRoot = resolveHarnessWorkspaceDirectory(invocationDirectory, process.env);
+  const normalizedRuntimeRoot = resolve(workspaceRuntimeRoot);
+  const normalizedStateDbPath = resolve(stateDbPath);
+  if (
+    normalizedStateDbPath !== normalizedRuntimeRoot &&
+    !normalizedStateDbPath.startsWith(`${normalizedRuntimeRoot}/`)
+  ) {
+    throw new Error(
+      `invalid --state-db-path: ${stateDbPath}. state db path must be under workspace runtime root ${workspaceRuntimeRoot}`,
+    );
+  }
 
   return {
     host,

package/scripts/harness.ts

@@ -19,6 +19,10 @@ import { connectControlPlaneStreamClient } from '../src/control-plane/stream-cli
 import { parseStreamCommand } from '../src/control-plane/stream-command-parser.ts';
 import type { StreamCommand } from '../src/control-plane/stream-protocol.ts';
 import { runHarnessAnimate } from './harness-animate.ts';
+import {
+  clearDefaultGatewayPointerForRecordPath,
+  writeDefaultGatewayPointerFromGatewayRecord,
+} from '../src/cli/default-gateway-pointer.ts';
 import {
   GATEWAY_RECORD_VERSION,
   DEFAULT_GATEWAY_DB_PATH,
@@ -960,6 +964,7 @@ function writeTextFileAtomically(filePath: string, text: string): void {
 
 function writeGatewayRecord(recordPath: string, record: GatewayRecord): void {
   writeTextFileAtomically(recordPath, serializeGatewayRecord(record));
+  writeDefaultGatewayPointerFromGatewayRecord(recordPath, record, process.env);
 }
 
 function removeGatewayRecord(recordPath: string): void {
@@ -971,6 +976,7 @@ function removeGatewayRecord(recordPath: string): void {
       throw error;
     }
   }
+  clearDefaultGatewayPointerForRecordPath(recordPath, process.cwd(), process.env);
 }
 
 function readProcessStartedAt(pid: number): string | null {
@@ -1473,8 +1479,9 @@ function listGatewayDaemonProcesses(): readonly ParsedGatewayDaemonEntry[] {
 function isPathWithinWorkspaceRuntimeScope(
   pathValue: string,
   invocationDirectory: string,
+  env: NodeJS.ProcessEnv = process.env,
 ): boolean {
-  const runtimeRoot = resolveHarnessWorkspaceDirectory(invocationDirectory, process.env);
+  const runtimeRoot = resolveHarnessWorkspaceDirectory(invocationDirectory, env);
   const normalizedRoot = resolve(runtimeRoot);
   const normalizedPath = resolve(pathValue);
   return normalizedPath === normalizedRoot || normalizedPath.startsWith(`${normalizedRoot}/`);
@@ -1702,10 +1709,15 @@ function resolveGatewaySettings(
   const port = normalizeGatewayPort(
     overrides.port ?? record?.port ?? env.HARNESS_CONTROL_PLANE_PORT,
   );
-  const configuredStateDbPath =
-    overrides.stateDbPath ?? env.HARNESS_CONTROL_PLANE_DB_PATH ?? defaultStateDbPath;
+  const configuredStateDbPath = overrides.stateDbPath ?? defaultStateDbPath;
   const stateDbPathRaw = normalizeGatewayStateDbPath(configuredStateDbPath, defaultStateDbPath);
   const stateDbPath = resolveHarnessRuntimePath(invocationDirectory, stateDbPathRaw, env);
+  if (!isPathWithinWorkspaceRuntimeScope(stateDbPath, invocationDirectory, env)) {
+    const runtimeRoot = resolveHarnessWorkspaceDirectory(invocationDirectory, env);
+    throw new Error(
+      `invalid --state-db-path: ${stateDbPath}. state db path must be under workspace runtime root ${runtimeRoot}`,
+    );
+  }
 
   const envToken =
     typeof env.HARNESS_CONTROL_PLANE_AUTH_TOKEN === 'string' &&
@@ -2916,7 +2928,7 @@ async function main(): Promise<number> {
   const migration = migrateLegacyHarnessLayout(invocationDirectory, process.env);
   if (migration.migrated) {
     process.stdout.write(
-      `[migration] local .harness migrated to global runtime layout (${String(migration.migratedEntries)} entries, configCopied=${String(migration.configCopied)}, secretsCopied=${String(migration.secretsCopied)})\n`,
+      `[migration] local .harness migrated to global runtime layout (${String(migration.migratedEntries)} entries, configCopied=${String(migration.configCopied)}, secretsCopied=${String(migration.secretsCopied)}, legacyRootRemoved=${String(migration.legacyRootRemoved)})\n`,
     );
   }
   loadHarnessSecrets({ cwd: invocationDirectory });

package/src/cli/default-gateway-pointer.ts

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { resolveHarnessConfigDirectory } from '../config/config-core.ts';
+import type { GatewayRecord } from './gateway-record.ts';
+
+const DEFAULT_GATEWAY_POINTER_VERSION = 1;
+const DEFAULT_GATEWAY_RECORD_PATH_PATTERN = /[\\/]gateway\.json$/u;
+const NAMED_SESSION_GATEWAY_RECORD_PATH_PATTERN = /[\\/]sessions[\\/][^\\/]+[\\/]gateway\.json$/u;
+
+const DEFAULT_GATEWAY_POINTER_FILE_NAME = 'default-gateway.json';
+
+interface DefaultGatewayPointerRecord {
+  readonly version: number;
+  readonly workspaceRoot: string;
+  readonly workspaceRuntimeRoot: string;
+  readonly gatewayRecordPath: string;
+  readonly gatewayLogPath: string;
+  readonly stateDbPath: string;
+  readonly pid: number;
+  readonly startedAt: string;
+  readonly updatedAt: string;
+  readonly gatewayRunId?: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function readNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function readPositiveInt(value: unknown): number | null {
+  if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isInteger(value)) {
+    return null;
+  }
+  return value > 0 ? value : null;
+}
+
+function isDefaultGatewayRecordPath(recordPath: string): boolean {
+  const normalizedPath = resolve(recordPath);
+  return (
+    DEFAULT_GATEWAY_RECORD_PATH_PATTERN.test(normalizedPath) &&
+    !NAMED_SESSION_GATEWAY_RECORD_PATH_PATTERN.test(normalizedPath)
+  );
+}
+
+export function resolveDefaultGatewayPointerPath(
+  invocationDirectory: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return resolve(
+    resolveHarnessConfigDirectory(invocationDirectory, env),
+    DEFAULT_GATEWAY_POINTER_FILE_NAME,
+  );
+}
+
+export function parseDefaultGatewayPointerText(text: string): DefaultGatewayPointerRecord | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const record = asRecord(parsed);
+  if (record === null) {
+    return null;
+  }
+  if (record['version'] !== DEFAULT_GATEWAY_POINTER_VERSION) {
+    return null;
+  }
+  const workspaceRoot = readNonEmptyString(record['workspaceRoot']);
+  const workspaceRuntimeRoot = readNonEmptyString(record['workspaceRuntimeRoot']);
+  const gatewayRecordPath = readNonEmptyString(record['gatewayRecordPath']);
+  const gatewayLogPath = readNonEmptyString(record['gatewayLogPath']);
+  const stateDbPath = readNonEmptyString(record['stateDbPath']);
+  const startedAt = readNonEmptyString(record['startedAt']);
+  const updatedAt = readNonEmptyString(record['updatedAt']);
+  const pid = readPositiveInt(record['pid']);
+  const gatewayRunIdRaw = record['gatewayRunId'];
+  const gatewayRunId =
+    gatewayRunIdRaw === undefined ? undefined : readNonEmptyString(gatewayRunIdRaw);
+
+  if (
+    workspaceRoot === null ||
+    workspaceRuntimeRoot === null ||
+    gatewayRecordPath === null ||
+    gatewayLogPath === null ||
+    stateDbPath === null ||
+    startedAt === null ||
+    updatedAt === null ||
+    pid === null ||
+    (gatewayRunIdRaw !== undefined && gatewayRunId === null)
+  ) {
+    return null;
+  }
+  const parsedGatewayRunId = gatewayRunId === null ? undefined : gatewayRunId;
+
+  return {
+    version: DEFAULT_GATEWAY_POINTER_VERSION,
+    workspaceRoot,
+    workspaceRuntimeRoot,
+    gatewayRecordPath,
+    gatewayLogPath,
+    stateDbPath,
+    pid,
+    startedAt,
+    updatedAt,
+    ...(parsedGatewayRunId === undefined ? {} : { gatewayRunId: parsedGatewayRunId }),
+  };
+}
+
+export function readDefaultGatewayPointer(
+  invocationDirectory: string,
+  env: NodeJS.ProcessEnv = process.env,
+): DefaultGatewayPointerRecord | null {
+  const pointerPath = resolveDefaultGatewayPointerPath(invocationDirectory, env);
+  if (!existsSync(pointerPath)) {
+    return null;
+  }
+  try {
+    return parseDefaultGatewayPointerText(readFileSync(pointerPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeDefaultGatewayPointerFromGatewayRecord(
+  recordPath: string,
+  record: GatewayRecord,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (!isDefaultGatewayRecordPath(recordPath)) {
+    return;
+  }
+  const normalizedRecordPath = resolve(recordPath);
+  const pointerPath = resolveDefaultGatewayPointerPath(record.workspaceRoot, env);
+  const payload: DefaultGatewayPointerRecord = {
+    version: DEFAULT_GATEWAY_POINTER_VERSION,
+    workspaceRoot: record.workspaceRoot,
+    workspaceRuntimeRoot: dirname(normalizedRecordPath),
+    gatewayRecordPath: normalizedRecordPath,
+    gatewayLogPath: resolve(dirname(normalizedRecordPath), 'gateway.log'),
+    stateDbPath: record.stateDbPath,
+    pid: record.pid,
+    startedAt: record.startedAt,
+    updatedAt: new Date().toISOString(),
+    ...(record.gatewayRunId == null ? {} : { gatewayRunId: record.gatewayRunId }),
+  };
+  mkdirSync(dirname(pointerPath), { recursive: true });
+  writeFileSync(pointerPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+
+export function clearDefaultGatewayPointerForRecordPath(
+  recordPath: string,
+  invocationDirectory: string = process.cwd(),
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  if (!isDefaultGatewayRecordPath(recordPath)) {
+    return;
+  }
+  const pointerPath = resolveDefaultGatewayPointerPath(invocationDirectory, env);
+  if (!existsSync(pointerPath)) {
+    return;
+  }
+  let pointer: DefaultGatewayPointerRecord | null = null;
+  try {
+    pointer = parseDefaultGatewayPointerText(readFileSync(pointerPath, 'utf8'));
+  } catch {
+    pointer = null;
+  }
+  if (pointer === null) {
+    return;
+  }
+  if (resolve(pointer.gatewayRecordPath) !== resolve(recordPath)) {
+    return;
+  }
+  try {
+    unlinkSync(pointerPath);
+  } catch (error: unknown) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}