@astrosheep/square 0.3.4 → 0.3.6

package/dist/delivery-health.js

@@ -1,249 +1,143 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { loadSquare, saveRuntimeSidecar } from './artifact.js';
-import { SquareError, sameName } from './model.js';
-import { planActNotifications } from './notifications.js';
+import { loadSquare } from './artifact.js';
+import { deriveDeliveryModel } from './delivery.js';
+import { readNotificationFailures } from './notification-failures.js';
+import { isCurrentlyJoined } from './runtime.js';
+import { sameName } from './model.js';
 import { formatDuration } from './time.js';
-import { isCurrentlyJoined, isDeliveryDelivered, lastJoinAt, recordDeliveredDelivery, resolveRosterName, rosterNames, } from './runtime.js';
-const DEFAULT_STALE_MS = 60_000;
-/** Only acts inside this lookback can prove "hooks are dead right now". Older = historical debt. */
-const DEFAULT_LOOKBACK_MS = 60 * 60 * 1000;
-function parsePositiveIntegerEnv(name, fallback) {
-    const raw = process.env[name];
+const STALE_MS = 60_000;
+const LOOKBACK_MS = 60 * 60 * 1000;
+function positive(name, fallback, env) {
+    const raw = 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.`);
-    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0)
+        throw new Error(`Invalid ${name}: expected a positive integer.`);
     return value;
 }
-/** How long a mention/bell may remain undelivered before harness liveness is suspect. */
-export function deliveryStaleMs() {
-    return parsePositiveIntegerEnv('SQUARE_DELIVERY_STALE_MS', DEFAULT_STALE_MS);
-}
-/** How far back liveness scans look. Older unreceipted mentions are backlog, not hook-death. */
-export function deliveryLookbackMs() {
-    return parsePositiveIntegerEnv('SQUARE_DELIVERY_LOOKBACK_MS', DEFAULT_LOOKBACK_MS);
-}
-function baselinePath(env = process.env) {
-    return env.SQUARE_DELIVERY_BASELINE || path.join(os.homedir(), '.square', 'delivery-baseline.json');
-}
-function readBaselines(env = process.env) {
-    const file = baselinePath(env);
-    if (!fs.existsSync(file))
-        return {};
-    try {
-        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
-        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
-            return {};
-        return parsed;
-    }
-    catch {
-        return {};
-    }
-}
-export function recordBacklogBaseline(squarePath, backlogCount, env = process.env, at = Date.now()) {
-    const file = baselinePath(env);
-    const data = readBaselines(env);
-    data[path.resolve(squarePath)] = { backlogCount, at };
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    const temp = `${file}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(temp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
-    fs.renameSync(temp, file);
+export function deliveryStaleMs(env = process.env) {
+    return positive('SQUARE_DELIVERY_STALE_MS', STALE_MS, env);
 }
-export function previousBacklogCount(squarePath, env = process.env) {
-    return readBaselines(env)[path.resolve(squarePath)]?.backlogCount;
+export function deliveryLookbackMs(env = process.env) {
+    return positive('SQUARE_DELIVERY_LOOKBACK_MS', LOOKBACK_MS, env);
 }
-function isReceipted(_squarePath, doc, recipient, actIndex, _env) {
-    // This sidecar record is the only delivery authority. A machine-local
-    // presentation cache may suppress duplicate hook text, but never clears debt.
-    return isDeliveryDelivered(doc, recipient, actIndex);
+function actedAfter(doc, recipient, actIndex) {
+    return doc.acts.some((act) => act.actor !== undefined && sameName(act.actor, recipient) && act.index > actIndex);
 }
-function actedAfterMention(doc, recipient, mentionAt, mentionIndex) {
-    return doc.acts.some((act) => act.actor !== undefined &&
-        sameName(act.actor, recipient) &&
-        (act.at > mentionAt || act.index > mentionIndex));
-}
-function collectUnreceiptedMentions(squarePath, doc, now, opts = {}) {
-    const env = opts.env ?? process.env;
-    const pending = [];
-    for (const act of doc.acts) {
-        if (act.kind !== 'say')
-            continue;
-        const item = { act, index: act.index };
-        for (const planned of planActNotifications(doc, item)) {
-            if (planned.via !== 'mention' && planned.via !== 'bell')
-                continue;
-            const recipient = resolveRosterName(doc, planned.recipient) ?? planned.recipient;
-            if (opts.onlyJoined && !isCurrentlyJoined(doc.acts, recipient))
-                continue;
-            if (isReceipted(squarePath, doc, recipient, act.index, env))
-                continue;
-            pending.push({
-                squarePath,
-                recipient,
-                actIndex: act.index,
-                actor: act.actor,
-                at: act.at,
-                ageMs: now - act.at,
-                via: planned.via,
-                actedAfterWithoutDelivery: actedAfterMention(doc, recipient, act.at, act.index),
-            });
-        }
-    }
-    return pending;
+function pending(squarePath, now) {
+    const doc = loadSquare(squarePath);
+    const model = deriveDeliveryModel(doc);
+    const recipients = [...new Set(doc.acts.filter((act) => act.kind === 'join').map((act) => act.actor))]
+        .filter((name) => isCurrentlyJoined(doc.acts, name));
+    return recipients.flatMap((recipient) => model.pendingFor(recipient).map((note) => ({
+        squarePath,
+        recipient: note.recipient,
+        actIndex: note.item.index,
+        actor: note.item.actor,
+        at: note.item.at,
+        ageMs: now - note.item.at,
+        route: note.route,
+        actedAfterWithoutDelivery: actedAfter(doc, note.recipient, note.item.index),
+    })));
 }
-/**
- * Partition unreceipted mention/bell traffic.
- * Liveness failure requires: past stale, inside lookback, currently joined, mention after last join.
- */
 export function partitionPendingDeliveries(squarePath, opts = {}) {
     const now = opts.now ?? Date.now();
     const staleMs = opts.staleMs ?? deliveryStaleMs();
     const lookbackMs = Math.max(opts.lookbackMs ?? deliveryLookbackMs(), staleMs);
-    const doc = opts.doc ?? loadSquare(squarePath);
     const recent = [];
     const historical = [];
-    // Include not-joined for historical/reconcile; liveness only uses joined.
-    for (const item of collectUnreceiptedMentions(squarePath, doc, now, {
-        onlyJoined: false,
-        env: opts.env,
-    })) {
-        const joined = isCurrentlyJoined(doc.acts, item.recipient);
-        const joinAt = lastJoinAt(doc.acts, item.recipient);
-        const afterJoin = joinAt === undefined || item.at >= joinAt;
-        const inLookback = item.ageMs <= lookbackMs;
-        const pastStale = item.ageMs >= staleMs;
-        if (joined && pastStale && inLookback && afterJoin) {
+    for (const item of pending(squarePath, now)) {
+        if (item.ageMs >= staleMs && item.ageMs <= lookbackMs)
             recent.push(item);
-            continue;
-        }
-        // Still in grace window and would otherwise be live → ignore (not historical yet).
-        if (joined && !pastStale && inLookback && afterJoin)
-            continue;
-        historical.push(item);
+        else if (item.ageMs >= staleMs)
+            historical.push(item);
     }
     return { recent, historical };
 }
-/** Recent stale only — the liveness signal. */
-export function findStalePendingMentions(squarePath, opts = {}) {
-    return partitionPendingDeliveries(squarePath, opts).recent;
-}
-function summarizeByRecipient(items) {
-    const byRecipient = new Map();
-    for (const item of items) {
-        const list = byRecipient.get(item.recipient) ?? [];
-        list.push(item);
-        byRecipient.set(item.recipient, list);
-    }
-    const lines = [];
-    for (const [recipient, group] of byRecipient) {
-        const oldest = group.reduce((a, b) => (a.at <= b.at ? a : b));
-        const ageSec = Math.max(1, Math.round(oldest.ageMs / 1000));
-        const adapter = group.some((item) => item.actedAfterWithoutDelivery);
-        lines.push(adapter
-            ? `  · @${recipient}: ${group.length} pending — acted after the mention, but delivery was not acknowledged (oldest act_${oldest.actIndex}, ~${ageSec}s)`
-            : `  · @${recipient}: ${group.length} pending (oldest act_${oldest.actIndex} from @${oldest.actor}, ~${ageSec}s)`);
-    }
-    return lines;
+function byRecipient(items) {
+    const groups = new Map();
+    for (const item of items)
+        groups.set(item.recipient, [...(groups.get(item.recipient) ?? []), item]);
+    return [...groups].map(([recipient, notes]) => {
+        const oldest = notes.reduce((first, item) => item.at < first.at ? item : first);
+        const adapterFault = notes.some((item) => item.actedAfterWithoutDelivery);
+        return adapterFault
+            ? `  · @${recipient}: ${notes.length} pending; they acted after it without a receipt (act_${oldest.actIndex})`
+            : `  · @${recipient}: ${notes.length} pending (oldest act_${oldest.actIndex} from @${oldest.actor})`;
+    });
 }
 export function formatStaleDeliveryWarnings(recent, historical = [], opts = {}) {
-    const lines = [];
+    const out = [];
     if (recent.length > 0) {
         const adapterFaults = recent.filter((item) => item.actedAfterWithoutDelivery);
-        if (adapterFaults.length > 0) {
-            lines.push(`⚠ ${adapterFaults.length} recent mention(s): the recipient acted after the mention, but delivery was not acknowledged.`);
-            lines.push('  This points to an adapter failure, not participant behavior.');
-            lines.push('  » square harness doctor');
-        }
-        const other = recent.filter((item) => !item.actedAfterWithoutDelivery);
-        if (other.length > 0) {
-            lines.push(`⚠ ${other.length} recent mention or bell notification(s) were not acknowledged inside the delivery window.`);
-            lines.push('  The installed hook or extension may not be consuming notifications.');
-        }
-        lines.push(...summarizeByRecipient(recent));
-        if (adapterFaults.length === 0)
-            lines.push('  » square harness doctor');
+        out.push(adapterFaults.length > 0
+            ? `✕ ${adapterFaults.length} pending notification(s) point to an adapter/pull dead path.`
+            : `✕ ${recent.length} recent notification(s) have no delivered receipt.`);
+        out.push(...byRecipient(recent));
     }
     if (historical.length > 0) {
-        lines.push(`○ ${historical.length} historical or pre-join mention(s) remain unacknowledged — backlog, not a current delivery failure.`);
-        const counts = new Map();
-        for (const item of historical) {
-            counts.set(item.recipient, (counts.get(item.recipient) ?? 0) + 1);
-        }
-        lines.push(`  · ${[...counts.entries()].map(([name, n]) => `@${name}:${n}`).join(', ')}`);
+        out.push(`○ ${historical.length} older pending notification(s) remain as historical backlog.`);
+        out.push(...byRecipient(historical));
         if (opts.previousBacklog !== undefined) {
             const delta = historical.length - opts.previousBacklog;
-            if (delta > 0) {
-                lines.push(`  ⚠ backlog grew by ${delta} since last doctor (something aged out of lookback unnoticed).`);
-            }
-            else if (delta < 0) {
-                lines.push(`  · backlog shrank by ${-delta} since last doctor.`);
-            }
-            else {
-                lines.push('  · backlog unchanged since last doctor.');
-            }
+            out.push(delta === 0 ? '  · backlog unchanged since last doctor.' : delta > 0 ? `  · backlog grew by ${delta} since last doctor.` : `  · backlog shrank by ${-delta} since last doctor.`);
         }
     }
-    else if (opts.previousBacklog !== undefined && opts.previousBacklog > 0) {
-        lines.push(`○ backlog cleared (was ${opts.previousBacklog}).`);
-    }
-    return lines;
+    else if ((opts.previousBacklog ?? 0) > 0)
+        out.push(`○ backlog cleared (was ${opts.previousBacklog}).`);
+    return out;
 }
-export function doctorDeliveryHealth(squarePath, now = Date.now(), env = process.env) {
+function baselineFile(env) {
+    return env.SQUARE_DELIVERY_BASELINE ?? path.join(os.homedir(), '.square', 'delivery-baseline.json');
+}
+function baseline(squarePath, env) {
     try {
-        const doc = loadSquare(squarePath);
-        const { recent, historical } = partitionPendingDeliveries(squarePath, { now, doc, env });
-        const previous = previousBacklogCount(squarePath, env);
-        const lines = [
-            `· stale after ${formatDuration(deliveryStaleMs())} · scan window ${formatDuration(deliveryLookbackMs())}`,
-            `· participants ${rosterNames(doc).join(', ') || '(none)'}`,
-        ];
-        if (recent.length === 0 && historical.length === 0) {
-            lines.push('✓ no stale undelivered mentions or bells');
-        }
-        else {
-            if (recent.length === 0) {
-                lines.push('✓ no current delivery failures inside the scan window');
-            }
-            lines.push(...formatStaleDeliveryWarnings(recent, historical, { previousBacklog: previous }).map((line) => line.startsWith('⚠ ') ? line.replace(/^⚠ /, '✕ ') : line));
-        }
-        recordBacklogBaseline(squarePath, historical.length, env, now);
-        return lines;
+        return JSON.parse(fs.readFileSync(baselineFile(env), 'utf8'))[path.resolve(squarePath)]?.backlogCount;
     }
-    catch (error) {
-        return [`✕ delivery health unreadable: ${error instanceof Error ? error.message : String(error)}`];
+    catch {
+        return undefined;
     }
 }
-/** Act-path only screams for recent liveness failures, not historical backlog. */
-export function hasStalePendingForAny(squarePath, now = Date.now()) {
-    return findStalePendingMentions(squarePath, { now }).length > 0;
-}
-export function notificationMessageId(squarePath, actIndex) {
-    return `square:${squarePath}#act_${actIndex}`;
-}
-/**
- * Write delivered-class receipts with reason=reconciled for backlog items.
- * Does not touch recent liveness failures.
- */
-export function reconcileDeliveryBacklog(squarePath, opts = {}) {
-    const now = opts.now ?? Date.now();
-    const doc = loadSquare(squarePath);
-    const { recent, historical } = partitionPendingDeliveries(squarePath, {
-        now,
-        doc,
-        lookbackMs: opts.lookbackMs,
-        staleMs: opts.staleMs,
-    });
-    const actor = opts.actor ?? 'doctor --fix reconcile-backlog';
-    let reconciled = 0;
-    for (const item of historical) {
-        if (recordDeliveredDelivery(doc, item.recipient, item.actIndex, { at: now, reason: 'reconciled', actor }))
-            reconciled += 1;
+function writeBaseline(squarePath, backlogCount, env, at) {
+    const file = baselineFile(env);
+    let rows = {};
+    try {
+        rows = JSON.parse(fs.readFileSync(file, 'utf8'));
     }
-    if (reconciled > 0)
-        saveRuntimeSidecar(squarePath, doc.runtime);
-    return { reconciled, skippedRecent: recent.length, items: historical };
+    catch { }
+    rows[path.resolve(squarePath)] = { backlogCount, at };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(rows, null, 2)}\n`, { mode: 0o600 });
+}
+function formatFailures(squarePath, recent, env) {
+    const failures = readNotificationFailures(squarePath, env);
+    if (failures.length === 0)
+        return [];
+    const pendingKeys = new Set(recent.map((item) => `${item.recipient}\0${item.actIndex}`));
+    const current = failures.filter((item) => item.recipient !== undefined && pendingKeys.has(`${item.recipient}\0${item.actIndex}`));
+    const rows = current.length > 0 ? current : failures;
+    const historical = current.length === 0;
+    const latest = rows.at(-1);
+    const diagnostic = latest.diagnostic;
+    return [
+        historical ? `○ ${rows.length} historical notification failure(s) retained: ${latest.message}` : `✕ ${rows.length} notification attempt(s) failed: ${latest.message}; receipt remains pending.`,
+        ...(diagnostic?.passwordPresent === false ? ['  · PASEO_PASSWORD absent; pass PASEO_PASSWORD to the Codex process.'] : []),
+        `  · ${notificationFailuresPathForDisplay(squarePath, env)}`,
+    ];
+}
+function notificationFailuresPathForDisplay(squarePath, env) {
+    return env.SQUARE_NOTIFICATION_FAILURES ?? path.join(path.dirname(squarePath), 'notification-failures.ndjsonl');
+}
+export function doctorDeliveryHealth(squarePath, now = Date.now(), env = process.env) {
+    const { recent, historical } = partitionPendingDeliveries(squarePath, { now, staleMs: deliveryStaleMs(env), lookbackMs: deliveryLookbackMs(env) });
+    const prior = baseline(squarePath, env);
+    writeBaseline(squarePath, historical.length, env, now);
+    return [
+        `· stale after ${formatDuration(deliveryStaleMs(env))} · scan window ${formatDuration(deliveryLookbackMs(env))}`,
+        ...(recent.length === 0 && historical.length === 0 ? ['✓ no stale undelivered notifications'] : formatStaleDeliveryWarnings(recent, historical, { previousBacklog: prior })),
+        ...formatFailures(squarePath, recent, env),
+    ];
 }

package/dist/delivery.js

@@ -1,5 +1,37 @@
 import { findParticipantName, sameName, } from './model.js';
-import { extractMentions, isDeliveryDelivered, lastJoinIndex, matchesMentionTarget, rosterNames } from './runtime.js';
+import { actId, extractMentions, isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
+export function notificationMessageId(squarePath, actIndex) {
+    return `square:${squarePath}#act_${actIndex}`;
+}
+export function isPendingNotification(notification) {
+    return notification.route !== 'broadcast';
+}
+function canonicalRecipient(doc, name) {
+    return resolveRosterName(doc, name) ?? name;
+}
+/** Delivery receipts are the only durable acknowledgement of directed attention. */
+export function deliveryReceipt(doc, name, actOrIndex) {
+    return deliveryReceiptFromRuntime(doc.runtime, canonicalRecipient(doc, name), actOrIndex);
+}
+export function deliveryReceiptFromRuntime(runtime, recipient, actOrIndex) {
+    return runtime.deliveryReceipts[recipient]?.[actId(actOrIndex)];
+}
+export function isDeliveryDelivered(doc, name, actOrIndex) {
+    return deliveryReceipt(doc, name, actOrIndex)?.status === 'delivered';
+}
+export function recordDeliveredDelivery(doc, name, actOrIndex, receipt) {
+    return recordDeliveredRuntime(doc.runtime, canonicalRecipient(doc, name), actOrIndex, receipt);
+}
+export function recordDeliveredRuntime(runtime, recipient, actOrIndex, receipt) {
+    const id = actId(actOrIndex);
+    if (deliveryReceiptFromRuntime(runtime, recipient, actOrIndex)?.status === 'delivered')
+        return false;
+    (runtime.deliveryReceipts[recipient] ??= {})[id] = { status: 'delivered', ...receipt };
+    return true;
+}
+export function markDeliveredDelivery(doc, name, actOrIndex, at = Date.now()) {
+    return recordDeliveredDelivery(doc, name, actOrIndex, { at });
+}
 function uniqueKnownMentions(body, roster) {
     const recipients = [];
     for (const mention of extractMentions(body)) {
@@ -15,30 +47,30 @@ function uniqueKnownMentions(body, roster) {
  * All consumers share these targets instead of reinterpreting artifact text or cursor state.
  */
 export function deriveDeliveryModel(doc) {
-    const roster = rosterNames(doc);
+    const roster = rosterNames(doc).filter((name) => isCurrentlyJoined(doc.acts, name));
     let pendingByRecipient;
     function plan(item) {
-        if (item.act.kind !== 'say')
+        if (item.kind !== 'say')
             return [];
         const sayItem = item;
-        const actor = sayItem.act.actor;
-        if (sayItem.act.reach === 'bell') {
+        const actor = sayItem.actor;
+        if (sayItem.reach === 'bell') {
             return roster
                 .filter((recipient) => !sameName(recipient, actor))
-                .map((recipient) => ({ item: sayItem, recipient, via: 'bell' }));
+                .map((recipient) => ({ item: sayItem, recipient, route: 'bell' }));
         }
-        if (sayItem.act.reach !== undefined) {
-            const recipient = findParticipantName(roster, sayItem.act.reach.beside);
+        if (sayItem.reach !== undefined) {
+            const recipient = findParticipantName(roster, sayItem.reach.beside);
             return recipient === undefined || sameName(recipient, actor)
                 ? []
-                : [{ item: sayItem, recipient, via: 'mention' }];
+                : [{ item: sayItem, recipient, route: 'beside' }];
         }
-        const mentions = uniqueKnownMentions(sayItem.act.body, roster).filter((recipient) => !sameName(recipient, actor));
+        const mentions = uniqueKnownMentions(sayItem.body, roster).filter((recipient) => !sameName(recipient, actor));
         const recipients = mentions.length > 0
             ? mentions
             : roster.filter((recipient) => !sameName(recipient, actor));
-        const via = mentions.length > 0 ? 'mention' : 'broadcast';
-        return recipients.map((recipient) => ({ item: sayItem, recipient, via }));
+        const route = mentions.length > 0 ? 'mention' : 'broadcast';
+        return recipients.map((recipient) => ({ item: sayItem, recipient, route }));
     }
     function pendingFor(requestedRecipient) {
         const recipient = findParticipantName(roster, requestedRecipient);
@@ -54,15 +86,15 @@ export function deriveDeliveryModel(doc) {
                 // avoids allocating one planned notification per participant per activity.
                 if (act.reach === undefined && extractMentions(act.body).length === 0)
                     continue;
-                for (const planned of plan({ act, index: act.index })) {
-                    if (planned.via === 'broadcast')
+                for (const planned of plan(act)) {
+                    if (planned.route === 'broadcast')
                         continue;
                     const joinedAt = joinedAfter.get(planned.recipient);
                     if (joinedAt === undefined || act.index <= joinedAt)
                         continue;
                     if (isDeliveryDelivered(doc, planned.recipient, act.index))
                         continue;
-                    pendingByRecipient.get(planned.recipient)?.push({ ...planned, via: planned.via });
+                    pendingByRecipient.get(planned.recipient)?.push({ ...planned, route: planned.route });
                 }
             }
         }
@@ -73,21 +105,39 @@ export function deriveDeliveryModel(doc) {
 export function planActNotifications(doc, item) {
     return deriveDeliveryModel(doc).plan(item);
 }
+/** Mark only the directed notifications selected by the canonical pending projection. */
+export function markDeliveredNotifications(doc, recipient, delivered, at = Date.now()) {
+    const deliveredIndexes = new Set(delivered.map((item) => item.index));
+    let changed = false;
+    for (const notification of deriveDeliveryModel(doc).pendingFor(recipient)) {
+        if (!deliveredIndexes.has(notification.item.index))
+            continue;
+        changed = recordDeliveredDelivery(doc, notification.recipient, notification.item.index, { at }) || changed;
+    }
+    return changed;
+}
 /** Canonical say-activity filter shared by catch selection and hook ownership. */
 export function matchesCatchFilter(activity, filter) {
-    if (activity.bell)
+    if (activity.reach === 'bell')
         return true;
     if (filter.participants !== undefined &&
         !filter.participants.some((participant) => sameName(participant, activity.actor))) {
         return false;
     }
-    return filter.mention === undefined || matchesMentionTarget({ body: activity.body }, filter.mention);
+    return filter.mention === undefined || matchesMentionTarget(activity, filter.mention);
 }
 /** True only when the live catch's own filters would deliver this notification. */
 export function leaseOwnsNotification(lease, notification) {
+    const recipient = notification.recipient;
+    if (notification.route === 'beside' && recipient === undefined)
+        return false;
     return matchesCatchFilter({
         actor: notification.actor,
         body: notification.body,
-        bell: notification.via === 'bell',
+        reach: notification.route === 'bell'
+            ? 'bell'
+            : notification.route === 'beside'
+                ? { beside: recipient }
+                : undefined,
     }, lease.filter ?? {});
 }

package/dist/doctor.js

@@ -4,17 +4,19 @@ export function planRepair(text) {
     if (diagnosis.unfixable)
         return { diagnosis };
     const actions = [];
-    const acts = diagnosis.acts.map(({ act }, index) => ({ ...act, index }));
-    if (diagnosis.acts.some(({ act }, index) => act.index !== index)) {
+    const diagnosedFirstIndex = diagnosis.acts[0]?.act.index ?? 0;
+    const preservesStableIndexes = diagnosis.acts.every(({ act }, index) => act.index === diagnosedFirstIndex + index);
+    const acts = diagnosis.acts.map(({ act }, index) => ({
+        ...act,
+        index: preservesStableIndexes ? act.index : index,
+    }));
+    if (!preservesStableIndexes) {
         actions.push({ message: 'renumbered act indexes to be contiguous' });
     }
     if (diagnosis.quarantined.length > 0) {
         actions.push({ message: `quarantined ${diagnosis.quarantined.length} unparseable act block(s)` });
     }
-    if (diagnosis.legacyParticipants.length > 0) {
-        actions.push({ message: 'dropped frontmatter participants; roster now derives from join/done acts' });
-    }
-    const nextActIndex = acts.length;
+    const nextActIndex = acts.length > 0 ? acts[acts.length - 1].index + 1 : 0;
     const doc = {
         hardCap: diagnosis.hardCap,
         throttlePerMinute: diagnosis.throttlePerMinute,
@@ -24,9 +26,8 @@ export function planRepair(text) {
         runtime: {
             version: 2,
             nextActIndex,
-            firstActIndex: acts.length > 0 ? (acts[0].index ?? 0) : 0,
             cursors: {},
-            mentionReceipts: {},
+            deliveryReceipts: {},
             leases: {},
         },
     };

package/dist/harness-claude.js

@@ -0,0 +1,68 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SQUARE_IDENTITY } from './identity.js';
+import { stageReplacement } from './harness-stage.js';
+export const CLAUDE_PLUGIN_ID = SQUARE_IDENTITY.pluginId;
+export const CLAUDE_MARKETPLACE_NAME = SQUARE_IDENTITY.marketplaceName;
+export function claudeMarketplaceRoot(homeDir) {
+    return path.join(homeDir, '.square', 'claude', 'marketplaces', CLAUDE_MARKETPLACE_NAME);
+}
+function runClaude(homeDir, args) {
+    const result = spawnSync(process.env.SQUARE_CLAUDE_BIN || 'claude', args, {
+        encoding: 'utf8', env: { ...process.env, HOME: homeDir, CLAUDE_CONFIG_DIR: path.join(homeDir, '.claude') }, timeout: 30_000,
+    });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout || '', stderr: result.stderr || '' };
+}
+function requireSuccess(result, operation, allowMissing = false) {
+    if (result.status === 0 || (allowMissing && /not configured|not installed|not found/i.test(result.stderr)))
+        return;
+    throw new Error(`Claude ${operation} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`);
+}
+function writeJson(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+export async function installClaudePlugin(homeDir, run = runClaude) {
+    const marketplaceRoot = claudeMarketplaceRoot(homeDir);
+    const staged = stageReplacement(marketplaceRoot, (stage) => {
+        const plugin = path.join(stage, 'plugins', SQUARE_IDENTITY.pluginName);
+        fs.cpSync(fileURLToPath(new URL('../skills/square/', import.meta.url)), plugin, { recursive: true });
+        writeJson(path.join(stage, '.claude-plugin', 'marketplace.json'), {
+            name: CLAUDE_MARKETPLACE_NAME,
+            plugins: [{ name: SQUARE_IDENTITY.pluginName, source: './plugins/square' }],
+        });
+    });
+    try {
+        const add = run(homeDir, ['plugin', 'marketplace', 'add', marketplaceRoot]);
+        requireSuccess(add, 'marketplace install', true);
+        requireSuccess(run(homeDir, ['plugin', 'install', CLAUDE_PLUGIN_ID]), 'plugin install');
+        requireSuccess(run(homeDir, ['plugin', 'update', CLAUDE_PLUGIN_ID]), 'plugin update');
+        staged.finalize();
+    }
+    catch (error) {
+        staged.rollback();
+        throw error;
+    }
+    return { marketplaceRoot, pluginRoot: path.join(marketplaceRoot, 'plugins', SQUARE_IDENTITY.pluginName) };
+}
+export async function uninstallClaudePlugin(homeDir, run = runClaude) {
+    const root = claudeMarketplaceRoot(homeDir);
+    requireSuccess(run(homeDir, ['plugin', 'remove', CLAUDE_PLUGIN_ID]), 'plugin removal', true);
+    requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', CLAUDE_MARKETPLACE_NAME]), 'marketplace removal', true);
+    fs.rmSync(root, { recursive: true, force: true });
+    return { paths: [root], notes: [] };
+}
+export async function doctorClaudePlugin(homeDir, run = runClaude) {
+    const root = claudeMarketplaceRoot(homeDir);
+    const bundle = path.join(root, 'plugins', SQUARE_IDENTITY.pluginName);
+    const listed = run(homeDir, ['plugin', 'list', '--json']);
+    const installed = listed.status === 0 && listed.stdout.includes(CLAUDE_PLUGIN_ID);
+    return [
+        fs.existsSync(bundle) ? `✓ Square Claude plugin bundle ${root}` : `○ Square Claude plugin bundle missing ${root}`,
+        installed ? `✓ ${CLAUDE_PLUGIN_ID} installed` : `○ ${CLAUDE_PLUGIN_ID} unavailable`,
+    ];
+}