@astrosheep/square 0.3.12 → 0.3.13

package/dist/delivery-health.d.ts

@@ -0,0 +1,21 @@
+import { type DirectedNotificationRoute } from './delivery.js';
+import type { WakeAttempt } from './wake-attempts.js';
+export type DeliveryHealthKind = 'awaiting' | 'wake-accepted' | 'wake-unknown' | 'presented-not-delivered' | 'unreachable';
+export interface DeliveryHealthItem {
+    squarePath: string;
+    recipient: string;
+    actIndex: number;
+    actor: string;
+    at: number;
+    ageMs: number;
+    route: DirectedNotificationRoute;
+    kind: DeliveryHealthKind;
+    attempt?: WakeAttempt;
+}
+/** Purely classify current pending attention from the artifact and durable ledgers. */
+export declare function classifyDeliveryHealth(squarePath: string, opts: {
+    graceMs: number;
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<DeliveryHealthItem[]>;
+export declare function doctorDeliveryHealth(squarePath: string, graceMs: number, now?: number, env?: NodeJS.ProcessEnv): Promise<string[]>;

package/dist/delivery-health.js

@@ -1,8 +1,10 @@
-import { loadSquare } from './artifact.js';
-import { deriveDeliveryModel, } from './delivery.js';
 import { formatActivityId } from './square-core.js';
+import { participantIdentity } from './presentation.js';
 import { formatDuration } from './time.js';
-import { joinedRecipients, wakeEvidence } from './wake-evidence.js';
+import { wakeEvidence } from './wake-evidence.js';
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { pendingDeliveries } from './views.js';
 const DISPLAY_ORDER = [
     'awaiting',
     'wake-accepted',
@@ -12,43 +14,47 @@ const DISPLAY_ORDER = [
 ];
 const ACTIONABLE = new Set(['wake-unknown', 'unreachable']);
 /** Purely classify current pending attention from the artifact and durable ledgers. */
-export function classifyDeliveryHealth(squarePath, opts) {
+export async function classifyDeliveryHealth(squarePath, opts) {
     const now = opts.now ?? Date.now();
     const env = opts.env ?? process.env;
-    const doc = loadSquare(squarePath);
-    const model = deriveDeliveryModel(doc);
-    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 }),
-        };
-    }));
+    const square = await openSquare(squarePath, { clock: () => now });
+    const pending = await pendingDeliveries(square).finally(() => closeOpenSquare(square));
+    const items = [];
+    for (const delivery of pending) {
+        for (const note of delivery.notifications) {
+            const ageMs = Math.max(0, now - note.item.at);
+            const evidence = await 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);
+            items.push({
+                squarePath,
+                recipient: note.recipient,
+                actIndex: note.item.index,
+                actor: note.item.actor,
+                at: note.item.at,
+                ageMs,
+                route: note.route,
+                kind,
+                ...(attempt === undefined ? {} : { attempt }),
+            });
+        }
+    }
+    return items;
 }
 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}`;
+    return `  · ${formatActivityId(item.actIndex)} → ${participantIdentity(item.recipient)} from ${participantIdentity(item.actor)} · ${formatDuration(item.ageMs)}${evidence}`;
 }
-export function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
-    const items = classifyDeliveryHealth(squarePath, { graceMs, now, env });
+export async function doctorDeliveryHealth(squarePath, graceMs, now = Date.now(), env = process.env) {
+    const items = await classifyDeliveryHealth(squarePath, { graceMs, now, env });
     if (items.length === 0)
         return ['✓ no pending delivery attention'];
     const out = [`· delivery attention · ${items.length} pending`];

package/dist/delivery.d.ts

@@ -0,0 +1,81 @@
+import { type DeliveryReceipt, type DirectedNotificationRoute, type SquareState, type SquareRuntimeState, type StoredAct, type WatchLease, type WatchLeaseFilter, type WakeRouteKind, type Reach } from './model.js';
+export type { DirectedNotificationRoute } from './model.js';
+export type SayItem = StoredAct & {
+    kind: 'say';
+};
+export declare function notificationMessageId(squarePath: string, actIndex: number): string;
+export interface PlannedNotification {
+    item: SayItem;
+    recipient: string;
+    route: DirectedNotificationRoute;
+}
+export interface WakeRequest {
+    squarePath: string;
+    actIndex: number;
+    recipient: string;
+    actor: string;
+    route: DirectedNotificationRoute;
+}
+export type WakeDispatchResult = {
+    outcome: 'accepted';
+} | {
+    outcome: 'unknown';
+    signature: string;
+    message: string;
+    diagnostic?: unknown;
+} | {
+    outcome: 'failed';
+    signature: string;
+    message: string;
+    diagnostic?: unknown;
+} | {
+    outcome: 'cancelled';
+};
+export interface WakeAdapter {
+    readonly kind: WakeRouteKind;
+    dispatch(address: Readonly<Record<string, string>>, payload: string, beforeSend: () => Promise<boolean>): Promise<WakeDispatchResult>;
+}
+export interface RoutedNotification {
+    actor: string;
+    body: string;
+    route: DirectedNotificationRoute;
+}
+export interface CatchFilterShape {
+    actor: string;
+    body: string;
+    reach?: Reach;
+}
+export interface DeliveryModel {
+    plan(item: StoredAct): PlannedNotification[];
+    pendingFor(recipient: string): PlannedNotification[];
+}
+/** Delivery receipts are the only durable acknowledgement of directed attention. */
+export declare function deliveryReceipt(squareState: SquareState, name: string, actOrIndex: StoredAct | number): DeliveryReceipt | undefined;
+export declare function deliveryReceiptFromRuntime(runtime: SquareRuntimeState, recipient: string, actOrIndex: StoredAct | number): DeliveryReceipt | undefined;
+export declare function isDeliveryDelivered(squareState: SquareState, name: string, actOrIndex: StoredAct | number): boolean;
+export declare function recordDeliveredDelivery(squareState: SquareState, name: string, actOrIndex: StoredAct | number, receipt: Omit<DeliveryReceipt, 'status'>): boolean;
+export declare function recordDeliveredRuntime(runtime: SquareRuntimeState, recipient: string, actOrIndex: StoredAct | number, receipt: Omit<DeliveryReceipt, 'status'>): boolean;
+export declare function markDeliveredDelivery(squareState: SquareState, name: string, actOrIndex: StoredAct | number, at?: number): boolean;
+/**
+ * Derive delivery behavior once from the decoded Square state.
+ * All consumers share these targets instead of reinterpreting artifact text or cursor state.
+ */
+export declare function deriveDeliveryModel(squareState: SquareState): DeliveryModel;
+export declare function planActNotifications(squareState: SquareState, item: StoredAct): PlannedNotification[];
+/** Mark only the directed notifications selected by the canonical pending projection. */
+export declare function markDeliveredNotifications(squareState: SquareState, recipient: string, delivered: StoredAct[], at?: number): boolean;
+/** Canonical say-activity filter shared by catch selection and hook ownership. */
+export declare function matchesCatchFilter(activity: CatchFilterShape, filter: WatchLeaseFilter): boolean;
+/** True only when the live catch's own filters would deliver this notification. */
+export declare function leaseOwnsNotification(lease: WatchLease, notification: RoutedNotification): boolean;
+export type SquareRoute = Readonly<unknown>;
+interface ParsedSquareRoute {
+    readonly v: 1;
+    readonly squarePath: string;
+    readonly name: string;
+}
+export declare function parseSquareRoute(value: unknown): ParsedSquareRoute;
+export declare function captureRoute(input: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}): SquareRoute | null;

package/dist/delivery.js

@@ -1,24 +1,26 @@
-import { findParticipantName, sameName, } from './model.js';
+import path from 'node:path';
+import { SquareError, findParticipantName, sameName, } from './model.js';
+import { canonicalSquarePath, localParticipantName } from './registry.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}#${formatActivityId(actIndex)}`;
 }
-function canonicalRecipient(doc, name) {
-    return resolveRosterName(doc, name) ?? name;
+function canonicalRecipient(squareState, name) {
+    return resolveRosterName(squareState, 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 deliveryReceipt(squareState, name, actOrIndex) {
+    return deliveryReceiptFromRuntime(squareState.runtime, canonicalRecipient(squareState, 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 isDeliveryDelivered(squareState, name, actOrIndex) {
+    return deliveryReceipt(squareState, name, actOrIndex)?.status === 'delivered';
 }
-export function recordDeliveredDelivery(doc, name, actOrIndex, receipt) {
-    return recordDeliveredRuntime(doc.runtime, canonicalRecipient(doc, name), actOrIndex, receipt);
+export function recordDeliveredDelivery(squareState, name, actOrIndex, receipt) {
+    return recordDeliveredRuntime(squareState.runtime, canonicalRecipient(squareState, name), actOrIndex, receipt);
 }
 export function recordDeliveredRuntime(runtime, recipient, actOrIndex, receipt) {
     const id = actId(actOrIndex);
@@ -27,15 +29,15 @@ export function recordDeliveredRuntime(runtime, recipient, actOrIndex, receipt)
     (runtime.deliveryReceipts[recipient] ??= {})[id] = { status: 'delivered', ...receipt };
     return true;
 }
-export function markDeliveredDelivery(doc, name, actOrIndex, at = Date.now()) {
-    return recordDeliveredDelivery(doc, name, actOrIndex, { at });
+export function markDeliveredDelivery(squareState, name, actOrIndex, at = Date.now()) {
+    return recordDeliveredDelivery(squareState, name, actOrIndex, { at });
 }
 /**
- * Derive delivery behavior once from the parsed Square document.
+ * Derive delivery behavior once from the decoded Square state.
  * All consumers share these targets instead of reinterpreting artifact text or cursor state.
  */
-export function deriveDeliveryModel(doc) {
-    const roster = rosterNames(doc).filter((name) => isCurrentlyJoined(doc.acts, name));
+export function deriveDeliveryModel(squareState) {
+    const roster = rosterNames(squareState).filter((name) => isCurrentlyJoined(squareState.acts, name));
     let pendingByRecipient;
     function plan(item) {
         if (item.kind !== 'say')
@@ -52,8 +54,8 @@ export function deriveDeliveryModel(doc) {
             return [];
         if (pendingByRecipient === undefined) {
             pendingByRecipient = new Map(roster.map((name) => [name, []]));
-            const joinedAfter = new Map(roster.map((name) => [name, lastJoinIndex(doc.acts, name)]));
-            for (const act of doc.acts) {
+            const joinedAfter = new Map(roster.map((name) => [name, lastJoinIndex(squareState.acts, name)]));
+            for (const act of squareState.acts) {
                 if (act.kind !== 'say')
                     continue;
                 const audience = audienceOf(act);
@@ -63,7 +65,7 @@ export function deriveDeliveryModel(doc) {
                     const joinedAt = joinedAfter.get(planned.recipient);
                     if (joinedAt === undefined || act.index <= joinedAt)
                         continue;
-                    if (isDeliveryDelivered(doc, planned.recipient, act.index))
+                    if (isDeliveryDelivered(squareState, planned.recipient, act.index))
                         continue;
                     pendingByRecipient.get(planned.recipient)?.push(planned);
                 }
@@ -73,17 +75,17 @@ export function deriveDeliveryModel(doc) {
     }
     return { plan, pendingFor };
 }
-export function planActNotifications(doc, item) {
-    return deriveDeliveryModel(doc).plan(item);
+export function planActNotifications(squareState, item) {
+    return deriveDeliveryModel(squareState).plan(item);
 }
 /** Mark only the directed notifications selected by the canonical pending projection. */
-export function markDeliveredNotifications(doc, recipient, delivered, at = Date.now()) {
+export function markDeliveredNotifications(squareState, 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)) {
+    for (const notification of deriveDeliveryModel(squareState).pendingFor(recipient)) {
         if (!deliveredIndexes.has(notification.item.index))
             continue;
-        changed = recordDeliveredDelivery(doc, notification.recipient, notification.item.index, { at }) || changed;
+        changed = recordDeliveredDelivery(squareState, notification.recipient, notification.item.index, { at }) || changed;
     }
     return changed;
 }
@@ -105,3 +107,39 @@ export function leaseOwnsNotification(lease, notification) {
         ...(notification.route === 'bell' ? { reach: 'bell' } : {}),
     }, lease.filter ?? {});
 }
+const SQUARE_ROUTE_KEYS = ['name', 'squarePath', 'v'];
+function publicSquareFromCwd(cwd) {
+    return path.resolve(cwd, '.square', 'PUBLIC.square');
+}
+export function parseSquareRoute(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new SquareError('invalid_args', 'Malformed Square route');
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    if (keys.length !== SQUARE_ROUTE_KEYS.length || keys.some((key, index) => key !== SQUARE_ROUTE_KEYS[index])) {
+        throw new SquareError('invalid_args', 'Malformed Square route');
+    }
+    if (record.v !== 1 ||
+        typeof record.squarePath !== 'string' || record.squarePath === '' ||
+        typeof record.name !== 'string' || record.name === '') {
+        throw new SquareError('invalid_args', 'Malformed Square route');
+    }
+    return {
+        v: 1,
+        squarePath: record.squarePath,
+        name: record.name,
+    };
+}
+export function captureRoute(input) {
+    const env = input.env ?? process.env;
+    const squarePath = canonicalSquarePath(publicSquareFromCwd(input.cwd));
+    const name = localParticipantName(squarePath, env);
+    if (name === undefined)
+        return null;
+    return Object.freeze({
+        v: 1,
+        squarePath,
+        name,
+    });
+}

package/dist/file-lock.d.ts

@@ -0,0 +1,6 @@
+export interface FileLockOptions {
+    retryMs: number;
+    staleMs: number;
+}
+export declare function withFileLockSync<T>(lockPath: string, options: FileLockOptions, fn: () => T): T;
+export declare function withFileLock<T>(lockPath: string, options: FileLockOptions, fn: () => T | Promise<T>): Promise<T>;

package/dist/harness-claude.d.ts

@@ -0,0 +1,19 @@
+export declare const CLAUDE_PLUGIN_ID: "square@astrosheep";
+export declare const CLAUDE_MARKETPLACE_NAME: "astrosheep";
+export interface ClaudeCommandResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export type ClaudeCommandRunner = (homeDir: string, args: string[]) => ClaudeCommandResult;
+export interface ClaudeInstallResult {
+    marketplaceRoot: string;
+    pluginRoot: string;
+}
+export declare function claudeMarketplaceRoot(homeDir: string): string;
+export declare function installClaudePlugin(homeDir: string, run?: ClaudeCommandRunner): Promise<ClaudeInstallResult>;
+export declare function uninstallClaudePlugin(homeDir: string, run?: ClaudeCommandRunner): Promise<{
+    paths: string[];
+    notes: string[];
+}>;
+export declare function doctorClaudePlugin(homeDir: string, run?: ClaudeCommandRunner): Promise<string[]>;

package/dist/harness-claude.js

@@ -1,7 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import crossSpawn from 'cross-spawn';
 import { SQUARE_IDENTITY } from './identity.js';
 import { stageReplacement } from './harness-stage.js';
 export const CLAUDE_PLUGIN_ID = SQUARE_IDENTITY.pluginId;
@@ -10,11 +10,16 @@ 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, {
+    const command = process.env.SQUARE_CLAUDE_BIN || 'claude';
+    const result = crossSpawn.sync(command, args, {
         encoding: 'utf8', env: { ...process.env, HOME: homeDir, CLAUDE_CONFIG_DIR: path.join(homeDir, '.claude') }, timeout: 30_000,
     });
-    if (result.error)
+    if (result.error) {
+        if (result.error.code === 'ENOENT') {
+            throw new Error(`Claude CLI not found: ${command}. Install Claude Code or set SQUARE_CLAUDE_BIN to its executable path.`);
+        }
         throw result.error;
+    }
     return { status: result.status ?? 1, stdout: result.stdout || '', stderr: result.stderr || '' };
 }
 function requireSuccess(result, operation, allowMissing = false) {

package/dist/harness-codex.d.ts

@@ -0,0 +1,29 @@
+export declare const CODEX_HOOK_COMMAND: "square codex-hook";
+export declare const SQUARE_CODEX_MARKER: "square-codex-hook";
+export declare const CODEX_PLUGIN_ID: "square@astrosheep";
+export declare const CODEX_MARKETPLACE_NAME: "astrosheep";
+export interface CodexCommandResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export type CodexCommandRunner = (homeDir: string, args: string[], codexHomeDir?: string) => CodexCommandResult;
+export interface CodexInstallResult {
+    configPath: string;
+    marketplaceRoot: string;
+    pluginRoot: string;
+    installedPath?: string;
+    notes: string[];
+}
+export declare function codexMarketplaceRoot(homeDir: string): string;
+export declare function codexPluginRoot(homeDir: string, marketplaceRoot?: string): string;
+export declare function codexPluginHooksPath(homeDir: string, marketplaceRoot?: string): string;
+export declare function codexHomeHooksPath(homeDir: string, codexHomeDir?: string): string;
+export declare function codexConfigPath(homeDir: string, codexHomeDir?: string): string;
+export declare function upsertTomlSectionKey(text: string, section: string, key: string, value: string): string;
+export declare function installCodexPlugin(homeDir: string, run?: CodexCommandRunner, codexHomeDir?: string): Promise<CodexInstallResult>;
+export declare function uninstallCodexPlugin(homeDir: string, run?: CodexCommandRunner, codexHomeDir?: string): Promise<{
+    paths: string[];
+    notes: string[];
+}>;
+export declare function doctorCodexPlugin(homeDir: string, run?: CodexCommandRunner, codexHomeDir?: string): Promise<string[]>;

package/dist/harness-codex.js

@@ -1,7 +1,7 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import crossSpawn from 'cross-spawn';
 import { SQUARE_IDENTITY } from './identity.js';
 import { stageReplacement } from './harness-stage.js';
 export const CODEX_HOOK_COMMAND = SQUARE_IDENTITY.hookCommand;
@@ -46,7 +46,7 @@ function codexHome(homeDir, codexHomeDir) {
 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, {
+    const result = crossSpawn.sync(process.env.SQUARE_CODEX_BIN || 'codex', args, {
         encoding: 'utf8', env: { ...process.env, HOME: homeDir, CODEX_HOME: codexHome(homeDir, codexHomeDir) }, timeout: 30_000,
     });
     if (result.error)

package/dist/harness-links.d.ts

@@ -0,0 +1,17 @@
+export interface HarnessLink {
+    source: string;
+    target: string;
+    kind?: 'skill' | 'extension';
+}
+export declare function installHarnessLinks(links: HarnessLink[], force?: boolean): string[];
+export declare function uninstallHarnessLinks(links: HarnessLink[]): string[];
+export declare function doctorHarnessLinks(links: HarnessLink[]): string[];
+export type OpenCodeCommandRunner = (homeDir: string, args: string[]) => {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+/** Verify that OpenCode accepts its resolved runtime configuration after links are installed. */
+export declare function verifyOpenCodeRuntime(homeDir: string, run?: OpenCodeCommandRunner): string;
+export declare function skillLinks(homeDir?: string, parents?: Array<'.claude' | '.agents'>): HarnessLink[];
+export declare function opencodeExtensionLink(homeDir?: string): HarnessLink;

package/dist/harness-links.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import crossSpawn from 'cross-spawn';
 function packageRoot() {
     // Emitted modules live in dist; package assets are one level above them.
     return fileURLToPath(new URL('../', import.meta.url));
@@ -74,7 +74,7 @@ export function doctorHarnessLinks(links) {
         : `○ Square ${link.kind ?? 'link'} missing ${link.target}`);
 }
 function runOpenCode(homeDir, args) {
-    const result = spawnSync(process.env.SQUARE_OPENCODE_BIN || 'opencode', args, {
+    const result = crossSpawn.sync(process.env.SQUARE_OPENCODE_BIN || 'opencode', args, {
         encoding: 'utf8',
         env: { ...process.env, HOME: homeDir, XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME ?? path.join(homeDir, '.config') },
         timeout: 30_000,

package/dist/harness-pi.d.ts

@@ -0,0 +1,11 @@
+export interface PiCommandResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+export type PiCommandRunner = (homeDir: string, args: string[]) => PiCommandResult;
+export declare function piPackageSource(): string;
+export declare function piPackageRoot(homeDir: string): string;
+export declare function installPiPackage(homeDir: string, run?: PiCommandRunner): string[];
+export declare function uninstallPiPackage(homeDir: string, run?: PiCommandRunner): string[];
+export declare function doctorPiPackage(homeDir: string, run?: PiCommandRunner): string[];

package/dist/harness-pi.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import crossSpawn from 'cross-spawn';
 import { SQUARE_IDENTITY } from './identity.js';
 export function piPackageSource() {
     return `npm:${SQUARE_IDENTITY.packageName}@${SQUARE_IDENTITY.packageVersion}`;
@@ -9,7 +9,7 @@ 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, {
+    const result = crossSpawn.sync(process.env.SQUARE_PI_BIN || 'pi', args, {
         encoding: 'utf8',
         env: { ...process.env, HOME: homeDir },
         timeout: 30_000,

package/dist/harness-stage.d.ts

@@ -0,0 +1,6 @@
+export interface StagedReplacement {
+    rollback(): void;
+    finalize(): void;
+}
+/** Replace a file or directory while retaining the previous value for rollback. */
+export declare function stageReplacement(root: string, populate: (stage: string) => void): StagedReplacement;

package/dist/harness.d.ts

@@ -0,0 +1,20 @@
+export type HarnessTargetName = 'claude' | 'codex' | 'opencode' | 'pi' | 'delivery';
+export type HarnessAction = 'install' | 'uninstall' | 'doctor';
+export interface HarnessTargetContext {
+    homeDir: string;
+    squarePath?: string;
+    force: boolean;
+}
+export interface HarnessTargetResult {
+    lines: string[];
+    notes: string[];
+}
+export interface HarnessTarget {
+    name: HarnessTargetName;
+    capabilities: readonly HarnessAction[];
+    install?(context: HarnessTargetContext): Promise<HarnessTargetResult> | HarnessTargetResult;
+    uninstall?(context: HarnessTargetContext): Promise<HarnessTargetResult> | HarnessTargetResult;
+    doctor?(context: HarnessTargetContext): Promise<HarnessTargetResult> | HarnessTargetResult;
+}
+export declare function harnessTargets(): readonly HarnessTarget[];
+export declare function executeHarnessTarget(targetName: string, action: HarnessAction, context: HarnessTargetContext): Promise<HarnessTargetResult>;

package/dist/harness.js

@@ -79,9 +79,11 @@ const TARGETS = [
     {
         name: 'delivery',
         capabilities: ['doctor'],
-        doctor: ({ squarePath }) => result(readableSquarePath(squarePath)
-            ? doctorDeliveryHealth(squarePath, wakeGraceMs())
-            : ['○ delivery health skipped (no readable square path)']),
+        async doctor({ squarePath }) {
+            return result(readableSquarePath(squarePath)
+                ? await doctorDeliveryHealth(squarePath, wakeGraceMs())
+                : ['○ delivery health skipped (no readable square path)']);
+        },
     },
 ];
 export function harnessTargets() {

package/dist/help.d.ts

@@ -0,0 +1,6 @@
+export declare function renderGlobalHelp(): string;
+export declare function renderSubcommandHelp(command: string): string | undefined;
+export declare function helpRequest(rawArgs: string[]): {
+    command?: string;
+} | undefined;
+export declare function commandUsageHint(command: string | undefined): string;

package/dist/help.js

@@ -40,7 +40,7 @@ const COMMANDS = [
     {
         names: ['history'], usage: '[--as <name>] history [filters] [output]', usesSquare: true, group: 'participant',
         summary: 'Read or search the archive without changing what you have caught.',
-        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search ids, participant names, and original bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --ids <ids> | --at <id>         Match stable activity ids and show original bodies.', '  -B, -A, -C <N>                 Set non-negative context around --at.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order.', '', 'Output:', '  --full  --json  --format <fields>  --count'],
+        details: ['Filters:', '  --from <names>                  Match activities from participants.', '  --since <time>, --until <time>  Match a time window.', '  --grep <regex> | --fixed <s>    Search activity ids, participants, and original bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --at <ids>                      Center on comma-separated activity ids; may repeat.', '  -B, -A, -C <N>                 Set non-negative context around every --at coordinate.', '  --after <id>                    Match activities after an id.', '', 'Results:', '  --limit <N> | --all             Bound the newest matches (default 10).', '  --order <asc|desc>              Set display order (default oldest first).', '', 'Output:', '  --full  --json  --format <fields>', '  Without --as, the default view shows complete activity bodies.'],
     },
     { names: ['status'], usage: '[--as <name>] status', usesSquare: true, group: 'participant', summary: 'Show who is present and what happened most recently.' },
     { names: ['participants'], usage: 'participants', usesSquare: true, group: 'host', summary: 'Show the full participant roster and current states.' },
@@ -61,7 +61,6 @@ const COMMANDS = [
         summary: 'Diagnose installed agent-host support.',
         details: ['Targets:', '  claude, codex, opencode, pi  Diagnose one installed adapter.', '  delivery                      Diagnose delivery for the selected square.'],
     },
-    { names: ['compact'], usage: 'compact [--keep N]', usesSquare: true, group: 'host', summary: 'Move older activity out of the working artifact while keeping the latest N.' },
     {
         names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',
         summary: 'Validate binary artifact integrity.',
@@ -76,7 +75,7 @@ function isHelpFlag(value) {
 export function renderGlobalHelp() {
     const groups = [
         { key: 'participant', title: 'In the square:', order: ['join', 'express', 'catch', 'history', 'status', 'hold', 'resume', 'done'] },
-        { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants', 'compact'] },
+        { key: 'host', title: 'Prepare and manage:', order: ['build', 'list', 'participants'] },
         { key: 'maintenance', title: 'Setup:', order: ['install', 'uninstall', 'doctor'] },
     ];
     const commandLines = groups.flatMap(({ key, title, order }) => [
@@ -88,7 +87,9 @@ export function renderGlobalHelp() {
         '',
     ]);
     return [
-        'Usage: square [--location <path>] [--as <name>] <command> [args...]',
+        'Usage: square [--location <square>] [--as <name>] <command> [args...]',
+        'Environment: SQUARE_LOCATION sets the CLI location; SQUARE_PARTICIPANT_NAME sets the participant name.',
+        'CLI flags override environment values. Automatic provider sessions use only .square/PUBLIC.square.',
         '',
         ...commandLines,
         "Run 'square <command> --help' for command options.",
@@ -102,7 +103,7 @@ export function renderSubcommandHelp(command) {
     const aliases = definition.names.filter((name) => name !== command);
     const usage = definition.usage.replace('{command}', command);
     return [
-        `Usage: square ${definition.usesSquare ? '[--location <path>] ' : ''}${usage}`,
+        `Usage: square ${definition.usesSquare ? '[--location <square>] ' : ''}${usage}`,
         ...(aliases.length > 0 ? [`Aliases: ${aliases.join(', ')}`] : []),
         '',
         definition.summary,

package/dist/identity.d.ts

@@ -0,0 +1,13 @@
+export declare const SQUARE_IDENTITY: Readonly<{
+    publisher: "astrosheep";
+    packageName: "@astrosheep/square";
+    packageVersion: string;
+    productName: "Square";
+    pluginName: "square";
+    marketplaceName: "astrosheep";
+    cliName: "square";
+    pluginId: "square@astrosheep";
+    hookCommand: "square codex-hook";
+    hookMarker: "square-codex-hook";
+    clientName: "astrosheep_square";
+}>;

package/dist/inbox.d.ts

@@ -0,0 +1,2 @@
+import { type InboxMembership } from './model.js';
+export declare function sessionInbox(sessionId: string): Promise<InboxMembership[]>;