fix(host-kit): a lock claim is identified by its token, not only by its process

Two records can name the same process and still be different acquisitions of the same
path, which is the distinction a release and a reclaim both need. Each acquisition
publishes a random claim token with its owner record: release matches the token rather
than pid and start time alone, and a reclaim compares the token of the record inside the
directory it moved with the one it judged before renaming.

The publication-ownership rule now says what it means for the process lock: its owner
record goes through the shared publication owner and it writes no file by hand, while its
renames are addressed only between the lock path and the reclaimed name. Reclaiming a
lock directory is a different claim of ownership from publishing a file into one.

Co-authored-by: Apex by Callstack <noreply@callstack.com>

Author: thymikee

packages/host-kit/src/internal/process-lock.test.ts

@@ -162,6 +162,44 @@ test('release leaves a lock whose record names a different process', async () =>
   assert.equal(fs.existsSync(ownerFilePath), true);
 });
 
+test('release leaves a lock that a new acquisition of the same process republished', async () => {
+  const lockDirPath = path.join(tmpDir, 'reacquired.lock');
+  const ownerFilePath = path.join(lockDirPath, 'owner.json');
+  const owner = currentProcessOwner();
+  const release = await acquireProcessLock({ lockDirPath, owner });
+
+  // Same pid, same start time: the only thing that can tell this record from ours is the
+  // claim written with it. Removing the directory would hand the new holder's lock away.
+  fs.writeFileSync(
+    ownerFilePath,
+    JSON.stringify({ ...owner, acquiredAtMs: Date.now(), claimToken: 'a-different-claim' }),
+  );
+  await release();
+
+  assert.equal(
+    (JSON.parse(fs.readFileSync(ownerFilePath, 'utf8')) as { claimToken: string }).claimToken,
+    'a-different-claim',
+  );
+});
+
+test('a reacquired lock publishes a claim that its predecessor cannot reuse', async () => {
+  const lockDirPath = path.join(tmpDir, 'claim-token.lock');
+  const ownerFilePath = path.join(lockDirPath, 'owner.json');
+  const first = await acquireProcessLock({ lockDirPath, owner: currentProcessOwner() });
+  const firstToken = (JSON.parse(fs.readFileSync(ownerFilePath, 'utf8')) as { claimToken: string })
+    .claimToken;
+  await first();
+
+  const second = await acquireProcessLock({ lockDirPath, owner: currentProcessOwner() });
+  const secondToken = (JSON.parse(fs.readFileSync(ownerFilePath, 'utf8')) as { claimToken: string })
+    .claimToken;
+  await second();
+
+  assert.equal(typeof firstToken, 'string');
+  assert.equal(typeof secondToken, 'string');
+  assert.notEqual(firstToken, secondToken);
+});
+
 test('acquireProcessLock does not evict a live owner whose owner.json is malformed', async () => {
   const lockDirPath = path.join(tmpDir, 'malformed.lock');
   fs.mkdirSync(lockDirPath);

packages/host-kit/src/internal/process-lock.ts

@@ -18,8 +18,17 @@ export type ProcessLockOwner = {
   acquiredAtMs: number;
 };
 
+/**
+ * One acquisition of a lock. The token says which: two records can name the same process
+ * and still be different claims on the same path, which is what a release and a reclaim
+ * have to tell apart.
+ */
+export type ProcessLockOwnerRecord = ProcessLockOwner & {
+  claimToken: string | null;
+};
+
 type ProcessLockOwnerReading =
-  | { kind: 'owner'; owner: ProcessLockOwner }
+  | { kind: 'owner'; owner: ProcessLockOwnerRecord }
   | { kind: 'unwritten' }
   | { kind: 'unreadable' };
 
@@ -39,15 +48,16 @@ export async function acquireProcessLock(params: {
   const description = params.description ?? 'process lock';
 
   fs.mkdirSync(path.dirname(lockDirPath), { recursive: true });
+  const claim: ProcessLockOwnerRecord = { ...owner, claimToken: crypto.randomUUID() };
 
   while (Date.now() < deadline) {
     try {
       fs.mkdirSync(lockDirPath);
-      writeProcessLockOwner(ownerFilePath, owner);
+      writeProcessLockOwner(ownerFilePath, claim);
       let released = false;
       return async () => {
         if (released) return;
-        const outcome = releaseProcessLock(lockDirPath, ownerFilePath, owner);
+        const outcome = releaseProcessLock(lockDirPath, ownerFilePath, claim);
         if (outcome !== 'unverified') {
           released = true;
           return;
@@ -84,7 +94,7 @@ function staleLockHint(lockDirPath: string): string {
   return `Remove ${lockDirPath} once you have confirmed no live process holds it, then retry.`;
 }
 
-function writeProcessLockOwner(ownerFilePath: string, owner: ProcessLockOwner): void {
+function writeProcessLockOwner(ownerFilePath: string, owner: ProcessLockOwnerRecord): void {
   publishFileSync({
     destination: ownerFilePath,
     contents: JSON.stringify(owner),
@@ -99,12 +109,15 @@ function writeProcessLockOwner(ownerFilePath: string, owner: ProcessLockOwner):
 function releaseProcessLock(
   lockDirPath: string,
   ownerFilePath: string,
-  owner: ProcessLockOwner,
+  claim: ProcessLockOwnerRecord,
 ): 'removed' | 'not-owner' | 'unverified' {
   const reading = readProcessLockOwner(ownerFilePath);
   if (reading.kind === 'unreadable') return 'unverified';
-  if (reading.kind === 'unwritten' || !ownerIdentityMatches(reading.owner, owner))
+  if (reading.kind === 'unwritten' || !ownerIdentityMatches(reading.owner, claim))
     return 'not-owner';
+  // The same process can hold this path twice in sequence, and a reclaim that moved our
+  // directory aside leaves a record behind that names us as though nothing had happened.
+  if (reading.owner.claimToken !== claim.claimToken) return 'not-owner';
   fs.rmSync(lockDirPath, { recursive: true, force: true });
   return 'removed';
 }
@@ -125,7 +138,10 @@ function clearStaleProcessLock(
   // owner record, so its age is the only evidence available about it.
   if (!lockStats.isDirectory()) {
     return reclaimWhenAbandoned(lockStats, ownerGraceMs)
-      ? reclaimProcessLockDirectory(lockDirPath, ownerFilePath, lockStats)
+      ? reclaimProcessLockDirectory(lockDirPath, ownerFilePath, {
+          stats: lockStats,
+          claimToken: null,
+        })
       : false;
   }
 
@@ -134,7 +150,10 @@ function clearStaleProcessLock(
     if (isLiveProcessLockOwner(reading.owner)) {
       return false;
     }
-    return reclaimProcessLockDirectory(lockDirPath, ownerFilePath, lockStats);
+    return reclaimProcessLockDirectory(lockDirPath, ownerFilePath, {
+      stats: lockStats,
+      claimToken: reading.owner.claimToken,
+    });
   }
   // A record we cannot read leaves an owner whose identity is unknown, which is not
   // evidence of death. Only a record that is genuinely absent lets the directory's
@@ -143,7 +162,10 @@ function clearStaleProcessLock(
     return false;
   }
   return reclaimWhenAbandoned(lockStats, ownerGraceMs)
-    ? reclaimProcessLockDirectory(lockDirPath, ownerFilePath, lockStats)
+    ? reclaimProcessLockDirectory(lockDirPath, ownerFilePath, {
+        stats: lockStats,
+        claimToken: null,
+      })
     : false;
 }
 
@@ -161,7 +183,7 @@ function reclaimWhenAbandoned(lockStats: fs.Stats, ownerGraceMs: number): boolea
 function reclaimProcessLockDirectory(
   lockDirPath: string,
   ownerFilePath: string,
-  judged: fs.Stats,
+  judged: JudgedLock,
 ): boolean {
   const asidePath = reclaimedLockPath(lockDirPath);
   try {
@@ -199,22 +221,28 @@ function reclaimWithoutTheRename(
 
 /**
  * A rename addresses whatever stands at the path now, not the directory whose record was
- * read. A contender that reclaimed first and published a live owner in the meantime has
- * put a different directory there, so what arrived is compared against what was judged:
- * the same inode, and no live owner inside.
+ * read. A contender that reclaimed first and claimed the path again has put a different
+ * directory there, so what arrived is compared against what was judged: the same inode,
+ * no live owner inside, and the claim token that was read before the rename.
  */
-function reclaimedLockIsTheOneJudged(asidePath: string, judged: fs.Stats): boolean {
+function reclaimedLockIsTheOneJudged(asidePath: string, judged: JudgedLock): boolean {
   let moved: fs.Stats;
   try {
     moved = fs.statSync(asidePath);
   } catch {
     return false;
   }
-  if (moved.ino !== judged.ino || moved.dev !== judged.dev) return false;
+  if (moved.ino !== judged.stats.ino || moved.dev !== judged.stats.dev) return false;
   const reading = readProcessLockOwner(path.join(asidePath, OWNER_FILE_NAME));
-  return !(reading.kind === 'owner' && isLiveProcessLockOwner(reading.owner));
+  if (reading.kind === 'owner' && isLiveProcessLockOwner(reading.owner)) return false;
+  return readClaimToken(reading) === judged.claimToken;
 }
 
+type JudgedLock = {
+  stats: fs.Stats;
+  claimToken: string | null;
+};
+
 /**
  * Returns a directory that turned out to belong to someone else. Failure is not a
  * licence to delete it: its holder's own release reports an unreadable owner rather than
@@ -259,7 +287,11 @@ function readProcessLockOwner(ownerFilePath: string): ProcessLockOwnerReading {
   return owner ? { kind: 'owner', owner } : { kind: 'unreadable' };
 }
 
-function parseProcessLockOwner(contents: string): ProcessLockOwner | null {
+function readClaimToken(reading: ProcessLockOwnerReading): string | null {
+  return reading.kind === 'owner' ? reading.owner.claimToken : null;
+}
+
+function parseProcessLockOwner(contents: string): ProcessLockOwnerRecord | null {
   let parsed: unknown;
   try {
     parsed = JSON.parse(contents);
@@ -275,6 +307,9 @@ function parseProcessLockOwner(contents: string): ProcessLockOwner | null {
     pid: record.pid as number,
     startTime: typeof record.startTime === 'string' ? record.startTime : null,
     acquiredAtMs: record.acquiredAtMs as number,
+    // A record written before claims were tokenized names a process without saying which
+    // acquisition it was, which no release can match and no reclaim can be blamed for.
+    claimToken: typeof record.claimToken === 'string' ? record.claimToken : null,
   };
 }
 

src/daemon/__tests__/atomic-publish-ownership.test.ts

@@ -11,9 +11,13 @@ const SIMPLE_PUBLISHERS = [
   new URL('../session-script-writer.ts', import.meta.url),
   new URL('../../../packages/platform-apple/src/runner/runner-lease.ts', import.meta.url),
   new URL('../../remote/remote-connection-state.ts', import.meta.url),
-  new URL('../../../packages/host-kit/src/internal/process-lock.ts', import.meta.url),
 ] as const;
 
+const PROCESS_LOCK_SOURCE = new URL(
+  '../../../packages/host-kit/src/internal/process-lock.ts',
+  import.meta.url,
+);
+
 test('simple same-directory publishers use the shared atomic publish owner', () => {
   for (const sourcePath of SIMPLE_PUBLISHERS) {
     const source = fs.readFileSync(sourcePath, 'utf8');
@@ -22,6 +26,20 @@ test('simple same-directory publishers use the shared atomic publish owner', ()
   }
 });
 
+// The process lock publishes a file and reclaims a directory, which are two different
+// claims of ownership: only the first belongs to the publication owners above.
+test('the process lock publishes its owner record without publishing files by hand', () => {
+  const source = fs.readFileSync(PROCESS_LOCK_SOURCE, 'utf8');
+  assert.match(source, /publishFileSync/);
+  assert.doesNotMatch(source, /fs\.writeFileSync\s*\(/);
+});
+
+test('the process lock renames only between the lock path and its reclaimed name', () => {
+  const source = fs.readFileSync(PROCESS_LOCK_SOURCE, 'utf8');
+  const renamed = [...source.matchAll(/fs\.renameSync\(([^)]*)\)/g)].map((match) => match[1]);
+  assert.deepEqual(renamed.sort(), ['asidePath, lockDirPath', 'lockDirPath, asidePath']);
+});
+
 test('durable publishers share the host-kit durable publication owner', () => {
   const sourcePaths = [
     new URL('../../../packages/capture-kit/src/durable-capture/store.ts', import.meta.url),