@astrosheep/square 0.3.2

package/dist/help.js

@@ -0,0 +1,131 @@
+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: ['build'], usage: 'build --cap <N|-1> [--template <name>] [--throttle N] [-f] < body.md', usesSquare: true,
+        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.'],
+    },
+    {
+        names: ['ls', 'list'], usage: '{command} [--depth N]', summary: 'List nearby squares below the current directory.',
+        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,
+        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.'],
+    },
+    {
+        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: ['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: ['done'], usage: '--as <name> done [final | -]', usesSquare: true, summary: 'Step out, optionally leaving a final note.' },
+    {
+        names: ['stream'], usage: 'stream [--ndjson [--for <name>]]', usesSquare: 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]',
+        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: ['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: ['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: ['harness'], usage: 'harness <install <skills|claude|codex|opencode|pi> [-f] | uninstall codex | doctor [codex|opencode|delivery]>', usesSquare: true,
+        summary: 'Install, remove, or diagnose official harness adapters.',
+    },
+    { names: ['compact'], usage: 'compact [--keep N]', usesSquare: true, summary: 'Archive older acts while retaining 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.'],
+    },
+];
+function definitionFor(command) {
+    return COMMANDS.find((item) => item.names.includes(command));
+}
+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}`);
+    return [
+        'Usage: square [--square-path <path>] [--as <name>] <command> [args...]',
+        '',
+        'Commands:',
+        ...commandLines,
+        '',
+        "Run 'square <command> --help' for command options.",
+        '',
+    ].join('\n');
+}
+export function renderSubcommandHelp(command) {
+    const definition = definitionFor(command);
+    if (definition === undefined)
+        return undefined;
+    const aliases = definition.names.filter((name) => name !== command);
+    const usage = definition.usage.replace('{command}', command);
+    return [
+        `Usage: square ${definition.usesSquare ? '[--square-path <path>] ' : ''}${usage}`,
+        ...(aliases.length > 0 ? [`Aliases: ${aliases.join(', ')}`] : []),
+        '',
+        definition.summary,
+        ...(definition.details === undefined ? [] : ['', ...definition.details]),
+        '',
+        'Help:',
+        '  -h, --help  Show this command help.',
+        '',
+        "Run 'square help' to list every command.",
+        '',
+    ].join('\n');
+}
+export function helpRequest(rawArgs) {
+    const args = [];
+    for (let index = 0; index < rawArgs.length; index++) {
+        const arg = rawArgs[index];
+        if (arg === '--square-path' || arg === '--as') {
+            const value = rawArgs[index + 1];
+            if (value === undefined || value.startsWith('--'))
+                return undefined;
+            index++;
+            continue;
+        }
+        args.push(arg);
+    }
+    if (isHelpFlag(args[0]))
+        return {};
+    if (args[0] === 'help') {
+        if (args.length === 1)
+            return {};
+        if (args.length === 2)
+            return { command: isHelpFlag(args[1]) ? 'help' : args[1] };
+        return undefined;
+    }
+    if (args.length > 1 && args.slice(1).some(isHelpFlag))
+        return { command: args[0] };
+    return undefined;
+}
+export function commandUsageHint(command) {
+    return command !== undefined && definitionFor(command) !== undefined
+        ? `Run 'square ${command} --help' for usage.\n`
+        : "Run 'square help' to list commands.\n";
+}

package/dist/inbox.js

@@ -0,0 +1,33 @@
+import { loadSquare } from './artifact.js';
+import { deriveDeliveryModel } from './delivery.js';
+import { lookupSession } from './registry.js';
+import { freshWatchLease, isCurrentlyJoined, resolveRosterName } from './runtime.js';
+export function sessionInbox(sessionId) {
+    const inbox = [];
+    for (const membership of lookupSession(sessionId)) {
+        try {
+            const doc = loadSquare(membership.squarePath);
+            const name = resolveRosterName(doc, membership.name);
+            if (!name || !isCurrentlyJoined(doc.acts, name))
+                continue;
+            const notifications = deriveDeliveryModel(doc).pendingFor(name).map(({ item, via }) => ({
+                actIndex: item.index,
+                actor: item.act.actor,
+                at: item.act.at,
+                via,
+                body: item.act.body,
+            }));
+            const catchLease = freshWatchLease(doc, name);
+            inbox.push({
+                name,
+                squarePath: membership.squarePath,
+                notifications,
+                ...(catchLease !== undefined ? { catchLease } : {}),
+            });
+        }
+        catch {
+            // A stale discovery-cache row only disables delivery for that membership.
+        }
+    }
+    return inbox;
+}

package/dist/index.js

@@ -0,0 +1,163 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+export * from './model.js';
+export * from './square-core.js';
+export * from './decisions.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';
+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';
+export { WATCH_STALE_MS };
+function actRefIndex(ref) {
+    if (typeof ref === 'number')
+        return ref;
+    const match = ref.match(/^act_(\d+)$/);
+    if (!match)
+        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));
+}
+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 async function waitForDeliveredMention(squarePath, name, ref, opts = {}) {
+    return waitForDeliveredMentionImpl(squarePath, name, actRefIndex(ref), opts);
+}
+export function getParticipantPresence(squarePath, name, now = Date.now()) {
+    const doc = loadSquare(squarePath);
+    const known = resolveKnownName(doc, name);
+    const lease = freshWatchLease(doc, known, now);
+    return lease === undefined ? { watching: false } : { watching: true, lease };
+}
+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);
+}
+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* 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);
+    });
+    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);
+        });
+    }
+}

package/dist/list.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseSquare } from './artifact.js';
+import { inSquareCount, publicActs } from './runtime.js';
+import { formatRelativeTime } from './time.js';
+const DEFAULT_LIST_DEPTH = 4;
+const LIST_SKIP_DIRS = new Set(['.git', 'node_modules', 'dist']);
+function frontmatterOf(text) {
+    const match = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+    return match ? match[1] : null;
+}
+function candidateFrontmatter(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const buffer = Buffer.allocUnsafe(4096);
+        const bytesRead = fs.readSync(fd, buffer, 0, buffer.length, 0);
+        const prefix = buffer.toString('utf8', 0, bytesRead);
+        if (!prefix.startsWith('---\n'))
+            return null;
+        const frontmatter = frontmatterOf(prefix);
+        return frontmatter ?? frontmatterOf(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+function readSquareListItem(filePath, root) {
+    let text;
+    let doc;
+    let stat;
+    try {
+        stat = fs.statSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    const frontmatter = candidateFrontmatter(filePath);
+    if (!frontmatter)
+        return null;
+    if (!/^hard_cap:\s*(-1|\d+)\s*$/m.test(frontmatter))
+        return null;
+    if (!/^format_version:\s*3\s*$/m.test(frontmatter))
+        return null;
+    try {
+        text = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    if (!text.includes('<!-- square:warmup -->') || !text.includes('<!-- square:activities -->'))
+        return null;
+    try {
+        doc = parseSquare(text);
+    }
+    catch {
+        return null;
+    }
+    const relative = path.relative(root, filePath) || path.basename(filePath);
+    return {
+        path: relative,
+        lastActiveAt: stat.mtimeMs,
+        participants: inSquareCount(doc),
+        activities: publicActs(doc.acts).filter((act) => act.kind === 'say').length,
+    };
+}
+function collectSquareList(root, maxDepth) {
+    const items = [];
+    function walk(dir, depth) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            // Directory vanished or became unreadable mid-walk — skip it, don't abort the scan.
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (depth < maxDepth && !LIST_SKIP_DIRS.has(entry.name))
+                    walk(fullPath, depth + 1);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const item = readSquareListItem(fullPath, root);
+            if (item)
+                items.push(item);
+        }
+    }
+    walk(root, 0);
+    return items.sort((a, b) => a.path.localeCompare(b.path));
+}
+function renderSquareList(items) {
+    if (items.length === 0)
+        return '(no squares found)\n';
+    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`),
+    ];
+    return lines.join('\n') + '\n';
+}
+function parseMaxDepth(args, usage) {
+    if (args.length === 0)
+        return DEFAULT_LIST_DEPTH;
+    if (args.length !== 2 || args[0] !== '--depth' || !/^\d+$/.test(args[1])) {
+        usage();
+        return DEFAULT_LIST_DEPTH;
+    }
+    const depth = Number(args[1]);
+    if (!Number.isSafeInteger(depth)) {
+        usage();
+        return DEFAULT_LIST_DEPTH;
+    }
+    return depth;
+}
+export function cmdListSquares(args, usage) {
+    const maxDepth = parseMaxDepth(args, usage);
+    process.stdout.write(renderSquareList(collectSquareList(process.cwd(), maxDepth)));
+}

package/dist/model.js

@@ -0,0 +1,44 @@
+// Shared model and constants for Square.
+export class SquareError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SquareError';
+    }
+}
+export const WARMUP_HEADING = '## Warmup';
+export const WARMUP_MARKER = '<!-- square:warmup -->';
+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);
+}
+export function parseParticipantList(value) {
+    return value
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+}
+export function nameKey(name) {
+    return name.toLocaleLowerCase();
+}
+export function sameName(a, b) {
+    return nameKey(a) === nameKey(b);
+}
+export function findParticipantName(participants, name) {
+    return participants.find((participant) => sameName(participant, name));
+}
+export function validateName(name) {
+    if (!name || !/^[\p{L}\p{N}_-]+$/u.test(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/notifications.js

@@ -0,0 +1,97 @@
+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 { 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) {
+        throw new SquareError('invalid_args', `Unknown participant "${name}". Expected one of: ${rosterNames(doc).join(', ')}.`);
+    }
+    return known;
+}
+export function notificationDeliveryWaitMs() {
+    return parsePositiveIntegerEnv('SQUARE_NOTIFY_DELIVERY_WAIT_MS', 5000);
+}
+export function hasDeliveredMention(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);
+}
+/**
+ * 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) {
+    const doc = loadSquare(squarePath);
+    const known = resolveKnownParticipant(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);
+}
+export async function waitForDeliveredMention(squarePath, name, ref, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 30000;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        if (hasDeliveredMention(squarePath, name, ref))
+            return true;
+        await sleep(Math.min(SLEEP_MS, Math.max(1, deadline - Date.now())));
+    }
+    return false;
+}
+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)
+        return;
+    for (const notification of notifications) {
+        // Presented only avoids duplicate wake text. It does not affect delivery state.
+        if (hasAttentionMention(squarePath, notification.recipient, actIndex))
+            continue;
+        for (const sink of sinks) {
+            await sink.dispatch(notification, { squarePath });
+        }
+    }
+}
+function launchDetachedWorker(workerPath, args) {
+    const child = spawn(process.execPath, [workerPath, ...args], {
+        detached: true,
+        stdio: 'ignore',
+        env: process.env,
+    });
+    child.unref();
+}
+export async function dispatchActNotifications(squarePath, item, opts = {}) {
+    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)
+        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)]);
+}