@astrosheep/square 0.3.56 → 0.3.58

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.56",
+  "version": "0.3.58",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.56",
+  "version": "0.3.58",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/dist/activity.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { SquareError, isSquareError, validateName } from './model.js';
-import { expressHintLine, renderActivityBlocked, renderActivityLimit, renderExpressNoWait, renderExpressWaiting, renderPendingFeed, withPathOutput, } from './presentation.js';
+import { expressHintLine, renderActivityBlocked, renderActivityLimit, renderExpressNoWait, renderExpressWaiting, renderPendingFeed, joinRecoveryCommand, withPathOutput, } from './presentation.js';
 import { nowMs, SLEEP_MS } from './runtime.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
@@ -55,6 +55,8 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
                 const draftPath = saveActivityDraft(squarePath, name, rawInput);
                 process.stderr.write(err.message + '\n');
                 process.stderr.write(`draft kept: ${draftPath}\n`);
+                if (/^Unknown participant/.test(err.message))
+                    process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
                 process.exit(2);
             }
             process.stderr.write(err.message + '\n');

package/dist/cli/program.js

@@ -1,13 +1,20 @@
 import { helpRequest } from '../help.js';
 import { isSquareError } from '../model.js';
-import { commandPrefix } from '../presentation.js';
+import { joinRecoveryCommand, participantsRecoveryCommand } from '../presentation.js';
 import { defaultContext, parseGlobalArgs } from './context.js';
 import { executeRegisteredCommand, findCommand } from './registry.js';
-function handleSquareError(error, squarePath) {
+function handleSquareError(error, squarePath, name) {
     if (isSquareError(error)) {
         process.stderr.write(`${error.message}\n`);
-        if (squarePath !== undefined && /^(Unknown participant|Unknown mention target)/.test(error.message)) {
-            process.stderr.write(`» ${commandPrefix(squarePath)} participants\n`);
+        if (squarePath !== undefined && /^Unknown participant/.test(error.message)) {
+            // The caller's name has never joined this square; only a join admits it.
+            if (name !== undefined)
+                process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
+            else
+                process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
+        }
+        else if (squarePath !== undefined && /^Unknown mention target/.test(error.message)) {
+            process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
         }
         process.exit(error.code === 'not_found' ? 1 : 2);
     }
@@ -16,6 +23,7 @@ function handleSquareError(error, squarePath) {
 /** Parse global flags, select an executable adapter, and leave all command work to the registry. */
 export async function runCli(rawArgs = process.argv.slice(2)) {
     let squarePath;
+    let requestedName;
     try {
         const requestedHelp = helpRequest(rawArgs);
         if (requestedHelp !== undefined) {
@@ -24,6 +32,7 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
         }
         const parsed = await parseGlobalArgs(rawArgs);
         squarePath = parsed.squarePath;
+        requestedName = parsed.name;
         if (parsed.args.length === 0 || parsed.args[0] === '--help' || parsed.args[0] === '-h') {
             await executeRegisteredCommand('help', [], defaultContext('help', parsed.squarePath, parsed.name));
             return;
@@ -36,6 +45,6 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
         await executeRegisteredCommand(command, parsed.args.slice(1), defaultContext(command, parsed.squarePath, parsed.name));
     }
     catch (error) {
-        handleSquareError(error, squarePath);
+        handleSquareError(error, squarePath, requestedName);
     }
 }

package/dist/delivery-health.d.ts

@@ -1,5 +1,6 @@
 import { type DirectedNotificationRoute } from './delivery.js';
-import type { WakeAttempt } from './square-projections.js';
+import { type WakeAttempt } from './square-projections.js';
+import { type WakeReleaseDiagnostic } from './wake-attempts.js';
 export type DeliveryHealthKind = 'awaiting' | 'wake-accepted' | 'wake-unknown' | 'presented-not-delivered' | 'unreachable';
 export interface DeliveryHealthItem {
     squarePath: string;
@@ -18,5 +19,5 @@ export declare function classifyDeliveryHealth(squarePath: string, opts: {
     now?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<DeliveryHealthItem[]>;
-export declare function renderDeliveryHealth(items: readonly DeliveryHealthItem[]): string[];
+export declare function renderDeliveryHealth(items: readonly DeliveryHealthItem[], releases?: readonly WakeReleaseDiagnostic[], now?: number): string[];
 export declare function doctorDeliveryHealth(squarePath: string, graceMs: number, now?: number, env?: NodeJS.ProcessEnv): Promise<string[]>;

package/dist/delivery-health.js

@@ -1,10 +1,12 @@
+import { deriveDeliveryModel } from './delivery.js';
 import { formatActivityId } from './square-core.js';
 import { participantIdentity, truncateChars } from './presentation.js';
 import { formatDuration } from './time.js';
-import { wakeEvidence } from './wake-evidence.js';
+import { projectWakeEvidenceFromState } from './square-projections.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
-import { pendingDeliveries } from './views.js';
+import { pendingDeliveriesFromState } from './views.js';
+import { readWakeReleaseDiagnostics } from './wake-attempts.js';
 const DISPLAY_ORDER = [
     'awaiting',
     'wake-accepted',
@@ -19,37 +21,51 @@ const DISPLAY_FIELD_LIMIT = 160;
 export async function classifyDeliveryHealth(squarePath, opts) {
     const now = opts.now ?? Date.now();
     const env = opts.env ?? process.env;
-    const square = await openSquare(squarePath, { clock: () => now });
-    const pending = await pendingDeliveries(square).finally(() => closeOpenSquare(square));
-    const items = [];
-    for (const delivery of pending) {
-        for (const note of delivery.notifications) {
-            const ageMs = Math.max(0, now - note.item.at);
-            const evidence = await wakeEvidence(squarePath, note.recipient, note.item.index, now, env);
-            const kind = evidence.presented
-                ? 'presented-not-delivered'
-                : evidence.terminal?.outcome === 'accepted'
-                    ? 'wake-accepted'
-                    : evidence.terminal?.outcome === 'unknown'
-                        ? 'wake-unknown'
-                        : ageMs > opts.graceMs && evidence.attemptableRoutes.length === 0
-                            ? 'unreachable'
-                            : 'awaiting';
-            const attempt = evidence.terminal ?? evidence.attempts.at(-1);
-            items.push({
-                squarePath,
-                recipient: note.recipient,
-                actIndex: note.item.index,
-                actor: note.item.actor,
-                at: note.item.at,
-                ageMs,
-                route: note.route,
-                kind,
-                ...(attempt === undefined ? {} : { attempt }),
-            });
+    const square = await openSquare(squarePath, { clock: () => now, env });
+    try {
+        const { state } = await square.artifact.read();
+        const delivery = deriveDeliveryModel(state);
+        const pending = pendingDeliveriesFromState(state, delivery);
+        const evidenceProjection = await projectWakeEvidenceFromState({
+            location: squarePath,
+            state,
+            hostLedger: square.hostLedger,
+            now,
+            delivery,
+        });
+        const items = [];
+        for (const pendingDelivery of pending) {
+            for (const note of pendingDelivery.notifications) {
+                const ageMs = Math.max(0, now - note.item.at);
+                const evidence = evidenceProjection.evidence(pendingDelivery.recipient, note.item.index);
+                const kind = evidence.presented
+                    ? 'presented-not-delivered'
+                    : evidence.terminal?.outcome === 'accepted'
+                        ? 'wake-accepted'
+                        : evidence.terminal?.outcome === 'unknown'
+                            ? 'wake-unknown'
+                            : ageMs > opts.graceMs && evidence.attemptableRoutes.length === 0
+                                ? 'unreachable'
+                                : 'awaiting';
+                const attempt = evidence.terminal ?? evidence.attempts.at(-1);
+                items.push({
+                    squarePath,
+                    recipient: pendingDelivery.recipient,
+                    actIndex: note.item.index,
+                    actor: note.item.actor,
+                    at: note.item.at,
+                    ageMs,
+                    route: note.route,
+                    kind,
+                    ...(attempt === undefined ? {} : { attempt }),
+                });
+            }
         }
+        return items;
+    }
+    finally {
+        await closeOpenSquare(square);
     }
-    return items;
 }
 function displayField(value) {
     const truncated = truncateChars(value, DISPLAY_FIELD_LIMIT - 1);
@@ -59,24 +75,40 @@ function formatItem(item) {
     const evidence = item.attempt?.signature === undefined ? '' : ` · ${displayField(item.attempt.signature)}`;
     return `  · ${formatActivityId(item.actIndex)} → ${displayField(participantIdentity(item.recipient))} from ${displayField(participantIdentity(item.actor))} · ${formatDuration(item.ageMs)}${evidence}`;
 }
-export function renderDeliveryHealth(items) {
-    if (items.length === 0)
-        return ['✓ no pending delivery attention'];
-    const out = [`· delivery attention · ${items.length} pending`];
-    let displayed = 0;
-    for (const kind of DISPLAY_ORDER) {
-        const group = items.filter((item) => item.kind === kind);
-        if (group.length === 0)
-            continue;
-        out.push(`${ACTIONABLE.has(kind) ? '✕' : '○'} ${kind}: ${group.length}`);
-        const details = group.slice(0, DETAIL_LIMIT - displayed);
-        out.push(...details.map(formatItem));
-        displayed += details.length;
+export function renderDeliveryHealth(items, releases = [], now = Date.now()) {
+    const out = items.length === 0 ? ['✓ no pending delivery attention'] : [`· delivery attention · ${items.length} pending`];
+    if (items.length > 0) {
+        let displayed = 0;
+        for (const kind of DISPLAY_ORDER) {
+            const group = items.filter((item) => item.kind === kind);
+            if (group.length === 0)
+                continue;
+            out.push(`${ACTIONABLE.has(kind) ? '✕' : '○'} ${kind}: ${group.length}`);
+            const details = group.slice(0, DETAIL_LIMIT - displayed);
+            out.push(...details.map(formatItem));
+            displayed += details.length;
+        }
+        if (items.length > DETAIL_LIMIT)
+            out.push(`${DETAIL_LIMIT} of ${items.length} pending details shown`);
+    }
+    if (releases.length > 0) {
+        out.push(`· recent wake releases · ${releases.length}`);
+        out.push(...releases.slice(0, DETAIL_LIMIT).map((release) => formatRelease(release, now)));
+        if (releases.length > DETAIL_LIMIT)
+            out.push(`${DETAIL_LIMIT} of ${releases.length} wake releases shown`);
     }
-    if (items.length > DETAIL_LIMIT)
-        out.push(`${DETAIL_LIMIT} of ${items.length} pending details shown`);
     return out;
 }
+function formatRelease(release, now) {
+    const route = displayField(release.routeKind ?? 'unknown route');
+    const reason = displayField(release.signature ?? 'reason not recorded');
+    const age = formatDuration(Math.max(0, now - release.at));
+    const message = release.message === undefined ? '' : ` — ${displayField(release.message)}`;
+    const diagnostic = release.diagnostic === undefined ? '' : ` · ${displayField(JSON.stringify(release.diagnostic))}`;
+    return `  · ${formatActivityId(release.attention.actIndex)} → ${displayField(participantIdentity(release.attention.recipient))} · ${route} · ${reason} · ${age}${message}${diagnostic}`;
+}
 export async function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
-    return renderDeliveryHealth(await classifyDeliveryHealth(squarePath, { graceMs, now, env }));
+    const items = await classifyDeliveryHealth(squarePath, { graceMs, now, env });
+    const releases = await readWakeReleaseDiagnostics({ location: squarePath, now, env });
+    return renderDeliveryHealth(items, releases, now);
 }

package/dist/delivery-operations.js

@@ -4,6 +4,22 @@ import { nameKey } from './model.js';
 import { deriveDeliveryModel } from './delivery.js';
 import { currentSessionBindings, isWakeRouteAttemptable, presentationSuppressesWake, projectPresentationEvidence } from './square-projections.js';
 import { retireWakeRouteFromArtifact } from './routes.js';
+import { redactCurrentDiagnostic } from './diagnostic-redaction.js';
+async function releaseWakeClaim(input, details) {
+    await input.hostLedger.releaseEvidence({
+        location: input.location,
+        participant: input.participant,
+        session: input.session,
+        activity: input.activity,
+        kind: 'wake',
+        claimToken: input.claimToken,
+        ...(input.routeKind === undefined ? {} : { routeKind: input.routeKind }),
+        ...(input.attemptN === undefined ? {} : { attemptN: input.attemptN }),
+        signature: details.signature,
+        message: redactCurrentDiagnostic(details.message),
+        ...(details.diagnostic === undefined ? {} : { diagnostic: redactCurrentDiagnostic(details.diagnostic) }),
+    });
+}
 async function attemptWakeWithin(transport, request, timeoutMs, beforeSend) {
     let timer;
     const timeout = new Promise((resolve) => {
@@ -119,7 +135,10 @@ export async function deliverPending(input) {
                 if (lease.type === 'ambiguous') {
                     let recovered = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, claimToken: lease.lease.leaseId });
                     if (recovered.status === 'busy' && recovered.record.claimToken !== undefined) {
-                        await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken: recovered.record.claimToken });
+                        await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken: recovered.record.claimToken, routeKind: lease.lease.routeKind ?? route.route.kind, attemptN: lease.lease.attemptN }, {
+                            signature: 'stale_dispatch_claim_recovered',
+                            message: 'A stale dispatch claim was released so recovery could continue.',
+                        });
                         recovered = await input.hostLedger.claimEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', leaseMs, claimToken: lease.lease.leaseId });
                     }
                     if (recovered.status === 'acquired') {
@@ -168,7 +187,10 @@ export async function deliverPending(input) {
                 const claimToken = claim.claimToken;
                 const dispatching = await input.hostLedger.transitionWakeDispatch({ attention, leaseId, phase: 'dispatching', leaseMs, routeKind: route.route.kind, attemptN, session: route.session });
                 if (!dispatching) {
-                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken }).catch(() => undefined);
+                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
+                        signature: 'dispatch_claim_transition_failed',
+                        message: 'The wake dispatch claim could not enter the dispatching phase.',
+                    }).catch(() => undefined);
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
                     continue;
                 }
@@ -190,7 +212,11 @@ export async function deliverPending(input) {
                     && published.kind === route.route.kind
                     && JSON.stringify(published.address) === JSON.stringify(route.route.address));
                 if (!stillPending || !stillBound || !stillPublished) {
-                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken }).catch(() => undefined);
+                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
+                        signature: 'pre_send_revalidation_failed',
+                        message: 'Wake was not sent because the activity, session binding, or published route changed before dispatch.',
+                        diagnostic: { pending: stillPending, bound: stillBound, publishedRoute: stillPublished },
+                    }).catch(() => undefined);
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
                     continue;
                 }
@@ -200,7 +226,11 @@ export async function deliverPending(input) {
                 }
                 catch { /* capability is handled by the transport path */ }
                 if (presentationSuppressesWake(latestPresentations)) {
-                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken }).catch(() => undefined);
+                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
+                        signature: 'presentation_already_recorded',
+                        message: 'Wake was suppressed because presentation evidence already exists.',
+                        diagnostic: { outcomes: latestPresentations.map((row) => row.outcome) },
+                    }).catch(() => undefined);
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
                     continue;
                 }
@@ -221,13 +251,20 @@ export async function deliverPending(input) {
                     outcome = { outcome: 'unknown', diagnostic: error instanceof Error ? error.message : String(error) };
                 }
                 if (suppressedDuringSend) {
-                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken }).catch(() => undefined);
+                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
+                        signature: 'presentation_recorded_during_dispatch',
+                        message: 'Wake was cancelled because presentation evidence appeared before the final send check.',
+                    }).catch(() => undefined);
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
                     continue;
                 }
                 attempted += 1;
                 if (outcome.outcome === 'not-capable') {
-                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken }).catch(() => undefined);
+                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN }, {
+                        signature: 'transport_not_capable',
+                        message: 'The wake transport reported that it could not deliver this route.',
+                        diagnostic: outcome.diagnostic,
+                    }).catch(() => undefined);
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session }).catch(() => undefined);
                     notCapableForAttention = true;
                     continue;
@@ -235,12 +272,17 @@ export async function deliverPending(input) {
                 if (outcome.outcome === 'failed' && outcome.unavailable) {
                     if (outcome.routeStale === true)
                         await retireWakeRouteFromArtifact(input.artifact, { location: route.location, participant: route.participant, sessionId: route.session });
-                    await input.hostLedger.releaseEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', claimToken });
+                    await releaseWakeClaim({ hostLedger: input.hostLedger, location: input.location, participant: membership.recipient, session: route.session, activity, claimToken, routeKind: route.route.kind, attemptN: outcome.attemptN ?? attemptN }, {
+                        signature: outcome.signature ?? 'transport_unavailable',
+                        message: outcome.message ?? 'The wake transport was unavailable.',
+                        diagnostic: outcome.diagnostic,
+                    });
                     await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
                     failedForAttention = true;
                     continue;
                 }
-                await input.hostLedger.appendEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', outcome: outcome.outcome, routeKind: route.route.kind, attemptN: outcome.attemptN ?? attemptN, ...(outcome.outcome === 'accepted' && outcome.signature === undefined ? {} : outcome.outcome === 'accepted' ? { signature: outcome.signature } : outcome.outcome === 'failed' ? { message: outcome.message } : { diagnostic: outcome.diagnostic }), claimToken });
+                const safeOutcome = redactCurrentDiagnostic(outcome);
+                await input.hostLedger.appendEvidence({ location: input.location, participant: membership.recipient, session: route.session, activity, kind: 'wake', outcome: safeOutcome.outcome, routeKind: route.route.kind, attemptN: safeOutcome.attemptN ?? attemptN, ...(safeOutcome.signature === undefined ? {} : { signature: safeOutcome.signature }), ...(safeOutcome.outcome !== 'accepted' && safeOutcome.message !== undefined ? { message: safeOutcome.message } : {}), ...(safeOutcome.outcome !== 'accepted' && safeOutcome.diagnostic !== undefined ? { diagnostic: safeOutcome.diagnostic } : {}), claimToken });
                 await input.hostLedger.releaseWakeDispatch({ attention, leaseId, session: route.session });
                 if (outcome.outcome === 'accepted') {
                     acceptedForAttention = true;

package/dist/diagnostic-redaction.d.ts

@@ -0,0 +1,2 @@
+export declare function redactDiagnostic(value: unknown, secret: string | undefined): unknown;
+export declare function redactCurrentDiagnostic(value: unknown, env?: NodeJS.ProcessEnv): unknown;

package/dist/diagnostic-redaction.js

@@ -0,0 +1,40 @@
+const MAX_STRING_LENGTH = 1_000;
+const MAX_COLLECTION_ITEMS = 32;
+const MAX_NESTING = 8;
+function redactText(value, secret) {
+    const withoutSecret = secret?.trim() ? value.split(secret.trim()).join('[redacted]') : value;
+    const withoutUrlPassword = withoutSecret.replace(/([?&]password=)[^&\s]+/gi, '$1[redacted]');
+    return [...withoutUrlPassword].length <= MAX_STRING_LENGTH
+        ? withoutUrlPassword
+        : `${[...withoutUrlPassword].slice(0, MAX_STRING_LENGTH - 1).join('')}…`;
+}
+function redactValue(value, secret, seen, depth) {
+    if (typeof value === 'string')
+        return redactText(value, secret);
+    if (depth >= MAX_NESTING)
+        return '[truncated]';
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            return '[circular]';
+        seen.add(value);
+        return value.slice(0, MAX_COLLECTION_ITEMS).map((item) => redactValue(item, secret, seen, depth + 1));
+    }
+    if (value !== null && typeof value === 'object') {
+        if (seen.has(value))
+            return '[circular]';
+        seen.add(value);
+        return Object.fromEntries(Object.entries(value).slice(0, MAX_COLLECTION_ITEMS).map(([key, item]) => [
+            key,
+            /password|secret|api[-_]?key|token/i.test(key) && typeof item !== 'boolean'
+                ? '[redacted]'
+                : redactValue(item, secret, seen, depth + 1),
+        ]));
+    }
+    return value;
+}
+export function redactDiagnostic(value, secret) {
+    return redactValue(value, secret, new WeakSet(), 0);
+}
+export function redactCurrentDiagnostic(value, env = process.env) {
+    return redactDiagnostic(value, env.PASEO_PASSWORD);
+}

package/dist/help.js

@@ -66,7 +66,7 @@ const COMMANDS = [
     {
         names: ['harness'], usage: 'harness doctor [claude|codex|opencode|pi|delivery]', usesSquare: true, group: 'maintenance', hiddenFromIndex: true,
         summary: 'Diagnose installed agent-host support.',
-        details: ['Targets:', '  claude, codex, opencode, pi  Diagnose one installed adapter.', '  delivery                      Diagnose delivery for the selected square.'],
+        details: ['Targets:', '  claude, codex, opencode, pi  Diagnose one installed adapter.', '  delivery                      Diagnose pending delivery and recent wake-release reasons for the selected square.'],
     },
     {
         names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',

package/dist/host-ledger-file-adapter.js

@@ -154,11 +154,11 @@ export class FileHostLedgerPort {
         return { status: 'degraded', error };
     } }
     async releaseEvidence(i) { const f = this.file('user', 'evidence'), location = await canon(i.location), at = i.now ?? this.clock(); await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, at, true), same = (x) => x.kind === i.kind && x.location === location && nameKey(x.participant) === nameKey(i.participant) && x.activity === i.activity && x.session === i.session, current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== i.claimToken)
-        return; const tombstone = { ...current, outcome: 'released', at, expiresAt: undefined }; delete tombstone.expiresAt; await write(f, [...all.filter(x => x !== current), tombstone]); }); }
+        return; const tombstone = { ...current, outcome: 'released', at, ...(i.routeKind === undefined ? {} : { routeKind: i.routeKind }), ...(i.attemptN === undefined ? {} : { attemptN: i.attemptN }), ...(i.signature === undefined ? {} : { signature: i.signature }), ...(i.message === undefined ? {} : { message: i.message }), ...(i.diagnostic === undefined ? {} : { diagnostic: i.diagnostic }), expiresAt: undefined }; delete tombstone.expiresAt; await write(f, [...all.filter(x => x !== current), tombstone]); }); }
     async appendEvidence(i) { const f = this.file('user', 'evidence'), r = { ...i, location: await canon(i.location), at: i.at ?? this.clock(), v: 1 }; const token = i.claimToken; if (typeof token !== 'string' || token.length === 0)
         return; await withFileLock(f + '.lock', LOCK, async () => { const all = await read(f, r.at, true); const same = (x) => x.kind === r.kind && x.location === r.location && nameKey(x.participant) === nameKey(r.participant) && x.activity === r.activity && x.session === r.session; const current = all.findLast(x => same(x) && x.outcome === 'dispatching'); if (current === undefined || current.claimToken !== token)
         return; const terminalKey = (x) => same(x) && x.attemptN === r.attemptN && x.outcome !== 'dispatching' && x.outcome !== 'released'; await write(f, [...all.filter(x => x !== current && !terminalKey(x)), r]); }); }
-    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('user', 'evidence'), i.now ?? this.clock())).filter(r => r.outcome !== 'released' && (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
+    async listEvidence(i = {}) { const loc = i.location === undefined ? undefined : await canon(i.location); return (await read(this.file('user', 'evidence'), i.now ?? this.clock())).filter(r => (i.includeReleased === true || r.outcome !== 'released') && (!loc || r.location === loc) && (!i.participant || nameKey(r.participant) === nameKey(i.participant)) && (!i.session || r.session === i.session) && (!i.activity || r.activity === i.activity) && (!i.kind || r.kind === i.kind)); }
     async gcEvidence(i) { const f = this.file('user', 'evidence'), pending = new Set(i.pendingWakeActivities ?? []); await withFileLock(f + '.lock', LOCK, async () => write(f, (await read(f, this.clock(), true)).filter(r => r.at >= i.before || r.kind === 'wake' && r.outcome === 'accepted' && pending.has(r.activity)))); }
     async reconcileBinding(i = {}) { let b = []; try {
         b = [...await this.listPresence({ scopes: i.scopes, now: i.now })];

package/dist/host-ledger.d.ts

@@ -65,9 +65,15 @@ export interface EvidenceClaim {
     readonly claimToken?: string;
     readonly now?: number;
 }
-export type EvidenceRelease = Omit<EvidenceClaim, 'leaseMs'> & {
+/** Release metadata and includeReleased are diagnostic-only; default evidence reads stay behavior-safe. */
+export interface EvidenceRelease extends Omit<EvidenceClaim, 'leaseMs'> {
     readonly claimToken: string;
-};
+    readonly routeKind?: WakeRouteKind;
+    readonly attemptN?: number;
+    readonly signature?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
+}
 export interface EvidenceLookup {
     readonly location?: string;
     readonly participant?: string;
@@ -75,6 +81,7 @@ export interface EvidenceLookup {
     readonly activity?: string;
     readonly kind?: EvidenceRecord['kind'];
     readonly now?: number;
+    readonly includeReleased?: boolean;
 }
 export interface EvidenceGc {
     readonly before: number;

package/dist/notifications.js

@@ -102,28 +102,28 @@ export async function createDefaultWakeTransport(hostLedger, clock, env = proces
     const adapters = await defaultWakeAdapters();
     return createWakeTransport(env.SQUARE_DISABLE_PASEO_WAKE === '1' ? adapters.filter((adapter) => adapter.kind !== 'paseo') : adapters, hostLedger, clock);
 }
-async function wakeRequestIsCurrent(request, hostLedger, now) {
+async function wakeRequestCurrentness(request, hostLedger, now) {
     const activity = parseActivityId(request.activity);
     if (activity === undefined)
-        return false;
+        return { current: false, activityPending: false, sessionBound: false, routePublished: false, observationAvailable: true };
     let square;
     try {
         square = await openSquare(request.location, { hostLedger });
         const current = await observeSquare({ artifact: square.artifact, hostLedger, location: request.location, now });
-        const pending = current.pending.some((entry) => nameKey(entry.recipient) === nameKey(request.participant)
+        const activityPending = current.pending.some((entry) => nameKey(entry.recipient) === nameKey(request.participant)
             && entry.notifications.some((notification) => notification.item.index === activity));
-        const bound = current.bindings.some((binding) => nameKey(binding.participant) === nameKey(request.route.participant)
+        const sessionBound = current.bindings.some((binding) => nameKey(binding.participant) === nameKey(request.route.participant)
             && binding.sessionId === request.route.sessionId
             && binding.location === request.route.location);
-        const published = (current.state.routes ?? []).some((route) => route.location === request.route.location
+        const routePublished = (current.state.routes ?? []).some((route) => route.location === request.route.location
             && nameKey(route.participant) === nameKey(request.route.participant)
             && route.sessionId === request.route.sessionId
             && route.kind === request.route.kind
             && JSON.stringify(route.address) === JSON.stringify(request.route.address));
-        return pending && bound && published;
+        return { current: activityPending && sessionBound && routePublished, activityPending, sessionBound, routePublished, observationAvailable: true };
     }
     catch {
-        return false;
+        return { current: false, activityPending: false, sessionBound: false, routePublished: false, observationAvailable: false };
     }
     finally {
         if (square !== undefined)
@@ -151,15 +151,32 @@ export function createWakeTransport(adapters, hostLedger, clock) {
             if (adapter === undefined)
                 return { outcome: 'not-capable', diagnostic: `no adapter for ${request.route.kind}` };
             try {
-                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => (await (beforeSend ?? (async () => true))()) && await wakeRequestIsCurrent(request, hostLedger, clock()), timeoutMs);
+                let revalidation;
+                const result = await adapter.dispatch(request.route.address, renderWakePayload(request), async () => {
+                    if (!(await (beforeSend ?? (async () => true))()))
+                        return false;
+                    revalidation = await wakeRequestCurrentness(request, hostLedger, clock());
+                    return revalidation.current;
+                }, timeoutMs);
                 if (result.outcome === 'accepted')
                     return { outcome: 'accepted' };
                 if (result.outcome === 'failed')
-                    return { outcome: 'failed', message: result.message };
+                    return { outcome: 'failed', ...(result.signature === undefined ? {} : { signature: result.signature }), message: result.message, ...(result.diagnostic === undefined ? {} : { diagnostic: result.diagnostic }) };
                 if (result.outcome === 'unavailable')
-                    return { outcome: 'failed', message: result.message, unavailable: true, ...(result.retainRoute === true ? { retainRoute: true } : {}), ...(result.routeStale === true ? { routeStale: true } : {}) };
+                    return { outcome: 'failed', signature: result.signature, message: result.message, ...(result.diagnostic === undefined ? {} : { diagnostic: result.diagnostic }), unavailable: true, ...(result.retainRoute === true ? { retainRoute: true } : {}), ...(result.routeStale === true ? { routeStale: true } : {}) };
                 if (result.outcome === 'unknown')
-                    return { outcome: 'unknown', diagnostic: result.message };
+                    return { outcome: 'unknown', ...(result.signature === undefined ? {} : { signature: result.signature }), ...(result.message === undefined ? {} : { message: result.message }), ...(result.diagnostic === undefined ? {} : { diagnostic: result.diagnostic }) };
+                if (result.outcome === 'cancelled' && revalidation !== undefined && !revalidation.current) {
+                    return {
+                        outcome: 'failed',
+                        signature: 'pre_send_revalidation_failed',
+                        message: revalidation.observationAvailable
+                            ? 'Wake was not sent because current attention, session binding, or route no longer matches.'
+                            : 'Wake was not sent because current Square delivery state could not be verified.',
+                        diagnostic: revalidation,
+                        unavailable: true,
+                    };
+                }
                 return { outcome: 'unknown', diagnostic: 'wake dispatch cancelled' };
             }
             catch (error) {

package/dist/ports.d.ts

@@ -69,6 +69,8 @@ export type WakeOutcome = {
 } | {
     readonly outcome: 'failed';
     readonly message?: string;
+    readonly signature?: string;
+    readonly diagnostic?: unknown;
     readonly attemptN?: number;
     readonly unavailable?: boolean;
     readonly retainRoute?: boolean;
@@ -78,7 +80,9 @@ export type WakeOutcome = {
     readonly diagnostic?: string;
 } | {
     readonly outcome: 'unknown';
-    readonly diagnostic?: string;
+    readonly signature?: string;
+    readonly message?: string;
+    readonly diagnostic?: unknown;
     readonly attemptN?: number;
 };
 export interface SquareObservation {

package/dist/presentation.d.ts

@@ -49,6 +49,9 @@ export declare function withPathOutput(squarePath: string, body?: string, opts?:
 export declare function quoteShell(value: string): string;
 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;
+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;
 export declare function truncateChars(body: string, maxChars: number): {

package/dist/presentation.js

@@ -41,6 +41,13 @@ export function commandPrefix(squarePath) {
 export function participantCommandPrefix(squarePath, name) {
     return `square --location ${quoteShell(path.resolve(squarePath))} --as ${quoteShell(name)}`;
 }
+/** Blocked actions end with a full copy-pasteable recovery command. */
+export function joinRecoveryCommand(squarePath, name) {
+    return `» ${participantCommandPrefix(squarePath, name)} join`;
+}
+export function participantsRecoveryCommand(squarePath) {
+    return `» ${commandPrefix(squarePath)} participants`;
+}
 function formatAge(ms) {
     if (ms === undefined)
         return '(none)';

package/dist/wake-attempts.d.ts

@@ -7,6 +7,16 @@ export interface WakeAttention {
     actIndex: number;
     recipient: string;
 }
+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 WakeAttempt = ProjectedWakeAttempt;
 export interface WakeDispatchLease {
     readonly leaseId: string;
@@ -36,6 +46,14 @@ export declare function readWakeAttempts(opts?: {
     now?: number;
     env?: NodeJS.ProcessEnv;
 }): Promise<WakeAttempt[]>;
+export declare function redactWakeDiagnostic(value: unknown, env?: NodeJS.ProcessEnv): unknown;
+export declare function readWakeReleaseDiagnostics(opts?: {
+    location?: string;
+    attention?: WakeAttention;
+    sessionId?: string;
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<WakeReleaseDiagnostic[]>;
 export declare function recordWakeAttempt(attempt: Omit<WakeAttempt, 'at'> & {
     at?: number;
 }, env?: NodeJS.ProcessEnv): Promise<WakeAttempt>;

package/dist/wake-attempts.js

@@ -5,6 +5,7 @@ import { canonicalSquarePath } from './registry.js';
 import { formatActivityId, parseActivityId } from './square-core.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { terminalWakeEvidence } from './square-projections.js';
+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) {
@@ -44,17 +45,43 @@ export async function readWakeAttempts(opts = {}) {
     const keys = await Promise.all(scoped.map((attempt) => wakeAttentionKey(attempt.attention)));
     return scoped.filter((_, index) => keys[index] === expected);
 }
-function redact(value, secret) {
-    if (typeof value === 'string') {
-        const withoutKnownSecret = secret ? value.split(secret).join('[redacted]') : value;
-        return withoutKnownSecret.replace(/([?&]password=)[^&\s]+/gi, '$1[redacted]');
-    }
-    if (Array.isArray(value))
-        return value.map((item) => redact(item, secret));
-    if (value !== null && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redact(item, secret)]));
+export function redactWakeDiagnostic(value, env = process.env) {
+    return redactDiagnostic(value, env.PASEO_PASSWORD);
+}
+export async function readWakeReleaseDiagnostics(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const env = opts.env ?? process.env;
+    const rows = await ledger(env).listEvidence({
+        kind: 'wake',
+        location: opts.location ?? opts.attention?.squarePath,
+        includeReleased: true,
+        now,
+    });
+    const expected = opts.attention === undefined ? undefined : await wakeAttentionKey(opts.attention);
+    const releases = [];
+    for (const row of rows) {
+        if (row.outcome !== 'released')
+            continue;
+        const actIndex = parseActivityId(row.activity);
+        if (actIndex === undefined || row.at === undefined)
+            continue;
+        if (opts.sessionId !== undefined && row.session !== opts.sessionId)
+            continue;
+        const attention = { squarePath: row.location, recipient: row.participant, actIndex };
+        if (expected !== undefined && JSON.stringify([row.location, formatActivityId(actIndex), nameKey(row.participant)]) !== expected)
+            continue;
+        releases.push({
+            at: row.at,
+            attention,
+            ...(row.routeKind === undefined ? {} : { routeKind: row.routeKind }),
+            ...(row.attemptN === undefined ? {} : { attemptN: row.attemptN }),
+            ...(row.session === undefined ? {} : { session: row.session }),
+            ...(row.signature === undefined ? {} : { signature: row.signature }),
+            ...(row.message === undefined ? {} : { message: redactWakeDiagnostic(row.message, env) }),
+            ...(row.diagnostic === undefined ? {} : { diagnostic: redactWakeDiagnostic(row.diagnostic, env) }),
+        });
     }
-    return value;
+    return releases.sort((left, right) => right.at - left.at);
 }
 export async function recordWakeAttempt(attempt, env = process.env) {
     const value = { ...attempt, at: attempt.at ?? Date.now() };
@@ -63,7 +90,7 @@ export async function recordWakeAttempt(attempt, env = process.env) {
     if (value.outcome !== 'accepted' && !value.signature) {
         throw new Error(`${value.outcome} wake attempts require a transport signature.`);
     }
-    const safe = redact(value, env.PASEO_PASSWORD);
+    const safe = redactWakeDiagnostic(value, env);
     const session = safe.session ?? safe.signature ?? `route:${safe.routeKind}`;
     const claim = await ledger(env).claimEvidence({ location: safe.attention.squarePath, participant: safe.attention.recipient, session, activity: formatActivityId(safe.attention.actIndex), kind: 'wake', leaseMs: 5000 });
     if (claim.status === 'acquired')

package/dist/watch.js

@@ -6,7 +6,7 @@ import { closeOpenSquare } from './open-square.js';
 import { openParticipant } from './square-wiring.js';
 import { resolveParticipant, watchPresentation } from './views.js';
 import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
-import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, } from './presentation.js';
+import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, joinRecoveryCommand, participantsRecoveryCommand, withPathOutput, } from './presentation.js';
 import { hasAutomaticDeliveryIdentity } from './registry.js';
 import { parseActivityId } from './square-core.js';
 function watchStatusExitCode(status) {
@@ -150,6 +150,18 @@ export async function cmdWatch(squarePath, name, opts) {
     try {
         square = await openSquare(squarePath, { clock: nowMs });
         name = (await resolveParticipant(square, name)).name;
+    }
+    catch (err) {
+        if (isSquareError(err)) {
+            process.stderr.write(err.message + '\n');
+            // 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`);
+            process.exit(err.code === 'not_found' ? 1 : 2);
+        }
+        throw err;
+    }
+    try {
         if (opts.mention !== undefined)
             opts = { ...opts, mention: (await resolveParticipant(square, opts.mention)).name };
         if (opts.participants !== undefined && opts.participants.length > 0) {
@@ -157,8 +169,12 @@ export async function cmdWatch(squarePath, name, opts) {
         }
     }
     catch (err) {
+        await closeOpenSquare(square).catch(() => undefined);
         if (isSquareError(err)) {
             process.stderr.write(err.message + '\n');
+            // 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`);
             process.exit(err.code === 'not_found' ? 1 : 2);
         }
         throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.56",
+  "version": "0.3.58",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {