@mycompbox/compbox-cli 1.13.0

package/utils/claude-runtime.d.ts

@@ -0,0 +1,116 @@
+/**
+ * claude-runtime (ENG-135) — shared resolver + probe for the local `claude`
+ * CLI binary.
+ *
+ * Root bug this fixes: the `compbox run` daemon spawns `claude` by bare name
+ * with the daemon's inherited PATH. When the daemon is launched by launchd /
+ * a GUI / a Homebrew service, that PATH does NOT include `~/.local/bin` (the
+ * default Claude Code install location), so web-initiated subscription-mode
+ * interviews fail with "claude CLI not found on PATH" even though `claude` is
+ * installed and works fine in the user's interactive shell.
+ *
+ * The fix, in one place, reused by every spawn site:
+ *   1. Recover the *login shell* PATH (what the user actually has), not just
+ *      the daemon's inherited PATH.
+ *   2. Search that PATH plus a set of well-known install directories for an
+ *      executable `claude`, and return its ABSOLUTE path.
+ *   3. Probe that the resolved binary is actually invocable, with a bounded
+ *      timeout that can never hang (mirrors doctor.ts `probeLaunchTarget`).
+ *
+ * Everything here is pure-ish and dependency-injectable so it is unit-testable
+ * without a real `claude` install or spawning real processes.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Well-known absolute directories where `claude` is commonly installed,
+ * searched IN ADDITION to (and after) the login-shell PATH. Exported so the
+ * "not found" error message and the unit tests can reference the exact set of
+ * locations that were searched.
+ *
+ * Order: the canonical Claude Code install dir first, then the two Homebrew
+ * bin dirs, then npm/pnpm global bin dirs derived from the environment.
+ */
+export declare const WELL_KNOWN_DIRS: readonly string[];
+/** Signature of the exec used to recover the login-shell PATH (injectable for tests). */
+export type ExecFileSyncFn = (file: string, args: string[], options: {
+    timeout: number;
+    encoding: 'utf-8';
+}) => string;
+/** Test-only: clear the login-shell PATH cache so caching behavior can be exercised. */
+export declare function resetLoginShellPathCacheForTests(): void;
+/**
+ * Returns the PATH as seen by the user's LOGIN shell (`$SHELL -lic 'echo
+ * $PATH'`), which is what actually contains `~/.local/bin` and Homebrew dirs
+ * for most installs — unlike the possibly-stripped PATH a launchd/GUI-spawned
+ * daemon inherits. Cached after the first successful (or failed) call.
+ *
+ * Falls back to `process.env.PATH ?? ''` on ANY failure: missing `$SHELL`,
+ * a non-zero exit, a spawn error, or a timeout. Never throws.
+ */
+export declare function getLoginShellPath(exec?: ExecFileSyncFn): string;
+/**
+ * The ordered, de-duplicated list of directories searched for `claude`:
+ * every entry on the login-shell PATH first, then WELL_KNOWN_DIRS. Exposed so
+ * the child-env PATH augmentation and tests can reuse the exact search set.
+ */
+export declare function claudeSearchDirs(getPath?: () => string): string[];
+/** Injectable dependencies for resolveClaudeBinary (all default to real impls). */
+export interface ResolveClaudeDeps {
+    /** Source of the search directories (defaults to login-shell PATH + WELL_KNOWN_DIRS). */
+    dirs?: readonly string[];
+    /** Predicate for "this absolute path is an executable file". */
+    isExecutableFile?: (p: string) => boolean;
+}
+/**
+ * Resolves `claude` to an ABSOLUTE path by scanning the login-shell PATH and
+ * the well-known install dirs, returning the first executable match. Returns
+ * `null` when `claude` is not found anywhere. Never throws.
+ */
+export declare function resolveClaudeBinary(deps?: ResolveClaudeDeps): string | null;
+/**
+ * Builds the PATH string to hand a spawned `claude` child: the search dirs
+ * (login-shell PATH + well-known dirs) merged ahead of whatever PATH the
+ * child would otherwise inherit, de-duplicated. This makes even a bare-name
+ * spawn resolvable and lets `claude` itself find any helper binaries it needs.
+ */
+export declare function claudeChildEnvPath(currentPath?: string | undefined): string;
+/**
+ * Actionable "claude not found" message: names every location that was
+ * searched plus the install link. Used both by the runtime probe and by the
+ * subscription-mode spawn's ENOENT handler so the user knows exactly where to
+ * put `claude` (or how to install it).
+ */
+export declare function claudeNotFoundMessage(): string;
+/** Bounded wall-clock budget for `claude --version`; the probe can never hang. */
+export declare const AGENT_RUNTIME_PROBE_TIMEOUT_MS = 5000;
+export interface AgentRuntimeProbe {
+    /**
+     * - `not-found`: `claude` could not be resolved to any path.
+     * - `ok`: the resolved binary ran `--version` and exited 0.
+     * - `error`: the binary was found but failed to run (crash, non-zero exit,
+     *   spawn error, or timeout).
+     */
+    status: 'ok' | 'error' | 'not-found';
+    /** Human-readable detail: version string on ok, the reason otherwise. */
+    detail: string;
+    /** ISO-8601 timestamp of when the probe settled. */
+    checkedAt: string;
+}
+/** Minimal shape of the spawn function so tests can inject a fake child. */
+export type SpawnFn = typeof spawn;
+/** Injectable dependencies for probeAgentRuntime (all default to real impls). */
+export interface ProbeAgentRuntimeDeps {
+    timeoutMs?: number;
+    /** Resolver override (defaults to resolveClaudeBinary). */
+    resolve?: () => string | null;
+    /** Spawn override (defaults to node:child_process spawn). */
+    spawnFn?: SpawnFn;
+}
+/**
+ * Probes whether the local `claude` runtime is invocable. Resolves the binary
+ * first; if absent, returns `not-found` without spawning. Otherwise spawns
+ * `<abs> --version` with a bounded timeout, ALWAYS killing the child on
+ * settle (mirrors doctor.ts `probeLaunchTarget`). Never rejects.
+ */
+export declare function probeAgentRuntime(deps?: ProbeAgentRuntimeDeps): Promise<AgentRuntimeProbe>;
+//# sourceMappingURL=claude-runtime.d.ts.map

package/utils/claude-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-runtime.d.ts","sourceRoot":"","sources":["../../src/utils/claude-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,KAAK,EAAqB,MAAM,oBAAoB,CAAC;AAM9D;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAyB,CAAC;AA0BvE,yFAAyF;AACzF,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,KAC5C,MAAM,CAAC;AAaZ,wFAAwF;AACxF,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,cAAoC,GAAG,MAAM,CA6BpF;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,MAAM,MAA0B,GAAG,MAAM,EAAE,CAcpF;AAeD,mFAAmF;AACnF,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,gEAAgE;IAChE,gBAAgB,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;CAC3C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,iBAAsB,GAAG,MAAM,GAAG,IAAI,CAe/E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,GAAE,MAAM,GAAG,SAA4B,GAAG,MAAM,CAc7F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAM9C;AAMD,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AAEpD,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,WAAW,CAAC;IACrC,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC;AAEnC,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC9B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,qBAA0B,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8E9F"}

package/utils/claude-runtime.js

@@ -0,0 +1,291 @@
+/**
+ * claude-runtime (ENG-135) — shared resolver + probe for the local `claude`
+ * CLI binary.
+ *
+ * Root bug this fixes: the `compbox run` daemon spawns `claude` by bare name
+ * with the daemon's inherited PATH. When the daemon is launched by launchd /
+ * a GUI / a Homebrew service, that PATH does NOT include `~/.local/bin` (the
+ * default Claude Code install location), so web-initiated subscription-mode
+ * interviews fail with "claude CLI not found on PATH" even though `claude` is
+ * installed and works fine in the user's interactive shell.
+ *
+ * The fix, in one place, reused by every spawn site:
+ *   1. Recover the *login shell* PATH (what the user actually has), not just
+ *      the daemon's inherited PATH.
+ *   2. Search that PATH plus a set of well-known install directories for an
+ *      executable `claude`, and return its ABSOLUTE path.
+ *   3. Probe that the resolved binary is actually invocable, with a bounded
+ *      timeout that can never hang (mirrors doctor.ts `probeLaunchTarget`).
+ *
+ * Everything here is pure-ish and dependency-injectable so it is unit-testable
+ * without a real `claude` install or spawning real processes.
+ */
+import { spawn } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants as fsConstants, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, join } from 'node:path';
+/**
+ * Well-known absolute directories where `claude` is commonly installed,
+ * searched IN ADDITION to (and after) the login-shell PATH. Exported so the
+ * "not found" error message and the unit tests can reference the exact set of
+ * locations that were searched.
+ *
+ * Order: the canonical Claude Code install dir first, then the two Homebrew
+ * bin dirs, then npm/pnpm global bin dirs derived from the environment.
+ */
+export const WELL_KNOWN_DIRS = buildWellKnownDirs();
+function buildWellKnownDirs() {
+    const home = homedir();
+    const dirs = [
+        join(home, '.local', 'bin'), // default Claude Code install location
+        '/opt/homebrew/bin', // Homebrew on Apple Silicon
+        '/usr/local/bin', // Homebrew on Intel / common Unix prefix
+    ];
+    // npm global bin — respects an explicit prefix, else the conventional dir.
+    if (process.env.npm_config_prefix) {
+        dirs.push(join(process.env.npm_config_prefix, 'bin'));
+    }
+    dirs.push(join(home, '.npm-global', 'bin'));
+    // pnpm global bin — PNPM_HOME when set, else the per-OS defaults.
+    if (process.env.PNPM_HOME) {
+        dirs.push(process.env.PNPM_HOME);
+    }
+    dirs.push(join(home, 'Library', 'pnpm')); // macOS default
+    dirs.push(join(home, '.local', 'share', 'pnpm')); // Linux default
+    return dirs;
+}
+const LOGIN_SHELL_PATH_TIMEOUT_MS = 2_000;
+/**
+ * Module-local cache of the login-shell PATH. Resolved at most once per
+ * process: a login shell can take a noticeable fraction of a second to start
+ * (it sources the user's full rc/profile), so we pay that cost once. The
+ * cached value is an immutable string — this is a memoised pure result, not
+ * shared mutable state across agents (see the Sub-Agent Isolation Rule).
+ */
+let cachedLoginShellPath = null;
+/** Test-only: clear the login-shell PATH cache so caching behavior can be exercised. */
+export function resetLoginShellPathCacheForTests() {
+    cachedLoginShellPath = null;
+}
+/**
+ * Returns the PATH as seen by the user's LOGIN shell (`$SHELL -lic 'echo
+ * $PATH'`), which is what actually contains `~/.local/bin` and Homebrew dirs
+ * for most installs — unlike the possibly-stripped PATH a launchd/GUI-spawned
+ * daemon inherits. Cached after the first successful (or failed) call.
+ *
+ * Falls back to `process.env.PATH ?? ''` on ANY failure: missing `$SHELL`,
+ * a non-zero exit, a spawn error, or a timeout. Never throws.
+ */
+export function getLoginShellPath(exec = defaultExecFileSync) {
+    if (cachedLoginShellPath !== null) {
+        return cachedLoginShellPath;
+    }
+    const shell = process.env.SHELL;
+    const fallback = process.env.PATH ?? '';
+    if (!shell) {
+        cachedLoginShellPath = fallback;
+        return cachedLoginShellPath;
+    }
+    try {
+        // -l = login shell (sources profile), -i = interactive (sources rc),
+        // -c = run the command. This mirrors how the user's terminal builds PATH.
+        const out = exec(shell, ['-lic', 'echo $PATH'], {
+            timeout: LOGIN_SHELL_PATH_TIMEOUT_MS,
+            encoding: 'utf-8',
+        });
+        // The shell may print rc-file noise before our echo; the PATH is the last
+        // non-empty line.
+        const line = out
+            .split('\n')
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0)
+            .pop();
+        cachedLoginShellPath = line ?? fallback;
+    }
+    catch {
+        cachedLoginShellPath = fallback;
+    }
+    return cachedLoginShellPath;
+}
+function defaultExecFileSync(file, args, options) {
+    return execFileSync(file, args, {
+        timeout: options.timeout,
+        encoding: options.encoding,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+/**
+ * The ordered, de-duplicated list of directories searched for `claude`:
+ * every entry on the login-shell PATH first, then WELL_KNOWN_DIRS. Exposed so
+ * the child-env PATH augmentation and tests can reuse the exact search set.
+ */
+export function claudeSearchDirs(getPath = getLoginShellPath) {
+    const pathDirs = getPath()
+        .split(delimiter)
+        .map((d) => d.trim())
+        .filter((d) => d.length > 0);
+    const seen = new Set();
+    const out = [];
+    for (const dir of [...pathDirs, ...WELL_KNOWN_DIRS]) {
+        if (!seen.has(dir)) {
+            seen.add(dir);
+            out.push(dir);
+        }
+    }
+    return out;
+}
+/** True when `p` exists, is a regular file, and is executable by this process. */
+function isExecutableFile(p) {
+    try {
+        if (!statSync(p).isFile()) {
+            return false;
+        }
+        accessSync(p, fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves `claude` to an ABSOLUTE path by scanning the login-shell PATH and
+ * the well-known install dirs, returning the first executable match. Returns
+ * `null` when `claude` is not found anywhere. Never throws.
+ */
+export function resolveClaudeBinary(deps = {}) {
+    const dirs = deps.dirs ?? claudeSearchDirs();
+    const isExec = deps.isExecutableFile ?? isExecutableFile;
+    const seen = new Set();
+    for (const dir of dirs) {
+        if (!dir || seen.has(dir)) {
+            continue;
+        }
+        seen.add(dir);
+        const candidate = join(dir, 'claude');
+        if (isExec(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Builds the PATH string to hand a spawned `claude` child: the search dirs
+ * (login-shell PATH + well-known dirs) merged ahead of whatever PATH the
+ * child would otherwise inherit, de-duplicated. This makes even a bare-name
+ * spawn resolvable and lets `claude` itself find any helper binaries it needs.
+ */
+export function claudeChildEnvPath(currentPath = process.env.PATH) {
+    const existing = (currentPath ?? '')
+        .split(delimiter)
+        .map((d) => d.trim())
+        .filter((d) => d.length > 0);
+    const seen = new Set();
+    const merged = [];
+    for (const dir of [...claudeSearchDirs(), ...existing]) {
+        if (!seen.has(dir)) {
+            seen.add(dir);
+            merged.push(dir);
+        }
+    }
+    return merged.join(delimiter);
+}
+/**
+ * Actionable "claude not found" message: names every location that was
+ * searched plus the install link. Used both by the runtime probe and by the
+ * subscription-mode spawn's ENOENT handler so the user knows exactly where to
+ * put `claude` (or how to install it).
+ */
+export function claudeNotFoundMessage() {
+    return [
+        'The `claude` CLI could not be located. Searched every directory on the login-shell PATH, plus these well-known install locations:',
+        ...WELL_KNOWN_DIRS.map((d) => `  - ${d}`),
+        'Install Claude Code to use subscription mode: https://code.claude.com',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------
+// Runtime probe — is the resolved `claude` actually invocable?
+// ---------------------------------------------------------------------
+/** Bounded wall-clock budget for `claude --version`; the probe can never hang. */
+export const AGENT_RUNTIME_PROBE_TIMEOUT_MS = 5_000;
+/**
+ * Probes whether the local `claude` runtime is invocable. Resolves the binary
+ * first; if absent, returns `not-found` without spawning. Otherwise spawns
+ * `<abs> --version` with a bounded timeout, ALWAYS killing the child on
+ * settle (mirrors doctor.ts `probeLaunchTarget`). Never rejects.
+ */
+export function probeAgentRuntime(deps = {}) {
+    const timeoutMs = deps.timeoutMs ?? AGENT_RUNTIME_PROBE_TIMEOUT_MS;
+    const resolveBin = deps.resolve ?? (() => resolveClaudeBinary());
+    const spawnFn = deps.spawnFn ?? spawn;
+    const abs = resolveBin();
+    if (!abs) {
+        return Promise.resolve({
+            status: 'not-found',
+            detail: claudeNotFoundMessage(),
+            checkedAt: new Date().toISOString(),
+        });
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let child;
+        let stdout = '';
+        let stderr = '';
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // Child already gone — nothing to clean up.
+            }
+            resolve({ ...result, checkedAt: new Date().toISOString() });
+        };
+        // `settle` closes over `timer`; it can only fire after the handlers below
+        // are attached, by which point `timer` is initialized.
+        const timer = setTimeout(() => {
+            settle({
+                status: 'error',
+                detail: `\`claude --version\` timed out after ${String(timeoutMs / 1000)}s`,
+            });
+        }, timeoutMs);
+        try {
+            child = spawnFn(abs, ['--version'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            resolve({
+                status: 'error',
+                detail: error instanceof Error ? error.message : 'failed to spawn claude',
+                checkedAt: new Date().toISOString(),
+            });
+            return;
+        }
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk.toString('utf-8');
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr += chunk.toString('utf-8');
+        });
+        child.on('error', (error) => {
+            settle({ status: 'error', detail: error.message });
+        });
+        child.on('exit', (code) => {
+            if (code === 0) {
+                settle({ status: 'ok', detail: stdout.trim() || abs });
+                return;
+            }
+            settle({
+                status: 'error',
+                detail: stderr.trim() ||
+                    stdout.trim() ||
+                    `\`claude --version\` exited with code ${String(code ?? 'null')}`,
+            });
+        });
+    });
+}
+//# sourceMappingURL=claude-runtime.js.map

package/utils/claude-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-runtime.js","sourceRoot":"","sources":["../../src/utils/claude-runtime.ts"],"names":[],"mappings":"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"}

package/utils/config-store.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Local configuration store for the CompBox employee agent.
+ *
+ * Persists NON-SECRET pairing configuration to `~/.compbox/config.json`:
+ *   - the central API base URL
+ *   - the per-employee CompBox API token (an `st_...` pairing credential)
+ *   - resolved identity (userId / email / name) for display and doctor checks
+ *   - the selected AI mode
+ *
+ * The AI provider secret (e.g. an Anthropic API key) is NEVER stored here — it
+ * lives in the OS keychain (see `keychain.ts`) and is never transmitted to
+ * central. The API token is a pairing credential and is written to this file
+ * with `0600` permissions (owner-only), mirroring how tools like npm persist
+ * registry tokens in `.npmrc`.
+ *
+ * The config directory can be overridden with the `COMPBOX_CONFIG_DIR`
+ * environment variable (used by tests to avoid touching the real home dir).
+ */
+/**
+ * How the employee's Claude/AI access is provided (the ENG-119 3-mode
+ * agent-invoker decision). `claude-subscription` covers BOTH a personal
+ * Pro/Max login and a company Team-seat login — the daemon cannot tell which
+ * account is logged into the local `claude` CLI, so at the config level they
+ * are one mode. `api-key` is the always-safe default requiring no
+ * acknowledgment; `claude-subscription` requires `agentModeAcknowledged`.
+ */
+export type AiMode = 'claude-subscription' | 'api-key';
+/** Non-secret local configuration written to `~/.compbox/config.json`. */
+export interface CompboxConfig {
+    /** Central CompBox API base URL (e.g. https://compbox.example.com). */
+    apiBaseUrl?: string;
+    /** Per-employee CompBox API token (`st_...`). Pairing credential. */
+    apiToken?: string;
+    /** ID of the API token record (used to rotate/revoke later). */
+    apiTokenId?: string;
+    /** Resolved user id from central (attribution). */
+    userId?: string;
+    /** Resolved user email from central. */
+    email?: string;
+    /** Resolved user display name from central. */
+    userName?: string;
+    /** Selected AI mode. */
+    aiMode?: AiMode;
+    /**
+     * Whether the user has explicitly acknowledged entitlement to use their
+     * Claude Code CLI login for automated/unattended daemon invocation
+     * (required before `claude-subscription` mode may run — ENG-119 decision).
+     * Never set for `api-key` mode, which needs no such gate.
+     */
+    agentModeAcknowledged?: boolean;
+    /** ID of this machine's pairing record on central (Machine.id). */
+    machineId?: string;
+    /** Display name given to this machine at pairing time. */
+    machineName?: string;
+    /**
+     * Route this machine's agent model calls through the local pxpipe proxy to
+     * cut token usage (ENG-E26). Read at daemon startup and promoted to
+     * PXPIPE_ENABLED so it works even when the daemon runs as a background
+     * service (which does not inherit the user's shell env).
+     */
+    pxpipeEnabled?: boolean;
+    /**
+     * Absolute path to the CompBox project repository checkout this machine runs
+     * agent pipelines against (ENG-164). A `start_execution`/`plan` job spawns
+     * the local `claude` CLI in this directory so the repo's `.mcp.json`
+     * (CompBox MCP) and `CLAUDE.md` (@agent routing) load. Set via
+     * `compbox run --project-dir <path>` (persisted) or the `COMPBOX_PROJECT_DIR`
+     * env fallback; a job fails with an actionable message when neither resolves
+     * to a git repository.
+     */
+    projectDir?: string;
+}
+/** Environment fallback for the project repo directory (ENG-164 / H2). */
+export declare const PROJECT_DIR_ENV = "COMPBOX_PROJECT_DIR";
+/** Absolute path to the CompBox config directory (`~/.compbox` by default). */
+export declare function getConfigDir(): string;
+/** Absolute path to the config file. */
+export declare function getConfigPath(): string;
+/**
+ * Read the local config. Returns an empty object if the file is missing or
+ * unreadable/corrupt — callers treat a missing config as "not configured yet".
+ */
+export declare function readConfig(): CompboxConfig;
+/**
+ * Write the full config object, creating the directory if needed and enforcing
+ * owner-only (`0600`) permissions since it contains the API token.
+ */
+export declare function writeConfig(config: CompboxConfig): void;
+/**
+ * Shallow-merge a partial patch into the existing config and persist it.
+ * Returns the merged config.
+ */
+export declare function updateConfig(patch: Partial<CompboxConfig>): CompboxConfig;
+/**
+ * Promote the persisted pxpipe enable flag into the environment (ENG-E26) so
+ * the daemon routes agent calls through pxpipe even when running as a
+ * background service (which does not source the user's shell profile). A pre-set
+ * PXPIPE_ENABLED in the environment always wins and is left untouched.
+ */
+export declare function applyPxpipeEnv(config: CompboxConfig, env?: NodeJS.ProcessEnv): void;
+/**
+ * Resolve the project repository directory for a `start_execution` job (ENG-164
+ * / H2), in a fixed, unit-tested precedence order:
+ *
+ *   1. An explicit `--project-dir <path>` flag (highest — an operator override
+ *      for this run; run.ts also persists it so later runs inherit it).
+ *   2. The `COMPBOX_PROJECT_DIR` environment variable.
+ *   3. The persisted `config.projectDir` (set by a prior `--project-dir`).
+ *
+ * Returns the first non-empty candidate (trimmed), or `undefined` when none is
+ * set. This is a pure resolution helper — it does NOT check that the path is a
+ * git repository; validation is the caller's job so the failure can carry an
+ * actionable, path-specific message (see the invoker's git-repo check).
+ */
+export declare function resolveProjectDir(opts: {
+    flag?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    config?: CompboxConfig | undefined;
+}): string | undefined;
+/**
+ * True when `dir` looks like a git repository — a `.git` entry (directory for a
+ * normal checkout, or a file for a worktree/submodule) exists inside it. Used to
+ * validate {@link resolveProjectDir}'s result before spawning the planner so a
+ * misconfigured path fails fast with an actionable message rather than letting
+ * `claude` start in a non-repo (where `.mcp.json`/`CLAUDE.md` would be absent).
+ */
+export declare function isGitRepoDir(dir: string): boolean;
+//# sourceMappingURL=config-store.d.ts.map

package/utils/config-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-store.d.ts","sourceRoot":"","sources":["../../src/utils/config-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH;;;;;;;GAOG;AACH,MAAM,MAAM,MAAM,GAAG,qBAAqB,GAAG,SAAS,CAAC;AAEvD,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,0EAA0E;AAC1E,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD,+EAA+E;AAC/E,wBAAgB,YAAY,IAAI,MAAM,CAMrC;AAED,wCAAwC;AACxC,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,aAAa,CAc1C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAcvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAKzE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,IAAI,CAIN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IACpC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CACpC,GAAG,MAAM,GAAG,SAAS,CASrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMjD"}