driftseal 1.1.6 → 1.2.0

package/README.md

@@ -73,8 +73,9 @@ driftseal skill install --target kimi-code --scope global
 | `cursor` | `.cursor/skills/use-driftseal` | `~/.cursor/skills/use-driftseal` |
 
 Use `--root <repository>` to select a project when running the installer
-elsewhere. Repeated installs of identical content are no-ops; a different
-existing skill requires `--force`. MCP and lifecycle hooks are optional
+elsewhere. Repeated installs of identical content are no-ops, and a skill left
+by an earlier DriftSeal release is upgraded in place; only a skill this
+installer never wrote requires `--force`. MCP and lifecycle hooks are optional
 adapters; enable them only for a concrete host constraint or reminder need, not
 as additional policy layers.
 
@@ -212,9 +213,12 @@ If the scope changes, close the current intent as `partial` or `abandoned`, then
 Git operations are entirely outside the intent log because Git maintains their
 history. Inspection, branch and worktree management, staging, commits, merges,
 rebases, cherry-picks, tags, and pushes never need an intent of their own. They
-still require normal authorization and safety checks. Single-step builds and
-checks, such as compiling or running tests, also need no intent. Any non-Git
-content change starts a new work round.
+still require normal authorization and safety checks. A command whose result
+can be reconstructed from Git state, such as a patch file regenerated from a
+commit range or a scratch harness that re-runs, needs no intent either; content
+that will be committed and cannot be reconstructed, such as a `.gitignore`
+edit, does. Single-step builds and checks, such as compiling or running tests,
+also need no intent. Any other non-Git content change starts a new work round.
 
 ## Commands
 
@@ -236,7 +240,7 @@ content change starts a new work round.
 | `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | Install the repository-pinned MCP server into Codex, Kimi Code, OpenCode, Claude Code, or Cursor. |
 | `driftseal hook install --target TARGET [--scope project\|global] [--root path] [--force]` | Install advisory lifecycle reminders into Kimi Code, Claude Code, or Codex. |
 | `driftseal hook prompt\|stop [--format plain\|claude-code]` | Emit the reminder a lifecycle hook injects; never blocks. |
-| `driftseal init [--lang <tag>]` | Add the adoption protocol to `AGENTS.md` and configure the git merge driver. `--lang` sets the intent/decision log language (BCP 47, default `en`). |
+| `driftseal init [--lang <tag>] [--local-log]` | Add the adoption protocol to `AGENTS.md` and configure the git merge driver. `--lang` sets the intent/decision log language (BCP 47, default `en`). `--local-log` keeps the logs local and untracked instead of committing them with the code; if the logs are already tracked, init warns with the remediation steps and leaves the index and `.gitignore` untouched. |
 | `driftseal --version` or `driftseal -V` | Print the installed DriftSeal version. |
 | `driftseal help` | Print CLI usage. |
 

package/README.zh-CN.md

@@ -71,7 +71,8 @@ driftseal skill install --target kimi-code --scope global
 | `cursor` | `.cursor/skills/use-driftseal` | `~/.cursor/skills/use-driftseal` |
 
 如果不在目标 repository 中执行，用 `--root <repository>` 明确指定项目。
-重复安装相同内容不会产生改动；目标位置已有不同版本时必须显式传入 `--force`。
+重复安装相同内容不会产生改动；旧版本 DriftSeal 装下的 skill 会被直接原地升级，
+只有安装器从未写过的 skill 才需要显式传入 `--force`。
 MCP 与 lifecycle hook 都是可选适配层；只有确实存在 host 限制或提醒需求时
 才启用，不要把它们叠成额外的 policy 层。
 
@@ -201,8 +202,10 @@ driftseal end \
 
 Git 操作完全不计入 intent log，因为 Git 会自行维护历史。查看状态、管理 branch
 或 worktree、stage、commit、merge、rebase、cherry-pick、tag 和 push 都不需要
-单独开启 intent，但仍须遵守正常的授权与安全要求。编译、跑测试等单步构建或检查
-也不需要 intent；只要要做非 Git 内容改动，就开启新一轮。
+单独开启 intent，但仍须遵守正常的授权与安全要求。结果能从 Git 状态重建的命令
+——比如从 commit range 重新生成的 patch 文件、可以重跑的临时 harness——也不需要
+intent；会被提交且无法重建的内容改动（比如编辑 `.gitignore`）则需要。编译、跑测试
+等单步构建或检查同样不需要 intent；除此之外的非 Git 内容改动，都要开启新一轮。
 
 ## 命令速览
 
@@ -224,7 +227,7 @@ Git 操作完全不计入 intent log，因为 Git 会自行维护历史。查看
 | `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | 把固定到 repository 的 MCP server 安装到 Codex、Kimi Code、OpenCode、Claude Code 或 Cursor。 |
 | `driftseal hook install --target TARGET [--scope project\|global] [--root path] [--force]` | 把建议性的 lifecycle 提醒安装到 Kimi Code、Claude Code 或 Codex。 |
 | `driftseal hook prompt\|stop [--format plain\|claude-code]` | 输出 lifecycle hook 注入的提醒；绝不阻断。 |
-| `driftseal init [--lang <tag>]` | 把接入协议写入 `AGENTS.md`，并配置 git merge driver。`--lang` 设置 intent / decision log 的语言（BCP 47，默认 `en`）。 |
+| `driftseal init [--lang <tag>] [--local-log]` | 把接入协议写入 `AGENTS.md`，并配置 git merge driver。`--lang` 设置 intent / decision log 的语言（BCP 47，默认 `en`）。`--local-log` 让日志保持本地、不入库，不随代码提交；如果日志已被 git 跟踪，init 会打印警告和处理建议，但不会改动 index 或 `.gitignore`。 |
 | `driftseal --version` 或 `driftseal -V` | 输出当前安装的 DriftSeal 版本。 |
 | `driftseal help` | 查看 CLI 用法。 |
 

package/bin/driftseal-mcp.js

@@ -6,6 +6,8 @@ const { createApi, DECISION_STATUSES, END_STATUSES } = require('./driftseal.js')
 
 const SERVER_NAME = 'driftseal';
 const SERVER_VERSION = require('../package.json').version;
+const READ_ONLY_SUFFIX =
+  '(read-only: another mutation holds the lock; this snapshot may be incomplete)';
 
 function parseArguments(argv) {
   let root = process.cwd();
@@ -75,11 +77,14 @@ function registerTools(server, api, z) {
     status: z.enum(END_STATUSES).or(z.literal('in_progress')),
     note: z.string().nullable(),
     verifyResult: z.string().nullable(),
+    beginHead: z.string().nullable(),
+    endHead: z.string().nullable(),
     beganAt: z.string(),
     endedAt: z.string().nullable(),
     reclaimed: z.boolean(),
     reclaimReason: z.string().nullable(),
     reclaimedAt: z.string().nullable(),
+    readOnly: z.boolean().optional(),
   });
   const decisionRecord = z.object({
     id: z.string(),
@@ -115,15 +120,24 @@ function registerTools(server, api, z) {
       description:
         'Inspect the one intent currently in progress before repository work or after context loss. Returns null when no intent is open.',
       inputSchema: {},
-      outputSchema: { root: z.string(), intent: intentRecord.nullable() },
+      outputSchema: {
+        root: z.string(),
+        intent: intentRecord.nullable(),
+        readOnly: z.boolean().optional(),
+      },
       annotations: readOnly,
     },
     async () =>
       guarded(() => {
         const intent = api.status();
+        const readOnly = api.readOnly;
+        const snapshot = intent && readOnly ? { ...intent, readOnly: true } : intent;
+        const summary = snapshot
+          ? `Intent ${snapshot.id} is ${snapshot.status}.`
+          : 'No DriftSeal intent is in progress.';
         return success(
-          { root: api.root, intent },
-          intent ? `Intent ${intent.id} is ${intent.status}.` : 'No DriftSeal intent is in progress.'
+          { root: api.root, intent: snapshot, ...(readOnly ? { readOnly: true } : {}) },
+          readOnly ? `${summary} ${READ_ONLY_SUFFIX}` : summary
         );
       })
   );
@@ -184,13 +198,22 @@ function registerTools(server, api, z) {
         last: z.number().int().positive().max(100).optional(),
         includeReclaimed: z.boolean().default(false),
       },
-      outputSchema: { root: z.string(), intents: z.array(intentRecord) },
+      outputSchema: {
+        root: z.string(),
+        intents: z.array(intentRecord),
+        readOnly: z.boolean().optional(),
+      },
       annotations: readOnly,
     },
     async (input) =>
       guarded(() => {
         const intents = api.log({ last: input.last, all: input.includeReclaimed });
-        return success({ root: api.root, intents }, `Found ${intents.length} DriftSeal intent records.`);
+        const readOnly = api.readOnly;
+        const summary = `Found ${intents.length} DriftSeal intent records.`;
+        return success(
+          { root: api.root, intents, ...(readOnly ? { readOnly: true } : {}) },
+          readOnly ? `${summary} ${READ_ONLY_SUFFIX}` : summary
+        );
       })
   );
 

package/bin/driftseal.js

@@ -38,11 +38,13 @@ const DECISION_STATUSES = [
   'superseded',
 ];
 const EVENT_SCHEMA_VERSION = 3;
-const PROTOCOL_VERSION = 11;
+const PROTOCOL_VERSION = 12;
 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 READ_ONLY_NOTICE = '(read-only: another mutation holds the lock; tail repair skipped)';
+const READ_ONLY_LOCK_WAIT_MS = Number(process.env._DRIFTSEAL_TEST_READ_ONLY_LOCK_WAIT_MS) || 1500;
 const MAX_DECISION_SLUG_LENGTH = 180;
 
 class DriftSealError extends Error {
@@ -52,6 +54,44 @@ class DriftSealError extends Error {
   }
 }
 
+/** Thrown by parseArgs on --help/-h; dispatch prints the usage and exits 0. */
+class HelpRequested extends DriftSealError {
+  constructor(usageKey) {
+    super('help requested');
+    this.name = 'HelpRequested';
+    this.usageKey = usageKey || null;
+  }
+}
+
+/** Single source of truth for per-command usage lines. */
+function usageFor(key) {
+  const lines = {
+    begin: 'usage: driftseal begin "<intent>" [--verify "<how to verify>"] [--decision <id>] [--force]',
+    end: 'usage: driftseal end [id] [options]',
+    status: 'usage: driftseal status',
+    log: 'usage: driftseal log [--last N] [--all]',
+    reclaim:
+      'usage: driftseal reclaim [id ...] --reason "<why>" [--older-than <days>] [--force] [--dry-run]',
+    unreclaim: 'usage: driftseal unreclaim <id> --reason "<why>"',
+    absorb: absorbUsage(),
+    init: 'usage: driftseal init [--lang <tag>] [--local-log]',
+    decision: 'usage: driftseal decision add|update|list|show (run: driftseal help)',
+    'decision add':
+      'usage: driftseal decision add "<title>" --context "..." --outcome "..." [options]',
+    'decision update':
+      'usage: driftseal decision update <id> [--status <status>] --note "<what changed or was confirmed>"',
+    'decision list': 'usage: driftseal decision list [--status STATUS] [--last N | --count]',
+    'decision show': 'usage: driftseal decision show <id>',
+    hook: hookUsage(),
+    'hook install': hookUsage(),
+    'hook prompt': hookUsage(),
+    'hook stop': hookUsage(),
+    mcp: mcpInstallUsage(),
+    skill: skillInstallUsage(),
+  };
+  return lines[key] || null;
+}
+
 let activeOutput = null;
 
 function printLine(value = '') {
@@ -97,6 +137,11 @@ function decisionDir() {
   return process.env.DRIFTSEAL_DECISION_HOME || path.join(process.cwd(), '.decision-log');
 }
 
+// A corrupt log line must not wedge reads; a non-string head degrades to null.
+function normalizeHead(value) {
+  return typeof value === 'string' ? value : null;
+}
+
 function normalizeEvent(event, line) {
   if (!event || typeof event !== 'object' || Array.isArray(event)) {
     fail(`invalid event object on log line ${line}`);
@@ -127,12 +172,12 @@ function normalizeEvent(event, line) {
     if (new Set(decisions).size !== decisions.length) {
       fail(`duplicate linked decision on log line ${line}`);
     }
-    return { ...event, decisions };
+    return { ...event, decisions, head: normalizeHead(event.head) };
   }
 
   if (event.type === 'end') {
     if (!END_STATUSES.includes(event.status)) fail(`invalid end event on log line ${line}`);
-    return event;
+    return { ...event, head: normalizeHead(event.head) };
   }
 
   if (event.type === 'reclaim' || event.type === 'unreclaim') {
@@ -236,8 +281,17 @@ function shouldAttachInProgress(file) {
   return live !== null && sameResolvedPath(file, live);
 }
 
-function readJsonlRecordsFromFile(file, { repairTail = false } = {}) {
+function readJsonlRecordsFromFile(file, { repairTail = false, readOnly = false } = {}) {
   if (!fs.existsSync(file)) return [];
+  if (
+    readOnly &&
+    process.env._DRIFTSEAL_TEST_UNLINK_PARK_BEFORE_READ === '1' &&
+    path.basename(file) === IN_PROGRESS_GIT_PATH
+  ) {
+    // Simulate a writer flushing and unlinking the park between the existence
+    // check and the read; the next attempt sees the park as absent.
+    fs.unlinkSync(file);
+  }
   let content = fs.readFileSync(file, 'utf8');
   const rawLines = content.split('\n');
   if (content.length > 0 && !content.endsWith('\n')) {
@@ -245,14 +299,16 @@ function readJsonlRecordsFromFile(file, { repairTail = false } = {}) {
     try {
       JSON.parse(tail);
     } catch {
-      if (!repairTail) fail(`corrupt final log line in ${file}`);
       const validLength = content.lastIndexOf('\n') + 1;
-      const fd = fs.openSync(file, 'r+');
-      try {
-        fs.ftruncateSync(fd, Buffer.byteLength(content.slice(0, validLength), 'utf8'));
-        fs.fsyncSync(fd);
-      } finally {
-        fs.closeSync(fd);
+      if (!readOnly) {
+        if (!repairTail) fail(`corrupt final log line in ${file}`);
+        const fd = fs.openSync(file, 'r+');
+        try {
+          fs.ftruncateSync(fd, Buffer.byteLength(content.slice(0, validLength), 'utf8'));
+          fs.fsyncSync(fd);
+        } finally {
+          fs.closeSync(fd);
+        }
       }
       content = content.slice(0, validLength);
     }
@@ -279,9 +335,9 @@ function overlayIsCommitted(committedEvents, overlayEvents) {
 }
 
 /** How a parked overlay lines up with the committed log; touches neither file. */
-function planInProgressOverlay(committedEvents, park, { repairTail = false } = {}) {
+function planInProgressOverlay(committedEvents, park, { repairTail = false, readOnly = false } = {}) {
   if (!park || !fs.existsSync(park)) return null;
-  const overlayRecords = readJsonlRecordsFromFile(park, { repairTail });
+  const overlayRecords = readJsonlRecordsFromFile(park, { repairTail, readOnly });
   const overlayEvents = overlayRecords.map((record) => record.event);
   if (overlayEvents.length === 0 || overlayIsCommitted(committedEvents, overlayEvents)) {
     return { park, records: [], mappings: [], alreadyCommitted: true };
@@ -295,29 +351,55 @@ function discardInProgressLog(park) {
   fsyncDirectory(path.dirname(park));
 }
 
-function reconcileInProgressRecords(committedEvents, { repairTail = false, park = inProgressFile() } = {}) {
-  const plan = planInProgressOverlay(committedEvents, park, { repairTail });
+function reconcileInProgressRecords(
+  committedEvents,
+  { repairTail = false, readOnly = false, park = inProgressFile() } = {}
+) {
+  const plan = planInProgressOverlay(committedEvents, park, { repairTail, readOnly });
   if (!plan) return [];
   if (plan.alreadyCommitted) {
-    discardInProgressLog(park);
+    if (!readOnly) discardInProgressLog(park);
     return [];
   }
-  if (plan.mappings.length > 0) writeJsonl(park, plan.records);
+  if (!readOnly && plan.mappings.length > 0) writeJsonl(park, plan.records);
   return plan.records;
 }
 
-function readEvents({ repairTail = false, file = logFile() } = {}) {
-  const records = readJsonlRecordsFromFile(file, { repairTail });
+const READ_ONLY_SNAPSHOT_ATTEMPTS = 3;
+
+function readEventsSnapshot(file, { repairTail = false, readOnly = false } = {}) {
+  const records = readJsonlRecordsFromFile(file, { repairTail, readOnly });
   const events = records.map((record) => record.event);
   if (!shouldAttachInProgress(file)) return events;
   return events.concat(
     reconcileInProgressRecords(events, {
       repairTail,
+      readOnly,
       park: worktreeInProgressFile(),
     }).map((record) => record.event)
   );
 }
 
+function readEvents({ repairTail = false, readOnly = false, file = logFile() } = {}) {
+  if (!readOnly) return readEventsSnapshot(file, { repairTail, readOnly });
+  // Lock-free reads race with a writer flushing the park: the park can pass the
+  // existence check and be unlinked before the read. Retry the whole main+park
+  // snapshot, because the flush may have appended the park to the main log.
+  for (let attempt = 1; ; attempt++) {
+    try {
+      return readEventsSnapshot(file, { repairTail, readOnly });
+    } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      if (attempt >= READ_ONLY_SNAPSHOT_ATTEMPTS) {
+        // The park keeps vanishing; treat it as absent and read the main log only.
+        return readJsonlRecordsFromFile(file, { repairTail, readOnly }).map(
+          (record) => record.event
+        );
+      }
+    }
+  }
+}
+
 function parseJsonlRecords(content, source = 'log') {
   return content
     .split('\n')
@@ -599,17 +681,23 @@ function clearStaleLock(lock) {
   return true;
 }
 
-function acquireMutationLock(resource) {
+const LOCK_WAIT_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
+
+function acquireMutationLock(resource, { waitMs = 0, intervalMs = 100 } = {}) {
   ensureDirectoryDurable(resource);
   const lock = path.join(resource, '.driftseal.lock');
-  for (let attempt = 0; attempt < 2; attempt++) {
+  const deadline = Date.now() + waitMs;
+  for (;;) {
     try {
       fs.mkdirSync(lock, { mode: 0o700 });
       break;
     } catch (err) {
-      if (err.code !== 'EEXIST' || attempt > 0 || !clearStaleLock(lock)) {
+      if (err.code === 'EEXIST' && clearStaleLock(lock)) continue;
+      if (err.code !== 'EEXIST' || Date.now() >= deadline) {
+        if (waitMs > 0) return null;
         fail(`another DriftSeal mutation is in progress (lock: ${lock})`);
       }
+      Atomics.wait(LOCK_WAIT_SIGNAL, 0, 0, intervalMs);
     }
   }
   let token;
@@ -664,7 +752,7 @@ function acquireMutationLock(resource) {
   };
 }
 
-function withMutationLocks(resources, action) {
+function withMutationLocks(resources, action, { tryWaitMs } = {}) {
   const roots = [
     ...new Set(
       resources.map((resource) => {
@@ -697,8 +785,16 @@ function withMutationLocks(resources, action) {
   let actionFailed = false;
   process.once('exit', bestEffortCleanup);
   try {
-    for (const root of roots) releases.push(acquireMutationLock(root));
-    return action();
+    for (const root of roots) {
+      const release =
+        tryWaitMs === undefined
+          ? acquireMutationLock(root)
+          : acquireMutationLock(root, { waitMs: tryWaitMs });
+      if (!release) return null;
+      releases.push(release);
+    }
+    const data = action();
+    return tryWaitMs === undefined ? data : { acquired: true, data };
   } catch (err) {
     actionFailed = true;
     throw err;
@@ -722,6 +818,7 @@ function fold(events) {
         tsBegin: ev.ts,
         intent: ev.intent,
         verify: ev.verify || null,
+        beginHead: ev.head || null,
         decisions: Array.isArray(ev.decisions) ? ev.decisions : [],
         schemaVersion: ev.schemaVersion || 1,
         decisionPrepares: [],
@@ -731,6 +828,7 @@ function fold(events) {
         tsEnd: null,
         note: null,
         verifyResult: null,
+        endHead: null,
         reclaimed: false,
         reclaimReason: null,
         reclaimedAt: null,
@@ -783,6 +881,7 @@ function fold(events) {
       rec.tsEnd = ev.ts;
       rec.note = ev.note || null;
       rec.verifyResult = ev.verifyResult || null;
+      rec.endHead = ev.head || null;
     } else if (ev.type === 'decision_reconcile_prepare') {
       const rec = records.get(ev.id);
       if (!rec) fail(`decision reconciliation references unknown intent id: ${ev.id}`);
@@ -1160,6 +1259,7 @@ function closeIntentAsEscape(events, record, requestedStatus, note, verifyResult
       status,
       note: note || null,
       verifyResult: verifyResult || null,
+      head: gitCapture(['rev-parse', 'HEAD']),
     })
   );
   return status;
@@ -1184,7 +1284,7 @@ function looksLikeFlag(value, spec) {
 }
 
 /** Minimal flag parser: positionals + --flag value / --flag=value / -x value */
-function parseArgs(argv, spec) {
+function parseArgs(argv, spec, usageKey) {
   const positionals = [];
   const flags = {};
   const assignFlag = (name, value) => {
@@ -1198,6 +1298,7 @@ function parseArgs(argv, spec) {
   };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (arg === '--help' || arg === '-h') throw new HelpRequested(usageKey);
     if (arg.startsWith('--')) {
       const eq = arg.indexOf('=');
       const name = eq === -1 ? arg.slice(2) : arg.slice(2, eq);
@@ -1238,6 +1339,9 @@ function render(rec) {
   if (rec.verify) lines.push(`  verify: ${rec.verify}`);
   if (rec.verifyResult) lines.push(`  verify-result: ${rec.verifyResult}`);
   if (rec.note) lines.push(`  note: ${rec.note}`);
+  if (rec.beginHead || rec.endHead) {
+    lines.push(`  head: ${rec.beginHead || '-'}..${rec.endHead || '-'}`);
+  }
   lines.push(`  began: ${rec.tsBegin}` + (rec.tsEnd ? `  ended: ${rec.tsEnd}` : ''));
   if (rec.reclaimed) lines.push(`  reclaimed: ${rec.reclaimReason}`);
   return lines.join('\n');
@@ -1253,6 +1357,8 @@ function publicIntent(rec) {
     status: rec.status,
     note: rec.note,
     verifyResult: rec.verifyResult,
+    beginHead: rec.beginHead,
+    endHead: rec.endHead,
     beganAt: rec.tsBegin,
     endedAt: rec.tsEnd,
     reclaimed: rec.reclaimed,
@@ -1278,6 +1384,7 @@ const DECISION_PROTOCOL_MARKER = '<!-- driftseal-decisions -->';
 const DECISION_PROTOCOL_END = '<!-- /driftseal-decisions -->';
 const LOG_LANGUAGE_COMMENT_RE = /^<!-- driftseal-log-language: ([^>\r\n]+) -->\r?$/m;
 const LOG_LANGUAGE_PROSE_RE = /\*\*Log language:\*\* `([^`]+)`/;
+const LOCAL_LOG_COMMENT_RE = /^<!-- driftseal-local-log: true -->\r?$/m;
 const IRREGULAR_GRANDFATHERED_TAGS = new Map([
   ['en-gb-oed', 'en-GB-oed'],
   ['i-ami', 'i-ami'],
@@ -1461,6 +1568,37 @@ function resolveInitLogLanguage(requested, content) {
   return languages.size === 1 ? [...languages][0] : DEFAULT_LOG_LANGUAGE;
 }
 
+function resolveInitLocalLog(requested, content) {
+  if (requested) return true;
+  const intent = extractManagedBlock(content, INTENT_PROTOCOL_MARKER, INTENT_PROTOCOL_END);
+  if (intent && LOCAL_LOG_COMMENT_RE.test(intent)) return true;
+  const decision = extractManagedBlock(content, DECISION_PROTOCOL_MARKER, DECISION_PROTOCOL_END);
+  return Boolean(decision && LOCAL_LOG_COMMENT_RE.test(decision));
+}
+
+/**
+ * Log languages persisted in the current managed blocks, collected leniently
+ * (no failure on malformed or conflicting declarations: init --lang may be
+ * fixing exactly that). Lets init recognize default blocks written in the
+ * existing language when --lang switches to a new one.
+ */
+function persistedLogLanguages(content) {
+  const languages = new Set();
+  const blocks = [
+    extractManagedBlock(content, INTENT_PROTOCOL_MARKER, INTENT_PROTOCOL_END),
+    extractManagedBlock(content, DECISION_PROTOCOL_MARKER, DECISION_PROTOCOL_END),
+  ];
+  for (const block of blocks) {
+    if (!block) continue;
+    const comment = block.match(LOG_LANGUAGE_COMMENT_RE);
+    const prose = block.match(LOG_LANGUAGE_PROSE_RE);
+    const value = comment ? comment[1] : prose ? prose[1] : null;
+    const canonical = value ? wellFormedBcp47(value.trim()) : null;
+    if (canonical) languages.add(canonical);
+  }
+  return languages;
+}
+
 function protocolBlockKey(block) {
   return block
     .replace(/^<!-- driftseal-log-language: [^>\r\n]+ -->\r?$/m, '<!-- driftseal-log-language: -->')
@@ -1479,10 +1617,10 @@ function stripDecisionLogLanguage(block, language = DEFAULT_LOG_LANGUAGE) {
     .replace(`\n${decisionLogLanguageParagraph(language)}\n`, '');
 }
 
-function intentProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE) {
+function intentProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
   return `${INTENT_PROTOCOL_MARKER}
 <!-- driftseal-version: ${version} -->
-<!-- driftseal-log-language: ${language} -->
+<!-- driftseal-log-language: ${language} -->${localLog ? '\n<!-- driftseal-local-log: true -->' : ''}
 
 ## Agent protocol: intent write-ahead log
 
@@ -1501,23 +1639,31 @@ ${intentLogLanguageParagraph(language)}
    Git operations never need an intent and are not included in the intent log;
    Git maintains their history. This includes inspection, branch and worktree
    management, staging, commits, merges, rebases, cherry-picks, tags, and pushes.
+   A command whose result can be reconstructed from Git state (for example a
+   patch file regenerated from a commit range, or a scratch harness that
+   re-runs) needs no intent; content that will be committed and cannot be
+   reconstructed (for example a .gitignore edit) does.
    Single-step commands that only build or check work already done, such as
    compiling or running tests, also need no intent.
+   Size an intent to the smallest unit that leaves the tree self-consistent
+   and can be verified on its own.
 2. **Execute only the intent.** Scope change? Close the current intent
    (\`driftseal end -s partial|abandoned -n "<why>"\`) and \`driftseal begin\` a new one.
 3. **Verify, then close**: run the declared verification, then
-   \`driftseal end -s completed|partial|failed|abandoned -n "<what happened>" -r "<verify output>"\`.
+   \`driftseal end -s completed|partial|failed|abandoned -n "<what happened>" -r "<what the verification showed, written for the next agent>"\`.
    Never report success without closing the intent.
    Before closing a linked intent as \`completed\` or \`partial\`, reconcile every
    declared decision with \`driftseal decision update <id> --status <status> --note "<why>"\`.
    DriftSeal rejects a successful close when a declared decision was not reconciled.
-   Do not edit a decision after reconciling it; run \`decision update\` again so
-   the final content hash is recorded. Interrupted reconciliation is recovered
+   To revise a decision's prose, edit the file, then run \`decision update\` to
+   record the new content hash. Do not edit a decision after reconciling it;
+   run \`decision update\` again so the final content hash is recorded.
+   Interrupted reconciliation is recovered
    by the next linked \`decision update\` or successful \`end\`. Closing as
    \`failed\` or \`abandoned\` cancels pending recovery for that intent.
    Git operations remain subject to normal authorization and safety requirements
    even though they do not require an intent. Any non-Git content change made while
-   preparing a Git operation does require a new intent.
+   preparing a Git operation does require a new intent, per the step 1 test.
 4. **Re-anchor after context loss**: run \`driftseal status\` and \`driftseal log --last 3\` before
    doing anything else. The open intent is the source of truth: resume it when its
    objective still matches the current task; otherwise close it (\`partial\` or
@@ -1532,12 +1678,42 @@ After a merge collision, run \`driftseal absorb\` rather than editing the log;
 if both sides still have an open intent, add \`--abandon-theirs\` or
 \`--abandon-ours\`.
 
-Log: \`.intent-log/events.jsonl\` (override with \`$DRIFTSEAL_HOME\`); commit it with the code.
+Log: \`.intent-log/events.jsonl\` (override with \`$DRIFTSEAL_HOME\`); ${localLog ? 'this repository keeps the log local and untracked; do not add it to commits.' : 'commit it with the code.'}
 ${INTENT_PROTOCOL_END}`;
 }
 
-function previousIntentProtocolBlock(version) {
-  const v10 = stripIntentLogLanguage(intentProtocolBlock(version, DEFAULT_LOG_LANGUAGE));
+function previousIntentProtocolBlock(version, language = DEFAULT_LOG_LANGUAGE) {
+  const v11 = intentProtocolBlock(version, language)
+    .replace(
+      '-r "<what the verification showed, written for the next agent>"',
+      '-r "<verify output>"'
+    )
+    .replace(
+      '\n   A command whose result can be reconstructed from Git state (for example a\n' +
+        '   patch file regenerated from a commit range, or a scratch harness that\n' +
+        '   re-runs) needs no intent; content that will be committed and cannot be\n' +
+        '   reconstructed (for example a .gitignore edit) does.',
+      ''
+    )
+    .replace(
+      '\n   Size an intent to the smallest unit that leaves the tree self-consistent\n' +
+        '   and can be verified on its own.',
+      ''
+    )
+    .replace(
+      '   To revise a decision\'s prose, edit the file, then run `decision update` to\n' +
+        '   record the new content hash. Do not edit a decision after reconciling it;\n' +
+        '   run `decision update` again so the final content hash is recorded.\n' +
+        '   Interrupted reconciliation is recovered',
+      '   Do not edit a decision after reconciling it; run `decision update` again so\n' +
+        '   the final content hash is recorded. Interrupted reconciliation is recovered'
+    )
+    .replace(
+      'preparing a Git operation does require a new intent, per the step 1 test.',
+      'preparing a Git operation does require a new intent.'
+    );
+  if (version >= 11) return v11;
+  const v10 = stripIntentLogLanguage(v11, language);
   if (version >= 10) return v10;
   const v9 = v10.replace(
       '1. **Write intent first**, before modifying, creating, or deleting files, or\n' +
@@ -1618,10 +1794,10 @@ function protocolEol(content, eol) {
   return eol === '\n' ? content : content.replace(/\n/g, eol);
 }
 
-function decisionProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE) {
+function decisionProtocolBlock(version = PROTOCOL_VERSION, language = DEFAULT_LOG_LANGUAGE, localLog = false) {
   return `${DECISION_PROTOCOL_MARKER}
 <!-- driftseal-decisions-version: ${version} -->
-<!-- driftseal-log-language: ${language} -->
+<!-- driftseal-log-language: ${language} -->${localLog ? '\n<!-- driftseal-local-log: true -->' : ''}
 
 ## Agent protocol: decision log
 
@@ -1645,7 +1821,7 @@ When an intent declares an existing decision with \`--decision <id>\`, use
 \`driftseal decision update\` to record its status transition or explicit confirmation.
 After a merge, colliding decision ids are remapped with \`driftseal absorb\`;
 concurrent edits of a shared decision are not auto-merged.
-Commit \`.decision-log/\` with the code.
+${localLog ? 'Keep `.decision-log/` local and untracked; do not add it to commits.' : 'Commit `.decision-log/` with the code.'}
 ${DECISION_PROTOCOL_END}`;
 }
 
@@ -1700,8 +1876,9 @@ When an intent declares an existing decision with \`--decision <id>\`, use
 Commit \`.decision-log/\` with the code.`;
 }
 
-function previousDecisionProtocolBlock(version) {
-  const v10 = stripDecisionLogLanguage(decisionProtocolBlock(version, DEFAULT_LOG_LANGUAGE));
+function previousDecisionProtocolBlock(version, language = DEFAULT_LOG_LANGUAGE) {
+  if (version >= 11) return decisionProtocolBlock(version, language);
+  const v10 = stripDecisionLogLanguage(decisionProtocolBlock(version, language), language);
   if (version >= 9) return v10;
   const v8 = v10.replace(
     '\nAfter a merge, colliding decision ids are remapped with `driftseal absorb`;\n' +
@@ -1744,11 +1921,18 @@ function upgradeManagedBlock({
         `protocol version ${version} requires a newer DriftSeal client (supported: ${PROTOCOL_VERSION})`
       );
     }
-    if (
-      block !== replacement &&
-      !knownManagedBlocks.includes(block) &&
-      protocolBlockKey(block) !== protocolBlockKey(replacement)
-    ) {
+    // A block counts as unmodified when it matches the replacement or a known
+    // released block, either exactly or once log-language declarations are
+    // neutralized. The lenient key comparison covers every candidate, not just
+    // the replacement, so `--lang` still repairs a block whose comment and
+    // prose disagree even when the same run also toggles local log mode.
+    const key = protocolBlockKey(block);
+    const recognized =
+      block === replacement ||
+      knownManagedBlocks.includes(block) ||
+      key === protocolBlockKey(replacement) ||
+      knownManagedBlocks.some((known) => key === protocolBlockKey(known));
+    if (!recognized) {
       fail(`cannot safely upgrade customized protocol block beginning with ${marker}`);
     }
     return {
@@ -1815,6 +1999,7 @@ function mcpConfigLocation(target, scope, root) {
 
 function parseMcpInstallRequest(argv) {
   const [subcommand, ...rest] = argv;
+  if (subcommand === '--help' || subcommand === '-h') throw new HelpRequested('mcp');
   if (subcommand !== 'install') {
     fail(mcpInstallUsage());
   }
@@ -1823,7 +2008,7 @@ function parseMcpInstallRequest(argv) {
     scope: 'single',
     root: 'single',
     force: 'boolean',
-  });
+  }, 'mcp');
   if (positionals.length > 0 || !flags.target) {
     fail(mcpInstallUsage());
   }
@@ -1984,6 +2169,27 @@ function installMcp(request) {
 
 const SKILL_NAME = 'use-driftseal';
 
+/*
+ * Every skill tree DriftSeal has ever bundled, oldest first, as skillTreeDigest
+ * hashes. `skill install` treats a directory matching one of these as its own
+ * earlier output and upgrades it in place; anything else is someone's local
+ * skill that only --force may replace. Append the new digest whenever the
+ * bundled skill changes, otherwise the next release cannot upgrade this one;
+ * the "bundled use-driftseal skill is a known release" test fails until you do.
+ */
+const SKILL_RELEASE_DIGESTS = new Set([
+  'e996627c96edc7c09599bc454c4225a416aa89e50aef14d4dd569dd21454e882', // 1b76215 initial commit
+  '5f702545b18e117bafcea669b48cdb3b31c98079f97eaa084fd3b4ceff9500e8', // 5c2ec74 intents only for rollback-worthy changes
+  '77f6365590ff181ee6be003930dd1696c363e213368de0f4e89962555af3fabe', // 56380a8 local MCP server
+  'b7e2310eaf20b50b5ec28531471965607e7e070a4f58263e29408b2cd5cdfb11', // 1cc77f6 reclaim markers
+  '08bc63b8dcf0f4f078252179a3fc2ca4ef2632ecb5b9dfe3782a452c3202c2c4', // de4a8a1 skill slimmed into a usage guide
+  '8523459ff81cf0b97a36b30d216956a58d8a3b3b9760f455d7ea334604da335a', // 3a1d6e0 protocol v7 resume semantics
+  'cc98b9348ec222320bfcd285ba3f1f499a42d15b31e9b1d83c35f0206b2d5ba9', // ca16785 CLI-first skill integration
+  '0fd870f8c1b81f8386d986d64742679d56cd1d317c02890830c81876eb9227d6', // da8afd2 1.1.0 absorb
+  '72ddea79940bdf2bce66d491888f11423ae1bd383e1b511028fda617e6f6fb27', // f395778 1.1.6 parked intents
+  'df8bc7035de1a19faf307c92f9bb0f4052e683d1a94881c2c5d5cbef48b67568', // dc9899d 1.1.7 parked intents in absorb (current)
+]);
+
 function skillInstallUsage() {
   return 'usage: driftseal skill install --target <codex|kimi-code|opencode|claude-code|cursor> [--scope project|global] [--root <repository>] [--force]';
 }
@@ -2018,13 +2224,14 @@ function skillInstallLocation(target, scope, root) {
 
 function parseSkillInstallRequest(argv) {
   const [subcommand, ...rest] = argv;
+  if (subcommand === '--help' || subcommand === '-h') throw new HelpRequested('skill');
   if (subcommand !== 'install') fail(skillInstallUsage());
   const { positionals, flags } = parseArgs(rest, {
     target: 'single',
     scope: 'single',
     root: 'single',
     force: 'boolean',
-  });
+  }, 'skill');
   if (positionals.length > 0 || !flags.target) fail(skillInstallUsage());
 
   const target = flags.target.toLowerCase();
@@ -2046,7 +2253,13 @@ function parseSkillInstallRequest(argv) {
   };
 }
 
-function directoryDigest(directory) {
+/*
+ * Identifies a skill tree by its contents alone: relative paths joined with "/"
+ * and file bytes, never file modes or timestamps. The digest therefore stays
+ * stable across platforms, checkouts, and npm tarballs, which is what lets
+ * SKILL_RELEASE_DIGESTS recognize a skill DriftSeal installed earlier.
+ */
+function skillTreeDigest(directory) {
   if (!fs.existsSync(directory)) return null;
   const digest = crypto.createHash('sha256');
 
@@ -2055,12 +2268,12 @@ function directoryDigest(directory) {
     if (stat.isDirectory()) {
       digest.update(`directory\0${relative}\0`);
       for (const name of fs.readdirSync(current).sort()) {
-        visit(path.join(current, name), relative ? path.join(relative, name) : name);
+        visit(path.join(current, name), relative ? `${relative}/${name}` : name);
       }
       return;
     }
     if (stat.isFile()) {
-      digest.update(`file\0${relative}\0${stat.mode & 0o777}\0`);
+      digest.update(`file\0${relative}\0`);
       digest.update(fs.readFileSync(current));
       digest.update('\0');
       return;
@@ -2069,7 +2282,7 @@ function directoryDigest(directory) {
       digest.update(`symlink\0${relative}\0${fs.readlinkSync(current)}\0`);
       return;
     }
-    digest.update(`other\0${relative}\0${stat.mode}\0`);
+    digest.update(`other\0${relative}\0`);
   }
 
   visit(directory, '');
@@ -2096,15 +2309,18 @@ function installSkill(request) {
     fail(`bundled ${SKILL_NAME} skill is missing from this DriftSeal installation: ${sourceDir}`);
   }
 
-  const sourceDigest = directoryDigest(sourceDir);
-  const existingDigest = directoryDigest(skillDir);
+  const sourceDigest = skillTreeDigest(sourceDir);
+  const existingDigest = skillTreeDigest(skillDir);
   if (existingDigest === sourceDigest) {
     printLine(`${SKILL_NAME} skill is already installed for ${targetLabel} (${scope}): ${skillDir}`);
     return { changed: false, target, scope, root, skillDir };
   }
-  if (existingDigest !== null && !force) {
+  // An untouched skill from an earlier DriftSeal upgrades on its own; only a
+  // skill this installer never wrote needs the operator to confirm with --force.
+  const upgraded = existingDigest !== null && SKILL_RELEASE_DIGESTS.has(existingDigest);
+  if (existingDigest !== null && !upgraded && !force) {
     fail(
-      `${targetLabel} already has a different ${SKILL_NAME} skill at ${skillDir}; ` +
+      `${targetLabel} already has a ${SKILL_NAME} skill DriftSeal did not install at ${skillDir}; ` +
         're-run with --force to replace it'
     );
   }
@@ -2134,9 +2350,12 @@ function installSkill(request) {
     throw err;
   }
 
-  printLine(`Installed ${SKILL_NAME} skill for ${targetLabel} (${scope}): ${skillDir}`);
+  printLine(
+    `${upgraded ? 'Upgraded' : 'Installed'} ${SKILL_NAME} skill for ` +
+      `${targetLabel} (${scope}): ${skillDir}`
+  );
   if (scope === 'project') printLine(`Repository root: ${root}`);
-  return { changed: true, target, scope, root, skillDir };
+  return { changed: true, upgraded, target, scope, root, skillDir };
 }
 
 const HOOK_TARGETS = ['kimi-code', 'claude-code', 'codex'];
@@ -2179,7 +2398,7 @@ function parseHookInstallRequest(argv) {
     scope: 'single',
     root: 'single',
     force: 'boolean',
-  });
+  }, 'hook install');
   if (positionals.length > 0 || !flags.target) {
     fail(hookUsage());
   }
@@ -2402,7 +2621,7 @@ function hookLogFile() {
 }
 
 /** Advisory reminder text; null when no ancestor has an intent log yet. */
-function hookReminder(event) {
+function hookReminder(event, { readOnly = false } = {}) {
   const file = hookLogFile();
   if (!file) return null;
   if (event === 'prompt') {
@@ -2413,7 +2632,7 @@ function hookReminder(event) {
       'reminder when it does not apply.'
     );
   }
-  const open = openIntent(fold(readEvents({ file })));
+  const open = openIntent(fold(readEvents({ file, readOnly })));
   if (open) {
     return (
       `DriftSeal reminder: intent ${open.id} is still in_progress: "${open.intent}". ` +
@@ -2427,8 +2646,8 @@ function hookReminder(event) {
   );
 }
 
-function runHookReminder(event, argv) {
-  const { positionals, flags } = parseArgs(argv, { format: 'single' });
+function runHookReminder(event, argv, { readOnly = false } = {}) {
+  const { positionals, flags } = parseArgs(argv, { format: 'single' }, `hook ${event}`);
   if (positionals.length > 0) fail(hookUsage());
   const format = (flags.format || 'plain').toLowerCase();
   if (!['plain', 'claude-code'].includes(format)) {
@@ -2438,7 +2657,7 @@ function runHookReminder(event, argv) {
   // Hooks must never block the agent: any failure exits quietly with no output.
   let reminder = null;
   try {
-    reminder = hookReminder(event);
+    reminder = hookReminder(event, { readOnly });
   } catch {
     reminder = null;
   }
@@ -2477,10 +2696,63 @@ function gitCapture(args, cwd = process.cwd()) {
   return output === null ? null : output.trim();
 }
 
+/**
+ * Capture a single git value without touching the payload: only the one
+ * newline git appends is removed, so paths that begin or end with whitespace
+ * survive intact (`gitCapture` would trim them away).
+ */
+function gitCaptureLine(args, cwd = process.cwd()) {
+  const output = gitCaptureRaw(args, cwd);
+  if (output === null) return null;
+  return output.endsWith('\n') ? output.slice(0, -1) : output;
+}
+
 function isGitWorkTree(cwd = process.cwd()) {
   return gitCapture(['rev-parse', '--is-inside-work-tree'], cwd) === 'true';
 }
 
+/**
+ * Warn (without mutating the index or .gitignore) when local log mode is on
+ * but the default log paths are still tracked by git. The log directories are
+ * resolved relative to the init cwd (init writes ./AGENTS.md there), so a
+ * nested init checks its own logs rather than the repository root's.
+ *
+ * Paths are read from `ls-files -z` with `:(literal)` pathspecs because git's
+ * human-readable listing C-quotes non-ASCII names and treats `*?[\` as
+ * wildcards. The printed remediation uses the fixed names `.intent-log` and
+ * `.decision-log` and is meant to be run from this directory: git resolves
+ * those pathspecs against the init cwd, so the command stays paste-safe in
+ * POSIX shells, cmd.exe, and PowerShell without embedding the repo-relative
+ * prefix or any shell quoting.
+ */
+function warnIfDefaultLogsTracked(cwd = process.cwd()) {
+  if (!isGitWorkTree(cwd)) return;
+  const root = gitCaptureLine(['rev-parse', '--show-toplevel'], cwd);
+  if (!root) return;
+  const prefix = gitCaptureLine(['rev-parse', '--show-prefix'], cwd);
+  if (prefix === null) return;
+  const logNames = ['.intent-log', '.decision-log'];
+  const logDirs = logNames.map((name) => `${prefix}${name}`);
+  const listing = gitCaptureRaw(
+    ['ls-files', '-z', '--', ...logDirs.map((name) => `:(literal)${name}`)],
+    root
+  );
+  if (!listing) return;
+  const files = listing.split('\0').filter((file) => file.length > 0);
+  const trackedNames = logNames.filter((name) => {
+    const dir = `${prefix}${name}`;
+    return files.some((file) => file === dir || file.startsWith(`${dir}/`));
+  });
+  if (trackedNames.length === 0) return;
+  const tracked = trackedNames.map((name) => `${prefix}${name}`);
+  printLine(
+    `warning: local log mode is on, but ${tracked.join(' and ')} ` +
+      `${tracked.length === 1 ? 'is' : 'are'} still tracked by git; run ` +
+      `\`git rm -r --cached -- ${trackedNames.join(' ')}\` from this directory ` +
+      'and add them to .gitignore to keep the logs local'
+  );
+}
+
 function gitOtherHead(cwd = process.cwd()) {
   return (
     gitCapture(['rev-parse', '--verify', 'MERGE_HEAD'], cwd) ||
@@ -2902,6 +3174,7 @@ function abandonOpenIntent(records, targetId, side) {
       status: 'abandoned',
       note: `abandoned during absorb (--abandon-${side})`,
       verifyResult: null,
+      head: gitCapture(['rev-parse', 'HEAD']),
     },
   });
   return targetId;
@@ -3310,10 +3583,10 @@ const commands = {
       verify: '-v',
       decision: 'multiple',
       force: 'boolean',
-    });
+    }, 'begin');
     const intent = positionals.join(' ').trim();
     if (!intent) {
-      fail('usage: driftseal begin "<intent>" [--verify "<how to verify>"] [--decision <id>] [--force]');
+      fail(usageFor('begin'));
     }
     const requestedDecisions = flags.decision || [];
     const index = requestedDecisions.length > 0 ? decisionIndex() : [];
@@ -3357,6 +3630,7 @@ const commands = {
       intent,
       verify: flags.verify || null,
       decisions,
+      head: gitCapture(['rev-parse', 'HEAD']),
     }));
     const record = fold(events).find((candidate) => candidate.id === id);
     printLine(id);
@@ -3368,9 +3642,9 @@ const commands = {
       status: '-s',
       note: '-n',
       'verify-result': '-r',
-    });
+    }, 'end');
     const status = flags.status || 'completed';
-    if (positionals.length > 1) fail('usage: driftseal end [id] [options]');
+    if (positionals.length > 1) fail(usageFor('end'));
     if (!END_STATUSES.includes(status)) {
       fail(`invalid status "${status}" (expected: ${END_STATUSES.join(', ')})`);
     }
@@ -3441,16 +3715,17 @@ const commands = {
       status,
       note: flags.note || null,
       verifyResult: flags['verify-result'] || null,
+      head: gitCapture(['rev-parse', 'HEAD']),
     }));
     const record = fold(events).find((candidate) => candidate.id === target.id);
     printLine(`${target.id} ${status}`);
     return publicIntent(record);
   },
 
-  status(argv) {
-    const { positionals } = parseArgs(argv, {});
-    if (positionals.length > 0) fail('usage: driftseal status');
-    const open = openIntent(fold(readEvents({ repairTail: true })));
+  status(argv, { readOnly = false } = {}) {
+    const { positionals } = parseArgs(argv, {}, 'status');
+    if (positionals.length > 0) fail(usageFor('status'));
+    const open = openIntent(fold(readEvents({ repairTail: true, readOnly })));
     if (!open) {
       printLine('no intent in progress');
       return null;
@@ -3459,10 +3734,10 @@ const commands = {
     return publicIntent(open);
   },
 
-  log(argv) {
-    const { positionals, flags } = parseArgs(argv, { last: '-n', all: 'boolean' });
-    if (positionals.length > 0) fail('usage: driftseal log [--last N] [--all]');
-    let records = fold(readEvents({ repairTail: true }));
+  log(argv, { readOnly = false } = {}) {
+    const { positionals, flags } = parseArgs(argv, { last: '-n', all: 'boolean' }, 'log');
+    if (positionals.length > 0) fail(usageFor('log'));
+    let records = fold(readEvents({ repairTail: true, readOnly }));
     if (!flags.all) records = records.filter((record) => !record.reclaimed);
     if (flags.last) {
       const n = positiveInteger(flags.last, '--last');
@@ -3482,12 +3757,10 @@ const commands = {
       'older-than': 'single',
       force: 'boolean',
       'dry-run': 'boolean',
-    });
+    }, 'reclaim');
     const reason = flags.reason && flags.reason.trim();
     if (!reason) {
-      fail(
-        'usage: driftseal reclaim [id ...] --reason "<why>" [--older-than <days>] [--force] [--dry-run]'
-      );
+      fail(usageFor('reclaim'));
     }
     let olderThanDays = 7;
     if (flags['older-than'] !== undefined) {
@@ -3557,10 +3830,10 @@ const commands = {
   },
 
   unreclaim(argv) {
-    const { positionals, flags } = parseArgs(argv, { reason: '-r' });
+    const { positionals, flags } = parseArgs(argv, { reason: '-r' }, 'unreclaim');
     const reason = flags.reason && flags.reason.trim();
     if (positionals.length !== 1 || !reason) {
-      fail('usage: driftseal unreclaim <id> --reason "<why>"');
+      fail(usageFor('unreclaim'));
     }
     const events = readEvents({ repairTail: true });
     const record = fold(events).find((candidate) => candidate.id === positionals[0]);
@@ -3581,6 +3854,7 @@ const commands = {
 
   decision(argv) {
     const [subcommand, ...rest] = argv;
+    if (subcommand === '--help' || subcommand === '-h') throw new HelpRequested('decision');
     if (subcommand === 'add') {
       const { positionals, flags } = parseArgs(rest, {
         context: '-c',
@@ -3589,12 +3863,12 @@ const commands = {
         driver: 'multiple',
         option: 'multiple',
         consequence: 'multiple',
-      });
+      }, 'decision add');
       const title = positionals.join(' ').replace(/\s+/g, ' ').trim();
       const context = flags.context && flags.context.trim();
       const outcome = flags.outcome && flags.outcome.trim();
       if (!title || !context || !outcome) {
-        fail('usage: driftseal decision add "<title>" --context "..." --outcome "..." [options]');
+        fail(usageFor('decision add'));
       }
       const status = (flags.status || 'accepted').toLowerCase();
       if (!DECISION_STATUSES.includes(status)) {
@@ -3623,10 +3897,10 @@ const commands = {
     }
 
     if (subcommand === 'update') {
-      const { positionals, flags } = parseArgs(rest, { status: '-s', note: '-n' });
+      const { positionals, flags } = parseArgs(rest, { status: '-s', note: '-n' }, 'decision update');
       const note = flags.note && flags.note.trim();
       if (positionals.length !== 1 || !note) {
-        fail('usage: driftseal decision update <id> [--status <status>] --note "<what changed or was confirmed>"');
+        fail(usageFor('decision update'));
       }
 
       let events = readEvents({ repairTail: true });
@@ -3663,9 +3937,9 @@ const commands = {
     }
 
     if (subcommand === 'list') {
-      const { positionals, flags } = parseArgs(rest, { last: '-n', status: '-s', count: 'boolean' });
+      const { positionals, flags } = parseArgs(rest, { last: '-n', status: '-s', count: 'boolean' }, 'decision list');
       if (positionals.length > 0) {
-        fail('usage: driftseal decision list [--status STATUS] [--last N | --count]');
+        fail(usageFor('decision list'));
       }
       if (flags.count && flags.last) fail('--count cannot be combined with --last');
       const last = flags.last && positiveInteger(flags.last, '--last');
@@ -3700,16 +3974,16 @@ const commands = {
     }
 
     if (subcommand === 'show') {
-      const { positionals } = parseArgs(rest, {});
+      const { positionals } = parseArgs(rest, {}, 'decision show');
       if (positionals.length !== 1 || !/^\d+$/.test(positionals[0])) {
-        fail('usage: driftseal decision show <id>');
+        fail(usageFor('decision show'));
       }
       const decision = findDecision(positionals[0]);
       writeOutput(decision.content);
       return publicDecision(decision, { includeContent: true });
     }
 
-    fail('usage: driftseal decision add|update|list|show (run: driftseal help)');
+    fail(usageFor('decision'));
   },
 
   mcp(argv) {
@@ -3721,13 +3995,14 @@ const commands = {
     return installSkill(parseSkillInstallRequest(argv));
   },
 
-  hook(argv) {
+  hook(argv, { readOnly = false } = {}) {
     const [subcommand, ...rest] = argv;
+    if (subcommand === '--help' || subcommand === '-h') throw new HelpRequested('hook');
     if (subcommand === 'install') {
       return installHook(parseHookInstallRequest(rest));
     }
     if (HOOK_EVENTS.includes(subcommand)) {
-      return runHookReminder(subcommand, rest);
+      return runHookReminder(subcommand, rest, { readOnly });
     }
     fail(hookUsage());
   },
@@ -3739,7 +4014,7 @@ const commands = {
       'abandon-theirs': 'boolean',
       'abandon-ours': 'boolean',
       'dry-run': 'boolean',
-    });
+    }, 'absorb');
     if (flags['abandon-theirs'] && flags['abandon-ours']) {
       fail('cannot combine --abandon-theirs and --abandon-ours');
     }
@@ -3756,15 +4031,24 @@ const commands = {
   },
 
   init(argv) {
-    const { positionals, flags } = parseArgs(argv, { lang: 'single' });
-    if (positionals.length > 0) fail('usage: driftseal init [--lang <tag>]');
+    const { positionals, flags } = parseArgs(argv, { lang: 'single', 'local-log': 'boolean' }, 'init');
+    if (positionals.length > 0) fail(usageFor('init'));
     const target = path.join(process.cwd(), 'AGENTS.md');
     const existed = fs.existsSync(target);
     const current = existed ? fs.readFileSync(target, 'utf8') : '';
     const eol = current.includes('\r\n') ? '\r\n' : '\n';
     const language = resolveInitLogLanguage(flags.lang, current);
-    const intentBlock = protocolEol(intentProtocolBlock(PROTOCOL_VERSION, language), eol);
-    const decisionBlock = protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, language), eol);
+    const localLog = resolveInitLocalLog(flags['local-log'] === true, current);
+    // Accept default blocks in the persisted language too, so a single run can
+    // switch language and enable local mode on a default or v11 protocol.
+    const sourceLanguages = [language];
+    if (flags.lang !== undefined) {
+      for (const persisted of persistedLogLanguages(current)) {
+        if (!sourceLanguages.includes(persisted)) sourceLanguages.push(persisted);
+      }
+    }
+    const intentBlock = protocolEol(intentProtocolBlock(PROTOCOL_VERSION, language, localLog), eol);
+    const decisionBlock = protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, language, localLog), eol);
     let updated = current;
     const intent = upgradeManagedBlock({
       content: updated,
@@ -3773,6 +4057,10 @@ const commands = {
       versionPattern: /^<!-- driftseal-version: (\d+) -->\r?$/m,
       replacement: intentBlock,
       knownManagedBlocks: [
+        ...sourceLanguages.flatMap((source) => [
+          protocolEol(intentProtocolBlock(PROTOCOL_VERSION, source), eol),
+          protocolEol(previousIntentProtocolBlock(11, source), eol),
+        ]),
         protocolEol(previousIntentProtocolBlock(2), eol),
         protocolEol(previousIntentProtocolBlock(3), eol),
         protocolEol(previousIntentProtocolBlock(4), eol),
@@ -3793,6 +4081,10 @@ const commands = {
       versionPattern: /^<!-- driftseal-decisions-version: (\d+) -->\r?$/m,
       replacement: decisionBlock,
       knownManagedBlocks: [
+        ...sourceLanguages.flatMap((source) => [
+          protocolEol(decisionProtocolBlock(PROTOCOL_VERSION, source), eol),
+          protocolEol(previousDecisionProtocolBlock(11, source), eol),
+        ]),
         protocolEol(previousDecisionProtocolBlock(2), eol),
         protocolEol(previousDecisionProtocolBlock(3), eol),
         protocolEol(previousDecisionProtocolBlock(4), eol),
@@ -3829,6 +4121,8 @@ const commands = {
       printLine(`warning: could not configure git merge driver: ${err && err.message ? err.message : err}`);
     }
 
+    if (localLog) warnIfDefaultLogsTracked();
+
     if (updated === current && !attributes.changed && !driver.changed) {
       printLine('AGENTS.md already contains the DriftSeal protocols; nothing to do');
       return { changed: false, target };
@@ -3882,8 +4176,10 @@ usage:
                                  targets: kimi-code (global only), claude-code, codex (prompt only)
   driftseal hook prompt|stop [--format plain|claude-code]
                                  emit the reminder a lifecycle hook injects; never blocks
-  driftseal init [--lang <tag>]        inject protocols into ./AGENTS.md and configure the git merge driver
+  driftseal init [--lang <tag>] [--local-log]
+                                 inject protocols into ./AGENTS.md and configure the git merge driver
                                  --lang sets the intent/decision log language (BCP 47, default: en)
+                                 --local-log keeps the logs local and untracked instead of committing them
   driftseal --version | -V             print the installed DriftSeal version
   driftseal help
 
@@ -3913,6 +4209,43 @@ function requestedEndStatus(argv) {
   return 'completed';
 }
 
+/**
+ * Flags that consume the following token as their value, keyed by command or
+ * subcommand, mirroring the value-taking entries of each parseArgs spec.
+ */
+const VALUE_TAKING_FLAGS = {
+  begin: ['--verify', '-v', '--decision'],
+  end: ['--status', '-s', '--note', '-n', '--verify-result', '-r'],
+  log: ['--last', '-n'],
+  reclaim: ['--reason', '-r', '--older-than'],
+  unreclaim: ['--reason', '-r'],
+  absorb: ['--decisions'],
+  init: ['--lang'],
+  'decision add': ['--context', '-c', '--outcome', '-o', '--status', '-s', '--driver', '--option', '--consequence'],
+  'decision update': ['--status', '-s', '--note', '-n'],
+  'decision list': ['--last', '-n', '--status', '-s'],
+  'hook install': ['--target', '--scope', '--root'],
+  'hook prompt': ['--format'],
+  'hook stop': ['--format'],
+  'mcp install': ['--target', '--scope', '--root'],
+  'skill install': ['--target', '--scope', '--root'],
+};
+
+/**
+ * Pre-lock help probe. A bare --help/-h token is help unless it is the value of
+ * a known value-taking flag given without `=`, so a real mutation whose flag
+ * value happens to be --help still enters the locked path and fails in parseArgs.
+ */
+function wantsHelpBeforeLock(cmd, rest) {
+  const key = Object.hasOwn(VALUE_TAKING_FLAGS, `${cmd} ${rest[0]}`) ? `${cmd} ${rest[0]}` : cmd;
+  const valueFlags = VALUE_TAKING_FLAGS[key] || [];
+  return rest.some((arg, index) => {
+    if (arg !== '--help' && arg !== '-h') return false;
+    const previous = index > 0 ? rest[index - 1] : null;
+    return previous === null || !valueFlags.includes(previous);
+  });
+}
+
 function mutationResources(cmd, argv) {
   if (cmd === 'skill') return [parseSkillInstallRequest(argv).skillsDir];
   if (cmd === 'mcp') return [parseMcpInstallRequest(argv).configDir];
@@ -3940,18 +4273,60 @@ function dispatch(argv) {
   }
   const fn = commands[cmd];
   if (!fn) fail(`unknown command: ${cmd} (run: driftseal help)`);
-  const mutates =
-    ['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) || (cmd === 'hook' && ['prompt', 'stop'].includes(rest[0]));
-  if (mutates || readsIntentLog) {
-    const resources = readsIntentLog ? [logDir()] : mutationResources(cmd, rest);
-    const data = withMutationLocks(resources, () => fn(rest));
-    return { data, exitCode: data && Number.isInteger(data.exitCode) ? data.exitCode : 0 };
+  try {
+    // Help must print even while another session holds the mutation lock. The
+    // probe is spec-aware so it never bypasses the lock for a real mutation: a
+    // --help token consumed as a flag value is left for parseArgs to reject.
+    if (wantsHelpBeforeLock(cmd, rest)) return { data: fn(rest), exitCode: 0 };
+    const mutates =
+      ['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) || (cmd === 'hook' && ['prompt', 'stop'].includes(rest[0]));
+    if (mutates || readsIntentLog) {
+      if (readsIntentLog) {
+        let resources;
+        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).
+          // With no ancestor log the hook prints nothing, so skip locking — this
+          // also avoids creating a spurious <cwd>/.intent-log.
+          const hookFile = hookLogFile();
+          if (!hookFile) return { data: fn(rest), exitCode: 0 };
+          resources = [path.dirname(hookFile)];
+        } else {
+          resources = [logDir()];
+        }
+        const locked = withMutationLocks(resources, () => fn(rest), {
+          tryWaitMs: READ_ONLY_LOCK_WAIT_MS,
+        });
+        if (locked !== null) {
+          return {
+            data: locked.data,
+            exitCode:
+              locked.data && Number.isInteger(locked.data.exitCode) ? locked.data.exitCode : 0,
+          };
+        }
+        // Degrade to a lock-free read-only read rather than blocking re-anchoring.
+        if (cmd === 'hook') printError(READ_ONLY_NOTICE);
+        else printLine(READ_ONLY_NOTICE);
+        const data = fn(rest, { readOnly: true });
+        return { data, exitCode: data && Number.isInteger(data.exitCode) ? data.exitCode : 0, readOnly: true };
+      }
+      const resources = mutationResources(cmd, rest);
+      const data = withMutationLocks(resources, () => fn(rest));
+      return { data, exitCode: data && Number.isInteger(data.exitCode) ? data.exitCode : 0 };
+    }
+    return { data: fn(rest), exitCode: 0 };
+  } catch (err) {
+    if (err instanceof HelpRequested) {
+      printLine(usageFor(err.usageKey) || usageFor(cmd) || 'run: driftseal help');
+      return { data: null, exitCode: 0 };
+    }
+    throw err;
   }
-  return { data: fn(rest), exitCode: 0 };
 }
 
 function repositoryRoot(root) {
@@ -3979,7 +4354,7 @@ function runCommand(argv, { root = process.cwd(), isolateStorage = false, captur
   const previousCwd = process.cwd();
   const previousIntentHome = process.env.DRIFTSEAL_HOME;
   const previousDecisionHome = process.env.DRIFTSEAL_DECISION_HOME;
-  const output = { stdout: '', stderr: '', data: null, exitCode: 0 };
+  const output = { stdout: '', stderr: '', data: null, exitCode: 0, readOnly: false };
   const previousOutput = activeOutput;
 
   try {
@@ -3992,6 +4367,7 @@ function runCommand(argv, { root = process.cwd(), isolateStorage = false, captur
     const result = dispatch(argv);
     output.data = result.data;
     output.exitCode = result.exitCode;
+    output.readOnly = result.readOnly === true;
     return output;
   } catch (err) {
     if (capture) {
@@ -4015,9 +4391,18 @@ function appendFlag(argv, flag, value) {
 
 function createApi({ root = process.cwd(), isolateStorage = false } = {}) {
   const fixedRoot = repositoryRoot(root);
-  const call = (argv) => runCommand(argv, { root: fixedRoot, isolateStorage, capture: true }).data;
+  let lastReadOnly = false;
+  const call = (argv) => {
+    const output = runCommand(argv, { root: fixedRoot, isolateStorage, capture: true });
+    lastReadOnly = output.readOnly;
+    return output.data;
+  };
   return Object.freeze({
     root: fixedRoot,
+    /** True when the most recent call fell back to a lock-free read-only snapshot. */
+    get readOnly() {
+      return lastReadOnly;
+    },
     status() {
       return call(['status']);
     },

package/package.json

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