@cordfuse/crosstalk 7.0.0-alpha.5 → 7.0.0-alpha.6

package/README.md

@@ -19,16 +19,14 @@ Requires: Node.js ≥ 20 + Docker on PATH + git on PATH. Works on Linux, macOS,
 ## Quickstart
 
 ```sh
-# 1. Scaffold a transport.
-crosstalk init mytransport
-cd mytransport
+# 1. Scaffold a transport. Runtime-owned at <base>/crosstalk/transport/.
+crosstalk init
 
-# 2. Bring up the engine container for this transport.
+# 2. Bring up the engine container.
 crosstalk up
-#    Generates docker-compose.yml in the transport root and runs
-#    `docker compose up -d` for ghcr.io/cordfuse/crosstalk-server:<latest>.
-#    Bind-mounts $PWD as the transport — any `git remote add` from the
-#    host is immediately visible to the engine.
+#    Generates <base>/crosstalk/docker-compose.yml and runs `docker
+#    compose up -d` for ghcr.io/cordfuse/crosstalk-server:<latest>.
+#    No cwd magic — works from any directory.
 
 # 3. Install an agent CLI inside the container, then authenticate.
 crosstalk chat --shell
@@ -36,8 +34,8 @@ crosstalk chat --shell
   exit
 crosstalk chat --agent claude --login
 #    Auth URL opens in your default browser via xdg-open / open / start.
-#    Operator never has to copy-paste it. Token saved in the /crosstalk-root
-#    volume so subsequent dispatched workers reuse it.
+#    Token saved in the /crosstalk-root volume so subsequent dispatched
+#    workers reuse it.
 
 # 4. Send your first message.
 crosstalk channel general
@@ -49,16 +47,19 @@ crosstalk replies <relPath printed by step above>
 
 ## Subcommand surface
 
+Every name-resolved verb takes an optional `--containername <name>` (or `-c <name>`) flag. Bare verb = default container (literally named `crosstalk`).
+
 | Group | Subcommand | What it does |
 |---|---|---|
 | Meta | `crosstalk version` | Print client + engine versions (warns on skew) |
-| Protocol | `crosstalk init <dir>` | Scaffold a transport + `git init` |
+| Protocol | `crosstalk init [-c <name>] [--remote <url>]` | Scaffold a transport at `<base>/<name>/transport/` |
 | Protocol | `crosstalk run --type primitive\|workflow ...` | Dispatch a primitive or workflow |
 | Protocol | `crosstalk replies <relPath>...` | Poll reply status |
-| Protocol | `crosstalk status` | Engine heartbeat, claimed models, channels |
+| Protocol | `crosstalk status` | Container name, transport host path, engine state, channels |
 | Protocol | `crosstalk channel <name> [--rename\|--delete]` | Channel operations |
-| Lifecycle | `crosstalk up` | Generate docker-compose, start engine container |
-| Lifecycle | `crosstalk down [--volumes]` | Stop the engine container |
+| Lifecycle | `crosstalk up` | Generate docker-compose, start the engine container |
+| Lifecycle | `crosstalk down` | Stop the engine container (keep storage) |
+| Lifecycle | `crosstalk rm [--force]` | Remove container AND wipe storage (cannot undo) |
 | Lifecycle | `crosstalk restart` | Down + up |
 | Lifecycle | `crosstalk pull` | Refresh the engine image |
 | Lifecycle | `crosstalk logs [-f]` | Stream the engine container's logs |
@@ -72,10 +73,14 @@ crosstalk replies <relPath printed by step above>
 
 ## What lives where
 
-- **Host** — `crosstalk` binary on PATH, `~/path/to/mytransport/` (the operator's transport directory, bind-mounted).
-- **Container** (`crosstalk-server`, image `ghcr.io/cordfuse/crosstalk-server`) — `crosstalkd` daemon, dispatch state bind-mounted at `<base>/<transport>/crosstalk-state:/var/lib/crosstalk-state`, operator-installed agent CLIs + auth tokens bind-mounted at `<base>/<transport>/crosstalk-root:/crosstalk-root`. `<base>` is per-OS (`$XDG_DATA_HOME/crosstalk` on Linux, `~/Library/Application Support/crosstalk` on macOS, `%LOCALAPPDATA%\crosstalk` on Windows); `CROSSTALK_STORAGE_MODE=system` switches to `/var/lib`-style paths instead.
-- **Engine HTTP API** — `127.0.0.1:7000` (compose `127.0.0.1:HOST:CONTAINER` port mapping is the actual security boundary; engine binds 0.0.0.0 inside the container).
-- **Transport bind-mount** — `$PWD:/var/lib/crosstalk-transport`. Operator git commands on the host are seen by the engine immediately.
+- **Host** — `crosstalk` binary on PATH. Per-transport storage at `<base>/<name>/` (one tree per container).
+- **Container** (literally named whatever the operator picked at `init`, default `crosstalk`; image `ghcr.io/cordfuse/crosstalk-server`) — `crosstalkd` daemon, bind-mounted from:
+  - `<base>/<name>/transport/` → `/var/lib/crosstalk-transport` (runtime-owned git repo)
+  - `<base>/<name>/crosstalk-root/` → `/crosstalk-root` (operator CLIs + auth)
+  - `<base>/<name>/crosstalk-state/` → `/var/lib/crosstalk-state` (cursor + heartbeat)
+- **`<base>`** is per-OS user-mode: `$XDG_DATA_HOME/crosstalk` on Linux, `~/Library/Application Support/crosstalk` on macOS, `%LOCALAPPDATA%\crosstalk` on Windows. `CROSSTALK_STORAGE_MODE=system` switches to `/var/lib`-style paths.
+- **Engine HTTP API** — `127.0.0.1:<port>`. Default container = port 7000; named containers allocate at init from 7001 upward, recorded in `<base>/<name>/api-port`.
+- **Container identification** — every crosstalkd container gets the Docker label `crosstalk.transport=true`. The client uses the label for inventory queries, not name-pattern matching.
 
 ---
 

package/bin/crosstalk.js

@@ -30,6 +30,7 @@ const SUBCOMMANDS = {
   init:    'init.js',
   up:      'up.js',
   down:    'down.js',
+  rm:      'rm.js',
   restart: 'restart.js',
   pull:    'pull.js',
   logs:    'logs.js',

package/commands/channel.js

@@ -4,7 +4,7 @@
 // endpoints that haven't been added to the engine yet; they land
 // when the engine gains them.
 
-import { api } from '../lib/api-client.js';
+import { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
 import { positionals, has, flag } from '../lib/argv.js';
 
@@ -25,7 +25,8 @@ function usage(exit = 0) {
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const pos = positionals(argv, ['--rename']);
+  const api = apiFor(argv);
+  const pos = positionals(argv, ['--rename', '--containername', '-c']);
   if (pos.length === 0) usage(1);
 
   // `crosstalk channel list` → list channels

package/commands/chat.js

@@ -23,8 +23,8 @@
 //   fallback, not the primary mechanism.
 
 import { spawn, spawnSync } from 'child_process';
-import { requireTransportRoot, containerName } from '../lib/transport.js';
-import { api, ConnectError } from '../lib/api-client.js';
+import { requireInitialized } from '../lib/resolve.js';
+import { apiFor, ConnectError } from '../lib/api-client.js';
 import { flag, has } from '../lib/argv.js';
 
 const KNOWN_AGENTS = ['claude', 'codex', 'gemini', 'qwen', 'opencode', 'agy'];
@@ -195,8 +195,8 @@ function runLogin(container, agent) {
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const root = requireTransportRoot();
-  const name = containerName(root);
+  const { name } = requireInitialized(argv);
+  const api = apiFor(argv);
 
   if (has(argv, '--shell')) {
     return runInteractive(name, 'bash');

package/commands/down.js

@@ -1,18 +1,22 @@
-// crosstalk down — stop the engine container for this transport.
+// crosstalk down — stop a transport's container, keep storage.
+//
+// alpha.6: name-resolved. --volumes flag retires (no named volumes in
+// the bind-mount model). Reversible — next `up` resumes against the
+// preserved <base>/<name>/ storage.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized, DEFAULT_CONTAINER_NAME } from '../lib/resolve.js';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
-`Usage: crosstalk down [--volumes]
+`Usage: crosstalk down [--containername <name>]
 
-Stops the engine container for the transport in the current directory.
-With --volumes, also removes the persistent volumes (clears operator-
-installed CLIs + auth state; you'll have to re-install + re-auth).
+Stops the engine container for a transport. Storage at <base>/<name>/
+is preserved — next 'crosstalk up' resumes against it. Use
+'crosstalk rm' if you want to wipe storage as well.
 `,
   );
   process.exit(exit);
@@ -21,17 +25,16 @@ installed CLIs + auth state; you'll have to re-install + re-auth).
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk down: no docker-compose.yml at ${composeYml}\n`);
-    process.stderr.write(`  (this transport was probably never brought up — nothing to do)\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(
+      `crosstalk down: '${name}' has no compose file (never brought up). Nothing to do.\n`,
+    );
     return 0;
   }
 
-  const args = ['compose', '-f', composeYml, 'down'];
-  if (has(argv, '--volumes')) args.push('--volumes');
-
-  const r = spawnSync('docker', args, { cwd: root, stdio: 'inherit' });
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'down'], {
+    stdio: 'inherit',
+  });
   return r.status ?? 1;
 }

package/commands/init.js

@@ -1,42 +1,70 @@
-// crosstalk init <dir> — scaffold a new transport via docker.
+// crosstalk init — scaffold a transport into <base>/<name>/.
 //
-// Doesn't go through the engine HTTP API — there's no running engine
-// at init time. Instead, runs the engine in a one-shot container with
-// a bind-mount of the target directory, and lets crosstalkd's init
-// subcommand write the template files directly.
+// alpha.6: runtime owns the transport. Operator no longer creates a
+// `transport/` dir on their host filesystem; init creates it at
+// <base>/<name>/transport/ where <base> is per-OS user-mode (or
+// system-mode via CROSSTALK_STORAGE_MODE=system).
 //
-//   docker run --rm \
-//     -v "$(realpath <dir>):/init-target" \
-//     --user "$(id -u):$(id -g)" \
-//     <image> \
-//     crosstalkd init /init-target
+// Operator's interaction surface:
+//   crosstalk init                            # default container 'crosstalk'
+//   crosstalk init --containername uat        # named container 'uat'
+//   crosstalk init --remote git@example:t.git # set upstream at init time
 //
-// The --user flag is critical: without it, the template files would
-// land owned by root (the container's user). Setting it to the
-// operator's UID/GID keeps file ownership sane.
+// Mechanics:
+//   1. Resolve <base>/<name>/ and pre-create the bind-mount subdirs
+//      (transport/, crosstalk-root/, crosstalk-state/).
+//   2. Run `crosstalkd init /init-target` in a one-shot container,
+//      bind-mounting transport/ as /init-target. The engine writes its
+//      template (CROSSTALK-VERSION, PROTOCOL.md, CROSSTALK.md, data/,
+//      local/) into the bind-mount.
+//   3. `git init` inside transport/ + initial commit.
+//   4. If --remote: `git remote add origin <url>`.
+//   5. Pick a free API port (default container always 7000; named
+//      containers search from 7001) and write to <base>/<name>/api-port.
 
-import { mkdirSync, existsSync } from 'fs';
-import { resolve } from 'path';
+import { mkdirSync, existsSync, writeFileSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { has, positionals } from '../lib/argv.js';
+import { has, flag } from '../lib/argv.js';
+import {
+  parseContainerName,
+  storagePaths,
+  isInitialized,
+  pickFreePort,
+  DEFAULT_CONTAINER_NAME,
+} from '../lib/resolve.js';
 
 const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
-  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.5';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.6';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
 `Usage:
-  crosstalk init <dir>        # scaffold a new transport at <dir>
+  crosstalk init [--containername <name>] [--remote <url>]
 
-  Image:  ${DEFAULT_IMAGE}
-  Override:  CROSSTALK_IMAGE=<image-tag> crosstalk init <dir>
+Creates a new transport on this machine. The transport git repo lives at
+<base>/<name>/transport/ where <base> is:
+  Linux:   $XDG_DATA_HOME/crosstalk/   (or ~/.local/share/crosstalk/)
+  macOS:   ~/Library/Application Support/crosstalk/
+  Windows: %LOCALAPPDATA%\\crosstalk\\
 
-  The image must be pullable (or already present locally). For local dev
-  before the GHCR publish pipeline ships, build the image first:
-    docker build -t crosstalk-server:7.0.0-alpha.5 -f server/Dockerfile .
-  Then run:
-    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.5 crosstalk init mytransport
+Set CROSSTALK_STORAGE_MODE=system to use the system-wide path (sudo/UAC
+required; intended for headless multi-operator hosts).
+
+Options:
+  --containername <name>   Container name (default: 'crosstalk'). Must be
+                           lowercase alphanumeric + ._- (no leading . or -).
+                           One default + N named containers per machine.
+  --remote <url>           Set git upstream at init time. Engine's first
+                           tick will fetch + rebase against this remote.
+  --image <tag>            Override the engine image (default: bundled
+                           GHCR tag; or CROSSTALK_IMAGE env).
+  -c <name>                Shorthand for --containername.
+
+Examples:
+  crosstalk init                                   # default container
+  crosstalk init --containername uat               # second container
+  crosstalk init --remote git\\@github.com:me/t.git # with upstream
 `,
   );
   process.exit(exit);
@@ -44,62 +72,124 @@ function usage(exit = 0) {
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
-  const pos = positionals(argv, []);
-  if (pos.length === 0) usage(1);
 
-  const target = resolve(pos[0]);
-  if (!existsSync(target)) mkdirSync(target, { recursive: true });
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk init: ${err.message}\n`);
+    return 1;
+  }
+
+  if (isInitialized(name)) {
+    const paths = storagePaths(name);
+    process.stderr.write(
+      `crosstalk init: transport '${name}' already initialized at ${paths.transportDir}.\n` +
+      `  Run 'crosstalk up${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to start it,\n` +
+      `  or 'crosstalk rm${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to wipe it first.\n`,
+    );
+    return 1;
+  }
+
+  const remote = flag(argv, '--remote');
+  const image = flag(argv, '--image') ?? DEFAULT_IMAGE;
+  const paths = storagePaths(name);
+
+  // Pre-create the storage tree. Docker would auto-create the bind-mount
+  // dirs root-owned otherwise, breaking the entrypoint's chown step.
+  try {
+    mkdirSync(paths.transportDir,   { recursive: true });
+    mkdirSync(paths.crosstalkRoot,  { recursive: true });
+    mkdirSync(paths.crosstalkState, { recursive: true });
+  } catch (err) {
+    process.stderr.write(
+      `crosstalk init: failed to create storage at ${paths.storageRoot} — ${err.message}\n`,
+    );
+    if (paths.mode === 'system') {
+      process.stderr.write(
+        `  System-mode storage requires write access to ${paths.base}.\n` +
+        `  Try: sudo mkdir -p ${paths.storageRoot} && sudo chown -R $USER ${paths.storageRoot}\n`,
+      );
+    }
+    return 1;
+  }
 
-  // Resolve uid/gid via process.getuid() — POSIX only. On Windows the
-  // --user flag is omitted; Docker Desktop handles ownership differently.
+  // Engine-side template scaffolding: run crosstalkd init in a one-shot
+  // container, bind-mounting our transport/ as /init-target. --user maps
+  // ownership to operator UID so the written files are operator-owned.
   const uid = typeof process.getuid === 'function' ? process.getuid() : null;
   const gid = typeof process.getgid === 'function' ? process.getgid() : null;
   const userArgs = (uid != null && gid != null) ? ['--user', `${uid}:${gid}`] : [];
 
-  // --entrypoint crosstalkd overrides the image's default ENTRYPOINT
-  // (which is the dispatcher entrypoint.sh requiring TRANSPORT_GIT_URL).
-  // For init we want to call crosstalkd directly with no env requirements.
-  const args = [
+  const dockerArgs = [
     'run', '--rm',
-    '-v', `${target}:/init-target`,
+    '-v', `${paths.transportDir}:/init-target`,
     ...userArgs,
     '--entrypoint', 'crosstalkd',
-    DEFAULT_IMAGE,
+    image,
     'init', '/init-target',
   ];
 
-  const r = spawnSync('docker', args, { stdio: 'inherit' });
-  if (r.status !== 0) {
-    process.stderr.write(`crosstalk init: docker run exited ${r.status}\n`);
-    process.stderr.write(`  command was: docker ${args.join(' ')}\n`);
-    return r.status ?? 1;
+  const initRun = spawnSync('docker', dockerArgs, { stdio: 'inherit' });
+  if (initRun.status !== 0) {
+    process.stderr.write(`crosstalk init: docker run exited ${initRun.status}\n`);
+    process.stderr.write(`  command was: docker ${dockerArgs.join(' ')}\n`);
+    return initRun.status ?? 1;
   }
 
-  // Auto git init + initial commit so the transport is ready for
-  // `crosstalk up` immediately. Engine expects a git repo (cursor +
-  // commit operations on every tick). Doing this on the host so the
-  // commit author uses the operator's local git config — not the
-  // container's default.
-  //
-  // Best-effort: if any git step fails, print a warning but don't fail
-  // the init (operator can complete the steps manually).
+  // Auto git init + initial commit. Doing it on the host so the commit
+  // author uses the operator's local git config — not the container's.
   const gitSteps = [
     ['init', '--quiet', '--initial-branch=main'],
     ['add', '-A'],
     ['commit', '--quiet', '-m', 'initial transport'],
   ];
   for (const args of gitSteps) {
-    const gr = spawnSync('git', args, { cwd: target, stdio: 'pipe' });
+    const gr = spawnSync('git', args, { cwd: paths.transportDir, stdio: 'pipe' });
     if (gr.status !== 0) {
       const stderr = gr.stderr?.toString().trim() ?? '';
       process.stderr.write(
-        `crosstalk init: \`git ${args.join(' ')}\` failed (transport scaffolded but not committed)\n`,
+        `crosstalk init: 'git ${args.join(' ')}' failed — ${stderr}\n` +
+        `  Storage was scaffolded but not committed. Finish manually at:\n` +
+        `    ${paths.transportDir}\n`,
+      );
+      // Not fatal — storage exists and engine will tolerate uncommitted state
+      break;
+    }
+  }
+
+  // Set up the upstream if requested. Failures here aren't fatal —
+  // operator can retry with `cd <transport-dir> && git remote add`.
+  if (remote) {
+    const rr = spawnSync('git', ['remote', 'add', 'origin', remote], {
+      cwd: paths.transportDir,
+      stdio: 'pipe',
+    });
+    if (rr.status !== 0) {
+      process.stderr.write(
+        `crosstalk init: 'git remote add origin ${remote}' failed — ${rr.stderr?.toString().trim()}\n`,
       );
-      if (stderr) process.stderr.write(`  ${stderr.split('\n').join('\n  ')}\n`);
-      process.stderr.write(`  Finish manually: cd ${target} && git init && git add -A && git commit -m "initial transport"\n`);
-      return 0;  // not fatal — scaffold succeeded
     }
   }
-  process.stdout.write(`\nGit initialized; transport is ready for \`crosstalk up\`.\n`);
+
+  // Allocate an API port and persist it for the resolver.
+  let port;
+  try {
+    port = pickFreePort(name);
+    writeFileSync(paths.portFile, `${port}\n`);
+  } catch (err) {
+    process.stderr.write(`crosstalk init: port allocation failed — ${err.message}\n`);
+    return 1;
+  }
+
+  process.stdout.write(
+    `\nTransport '${name}' initialized:\n` +
+    `  storage:    ${paths.storageRoot}\n` +
+    `  transport:  ${paths.transportDir}\n` +
+    `  image:      ${image}\n` +
+    `  api port:   ${port}\n` +
+    (remote ? `  remote:     ${remote}\n` : '') +
+    `\nNext: crosstalk up${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}\n`,
+  );
   return 0;
 }

package/commands/logs.js

@@ -1,14 +1,14 @@
-// crosstalk logs — tail the engine container's logs.
+// crosstalk logs — tail a transport's engine logs.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
-`Usage: crosstalk logs [-f|--follow] [-n <lines>]
+`Usage: crosstalk logs [--containername <name>] [-f|--follow] [-n <lines>]
 
 Streams the engine container's stdout/stderr. -f to follow (Ctrl-C to stop).
 `,
@@ -19,21 +19,19 @@ Streams the engine container's stdout/stderr. -f to follow (Ctrl-C to stop).
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk logs: no docker-compose.yml — run 'crosstalk up' first.\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk logs: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const args = ['compose', '-f', composeYml, 'logs'];
+  const args = ['compose', '-f', paths.composeFile, 'logs'];
   if (has(argv, '-f') || has(argv, '--follow')) args.push('--follow');
-  // Pass through tail count if provided.
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '-n' || argv[i] === '--tail') {
       args.push('--tail', argv[i + 1] ?? '100');
       i++;
     }
   }
-  const r = spawnSync('docker', args, { cwd: root, stdio: 'inherit' });
+  const r = spawnSync('docker', args, { stdio: 'inherit' });
   return r.status ?? 1;
 }

package/commands/pull.js

@@ -1,23 +1,21 @@
-// crosstalk pull — refresh the engine image.
+// crosstalk pull — refresh the engine image for a transport.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) {
-    process.stdout.write('Usage: crosstalk pull\n');
+    process.stdout.write('Usage: crosstalk pull [--containername <name>]\n');
     return 0;
   }
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk pull: no docker-compose.yml — run 'crosstalk up' first.\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk pull: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const r = spawnSync('docker', ['compose', '-f', composeYml, 'pull'], {
-    cwd: root,
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'pull'], {
     stdio: 'inherit',
   });
   return r.status ?? 1;

package/commands/replies.js

@@ -3,19 +3,20 @@
 // Exit 0 if all targets have REPLIED or FAILED, exit 2 while any PENDING
 // — agents can poll cheaply in a loop. Mirrors crosstalkd replies.
 
-import { api } from '../lib/api-client.js';
+import { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
 import { positionals, has } from '../lib/argv.js';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
-  w.write('Usage: crosstalk replies <relPath> [<relPath>...]\n');
+  w.write('Usage: crosstalk replies [--containername <name>] <relPath> [<relPath>...]\n');
   process.exit(exit);
 }
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
-  const targets = positionals(argv, []);
+  const api = apiFor(argv);
+  const targets = positionals(argv, ['--containername', '-c']);
   if (targets.length === 0) usage(1);
 
   let resp;

package/commands/restart.js

@@ -1,23 +1,21 @@
-// crosstalk restart — restart the engine container.
+// crosstalk restart — restart a transport's engine container.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { requireTransportRoot, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import { requireInitialized } from '../lib/resolve.js';
 
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) {
-    process.stdout.write('Usage: crosstalk restart\n');
+    process.stdout.write('Usage: crosstalk restart [--containername <name>]\n');
     return 0;
   }
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  if (!existsSync(composeYml)) {
-    process.stderr.write(`crosstalk restart: no docker-compose.yml — run 'crosstalk up' first.\n`);
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(`crosstalk restart: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const r = spawnSync('docker', ['compose', '-f', composeYml, 'restart'], {
-    cwd: root,
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'restart'], {
     stdio: 'inherit',
   });
   return r.status ?? 1;