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

package/bin/crosstalk.js

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

package/commands/auth.js

@@ -0,0 +1,218 @@
+// crosstalk auth — manage agent auth tokens/keys.
+//
+// One subverb: `paste`. Operator runs the agent's headless-token
+// generator on their host (`claude setup-token`, etc.), pastes the
+// resulting token at our prompt, and we persist it in the container's
+// env so subsequent dispatch + chat invocations are authenticated.
+//
+// Storage: <base>/<name>/auth.env (0600, operator-UID owned). Docker
+// Compose's `env_file:` references it; each line is `KEY=value`.
+// Existing keys are replaced in-place; new keys append. Empty lines
+// and `#` comments preserved.
+//
+// Why this exists: 5 of the 6 supported agents work cleanly with env-
+// var auth (the headless path), but none of them have a uniform "set
+// the token" UX inside the container. This verb is the operator's
+// one-stop shop — same UX for any agent.
+//
+// Per-agent env var (the audit on 2026-06-14 confirmed each):
+//   claude → CLAUDE_CODE_OAUTH_TOKEN   (preferred: `claude setup-token`)
+//            ANTHROPIC_API_KEY         (alternate: Console API key)
+//   codex  → OPENAI_API_KEY            (preferred)
+//            CODEX_ACCESS_TOKEN        (alternate: device-auth output)
+//   gemini → GEMINI_API_KEY
+//   qwen   → OPENAI_API_KEY            (qwen --auth-type openai)
+//   agy    → none (interactive OAuth only; errors with hint)
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { createInterface } from 'readline';
+import { has, flag } from '../lib/argv.js';
+import { requireInitialized, DEFAULT_CONTAINER_NAME } from '../lib/resolve.js';
+
+const AGENT_ENV = {
+  claude:   { default: 'CLAUDE_CODE_OAUTH_TOKEN', label: 'OAuth token' },
+  codex:    { default: 'OPENAI_API_KEY',          label: 'API key' },
+  gemini:   { default: 'GEMINI_API_KEY',          label: 'API key' },
+  qwen:     { default: 'OPENAI_API_KEY',          label: 'API key' },
+  opencode: { default: 'OPENAI_API_KEY',          label: 'provider API key' },
+};
+
+const AGENT_GEN_CMD = {
+  claude:   'claude setup-token        # on a host with a browser',
+  codex:    'echo $OPENAI_API_KEY      # or platform.openai.com/api-keys',
+  gemini:   'echo $GEMINI_API_KEY      # or aistudio.google.com/apikey',
+  qwen:     'echo $OPENAI_API_KEY      # OpenAI-compatible',
+  opencode: 'echo $OPENAI_API_KEY      # or provider-specific',
+};
+
+// Control byte values used by the TTY prompt — avoid embedding raw
+// bytes inline so the file is editor/linter clean.
+const CTRL_C = String.fromCharCode(3);   // 0x03 — interrupt
+const CTRL_D = String.fromCharCode(4);   // 0x04 — EOF
+const BS     = String.fromCharCode(8);   // 0x08 — backspace
+const DEL    = String.fromCharCode(127); // 0x7F — terminal backspace
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk auth paste --agent <name> [--containername <name>]
+
+Persists an auth token/key for an agent CLI into the container's
+environment. Operator generates the value on the host (which has a
+browser) and pastes at the prompt; crosstalk writes it to
+<base>/<name>/auth.env. Subsequent dispatch + chat invocations pick
+it up via the engine container's env.
+
+Options:
+  --agent <name>           One of: claude, codex, gemini, qwen, opencode.
+                           agy is interactive-only; use 'crosstalk chat
+                           --agent agy --login' for OAuth instead.
+  --containername <name>   Which crosstalk container to set the env on
+                           (default: 'crosstalk').
+  -c <name>                Shorthand for --containername.
+
+Reads from stdin (hidden) — if the input isn't a TTY, the entire stdin
+is read as the token (e.g. piped from a setup script).
+
+After paste, run 'crosstalk restart' to pick up the new env.
+`,
+  );
+  process.exit(exit);
+}
+
+function promptHidden(promptText) {
+  return new Promise((resolve) => {
+    process.stderr.write(promptText);
+    if (!process.stdin.isTTY) {
+      let buf = '';
+      process.stdin.on('data', (chunk) => { buf += chunk.toString(); });
+      process.stdin.on('end', () => resolve(buf.trim()));
+      return;
+    }
+    if (typeof process.stdin.setRawMode !== 'function') {
+      const rl = createInterface({ input: process.stdin, output: process.stderr });
+      rl.question('', (ans) => { rl.close(); resolve(ans.trim()); });
+      return;
+    }
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf-8');
+    let buf = '';
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') {
+          process.stderr.write('\n');
+          process.stdin.setRawMode(false);
+          process.stdin.pause();
+          process.stdin.removeListener('data', onData);
+          resolve(buf.trim());
+          return;
+        }
+        if (ch === CTRL_C || ch === CTRL_D) {
+          process.stderr.write('\n');
+          process.stdin.setRawMode(false);
+          process.exit(130);
+        }
+        if (ch === BS || ch === DEL) {
+          buf = buf.slice(0, -1);
+          continue;
+        }
+        buf += ch;
+      }
+    };
+    process.stdin.on('data', onData);
+  });
+}
+
+// Upsert a KEY=value line in env-file content. Preserves other lines +
+// comments. Returns the new content.
+function upsertEnv(existing, key, value) {
+  const lines = existing.split('\n');
+  let replaced = false;
+  const out = lines.map((line) => {
+    if (line.startsWith(`${key}=`)) {
+      replaced = true;
+      return `${key}=${value}`;
+    }
+    return line;
+  });
+  if (!replaced) {
+    while (out.length > 0 && out[out.length - 1] === '') out.pop();
+    out.push(`${key}=${value}`);
+    out.push('');
+  }
+  return out.join('\n');
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const pos = argv.filter((a) => !a.startsWith('-'));
+  const subverb = pos[0];
+  if (subverb !== 'paste') {
+    if (subverb) {
+      process.stderr.write(`crosstalk auth: unknown subverb '${subverb}'. Try 'paste'.\n`);
+    } else {
+      usage(1);
+    }
+    return 1;
+  }
+
+  const agent = flag(argv, '--agent');
+  if (!agent) {
+    process.stderr.write(`crosstalk auth paste: --agent <name> is required.\n`);
+    return 1;
+  }
+
+  if (agent === 'agy') {
+    process.stderr.write(
+      `crosstalk auth paste: agy has no headless env-var path — its only auth is interactive OAuth.\n` +
+      `  Use 'crosstalk chat --agent agy --login' to set up auth.\n`,
+    );
+    return 1;
+  }
+
+  const cfg = AGENT_ENV[agent];
+  if (!cfg) {
+    process.stderr.write(
+      `crosstalk auth paste: unknown agent '${agent}'.\n` +
+      `  Supported: ${Object.keys(AGENT_ENV).join(', ')}.\n`,
+    );
+    return 1;
+  }
+
+  const { name, paths } = requireInitialized(argv);
+
+  if (process.stdin.isTTY) {
+    process.stderr.write(
+      `\nPasting ${cfg.label} for ${agent} into '${name}' container.\n` +
+      `  Env var: ${cfg.default}\n` +
+      `  Storage: ${paths.authEnvFile}\n` +
+      `\nGenerate on host:\n  ${AGENT_GEN_CMD[agent] ?? '(see agent docs)'}\n` +
+      `\nPaste the value below (input hidden, press Enter):\n`,
+    );
+  }
+  const value = await promptHidden('> ');
+  if (!value) {
+    process.stderr.write(`crosstalk auth paste: empty input — aborted.\n`);
+    return 1;
+  }
+  if (value.includes('\n')) {
+    process.stderr.write(
+      `crosstalk auth paste: input contains a newline. Tokens are single-line; check copy/paste.\n`,
+    );
+    return 1;
+  }
+
+  const existing = existsSync(paths.authEnvFile)
+    ? readFileSync(paths.authEnvFile, 'utf-8')
+    : '';
+  const updated = upsertEnv(existing, cfg.default, value);
+  writeFileSync(paths.authEnvFile, updated, { mode: 0o600 });
+
+  process.stdout.write(
+    `\nSaved ${cfg.default} to ${paths.authEnvFile}.\n` +
+    `Run 'crosstalk restart${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to pick up the new env.\n`,
+  );
+  return 0;
+}

package/commands/chat.js

@@ -132,6 +132,17 @@ Examples:
   process.exit(exit);
 }
 
+// Detect host terminal dims with sane fallbacks. Pass into the
+// container via -e COLUMNS/LINES so the agent CLI renders at the
+// operator's real terminal size instead of docker's 80×24 fallback.
+// (When stdout is piped — like in --login — docker can't auto-detect
+// the host's stdout terminal, which is mac's alpha.6 bug D.)
+function hostTermDims() {
+  const cols = process.stdout.columns || process.stderr.columns || 120;
+  const rows = process.stdout.rows    || process.stderr.rows    || 40;
+  return { cols, rows };
+}
+
 function runInteractive(container, command, env = {}) {
   // Full TTY passthrough — docker exec -it gives the container a real
   // PTY, and stdio: 'inherit' forwards stdin/stdout/stderr from the
@@ -147,30 +158,79 @@ function runInteractive(container, command, env = {}) {
   return r.status ?? 1;
 }
 
+// Per-agent login command. Returns null for agents without an OAuth
+// path (gemini, qwen, opencode) — these need env-var auth, not browser
+// OAuth. The full audit (cachy 2026-06-14) confirmed each agent's
+// surface:
+//   claude  → `claude auth login` (clean single-line URL output)
+//   codex   → `codex login`       (clean single-line URL output)
+//   agy     → `agy --print init`  (triggers OAuth, clean URL)
+// We use the explicit auth subcommand instead of bare invocation —
+// that's mac's bug D fix root cause. Bare `claude` drops into a TUI
+// with line wraps + winsize sensitivity that broke URL extraction
+// across alpha.3 → alpha.6. The official auth subcommand prints a
+// plain single-line URL on stdout, no TUI involved.
+function loginCommand(agent) {
+  if (agent === 'claude') return ['claude', 'auth', 'login'];
+  if (agent === 'codex')  return ['codex', 'login'];
+  if (agent === 'agy')    return ['agy', '--print', 'init'];
+  return null;  // gemini, qwen, opencode — env-based
+}
+
+// Per-agent env-var hint for the no-OAuth agents.
+function envHint(agent) {
+  if (agent === 'gemini')   return 'GEMINI_API_KEY';
+  if (agent === 'qwen')     return 'OPENAI_API_KEY (qwen --auth-type openai)';
+  if (agent === 'opencode') return 'per-provider keys in opencode config';
+  return null;
+}
+
 function runLogin(container, agent) {
-  // Login mode: tee the agent's stdout so we can spot the auth URL and
-  // open it in the operator's browser. The container still has a real
-  // PTY (docker exec -it allocates one inside the container regardless
-  // of host stdio configuration), so the agent CLI renders into a TTY;
-  // we just pipe the bytes on the host side to inspect them.
-  //
-  // No agent-specific "login" subcommand — we just run the agent's
-  // default interactive entry point. First-run auth flow happens
-  // automatically for every agent we support.
-  //
-  // No COLUMNS=1000 env: making the agent render the URL "unwrapped" via
-  // a wide terminal claim doesn't reliably propagate to the in-container
-  // PTY, and even when it does Claude's TUI hard-wraps anyway. The
-  // extractCompleteUrl() function joins wrapped URL fragments on the
-  // host side, so the agent's rendering width is irrelevant. As bonus,
-  // dropping COLUMNS=1000 fixes daily-chat soft-wrap weirdness in
-  // long-form prose (agents see the real host terminal width).
+  const cmd = loginCommand(agent);
+  if (!cmd) {
+    const env = envHint(agent);
+    process.stderr.write(
+      `crosstalk chat --login --agent ${agent}: this agent has no browser OAuth flow.\n` +
+      (env ? `  Use environment-based auth instead:\n    crosstalk auth paste --agent ${agent}\n  (or set ${env} directly in docker-compose.yml)\n` : '') +
+      `  Documented in GUIDE-CLI.md § Agent auth.\n`,
+    );
+    return Promise.resolve(1);
+  }
+
+  // Pass host terminal dims explicitly. Docker exec -t normally sizes
+  // the container PTY off its stdout terminal, but we PIPE stdout (to
+  // scrape the OAuth URL), so docker has no TTY to size from and falls
+  // back to 80×24 — that's mac's bug D root cause. Setting COLUMNS/LINES
+  // env vars gets the agent CLI to render at the right size from the
+  // start. (Live SIGWINCH updates aren't propagated — docker env is
+  // set-at-spawn — but OAuth flows are short; operators don't typically
+  // resize the terminal mid-auth.)
+  const { cols, rows } = hostTermDims();
+
   return new Promise((resolve) => {
     const child = spawn(
       'docker',
-      ['exec', '-it', container, agent],
+      ['exec', '-it',
+       '-e', `COLUMNS=${cols}`,
+       '-e', `LINES=${rows}`,
+       '-e', 'TERM=xterm-256color',
+       container, ...cmd],
       { stdio: ['inherit', 'pipe', 'inherit'] },
     );
+
+    // SIGWINCH handler: docker env is set-at-spawn so we can't dynamically
+    // resize the in-container PTY without a control channel (would need
+    // node-pty or a sidecar process). Best-effort: surface that a resize
+    // happened so the operator knows why the TUI may not have responded.
+    const onWinch = () => {
+      const { cols: c, rows: r } = hostTermDims();
+      process.stderr.write(
+        `\n[crosstalk chat] Terminal resized to ${c}×${r} — in-container PTY won't update mid-session. ` +
+        `Exit (Ctrl-C) and retry if rendering is off.\n`,
+      );
+    };
+    process.on('SIGWINCH', onWinch);
+
     let opened = false;
     let buffer = '';
     child.stdout.on('data', (chunk) => {
@@ -187,8 +247,14 @@ function runLogin(container, agent) {
           : `\n[crosstalk chat] Could not auto-open browser. Open this URL manually:\n  ${url}\n`,
       );
     });
-    child.on('exit', (code) => resolve(code ?? 0));
-    child.on('error', () => resolve(1));
+    child.on('exit', (code) => {
+      process.removeListener('SIGWINCH', onWinch);
+      resolve(code ?? 0);
+    });
+    child.on('error', () => {
+      process.removeListener('SIGWINCH', onWinch);
+      resolve(1);
+    });
   });
 }
 

package/commands/init.js

@@ -1,40 +1,40 @@
 // crosstalk init — scaffold a transport into <base>/<name>/.
 //
-// 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).
+// alpha.7 rewrite: phased + idempotent. Each phase is independent and
+// safe to re-run; re-init detects missing markers and repairs them.
+// Mac caught bug A in alpha.6 where the api-port file was written at
+// the end of the pipeline, so any disruption (image pull, git failure)
+// left storage existing but unstartable — and re-init silently
+// no-op-ed instead of fixing it.
 //
-// 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
+// Phases:
+//   1. Storage layout — mkdir subdirs + write api-port. Pure FS, fast,
+//      runs first so the resolver-visible marker exists before anything
+//      else can go wrong.
+//   2. Transport scaffold — `crosstalkd init` in a one-shot container.
+//      Skipped if transport/.git already exists. stdout/stderr captured
+//      (mac's bug B — in-container scaffold output was leaking).
+//   3. Git init + initial commit. Skipped if .git exists.
+//   4. Remote setup if --remote given (errors if a different origin
+//      is already set; idempotent on same-value).
+//   5. Summary.
 //
-// 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, writeFileSync } from 'fs';
+// Each phase reports created/skipped/repaired so operators can tell
+// what just happened.
+
+import { mkdirSync, existsSync, writeFileSync, readFileSync } from 'fs';
 import { spawnSync } from 'child_process';
+import { join } from 'path';
 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.6';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.7';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
@@ -42,8 +42,11 @@ function usage(exit = 0) {
 `Usage:
   crosstalk init [--containername <name>] [--remote <url>]
 
-Creates a new transport on this machine. The transport git repo lives at
-<base>/<name>/transport/ where <base> is:
+Creates a new transport on this machine, or repairs an existing
+incomplete one. Idempotent — re-running fills in any missing markers
+without disturbing existing state.
+
+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\\
@@ -55,8 +58,8 @@ 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.
+  --remote <url>           Set git upstream. If a different remote is
+                           already set, errors instead of overwriting.
   --image <tag>            Override the engine image (default: bundled
                            GHCR tag; or CROSSTALK_IMAGE env).
   -c <name>                Shorthand for --containername.
@@ -81,22 +84,15 @@ export async function run(argv) {
     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);
+  const report = [];
 
-  // Pre-create the storage tree. Docker would auto-create the bind-mount
-  // dirs root-owned otherwise, breaking the entrypoint's chown step.
+  // ── Phase 1: Storage layout ────────────────────────────────────────
+  // mkdir is idempotent (recursive: true). Write api-port if absent.
+  // This is the load-bearing fix for bug A — port file lands FIRST,
+  // before anything else can go wrong (image pull, git init, etc.).
   try {
     mkdirSync(paths.transportDir,   { recursive: true });
     mkdirSync(paths.crosstalkRoot,  { recursive: true });
@@ -114,81 +110,140 @@ export async function run(argv) {
     return 1;
   }
 
-  // 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}`] : [];
-
-  const dockerArgs = [
-    'run', '--rm',
-    '-v', `${paths.transportDir}:/init-target`,
-    ...userArgs,
-    '--entrypoint', 'crosstalkd',
-    image,
-    'init', '/init-target',
-  ];
+  let port;
+  if (existsSync(paths.portFile)) {
+    const v = Number(readFileSync(paths.portFile, 'utf-8').trim());
+    if (Number.isInteger(v) && v > 0 && v < 65536) {
+      port = v;
+      report.push(`  api port:   ${port} (existing)`);
+    }
+  }
+  if (!port) {
+    try {
+      port = pickFreePort(name);
+      writeFileSync(paths.portFile, `${port}\n`);
+      report.push(`  api port:   ${port} (allocated)`);
+    } catch (err) {
+      process.stderr.write(`crosstalk init: port allocation failed — ${err.message}\n`);
+      return 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;
+  // Ensure an empty auth.env exists so compose's env_file: can reference
+  // it without erroring on missing file. Operator-owned, 0600 — even
+  // when empty it's where `crosstalk auth paste` will land tokens.
+  if (!existsSync(paths.authEnvFile)) {
+    writeFileSync(paths.authEnvFile, '', { mode: 0o600 });
+  }
+
+  // ── Phase 2: Transport scaffold ────────────────────────────────────
+  // The template-scaffold check is "does CROSSTALK-VERSION exist?" NOT
+  // ".git exists" — git init is a separate phase, and the engine refuses
+  // to re-scaffold over an existing CROSSTALK-VERSION (without --force).
+  // Decoupling means a disrupted init (template written, git init never
+  // ran) re-enters Phase 3 cleanly on re-run.
+  const transportGitDir      = join(paths.transportDir, '.git');
+  const crosstalkVersionFile = join(paths.transportDir, 'CROSSTALK-VERSION');
+  if (!existsSync(crosstalkVersionFile)) {
+    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}`] : [];
+
+    const dockerArgs = [
+      'run', '--rm',
+      '-v', `${paths.transportDir}:/init-target`,
+      ...userArgs,
+      '--entrypoint', 'crosstalkd',
+      image,
+      'init', '/init-target',
+    ];
+
+    // Bug B fix: don't inherit stdio — the engine prints next-steps that
+    // confuse operators ("Transport initialized at /init-target" with
+    // container-internal paths). Capture, show only on failure.
+    const initRun = spawnSync('docker', dockerArgs, { stdio: 'pipe' });
+    if (initRun.status !== 0) {
+      const stderr = initRun.stderr?.toString() ?? '';
+      const stdout = initRun.stdout?.toString() ?? '';
+      process.stderr.write(`crosstalk init: docker run exited ${initRun.status}\n`);
+      if (stderr.trim()) process.stderr.write(`  stderr: ${stderr.trim()}\n`);
+      if (stdout.trim()) process.stderr.write(`  stdout: ${stdout.trim()}\n`);
+      process.stderr.write(`  command was: docker ${dockerArgs.join(' ')}\n`);
+      return initRun.status ?? 1;
+    }
+    report.push(`  template:   scaffolded via ${image}`);
+  } else {
+    report.push(`  template:   present (skipped scaffold)`);
+  }
+
+  // ── Phase 3: Git init + initial commit ─────────────────────────────
+  if (!existsSync(crosstalkVersionFile)) {
+    // Engine init succeeded but didn't leave files. Bail clearly — we
+    // won't proceed to git init on an empty dir.
+    process.stderr.write(
+      `crosstalk init: transport template missing at ${paths.transportDir}\n` +
+      `  Engine init didn't write template files. Try 'crosstalk rm' then re-init.\n`,
+    );
+    return 1;
   }
 
-  // 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'],
   ];
+  let gitOk = true;
   for (const args of gitSteps) {
     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 — ${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
+      // 'git init' on existing repo is fine (it re-runs idempotently);
+      // 'add -A' is also idempotent. 'commit' fails when there's
+      // nothing to commit — that means a previous run already committed.
+      // Only the first call (git init) is load-bearing; the rest are
+      // best-effort to populate the initial state.
+      gitOk = false;
       break;
     }
   }
+  report.push(gitOk ? `  git:        initialized + committed` : `  git:        already present (skipped)`);
 
-  // Set up the upstream if requested. Failures here aren't fatal —
-  // operator can retry with `cd <transport-dir> && git remote add`.
+  // ── Phase 4: Remote setup ──────────────────────────────────────────
   if (remote) {
-    const rr = spawnSync('git', ['remote', 'add', 'origin', remote], {
+    const cur = spawnSync('git', ['remote', 'get-url', 'origin'], {
       cwd: paths.transportDir,
       stdio: 'pipe',
     });
-    if (rr.status !== 0) {
+    const currentUrl = cur.status === 0 ? cur.stdout.toString().trim() : null;
+    if (!currentUrl) {
+      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`,
+        );
+      } else {
+        report.push(`  remote:     ${remote} (added)`);
+      }
+    } else if (currentUrl === remote) {
+      report.push(`  remote:     ${remote} (already set)`);
+    } else {
       process.stderr.write(
-        `crosstalk init: 'git remote add origin ${remote}' failed — ${rr.stderr?.toString().trim()}\n`,
+        `crosstalk init: remote already set to '${currentUrl}'; refusing to overwrite with '${remote}'.\n` +
+        `  Use 'crosstalk status' to see the transport path; cd there and adjust git config manually if intended.\n`,
       );
+      return 1;
     }
   }
 
-  // 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;
-  }
-
+  // ── Phase 5: Summary ───────────────────────────────────────────────
   process.stdout.write(
-    `\nTransport '${name}' initialized:\n` +
+    `\nTransport '${name}' ready:\n` +
     `  storage:    ${paths.storageRoot}\n` +
     `  transport:  ${paths.transportDir}\n` +
     `  image:      ${image}\n` +
-    `  api port:   ${port}\n` +
-    (remote ? `  remote:     ${remote}\n` : '') +
+    report.join('\n') + '\n' +
     `\nNext: crosstalk up${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}\n`,
   );
   return 0;

package/commands/restart.js

@@ -1,4 +1,9 @@
 // crosstalk restart — restart a transport's engine container.
+//
+// Uses `compose up -d --force-recreate` (not `compose restart`) so
+// changes to env_file (e.g. tokens added via `crosstalk auth paste`)
+// are picked up. Plain `compose restart` just stops + starts the same
+// container without re-reading config.
 
 import { existsSync } from 'fs';
 import { spawnSync } from 'child_process';
@@ -15,8 +20,10 @@ export async function run(argv) {
     process.stderr.write(`crosstalk restart: '${name}' has no compose file — run 'crosstalk up' first.\n`);
     return 1;
   }
-  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'restart'], {
-    stdio: 'inherit',
-  });
+  const r = spawnSync(
+    'docker',
+    ['compose', '-f', paths.composeFile, 'up', '-d', '--force-recreate'],
+    { stdio: 'inherit' },
+  );
   return r.status ?? 1;
 }

package/commands/up.js

@@ -24,7 +24,7 @@ import {
 } from '../lib/resolve.js';
 
 const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
-  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.6';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.7';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
@@ -69,6 +69,8 @@ services:
       - ${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}"

package/lib/api-client.js

@@ -111,9 +111,16 @@ async function call(method, path, body, opts = {}) {
 
 // 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.
+// 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) {
-  const name = parseContainerName(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 }),

package/lib/resolve.js

@@ -66,6 +66,7 @@ export function storagePaths(name, mode = storageMode()) {
     crosstalkState: join(root, 'crosstalk-state'),
     composeFile:    join(root, 'docker-compose.yml'),
     portFile:       join(root, 'api-port'),
+    authEnvFile:    join(root, 'auth.env'),
   };
 }
 
@@ -168,8 +169,18 @@ export function containerExists(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) {
-  const name = parseContainerName(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` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "7.0.0-alpha.6",
+  "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",