@astrosheep/square 0.3.63 → 0.3.65

package/dist/wake-eligibility.d.ts

@@ -0,0 +1,43 @@
+import { type SquareState, type WakeRoute } from './model.js';
+import { deriveDeliveryModel } from './delivery.js';
+import type { EvidenceRecord, PresenceRecord } from './host-ledger.js';
+import type { PresentationEvidenceProjection, WakeRequest } from './ports.js';
+import { type WakeAttempt } from './wake-evidence.js';
+export interface WakeSnapshot {
+    readonly state: SquareState;
+    /** Canonicalized by the caller; every identity in this snapshot is square-local. */
+    readonly location: string;
+    readonly owners: readonly PresenceRecord[];
+    readonly wakeRecords: readonly EvidenceRecord[];
+    readonly presentations: readonly PresentationEvidenceProjection[];
+    readonly now: number;
+    readonly delivery?: ReturnType<typeof deriveDeliveryModel>;
+}
+export interface OwnedWakeRoute {
+    readonly route: WakeRoute;
+    readonly owner: PresenceRecord;
+}
+export interface WakeCurrentness {
+    readonly current: boolean;
+    readonly activityPending: boolean;
+    readonly sessionBound: boolean;
+    readonly routePublished: boolean;
+    readonly selectedOwner: boolean;
+    readonly cancelled: boolean;
+    readonly presented: boolean;
+}
+export interface WakeEvidence {
+    readonly delivered: boolean;
+    /** All selected, uncancelled routes have session-local presentation evidence. */
+    readonly presented: boolean;
+    readonly attempts: readonly WakeAttempt[];
+    readonly terminal?: WakeAttempt;
+    readonly attemptableRoutes: readonly WakeRoute[];
+}
+export interface WakeEligibility {
+    evidence(recipient: string, actIndex: number): WakeEvidence;
+    currentness(request: WakeRequest): WakeCurrentness;
+}
+/** One strict ownership join, latest selection, and request fence over primary evidence only. */
+export declare function projectWakeEligibility(input: WakeSnapshot): WakeEligibility;
+export declare function wakeIsEligible(evidence: WakeEvidence): boolean;

package/dist/wake-eligibility.js

@@ -0,0 +1,106 @@
+import { nameKey } from './model.js';
+import { deriveDeliveryModel } from './delivery.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
+import { decodeWakeEvidence } from './wake-evidence.js';
+function identity(...parts) { return JSON.stringify(parts); }
+/** One strict ownership join, latest selection, and request fence over primary evidence only. */
+export function projectWakeEligibility(input) {
+    const delivery = input.delivery ?? deriveDeliveryModel(input.state);
+    const ownersBySession = new Map();
+    for (const owner of input.owners) {
+        if (owner.location !== input.location)
+            continue;
+        const key = identity(nameKey(owner.participant), owner.session);
+        const rows = ownersBySession.get(key) ?? [];
+        rows.push(owner);
+        ownersBySession.set(key, rows);
+    }
+    const ownerFor = (route) => route.location !== input.location ? undefined
+        : ownersBySession.get(identity(nameKey(route.participant), route.sessionId))?.find((row) => route.epoch === undefined || row.epoch === route.epoch);
+    const ownedRoutes = [];
+    const latest = new Map();
+    for (const route of input.state.routes ?? []) {
+        const participant = nameKey(route.participant);
+        const owner = ownerFor(route);
+        if (owner === undefined)
+            continue;
+        ownedRoutes.push({ route, owner });
+        latest.set(participant, Math.max(latest.get(participant) ?? Number.NEGATIVE_INFINITY, route.updatedAt));
+    }
+    const selectedByRecipient = new Map();
+    for (const owned of ownedRoutes) {
+        const key = nameKey(owned.route.participant);
+        if (owned.route.updatedAt !== latest.get(key))
+            continue;
+        const rows = selectedByRecipient.get(key) ?? [];
+        rows.push(owned);
+        selectedByRecipient.set(key, rows);
+    }
+    const pending = new Set();
+    for (const recipient of delivery.joinedRecipients()) {
+        for (const notification of delivery.pendingFor(recipient))
+            pending.add(identity(nameKey(recipient), notification.item.index));
+    }
+    const attemptsByAttention = new Map();
+    for (const record of input.wakeRecords) {
+        if (record.location !== input.location)
+            continue;
+        const decoded = decodeWakeEvidence(record, input.now);
+        if (decoded?.kind !== 'attempt')
+            continue;
+        const attempt = decoded.value;
+        const key = identity(nameKey(attempt.attention.recipient), attempt.attention.actIndex);
+        const rows = attemptsByAttention.get(key) ?? [];
+        rows.push(attempt);
+        attemptsByAttention.set(key, rows);
+    }
+    const presentedSessions = new Set();
+    for (const row of input.presentations) {
+        if (row.location !== input.location || (row.outcome !== 'presented' && row.outcome !== 'clipped'))
+            continue;
+        presentedSessions.add(identity(nameKey(row.participant), row.activity, row.sessionId));
+    }
+    const isPresented = (route, actIndex) => presentedSessions.has(identity(nameKey(route.participant), formatActivityId(actIndex), route.sessionId));
+    const isCancelled = (owner, actIndex) => actIndex <= (owner.cancelledThrough ?? -1);
+    return {
+        evidence(recipient, actIndex) {
+            const key = nameKey(recipient);
+            // Accepted/unknown exclusion belongs to attention, not to a surviving owner or route kind.
+            const attempts = attemptsByAttention.get(identity(key, actIndex)) ?? [];
+            const terminal = attempts.findLast((attempt) => attempt.outcome === 'accepted')
+                ?? attempts.findLast((attempt) => attempt.outcome === 'unknown');
+            const routes = (selectedByRecipient.get(key) ?? []).filter(({ owner }) => !isCancelled(owner, actIndex));
+            const presented = routes.length > 0 && routes.every(({ route }) => isPresented(route, actIndex));
+            return {
+                delivered: delivery.isSeen(recipient, actIndex), presented, attempts,
+                ...(terminal === undefined ? {} : { terminal }),
+                attemptableRoutes: terminal === undefined && pending.has(identity(key, actIndex))
+                    ? routes.filter(({ route }) => !isPresented(route, actIndex)).map(({ route }) => route) : [],
+            };
+        },
+        currentness(request) {
+            const actIndex = parseActivityId(request.activity);
+            const route = request.route;
+            const sameRecipient = nameKey(request.participant) === nameKey(route.participant);
+            const sameLocation = request.location === input.location && route.location === input.location;
+            const activityPending = actIndex !== undefined && request.location === input.location
+                && pending.has(identity(nameKey(request.participant), actIndex));
+            const owner = sameLocation && sameRecipient ? ownerFor(route) : undefined;
+            const sessionBound = owner !== undefined;
+            const matchesRequest = (published) => published.location === route.location
+                && nameKey(published.participant) === nameKey(route.participant) && published.sessionId === route.sessionId
+                && published.kind === route.kind && published.epoch === route.epoch && Object.keys(published.address).length === Object.keys(route.address).length && Object.keys(published.address).every((key) => published.address[key] === route.address[key]);
+            const routePublished = sameLocation && sameRecipient && (input.state.routes ?? []).some(matchesRequest);
+            const selectedOwner = sameLocation && sameRecipient
+                && (selectedByRecipient.get(nameKey(route.participant)) ?? []).some(({ route: published }) => matchesRequest(published));
+            const cancelled = actIndex !== undefined && owner !== undefined && isCancelled(owner, actIndex);
+            const presented = actIndex !== undefined && sameLocation && sameRecipient && isPresented(route, actIndex);
+            // Dispatching evidence deliberately does not fence the request that owns the atomic claim.
+            return { current: activityPending && sessionBound && routePublished && selectedOwner && !cancelled && !presented,
+                activityPending, sessionBound, routePublished, selectedOwner, cancelled, presented };
+        },
+    };
+}
+export function wakeIsEligible(evidence) {
+    return !evidence.delivered && !evidence.presented && evidence.terminal === undefined && evidence.attemptableRoutes.length > 0;
+}

package/dist/wake-evidence.d.ts

@@ -1,9 +1,32 @@
-import type { SquareState } from './model.js';
-import { wakeIsEligible, type WakeEvidence, type WakeEvidenceProjection } from './square-projections.js';
-import type { DeliveryModel } from './delivery.js';
-export type { WakeEvidence, WakeEvidenceProjection };
-export { wakeIsEligible };
-/** Adapter entry: open the artifact, assemble host ports, and project wake evidence. */
-export declare function wakeEvidenceProjection(squarePath: string, now: number, env: NodeJS.ProcessEnv): Promise<WakeEvidenceProjection>;
-export declare function wakeEvidenceProjectionFromState(squarePath: string, state: SquareState, now: number, env: NodeJS.ProcessEnv, delivery?: DeliveryModel): Promise<WakeEvidenceProjection>;
-export declare function wakeEvidence(squarePath: string, recipient: string, actIndex: number, now: number, env: NodeJS.ProcessEnv): Promise<WakeEvidence>;
+import type { EvidenceRecord, WakeAttention } from './host-ledger.js';
+import type { WakeRouteKind } from './model.js';
+export interface WakeAttempt {
+    readonly at: number;
+    readonly attention: WakeAttention;
+    readonly routeKind: WakeRouteKind;
+    readonly outcome: 'accepted' | 'unknown' | 'failed';
+    readonly signature?: string;
+    readonly attemptN: number;
+    readonly session?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+}
+export interface WakeReleaseDiagnostic {
+    readonly at: number;
+    readonly attention: WakeAttention;
+    readonly routeKind?: WakeRouteKind;
+    readonly attemptN?: number;
+    readonly session?: string;
+    readonly signature?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+}
+export type DecodedWakeEvidence = {
+    readonly kind: 'attempt';
+    readonly value: WakeAttempt;
+} | {
+    readonly kind: 'release';
+    readonly value: WakeReleaseDiagnostic;
+};
+/** Decode primary attempts and diagnostic-only releases without mixing their evidence. */
+export declare function decodeWakeEvidence(record: EvidenceRecord, now: number): DecodedWakeEvidence | undefined;

package/dist/wake-evidence.js

@@ -1,26 +1,31 @@
-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) {
-    return createHostLedgerPort({ rootPath: hostLedgerRoot(env) });
-}
-/** Adapter entry: open the artifact, assemble host ports, and project wake evidence. */
-export async function wakeEvidenceProjection(squarePath, now, env) {
-    const square = await openSquare(squarePath, { clock: () => now, hostLedger: hostLedgerForEnv(env), env });
-    try {
-        const { state } = await square.artifact.read();
-        return projectWakeEvidenceFromState({ location: squarePath, state, hostLedger: square.hostLedger, now });
-    }
-    finally {
-        await closeOpenSquare(square);
+import { parseActivityId } from './square-core.js';
+/** Decode primary attempts and diagnostic-only releases without mixing their evidence. */
+export function decodeWakeEvidence(record, now) {
+    if (record.kind !== 'wake')
+        return undefined;
+    const actIndex = parseActivityId(record.activity);
+    if (actIndex === undefined)
+        return undefined;
+    const value = {
+        at: record.at ?? now,
+        attention: { squarePath: record.location, recipient: record.participant, actIndex },
+        ...(record.session === undefined ? {} : { session: record.session }),
+        ...(record.signature === undefined ? {} : { signature: record.signature }),
+        ...(record.message === undefined ? {} : { message: record.message }),
+        ...(record.diagnostic === undefined ? {} : { diagnostic: record.diagnostic }),
+    };
+    if (record.outcome === 'released') {
+        if (record.at === undefined)
+            return undefined;
+        return { kind: 'release', value: {
+                ...value,
+                ...(record.routeKind === undefined ? {} : { routeKind: record.routeKind }),
+                ...(record.attemptN === undefined ? {} : { attemptN: record.attemptN }),
+            } };
     }
-}
-export function wakeEvidenceProjectionFromState(squarePath, state, now, env, delivery) {
-    return projectWakeEvidenceFromState({ location: squarePath, state, hostLedger: hostLedgerForEnv(env), now, delivery });
-}
-export async function wakeEvidence(squarePath, recipient, actIndex, now, env) {
-    return (await wakeEvidenceProjection(squarePath, now, env)).evidence(recipient, actIndex);
+    if (record.outcome !== 'accepted' && record.outcome !== 'unknown' && record.outcome !== 'failed')
+        return undefined;
+    if (record.routeKind === undefined || typeof record.attemptN !== 'number')
+        return undefined;
+    return { kind: 'attempt', value: { ...value, routeKind: record.routeKind, attemptN: record.attemptN, outcome: record.outcome } };
 }

package/dist/wake-sink.d.ts

@@ -1,14 +1,18 @@
+/** One Paseo wake attempt: where it goes, what it says, and what identifies it. */
 export interface PaseoWakeRequest {
     agentId: string;
     prompt: string;
+    location: string;
+    participant: string;
+    activity: string;
+    attemptN?: number;
 }
-export type PaseoWakeFailureKind = 'transient' | 'rejected' | 'unknown';
-export declare class PaseoWakeSendError extends Error {
-    readonly kind: PaseoWakeFailureKind;
-    constructor(message: string, kind: PaseoWakeFailureKind);
-}
-export declare function sendPaseoWake({ agentId, prompt }: PaseoWakeRequest, opts?: {
-    args?: string[];
-    bin?: string;
+/**
+ * The daemon's own dedup key for one attempt. Every retry of the same attempt
+ * derives the same id; a later attempt of the same attention derives a new one.
+ */
+export declare function paseoWakeMessageId(request: Pick<PaseoWakeRequest, 'location' | 'participant' | 'activity' | 'attemptN'>): string;
+/** Steer one existing Paseo agent through the shared delivery entry. Never interrupts a turn. */
+export declare function sendPaseoWake(request: PaseoWakeRequest, opts?: {
     timeoutMs?: number;
-}): void;
+}): Promise<void>;

package/dist/wake-sink.js

@@ -1,56 +1,37 @@
-import { spawnSync } from 'node:child_process';
-export class PaseoWakeSendError extends Error {
-    kind;
-    constructor(message, kind) {
-        super(message);
-        this.kind = kind;
-        this.name = 'PaseoWakeSendError';
-    }
+import { createHash } from 'node:crypto';
+import { DeliveryError, connect } from './packages/agent-delivery/src/index.js';
+/**
+ * The daemon's own dedup key for one attempt. Every retry of the same attempt
+ * derives the same id; a later attempt of the same attention derives a new one.
+ */
+export function paseoWakeMessageId(request) {
+    const digest = createHash('sha256')
+        .update([request.location, request.participant, request.activity, request.attemptN ?? 0].join('|'))
+        .digest('hex');
+    return `square-${digest.slice(0, 32)}`;
 }
-function commandError(output) {
-    try {
-        const parsed = JSON.parse(output);
-        if (parsed.error === undefined)
-            return undefined;
-        return {
-            ...(typeof parsed.error.code === 'string' ? { code: parsed.error.code } : {}),
-            message: typeof parsed.error.message === 'string' ? parsed.error.message : output.trim(),
-        };
-    }
-    catch {
-        return undefined;
-    }
-}
-function classifyCommandFailure(code, message) {
-    if (code === 'DAEMON_NOT_RUNNING' || /ECONNREFUSED|ENOENT|not found.*executable/i.test(message))
-        return 'transient';
-    if (/password|auth|unauthori[sz]ed|agent not found|rejected/i.test(message))
-        return 'rejected';
-    return 'unknown';
-}
-function redactUriPassword(value) {
-    return value.replace(/([?&]password=)[^&\s]+/gi, '$1[redacted]');
-}
-function configuredArguments(name) {
-    try {
-        const parsed = JSON.parse(process.env[name] ?? '[]');
-        return Array.isArray(parsed) && parsed.every((item) => typeof item === 'string') ? parsed : [];
-    }
-    catch {
-        return [];
-    }
-}
-export function sendPaseoWake({ agentId, prompt }, opts = {}) {
-    const result = spawnSync(opts.bin ?? process.env.SQUARE_PASEO_BIN ?? 'paseo', [...(opts.args ?? configuredArguments('SQUARE_PASEO_BIN_ARGS')), 'send', agentId, '--prompt', prompt, '--no-wait', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: opts.timeoutMs ?? 5000, env: process.env });
-    if (result.error) {
-        const code = result.error.code;
-        const kind = code === 'ENOENT' || code === 'ECONNREFUSED' ? 'transient' : 'unknown';
-        throw new PaseoWakeSendError(result.error.message, kind);
-    }
-    if (result.status === 0)
-        return;
-    const output = `${result.stderr ?? ''}${result.stdout ?? ''}`;
-    const failure = commandError(output);
-    const message = redactUriPassword(failure?.message || output.trim() || `paseo send exited with ${result.status ?? 'no status'}`);
-    throw new PaseoWakeSendError(message, classifyCommandFailure(failure?.code, message));
+/** Steer one existing Paseo agent through the shared delivery entry. Never interrupts a turn. */
+export async function sendPaseoWake(request, opts = {}) {
+    const budgetMs = opts.timeoutMs;
+    // A usable budget becomes one deadline both phases share; anything else is an
+    // argument error, so it is handed to the entry untouched to classify.
+    const bounded = budgetMs !== undefined && Number.isFinite(budgetMs) && budgetMs > 0;
+    const deadline = bounded ? Date.now() + budgetMs : 0;
+    // An elapsed budget never reached the daemon, so it is the shared entry's own
+    // "unavailable" failure rather than a send error of its own.
+    const connectMs = bounded ? Math.max(0, deadline - Date.now()) : budgetMs;
+    if (bounded && connectMs === 0)
+        throw new DeliveryError('unavailable');
+    const agent = await connect({
+        harness: 'paseo',
+        agentId: request.agentId,
+        ...(connectMs === undefined ? {} : { timeoutMs: connectMs }),
+    });
+    const steerMs = bounded ? Math.max(0, deadline - Date.now()) : budgetMs;
+    if (bounded && steerMs === 0)
+        throw new DeliveryError('unavailable');
+    await agent.steer(request.prompt, {
+        id: paseoWakeMessageId(request),
+        ...(steerMs === undefined ? {} : { timeoutMs: steerMs }),
+    });
 }

package/dist/watch.js

@@ -1,5 +1,5 @@
 import { isSquareError, } from './model.js';
-import { STALE_MS, WATCH_HEARTBEAT_MS, inSquareCount, nowMs, } from './runtime.js';
+import { STALE_MS, WATCH_HEARTBEAT_MS, countSays, inSquareCount, nowMs, } from './runtime.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
 import { createSquareApplication } from './square-application.js';
@@ -20,20 +20,14 @@ function watchOutputResult(squarePath, presentation, name, caught, opts = {}) {
         const stored = index === undefined ? undefined : presentation.activities.find((item) => item.index === index);
         return stored === undefined ? [] : [{ activity: stored, perception: activity.perception }];
     });
-    const publicItems = delivered
-        .map(({ activity }) => activity)
-        .filter((item) => item.kind === 'say' || item.kind === 'done');
-    const roomChanges = delivered
-        .map(({ activity }) => activity)
-        .filter((item) => item.kind === 'join' || item.kind === 'done' || item.kind === 'hold' || item.kind === 'resume');
+    // Catch delivers only directed say activities, so there is no lifecycle list to split off.
+    const publicItems = delivered.map(({ activity }) => activity).filter((item) => item.kind === 'say' || item.kind === 'done');
     const perceptions = new Map(delivered.map(({ activity, perception }) => [activity.index, perception]));
     return {
         type: 'output',
-        stdout: renderWatchOutput([...presentation.activities], publicItems, roomChanges, {
+        stdout: renderWatchOutput([...presentation.activities], publicItems, {
             ...opts,
-            squarePath,
             viewer: name,
-            showCatchHint: !hasAutomaticDeliveryIdentity(),
             perceptions,
         }) + (caught.remaining > 0
             ? `\n○ ${caught.remaining} matching ${caught.remaining === 1 ? 'activity remains' : 'activities remain'}\n${catchContinuationCommand(squarePath, name, opts)}`
@@ -72,6 +66,8 @@ function writeWatchTerminal(squarePath, name, presentation, status, idleMs) {
         ...(idleMs === undefined ? {} : { idleMs }),
         presence: presentation.presence,
         showCatchHint: !hasAutomaticDeliveryIdentity(),
+        ownActivityCount: countSays(presentation.state.acts, name),
+        hardCap: presentation.state.hardCap,
     }), { participantCount: presentation.participantCount }));
 }
 function writeWatchReplaced(squarePath, name, presentation) {
@@ -142,14 +138,6 @@ async function cmdWatchNow(squarePath, name, opts, caller) {
         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, caller = { cwd: process.cwd(), env: { ...process.env } }) {
     let square;
@@ -163,7 +151,7 @@ export async function cmdWatch(squarePath, name, opts, caller = { cwd: process.c
         if (isSquareError(err)) {
             const bodyLines = [err.message];
             // The caller's own name has never joined; only a join admits it.
-            if (/^✕ .* has never stepped into/.test(err.message))
+            if (err.facts?.reason === 'never_joined')
                 bodyLines.push(joinRecoveryCommand(squarePath, name));
             process.stderr.write(formatRefusal(squarePath, bodyLines, participantCount === undefined ? {} : { participantCount }));
             process.exit(err.code === 'not_found' ? 1 : 2);
@@ -178,12 +166,16 @@ export async function cmdWatch(squarePath, name, opts, caller = { cwd: process.c
         }
     }
     catch (err) {
-        const participantCount = await countParticipants(square);
+        let participantCount;
+        try {
+            participantCount = inSquareCount((await square.artifact.read()).state);
+        }
+        catch { /* the header count is best effort */ }
         await closeOpenSquare(square).catch(() => undefined);
         if (isSquareError(err)) {
             const bodyLines = [err.message];
             // A filter target is unknown, not the caller; the roster is the useful next read.
-            if (/^✕ .*(has never stepped into|is not standing in this square)/.test(err.message))
+            if (err.facts?.reason === 'never_joined' || err.facts?.reason === 'not_standing')
                 bodyLines.push(participantsRecoveryCommand(squarePath));
             process.stderr.write(formatRefusal(squarePath, bodyLines, participantCount === undefined ? {} : { participantCount }));
             process.exit(err.code === 'not_found' ? 1 : 2);

package/extensions/square-pi.js

@@ -2,6 +2,7 @@ import { presentPendingAtBoundary, renderPendingAtBoundary } from '../dist/bound
 import { automaticSessionEnd, automaticSessionStart } from '../dist/automatic-session.js';
 import { sessionInbox, observeSessionPending } from '../dist/inbox.js';
 import { renderAttentionDescription } from '../dist/attention-presentation.js';
+import { createPiReceiver, sendPiMessage } from '../dist/packages/agent-delivery/src/pi.js';
 
 class PiDeliveryDroppedError extends Error {
   constructor() {
@@ -42,6 +43,10 @@ export function summarizePendingForNotify(pending) {
 }
 
 export default function squarePiExtension(pi) {
+  pi.registerFlag('agent-delivery-socket', { type: 'string', description: 'Explicit private local delivery socket' });
+  createPiReceiver(pi, {
+    get endpoint() { return pi.getFlag('agent-delivery-socket'); },
+  });
   let sessionId;
   let sessionCwd;
   let ui;
@@ -115,12 +120,12 @@ export default function squarePiExtension(pi) {
   // Pi owns PI_SESSION_ID and several SDK sessions may coexist in one process.
   const sessionEnv = (id) => ({ ...process.env, ...(id === undefined ? {} : { PI_SESSION_ID: id }) });
 
-  // A transport may keep its promise pending while Pi is shutting down or
-  // replacing a session. Never make a lifecycle hook wait for that transport.
+  // Aborting releases native landing waits; retain cleanup until the observer
+  // has closed, including when cancellation precedes a lifecycle hook.
   const stopWatcher = () => {
     watcherAbort?.abort();
-    watcher = undefined;
     watcherAbort = undefined;
+    return watcher;
   };
 
   const pause = (signal, delayMs) => new Promise((resolve) => {
@@ -201,10 +206,10 @@ export default function squarePiExtension(pi) {
               const messageContent = framePiMessage(content);
               const landing = waitForLanding(messageContent, signal, 'steer');
               try {
-                Promise.resolve(pi.sendMessage(
+                sendPiMessage(pi,
                   { customType: 'square', content: messageContent, display: false },
                   { deliverAs: 'steer', triggerTurn: true },
-                )).catch((error) => landing.ack.settle(error));
+                );
               } catch (error) {
                 landing.ack.settle(error);
               }
@@ -224,6 +229,7 @@ export default function squarePiExtension(pi) {
             env,
             signal,
           );
+          if (signal.aborted || token !== generation) return;
           for (const key of keys) handledPending.add(key);
         } catch (error) {
           if (signal.aborted || token !== generation) return;
@@ -247,7 +253,7 @@ export default function squarePiExtension(pi) {
     cancelledRun = false;
     generation += 1;
     failAcks(new Error('Pi session replaced'));
-    stopWatcher();
+    const stopped = stopWatcher();
     handledPending.clear();
     observedPending.clear();
     retryAfterChange = false;
@@ -259,29 +265,31 @@ export default function squarePiExtension(pi) {
     sessionId = ctx.sessionManager.getSessionId();
     sessionCwd = ctx.cwd || process.cwd();
     const token = generation;
+    await stopped;
+    if (token !== generation) return;
     watcherAbort = new AbortController();
     const signal = watcherAbort.signal;
-    void automaticSessionStart('pi', sessionId, sessionCwd, sessionEnv(sessionId)).then((context) => {
+    const startup = automaticSessionStart('pi', sessionId, sessionCwd, sessionEnv(sessionId)).then((context) => {
       if (context === undefined || sessionId === undefined || token !== generation) return;
       const messageContent = framePiMessage(context);
       const landing = waitForLanding(messageContent, signal, 'nextTurn');
       try {
-        Promise.resolve(pi.sendMessage(
+        sendPiMessage(pi,
           { customType: 'square', content: messageContent, display: true },
           { deliverAs: 'nextTurn' },
-        )).catch((error) => landing.ack.settle(error));
+        );
       } catch {
         // Joining context is advisory; an unavailable Pi transport does not block startup.
         landing.ack.settle(new Error('Pi joining-context injection failed'));
       }
       void landing.promise.catch(() => undefined);
     }).catch(() => undefined);
-    watcher = wake(token, signal).catch(() => undefined);
+    watcher = Promise.allSettled([startup, wake(token, signal)]).then(() => undefined);
   });
 
   pi.on('agent_start', async (_event, ctx) => {
     detachRunAbort?.();
-    currentRunSignal = ctx?.getSignal?.();
+    currentRunSignal = ctx?.signal;
     if (ctx?.mode !== 'tui' || currentRunSignal === undefined) return;
     const runSignal = currentRunSignal;
     detachRunAbort = () => runSignal.removeEventListener('abort', cancelRunDelivery);
@@ -329,6 +337,8 @@ export default function squarePiExtension(pi) {
     const token = generation;
     // Cancel the entire pending batch, including entries not yet sent to Pi.
     // This is local suppression, never evidence that the model saw the activity.
+    await stopWatcher();
+    if (token !== generation || sessionId === undefined) return;
     const cancelled = await sessionInbox(sessionId, sessionEnv(sessionId));
     if (token !== generation || sessionId === undefined) return;
     for (const key of inboxKeys(cancelled)) handledPending.add(key);
@@ -343,13 +353,17 @@ export default function squarePiExtension(pi) {
     cancelledRun = false;
     generation += 1;
     failAcks(new Error('Pi session ended'));
-    stopWatcher();
+    const stopped = stopWatcher();
     ui = undefined;
-    if (sessionId && sessionCwd) void automaticSessionEnd('pi', sessionId, sessionCwd, sessionEnv(sessionId)).catch(() => undefined);
+    const endedId = sessionId;
+    const endedCwd = sessionCwd;
+    const endedEnv = sessionEnv(endedId);
     sessionId = undefined;
     sessionCwd = undefined;
     retryWait = undefined;
     activeTurn = undefined;
     currentRunSignal = undefined;
+    await stopped;
+    if (endedId && endedCwd) await automaticSessionEnd('pi', endedId, endedCwd, endedEnv).catch(() => undefined);
   });
 }

package/guides/change-waits.md

@@ -4,7 +4,7 @@ Square's artifact and host-ledger adapters own change detection. Notifications a
 
 - A process shares a revision reader per canonical artifact and a filesystem watcher per containing directory. Subscribers have independent baselines, deadlines, and cancellation. The final release closes the watcher, reconciliation timer, and any outstanding read.
 - Directory notifications invalidate lightweight reads. A two-second reconciliation checks revisions/ledger metadata even when notifications are missing. Missing directories, unsupported watches, and watcher failures retain that fallback; directory replacement is detected during reconciliation. Normal notification latency is not a hard guarantee: a missed hint may wait for reconciliation, plus scheduling and lock contention.
-- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Only changed projections load historical state. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
+- The artifact revision remains authoritative. No new sidecar, broker, or persistent cache is introduced. Only changed projections load historical state. A missing artifact is a stable observation, not a repeated change: reconciliation remains quiet while it stays absent and detects its return without deleting its session bindings. Strict artifact reads still report absence as an error. Ledger metadata invalidates bindings and presentation projections; it is never treated as evidence of delivery.
 - Each Pi session owns a long-lived pending observer, including when it has no bindings yet. Presence and evidence changes update its subscriptions. There is no repeated thirty-second restart and no per-second binding scan. A failed injection waits for a substantive change; its own failed evidence write does not trigger a retry loop.
 - Blocking CLI catch waits for a revision or its next heartbeat/quiet deadline. A held catch keeps its lease alive and pauses quiet expiry. Core catch, NDJSON stream, and delivery-receipt waits use the same change detector. Held express also waits for changes; throttling still waits for its eligibility time.
 - Catch lease expiry, ledger retention/claim expiry, and cancellation are independent wake conditions. No filesystem write is required for a time-based eligibility change.