@astrosheep/square 0.4.0 → 0.4.2

package/dist/artifact.d.ts

@@ -1,9 +1,7 @@
 import { type BuildOptions } from './model.js';
 import type { SquareResourceOwner, SquareArtifactPort } from './ports.js';
 import { type SquareState } from './square-sqlite.js';
-import type { ChannelArtifact } from './channel-ports.js';
 export { openExistingSquareDatabase } from './artifact-store.js';
-export declare function channelArtifact(port: SquareArtifactPort): ChannelArtifact;
 /** Explicit-lifetime holder of one reused artifact connection. Request cancellation
  * never becomes the shared connection's lifetime; close drains the owner once. */
 export declare function createSquareResourceOwner(): SquareResourceOwner;
@@ -24,7 +22,7 @@ export interface SquareSnapshot {
     readonly state: SquareState;
     readonly revision: number;
 }
-/** Agora composition over the same lower SQL and ordered store used by standalone Channel. */
+/** Square social state and producer state share one synchronous artifact transaction. */
 export declare function createArtifactPort(location: string, initial?: SquareState, externalSignal?: AbortSignal): SquareArtifactPort;
 export declare function createSquareFile(location: string, state: SquareState, signal?: AbortSignal): Promise<boolean>;
 export declare function writeSquareFile(location: string, state: SquareState, signal?: AbortSignal): Promise<void>;

package/dist/artifact.js

@@ -4,24 +4,10 @@ import { canonicalPath } from './canonical-path.js';
 import { InternalSquareError, SquareError } from './model.js';
 import { wrapSquareWrite } from './square-domain.js';
 import { createSqliteDriver, initializeSqlite, exportSqliteState, inspectSqlite, emptyRuntimeState, squareStoreFormat } from './square-sqlite.js';
-import { createChannelSqlite } from './sqlite-channel.js';
-import { channelLowerSchema } from './channel-sqlite-schema.js';
 import { resetStorageMeta } from './sqlite-framing.js';
 import { createArtifactStore, createStoreFile, replaceStoreFile, inspectStore, observeStoreRevision } from './artifact-store.js';
-import { channelReads, channelWrites } from './channel-artifact.js';
 export { openExistingSquareDatabase } from './artifact-store.js';
-export function channelArtifact(port) {
-    return {
-        read: (select, signal) => port.read(facts => select(facts.channel), signal),
-        transactAs: (authority, change, signal) => port.transactAs(authority, facts => change(facts.channel), signal),
-        claimDelivery: (input, signal) => port.claimDelivery(input, signal),
-        prepareDelivery: (input, signal) => port.prepareDelivery(input, signal),
-        completeDelivery: (input, signal) => port.completeDelivery(input, signal),
-        cancelDeliveries: (seat, through, signal) => port.cancelDeliveries(seat, through, signal),
-        changed: (since, timeout, signal) => port.changed(since, timeout, signal), close: () => port.close(),
-    };
-}
-const format = squareStoreFormat(channelLowerSchema, resetStorageMeta);
+const format = squareStoreFormat(resetStorageMeta);
 /** Explicit-lifetime holder of one reused artifact connection. Request cancellation
  * never becomes the shared connection's lifetime; close drains the owner once. */
 export function createSquareResourceOwner() {
@@ -95,22 +81,21 @@ export async function createSquare(location, options, snippet, signal, includeGu
 }
 const readMethods = [
     'header', 'participant', 'roster', 'attention', 'incomingAttention',
-    'activity', 'activityByMessage', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
+    'activity', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
     'audience', 'directed', 'directedAt', 'directedCount',
     'receipt', 'receiptFacts', 'lease', 'participantCounts', 'seat', 'seatsForOwner',
-    'deliveryEvidence', 'deliveryByToken', 'cancelledThrough', 'deliveryDeferrals',
+    'pendingPosts', 'postedPosts', 'ownsPost',
 ];
-const writeMethods = ['applyLanding', 'putLease', 'removeLease', 'storeSeat', 'removeSeat', 'updateWakeAddress', 'reattachSeat', 'detachSeat'];
-/** Agora composition over the same lower SQL and ordered store used by standalone Channel. */
+const writeMethods = ['applyLanding', 'putLease', 'removeLease', 'storeSeat', 'removeSeat', 'markSeen', 'setSeatAttachment', 'insertNotice', 'ackMatching', 'acquirePost', 'settlePost', 'foldReceipt'];
+/** Square social state and producer state share one synchronous artifact transaction. */
 export function createArtifactPort(location, initial, externalSignal) {
-    const store = createArtifactStore(location, format, initial === undefined ? undefined : db => initializeSqlite(db, initial, 0, channelLowerSchema), externalSignal);
+    const store = createArtifactStore(location, format, initial === undefined ? undefined : db => initializeSqlite(db, initial, 0), externalSignal);
     function transaction(select, write, authority, signal, settlement = false) {
         return store.run(write, ({ db, guard, track }) => {
-            const channel = createChannelSqlite(db);
-            const driver = createSqliteDriver(db, channel);
+            const driver = createSqliteDriver(db);
             track(driver);
-            const reads = Object.assign(Object.fromEntries(readMethods.map(name => [name, guard(driver[name])])), { channel: channelReads(channel, guard) });
-            const writes = Object.assign(Object.fromEntries(writeMethods.map(name => [name, guard(driver[name])])), { channel: channelWrites(channel, guard) });
+            const reads = Object.fromEntries(readMethods.map(name => [name, guard(driver[name])]));
+            const writes = Object.fromEntries(writeMethods.map(name => [name, guard(driver[name])]));
             const gate = write ? wrapSquareWrite(reads, writes, authority) : undefined;
             const value = select(gate?.facts ?? reads);
             gate?.complete();
@@ -122,24 +107,15 @@ export function createArtifactPort(location, initial, externalSignal) {
         transactAs: (authority, change, signal) => transaction(change, true, authority, signal),
         settleAs: (authority, change) => transaction(change, true, authority, undefined, true),
         revision: store.revision, deliveryRevision: store.deliveryRevision,
-        async claimDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.channel.claimDelivery(input), signal)).value; },
-        async prepareDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.channel.prepareDelivery(input), signal)).value; },
-        async completeDelivery(input, signal) { return (await port.transactAs({ kind: 'participant', seat: input.seat }, facts => facts.channel.completeDelivery(input), signal)).value; },
-        async cancelDeliveries(seat, through, signal) {
-            return (await port.transactAs({ kind: 'participant', seat }, facts => {
-                const boundary = through ?? facts.channel.header().lastMessageIndex;
-                return boundary < 0 ? false : facts.channel.cancelThrough(seat, boundary);
-            }, signal)).value;
-        },
         changed: store.changed, close: store.close,
     };
     return port;
 }
 export function createSquareFile(location, state, signal) {
-    return createStoreFile(location, format, db => initializeSqlite(db, state, 0, channelLowerSchema), signal);
+    return createStoreFile(location, format, db => initializeSqlite(db, state, 0), signal);
 }
 export function writeSquareFile(location, state, signal) {
-    return replaceStoreFile(location, format, (db, revision) => initializeSqlite(db, state, revision, channelLowerSchema), signal);
+    return replaceStoreFile(location, format, (db, revision) => initializeSqlite(db, state, revision), signal);
 }
 export function readSquareSnapshot(location, signal) {
     return inspectStore(location, format, db => ({ state: exportSqliteState(db), revision: createSqliteDriver(db).header().revision }), signal);
@@ -154,7 +130,7 @@ export const observeSquareRevision = (location) => observeStoreRevision(location
 export const observeSquareDeliveryRevision = (location) => observeStoreRevision(location, format, true);
 export async function diagnoseSquareFile(location) {
     try {
-        return { problems: [], ...await inspectStore(await canonicalPath(location), format, db => inspectSqlite(db, channelLowerSchema)) };
+        return { problems: [], ...await inspectStore(await canonicalPath(location), format, db => inspectSqlite(db)) };
     }
     catch (error) {
         return { unfixable: error instanceof Error ? error.message : String(error), problems: [] };

package/dist/attention-presentation.d.ts

@@ -1,4 +1,3 @@
-export { projectChannelNotification, renderSquareReminder } from './channel-presentation.js';
 import type { DirectedNotificationRoute } from './model.js';
 export declare const ATTENTION_BODY_MAX = 200;
 export interface AttentionPreview {
@@ -8,7 +7,7 @@ export interface AttentionPreview {
     actor: string;
     route: DirectedNotificationRoute;
     body: string;
-    preview?: string;
+    metadataOnly?: boolean;
 }
 export declare function previewAttentionBody(body: string): string;
 export declare function attentionBodyIsClipped(body: string): boolean;
@@ -20,26 +19,7 @@ export declare function projectNotification(attention: AttentionPreview): {
     full: string;
     preview: string;
     description: string;
-    clipped: boolean;
-    agora: boolean;
-};
-/** One stored message: Agora framing when an upper say owns it, Channel's raw frame otherwise. */
-export declare function projectMessageNotification(input: {
-    squarePath: string;
-    recipient: string;
-    actor: string;
-    body: string;
-    preview?: string;
-    agora?: {
-        readonly actIndex: number;
-        readonly route: DirectedNotificationRoute;
-    };
-}): {
-    text: string;
-    full: string;
-    preview: string;
-    description: string;
-    clipped: boolean;
+    isFull: boolean;
 };
 /** Full human expansion never substitutes a sender-owned preview for the stored body. */
 export declare function renderAttentionFull(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -1,5 +1,3 @@
-import { escapeSquareTags, projectChannelNotification } from './channel-presentation.js';
-export { projectChannelNotification, renderSquareReminder } from './channel-presentation.js';
 import { homedir } from 'node:os';
 import { formatActivityId } from './square-core.js';
 export const ATTENTION_BODY_MAX = 200;
@@ -21,14 +19,18 @@ export function renderAttentionDescription({ actor, route }) {
         case 'bell': return `${actor} rang the bell`;
     }
 }
+function escapeSquareTags(text) {
+    return text.replace(/<(\/?)(square-|channel-|system-reminder)/gi, '<\\$1$2');
+}
 function escapeAttribute(value) {
     return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 /** The sole source adapter: transports and cards consume this projection, not delivery modes. */
 export function projectNotification(attention) {
-    const body = attention.body.replace(/\r\n/g, '\n');
+    const body = attention.metadataOnly ? '(structured activity)' : attention.body.replace(/\r\n/g, '\n');
     const description = renderAttentionDescription(attention);
     const remaining = body.length - ATTENTION_BODY_MAX;
+    const isFull = !attention.metadataOnly && remaining <= 0;
     const preview = previewAttentionBody(body);
     const attributes = [
         `square="${escapeAttribute(displayAttentionPath(attention.squarePath))}"`,
@@ -38,19 +40,14 @@ export function projectNotification(attention) {
         ...(remaining > 0 ? [`truncated="${remaining} more chars"`] : []),
     ];
     return {
-        text: [`<square-activity ${attributes.join(' ')}>`, `${description}.`, '', escapeSquareTags(preview), '</square-activity>'].join('\n'),
+        text: [`<square-activity ${attributes.join(' ')}>`, `${description}.`, '', escapeSquareTags(preview),
+            ...(!isFull ? ['', escapeSquareTags(`Use square_catch with location=${JSON.stringify(attention.squarePath)}, as=${JSON.stringify(attention.recipient)}, id=${JSON.stringify(formatActivityId(attention.actIndex))} for the full activity.`)] : []),
+            '</square-activity>'].join('\n'),
         full: ['<square-activity>', `· ${displayAttentionPath(attention.squarePath)} · ${attention.recipient} · ${formatActivityId(attention.actIndex)}`,
             `● ${description}`, '', body, '</square-activity>'].join('\n'),
-        preview, description, clipped: remaining > 0, agora: true,
+        preview, description, isFull,
     };
 }
-/** One stored message: Agora framing when an upper say owns it, Channel's raw frame otherwise. */
-export function projectMessageNotification(input) {
-    if (input.agora === undefined)
-        return projectChannelNotification(input);
-    return projectNotification({ squarePath: input.squarePath, recipient: input.recipient, actor: input.actor,
-        route: input.agora.route, actIndex: input.agora.actIndex, body: input.body });
-}
 /** Full human expansion never substitutes a sender-owned preview for the stored body. */
 export function renderAttentionFull(attention) { return projectNotification(attention).full; }
 export function renderAttentionPreview(attention) { return projectNotification(attention).text; }

package/dist/boundary-presentation.d.ts

@@ -1,14 +1,3 @@
-import type { Owner, PendingMembership } from './model.js';
-export declare function renderPendingAtBoundary(inbox: PendingMembership[]): string;
-/**
- * Serialize a boundary across hook processes so one stale inbox cannot render twice.
- *
- * `lookup` returns the session's memberships for this boundary. It may reuse an observation it has
- * verified against the current presence binding and artifact revision; the boundary still projects
- * presentation evidence live. Every item is claimed and revalidated before the batch sink;
- * after success, captured-seat commits record the winning batch, including budget omissions as
- * clipped (no consumption receipt), without an eligibility veto. Coverage is conservative if a
- * competing claim's removal lets a previously omitted body fit in the final preview.
- * A source that cannot verify its reuse must read the inbox again.
- */
-export declare function presentPendingAtBoundary<T>(identity: Owner, present: (context: string, delivered: PendingMembership[]) => T | Promise<T>, lookup?: (identity: Owner, env?: NodeJS.ProcessEnv, signal?: AbortSignal) => Promise<PendingMembership[]> | PendingMembership[], env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;
+import type { Owner } from './owner.js';
+/** The sink must resolve only after the host has actually accepted the output. */
+export declare function presentPendingAtBoundary<T>(owner: Owner, present: (context: string) => T | Promise<T>, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<T | undefined>;

package/dist/boundary-presentation.js

@@ -1,115 +1,40 @@
-import { squareIndexPath } from './square-index.js';
-import { createHash } from 'node:crypto';
-import { withFileLock } from './file-lock.js';
-import { createArtifactPort } from './artifact.js';
-import { preparePendingPresentation } from './presentation-operations.js';
-import { presentPreparedBatch } from './delivery-effects.js';
-import { sessionInbox, projectBoundaryEligibility, pendingKey } from './inbox.js';
-import { projectChannelNotification, projectNotification, renderSquareReminder } from './attention-presentation.js';
+import { DeliveryLedger } from './delivery-ledger.js';
+import { deliveryFrameOverhead, renderDeliveryReminder } from './delivery-frame.js';
 const CONTEXT_MAX = 1200;
-export function renderPendingAtBoundary(inbox) {
-    return renderBoundary(inbox).context;
-}
-function renderBoundary(inbox) {
-    const queued = inbox.flatMap((membership) => membership.notifications.map((notification) => ({ membership, notification })));
-    const blocks = [];
-    const agoraBlocks = [];
-    let remainingAgora = queued.filter(({ notification }) => notification.route !== undefined).length;
-    const entries = [];
-    let omitted = 0;
-    const omission = (count) => `${count} more ${count === 1 ? 'activity' : 'activities'} not shown.`;
-    for (const entry of queued) {
-        const { membership, notification } = entry;
-        // The omission line represents the rest of this batch too, but never consumes its bodies.
-        const coverage = { membership, messageIndex: notification.messageIndex, markSeen: false };
-        entries.push(coverage);
-        const projected = notification.route === undefined
-            ? projectChannelNotification({ squarePath: membership.location, recipient: membership.seat.participant,
-                actor: notification.actor, body: notification.body, ...(notification.preview === undefined ? {} : { preview: notification.preview }) })
-            : projectNotification({ squarePath: membership.location, actIndex: notification.actIndex ?? notification.messageIndex,
-                recipient: membership.seat.participant, actor: notification.actor, route: notification.route,
-                body: notification.body, ...(notification.preview === undefined ? {} : { preview: notification.preview }) });
-        const block = projected.text;
-        if ('agora' in projected && projected.agora) {
-            remainingAgora -= 1;
-            const omittedAfter = omitted + remainingAgora;
-            const prospective = renderSquareReminder([...agoraBlocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
-            if (prospective.length > CONTEXT_MAX) {
-                omitted += 1;
-                continue;
-            }
-            agoraBlocks.push(block);
-        }
-        blocks.push(block);
-        coverage.markSeen = !projected.clipped;
-    }
-    return {
-        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])]),
-        entries,
-    };
-}
-async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sessionInbox, env = process.env, signal) {
-    const inbox = await lookup(identity, env, signal);
-    if (signal?.aborted)
-        return undefined;
-    const pending = await projectBoundaryEligibility(inbox);
-    if (pending.length === 0 || signal?.aborted)
-        return undefined;
-    const artifacts = new Map();
-    const claims = [];
+/** The sink must resolve only after the host has actually accepted the output. */
+export async function presentPendingAtBoundary(owner, present, env = process.env, signal) {
+    const ledger = await DeliveryLedger.open({ location: env.SQUARE_DELIVERY });
     try {
+        const session = await ledger.session(owner);
+        if (!session || session.state !== 'attached' || signal?.aborted)
+            return undefined;
+        const claim = await ledger.claimPresentation(owner, { generation: session.generation, budgetChars: CONTEXT_MAX - deliveryFrameOverhead({ tagged: true }), signal });
+        if (!claim)
+            return undefined;
+        let current;
         try {
-            // Enumeration owns discovery/connections only; returned handles belong to the common runner.
-            for (const entry of renderBoundary(pending).entries) {
-                const { location, seat } = entry.membership;
-                let artifact = artifacts.get(location);
-                if (artifact === undefined) {
-                    // Keep connections alive through all signal-independent settlement/cleanup.
-                    artifact = createArtifactPort(location);
-                    artifacts.set(location, artifact);
-                }
-                const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
-                    message: entry.messageIndex, seat, markSeen: entry.markSeen, signal });
-                if (claim !== undefined)
-                    claims.push({ key: pendingKey(entry.membership, entry.messageIndex), claim });
-            }
+            current = await claim.current(signal);
         }
         catch (error) {
-            // Transfer has not happened: enumeration must abandon any custody already acquired.
-            await Promise.all(claims.map(({ claim }) => claim.release()));
+            await claim.settle('released');
             throw error;
         }
-        const report = await presentPreparedBatch(claims.map(({ claim }) => claim), eligibleClaims => {
-            const eligible = new Set(claims.filter(({ claim }) => eligibleClaims.includes(claim)).map(({ key }) => key));
-            const delivered = pending.map(membership => ({ ...membership,
-                notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.messageIndex))),
-            })).filter(membership => membership.notifications.length > 0);
-            return { payload: { context: renderBoundary(delivered).context, delivered }, included: eligibleClaims };
-        }, payload => present(payload.context, payload.delivered), { signal });
-        if (report.observation.kind === 'threw')
-            throw report.observation.error;
-        for (const { result } of report.settlements)
-            if (result.persistence.status === 'error')
-                throw result.persistence.error;
-        return report.observation.kind === 'returned' ? report.observation.value : undefined;
+        if (!current || signal?.aborted) {
+            await claim.settle('released');
+            return undefined;
+        }
+        let result;
+        try {
+            result = await present(renderDeliveryReminder(claim.cards.map(card => card.text), { tagged: true }));
+        }
+        catch (error) {
+            await claim.settle('unknown');
+            throw error;
+        }
+        await claim.settle('presented');
+        return result;
     }
     finally {
-        await Promise.all([...artifacts.values()].map(artifact => artifact.close()));
+        await ledger.close();
     }
 }
-/**
- * Serialize a boundary across hook processes so one stale inbox cannot render twice.
- *
- * `lookup` returns the session's memberships for this boundary. It may reuse an observation it has
- * verified against the current presence binding and artifact revision; the boundary still projects
- * presentation evidence live. Every item is claimed and revalidated before the batch sink;
- * after success, captured-seat commits record the winning batch, including budget omissions as
- * clipped (no consumption receipt), without an eligibility veto. Coverage is conservative if a
- * competing claim's removal lets a previously omitted body fit in the final preview.
- * A source that cannot verify its reuse must read the inbox again.
- */
-export async function presentPendingAtBoundary(identity, present, lookup = sessionInbox, env = process.env, signal) {
-    const indexPath = squareIndexPath(env);
-    const ownerKey = createHash('sha256').update(JSON.stringify(identity)).digest('hex');
-    return withFileLock(`${indexPath}.boundary-${ownerKey}.lock`, { retryMs: 10, signal }, () => presentPendingAtBoundaryUnlocked(identity, present, lookup, env, signal));
-}

package/dist/card-presentation.d.ts

@@ -0,0 +1 @@
+export { isCardPresentation, type CardPresentation } from './plugins/paseo/shared/card-presentation.js';

package/dist/card-presentation.js

@@ -0,0 +1,2 @@
+// Keep the shared schema inside the standalone Paseo plugin's package boundary.
+export { isCardPresentation } from './plugins/paseo/shared/card-presentation.js';

package/dist/catch-decisions.js

@@ -64,19 +64,13 @@ export function decideCatch(facts, requestedName, options, at) {
     }
     let consumed;
     try {
-        // Receipts are recorded by message coordinate; the batch hydration above already resolved each selected say.
-        let selected = new Map();
         consumed = consumeReceived({
             ...squareReceiveRead(facts),
-            load(keys) { selected = facts.activities(keys).reduce((map, item) => map.set(item.index, item), new Map()); return selected; },
             addressed(recipient, index) {
                 const head = facts.directed(recipient, { indexes: [index], kinds: ['say'] }, { edge: 'oldest', limit: 1 }).items[0];
                 return head === undefined ? undefined : { key: head.index, via: head.route };
             },
-            insertReceipt: (ref, time) => {
-                const item = selected.get(ref.item);
-                return item?.kind === 'say' && facts.channel.markSeen(ref.recipient, [item.messageIndex], time) > 0;
-            },
+            insertReceipt: (ref, time) => facts.markSeen(ref.recipient, [ref.item], time) > 0,
         }, viewer, selection, at);
     }
     catch (error) {

package/dist/claude-boundary-state.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod/v4';
+declare const stateSchema: z.ZodObject<{
+    generation: z.ZodString;
+    promptId: z.ZodOptional<z.ZodString>;
+    stopEpoch: z.ZodString;
+    consumed: z.ZodBoolean;
+    ended: z.ZodBoolean;
+}, z.core.$strip>;
+export type ClaudeBoundary = z.infer<typeof stateSchema>;
+/** Receiver operational facts only: no cards, claims, or payload copies. */
+export declare function claudeBoundaryStore(session: string, env: NodeJS.ProcessEnv): {
+    start(attach: () => Promise<string | false>): Promise<void>;
+    end(): Promise<ClaudeBoundary | undefined>;
+    prompt(promptId: string | undefined): Promise<void>;
+    capture(promptId: string): Promise<ClaudeBoundary | undefined>;
+    current(captured: ClaudeBoundary): Promise<boolean>;
+    consume(captured: ClaudeBoundary): Promise<void>;
+    watch<T>(signal: AbortSignal, run: () => Promise<T>): Promise<T>;
+};
+export {};

package/dist/claude-boundary-state.js

@@ -0,0 +1,84 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod/v4';
+import { deliveryLedgerLocation } from './delivery-ledger.js';
+import { withFileLock } from './file-lock.js';
+const stateSchema = z.object({
+    generation: z.string().min(1), promptId: z.string().min(1).optional(),
+    stopEpoch: z.string().min(1), consumed: z.boolean(), ended: z.boolean(),
+});
+/** Receiver operational facts only: no cards, claims, or payload copies. */
+export function claudeBoundaryStore(session, env) {
+    const root = path.join(path.dirname(deliveryLedgerLocation(env)), 'claude-hooks');
+    const key = createHash('sha256').update(session).digest('hex');
+    const file = path.join(root, `${key}.json`);
+    async function mutate(change) {
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        await fs.chmod(root, 0o700);
+        return withFileLock(path.join(root, `${key}.lock`), { retryMs: 10, signal: AbortSignal.timeout(2500) }, async () => {
+            let state;
+            try {
+                state = stateSchema.parse(JSON.parse(await fs.readFile(file, 'utf8')));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            return change(state, async (next) => {
+                const temporary = `${file}.${randomUUID()}.tmp`;
+                try {
+                    await fs.writeFile(temporary, JSON.stringify(next), { mode: 0o600, flag: 'wx' });
+                    await fs.rename(temporary, file);
+                }
+                finally {
+                    await fs.rm(temporary, { force: true });
+                }
+            });
+        });
+    }
+    const matches = (state, captured) => !!state && !state.ended && !state.consumed
+        && state.generation === captured.generation && state.promptId === captured.promptId && state.stopEpoch === captured.stopEpoch;
+    return {
+        async start(attach) {
+            await mutate(async (state, save) => {
+                if (state)
+                    await save({ ...state, promptId: undefined, ended: true, stopEpoch: randomUUID() });
+                const generation = await attach();
+                if (generation)
+                    await save({ generation, stopEpoch: randomUUID(), consumed: false, ended: false });
+            });
+        },
+        async end() {
+            return mutate(async (state, save) => {
+                if (state)
+                    await save({ ...state, ended: true, stopEpoch: randomUUID() });
+                return state;
+            });
+        },
+        async prompt(promptId) {
+            await mutate(async (state, save) => {
+                if (state && !state.ended)
+                    await save({ ...state, promptId, stopEpoch: randomUUID(), consumed: false });
+            });
+        },
+        capture(promptId) {
+            return mutate(async (state) => state && !state.ended && !state.consumed && state.promptId === promptId ? state : undefined);
+        },
+        current(captured) { return mutate(async (state) => matches(state, captured)); },
+        async consume(captured) {
+            await mutate(async (state, save) => {
+                if (matches(state, captured))
+                    await save({ ...state, consumed: true });
+            });
+        },
+        async watch(signal, run) {
+            await fs.mkdir(root, { recursive: true, mode: 0o700 });
+            const lock = path.join(root, `${key}.watch.lock`);
+            const handle = await fs.open(lock, 'a', 0o600);
+            await handle.close();
+            // A newer Stop waits through bounded shutdown; it must not skip a busy lock.
+            return withFileLock(lock, { retryMs: 10, signal }, run);
+        },
+    };
+}

package/dist/claude-hook.d.ts

@@ -0,0 +1,2 @@
+export declare function runClaudeHook(text: string, env?: NodeJS.ProcessEnv, sink?: (value: string) => void | Promise<void>): Promise<string>;
+export declare function runClaudeWatch(text: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal, output?: (frame: string) => Promise<void>): Promise<string>;