@astrosheep/square 0.3.58 → 0.3.62

package/dist/presentation.js

@@ -3,16 +3,18 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { participantIdentity } from './participant-identity.js';
 export { participantIdentity } from './participant-identity.js';
-import { audienceIncludes, audienceOf, MAX_IDENTITY_SET_SIZE } from './square-core.js';
+import { audienceIncludes, audienceOf, MAX_IDENTITY_SET_SIZE, replayLandedAudiences } from './square-core.js';
 import { perceiveActivity } from './delivery.js';
-import { actId, publicActs, readCursor, rosterNames, sayNumberFor } from './runtime.js';
+import { actId, presenceAnchor, publicActs, rosterNames, sayNumberFor, HELD_WAIT_BUDGET_MS } from './runtime.js';
 import { formatDuration, formatRelativeTime, formatTimestamp } from './time.js';
 import { compareParticipantActivity } from './decisions.js';
 import { grepSnippet } from './search.js';
+import { style } from './tty-style.js';
 function headerLine(squarePath, opts = {}) {
     const count = opts.participantCount ?? 0;
     const heldSuffix = opts.held ? ' — a hand is raised' : '';
-    return `· the square at ${displayPath(squarePath)} — ${count} in the square${heldSuffix}`;
+    const line = `· ${displayPath(squarePath)} — ${count} in the square${heldSuffix}`;
+    return opts.plain === true ? line : style('dim', line);
 }
 export function displayPath(squarePath, cwd = process.cwd()) {
     if (!path.isAbsolute(squarePath))
@@ -32,6 +34,14 @@ export function displayPath(squarePath, cwd = process.cwd()) {
 export function withPathOutput(squarePath, body = '', opts = {}) {
     return [headerLine(squarePath, opts), ...(body === '' ? [] : ['', body])].join('\n') + '\n';
 }
+/** The same header/blank/body layout as withPathOutput, for refusal bodies written to stderr. */
+export function formatRefusal(squarePath, bodyLines, opts = {}) {
+    const body = bodyLines.join('\n');
+    // A refusal with no known count stays bare rather than claiming "0 in the square".
+    if (opts.participantCount === undefined)
+        return body === '' ? '' : `${body}\n`;
+    return withPathOutput(squarePath, body, { ...opts, plain: true });
+}
 export function quoteShell(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -43,10 +53,17 @@ export function participantCommandPrefix(squarePath, name) {
 }
 /** Blocked actions end with a full copy-pasteable recovery command. */
 export function joinRecoveryCommand(squarePath, name) {
-    return `» ${participantCommandPrefix(squarePath, name)} join`;
+    return `${participantCommandPrefix(squarePath, name)} join`;
+}
+/** Taking a name is an explicit recovery choice, never an automatic retry. */
+export function takeoverRecoveryLines(squarePath, name) {
+    return [
+        'If this is your name to reclaim, --kick banishes the one standing here so you can step in:',
+        `${participantCommandPrefix(squarePath, name)} join --kick`,
+    ];
 }
 export function participantsRecoveryCommand(squarePath) {
-    return `» ${commandPrefix(squarePath)} participants`;
+    return `${commandPrefix(squarePath)} participants`;
 }
 function formatAge(ms) {
     if (ms === undefined)
@@ -68,6 +85,10 @@ function presenceGlyph(participant) {
         return '●';
     return '○';
 }
+function styledPresenceGlyph(participant) {
+    const glyph = presenceGlyph(participant);
+    return glyph === '○' ? style('dim', glyph) : glyph;
+}
 function presenceText(participant, now) {
     if (participant.state === 'done') {
         return participant.lastActiveAt === undefined ? 'stepped out of the square' : `stepped out of the square · ${formatRelativeTime(participant.lastActiveAt, now)}`;
@@ -86,17 +107,17 @@ export function renderPresenceLines(participants, now, limit = 5) {
         .sort(compareParticipantActivity);
     const shown = recent.slice(0, limit);
     if (shown.length === 0)
-        return ['  ○ nobody nearby'];
-    const lines = shown.map((p) => `  ${presenceGlyph(p)} ${participantIdentity(p.name)} · ${presenceText(p, now)}`);
+        return [style('dim', '  ○ nobody nearby')];
+    const lines = shown.map((p) => `  ${styledPresenceGlyph(p)} ${participantIdentity(p.name)}${style('dim', ` · ${presenceText(p, now)}`)}`);
     const remaining = recent.length - shown.length;
     if (remaining > 0)
-        lines.push(`  ○ …and ${remaining} more`);
+        lines.push(style('dim', `  ○ … ${remaining} more nearby`));
     return lines;
 }
 const EXPRESS_HINTS = [
     '*asterisks* are your body — *slams table*, *sketches in the air*, *shrugs*',
     "you're standing in a square — words and gestures both land",
-    'the square is for conversation — share thoughts and engage with others, beyond status updates and empty acknowledgments',
+    'the square runs on conversation — say things that move it, not nods that fill it',
 ];
 export function expressHintLine(ownActivityCount) {
     if (ownActivityCount !== 1 && ownActivityCount % 5 !== 0)
@@ -119,7 +140,7 @@ export function truncateExternalDiagnostic(diagnostic) {
 }
 function previewBody(body, maxLen = BODY_PREVIEW_LENGTH) {
     const preview = truncateChars(body, maxLen);
-    return preview.remaining === 0 ? preview.text : `${preview.text}\n… ${preview.remaining} more chars`;
+    return preview.remaining === 0 ? preview.text : `${preview.text}\n${style('dim', `… ${preview.remaining} more chars`)}`;
 }
 const UNREAD_PREVIEW_CHARS = 120;
 export function previewActivityBody(body) {
@@ -127,7 +148,7 @@ export function previewActivityBody(body) {
     if (compact === '')
         return '(empty)';
     const preview = truncateChars(compact, UNREAD_PREVIEW_CHARS);
-    return preview.remaining === 0 ? preview.text : `${preview.text}… (+${preview.remaining} chars)`;
+    return preview.remaining === 0 ? preview.text : `${preview.text}${style('dim', `… (+${preview.remaining} chars)`)}`;
 }
 export function renderRoomChangeText(event) {
     const actor = event.actor ?? 'someone';
@@ -166,7 +187,7 @@ export function renderEventCli(event, opts = {}) {
         case 'hold':
             return `· ${renderRoomChangeText(event)}`;
         case 'resume':
-            return `✓ ${renderRoomChangeText(event)}`;
+            return `${style('release', '✓')} ${renderRoomChangeText(event)}`;
         case 'listen':
         case 'ignore':
             return `· ${renderRoomChangeText(event)}`;
@@ -177,11 +198,12 @@ export function renderEventCli(event, opts = {}) {
                 ? ` · calls your name across the square — ${participantIdentity(mention)}`
                 : '';
             const replySuffix = event.reply === undefined ? '' : ` · replies to ${actId(event.reply)}`;
-            return `● ${participantIdentity(event.actor)} #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, now)}${mentionSuffix}${replySuffix}${bodySuffix(body)}`;
+            const meta = ` #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, now)}${mentionSuffix}${replySuffix}`;
+            return `● ${participantIdentity(event.actor)}${style('dim', meta)}${bodySuffix(body)}`;
         }
         case 'done': {
             const body = renderedBody(event.body, maxBody);
-            return `○ ${participantIdentity(event.actor)} stepped out of the square — done · ${actId(event)} · ${formatRelativeTime(event.at, now)}${bodySuffix(body)}`;
+            return `${style('dim', '○')} ${participantIdentity(event.actor)} stepped out of the square — done${style('dim', ` · ${actId(event)} · ${formatRelativeTime(event.at, now)}`)}${bodySuffix(body)}`;
         }
         case 'read':
             return '';
@@ -190,8 +212,9 @@ export function renderEventCli(event, opts = {}) {
 function renderPresenceOnlySay(event, opts = {}) {
     const audience = audienceOf(event);
     const targets = audience.kind === 'bell' ? [] : audience.names;
+    const meta = style('dim', ` #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, opts.now)}`);
     if (targets.length === 0) {
-        return `● ${participantIdentity(event.actor)} #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, opts.now)}`;
+        return `● ${participantIdentity(event.actor)}${meta}`;
     }
     const visibleTargets = targets.slice(0, MAX_IDENTITY_SET_SIZE).map((name) => participantIdentity(name));
     const remainingTargets = targets.length - visibleTargets.length;
@@ -199,7 +222,7 @@ function renderPresenceOnlySay(event, opts = {}) {
         ...visibleTargets,
         ...(remainingTargets === 0 ? [] : [`${remainingTargets} ${remainingTargets === 1 ? 'other' : 'others'}`]),
     ].join(' and ')}`;
-    return `● ${participantIdentity(event.actor)} #${opts.actNumber ?? 1} · ${actId(event)} · ${formatRelativeTime(event.at, opts.now)}\n  talked to${dest}`;
+    return `● ${participantIdentity(event.actor)}${meta}\n${style('dim', `  talked to${dest}`)}`;
 }
 export function renderAmbientEvent(event, viewer, opts = {}) {
     if (event.kind !== 'say')
@@ -216,7 +239,7 @@ export function renderAmbientEvent(event, viewer, opts = {}) {
     return renderEventCli(event, opts);
 }
 function draftSavedLines(draftPath) {
-    return draftPath === undefined ? [] : [`· draft kept: ${draftPath}`];
+    return draftPath === undefined ? [] : [style('dim', `· draft kept: ${draftPath}`)];
 }
 function withDraftInput(command, draftPath) {
     return draftPath === undefined ? command : `${command} < ${quoteShell(draftPath)}`;
@@ -229,15 +252,15 @@ function renderUnreadSummary(opts) {
             ...item.previews.slice(-1).map((preview) => {
                 const rendered = renderAmbientEvent(preview.act, opts.viewer, { actNumber: preview.number, perception: preview.perception });
                 if (rendered === '')
-                    return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago`;
+                    return style('dim', `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago`);
                 if (preview.perception === 'presence') {
-                    return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · ${rendered.replace(/\n/g, ' ')}`;
+                    return style('dim', `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · ${rendered.replace(/\n/g, ' ')}`);
                 }
-                return `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · "${previewActivityBody(preview.act.body)}"`;
+                return style('dim', `  · ${participantIdentity(item.name)} spoke — ${formatAge(item.latestActivityAgeMs)} ago · "${previewActivityBody(preview.act.body)}"`);
             }),
         ]),
-        ...(remainingSummaries === 0 ? [] : [`  · ${remainingSummaries} more participants have unread activity`]),
-        ...opts.roomChanges.map((act) => `  · ${renderRoomChangeText(act)}`),
+        ...(remainingSummaries === 0 ? [] : [style('dim', `  · ${remainingSummaries} more participants have unread activity`)]),
+        ...opts.roomChanges.map((act) => style('dim', `  · ${renderRoomChangeText(act)}`)),
     ];
 }
 export function renderPendingFeed(history, publicItems, roomChanges, viewer = '', squareState) {
@@ -261,35 +284,58 @@ export function renderPendingFeed(history, publicItems, roomChanges, viewer = ''
 export function renderActivityBlocked(opts) {
     const readNowCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} catch --now`;
     return withPathOutput(opts.squarePath, [
-        "✕ your activity doesn't land — the square moved behind your back",
+        `${style('blocked', '✕')} your activity doesn't land — the square moved behind your back`,
         ...renderUnreadSummary({ activitySummaries: opts.activitySummaries, roomChanges: opts.unreadRoomChanges, viewer: opts.name }),
         ...draftSavedLines(opts.draftPath),
-        `» ${readNowCommand}`,
-        '  take it in, then express again',
-        `» ${withDraftInput(opts.forceCommand, opts.draftPath)}`,
-        '  only if you truly mean to express over unread activity',
+        `${readNowCommand}`,
+        '  · take it in, then retry:',
+        withDraftInput(opts.retryCommand, opts.draftPath),
+        '  · optional: express over unread activity with --force:',
+        withDraftInput(opts.forceCommand, opts.draftPath),
     ].join('\n'), { participantCount: opts.participantCount, held: opts.held });
 }
+/** An indeterminate or already-committed send only points to inspection, never resend. */
+export function renderActivityUncertain(opts) {
+    return formatRefusal(opts.squarePath, [
+        opts.landedId === undefined
+            ? '✕ your activity may have landed — check history before sending again'
+            : `✕ your activity landed · ${opts.landedId} — the confirmation could not finish`,
+        ...(opts.detail === undefined ? [] : [`  · ${truncateExternalDiagnostic(opts.detail)}`]),
+        ...draftSavedLines(opts.draftPath),
+        '  · the draft is a saved copy; sending it again could repeat your activity',
+        `${commandPrefix(opts.squarePath)} history${opts.landedId === undefined ? ' --limit 10' : ` --at ${opts.landedId}`} --no-truncate`,
+    ], opts);
+}
 export function renderExpressWaiting(opts) {
     if (opts.reason === 'throttled') {
-        return ['✕ the square is packed', `  · your activity is waiting · next opening in ${formatDuration(opts.delayMs)}`].join('\n');
+        return [
+            '✕ the square is packed',
+            `  · your activity is waiting · next opening in ${formatDuration(opts.delayMs)}`,
+            '  · --no-wait saves a draft and returns now',
+        ].join('\n');
     }
-    return ["✕ your activity doesn't land — a hand is raised", '  · your activity is waiting'].join('\n');
+    const holder = opts.holder === undefined ? 'a hand is raised' : `${participantIdentity(opts.holder)} raised a hand`;
+    return [
+        `✕ your activity doesn't land — ${holder}`,
+        ...(opts.holdReason === undefined ? [] : [`  · ${opts.holdReason}`]),
+        `  · your activity is waiting — after ${formatDuration(HELD_WAIT_BUDGET_MS)} it saves a draft and stops`,
+        '  · --no-wait saves a draft and returns now',
+    ].join('\n');
 }
 export function renderExpressNoWait(opts) {
-    const retryCommand = opts.forceCommand;
+    const retryCommand = opts.retryCommand;
     const lines = opts.reason === 'throttled'
         ? [
-            '✕ the square is packed',
+            `${style('blocked', '✕')} the square is packed`,
             `  · next opening in ${formatDuration(opts.delayMs)}`,
             ...draftSavedLines(opts.draftPath),
-            `» ${withDraftInput(retryCommand, opts.draftPath)}`,
+            `${withDraftInput(retryCommand, opts.draftPath)}`,
         ]
         : [
-            "✕ your activity doesn't land — a hand is raised",
-            `  · ${opts.holdReason ?? 'the square holds its breath'}`,
+            `${style('blocked', '✕')} your activity doesn't land — a hand is raised`,
+            style('dim', `  · ${opts.holdReason ?? 'the square holds its breath'}`),
             ...draftSavedLines(opts.draftPath),
-            `» ${withDraftInput(retryCommand, opts.draftPath)}`,
+            `${withDraftInput(retryCommand, opts.draftPath)}`,
         ];
     return withPathOutput(opts.squarePath, lines.join('\n'), { participantCount: opts.participantCount, held: opts.held });
 }
@@ -302,32 +348,24 @@ export function renderPublicTail(squareState, events, lastN, now, viewer = '') {
         .filter(Boolean)
         .join('\n\n');
 }
-function lastPresenceAnchor(squareState, name) {
-    const cursor = readCursor(squareState, name);
-    for (let i = squareState.acts.length - 1; i >= 0; i--) {
-        const event = squareState.acts[i];
-        const index = event.index;
-        if (index > cursor)
-            continue;
-        if (event.kind === 'say' || event.kind === 'done')
-            return index;
-    }
-    return -1;
+function lastPresenceAnchor(squareState, name, landed) {
+    return presenceAnchor(squareState, name, landed);
 }
 export function renderPresenceAnchor(names) {
     const visibleNames = names.slice(0, MAX_IDENTITY_SET_SIZE);
     const participants = visibleNames.map((name) => participantIdentity(name)).join(', ');
     const remaining = names.length - visibleNames.length;
     const suffix = remaining === 0 ? '' : ` and ${remaining} more`;
-    return names.length === 1 ? `→ ${participants} was here` : `→ ${participants}${suffix} were here`;
+    return style('dim', names.length === 1 ? `→ ${participants} was here` : `→ ${participants}${suffix} were here`);
 }
 export function renderActivitiesView(squareState, visible, lastN, noTruncate, squarePath, viewer = '', mode = 'ambient') {
     const publicVisible = visible.filter((act) => act.kind === 'say' || act.kind === 'done');
     const shown = lastN == null ? publicVisible : publicVisible.slice(-lastN);
     const previewLen = noTruncate ? undefined : BODY_PREVIEW_LENGTH;
     const markers = new Map();
+    const landed = replayLandedAudiences(squareState.acts);
     for (const participant of rosterNames(squareState)) {
-        const anchor = lastPresenceAnchor(squareState, participant);
+        const anchor = lastPresenceAnchor(squareState, participant, landed);
         if (anchor >= 0)
             markers.set(anchor, [...(markers.get(anchor) ?? []), participant]);
     }
@@ -351,15 +389,13 @@ export function renderActivitiesView(squareState, visible, lastN, noTruncate, sq
     if (previewLen !== undefined) {
         const truncated = shown.some((act) => act.kind === 'say' && act.body.length > previewLen && (mode === 'archive' || perceiveActivity(squareState, act, viewer) === 'full'));
         if (truncated)
-            chunks.push(`» ${commandPrefix(squarePath)} history --no-truncate`);
+            chunks.push(`${commandPrefix(squarePath)} history --no-truncate`);
     }
     return chunks.join('\n\n');
 }
 const GREP_PREVIEW_CHARS = 160;
 function highlightGrepMatch(text) {
-    if (!process.stdout.isTTY || process.env.NO_COLOR !== undefined || text === '')
-        return text;
-    return `\x1b[38;5;222m\x1b[1m${text}\x1b[0m`;
+    return style('match', text);
 }
 export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squarePath, pattern, fixed = false, perception) {
     const publicVisible = visible.filter((act) => act.kind === 'say' || act.kind === 'done');
@@ -370,19 +406,20 @@ export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squa
     let truncated = false;
     for (const act of publicVisible) {
         const rawBody = act.body ?? '';
+        const header = `${style('dim', actId(act.index))} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${style('dim', formatTimestamp(act.at))}`;
         if (perception?.(act) === 'presence') {
-            chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}`);
+            chunks.push(header);
             continue;
         }
         if (noTruncate === true) {
             const body = rawBody.split('\n').map((line) => `  ${line}`).join('\n');
-            chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}\n${body}`);
+            chunks.push(`${header}\n${body}`);
             continue;
         }
         const snippet = grepSnippet(rawBody, pattern, GREP_PREVIEW_CHARS, fixed);
         if (snippet === undefined) {
             const preview = previewBody(rawBody, GREP_PREVIEW_CHARS);
-            chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}${preview === '' ? '' : `\n  ${preview}`}`);
+            chunks.push(`${header}${preview === '' ? '' : `\n  ${preview}`}`);
             continue;
         }
         const clippedBefore = snippet.beforeOmitted > 0;
@@ -390,25 +427,26 @@ export function renderGrepActivitiesView(visible, totalMatches, noTruncate, squa
         truncated ||= clippedBefore || clippedAfter;
         const text = `${clippedBefore ? '… ' : ''}${snippet.before}${highlightGrepMatch(snippet.match)}${snippet.after}${clippedAfter ? ' …' : ''}`;
         const omitted = clippedBefore || clippedAfter
-            ? `\n  · ${snippet.beforeOmitted} chars before · ${snippet.afterOmitted} chars after`
+            ? `\n${style('dim', `  · ${snippet.beforeOmitted} chars before · ${snippet.afterOmitted} chars after`)}`
             : '';
-        chunks.push(`${actId(act.index)} · ${act.actor === undefined ? 'unknown' : participantIdentity(act.actor)} · ${formatTimestamp(act.at)}\n  ${text.trim()}${omitted}`);
+        chunks.push(`${header}\n  ${text.trim()}${omitted}`);
     }
     if (publicVisible.length === 1) {
-        chunks.push(`» ${commandPrefix(squarePath)} history --at ${actId(publicVisible[0].index)} -C 2${truncated ? ' --no-truncate' : ''}`);
+        chunks.push(`${commandPrefix(squarePath)} history --at ${actId(publicVisible[0].index)} -C 2${truncated ? ' --no-truncate' : ''}`);
     }
     else if (truncated && publicVisible.length > 1) {
-        chunks.push(`» ${commandPrefix(squarePath)} history --at ${actId(publicVisible[0].index)} -C 2 --no-truncate`);
+        chunks.push(`${commandPrefix(squarePath)} history --at ${actId(publicVisible[0].index)} -C 2 --no-truncate`);
     }
     return chunks.join('\n\n');
 }
 function renderActivityLimitBody(opts) {
     const countText = opts.count !== undefined && opts.hardCap !== undefined ? ` (${opts.count}/${opts.hardCap})` : '';
-    const doneCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} done -`;
+    const doneCommand = `${participantCommandPrefix(opts.squarePath, opts.name)} done`;
     return [
-        `✕ your activity doesn't land — the cap is reached${countText}`,
+        `${style('blocked', '✕')} your activity doesn't land — the cap is reached${countText}`,
         ...draftSavedLines(opts.draftPath),
-        `» ${withDraftInput(doneCommand, opts.draftPath)}`,
+        '  · your draft stays unsent; done only steps out',
+        doneCommand,
     ].join('\n');
 }
 export function renderActivityLimit(opts) {
@@ -416,17 +454,17 @@ export function renderActivityLimit(opts) {
 }
 export function renderWatchAlreadyActive(opts) {
     return [
-        '✕ you are already catching',
+        `${style('blocked', '✕')} you are already catching`,
         `  · an active catch is already running for ${participantIdentity(opts.name)}`,
-        '  · wait for it to finish before starting another catch',
-        `» ${commandPrefix(opts.squarePath)} participants`,
+        '  · --replace lets a new catch take over',
+        `${participantCommandPrefix(opts.squarePath, opts.name)} catch --idle 30m --replace`,
     ].join('\n');
 }
 export function renderWatchForceTakeover(_opts) {
     return '✓ your new catch takes over';
 }
 export function renderWatchReplaceMissing(_opts) {
-    return '⚠ nothing to replace — no active catch was running; your catch started normally';
+    return '· no catch stood here — yours takes the spot';
 }
 export function renderWatchReplaced(_opts) {
     return '✕ a newer catch took over';
@@ -443,26 +481,26 @@ export function renderWatchStatus(opts) {
         case 'empty-now': {
             const prefix = participantCommandPrefix(opts.squarePath, opts.name);
             const quiet = opts.status === 'stale' && opts.idleMs !== undefined
-                ? `○ ${formatDuration(opts.idleMs)} of quiet — nothing new for you`
-                : '○ only footsteps in the square — nothing new for you';
+                ? style('dim', `○ ${formatDuration(opts.idleMs)} of quiet — nothing new for you`)
+                : style('dim', '○ only footsteps in the square — nothing new for you');
             return [
                 quiet,
                 ...(opts.showCatchHint === false
                     ? []
-                    : [`» ${prefix} catch --idle 30m`, `  glance: ${prefix} catch --now`]),
+                    : [`${prefix} catch --idle 30m`, `  glance: ${prefix} catch --now`]),
                 ...presenceLines,
             ].join('\n');
         }
         case 'quorum':
-            return ['✓ everyone else has left — the square is yours alone', `» ${participantCommandPrefix(opts.squarePath, opts.name)} done -`].join('\n');
+            return [`${style('release', '✓')} everyone else has left — the square is yours alone`, `${participantCommandPrefix(opts.squarePath, opts.name)} done`].join('\n');
         case 'capped':
-            return ['✕ nothing left in you — the cap is reached', `» ${participantCommandPrefix(opts.squarePath, opts.name)} done -`].join('\n');
+            return [`${style('blocked', '✕')} nothing left in you — the cap is reached`, `${participantCommandPrefix(opts.squarePath, opts.name)} done`].join('\n');
     }
 }
 function renderRoomChanges(changes) {
     if (changes.length === 0)
         return '';
-    return ['▲ while your back was turned', ...changes.map((act) => `  · ${renderRoomChangeText(act)}`)].join('\n');
+    return [`${style('changed', '▲')} while your back was turned`, ...changes.map((act) => `  · ${renderRoomChangeText(act)}`)].join('\n');
 }
 export function renderDoctorClean() {
     return '✓ no problems found';
@@ -481,7 +519,7 @@ export function renderWatchOutput(history, publicItems, roomChanges, opts) {
             quiet,
             ...(opts.showCatchHint === false
                 ? []
-                : [`» ${prefix} catch --idle 30m`, `  glance: ${prefix} catch --now`]),
+                : [`${prefix} catch --idle 30m`, `  glance: ${prefix} catch --now`]),
         ].join('\n'));
     }
     const publicIndexes = new Set(publicItems.map((item) => item.index));

package/dist/presented.js

@@ -1,9 +1,10 @@
 import os from 'node:os';
+import { hostLedgerRoot } from './host-ledger-root.js';
 import path from 'node:path';
 import { canonicalSquarePath } from './registry.js';
 import { createHostLedgerPort } from './host-ledger-file-adapter.js';
 import { formatActivityId } from './square-core.js';
 import { projectPresentationEvidence } from './square-projections.js';
 export function presentedPath(env = process.env) { return env.SQUARE_PRESENTED || path.join(os.homedir(), '.square', 'presented.ndjsonl'); }
-function evidence(env = process.env) { const file = presentedPath(env); return createHostLedgerPort({ userPath: env.SQUARE_HOST_LEDGER_USER ?? path.dirname(file), writableScope: 'user', readableScopes: ['user'] }); }
+function evidence(env = process.env) { const file = presentedPath(env); return createHostLedgerPort({ rootPath: hostLedgerRoot(env) }); }
 export async function hasPresentedForOwner(sessionId, squarePath, name, actIndex, env = process.env, now = Date.now()) { const resolved = await canonicalSquarePath(squarePath); return (await projectPresentationEvidence({ hostLedger: evidence(env), now, location: resolved, participant: name, sessionId, activity: formatActivityId(actIndex) })).some((row) => row.outcome === 'presented'); }

package/dist/registry.d.ts

@@ -1,6 +1,6 @@
 /** Machine-local participant discovery cache. */
 import { type StoredAct } from './model.js';
-import type { PresenceRecord } from './host-ledger.js';
+import type { HostLedgerPort, PresenceRecord } from './host-ledger.js';
 export type SessionChannel = 'claude-code' | 'codex' | 'opencode' | 'pi' | 'paseo' | 'unknown';
 export interface RegistryBinding {
     sessionId: string;
@@ -26,7 +26,7 @@ export declare function registryPath(env?: NodeJS.ProcessEnv): string;
 export declare function canonicalSquarePath(squarePath: string): Promise<string>;
 export declare function presenceEpoch(record: PresenceWithEpoch | undefined): number;
 /** Runs `fn` inside the ownership claim critical section, under the same lock as claims and finalize. */
-export declare function withOwnershipClaimLock<T>(env: NodeJS.ProcessEnv, fn: () => Promise<T>): Promise<T>;
+export declare function withOwnershipClaimLock<T>(env: NodeJS.ProcessEnv, fn: () => Promise<T>, signal?: AbortSignal): Promise<T>;
 export declare function recordJoin(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): Promise<void>;
 export declare function recordDone(sessionId: string, name: string, squarePath: string, options?: RegistryWriteOptions): Promise<void>;
 export declare function readActiveBindings(now?: number, env?: NodeJS.ProcessEnv): Promise<RegistryBinding[]>;
@@ -45,6 +45,7 @@ export type CurrentParticipantBinding = Readonly<{
 }>;
 export type OwnershipClaim = {
     readonly status: 'acquired' | 'owned';
+    readonly record: PresenceWithEpoch;
     readonly sessionId: string;
     readonly epoch: number;
 } | undefined;
@@ -63,7 +64,8 @@ export type TakeoverRunResult<T> = {
 };
 export declare function readParticipantOwner(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<RegistryBinding | undefined>;
 export declare function sessionOwnsParticipant(squarePath: string, name: string, sessionId: string, env?: NodeJS.ProcessEnv, expectedEpoch?: number): Promise<boolean>;
-export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<OwnershipClaim>;
+export declare function releaseSessionParticipantClaim(squarePath: string, name: string, env: NodeJS.ProcessEnv, claim: OwnershipClaim): Promise<void>;
+export declare function claimSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<OwnershipClaim>;
 /**
  * Fenced takeover: the ownership claim and the lifecycle run as one critical section under the
  * presence-claim lock, so no second takeover can interleave between claim and commit. The claim
@@ -76,7 +78,7 @@ export declare function claimSessionParticipant(squarePath: string, name: string
 export declare function claimSessionTakeover<T>(squarePath: string, name: string, env: NodeJS.ProcessEnv | undefined, opts: {
     readonly expectedEpoch?: number;
     readonly expectedSession?: string;
-} | undefined, lifecycle: (claim: TakeoverClaimToken) => Promise<T>): Promise<TakeoverRunResult<T>>;
+} | undefined, lifecycle: (claim: TakeoverClaimToken) => Promise<T>, signal?: AbortSignal): Promise<TakeoverRunResult<T>>;
 export declare function releaseSessionParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function bindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<CurrentParticipantBinding>;
 export declare function unbindCurrentParticipant(squarePath: string, name: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
@@ -97,4 +99,6 @@ export declare function recordLocalJoin(name: string, squarePath: string, env?:
 export declare function recordLocalDone(name: string, squarePath: string, env?: NodeJS.ProcessEnv): Promise<void>;
 export declare function recordSessionJoin(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): Promise<string>;
 export declare function recordSessionDone(sessionId: string, name: string, squarePath: string, channel: SessionChannel, env?: NodeJS.ProcessEnv): Promise<boolean>;
+/** Bind the host ledger to the caller's captured environment. */
+export declare function hostLedgerForEnv(env?: NodeJS.ProcessEnv): HostLedgerPort;
 export {};