Unit ownership should use SQLite, not JSON file — read-modify-write race

[igouss]

Summary

unit-ownership.ts stores claims in .gsd/unit-claims.json via read-modify-write on a flat file. Everything else in the engine uses SQLite. The claim mechanism has a lost-update race that defeats its purpose under concurrent multi-agent use.

The Race

1. Agent A reads unit-claims.json — unit is unclaimed
2. Agent B reads unit-claims.json — unit is unclaimed
3. Agent A writes claim for itself — succeeds
4. Agent B writes claim for itself — succeeds, overwrites Agent A's claim

atomicWriteSync() prevents torn writes (the file is never half-written) but does not prevent lost updates. The read-modify-write cycle is not atomic.

Current Code

unit-ownership.ts:62-68 — claimUnit():

readClaims() → mutate in memory → atomicWriteSync()

The code comments document this as "last writer wins" — which acknowledges the race rather than fixing it.

Fix

Move claims into a SQLite table:

CREATE TABLE IF NOT EXISTS unit_claims (
  unit_key TEXT PRIMARY KEY,
  agent_name TEXT NOT NULL,
  claimed_at TEXT NOT NULL
);

Use INSERT OR IGNORE or INSERT ... WHERE NOT EXISTS for atomic claim acquisition. The SQLite single-writer lock provides the serialization that the JSON file cannot.

This also eliminates the inconsistency of having one piece of engine state in a different storage backend than everything else.

Files

• src/resources/extensions/gsd/unit-ownership.ts — lines 62-68

Confidence

81%

[igouss]

Investigation Results

Three Distinct Problems Found

The original issue (read-modify-write race) is real, but investigation uncovered two additional problems that compound it:

Problem 1: Read-Modify-Write Race (as reported)

Agent A: readClaims() → {T01: agent-a, T02: agent-b}
Agent B: readClaims() → {T01: agent-a, T02: agent-b}
Agent A: claims[T03] = agent-a → atomicWriteSync({T01:a, T02:b, T03:a})
Agent B: claims[T04] = agent-b → atomicWriteSync({T01:a, T02:b, T04:b})  ← T03 claim LOST

atomicWriteSync prevents torn writes (rename is atomic), but the read-modify-write cycle is not. Agent B's write stomps Agent A's T03 claim.

File: unit-ownership.ts:62-68

Problem 2: Ownership Check Outside Transaction (TOCTOU)

Both consumers run checkOwnership() before the transaction() block:

• complete-task.ts:142 — ownership check; txn starts at line 155
• complete-slice.ts:210 — ownership check; txn starts at line 223

An agent can pass the ownership check, then another agent claims the unit, then the first agent writes inside its transaction. The check and the guarded write are not atomic.

Problem 3: Nobody Actually Claims Units

claimUnit() is never called from any production code path. Only the test file exercises it. The checkOwnership() calls in complete-task and complete-slice check against a claims file that is never populated — making the entire ownership system a no-op in practice.

---

Recommended Fix: Move to SQLite

The DB already has schema v12 with established migration patterns, transaction() for atomic read-write cycles, WAL mode + busy timeout.

1. Schema v13 migration in gsd-db.ts

CREATE TABLE IF NOT EXISTS unit_claims (
  unit_key TEXT PRIMARY KEY,
  agent_name TEXT NOT NULL,
  claimed_at TEXT NOT NULL
);

2. Replace file ops with DB functions in unit-ownership.ts

// Atomic claim — only succeeds if unclaimed or already owned by same agent
function claimUnit(unitKey: string, agentName: string): boolean {
  return transaction(() => {
    const existing = getClaimRow(unitKey);
    if (existing && existing.agent_name !== agentName) return false;
    upsertClaim(unitKey, agentName);
    return true;
  });
}

// Now a DB read — can participate in the caller's transaction
function checkOwnership(unitKey: string, actorName?: string): string | null {
  if (!actorName) return null;
  const row = getClaimRow(unitKey);
  if (!row) return null;
  if (row.agent_name === actorName) return null;
  return `Unit ${unitKey} is owned by ${row.agent_name}, not ${actorName}`;
}

3. Move checkOwnership() inside transactions

In complete-task.ts and complete-slice.ts, move the ownership check inside the transaction() callback alongside the state machine guards.

4. Wire claimUnit() into dispatch/execution path

Without this, the ownership system remains a no-op regardless of storage backend.

5. Migration + cleanup

One-time migration: read existing .gsd/unit-claims.json (if present) → import into unit_claims table → file no longer needed.

---

Files Changed

File	Change
gsd-db.ts	Schema v13 migration + getClaimRow, upsertClaim, deleteClaim DB functions
unit-ownership.ts	Rewrite from file I/O to DB calls; claimUnit returns boolean (success/failure) instead of void
complete-task.ts	Move checkOwnership() inside transaction() callback
complete-slice.ts	Move checkOwnership() inside transaction() callback
unit-ownership.test.ts	Update tests to use test DB instead of temp directories

Public API surface (claimUnit, releaseUnit, getOwner, checkOwnership, taskUnitKey, sliceUnitKey) stays identical — only implementation changes.