@cordfuse/crosstalk 6.0.0-alpha.9 → 7.0.0-alpha.1

package/commands/restart.js

@@ -0,0 +1,24 @@
+// crosstalk restart — restart the engine container.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { requireTransportRoot, composeFile } from '../lib/transport.js';
+import { has } from '../lib/argv.js';
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) {
+    process.stdout.write('Usage: crosstalk restart\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`);
+    return 1;
+  }
+  const r = spawnSync('docker', ['compose', '-f', composeYml, 'restart'], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  return r.status ?? 1;
+}

package/commands/run.js

@@ -0,0 +1,121 @@
+// crosstalk run — dispatch a primitive or workflow via POST /messages.
+//
+// Mirrors crosstalkd's run surface:
+//   crosstalk run --type primitive --to <model>[@<machine>] [--as <persona>]
+//                 [--fanout <n>] [--channel <name|uuid>] [--from <name>]
+//                 [--new] <body|file|->
+//   crosstalk run --type workflow [--channel <name|uuid>] [--from <name>]
+//                 [--new] <file|->
+
+import { readFileSync, existsSync, statSync } from 'fs';
+import { api } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { flag, has } from '../lib/argv.js';
+
+const FLAGS_WITH_VALUE = new Set(['--type', '--to', '--as', '--fanout', '--channel', '--from']);
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk run --type primitive --to <model>[@<machine>] \\
+                 [--as <persona>] [--fanout <n>] \\
+                 [--channel <name|uuid>] [--from <name>] [--new] \\
+                 <body|file|->
+
+  crosstalk run --type workflow [--channel <name|uuid>] \\
+                 [--from <name>] [--new] <file|->
+`,
+  );
+  process.exit(exit);
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function resolveBody(arg) {
+  if (arg == null) return null;
+  if (arg === '-') return readStdin();
+  if (existsSync(arg)) {
+    try {
+      if (statSync(arg).isFile()) return readFileSync(arg, 'utf-8');
+    } catch { /* fall through to inline */ }
+  }
+  return arg;
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const type = flag(argv, '--type');
+  if (type !== 'primitive' && type !== 'workflow') usage(1);
+
+  // The body is the last non-flag arg. Walk argv backwards skipping
+  // flag values.
+  let bodyArg;
+  for (let i = argv.length - 1; i >= 0; i--) {
+    const a = argv[i];
+    if (a.startsWith('--')) break;
+    // Make sure we're not the value of a flag like `--to <value>`
+    const prev = argv[i - 1];
+    if (prev && FLAGS_WITH_VALUE.has(prev)) continue;
+    bodyArg = a;
+    break;
+  }
+
+  const body = resolveBody(bodyArg);
+  if (body == null || body.length === 0) {
+    process.stderr.write('crosstalk run: missing body (file path, inline string, or `-` for stdin)\n');
+    return 1;
+  }
+
+  const channel = flag(argv, '--channel');
+  const from = flag(argv, '--from') ?? process.env.USER ?? 'operator';
+
+  let payload;
+  if (type === 'primitive') {
+    const to = flag(argv, '--to');
+    if (!to) {
+      process.stderr.write('crosstalk run --type primitive: --to <model> is required\n');
+      return 1;
+    }
+    const fanoutRaw = flag(argv, '--fanout');
+    const fanout = fanoutRaw ? Math.max(1, parseInt(fanoutRaw, 10)) : 1;
+    payload = {
+      type: 'primitive',
+      to,
+      as: flag(argv, '--as'),
+      channel,
+      from,
+      fanout,
+      body,
+    };
+  } else {
+    payload = {
+      type: 'workflow',
+      channel,
+      from,
+      body,
+    };
+  }
+
+  let resp;
+  try {
+    resp = await api.post('/messages', payload);
+  } catch (err) {
+    reportAndExit(err, 'crosstalk run');
+  }
+
+  if (resp.type === 'primitive') {
+    for (const p of resp.relPaths) process.stdout.write(`Sent: ${p}\n`);
+  } else {
+    process.stdout.write(`Workflow dispatched: ${resp.relPath}\n`);
+    process.stdout.write(`Child channel: ${resp.childChannel} (parent: ${resp.channel.slice(0, 8)})\n`);
+  }
+  return 0;
+}

package/commands/status.js

@@ -0,0 +1,52 @@
+// crosstalk status — mirror of crosstalkd status output, fetched via API.
+
+import { api } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+
+export async function run(_argv) {
+  let s;
+  try {
+    s = await api.get('/status');
+  } catch (err) {
+    reportAndExit(err, 'crosstalk status');
+  }
+
+  process.stdout.write(`Crosstalk transport: ${s.transport_root}\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');
+  } else {
+    for (const m of s.claimed_models) process.stdout.write(`  - ${m}\n`);
+  }
+  process.stdout.write('\n');
+
+  if (s.heartbeat) {
+    const ageS = Math.floor((Date.now() - new Date(s.heartbeat.ts).getTime()) / 1000);
+    const label = ageS < 120 ? 'LIVE' : ageS > 300 ? 'STALE' : 'idle';
+    process.stdout.write(`Dispatch heartbeat: ${label} (pid ${s.heartbeat.pid}, last tick ${ageS}s ago, ${s.heartbeat.version})\n`);
+  } else {
+    process.stdout.write('Dispatch heartbeat: never\n');
+  }
+
+  if (s.cursor) {
+    process.stdout.write(`Cursor: ${s.cursor.slice(0, 12)} (global, machine-local)\n`);
+  } else {
+    process.stdout.write('Cursor: (none yet — first tick will seed to HEAD)\n');
+  }
+  process.stdout.write('\n');
+
+  process.stdout.write(`Channels: ${s.channels.length}\n`);
+  for (const ch of s.channels) {
+    const name = 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('\n');
+
+  process.stdout.write(`Infrastructure errors logged: ${s.errors_logged}\n`);
+  return 0;
+}

package/commands/up.js

@@ -0,0 +1,129 @@
+// crosstalk up — bring up the engine container for this 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.
+//
+// Subsequent runs: just shell out to `docker compose up -d`.
+
+import { writeFileSync, existsSync, appendFileSync, 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';
+
+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;
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk up
+
+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.
+`,
+  );
+  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.
+
+services:
+  crosstalkd:
+    image: ${image}
+    container_name: crosstalk-${name}
+    restart: unless-stopped
+    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
+    environment:
+      CROSSTALK_ALIAS: ${alias}
+      CROSSTALK_UID: "${uid}"
+      CROSSTALK_GID: "${gid}"
+      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);
+
+  if (generated) {
+    const alias = process.env.CROSSTALK_ALIAS ?? process.env.HOSTNAME ?? transportName(root);
+    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 r = spawnSync('docker', ['compose', '-f', composeYml, 'up', '-d'], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  if (r.status !== 0) {
+    process.stderr.write(`crosstalk up: docker compose exited ${r.status}\n`);
+    return r.status ?? 1;
+  }
+  process.stdout.write(
+    `\nEngine starting. Check status with 'crosstalk status' (give it ~5s to settle).\n`,
+  );
+  return 0;
+}

package/commands/version.js

@@ -0,0 +1,30 @@
+// crosstalk version — print client and (if reachable) engine versions.
+//
+// Doesn't fail if the engine isn't reachable; just prints "(engine
+// unreachable)" since you might be running `version` before bringing
+// the container up.
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { api, 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) {
+  process.stdout.write(`crosstalk client: ${clientPkg.version}\n`);
+  try {
+    const v = await api.get('/version');
+    process.stdout.write(`crosstalkd engine: ${v.version} (alias: ${v.alias})\n`);
+  } catch (err) {
+    if (err instanceof ConnectError) {
+      process.stdout.write(`crosstalkd engine: (unreachable on 127.0.0.1:${err.port})\n`);
+      return 0;
+    }
+    process.stdout.write(`crosstalkd engine: (error: ${err.message})\n`);
+    return 0;
+  }
+  return 0;
+}

package/lib/api-client.js

@@ -0,0 +1,80 @@
+// 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>.
+//
+// Port resolution (in order):
+//   1. --port <n> CLI flag (handled by individual commands)
+//   2. CROSSTALK_API_PORT env var
+//   3. Default 7000
+//
+// No auth: the engine binds 127.0.0.1 only and there's no token. Same
+// model as ollama / postgres-on-localhost.
+
+export const DEFAULT_API_PORT = 7000;
+
+export function resolvePort(explicit) {
+  if (typeof explicit === 'number' && Number.isInteger(explicit)) return explicit;
+  const fromEnv = Number(process.env.CROSSTALK_API_PORT);
+  if (Number.isInteger(fromEnv) && fromEnv > 0) return fromEnv;
+  return DEFAULT_API_PORT;
+}
+
+function apiUrl(path, port) {
+  return `http://127.0.0.1:${port}${path}`;
+}
+
+async function parseJsonOrThrow(res) {
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    throw new ApiError(res.status, 'invalid JSON in response');
+  }
+  if (!res.ok) {
+    const msg = body && typeof body.error === 'string' ? body.error : `HTTP ${res.status}`;
+    throw new ApiError(res.status, msg);
+  }
+  return body;
+}
+
+export class ApiError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+export class ConnectError extends Error {
+  constructor(port, cause) {
+    super(
+      `cannot reach crosstalkd on 127.0.0.1:${port} — is the container running? ` +
+      `Try 'crosstalk up' to start it. (underlying: ${cause})`,
+    );
+    this.name = 'ConnectError';
+    this.port = port;
+  }
+}
+
+async function call(method, path, body, opts = {}) {
+  const port = resolvePort(opts.port);
+  const init = {
+    method,
+    headers: body ? { 'Content-Type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  };
+  let res;
+  try {
+    res = await fetch(apiUrl(path, port), init);
+  } catch (err) {
+    throw new ConnectError(port, err.message || String(err));
+  }
+  return parseJsonOrThrow(res);
+}
+
+export const api = {
+  get: (path, opts) => call('GET', path, undefined, opts),
+  post: (path, body, opts) => call('POST', path, body, opts),
+};

package/lib/argv.js

@@ -0,0 +1,28 @@
+// Tiny argv helpers shared across commands. No yargs / commander
+// dependency — the surfaces are simple enough that hand-parsing is
+// shorter than wiring a framework.
+
+export function flag(argv, name) {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+export function has(argv, name) {
+  return argv.includes(name);
+}
+
+// All positional (non-flag) args, skipping flag values.
+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 (valueFlags.has(a)) i++;
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}

package/lib/errors.js

@@ -0,0 +1,19 @@
+// Shared error→stderr formatting for client commands.
+//
+// Pattern: catch known error types (ConnectError, ApiError) and print
+// operator-readable messages with appropriate exit codes. Unknown errors
+// rethrow so they show stack traces — those are real bugs to fix.
+
+import { ApiError, ConnectError } from './api-client.js';
+
+export function reportAndExit(err, contextHint) {
+  if (err instanceof ConnectError) {
+    process.stderr.write(`${contextHint}: ${err.message}\n`);
+    process.exit(4);
+  }
+  if (err instanceof ApiError) {
+    process.stderr.write(`${contextHint}: ${err.message} (HTTP ${err.status})\n`);
+    process.exit(err.status === 400 ? 1 : 3);
+  }
+  throw err;
+}

package/lib/transport.js

@@ -0,0 +1,51 @@
+// transport.js — locate the current Crosstalk transport on the host,
+// derive its conventional names (compose project, container name, etc.).
+//
+// A transport is identified by a CROSSTALK-VERSION file at its root.
+// `crosstalk` walks up from the operator's cwd to find it — same pattern
+// as `git`, `npm`, etc. discovering their root directories.
+
+import { existsSync, statSync } from 'fs';
+import { resolve, basename, dirname, join } from 'path';
+
+export function findTransportRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, 'CROSSTALK-VERSION'))) {
+      try {
+        if (statSync(join(dir, 'CROSSTALK-VERSION')).isFile()) return dir;
+      } catch { /* fall through */ }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function requireTransportRoot(startDir = process.cwd()) {
+  const root = findTransportRoot(startDir);
+  if (!root) {
+    process.stderr.write(
+      `crosstalk: not inside a Crosstalk transport ` +
+      `(no CROSSTALK-VERSION found from ${resolve(startDir)} upward).\n` +
+      `Create one with 'crosstalk init <dir>' or cd into an existing transport.\n`,
+    );
+    process.exit(2);
+  }
+  return root;
+}
+
+// transport-name is the basename of the transport root. Used for the
+// compose project, container name, volume names — gives each transport
+// on a host distinct docker objects without an explicit registry.
+export function transportName(transportRoot) {
+  return basename(transportRoot);
+}
+
+export function containerName(transportRoot) {
+  return `crosstalk-${transportName(transportRoot)}`;
+}
+
+export function composeFile(transportRoot) {
+  return join(transportRoot, 'docker-compose.yml');
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "6.0.0-alpha.9",
-  "description": "Crosstalk runtime — async messaging between agents over git, across machines.",
+  "version": "7.0.0-alpha.1",
+  "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/cordfuse/crosstalk",
@@ -14,26 +14,10 @@
   },
   "files": [
     "bin/",
-    "src/",
-    "template/"
+    "lib/",
+    "commands/",
+    "README.md"
   ],
-  "scripts": {
-    "build": "tsc --noEmit",
-    "lint": "tsc --noEmit",
-    "test": "bun test",
-    "prepack": "cp -r ../transport template",
-    "postpack": "rm -rf template"
-  },
-  "dependencies": {
-    "@cordfuse/turnq": "^0.4.2",
-    "@lydell/node-pty": "^1.2.0-beta.12",
-    "tsx": "^4.20.0",
-    "yaml": "^2.8.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.0",
-    "typescript": "^5.7.0"
-  },
   "engines": {
     "node": ">=20"
   },

package/src/activation.ts

@@ -1,104 +0,0 @@
-// The activation rule — pure functions, no I/O, exhaustively unit-tested.
-//
-// One rule (CROSSTALK.md "Activation"):
-//
-//   A message wakes its addressee if it has no `re:` (a new task), or its
-//   `re:` points at a message the addressee sent.
-//
-// `re:` is written by the runtime at send time, never inferred at read
-// time. It is a string or a list: a reply that answers a batch of N
-// messages records ALL N relPaths, so no answered message is ever lost to
-// batching.
-
-export interface ActivationMessage {
-  from: string;
-  to: string[];
-  re?: string | string[];
-}
-
-export function recipients(toField: unknown): string[] {
-  if (Array.isArray(toField)) return toField.map(String);
-  if (typeof toField === 'string') return [toField];
-  return [];
-}
-
-export function reList(reField: unknown): string[] {
-  if (Array.isArray(reField)) return reField.map(String);
-  if (typeof reField === 'string') return [reField];
-  return [];
-}
-
-// A recipient is `actor` or `actor@host`.
-export function extractActor(recipient: string): string {
-  const at = recipient.indexOf('@');
-  return at === -1 ? recipient : recipient.slice(0, at);
-}
-
-export function targetHost(recipient: string): string | null {
-  const at = recipient.indexOf('@');
-  return at === -1 ? null : recipient.slice(at + 1);
-}
-
-export interface RoutingResult {
-  addressed: boolean;
-  // Actor was named, but every instance targeted a different host — logged
-  // by the dispatcher so wrong-host routes are visible, never silent.
-  wrongHost: boolean;
-}
-
-export function matchRouting(
-  recipientList: string[],
-  actorName: string,
-  thisHost: string,
-): RoutingResult {
-  let actorNamedAtAll = false;
-  for (const r of recipientList) {
-    if (r === 'all') return { addressed: true, wrongHost: false };
-    if (extractActor(r) !== actorName) continue;
-    actorNamedAtAll = true;
-    const host = targetHost(r);
-    if (host === null || host === thisHost) return { addressed: true, wrongHost: false };
-  }
-  return { addressed: false, wrongHost: actorNamedAtAll };
-}
-
-export type WakeDecision = 'wake' | 'skip' | 'wrong-host';
-
-// `senderOf` resolves a channel relPath to the `from:` of the message there,
-// or undefined if no such message exists. A dangling `re:` entry (target
-// missing) wakes the addressee — fail open so a message is never silently
-// dropped; no loop is possible because the reply to it carries a
-// resolvable `re:`.
-export function decideWake(
-  msg: ActivationMessage,
-  actorName: string,
-  thisHost: string,
-  senderOf: (relPath: string) => string | undefined,
-): WakeDecision {
-  const routing = matchRouting(msg.to, actorName, thisHost);
-  if (!routing.addressed) return routing.wrongHost ? 'wrong-host' : 'skip';
-  if (msg.from === actorName) return 'skip';
-  const targets = reList(msg.re);
-  if (targets.length === 0) return 'wake';
-  for (const target of targets) {
-    const asker = senderOf(target);
-    if (asker === undefined || asker === actorName) return 'wake';
-  }
-  return 'skip';
-}
-
-// Split a channel's pending messages (already sorted by relPath) into
-// contiguous batches sized for the actor's concurrency. Contiguous so each
-// batch's highest relPath is monotone across batches — the cursor advances
-// safely per batch. When pending fits within concurrency, every batch is a
-// single message (parallel fan-out); when it exceeds, batches collapse into
-// ~concurrency invocations (fan-in stays O(1) per actor).
-export function splitForConcurrency<T>(msgs: T[], concurrency: number): T[][] {
-  if (concurrency <= 1 || msgs.length <= 1) return [msgs];
-  const chunkSize = Math.max(1, Math.ceil(msgs.length / concurrency));
-  const out: T[][] = [];
-  for (let i = 0; i < msgs.length; i += chunkSize) {
-    out.push(msgs.slice(i, i + chunkSize));
-  }
-  return out;
-}