Six stacked pull requests, landed as one

.github/workflows/test.yml

@@ -142,7 +142,11 @@ jobs:
           go-version-file: 'go.mod'
 
       - name: Run tests with race detector
-        run: go test -tags dev -race -v ./...
+        # 20 minutes, not Go's default 10 per package. internal/connector runs
+        # real sockets, real processes and the recovery harness; under -race it
+        # takes about five minutes on a fast box and roughly twice that on a
+        # runner. The default was not a hung test, it was the budget.
+        run: go test -tags dev -race -v -timeout 20m ./...
 
   integration:
     name: Integration Tests

.naming-allowlist

@@ -21,3 +21,5 @@ keyring(bcq
 legacy bcq
 # RELEASING.md — actual GitHub App name
 bcq-release-bot
+# npm integrity hashes are base64 and can contain any letters
+./internal/connector/driver/acp/adapters/package-lock.json

Makefile

@@ -130,6 +130,33 @@ qa-report:
 		echo ""; \
 	fi
 
+# The connector's acp driver runs pinned ACP adapters, installed here once by
+# an operator and never downloaded at dispatch time.
+# Where basecamp connect looks by default: an absolute $XDG_DATA_HOME, else
+# ~/.local/share (a relative XDG_DATA_HOME is ignored there too).
+ACP_ADAPTERS_DIR ?= $(if $(filter /%,$(XDG_DATA_HOME)),$(XDG_DATA_HOME),$(HOME)/.local/share)/basecamp/acp-adapters
+
+# Install the pinned ACP adapters (internal/connector/driver/acp/adapters).
+# --engine-strict: an adapter whose Node version requirement this machine does
+# not meet fails the install, not the first dispatch.
+.PHONY: acp-adapters
+acp-adapters:
+	@mkdir -p "$(ACP_ADAPTERS_DIR)"
+	cp internal/connector/driver/acp/adapters/package.json internal/connector/driver/acp/adapters/package-lock.json "$(ACP_ADAPTERS_DIR)/"
+	npm ci --prefix "$(ACP_ADAPTERS_DIR)" --ignore-scripts --no-audit --no-fund --engine-strict
+
+# The ACP adapter-compatibility test: eight checks through the acp driver
+# against each installed adapter (the spike's four, the worker shell's
+# environment, a decoy MCP server in the working directory, the task
+# token's bridge, and what an adapter does when a session's MCP server dies
+# mid-session). Sends real prompts (model quota); skipped
+# for an adapter that is not installed. ACP_TRANSCRIPTS=<dir> keeps redacted
+# JSON-RPC transcripts.
+.PHONY: test-acp-compat
+test-acp-compat: check-toolchain
+	BASECAMP_ACP_ADAPTERS_DIR="$(ACP_ADAPTERS_DIR)" BASECAMP_ACP_TRANSCRIPTS="$(ACP_TRANSCRIPTS)" \
+		$(GOTEST) -tags acpcompat -run TestAdapterCompat -count=1 -timeout 30m -v ./internal/connector/driver/acp/
+
 # Run tests with race detector
 .PHONY: race-test
 race-test: check-toolchain
@@ -294,6 +321,9 @@ provenance-check:
 .PHONY: vet
 vet: check-toolchain
 	$(GOVET) $(BUILD_TAGS) ./...
+	@# The adapter-compatibility test builds only with its own tag, so
+	@# nothing else would notice it rotting.
+	$(GOVET) -tags acpcompat ./internal/connector/driver/acp/
 
 # Format code
 .PHONY: fmt

STYLE.md

@@ -50,6 +50,12 @@ recording's change history and predates the account-wide event feed that
 rather than becoming a group: turning it into one would break every existing
 `basecamp events <id>` invocation to gain nothing.
 
+`connect` is the other exception. The spec names the connector's run as the bare
+`basecamp connect -P <agent>`, a long-running foreground command in the grain of
+`basecamp mcp`, with `setup` beside it as the one-off that prepares it. Making the
+run a `connect run` subcommand would put a verb under a command that is already
+the verb.
+
 `scripts/check-bare-groups.sh` enforces this with an allowlist; a command added
 there belongs in this section too, with the reason it is an exception.
 

e2e/smoke/smoke_lifecycle.bats

@@ -24,6 +24,42 @@ load smoke_helper
   mark_out_of_scope "Reads the connector policy a connected profile's setup wrote — covered by Go tests in internal/commands"
 }
 
+@test "connect status is out of scope" {
+  mark_out_of_scope "Reads a local connector ledger the smoke account does not have — covered by Go tests in internal/commands and internal/connector"
+}
+
+@test "connect doctor is out of scope" {
+  mark_out_of_scope "Needs a set-up connector profile and starts its MCP server — covered by Go tests in internal/commands"
+}
+
+@test "connect redispatch is out of scope" {
+  mark_out_of_scope "Decides a record in a local connector ledger — covered by Go tests in internal/commands and internal/connector"
+}
+
+@test "connect discard is out of scope" {
+  mark_out_of_scope "Decides a record in a local connector ledger — covered by Go tests in internal/commands and internal/connector"
+}
+
+@test "connect release is out of scope" {
+  mark_out_of_scope "Clears the hold in a local connector ledger — covered by Go tests in internal/commands and internal/connector"
+}
+
+@test "connect shadow promote is out of scope" {
+  mark_out_of_scope "Moves a local shadow ledger — covered by Go tests, including a process killed at every step, in internal/connector"
+}
+
+@test "connect import is out of scope" {
+  mark_out_of_scope "Applies a reconciliation file to a local connector ledger — covered by Go tests in internal/commands and internal/connector"
+}
+
+@test "connect worktrees list is out of scope" {
+  mark_out_of_scope "Reads a local connector's ledger — covered by Go tests in internal/commands and internal/connector"
+}
+
+@test "connect worktrees prune is out of scope" {
+  mark_out_of_scope "Removes local git worktrees a connector kept — covered by Go tests in internal/commands and internal/connector"
+}
+
 @test "auth refresh is out of scope" {
   mark_out_of_scope "Requires OAuth credentials"
 }

internal/commands/commands.go

@@ -146,7 +146,7 @@ func CommandCategories() []CommandCategory {
 				{Name: "bonfire", Category: "additional", Description: "Multi-chat orchestration", Actions: []string{"split", "layout"}, Experimental: true, DevOnly: true},
 				{Name: "api", Category: "additional", Description: "Raw API access"},
 				{Name: "mcp", Category: "additional", Description: "Serve Basecamp to MCP clients over stdio"},
-				{Name: "connect", Category: "additional", Description: "Set up a local agent connector for a Basecamp agent", Actions: []string{"setup", "show"}},
+				{Name: "connect", Category: "additional", Description: "Run a local agent connector for a Basecamp agent, and see and decide what it runs", Actions: []string{"setup", "show", "status", "doctor", "redispatch", "discard", "release", "shadow", "import", "worktrees"}},
 				{Name: "help", Category: "additional", Description: "Show help"},
 				{Name: "version", Category: "additional", Description: "Show version"},
 			},

internal/commands/connect.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path/filepath"
 	"runtime"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -29,20 +30,53 @@ import (
 
 // NewConnectCmd is the local agent connector's command group.
 func NewConnectCmd() *cobra.Command {
+	var run connectRunFlags
 	cmd := &cobra.Command{
 		Use:   "connect",
-		Short: "Set up a local agent connector for a Basecamp agent",
+		Short: "Run a local agent connector for a Basecamp agent",
 		Long: `Run a local agent connector: it listens to the account event feed as a
 Basecamp agent, admits what a trusted person asks of that agent, and hands
 the work to a local coding agent that replies in Basecamp as the agent.
 
 Connect the agent to a profile first (basecamp auth agent connect -P <profile>),
 then run setup on that profile: it records who may drive the agent, maps
 projects to the directories their work runs in, and checks the connector is
-ready. Show prints what setup recorded.`,
+ready. Show prints what setup recorded. Then run the connector on it:
+
+  basecamp connect -P <profile> [--project <id>]... [--shadow]
+
+It runs in the foreground until interrupted. Stdout is a wire of one JSON
+object per line (events seen, verdicts, dispatches, lifecycle messages;
+never content), and logs
+go to stderr. SIGINT and SIGTERM cancel live workers with stop reason
+shutdown, settle them, and exit 130 and 143. --shadow admits and logs in an
+isolated state directory and dispatches nothing. --hold sets a durable hold:
+intake and admission run, nothing dispatches or posts, and earlier records
+wait for review, until basecamp connect release. Linux only.
+
+  basecamp connect status             what it heard, holds and ran
+  basecamp connect doctor             what it needs to run
+  basecamp connect redispatch <id>    authorize a record to run
+  basecamp connect discard <id>       close a record without running it
+  basecamp connect release            clear the hold
+  basecamp connect shadow promote     make the shadow ledger the connector's, held
+  basecamp connect import <file>      apply a cutover reconciliation file`,
+		Example: `  basecamp connect setup -P agent --operator-profile me --route 12345=/src/app
+  basecamp connect -P agent
+  basecamp connect -P agent --project 12345 --shadow`,
+		Args: cobra.NoArgs,
+		Annotations: map[string]string{
+			"agent_notes": "Long-running; stdout is NDJSON pointer lines, logs on stderr. Not for interactive use.",
+			"stdout_wire": "connect",
+		},
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runConnect(cmd, &run)
+		},
 	}
-	cmd.AddCommand(newConnectSetupCmd())
-	cmd.AddCommand(newConnectShowCmd())
+	addConnectRunFlags(cmd, &run)
+	cmd.AddCommand(newConnectSetupCmd(), newConnectWorkerMCPCmd(), newConnectShowCmd(), newConnectStatusCmd(), newConnectDoctorCmd(),
+		newConnectRedispatchCmd(), newConnectDiscardCmd(), newConnectReleaseCmd(), newConnectShadowCmd(), newConnectImportCmd(),
+		newConnectWorktreesCmd())
 	return cmd
 }
 
@@ -157,7 +191,11 @@ func connectShowDisplay(path string, f setup.File, markdown bool) map[string]any
 		"agent":    agent,
 		"operator": fmt.Sprintf("person %d", f.Trust.OperatorID),
 		"trust":    trust,
-		"workers":  fmt.Sprintf("%s, concurrency %d, deadline %s, worktrees %s", f.Driver, f.Concurrency, time.Duration(f.Deadline), worktrees),
+		// The worker as well as the driver: the file records which coding
+		// agent the driver runs, and a file written before that field
+		// existed still means the default, which is what a person reading
+		// show needs to see.
+		"workers":  fmt.Sprintf("%s running %s, concurrency %d, deadline %s, worktrees %s", f.Driver, f.WorkerName(), f.Concurrency, time.Duration(f.Deadline), worktrees),
 		"projects": strconv.Itoa(len(f.Projects)) + " routed",
 	}
 	for id, r := range f.Projects {
@@ -233,6 +271,7 @@ type connectSetupFlags struct {
 	unwatch   []string
 	unroute   []string
 	driver    string
+	worker    string
 	parallel  int
 	deadline  time.Duration
 	worktrees bool
@@ -315,6 +354,7 @@ Examples:
 	fl.StringArrayVar(&f.watch, "watch-completions", nil, "Admit every trusted completion in a routed project (repeatable)")
 	fl.StringArrayVar(&f.unwatch, "no-watch-completions", nil, "Stop watching a project's completions (repeatable)")
 	fl.StringVar(&f.driver, "driver", "", "How workers are run: spawn or acp (default spawn)")
+	fl.StringVar(&f.worker, "worker", "", fmt.Sprintf("The coding agent workers run: %s (default %s)", strings.Join(setup.Workers, ", "), setup.DefaultWorker))
 	fl.IntVar(&f.parallel, "concurrency", 0, fmt.Sprintf("Workers at once (default %d)", setup.DefaultConcurrency))
 	fl.DurationVar(&f.deadline, "deadline", 0, fmt.Sprintf("Deadline per task (default %s)", setup.DefaultDeadline))
 	fl.BoolVar(&f.worktrees, "worktrees", false, "Give each task its own git worktree")
@@ -749,6 +789,10 @@ func (f *connectSetupFlags) changes(cmd *cobra.Command) (setup.Changes, error) {
 	default:
 		return ch, output.ErrUsage(fmt.Sprintf("Invalid --driver %q: use spawn or acp", f.driver))
 	}
+	if f.worker != "" && !slices.Contains(setup.Workers, f.worker) {
+		return ch, output.ErrUsage(fmt.Sprintf("Invalid --worker %q: use %s", f.worker, strings.Join(setup.Workers, ", ")))
+	}
+	ch.Worker = f.worker
 	// A typed zero is out of range, not a request for the default: the flags
 	// are read as typed, not as their zero values.
 	if cmd.Flags().Changed("concurrency") {