@clipboard-health/groundcrew 4.9.0 → 4.10.1

package/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  Dispatch your ticket backlog to AI coding agents. One git worktree per ticket, sandboxed by default.
+  Dispatch your ticket backlog to local, interactive AI coding agents. One git worktree per ticket, sandboxed by default.
 </p>
 
 <p align="center">
@@ -17,16 +17,22 @@
 </p>
 
 <p align="center">
-  <img alt="Groundcrew picking up tickets and running coding agents in parallel" src="./static/demo.gif" width="800">
+  <a href="./static/demo.tape"><img alt="Groundcrew dispatching tickets into tmux panes with coding agents running in parallel" src="./static/demo.gif" width="800"></a>
+</p>
+
+<p align="center">
+  VHS source: <a href="./static/demo.tape">static/demo.tape</a>.
 </p>
 
 Groundcrew watches assigned tickets, creates isolated worktrees, launches agent CLIs in dedicated terminals, and leaves each ticket's work on its own PR-ready branch. For the backstory, read _[Tickets to pull requests while you sleep](https://www.clipboardworks.com/resources/blog/tickets-to-pull-requests-while-you-sleep)_.
 
 ## Why
 
+- **Local.** Agents run on your machine with your tools, shell, and credentials. That makes them more steerable than remote agents, and easy to nudge when they drift.
+- **Interactive.** Each ticket launches the real `claude` or `codex` CLI in its own terminal pane, not a wrapper that approximates it. Watch any session live and take over when you need to.
 - **One worktree per ticket.** Agents work in parallel without stepping on each other.
+- **Sandboxed by default.** Safehouse or Docker Sandboxes isolate each agent on the host; `none` is an explicit escape hatch.
 - **Pluggable ticket sources.** Linear by default; Jira and local files via [ticket sources](./docs/ticket-sources.md).
-- **Local-first isolation.** Safehouse, Docker Sandboxes, or an explicit `none` escape hatch.
 - **Multi-agent routing.** Ships `claude` and `codex` presets; bring your own CLI in config.
 
 ## Prerequisites
@@ -83,8 +89,7 @@ crew init [--global | --local] [--force] [--dry-run]     # create a crew.config.
           [--runner <auto|safehouse|sdx|none>] [--model <claude|codex>]
 crew doctor                                              # check setup
 crew status [<TICKET>]                                   # inspect current state or one ticket
-crew run                                                 # one-shot orchestration
-crew run --watch                                         # poll forever
+crew run [--watch]                                       # one-shot or --watch forever
 crew start <TICKET>                                      # provision + launch one ticket now
 crew stop <TICKET> [--reason <text>]                     # stop workspace, keep worktree
 crew resume <TICKET>                                     # reopen a paused ticket
@@ -106,15 +111,18 @@ export default {
     projectDir: "~/dev",
     knownRepositories: ["OWNER/REPO"],
   },
-  local: {
-    runner: "auto",
-  },
   models: {
     default: "claude",
     definitions: {
       claude: {},
     },
   },
+  defaults: {
+    hooks: {
+      // No-op placeholder; replace with your repo's setup, e.g. "npm ci".
+      prepareWorktree: "true",
+    },
+  },
 } satisfies Config;
 ```
 
@@ -143,6 +151,12 @@ node --run crew:op -- run --watch
 
 Both forms discover config through cosmiconfig. Source edits in `src/**` are picked up on the next invocation. Requires Node >= 24.
 
+Regenerate the README demo with VHS:
+
+```bash
+./static/render-demo.sh
+```
+
 ## License
 
 [MIT](./LICENSE)

package/clearance-allow-hosts

@@ -64,8 +64,9 @@ raw.githubusercontent.com
 release-assets.githubusercontent.com
 results-receiver.actions.githubusercontent.com
 
-# npm registry + package website
+# npm/Conda registries + package websites
 api.npmjs.org
+conda.anaconda.org
 registry.npmjs.org
 www.npmjs.com
 
@@ -83,6 +84,9 @@ formulae.brew.sh
 hub.docker.com
 index.docker.io
 json.schemastore.org
+mise-versions.jdx.dev
 nx.dev
+playwright.azureedge.net
+registry.terraform.io
 sourcegraph.com
 vitest.dev

package/crew.config.example.ts

@@ -35,6 +35,15 @@ export default {
       // },
     },
   },
+  // Repo-preparation hook: runs after each worktree is created and before the
+  // agent launches. The default below is a no-op placeholder. Replace it with
+  // your repo's setup, e.g. "npm ci" or "uv sync --dev --frozen". A repo-local
+  // `.groundcrew/config.json` hooks.prepareWorktree overrides this per repo.
+  defaults: {
+    hooks: {
+      prepareWorktree: "true",
+    },
+  },
   // Everything below is optional — defaults shown for reference. Uncomment
   // and edit to override.
   //
@@ -59,14 +68,6 @@ export default {
   //
   // git: { remote: "origin", defaultBranch: "main" },
   //
-  // // Fallback repo-preparation hook for repos that do not define
-  // // `.groundcrew/config.json` hooks.prepareWorktree. Repo-local config wins.
-  // defaults: {
-  //   hooks: {
-  //     prepareWorktree: "test ! -f package-lock.json || npm ci",
-  //   },
-  // },
-  //
   // orchestrator: {
   //   maximumInProgress: 4,
   //   pollIntervalMilliseconds: 120_000,

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

@@ -1 +1 @@
-{"version":3,"file":"cleanupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/cleanupWorkspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAMnE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAwBD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAef;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE"}
+{"version":3,"file":"cleanupWorkspace.d.ts","sourceRoot":"","sources":["../../src/commands/cleanupWorkspace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAQnE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAwBD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAIvE"}

package/dist/commands/cleanupWorkspace.js

@@ -1,6 +1,8 @@
 import { loadConfig } from "../lib/config.js";
+import { readRunState, removeRunState } from "../lib/runState.js";
 import { recordCleanedUpRuns } from "../lib/runStateCleanup.js";
 import { log } from "../lib/util.js";
+import { workspaces } from "../lib/workspaces.js";
 import { worktrees } from "../lib/worktrees.js";
 import { logTeardown } from "./teardownReporter.js";
 function parseArguments(argv) {
@@ -26,7 +28,21 @@ export async function cleanupWorkspace(config, options) {
     const { ticket, force = false } = options;
     const entries = worktrees.findByTicket(config, ticket);
     if (entries.length === 0) {
-        log(`No worktree found for ${ticket}; nothing to clean up.`);
+        if (readRunState(config, ticket) === undefined) {
+            log(`No worktree found for ${ticket}; nothing to clean up.`);
+            return;
+        }
+        const workspaceProbe = await workspaces.probe(config);
+        if (workspaceProbe.kind === "unavailable") {
+            log(`No worktree found for ${ticket}; workspace probe unavailable, leaving run-state intact.`);
+            return;
+        }
+        if (workspaceProbe.names.has(ticket)) {
+            log(`No worktree found for ${ticket}; workspace still present; leaving run-state intact.`);
+            return;
+        }
+        removeRunState(config, ticket);
+        log(`No worktree found for ${ticket}; cleared stale run-state.`);
         return;
     }
     const result = await worktrees.teardown(config, entries, { force });

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuKH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CA8E/C"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA8KH,wBAAsB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,CAgF/C"}

package/dist/commands/doctor.js

@@ -5,7 +5,7 @@
 import { existsSync, statSync } from "node:fs";
 import { createBoard } from "../lib/board.js";
 import { buildSources, sourcesFromConfig } from "../lib/buildSources.js";
-import { loadConfig, } from "../lib/config.js";
+import { loadConfigWithSource, } from "../lib/config.js";
 import { detectHostCapabilities, which } from "../lib/host.js";
 import { resolveLocalRunner } from "../lib/localRunner.js";
 import { gatedModels } from "../lib/usage.js";
@@ -15,6 +15,11 @@ import { resolveWorkspaceKind } from "../lib/workspaces.js";
 // catch wrapper + wrapped CLI commands like `safehouse claude --foo`.
 const MAX_TOKENS_PER_CMD = 2;
 const BUILT_IN_MODEL_NAMES = ["claude", "codex"];
+const CONFIG_SOURCE_LABELS = {
+    env: "GROUNDCREW_CONFIG",
+    project: "project",
+    xdg: "global XDG",
+};
 async function checkCmd(cmd, required, hint) {
     const path = await which(cmd);
     const resolvedHint = path ?? hint;
@@ -148,8 +153,10 @@ export async function doctor() {
     writeOutput("=================");
     let config;
     try {
-        config = await loadConfig();
-        writeOutput("[ok] config loaded");
+        const { config: loadedConfig, source } = await loadConfigWithSource();
+        config = loadedConfig;
+        const sourceLabel = CONFIG_SOURCE_LABELS[source.kind];
+        writeOutput(`[ok] config loaded — ${source.filepath} (${sourceLabel})`);
     }
     catch (error) {
         writeOutput(`[--] config: ${errorMessage(error)}`);

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

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAanE,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAkjBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"AAIA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAanE,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAonBD,wBAAsB,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/F;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAI7D"}

package/dist/commands/status.js

@@ -76,11 +76,14 @@ function ticketWorkspaceText(probe, ticket) {
 function isWorkspaceExited(probe, ticket) {
     return probe.kind === "ok" && probe.exitedNames?.has(ticket) === true;
 }
-function formatRunState(state) {
+function formatRunState(state, flags = []) {
     if (state === undefined) {
         return "(none)";
     }
-    const summary = `${state.state}; model=${state.model}; updated=${state.updatedAt}; resumes=${state.resumeCount}`;
+    // Only the leading lifecycle token gains the reconciliation flags; the
+    // `;`-separated detail (model/updated/resumes/reason) is preserved verbatim.
+    const lifecycle = flags.length === 0 ? state.state : `${state.state} (${flags.join(", ")})`;
+    const summary = `${lifecycle}; model=${state.model}; updated=${state.updatedAt}; resumes=${state.resumeCount}`;
     const detail = state.reason ?? state.detail;
     return detail === undefined ? summary : `${summary}; ${detail}`;
 }
@@ -174,7 +177,7 @@ async function writeTicketStatus(config, rawTicket) {
     const accessHint = await exitedWorkspaceAccessHint(config, workspaceProbe, ticket);
     writeOutput(formatTicketLine(ticket, runState, sourceStatus));
     writeTicketTitle(runState, sourceStatus);
-    writeOutput(`run: ${formatRunState(runState)}`);
+    writeOutput(`run: ${formatRunState(runState, runProbeFlags(runState, workspaceProbe, ticket))}`);
     writeOutput(`workspace: ${ticketWorkspaceText(workspaceProbe, ticket)}`);
     if (accessHint !== undefined) {
         writeOutput(`attach: ${accessHint.command}`);
@@ -220,32 +223,43 @@ function formatDuration(ms) {
     const hours = Math.floor((ms - days * MS_PER_DAY) / MS_PER_HOUR);
     return hours === 0 ? `${days}d` : `${days}d ${hours}h`;
 }
+/**
+ * Probe-reconciliation flags shared by the inventory row and the per-ticket
+ * `run:` line. Flags the two interesting disagreements between the recorded
+ * RunState lifecycle and the live workspace probe: a running/resumed dispatch
+ * with a missing or exited session, and an idle row with a stray live or
+ * exited session. `probe.kind === "unavailable"` is "we don't know" and yields
+ * no flags. Excludes the duration token, which only the inventory row appends.
+ */
+function runProbeFlags(runState, probe, ticket) {
+    if (probe.kind !== "ok") {
+        return [];
+    }
+    const lifecycle = runState?.state ?? "idle";
+    const sessionPresent = probe.names.has(ticket);
+    const sessionExited = isWorkspaceExited(probe, ticket);
+    const flags = [];
+    if (lifecycle === "idle" && sessionPresent) {
+        flags.push(sessionExited ? "stray exited session" : "stray session");
+    }
+    if ((lifecycle === "running" || lifecycle === "resumed") && sessionExited) {
+        flags.push("session exited");
+    }
+    else if ((lifecycle === "running" || lifecycle === "resumed") && !sessionPresent) {
+        flags.push("session dead");
+    }
+    return flags;
+}
 /**
  * Combined human-readable state for the inventory row. Surfaces RunState
  * lifecycle and flags the two interesting disagreements with the workspace
- * probe. A recorded running dispatch can have a missing or exited session;
- * an idle row can have a stray live or exited session. `probe.kind ===
- * "unavailable"` is treated as "we don't know" and never produces a suffix.
- * When the row is actively running, appends the elapsed wall-clock time since
- * dispatch.
+ * probe via `runProbeFlags`. When the row is actively running, appends the
+ * elapsed wall-clock time since dispatch.
  */
 function inventoryStateText(runState, probe, ticket, now) {
     const lifecycle = runState?.state ?? "idle";
+    const flags = runProbeFlags(runState, probe, ticket);
     const duration = runStateDurationMs(runState, now);
-    const flags = [];
-    if (probe.kind === "ok") {
-        const sessionPresent = probe.names.has(ticket);
-        const sessionExited = isWorkspaceExited(probe, ticket);
-        if (lifecycle === "idle" && sessionPresent) {
-            flags.push(sessionExited ? "stray exited session" : "stray session");
-        }
-        if ((lifecycle === "running" || lifecycle === "resumed") && sessionExited) {
-            flags.push("session exited");
-        }
-        else if ((lifecycle === "running" || lifecycle === "resumed") && !sessionPresent) {
-            flags.push("session dead");
-        }
-    }
     if (duration !== undefined) {
         flags.push(formatDuration(duration));
     }
@@ -459,6 +473,43 @@ function writeQueueSections(boardResult) {
 function inProgressCount(issues) {
     return issues.filter((issue) => issue.status === "in-progress").length;
 }
+/**
+ * In-progress board issues that have no local worktree. These count toward the
+ * `slots: N/M used` total but are absent from the Worktrees section (their
+ * worktree was removed, or lives outside this config's projectDir /
+ * knownRepositories), so without this they'd be counted yet invisible. Worktree
+ * tickets are lowercased, so the natural id is lowercased before matching.
+ */
+function inProgressWithoutWorktree(issues, worktreeTickets) {
+    return issues
+        .filter((issue) => issue.status === "in-progress")
+        .filter((issue) => !worktreeTickets.has(naturalIdFromCanonical(issue.id).toLowerCase()))
+        .toSorted((left, right) => left.id.localeCompare(right.id));
+}
+function writeInProgressIssue(issue) {
+    const naturalId = naturalIdFromCanonical(issue.id);
+    writeOutput(issue.url === undefined ? naturalId : `${naturalId}  ${issue.url}`);
+    writeOutput(inventoryField("title", issue.title));
+    if (issue.repository !== undefined) {
+        writeOutput(inventoryField("repo", issue.repository));
+    }
+}
+function writeInProgressWithoutWorktree(boardResult, worktreeTickets) {
+    if (boardResult.kind !== "ok") {
+        return;
+    }
+    const issues = inProgressWithoutWorktree(boardResult.issues, worktreeTickets);
+    if (issues.length === 0) {
+        return;
+    }
+    writeSection("In progress (no local worktree)");
+    for (const [index, issue] of issues.entries()) {
+        if (index > 0) {
+            writeOutput();
+        }
+        writeInProgressIssue(issue);
+    }
+}
 async function writeInventoryStatus(config) {
     // Banner ("groundcrew status\n=================") dropped: the command
     // you just ran already tells you what report you're looking at, and the
@@ -469,6 +520,7 @@ async function writeInventoryStatus(config) {
     const worktreeTickets = new Set(worktrees.list(config).map((entry) => entry.ticket));
     writeStraySessions(probe, worktreeTickets);
     const boardResult = await boardResultPromise;
+    writeInProgressWithoutWorktree(boardResult, worktreeTickets);
     if (boardResult.kind === "ok") {
         const used = inProgressCount(boardResult.issues);
         writeOutput();

package/dist/lib/config.d.ts

@@ -241,6 +241,15 @@ export interface ResolvedConfig {
         file: string;
     };
 }
+export type ConfigSourceKind = "env" | "project" | "xdg";
+export interface ConfigSource {
+    kind: ConfigSourceKind;
+    filepath: string;
+}
+export interface LoadedConfig {
+    config: Readonly<ResolvedConfig>;
+    source: Readonly<ConfigSource>;
+}
 /**
  * Single source of truth for "is preLaunchEnv asking us to forward anything?"
  *
@@ -258,5 +267,6 @@ export declare function hasPreLaunchEnv(definition: Pick<ModelDefinition, "preLa
  * not enabled from an arbitrary unknown label like `agent-typo`.
  */
 export declare function isBuiltInModelNotEnabled(config: Pick<ResolvedConfig, "models">, name: string): boolean;
+export declare function loadConfigWithSource(): Promise<Readonly<LoadedConfig>>;
 export declare function loadConfig(): Promise<Readonly<ResolvedConfig>>;
 //# sourceMappingURL=config.d.ts.map

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

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

package/dist/lib/config.js

@@ -606,26 +606,28 @@ async function discoverUserConfig() {
         if (!existsSync(overridePath)) {
             fail(`GROUNDCREW_CONFIG=${overridePath} not found`);
         }
-        return await loadAt(overridePath);
+        const result = await loadAt(overridePath);
+        return { result, source: { kind: "env", filepath: result.filepath } };
     }
     const project = await explorer.search(process.cwd());
     if (project !== null && project.isEmpty !== true) {
-        return project;
+        return { result: project, source: { kind: "project", filepath: project.filepath } };
     }
     const xdgPath = findXdgConfigFile();
     if (xdgPath !== undefined) {
-        return await loadAt(xdgPath);
+        const result = await loadAt(xdgPath);
+        return { result, source: { kind: "xdg", filepath: result.filepath } };
     }
     // Throw directly so oxlint's `consistent-return` rule sees a
     // terminating statement; it doesn't track `fail()`'s `never` return.
     throw new Error(`groundcrew config: no crew config found. Create crew.config.ts in your project root, or ${xdgConfigPath("groundcrew", "crew.config.ts")}, or set GROUNDCREW_CONFIG.`);
 }
 let cached;
-export async function loadConfig() {
+export async function loadConfigWithSource() {
     if (cached) {
         return cached;
     }
-    const result = await discoverUserConfig();
+    const { result, source } = await discoverUserConfig();
     const { filepath, isEmpty } = result;
     const userConfig = result.config;
     if (isEmpty === true || !isPlainObject(userConfig)) {
@@ -636,6 +638,13 @@ export async function loadConfig() {
     const resolved = applyDefaults(userConfig);
     validate(resolved);
     setLogFile(resolved.logging.file);
-    cached = Object.freeze(resolved);
+    cached = Object.freeze({
+        config: Object.freeze(resolved),
+        source: Object.freeze(source),
+    });
     return cached;
 }
+export async function loadConfig() {
+    const loadedConfig = await loadConfigWithSource();
+    return loadedConfig.config;
+}

package/docs/commands.md

@@ -4,7 +4,7 @@
 
 `crew status <TICKET>` prints a read-only snapshot for one ticket: cached title and URL when present, recorded run state, live workspace presence, matching worktrees, git dirtiness, PR links for matching branches, recent log lines when present, and the ticket status from the configured ticket source.
 
-`crew status` with no ticket prints the current inventory: known worktrees with cached ticket metadata, workspace/run-state agreement, attach hints, worktree paths, PR links, and stray sessions reported by the configured backend. Local diagnostics are printed before ticket-source fetches complete. When the source fetch succeeds, status also prints slot usage plus Queue/Blocked sections for eligible Todo tickets. If the source fetch fails, Queue shows `unavailable: <reason>` and the slots line is omitted.
+`crew status` with no ticket prints the current inventory: known worktrees with cached ticket metadata, workspace/run-state agreement, attach hints, worktree paths, PR links, and stray sessions reported by the configured backend. Local diagnostics are printed before ticket-source fetches complete. When the source fetch succeeds, status also prints any in-progress source tickets with no local worktree, slot usage, and Queue/Blocked sections for eligible Todo tickets. Worktree-less in-progress rows include the ticket title, URL when the source provides one, and repository when the source resolves one. If the source fetch fails, Queue shows `unavailable: <reason>` and the slots line is omitted.
 
 Status is informational only. Use `crew cleanup <TICKET>` to tear down stale worktrees and `crew resume <TICKET>` to reopen preserved work.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clipboard-health/groundcrew",
-  "version": "4.9.0",
+  "version": "4.10.1",
   "description": "Linear-driven orchestrator that launches AI coding agents in git worktrees, with workspace lifecycle and usage tracking.",
   "keywords": [
     "agent",
@@ -84,7 +84,7 @@
     "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "@vitest/coverage-v8": "4.1.7",
     "cspell": "10.0.0",
-    "dependency-cruiser": "17.4.2",
+    "dependency-cruiser": "17.4.3",
     "husky": "9.1.7",
     "jscpd": "4.2.4",
     "knip": "6.14.2",

package/static/demo-fixture.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Semantic ANSI colors. Actual hues are defined by the VHS theme in demo.tape,
+# so content and chrome stay in sync: green = orchestrator, yellow = codex,
+# blue = claude, bright-black = dim chrome.
+c_reset=$'\033[0m'
+c_dim=$'\033[90m'
+c_green=$'\033[32m'
+c_amber=$'\033[33m'
+c_blue=$'\033[34m'
+
+export PS1="\[${c_green}\]groundcrew\[${c_dim}\] on \[${c_reset}\]main \[${c_green}\]\$\[${c_reset}\] "
+
+tmux rename-window 'crew run --watch'
+tmux set-option -g status off
+tmux set-option -g pane-border-status top
+tmux set-option -g pane-border-format ' #{?#{m:codex*,#{pane_title}},#[fg=#fbbf24],#{?#{m:claude*,#{pane_title}},#[fg=#60a5fa],#[fg=#77d94e]}}#[bold]#{pane_title}#[default] '
+# Use one divider color for active and inactive panes. tmux highlights only the
+# active-adjacent segment of a shared divider, so a distinct active color makes a
+# single divider render two-tone (and the dim half reads as "missing"). A uniform
+# color keeps every divider a clean, continuous line. Accent lives in pane titles.
+tmux set-option -g pane-border-style 'fg=#52525b'
+tmux set-option -g pane-active-border-style 'fg=#52525b'
+tmux set-option -g remain-on-exit on
+
+printf '\033]2;groundcrew\033\\'
+
+# This agent script prints 12 lines into a split pane. The pane heights are set
+# by `Set Height` in demo.tape (see the note there) so all 12 fit without
+# scrolling — a scrolling pane makes its top border drift. If you add or remove
+# output lines here, keep that height in sync.
+demo_agent_script="$(mktemp "${TMPDIR:-/tmp}/groundcrew-vhs-agent.XXXXXX")"
+trap 'rm -f "${demo_agent_script}"' EXIT
+cat >"${demo_agent_script}" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+ticket="${1}"
+model="${2}"
+title="${3}"
+worktree="${4:-groundcrew-${ticket}}"
+branch="groundcrew/${ticket}"
+
+reset=$'\033[0m'
+bold=$'\033[1m'
+dim=$'\033[90m'
+green=$'\033[32m'
+case "${model}" in
+  codex) accent=$'\033[33m' ;;
+  claude) accent=$'\033[34m' ;;
+  *) accent=$'\033[32m' ;;
+esac
+
+printf '\033]2;%s %s\033\\' "${model}" "${ticket}"
+printf '%s%s%s    clipboard/groundcrew\n' "${dim}" 'repo' "${reset}"
+printf '%s%s%s  %s\n\n' "${dim}" 'branch' "${reset}" "${branch}"
+sleep 0.4
+printf '%s$%s %s%s%s %s< prompts/%s.txt%s\n\n' "${dim}" "${reset}" "${accent}" "${model}" "${reset}" "${dim}" "${ticket}" "${reset}"
+sleep 0.5
+printf '%sTicket%s    %s\n' "${dim}" "${reset}" "${title}"
+sleep 0.4
+printf '%sWorktree%s  %s~/dev/c/%s%s\n\n' "${dim}" "${reset}" "${dim}" "${worktree}" "${reset}"
+sleep 0.5
+printf '%sReading repo context...%s\n' "${dim}" "${reset}"
+sleep 0.5
+printf '%sEditing in isolated branch...%s\n' "${dim}" "${reset}"
+sleep 0.5
+printf '%sRunning verification...%s\n' "${dim}" "${reset}"
+sleep 0.5
+# No trailing newline: keeps the final line flush against the pane bottom so the
+# pane never has to scroll a phantom empty line (which VHS renders as the top
+# border drifting down).
+printf '%s%s✓ Ready for review.%s' "${green}" "${bold}" "${reset}"
+
+while :; do
+  sleep 60
+done
+SH
+chmod +x "${demo_agent_script}"
+
+demo_ts_second=18
+
+demo_log() {
+  printf '%s[15:23:%02d]%s %s\n' "${c_dim}" "${demo_ts_second}" "${c_reset}" "${1}"
+  demo_ts_second=$((demo_ts_second + 1))
+}
+
+crew() {
+  if [[ "${1:-}" != "run" || "${2:-}" != "--watch" ]]; then
+    printf '%s\n' 'demo supports: crew run --watch'
+    return 2
+  fi
+
+  local pane_one
+
+  demo_log "${c_dim}Linear viewer ·${c_reset} Rocky Warren"
+  sleep 0.5
+  demo_log "${c_dim}Slots${c_reset} 0/3 ${c_dim}· dispatching${c_reset} ${c_amber}ENG-184${c_reset}${c_dim},${c_reset} ${c_blue}ENG-217${c_reset}"
+  sleep 0.6
+
+  demo_log "${c_dim}Worktree${c_reset} web-ENG-184 ${c_dim}→${c_reset} groundcrew/ENG-184"
+  sleep 0.5
+  pane_one="$(
+    tmux split-window -d -h -p 42 -P -F '#{pane_id}' -- \
+      "${demo_agent_script} ENG-184 codex 'Add Jira ticket source docs' web-ENG-184"
+  )"
+  sleep 0.7
+  demo_log "${c_green}✓${c_reset} ${c_amber}ENG-184${c_reset} launched ${c_dim}·${c_reset} ${c_amber}codex${c_reset}"
+  sleep 0.7
+
+  demo_log "${c_dim}Worktree${c_reset} api-ENG-217 ${c_dim}→${c_reset} groundcrew/ENG-217"
+  sleep 0.5
+  tmux split-window -d -v -p 50 -t "${pane_one}" -P -F '#{pane_id}' -- \
+    "${demo_agent_script} ENG-217 claude 'Fix flaky status output' api-ENG-217" >/dev/null
+  sleep 0.7
+  demo_log "${c_green}✓${c_reset} ${c_blue}ENG-217${c_reset} launched ${c_dim}·${c_reset} ${c_blue}claude${c_reset}"
+  sleep 0.7
+
+  demo_log "${c_dim}Queue clear · next poll in 60s${c_reset}"
+  tmux refresh-client
+  # Hold the fully-settled layout on screen. Must outlast the tape's trailing
+  # Sleep so the orchestrator pane never drops back to a shell prompt on camera.
+  sleep 20
+}

package/static/demo.tape

@@ -0,0 +1,47 @@
+# cspell:ignore noprofile norc ttyd
+
+Output static/demo.gif
+Require bash
+Require ffmpeg
+Require tmux
+Require ttyd
+
+Set Shell "bash"
+Set Width 1320
+# 690px ≈ 28 terminal rows. The right column splits into two stacked agent panes
+# of ~13 content rows each, sized to hold the demo-fixture.sh agent script's
+# 12-line output without scrolling (a scrolling pane makes its top border drift).
+# Grow this if that output grows past ~13 lines.
+Set Height 690
+Set FontSize 16
+Set FontFamily "Menlo"
+Set Padding 16
+Set Margin 40
+Set MarginFill "#0a0a0b"
+Set WindowBar Colorful
+Set BorderRadius 12
+Set TypingSpeed 35ms
+Set CursorBlink false
+Set Theme '{ "background": "#18181b", "foreground": "#e4e4e7", "cursor": "#77d94e", "selection": "#3f3f46", "black": "#27272a", "red": "#fb7185", "green": "#77d94e", "yellow": "#fbbf24", "blue": "#60a5fa", "magenta": "#c084fc", "cyan": "#34d399", "white": "#e4e4e7", "brightBlack": "#52525b", "brightRed": "#fda4af", "brightGreen": "#a3e635", "brightYellow": "#fcd34d", "brightBlue": "#93c5fd", "brightMagenta": "#d8b4fe", "brightCyan": "#6ee7b7", "brightWhite": "#fafafa" }'
+
+Hide
+Type "tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew 2>/dev/null || true"
+Enter
+Type "tmux -f /dev/null -L groundcrew-demo new-session -s groundcrew -- /bin/bash --noprofile --norc"
+Enter
+Type "source static/demo-fixture.sh"
+Enter
+Type "clear"
+Enter
+Show
+
+Sleep 1.0
+Type "crew run --watch"
+Sleep 0.4
+Enter
+# ~8s of action, then hold the settled layout long enough to read all three panes.
+Sleep 15
+
+Hide
+Type "tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew"
+Enter

package/static/render-demo.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# cspell:ignore ttyd
+set -euo pipefail
+
+script_dir="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+repo_dir="$(cd -- "${script_dir}/.." && pwd)"
+cd "${repo_dir}"
+
+for required_command in vhs ttyd tmux ffmpeg; do
+  if ! command -v "${required_command}" >/dev/null 2>&1; then
+    printf 'Missing required command: %s\n' "${required_command}" >&2
+    exit 127
+  fi
+done
+
+tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew 2>/dev/null || true
+
+log_file="$(mktemp)"
+trap 'rm -f "${log_file}"' EXIT
+
+for attempt in 1 2 3; do
+  rm -f "${log_file}"
+
+  if VHS_NO_SANDBOX="${VHS_NO_SANDBOX:-1}" vhs static/demo.tape 2>&1 | tee "${log_file}"; then
+    exit 0
+  fi
+
+  status="${PIPESTATUS[0]}"
+  tmux -f /dev/null -L groundcrew-demo kill-session -t groundcrew 2>/dev/null || true
+
+  if ! grep -Eq 'could not open ttyd|ERR_CONNECTION_REFUSED' "${log_file}"; then
+    exit "${status}"
+  fi
+
+  if [[ "${attempt}" -eq 3 ]]; then
+    exit "${status}"
+  fi
+
+  sleep "${attempt}"
+done