@astrosheep/square 0.3.11 → 0.3.13

package/dist/delivery.js

@@ -1,26 +1,26 @@
-import { findParticipantName, sameName, } from './model.js';
-import { actId, extractMentions, isCurrentlyJoined, lastJoinIndex, matchesMentionTarget, resolveRosterName, rosterNames } from './runtime.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}#act_${actIndex}`;
+    return `square:${squarePath}#${formatActivityId(actIndex)}`;
 }
-export function isPendingNotification(notification) {
-    return notification.route !== 'broadcast';
-}
-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);
@@ -29,47 +29,23 @@ 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 });
-}
-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;
+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')
             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) {
@@ -78,23 +54,20 @@ 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;
-                // 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))
+                    if (isDeliveryDelivered(squareState, planned.recipient, act.index))
                         continue;
-                    pendingByRecipient.get(planned.recipient)?.push({ ...planned, route: planned.route });
+                    pendingByRecipient.get(planned.recipient)?.push(planned);
                 }
             }
         }
@@ -102,23 +75,23 @@ 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;
 }
 /** 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 +101,45 @@ 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 ?? {});
 }
+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

@@ -16,9 +16,9 @@ const COMMANDS = [
         details: ['Options:', '  --last <N>  Show the last N public activities (default 10).', '  --all       Show the complete history.'],
     },
     {
-        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--beside <name> | --bell] [--reply <act_N>] <activity | ->', usesSquare: true, group: 'participant',
+        names: ['express'], usage: '--as <name> express [-f|--force] [--no-wait] [--bell] [--reply <activity-id>] <activity | ->', usesSquare: true, group: 'participant',
         summary: 'Speak, gesture, or do both.',
-        details: ['Options:', '  -f, --force       Express without first catching unread activity.', '  --no-wait         If held or throttled, save a draft and return.', '  --beside <name>   Speak aside to one participant.', "  --bell            Call every participant's attention to this activity.", '  --reply <act_N>   Mark this activity as a reply to an earlier activity.'],
+        details: ['Reach:', '  @name             Address someone in the square. They hear the body; everyone else sees you walk over.', "  --bell            Call every participant's attention to this activity without a mention.", '', 'Options:', '  -f, --force       Express without first catching unread activity.', '  --no-wait         If held or throttled, save a draft and return.', '  --reply <activity-id>   Mark this activity as a reply to an earlier activity (for example act/12).'],
     },
     {
         names: ['catch'], usage: '--as <name> catch (--now | --idle <duration>) [--from <names>] [--mention [name]] [--replace]', usesSquare: true, group: 'participant',
@@ -39,10 +39,9 @@ const COMMANDS = [
     { names: ['claude-hook', 'codex-hook'], usage: '{command}', summary: 'Present pending attention at one native agent boundary.', hiddenFromIndex: true },
     {
         names: ['history'], usage: '[--as <name>] history [filters] [output]', usesSquare: true, group: 'participant',
-        summary: 'Read or search what happened 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 bodies.', '  --mention <name>                Match mentions.', '  --pending                       Match attention waiting for --as <name>.', '  --ids <ids> | --at <id>         Match stable activity ids.', '  -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'],
+        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 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: ['warmup'], usage: 'warmup', usesSquare: true, group: 'host', summary: 'Print the complete embedded participant warmup.' },
     { 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.' },
     { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
@@ -62,11 +61,9 @@ 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 [--fix]', usesSquare: true, group: 'maintenance',
-        summary: 'Diagnose artifact integrity.',
-        details: ['Options:', '  --fix              Repair recoverable artifact problems.'],
+        names: ['doctor'], usage: 'doctor', usesSquare: true, group: 'maintenance',
+        summary: 'Validate binary artifact integrity.',
     },
 ];
 function definitionFor(command) {
@@ -78,8 +75,8 @@ 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', 'warmup', 'compact'] },
-        { key: 'maintenance', title: 'Setup and repair:', order: ['install', 'uninstall', 'doctor'] },
+        { 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 }) => [
         title,
@@ -90,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.",
@@ -104,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[]>;

package/dist/inbox.js

@@ -1,34 +1,30 @@
-import { loadSquare } from './artifact.js';
-import { deriveDeliveryModel } from './delivery.js';
 import { lookupSessionBindings } from './registry.js';
-import { freshWatchLease, isCurrentlyJoined, resolveRosterName } from './runtime.js';
-export function sessionInbox(sessionId) {
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { inboxProjection } from './views.js';
+export async function sessionInbox(sessionId) {
     const inbox = [];
     for (const binding of lookupSessionBindings(sessionId)) {
+        let square;
         try {
-            const doc = loadSquare(binding.squarePath);
-            const name = resolveRosterName(doc, binding.name);
-            if (!name || !isCurrentlyJoined(doc.acts, name))
+            square = await openSquare(binding.squarePath);
+            const projection = await inboxProjection(square, binding.name, binding.ownerId);
+            if (!projection.joined)
                 continue;
-            const notifications = deriveDeliveryModel(doc).pendingFor(name).map(({ item, route }) => ({
-                actIndex: item.index,
-                actor: item.actor,
-                at: item.at,
-                route,
-                body: item.body,
-            }));
-            const lease = freshWatchLease(doc, name);
-            const catchLease = lease?.ownerId === binding.ownerId ? lease : undefined;
             inbox.push({
-                name,
+                name: projection.name,
                 squarePath: binding.squarePath,
-                notifications,
-                ...(catchLease !== undefined ? { catchLease } : {}),
+                notifications: [...projection.notifications],
+                ...(projection.catchLease !== undefined ? { catchLease: projection.catchLease } : {}),
             });
         }
         catch {
             // A stale discovery-cache row only disables delivery for that membership.
         }
+        finally {
+            if (square !== undefined)
+                await closeOpenSquare(square);
+        }
     }
     return inbox;
 }

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { type SquareRoute } from './delivery.js';
+import type { ExpressResult } from './square-facade.js';
+export { Square } from './square-wiring.js';
+export { SquareError } from './model.js';
+export { captureRoute } from './delivery.js';
+export type { SquareRoute } from './delivery.js';
+export type { ActivityId } from './square-core.js';
+export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, WakeNotifier, } from './square-facade.js';
+export interface RouteExpressOptions {
+    readonly as: string;
+    readonly body: string;
+}
+export declare function express(route: SquareRoute, options: RouteExpressOptions): Promise<ExpressResult>;