@astrosheep/square 0.3.42 → 0.3.43

package/dist/file-lock.js

@@ -1,95 +1,25 @@
 import { DatabaseSync } from 'node:sqlite';
-import { randomUUID } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-function isBusy(error) {
-    return error instanceof Error && /database is locked|SQLITE_BUSY/i.test(error.message);
-}
-async function ownerState(lockPath) {
-    let pid;
-    try {
-        pid = Number.parseInt((await fs.readFile(lockPath, 'utf8')).split('\n')[0], 10);
-    }
-    catch {
-        return 'unknown';
-    }
-    if (!Number.isSafeInteger(pid) || pid <= 0)
-        return 'unknown';
-    try {
-        process.kill(pid, 0);
-        return 'alive';
-    }
-    catch (error) {
-        return error.code === 'ESRCH' ? 'dead' : 'alive';
-    }
-}
-async function createLegacyLock(lockPath) {
-    let fd;
-    try {
-        fd = await fs.open(lockPath, 'wx', 0o600);
-    }
-    catch (error) {
-        if (error.code === 'EEXIST')
-            return undefined;
-        throw error;
-    }
-    const token = `${process.pid}\n${Date.now()}\n${randomUUID()}\n`;
-    try {
-        await fd.writeFile(token, 'utf8');
-        return token;
-    }
-    catch (error) {
-        await fs.unlink(lockPath).catch(() => undefined);
-        throw error;
-    }
-    finally {
-        await fd.close();
+export class FileLockError extends Error {
+    code = 'not_a_database';
+    constructor(lockPath, cause) {
+        super(`File lock is not a database: ${lockPath}`);
+        this.name = 'FileLockError';
+        if (cause !== undefined)
+            this.cause = cause;
     }
 }
-async function reclaimLegacyLock(lockPath, staleMs) {
-    const quarantinePath = `${lockPath}.reclaim-${randomUUID()}`;
-    try {
-        const stale = Date.now() - (await fs.stat(lockPath)).mtimeMs > staleMs;
-        const owner = await ownerState(lockPath);
-        if (owner === 'alive' || (owner !== 'dead' && !stale))
-            return false;
-        await fs.rename(lockPath, quarantinePath);
-        await fs.unlink(quarantinePath).catch(() => undefined);
-        return true;
-    }
-    catch (error) {
-        await fs.unlink(quarantinePath).catch(() => undefined);
-        return error.code === 'ENOENT';
-    }
+function isBusy(error) {
+    return error instanceof Error && /database is locked|SQLITE_BUSY/i.test(error.message);
 }
-async function releaseLegacyLock(lockPath, token) {
-    try {
-        if (await fs.readFile(lockPath, 'utf8') === token)
-            await fs.unlink(lockPath);
-    }
-    catch { }
+function isNotADatabase(error) {
+    return error instanceof Error && /not a database|file is not a database/i.test(error.message);
 }
-async function withLegacyFileLock(lockPath, options, fn) {
-    let token;
-    while (token === undefined) {
-        if (options.signal?.aborted)
-            throw options.signal.reason ?? new Error('File lock acquisition aborted');
-        token = await createLegacyLock(lockPath);
-        if (token !== undefined)
-            break;
-        if (await reclaimLegacyLock(lockPath, options.staleMs))
-            continue;
-        await sleep(options.retryMs, undefined, { signal: options.signal });
-    }
-    try {
-        return await fn();
-    }
-    finally {
-        await releaseLegacyLock(lockPath, token);
-    }
-}
-async function withSqliteLock(lockPath, options, fn) {
+export async function withFileLock(lockPath, options, fn) {
+    if (options.createParent !== false)
+        await fs.mkdir(path.dirname(lockPath), { recursive: true });
     while (true) {
         if (options.signal?.aborted)
             throw options.signal.reason ?? new Error('File lock acquisition aborted');
@@ -109,9 +39,8 @@ async function withSqliteLock(lockPath, options, fn) {
                 await sleep(options.retryMs, undefined, { signal: options.signal });
                 continue;
             }
-            if (error instanceof Error && /not a database|file is not a database/i.test(error.message)) {
-                return withLegacyFileLock(lockPath, options, fn);
-            }
+            if (isNotADatabase(error))
+                throw new FileLockError(lockPath, error);
             throw error;
         }
         try {
@@ -131,7 +60,3 @@ async function withSqliteLock(lockPath, options, fn) {
         }
     }
 }
-export async function withFileLock(lockPath, options, fn) {
-    await fs.mkdir(path.dirname(lockPath), { recursive: true });
-    return withSqliteLock(lockPath, options, fn);
-}

package/dist/host-ledger-file-adapter.d.ts

@@ -24,10 +24,14 @@ export declare class FileHostLedgerPort implements HostLedgerPort {
     transitionWakeDispatch(i: WakeDispatchTransitionInput): Promise<boolean>;
     releaseWakeDispatch(i: WakeDispatchReleaseInput): Promise<void>;
     listWakeAttempts(i?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
-    appendWakeAttempt(i: EvidenceRecord): Promise<void>;
+    appendWakeAttempt(i: EvidenceRecord & {
+        readonly claimToken: string;
+    }): Promise<void>;
     claimEvidence(i: EvidenceClaim): Promise<ClaimResult>;
     releaseEvidence(i: EvidenceRelease): Promise<void>;
-    appendEvidence(i: EvidenceRecord): Promise<void>;
+    appendEvidence(i: EvidenceRecord & {
+        readonly claimToken: string;
+    }): Promise<void>;
     listEvidence(i?: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
     gcEvidence(i: EvidenceGc): Promise<void>;
     reconcileBinding(i?: ReconcileBindingInput): Promise<ReconcileBindingResult>;

package/dist/host-ledger-file-adapter.js

@@ -1,10 +1,11 @@
 import { promises as fs } from 'node:fs';
+import fsSync from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { withFileLock } from './file-lock.js';
 import { nameKey } from './model.js';
 import { isCurrentlyJoined } from './runtime.js';
-const LOCK = { retryMs: 10, staleMs: 300000 };
+const LOCK = { retryMs: 10 };
 const RETENTION = 7 * 86400000;
 async function canon(value) { const absolute = path.resolve(value); try {
     return await fs.realpath(absolute);
@@ -12,11 +13,26 @@ async function canon(value) { const absolute = path.resolve(value); try {
 catch {
     return absolute;
 } }
+function canonRoot(value) { let current = path.resolve(value), suffix = []; for (;;) {
+    try {
+        return path.join(fsSync.realpathSync.native(current), ...suffix.reverse());
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            return path.resolve(value);
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(value);
+        suffix.push(path.basename(current));
+        current = parent;
+    }
+} }
 async function read(file, now, includeFuture = false) { try {
     return (await fs.readFile(file, 'utf8')).split('\n').flatMap(line => { try {
         const row = JSON.parse(line);
         const at = row.at ?? row.updatedAt;
-        return row.v === 1 && typeof at === 'number' && at >= now - RETENTION && (includeFuture || at <= now) ? [row] : [];
+        const durableTerminal = row.kind === 'wake' && row.outcome === 'accepted';
+        return row.v === 1 && typeof at === 'number' && (durableTerminal || at >= now - RETENTION) && (includeFuture || at <= now) ? [row] : [];
     }
     catch {
         return [];
@@ -28,7 +44,7 @@ catch (e) {
     throw e;
 } }
 async function write(file, rows) { await fs.mkdir(path.dirname(file), { recursive: true }); const tmp = `${file}.${process.pid}.${Date.now()}.tmp`; await fs.writeFile(tmp, rows.length ? rows.map(row => JSON.stringify(row)).join('\n') + '\n' : '', { mode: 0o600 }); await fs.rename(tmp, file); }
-function k(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind]); }
+function k(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind, v.scope ?? null]); }
 function evidenceKey(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.activity, v.kind, v.attemptN ?? null]); }
 async function readClaims(file, now) { try {
     return (await fs.readFile(file, 'utf8')).split('\n').flatMap(line => { try {
@@ -60,12 +76,12 @@ export class FileHostLedgerPort {
     readable;
     claims;
     clock;
-    constructor(o = {}) { const testRoot = process.env.SQUARE_REGISTRY ? path.dirname(process.env.SQUARE_REGISTRY) : undefined; this.user = o.userPath ?? (testRoot ?? path.join(os.homedir(), '.square', 'host-ledger')); this.local = o.localPath ?? (testRoot ?? path.join(process.cwd(), '.square', 'host-ledger')); this.writable = o.writableScope ?? 'local'; this.readable = o.readableScopes ?? ['user', 'local']; this.claims = o.claimsPath ?? path.join(this.user, 'wake-claims.ndjsonl'); this.clock = o.now ?? Date.now; }
+    constructor(o = {}) { const testRoot = process.env.SQUARE_REGISTRY ? path.dirname(process.env.SQUARE_REGISTRY) : undefined; this.user = canonRoot(o.userPath ?? (testRoot ?? path.join(os.homedir(), '.square', 'host-ledger'))); this.local = canonRoot(o.localPath ?? (testRoot ?? path.join(process.cwd(), '.square', 'host-ledger'))); this.writable = o.writableScope ?? 'local'; this.readable = o.readableScopes ?? ['user', 'local']; this.claims = canonRoot(o.claimsPath ?? path.join(this.user, 'wake-claims.ndjsonl')); this.clock = o.now ?? Date.now; }
     file(s, f) { return path.join(s === 'user' ? this.user : this.local, `${f}.ndjsonl`); }
-    async claimPresence(i, scope = this.writable) { const location = await canon(i.location), r = { ...i, location, ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }, lock = path.join(this.user, 'presence-claim.lock'); try {
+    async claimPresence(i, scope = this.writable) { const location = await canon(i.location), r = { ...i, location, scope, ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }, lock = path.join(this.user, 'presence-claim.lock'); try {
         return await withFileLock(lock, LOCK, async () => { const candidates = []; for (const s of ['user', 'local']) {
             for (const row of await read(this.file(s, 'presence'), this.clock(), true)) {
-                if (row.location !== location || nameKey(row.participant) !== nameKey(r.participant))
+                if ((row.scope ?? s) !== s || row.location !== location || nameKey(row.participant) !== nameKey(r.participant))
                     continue;
                 candidates.push(s === 'user' ? row : { ...row, route: undefined });
             }
@@ -73,37 +89,37 @@ export class FileHostLedgerPort {
             if (existing.session === r.session)
                 return { status: 'owned', record: existing };
             return { status: 'busy', record: existing };
-        } const f = this.file(scope, 'presence'); await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k(x) !== k(r)), r])); return { status: 'acquired', record: r }; });
+        } const f = this.file(scope, 'presence'); await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k({ ...x, scope: x.scope ?? scope }) !== k(r)), r])); return { status: 'acquired', record: r }; });
     }
     catch (error) {
         return { status: 'degraded', record: r, error };
     } }
-    async ensurePresence(i, scope = this.writable) { const r = { ...i, location: await canon(i.location), ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }; const f = this.file(scope, 'presence'); try {
-        await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k(x) !== k(r)), r]));
+    async ensurePresence(i, scope = this.writable) { const r = { ...i, location: await canon(i.location), scope, ...(scope === 'local' ? { route: undefined } : {}), updatedAt: i.updatedAt ?? this.clock(), v: 1 }; const f = this.file(scope, 'presence'); try {
+        await withFileLock(f + '.lock', LOCK, async () => write(f, [...(await read(f, this.clock(), true)).filter(x => k({ ...x, scope: x.scope ?? scope }) !== k(r)), r]));
         return { status: 'ensured', record: r };
     }
     catch (error) {
         return { status: 'degraded', record: r, error };
     } }
-    async removePresence(i) { const r = { ...i, location: await canon(i.location) }, f = this.file(this.writable, 'presence'); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(x => k(x) !== k(r)))); }
+    async removePresence(i) { const r = { ...i, location: await canon(i.location), scope: this.writable }, f = this.file(this.writable, 'presence'), shared = this.user === this.local; await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(x => { const rowScope = x.scope ?? this.writable; return shared ? k({ ...x, scope: rowScope }) !== k({ ...r, scope: rowScope }) : k({ ...x, scope: rowScope }) !== k(r); }))); }
     async listPresence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location), m = new Map(); for (const s of i.scopes ?? this.readable)
         for (const r of await read(this.file(s, 'presence'), i.now ?? this.clock())) {
-            if (loc && r.location !== loc || i.participant && nameKey(r.participant) !== nameKey(i.participant) || i.session && r.session !== i.session)
+            if ((r.scope ?? s) !== s || loc && r.location !== loc || i.participant && nameKey(r.participant) !== nameKey(i.participant) || i.session && r.session !== i.session)
                 continue;
-            const x = s === 'user' ? r : { ...r, route: undefined }, key = k(x), old = m.get(key);
+            const x = s === 'user' ? r : { ...r, route: undefined }, key = k({ ...x, scope: undefined }), old = m.get(key);
             if (old?.scope === 'user' && s === 'local')
                 continue;
             if (!old || s === 'user' || x.updatedAt >= old.record.updatedAt)
                 m.set(key, { record: x, scope: s });
-        } return [...m.values()].map(({ record }) => record); }
-    async claimWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, i.session ?? null, 'wake']), at = i.at ?? this.clock(); return withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at), existing = rows.find((row) => row.attention_key === key); if (existing?.phase === 'dispatching') {
+        } return [...m.values()].map(({ record }) => { const { scope: _scope, ...publicRecord } = record; return publicRecord; }); }
+    async claimWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, 'wake']), at = i.at ?? this.clock(); return withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at), existing = rows.find((row) => row.attention_key === key); if (existing?.phase === 'dispatching') {
         const alive = processAlive(existing.ownerPid);
         if (existing.expiresAt <= at || alive === false)
             return { type: 'ambiguous', lease: existing };
         return { type: 'busy' };
     } if (existing !== undefined && existing.expiresAt > at)
         return { type: 'busy' }; const next = { v: 1, ts: at, attention_key: key, leaseId: i.leaseId, expiresAt: at + i.leaseMs, phase: 'claimed', ownerPid: process.pid, ...(i.session === undefined ? {} : { session: i.session }) }; await writeClaims(this.claims, [...rows.filter((row) => row.attention_key !== key), next]); return { type: 'acquired', leaseId: i.leaseId }; }); }
-    async transitionWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, i.session ?? null, 'wake']), at = i.at ?? this.clock(); return withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at), current = rows.find((row) => { if (row.leaseId !== i.leaseId)
+    async transitionWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, 'wake']), at = i.at ?? this.clock(); return withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at), current = rows.find((row) => { if (row.leaseId !== i.leaseId)
         return false; try {
         const parts = JSON.parse(row.attention_key);
         return parts[0] === location && parts[1] === nameKey(i.attention.recipient) && parts[2] === i.attention.actIndex;
@@ -112,22 +128,25 @@ export class FileHostLedgerPort {
         return false;
     } }); if (current === undefined)
         return false; const next = { v: 1, ts: at, attention_key: key, leaseId: i.leaseId, expiresAt: at + i.leaseMs, phase: i.phase, ownerPid: current.ownerPid, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.session === undefined ? {} : { session: i.session }) }; await writeClaims(this.claims, [...rows.filter((row) => row !== current), next]); return true; }); }
-    async releaseWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, i.session ?? null, 'wake']), at = i.at ?? this.clock(); await withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at); await writeClaims(this.claims, rows.filter((row) => row.attention_key !== key || row.leaseId !== i.leaseId)); }); }
+    async releaseWakeDispatch(i) { const location = await canon(i.attention.squarePath), key = JSON.stringify([location, nameKey(i.attention.recipient), i.attention.actIndex, 'wake']), at = i.at ?? this.clock(); await withFileLock(`${this.claims}.lock`, LOCK, async () => { const rows = await readClaims(this.claims, at); await writeClaims(this.claims, rows.filter((row) => row.attention_key !== key || row.leaseId !== i.leaseId)); }); }
     async listWakeAttempts(i = {}) { const attention = i.attention; return this.listEvidence({ kind: 'wake', ...(attention === undefined ? {} : { location: await canon(attention.squarePath), participant: attention.recipient, activity: `act/${attention.actIndex}` }), ...(i.session === undefined ? {} : { session: i.session }), now: i.now }); }
     async appendWakeAttempt(i) { if (i.kind !== 'wake')
-        throw new Error('Wake attempt rows require wake evidence kind'); return this.appendEvidence(i); }
-    async claimEvidence(i) { const f = this.file('user', 'evidence'), at = i.now ?? this.clock(), { leaseMs, ...claim } = i, r = { ...claim, location: await canon(i.location), outcome: 'dispatching', at, expiresAt: at + leaseMs, v: 1 }; try {
+        throw new Error('Wake attempt rows require wake evidence kind'); await this.appendEvidence(i); }
+    async claimEvidence(i) { const f = this.file('user', 'evidence'), at = i.now ?? this.clock(), { leaseMs, claimToken: requestedToken, ...claim } = i, r = { ...claim, location: await canon(i.location), outcome: 'dispatching', at, expiresAt: at + leaseMs, v: 1 }; try {
         return await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), matching = all.filter(x => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session), old = matching.findLast(x => x.outcome === 'dispatching'); if (old !== undefined && typeof old.expiresAt === 'number' && old.expiresAt > at)
             return { status: 'busy', record: old }; const delivered = (r.kind === 'wake' && matching.some(x => x.outcome === 'accepted')) || (r.kind === 'presentation' && matching.some(x => x.outcome === 'presented')); if (delivered)
-            return { status: 'delivered', record: matching.findLast(x => x.outcome === 'accepted' || x.outcome === 'presented') }; await write(f, [...all.filter(x => !(x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session && x.outcome === 'dispatching')), r]); return { status: 'acquired' }; });
+            return { status: 'delivered', record: matching.findLast(x => x.outcome === 'accepted' || x.outcome === 'presented') }; const index = Number(r.activity.slice(4)), attentionKey = JSON.stringify([r.location, nameKey(r.participant), index, r.session ?? null, 'wake']), dispatchToken = r.kind === 'wake' && typeof requestedToken === 'string' && Number.isInteger(index) && (await readClaims(this.claims, at)).some((row) => row.leaseId === requestedToken && row.attention_key === attentionKey) ? requestedToken : undefined, claimToken = dispatchToken ?? `${process.pid}-${at}-${Math.random().toString(36).slice(2)}`, row = { ...r, claimToken }; await write(f, [...all.filter(x => !(x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session && (x.outcome === 'dispatching' || x.outcome === 'released'))), row]); return { status: 'acquired', claimToken }; });
     }
     catch (error) {
         return { status: 'degraded', error };
     } }
-    async releaseEvidence(i) { const f = this.file('user', 'evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, at, true)).filter(x => !(x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session && x.outcome === 'dispatching')))); }
-    async appendEvidence(i) { const f = this.file('user', 'evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, r.at, true); const base = all.filter(x => k(x) === k(r)); const replaceable = new Set(base.filter(x => x.outcome === 'dispatching' || (r.attemptN !== undefined && x.attemptN === r.attemptN)).map(x => evidenceKey(x))); await write(f, [...all.filter(x => !(x.outcome === 'dispatching' && k(x) === k(r)) && !replaceable.has(evidenceKey(x))), r]); }); }
-    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('user', 'evidence'), i.now ?? this.clock())).filter(r => (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
-    async gcEvidence(i) { const f = this.file('user', 'evidence'); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock())).filter(r => r.at >= i.before))); }
+    async releaseEvidence(i) { const f = this.file('user', 'evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), same = (x) => x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session, current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== i.claimToken)
+        return; const tombstone = { ...current, outcome: 'released', at, expiresAt: undefined }; delete tombstone.expiresAt; await write(f, [...all.filter(x => x !== current), tombstone]); }); }
+    async appendEvidence(i) { const f = this.file('user', 'evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; const token = i.claimToken; if (typeof token !== 'string' || token.length === 0)
+        return; await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, r.at, true); const same = (x) => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session; const current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== token)
+        return; const terminalKey = (x) => same(x) && x.attemptN === r.attemptN && x.outcome !== 'dispatching' && x.outcome !== 'released'; await write(f, [...all.filter(x => x !== current && !terminalKey(x)), r]); }); }
+    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('user', 'evidence'), i.now ?? this.clock())).filter(r => r.outcome !== 'released' && (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
+    async gcEvidence(i) { const f = this.file('user', 'evidence'), pending = new Set(i.pendingWakeActivities ?? []); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(r => r.at >= i.before || r.kind === 'wake' && r.outcome === 'accepted' && pending.has(r.activity)))); }
     async reconcileBinding(i = {}) { let b = []; try {
         b = [...await this.listPresence({ scopes: i.scopes, now: i.now })];
         if (i.artifact) {

package/dist/host-ledger.d.ts

@@ -53,6 +53,7 @@ export interface EvidenceRecord {
     readonly attemptN?: number;
     readonly message?: string;
     readonly diagnostic?: unknown;
+    readonly claimToken?: string;
 }
 export interface EvidenceClaim {
     readonly location: string;
@@ -61,9 +62,12 @@ export interface EvidenceClaim {
     readonly activity: string;
     readonly kind: EvidenceRecord['kind'];
     readonly leaseMs: number;
+    readonly claimToken?: string;
     readonly now?: number;
 }
-export type EvidenceRelease = Omit<EvidenceClaim, 'leaseMs'>;
+export type EvidenceRelease = Omit<EvidenceClaim, 'leaseMs'> & {
+    readonly claimToken: string;
+};
 export interface EvidenceLookup {
     readonly location?: string;
     readonly participant?: string;
@@ -74,6 +78,7 @@ export interface EvidenceLookup {
 }
 export interface EvidenceGc {
     readonly before: number;
+    readonly pendingWakeActivities?: readonly string[];
 }
 export interface WakeAttention {
     readonly squarePath: string;
@@ -127,6 +132,7 @@ export interface WakeAttemptLookup {
 }
 export type ClaimResult = {
     readonly status: 'acquired';
+    readonly claimToken: string;
 } | {
     readonly status: 'busy' | 'delivered';
     readonly record: EvidenceRecord;
@@ -160,10 +166,14 @@ export interface HostLedgerPort {
     listPresence(input: PresenceLookup): Promise<readonly PresenceRecord[]>;
     claimEvidence(input: EvidenceClaim): Promise<ClaimResult>;
     releaseEvidence(input: EvidenceRelease): Promise<void>;
-    appendEvidence(input: EvidenceRecord): Promise<void>;
+    appendEvidence(input: EvidenceRecord & {
+        readonly claimToken: string;
+    }): Promise<void>;
     listEvidence(input: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
     listWakeAttempts(input?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
-    appendWakeAttempt(input: EvidenceRecord): Promise<void>;
+    appendWakeAttempt(input: EvidenceRecord & {
+        readonly claimToken: string;
+    }): Promise<void>;
     claimWakeDispatch(input: WakeDispatchClaimInput): Promise<WakeDispatchClaim>;
     transitionWakeDispatch(input: WakeDispatchTransitionInput): Promise<boolean>;
     releaseWakeDispatch(input: WakeDispatchReleaseInput): Promise<void>;

package/dist/notifications.js

@@ -9,7 +9,8 @@ import { displayAttentionPath } from './attention-presentation.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { notificationDelivered, resolveParticipant } from './views.js';
-import { deliverPending, sweepPending, sweepPendingFromState } from './delivery-operations.js';
+import { deliverPending, observeSquare, sweepPending, sweepPendingFromState } from './delivery-operations.js';
+import { nameKey } from './model.js';
 import { projectPresentationEvidence } from './square-projections.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 export { planActNotifications, matchesMentionTarget };
@@ -101,6 +102,34 @@ export async function createDefaultWakeTransport(hostLedger, clock, env = proces
     const adapters = await defaultWakeAdapters();
     return createWakeTransport(env.SQUARE_DISABLE_PASEO_WAKE === '1' ? adapters.filter((adapter) => adapter.kind !== 'paseo') : adapters, hostLedger, clock);
 }
+async function wakeRequestIsCurrent(request, hostLedger, now) {
+    const activity = parseActivityId(request.activity);
+    if (activity === undefined)
+        return false;
+    let square;
+    try {
+        square = await openSquare(request.location, { hostLedger });
+        const current = await observeSquare({ artifact: square.artifact, hostLedger, location: request.location, now });
+        const pending = current.pending.some((entry) => nameKey(entry.recipient) === nameKey(request.participant)
+            && entry.notifications.some((notification) => notification.item.index === activity));
+        const bound = current.bindings.some((binding) => nameKey(binding.participant) === nameKey(request.route.participant)
+            && binding.sessionId === request.route.sessionId
+            && binding.location === request.route.location);
+        const published = (current.state.routes ?? []).some((route) => route.location === request.route.location
+            && nameKey(route.participant) === nameKey(request.route.participant)
+            && route.sessionId === request.route.sessionId
+            && route.kind === request.route.kind
+            && JSON.stringify(route.address) === JSON.stringify(request.route.address));
+        return pending && bound && published;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (square !== undefined)
+            await closeOpenSquare(square);
+    }
+}
 export function createWakeTransport(adapters, hostLedger, clock) {
     return {
         probe: async (route) => {
@@ -117,12 +146,12 @@ export function createWakeTransport(adapters, hostLedger, clock) {
                 return { outcome: 'not-capable', diagnostic: error instanceof Error ? error.message : String(error) };
             }
         },
-        attempt: async (request, timeoutMs) => {
+        attempt: async (request, timeoutMs, beforeSend) => {
             const adapter = adapters.find((candidate) => candidate.kind === request.route.kind);
             if (adapter === undefined)
                 return { outcome: 'not-capable', diagnostic: `no adapter for ${request.route.kind}` };
             try {
-                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => true, timeoutMs);
+                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => (await (beforeSend ?? (async () => true))()) && await wakeRequestIsCurrent(request, hostLedger, clock()), timeoutMs);
                 if (result.outcome === 'accepted')
                     return { outcome: 'accepted' };
                 if (result.outcome === 'failed')

package/dist/participant-identity.js

@@ -7,7 +7,7 @@ const nativeSessions = [
     { variable: 'CLAUDE_CODE_SESSION_ID', provider: 'claude' },
     { variable: 'CODEX_THREAD_ID', provider: 'codex' },
     { variable: 'OPENCODE_SESSION_ID', provider: 'opencode' },
-    { variable: 'PI_SESSION_ID', provider: 'pi' },
+    { variable: 'SQUARE_PI_SESSION_ID', provider: 'pi' },
 ];
 export function automaticParticipant(provider, sessionId, env) {
     const configured = env.SQUARE_PARTICIPANT_NAME?.trim();

package/dist/ports.d.ts

@@ -11,7 +11,10 @@ export interface SquareArtifactPort {
     transact<R>(fn: (state: SquareState, version: number) => {
         state?: SquareState;
         result: R;
-    }): Promise<R>;
+    } | Promise<{
+        state?: SquareState;
+        result: R;
+    }>): Promise<R>;
     changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
     close(): Promise<void>;
 }
@@ -22,7 +25,7 @@ export interface WakeTransportPort {
         readonly outcome: 'not-capable';
         readonly diagnostic?: string;
     }>;
-    attempt(request: WakeRequest, timeoutMs: number): Promise<WakeOutcome>;
+    attempt(request: WakeRequest, timeoutMs: number, beforeSend?: () => Promise<boolean>): Promise<WakeOutcome>;
     /** Optional route retirement supplied by the concrete executor adapter. */
     invalidate?(request: WakeRequest): Promise<void>;
 }

package/dist/presentation-operations.js

@@ -17,27 +17,29 @@ export async function presentPending(input) {
     const item = before.state.acts.find((activity) => activity.index === index);
     if (item === undefined || delivery.isSeen(input.participant, index) || !delivery.pendingFor(input.participant).some((notification) => notification.item.index === index))
         return { presented: false };
+    let claimToken;
     if (input.hostLedger !== undefined && input.session !== undefined) {
-        const claim = await input.hostLedger.claimEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', leaseMs: input.timeoutMs ?? 5000, now: input.now });
+        const claim = await input.hostLedger.claimEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', leaseMs: input.timeoutMs ?? 5000 });
         if (claim.status !== 'acquired')
             return { presented: false };
+        claimToken = claim.claimToken;
         let current;
         try {
             current = await input.artifact.read();
         }
         catch {
-            await input.hostLedger.releaseEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', now: input.now }).catch(() => undefined);
+            await input.hostLedger.releaseEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', claimToken }).catch(() => undefined);
             return { presented: false };
         }
         if (deriveDeliveryModel(current.state).isSeen(input.participant, index)) {
-            await input.hostLedger.releaseEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', now: input.now }).catch(() => undefined);
+            await input.hostLedger.releaseEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', claimToken }).catch(() => undefined);
             return { presented: false };
         }
         try {
             await input.sink.present(item);
         }
         catch (error) {
-            await input.hostLedger.appendEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', outcome: 'failed', message: error instanceof Error ? error.message : String(error), at: input.now });
+            await input.hostLedger.appendEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', outcome: 'failed', message: error instanceof Error ? error.message : String(error), claimToken });
             throw error;
         }
     }
@@ -45,7 +47,7 @@ export async function presentPending(input) {
         await input.sink.present(item);
     if (input.markSeen !== false)
         await input.artifact.transact((state) => { const changed = recordObservation(state, input.participant, index, 'seen', input.now ?? Date.now()); return changed ? { state, result: undefined } : { result: undefined }; });
-    if (input.hostLedger !== undefined && input.session !== undefined)
-        await input.hostLedger.appendEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', outcome: input.markSeen === false ? 'clipped' : 'presented', ...(input.markSeen === false ? { message: 'presentation clipped' } : {}), at: input.now });
+    if (input.hostLedger !== undefined && input.session !== undefined && claimToken !== undefined)
+        await input.hostLedger.appendEvidence({ location: input.location, participant: input.participant, session: input.session, activity: formatActivityId(index), kind: 'presentation', outcome: input.markSeen === false ? 'clipped' : 'presented', ...(input.markSeen === false ? { message: 'presentation clipped' } : {}), claimToken });
     return { presented: true, activity: item };
 }

package/dist/registry.d.ts

@@ -10,6 +10,7 @@ export interface RegistryBinding {
     child: boolean;
     route?: PresenceRecord['route'];
     updatedAt: number;
+    epoch: number;
 }
 export interface RegistryWriteOptions {
     channel?: SessionChannel;
@@ -18,8 +19,14 @@ export interface RegistryWriteOptions {
     at?: number;
     env?: NodeJS.ProcessEnv;
 }
+type PresenceWithEpoch = PresenceRecord & {
+    readonly epoch?: number;
+};
 export declare function registryPath(env?: NodeJS.ProcessEnv): string;
 export declare function canonicalSquarePath(squarePath: string): Promise<string>;
+export declare function presenceEpoch(record: PresenceWithEpoch | undefined): number;
+/** Runs `fn` inside the ownership claim critical section, under the same lock as claims and finalize. */
+export declare function withOwnershipClaimLock<T>(env: NodeJS.ProcessEnv, fn: () => Promise<T>): Promise<T>;
 export declare function recordJoin(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): Promise<void>;
 export declare function recordDone(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): Promise<void>;
 export declare function readActiveBindings(now?: number, env?: NodeJS.ProcessEnv): Promise<RegistryBinding[]>;
@@ -36,10 +43,40 @@ export type CurrentParticipantBinding = Readonly<{
     created: boolean;
     sessionId: string;
 }>;
-export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<{
+export type OwnershipClaim = {
     readonly status: 'acquired' | 'owned';
     readonly sessionId: string;
-} | undefined>;
+    readonly epoch: number;
+} | undefined;
+export type TakeoverClaimToken = {
+    readonly sessionId: string;
+    readonly epoch: number;
+};
+export type TakeoverRunResult<T> = {
+    readonly status: 'acquired';
+    readonly sessionId: string;
+    readonly epoch: number;
+    readonly result: T;
+} | {
+    readonly status: 'busy';
+    readonly epoch: number;
+};
+export declare function readParticipantOwner(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<RegistryBinding | undefined>;
+export declare function sessionOwnsParticipant(squarePath: string, name: string, sessionId: string, env?: NodeJS.ProcessEnv, expectedEpoch?: number): Promise<boolean>;
+export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<OwnershipClaim>;
+/**
+ * Fenced takeover: the ownership claim and the lifecycle run as one critical section under the
+ * presence-claim lock, so no second takeover can interleave between claim and commit. The claim
+ * persists nothing until the lifecycle commits: standing owner rows stay authoritative through
+ * the lifecycle (a self-takeover can therefore never clobber its own standing row). On success
+ * the standing rows are replaced by the new owner's row at the claim epoch; on refusal, rows
+ * carrying the claim token (session + channel + claim epoch) are withdrawn and the captured
+ * standing rows are restored exactly.
+ */
+export declare function claimSessionTakeover<T>(squarePath: string, name: string, env: NodeJS.ProcessEnv | undefined, opts: {
+    readonly expectedEpoch?: number;
+    readonly expectedSession?: string;
+} | undefined, lifecycle: (claim: TakeoverClaimToken) => Promise<T>): Promise<TakeoverRunResult<T>>;
 export declare function releaseSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function bindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<CurrentParticipantBinding>;
 export declare function unbindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
@@ -60,3 +97,4 @@ export declare function recordLocalJoin(name: string, squarePath: string, env?:
 export declare function recordLocalDone(name: string, squarePath: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function recordSessionJoin(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function recordSessionDone(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): Promise<boolean>;
+export {};