wowbagger 0.1.0-alpha.12 → 0.1.0-alpha.13

package/CHANGELOG.md

@@ -7,6 +7,59 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.1.0-alpha.13 - 2026-08-28
+
+### Fixed
+
+- **Every reconciling command reads the same writer evidence.** `claim-verify`
+  and ordinary mutations named the worktree they spoke for when they
+  classified reconciliation; `publish-claimed`, `claim-adopt`, and the
+  `claim acquire`, `claim renew`, and `claim release` lifecycle commands did
+  not. An unreachable successor written by the current worktree therefore read
+  as advisory sibling synchronization on those surfaces, whose target scoping
+  let `publish-claimed` commit a publication and `claim acquire` grant a claim
+  in exactly the state a `patch` refused. `publish-claimed`, `claim acquire`,
+  and `claim renew` now report `unauthorized-revision` and refuse, matching
+  `claim-verify`. `claim release` stays available: it relinquishes authority
+  rather than extending it, and refusing it would strand 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. The release compare-and-swap is
+  unchanged, so a wrong owner, epoch, or expiry still refuses with
+  `claim-conflict`. A genuine sibling successor and an authorization written
+  before writer identity existed remain advisory synchronization on every
+  surface. `claim-adopt` semantics are unchanged: it reports no reconciliation
+  diagnosis and stays available as the remedy. It now judges its own identity
+  bytes before the worktree roster, so its own malformed identity reports as
+  such instead of as a failed sibling enumeration.
+
+### Known limitations
+
+- **Creates in more than one worktree can commit duplicate item numbers, even
+  when the creates are sequential, and no sanctioned repair exists** (items
+  #181 and #182). Create is journal-silent, so nothing coordinates the number
+  it derives. Any two worktrees whose checkouts have not been integrated derive
+  the next schema-v2 `number` from the base each can see, and both derive the
+  same one. The two creates need not overlap in time: a create in one worktree
+  today and a create in another worktree tomorrow collide just as surely, so
+  long as neither worktree has seen the other's commit. Each create succeeds,
+  each refuses nothing, and reconciliation reports nothing. The collision only
+  exists once the branches are integrated. `validate` then fails globally with
+  `duplicate-number` on every colliding item, and because an invalid ledger
+  blocks every mutation, the whole ledger stops accepting work. `number` is
+  immutable and `patch` correctly rejects it, so Wowbagger currently offers no
+  operation that repairs the collision.
+
+  Until both items ship, serialize `create` through a single worktree, and run
+  `validate` immediately after you integrate branches so a collision surfaces
+  at the merge rather than at the next mutation.
+
+  The PropertyCompass repair — editing `number` in the item source by hand,
+  committing it, then running `claim-adopt` — was an emergency intervention
+  taken under an outage. It is **not a supported workaround**. It bypasses the
+  number-collision and reference checks every mutation performs, and it can
+  leave dangling `depends_on`, `related`, and parent references that nothing
+  reports. Do not adopt it as routine practice.
+
 ## 0.1.0-alpha.12 - 2026-08-28
 
 ### Fixed

package/README.md

@@ -30,8 +30,8 @@ agent to use those guarantees instead of hand-editing your Markdown.
 
 **Start here:** [install the core and set up a ledger](#start-here).
 
-> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.12` is on npm under
-> the `next` tag and on this repository's `v0.1.0-alpha.12` tag. It is the
+> **Status: alpha, published, and self-hosted.** `0.1.0-alpha.13` is on npm under
+> the `next` tag and on this repository's `v0.1.0-alpha.13` tag. It is the
 > version this repository runs its own backlog on. The API is not frozen and the
 > version will move before a stable release.
 >
@@ -77,7 +77,7 @@ Wowbagger is the core authority for a Git-native work ledger. Use it instead
 of editing ledger Markdown by hand.
 
 ```sh
-wowbagger --version                 # require 0.1.0-alpha.12
+wowbagger --version                 # require 0.1.0-alpha.13
 wowbagger capabilities --json       # require contract_version: 5
 wowbagger validate --ledger ledger --json
 wowbagger ready --ledger ledger --as-of YYYY-MM-DD --json
@@ -103,10 +103,10 @@ cooperating writers; they are not exclusive locks.
 Install the core CLI, then verify it. The core requires Node.js 20 or later:
 
 ```sh
-npm install -g wowbagger@0.1.0-alpha.12   # exact plugin-matched release
+npm install -g wowbagger@0.1.0-alpha.13   # exact plugin-matched release
 # or, from this release's Git tag:
-# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.12
-wowbagger --version         # 0.1.0-alpha.12
+# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.13
+wowbagger --version         # 0.1.0-alpha.13
 wowbagger capabilities --json              # must report contract_version: 5
 ```
 
@@ -325,7 +325,7 @@ two supported install routes:
   registry requires a `latest` tag), so a bare install resolves to the same
   bytes.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.12` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.13` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
@@ -397,7 +397,7 @@ Upgrade the pieces you installed:
 
 ```sh
 npm install -g wowbagger@next                  # public npm registry
-npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.12  # immutable Git release
+npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.13  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 

package/docs/work-claim-contract.md

@@ -360,6 +360,31 @@ next mutation refuses. Inside the window, only an actor that bypasses this tool
 can overwrite the item, and this protocol does not defend against that actor.
 It is merge-coordinated, not exclusive.
 
+**Warning: the same window lets more than one worktree commit one item number,
+and nothing repairs it** (items #181 and #182). Because create is
+journal-silent, nothing coordinates the number a create derives. Any two
+worktrees whose checkouts have not been integrated derive the next schema-v2
+`number` from the base each can see, and both derive the same one. The two
+creates need not overlap in time: a create in one worktree today and a create
+in another worktree tomorrow collide just as surely, so long as neither
+worktree has seen the other's commit. Both creates succeed, both refuse
+nothing, and reconciliation reports nothing, because there is no recorded
+revision to compare. The collision becomes visible only when the branches are
+integrated: `validate` then fails globally with `duplicate-number` on every
+colliding item, and an invalid ledger blocks every mutation, so the whole
+ledger stops accepting work. `number` is immutable and `patch` correctly
+rejects it, so this protocol currently offers no operation that repairs the
+collision.
+
+Until both items ship, serialize `create` through a single worktree, and run
+`validate` immediately after you integrate branches so a collision surfaces at
+the merge rather than at the next mutation. Editing `number` in the item
+source by hand, committing it, and then running `claim-adopt` is **not a
+supported workaround**: one field deployment did exactly that as an emergency
+intervention during an outage, and it bypasses the number-collision and
+reference checks every mutation performs, so it can leave dangling
+`depends_on`, `related`, and parent references that nothing reports.
+
 **`unauthorized-revision` has two remedies, and only one of them is
 destructive.** Restoring the authorized revision discards the out-of-protocol
 edit. Adopting the committed revision keeps it and moves the coordinator's
@@ -384,6 +409,57 @@ worktree; it remains `unauthorized-revision` and blocks unrelated mutations.
 This distinguishes a real sibling's uncommitted successor from history the
 current checkout already owns.
 
+**Writer identity.** A legacy mutation and a claimed publication record the
+worktree that authorized them in their journal entries as
+`writer_worktree_id`: `legacy-mutation-intent`, `legacy-mutation`,
+`publish-intent`, and `publish-final`. The field is optional on all of them: an
+entry written before the field existed stays valid and attributes nothing. A
+publication resolves its identity once under the claim lock, so its intent and
+its terminal name one writer, and a terminal that recovery reconstructs after a
+lost response carries the identity its intent recorded. When the journal names
+the current worktree as the writer of the expected revision and no reachable
+ref carries that revision, no sibling can ever produce it, so the finding is
+`unauthorized-revision` and blocks every mutation instead of
+`worktree-synchronization-required`, which blocks only its own item.
+
+Recording the field on publication entries is an additive optional journal
+change, so core `contract_version` stays `5` and every public request, success
+envelope, and refusal envelope is unchanged. The item #122 lock-coarsening
+parity golden, `test/publication-parity-baseline.json`, was regenerated to
+record it: that recording is a work-claim contract change, never routine
+fixture maintenance.
+
+**What that identity discloses.** The identity is an opaque random UUID,
+created once per worktree in that worktree's private Git directory. It contains
+no path, branch, ref, hostname, user, or machine data. Journal entries are
+projected into the tracked reconciliation log, so the identity persists in
+committed Git history: any reader of that history can correlate every entry
+written from one worktree, and an identity stays in that history indefinitely
+after the worktree it named is removed. It never becomes a claim owner, and no
+protocol decision reads it other than the writer comparison above.
+
+**Ambiguous identity.** A UUID names one worktree. Before it reasons from a
+recorded writer, the coordinator enumerates the worktrees Git currently reports
+live and reads the identity each one already holds; it creates none. Two live
+worktrees answering to one UUID, or a roster the coordinator could not finish
+reading, refuses `claim-verify`, every claim-protected mutation,
+`publish-claimed`, and `claim-adopt` before anything is classified or written.
+The refusal keeps the existing exit `6`, `claim-store-unavailable`,
+`claim-store-unreadable`, `state: "unchanged"` form and adds one
+`error.details.identity_diagnostic`: `code: "duplicate-worktree-identity"` with
+`worktree_id` and `live_worktree_count`, or `code:
+"worktree-enumeration-failed"` with no further member. Auto-commit surfaces the
+same diagnostic inside its `auto-commit-preflight-failed` details with
+`retryable: false`. Nothing else about the envelope changes, and core
+`contract_version` stays `5`.
+
+Detection covers only what Git reports live. A worktree Git marks prunable —
+including one whose path is temporarily unavailable or unmounted — is excluded,
+so a duplicate identity held there is not detected until Git sees that worktree
+live again. Removing a worktree removes the private Git directory that held its
+identity, and nothing restores it: a worktree recreated at the same path earns
+a new UUID, and the removed UUID stays in journal history attributing nothing.
+
 ### 3.2 Recovering from a foreign-writer block
 
 1. Stop writing the affected item in the blocked worktree. Unrelated item
@@ -452,10 +528,12 @@ answering with `namespace: "work-claim"`, `command: "claim-adopt"`, and
 mutation runs and no item file changes. It is not a `claim-verify` flag, because
 `claim-verify` is the read-mostly reconciliation report every remediation string
 names, and one command name must not mean both "tell me the state" and "change
-the authorization baseline". It is not a `claim` subcommand, because every claim
-lifecycle subcommand refuses with `publication-reconciliation-required` while
-reconciliation reports blocking findings, and adoption exists to clear exactly
-that state, so it runs while those findings stand.
+the authorization baseline". It is not a `claim` subcommand, because
+`work-claim.acquire` and `work-claim.renew` refuse with
+`publication-reconciliation-required` while reconciliation reports blocking
+findings, and adoption exists to clear exactly that state, so it runs while
+those findings stand. `work-claim.release` also runs while they stand, for the
+narrower reason that surrendering a lease takes no authority (section 5).
 
 The request is UTF-8 JSON with exactly these members:
 
@@ -602,6 +680,22 @@ member at any depth, and exactly the listed members. Unknown members, wrong
 types, noncanonical values, and unprovisioned namespaces are exit 2
 `invalid-request`; no authoritative lease decision has then occurred.
 
+**A reconciliation barrier stops a caller from taking or extending authority,
+never from surrendering it.** `work-claim.acquire` and `work-claim.renew` MUST
+refuse with exit 6 `claim-store-unavailable`, reason
+`publication-reconciliation-required`, and the reconciliation `findings`,
+whenever reconciliation reports a finding that blocks the request's item.
+`work-claim.release` MUST NOT refuse for that reason. The holder has to be able
+to hand the lease back: no other worktree can take the item over while the
+claim is held, and the worktree holding it is often the one least able to clear
+the barrier. Refusing the surrender strands the lease and the item with it.
+
+Release keeps every other refusal. An identity the domain cannot resolve, a
+journal it cannot read, and a clock floor it cannot persist all refuse before
+any lease decision, and the owner, epoch, and expected-expiry CAS tuple below
+still rules on the request: a mismatch is exit 4 `claim-conflict` and the claim
+stays held. A barrier never turns a release into an unconditional discard.
+
 ### Read
 
 `work-claim.read` accepts exactly:
@@ -673,6 +767,10 @@ It uses the same precedence. Success sets `active` to `null`, retains
 `last_epoch`, and returns `released_claim` plus `read_back`. A later acquire
 must allocate a greater epoch, preventing ABA even across restart.
 
+A reconciliation barrier does not refuse a release; it refuses only acquire and
+renew (section 5 preamble). The CAS tuple still applies, so a release under a
+barrier is exactly as conditional as a release without one.
+
 Success envelopes for these three commands have exactly `ok`, `namespace`,
 `command`, `contract_version`, `state: "committed"`, and `result`. Semantic
 failures replace `result` with `error`, use `state: "unchanged"`, and include

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wowbagger",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.13",
   "description": "Git-native work ledger for coding agents: deterministic ready queues, guarded CAS mutations, claims and fencing, and self-contained HTML reports.",
   "type": "module",
   "license": "MIT",

package/skills/wowbagger/SKILL.md

@@ -14,7 +14,7 @@ publish something.
 Install the core separately before using this skill:
 
 ```sh
-npm install -g wowbagger@0.1.0-alpha.12
+npm install -g wowbagger@0.1.0-alpha.13
 ```
 
 The core requires Node.js 20 or later. This plugin ships only agent
@@ -34,9 +34,9 @@ wowbagger capabilities --json
 
 Read the plain distribution version from the first command and the top-level
 `contract_version` from the second. **This skill requires distribution version
-`0.1.0-alpha.12` and core `contract_version: 5`.**
+`0.1.0-alpha.13` and core `contract_version: 5`.**
 
-The distribution pin names the published `0.1.0-alpha.12` release; the cut that
+The distribution pin names the published `0.1.0-alpha.13` release; the cut that
 publishes core `contract_version: 5` moves it. Earlier cores report
 `contract_version: 3` or lower and lack behavior this skill requires, including
 the bounded item source, so the version check refuses them. Do not soften

package/src/claim-coordinator.js

@@ -14,6 +14,11 @@ import { readBack } from './claim-operations.js';
 import { reconcileClaimJournal } from './claim-publication.js';
 import { claimStorePath, resolveVerifiedGitCommonDir, withClaimLock } from './claim-store.js';
 import { readNamespace } from './namespace.js';
+import {
+  assertUniqueWorktreeIdentity,
+  ensureWorktreeIdentity,
+  identityDiagnosticDetails,
+} from './worktree-identity.js';
 
 export async function withLegacyMutationFence(
   ledgerDirectory,
@@ -37,12 +42,22 @@ export async function withLegacyMutationFence(
   let intent = null;
   try {
     return await withClaimLock(storePath, async () => {
+      // The writer's own identity must exist before anything it does can be
+      // attributed, so it is established under the same lock that serializes
+      // the journal, ahead of reconciliation and of any intent append. Its own
+      // file is judged first, so bytes this worktree owns keep reporting as its
+      // own invalid identity rather than as an unreadable roster.
+      const currentWorktreeId = await ensureWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      // Then the domain: a UUID two live worktrees answer to attributes
+      // nothing, so nothing may be written from it.
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       const replayed = await replayClaimJournal(journalPath, namespace);
       const reconciled = await reconcileClaimJournal({
         ledgerDirectory,
         gitCommonDir,
         namespace,
         replayed,
+        currentWorktreeId,
         physicalNow: new Date().toISOString(),
         targetItemId: itemId,
         writeLogOnUnsafe: false,
@@ -76,6 +91,7 @@ export async function withLegacyMutationFence(
           expected_revision: expectedRevision,
           candidate_revision: candidateRevision,
           item_path: itemPath,
+          writer_worktree_id: currentWorktreeId,
           observed_at: observedAt,
         };
         const terminalEntry = {
@@ -86,6 +102,7 @@ export async function withLegacyMutationFence(
           command,
           committed_revision: candidateRevision,
           item_path: itemPath,
+          writer_worktree_id: currentWorktreeId,
           observed_at: observedAt,
         };
         const abortEntry = {
@@ -148,6 +165,7 @@ export async function withLegacyMutationFence(
             committed_revision: committedRevision,
             observed_at: observedAt,
             item_path: intent.item_path,
+            writer_worktree_id: currentWorktreeId,
           }));
         } catch {
           return claimStoreUnavailable(responseCommand, 'legacy-mutation-record-failed', {
@@ -192,7 +210,7 @@ export async function withLegacyMutationFence(
   } catch (error) {
     return claimStoreUnavailable(responseCommand, error?.code === 'CLAIM_LOCK_HELD'
       ? 'claim-store-locked'
-      : 'claim-store-unreadable', {}, intent ? 'unknown' : 'unchanged');
+      : 'claim-store-unreadable', identityDiagnosticDetails(error), intent ? 'unknown' : 'unchanged');
   }
 }
 

package/src/claim-journal.js

@@ -286,6 +286,8 @@ function validJournalEntry(entry, namespace) {
       && typeof entry.expected_revision === 'string'
       && typeof entry.candidate_revision === 'string'
       && (!Object.hasOwn(entry, 'item_path') || typeof entry.item_path === 'string')
+      && (!Object.hasOwn(entry, 'writer_worktree_id')
+        || typeof entry.writer_worktree_id === 'string')
       && typeof entry.observed_at === 'string';
   }
   if (entry.type === 'legacy-mutation') {
@@ -296,6 +298,8 @@ function validJournalEntry(entry, namespace) {
       && ['patch-v1', 'transition-v1'].includes(entry.command)
       && typeof entry.committed_revision === 'string'
       && (!Object.hasOwn(entry, 'item_path') || typeof entry.item_path === 'string')
+      && (!Object.hasOwn(entry, 'writer_worktree_id')
+        || typeof entry.writer_worktree_id === 'string')
       && typeof entry.observed_at === 'string';
   }
   if (entry.type === 'legacy-mutation-abort') {
@@ -325,6 +329,8 @@ function validJournalEntry(entry, namespace) {
       && typeof entry.expected_revision === 'string'
       && typeof entry.candidate_sha256 === 'string'
       && (!Object.hasOwn(entry, 'item_path') || typeof entry.item_path === 'string')
+      && (!Object.hasOwn(entry, 'writer_worktree_id')
+        || typeof entry.writer_worktree_id === 'string')
       && isRecord(entry.fence)
       && (namespace === null || entry.fence.ledger_namespace === namespace)
       && entry.fence.item_id === entry.item_id;
@@ -335,6 +341,8 @@ function validJournalEntry(entry, namespace) {
       && typeof entry.ledger_namespace === 'string'
       && (namespace === null || entry.ledger_namespace === namespace)
       && typeof entry.item_id === 'string'
+      && (!Object.hasOwn(entry, 'writer_worktree_id')
+        || typeof entry.writer_worktree_id === 'string')
       && validPublicationOutcome(entry);
   }
   return typeof entry.operation_id === 'string'

package/src/claim-publication.js

@@ -19,6 +19,12 @@ import { MAX_ITEM_SOURCE_BYTES } from './limits.js';
 import { findRevisionOwner, readGitHeadLedger, readGitTreeFile } from './git-reconciliation.js';
 import { publishClaimedCandidate, revisionFor } from './mutation.js';
 import { validateLedger } from './validate.js';
+import {
+  assertUniqueWorktreeIdentity,
+  ensureWorktreeIdentity,
+  identityDiagnosticDetails,
+  readWorktreeIdentity,
+} from './worktree-identity.js';
 
 const ITEM_ID = /^wb_[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
 const NAMESPACE_ID = /^wbns_[a-f0-9]{32}$/;
@@ -179,6 +185,15 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
       // file, so the first of them is the snapshot the rest share. The read
       // under lock, which the mutation engine still performs on its own, is
       // what makes the revision compare-and-swap meaningful.
+      //
+      // A claimed publication authorizes an item revision, so an ambiguous
+      // domain is refused before reconciliation classifies one. The writer
+      // names itself first, under this same hold, so a domain that cannot
+      // resolve its own identity refuses as its own invalid identity rather
+      // than as an unreadable roster — and so every entry this hold appends
+      // carries one ID resolved exactly once.
+      const currentWorktreeId = await ensureWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       let reconciled;
       try {
         reconciled = await reconcileClaimJournal({
@@ -188,6 +203,7 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
           replayed,
           physicalNow: new Date().toISOString(),
           targetItemId: request.item_id,
+          currentWorktreeId,
           writeLogOnUnsafe: false,
         });
       } catch (error) {
@@ -237,7 +253,7 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
             active_owner_id: record.active?.owner_id ?? null,
             active_epoch: record.active?.epoch ?? null,
           }, 4);
-        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath);
+        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath, currentWorktreeId);
       }
       await publicationTestCheckpoint(scenario, 'before-publish-intent', ledgerDirectory);
       const intent = await appendClaimEntry(journalPath, {
@@ -249,6 +265,7 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
         candidate_sha256: request.candidate_sha256,
         fence: request.claim_fence,
         floor: observedAt,
+        writer_worktree_id: currentWorktreeId,
         state: 'pending',
       });
       entries.push(intent);
@@ -258,11 +275,11 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
       });
       if (!mutation.ok) {
         const outcome = mutationFailure(request, mutation);
-        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath);
+        return persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath, currentWorktreeId);
       }
       await publicationTestCheckpoint(scenario, 'after-ledger-commit', ledgerDirectory);
       const outcome = publicationSuccess(request, record, observedAt, mutation.item?.path, namespace);
-      const terminal = await persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath);
+      const terminal = await persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, replayed.state, storePath, currentWorktreeId);
       await publicationTestCheckpoint(scenario, 'after-terminal-record', ledgerDirectory);
       return terminal;
     });
@@ -272,6 +289,15 @@ export async function publishClaimed({ ledgerDirectory, gitCommonDir, namespace,
         reason: 'claim-store-locked',
       }, 6);
     }
+    // An identity the coordination domain cannot resolve is a store this
+    // command could not read, not a mutation whose outcome is unknown: it
+    // refused before it appended an intent or touched an item byte.
+    if (error?.code === 'CLAIM_WORKTREE_IDENTITY_INVALID') {
+      return publicationError(request, 'claim-store-unavailable', 'The durable claim store is unavailable.', {
+        reason: 'claim-store-unreadable',
+        ...identityDiagnosticDetails(error),
+      }, 6);
+    }
     return publicationUnknown(request);
   }
 }
@@ -350,6 +376,10 @@ export async function reconcileClaimJournal({
   namespace,
   replayed,
   physicalNow,
+  // The worktree this invocation speaks for, when it has established an
+  // identity. A caller that cannot name itself passes null, and every
+  // recorded writer then reads as unknown.
+  currentWorktreeId = null,
   targetItemId = null,
   writeLogOnUnsafe = true,
   writeLogWhenEmpty = true,
@@ -407,6 +437,12 @@ export async function reconcileClaimJournal({
         command: intent.command,
         committed_revision: actualRevision,
         ...(intent.item_path ? { item_path: intent.item_path } : {}),
+        // The writer that authorized the attempt owns the revision this
+        // resolution ratifies, so its identity travels with the terminal
+        // entry. Absent on alpha.12 intents, which stay valid without it.
+        ...(intent.writer_worktree_id
+          ? { writer_worktree_id: intent.writer_worktree_id }
+          : {}),
         observed_at: observedAt,
       }));
     } else if (actualRevision === intent.expected_revision) {
@@ -496,6 +532,12 @@ export async function reconcileClaimJournal({
       operation_digest: intent.operation_digest,
       ledger_namespace: namespace,
       item_id: intent.item_id,
+      // The writer that authorized the publication owns the revision this
+      // resolution ratifies, so its identity travels with the terminal entry.
+      // Absent on alpha.12 intents, which stay valid without it.
+      ...(intent.writer_worktree_id
+        ? { writer_worktree_id: intent.writer_worktree_id }
+        : {}),
       outcome,
     }));
     const unknownPath = itemPathRelativeToLedger(ledgerDirectory, item?.file);
@@ -608,6 +650,13 @@ export async function reconcileClaimJournal({
       });
       continue;
     }
+    // Who the journal says wrote the authorized revision, judged against who
+    // is asking. An entry from before writer identity existed, or a caller
+    // that cannot name itself, leaves the writer unknown.
+    const recordedWriter = latestAuthorized.writer_worktree_id ?? null;
+    const expectedWriter = recordedWriter === null || currentWorktreeId === null
+      ? 'unknown'
+      : recordedWriter === currentWorktreeId ? 'current' : 'other';
     const diagnosis = await reconciliationDiagnosis({
       ledgerDirectory,
       actualRevision,
@@ -615,6 +664,7 @@ export async function reconcileClaimJournal({
       expectedPath,
       expectedRevision,
       headRevision,
+      expectedWriter,
       workingTreeChanged,
     });
     findings.push({
@@ -755,14 +805,26 @@ function blocksTarget(finding, targetItemId) {
 // Ownership is evidence, never a guess: an unreadable history or a missing
 // expected path leaves the revision unattributed instead of naming a ref.
 async function revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision) {
-  if (!expectedPath) return { owner_unavailable: true };
+  if (!expectedPath) return { kind: 'unreachable' };
   try {
     return await findRevisionOwner(ledgerDirectory, expectedPath, expectedRevision);
   } catch {
-    return { owner_unavailable: true };
+    return { kind: 'unreachable' };
   }
 }
 
+// One owner, one shape: only an active named worktree reaches this finding, and
+// the remediation names the same ref and commit the finding does.
+function namedOwnerFinding(owner, expectedPath) {
+  return {
+    reason: 'worktree-synchronization-required',
+    ...(expectedPath ? { expected_path: expectedPath } : {}),
+    owner_ref: owner.ref,
+    owner_commit: owner.commit,
+    remediation: `WAIT for owner ${owner.ref} to publish ${owner.commit}, then synchronize this worktree and run claim-verify.`,
+  };
+}
+
 async function reconciliationDiagnosis({
   ledgerDirectory,
   actualRevision,
@@ -770,6 +832,7 @@ async function reconciliationDiagnosis({
   expectedPath,
   expectedRevision,
   headRevision,
+  expectedWriter,
   workingTreeChanged,
 }) {
   const pathLabel = expectedPath ?? 'the item path';
@@ -791,15 +854,7 @@ async function reconciliationDiagnosis({
   if (headRevision !== null && actualRevision === headRevision
     && headRevision !== expectedRevision) {
     expectedOwner = await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision);
-    if (expectedOwner.owner_ref) {
-      return {
-        reason: 'worktree-synchronization-required',
-        ...(expectedPath ? { expected_path: expectedPath } : {}),
-        owner_ref: expectedOwner.owner_ref,
-        owner_commit: expectedOwner.owner_commit,
-        remediation: `WAIT for owner ${expectedOwner.owner_ref} to publish ${expectedOwner.owner_commit}, then synchronize this worktree and run claim-verify.`,
-      };
-    }
+    if (expectedOwner.kind === 'named-sibling') return namedOwnerFinding(expectedOwner, expectedPath);
   }
   if (!workingTreeChanged && headRevision !== expectedRevision) {
     return {
@@ -810,30 +865,23 @@ async function reconciliationDiagnosis({
   }
   if (actualRevision === null && headRevision !== expectedRevision) {
     const owner = await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision);
-    const publicOwner = owner.owner_ref
-      ? { owner_ref: owner.owner_ref, owner_commit: owner.owner_commit }
-      : { owner_unavailable: true };
+    if (owner.kind === 'named-sibling') return namedOwnerFinding(owner, expectedPath);
     return {
       reason: 'worktree-synchronization-required',
       ...(expectedPath ? { expected_path: expectedPath } : {}),
-      ...publicOwner,
-      remediation: owner.owner_ref
-        ? `WAIT for owner ${owner.owner_ref} to publish ${owner.owner_commit}, then synchronize this worktree and run claim-verify.`
-        : `Ownership of ${pathLabel} revision ${expectedRevision} cannot be established from reachable refs; inspect reachable or dangling commits, restore or explicitly adopt reviewed bytes, then run claim-verify.`,
+      owner_unavailable: true,
+      remediation: `Ownership of ${pathLabel} revision ${expectedRevision} cannot be established from reachable refs; inspect reachable or dangling commits, restore or explicitly adopt reviewed bytes, then run claim-verify.`,
     };
   }
   if (authorizedRevisions.has(actualRevision)) {
     expectedOwner ??= await revisionOwnerEvidence(ledgerDirectory, expectedPath, expectedRevision);
-    if (expectedOwner.owner_ref) {
-      return {
-        reason: 'worktree-synchronization-required',
-        ...(expectedPath ? { expected_path: expectedPath } : {}),
-        owner_ref: expectedOwner.owner_ref,
-        owner_commit: expectedOwner.owner_commit,
-        remediation: `WAIT for owner ${expectedOwner.owner_ref} to publish ${expectedOwner.owner_commit}, then synchronize this worktree and run claim-verify.`,
-      };
-    }
-    if (expectedOwner.owner_current_ref !== true) {
+    if (expectedOwner.kind === 'named-sibling') return namedOwnerFinding(expectedOwner, expectedPath);
+    // Advice to wait for an owning worktree needs an owner that could still
+    // appear. When the journal names this worktree as the writer of the
+    // expected revision and no active worktree carries it, the successor exists
+    // nowhere but in the journal: there is nothing to synchronize from, and the
+    // local bytes are simply unauthorized.
+    if (expectedWriter !== 'current' && expectedOwner.kind !== 'current') {
       return {
         reason: 'worktree-synchronization-required',
         ...(expectedPath ? { expected_path: expectedPath } : {}),
@@ -913,12 +961,22 @@ export async function verifyClaimJournal({
   const journalPath = claimJournalPath(gitCommonDir, namespace);
   try {
     return await withClaimLock(storePath, async () => {
+      // Verification writes no item byte and creates no identity: it reports on
+      // the worktree it runs in, and an unidentified worktree simply cannot
+      // recognize itself in a recorded writer. Its own file is judged first, so
+      // bytes this worktree owns keep reporting as its own invalid identity
+      // rather than as an unreadable roster.
+      const currentWorktreeId = await readWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      // Verification reasons from recorded writers, so it refuses an ambiguous
+      // domain before it classifies anything, exactly as a mutation does.
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       const reconciled = await reconcileClaimJournal({
         ledgerDirectory,
         gitCommonDir,
         namespace,
         replayed: await replayClaimJournal(journalPath, namespace),
         physicalNow: new Date().toISOString(),
+        currentWorktreeId,
         targetItemId,
         writeLogWhenEmpty,
         writeLogOnUnsafe,
@@ -957,6 +1015,7 @@ export async function verifyClaimJournal({
             reason: error?.code === 'CLAIM_LOCK_HELD'
               ? 'claim-store-locked'
               : 'claim-store-unreadable',
+            ...identityDiagnosticDetails(error),
           },
         },
       },
@@ -968,20 +1027,30 @@ export async function verifyClaimJournal({
 // re-baselines the coordinator's authorized revision onto bytes that are
 // already committed, and writes no item byte. It runs while reconciliation is
 // unsafe on purpose — clearing that state is the point — so it never refuses on
-// `publication-reconciliation-required` the way a claim lifecycle operation
-// does. Every precondition is checked under the claim lock against the state
-// reconciliation just observed.
+// `publication-reconciliation-required` the way `claim acquire` or
+// `claim renew` do. Every precondition is checked under the claim lock against
+// the state reconciliation just observed.
 export async function adoptItemRevision({ ledgerDirectory, gitCommonDir, namespace, request }) {
   const storePath = claimStorePath(gitCommonDir, namespace);
   const journalPath = claimJournalPath(gitCommonDir, namespace);
   try {
     return await withClaimLock(storePath, async () => {
+      // Adoption writes no item byte and creates no identity, so it names
+      // itself by reading the ID it already answers to. Its own file is judged
+      // first, so bytes this worktree owns keep reporting as its own invalid
+      // identity rather than as an unreadable roster, exactly as claim-verify
+      // reports them.
+      const currentWorktreeId = await readWorktreeIdentity({ ledgerDirectory, gitCommonDir });
+      // Adoption re-baselines an authorized revision, so it too refuses an
+      // ambiguous domain before reconciliation classifies one.
+      await assertUniqueWorktreeIdentity({ ledgerDirectory });
       const reconciled = await reconcileClaimJournal({
         ledgerDirectory,
         gitCommonDir,
         namespace,
         replayed: await replayClaimJournal(journalPath, namespace),
         physicalNow: new Date().toISOString(),
+        currentWorktreeId,
       });
       const refusal = adoptionRefusal(reconciled, ledgerDirectory, request);
       if (refusal) return refusal;
@@ -1050,6 +1119,7 @@ export async function adoptItemRevision({ ledgerDirectory, gitCommonDir, namespa
             reason: error?.code === 'CLAIM_LOCK_HELD'
               ? 'claim-store-locked'
               : 'claim-store-unreadable',
+            ...identityDiagnosticDetails(error),
           },
         },
       },
@@ -1156,13 +1226,14 @@ export function operationDigest(request) {
   return `sha256:${createHash('sha256').update(canonicalJson(request)).digest('hex')}`;
 }
 
-async function persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, state, storePath) {
+async function persistTerminal(entries, journalPath, ledgerDirectory, namespace, request, outcome, state, storePath, writerWorktreeId) {
   const terminal = await appendClaimEntry(journalPath, {
     type: 'publish-final',
     operation_id: request.operation_id,
     operation_digest: operationDigest(request),
     ledger_namespace: request.ledger_namespace,
     item_id: request.item_id,
+    writer_worktree_id: writerWorktreeId,
     outcome,
   });
   entries.push(terminal);

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

@@ -82,6 +82,7 @@ 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;
@@ -1659,6 +1660,21 @@ async function runClaimCommand(claimCommand, argumentsList) {
       } catch (error) {
         throw taggedFailure('CLAIM_STORE_UNREADABLE', error);
       }
+      // 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.
+      let currentWorktreeId;
+      try {
+        currentWorktreeId = await readWorktreeIdentity({
+          ledgerDirectory: parsedOptions.options.ledger,
+          gitCommonDir,
+        });
+      } catch (error) {
+        throw taggedFailure('CLAIM_STORE_UNREADABLE', error);
+      }
       const physicalNow = new Date().toISOString();
       let reconciled;
       try {
@@ -1669,6 +1685,7 @@ async function runClaimCommand(claimCommand, argumentsList) {
           replayed,
           physicalNow,
           targetItemId: request.item_id,
+          currentWorktreeId,
           writeLogOnUnsafe: false,
         });
       } catch (error) {
@@ -1679,7 +1696,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,
         });

package/src/git-autocommit.js

@@ -410,6 +410,12 @@ function claimVerificationFailureDetails(verified) {
   return {
     ...(error?.code ? { claim_verify_code: error.code } : {}),
     ...(error?.details?.reason ? { claim_verify_reason: error.details.reason } : {}),
+    // Why the claim store could not be read travels with the refusal: an
+    // operator told only that a store is unreadable cannot find the two
+    // worktrees answering to one identity.
+    ...(error?.details?.identity_diagnostic
+      ? { identity_diagnostic: error.details.identity_diagnostic }
+      : {}),
     ...(findings ? { findings } : {}),
   };
 }

package/src/git-reconciliation.js

@@ -2,6 +2,7 @@ import { execFile, spawn } from 'node:child_process';
 import { realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
+import { listWorktrees } from './git-worktrees.js';
 import { recordCount, timePhase } from './instrumentation.js';
 import { revisionFor } from './mutation.js';
 
@@ -63,48 +64,84 @@ export async function readGitTreeFile(ledgerDirectory, treeish, relativePath) {
   return gitBuffer(root, ['show', `${treeish}:${gitPath}`]);
 }
 
-// Which local ref carries the revision the journal expects. A finding may name
-// only ownership it can prove from reachable history, so a revision no ref
-// contains stays unattributed rather than guessed from the item path.
+// Which active worktree carries the revision the journal expects. Reachability
+// alone proves nothing about ownership: a tag, a remote-tracking ref, or a
+// branch nobody has checked out names no worktree that could publish anything.
+// So the evidence is the worktree roster, this worktree first, and a revision
+// reachable only outside it stays unowned rather than attributed to a ref.
+//
+// Returns `{ kind, ref?, commit? }`, where `kind` is one of:
+//   `current`           this worktree's own history reaches the revision;
+//   `named-sibling`     a live sibling worktree on a branch reaches it;
+//   `reachable-unowned` Git reaches it, but no live named worktree does;
+//   `unreachable`       no reachable commit carries the expected bytes.
 export async function findRevisionOwner(ledgerDirectory, itemPath, expectedRevision) {
   const { root, relativeLedger } = await resolveWorktreeLedger(ledgerDirectory);
   const gitPath = toGitPath(path.join(relativeLedger, itemPath));
-  let currentRef = null;
+  const carrierIn = revisionCarrier(root, gitPath, expectedRevision);
+  const current = await carrierIn(await pathHistory(root, 'HEAD', gitPath));
+  if (current) return { kind: 'current', commit: current };
+  const live = (await listWorktrees(root)).filter((record) => (
+    !record.bare && !record.prunable && record.head !== null
+  ));
+  // One expected revision can sit in several live worktrees at once. Branch ref
+  // then path is the only ordering both stable across runs and independent of
+  // the order Git happened to register the worktrees in.
+  for (const record of live.filter((entry) => entry.branch !== null).sort(byBranchThenPath)) {
+    const commit = await carrierIn(await pathHistory(root, record.head, gitPath));
+    if (commit) return { kind: 'named-sibling', ref: record.branch, commit };
+  }
+  // A detached worktree is a real writer with no ref to wait on, so it proves
+  // reachability and nothing else. So does any remaining ref: a tag, a
+  // remote-tracking ref, or a branch no worktree has checked out.
+  for (const record of live.filter((entry) => entry.branch === null)) {
+    const commit = await carrierIn(await pathHistory(root, record.head, gitPath));
+    if (commit) return { kind: 'reachable-unowned', commit };
+  }
+  const reachable = await carrierIn(await pathHistory(root, '--all', gitPath));
+  return reachable ? { kind: 'reachable-unowned', commit: reachable } : { kind: 'unreachable' };
+}
+
+// The first commit of a history whose item bytes are the expected revision, or
+// null. Sibling histories overlap almost entirely and every answer costs a
+// `git show`, so one commit is read at most once per lookup.
+function revisionCarrier(root, gitPath, expectedRevision) {
+  const answered = new Map();
+  return async (commits) => {
+    for (const commit of commits) {
+      if (!answered.has(commit)) {
+        answered.set(commit, await carriesRevision(root, commit, gitPath, expectedRevision));
+      }
+      if (answered.get(commit)) return commit;
+    }
+    return null;
+  };
+}
+
+async function carriesRevision(root, commit, gitPath, expectedRevision) {
   try {
-    currentRef = (await gitText(root, ['symbolic-ref', '-q', 'HEAD'])).trim() || null;
+    const bytes = await gitBuffer(root, ['show', `${commit}:${gitPath}`]);
+    return revisionFor(bytes) === expectedRevision;
   } catch {
-    // A detached HEAD has no current branch; its commit history is checked below.
+    // The path does not exist in this commit, so it cannot carry the revision.
+    return false;
   }
-  const detachedHeadCommits = new Set(currentRef === null
-    ? gitLines(await gitText(root, ['rev-list', 'HEAD', '--', gitPath]))
-    : []);
-  const allRefCommits = gitLines(await gitText(root, ['rev-list', '--all', '--', gitPath]));
-  const commits = [...new Set([...detachedHeadCommits, ...allRefCommits])];
-  for (const commit of commits) {
-    let bytes;
-    try {
-      bytes = await gitBuffer(root, ['show', `${commit}:${gitPath}`]);
-    } catch {
-      // The path does not exist in this commit, so it cannot carry the revision.
-      continue;
-    }
-    if (revisionFor(bytes) !== expectedRevision) continue;
-    if (detachedHeadCommits.has(commit)) {
-      return { owner_unavailable: true, owner_current_ref: true, owner_commit: commit };
-    }
-    const refs = gitLines(await gitText(root, [
-      'for-each-ref',
-      '--contains',
-      commit,
-      '--format=%(refname)',
-    ])).sort();
-    if (currentRef !== null && refs.includes(currentRef)) {
-      return { owner_unavailable: true, owner_current_ref: true, owner_commit: commit };
-    }
-    const [ownerRef] = refs;
-    return ownerRef ? { owner_ref: ownerRef, owner_commit: commit } : { owner_unavailable: true };
+}
+
+// The commits one revision range reaches that touch the item path, newest
+// first. An unborn `HEAD` names no commit, so a worktree Git cannot resolve
+// reaches nothing.
+async function pathHistory(root, revisionRange, gitPath) {
+  try {
+    return gitLines(await gitText(root, ['rev-list', revisionRange, '--', gitPath]));
+  } catch {
+    return [];
   }
-  return { owner_unavailable: true };
+}
+
+function byBranchThenPath(a, b) {
+  if (a.branch !== b.branch) return a.branch < b.branch ? -1 : 1;
+  return a.path < b.path ? -1 : 1;
 }
 
 async function gitText(cwd, argumentsList) {

package/src/git-worktrees.js

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+// Git answers `GIT_DIR` and its siblings before it answers `cwd`, so an
+// inherited value would report a repository the caller never named.
+const GIT_ENVIRONMENT = Object.fromEntries(
+  Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')),
+);
+
+// Every worktree of one repository owns a private Git directory: the common
+// directory itself for the main worktree, `<common>/worktrees/<name>` for a
+// linked one. Anything a single worktree must not share with its siblings
+// belongs there. Git resolves it; nothing here parses a `.git` file.
+export async function resolvePrivateGitDir(directory) {
+  const { stdout } = await execFileAsync('git', ['rev-parse', '--absolute-git-dir'], {
+    cwd: path.resolve(directory),
+    encoding: 'utf8',
+    env: GIT_ENVIRONMENT,
+    maxBuffer: 1024 * 1024,
+  });
+  return stdout.trim();
+}
+
+// The registered worktrees of one repository, as Git itself reports them.
+// `--porcelain -z` terminates every attribute with NUL and separates records
+// with one extra NUL, so a worktree path holding a newline still parses; the
+// newline-delimited spelling cannot promise that. Git emits `worktree <path>`
+// first, then `HEAD <oid>` and either `branch <ref>` or `detached`, plus the
+// bare, locked, and prunable markers where they apply. An attribute before the
+// first `worktree` line cannot exist, and one that does belongs to no record.
+export async function listWorktrees(directory) {
+  const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain', '-z'], {
+    cwd: path.resolve(directory),
+    encoding: 'utf8',
+    env: GIT_ENVIRONMENT,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  const worktrees = [];
+  let record = null;
+  for (const field of stdout.split('\0')) {
+    if (field === '') {
+      if (record) worktrees.push(record);
+      record = null;
+      continue;
+    }
+    const boundary = field.indexOf(' ');
+    const name = boundary === -1 ? field : field.slice(0, boundary);
+    const value = boundary === -1 ? '' : field.slice(boundary + 1);
+    if (name === 'worktree') {
+      record = {
+        path: value,
+        head: null,
+        branch: null,
+        detached: false,
+        bare: false,
+        locked: false,
+        prunable: false,
+      };
+      continue;
+    }
+    if (!record) continue;
+    if (name === 'HEAD') record.head = value;
+    else if (name === 'branch') record.branch = value;
+    else if (name === 'detached') record.detached = true;
+    else if (name === 'bare') record.bare = true;
+    else if (name === 'locked') record.locked = true;
+    else if (name === 'prunable') record.prunable = true;
+  }
+  if (record) worktrees.push(record);
+  return worktrees;
+}

package/src/instrumentation.js

@@ -16,6 +16,7 @@ const COUNTER_NAMES = [
   'item_lock_fsyncs',
   'item_lock_releases',
   'namespace_lock_acquisitions',
+  'worktree_identity_lock_acquisitions',
   'head_tree_entries',
   'head_blobs_read',
   'head_bytes_read',

package/src/worktree-identity.js

@@ -0,0 +1,165 @@
+import { randomUUID } from 'node:crypto';
+import { open, readFile, realpath, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { withClaimLock } from './claim-store.js';
+import { listWorktrees, resolvePrivateGitDir } from './git-worktrees.js';
+
+const IDENTITY_FILE = 'wowbagger-worktree-id';
+const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+function invalidIdentity(reason) {
+  const error = new Error('worktree identity is invalid');
+  error.code = 'CLAIM_WORKTREE_IDENTITY_INVALID';
+  error.reason = reason;
+  return error;
+}
+
+export async function readWorktreeIdentity({ ledgerDirectory, gitCommonDir }) {
+  return readIdentityFile(await resolveIdentityPath(ledgerDirectory, gitCommonDir));
+}
+
+// Two live worktrees answering to one UUID make every writer attribution in
+// the shared journal ambiguous, and an ambiguous writer is exactly what
+// reconciliation reasons from. The caller runs this before it classifies or
+// publishes anything, so an ambiguous domain refuses rather than guesses.
+//
+// Nothing here creates an identity file: a worktree that has never written one
+// stays anonymous and holds no UUID to collide with.
+export async function assertUniqueWorktreeIdentity({ ledgerDirectory }) {
+  const identities = await enumerateWorktreeIdentities(ledgerDirectory);
+  const holders = new Map();
+  for (const identity of identities) {
+    if (identity !== null) holders.set(identity, (holders.get(identity) ?? 0) + 1);
+  }
+  // Sorted so a domain holding more than one collision always names the same
+  // one, and the diagnostic an operator reads twice does not move.
+  const duplicate = [...holders]
+    .filter(([, count]) => count > 1)
+    .sort(([left], [right]) => (left < right ? -1 : 1))
+    .at(0);
+  if (!duplicate) return;
+  const error = invalidIdentity('duplicate-worktree-identity');
+  error.identityDiagnostic = {
+    code: 'duplicate-worktree-identity',
+    worktree_id: duplicate[0],
+    live_worktree_count: duplicate[1],
+  };
+  throw error;
+}
+
+// One entry per live registered worktree: its recorded UUID, or null when it
+// has never written one.
+//
+// Evidence gathering fails closed, because a roster this function could not
+// finish reading is not a roster without duplicates. An enumeration that never
+// ran, a private Git directory that will not resolve, a path that vanished
+// between the listing and the read, and identity bytes that are present but
+// malformed all leave the roster incomplete, so all of them refuse the caller
+// rather than shrink the evidence. Silently dropping any of them could hide
+// the very duplicate this check exists to find.
+//
+// Only what Git itself has already disowned is excluded: a record Git marks
+// prunable, and a bare repository, which has no checkout to hold an identity.
+async function enumerateWorktreeIdentities(ledgerDirectory) {
+  try {
+    const roster = await listWorktrees(ledgerDirectory);
+    return await Promise.all(roster
+      .filter((worktree) => !(worktree.bare || worktree.prunable))
+      .map(async (worktree) => readIdentityFile(path.join(
+        await resolvePrivateGitDir(worktree.path), IDENTITY_FILE,
+      ))));
+  } catch {
+    const error = invalidIdentity('worktree-enumeration-failed');
+    // The roster is unknown, so the diagnostic names no UUID and no count.
+    error.identityDiagnostic = { code: 'worktree-enumeration-failed' };
+    throw error;
+  }
+}
+
+// A duplicate refusal keeps its caller's existing outer code and reason, and
+// adds only this diagnostic to the details a client already tolerates extra
+// members in.
+export function identityDiagnosticDetails(error) {
+  return error?.identityDiagnostic ? { identity_diagnostic: error.identityDiagnostic } : {};
+}
+
+// The identity file is created once and never rewritten: a worktree that
+// already answers to an ID keeps it, because journal entries elsewhere already
+// name it.
+//
+// Read and create run under a lock keyed on the identity path, which is the
+// worktree itself. The namespace write lock cannot stand in for it: two ledger
+// namespaces can share one worktree, so they hold different namespace locks
+// while contending for one identity file. Without this lock both would observe
+// no identity, both would create one, and the later rename would leave the
+// earlier writer holding an ID the file no longer contains. The lock is a
+// try-lock, so a losing writer is refused with `CLAIM_LOCK_HELD` and retries
+// rather than publishing a second identity.
+//
+// Creation still writes a fresh file in the same directory, fsyncs it, and
+// renames it over the final path, so a reader taking no lock at all sees
+// either no file or one whole ID. The final path is never opened for writing,
+// so a crash can never leave a truncated identity behind.
+export async function ensureWorktreeIdentity({ ledgerDirectory, gitCommonDir }) {
+  const identityPath = await resolveIdentityPath(ledgerDirectory, gitCommonDir);
+  return withClaimLock(identityPath, async () => {
+    const existing = await readIdentityFile(identityPath);
+    if (existing !== null) return existing;
+
+    const temporaryPath = path.join(
+      path.dirname(identityPath),
+      `.${IDENTITY_FILE}.${randomUUID()}`,
+    );
+    try {
+      const handle = await open(temporaryPath, 'wx', 0o600);
+      try {
+        await handle.writeFile(`${randomUUID()}\n`, 'utf8');
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporaryPath, identityPath);
+    } finally {
+      await rm(temporaryPath, { force: true });
+    }
+
+    // Read back rather than trust the value just written: the caller must act
+    // on the ID the next reader will see, not the one this process intended.
+    const written = await readIdentityFile(identityPath);
+    if (written === null) throw invalidIdentity('missing-after-write');
+    return written;
+  }, { counter: 'worktree_identity_lock_acquisitions' });
+}
+
+// The verified common directory is the caller's proof of which repository it
+// is fencing. A private directory that is neither that directory nor one of
+// its linked worktrees belongs to some other repository, and an identity
+// written there would name the wrong writer.
+async function resolveIdentityPath(ledgerDirectory, gitCommonDir) {
+  const privateGitDir = await resolvePrivateGitDir(ledgerDirectory);
+  const [privateReal, commonReal] = await Promise.all([
+    realpath(privateGitDir),
+    realpath(gitCommonDir),
+  ]);
+  const linked = path.join(commonReal, 'worktrees');
+  if (privateReal !== commonReal && path.dirname(privateReal) !== linked) {
+    throw invalidIdentity('private-git-dir-outside-common-dir');
+  }
+  return path.join(privateGitDir, IDENTITY_FILE);
+}
+
+async function readIdentityFile(identityPath) {
+  let text;
+  try {
+    text = await readFile(identityPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!text.endsWith('\n')) throw invalidIdentity('missing-terminator');
+  const identity = text.slice(0, -1);
+  // The anchored pattern rejects a second line as well as a malformed one.
+  if (!UUID_V4.test(identity)) throw invalidIdentity('malformed-uuid');
+  return identity;
+}