crew-runner 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CrewCortex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# crew-runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs your CrewCortex assistants on your own computer (Mac or Windows), using the Claude Code app (Claude plan) or the Codex app
+(ChatGPT plan) you already signed in to. The runner only calls each app's public commands and never reads its files or login.
+CrewCortex never asks for your Claude or ChatGPT login or token.
+Runs go through the Agent Client Protocol (ACP), so one code path drives both apps.
+
+## Setup
+
+Needs Node.js 20 or later (https://nodejs.org).
+
+1. Install and sign in to one of the apps.
+   - Claude Code: install it, run `claude`, then type `/login`.
+   - Codex: install it, then run `codex login` (a ChatGPT plan works). Codex 0.142 or later is needed.
+2. Link this computer: `npx crew-runner@latest login`. Open the page it prints, sign in and confirm.
+   It links to https://app.crewcortex.com. For another CrewCortex address, add it: `npx crew-runner@latest login https://your-app.example`.
+3. Start it: `npx crew-runner@latest start` and leave the window open. It uses Claude Code if that is ready, otherwise Codex.
+   To choose one, add `--cli codex` (or `--cli claude`), or set `CREW_RUNNER_CLI`.
+
+To skip `npx`, install it once with `npm install -g crew-runner` and use `crew-runner login`, `crew-runner start` and so on.
+
+`crew-runner status` shows whether each app is ready. `crew-runner logout` unlinks this computer.
+
+### Mac
+
+Use Terminal. If the app is not on your PATH, point at it:
+
+```sh
+export CREW_CLAUDE_BIN=/opt/homebrew/bin/claude
+export CREW_CODEX_BIN=/opt/homebrew/bin/codex
+```
+
+### Windows (PowerShell)
+
+Use PowerShell. Install Node.js, then do the three steps above:
+
+```powershell
+npx crew-runner@latest login
+npx crew-runner@latest start
+```
+
+The apps are found on your PATH, including the `.cmd` files npm creates (`claude.cmd`, `codex.cmd`). If they are not on
+your PATH, set the full path for the session (add it to your PowerShell profile to keep it):
+
+```powershell
+$env:CREW_CLAUDE_BIN = "C:\Users\you\AppData\Roaming\npm\claude.cmd"
+$env:CREW_CODEX_BIN = "C:\Users\you\AppData\Roaming\npm\codex.cmd"
+```
+
+Press Ctrl+C (or close the window) to stop the runner. Notes for Windows:
+
+- The runner never starts a general shell. For a `.cmd` file it starts `cmd.exe` itself with every argument quoted.
+  For Claude Code it reads the `.cmd` file to find the real `claude` program and hands that to the adapter,
+  because the adapter cannot start a `.cmd` file. If it cannot find it, set `CREW_CLAUDE_BIN` to `claude.exe` or `cli.js`.
+- Ending a run uses `taskkill /T`, which also ends the app the adapter started.
+- Windows has no file modes, so the 0600 setting on `%USERPROFILE%\.crew-runner\device.json` does nothing there. The file
+  is protected by the permissions of your own user folder. Do not share that folder.
+- Set `CREW_RUNNER_HOME` to keep the device file somewhere else.
+- Only the old `CREW_RUNNER_PROTOCOL=legacy` path has limits on a `.cmd` file: an instruction with a line break fails there.
+  The default ACP path has no such limit.
+
+## What the apps can do during a run
+
+Each run happens in an empty temporary folder, and the only tool is CrewCortex itself. For Codex the run
+uses a read-only sandbox, ignores your own Codex config and rules, and turns off the shell, browser,
+computer, image, web search, plugin and sub-agent tools. The run token is passed through an environment
+variable, never on the command line.
+
+## How runs work (ACP)
+
+For each run the runner starts a small adapter that wraps your own app: `claude-agent-acp` for Claude Code and
+`@agentclientprotocol/codex-acp` for Codex. Both ship as dependencies of this package, so nothing extra is installed. The runner then:
+
+1. Sends `initialize` with file system and terminal access switched off.
+2. Opens a session in an empty temporary folder with the CrewCortex MCP server (the run token goes in a bearer header).
+3. Sends the conversation, forwards streamed text, tool calls and plans to CrewCortex, and returns the final answer.
+4. Answers every permission request itself: it allows only CrewCortex tools and refuses all built-in file, shell and edit tools.
+5. Stops the adapter when the run ends, times out (10 minutes) or you press Ctrl+C.
+
+The runner never calls the ACP `authenticate` step. If the app is signed out the run fails and you sign in to the app yourself.
+Claude Code runs with no built-in tools and none of your own settings. `CLAUDE_CODE_EXECUTABLE` is set from `CREW_CLAUDE_BIN`
+(or `claude`) so the adapter drives your installed app.
+Codex runs through `@agentclientprotocol/codex-acp`, which bundles its own Codex build and uses the login from `codex login`.
+It runs read only, with shell, apps, plugins, browser and web search off. Before each run the runner asks Codex for the names
+of your own MCP servers (`codex mcp list`, names only) and switches every one of them off for that run, so a run sees only the
+CrewCortex tools. If that list fails, the run fails.
+
+### Old direct path
+
+`CREW_RUNNER_PROTOCOL=legacy` switches back to the previous direct adapters (`claude -p` and `codex exec`). It is kept for one
+release and then removed. The default is `acp`.

package/bin/crew-runner.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { register } from "tsx/esm/api";
+
+register();
+const { main } = await import("../src/cli.ts");
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "crew-runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Runs a CrewCortex assistant on your own computer using the Claude Code or Codex app you already signed in to.",
+  "keywords": [
+    "crewcortex",
+    "claude-code",
+    "codex",
+    "acp",
+    "agent"
+  ],
+  "license": "MIT",
+  "homepage": "https://crewcortex.com",
+  "bin": {
+    "crew-runner": "bin/crew-runner.mjs"
+  },
+  "files": [
+    "bin",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agentclientprotocol/codex-acp": "^2.1.1",
+    "@agentclientprotocol/sdk": "^1.7.0",
+    "@zed-industries/claude-agent-acp": "^0.23.1",
+    "tsx": "^4.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  }
+}

package/src/acp.ts

@@ -0,0 +1,324 @@
+import { spawn, spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { existsSync, realpathSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import * as acp from "@agentclientprotocol/sdk";
+import type { Claimed, RunEvent } from "./api.ts";
+import { promptFrom, type Outcome } from "./claude.ts";
+import { DISABLED_FEATURES } from "./codex.ts";
+import { claudeExecutable, killTree } from "./spawn.ts";
+
+// One Agent Client Protocol client for both vendors. We spawn a small adapter (claude-agent-acp or codex-acp) that
+// wraps the member's own signed-in app. The adapter holds the login. We never read the vendors' files, never call
+// `authenticate` (which could start a browser login) and never see a credential: if the app is signed out the
+// session simply fails to open and we report that.
+const MAX_TEXT = 100_000;
+const MAX_EVENT_TEXT = 20_000;
+const FLUSH_MS = 300;
+const CANCEL_GRACE_MS = 5_000;
+const MCP_NAME = "crew";
+const CLAUDE_TOOL_PREFIX = `mcp__${MCP_NAME}__`;
+
+export type AgentName = "claude" | "codex";
+
+type Launch = { command: string; args: string[]; env?: Record<string, string> };
+
+// Finds an installed adapter by walking up node_modules. require.resolve cannot be used: both packages only
+// declare an "import" export condition.
+function adapterFile(pkgName: string, file: string): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (;;) {
+    const p = join(dir, "node_modules", pkgName, file);
+    if (existsSync(p)) return p;
+    const up = dirname(dir);
+    if (up === dir) throw new Error(`${pkgName} is not installed`);
+    dir = up;
+  }
+}
+
+type RunPkg = Pick<Claimed, "instructions" | "mcp_url" | "token">;
+
+export type AgentSpec = {
+  label: string;
+  launch: (pkg: RunPkg, opts: { bin?: string }) => Launch;
+  // false = the launch config already carries our MCP server, so session/new sends none.
+  acpMcp: boolean;
+  // Fields added to session/new for this adapter.
+  sessionMeta: (pkg: Pick<Claimed, "instructions">) => Record<string, unknown> | undefined;
+  // Idle chat mode to force after session/new, or null.
+  mode: string | null;
+  allowTool: (p: acp.RequestPermissionRequest, calls: ReadonlyMap<string, SeenCall>) => boolean;
+};
+
+// Tool calls the agent announced in this session, by id. Some approvals carry only the id.
+export type SeenCall = { title: string; rawInput: unknown };
+
+const field = (v: unknown, key: string): unknown => (v && typeof v === "object" ? (v as Record<string, unknown>)[key] : undefined);
+
+// Claude names every MCP tool mcp__<server>__<tool> in the permission title. Anything else is a built-in tool.
+export function allowClaudeTool(p: acp.RequestPermissionRequest): boolean {
+  return (p.toolCall.title ?? "").startsWith(CLAUDE_TOOL_PREFIX);
+}
+
+// codex-acp marks MCP tool approvals with _meta.is_mcp_tool_approval. The approval usually carries only the id of a
+// tool call announced earlier with rawInput { server, tool }; a standalone one carries rawInput { serverName }.
+// Only our server passes. Commands, edits and anything else are refused.
+export function allowCodexTool(p: acp.RequestPermissionRequest, calls: ReadonlyMap<string, SeenCall>): boolean {
+  if (field(p._meta, "is_mcp_tool_approval") !== true) return false;
+  if (p.toolCall.kind && p.toolCall.kind !== "execute") return false;
+  const seen = calls.get(p.toolCall.toolCallId);
+  const server = seen ? field(seen.rawInput, "server") : field(p.toolCall.rawInput, "serverName");
+  return server === MCP_NAME;
+}
+
+// Codex also loads the member's own MCP servers from their config, and those tools run without asking us. We ask
+// the bundled Codex for the server names (never the files or values) and switch each one off for this session.
+// Ours goes in the same mcp_servers table: the adapter would replace the table if it added ours from session/new.
+// If the list fails the run fails: no lockdown, no run.
+const LIST_TIMEOUT_MS = 20_000;
+
+export function memberMcpNames(listJson: string): string[] {
+  const list: unknown = JSON.parse(listJson);
+  if (!Array.isArray(list)) throw new Error("codex mcp list returned no list");
+  // Already-off servers are left alone: some have no config entry, and a bare { enabled } entry would not load.
+  return list
+    .filter((s) => field(s, "enabled") !== false)
+    .map((s) => field(s, "name"))
+    .filter((n): n is string => typeof n === "string" && n !== MCP_NAME);
+}
+
+function listCodexMcp(): string[] {
+  const codex = createRequire(realpathSync(adapterFile("@agentclientprotocol/codex-acp", "dist/index.js"))).resolve("@openai/codex/bin/codex.js");
+  const r = spawnSync(process.execPath, [codex, "mcp", "list", "--json"], { cwd: tmpdir(), encoding: "utf8", timeout: LIST_TIMEOUT_MS, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] });
+  if (r.status !== 0) throw new Error("could not list Codex MCP servers");
+  return memberMcpNames(r.stdout);
+}
+
+export const CODEX_TOKEN_ENV = "CREW_MCP_TOKEN";
+
+export function codexConfig(pkg: RunPkg, memberServers: readonly string[]): Record<string, unknown> {
+  return {
+    features: Object.fromEntries(DISABLED_FEATURES.map((f) => [f, false])),
+    web_search: "disabled",
+    sandbox_mode: "read-only",
+    approval_policy: "on-request",
+    developer_instructions: pkg.instructions,
+    mcp_servers: {
+      ...Object.fromEntries(memberServers.map((n) => [n, { enabled: false }])),
+      [MCP_NAME]: { url: pkg.mcp_url, bearer_token_env_var: CODEX_TOKEN_ENV },
+    },
+  };
+}
+
+export const AGENTS: Record<AgentName, AgentSpec> = {
+  claude: {
+    label: "Claude Code",
+    launch: (_pkg, opts) => ({
+      command: process.execPath,
+      args: [adapterFile("@zed-industries/claude-agent-acp", "dist/index.js")],
+      // On Windows a .cmd shim cannot be started by the adapter, so it gets the real file the shim points at.
+      env: opts.bin ? { CLAUDE_CODE_EXECUTABLE: claudeExecutable(opts.bin) } : undefined,
+    }),
+    sessionMeta: (pkg) => ({
+      systemPrompt: pkg.instructions,
+      // No built-in tools, no member settings or project files, only the MCP server we pass.
+      claudeCode: { options: { tools: [], settingSources: [], strictMcpConfig: true } },
+    }),
+    // The member's own default mode could be "bypass permissions"; force the asking mode so our handler decides.
+    mode: "default",
+    acpMcp: true,
+    allowTool: allowClaudeTool,
+  },
+  codex: {
+    label: "Codex",
+    // The adapter takes Codex config as one JSON object. NO_BROWSER hides the browser login method, so a signed-out
+    // app fails instead of opening a login page.
+    launch: (pkg) => ({
+      command: process.execPath,
+      args: [adapterFile("@agentclientprotocol/codex-acp", "dist/index.js")],
+      env: {
+        CODEX_CONFIG: JSON.stringify(codexConfig(pkg, listCodexMcp())),
+        [CODEX_TOKEN_ENV]: pkg.token,
+        INITIAL_AGENT_MODE: "read-only",
+        NO_BROWSER: "1",
+      },
+    }),
+    sessionMeta: () => undefined,
+    mode: null,
+    acpMcp: false,
+    allowTool: allowCodexTool,
+  },
+};
+
+type Option = acp.RequestPermissionRequest["options"][number];
+
+// Pure policy: the option id to select, or null to cancel the request.
+export function decide(
+  spec: Pick<AgentSpec, "allowTool">,
+  p: acp.RequestPermissionRequest,
+  calls: ReadonlyMap<string, SeenCall> = new Map(),
+): { allowed: boolean; optionId: string | null } {
+  const allowed = spec.allowTool(p, calls);
+  const pick = (kinds: string[], ids: string[]): Option | undefined =>
+    p.options.find((o) => kinds.includes(o.kind)) ?? p.options.find((o) => ids.includes(o.optionId));
+  // Always the one-shot option, never "always": the next call is judged on its own.
+  const o = allowed ? pick(["allow_once"], ["approved", "allow", "allow_once"]) : pick(["reject_once", "reject_always"], ["cancel", "reject", "denied", "abort"]);
+  return { allowed, optionId: o?.optionId ?? null };
+}
+
+export type RunAcpOptions = {
+  timeoutMs: number;
+  // Override how the adapter is started (tests). Defaults to the registry.
+  launch?: Launch;
+  // The member's own CLI path (CREW_CLAUDE_BIN), handed to the claude adapter.
+  bin?: string;
+  // Abort = run cancelled: session/cancel first, kill after a short grace.
+  signal?: AbortSignal;
+};
+
+type Sink = (events: RunEvent[]) => Promise<void>;
+
+const failed = (error: string, inputTokens = 0, outputTokens = 0): Outcome => ({ status: "failed", text: "", inputTokens, outputTokens, error });
+
+export async function runAcp(agent: AgentName, pkg: Claimed, sink: Sink, opts: RunAcpOptions): Promise<Outcome> {
+  const spec = AGENTS[agent];
+  // Empty temp directory: even if a built-in tool were somehow on, there is nothing of the member's to touch.
+  const cwd = await mkdtemp(join(tmpdir(), "crew-run-"));
+  let child: ReturnType<typeof spawn> | undefined;
+  let timer: NodeJS.Timeout | undefined;
+  let flushTimer: NodeJS.Timeout | undefined;
+  let graceTimer: NodeJS.Timeout | undefined;
+  let onAbort: (() => void) | undefined;
+  try {
+    const launch = opts.launch ?? spec.launch(pkg, { bin: opts.bin });
+    // POSIX: detached makes the adapter lead a process group, so killTree ends it and the app it started. Windows uses taskkill.
+    child = spawn(launch.command, launch.args, { cwd, stdio: ["pipe", "pipe", "ignore"], detached: process.platform !== "win32", windowsHide: true, env: { ...process.env, ...launch.env } });
+    const proc = child;
+    const exited = new Promise<never>((_, reject) => {
+      proc.on("error", () => reject(new Error("runner_failed")));
+      proc.on("close", () => reject(new Error("runner_failed")));
+    });
+    exited.catch(() => undefined);
+    const timedOut = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error("runner_timeout")), opts.timeoutMs);
+    });
+    timedOut.catch(() => undefined);
+
+    // Serialised sink, text coalesced so a token stream is not one HTTP call per chunk.
+    let chain: Promise<void> = Promise.resolve();
+    const send = (events: RunEvent[]) => {
+      if (events.length) chain = chain.then(() => sink(events).catch(() => undefined));
+    };
+    const calls = new Map<string, SeenCall>();
+    let buffered = "";
+    let final = "";
+    const flush = () => {
+      clearTimeout(flushTimer);
+      flushTimer = undefined;
+      while (buffered) {
+        send([{ type: "text", text: buffered.slice(0, MAX_EVENT_TEXT) }]);
+        buffered = buffered.slice(MAX_EVENT_TEXT);
+      }
+    };
+    const onText = (t: string) => {
+      buffered += t;
+      final += t;
+      if (buffered.length >= MAX_EVENT_TEXT) flush();
+      else flushTimer ??= setTimeout(flush, FLUSH_MS);
+    };
+
+    const handleUpdate = (u: acp.SessionUpdate) => {
+      switch (u.sessionUpdate) {
+        case "agent_message_chunk":
+          if (u.content.type === "text") onText(u.content.text);
+          break;
+        case "tool_call":
+          calls.set(u.toolCallId, { title: u.title, rawInput: u.rawInput });
+          flush();
+          final = ""; // the answer is the text after the last tool call
+          send([{ type: "step", kind: "tool", name: u.title.slice(0, 200), input: u.rawInput }]);
+          break;
+        case "tool_call_update":
+          if (u.status === "completed" || u.status === "failed") {
+            flush();
+            send([{ type: "step", kind: "tool", output: u.rawOutput ?? u.content }]);
+          }
+          break;
+        case "plan":
+          send([{ type: "step", kind: "model", name: "plan", output: u.entries.map((e) => e.content) }]);
+          break;
+        default:
+          break;
+      }
+    };
+
+    const stream = acp.ndJsonStream(Writable.toWeb(proc.stdin!) as WritableStream<Uint8Array>, Readable.toWeb(proc.stdout!) as ReadableStream<Uint8Array>);
+
+    const session = acp
+      .client({ name: "crew-runner" })
+      .onRequest(acp.methods.client.session.requestPermission, (ctx) => {
+        const d = decide(spec, ctx.params, calls);
+        return { outcome: d.optionId ? { outcome: "selected" as const, optionId: d.optionId } : { outcome: "cancelled" as const } };
+      })
+      .connectWith(stream, async (ctx) => {
+        await ctx.request(acp.methods.agent.initialize, {
+          protocolVersion: acp.PROTOCOL_VERSION,
+          // No file system or terminal for the agent: it can only use the MCP tools we hand it.
+          clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+        });
+        const request: acp.NewSessionRequest = {
+          cwd,
+          mcpServers: spec.acpMcp ? [{ type: "http", name: MCP_NAME, url: pkg.mcp_url, headers: [{ name: "Authorization", value: `Bearer ${pkg.token}` }] }] : [],
+          _meta: spec.sessionMeta(pkg),
+        };
+        const active = await ctx.buildSession(request).start();
+        try {
+          if (spec.mode) await ctx.request(acp.methods.agent.session.setMode, { sessionId: active.sessionId, modeId: spec.mode });
+          onAbort = () => {
+            void ctx.notify(acp.methods.agent.session.cancel, { sessionId: active.sessionId }).catch(() => undefined);
+            graceTimer = setTimeout(() => killTree(proc), CANCEL_GRACE_MS);
+          };
+          if (opts.signal?.aborted) onAbort();
+          else opts.signal?.addEventListener("abort", onAbort, { once: true });
+          void active.prompt(promptFrom(pkg.messages)).catch(() => undefined);
+          for (;;) {
+            const m = await active.nextUpdate();
+            if (m.kind === "stop") return m.response;
+            handleUpdate(m.update);
+          }
+        } finally {
+          active.dispose();
+        }
+      });
+    session.catch(() => undefined);
+
+    let response: acp.PromptResponse;
+    try {
+      response = await Promise.race([session, exited, timedOut]);
+    } catch (e) {
+      flush();
+      await chain;
+      return failed(e instanceof Error && e.message === "runner_timeout" ? "runner_timeout" : opts.signal?.aborted ? "runner_cancelled" : "runner_failed");
+    }
+    flush();
+    await chain;
+    const inputTokens = response.usage?.inputTokens ?? 0;
+    const outputTokens = response.usage?.outputTokens ?? 0;
+    if (response.stopReason === "cancelled") return failed("runner_cancelled", inputTokens, outputTokens);
+    if (response.stopReason !== "end_turn" && response.stopReason !== "max_tokens") return failed("runner_failed", inputTokens, outputTokens);
+    return { status: "completed", text: final.slice(0, MAX_TEXT), inputTokens, outputTokens };
+  } catch {
+    return failed("runner_failed");
+  } finally {
+    clearTimeout(timer);
+    clearTimeout(flushTimer);
+    clearTimeout(graceTimer);
+    if (onAbort) opts.signal?.removeEventListener("abort", onAbort);
+    if (child) killTree(child);
+    await rm(cwd, { recursive: true, force: true });
+  }
+}

package/src/api.ts

@@ -0,0 +1,56 @@
+import type { Stored } from "./store.ts";
+
+export type Claimed = {
+  run_id: string;
+  instructions: string;
+  messages: { role: string; content: unknown }[];
+  mcp_url: string;
+  token: string;
+};
+
+export type RunEvent =
+  | { type: "text"; text: string }
+  | { type: "step"; kind: "model" | "tool"; name?: string; input?: unknown; output?: unknown };
+
+export type Complete = {
+  run_id: string;
+  status: "completed" | "failed";
+  text: string;
+  input_tokens?: number;
+  output_tokens?: number;
+  error?: string;
+};
+
+export function createApi(cfg: Stored, fetchImpl: typeof fetch = fetch) {
+  const call = (path: string, body: unknown, signal?: AbortSignal) =>
+    fetchImpl(`${cfg.appUrl}/api/runner/${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${cfg.token}` },
+      body: JSON.stringify(body),
+      signal,
+    });
+  return {
+    // true = this device token is accepted by the server.
+    async ping(): Promise<boolean> {
+      return (await call("ping", {})).ok;
+    },
+    // null = no work (204). Throws on auth or server errors so the loop can back off.
+    async claim(signal?: AbortSignal): Promise<Claimed | null> {
+      const res = await call("claim", {}, signal);
+      if (res.status === 204) return null;
+      if (!res.ok) throw new Error(`claim failed (${res.status})`);
+      return (await res.json()) as Claimed;
+    },
+    async events(runId: string, events: RunEvent[]): Promise<void> {
+      if (events.length === 0) return;
+      await call("events", { run_id: runId, events });
+    },
+    async complete(body: Complete): Promise<void> {
+      await call("complete", body);
+    },
+    async revoke(): Promise<boolean> {
+      return (await call("revoke", {})).ok;
+    },
+  };
+}
+export type RunnerApi = ReturnType<typeof createApi>;

package/src/claude.ts

@@ -0,0 +1,155 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import type { Claimed, RunEvent } from "./api.ts";
+import { invocation, spawnBin } from "./spawn.ts";
+
+// Drives the member's own `claude` app in print mode. We only run its public commands (--version, auth status)
+// and read its exit code. We never open its files or environment: whatever login it has stays inside it.
+const SUPPORTED_MAJOR = 2;
+const MIN_MINOR = 1;
+const MAX_TEXT = 100_000;
+
+export type Check = { ok: true; version: string } | { ok: false; message: string };
+
+// On Windows `bin` may be a .cmd shim; invocation() starts it through cmd.exe, never through a general shell.
+export const run = (bin: string, args: string[]): Promise<{ code: number; out: string }> =>
+  new Promise((resolve) => {
+    let inv;
+    try {
+      inv = invocation(bin, args);
+    } catch {
+      resolve({ code: 1, out: "" });
+      return;
+    }
+    execFile(inv.command, inv.args, { timeout: 20_000, windowsHide: true, windowsVerbatimArguments: inv.windowsVerbatimArguments }, (err, stdout) => {
+      const code = err ? (typeof err.code === "number" ? err.code : 1) : 0;
+      resolve({ code, out: String(stdout ?? "") });
+    });
+  });
+
+export function parseVersion(out: string): { major: number; minor: number; text: string } | null {
+  const m = /(\d+)\.(\d+)\.(\d+)/.exec(out);
+  if (!m) return null;
+  return { major: Number(m[1]), minor: Number(m[2]), text: `${m[1]}.${m[2]}.${m[3]}` };
+}
+
+export async function checkClaude(bin = "claude"): Promise<Check> {
+  const v = await run(bin, ["--version"]);
+  if (v.code !== 0) return { ok: false, message: "Claude Code is not installed. Install it, sign in, then run this again." };
+  const ver = parseVersion(v.out);
+  if (!ver) return { ok: false, message: "Could not read the Claude Code version." };
+  if (ver.major !== SUPPORTED_MAJOR || ver.minor < MIN_MINOR) {
+    return { ok: false, message: `Claude Code ${ver.text} is outside the supported range (${SUPPORTED_MAJOR}.${MIN_MINOR}.x and later ${SUPPORTED_MAJOR}.x). Update it.` };
+  }
+  const s = await run(bin, ["auth", "status"]);
+  let signedIn = s.code === 0;
+  try {
+    const json = JSON.parse(s.out) as { loggedIn?: unknown };
+    if (json.loggedIn === false) signedIn = false;
+  } catch {
+    // Not JSON: trust the exit code.
+  }
+  if (!signedIn) return { ok: false, message: "Claude Code is not signed in. Open it, sign in, then run this again." };
+  return { ok: true, version: ver.text };
+}
+
+// Only our MCP server is configured and every built-in file and shell tool is off, so the only tools are ours.
+export function buildArgs(pkg: Pick<Claimed, "instructions" | "mcp_url" | "token">): string[] {
+  const mcp = JSON.stringify({ mcpServers: { crew: { type: "http", url: pkg.mcp_url, headers: { Authorization: `Bearer ${pkg.token}` } } } });
+  return [
+    "-p",
+    "--output-format", "stream-json",
+    "--verbose",
+    "--mcp-config", mcp,
+    "--strict-mcp-config",
+    "--tools", "",
+    "--permission-mode", "dontAsk",
+    "--allowedTools", "mcp__crew",
+    "--system-prompt", pkg.instructions,
+  ];
+}
+
+export function promptFrom(messages: Claimed["messages"]): string {
+  return messages.map((m) => `${m.role}: ${typeof m.content === "string" ? m.content : JSON.stringify(m.content)}`).join("\n\n");
+}
+
+export type Outcome = { status: "completed" | "failed"; text: string; inputTokens: number; outputTokens: number; costMicroUsd?: number; error?: string };
+
+type Block = { type?: string; text?: string; name?: string; input?: unknown; content?: unknown };
+type Line = {
+  type?: string;
+  message?: { content?: Block[] };
+  result?: string;
+  is_error?: boolean;
+  total_cost_usd?: number;
+  usage?: { input_tokens?: number; output_tokens?: number };
+};
+
+// One stream-json line -> zero or more events for the server.
+export function eventsFromLine(line: Line): RunEvent[] {
+  const out: RunEvent[] = [];
+  const blocks = line.message?.content;
+  if (!Array.isArray(blocks)) return out;
+  for (const b of blocks) {
+    if (line.type === "assistant" && b.type === "tool_use") out.push({ type: "step", kind: "tool", name: b.name, input: b.input });
+    if (line.type === "user" && b.type === "tool_result") out.push({ type: "step", kind: "tool", output: b.content });
+  }
+  return out;
+}
+
+export async function runClaude(
+  pkg: Claimed,
+  sink: (events: RunEvent[]) => Promise<void>,
+  opts: { bin?: string; timeoutMs: number },
+): Promise<Outcome> {
+  // Empty temp directory: even if a built-in tool were somehow on, there is nothing of the member's to touch.
+  const cwd = await mkdtemp(join(tmpdir(), "crew-run-"));
+  let child;
+  try {
+    child = spawnBin(opts.bin ?? "claude", buildArgs(pkg), { cwd, stdio: ["pipe", "pipe", "ignore"] });
+  } catch {
+    // Windows .cmd shim given an argument it cannot carry (a line break in the instructions).
+    await rm(cwd, { recursive: true, force: true });
+    return { status: "failed", text: "", inputTokens: 0, outputTokens: 0, error: "runner_failed" };
+  }
+  const timer = setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs);
+  child.stdin?.on("error", () => undefined);
+  child.stdin?.end(promptFrom(pkg.messages));
+
+  let result: Line | null = null;
+  const pending: Promise<void>[] = [];
+  const rl = createInterface({ input: child.stdout! });
+  rl.on("line", (raw) => {
+    let line: Line;
+    try {
+      line = JSON.parse(raw) as Line;
+    } catch {
+      return;
+    }
+    if (line.type === "result") result = line;
+    const events = eventsFromLine(line);
+    if (events.length) pending.push(sink(events).catch(() => undefined));
+  });
+  const code = await new Promise<number>((resolve) => {
+    child.on("error", () => resolve(127));
+    child.on("close", (c) => resolve(c ?? 1));
+  });
+  clearTimeout(timer);
+  await Promise.all(pending);
+  await rm(cwd, { recursive: true, force: true });
+
+  const r = result as Line | null;
+  if (!r || r.is_error || code !== 0) {
+    return { status: "failed", text: "", inputTokens: 0, outputTokens: 0, error: "runner_failed" };
+  }
+  return {
+    status: "completed",
+    text: (r.result ?? "").slice(0, MAX_TEXT),
+    inputTokens: r.usage?.input_tokens ?? 0,
+    outputTokens: r.usage?.output_tokens ?? 0,
+    costMicroUsd: undefined,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,161 @@
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createApi } from "./api.ts";
+import { runAcp } from "./acp.ts";
+import { checkClaude, runClaude, type Check } from "./claude.ts";
+import { checkCodex, runCodex } from "./codex.ts";
+import { loop, RUN_TIMEOUT_MS, type Runner } from "./loop.ts";
+import * as store from "./store.ts";
+
+const DEFAULT_APP_URL = "https://app.crewcortex.com";
+const LINK_WAIT_MS = 5 * 60 * 1000;
+const LINK_POLL_MS = 2_000;
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+function openBrowser(url: string): void {
+  // Not `cmd /c start`: cmd treats the & in a URL as the end of the command. rundll32 takes the URL as one argument.
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url] : [url];
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => undefined).unref();
+  } catch {
+    // The URL is printed too.
+  }
+}
+
+// The token is made here and never sent. The server only gets its SHA-256 (the "code") through the signed-in member.
+async function login(appUrlArg: string | undefined): Promise<number> {
+  const appUrl = (appUrlArg || process.env.CREW_APP_URL || DEFAULT_APP_URL).replace(/\/+$/, "");
+  if (!/^https?:\/\//.test(appUrl)) {
+    console.error("Usage: crew-runner login [app url]");
+    return 2;
+  }
+  // 32 bytes base64url (43 chars): the only shape the server's bearerToken() accepts.
+  const token = randomBytes(32).toString("base64url");
+  const code = createHash("sha256").update(token).digest("hex");
+  const url = `${appUrl}/runner/link?code=${code}`;
+  console.log(`Open this page, sign in and confirm this computer:\n${url}`);
+  openBrowser(url);
+  const api = createApi({ appUrl, token });
+  const until = Date.now() + LINK_WAIT_MS;
+  while (Date.now() < until) {
+    if (await api.ping().catch(() => false)) {
+      await store.save({ appUrl, token });
+      console.log("Linked. Now run `npx crew-runner@latest start` (or `crew-runner start` if you installed it) and leave it running.");
+      return 0;
+    }
+    await sleep(LINK_POLL_MS);
+  }
+  console.error("Timed out waiting for the link to be confirmed.");
+  return 1;
+}
+
+type CliName = "claude" | "codex";
+
+// Default is the ACP path. CREW_RUNNER_PROTOCOL=legacy keeps the old direct adapters for one release.
+const legacy = () => process.env.CREW_RUNNER_PROTOCOL === "legacy";
+
+const CLIS: Record<CliName, { label: string; bin: () => string; check: (bin: string) => Promise<Check>; runner: (bin: string) => Runner }> = {
+  claude: {
+    label: "Claude Code",
+    bin: () => process.env.CREW_CLAUDE_BIN || "claude",
+    check: checkClaude,
+    runner: (bin) => (pkg, sink, signal) =>
+      legacy() ? runClaude(pkg, sink, { bin, timeoutMs: RUN_TIMEOUT_MS }) : runAcp("claude", pkg, sink, { bin, timeoutMs: RUN_TIMEOUT_MS, signal }),
+  },
+  codex: {
+    label: "Codex",
+    bin: () => process.env.CREW_CODEX_BIN || "codex",
+    check: checkCodex,
+    runner: (bin) => (pkg, sink, signal) =>
+      legacy() ? runCodex(pkg, sink, { bin, timeoutMs: RUN_TIMEOUT_MS }) : runAcp("codex", pkg, sink, { timeoutMs: RUN_TIMEOUT_MS, signal }),
+  },
+};
+const CLI_NAMES = Object.keys(CLIS) as CliName[];
+
+function flagValue(args: string[], flag: string): string | undefined {
+  const i = args.indexOf(flag);
+  if (i >= 0) return args[i + 1];
+  return args.find((a) => a.startsWith(`${flag}=`))?.slice(flag.length + 1);
+}
+
+// Picks which app runs the agents: --cli, then CREW_RUNNER_CLI, else the first one that is installed and signed in.
+async function chooseCli(args: string[]): Promise<{ name: CliName; version: string } | { error: string }> {
+  const asked = flagValue(args, "--cli") ?? process.env.CREW_RUNNER_CLI;
+  if (asked) {
+    if (!CLI_NAMES.includes(asked as CliName)) return { error: `Unknown --cli "${asked}". Use claude or codex.` };
+    const name = asked as CliName;
+    const check = await CLIS[name].check(CLIS[name].bin());
+    return check.ok ? { name, version: check.version } : { error: check.message };
+  }
+  const messages: string[] = [];
+  for (const name of CLI_NAMES) {
+    const check = await CLIS[name].check(CLIS[name].bin());
+    if (check.ok) return { name, version: check.version };
+    messages.push(check.message);
+  }
+  return { error: messages.join("\n") };
+}
+
+async function start(args: string[]): Promise<number> {
+  const cfg = await store.load();
+  if (!cfg) {
+    console.error("Not linked. Run `npx crew-runner@latest login` first.");
+    return 1;
+  }
+  const chosen = await chooseCli(args);
+  if ("error" in chosen) {
+    console.error(chosen.error);
+    return 1;
+  }
+  const api = createApi(cfg);
+  if (!(await api.ping().catch(() => false))) {
+    console.error("The server did not accept this device. Run `npx crew-runner@latest login` again.");
+    return 1;
+  }
+  const cli = CLIS[chosen.name];
+  console.log(`Ready. ${cli.label} ${chosen.version}. Waiting for runs. Press Ctrl+C to stop.`);
+  const ac = new AbortController();
+  process.once("SIGINT", () => ac.abort());
+  process.once("SIGTERM", () => ac.abort());
+  // Windows sends SIGBREAK (Ctrl+Break, closing the console window) instead of SIGTERM.
+  if (process.platform === "win32") process.once("SIGBREAK", () => ac.abort());
+  await loop(api, cli.runner(cli.bin()), ac.signal, (m) => console.log(m));
+  return 0;
+}
+
+async function status(): Promise<number> {
+  const cfg = await store.load();
+  if (!cfg) {
+    console.log("Not linked.");
+    return 1;
+  }
+  const linked = await createApi(cfg).ping().catch(() => false);
+  console.log(`Server: ${cfg.appUrl}`);
+  console.log(`Device: ${linked ? "linked" : "not accepted (run login again)"}`);
+  let anyReady = false;
+  for (const name of CLI_NAMES) {
+    const check = await CLIS[name].check(CLIS[name].bin());
+    anyReady ||= check.ok;
+    console.log(`${CLIS[name].label}: ${check.ok ? `ready (${check.version})` : check.message}`);
+  }
+  return linked && anyReady ? 0 : 1;
+}
+
+async function logout(): Promise<number> {
+  const cfg = await store.load();
+  if (cfg) await createApi(cfg).revoke().catch(() => false);
+  await store.clear();
+  console.log("Logged out. This device can no longer receive runs.");
+  return 0;
+}
+
+export async function main(argv: string[]): Promise<number> {
+  const [cmd, arg] = argv;
+  if (cmd === "login") return login(arg);
+  if (cmd === "start") return start(argv.slice(1));
+  if (cmd === "status") return status();
+  if (cmd === "logout") return logout();
+  console.log("Usage: crew-runner <login [app url] | start [--cli claude|codex] | status | logout>");
+  return cmd ? 2 : 0;
+}

package/src/codex.ts

@@ -0,0 +1,158 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import type { Claimed, RunEvent } from "./api.ts";
+import { spawnBin } from "./spawn.ts";
+import { parseVersion, promptFrom, run, type Check, type Outcome } from "./claude.ts";
+
+// Drives the member's own `codex` app in exec mode. Like claude.ts we only run its public commands
+// (--version, login status) and read the exit code. We never open its files or environment.
+const MIN_CODEX_MAJOR = 0;
+const MIN_CODEX_MINOR = 142;
+const MAX_TEXT = 100_000;
+const TOKEN_ENV = "CREW_RUN_TOKEN";
+
+// Every enabled feature in `codex features list` that adds tool surface (checked on 0.142.5). Our MCP server is the only
+// intended tool, so the shell, browser, computer, image, apps, plugin and sub-agent tools are all switched off.
+export const DISABLED_FEATURES = [
+  "shell_tool",
+  "unified_exec",
+  "apps",
+  "browser_use",
+  "browser_use_external",
+  "browser_use_full_cdp_access",
+  "computer_use",
+  "in_app_browser",
+  "image_generation",
+  "multi_agent",
+  "plugins",
+  "tool_suggest",
+  "goals",
+  "hooks",
+  "skill_mcp_dependency_install",
+] as const;
+
+export async function checkCodex(bin = "codex"): Promise<Check> {
+  const v = await run(bin, ["--version"]);
+  if (v.code !== 0) return { ok: false, message: "Codex is not installed. Install it, sign in with `codex login`, then run this again." };
+  const ver = parseVersion(v.out);
+  if (!ver) return { ok: false, message: "Could not read the Codex version." };
+  if (ver.major < MIN_CODEX_MAJOR || (ver.major === MIN_CODEX_MAJOR && ver.minor < MIN_CODEX_MINOR)) {
+    return { ok: false, message: `Codex ${ver.text} is too old (${MIN_CODEX_MAJOR}.${MIN_CODEX_MINOR}.x or later is needed). Update it.` };
+  }
+  const s = await run(bin, ["login", "status"]);
+  if (s.code !== 0) return { ok: false, message: "Codex is not signed in. Run `codex login`, then run this again." };
+  return { ok: true, version: ver.text };
+}
+
+// The run token is NOT in these args: Codex reads it from the child env var named by bearer_token_env_var.
+// Values go through JSON.stringify, which is a valid TOML basic string. The prompt is sent on stdin ("-").
+export function buildCodexArgs(pkg: Pick<Claimed, "instructions" | "mcp_url">, cwd: string): string[] {
+  const args = [
+    "exec",
+    "--json",
+    "-s", "read-only",
+    "--ephemeral",
+    "--skip-git-repo-check",
+    "--ignore-user-config",
+    "--ignore-rules",
+    "-C", cwd,
+  ];
+  for (const f of DISABLED_FEATURES) args.push("--disable", f);
+  const cfg: [string, string][] = [
+    ["web_search", JSON.stringify("disabled")],
+    ["approval_policy", JSON.stringify("never")],
+    ["developer_instructions", JSON.stringify(pkg.instructions)],
+    ["mcp_servers.crew.url", JSON.stringify(pkg.mcp_url)],
+    ["mcp_servers.crew.bearer_token_env_var", JSON.stringify(TOKEN_ENV)],
+    ["mcp_servers.crew.default_tools_approval_mode", JSON.stringify("approve")],
+    ["mcp_servers.crew.required", "true"],
+  ];
+  for (const [k, v] of cfg) args.push("-c", `${k}=${v}`);
+  args.push("-");
+  return args;
+}
+
+type Item = {
+  type?: string;
+  text?: string;
+  server?: string;
+  tool?: string;
+  arguments?: unknown;
+  result?: { content?: unknown; structured_content?: unknown } | null;
+  error?: { message?: string } | null;
+};
+type Line = {
+  type?: string;
+  item?: Item;
+  usage?: { input_tokens?: number; output_tokens?: number };
+};
+
+// One `codex exec --json` line -> zero or more events for the server.
+export function codexEventsFromLine(line: Line): RunEvent[] {
+  const item = line.item;
+  if (!item || item.type !== "mcp_tool_call") return [];
+  if (line.type === "item.started") {
+    return [{ type: "step", kind: "tool", name: `mcp__${item.server}__${item.tool}`, input: item.arguments }];
+  }
+  if (line.type === "item.completed") {
+    const output = item.error ? item.error.message : (item.result?.structured_content ?? item.result?.content);
+    return [{ type: "step", kind: "tool", output }];
+  }
+  return [];
+}
+
+export async function runCodex(
+  pkg: Claimed,
+  sink: (events: RunEvent[]) => Promise<void>,
+  opts: { bin?: string; timeoutMs: number },
+): Promise<Outcome> {
+  // Empty temp directory, as in claude.ts: there is nothing of the member's to touch.
+  const cwd = await mkdtemp(join(tmpdir(), "crew-run-"));
+  const env = { ...process.env, [TOKEN_ENV]: pkg.token };
+  const child = spawnBin(opts.bin ?? "codex", buildCodexArgs(pkg, cwd), { cwd, env, stdio: ["pipe", "pipe", "ignore"] });
+  const timer = setTimeout(() => child.kill("SIGKILL"), opts.timeoutMs);
+  child.stdin!.on("error", () => undefined);
+  child.stdin!.end(promptFrom(pkg.messages));
+
+  let text = "";
+  let usage: Line["usage"];
+  let completed = false;
+  let failed = false;
+  const pending: Promise<void>[] = [];
+  const rl = createInterface({ input: child.stdout! });
+  rl.on("line", (raw) => {
+    let line: Line;
+    try {
+      line = JSON.parse(raw) as Line;
+    } catch {
+      return;
+    }
+    if (line.type === "turn.completed") {
+      completed = true;
+      usage = line.usage;
+    }
+    if (line.type === "turn.failed") failed = true;
+    if (line.type === "item.completed" && line.item?.type === "agent_message") text = line.item.text ?? "";
+    const events = codexEventsFromLine(line);
+    if (events.length) pending.push(sink(events).catch(() => undefined));
+  });
+  const code = await new Promise<number>((resolve) => {
+    child.on("error", () => resolve(127));
+    child.on("close", (c) => resolve(c ?? 1));
+  });
+  clearTimeout(timer);
+  await Promise.all(pending);
+  await rm(cwd, { recursive: true, force: true });
+
+  if (!completed || failed || code !== 0) {
+    return { status: "failed", text: "", inputTokens: 0, outputTokens: 0, error: "runner_failed" };
+  }
+  return {
+    status: "completed",
+    text: text.slice(0, MAX_TEXT),
+    inputTokens: usage?.input_tokens ?? 0,
+    outputTokens: usage?.output_tokens ?? 0,
+  };
+}

package/src/loop.ts

@@ -0,0 +1,38 @@
+import type { Claimed, RunEvent, RunnerApi } from "./api.ts";
+import type { Outcome } from "./claude.ts";
+
+export const RUN_TIMEOUT_MS = 10 * 60 * 1000;
+const BACKOFF_MS = 5_000;
+
+// `signal` aborts when the runner is stopped (Ctrl+C): the ACP path cancels the agent turn, the legacy path ignores it.
+export type Runner = (pkg: Claimed, sink: (events: RunEvent[]) => Promise<void>, signal?: AbortSignal) => Promise<Outcome>;
+
+export async function handleRun(api: RunnerApi, pkg: Claimed, runner: Runner, signal?: AbortSignal): Promise<void> {
+  const outcome = await runner(pkg, (events) => api.events(pkg.run_id, events), signal);
+  await api.complete({
+    run_id: pkg.run_id,
+    status: outcome.status,
+    text: outcome.text,
+    input_tokens: outcome.inputTokens,
+    output_tokens: outcome.outputTokens,
+    error: outcome.error,
+  });
+}
+
+// Claim, run, complete, repeat. A failed claim (network, 401) waits and tries again until stopped.
+export async function loop(api: RunnerApi, runner: Runner, signal: AbortSignal, log: (m: string) => void): Promise<void> {
+  while (!signal.aborted) {
+    try {
+      const pkg = await api.claim(signal);
+      if (pkg) {
+        log(`run ${pkg.run_id} started`);
+        await handleRun(api, pkg, runner, signal);
+        log(`run ${pkg.run_id} finished`);
+      }
+    } catch {
+      if (signal.aborted) return;
+      log("could not reach the server, retrying");
+      await new Promise((r) => setTimeout(r, BACKOFF_MS));
+    }
+  }
+}

package/src/spawn.ts

@@ -0,0 +1,120 @@
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { win32 } from "node:path";
+
+// Windows launch helpers. On Windows the apps installed with npm are .cmd shims, and a spawn without a shell cannot
+// start them (ENOENT, or EINVAL on current Node). We never use `shell: true`. For a shim we start cmd.exe ourselves
+// with every argument quoted for it. Everything here is a no-op on Mac and Linux. The run token is never put in
+// these arguments: it travels in an environment variable or a request header.
+type Platform = NodeJS.Platform;
+type Exists = (path: string) => boolean;
+
+const DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+const SHIM = /\.(cmd|bat)$/i;
+// Characters cmd.exe treats as syntax.
+const META = /([()\][%!^"`<>&|;, *?])/g;
+
+export const isShim = (path: string): boolean => SHIM.test(path);
+
+// "claude" -> "C:\\Users\\me\\AppData\\Roaming\\npm\\claude.cmd" by walking PATH with PATHEXT, as cmd.exe would.
+// A path with a folder in it is only tried with the extensions. Anything not found is returned unchanged.
+export function resolveBin(bin: string, platform: Platform = process.platform, env: NodeJS.ProcessEnv = process.env, exists: Exists = existsSync): string {
+  if (platform !== "win32") return bin;
+  // Lower case: Windows file names are not case sensitive, and this keeps the result stable.
+  const exts = (env.PATHEXT ?? DEFAULT_PATHEXT).toLowerCase().split(";").filter(Boolean);
+  const names = win32.extname(bin) ? [bin, ...exts.map((e) => bin + e)] : exts.map((e) => bin + e);
+  const dirs = /[\\/]/.test(bin) ? [""] : (env.PATH ?? env.Path ?? "").split(";").filter(Boolean);
+  for (const dir of dirs) {
+    for (const name of names) {
+      const candidate = dir ? win32.join(dir, name) : name;
+      if (exists(candidate)) return candidate;
+    }
+  }
+  return bin;
+}
+
+// Quoting for cmd.exe /c, in the same way as the cross-spawn package. Shim arguments are escaped twice because the
+// shim hands them to a second cmd.exe level.
+const quoteArg = (arg: string): string => {
+  let a = arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/, "$1$1");
+  a = `"${a}"`.replace(META, "^$1");
+  return a.replace(META, "^$1");
+};
+const quoteCommand = (cmd: string): string => cmd.replace(META, "^$1");
+
+export type Invocation = { command: string; args: string[]; windowsVerbatimArguments?: boolean };
+
+export function invocation(
+  bin: string,
+  args: readonly string[],
+  platform: Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+  exists: Exists = existsSync,
+): Invocation {
+  const resolved = resolveBin(bin, platform, env, exists);
+  if (platform !== "win32" || !isShim(resolved)) return { command: resolved, args: [...args] };
+  // cmd.exe ends a command line at a line break, so such an argument would be silently cut short.
+  if (args.some((a) => /[\r\n]/.test(a))) throw new Error("an argument has a line break, which cmd.exe cannot pass to a .cmd shim");
+  const line = [quoteCommand(resolved), ...args.map(quoteArg)].join(" ");
+  return { command: env.ComSpec || "cmd.exe", args: ["/d", "/s", "/c", `"${line}"`], windowsVerbatimArguments: true };
+}
+
+export function spawnBin(bin: string, args: readonly string[], options: SpawnOptions): ChildProcess {
+  const inv = invocation(bin, args);
+  return spawn(inv.command, inv.args, { ...options, windowsHide: true, ...(inv.windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}) });
+}
+
+// The npm shim for an app is a few lines that run a script next to it, for example
+//   "%_prog%"  "%dp0%\node_modules\@anthropic-ai\claude-code\cli.js" %*
+// Returns that script (or .exe) so the Claude adapter, which cannot start a shim, can be pointed at the real file.
+export function shimTarget(shim: string, read: (p: string) => string = (p) => readFileSync(p, "utf8"), exists: Exists = existsSync): string | null {
+  try {
+    const m = /"%(?:~dp0|dp0)%?\\([^"\r\n]+\.(?:m?js|cjs|exe))"/i.exec(read(shim));
+    if (!m) return null;
+    const target = win32.join(win32.dirname(shim), m[1]!);
+    return exists(target) ? target : null;
+  } catch {
+    return null;
+  }
+}
+
+// What to hand the Claude adapter as CLAUDE_CODE_EXECUTABLE: the real app file, not a .cmd shim.
+export function claudeExecutable(bin: string, platform: Platform = process.platform, env: NodeJS.ProcessEnv = process.env, exists: Exists = existsSync): string {
+  const resolved = resolveBin(bin, platform, env, exists);
+  if (platform !== "win32" || !isShim(resolved)) return resolved;
+  return shimTarget(resolved, undefined, exists) ?? resolved;
+}
+
+// Ends the adapter and the app it started. POSIX: the adapter leads a process group, so one negative-pid kill ends
+// both. Windows has no groups, so `taskkill /T` walks the child tree; if that cannot run we kill the one process.
+type KillDeps = {
+  kill: (pid: number, signal: NodeJS.Signals) => void;
+  run: (cmd: string, args: string[], onFail: () => void) => void;
+};
+const realKillDeps: KillDeps = {
+  kill: (pid, signal) => process.kill(pid, signal),
+  run: (cmd, args, onFail) => {
+    const p = spawn(cmd, args, { stdio: "ignore", windowsHide: true });
+    p.on("error", onFail);
+    p.on("exit", (code) => {
+      if (code !== 0) onFail();
+    });
+  },
+};
+
+export function killTree(proc: Pick<ChildProcess, "pid" | "kill">, platform: Platform = process.platform, deps: KillDeps = realKillDeps): void {
+  const own = () => {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // Already gone.
+    }
+  };
+  try {
+    if (platform === "win32" && proc.pid) deps.run("taskkill", ["/pid", String(proc.pid), "/T", "/F"], own);
+    else if (platform !== "win32" && proc.pid) deps.kill(-proc.pid, "SIGKILL");
+    else own();
+  } catch {
+    own();
+  }
+}

package/src/store.ts

@@ -0,0 +1,30 @@
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// The only secret this program keeps is the device token the CrewCortex server gave it. It lives in a 0600 file.
+// On Windows the mode bits and chmod do nothing; the file is protected by the ACL of the user's own profile folder instead.
+// (An OS keychain is a later upgrade; the file is the supported path and the one tests use.)
+export type Stored = { appUrl: string; token: string };
+
+const dir = () => process.env.CREW_RUNNER_HOME || join(homedir(), ".crew-runner");
+const file = () => join(dir(), "device.json");
+
+export async function save(value: Stored): Promise<void> {
+  await mkdir(dir(), { recursive: true, mode: 0o700 });
+  await writeFile(file(), JSON.stringify(value), { mode: 0o600 });
+  await chmod(file(), 0o600);
+}
+
+export async function load(): Promise<Stored | null> {
+  try {
+    const parsed = JSON.parse(await readFile(file(), "utf8")) as Partial<Stored>;
+    return typeof parsed.appUrl === "string" && typeof parsed.token === "string" ? { appUrl: parsed.appUrl, token: parsed.token } : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function clear(): Promise<void> {
+  await rm(file(), { force: true });
+}