@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/lock.js

@@ -0,0 +1,207 @@
+/**
+ * `agents.lock` — a deterministic SHA-256 manifest of the resolved resource set
+ * at a project root, plus the `--frozen` verification that fails closed on any
+ * drift. This is the reproducible-CI slice of the governance work (#337); org
+ * version pins and bundle signing are deferred follow-ups.
+ *
+ * Design:
+ *  - Content hashing REUSES `fingerprintDir` / `fingerprintFile`
+ *    (src/lib/staleness/fingerprint.ts) — the same two-tier fingerprinter every
+ *    staleness checker uses. No new recursive file walker is introduced here.
+ *  - The resource SET is the layered, resolved source union (project > user >
+ *    system > extras), the same precedence `resolveResource` / `syncResourcesToVersion`
+ *    read from. It is enumerated agent-independently on purpose: the lock must be
+ *    reproducible on a fresh CI checkout that has no installed agent VERSIONS, so
+ *    it snapshots the SOURCES sync copies FROM, not any per-version home.
+ *
+ * Lock shape (JSON): `{ "version": 1, "resources": { "<relpath>": "<sha256>" } }`,
+ * keys sorted so the file is byte-stable across machines and runs.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fingerprintDir, fingerprintFile } from './staleness/fingerprint.js';
+import { getProjectAgentsDir, getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos, } from './state.js';
+export const LOCK_FILENAME = 'agents.lock';
+export const LOCK_VERSION = 1;
+/**
+ * Resource kinds captured by the lock — the file/dir-backed layered resources
+ * shared across every agent. Presence-only kinds handled specially by the sync
+ * differ (plugins/promptcuts) are intentionally out of this first slice.
+ */
+export const LOCK_KINDS = [
+    'commands',
+    'skills',
+    'hooks',
+    'rules',
+    'mcp',
+    'permissions',
+    'subagents',
+];
+/** Normalise a filesystem-relative path to POSIX separators for stable keys. */
+function toPosix(rel) {
+    return rel.split(path.sep).join('/');
+}
+/**
+ * Hash every resolved source into a flat `relpath -> sha256` map. Directories are
+ * expanded with `fingerprintDir` (every contained file, sorted); single files use
+ * `fingerprintFile`. Unreadable / missing sources are skipped — enumeration only
+ * ever hands us paths that existed at scan time.
+ */
+export function hashLockSources(sources) {
+    const out = {};
+    for (const src of sources) {
+        let stat;
+        try {
+            stat = fs.statSync(src.path);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            for (const fp of fingerprintDir(src.path)) {
+                const rel = toPosix(path.relative(src.path, fp.path));
+                out[`${src.key}/${rel}`] = fp.sha256;
+            }
+        }
+        else if (stat.isFile()) {
+            const fp = fingerprintFile(src.path);
+            if (fp)
+                out[src.key] = fp.sha256;
+        }
+    }
+    return out;
+}
+/** Build a fully-sorted lock object from a resolved source set. */
+export function buildLock(sources) {
+    return { version: LOCK_VERSION, resources: sortRecord(hashLockSources(sources)) };
+}
+/** Return a new record with keys inserted in sorted order (deterministic JSON). */
+function sortRecord(record) {
+    const out = {};
+    for (const key of Object.keys(record).sort())
+        out[key] = record[key];
+    return out;
+}
+/** Serialise a lock to the canonical, sorted, newline-terminated JSON form. */
+export function serializeLock(lock) {
+    return JSON.stringify({ version: lock.version, resources: sortRecord(lock.resources) }, null, 2) + '\n';
+}
+/** Absolute path to the lockfile for a project root. */
+export function lockPath(projectRoot) {
+    return path.join(projectRoot, LOCK_FILENAME);
+}
+/**
+ * Read + validate an existing lock. Returns null ONLY when the file is absent —
+ * a present-but-malformed lock throws, so `--frozen` fails closed instead of
+ * silently treating corruption as "no lock".
+ */
+export function readLock(projectRoot) {
+    const p = lockPath(projectRoot);
+    if (!fs.existsSync(p))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch (e) {
+        throw new Error(`${LOCK_FILENAME} is not valid JSON: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`${LOCK_FILENAME} is malformed (expected an object).`);
+    }
+    const obj = parsed;
+    if (obj.version !== LOCK_VERSION) {
+        throw new Error(`${LOCK_FILENAME} version ${String(obj.version)} is unsupported (expected ${LOCK_VERSION}).`);
+    }
+    if (!obj.resources || typeof obj.resources !== 'object') {
+        throw new Error(`${LOCK_FILENAME} is missing a resources map.`);
+    }
+    return { version: LOCK_VERSION, resources: obj.resources };
+}
+/** Write the lock to `<projectRoot>/agents.lock`, returning the path written. */
+export function writeLock(projectRoot, lock) {
+    const p = lockPath(projectRoot);
+    fs.writeFileSync(p, serializeLock(lock));
+    return p;
+}
+/** Diff a recorded lock against a freshly-computed one. */
+export function diffLock(expected, actual) {
+    const e = expected.resources;
+    const a = actual.resources;
+    const added = [];
+    const removed = [];
+    const changed = [];
+    for (const k of Object.keys(a))
+        if (!(k in e))
+            added.push(k);
+    for (const k of Object.keys(e)) {
+        if (!(k in a))
+            removed.push(k);
+        else if (e[k] !== a[k])
+            changed.push(k);
+    }
+    added.sort();
+    removed.sort();
+    changed.sort();
+    return { added, removed, changed };
+}
+/** True when a diff has no added/removed/changed entries. */
+export function lockDiffIsClean(diff) {
+    return diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0;
+}
+/** Verify a recorded lock against the live resolved sources. */
+export function verifyLock(expected, sources) {
+    return diffLock(expected, buildLock(sources));
+}
+/**
+ * The project root the lockfile lives at: the parent of the discovered project
+ * `.agents/` dir, or the cwd itself when none is found.
+ */
+export function resolveProjectRoot(cwd = process.cwd()) {
+    const projectDir = getProjectAgentsDir(cwd);
+    return projectDir ? path.dirname(projectDir) : path.resolve(cwd);
+}
+/**
+ * Enumerate the resolved resource sources for a cwd: for each lockable kind, the
+ * winning entry per name across layers (project > user > system > extras), keyed
+ * `<kind>/<entryName>`. This is a single-level `readdir` per kind dir — the
+ * recursive fingerprinting is delegated to `fingerprintDir`.
+ *
+ * Entry names keep their extension in the key, so a hook script `foo.sh` and its
+ * sidecar `foo.yaml` stay distinct (a name-stripped enumerator would collide
+ * them). Dotfiles at the kind-dir top level are skipped as noise.
+ */
+export function enumerateLockSources(cwd = process.cwd()) {
+    const roots = [];
+    const projectDir = getProjectAgentsDir(cwd);
+    if (projectDir)
+        roots.push(projectDir);
+    roots.push(getUserAgentsDir());
+    roots.push(getSystemAgentsDir());
+    for (const extra of getEnabledExtraRepos())
+        roots.push(extra.dir);
+    const sources = [];
+    const seen = new Set();
+    for (const kind of LOCK_KINDS) {
+        for (const root of roots) {
+            const kindDir = path.join(root, kind);
+            let entries;
+            try {
+                entries = fs.readdirSync(kindDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.name.startsWith('.'))
+                    continue;
+                const key = `${kind}/${entry.name}`;
+                if (seen.has(key))
+                    continue; // project layer wins on same name
+                seen.add(key);
+                sources.push({ path: path.join(kindDir, entry.name), key });
+            }
+        }
+    }
+    return sources.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+}

package/dist/lib/loop.js

@@ -26,6 +26,8 @@ import { buildExecCommand, buildExecEnv } from './exec.js';
 import { extractUsageEvents } from './budget/enforce.js';
 import { parseTimeout } from './routines.js';
 import { writeCheckpoint } from './checkpoint.js';
+import { mailboxDir } from './mailbox.js';
+import { composeWin32CommandLine } from './platform/index.js';
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** Path to a run's loop-signal.json. */
 export function loopSignalPath(runDir) {
@@ -129,8 +131,14 @@ export function defaultRunIteration(options) {
     const cwd = execOptions.cwd || process.cwd();
     const model = execOptions.model ?? `${execOptions.agent}-default`;
     return new Promise((resolve, reject) => {
+        // DEP0190-safe shell spawn: on the win32 shell path compose ONE fully-quoted
+        // command line and pass an EMPTY args array (see composeWin32CommandLine) so
+        // Node never concatenates the args array — which carries the re-injected
+        // prompt — into the cmd.exe line unescaped.
         const useShell = process.platform === 'win32' && (!path.isAbsolute(executable) || executable.endsWith('.cmd'));
-        const child = spawn(executable, args, {
+        const spawnCommand = useShell ? composeWin32CommandLine(executable, args) : executable;
+        const spawnArgs = useShell ? [] : args;
+        const child = spawn(spawnCommand, spawnArgs, {
             cwd,
             stdio: ['inherit', 'pipe', 'pipe'],
             env,
@@ -207,6 +215,9 @@ export async function runLoop(execOptions, loop, ctx, deps) {
         process.stderr.write(`[loop] WARNING: cross-iteration conversation continuity applies to claude only. ` +
             `Each ${ctx.agent} iteration runs as an independent fresh conversation (no /continue handoff).\n`);
     }
+    // Surface the run-level mailbox id (otherwise undiscoverable — runId is not in
+    // the session registry) so an operator can message the loop mid-flight.
+    process.stderr.write(`[loop] mailbox: agents message ${ctx.runId} "<text>"\n`);
     let tokens = ctx.startTokens ?? 0;
     let lastSignal;
     let stopSignal = false;
@@ -271,6 +282,10 @@ export async function runLoop(execOptions, loop, ctx, deps) {
                     AGENTS_RUN_DIR: ctx.runDir,
                     AGENTS_LOOP_SIGNAL: loopSignalPath(ctx.runDir),
                     AGENTS_LOOP_ITERATION: String(iteration),
+                    // Every iteration is a fresh session, so key the mailbox by the stable
+                    // run id — one box for the whole loop. Overrides the per-iteration
+                    // AGENTS_MAILBOX_DIR that buildExecEnv would derive from sessionId.
+                    AGENTS_MAILBOX_DIR: mailboxDir(ctx.runId),
                 },
             };
             let result;

package/dist/lib/machine-id.d.ts

@@ -0,0 +1,21 @@
+/**
+ * This machine's stable, human-readable id. Lives in a dependency-free leaf so
+ * low-level modules (state.ts) can key per-device paths off it without importing
+ * the secrets/session-sync layer (which would create a cycle).
+ */
+/**
+ * Normalize a raw hostname into a stable device id: first label only,
+ * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
+ * `ZION` both become `zion`. The single source for this transform — machineId()
+ * and cross-machine session grouping must agree or the local machine won't
+ * match its own registry key.
+ */
+export declare function normalizeHost(raw: string): string;
+/**
+ * This machine's stable, human-readable id, used as its R2 sync prefix, session
+ * mirror directory, `agents devices` self-key, and per-device config folder.
+ * Tailnet hostnames (zion, yosemite-s0, mac-mini) are already unique and
+ * readable; we lowercase and strip any domain suffix. Overridable via
+ * AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export declare function machineId(): string;

package/dist/lib/machine-id.js

@@ -0,0 +1,26 @@
+/**
+ * This machine's stable, human-readable id. Lives in a dependency-free leaf so
+ * low-level modules (state.ts) can key per-device paths off it without importing
+ * the secrets/session-sync layer (which would create a cycle).
+ */
+import * as os from 'os';
+/**
+ * Normalize a raw hostname into a stable device id: first label only,
+ * lowercased, non-alphanumerics collapsed to hyphens. `zion.tail…ts.net` and
+ * `ZION` both become `zion`. The single source for this transform — machineId()
+ * and cross-machine session grouping must agree or the local machine won't
+ * match its own registry key.
+ */
+export function normalizeHost(raw) {
+    return raw.split('.')[0].trim().toLowerCase().replace(/[^a-z0-9_-]/g, '-') || 'unknown';
+}
+/**
+ * This machine's stable, human-readable id, used as its R2 sync prefix, session
+ * mirror directory, `agents devices` self-key, and per-device config folder.
+ * Tailnet hostnames (zion, yosemite-s0, mac-mini) are already unique and
+ * readable; we lowercase and strip any domain suffix. Overridable via
+ * AGENTS_SYNC_MACHINE_ID for tests and unusual setups.
+ */
+export function machineId() {
+    return normalizeHost(process.env.AGENTS_SYNC_MACHINE_ID || os.hostname());
+}

package/dist/lib/mailbox-target.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolve an `agents message <target>` argument to exactly one destination —
+ * a cloud task, one live local/teams/loop agent, or an error. The anti-misroute
+ * rule lives here: a target that matches zero or more-than-one live agent is
+ * NEVER guessed; the caller reports it. Pure (no I/O) so it is unit-testable.
+ */
+import type { ActiveSession } from './session/active.js';
+export type MessageResolution = {
+    kind: 'cloud';
+    id: string;
+} | {
+    kind: 'local';
+    id: string;
+} | {
+    kind: 'none';
+} | {
+    kind: 'ambiguous';
+    candidates: Array<{
+        id: string;
+        label: string;
+    }>;
+};
+/**
+ * The mailbox id a live session's box is keyed by. Teams stamp a durable
+ * `agentId` (== the Claude session id for Claude teammates); a bare run has
+ * only its `sessionId`. The spawn-time `AGENTS_MAILBOX_DIR` wiring must key the
+ * box by this same id — this is the single source of truth for both sides.
+ */
+export declare function mailboxIdForActiveSession(s: ActiveSession): string | undefined;
+/**
+ * Resolve `target` against the live sessions. Exact id matches win over prefix
+ * matches; results are de-duped by canonical mailbox id (collapsed subagents
+ * share one). `isCloudTask` is consulted first so a cloud task id routes to the
+ * cloud provider.
+ */
+export declare function resolveMessageTarget(target: string, sessions: ActiveSession[], isCloudTask: (id: string) => boolean): MessageResolution;

package/dist/lib/mailbox-target.js

@@ -0,0 +1,45 @@
+/**
+ * The mailbox id a live session's box is keyed by. Teams stamp a durable
+ * `agentId` (== the Claude session id for Claude teammates); a bare run has
+ * only its `sessionId`. The spawn-time `AGENTS_MAILBOX_DIR` wiring must key the
+ * box by this same id — this is the single source of truth for both sides.
+ */
+export function mailboxIdForActiveSession(s) {
+    return s.agentId ?? s.sessionId;
+}
+function labelFor(s) {
+    return s.label ?? s.topic ?? s.teamName ?? s.host ?? s.context;
+}
+/**
+ * Resolve `target` against the live sessions. Exact id matches win over prefix
+ * matches; results are de-duped by canonical mailbox id (collapsed subagents
+ * share one). `isCloudTask` is consulted first so a cloud task id routes to the
+ * cloud provider.
+ */
+export function resolveMessageTarget(target, sessions, isCloudTask) {
+    if (isCloudTask(target))
+        return { kind: 'cloud', id: target };
+    // An empty target would make every `startsWith` prefix match — never guess.
+    if (target.length === 0)
+        return { kind: 'none' };
+    const exact = sessions.filter((s) => s.sessionId === target || s.agentId === target);
+    const chosen = exact.length > 0
+        ? exact
+        : sessions.filter((s) => Boolean(s.sessionId?.startsWith(target)) || Boolean(s.agentId?.startsWith(target)));
+    // De-dupe by canonical mailbox id (one box per logical agent).
+    const byId = new Map();
+    for (const s of chosen) {
+        const id = mailboxIdForActiveSession(s);
+        if (id && !byId.has(id))
+            byId.set(id, s);
+    }
+    const ids = [...byId.keys()];
+    if (ids.length === 0)
+        return { kind: 'none' };
+    if (ids.length === 1)
+        return { kind: 'local', id: ids[0] };
+    return {
+        kind: 'ambiguous',
+        candidates: [...byId.entries()].map(([id, s]) => ({ id, label: labelFor(s) })),
+    };
+}

package/dist/lib/mailbox.d.ts

@@ -0,0 +1,47 @@
+/** A single mailbox message. `text` may embed `host:/path` clip tokens. */
+export interface MailboxMessage {
+    /** Unique, time-sortable id. Also the on-disk filename stem. */
+    msgId: string;
+    /** The mailboxId this message is addressed to (anti-misroute stamp). */
+    to: string;
+    /** Who sent it (operator label / agent id / host). Optional. */
+    from?: string;
+    /** ISO-8601 creation time. */
+    ts: string;
+    /** The message body. */
+    text: string;
+}
+/**
+ * A mailboxId must be a single, separator-free path segment. Real ids (session
+ * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
+ * else fails loud instead of silently misrouting — a message whose id contained
+ * a `/` would nest under a different dir than the `to` stamp it is matched
+ * against, and would be dropped with no error. Also blocks `.`/`..` traversal
+ * once `agents message` starts accepting external target ids.
+ */
+export declare function isValidMailboxId(mailboxId: string): boolean;
+export declare function assertValidMailboxId(mailboxId: string): void;
+/** Absolute path to a box. `root` override is for tests. */
+export declare function mailboxDir(mailboxId: string, root?: string): string;
+/**
+ * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
+ * is stamped so a drain can refuse a message that lands in the wrong box.
+ */
+export declare function enqueue(boxDir: string, msg: {
+    to: string;
+    text: string;
+    from?: string;
+}): string;
+/**
+ * Drain the box: return every pending message addressed to it, in FIFO order,
+ * removing them from the queue. Claim-first (inbox → processing → consumed) so
+ * an interrupted drain is recovered on the next call (at-least-once). Corrupt
+ * files and messages addressed to a different box are dropped, not returned.
+ *
+ * `boxId` defaults to the box's directory name — the id it was created under.
+ */
+export declare function drain(boxDir: string, boxId?: string): MailboxMessage[];
+/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
+export declare function peek(boxDir: string, boxId?: string): MailboxMessage[];
+/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
+export declare function clear(boxDir: string): number;

package/dist/lib/mailbox.js

@@ -0,0 +1,194 @@
+/**
+ * Agent mailbox — a file-spool that lets a message reach an already-running
+ * agent mid-flight. One box per logical agent, keyed by a unique-per-launch id
+ * (session UUID / teams agentId / loop runId), so boxes are disjoint and a
+ * message can never reach the wrong agent (see docs / plan velvety-conjuring-popcorn).
+ *
+ * Layout: <root>/<mailboxId>/{inbox,processing,consumed}/<msgId>.json
+ *   inbox/      pending, written by `agents message`
+ *   processing/ claimed by a drain (claim-first = crash-safe)
+ *   consumed/   archived after delivery (and dropped mismatches)
+ *
+ * A box has a SINGLE consumer — the owning agent, whose tool calls (and thus
+ * hook-driven drains) are sequential. Writers may be concurrent; each enqueue
+ * is atomic (temp-write + rename), so a drain never observes a partial file.
+ * Delivery is at-least-once: an interrupted drain leaves the message in
+ * processing/, and the next drain recovers it. Consumers dedup by `msgId`.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomUUID } from 'crypto';
+import { getMailboxRootDir } from './state.js';
+/**
+ * A mailboxId must be a single, separator-free path segment. Real ids (session
+ * UUID / teams agentId / loop runId) already satisfy this; rejecting anything
+ * else fails loud instead of silently misrouting — a message whose id contained
+ * a `/` would nest under a different dir than the `to` stamp it is matched
+ * against, and would be dropped with no error. Also blocks `.`/`..` traversal
+ * once `agents message` starts accepting external target ids.
+ */
+export function isValidMailboxId(mailboxId) {
+    return /^[A-Za-z0-9._-]+$/.test(mailboxId) && mailboxId !== '.' && mailboxId !== '..';
+}
+export function assertValidMailboxId(mailboxId) {
+    if (!isValidMailboxId(mailboxId)) {
+        throw new Error(`Invalid mailboxId ${JSON.stringify(mailboxId)}: must be a single path segment ` +
+            `matching [A-Za-z0-9._-] (no separators, not '.'/'..').`);
+    }
+}
+/** Absolute path to a box. `root` override is for tests. */
+export function mailboxDir(mailboxId, root = getMailboxRootDir()) {
+    assertValidMailboxId(mailboxId);
+    return path.join(root, mailboxId);
+}
+function inboxDir(boxDir) { return path.join(boxDir, 'inbox'); }
+function processingDir(boxDir) { return path.join(boxDir, 'processing'); }
+function consumedDir(boxDir) { return path.join(boxDir, 'consumed'); }
+/** Create the three sub-buckets. Idempotent. */
+function ensureDirs(boxDir) {
+    fs.mkdirSync(inboxDir(boxDir), { recursive: true });
+    fs.mkdirSync(processingDir(boxDir), { recursive: true });
+    fs.mkdirSync(consumedDir(boxDir), { recursive: true });
+}
+let seq = 0;
+/**
+ * `<epochMs>-<seq>-<rand>` — sorts by filename in FIFO order. The per-process
+ * monotonic `seq` breaks ties within the same millisecond (so a single writer's
+ * order is preserved); `rand` keeps it unique across processes/hosts.
+ */
+function newMsgId() {
+    const s = String(seq++).padStart(6, '0');
+    return `${Date.now()}-${s}-${randomUUID().slice(0, 8)}`;
+}
+/**
+ * Enqueue a message into `boxDir` atomically. Returns the msgId. The `to` field
+ * is stamped so a drain can refuse a message that lands in the wrong box.
+ */
+export function enqueue(boxDir, msg) {
+    assertValidMailboxId(msg.to);
+    ensureDirs(boxDir);
+    const msgId = newMsgId();
+    const record = {
+        msgId,
+        to: msg.to,
+        from: msg.from,
+        ts: new Date().toISOString(),
+        text: msg.text,
+    };
+    const target = path.join(inboxDir(boxDir), `${msgId}.json`);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2), 'utf-8');
+    fs.renameSync(tmp, target); // atomic on a single filesystem
+    return msgId;
+}
+/** Parse a message file. Returns null on missing/corrupt/invalid-shape. */
+function readMessage(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const m = parsed;
+    if (typeof m?.msgId !== 'string' || typeof m?.to !== 'string' || typeof m?.text !== 'string') {
+        return null;
+    }
+    return { msgId: m.msgId, to: m.to, from: m.from, ts: m.ts ?? '', text: m.text };
+}
+function jsonFiles(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((n) => n.endsWith('.json')).sort();
+}
+/**
+ * Consume a file already sitting in `processing/`: read, verify it is addressed
+ * to this box, then archive to `consumed/`. Returns the message iff valid AND
+ * addressed here; a mismatched/corrupt file is archived (dropped) so it never
+ * loops. Returns null when the file vanished (a racing drain took it).
+ */
+function consumeClaimed(boxDir, name, expectedTo) {
+    const src = path.join(processingDir(boxDir), name);
+    const dest = path.join(consumedDir(boxDir), name);
+    const msg = readMessage(src);
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch {
+        return null; // already archived/claimed elsewhere
+    }
+    if (!msg || msg.to !== expectedTo)
+        return null; // dropped (corrupt or wrong box)
+    return msg;
+}
+/**
+ * Drain the box: return every pending message addressed to it, in FIFO order,
+ * removing them from the queue. Claim-first (inbox → processing → consumed) so
+ * an interrupted drain is recovered on the next call (at-least-once). Corrupt
+ * files and messages addressed to a different box are dropped, not returned.
+ *
+ * `boxId` defaults to the box's directory name — the id it was created under.
+ */
+export function drain(boxDir, boxId = path.basename(boxDir)) {
+    ensureDirs(boxDir);
+    const out = [];
+    // 1. Recover orphans left in processing/ by a prior interrupted drain.
+    for (const name of jsonFiles(processingDir(boxDir))) {
+        const msg = consumeClaimed(boxDir, name, boxId);
+        if (msg)
+            out.push(msg);
+    }
+    // 2. Claim and consume pending inbox messages.
+    for (const name of jsonFiles(inboxDir(boxDir))) {
+        const from = path.join(inboxDir(boxDir), name);
+        const to = path.join(processingDir(boxDir), name);
+        try {
+            fs.renameSync(from, to); // atomic claim
+        }
+        catch {
+            continue; // vanished — a racing drain took it
+        }
+        const msg = consumeClaimed(boxDir, name, boxId);
+        if (msg)
+            out.push(msg);
+    }
+    return out;
+}
+/** Read pending messages (inbox + in-flight) without consuming them. FIFO. */
+export function peek(boxDir, boxId = path.basename(boxDir)) {
+    const out = [];
+    for (const dir of [processingDir(boxDir), inboxDir(boxDir)]) {
+        for (const name of jsonFiles(dir)) {
+            const msg = readMessage(path.join(dir, name));
+            if (msg && msg.to === boxId)
+                out.push(msg);
+        }
+    }
+    return out;
+}
+/** Delete pending (not-yet-claimed) inbox messages. Returns the count removed. */
+export function clear(boxDir) {
+    let n = 0;
+    for (const name of jsonFiles(inboxDir(boxDir))) {
+        try {
+            fs.unlinkSync(path.join(inboxDir(boxDir), name));
+            n++;
+        }
+        catch {
+            // already gone — ignore
+        }
+    }
+    return n;
+}

package/dist/lib/mcp.d.ts

@@ -39,6 +39,11 @@ export interface McpTargetOperationResult {
  * Parse an MCP server config from a YAML file.
  */
 export declare function parseMcpServerConfig(filePath: string): McpYamlConfig | null;
+/**
+ * Validate an MCP server name. Rejects names that could be misinterpreted as
+ * command-line options or that contain characters unsafe for argv/identifier use.
+ */
+export declare function validateMcpServerName(name: string): void;
 /**
  * List all MCP server configs from ~/.agents/mcp/.
  */