@astrosheep/square 0.3.27 → 0.3.29

package/dist/registry.js

@@ -1,11 +1,5 @@
-/**
- * Machine-local participant discovery cache.
- *
- * The Square artifact remains authoritative for membership. This append-only
- * cache only maps native harness sessions and optional Paseo agent ids back to
- * active (square path, participant name) pairs.
- */
-import fs from 'node:fs';
+/** Machine-local participant discovery cache. */
+import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
@@ -23,29 +17,16 @@ const LOCAL_SESSION_SOURCES = [
     { variable: 'OPENCODE_SESSION_ID', channel: 'opencode' },
     { variable: 'SQUARE_PI_SESSION_ID', channel: 'pi' },
 ];
-export function registryPath() {
-    if (process.env['SQUARE_REGISTRY'])
-        return process.env['SQUARE_REGISTRY'];
-    return path.join(homedir(), '.square', 'sessions.ndjsonl');
-}
-export function canonicalSquarePath(squarePath) {
-    const absolute = path.resolve(squarePath);
-    try {
-        return fs.realpathSync.native(absolute);
-    }
-    catch {
-        return absolute;
-    }
-}
-function bindingKey(sessionId, squarePath, name, channel) {
-    return JSON.stringify([sessionId, canonicalSquarePath(squarePath), nameKey(name), channel]);
-}
-function participantKey(squarePath, name) {
-    return JSON.stringify([canonicalSquarePath(squarePath), nameKey(name)]);
-}
-function nextOwnerId() {
-    return randomUUID();
-}
+export function registryPath() { return process.env.SQUARE_REGISTRY || path.join(homedir(), '.square', 'sessions.ndjsonl'); }
+export async function canonicalSquarePath(squarePath) { const absolute = path.resolve(squarePath); try {
+    return await fs.realpath(absolute);
+}
+catch {
+    return absolute;
+} }
+async function bindingKey(sessionId, squarePath, name, channel) { return JSON.stringify([sessionId, await canonicalSquarePath(squarePath), nameKey(name), channel]); }
+async function participantKey(squarePath, name) { return JSON.stringify([await canonicalSquarePath(squarePath), nameKey(name)]); }
+function nextOwnerId() { return randomUUID(); }
 function parseLine(raw, now) {
     let value;
     try {
@@ -57,320 +38,108 @@ function parseLine(raw, now) {
     if (value === null || typeof value !== 'object')
         return undefined;
     const entry = value;
-    if ((entry.v !== undefined && entry.v !== 1) ||
-        (entry.op !== 'join' && entry.op !== 'done') ||
-        typeof entry.session_id !== 'string' ||
-        entry.session_id === '' ||
-        typeof entry.name !== 'string' ||
-        entry.name === '' ||
-        typeof entry.square_path !== 'string' ||
-        entry.square_path === '' ||
-        typeof entry.ts !== 'string') {
+    if ((entry.v !== undefined && entry.v !== 1) || (entry.op !== 'join' && entry.op !== 'done') || typeof entry.session_id !== 'string' || entry.session_id === '' || typeof entry.name !== 'string' || entry.name === '' || typeof entry.square_path !== 'string' || entry.square_path === '' || typeof entry.ts !== 'string')
         return undefined;
-    }
     const updatedAt = Date.parse(entry.ts);
     if (!Number.isFinite(updatedAt) || updatedAt > now || now - updatedAt > MAX_AGE_MS)
         return undefined;
     const channel = entry.channel ?? 'unknown';
-    if (!VALID_CHANNELS.has(channel))
-        return undefined;
-    if (entry.child !== undefined && entry.child !== true)
-        return undefined;
-    if (entry.paseo_agent_id !== undefined && typeof entry.paseo_agent_id !== 'string')
-        return undefined;
-    if (entry.owner_id !== undefined && typeof entry.owner_id !== 'string')
+    if (!VALID_CHANNELS.has(channel) || (entry.child !== undefined && entry.child !== true) || (entry.paseo_agent_id !== undefined && typeof entry.paseo_agent_id !== 'string') || (entry.owner_id !== undefined && typeof entry.owner_id !== 'string'))
         return undefined;
     return { ...entry, v: 1, channel };
 }
-function foldRegistry(raw, now) {
+async function foldRegistry(raw, now) {
     const state = new Map();
-    // A later claim replaces the participant's prior agent, while one claim may retain multiple adapter identities.
     const owners = new Map();
     let order = 0;
     for (const line of raw.split('\n')) {
-        if (line.trim() === '')
+        if (!line.trim())
             continue;
         const entry = parseLine(line, now);
         if (!entry)
             continue;
         order++;
         const ownerId = entry.owner_id ?? `legacy:${order}`;
-        state.set(bindingKey(entry.session_id, entry.square_path, entry.name, entry.channel), {
-            entry,
-            updatedAt: Date.parse(entry.ts),
-            ownerId,
-        });
+        state.set(await bindingKey(entry.session_id, entry.square_path, entry.name, entry.channel), { entry, updatedAt: Date.parse(entry.ts), ownerId });
         if (entry.op === 'join')
-            owners.set(participantKey(entry.square_path, entry.name), ownerId);
+            owners.set(await participantKey(entry.square_path, entry.name), ownerId);
     }
     const active = [];
     for (const { entry, updatedAt, ownerId } of state.values()) {
-        if (entry.op !== 'join')
+        if (entry.op !== 'join' || owners.get(await participantKey(entry.square_path, entry.name)) !== ownerId)
             continue;
-        if (owners.get(participantKey(entry.square_path, entry.name)) !== ownerId)
-            continue;
-        active.push({
-            sessionId: entry.session_id,
-            name: entry.name,
-            squarePath: canonicalSquarePath(entry.square_path),
-            channel: entry.channel,
-            child: entry.child === true,
-            ...(entry.paseo_agent_id ? { paseoAgentId: entry.paseo_agent_id } : {}),
-            ownerId,
-            updatedAt,
-        });
+        active.push({ sessionId: entry.session_id, name: entry.name, squarePath: await canonicalSquarePath(entry.square_path), channel: entry.channel, child: entry.child === true, ...(entry.paseo_agent_id ? { paseoAgentId: entry.paseo_agent_id } : {}), ownerId, updatedAt });
     }
     return active.sort((a, b) => b.updatedAt - a.updatedAt);
 }
-function writeRegistryBindings(filePath, bindings) {
-    const compacted = bindings
-        .slice()
-        .reverse()
-        .map((binding) => JSON.stringify({
-        v: 1,
-        ts: new Date(binding.updatedAt).toISOString(),
-        op: 'join',
-        channel: binding.channel,
-        session_id: binding.sessionId,
-        name: binding.name,
-        square_path: binding.squarePath,
-        ...(binding.child ? { child: true } : {}),
-        ...(binding.paseoAgentId ? { paseo_agent_id: binding.paseoAgentId } : {}),
-        owner_id: binding.ownerId,
-    }))
-        .join('\n');
-    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(temporary, compacted === '' ? '' : `${compacted}\n`, { mode: 0o600 });
-    fs.renameSync(temporary, filePath);
-}
-function compactRegistry(filePath, raw, now) {
-    writeRegistryBindings(filePath, foldRegistry(raw, now));
-}
-function maybeCompactRegistry(filePath, now) {
-    let stat;
-    try {
-        stat = fs.statSync(filePath);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return;
-        throw error;
-    }
-    if (stat.size <= COMPACT_BYTES)
-        return;
-    const raw = fs.readFileSync(filePath, 'utf8');
-    const lines = raw.split('\n').filter(Boolean).length;
-    if (stat.size > COMPACT_BYTES || lines > COMPACT_LINES)
-        compactRegistry(filePath, raw, now);
-}
-function appendRegistryLine(entry, now) {
-    const filePath = registryPath();
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    maybeCompactRegistry(filePath, now);
-    const fd = fs.openSync(filePath, 'a', 0o600);
-    try {
-        fs.writeSync(fd, `${JSON.stringify(entry)}\n`);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
+async function writeRegistryBindings(filePath, bindings) { const compacted = bindings.slice().reverse().map((binding) => JSON.stringify({ v: 1, ts: new Date(binding.updatedAt).toISOString(), op: 'join', channel: binding.channel, session_id: binding.sessionId, name: binding.name, square_path: binding.squarePath, ...(binding.child ? { child: true } : {}), ...(binding.paseoAgentId ? { paseo_agent_id: binding.paseoAgentId } : {}), owner_id: binding.ownerId })).join('\n'); const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`; await fs.writeFile(temporary, compacted === '' ? '' : `${compacted}\n`, { mode: 0o600 }); await fs.rename(temporary, filePath); }
+async function maybeCompactRegistry(filePath, now) { let stat; try {
+    stat = await fs.stat(filePath);
 }
-function writeLifecycle(op, sessionId, name, squarePath, options) {
-    if (!sessionId || !name || !squarePath)
+catch (error) {
+    if (error.code === 'ENOENT')
         return;
-    const at = options.at ?? Date.now();
-    if (!Number.isFinite(at))
-        return;
-    try {
-        appendRegistryLine({
-            v: 1,
-            ts: new Date(at).toISOString(),
-            op,
-            channel: options.channel ?? 'unknown',
-            session_id: sessionId,
-            name,
-            square_path: canonicalSquarePath(squarePath),
-            ...(options.child ? { child: true } : {}),
-            ...(options.paseoAgentId ? { paseo_agent_id: options.paseoAgentId } : {}),
-            ...(op === 'join' ? { owner_id: options.ownerId ?? nextOwnerId() } : {}),
-        }, at);
-    }
-    catch (error) {
-        process.stderr.write(`! square registry write failed: ${error instanceof Error ? error.message : String(error)}\n`);
-    }
-}
-export function recordJoin(sessionId, name, squarePath, options = {}) {
-    writeLifecycle('join', sessionId, name, squarePath, options);
-}
-export function recordDone(sessionId, name, squarePath, options = {}) {
-    writeLifecycle('done', sessionId, name, squarePath, options);
-}
-export function readActiveBindings(now = Date.now()) {
-    try {
-        return foldRegistry(fs.readFileSync(registryPath(), 'utf8'), now);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return [];
-        return [];
-    }
-}
-export function lookupSessionBindings(sessionId, now = Date.now()) {
-    return readActiveBindings(now).filter((binding) => binding.sessionId === sessionId);
-}
-export function lookupSession(sessionId, now = Date.now()) {
-    return lookupSessionBindings(sessionId, now).map(({ name, squarePath }) => ({ name, squarePath }));
-}
-export function lookupParticipant(squarePath, name, now = Date.now()) {
-    const canonicalPath = canonicalSquarePath(squarePath);
-    return readActiveBindings(now).filter((binding) => binding.squarePath === canonicalPath && sameName(binding.name, name));
-}
-/** Resolve the current local harness owner for a participant, if one is registered. */
-export function localParticipantOwner(squarePath, name, env = process.env, now = Date.now()) {
-    const sessionIds = new Set(localSessionIdentities(env).map((identity) => identity.sessionId));
-    if (sessionIds.size === 0)
-        return undefined;
-    return lookupParticipant(squarePath, name, now).find((binding) => sessionIds.has(binding.sessionId))?.ownerId;
-}
-export function localParticipantName(squarePath, env = process.env) {
-    const identities = localSessionIdentities(env);
-    const names = new Set(identities.flatMap((identity) => lookupSession(identity.sessionId).filter((item) => canonicalSquarePath(item.squarePath) === canonicalSquarePath(squarePath)).map((item) => item.name)));
-    return names.size === 1 ? [...names][0] : undefined;
-}
-/** Compute the current participant from the live harness identity, without registry history. */
-export function squareAssignedParticipantName(env = process.env) {
-    return computeSquareAssignedParticipantName(env);
-}
-/** Bind the current harness to one explicit Square participant. */
-export function bindCurrentParticipant(squarePath, name, env = process.env) {
-    if (squareAssignedParticipantName(env) !== name) {
-        throw new SquareError('invalid_args', `The current session is not assigned ${name}`);
-    }
-    const localOwner = localParticipantOwner(squarePath, name, env);
-    if (localOwner !== undefined)
-        return { created: false, ownerId: localOwner };
-    const occupied = lookupParticipant(squarePath, name).at(0);
-    if (occupied !== undefined) {
-        throw new SquareError('already_joined', `${name} is already bound to another session`);
-    }
-    recordLocalJoin(name, squarePath, env);
-    const ownerId = localParticipantOwner(squarePath, name, env);
-    if (ownerId === undefined)
-        throw new Error(`Current participant binding did not commit for ${name}`);
-    return { created: true, ownerId };
-}
-/** Retire only this harness's binding for one Square participant. */
-export function unbindCurrentParticipant(squarePath, name, env = process.env) {
-    const identities = new Set(localSessionIdentities(env).map((identity) => identity.sessionId));
-    const current = lookupParticipant(squarePath, name).filter((binding) => identities.has(binding.sessionId));
-    for (const binding of current) {
-        recordSessionDone(binding.sessionId, binding.name, binding.squarePath, binding.channel, env);
-    }
-    return current.length > 0;
-}
-function bindingIsProvablyObsolete(binding, acts) {
-    return acts !== undefined && !isCurrentlyJoined(acts, binding.name);
-}
-/** Compact the registry and remove only bindings disproved by their authoritative artifact. */
-export function pruneRegistry(readActs, now = Date.now()) {
-    const filePath = registryPath();
-    let raw;
-    try {
-        raw = fs.readFileSync(filePath, 'utf8');
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return { removed: 0, kept: 0 };
-        throw error;
-    }
-    const active = foldRegistry(raw, now);
-    const kept = active.filter((binding) => !bindingIsProvablyObsolete(binding, readActs(binding.squarePath)));
-    writeRegistryBindings(filePath, kept);
-    return { removed: active.length - kept.length, kept: kept.length };
-}
-function addLocalSession(identities, sessionId, channel, child, paseoAgentId) {
-    if (!sessionId || identities.some((identity) => identity.sessionId === sessionId))
-        return;
-    identities.push({ sessionId, channel, child, ...(paseoAgentId ? { paseoAgentId } : {}) });
-}
-export function localSessionIdentities(env = process.env) {
-    const paseoAgentId = env['PASEO_AGENT_ID']?.trim() || undefined;
-    const identities = [];
-    for (const source of LOCAL_SESSION_SOURCES) {
-        addLocalSession(identities, env[source.variable]?.trim(), source.channel, source.child !== undefined && env[source.child] === '1', paseoAgentId);
-    }
-    addLocalSession(identities, paseoAgentId, 'paseo', false, paseoAgentId);
-    return identities;
-}
-/** True when this process belongs to a harness that can deliver Square attention without a foreground catch. */
-export function hasAutomaticDeliveryIdentity(env = process.env) {
-    return localSessionIdentities(env).length > 0;
-}
-export function recordLocalJoin(name, squarePath, env = process.env) {
-    const at = Date.now();
-    const identities = localSessionIdentities(env);
-    const current = lookupParticipant(squarePath, name, at);
-    const ownerId = nextOwnerId();
-    for (const binding of current) {
-        recordDone(binding.sessionId, binding.name, binding.squarePath, {
-            channel: binding.channel,
-            child: binding.child,
-            ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}),
-            at,
-        });
-    }
-    for (const identity of identities) {
-        recordJoin(identity.sessionId, name, squarePath, { ...identity, at, ownerId });
-    }
-    publishWakeRoutes(ownerId, { at, env });
-    for (const previousOwnerId of new Set(current.map((binding) => binding.ownerId))) {
-        if (previousOwnerId !== ownerId)
-            retireOwnerWakeRoutes(previousOwnerId, { at, env });
-    }
-}
-export function recordLocalDone(name, squarePath, env = process.env) {
-    const at = Date.now();
-    const current = lookupParticipant(squarePath, name, at);
-    for (const binding of current) {
-        recordDone(binding.sessionId, binding.name, binding.squarePath, {
-            channel: binding.channel,
-            child: binding.child,
-            ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}),
-            at,
-        });
-    }
-    for (const ownerId of new Set(current.map((binding) => binding.ownerId))) {
-        retireOwnerWakeRoutes(ownerId, { at, env });
-    }
-}
-export function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) {
-    const at = Date.now();
-    const ownerId = nextOwnerId();
-    const current = lookupParticipant(squarePath, name, at);
-    for (const binding of current) {
-        recordDone(binding.sessionId, binding.name, binding.squarePath, {
-            channel: binding.channel,
-            child: binding.child,
-            ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}),
-            at,
-        });
-        retireOwnerWakeRoutes(binding.ownerId, { at, env });
-    }
-    recordJoin(sessionId, name, squarePath, { channel, at, ownerId });
-    publishWakeRoutes(ownerId, { at, env });
-    return ownerId;
-}
-export function recordSessionDone(sessionId, name, squarePath, channel, env = process.env) {
-    const binding = lookupSessionBindings(sessionId).find((item) => canonicalSquarePath(item.squarePath) === canonicalSquarePath(squarePath)
-        && sameName(item.name, name)
-        && item.channel === channel);
-    if (binding === undefined)
-        return false;
-    const at = Date.now();
-    recordDone(sessionId, binding.name, binding.squarePath, { channel, at });
-    const remaining = lookupParticipant(squarePath, binding.name, at)
-        .some((candidate) => candidate.ownerId === binding.ownerId);
-    if (!remaining)
-        retireOwnerWakeRoutes(binding.ownerId, { at, env });
-    return true;
-}
+    throw error;
+} if (stat.size <= COMPACT_BYTES)
+    return; const raw = await fs.readFile(filePath, 'utf8'); if (stat.size > COMPACT_BYTES || raw.split('\n').filter(Boolean).length > COMPACT_LINES)
+    await writeRegistryBindings(filePath, await foldRegistry(raw, now)); }
+async function appendRegistryLine(entry, now) { const filePath = registryPath(); await fs.mkdir(path.dirname(filePath), { recursive: true }); await maybeCompactRegistry(filePath, now); await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, { mode: 0o600 }); }
+async function writeLifecycle(op, sessionId, name, squarePath, options) { if (!sessionId || !name || !squarePath)
+    return; const at = options.at ?? Date.now(); if (!Number.isFinite(at))
+    return; try {
+    await appendRegistryLine({ v: 1, ts: new Date(at).toISOString(), op, channel: options.channel ?? 'unknown', session_id: sessionId, name, square_path: await canonicalSquarePath(squarePath), ...(options.child ? { child: true } : {}), ...(options.paseoAgentId ? { paseo_agent_id: options.paseoAgentId } : {}), ...(op === 'join' ? { owner_id: options.ownerId ?? nextOwnerId() } : {}) }, at);
+}
+catch (error) {
+    process.stderr.write(`! square registry write failed: ${error instanceof Error ? error.message : String(error)}\n`);
+} }
+export function recordJoin(sessionId, name, squarePath, options = {}) { return writeLifecycle('join', sessionId, name, squarePath, options); }
+export function recordDone(sessionId, name, squarePath, options = {}) { return writeLifecycle('done', sessionId, name, squarePath, options); }
+export async function readActiveBindings(now = Date.now()) { try {
+    return await foldRegistry(await fs.readFile(registryPath(), 'utf8'), now);
+}
+catch {
+    return [];
+} }
+export async function lookupSessionBindings(sessionId, now = Date.now()) { return (await readActiveBindings(now)).filter((binding) => binding.sessionId === sessionId); }
+export async function lookupSession(sessionId, now = Date.now()) { return (await lookupSessionBindings(sessionId, now)).map(({ name, squarePath }) => ({ name, squarePath })); }
+export async function lookupParticipant(squarePath, name, now = Date.now()) { const canonicalPath = await canonicalSquarePath(squarePath); return (await readActiveBindings(now)).filter((binding) => binding.squarePath === canonicalPath && sameName(binding.name, name)); }
+export async function localParticipantOwner(squarePath, name, env = process.env, now = Date.now()) { const sessionIds = new Set(localSessionIdentities(env).map((identity) => identity.sessionId)); if (sessionIds.size === 0)
+    return undefined; return (await lookupParticipant(squarePath, name, now)).find((binding) => sessionIds.has(binding.sessionId))?.ownerId; }
+export async function localParticipantName(squarePath, env = process.env) { const canonicalPath = await canonicalSquarePath(squarePath); const names = new Set((await Promise.all(localSessionIdentities(env).map(async (identity) => (await lookupSession(identity.sessionId)).filter((item) => item.squarePath === canonicalPath).map((item) => item.name)))).flat()); return names.size === 1 ? [...names][0] : undefined; }
+export function squareAssignedParticipantName(env = process.env) { return computeSquareAssignedParticipantName(env); }
+export async function bindCurrentParticipant(squarePath, name, env = process.env) { if (squareAssignedParticipantName(env) !== name)
+    throw new SquareError('invalid_args', `The current session is not assigned ${name}`); const localOwner = await localParticipantOwner(squarePath, name, env); if (localOwner !== undefined)
+    return { created: false, ownerId: localOwner }; if ((await lookupParticipant(squarePath, name)).at(0) !== undefined)
+    throw new SquareError('already_joined', `${name} is already bound to another session`); await recordLocalJoin(name, squarePath, env); const ownerId = await localParticipantOwner(squarePath, name, env); if (ownerId === undefined)
+    throw new Error(`Current participant binding did not commit for ${name}`); return { created: true, ownerId }; }
+export async function unbindCurrentParticipant(squarePath, name, env = process.env) { const identities = new Set(localSessionIdentities(env).map((identity) => identity.sessionId)); const current = (await lookupParticipant(squarePath, name)).filter((binding) => identities.has(binding.sessionId)); for (const binding of current)
+    await recordSessionDone(binding.sessionId, binding.name, binding.squarePath, binding.channel, env); return current.length > 0; }
+function bindingIsProvablyObsolete(binding, acts) { return acts !== undefined && !isCurrentlyJoined(acts, binding.name); }
+export async function pruneRegistry(readActs, now = Date.now()) { const filePath = registryPath(); let raw; try {
+    raw = await fs.readFile(filePath, 'utf8');
+}
+catch (error) {
+    if (error.code === 'ENOENT')
+        return { removed: 0, kept: 0 };
+    throw error;
+} const active = await foldRegistry(raw, now); const observed = await Promise.all(active.map(async (binding) => ({ binding, acts: await readActs(binding.squarePath) }))); const kept = observed.filter(({ binding, acts }) => !bindingIsProvablyObsolete(binding, acts)).map(({ binding }) => binding); await writeRegistryBindings(filePath, kept); return { removed: active.length - kept.length, kept: kept.length }; }
+function addLocalSession(identities, sessionId, channel, child, paseoAgentId) { if (!sessionId || identities.some((identity) => identity.sessionId === sessionId))
+    return; identities.push({ sessionId, channel, child, ...(paseoAgentId ? { paseoAgentId } : {}) }); }
+export function localSessionIdentities(env = process.env) { const paseoAgentId = env.PASEO_AGENT_ID?.trim() || undefined; const identities = []; for (const source of LOCAL_SESSION_SOURCES)
+    addLocalSession(identities, env[source.variable]?.trim(), source.channel, source.child !== undefined && env[source.child] === '1', paseoAgentId); addLocalSession(identities, paseoAgentId, 'paseo', false, paseoAgentId); return identities; }
+export function hasAutomaticDeliveryIdentity(env = process.env) { return localSessionIdentities(env).length > 0; }
+export async function recordLocalJoin(name, squarePath, env = process.env) { const at = Date.now(); const identities = localSessionIdentities(env); const current = await lookupParticipant(squarePath, name, at); const ownerId = nextOwnerId(); for (const binding of current)
+    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, child: binding.child, ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}), at }); for (const identity of identities)
+    await recordJoin(identity.sessionId, name, squarePath, { ...identity, at, ownerId }); await publishWakeRoutes(ownerId, { at, env }); for (const previousOwnerId of new Set(current.map((binding) => binding.ownerId)))
+    if (previousOwnerId !== ownerId)
+        await retireOwnerWakeRoutes(previousOwnerId, { at, env }); }
+export async function recordLocalDone(name, squarePath, env = process.env) { const at = Date.now(); const current = await lookupParticipant(squarePath, name, at); for (const binding of current)
+    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, child: binding.child, ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}), at }); for (const ownerId of new Set(current.map((binding) => binding.ownerId)))
+    await retireOwnerWakeRoutes(ownerId, { at, env }); }
+export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const ownerId = nextOwnerId(); const current = await lookupParticipant(squarePath, name, at); for (const binding of current) {
+    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, child: binding.child, ...(binding.paseoAgentId ? { paseoAgentId: binding.paseoAgentId } : {}), at });
+    await retireOwnerWakeRoutes(binding.ownerId, { at, env });
+} await recordJoin(sessionId, name, squarePath, { channel, at, ownerId }); await publishWakeRoutes(ownerId, { at, env }); return ownerId; }
+export async function recordSessionDone(sessionId, name, squarePath, channel, env = process.env) { const canonicalPath = await canonicalSquarePath(squarePath); const binding = (await lookupSessionBindings(sessionId)).find((item) => item.squarePath === canonicalPath && sameName(item.name, name) && item.channel === channel); if (binding === undefined)
+    return false; const at = Date.now(); await recordDone(sessionId, binding.name, binding.squarePath, { channel, at }); const remaining = (await lookupParticipant(squarePath, binding.name, at)).some((candidate) => candidate.ownerId === binding.ownerId); if (!remaining)
+    await retireOwnerWakeRoutes(binding.ownerId, { at, env }); return true; }

package/dist/routes.d.ts

@@ -8,20 +8,20 @@ export declare function readWakeRoutes(opts?: {
     freshOnly?: boolean;
     now?: number;
     env?: NodeJS.ProcessEnv;
-}): WakeRoute[];
+}): Promise<WakeRoute[]>;
 export declare function upsertWakeRoute(route: Omit<WakeRoute, 'updatedAt'>, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
-}): void;
+}): Promise<void>;
 export declare function retireOwnerWakeRoutes(ownerId: string, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
-}): void;
+}): Promise<void>;
 /** Retire one capability without touching sibling identities in the same claim. */
 export declare function retireWakeRoute(route: Pick<WakeRoute, 'ownerId' | 'sessionId' | 'kind'>, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
-}): void;
+}): Promise<void>;
 export interface WakeRouteEvidence {
     sessionId: string;
     address: Record<string, string>;
@@ -39,9 +39,9 @@ export declare const WAKE_ROUTE_PROBES: Readonly<Record<WakeRouteKind, WakeRoute
 export declare function publishWakeRoutesFrom(ownerId: string, probes: Readonly<Record<WakeRouteKind, WakeRouteProbe>>, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
-}): void;
+}): Promise<void>;
 /** Publication boundary: every route written is complete provider evidence. */
 export declare function publishWakeRoutes(ownerId: string, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
-}): void;
+}): Promise<void>;

package/dist/routes.js

@@ -1,4 +1,4 @@
-import fs from 'node:fs';
+import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { WAKE_ROUTE_KINDS, isWakeRouteKind } from './model.js';
@@ -42,10 +42,10 @@ function parseRow(raw, now) {
         return undefined;
     return row;
 }
-function readRows(env, now) {
+async function readRows(env, now) {
     let raw;
     try {
-        raw = fs.readFileSync(routesPath(env), 'utf8');
+        raw = await fs.readFile(routesPath(env), 'utf8');
     }
     catch (error) {
         if (error.code === 'ENOENT')
@@ -54,10 +54,10 @@ function readRows(env, now) {
     }
     return raw.split('\n').filter(Boolean).map((line) => parseRow(line, now)).filter((row) => row !== undefined);
 }
-export function readWakeRoutes(opts = {}) {
+export async function readWakeRoutes(opts = {}) {
     const now = opts.now ?? Date.now();
     const state = new Map();
-    for (const row of readRows(opts.env ?? process.env, now)) {
+    for (const row of await readRows(opts.env ?? process.env, now)) {
         const key = routeKey(row.owner_id, row.kind);
         const current = state.get(key);
         if (current === undefined || row.ts >= current.ts)
@@ -77,14 +77,14 @@ export function readWakeRoutes(opts = {}) {
         .sort((a, b) => (ROUTE_KIND_PRIORITY.get(a.kind) ?? 0) - (ROUTE_KIND_PRIORITY.get(b.kind) ?? 0) ||
         b.updatedAt - a.updatedAt);
 }
-function appendRouteRow(row, env) {
+async function appendRouteRow(row, env) {
     const file = routesPath(env);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.appendFileSync(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.appendFile(file, `${JSON.stringify(row)}\n`, { mode: 0o600 });
 }
-export function upsertWakeRoute(route, opts = {}) {
+export async function upsertWakeRoute(route, opts = {}) {
     const at = opts.at ?? Date.now();
-    appendRouteRow({
+    await appendRouteRow({
         v: 1,
         ts: at,
         op: 'upsert',
@@ -94,11 +94,11 @@ export function upsertWakeRoute(route, opts = {}) {
         address: route.address,
     }, opts.env ?? process.env);
 }
-export function retireOwnerWakeRoutes(ownerId, opts = {}) {
+export async function retireOwnerWakeRoutes(ownerId, opts = {}) {
     const at = opts.at ?? Date.now();
     const env = opts.env ?? process.env;
-    for (const route of readWakeRoutes({ ownerId, now: at, env })) {
-        appendRouteRow({
+    for (const route of await readWakeRoutes({ ownerId, now: at, env })) {
+        await appendRouteRow({
             v: 1,
             ts: at,
             op: 'retire',
@@ -109,14 +109,14 @@ export function retireOwnerWakeRoutes(ownerId, opts = {}) {
     }
 }
 /** Retire one capability without touching sibling identities in the same claim. */
-export function retireWakeRoute(route, opts = {}) {
+export async function retireWakeRoute(route, opts = {}) {
     const at = opts.at ?? Date.now();
     const env = opts.env ?? process.env;
-    const current = readWakeRoutes({ ownerId: route.ownerId, now: at, env })
+    const current = (await readWakeRoutes({ ownerId: route.ownerId, now: at, env }))
         .find((candidate) => candidate.sessionId === route.sessionId && candidate.kind === route.kind);
     if (current === undefined)
         return;
-    appendRouteRow({
+    await appendRouteRow({
         v: 1,
         ts: at,
         op: 'retire',
@@ -157,17 +157,17 @@ export const WAKE_ROUTE_PROBES = {
     },
 };
 /** The kind-neutral publication loop; probes supply complete evidence per kind. */
-export function publishWakeRoutesFrom(ownerId, probes, opts = {}) {
+export async function publishWakeRoutesFrom(ownerId, probes, opts = {}) {
     const at = opts.at ?? Date.now();
     const env = opts.env ?? process.env;
     for (const kind of WAKE_ROUTE_KINDS) {
         const evidence = probes[kind](env);
         if (!completeRouteEvidence(evidence))
             continue;
-        upsertWakeRoute({ ownerId, sessionId: evidence.sessionId, kind, address: evidence.address }, { at, env });
+        await upsertWakeRoute({ ownerId, sessionId: evidence.sessionId, kind, address: evidence.address }, { at, env });
     }
 }
 /** Publication boundary: every route written is complete provider evidence. */
-export function publishWakeRoutes(ownerId, opts = {}) {
-    publishWakeRoutesFrom(ownerId, WAKE_ROUTE_PROBES, opts);
+export async function publishWakeRoutes(ownerId, opts = {}) {
+    await publishWakeRoutesFrom(ownerId, WAKE_ROUTE_PROBES, opts);
 }

package/dist/square-file-adapter.d.ts

@@ -13,7 +13,7 @@ export interface SquareBuildOptions {
     notifier?: WakeNotifier;
 }
 export declare function openSquare(squarePath: string, options?: Pick<SquareBuildOptions, 'clock' | 'notifier'>): Promise<OpenSquare>;
-export declare function probeSquare(squarePath: string): OpenSquare | undefined;
+export declare function probeSquare(squarePath: string): Promise<OpenSquare | undefined>;
 export declare function buildSquare(squarePath: string, options: SquareBuildOptions): Promise<OpenSquare>;
 export declare function buildMemorySquare(options: SquareBuildOptions): OpenSquare;
 /** Wait for any bound artifact to change; delivery callers re-project after the edge. */

package/dist/square-file-adapter.js

@@ -2,17 +2,13 @@ import fs from 'node:fs';
 import { createSquareState, probeSquareFile, writeSquareSnapshot, withSquareFileLock, openSquareCell, createMemoryCell, } from './square-storage.js';
 import { InternalSquareError, SquareError, } from './model.js';
 import { closeOpenSquare } from './open-square.js';
-/** The current CLI file mutation boundary. */
-function writeSquareState(squarePath, squareState) {
-    writeSquareSnapshot(squarePath, squareState);
-}
 /** File-owned artifact creation for the CLI and path-backed public facade. */
 export async function createSquare(squarePath, options, snippet) {
-    await withSquareFileLock(squarePath, () => {
-        if (fs.existsSync(squarePath) && !options.force) {
+    await withSquareFileLock(squarePath, async () => {
+        if (await fs.promises.access(squarePath).then(() => true, () => false) && !options.force) {
             throw new InternalSquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
         }
-        writeSquareSnapshot(squarePath, createSquareState(options, snippet));
+        await writeSquareSnapshot(squarePath, await createSquareState(options, snippet));
     });
 }
 function validateBuildOptions(options) {
@@ -39,8 +35,8 @@ export async function openSquare(squarePath, options = {}) {
         throw error;
     }
 }
-export function probeSquare(squarePath) {
-    const state = probeSquareFile(squarePath);
+export async function probeSquare(squarePath) {
+    const state = await probeSquareFile(squarePath);
     return state === undefined ? undefined : { cell: createMemoryCell(state), clock: Date.now, location: squarePath };
 }
 export async function buildSquare(squarePath, options) {