@astrosheep/square 0.3.58 → 0.3.62

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

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

package/claude-plugin/skills/square/SKILL.md

@@ -63,9 +63,9 @@ The ownership boundary belongs here. Does this match your read?
 EOF
 ```
 
-**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. An `@name` in the body is ordinary Markdown and does not address anyone. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
+**Addressing.** Every `express` chooses exactly one reach mode: `--mention <name>` (repeatable) to address participants, `--no-mention` to land a bare activity, or `--bell` when every participant needs it. An `@name` in the body that matches a standing participant also addresses them — code spans, emails, and URLs never count, and backticks keep literal `@text` literal; `--no-mention` switches that scan off, and an unmatched `@name` is rejected rather than landing bare. Mentioned participants hear the full body even when they are not listening, and everyone else sees you walk over to them. `listen` opts a participant into future bare delivery. Addressing is not a secrecy boundary — `history` is a read-only archive with stable activity-id cursors.
 
-Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, or `--bell`. The CLI rejects an omitted mode and rejects combining these modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.
+Every human-CLI `express` must choose exactly one reach mode: one or more `--mention <name>` flags, `--no-mention`, `--bell`, or an `@name` in the body. The CLI rejects an omitted mode and rejects combining these flag modes. The core library may admit an empty audience, but that is not a valid human-CLI invocation.
 
 **Discipline.** Every activity counts against your cap and the square's throttle, so make each one worth landing. Keep private progress and tool chatter out — express only when another participant needs the thought, question, or decision.
 
@@ -128,13 +128,11 @@ square --location <square> --as <name> resume
 `done` is permanent, not the end of a conversation round. Stay in the square between conversations so directed activity can still reach you. Use `done` only after you no longer want to participate in or receive anything from this square — the whole square sees you go:
 
 ```bash
-square --location <square> --as <name> done - <<'EOF'
-*pushes the chair back*
-
-Final state, decision, or handoff.
-EOF
+square --location <square> --as <name> done
 ```
 
+`done` only leaves the square and takes no message. Send any activity with `express` before leaving.
+
 ## Environment
 
 - `SQUARE_LOCATION` sets the square location.

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

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

package/dist/activity.d.ts

@@ -1,10 +1,14 @@
 export interface ActivityOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
     force?: boolean;
-    forceCommand: string;
     noWait?: boolean;
+    noMention?: boolean;
     mentions?: readonly string[];
     reach?: import('./model.js').Reach;
-    reply?: number;
+    reply?: string;
 }
 export declare function saveActivityDraft(squarePath: string, name: string, body: string): string;
+/** Retry commands preserve the original reach, reply, wait and force choices. */
+export declare function activityRetryCommand(squarePath: string, name: string, opts: ActivityOptions, force?: boolean): string;
 export declare function cmdActivity(squarePath: string, name: string, activity: string, resolveBody: (arg: string) => string, opts: ActivityOptions): Promise<void>;

package/dist/activity.js

@@ -1,17 +1,18 @@
 import crypto from 'node:crypto';
 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, joinRecoveryCommand, withPathOutput, } from './presentation.js';
+import { expressHintLine, formatRefusal, renderActivityBlocked, renderActivityLimit, renderActivityUncertain, renderExpressNoWait, renderExpressWaiting, renderPendingFeed, joinRecoveryCommand, participantIdentity, participantsRecoveryCommand, participantCommandPrefix, commandPrefix, quoteShell, takeoverRecoveryLines, withPathOutput, } from './presentation.js';
 import { nowMs, SLEEP_MS } from './runtime.js';
+import { unreadActivitySummaries } from './decisions.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
-import { Square } from './square-wiring.js';
+import { createSquareApplication } from './square-application.js';
 import { activityPresentation, resolveParticipant } from './views.js';
-import { formatActivityId } from './square-core.js';
-import { formatTimestamp } from './time.js';
-import { createHostLedgerPort } from './host-ledger-file-adapter.js';
+import { formatActivityId, parseActivityId } from './square-core.js';
+import { formatDuration } from './time.js';
+import { style } from './tty-style.js';
+import { hostLedgerForEnv } from './registry.js';
 import { createDefaultWakeTransport } from './notifications.js';
 function draftDirFor(squarePath) {
     return path.join(path.dirname(squarePath), 'drafts');
@@ -40,140 +41,176 @@ export function saveActivityDraft(squarePath, name, body) {
         }
     }
 }
+/** Retry commands preserve the original reach, reply, wait and force choices. */
+export function activityRetryCommand(squarePath, name, opts, force = opts.force ?? false) {
+    const reach = opts.reach === 'bell' ? ' --bell'
+        : opts.mentions?.length ? opts.mentions.map((target) => ` --mention ${quoteShell(target)}`).join('')
+            : opts.noMention === true ? ' --no-mention'
+                : '';
+    const replyIndex = opts.reply === undefined ? undefined : parseActivityId(opts.reply);
+    const reply = opts.reply === undefined ? '' : ` --reply ${replyIndex === undefined ? quoteShell(opts.reply) : formatActivityId(replyIndex)}`;
+    return `${participantCommandPrefix(squarePath, name)} express${force ? ' --force' : ''}${opts.noWait ? ' --no-wait' : ''}${reach}${reply} -`;
+}
 export async function cmdActivity(squarePath, name, activity, resolveBody, opts) {
-    validateName(name);
-    const rawInput = String(resolveBody(activity)).replace(/\r\n/g, '\n');
-    const reader = await openSquare(squarePath, { clock: nowMs });
-    let knownName;
-    try {
-        knownName = (await resolveParticipant(reader, name)).name;
-    }
-    catch (err) {
-        await closeOpenSquare(reader);
-        if (isSquareError(err)) {
-            if (err.code === 'unknown_participant' || err.code === 'invalid_args') {
-                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');
-            process.exit(err.code === 'not_found' ? 1 : 2);
+    const rawInput = String(resolveBody(activity));
+    const env = { ...(opts.env ?? process.env) };
+    const hostLedger = hostLedgerForEnv(env);
+    const retryCommand = activityRetryCommand(squarePath, name, opts);
+    const forceCommand = activityRetryCommand(squarePath, name, opts, true);
+    let knownName = name;
+    let callerMissing = false;
+    let expressAttempted = false;
+    let landedId;
+    let announcedWait;
+    async function presentation() {
+        const square = await openSquare(squarePath, { clock: nowMs, env, hostLedger });
+        try {
+            return await activityPresentation(square, knownName);
+        }
+        finally {
+            await closeOpenSquare(square);
         }
-        throw err;
     }
-    await closeOpenSquare(reader);
-    const body = rawInput.trim();
-    const force = opts.force ?? false;
-    const noWait = opts.noWait ?? false;
-    const reach = opts.reach === 'bell' ? 'bell' : undefined;
-    let announcedWait;
-    const ledgerRoot = process.env.SQUARE_REGISTRY === undefined ? undefined : path.dirname(process.env.SQUARE_REGISTRY);
-    const hostLedger = createHostLedgerPort({ userPath: process.env.SQUARE_HOST_LEDGER_USER ?? ledgerRoot, localPath: process.env.SQUARE_HOST_LEDGER_LOCAL ?? ledgerRoot });
-    const square = await Square.at({ path: squarePath, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs) });
     try {
-        const participant = await square.join(name);
-        while (true) {
-            const beforeSquare = await openSquare(squarePath, { clock: nowMs });
-            const before = await activityPresentation(beforeSquare, knownName).finally(() => closeOpenSquare(beforeSquare));
-            const pendingPublic = before.pendingPublic;
-            const pendingRoomChanges = before.pendingRoomChanges;
-            try {
-                await participant.express(body, {
-                    force,
-                    ...(opts.mentions === undefined ? {} : { mentions: opts.mentions }),
-                    ...(reach === undefined ? {} : { reach }),
-                    ...(opts.reply === undefined ? {} : { reply: formatActivityId(opts.reply) }),
-                });
-                const freshSquare = await openSquare(squarePath, { clock: nowMs });
-                const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
-                const headerCount = fresh.participantCount;
-                const held = fresh.held;
-                const ownActCount = fresh.ownActivityCount;
-                const hasPending = pendingPublic.length > 0 || pendingRoomChanges.length > 0;
-                const pending = hasPending ? `\n\n${renderPendingFeed([...fresh.activities], [...pendingPublic], [...pendingRoomChanges], knownName, fresh.state)}` : '';
-                const hint = expressHintLine(ownActCount);
-                const confirmation = `● heads turn your way — #${ownActCount}`;
-                const withHint = hint ? `${confirmation}\n${hint}` : confirmation;
-                process.stdout.write(withPathOutput(squarePath, withHint + pending, { participantCount: headerCount, held }));
+        validateName(name);
+        for (const target of opts.mentions ?? [])
+            validateName(target);
+        if (opts.reply !== undefined && parseActivityId(opts.reply) === undefined) {
+            throw new SquareError('invalid_args', 'Invalid --reply: expected an activity id like act/12');
+        }
+        const reader = await openSquare(squarePath, { clock: nowMs, env, hostLedger });
+        try {
+            knownName = (await resolveParticipant(reader, name)).name;
+        }
+        catch (error) {
+            // The caller name was validated above; invalid_args here means it is absent
+            // from the roster. Keep the join recovery distinct from recipient validation.
+            callerMissing = isSquareError(error) && error.code === 'invalid_args';
+            throw error;
+        }
+        finally {
+            await closeOpenSquare(reader);
+        }
+        const application = createSquareApplication({ cwd: opts.cwd ?? process.cwd(), env, squarePath, clock: nowMs, hostLedger, wakeTransport: await createDefaultWakeTransport(hostLedger, nowMs), participant: name });
+        // The caller is roster-known at this point, so a landed join act is always a
+        // re-entry after done — never a first arrival. Announce it; a silent return
+        // would make `done` a fake exit.
+        const entry = await application.join();
+        const reentered = entry.kind === 'joined' && entry.activity !== null;
+        const before = await presentation();
+        const pendingPublic = before.pendingPublic;
+        const pendingRoomChanges = before.pendingRoomChanges;
+        expressAttempted = true;
+        const landed = await application.express(rawInput.replace(/\r\n/g, '\n').trim(), {
+            force: opts.force ?? false,
+            noWait: opts.noWait ?? false,
+            ...(opts.mentions === undefined ? {} : { mentions: opts.mentions }),
+            ...(opts.noMention === undefined ? {} : { noMention: opts.noMention }),
+            ...(opts.reach === undefined ? {} : { reach: opts.reach }),
+            // The action boundary validates the raw id before attempting a commit.
+            ...(opts.reply === undefined ? {} : { reply: opts.reply }),
+        }, {
+            onProgress: (progress) => {
+                if (announcedWait === progress.reason)
+                    return;
+                const delayMs = progress.delayMs ?? SLEEP_MS;
+                process.stdout.write(renderExpressWaiting({
+                    reason: progress.reason,
+                    ...(progress.reason === 'throttled' ? { delayMs } : {}),
+                    ...(progress.holder === undefined ? {} : { holder: progress.holder }),
+                    ...(progress.holdReason === undefined ? {} : { holdReason: progress.holdReason }),
+                }) + '\n');
+                announcedWait = progress.reason;
+            },
+        });
+        landedId = landed.activity.id;
+        const fresh = await presentation();
+        const headerCount = fresh.participantCount;
+        const held = fresh.held;
+        const ownActCount = fresh.ownActivityCount;
+        const hasPending = pendingPublic.length > 0 || pendingRoomChanges.length > 0;
+        const pending = hasPending ? `\n\n${renderPendingFeed([...fresh.activities], [...pendingPublic], [...pendingRoomChanges], knownName, fresh.state)}` : '';
+        const hint = expressHintLine(ownActCount);
+        const reachEcho = landed.activity.reach === 'bell'
+            ? ' · to everyone (bell)'
+            : landed.activity.mentions.length > 0
+                ? ` · to ${landed.activity.mentions.map((target) => participantIdentity(target)).join(', ')}`
+                : '';
+        const confirmation = `● your activity lands${style('dim', ` — #${ownActCount} · ${landed.activity.id}${reachEcho}`)}`;
+        const withHint = hint ? `${confirmation}\n${style('dim', hint)}` : confirmation;
+        const reentry = reentered ? '● you stepped back into the square\n' : '';
+        process.stdout.write(withPathOutput(squarePath, reentry + withHint + pending, { participantCount: headerCount, held }));
+    }
+    catch (error) {
+        // Save before any recovery read: even a broken artifact must not eat the body.
+        const draftPath = saveActivityDraft(squarePath, name, rawInput);
+        const confirmedUnsent = landedId === undefined && (!expressAttempted || (isSquareError(error) && error.facts?.activityUnsent === true));
+        const fresh = await presentation().catch(() => undefined);
+        const output = { squarePath, name: knownName, draftPath, participantCount: fresh?.participantCount, held: fresh?.held };
+        if (!confirmedUnsent) {
+            process.stderr.write(renderActivityUncertain({ ...output, landedId, detail: error instanceof Error ? error.message : String(error) }));
+            process.exit(1);
+            return;
+        }
+        if (isSquareError(error) && fresh !== undefined) {
+            if (error.code === 'behind') {
+                process.stdout.write(renderActivityBlocked({
+                    ...output,
+                    retryCommand,
+                    forceCommand,
+                    activitySummaries: unreadActivitySummaries(fresh.state, knownName, nowMs()),
+                    unreadRoomChanges: [],
+                }));
+                process.exit(1);
                 return;
             }
-            catch (error) {
-                if (!(error instanceof SquareError))
-                    throw error;
-                const freshSquare = await openSquare(squarePath, { clock: nowMs });
-                const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
-                const headerCount = fresh.participantCount;
-                const held = fresh.held;
-                if (error.code === 'behind') {
-                    const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                    process.stdout.write(renderActivityBlocked({
-                        squarePath,
-                        name: knownName,
-                        forceCommand: opts.forceCommand,
-                        activitySummaries: [],
-                        unreadRoomChanges: [...pendingRoomChanges],
-                        draftPath,
-                        participantCount: headerCount,
-                        held,
-                    }));
-                    process.exit(1);
-                    return;
-                }
-                if (error.code === 'capped') {
-                    process.stdout.write(renderActivityLimit({
-                        squarePath,
-                        name: knownName,
-                        count: fresh.ownActivityCount,
-                        ...(fresh.hardCap === null ? {} : { hardCap: fresh.hardCap }),
-                        draftPath: saveActivityDraft(squarePath, name, rawInput),
-                        participantCount: headerCount,
-                        held,
-                    }));
-                    process.exit(1);
-                    return;
-                }
-                if (error.code === 'throttled') {
-                    const delayMs = error.facts?.retryAfterMs ?? SLEEP_MS;
-                    if (noWait) {
-                        const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'throttled', delayMs, draftPath, participantCount: headerCount, held, forceCommand: opts.forceCommand }));
-                        process.exit(1);
-                    }
-                    if (announcedWait !== 'throttled') {
-                        process.stdout.write(renderExpressWaiting({ reason: 'throttled', delayMs }) + '\n');
-                        announcedWait = 'throttled';
-                    }
-                    await sleep(delayMs);
-                    continue;
-                }
-                if (error.code === 'held') {
-                    const holdReason = fresh.holdReason;
-                    if (noWait) {
-                        const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'held', holdReason, draftPath, participantCount: headerCount, held, forceCommand: opts.forceCommand }));
-                        process.exit(1);
-                    }
-                    if (announcedWait !== 'held') {
-                        process.stdout.write(renderExpressWaiting({ reason: 'held' }) + '\n');
-                        announcedWait = 'held';
-                    }
-                    await sleep(SLEEP_MS);
-                    continue;
-                }
-                if (error.code === 'bell_quota') {
-                    const nextAt = nowMs() + (error.facts?.retryAfterMs ?? 1);
-                    process.stdout.write(withPathOutput(squarePath, [`✕ the bell stays quiet for now`, `  · you can ring it again at ${formatTimestamp(nextAt)}`].join('\n'), { participantCount: headerCount, held }));
-                    process.exit(1);
-                    return;
-                }
-                throw error;
+            if (error.code === 'capped') {
+                process.stdout.write(renderActivityLimit({
+                    ...output,
+                    count: fresh.ownActivityCount,
+                    ...(fresh.hardCap === null ? {} : { hardCap: fresh.hardCap }),
+                }));
+                process.exit(1);
+                return;
+            }
+            if (error.code === 'throttled' || error.code === 'held') {
+                process.stdout.write(renderExpressNoWait({
+                    ...output,
+                    reason: error.code,
+                    delayMs: error.facts?.retryAfterMs ?? SLEEP_MS,
+                    holdReason: fresh.holdReason,
+                    retryCommand,
+                }));
+                process.exit(1);
+                return;
+            }
+            if (error.code === 'bell_quota') {
+                process.stdout.write(withPathOutput(squarePath, [
+                    '✕ the bell stays quiet for now',
+                    `  · you can ring it again in ${formatDuration(error.facts?.retryAfterMs ?? 1)}`,
+                    `· draft kept: ${draftPath}`,
+                    `  · retry when the bell is ready:`,
+                    `${retryCommand} < ${quoteShell(draftPath)}`,
+                ].join('\n'), output));
+                process.exit(1);
+                return;
             }
         }
-    }
-    finally {
-        await square.close();
+        const lines = [error instanceof Error ? error.message : String(error), `· draft kept: ${draftPath}`];
+        if (isSquareError(error)) {
+            if (callerMissing || error.code === 'unknown_participant' || error.code === 'not_joined')
+                lines.push(joinRecoveryCommand(squarePath, name));
+            if (error.code === 'already_joined')
+                lines.push(...takeoverRecoveryLines(squarePath, name));
+            if (error.code === 'invalid_args' || error.code === 'invalid_name') {
+                if (opts.mentions?.length)
+                    lines.push(participantsRecoveryCommand(squarePath));
+                if (opts.reply !== undefined)
+                    lines.push(`${commandPrefix(squarePath)} history --limit 10`);
+            }
+        }
+        lines.push('  · correct the problem above before retrying; keep your intended recipients and reply:', `${retryCommand} < ${quoteShell(draftPath)}`);
+        process.stderr.write(formatRefusal(squarePath, lines, output));
+        process.exit(2);
     }
 }

package/dist/artifact.d.ts

@@ -20,6 +20,10 @@ export declare function createSquareFile(squarePath: string, state: SquareState)
  * conflicts. The URI remains create-disabled throughout the retry loop.
  */
 export declare function readSquareSnapshot(squarePath: string, signal?: AbortSignal): Promise<SquareSnapshot>;
+/** Check the artifact revision without loading or parsing the historical state. */
+export declare function readSquareRevision(squarePath: string, signal?: AbortSignal): Promise<number>;
+/** One reference-counted revision detector per canonical artifact in this process. */
+export declare function observeSquareRevision(squarePath: string): Promise<import('./file-changes.js').VersionObserver<number>>;
 export type SquareTransition<R> = (state: SquareState, revision: number) => {
     state?: SquareState;
     result: R;

package/dist/artifact.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { isDeepStrictEqual } from 'node:util';
+import { observeFileVersion } from './file-changes.js';
 import { InternalSquareError, SquareError } from './model.js';
 import { validateSquareState } from './square-state.js';
 const APPLICATION_ID = 0x53515245;
@@ -86,19 +87,26 @@ function isOwnedSnapshotSchema(database) {
             && column.pk === expected.pk && column.hidden === expected.hidden;
     });
 }
+function validateDatabaseHeader(database) {
+    const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
+    if (identity.application_id !== APPLICATION_ID)
+        throw invalidArtifact('unrelated SQLite database.');
+    if (identity.user_version !== USER_VERSION)
+        throw invalidArtifact('unsupported SQLite format version.');
+    if (!isOwnedSnapshotSchema(database))
+        throw invalidArtifact('unsupported snapshot schema.');
+}
+function validateSnapshotRevision(rows) {
+    if (rows.length !== 1 || rows[0].id !== 1 || !Number.isSafeInteger(rows[0].revision) || rows[0].revision < 0)
+        throw invalidArtifact('snapshot row is malformed.');
+    return rows[0].revision;
+}
 function validateDatabase(database) {
     try {
-        const identity = database.prepare('SELECT application_id, user_version FROM pragma_application_id, pragma_user_version').get();
-        if (identity.application_id !== APPLICATION_ID)
-            throw invalidArtifact('unrelated SQLite database.');
-        if (identity.user_version !== USER_VERSION)
-            throw invalidArtifact('unsupported SQLite format version.');
-        if (!isOwnedSnapshotSchema(database))
-            throw invalidArtifact('unsupported snapshot schema.');
+        validateDatabaseHeader(database);
         const rows = database.prepare(`SELECT id, revision, state FROM ${SNAPSHOT_TABLE}`).all();
-        if (rows.length !== 1 || rows[0].id !== 1 || !Number.isSafeInteger(rows[0].revision) || rows[0].revision < 0)
-            throw invalidArtifact('snapshot row is malformed.');
-        return { state: parseState(rows[0].state), revision: rows[0].revision };
+        const revision = validateSnapshotRevision(rows);
+        return { state: parseState(rows[0].state), revision };
     }
     catch (error) {
         if (error instanceof SquareError)
@@ -112,12 +120,12 @@ function configureDatabase(database) {
     database.exec('PRAGMA busy_timeout = 0; PRAGMA journal_mode = DELETE; PRAGMA synchronous = FULL;');
 }
 /** Opens an existing artifact without permitting SQLite to create a missing path. */
-function readSquareSnapshotOnce(squarePath) {
+function readExistingArtifact(squarePath, read) {
     requireSquareExtension(squarePath);
     let database;
     try {
         database = openExistingDatabase(squarePath);
-        return validateDatabase(database);
+        return read(database);
     }
     catch (error) {
         if (error instanceof SquareError)
@@ -132,6 +140,16 @@ function readSquareSnapshotOnce(squarePath) {
         closeQuietly(database);
     }
 }
+function readSquareSnapshotOnce(squarePath) {
+    return readExistingArtifact(squarePath, validateDatabase);
+}
+function readSquareRevisionOnce(squarePath) {
+    return readExistingArtifact(squarePath, (database) => {
+        validateDatabaseHeader(database);
+        const rows = database.prepare(`SELECT id, revision FROM ${SNAPSHOT_TABLE}`).all();
+        return validateSnapshotRevision(rows);
+    });
+}
 async function createTemporaryArtifact(squarePath) {
     const directory = path.dirname(squarePath);
     await fs.promises.mkdir(directory, { recursive: true });
@@ -236,12 +254,23 @@ async function pauseForBusy(signal) {
  * Reads a complete validated snapshot, yielding between transient SQLite lock
  * conflicts. The URI remains create-disabled throughout the retry loop.
  */
-export async function readSquareSnapshot(squarePath, signal) {
+export function readSquareSnapshot(squarePath, signal) {
+    return readWithBusyRetry(() => readSquareSnapshotOnce(squarePath), signal);
+}
+/** Check the artifact revision without loading or parsing the historical state. */
+export function readSquareRevision(squarePath, signal) {
+    return readWithBusyRetry(() => readSquareRevisionOnce(squarePath), signal);
+}
+/** One reference-counted revision detector per canonical artifact in this process. */
+export function observeSquareRevision(squarePath) {
+    return observeFileVersion(squarePath, 'square-revision', readSquareRevision);
+}
+async function readWithBusyRetry(read, signal) {
     while (true) {
         if (signal?.aborted)
             throw signal.reason ?? closedError();
         try {
-            return readSquareSnapshotOnce(squarePath);
+            return read();
         }
         catch (error) {
             if (!isBusy(error))

package/dist/attention-presentation.d.ts

@@ -11,4 +11,5 @@ export interface AttentionPreview {
 export declare function previewAttentionBody(body: string): string;
 export declare function attentionBodyIsClipped(body: string): boolean;
 export declare function displayAttentionPath(squarePath: string): string;
+export declare function renderAttentionDescription({ actor, recipient, route }: Pick<AttentionPreview, 'actor' | 'recipient' | 'route'>): string;
 export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -16,30 +16,32 @@ export function displayAttentionPath(squarePath) {
         ? `~${squarePath.slice(homedir().length)}`
         : squarePath;
 }
+export function renderAttentionDescription({ actor, recipient, route }) {
+    switch (route) {
+        case 'mention': return `${actor} addressed you (${recipient})`;
+        case 'attention': return `${actor} spoke · you’re listening to ${actor}`;
+        case 'bell': return `${actor} rang the bell · everyone’s attention`;
+    }
+}
 export function renderAttentionPreview(attention) {
-    const attentionKind = attention.route === 'bell' ? 'bell' : 'attention';
-    const attributes = {
-        location: displayAttentionPath(attention.squarePath),
-        id: formatActivityId(attention.actIndex),
-        from: attention.actor,
-        to: attention.recipient,
-        kind: attentionKind,
-    };
-    const entries = Object.entries(attributes);
-    const [lastKey, lastValue] = entries[entries.length - 1];
+    // The fence is what keeps the body from being re-rendered by Markdown. It grows past any
+    // backtick run in the body so a body containing a fence cannot break out of this one.
+    // Everything outside the fence is the system's voice, which participant bodies cannot fake.
+    const fence = '`'.repeat(Math.max(3, longestBacktickRun(attention.body) + 1));
     return [
-        '<square-activity',
-        // The opening tag must never emit a standalone `>` line: Markdown renders it as a blockquote.
-        ...entries.slice(0, -1).map(([key, value]) => `  ${key}="${escapeAttribute(value)}"`),
-        `  ${lastKey}="${escapeAttribute(lastValue)}">`,
+        `${fence}square-activity`,
+        `· ${displayAttentionPath(attention.squarePath)} · ${formatActivityId(attention.actIndex)}`,
+        `● ${renderAttentionDescription(attention)}`,
+        '',
         previewAttentionBody(attention.body),
-        '</square-activity>',
+        fence,
+        // A clipped body ends with the full command to read it all: a labeled caption, then the
+        // command bare on its own line so it can be copied and run as it is.
         ...(attentionBodyIsClipped(attention.body)
-            ? [`» ${participantCommandPrefix(attention.squarePath, attention.recipient)} catch --id ${formatActivityId(attention.actIndex)}`]
+            ? ['· clipped — read it all:', `${participantCommandPrefix(attention.squarePath, attention.recipient)} catch --id ${formatActivityId(attention.actIndex)}`]
             : []),
     ].join('\n');
 }
-function escapeAttribute(value) {
-    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-        .replace(/\r/g, '&#13;').replace(/\n/g, '&#10;').replace(/\t/g, '&#9;');
+function longestBacktickRun(value) {
+    return value.match(/`+/g)?.reduce((longest, run) => Math.max(longest, run.length), 0) ?? 0;
 }