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

package/commands/up.js

@@ -1,140 +1,76 @@
-// crosstalk up — bring up the engine container for this transport.
+// crosstalk up — bring up the engine container for a transport.
 //
-// First-time use: generates docker-compose.yml in the transport root from
-// a template (operator can edit freely, subsequent `up`s won't clobber).
-// The compose file bind-mounts the transport root as the engine's working
-// tree so git operations work both ways — engine sees operator's local
-// commits and configured remotes immediately, operator sees engine
-// commits (replies, cursor advances) immediately.
+// alpha.6: no cwd magic. Resolves container by --containername flag
+// (default 'crosstalk') and operates against <base>/<name>/.
 //
-// Subsequent runs: just shell out to `docker compose up -d`.
+// Three lifecycle cases:
+//   1. Container already running → error (use chat/restart instead).
+//   2. Storage exists, no container → resume; print one-line notice.
+//   3. Storage doesn't exist → error pointing to `crosstalk init`.
+//
+// First-time up generates <base>/<name>/docker-compose.yml from a template.
+// Subsequent ups respect operator edits — only regenerate if missing.
 
-import { writeFileSync, existsSync, mkdirSync, appendFileSync, readFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { join } from 'path';
-import { homedir } from 'os';
-import { requireTransportRoot, transportName, composeFile } from '../lib/transport.js';
 import { has } from '../lib/argv.js';
+import {
+  requireInitialized,
+  isRunning,
+  containerExists,
+  apiPortFor,
+  DEFAULT_CONTAINER_NAME,
+  CROSSTALK_LABEL,
+} from '../lib/resolve.js';
 
 const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
-  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.5';
-const DEFAULT_API_PORT = Number(process.env.CROSSTALK_API_PORT) || 7000;
-const STORAGE_MODE = (process.env.CROSSTALK_STORAGE_MODE ?? 'user').toLowerCase();
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.7';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
   w.write(
-`Usage: crosstalk up
+`Usage: crosstalk up [--containername <name>]
+
+Starts the engine container for a transport that has already been
+'crosstalk init'd. Default container is 'crosstalk'; pass --containername
+to address a named one.
 
-Brings up the engine container for the transport in the current directory
-(or any ancestor containing CROSSTALK-VERSION). First-time use generates
-docker-compose.yml in the transport root.
+If the storage at <base>/<name>/ already exists (operator previously
+brought it up then 'crosstalk down'd it), the container resumes against
+that state — installed agent CLIs, OAuth tokens, dispatcher cursor all
+carry over.
 
 Environment:
-  CROSSTALK_IMAGE         Image to pin (default: bundled GHCR tag)
-  CROSSTALK_API_PORT      Host port to map (default: 7000)
-  CROSSTALK_ALIAS         Dispatcher's machine identity in the bus
-  CROSSTALK_STORAGE_MODE  user (default) | system
-                          Where bind-mounted crosstalk-root +
-                          crosstalk-state live on the host. 'system'
-                          uses paths under /var/lib (Linux) / /Library
-                          (macOS) / C:\\ProgramData (Windows) — requires
-                          sudo/UAC and (on macOS) Docker Desktop file-
-                          sharing allowlist. 'user' uses paths under
-                          the operator's home directory with no
-                          escalation.
+  CROSSTALK_IMAGE         Override the engine image
+  CROSSTALK_ALIAS         Override the engine's machine identity
+                          (defaults to the container name)
 `,
   );
   process.exit(exit);
 }
 
-// Resolve the host directories that back the container's /crosstalk-root
-// (operator-installed CLIs + auth) and /var/lib/crosstalk-state
-// (dispatcher state) bind mounts.
-//
-// User-mode (default) keeps everything under the operator's home so no
-// sudo / UAC / Docker Desktop file-sharing allowlist gymnastics are
-// needed. System-mode is for headless production-style deployments
-// where multiple operators share a machine and a service user manages
-// the daemon.
-//
-// Host-side dir names use the same `crosstalk-` prefix as the container
-// paths so things stay identifiable wherever they surface (backup tools,
-// file managers, support-email screenshots).
-function resolveStoragePaths(transportName, mode) {
-  const platform = process.platform;
-  // Per-OS base directories.
-  const bases = (platform === 'darwin')
-    ? {
-        user:   join(homedir(), 'Library', 'Application Support', 'crosstalk'),
-        system: '/Library/Application Support/crosstalk',
-      }
-    : (platform === 'win32')
-    ? {
-        // %LOCALAPPDATA% should always be set on supported Win versions;
-        // fall back to ~/AppData/Local if it isn't.
-        user:   process.env['LOCALAPPDATA']
-                  ? join(process.env['LOCALAPPDATA'], 'crosstalk')
-                  : join(homedir(), 'AppData', 'Local', 'crosstalk'),
-        system: 'C:\\ProgramData\\crosstalk',
-      }
-    : /* linux + other unix */ {
-        // Honor XDG_DATA_HOME silently (no docs surface; the 99% of
-        // operators who haven't set it get ~/.local/share/crosstalk
-        // either way).
-        user:   join(process.env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share'), 'crosstalk'),
-        system: '/var/lib/crosstalk',
-      };
-
-  if (mode !== 'user' && mode !== 'system') {
-    throw new Error(
-      `crosstalk up: CROSSTALK_STORAGE_MODE='${mode}' invalid — must be 'user' or 'system'.`,
-    );
-  }
-  const base = bases[mode];
-  const transportRoot = join(base, transportName);
-  return {
-    crosstalkRoot:  join(transportRoot, 'crosstalk-root'),
-    crosstalkState: join(transportRoot, 'crosstalk-state'),
-    mode,
-  };
-}
-
-function renderCompose({ name, image, apiPort, alias, uid, gid, crosstalkRootHost, crosstalkStateHost, storageMode }) {
-  // Entrypoint runs as root for setup (npm prefix, SSH key import). It
-  // then adjusts a 'crosstalkd' user to match CROSSTALK_UID/GID
-  // (operator's host UID), chowns the bind-mounted transport, state
-  // dir, AND /crosstalk-root to that user, then drops via setpriv before
-  // exec'ing the dispatcher. Net effect: bind-mount files written by
-  // the engine are operator-owned on the host, so \`git remote add\`
-  // and \`rm -rf\` from the host both work without sudo.
-  return `# Generated by \`crosstalk up\`. Safe to edit; subsequent \`up\`s
-# only regenerate when this file is missing. Compose config is machine-
-# local — kept out of git via .gitignore by default.
-#
-# Storage mode: ${storageMode}
-# crosstalk-root  (container /crosstalk-root)              → ${crosstalkRootHost}
-# crosstalk-state (container /var/lib/crosstalk-state)     → ${crosstalkStateHost}
-# transport       (container /var/lib/crosstalk-transport) → \${PWD} (bind to this directory)
+function renderCompose({ name, image, apiPort, alias, uid, gid, paths }) {
+  return `# Generated by 'crosstalk up'. Machine-local — runtime-owned.
+# Storage mode: ${paths.mode}
+# transport       (container /var/lib/crosstalk-transport) → ${paths.transportDir}
+# crosstalk-root  (container /crosstalk-root)              → ${paths.crosstalkRoot}
+# crosstalk-state (container /var/lib/crosstalk-state)     → ${paths.crosstalkState}
 
 services:
   crosstalkd:
     image: ${image}
-    container_name: crosstalk-${name}
+    container_name: ${name}
     restart: unless-stopped
+    labels:
+      ${CROSSTALK_LABEL.replace('=', ': "')}"
     ports:
       - "127.0.0.1:${apiPort}:7000"
     volumes:
-      # Transport bind-mount: \`git remote add\` from the host is visible
-      # to the engine on the next tick. No clone-on-startup needed.
-      - .:/var/lib/crosstalk-transport
-      # Operator-installed agent CLIs (claude, codex, agy, ...) + auth
-      # state. Chowned to operator UID at entrypoint so host-side
-      # \`rm -rf\` works without sudo.
-      - ${crosstalkRootHost}:/crosstalk-root
-      # Dispatcher's machine-local state: cursor, heartbeat, errors.log,
-      # pidfile, wake.signal. Operator-UID-owned (chowned by entrypoint).
-      - ${crosstalkStateHost}:/var/lib/crosstalk-state
+      - ${paths.transportDir}:/var/lib/crosstalk-transport
+      - ${paths.crosstalkRoot}:/crosstalk-root
+      - ${paths.crosstalkState}:/var/lib/crosstalk-state
+    env_file:
+      - ${paths.authEnvFile}
     environment:
       CROSSTALK_ALIAS: ${alias}
       CROSSTALK_UID: "${uid}"
@@ -145,73 +81,49 @@ services:
 `;
 }
 
-function ensureGitignored(transportRoot) {
-  const path = join(transportRoot, '.gitignore');
-  const entry = 'docker-compose.yml\n';
-  if (!existsSync(path)) {
-    writeFileSync(path, entry);
-    return;
-  }
-  const current = readFileSync(path, 'utf-8');
-  if (!current.split('\n').includes('docker-compose.yml')) {
-    appendFileSync(path, (current.endsWith('\n') ? '' : '\n') + entry);
-  }
-}
-
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const root = requireTransportRoot();
-  const composeYml = composeFile(root);
-  const generated = !existsSync(composeYml);
+  const { name, paths } = requireInitialized(argv);
+
+  // Case 1: already running → error, don't surprise the operator with
+  // a silent no-op or implicit restart.
+  if (isRunning(name)) {
+    process.stderr.write(
+      `crosstalk up: '${name}' is already running.\n` +
+      `  Use 'crosstalk chat${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to attach,\n` +
+      `  'crosstalk restart${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to recreate,\n` +
+      `  or 'crosstalk down${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' first.\n`,
+    );
+    return 1;
+  }
+
+  // Case "stopped but not removed" — `docker stop` without compose down.
+  // Silently remove the dead container so the recreate works.
+  if (containerExists(name)) {
+    spawnSync('docker', ['rm', '-f', name], { stdio: 'ignore' });
+  }
 
+  // Compose file generation. If operator edited theirs, respect it.
+  const generated = !existsSync(paths.composeFile);
   if (generated) {
-    const alias = process.env.CROSSTALK_ALIAS ?? process.env.HOSTNAME ?? transportName(root);
+    const alias = process.env.CROSSTALK_ALIAS ?? name;
     const uid = typeof process.getuid === 'function' ? process.getuid() : 1000;
     const gid = typeof process.getgid === 'function' ? process.getgid() : 1000;
-    let storage;
-    try {
-      storage = resolveStoragePaths(transportName(root), STORAGE_MODE);
-    } catch (err) {
-      process.stderr.write(`${err.message}\n`);
-      return 1;
-    }
-    // Pre-create the host bind-mount directories. Docker would auto-
-    // create them as root-owned otherwise, which would break the
-    // operator-UID chown step inside the container.
-    try {
-      mkdirSync(storage.crosstalkRoot,  { recursive: true });
-      mkdirSync(storage.crosstalkState, { recursive: true });
-    } catch (err) {
-      process.stderr.write(
-        `crosstalk up: failed to create storage directories — ${err.message}\n`,
-      );
-      if (storage.mode === 'system') {
-        process.stderr.write(
-          `  System-mode storage requires write access to ${storage.crosstalkRoot}'s parent.\n` +
-          `  Try: sudo mkdir -p ${storage.crosstalkRoot} ${storage.crosstalkState} && sudo chown -R \$USER ${storage.crosstalkRoot} ${storage.crosstalkState}\n`,
-        );
-      }
-      return 1;
-    }
-    const content = renderCompose({
-      name: transportName(root),
-      image: DEFAULT_IMAGE,
-      apiPort: DEFAULT_API_PORT,
-      alias,
-      uid,
-      gid,
-      crosstalkRootHost:  storage.crosstalkRoot,
-      crosstalkStateHost: storage.crosstalkState,
-      storageMode: storage.mode,
-    });
-    writeFileSync(composeYml, content);
-    ensureGitignored(root);
-    process.stdout.write(`Generated ${composeYml} (storage: ${storage.mode})\n`);
+    const apiPort = apiPortFor(name);
+    const image = DEFAULT_IMAGE;
+    const content = renderCompose({ name, image, apiPort, alias, uid, gid, paths });
+    writeFileSync(paths.composeFile, content);
+  }
+
+  // Resume notice when storage is non-fresh (operator brought it up
+  // before, has installed CLIs / auth state in crosstalk-root/). Heuristic:
+  // crosstalk-root has more than just a .gitkeep / nothing.
+  if (!generated) {
+    process.stdout.write(`Resuming '${name}' (existing state at ${paths.storageRoot})\n`);
   }
 
-  const r = spawnSync('docker', ['compose', '-f', composeYml, 'up', '-d'], {
-    cwd: root,
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'up', '-d'], {
     stdio: 'inherit',
   });
   if (r.status !== 0) {
@@ -219,7 +131,7 @@ export async function run(argv) {
     return r.status ?? 1;
   }
   process.stdout.write(
-    `\nEngine starting. Check status with 'crosstalk status' (give it ~5s to settle).\n`,
+    `\n'${name}' starting. Check with 'crosstalk status${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' (give it ~5s).\n`,
   );
   return 0;
 }

package/commands/version.js

@@ -7,14 +7,15 @@
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { api, ConnectError } from '../lib/api-client.js';
+import { apiFor, ConnectError } from '../lib/api-client.js';
 
 const thisDir = dirname(fileURLToPath(import.meta.url));
 const pkgPath = join(thisDir, '..', 'package.json');
 const clientPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 
-export async function run(_argv) {
+export async function run(argv) {
   process.stdout.write(`crosstalk client: ${clientPkg.version}\n`);
+  const api = apiFor(argv);
   try {
     // Skew detection happens passively in api-client.js via the
     // X-Crosstalk-Engine-Version response header — no duplication here.

package/lib/api-client.js

@@ -1,26 +1,27 @@
 // api-client.js — HTTP client over loopback to crosstalkd's local API.
 //
 // All operator commands route through this. The engine binds 127.0.0.1
-// inside the container; docker-compose maps that to the host loopback
-// at the same port. Client connects to http://127.0.0.1:<port>/<path>.
+// inside the container; docker-compose maps that to the host loopback.
+// The host port differs per container — default container 'crosstalk'
+// gets 7000; named containers pick a free port at init time, recorded in
+// `<base>/<name>/api-port`. apiPortFor() resolves name → port.
 //
-// Port resolution (in order):
-//   1. --port <n> CLI flag (handled by individual commands)
-//   2. CROSSTALK_API_PORT env var
-//   3. Default 7000
+// Port resolution order:
+//   1. opts.port (explicit override from caller)
+//   2. CROSSTALK_API_PORT env var (test/dev override)
+//   3. apiPortFor(name) — reads `<base>/<name>/api-port` file
+//   4. DEFAULT_API_PORT (7000) as last resort
 //
-// No auth: the engine binds 127.0.0.1 only and there's no token. Same
-// model as ollama / postgres-on-localhost.
+// No auth: engine binds 127.0.0.1 only, no token. Same model as ollama.
 //
-// Version skew: engine sets X-Crosstalk-Engine-Version on every
-// response. We compare it to the client's package.json version on each
-// call and emit one warning per process if they don't match. Pre-1.0
-// client and engine ship in lockstep; mismatches usually mean the
-// operator upgraded one without the other.
+// Version skew: engine sets X-Crosstalk-Engine-Version on every response.
+// We compare to client version on each call, emit one warning per process
+// if mismatched. Pre-1.0 client and engine ship in lockstep.
 
 import { readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { apiPortFor, DEFAULT_API_PORT, parseContainerName } from './resolve.js';
 
 const CLIENT_VERSION = (() => {
   try {
@@ -44,12 +45,13 @@ function checkSkew(engineVersion) {
   );
 }
 
-export const DEFAULT_API_PORT = 7000;
+export { DEFAULT_API_PORT };
 
-export function resolvePort(explicit) {
-  if (typeof explicit === 'number' && Number.isInteger(explicit)) return explicit;
+export function resolvePort(opts = {}) {
+  if (typeof opts.port === 'number' && Number.isInteger(opts.port)) return opts.port;
   const fromEnv = Number(process.env.CROSSTALK_API_PORT);
   if (Number.isInteger(fromEnv) && fromEnv > 0) return fromEnv;
+  if (opts.name) return apiPortFor(opts.name);
   return DEFAULT_API_PORT;
 }
 
@@ -91,7 +93,7 @@ export class ConnectError extends Error {
 }
 
 async function call(method, path, body, opts = {}) {
-  const port = resolvePort(opts.port);
+  const port = resolvePort(opts);
   const init = {
     method,
     headers: body ? { 'Content-Type': 'application/json' } : undefined,
@@ -107,6 +109,30 @@ async function call(method, path, body, opts = {}) {
   return parseJsonOrThrow(res);
 }
 
+// Bind an api client to a specific container name. All callers should
+// either pass argv (auto-resolves name) or an explicit name. Internally
+// each call resolves the port via the name's api-port file. Validation
+// errors print cleanly (no stack trace) — bug C fix.
+export function apiFor(argv) {
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk: ${err.message}\n`);
+    process.exit(1);
+  }
+  return {
+    name,
+    get:    (path, opts = {})        => call('GET',    path, undefined, { ...opts, name }),
+    post:   (path, body, opts = {})  => call('POST',   path, body,      { ...opts, name }),
+    patch:  (path, body, opts = {})  => call('PATCH',  path, body,      { ...opts, name }),
+    delete: (path, opts = {})        => call('DELETE', path, undefined, { ...opts, name }),
+  };
+}
+
+// Legacy entry point — env-driven port (CROSSTALK_API_PORT or 7000),
+// no name resolution. Kept for harness compatibility; new code should
+// use apiFor(argv) instead.
 export const api = {
   get:    (path, opts)        => call('GET',    path, undefined, opts),
   post:   (path, body, opts)  => call('POST',   path, body,       opts),

package/lib/argv.js

@@ -12,13 +12,15 @@ export function has(argv, name) {
   return argv.includes(name);
 }
 
-// All positional (non-flag) args, skipping flag values.
+// All positional (non-flag) args, skipping flag values for the listed
+// flags. Handles both --long and -short forms; flag names in
+// flagsWithValue must match the form they appear in argv.
 export function positionals(argv, flagsWithValue) {
   const valueFlags = new Set(flagsWithValue);
   const out = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a.startsWith('--')) {
+    if (a.startsWith('-')) {
       if (valueFlags.has(a)) i++;
       continue;
     }

package/lib/resolve.js

@@ -0,0 +1,192 @@
+// resolve.js — name-based resolution for the runtime-owned-transport
+// model (alpha.6+).
+//
+// Operator addresses transports by container name, picked at `crosstalk
+// init`. Default container is literally `crosstalk`; named containers
+// are literally whatever the operator typed into --containername.
+// Identity lives with the container; storage lives at <base>/<name>/.
+//
+// Replaces the cwd-walking transport.js from alpha.5 (which derived
+// identity from the operator's filesystem position). The new model is
+// position-independent — operator can be anywhere on disk.
+
+import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export const DEFAULT_CONTAINER_NAME = 'crosstalk';
+export const DEFAULT_API_PORT = 7000;
+export const CROSSTALK_LABEL = 'crosstalk.transport=true';
+
+// Per-OS storage bases. User-mode (default) keeps everything under the
+// operator's home — no sudo/UAC, no Docker Desktop file-sharing allowlist
+// gymnastics. System-mode is for headless multi-operator deployments.
+export function resolveBase(mode) {
+  const platform = process.platform;
+  const bases = (platform === 'darwin')
+    ? {
+        user:   join(homedir(), 'Library', 'Application Support', 'crosstalk'),
+        system: '/Library/Application Support/crosstalk',
+      }
+    : (platform === 'win32')
+    ? {
+        user:   process.env['LOCALAPPDATA']
+                  ? join(process.env['LOCALAPPDATA'], 'crosstalk')
+                  : join(homedir(), 'AppData', 'Local', 'crosstalk'),
+        system: 'C:\\ProgramData\\crosstalk',
+      }
+    : {
+        user:   join(process.env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share'), 'crosstalk'),
+        system: '/var/lib/crosstalk',
+      };
+
+  if (mode !== 'user' && mode !== 'system') {
+    throw new Error(`CROSSTALK_STORAGE_MODE='${mode}' invalid — must be 'user' or 'system'.`);
+  }
+  return bases[mode];
+}
+
+export function storageMode() {
+  return (process.env.CROSSTALK_STORAGE_MODE ?? 'user').toLowerCase();
+}
+
+// All storage paths for a given container name, derived from the resolved
+// base. None of these are validated for existence here — callers check
+// based on context (init pre-creates, up verifies, etc).
+export function storagePaths(name, mode = storageMode()) {
+  const base = resolveBase(mode);
+  const root = join(base, name);
+  return {
+    base,
+    mode,
+    storageRoot:    root,
+    transportDir:   join(root, 'transport'),
+    crosstalkRoot:  join(root, 'crosstalk-root'),
+    crosstalkState: join(root, 'crosstalk-state'),
+    composeFile:    join(root, 'docker-compose.yml'),
+    portFile:       join(root, 'api-port'),
+    authEnvFile:    join(root, 'auth.env'),
+  };
+}
+
+// Container name from --containername flag, defaulting to `crosstalk`.
+// Validates the name is a sane Docker container name + filesystem dir
+// name: lowercase alphanumeric, `_.-`, no leading dot/hyphen.
+const NAME_RE = /^[a-z0-9][a-z0-9_.-]*$/;
+export function parseContainerName(argv) {
+  let name = DEFAULT_CONTAINER_NAME;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--containername' || argv[i] === '-c') {
+      const val = argv[i + 1];
+      if (!val) throw new Error('--containername requires a value');
+      name = val;
+      break;
+    }
+  }
+  if (!NAME_RE.test(name)) {
+    throw new Error(
+      `--containername '${name}' invalid — must be lowercase alphanumeric ` +
+      `with optional ._- (no leading . or -).`,
+    );
+  }
+  return name;
+}
+
+// Read the API port for a given container. Source-of-truth lookup:
+//   1. `<base>/<name>/api-port` file (written at init time)
+//   2. Fallback: DEFAULT_API_PORT
+// We use a file rather than `docker inspect` because the resolver runs
+// before the container exists (`init`) and after it's gone (`rm` cleanup).
+// Docker is authoritative for what's running; the port file is
+// authoritative for which port a given container WOULD use.
+export function apiPortFor(name) {
+  const paths = storagePaths(name);
+  if (existsSync(paths.portFile)) {
+    const v = Number(readFileSync(paths.portFile, 'utf-8').trim());
+    if (Number.isInteger(v) && v > 0 && v < 65536) return v;
+  }
+  return DEFAULT_API_PORT;
+}
+
+// Pick a free TCP port. Default container always gets DEFAULT_API_PORT
+// (7000) so operators have a predictable target. Named containers search
+// upward from 7001 until they find one that doesn't collide with already-
+// allocated containers (any `<base>/*/api-port` file).
+export function pickFreePort(name, mode = storageMode()) {
+  if (name === DEFAULT_CONTAINER_NAME) return DEFAULT_API_PORT;
+  const base = resolveBase(mode);
+  const taken = new Set([DEFAULT_API_PORT]);
+  try {
+    const dirs = readdirSync(base);
+    for (const d of dirs) {
+      const portFile = join(base, d, 'api-port');
+      if (existsSync(portFile)) {
+        const v = Number(readFileSync(portFile, 'utf-8').trim());
+        if (Number.isInteger(v)) taken.add(v);
+      }
+    }
+  } catch { /* base may not exist yet */ }
+  for (let p = 7001; p < 8000; p++) {
+    if (!taken.has(p)) return p;
+  }
+  throw new Error('Could not find a free port between 7001 and 7999.');
+}
+
+// True if `<base>/<name>/transport/.git` exists. The cheapest signal that
+// a transport has been initialized for this name.
+export function isInitialized(name) {
+  const paths = storagePaths(name);
+  return existsSync(join(paths.transportDir, '.git'));
+}
+
+// True if a running container exists for this name. Uses Docker as the
+// source of truth, filtered by our label to avoid confusing
+// operator-named-`crosstalk` containers from other workloads.
+export function isRunning(name) {
+  const r = spawnSync(
+    'docker',
+    ['ps', '--filter', `label=${CROSSTALK_LABEL}`, '--filter', `name=^${name}$`, '--format', '{{.Names}}'],
+    { encoding: 'utf-8' },
+  );
+  if (r.status !== 0) return false;
+  return r.stdout.trim().split('\n').includes(name);
+}
+
+// True if a stopped container exists (less common path; usually `down`
+// removes the container). Checked separately so `up` can decide whether
+// to `docker rm` and recreate.
+export function containerExists(name) {
+  const r = spawnSync(
+    'docker',
+    ['ps', '-a', '--filter', `label=${CROSSTALK_LABEL}`, '--filter', `name=^${name}$`, '--format', '{{.Names}}'],
+    { encoding: 'utf-8' },
+  );
+  if (r.status !== 0) return false;
+  return r.stdout.trim().split('\n').includes(name);
+}
+
+// Look up the resolved name+paths from argv, validate that init has run,
+// and exit with a clear error if not. For verbs that operate on existing
+// transports (up after init, status, chat, down, rm, etc).
+//
+// Validation errors from parseContainerName are caught here and printed
+// cleanly — Mac's bug C from alpha.6 was a raw stack trace when an
+// invalid --containername reached the resolver.
+export function requireInitialized(argv) {
+  let name;
+  try {
+    name = parseContainerName(argv);
+  } catch (err) {
+    process.stderr.write(`crosstalk: ${err.message}\n`);
+    process.exit(1);
+  }
+  if (!isInitialized(name)) {
+    process.stderr.write(
+      `crosstalk: no transport '${name}' on this machine.\n` +
+      `  Run 'crosstalk init${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to set one up.\n`,
+    );
+    process.exit(2);
+  }
+  return { name, paths: storagePaths(name) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "7.0.0-alpha.5",
+  "version": "7.0.0-alpha.7",
   "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
   "type": "module",
   "license": "MIT",