trellis 3.1.30 → 3.1.33

package/dist/{index-ncckgtrk.js → index-rv1p47gp.js}

@@ -1,6 +1,8 @@
 // @bun
 import {
   BlobStore,
+  JsonOpLog,
+  LaneOpLog,
   addCriterion,
   assignIssue,
   blockIssue,
@@ -10,12 +12,14 @@ import {
   createBranch,
   createCheckpoint,
   createIssue,
+  createLaneMeta,
   createMilestone,
   decompose,
   deleteBranch,
   diffFileStates,
   diffOpRange,
   getActiveIssues,
+  getBranchHeadOpHash,
   getIssue,
   init_blob_store,
   init_branch,
@@ -23,39 +27,50 @@ import {
   init_decompose,
   init_diff,
   init_issue,
+  init_lane,
   init_merge,
   init_milestone,
+  init_op_log,
+  laneDir,
   listBranches,
   listCheckpoints,
   listIssues,
+  listLaneMetas,
   listMilestones,
   loadBranchState,
+  loadLaneMeta,
   pauseIssue,
   reopenIssue,
+  resolveLaneHeadFromJournal,
   resumeIssue,
   runCriteria,
   saveBranchState,
+  saveLaneMeta,
   setCriterionStatus,
+  shouldAdvanceBranchHead,
   startIssue,
   switchBranch,
   threeWayMerge,
+  threeWayTextMerge,
   triageIssue,
   unblockIssue,
-  updateIssue
-} from "./index-a2a394zz.js";
+  updateIssue,
+  updateLaneHead
+} from "./index-xhcp6xrn.js";
 import {
   getDecision,
   getDecisionChain,
   init_decisions,
   queryDecisions,
   recordDecision
-} from "./index-65z0xfjw.js";
+} from "./index-4cdr7x2x.js";
 import {
   DEFAULT_CONFIG,
   createVcsOp,
   init_ops,
-  init_types
-} from "./index-v9b4hqa7.js";
+  init_types,
+  isVcsOpKind
+} from "./index-nzb3am4f.js";
 import {
   EAVStore,
   init_eav_store
@@ -308,6 +323,9 @@ class Ingestion {
   getLastOpHash() {
     return this.lastOpHash;
   }
+  setLastOpHash(hash) {
+    this.lastOpHash = hash;
+  }
 }
 var EXT_LANGUAGE;
 var init_ingestion = __esm(() => {
@@ -5333,109 +5351,443 @@ var init_semantic = __esm(() => {
   init_semantic_merge();
 });
 
-// src/engine.ts
-import {
-  existsSync as existsSync4,
-  mkdirSync as mkdirSync3,
-  readFileSync as readFileSync4,
-  writeFileSync as writeFileSync3,
-  copyFileSync
-} from "fs";
-import { readFile as readFile2 } from "fs/promises";
-import { join as join5, dirname } from "path";
-
-class JsonOpLog {
-  ops = [];
-  filePath;
-  constructor(filePath) {
-    this.filePath = filePath;
+// src/vcs/lane-promote.ts
+function replayOpIntoStore(store, op) {
+  const d = decompose(op);
+  if (d.deleteFacts.length > 0)
+    store.deleteFacts(d.deleteFacts);
+  if (d.deleteLinks.length > 0)
+    store.deleteLinks(d.deleteLinks);
+  if (d.addFacts.length > 0)
+    store.addFacts(d.addFacts);
+  if (d.addLinks.length > 0)
+    store.addLinks(d.addLinks);
+}
+function resolveBranchHeadFromOps(ops, branchName) {
+  for (let i = ops.length - 1;i >= 0; i--) {
+    const op = ops[i];
+    if (op.kind === "vcs:branchAdvance" && op.vcs?.branchName === branchName && op.vcs.targetOpHash) {
+      return op.vcs.targetOpHash;
+    }
+  }
+  return ops[ops.length - 1]?.hash;
+}
+function buildStoreUpTo(ops, atOpHash) {
+  const store = new EAVStore;
+  for (const op of ops) {
+    replayOpIntoStore(store, op);
+    if (atOpHash && op.hash === atOpHash)
+      break;
   }
-  load() {
-    if (existsSync4(this.filePath)) {
-      const raw = readFileSync4(this.filePath, "utf-8");
-      try {
-        this.ops = JSON.parse(raw);
-      } catch (err) {
-        const backupPath = this.filePath + ".bak";
-        if (existsSync4(backupPath)) {
-          const backupRaw = readFileSync4(backupPath, "utf-8");
-          this.ops = JSON.parse(backupRaw);
-          writeFileSync3(this.filePath, backupRaw);
-        } else {
-          throw new Error(`Corrupted ops.json and no backup found. Run \`trellis repair\` to attempt recovery.`);
-        }
+  return store;
+}
+function getFactValue(store, entity, attribute) {
+  const facts = store.getFactsByEntity(entity).filter((f) => f.a === attribute);
+  return facts[facts.length - 1]?.v;
+}
+function entityAttributes(store, entity) {
+  const map = new Map;
+  for (const fact of store.getFactsByEntity(entity)) {
+    map.set(fact.a, fact.v);
+  }
+  return map;
+}
+function collectTouchedAttributes(op) {
+  const d = decompose(op);
+  const map = new Map;
+  const touch = (fact) => {
+    if (!map.has(fact.e))
+      map.set(fact.e, new Set);
+    map.get(fact.e).add(fact.a);
+  };
+  for (const f of d.addFacts)
+    touch(f);
+  for (const f of d.deleteFacts)
+    touch(f);
+  return map;
+}
+function collectTouchedEntities(op) {
+  const d = decompose(op);
+  const entities = new Set;
+  for (const f of [...d.addFacts, ...d.deleteFacts])
+    entities.add(f.e);
+  for (const l of [...d.addLinks, ...d.deleteLinks]) {
+    entities.add(l.e1);
+    entities.add(l.e2);
+  }
+  return entities;
+}
+function atomsEqual(a, b) {
+  if (a === b)
+    return true;
+  if (a === undefined || b === undefined)
+    return false;
+  return String(a) === String(b);
+}
+function buildLaneFileState(laneOps, throughIndex) {
+  const slice = laneOps.slice(0, throughIndex + 1);
+  return buildFileStateAtOp(slice);
+}
+function filePathsFromOp(op) {
+  const paths = [];
+  if (op.vcs?.filePath)
+    paths.push(op.vcs.filePath);
+  if (op.vcs?.oldFilePath)
+    paths.push(op.vcs.oldFilePath);
+  return paths;
+}
+function detectEntityConflicts(op, baseStore, headStore) {
+  const conflicts = [];
+  const d = decompose(op);
+  const touchedEntities = collectTouchedEntities(op);
+  const laneAttrsByEntity = collectTouchedAttributes(op);
+  for (const fact of d.addFacts) {
+    const headValue = getFactValue(headStore, fact.e, fact.a);
+    const baseValue = getFactValue(baseStore, fact.e, fact.a);
+    if (atomsEqual(headValue, fact.v))
+      continue;
+    if (!atomsEqual(headValue, baseValue) && headValue !== undefined) {
+      conflicts.push({
+        class: "hard",
+        laneOpHash: op.hash,
+        entityId: fact.e,
+        attribute: fact.a,
+        integrationValue: headValue,
+        laneValue: fact.v,
+        suggestion: "manual",
+        message: `Integration changed ${fact.e}.${fact.a} since fork`
+      });
+    }
+  }
+  for (const entityId of touchedEntities) {
+    const laneAttrs = laneAttrsByEntity.get(entityId) ?? new Set;
+    if (laneAttrs.size === 0)
+      continue;
+    const baseAttrs = entityAttributes(baseStore, entityId);
+    const headAttrs = entityAttributes(headStore, entityId);
+    for (const [attribute, headValue] of headAttrs) {
+      if (laneAttrs.has(attribute))
+        continue;
+      const baseValue = baseAttrs.get(attribute);
+      if (!atomsEqual(headValue, baseValue)) {
+        conflicts.push({
+          class: "soft",
+          laneOpHash: op.hash,
+          entityId,
+          attribute,
+          integrationValue: headValue,
+          suggestion: "manual",
+          message: `Integration updated ${entityId}.${attribute} while lane touched the same entity`
+        });
       }
     }
   }
-  append(op) {
-    this.ops.push(op);
-    this.flush();
+  return conflicts;
+}
+function blobText(blobStore, hash) {
+  if (!hash || !blobStore)
+    return;
+  const content = blobStore.get(hash);
+  if (!content)
+    return;
+  const text = content.toString("utf-8");
+  return text.endsWith(`
+`) ? text.slice(0, -1) : text;
+}
+function mergeLaneFile(path, base, ours, theirs, blobStore) {
+  const b = base.get(path);
+  const o = ours.get(path);
+  const t = theirs.get(path);
+  const baseHash = b && !b.deleted ? b.contentHash : undefined;
+  const oursHash = o && !o.deleted ? o.contentHash : undefined;
+  const theirsHash = t && !t.deleted ? t.contentHash : undefined;
+  if (oursHash === theirsHash)
+    return { clean: true };
+  if (theirsHash === baseHash && oursHash !== baseHash)
+    return { clean: true };
+  if (oursHash === baseHash && theirsHash !== baseHash) {
+    const theirsContent2 = blobText(blobStore, theirsHash);
+    return { clean: true, merged: theirsContent2 };
+  }
+  const baseContent = blobText(blobStore, baseHash) ?? "";
+  const oursContent = blobText(blobStore, oursHash);
+  const theirsContent = blobText(blobStore, theirsHash);
+  if (oursContent === undefined || theirsContent === undefined) {
+    return { clean: false, conflictKind: "modify-modify" };
+  }
+  const textResult = threeWayTextMerge(baseContent, oursContent, theirsContent);
+  if (textResult.clean) {
+    return { clean: true, merged: textResult.merged };
+  }
+  return { clean: false, conflictKind: "modify-modify" };
+}
+function detectFileConflict(op, integrationOps, laneOps, laneOpIndex, baseOpHash, snapshotHead, blobStore) {
+  const paths = filePathsFromOp(op);
+  if (paths.length === 0)
+    return {};
+  const base = buildFileStateAtOp(integrationOps, baseOpHash);
+  const ours = buildFileStateAtOp(integrationOps, snapshotHead);
+  const theirs = buildLaneFileState(laneOps, laneOpIndex);
+  for (const path of paths) {
+    const baseState = base.get(path);
+    const headState = ours.get(path);
+    const laneState = theirs.get(path);
+    const baseHash = baseState && !baseState.deleted ? baseState.contentHash : undefined;
+    const headHash = headState && !headState.deleted ? headState.contentHash : undefined;
+    const laneHash = laneState && !laneState.deleted ? laneState.contentHash : undefined;
+    if (headHash === laneHash)
+      continue;
+    if (headHash === baseHash && laneHash !== baseHash)
+      continue;
+    if (laneHash === baseHash && headHash !== baseHash)
+      continue;
+    const mergeResult = mergeLaneFile(path, base, ours, theirs, blobStore);
+    if (mergeResult.clean) {
+      if (mergeResult.merged !== undefined) {
+        return { mergedContent: mergeResult.merged };
+      }
+      continue;
+    }
+    return {
+      conflict: {
+        class: "file",
+        laneOpHash: op.hash,
+        filePath: path,
+        suggestion: "manual",
+        message: `File conflict on ${path} (${mergeResult.conflictKind ?? "modify-modify"})`
+      }
+    };
   }
-  readAll() {
-    return [...this.ops];
+  return {};
+}
+function isBlockingConflict(conflict) {
+  return conflict.class === "soft" || conflict.class === "hard" || conflict.class === "file";
+}
+async function planLanePromote(params) {
+  const {
+    laneId,
+    meta,
+    targetBranch,
+    snapshotHead,
+    integrationOps,
+    laneOps,
+    parentLaneOps,
+    blobStore
+  } = params;
+  const baseStore = buildStoreUpTo(integrationOps, meta.baseOpHash);
+  const headStore = buildStoreUpTo(integrationOps, snapshotHead);
+  const fileLaneOps = meta.forkKind === "child" && parentLaneOps?.length ? [...parentLaneOps, ...laneOps] : laneOps;
+  const childOpOffset = parentLaneOps?.length ?? 0;
+  const opsToReplay = [];
+  const conflicts = [];
+  let safeOpCount = 0;
+  for (let i = 0;i < laneOps.length; i++) {
+    const op = laneOps[i];
+    if (SKIP_PROMOTE_KINDS.has(op.kind))
+      continue;
+    if (FILE_OP_KINDS2.has(op.kind)) {
+      const fileResult = detectFileConflict(op, integrationOps, fileLaneOps, childOpOffset + i, meta.baseOpHash, snapshotHead, blobStore);
+      if (fileResult.conflict) {
+        conflicts.push(fileResult.conflict);
+        continue;
+      }
+      opsToReplay.push({
+        sourceOp: op,
+        mergedContent: fileResult.mergedContent
+      });
+      safeOpCount++;
+      continue;
+    }
+    const decomposed = decompose(op);
+    if (decomposed.addFacts.length > 0 && decomposed.deleteFacts.length === 0 && decomposed.addFacts.every((fact) => atomsEqual(getFactValue(headStore, fact.e, fact.a), fact.v))) {
+      continue;
+    }
+    const entityConflicts = detectEntityConflicts(op, baseStore, headStore);
+    const blockingEntity = entityConflicts.filter(isBlockingConflict);
+    conflicts.push(...entityConflicts);
+    if (blockingEntity.length > 0)
+      continue;
+    opsToReplay.push({ sourceOp: op });
+    safeOpCount++;
+    replayOpIntoStore(headStore, op);
   }
-  getLastOp() {
-    return this.ops.length > 0 ? this.ops[this.ops.length - 1] : undefined;
+  const blockingConflicts = conflicts.filter(isBlockingConflict);
+  return {
+    laneId,
+    targetBranch,
+    snapshotHead,
+    baseOpHash: meta.baseOpHash,
+    opsToReplay,
+    conflicts,
+    blockingConflicts,
+    safeOpCount,
+    canPromote: blockingConflicts.length === 0 && opsToReplay.length > 0
+  };
+}
+async function rechainOpForIntegration(op, previousHash) {
+  if (!isVcsOpKindSafe(op.kind)) {
+    throw new Error(`Cannot rechain op kind '${op.kind}' for integration replay`);
   }
-  count() {
-    return this.ops.length;
+  return createVcsOp(op.kind, {
+    agentId: op.agentId,
+    previousHash,
+    vcs: { ...op.vcs }
+  });
+}
+function isVcsOpKindSafe(kind) {
+  return kind.startsWith("vcs:");
+}
+function formatPromoteExplain(plan) {
+  const lines = [
+    `Lane promote plan: ${plan.laneId}`,
+    `  Target branch: ${plan.targetBranch}`,
+    `  Fork base:     ${plan.baseOpHash}`,
+    `  Snapshot head: ${plan.snapshotHead}`,
+    `  Ops to replay: ${plan.opsToReplay.length}`,
+    `  Safe ops:      ${plan.safeOpCount}`
+  ];
+  if (plan.blockingConflicts.length === 0) {
+    lines.push("", plan.canPromote ? "\u2713 Ready to promote" : "No ops to replay");
+    return lines.join(`
+`);
   }
-  flush() {
-    const dir = dirname(this.filePath);
-    if (!existsSync4(dir))
-      mkdirSync3(dir, { recursive: true });
-    if (existsSync4(this.filePath)) {
-      const backupPath = this.filePath + ".bak";
-      try {
-        copyFileSync(this.filePath, backupPath);
-      } catch {}
+  lines.push("", `Blocking conflicts (${plan.blockingConflicts.length}):`);
+  for (const c of plan.blockingConflicts) {
+    const where = c.filePath ?? (c.entityId && c.attribute ? `${c.entityId}.${c.attribute}` : c.entityId);
+    lines.push(`  [${c.class}] ${where ?? c.laneOpHash.slice(0, 24)}`);
+    if (c.message)
+      lines.push(`    ${c.message}`);
+    if (c.integrationValue !== undefined) {
+      lines.push(`    integration: ${String(c.integrationValue)}`);
     }
-    writeFileSync3(this.filePath, JSON.stringify(this.ops, null, 2));
-  }
-  static repair(filePath) {
-    if (!existsSync4(filePath)) {
-      return { recovered: 0, lost: 0 };
+    if (c.laneValue !== undefined) {
+      lines.push(`    lane:        ${String(c.laneValue)}`);
     }
-    const raw = readFileSync4(filePath, "utf-8");
-    try {
-      const ops = JSON.parse(raw);
-      return { recovered: ops.length, lost: 0 };
-    } catch {}
-    const lastHash = raw.lastIndexOf('"hash": "trellis:op:');
-    if (lastHash === -1) {
-      const bakPath = filePath + ".bak";
-      if (existsSync4(bakPath)) {
-        const bakRaw = readFileSync4(bakPath, "utf-8");
-        try {
-          const ops = JSON.parse(bakRaw);
-          writeFileSync3(filePath, bakRaw);
-          return { recovered: ops.length, lost: 0 };
-        } catch {}
+  }
+  return lines.join(`
+`);
+}
+var SKIP_PROMOTE_KINDS, FILE_OP_KINDS2;
+var init_lane_promote = __esm(() => {
+  init_eav_store();
+  init_decompose();
+  init_diff();
+  init_merge();
+  init_ops();
+  SKIP_PROMOTE_KINDS = new Set([
+    "vcs:branchAdvance",
+    "vcs:laneCreate",
+    "vcs:laneDrop",
+    "vcs:lanePromoteStart",
+    "vcs:lanePromoteComplete",
+    "vcs:lanePromoteAbort"
+  ]);
+  FILE_OP_KINDS2 = new Set([
+    "vcs:fileAdd",
+    "vcs:fileModify",
+    "vcs:fileDelete",
+    "vcs:fileRename"
+  ]);
+});
+
+// src/vcs/lane-materialize.ts
+function emptyMaterializationStats() {
+  return {
+    integrationOpsReplayed: 0,
+    laneOpsReplayed: 0,
+    integrationCacheHit: false
+  };
+}
+function replayOpIntoStore2(store, op) {
+  const d = decompose(op);
+  if (d.deleteFacts.length > 0)
+    store.deleteFacts(d.deleteFacts);
+  if (d.deleteLinks.length > 0)
+    store.deleteLinks(d.deleteLinks);
+  if (d.addFacts.length > 0)
+    store.addFacts(d.addFacts);
+  if (d.addLinks.length > 0)
+    store.addLinks(d.addLinks);
+}
+function cloneStore(source) {
+  const clone = new EAVStore;
+  clone.restore(source.snapshot());
+  return clone;
+}
+function materializeIntegrationOps(ops, cache, tailHash) {
+  if (cache && cache.tailHash === tailHash) {
+    return {
+      store: cache.store,
+      cache,
+      stats: {
+        integrationOpsReplayed: 0,
+        laneOpsReplayed: 0,
+        integrationCacheHit: true,
+        integrationTailHash: tailHash
       }
-      writeFileSync3(filePath, "[]");
-      return { recovered: 0, lost: -1 };
-    }
-    const endOfLine = raw.indexOf(`
-`, lastHash);
-    const closingBrace = raw.indexOf("  }", endOfLine);
-    if (closingBrace === -1) {
-      writeFileSync3(filePath, "[]");
-      return { recovered: 0, lost: -1 };
-    }
-    const fixed = raw.slice(0, closingBrace + 3) + `
-]`;
-    try {
-      const ops = JSON.parse(fixed);
-      writeFileSync3(filePath + ".corrupted", raw);
-      writeFileSync3(filePath, fixed);
-      return { recovered: ops.length, lost: 0 };
-    } catch {
-      writeFileSync3(filePath + ".corrupted", raw);
-      writeFileSync3(filePath, "[]");
-      return { recovered: 0, lost: -1 };
+    };
+  }
+  const store = new EAVStore;
+  for (const op of ops) {
+    replayOpIntoStore2(store, op);
+  }
+  return {
+    store,
+    cache: { tailHash, store },
+    stats: {
+      integrationOpsReplayed: ops.length,
+      laneOpsReplayed: 0,
+      integrationCacheHit: false,
+      integrationTailHash: tailHash
     }
+  };
+}
+function overlayLaneOps(integrationStore, laneOps) {
+  const store = cloneStore(integrationStore);
+  for (const op of laneOps) {
+    replayOpIntoStore2(store, op);
   }
+  return { store, laneOpsReplayed: laneOps.length };
 }
+function materializeChildForkEntry(integrationOps, baseOpHash, parentLaneOps, childLaneOps) {
+  const store = new EAVStore;
+  let integrationReplayed = 0;
+  for (const op of integrationOps) {
+    replayOpIntoStore2(store, op);
+    integrationReplayed++;
+    if (op.hash === baseOpHash)
+      break;
+  }
+  for (const op of parentLaneOps) {
+    replayOpIntoStore2(store, op);
+  }
+  for (const op of childLaneOps) {
+    replayOpIntoStore2(store, op);
+  }
+  return {
+    store,
+    stats: {
+      integrationOpsReplayed: integrationReplayed,
+      laneOpsReplayed: parentLaneOps.length + childLaneOps.length,
+      integrationCacheHit: false,
+      integrationTailHash: integrationOps[integrationOps.length - 1]?.hash
+    }
+  };
+}
+var init_lane_materialize = __esm(() => {
+  init_eav_store();
+  init_decompose();
+});
+
+// src/engine.ts
+import {
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync3,
+  readFileSync as readFileSync4,
+  writeFileSync as writeFileSync3
+} from "fs";
+import { readFile as readFile2 } from "fs/promises";
+import { join as join5 } from "path";
 function parseIgnoreFile(filePath) {
   if (!existsSync4(filePath))
     return [];
@@ -5489,6 +5841,10 @@ class TrellisVcsEngine {
   checkpointThreshold = 100;
   _pendingAutoCheckpoint = false;
   _blobStore = null;
+  activeLaneId;
+  activeLaneLog = null;
+  integrationCache = null;
+  materializationStats = emptyMaterializationStats();
   constructor(opts) {
     const gitignorePatterns = readIgnorePatterns(opts.rootPath);
     const mergedIgnore = [
@@ -5533,7 +5889,7 @@ class TrellisVcsEngine {
         branchName: this.config.defaultBranch
       }
     });
-    this.applyOp(branchOp);
+    await this.applyOp(branchOp);
     const scanner = new FileWatcher({
       rootPath: this.config.rootPath,
       ignorePatterns: [...this.config.ignorePatterns, ".trellis"],
@@ -5577,7 +5933,7 @@ class TrellisVcsEngine {
           size: event.size
         }
       });
-      this.applyOp(op);
+      await this.applyOp(op);
       opsCreated++;
       const scannedFiles = opsCreated - 1;
       if (scannedFiles % 25 === 0 || scannedFiles === events.length) {
@@ -5626,16 +5982,19 @@ class TrellisVcsEngine {
       this.config.defaultBranch = persisted.defaultBranch;
     }
     this.loadCurrentBranch();
-    const ops = this.opLog.readAll();
-    for (const op of ops) {
-      this.replayOp(op);
-    }
-    return { opsReplayed: ops.length };
+    const integrationOps = this.opLog.readAll();
+    const laneOps = this.activeLaneLog ? this.activeLaneLog.readAll() : undefined;
+    const activeMeta = this.activeLaneId ? this.getLaneMeta(this.activeLaneId) : undefined;
+    this.refreshMaterializedStore(integrationOps, laneOps, activeMeta);
+    const laneReplayed = this.materializationStats.laneOpsReplayed;
+    return {
+      opsReplayed: this.materializationStats.integrationOpsReplayed + laneReplayed
+    };
   }
   watch() {
     this.ingestion = new Ingestion({
       agentId: this.agentId,
-      lastOpHash: this.opLog.getLastOp()?.hash,
+      lastOpHash: this.getActiveJournal().getLastOp()?.hash,
       onOp: (op) => this.applyOp(op)
     });
     this.watcher = new FileWatcher({
@@ -5740,7 +6099,11 @@ class TrellisVcsEngine {
   switchBranch(name) {
     switchBranch(this._ctx(), name);
     this.currentBranch = name;
-    saveBranchState(this.config.rootPath, { currentBranch: name });
+    const state = loadBranchState(this.config.rootPath);
+    saveBranchState(this.config.rootPath, {
+      ...state,
+      currentBranch: name
+    });
   }
   listBranches() {
     return listBranches(this._ctx(), this.currentBranch);
@@ -5753,6 +6116,344 @@ class TrellisVcsEngine {
   getCurrentBranch() {
     return this.currentBranch;
   }
+  getBranchHeadOpHash(branchName = this.currentBranch) {
+    return getBranchHeadOpHash(this._ctx(), branchName);
+  }
+  getActiveLaneId() {
+    return this.activeLaneId;
+  }
+  getMaterializationStats() {
+    return { ...this.materializationStats };
+  }
+  listLanes() {
+    return listLaneMetas(this.trellisDir());
+  }
+  getIntegrationOpCount() {
+    return this.opLog.count();
+  }
+  getLaneOpCount(laneId) {
+    const log = new LaneOpLog(laneDir(this.trellisDir(), laneId));
+    log.load();
+    return log.count();
+  }
+  getLaneMeta(laneId) {
+    return loadLaneMeta(this.trellisDir(), laneId);
+  }
+  findLaneForIssue(issueId) {
+    const normalized = issueId.startsWith("issue:") ? issueId : `issue:${issueId}`;
+    return this.listLanes().find((lane) => lane.issueId === normalized && lane.status === "active");
+  }
+  async syncEnvLaneFromEnv() {
+    const laneId = process.env.TRELLIS_LANE_ID?.trim();
+    if (!laneId)
+      return;
+    if (this.activeLaneId === laneId)
+      return;
+    if (this.activeLaneId) {
+      throw new Error(`TRELLIS_LANE_ID=${laneId} conflicts with active lane '${this.activeLaneId}'`);
+    }
+    await this.enterLane(laneId);
+  }
+  summarizeLane(laneId) {
+    const meta = this.getLaneMeta(laneId);
+    if (!meta) {
+      throw new Error(`Lane not found: ${laneId}`);
+    }
+    const log = new LaneOpLog(laneDir(this.trellisDir(), laneId));
+    log.load();
+    const ops = log.readAll();
+    const filePaths = [
+      ...new Set(ops.map((op) => op.vcs?.filePath ?? op.vcs?.oldFilePath).filter((p) => Boolean(p)))
+    ];
+    return {
+      meta,
+      ops,
+      filePaths,
+      integrationHead: this.getBranchHeadOpHash(meta.targetBranch)
+    };
+  }
+  async createLane(opts) {
+    if (this.activeLaneId) {
+      throw new Error(`Cannot create a lane while inside lane '${this.activeLaneId}' \u2014 leave first`);
+    }
+    const baseBranch = opts?.fromBranch ?? this.currentBranch;
+    const baseOpHash = getBranchHeadOpHash(this._ctx(), baseBranch) ?? this.opLog.getLastOp()?.hash;
+    if (!baseOpHash) {
+      throw new Error(`No integration head on branch '${baseBranch}' to fork lane from`);
+    }
+    const meta = createLaneMeta(this.trellisDir(), {
+      baseBranch,
+      baseOpHash,
+      targetBranch: opts?.targetBranch ?? baseBranch,
+      agentId: this.agentId,
+      issueId: opts?.issueId,
+      sessionId: opts?.sessionId,
+      worktreePath: opts?.worktreePath
+    });
+    const op = await createVcsOp("vcs:laneCreate", {
+      agentId: this.agentId,
+      previousHash: this.opLog.getLastOp()?.hash,
+      vcs: {
+        laneId: meta.id,
+        baseBranch: meta.baseBranch,
+        baseOpHash: meta.baseOpHash,
+        targetBranch: meta.targetBranch,
+        issueId: meta.issueId
+      }
+    });
+    await this.applyOp(op);
+    return meta;
+  }
+  async forkLane(parentLaneId, opts) {
+    if (this.activeLaneId) {
+      throw new Error(`Cannot fork a lane while inside lane '${this.activeLaneId}' \u2014 leave first`);
+    }
+    const parent = loadLaneMeta(this.trellisDir(), parentLaneId);
+    if (!parent) {
+      throw new Error(`Lane not found: ${parentLaneId}`);
+    }
+    if (parent.status !== "active") {
+      throw new Error(`Lane '${parentLaneId}' is ${parent.status} \u2014 cannot fork`);
+    }
+    const forkKind = opts?.forkKind ?? "sibling";
+    const forkedAt = new Date().toISOString();
+    const parentLog = new LaneOpLog(laneDir(this.trellisDir(), parentLaneId));
+    parentLog.load();
+    const parentLaneOps = parentLog.readAll();
+    const parentHead = resolveLaneHeadFromJournal(parent, parentLaneOps);
+    if (forkKind === "child") {
+      const meta2 = createLaneMeta(this.trellisDir(), {
+        baseBranch: parent.baseBranch,
+        baseOpHash: parent.baseOpHash,
+        targetBranch: parent.targetBranch,
+        agentId: this.agentId,
+        issueId: opts?.issueId ?? parent.issueId,
+        sessionId: opts?.sessionId,
+        worktreePath: opts?.worktreePath,
+        parentLaneId: parent.id,
+        forkKind: "child",
+        forkedAt,
+        virtualBaseOpHash: parentHead
+      });
+      const op2 = await createVcsOp("vcs:laneCreate", {
+        agentId: this.agentId,
+        previousHash: this.opLog.getLastOp()?.hash,
+        vcs: {
+          laneId: meta2.id,
+          baseBranch: meta2.baseBranch,
+          baseOpHash: meta2.baseOpHash,
+          targetBranch: meta2.targetBranch,
+          issueId: meta2.issueId,
+          sessionId: meta2.sessionId,
+          parentLaneId: parent.id,
+          forkKind: "child",
+          virtualBaseOpHash: parentHead
+        }
+      });
+      await this.applyOp(op2);
+      return meta2;
+    }
+    const meta = createLaneMeta(this.trellisDir(), {
+      baseBranch: parent.baseBranch,
+      baseOpHash: parent.baseOpHash,
+      targetBranch: parent.targetBranch,
+      agentId: this.agentId,
+      issueId: opts?.issueId ?? parent.issueId,
+      sessionId: opts?.sessionId,
+      worktreePath: opts?.worktreePath,
+      parentLaneId: parent.id,
+      forkKind: "sibling",
+      forkedAt
+    });
+    const op = await createVcsOp("vcs:laneCreate", {
+      agentId: this.agentId,
+      previousHash: this.opLog.getLastOp()?.hash,
+      vcs: {
+        laneId: meta.id,
+        baseBranch: meta.baseBranch,
+        baseOpHash: meta.baseOpHash,
+        targetBranch: meta.targetBranch,
+        issueId: meta.issueId,
+        sessionId: meta.sessionId,
+        parentLaneId: parent.id,
+        forkKind: "sibling"
+      }
+    });
+    await this.applyOp(op);
+    return meta;
+  }
+  async enterLane(laneId) {
+    if (this.activeLaneId) {
+      throw new Error(`Already in lane '${this.activeLaneId}' \u2014 leave before entering another`);
+    }
+    const meta = loadLaneMeta(this.trellisDir(), laneId);
+    if (!meta) {
+      throw new Error(`Lane not found: ${laneId}`);
+    }
+    if (meta.status !== "active") {
+      throw new Error(`Lane '${laneId}' is ${meta.status} \u2014 cannot enter`);
+    }
+    this.activeLaneId = laneId;
+    this.activeLaneLog = new LaneOpLog(laneDir(this.trellisDir(), laneId));
+    this.activeLaneLog.load();
+    this.refreshMaterializedStore(this.opLog.readAll(), this.activeLaneLog.readAll(), meta);
+    saveBranchState(this.config.rootPath, {
+      currentBranch: this.currentBranch,
+      activeLaneId: laneId
+    });
+    this.syncIngestionLastOpHash();
+    return meta;
+  }
+  async leaveLane() {
+    if (!this.activeLaneId)
+      return;
+    this.activeLaneId = undefined;
+    this.activeLaneLog = null;
+    saveBranchState(this.config.rootPath, {
+      currentBranch: this.currentBranch
+    });
+    this.restoreIntegrationOnlyStore();
+    this.syncIngestionLastOpHash();
+  }
+  async dropLane(laneId) {
+    if (this.activeLaneId === laneId) {
+      await this.leaveLane();
+    }
+    const meta = loadLaneMeta(this.trellisDir(), laneId);
+    if (!meta) {
+      throw new Error(`Lane not found: ${laneId}`);
+    }
+    if (meta.status === "dropped")
+      return;
+    meta.status = "dropped";
+    meta.updatedAt = new Date().toISOString();
+    saveLaneMeta(this.trellisDir(), meta);
+    const op = await createVcsOp("vcs:laneDrop", {
+      agentId: this.agentId,
+      previousHash: this.opLog.getLastOp()?.hash,
+      vcs: {
+        laneId: meta.id,
+        laneStatus: "dropped"
+      }
+    });
+    await this.applyOp(op);
+  }
+  async promoteLane(laneId, opts) {
+    const meta = this.getLaneMeta(laneId);
+    if (!meta) {
+      throw new Error(`Lane not found: ${laneId}`);
+    }
+    if (meta.status !== "active") {
+      throw new Error(`Lane '${laneId}' is ${meta.status} \u2014 cannot promote`);
+    }
+    if (this.activeLaneId === laneId) {
+      await this.leaveLane();
+    } else if (this.activeLaneId) {
+      throw new Error(`Cannot promote while inside lane '${this.activeLaneId}' \u2014 leave first`);
+    }
+    const targetBranch = opts?.toBranch ?? meta.targetBranch;
+    const integrationOps = this.opLog.readAll();
+    const snapshotHead = resolveBranchHeadFromOps(integrationOps, targetBranch) ?? getBranchHeadOpHash(this._ctx(), targetBranch);
+    if (!snapshotHead) {
+      throw new Error(`No head on branch '${targetBranch}' to promote onto`);
+    }
+    const laneLog = new LaneOpLog(laneDir(this.trellisDir(), laneId));
+    laneLog.load();
+    const laneOps = laneLog.readAll();
+    let parentLaneOps;
+    if (meta.forkKind === "child" && meta.parentLaneId) {
+      parentLaneOps = this.loadLaneJournalOps(meta.parentLaneId);
+    }
+    const plan = await planLanePromote({
+      laneId,
+      meta,
+      targetBranch,
+      snapshotHead,
+      integrationOps: this.opLog.readAll(),
+      laneOps,
+      parentLaneOps,
+      blobStore: this._blobStore
+    });
+    if (opts?.dryRun || !plan.canPromote) {
+      return { ...plan, promoted: false };
+    }
+    meta.status = "promoting";
+    meta.updatedAt = new Date().toISOString();
+    saveLaneMeta(this.trellisDir(), meta);
+    const startOp = await createVcsOp("vcs:lanePromoteStart", {
+      agentId: this.agentId,
+      previousHash: this.opLog.getLastOp()?.hash,
+      vcs: {
+        laneId,
+        targetBranch,
+        baseOpHash: meta.baseOpHash
+      }
+    });
+    await this.applyOp(startOp, { skipBranchAdvance: true });
+    const currentHead = resolveBranchHeadFromOps(this.opLog.readAll(), targetBranch) ?? getBranchHeadOpHash(this._ctx(), targetBranch);
+    if (currentHead !== snapshotHead) {
+      meta.status = "active";
+      meta.updatedAt = new Date().toISOString();
+      saveLaneMeta(this.trellisDir(), meta);
+      const abortOp = await createVcsOp("vcs:lanePromoteAbort", {
+        agentId: this.agentId,
+        previousHash: this.opLog.getLastOp()?.hash,
+        vcs: { laneId }
+      });
+      await this.applyOp(abortOp, { skipBranchAdvance: true });
+      throw new Error(`Integration head moved during promote \u2014 retry after integration settles`);
+    }
+    let previousHash = this.opLog.getLastOp()?.hash;
+    let lastReplayedHash;
+    let opsAppended = 0;
+    for (const action of plan.opsToReplay) {
+      let opToApply;
+      if (action.mergedContent !== undefined && action.sourceOp.vcs?.filePath) {
+        const contentHash = await this._blobStore.put(Buffer.from(action.mergedContent, "utf-8"));
+        opToApply = await createVcsOp("vcs:fileModify", {
+          agentId: action.sourceOp.agentId,
+          previousHash,
+          vcs: {
+            filePath: action.sourceOp.vcs.filePath,
+            contentHash,
+            laneId: action.sourceOp.vcs.laneId ?? laneId
+          }
+        });
+      } else {
+        opToApply = await rechainOpForIntegration(action.sourceOp, previousHash);
+      }
+      await this.applyOp(opToApply, { skipBranchAdvance: true });
+      previousHash = opToApply.hash;
+      lastReplayedHash = opToApply.hash;
+      opsAppended++;
+    }
+    if (lastReplayedHash) {
+      await this.appendBranchAdvance(lastReplayedHash);
+    }
+    const completeOp = await createVcsOp("vcs:lanePromoteComplete", {
+      agentId: this.agentId,
+      previousHash: this.opLog.getLastOp()?.hash,
+      vcs: {
+        laneId,
+        targetBranch,
+        laneStatus: "promoted"
+      }
+    });
+    await this.applyOp(completeOp, { skipBranchAdvance: true });
+    meta.status = "promoted";
+    meta.headOpHash = lastReplayedHash ?? meta.headOpHash;
+    meta.updatedAt = new Date().toISOString();
+    saveLaneMeta(this.trellisDir(), meta);
+    this.invalidateIntegrationCache();
+    this.refreshMaterializedStore(this.opLog.readAll());
+    this.syncIngestionLastOpHash();
+    return {
+      ...plan,
+      promoted: true,
+      integrationOpsAppended: opsAppended + 2,
+      completeOpHash: completeOp.hash
+    };
+  }
   async createMilestone(message, opts) {
     const op = await createMilestone(this._ctx(), message, opts);
     await this.flushAutoCheckpoint();
@@ -5885,7 +6586,10 @@ class TrellisVcsEngine {
     await this.flushAutoCheckpoint();
     return op;
   }
-  async startIssue(id) {
+  async startIssue(id, opts) {
+    if (this.activeLaneId) {
+      await this.leaveLane();
+    }
     const issue = getIssue(this._ctx(), id);
     if (!issue)
       throw new Error(`Issue ${id} not found.`);
@@ -5894,16 +6598,27 @@ class TrellisVcsEngine {
     await this.createBranch(branchName);
     const op = await startIssue(this._ctx(), id, branchName);
     this.switchBranch(branchName);
+    if (opts?.lane !== false) {
+      const issueKey = id.startsWith("issue:") ? id : `issue:${id}`;
+      let lane = this.findLaneForIssue(issueKey);
+      if (!lane) {
+        lane = await this.createLane({ issueId: issueKey });
+      }
+      await this.enterLane(lane.id);
+    }
     await this.flushAutoCheckpoint();
     return op;
   }
   async pauseIssue(id, note) {
+    if (this.activeLaneId) {
+      await this.leaveLane();
+    }
     const op = await pauseIssue(this._ctx(), id, note);
     this.switchBranch(this.config.defaultBranch);
     await this.flushAutoCheckpoint();
     return op;
   }
-  async resumeIssue(id) {
+  async resumeIssue(id, opts) {
     const issue = getIssue(this._ctx(), id);
     if (!issue)
       throw new Error(`Issue ${id} not found.`);
@@ -5911,10 +6626,20 @@ class TrellisVcsEngine {
       throw new Error(`Issue ${id} has no tracked branch.`);
     const op = await resumeIssue(this._ctx(), id);
     this.switchBranch(issue.branchName);
+    if (opts?.lane !== false) {
+      const issueKey = id.startsWith("issue:") ? id : `issue:${id}`;
+      const lane = this.findLaneForIssue(issueKey);
+      if (lane) {
+        await this.enterLane(lane.id);
+      }
+    }
     await this.flushAutoCheckpoint();
     return op;
   }
   async closeIssue(id, opts) {
+    if (this.activeLaneId) {
+      await this.leaveLane();
+    }
     const result = await closeIssue(this._ctx(), id, opts);
     if (result.op) {
       await this.flushAutoCheckpoint();
@@ -5989,13 +6714,106 @@ class TrellisVcsEngine {
     return {
       store: this.store,
       agentId: this.agentId,
-      readAllOps: () => this.opLog.readAll(),
-      getLastOp: () => this.opLog.getLastOp(),
-      applyOp: (op) => this.applyOp(op)
+      readAllOps: () => this.getActiveJournal().readAll(),
+      getLastOp: () => this.getActiveJournal().getLastOp(),
+      applyOp: (op, opts) => this.applyOp(op, opts)
     };
   }
-  applyOp(op) {
-    const decomposed = decompose(op);
+  trellisDir() {
+    return join5(this.config.rootPath, ".trellis");
+  }
+  getActiveJournal() {
+    if (this.activeLaneId && this.activeLaneLog) {
+      return this.activeLaneLog;
+    }
+    return this.opLog;
+  }
+  invalidateIntegrationCache() {
+    this.integrationCache = null;
+  }
+  loadLaneJournalOps(laneId) {
+    const log = new LaneOpLog(laneDir(this.trellisDir(), laneId));
+    log.load();
+    return log.readAll();
+  }
+  refreshMaterializedStore(integrationOps, laneOps, meta) {
+    const laneMeta = meta ?? (this.activeLaneId ? this.getLaneMeta(this.activeLaneId) : undefined);
+    if (laneMeta?.forkKind === "child" && laneMeta.parentLaneId) {
+      const parentLaneOps = this.loadLaneJournalOps(laneMeta.parentLaneId);
+      const { store: store2, stats: stats2 } = materializeChildForkEntry(integrationOps, laneMeta.baseOpHash, parentLaneOps, laneOps ?? []);
+      this.store = store2;
+      this.materializationStats = stats2;
+      return;
+    }
+    const tailHash = integrationOps[integrationOps.length - 1]?.hash;
+    const { store, cache, stats } = materializeIntegrationOps(integrationOps, this.integrationCache, tailHash);
+    this.integrationCache = cache;
+    if (laneOps !== undefined) {
+      const overlay = overlayLaneOps(store, laneOps);
+      this.store = overlay.store;
+      this.materializationStats = {
+        ...stats,
+        laneOpsReplayed: overlay.laneOpsReplayed
+      };
+      return;
+    }
+    this.store = store;
+    this.materializationStats = stats;
+  }
+  restoreIntegrationOnlyStore() {
+    const integrationOps = this.opLog.readAll();
+    const tailHash = integrationOps[integrationOps.length - 1]?.hash;
+    const { store, cache, stats } = materializeIntegrationOps(integrationOps, this.integrationCache, tailHash);
+    this.integrationCache = cache;
+    this.store = store;
+    this.materializationStats = {
+      ...stats,
+      laneOpsReplayed: 0
+    };
+  }
+  rebuildStore(ops) {
+    this.store = new EAVStore;
+    for (const op of ops) {
+      this.replayOp(op);
+    }
+  }
+  syncIngestionLastOpHash() {
+    if (this.ingestion) {
+      this.ingestion.setLastOpHash(this.getActiveJournal().getLastOp()?.hash);
+    }
+  }
+  stampLaneId(op) {
+    if (!this.activeLaneId)
+      return;
+    op.vcs = { ...op.vcs, laneId: this.activeLaneId };
+  }
+  requireActiveLaneLog() {
+    if (!this.activeLaneId || !this.activeLaneLog) {
+      throw new Error("No active lane journal");
+    }
+    return this.activeLaneLog;
+  }
+  isIssueIntegrationOp(kind) {
+    return ISSUE_INTEGRATION_KINDS.has(kind);
+  }
+  async applyOp(op, opts) {
+    const inLane = Boolean(this.activeLaneId);
+    const forceIntegration = Boolean(opts?.allowIntegrationWrite) || inLane && this.isIssueIntegrationOp(op.kind);
+    let opToApply = op;
+    if (inLane && forceIntegration) {
+      const intLast = this.opLog.getLastOp();
+      if (intLast?.hash !== op.previousHash && isVcsOpKind(op.kind)) {
+        opToApply = await createVcsOp(op.kind, {
+          agentId: op.agentId,
+          previousHash: intLast?.hash,
+          vcs: op.vcs ?? {}
+        });
+      }
+    }
+    if (inLane && !forceIntegration) {
+      this.stampLaneId(opToApply);
+    }
+    const decomposed = decompose(opToApply);
     if (decomposed.deleteFacts.length > 0) {
       this.store.deleteFacts(decomposed.deleteFacts);
     }
@@ -6008,13 +6826,55 @@ class TrellisVcsEngine {
     if (decomposed.addLinks.length > 0) {
       this.store.addLinks(decomposed.addLinks);
     }
-    this.opLog.append(op);
-    if (op.kind !== "vcs:checkpointCreate" && this.checkpointThreshold > 0) {
+    if (inLane && !forceIntegration) {
+      const laneLog = this.requireActiveLaneLog();
+      laneLog.append(opToApply);
+      updateLaneHead(this.trellisDir(), this.activeLaneId, opToApply.hash);
+      if (opToApply.kind !== "vcs:checkpointCreate" && this.checkpointThreshold > 0) {
+        this.checkpointOpCount++;
+        if (this.checkpointOpCount >= this.checkpointThreshold) {
+          this._pendingAutoCheckpoint = true;
+        }
+      }
+      return;
+    }
+    this.opLog.append(opToApply);
+    if (inLane && forceIntegration) {
+      const meta = this.getLaneMeta(this.activeLaneId);
+      this.refreshMaterializedStore(this.opLog.readAll(), this.activeLaneLog.readAll(), meta);
+    } else if (!inLane) {
+      if (!this.integrationCache) {
+        this.integrationCache = {
+          tailHash: opToApply.hash,
+          store: this.store
+        };
+      } else {
+        this.integrationCache.tailHash = opToApply.hash;
+      }
+    }
+    if (opToApply.kind !== "vcs:checkpointCreate" && this.checkpointThreshold > 0) {
       this.checkpointOpCount++;
       if (this.checkpointOpCount >= this.checkpointThreshold) {
         this._pendingAutoCheckpoint = true;
       }
     }
+    if (!opts?.skipBranchAdvance && shouldAdvanceBranchHead(opToApply.kind)) {
+      await this.appendBranchAdvance(opToApply.hash);
+    }
+  }
+  async appendBranchAdvance(targetOpHash) {
+    const advanceOp = await createVcsOp("vcs:branchAdvance", {
+      agentId: this.agentId,
+      previousHash: this.opLog.getLastOp()?.hash,
+      vcs: {
+        branchName: this.currentBranch,
+        targetOpHash
+      }
+    });
+    await this.applyOp(advanceOp, {
+      skipBranchAdvance: true,
+      allowIntegrationWrite: true
+    });
   }
   async flushAutoCheckpoint() {
     if (this._pendingAutoCheckpoint) {
@@ -6025,6 +6885,17 @@ class TrellisVcsEngine {
   loadCurrentBranch() {
     const state = loadBranchState(this.config.rootPath);
     this.currentBranch = state.currentBranch;
+    this.activeLaneId = state.activeLaneId;
+    this.activeLaneLog = null;
+    if (this.activeLaneId) {
+      const meta = loadLaneMeta(this.trellisDir(), this.activeLaneId);
+      if (meta && meta.status === "active") {
+        this.activeLaneLog = new LaneOpLog(laneDir(this.trellisDir(), this.activeLaneId));
+        this.activeLaneLog.load();
+      } else {
+        this.activeLaneId = undefined;
+      }
+    }
   }
   replayOp(op) {
     const decomposed = decompose(op);
@@ -6042,7 +6913,7 @@ class TrellisVcsEngine {
     }
   }
 }
-var TRELLIS_GITIGNORE_ENTRY = ".trellis/";
+var TRELLIS_GITIGNORE_ENTRY = ".trellis/", ISSUE_INTEGRATION_KINDS;
 var init_engine = __esm(() => {
   init_eav_store();
   init_fs_watcher();
@@ -6063,6 +6934,21 @@ var init_engine = __esm(() => {
   init_infer();
   init_profile();
   init_write();
+  init_op_log();
+  init_lane();
+  init_lane_promote();
+  init_lane_materialize();
+  ISSUE_INTEGRATION_KINDS = new Set([
+    "vcs:issueCreate",
+    "vcs:issueStart",
+    "vcs:issuePause",
+    "vcs:issueResume",
+    "vcs:issueClose",
+    "vcs:issueReopen",
+    "vcs:criterionUpdate",
+    "vcs:issueBlock",
+    "vcs:issueUnblock"
+  ]);
 });
 
-export { FileWatcher, init_fs_watcher, Ingestion, init_ingestion, inferProjectContext, init_infer, loadProfile, saveProfile, hasProfile, promptForProfile, updateProfile, init_profile, writeAgentScaffold, writeIdeScaffold, init_write, TrellisVcsEngine, init_engine };
+export { FileWatcher, init_fs_watcher, Ingestion, init_ingestion, inferProjectContext, init_infer, loadProfile, saveProfile, hasProfile, promptForProfile, updateProfile, init_profile, writeAgentScaffold, writeIdeScaffold, init_write, formatPromoteExplain, init_lane_promote, TrellisVcsEngine, init_engine };