driftseal 3.0.0 → 3.1.0

package/README.md

@@ -66,8 +66,9 @@ fresh clone because Git config is local to each clone.
 
 Use `driftseal init --lang <BCP-47-tag>` to choose the prose language stored in
 outcome and MADR records. Use `--local-log` only when `.seal/` should remain
-untracked; DriftSeal reports tracked state but does not edit `.gitignore` or the
-Git index.
+untracked; DriftSeal reports tracked state but does not edit the repository-root
+`.gitignore` or the Git index. When the seal sits inside a Git worktree, `init`
+may still write `.seal/outcomes/.gitignore` so derived sidecars stay untracked.
 
 ## Core workflow
 
@@ -156,13 +157,13 @@ has, `status`, `log`, and `lane` fall back to `main` with a warning; `begin`
 still refuses until you `lane switch main` or add the lane. `log --last N` can
 return more than N records when an open outcome sits on another lane.
 
-A derived SQLite outcome index stores folded records in Git metadata (or beside
-a custom seal). It is a disposable read model; `events.jsonl` remains the only
-canonical history. Incremental sync follows `indexedThrough` and
-`indexedLines`. File identity makes unchanged hot reads constant-time, while a
-full checksum of the previously indexed WAL prefix validates every incremental
-catch-up. A source rewrite, incompatible schema, malformed indexed row, or
-SQLite read error triggers a full rebuild.
+A derived SQLite outcome index stores folded records beside the WAL
+(`outcomes/.outcome-index.sqlite`). It is a disposable read model;
+`events.jsonl` remains the only canonical history. Incremental sync follows
+`indexedThrough` and `indexedLines`. File identity makes unchanged hot reads
+constant-time, while a full checksum of the previously indexed WAL prefix
+validates every incremental catch-up. A source rewrite, incompatible schema,
+malformed indexed row, or SQLite read error triggers a full rebuild.
 
 `log --last N` uses a `(lane, reclaimed, ordinal)` SQLite index and reads only
 the selected outcome rows plus open outcomes from other lanes. Parked events
@@ -171,9 +172,10 @@ identities, so an open outcome does not force a committed-WAL scan. When a
 lock-free read sees a missing or stale database, DriftSeal folds the canonical
 WAL in memory instead of serving stale index data. Stored WAL byte ranges remain
 available for future projections but are not required for recent-log lookup.
-The database is reconstructable and is not committed with the log. Custom-home
-sidecars sit next to `events.jsonl`; when that directory is inside a Git
-worktree, they are listed in its `.gitignore`.
+The database is reconstructable and is not committed with the log. Sidecars sit
+next to `events.jsonl`; when that directory is inside a Git worktree, they are
+listed in its `.gitignore`. Keeping the file in the workspace avoids agent
+sandboxes that deny writes under `.git/`.
 
 ## Decisions and MADR
 
@@ -292,9 +294,11 @@ migrated state.
 
 ## Git and merge behavior
 
-In a Git worktree, `begin` parks the open outcome in Git metadata so it does not
-dirty the tracked log. `end` flushes the lineage to
-`.seal/outcomes/events.jsonl`. The event log is append-only during normal work.
+In a default Git-repository seal, `begin` parks the open outcome beside the WAL
+(`.seal/outcomes/.in-progress.jsonl`, gitignored) so it does not dirty the
+tracked log. Custom `$DRIFTSEAL_HOME` seals write that open outcome directly to
+`events.jsonl`. `end` flushes a parked lineage to `.seal/outcomes/events.jsonl`.
+The event log is append-only during normal work.
 
 After a merge collision, run:
 
@@ -341,11 +345,19 @@ MADR tools, and the three migration tools. Resources are:
   DriftSeal; use `reclaim`, `unreclaim`, `lane`, and `absorb` instead of manual edits.
 - `.seal/madr/` stores numbered MADR documents.
 - `$DRIFTSEAL_HOME` replaces the `.seal` root.
-- The current lane and derived SQLite outcome index live in Git metadata for a default
-  repository seal, or beside a custom seal (`outcomes/.current-lane` and
-  `outcomes/.outcome-index.sqlite`). When the custom seal sits inside a Git
-  worktree, those sidecars are gitignored. They are reconstructable and are not
-  part of the committed WAL.
+- The derived SQLite outcome index and the current-lane pointer sit next to the
+  WAL (`outcomes/.outcome-index.sqlite`, `outcomes/.current-lane`). The index is
+  reconstructable from `events.jsonl`; a missing or stale current-lane pointer
+  falls back to `main`. A default repository seal also parks the open outcome and
+  local verification provenance beside the WAL
+  (`outcomes/.in-progress.jsonl`, `outcomes/.driftseal-local-outcome.json`). Those
+  two files are not reconstructable: deleting the park discards the still-open
+  outcome, and deleting provenance changes verifier trust. Custom
+  `$DRIFTSEAL_HOME` seals write open outcomes directly to the WAL and still keep
+  provenance beside that log. When the outcomes directory is inside a Git
+  worktree, the sidecars are gitignored. A default repository seal keeps one
+  ignored copy per worktree; a shared `$DRIFTSEAL_HOME` shares the files that
+  exist there.
 - Advisory hooks remind agents about lifecycle state but never broaden the
   repository's `AGENTS.md` policy.
 

package/README.zh-CN.md

@@ -60,7 +60,8 @@ attribute，并配置本地 Git merge driver。Git config 不会随 clone 传播
 
 `driftseal init --lang <BCP-47-tag>` 用来指定 outcome 与 MADR 正文的语言。
 `--local-log` 会让 `.seal/` 保持本地、不被跟踪；DriftSeal 只报告当前 tracked 状态，
-不会替你修改 `.gitignore` 或 Git index。
+不会替你修改仓库根目录的 `.gitignore` 或 Git index。seal 在 Git worktree 内时，
+`init` 仍可能写入 `.seal/outcomes/.gitignore`，用来忽略派生 sidecar。
 
 ## 基本工作流
 
@@ -141,19 +142,21 @@ lane 不能改名或删除。`lane add` 打错的名字会一直出现在 `drift
 直到 `lane switch main` 或把该 lane 加回来。`log --last N` 在 open outcome 属于
 别的 lane 时，返回条数可以多于 N。
 
-派生的 SQLite outcome index 放在 Git metadata（或自定义 seal 旁边）。它只是可以
-随时删除重建的 read model；`events.jsonl` 仍是唯一 canonical history。增量同步跟随
-`indexedThrough` 和 `indexedLines`。未变化的 hot read 用 file identity 做常量时间
-校验；增量追赶前会校验此前全部 WAL prefix 的 checksum。source 被改写、schema
-不兼容、indexed row 损坏或 SQLite read 失败时，DriftSeal 会全量重建。
+派生的 SQLite outcome index 放在 WAL 旁边（`outcomes/.outcome-index.sqlite`）。
+它只是可以随时删除重建的 read model；`events.jsonl` 仍是唯一 canonical history。
+增量同步跟随 `indexedThrough` 和 `indexedLines`。未变化的 hot read 用 file
+identity 做常量时间校验；增量追赶前会校验此前全部 WAL prefix 的 checksum。
+source 被改写、schema 不兼容、indexed row 损坏或 SQLite read 失败时，DriftSeal
+会全量重建。
 
 `log --last N` 使用 `(lane, reclaimed, ordinal)` SQLite index，只读取命中的 outcome
 row，并补上其他 lane 的 open outcome。parked event 会依据 index 中保存的 committed
 event identity 做定向 overlay，不再因此重扫 committed WAL。无锁读取遇到缺失或 stale
 database 时，会在内存中 fold canonical WAL，绝不会返回 stale index。保存的 WAL byte
 range 留给后续 projection 使用，但 recent-log lookup 不依赖它。database 可以重建，
-不会随 log 一起提交。自定义 home 下的 sidecar 放在 `events.jsonl` 旁边；该目录在 Git
-worktree 内时，由目录里的 `.gitignore` 忽略。
+不会随 log 一起提交。sidecar 放在 `events.jsonl` 旁边；该目录在 Git worktree
+内时，由目录里的 `.gitignore` 忽略。文件留在工作树里，避免被默认禁止写入
+`.git/` 的 agent sandbox 拦住。
 
 ## Decision 与 MADR
 
@@ -262,9 +265,11 @@ tools 可以立刻看到 migration 后的状态。
 
 ## Git 与 merge
 
-在 Git worktree 中，`begin` 会把 open outcome park 到 Git metadata，避免弄脏 tracked
-log；`end` 再把完整 lineage 写入 `.seal/outcomes/events.jsonl`。正常工作期间 event log
-保持 append-only。
+在默认 Git-repository seal 中，`begin` 会把 open outcome park 到 WAL 旁边
+（`.seal/outcomes/.in-progress.jsonl`，已被 gitignore），避免弄脏 tracked log。
+自定义 `$DRIFTSEAL_HOME` 会把该 open outcome 直接写入 `events.jsonl`。`end`
+再把 parked lineage flush 到 `.seal/outcomes/events.jsonl`。正常工作期间 event
+log 保持 append-only。
 
 发生 merge collision 后执行：
 
@@ -310,10 +315,16 @@ resources 为：
   `absorb`，不要手改。
 - `.seal/madr/` 保存编号化 MADR。
 - `$DRIFTSEAL_HOME` 替换整个 `.seal` root。
-- 当前 lane 与派生 SQLite outcome index 对默认 repo seal 存在 Git metadata 里，对自定义 seal
-  则放在旁边（`outcomes/.current-lane` 与 `outcomes/.outcome-index.sqlite`）。自定义
-  seal 在 Git worktree 内时，这些 sidecar 会被 gitignore。它们可以重建，不是
-  committed WAL 的一部分。
+- 派生 SQLite outcome index 和当前 lane 指针放在 WAL 旁边
+  （`outcomes/.outcome-index.sqlite`、`outcomes/.current-lane`）。index 可以从
+  `events.jsonl` 重建；缺失或过期的 current-lane 会回退到 `main`。默认 repo
+  seal 还会把 open outcome 和本地 verification provenance park 在 WAL 旁边
+  （`outcomes/.in-progress.jsonl`、`outcomes/.driftseal-local-outcome.json`）。
+  这两份文件不能重建：删掉 park 会丢掉尚未 flush 的 open outcome，删掉
+  provenance 会改变 verifier 信任。自定义 `$DRIFTSEAL_HOME` 会把 open outcome
+  直接写入 WAL，provenance 仍放在该 log 旁边。outcomes 目录在 Git worktree 内时，
+  这些 sidecar 会被 gitignore。默认 repo seal 下每个 worktree 各自一份；共享的
+  `$DRIFTSEAL_HOME` 会共用那里实际存在的文件。
 - advisory hook 只提示 lifecycle 状态，不会扩大 repo 中 `AGENTS.md` 的政策边界。
 
 DriftSeal 不会替你判断 verification command 是否安全，也不会判断测试本身是否充分。

package/bin/driftseal.js

@@ -20,7 +20,8 @@
  *
  * Seal root: $DRIFTSEAL_HOME, or .seal in cwd.
  * Outcome log: <seal-root>/outcomes/events.jsonl.
- * In a Git worktree, an open outcome is parked in Git metadata until end.
+ * In a default Git-repository seal, an open outcome is parked beside the WAL until end.
+ * Custom $DRIFTSEAL_HOME seals write open outcomes directly to the WAL.
  * MADR records: <seal-root>/madr/.
  */
 
@@ -59,10 +60,22 @@ const PROTOCOL_VERSION = '2.1';
 const DEFAULT_LOG_LANGUAGE = 'en';
 const DEFAULT_LANE = 'main';
 const LANE_NAME_RE = /^[a-z][a-z0-9-]{0,62}$/;
-const IN_PROGRESS_GIT_PATH = 'driftseal-v2-in-progress.jsonl';
-const CURRENT_LANE_GIT_PATH = 'driftseal-v2-current-lane';
-const LANE_INDEX_GIT_PATH = 'driftseal-v3-outcome-index.sqlite';
-const LEGACY_LANE_INDEX_GIT_PATH = 'driftseal-v2-lane-index.json';
+const IN_PROGRESS_SIDECAR = '.in-progress.jsonl';
+const WORKSPACE_SIDECAR_IGNORE_NAMES = Object.freeze([
+  '.current-lane',
+  '.lane-index.json',
+  '.in-progress.jsonl',
+  '.driftseal-local-outcome.json',
+  '.outcome-index.sqlite',
+  '.outcome-index.sqlite-journal',
+  '.outcome-index.sqlite-wal',
+  '.outcome-index.sqlite-shm',
+  '..outcome-index.sqlite.*.tmp',
+  '..outcome-index.sqlite.*.tmp-*',
+  '..current-lane.*.tmp',
+  '..in-progress.jsonl.*.tmp',
+  '..driftseal-local-outcome.json.*.tmp',
+]);
 const LOCK_STALE_MS = 30 * 60 * 1000;
 const LOCK_INIT_STALE_MS = 5 * 1000;
 const READ_ONLY_NOTICE = '(read-only: another mutation holds the lock; tail repair skipped)';
@@ -574,13 +587,6 @@ function gitWorktreeRoot(cwd = process.cwd()) {
   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 isParkableOutcomeLog() {
   if (process.env.DRIFTSEAL_HOME) return false;
   const root = gitWorktreeRoot();
@@ -588,30 +594,45 @@ function isParkableOutcomeLog() {
   return path.resolve(logFile()) === path.resolve(root, '.seal', 'outcomes', 'events.jsonl');
 }
 
+function inProgressFileForLog(file) {
+  return path.join(path.dirname(file), IN_PROGRESS_SIDECAR);
+}
+
 function inProgressFile() {
   if (!isParkableOutcomeLog()) return null;
-  return worktreeInProgressFile();
+  return inProgressFileForLog(logFile());
 }
 
-function worktreeMetadataFile(gitPath, cwd = process.cwd()) {
-  if (!isGitWorkTree(cwd)) return null;
-  const resolved = gitCapture(['rev-parse', '--git-path', gitPath], cwd);
-  if (!resolved) return null;
-  return path.resolve(cwd, resolved);
+function existingInProgressFileForLog(file) {
+  return inProgressFileForLog(file);
+}
+
+function existingInProgressFile() {
+  if (!isParkableOutcomeLog()) return null;
+  return existingInProgressFileForLog(logFile());
+}
+
+function adoptInProgressFile() {
+  const current = inProgressFile();
+  if (!current) return null;
+  ensureDerivedLaneSidecarIgnore();
+  ensureDirectoryDurable(path.dirname(current));
+  return current;
 }
 
 function currentLaneFile() {
-  if (isParkableOutcomeLog()) return worktreeMetadataFile(CURRENT_LANE_GIT_PATH);
+  // Keep the worktree-local pointer beside the WAL so agent sandboxes that
+  // deny .git writes can still switch lanes.
   return path.join(logDir(), '.current-lane');
 }
 
 function laneIndexFile() {
-  if (isParkableOutcomeLog()) return worktreeMetadataFile(LANE_INDEX_GIT_PATH);
+  // Keep the disposable index beside the WAL so agent sandboxes that deny
+  // .git writes can still rebuild it inside the workspace.
   return path.join(logDir(), '.outcome-index.sqlite');
 }
 
 function legacyLaneIndexFile() {
-  if (isParkableOutcomeLog()) return worktreeMetadataFile(LEGACY_LANE_INDEX_GIT_PATH);
   return path.join(logDir(), '.lane-index.json');
 }
 
@@ -619,14 +640,17 @@ function emptyLaneCatalog() {
   return outcomeFoldEngine.emptyLaneCatalog();
 }
 
-function readCurrentLaneName() {
-  const file = currentLaneFile();
-  if (!file || !fs.existsSync(file)) return DEFAULT_LANE;
+function readLaneNameFromFile(file) {
+  if (!file || !fs.existsSync(file)) return null;
   const name = fs.readFileSync(file, 'utf8').trim();
-  if (!name) return DEFAULT_LANE;
+  if (!name) return null;
   return normalizeLaneName(name);
 }
 
+function readCurrentLaneName() {
+  return readLaneNameFromFile(currentLaneFile()) || DEFAULT_LANE;
+}
+
 function writeCurrentLaneName(name, { readOnly = false } = {}) {
   if (readOnly) return;
   const file = currentLaneFile();
@@ -636,29 +660,59 @@ function writeCurrentLaneName(name, { readOnly = false } = {}) {
   atomicWriteFile(file, `${name}\n`, 0o600);
 }
 
+function existingAncestor(dir) {
+  let current = path.resolve(dir);
+  while (!fs.existsSync(current)) {
+    const parent = path.dirname(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+  return current;
+}
+
+function listedIgnoreNames(content) {
+  return new Set(
+    content
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0)
+  );
+}
+
+function workspaceSidecarIgnoreFile() {
+  return path.join(logDir(), '.gitignore');
+}
+
+function gitContainedOutcomeLog() {
+  return isGitWorkTree(existingAncestor(logDir()));
+}
+
+function workspaceSidecarIgnoreComplete() {
+  const ignoreFile = workspaceSidecarIgnoreFile();
+  if (!fs.existsSync(ignoreFile)) return false;
+  const listed = listedIgnoreNames(fs.readFileSync(ignoreFile, 'utf8'));
+  return WORKSPACE_SIDECAR_IGNORE_NAMES.every((name) => listed.has(name));
+}
+
+function canPersistDerivedOutcomeIndex() {
+  return !gitContainedOutcomeLog() || workspaceSidecarIgnoreComplete();
+}
+
 function ensureDerivedLaneSidecarIgnore() {
-  if (isParkableOutcomeLog()) return;
-  if (!isGitWorkTree(logDir())) return;
-  const ignoreFile = path.join(logDir(), '.gitignore');
+  if (!gitContainedOutcomeLog()) return { changed: false, target: null };
+  const ignoreFile = workspaceSidecarIgnoreFile();
   let current = fs.existsSync(ignoreFile) ? fs.readFileSync(ignoreFile, 'utf8') : '';
+  const listed = listedIgnoreNames(current);
   let next = current;
-  for (const name of [
-    '.current-lane',
-    '.lane-index.json',
-    '.outcome-index.sqlite',
-    '.outcome-index.sqlite-journal',
-    '.outcome-index.sqlite-wal',
-    '.outcome-index.sqlite-shm',
-    '..outcome-index.sqlite.*.tmp',
-  ]) {
-    const present = next.split(/\r?\n/).some((line) => line.trim() === name);
-    if (present) continue;
+  for (const name of WORKSPACE_SIDECAR_IGNORE_NAMES) {
+    if (listed.has(name)) continue;
     if (next && !next.endsWith('\n')) next += '\n';
     next += `${name}\n`;
   }
-  if (next === current) return;
+  if (next === current) return { changed: false, target: ignoreFile };
   ensureDirectoryDurable(logDir());
   atomicWriteFile(ignoreFile, next, 0o644);
+  return { changed: true, target: ignoreFile };
 }
 
 function hashFilePrefix(file, length) {
@@ -817,16 +871,15 @@ function replaceOutcomeIndexFile(temporary, target) {
 }
 
 function removeLegacyLaneIndex() {
-  const legacy = legacyLaneIndexFile();
-  if (legacy) fs.rmSync(legacy, { force: true });
+  fs.rmSync(legacyLaneIndexFile(), { force: true });
 }
 
 function rebuildCommittedOutcomeIndex({ repairTail = false } = {}) {
   const wal = logFile();
   const target = laneIndexFile();
   if (!target) return null;
+  if (!canPersistDerivedOutcomeIndex()) return null;
   ensureDirectoryDurable(path.dirname(target));
-  ensureDerivedLaneSidecarIgnore();
   const temporary = temporaryIndexPath(target);
   removeIndexFiles(temporary);
   let index;
@@ -872,6 +925,7 @@ function syncCommittedLaneIndex({ repairTail = false, readOnly = false, forceFul
   const wal = logFile();
   const target = laneIndexFile();
   if (!target) return null;
+  if (!readOnly && !canPersistDerivedOutcomeIndex()) return null;
   if (readOnly) {
     if (!fs.existsSync(target)) return null;
     try {
@@ -993,7 +1047,7 @@ function recoverableOutcomeIndexError(error) {
 }
 
 function loadOutcomeView({ repairTail = false, readOnly = false } = {}) {
-  const park = inProgressFile();
+  const park = existingInProgressFile();
   let index = syncCommittedLaneIndex({ repairTail, readOnly });
   if (!index) {
     const records = fold(readEvents({ repairTail, readOnly }));
@@ -1095,7 +1149,7 @@ function indexedLaneSummary(state, name) {
 }
 
 function tryLoadRecentOutcomeView(n, { includeReclaimed = false, repairTail = false, readOnly = false } = {}) {
-  const park = inProgressFile();
+  const park = existingInProgressFile();
   let index = syncCommittedLaneIndex({ repairTail, readOnly });
   if (!index) return null;
   const query = () => {
@@ -1150,7 +1204,7 @@ function readJsonlRecordsFromFile(file, { repairTail = false, readOnly = false }
   if (
     readOnly &&
     process.env._DRIFTSEAL_TEST_UNLINK_PARK_BEFORE_READ === '1' &&
-    path.basename(file) === IN_PROGRESS_GIT_PATH
+    path.basename(file) === IN_PROGRESS_SIDECAR
   ) {
     // Simulate a writer flushing and unlinking the park between the existence
     // check and the read; the next attempt sees the park as absent.
@@ -1232,13 +1286,13 @@ function planIndexedInProgressOverlay(index, park, { repairTail = false, readOnl
 }
 
 function discardInProgressLog(park) {
-  fs.unlinkSync(park);
+  fs.rmSync(park, { force: true });
   fsyncDirectory(path.dirname(park));
 }
 
 function reconcileInProgressRecords(
   committedEvents,
-  { repairTail = false, readOnly = false, park = inProgressFile() } = {}
+  { repairTail = false, readOnly = false, park = existingInProgressFile() } = {}
 ) {
   const plan = planInProgressOverlay(committedEvents, park, { repairTail, readOnly });
   if (!plan) return [];
@@ -1260,7 +1314,7 @@ function readEventsSnapshot(file, { repairTail = false, readOnly = false } = {})
     reconcileInProgressRecords(events, {
       repairTail,
       readOnly,
-      park: worktreeInProgressFile(),
+      park: existingInProgressFileForLog(file),
     }).map((record) => record.event)
   );
 }
@@ -1389,7 +1443,7 @@ function appendEventTo(file, event) {
  * Returns the outcome ids it had to remap.
  */
 function flushInProgressLog() {
-  const park = inProgressFile();
+  const park = adoptInProgressFile();
   if (!park || !fs.existsSync(park)) return new Map();
   const committedRecords = readJsonlRecordsFromFile(logFile());
   const plan = planInProgressOverlay(
@@ -1419,7 +1473,8 @@ function parkedOpenOutcome(park) {
 }
 
 function appendEvent(event) {
-  const park = inProgressFile();
+  ensureDerivedLaneSidecarIgnore();
+  const park = adoptInProgressFile();
   if (!park) {
     const stored = appendEventTo(logFile(), event);
     if (event.type === 'begin') writeLocalOutcomeProvenance(stored);
@@ -1434,7 +1489,7 @@ function appendEvent(event) {
   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
+  // Close in the tracked log, never only in the park: 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') {
@@ -1448,11 +1503,7 @@ function contentHash(content) {
 }
 
 function localOutcomeProvenanceFile() {
-  const root = gitWorktreeRoot();
-  const key = contentHash(path.resolve(logFile())).slice(0, 16);
-  if (!root) return path.join(logDir(), LOCAL_OUTCOME_PROVENANCE_FILE);
-  const gitPath = gitCapture(['rev-parse', '--git-path', `driftseal-local-outcome-${key}.json`]);
-  return gitPath ? path.resolve(process.cwd(), gitPath) : null;
+  return path.join(logDir(), LOCAL_OUTCOME_PROVENANCE_FILE);
 }
 
 function localOutcomeLogIdentity() {
@@ -1471,6 +1522,7 @@ function localOutcomeProvenanceFingerprint({ id, ts, verify }) {
 function writeLocalOutcomeProvenance(event) {
   const file = localOutcomeProvenanceFile();
   if (!file) return;
+  ensureDerivedLaneSidecarIgnore();
   ensureDirectoryDurable(path.dirname(file));
   atomicWriteFile(
     file,
@@ -1484,8 +1536,7 @@ function writeLocalOutcomeProvenance(event) {
   );
 }
 
-function readLocalOutcomeProvenance() {
-  const file = localOutcomeProvenanceFile();
+function parseLocalOutcomeProvenance(file) {
   if (!file || !fs.existsSync(file)) return null;
   try {
     const provenance = JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -1503,6 +1554,10 @@ function readLocalOutcomeProvenance() {
   }
 }
 
+function readLocalOutcomeProvenance() {
+  return parseLocalOutcomeProvenance(localOutcomeProvenanceFile());
+}
+
 function hasMatchingLocalOutcomeProvenance(outcome) {
   const provenance = readLocalOutcomeProvenance();
   return (
@@ -1519,11 +1574,13 @@ function hasMatchingLocalOutcomeProvenance(outcome) {
 }
 
 function clearLocalOutcomeProvenance(id) {
-  const file = localOutcomeProvenanceFile();
   const provenance = readLocalOutcomeProvenance();
-  if (!file || !provenance || provenance.id !== id) return;
-  fs.unlinkSync(file);
-  fsyncDirectory(path.dirname(file));
+  if (!provenance || provenance.id !== id) return;
+  const file = localOutcomeProvenanceFile();
+  if (file && fs.existsSync(file)) {
+    fs.unlinkSync(file);
+    fsyncDirectory(path.dirname(file));
+  }
 }
 
 function atomicWriteFile(target, content, createMode = 0o644) {
@@ -3362,6 +3419,8 @@ const SKILL_RELEASE_DIGESTS = new Set([
   '42a0549dff21483c0508ea4a79658e7bf05cd98f8af4238c95dbd23cdcde7ee6', // 2.0.0 outcome workflow
   '38e89060ff37ecdd663eae73a3e0c646d6bb220fc8232a5762356375d84ba69b', // 2.1.0 outcome lanes
   'b4b2cc27ea71c5777b5eb9b67d861fbe1da43f31ab5d422d6a877e0cad592493', // 2.1.0 lane re-anchor recovery
+  '6c49523c2f4a36ea1cd9d0b4e793ea3cdbd9d299174cf1f9a0a54f3d9a7cd331', // workspace park sidecar wording
+  '678cbaa8380f75f7a45d634010b500e51a59b06ea759eaf23cff2980142662f0', // default-seal parking help wording
 ]);
 
 function skillInstallUsage() {
@@ -3783,11 +3842,9 @@ function hookLogFile() {
   const root = gitWorktreeRoot(current);
   while (true) {
     const candidate = path.join(current, '.seal', 'outcomes', '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 workspacePark = path.join(current, '.seal', 'outcomes', IN_PROGRESS_SIDECAR);
+    if (fs.existsSync(candidate) || fs.existsSync(workspacePark)) return candidate;
+    if (root && path.resolve(root) === current) return null;
     const parent = path.dirname(current);
     if (parent === current) return null;
     current = parent;
@@ -4620,8 +4677,12 @@ function finishAbsorb({
   allowConflict = false,
   followupMessage = null,
 }) {
-  // An outcome parked in Git metadata is part of our side even though the log never saw it.
-  const park = shouldAttachInProgress(outputFile) ? inProgressFile() : null;
+  // A parked outcome is local even though the tracked log never saw it.
+  const park = shouldAttachInProgress(outputFile)
+    ? dryRun
+      ? existingInProgressFileForLog(outputFile)
+      : adoptInProgressFile() || existingInProgressFileForLog(outputFile)
+    : null;
   const plan = planInProgressOverlay(result.map((record) => record.event), park, {
     repairTail: true,
   });
@@ -4992,7 +5053,7 @@ function runMachineVerification({ allowTrackedCommand = false } = {}) {
       fail(`outcome ${outcome.id} has no acceptance criteria; declare them with driftseal begin --accept`);
     }
     if (!outcome.verify) fail(`outcome ${outcome.id} has no verification command`);
-    const park = inProgressFile();
+    const park = existingInProgressFile();
     const parked = park ? parkedOpenOutcome(park) : null;
     const locallyProvenanced = hasMatchingLocalOutcomeProvenance(outcome);
     return {
@@ -6691,10 +6752,11 @@ const commands = {
     } catch (err) {
       printLine(`warning: could not configure git merge driver: ${err && err.message ? err.message : err}`);
     }
+    const indexIgnore = ensureDerivedLaneSidecarIgnore();
 
     if (localLog) warnIfDefaultLogsTracked();
 
-    if (updated === current && !attributes.changed && !driver.changed) {
+    if (updated === current && !attributes.changed && !driver.changed && !indexIgnore.changed) {
       printLine('AGENTS.md already contains the DriftSeal protocols; nothing to do');
       return { changed: false, target };
     }
@@ -6708,6 +6770,9 @@ const commands = {
     if (driver.changed) {
       printLine('Configured local git merge driver for DriftSeal outcome logs');
     }
+    if (indexIgnore.changed) {
+      printLine(`Configured derived outcome-index ignore: ${indexIgnore.target}`);
+    }
     return { changed: true, target };
   },
 
@@ -6785,7 +6850,7 @@ seal root: $DRIFTSEAL_HOME, or .seal in the current directory
 outcome log: <seal-root>/outcomes/events.jsonl
 MADR records: <seal-root>/madr/
 $DRIFTSEAL_DECISION_HOME is a v1-only default for migration source detection; v2 runtime ignores it.
-In a Git worktree, begin parks an open outcome in Git metadata until end, so merge does not need a log-only commit.`);
+In a default Git-repository seal, begin parks an open outcome beside the WAL until end, so merge does not need a log-only commit. Custom $DRIFTSEAL_HOME seals write that open outcome directly to events.jsonl.`);
     return null;
   },
 
@@ -7197,7 +7262,7 @@ function dispatch(argv) {
         if (cmd === 'hook') {
           // Hooks read the nearest ancestor log, not the cwd-relative one: lock
           // the directory of the file the hook will actually read (the park a
-          // writer flushes under that same lock lives in the repo's Git metadata).
+          // writer flushes under that same lock lives beside the WAL).
           // With no ancestor log the hook prints nothing, so skip locking — this
           // also avoids creating a spurious <cwd>/.intent-log.
           const hookFile = hookLogFile();
@@ -7205,6 +7270,14 @@ function dispatch(argv) {
           resources = [path.dirname(hookFile)];
         } else if (legacyParkedIntent()) {
           resources = [path.dirname(legacyIntentLogFile())];
+        } else if (!fs.existsSync(logDir())) {
+          // Do not mkdir a cwd-relative seal just to lock a read: status/log
+          // from a subdirectory would otherwise plant packages/**/.seal.
+          const data = fn(rest, { readOnly: true });
+          return {
+            data,
+            exitCode: data && Number.isInteger(data.exitCode) ? data.exitCode : 0,
+          };
         } else {
           resources = [logDir()];
         }

package/package.json

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

package/skills/use-driftseal/SKILL.md

@@ -47,13 +47,14 @@ If `status` or `log` fails with a duplicate id or with `multiple outcomes in
 progress`, or the outcome log has conflict markers, run `driftseal absorb`
 instead of editing `.seal/outcomes/events.jsonl`. When both sides still have an
 open outcome, add `--abandon-theirs` or `--abandon-ours`; this works whether your
-open outcome sits in the log or is parked in Git metadata. `driftseal init` also
+open outcome sits in the log or is parked beside the WAL. `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 outcome log, so `git merge`
-can run with an outcome still in progress. `end` writes the closed record to
-`.seal/outcomes/events.jsonl`; if it is interrupted, the outcome stays open
-there and `end` can be run again.
+In a default Git-repository seal, `begin` parks beside the WAL and does not dirty
+the tracked outcome log, so `git merge` can run with an outcome still in
+progress. Custom `$DRIFTSEAL_HOME` seals write that open outcome directly to
+`events.jsonl`. `end` writes the closed record to `.seal/outcomes/events.jsonl`;
+if it is interrupted, the outcome stays open there and `end` can be run again.
 
 For a v1 repository, do not reinterpret or delete the old logs directly. Use
 `driftseal migrate v1-to-v2 inspect`, prepare a reviewed grouping plan, apply