@cordfuse/crosstalk 7.0.0-alpha.1 → 7.0.0-alpha.10

package/commands/status.js

@@ -1,9 +1,16 @@
 // crosstalk status — mirror of crosstalkd status output, fetched via API.
+//
+// alpha.6: also prints the host path of the transport git repo as an
+// escape hatch for operators who want to poke around with raw git.
 
-import { api } from '../lib/api-client.js';
+import { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
+import { requireInitialized } from '../lib/resolve.js';
+
+export async function run(argv) {
+  const { name, paths } = requireInitialized(argv);
+  const api = apiFor(argv);
 
-export async function run(_argv) {
   let s;
   try {
     s = await api.get('/status');
@@ -11,14 +18,45 @@ export async function run(_argv) {
     reportAndExit(err, 'crosstalk status');
   }
 
-  process.stdout.write(`Crosstalk transport: ${s.transport_root}\n`);
+  process.stdout.write(`Container:           ${name}\n`);
+  process.stdout.write(`Transport host path: ${paths.transportDir}\n`);
   process.stdout.write(`Engine alias:        ${s.alias}\n`);
   process.stdout.write(`Engine version:      ${s.version}\n`);
   process.stdout.write('\n');
 
   process.stdout.write(`Claimed models: ${s.claimed_models.length}\n`);
   if (s.claimed_models.length === 0) {
-    process.stdout.write('  (no model CLIs found inside the container — install one or edit data/models.yaml)\n');
+    let installed = null;
+    let yamlReferenced = null;
+    try {
+      const r = await api.get('/agents/installed');
+      installed = r.installed;
+      yamlReferenced = r.yaml_referenced;
+    } catch { /* ignore — fall back to generic message */ }
+    if (installed && installed.length > 0) {
+      // M2 (alpha.10): differentiate "yaml references it but the claim
+      // list is stale" from "yaml has no entry yet". The dispatcher
+      // claims at startup; a CLI installed after `crosstalk up` doesn't
+      // surface until `crosstalk restart`.
+      const referencedSet = new Set(yamlReferenced ?? []);
+      const installedAndReferenced = installed.filter((b) => referencedSet.has(b));
+      const installedNotReferenced = installed.filter((b) => !referencedSet.has(b));
+      if (installedAndReferenced.length > 0) {
+        const verb = installedAndReferenced.length === 1 ? 'is' : 'are';
+        process.stdout.write(
+          `  (${installedAndReferenced.join(', ')} ${verb} installed and referenced in data/crosstalk.yaml ` +
+          `but not yet claimed — run 'crosstalk restart' to refresh the dispatcher's claim list)\n`,
+        );
+      }
+      if (installedNotReferenced.length > 0) {
+        const verb = installedNotReferenced.length === 1 ? 'references it' : 'references them';
+        process.stdout.write(
+          `  (${installedNotReferenced.join(', ')} installed in the container but no data/crosstalk.yaml entry ${verb} — add one to claim)\n`,
+        );
+      }
+    } else {
+      process.stdout.write('  (no model CLIs found inside the container — install one via `crosstalk chat --shell` and add an entry to data/crosstalk.yaml)\n');
+    }
   } else {
     for (const m of s.claimed_models) process.stdout.write(`  - ${m}\n`);
   }
@@ -41,9 +79,9 @@ export async function run(_argv) {
 
   process.stdout.write(`Channels: ${s.channels.length}\n`);
   for (const ch of s.channels) {
-    const name = ch.name ?? '(unnamed)';
+    const chName = ch.name ?? '(unnamed)';
     const parentSuffix = ch.parent ? ` [child of ${ch.parent.slice(0, 8)}]` : '';
-    process.stdout.write(`  ${ch.uuid.slice(0, 8)}... — ${name}${parentSuffix}\n`);
+    process.stdout.write(`  ${ch.uuid.slice(0, 8)}... — ${chName}${parentSuffix}\n`);
   }
   process.stdout.write('\n');
 

package/commands/up.js

@@ -1,68 +1,74 @@
-// 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, appendFileSync, readFileSync } from 'fs';
+import { writeFileSync, existsSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { join } from 'path';
-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.1';
-const DEFAULT_API_PORT = Number(process.env.CROSSTALK_API_PORT) || 7000;
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.8';
 
 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. Override the image with
-CROSSTALK_IMAGE, the API port with CROSSTALK_API_PORT.
+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         Override the engine image
+  CROSSTALK_ALIAS         Override the engine's machine identity
+                          (defaults to the container name)
 `,
   );
   process.exit(exit);
 }
 
-function renderCompose({ name, image, apiPort, alias, uid, gid }) {
-  // Entrypoint runs as root for setup (apt-installed CLIs in /root,
-  // 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 to that user, and 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 friends work without sudo. /root stays
-  // root-owned for CLI installs.
-  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.
+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. Root-owned, dispatcher reads only.
-      - crosstalk-root:/root
-      # Dispatcher's machine-local state: cursor, heartbeat, errors.log.
-      # Operator-UID-owned (chowned by entrypoint to CROSSTALK_UID/GID).
-      - crosstalk-state:/var/lib/crosstalkd-state
+      - ${paths.transportDir}:/var/lib/crosstalk-transport
+      - ${paths.crosstalkRoot}:/crosstalk-root
+      - ${paths.crosstalkState}:/var/lib/crosstalk-state
     environment:
       CROSSTALK_ALIAS: ${alias}
       CROSSTALK_UID: "${uid}"
@@ -70,52 +76,52 @@ services:
       CROSSTALKD_API_PORT: "7000"
       DISPATCH_JSON: "true"
       DISPATCH_POLL_SECONDS: "30"
-
-volumes:
-  crosstalk-root:
-  crosstalk-state:
 `;
 }
 
-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;
-    const content = renderCompose({
-      name: transportName(root),
-      image: DEFAULT_IMAGE,
-      apiPort: DEFAULT_API_PORT,
-      alias,
-      uid,
-      gid,
-    });
-    writeFileSync(composeYml, content);
-    ensureGitignored(root);
-    process.stdout.write(`Generated ${composeYml}\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) {
@@ -123,7 +129,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,15 +7,18 @@
 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.
     const v = await api.get('/version');
     process.stdout.write(`crosstalkd engine: ${v.version} (alias: ${v.alias})\n`);
   } catch (err) {

package/lib/api-client.js

@@ -1,23 +1,57 @@
 // 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 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 {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync(join(thisDir, '..', 'package.json'), 'utf-8')).version;
+  } catch {
+    return 'unknown';
+  }
+})();
 
-export const DEFAULT_API_PORT = 7000;
+let skewWarned = false;
+
+function checkSkew(engineVersion) {
+  if (skewWarned || !engineVersion || engineVersion === CLIENT_VERSION) return;
+  skewWarned = true;
+  process.stderr.write(
+    `[WARN] Version skew: client ${CLIENT_VERSION}, engine ${engineVersion}.\n` +
+    `       Pre-1.0 client and engine ship in lockstep. Likely fix:\n` +
+    `         crosstalk pull && crosstalk restart    # if engine is behind\n` +
+    `         npm install -g @cordfuse/crosstalk     # if client is behind\n\n`,
+  );
+}
 
-export function resolvePort(explicit) {
-  if (typeof explicit === 'number' && Number.isInteger(explicit)) return explicit;
+export { DEFAULT_API_PORT };
+
+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;
 }
 
@@ -59,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,
@@ -71,10 +105,37 @@ async function call(method, path, body, opts = {}) {
   } catch (err) {
     throw new ConnectError(port, err.message || String(err));
   }
+  checkSkew(res.headers.get('x-crosstalk-engine-version'));
   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),
+  get:    (path, opts)        => call('GET',    path, undefined, opts),
+  post:   (path, body, opts)  => call('POST',   path, body,       opts),
+  patch:  (path, body, opts)  => call('PATCH',  path, body,       opts),
+  delete: (path, opts)        => call('DELETE', path, undefined,  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,191 @@
+// 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'),
+  };
+}
+
+// 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.1",
+  "version": "7.0.0-alpha.10",
   "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
   "type": "module",
   "license": "MIT",