@cordfuse/crosstalk 5.0.0-alpha.2

package/bin/crosstalk.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// crosstalk — subcommand dispatcher
+//
+// Walks up from cwd to find a Crosstalk transport (identified by
+// upstream/CROSSTALK-VERSION), then execs tsx against the requested
+// subcommand from the runtime's installed source. All args after the
+// subcommand are forwarded.
+//
+// Examples:
+//   crosstalk attach
+//   crosstalk send --to concierge "hello"
+//   crosstalk dlq --show abc123
+//   crosstalk dispatch
+//
+// init is a special case — it can run outside any transport (it CREATES
+// one). All other subcommands require a transport in the cwd tree.
+
+import { existsSync, statSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const SUBCOMMANDS = [
+  'dispatch', 'send', 'wake', 'status', 'init', 'dlq',
+  'open', 'channel', 'chat', 'attach', 'upgrade',
+];
+
+// Subcommands that operate outside an existing transport (they create or
+// inspect from anywhere).
+const STANDALONE_SUBCOMMANDS = new Set(['init']);
+
+function findTransportRoot(startDir) {
+  let dir = resolve(startDir);
+  while (true) {
+    const versionFile = join(dir, 'upstream', 'CROSSTALK-VERSION');
+    if (existsSync(versionFile) && statSync(versionFile).isFile()) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function printUsage(exitCode = 0) {
+  process.stdout.write(
+    `Usage: crosstalk <subcommand> [args...]\n\n` +
+    `Subcommands:\n` +
+    SUBCOMMANDS.map((s) => `  ${s}`).join('\n') +
+    `\n\nMost subcommands require you to be inside a Crosstalk transport\n` +
+    `(a directory containing upstream/CROSSTALK-VERSION). 'init' can run\n` +
+    `from anywhere to scaffold a new transport.\n`,
+  );
+  process.exit(exitCode);
+}
+
+const argv = process.argv.slice(2);
+
+if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') {
+  printUsage(0);
+}
+
+const subcommand = argv[0];
+const forwardArgs = argv.slice(1);
+
+if (!SUBCOMMANDS.includes(subcommand)) {
+  process.stderr.write(
+    `crosstalk: unknown subcommand '${subcommand}'.\n` +
+    `Available: ${SUBCOMMANDS.join(', ')}\n`,
+  );
+  process.exit(2);
+}
+
+// Resolve the runtime's source directory (sibling of bin/, both inside
+// the installed @cordfuse/crosstalk package).
+const binDir = dirname(fileURLToPath(import.meta.url));
+const runtimeRoot = dirname(binDir);
+const toolPath = join(runtimeRoot, 'src', `${subcommand}.ts`);
+
+if (!existsSync(toolPath)) {
+  process.stderr.write(
+    `crosstalk: tool source not found at ${toolPath}.\n` +
+    `The @cordfuse/crosstalk installation may be corrupted; try reinstalling.\n`,
+  );
+  process.exit(2);
+}
+
+// For non-standalone subcommands, locate the transport in the cwd tree.
+let workingDir = process.cwd();
+if (!STANDALONE_SUBCOMMANDS.has(subcommand)) {
+  const transportRoot = findTransportRoot(process.cwd());
+  if (!transportRoot) {
+    process.stderr.write(
+      `crosstalk: no transport found in current directory tree.\n` +
+      `Run from inside a directory containing upstream/CROSSTALK-VERSION,\n` +
+      `or use 'crosstalk init <name>' to scaffold a new transport.\n`,
+    );
+    process.exit(2);
+  }
+  workingDir = transportRoot;
+}
+
+// Strip a single leading `--` separator if present (legacy npm run X -- ergonomics).
+const cleanedArgs = forwardArgs[0] === '--' ? forwardArgs.slice(1) : forwardArgs;
+
+const result = spawnSync('npx', ['tsx', toolPath, ...cleanedArgs], {
+  cwd: workingDir,
+  stdio: 'inherit',
+});
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@cordfuse/crosstalk",
+  "version": "5.0.0-alpha.2",
+  "description": "Crosstalk runtime — async messaging between agents over git. The crosstalk CLI plus dispatch, send, attach, chat, and supporting tools.",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/cordfuse/crosstalk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cordfuse/crosstalk.git"
+  },
+  "bin": {
+    "crosstalk": "./bin/crosstalk.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/"
+  ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "echo 'No tests yet'"
+  },
+  "dependencies": {
+    "@cordfuse/turnq": "^0.3.4",
+    "@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"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "messaging",
+    "git",
+    "crosstalk",
+    "cordfuse"
+  ]
+}

package/src/actor.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { hostname as osHostname } from 'os';
+import { parseFrontmatter } from './frontmatter.js';
+
+export interface HostActorTier {
+  cli: string;
+  count?: number;
+  systemPromptFile?: string;
+}
+
+export type HostActorTiers = Record<string, HostActorTier | string>;
+
+export interface HostFile {
+  alias: string;
+  hostname?: string;
+  actors: Record<string, HostActorTiers>;
+}
+
+export interface ActorProfile {
+  name: string;
+  systemPrompt: string;
+}
+
+export function findHostFile(transportRoot: string, override?: string): HostFile {
+  const dir = join(transportRoot, 'hosts');
+  if (!existsSync(dir)) {
+    throw new Error(`No host directory at ${dir}`);
+  }
+  const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+  if (files.length === 0) {
+    throw new Error(`No host files in ${dir}`);
+  }
+  if (override) {
+    const target = files.find((f) => f.replace(/\.md$/, '') === override);
+    if (!target) throw new Error(`Host file '${override}' not found in ${dir}`);
+    return parseHostFile(join(dir, target));
+  }
+  const hostName = osHostname();
+  for (const f of files) {
+    const parsed = parseHostFile(join(dir, f));
+    if (parsed.hostname === hostName || parsed.alias === hostName) return parsed;
+  }
+  throw new Error(
+    `No host file matches hostname '${hostName}' in ${dir}. ` +
+      `Pass --host <alias> to override.`,
+  );
+}
+
+function parseHostFile(path: string): HostFile {
+  const raw = readFileSync(path, 'utf-8');
+  const { data } = parseFrontmatter<HostFile>(raw);
+  if (!data.alias) throw new Error(`Host file ${path} missing 'alias' field`);
+  if (!data.actors) throw new Error(`Host file ${path} missing 'actors' field`);
+  return data;
+}
+
+export function loadActorProfile(transportRoot: string, name: string): ActorProfile {
+  const candidates = [
+    join(transportRoot, 'local', 'actors', `${name}.md`),
+    join(transportRoot, 'upstream', 'actors', `${name}.md`),
+  ];
+  const path = candidates.find((p) => existsSync(p));
+  if (!path) {
+    throw new Error(
+      `Actor profile not found for '${name}'. Looked in:\n  ${candidates.join('\n  ')}`,
+    );
+  }
+  const raw = readFileSync(path, 'utf-8');
+  const { body } = parseFrontmatter(raw);
+  return { name, systemPrompt: body.trim() };
+}
+
+// Quote-aware tokenizer for CLI strings. Splits on whitespace but treats
+// "double-quoted" and 'single-quoted' segments as single tokens. Adequate
+// for `bash -c "cmd; cmd"` and similar; does not implement shell escape
+// sequences (operators who need those can use cli as a string[] in YAML
+// once we support that, or write a wrapper script).
+export function tokenizeCli(cli: string): string[] {
+  const tokens: string[] = [];
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(cli)) !== null) {
+    const tok = m[1] ?? m[2] ?? m[3] ?? '';
+    tokens.push(tok);
+  }
+  return tokens;
+}
+
+export function pickTier(
+  tiers: HostActorTiers,
+  preferred?: string,
+): { tier: string; cli: string } {
+  if (preferred && tiers[preferred] !== undefined) {
+    const value = tiers[preferred];
+    const cli = typeof value === 'string' ? value : value.cli;
+    if (cli) return { tier: preferred, cli };
+    // declared but cli missing — fall through to first-tier fallback
+  }
+  const entries = Object.entries(tiers);
+  if (entries.length === 0) throw new Error('No tiers defined for actor');
+  const [tier, value] = entries[0];
+  const cli = typeof value === 'string' ? value : value.cli;
+  if (!cli) throw new Error(`Tier '${tier}' has no cli command`);
+  return { tier, cli };
+}

package/src/attach.ts

@@ -0,0 +1,118 @@
+// crosstalk attach — pty-wrap an agent CLI in operator mode
+//
+// Spawns the operator's preferred agent CLI inside a pseudo-terminal,
+// preloading OPERATOR.md as system context so the agent acts as the
+// operator's natural-language interface to this Crosstalk transport.
+//
+// The CLI thinks it's running natively — its TUI features (slash commands,
+// autocompletion, syntax highlighting) all work because it has a real
+// (virtual) terminal underneath. The wrapper just forwards bytes both ways
+// and handles terminal resize.
+//
+// Usage:
+//   crosstalk attach
+//   CROSSTALK_OPERATOR_CLI="claude --append-system-prompt" crosstalk attach
+//   CROSSTALK_OPERATOR_CLI="gemini -i" crosstalk attach
+//   CROSSTALK_OPERATOR_CLI="agy -i" crosstalk attach
+//
+// CROSSTALK_OPERATOR_CLI is the full agent invocation including the
+// system-prompt-equivalent flag. OPERATOR.md content is appended as the
+// final argument. Defaults to `claude --append-system-prompt`.
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve, join } from 'path';
+import { spawn as ptySpawn } from '@lydell/node-pty';
+import { tokenizeCli } from './actor.js';
+
+const transportRoot = resolve(process.cwd());
+const operatorMdPath = join(transportRoot, 'upstream', 'OPERATOR.md');
+
+if (!existsSync(operatorMdPath)) {
+  console.error(`crosstalk attach: OPERATOR.md not found at ${operatorMdPath}`);
+  console.error(`This tool requires upstream/OPERATOR.md to be present.`);
+  process.exit(1);
+}
+
+const operatorContent = readFileSync(operatorMdPath, 'utf-8').trim();
+const cliCommand = process.env['CROSSTALK_OPERATOR_CLI'] ?? 'claude --append-system-prompt';
+const parts = tokenizeCli(cliCommand);
+
+if (parts.length === 0) {
+  console.error('crosstalk attach: CROSSTALK_OPERATOR_CLI is empty');
+  process.exit(1);
+}
+
+const [bin, ...flagArgs] = parts;
+const args = [...flagArgs, operatorContent];
+
+const cols = process.stdout.columns ?? 80;
+const rows = process.stdout.rows ?? 24;
+
+process.stdout.write(`crosstalk: attaching to ${bin} (operator mode)\n`);
+
+let term;
+try {
+  term = ptySpawn(bin, args, {
+    name: process.env['TERM'] ?? 'xterm-256color',
+    cols,
+    rows,
+    cwd: transportRoot,
+    env: process.env as Record<string, string>,
+  });
+} catch (err) {
+  console.error(
+    `crosstalk attach: failed to launch '${bin}': ${(err as Error).message}`,
+  );
+  console.error(
+    `Check that '${bin}' is installed and on your PATH. Override with` +
+      ` CROSSTALK_OPERATOR_CLI to use a different CLI.`,
+  );
+  process.exit(1);
+}
+
+const startedAt = Date.now();
+let turnCount = 0;
+
+if (process.stdin.isTTY) {
+  process.stdin.setRawMode(true);
+}
+process.stdin.resume();
+
+process.stdin.on('data', (data) => {
+  term.write(data.toString());
+  if (data.includes(0x0d) || data.includes(0x0a)) turnCount++;
+});
+
+term.onData((data) => {
+  process.stdout.write(data);
+});
+
+const handleResize = () => {
+  try {
+    term.resize(process.stdout.columns ?? cols, process.stdout.rows ?? rows);
+  } catch {
+    /* term may have exited */
+  }
+};
+process.stdout.on('resize', handleResize);
+
+const cleanup = (exitCode: number) => {
+  if (process.stdin.isTTY) {
+    try { process.stdin.setRawMode(false); } catch { /* ignore */ }
+  }
+  process.stdin.pause();
+  const seconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+  process.stdout.write(
+    `\ncrosstalk: session ended (${turnCount} turns, ${seconds}s active)\n`,
+  );
+  process.exit(exitCode);
+};
+
+term.onExit(({ exitCode }) => cleanup(exitCode ?? 0));
+
+const forwardSignal = (sig: 'SIGINT' | 'SIGTERM' | 'SIGHUP') => {
+  try { term.kill(sig); } catch { /* term may already be gone */ }
+};
+process.on('SIGINT', () => forwardSignal('SIGINT'));
+process.on('SIGTERM', () => forwardSignal('SIGTERM'));
+process.on('SIGHUP', () => forwardSignal('SIGHUP'));

package/src/channel.ts

@@ -0,0 +1,62 @@
+import { mkdirSync, writeFileSync, existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { randomUUID } from 'crypto';
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+const name = flag('--name');
+const parent = flag('--parent');
+const createdBy = flag('--created-by') ?? process.env.USER ?? 'operator';
+
+if (!name) {
+  console.error(
+    'Usage: npm run channel -- --name <name> [--parent <parent-uuid>] [--created-by <name>]',
+  );
+  process.exit(1);
+}
+
+const uuid = randomUUID();
+const dir = join(transportRoot, 'data', 'channels', uuid);
+
+if (existsSync(dir)) {
+  console.error(`Directory already exists: ${dir}`);
+  process.exit(1);
+}
+
+mkdirSync(dir, { recursive: true });
+
+const frontmatter: Record<string, unknown> = {
+  name,
+  created_by: createdBy,
+  created_at: new Date().toISOString(),
+};
+if (parent) frontmatter.parent = parent;
+
+const lines = ['---'];
+for (const [k, v] of Object.entries(frontmatter)) {
+  lines.push(`${k}: ${v}`);
+}
+lines.push('---');
+lines.push('');
+lines.push(`# ${name}`);
+lines.push('');
+if (parent) {
+  lines.push(`Subchannel of \`${parent}\`.`);
+} else {
+  lines.push('Channel description goes here.');
+}
+lines.push('');
+
+writeFileSync(join(dir, 'CHANNEL.md'), lines.join('\n'));
+
+console.log(`Created channel: ${uuid}`);
+console.log(`  name: ${name}`);
+if (parent) console.log(`  parent: ${parent}`);
+console.log(`  path: data/channels/${uuid}/CHANNEL.md`);

package/src/chat.ts

@@ -0,0 +1,203 @@
+// Participate in a crosstalk channel as a regular human, without
+// invoking any agent CLI locally. Sends messages by writing + committing
+// + pushing to the channel; polls the channel for replies addressed to
+// the operator; displays them.
+//
+// Use this when a deployed crosstalk-server (or any other dispatcher) is
+// running against the transport and you want to chat with the dispatched
+// actors from a clean local clone. No Claude install needed locally, no
+// OAuth, no docker exec.
+//
+// Difference from `open`:
+//   - `open` spawns the actor's CLI LOCALLY — needs claude/etc. installed,
+//     needs auth, doesn't use any remote dispatcher.
+//   - `chat` just produces messages and waits for the channel to fill in
+//     replies. Whatever's processing the channel (a container, a remote
+//     dispatcher, a peer) handles the work.
+//
+// Usage:
+//   npm run chat -- --channel <uuid> --to <actor> [--as <name>] [--tier <name>]
+//   npm run chat -- --channel <uuid> --to concierge --as steve
+
+import { resolve, join } from 'path';
+import { mkdirSync, writeFileSync, readdirSync, readFileSync, statSync, existsSync } from 'fs';
+import { createInterface } from 'readline/promises';
+import { spawnSync } from 'child_process';
+import { now, messageFilename } from './filenames.js';
+import { serializeFrontmatter, parseFrontmatter } from './frontmatter.js';
+import { gitCommitAndPush, writeErrorLog } from './transport.js';
+import { withLock } from './turnq.js';
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+const channelUuid = flag('--channel');
+const toActor = flag('--to');
+const fromName = flag('--as') ?? process.env.USER ?? 'steve';
+const tier = flag('--tier');
+const pollSeconds = Number(flag('--poll')) || 5;
+const replyTimeoutSeconds = Number(flag('--timeout')) || 600;
+
+if (!channelUuid || !toActor) {
+  console.error(
+    'Usage: npm run chat -- --channel <uuid> --to <actor> [--as <name>] [--tier <name>] [--poll <seconds>] [--timeout <seconds>]',
+  );
+  process.exit(1);
+}
+
+interface ScannedMessage {
+  relPath: string;
+  ts: number;
+  from: string;
+  to: string[];
+  type: string;
+  body: string;
+}
+
+function recipients(toField: unknown): string[] {
+  if (Array.isArray(toField)) return toField.map(String);
+  if (typeof toField === 'string') return [toField];
+  return [];
+}
+
+function scanChannelMessages(): ScannedMessage[] {
+  const channelDir = join(transportRoot, 'data', 'channels', channelUuid!);
+  if (!existsSync(channelDir)) return [];
+  const results: ScannedMessage[] = [];
+  const walk = (dir: string, prefix: string): void => {
+    let entries: string[];
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const entry of entries) {
+      const full = join(dir, entry);
+      const rel = prefix ? `${prefix}/${entry}` : entry;
+      let stat;
+      try { stat = statSync(full); } catch { continue; }
+      if (stat.isDirectory()) {
+        walk(full, rel);
+      } else if (entry.endsWith('.md') && entry !== 'CHANNEL.md') {
+        try {
+          const raw = readFileSync(full, 'utf-8');
+          const { data, body } = parseFrontmatter(raw);
+          const from = typeof data.from === 'string' ? data.from : '';
+          const type = typeof data.type === 'string' ? data.type : '';
+          const timestamp = typeof data.timestamp === 'string' ? data.timestamp : '';
+          if (!from || !type || !timestamp) continue;
+          results.push({
+            relPath: rel,
+            ts: new Date(timestamp).getTime(),
+            from,
+            to: recipients(data.to),
+            type,
+            body,
+          });
+        } catch { /* skip unparseable */ }
+      }
+    }
+  };
+  walk(channelDir, '');
+  return results.sort((a, b) => a.ts - b.ts);
+}
+
+function gitPullQuiet(): boolean {
+  const r = spawnSync('git', ['pull', '--rebase', '--quiet'], {
+    cwd: transportRoot,
+    encoding: 'utf-8',
+  });
+  return r.status === 0;
+}
+
+async function sendMessage(body: string): Promise<void> {
+  await withLock('dispatch', async () => {
+    const ts = now();
+    const dir = join(transportRoot, 'data', 'channels', channelUuid!, ts.pathDate);
+    mkdirSync(dir, { recursive: true });
+    const frontmatter: Record<string, unknown> = {
+      from: fromName,
+      to: toActor!,
+      type: 'text',
+      timestamp: ts.iso,
+    };
+    if (tier) frontmatter.tier = tier;
+    const content = serializeFrontmatter(frontmatter, body);
+    writeFileSync(join(dir, messageFilename(ts)), content);
+
+    const r = gitCommitAndPush(
+      transportRoot,
+      `chat: ${fromName} -> ${toActor} in ${channelUuid!.slice(0, 8)}`,
+    );
+    if (!r.ok && r.error) {
+      const kind = r.committed ? 'git_push' : 'git_commit';
+      writeErrorLog(transportRoot, kind, r.error);
+      console.error(`(${kind} failed: ${r.error.slice(0, 120)} — message is local-only)`);
+    }
+  });
+}
+
+async function waitForReplyAfter(thresholdTs: number): Promise<ScannedMessage | null> {
+  const deadline = Date.now() + replyTimeoutSeconds * 1_000;
+  while (Date.now() < deadline) {
+    gitPullQuiet();
+    const messages = scanChannelMessages();
+    const reply = messages.find(
+      (m) =>
+        m.ts > thresholdTs &&
+        m.type === 'text' &&
+        m.from === toActor &&
+        m.to.includes(fromName),
+    );
+    if (reply) return reply;
+    await new Promise((r) => setTimeout(r, pollSeconds * 1_000));
+  }
+  return null;
+}
+
+async function main(): Promise<void> {
+  console.log(
+    `crosstalk chat — channel=${channelUuid!.slice(0, 8)} from=${fromName} to=${toActor}`,
+  );
+  console.log(
+    'Type a message and press Enter. Replies will appear after the dispatcher processes them.',
+  );
+  console.log('Ctrl-C or Ctrl-D to exit.');
+  console.log('');
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    while (true) {
+      let userMsg: string;
+      try {
+        userMsg = await rl.question(`${fromName}> `);
+      } catch {
+        break;
+      }
+      if (userMsg === undefined || userMsg === null) break;
+      const trimmed = userMsg.trim();
+      if (!trimmed) continue;
+
+      const sentAt = Date.now();
+      await sendMessage(trimmed);
+      process.stdout.write(`(waiting for ${toActor}…) `);
+
+      const reply = await waitForReplyAfter(sentAt);
+      if (!reply) {
+        console.log(
+          `\n(no reply within ${replyTimeoutSeconds}s — give up and try again, or check dispatch state)\n`,
+        );
+        continue;
+      }
+      process.stdout.write('\r' + ' '.repeat(40) + '\r');
+      console.log(`${toActor}> ${reply.body}\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+main();

package/src/cursor.ts

@@ -0,0 +1,48 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { writeErrorLog } from './transport.js';
+
+// Cursor format mirrors message relPath from filenames.ts:
+//   YYYY/MM/DD/HHMMSSmmmZ-<8hex>.md
+const VALID_CURSOR = /^\d{4}\/\d{2}\/\d{2}\/\d{6}\d{3}Z-[0-9a-f]{8}\.md$/;
+
+export function cursorPath(transportRoot: string, actor: string, channelUuid: string): string {
+  return join(transportRoot, 'cursors', actor, `${channelUuid}.md`);
+}
+
+export function readCursor(transportRoot: string, actor: string, channelUuid: string): string | null {
+  const p = cursorPath(transportRoot, actor, channelUuid);
+  if (!existsSync(p)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(p, 'utf-8').trim();
+  } catch (err) {
+    writeErrorLog(
+      transportRoot,
+      'fs',
+      `cursor read failed for ${actor}@${channelUuid}: ${(err as Error).message}`,
+    );
+    return null;
+  }
+  if (raw.length === 0) return null;
+  if (!VALID_CURSOR.test(raw)) {
+    writeErrorLog(
+      transportRoot,
+      'parse',
+      `cursor file for ${actor}@${channelUuid} contains invalid value '${raw.slice(0, 80)}' — treating as null (will re-scan from start)`,
+    );
+    return null;
+  }
+  return raw;
+}
+
+export function writeCursor(
+  transportRoot: string,
+  actor: string,
+  channelUuid: string,
+  relPath: string,
+): void {
+  const p = cursorPath(transportRoot, actor, channelUuid);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, relPath + '\n');
+}