driftseal 1.1.5 → 1.1.6

package/README.md

@@ -317,6 +317,20 @@ ambiguous decision catalog. Run `driftseal absorb`, stage the repaired intent
 and decision logs, then continue the merge. Clones need `init` again because
 the driver lives in local git config.
 
+In a Git worktree, `begin` parks the open intent in Git metadata instead of
+appending to the tracked `events.jsonl`. Git can merge while that intent is
+still in progress, so you do not need a log-only commit just to get a clean
+tree. `end` moves the parked records into the tracked log and writes the closing
+record there — never into Git metadata — so an interrupted `end` leaves the
+intent open in the log and can simply be run again. If the parked intent's id
+collides with incoming merged events, DriftSeal remaps it the same way `absorb`
+remaps colliding worktree ids.
+
+When a merge brings in a second open intent, `absorb --abandon-ours` closes the
+parked one into the tracked log and `absorb --abandon-theirs` closes the
+incoming one and leaves yours parked. `end <id>` also works on the incoming
+intent directly, and `begin --force` abandons every open intent at once.
+
 ## Storage
 
 - `.intent-log/events.jsonl` is the append-only intent log. All access goes through `driftseal` (CLI or MCP) — never read, edit, move, or delete it directly; use `driftseal reclaim` to retire meaningless records instead of deleting log lines. After a merge collision, use `driftseal absorb` instead of editing the file.

package/README.zh-CN.md

@@ -288,6 +288,18 @@ driftseal absorb ../other-worktree/.intent-log/events.jsonl \
 `driftseal absorb`、stage 修复后的 intent / decision logs，再继续 merge。clone
 之后需要再跑一次 `init`，因为 driver 只存在于 local git config。
 
+在 Git worktree 里，`begin` 会把未关闭的 intent 停在 Git 元数据中，而不是追加到
+已跟踪的 `events.jsonl`。因此工作树保持干净，`git merge` 可以在 intent 仍进行中
+时执行，不必为了清工作树而多做一个只含日志的提交。`end` 会先把停放的记录移入跟踪
+日志，再把关闭记录写在那里，而不会写进 Git 元数据；因此 `end` 中途失败时，intent
+只是以未关闭状态留在日志里，重跑一次即可。如果停放中的 intent id 与合并进来的事件
+撞号，DriftSeal 会按 `absorb` 同样的规则重编号。
+
+合并带进来第二个未关闭的 intent 时，`absorb --abandon-ours` 会关闭停放的那一个并
+写入跟踪日志，`absorb --abandon-theirs` 则关闭合并进来的那一个、保留自己的停放
+状态。也可以用 `end <id>` 直接关闭合并进来的 intent，或用 `begin --force` 一次性
+放弃所有未关闭的 intent。
+
 ## 数据保存在哪里
 
 - `.intent-log/events.jsonl`：append-only intent log。所有读写都必须经过 `driftseal`（CLI 或 MCP）——不要直接读取、修改、移动或删除该文件；需要让无意义的记录退场时使用 `driftseal reclaim`，而不是删除日志行。合并撞号时用 `driftseal absorb`，不要手改这个文件。

package/bin/driftseal.js

@@ -16,6 +16,7 @@
  *   { "type": "end",   "id", "ts", "status", "note", "verifyResult" }
  *
  * Intent log: $DRIFTSEAL_HOME/events.jsonl, or .intent-log/events.jsonl in cwd.
+ * In a Git worktree, an open intent is parked in Git metadata until end.
  * Decision log: $DRIFTSEAL_DECISION_HOME, or .decision-log/ in cwd.
  */
 
@@ -23,6 +24,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const os = require('os');
+const { isDeepStrictEqual } = require('util');
 const { execFileSync } = require('child_process');
 const { version: PACKAGE_VERSION } = require('../package.json');
 
@@ -38,6 +40,7 @@ const DECISION_STATUSES = [
 const EVENT_SCHEMA_VERSION = 3;
 const PROTOCOL_VERSION = 11;
 const DEFAULT_LOG_LANGUAGE = 'en';
+const IN_PROGRESS_GIT_PATH = 'driftseal-in-progress.jsonl';
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const LOCK_INIT_STALE_MS = 5 * 1000;
 const MAX_DECISION_SLUG_LENGTH = 180;
@@ -193,7 +196,47 @@ function normalizeEvent(event, line) {
   fail(`unknown event type "${event.type}" on log line ${line}`);
 }
 
-function readEvents({ repairTail = false, file = logFile() } = {}) {
+function gitWorktreeRoot(cwd = process.cwd()) {
+  if (!isGitWorkTree(cwd)) return null;
+  return gitCapture(['rev-parse', '--show-toplevel'], cwd);
+}
+
+function worktreeInProgressFile(cwd = process.cwd()) {
+  if (!isGitWorkTree(cwd)) return null;
+  const gitPath = gitCapture(['rev-parse', '--git-path', IN_PROGRESS_GIT_PATH], cwd);
+  if (!gitPath) return null;
+  return path.resolve(cwd, gitPath);
+}
+
+function isParkableIntentLog() {
+  if (process.env.DRIFTSEAL_HOME) return false;
+  const root = gitWorktreeRoot();
+  if (!root) return false;
+  return path.resolve(logFile()) === path.resolve(root, '.intent-log', 'events.jsonl');
+}
+
+function inProgressFile() {
+  if (!isParkableIntentLog()) return null;
+  return worktreeInProgressFile();
+}
+
+function liveWorktreeIntentLog() {
+  const root = gitWorktreeRoot();
+  if (!root) return null;
+  return path.resolve(root, '.intent-log', 'events.jsonl');
+}
+
+function sameResolvedPath(left, right) {
+  return path.resolve(left) === path.resolve(right);
+}
+
+function shouldAttachInProgress(file) {
+  if (process.env.DRIFTSEAL_HOME) return false;
+  const live = liveWorktreeIntentLog();
+  return live !== null && sameResolvedPath(file, live);
+}
+
+function readJsonlRecordsFromFile(file, { repairTail = false } = {}) {
   if (!fs.existsSync(file)) return [];
   let content = fs.readFileSync(file, 'utf8');
   const rawLines = content.split('\n');
@@ -214,7 +257,65 @@ function readEvents({ repairTail = false, file = logFile() } = {}) {
       content = content.slice(0, validLength);
     }
   }
-  return parseJsonlRecords(content, file).map((record) => record.event);
+  return parseJsonlRecords(content, file);
+}
+
+/**
+ * True when the parked records already sit in the committed log. A flush appends them, so
+ * they land as a suffix; a merge that appends afterwards leaves them as an interior run.
+ */
+function overlayIsCommitted(committedEvents, overlayEvents) {
+  if (overlayEvents.length === 0 || committedEvents.length < overlayEvents.length) return false;
+  const head = overlayEvents[0];
+  for (let start = committedEvents.length - overlayEvents.length; start >= 0; start--) {
+    const candidate = committedEvents[start];
+    if (candidate.type !== head.type || candidate.id !== head.id || candidate.ts !== head.ts) continue;
+    const matches = overlayEvents.every((event, index) =>
+      isDeepStrictEqual(committedEvents[start + index], event)
+    );
+    if (matches) return true;
+  }
+  return false;
+}
+
+/** How a parked overlay lines up with the committed log; touches neither file. */
+function planInProgressOverlay(committedEvents, park, { repairTail = false } = {}) {
+  if (!park || !fs.existsSync(park)) return null;
+  const overlayRecords = readJsonlRecordsFromFile(park, { repairTail });
+  const overlayEvents = overlayRecords.map((record) => record.event);
+  if (overlayEvents.length === 0 || overlayIsCommitted(committedEvents, overlayEvents)) {
+    return { park, records: [], mappings: [], alreadyCommitted: true };
+  }
+  const remapped = remapTheirsRecords(overlayRecords, committedEvents, new Map(), new Map());
+  return { park, records: remapped.records, mappings: remapped.mappings, alreadyCommitted: false };
+}
+
+function discardInProgressLog(park) {
+  fs.unlinkSync(park);
+  fsyncDirectory(path.dirname(park));
+}
+
+function reconcileInProgressRecords(committedEvents, { repairTail = false, park = inProgressFile() } = {}) {
+  const plan = planInProgressOverlay(committedEvents, park, { repairTail });
+  if (!plan) return [];
+  if (plan.alreadyCommitted) {
+    discardInProgressLog(park);
+    return [];
+  }
+  if (plan.mappings.length > 0) writeJsonl(park, plan.records);
+  return plan.records;
+}
+
+function readEvents({ repairTail = false, file = logFile() } = {}) {
+  const records = readJsonlRecordsFromFile(file, { repairTail });
+  const events = records.map((record) => record.event);
+  if (!shouldAttachInProgress(file)) return events;
+  return events.concat(
+    reconcileInProgressRecords(events, {
+      repairTail,
+      park: worktreeInProgressFile(),
+    }).map((record) => record.event)
+  );
 }
 
 function parseJsonlRecords(content, source = 'log') {
@@ -257,15 +358,11 @@ function ensureDirectoryDurable(directory) {
   for (const created of missing.reverse()) fsyncDirectory(path.dirname(created));
 }
 
-function appendEvent(event) {
-  ensureDirectoryDurable(logDir());
-  const file = logFile();
+function appendEventTo(file, event) {
+  ensureDirectoryDurable(path.dirname(file));
   const existed = fs.existsSync(file);
   const storedEvent = { schemaVersion: EVENT_SCHEMA_VERSION, ...event };
-  const line = Buffer.from(
-    JSON.stringify(storedEvent) + '\n',
-    'utf8'
-  );
+  const line = Buffer.from(`${JSON.stringify(storedEvent)}\n`, 'utf8');
   const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND, 0o600);
   try {
     const stat = fs.fstatSync(fd);
@@ -285,10 +382,66 @@ function appendEvent(event) {
   } finally {
     fs.closeSync(fd);
   }
-  if (!existed) fsyncDirectory(logDir());
+  if (!existed) fsyncDirectory(path.dirname(file));
   return storedEvent;
 }
 
+/**
+ * Move the parked records into the tracked log. Safe to retry: a remap is persisted to the
+ * park first, the log is written before the park file is dropped, so an interruption either
+ * leaves nothing committed or leaves the overlay recognizable as already committed.
+ * Returns the intent ids it had to remap.
+ */
+function flushInProgressLog() {
+  const park = inProgressFile();
+  if (!park || !fs.existsSync(park)) return new Map();
+  const committedRecords = readJsonlRecordsFromFile(logFile());
+  const plan = planInProgressOverlay(
+    committedRecords.map((record) => record.event),
+    park,
+    { repairTail: true }
+  );
+  if (!plan) return new Map();
+  if (plan.alreadyCommitted) {
+    discardInProgressLog(park);
+    return new Map();
+  }
+  // Persist a remap before touching the log: after any crash the park then matches what the
+  // log received (or will receive), so recovery never re-remaps it into a duplicate.
+  if (plan.mappings.length > 0) writeJsonl(park, plan.records);
+  writeJsonl(logFile(), [...committedRecords, ...plan.records]);
+  discardInProgressLog(park);
+  return new Map(
+    plan.mappings.filter((mapping) => mapping.kind === 'intent').map((mapping) => [mapping.from, mapping.to])
+  );
+}
+
+function parkedOpenIntent(park) {
+  if (!fs.existsSync(park)) return null;
+  const records = readJsonlRecordsFromFile(park, { repairTail: true });
+  return openIntent(fold(records.map((record) => record.event)));
+}
+
+function appendEvent(event) {
+  const park = inProgressFile();
+  if (!park) return appendEventTo(logFile(), event);
+
+  const open = parkedOpenIntent(park);
+  // A park with nothing open left in it belongs in the log; an interrupted end retries here.
+  if (!open) flushInProgressLog();
+
+  if (event.type === 'begin') return appendEventTo(park, event);
+  if (!open || open.id !== event.id) return appendEventTo(logFile(), event);
+  if (event.type !== 'end') return appendEventTo(park, event);
+  // Close in the tracked log, never in Git metadata: the parked records move first, so the
+  // closing record cannot end up somewhere a clone or a removed worktree would drop it.
+  const remapped = flushInProgressLog();
+  if (process.env._DRIFTSEAL_TEST_CRASH_AFTER_IN_PROGRESS_FLUSH === '1') {
+    fail('simulated interruption after the in-progress flush');
+  }
+  return appendEventTo(logFile(), remapEvent(event, remapped, new Map()));
+}
+
 function contentHash(content) {
   return crypto.createHash('sha256').update(content, 'utf8').digest('hex');
 }
@@ -2234,9 +2387,14 @@ function hookLogFile() {
     return fs.existsSync(configured) ? configured : null;
   }
   let current = path.resolve(process.cwd());
+  const root = gitWorktreeRoot(current);
   while (true) {
     const candidate = path.join(current, '.intent-log', 'events.jsonl');
     if (fs.existsSync(candidate)) return candidate;
+    if (root && path.resolve(root) === current) {
+      const park = worktreeInProgressFile(current);
+      if (park && fs.existsSync(park)) return candidate;
+    }
     const parent = path.dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -2727,8 +2885,9 @@ function printAbsorbReport({ mappings, abandoned, intentCount }) {
     `absorbed ${intentCount} intent(s), remapped ${remappedIntents} intent id(s), ${remappedDecisions} decision id(s)`
   );
   for (const mapping of mappings) {
-    if (mapping.kind === 'intent') printLine(`${mapping.from} (theirs) -> ${mapping.to}`);
-    else printLine(`decision ${mapping.from} (theirs) -> ${mapping.to}`);
+    const side = mapping.side || 'theirs';
+    if (mapping.kind === 'intent') printLine(`${mapping.from} (${side}) -> ${mapping.to}`);
+    else printLine(`decision ${mapping.from} (${side}) -> ${mapping.to}`);
   }
   if (abandoned) printLine(`abandoned ${abandoned} during absorb`);
 }
@@ -2748,23 +2907,45 @@ function abandonOpenIntent(records, targetId, side) {
   return targetId;
 }
 
-function resolveOpenIntents(result, oursRecords, theirsRecords, abandon, { allowConflict = false } = {}) {
+function resolveOpenIntents(
+  result,
+  oursRecords,
+  theirsRecords,
+  abandon,
+  { allowConflict = false, overlay = [], parkedOpen = null } = {}
+) {
   const oursOpen = openIntent(fold(oursRecords.map((record) => record.event)));
   const theirsOpen = openIntent(fold(theirsRecords.map((record) => record.event)));
   try {
-    openIntent(fold(result.map((record) => record.event)));
-    return { abandoned: null, conflict: false };
+    openIntent(fold([...result, ...overlay].map((record) => record.event)));
+    return { abandoned: null, conflict: false, parkedClosed: false };
   } catch (err) {
     if (!(err instanceof DriftSealError) || !/multiple intents in progress/.test(err.message)) {
       throw err;
     }
     if (abandon === 'theirs' && theirsOpen) {
-      return { abandoned: abandonOpenIntent(result, theirsOpen.id, 'theirs'), conflict: false };
+      return {
+        abandoned: abandonOpenIntent(result, theirsOpen.id, 'theirs'),
+        conflict: false,
+        parkedClosed: false,
+      };
+    }
+    // A parked intent is local by construction, so --abandon-ours targets it before the log.
+    if (abandon === 'ours' && parkedOpen) {
+      return {
+        abandoned: abandonOpenIntent(overlay, parkedOpen.id, 'ours'),
+        conflict: false,
+        parkedClosed: true,
+      };
     }
     if (abandon === 'ours' && oursOpen) {
-      return { abandoned: abandonOpenIntent(result, oursOpen.id, 'ours'), conflict: false };
+      return {
+        abandoned: abandonOpenIntent(result, oursOpen.id, 'ours'),
+        conflict: false,
+        parkedClosed: false,
+      };
     }
-    if (allowConflict) return { abandoned: null, conflict: true };
+    if (allowConflict) return { abandoned: null, conflict: true, parkedClosed: false };
     fail(`${err.message}; re-run with --abandon-theirs or --abandon-ours`);
   }
 }
@@ -2859,20 +3040,51 @@ function finishAbsorb({
   allowConflict = false,
   followupMessage = null,
 }) {
-  const { abandoned, conflict } = resolveOpenIntents(result, oursRecords, theirsRecords, abandon, {
-    allowConflict,
+  // An intent parked in Git metadata is part of our side even though the log never saw it.
+  const park = shouldAttachInProgress(outputFile) ? inProgressFile() : null;
+  const plan = planInProgressOverlay(result.map((record) => record.event), park, {
+    repairTail: true,
   });
-  fold(result.map((record) => record.event));
-  if (!conflict) openIntent(fold(result.map((record) => record.event)));
+  const overlay = plan && !plan.alreadyCommitted ? plan.records : [];
+  const parkedOpen =
+    overlay.length > 0 ? openIntent(fold(overlay.map((record) => record.event))) : null;
+  const parkMappings = plan
+    ? plan.mappings.map((mapping) => ({ ...mapping, side: 'parked' }))
+    : [];
+  const allMappings = [...mappings, ...parkMappings];
+  const { abandoned, conflict, parkedClosed } = resolveOpenIntents(
+    result,
+    oursRecords,
+    theirsRecords,
+    abandon,
+    { allowConflict, overlay, parkedOpen }
+  );
+  // A parked overlay with nothing left open in it belongs in the tracked log, whether the
+  // abandon flag just closed it or an interrupted end left it closed.
+  const flushOverlay = parkedClosed || (overlay.length > 0 && !parkedOpen);
+  const merged = flushOverlay ? [...result, ...overlay] : result;
+  const effective = [...result, ...overlay].map((record) => record.event);
+  fold(effective);
+  if (!conflict) openIntent(fold(effective));
   if (!dryRun) {
-    writeJsonl(outputFile, result);
+    writeJsonl(outputFile, merged);
     applyDecisionCopies(copies, dryRun);
+    if (plan) {
+      if (plan.alreadyCommitted || flushOverlay) discardInProgressLog(park);
+      else if (plan.mappings.length > 0) writeJsonl(park, overlay);
+    }
   }
-  if (intentCount === 0 && mappings.length === 0 && copies.length === 0 && !abandoned) {
+  if (
+    intentCount === 0 &&
+    allMappings.length === 0 &&
+    copies.length === 0 &&
+    !abandoned &&
+    !flushOverlay
+  ) {
     printLine('nothing to absorb');
   } else {
     printAbsorbReport({
-      mappings,
+      mappings: allMappings,
       abandoned,
       intentCount,
     });
@@ -2882,7 +3094,7 @@ function finishAbsorb({
   }
   if (followupMessage) printLine(followupMessage);
   return {
-    mappings,
+    mappings: allMappings,
     abandoned,
     copies: copies.map((item) => item.toFile),
     outputFile,
@@ -3111,22 +3323,30 @@ const commands = {
 
     const events = readEvents({ repairTail: true });
     const records = fold(events);
-    const open = openIntent(records);
-    if (open) {
-      if (!flags.force) {
-        fail(
-          `intent ${open.id} is still in_progress: "${open.intent}"\n` +
-            `end it first (driftseal end) or re-run with --force to abandon it`
-        );
-      }
+    // A parked intent and a merged-in one can both be open; --force clears every one of them.
+    const open = records.filter((record) => record.status === 'in_progress');
+    if (open.length > 1 && !flags.force) {
+      fail(
+        `multiple intents in progress: ${open.map((record) => record.id).join(', ')}\n` +
+          'resolve them with driftseal absorb --abandon-ours or --abandon-theirs, ' +
+          'or re-run with --force to abandon all of them'
+      );
+    }
+    if (open.length === 1 && !flags.force) {
+      fail(
+        `intent ${open[0].id} is still in_progress: "${open[0].intent}"\n` +
+          `end it first (driftseal end) or re-run with --force to abandon it`
+      );
+    }
+    for (const record of open) {
       const status = closeIntentAsEscape(
         events,
-        open,
+        record,
         'abandoned',
         'superseded by --force',
         null
       );
-      printError(`driftseal: ${status} ${open.id}`);
+      printError(`driftseal: ${status} ${record.id}`);
     }
 
     const id = nextId(events);
@@ -3674,7 +3894,8 @@ decision add options:
   --consequence "..."           repeat for each consequence
 
 intent log: $DRIFTSEAL_HOME/events.jsonl, or .intent-log/events.jsonl
-decision log: $DRIFTSEAL_DECISION_HOME, or .decision-log/ in the current directory`);
+decision log: $DRIFTSEAL_DECISION_HOME, or .decision-log/ in the current directory
+In a Git worktree, begin parks an open intent in Git metadata until end, so merge does not need a log-only commit.`);
     return null;
   },
 
@@ -3723,7 +3944,8 @@ function dispatch(argv) {
     ['begin', 'end', 'init', 'skill', 'mcp', 'reclaim', 'unreclaim', 'absorb'].includes(cmd) ||
     (cmd === 'hook' && rest[0] === 'install') ||
     (cmd === 'decision' && ['add', 'update'].includes(rest[0]));
-  const readsIntentLog = ['status', 'log'].includes(cmd);
+  const readsIntentLog =
+    ['status', 'log'].includes(cmd) || (cmd === 'hook' && ['prompt', 'stop'].includes(rest[0]));
   if (mutates || readsIntentLog) {
     const resources = readsIntentLog ? [logDir()] : mutationResources(cmd, rest);
     const data = withMutationLocks(resources, () => fn(rest));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Seal intent, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",

package/skills/use-driftseal/SKILL.md

@@ -39,11 +39,17 @@ driftseal help
 
 ## After a merge
 
-If `status` or `log` fails with a duplicate id, or the intent log has conflict
-markers, run `driftseal absorb` instead of editing `.intent-log/events.jsonl`.
-When both sides still have an open intent, add `--abandon-theirs` or
-`--abandon-ours`. `driftseal init` also configures the local git merge driver;
-clones need `init` again for that driver.
+If `status` or `log` fails with a duplicate id or with `multiple intents in
+progress`, or the intent log has conflict markers, run `driftseal absorb`
+instead of editing `.intent-log/events.jsonl`. When both sides still have an
+open intent, add `--abandon-theirs` or `--abandon-ours`; this works whether your
+open intent sits in the log or is parked in Git metadata. `driftseal init` also
+configures the local git merge driver; clones need `init` again for that driver.
+
+In a Git worktree, `begin` does not dirty the tracked intent log, so `git merge`
+can run with an intent still in progress. `end` writes the closed record to
+`.intent-log/events.jsonl`; if it is interrupted, the intent stays open there
+and `end` can be run again.
 
 Do not treat this skill, MCP descriptions, or lifecycle-hook reminders as
 additional policy. If they conflict with `AGENTS.md`, follow `AGENTS.md`.