@astrosheep/square 0.3.58 → 0.3.62

package/dist/square-wiring.js

@@ -1,11 +1,10 @@
 import { closeOpenSquare } from './open-square.js';
 import { buildMemorySquare, buildSquare, openSquare } from './square-file-adapter.js';
-import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, } from './square-actions.js';
+import { catchUp, done, endOwnedSession, express, hold, ignore, implicitJoin, join, takeover, listen, listening, resume, retireEndedSessionRoutes, } from './square-actions.js';
 import { markBoundarySeen as recordBoundarySeen } from './presence.js';
 import { history, participantHistory, participants, resolveParticipant, snapshot } from './views.js';
 import { currentParticipant } from './views.js';
 import { projectSessionBindings } from './square-projections.js';
-import { reconcileBinding as reconcileBindingOperation } from './delivery-operations.js';
 class ParticipantHandle {
     name;
     square;
@@ -15,32 +14,32 @@ class ParticipantHandle {
         this.square = square;
         this.context = context;
     }
-    express(body, options) {
-        return express(this.context, this.name, body, options);
+    express(body, options, control) {
+        return express(this.context, this.name, body, options, control);
     }
-    listen(target) {
-        return listen(this.context, this.name, target);
+    listen(target, control) {
+        return listen(this.context, this.name, target, control);
     }
-    ignore(target) {
-        return ignore(this.context, this.name, target);
+    ignore(target, control) {
+        return ignore(this.context, this.name, target, control);
     }
-    listening() {
-        return listening(this.context, this.name);
+    listening(control) {
+        return listening(this.context, this.name, control);
     }
-    catch(options) {
-        return catchUp(this.context, this.name, options);
+    catch(options, control) {
+        return catchUp(this.context, this.name, options, undefined, control);
     }
-    history(query) {
-        return participantHistory(this.square, this.name, query);
+    history(query, control) {
+        return participantHistory(this.square, this.name, query, control);
     }
-    hold(reason) {
-        return hold(this.context, this.name, reason);
+    hold(reason, control) {
+        return hold(this.context, this.name, reason, control);
     }
-    resume() {
-        return resume(this.context, this.name);
+    resume(control) {
+        return resume(this.context, this.name, control);
     }
-    done(body) {
-        return done(this.context, this.name, body);
+    done(body, control) {
+        return done(this.context, this.name, body, {}, control);
     }
 }
 export class Square {
@@ -61,27 +60,33 @@ export class Square {
     static inMemory(input) {
         return new Square('memory', buildMemorySquare(input));
     }
-    async join(name) {
-        const joined = await join(this.context, name);
+    async join(name, control) {
+        const joined = await join(this.context, name, control);
         return new ParticipantHandle(joined.name, this.square, this.context);
     }
-    async joinWithActivity(name) {
-        const joined = await join(this.context, name);
+    async joinWithActivity(name, control) {
+        const joined = await join(this.context, name, control);
         return { participant: new ParticipantHandle(joined.name, this.square, this.context), activity: joined.activity };
     }
-    async takeover(name) {
-        const result = await takeover(this.context, name);
-        return new ParticipantHandle(result.name, this.square, this.context);
+    async takeoverWithActivity(name, control) {
+        const result = await takeover(this.context, name, [], control);
+        return { participant: new ParticipantHandle(result.name, this.square, this.context), activities: result.activities };
     }
-    async implicitJoin(name) {
-        const joined = await implicitJoin(this.context, name);
+    async takeover(name, control) {
+        return (await this.takeoverWithActivity(name, control)).participant;
+    }
+    doneOwnedSession(name, body, expectedEpoch, control) {
+        return done(this.context, name, body, { expectedEpoch }, control);
+    }
+    async implicitJoin(name, control) {
+        const joined = await implicitJoin(this.context, name, control);
         return joined.state === 'done'
             ? { state: joined.state }
             : { state: joined.state, participant: new ParticipantHandle(joined.name, this.square, this.context) };
     }
     participants() { return participants(this.square); }
     snapshot() { return snapshot(this.square); }
-    history(query) { return history(this.square, query); }
+    history(query, control) { return history(this.square, query, control); }
     async recognize(env) {
         if (this.square.hostLedger === undefined)
             return null;
@@ -93,7 +98,6 @@ export class Square {
             hostLedger: this.square.hostLedger,
             location: this.square.location,
             sessionId,
-            scopes: ['user', 'local'],
         })))).flat();
         if (candidates.length !== 1)
             return null;
@@ -101,8 +105,8 @@ export class Square {
         return canonicalName === undefined ? null : new ParticipantHandle(canonicalName, this.square, this.context);
     }
     close() { return closeOpenSquare(this.square); }
-    reconcileBinding() { return reconcileBindingOperation({ artifact: this.square.artifact, hostLedger: this.square.hostLedger, location: this.location }); }
     endOwnedSession(name, sessionId, expectedEpoch) { return endOwnedSession(this.context, name, sessionId, expectedEpoch); }
+    retireEndedSessionRoutes(sessionId) { return retireEndedSessionRoutes(this.context, sessionId); }
 }
 export function markBoundarySeen(squarePath, name, actIndexes, at) {
     return recordBoundarySeen(squarePath, name, actIndexes, at);

package/dist/state-cell.d.ts

@@ -9,6 +9,6 @@ export interface StateCell {
         state: SquareState;
         version: number;
     }>;
-    changed(sinceVersion: number, timeoutMs: number): Promise<boolean>;
+    changed(sinceVersion: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
     close(): Promise<void>;
 }

package/dist/stream.js

@@ -1,10 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { once } from 'node:events';
-import { setTimeout as sleep } from 'node:timers/promises';
 import { quoteShell } from './presentation.js';
-import { SLEEP_MS } from './runtime.js';
-import { openSquare } from './square-file-adapter.js';
+import { openSquare, observeSquareChanges } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { streamProjection, streamTailProjection } from './views.js';
 async function writeNdjson(value) {
@@ -20,38 +18,44 @@ export async function cmdStreamNdjson(squarePath, recipient, start = { kind: 'ta
     }
     let cursor = start.kind === 'after' ? start.after : -1;
     let initial = start.kind === 'tail' ? start : undefined;
-    while (true) {
-        try {
-            const square = await openSquare(squarePath);
+    const observer = await observeSquareChanges(squarePath);
+    try {
+        while (true) {
+            const generation = observer.generation;
             try {
-                const projection = initial === undefined
-                    ? await streamProjection(square, cursor, recipient)
-                    : await streamTailProjection(square, initial.last, recipient);
-                for (const item of projection.activities) {
-                    await writeNdjson({
-                        seq: item.activity.index,
-                        square: squarePath,
-                        ...item.activity,
-                        ...(item.route === undefined ? {} : { route: item.route }),
-                    });
+                const baseline = await observer.read();
+                const square = await openSquare(squarePath);
+                let hasMore;
+                try {
+                    const projection = initial === undefined
+                        ? await streamProjection(square, cursor, recipient)
+                        : await streamTailProjection(square, initial.last, recipient);
+                    for (const item of projection.activities) {
+                        await writeNdjson({ seq: item.activity.index, square: squarePath, ...item.activity,
+                            ...(item.route === undefined ? {} : { route: item.route }) });
+                    }
+                    cursor = projection.cursor;
+                    initial = undefined;
+                    hasMore = projection.hasMore;
                 }
-                cursor = projection.cursor;
-                initial = undefined;
-                if (projection.hasMore)
-                    continue;
+                finally {
+                    await closeOpenSquare(square);
+                }
+                if (!hasMore)
+                    await observer.changed(baseline, Infinity);
             }
-            finally {
-                await closeOpenSquare(square);
+            catch {
+                // Repair/replacement is a storage hint, not a reason to scan history on a timer.
+                await observer.hinted(generation, Infinity);
             }
         }
-        catch {
-            // A concurrent artifact replacement is retried on the next poll.
-        }
-        await sleep(SLEEP_MS);
+    }
+    finally {
+        observer.close();
     }
 }
 export async function cmdStream(squarePath) {
     process.stderr.write('✕ interactive stream was removed\n');
-    process.stderr.write(`» square --location ${quoteShell(path.resolve(squarePath))} stream --ndjson\n`);
+    process.stderr.write(`square --location ${quoteShell(path.resolve(squarePath))} stream --ndjson\n`);
     process.exitCode = 2;
 }

package/dist/tty-style.d.ts

@@ -0,0 +1,7 @@
+export type StyleRole = 'blocked' | 'release' | 'changed' | 'dim' | 'match';
+export declare function style(role: StyleRole, text: string, opts?: {
+    stream?: {
+        isTTY?: boolean;
+    };
+    env?: NodeJS.ProcessEnv;
+}): string;

package/dist/tty-style.js

@@ -0,0 +1,13 @@
+const PALETTE = {
+    blocked: '\x1b[38;5;203m',
+    release: '\x1b[38;5;114m',
+    changed: '\x1b[38;5;179m',
+    dim: '\x1b[38;5;244m',
+    match: '\x1b[38;5;222m\x1b[1m',
+};
+export function style(role, text, opts = {}) {
+    if (!(opts.stream ?? process.stdout).isTTY || (opts.env ?? process.env).NO_COLOR !== undefined || text === '') {
+        return text;
+    }
+    return `${PALETTE[role]}${text}\x1b[0m`;
+}

package/dist/views.d.ts

@@ -3,7 +3,7 @@ import { coreParticipants, coreStatus } from './decisions.js';
 import { type DeliveryModel, type PlannedNotification } from './delivery.js';
 import { type ActivitiesOptions, type ActivityObservation, type InboxNotification, type PublicAct, type RoomChangeAct, type SquareState, type StoredAct } from './model.js';
 import type { OpenSquare } from './open-square.js';
-import type { Activity, HistoryQuery, ParticipantStatus, SquareSnapshot } from './square-facade.js';
+import type { Activity, HistoryQuery, OperationControl, ParticipantStatus, SquareSnapshot } from './square-facade.js';
 export interface ActivityPresentation {
     readonly name: string;
     readonly roster: readonly string[];
@@ -71,8 +71,8 @@ export interface PendingDeliveryProjection {
     readonly recipient: string;
     readonly notifications: readonly PlannedNotification[];
 }
-export declare function history(square: OpenSquare, query?: HistoryQuery): Promise<Activity[]>;
-export declare function participantHistory(square: OpenSquare, _name: string, query?: HistoryQuery): Promise<Activity[]>;
+export declare function history(square: OpenSquare, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
+export declare function participantHistory(square: OpenSquare, _name: string, query?: HistoryQuery, control?: OperationControl): Promise<Activity[]>;
 export declare function resolveParticipant(square: OpenSquare, name: string): Promise<{
     readonly name: string;
     readonly roster: readonly string[];

package/dist/views.js

@@ -1,13 +1,13 @@
-import { formatActivityId, parseActivityId } from './square-core.js';
+import { formatActivityId, parseActivityId, replayLandedAudiences } from './square-core.js';
 import { deliveryDelta, directedPeerSays } from './activity-feed.js';
 import { coreActivities, coreParticipants, coreStatus, resolveKnownName } from './decisions.js';
 import { deriveDeliveryModel, isActivitySeen } from './delivery.js';
 import { SquareError, nameKey } from './model.js';
-import { countSays, currentHold, foldedState, freshWatchLease, inSquareCount, isCurrentlyJoined, resolveRosterName, rosterNames, watchTerminalStatus } from './runtime.js';
+import { countSays, currentHold, foldedState, freshWatchLease, inSquareCount, isCurrentlyJoined, presenceAnchor, resolveRosterName, rosterNames, watchTerminalStatus } from './runtime.js';
 function expose(stored) {
     if (stored.kind === 'read' || stored.actor === undefined)
         throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
-    return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor, ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}), mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}), ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
+    return { id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor, ...(stored.kind === 'say' && stored.reach !== undefined ? { reach: stored.reach } : {}), ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}), mentions: stored.kind === 'say' ? stored.mentions ?? [] : [], ...('target' in stored ? { target: stored.target } : {}), ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}) };
 }
 function parseRequiredActivityId(id) {
     const index = parseActivityId(id);
@@ -20,7 +20,7 @@ function historyOptions(query) {
         throw new SquareError('invalid_args', 'History cannot combine before and after cursors');
     const afterIndex = query.after === undefined ? undefined : parseRequiredActivityId(query.after);
     const beforeIndex = query.before === undefined ? undefined : parseRequiredActivityId(query.before);
-    return { ...(query.from === undefined ? {} : { participants: [...query.from] }), ...(query.grep === undefined ? {} : { grep: query.grep }), ...(query.mention === undefined ? {} : { mention: query.mention }), ...(afterIndex === undefined ? {} : { afterIndex }), ...(beforeIndex === undefined ? {} : { beforeIndex }), order: 'asc' };
+    return { ...(query.from === undefined ? {} : { participants: [...query.from] }), ...(query.grep === undefined ? {} : { grep: query.grep }), ...(query.fixed === undefined ? {} : { fixed: query.fixed }), ...(query.mention === undefined ? {} : { mention: query.mention }), ...(afterIndex === undefined ? {} : { afterIndex }), ...(beforeIndex === undefined ? {} : { beforeIndex }), order: 'asc' };
 }
 function selectHistory(stored, query) {
     let selected = stored.filter((activity) => activity.kind !== 'read');
@@ -40,10 +40,11 @@ function statuses(square, state) {
 }
 function anchors(state, delivery) {
     const result = {};
+    const landed = replayLandedAudiences(state.acts);
     for (const name of delivery.participants()) {
-        const activity = state.acts.findLast((candidate) => candidate.index <= delivery.cursorFor(name) && (candidate.kind === 'say' || candidate.kind === 'done'));
-        if (activity !== undefined)
-            result[activity.index] = [...(result[activity.index] ?? []), name];
+        const anchor = presenceAnchor(state, name, landed);
+        if (anchor >= 0)
+            result[anchor] = [...(result[anchor] ?? []), name];
     }
     return result;
 }
@@ -58,8 +59,8 @@ function sayNumbers(state) {
         }
     return result;
 }
-export async function history(square, query = {}) { const { state } = await square.artifact.read(); return selectHistory(coreActivities(state, historyOptions(query)), query).map(expose); }
-export async function participantHistory(square, _name, query = {}) { const { state } = await square.artifact.read(); const effective = query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective)), effective).map(expose); }
+export async function history(square, query = {}, control) { const { state } = await square.artifact.read(control?.signal); return selectHistory(coreActivities(state, historyOptions(query)), query).map(expose); }
+export async function participantHistory(square, _name, query = {}, control) { const { state } = await square.artifact.read(control?.signal); const effective = query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective)), effective).map(expose); }
 export async function resolveParticipant(square, name) { const { state } = await square.artifact.read(); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
 export async function currentParticipant(square, name) { const { state } = await square.artifact.read(); const known = resolveRosterName(state, name); return known !== undefined && isCurrentlyJoined(state.acts, known) ? known : undefined; }
 export async function participants(square) { const { state } = await square.artifact.read(); return statuses(square, state); }

package/dist/wake-attempts.js

@@ -1,4 +1,5 @@
 import os from 'node:os';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import path from 'node:path';
 import { isWakeRouteKind, nameKey } from './model.js';
 import { canonicalSquarePath } from './registry.js';
@@ -9,7 +10,7 @@ import { redactDiagnostic } from './diagnostic-redaction.js';
 export { hasAttemptableWakeRoute, isWakeRouteAttemptable, terminalWakeEvidence } from './square-projections.js';
 const VALID_OUTCOMES = new Set(['accepted', 'unknown', 'failed']);
 function ledger(env) {
-    return createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? path.dirname(wakeAttemptsPath(env)), readableScopes: ['user'], writableScope: 'user' });
+    return createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
 }
 export function wakeAttemptsPath(env = process.env) {
     return env.SQUARE_WAKE_ATTEMPTS || path.join(os.homedir(), '.square', 'wake-attempts.ndjsonl');

package/dist/wake-evidence.js

@@ -1,17 +1,11 @@
-import path from 'node:path';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { projectWakeEvidenceFromState, wakeIsEligible, } from './square-projections.js';
 export { wakeIsEligible };
 function hostLedgerForEnv(env) {
-    const root = env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(env.SQUARE_REGISTRY);
-    return createHostLedgerPort({
-        userPath: env.SQUARE_HOST_LEDGER_USER ?? root,
-        localPath: env.SQUARE_HOST_LEDGER_LOCAL ?? root,
-        readableScopes: ['user'],
-        writableScope: 'user',
-    });
+    return createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
 }
 /** Adapter entry: open the artifact, assemble host ports, and project wake evidence. */
 export async function wakeEvidenceProjection(squarePath, now, env) {

package/dist/wakes.d.ts

@@ -13,6 +13,7 @@ export type WatchLeasePulse = {
     readonly type: 'replaced';
 } | {
     readonly type: 'held';
+    readonly heartbeatAt?: number;
 } | {
     readonly type: 'terminal';
     readonly status: 'capped' | 'quorum';

package/dist/wakes.js

@@ -21,15 +21,15 @@ export async function pulseWatchLease(square, name, leaseId, options, heartbeatD
         const lease = freshWatchLease(state, known, at);
         if (lease?.leaseId !== leaseId)
             return { result: { type: 'replaced' } };
-        if (currentHold(state.acts).active)
-            return { result: { type: 'held' } };
-        const terminal = watchTerminalStatus(state, known);
+        const held = currentHold(state.acts).active;
+        const terminal = held ? undefined : watchTerminalStatus(state, known);
         if (terminal !== undefined)
             return { result: { type: 'terminal', status: terminal } };
+        const type = held ? 'held' : 'sleep';
         if (!heartbeatDue)
-            return { result: { type: 'sleep' } };
+            return { result: { type } };
         writeWatchLease(state, known, { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
-        return { state, result: { type: 'sleep', heartbeatAt: at } };
+        return { state, result: { type, heartbeatAt: at } };
     });
 }
 export async function releaseWatchLease(square, name, leaseId) {

package/dist/watch.d.ts

@@ -1,3 +1,8 @@
 import { type WatchOptions } from './model.js';
+interface WatchCallerContext {
+    readonly cwd: string;
+    readonly env: NodeJS.ProcessEnv;
+}
 /** `false` is reserved for a quiet --now; idle completion preserves its existing sweep boundary. */
-export declare function cmdWatch(squarePath: string, name: string, opts: WatchOptions): Promise<boolean | undefined>;
+export declare function cmdWatch(squarePath: string, name: string, opts: WatchOptions, caller?: WatchCallerContext): Promise<boolean | undefined>;
+export {};

package/dist/watch.js

@@ -1,12 +1,11 @@
-import { setTimeout as sleep } from 'node:timers/promises';
 import { isSquareError, } from './model.js';
-import { SLEEP_MS, STALE_MS, WATCH_HEARTBEAT_MS, nowMs, } from './runtime.js';
+import { STALE_MS, WATCH_HEARTBEAT_MS, inSquareCount, nowMs, } from './runtime.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
-import { openParticipant } from './square-wiring.js';
+import { createSquareApplication } from './square-application.js';
 import { resolveParticipant, watchPresentation } from './views.js';
 import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
-import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, joinRecoveryCommand, participantsRecoveryCommand, withPathOutput, } from './presentation.js';
+import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, formatRefusal, participantCommandPrefix, joinRecoveryCommand, participantsRecoveryCommand, withPathOutput, } from './presentation.js';
 import { hasAutomaticDeliveryIdentity } from './registry.js';
 import { parseActivityId } from './square-core.js';
 function watchStatusExitCode(status) {
@@ -37,7 +36,7 @@ function watchOutputResult(squarePath, presentation, name, caught, opts = {}) {
             showCatchHint: !hasAutomaticDeliveryIdentity(),
             perceptions,
         }) + (caught.remaining > 0
-            ? `\n○ ${caught.remaining} matching ${caught.remaining === 1 ? 'activity remains' : 'activities remain'}\n» ${catchContinuationCommand(squarePath, name, opts)}`
+            ? `\n○ ${caught.remaining} matching ${caught.remaining === 1 ? 'activity remains' : 'activities remain'}\n${catchContinuationCommand(squarePath, name, opts)}`
             : ''),
         remaining: caught.remaining,
         ...(opts.status ? { status: opts.status } : {}),
@@ -61,7 +60,7 @@ function writeWatchOutput(squarePath, name, presentation, stdout, remaining, sta
         return;
     }
     const fallback = showCatchHint && remaining === 0
-        ? `» ${participantCommandPrefix(squarePath, name)} catch --idle 30m\n  stay available for new activity`
+        ? `${participantCommandPrefix(squarePath, name)} catch --idle 30m\n  stay available for new activity`
         : '';
     process.stdout.write(withPathOutput(squarePath, [stdout.trimEnd(), fallback].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
 }
@@ -109,7 +108,7 @@ function installWatchInterruptHandler(square, squarePath, name, currentLeaseId)
     const onInterrupt = () => {
         void (async () => {
             await endWatch(square, name, currentLeaseId());
-            process.stdout.write(withPathOutput(squarePath, '✕ catch stopped'));
+            process.stdout.write(withPathOutput(squarePath, '○ you step back — catch stopped'));
             process.exit(130);
         })().catch((error) => {
             process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -121,11 +120,11 @@ function installWatchInterruptHandler(square, squarePath, name, currentLeaseId)
         process.off('SIGINT', onInterrupt);
     };
 }
-async function cmdWatchNow(squarePath, name, opts) {
-    const square = await openSquare(squarePath, { clock: nowMs });
-    const facade = await openParticipant({ path: squarePath, clock: nowMs }, name);
+async function cmdWatchNow(squarePath, name, opts, caller) {
+    const square = await openSquare(squarePath, { clock: nowMs, env: caller.env });
+    const application = createSquareApplication({ cwd: caller.cwd, env: caller.env, squarePath, participant: name, clock: nowMs });
     try {
-        const caught = await facade.participant.catch({
+        const caught = await application.catch({
             ...(opts.id === undefined ? {} : { id: opts.id }),
             ...(opts.participants === undefined ? {} : { from: opts.participants }),
             ...(opts.mention === undefined ? {} : { mention: true }),
@@ -140,23 +139,33 @@ async function cmdWatchNow(squarePath, name, opts) {
         return caught.activities.length > 0;
     }
     finally {
-        await facade.close();
         await closeOpenSquare(square);
     }
 }
+async function countParticipants(square) {
+    try {
+        return inSquareCount((await square.artifact.read()).state);
+    }
+    catch {
+        return undefined;
+    }
+}
 /** `false` is reserved for a quiet --now; idle completion preserves its existing sweep boundary. */
-export async function cmdWatch(squarePath, name, opts) {
+export async function cmdWatch(squarePath, name, opts, caller = { cwd: process.cwd(), env: { ...process.env } }) {
     let square;
+    let participantCount;
     try {
-        square = await openSquare(squarePath, { clock: nowMs });
+        square = await openSquare(squarePath, { clock: nowMs, env: caller.env });
+        participantCount = inSquareCount((await square.artifact.read()).state);
         name = (await resolveParticipant(square, name)).name;
     }
     catch (err) {
         if (isSquareError(err)) {
-            process.stderr.write(err.message + '\n');
+            const bodyLines = [err.message];
             // The caller's own name has never joined; only a join admits it.
-            if (/^Unknown participant/.test(err.message))
-                process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
+            if (/^✕ .* has never stepped into/.test(err.message))
+                bodyLines.push(joinRecoveryCommand(squarePath, name));
+            process.stderr.write(formatRefusal(squarePath, bodyLines, participantCount === undefined ? {} : { participantCount }));
             process.exit(err.code === 'not_found' ? 1 : 2);
         }
         throw err;
@@ -169,19 +178,21 @@ export async function cmdWatch(squarePath, name, opts) {
         }
     }
     catch (err) {
+        const participantCount = await countParticipants(square);
         await closeOpenSquare(square).catch(() => undefined);
         if (isSquareError(err)) {
-            process.stderr.write(err.message + '\n');
+            const bodyLines = [err.message];
             // A filter target is unknown, not the caller; the roster is the useful next read.
-            if (/^(Unknown participant|Unknown mention target)/.test(err.message))
-                process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
+            if (/^✕ .*(has never stepped into|is not standing in this square)/.test(err.message))
+                bodyLines.push(participantsRecoveryCommand(squarePath));
+            process.stderr.write(formatRefusal(squarePath, bodyLines, participantCount === undefined ? {} : { participantCount }));
             process.exit(err.code === 'not_found' ? 1 : 2);
         }
         throw err;
     }
     if (opts.now) {
         await closeOpenSquare(square);
-        return cmdWatchNow(squarePath, name, opts);
+        return cmdWatchNow(squarePath, name, opts, caller);
     }
     const start = await beginWatch(square, squarePath, name, opts);
     if (start.type === 'active') {
@@ -191,6 +202,7 @@ export async function cmdWatch(squarePath, name, opts) {
         process.exit(1);
     }
     let staleSince = nowMs();
+    let wasHeld = false;
     let currentLeaseId = start.leaseId;
     let nextHeartbeatAt = start.heartbeatAt + WATCH_HEARTBEAT_MS;
     if (opts.replace) {
@@ -201,16 +213,18 @@ export async function cmdWatch(squarePath, name, opts) {
     }
     const idleMs = opts.idleMs ?? STALE_MS;
     const removeInterruptHandler = installWatchInterruptHandler(square, squarePath, name, () => currentLeaseId);
-    const facade = await openParticipant({ path: squarePath, clock: nowMs }, name);
+    const application = createSquareApplication({ cwd: caller.cwd, env: caller.env, squarePath, participant: name, clock: nowMs });
     try {
         while (true) {
+            // Capture before evaluation: changes during catch/lease checks must not be lost.
+            const baseline = (await square.artifact.read()).version;
             const leaseState = await pulseWatchLease(square, name, currentLeaseId, opts, nowMs() >= nextHeartbeatAt);
-            if (leaseState.type === 'sleep' && leaseState.heartbeatAt !== undefined) {
+            if ((leaseState.type === 'sleep' || leaseState.type === 'held') && leaseState.heartbeatAt !== undefined) {
                 nextHeartbeatAt = leaseState.heartbeatAt + WATCH_HEARTBEAT_MS;
             }
             let result = leaseState;
             if (result.type === 'sleep') {
-                const caught = await facade.participant.catch({
+                const caught = await application.catch({
                     ...(opts.participants === undefined ? {} : { from: opts.participants }),
                     ...(opts.mention === undefined ? {} : { mention: true }),
                     ...(opts.limit === undefined ? {} : { limit: opts.limit }),
@@ -223,9 +237,10 @@ export async function cmdWatch(squarePath, name, opts) {
                 currentLeaseId = undefined;
                 return;
             }
-            if (result.type === 'held')
+            if (result.type === 'held' || wasHeld)
                 staleSince = nowMs();
-            if (nowMs() - staleSince >= idleMs) {
+            wasHeld = result.type === 'held';
+            if (!wasHeld && nowMs() - staleSince >= idleMs) {
                 const result = !await ownsWatchLease(square, name, currentLeaseId)
                     ? { type: 'replaced' }
                     : { type: 'terminal', status: 'stale' };
@@ -234,11 +249,11 @@ export async function cmdWatch(squarePath, name, opts) {
                     return;
                 }
             }
-            await sleep(SLEEP_MS);
+            const nextDeadline = Math.min(nextHeartbeatAt, wasHeld ? Infinity : staleSince + idleMs);
+            await square.artifact.changed(baseline, Math.max(0, nextDeadline - nowMs()));
         }
     }
     finally {
-        await facade.close();
         await closeOpenSquare(square);
         removeInterruptHandler();
     }