@astrosheep/square 0.3.4 → 0.3.6

package/dist/help.js

@@ -1,61 +1,62 @@
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
-    { names: ['version'], usage: 'version', summary: 'Print the installed version.' },
+    { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
     {
-        names: ['build'], usage: 'build --cap <N|-1> [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true,
+        names: ['build'], usage: 'build [--cap <N|unlimited>] [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true, group: 'host',
         summary: 'Create a square from Markdown on stdin.',
-        details: ['Options:', '  --cap <N|-1>       Required activity cap; -1 means unlimited.', '  --template <name>  Append a packaged activity guide.', '  --throttle <N>     Allow at most N public activities per minute.', '  -f, --force        Replace an existing artifact.'],
+        details: ['Options:', '  --cap <N|unlimited>  Set a per-participant activity cap (default unlimited).', '  --template <name>    Append a packaged activity guide.', '  --throttle <N>       Allow at most N public activities per minute.', '  -f, --force          Replace an existing artifact.'],
     },
     {
-        names: ['ls', 'list'], usage: '{command} [--depth N]', summary: 'List nearby squares below the current directory.',
+        names: ['list', 'ls'], usage: '{command} [--depth N]', summary: 'List nearby squares below the current directory.', group: 'host',
         details: ['Options:', '  --depth <N>  Descend through at most N directory levels (default 4; 0 scans only the current directory).'],
     },
     {
-        names: ['join'], usage: '--as <name> join [--last N | --all]', usesSquare: true,
+        names: ['join'], usage: '--as <name> join [--last N | --all]', usesSquare: true, group: 'participant',
         summary: 'Step into the square and read its current context.',
-        details: ['Options:', '  --last <N>  Show the last N public activities (default 10).', '  --all       Show the full public archive.'],
+        details: ['Options:', '  --last <N>  Show the last N public activities (default 10).', '  --all       Show the complete history.'],
     },
     {
-        names: ['act'], usage: '--as <name> act [-f|--force] [--no-wait] [--beside <name> | --bell] <activity | ->', usesSquare: true,
-        summary: 'Add one public activity; pass - to read a multi-line body from stdin.',
-        details: ['Options:', '  -f, --force       Speak over older unread peer activity.', '  --no-wait         Return through a hold or throttle lull, preserving a draft.', '  --beside <name>   Let only that participant hear the full body.', '  --bell            Ring every participant once within the bell window.'],
+        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--beside <name> | --bell] <activity | ->', usesSquare: true, group: 'participant',
+        summary: 'Speak, gesture, or do both.',
+        details: ['Options:', '  -f, --force       Express without first catching unread activity.', '  --no-wait         If held or throttled, save a draft and return.', '  --beside <name>   Speak aside to one participant.', "  --bell            Call every participant's attention to this activity."],
     },
     {
-        names: ['catch'], usage: '--as <name> catch [--now | --follow] [--count N] [--by <names>] [--mention [name]] [--idle <duration>] [-f|--force]', usesSquare: true,
-        summary: 'Catch peer activity and advance this participant\'s presence.',
-        details: ['Options:', '  --now             Catch up immediately.', '  --follow          Keep catching until idle or a terminal state.', '  --count <N>       Return after N matching peer activities.', '  --by <names>      Match only comma-separated participants.', '  --mention [name]  Match mentions of a name, or your own name when omitted.', '  --idle <duration> Set the idle wait, for example 30s, 10m, or 1h.', '  -f, --force       Replace another active catch for this participant.'],
+        names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention [name]] [--replace]', usesSquare: true, group: 'participant',
+        summary: 'Catch what others have said or done since you last looked.',
+        details: ['Modes:', '  --now             Catch up immediately.', '  --idle <duration> Wait for something relevant, or for quiet to last this long.', '', 'Filters:', '  --from <names>    Match only comma-separated participants.', '  --mention [name]  Match mentions of a name, or your own name when omitted.', '', 'Recovery:', '  --replace         Replace another active catch for this participant.'],
     },
-    { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, summary: 'Step out, optionally leaving a final note.' },
+    { names: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, group: 'participant', summary: 'Step out, optionally leaving a final note.' },
     {
-        names: ['stream'], usage: 'stream [--ndjson [--for <name>]]', usesSquare: true,
+        names: ['stream'], usage: 'stream [--ndjson [--for <name>]]', usesSquare: true, hiddenFromIndex: true,
         summary: 'Follow activity without consuming participant presence.',
         details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.'],
     },
     {
-        names: ['inbox'], usage: 'inbox --for-session <session-id> [--json]',
+        names: ['inbox'], usage: 'inbox --for-session <session-id> [--json]', hiddenFromIndex: true,
         summary: 'Inspect bounded machine-local notifications for a native session.',
         details: ['Options:', '  --for-session <id>  Required harness session id.', '  --json              Emit structured JSON.'],
     },
-    { names: ['claude-hook', 'codex-hook'], usage: '{command}', summary: 'Run one native turn-boundary hook event from JSON on stdin.' },
+    { names: ['claude-hook', 'codex-hook'], usage: '{command}', summary: 'Run one native turn-boundary hook event from JSON on stdin.', hiddenFromIndex: true },
     {
-        names: ['echo'], usage: '[--as <name>] echo [filters] [output]', usesSquare: true,
-        summary: 'Read the activity archive without advancing participant presence.',
-        details: ['Filters:', '  --from, --by <names>          Match participants.', '  --since, --until <time>       Match a time window.', '  --grep <regex> | --fixed <s>  Search activity bodies.', '  --mention <name>              Match mentions.', '  --mentions me | --pending     Match attention for --as <name>.', '  --ids <ids> | --at <id>       Match stable activity ids.', '  -B, -A, -C <N>               Set non-negative context around --at.', '  --after <id>                  Match activities after an id.', '  --order <asc|desc>            Set result order.', '  --last, --limit <N> | --all   Bound the result count.', '', 'Output:', '  --full  --json  --format <fields>  --count'],
+        names: ['history'], usage: '[--as <name>] history [filters] [output]', usesSquare: true, group: 'participant',
+        summary: 'Read or search what happened without changing what you have caught.',
+        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search ids, participant names, and bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --ids <ids> | --at <id>         Match stable activity ids.', '  -B, -A, -C <N>                 Set non-negative context around --at.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order.', '', 'Output:', '  --full  --json  --format <fields>  --count'],
     },
-    { names: ['warmup'], usage: 'warmup', usesSquare: true, summary: 'Print the complete embedded participant warmup.' },
-    { names: ['status'], usage: '[--as <name>] status', usesSquare: true, summary: 'Show the current state and latest public activity.' },
-    { names: ['participants'], usage: 'participants', usesSquare: true, summary: 'Show the participant roster and current states.' },
-    { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, summary: 'Raise a hand and pause participant activity.' },
-    { names: ['resume'], usage: '--as <name> resume', usesSquare: true, summary: 'Lower the raised hand and resume activity.' },
+    { names: ['warmup'], usage: 'warmup', usesSquare: true, group: 'host', summary: 'Print the complete embedded participant warmup.' },
+    { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
+    { names: ['participants'], usage: 'participants', usesSquare: true, group: 'host', summary: 'Show the full participant roster and current states.' },
+    { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
+    { names: ['resume'], usage: '--as <name> resume', usesSquare: true, group: 'participant', summary: 'Lower the raised hand and resume activity.' },
     {
-        names: ['harness'], usage: 'harness <install <skills|claude|codex|opencode|pi> [-f] | uninstall codex | doctor [codex|opencode|delivery]>', usesSquare: true,
+        names: ['harness'], usage: 'harness <install <skills|claude|codex|opencode|pi> [-f] | uninstall <skills|claude|codex|opencode|pi> | doctor [skills|claude|codex|opencode|pi|delivery]>', usesSquare: true, group: 'maintenance',
         summary: 'Install, remove, or diagnose official harness adapters.',
+        details: ['Targets:', '  skills, claude, codex, opencode, pi  Install, remove, or diagnose one adapter.', '  delivery                              Diagnose delivery only; skips when no readable artifact is selected.'],
     },
-    { names: ['compact'], usage: 'compact [--keep N]', usesSquare: true, summary: 'Archive older acts while retaining the latest N.' },
+    { names: ['compact'], usage: 'compact [--keep N]', usesSquare: true, group: 'host', summary: 'Move older activity out of the working artifact while keeping the latest N.' },
     {
-        names: ['doctor'], usage: 'doctor [--fix] [reconcile-backlog [--before <time>]]', usesSquare: true,
-        summary: 'Diagnose artifact integrity and delivery health.',
-        details: ['Options:', '  --fix              Repair recoverable artifact problems.', '  reconcile-backlog  Close historical delivery acknowledgement debt.', '  --before <time>    Record the intended reconciliation boundary.'],
+        names: ['doctor'], usage: 'doctor [--fix]', usesSquare: true, group: 'maintenance',
+        summary: 'Diagnose artifact integrity.',
+        details: ['Options:', '  --fix              Repair recoverable artifact problems.'],
     },
 ];
 function definitionFor(command) {
@@ -65,15 +66,23 @@ function isHelpFlag(value) {
     return value === '--help' || value === '-h';
 }
 export function renderGlobalHelp() {
-    const commandLines = COMMANDS
-        .filter((item) => item.names[0] !== 'help')
-        .map((item) => `  ${item.names.join(', ')}\n      ${item.summary}`);
+    const groups = [
+        { key: 'participant', title: 'In the square:', order: ['join', 'express', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
+        { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants', 'warmup', 'compact'] },
+        { key: 'maintenance', title: 'Setup and repair:', order: ['harness', 'doctor'] },
+    ];
+    const commandLines = groups.flatMap(({ key, title, order }) => [
+        title,
+        ...COMMANDS
+            .filter((item) => item.group === key && item.hiddenFromIndex !== true)
+            .sort((left, right) => order.indexOf(left.names[0]) - order.indexOf(right.names[0]))
+            .map((item) => `  ${item.names[0]}\n      ${item.summary}`),
+        '',
+    ]);
     return [
         'Usage: square [--square-path <path>] [--as <name>] <command> [args...]',
         '',
-        'Commands:',
         ...commandLines,
-        '',
         "Run 'square <command> --help' for command options.",
         '',
     ].join('\n');
@@ -94,7 +103,7 @@ export function renderSubcommandHelp(command) {
         'Help:',
         '  -h, --help  Show this command help.',
         '',
-        "Run 'square help' to list every command.",
+        "Run 'square help' to list available commands.",
         '',
     ].join('\n');
 }

package/dist/inbox.js

@@ -1,26 +1,27 @@
 import { loadSquare } from './artifact.js';
 import { deriveDeliveryModel } from './delivery.js';
-import { lookupSession } from './registry.js';
+import { lookupSessionBindings } from './registry.js';
 import { freshWatchLease, isCurrentlyJoined, resolveRosterName } from './runtime.js';
 export function sessionInbox(sessionId) {
     const inbox = [];
-    for (const membership of lookupSession(sessionId)) {
+    for (const binding of lookupSessionBindings(sessionId)) {
         try {
-            const doc = loadSquare(membership.squarePath);
-            const name = resolveRosterName(doc, membership.name);
+            const doc = loadSquare(binding.squarePath);
+            const name = resolveRosterName(doc, binding.name);
             if (!name || !isCurrentlyJoined(doc.acts, name))
                 continue;
-            const notifications = deriveDeliveryModel(doc).pendingFor(name).map(({ item, via }) => ({
+            const notifications = deriveDeliveryModel(doc).pendingFor(name).map(({ item, route }) => ({
                 actIndex: item.index,
-                actor: item.act.actor,
-                at: item.act.at,
-                via,
-                body: item.act.body,
+                actor: item.actor,
+                at: item.at,
+                route,
+                body: item.body,
             }));
-            const catchLease = freshWatchLease(doc, name);
+            const lease = freshWatchLease(doc, name);
+            const catchLease = lease?.ownerId === binding.ownerId ? lease : undefined;
             inbox.push({
                 name,
-                squarePath: membership.squarePath,
+                squarePath: binding.squarePath,
                 notifications,
                 ...(catchLease !== undefined ? { catchLease } : {}),
             });

package/dist/index.js

@@ -1,25 +1,11 @@
-import { setTimeout as sleep } from 'node:timers/promises';
-export * from './model.js';
-export * from './square-core.js';
-export * from './decisions.js';
+export { SquareError } from './model.js';
 export { loadSquare } from './artifact.js';
-export { indexedDelta } from './activity-feed.js';
-export * from './notifications.js';
-export * from './wake-sink.js';
-export * from './paseo-timeline.js';
-export * from './registry.js';
-export * from './inbox.js';
-export * from './presented.js';
-export * from './delivery-health.js';
-export * from './claude-hook.js';
-export * from './harness.js';
-export { extractMentions, countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, appendAct, withSquareLock, readCursor, } from './runtime.js';
+export { extractMentions, countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, readCursor, } from './runtime.js';
 import { loadSquare } from './artifact.js';
-import { ackPeerDelta, indexedDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
-import { dispatchActNotifications, hasDeliveredMention as hasDeliveredMentionImpl, matchesMentionTarget, waitForDeliveredMention as waitForDeliveredMentionImpl, } from './notifications.js';
-import { sameName } from './model.js';
-import { SLEEP_MS, WATCH_HEARTBEAT_MS, WATCH_STALE_MS, actStableIndex, appendAct, freshWatchLease, getReadState as getDocReadState, latestIndexedActIndex, markDeliveredMentions, readCursor, withSquareLock, writeSquareDoc, } from './runtime.js';
-import { decideAct, resolveKnownName } from './decisions.js';
+import { hasDeliveredNotification as hasDeliveredNotificationImpl, waitForDeliveredNotification as waitForDeliveredNotificationImpl, } from './notifications.js';
+import { WATCH_STALE_MS, freshWatchLease, getReadState as getDocReadState, } from './runtime.js';
+import { resolveKnownName } from './decisions.js';
+import { execute } from './square-application.js';
 export { WATCH_STALE_MS };
 function actRefIndex(ref) {
     if (typeof ref === 'number')
@@ -29,22 +15,6 @@ function actRefIndex(ref) {
         throw new Error(`Invalid act ref: ${ref}`);
     return Number(match[1]);
 }
-function byList(by) {
-    if (by === undefined)
-        return undefined;
-    return Array.isArray(by) ? by : by.split(',').map((item) => item.trim()).filter(Boolean);
-}
-function matchesProgrammaticFilter(item, opts) {
-    const speakers = byList(opts.by);
-    if (speakers !== undefined && (item.act.actor === undefined || !speakers.some((speaker) => sameName(speaker, item.act.actor))))
-        return false;
-    if (opts.mention !== undefined) {
-        if (item.act.kind !== 'say')
-            return false;
-        return matchesMentionTarget(item.act, opts.mention);
-    }
-    return item.act.kind === 'say' || item.act.kind === 'done' || item.act.kind === 'join';
-}
 export function getReadState(squarePath, name) {
     const doc = loadSquare(squarePath);
     return getDocReadState(doc, resolveKnownName(doc, name));
@@ -53,11 +23,11 @@ export function hasConsumedAct(squarePath, name, ref) {
     const state = getReadState(squarePath, name);
     return (state?.consumedThroughIndex ?? -1) >= actRefIndex(ref);
 }
-export function hasDeliveredMention(squarePath, name, ref) {
-    return hasDeliveredMentionImpl(squarePath, name, actRefIndex(ref));
+export function hasDeliveredNotification(squarePath, name, ref) {
+    return hasDeliveredNotificationImpl(squarePath, name, actRefIndex(ref));
 }
-export async function waitForDeliveredMention(squarePath, name, ref, opts = {}) {
-    return waitForDeliveredMentionImpl(squarePath, name, actRefIndex(ref), opts);
+export async function waitForDeliveredNotification(squarePath, name, ref, opts = {}) {
+    return waitForDeliveredNotificationImpl(squarePath, name, actRefIndex(ref), opts);
 }
 export function getParticipantPresence(squarePath, name, now = Date.now()) {
     const doc = loadSquare(squarePath);
@@ -68,96 +38,27 @@ export function getParticipantPresence(squarePath, name, now = Date.now()) {
 export function isWatching(squarePath, name, now = Date.now()) {
     return getParticipantPresence(squarePath, name, now).watching;
 }
-export async function act(squarePath, name, body, opts = {}) {
-    const sent = await withSquareLock(squarePath, () => {
-        const doc = loadSquare(squarePath);
-        const decision = decideAct(doc, { name, body, force: opts.force ?? false, now: Date.now() });
-        if (decision.type === 'sent') {
-            const appended = appendAct(squarePath, doc, decision.act);
-            return { act: appended, index: actStableIndex(appended) };
-        }
-        throw new Error(`Act rejected: ${decision.type}`);
-    });
-    if (sent)
-        await dispatchActNotifications(squarePath, sent);
+/** Typed participant intents share the same commit/effect pipeline as the CLI. */
+export async function join(squarePath, name) {
+    await execute(squarePath, { type: 'join', name, now: Date.now() });
+}
+export async function done(squarePath, name, body = '') {
+    await execute(squarePath, { type: 'done', name, body, now: Date.now() });
+}
+export async function hold(squarePath, actor, body = '') {
+    await execute(squarePath, { type: 'hold', actor, body, now: Date.now() });
 }
-export async function* streamEvents(squarePath, opts = {}) {
-    let doc = loadSquare(squarePath);
-    let cursor = latestIndexedActIndex(doc.acts.map((act) => ({ act, index: actStableIndex(act) })));
-    while (true) {
-        await sleep(SLEEP_MS);
-        try {
-            doc = loadSquare(squarePath);
-        }
-        catch {
-            continue;
-        }
-        const delta = indexedDelta(doc.acts, cursor);
-        if (delta.length === 0)
-            continue;
-        cursor = latestIndexedActIndex(delta);
-        const filtered = delta.filter((item) => matchesProgrammaticFilter(item, opts));
-        if (filtered.length > 0)
-            yield filtered;
-    }
+export async function resume(squarePath, actor) {
+    await execute(squarePath, { type: 'resume', actor, now: Date.now() });
 }
-export async function* watch(squarePath, opts) {
-    let doc = loadSquare(squarePath);
-    const name = resolveKnownName(doc, opts.name);
-    const leaseId = `watch_api_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-    let nextHeartbeatAt = Date.now() + WATCH_HEARTBEAT_MS;
-    await withSquareLock(squarePath, () => {
-        doc = loadSquare(squarePath);
-        const existing = freshWatchLease(doc, name);
-        if (existing !== undefined)
-            throw new Error(`${name} already has an active watch.`);
-        const at = Date.now();
-        nextHeartbeatAt = at + WATCH_HEARTBEAT_MS;
-        const participants = byList(opts.by);
-        const filter = { ...(participants ? { participants } : {}), ...(typeof opts.mention === 'string' ? { mention: opts.mention } : {}) };
-        doc.runtime.leases[name] = { leaseId, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter).length > 0 ? { filter } : {}) };
-        writeSquareDoc(squarePath, doc);
+export async function express(squarePath, name, body, opts = {}) {
+    const committed = await execute(squarePath, {
+        type: 'say',
+        name,
+        body,
+        force: opts.force ?? false,
+        now: Date.now(),
     });
-    try {
-        while (true) {
-            const yielded = await withSquareLock(squarePath, () => {
-                const latest = loadSquare(squarePath);
-                const at = Date.now();
-                const lease = freshWatchLease(latest, name, at);
-                if (lease?.leaseId !== leaseId)
-                    throw new Error(`${name}'s watch was replaced.`);
-                let mutated = false;
-                if (at >= nextHeartbeatAt) {
-                    latest.runtime.leases[name] = { ...lease, heartbeatAt: at, expiresAt: at + WATCH_STALE_MS };
-                    nextHeartbeatAt = at + WATCH_HEARTBEAT_MS;
-                    mutated = true;
-                }
-                const delta = indexedDelta(latest.acts, readCursor(latest, name));
-                const deliverable = [...peerPublicActs(delta, name), ...peerRoomChanges(delta, name)];
-                if (deliverable.length === 0) {
-                    if (mutated)
-                        writeSquareDoc(squarePath, latest);
-                    return null;
-                }
-                const filtered = deliverable.filter((item) => matchesProgrammaticFilter(item, opts));
-                const consumed = ackPeerDelta(latest, name, delta);
-                const receipts = markDeliveredMentions(latest, name, filtered);
-                if (consumed || receipts || mutated)
-                    writeSquareDoc(squarePath, latest);
-                return filtered.length > 0 ? filtered : null;
-            });
-            if (yielded !== null)
-                yield yielded;
-            await sleep(SLEEP_MS);
-        }
-    }
-    finally {
-        await withSquareLock(squarePath, () => {
-            const latest = loadSquare(squarePath);
-            if (latest.runtime.leases[name]?.leaseId !== leaseId)
-                return;
-            delete latest.runtime.leases[name];
-            writeSquareDoc(squarePath, latest);
-        });
-    }
+    if (committed.result.type !== 'sent')
+        throw new Error(`Activity rejected: ${committed.result.type}`);
 }

package/dist/list.js

@@ -102,7 +102,7 @@ function renderSquareList(items) {
     const now = Date.now();
     const lines = [
         'squares',
-        ...items.map((item) => `${item.activities > 0 ? '●' : '○'} ${item.path} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants} in square · ${item.activities} acts`),
+        ...items.map((item) => `${item.activities > 0 ? '●' : '○'} ${item.path} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants} in square · ${item.activities} activities`),
     ];
     return lines.join('\n') + '\n';
 }

package/dist/model.js

@@ -13,9 +13,6 @@ export const ACTIVITIES_HEADING = '## Activities';
 export const ACTIVITIES_MARKER = '<!-- square:activities -->';
 export const ACT_MARKER_PREFIX = '<!-- square:act';
 export const CURRENT_FORMAT_VERSION = 3;
-export function formatParticipants(participants) {
-    return participants.join(', ');
-}
 export function formatHardCap(hardCap) {
     return hardCap === null ? '-1' : String(hardCap);
 }
@@ -39,6 +36,3 @@ export function validateName(name) {
         throw new SquareError('invalid_name', 'Invalid name: names must be non-empty and can only contain Unicode letters, digits, hyphens, and underscores.');
     }
 }
-export function validateParticipantName(name) {
-    validateName(name);
-}

package/dist/notification-failures.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_BYTES = 1_000_000;
+export function notificationFailuresPath(squarePath, env = process.env) {
+    return env.SQUARE_NOTIFICATION_FAILURES ?? path.join(path.dirname(squarePath), 'notification-failures.ndjsonl');
+}
+function redact(value, secret = process.env.PASEO_PASSWORD) {
+    if (typeof value === 'string')
+        return secret ? value.split(secret).join('[redacted]') : value;
+    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)]));
+    }
+    return value;
+}
+function parseRows(file) {
+    try {
+        return fs.readFileSync(file, 'utf8').split('\n').flatMap((line) => {
+            if (line.trim() === '')
+                return [];
+            try {
+                const row = JSON.parse(line);
+                return row.v === 1 && row.op === 'failed' && typeof row.actIndex === 'number' && typeof row.sink === 'string' && typeof row.message === 'string' && typeof row.at === 'number'
+                    ? [{ actIndex: row.actIndex, recipient: row.recipient, route: row.route, sink: row.sink, message: row.message, at: row.at, ...(row.diagnostic === undefined ? {} : { diagnostic: row.diagnostic }) }]
+                    : [];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+export function readNotificationFailures(squarePath, env = process.env) {
+    return parseRows(notificationFailuresPath(squarePath, env));
+}
+/** Append diagnosable delivery failures without ever persisting Paseo credentials. */
+export function recordNotificationFailure(squarePath, input, at = Date.now(), env = process.env) {
+    const file = notificationFailuresPath(squarePath, env);
+    const safe = redact({ ...input, at }, env.PASEO_PASSWORD);
+    const row = { v: 1, op: 'failed', ...safe };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const text = `${JSON.stringify(row)}\n`;
+    if (fs.existsSync(file) && fs.statSync(file).size + Buffer.byteLength(text) > MAX_BYTES) {
+        const retained = parseRows(file).slice(-500);
+        fs.writeFileSync(file, retained.map((item) => JSON.stringify({ v: 1, op: 'failed', ...item })).join('\n') + (retained.length ? '\n' : ''), { mode: 0o600 });
+    }
+    fs.appendFileSync(file, text, { mode: 0o600 });
+}

package/dist/notifications.js

@@ -2,56 +2,40 @@ import { spawn } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 import { loadSquare } from './artifact.js';
-import { SquareError } from './model.js';
+import { isDeliveryDelivered, isPendingNotification, planActNotifications, } from './delivery.js';
+import { recordNotificationFailure } from './notification-failures.js';
 import { hasPresentedAttention } from './presented.js';
-import { SLEEP_MS, isDeliveryDelivered, resolveRosterName, rosterNames, } from './runtime.js';
-import { planActNotifications } from './delivery.js';
-import { defaultWakeSinks, } from './wake-sink.js';
-export { planActNotifications } from './delivery.js';
-export { matchesMentionTarget } from './runtime.js';
-function parsePositiveIntegerEnv(name, fallback) {
-    const raw = process.env[name];
-    if (raw === undefined)
-        return fallback;
-    const value = Number.parseInt(raw, 10);
-    if (!Number.isFinite(value) || value <= 0) {
-        throw new SquareError('invalid_args', `Invalid ${name}: expected a positive integer.`);
-    }
-    return value;
-}
-function resolveKnownParticipant(doc, name) {
-    const known = resolveRosterName(doc, name);
-    if (known === undefined) {
+import { SquareError } from './model.js';
+import { SLEEP_MS, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
+import { defaultWakeSinks } from './wake-sink.js';
+export { planActNotifications, matchesMentionTarget };
+function known(doc, name) {
+    const value = resolveRosterName(doc, name);
+    if (value === undefined)
         throw new SquareError('invalid_args', `Unknown participant "${name}". Expected one of: ${rosterNames(doc).join(', ')}.`);
-    }
-    return known;
+    return value;
 }
+export { notificationMessageId } from './delivery.js';
 export function notificationDeliveryWaitMs() {
-    return parsePositiveIntegerEnv('SQUARE_NOTIFY_DELIVERY_WAIT_MS', 5000);
+    const value = Number.parseInt(process.env.SQUARE_NOTIFY_DELIVERY_WAIT_MS ?? '5000', 10);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new SquareError('invalid_args', 'Invalid SQUARE_NOTIFY_DELIVERY_WAIT_MS: expected a positive integer.');
+    return value;
 }
-export function hasDeliveredMention(squarePath, name, ref) {
+export function hasDeliveredNotification(squarePath, name, ref) {
     const doc = loadSquare(squarePath);
-    const known = resolveKnownParticipant(doc, name);
-    const index = typeof ref === 'number' ? ref : Number(ref.slice(4));
-    return isDeliveryDelivered(doc, known, index);
+    return isDeliveryDelivered(doc, known(doc, name), typeof ref === 'number' ? ref : Number(ref.slice(4)));
 }
-/**
- * Duplicate-wake suppression only. Delivery remains pending until the canonical
- * recipient/act receipt is delivered; presented is a machine-local cache.
- */
-export function hasAttentionMention(squarePath, name, ref, env = process.env) {
+export function hasAttentionNotification(squarePath, name, ref, env = process.env) {
     const doc = loadSquare(squarePath);
-    const known = resolveKnownParticipant(doc, name);
+    const recipient = known(doc, name);
     const index = typeof ref === 'number' ? ref : Number(ref.slice(4));
-    if (isDeliveryDelivered(doc, known, index))
-        return true;
-    return hasPresentedAttention(squarePath, known, index, env);
+    return isDeliveryDelivered(doc, recipient, index) || hasPresentedAttention(squarePath, recipient, index, env);
 }
-export async function waitForDeliveredMention(squarePath, name, ref, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 30000;
-    const deadline = Date.now() + timeoutMs;
+export async function waitForDeliveredNotification(squarePath, name, ref, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 30000);
     while (Date.now() <= deadline) {
-        if (hasDeliveredMention(squarePath, name, ref))
+        if (hasDeliveredNotification(squarePath, name, ref))
             return true;
         await sleep(Math.min(SLEEP_MS, Math.max(1, deadline - Date.now())));
     }
@@ -59,39 +43,40 @@ export async function waitForDeliveredMention(squarePath, name, ref, opts = {})
 }
 export async function processActNotificationsOnce(squarePath, actIndex, opts = {}) {
     const doc = loadSquare(squarePath);
-    const act = doc.acts.find((candidate) => candidate.index === actIndex);
-    if (!act)
-        return;
-    const item = { act, index: actIndex };
-    const notifications = planActNotifications(doc, item).filter((notification) => notification.via === 'mention' || notification.via === 'bell');
-    const sinks = opts.sinks ?? defaultWakeSinks();
-    if (sinks.length === 0)
+    const item = doc.acts.find((candidate) => candidate.index === actIndex);
+    if (item === undefined)
         return;
+    const notifications = planActNotifications(doc, item).filter(isPendingNotification);
     for (const notification of notifications) {
-        // Presented only avoids duplicate wake text. It does not affect delivery state.
-        if (hasAttentionMention(squarePath, notification.recipient, actIndex))
+        if (hasAttentionNotification(squarePath, notification.recipient, notification.item.index))
             continue;
-        for (const sink of sinks) {
-            await sink.dispatch(notification, { squarePath });
+        for (const sink of opts.sinks ?? defaultWakeSinks()) {
+            try {
+                await sink.dispatch(notification, { squarePath });
+            }
+            catch (error) {
+                recordNotificationFailure(squarePath, {
+                    actIndex: notification.item.index,
+                    recipient: notification.recipient,
+                    route: notification.route,
+                    sink: sink.name,
+                    message: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof Error && 'diagnostic' in error ? { diagnostic: error.diagnostic } : {}),
+                });
+            }
         }
     }
 }
-function launchDetachedWorker(workerPath, args) {
-    const child = spawn(process.execPath, [workerPath, ...args], {
-        detached: true,
-        stdio: 'ignore',
-        env: process.env,
-    });
+function launchWorker(workerPath, args) {
+    const child = spawn(process.execPath, [workerPath, ...args], { detached: true, stdio: 'ignore', env: process.env });
     child.unref();
 }
+/** Start one detached worker only when this act contains directed attention. */
 export async function dispatchActNotifications(squarePath, item, opts = {}) {
-    if (process.env['SQUARE_DISABLE_PASEO_WAKE'] === '1')
+    if (process.env.SQUARE_DISABLE_PASEO_WAKE === '1')
         return;
     const doc = loadSquare(squarePath);
-    const notifications = planActNotifications(doc, item).filter((notification) => notification.via === 'mention' || notification.via === 'bell');
-    if (notifications.length === 0)
+    if (!planActNotifications(doc, item).some(isPendingNotification))
         return;
-    const workerPath = fileURLToPath(new URL('./cmd/notify-once.js', import.meta.url));
-    const launch = opts.launchWorker ?? launchDetachedWorker;
-    launch(workerPath, ['--square-path', squarePath, '--act-index', String(item.index)]);
+    (opts.launchWorker ?? launchWorker)(fileURLToPath(new URL('./cmd/notify-once.js', import.meta.url)), ['--square-path', squarePath, '--act-index', String(item.index)]);
 }