@astrosheep/square 0.3.56 → 0.3.57

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.56",
+  "version": "0.3.57",
   "description": "Native Claude Code turn-boundary delivery for Square participants",
   "author": {
     "name": "Square"

package/codex-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "square",
-  "version": "0.3.56",
+  "version": "0.3.57",
   "description": "Shared Square activity with reliable participant attention at Codex boundaries.",
   "author": {
     "name": "Square"

package/dist/activity.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { SquareError, isSquareError, validateName } from './model.js';
-import { expressHintLine, renderActivityBlocked, renderActivityLimit, renderExpressNoWait, renderExpressWaiting, renderPendingFeed, withPathOutput, } from './presentation.js';
+import { expressHintLine, renderActivityBlocked, renderActivityLimit, renderExpressNoWait, renderExpressWaiting, renderPendingFeed, joinRecoveryCommand, withPathOutput, } from './presentation.js';
 import { nowMs, SLEEP_MS } from './runtime.js';
 import { openSquare } from './square-file-adapter.js';
 import { closeOpenSquare } from './open-square.js';
@@ -55,6 +55,8 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
                 const draftPath = saveActivityDraft(squarePath, name, rawInput);
                 process.stderr.write(err.message + '\n');
                 process.stderr.write(`draft kept: ${draftPath}\n`);
+                if (/^Unknown participant/.test(err.message))
+                    process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
                 process.exit(2);
             }
             process.stderr.write(err.message + '\n');

package/dist/cli/program.js

@@ -1,13 +1,20 @@
 import { helpRequest } from '../help.js';
 import { isSquareError } from '../model.js';
-import { commandPrefix } from '../presentation.js';
+import { joinRecoveryCommand, participantsRecoveryCommand } from '../presentation.js';
 import { defaultContext, parseGlobalArgs } from './context.js';
 import { executeRegisteredCommand, findCommand } from './registry.js';
-function handleSquareError(error, squarePath) {
+function handleSquareError(error, squarePath, name) {
     if (isSquareError(error)) {
         process.stderr.write(`${error.message}\n`);
-        if (squarePath !== undefined && /^(Unknown participant|Unknown mention target)/.test(error.message)) {
-            process.stderr.write(`» ${commandPrefix(squarePath)} participants\n`);
+        if (squarePath !== undefined && /^Unknown participant/.test(error.message)) {
+            // The caller's name has never joined this square; only a join admits it.
+            if (name !== undefined)
+                process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
+            else
+                process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
+        }
+        else if (squarePath !== undefined && /^Unknown mention target/.test(error.message)) {
+            process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
         }
         process.exit(error.code === 'not_found' ? 1 : 2);
     }
@@ -16,6 +23,7 @@ function handleSquareError(error, squarePath) {
 /** Parse global flags, select an executable adapter, and leave all command work to the registry. */
 export async function runCli(rawArgs = process.argv.slice(2)) {
     let squarePath;
+    let requestedName;
     try {
         const requestedHelp = helpRequest(rawArgs);
         if (requestedHelp !== undefined) {
@@ -24,6 +32,7 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
         }
         const parsed = await parseGlobalArgs(rawArgs);
         squarePath = parsed.squarePath;
+        requestedName = parsed.name;
         if (parsed.args.length === 0 || parsed.args[0] === '--help' || parsed.args[0] === '-h') {
             await executeRegisteredCommand('help', [], defaultContext('help', parsed.squarePath, parsed.name));
             return;
@@ -36,6 +45,6 @@ export async function runCli(rawArgs = process.argv.slice(2)) {
         await executeRegisteredCommand(command, parsed.args.slice(1), defaultContext(command, parsed.squarePath, parsed.name));
     }
     catch (error) {
-        handleSquareError(error, squarePath);
+        handleSquareError(error, squarePath, requestedName);
     }
 }

package/dist/presentation.d.ts

@@ -49,6 +49,9 @@ export declare function withPathOutput(squarePath: string, body?: string, opts?:
 export declare function quoteShell(value: string): string;
 export declare function commandPrefix(squarePath: string): string;
 export declare function participantCommandPrefix(squarePath: string, name: string): string;
+/** Blocked actions end with a full copy-pasteable recovery command. */
+export declare function joinRecoveryCommand(squarePath: string, name: string): string;
+export declare function participantsRecoveryCommand(squarePath: string): string;
 export declare function renderPresenceLines(participants: ParticipantStatus[], now: number, limit?: number): string[];
 export declare function expressHintLine(ownActivityCount: number): string | undefined;
 export declare function truncateChars(body: string, maxChars: number): {

package/dist/presentation.js

@@ -41,6 +41,13 @@ export function commandPrefix(squarePath) {
 export function participantCommandPrefix(squarePath, name) {
     return `square --location ${quoteShell(path.resolve(squarePath))} --as ${quoteShell(name)}`;
 }
+/** Blocked actions end with a full copy-pasteable recovery command. */
+export function joinRecoveryCommand(squarePath, name) {
+    return `» ${participantCommandPrefix(squarePath, name)} join`;
+}
+export function participantsRecoveryCommand(squarePath) {
+    return `» ${commandPrefix(squarePath)} participants`;
+}
 function formatAge(ms) {
     if (ms === undefined)
         return '(none)';

package/dist/watch.js

@@ -6,7 +6,7 @@ import { closeOpenSquare } from './open-square.js';
 import { openParticipant } from './square-wiring.js';
 import { resolveParticipant, watchPresentation } from './views.js';
 import { acquireWatchLease, ownsWatchLease, pulseWatchLease, releaseWatchLease } from './wakes.js';
-import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, } from './presentation.js';
+import { renderWatchForceTakeover, renderWatchAlreadyActive, renderWatchReplaceMissing, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, joinRecoveryCommand, participantsRecoveryCommand, withPathOutput, } from './presentation.js';
 import { hasAutomaticDeliveryIdentity } from './registry.js';
 import { parseActivityId } from './square-core.js';
 function watchStatusExitCode(status) {
@@ -150,6 +150,18 @@ export async function cmdWatch(squarePath, name, opts) {
     try {
         square = await openSquare(squarePath, { clock: nowMs });
         name = (await resolveParticipant(square, name)).name;
+    }
+    catch (err) {
+        if (isSquareError(err)) {
+            process.stderr.write(err.message + '\n');
+            // The caller's own name has never joined; only a join admits it.
+            if (/^Unknown participant/.test(err.message))
+                process.stderr.write(`${joinRecoveryCommand(squarePath, name)}\n`);
+            process.exit(err.code === 'not_found' ? 1 : 2);
+        }
+        throw err;
+    }
+    try {
         if (opts.mention !== undefined)
             opts = { ...opts, mention: (await resolveParticipant(square, opts.mention)).name };
         if (opts.participants !== undefined && opts.participants.length > 0) {
@@ -157,8 +169,12 @@ export async function cmdWatch(squarePath, name, opts) {
         }
     }
     catch (err) {
+        await closeOpenSquare(square).catch(() => undefined);
         if (isSquareError(err)) {
             process.stderr.write(err.message + '\n');
+            // A filter target is unknown, not the caller; the roster is the useful next read.
+            if (/^(Unknown participant|Unknown mention target)/.test(err.message))
+                process.stderr.write(`${participantsRecoveryCommand(squarePath)}\n`);
             process.exit(err.code === 'not_found' ? 1 : 2);
         }
         throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.56",
+  "version": "0.3.57",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {