@astrosheep/square 0.3.41 → 0.3.43

package/dist/registry.js

@@ -1,11 +1,13 @@
 /** Machine-local participant discovery cache. */
 import path from 'node:path';
 import { homedir } from 'node:os';
+import { withFileLock } from './file-lock.js';
 import { sameName, SquareError } from './model.js';
 import { isCurrentlyJoined } from './runtime.js';
 import { squareAssignedParticipantName as computeSquareAssignedParticipantName } from './participant-identity.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+const PRESENCE_CLAIM_LOCK = { retryMs: 10 };
 const LOCAL_SESSION_SOURCES = [
     { variable: 'CLAUDE_CODE_SESSION_ID', channel: 'claude-code', child: 'CLAUDE_CODE_CHILD_SESSION' },
     { variable: 'CODEX_THREAD_ID', channel: 'codex' },
@@ -19,8 +21,38 @@ export async function canonicalSquarePath(squarePath) { const absolute = path.re
 catch {
     return absolute;
 } }
-function ledger(env, writableScope = 'local') { const root = path.dirname(registryPath(env)); return createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? (env.SQUARE_REGISTRY ? root : path.join(homedir(), '.square', 'host-ledger')), localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? (env.SQUARE_REGISTRY ? root : path.join(process.cwd(), '.square', 'host-ledger')), writableScope }); }
-function toBinding(record) { return { sessionId: record.session, name: record.participant, squarePath: record.location, channel: record.channel, child: false, ...(record.route === undefined ? {} : { route: record.route }), updatedAt: record.updatedAt ?? 0 }; }
+function ledgerRoot(env) {
+    const root = path.dirname(registryPath(env));
+    return {
+        userPath: env.SQUARE_HOST_LEDGER_USER ?? (env.SQUARE_REGISTRY ? root : path.join(homedir(), '.square', 'host-ledger')),
+        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? (env.SQUARE_REGISTRY ? root : path.join(process.cwd(), '.square', 'host-ledger')),
+    };
+}
+function ledger(env, writableScope = 'local') {
+    return createHostLedgerPort({ ...ledgerRoot(env), writableScope });
+}
+export function presenceEpoch(record) {
+    return typeof record?.epoch === 'number' && Number.isSafeInteger(record.epoch) && record.epoch > 0 ? record.epoch : 0;
+}
+function toBinding(record) {
+    return {
+        sessionId: record.session,
+        name: record.participant,
+        squarePath: record.location,
+        channel: record.channel,
+        child: false,
+        ...(record.route === undefined ? {} : { route: record.route }),
+        updatedAt: record.updatedAt ?? 0,
+        epoch: presenceEpoch(record),
+    };
+}
+function presenceClaimLockPath(env) {
+    return path.join(ledgerRoot(env).userPath, 'presence-claim.lock');
+}
+/** Runs `fn` inside the ownership claim critical section, under the same lock as claims and finalize. */
+export async function withOwnershipClaimLock(env, fn) {
+    return withFileLock(presenceClaimLockPath(env), PRESENCE_CLAIM_LOCK, fn);
+}
 async function activeBindings(now, env) { return (await ledger(env).listPresence({ now, scopes: ['user', 'local'] })).map(toBinding).sort((a, b) => b.updatedAt - a.updatedAt); }
 async function writePresence(sessionId, name, squarePath, options, done, scope = 'local') { if (!sessionId || !name || !squarePath)
     return; const env = options.env ?? process.env; const channel = options.channel ?? 'unknown'; const port = ledger(env, scope); const location = await canonicalSquarePath(squarePath); if (done)
@@ -45,17 +77,122 @@ export async function localParticipantOwner(squarePath, name, env = process.env,
     return undefined; return (await lookupParticipant(squarePath, name, now, env)).find((binding) => sessionIds.has(binding.sessionId))?.sessionId; }
 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, Date.now(), env)).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 readParticipantOwner(squarePath, name, env = process.env) {
+    const bindings = await lookupParticipant(squarePath, name, Date.now(), env);
+    return bindings.sort((left, right) => right.epoch - left.epoch || right.updatedAt - left.updatedAt)[0];
+}
+export async function sessionOwnsParticipant(squarePath, name, sessionId, env = process.env, expectedEpoch) {
+    const owner = await readParticipantOwner(squarePath, name, env);
+    if (owner === undefined || owner.sessionId !== sessionId)
+        return false;
+    return expectedEpoch === undefined || owner.epoch === expectedEpoch;
+}
 export async function claimSessionParticipant(squarePath, name, env = process.env) {
     const identity = localSessionIdentities(env)[0];
     if (identity === undefined)
         return undefined;
     const location = await canonicalSquarePath(squarePath);
-    const result = await ledger(env).claimPresence({ location, participant: name, session: identity.sessionId, channel: identity.channel, updatedAt: Date.now() }, 'local');
+    const result = await ledger(env).claimPresence({
+        location,
+        participant: name,
+        session: identity.sessionId,
+        channel: identity.channel,
+        updatedAt: Date.now(),
+        epoch: 1,
+    }, 'local');
     if (result.status === 'busy')
         throw new SquareError('already_joined', `${name} is already bound to another session`);
     if (result.status === 'degraded')
         throw result.error;
-    return { status: result.status, sessionId: identity.sessionId };
+    const epoch = presenceEpoch(result.record) || (result.status === 'acquired' ? 1 : 0);
+    return { status: result.status, sessionId: identity.sessionId, epoch };
+}
+/**
+ * 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 async function claimSessionTakeover(squarePath, name, env = process.env, opts = {}, lifecycle) {
+    const identity = localSessionIdentities(env)[0];
+    if (identity === undefined)
+        throw new SquareError('invalid_args', 'No local session identity for takeover');
+    const location = await canonicalSquarePath(squarePath);
+    return withFileLock(presenceClaimLockPath(env), PRESENCE_CLAIM_LOCK, async () => {
+        const port = ledger(env);
+        const standing = {
+            user: await port.listPresence({ location, participant: name, scopes: ['user'] }),
+            local: await port.listPresence({ location, participant: name, scopes: ['local'] }),
+        };
+        const owner = [...standing.user, ...standing.local]
+            .map((row) => toBinding(row))
+            .sort((left, right) => right.epoch - left.epoch || right.updatedAt - left.updatedAt)[0];
+        const currentEpoch = owner?.epoch ?? 0;
+        const epochMatches = opts.expectedEpoch === undefined || currentEpoch === opts.expectedEpoch;
+        const sessionMatches = opts.expectedSession === undefined
+            || (opts.expectedSession === '' ? owner === undefined : owner?.sessionId === opts.expectedSession);
+        if (!epochMatches || !sessionMatches) {
+            return { status: 'busy', epoch: currentEpoch };
+        }
+        const epoch = currentEpoch + 1;
+        let result;
+        try {
+            result = await lifecycle({ sessionId: identity.sessionId, epoch });
+        }
+        catch (error) {
+            // Withdraw: the claim itself persisted nothing. Remove only rows carrying this exact claim
+            // token (session + channel + epoch) — whatever the lifecycle itself ensured — then restore
+            // the captured standing rows so the old owner survives byte-consistently. Foreign rows and
+            // later owners are never touched.
+            for (const scope of ['user', 'local']) {
+                const tokenRows = await ledger(env, scope).listPresence({
+                    location,
+                    participant: name,
+                    session: identity.sessionId,
+                    scopes: [scope],
+                });
+                for (const row of tokenRows) {
+                    if (row.channel !== identity.channel || presenceEpoch(row) !== epoch)
+                        continue;
+                    await ledger(env, scope).removePresence({
+                        location: row.location,
+                        participant: row.participant,
+                        session: row.session,
+                        channel: row.channel,
+                    });
+                }
+                for (const row of standing[scope]) {
+                    await ledger(env, scope).ensurePresence(row, scope);
+                }
+            }
+            throw error;
+        }
+        // Finalize: the lifecycle committed. Replace the standing owner with the new owner's row at
+        // the claim epoch in every scope where the owner was visible, so exactly one current owner
+        // remains — also when the takeover is a self-takeover (same session as the standing owner).
+        for (const scope of ['user', 'local']) {
+            for (const row of standing[scope]) {
+                await ledger(env, scope).removePresence({
+                    location: row.location,
+                    participant: row.participant,
+                    session: row.session,
+                    channel: row.channel,
+                });
+            }
+            await ledger(env, scope).ensurePresence({
+                location,
+                participant: name,
+                session: identity.sessionId,
+                channel: identity.channel,
+                updatedAt: Date.now(),
+                epoch,
+            }, scope);
+        }
+        return { status: 'acquired', sessionId: identity.sessionId, epoch, result };
+    });
 }
 export async function releaseSessionParticipant(squarePath, name, env = process.env) {
     const identity = localSessionIdentities(env)[0];

package/dist/routes.d.ts

@@ -13,7 +13,6 @@ export interface WakeRouteCapabilities {
     readonly canUse: (kind: WakeRouteKind, address: Readonly<Record<string, string>>) => boolean;
 }
 export declare function defaultWakeRouteCapabilities(hostLedger?: import('./host-ledger.js').HostLedgerPort): Promise<WakeRouteCapabilities>;
-/** Pure, ordered route precedence. Capability predicates own adapter and scope checks. */
 export declare function selectPrimaryWakeRoute(input: {
     readonly boundary: WakeBoundary;
     readonly env: NodeJS.ProcessEnv;
@@ -33,12 +32,25 @@ export declare function upsertWakeRoute(route: Omit<WakeRoute, 'updatedAt'>, opt
     at?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<void>;
-export declare function publishWakeRoute(artifact: import('./ports.js').SquareArtifactPort, route: Omit<WakeRoute, 'updatedAt'>, opts?: {
+export type RouteEpoch = {
+    readonly epoch?: number;
+};
+export declare function applyWakeRouteToState(state: import('./model.js').SquareState, route: Omit<WakeRoute, 'updatedAt'> & RouteEpoch, at?: number): void;
+export declare function dropSessionWakeRoutesFromState(state: import('./model.js').SquareState, location: string, sessionId: string): void;
+export declare function dropParticipantWakeRoutesFromState(state: import('./model.js').SquareState, location: string, participant: string): void;
+export declare function sessionOwnsParticipantRoutes(state: import('./model.js').SquareState, location: string, participant: string, sessionId: string): boolean;
+export declare function sessionCanEndParticipant(state: import('./model.js').SquareState, location: string, participant: string, sessionId: string, currentSessionId?: string): boolean;
+export declare function publishWakeRoute(artifact: import('./ports.js').SquareArtifactPort, route: Omit<WakeRoute, 'updatedAt'> & RouteEpoch, opts?: {
     at?: number;
+    requireCurrentSession?: boolean;
 }): Promise<void>;
 export declare function retireWakeRoute(route: WakeRoute, opts?: {
     at?: number;
     env?: NodeJS.ProcessEnv;
+    expectedEpoch?: number;
 }): Promise<void>;
-export declare function retireWakeRouteFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>): Promise<void>;
+export declare function retireWakeRouteFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'participant' | 'sessionId'>, opts?: {
+    readonly expectedEpoch?: number;
+}): Promise<void>;
+export declare function retireWakeRoutesForSessionFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'sessionId'>): Promise<void>;
 export declare function canonicalRouteLocation(location: string): Promise<string>;

package/dist/routes.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { nameKey } from './model.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
+import { isCurrentlyJoined } from './runtime.js';
 export { WAKE_ROUTE_KINDS } from './model.js';
 export const ROUTE_FRESH_MS = 24 * 60 * 60 * 1000;
 export async function defaultWakeRouteCapabilities(hostLedger) {
@@ -39,7 +40,6 @@ function nativeCandidate(boundary) {
         return { kind: 'pi-extension', address: { sessionId: boundary.sessionId } };
     return undefined;
 }
-/** Pure, ordered route precedence. Capability predicates own adapter and scope checks. */
 export function selectPrimaryWakeRoute(input) {
     const { boundary, env, capabilities } = input;
     const paseoAgentId = env.PASEO_AGENT_ID?.trim();
@@ -87,24 +87,84 @@ export async function upsertWakeRoute(route, opts = {}) {
     const location = await canonicalRouteLocation(route.location);
     await withArtifact(location, async (square) => publishWakeRoute(square.artifact, { ...route, location }, opts));
 }
+function sameRouteAddress(left, right) {
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length && leftKeys.every((key, index) => rightKeys[index] === key && left[key] === right[key]);
+}
+function canonicalRouteLocationSync(location) {
+    const absolute = path.resolve(location);
+    try {
+        return fs.realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+export function applyWakeRouteToState(state, route, at = Date.now()) {
+    const location = canonicalRouteLocationSync(route.location);
+    state.routes = [...(state.routes ?? []).filter((item) => {
+            const itemLocation = canonicalRouteLocationSync(item.location);
+            return !(itemLocation === location && routeIdentityKey(item, itemLocation) === routeIdentityKey(route, location));
+        }), { ...route, location, updatedAt: at }];
+}
+export function dropSessionWakeRoutesFromState(state, location, sessionId) {
+    const canonical = canonicalRouteLocationSync(location);
+    state.routes = (state.routes ?? []).filter((item) => !(item.sessionId === sessionId && canonicalRouteLocationSync(item.location) === canonical));
+}
+export function dropParticipantWakeRoutesFromState(state, location, participant) {
+    const canonical = canonicalRouteLocationSync(location);
+    state.routes = (state.routes ?? []).filter((item) => !(nameKey(item.participant) === nameKey(participant) && canonicalRouteLocationSync(item.location) === canonical));
+}
+export function sessionOwnsParticipantRoutes(state, location, participant, sessionId) {
+    const canonical = canonicalRouteLocationSync(location);
+    const owned = (state.routes ?? []).filter((item) => nameKey(item.participant) === nameKey(participant) && canonicalRouteLocationSync(item.location) === canonical);
+    return owned.length > 0 && owned.every((item) => item.sessionId === sessionId);
+}
+export function sessionCanEndParticipant(state, location, participant, sessionId, currentSessionId) {
+    const canonical = canonicalRouteLocationSync(location);
+    const owned = (state.routes ?? []).filter((item) => nameKey(item.participant) === nameKey(participant) && canonicalRouteLocationSync(item.location) === canonical);
+    if (owned.length === 0)
+        return currentSessionId === sessionId;
+    return owned.every((item) => item.sessionId === sessionId) && (currentSessionId === undefined || currentSessionId === sessionId);
+}
 export async function publishWakeRoute(artifact, route, opts = {}) {
     const location = await canonicalRouteLocation(route.location);
-    await artifact.transact((state) => ({ state: { ...state, routes: [...(state.routes ?? []).filter((item) => routeIdentityKey(item) !== routeIdentityKey({ ...route, location })), { ...route, location, participant: route.participant, updatedAt: opts.at ?? Date.now() }] }, result: undefined }));
+    const at = opts.at ?? Date.now();
+    await artifact.transact((state) => {
+        if (opts.requireCurrentSession) {
+            const participantRoutes = (state.routes ?? []).filter((item) => nameKey(item.participant) === nameKey(route.participant) && canonicalRouteLocationSync(item.location) === location);
+            if (!isCurrentlyJoined(state.acts, route.participant) || participantRoutes.some((item) => item.sessionId !== route.sessionId))
+                return { state, result: undefined };
+        }
+        const identity = routeIdentityKey({ ...route, location });
+        const matching = (state.routes ?? []).filter((item) => routeIdentityKey(item, canonicalRouteLocationSync(item.location)) === identity);
+        const existing = matching[0];
+        const existingEpoch = existing?.epoch;
+        const epochMatches = route.epoch === undefined ? existingEpoch === undefined : existingEpoch === route.epoch;
+        if (matching.length === 1 && existing !== undefined && existing.updatedAt > at - ROUTE_FRESH_MS && existing.kind === route.kind && existing.channel === route.channel && sameRouteAddress(existing.address, route.address) && epochMatches)
+            return { result: undefined };
+        return { state: { ...state, routes: [...(state.routes ?? []).filter((item) => routeIdentityKey(item, canonicalRouteLocationSync(item.location)) !== identity), { ...route, location, updatedAt: at }] }, result: undefined };
+    });
 }
 export async function retireWakeRoute(route, opts = {}) {
     const location = await canonicalRouteLocation(route.location);
-    await withArtifact(location, async (square) => retireWakeRouteFromArtifact(square.artifact, { ...route, location }));
+    await withArtifact(location, async (square) => retireWakeRouteFromArtifact(square.artifact, { ...route, location }, opts));
 }
-export async function retireWakeRouteFromArtifact(artifact, route) {
+export async function retireWakeRouteFromArtifact(artifact, route, opts = {}) {
     const location = await canonicalRouteLocation(route.location);
-    await artifact.transact((state) => ({ state: { ...state, routes: (state.routes ?? []).filter((item) => routeIdentityKey(item) !== routeIdentityKey({ ...route, location })) }, result: undefined }));
+    const target = routeIdentityKey({ ...route, location });
+    await artifact.transact((state) => ({ state: { ...state, routes: (state.routes ?? []).filter((item) => {
+                const itemLocation = canonicalRouteLocationSync(item.location);
+                if (routeIdentityKey(item, itemLocation) !== target)
+                    return true;
+                const itemEpoch = item.epoch;
+                return opts.expectedEpoch !== undefined && itemEpoch !== opts.expectedEpoch;
+            }) }, result: undefined }));
+}
+export async function retireWakeRoutesForSessionFromArtifact(artifact, route) {
+    await artifact.transact((state) => { dropSessionWakeRoutesFromState(state, route.location, route.sessionId); return { state, result: undefined }; });
 }
 export async function canonicalRouteLocation(location) {
-    const absolute = path.resolve(location);
-    try {
-        return await fs.promises.realpath(absolute);
-    }
-    catch {
-        return absolute;
-    }
+    return canonicalRouteLocationSync(location);
 }

package/dist/runtime.d.ts

@@ -5,7 +5,6 @@ export declare const SLEEP_MS: number;
 export declare const STALE_MS: number;
 export declare const WATCH_STALE_MS: number;
 export declare const LOCK_RETRY_MS: number;
-export declare const LOCK_STALE_MS: number;
 export declare const THROTTLE_WINDOW_MS: number;
 export declare const UNREAD_BLOCK_GRACE_MS: number;
 export declare function nowMs(): number;

package/dist/runtime.js

@@ -38,7 +38,6 @@ export const SLEEP_MS = parseIntegerEnvAlias('SQUARE_WATCH_POLL_MS', ['SQUARE_SL
 export const STALE_MS = parseIntegerEnvAlias('SQUARE_WATCH_QUIET_MS', ['SQUARE_STALE_MS'], scaledMs(WATCH_HEARTBEAT_MS, parseScaleEnv('SQUARE_WATCH_QUIET_SCALE', 5)));
 export const WATCH_STALE_MS = parseIntegerEnv('SQUARE_WATCH_STALE_MS', scaledMs(WATCH_HEARTBEAT_MS, parseScaleEnv('SQUARE_WATCH_STALE_SCALE', 3)));
 export const LOCK_RETRY_MS = parseIntegerEnv('SQUARE_LOCK_RETRY_MS', 25);
-export const LOCK_STALE_MS = parseIntegerEnv('SQUARE_LOCK_STALE_MS', 30000);
 export const THROTTLE_WINDOW_MS = parseIntegerEnv('SQUARE_THROTTLE_WINDOW_MS', 60000);
 export const UNREAD_BLOCK_GRACE_MS = parseIntegerEnv('SQUARE_UNREAD_BLOCK_GRACE_MS', 90000);
 export function nowMs() {

package/dist/square-actions.d.ts

@@ -1,8 +1,7 @@
 import { type SquareState } from './model.js';
 import type { HostLedgerPort, SquareArtifactPort } from './ports.js';
-import type { Activity, ExpressOptions, ExpressResult } from './square-facade.js';
+import type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, OwnershipFenceOptions } from './square-facade.js';
 import { type CatchProjection } from './catch-decisions.js';
-import type { CatchOptions, CatchResult } from './square-facade.js';
 export interface OperationContext {
     readonly artifact: SquareArtifactPort;
     readonly clock: () => number;
@@ -11,15 +10,17 @@ export interface OperationContext {
     readonly wakeTransport?: import('./ports.js').WakeTransportPort;
     readonly env?: NodeJS.ProcessEnv;
 }
+export type { OwnershipFenceOptions };
 export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, project?: (state: SquareState) => CatchProjection): Promise<CatchResult>;
 export declare function join(square: OperationContext, name: string): Promise<{
     readonly name: string;
     readonly activity: Activity | null;
 }>;
 /** End the standing participant and immediately let the caller reclaim the name. */
-export declare function takeover(square: OperationContext, name: string): Promise<{
+export declare function takeover(square: OperationContext, name: string, _oldSessionIds?: readonly string[]): Promise<{
     readonly name: string;
     readonly activities: readonly Activity[];
+    readonly epoch?: number;
 }>;
 export declare function implicitJoin(square: OperationContext, name: string): Promise<{
     readonly name: string;
@@ -33,6 +34,8 @@ export interface ListenerChangeResult {
 export declare function listen(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
 export declare function ignore(square: OperationContext, actor: string, target: string): Promise<ListenerChangeResult>;
 export declare function listening(square: OperationContext, actor: string): Promise<readonly string[]>;
-export declare function done(square: OperationContext, name: string, body?: string): Promise<ExpressResult>;
+export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions): Promise<ExpressResult>;
+/** SessionEnd retires the ended session's routes even when its presence row is gone. */
+export declare function endOwnedSession(square: OperationContext, name: string, sessionId: string, expectedEpoch?: number): Promise<ExpressResult | null>;
 export declare function hold(square: OperationContext, name: string, reason?: string): Promise<ExpressResult>;
 export declare function resume(square: OperationContext, name: string): Promise<ExpressResult>;