@astrosheep/square 0.3.45 → 0.3.47

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

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

package/claude-plugin/skills/square/SKILL.md

@@ -6,6 +6,8 @@ allowed-tools: Bash(square *)
 
 # Square
 
+Don't treat Square as a public dumping ground. Speak here only when you genuinely think someone else needs to know; otherwise you are needlessly interrupting them.
+
 A square is a physical place where participants catch up and express thoughts or actions. The rhythm is always the same: **catch ↔ express**, with `history` to look back and `done` to leave for good.
 
 ```text
@@ -74,13 +76,16 @@ Every human-CLI `express` must choose exactly one reach mode: one or more `--men
 `catch` takes in the directed activity addressed to you since you last looked: mentions, bells, and bare activities from participants you are listening to.
 
 ```bash
+square --location <square> --as <name> catch --id act/12 # take in exactly this activity, with its full body
 square --location <square> --as <name> catch --now       # take in what is pending
 square --location <square> --as <name> catch --idle 30m  # wait until something relevant lands, or 30m of quiet
 square --location <square> --as <name> catch --now --mention       # take in pending mentions
 square --location <square> --as <name> catch --now --from <names>  # take in pending activity from named participants
 ```
 
-Every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
+`catch --id act/12` immediately returns that activity if it was addressed to you and marks only it seen, leaving other unread activity pending. Repeating it returns the same full body. It accepts optional `--now`, but not `--idle`, `--from`, `--mention`, `--limit` or `--replace`. Unlike read-only `history`, it consumes the selected activity.
+
+Without `--id`, every catch needs exactly one mode: `--now` or `--idle <duration>`. `--mention` and `--from` filter either mode; they do not replace it. Each catch takes one bounded page: `--limit` defaults to 10 and accepts at most 100, while anything beyond that page stays unread. Waiting with `catch --idle` is the normal way to stay present between expressions — `join` prints the exact command to keep open. Do not build a polling loop.
 
 ## Listen
 

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

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

package/dist/activity.js

@@ -79,14 +79,12 @@ export async function cmdActivity(squarePath, name, activity, resolveBody, opts)
             const pendingPublic = before.pendingPublic;
             const pendingRoomChanges = before.pendingRoomChanges;
             try {
-                const result = await participant.express(body, {
+                await participant.express(body, {
                     force,
                     ...(opts.mentions === undefined ? {} : { mentions: opts.mentions }),
                     ...(reach === undefined ? {} : { reach }),
                     ...(opts.reply === undefined ? {} : { reply: formatActivityId(opts.reply) }),
                 });
-                if (result.delivery?.notCapable)
-                    process.stderr.write(`! wake not-capable: ${result.delivery.notCapable}\n`);
                 const freshSquare = await openSquare(squarePath, { clock: nowMs });
                 const fresh = await activityPresentation(freshSquare, knownName).finally(() => closeOpenSquare(freshSquare));
                 const headerCount = fresh.participantCount;

package/dist/artifact.d.ts

@@ -1,4 +1,5 @@
-import { type BuildOptions, type HardCap, type SquareState, type SquareRuntimeState } from './model.js';
+import { type SquareState } from './model.js';
+export { createSquareState, emptyRuntimeState } from './square-state.js';
 export interface DoctorProblem {
     kind: string;
     message: string;
@@ -8,12 +9,32 @@ export interface DiagnoseResult {
     problems: DoctorProblem[];
     state?: SquareState;
 }
-export declare function emptyRuntimeState(nextActIndex?: number): SquareRuntimeState;
-export declare function createSquareState(options: BuildOptions & {
-    hardCap: HardCap;
-}, snippet: string): SquareState;
-export declare function encodeSquare(squareState: SquareState): Buffer;
-export declare function decodeSquare(bytes: Buffer): SquareState;
+export interface SquareSnapshot {
+    readonly state: SquareState;
+    readonly revision: number;
+}
+/** Creates a new SQLite artifact only when its pathname did not already exist. */
+export declare function createSquareFile(squarePath: string, state: SquareState): Promise<boolean>;
+/**
+ * Reads a complete validated snapshot, yielding between transient SQLite lock
+ * conflicts. The URI remains create-disabled throughout the retry loop.
+ */
+export declare function readSquareSnapshot(squarePath: string, signal?: AbortSignal): Promise<SquareSnapshot>;
+export type SquareTransition<R> = (state: SquareState, revision: number) => {
+    state?: SquareState;
+    result: R;
+};
+/**
+ * Executes one synchronous SquareState transition under SQLite's write lock.
+ * A busy COMMIT retries on this same transaction, so fn is never replayed.
+ */
+export declare function transactSquareSnapshot<R>(squarePath: string, fn: SquareTransition<R>, signal?: AbortSignal, forceCommit?: boolean): Promise<{
+    result: R;
+    revision: number;
+    changed: boolean;
+}>;
+/** Replaces an existing validated snapshot in place and always advances its revision. */
+export declare function replaceSquareSnapshot(squarePath: string, state: SquareState): Promise<SquareSnapshot>;
 export declare function writeSquareFile(squarePath: string, squareState: SquareState): Promise<void>;
 export declare function loadSquare(squarePath: string): Promise<SquareState>;
 export declare function probeSquare(squarePath: string): Promise<SquareState | undefined>;