@astrosheep/square 0.3.61 → 0.3.62

package/dist/notifications.d.ts

@@ -12,6 +12,7 @@ export declare function hasDeliveredNotification(squarePath: string, name: strin
 export declare function hasAttentionNotification(squarePath: string, name: string, ref: number | ActivityId, env?: NodeJS.ProcessEnv): Promise<boolean>;
 export declare function waitForDeliveredNotification(squarePath: string, name: string, ref: number | ActivityId, opts?: {
     timeoutMs?: number;
+    signal?: AbortSignal;
 }): Promise<boolean>;
 interface ProcessNotificationOptions {
     adapters?: WakeAdapter[];

package/dist/notifications.js

@@ -1,12 +1,12 @@
-import { setTimeout as sleep } from 'node:timers/promises';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import path from 'node:path';
 import fs from 'node:fs';
 import { planActNotifications, } from './delivery.js';
 import { SquareError } from './model.js';
-import { SLEEP_MS, matchesMentionTarget } from './runtime.js';
+import { matchesMentionTarget } from './runtime.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { displayAttentionPath } from './attention-presentation.js';
-import { openSquare } from './square-file-adapter.js';
+import { openSquare, observeSquareChanges } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { notificationDelivered, resolveParticipant } from './views.js';
 import { deliverPending, observeSquare, sweepPending, sweepPendingFromState } from './delivery-operations.js';
@@ -63,8 +63,8 @@ export async function hasAttentionNotification(squarePath, name, ref, env = proc
         const index = notificationIndex(ref);
         if (await notificationDelivered(square, recipient, index))
             return true;
-        const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-        const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+        const root = hostLedgerRoot(env);
+        const hostLedger = createHostLedgerPort({ rootPath: root });
         return (await projectPresentationEvidence({ hostLedger, location: squarePath, participant: recipient, activity: formatActivityId(index), now: Date.now() })).some((row) => row.outcome === 'presented');
     }
     finally {
@@ -73,12 +73,20 @@ export async function hasAttentionNotification(squarePath, name, ref, env = proc
 }
 export async function waitForDeliveredNotification(squarePath, name, ref, opts = {}) {
     const deadline = Date.now() + (opts.timeoutMs ?? 30000);
-    while (Date.now() <= deadline) {
-        if (await hasDeliveredNotification(squarePath, name, ref))
-            return true;
-        await sleep(Math.min(SLEEP_MS, Math.max(1, deadline - Date.now())));
+    const observer = await observeSquareChanges(squarePath);
+    try {
+        while (Date.now() <= deadline) {
+            const baseline = await observer.read(opts.signal);
+            if (await hasDeliveredNotification(squarePath, name, ref))
+                return true;
+            if (!await observer.changed(baseline, Math.max(0, deadline - Date.now()), opts.signal))
+                return false;
+        }
+        return false;
+    }
+    finally {
+        observer.close();
     }
-    return false;
 }
 export async function defaultWakeAdapters() {
     const adapters = [];
@@ -188,10 +196,9 @@ export function createWakeTransport(adapters, hostLedger, clock) {
 export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
     const env = opts.env ?? process.env;
     const now = opts.now ?? Date.now;
-    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
+    const ledgerRoot = hostLedgerRoot(env);
     const hostLedger = createHostLedgerPort({
-        userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot,
-        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot,
+        rootPath: ledgerRoot,
     });
     const square = await openSquare(squarePath, { clock: now, hostLedger, env });
     try {
@@ -213,11 +220,11 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
     const remainingMs = () => Math.max(0, deadline - Date.now());
     if (remainingMs() === 0 || signal?.aborted)
         return;
-    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? root, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root, readableScopes: ['user'], writableScope: 'user' });
+    const root = hostLedgerRoot(env);
+    const hostLedger = createHostLedgerPort({ rootPath: root });
     let indexed = [];
     try {
-        indexed = await hostLedger.listPresence({ scopes: ['user'], now: Date.now() });
+        indexed = await hostLedger.listPresence({ now: Date.now() });
     }
     catch { /* capability is best effort */ }
     const paths = new Set(indexed.map((binding) => binding.location));
@@ -237,7 +244,6 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
         try {
             const square = await openSquare(squarePath, { hostLedger, env, signal });
             try {
-                await hostLedger.reconcileBinding({ artifact: square.artifact, scopes: ['user'], now: Date.now() }).catch(() => undefined);
                 if (remainingMs() === 0 || signal?.aborted)
                     break;
                 const limit = Number.parseInt(env.SQUARE_NOTIFY_SWEEP_LIMIT ?? '8', 10);
@@ -262,7 +268,7 @@ export async function sweepPrivilegedPending(cwd, env = process.env, suppliedAda
 }
 /** Select sweep candidates from one frozen snapshot and one delivery replay. */
 export async function pendingNotificationSweepFromState(squarePath, state, now, env, limit, deriveDelivery) {
-    const ledger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER, writableScope: 'user', readableScopes: ['user'] });
+    const ledger = createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
     return sweepPendingFromState({ state, hostLedger: ledger, location: squarePath, now, graceMs: wakeGraceMs(env), limit, deriveDelivery });
 }
 /** Select old pending attention at a bounded action boundary for an explicit executor. */
@@ -272,8 +278,7 @@ export async function sweepPendingNotifications(squarePath, opts = {}) {
         return [];
     const now = opts.now ?? Date.now();
     const limit = opts.limit ?? 8;
-    const ledgerRoot = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    const hostLedger = createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot, localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot });
+    const hostLedger = createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
     const square = await openSquare(squarePath, { clock: () => now, hostLedger, env });
     let selected;
     try {

package/dist/participant-host.js

@@ -53,7 +53,7 @@ export async function ensureLocalPresence(context, participant, epoch) {
     const now = context.clock();
     // Semantic publish: an unexpired presence row already stands when it carries the same owner epoch.
     try {
-        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, scopes: ['local'], now });
+        const existing = await context.hostLedger.listPresence({ location: context.location, participant, session: identity.session, now });
         if (existing.some((row) => row.channel === identity.channel
             && now - (row.updatedAt ?? 0) < ROUTE_FRESH_MS
             && (ownerEpoch === undefined || row.epoch === ownerEpoch)))
@@ -68,7 +68,7 @@ export async function ensureLocalPresence(context, participant, epoch) {
         // Presence rows are host-ledger wall-time evidence; the square clock belongs to artifact activities.
         updatedAt: Date.now(),
         ...(ownerEpoch === undefined || ownerEpoch <= 0 ? {} : { epoch: ownerEpoch }),
-    }, 'local').catch((error) => ({
+    }).catch((error) => ({
         status: 'degraded',
         record: { location: context.location, participant, session: identity.session, channel: identity.channel },
         error,

package/dist/ports.d.ts

@@ -1,6 +1,6 @@
 import type { InboxNotification, SquareState, StoredAct, WakeRoute, WatchLease } from './model.js';
 import type { PlannedNotification } from './delivery.js';
-export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, HostLedgerScope, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, ReconcileBindingInput as HostLedgerReconcileBindingInput, ReconcileBindingResult, } from './host-ledger.js';
+export type { ClaimResult, EvidenceClaim, EvidenceRelease, EvidenceGc, EvidenceLookup, EvidenceRecord, HostLedgerPort, PresenceKey, PresenceLookup, PresenceRecord, PresenceClaimResult, PresenceChannel, PresenceResult, } from './host-ledger.js';
 import type { HostLedgerPort } from './host-ledger.js';
 /** Atomic artifact access. Never exposes framing, compression, locks, or storage schema. */
 export interface SquareArtifactPort {
@@ -12,7 +12,7 @@ export interface SquareArtifactPort {
         state?: SquareState;
         result: R;
     }, signal?: AbortSignal): Promise<R>;
-    changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
+    changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }
 /** Capability-neutral wake transport. Unused by this Contract's activity operations. */
@@ -101,13 +101,6 @@ export interface ObserveSquareInput {
     readonly location?: string;
     readonly now?: number;
 }
-export interface ReconcileBindingInput {
-    readonly artifact: SquareArtifactPort;
-    readonly hostLedger: HostLedgerPort;
-    readonly location?: string;
-    readonly scopes?: readonly import('./host-ledger.js').HostLedgerScope[];
-    readonly now?: number;
-}
 export interface DeliveryResult {
     readonly attempted: number;
     readonly accepted: number;

package/dist/presentation.d.ts

@@ -21,6 +21,7 @@ interface ActivityLimitOptions extends ParticipantOutputOptions {
     draftPath?: string;
 }
 interface ActivityBlockedOptions extends ParticipantOutputOptions {
+    retryCommand: string;
     forceCommand: string;
     activitySummaries: UnreadActivitySummary[];
     unreadRoomChanges: RoomChangeAct[];
@@ -29,10 +30,12 @@ interface ActivityBlockedOptions extends ParticipantOutputOptions {
 interface ExpressWaitingOptions {
     reason: 'throttled' | 'held';
     delayMs?: number;
+    holder?: string;
+    holdReason?: string;
 }
 interface ExpressNoWaitOptions extends ParticipantOutputOptions {
     reason: 'throttled' | 'held';
-    forceCommand: string;
+    retryCommand: string;
     delayMs?: number;
     holdReason?: string;
     draftPath?: string;
@@ -58,6 +61,8 @@ export declare function commandPrefix(squarePath: string): string;
 export declare function participantCommandPrefix(squarePath: string, name: string): string;
 /** Blocked actions end with a full copy-pasteable recovery command. */
 export declare function joinRecoveryCommand(squarePath: string, name: string): string;
+/** Taking a name is an explicit recovery choice, never an automatic retry. */
+export declare function takeoverRecoveryLines(squarePath: string, name: string): string[];
 export declare function participantsRecoveryCommand(squarePath: string): string;
 export declare function renderPresenceLines(participants: ParticipantStatus[], now: number, limit?: number): string[];
 export declare function expressHintLine(ownActivityCount: number): string | undefined;
@@ -85,6 +90,12 @@ export declare function renderAmbientEvent(event: StoredAct, viewer: string, opt
 }): string;
 export declare function renderPendingFeed(history: StoredAct[], publicItems: PublicAct[], roomChanges: RoomChangeAct[], viewer: string | undefined, squareState: SquareState): string;
 export declare function renderActivityBlocked(opts: ActivityBlockedOptions): string;
+/** An indeterminate or already-committed send only points to inspection, never resend. */
+export declare function renderActivityUncertain(opts: ParticipantOutputOptions & {
+    draftPath: string;
+    landedId?: string;
+    detail?: string;
+}): string;
 export declare function renderExpressWaiting(opts: ExpressWaitingOptions): string;
 export declare function renderExpressNoWait(opts: ExpressNoWaitOptions): string;
 export declare function renderPublicTail(squareState: SquareState, events: StoredAct[], lastN: number | null | undefined, now?: number, viewer?: string): string;

package/dist/presentation.js

@@ -5,7 +5,7 @@ import { participantIdentity } from './participant-identity.js';
 export { participantIdentity } from './participant-identity.js';
 import { audienceIncludes, audienceOf, MAX_IDENTITY_SET_SIZE, replayLandedAudiences } from './square-core.js';
 import { perceiveActivity } from './delivery.js';
-import { actId, presenceAnchor, publicActs, rosterNames, sayNumberFor } from './runtime.js';
+import { actId, presenceAnchor, publicActs, rosterNames, sayNumberFor, HELD_WAIT_BUDGET_MS } from './runtime.js';
 import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { compareParticipantActivity } from './decisions.js';
 import { grepSnippet } from './search.js';
@@ -55,6 +55,13 @@ export function participantCommandPrefix(squarePath, name) {
 export function joinRecoveryCommand(squarePath, name) {
     return `${participantCommandPrefix(squarePath, name)} join`;
 }
+/** Taking a name is an explicit recovery choice, never an automatic retry. */
+export function takeoverRecoveryLines(squarePath, name) {
+    return [
+        'If this is your name to reclaim, --kick banishes the one standing here so you can step in:',
+        `${participantCommandPrefix(squarePath, name)} join --kick`,
+    ];
+}
 export function participantsRecoveryCommand(squarePath) {
     return `${commandPrefix(squarePath)} participants`;
 }
@@ -281,19 +288,42 @@ export function renderActivityBlocked(opts) {
         ...renderUnreadSummary({ activitySummaries: opts.activitySummaries, roomChanges: opts.unreadRoomChanges, viewer: opts.name }),
         ...draftSavedLines(opts.draftPath),
         `${readNowCommand}`,
-        '  take it in, then express again',
-        `${withDraftInput(opts.forceCommand, opts.draftPath)}`,
-        '  only if you truly mean to express over unread activity',
+        '  · take it in, then retry:',
+        withDraftInput(opts.retryCommand, opts.draftPath),
+        '  · optional: express over unread activity with --force:',
+        withDraftInput(opts.forceCommand, opts.draftPath),
     ].join('\n'), { participantCount: opts.participantCount, held: opts.held });
 }
+/** An indeterminate or already-committed send only points to inspection, never resend. */
+export function renderActivityUncertain(opts) {
+    return formatRefusal(opts.squarePath, [
+        opts.landedId === undefined
+            ? '✕ your activity may have landed — check history before sending again'
+            : `✕ your activity landed · ${opts.landedId} — the confirmation could not finish`,
+        ...(opts.detail === undefined ? [] : [`  · ${truncateExternalDiagnostic(opts.detail)}`]),
+        ...draftSavedLines(opts.draftPath),
+        '  · the draft is a saved copy; sending it again could repeat your activity',
+        `${commandPrefix(opts.squarePath)} history${opts.landedId === undefined ? ' --limit 10' : ` --at ${opts.landedId}`} --no-truncate`,
+    ], opts);
+}
 export function renderExpressWaiting(opts) {
     if (opts.reason === 'throttled') {
-        return ['✕ the square is packed', `  · your activity is waiting · next opening in ${formatDuration(opts.delayMs)}`].join('\n');
+        return [
+            '✕ the square is packed',
+            `  · your activity is waiting · next opening in ${formatDuration(opts.delayMs)}`,
+            '  · --no-wait saves a draft and returns now',
+        ].join('\n');
     }
-    return ["✕ your activity doesn't land — a hand is raised", '  · your activity is waiting'].join('\n');
+    const holder = opts.holder === undefined ? 'a hand is raised' : `${participantIdentity(opts.holder)} raised a hand`;
+    return [
+        `✕ your activity doesn't land — ${holder}`,
+        ...(opts.holdReason === undefined ? [] : [`  · ${opts.holdReason}`]),
+        `  · your activity is waiting — after ${formatDuration(HELD_WAIT_BUDGET_MS)} it saves a draft and stops`,
+        '  · --no-wait saves a draft and returns now',
+    ].join('\n');
 }
 export function renderExpressNoWait(opts) {
-    const retryCommand = opts.forceCommand;
+    const retryCommand = opts.retryCommand;
     const lines = opts.reason === 'throttled'
         ? [
             `${style('blocked', '✕')} the square is packed`,
@@ -411,12 +441,12 @@ export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squa
 }
 function renderActivityLimitBody(opts) {
     const countText = opts.count !== undefined && opts.hardCap !== undefined ? ` (${opts.count}/${opts.hardCap})` : '';
-    const doneCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} done -`;
+    const doneCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} done`;
     return [
         `${style('blocked', '✕')} your activity doesn't land — the cap is reached${countText}`,
         ...draftSavedLines(opts.draftPath),
-        `${withDraftInput(doneCommand, opts.draftPath)}`,
-        '  your draft becomes your final note',
+        '  · your draft stays unsent; done only steps out',
+        doneCommand,
     ].join('\n');
 }
 export function renderActivityLimit(opts) {
@@ -462,9 +492,9 @@ export function renderWatchStatus(opts) {
             ].join('\n');
         }
         case 'quorum':
-            return [`${style('release', '✓')} everyone else has left — the square is yours alone`, `${participantCommandPrefix(opts.squarePath, opts.name)} done -`].join('\n');
+            return [`${style('release', '✓')} everyone else has left — the square is yours alone`, `${participantCommandPrefix(opts.squarePath, opts.name)} done`].join('\n');
         case 'capped':
-            return [`${style('blocked', '✕')} nothing left in you — the cap is reached`, `${participantCommandPrefix(opts.squarePath, opts.name)} done -`].join('\n');
+            return [`${style('blocked', '✕')} nothing left in you — the cap is reached`, `${participantCommandPrefix(opts.squarePath, opts.name)} done`].join('\n');
     }
 }
 function renderRoomChanges(changes) {

package/dist/presented.js

@@ -1,9 +1,10 @@
 import os from 'node:os';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import path from 'node:path';
 import { canonicalSquarePath } from './registry.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { formatActivityId } from './square-core.js';
 import { projectPresentationEvidence } from './square-projections.js';
 export function presentedPath(env = process.env) { return env.SQUARE_PRESENTED || path.join(os.homedir(), '.square', 'presented.ndjsonl'); }
-function evidence(env = process.env) { const file = presentedPath(env); return createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? path.dirname(file), writableScope: 'user', readableScopes: ['user'] }); }
+function evidence(env = process.env) { const file = presentedPath(env); return createHostLedgerPort({ rootPath: hostLedgerRoot(env) }); }
 export async function hasPresentedForOwner(sessionId, squarePath, name, actIndex, env = process.env, now = Date.now()) { const resolved = await canonicalSquarePath(squarePath); return (await projectPresentationEvidence({ hostLedger: evidence(env), now, location: resolved, participant: name, sessionId, activity: formatActivityId(actIndex) })).some((row) => row.outcome === 'presented'); }

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 /** Machine-local participant discovery cache. */
 import { type StoredAct } from './model.js';
-import type { PresenceRecord } from './host-ledger.js';
+import type { HostLedgerPort, PresenceRecord } from './host-ledger.js';
 export type SessionChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo' | 'unknown';
 export interface RegistryBinding {
     sessionId: string;
@@ -26,7 +26,7 @@ export declare function registryPath(env?: NodeJS.ProcessEnv): string;
 export declare function canonicalSquarePath(squarePath: string): Promise<string>;
 export declare function presenceEpoch(record: PresenceWithEpoch | undefined): number;
 /** Runs `fn` inside the ownership claim critical section, under the same lock as claims and finalize. */
-export declare function withOwnershipClaimLock<T>(env: NodeJS.ProcessEnv, fn: () => Promise<T>): Promise<T>;
+export declare function withOwnershipClaimLock<T>(env: NodeJS.ProcessEnv, fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
 export declare function recordJoin(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): Promise<void>;
 export declare function recordDone(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): Promise<void>;
 export declare function readActiveBindings(now?: number, env?: NodeJS.ProcessEnv): Promise<RegistryBinding[]>;
@@ -45,6 +45,7 @@ export type CurrentParticipantBinding = Readonly<{
 }>;
 export type OwnershipClaim = {
     readonly status: 'acquired' | 'owned';
+    readonly record: PresenceWithEpoch;
     readonly sessionId: string;
     readonly epoch: number;
 } | undefined;
@@ -63,7 +64,8 @@ export type TakeoverRunResult<T> = {
 };
 export declare function readParticipantOwner(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<RegistryBinding | undefined>;
 export declare function sessionOwnsParticipant(squarePath: string, name: string, sessionId: string, env?: NodeJS.ProcessEnv, expectedEpoch?: number): Promise<boolean>;
-export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<OwnershipClaim>;
+export declare function releaseSessionParticipantClaim(squarePath: string, name: string, env: NodeJS.ProcessEnv, claim: OwnershipClaim): Promise<void>;
+export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<OwnershipClaim>;
 /**
  * Fenced takeover: the ownership claim and the lifecycle run as one critical section under the
  * presence-claim lock, so no second takeover can interleave between claim and commit. The claim
@@ -76,7 +78,7 @@ export declare function claimSessionParticipant(squarePath: string, name: string
 export declare function claimSessionTakeover<T>(squarePath: string, name: string, env: NodeJS.ProcessEnv | undefined, opts: {
     readonly expectedEpoch?: number;
     readonly expectedSession?: string;
-} | undefined, lifecycle: (claim: TakeoverClaimToken) => Promise<T>): Promise<TakeoverRunResult<T>>;
+} | undefined, lifecycle: (claim: TakeoverClaimToken) => Promise<T>, signal?: AbortSignal): Promise<TakeoverRunResult<T>>;
 export declare function releaseSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function bindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<CurrentParticipantBinding>;
 export declare function unbindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
@@ -97,4 +99,6 @@ export declare function recordLocalJoin(name: string, squarePath: string, env?:
 export declare function recordLocalDone(name: string, squarePath: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function recordSessionJoin(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function recordSessionDone(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** Bind the host ledger to the caller's captured environment. */
+export declare function hostLedgerForEnv(env?: NodeJS.ProcessEnv): HostLedgerPort;
 export {};

package/dist/registry.js

@@ -1,11 +1,11 @@
 /** 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';
+import { hostLedgerRoot } from './host-ledger-root.js';
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const PRESENCE_CLAIM_LOCK = { retryMs: 10 };
 const LOCAL_SESSION_SOURCES = [
@@ -14,23 +14,15 @@ const LOCAL_SESSION_SOURCES = [
     { variable: 'OPENCODE_SESSION_ID', channel: 'opencode' },
     { variable: 'PI_SESSION_ID', channel: 'pi' },
 ];
-export function registryPath(env = process.env) { return env.SQUARE_REGISTRY || path.join(homedir(), '.square', 'sessions.ndjsonl'); }
+export function registryPath(env = process.env) { return env.SQUARE_REGISTRY || path.join(hostLedgerRoot(env), '..', 'sessions.ndjsonl'); }
 export async function canonicalSquarePath(squarePath) { const absolute = path.resolve(squarePath); try {
     return await (await import('node:fs/promises')).realpath(absolute);
 }
 catch {
     return absolute;
 } }
-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 });
-}
+function ledgerRoot(env) { return hostLedgerRoot(env); }
+function ledger(env) { return createHostLedgerPort({ rootPath: ledgerRoot(env) }); }
 export function presenceEpoch(record) {
     return typeof record?.epoch === 'number' && Number.isSafeInteger(record.epoch) && record.epoch > 0 ? record.epoch : 0;
 }
@@ -47,22 +39,21 @@ function toBinding(record) {
     };
 }
 function presenceClaimLockPath(env) {
-    return path.join(ledgerRoot(env).userPath, 'presence-claim.lock');
+    return path.join(ledgerRoot(env), '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);
+export async function withOwnershipClaimLock(env, fn, signal) {
+    return withFileLock(presenceClaimLockPath(env), { ...PRESENCE_CLAIM_LOCK, signal }, 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)
+async function activeBindings(now, env) { return (await ledger(env).listPresence({ now })).map(toBinding).sort((a, b) => b.updatedAt - a.updatedAt); }
+async function writePresence(sessionId, name, squarePath, options, done) { if (!sessionId || !name || !squarePath)
+    return; const env = options.env ?? process.env; const channel = options.channel ?? 'unknown'; const port = ledger(env); const location = await canonicalSquarePath(squarePath); if (done)
     await port.removePresence({ location, participant: name, session: sessionId, channel });
 else
     await port.ensurePresence({ location, participant: name, session: sessionId, channel, updatedAt: options.at ?? Date.now() }); }
 export function recordJoin(sessionId, name, squarePath, options = {}) { return writePresence(sessionId, name, squarePath, options, false); }
 export async function recordDone(sessionId, name, squarePath, options = {}) {
     await writePresence(sessionId, name, squarePath, options, true);
-    await writePresence(sessionId, name, squarePath, options, true, 'user');
 }
 export async function readActiveBindings(now = Date.now(), env = process.env) { try {
     return await activeBindings(now, env);
@@ -87,10 +78,18 @@ export async function sessionOwnsParticipant(squarePath, name, sessionId, env =
         return false;
     return expectedEpoch === undefined || owner.epoch === expectedEpoch;
 }
-export async function claimSessionParticipant(squarePath, name, env = process.env) {
+export async function releaseSessionParticipantClaim(squarePath, name, env, claim) {
+    if (claim?.status !== 'acquired')
+        return;
+    const port = ledger(env);
+    await port.removePresenceIfUnchanged(claim.record);
+}
+export async function claimSessionParticipant(squarePath, name, env = process.env, signal) {
     const identity = localSessionIdentities(env)[0];
     if (identity === undefined)
         return undefined;
+    if (signal?.aborted)
+        throw signal.reason ?? new Error('Operation aborted');
     const location = await canonicalSquarePath(squarePath);
     const result = await ledger(env).claimPresence({
         location,
@@ -99,13 +98,13 @@ export async function claimSessionParticipant(squarePath, name, env = process.en
         channel: identity.channel,
         updatedAt: Date.now(),
         epoch: 1,
-    }, 'local');
+    }, signal);
     if (result.status === 'busy')
         throw new SquareError('already_joined', `✕ ${name} already stands here — another session holds the name`);
     if (result.status === 'degraded')
         throw result.error;
-    const epoch = presenceEpoch(result.record) || (result.status === 'acquired' ? 1 : 0);
-    return { status: result.status, sessionId: identity.sessionId, epoch };
+    const record = result.record;
+    return { status: result.status, record, sessionId: record.session, epoch: presenceEpoch(record) };
 }
 /**
  * Fenced takeover: the ownership claim and the lifecycle run as one critical section under the
@@ -116,18 +115,15 @@ export async function claimSessionParticipant(squarePath, name, env = process.en
  * 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) {
+export async function claimSessionTakeover(squarePath, name, env = process.env, opts = {}, lifecycle, signal) {
     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 () => {
+    return withFileLock(presenceClaimLockPath(env), { ...PRESENCE_CLAIM_LOCK, signal }, 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]
+        const standing = await port.listPresence({ location, participant: name });
+        const owner = standing
             .map((row) => toBinding(row))
             .sort((left, right) => right.epoch - left.epoch || right.updatedAt - left.updatedAt)[0];
         const currentEpoch = owner?.epoch ?? 0;
@@ -147,50 +143,21 @@ export async function claimSessionTakeover(squarePath, name, env = process.env,
             // 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);
-                }
+            const tokenRows = await ledger(env).listPresence({ location, participant: name, session: identity.sessionId });
+            for (const row of tokenRows) {
+                if (row.channel === identity.channel && presenceEpoch(row) === epoch)
+                    await ledger(env).removePresence({ location: row.location, participant: row.participant, session: row.session, channel: row.channel });
             }
+            for (const row of standing)
+                await ledger(env).ensurePresence(row);
             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
+        // the claim epoch 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);
-        }
+        for (const row of standing)
+            await ledger(env).removePresence({ location: row.location, participant: row.participant, session: row.session, channel: row.channel });
+        await ledger(env).ensurePresence({ location, participant: name, session: identity.sessionId, channel: identity.channel, updatedAt: Date.now(), epoch });
         return { status: 'acquired', sessionId: identity.sessionId, epoch, result };
     });
 }
@@ -226,9 +193,9 @@ export async function recordLocalJoin(name, squarePath, env = process.env) { con
 } }
 export async function recordLocalDone(name, squarePath, env = process.env) { const at = Date.now(); const identities = new Set(localSessionIdentities(env).map((identity) => identity.sessionId)); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => identities.has(binding.sessionId)); for (const binding of current)
     await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }); }
-export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => binding.sessionId === sessionId); for (const binding of current) {
-    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env });
-    await writePresence(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }, true, 'user');
-} await recordJoin(sessionId, name, squarePath, { channel, at, env }); await writePresence(sessionId, name, squarePath, { channel, at, env }, false, 'user'); return sessionId; }
+export async function recordSessionJoin(sessionId, name, squarePath, channel, env = process.env) { const at = Date.now(); const current = (await lookupParticipant(squarePath, name, at, env)).filter((binding) => binding.sessionId === sessionId); for (const binding of current)
+    await recordDone(binding.sessionId, binding.name, binding.squarePath, { channel: binding.channel, at, env }); await recordJoin(sessionId, name, squarePath, { channel, at, env }); return sessionId; }
 export async function recordSessionDone(sessionId, name, squarePath, channel, env = process.env) { const canonicalPath = await canonicalSquarePath(squarePath); const binding = (await lookupSessionBindings(sessionId, Date.now(), env)).find((item) => item.squarePath === canonicalPath && sameName(item.name, name) && item.channel === channel); if (binding === undefined)
-    return false; const options = { channel, at: Date.now(), env }; await recordDone(sessionId, binding.name, binding.squarePath, options); await writePresence(sessionId, binding.name, binding.squarePath, options, true, 'user'); return true; }
+    return false; const options = { channel, at: Date.now(), env }; await recordDone(sessionId, binding.name, binding.squarePath, options); return true; }
+/** Bind the host ledger to the caller's captured environment. */
+export function hostLedgerForEnv(env = process.env) { return ledger(env); }

package/dist/routes.d.ts

@@ -36,7 +36,22 @@ 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 dropSessionWakeRoutesFromState(state: import('./model.js').SquareState, location: string, sessionId: string, expectedEpoch?: number): void;
+/**
+ * Drop one ended session's routes at a location, atomically with the lifecycle decide.
+ *
+ * A route survives when the ending transaction did not commit `done` and this session
+ * still holds the sole live presence for its participant — an in-flight same-session
+ * rejoin. `liveParticipants === undefined` means the ledger could not be read, so
+ * nothing is dropped on suspicion. An explicit epoch fence additionally keeps routes
+ * published by a later generation.
+ */
+export declare function dropEndedSessionWakeRoutesFromState(state: import('./model.js').SquareState, location: string, sessionId: string, opts: {
+    readonly expectedEpoch?: number;
+    readonly liveParticipants?: ReadonlySet<string>;
+    readonly force: boolean;
+    readonly participant?: 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;
@@ -52,5 +67,7 @@ export declare function retireWakeRoute(route: WakeRoute, opts?: {
 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 retireWakeRoutesForSessionFromArtifact(artifact: import('./ports.js').SquareArtifactPort, route: Pick<WakeRoute, 'location' | 'sessionId'>, opts?: {
+    readonly expectedEpoch?: number;
+}): Promise<void>;
 export declare function canonicalRouteLocation(location: string): Promise<string>;