@astrosheep/square 0.3.12 → 0.3.14

package/dist/watch.js

@@ -1,55 +1,31 @@
 import { setTimeout as sleep } from 'node:timers/promises';
-import { loadSquare } from './artifact.js';
-import { SquareError, nameKey, } from './model.js';
-import { markDeliveredNotifications } from './delivery.js';
-import { SLEEP_MS, STALE_MS, WATCH_HEARTBEAT_MS, WATCH_STALE_MS, countSays, currentHold, doneNames, freshWatchLease, hasQuorum, inSquareCount, nowMs, touchPresenceCursor, writeWatchLease, } from './runtime.js';
-import { execute, withSquareLock, writeSquareDoc } from './square-application.js';
+import { isSquareError, } from './model.js';
+import { SLEEP_MS, STALE_MS, WATCH_HEARTBEAT_MS, nowMs, } from './runtime.js';
+import { openSquare } from './square-file-adapter.js';
+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, renderWatchOutput, renderWatchReplaced, renderWatchStatus, participantCommandPrefix, withPathOutput, } from './presentation.js';
-import { ackPeerDelta, deliveryDelta, filteredPeerActivities, filteredRoomChanges, matchesFeedFilter, peerPublicActs, peerRoomChanges, } from './activity-feed.js';
-import { coreParticipants, resolveKnownName } from './decisions.js';
 import { hasAutomaticDeliveryIdentity, localParticipantOwner } from './registry.js';
-function catchDelta(doc, name) {
-    return deliveryDelta(doc, name);
-}
+import { parseActivityId } from './square-core.js';
 function watchStatusExitCode(status) {
     return status === 'capped' ? 1 : 0;
 }
 function leaseId() {
     return `watch_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}`;
 }
-function leaseFilter(opts) {
-    const filter = {
-        ...(opts.participants !== undefined ? { participants: opts.participants } : {}),
-        ...(opts.mention !== undefined ? { mention: opts.mention } : {}),
-    };
-    return Object.keys(filter).length === 0 ? undefined : filter;
-}
-function setLease(doc, name, id, at, opts, ownerId) {
-    const filter = leaseFilter(opts);
-    writeWatchLease(doc, name, {
-        leaseId: id,
-        ...(ownerId === undefined ? {} : { ownerId }),
-        heartbeatAt: at,
-        expiresAt: at + WATCH_STALE_MS,
-        ...(filter ? { filter } : {}),
+function watchOutputResult(squarePath, presentation, name, caught, opts = {}) {
+    const delivered = caught.activities.flatMap((activity) => {
+        const index = parseActivityId(activity.id);
+        const stored = index === undefined ? undefined : presentation.activities.find((item) => item.index === index);
+        return stored === undefined ? [] : [stored];
     });
-}
-function sameLease(doc, name, id, at = nowMs()) {
-    return freshWatchLease(doc, name, at)?.leaseId === id;
-}
-function consumeDelta(doc, name, delta, delivered, at) {
-    const consumed = ackPeerDelta(doc, name, delta);
-    const receipts = markDeliveredNotifications(doc, name, delivered, at);
-    return consumed || receipts;
-}
-function watchOutputResult(squarePath, doc, name, delta, opts = {}) {
-    const publicItems = peerPublicActs(delta, name).filter((item) => matchesFeedFilter(item, opts));
-    const roomChanges = filteredRoomChanges(delta, name, opts);
-    consumeDelta(doc, name, delta, publicItems, nowMs());
-    writeSquareDoc(squarePath, doc);
+    const publicItems = delivered.filter((item) => item.kind === 'say' || item.kind === 'done');
+    const roomChanges = delivered.filter((item) => item.kind === 'join' || item.kind === 'done' || item.kind === 'hold' || item.kind === 'resume');
     return {
         type: 'output',
-        stdout: renderWatchOutput(doc.acts, publicItems, roomChanges, {
+        stdout: renderWatchOutput([...presentation.activities], publicItems, roomChanges, {
             ...opts,
             squarePath,
             viewer: name,
@@ -58,30 +34,11 @@ function watchOutputResult(squarePath, doc, name, delta, opts = {}) {
         ...(opts.status ? { status: opts.status } : {}),
     };
 }
-function loadPresence(squarePath) {
-    try {
-        const doc = loadSquare(squarePath);
-        const now = nowMs();
-        return { participants: coreParticipants(doc, now), now };
-    }
-    catch {
-        return undefined;
-    }
-}
-function loadHeaderCount(squarePath) {
-    try {
-        return inSquareCount(loadSquare(squarePath));
-    }
-    catch {
-        return undefined;
-    }
-}
-function writeWatchOutput(squarePath, name, stdout, status, idleMs) {
-    const presence = loadPresence(squarePath);
-    const headerOpts = { participantCount: loadHeaderCount(squarePath) };
+function writeWatchOutput(squarePath, name, presentation, stdout, status, idleMs) {
+    const headerOpts = { participantCount: presentation.participantCount };
     const showCatchHint = !hasAutomaticDeliveryIdentity();
     if (status) {
-        process.stdout.write(withPathOutput(squarePath, [renderWatchStatus({ status, squarePath, name, idleMs, presence, showCatchHint }), stdout.trimEnd()].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
+        process.stdout.write(withPathOutput(squarePath, [renderWatchStatus({ status, squarePath, name, idleMs, presence: presentation.presence, showCatchHint }), stdout.trimEnd()].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
         return;
     }
     const fallback = showCatchHint
@@ -89,67 +46,51 @@ function writeWatchOutput(squarePath, name, stdout, status, idleMs) {
         : '';
     process.stdout.write(withPathOutput(squarePath, [stdout.trimEnd(), fallback].filter(Boolean).join('\n\n').trimEnd(), headerOpts));
 }
-function writeWatchTerminal(squarePath, name, status, idleMs) {
-    const presence = loadPresence(squarePath);
+function writeWatchTerminal(squarePath, name, presentation, status, idleMs) {
     process.stdout.write(withPathOutput(squarePath, renderWatchStatus({
         status,
         squarePath,
         name,
         ...(idleMs === undefined ? {} : { idleMs }),
-        presence,
+        presence: presentation.presence,
         showCatchHint: !hasAutomaticDeliveryIdentity(),
-    }), { participantCount: loadHeaderCount(squarePath) }));
+    }), { participantCount: presentation.participantCount }));
 }
-function writeWatchReplaced(squarePath, name) {
-    process.stdout.write(withPathOutput(squarePath, renderWatchReplaced({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
+function writeWatchReplaced(squarePath, name, presentation) {
+    process.stdout.write(withPathOutput(squarePath, renderWatchReplaced({ squarePath, name }), { participantCount: presentation.participantCount }));
 }
-async function finishWatchResult(squarePath, name, result, leaseId, idleMs) {
+async function finishWatchResult(square, squarePath, name, result, leaseId, idleMs) {
     if (result.type === 'output') {
-        await endWatch(squarePath, name, leaseId);
-        writeWatchOutput(squarePath, name, result.stdout, result.status);
+        await endWatch(square, name, leaseId);
+        writeWatchOutput(squarePath, name, await watchPresentation(square, name), result.stdout, result.status);
         process.exitCode = watchStatusExitCode(result.status);
         return true;
     }
     if (result.type === 'terminal') {
-        await endWatch(squarePath, name, leaseId);
-        writeWatchTerminal(squarePath, name, result.status, idleMs);
+        await endWatch(square, name, leaseId);
+        writeWatchTerminal(squarePath, name, await watchPresentation(square, name), result.status, idleMs);
         process.exitCode = watchStatusExitCode(result.status);
         return true;
     }
     if (result.type === 'replaced') {
-        writeWatchReplaced(squarePath, name);
+        writeWatchReplaced(squarePath, name, await watchPresentation(square, name));
         process.exitCode = 0;
         return true;
     }
     return false;
 }
-async function beginWatch(squarePath, name, opts) {
-    const at = nowMs();
+async function beginWatch(square, squarePath, name, opts) {
     const id = leaseId();
     const ownerId = localParticipantOwner(squarePath, name);
-    const committed = await execute(squarePath, {
-        type: 'lease',
-        name,
-        leaseId: id,
-        ...(ownerId === undefined ? {} : { ownerId }),
-        at,
-        expiresAt: at + WATCH_STALE_MS,
-        force: opts.replace,
-        filter: leaseFilter(opts),
-    });
-    if (committed.result.type === 'active')
-        return committed.result;
-    return { type: 'started', leaseId: id, replaced: committed.result.replaced, heartbeatAt: at };
+    return acquireWatchLease(square, name, id, opts, ownerId);
 }
-async function endWatch(squarePath, name, id) {
-    if (id === undefined)
-        return;
-    await execute(squarePath, { type: 'release-lease', name, leaseId: id });
+async function endWatch(square, name, id) {
+    await releaseWatchLease(square, name, id);
 }
-function installWatchInterruptHandler(squarePath, name, currentLeaseId) {
+function installWatchInterruptHandler(square, squarePath, name, currentLeaseId) {
     const onInterrupt = () => {
         void (async () => {
-            await endWatch(squarePath, name, currentLeaseId());
+            await endWatch(square, name, currentLeaseId());
             process.stdout.write(withPathOutput(squarePath, '✕ catch stopped'));
             process.exit(130);
         })().catch((error) => {
@@ -162,157 +103,93 @@ function installWatchInterruptHandler(squarePath, name, currentLeaseId) {
         process.off('SIGINT', onInterrupt);
     };
 }
-function terminalStatus(doc, name) {
-    const count = countSays(doc.acts, name);
-    if (doc.hardCap !== null && count >= doc.hardCap)
-        return 'capped';
-    const done = doneNames(doc.acts);
-    done.delete(nameKey(name));
-    if (hasQuorum(doc, name, done))
-        return 'quorum';
-    return undefined;
-}
 async function cmdWatchNow(squarePath, name, opts) {
-    const result = await withSquareLock(squarePath, () => {
-        const doc = loadSquare(squarePath);
-        const at = nowMs();
-        const touched = touchPresenceCursor(doc, name, at);
-        const delta = catchDelta(doc, name);
-        const peerPublic = peerPublicActs(delta, name);
-        const roomChanges = peerRoomChanges(delta, name);
-        const filteredActivities = filteredPeerActivities(delta, name, opts);
-        const matchingRoomChanges = filteredRoomChanges(delta, name, opts);
-        const hasDeliverable = peerPublic.length > 0 || roomChanges.length > 0;
-        const hasFilteredDeliverable = filteredActivities.length > 0 || matchingRoomChanges.length > 0;
-        const status = terminalStatus(doc, name);
-        if (hasDeliverable && hasFilteredDeliverable) {
-            return watchOutputResult(squarePath, doc, name, delta, {
-                participants: opts.participants,
-                mention: opts.mention,
-                ...(status ? { status } : {}),
-            });
-        }
-        if (hasDeliverable) {
-            const acked = ackPeerDelta(doc, name, delta);
-            if (acked || touched)
-                writeSquareDoc(squarePath, doc);
-        }
-        else if (touched) {
-            writeSquareDoc(squarePath, doc);
-        }
-        if (status)
-            return { type: 'terminal', status };
-        return { type: 'terminal', status: 'empty-now' };
-    });
-    await finishWatchResult(squarePath, name, result, undefined);
+    const square = await openSquare(squarePath, { clock: nowMs });
+    const facade = await openParticipant({ path: squarePath, clock: nowMs }, name);
+    try {
+        const caught = await facade.participant.catch({
+            ...(opts.participants === undefined ? {} : { from: opts.participants }),
+            ...(opts.mention === undefined ? {} : { mention: true }),
+        });
+        const presentation = await watchPresentation(square, name);
+        const status = presentation.terminalStatus;
+        const result = caught.activities.length > 0
+            ? watchOutputResult(squarePath, presentation, name, caught, { mention: opts.mention, ...(status ? { status } : {}) })
+            : { type: 'terminal', status: status ?? 'empty-now' };
+        await finishWatchResult(square, squarePath, name, result, undefined);
+    }
+    finally {
+        await facade.close();
+        await closeOpenSquare(square);
+    }
 }
 export async function cmdWatch(squarePath, name, opts) {
-    let initialDoc;
+    let square;
     try {
-        initialDoc = loadSquare(squarePath);
-        name = resolveKnownName(initialDoc, name);
+        square = await openSquare(squarePath, { clock: nowMs });
+        name = (await resolveParticipant(square, name)).name;
         if (opts.mention !== undefined)
-            opts = { ...opts, mention: resolveKnownName(initialDoc, opts.mention) };
+            opts = { ...opts, mention: (await resolveParticipant(square, opts.mention)).name };
         if (opts.participants !== undefined && opts.participants.length > 0) {
-            opts = { ...opts, participants: opts.participants.map((p) => resolveKnownName(initialDoc, p)) };
+            opts = { ...opts, participants: await Promise.all(opts.participants.map(async (participant) => (await resolveParticipant(square, participant)).name)) };
         }
     }
     catch (err) {
-        if (err instanceof SquareError) {
+        if (isSquareError(err)) {
             process.stderr.write(err.message + '\n');
             process.exit(err.code === 'not_found' ? 1 : 2);
         }
         throw err;
     }
     if (opts.now) {
+        await closeOpenSquare(square);
         await cmdWatchNow(squarePath, name, opts);
         return;
     }
-    const start = await beginWatch(squarePath, name, opts);
+    const start = await beginWatch(square, squarePath, name, opts);
     if (start.type === 'active') {
-        process.stdout.write(withPathOutput(squarePath, renderWatchAlreadyActive({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
+        const presentation = await watchPresentation(square, name);
+        process.stdout.write(withPathOutput(squarePath, renderWatchAlreadyActive({ squarePath, name }), { participantCount: presentation.participantCount }));
+        await closeOpenSquare(square);
         process.exit(1);
     }
     let staleSince = nowMs();
     let currentLeaseId = start.leaseId;
     let nextHeartbeatAt = start.heartbeatAt + WATCH_HEARTBEAT_MS;
     if (start.replaced) {
-        process.stdout.write(withPathOutput(squarePath, renderWatchForceTakeover({ squarePath, name }), { participantCount: loadHeaderCount(squarePath) }));
+        const presentation = await watchPresentation(square, name);
+        process.stdout.write(withPathOutput(squarePath, renderWatchForceTakeover({ squarePath, name }), { participantCount: presentation.participantCount }));
     }
     const idleMs = opts.idleMs ?? STALE_MS;
-    const removeInterruptHandler = installWatchInterruptHandler(squarePath, name, () => currentLeaseId);
+    const removeInterruptHandler = installWatchInterruptHandler(square, squarePath, name, () => currentLeaseId);
+    const facade = await openParticipant({ path: squarePath, clock: nowMs }, name);
     try {
         while (true) {
-            const result = await withSquareLock(squarePath, () => {
-                const doc = loadSquare(squarePath);
-                const at = nowMs();
-                const lease = freshWatchLease(doc, name, at);
-                if (lease === undefined || lease.leaseId !== currentLeaseId)
-                    return { type: 'replaced' };
-                let mutated = false;
-                if (at >= nextHeartbeatAt) {
-                    setLease(doc, name, currentLeaseId, at, opts, lease.ownerId);
-                    mutated = touchPresenceCursor(doc, name, at) || mutated;
-                    nextHeartbeatAt = at + WATCH_HEARTBEAT_MS;
-                    mutated = true;
-                }
-                const delta = catchDelta(doc, name);
-                const peerPublic = peerPublicActs(delta, name);
-                const roomChanges = peerRoomChanges(delta, name);
-                const filteredActivities = filteredPeerActivities(delta, name, opts);
-                const matchingRoomChanges = filteredRoomChanges(delta, name, opts);
-                const hasDeliverable = peerPublic.length > 0 || roomChanges.length > 0;
-                const hasFilteredDeliverable = filteredActivities.length > 0 || matchingRoomChanges.length > 0;
-                const status = terminalStatus(doc, name);
-                if (currentHold(doc.acts).active) {
-                    if (mutated)
-                        writeSquareDoc(squarePath, doc);
-                    return { type: 'held' };
-                }
-                if (hasDeliverable &&
-                    hasFilteredDeliverable &&
-                    (filteredActivities.length > 0 || matchingRoomChanges.length > 0 || status !== undefined)) {
-                    return watchOutputResult(squarePath, doc, name, delta, {
-                        participants: opts.participants,
-                        mention: opts.mention,
-                        ...(status ? { status } : {}),
-                    });
-                }
-                if (hasDeliverable && !hasFilteredDeliverable)
-                    mutated = ackPeerDelta(doc, name, delta) || mutated;
-                if (status) {
-                    if (mutated)
-                        writeSquareDoc(squarePath, doc);
-                    return { type: 'terminal', status };
+            const leaseState = await pulseWatchLease(square, name, currentLeaseId, opts, nowMs() >= nextHeartbeatAt);
+            if (leaseState.type === 'sleep' && leaseState.heartbeatAt !== undefined) {
+                nextHeartbeatAt = leaseState.heartbeatAt + WATCH_HEARTBEAT_MS;
+            }
+            let result = leaseState;
+            if (result.type === 'sleep') {
+                const caught = await facade.participant.catch({
+                    ...(opts.participants === undefined ? {} : { from: opts.participants }),
+                    ...(opts.mention === undefined ? {} : { mention: true }),
+                });
+                if (caught.activities.length > 0) {
+                    result = watchOutputResult(squarePath, await watchPresentation(square, name), name, caught, { mention: opts.mention });
                 }
-                if (mutated)
-                    writeSquareDoc(squarePath, doc);
-                return { type: 'sleep' };
-            });
-            if (await finishWatchResult(squarePath, name, result, currentLeaseId)) {
+            }
+            if (await finishWatchResult(square, squarePath, name, result, currentLeaseId)) {
                 currentLeaseId = undefined;
                 return;
             }
             if (result.type === 'held')
                 staleSince = nowMs();
             if (nowMs() - staleSince >= idleMs) {
-                const result = await withSquareLock(squarePath, () => {
-                    const doc = loadSquare(squarePath);
-                    if (!sameLease(doc, name, currentLeaseId))
-                        return { type: 'replaced' };
-                    const delta = catchDelta(doc, name);
-                    const filteredActivities = filteredPeerActivities(delta, name, opts);
-                    if (filteredActivities.length > 0) {
-                        return watchOutputResult(squarePath, doc, name, delta, {
-                            stalePartial: true,
-                            participants: opts.participants,
-                            mention: opts.mention,
-                            idleMs,
-                        });
-                    }
-                    return { type: 'terminal', status: 'stale' };
-                });
-                if (await finishWatchResult(squarePath, name, result, currentLeaseId, idleMs)) {
+                const result = !await ownsWatchLease(square, name, currentLeaseId)
+                    ? { type: 'replaced' }
+                    : { type: 'terminal', status: 'stale' };
+                if (await finishWatchResult(square, squarePath, name, result, currentLeaseId, idleMs)) {
                     currentLeaseId = undefined;
                     return;
                 }
@@ -321,6 +198,8 @@ export async function cmdWatch(squarePath, name, opts) {
         }
     }
     finally {
+        await facade.close();
+        await closeOpenSquare(square);
         removeInterruptHandler();
     }
 }

package/extensions/square-opencode.js

@@ -1,14 +1,40 @@
 import { presentPendingAtBoundary } from '../dist/boundary-presentation.js';
+import { automaticSessionEnd, automaticSessionStart } from '../dist/automatic-session.js';
 
 export default async function squareOpenCodePlugin() {
+  const joining = new Map();
   return {
+    event: async ({ event }) => {
+      if (event.type === 'session.created' || event.type === 'session.updated') {
+        const sessionID = event.properties?.sessionID;
+        const cwd = event.properties?.info?.directory || process.cwd();
+        if (sessionID) {
+          try {
+            const context = await automaticSessionStart('opencode', sessionID, cwd);
+            if (context) joining.set(sessionID, context);
+          } catch { /* startup remains bounded */ }
+        }
+      } else if (event.type === 'session.deleted') {
+        const sessionID = event.properties?.sessionID;
+        const cwd = event.properties?.info?.directory || process.cwd();
+        if (sessionID) {
+          joining.delete(sessionID);
+          await automaticSessionEnd('opencode', sessionID, cwd);
+        }
+      }
+    },
     'shell.env': async (input, output) => {
       if (input.sessionID) output.env.OPENCODE_SESSION_ID = input.sessionID;
     },
 
     'tool.execute.after': async (input, output) => {
       try {
-        presentPendingAtBoundary(
+        const joined = joining.get(input.sessionID);
+        if (joined) {
+          joining.delete(input.sessionID);
+          output.output = `${output.output}${output.output === '' ? '' : '\n\n'}${joined}`;
+        }
+        await presentPendingAtBoundary(
           input.sessionID,
           (context) => {
             output.output = `${output.output}${output.output === '' ? '' : '\n\n'}${context}`;

package/extensions/square-pi.js

@@ -1,4 +1,5 @@
 import { presentPendingAtBoundary, renderPendingAtBoundary } from '../dist/boundary-presentation.js';
+import { automaticSessionEnd, automaticSessionStart } from '../dist/automatic-session.js';
 
 export function pendingInbox(inbox) {
   return inbox.filter((item) => item.notifications?.length > 0);
@@ -16,17 +17,26 @@ export function renderPiInbox(inbox) {
 
 export default function squarePiExtension(pi) {
   let sessionId;
+  let sessionCwd;
+  let joiningContext;
   let previousSessionId;
   const present = (deliver) => sessionId === undefined ? undefined : presentPendingAtBoundary(sessionId, deliver);
 
   pi.on('session_start', async (_event, ctx) => {
     sessionId = ctx.sessionManager.getSessionId();
+    sessionCwd = ctx.cwd || process.cwd();
     previousSessionId = process.env.SQUARE_PI_SESSION_ID;
     process.env.SQUARE_PI_SESSION_ID = sessionId;
+    try { joiningContext = await automaticSessionStart('pi', sessionId, sessionCwd); } catch { joiningContext = undefined; }
   });
 
   pi.on('before_agent_start', async () => {
     try {
+      if (joiningContext) {
+        const context = joiningContext;
+        joiningContext = undefined;
+        return { message: { customType: 'square', content: context, display: true } };
+      }
       return present((context) => ({ message: { customType: 'square', content: context, display: true } }));
     } catch {
       return undefined;
@@ -34,10 +44,13 @@ export default function squarePiExtension(pi) {
   });
 
   pi.on('session_shutdown', async () => {
+    if (sessionId && sessionCwd) await automaticSessionEnd('pi', sessionId, sessionCwd);
     if (process.env.SQUARE_PI_SESSION_ID === sessionId) {
       if (previousSessionId === undefined) delete process.env.SQUARE_PI_SESSION_ID;
       else process.env.SQUARE_PI_SESSION_ID = previousSessionId;
     }
     sessionId = undefined;
+    sessionCwd = undefined;
+    joiningContext = undefined;
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrosheep/square",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "A shared public square where agents join, catch activity, express, and step out when done.",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
     "build": "npm run clean && tsc && node --input-type=module -e \"import fs from 'node:fs'; fs.chmodSync('dist/square.js',0o755)\"",
     "verify-release": "node test/release.test.js",
     "prepublishOnly": "npm run build && npm run verify-release",
-    "test": "npm run build && node --test test/*.test.js"
+    "test": "npm run build && node --test test/*.test.js",
+    "test:cli-process": "npm run build && node --test test/process/square-cli-render.test.js"
   },
   "keywords": [
     "brainstorm",
@@ -35,6 +36,7 @@
   "author": "astrosheep",
   "license": "MIT",
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^22",
     "@types/ws": "^8.18.1",
     "typescript": "^5.8"
@@ -57,6 +59,7 @@
   },
   "dependencies": {
     "@getpaseo/client": "^0.3.1",
+    "cross-spawn": "^7.0.6",
     "ws": "^8.21.3"
   }
 }

package/skills/brainstorm/SKILL.md

@@ -7,7 +7,7 @@ allowed-tools: Bash(square *), Skill(square)
 # Square Brainstorm
 
 Use this skill when you are coordinating a brainstorm. Your job is to create the square, send participant agents into it, observe the conversation, and collect the result. Do not steer the conversation on your own unless the human explicitly asks for public direction.
-Commands default to `.square/SQUARE.square`; use `--location <path>` when you want a different file.
+Commands default to `.square/SQUARE.square` for build and inspection. Manual participant commands require `--location <square>` or `SQUARE_LOCATION`; `--location` wins. Set `SQUARE_PARTICIPANT_NAME` for the participant name, overridden by `--as`. `.square/PUBLIC.square` is the public square and does not need a manual `join`.
 
 ## Build
 
@@ -31,33 +31,33 @@ square status
 
 ## Start Participants
 
-Send each participant agent this prompt. Replace `<name>` and `<path>`, but do not summarize or rewrite the prompt:
+Send each participant agent this prompt. Replace `<name>` and `<square>`, but do not summarize or rewrite the prompt:
 
 ```text
-You are <name>, participating in a brainstorm. The square file is at <path>.
+You are <name>, participating in a brainstorm. The square file is at <square>.
 
 First action: enter the square. Read the context, warmup, and recent activity printed by this command before expressing:
-square --location <path> --as <name> join
+square --location <square> --as <name> join
 
 Then follow the Happy Path from the join output. Core commands:
-square --location <path> --as <name> express - <<'EOF'
+square --location <square> --as <name> express - <<'EOF'
 ...
 EOF
-square --location <path> --as <name> catch --mention --idle 10m
-square --location <path> --as <name> catch --now
-square --location <path> --as <name> catch --idle 10m
-square --location <path> history --limit 80
-square --location <path> history --from <name> --limit 80
-square --location <path> status
-square --location <path> --as <name> done - <<'EOF'
+square --location <square> --as <name> catch --mention --idle 10m
+square --location <square> --as <name> catch --now
+square --location <square> --as <name> catch --idle 10m
+square --location <square> history --limit 80
+square --location <square> history --from <name> --limit 80
+square --location <square> status
+square --location <square> --as <name> done - <<'EOF'
 ...
 EOF
 
-For complete history: square --location <path> history --all --full
+For complete history: square --location <square> history --all --full
 
 Every activity must address at least one participant with @name. Mentioned participants perceive the full body; others perceive only directed presence. Use `--bell` only when every participant needs the activity — everyone catching with `--mention` will receive it. Precise history queries may still read original archive bodies.
 
-If an activity is refused because something happened while the participant was not looking, run `square --location <path> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
+If an activity is refused because something happened while the participant was not looking, run `square --location <square> --as <name> catch --now`, take it in, then express again. `catch --now` catches up without waiting.
 ```
 
 Need another voice later? Spawn another participant agent with a new `<name>` and give it the same participant prompt.
@@ -67,12 +67,12 @@ Need another voice later? Spawn another participant agent with a new `<name>` an
 If you or the human want to participate, choose a participant name and use the participant loop:
 
 ```bash
-square --location <path> --as <name> join
-square --location <path> --as <name> express - <<'EOF'
+square --location <square> --as <name> join
+square --location <square> --as <name> express - <<'EOF'
 @<participant-name> your view
 EOF
-square --location <path> --as <name> catch --idle 10m
-square --location <path> --as <name> done - <<'EOF'
+square --location <square> --as <name> catch --idle 10m
+square --location <square> --as <name> done - <<'EOF'
 final note
 EOF
 ```
@@ -82,9 +82,9 @@ EOF
 Use these to check progress:
 
 ```bash
-square --location <path> history --limit 50
-square --location <path> history --from <name>
-square --location <path> status
+square --location <square> history --limit 50
+square --location <square> history --from <name>
+square --location <square> status
 ```
 
 `history` reads the archive without advancing participant presence. `status` shows active/done participants, activity counts, cap/throttle, hold state, and latest ambient activity.
@@ -96,7 +96,7 @@ Every activity must contain `@name`; use `--bell` only for activity that every p
 If the human wants to refocus the square, add a constraint, ask a convergence question, or correct its direction, write that direction publicly with a participant name:
 
 ```bash
-square --location <path> --as <name> express --bell - <<'EOF'
+square --location <square> --as <name> express --bell - <<'EOF'
 Refocus on <specific direction, constraint, question, or decision needed>.
 EOF
 ```
@@ -106,8 +106,8 @@ Do not add direction on your own. If you notice the square drifting or stuck, re
 Pause the participant loop when a human needs time to read, think, or add another voice:
 
 ```bash
-square --location <path> hold "human reading"
-square --location <path> resume
+square --location <square> hold "human reading"
+square --location <square> resume
 ```
 
 While held, participant expression and catch pause. Join, done, status, and history still work.
@@ -117,8 +117,8 @@ While held, participant expression and catch pause. Join, done, status, and hist
 When participants are done, collect the public activities:
 
 ```bash
-square --location <path> history --all --full        # complete public history
-square --location <path> status
+square --location <square> history --all --full        # complete public history
+square --location <square> status
 ```
 
 ## Boundaries