@astrosheep/square 0.3.12 → 0.3.13

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

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

package/codex-plugin/hooks/hooks.json

@@ -1,5 +1,14 @@
 {
   "hooks": {
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+    ],
+    "SessionResume": [
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+    ],
+    "SessionEnd": [
+      { "hooks": [{ "type": "command", "command": "square codex-hook", "timeout": 5 }] }
+    ],
     "PostToolUse": [
       {
         "hooks": [

package/dist/activity-feed.d.ts

@@ -0,0 +1,14 @@
+import { type StoredAct, type SquareState, type PublicAct, type RoomChangeAct } from './model.js';
+export interface ActivityFeedFilter {
+    participants?: string[];
+    mention?: string;
+}
+export declare function actDelta(acts: StoredAct[], cursor: number): StoredAct[];
+/** Public cursor changes plus directed receipts that remain pending behind it. */
+export declare function deliveryDelta(squareState: SquareState, name: string): StoredAct[];
+export declare function peerRoomChanges(delta: StoredAct[], name: string): RoomChangeAct[];
+export declare function peerPublicActs(delta: StoredAct[], name: string): PublicAct[];
+export declare function matchesFeedFilter(act: StoredAct, filter: ActivityFeedFilter): boolean;
+export declare function filteredPeerActivities(delta: StoredAct[], name: string, filter: ActivityFeedFilter): PublicAct[];
+export declare function filteredRoomChanges(delta: StoredAct[], name: string, filter: ActivityFeedFilter): RoomChangeAct[];
+export declare function ackPeerDelta(squareState: SquareState, name: string, delta: StoredAct[], at?: number): boolean;

package/dist/activity-feed.js

@@ -5,10 +5,10 @@ export function actDelta(acts, cursor) {
     return acts.filter((act) => act.index > cursor);
 }
 /** Public cursor changes plus directed receipts that remain pending behind it. */
-export function deliveryDelta(doc, name) {
-    const items = actDelta(doc.acts, readCursor(doc, name));
+export function deliveryDelta(squareState, name) {
+    const items = actDelta(squareState.acts, readCursor(squareState, name));
     const seen = new Set(items.map((act) => act.index));
-    for (const notification of deriveDeliveryModel(doc).pendingFor(name)) {
+    for (const notification of deriveDeliveryModel(squareState).pendingFor(name)) {
         if (!seen.has(notification.item.index))
             items.push(notification.item);
     }
@@ -39,6 +39,6 @@ export function filteredRoomChanges(delta, name, filter) {
         return [];
     return peerRoomChanges(delta, name).filter((act) => matchesParticipants(act, filter.participants));
 }
-export function ackPeerDelta(doc, name, delta) {
-    return advanceCursor(doc, name, latestActIndex([...peerPublicActs(delta, name), ...peerRoomChanges(delta, name)]));
+export function ackPeerDelta(squareState, name, delta, at) {
+    return advanceCursor(squareState, name, latestActIndex([...peerPublicActs(delta, name), ...peerRoomChanges(delta, name)]), at);
 }

package/dist/activity.d.ts

@@ -0,0 +1,9 @@
+export interface ActivityOptions {
+    force?: boolean;
+    forceCommand: string;
+    noWait?: boolean;
+    reach?: import('./model.js').Reach;
+    reply?: number;
+}
+export declare function saveActivityDraft(squarePath: string, name: string, body: string): string;
+export declare function cmdActivity(squarePath: string, name: string, activity: string, resolveBody: (arg: string) => string, opts: ActivityOptions): Promise<void>;

package/dist/activity.js

@@ -2,12 +2,15 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { loadSquare } from './artifact.js';
-import { SquareError, validateName } from './model.js';
+import { SquareError, isSquareError, validateName } from './model.js';
 import { expressHintLine, renderActivityBlocked, renderActivityLimit, renderExpressNoWait, renderExpressWaiting, renderPendingFeed, withPathOutput, } from './presentation.js';
-import { currentHold, inSquareCount, nowMs, SLEEP_MS, resolveRosterName } from './runtime.js';
-import { dispatchActNotifications } from './notifications.js';
-import { execute } from './square-application.js';
+import { nowMs, SLEEP_MS } from './runtime.js';
+import { wakeNotifierForSquare } from './notifications.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { Square } from './square-wiring.js';
+import { activityPresentation, resolveParticipant } from './views.js';
+import { formatActivityId } from './square-core.js';
 import { formatTimestamp } from './time.js';
 function draftDirFor(squarePath) {
     return path.join(path.dirname(squarePath), 'drafts');
@@ -39,114 +42,132 @@ export function saveActivityDraft(squarePath, name, body) {
 export async function cmdActivity(squarePath, name, activity, resolveBody, opts) {
     validateName(name);
     const rawInput = String(resolveBody(activity)).replace(/\r\n/g, '\n');
-    let doc;
+    const reader = await openSquare(squarePath, { clock: nowMs });
+    let knownName;
     try {
-        doc = loadSquare(squarePath);
+        knownName = (await resolveParticipant(reader, name)).name;
     }
     catch (err) {
-        if (err instanceof SquareError) {
+        await closeOpenSquare(reader);
+        if (isSquareError(err)) {
+            if (err.code === 'unknown_participant' || err.code === 'invalid_args') {
+                const draftPath = saveActivityDraft(squarePath, name, rawInput);
+                process.stderr.write(err.message + '\n');
+                process.stderr.write(`draft kept: ${draftPath}\n`);
+                process.exit(2);
+            }
             process.stderr.write(err.message + '\n');
             process.exit(err.code === 'not_found' ? 1 : 2);
         }
         throw err;
     }
-    const knownName = resolveRosterName(doc, name);
-    if (knownName === undefined) {
-        const draftPath = saveActivityDraft(squarePath, name, rawInput);
-        const expected = doc.acts.filter((act) => act.kind === 'join').map((act) => act.actor);
-        process.stderr.write(`Unknown participant "${name}". Expected one of: ${expected.join(', ')}.\n`);
-        process.stderr.write(`draft kept: ${draftPath}\n`);
-        process.exit(2);
-    }
+    await closeOpenSquare(reader);
     const body = rawInput.trim();
     const force = opts.force ?? false;
     const noWait = opts.noWait ?? false;
     const reach = opts.reach === 'bell' ? 'bell' : undefined;
     let announcedWait;
-    while (true) {
-        const committed = await execute(squarePath, {
-            type: 'say',
-            name,
-            body,
-            force,
-            now: nowMs(),
-            ...(reach === undefined ? {} : { reach }),
-            ...(opts.reply === undefined ? {} : { reply: opts.reply }),
-        });
-        const decision = committed.result;
-        const freshDoc = loadSquare(squarePath);
-        const headerCount = inSquareCount(freshDoc);
-        const held = currentHold(freshDoc.acts).active;
-        switch (decision.type) {
-            case 'sent': {
-                const sayAct = committed.acts.find((act) => act.kind === 'say');
-                if (sayAct !== undefined)
-                    await dispatchActNotifications(squarePath, sayAct);
-                const hasPending = decision.pendingPublic.length > 0 || decision.pendingRoomChanges.length > 0;
-                const pending = hasPending ? `\n\n${renderPendingFeed(freshDoc.acts, decision.pendingPublic, decision.pendingRoomChanges, knownName)}` : '';
-                const hint = expressHintLine(decision.ownActCount);
-                const withHint = hint ? `${decision.confirmation}\n${hint}` : decision.confirmation;
+    const square = await Square.at({ path: squarePath, clock: nowMs, notifier: wakeNotifierForSquare(squarePath) });
+    try {
+        const participant = await square.join(name);
+        while (true) {
+            const beforeSquare = await openSquare(squarePath, { clock: nowMs });
+            const before = await activityPresentation(beforeSquare, knownName).finally(() => closeOpenSquare(beforeSquare));
+            const pendingPublic = before.pendingPublic;
+            const pendingRoomChanges = before.pendingRoomChanges;
+            try {
+                await participant.express(body, {
+                    force,
+                    ...(reach === undefined ? {} : { reach }),
+                    ...(opts.reply === undefined ? {} : { reply: formatActivityId(opts.reply) }),
+                });
+                const freshSquare = await openSquare(squarePath, { clock: nowMs });
+                const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
+                const headerCount = fresh.participantCount;
+                const held = fresh.held;
+                const ownActCount = fresh.ownActivityCount;
+                const hasPending = pendingPublic.length > 0 || pendingRoomChanges.length > 0;
+                const pending = hasPending ? `\n\n${renderPendingFeed([...fresh.activities], [...pendingPublic], [...pendingRoomChanges], knownName)}` : '';
+                const hint = expressHintLine(ownActCount);
+                const confirmation = `● heads turn your way — #${ownActCount}`;
+                const withHint = hint ? `${confirmation}\n${hint}` : confirmation;
                 process.stdout.write(withPathOutput(squarePath, withHint + pending, { participantCount: headerCount, held }));
                 return;
             }
-            case 'blocked': {
-                const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                process.stdout.write(renderActivityBlocked({
-                    squarePath,
-                    name: knownName,
-                    forceCommand: opts.forceCommand,
-                    activitySummaries: decision.activitySummaries,
-                    unreadRoomChanges: decision.unreadRoomChanges,
-                    draftPath,
-                    participantCount: headerCount,
-                    held,
-                }));
-                process.exit(1);
-                break;
-            }
-            case 'capped': {
-                process.stdout.write(renderActivityLimit({
-                    squarePath,
-                    name: knownName,
-                    count: decision.count,
-                    hardCap: decision.hardCap,
-                    draftPath: saveActivityDraft(squarePath, name, rawInput),
-                    participantCount: headerCount,
-                    held,
-                }));
-                process.exit(1);
-                break;
-            }
-            case 'throttled': {
-                if (noWait) {
+            catch (error) {
+                if (!(error instanceof SquareError))
+                    throw error;
+                const freshSquare = await openSquare(squarePath, { clock: nowMs });
+                const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
+                const headerCount = fresh.participantCount;
+                const held = fresh.held;
+                if (error.code === 'behind') {
                     const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                    process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'throttled', delayMs: decision.delayMs, draftPath, participantCount: headerCount, held }));
+                    process.stdout.write(renderActivityBlocked({
+                        squarePath,
+                        name: knownName,
+                        forceCommand: opts.forceCommand,
+                        activitySummaries: [],
+                        unreadRoomChanges: [...pendingRoomChanges],
+                        draftPath,
+                        participantCount: headerCount,
+                        held,
+                    }));
                     process.exit(1);
+                    return;
                 }
-                if (announcedWait !== 'throttled') {
-                    process.stdout.write(renderExpressWaiting({ reason: 'throttled', delayMs: decision.delayMs }) + '\n');
-                    announcedWait = 'throttled';
-                }
-                await sleep(decision.delayMs);
-                break;
-            }
-            case 'held': {
-                if (noWait) {
-                    const draftPath = saveActivityDraft(squarePath, name, rawInput);
-                    process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'held', holdReason: decision.reason, draftPath, participantCount: headerCount, held }));
+                if (error.code === 'capped') {
+                    process.stdout.write(renderActivityLimit({
+                        squarePath,
+                        name: knownName,
+                        count: fresh.ownActivityCount,
+                        ...(fresh.hardCap === null ? {} : { hardCap: fresh.hardCap }),
+                        draftPath: saveActivityDraft(squarePath, name, rawInput),
+                        participantCount: headerCount,
+                        held,
+                    }));
                     process.exit(1);
+                    return;
                 }
-                if (announcedWait !== 'held') {
-                    process.stdout.write(renderExpressWaiting({ reason: 'held' }) + '\n');
-                    announcedWait = 'held';
+                if (error.code === 'throttled') {
+                    const delayMs = error.facts?.retryAfterMs ?? SLEEP_MS;
+                    if (noWait) {
+                        const draftPath = saveActivityDraft(squarePath, name, rawInput);
+                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'throttled', delayMs, draftPath, participantCount: headerCount, held }));
+                        process.exit(1);
+                    }
+                    if (announcedWait !== 'throttled') {
+                        process.stdout.write(renderExpressWaiting({ reason: 'throttled', delayMs }) + '\n');
+                        announcedWait = 'throttled';
+                    }
+                    await sleep(delayMs);
+                    continue;
                 }
-                await sleep(SLEEP_MS);
-                break;
-            }
-            case 'bell_quota': {
-                process.stdout.write(withPathOutput(squarePath, [`✕ the bell stays quiet for now`, `  · you can ring it again at ${formatTimestamp(decision.nextAt)}`].join('\n'), { participantCount: headerCount, held }));
-                process.exit(1);
+                if (error.code === 'held') {
+                    const holdReason = fresh.holdReason;
+                    if (noWait) {
+                        const draftPath = saveActivityDraft(squarePath, name, rawInput);
+                        process.stdout.write(renderExpressNoWait({ squarePath, name: knownName, reason: 'held', holdReason, draftPath, participantCount: headerCount, held }));
+                        process.exit(1);
+                    }
+                    if (announcedWait !== 'held') {
+                        process.stdout.write(renderExpressWaiting({ reason: 'held' }) + '\n');
+                        announcedWait = 'held';
+                    }
+                    await sleep(SLEEP_MS);
+                    continue;
+                }
+                if (error.code === 'bell_quota') {
+                    const nextAt = nowMs() + (error.facts?.retryAfterMs ?? 1);
+                    process.stdout.write(withPathOutput(squarePath, [`✕ the bell stays quiet for now`, `  · you can ring it again at ${formatTimestamp(nextAt)}`].join('\n'), { participantCount: headerCount, held }));
+                    process.exit(1);
+                    return;
+                }
+                throw error;
             }
         }
     }
+    finally {
+        await square.close();
+    }
 }

package/dist/artifact.d.ts

@@ -0,0 +1,20 @@
+import { type BuildOptions, type HardCap, type SquareState, type SquareRuntimeState } from './model.js';
+export interface DoctorProblem {
+    kind: string;
+    message: string;
+}
+export interface DiagnoseResult {
+    unfixable?: string;
+    problems: DoctorProblem[];
+    state?: SquareState;
+}
+export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeState;
+export declare function createSquareState(options: BuildOptions & {
+    hardCap: HardCap;
+}, snippet: string): SquareState;
+export declare function encodeSquare(squareState: SquareState): Buffer;
+export declare function decodeSquare(bytes: Buffer): SquareState;
+export declare function writeSquareFile(squarePath: string, squareState: SquareState): void;
+export declare function loadSquare(squarePath: string): SquareState;
+export declare function probeSquare(squarePath: string): SquareState | undefined;
+export declare function diagnoseSquareFile(squarePath: string): DiagnoseResult;

package/dist/artifact.js

@@ -3,10 +3,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { TextDecoder } from 'node:util';
 import zlib from 'node:zlib';
-import { isWakeRouteKind, nameKey, SquareError, } from './model.js';
+import { isWakeRouteKind, InternalSquareError, nameKey, SquareError, } from './model.js';
 import { parseActivityId } from './square-core.js';
 const SQUARE_MAGIC = Buffer.from('SQUARE01', 'ascii');
-const ARCHIVE_MAGIC = Buffer.from('SQARCH01', 'ascii');
 const LENGTH_BYTES = 4;
 const DIGEST_BYTES = 32;
 const HEADER_BYTES = SQUARE_MAGIC.length + LENGTH_BYTES + DIGEST_BYTES;
@@ -185,7 +184,7 @@ function validateActs(value) {
     }
     return true;
 }
-function validateSquareDoc(value) {
+function validateSquareState(value) {
     if (!isObject(value)
         || !hasExactKeys(value, ['hardCap', 'preamble', 'warmup', 'acts', 'runtime'], ['throttlePerMinute'])
         || !(value.hardCap === null || (Number.isSafeInteger(value.hardCap) && value.hardCap > 0))
@@ -279,7 +278,7 @@ function readGuide(name) {
         throw error;
     }
 }
-export function createSquareDoc(options, snippet) {
+export function createSquareState(options, snippet) {
     const guides = [readGuide('participant')];
     if (options.template !== undefined)
         guides.push(readGuide(options.template));
@@ -292,23 +291,11 @@ export function createSquareDoc(options, snippet) {
         runtime: emptyRuntimeState(),
     };
 }
-export function encodeSquare(doc) {
-    return encodeEnvelope(SQUARE_MAGIC, validateSquareDoc(doc));
+export function encodeSquare(squareState) {
+    return encodeEnvelope(SQUARE_MAGIC, validateSquareState(squareState));
 }
 export function decodeSquare(bytes) {
-    return validateSquareDoc(decodeEnvelope(bytes, SQUARE_MAGIC));
-}
-export function encodeArchive(acts) {
-    if (!validateActs(acts))
-        throw invalidArtifact('archive activity schema is malformed.');
-    return encodeEnvelope(ARCHIVE_MAGIC, { acts });
-}
-export function decodeArchive(bytes) {
-    const value = decodeEnvelope(bytes, ARCHIVE_MAGIC);
-    if (!isObject(value) || !hasExactKeys(value, ['acts']) || !validateActs(value.acts)) {
-        throw invalidArtifact('archive schema is malformed.');
-    }
-    return value.acts;
+    return validateSquareState(decodeEnvelope(bytes, SQUARE_MAGIC));
 }
 function readArtifact(squarePath) {
     try {
@@ -316,7 +303,7 @@ function readArtifact(squarePath) {
     }
     catch (error) {
         if (error.code === 'ENOENT') {
-            throw new SquareError('not_found', `square file not found: ${squarePath}`);
+            throw new InternalSquareError('not_found', `square file not found: ${squarePath}`);
         }
         throw error;
     }
@@ -341,20 +328,14 @@ function atomicWrite(target, bytes) {
         throw error;
     }
 }
-export function writeSquareFile(squarePath, doc) {
+export function writeSquareFile(squarePath, squareState) {
     requireSquareExtension(squarePath);
-    atomicWrite(squarePath, encodeSquare(doc));
+    atomicWrite(squarePath, encodeSquare(squareState));
 }
 export function loadSquare(squarePath) {
     requireSquareExtension(squarePath);
     return decodeSquare(readArtifact(squarePath));
 }
-export function writeArchiveFile(archivePath, acts) {
-    atomicWrite(archivePath, encodeArchive(acts));
-}
-export function loadArchive(archivePath) {
-    return decodeArchive(readArtifact(archivePath));
-}
 export function probeSquare(squarePath) {
     if (!squarePath.endsWith('.square'))
         return undefined;
@@ -382,7 +363,7 @@ export function probeSquare(squarePath) {
 }
 export function diagnoseSquareFile(squarePath) {
     try {
-        return { problems: [], doc: loadSquare(squarePath) };
+        return { problems: [], state: loadSquare(squarePath) };
     }
     catch (error) {
         return {

package/dist/automatic-session.d.ts

@@ -0,0 +1,5 @@
+export type AutomaticProvider = 'codex' | 'claude' | 'opencode' | 'pi';
+export declare function publicSquarePath(cwd: string): string;
+export declare function automaticParticipant(provider: AutomaticProvider, sessionId: string, env: NodeJS.ProcessEnv): string;
+export declare function automaticSessionStart(provider: AutomaticProvider, sessionId: string, cwd: string, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+export declare function automaticSessionEnd(provider: AutomaticProvider, sessionId: string, cwd: string, env?: NodeJS.ProcessEnv): Promise<void>;

package/dist/automatic-session.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { Square } from './square-wiring.js';
+import { entryPresentation } from './views.js';
+import { canonicalSquarePath, lookupSession, lookupSessionBindings, recordSessionDone, recordSessionJoin } from './registry.js';
+import { participantIdentity, renderAmbientEvent } from './presentation.js';
+import { validateName } from './model.js';
+const providerEnv = {
+    codex: 'CODEX_THREAD_ID',
+    claude: 'CLAUDE_CODE_SESSION_ID',
+    opencode: 'OPENCODE_SESSION_ID',
+    pi: 'SQUARE_PI_SESSION_ID',
+};
+export function publicSquarePath(cwd) {
+    return path.join(cwd, '.square', 'PUBLIC.square');
+}
+export function automaticParticipant(provider, sessionId, env) {
+    const configured = env.SQUARE_PARTICIPANT_NAME?.trim();
+    if (configured) {
+        validateName(configured);
+        return configured;
+    }
+    const digest = createHash('sha256').update(sessionId, 'utf8').digest('hex').slice(0, 12);
+    return `${provider}-${digest}`;
+}
+export async function automaticSessionStart(provider, sessionId, cwd, env = process.env) {
+    const squarePath = publicSquarePath(cwd);
+    if (!fs.existsSync(squarePath))
+        return undefined;
+    let reader;
+    try {
+        reader = await openSquare(squarePath);
+    }
+    catch (error) {
+        process.stderr.write(`! PUBLIC.square unreadable: ${error instanceof Error ? error.message : String(error)}\n`);
+        return undefined;
+    }
+    const name = automaticParticipant(provider, sessionId, env);
+    const bindings = lookupSession(sessionId);
+    const before = await entryPresentation(reader, name);
+    if (bindings.some((binding) => canonicalSquarePath(binding.squarePath) === canonicalSquarePath(squarePath) && binding.name === name) && before.joined) {
+        await closeOpenSquare(reader);
+        return undefined;
+    }
+    await closeOpenSquare(reader);
+    const square = await Square.at({ path: squarePath });
+    try {
+        await square.join(name);
+        const channel = provider === 'claude' ? 'claude-code' : provider;
+        recordSessionJoin(sessionId, name, squarePath, channel, { ...env, [providerEnv[provider]]: sessionId });
+        const afterSquare = await openSquare(squarePath);
+        const after = await entryPresentation(afterSquare, name, 10).finally(() => closeOpenSquare(afterSquare));
+        const activity = after.recentActivities.map((event) => renderAmbientEvent(event, name, {
+            now: Date.now(),
+            preview: 200,
+            actNumber: event.kind === 'say' ? after.sayNumbers[event.index] : undefined,
+        })).filter(Boolean).join('\n\n');
+        return [`You joined the public square as ${participantIdentity(name)}.`, after.scene, after.context ? `context\n${after.context}` : '', activity ? `recent activity\n${activity}` : ''].filter(Boolean).join('\n\n');
+    }
+    finally {
+        await square.close();
+    }
+}
+export async function automaticSessionEnd(provider, sessionId, cwd, env = process.env) {
+    const squarePath = publicSquarePath(cwd);
+    const channel = provider === 'claude' ? 'claude-code' : provider;
+    const binding = lookupSessionBindings(sessionId).find((item) => canonicalSquarePath(item.squarePath) === canonicalSquarePath(squarePath) && item.channel === channel);
+    if (binding === undefined || !fs.existsSync(squarePath))
+        return;
+    const reader = await openSquare(squarePath);
+    const joined = await entryPresentation(reader, binding.name).finally(() => closeOpenSquare(reader));
+    if (!joined.joined)
+        return;
+    const square = await Square.at({ path: squarePath });
+    try {
+        const participant = await square.join(binding.name);
+        await participant.done();
+    }
+    finally {
+        await square.close();
+    }
+    recordSessionDone(sessionId, binding.name, squarePath, channel, env);
+}

package/dist/boundary-presentation.d.ts

@@ -0,0 +1,5 @@
+import type { InboxMembership } from './model.js';
+/** A fresh blocking catch owns only the notifications admitted by its filter. */
+export declare function pendingAtBoundary(inbox: InboxMembership[]): InboxMembership[];
+export declare function renderPendingAtBoundary(inbox: InboxMembership[]): string;
+export declare function presentPendingAtBoundary<T>(sessionId: string, present: (context: string) => T, lookup?: (sessionId: string) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -1,6 +1,6 @@
 import { leaseOwnsNotification, notificationMessageId } from './delivery.js';
 import { sessionInbox } from './inbox.js';
-import { participantCommandPrefix } from './presentation.js';
+import { participantCommandPrefix, participantIdentity } from './presentation.js';
 import { presentOnce } from './presented.js';
 const BODY_MAX = 200;
 const CONTEXT_MAX = 1200;
@@ -43,7 +43,7 @@ export function renderPendingAtBoundary(inbox) {
         const command = `${participantCommandPrefix(membership.squarePath, membership.name)} catch --now`;
         const id = notificationMessageId(membership.squarePath, notification.actIndex);
         const block = [
-            `${id} · ${membership.squarePath}: @${membership.name} from @${notification.actor} (${notification.route})`,
+            `${id} · ${membership.squarePath}: ${participantIdentity(membership.name)} from ${participantIdentity(notification.actor)} (${notification.route})`,
             bodyPreview(notification.body),
             `Ack with: ${command}`,
         ].join('\n');
@@ -72,6 +72,7 @@ export function renderPendingAtBoundary(inbox) {
         ...footer,
     ].join('\n');
 }
-export function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env) {
-    return presentOnce(sessionId, (id) => pendingAtBoundary(lookup(id)), (inbox) => present(renderPendingAtBoundary(inbox)), env);
+export async function presentPendingAtBoundary(sessionId, present, lookup = sessionInbox, env = process.env) {
+    const inbox = await lookup(sessionId);
+    return presentOnce(sessionId, () => pendingAtBoundary(inbox), (inbox) => present(renderPendingAtBoundary(inbox)), env);
 }

package/dist/claude-hook.d.ts

@@ -0,0 +1,9 @@
+import type { InboxMembership } from './model.js';
+export interface NativeHookInput {
+    session_id?: unknown;
+    hook_event_name?: unknown;
+    cwd?: unknown;
+}
+export declare function runClaudeHookAsync(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;
+export declare function claudeHookResponse(input: NativeHookInput, lookup?: (sessionId: string) => Promise<InboxMembership[]> | InboxMembership[], env?: NodeJS.ProcessEnv): Promise<object | undefined>;
+export declare function runClaudeHook(inputText: string, env?: NodeJS.ProcessEnv): Promise<string>;

package/dist/claude-hook.js

@@ -1,13 +1,45 @@
 import { presentPendingAtBoundary } from './boundary-presentation.js';
 import { sessionInbox } from './inbox.js';
-export function claudeHookResponse(input, lookup = sessionInbox, env = process.env) {
+import { automaticSessionEnd, automaticSessionStart } from './automatic-session.js';
+export async function runClaudeHookAsync(inputText, env = process.env) {
+    let input;
+    try {
+        input = JSON.parse(inputText);
+    }
+    catch {
+        return '';
+    }
+    if (input === null || typeof input !== 'object')
+        return '';
+    const value = input;
+    if (typeof value.session_id !== 'string' || typeof value.cwd !== 'string')
+        return runClaudeHook(inputText, env);
+    if (value.hook_event_name === 'SessionStart' || value.hook_event_name === 'SessionResume') {
+        try {
+            const context = await automaticSessionStart('claude', value.session_id, value.cwd, env);
+            return context === undefined ? '' : `${JSON.stringify({ hookSpecificOutput: { hookEventName: value.hook_event_name, additionalContext: context } })}\n`;
+        }
+        catch {
+            return '';
+        }
+    }
+    if (value.hook_event_name === 'SessionEnd') {
+        try {
+            await automaticSessionEnd('claude', value.session_id, value.cwd, env);
+        }
+        catch { /* end remains bounded */ }
+        return '';
+    }
+    return runClaudeHook(inputText, env);
+}
+export async function claudeHookResponse(input, lookup = sessionInbox, env = process.env) {
     if (typeof input.session_id !== 'string' || input.session_id === '')
         return undefined;
     if (input.hook_event_name !== 'PostToolBatch')
         return undefined;
     return presentPendingAtBoundary(input.session_id, (context) => ({ hookSpecificOutput: { hookEventName: 'PostToolBatch', additionalContext: context } }), lookup, env);
 }
-export function runClaudeHook(inputText, env = process.env) {
+export async function runClaudeHook(inputText, env = process.env) {
     let input;
     try {
         input = JSON.parse(inputText);
@@ -17,6 +49,6 @@ export function runClaudeHook(inputText, env = process.env) {
     }
     if (input === null || typeof input !== 'object')
         return '';
-    const response = claudeHookResponse(input, sessionInbox, env);
+    const response = await claudeHookResponse(input, sessionInbox, env);
     return response === undefined ? '' : `${JSON.stringify(response)}\n`;
 }