cyberlegion 1.8.0 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.8.0",
+	"version": "1.9.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
 	"name": "cyberlegion",
-	"version": "1.8.0",
+	"version": "1.9.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/.plugin/pins.json

@@ -1,3 +1,3 @@
 {
-	"cyberlegion": "1.8.0"
+	"cyberlegion": "1.9.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # cyberlegion
 
+## 1.9.0
+
+### Minor Changes
+
+- deed34d: `mail inbox --unit <handle|id>` lists another unit's mail without acking it and without the caller taking that unit's identity. Exited units resolve too, so a cleanup sweep can check whether a dead unit left unread mail without reading the hub's files itself. The output carries a `mailbox` state of `none` (no mail was ever delivered), `present`, or `unreadable`. An unreadable mailbox exits 1, so a caller never reads it as empty.
+
+### Patch Changes
+
+- a7a2d57: `unit spawn` no longer leaves several unsent "Read your brief" lines in a new session's input box. The first-turn ring now waits for the harness to draw its input box before typing; keys typed while a harness boots are taken as one paste, so each Enter became a newline and re-typed copies piled up. Copies of the doorbell sitting in the input box are also no longer counted as a posted turn, so a staged doorbell is flushed with Enter instead of reported rung.
+
 ## 1.8.0
 
 ### Minor Changes

package/dist/cli.mjs

@@ -10671,6 +10671,20 @@ function resolveOwnerMailbox(store, ref) {
 	if (services.length > 1) throw new Error(`"${ref}" names ${services.length} service endpoints — pass an endpoint id (${services.map((a) => a.id).join(", ")})`);
 	return resolveStandingOwner(store, ref);
 }
+/** Resolve the unit whose mailbox `mail inbox --unit` reads, by id or handle. Unlike a recipient, an
+* exited unit resolves: the caller is deciding about that unit (a sweep asking whether a dead unit left
+* unread mail), not writing to it. A live holder of the handle wins; several exited holders and no live
+* one fail rather than picking one. */
+function resolveUnitMailbox(store, ref) {
+	const byId = loadAgent(store, ref);
+	if (byId) return byId;
+	const { live, exited } = matchHandle(listAgents(store), ref);
+	const byHandle = pickLive(ref, live);
+	if (byHandle) return byHandle;
+	if (exited.length > 1) throw new Error(`"${ref}" names ${exited.length} exited units — pass an id (${exited.map((a) => a.id).join(", ")})`);
+	if (exited[0]) return exited[0];
+	throw new Error(`no unit addressable as "${ref}" (tried id and handle)`);
+}
 /**
 * Bind the caller's own unit as a standing owner's presence — the live unit standing in for a
 * durable record that has no session of its own. Order matters: resolve the standing record first
@@ -11016,6 +11030,10 @@ function readShape(rows, shape) {
 	}
 	return { kind: "unknown" };
 }
+/** Whether this reader knows `harness`'s input box, so a missing box on screen means it is not drawn yet. */
+function knowsPromptOf(harness) {
+	return harness !== void 0 && SHAPES[harness] !== void 0;
+}
 /**
 * Read the input box off `screen` — a plain-text scrape of the pane — with the shape of `harness`,
 * or, when the harness is not known, with each known shape in turn until one recognizes the box.
@@ -11116,6 +11134,27 @@ function copiesOn(screen, message) {
 	return screen.split("\n").filter((row) => row.replace(/\s+/g, " ").includes(needle)).length;
 }
 /**
+* Read `screen` for the ring: whether `message` sits in the input box, and how many copies of it
+* are on screen outside the box. With the box read by its harness's shape, copies inside the box are
+* left out of the count: a booting harness can take several typed copies as one paste, and those
+* copies are staged text, not posted turns. A screen with no input box the reader knows falls back to
+* cyber-mux's `isStaged`, and the box's copy is counted with the rest.
+*/
+function readRing(screen, message, harness) {
+	const box = screen ? readPrompt(screen, harness) : { kind: "unknown" };
+	if (box.kind === "unknown") return {
+		boxKnown: false,
+		staged: isStaged(screen, message),
+		outside: copiesOn(screen, message)
+	};
+	const inBox = box.kind === "draft" ? copiesOn(box.text, message) : 0;
+	return {
+		boxKnown: true,
+		staged: inBox > 0,
+		outside: copiesOn(screen, message) - inBox
+	};
+}
+/**
 * Submit `message` to `target` as a taken turn: cyber-mux's `nudge`, with one more way to see that the
 * turn was taken.
 *
@@ -11135,18 +11174,32 @@ function copiesOn(screen, message) {
 * queue. Text that is neither staged nor posted is lost: after one more settle for a slow redraw, it
 * is typed again. It is opt-in because it needs the posted copy to stay on screen: a busy peer's
 * output can scroll earlier copies away, so a ring to it could read as lost and be typed twice.
+*
+* With `requirePosted` and a harness whose input box this reader knows, nothing is typed until the
+* harness has drawn that box, for up to the
+* whole retry budget. Keys typed while a harness boots are buffered, and the harness takes them as one
+* paste once it draws the box: each Enter becomes a newline, so re-typed copies pile up in the box
+* unsent. A box that never shows within the budget is typed into anyway, as before.
+*
+* Where the input box can be read, copies of the text inside it are not counted as posted: only a
+* copy outside the box means the harness took the turn.
 */
 async function ringTurn(adapter, exec, target, message, opts = {}) {
 	const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
 	const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
 	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
 	if (!adapter.paneExists(exec, target)) throw new Error(`nudge failed: pane ${target.id} no longer exists — the peer's session is gone, not busy.`);
-	const before = copiesOn(adapter.read(exec, target).text, message);
+	let first = adapter.read(exec, target).text;
+	if (opts.requirePosted && knowsPromptOf(opts.harness)) for (let wait = 0; wait < attempts && !readRing(first, message, opts.harness).boxKnown; wait++) {
+		await sleep(settleMs);
+		first = adapter.read(exec, target).text;
+	}
+	const before = readRing(first, message, opts.harness).outside;
 	const check = () => {
-		const screen = adapter.read(exec, target).text;
-		const copies = copiesOn(screen, message);
-		if (isStaged(screen, message)) return copies >= before + 2 ? "taken" : "staged";
-		return copies > before || !opts.requirePosted ? "taken" : "lost";
+		const seen = readRing(adapter.read(exec, target).text, message, opts.harness);
+		const posted = seen.outside >= before + (seen.boxKnown || !seen.staged ? 1 : 2);
+		if (seen.staged) return posted ? "taken" : "staged";
+		return posted || !opts.requirePosted ? "taken" : "lost";
 	};
 	adapter.submit(exec, target, message);
 	await sleep(settleMs);
@@ -11306,7 +11359,10 @@ async function wakeRecipient(store, getAdapter, exec, input, nudgeOpts, guardOpt
 		try {
 			const adapter = getAdapter();
 			const target = { id: pane };
-			await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, DELIVERY_DOORBELL, nudgeOpts), {
+			await withDraftGuard(adapter, exec, target, () => ringTurn(adapter, exec, target, DELIVERY_DOORBELL, {
+				...nudgeOpts,
+				harness
+			}), {
 				...guardOpts,
 				harness,
 				ownText: (text) => isRingText(text)
@@ -11351,7 +11407,8 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
 		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, {
 			...nudgeOpts,
-			requirePosted: true
+			requirePosted: true,
+			harness: input.harness
 		}), {
 			...guardOpts,
 			harness: input.harness,
@@ -12575,6 +12632,26 @@ function inbox(ctx, q) {
 	if (q.thread) items = items.filter((m) => m.thread === q.thread);
 	return items.sort((a, b) => a.id.localeCompare(b.id));
 }
+/** List another unit's mail read-only, for a caller deciding about that unit (a cleanup sweep): never
+* acks, and reports a missing or unreadable mailbox as its own state rather than as an empty one. */
+function unitInbox(ctx, q) {
+	if (!ctx.store.hasMailbox(q.meId)) return {
+		mailbox: "none",
+		messages: []
+	};
+	try {
+		return {
+			mailbox: "present",
+			messages: inbox(ctx, q)
+		};
+	} catch (err) {
+		return {
+			mailbox: "unreadable",
+			messages: [],
+			error: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
 /** Peek at a message (unread or already-acked) without changing its state. */
 function peek(ctx, meId, msgId) {
 	const snap = ctx.store.listInbox(meId);
@@ -14008,6 +14085,10 @@ var FileStore = class {
 			read: read ? readMessages(read) : []
 		};
 	}
+	hasMailbox(id) {
+		const dir = readPathOrUndefined(() => paths.inboxDir(this.root, id));
+		return dir !== void 0 && existsSync(dir);
+	}
 	ackMessage(id, msgId) {
 		const src = readPathOrUndefined(() => paths.messageFile(this.root, id, msgId));
 		if (!src || !existsSync(src)) throw new Error(`"${msgId}" is not an unread message in this inbox`);
@@ -15238,12 +15319,67 @@ function emitInbox(ctx, opts, meId, readCmd) {
 	const firstUnread = items.find((m) => !m.read);
 	if (firstUnread) nextStep(`${readCmd} ${firstUnread.id}`);
 }
+/** List another unit's mailbox read-only (`--unit`). Its `mailbox` state tells a missing mailbox
+* from an empty one; an unreadable one is reported on stdout and exits 1, never read as empty. */
+function emitUnitInbox(ctx, opts, ref) {
+	let unit;
+	try {
+		unit = resolveUnitMailbox(ctx.store, ref);
+	} catch (err) {
+		fail(err instanceof Error ? err.message : String(err));
+	}
+	const result = unitInbox({ store: ctx.store }, {
+		meId: unit.id,
+		unread: opts.unread,
+		from: opts.from,
+		thread: opts.thread
+	});
+	const unreadCount = result.messages.filter((m) => !m.read).length;
+	const summary = result.mailbox === "none" ? "no mailbox" : result.mailbox === "unreadable" ? `mailbox unreadable: ${result.error}` : `${result.messages.length} messages (${unreadCount} unread)`;
+	emit(formatOf(opts), {
+		toon: [toonObject({
+			unit: unit.id,
+			handle: unit.handle,
+			mailbox: result.mailbox
+		}), toonList("messages", result.messages, [
+			{
+				key: "id",
+				get: (m) => m.id
+			},
+			{
+				key: "from",
+				get: (m) => m.fromHandle
+			},
+			{
+				key: "subject",
+				get: (m) => m.subject ?? ""
+			},
+			{
+				key: "read",
+				get: (m) => m.read
+			}
+		], summary)].join("\n"),
+		json: {
+			unit: unit.id,
+			handle: unit.handle,
+			...result
+		}
+	});
+	if (result.mailbox === "unreadable") {
+		console.error(JSON.stringify({ error: `mailbox of ${unit.id} is unreadable: ${result.error}` }));
+		process.exitCode = 1;
+	}
+}
 function runInbox(opts) {
 	const ctx = ctxOf(opts);
 	touch(ctx);
+	if (opts.unit) {
+		emitUnitInbox(ctx, opts, opts.unit);
+		return;
+	}
 	emitInbox(ctx, opts, opts.owner ? resolveOwnerMailbox(ctx.store, opts.owner) : requireSelf(ctx), "cyberlegion mail read");
 }
-withGlobals(mail.command("inbox")).description("list your mail").option("--unread", "only un-acked mail").option("--from <id>", "filter by sender").option("--thread <id>", "filter to messages carrying this thread id").option("--owner <handle>", "target a standing owner's mailbox instead of this session's own").action(runInbox);
+withGlobals(mail.command("inbox")).description("list your mail").option("--unread", "only un-acked mail").option("--from <id>", "filter by sender").option("--thread <id>", "filter to messages carrying this thread id").option("--owner <handle>", "target a standing owner's mailbox instead of this session's own").addOption(new Option("--unit <handle|id>", "list another unit's mailbox read-only (exited units too); never acks, reports mailbox: none|present|unreadable").conflicts("owner")).action(runInbox);
 withGlobals(mail.command("read")).description("read a message; --ack consumes it in the same step, otherwise it only peeks").argument("<msg-id>", "message id").option("--ack", "acknowledge the message in the same step (idempotent — no error if already acked)").option("--owner <handle>", "read a standing owner's mailbox instead of this session's own").action((msgId, opts) => {
 	const ctx = ctxOf(opts);
 	const meId = opts.owner ? resolveOwnerMailbox(ctx.store, opts.owner) : requireSelf(ctx);

package/dist/index.d.mts

@@ -162,6 +162,8 @@ interface MailboxStore {
   putMessage(toId: string, msg: Message): void;
   /** The full unread/read split for one agent's inbox. */
   listInbox(id: string): InboxSnapshot;
+  /** Whether `id` has a mailbox at all — one exists once mail was first delivered to it. */
+  hasMailbox(id: string): boolean;
   /** Ack a message by moving it out of the unread set; throws if it is not currently unread. */
   ackMessage(id: string, msgId: string): Message;
   /** Permanently remove a message (unread or already-acked) from `id`'s inbox; throws if absent. */
@@ -864,6 +866,7 @@ export declare class FileStore implements Store {
   ensureMarker(): void;
   putMessage(toId: string, msg: Message): void;
   listInbox(id: string): InboxSnapshot;
+  hasMailbox(id: string): boolean;
   ackMessage(id: string, msgId: string): Message;
   removeMessage(id: string, msgId: string): void;
   removeMailbox(id: string): void;

package/dist/index.mjs

@@ -599,6 +599,10 @@ function readShape(rows, shape) {
 	}
 	return { kind: "unknown" };
 }
+/** Whether this reader knows `harness`'s input box, so a missing box on screen means it is not drawn yet. */
+function knowsPromptOf(harness) {
+	return harness !== void 0 && SHAPES[harness] !== void 0;
+}
 /**
 * Read the input box off `screen` — a plain-text scrape of the pane — with the shape of `harness`,
 * or, when the harness is not known, with each known shape in turn until one recognizes the box.
@@ -699,6 +703,27 @@ function copiesOn(screen, message) {
 	return screen.split("\n").filter((row) => row.replace(/\s+/g, " ").includes(needle)).length;
 }
 /**
+* Read `screen` for the ring: whether `message` sits in the input box, and how many copies of it
+* are on screen outside the box. With the box read by its harness's shape, copies inside the box are
+* left out of the count: a booting harness can take several typed copies as one paste, and those
+* copies are staged text, not posted turns. A screen with no input box the reader knows falls back to
+* cyber-mux's `isStaged`, and the box's copy is counted with the rest.
+*/
+function readRing(screen, message, harness) {
+	const box = screen ? readPrompt(screen, harness) : { kind: "unknown" };
+	if (box.kind === "unknown") return {
+		boxKnown: false,
+		staged: isStaged(screen, message),
+		outside: copiesOn(screen, message)
+	};
+	const inBox = box.kind === "draft" ? copiesOn(box.text, message) : 0;
+	return {
+		boxKnown: true,
+		staged: inBox > 0,
+		outside: copiesOn(screen, message) - inBox
+	};
+}
+/**
 * Submit `message` to `target` as a taken turn: cyber-mux's `nudge`, with one more way to see that the
 * turn was taken.
 *
@@ -718,18 +743,32 @@ function copiesOn(screen, message) {
 * queue. Text that is neither staged nor posted is lost: after one more settle for a slow redraw, it
 * is typed again. It is opt-in because it needs the posted copy to stay on screen: a busy peer's
 * output can scroll earlier copies away, so a ring to it could read as lost and be typed twice.
+*
+* With `requirePosted` and a harness whose input box this reader knows, nothing is typed until the
+* harness has drawn that box, for up to the
+* whole retry budget. Keys typed while a harness boots are buffered, and the harness takes them as one
+* paste once it draws the box: each Enter becomes a newline, so re-typed copies pile up in the box
+* unsent. A box that never shows within the budget is typed into anyway, as before.
+*
+* Where the input box can be read, copies of the text inside it are not counted as posted: only a
+* copy outside the box means the harness took the turn.
 */
 async function ringTurn(adapter, exec, target, message, opts = {}) {
 	const attempts = opts.attempts ?? DEFAULT_ATTEMPTS;
 	const settleMs = opts.settleMs ?? DEFAULT_SETTLE_MS;
 	const sleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
 	if (!adapter.paneExists(exec, target)) throw new Error(`nudge failed: pane ${target.id} no longer exists — the peer's session is gone, not busy.`);
-	const before = copiesOn(adapter.read(exec, target).text, message);
+	let first = adapter.read(exec, target).text;
+	if (opts.requirePosted && knowsPromptOf(opts.harness)) for (let wait = 0; wait < attempts && !readRing(first, message, opts.harness).boxKnown; wait++) {
+		await sleep(settleMs);
+		first = adapter.read(exec, target).text;
+	}
+	const before = readRing(first, message, opts.harness).outside;
 	const check = () => {
-		const screen = adapter.read(exec, target).text;
-		const copies = copiesOn(screen, message);
-		if (isStaged(screen, message)) return copies >= before + 2 ? "taken" : "staged";
-		return copies > before || !opts.requirePosted ? "taken" : "lost";
+		const seen = readRing(adapter.read(exec, target).text, message, opts.harness);
+		const posted = seen.outside >= before + (seen.boxKnown || !seen.staged ? 1 : 2);
+		if (seen.staged) return posted ? "taken" : "staged";
+		return posted || !opts.requirePosted ? "taken" : "lost";
 	};
 	adapter.submit(exec, target, message);
 	await sleep(settleMs);
@@ -829,7 +868,8 @@ async function wakeSpawn(getAdapter, exec, input, nudgeOpts = SPAWN_NUDGE_OPTS,
 		const doorbell = (input.resumed ? resumeDoorbell : spawnDoorbell)(input.briefPath);
 		await withDraftGuard(adapter, exec, input.target, () => ringTurn(adapter, exec, input.target, doorbell, {
 			...nudgeOpts,
-			requirePosted: true
+			requirePosted: true,
+			harness: input.harness
 		}), {
 			...guardOpts,
 			harness: input.harness,
@@ -2857,6 +2897,10 @@ var FileStore = class {
 			read: read ? readMessages(read) : []
 		};
 	}
+	hasMailbox(id) {
+		const dir = readPathOrUndefined(() => paths.inboxDir(this.root, id));
+		return dir !== void 0 && existsSync(dir);
+	}
 	ackMessage(id, msgId) {
 		const src = readPathOrUndefined(() => paths.messageFile(this.root, id, msgId));
 		if (!src || !existsSync(src)) throw new Error(`"${msgId}" is not an unread message in this inbox`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",

package/plugin.json

@@ -1,7 +1,7 @@
 {
 	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
 	"name": "cyberlegion",
-	"version": "1.8.0",
+	"version": "1.9.0",
 	"description": "Agent session spawning, messaging, and dispatch — the Legion and its Legate.",
 	"author": {
 		"name": "unional"

package/skills/dispatch-governance/SKILL.md

@@ -17,7 +17,7 @@ satisfies verdict schema `V`.
 > **Running the CLI.** Every `node scripts/cyberlegion.mjs …` command below runs the `cyberlegion` CLI
 > this plugin ships. The path is relative to this skill's own directory, not the working directory.
 > If you cannot resolve it, run the published CLI of the version that shipped this skill instead,
-> with the same arguments: `npx -y cyberlegion@1.8.0`.
+> with the same arguments: `npx -y cyberlegion@1.9.0`.
 
 ## 1. Resolve the agent definition