@astrosheep/square 0.3.63 → 0.3.65

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

@@ -1,12 +1,13 @@
 import { promises as fs } from 'node:fs';
-import fsSync from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { withFileLock as acquireFileLock } from './file-lock.js';
 import { nameKey } from './model.js';
+import { formatActivityId } from './square-core.js';
 import { hostLedgerRoot } from './host-ledger-root.js';
 import { observeFileMetadata } from './file-changes.js';
+import { canonicalPath, canonicalPathSync } from './canonical-path.js';
 const LOCK = { retryMs: 10 };
 const RETENTION = 7 * 86400000;
 // Prepare before locking: lock databases and their journals are local runtime data too.
@@ -24,32 +25,12 @@ async function withFileLock(file, options, fn) {
     }
     return acquireFileLock(file, options, fn);
 }
-async function canon(value) { const absolute = path.resolve(value); try {
-    return await fs.realpath(absolute);
-}
-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 parsed = JSON.parse(line);
+        const row = decodeWakeRecord(parsed);
         const at = row.at ?? row.updatedAt;
-        const durableTerminal = row.kind === 'wake' && row.outcome === 'accepted';
-        return row.v === 1 && typeof at === 'number' && (durableTerminal || at >= now - RETENTION) && (includeFuture || at <= now) ? [row] : [];
+        return row.v === 1 && typeof at === 'number' && (durableWake(row) || at >= now - RETENTION) && (includeFuture || at <= now) ? [row] : [];
     }
     catch {
         return [];
@@ -89,21 +70,20 @@ async function write(file, rows, signal) {
     }
 }
 function k(v) { return JSON.stringify([v.location, nameKey(v.participant), v.session, v.channel, v.activity, v.kind]); }
-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 {
-        const row = JSON.parse(line);
-        return row.v === 1 && typeof row.ts === 'number' && typeof row.attention_key === 'string' && typeof row.leaseId === 'string' && typeof row.expiresAt === 'number' && (row.phase === 'claimed' || row.phase === 'dispatching') && row.ts >= now - RETENTION ? [row] : [];
-    }
-    catch {
-        return [];
-    } });
+function durableWake(record) {
+    const row = record;
+    return row.kind === 'wake' && (row.outcome === 'accepted' || row.outcome === 'unknown' || row.outcome === 'dispatching');
+}
+function decodeWakeRecord(row) {
+    return row.kind === 'wake' && row.outcome === 'unknown' && row.unknownSource === undefined
+        ? { ...row, unknownSource: row.signature === 'worker_interrupted_during_dispatch' ? 'interrupted' : 'transport' } : row;
+}
+/** Keep identity and native receipt, never a completed attempt's lease. */
+function finishWake(current, outcome, details = {}) {
+    const { expiresAt: _expiresAt, ownerPid: _ownerPid, unknownSource: _unknownSource, ...rest } = current;
+    return { ...rest, ...details, kind: 'wake', outcome,
+        ...(outcome === 'unknown' ? { unknownSource: details.unknownSource ?? 'transport' } : {}) };
 }
-catch (e) {
-    if (e.code === 'ENOENT')
-        return [];
-    throw e;
-} }
 function processAlive(pid) { if (pid === undefined)
     return undefined; try {
     process.kill(pid, 0);
@@ -112,14 +92,11 @@ function processAlive(pid) { if (pid === undefined)
 catch (error) {
     return error.code === 'ESRCH' ? false : true;
 } }
-function writeClaims(file, rows) { return write(file, rows); }
 export class FileHostLedgerPort {
     root;
-    claims;
     clock;
     constructor(o = {}) {
-        this.root = canonRoot(o.rootPath ?? hostLedgerRoot());
-        this.claims = canonRoot(o.claimsPath ?? path.join(this.root, 'wake-claims.ndjsonl'));
+        this.root = canonicalPathSync(o.rootPath ?? hostLedgerRoot());
         this.clock = o.now ?? Date.now;
     }
     file(kind) { return path.join(this.root, `${kind}.ndjsonl`); }
@@ -145,7 +122,7 @@ export class FileHostLedgerPort {
             if (typeof at === 'number') {
                 if (at > now)
                     next = Math.min(next, at);
-                if (at + RETENTION + 1 > now && !('kind' in row && row.kind === 'wake' && row.outcome === 'accepted'))
+                if (at + RETENTION + 1 > now && !durableWake(row))
                     next = Math.min(next, at + RETENTION + 1);
             }
             if ('expiresAt' in row && typeof row.expiresAt === 'number' && row.expiresAt > now)
@@ -153,11 +130,15 @@ export class FileHostLedgerPort {
         }
         return next;
     }
+    /** The ownership claim critical section: the same lock as claimPresence and finalize. */
+    withClaimLock(fn, signal) {
+        return withFileLock(path.join(this.root, 'presence-claim.lock'), { ...LOCK, signal }, fn);
+    }
     async claimPresence(i, signal) {
-        const location = await canon(i.location);
+        const location = await canonicalPath(i.location);
         const record = { ...i, location, updatedAt: i.updatedAt ?? this.clock(), v: 1 };
         try {
-            return await withFileLock(path.join(this.root, 'presence-claim.lock'), { ...LOCK, signal }, async () => {
+            return await this.withClaimLock(async () => {
                 const file = this.file('presence');
                 // The authoritative read, ownership check, and write share the presence file lock:
                 // a concurrent ensurePresence/removePresence between them must never be overwritten
@@ -170,28 +151,47 @@ export class FileHostLedgerPort {
                     await write(file, [...rows, record], signal);
                     return { status: 'acquired', record };
                 });
-            });
+            }, signal);
         }
         catch (error) {
             return { status: 'degraded', record, error };
         }
     }
     async ensurePresence(i) {
-        const record = { ...i, location: await canon(i.location), updatedAt: i.updatedAt ?? this.clock(), v: 1 };
+        const record = { ...i, location: await canonicalPath(i.location), updatedAt: i.updatedAt ?? this.clock(), v: 1 };
         try {
-            await withFileLock(this.file('presence') + '.lock', LOCK, async () => write(this.file('presence'), [...(await read(this.file('presence'), this.clock(), true)).filter((row) => k(row) !== k(record)), record]));
+            await withFileLock(this.file('presence') + '.lock', LOCK, async () => {
+                const rows = await read(this.file('presence'), this.clock(), true);
+                const current = rows.findLast((row) => k(row) === k(record));
+                const sameEpoch = current?.epoch === record.epoch;
+                const cancelledThrough = sameEpoch ? Math.max(current?.cancelledThrough ?? -1, record.cancelledThrough ?? -1) : record.cancelledThrough ?? -1;
+                await write(this.file('presence'), [...rows.filter((row) => k(row) !== k(record)), { ...record, ...(cancelledThrough < 0 ? {} : { cancelledThrough }) }]);
+            });
             return { status: 'ensured', record };
         }
         catch (error) {
             return { status: 'degraded', record, error };
         }
     }
+    /** Local batch suppression is monotonic only for the captured host generation. */
+    async suppressPresence(i, through) {
+        const record = { ...i, location: await canonicalPath(i.location) };
+        const file = this.file('presence');
+        return withFileLock(file + '.lock', LOCK, async () => {
+            const rows = await read(file, this.clock(), true);
+            const current = rows.findLast((row) => k(row) === k(record) && row.epoch === record.epoch);
+            if (!current)
+                return false;
+            await write(file, rows.map((row) => row === current ? { ...row, cancelledThrough: Math.max(row.cancelledThrough ?? -1, through) } : row));
+            return true;
+        });
+    }
     async removePresence(i) {
-        const record = { ...i, location: await canon(i.location) };
+        const record = { ...i, location: await canonicalPath(i.location) };
         await withFileLock(this.file('presence') + '.lock', LOCK, async () => write(this.file('presence'), (await read(this.file('presence'), this.clock(), true)).filter((row) => k(row) !== k(record))));
     }
     async removePresenceIfUnchanged(i) {
-        const record = { ...i, location: await canon(i.location) };
+        const record = { ...i, location: await canonicalPath(i.location) };
         return withFileLock(this.file('presence') + '.lock', LOCK, async () => {
             const file = this.file('presence');
             const rows = await read(file, this.clock(), true);
@@ -206,43 +206,127 @@ export class FileHostLedgerPort {
         });
     }
     async listPresence(i = {}) {
-        const location = i.location === undefined ? undefined : await canon(i.location);
+        const location = i.location === undefined ? undefined : await canonicalPath(i.location);
         return (await read(this.file('presence'), i.now ?? this.clock())).filter((row) => (!location || row.location === location) && (!i.participant || nameKey(row.participant) === nameKey(i.participant)) && (!i.session || row.session === i.session)).map(({ scope: _scope, ...row }) => row);
     }
-    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, '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;
+    /** One attempt row owns attention-wide exclusion and session-scoped history for a wake. */
+    async claimWakeAttempt(i) {
+        const location = await canonicalPath(i.attention.squarePath);
+        const activity = formatActivityId(i.attention.actIndex);
+        const at = i.now ?? this.clock();
+        const file = this.file('evidence');
+        try {
+            return await withFileLock(file + '.lock', LOCK, async () => {
+                const all = await read(file, at, true);
+                const attention = all.filter((row) => row.kind === 'wake' && row.location === location && nameKey(row.participant) === nameKey(i.attention.recipient) && row.activity === activity);
+                const terminal = attention.findLast((row) => row.outcome === 'accepted') ?? attention.findLast((row) => row.outcome === 'unknown');
+                if (terminal)
+                    return { status: 'terminal', record: terminal };
+                const interrupted = attention.filter((row) => row.outcome === 'dispatching');
+                const busy = interrupted.find((row) => (row.expiresAt ?? 0) > at && processAlive(row.ownerPid) !== false);
+                if (busy)
+                    return { status: 'busy', record: busy };
+                const nextNumber = (session) => attention.filter((row) => row.session === session).reduce((highest, row) => Math.max(highest, row.attemptN ?? 0), 0) + 1;
+                // An abandoned attempt may already have been sent, so it blocks every route.
+                if (interrupted.length) {
+                    const recovered = interrupted.map((row) => ({ ...finishWake(row, 'unknown', {
+                            unknownSource: 'interrupted', signature: 'worker_interrupted_during_dispatch',
+                            message: 'The notification worker ended after dispatch began; transport acceptance is unknown.',
+                        }), routeKind: row.routeKind ?? i.routeKind, attemptN: row.attemptN ?? nextNumber(row.session), v: 1 }));
+                    const replacements = new Map(interrupted.map((row, index) => [row, recovered[index]]));
+                    await write(file, all.map((row) => replacements.get(row) ?? row));
+                    return { status: 'terminal', record: recovered[0] };
+                }
+                const attemptN = nextNumber(i.session), claimToken = `${process.pid}-${at}-${randomUUID()}`;
+                await write(file, [...all, { v: 1, at, location, participant: i.attention.recipient, session: i.session, activity,
+                        kind: 'wake', outcome: 'dispatching', routeKind: i.routeKind, attemptN, claimToken, ownerPid: process.pid, expiresAt: at + i.leaseMs }]);
+                return { status: 'acquired', claimToken, attemptN };
+            });
+        }
+        catch (error) {
+            return { status: 'degraded', error };
+        }
     }
-    catch {
-        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, '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'); await this.appendEvidence(i); }
-    async claimEvidence(i) { const f = this.file('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 {
+    /** One locked, token-fenced replacement; each operation owns its state condition. */
+    async updateWake(input, update, at = this.clock()) {
+        if (!input.claimToken)
+            return false;
+        const location = await canonicalPath(input.location), file = this.file('evidence');
+        return withFileLock(file + '.lock', LOCK, async () => {
+            const all = await read(file, at, true);
+            const current = all.findLast((row) => row.kind === 'wake' && row.location === location && nameKey(row.participant) === nameKey(input.participant) && row.activity === input.activity && row.session === input.session && row.claimToken === input.claimToken);
+            const next = current && update(current);
+            if (!next)
+                return false;
+            if (next !== current)
+                await write(file, all.map((row) => row === current ? { ...next, v: 1 } : row));
+            return true;
+        });
+    }
+    async listWakeAttempts(i = {}) {
+        const attention = i.attention;
+        return this.listEvidence({ kind: 'wake', ...(attention === undefined ? {} : { location: await canonicalPath(attention.squarePath), participant: attention.recipient, activity: formatActivityId(attention.actIndex) }), session: i.session, now: i.now });
+    }
+    async prepareNativeWake(i) {
+        return this.updateWake(i, (current) => current.outcome === 'dispatching'
+            ? { ...current, nativeDelivery: i.nativeDelivery, routeKind: i.routeKind, attemptN: i.attemptN } : undefined);
+    }
+    async confirmWakeAdmission(i) {
+        return this.updateWake(i, (current) => {
+            if (!current.nativeDelivery || !['dispatching', 'unknown', 'accepted'].includes(current.outcome))
+                return undefined;
+            return current.outcome === 'accepted' ? current : finishWake(current, 'accepted', { signature: 'native_queue_confirmed', message: undefined, diagnostic: undefined });
+        });
+    }
+    async claimEvidence(i) { if (i.kind === 'wake')
+        return { status: 'degraded', error: new Error('wake attempts are claimed with claimWakeAttempt') }; const f = this.file('evidence'), at = i.now ?? this.clock(), { leaseMs, ...claim } = i, r = { ...claim, location: await canonicalPath(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') }; 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 }; });
+            return { status: 'busy', record: old }; if (r.kind === 'presentation' && matching.some(x => x.outcome === 'presented'))
+            return { status: 'delivered', record: matching.findLast(x => x.outcome === 'presented') }; const claimToken = `${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('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, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.signature === undefined ? {} : { signature: i.signature }), ...(i.message === undefined ? {} : { message: i.message }), ...(i.diagnostic === undefined ? {} : { diagnostic: i.diagnostic }), expiresAt: undefined }; delete tombstone.expiresAt; await write(f, [...all.filter(x => x !== current), tombstone]); }); }
-    async appendEvidence(i) { const f = this.file('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('evidence'), i.now ?? this.clock())).filter(r => (i.includeReleased === true || 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('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 releaseEvidence(i) {
+        if (i.kind === 'wake') {
+            const { signature, message, diagnostic, routeKind, attemptN } = i;
+            const details = Object.fromEntries(Object.entries({ signature, message, diagnostic, routeKind, attemptN }).filter(([, value]) => value !== undefined));
+            await this.updateWake(i, (current) => current.outcome === 'dispatching'
+                ? finishWake(current, 'released', { ...details, at: i.now ?? this.clock() }) : undefined, i.now);
+            return;
+        }
+        const f = this.file('evidence'), location = await canonicalPath(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, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.signature === undefined ? {} : { signature: i.signature }), ...(i.message === undefined ? {} : { message: i.message }), ...(i.diagnostic === undefined ? {} : { diagnostic: i.diagnostic }), expiresAt: undefined }; delete tombstone.expiresAt; delete tombstone.ownerPid; await write(f, [...all.filter(x => x !== current), tombstone]); });
+    }
+    /** Token-fenced terminal write. A token may only finish the attempt it claimed. */
+    async appendEvidence(i) {
+        const f = this.file('evidence'), r = { ...i, location: await canonicalPath(i.location), at: i.at ?? this.clock(), v: 1 };
+        const token = i.claimToken;
+        if (typeof token !== 'string' || token.length === 0)
+            return;
+        if (i.kind === 'wake') {
+            if (r.outcome !== 'accepted' && r.outcome !== 'failed' && r.outcome !== 'unknown')
+                return;
+            const outcome = r.outcome;
+            await this.updateWake(r, (current) => {
+                if (current.outcome !== 'dispatching' && !(current.outcome === 'unknown' && current.unknownSource === 'interrupted' && outcome === 'accepted'))
+                    return undefined;
+                return finishWake(current, outcome, { at: r.at, routeKind: r.routeKind, attemptN: r.attemptN, signature: r.signature, message: r.message, diagnostic: r.diagnostic });
+            }, r.at);
+            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 dispatching = all.findLast((x) => same(x) && x.outcome === 'dispatching');
+            const source = dispatching?.claimToken === token ? dispatching : undefined;
+            if (source === undefined)
+                return;
+            await write(f, [...all.filter((x) => x !== source && !(same(x) && x.attemptN === r.attemptN && x.outcome !== 'dispatching' && x.outcome !== 'released')), { ...r, ...(source.nativeDelivery === undefined ? {} : { nativeDelivery: source.nativeDelivery }) }]);
+        });
+    }
+    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canonicalPath(i.location); return (await read(this.file('evidence'), i.now ?? this.clock())).filter(r => (i.includeReleased === true || 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('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 || durableWake(r) && pending.has(r.activity)))); }
 }
 export function createHostLedgerPort(o = {}) { return new FileHostLedgerPort(o); }

package/dist/host-ledger.d.ts

@@ -1,16 +1,14 @@
 import type { WakeRouteKind } from './model.js';
-export type PresenceChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo' | 'unknown';
+import type { HarnessSessionChannel } from './participant-identity.js';
+export type PresenceChannel = HarnessSessionChannel | 'unknown';
 export interface PresenceRecord {
     readonly location: string;
     readonly participant: string;
     readonly session: string;
     readonly channel: PresenceChannel;
-    readonly route?: {
-        readonly kind: WakeRouteKind;
-        readonly address: Readonly<Record<string, string>>;
-    };
     readonly updatedAt?: number;
     readonly epoch?: number;
+    readonly cancelledThrough?: number;
 }
 export type PresenceKey = Pick<PresenceRecord, 'location' | 'participant' | 'session' | 'channel'>;
 export interface PresenceLookup {
@@ -38,12 +36,24 @@ export type PresenceClaimResult = {
     readonly record: PresenceRecord;
     readonly error: unknown;
 };
+export type NativeDeliveryEvidence = {
+    readonly payload: string;
+    readonly epoch: number;
+} & ({
+    readonly harness: 'claude';
+    readonly endpoint: string;
+} | {
+    readonly harness: 'opencode';
+    readonly inputId: string;
+});
 export interface EvidenceRecord {
+    readonly bindingEpoch?: number;
+    readonly nativeDelivery?: NativeDeliveryEvidence;
     readonly location: string;
     readonly participant: string;
     readonly session: string;
     readonly activity: string;
-    readonly kind: 'wake' | 'presentation';
+    readonly kind: 'wake' | 'presentation' | 'lifecycle';
     readonly outcome: string;
     readonly at?: number;
     readonly expiresAt?: number;
@@ -53,25 +63,33 @@ export interface EvidenceRecord {
     readonly message?: string;
     readonly diagnostic?: unknown;
     readonly claimToken?: string;
+    readonly ownerPid?: number;
+    readonly unknownSource?: 'interrupted' | 'transport';
 }
+/** Presentation and lifecycle claims only: wake attempts are acquired by claimWakeAttempt. */
 export interface EvidenceClaim {
     readonly location: string;
     readonly participant: string;
     readonly session: string;
     readonly activity: string;
-    readonly kind: EvidenceRecord['kind'];
+    readonly kind: 'presentation' | 'lifecycle';
     readonly leaseMs: number;
-    readonly claimToken?: string;
     readonly now?: number;
 }
 /** Release metadata and includeReleased are diagnostic-only; default evidence reads stay behavior-safe. */
-export interface EvidenceRelease extends Omit<EvidenceClaim, 'leaseMs'> {
+export interface EvidenceRelease {
+    readonly location: string;
+    readonly participant: string;
+    readonly session: string;
+    readonly activity: string;
+    readonly kind: EvidenceRecord['kind'];
     readonly claimToken: string;
     readonly routeKind?: WakeRouteKind;
     readonly attemptN?: number;
     readonly signature?: string;
     readonly message?: string;
     readonly diagnostic?: unknown;
+    readonly now?: number;
 }
 export interface EvidenceLookup {
     readonly location?: string;
@@ -91,46 +109,28 @@ export interface WakeAttention {
     readonly actIndex: number;
     readonly recipient: string;
 }
-export interface WakeDispatchLease {
-    readonly leaseId: string;
-    readonly expiresAt: number;
-    readonly phase: 'claimed' | 'dispatching';
-    readonly routeKind?: WakeRouteKind;
-    readonly attemptN?: number;
-    readonly session?: string;
+/** One wake attempt row carries attention-wide exclusion and session-specific history. */
+export interface WakeAttemptClaimInput {
+    readonly attention: WakeAttention;
+    readonly session: string;
+    readonly routeKind: WakeRouteKind;
+    readonly leaseMs: number;
+    readonly now?: number;
 }
-export type WakeDispatchClaim = {
-    readonly type: 'acquired';
-    readonly leaseId: string;
+export type WakeAttemptClaim = {
+    readonly status: 'acquired';
+    readonly claimToken: string;
+    readonly attemptN: number;
+} | {
+    readonly status: 'busy';
+    readonly record: EvidenceRecord;
 } | {
-    readonly type: 'busy';
+    readonly status: 'terminal';
+    readonly record: EvidenceRecord;
 } | {
-    readonly type: 'ambiguous';
-    readonly lease: WakeDispatchLease;
+    readonly status: 'degraded';
+    readonly error: unknown;
 };
-export interface WakeDispatchClaimInput {
-    readonly attention: WakeAttention;
-    readonly leaseId: string;
-    readonly leaseMs: number;
-    readonly session?: string;
-    readonly at?: number;
-}
-export interface WakeDispatchTransitionInput {
-    readonly attention: WakeAttention;
-    readonly leaseId: string;
-    readonly phase: WakeDispatchLease['phase'];
-    readonly leaseMs: number;
-    readonly routeKind?: WakeRouteKind;
-    readonly attemptN?: number;
-    readonly session?: string;
-    readonly at?: number;
-}
-export interface WakeDispatchReleaseInput {
-    readonly attention: WakeAttention;
-    readonly leaseId: string;
-    readonly session?: string;
-    readonly at?: number;
-}
 export interface WakeAttemptLookup {
     readonly attention?: WakeAttention;
     readonly session?: string;
@@ -147,8 +147,10 @@ export type ClaimResult = {
     readonly error: unknown;
 };
 export interface HostLedgerPort {
+    withClaimLock<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
     claimPresence(input: PresenceRecord, signal?: AbortSignal): Promise<PresenceClaimResult>;
     ensurePresence(input: PresenceRecord): Promise<PresenceResult>;
+    suppressPresence(input: PresenceRecord, through: number): Promise<boolean>;
     removePresence(input: PresenceKey): Promise<void>;
     removePresenceIfUnchanged(input: PresenceRecord): Promise<boolean>;
     listPresence(input: PresenceLookup): Promise<readonly PresenceRecord[]>;
@@ -159,11 +161,14 @@ export interface HostLedgerPort {
     }): Promise<void>;
     listEvidence(input: EvidenceLookup): Promise<readonly EvidenceRecord[]>;
     listWakeAttempts(input?: WakeAttemptLookup): Promise<readonly EvidenceRecord[]>;
-    appendWakeAttempt(input: EvidenceRecord & {
+    prepareNativeWake(input: EvidenceRecord & {
         readonly claimToken: string;
-    }): Promise<void>;
-    claimWakeDispatch(input: WakeDispatchClaimInput): Promise<WakeDispatchClaim>;
-    transitionWakeDispatch(input: WakeDispatchTransitionInput): Promise<boolean>;
-    releaseWakeDispatch(input: WakeDispatchReleaseInput): Promise<void>;
+        readonly routeKind: WakeRouteKind;
+        readonly nativeDelivery: NativeDeliveryEvidence;
+    }): Promise<boolean>;
+    confirmWakeAdmission(input: EvidenceRecord & {
+        readonly claimToken: string;
+    }): Promise<boolean>;
+    claimWakeAttempt(input: WakeAttemptClaimInput): Promise<WakeAttemptClaim>;
     gcEvidence(input: EvidenceGc): Promise<void>;
 }

package/dist/inbox.d.ts

@@ -1,5 +1,4 @@
 import { type InboxMembership } from './model.js';
-export declare function hostLedgerForEnv(env: NodeJS.ProcessEnv): import("./host-ledger-file-adapter.js").FileHostLedgerPort;
 export interface PendingWaitOptions {
     signal?: AbortSignal;
     /** Local delivery suppression, never persisted as evidence of receipt. */
@@ -15,5 +14,3 @@ export interface SessionPendingObserver {
 }
 /** Session-scoped projection over process-shared storage change detectors. */
 export declare function observeSessionPending(sessionId: string, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;
-/** Finite one-shot consumers retain their API; Pi owns a long-lived observer instead. */
-export declare function waitForSessionPending(sessionId: string, timeoutMs: number, options?: PendingWaitOptions, env?: NodeJS.ProcessEnv): Promise<InboxMembership[]>;