amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/registry/store.js

@@ -0,0 +1,290 @@
+'use strict';
+
+/**
+ * The registry's durable memory: ONE identity database per installation.
+ * Every registered tree lives here as one active parentless record with
+ * its descendants beneath it — identity is never partitioned by tree, so
+ * an entity crossing tree boundaries is a parent update in one
+ * transaction, never an export between databases. A tree is a SYNC
+ * boundary (its own head and rail, future Send work), not an identity
+ * boundary. The database handle is injected — this module never opens a
+ * connection itself. The schema also creates the evidence layer's two
+ * tables (registry/evidence.js), so all four are born together and ONE
+ * inspect and one sentinel guard records and evidence alike — but
+ * creation is the whole relationship: the registry never reads or writes
+ * them.
+ *
+ * Unlike the observer's store, this is IDENTITY DATA, not a rebuildable
+ * cache: nothing on disk carries UUIDs, so a lost registry cannot be
+ * reconstructed locally. `inspect` exists so the owner (index.js) can tell
+ * first initialization apart from loss before any schema is created.
+ *
+ * One invariant lives in the schema itself, so the database convicts even
+ * if application code fails to: one active owner per (parent_uuid, name)
+ * slot. Parentless records are exempt by SQLite's own NULL-distinctness —
+ * deliberately: a top-level tree is placed by its machine binding
+ * (address), never by name, so two trees may share a basename.
+ */
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS registry_meta (
+  singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+  epoch_uuid TEXT NOT NULL,
+  created_at_ms INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS entities (
+  uuid TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  parent_uuid TEXT REFERENCES entities(uuid),
+  name TEXT NOT NULL,
+  status TEXT NOT NULL CHECK (status IN ('active', 'trashed', 'deleted')),
+  payload_version TEXT
+);
+CREATE UNIQUE INDEX IF NOT EXISTS entities_slot
+  ON entities (parent_uuid, name) WHERE status = 'active';
+CREATE INDEX IF NOT EXISTS entities_parent ON entities (parent_uuid);
+CREATE TABLE IF NOT EXISTS channel_bindings (
+  channel_id TEXT PRIMARY KEY,
+  scope_id TEXT NOT NULL,
+  entity_uuid TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS channel_bindings_scope ON channel_bindings (scope_id);
+CREATE TABLE IF NOT EXISTS contested_ground (
+  scope_id TEXT NOT NULL,
+  rel_path TEXT NOT NULL,
+  claimant_uuid TEXT NOT NULL,
+  kind TEXT NOT NULL CHECK (kind IN ('file', 'dir')),
+  PRIMARY KEY (scope_id, rel_path)
+);
+CREATE TABLE IF NOT EXISTS repo_states (
+  entity_uuid TEXT PRIMARY KEY REFERENCES entities(uuid),
+  state_id TEXT NOT NULL,
+  card_id TEXT NOT NULL,
+  checkpoint_id TEXT NOT NULL,
+  state_json TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS entity_cloud_replica (
+  singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+  resource_id TEXT NOT NULL,
+  device_id TEXT NOT NULL,
+  authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
+  head_version INTEGER NOT NULL CHECK (head_version >= 0),
+  state TEXT NOT NULL CHECK (state IN ('active', 'bootstrapping')),
+  snapshot_cutoff INTEGER,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS entity_cloud_mutations (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  resource_id TEXT NOT NULL,
+  mutation_id TEXT NOT NULL UNIQUE,
+  operation_json TEXT NOT NULL,
+  mutation_state TEXT NOT NULL CHECK (mutation_state IN ('pending', 'syncing', 'synced', 'rejected')),
+  base_version INTEGER,
+  official_version INTEGER,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  next_attempt_at TEXT,
+  last_error TEXT,
+  cloud_committed_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS entity_cloud_mutations_pending
+  ON entity_cloud_mutations (resource_id, mutation_state, sequence);
+`;
+
+const CORE_TABLES = ['registry_meta', 'entities', 'channel_bindings', 'contested_ground'];
+const REPO_STATE_TABLES = [...CORE_TABLES, 'repo_states'];
+const TABLES = [...REPO_STATE_TABLES, 'entity_cloud_replica', 'entity_cloud_mutations'];
+
+// The schema generation this code speaks, stamped as PRAGMA user_version at
+// creation — completeness is judged against a declared shape, never
+// guessed. Generation 3 adds the current Card + Checkpoint document for
+// each repo.git entity. Generation 4 adds the entity-cloud replica and its
+// durable outbox to that SAME identity database: a local entity mutation and
+// the cloud delivery intent must commit together. Generations 2 and 3 are
+// additive predecessors: migrations only add tables beside existing identity
+// records, never rewrite UUIDs or evidence bindings. The per-tree era never
+// stamped a version and reads 0 — an older generation, refused distinctly
+// from loss until an explicit migration exists.
+const GENERATION = 4;
+const REPO_STATE_GENERATION = 3;
+const PREVIOUS_GENERATION = 2;
+
+function rowToEntity(row) {
+  if (!row) return null;
+  return {
+    uuid: row.uuid,
+    type: row.type,
+    parentUuid: row.parent_uuid,
+    name: row.name,
+    status: row.status,
+    payloadVersion: row.payload_version,
+  };
+}
+
+/** Which registry tables already exist — asked BEFORE any schema runs. */
+function inspect(db) {
+  const present = db.prepare(
+    `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${TABLES.map(() => '?').join(', ')})`,
+  ).all(...TABLES).map((row) => row.name);
+  return { fresh: present.length === 0, missing: TABLES.filter((name) => !present.includes(name)) };
+}
+
+function isMigratableGenerationShape(db, inspection) {
+  const generation = db.pragma('user_version', { simple: true });
+  if (generation === PREVIOUS_GENERATION) {
+    return inspection.missing.length === 3
+      && ['repo_states', 'entity_cloud_replica', 'entity_cloud_mutations']
+        .every((name) => inspection.missing.includes(name))
+      && CORE_TABLES.every((name) => !inspection.missing.includes(name));
+  }
+  return generation === REPO_STATE_GENERATION
+    && inspection.missing.length === 2
+    && ['entity_cloud_replica', 'entity_cloud_mutations']
+      .every((name) => inspection.missing.includes(name))
+    && REPO_STATE_TABLES.every((name) => !inspection.missing.includes(name));
+}
+
+function createStore(db) {
+  const generation = db.pragma('user_version', { simple: true });
+  const inspection = inspect(db);
+  if (!inspection.fresh && generation !== GENERATION && !isMigratableGenerationShape(db, inspection)) {
+    throw new Error(`identity registry is schema generation ${generation}, this code speaks ${GENERATION} — migration is an explicit act, never a silent table creation`);
+  }
+  db.exec(SCHEMA);
+  db.pragma(`user_version = ${GENERATION}`);
+
+  return {
+    meta() {
+      const row = db.prepare('SELECT * FROM registry_meta WHERE singleton = 1').get();
+      return row ? { epochUuid: row.epoch_uuid, createdAtMs: row.created_at_ms } : null;
+    },
+    initMeta({ epochUuid, createdAtMs }) {
+      db.prepare('INSERT INTO registry_meta (singleton, epoch_uuid, created_at_ms) VALUES (1, ?, ?)')
+        .run(epochUuid, createdAtMs);
+    },
+
+    byUuid(uuid) {
+      return rowToEntity(db.prepare('SELECT * FROM entities WHERE uuid = ?').get(uuid));
+    },
+    /** Every registered tree's top record: the active parentless rows. */
+    activeRoots() {
+      return db.prepare("SELECT * FROM entities WHERE parent_uuid IS NULL AND status = 'active' ORDER BY uuid")
+        .all().map(rowToEntity);
+    },
+    activeAtSlot(parentUuid, name) {
+      return rowToEntity(
+        db.prepare("SELECT * FROM entities WHERE parent_uuid IS ? AND name = ? AND status = 'active'")
+          .get(parentUuid, name),
+      );
+    },
+    childrenOf(parentUuid) {
+      return db.prepare('SELECT * FROM entities WHERE parent_uuid = ? ORDER BY uuid').all(parentUuid)
+        .map(rowToEntity);
+    },
+    activeChildrenOf(parentUuid) {
+      return db.prepare("SELECT * FROM entities WHERE parent_uuid = ? AND status = 'active' ORDER BY uuid")
+        .all(parentUuid).map(rowToEntity);
+    },
+    activeByType(type) {
+      return db.prepare("SELECT * FROM entities WHERE type = ? AND status = 'active' ORDER BY uuid")
+        .all(type).map(rowToEntity);
+    },
+    /** Logical graph rows for the cloud registry. This deliberately excludes
+     * observer bindings and every machine-local table. */
+    allEntities() {
+      return db.prepare('SELECT * FROM entities ORDER BY uuid').all().map(rowToEntity);
+    },
+
+    insert(entity) {
+      db.prepare(`
+        INSERT INTO entities (uuid, type, parent_uuid, name, status, payload_version)
+        VALUES (?, ?, ?, ?, ?, ?)
+      `).run(entity.uuid, entity.type, entity.parentUuid, entity.name, entity.status, entity.payloadVersion);
+    },
+    update(uuid, { type, parentUuid, name, status, payloadVersion }) {
+      db.prepare(`
+        UPDATE entities SET type = ?, parent_uuid = ?, name = ?, status = ?, payload_version = ?
+        WHERE uuid = ?
+      `).run(type, parentUuid, name, status, payloadVersion, uuid);
+    },
+    /**
+     * One address permutation as one write. Movers may hold each other's
+     * slots, and the live unique index cannot be threaded one row at a
+     * time — so land in two phases through impossible names (a real name
+     * never contains NUL), the same hidden-name trick disk itself uses
+     * for an exchange. One transaction: the in-between never exists.
+     */
+    applyMoves(moves) {
+      const toTemp = db.prepare('UPDATE entities SET name = ? WHERE uuid = ?');
+      // An optional type rides the same transition (adoption lands a
+      // workspace as a folder) — a separate write could tear.
+      const toFinal = db.prepare('UPDATE entities SET parent_uuid = ?, name = ?, type = COALESCE(?, type) WHERE uuid = ?');
+      db.transaction(() => {
+        for (const move of moves) toTemp.run(`\0${move.uuid}`, move.uuid);
+        for (const move of moves) toFinal.run(move.parentUuid, move.name, move.type ?? null, move.uuid);
+      })();
+    },
+
+    cloudReplica() {
+      const row = db.prepare('SELECT * FROM entity_cloud_replica WHERE singleton = 1').get();
+      if (!row) return null;
+      return {
+        resourceId: row.resource_id,
+        deviceId: row.device_id,
+        authorityEpoch: Number(row.authority_epoch),
+        headVersion: Number(row.head_version),
+        state: row.state,
+        snapshotCutoff: row.snapshot_cutoff == null ? null : Number(row.snapshot_cutoff),
+        updatedAt: row.updated_at,
+      };
+    },
+    saveCloudReplica(replica) {
+      db.prepare(`
+        INSERT INTO entity_cloud_replica (
+          singleton, resource_id, device_id, authority_epoch, head_version,
+          state, snapshot_cutoff, updated_at
+        ) VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(singleton) DO UPDATE SET
+          resource_id = excluded.resource_id,
+          device_id = excluded.device_id,
+          authority_epoch = excluded.authority_epoch,
+          head_version = excluded.head_version,
+          state = excluded.state,
+          snapshot_cutoff = excluded.snapshot_cutoff,
+          updated_at = excluded.updated_at
+      `).run(
+        replica.resourceId,
+        replica.deviceId,
+        replica.authorityEpoch,
+        replica.headVersion,
+        replica.state,
+        replica.snapshotCutoff ?? null,
+        replica.updatedAt,
+      );
+    },
+    cloudMutationCutoff() {
+      const row = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get();
+      return Number(row.sequence);
+    },
+    enqueueCloudMutation(mutation) {
+      db.prepare(`
+        INSERT INTO entity_cloud_mutations (
+          resource_id, mutation_id, operation_json, mutation_state,
+          created_at, updated_at
+        ) VALUES (?, ?, ?, 'pending', ?, ?)
+      `).run(
+        mutation.resourceId,
+        mutation.mutationId,
+        mutation.operationJson,
+        mutation.createdAt,
+        mutation.createdAt,
+      );
+    },
+    listCloudMutations() {
+      return db.prepare('SELECT * FROM entity_cloud_mutations ORDER BY sequence').all();
+    },
+  };
+}
+
+module.exports = { createStore, inspect, isMigratableGenerationShape };

package/runtime/scripts/amalgm-mcp/repocard/README.md

@@ -0,0 +1,103 @@
+# Repocard — the code-description layer
+
+## Purpose
+
+Describe a git repository perfectly, in two documents, so that another
+machine can rebuild exactly what the user sees — and so that a checkout,
+rebase, or merge travels the rails as one card, never as thousands of file
+events. This layer never syncs, never watches, never decides truth for
+anyone else: it captures, it applies, it verifies.
+
+## Axioms
+
+1. **Two documents, one truth.** The *card* is the committed repository:
+   HEAD, every local branch, every tag, and a bundle holding the objects.
+   The *checkpoint* is everything uncommitted riding on top: the staged
+   patch, the unstaged patch, and untracked file contents. Card + checkpoint
+   rebuild the user's exact view.
+2. **Identity is content-derived.** `cardId` hashes HEAD + branches + tags;
+   `checkpointId` hashes base commit + patches + untracked hashes. Equal ids
+   are silence — the echo-suppression rule of this layer. Bundle bytes never
+   enter identity (git's packing is not byte-deterministic); the bundle
+   carries its own checksum so corrupt data is rejected on apply.
+3. **Busy is honest.** A repo mid-merge, mid-rebase, mid-cherry-pick holds
+   index states no patch can represent. `capture` says `busy` and nothing
+   else; the operation's end fires its own doorbell. This is why a rebase is
+   one final card instead of a thousand events. Bisect is deliberately NOT
+   busy: it is a mode, not an unfinished operation — it can run for hours,
+   and every checkout it makes must be captured like any other.
+4. **Apply proves itself.** After materializing, the ids are re-derived from
+   the result and must equal the ids that arrived. Only then is the state
+   "applied". There is no separate notion of verification — reproduction is
+   the proof.
+5. **Machine-local stays local.** Absolute paths, credentials, reflogs,
+   hooks, stashes, and ignored files never travel. Remote URLs ride the card
+   as seed metadata (a rebuilt repo should know its origin) but stay outside
+   `cardId` — machines may legitimately reach the same origin differently.
+
+## Shape
+
+- `git.js` — the one place this layer runs git. Plain subprocesses, no
+  libraries, Buffers in and out.
+- `capture.js` — repo → `{ card, checkpoint, cardId, checkpointId, stateId }`
+  or `{ busy }`. Reads git, writes nothing.
+- `apply.js` — `materialize(dir, card, checkpoint)`: blank directory or
+  existing replica in, exact repo state out. Same code for a first apply and
+  a checkpoint-only refresh — refs, HEAD, and worktree are forced to the
+  card's truth, then the checkpoint lands on top.
+- `follow.js` — the follower: raw repo doorbells in, at most one honest
+  semantic event out (`card.changed` / `checkpoint.changed` / silence).
+- `index.js` — the api: `capture`, `verify`, `apply` (materialize + the
+  axiom-4 proof), and `createFollower`.
+
+Fidelity is git-level, not filesystem-level: the executable bit travels,
+arbitrary permissions do not; commit timestamps travel (they are committed
+history), machine timestamps do not; ignored files never travel.
+
+## The follower
+
+The observer answers "something happened in this repo territory"; the
+follower answers "what fact, if any, should travel". Its axiom: **ids
+identify settled states — and a settled state is the only completion git
+ever announces.** Every change the two documents describe settles as one
+of exactly two facts: the committed history moved (cardId) or the work on
+top of it moved (checkpointId). History-moving operations — commit,
+merge, rebase, checkout — end by moving a ref atomically; worktree
+commands — add, restore, clean, an editor saving — end the way any edit
+does, leaving files that settle into a new checkpointId. Ids never claim
+a *command* finished: an unowned writer that pauses mid-run yields two
+true states, not one. Operation boundaries exist only where someone owns
+the writer — git's busy markers for its own operations, `command()` for
+amalgm's — and no event-driven observer can invent one for a writer
+nobody owns. So the follower reads where both ids are once the ground is
+still. Card + checkpoint is the whole vocabulary; everything else is
+read-safety plumbing for an outside reader git gives no bell, no atomic
+glance, and no record of untracked files:
+
+- **The torn-read guard** — a state travels only when two consecutive
+  captures agree on its identity: no torn, id-inconsistent snapshot ever
+  travels, and ignored churn — which never moves the ids — cannot starve
+  detection (`capMs` keeps trying, the pair keeps it honest).
+- **Busy markers** — git saying "I am between two cards; there is no
+  coherent state to photograph yet"; their removal rings.
+- **Locks with a liveness check** — a lock held by a living process is git
+  mid-write: wait, and report it (`status().blocked`); its deletion rings.
+  An unheld lock is litter from a crash and blocks nothing — proven: a
+  stale lock stops neither editors nor `git clean` nor `update-ref`, so
+  honoring it would be permanent blindness, not safety. The holder check
+  is a single shot when a capture attempt meets a lock — never a poll.
+- **`command(fn)` is an optimization, not an authority** — an amalgm-run
+  command batches its noise into one capture at its declared end (nesting
+  collapses to the outermost end; failure still ends). Correctness never
+  depends on it: the ids' movement is the completion signal for the
+  commands amalgm never sees.
+
+Equal ids are silence, and `known` advances only on successful delivery —
+a failed emit leaves the state undelivered and re-offered. The follower
+retries itself whenever it witnessed the miss firsthand (a disagreeing
+pair, a failed capture or emit); it waits on the doorbell only for endings
+that are filesystem events; and consumer moments (`flush()` — a session
+opening, an app regaining focus) are the pull valve that turns a lost
+doorbell's "delayed" into "delivered" without polling. Named residual: a
+lock-free writer that stalls across both reads looks like stillness — the
+next doorbell or flush corrects the ids but cannot unsend the event.

package/runtime/scripts/amalgm-mcp/repocard/apply.js

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * materialize(dir, card, checkpoint): blank directory or existing replica
+ * in, the exact described repo state out. One code path for both — refs,
+ * HEAD, index, and worktree are forced to the card's truth, then the
+ * checkpoint lands on top. Nothing here trusts itself: the caller proves
+ * the result by re-deriving ids (axiom 4, done in index.js).
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const { runGit, tryGit, tryGitText } = require('./git');
+const { sha256 } = require('./capture');
+
+function fetchBundle(dir, bundle) {
+  if (sha256(bundle.bytes) !== bundle.sha256) {
+    throw new Error('bundle rejected: checksum does not match the card');
+  }
+  const tmp = path.join(os.tmpdir(), `repocard-apply-${process.pid}-${crypto.randomBytes(6).toString('hex')}.bundle`);
+  fs.writeFileSync(tmp, bundle.bytes);
+  try {
+    // Land the objects under a neutral namespace; real refs are written
+    // next from the card's explicit list, then the namespace is pruned.
+    // HEAD must be fetched explicitly: detached-HEAD commits are reachable
+    // from no branch, and a fetch that skips HEAD silently drops them.
+    runGit(dir, ['fetch', '--quiet', tmp,
+      '+HEAD:refs/card-import/HEAD',
+      '+refs/heads/*:refs/card-import/heads/*',
+      '+refs/tags/*:refs/card-import/tags/*']);
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+function haveAllObjects(dir, card) {
+  const wanted = [
+    ...card.branches.map((ref) => ref.commit),
+    ...card.tags.map((ref) => ref.commit),
+    ...(card.head.commit ? [card.head.commit] : []),
+  ];
+  return wanted.every((sha) => tryGit(dir, ['cat-file', '-e', sha]) !== null);
+}
+
+function forceRefs(dir, card) {
+  for (const ref of card.branches) runGit(dir, ['update-ref', `refs/heads/${ref.name}`, ref.commit]);
+  for (const ref of card.tags) runGit(dir, ['update-ref', `refs/tags/${ref.name}`, ref.commit]);
+
+  const keep = new Set([
+    ...card.branches.map((ref) => `refs/heads/${ref.name}`),
+    ...card.tags.map((ref) => `refs/tags/${ref.name}`),
+  ]);
+  const existing = tryGitText(dir, ['for-each-ref', '--format=%(refname)', 'refs/heads', 'refs/tags', 'refs/card-import']);
+  for (const ref of (existing || '').split('\n').filter(Boolean)) {
+    if (!keep.has(ref)) runGit(dir, ['update-ref', '-d', ref]);
+  }
+}
+
+function forceHead(dir, card) {
+  if (card.head.commit === null) {
+    // Unborn: point HEAD at the named branch, clear index and worktree.
+    runGit(dir, ['symbolic-ref', 'HEAD', `refs/heads/${card.head.branch}`]);
+    runGit(dir, ['read-tree', '--empty']);
+    runGit(dir, ['clean', '-fdq']);
+    return;
+  }
+  if (card.head.branch === null) {
+    runGit(dir, ['-c', 'advice.detachedHead=false', 'checkout', '--force', '--quiet', '--detach', card.head.commit]);
+  } else {
+    runGit(dir, ['symbolic-ref', 'HEAD', `refs/heads/${card.head.branch}`]);
+    runGit(dir, ['reset', '--hard', '--quiet']);
+  }
+  runGit(dir, ['clean', '-fdq']); // stale untracked work is the old checkpoint's, not ours
+}
+
+function applyCheckpoint(dir, checkpoint) {
+  if (checkpoint.stagedPatch.length > 0) {
+    runGit(dir, ['apply', '--index', '--binary', '--whitespace=nowarn'], { input: checkpoint.stagedPatch });
+  }
+  if (checkpoint.unstagedPatch.length > 0) {
+    runGit(dir, ['apply', '--binary', '--whitespace=nowarn'], { input: checkpoint.unstagedPatch });
+  }
+  for (const file of checkpoint.untracked) {
+    const abs = path.join(dir, file.path);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    if (file.mode === '120000') {
+      fs.rmSync(abs, { force: true });
+      fs.symlinkSync(file.content.toString('utf8'), abs);
+    } else {
+      fs.writeFileSync(abs, file.content);
+      fs.chmodSync(abs, file.mode === '100755' ? 0o755 : 0o644);
+    }
+  }
+}
+
+function materialize(dir, card, checkpoint) {
+  fs.mkdirSync(dir, { recursive: true });
+  if (!fs.existsSync(path.join(dir, '.git'))) {
+    runGit(dir, ['init', '--quiet']);
+    for (const remote of card.remotes) runGit(dir, ['remote', 'add', remote.name, remote.url]);
+  }
+  if (card.bundle && !haveAllObjects(dir, card)) fetchBundle(dir, card.bundle);
+  forceRefs(dir, card);
+  forceHead(dir, card);
+  applyCheckpoint(dir, checkpoint);
+}
+
+module.exports = { materialize };

package/runtime/scripts/amalgm-mcp/repocard/capture-worker.js

@@ -0,0 +1,94 @@
+'use strict';
+
+/**
+ * Capture, off the event loop.
+ *
+ * One persistent worker thread runs the synchronous `capture` so the
+ * runtime never blocks on git subprocesses. Requests serialize through the
+ * single worker on purpose: captures are short, a follower never overlaps
+ * its own pairs, and serializing across repos means a churny machine runs
+ * one git at a time instead of a subprocess storm. Structured clone strips
+ * the Buffer prototype, so patch and file bytes are re-hydrated on receipt.
+ *
+ * The worker is spawned lazily on first use, unref'd so it never holds the
+ * process open, and respawned on the next request if it dies. A death
+ * rejects every pending request — the follower treats that like any failed
+ * capture: retry, patiently.
+ */
+
+const { Worker, isMainThread, parentPort } = require('worker_threads');
+
+if (!isMainThread) {
+  const { capture } = require('./capture');
+  parentPort.on('message', ({ id, repoPath, options }) => {
+    try {
+      parentPort.postMessage({ id, snap: capture(repoPath, options) });
+    } catch (error) {
+      parentPort.postMessage({ id, error: error?.message || String(error) });
+    }
+  });
+}
+
+const asBuffer = (view) => (view == null ? view : Buffer.from(view));
+
+/** Structured clone turns Buffers into plain Uint8Arrays; undo that. */
+function rehydrate(snap) {
+  if (!snap || snap.busy) return snap;
+  if (snap.card.bundle) snap.card.bundle.bytes = asBuffer(snap.card.bundle.bytes);
+  snap.checkpoint.stagedPatch = asBuffer(snap.checkpoint.stagedPatch);
+  snap.checkpoint.unstagedPatch = asBuffer(snap.checkpoint.unstagedPatch);
+  for (const file of snap.checkpoint.untracked) file.content = asBuffer(file.content);
+  return snap;
+}
+
+function createCaptureWorker() {
+  let worker = null;
+  let closed = false;
+  let nextId = 1;
+  const pending = new Map();
+
+  function failAll(error) {
+    const waiting = [...pending.values()];
+    pending.clear();
+    for (const entry of waiting) entry.reject(error);
+  }
+
+  function ensureWorker() {
+    if (worker) return worker;
+    worker = new Worker(__filename);
+    worker.unref();
+    worker.on('message', ({ id, snap, error }) => {
+      const entry = pending.get(id);
+      if (!entry) return;
+      pending.delete(id);
+      if (error) entry.reject(new Error(error));
+      else entry.resolve(rehydrate(snap));
+    });
+    worker.on('error', (error) => failAll(error));
+    worker.on('exit', (code) => {
+      worker = null; // next request respawns
+      if (pending.size) failAll(new Error(`capture worker exited (code ${code})`));
+    });
+    return worker;
+  }
+
+  return {
+    capture(repoPath, options = {}) {
+      if (closed) return Promise.reject(new Error('capture worker is closed'));
+      return new Promise((resolve, reject) => {
+        const id = nextId++;
+        pending.set(id, { resolve, reject });
+        ensureWorker().postMessage({ id, repoPath, options });
+      });
+    },
+    async close() {
+      closed = true;
+      const dying = worker;
+      worker = null;
+      failAll(new Error('capture worker is closed'));
+      if (dying) await dying.terminate();
+    },
+  };
+}
+
+module.exports = { createCaptureWorker };