@companyhelm/cli 0.1.5 → 0.3.0

package/README.md

@@ -1,9 +1,14 @@
 # CompanyHelm - Distributed AI Agent Orchestration
 
+<a href="https://discord.gg/YueY3dQM9Q"><img src="https://img.shields.io/discord/1456350064065904867?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt="Discord"></a>
+
 CompanyHelm is an open-source control plane for running AI-agent companies in your own infrastructure.
 It gives teams a way to organize agents by role, keep humans in the loop for approvals and clarification, and run agent workloads in isolated environments instead of opaque hosted black boxes. Each agent can run its own app infrastructure for testing and create PRs autonomously. Spin up container-isolated agent threads with a click.
 
-[Website](https://www.companyhelm.com/)
+[Website](https://www.companyhelm.com/) · [Discord](https://discord.gg/YueY3dQM9Q)
+
+<img width="1843" height="973" alt="Task management" src="https://github.com/user-attachments/assets/c0faa139-06ed-4299-a76f-63c186204038" />
+
 
 ## Quick start
 

package/dist/cli.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export declare function main(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -1,6 +1,18 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 import { buildProgram } from "./commands/register-commands.js";
 import { InteractiveCommandCancelledError } from "./commands/interactive.js";
+import { CliPackageMetadata } from "./core/runtime/CliPackageMetadata.js";
+function shouldPrintVersion(argv = process.argv) {
+    const args = argv.slice(2);
+    return args.length === 1 && (args[0] === "--version" || args[0] === "-V");
+}
 export async function main(argv = process.argv) {
+    if (shouldPrintVersion(argv)) {
+        process.stdout.write(`${new CliPackageMetadata().version()}\n`);
+        return;
+    }
     const program = buildProgram();
     try {
         await program.parseAsync(argv);
@@ -10,9 +22,18 @@ export async function main(argv = process.argv) {
             process.exitCode = 1;
             return;
         }
-        throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        process.exitCode = 1;
+    }
+}
+function isCliEntrypoint(argv = process.argv) {
+    const entrypointPath = argv[1];
+    if (!entrypointPath) {
+        return false;
     }
+    return pathToFileURL(realpathSync(entrypointPath)).href === import.meta.url;
 }
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isCliEntrypoint()) {
     void main();
 }

package/dist/commands/dependencies.js

@@ -19,7 +19,11 @@ import { RuntimeStateStore } from "../core/runtime/RuntimeStateStore.js";
 import { VersionCatalog } from "../core/runtime/VersionCatalog.js";
 import { StatusService } from "../core/status/StatusService.js";
 import { TerminalRenderer } from "../core/ui/TerminalRenderer.js";
+import { LocalConfigStore } from "../core/runtime/LocalConfigStore.js";
+import { PortAllocator } from "../core/runtime/PortAllocator.js";
+import { runStartupPreflightChecks } from "../preflight/runStartupPreflightChecks.js";
 import { ensureGithubAppConfig } from "./setup-github-app.js";
+import { ensureAgentWorkspaceMode } from "./startup-preferences.js";
 function runtimeRoot() {
     return process.env.COMPANYHELM_HOME || path.join(os.homedir(), ".companyhelm");
 }
@@ -36,6 +40,7 @@ export function createDefaultDependencies() {
     const apiEnvFileWriter = new ApiEnvFileWriter(process.cwd());
     const projectPaths = new ProjectPaths(process.cwd());
     const localRepoSourceResolver = new LocalRepoSourceResolver(process.cwd());
+    const localConfigStore = new LocalConfigStore(root);
     const localServiceProcessManager = new LocalServiceProcessManager();
     const apiLocalService = new ApiLocalService(localServiceProcessManager, commandRunner);
     const webLocalService = new WebLocalService(localServiceProcessManager, commandRunner);
@@ -86,11 +91,21 @@ export function createDefaultDependencies() {
         async up(options = {}) {
             const logLevel = options.logLevel ?? "info";
             const useHostDockerRuntime = options.useHostDockerRuntime ?? false;
-            const githubAppConfig = await ensureGithubAppConfig(githubAppConfigStore, process.stdin, process.stdout);
-            const state = stateStore.initialize();
             process.stdout.write(`${renderer.renderBanner()}\n`);
-            const runnerAlreadyRunning = await isRunnerRunning(commandRunner, runnerSupervisor);
             const desiredSources = localRepoSourceResolver.resolve(options);
+            const currentState = stateStore.load();
+            const allocatedPorts = currentState?.ports ?? new PortAllocator().allocate();
+            await runStartupPreflightChecks({
+                commandRunner,
+                currentState,
+                desiredSources,
+                ports: allocatedPorts,
+                readStatus: () => statusService.read()
+            });
+            const workspaceMode = await ensureAgentWorkspaceMode(localConfigStore, process.stdin, process.stdout);
+            const githubAppConfig = await ensureGithubAppConfig(githubAppConfigStore, process.stdin, process.stdout, { workspaceMode });
+            const state = currentState ?? stateStore.initialize();
+            const runnerAlreadyRunning = await isRunnerRunning(commandRunner, runnerSupervisor);
             const versions = versionCatalog.resolve();
             const passwordRecord = createPasswordHash(state.auth.password);
             const startedLocalServices = [];
@@ -100,7 +115,8 @@ export function createDefaultDependencies() {
             apiEnvFileWriter.write(githubAppConfig);
             bootstrapper.writeSeedSql(root, state, passwordRecord.passwordHash, passwordRecord.passwordSalt);
             bootstrapper.writeApiConfig(root, state, logLevel, {
-                databaseHost: desiredSources.api.source === "local" ? "127.0.0.1" : "postgres"
+                databaseHost: desiredSources.api.source === "local" ? "127.0.0.1" : "postgres",
+                githubAppConfig
             });
             bootstrapper.writeFrontendConfig(root, state);
             await stopLocalServicesFromState(stateStore.load(), localServiceProcessManager);
@@ -145,10 +161,12 @@ export function createDefaultDependencies() {
                         logPath: runtimePaths.runnerLogPath(),
                         secret: state.runner.secret,
                         logLevel,
-                        useHostDockerRuntime
+                        useHostDockerRuntime,
+                        workspaceMode,
+                        projectRoot: process.cwd()
                     });
                     process.stdout.write(`${renderer.progress("Starting the runner...")}\n`);
-                    await commandRunner.run(startCommand.command, startCommand.args);
+                    await commandRunner.run(startCommand.command, startCommand.args, undefined, startCommand.env);
                     runnerStarted = true;
                 }
                 if (desiredSources.frontend.source === "local") {
@@ -247,6 +265,7 @@ export function createDefaultDependencies() {
             }
             await dockerStackManager.down({ removeVolumes: true });
             fs.rmSync(projectPaths.apiEnvPath(), { force: true });
+            fs.rmSync(localConfigStore.configPath(), { force: true });
             fs.rmSync(root, { recursive: true, force: true });
             if (options.removeGithubAppConfig) {
                 githubAppConfigStore.delete();

package/dist/commands/interactive.d.ts

@@ -2,5 +2,6 @@ import type { Readable, Writable } from "node:stream";
 export declare class InteractiveCommandCancelledError extends Error {
     constructor(message: string);
 }
+export declare function hasInteractiveTerminal(input: Readable, output: Writable): boolean;
 export declare function requireInteractiveTerminal(input: Readable, output: Writable, message: string): void;
 export declare function unwrapPromptResult<T>(value: T | symbol, message: string, output: Writable): T;

package/dist/commands/interactive.js

@@ -8,8 +8,11 @@ export class InteractiveCommandCancelledError extends Error {
 function isReadableTty(input) {
     return "isTTY" in input && Boolean(input.isTTY);
 }
+export function hasInteractiveTerminal(input, output) {
+    return isReadableTty(input) && clack.isTTY(output);
+}
 export function requireInteractiveTerminal(input, output, message) {
-    if (!isReadableTty(input) || !clack.isTTY(output)) {
+    if (!hasInteractiveTerminal(input, output)) {
         throw new Error(message);
     }
 }

package/dist/commands/logs.js

@@ -1,4 +1,4 @@
-const AVAILABLE_LOG_SERVICES = ["postgres", "api", "frontend", "runner"];
+import { AVAILABLE_MANAGED_SERVICE_NAMES } from "../core/services/ManagedServiceNames.js";
 export function registerLogsCommand(program, dependencies) {
     program
         .command("logs")
@@ -6,7 +6,7 @@ export function registerLogsCommand(program, dependencies) {
         .argument("[service]")
         .action(async (service) => {
         if (!service) {
-            process.stdout.write(`Available services:\n${AVAILABLE_LOG_SERVICES.map((name) => `- ${name}`).join("\n")}\n`);
+            process.stdout.write(`Available services:\n${AVAILABLE_MANAGED_SERVICE_NAMES.map((name) => `- ${name}`).join("\n")}\n`);
             return;
         }
         await dependencies.logs(service);

package/dist/commands/register-commands.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import { createDefaultDependencies } from "./dependencies.js";
+import { CliPackageMetadata } from "../core/runtime/CliPackageMetadata.js";
 import { registerDownCommand } from "./down.js";
 import { registerLogsCommand } from "./logs.js";
 import { registerResetCommand } from "./reset.js";
@@ -8,7 +9,9 @@ import { registerSetImageVersionCommand } from "./set-image-version.js";
 import { registerStatusCommand } from "./status.js";
 import { registerUpCommand } from "./up.js";
 export function buildProgram(dependencies = createDefaultDependencies()) {
-    const program = new Command().name("companyhelm");
+    const program = new Command()
+        .name("companyhelm")
+        .version(new CliPackageMetadata().version());
     registerSetupGithubAppCommand(program);
     registerUpCommand(program, dependencies);
     registerDownCommand(program, dependencies);

package/dist/commands/reset.js

@@ -4,7 +4,7 @@ import { requireInteractiveTerminal, unwrapPromptResult } from "./interactive.js
 export async function confirmReset(input = process.stdin, output = process.stdout) {
     requireInteractiveTerminal(input, output, "reset requires confirmation from a TTY. Re-run with --yes to skip the prompt.");
     const confirmed = await clack.confirm({
-        message: "This will remove CompanyHelm containers, Postgres data, local runtime state, and generated .companyhelm/api/.env. Continue?",
+        message: "This will remove CompanyHelm containers, Postgres data, local runtime state, generated .companyhelm/api/.env, and the CompanyHelm home config. Continue?",
         active: "Yes",
         inactive: "No",
         initialValue: false,

package/dist/commands/set-image-version.js

@@ -78,7 +78,7 @@ export async function runSetImageVersion(options, dependencies = {}) {
 export function registerSetImageVersionCommand(program) {
     program
         .command("set-image-version")
-        .description("Interactively choose an API or frontend image tag and store it in local config.yaml.")
+        .description("Interactively choose an API or frontend image tag and store it in the CompanyHelm home config.")
         .option("-s, --service <service>", "Prefill the service to update (api or frontend)")
         .option("-l, --limit <count>", "How many image tags to show", parsePositiveInteger, 20)
         .action(async (options) => {

package/dist/commands/setup-github-app.d.ts

@@ -2,9 +2,12 @@ import { Writable, type Readable } from "node:stream";
 import type { Command } from "commander";
 import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
 import { type GithubAppConfig } from "../core/config/GithubAppConfig.js";
+import type { AgentWorkspaceMode } from "../core/runtime/LocalConfigStore.js";
 type BrowserUrlOpener = (url: string) => Promise<void>;
 export declare function readPemFromTerminal(input?: Readable, output?: Writable): Promise<string>;
 export declare function promptGithubAppConfig(input?: Readable, output?: Writable, openBrowser?: BrowserUrlOpener): Promise<GithubAppConfig>;
-export declare function ensureGithubAppConfig(store?: GithubAppConfigStore, input?: Readable, output?: Writable): Promise<GithubAppConfig>;
+export declare function ensureGithubAppConfig(store?: GithubAppConfigStore, input?: Readable, output?: Writable, options?: {
+    workspaceMode?: AgentWorkspaceMode;
+}): Promise<GithubAppConfig | null>;
 export declare function registerSetupGithubAppCommand(program: Command, store?: GithubAppConfigStore): void;
 export {};

package/dist/commands/setup-github-app.js

@@ -3,7 +3,7 @@ import chalk from "chalk";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { Writable } from "node:stream";
-import { unwrapPromptResult, requireInteractiveTerminal, InteractiveCommandCancelledError } from "./interactive.js";
+import { unwrapPromptResult, requireInteractiveTerminal, InteractiveCommandCancelledError, hasInteractiveTerminal } from "./interactive.js";
 import { GithubAppConfigStore } from "../core/config/GithubAppConfigStore.js";
 import { normalizeGithubAppConfig } from "../core/config/GithubAppConfig.js";
 const GITHUB_NEW_APP_URL = "https://github.com/settings/apps/new";
@@ -176,17 +176,39 @@ export async function promptGithubAppConfig(input = process.stdin, output = proc
         appPrivateKeyPem,
     });
 }
-export async function ensureGithubAppConfig(store = new GithubAppConfigStore(), input = process.stdin, output = process.stdout) {
+export async function ensureGithubAppConfig(store = new GithubAppConfigStore(), input = process.stdin, output = process.stdout, options = {}) {
     const existingConfig = store.load();
     if (existingConfig) {
         return existingConfig;
     }
-    requireInteractiveTerminal(input, output, `GitHub App config is not set up. Run \`companyhelm setup-github-app\` or rerun \`companyhelm up\` in a TTY.`);
-    clack.intro("CompanyHelm GitHub App setup", { output });
-    clack.note([
-        "No machine GitHub App config was found.",
-        "CompanyHelm will collect it now and then continue startup.",
-    ].join("\n"), "Setup required", { output });
+    if (!hasInteractiveTerminal(input, output)) {
+        return null;
+    }
+    const workspaceMode = options.workspaceMode ?? "dedicated";
+    clack.intro("CompanyHelm GitHub auth", { output });
+    clack.note(workspaceMode === "dedicated"
+        ? [
+            "No machine GitHub App config was found.",
+            "Dedicated workspaces cannot access files from your host system.",
+            "GitHub auth is recommended so agents can clone and work in your repositories.",
+        ].join("\n")
+        : [
+            "No machine GitHub App config was found.",
+            "GitHub auth is optional in current working directory mode.",
+            "Set it up now if you want agents to access GitHub directly from this deployment.",
+        ].join("\n"), "Optional setup", { output });
+    const shouldSetup = unwrapPromptResult(await clack.confirm({
+        message: "Set up GitHub auth now?",
+        active: "Set it up",
+        inactive: "Skip for now",
+        initialValue: false,
+        input,
+        output,
+    }), "GitHub App setup cancelled.", output);
+    if (!shouldSetup) {
+        clack.outro("Skipping GitHub App setup. Continuing startup without GitHub access.", { output });
+        return null;
+    }
     const config = await promptGithubAppConfig(input, output);
     const spinner = clack.spinner({ output });
     spinner.start("Saving machine GitHub App config");

package/dist/commands/startup-preferences.d.ts

@@ -0,0 +1,3 @@
+import type { Readable, Writable } from "node:stream";
+import { LocalConfigStore, type AgentWorkspaceMode } from "../core/runtime/LocalConfigStore.js";
+export declare function ensureAgentWorkspaceMode(store?: LocalConfigStore, input?: Readable, output?: Writable): Promise<AgentWorkspaceMode>;

package/dist/commands/startup-preferences.js

@@ -0,0 +1,39 @@
+import * as clack from "@clack/prompts";
+import { unwrapPromptResult, hasInteractiveTerminal } from "./interactive.js";
+import { LocalConfigStore } from "../core/runtime/LocalConfigStore.js";
+const DEFAULT_WORKSPACE_MODE = "current-working-directory";
+export async function ensureAgentWorkspaceMode(store = new LocalConfigStore(), input = process.stdin, output = process.stdout) {
+    const existingMode = store.load().agentWorkspaceMode;
+    if (existingMode) {
+        return existingMode;
+    }
+    if (!hasInteractiveTerminal(input, output)) {
+        return DEFAULT_WORKSPACE_MODE;
+    }
+    clack.note([
+        "Choose where agent threads should run.",
+        "Dedicated workspaces keep agents isolated from your host filesystem.",
+        "In dedicated mode agents will not have access to files on your system, so GitHub auth is recommended if you want them to clone your repositories.",
+        "Current working directory mode mounts this checkout directly into agent threads.",
+    ].join("\n"), "Agent workspace", { output });
+    const selectedMode = unwrapPromptResult(await clack.select({
+        message: "Where should agents operate?",
+        options: [
+            {
+                value: "current-working-directory",
+                label: "Current working directory",
+                hint: "recommended: agents work directly in this checkout"
+            },
+            {
+                value: "dedicated",
+                label: "Dedicated workspaces directory",
+                hint: "isolated thread workspaces"
+            }
+        ],
+        initialValue: DEFAULT_WORKSPACE_MODE,
+        input,
+        output
+    }), "Workspace selection cancelled.", output);
+    store.setAgentWorkspaceMode(selectedMode);
+    return selectedMode;
+}

package/dist/core/bootstrap/DeploymentBootstrapper.d.ts

@@ -1,4 +1,5 @@
 import type { LogLevel } from "../../commands/dependencies.js";
+import type { GithubAppConfig } from "../config/GithubAppConfig.js";
 import type { RuntimeState } from "../runtime/RuntimeState.js";
 export declare class DeploymentBootstrapper {
     private readonly renderer;
@@ -8,6 +9,7 @@ export declare class DeploymentBootstrapper {
         appPort?: number;
         runnerGrpcPort?: number;
         agentGrpcPort?: number;
+        githubAppConfig?: GithubAppConfig | null;
     }): string;
     writeFrontendConfig(root: string, state: RuntimeState): string;
     private indentBlock;

package/dist/core/bootstrap/DeploymentBootstrapper.js

@@ -25,6 +25,17 @@ export class DeploymentBootstrapper {
         const runnerGrpcPort = options.runnerGrpcPort ?? state.ports.runnerGrpc;
         const agentGrpcPort = options.agentGrpcPort ?? state.ports.agentCliGrpc;
         const databaseHost = options.databaseHost ?? "postgres";
+        const githubConfigLines = options.githubAppConfig
+            ? [
+                '  app_client_id: "${GITHUB_APP_CLIENT_ID}"',
+                '  app_private_key_pem: "${GITHUB_APP_PRIVATE_KEY_PEM}"',
+                '  app_link: "${GITHUB_APP_URL}"'
+            ]
+            : [
+                '  app_client_id: "companyhelm-local-github-disabled"',
+                '  app_private_key_pem: "companyhelm-local-github-disabled"',
+                '  app_link: "https://github.com/apps/companyhelm-local-disabled"'
+            ];
         const yaml = [
             "app:",
             '  host: "0.0.0.0"',
@@ -37,6 +48,17 @@ export class DeploymentBootstrapper {
             "    heartbeat:",
             "      intervalMs: 20000",
             "      jitterMs: 10000",
+            "  workers:",
+            "    agentHeartbeats:",
+            "      intervalSeconds: 60",
+            "      jitterSeconds: 60",
+            "      batchSize: 10",
+            "      leaseSeconds: 120",
+            "    taskWorker:",
+            "      intervalSeconds: 60",
+            "      jitterSeconds: 60",
+            "      batchSize: 10",
+            "      leaseSeconds: 120",
             "agent:",
             "  grpc:",
             '    host: "0.0.0.0"',
@@ -53,9 +75,7 @@ export class DeploymentBootstrapper {
             '      username: "postgres"',
             '      password: "postgres"',
             "github:",
-            '  app_client_id: "${GITHUB_APP_CLIENT_ID}"',
-            '  app_private_key_pem: "${GITHUB_APP_PRIVATE_KEY_PEM}"',
-            '  app_link: "${GITHUB_APP_URL}"',
+            ...githubConfigLines,
             'authProvider: "companyhelm"',
             "auth:",
             "  companyhelm:",

package/dist/core/config/ApiEnvFileWriter.d.ts

@@ -2,5 +2,5 @@ import type { GithubAppConfig } from "./GithubAppConfig.js";
 export declare class ApiEnvFileWriter {
     private readonly projectPaths;
     constructor(projectRoot?: string);
-    write(config: GithubAppConfig): string;
+    write(config: GithubAppConfig | null): string;
 }

package/dist/core/config/ApiEnvFileWriter.js

@@ -15,9 +15,9 @@ export class ApiEnvFileWriter {
     write(config) {
         fs.mkdirSync(this.projectPaths.apiDirectoryPath(), { recursive: true });
         const contents = [
-            `GITHUB_APP_URL=${escapeEnvValue(config.appUrl)}`,
-            `GITHUB_APP_CLIENT_ID=${escapeEnvValue(config.appClientId)}`,
-            `GITHUB_APP_PRIVATE_KEY_PEM=${escapeEnvValue(config.appPrivateKeyPem)}`,
+            `GITHUB_APP_URL=${escapeEnvValue(config?.appUrl ?? "")}`,
+            `GITHUB_APP_CLIENT_ID=${escapeEnvValue(config?.appClientId ?? "")}`,
+            `GITHUB_APP_PRIVATE_KEY_PEM=${escapeEnvValue(config?.appPrivateKeyPem ?? "")}`,
             "",
         ].join("\n");
         fs.writeFileSync(this.projectPaths.apiEnvPath(), contents, "utf8");

package/dist/core/local/ApiLocalService.d.ts

@@ -8,7 +8,7 @@ export interface ApiLocalServiceStartInput {
     configPath: string;
     graphqlUrl: string;
     logPath: string;
-    githubAppConfig: GithubAppConfig;
+    githubAppConfig: GithubAppConfig | null;
     state: RuntimeState;
     logLevel: LogLevel;
 }

package/dist/core/local/ApiLocalService.js

@@ -24,9 +24,9 @@ export class ApiLocalService {
             logPath: input.logPath,
             env: {
                 APP_ENV: "local",
-                GITHUB_APP_CLIENT_ID: input.githubAppConfig.appClientId,
-                GITHUB_APP_URL: input.githubAppConfig.appUrl,
-                GITHUB_APP_PRIVATE_KEY_PEM: input.githubAppConfig.appPrivateKeyPem,
+                GITHUB_APP_CLIENT_ID: input.githubAppConfig?.appClientId ?? "",
+                GITHUB_APP_URL: input.githubAppConfig?.appUrl ?? "",
+                GITHUB_APP_PRIVATE_KEY_PEM: input.githubAppConfig?.appPrivateKeyPem ?? "",
                 COMPANYHELM_JWT_PRIVATE_KEY_PEM: input.state.auth.jwtPrivateKeyPem,
                 COMPANYHELM_JWT_PUBLIC_KEY_PEM: input.state.auth.jwtPublicKeyPem,
                 COMPANYHELM_LOG_LEVEL: input.logLevel

package/dist/core/logs/LogsService.d.ts

@@ -1,5 +1,6 @@
+import { type ManagedServiceKey } from "../services/ManagedServiceNames.js";
 export declare class LogsService {
     private readonly streamServiceLogs;
-    constructor(streamServiceLogs: (service: "postgres" | "api" | "frontend" | "runner") => Promise<void>);
+    constructor(streamServiceLogs: (service: ManagedServiceKey) => Promise<void>);
     stream(service: string): Promise<void>;
 }

package/dist/core/logs/LogsService.js

@@ -1,13 +1,14 @@
-const MANAGED_SERVICES = new Set(["postgres", "api", "frontend", "runner"]);
+import { AVAILABLE_MANAGED_SERVICE_NAMES, resolveManagedServiceKey } from "../services/ManagedServiceNames.js";
 export class LogsService {
     streamServiceLogs;
     constructor(streamServiceLogs) {
         this.streamServiceLogs = streamServiceLogs;
     }
     async stream(service) {
-        if (!MANAGED_SERVICES.has(service)) {
-            throw new Error(`Unknown service '${service}'. Expected one of: ${Array.from(MANAGED_SERVICES).join(", ")}`);
+        const resolvedService = resolveManagedServiceKey(service);
+        if (!resolvedService) {
+            throw new Error(`Unknown service '${service}'. Expected one of: ${AVAILABLE_MANAGED_SERVICE_NAMES.join(", ")}`);
         }
-        await this.streamServiceLogs(service);
+        await this.streamServiceLogs(resolvedService);
     }
 }

package/dist/core/runner/RunnerSupervisor.d.ts

@@ -1,4 +1,5 @@
 import type { LogLevel } from "../../commands/dependencies.js";
+import type { AgentWorkspaceMode } from "../runtime/LocalConfigStore.js";
 export interface RunnerStartInput {
     serverUrl: string;
     agentApiUrl: string;
@@ -6,10 +7,13 @@ export interface RunnerStartInput {
     secret: string;
     logLevel?: LogLevel;
     useHostDockerRuntime?: boolean;
+    workspaceMode?: AgentWorkspaceMode;
+    projectRoot?: string;
 }
 export interface RunnerStartCommand {
     command: string;
     args: string[];
+    env?: NodeJS.ProcessEnv;
 }
 export declare class RunnerSupervisor {
     private readonly configPath;
@@ -19,5 +23,7 @@ export declare class RunnerSupervisor {
     buildStopArgs(): RunnerStartCommand;
     buildStatusArgs(): RunnerStartCommand;
     private resolveRunnerCliPath;
+    private resolveRunnerCliOverridePath;
+    private resolveRunnerEntrypointPath;
     private resolveHostDockerPath;
 }

package/dist/core/runner/RunnerSupervisor.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
 const DEFAULT_HOST_DOCKER_PATH = "unix:///var/run/docker.sock";
 export class RunnerSupervisor {
@@ -15,15 +16,23 @@ export class RunnerSupervisor {
         };
     }
     buildStartArgs(input) {
-        const runnerCliPath = this.resolveRunnerCliPath();
         const logLevel = (input.logLevel ?? "info").toUpperCase();
         const hostDockerArgs = input.useHostDockerRuntime
             ? ["--use-host-docker-runtime", "--host-docker-path", this.resolveHostDockerPath()]
             : [];
+        const runnerEntrypoint = this.resolveRunnerEntrypointPath();
+        const runnerCliOverridePath = this.resolveRunnerCliOverridePath();
+        const env = input.workspaceMode === "current-working-directory" && input.projectRoot
+            ? {
+                COMPANYHELM_RUNNER_WORKSPACE_MODE: input.workspaceMode,
+                COMPANYHELM_RUNNER_PROJECT_ROOT: input.projectRoot,
+            }
+            : undefined;
         return {
             command: process.execPath,
             args: [
-                runnerCliPath,
+                runnerEntrypoint,
+                ...(runnerCliOverridePath ? [runnerCliOverridePath] : []),
                 "--config-path",
                 this.configPath,
                 "start",
@@ -39,7 +48,8 @@ export class RunnerSupervisor {
                 input.secret,
                 "--log-level",
                 logLevel
-            ]
+            ],
+            env
         };
     }
     buildStopArgs() {
@@ -63,6 +73,13 @@ export class RunnerSupervisor {
         const packageJsonPath = require.resolve("@companyhelm/runner/package.json");
         return path.resolve(path.dirname(packageJsonPath), "dist/cli.js");
     }
+    resolveRunnerCliOverridePath() {
+        const overridePath = String(process.env.COMPANYHELM_RUNNER_CLI_PATH || "").trim();
+        return overridePath || null;
+    }
+    resolveRunnerEntrypointPath() {
+        return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "runner-bootstrap.js");
+    }
     resolveHostDockerPath() {
         const dockerHost = String(process.env.DOCKER_HOST || "").trim();
         if (dockerHost) {

package/dist/core/runner/runner-bootstrap.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveRunnerCliEntrypointArg(argv: string[]): string | null;
+export declare function runRunnerBootstrap(): Promise<void>;

package/dist/core/runner/runner-bootstrap.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+const require = createRequire(import.meta.url);
+function applyCurrentWorkingDirectoryMode(projectRoot) {
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    const fsModule = require("node:fs");
+    const originalRmSync = fsModule.rmSync.bind(fsModule);
+    fsModule.rmSync = ((target, options) => {
+        if (path.resolve(String(target)) === resolvedProjectRoot) {
+            return;
+        }
+        return originalRmSync(target, options);
+    });
+    const configModule = require("@companyhelm/runner/dist/config.js");
+    const originalParse = configModule.config.parse.bind(configModule.config);
+    configModule.config.parse = ((input = {}) => originalParse({
+        ...input,
+        workspaces_directory: resolvedProjectRoot
+    }));
+    const threadLifecycle = require("@companyhelm/runner/dist/service/thread_lifecycle.js");
+    threadLifecycle.resolveThreadDirectory = (() => resolvedProjectRoot);
+}
+export function resolveRunnerCliEntrypointArg(argv) {
+    const candidate = String(argv[2] || "").trim();
+    if (!candidate || candidate.startsWith("-")) {
+        return null;
+    }
+    return candidate;
+}
+const workspaceMode = String(process.env.COMPANYHELM_RUNNER_WORKSPACE_MODE || "").trim();
+const projectRoot = String(process.env.COMPANYHELM_RUNNER_PROJECT_ROOT || "").trim();
+export async function runRunnerBootstrap() {
+    if (workspaceMode === "current-working-directory" && projectRoot) {
+        applyCurrentWorkingDirectoryMode(projectRoot);
+    }
+    const runnerEntrypoint = resolveRunnerCliEntrypointArg(process.argv);
+    if (runnerEntrypoint) {
+        process.argv.splice(2, 1);
+    }
+    await import(runnerEntrypoint ? pathToFileURL(runnerEntrypoint).href : "@companyhelm/runner/dist/cli.js");
+}
+const invokedAsEntrypoint = process.argv[1]
+    ? pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url
+    : false;
+if (invokedAsEntrypoint) {
+    await runRunnerBootstrap();
+}

package/dist/core/runtime/CliPackageMetadata.d.ts

@@ -0,0 +1,3 @@
+export declare class CliPackageMetadata {
+    version(): string;
+}

package/dist/core/runtime/CliPackageMetadata.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+export class CliPackageMetadata {
+    version() {
+        const manifestPath = new URL("../../../package.json", import.meta.url);
+        const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return manifest.version;
+    }
+}

package/dist/core/runtime/LocalConfigStore.d.ts

@@ -1,5 +1,7 @@
 import type { ManagedImageService } from "./ManagedImages.js";
+export type AgentWorkspaceMode = "dedicated" | "current-working-directory";
 export interface LocalConfig {
+    agentWorkspaceMode?: AgentWorkspaceMode;
     images: Partial<Record<ManagedImageService, string>>;
 }
 export declare class LocalConfigStore {
@@ -11,6 +13,10 @@ export declare class LocalConfigStore {
         configPath: string;
         image: string;
     };
+    setAgentWorkspaceMode(agentWorkspaceMode: AgentWorkspaceMode): {
+        configPath: string;
+        agentWorkspaceMode: AgentWorkspaceMode;
+    };
     save(config: LocalConfig): void;
     private parse;
 }

package/dist/core/runtime/LocalConfigStore.js

@@ -1,8 +1,12 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+function defaultLocalConfigRoot() {
+    return process.env.COMPANYHELM_HOME || path.join(os.homedir(), ".companyhelm");
+}
 export class LocalConfigStore {
     root;
-    constructor(root = process.cwd()) {
+    constructor(root = defaultLocalConfigRoot()) {
         this.root = root;
     }
     configPath() {
@@ -21,18 +25,30 @@ export class LocalConfigStore {
         this.save(nextConfig);
         return { configPath: this.configPath(), image };
     }
+    setAgentWorkspaceMode(agentWorkspaceMode) {
+        const nextConfig = this.load();
+        nextConfig.agentWorkspaceMode = agentWorkspaceMode;
+        this.save(nextConfig);
+        return { configPath: this.configPath(), agentWorkspaceMode };
+    }
     save(config) {
-        const lines = ["images:"];
+        const lines = [];
+        if (config.agentWorkspaceMode) {
+            lines.push(`agent_workspace_mode: ${config.agentWorkspaceMode}`);
+        }
+        lines.push("images:");
         if (config.images.api) {
             lines.push(`  api: ${config.images.api}`);
         }
         if (config.images.frontend) {
             lines.push(`  frontend: ${config.images.frontend}`);
         }
+        fs.mkdirSync(path.dirname(this.configPath()), { recursive: true });
         fs.writeFileSync(this.configPath(), `${lines.join("\n")}\n`, "utf8");
     }
     parse(content) {
         const images = {};
+        let agentWorkspaceMode;
         let inImagesSection = false;
         for (const rawLine of content.split(/\r?\n/)) {
             const line = rawLine.trimEnd();
@@ -43,6 +59,11 @@ export class LocalConfigStore {
                 inImagesSection = true;
                 continue;
             }
+            const workspaceModeMatch = line.match(/^agent_workspace_mode:\s*(dedicated|current-working-directory)$/);
+            if (workspaceModeMatch) {
+                agentWorkspaceMode = workspaceModeMatch[1];
+                continue;
+            }
             if (inImagesSection && /^[^\s]/.test(line)) {
                 inImagesSection = false;
             }
@@ -54,6 +75,9 @@ export class LocalConfigStore {
                 images[match[1]] = match[2];
             }
         }
-        return { images };
+        return {
+            agentWorkspaceMode,
+            images
+        };
     }
 }

package/dist/core/services/ManagedServiceNames.d.ts

@@ -0,0 +1,5 @@
+export declare const MANAGED_SERVICE_KEYS: readonly ["postgres", "api", "frontend", "runner"];
+export type ManagedServiceKey = (typeof MANAGED_SERVICE_KEYS)[number];
+export declare const MANAGED_SERVICE_NAMES: Record<ManagedServiceKey, string>;
+export declare const AVAILABLE_MANAGED_SERVICE_NAMES: string[];
+export declare function resolveManagedServiceKey(serviceName: string): ManagedServiceKey | null;

package/dist/core/services/ManagedServiceNames.js

@@ -0,0 +1,12 @@
+export const MANAGED_SERVICE_KEYS = ["postgres", "api", "frontend", "runner"];
+export const MANAGED_SERVICE_NAMES = {
+    postgres: "postgres",
+    api: "companyhelm-api",
+    frontend: "companyhelm-web",
+    runner: "companyhelm-runner"
+};
+const SERVICE_NAME_TO_KEY = new Map(Object.entries(MANAGED_SERVICE_NAMES).map(([key, value]) => [value, key]));
+export const AVAILABLE_MANAGED_SERVICE_NAMES = MANAGED_SERVICE_KEYS.map((key) => MANAGED_SERVICE_NAMES[key]);
+export function resolveManagedServiceKey(serviceName) {
+    return SERVICE_NAME_TO_KEY.get(serviceName.trim()) ?? null;
+}

package/dist/preflight/ApiPortPreflightCheck.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class ApiPortPreflightCheck implements PreflightCheck {
+    private readonly delegate;
+    constructor(port: number);
+    run(): Promise<void>;
+}

package/dist/preflight/ApiPortPreflightCheck.js

@@ -0,0 +1,10 @@
+import { PortAvailabilityPreflightCheck } from "./PortAvailabilityPreflightCheck.js";
+export class ApiPortPreflightCheck {
+    delegate;
+    constructor(port) {
+        this.delegate = new PortAvailabilityPreflightCheck("companyhelm-api", port);
+    }
+    run() {
+        return this.delegate.run();
+    }
+}

package/dist/preflight/DockerInstalledPreflightCheck.d.ts

@@ -0,0 +1,7 @@
+import { CommandRunner } from "../core/process/CommandRunner.js";
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class DockerInstalledPreflightCheck implements PreflightCheck {
+    private readonly commandRunner;
+    constructor(commandRunner?: CommandRunner);
+    run(): Promise<void>;
+}

package/dist/preflight/DockerInstalledPreflightCheck.js

@@ -0,0 +1,15 @@
+import { CommandRunner } from "../core/process/CommandRunner.js";
+export class DockerInstalledPreflightCheck {
+    commandRunner;
+    constructor(commandRunner = new CommandRunner()) {
+        this.commandRunner = commandRunner;
+    }
+    async run() {
+        try {
+            await this.commandRunner.capture("docker", ["--version"]);
+        }
+        catch {
+            throw new Error("Docker is required for `companyhelm up`, but the `docker` command is unavailable. Install Docker and make sure it is on your PATH.");
+        }
+    }
+}

package/dist/preflight/PortAvailabilityPreflightCheck.d.ts

@@ -0,0 +1,7 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class PortAvailabilityPreflightCheck implements PreflightCheck {
+    private readonly serviceName;
+    private readonly port;
+    constructor(serviceName: string, port: number);
+    run(): Promise<void>;
+}

package/dist/preflight/PortAvailabilityPreflightCheck.js

@@ -0,0 +1,31 @@
+import net from "node:net";
+export class PortAvailabilityPreflightCheck {
+    serviceName;
+    port;
+    constructor(serviceName, port) {
+        this.serviceName = serviceName;
+        this.port = port;
+    }
+    async run() {
+        await new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.once("error", (error) => {
+                if (error.code === "EADDRINUSE") {
+                    reject(new Error(`${this.serviceName} cannot start because port ${this.port} is already in use.`));
+                    return;
+                }
+                reject(new Error(`${this.serviceName} cannot verify port ${this.port}: ${error.message}`));
+            });
+            server.once("listening", () => {
+                server.close((closeError) => {
+                    if (closeError) {
+                        reject(closeError);
+                        return;
+                    }
+                    resolve();
+                });
+            });
+            server.listen(this.port, "0.0.0.0");
+        });
+    }
+}

package/dist/preflight/PostgresPortPreflightCheck.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class PostgresPortPreflightCheck implements PreflightCheck {
+    private readonly delegate;
+    constructor(port?: number);
+    run(): Promise<void>;
+}

package/dist/preflight/PostgresPortPreflightCheck.js

@@ -0,0 +1,10 @@
+import { PortAvailabilityPreflightCheck } from "./PortAvailabilityPreflightCheck.js";
+export class PostgresPortPreflightCheck {
+    delegate;
+    constructor(port = 5432) {
+        this.delegate = new PortAvailabilityPreflightCheck("Postgres", port);
+    }
+    run() {
+        return this.delegate.run();
+    }
+}

package/dist/preflight/PreflightCheck.d.ts

@@ -0,0 +1,3 @@
+export interface PreflightCheck {
+    run(): Promise<void>;
+}

package/dist/preflight/PreflightCheck.js

@@ -0,0 +1 @@
+export {};

package/dist/preflight/WebPortPreflightCheck.d.ts

@@ -0,0 +1,6 @@
+import type { PreflightCheck } from "./PreflightCheck.js";
+export declare class WebPortPreflightCheck implements PreflightCheck {
+    private readonly delegate;
+    constructor(port: number);
+    run(): Promise<void>;
+}

package/dist/preflight/WebPortPreflightCheck.js

@@ -0,0 +1,10 @@
+import { PortAvailabilityPreflightCheck } from "./PortAvailabilityPreflightCheck.js";
+export class WebPortPreflightCheck {
+    delegate;
+    constructor(port) {
+        this.delegate = new PortAvailabilityPreflightCheck("companyhelm-web", port);
+    }
+    run() {
+        return this.delegate.run();
+    }
+}

package/dist/preflight/runStartupPreflightChecks.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedServiceSources } from "../core/local/LocalRepoSourceResolver.js";
+import type { CommandRunner } from "../core/process/CommandRunner.js";
+import type { RuntimePorts, RuntimeState } from "../core/runtime/RuntimeState.js";
+import type { ManagedServiceStatus } from "../core/status/StatusService.js";
+interface StartupStatusSnapshot {
+    postgres: ManagedServiceStatus;
+    api: ManagedServiceStatus;
+    frontend: ManagedServiceStatus;
+}
+interface StartupPreflightOptions {
+    commandRunner: CommandRunner;
+    currentState: RuntimeState | null;
+    desiredSources: ResolvedServiceSources;
+    ports: RuntimePorts;
+    readStatus: () => Promise<StartupStatusSnapshot>;
+}
+export declare function runStartupPreflightChecks(options: StartupPreflightOptions): Promise<void>;
+export {};

package/dist/preflight/runStartupPreflightChecks.js

@@ -0,0 +1,42 @@
+import { DockerInstalledPreflightCheck } from "./DockerInstalledPreflightCheck.js";
+import { ApiPortPreflightCheck } from "./ApiPortPreflightCheck.js";
+import { PostgresPortPreflightCheck } from "./PostgresPortPreflightCheck.js";
+import { WebPortPreflightCheck } from "./WebPortPreflightCheck.js";
+export async function runStartupPreflightChecks(options) {
+    await new DockerInstalledPreflightCheck(options.commandRunner).run();
+    const currentStatus = await options.readStatus();
+    if (shouldCheckApiPort(options, currentStatus)) {
+        await new ApiPortPreflightCheck(options.ports.apiHttp).run();
+    }
+    if (shouldCheckWebPort(options, currentStatus)) {
+        await new WebPortPreflightCheck(options.ports.ui).run();
+    }
+    if (shouldCheckPostgresPort(options, currentStatus)) {
+        await new PostgresPortPreflightCheck().run();
+    }
+}
+function shouldCheckApiPort(options, currentStatus) {
+    return shouldCheckServicePort("api", options.currentState, currentStatus.api, options.desiredSources.api.source);
+}
+function shouldCheckWebPort(options, currentStatus) {
+    return shouldCheckServicePort("frontend", options.currentState, currentStatus.frontend, options.desiredSources.frontend.source);
+}
+function shouldCheckPostgresPort(options, currentStatus) {
+    if (options.desiredSources.api.source !== "local") {
+        return false;
+    }
+    return currentStatus.postgres !== "running";
+}
+function shouldCheckServicePort(service, currentState, currentStatus, desiredSource) {
+    if (currentStatus !== "running") {
+        return true;
+    }
+    const currentService = currentState?.services[service];
+    if (!currentService) {
+        return true;
+    }
+    if (currentService.source === "docker") {
+        return desiredSource !== "docker";
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@companyhelm/cli",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Bootstrap and manage a local CompanyHelm deployment.",
   "license": "MIT",
   "private": false,
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@companyhelm/runner": "^0.1.1",
+    "@companyhelm/runner": "^0.1.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.1",
     "dockerode": "^4.0.9",