@jmoyers/harness 0.1.1 → 0.1.6

package/README.md

@@ -6,15 +6,18 @@ Use it when you want to move faster than a single chat window: keep multiple thr
 
 ## Why teams use it
 
-- Run multiple threads in parallel (`codex`, `claude`, `cursor`, `terminal`, `critique`).
-- Keep work scoped to the right project/repo context.
-- Reconnect without losing long-running sessions.
-- Move quickly between implementation and review loops.
-- Open repo/PR actions directly from the same workflow.
+- Run many agent threads in parallel across `codex`, `claude`, `cursor`, `terminal`, and `critique`.
+- Keep native CLI ergonomics in one keyboard-first workspace.
+- Keep long-running threads alive in the detached gateway so reconnects do not kill work.
+- Open a command palette with `ctrl+p`/`cmd+p`, live-filter registered actions, and execute context-aware thread/project/runtime controls.
+- Open a thread-scoped command palette from left-rail `[+ thread]` (same matcher/autocomplete as `ctrl+p`) to start/install agent CLIs per project.
+- Start in the Home pane by default, then jump to projects/threads from the left rail.
+- Open `Set a Theme` from the command palette to launch a second autocomplete picker of canonical OpenCode presets (plus a `default` reset option), with live preview while you navigate.
+- Open or create a GitHub pull request for the currently tracked project branch directly from the command palette.
 
 ## Demo
 
-![Harness multi-thread recording](assets/poem-recording.gif)
+![Harness multi-thread recording](https://raw.githubusercontent.com/jmoyers/harness/main/assets/poem-recording.gif)
 
 ## Quick start
 
@@ -24,7 +27,22 @@ Use it when you want to move faster than a single chat window: keep multiple thr
 - Rust toolchain
 - At least one installed agent CLI (`codex`, `claude`, `cursor`, or `critique`)
 
-### Install
+### Install (npm package)
+
+> Note: Harness requires Bun. It does not work with Node.js alone.
+
+```bash
+# One-line bootstrap (installs missing Bun/Rust deps, then installs Harness globally)
+curl -fsSL https://raw.githubusercontent.com/jmoyers/harness/main/install.sh | bash
+
+# Run directly with bunx (no install needed)
+bunx @jmoyers/harness@latest
+
+# Or install globally
+bun add -g --trust @jmoyers/harness
+```
+
+### Install (from source)
 
 ```bash
 bun install
@@ -50,9 +68,108 @@ harness --session my-session
 3. Use the command palette (`ctrl+p` / `cmd+p`) to jump, run actions, and manage project context.
 4. Open the repo or PR actions from inside Harness when GitHub auth is available.
 
+## Critique threads
+
+- Available in the thread-scoped command palette (`[+ thread]`).
+- Runs with `--watch` by default.
+- Install actions are availability-aware and config-driven (`*.install.command`), opening a terminal thread to run the configured install command when a tool is missing.
+- Global command palette (`ctrl+p` / `cmd+p`) includes:
+  - `Critique AI Review: Staged Changes`
+  - `Critique AI Review: Current Branch vs Base`
+- These start a terminal thread and run `critique review ...`, preferring `claude` when available and otherwise using `opencode` when installed.
+- `mux.conversation.critique.open-or-create` is bound to `ctrl+g` by default.
+
+`ctrl+g` behavior is project-aware:
+
+- If a critique thread exists for the current project, it selects it.
+- If not, it creates and opens one in the main pane.
+
+`session.interrupt` is also surfaced as a mux keybinding action (`mux.conversation.interrupt`) so teams can bind a dedicated in-client thread interrupt shortcut without overloading quit semantics.
+
+## GitHub PR Integration
+
+When GitHub auth is available (`GITHUB_TOKEN` or an authenticated `gh` CLI), Harness can:
+
+- Detect the tracked branch for the active project and show `Open PR` (if an open PR exists) or `Create PR` in the command palette.
+- Continuously sync open PR CI/check status into the control-plane store for realtime clients.
+- If auth is unavailable, PR actions fail quietly and show a lightweight hint instead of surfacing hard errors.
+
+## API for Automation
+
+Harness exposes a typed realtime client for orchestrators, policy agents, and dashboards:
+
+```ts
+import { connectHarnessAgentRealtimeClient } from './src/control-plane/agent-realtime-api.ts';
+
+const client = await connectHarnessAgentRealtimeClient({
+  host: '127.0.0.1',
+  port: 7777,
+  subscription: { includeOutput: false },
+});
+
+client.on('session.status', ({ observed }) => {
+  console.log(observed.sessionId, observed.status);
+});
+
+await client.close();
+```
+
+Key orchestration calls are available in the same client:
+
+- `client.tasks.pull(...)`
+- `client.projects.status(projectId)`
+- `client.projects.settings.get(projectId)` / `client.projects.settings.update(projectId, update)`
+- `client.automation.getPolicy(...)` / `client.automation.setPolicy(...)`
+
 ## Configuration
 
-Harness is config-first via `harness.config.jsonc` and bootstraps it automatically on first run.
+Runtime behavior is config-first via `harness.config.jsonc`.
+GitHub project/PR integration is enabled by default and configured under `github.*`.
+
+Example (install commands + critique defaults + hotkey override + OpenCode theme selection):
+
+```jsonc
+{
+  "codex": {
+    "install": {
+      "command": "bunx @openai/codex@latest"
+    }
+  },
+  "claude": {
+    "install": {
+      "command": "bunx @anthropic-ai/claude-code@latest"
+    }
+  },
+  "cursor": {
+    "install": {
+      "command": null
+    }
+  },
+  "critique": {
+    "launch": {
+      "defaultArgs": ["--watch"]
+    },
+    "install": {
+      "command": "bun add --global critique@latest"
+    }
+  },
+  "mux": {
+    "ui": {
+      "theme": {
+        "preset": "tokyonight",
+        "mode": "dark",
+        "customThemePath": null
+      }
+    },
+    "keybindings": {
+      "mux.conversation.critique.open-or-create": ["ctrl+g"]
+    }
+  }
+}
+```
+
+`mux.ui.theme.customThemePath` can point to any local JSON file that follows the OpenCode theme schema (`https://opencode.ai/theme.json`).
+Built-in presets now mirror the canonical OpenCode set (for example `aura`, `ayu`, `carbonfox`, `catppuccin`, `dracula`, `everforest`, `github`, `gruvbox`, `nightowl`, `nord`, `one-dark`, `opencode`, `tokyonight`, `vesper`, `zenburn`, and more), plus a special `default` picker option for the legacy default mux theme.
 
 ## Documentation
 

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@jmoyers/harness",
-  "version": "0.1.1",
+  "version": "0.1.6",
   "private": false,
-  "type": "module",
-  "packageManager": "bun@1.3.9",
-  "publishConfig": {
-    "access": "public"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jmoyers/harness"
+  },
+  "bin": {
+    "harness": "scripts/harness-bin.js"
   },
   "files": [
     "src",
+    "scripts/bun-runtime-guard.js",
     "scripts/build-ptyd.sh",
     "scripts/control-plane-daemon.ts",
     "scripts/cursor-hook-relay.ts",
@@ -17,20 +20,23 @@
     "scripts/harness-core.ts",
     "scripts/harness-inspector.ts",
     "scripts/harness.ts",
+    "scripts/require-bun.js",
     "native/ptyd/Cargo.lock",
     "native/ptyd/Cargo.toml",
     "native/ptyd/src",
     "README.md",
     "LICENSE"
   ],
-  "bin": {
-    "harness": "scripts/harness-bin.js"
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
     "migrate:bun": "bash ./scripts/migrate-to-bun.sh",
     "harness": "bun scripts/harness.ts",
     "harness:core": "bun scripts/harness-core.ts",
     "build:ptyd": "bash ./scripts/build-ptyd.sh",
+    "preinstall": "node scripts/require-bun.js",
     "postinstall": "bun run build:ptyd",
     "codex:live": "bun scripts/codex-live.ts",
     "codex:pty:vte:passthrough": "bun scripts/codex-pty-vte-passthrough.ts",
@@ -74,17 +80,19 @@
     "verify": "bun run format:check && bun run lint && bun run typecheck && bun run deadcode && bun run test:coverage",
     "verify:strict": "bun run verify && bun run loc:verify:enforce"
   },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.92",
+    "gifenc": "^1.0.3"
+  },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.45",
     "@types/node": "^22.17.0",
     "ai": "^6.0.91",
+    "fast-check": "^4.5.3",
     "oxfmt": "^0.33.0",
     "oxlint": "^1.48.0",
     "typescript": "^5.9.2",
     "zod": "^4.3.6"
   },
-  "dependencies": {
-    "@napi-rs/canvas": "^0.1.92",
-    "gifenc": "^1.0.3"
-  }
+  "packageManager": "bun@1.3.9"
 }

package/scripts/bun-runtime-guard.js

@@ -0,0 +1,35 @@
+import { spawnSync } from 'node:child_process';
+
+export const BUN_INSTALL_DOCS_URL = 'https://bun.sh/docs/installation';
+
+export function formatBunRequiredMessage() {
+  return [
+    '[harness] Bun is required to install and run Harness.',
+    `[harness] install Bun: ${BUN_INSTALL_DOCS_URL}`,
+    '[harness] then verify: bun --version',
+  ].join('\n');
+}
+
+export function isBunAvailable(command = 'bun') {
+  const check = spawnSync(command, ['--version'], {
+    stdio: 'ignore',
+  });
+  return check.status === 0;
+}
+
+export function ensureBunAvailable(options = {}) {
+  const command =
+    typeof options.command === 'string' && options.command.trim().length > 0
+      ? options.command.trim()
+      : 'bun';
+  const stderr = options.stderr ?? process.stderr;
+  if (isBunAvailable(command)) {
+    return true;
+  }
+  stderr.write(`${formatBunRequiredMessage()}\n`);
+  const onMissing = options.onMissing;
+  if (typeof onMissing === 'function') {
+    onMissing();
+  }
+  return false;
+}

package/scripts/control-plane-daemon.ts

@@ -2,6 +2,8 @@ import { resolve } from 'node:path';
 import { startCodexLiveSession } from '../src/codex/live-session.ts';
 import { startControlPlaneStreamServer } from '../src/control-plane/stream-server.ts';
 import { loadHarnessConfig } 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 {
   configurePerfCore,
@@ -39,11 +41,14 @@ function configureProcessPerf(invocationDirectory: string): void {
   const loadedConfig = loadHarnessConfig({ cwd: invocationDirectory });
   const configEnabled = loadedConfig.config.debug.enabled && loadedConfig.config.debug.perf.enabled;
   const perfEnabled = parseBooleanEnv(process.env.HARNESS_PERF_ENABLED, configEnabled);
-  const configuredPath = resolve(invocationDirectory, loadedConfig.config.debug.perf.filePath);
+  const configuredPath = resolveHarnessRuntimePath(
+    invocationDirectory,
+    loadedConfig.config.debug.perf.filePath,
+  );
   const envPath = process.env.HARNESS_PERF_FILE_PATH;
   const perfFilePath =
     typeof envPath === 'string' && envPath.trim().length > 0
-      ? resolve(invocationDirectory, envPath)
+      ? resolveHarnessRuntimePath(invocationDirectory, envPath)
       : configuredPath;
 
   configurePerfCore({
@@ -58,12 +63,14 @@ function configureProcessPerf(invocationDirectory: string): void {
   });
 }
 
-function parseArgs(argv: string[]): DaemonOptions {
+function parseArgs(argv: string[], invocationDirectory: string): DaemonOptions {
   const defaultHost = process.env.HARNESS_CONTROL_PLANE_HOST ?? '127.0.0.1';
   const defaultPortRaw = process.env.HARNESS_CONTROL_PLANE_PORT ?? '7777';
   const defaultAuthToken = process.env.HARNESS_CONTROL_PLANE_AUTH_TOKEN ?? null;
-  const defaultStateDbPath =
-    process.env.HARNESS_CONTROL_PLANE_DB_PATH ?? '.harness/control-plane.sqlite';
+  const defaultStateDbPath = resolveHarnessRuntimePath(
+    invocationDirectory,
+    process.env.HARNESS_CONTROL_PLANE_DB_PATH ?? '.harness/control-plane.sqlite',
+  );
 
   let host = defaultHost;
   let portRaw = defaultPortRaw;
@@ -133,6 +140,7 @@ function parseArgs(argv: string[]): DaemonOptions {
 
 async function main(): Promise<number> {
   const invocationDirectory = resolveInvocationDirectory();
+  migrateLegacyHarnessLayout(invocationDirectory, process.env);
   loadHarnessSecrets({ cwd: invocationDirectory });
   configureProcessPerf(invocationDirectory);
   const loadedConfig = loadHarnessConfig({ cwd: invocationDirectory });
@@ -155,7 +163,7 @@ async function main(): Promise<number> {
   recordPerfEvent('daemon.startup.begin', {
     process: 'daemon',
   });
-  const options = parseArgs(process.argv.slice(2));
+  const options = parseArgs(process.argv.slice(2), invocationDirectory);
 
   const listenSpan = startPerfSpan('daemon.startup.listen', {
     process: 'daemon',
@@ -171,6 +179,12 @@ async function main(): Promise<number> {
       directoryModes: codexLaunchDirectoryModes,
     },
     critique: loadedConfig.config.critique,
+    agentInstall: {
+      codex: loadedConfig.config.codex.install,
+      claude: loadedConfig.config.claude.install,
+      cursor: loadedConfig.config.cursor.install,
+      critique: loadedConfig.config.critique.install,
+    },
     cursorLaunch: {
       defaultMode: loadedConfig.config.cursor.launch.defaultMode,
       directoryModes: cursorLaunchDirectoryModes,
@@ -181,6 +195,15 @@ async function main(): Promise<number> {
       maxConcurrency: loadedConfig.config.mux.git.maxConcurrency,
       minDirectoryRefreshMs: Math.max(loadedConfig.config.mux.git.idlePollMs, 30_000),
     },
+    github: {
+      enabled: loadedConfig.config.github.enabled,
+      apiBaseUrl: loadedConfig.config.github.apiBaseUrl,
+      tokenEnvVar: loadedConfig.config.github.tokenEnvVar,
+      pollMs: loadedConfig.config.github.pollMs,
+      maxConcurrency: loadedConfig.config.github.maxConcurrency,
+      branchStrategy: loadedConfig.config.github.branchStrategy,
+      viewerLogin: loadedConfig.config.github.viewerLogin,
+    },
     lifecycleHooks: loadedConfig.config.hooks.lifecycle,
     startSession: (input) => {
       const sessionOptions: Parameters<typeof startCodexLiveSession>[0] = {

package/scripts/harness-bin.js

@@ -1,9 +1,10 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
 import { existsSync, readFileSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ensureBunAvailable } from './bun-runtime-guard.js';
 
 const LEGACY_LOCKFILES = [
   'package-lock.json',
@@ -53,10 +54,20 @@ function maybePrintBunMigrationHint() {
 
 maybePrintBunMigrationHint();
 
+const bunCommand =
+  typeof process.env.HARNESS_BUN_COMMAND === 'string' &&
+  process.env.HARNESS_BUN_COMMAND.trim().length > 0
+    ? process.env.HARNESS_BUN_COMMAND.trim()
+    : 'bun';
+
+if (!ensureBunAvailable({ command: bunCommand })) {
+  process.exit(1);
+}
+
 const here = dirname(fileURLToPath(import.meta.url));
 const scriptPath = resolve(here, './harness.ts');
 const runtimeArgs = [scriptPath, ...process.argv.slice(2)];
-const child = spawn(process.execPath, runtimeArgs, {
+const child = spawn(bunCommand, runtimeArgs, {
   stdio: 'inherit',
 });
 

package/scripts/harness.ts

@@ -5,6 +5,7 @@ import {
   mkdirSync,
   openSync,
   readFileSync,
+  renameSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
@@ -33,6 +34,11 @@ import {
   type GatewayRecord,
 } from '../src/cli/gateway-record.ts';
 import { loadHarnessConfig } from '../src/config/config-core.ts';
+import {
+  resolveHarnessRuntimePath,
+  resolveHarnessWorkspaceDirectory,
+} from '../src/config/harness-paths.ts';
+import { migrateLegacyHarnessLayout } from '../src/config/harness-runtime-migration.ts';
 import { loadHarnessSecrets } from '../src/config/secrets-core.ts';
 import {
   buildCursorManagedHookRelayCommand,
@@ -72,8 +78,8 @@ const DEFAULT_GATEWAY_START_RETRY_WINDOW_MS = 6000;
 const DEFAULT_GATEWAY_START_RETRY_DELAY_MS = 40;
 const DEFAULT_GATEWAY_STOP_TIMEOUT_MS = 5000;
 const DEFAULT_GATEWAY_STOP_POLL_MS = 50;
-const DEFAULT_PROFILE_ROOT_PATH = '.harness/profiles';
-const DEFAULT_SESSION_ROOT_PATH = '.harness/sessions';
+const DEFAULT_PROFILE_ROOT_PATH = 'profiles';
+const DEFAULT_SESSION_ROOT_PATH = 'sessions';
 const PROFILE_STATE_FILE_NAME = 'active-profile.json';
 const PROFILE_CLIENT_FILE_NAME = 'client.cpuprofile';
 const PROFILE_GATEWAY_FILE_NAME = 'gateway.cpuprofile';
@@ -316,35 +322,50 @@ function resolveSessionPaths(
   invocationDirectory: string,
   sessionName: string | null,
 ): SessionPaths {
-  const statusTimelineStatePath = resolveStatusTimelineStatePath(invocationDirectory, sessionName);
+  const workspaceDirectory = resolveHarnessWorkspaceDirectory(invocationDirectory, process.env);
+  const statusTimelineStatePath = resolveStatusTimelineStatePath(
+    invocationDirectory,
+    sessionName,
+    process.env,
+  );
   const defaultStatusTimelineOutputPath = resolveDefaultStatusTimelineOutputPath(
     invocationDirectory,
     sessionName,
+    process.env,
+  );
+  const renderTraceStatePath = resolveRenderTraceStatePath(
+    invocationDirectory,
+    sessionName,
+    process.env,
   );
-  const renderTraceStatePath = resolveRenderTraceStatePath(invocationDirectory, sessionName);
   const defaultRenderTraceOutputPath = resolveDefaultRenderTraceOutputPath(
     invocationDirectory,
     sessionName,
+    process.env,
   );
   if (sessionName === null) {
     return {
-      recordPath: resolveGatewayRecordPath(invocationDirectory),
-      logPath: resolveGatewayLogPath(invocationDirectory),
-      defaultStateDbPath: resolve(invocationDirectory, DEFAULT_GATEWAY_DB_PATH),
-      profileDir: resolve(invocationDirectory, DEFAULT_PROFILE_ROOT_PATH),
-      profileStatePath: resolve(invocationDirectory, '.harness', PROFILE_STATE_FILE_NAME),
+      recordPath: resolveGatewayRecordPath(invocationDirectory, process.env),
+      logPath: resolveGatewayLogPath(invocationDirectory, process.env),
+      defaultStateDbPath: resolveHarnessRuntimePath(
+        invocationDirectory,
+        DEFAULT_GATEWAY_DB_PATH,
+        process.env,
+      ),
+      profileDir: resolve(workspaceDirectory, DEFAULT_PROFILE_ROOT_PATH),
+      profileStatePath: resolve(workspaceDirectory, PROFILE_STATE_FILE_NAME),
       statusTimelineStatePath,
       defaultStatusTimelineOutputPath,
       renderTraceStatePath,
       defaultRenderTraceOutputPath,
     };
   }
-  const sessionRoot = resolve(invocationDirectory, DEFAULT_SESSION_ROOT_PATH, sessionName);
+  const sessionRoot = resolve(workspaceDirectory, DEFAULT_SESSION_ROOT_PATH, sessionName);
   return {
     recordPath: resolve(sessionRoot, 'gateway.json'),
     logPath: resolve(sessionRoot, 'gateway.log'),
     defaultStateDbPath: resolve(sessionRoot, 'control-plane.sqlite'),
-    profileDir: resolve(invocationDirectory, DEFAULT_PROFILE_ROOT_PATH, sessionName),
+    profileDir: resolve(workspaceDirectory, DEFAULT_PROFILE_ROOT_PATH, sessionName),
     profileStatePath: resolve(sessionRoot, PROFILE_STATE_FILE_NAME),
     statusTimelineStatePath,
     defaultStatusTimelineOutputPath,
@@ -830,9 +851,24 @@ function readGatewayRecord(recordPath: string): GatewayRecord | null {
   }
 }
 
+function writeTextFileAtomically(filePath: string, text: string): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${randomUUID()}`;
+  try {
+    writeFileSync(tempPath, text, 'utf8');
+    renameSync(tempPath, filePath);
+  } catch (error: unknown) {
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // Best-effort cleanup only.
+    }
+    throw error;
+  }
+}
+
 function writeGatewayRecord(recordPath: string, record: GatewayRecord): void {
-  mkdirSync(dirname(recordPath), { recursive: true });
-  writeFileSync(recordPath, serializeGatewayRecord(record), 'utf8');
+  writeTextFileAtomically(recordPath, serializeGatewayRecord(record));
 }
 
 function removeGatewayRecord(recordPath: string): void {
@@ -916,8 +952,7 @@ function readActiveProfileState(profileStatePath: string): ActiveProfileState |
 }
 
 function writeActiveProfileState(profileStatePath: string, state: ActiveProfileState): void {
-  mkdirSync(dirname(profileStatePath), { recursive: true });
-  writeFileSync(profileStatePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  writeTextFileAtomically(profileStatePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 
 function removeActiveProfileState(profileStatePath: string): void {
@@ -947,8 +982,7 @@ function readActiveStatusTimelineState(statePath: string): ActiveStatusTimelineS
 }
 
 function writeActiveStatusTimelineState(statePath: string, state: ActiveStatusTimelineState): void {
-  mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  writeTextFileAtomically(statePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 
 function removeActiveStatusTimelineState(statePath: string): void {
@@ -979,8 +1013,7 @@ function readActiveRenderTraceState(statePath: string): ActiveRenderTraceState |
 }
 
 function writeActiveRenderTraceState(statePath: string, state: ActiveRenderTraceState): void {
-  mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+  writeTextFileAtomically(statePath, `${JSON.stringify(state, null, 2)}\n`);
 }
 
 function removeActiveRenderTraceState(statePath: string): void {
@@ -1312,7 +1345,7 @@ function resolveGatewaySettings(
     overrides.stateDbPath ?? record?.stateDbPath ?? env.HARNESS_CONTROL_PLANE_DB_PATH,
     defaultStateDbPath,
   );
-  const stateDbPath = resolve(invocationDirectory, stateDbPathRaw);
+  const stateDbPath = resolveHarnessRuntimePath(invocationDirectory, stateDbPathRaw, env);
 
   const envToken =
     typeof env.HARNESS_CONTROL_PLANE_AUTH_TOKEN === 'string' &&
@@ -2392,6 +2425,12 @@ async function runCursorHooksCommandEntry(
 
 async function main(): Promise<number> {
   const invocationDirectory = resolveInvocationDirectory(process.env, process.cwd());
+  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`,
+    );
+  }
   loadHarnessSecrets({ cwd: invocationDirectory });
   const runtimeOptions = resolveInspectRuntimeOptions(invocationDirectory);
   const daemonScriptPath = resolveScriptPath(

package/scripts/require-bun.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { ensureBunAvailable } from './bun-runtime-guard.js';
+
+if (!ensureBunAvailable()) {
+  process.exit(1);
+}

package/src/adapters/agent-session-state.ts

@@ -313,10 +313,10 @@ export function buildAgentStartArgs(
     const argsWithLaunchMode = [...baseArgs];
     if (
       cursorLaunchMode === 'yolo' &&
-      !argsWithLaunchMode.includes('--yolo') &&
-      !argsWithLaunchMode.includes('--force')
+      !argsWithLaunchMode.includes('--force') &&
+      !argsWithLaunchMode.includes('-f')
     ) {
-      argsWithLaunchMode.push('--yolo');
+      argsWithLaunchMode.push('--force');
     }
     if (
       cursorLaunchMode === 'yolo' &&

package/src/cli/gateway-record.ts

@@ -1,4 +1,4 @@
-import { resolve } from 'node:path';
+import { resolveHarnessRuntimePath } from '../config/harness-paths.ts';
 
 export const GATEWAY_RECORD_VERSION = 1;
 export const DEFAULT_GATEWAY_HOST = '127.0.0.1';
@@ -60,12 +60,18 @@ export function resolveInvocationDirectory(env: NodeJS.ProcessEnv, cwd: string):
   return env.HARNESS_INVOKE_CWD ?? env.INIT_CWD ?? cwd;
 }
 
-export function resolveGatewayRecordPath(workspaceRoot: string): string {
-  return resolve(workspaceRoot, DEFAULT_GATEWAY_RECORD_PATH);
+export function resolveGatewayRecordPath(
+  workspaceRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return resolveHarnessRuntimePath(workspaceRoot, DEFAULT_GATEWAY_RECORD_PATH, env);
 }
 
-export function resolveGatewayLogPath(workspaceRoot: string): string {
-  return resolve(workspaceRoot, DEFAULT_GATEWAY_LOG_PATH);
+export function resolveGatewayLogPath(
+  workspaceRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  return resolveHarnessRuntimePath(workspaceRoot, DEFAULT_GATEWAY_LOG_PATH, env);
 }
 
 export function normalizeGatewayHost(
@@ -93,7 +99,7 @@ export function normalizeGatewayPort(
     return fallback;
   }
   const trimmed = input.trim();
-  if (trimmed.length === 0) {
+  if (trimmed.length === 0 || !/^\d+$/u.test(trimmed)) {
     return fallback;
   }
   const parsed = Number.parseInt(trimmed, 10);