borgmcp 3.11.1 → 3.13.0

package/docs/RELEASING.md

@@ -8,8 +8,9 @@ npm Trusted Publishing; no long-lived npm token is stored or exposed.
 ## Release Integrity
 
 Release provenance is established by protected annotated tags, GitHub build
-provenance, and npm Trusted Publishing. Tags and publication workflows are
-immutable: never move, replace, reuse, or rerun them.
+provenance, and npm Trusted Publishing. Never move, replace, or reuse a tag.
+A failed workflow may be rerun until npm accepts a stage; stage acceptance
+consumes the version.
 
 ## Release Prerequisites
 
@@ -20,19 +21,15 @@ Before creating the release tag, independently verify all of these conditions:
 - the extraction review confirms no private backend secrets, deployment
   configuration, customer data, local state, or duplicated shared contracts
   entered the public package;
-- the exact audited registry dependency `borgmcp-shared@0.11.0` remains locked to
+- the exact audited registry dependency `borgmcp-shared@0.12.2` remains locked to
   its canonical tarball and integrity
-  `sha512-I8mixCbSrLKyOAAyqEI/HZJ8cML2rz3r812Up8pr547OdAk9LxZevdCo7ojG42ZwrUmS5u7iKQPg7Vk1XvtX1g==`;
-- the coupled shared/server/client candidates have all been built against the
-  same exact `borgmcp-shared` version and passed the complete local dogfood gate
-  before any stage is approved;
+  `sha512-l459XEeqk0cSz1+Z8yk8cCVWik4/CX4OBTRZqj6n1SZYvDpzWJksUz82FA9k4taf//rs43Tfl1tpWXnRHAqxOQ==`;
+- the coupled shared/server/client candidates use the same exact
+  `borgmcp-shared` version;
 - the selected stable client version is unused and the exact release commit is
   on protected `main`;
 - the repository and protected npm environment settings pass an operator audit;
-- the exact release source passes Code Review, Security Review, Release Quality,
-  extraction, and package gates; and
-- the immutable annotated tag and publication receive explicit release
-  authorization.
+- the exact release source passes exact-SHA CI and one Code Review.
 
 `scripts/verify-release-readiness.mjs` makes the source-side blockers
 machine-checkable. A release tag created before they are resolved fails before
@@ -41,18 +38,19 @@ dependency installation or publication.
 ### Release branches
 
 Release branches use the `release/` prefix and enter protected `main` through a
-pull request. Direct pushes only update staging branches; publication still
-requires the complete protected release gate.
+pull request. After exact-SHA CI and one Code Review, merge the preparation and
+create its annotated version tag. The tag automatically verifies and stages the
+package.
 
 ## Repository Controls
 
 Repository settings are operator-owned and are not changed by this workflow.
 Before preparing a candidate, independently verify:
 
-1. The `npm-publish` environment disables administrator bypass, requires the
-   reviewed human approver, and allows only the protected release refs. Its
-   `NPM_EXPECTED_OWNER` variable must match the sole reviewed maintainer of the
-   existing `borgmcp` package. It must contain no npm token.
+1. The `npm-publish` environment disables administrator bypass, has no required
+   reviewer, and allows only `v*.*.*` tags. Its `NPM_EXPECTED_OWNER` variable
+   must match the sole reviewed maintainer of the existing `borgmcp` package.
+   It must contain no npm token.
 2. npm Trusted Publishing is configured for organization `Byte-Ventures`,
    repository `borg-mcp-client`, workflow `publish.yml`, and environment
    `npm-publish`. Its allowed actions enable `npm stage publish` and disable
@@ -69,212 +67,8 @@ Before preparing a candidate, independently verify:
 
 ## Release Workflow
 
-### Clean-environment rig lifecycle
-
-Every clean-environment verification rig has an explicit identity and an
-explicit end-of-life. Run it from a Borg-launched session and keep filesystem
-workspaces under the exact disposable scratch root Borg exports. Give each
-workspace a name beginning with `borg-rig-` followed by its owner, purpose, and
-a unique suffix. Before the first command that can create files, anchor the rig
-as its own npm project:
-
-```sh
-BORG_SCRATCH_ROOT="${BORG_LAUNCH_SCRATCH:?run from a Borg-launched session}"
-RIG_OWNER="$(basename "$BORG_SCRATCH_ROOT")"
-RIG_NONCE="${RIG_NONCE:-$(date +%Y%m%d%H%M%S)-$$}"
-RIG_ID="borg-rig-${RIG_OWNER}-release-${RIG_NONCE}"
-RIG_ROOT="$BORG_SCRATCH_ROOT/$RIG_ID"
-mkdir -p "$RIG_ROOT"
-printf '%s\n' '{"private":true}' > "$RIG_ROOT/package.json"
-```
-
-The manifest anchor is required before any `npm install`, `npm update`, or
-other npm command. Without it, npm can walk up from an empty scratch directory
-and write the operator's `package.json` instead of creating project-local
-state. In a source checkout, the committed `release:exercise` follows this rule
-for its temporary consumer; other QA scripts and manual rigs must do the same.
-
-The system temporary root is shared with the whole machine, so an unbounded
-listing there is not an inspectable cleanup check. Bound that leg by the
-invoking user and the run-window markers, which select directories whose
-timestamps fall within this run window without requiring a prefix inventory.
-New `mkdtemp` prefixes therefore require no documentation change. Keep both
-time predicates and the ownership predicate: removing the run-window bound
-turns a populated shared temp root back into an uninspectable listing.
-
-On a machine where several runs share one user account, this listing can
-include another run's live workspace. Removal is scoped to paths created by
-this run; anything else in the output is reported, not deleted. Unrelated
-same-user temporary directories created during the window can therefore
-appear in the result, so never remove a path merely because this listing found
-it.
-
-```sh
-TEMP_ROOT="${TMPDIR:-/tmp}"
-TEMP_OWNER="$(id -un)"
-TEMP_SCAN_START="$TEMP_ROOT/.${RIG_ID}-temp-scan-start"
-TEMP_SCAN_END="$TEMP_ROOT/.${RIG_ID}-temp-scan-end"
-
-list_recent_owned_temp_rigs() {
-  find "$TEMP_ROOT" -mindepth 1 -prune \
-    -type d \
-    -user "$TEMP_OWNER" \
-    -newer "$TEMP_SCAN_START" \
-    ! -newer "$TEMP_SCAN_END" \
-    -print
-}
-
-touch "$TEMP_SCAN_START"
-```
-
-Container-backed rigs use the same `RIG_ID` as the container name and carry
-both labels below. Register exact-target cleanup before launching the rig:
-
-```sh
-list_owned_rig_containers() {
-  docker container ls --all \
-    --filter label=borg-rig=1 \
-    --filter "label=borg-rig-owner=${RIG_OWNER:?}" \
-    --format '{{.ID}}\t{{.Names}}\t{{.Status}}'
-}
-
-cleanup_done=0
-cleanup() {
-  [ "$cleanup_done" -eq 0 ] || return
-  cleanup_done=1
-  trap - EXIT HUP INT TERM
-  docker container rm --force "$RIG_ID" >/dev/null 2>&1 || true
-  rm -rf -- "$RIG_ROOT"
-  list_owned_rig_containers
-  find "$BORG_SCRATCH_ROOT" -mindepth 1 -print
-  find "$BORG_SCRATCH_ROOT" -name 'borg-rig-*' -print
-  if [ -e "$TEMP_SCAN_START" ]; then
-    touch "$TEMP_SCAN_END"
-    list_recent_owned_temp_rigs
-  fi
-  rm -f -- "$TEMP_SCAN_START" "$TEMP_SCAN_END"
-}
-trap cleanup EXIT
-trap 'exit 129' HUP
-trap 'exit 130' INT
-trap 'exit 143' TERM
-```
-
-List containers and scratch paths before starting. The filters distinguish this
-session's rigs from unrelated containers on a shared host:
-
-```sh
-list_owned_rig_containers
-find "$BORG_SCRATCH_ROOT" -mindepth 1 -print
-find "$BORG_SCRATCH_ROOT" -name 'borg-rig-*' -print
-```
-
-Only after the cleanup traps and pre-launch listings are in place, launch a
-container-backed rig. `--rm` is preferred; a runtime without automatic removal
-must remove the exact `RIG_ID` in its cleanup path and retain the labels for a
-bounded sweep:
-
-```sh
-RIG_IMAGE="${RIG_IMAGE:?set the rig image}"
-docker run --rm \
-  --name "$RIG_ID" \
-  --label borg-rig=1 \
-  --label "borg-rig-owner=$RIG_OWNER" \
-  "$RIG_IMAGE"
-```
-
-The unfiltered filesystem listings expose legacy names as well as conforming
-rigs. The bounded temporary-directory function reports same-user directories
-created during the run window, including unrelated work; it does not establish
-which process owns them. The cleanup path runs the container and scratch
-listings after removing this rig, then runs the bounded temporary-directory
-listing between the start and end markers. Inspect and report its results. If a
-rig creates an exact system-temporary path, record that path when it is created
-and remove that exact path during cleanup; never remove a path solely because
-the bounded listing found it.
-
-Register cleanup before launching any process, run it on success and failure,
-and do not deliver a verdict until the container listing and both scratch
-listings show no rig owned by this run, every exact system-temporary path
-recorded by the rig has been removed, and the bounded temporary-directory
-listing has been inspected and reported. For a non-`--rm` container runtime,
-remove only the named rig or the same owner label; never prune unrelated
-containers. A completed verification
-therefore implies zero running or stopped rig containers and no rig workspace
-created by this run left in either the session scratch root or any exact
-system-temporary path the rig recorded.
-
-### Pre-tag composed exercise
-
-Before creating a release tag, exercise the packed client against the selected
-server artifact:
-
-```sh
-npm run release:exercise -- \
-  --server /absolute/path/to/borgmcp-server.tgz \
-  --server-integrity 'sha512-...'
-```
-
-The server integrity must come from the reviewed producer of that artifact. Run
-the command once with the published counterpart. When the client and server are
-being released together, run it again with the co-releasing server candidate.
-The default path builds and packs the current client; `--client-tarball` exists
-only for reproducing a reviewed packed client or running a negative control.
-
-This harness exercises reviewed release candidates and their published
-counterparts. It is not a containment sandbox for hostile or otherwise untrusted
-packages and must not be used as one. The temporary install and data directories
-isolate the reviewed exercise from normal product state; they are not an
-operating-system security boundary.
-
-The harness requires Node.js 22, npm 11.18.0, Python 3, and macOS or Linux. It
-installs both tarballs into a private temporary project, bootstraps isolated
-server data, and starts the installed server directly. It never uses
-`borg server setup`, because registry-backed activation would select the
-previously published server instead of a candidate.
-
-Both composed terminal journeys run under a real PTY:
-
-- `borg server dashboard` must render the attached-viewer footer, exit cleanly
-  on Ctrl-C, restore the cursor and alternate screen, and leave the server's
-  pinned-TLS process healthy at `GET /healthz` (204, empty body).
-- `borg server start` must render the foreground-server footer, exit cleanly on
-  Ctrl-C, restore the terminal, stop the server, and release its health endpoint.
-
-The client facade resolves `borg-mcp-server` by bare name. The harness therefore
-uses a controlled shim only to arrange resolution, then verifies the outcome:
-before trusting a frame, it reads the live process command and requires the
-absolute installed server entry. Every client or server executable must resolve
-inside the installed package root covered by the SRI cited for that role. Its
-JSON report records the absolute path, version, and independently supplied
-integrity for the client, dashboard listener, dashboard viewer, and foreground
-listener/viewer roles. PATH ordering alone is never accepted as identity evidence.
-
-The harness is a fail-closed release gate. A missing frame, non-PTY execution,
-wrong journey footer, substituted artifact, nonzero exit, absent terminal
-restore sequence, failed post-exit health assertion, timeout, or oversized
-transcript fails the command. Its controls must remain demonstrably bidirectional:
-the current client/server pairing passes; and a deliberately wrong server
-integrity fails before either journey starts.
-
-The terminal-restore negative control is specifically the packed pre-#146 client
-from commit `81da7b970ffb4e76a35c7bc551c419fec702a3b6` composed with published
-`borgmcp-server@0.2.0`, registry integrity
-`sha512-squb0+vdy0q7l/4FeV7OTvSm7OiFWGsAjGhcVEXYrQc9K/8jJYduqPS90VBwaJRT6z221Gxf3xQ5SeZe/Qoncw==`.
-That composition must fail on the missing cursor-restore sequence. A newer server
-candidate can mask the old client's defect and is not a valid counterpart for
-this negative control.
-
-```sh
-npm run release:exercise -- \
-  --server borgmcp-server@0.2.0 \
-  --server-integrity 'sha512-squb0+vdy0q7l/4FeV7OTvSm7OiFWGsAjGhcVEXYrQc9K/8jJYduqPS90VBwaJRT6z221Gxf3xQ5SeZe/Qoncw==' \
-  --client-tarball /absolute/path/to/pre-146-borgmcp-2.1.1.tgz
-```
-
 The only trigger is a protected annotated `v<package version>` tag. Manual
-dispatch is intentionally absent so a second run cannot rebuild or publish an
-existing tag. The workflow rejects reruns, root `.npmrc`
+dispatch is intentionally absent. The workflow rejects root `.npmrc`
 configuration, non-tag events, lightweight or malformed tags, version mismatch,
 source/tag mismatch, and tags whose commits are not on protected `main`.
 
@@ -283,7 +77,8 @@ The unprivileged `verify` job performs one sequence:
 1. Verify the public-source boundary, extraction readiness, exact shared-package
    pin, and canonical registry lock metadata.
 2. Install the lockfile once with lifecycle scripts disabled and audit it.
-3. Run type checks, tests, and one readable build; reject generated `dist` drift.
+3. Run one readable build and reject generated `dist` drift. Tests already ran
+   in CI on the exact source.
 4. Produce one npm tarball.
 5. Verify that tarball once for package identity, license/notice, source and map
    completeness, executable bins, archive safety, dependency integrity, and
@@ -294,14 +89,6 @@ The unprivileged `verify` job performs one sequence:
 7. Upload only the tarball and its verifier-generated report as the same-run
    release artifact.
 
-After `verify` succeeds, the designated Queen operator alone approves the
-`npm-publish` environment. There is no separate pre-stage exact-artifact
-Security gate: the verify job is the mechanical authority for the exact bytes
-that the stage job consumes. Environment approval authorizes submitting those
-bytes to npm's private staged-publishing service; it does not make the version
-public, permit a rerun or rebuilt artifact, or authorize approval by another
-actor.
-
 The protected `publish` job alone receives `id-token: write`. It downloads the
 same-run artifact and rejects a report whose package name or version differs
 from the release, a version that already exists, an unclaimed package, or an
@@ -313,48 +100,15 @@ package.
 
 Successful completion of the workflow means npm accepted the immutable staged
 tarball. It does not mean the version is public. Stage acceptance consumes the
-tagged attempt and version under the burned-version rule, but must not trigger
+version, but must not trigger
 release announcements, issue closure, consumer pins, site synchronization, or
 claims that the version was published. There is no workflow registry readback:
 stage inspection and approval require an interactive npm identity and cannot use
 the workflow's OIDC credential.
 
-### Coupled stage approval
-
-Before approving anything, the operator requires successful stage workflows for
-`borgmcp-shared`, `borgmcp-server`, and `borgmcp`. Use authenticated
-`npm stage list` and `npm stage view <UUID>` to record and inspect all three stage
-UUIDs and verify each package, version, and eventual `latest` tag. For every
-package, `npm stage download <UUID>` is mandatory; compute its SHA-512 SRI and
-require an exact match with that workflow run's same-run artifact report. Bind
-the source annotated tag object, commit, and workflow run separately from GitHub
-evidence, because npm stage inspection does not expose them. Exercise the exact
-downloaded coupled set before approval. Confirm that public `latest`, public
-`versions`, and client update resolution still expose the prior coherent release
-set. If a pending stage appears on any public surface, approve nothing and halt
-this mechanism before consumers can observe it.
-
-Approve the verified UUIDs in one operator session, using interactive 2FA, in
-this exact order:
-
-1. `npm stage approve <shared-stage-uuid>`
-2. `npm stage approve <server-stage-uuid>`
-3. `npm stage approve <client-stage-uuid>`
-
-The approvals are not atomic. Shared approval leaves existing client and server
-pins coherent. Server approval opens a bounded mismatch window between public
-server `latest` and client `latest`; client approval closes it. After an approval
-returns successfully, continue only while the next stage remains valid. For an
-ambiguous result, inspect authenticated stage state and canonical public package
-version/integrity before acting; never repeat an approval blindly.
-
-The terminal release boundary is successful interactive stage approval followed
-by canonical registry visibility, integrity verification, and registry
-provenance-attestation inspection. Stage inspection cannot establish provenance
-before approval; Trusted Publishing carries it to the live package, where the
-registry attestation is authoritative. Only then may the release be announced,
-issues closed, consumer pins or site data synchronized, or the version described
-as published.
+Inspect the npm stage, then approve it interactively. This stage approval is the
+sole human publication boundary. Confirm canonical live package visibility and
+integrity before announcing the release or updating dependent packages.
 
 After all three packages cross that boundary, create their GitHub Releases in
 the same shared → server → client operator session. In each package repository,
@@ -364,46 +118,16 @@ run:
 GITHUB_TOKEN="$(gh auth token)" node scripts/create-github-release.mjs <version>
 ```
 
-The script binds the annotated tag, merged release pull request, successful tag
-workflow artifact, and live npm integrity before creating the Release. It copies
-the merged release pull request body verbatim and refuses an existing Release.
-
-Separately, once the release is installable from the canonical registry, install
-it into an isolated prefix and exercise the real user update path end to end.
-This is product verification, not candidate validation: failure routes a new
-reviewed fix and never invalidates, rebuilds, retags, or reruns the immutable
-release. Do not repeat byte comparisons, packed-version checks, source-tree
-verification, dist-tag readback, or provenance reconstruction that the
-exact-artifact `verify` and stage jobs already completed. The canonical
-live-version integrity check is required because it establishes the approval
-boundary; it is not a duplicate candidate verification.
-
-No separate checksum file is needed: the tarball verifier records canonical
-SHA-512 SRI in the artifact report. GitHub's same-run artifact transport and the
-report bind the reviewed candidate without repeated SHA512 choreography.
-
-Rely on npm Trusted Publishing. Perform the one authoritative registry
-provenance-attestation inspection at the approved-live boundary; do not
-reconstruct DSSE, in-toto, SLSA, workflow-ref, or builder statements locally or
-add redundant provenance readback.
-Do not add cross-run tuple variables, cross-run artifact selection, duplicate
-builds, duplicate package verification, checksum bundles, or SBOM ceremony.
+The script binds the annotated tag, live npm package and integrity, and Release
+absence before creating the Release. It reads
+the curated `docs/releases/<version>.md` notes from the exact tagged commit,
+renders them under `News and fixes`, and refuses missing or blank notes and an
+existing Release.
 
 ## Stop And Recovery Conditions
 
-Stop when source, settings, ownership, tag, artifact, test, audit, review, or
-authorization evidence is missing or inconsistent. Never move or reuse a failed
-tag, rerun a failed release workflow, overwrite an npm version, unpublish to hide
-a failure, or substitute a local rebuild. Recovery starts from a fresh reviewed
-source change and, after any registry mutation, a separately authorized version.
-
-Before any approval, missing or inconsistent stage evidence means approve none.
-Reject all three stages only when abandoning the coupled candidate; Borg treats
-every rejected or unusable tagged stage as burned, even though npm permits some
-re-staging. Replacement versions require fresh review, tags, and stage runs.
-After shared approval but before server approval, stopping is compatibility-safe
-for the existing client/server pair, but shared is immutable and any repair uses
-fresh versions. After server approval, prioritize the already-verified client
-approval because the public pair is mismatched. If that client stage cannot be
-approved, do not reject it or rerun the tag; prepare newly reviewed matching
-server/client recovery versions and state the live mismatch window explicitly.
+Stop when source, settings, ownership, tag, artifact, test, audit, or review
+evidence is missing or inconsistent. Never move or reuse a tag,
+overwrite an npm version, unpublish to hide a failure, or substitute a local
+rebuild. A pre-stage workflow failure may be rerun against the same immutable
+tag. After npm accepts a stage, recovery uses a fresh reviewed version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp",
-  "version": "3.11.1",
+  "version": "3.13.0",
   "description": "Coordinate AI coding agents in shared cubes. Works with Claude Code, Codex, and OpenCode.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,6 +48,7 @@
     "README.md",
     "LICENSE",
     "NOTICE",
+    "THIRD_PARTY_NOTICES.md",
     "SECURITY.md",
     "CONTRIBUTING.md"
   ],
@@ -71,7 +72,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
-    "borgmcp-shared": "0.11.0",
+    "borgmcp-shared": "0.12.2",
     "chalk": "^5.3.0",
     "prompts": "^2.4.2",
     "which": "^4.0.0"

package/src/assimilate-deps.ts

@@ -40,6 +40,7 @@ import {
   resumeLocalBorgServerEnrollment,
   sendBorgServerAttach,
 } from './server-handshake.js';
+import { advanceLocalServerCursor } from './local-server-cursor.js';
 import {
   findIncompleteSiblingAttempt,
   observeSeat,
@@ -483,6 +484,16 @@ export function buildDefaultAssimilateDeps(
             );
           }
         }
+        if (prepared.initialLogCursor) {
+          const binding = {
+            origin: apiUrl,
+            trustIdentity: serverTrustIdentity,
+            cubeId: prepared.cube.id,
+            droneId: prepared.drone.id,
+          };
+          await advanceLocalServerCursor(binding, prepared.initialLogCursor);
+          await advanceLocalServerCursor({ ...binding, purpose: 'stream' }, prepared.initialLogCursor);
+        }
         return {
           cube_id: prepared.cube.id,
           drone_id: prepared.drone.id,

package/src/cli-help.ts

@@ -57,12 +57,15 @@ export function quickstartHelpText(version: string): string {
     `Usage:\n` +
     `  borg quickstart [options]\n\n` +
     `Options:\n` +
-    `  --template ${NEW_CUBE_TEMPLATE_OPTIONS}  Choose the new-cube template without prompting\n` +
+    `  --template <name>                  Choose without prompting:\n` +
+    `                                     ${NEW_CUBE_TEMPLATE_OPTIONS}\n` +
     `  --role <slug>[:<count>]            Fully specify the roster (repeatable)\n` +
     `  --yes, -y                          Accept the displayed plan\n` +
     `  --help, -h                         Show this help\n\n` +
-    `Quickstart requires a running Borg server and never starts one. Rerun the same\n` +
-    `command after a partial failure; existing drones are kept and skipped.\n`
+    `For the current repository, quickstart creates and launches a full roster.\n` +
+    `Use --role to replace that roster with an explicit selection. Quickstart\n` +
+    `requires a running Borg server and never starts one. Rerun the same command\n` +
+    `after a partial failure; existing drones are kept and skipped.\n`
   );
 }
 
@@ -70,10 +73,17 @@ export function cloneHelpText(version: string): string {
   return (
     `borg clone (borgmcp ${version}) — clone a repository and run quickstart\n\n` +
     `Usage:\n` +
-    `  borg clone <repository-url> [directory] [--no-launch]\n\n` +
+    `  borg clone <repository-url> [directory] [options]\n\n` +
     `Options:\n` +
-    `  --no-launch  Stop after the checkout is ready; do not create or launch a cube\n` +
-    `  --help, -h   Show this help\n\n` +
+    `  --template <name>                  Choose without prompting:\n` +
+    `                                     ${NEW_CUBE_TEMPLATE_OPTIONS}\n` +
+    `  --role <slug>[:<count>]            Fully specify the roster (repeatable)\n` +
+    `  --yes, -y                          Accept the displayed plan\n` +
+    `  --checkout-only                    Stop after the checkout is ready\n` +
+    `  --no-launch                        Same as --checkout-only\n` +
+    `  --help, -h                         Show this help\n\n` +
+    `Clone checks out a new repository, then delegates the complete setup directly to\n` +
+    `quickstart. Non-interactive full setup requires both --yes and --template.\n` +
     `A repeated command reuses a checkout only when its origin matches. Default\n` +
     `destination names avoid non-repository collisions. Credential-bearing URLs are\n` +
     `refused; use a Git credential helper or SSH configuration instead.\n`
@@ -162,7 +172,7 @@ export function topLevelHelpText(version: string): string {
     `  borg doctor              Check agent hook commands, versions, configs, and the OpenCode plugin\n` +
     `  borg clone <url> [dir]   Clone a repository, then create and launch its cube\n` +
     `  borg quickstart          Create a cube and a drone for every role, then launch them\n` +
-    `  borg assimilate [role]   Join or create a cube\n` +
+    `  borg assimilate [role]   Join or create a cube with one drone under one role\n` +
     `  borg assimilate --host <host>   Join or create on an explicit server\n` +
     `  borg assimilate --worktree <name>   Spawn a worktree drone (in ~/.borg/worktrees/<repo>/<name>)\n` +
     `  borg server cube init    Initialize this repository's cube without creating a drone\n` +
@@ -280,6 +290,8 @@ export function assimilateHelpText(version: string): string {
     `  --cli claude|codex|opencode         Agent CLI to launch\n` +
     `  --model claude:<model>   Legacy Claude model override (configure models in the agent CLI)\n` +
     `  --yes, -y                  Accept new-cube defaults; never adopt by name\n\n` +
+    `Assimilate adds or resumes one drone under one role; use quickstart when you want\n` +
+    `the repository's full roster.\n` +
     `Creation shows repository context, name, template, and one confirmation. An existing\n` +
     `repository association skips all prompts. One accessible exact-name legacy cube requires\n` +
     `explicit interactive adoption; ambiguous matches fail closed. An enrolled owner client may\n` +

package/src/clone-cmd.ts

@@ -4,7 +4,12 @@ import { basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { hasCloneCredentials, redactCloneSecrets } from './clone-security.js';
 import type { CloneArgs } from './parse-clone-args.js';
-import { buildDefaultQuickstartDeps, runQuickstart } from './quickstart-cmd.js';
+import type { QuickstartArgs } from './parse-quickstart-args.js';
+import {
+  buildDefaultQuickstartDeps,
+  runQuickstart,
+  type QuickstartRunOptions,
+} from './quickstart-cmd.js';
 import { shellEscape } from './shell-escape.js';
 
 export interface GitRunResult {
@@ -22,7 +27,8 @@ export interface CloneDeps {
   readDirectory: (path: string) => string[];
   createDirectory: (path: string) => boolean;
   removeTree: (path: string) => void;
-  quickstart: (cwd: string) => Promise<number>;
+  isTTY: () => boolean;
+  quickstart: (cwd: string, args: QuickstartArgs, options: QuickstartRunOptions) => Promise<number>;
   stdout: (text: string) => void;
   stderr: (text: string) => void;
 }
@@ -61,9 +67,10 @@ export function buildDefaultCloneDeps(): CloneDeps {
       }
     },
     removeTree: (path) => rmSync(path, { recursive: true, force: true }),
-    quickstart: async (cwd) => {
+    isTTY: () => process.stdin.isTTY === true,
+    quickstart: async (cwd, args, options) => {
       process.chdir(cwd);
-      return runQuickstart({ roles: [], yes: false }, buildDefaultQuickstartDeps());
+      return runQuickstart(args, buildDefaultQuickstartDeps(), options);
     },
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text),
@@ -177,6 +184,13 @@ export async function runClone(args: CloneArgs, rawDeps: CloneDeps): Promise<num
     deps.stderr(`borg clone: ${valid.error}.\n`);
     return 1;
   }
+  if (!args.checkoutOnly && !deps.isTTY() && (!args.yes || !args.template)) {
+    deps.stderr(
+      'borg clone: non-interactive full setup requires both --yes and --template; ' +
+      'use --checkout-only to clone without setup.\n',
+    );
+    return 1;
+  }
   const selected = chooseDestination(deps, args);
   if ('error' in selected) {
     deps.stderr(`borg clone: ${selected.error}.\n`);
@@ -224,7 +238,7 @@ export async function runClone(args: CloneArgs, rawDeps: CloneDeps): Promise<num
     deps.stdout(`Cloned ${sourceName(args.repositoryUrl)} into ${destination}.\n`);
   }
 
-  if (args.noLaunch) {
+  if (args.checkoutOnly) {
     deps.stdout(
       `Checkout ready at ${destination}. No cube or drone was created.\n` +
       `Next: cd ${shellEscape(destination)} && borg quickstart\n`,
@@ -232,8 +246,23 @@ export async function runClone(args: CloneArgs, rawDeps: CloneDeps): Promise<num
     return 0;
   }
   deps.chdir(destination);
-  const code = await deps.quickstart(destination);
-  if (code !== 0) {
+  const quickstartArgs: QuickstartArgs = {
+    ...(args.template === undefined ? {} : { template: args.template }),
+    roles: args.roles,
+    yes: args.yes,
+  };
+  let cancelled = false;
+  const code = await deps.quickstart(destination, quickstartArgs, {
+    onCancelled: (kind) => {
+      cancelled = true;
+      const message =
+        `${kind === 'interrupted' ? '\n' : ''}borg clone: cancelled. Checkout remains at ${destination}.\n` +
+        `Resume: cd ${shellEscape(destination)} && borg quickstart\n`;
+      if (kind === 'interrupted') deps.stderr(message);
+      else deps.stdout(message);
+    },
+  });
+  if (code !== 0 && !cancelled) {
     deps.stderr(
       `The checkout${cloned ? '' : ' you already had'} is ready at ${destination}, but quickstart did not finish. ` +
       `It was left untouched; cd there and run \`borg quickstart\` again.\n`,