@astrosheep/square 0.3.57 → 0.3.61

package/dist/runtime.js

@@ -184,6 +184,43 @@ export function readCursor(squareState, name, landed = replayLandedAudiences(squ
 export function latestActIndex(acts) {
     return acts.reduce((max, act) => Math.max(max, act.index), -1);
 }
+/**
+ * "Was here" is a claim of presence, so it rides on evidence: the participant's own acts
+ * and seen receipts after their latest join. Anything else — in particular acts merely
+ * not addressed to them — says nothing about where they actually were.
+ */
+export function presenceEvidenceCursor(squareState, name, landed = replayLandedAudiences(squareState.acts)) {
+    const recipient = landed.resolveParticipant(name) ?? name;
+    const boundary = landed.lastJoinIndex(recipient) ?? -1;
+    if (boundary < 0)
+        return -1;
+    let evidence = boundary;
+    for (const act of squareState.acts) {
+        if (act.index <= boundary || act.index <= evidence || act.actor === undefined)
+            continue;
+        if (sameName(act.actor, recipient)
+            || squareState.runtime.observations?.[recipient]?.[formatActivityId(act.index)]?.state === 'seen') {
+            evidence = act.index;
+        }
+    }
+    return evidence;
+}
+/** The last public act the participant was verifiably present for, or -1 when there is no evidence. */
+export function presenceAnchor(squareState, name, landed = replayLandedAudiences(squareState.acts)) {
+    const recipient = landed.resolveParticipant(name) ?? name;
+    const boundary = landed.lastJoinIndex(recipient) ?? -1;
+    if (boundary < 0)
+        return -1;
+    const evidence = presenceEvidenceCursor(squareState, recipient, landed);
+    for (let i = squareState.acts.length - 1; i >= 0; i--) {
+        const event = squareState.acts[i];
+        if (event.index <= boundary || event.index > evidence)
+            continue;
+        if (event.kind === 'say' || event.kind === 'done')
+            return event.index;
+    }
+    return -1;
+}
 export function freshWatchLease(squareState, name, at = Date.now()) {
     const key = canonicalRuntimeName(squareState, name);
     const lease = watchLease(squareState, key);

package/dist/square-actions.js

@@ -29,7 +29,7 @@ export async function catchUp(square, name, options = {}, project) {
     const deadline = Date.now() + idle;
     while (true) {
         if (!await assertLiveOwner(square, name)) {
-            throw new SquareError('already_joined', `${participantIdentity(name)} is already bound to another session`);
+            throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`);
         }
         const attempt = await square.artifact.transact((state, version) => {
             const decision = decideCatch(state, name, options, square.clock(), project);
@@ -192,7 +192,7 @@ export async function takeover(square, name, _oldSessionIds = []) {
             return committed;
         });
         if (outcome.status === 'busy')
-            throw new SquareError('already_joined', `${participantIdentity(name)} is already bound to another session`);
+            throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`);
         return { name: outcome.result.name, activities: outcome.result.stored.map(exposeActivity), epoch: outcome.epoch };
     }
     const committed = await commitLifecycle();
@@ -227,7 +227,7 @@ export async function implicitJoin(square, name) {
 }
 export async function express(square, name, body, options = {}) {
     if (!await assertLiveOwner(square, name)) {
-        throw new SquareError('already_joined', `${participantIdentity(name)} is already bound to another session`);
+        throw new SquareError('already_joined', `✕ ${participantIdentity(name)} already stands here — another session holds the name`);
     }
     const now = square.clock();
     const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
@@ -280,7 +280,7 @@ async function landCore(square, verb, actor, body = '', fence = {}) {
     // be completed by a stale done — an old expected epoch refuses instead of appending.
     const commit = async () => {
         if (verb === 'done' && !await assertLiveOwner(square, actor, fence.expectedEpoch)) {
-            throw new SquareError('already_done', `${participantIdentity(actor)} is already bound to another session`);
+            throw new SquareError('already_done', `✕ ${participantIdentity(actor)} already stands here — another session holds the name`);
         }
         const now = square.clock();
         return square.artifact.transact((state) => {

package/dist/stream.js

@@ -52,6 +52,6 @@ export async function cmdStreamNdjson(squarePath, recipient, start = { kind: 'ta
 }
 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.js

@@ -1,9 +1,9 @@
-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)}`);
@@ -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;
 }

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

@@ -1,12 +1,12 @@
 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 { SLEEP_MS, 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 { 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 +37,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 +61,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 +109,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`);
@@ -144,19 +144,30 @@ async function cmdWatchNow(squarePath, name, opts) {
         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) {
     let square;
+    let participantCount;
     try {
         square = await openSquare(squarePath, { clock: nowMs });
+        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,12 +180,14 @@ 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;

package/extensions/square-pi.js

@@ -31,12 +31,20 @@ export function renderPiInbox(inbox) {
 
 const NOTIFY_BODY_MAX = 80;
 
+function framePiMessage(content) {
+  return `\n${content.replace(/^\n+/, '').replace(/\n+$/, '')}\n`;
+}
+
 export function summarizePendingForNotify(pending) {
   const lines = pending.flatMap((membership) => membership.notifications.map((note) => {
-    const verb = note.route === 'bell' ? 'rang the bell for' : note.route === 'mention' ? 'walked over to' : 'paid attention to';
+    const verb = note.route === 'bell'
+      ? 'rang the bell'
+      : note.route === 'mention'
+        ? `called your name (${membership.name})`
+        : `spoke within your earshot (${membership.name})`;
     const body = note.body.replace(/\s+/g, ' ').trim();
     const clipped = body.length > NOTIFY_BODY_MAX ? `${body.slice(0, NOTIFY_BODY_MAX).trimEnd()}…` : body;
-    return `${note.actor} ${verb} ${membership.name}${clipped ? ` — ${clipped}` : ''}`;
+    return `${note.actor} ${verb}${clipped ? ` — ${clipped}` : ''}`;
   }));
   if (lines.length === 0) return undefined;
   return lines.length === 1 ? `■ square · ${lines[0]}` : `■ square · ${lines[0]} (+${lines.length - 1} more)`;
@@ -203,10 +211,11 @@ export default function squarePiExtension(pi) {
             // reaches the model; a brief notify tells the human what just landed.
             const summary = summarizePendingForNotify(pending);
             if (summary) ui?.notify?.(summary, 'info');
-            const landing = waitForLanding(content, signal, 'steer');
+            const messageContent = framePiMessage(content);
+            const landing = waitForLanding(messageContent, signal, 'steer');
             try {
               Promise.resolve(pi.sendMessage(
-                { customType: 'square', content, display: false },
+                { customType: 'square', content: messageContent, display: false },
                 { deliverAs: 'steer', triggerTurn: true },
               )).catch((error) => landing.ack.settle(error));
             } catch (error) {
@@ -266,10 +275,11 @@ export default function squarePiExtension(pi) {
     const signal = watcherAbort.signal;
     void automaticSessionStart('pi', sessionId, sessionCwd, sessionEnv(sessionId)).then((context) => {
       if (context === undefined || sessionId === undefined || token !== generation) return;
-      const landing = waitForLanding(context, signal, 'nextTurn');
+      const messageContent = framePiMessage(context);
+      const landing = waitForLanding(messageContent, signal, 'nextTurn');
       try {
         Promise.resolve(pi.sendMessage(
-          { customType: 'square', content: context, display: true },
+          { customType: 'square', content: messageContent, display: true },
           { deliverAs: 'nextTurn' },
         )).catch((error) => landing.ack.settle(error));
       } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.57",
+  "version": "0.3.61",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -21,8 +21,8 @@
     "sync-manifests": "node scripts/sync-manifests.mjs",
     "release": "npm version patch && npm run sync-manifests -- --commit && npm publish && git push --follow-tags",
     "prepublishOnly": "npm run sync-manifests && npm run build && npm run verify-release",
-    "test": "npm run build && node --test test/*.test.js",
-    "test:cli-process": "npm run build && node --test test/process/square-cli-render.test.js"
+    "test": "npm run build && node --import ./test/sandbox-env.js --test test/*.test.js",
+    "test:cli-process": "npm run build && node --import ./test/sandbox-env.js --test test/process/square-cli-render.test.js"
   },
   "keywords": [
     "brainstorm",