@astrosheep/square 0.3.4 → 0.3.6

package/dist/registry.js

@@ -9,11 +9,19 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { randomUUID } from 'node:crypto';
+import { loadSquare } from './artifact.js';
 import { nameKey, sameName } from './model.js';
+import { isCurrentlyJoined } from './runtime.js';
 const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 const COMPACT_BYTES = 64 * 1024;
 const COMPACT_LINES = 1000;
 const VALID_CHANNELS = new Set(['claude-code', 'codex', 'opencode', 'pi', 'paseo', 'unknown']);
+const LOCAL_SESSION_SOURCES = [
+    { variable: 'CLAUDE_CODE_SESSION_ID', channel: 'claude-code', child: 'CLAUDE_CODE_CHILD_SESSION' },
+    { variable: 'CODEX_THREAD_ID', channel: 'codex' },
+    { variable: 'OPENCODE_SESSION_ID', channel: 'opencode' },
+    { variable: 'SQUARE_PI_SESSION_ID', channel: 'pi' },
+];
 export function registryPath() {
     if (process.env['SQUARE_REGISTRY'])
         return process.env['SQUARE_REGISTRY'];
@@ -113,9 +121,8 @@ function foldRegistry(raw, now) {
     }
     return active.sort((a, b) => b.updatedAt - a.updatedAt);
 }
-function compactRegistry(filePath, raw, now) {
-    const active = foldRegistry(raw, now);
-    const compacted = active
+function writeRegistryBindings(filePath, bindings) {
+    const compacted = bindings
         .slice()
         .reverse()
         .map((binding) => JSON.stringify({
@@ -135,6 +142,9 @@ function compactRegistry(filePath, raw, now) {
     fs.writeFileSync(temporary, compacted === '' ? '' : `${compacted}\n`, { mode: 0o600 });
     fs.renameSync(temporary, filePath);
 }
+function compactRegistry(filePath, raw, now) {
+    writeRegistryBindings(filePath, foldRegistry(raw, now));
+}
 function maybeCompactRegistry(filePath, now) {
     let stat;
     try {
@@ -214,53 +224,53 @@ export function lookupParticipant(squarePath, name, now = Date.now()) {
     const canonicalPath = canonicalSquarePath(squarePath);
     return readActiveBindings(now).filter((binding) => binding.squarePath === canonicalPath && sameName(binding.name, name));
 }
-export function localSessionIdentities(env = process.env) {
-    const paseoAgentId = env['PASEO_AGENT_ID']?.trim() || undefined;
-    const identities = [];
-    const claudeSessionId = env['CLAUDE_CODE_SESSION_ID']?.trim();
-    if (claudeSessionId) {
-        identities.push({
-            sessionId: claudeSessionId,
-            channel: 'claude-code',
-            child: env['CLAUDE_CODE_CHILD_SESSION'] === '1',
-            ...(paseoAgentId ? { paseoAgentId } : {}),
-        });
+/** Resolve the current local harness owner for a participant, if one is registered. */
+export function localParticipantOwner(squarePath, name, env = process.env, now = Date.now()) {
+    const sessionIds = new Set(localSessionIdentities(env).map((identity) => identity.sessionId));
+    if (sessionIds.size === 0)
+        return undefined;
+    return lookupParticipant(squarePath, name, now).find((binding) => sessionIds.has(binding.sessionId))?.ownerId;
+}
+function bindingIsProvablyObsolete(binding) {
+    if (!fs.existsSync(binding.squarePath))
+        return true;
+    try {
+        return !isCurrentlyJoined(loadSquare(binding.squarePath).acts, binding.name);
     }
-    const codexThreadId = env['CODEX_THREAD_ID']?.trim();
-    if (codexThreadId && !identities.some((identity) => identity.sessionId === codexThreadId)) {
-        identities.push({
-            sessionId: codexThreadId,
-            channel: 'codex',
-            child: false,
-            ...(paseoAgentId ? { paseoAgentId } : {}),
-        });
+    catch {
+        // A temporarily unreadable artifact is uncertain, so preserve its binding.
+        return false;
     }
-    const openCodeSessionId = env['OPENCODE_SESSION_ID']?.trim();
-    if (openCodeSessionId && !identities.some((identity) => identity.sessionId === openCodeSessionId)) {
-        identities.push({
-            sessionId: openCodeSessionId,
-            channel: 'opencode',
-            child: false,
-            ...(paseoAgentId ? { paseoAgentId } : {}),
-        });
+}
+/** Compact the registry and remove only bindings disproved by their authoritative artifact. */
+export function pruneRegistry(now = Date.now()) {
+    const filePath = registryPath();
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
     }
-    const piSessionId = env['SQUARE_PI_SESSION_ID']?.trim();
-    if (piSessionId && !identities.some((identity) => identity.sessionId === piSessionId)) {
-        identities.push({
-            sessionId: piSessionId,
-            channel: 'pi',
-            child: false,
-            ...(paseoAgentId ? { paseoAgentId } : {}),
-        });
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { removed: 0, kept: 0 };
+        throw error;
     }
-    if (paseoAgentId && !identities.some((identity) => identity.sessionId === paseoAgentId)) {
-        identities.push({
-            sessionId: paseoAgentId,
-            channel: 'paseo',
-            child: false,
-            paseoAgentId,
-        });
+    const active = foldRegistry(raw, now);
+    const kept = active.filter((binding) => !bindingIsProvablyObsolete(binding));
+    writeRegistryBindings(filePath, kept);
+    return { removed: active.length - kept.length, kept: kept.length };
+}
+function addLocalSession(identities, sessionId, channel, child, paseoAgentId) {
+    if (!sessionId || identities.some((identity) => identity.sessionId === sessionId))
+        return;
+    identities.push({ sessionId, channel, child, ...(paseoAgentId ? { paseoAgentId } : {}) });
+}
+export function localSessionIdentities(env = process.env) {
+    const paseoAgentId = env['PASEO_AGENT_ID']?.trim() || undefined;
+    const identities = [];
+    for (const source of LOCAL_SESSION_SOURCES) {
+        addLocalSession(identities, env[source.variable]?.trim(), source.channel, source.child !== undefined && env[source.child] === '1', paseoAgentId);
     }
+    addLocalSession(identities, paseoAgentId, 'paseo', false, paseoAgentId);
     return identities;
 }
 /** True when this process belongs to a harness that can deliver Square attention without a foreground catch. */

package/dist/runtime.js

@@ -1,8 +1,4 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { setTimeout as sleep } from 'node:timers/promises';
 import { fold } from './square-core.js';
-import { renderSquareDoc, saveRuntimeSidecar } from './artifact.js';
 import { SquareError, findParticipantName, nameKey, sameName, } from './model.js';
 function parseIntegerEnvValue(name, raw, fallback) {
     if (raw === undefined)
@@ -63,8 +59,13 @@ export function extractMentions(body) {
         matches.push(match[1]);
     return matches;
 }
-/** Pure mention filter for say acts. Broadcast bodies (no @) match any named viewer. */
+/** Pure directed-activity filter. Broadcast bodies (no @) match any named viewer. */
 export function matchesMentionTarget(act, mention) {
+    if (act.reach === 'bell')
+        return true;
+    if (act.reach !== undefined) {
+        return mention === true || sameName(act.reach.beside, mention);
+    }
     const mentions = extractMentions(act.body);
     if (mention === true)
         return mentions.length > 0;
@@ -108,24 +109,12 @@ export function sayNumberFor(acts, target) {
 export function doneNames(acts) {
     return new Set(fold(acts).done.map((participant) => nameKey(participant)));
 }
-export function hasJoined(acts, name) {
-    return fold(acts).participants.some((participant) => sameName(participant.name, name) && participant.joined);
-}
 export function joinedNames(acts) {
     return new Set(acts.filter((act) => act.kind === 'join').map((act) => nameKey(act.actor)));
 }
 export function isCurrentlyJoined(acts, name) {
     return fold(acts).participants.some((participant) => sameName(participant.name, name) && participant.joined);
 }
-/** Timestamp of the recipient's most recent join act, if any. */
-export function lastJoinAt(acts, name) {
-    let last;
-    for (const act of acts) {
-        if (act.kind === 'join' && sameName(act.actor, name))
-            last = act.at;
-    }
-    return last;
-}
 /** Stable index of the recipient's most recent join act, if any. */
 export function lastJoinIndex(acts, name) {
     let last;
@@ -135,11 +124,6 @@ export function lastJoinIndex(acts, name) {
     }
     return last;
 }
-/** Notifications are live only when they land after the recipient joined. */
-export function isPostJoinActivity(acts, name, actIndex) {
-    const joinIndex = lastJoinIndex(acts, name);
-    return joinIndex !== undefined && actIndex > joinIndex;
-}
 export function actStableIndex(act) {
     if (act.index === undefined)
         throw new Error(`act ${act.kind} is missing a stable index`);
@@ -162,26 +146,13 @@ export function currentHold(acts) {
 export function publicActs(acts) {
     return acts.filter((act) => act.kind === 'say' || act.kind === 'done');
 }
-export function roomChangeActs(acts) {
-    return acts.filter((act) => act.kind !== 'say' && act.kind !== 'read');
-}
-export function throttleDelayMs(doc, at) {
-    const limit = doc.throttlePerMinute;
-    if (limit === undefined)
-        return 0;
-    const recent = foldedState(doc).throttleActivityAts.filter((eventAt) => at - eventAt < THROTTLE_WINDOW_MS).sort((a, b) => a - b);
-    if (recent.length < limit)
-        return 0;
-    const releaseAt = recent[recent.length - limit] + THROTTLE_WINDOW_MS;
-    return Math.max(1, releaseAt - at);
-}
 function canonicalRuntimeName(doc, name) {
     return resolveRosterName(doc, name) ?? name;
 }
-export function advanceCursor(doc, name, index, source = 'watch', updatedAt = Date.now()) {
-    return touchPresenceCursor(doc, name, updatedAt, source, index);
+export function advanceCursor(doc, name, index, updatedAt = Date.now()) {
+    return touchPresenceCursor(doc, name, updatedAt, index);
 }
-export function touchPresenceCursor(doc, name, at, source, consumedThroughIndex) {
+export function touchPresenceCursor(doc, name, at, consumedThroughIndex) {
     if (!Number.isFinite(at))
         return false;
     if (consumedThroughIndex !== undefined && (!Number.isInteger(consumedThroughIndex) || consumedThroughIndex < 0))
@@ -192,113 +163,31 @@ export function touchPresenceCursor(doc, name, at, source, consumedThroughIndex)
         ? (current?.consumedThroughIndex ?? readCursor(doc, key))
         : Math.max(current?.consumedThroughIndex ?? -1, consumedThroughIndex);
     const updatedAt = current === undefined ? at : Math.max(current.updatedAt, at);
-    if (current?.consumedThroughIndex === nextIndex && current.updatedAt === updatedAt && current.source === source)
+    if (current?.consumedThroughIndex === nextIndex && current.updatedAt === updatedAt)
         return false;
-    doc.runtime.cursors[key] = { consumedThroughIndex: nextIndex, updatedAt, source };
+    doc.runtime.cursors[key] = { consumedThroughIndex: nextIndex, updatedAt };
     return true;
 }
-/** The canonical delivery ledger is keyed by (recipient, stable act id). */
-export function deliveryReceipt(doc, name, actOrIndex) {
-    const id = actId(actOrIndex);
-    // Delivery planners and runtime writers pass roster-canonical names. Keeping
-    // this a direct lookup is important: pending/status scans must stay linear in
-    // activities rather than folding the whole square once per notification.
-    return doc.runtime.mentionReceipts[name]?.[id];
-}
-export function isDeliveryDelivered(doc, name, actOrIndex) {
-    return deliveryReceipt(doc, name, actOrIndex)?.status === 'delivered';
-}
-export function recordDeliveredDelivery(doc, name, actOrIndex, receipt) {
-    const key = canonicalRuntimeName(doc, name);
-    const id = actId(actOrIndex);
-    const current = deliveryReceipt(doc, key, actOrIndex);
-    if (current?.status === 'delivered')
-        return false;
-    const receipts = doc.runtime.mentionReceipts[key] ?? {};
-    receipts[id] = { status: 'delivered', ...receipt };
-    doc.runtime.mentionReceipts[key] = receipts;
-    return true;
-}
-export function markDeliveredMention(doc, name, actOrIndex, at = Date.now()) {
-    return recordDeliveredDelivery(doc, name, actOrIndex, { at });
-}
-export function mentionDeliveredStatus(doc, name, actOrIndex) {
-    return isDeliveryDelivered(doc, name, actOrIndex) ? 'delivered' : undefined;
-}
-export function markDeliveredMentions(doc, name, delivered, at = Date.now()) {
-    let changed = false;
-    for (const item of delivered) {
-        const act = item.act;
-        if (act.kind !== 'say')
-            continue;
-        // A cursor says only where feed reading reached. The recipient/act receipt is
-        // the delivery fact, so never create one for a broadcast or unrelated say.
-        const directed = act.reach === 'bell' ||
-            (act.reach !== undefined && sameName(act.reach.beside, name)) ||
-            extractMentions(act.body).some((mention) => sameName(mention, name));
-        if (!directed)
-            continue;
-        changed = markDeliveredMention(doc, name, actStableIndex(act), at) || changed;
-    }
-    return changed;
-}
-export function writeSquareDoc(squarePath, doc) {
-    const dir = path.dirname(squarePath);
-    const base = path.basename(squarePath);
-    const tempPath = path.join(dir, `.${base}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.tmp`);
-    fs.writeFileSync(tempPath, renderSquareDoc(doc));
-    fs.renameSync(tempPath, squarePath);
-    saveRuntimeSidecar(squarePath, doc.runtime);
-}
-export function appendAct(squarePath, doc, act) {
-    const indexed = { ...act, index: doc.runtime.nextActIndex };
-    doc.runtime.nextActIndex++;
-    doc.acts.push(indexed);
-    if (indexed.actor !== undefined)
-        touchPresenceCursor(doc, indexed.actor, indexed.at, indexed.kind === 'join' ? 'join' : 'api', actStableIndex(indexed));
-    writeSquareDoc(squarePath, doc);
-    return indexed;
-}
-export function latestIndexedActIndex(items) {
-    return items.reduce((max, item) => Math.max(max, item.index), -1);
+export function latestActIndex(acts) {
+    return acts.reduce((max, act) => Math.max(max, act.index), -1);
 }
 export function freshWatchLease(doc, name, at = Date.now()) {
     const key = canonicalRuntimeName(doc, name);
-    const lease = doc.runtime.leases[key];
+    const lease = watchLease(doc, key);
     if (lease === undefined || lease.expiresAt <= at || at - lease.heartbeatAt > WATCH_STALE_MS)
         return undefined;
     return lease;
 }
-export async function withSquareLock(squarePath, fn) {
-    const lockPath = `${squarePath}.lock`;
-    const lockDir = path.dirname(lockPath);
-    fs.mkdirSync(lockDir, { recursive: true });
-    while (true) {
-        try {
-            const fd = fs.openSync(lockPath, 'wx');
-            fs.writeFileSync(fd, `${process.pid}\n${Date.now()}\n`, 'utf8');
-            fs.closeSync(fd);
-            try {
-                return await fn();
-            }
-            finally {
-                try {
-                    fs.unlinkSync(lockPath);
-                }
-                catch { }
-            }
-        }
-        catch (err) {
-            const errno = err;
-            if (errno.code !== 'EEXIST')
-                throw err;
-            try {
-                const stat = fs.statSync(lockPath);
-                if (Date.now() - stat.mtimeMs > LOCK_STALE_MS)
-                    fs.unlinkSync(lockPath);
-            }
-            catch { }
-            await sleep(LOCK_RETRY_MS);
-        }
-    }
+export function watchLease(doc, name) {
+    return doc.runtime.leases[canonicalRuntimeName(doc, name)];
+}
+export function writeWatchLease(doc, name, lease) {
+    doc.runtime.leases[canonicalRuntimeName(doc, name)] = lease;
+}
+export function removeWatchLease(doc, name, leaseId) {
+    const key = canonicalRuntimeName(doc, name);
+    if (doc.runtime.leases[key]?.leaseId !== leaseId)
+        return false;
+    delete doc.runtime.leases[key];
+    return true;
 }

package/dist/square-application.js

@@ -0,0 +1,264 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { emptyRuntimeState, loadRuntimeSidecar, loadSquare, mergeRuntimeState, renderArtifactAct, renderSquare, renderSquareDoc, saveRuntimeSidecar } from './artifact.js';
+import { coreCompact, coreDone, coreHold, coreResume, decideAct, decideJoin, resolveKnownName } from './decisions.js';
+import { dispatchActNotifications } from './notifications.js';
+import { planRepair } from './doctor.js';
+import { stageReplacement } from './harness-stage.js';
+import { SquareError } from './model.js';
+import { advanceCursor, freshWatchLease, LOCK_RETRY_MS, LOCK_STALE_MS, removeWatchLease, touchPresenceCursor, watchLease, writeWatchLease } from './runtime.js';
+/** The only persistence primitive: one per-square lock, one Markdown write, one sidecar write. */
+export async function withSquareLock(squarePath, fn) {
+    const lockPath = `${squarePath}.lock`;
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    while (true) {
+        let fd;
+        try {
+            fd = fs.openSync(lockPath, 'wx');
+            fs.writeFileSync(fd, `${process.pid}\n${Date.now()}\n`, 'utf8');
+        }
+        catch (error) {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { }
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch { }
+            }
+            const errno = error;
+            if (errno.code !== 'EEXIST')
+                throw error;
+            try {
+                if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS)
+                    fs.unlinkSync(lockPath);
+            }
+            catch { }
+            await sleep(LOCK_RETRY_MS);
+            continue;
+        }
+        fs.closeSync(fd);
+        try {
+            return await fn();
+        }
+        finally {
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { }
+        }
+    }
+}
+export function writeSquareDoc(squarePath, doc) {
+    const temporary = path.join(path.dirname(squarePath), `.${path.basename(squarePath)}.${process.pid}.${Date.now()}.tmp`);
+    fs.writeFileSync(temporary, renderSquareDoc(doc));
+    fs.renameSync(temporary, squarePath);
+    saveRuntimeSidecar(squarePath, doc.runtime);
+}
+export function appendAct(squarePath, doc, act) {
+    const stored = applyActs(doc, [act])[0];
+    writeSquareDoc(squarePath, doc);
+    return stored;
+}
+function applyActs(doc, acts, mutateRuntime) {
+    const stored = [];
+    for (const act of acts) {
+        const item = { ...act, index: doc.runtime.nextActIndex };
+        doc.runtime.nextActIndex++;
+        doc.acts.push(item);
+        if (item.actor !== undefined)
+            touchPresenceCursor(doc, item.actor, item.at, item.index);
+        stored.push(item);
+    }
+    mutateRuntime?.(doc);
+    return stored;
+}
+/**
+ * Publish a dependent persistence file before the Square document. A retained
+ * backup lets a failed document commit restore the prior file exactly.
+ */
+function prepareAppend(filePath, block, existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '') {
+    return stageReplacement(filePath, (stage) => {
+        fs.writeFileSync(stage, `${existing}${existing === '' ? '' : '\n'}${block}\n`);
+    });
+}
+function plan(doc, intent) {
+    switch (intent.type) {
+        case 'join': {
+            const decision = decideJoin(doc, intent.name, intent.now);
+            return { result: decision, acts: [decision.joinAct] };
+        }
+        case 'say': {
+            const decision = decideAct(doc, intent);
+            return {
+                result: decision,
+                acts: decision.type === 'sent' ? [decision.act] : [],
+            };
+        }
+        case 'hold':
+            return { result: undefined, acts: [coreHold(doc, intent.actor, intent.body, intent.now)] };
+        case 'resume':
+            return { result: undefined, acts: [coreResume(doc, intent.actor, intent.now)] };
+        case 'done':
+            return { result: undefined, acts: [coreDone(doc, intent.name, intent.body, intent.now)] };
+        case 'lease': {
+            const name = resolveKnownName(doc, intent.name);
+            const existing = freshWatchLease(doc, name, intent.at);
+            if (existing !== undefined && !intent.force) {
+                return { result: { type: 'active', lease: existing }, acts: [] };
+            }
+            return {
+                result: { type: 'started', name, replaced: existing !== undefined },
+                acts: [],
+                mutateRuntime: (nextDoc) => {
+                    writeWatchLease(nextDoc, name, {
+                        leaseId: intent.leaseId,
+                        ...(intent.ownerId === undefined ? {} : { ownerId: intent.ownerId }),
+                        heartbeatAt: intent.at,
+                        expiresAt: intent.expiresAt,
+                        ...(intent.filter === undefined ? {} : { filter: intent.filter }),
+                    });
+                    touchPresenceCursor(nextDoc, name, intent.at);
+                },
+            };
+        }
+        case 'release-lease': {
+            const name = resolveKnownName(doc, intent.name);
+            if (watchLease(doc, name)?.leaseId !== intent.leaseId) {
+                return { result: { released: false }, acts: [] };
+            }
+            return {
+                result: { released: true },
+                acts: [],
+                mutateRuntime: (nextDoc) => { removeWatchLease(nextDoc, name, intent.leaseId); },
+            };
+        }
+        case 'consume': {
+            const name = resolveKnownName(doc, intent.name);
+            return {
+                result: { name },
+                acts: [],
+                mutateRuntime: (nextDoc) => { advanceCursor(nextDoc, name, intent.throughIndex, intent.at); },
+            };
+        }
+        case 'compact': {
+            const result = coreCompact(doc, intent.keep);
+            const archive = result.archived;
+            return {
+                result,
+                acts: [],
+                replaceDoc: result.doc,
+                preparePersistence: archive.length === 0
+                    ? undefined
+                    : () => {
+                        const existing = fs.existsSync(intent.archivePath) ? fs.readFileSync(intent.archivePath, 'utf8') : '';
+                        const block = archive
+                            .map((act, index) => renderArtifactAct(act, { first: existing === '' && index === 0 }))
+                            .join('\n');
+                        return prepareAppend(intent.archivePath, block, existing);
+                    },
+            };
+        }
+        case 'repair':
+            return {
+                result: undefined,
+                acts: [],
+                replaceDoc: intent.doc,
+                preparePersistence: intent.quarantine === undefined || intent.quarantine.blocks.length === 0
+                    ? undefined
+                    : () => {
+                        const block = intent.quarantine.blocks.join('\n\n');
+                        return prepareAppend(intent.quarantine.path, block);
+                    },
+            };
+    }
+}
+function commitPlan(squarePath, doc, planned) {
+    const nextDoc = planned.replaceDoc ?? doc;
+    const committed = { result: planned.result, acts: applyActs(nextDoc, planned.acts, planned.mutateRuntime) };
+    if (planned.acts.length === 0 && planned.mutateRuntime === undefined && planned.replaceDoc === undefined) {
+        return committed;
+    }
+    let persistence;
+    try {
+        persistence = planned.preparePersistence?.();
+        writeSquareDoc(squarePath, nextDoc);
+        persistence?.finalize();
+        return committed;
+    }
+    catch (error) {
+        try {
+            persistence?.rollback();
+        }
+        catch { }
+        throw error;
+    }
+}
+/** The one mutation pipeline shared by package and CLI adapters. */
+export async function execute(squarePath, intent) {
+    const committed = await withSquareLock(squarePath, () => {
+        const doc = loadSquare(squarePath);
+        return commitPlan(squarePath, doc, plan(doc, intent));
+    });
+    for (const act of committed.acts) {
+        if (act.kind === 'say')
+            await dispatchActNotifications(squarePath, act);
+    }
+    return committed;
+}
+/** Application-owned artifact creation; adapters provide validated options and stdin text only. */
+export async function createSquare(squarePath, options, snippet) {
+    await withSquareLock(squarePath, () => {
+        if (fs.existsSync(squarePath) && !options.force) {
+            throw new SquareError('conflict', `Refusing to overwrite existing square: ${squarePath}\nPass -f to overwrite.`);
+        }
+        const temporary = path.join(path.dirname(squarePath), `.${path.basename(squarePath)}.${process.pid}.${Date.now()}.tmp`);
+        fs.mkdirSync(path.dirname(squarePath), { recursive: true });
+        fs.writeFileSync(temporary, renderSquare(options, snippet));
+        fs.renameSync(temporary, squarePath);
+        saveRuntimeSidecar(squarePath, emptyRuntimeState(0));
+    });
+}
+/** Keep artifact repair planning and dependent quarantine persistence inside the application boundary. */
+export async function repairSquare(squarePath) {
+    const result = await withSquareLock(squarePath, () => {
+        let text;
+        try {
+            text = fs.readFileSync(squarePath, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                throw new SquareError('not_found', `square file not found: ${squarePath}`);
+            throw error;
+        }
+        const repair = planRepair(text);
+        if (repair.diagnosis.unfixable || repair.repaired === undefined)
+            return { repair };
+        // Repair changes Markdown only. Keep the sidecar's runtime metadata and
+        // merge history boundaries so a doctor run cannot erase delivery state or
+        // reuse a stable activity index.
+        const sidecarRuntime = loadRuntimeSidecar(squarePath, repair.repaired.doc.runtime);
+        const indexesPreserved = repair.diagnosis.acts.every(({ act }, index) => repair.repaired.doc.acts[index]?.index === act.index);
+        if (indexesPreserved) {
+            repair.repaired.doc.runtime = mergeRuntimeState(repair.repaired.doc.runtime, sidecarRuntime);
+        }
+        else {
+            repair.repaired.doc.runtime = emptyRuntimeState(Math.max(repair.repaired.doc.runtime.nextActIndex, sidecarRuntime.nextActIndex));
+            repair.repaired.actions.push({ message: 'reset runtime delivery metadata because act indexes changed' });
+        }
+        const quarantinePath = squarePath.replace(/\.md$/, '') + '.quarantine.md';
+        const intent = {
+            type: 'repair',
+            doc: repair.repaired.doc,
+            ...(repair.repaired.quarantinedBlocks.length === 0
+                ? {}
+                : { quarantine: { path: quarantinePath, blocks: repair.repaired.quarantinedBlocks } }),
+        };
+        commitPlan(squarePath, repair.repaired.doc, plan(repair.repaired.doc, intent));
+        return { repair };
+    });
+    return result.repair;
+}

package/dist/square-core.js

@@ -26,14 +26,6 @@ function touchParticipant(byKey, ordered, actor) {
     ordered.push(created);
     return created;
 }
-export function isWarm(lastSeen, now, threshold) {
-    if (lastSeen === undefined)
-        return false;
-    if (!Number.isFinite(lastSeen) || !Number.isFinite(now) || !Number.isFinite(threshold) || threshold <= 0)
-        return false;
-    const delta = now - lastSeen;
-    return delta >= 0 && delta <= threshold;
-}
 function pushThrottleAt(state, at) {
     if (typeof at === 'number' && Number.isFinite(at))
         state.throttleActivityAts.push(at);
@@ -59,7 +51,7 @@ function bellRecentAt(state, actor, at, windowMs) {
     }
     return latest;
 }
-export function fold(acts, options = {}) {
+export function fold(acts) {
     const ordered = [];
     const byKey = new Map();
     const hold = { active: false };
@@ -168,12 +160,12 @@ export function validate(state, act, options = {}) {
             return { ok: true };
     }
 }
-export function perceive(state, act, viewer, options = {}) {
+export function perceive(state, act, viewer) {
     void state;
     if (act.kind !== 'say')
         return 'full';
     const actor = act.actor;
-    if ((options.includeActor ?? true) && sameName(actor, viewer))
+    if (sameName(actor, viewer))
         return 'full';
     if (act.reach === undefined || act.reach === 'bell')
         return 'full';