@clipboard-health/groundcrew 1.10.2 → 1.12.0

package/README.md

@@ -37,6 +37,16 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
    gh repo clone owner/repo ~/dev/groundcrew-workspaces/owner/repo
    ```
 
+   Or let `crew` clone every missing `owner/repo` entry for you using your `gh` login:
+
+   ```bash
+   crew setup repos              # clone all missing entries
+   crew setup repos --dry-run    # preview what would be cloned
+   crew setup repos owner/repo   # restrict to one entry
+   ```
+
+   `crew setup repos` is idempotent — already-cloned repos are reported `[exists]` and untouched. Bare-name entries (no `owner/`) are skipped with an instruction to clone manually, since groundcrew can't safely guess the org. The command fails fast with an install hint when `gh` is not on `PATH`.
+
    `crew` resolves the config path as: `GROUNDCREW_CONFIG` if set → `${XDG_CONFIG_HOME:-$HOME/.config}/groundcrew/config.ts` if it exists → a `config.ts` sitting next to `crew`'s own source files (only useful from a local checkout; see [Hacking on groundcrew](#hacking-on-groundcrew)). Set `GROUNDCREW_CONFIG` only when you want to override the XDG location.
 
 4. **Provide a Linear API key.** `crew` expects `LINEAR_API_KEY` in its environment. Any mechanism works — shell export, [direnv](https://direnv.net/), a `.env` file you `source`, or piping through `op run` if you store the credential in 1Password:
@@ -81,6 +91,7 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
      --claude \
      --codex \
      --copy-local-codex-auth \
+     --datadog \
      --github \
      --git-name "Your Name" \
      --git-email "you@users.noreply.github.com" \
@@ -89,7 +100,7 @@ This installs the `crew` binary. `@clipboard-health/clearance` is pulled in tran
      --checkpoint
    ```
 
-   Known MCP aliases are `linear`, `slack`, and `notion`. For another HTTP MCP server, pass `--mcp name=https://example.com/mcp`. The command creates the remote runner if needed, prepares `~/dev`, configures Git, runs selected auth flows, adds selected MCP servers to Claude Code, and then opens Claude so you can run `/mcp` and authenticate only those selected servers. With the Sprite provider, `--copy-local-codex-auth` copies `${CODEX_HOME:-$HOME/.codex}/auth.json` into `/home/sprite/.codex/auth.json` and then verifies `codex login status`; it never prints the file contents. Use `--skip-mcp-auth` when you only want to add MCP definitions, and run the `/mcp` step later.
+   Known MCP aliases are `linear`, `slack`, and `notion`. For another HTTP MCP server, pass `--mcp name=https://example.com/mcp`. The command creates the remote runner if needed, prepares `~/dev`, configures Git, runs selected auth flows, adds selected MCP servers to Claude Code, and then opens Claude so you can run `/mcp` and authenticate only those selected servers. With the Sprite provider, `--copy-local-codex-auth` copies `${CODEX_HOME:-$HOME/.codex}/auth.json` into `/home/sprite/.codex/auth.json` and then verifies `codex login status`; it never prints the file contents. `--datadog` installs a pinned `pup` release in the remote runner, verifies its checksum, installs the `dd-pup` guidance for Claude and Codex, verifies `pup auth status`, and when auth is missing temporarily runs `sprite proxy` for the OAuth callback while `pup auth login --read-only` runs in the remote runner. Open the Datadog URL printed by `pup` if your terminal does not open it automatically. Use `--skip-mcp-auth` when you only want to add MCP definitions, and run the `/mcp` step later.
 
    Repo setup is separate from runner setup and should run after the ticket branch exists, immediately before launching an agent. It clones/fetches the repo in the remote runner, checks out the requested branch (creating it from the base branch when it does not exist on origin), forwards only build-time secrets for the dependency install, removes the temporary secret file, clears those env vars, and then exits. It uses groundcrew's remote setup command.
 
@@ -180,13 +191,14 @@ Rules:
 ## Manual commands
 
 ```bash
-crew remote setup crew-claude-1 --claude --codex --copy-local-codex-auth --github --mcp linear --checkpoint
+crew remote setup crew-claude-1 --claude --codex --copy-local-codex-auth --datadog --github --mcp linear --checkpoint
 crew remote bootstrap crew-claude-1 core-utils --branch rocky-team-123
 crew remote sessions
 crew remote attach <session-id-or-command> --runner crew-claude-1
 crew remote ps crew-claude-1
 crew remote interrupt <process-group-id> --runner crew-claude-1
 crew run --ticket <TICKET>
+crew setup repos [--dry-run] [<repo>...]
 crew cleanup <TICKET>
 ```
 
@@ -211,6 +223,7 @@ crew cleanup <TICKET>
 - **Doctor checks every enabled model, including shipped defaults you didn't disable.** `models.definitions` includes both shipped defaults (`claude`, `codex`) by default via additive merge. If you only intend to label tickets `agent-claude` and don't have `codex` installed, set `models.definitions.codex: { disabled: true }` (see "Disabling a shipped default" under "Config reference"). Without that, doctor exits non-zero on a missing `codex` binary even though `crew run` would never route to it.
 - **Switch to tmux if cmux is misbehaving.** Set `workspaceKind: "tmux"` to force the tmux backend when cmux's CLI/socket bridge is flaky (symptoms: `cmux --json list-workspaces` returning `Failed to write to socket (Broken pipe)` or `Socket not found at ...cmux.sock` on every tick). tmux is more reliable — just a unix socket, no GUI app — at the cost of losing cmux's status pills, notifications, and vertical-tab sidebar.
 - **Agent CLI must accept a positional prompt.** The handoff is `<your cmd> "<prompt>"`. `claude`, `codex`, and `cursor-agent` all support this.
+- **`crew setup repos` only auto-clones `owner/repo` entries.** Bare-name entries in `workspace.knownRepositories` (e.g. `"api"` rather than `"clipboardhealth/api"`) are skipped with a hint to clone manually — the command refuses to guess the owner. After a partial setup, the exit code is non-zero so CI gates notice; rerun is idempotent once you clone the bare ones into `<projectDir>/<name>` yourself. Adding a new repo to `knownRepositories` later? Just rerun `crew setup repos`; already-present entries report `[exists]` and are untouched.
 
 ## Hacking on groundcrew
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAmHA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAsIA,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BvD"}

package/dist/cli.js

@@ -3,9 +3,21 @@ import { cleanupWorkspaceCli } from "./commands/cleanupWorkspace.js";
 import { doctor } from "./commands/doctor.js";
 import { orchestrate } from "./commands/orchestrator.js";
 import { remoteCli } from "./commands/remoteSetup.js";
+import { setupReposCli } from "./commands/setupRepos.js";
 import { setupWorkspaceCli } from "./commands/setupWorkspace.js";
 import { errorMessage, writeError, writeOutput } from "./lib/util.js";
 const requireFromCli = createRequire(import.meta.url);
+function setupUsage() {
+    return "Usage: crew setup repos [--dry-run] [<repo>...]";
+}
+async function setupCli(argv) {
+    const [verb, ...rest] = argv;
+    if (verb === "repos") {
+        await setupReposCli(rest);
+        return;
+    }
+    throw new Error(setupUsage());
+}
 async function runCli(argv) {
     let watch = false;
     let dryRun = false;
@@ -60,9 +72,14 @@ const SUBCOMMANDS = {
         usage: "[--force] <ticket>",
         invoke: cleanupWorkspaceCli,
     },
+    setup: {
+        summary: "Project-level setup commands (currently: repos)",
+        usage: "repos [--dry-run] [<repo>...]",
+        invoke: setupCli,
+    },
     remote: {
         summary: "Create, authenticate, bootstrap, and inspect a remote runner",
-        usage: "setup <runner-name> [--claude] [--github] [--mcp <alias|name=url>] [--checkpoint]\n" +
+        usage: "setup <runner-name> [--claude] [--codex] [--datadog] [--github] [--mcp <alias|name=url>] [--checkpoint]\n" +
             "           → crew remote bootstrap <runner-name> <repo> [--branch <branch>]\n" +
             "           → crew remote sessions [<runner-name>]\n" +
             "           → crew remote attach <session-id-or-command> [--runner <runner-name>]\n" +

package/dist/commands/remoteSetup.d.ts

@@ -8,6 +8,7 @@ export interface RemoteSetupOptions {
     shouldAuthenticateClaude: boolean;
     shouldAuthenticateCodex: boolean;
     shouldCopyLocalCodexAuth?: boolean;
+    shouldSetupDatadog?: boolean;
     shouldAuthenticateGithub: boolean;
     shouldAuthenticateMcp: boolean;
     shouldCheckpoint: boolean;

package/dist/commands/remoteSetup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remoteSetup.d.ts","sourceRoot":"","sources":["../../src/commands/remoteSetup.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,wBAAwB,EAAE,OAAO,CAAC;IAClC,uBAAuB,EAAE,OAAO,CAAC;IACjC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,wBAAwB,EAAE,OAAO,CAAC;IAClC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4BAA4B,EAAE,OAAO,CAAC;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA4rBD,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B9F;AAUD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrF;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF;AAED,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhG;AAYD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6BlF;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B7D"}
+{"version":3,"file":"remoteSetup.d.ts","sourceRoot":"","sources":["../../src/commands/remoteSetup.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,wBAAwB,EAAE,OAAO,CAAC;IAClC,uBAAuB,EAAE,OAAO,CAAC;IACjC,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wBAAwB,EAAE,OAAO,CAAC;IAClC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4BAA4B,EAAE,OAAO,CAAC;IACtC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAy0BD,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B9F;AAUD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrF;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAItF;AAED,wBAAsB,2BAA2B,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhG;AAYD,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgClF;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA2B7D"}

package/dist/commands/remoteSetup.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { BUILD_SECRET_NAMES, DEFAULT_REMOTE_SETUP_COMMAND, loadConfig, } from "../lib/config.js";
 import { shellSingleQuote } from "../lib/shell.js";
 import { getRemoteRunnerProvider, remoteConfigWithRunnerName, } from "../lib/spriteRemoteRunnerProvider.js";
@@ -14,6 +15,10 @@ const DEFAULT_CHECKPOINT_COMMENT = "groundcrew remote runner baseline: selected
 const CLAUDE_SUBSCRIPTION_LOGIN_FLAG = ["--claude", "ai"].join("");
 const DEFAULT_REPOSITORY_OWNER = "ClipboardHealth";
 const DEFAULT_BASE_BRANCH = "main";
+const DATADOG_PUP_VERSION = "0.63.0";
+const DATADOG_OAUTH_CALLBACK_PORT = 8000;
+const DATADOG_AUTH_STATUS_RETRY_ATTEMPTS = 5;
+const DATADOG_AUTH_STATUS_RETRY_DELAY_MS = 250;
 const REMOTE_SECRETS_FILE = "/tmp/groundcrew-build-secrets.env";
 const REMOTE_CODEX_AUTH_UPLOAD_FILE = "/tmp/groundcrew-codex-auth.json";
 const REMOTE_CODEX_AUTH_FILE = "/home/sprite/.codex/auth.json";
@@ -31,6 +36,7 @@ function usage() {
         "  --claude                    Authenticate Claude Code with a Claude subscription",
         "  --codex                     Authenticate Codex CLI",
         "  --copy-local-codex-auth     With --codex, copy local CODEX_HOME auth.json into the remote runner",
+        "  --datadog                   Install pup, add dd-pup skills, and authenticate Datadog",
         "  --github                    Authenticate gh for GitHub PRs",
         "  --mcp <alias|name=url>      Add/authenticate one MCP server; repeat for multiple",
         "                              Known aliases: linear, slack, notion",
@@ -134,6 +140,7 @@ function parseArguments(argv) {
     let shouldAuthenticateClaude = false;
     let shouldAuthenticateCodex = false;
     let shouldCopyLocalCodexAuth = false;
+    let shouldSetupDatadog = false;
     let shouldAuthenticateGithub = false;
     let shouldAuthenticateMcp = true;
     let shouldCheckpoint = false;
@@ -156,6 +163,10 @@ function parseArguments(argv) {
             shouldCopyLocalCodexAuth = true;
             continue;
         }
+        if (argument === "--datadog") {
+            shouldSetupDatadog = true;
+            continue;
+        }
         if (argument === "--github") {
             shouldAuthenticateGithub = true;
             continue;
@@ -202,6 +213,7 @@ function parseArguments(argv) {
         shouldAuthenticateClaude,
         shouldAuthenticateCodex,
         shouldCopyLocalCodexAuth,
+        shouldSetupDatadog,
         shouldAuthenticateGithub,
         shouldAuthenticateMcp,
         shouldCheckpoint,
@@ -457,6 +469,105 @@ async function authenticateCodex(arguments_) {
     }
     throw new Error("Codex login finished, but `codex login status` still reports not logged in inside the remote runner. Try `crew remote setup <runner-name> --codex --copy-local-codex-auth`.");
 }
+function datadogPupInstallCommand() {
+    const shellVariable = "$";
+    return [
+        "set -euo pipefail",
+        `version=${shellSingleQuote(DATADOG_PUP_VERSION)}`,
+        'case "$(uname -m)" in',
+        "  x86_64|amd64) arch=x86_64 ;;",
+        "  aarch64|arm64) arch=arm64 ;;",
+        '  *) echo "Unsupported Linux architecture: $(uname -m)" >&2; exit 1 ;;',
+        "esac",
+        `asset="pup_${shellVariable}{version}_Linux_${shellVariable}{arch}.tar.gz"`,
+        `base_url="https://github.com/DataDog/pup/releases/download/v${shellVariable}{version}"`,
+        'binary="$HOME/.local/bin/pup"',
+        'mkdir -p "$HOME/.local/bin"',
+        `if [ -x "$binary" ] && "$binary" version | grep -q "Pup ${shellVariable}{version} "; then "$binary" version; exit 0; fi`,
+        'install_dir="$(mktemp -d)"',
+        "trap 'rm -rf \"$install_dir\"' EXIT",
+        `archive="${shellVariable}{install_dir}/${shellVariable}{asset}"`,
+        `checksums="${shellVariable}{install_dir}/pup_${shellVariable}{version}_checksums.txt"`,
+        'curl -fsSL -o "$archive" "$base_url/$asset"',
+        `curl -fsSL -o "$checksums" "$base_url/pup_${shellVariable}{version}_checksums.txt"`,
+        `(cd "$install_dir" && grep " ${shellVariable}{asset}$" "$checksums" | sha256sum -c -)`,
+        'tar -xzf "$archive" -C "$HOME/.local/bin" pup',
+        'chmod 755 "$binary"',
+        '"$binary" version',
+    ].join("\n");
+}
+async function installDatadogPup(provider, config) {
+    log(`Installing Datadog pup ${DATADOG_PUP_VERSION} inside the remote runner`);
+    await provider.runCommand({
+        config,
+        remoteArguments: ["bash", "-lc", datadogPupInstallCommand()],
+    });
+}
+async function installDatadogPupSkills(provider, config) {
+    for (const platform of ["claude-code", "codex"]) {
+        // oxlint-disable-next-line no-await-in-loop -- installs are quick and ordered so logs stay readable.
+        await provider.runCommand({
+            config,
+            remoteArguments: ["pup", "skills", "install", platform, "--name", "dd-pup", "--yes"],
+        });
+    }
+}
+async function validateDatadogLogin(provider, config) {
+    return await commandSucceeds({
+        provider,
+        config,
+        remoteArguments: ["pup", "auth", "status"],
+    });
+}
+async function waitForDatadogLogin(provider, config) {
+    for (let attempt = 1; attempt <= DATADOG_AUTH_STATUS_RETRY_ATTEMPTS; attempt += 1) {
+        // oxlint-disable-next-line no-await-in-loop -- bounded polling smooths over Datadog OAuth propagation delay.
+        if (await validateDatadogLogin(provider, config)) {
+            return true;
+        }
+        if (attempt < DATADOG_AUTH_STATUS_RETRY_ATTEMPTS) {
+            // oxlint-disable-next-line no-await-in-loop -- retries are intentionally spaced.
+            await sleep(DATADOG_AUTH_STATUS_RETRY_DELAY_MS);
+        }
+    }
+    return false;
+}
+async function authenticateDatadog(provider, config) {
+    if (await validateDatadogLogin(provider, config)) {
+        return;
+    }
+    writeOutput();
+    writeOutput("Datadog OAuth will run inside the remote runner.");
+    writeOutput(`Groundcrew is forwarding local port ${DATADOG_OAUTH_CALLBACK_PORT} to the remote callback server while login runs.`);
+    writeOutput("Open the Datadog URL printed by pup if your terminal does not open it for you.");
+    writeOutput();
+    const proxy = await provider.startPortProxy(config, DATADOG_OAUTH_CALLBACK_PORT);
+    try {
+        await provider.runTtyCommand({
+            config,
+            remoteArguments: [
+                "pup",
+                "auth",
+                "login",
+                "--read-only",
+                "--callback-port",
+                String(DATADOG_OAUTH_CALLBACK_PORT),
+            ],
+        });
+    }
+    finally {
+        await proxy.close();
+    }
+    if (await waitForDatadogLogin(provider, config)) {
+        return;
+    }
+    throw new Error("Datadog auth finished, but `pup auth status` still reports not logged in inside the remote runner.");
+}
+async function setupDatadog(provider, config) {
+    await installDatadogPup(provider, config);
+    await installDatadogPupSkills(provider, config);
+    await authenticateDatadog(provider, config);
+}
 async function addMcpServer(arguments_) {
     const { provider, config, server } = arguments_;
     const exists = await commandSucceeds({
@@ -661,6 +772,9 @@ export async function setupRemoteRunner(options) {
             shouldCopyLocalAuth: options.shouldCopyLocalCodexAuth === true,
         });
     }
+    if (options.shouldSetupDatadog === true) {
+        await setupDatadog(provider, config);
+    }
     for (const server of options.mcpServers) {
         // oxlint-disable-next-line no-await-in-loop -- MCP additions are sequential so auth instructions stay ordered.
         await addMcpServer({ provider, config, server });

package/dist/commands/setupRepos.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `crew setup repos` — clone every entry of `workspace.knownRepositories`
+ * that does not already exist under `workspace.projectDir`. Entries
+ * shaped `<owner>/<repo>` are cloned via `gh repo clone`; bare-name
+ * entries are skipped with a hint, because they have no canonical URL
+ * we can guess at without involving the user's gh login. Idempotent.
+ */
+import { type ResolvedConfig } from "../lib/config.ts";
+export interface SetupReposOptions {
+    /** Print the plan without running any clone. */
+    dryRun?: boolean;
+    /**
+     * Restrict the action to this subset of `knownRepositories`. Each entry
+     * must match an entry in the config or the call rejects before any side
+     * effect.
+     */
+    only?: readonly string[];
+}
+export type SetupReposSkipKind = "bare-name" | "invalid-repository" | "invalid-target";
+export interface SetupReposSkip {
+    repo: string;
+    kind: SetupReposSkipKind;
+    reason: string;
+}
+export interface SetupReposResult {
+    /** Entries already present under `projectDir`. */
+    existing: string[];
+    /** Entries that would be cloned in dry-run mode. */
+    planned: string[];
+    /** Entries successfully cloned this run. */
+    cloned: string[];
+    /** Entries skipped with a reason (e.g. bare names, invalid targets). */
+    skipped: SetupReposSkip[];
+    /** Entries that failed during clone. */
+    failed: {
+        repo: string;
+        error: Error;
+    }[];
+    /** True when `gh` is missing and at least one clone was needed. */
+    ghMissing: boolean;
+}
+export declare function setupRepos(config: ResolvedConfig, options: SetupReposOptions): Promise<SetupReposResult>;
+export declare function setupReposCli(argv: string[]): Promise<void>;
+//# sourceMappingURL=setupRepos.d.ts.map

package/dist/commands/setupRepos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupRepos.d.ts","sourceRoot":"","sources":["../../src/commands/setupRepos.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAInE,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,oBAAoB,GAAG,gBAAgB,CAAC;AAEvF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,kBAAkB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wCAAwC;IACxC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,EAAE,CAAC;IACzC,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AA6JD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAyD3B;AAwBD,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAajE"}

package/dist/commands/setupRepos.js

@@ -0,0 +1,222 @@
+/**
+ * `crew setup repos` — clone every entry of `workspace.knownRepositories`
+ * that does not already exist under `workspace.projectDir`. Entries
+ * shaped `<owner>/<repo>` are cloned via `gh repo clone`; bare-name
+ * entries are skipped with a hint, because they have no canonical URL
+ * we can guess at without involving the user's gh login. Idempotent.
+ */
+import { opendirSync, statSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { runCommandAsync } from "../lib/commandRunner.js";
+import { loadConfig } from "../lib/config.js";
+import { which } from "../lib/host.js";
+import { errorMessage, log, writeOutput } from "../lib/util.js";
+function emptyResult() {
+    return {
+        existing: [],
+        planned: [],
+        cloned: [],
+        skipped: [],
+        failed: [],
+        ghMissing: false,
+    };
+}
+function selectRepositories(config, only) {
+    if (only === undefined) {
+        return config.workspace.knownRepositories;
+    }
+    const known = new Set(config.workspace.knownRepositories);
+    const unknown = only.filter((entry) => !known.has(entry));
+    if (unknown.length > 0) {
+        throw new Error(`Repositories not in workspace.knownRepositories: ${unknown.join(", ")}. Known: ${config.workspace.knownRepositories.join(", ")}`);
+    }
+    return only;
+}
+function pathExists(path) {
+    return statSync(path, { throwIfNoEntry: false }) !== undefined;
+}
+function isDirectoryEmpty(path) {
+    const directory = opendirSync(path);
+    try {
+        return directory.readSync() === null;
+    }
+    finally {
+        directory.closeSync();
+    }
+}
+function existingTargetPlan(target) {
+    const stats = statSync(target, { throwIfNoEntry: false });
+    if (stats === undefined) {
+        return "clone";
+    }
+    if (!stats.isDirectory()) {
+        return "skip-invalid";
+    }
+    if (pathExists(resolve(target, ".git"))) {
+        return "existing";
+    }
+    return isDirectoryEmpty(target) ? "clone" : "skip-invalid";
+}
+function isInsideProjectDir(projectDir, target) {
+    const relativeTarget = relative(projectDir, target);
+    return (relativeTarget.length > 0 && !relativeTarget.startsWith("..") && !isAbsolute(relativeTarget));
+}
+function repositoryEntryPlan(repo) {
+    const parts = repo.split("/");
+    if (parts.length === 1) {
+        return "bare-name";
+    }
+    if (parts.length === 2 && parts.every((part) => part.length > 0)) {
+        return "clone";
+    }
+    return "invalid-repository";
+}
+function bareNameSkip(repo, target) {
+    return {
+        repo,
+        kind: "bare-name",
+        reason: `bare name needs owner/ prefix to auto-clone; clone manually into ${target}`,
+    };
+}
+function invalidTargetSkip(repo, target) {
+    return {
+        repo,
+        kind: "invalid-target",
+        reason: `target exists but is not a git repository or empty directory: ${target}`,
+    };
+}
+function invalidRepositorySkip(repo, target) {
+    return {
+        repo,
+        kind: "invalid-repository",
+        reason: `repository must be owner/repo to auto-clone; clone manually into ${target}`,
+    };
+}
+function escapingTargetSkip(repo, projectDir, target) {
+    return {
+        repo,
+        kind: "invalid-repository",
+        reason: `repository resolves outside workspace.projectDir (${projectDir}): ${target}`,
+    };
+}
+function planClones(config, repositories) {
+    const projectDir = resolve(config.workspace.projectDir);
+    const toClone = [];
+    const existing = [];
+    const skipped = [];
+    const seen = new Set();
+    for (const entry of repositories) {
+        if (seen.has(entry)) {
+            continue;
+        }
+        seen.add(entry);
+        const target = resolve(projectDir, entry);
+        if (!isInsideProjectDir(projectDir, target)) {
+            skipped.push(escapingTargetSkip(entry, projectDir, target));
+            continue;
+        }
+        const targetPlan = existingTargetPlan(target);
+        if (targetPlan === "existing") {
+            existing.push(entry);
+            continue;
+        }
+        if (targetPlan === "skip-invalid") {
+            skipped.push(invalidTargetSkip(entry, target));
+            continue;
+        }
+        const repositoryPlan = repositoryEntryPlan(entry);
+        if (repositoryPlan === "bare-name") {
+            skipped.push(bareNameSkip(entry, target));
+            continue;
+        }
+        if (repositoryPlan === "invalid-repository") {
+            skipped.push(invalidRepositorySkip(entry, target));
+            continue;
+        }
+        toClone.push(entry);
+    }
+    return { toClone, existing, skipped };
+}
+export async function setupRepos(config, options) {
+    const repositories = selectRepositories(config, options.only);
+    const plan = planClones(config, repositories);
+    const result = emptyResult();
+    result.existing = plan.existing;
+    result.skipped = plan.skipped;
+    for (const entry of plan.existing) {
+        log(`[exists] ${entry}`);
+    }
+    for (const { repo, reason } of plan.skipped) {
+        log(`[skip] ${repo} — ${reason}`);
+    }
+    if (options.dryRun === true) {
+        result.planned = plan.toClone;
+        for (const entry of plan.toClone) {
+            log(`[dry-run] would clone ${entry}`);
+        }
+        return result;
+    }
+    if (plan.toClone.length === 0) {
+        return result;
+    }
+    const ghPath = await which("gh");
+    if (ghPath === undefined) {
+        result.ghMissing = true;
+        writeOutput("gh CLI not found - install GitHub CLI from https://cli.github.com/ (or clone the missing repos manually).");
+        return result;
+    }
+    const projectDir = resolve(config.workspace.projectDir);
+    // Sequential on purpose: each `gh repo clone` inherits stdio for progress
+    // bars and auth prompts. Parallel clones would interleave output and make
+    // any interactive 2FA prompt unanswerable.
+    for (const entry of plan.toClone) {
+        const target = resolve(projectDir, entry);
+        log(`[clone] ${entry} → ${target}`);
+        try {
+            // oxlint-disable-next-line no-await-in-loop -- see comment above
+            await runCommandAsync("gh", ["repo", "clone", entry, target], {
+                stdio: "inherit",
+                timeoutMs: 0,
+            });
+            result.cloned.push(entry);
+        }
+        catch (error) {
+            const wrapped = error instanceof Error ? error : new Error(errorMessage(error));
+            log(`[fail]  ${entry}: ${wrapped.message}`);
+            result.failed.push({ repo: entry, error: wrapped });
+        }
+    }
+    return result;
+}
+function parseArguments(argv) {
+    let dryRun = false;
+    const positionals = [];
+    for (const argument of argv) {
+        if (argument === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (argument.startsWith("-")) {
+            throw new Error(`Unknown option: ${argument}\nUsage: crew setup repos [--dry-run] [<repo>...]`);
+        }
+        positionals.push(argument);
+    }
+    const options = { dryRun };
+    if (positionals.length > 0) {
+        options.only = positionals;
+    }
+    return options;
+}
+export async function setupReposCli(argv) {
+    const options = parseArguments(argv);
+    const config = await loadConfig();
+    const result = await setupRepos(config, options);
+    if (result.ghMissing || result.failed.length > 0) {
+        process.exitCode = 1;
+        return;
+    }
+    // Remaining skips mean setup is incomplete — signal that to CI gates.
+    if (result.skipped.length > 0) {
+        process.exitCode = 1;
+    }
+}

package/dist/lib/spriteRemoteRunnerProvider.d.ts

@@ -54,6 +54,9 @@ export interface RemoteRunnerProvider {
     runCommand(arguments_: RemoteRunArguments): Promise<string | undefined>;
     runTtyCommand(arguments_: RemoteRunArguments): Promise<void>;
     buildTtyCommand(arguments_: RemoteTtyCommandArguments): string;
+    startPortProxy(config: RemoteRunnerConfig, port: number): Promise<{
+        close(): Promise<void>;
+    }>;
     listSessions(config: RemoteRunnerConfig): Promise<string>;
     attachSession(config: RemoteRunnerConfig, target: string): Promise<void>;
     listProcesses(config: RemoteRunnerConfig): Promise<string>;

package/dist/lib/spriteRemoteRunnerProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spriteRemoteRunnerProvider.d.ts","sourceRoot":"","sources":["../../src/lib/spriteRemoteRunnerProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"spriteRemoteRunnerProvider.d.ts","sourceRoot":"","sources":["../../src/lib/spriteRemoteRunnerProvider.ts"],"names":[],"mappings":"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"}

package/dist/lib/spriteRemoteRunnerProvider.js

@@ -1,6 +1,12 @@
+import { connect } from "node:net";
+import { setTimeout as sleep } from "node:timers/promises";
 import { runCommandAsync } from "./commandRunner.js";
 import { shellSingleQuote } from "./shell.js";
 const LONG_RUNNING_COMMAND_OPTIONS = { stdio: "inherit", timeoutMs: 0 };
+const PROXY_CLOSE_SIGNAL = "SIGINT";
+const PROXY_READY_HOST = "127.0.0.1";
+const PROXY_READY_TIMEOUT_MS = 5000;
+const PROXY_READY_RETRY_DELAY_MS = 25;
 export const SPRITE_REMOTE_PROVIDER_DEFAULTS = {
     provider: "sprite",
     runnerName: "crew-claude-1",
@@ -155,6 +161,96 @@ async function createSpriteRunner(config) {
         timeoutMs: 0,
     });
 }
+async function startSpritePortProxy(config, port) {
+    const controller = new AbortController();
+    let closeWasRequested = false;
+    let proxyError;
+    const proxy = (async () => {
+        try {
+            await runCommandAsync("sprite", ["proxy", "-s", config.runnerName, String(port)], {
+                signal: controller.signal,
+                stdio: "inherit",
+                timeoutMs: 0,
+            });
+            if (!closeWasRequested) {
+                proxyError = new Error("Sprite proxy exited before it was closed.");
+            }
+        }
+        catch (error) {
+            if (closeWasRequested && errorHasSignal(error, PROXY_CLOSE_SIGNAL)) {
+                return;
+            }
+            proxyError = new Error(`Sprite proxy exited before it was closed: ${String(error)}`, {
+                cause: error,
+            });
+        }
+    })();
+    try {
+        await waitForSpritePortProxy({ port, proxy, proxyError: () => proxyError });
+    }
+    catch (error) {
+        closeWasRequested = true;
+        controller.abort();
+        await proxy;
+        throw error;
+    }
+    return {
+        async close() {
+            closeWasRequested = true;
+            controller.abort();
+            await proxy;
+            if (proxyError !== undefined) {
+                throw new Error(proxyError.message, { cause: proxyError });
+            }
+        },
+    };
+}
+async function waitForSpritePortProxy(arguments_) {
+    const deadline = Date.now() + PROXY_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        throwIfProxyExited(arguments_.proxyError());
+        // eslint-disable-next-line no-await-in-loop -- readiness polling must observe attempts sequentially.
+        if (await canConnectToLocalPort(arguments_.port)) {
+            throwIfProxyExited(arguments_.proxyError());
+            return;
+        }
+        throwIfProxyExited(arguments_.proxyError());
+        // eslint-disable-next-line no-await-in-loop -- retry delay is bounded and stops early if the proxy exits.
+        await Promise.race([sleep(PROXY_READY_RETRY_DELAY_MS), arguments_.proxy]);
+    }
+    throwIfProxyExited(arguments_.proxyError());
+    throw new Error(`Timed out waiting for Sprite proxy on ${PROXY_READY_HOST}:${arguments_.port} to accept connections.`);
+}
+function throwIfProxyExited(error) {
+    if (error !== undefined) {
+        throw new Error(error.message, { cause: error });
+    }
+}
+async function canConnectToLocalPort(port) {
+    return await new Promise((resolve) => {
+        const socket = connect({ host: PROXY_READY_HOST, port });
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
+function errorHasSignal(error, signal) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    if ("signal" in error && error.signal === signal) {
+        return true;
+    }
+    if (error instanceof Error && error.cause !== undefined) {
+        return errorHasSignal(error.cause, signal);
+    }
+    return false;
+}
 export const spriteRemoteRunnerProvider = {
     name: "sprite",
     async runnerExists(config) {
@@ -174,6 +270,9 @@ export const spriteRemoteRunnerProvider = {
         });
     },
     buildTtyCommand: buildSpriteTtyCommand,
+    async startPortProxy(config, port) {
+        return await startSpritePortProxy(config, port);
+    },
     async listSessions(config) {
         const output = await runCommandAsync("sprite", ["sessions", "list", "-s", config.runnerName], {
             trim: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "1.10.2",
+  "version": "1.12.0",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle, remote runners, and usage tracking.",
   "keywords": [
     "agent",