@cordfuse/crosstalk 5.0.0-alpha.3 → 5.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "5.0.0-alpha.3",
+  "version": "5.0.0-alpha.5",
   "description": "Crosstalk runtime — async messaging between agents over git. The crosstalk CLI plus dispatch, send, attach, chat, and supporting tools.",
   "type": "module",
   "license": "MIT",

package/src/chat.ts

@@ -25,7 +25,7 @@ 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 { gitCommitAndPush } from './transport.js';
 import { withLock } from './turnq.js';
 
 const transportRoot = resolve(process.cwd());
@@ -132,9 +132,11 @@ async function sendMessage(body: string): Promise<void> {
       `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)`);
+      // Same anti-pattern as send.ts: writing to errors/ from an operator-
+      // side command dirties the working tree and breaks subsequent
+      // git pull --rebase. Stay on stderr only.
+      const kind = r.committed ? 'push' : 'commit';
+      console.error(`(${kind} failed: ${r.error.slice(0, 200)} — message is local-only)`);
     }
   });
 }

package/src/dispatch.ts

@@ -1,4 +1,4 @@
-import { resolve, join } from 'path';
+import { resolve, join, dirname } from 'path';
 import { spawn } from 'child_process';
 import {
   mkdirSync,
@@ -10,6 +10,21 @@ import {
   closeSync,
 } from 'fs';
 import { watch } from 'fs/promises';
+import { fileURLToPath } from 'url';
+
+// Read runtime version from the installed package's package.json at startup
+// so dispatch_start logs and heartbeat content always match the actual
+// installed @cordfuse/crosstalk version. Avoids hand-editing on every release.
+const RUNTIME_VERSION: string = (() => {
+  try {
+    const thisFileDir = dirname(fileURLToPath(import.meta.url));
+    const pkgPath = join(thisFileDir, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: string };
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+})();
 import {
   findHostFile,
   loadActorProfile,
@@ -53,6 +68,16 @@ const logFile = flag('--log-file');
 const MAX_BACKOFF_MULTIPLIER = 10; // cap: pollSeconds * 10
 const BACKOFF_GRACE = 2; // first N failures don't trigger backoff
 
+// Per-tick heal: when N consecutive infra failures pile up, the dispatch
+// loop is stuck in a deadlock that entrypoint's boot-time auto-recovery
+// can't break (because dispatch is already running). At HEAL_THRESHOLD
+// consecutive failures, attempt a `git fetch && reset --hard origin/<branch>
+// && clean -fd` from inside the tick loop. Mirrors the entrypoint logic.
+// Throttled — won't reattempt until fully BACKOFF_GRACE+HEAL_THRESHOLD more
+// failures pile up after a heal, to avoid heal-loop-storms.
+const HEAL_THRESHOLD = 5;
+let lastHealAtFailureCount = 0;
+
 // Stale-read-receipt sweep config — runs at most every SWEEP_INTERVAL_MS
 // of wall-clock to surface read receipts that never produced a reply
 // (indicates dispatch crashed mid-tick or CLI hung silently).
@@ -80,7 +105,7 @@ function writeHeartbeat(): void {
   try {
     const dir = join(transportRoot, '.turnq');
     mkdirSync(dir, { recursive: true });
-    const data = { ts: new Date().toISOString(), pid: process.pid, version: '5.0.0-alpha.3' };
+    const data = { ts: new Date().toISOString(), pid: process.pid, version: RUNTIME_VERSION };
     writeFileSync(join(dir, 'heartbeat'), JSON.stringify(data) + '\n');
   } catch { /* best-effort */ }
 }
@@ -330,8 +355,13 @@ async function dispatchTick(): Promise<TickResult> {
 
     const pullResult = gitPull(transportRoot);
     if (!pullResult.ok && pullResult.error) {
-      const errId = writeErrorLog(transportRoot, 'git_pull', pullResult.error);
-      log('git_pull_failed', { error_id: errId, error: pullResult.error.slice(0, 120) });
+      // Note: deliberately NOT calling writeErrorLog here. Repeated pull
+      // failures (deadlock loop) would otherwise write a new errors/*.md
+      // every tick, which dispatch then has to commit, which the next
+      // pull then chokes on — a positive feedback that contributed to
+      // the alpha.3/alpha.4 Mac UAT wedge. The structured log line below
+      // gives operators full diagnostic info via stdout/json logs.
+      log('git_pull_failed', { error: pullResult.error.slice(0, 200) });
       infraOk = false;
     }
 
@@ -420,12 +450,14 @@ async function dispatchTick(): Promise<TickResult> {
       : `dispatch: cursor advance ${new Date().toISOString()}`;
     const pushResult = gitCommitAndPush(transportRoot, commitMsg);
     if (!pushResult.ok && pushResult.error) {
+      // Same rationale as the pull case above: no writeErrorLog.
+      // Repeated push failures shouldn't flood errors/ since that
+      // contributes to the same git-deadlock-feedback that pull does.
       const kind = pushResult.committed ? 'git_push' : 'git_commit';
-      const errId = writeErrorLog(transportRoot, kind, pushResult.error);
       log('git_push_failed', {
-        error_id: errId,
+        kind,
         committed_locally: pushResult.committed,
-        error: pushResult.error.slice(0, 120),
+        error: pushResult.error.slice(0, 200),
       });
       infraOk = false;
     }
@@ -467,7 +499,7 @@ async function waitForWakeOrTimeout(ms: number): Promise<'wake' | 'timeout'> {
 async function main(): Promise<void> {
   log('dispatch_start', {
     transport: transportRoot,
-    version: '5.0.0-alpha.3',
+    version: RUNTIME_VERSION,
     log_file: logFile ?? null,
   });
   if (onceMode) {
@@ -501,6 +533,43 @@ async function main(): Promise<void> {
         });
       }
 
+      // Per-tick heal: deadlock-break when the dispatch loop has been
+      // failing for HEAL_THRESHOLD consecutive ticks AND we haven't healed
+      // recently. Hard-resets the working tree to origin/<current branch>.
+      // Trades any uncommitted local state for forward progress — acceptable
+      // because messages/cursors/dlq are pulled back from origin and
+      // .turnq/errors are regenerated.
+      if (
+        consecutiveInfraFailures >= HEAL_THRESHOLD &&
+        consecutiveInfraFailures - lastHealAtFailureCount >= HEAL_THRESHOLD
+      ) {
+        try {
+          const branchProc = spawn('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            cwd: transportRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+          });
+          let branchName = '';
+          branchProc.stdout.on('data', (d) => { branchName += d.toString(); });
+          await new Promise<void>((res) => branchProc.on('close', () => res()));
+          const branch = branchName.trim() || 'main';
+          log('per_tick_heal_start', {
+            consecutive_failures: consecutiveInfraFailures,
+            target: `origin/${branch}`,
+          });
+          await new Promise<void>((res) => {
+            const p = spawn('sh', [
+              '-c',
+              `git rebase --abort 2>/dev/null; git fetch --quiet origin '${branch}' && git reset --hard --quiet 'origin/${branch}' && git clean -fdq`,
+            ], { cwd: transportRoot, stdio: 'inherit' });
+            p.on('close', () => res());
+          });
+          log('per_tick_heal_done', { target: `origin/${branch}` });
+          lastHealAtFailureCount = consecutiveInfraFailures;
+        } catch (err) {
+          log('per_tick_heal_failed', { error: (err as Error).message });
+        }
+      }
+
       if (r.didWork) {
         await new Promise((res) => setTimeout(res, 1_000 * backoffFactor));
       } else {

package/src/send.ts

@@ -2,7 +2,7 @@ import { resolve, join } from 'path';
 import { mkdirSync, writeFileSync } from 'fs';
 import { now, messageFilename } from './filenames.js';
 import { serializeFrontmatter } from './frontmatter.js';
-import { gitCommitAndPush, writeErrorLog } from './transport.js';
+import { gitCommitAndPush } from './transport.js';
 import { withLock } from './turnq.js';
 
 const transportRoot = resolve(process.cwd());
@@ -60,16 +60,19 @@ async function main(): Promise<void> {
     }
 
     if (!pushResult.ok && pushResult.error) {
-      const kind = pushResult.committed ? 'git_push' : 'git_commit';
-      const errId = writeErrorLog(transportRoot, kind, pushResult.error);
+      // Note: deliberately NOT writing to errors/. That directory is dispatcher-
+      // owned state, and operator-side writes from `crosstalk send` were
+      // dirtying the working tree, causing subsequent `git pull --rebase` to
+      // fail with "unstaged changes". Surface the error to stderr only.
+      const kind = pushResult.committed ? 'push' : 'commit';
       console.error(`Wrote locally: ${join(ts.pathDate, filename)}`);
-      console.error(
-        `but git ${kind === 'git_push' ? 'push' : 'commit'} FAILED (errors/${errId}.md):`,
-      );
-      console.error(`  ${pushResult.error.slice(0, 200)}`);
-      console.error(
-        '  Message is in your local clone but not on origin. Resolve the git issue and re-push manually.',
-      );
+      console.error(`but git ${kind} FAILED:`);
+      console.error(`  ${pushResult.error.slice(0, 300)}`);
+      console.error('');
+      console.error('Your message is in your local clone but not on origin.');
+      console.error('Recover with:');
+      console.error('  git pull --rebase');
+      console.error('  git push');
       process.exit(3);
     }
 

package/src/transport.ts

@@ -70,13 +70,40 @@ export function gitCommitAndPush(transportRoot: string, message: string): GitPus
     return { ok: true, committed: false, pushed: false };
   }
 
-  const add = captureGit(transportRoot, ['add', '-A']);
-  if (add.status !== 0) {
+  // Stage everything EXCEPT .turnq/ (machine-local runtime state; commits of
+  // this directory cause modify/delete conflicts the moment another clone
+  // untracks it via gitignore). Pathspec exclusion is independent of the
+  // transport's .gitignore — defensive against gitignore drift.
+  //
+  // Edge: `git add -A . :(exclude).turnq` exits non-zero with "The following
+  // paths are ignored by one of your .gitignore files: .turnq" because the
+  // exclude pathspec itself matches a gitignored path. The add still stages
+  // every other change correctly — only the exit code is misleading. So we
+  // treat that specific failure-pattern as benign and let the subsequent
+  // commit step decide whether anything actually got staged.
+  const add = captureGit(transportRoot, ['add', '-A', '.', ':(exclude).turnq']);
+  const addBenignIgnoredPath = add.status !== 0 &&
+                                /paths are ignored/.test(add.stderr);
+  if (add.status !== 0 && !addBenignIgnoredPath) {
     return { ok: false, committed: false, pushed: false, error: add.stderr.trim().slice(0, 500) };
   }
 
+  // If .turnq/ was previously committed (pre-alpha.4 transport), the index
+  // may still hold tracked .turnq/* entries. Untrack them here so subsequent
+  // pulls don't fight with operator clones that have untracked .turnq/. This
+  // is a one-time-per-transport heal; on a clean transport it's a no-op.
+  const indexedTurnq = captureGit(transportRoot, ['ls-files', '.turnq']);
+  if (indexedTurnq.status === 0 && indexedTurnq.stdout.trim().length > 0) {
+    captureGit(transportRoot, ['rm', '-r', '--cached', '--quiet', '.turnq']);
+  }
+
   const commit = captureGit(transportRoot, ['commit', '-m', message]);
   if (commit.status !== 0) {
+    // Empty commit ("nothing to commit") is fine — the exclusion may have
+    // dropped the only change. Treat exit-1 with no error text as no-op.
+    const noop = commit.stdout.includes('nothing to commit') ||
+                 commit.stderr.includes('nothing to commit');
+    if (noop) return { ok: true, committed: false, pushed: false };
     return { ok: false, committed: false, pushed: false, error: commit.stderr.trim().slice(0, 500) };
   }
 

package/template/upstream/PROTOCOL.md

@@ -54,13 +54,13 @@ If you are *authoring* an actor profile for a compute role, write the system pro
 
 ## Available tools
 
-You have shell access. You can invoke these tools any time you decide they help with your reply. All of them run from the transport root (the current working directory). The tools are documented here so you can pick the right one from natural-language intent — e.g. "check what the dispatch state looks like" → `npm run status`.
+You have shell access. You can invoke these tools any time you decide they help with your reply. All of them run from the transport root (the current working directory). The tools are documented here so you can pick the right one from natural-language intent — e.g. "check what the dispatch state looks like" → `crosstalk status`.
 
 ### `send` — initiate a message to another actor
 
 Use this when you want to **proactively** message someone, not just reply to the prompt you're processing. (If you only want to reply to what you received, just answer — do not call `send`.)
 
-    npm run send -- --channel <channel-uuid> --to <actor> [--from <your-name>] [--tier <tier-name>] "<message body>"
+    crosstalk send --channel <channel-uuid> --to <actor> [--from <your-name>] [--tier <tier-name>] "<message body>"
 
 `send` also pokes dispatch to tick immediately so the recipient sees the message right away.
 
@@ -70,13 +70,13 @@ Use this when you want to **proactively** message someone, not just reply to the
 
 Use this to bypass the quiet-poll interval. Rarely needed manually — `send` already pokes dispatch automatically. Use this if you've directly written a message file and want dispatch to notice it now.
 
-    npm run wake
+    crosstalk wake
 
 ### `status` — inspect transport state
 
 Use this when an operator asks "what's happening?" or before deciding whether to retry something.
 
-    npm run status
+    crosstalk status
 
 Outputs: host file summary, per-actor cursors, turnq lock state, channel list with message counts, DLQ entry count.
 
@@ -89,24 +89,24 @@ Use this when you want to inspect or retry failures. DLQ entries have one of two
 
 Entries also carry an `attempts` count and a `quarantined: true|false` flag. If the same failure repeats 4+ times within an hour, the entry is quarantined: dispatch starts skipping that message (for `dispatch` kind) or that actor (for `config` kind). The retry command clears the quarantine and lets the next dispatch tick try again.
 
-    npm run dlq                       # same as --list
-    npm run dlq -- --list             # list all DLQ entries (incl. quarantine markers + counts by kind)
-    npm run dlq -- --show <id>        # show full details of one entry
-    npm run dlq -- --retry <id>       # for dispatch: rewind cursor; for config: clear quarantine
-    npm run dlq -- --clear            # delete all entries (destructive)
+    crosstalk dlq                       # same as --list
+    crosstalk dlq --list             # list all DLQ entries (incl. quarantine markers + counts by kind)
+    crosstalk dlq --show <id>        # show full details of one entry
+    crosstalk dlq --retry <id>       # for dispatch: rewind cursor; for config: clear quarantine
+    crosstalk dlq --clear            # delete all entries (destructive)
 
 ### `init` — scaffold a new transport
 
 Use this only when an operator is setting up a fresh transport directory. Creates a default host file (for the current hostname), a `general` channel, and the empty `custom/actors/`, `cursors/`, and `dlq/` directories.
 
-    npm run init
-    npm run init -- --force          # overwrite existing files
+    crosstalk init
+    crosstalk init --force          # overwrite existing files
 
 ### `channel` — create a new channel or subchannel
 
 Use this when you want to spin up a new conversation space — either a top-level channel or a focused subchannel of an existing one. Generates a UUID and writes `data/channels/<uuid>/CHANNEL.md`.
 
-    npm run channel -- --name <name> [--parent <parent-uuid>] [--created-by <name>]
+    crosstalk channel --name <name> [--parent <parent-uuid>] [--created-by <name>]
 
 Prints the new channel UUID. Use that UUID in subsequent `send` calls.
 
@@ -146,7 +146,7 @@ There are two persistent failure logs in the transport:
 - **`dlq/`** — failed dispatches and config errors. Per-message and per-actor. Use the `dlq` tool to inspect/retry.
 - **`errors/`** — infrastructure failures (git pull/push/commit, filesystem, message parse). Deduped by signature with a `count` field. If you see something not working as expected (replies aren't reaching origin, dispatch keeps reporting `skip_tick_locked`, etc.), check this directory — operator hostile state often surfaces here first.
 
-`npm run status` shows counts for both at a glance, plus a **dispatch heartbeat** line — the timestamp of the most recent tick. If the heartbeat is fresh (under 2 min old), dispatch is running. If stale (over 5 min), dispatch has stopped or hung; check `errors/` and the process state.
+`crosstalk status` shows counts for both at a glance, plus a **dispatch heartbeat** line — the timestamp of the most recent tick. If the heartbeat is fresh (under 2 min old), dispatch is running. If stale (over 5 min), dispatch has stopped or hung; check `errors/` and the process state.
 
 **Persistent infrastructure failures trigger exponential backoff.** After 2+ consecutive ticks with failed git pull or push, dispatch doubles its poll interval each tick, capped at 10× the configured quiet poll. The `backoff_active` log event fires when active; `backoff_cleared` fires when a tick succeeds again.
 
@@ -177,4 +177,4 @@ For idempotent work (information lookup, calculation, advice), duplicates are ha
 - **Do not modify `errors/` directly.** Same reasoning — entries are deduped by signature and the count field matters.
 - **Do not modify `.turnq/`.** That holds turnq lock state.
 - **Do not reply to messages addressed to other actors.** You only act on messages where the `to:` field includes your name.
-- **Do not fabricate channel UUIDs.** Look at existing directories under `data/channels/` to find real ones — or run `npm run status` to list them.
+- **Do not fabricate channel UUIDs.** Look at existing directories under `data/channels/` to find real ones — or run `crosstalk status` to list them.