amalgm 0.1.178 → 0.1.179

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.178",
+  "version": "0.1.179",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/tests/workspace-checkpoint-reducer.test.js

@@ -89,3 +89,28 @@ test('an overlapping transition produces deterministic conflict bytes', async ()
   assert.match(content, /left/);
   assert.match(content, /right/);
 });
+
+test('an echoed transition that is already present reduces to a no-op', async () => {
+  const { repo, oid, tree: clean } = await makeRepo('echo');
+  const patch = await patchFor(repo, { 'a.txt': 'shared\n' });
+  const shared = await merge.treeOfPatch(repo, oid, patch);
+  const current = await merge.reduceTree(repo, clean, clean, shared, { label: '20' });
+  const echoed = await merge.reduceTree(repo, current.tree, clean, shared, { label: '21' });
+  assert.equal(echoed.tree, current.tree);
+  assert.deepEqual(echoed.conflicts, []);
+});
+
+test('a deletion never removes a file another writer edited', async () => {
+  const { repo, oid, tree: clean } = await makeRepo('delete-vs-edit');
+  const localPatch = await patchFor(repo, { 'a.txt': 'precious local edit\n' });
+  const localTree = await merge.treeOfPatch(repo, oid, localPatch);
+  fs.rmSync(path.join(repo, 'a.txt'));
+  const deletePatch = await git(repo, 'diff', 'HEAD', '--binary', '--full-index');
+  await git(repo, 'reset', '--hard', 'HEAD');
+  const deletedTree = await merge.treeOfPatch(repo, oid, deletePatch);
+
+  const current = await merge.reduceTree(repo, clean, clean, localTree, { label: '30' });
+  const outcome = await merge.reduceTree(repo, current.tree, clean, deletedTree, { label: '31' });
+  assert.equal(outcome.conflicts[0].kind, 'delete-vs-change');
+  assert.equal(await treeText(repo, outcome.tree, 'a.txt'), 'precious local edit\n');
+});

package/runtime/scripts/amalgm-mcp/tests/workspace-checkpoint.test.js

@@ -159,5 +159,5 @@ test('checkpoint captures are local cache; their operations travel on the one wa
   assert.equal(first, checkpointFile('m1', 'https://github.com/a/b'));
   assert.notEqual(first, checkpointFile('m2', 'https://github.com/a/b'));
   assert.notEqual(first, checkpointFile('m1', 'https://github.com/a/c'));
-  assert.match(first, /repo-checkpoints-v4/);
+  assert.match(first, /repo-checkpoints-v5/);
 });

package/runtime/scripts/amalgm-mcp/tests/workspace-reducer.test.js

@@ -22,7 +22,7 @@ fs.writeFileSync(
 
 const { closeLocalDb } = require('../state/db');
 const { revisionOf } = require('../workspace/checkpoint');
-const { materializeRepo, readRepoState, reduceWall } = require('../workspace/reducer');
+const { hydrateRepo, materializeRepo, readRepoState, reduceWall } = require('../workspace/reducer');
 
 test.after(() => {
   closeLocalDb();
@@ -66,7 +66,7 @@ function value(baseOid, diff) {
 
 function transition(machine, version, baseOid, from, to) {
   return {
-    checkpoint: 'repo-checkpoint@4',
+    checkpoint: 'repo-checkpoint@5',
     machine,
     repoKey: 'root:test',
     branch: 'main',
@@ -96,10 +96,10 @@ function card(repo, oid, version) {
 }
 
 test('wall reduction chooses one rail winner and orders checkpoint transitions by rail', () => {
-  const oldCard = { ...card('/old', 'a'.repeat(40), 4), checkpointVersion: 9 };
-  oldCard.checkpoint = transition('machine-a', 9, oldCard.head.oid, '', 'a');
-  const newCard = { ...card('/new', 'b'.repeat(40), 7), checkpointVersion: 8 };
-  newCard.checkpoint = transition('machine-b', 8, newCard.head.oid, '', 'b');
+  const oldCard = card('/old', 'a'.repeat(40), 4);
+  oldCard.checkpoints = [transition('machine-a', 9, oldCard.head.oid, '', 'a')];
+  const newCard = card('/new', 'b'.repeat(40), 7);
+  newCard.checkpoints = [transition('machine-b', 8, newCard.head.oid, '', 'b')];
   const plans = reduceWall([
     { machine: 'machine-a', cards: [oldCard] },
     { machine: 'machine-b', cards: [newCard] },
@@ -109,6 +109,64 @@ test('wall reduction chooses one rail winner and orders checkpoint transitions b
   assert.deepEqual(plan.transitions.map((item) => item.version), [8]);
 });
 
+test('a stale lower rail card cannot roll back a newer branch and commit', () => {
+  const newer = card('/newer', 'b'.repeat(40), 12);
+  newer.head.branch = 'feature';
+  const stale = card('/stale', 'a'.repeat(40), 11);
+  stale.head.branch = 'main';
+  const plan = reduceWall([
+    { machine: 'machine-stale', cards: [stale] },
+    { machine: 'machine-newer', cards: [newer] },
+  ]).get('root:test');
+  assert.equal(plan.card.head.branch, 'feature');
+  assert.equal(plan.card.head.oid, 'b'.repeat(40));
+  assert.equal(plan.card.positionVersion, 12);
+});
+
+test('an empty project folder hydrates from the winning card bundle without cloning', async () => {
+  const sourceRepo = await makeRepo('hydrate-source');
+  const source = sourceRepo.repo;
+  fs.mkdirSync(path.join(source, '.amalgam', 'context'), { recursive: true });
+  fs.writeFileSync(path.join(source, '.amalgam', 'context', 'notes.md'), 'committed note\n');
+  await git(source, 'add', '.');
+  await git(source, 'commit', '-m', 'track project memory');
+  const oid = (await git(source, 'rev-parse', 'HEAD')).trim();
+  const bundle = path.join(tempRoot, 'hydrate.bundle');
+  await git(source, 'bundle', 'create', bundle, 'main');
+  const bytes = fs.readFileSync(bundle);
+  const digest = require('crypto').createHash('sha256').update(bytes).digest('hex');
+  const chunks = path.join(process.env.AMALGM_DIR, 'state', 'repo-objects', 'chunks');
+  fs.mkdirSync(chunks, { recursive: true });
+  fs.writeFileSync(path.join(chunks, `${digest}.bin`), bytes);
+
+  const target = path.join(tempRoot, 'hydrate-target');
+  fs.mkdirSync(path.join(target, '.amalgam', 'context'), { recursive: true });
+  fs.writeFileSync(path.join(target, '.amalgam', 'context', 'notes.md'), 'local note\n');
+  const winning = card('/remote', oid, 1);
+  winning.repo.remote = 'https://example.com/org/repo';
+  winning.objects = {
+    kind: 'bundle',
+    contract: 'git-bundle-chunks@1',
+    resourceId: 'shr_hydrationProof123456',
+    oid,
+    ref: `refs/amalgm/exports/${oid}`,
+    checksum: digest,
+    bytes: bytes.length,
+    chunks: [{ sha256: digest, bytes: bytes.length }],
+  };
+
+  const result = await hydrateRepo(
+    { path: target },
+    { repoKey: 'https://example.com/org/repo', card: winning, transitions: [] },
+  );
+  assert.equal(result.state, 'hydrated');
+  assert.equal((await git(target, 'rev-parse', 'HEAD')).trim(), oid);
+  assert.equal((await git(target, 'symbolic-ref', '--short', 'HEAD')).trim(), 'main');
+  assert.equal(fs.readFileSync(path.join(target, 'a.txt'), 'utf8'), 'a0\n');
+  assert.equal(fs.readFileSync(path.join(target, '.amalgam', 'context', 'notes.md'), 'utf8'), 'local note\n');
+  assert.match(await git(target, 'status', '--porcelain=v1'), /\.amalgam\/context\/notes\.md/);
+});
+
 test('branch refs reduce per name; an absent stale list cannot delete another writer branch', () => {
   const first = card('/a', 'a'.repeat(40), 5);
   first.branches = [
@@ -143,9 +201,7 @@ test('a multi-user storm reduces identically regardless of network arrival order
   const entries = Array.from({ length: 12 }, (_, index) => {
     const machine = `machine-${index}`;
     const observed = card(`/machine-${index}`, oid, index + 1);
-    observed.checkpoint = transition(machine, 100 + index, oid, '', `patch-${index}`);
-    observed.checkpointVersion = 100 + index;
-    observed.checkpointMutationId = `mut_checkpoint_${index}`.padEnd(16, 'x');
+    observed.checkpoints = [transition(machine, 100 + index, oid, '', `patch-${index}`)];
     observed.branches = [
       {
         name: `feature-${index % 4}`,
@@ -216,6 +272,40 @@ test('one materializer converges to the reduced checkpoint and later removes a r
   assert.equal(fs.readFileSync(path.join(repo, 'b.txt'), 'utf8'), 'b1\n');
 });
 
+test('a writer publishing again cannot erase its earlier uncommitted work', async () => {
+  const { repo, oid } = await makeRepo('checkpoint-history');
+  const patchA = await patchFor(repo, { 'a.txt': 'a1\n' });
+  const patchAB = await patchFor(repo, { 'a.txt': 'a1\n', 'b.txt': 'b1\n' });
+  const patchABC = await patchFor(repo, {
+    'a.txt': 'a1\n',
+    'b.txt': 'b1\n',
+    'c.txt': 'c1\n',
+  });
+  const machineA = card('/machine-a', oid, 1);
+  machineA.machine = 'machine-a';
+  machineA.checkpoints = [
+    transition('machine-a', 2, oid, '', patchA),
+    transition('machine-a', 4, oid, patchAB, patchABC),
+  ];
+  const machineB = card('/machine-b', oid, 1);
+  machineB.machine = 'machine-b';
+  machineB.checkpoints = [
+    transition('machine-b', 3, oid, patchA, patchAB),
+  ];
+
+  const plan = reduceWall([
+    { machine: 'machine-a', cards: [machineA] },
+    { machine: 'machine-b', cards: [machineB] },
+  ]).get('root:test');
+  assert.deepEqual(plan.transitions.map((item) => item.version), [2, 3, 4]);
+
+  const outcome = await materializeRepo(card(repo, oid, 1), plan);
+  assert.equal(outcome.state, 'in-sync');
+  assert.equal(fs.readFileSync(path.join(repo, 'a.txt'), 'utf8'), 'a1\n');
+  assert.equal(fs.readFileSync(path.join(repo, 'b.txt'), 'utf8'), 'b1\n');
+  assert.equal(fs.readFileSync(path.join(repo, 'c.txt'), 'utf8'), 'c1\n');
+});
+
 test('a losing commit is parked, the winning card lands exactly, and losing work becomes uncommitted', async () => {
   const { repo, oid: baseOid } = await makeRepo('simultaneous-commit');
   fs.writeFileSync(path.join(repo, 'local-commit.txt'), 'losing commit work\n');
@@ -322,3 +412,54 @@ test('the materializer creates, moves, and deletes branch refs without checking
   await assert.rejects(() => git(repo, 'rev-parse', 'refs/heads/feature'));
   assert.equal((await git(repo, 'branch', '--show-current')).trim(), 'main');
 });
+
+test('a card branch switch follows branch and OID together and leaves the old branch unchanged', async () => {
+  const { repo, oid: mainOid } = await makeRepo('card-branch-switch');
+  await git(repo, 'checkout', '-b', 'feature');
+  fs.writeFileSync(path.join(repo, 'a.txt'), 'feature\n');
+  await git(repo, 'add', 'a.txt');
+  await git(repo, 'commit', '-m', 'feature');
+  const featureOid = (await git(repo, 'rev-parse', 'HEAD')).trim();
+  await git(repo, 'checkout', 'main');
+
+  const local = card(repo, mainOid, 1);
+  const winning = card('/peer', featureOid, 2);
+  winning.head.branch = 'feature';
+  winning.objects = { kind: 'local' };
+  const outcome = await materializeRepo(local, {
+    repoKey: 'root:test',
+    card: winning,
+    transitions: [],
+    branches: [
+      { name: 'main', oid: mainOid, version: 1, mutationId: 'mut_main_branch01' },
+      { name: 'feature', oid: featureOid, version: 2, mutationId: 'mut_feature_head1' },
+    ],
+  });
+
+  assert.equal(outcome.state, 'in-sync');
+  assert.equal((await git(repo, 'symbolic-ref', '--short', 'HEAD')).trim(), 'feature');
+  assert.equal((await git(repo, 'rev-parse', 'HEAD')).trim(), featureOid);
+  assert.equal((await git(repo, 'rev-parse', 'refs/heads/main')).trim(), mainOid);
+});
+
+test('a branch-only card change at the same commit still switches the exact branch', async () => {
+  const { repo, oid } = await makeRepo('same-oid-branch-switch');
+  await git(repo, 'branch', 'feature');
+  const local = card(repo, oid, 1);
+  const winning = card('/peer', oid, 2);
+  winning.head.branch = 'feature';
+  winning.objects = { kind: 'local' };
+
+  const outcome = await materializeRepo(local, {
+    repoKey: 'root:test',
+    card: winning,
+    transitions: [],
+    branches: [
+      { name: 'main', oid, version: 1, mutationId: 'mut_same_main001' },
+      { name: 'feature', oid, version: 2, mutationId: 'mut_same_feature1' },
+    ],
+  });
+  assert.equal(outcome.state, 'in-sync');
+  assert.equal((await git(repo, 'symbolic-ref', '--short', 'HEAD')).trim(), 'feature');
+  assert.equal((await git(repo, 'rev-parse', 'HEAD')).trim(), oid);
+});

package/runtime/scripts/amalgm-mcp/tests/workspace-wall.test.js

@@ -28,11 +28,13 @@ const { registerReplica } = require('../state/replicas');
 const { openDoc, getDocText, writeDocText } = require('../state/docs');
 const { upsertWorkspace } = require('../workspace/store');
 const { refreshRepoCards } = require('../workspace/cards');
-const { repoKeyOfCard } = require('../workspace/checkpoint');
+const { checkpointFile, repoKeyOfCard } = require('../workspace/checkpoint');
 const {
   bindProject,
+  isCommittedCard,
   projectForRepo,
   projectResourceId,
+  publishedCardFor,
   publishWall,
   readWall,
   wallStats,
@@ -64,16 +66,24 @@ test('a project id is stable for one owner and repo, and distinct for another ow
   assert.equal(projectResourceId(null, userA), null);
 });
 
+test('no commit means no shared card', () => {
+  assert.equal(isCommittedCard({ head: { branch: 'main', oid: null } }), false);
+  assert.equal(isCommittedCard({ head: { branch: 'main', oid: 'a'.repeat(40) } }), true);
+});
+
 test('a collaborator binds the same repo to the owner project, not a parallel project', () => {
   const shared = projectResourceId('repo-shared', '22222222-2222-4222-8222-222222222222');
+  const localPath = path.join(tempRoot, 'projects/shared');
   const bound = bindProject(
     'repo-shared',
     shared,
     '22222222-2222-4222-8222-222222222222',
+    localPath,
   );
   assert.equal(bound.resourceId, shared);
   assert.equal(projectForRepo('repo-shared').resourceId, shared);
   assert.equal(projectForRepo('repo-shared').ownerUserId, '22222222-2222-4222-8222-222222222222');
+  assert.equal(projectForRepo('repo-shared').path, localPath);
 });
 
 test('a repo project carries exactly one line per machine, replaced in place', async () => {
@@ -104,13 +114,14 @@ test('a repo project carries exactly one line per machine, replaced in place', a
   assert.equal(first.published, true);
   const entries = readWall(repoKey);
   assert.equal(entries.length, 1);
-  assert.equal(entries[0].wall, 'code-project@1');
+  assert.equal(entries[0].wall, 'code-project@3');
   assert.equal(entries[0].project, repoKey);
   assert.equal(entries[0].machine, 'machine-a');
   assert.equal(entries[0].cards.length, 1);
   assert.equal(entries[0].cards[0].head.branch, 'main');
   assert.equal(entries[0].cards[0].positionMutationId, first.mutationId);
   assert.equal(entries[0].cards[0].positionVersion, null);
+  assert.equal(publishedCardFor(refreshed.cards[0]), null);
 
   acknowledgeCloudMutation(project.resourceId, first.mutationId, {
     version: 1,
@@ -121,6 +132,7 @@ test('a repo project carries exactly one line per machine, replaced in place', a
   const sealedCard = readWall(repoKey)[0].cards[0];
   assert.equal(sealedCard.positionMutationId, first.mutationId);
   assert.equal(sealedCard.positionVersion, 1);
+  assert.equal(publishedCardFor(refreshed.cards[0]).positionVersion, 1);
 
   const again = publishWall(repoKey);
   assert.equal(again.published, false);
@@ -129,18 +141,59 @@ test('a repo project carries exactly one line per machine, replaced in place', a
   fs.writeFileSync(path.join(repo, 'new.txt'), 'x\n');
   await refreshRepoCards();
   const republished = publishWall(repoKey);
-  assert.equal(republished.published, true);
+  assert.equal(republished.published, false);
   const after = readWall(repoKey);
   assert.equal(after.length, 1);
-  assert.equal(after[0].cards[0].dirty.untracked, 1);
+  assert.equal(Object.hasOwn(after[0].cards[0], 'dirty'), false);
   assert.equal(after[0].cards[0].positionMutationId, first.mutationId);
   assert.equal(after[0].cards[0].positionVersion, 1);
   assert.equal(getDocText(project.file).trim().split('\n').length, 1);
 });
 
+test('checkpoint transitions append until the next card and carry their official rail numbers', async () => {
+  const card = readWall(repoKey)[0].cards[0];
+  const file = checkpointFile('machine-a', repoKey);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const firstCheckpoint = {
+    checkpoint: 'repo-checkpoint@5',
+    machine: 'machine-a',
+    repoKey,
+    branch: card.head.branch,
+    baseOid: card.head.oid,
+    from: { revision: null, indexDiff: '', worktreeDiff: '' },
+    to: { revision: 'revision-a', indexDiff: '', worktreeDiff: 'patch-a' },
+    parked: [],
+    capturedAt: '2026-07-23T00:00:01.000Z',
+  };
+  fs.writeFileSync(file, `${JSON.stringify(firstCheckpoint)}\n`);
+  const first = publishWall(repoKey);
+  assert.equal(first.published, true);
+  assert.equal(readWall(repoKey)[0].cards[0].checkpoints.length, 1);
+  assert.equal(readWall(repoKey)[0].cards[0].checkpoints[0].mutationId, first.mutationId);
+
+  acknowledgeCloudMutation(project.resourceId, first.mutationId, {
+    version: 2,
+    committedAt: '2026-07-23T00:00:02.000Z',
+  });
+  assert.equal(readWall(repoKey)[0].cards[0].checkpoints[0].version, 2);
+  assert.equal(publishWall(repoKey).published, true);
+
+  fs.writeFileSync(file, `${JSON.stringify({
+    ...firstCheckpoint,
+    from: firstCheckpoint.to,
+    to: { revision: 'revision-b', indexDiff: '', worktreeDiff: 'patch-b' },
+    capturedAt: '2026-07-23T00:00:03.000Z',
+  })}\n`);
+  const second = publishWall(repoKey);
+  assert.equal(second.published, true);
+  const history = readWall(repoKey)[0].cards[0].checkpoints;
+  assert.equal(history.length, 2);
+  assert.deepEqual(history.map((entry) => entry.mutationId), [first.mutationId, second.mutationId]);
+});
+
 test('a peer machine line is preserved byte-for-byte through local publishes', async () => {
   const peerLine = JSON.stringify({
-    wall: 'code-project@1',
+    wall: 'code-project@3',
     project: repoKey,
     machine: 'machine-b',
     publishedAt: '2026-07-19T00:00:00.000Z',
@@ -150,6 +203,8 @@ test('a peer machine line is preserved byte-for-byte through local publishes', a
 
   const repo = path.join(tempRoot, 'projects/app');
   fs.writeFileSync(path.join(repo, 'another.txt'), 'y\n');
+  await run(repo, 'add', '.');
+  await run(repo, 'commit', '-m', 'advance card');
   await refreshRepoCards();
   const result = publishWall(repoKey);
   assert.equal(result.published, true);
@@ -163,7 +218,7 @@ test('a peer machine line is preserved byte-for-byte through local publishes', a
 test('a torn line is ignored by readers, never fatal', () => {
   writeDocText(
     project.file,
-    `${getDocText(project.file)}{"wall":"code-project@1","project":"${repoKey}","machine":"machine-c","car\n`,
+    `${getDocText(project.file)}{"wall":"code-project@3","project":"${repoKey}","machine":"machine-c","car\n`,
   );
   assert.deepEqual(readWall(repoKey).map((entry) => entry.machine).sort(), ['machine-a', 'machine-b']);
 });
@@ -171,11 +226,11 @@ test('a torn line is ignored by readers, never fatal', () => {
 test('project stats name every project resource, binding, and publish counter', () => {
   const stats = wallStats();
   const row = stats.projects.find((entry) => entry.repoKey === repoKey);
-  assert.equal(stats.contract, 'code-project@1');
+  assert.equal(stats.contract, 'code-project@3');
   assert.equal(row.resourceId, project.resourceId);
   assert.equal(row.replica.appliedVersion >= 0, true);
   assert.equal(row.machines, 2);
-  assert.ok(stats.publishes >= 3);
+  assert.ok(stats.publishes >= 2);
   assert.ok(stats.publishSkips >= 1);
   assert.ok(stats.paths.includes(project.file));
 });

package/runtime/scripts/amalgm-mcp/workspace/checkpoint.js

@@ -25,7 +25,7 @@ const { machineId } = require('./identity');
 const { listRepoCards } = require('./cards');
 const { captureCheckpoint } = require('./git');
 
-const CHECKPOINT_CONTRACT = 'repo-checkpoint@4';
+const CHECKPOINT_CONTRACT = 'repo-checkpoint@5';
 const MAX_INLINE_DIFF_BYTES = 512 * 1024;
 const PUBLISH_QUIET_MS = 25;
 const RECONCILE_INTERVAL_MS = 30_000;
@@ -54,7 +54,7 @@ function checkpointFile(machine, repoKey) {
     .update(`${CHECKPOINT_CONTRACT}|${machine}|${repoKey}`)
     .digest('hex')
     .slice(0, 24);
-  return path.join(AMALGM_DIR, 'state', 'repo-checkpoints-v4', `${digest}.json`);
+  return path.join(AMALGM_DIR, 'state', 'repo-checkpoints-v5', `${digest}.json`);
 }
 
 function revisionOf(baseOid, indexDiff, worktreeDiff = '') {
@@ -145,23 +145,6 @@ function readCheckpointValue(baseOid, value) {
   return { state: 'ready', indexDiff, worktreeDiff };
 }
 
-function ownPublishedCard(card) {
-  const own = require('./wall').readWall().find((entry) => (
-    entry.machine === machineId()
-    && entry.cards?.some((candidate) => candidate.replica === card.replica)
-  ));
-  const published = own?.cards?.find((candidate) => candidate.replica === card.replica);
-  if (
-    !published
-    || !Number.isInteger(published.positionVersion)
-    || published.positionVersion < 1
-    || published.head?.branch !== card.head?.branch
-    || published.head?.oid !== card.head?.oid
-    || Boolean(published.head?.detached) !== Boolean(card.head?.detached)
-  ) return null;
-  return published;
-}
-
 async function publishPass(replicaId = null) {
   const machine = machineId();
   const run = { published: 0, skips: 0, waiting: 0, failures: 0 };
@@ -171,7 +154,7 @@ async function publishPass(replicaId = null) {
     const repoKey = repoKeyOfCard(card);
     if (!repoKey || !card.head?.oid) continue;
     try {
-      const publishedCard = ownPublishedCard(card);
+      const publishedCard = require('./wall').publishedCardFor(card);
       const reduced = require('./reducer').readRepoState(repoKey);
       if (
         !publishedCard
@@ -226,7 +209,6 @@ async function publishPass(replicaId = null) {
         repoKey,
         branch: card.head.branch,
         baseOid: card.head.oid,
-        cardVersion: publishedCard.positionVersion,
         from: checkpointValue(
           machine,
           repoKey,

package/runtime/scripts/amalgm-mcp/workspace/objects.js

@@ -328,7 +328,7 @@ function validateLocator(locator) {
   ) throw new Error('invalid git bundle locator');
 }
 
-async function importFromLocator(worktreeRoot, locator) {
+function prepareBundleImport(locator) {
   validateLocator(locator);
   ensureDirs();
   let waiting = false;
@@ -361,7 +361,13 @@ async function importFromLocator(worktreeRoot, locator) {
     }
     fs.writeFileSync(bundleFile, bundle, { mode: 0o600 });
   }
-  await transition.importBundle(worktreeRoot, bundleFile);
+  return { state: 'ready', file: bundleFile };
+}
+
+async function importFromLocator(worktreeRoot, locator) {
+  const prepared = prepareBundleImport(locator);
+  if (prepared.state !== 'ready') return prepared;
+  await transition.importBundle(worktreeRoot, prepared.file);
   return { state: 'imported' };
 }
 
@@ -375,6 +381,7 @@ module.exports = {
   claimUpload,
   importFromLocator,
   objectSourceFor,
+  prepareBundleImport,
   publishPayload,
   readPayload,
   receiveDownload,

package/runtime/scripts/amalgm-mcp/workspace/reducer.js

@@ -75,8 +75,9 @@ function validVersion(value) {
 }
 
 /**
- * Pure wall reduction. Machine identity never chooses a winner; it only
- * identifies the latest checkpoint transition each writer currently owns.
+ * Pure wall reduction. Machine identity never chooses a winner. Checkpoint
+ * transitions remain in the wall until the next card folds them into a
+ * commit, so reducing current state never forgets an earlier edit.
  */
 function reduceWall(entries) {
   const repos = new Map();
@@ -102,17 +103,14 @@ function reduceWall(entries) {
         const held = repo.branchMap.get(ref.name);
         if (!held || ref.version > held.version) repo.branchMap.set(ref.name, ref);
       }
-      if (
-        card.checkpoint
-        && validVersion(card.checkpointVersion)
-        && card.checkpoint.machine === wallEntry.machine
-      ) {
-        repo.transitions.push({
-          ...card.checkpoint,
-          version: card.checkpointVersion,
-          mutationId: card.checkpointMutationId,
-        });
-        repo.parked.push(...(card.checkpoint.parked || []));
+      for (const checkpoint of card.checkpoints || []) {
+        if (
+          validVersion(checkpoint.version)
+          && checkpoint.machine === wallEntry.machine
+        ) {
+          repo.transitions.push(checkpoint);
+          repo.parked.push(...(checkpoint.parked || []));
+        }
       }
     }
   }
@@ -171,6 +169,36 @@ async function obtainCardObjects(localCard, targetCard) {
     : { state: 'missing-objects-after-fetch' };
 }
 
+async function hydrateRepo(project, plan) {
+  const targetCard = plan.card;
+  if (!project?.path) return { state: 'waiting', reason: 'local-project-path-missing' };
+  if (!targetCard?.head?.oid) return { state: 'waiting', reason: 'winning-card-unborn' };
+  if (targetCard.objects?.kind !== 'bundle') {
+    return { state: 'waiting', reason: targetCard.objects?.kind === 'pending'
+      ? 'objects-uploading'
+      : 'winning-card-bundle-missing' };
+  }
+  const prepared = require('./objects').prepareBundleImport(targetCard.objects);
+  if (prepared.state !== 'ready') {
+    return { state: 'waiting', reason: `objects-${prepared.state}` };
+  }
+  await transition.initializeRepo(project.path, targetCard.repo?.remote || null);
+  await transition.importBundle(project.path, prepared.file);
+  const holding = transition.holdInitialFiles(project.path);
+  try {
+    await transition.checkoutInitialCard(project.path, {
+      branch: targetCard.head.branch,
+      oid: targetCard.head.oid,
+    });
+  } catch (error) {
+    transition.restoreInitialFiles(project.path, holding);
+    throw error;
+  }
+  transition.restoreInitialFiles(project.path, holding);
+  await refreshRepoCards();
+  return { state: 'hydrated', moved: true };
+}
+
 async function moveToWinningCard(localCard, targetCard) {
   const current = await headAndDirty(localCard.path);
   const operation = await operationState(localCard.path);
@@ -471,7 +499,8 @@ async function materializeRepo(localCardInput, plan) {
 async function runReducer() {
   service.counters.passes += 1;
   const startedAt = Date.now();
-  const plans = reduceWall(require('./wall').readWall());
+  const wall = require('./wall');
+  const plans = reduceWall(wall.readWall());
   const locals = new Map();
   for (const card of listRepoCards()) {
     if (card.kind !== 'primary' || card.health !== 'healthy') continue;
@@ -481,10 +510,50 @@ async function runReducer() {
 
   let moved = false;
   for (const [repoKey, plan] of plans) {
-    const local = locals.get(repoKey);
-    if (!local || !plan.card) continue;
+    let local = locals.get(repoKey);
+    if (!plan.card) continue;
     try {
-      const outcome = await materializeRepo(local, plan);
+      if (!local?.head?.oid) {
+        const hydrated = await hydrateRepo(wall.projectForRepo(repoKey), plan);
+        service.repos.set(repoKey, {
+          repoKey,
+          path: wall.projectForRepo(repoKey)?.path || local?.path || null,
+          ...hydrated,
+          at: new Date().toISOString(),
+        });
+        if (hydrated.state === 'waiting') service.counters.waiting += 1;
+        if (hydrated.moved) {
+          moved = true;
+          service.counters.materialized += 1;
+        }
+        continue;
+      }
+      const refreshed = await refreshRepoCard(local.replica) || local;
+      if (!wall.publishedCardFor(refreshed)) {
+        wall.publishWall(repoKey);
+        const outcome = { state: 'waiting', reason: 'local-card-publishing', moved: false };
+        service.repos.set(repoKey, {
+          repoKey,
+          path: refreshed.path,
+          ...outcome,
+          at: new Date().toISOString(),
+        });
+        service.counters.waiting += 1;
+        continue;
+      }
+      const currentPlan = reduceWall(wall.readWall()).get(repoKey);
+      if (!currentPlan?.card) {
+        const outcome = { state: 'waiting', reason: 'official-card-settling', moved: false };
+        service.repos.set(repoKey, {
+          repoKey,
+          path: refreshed.path,
+          ...outcome,
+          at: new Date().toISOString(),
+        });
+        service.counters.waiting += 1;
+        continue;
+      }
+      const outcome = await materializeRepo(refreshed, currentPlan);
       service.repos.set(repoKey, { repoKey, path: local.path, ...outcome, at: new Date().toISOString() });
       if (outcome.state === 'waiting') service.counters.waiting += 1;
       if (outcome.moved) {
@@ -572,6 +641,7 @@ function reducerStats() {
 }
 
 module.exports = {
+  hydrateRepo,
   materializeRepo,
   readRepoState,
   reduceNow,

package/runtime/scripts/amalgm-mcp/workspace/rest.js

@@ -694,6 +694,7 @@ function handleCodeProjectJoin(body, sendJson) {
       body?.repoKey,
       body?.resourceId,
       body?.ownerUserId,
+      body?.path,
     );
     sendJson(200, { project });
   } catch (error) {

package/runtime/scripts/amalgm-mcp/workspace/transition.js

@@ -23,6 +23,7 @@ const { AMALGM_DIR } = require('../config');
 const execFileAsync = promisify(execFile);
 
 const JOURNAL_FILE = path.join(AMALGM_DIR, 'state', 'workspace-transitions.jsonl');
+const HYDRATION_DIR = path.join(AMALGM_DIR, 'state', 'repo-hydration');
 
 const TRANSITION_ENV = {
   GIT_TERMINAL_PROMPT: '0',
@@ -101,6 +102,67 @@ function importBundle(worktreeRoot, bundleFile) {
   ]);
 }
 
+async function initializeRepo(worktreeRoot, remote) {
+  fs.mkdirSync(worktreeRoot, { recursive: true });
+  await run('initialize-repo', worktreeRoot, [
+    '-C', worktreeRoot, 'init',
+  ]);
+  if (!remote) return;
+  let current = null;
+  try {
+    current = (await run(
+      'observe-origin',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'remote', 'get-url', 'origin'],
+      { journalResult: false },
+    )).trim();
+  } catch (error) {
+    if (!(error instanceof TransitionError)) throw error;
+  }
+  if (!current) {
+    await run('set-origin', worktreeRoot, [
+      '-C', worktreeRoot, 'remote', 'add', 'origin', remote,
+    ]);
+  } else if (current !== remote) {
+    throw new TransitionError('initialize-repo', worktreeRoot, 'existing origin does not match the card');
+  }
+}
+
+async function checkoutInitialCard(worktreeRoot, { branch, oid }) {
+  await run('checkout-initial-card', worktreeRoot, branch
+    ? ['-C', worktreeRoot, 'checkout', '-B', branch, oid]
+    : ['-C', worktreeRoot, 'checkout', '--detach', oid], {
+    timeoutMs: 60_000,
+  });
+  const after = await currentHead(worktreeRoot);
+  if (after.branch !== (branch || null) || after.oid !== oid) {
+    throw new TransitionError(
+      'checkout-initial-card',
+      worktreeRoot,
+      `expected ${branch || '(detached)'}@${oid}, observed ${after.branch || '(detached)'}@${after.oid}`,
+    );
+  }
+}
+
+function holdInitialFiles(worktreeRoot) {
+  const entries = fs.readdirSync(worktreeRoot).filter((entry) => entry !== '.git');
+  if (!entries.length) return null;
+  fs.mkdirSync(HYDRATION_DIR, { recursive: true });
+  const holding = fs.mkdtempSync(path.join(HYDRATION_DIR, 'hold-'));
+  for (const entry of entries) {
+    fs.renameSync(path.join(worktreeRoot, entry), path.join(holding, entry));
+  }
+  journal({ action: 'hold-initial-files', worktree: worktreeRoot, holding, entries, ok: true });
+  return holding;
+}
+
+function restoreInitialFiles(worktreeRoot, holding) {
+  if (!holding) return;
+  fs.cpSync(holding, worktreeRoot, { recursive: true, force: true, dereference: false });
+  fs.rmSync(holding, { recursive: true, force: true });
+  journal({ action: 'restore-initial-files', worktree: worktreeRoot, holding, ok: true });
+}
+
 /** Fast-forward the current branch to an exact commit. Refuses anything but a ff. */
 function fastForwardTo(worktreeRoot, oid) {
   return run('fast-forward', worktreeRoot, ['-C', worktreeRoot, 'merge', '--ff-only', oid], {
@@ -285,14 +347,18 @@ module.exports = {
   TransitionError,
   applyMergedFiles,
   applyPatch,
+  checkoutInitialCard,
   createBundle,
   deleteBranchRef,
   fastForwardTo,
   fetchBranch,
   forceMoveToCard,
+  holdInitialFiles,
   importBundle,
+  initializeRepo,
   moveToCard,
   parkCommit,
+  restoreInitialFiles,
   setBranchRef,
   setIndexTree,
 };

package/runtime/scripts/amalgm-mcp/workspace/wall.js

@@ -19,7 +19,7 @@ const { machineId, userId } = require('./identity');
 const { listRepoCards } = require('./cards');
 const { readCheckpoint, repoKeyOfCard } = require('./checkpoint');
 
-const WALL_CONTRACT = 'code-project@1';
+const WALL_CONTRACT = 'code-project@3';
 const PROJECT_DIR = path.join(AMALGM_DIR, 'state', 'code-projects');
 const REGISTRY_FILE = path.join(PROJECT_DIR, 'projects.json');
 const PUBLISH_QUIET_MS = 25;
@@ -74,22 +74,40 @@ function projectForRepo(repoKey) {
   const bound = readRegistry()[repoKey];
   const ownerUserId = bound?.ownerUserId || userId();
   const resourceId = bound?.resourceId || projectResourceId(repoKey, ownerUserId);
-  return resourceId ? { repoKey, resourceId, ownerUserId, file: projectFile(resourceId) } : null;
+  return resourceId ? {
+    repoKey,
+    resourceId,
+    ownerUserId,
+    path: bound?.path || null,
+    file: projectFile(resourceId),
+  } : null;
 }
 
-function bindProject(repoKey, resourceId, ownerUserId = null) {
+function bindProject(repoKey, resourceId, ownerUserId = null, localPath = null) {
   if (!repoKey || typeof repoKey !== 'string') throw new Error('repoKey is required');
   if (!/^shr_[A-Za-z0-9_-]{16,128}$/.test(String(resourceId || ''))) {
     throw new Error('resourceId must be an opaque shared resource id');
   }
+  if (localPath !== null && (typeof localPath !== 'string' || !path.isAbsolute(localPath))) {
+    throw new Error('path must be an absolute folder path');
+  }
   const registry = readRegistry();
+  const previous = registry[repoKey];
   registry[repoKey] = {
     resourceId,
     ownerUserId: ownerUserId || null,
+    path: localPath || previous?.path || null,
     joinedAt: new Date().toISOString(),
   };
   writeRegistry(registry);
-  if (service.started) ensureProjectBound(projectForRepo(repoKey)).catch(() => {});
+  if (service.started) {
+    ensureProjectBound(projectForRepo(repoKey))
+      .then(() => {
+        schedulePublish();
+        return require('./reducer').reduceNow();
+      })
+      .catch(() => {});
+  }
   return projectForRepo(repoKey);
 }
 
@@ -130,7 +148,29 @@ function readProjectWall(project) {
   for (const line of require('../state/docs').getDocText(project.file).split('\n')) {
     if (!line) continue;
     const entry = parseWallLine(line);
-    if (entry?.project === project.repoKey) entries.set(entry.machine, entry);
+    if (entry?.project !== project.repoKey) continue;
+    entries.set(entry.machine, {
+      ...entry,
+      resourceId: project.resourceId,
+      cards: entry.cards.map((card) => ({
+        ...card,
+        positionVersion: validVersion(card.positionVersion)
+          ? card.positionVersion
+          : officialVersion(project.resourceId, card.positionMutationId),
+        branches: (card.branches || []).map((ref) => ({
+          ...ref,
+          version: validVersion(ref.version)
+            ? ref.version
+            : officialVersion(project.resourceId, ref.mutationId),
+        })),
+        checkpoints: (card.checkpoints || []).map((checkpoint) => ({
+          ...checkpoint,
+          version: validVersion(checkpoint.version)
+            ? checkpoint.version
+            : officialVersion(project.resourceId, checkpoint.mutationId),
+        })),
+      })),
+    });
   }
   return [...entries.values()];
 }
@@ -140,6 +180,22 @@ function readWall(repoKey = null) {
   return selected.flatMap((project) => readProjectWall(project));
 }
 
+function publishedCardFor(card) {
+  const repoKey = repoKeyOfCard(card);
+  if (!repoKey) return null;
+  const own = readWall(repoKey).find((entry) => entry.machine === machineId());
+  const published = own?.cards?.find((candidate) => candidate.replica === card.replica);
+  if (
+    !published
+    || !Number.isInteger(published.positionVersion)
+    || published.positionVersion < 1
+    || published.head?.branch !== card.head?.branch
+    || published.head?.oid !== card.head?.oid
+    || Boolean(published.head?.detached) !== Boolean(card.head?.detached)
+  ) return null;
+  return published;
+}
+
 function samePosition(left, right) {
   const sameHead = left?.head?.branch === right?.head?.branch
     && left?.head?.oid === right?.head?.oid
@@ -165,6 +221,15 @@ function checkpointIdentity(checkpoint) {
   });
 }
 
+function validVersion(value) {
+  return Number.isInteger(value) && value > 0;
+}
+
+function knownMutation(resourceId, mutationId) {
+  if (!mutationId) return false;
+  return Boolean(require('../state/mutations').getMutation(`resource:${resourceId}`, mutationId));
+}
+
 function officialVersion(resourceId, mutationId) {
   if (!mutationId) return null;
   const mutation = require('../state/mutations').getMutation(`resource:${resourceId}`, mutationId);
@@ -180,30 +245,63 @@ function stampBranches(refs, previousBranches, mutationId, resourceId) {
     const before = previous.get(name);
     const oid = observed?.oid ?? null;
     const unchanged = before && (before.oid ?? null) === oid;
-    const mutation = unchanged && before.mutationId ? before.mutationId : mutationId;
-    const carried = unchanged && Number.isInteger(before.version) ? before.version : null;
+    const reusable = unchanged
+      && before.mutationId
+      && (validVersion(before.version) || knownMutation(resourceId, before.mutationId));
+    const mutation = reusable ? before.mutationId : mutationId;
+    const version = reusable
+      ? (validVersion(before.version) ? before.version : officialVersion(resourceId, mutation))
+      : null;
     return {
       name,
       oid,
       ...(observed?.objects ? { objects: observed.objects } : {}),
       mutationId: mutation,
-      version: carried ?? officialVersion(resourceId, mutation),
+      ...(validVersion(version) ? { version } : {}),
     };
   });
 }
 
+function sharedCard(card) {
+  return {
+    card: card.card,
+    machine: card.machine,
+    replica: card.replica,
+    repo: card.repo,
+    objects: card.objects,
+    kind: card.kind,
+    head: {
+      branch: card.head?.branch ?? null,
+      oid: card.head?.oid ?? null,
+      detached: Boolean(card.head?.detached),
+    },
+    health: card.health,
+  };
+}
+
+function isCommittedCard(card) {
+  return typeof card?.head?.oid === 'string' && /^[0-9a-f]{40,64}$/.test(card.head.oid);
+}
+
 function stampCards(cards, previousCards, mutationId, project) {
   const previousByReplica = new Map(
     (previousCards || []).filter((card) => card?.replica).map((card) => [card.replica, card]),
   );
   return cards.map((card) => {
     const previous = previousByReplica.get(card.replica);
-    const positionMutationId = samePosition(previous, card) && previous?.positionMutationId
-      ? previous.positionMutationId
-      : mutationId;
-    const carriedPosition = samePosition(previous, card)
-      && Number.isInteger(previous?.positionVersion)
-      ? previous.positionVersion
+    const reusablePosition = samePosition(previous, card)
+      && previous?.positionMutationId
+      && (
+        validVersion(previous.positionVersion)
+        || knownMutation(project.resourceId, previous.positionMutationId)
+      );
+    const positionMutationId = reusablePosition ? previous.positionMutationId : mutationId;
+    const positionVersion = reusablePosition
+      ? (
+        validVersion(previous.positionVersion)
+          ? previous.positionVersion
+          : officialVersion(project.resourceId, positionMutationId)
+      )
       : null;
     const checkpoint = readCheckpoint(machineId(), project.repoKey);
     const currentCheckpoint = checkpoint
@@ -211,26 +309,33 @@ function stampCards(cards, previousCards, mutationId, project) {
       && checkpoint.branch === card.head?.branch
       ? checkpoint
       : null;
-    const sameCheckpoint = checkpointIdentity(previous?.checkpoint) === checkpointIdentity(currentCheckpoint);
-    const checkpointMutationId = currentCheckpoint
-      ? (sameCheckpoint && previous?.checkpointMutationId ? previous.checkpointMutationId : mutationId)
-      : null;
-    const checkpointVersion = currentCheckpoint
-      ? (sameCheckpoint && Number.isInteger(previous?.checkpointVersion)
-        ? previous.checkpointVersion
-        : officialVersion(project.resourceId, checkpointMutationId))
-      : null;
-    const { refs, ...cardWithoutRawRefs } = card;
+    const sameBase = previous?.head?.oid === card.head?.oid
+      && previous?.head?.branch === card.head?.branch;
+    const history = sameBase && Array.isArray(previous?.checkpoints)
+      ? previous.checkpoints.map((entry) => {
+        const version = validVersion(entry.version)
+          ? entry.version
+          : officialVersion(project.resourceId, entry.mutationId);
+        return validVersion(version) ? { ...entry, version } : entry;
+      })
+      : [];
+    const last = history.at(-1);
+    const checkpoints = currentCheckpoint
+      ? (checkpointIdentity(last) === checkpointIdentity(currentCheckpoint)
+        ? history
+        : [...history, { ...currentCheckpoint, mutationId }])
+      : history;
     return {
-      ...cardWithoutRawRefs,
+      ...sharedCard(card),
       positionMutationId,
-      positionVersion: carriedPosition ?? officialVersion(project.resourceId, positionMutationId),
-      branches: stampBranches(refs, previous?.branches, mutationId, project.resourceId),
-      ...(currentCheckpoint ? {
-        checkpoint: currentCheckpoint,
-        checkpointMutationId,
-        checkpointVersion,
-      } : {}),
+      ...(validVersion(positionVersion) ? { positionVersion } : {}),
+      branches: stampBranches(
+        card.refs,
+        sameBase ? previous?.branches : [],
+        mutationId,
+        project.resourceId,
+      ),
+      ...(checkpoints.length ? { checkpoints } : {}),
     };
   });
 }
@@ -316,7 +421,10 @@ function publishWall(repoKey = null) {
   const selected = repoKey ? [projectForRepo(repoKey)].filter(Boolean) : projects();
   const results = selected.map((project) => publishProject(
     project,
-    allCards.filter((card) => repoKeyOfCard(card) === project.repoKey),
+    allCards.filter((card) => (
+      repoKeyOfCard(card) === project.repoKey
+      && isCommittedCard(card)
+    )),
   ));
   if (repoKey) return results[0] || { published: false, reason: 'project-missing', repoKey };
   return {
@@ -475,9 +583,11 @@ function wallStats() {
 module.exports = {
   WALL_CONTRACT,
   bindProject,
+  isCommittedCard,
   projectFile,
   projectForRepo,
   projectResourceId,
+  publishedCardFor,
   publishWall,
   readWall,
   startWallService,