wowbagger 0.1.0-alpha.9 → 0.5.0

package/src/claim-request.js

@@ -4,6 +4,7 @@
 // requestSchemaError encodes for the reference model — production code must not
 // depend on test code, so the rules are duplicated here rather than imported.
 import { pointer } from './request.js';
+import { validateLedgerRepairRequest } from './ledger-repair.js';
 
 const NAMESPACE_ID = /^wbns_[a-f0-9]{32}$/;
 const ITEM_ID = /^wb_[0-9A-HJKMNP-TV-Z]{26}$/;
@@ -24,7 +25,15 @@ const REQUIRED_MEMBERS = {
 // Returns an array of {path, code, message} issues (empty when the request is valid).
 // The request must already be JSON-parsed and deep-normalized (plain objects/arrays,
 // JsonNumber unwrapped) — this module only checks shape, not JSON syntax.
+//
+// `number-repair` is a ledger-repair request, not a work-claim one. It is
+// answered here because the claim journal validates every entry it replays
+// through this seam, so a repair request the journal accepts must be the exact
+// request the command accepts. Its members are the repair domain's own.
 export function validateClaimRequest(operation, request) {
+  if (operation === 'number-repair') {
+    return validateLedgerRepairRequest(request);
+  }
   const required = REQUIRED_MEMBERS[operation];
   if (!isPlainObject(request)) {
     return [problem([], 'invalid-type', `The ${operation} request must be a JSON object.`)];

package/src/claim-store.js

@@ -127,7 +127,12 @@ export function namespaceLockHeld(hold, storePath) {
     && hold.storePath === storePath;
 }
 
-export async function withClaimLock(storePath, fn) {
+// `withClaimLock` is the one file-lock primitive; the counter name says which
+// lock a caller is taking, so a profile can hold each one to its own number
+// instead of watching a single total drift.
+export async function withClaimLock(storePath, fn, {
+  counter = 'namespace_lock_acquisitions',
+} = {}) {
   const directory = path.dirname(storePath);
   await mkdir(directory, { recursive: true });
   const lockPath = `${storePath}.lock`;
@@ -143,7 +148,7 @@ export async function withClaimLock(storePath, fn) {
   }
 
   try {
-    await acquireClaimLock(candidatePath, lockPath, recoveryPath);
+    await acquireClaimLock(candidatePath, lockPath, recoveryPath, counter);
     const hold = { [NAMESPACE_LOCK_HOLD]: true, storePath, released: false };
     try {
       return await fn(hold);
@@ -158,7 +163,7 @@ export async function withClaimLock(storePath, fn) {
   }
 }
 
-async function acquireClaimLock(candidatePath, lockPath, recoveryPath) {
+async function acquireClaimLock(candidatePath, lockPath, recoveryPath, counter) {
   for (;;) {
     const recoveryOwner = await readLockOwner(recoveryPath);
     if (recoveryOwner) {
@@ -168,7 +173,7 @@ async function acquireClaimLock(candidatePath, lockPath, recoveryPath) {
     }
     try {
       await link(candidatePath, lockPath);
-      recordCount('namespace_lock_acquisitions');
+      recordCount(counter);
       return;
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error;

package/src/cli.js

@@ -1,5 +1,6 @@
+import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { mkdir, open, writeFile } from 'node:fs/promises';
+import { access, link, mkdir, open, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -7,13 +8,16 @@ import { resolveClaimBackend, resolveWorkClaimCapability } from './claim-capabil
 import {
   appendClaimEntry,
   claimJournalPath,
+  isClaimJournalCapacityError,
   claimReconcileLogPath,
+  parseReconcileLog,
   replayClaimJournal,
   writeReconcileLog,
 } from './claim-journal.js';
 import { claimAcquire, claimRead, claimRelease, claimRenew } from './claim-operations.js';
 import {
   adoptItemRevision,
+  hydrateClaimJournalFromHead,
   publishClaimed,
   reconcileClaimJournal,
   readPublicationOutcome,
@@ -23,7 +27,7 @@ import {
 } from './claim-publication.js';
 import { loadExtensionDeclaration } from './extensions.js';
 import { validateClaimRequest } from './claim-request.js';
-import { checkProspectiveMerge, parseReconcileLog } from './claim-prospective.js';
+import { checkProspectiveMerge } from './claim-prospective.js';
 import { proposeExtensionDeclaration } from './extension-provision.js';
 import { selectCommittedAdoptions } from './claim-sync.js';
 import {
@@ -36,6 +40,14 @@ import {
 import { readGitTreeFile, readGitTreeLedger } from './git-reconciliation.js';
 import { finalizeFromRecoveryToken, withAutoCommit } from './git-autocommit.js';
 import { loadLedger } from './ledger.js';
+import {
+  finalizeNumberRepairCommit,
+  isNumberRepairRecoveryToken,
+  ledgerRepairInvalidRequest,
+  numberRepair,
+  numberRepairProposal,
+} from './ledger-repair.js';
+import { inspectVersionDrift } from './version-drift.js';
 import {
   assertReportOutputOutsideLedger,
   buildReportModel,
@@ -80,10 +92,20 @@ import { normalizeJsonValue, parseJsonRequest, sortIssues } from './request.js';
 import { selectReady } from './ready.js';
 import { isCalendarDate, validateLedger } from './validate.js';
 import { inspectWorkbench } from './workbench.js';
+import { readWorktreeIdentity } from './worktree-identity.js';
 
 const CLAIM_OPERATIONS = { read: claimRead, acquire: claimAcquire, renew: claimRenew, release: claimRelease };
 const MUTATION_CONTRACT_VERSION = 5;
-const AUTO_COMMIT_COMMANDS = new Set(['create', 'transition', 'patch', 'publish-claimed']);
+const ITEM_ID = /^wb_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+const AUTO_COMMIT_COMMANDS = new Set([
+  'create',
+  'transition',
+  'parent-migrate',
+  'snooze',
+  'patch',
+  'publish-claimed',
+  'number-repair',
+]);
 // The report failures this command states. A code outside the set is an
 // unexpected condition, never a classification the command can pass through.
 const REPORT_FAILURE_CODES = new Set([
@@ -110,7 +132,7 @@ const COMMAND_SUMMARIES = {
   list: 'List a validated ledger as bounded, paginated item summaries.',
   create: 'Create one ledger item through atomic, no-clobber publication.',
   transition: "Transition one item's lifecycle, guarded by lock and compare-and-swap.",
-  'parent-migrate': 'Move one live item to or from an epic with CAS fencing.',
+  'parent-migrate': 'Move one item to or from an epic with CAS fencing.',
   snooze: 'Set or clear an item snooze date with CAS fencing.',
   patch: "Patch an item's priority and relation lists, guarded the same way.",
   'extensions-provision': 'Declare explicitly selected existing extension members.',
@@ -120,6 +142,11 @@ const COMMAND_SUMMARIES = {
   'claim-sync': 'Import committed adoption evidence into the local claim journal.',
   'claim-adopt': 'Rule a committed out-of-protocol item revision legitimate.',
   'mutation-finalize': 'Complete the Git commit an auto-commit mutation could not establish.',
+  'version-drift': 'Check installed skill and running core version compatibility.',
+  'number-repair': 'Apply a proposed duplicate-number repair to a ledger the mutation gate refuses.',
+  provision: 'Provision a Git-backed work-claim namespace.',
+  claim: 'Read and coordinate work claims for one ledger.',
+  'claim-verify': 'Reconcile the durable claim journal with ledger bytes and Git.',
 };
 
 const KNOWN_COMMANDS = new Set([
@@ -144,6 +171,8 @@ const KNOWN_COMMANDS = new Set([
   'claim-sync',
   'claim-adopt',
   'mutation-finalize',
+  'version-drift',
+  'number-repair',
 ]);
 
 const CLAIM_SUBCOMMAND_SUMMARIES = {
@@ -178,6 +207,22 @@ export async function runCli(argumentsList, { scenario } = {}) {
     return;
   }
 
+  if (command === 'version-drift') {
+    const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
+    if (parsedOptions.issues.length > 0) {
+      writeInvalidRequest(command, parsedOptions.issues);
+      return;
+    }
+    writeClaimEnvelope(await inspectVersionDrift({
+      skillPath: parsedOptions.options.skill
+        ?? fileURLToPath(new URL('../skills/wowbagger/SKILL.md', import.meta.url)),
+      packagePath: fileURLToPath(new URL('../package.json', import.meta.url)),
+      runningDistribution: DISTRIBUTION_VERSION,
+      runningContractVersion: 5,
+    }));
+    return;
+  }
+
   if (command === 'capabilities') {
     const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
     if (parsedOptions.issues.length > 0) {
@@ -380,8 +425,25 @@ export async function runCli(argumentsList, { scenario } = {}) {
       writeInvalidRequest(command, parsedRequest.issues);
       return;
     }
+    const ledger = await loadLedger(parsedOptions.options.ledger);
+    const validation = validateLedger(ledger);
+    if (!validation.valid) {
+      process.stdout.write(`${JSON.stringify({
+        ok: false,
+        command,
+        contract_version: MUTATION_CONTRACT_VERSION,
+        state: 'unchanged',
+        error: {
+          code: 'ledger-invalid',
+          message: 'The configured ledger is invalid.',
+          details: { validation_errors: validation.errors },
+        },
+      })}\n`);
+      process.exitCode = 3;
+      return;
+    }
     const proposal = proposeExtensionDeclaration({
-      ledger: await loadLedger(parsedOptions.options.ledger),
+      ledger,
       members: parsedRequest.value?.members,
     });
     if (!proposal.ok) {
@@ -415,34 +477,72 @@ export async function runCli(argumentsList, { scenario } = {}) {
       })}\n`);
       return;
     }
+    const sameDeclaration = (declaration) => declaration
+      && Object.keys(declaration.members).length === Object.keys(proposal.declaration.members).length
+      && Object.entries(proposal.declaration.members)
+        .every(([name, type]) => declaration.members[name] === type);
+    const refuseConflict = () => {
+      process.stdout.write(`${JSON.stringify({
+        ok: false,
+        command,
+        contract_version: MUTATION_CONTRACT_VERSION,
+        state: 'unchanged',
+        error: {
+          code: 'extension-declaration-conflict',
+          message: 'The ledger already carries a different extension declaration.',
+          details: { output: '.wowbagger/extensions.json' },
+        },
+      })}\n`);
+      process.exitCode = 4;
+    };
     const existing = await loadExtensionDeclaration(parsedOptions.options.ledger);
     if (existing.declared) {
-      const same = existing.declaration
-        && JSON.stringify(existing.declaration) === JSON.stringify(proposal.declaration);
-      if (!same) {
-        process.stdout.write(`${JSON.stringify({
-          ok: false,
-          command,
-          contract_version: MUTATION_CONTRACT_VERSION,
-          state: 'unchanged',
-          error: {
-            code: 'extension-declaration-conflict',
-            message: 'The ledger already carries a different extension declaration.',
-            details: { output: '.wowbagger/extensions.json' },
-          },
-        })}\n`);
-        process.exitCode = 4;
+      if (!sameDeclaration(existing.declaration)) {
+        refuseConflict();
         return;
       }
     } else {
       await mkdir(path.dirname(output), { recursive: true });
-      const handle = await open(output, 'wx');
+      if (scenario === 'extension-provision-concurrent-same') {
+        await writeFile(
+          output,
+          '{\n  "extensions_version": 1,\n  "members": {"tags":"string-list"}\n}\n',
+          { flag: 'wx' },
+        );
+      } else if (scenario === 'extension-provision-concurrent-different') {
+        await writeFile(
+          output,
+          '{"extensions_version":1,"members":{"tier":"string"}}\n',
+          { flag: 'wx' },
+        );
+      }
+      const temporary = path.join(path.dirname(output), `.extensions-${randomUUID()}.tmp`);
+      const handle = await open(temporary, 'wx');
       try {
         await handle.writeFile(proposal.source, 'utf8');
         await handle.sync();
       } finally {
         await handle.close();
       }
+      try {
+        await extensionProvisionCheckpoint(scenario, parsedOptions.options.ledger);
+        try {
+          await link(temporary, output);
+        } catch (error) {
+          if (error?.code !== 'EEXIST') throw error;
+          const winner = await loadExtensionDeclaration(parsedOptions.options.ledger);
+          if (!winner.declared || !sameDeclaration(winner.declaration)) {
+            refuseConflict();
+            return;
+          }
+        }
+      } finally {
+        try {
+          await unlink(temporary);
+        } catch (error) {
+          if (error?.code !== 'ENOENT') throw error;
+        }
+      }
     }
     process.stdout.write(`${JSON.stringify({
       ok: true,
@@ -608,6 +708,12 @@ export async function runCli(argumentsList, { scenario } = {}) {
       writeClaimInvalidRequest(command, parsedOptions.issues);
       return;
     }
+    if (parsedOptions.options.id !== undefined && !ITEM_ID.test(parsedOptions.options.id)) {
+      writeClaimInvalidRequest(command, [
+        issue('/arguments', 'invalid-value', 'Argument --id must be a canonical Wowbagger item ID.'),
+      ]);
+      return;
+    }
     const ledgerDirectory = parsedOptions.options.ledger;
     const gitCommonDir = await resolveVerifiedGitCommonDir(ledgerDirectory);
     const namespace = gitCommonDir ? await readNamespace(ledgerDirectory) : null;
@@ -621,6 +727,7 @@ export async function runCli(argumentsList, { scenario } = {}) {
       ledgerDirectory,
       gitCommonDir,
       namespace,
+      targetItemId: parsedOptions.options.id ?? null,
     }));
     return;
   }
@@ -815,6 +922,13 @@ export async function runCli(argumentsList, { scenario } = {}) {
       writeClaimInvalidRequest(command, parsedOptions.issues);
       return;
     }
+    if (isNumberRepairRecoveryToken(parsedOptions.options.recoveryToken)) {
+      writeClaimEnvelope(await finalizeNumberRepairCommit({
+        ledgerDirectory: parsedOptions.options.ledger,
+        token: parsedOptions.options.recoveryToken,
+      }));
+      return;
+    }
     writeClaimEnvelope(await finalizeFromRecoveryToken({
       ledgerDirectory: parsedOptions.options.ledger,
       token: parsedOptions.options.recoveryToken,
@@ -822,6 +936,47 @@ export async function runCli(argumentsList, { scenario } = {}) {
     return;
   }
 
+  // The proposal is request-free and read-only: the ledger is its whole input.
+  if (command === 'number-repair-proposal') {
+    const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
+    if (parsedOptions.issues.length > 0) {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, parsedOptions.issues));
+      return;
+    }
+    writeClaimEnvelope(await numberRepairProposal(parsedOptions.options.ledger));
+    return;
+  }
+
+  if (command === 'number-repair') {
+    const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
+    if (parsedOptions.issues.length > 0) {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, parsedOptions.issues));
+      return;
+    }
+    let bytes;
+    try {
+      bytes = await requestSource(parsedOptions.options.input);
+    } catch {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, [
+        issue('/input', 'invalid-value', 'Request input could not be read.'),
+      ]));
+      return;
+    }
+    const parsedRequest = parseJsonRequest(bytes);
+    if (parsedRequest.issues.length > 0) {
+      writeClaimEnvelope(ledgerRepairInvalidRequest(command, parsedRequest.issues));
+      return;
+    }
+    // normalizeJsonValue rebuilds the tree into plain objects with every
+    // JsonNumber unwrapped, so the exact-member check cannot be slipped past
+    // with a `__proto__` member and the number witnesses compare as numbers.
+    writeClaimEnvelope(await numberRepair(normalizeJsonValue(parsedRequest.value), {
+      ledgerDirectory: parsedOptions.options.ledger,
+      autoCommit: parsedOptions.options.autoCommit === true,
+    }));
+    return;
+  }
+
   if (command === 'claim-adopt') {
     const parsedOptions = parseContractOptions(command, argumentsList.slice(1));
     if (parsedOptions.issues.length > 0) {
@@ -1302,29 +1457,34 @@ function parseContractOptions(command, argumentsList) {
   const options = {};
   const issues = [];
   const seen = new Set();
-  const valueFlags = command === 'inspect'
-    ? new Map([['--ledger', 'ledger'], ['--id', 'id'], ['--number', 'number'], ['--as-of', 'asOf']])
-    : command === 'report'
-      ? new Map([['--ledger', 'ledger'], ['--as-of', 'asOf'], ['--out', 'out'], ['--view', 'view']])
-      : command === 'create' || command === 'transition' || command === 'patch' || command === 'list'
-        || command === 'parent-migrate'
-        || command === 'snooze'
-        || command === 'extensions-provision'
-        || command === 'publish-claimed' || command === 'publication-read'
-        || command === 'claim-read' || command === 'claim-acquire' || command === 'claim-renew'
-        || command === 'claim-release' || command === 'claim-adopt'
-        ? new Map([['--ledger', 'ledger'], ['--input', 'input']])
-        : command === 'mutation-finalize'
-          ? new Map([['--ledger', 'ledger'], ['--recovery-token', 'recoveryToken']])
-          : command === 'claim-merge-verify'
-            ? new Map([['--ledger', 'ledger'], ['--base', 'base'], ['--head', 'head']])
-            : command === 'provision' || command === 'claim-capabilities' || command === 'claim-verify'
-              || command === 'claim-sync'
-              ? new Map([['--ledger', 'ledger']])
-            : command === 'mint-id'
-              ? new Map([['--date', 'date']])
-              : new Map();
-  // Bare flags carry no value. `--auto-commit` is accepted only on the four
+  const valueFlags = command === 'version-drift'
+    ? new Map([['--skill', 'skill']])
+    : command === 'inspect'
+      ? new Map([['--ledger', 'ledger'], ['--id', 'id'], ['--number', 'number'], ['--as-of', 'asOf']])
+      : command === 'report'
+        ? new Map([['--ledger', 'ledger'], ['--as-of', 'asOf'], ['--out', 'out'], ['--view', 'view']])
+        : command === 'create' || command === 'transition' || command === 'patch' || command === 'list'
+          || command === 'parent-migrate'
+          || command === 'snooze'
+          || command === 'extensions-provision'
+          || command === 'publish-claimed' || command === 'publication-read'
+          || command === 'claim-read' || command === 'claim-acquire' || command === 'claim-renew'
+          || command === 'claim-release' || command === 'claim-adopt'
+          || command === 'number-repair'
+          ? new Map([['--ledger', 'ledger'], ['--input', 'input']])
+          : command === 'mutation-finalize'
+            ? new Map([['--ledger', 'ledger'], ['--recovery-token', 'recoveryToken']])
+            : command === 'claim-merge-verify'
+              ? new Map([['--ledger', 'ledger'], ['--base', 'base'], ['--head', 'head']])
+              : command === 'claim-verify'
+                ? new Map([['--ledger', 'ledger'], ['--id', 'id']])
+                : command === 'provision' || command === 'claim-capabilities'
+                  || command === 'claim-sync' || command === 'number-repair-proposal'
+                  ? new Map([['--ledger', 'ledger']])
+                : command === 'mint-id'
+                  ? new Map([['--date', 'date']])
+                  : new Map();
+  // Bare flags carry no value. `--auto-commit` is accepted only on the
   // commands whose Git finalization it folds in; `--workbench` only on the one
   const bareFlags = AUTO_COMMIT_COMMANDS.has(command)
     ? new Map([['--auto-commit', 'autoCommit']])
@@ -1333,13 +1493,17 @@ function parseContractOptions(command, argumentsList) {
       : command === 'inspect'
         ? new Map([['--workbench', 'workbench']])
         : new Map();
-  const optionalFlags = command === 'mint-id'
-    ? new Set(['--date'])
-    : command === 'report'
-      ? new Set(['--out', '--view'])
-      : command === 'inspect'
-        ? new Set(['--id', '--number', '--as-of'])
-        : new Set();
+  const optionalFlags = command === 'version-drift'
+    ? new Set(['--skill'])
+    : command === 'mint-id'
+      ? new Set(['--date'])
+      : command === 'report'
+        ? new Set(['--out', '--view'])
+        : command === 'inspect'
+          ? new Set(['--id', '--number', '--as-of'])
+          : command === 'claim-verify'
+            ? new Set(['--id'])
+            : new Set();
   for (let index = 0; index < argumentsList.length; index += 1) {
     const argument = argumentsList[index];
     if (argument === '--json') {
@@ -1372,6 +1536,7 @@ function parseContractOptions(command, argumentsList) {
       continue;
     }
     seen.add(argument);
+
     const value = argumentsList[index + 1];
     if (!value || value.startsWith('--')) {
       issues.push(argumentIssue(index + 1, 'missing-argument', `Argument ${argument} requires a value.`));
@@ -1410,6 +1575,23 @@ function parseContractOptions(command, argumentsList) {
   return { options, issues: sortIssues(issues) };
 }
 
+async function extensionProvisionCheckpoint(scenario, ledgerDirectory) {
+  if (scenario !== 'extension-provision-pause-before-link') return;
+  const reached = path.join(ledgerDirectory, '.wowbagger-test-extension-provision-reached');
+  const allowed = path.join(ledgerDirectory, '.wowbagger-test-extension-provision-continue');
+  await writeFile(reached, 'reached\n');
+  const deadline = Date.now() + 2_000;
+  while (Date.now() < deadline) {
+    try {
+      await access(allowed);
+      return;
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  throw new Error('Timed out waiting to continue extension declaration publication.');
+}
 // `--auto-commit` is the only bare flag beyond `--json`, and it changes what
 // happens after the mutation, never the mutation itself.
 function autoCommitted(command, options, run, scenario, operationId = null, targetItemId = null) {
@@ -1451,6 +1633,7 @@ function writeInvalidRequest(command, issues) {
     ok: false,
     command,
     contract_version: MUTATION_CONTRACT_VERSION,
+    ...(command === 'parent-migrate' || command === 'snooze' ? { state: 'unchanged' } : {}),
     error: outcome.error,
   })}\n`);
   process.exitCode = outcome.exit;
@@ -1623,18 +1806,42 @@ async function runClaimCommand(claimCommand, argumentsList) {
   const operation = CLAIM_OPERATIONS[claimCommand];
   if (claimCommand === 'read') {
     try {
-      const replayed = await replayClaimJournal(journalPath, namespace);
+      // The lock-free read never writes: it projects committed evidence in
+      // memory so an unhydrated worktree still answers with the real claim.
+      const replayed = await hydrateClaimJournalFromHead({
+        ledgerDirectory: parsedOptions.options.ledger,
+        gitCommonDir,
+        namespace,
+        replayed: await replayClaimJournal(journalPath, namespace),
+        persist: false,
+      });
       writeClaimEnvelope(operation(replayed.state, request, new Date().toISOString()).envelope);
-    } catch {
-      writeClaimEnvelope(claimStoreUnavailable(claimCommand, 'claim-store-unreadable'));
+    } catch (error) {
+      writeClaimEnvelope(claimStoreUnavailable(
+        claimCommand,
+        isClaimJournalCapacityError(error) ? 'journal-capacity-exceeded' : 'claim-store-unreadable',
+      ));
     }
     return;
   }
   try {
     const envelope = await withClaimLock(storePath, async () => {
+      // A claim lifecycle command classifies item reconciliation and refuses
+      // on it, so it must reason from the same writer evidence every other
+      // classifying surface uses; otherwise one command grants a claim on
+      // exactly the state another command refuses to write. It writes no item
+      // byte and no writer-attributed entry, so it reads the identity it
+      // already answers to rather than creating one. Journal and identity are
+      // both store state this command only reads, so neither reading failure
+      // is anything but an unreadable store.
       let replayed;
+      let currentWorktreeId;
       try {
         replayed = await replayClaimJournal(journalPath, namespace);
+        currentWorktreeId = await readWorktreeIdentity({
+          ledgerDirectory: parsedOptions.options.ledger,
+          gitCommonDir,
+        });
       } catch (error) {
         throw taggedFailure('CLAIM_STORE_UNREADABLE', error);
       }
@@ -1648,6 +1855,8 @@ async function runClaimCommand(claimCommand, argumentsList) {
           replayed,
           physicalNow,
           targetItemId: request.item_id,
+          currentWorktreeId,
+          writeLogOnUnsafe: false,
         });
       } catch (error) {
         throw taggedFailure(
@@ -1657,7 +1866,15 @@ async function runClaimCommand(claimCommand, argumentsList) {
           error,
         );
       }
-      if (reconciled.unsafe) {
+      // Release relinquishes authority; it never extends or grants any. A
+      // barrier that refuses it strands the lease in the worktree least able
+      // to clear the barrier, because no other worktree can take the item over
+      // while the claim is held. Acquire and renew do extend authority against
+      // bytes nobody has ruled legitimate, so they keep refusing. Only this
+      // classification is bypassed: an unresolvable identity, an unreadable
+      // journal, and a clock floor that will not persist all throw before this
+      // point, and the tuple compare-and-swap below still rules on the request.
+      if (reconciled.unsafe && claimCommand !== 'release') {
         return claimStoreUnavailable(claimCommand, 'publication-reconciliation-required', {
           findings: reconciled.findings,
         });
@@ -1697,6 +1914,10 @@ async function runClaimCommand(claimCommand, argumentsList) {
       writeClaimEnvelope(claimStoreUnavailable(claimCommand, 'claim-store-locked'));
       return;
     }
+    if (isClaimJournalCapacityError(error)) {
+      writeClaimEnvelope(claimStoreUnavailable(claimCommand, 'journal-capacity-exceeded'));
+      return;
+    }
     if (error?.code === 'CLAIM_STORE_UNREADABLE') {
       writeClaimEnvelope(claimStoreUnavailable(claimCommand, 'claim-store-unreadable'));
       return;
@@ -1827,7 +2048,7 @@ function usage(command) {
     return 'Usage: wowbagger claim-adopt --ledger <dir> --input <request.json> --json';
   }
   if (command === 'claim-verify') {
-    return 'Usage: wowbagger claim-verify --ledger <dir> --json';
+    return 'Usage: wowbagger claim-verify --ledger <dir> [--id <wb_...>] --json';
   }
   if (command === 'snooze') {
     return 'Usage: wowbagger snooze --ledger <dir> --input <request.json> --json [--auto-commit]';
@@ -1843,6 +2064,17 @@ function usage(command) {
     return 'Usage: wowbagger mutation-finalize --ledger <dir> --recovery-token <token> --json';
   }
 
+  if (command === 'version-drift') {
+    return 'Usage: wowbagger version-drift [--skill <path>] --json';
+  }
+  if (command === 'number-repair-proposal') {
+    return 'Usage: wowbagger number-repair-proposal --ledger <dir> --json';
+  }
+
+  if (command === 'number-repair') {
+    return 'Usage: wowbagger number-repair --ledger <dir> --input <json-file|-> --json [--auto-commit]';
+  }
+
   if (command === 'claim') {
     return 'Usage: wowbagger claim <read|acquire|renew|release|capabilities> [options]';
   }
@@ -1977,6 +2209,20 @@ function commandHelp(command) {
     ].join('\n');
   }
 
+  if (command === 'list') {
+    return [
+      header,
+      '',
+      `${usage(command)}`,
+      '',
+      'Request JSON members: query_version, as_of, filters, sort, page_size, and cursor.',
+      'sort is {field, direction}; direction is ascending or descending.',
+      'Use the returned page.next_cursor as cursor to resume a stable snapshot.',
+      'A changed snapshot returns list-snapshot-changed; restart without cursor.',
+      '',
+    ].join('\n');
+  }
+
   return [
     header,
     '',

package/src/extensions.js

@@ -47,6 +47,7 @@ export const RESERVED_EXTENSION_MEMBERS = Object.freeze([
   'body',
   'number',
   'priority',
+  'extensions',
 ]);
 
 const RESERVED = new Set(RESERVED_EXTENSION_MEMBERS);