cyberlegion 0.3.0 → 0.3.2

package/dist/cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { A as bumpLastSeen, B as registerStanding, C as nudgeUnit, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, G as resolveStandingOwner, H as resolvePresence, I as prune, J as listAgentDefs, K as touch, L as realExec, M as clearPresence, N as detectHarness, O as DELIVERY_DOORBELL, P as listAgents, R as reconcile, S as focusUnit, V as resolveAgent, W as resolveSelfId, Y as resolveAgentDef, _ as install, a as emit, b as resolveSpawnLaunch, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, j as claimPresence, k as wakeRecipient, l as toonObject, m as readAck, n as awaitReply, o as fail, p as peek, q as normalizeMuxEnv, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, w as readUnit, x as clearUnit, z as register } from "./watch-BZmEAqUo.mjs";
+import { A as bumpLastSeen, B as registerStanding, C as nudgeUnit, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, G as resolveStandingOwner, H as resolvePresence, I as prune, J as listAgentDefs, K as touch, L as realExec, M as clearPresence, N as detectHarness, O as DELIVERY_DOORBELL, P as listAgents, R as reconcile, S as focusUnit, V as resolveAgent, W as resolveSelfId, Y as resolveAgentDef, _ as install, a as emit, b as resolveSpawnLaunch, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, j as claimPresence, k as wakeRecipient, l as toonObject, m as readAck, n as awaitReply, o as fail, p as peek, q as normalizeMuxEnv, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, w as readUnit, x as clearUnit, z as register } from "./watch-D33fQcUI.mjs";
+import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { Command, Option } from "commander";
 import { currentPane, probeMultiplexer } from "cyber-mux";
@@ -74,7 +75,7 @@ function readCommandOutput(format, result) {
 }
 //#endregion
 //#region src/cli.ts
-const VERSION = "0.0.0";
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 function ctxOf(opts) {
 	return {
 		store: new FileStore(resolveRoot({ space: opts.space })),

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import { Exec, Exec as Exec$1, MuxAdapter, MuxPlacement, MuxProbe, NudgeOptions, probeMultiplexer } from "cyber-mux";
 import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
-
 //#region src/store/store.d.ts
 interface Message {
   id: string;
@@ -103,6 +102,15 @@ interface Store {
   setMainPane(pane: string | null): void;
   /** The hub's currently bound main pane, or undefined when none is bound. */
   getMainPane(): string | undefined;
+  /** Run `fn` while holding an exclusive, named advisory lock scoped to this store's root —
+   * mutual exclusion for a genuine read-modify-write (read current state, decide, write back),
+   * which an atomic single-file write alone can't make safe against a concurrent racer. Blocks
+   * until acquired or throws `LockTimeoutError` (`store/lock.ts`) after a bounded wait; never
+   * steals a lock a live holder still holds — only one abandoned by a confirmed-dead process.
+   * `setMainPane` uses this internally; callers doing their own load-mutate-save against this
+   * store (e.g. a standing record's presence rebind) should hold the SAME named lock around that
+   * whole sequence, not just around the final write. */
+  withLock<T>(name: string, fn: () => T): T;
 }
 //#endregion
 //#region src/identity.d.ts
@@ -364,6 +372,11 @@ declare const paths: {
   dataDir: (root: string, id: string) => string;
   briefFile: (root: string, id: string) => string;
   mainPaneFile: (root: string) => string;
+  /** A message's file path within `toId`'s unread/read inbox dir, keyed by its own collision-free
+   * id — validated the same as an agent id (it's the same class of risk: a peer- or CLI-controlled
+   * string becoming a filename). */
+  messageFile: (root: string, toId: string, msgId: string) => string;
+  messageReadFile: (root: string, toId: string, msgId: string) => string;
 };
 //#endregion
 //#region src/session.d.ts
@@ -453,6 +466,7 @@ declare class FileStore implements Store {
   readBrief(agentId: string): string | undefined;
   setMainPane(pane: string | null): void;
   getMainPane(): string | undefined;
+  withLock<T>(name: string, fn: () => T): T;
 }
 //#endregion
 //#region src/wake/await.d.ts

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { $ as resolveProjectLocalRoot, A as bumpLastSeen, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, I as prune, J as listAgentDefs, K as touch, L as realExec, N as detectHarness, P as listAgents, Q as projectRoot, T as spawn, U as resolveRecipient, V as resolveAgent, W as resolveSelfId, X as ensureMarker, Y as resolveAgentDef, Z as paths, _ as install, a as emit, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, l as toonObject, n as awaitReply, o as fail, p as peek, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, y as realizeLaunch, z as register } from "./watch-BZmEAqUo.mjs";
+import { $ as resolveProjectLocalRoot, A as bumpLastSeen, D as selectSessionAdapter, E as spawnAndWake, F as loadAgent, I as prune, J as listAgentDefs, K as touch, L as realExec, N as detectHarness, P as listAgents, Q as projectRoot, T as spawn, U as resolveRecipient, V as resolveAgent, W as resolveSelfId, X as ensureMarker, Y as resolveAgentDef, Z as paths, _ as install, a as emit, c as toonList, d as deleteMessage, et as resolveRoot, f as inbox, g as send, h as resolveBody, i as injectInbox, l as toonObject, n as awaitReply, o as fail, p as peek, r as FileStore, s as nextStep, t as watchMail, u as ack, v as decommission, y as realizeLaunch, z as register } from "./watch-D33fQcUI.mjs";
 import { probeMultiplexer } from "cyber-mux";
 import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
 export { FileStore, ack, assertDistinctFromPrimary, awaitReply, bumpLastSeen, decommission, deleteMessage, detectHarness, emit, ensureMarker, fail, gitWorktreeAdapter, inbox, injectInbox, install, listAgentDefs, listAgents, loadAgent, nextStep, paths, peek, probeMultiplexer, projectRoot, prune, realExec, realizeLaunch, register, resolveAgent, resolveAgentDef, resolveBody, resolvePrimaryRoot, resolveProjectLocalRoot, resolveRecipient, resolveRoot, resolveSelfId, selectSessionAdapter, send, spawn, spawnAndWake, toonList, toonObject, touch, watchMail };

package/dist/{watch-BZmEAqUo.mjs → watch-D33fQcUI.mjs}

@@ -1,6 +1,6 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { callerPane, currentPane, herdrMuxAdapter, nodeExec, nudge, probeMultiplexer, tmuxMuxAdapter } from "cyber-mux";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { assertDistinctFromPrimary, gitWorktreeAdapter, resolvePrimaryRoot } from "cyber-mux/worktree";
@@ -75,16 +75,55 @@ function ensureMarker(root) {
 	const marker = join(root, MARKER_FILE);
 	if (!existsSync(marker)) writeFileSync(marker, `${JSON.stringify({ version: 1 }, null, 2)}\n`);
 }
+/**
+* Thrown when an agent/message id destined to become a filename PATH SEGMENT fails
+* `assertSafeId` — see that function's doc for why this rejects rather than encodes.
+*/
+var InvalidIdError = class extends Error {
+	kind;
+	value;
+	constructor(kind, value) {
+		super(`invalid ${kind} ${JSON.stringify(value)} — must not be empty, ".", "..", or contain a path separator`);
+		this.kind = kind;
+		this.value = value;
+		this.name = "InvalidIdError";
+	}
+};
+const UNSAFE_ID = /[\\/\0]/;
+/**
+* Filename-safety guard for any id that becomes a bare PATH SEGMENT under the hub root — agent ids
+* (`agentFile`/`inboxDir`/`dataDir`/`briefFile`) and message ids (`messageFile`). Both are
+* effectively user/peer-controlled: an agent id round-trips a caller-supplied `--handle`-adjacent
+* value in some flows, and nothing upstream of the store validates it before it reaches a `join()`.
+*
+* REJECT, don't encode: unlike `sanitizePane` (which deliberately encodes, because a tmux/herdr pane
+* locator is an opaque, internally-produced token that only needs to survive as a *lookup key*, not
+* round-trip as an identity), an agent/message id is a PRIMARY KEY — `getAgent(id)` must return
+* exactly what `putAgent` stored under that same `id`. Silently encoding two different malformed ids
+* onto the same sanitized filename would let one caller's write silently clobber or read another's
+* record — a worse failure than a loud, immediate refusal. So: empty, `.`, `..`, and any embedded
+* path separator (POSIX `/`, Windows `\`) or NUL byte are rejected outright, which also rejects an
+* absolute path outright (an absolute path always contains a separator).
+*/
+function assertSafeId(id, kind) {
+	if (!id || id === "." || id === ".." || UNSAFE_ID.test(id)) throw new InvalidIdError(kind, id);
+	return id;
+}
 const paths = {
 	agentsDir: (root) => join(root, "agents"),
-	agentFile: (root, id) => join(root, "agents", `${id}.json`),
+	agentFile: (root, id) => join(root, "agents", `${assertSafeId(id, "agent id")}.json`),
 	panesDir: (root) => join(root, "panes"),
 	paneFile: (root, pane) => join(root, "panes", `${sanitizePane(pane)}.id`),
-	inboxDir: (root, id) => join(root, "inbox", id),
-	inboxReadDir: (root, id) => join(root, "inbox", id, "read"),
-	dataDir: (root, id) => join(root, "data", id),
-	briefFile: (root, id) => join(root, "data", id, "brief.md"),
-	mainPaneFile: (root) => join(root, "main-pane.id")
+	inboxDir: (root, id) => join(root, "inbox", assertSafeId(id, "agent id")),
+	inboxReadDir: (root, id) => join(root, "inbox", assertSafeId(id, "agent id"), "read"),
+	dataDir: (root, id) => join(root, "data", assertSafeId(id, "agent id")),
+	briefFile: (root, id) => join(root, "data", assertSafeId(id, "agent id"), "brief.md"),
+	mainPaneFile: (root) => join(root, "main-pane.id"),
+	/** A message's file path within `toId`'s unread/read inbox dir, keyed by its own collision-free
+	* id — validated the same as an agent id (it's the same class of risk: a peer- or CLI-controlled
+	* string becoming a filename). */
+	messageFile: (root, toId, msgId) => join(paths.inboxDir(root, toId), `${assertSafeId(msgId, "message id")}.json`),
+	messageReadFile: (root, toId, msgId) => join(paths.inboxReadDir(root, toId), `${assertSafeId(msgId, "message id")}.json`)
 };
 /**
 * Where a spawned unit's own git worktree is checked out by default — a sibling of the primary
@@ -441,14 +480,18 @@ function resolveStandingOwner(store, handle) {
 * multiplexer never touches the pointer. Last claim wins: a plain overwrite, no merge.
 */
 function claimPresence(ctx, handle) {
-	const rec = loadAgent(ctx.store, resolveStandingOwner(ctx.store, handle));
-	if (!rec) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
+	const standingId = resolveStandingOwner(ctx.store, handle);
+	if (!loadAgent(ctx.store, standingId)) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
 	if (probeMultiplexer(ctx.exec ?? realExec, normalizeMuxEnv(ctx.env ?? process.env)).mux === "none") throw new Error("claiming a presence needs a multiplexer to open panes");
 	const selfId = resolveSelfId(ctx);
 	if (!selfId) throw new Error("no identity in this session — run `cyberlegion unit register` first");
-	rec.presence = selfId;
-	saveAgent(ctx.store, rec);
-	return rec;
+	return ctx.store.withLock(`presence:${standingId}`, () => {
+		const rec = loadAgent(ctx.store, standingId);
+		if (!rec) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
+		rec.presence = selfId;
+		saveAgent(ctx.store, rec);
+		return rec;
+	});
 }
 /**
 * Unbind a standing owner's presence. The unknown-handle throw (via `resolveStandingOwner`) wins
@@ -457,13 +500,17 @@ function claimPresence(ctx, handle) {
 * reporting a clear it never performed.
 */
 function clearPresence(ctx, handle) {
-	const rec = loadAgent(ctx.store, resolveStandingOwner(ctx.store, handle));
-	if (!rec) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
-	if (rec.presence !== void 0) {
-		rec.presence = void 0;
-		saveAgent(ctx.store, rec);
-	}
-	return rec;
+	const standingId = resolveStandingOwner(ctx.store, handle);
+	if (!loadAgent(ctx.store, standingId)) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
+	return ctx.store.withLock(`presence:${standingId}`, () => {
+		const rec = loadAgent(ctx.store, standingId);
+		if (!rec) throw new Error(`no standing owner "${handle}" — run 'cyberlegion unit register --standing --handle ${handle}'`);
+		if (rec.presence !== void 0) {
+			rec.presence = void 0;
+			saveAgent(ctx.store, rec);
+		}
+		return rec;
+	});
 }
 /**
 * The live-only presence rule, keyed off a standing record the caller ALREADY HOLDS — the pointer
@@ -532,7 +579,7 @@ function touch(ctx) {
 	const id = resolveSelfId(ctx);
 	if (id) bumpLastSeen(ctx, id);
 }
-const STALE_MS = 900 * 1e3;
+const STALE_MS = 9e5;
 /** The per-mux session adapters `prune` consults for pane liveness — each answers with its own
 * backend primitive so a herdr pane is never probed with a tmux query, and vice versa. */
 const PANE_ADAPTERS = {
@@ -778,25 +825,8 @@ function selectSessionAdapter(env, exec = realExec) {
 }
 //#endregion
 //#region src/workspace-label.ts
-/**
-* Workspace labels — the short, human-scannable name a `workspace` placement opens under.
-*
-* A unit's own visible space is what a human scans to find a session, so a bare backend default
-* ("workspace 4") costs a search every time. A label is `<code>-<subject>`, capped at 30 characters
-* INCLUDING the code, so it stays readable in a sidebar/status bar at a glance.
-*
-* The code is a NieR YoRHa unit class picked from the brief's leading action word in one fixed
-* order, so the same brief always yields the same code:
-*   - `A2-` — the action tears down or reverts (A2 is the rogue/attack unit)
-*   - `9S-` — the action is read-only recon (9S is the Scanner)
-*   - `2B-` — everything else: build-and-change work, the default (2B is the battle unit)
-*/
-/** Total label budget, code included. */
-const LABEL_CAP = 30;
-/** Every code is the same width, so the subject budget is a constant. */
-const CODE_WIDTH = 3;
 /** Leading actions that tear down or revert — the `A2-` class, checked first. */
-const TEARDOWN_ACTIONS = new Set([
+const TEARDOWN_ACTIONS = /* @__PURE__ */ new Set([
 	"clean",
 	"cleanup",
 	"decommission",
@@ -817,7 +847,7 @@ const TEARDOWN_ACTIONS = new Set([
 	"unregister"
 ]);
 /** Leading actions that only look and report — the `9S-` class, checked after teardown. */
-const RECON_ACTIONS = new Set([
+const RECON_ACTIONS = /* @__PURE__ */ new Set([
 	"analyze",
 	"assess",
 	"audit",
@@ -852,7 +882,7 @@ const RECON_ACTIONS = new Set([
 * dropped from it (the code already says "build"), an unrecognized leading word is kept (it is the
 * subject's own first noun, and dropping it would strip real signal).
 */
-const BUILD_ACTIONS = new Set([
+const BUILD_ACTIONS = /* @__PURE__ */ new Set([
 	"add",
 	"backfill",
 	"build",
@@ -882,7 +912,7 @@ const BUILD_ACTIONS = new Set([
 	"write"
 ]);
 /** Dropped when it leads the subject — an article carries no identifying signal. */
-const LEADING_ARTICLES = new Set([
+const LEADING_ARTICLES = /* @__PURE__ */ new Set([
 	"a",
 	"an",
 	"the"
@@ -910,7 +940,7 @@ function deriveWorkspaceLabel(input) {
 		subjectWords = leadIsAction ? briefWords.slice(1) : briefWords.slice();
 		if (subjectWords[0] && LEADING_ARTICLES.has(subjectWords[0])) subjectWords.shift();
 	}
-	const subject = fitWords(subjectWords, LABEL_CAP - CODE_WIDTH) || input.id.slice(0, 6);
+	const subject = fitWords(subjectWords, 27) || input.id.slice(0, 6);
 	return `${code}${subject}`;
 }
 /** The brief's first line with any content — a leading blank line is not the subject. */
@@ -962,7 +992,7 @@ const RESET_MAP = {
 * honest fresh-context command for these, so they are refused explicitly rather than lumped in
 * with a harness that is merely unmapped.
 */
-const FALSE_FRIEND_HARNESSES = new Set(["gemini"]);
+const FALSE_FRIEND_HARNESSES = /* @__PURE__ */ new Set(["gemini"]);
 /**
 * Resolve `harness`'s own fresh-context command from the reset map. String-keyed (not `Harness`)
 * so it also guards a harness present in `LAUNCH_MAP`/`identity.ts`'s `Harness` union but not yet
@@ -1199,7 +1229,7 @@ async function nudgeUnit(ctx, ref, options = {}) {
 function readUnit(ctx, ref, options = {}) {
 	const { agent, target } = paneTargetOf(ctx, ref);
 	const exec = ctx.exec ?? realExec;
-	const output = selectSessionAdapter(ctx.env ?? process.env, exec).read(exec, target, { lines: options.lines });
+	const output = selectSessionAdapter(ctx.env ?? process.env, exec).read(exec, target, { lines: options.lines }).text;
 	return {
 		agent,
 		pane: target.id,
@@ -1592,18 +1622,236 @@ function injectInbox(ctx, event) {
 	} };
 }
 //#endregion
+//#region src/store/errors.ts
+/** A record file exists but its content didn't parse as JSON — a torn write (crash mid-`writeFileSync`,
+* pre-atomic-write code path) or on-disk tampering. Carries the file path and the original parse
+* error so a caller can report exactly what's broken and where, rather than "Unexpected token" with
+* no location. */
+var CorruptRecordError = class extends Error {
+	file;
+	constructor(file, cause) {
+		super(`corrupt record at "${file}": ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		this.file = file;
+		this.name = "CorruptRecordError";
+	}
+};
+//#endregion
+//#region src/store/process-liveness.ts
+/**
+* Probe whether `pid` is alive using `process.kill(pid, 0)` — the POSIX "does this process exist"
+* idiom; it sends no signal, it only tests deliverability. `ESRCH` (no such process) is the only
+* errno that means "definitely dead". Every other errno — `EPERM` above all, common under sandboxes
+* and containers where a genuinely live process can be unsignalable by this one, or any process
+* owned by a different uid — reads as `'unknown'`, never `'dead'`: collapsing `EPERM` into "dead" is
+* exactly the defect this three-state return exists to make structurally impossible to reintroduce
+* at a new call site. Same-pid is trivially `'alive'` (a process checking its own prior identity,
+* e.g. after a crash-and-restart that reused nothing).
+*/
+function probeProcess(pid) {
+	if (pid === process.pid) return "alive";
+	try {
+		process.kill(pid, 0);
+		return "alive";
+	} catch (err) {
+		return err.code === "ESRCH" ? "dead" : "unknown";
+	}
+}
+//#endregion
+//#region src/store/lock.ts
+var LockTimeoutError = class extends Error {
+	name;
+	constructor(name) {
+		super(`timed out waiting for lock "${name}"`);
+		this.name = name;
+		this.name = "LockTimeoutError";
+	}
+};
+function locksDir(root) {
+	return join(root, "locks");
+}
+function lockDirFor(root, name) {
+	return join(locksDir(root), `${name}.lock`);
+}
+/** Read a lock dir's recorded holder. Absent/corrupt/mid-acquire (holder.json not written yet) all
+* read as "unknown" — never grounds to steal. An ambiguous read must never look like a green light. */
+function readHolder(dir) {
+	try {
+		return JSON.parse(readFileSync(join(dir, "holder.json"), "utf8"));
+	} catch {
+		return;
+	}
+}
+/** Locking's policy on `probeProcess`'s `'unknown'` state: treat it exactly like `'alive'` — i.e.
+* NOT `'dead'`. The one invariant that must never break here is stealing a lock a live holder still
+* holds, and `'unknown'` means "cannot rule out alive", so it can only ever be safe to fold it into
+* the "do not steal" side. This is a local policy decision, not `probeProcess`'s — a different call
+* site (a staleness reaper, say) folding `'unknown'` into "not provably alive" instead would be
+* reading the SAME three states toward the opposite default, which is exactly the bug class this
+* three-state type exists to force each call site to decide explicitly (see process-liveness.ts). */
+function heldByLiveOrUnknownPid(pid) {
+	return probeProcess(pid) !== "dead";
+}
+function sleepSync(ms) {
+	if (ms <= 0) return;
+	Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+* Attempt to reclaim an abandoned lock dir without ever discarding a LIVE one out from under its
+* holder — the exact defect agmsg/firstmate's lock suites exist to catch (evidence.md items 3-4).
+*
+* `mkdirSync` on the lock path itself already arbitrates ordinary contention (EEXIST = someone else
+* got there first); the harder race is a STEAL: two processes independently deciding the same lock
+* looks dead. `renameSync` gives the same exclusivity `mkdirSync` gives for a fresh path, but for an
+* EXISTING one — of any number of processes racing to rename the SAME source path away, exactly one
+* succeeds and the rest get ENOENT. So the rename-away is the sole arbiter of "who gets to attempt
+* the steal", not the earlier staleness read.
+*
+* That still leaves one race: the content we read as stale might not be the content we actually
+* capture, if the true holder released and a NEW, live holder re-acquired at this same path between
+* our staleness read and our rename. So after winning the rename, re-check the pid we ACTUALLY
+* captured (not the one from the earlier read) — if it's alive, this was a live lock we grabbed by
+* accident; put it back immediately (best-effort — if a third party has since re-mkdir'd the path,
+* the invariant we're protecting already holds, so just drop our capture) and refuse to finalize.
+*/
+function tryReclaimStale(dir) {
+	const grave = `${dir}.stale-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+	try {
+		renameSync(dir, grave);
+	} catch (err) {
+		if (err.code === "ENOENT") return false;
+		throw err;
+	}
+	const captured = readHolder(grave);
+	if (captured && heldByLiveOrUnknownPid(captured.pid)) {
+		try {
+			renameSync(grave, dir);
+		} catch {
+			rmSync(grave, {
+				recursive: true,
+				force: true
+			});
+		}
+		return false;
+	}
+	rmSync(grave, {
+		recursive: true,
+		force: true
+	});
+	return true;
+}
+/**
+* Acquire an advisory, mkdir-based lock at `root/locks/<name>.lock`. mkdir (not O_EXCL on a file) is
+* the primitive here because a lock also needs to carry its holder metadata (pid + timestamp) for
+* staleness detection, and a directory gives that a natural home (`holder.json` inside it) without a
+* second file to keep in sync; `mkdirSync` on a non-existent path is exactly as atomic as an
+* exclusive file create on every filesystem this tool targets (POSIX; NTFS via Node's Win32 mkdir).
+*
+* Blocks (busy-retries) until acquired or `timeoutMs` elapses, reclaiming a dead holder's lock along
+* the way (see `tryReclaimStale`) but NEVER a live one — contention with a live holder always waits
+* it out or times out, never steals.
+*/
+function acquireLock(root, name, opts = {}) {
+	const retryDelayMs = opts.retryDelayMs ?? 20;
+	const timeoutMs = opts.timeoutMs ?? 5e3;
+	const dir = lockDirFor(root, name);
+	mkdirSync(locksDir(root), { recursive: true });
+	const deadline = Date.now() + timeoutMs;
+	for (;;) try {
+		mkdirSync(dir);
+		writeFileSync(join(dir, "holder.json"), JSON.stringify({
+			pid: process.pid,
+			acquiredAt: Date.now()
+		}));
+		return { release: () => rmSync(dir, {
+			recursive: true,
+			force: true
+		}) };
+	} catch (err) {
+		if (err.code !== "EEXIST") throw err;
+		const holder = readHolder(dir);
+		if (holder && !heldByLiveOrUnknownPid(holder.pid) && tryReclaimStale(dir)) continue;
+		if (Date.now() > deadline) throw new LockTimeoutError(name);
+		sleepSync(retryDelayMs);
+	}
+}
+/** Acquire `name`, run `fn`, and always release — the shape every genuine read-modify-write in the
+* store should use (`setMainPane`, `identity.ts`'s `claimPresence`/`clearPresence` today). */
+function withLock(root, name, fn, opts) {
+	const handle = acquireLock(root, name, opts);
+	try {
+		return fn();
+	} finally {
+		handle.release();
+	}
+}
+//#endregion
 //#region src/store/file-store.ts
+/** Parse a record file's content, wrapping a `JSON.parse` failure in a typed, file-named
+* `CorruptRecordError` instead of letting a bare `SyntaxError` bubble up from deep inside
+* `listInbox`/`listAgents`/`getAgent` with no indication of WHICH file broke. A file that doesn't
+* exist is a caller error — callers check existence first, so this only ever sees files known to
+* be present but possibly torn (a crash mid-write predating the atomic-write fix, or on-disk
+* tampering) — see evidence.md item 5, "no silent success on a broken store". */
+function readJsonRecord(file) {
+	const raw = readFileSync(file, "utf8");
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new CorruptRecordError(file, err);
+	}
+}
 function readMessages(dir) {
 	if (!existsSync(dir)) return [];
-	return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync(join(dir, f), "utf8")));
+	return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => readJsonRecord(join(dir, f)));
+}
+/** Write `data` to `file` crash-safely: write to a sibling temp file first, then `renameSync` into
+* place. `rename` is atomic within a filesystem (POSIX guarantees this; Node's Win32 rename is too
+* for same-volume paths, which every path here is — always under the same store root), so any
+* reader either sees the OLD complete content or the NEW complete content, never a truncated
+* in-between. Before this fix, `putMessage`/`putAgent`/`putPaneIndex`/`setMainPane` called
+* `writeFileSync` directly on the final path — only `ackMessage`'s move (a rename of an already-
+* complete file) was atomic. A process crashing mid-`writeFileSync`, or a reader racing a writer on
+* a large record, could hand `JSON.parse` a truncated file and throw an uncaught `SyntaxError` deep
+* inside `listInbox`/`listAgents`/`getAgent`.
+*
+* Deliberately no `fsync` before the rename: this tool defends against a process CRASHING mid-write
+* (the actual, observed risk in a daemonless multi-process CLI), where the page cache alone is
+* sufficient, not against a power-loss/OS-crash losing unflushed pages, which cyberlegion doesn't
+* claim to survive today (no writer here holds data the user can't just re-send). Add fsync if that
+* durability bar ever changes.
+*
+* The temp name embeds pid + a counter so two writers to the SAME final path never collide on their
+* own temp files mid-write (each writer's temp file is unique to it). */
+let tmpCounter = 0;
+function writeFileAtomic(file, data) {
+	mkdirSync(dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.${tmpCounter++}.tmp`;
+	writeFileSync(tmp, data);
+	renameSync(tmp, file);
 }
 function writeJson(file, data) {
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+	writeFileAtomic(file, `${JSON.stringify(data, null, 2)}\n`);
 }
 function writeText(file, text) {
-	mkdirSync(dirname(file), { recursive: true });
-	writeFileSync(file, text);
+	writeFileAtomic(file, text);
+}
+/** Build a path via `build()` for a READ-only lookup, treating a syntactically-invalid id
+* (`InvalidIdError`) the same as "not found" rather than throwing. Reads are the wrong place to
+* enforce id-shape: `resolveAgent`/`resolveRecipient` (identity.ts) speculatively probe an arbitrary
+* ref — which may legitimately be a worktree BRANCH NAME containing `/` — as a candidate id before
+* falling back to handle/branch lookup, so `getAgent('cyberlegion/unit-abc')` must fail soft, not
+* throw, or that fallback chain breaks. The traversal risk this guards against (an id escaping the
+* store root) only bites on a WRITE — nothing is ever created or overwritten by a probe that finds
+* nothing — so a hard reject stays reserved for the write paths below (`putAgent`, `putMessage`,
+* `putPaneIndex`, `writeBrief`), where a malformed id would otherwise put a stray file wherever it
+* pointed. */
+function readPathOrUndefined(build) {
+	try {
+		return build();
+	} catch (err) {
+		if (err instanceof InvalidIdError) return void 0;
+		throw err;
+	}
 }
 /** The on-disk `Store` implementation — current per-writer sharded `.json` layout (ADR-0020):
 * one file per message/agent, collision-free filenames, ack = atomic rename into `read/`. */
@@ -1616,33 +1864,33 @@ var FileStore = class {
 		ensureMarker(this.root);
 	}
 	putMessage(toId, msg) {
-		const dir = paths.inboxDir(this.root, toId);
-		mkdirSync(dir, { recursive: true });
-		writeFileSync(join(dir, `${msg.id}.json`), `${JSON.stringify(msg, null, 2)}\n`);
+		writeFileAtomic(paths.messageFile(this.root, toId, msg.id), `${JSON.stringify(msg, null, 2)}\n`);
 	}
 	listInbox(id) {
+		const inbox = readPathOrUndefined(() => paths.inboxDir(this.root, id));
+		const read = readPathOrUndefined(() => paths.inboxReadDir(this.root, id));
 		return {
-			unread: readMessages(paths.inboxDir(this.root, id)),
-			read: readMessages(paths.inboxReadDir(this.root, id))
+			unread: inbox ? readMessages(inbox) : [],
+			read: read ? readMessages(read) : []
 		};
 	}
 	ackMessage(id, msgId) {
-		const src = join(paths.inboxDir(this.root, id), `${msgId}.json`);
-		if (!existsSync(src)) throw new Error(`"${msgId}" is not an unread message in this inbox`);
-		const msg = JSON.parse(readFileSync(src, "utf8"));
-		const dir = paths.inboxReadDir(this.root, id);
-		mkdirSync(dir, { recursive: true });
-		renameSync(src, join(dir, `${msgId}.json`));
+		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`);
+		const msg = readJsonRecord(src);
+		const dest = paths.messageReadFile(this.root, id, msgId);
+		mkdirSync(dirname(dest), { recursive: true });
+		renameSync(src, dest);
 		return msg;
 	}
 	removeMessage(id, msgId) {
-		const unreadFile = join(paths.inboxDir(this.root, id), `${msgId}.json`);
-		if (existsSync(unreadFile)) {
+		const unreadFile = readPathOrUndefined(() => paths.messageFile(this.root, id, msgId));
+		if (unreadFile && existsSync(unreadFile)) {
 			rmSync(unreadFile);
 			return;
 		}
-		const readFile = join(paths.inboxReadDir(this.root, id), `${msgId}.json`);
-		if (existsSync(readFile)) {
+		const readFile = readPathOrUndefined(() => paths.messageReadFile(this.root, id, msgId));
+		if (readFile && existsSync(readFile)) {
 			rmSync(readFile);
 			return;
 		}
@@ -1652,14 +1900,14 @@ var FileStore = class {
 		writeJson(paths.agentFile(this.root, rec.id), rec);
 	}
 	getAgent(id) {
-		const file = paths.agentFile(this.root, id);
-		if (!existsSync(file)) return void 0;
-		return JSON.parse(readFileSync(file, "utf8"));
+		const file = readPathOrUndefined(() => paths.agentFile(this.root, id));
+		if (!file || !existsSync(file)) return void 0;
+		return readJsonRecord(file);
 	}
 	listAgents() {
 		const dir = paths.agentsDir(this.root);
 		if (!existsSync(dir)) return [];
-		return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => JSON.parse(readFileSync(join(dir, f), "utf8"))).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+		return readdirSync(dir).filter((f) => f.endsWith(".json")).map((f) => readJsonRecord(join(dir, f))).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
 	}
 	removeAgent(id) {
 		rmSync(paths.agentFile(this.root, id), { force: true });
@@ -1692,21 +1940,26 @@ var FileStore = class {
 		writeText(paths.briefFile(this.root, agentId), text);
 	}
 	readBrief(agentId) {
-		const file = paths.briefFile(this.root, agentId);
-		return existsSync(file) ? readFileSync(file, "utf8") : void 0;
+		const file = readPathOrUndefined(() => paths.briefFile(this.root, agentId));
+		return file && existsSync(file) ? readFileSync(file, "utf8") : void 0;
 	}
 	setMainPane(pane) {
-		const file = paths.mainPaneFile(this.root);
-		if (pane) {
-			writeText(file, pane);
-			return;
-		}
-		rmSync(file, { force: true });
+		withLock(this.root, "main-pane", () => {
+			const file = paths.mainPaneFile(this.root);
+			if (pane) {
+				writeText(file, pane);
+				return;
+			}
+			rmSync(file, { force: true });
+		});
 	}
 	getMainPane() {
 		const file = paths.mainPaneFile(this.root);
 		return existsSync(file) ? readFileSync(file, "utf8").trim() : void 0;
 	}
+	withLock(name, fn) {
+		return withLock(this.root, name, fn);
+	}
 };
 //#endregion
 //#region src/wake/await.ts

package/{LICENSE → license}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 unional
+Copyright (c) 2026 Unional
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberlegion",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Harness-agnostic agent session spawning and messaging over the filesystem",
   "keywords": [
     "agent",
@@ -12,7 +12,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/cyberuni/cyberplace.git",
+    "url": "git+https://github.com/cyberuni/cyberlegion.git",
     "directory": "packages/cyberlegion"
   },
   "license": "MIT",
@@ -34,13 +34,13 @@
   ],
   "dependencies": {
     "commander": "^14.0.3",
-    "cyber-mux": "0.3.0"
+    "cyber-mux": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",
     "tsdown": "^0.22.0",
     "tsx": "^4.22.3",
-    "typescript": "^6.0.0",
+    "typescript": "^7.0.2",
     "vitest": "^4.1.7"
   },
   "engines": {
@@ -53,7 +53,6 @@
   "scripts": {
     "build": "tsdown",
     "check:metaphor-free": "tsx src/check-metaphor-free.ts",
-    "check:spec": "sdd-check-specs",
     "dev": "tsx src/cli.ts",
     "test": "vitest run src",
     "test:watch": "vitest",

package/readme.md

@@ -18,7 +18,7 @@ npx cyberlegion <command>
 Or pin to an exact version for reproducible hooks:
 
 ```sh
-npx cyberlegion@0.1.0 <command>
+npx cyberlegion@0.3.0 <command>
 ```
 
 ## Commands