@astrosheep/square 0.3.10 → 0.3.12

package/dist/delivery-health.js

@@ -1,143 +1,63 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
 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 { deriveDeliveryModel, } from './delivery.js';
+import { formatActivityId } from './square-core.js';
 import { formatDuration } from './time.js';
-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(raw);
-    if (!Number.isInteger(value) || value <= 0)
-        throw new Error(`Invalid ${name}: expected a positive integer.`);
-    return value;
-}
-export function deliveryStaleMs(env = process.env) {
-    return positive('SQUARE_DELIVERY_STALE_MS', STALE_MS, env);
-}
-export function deliveryLookbackMs(env = process.env) {
-    return positive('SQUARE_DELIVERY_LOOKBACK_MS', LOOKBACK_MS, env);
-}
-function actedAfter(doc, recipient, actIndex) {
-    return doc.acts.some((act) => act.actor !== undefined && sameName(act.actor, recipient) && act.index > actIndex);
-}
-function pending(squarePath, now) {
+import { joinedRecipients, wakeEvidence } from './wake-evidence.js';
+const DISPLAY_ORDER = [
+    'awaiting',
+    'wake-accepted',
+    'wake-unknown',
+    'presented-not-delivered',
+    'unreachable',
+];
+const ACTIONABLE = new Set(['wake-unknown', 'unreachable']);
+/** Purely classify current pending attention from the artifact and durable ledgers. */
+export function classifyDeliveryHealth(squarePath, opts) {
+    const now = opts.now ?? Date.now();
+    const env = opts.env ?? process.env;
     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),
-    })));
-}
-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 recent = [];
-    const historical = [];
-    for (const item of pending(squarePath, now)) {
-        if (item.ageMs >= staleMs && item.ageMs <= lookbackMs)
-            recent.push(item);
-        else if (item.ageMs >= staleMs)
-            historical.push(item);
-    }
-    return { recent, historical };
-}
-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 out = [];
-    if (recent.length > 0) {
-        const adapterFaults = recent.filter((item) => item.actedAfterWithoutDelivery);
-        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));
+    return joinedRecipients(doc).flatMap((recipient) => model.pendingFor(recipient).map((note) => {
+        const ageMs = Math.max(0, now - note.item.at);
+        const evidence = wakeEvidence(squarePath, note.recipient, note.item.index, now, env);
+        const kind = evidence.presented
+            ? 'presented-not-delivered'
+            : evidence.terminal?.outcome === 'accepted'
+                ? 'wake-accepted'
+                : evidence.terminal?.outcome === 'unknown'
+                    ? 'wake-unknown'
+                    : ageMs > opts.graceMs && evidence.attemptableRoutes.length === 0
+                        ? 'unreachable'
+                        : 'awaiting';
+        const attempt = evidence.terminal ?? evidence.attempts.at(-1);
+        return {
+            squarePath,
+            recipient: note.recipient,
+            actIndex: note.item.index,
+            actor: note.item.actor,
+            at: note.item.at,
+            ageMs,
+            route: note.route,
+            kind,
+            ...(attempt === undefined ? {} : { attempt }),
+        };
+    }));
+}
+function formatItem(item) {
+    const evidence = item.attempt?.signature === undefined ? '' : ` · ${item.attempt.signature}`;
+    return `  · ${formatActivityId(item.actIndex)} → @${item.recipient} from @${item.actor} · ${formatDuration(item.ageMs)}${evidence}`;
+}
+export function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
+    const items = classifyDeliveryHealth(squarePath, { graceMs, now, env });
+    if (items.length === 0)
+        return ['✓ no pending delivery attention'];
+    const out = [`· delivery attention · ${items.length} pending`];
+    for (const kind of DISPLAY_ORDER) {
+        const group = items.filter((item) => item.kind === kind);
+        if (group.length === 0)
+            continue;
+        out.push(`${ACTIONABLE.has(kind) ? '✕' : '○'} ${kind}: ${group.length}`);
+        out.push(...group.map(formatItem));
     }
-    if (historical.length > 0) {
-        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;
-            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 ?? 0) > 0)
-        out.push(`○ backlog cleared (was ${opts.previousBacklog}).`);
     return out;
 }
-function baselineFile(env) {
-    return env.SQUARE_DELIVERY_BASELINE ?? path.join(os.homedir(), '.square', 'delivery-baseline.json');
-}
-function baseline(squarePath, env) {
-    try {
-        return JSON.parse(fs.readFileSync(baselineFile(env), 'utf8'))[path.resolve(squarePath)]?.backlogCount;
-    }
-    catch {
-        return undefined;
-    }
-}
-function writeBaseline(squarePath, backlogCount, env, at) {
-    const file = baselineFile(env);
-    let rows = {};
-    try {
-        rows = JSON.parse(fs.readFileSync(file, 'utf8'));
-    }
-    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,10 +1,8 @@
 import { findParticipantName, sameName, } from './model.js';
-import { actId, extractMentions, isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.js';
+import { audienceOf, formatActivityId, resolveAudience } from './square-core.js';
+import { actId, 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';
+    return `square:${squarePath}#${formatActivityId(actIndex)}`;
 }
 function canonicalRecipient(doc, name) {
     return resolveRosterName(doc, name) ?? name;
@@ -32,16 +30,6 @@ export function recordDeliveredRuntime(runtime, recipient, actOrIndex, receipt)
 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)) {
-        const known = findParticipantName(roster, mention);
-        if (known !== undefined && !recipients.some((recipient) => sameName(recipient, known))) {
-            recipients.push(known);
-        }
-    }
-    return recipients;
-}
 /**
  * Derive delivery behavior once from the parsed Square document.
  * All consumers share these targets instead of reinterpreting artifact text or cursor state.
@@ -53,23 +41,9 @@ export function deriveDeliveryModel(doc) {
         if (item.kind !== 'say')
             return [];
         const sayItem = item;
-        const actor = sayItem.actor;
-        if (sayItem.reach === 'bell') {
-            return roster
-                .filter((recipient) => !sameName(recipient, actor))
-                .map((recipient) => ({ item: sayItem, recipient, route: 'bell' }));
-        }
-        if (sayItem.reach !== undefined) {
-            const recipient = findParticipantName(roster, sayItem.reach.beside);
-            return recipient === undefined || sameName(recipient, actor)
-                ? []
-                : [{ item: sayItem, recipient, route: 'beside' }];
-        }
-        const mentions = uniqueKnownMentions(sayItem.body, roster).filter((recipient) => !sameName(recipient, actor));
-        const recipients = mentions.length > 0
-            ? mentions
-            : roster.filter((recipient) => !sameName(recipient, actor));
-        const route = mentions.length > 0 ? 'mention' : 'broadcast';
+        const audience = audienceOf(sayItem);
+        const recipients = resolveAudience(audience, roster).filter((recipient) => !sameName(recipient, sayItem.actor));
+        const route = audience.kind === 'bell' ? 'bell' : 'mention';
         return recipients.map((recipient) => ({ item: sayItem, recipient, route }));
     }
     function pendingFor(requestedRecipient) {
@@ -82,19 +56,16 @@ export function deriveDeliveryModel(doc) {
             for (const act of doc.acts) {
                 if (act.kind !== 'say')
                     continue;
-                // Broadcasts can never be pending directed notifications. Skipping them here
-                // avoids allocating one planned notification per participant per activity.
-                if (act.reach === undefined && extractMentions(act.body).length === 0)
+                const audience = audienceOf(act);
+                if (audience.kind === 'mentions' && audience.names.length === 0)
                     continue;
                 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, route: planned.route });
+                    pendingByRecipient.get(planned.recipient)?.push(planned);
                 }
             }
         }
@@ -118,7 +89,7 @@ export function markDeliveredNotifications(doc, recipient, delivered, at = Date.
 }
 /** Canonical say-activity filter shared by catch selection and hook ownership. */
 export function matchesCatchFilter(activity, filter) {
-    if (activity.reach === 'bell')
+    if (audienceOf(activity).kind === 'bell')
         return true;
     if (filter.participants !== undefined &&
         !filter.participants.some((participant) => sameName(participant, activity.actor))) {
@@ -128,16 +99,9 @@ export function matchesCatchFilter(activity, filter) {
 }
 /** 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,
-        reach: notification.route === 'bell'
-            ? 'bell'
-            : notification.route === 'beside'
-                ? { beside: recipient }
-                : undefined,
+        ...(notification.route === 'bell' ? { reach: 'bell' } : {}),
     }, lease.filter ?? {});
 }

package/dist/file-lock.js

@@ -0,0 +1,112 @@
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+const lockWait = new Int32Array(new SharedArrayBuffer(4));
+const heldSyncLocks = new Set();
+function ownerState(lockPath) {
+    let pid;
+    try {
+        pid = Number.parseInt(fs.readFileSync(lockPath, 'utf8').split('\n')[0], 10);
+    }
+    catch {
+        return 'unknown';
+    }
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return 'unknown';
+    try {
+        process.kill(pid, 0);
+        return 'alive';
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? 'dead' : 'alive';
+    }
+}
+function createLock(lockPath) {
+    let fd;
+    try {
+        fd = fs.openSync(lockPath, 'wx', 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return undefined;
+        throw error;
+    }
+    const token = `${process.pid}\n${Date.now()}\n${randomUUID()}\n`;
+    try {
+        fs.writeFileSync(fd, token, 'utf8');
+        return token;
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch { }
+        throw error;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function reclaimLock(lockPath, staleMs) {
+    try {
+        const stale = Date.now() - fs.statSync(lockPath).mtimeMs > staleMs;
+        if (ownerState(lockPath) !== 'dead' && !stale)
+            return false;
+        fs.unlinkSync(lockPath);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'ENOENT';
+    }
+}
+function releaseLock(lockPath, token) {
+    try {
+        if (fs.readFileSync(lockPath, 'utf8') === token)
+            fs.unlinkSync(lockPath);
+    }
+    catch { }
+}
+function prepare(lockPath) {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+}
+export function withFileLockSync(lockPath, options, fn) {
+    if (heldSyncLocks.has(lockPath))
+        throw new Error(`Reentrant file lock: ${lockPath}`);
+    prepare(lockPath);
+    let token;
+    while (token === undefined) {
+        token = createLock(lockPath);
+        if (token !== undefined)
+            break;
+        if (reclaimLock(lockPath, options.staleMs))
+            continue;
+        Atomics.wait(lockWait, 0, 0, options.retryMs);
+    }
+    heldSyncLocks.add(lockPath);
+    try {
+        return fn();
+    }
+    finally {
+        heldSyncLocks.delete(lockPath);
+        releaseLock(lockPath, token);
+    }
+}
+export async function withFileLock(lockPath, options, fn) {
+    prepare(lockPath);
+    let token;
+    while (token === undefined) {
+        token = createLock(lockPath);
+        if (token !== undefined)
+            break;
+        if (reclaimLock(lockPath, options.staleMs))
+            continue;
+        await sleep(options.retryMs);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        releaseLock(lockPath, token);
+    }
+}

package/dist/harness-codex.js

@@ -12,7 +12,7 @@ const LEGACY_MARKETPLACES = ['astrosheep-square'];
 export function codexMarketplaceRoot(homeDir) {
     return path.join(homeDir, '.square', 'codex', 'marketplaces', CODEX_MARKETPLACE_NAME);
 }
-function configuredMarketplaceRoot(homeDir, configText) {
+function configuredMarketplaceRoot(homeDir, configText, codexHomeDir) {
     const lines = configText.split('\n');
     const header = `[marketplaces.${CODEX_MARKETPLACE_NAME}]`;
     const start = lines.findIndex((line) => line.trim() === header);
@@ -28,10 +28,10 @@ function configuredMarketplaceRoot(homeDir, configText) {
     if (!match)
         return undefined;
     const value = match[1].startsWith('"') ? JSON.parse(match[1]) : match[1].slice(1, -1);
-    return path.isAbsolute(value) ? value : path.resolve(codexHome(homeDir), value);
+    return path.isAbsolute(value) ? value : path.resolve(codexHome(homeDir, codexHomeDir), value);
 }
-function activeMarketplaceRoot(homeDir, configText) {
-    return configuredMarketplaceRoot(homeDir, configText) ?? codexMarketplaceRoot(homeDir);
+function activeMarketplaceRoot(homeDir, configText, codexHomeDir) {
+    return configuredMarketplaceRoot(homeDir, configText, codexHomeDir) ?? codexMarketplaceRoot(homeDir);
 }
 export function codexPluginRoot(homeDir, marketplaceRoot = codexMarketplaceRoot(homeDir)) {
     return path.join(marketplaceRoot, 'plugins', SQUARE_IDENTITY.pluginName);
@@ -39,12 +39,15 @@ export function codexPluginRoot(homeDir, marketplaceRoot = codexMarketplaceRoot(
 export function codexPluginHooksPath(homeDir, marketplaceRoot = codexMarketplaceRoot(homeDir)) {
     return path.join(codexPluginRoot(homeDir, marketplaceRoot), 'hooks', 'hooks.json');
 }
-function codexHome(homeDir) { return path.join(homeDir, '.codex'); }
-export function codexHomeHooksPath(homeDir) { return path.join(codexHome(homeDir), 'hooks.json'); }
-export function codexConfigPath(homeDir) { return path.join(codexHome(homeDir), 'config.toml'); }
-function runCodex(homeDir, args) {
+function codexHome(homeDir, codexHomeDir) {
+    const explicit = codexHomeDir?.trim();
+    return explicit ? path.resolve(explicit) : path.join(homeDir, '.codex');
+}
+export function codexHomeHooksPath(homeDir, codexHomeDir) { return path.join(codexHome(homeDir, codexHomeDir), 'hooks.json'); }
+export function codexConfigPath(homeDir, codexHomeDir) { return path.join(codexHome(homeDir, codexHomeDir), 'config.toml'); }
+function runCodex(homeDir, args, codexHomeDir) {
     const result = spawnSync(process.env.SQUARE_CODEX_BIN || 'codex', args, {
-        encoding: 'utf8', env: { ...process.env, HOME: homeDir, CODEX_HOME: codexHome(homeDir) }, timeout: 30_000,
+        encoding: 'utf8', env: { ...process.env, HOME: homeDir, CODEX_HOME: codexHome(homeDir, codexHomeDir) }, timeout: 30_000,
     });
     if (result.error)
         throw result.error;
@@ -77,10 +80,11 @@ function writeAtomic(file, text) {
     fs.writeFileSync(temp, text, { mode: 0o600 });
     fs.renameSync(temp, file);
 }
-export async function installCodexPlugin(homeDir, run = runCodex) {
-    const config = codexConfigPath(homeDir);
+export async function installCodexPlugin(homeDir, run = runCodex, codexHomeDir) {
+    const resolvedCodexHome = codexHome(homeDir, codexHomeDir);
+    const config = codexConfigPath(homeDir, resolvedCodexHome);
     const current = fs.existsSync(config) ? fs.readFileSync(config, 'utf8') : '';
-    const root = activeMarketplaceRoot(homeDir, current);
+    const root = activeMarketplaceRoot(homeDir, current, resolvedCodexHome);
     const staged = stageReplacement(root, (stage) => {
         const plugin = path.join(stage, 'plugins', SQUARE_IDENTITY.pluginName);
         fs.cpSync(fileURLToPath(new URL('../codex-plugin/', import.meta.url)), plugin, { recursive: true });
@@ -92,8 +96,8 @@ export async function installCodexPlugin(homeDir, run = runCodex) {
     const notes = [];
     try {
         writeAtomic(config, upsertTomlSectionKey(current, 'features', 'hooks', 'true'));
-        requireSuccess(run(homeDir, ['plugin', 'marketplace', 'add', root, '--json']), 'marketplace install', true);
-        const installed = run(homeDir, ['plugin', 'add', CODEX_PLUGIN_ID, '--json']);
+        requireSuccess(run(homeDir, ['plugin', 'marketplace', 'add', root, '--json'], resolvedCodexHome), 'marketplace install', true);
+        const installed = run(homeDir, ['plugin', 'add', CODEX_PLUGIN_ID, '--json'], resolvedCodexHome);
         requireSuccess(installed, 'plugin install');
         let installedPath;
         try {
@@ -108,8 +112,8 @@ export async function installCodexPlugin(homeDir, run = runCodex) {
             const pluginId = `${SQUARE_IDENTITY.pluginName}@${marketplace}`;
             if (!current.includes(`[marketplaces.${marketplace}]`) && !current.includes(`[plugins."${pluginId}"]`))
                 continue;
-            requireSuccess(run(homeDir, ['plugin', 'remove', pluginId, '--json']), 'legacy plugin removal', true);
-            requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', marketplace, '--json']), 'legacy marketplace removal', true);
+            requireSuccess(run(homeDir, ['plugin', 'remove', pluginId, '--json'], resolvedCodexHome), 'legacy plugin removal', true);
+            requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', marketplace, '--json'], resolvedCodexHome), 'legacy marketplace removal', true);
             notes.push(`retired ${pluginId}`);
         }
         staged.finalize();
@@ -120,25 +124,27 @@ export async function installCodexPlugin(homeDir, run = runCodex) {
         throw error;
     }
 }
-export async function uninstallCodexPlugin(homeDir, run = runCodex) {
-    const config = codexConfigPath(homeDir);
+export async function uninstallCodexPlugin(homeDir, run = runCodex, codexHomeDir) {
+    const resolvedCodexHome = codexHome(homeDir, codexHomeDir);
+    const config = codexConfigPath(homeDir, resolvedCodexHome);
     const current = fs.existsSync(config) ? fs.readFileSync(config, 'utf8') : '';
-    const root = activeMarketplaceRoot(homeDir, current);
-    requireSuccess(run(homeDir, ['plugin', 'remove', CODEX_PLUGIN_ID, '--json']), 'plugin removal', true);
-    requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', CODEX_MARKETPLACE_NAME, '--json']), 'marketplace removal', true);
+    const root = activeMarketplaceRoot(homeDir, current, resolvedCodexHome);
+    requireSuccess(run(homeDir, ['plugin', 'remove', CODEX_PLUGIN_ID, '--json'], resolvedCodexHome), 'plugin removal', true);
+    requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', CODEX_MARKETPLACE_NAME, '--json'], resolvedCodexHome), 'marketplace removal', true);
     for (const marketplace of LEGACY_MARKETPLACES) {
-        requireSuccess(run(homeDir, ['plugin', 'remove', `${SQUARE_IDENTITY.pluginName}@${marketplace}`, '--json']), 'legacy plugin removal', true);
-        requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', marketplace, '--json']), 'legacy marketplace removal', true);
+        requireSuccess(run(homeDir, ['plugin', 'remove', `${SQUARE_IDENTITY.pluginName}@${marketplace}`, '--json'], resolvedCodexHome), 'legacy plugin removal', true);
+        requireSuccess(run(homeDir, ['plugin', 'marketplace', 'remove', marketplace, '--json'], resolvedCodexHome), 'legacy marketplace removal', true);
     }
     fs.rmSync(root, { recursive: true, force: true });
-    fs.rmSync(codexHomeHooksPath(homeDir), { force: true });
-    return { paths: [root, codexConfigPath(homeDir), codexHomeHooksPath(homeDir)], notes: [] };
+    fs.rmSync(codexHomeHooksPath(homeDir, resolvedCodexHome), { force: true });
+    return { paths: [root, config, codexHomeHooksPath(homeDir, resolvedCodexHome)], notes: [] };
 }
-export async function doctorCodexPlugin(homeDir, run = runCodex) {
-    const config = codexConfigPath(homeDir);
+export async function doctorCodexPlugin(homeDir, run = runCodex, codexHomeDir) {
+    const resolvedCodexHome = codexHome(homeDir, codexHomeDir);
+    const config = codexConfigPath(homeDir, resolvedCodexHome);
     const current = fs.existsSync(config) ? fs.readFileSync(config, 'utf8') : '';
-    const root = activeMarketplaceRoot(homeDir, current);
-    const listed = run(homeDir, ['plugin', 'list', '--json']);
+    const root = activeMarketplaceRoot(homeDir, current, resolvedCodexHome);
+    const listed = run(homeDir, ['plugin', 'list', '--json'], resolvedCodexHome);
     return [
         /^hooks\s*=\s*true$/m.test(current) ? `✓ features.hooks=true in ${config}` : `○ features.hooks missing in ${config}`,
         fs.existsSync(codexPluginHooksPath(homeDir, root)) ? `✓ Square plugin hooks ${codexPluginHooksPath(homeDir, root)}` : `○ Square plugin bundle missing ${root}`,

package/dist/harness-links.js

@@ -122,6 +122,3 @@ export function opencodeExtensionLink(homeDir = os.homedir()) {
         kind: 'extension',
     };
 }
-export function piExtensionLink(homeDir = os.homedir()) {
-    return { source: path.join(packageRoot(), 'extensions', 'square-pi.js'), target: path.join(homeDir, '.pi', 'agent', 'extensions', 'square.js'), kind: 'extension' };
-}

package/dist/harness-pi.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SQUARE_IDENTITY } from './identity.js';
+export function piPackageSource() {
+    return `npm:${SQUARE_IDENTITY.packageName}@${SQUARE_IDENTITY.packageVersion}`;
+}
+export function piPackageRoot(homeDir) {
+    return path.join(homeDir, '.pi', 'agent', 'npm', 'node_modules', ...SQUARE_IDENTITY.packageName.split('/'));
+}
+function runPi(homeDir, args) {
+    const result = spawnSync(process.env.SQUARE_PI_BIN || 'pi', args, {
+        encoding: 'utf8',
+        env: { ...process.env, HOME: homeDir },
+        timeout: 30_000,
+    });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout || '', stderr: result.stderr || '' };
+}
+function requireSuccess(result, action) {
+    if (result.status === 0)
+        return;
+    throw new Error(`Pi ${action} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`);
+}
+export function installPiPackage(homeDir, run = runPi) {
+    requireSuccess(run(homeDir, ['install', piPackageSource()]), 'package install');
+    return [piPackageRoot(homeDir)];
+}
+export function uninstallPiPackage(homeDir, run = runPi) {
+    requireSuccess(run(homeDir, ['remove', piPackageSource()]), 'package removal');
+    return [piPackageRoot(homeDir)];
+}
+export function doctorPiPackage(homeDir, run = runPi) {
+    const listed = run(homeDir, ['list']);
+    const root = piPackageRoot(homeDir);
+    const manifestPath = path.join(root, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch {
+        // The diagnostics below name the missing or invalid package state.
+    }
+    const extensions = manifest?.pi?.extensions;
+    return [
+        listed.status === 0 && listed.stdout.includes(SQUARE_IDENTITY.packageName)
+            ? `✓ Pi package ${SQUARE_IDENTITY.packageName} configured`
+            : `○ Pi package ${SQUARE_IDENTITY.packageName} not configured`,
+        manifest?.version === SQUARE_IDENTITY.packageVersion
+            ? `✓ Pi package ${SQUARE_IDENTITY.packageVersion} installed at ${root}`
+            : `○ Pi package ${SQUARE_IDENTITY.packageVersion} missing at ${root}`,
+        Array.isArray(extensions) && extensions.includes('./extensions/square-pi.js')
+            ? '✓ Pi Square extension declared'
+            : '○ Pi Square extension not declared',
+    ];
+}