@oh-hai/cli 0.4.3 → 0.4.5

package/dist/commands/mail/http.js

@@ -0,0 +1,106 @@
+// Hub calls for the `oh-hai mail` surface — the account owner's own inbox (issue #874).
+//
+// Every function here takes a HUMAN session bearer. Nothing in this module decides whether the
+// caller is entitled to use it: that is `identity.ts`'s pre-flight gate, which runs before any of
+// these are reached. Re-checking here would invite the response-inspection shape the gate exists to
+// avoid — see that module's header.
+//
+// Status mapping, transport errors, and the error envelope are REUSED from the messaging layer
+// rather than reimplemented: a second copy of the status table drifts, and a drifted copy maps a
+// 404 or a 409 to the wrong exit code, which is exactly the machine contract callers branch on.
+import { throwTransportError } from "../http.js";
+import { readErrorEnvelope, readJson, redactToken, requestTimeoutMs, statusToCliError } from "../messaging/http.js";
+import { redactDeep } from "../messaging/sessions-http.js";
+import { CliError } from "../../envelope.js";
+function isMailRow(v) {
+    const r = v;
+    return typeof r === "object" && r !== null && typeof r.id === "string" && typeof r.type === "string" && typeof r.status === "string";
+}
+async function get(ctx, token, path) {
+    const url = `${ctx.config.baseUrl}${path}`;
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(requestTimeoutMs(ctx)),
+        });
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+    if (res.status < 200 || res.status >= 300) {
+        const { code, message } = await readErrorEnvelope(res);
+        throw statusToCliError(res.status, redactToken(message, token), code);
+    }
+    // REDACT THE BEARER FROM THE SUCCESS BODY TOO — not just from error messages (§5.4).
+    // A buggy or hostile Hub can echo the Authorization value into any field, and this surface
+    // serializes rows VERBATIM under `--json` (deliberately, so a multi-line body survives) — so an
+    // echoed bearer would land on stdout intact. The sibling `listMessages` already round-trips its
+    // rows through the same redactor; the human inbox path must not be the one that skips it.
+    // Fails CLOSED: a re-parse failure raises a server error rather than returning un-redacted data.
+    return redactDeep(await readJson(res), token, "message");
+}
+/** List the account inbox — full message bodies, not an index (see MailRow). `view` selects the
+ *  triage feed; `archived` is an explicit opt-in. */
+export async function listInbox(ctx, token, opts) {
+    const query = new URLSearchParams();
+    if (opts.limit !== undefined)
+        query.set("limit", String(opts.limit));
+    if (opts.offset !== undefined)
+        query.set("offset", String(opts.offset));
+    // Only the archived view carries a param; `active` is the absence of one.
+    if (opts.view === "archived")
+        query.set("archived", "true");
+    const suffix = query.toString();
+    const body = await get(ctx, token, `/v1/messages${suffix ? `?${suffix}` : ""}`);
+    const messages = body.messages;
+    if (!Array.isArray(messages) || !messages.every(isMailRow)) {
+        // A malformed body is a SERVER error, never a silently empty inbox — an empty table would read
+        // as "nothing to triage" and hide a Hub or proxy regression behind good news.
+        throw new CliError("server", "the Hub returned a malformed message list (expected { messages: [{ id, type, status }] }).");
+    }
+    return messages;
+}
+/** Pull one message by id.
+ *
+ *  VALIDATED LIKE THE LIST PATH, and for the same reason. `readJson` collapses a malformed 2xx —
+ *  non-JSON, an array, `{}` — to an empty object, so an unvalidated detail read would exit 0 and
+ *  print `{ message: {} }` (or a row of em dashes), presenting a Hub/proxy contract failure as a
+ *  successful read of an empty message. The list path already refuses that; leaving the detail path
+ *  permissive made the two disagree about what a valid response is. */
+export async function readMessage(ctx, token, id) {
+    const body = await get(ctx, token, `/v1/messages/${encodeURIComponent(id)}`);
+    if (!isMailRow(body)) {
+        throw new CliError("server", "the Hub returned a malformed message (expected { id, type, status }).");
+    }
+    // AND IT MUST BE THE MESSAGE THAT WAS ASKED FOR. A well-shaped body for a DIFFERENT id passes the
+    // shape check and would exit 0 having shown the wrong message — the caller then archives, quotes
+    // or acts on something they never requested. The agent-side `pollMessage` validates this echo for
+    // the same reason; a shape check alone is not an identity check.
+    if (body.id !== id) {
+        throw new CliError("server", "the Hub returned a different message than the one requested.");
+    }
+    return body;
+}
+/** Apply one triage verb to one message. Returns nothing — the Hub answers 2xx with no body worth
+ *  rendering, and inventing one would imply state this command did not read back. */
+export async function triage(ctx, token, id, verb) {
+    const url = `${ctx.config.baseUrl}/v1/messages/${encodeURIComponent(id)}/${verb}`;
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(url, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(requestTimeoutMs(ctx)),
+        });
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+    if (res.status < 200 || res.status >= 300) {
+        const { code, message } = await readErrorEnvelope(res);
+        throw statusToCliError(res.status, redactToken(message, token), code);
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/commands/mail/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/commands/mail/http.ts"],"names":[],"mappings":"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"}

package/dist/commands/mail/identity.d.ts

@@ -0,0 +1,15 @@
+import type { CommandContext } from "../context.js";
+/** The human identity a `mail` command runs as. */
+export interface MailIdentity {
+    /** The account owner's session bearer. */
+    token: string;
+    /** The `<userId>` half of the stored `human:<userId>` id — never the raw stored key. */
+    userId: string;
+}
+/**
+ * Resolve the human identity for a `mail` command, or refuse.
+ *
+ * Called before any request is composed. Throws rather than returning a discriminated result: a
+ * caller cannot then forget to branch, which is the failure this whole module exists to prevent.
+ */
+export declare function resolveMailIdentity(ctx: CommandContext): Promise<MailIdentity>;

package/dist/commands/mail/identity.js

@@ -0,0 +1,135 @@
+// Identity resolution for the `oh-hai mail` surface — the account OWNER's own inbox (issue #874).
+//
+// WHY THE REFUSAL IS PRE-FLIGHT, AND WHY IT CANNOT BE A RESPONSE CHECK.
+// `GET /v1/messages` is DUAL-AUDIENCE: with a human session bearer it returns the account-wide
+// inbox; with an AGENT bearer it SUCCEEDS and returns that agent's own submitted messages. It does
+// not error for the wrong audience — it returns different data with the same shape and the same
+// 200. So a guard that inspects the RESPONSE is unsound by construction, and the sibling
+// agent-side guard in `messaging/http.ts` says exactly that in its own comment:
+//
+//     a heuristic, not a proof of the agent branch: a single-agent or empty account has no
+//     foreign row to trip on
+//
+// That hole is widest precisely where it matters most — a fresh or single-agent account — and its
+// failure mode is silent: a plausible, well-formed, WRONG inbox with nothing signalling it.
+// Deciding from the RESOLVED IDENTITY, before a request is composed, has no such hole: an agent
+// identity never reaches the network here at all. Every `mail` command therefore calls
+// `resolveMailIdentity` FIRST, and nothing in this module consults response data.
+//
+// FAIL CLOSED. An unresolvable identity is refused as not-human rather than attempted
+// unauthenticated — "I could not tell" is never permission to send.
+import { resolveIdentity } from "../../auth/resolve-token.js";
+import { humanUserId, isHumanId } from "../../auth/token-store.js";
+import { CliError } from "../../envelope.js";
+import { sanitizeForTerminal } from "../messaging/shared.js";
+import { classifyProbeStatus, probeGet, readActor, readJsonBody } from "../whoami.js";
+/** How to get one, appended to every refusal so the error is actionable rather than a diagnosis. */
+const REMEDY = "`oh-hai mail` reads YOUR account inbox, so it needs a human identity: run `oh-hai login --human` " +
+    "(or select one with --account human:<id>). To read an agent's own submitted messages instead, use `oh-hai messages list`.";
+/**
+ * Resolve the human identity for a `mail` command, or refuse.
+ *
+ * Called before any request is composed. Throws rather than returning a discriminated result: a
+ * caller cannot then forget to branch, which is the failure this whole module exists to prevent.
+ */
+export async function resolveMailIdentity(ctx) {
+    // FIRST, AND BEFORE THE ID IS EVEN CONSULTED: refuse an env bearer.
+    //
+    // `MA2H_AGENT_TOKEN` is an AGENT credential by name and by contract, and — the part that makes
+    // this a hole rather than a nicety — it is NOT BOUND TO THE CONFIGURED ACCOUNT. `resolveIdentity`
+    // returns it verbatim alongside whatever `--account` says (the same unbinding `requireWatchIdentity`
+    // documents for the drain lock). So without this arm:
+    //
+    //     MA2H_AGENT_TOKEN=<agent bearer> oh-hai mail list --account human:usr_1
+    //
+    // presents a human-SHAPED id with an AGENT token behind it. The id test below would pass, the
+    // request would go out, and the Hub would answer with that agent's own submissions — the exact
+    // plausible-but-wrong inbox this module exists to prevent, reached through the env path instead
+    // of the store. A human identity must be STORE-resolved, where the token was looked up BY the
+    // human id and the two are therefore bound.
+    if (ctx.config.tokenSource === "env") {
+        throw new CliError("usage", "MA2H_AGENT_TOKEN is set, and it is an AGENT credential that is not bound to --account — it cannot be used as a human identity. " +
+            "Unset it and run `oh-hai login --human`, so the session token is stored under (and resolved by) your human id.");
+    }
+    const store = await ctx.runtime.openStore();
+    const { account, token } = await resolveIdentity(ctx.config, store);
+    // Order matters: classify the IDENTITY before asking whether a token exists. An agent identity
+    // that happens to have no stored token must still read as "wrong identity", not as "log in" —
+    // sending the caller to re-login would have them authenticate as the agent again and arrive back
+    // here, having been told the wrong thing twice.
+    if (account === undefined) {
+        throw new CliError("usage", `no identity is selected, so this command cannot tell whose inbox to read. ${REMEDY}`);
+    }
+    if (!isHumanId(account)) {
+        // SANITIZE THE ID BEFORE IT REACHES A TERMINAL. A device-code login stores the agent id the HUB
+        // chose, verbatim — `runDeviceCodeFlow` accepts any non-empty `agent_id` — so a custom or
+        // compromised Hub can plant control characters in it, and this message goes straight to stderr.
+        // The login and whoami display paths already sanitize for exactly this; the table rendering in
+        // mail.ts does too. The ERROR path was the one place still interpolating it raw.
+        throw new CliError("usage", `the selected identity "${sanitizeForTerminal(account)}" is an AGENT, not a human. ${REMEDY}`);
+    }
+    if (token === undefined) {
+        throw new CliError("auth", `no stored token for "${sanitizeForTerminal(account)}" — run \`oh-hai login --human\`.`);
+    }
+    // `humanUserId` re-tests the prefix rather than slicing on the strength of the check above, so
+    // this stays correct if the two are ever separated.
+    const userId = humanUserId(account);
+    if (userId === undefined || userId === "") {
+        throw new CliError("usage", `the selected identity "${sanitizeForTerminal(account)}" carries no user id. ${REMEDY}`);
+    }
+    // ATTEST THE CREDENTIAL. The checks above establish that the stored ID claims to be human; they
+    // cannot establish that the TOKEN is. The `human:` prefix is only reserved as of this change, and
+    // it never was on the server: `MA2H_AGENT_TOKENS` splits on `=` with no reserved-prefix rule, and
+    // an older CLI accepted `login --token-stdin --account human:bot` with any bearer. So a
+    // credential stored BEFORE this change — or configured on the Hub — can carry a human-shaped id
+    // over an AGENT token, and every local check would wave it through.
+    //
+    // This is the same rule as the two refusals above, applied honestly: an id-based check is sound
+    // only where the id IMPLIES the credential. History means it does not, so ask the Hub who this
+    // token actually is and believe THAT.
+    //
+    // ORDERING IS DELIBERATE. The local refusals run FIRST, so the common wrong-identity case still
+    // costs no network call at all and the "an agent identity never reaches the network" property
+    // holds for it. This probe runs only for a credential that already looks human, and it targets
+    // `/auth/whoami` — an identity endpoint that discloses nothing about the inbox — so the INBOX is
+    // still never touched by a non-human caller.
+    const res = await probeGet(ctx, "/auth/whoami", token);
+    if (res.status !== 200)
+        classifyProbeStatus(res.status);
+    const actor = readActor(await readJsonBody(res));
+    if (actor === undefined) {
+        throw new CliError("server", "the Hub did not attest an identity for this credential (200 without an actor); refusing rather than assuming it is yours.");
+    }
+    // NEVER ECHO AN ACTOR THAT CONTAINS THE CREDENTIAL. `sanitizeForTerminal` strips controls; it does
+    // not redact a PRINTABLE bearer. A Hub answering `agent:<the-token>` would otherwise have its
+    // actor interpolated into the refusal below and written to stderr — the §5.4 never-print contract
+    // broken by the very check that exists to protect the surface. The login arm refuses this exact
+    // shape; adding the probe here without the same refusal reproduced the hole one file over.
+    if (actor.includes(token)) {
+        throw new CliError("server", "the Hub echoed the presented credential back inside its identity response; refusing rather than reporting it.");
+    }
+    // THE ATTESTED ACTOR MUST BE **THIS** IDENTITY, not merely *a* human one.
+    //
+    // "Is it human?" is not the question. An older CLI accepted `--token-stdin --account human:A` with
+    // ANY bearer, so a store can hold human B's valid session token under the key `human:A`. The Hub
+    // then attests `human:B` — genuinely human — and a human-only check passes, after which
+    // `--account human:A` lists, reads and ARCHIVES B's inbox while every message claims to run as A.
+    // A cross-account read, reached through a check that looked like it had closed the hole.
+    //
+    // This is the third variant of one rule in this PR, and the general form is the one to hold:
+    // the credential must be attested as the EXACT identity being acted on, not as a member of the
+    // right class.
+    if (actor !== account) {
+        throw new CliError("usage", `the stored credential under "${sanitizeForTerminal(account)}" is attested by the Hub as a DIFFERENT identity. ` +
+            "It was stored before the `human:` prefix was reserved, or under the wrong key. Re-run `oh-hai login --human` to replace it — " +
+            "the attested id is not shown here because it is not yours to learn from a mismatched key.");
+    }
+    // NOTE: no separate "is the actor human?" arm here, deliberately. The equality check above already
+    // implies it — `account` passed `isHumanId` earlier, and `actor` must equal `account` — so such a
+    // branch could never execute. Leaving one would imply a live guard that is doing nothing, which is
+    // how a later reader concludes the class is covered when the equality check is what covers it.
+    // Equal to `account` by the check above; read from the ATTESTED value so the Hub remains the
+    // source of truth rather than the local key.
+    return { token, userId: humanUserId(actor) ?? userId };
+}
+//# sourceMappingURL=identity.js.map

package/dist/commands/mail/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/commands/mail/identity.ts"],"names":[],"mappings":"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"}

package/dist/commands/mail.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./context.js";
+export declare function mailCommand(ctx: CommandContext): Promise<void | number>;

package/dist/commands/mail.js

@@ -0,0 +1,232 @@
+// `oh-hai mail` (cli spec §4.16) — the ACCOUNT OWNER's own inbox, read and triaged from a terminal
+// (issue #874).
+//
+// A SEPARATE VERB FROM `inbox`, DELIBERATELY. `oh-hai inbox` is the AGENT's mailbox drain (the
+// human→agent leg). Dispatching one noun on the resolved identity would put the human/agent
+// decision in a runtime branch — the same shape as the failure this surface is built to prevent —
+// so the two are separate namespaces instead, and a wrong identity reaches a command that cannot
+// serve it at all.
+//
+// EVERY SUBCOMMAND RESOLVES ITS IDENTITY FIRST. `resolveMailIdentity` refuses an agent identity
+// before a request is composed; nothing here inspects a response to decide entitlement. See
+// `mail/identity.ts` for why the response cannot answer that question.
+//
+// Output posture: under `--json` rows keep their STRUCTURE and their newlines (a multi-line body
+// must survive, which is why they are not run through `sanitizeForTerminal` — that strips C0 and
+// would destroy them), while the human table renders only single-line index fields, each
+// `sanitizeForTerminal`'d against a hostile Hub.
+//
+// `JSON.stringify` IS NOT A SANITIZER, and an earlier revision of this comment claimed it was:
+// it escapes the C0 range but passes **C1** (U+0080–U+009F, including U+009B CSI) and **DEL**
+// through RAW. A JSON envelope printed into a terminal therefore carries a live injection vector.
+// `agents list --json` already strips these; this surface must too — see `stripJsonUnsafeControls`.
+import { buildOk, CliError, serializeEnvelope } from "../envelope.js";
+import { ExitCode } from "../exit-codes.js";
+import { flagOnStrict, parseCommandArgs } from "./flags.js";
+import { resolveMailIdentity } from "./mail/identity.js";
+import { listInbox, readMessage, triage } from "./mail/http.js";
+import { nonNegativeInt, positiveInt, sanitizeForTerminal, stringFlag } from "./messaging/shared.js";
+const SUBCOMMANDS = ["list", "read", "archive", "unarchive"];
+const OPTIONS = {
+    limit: { type: "string" },
+    offset: { type: "string" },
+    archived: { type: "boolean" },
+};
+const DEFAULT_LIMIT = 50;
+/** The Hub's server-side clamps on `GET /v1/messages`. Mirrored so the paging hint is computed
+ *  against the limit/offset the Hub ACTUALLY applied — a request above these is clamped server-side,
+ *  so a full clamped page compared against the raw request would wrongly report "no more" and a
+ *  scripted pager would stop early. Mirrors `messages.ts`. */
+const LIST_LIMIT_MAX = 200;
+const LIST_OFFSET_MAX = 10_000;
+/** A parsing ceiling — an absurd `--limit`/`--offset` is a usage error (exit 2) before any call. */
+const MAX_LIST_INT = 1_000_000;
+/** Strip the control characters `JSON.stringify` does NOT escape — **C1** (U+0080–U+009F, e.g.
+ *  U+009B CSI) and **DEL** (U+007F) — from every string in a value, recursively.
+ *
+ *  Deliberately NOT `sanitizeForTerminal`: that also strips C0, which includes the newlines a
+ *  message body legitimately contains, and preserving those is the entire reason this surface emits
+ *  rows with their structure intact. C0 needs no stripping here because `JSON.stringify` escapes it
+ *  (`\n`, `\u001b`), so it can never reach a terminal as a control. C1 and DEL are the gap. */
+function stripJsonUnsafeControls(value) {
+    if (typeof value === "string") {
+        let out = "";
+        for (const ch of value) {
+            const code = ch.codePointAt(0) ?? 0;
+            if (code !== 0x7f && !(code >= 0x80 && code <= 0x9f))
+                out += ch;
+        }
+        return out;
+    }
+    if (Array.isArray(value))
+        return value.map((v) => stripJsonUnsafeControls(v));
+    if (value !== null && typeof value === "object") {
+        const o = {};
+        for (const [k, v] of Object.entries(value)) {
+            o[stripJsonUnsafeControls(k)] = stripJsonUnsafeControls(v);
+        }
+        return o;
+    }
+    return value;
+}
+const EM_DASH = "—";
+export async function mailCommand(ctx) {
+    // Operands: the subcommand plus, for the triage verbs, one or more message ids.
+    const parsed = parseCommandArgs(ctx.argv, OPTIONS, { maxOperands: 64 });
+    const sub = parsed.positionals[1];
+    if (sub === undefined) {
+        throw new CliError("usage", `missing subcommand: expected one of ${SUBCOMMANDS.join(" | ")}.`);
+    }
+    if (!SUBCOMMANDS.includes(sub)) {
+        throw new CliError("usage", `unknown subcommand "${sub}": expected one of ${SUBCOMMANDS.join(" | ")}.`);
+    }
+    const ids = parsed.positionals.slice(2);
+    const flags = parsed.values;
+    // Flags are validated BEFORE credentials are touched (matches notify/messages): a bad invocation
+    // is exit 2 without opening the keychain.
+    const requestedLimit = flags.limit !== undefined ? positiveInt(stringFlag(flags.limit), "--limit", "a positive integer", MAX_LIST_INT) : DEFAULT_LIMIT;
+    const requestedOffset = flags.offset !== undefined ? nonNegativeInt(stringFlag(flags.offset), "--offset", "a non-negative integer", MAX_LIST_INT) : undefined;
+    // ARITY FIRST — before the credential lookup, not after.
+    // A malformed invocation (`mail read` with no id) is a USAGE error, and reporting it as an
+    // identity/auth error on a machine with no human identity selected sends the caller to fix the
+    // wrong thing entirely. It also opened — and could prompt — the OS keychain for an invocation
+    // that was never going to make a request. This does NOT weaken the gate below: arity is a purely
+    // local check, so the identity refusal still precedes every Hub call.
+    // `list` takes NO operands. Without this, `mail list message_1` opened credentials, contacted the
+    // Hub, and returned the WHOLE inbox while silently ignoring the argument — a caller who meant
+    // `mail read message_1` gets a plausible result for a question they did not ask.
+    if (sub === "list" && ids.length !== 0) {
+        throw new CliError("usage", "`oh-hai mail list` takes no message ids — did you mean `oh-hai mail read <id>`?");
+    }
+    if (sub === "read" && ids.length !== 1) {
+        throw new CliError("usage", "`oh-hai mail read` takes exactly one message id.");
+    }
+    if ((sub === "archive" || sub === "unarchive") && ids.length === 0) {
+        throw new CliError("usage", `\`oh-hai mail ${sub}\` takes one or more message ids.`);
+    }
+    // THE GATE. Before any request is composed, for every subcommand.
+    const { token } = await resolveMailIdentity(ctx);
+    if (sub === "list") {
+        // `flagOnStrict`, not `flagOn` and certainly not `=== true`. Two failure modes, one shape:
+        // under `strict: false` the supported `--archived=true` form arrives as the STRING "true", so an
+        // identity test reads it as off; and a TYPO (`--archived=treu`) is an unrecognized value that
+        // `flagOn` also reads as off. Both silently serve the ACTIVE inbox for an explicit request for
+        // the archived one — a plausible wrong view rather than an error, which is the failure this
+        // whole surface is built to avoid. `flagOnStrict` exists for exactly this: a value it does not
+        // recognize is a usage error, not a silent "off".
+        await mailList(ctx, token, requestedLimit, requestedOffset, flagOnStrict(flags.archived, "--archived"));
+        return;
+    }
+    if (sub === "read") {
+        await mailRead(ctx, token, ids[0]);
+        return;
+    }
+    return mailTriage(ctx, token, sub, ids);
+}
+async function mailList(ctx, token, requestedLimit, requestedOffset, archived) {
+    const limit = Math.min(requestedLimit, LIST_LIMIT_MAX);
+    const offset = requestedOffset !== undefined ? Math.min(requestedOffset, LIST_OFFSET_MAX) : undefined;
+    const view = archived ? "archived" : "active";
+    const messages = await listInbox(ctx, token, { limit, ...(offset !== undefined ? { offset } : {}), view });
+    const effectiveOffset = offset ?? 0;
+    const nextOffset = Math.min(effectiveOffset + messages.length, LIST_OFFSET_MAX);
+    const hasMore = messages.length === limit && effectiveOffset < LIST_OFFSET_MAX;
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("mail.list", stripJsonUnsafeControls({ messages, count: messages.length, view, has_more: hasMore, next_offset: nextOffset }))));
+        return;
+    }
+    if (messages.length === 0) {
+        ctx.io.log(archived ? "No archived messages." : "No messages.");
+        return;
+    }
+    const rows = messages.map(toRow);
+    const display = [{ id: "ID", type: "TYPE", status: "STATUS", title: "TITLE", created: "CREATED" }, ...rows];
+    const idW = colWidth(display, "id");
+    const typeW = colWidth(display, "type");
+    const statusW = colWidth(display, "status");
+    const titleW = colWidth(display, "title");
+    for (const r of display) {
+        ctx.io.log(`${r.id.padEnd(idW)}  ${r.type.padEnd(typeW)}  ${r.status.padEnd(statusW)}  ${r.title.padEnd(titleW)}  ${r.created}`);
+    }
+    if (hasMore)
+        ctx.io.err(`(more — re-run with --offset ${nextOffset})`);
+}
+async function mailRead(ctx, token, id) {
+    const message = await readMessage(ctx, token, id);
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("mail.read", stripJsonUnsafeControls({ message }))));
+        return;
+    }
+    // The human view prints the index fields plus the body, each sanitized. The body is the one
+    // multi-line field, so it is printed last and on its own lines rather than squeezed into a table.
+    const row = toRow(message);
+    ctx.io.log(`${row.id}  ${row.type}  ${row.status}`);
+    ctx.io.log(`title:   ${row.title}`);
+    ctx.io.log(`created: ${row.created}`);
+    const body = typeof message.body === "string" ? message.body : undefined;
+    if (body !== undefined) {
+        ctx.io.log("");
+        for (const line of body.split("\n"))
+            ctx.io.log(sanitizeForTerminal(line));
+    }
+}
+async function mailTriage(ctx, token, verb, ids) {
+    if (ids.length === 0)
+        throw new CliError("usage", `\`oh-hai mail ${verb}\` takes one or more message ids.`);
+    // Per-id outcome, deliberately: collapsing a partial failure into one status would report a batch
+    // as failed when most of it succeeded, and leave the caller unable to tell which ids to retry.
+    const results = [];
+    for (const id of ids) {
+        try {
+            await triage(ctx, token, id, verb);
+            results.push({ id, ok: true });
+        }
+        catch (error) {
+            // ONLY A GENUINELY PER-MESSAGE CONDITION STAYS PER-ID — an ALLOWLIST, not a denylist.
+            //
+            // An earlier revision rethrew just `auth` and `network`, which fixed two cells of a family and
+            // left the rest: a timeout still collapsed to exit 1 instead of the timeout tier, a Hub 5xx
+            // lost the server tier, and the loop re-attempted every id against a condition that could not
+            // improve. The failure classes are open-ended, so enumerating the batch-wide ones can never be
+            // complete; enumerating the PER-ID ones can, because they are the only classes that say
+            // something about THIS message rather than about the request as a whole.
+            // The allowlist, spelled with the §7 codes that actually exist: a message that is absent, in
+            // a conflicting state, or named by a request the Hub rejected as malformed. Everything else —
+            // auth, network, server, timeout, and every code not yet invented — is about the request as a
+            // whole and stops the batch.
+            const PER_MESSAGE = new Set(["not_found", "conflict", "bad_request", "validation_error"]);
+            const perMessage = error instanceof CliError && PER_MESSAGE.has(error.code);
+            if (!perMessage)
+                throw error;
+            results.push({ id, ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const failed = results.filter((r) => !r.ok);
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk(`mail.${verb}`, stripJsonUnsafeControls({ results, count: results.length, failed: failed.length }))));
+    }
+    else {
+        for (const r of results) {
+            if (r.ok)
+                ctx.io.log(`${verb}d ${sanitizeForTerminal(r.id)}`);
+            else
+                ctx.io.err(`FAILED ${sanitizeForTerminal(r.id)}: ${sanitizeForTerminal(r.error ?? "unknown error")}`);
+        }
+    }
+    // RETURN a non-zero code rather than THROWING, because stdout is already committed.
+    // Throwing here would make the dispatcher emit a SECOND `--json` envelope after the ok one, so a
+    // consumer reading the single-envelope contract (§8) gets two contradictory documents and
+    // commonly fails to parse — and the per-id results, the whole reason for reporting them, are
+    // absent from the error envelope that would arrive last. `doctor` returns its code for exactly
+    // this reason; the handler contract is `Promise<void | number>`.
+    return failed.length > 0 ? ExitCode.ERROR : ExitCode.SUCCESS;
+}
+/** Project a Hub row to sanitized, single-line index fields; absent fields render as an em dash. */
+function toRow(m) {
+    const one = (v) => (typeof v === "string" && v !== "" ? sanitizeForTerminal(v) : EM_DASH);
+    return { id: one(m.id), type: one(m.type), status: one(m.status), title: one(m.title), created: one(m.created_at) };
+}
+function colWidth(rows, key) {
+    return rows.reduce((w, r) => Math.max(w, r[key].length), 0);
+}
+//# sourceMappingURL=mail.js.map

package/dist/commands/mail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mail.js","sourceRoot":"","sources":["../../src/commands/mail.ts"],"names":[],"mappings":"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"}

package/dist/commands/messaging/capability.d.ts

@@ -29,7 +29,6 @@ export interface HubCapability {
         min_ttl_seconds?: number;
         max_ttl_seconds?: number;
         max_live_per_agent?: number;
-        agent_list_visibility?: boolean;
         terminal_retention_seconds?: number;
     };
     inter_agent?: {

package/dist/commands/messaging/capability.js

@@ -75,20 +75,19 @@ export async function fetchCapability(ctx) {
         return undefined;
     }
     const doc = body;
-    // `agent_list_visibility` is a GRANT and the only field a caller ACTS on — `fleet ls` turns it into
-    // the scope caption and into `data.scope` for scripts. A blind cast would read the STRING "false"
-    // as truthy and report the whole fleet for a list the Hub never said was account-wide. Anything
-    // that is not a real boolean is dropped, so it reads `unknown`: the honest answer for a document
-    // that did not say.
+    // `sessions` is read for its `enabled` flag (the §8.7.1 session-drain gate below), so a value that
+    // is not an object is dropped rather than cast — a non-object would make `sessions?.enabled` throw
+    // or silently read undefined off a string.
+    //
+    // The per-field `agent_list_visibility` sanitizer that used to live here is GONE with #860: it
+    // existed only because `fleet ls` ACTED on that field. The Hub still advertises it — it states the
+    // deployment ceiling — but it is only half the §16.4 answer, so the CLI reads the authenticated
+    // `scope` on `GET /v1/sessions` instead and ignores this field entirely. Nothing here reads it, so
+    // there is nothing to sanitize.
     const sessions = doc.sessions;
-    if (sessions !== null && typeof sessions === "object" && !Array.isArray(sessions)) {
-        const visibility = sessions.agent_list_visibility;
-        if (visibility !== undefined && typeof visibility !== "boolean") {
-            delete sessions.agent_list_visibility;
-        }
-    }
-    else if (sessions !== undefined) {
-        delete doc.sessions;
+    if (sessions === null || typeof sessions !== "object" || Array.isArray(sessions)) {
+        if (sessions !== undefined)
+            delete doc.sessions;
     }
     const capability = doc;
     CACHE.set(key, capability);

package/dist/commands/messaging/capability.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/commands/messaging/capability.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../../../src/commands/messaging/capability.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,0CAA0C;AAC1C,EAAE;AACF,sGAAsG;AACtG,mGAAmG;AACnG,oGAAoG;AACpG,mGAAmG;AACnG,mGAAmG;AACnG,kGAAkG;AAClG,EAAE;AACF,qGAAqG;AACrG,sGAAsG;AACtG,mGAAmG;AACnG,oGAAoG;AACpG,sGAAsG;AACtG,iGAAiG;AACjG,kDAAkD;AAClD,EAAE;AACF,sGAAsG;AACtG,sFAAsF;AAEtF,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA0C7C,0FAA0F;AAC1F,MAAM,gBAAgB,GAAG,CAAC,CAAC;AAE3B;;;wCAGwC;AACxC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEtD,qFAAqF;AACrF,MAAM,UAAU,oBAAoB;IAClC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED,gGAAgG;AAChG,SAAS,OAAO,CAAC,OAAgB;IAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAmB;IACvD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC;IAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,IAAI,SAAS,CAAC;IAErD,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,GAAG,CAAC,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxI,IAAI,GAAiB,CAAC;IACtB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,GAAG,gBAAgB,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClI,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC5E,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,mGAAmG;IACnG,mGAAmG;IACnG,2CAA2C;IAC3C,EAAE;IACF,+FAA+F;IAC/F,mGAAmG;IACnG,gGAAgG;IAChG,mGAAmG;IACnG,gCAAgC;IAChC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC9B,IAAI,QAAQ,KAAK,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjF,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,QAAQ,CAAC;IAClD,CAAC;IACD,MAAM,UAAU,GAAG,GAAoB,CAAC;IACxC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC3B,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,GAAmB,EAAE,EAAU;IAC7E,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,uBAAuB,EAAE,qCAAqC,GAAG,CAAC,MAAM,CAAC,OAAO,qCAAqC;YACnH,iHAAiH;YACjH,sGAAsG,CACzG,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,gBAAgB,EAAE,CAAC;QAC/C,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,uBAAuB,EAAE,4BAA4B,UAAU,CAAC,YAAY,IAAI,cAAc,mBAAmB;YAC/G,iIAAiI,CACpI,CAAC;IACJ,CAAC;IACD,kGAAkG;IAClG,iGAAiG;IACjG,IAAI,UAAU,CAAC,WAAW,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;QAC9C,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,uBAAuB,EAAE,yFAAyF,CACnH,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,GAAmB;IACnE,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,uDAAuD,GAAG,CAAC,MAAM,CAAC,OAAO,2CAA2C;YAClH,oHAAoH;YACpH,oHAAoH;YACpH,iCAAiC,CACpC,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;IAC/C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,gBAAgB,EAAE,CAAC;QAC/C,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,8CAA8C,UAAU,CAAC,YAAY,IAAI,cAAc,4BAA4B;YACjH,gHAAgH;YAChH,sEAAsE,CACzE,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,EAAE,OAAO,KAAK,KAAK,EAAE,CAAC;QAC3C,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,+GAA+G,CAAC,CAAC;IAC/I,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,EAAE,aAAa,KAAK,KAAK,EAAE,CAAC;QAChD,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,gIAAgI,CACjI,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/commands/messaging/http.d.ts

@@ -1,6 +1,6 @@
 import { type HubTouchpoint } from "@oh-hai/ma2h-core/errors";
 import { CliError } from "../../envelope.js";
-import type { CommandContext } from "../context.js";
+import type { CommandContext, HttpResponse } from "../context.js";
 import type { GetMessageBody, InboundDelivery, SubmitAck } from "./wire.js";
 /** POST /v1/inbox/ack — the ids of the directives consumed by this call (spec §14; the server's
  *  `ackDirectives` returns the id array, not a count). A TRANSPORT wrapper shape of this Hub's
@@ -67,3 +67,11 @@ export declare function ackInbox(ctx: CommandContext, token: string, ids: string
  *  the vendored §8.5 vocabulary — see `cliErrorCode`. The server message is stripped of terminal
  *  control chars (the top-level catch prints it). */
 export declare function statusToCliError(status: number, message: string | undefined, hubCode?: string, hint?: string, touchpoint?: HubTouchpoint): CliError;
+/** Parse a response body as a JSON object, defensively — a fake without `json()`, a non-JSON
+ *  body, or a non-object all collapse to `{}`, so callers read fields off a plain record. */
+export declare function readJson(res: HttpResponse): Promise<Record<string, unknown>>;
+/** Read the A2H error envelope `{ error: { code, message } }` from a non-2xx response. */
+export declare function readErrorEnvelope(res: HttpResponse): Promise<{
+    code: string | undefined;
+    message: string | undefined;
+}>;