@love-moon/conductor-cli 0.7.5 → 0.7.7

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @love-moon/conductor-cli
 
+## 0.7.7
+
+### Patch Changes
+
+- 400f3a7: Report a terminal task status when a stop request finds no active process, so a
+  task whose Fire already died converges instead of sitting in `killing` forever.
+
+  Drop queued terminal status events before an in-place restart reuses a working
+  directory. The durable upstream outbox lives inside that directory, so an
+  undelivered `KILLED` from the previous run was flushed on startup and killed the
+  task that had just finished resuming.
+
+- 67498dc: Report a Fire that dies inside its tmux session instead of leaving the task
+  hanging. In tmux mode the daemon's child is the short-lived `tmux new-session`
+  client, not the Fire, so an abnormal death (crash, OOM, SIGKILL) went unreported
+  and the task sat at `running` until reconcile relabelled it as a user stop. The
+  Fire now records its own exit code into its log under a per-launch nonce, and the
+  liveness reaper classifies the death from that marker and publishes a terminal
+  status with the real cause.
+- Updated dependencies [400f3a7]
+  - @love-moon/conductor-sdk@0.7.7
+  - @love-moon/ai-sdk@0.7.7
+
+## 0.7.6
+
+### Patch Changes
+
+- 7bbb412: Add `CONDUCTOR_HOME` support for relocating user-level configuration, logs,
+  Fire locks, sessions, update metadata, and AI manager caches while leaving
+  project-scoped `.conductor` directories and Fire task markers in place.
+
+  Migrate device authorization to `conductor.conductor-ai.top` while preserving
+  compatibility with the legacy official endpoint and self-hosted backends.
+
+- Updated dependencies [7bbb412]
+  - @love-moon/conductor-sdk@0.7.6
+  - @love-moon/ai-sdk@0.7.6
+
 ## 0.7.5
 
 ### Patch Changes

package/bin/conductor-channel.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
@@ -10,6 +9,7 @@ import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 import { loadConfig } from "@love-moon/conductor-sdk";
 import { envForExplicitConfigFile } from "../src/config-env.js";
+import { resolveConductorConfigPath } from "../src/conductor-paths.js";
 
 const isMainModule = (() => {
   const currentFile = fileURLToPath(import.meta.url);
@@ -18,8 +18,7 @@ const isMainModule = (() => {
 })();
 
 function resolveDefaultConfigPath(env = process.env) {
-  const home = env.HOME || env.USERPROFILE || os.homedir();
-  return path.join(home, ".conductor", "config.yaml");
+  return resolveConductorConfigPath(undefined, env);
 }
 
 function readTextFile(filePath) {
@@ -55,7 +54,7 @@ export async function connectFeishuChannel(options = {}) {
     throw new Error("fetch is not available");
   }
 
-  const resolvedConfigPath = path.resolve(options.configFile || resolveDefaultConfigPath(env));
+  const resolvedConfigPath = resolveConductorConfigPath(options.configFile, env);
   const rawYaml = readTextFile(resolvedConfigPath);
   const config = loadConfig(resolvedConfigPath, {
     env: envForExplicitConfigFile(options.configFile, env),

package/bin/conductor-chrome.js

@@ -9,6 +9,7 @@ import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import { launch as launchChrome } from 'chrome-launcher';
 import CDP from 'chrome-remote-interface';
+import { resolveConductorConfigPath } from '../src/conductor-paths.js';
 
 
 const BACKEND_URLS = {
@@ -52,7 +53,7 @@ const PAGE_AUTOMATION_PATH = new URL('pageAutomation.js', AUTOMATION_SRC_ROOT);
 const PROVIDERS_DIR = new URL('providers/', AUTOMATION_SRC_ROOT);
 let automationScriptCache;
 
-const CONFIG_PATH = path.join(homedir(), '.conductor', 'config.yaml');
+const CONFIG_PATH = resolveConductorConfigPath();
 
 function expandHomeDir(maybePath) {
   if (!maybePath) {
@@ -80,7 +81,7 @@ async function loadUserConfig() {
     }
   } catch (error) {
     if (error.code !== 'ENOENT') {
-      console.warn('Failed to read ~/.conductor/config.yaml:', error);
+      console.warn(`Failed to read ${CONFIG_PATH}:`, error);
     }
     cachedUserConfig = {};
   }

package/bin/conductor-config.js

@@ -9,9 +9,10 @@ import { execFileSync, execSync } from "node:child_process";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 import { RUNTIME_SUPPORTED_BACKENDS } from "../src/runtime-backends.js";
+import { resolveConductorConfigPath } from "../src/conductor-paths.js";
 
-const CONFIG_DIR = path.join(os.homedir(), ".conductor");
-const CONFIG_FILE = path.join(CONFIG_DIR, "config.yaml");
+const CONFIG_FILE = resolveConductorConfigPath();
+const CONFIG_DIR = path.dirname(CONFIG_FILE);
 const packageJson = JSON.parse(
   fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"),
 );
@@ -68,6 +69,9 @@ const defaultDaemonName = os.hostname() || "my-daemon";
 const cliVersion = packageJson.version || "unknown";
 const OPENCODE_INSTALL_URL = "https://opencode.ai/install";
 const OPENCODE_NPM_PACKAGE = "opencode-ai";
+const LEGACY_CONDUCTOR_PUBLIC_HOST = "conductor-ai.top";
+const CONDUCTOR_PUBLIC_HOST = "conductor.conductor-ai.top";
+const CONDUCTOR_PUBLIC_ORIGIN = "https://conductor.conductor-ai.top";
 
 const COLORS = {
   yellow: "\x1b[33m",
@@ -518,7 +522,9 @@ async function authorizeDeviceAndGetToken() {
   console.log(colorize("Open this link in your browser to authorize this device:", "cyan"));
   console.log("");
   console.log(`Device code: ${colorize(startData.user_code, "bold")}`);
-  console.log(`Direct link: ${startData.verification_uri_complete}`);
+  console.log(
+    `Direct link: ${normalizeOfficialConductorUrl(startData.verification_uri_complete, backendUrl)}`,
+  );
   console.log("");
   console.log("Only approve the request if the web page shows the same device code.");
   console.log("");
@@ -551,10 +557,17 @@ async function authorizeDeviceAndGetToken() {
       continue;
     }
     if (pollData.status === "approved") {
+      const resolvedBackendUrl = normalizeOfficialConductorUrl(
+        pollData.backend_url || backendUrl,
+        backendUrl,
+      );
       const result = {
         agentToken: pollData.agent_token,
-        backendUrl: pollData.backend_url || backendUrl,
-        websocketUrl: pollData.websocket_url || null,
+        backendUrl: resolvedBackendUrl,
+        websocketUrl: normalizeOfficialConductorUrl(
+          pollData.websocket_url || null,
+          backendUrl,
+        ),
       };
       lastDeviceAuthConfig = result;
       console.log(colorize("✓ Device authorized", "green"));
@@ -571,6 +584,43 @@ async function authorizeDeviceAndGetToken() {
   throw new Error("Device authorization timed out");
 }
 
+function isOfficialConductorBackend(value) {
+  if (typeof value !== "string" || !value.trim()) {
+    return false;
+  }
+  try {
+    const hostname = new URL(value).hostname;
+    return hostname === LEGACY_CONDUCTOR_PUBLIC_HOST || hostname === CONDUCTOR_PUBLIC_HOST;
+  } catch {
+    return false;
+  }
+}
+
+function normalizeOfficialConductorUrl(value, requestBackendUrl) {
+  if (typeof value !== "string" || !value.trim()) {
+    return value;
+  }
+  if (!isOfficialConductorBackend(requestBackendUrl)) {
+    return value;
+  }
+
+  try {
+    const parsed = new URL(value);
+    if (parsed.hostname !== LEGACY_CONDUCTOR_PUBLIC_HOST) {
+      return value;
+    }
+
+    const canonicalOrigin = new URL(CONDUCTOR_PUBLIC_ORIGIN);
+    parsed.protocol = parsed.protocol === "ws:" || parsed.protocol === "wss:"
+      ? "wss:"
+      : canonicalOrigin.protocol;
+    parsed.host = canonicalOrigin.host;
+    return parsed.toString();
+  } catch {
+    return value;
+  }
+}
+
 async function parseJsonResponse(response) {
   try {
     return await response.json();

package/bin/conductor-daemon.js

@@ -9,10 +9,16 @@ import { hideBin } from "yargs/helpers";
 import yaml from "js-yaml";
 
 import { startDaemon } from "../src/daemon.js";
+import {
+  materializeConductorPathEnv,
+  resolveConductorConfigPath,
+  resolveConductorHome,
+} from "../src/conductor-paths.js";
 
 const argv = hideBin(process.argv);
 
 const CLI_NAME = process.env.CONDUCTOR_CLI_NAME || "conductor-daemon";
+const CONDUCTOR_HOME = resolveConductorHome();
 
 function parseJsonArrayEnv(value) {
   if (typeof value !== "string" || !value.trim()) {
@@ -75,8 +81,7 @@ function formatBeijingTimestampForFile(date = new Date()) {
 
 function loadUserConfig(configFilePath) {
   try {
-    const home = os.homedir();
-    const configPath = configFilePath || path.join(home, ".conductor", "config.yaml");
+    const configPath = resolveConductorConfigPath(configFilePath);
     if (!fs.existsSync(configPath)) {
       return {};
     }
@@ -146,7 +151,7 @@ const args = yargs(argv)
   .option("nohup", {
     type: "boolean",
     default: false,
-    describe: "Run in background and write logs to ~/.conductor/logs/<timestamp>.log",
+    describe: `Run in background and write logs to ${path.join(CONDUCTOR_HOME, "logs", "<timestamp>.log")}`,
   })
   .option("force", {
     type: "boolean",
@@ -162,15 +167,21 @@ const args = yargs(argv)
     type: "string",
     describe: "Path to Conductor config file",
   })
-  .example("$0 --config-file ~/.conductor/config.yaml", "Run with daemon_name from config")
+  .example(`$0 --config-file ${resolveConductorConfigPath()}`, "Run with daemon_name from config")
   .example("$0 --nohup", "Run daemon in background with logfile")
   .example("$0 --nohup --force", "Restart daemon in background by stopping the existing one")
   .help()
   .strict()
   .parse();
 
+const materializedConductorPathEnv = materializeConductorPathEnv(args.configFile);
+Object.assign(process.env, materializedConductorPathEnv);
+const effectiveConfigFile = args.configFile
+  ? materializedConductorPathEnv.CONDUCTOR_CONFIG
+  : undefined;
+
 if (args.nohup) {
-  const workspaceRoot = resolveWorkspaceRoot(args.configFile);
+  const workspaceRoot = resolveWorkspaceRoot(effectiveConfigFile);
   const runningPid = findRunningDaemonPid(workspaceRoot);
   if (runningPid && !args.force) {
     process.stderr.write(
@@ -179,7 +190,7 @@ if (args.nohup) {
     process.exit(1);
   }
 
-  const logsDir = path.join(os.homedir(), ".conductor", "logs");
+  const logsDir = path.join(resolveConductorHome(), "logs");
   fs.mkdirSync(logsDir, { recursive: true });
   const timestamp = formatBeijingTimestampForFile(new Date());
   const logPath = path.join(logsDir, `${timestamp}.log`);
@@ -197,7 +208,7 @@ if (args.nohup) {
 
 startDaemon({
   CLEAN_ALL: args.cleanAll,
-  CONFIG_FILE: args.configFile,
+  CONFIG_FILE: effectiveConfigFile,
   FORCE: args.force,
   ...resolveLauncherConfig(),
 });

package/bin/conductor-fire.js

@@ -36,6 +36,7 @@ import {
   normalizeRuntimeBackendAlias,
   normalizeRuntimeBackendName,
 } from "../src/runtime-backends.js";
+import { resolveConductorConfigPath, resolveConductorHome } from "../src/conductor-paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -111,8 +112,7 @@ export function shouldFireReportTaskStatus({ launchedByDaemon = false, phase } =
 
 // Load allow_cli_list from config file (no defaults - must be configured)
 function loadFireConfigYaml(configFilePath) {
-  const home = os.homedir();
-  const configPath = configFilePath || process.env.CONDUCTOR_CONFIG || path.join(home, ".conductor", "config.yaml");
+  const configPath = resolveConductorConfigPath(configFilePath);
   try {
     if (fs.existsSync(configPath)) {
       const content = fs.readFileSync(configPath, "utf8");
@@ -313,14 +313,14 @@ function resolveLockWorkingDirectory(workingDirectory) {
   }
 }
 
-export function resolveFreshSessionBootstrapLockPath(backendName, workingDirectory) {
+export function resolveFreshSessionBootstrapLockPath(backendName, workingDirectory, env = process.env) {
   const normalizedBackend = String(backendName || "").trim().toLowerCase();
   if (normalizedBackend !== "codex") {
     return null;
   }
   const lockKey = `${normalizedBackend}:${resolveLockWorkingDirectory(workingDirectory)}`;
   const digest = createHash("sha1").update(lockKey).digest("hex");
-  return path.join(os.homedir(), ".conductor", "locks", `session-bootstrap-${digest}.lock`);
+  return path.join(resolveConductorHome(env), "locks", `session-bootstrap-${digest}.lock`);
 }
 
 function acquireFileLock(lockPath) {
@@ -605,7 +605,7 @@ async function main() {
       if (discoveryError) {
         throw discoveryError;
       }
-      process.stdout.write(`No supported backends configured.\n\nAdd allow_cli_list to your config file (~/.conductor/config.yaml):\n  allow_cli_list:\n    codex: codex --dangerously-bypass-approvals-and-sandbox\n    claude: claude --dangerously-skip-permissions\n    kimi: kimi\n    opencode: opencode\n`);
+      process.stdout.write(`No supported backends configured.\n\nAdd allow_cli_list to your config file (${resolveConductorConfigPath(cliArgs.configFile)}):\n  allow_cli_list:\n    codex: codex --dangerously-bypass-approvals-and-sandbox\n    claude: claude --dangerously-skip-permissions\n    kimi: kimi\n    opencode: opencode\n`);
     } else {
       if (supportedBackends.length > 0) {
         process.stdout.write(`Supported backends (from config):\n`);
@@ -1306,6 +1306,7 @@ export async function parseCliArgs(argvInput = process.argv) {
   // Handle help early
   if (helpWithoutSeparator) {
     const defaultBackend = supportedBackends[0] || externalBackends[0] || "none";
+    const defaultConfigPath = resolveConductorConfigPath(configFileFromArgs);
     process.stdout.write(`${CLI_NAME} - Conductor-aware AI coding agent runner
 
 Usage: ${CLI_NAME} [options] -- [backend options and prompt]
@@ -1320,7 +1321,7 @@ Options:
   -v, --version         Show Conductor CLI version and exit
   -h, --help            Show this help message
 
-Config file format (~/.conductor/config.yaml):
+Config file format (${defaultConfigPath}):
   allow_cli_list:
     codex: codex --dangerously-bypass-approvals-and-sandbox
     claude: claude --dangerously-skip-permissions
@@ -1335,9 +1336,11 @@ Examples:
   ${CLI_NAME} --backend codex --resume <id>       # Resume Codex session
   ${CLI_NAME} --backend kimi --resume <id>        # Resume Kimi session
   ${CLI_NAME} --list-backends                     # Show configured backends
-  ${CLI_NAME} --config-file ~/.conductor/config.yaml -- "fix the bug"
+  ${CLI_NAME} --config-file ${defaultConfigPath} -- "fix the bug"
 
 Environment:
+  CONDUCTOR_HOME        User data directory [default: ~/.conductor]
+  CONDUCTOR_CONFIG      Config file override (takes precedence over CONDUCTOR_HOME)
   CONDUCTOR_BACKEND     Default backend
   CONDUCTOR_PROJECT_ID  Project ID to attach to
   CONDUCTOR_TASK_ID     Attach to existing task instead of creating new one
@@ -1460,30 +1463,31 @@ function normalizeTaskId(value) {
   return value.trim();
 }
 
-function resolveFireStateDir(workingDirectory) {
+export function resolveFireStateDir(workingDirectory, env = process.env) {
   // Priority:
   //   1. CONDUCTOR_FIRE_STATE_DIR env override (used by tests to isolate the
   //      marker dir into a tmpdir; also handy for ops to relocate state).
-  //   2. Explicit `workingDirectory` argument (legacy callers).
-  //   3. ~/.conductor/state — matches the conductor convention used by the
-  //      session bootstrap locks (see line ~311).
+  //   2. Explicit `workingDirectory` argument. Production marker writes use
+  //      this project-scoped path so commands such as send-file can discover
+  //      the active task while walking up from the current directory.
+  //   3. $CONDUCTOR_HOME/state (defaults to ~/.conductor/state) only when no
+  //      project working directory is available.
   //
   // We deliberately do NOT default to process.cwd(), which would pollute
   // every project directory a user runs `conductor fire` from and cause tests
   // to leak marker files into the repo.
   const envOverride =
-    typeof process.env.CONDUCTOR_FIRE_STATE_DIR === "string" &&
-    process.env.CONDUCTOR_FIRE_STATE_DIR.trim()
-      ? process.env.CONDUCTOR_FIRE_STATE_DIR.trim()
+    typeof env.CONDUCTOR_FIRE_STATE_DIR === "string" &&
+    env.CONDUCTOR_FIRE_STATE_DIR.trim()
+      ? env.CONDUCTOR_FIRE_STATE_DIR.trim()
       : "";
   if (envOverride) {
     return path.resolve(envOverride);
   }
-  const baseDir =
-    typeof workingDirectory === "string" && workingDirectory.trim()
-      ? path.resolve(workingDirectory.trim())
-      : os.homedir();
-  return path.join(baseDir, ".conductor", "state");
+  if (typeof workingDirectory === "string" && workingDirectory.trim()) {
+    return path.join(path.resolve(workingDirectory.trim()), ".conductor", "state");
+  }
+  return path.join(resolveConductorHome(env), "state");
 }
 
 /**

package/bin/conductor-send-file.js

@@ -2,7 +2,6 @@
 
 import fs from "node:fs";
 import fsp from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
@@ -11,9 +10,9 @@ import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 import { ConductorConfig, loadConfig } from "@love-moon/conductor-sdk";
 import { envForExplicitConfigFile } from "../src/config-env.js";
+import { resolveConductorConfigPath } from "../src/conductor-paths.js";
 
 const DEFAULT_MIME_TYPE = "application/octet-stream";
-const DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".conductor", "config.yaml");
 const FIRE_TASK_MARKER_PREFIX = "active-fire";
 
 const EXTENSION_TO_MIME = {
@@ -110,7 +109,7 @@ export function detectTaskId(options = {}) {
 }
 
 function loadCliConfig(configFile, env = process.env) {
-  const configPath = configFile ? path.resolve(configFile) : DEFAULT_CONFIG_PATH;
+  const configPath = resolveConductorConfigPath(configFile, env);
   const configEnv = envForExplicitConfigFile(configFile, env);
   if (fs.existsSync(configPath)) {
     return loadConfig(configPath, { env: configEnv });

package/bin/conductor-serve-ai.js

@@ -117,7 +117,7 @@ async function main() {
             default: false,
             describe: "Overwrite an existing config-ai-serve.yaml",
           })
-          .example("$0 init", "Create ~/.conductor/config-ai-serve.yaml")
+          .example("$0 init", "Create config-ai-serve.yaml under CONDUCTOR_HOME")
           .example("$0 init --config-file /tmp/custom/config.yaml", "Create /tmp/custom/config-ai-serve.yaml"),
       async (args) => {
         const { conductorConfigPath, serveAiConfigPath } = resolveServeAiConfigPaths(args.configFile);

package/bin/conductor.js

@@ -140,6 +140,10 @@ Options:
   -h, --help     Show this help message
   -v, --version  Show version information
 
+Environment:
+  CONDUCTOR_HOME    User data directory (default: ~/.conductor)
+  CONDUCTOR_CONFIG  Config file override (takes precedence over CONDUCTOR_HOME)
+
 Examples:
   conductor fire -- "fix the bug"
   conductor fire --backend claude -- "add feature"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@love-moon/conductor-cli",
-  "version": "0.7.5",
-  "gitCommitId": "702c7c4",
+  "version": "0.7.7",
+  "gitCommitId": "26b2dbb",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lovemoon-ai/conductor.git"
@@ -24,8 +24,8 @@
     "test": "node --test test/*.test.js"
   },
   "dependencies": {
-    "@love-moon/ai-sdk": "0.7.5",
-    "@love-moon/conductor-sdk": "0.7.5",
+    "@love-moon/ai-sdk": "0.7.7",
+    "@love-moon/conductor-sdk": "0.7.7",
     "@github/copilot-sdk": "^0.3.0",
     "chrome-launcher": "^1.2.1",
     "chrome-remote-interface": "^0.33.0",
@@ -38,7 +38,7 @@
   },
   "optionalDependencies": {
     "@roamhq/wrtc": "^0.10.0",
-    "@love-moon/chat-web": "0.7.5"
+    "@love-moon/chat-web": "0.7.7"
   },
   "pnpm": {
     "onlyBuiltDependencies": [

package/src/ai-manager-handlers.js

@@ -9,7 +9,7 @@ const BASE_QUOTA_TOOLS = ["codex", "claude", "kimi", "copilot"];
 
 /**
  * @param {object} opts
- * @param {string} [opts.configPath] Path to ~/.conductor/config.yaml. Defaults to the manager facade default.
+ * @param {string} [opts.configPath] Path to config.yaml. Defaults to $CONDUCTOR_HOME/config.yaml.
  */
 export function createAiManagerHandlers(opts = {}) {
   const manager = new AiManager(opts.configPath ? { configPath: opts.configPath } : undefined);

package/src/cli-update-notifier.js

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 
 import { buildUpgradeCommand, fetchLatestVersion, isNewerVersion } from "./version-check.js";
+import { resolveConductorHome } from "./conductor-paths.js";
 
 export const DEFAULT_VERSION_CHECK_INTERVAL_MS = 12 * 60 * 60 * 1000;
 export const DEFAULT_VERSION_NOTIFY_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -44,8 +44,13 @@ function isTimestampOlderThan(value, ageMs, nowMs) {
 }
 
 export function resolveVersionCheckCachePath(options = {}) {
-  const homeDir = options.homeDir || process.env.HOME || os.homedir() || "/tmp";
-  return path.join(homeDir, ".conductor", DEFAULT_CACHE_FILE);
+  const env = options.env || process.env;
+  const conductorHome = options.conductorHome
+    ? path.resolve(options.conductorHome)
+    : options.homeDir
+      ? resolveConductorHome({}, { userHome: options.homeDir })
+      : resolveConductorHome(env);
+  return path.join(conductorHome, DEFAULT_CACHE_FILE);
 }
 
 export function normalizeVersionCheckCache(value) {
@@ -171,7 +176,9 @@ export async function maybeCheckForUpdates(options = {}) {
   const fetchLatestVersionFn = options.fetchLatestVersion || fetchLatestVersion;
   const cacheOptions = {
     cachePath: options.cachePath,
-    homeDir: options.homeDir || env.HOME,
+    conductorHome: options.conductorHome,
+    homeDir: options.homeDir,
+    env,
     readFile: options.readFile,
     writeFile: options.writeFile,
     mkdir: options.mkdir,

package/src/conductor-paths.js

@@ -0,0 +1,61 @@
+import os from "node:os";
+import path from "node:path";
+
+export const CONDUCTOR_HOME_ENV_VAR = "CONDUCTOR_HOME";
+export const CONDUCTOR_CONFIG_ENV_VAR = "CONDUCTOR_CONFIG";
+
+function normalizeOptionalString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "";
+}
+
+export function resolveUserHome(env = process.env, fallbackHome = os.homedir()) {
+  return (
+    normalizeOptionalString(env?.HOME) ||
+    normalizeOptionalString(env?.USERPROFILE) ||
+    normalizeOptionalString(fallbackHome) ||
+    "/tmp"
+  );
+}
+
+export function resolveHomeRelativePath(value, env = process.env, fallbackHome = os.homedir()) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    return "";
+  }
+  const userHome = resolveUserHome(env, fallbackHome);
+  if (normalized === "~") {
+    return path.resolve(userHome);
+  }
+  if (normalized.startsWith("~/") || normalized.startsWith("~\\")) {
+    return path.resolve(userHome, normalized.slice(2));
+  }
+  return path.resolve(normalized);
+}
+
+export function resolveConductorHome(env = process.env, options = {}) {
+  const configuredHome = normalizeOptionalString(env?.[CONDUCTOR_HOME_ENV_VAR]);
+  if (configuredHome) {
+    return resolveHomeRelativePath(configuredHome, env, options.fallbackHome);
+  }
+  const userHome = normalizeOptionalString(options.userHome) || resolveUserHome(env, options.fallbackHome);
+  return path.join(path.resolve(userHome), ".conductor");
+}
+
+export function resolveConductorConfigPath(configFile, env = process.env, options = {}) {
+  const explicitPath = normalizeOptionalString(configFile);
+  if (explicitPath) {
+    return resolveHomeRelativePath(explicitPath, env, options.fallbackHome);
+  }
+  const configuredPath = normalizeOptionalString(env?.[CONDUCTOR_CONFIG_ENV_VAR]);
+  if (configuredPath) {
+    return resolveHomeRelativePath(configuredPath, env, options.fallbackHome);
+  }
+  return path.join(resolveConductorHome(env, options), "config.yaml");
+}
+
+export function materializeConductorPathEnv(configFile, env = process.env, options = {}) {
+  return {
+    CONDUCTOR_HOME: resolveConductorHome(env, options),
+    CONDUCTOR_CONFIG: resolveConductorConfigPath(configFile, env, options),
+  };
+}

package/src/custom-command-handlers.js

@@ -7,6 +7,8 @@ import { randomUUID } from "node:crypto";
 
 import yaml from "js-yaml";
 
+import { resolveConductorConfigPath } from "./conductor-paths.js";
+
 const VALID_ACTIONS = new Set(["list", "run", "status"]);
 const MAX_TAIL_CHARS = 12_000;
 const MAX_RUNS = 200;
@@ -25,7 +27,7 @@ export const CUSTOM_COMMANDS_CAPABILITY = "custom_commands";
  * @param {typeof spawn} [opts.spawnFn]
  */
 export function createCustomCommandHandlers(opts = {}) {
-  const configPath = opts.configPath || path.join(os.homedir(), ".conductor", "config.yaml");
+  const configPath = resolveConductorConfigPath(opts.configPath);
   const spawnFn = opts.spawnFn || spawn;
   const runs = new Map();
   const runningByKey = new Map();
@@ -202,7 +204,7 @@ export async function loadCustomCommands(configPath) {
  * @param {string} configPath
  * @returns {CustomCommand[]}
  */
-export function parseCustomCommandsConfig(config, configPath = path.join(os.homedir(), ".conductor", "config.yaml")) {
+export function parseCustomCommandsConfig(config, configPath = resolveConductorConfigPath()) {
   const root = config && typeof config === "object" ? config : {};
   const rawCommands = root.custom_commands;
   if (rawCommands === undefined || rawCommands === null) {