@opvs-ai/cli 0.5.6 → 0.6.0

package/dist/commands/mail.js

@@ -1,8 +1,24 @@
 /**
- * opvs mail — OPVS Protocol messaging commands
+ * opvs mail — OPVS Protocol messaging commands.
+ *
+ * Two layers:
+ *   1. Server-facing commands (send, reply, resolve, claim, pair, …) —
+ *      hit the gateway and mirror the result to the local store.
+ *   2. Local-mirror commands (sync, watch, thread, list, search, unread,
+ *      status, ack, working, decline, flag, draft, awaiting, tickle,
+ *      sub, compact, log) — read/write the IMAP-style store at
+ *      ``~/.opvs/mail/`` shipped by ``@opvs-ai/core``'s mailstore.
+ *
+ * Per the IMAP-mail plan (`/root/.claude/plans/read-root-opvs-...`):
+ *   - No auto-seen — recipient must explicitly ``mail ack``.
+ *   - SLA fields are advisory, never server-enforced.
+ *   - Plus-addressing (``+suffix``) is first-class.
  */
-import { getEffectiveConfig, createClient } from "@opvs-ai/core";
+import { getEffectiveConfig, createClient, } from "@opvs-ai/core";
+import { mailstore } from "@opvs-ai/core";
 import { buildUrl, printResponse, printJson } from "../lib/format.js";
+import { registerInstallCommands } from "./install.js";
+import { readFileSync, existsSync, } from "node:fs";
 /** Map user-friendly type names to OPVS wire-format symbols. */
 const TYPE_SYMBOLS = {
     "?": "?", query: "?",
@@ -21,37 +37,112 @@ const PRIORITY_SYMBOLS = {
     normal: "",
     low: "",
 };
+/**
+ * Build a synthetic local Message from outbound send-context + the
+ * message_id returned by the server. Lets ``appendOutgoing`` mirror
+ * the send into ``~/.opvs/mail/objects/`` without an extra GET round-trip.
+ */
+function synthesizeOutgoingMessage(opts) {
+    // Split the optional +suffix out of from/to addresses.
+    const splitAddr = (addr) => {
+        const [local, tenant] = addr.includes("@") ? addr.split("@", 2) : [addr, null];
+        if (local.includes("+")) {
+            const [name, sub] = local.split("+", 2);
+            return { name, sub: sub || null, tenant: tenant ?? null };
+        }
+        return { name: local, sub: null, tenant: tenant ?? null };
+    };
+    const fromParts = splitAddr(opts.from);
+    const toParts = splitAddr(opts.to);
+    return {
+        id: opts.message_id,
+        thread_id: opts.thread_id ?? null,
+        reply_to_id: opts.reply_to_id ?? null,
+        from_agent: fromParts.name,
+        from_subaddress: fromParts.sub,
+        from_tenant: fromParts.tenant,
+        to_agent: toParts.name,
+        to_subaddress: toParts.sub,
+        to_tenant: toParts.tenant,
+        body: opts.body,
+        tags: opts.tags ?? [],
+        flags: [],
+        context: {},
+        message_type: opts.type,
+        priority: opts.priority === "critical" ? 0 : opts.priority === "high" ? 1 : opts.priority === "low" ? 3 : 2,
+        status: "delivered",
+        created_at: new Date().toISOString(),
+    };
+}
+/** Read a file, returning empty string if absent — for ``--body-file``. */
+function readBodyFromFile(path) {
+    if (!existsSync(path)) {
+        throw new Error(`Body file not found: ${path}`);
+    }
+    return readFileSync(path, "utf-8");
+}
+/** Pretty-print a message for ``mail read`` / ``mail thread``. */
+function printMessage(msg, opts) {
+    if (opts?.format === "json") {
+        printJson(msg);
+        return;
+    }
+    // Default: markdown-ish for agents to read.
+    const from = msg.from_agent + (msg.from_subaddress ? `+${msg.from_subaddress}` : "") +
+        (msg.from_tenant ? `::${msg.from_tenant}` : "");
+    const to = msg.to_agent
+        ? msg.to_agent + (msg.to_subaddress ? `+${msg.to_subaddress}` : "") + (msg.to_tenant ? `::${msg.to_tenant}` : "")
+        : msg.to_pool ? `|${msg.to_pool}` : msg.to_team ? `team:${msg.to_team}` : "*";
+    const status = msg.status ?? "delivered";
+    const tags = (msg.tags ?? []).map((t) => `#${t}`).join(" ");
+    console.log(`---`);
+    console.log(`id:      ${msg.id}`);
+    console.log(`thread:  ${msg.thread_id ?? ""}`);
+    console.log(`from:    ${from}`);
+    console.log(`to:      ${to}`);
+    console.log(`type:    ${msg.message_type ?? "."}    priority: ${msg.priority ?? 2}    status: ${status}`);
+    if (tags)
+        console.log(`tags:    ${tags}`);
+    console.log(`time:    ${msg.created_at}`);
+    console.log(``);
+    console.log(msg.body);
+    console.log(``);
+}
+// =============================================================
+// Register
+// =============================================================
 export function registerMailCommands(program) {
     const mail = program.command("mail").description("OPVS Protocol messaging");
-    // ── send ────────────────────────────────────────────────────
+    // ── server-facing: send / reply / inbox / read / resolve / claim ───
     mail
         .command("send <address> <message>")
         .description("Send an OPVS protocol message")
         .option("--priority <level>", "Priority: critical, high, medium, normal", "normal")
         .option("--tags <tags>", "Comma-separated tags")
-        .option("--type <type>", "Message type: ? ! ~ ^ . > < (or query, command, delegate, escalate, inform, handoff, reply)", ".")
+        .option("--type <type>", "Message type: ? ! ~ ^ . > < (or query/command/delegate/escalate/inform/handoff/reply)", ".")
         .option("--from <address>", "Sender address", "cli")
+        .option("--body-file <path>", "Read body from file instead of <message> arg")
+        .option("--no-mirror", "Skip writing to local store after send")
         .action(async (address, message, opts) => {
         const wsSlug = program.opts().workspace;
         const cfg = getEffectiveConfig(wsSlug);
         try {
             const typeSymbol = TYPE_SYMBOLS[opts.type] || ".";
             const priority = PRIORITY_SYMBOLS[opts.priority] || "";
-            const tagsPart = opts.tags
-                ? opts.tags.split(",").map((t) => `#${t.trim()}`).join(" ")
-                : "";
+            const tags = opts.tags
+                ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean)
+                : [];
+            const tagsPart = tags.map((t) => `#${t}`).join(" ");
             let header = `@${opts.from}>${address} ${typeSymbol}`;
             if (priority)
                 header += ` ${priority}`;
             if (tagsPart)
                 header += ` ${tagsPart}`;
-            const wireFormat = `${header}\n\n${message}`;
-            // Raw fetch — the core client always JSON-stringifies, but /send needs text/opvs
+            const bodyText = opts.bodyFile ? readBodyFromFile(opts.bodyFile) : message;
+            const wireFormat = `${header}\n\n${bodyText}`;
             const baseUrl = cfg.api_url.replace(/\/$/, "");
             const url = `${baseUrl}/api/v1/opvs/send`;
-            const headers = {
-                "Content-Type": "text/opvs",
-            };
+            const headers = { "Content-Type": "text/opvs" };
             if (cfg.token)
                 headers["Authorization"] = `Bearer ${cfg.token}`;
             if (cfg.brand_id)
@@ -61,15 +152,11 @@ export function registerMailCommands(program) {
                 let detail;
                 try {
                     const err = (await res.json());
-                    if (typeof err.detail === "string") {
-                        detail = err.detail;
-                    }
-                    else if (Array.isArray(err.detail)) {
-                        detail = err.detail.map((d) => d.msg || JSON.stringify(d)).join("; ");
-                    }
-                    else {
-                        detail = res.statusText;
-                    }
+                    detail = typeof err.detail === "string"
+                        ? err.detail
+                        : Array.isArray(err.detail)
+                            ? err.detail.map((d) => d.msg || JSON.stringify(d)).join("; ")
+                            : res.statusText;
                 }
                 catch {
                     detail = res.statusText;
@@ -77,21 +164,45 @@ export function registerMailCommands(program) {
                 console.error(`Error: ${detail}`);
                 process.exit(1);
             }
-            await printResponse(res);
+            const data = await res.json();
+            printJson(data);
+            // Mirror to local store unless caller opts out.
+            if (opts.mirror !== false && data.message_id) {
+                try {
+                    const synthesized = synthesizeOutgoingMessage({
+                        message_id: data.message_id,
+                        from: opts.from,
+                        to: address,
+                        type: typeSymbol,
+                        priority: opts.priority,
+                        tags,
+                        body: bodyText,
+                    });
+                    mailstore.appendOutgoing(synthesized);
+                }
+                catch (e) {
+                    // Mirror failure must not block the user — they got a server ack.
+                    console.error(`(warning) local mirror failed: ${e.message}`);
+                }
+            }
         }
         catch (err) {
             const e = err;
-            console.error(`Error: ${e.detail || "Failed to send message"}`);
+            console.error(`Error: ${e.detail || e.message || "Failed to send message"}`);
             process.exit(1);
         }
     });
-    // ── inbox ───────────────────────────────────────────────────
     mail
         .command("inbox")
-        .description("Fetch inbox messages")
+        .description("Fetch inbox messages from the server (use ``mail list`` for the local mirror)")
         .option("--limit <n>", "Max messages", "50")
         .option("--tags <tags>", "Filter by comma-separated tags")
         .option("--flags <flags>", "Filter by comma-separated flags")
+        .option("--since <id>", "Only return messages after this message id")
+        .option("--after <iso>", "Only return messages after this ISO timestamp")
+        .option("--suffix <s>", "Filter by recipient +suffix sub-address (empty string = no suffix)")
+        .option("--status <s>", "Filter by status (delivered, seen, working, …, or 'all')")
+        .option("--thread-id <id>", "Filter to one thread")
         .action(async (opts) => {
         const wsSlug = program.opts().workspace;
         const cfg = getEffectiveConfig(wsSlug);
@@ -104,6 +215,16 @@ export function registerMailCommands(program) {
                 params.tags = opts.tags;
             if (opts.flags)
                 params.flags = opts.flags;
+            if (opts.since)
+                params.since = opts.since;
+            if (opts.after)
+                params.after = opts.after;
+            if (opts.suffix !== undefined)
+                params.subaddress = opts.suffix;
+            if (opts.status)
+                params.status = opts.status;
+            if (opts.threadId)
+                params.thread_id = opts.threadId;
             const url = buildUrl("/api/v1/opvs/inbox", params, cfg.format);
             const res = await client.get(url);
             await printResponse(res);
@@ -114,18 +235,37 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── read ────────────────────────────────────────────────────
     mail
         .command("read <id>")
-        .description("Read a single message by ID")
-        .action(async (id) => {
+        .description("Read a single message — local first, server fallback")
+        .option("--remote", "Skip local cache and hit the server")
+        .option("--no-mirror", "Don't persist the fetched message locally")
+        .option("--format <fmt>", "Output: json or markdown (default markdown)")
+        .action(async (id, opts) => {
         const wsSlug = program.opts().workspace;
-        const cfg = getEffectiveConfig(wsSlug);
         try {
+            // Local-first lookup unless --remote
+            if (!opts.remote) {
+                const local = mailstore.readMessage(id);
+                if (local) {
+                    printMessage(local, { format: opts.format });
+                    // Mark viewed locally for the unread filter.
+                    mailstore.setFlag(id, "viewed", true);
+                    return;
+                }
+            }
             const client = createClient(wsSlug);
-            const url = buildUrl(`/api/v1/opvs/messages/${id}`, undefined, cfg.format);
-            const res = await client.get(url);
-            await printResponse(res);
+            const res = await client.get(`/api/v1/opvs/messages/${id}`);
+            const msg = await res.json();
+            if (opts.mirror !== false && msg && msg.id) {
+                try {
+                    mailstore.appendIncoming(msg);
+                }
+                catch { /* non-fatal */ }
+            }
+            if (msg)
+                mailstore.setFlag(id, "viewed", true);
+            printMessage(msg, { format: opts.format });
         }
         catch (err) {
             const e = err;
@@ -133,20 +273,53 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── reply ───────────────────────────────────────────────────
     mail
         .command("reply <id> <message>")
         .description("Reply to a message")
-        .action(async (id, message) => {
+        .option("--body-file <path>", "Read body from file instead of <message> arg")
+        .option("--no-mirror", "Skip writing to local store after reply")
+        .action(async (id, message, opts) => {
         const wsSlug = program.opts().workspace;
         try {
             const client = createClient(wsSlug);
+            const bodyText = opts.bodyFile ? readBodyFromFile(opts.bodyFile) : message;
             const res = await client.post("/api/v1/opvs/reply", {
                 message_id: id,
-                body: message,
+                body: bodyText,
             });
             const data = await res.json();
             printJson(data);
+            // Mirror reply locally — we know the original to recover thread_id.
+            if (opts.mirror !== false && data.message_id) {
+                try {
+                    const original = mailstore.readMessage(id);
+                    const cfg = getEffectiveConfig(wsSlug);
+                    const synthesized = {
+                        id: data.message_id,
+                        thread_id: original?.thread_id ?? id,
+                        reply_to_id: id,
+                        from_agent: "cli",
+                        from_tenant: null,
+                        from_subaddress: null,
+                        to_agent: original?.from_agent ?? null,
+                        to_tenant: original?.from_tenant ?? null,
+                        to_subaddress: original?.from_subaddress ?? null,
+                        body: bodyText,
+                        tags: [],
+                        flags: [],
+                        context: {},
+                        message_type: "<",
+                        priority: 2,
+                        status: "delivered",
+                        created_at: new Date().toISOString(),
+                    };
+                    void cfg;
+                    mailstore.appendOutgoing(synthesized);
+                }
+                catch (e) {
+                    console.error(`(warning) local mirror failed: ${e.message}`);
+                }
+            }
         }
         catch (err) {
             const e = err;
@@ -154,19 +327,21 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── resolve ─────────────────────────────────────────────────
     mail
         .command("resolve <id>")
-        .description("Mark a message as resolved")
+        .description("Mark a message as resolved (recipient only)")
         .action(async (id) => {
         const wsSlug = program.opts().workspace;
         try {
             const client = createClient(wsSlug);
-            const res = await client.post("/api/v1/opvs/resolve", {
-                message_id: id,
-            });
+            const res = await client.post("/api/v1/opvs/resolve", { message_id: id });
             const data = await res.json();
             printJson(data);
+            // Mirror status locally.
+            try {
+                mailstore.setStatus(id, "resolved");
+            }
+            catch { /* non-fatal */ }
         }
         catch (err) {
             const e = err;
@@ -174,7 +349,6 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── claim ───────────────────────────────────────────────────
     mail
         .command("claim")
         .description("Claim next message from a pool")
@@ -193,6 +367,12 @@ export function registerMailCommands(program) {
             const res = await client.post("/api/v1/opvs/claim", body);
             const data = await res.json();
             printJson(data);
+            if (data && data.id) {
+                try {
+                    mailstore.appendIncoming(data);
+                }
+                catch { /* non-fatal */ }
+            }
         }
         catch (err) {
             const e = err;
@@ -200,7 +380,6 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── pair ────────────────────────────────────────────────────
     mail
         .command("pair <address>")
         .description("Initiate pairing with another agent")
@@ -222,7 +401,6 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── agents ──────────────────────────────────────────────────
     mail
         .command("agents")
         .description("List registered OPVS agents")
@@ -251,7 +429,6 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
-    // ── register ────────────────────────────────────────────────
     mail
         .command("register")
         .description("Register a new OPVS agent address")
@@ -285,5 +462,488 @@ export function registerMailCommands(program) {
             process.exit(1);
         }
     });
+    // ─── local mirror: sync / watch ─────────────────────────────────────
+    mail
+        .command("sync")
+        .description("Pull new inbox messages from the server into the local store")
+        .option("--limit <n>", "Batch size per request", "100")
+        .option("--max-batches <n>", "Maximum batches per call", "50")
+        .option("--initial", "Force initial drain (ignore cursor file)")
+        .option("--refresh-status", "Also refresh server status for non-terminal sent messages")
+        .action(async (opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const client = createClient(wsSlug);
+            // Wrap the APIClient in a SyncHttpClient — patch is wired so
+            // ``mail ack`` shares the same client shape.
+            const syncClient = {
+                get: (path, h) => client.get(path, h),
+                patch: (path, body, h) => client.patch(path, body, h),
+            };
+            if (opts.initial) {
+                // Wipe cursor so the inbox endpoint walks everything.
+                mailstore.setCursor("", undefined);
+            }
+            const result = await mailstore.syncIncremental(syncClient, {
+                batchSize: parseInt(opts.limit, 10),
+                maxBatches: parseInt(opts.maxBatches, 10),
+                refreshStatus: !!opts.refreshStatus,
+            });
+            printJson(result);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || e.message || "Failed to sync"}`);
+            process.exit(1);
+        }
+    });
+    mail
+        .command("watch")
+        .description("Stream live inbox events via SSE (long-running)")
+        .option("--filter <suffix>", "Only emit messages with this +suffix")
+        .option("--quiet", "Don't print arrivals (just persist)")
+        .action(async (opts) => {
+        const wsSlug = program.opts().workspace;
+        const cfg = getEffectiveConfig(wsSlug);
+        const ctrl = new AbortController();
+        process.on("SIGINT", () => { ctrl.abort(); });
+        try {
+            await mailstore.watchLive({
+                apiUrl: cfg.api_url,
+                token: cfg.token,
+                brandId: cfg.brand_id ?? null,
+                filterSuffix: opts.filter,
+                signal: ctrl.signal,
+                onMessage: (m) => {
+                    if (!opts.quiet) {
+                        console.log(`📨 ${m.id} ${m.from_agent}${m.from_subaddress ? "+" + m.from_subaddress : ""} → ${m.to_agent}${m.to_subaddress ? "+" + m.to_subaddress : ""}`);
+                    }
+                },
+                onStatusChange: (e) => {
+                    if (!opts.quiet) {
+                        console.log(`🔁 ${e.message_id}  ${e.old_status ?? "?"} → ${e.new_status}`);
+                    }
+                },
+                onReady: ({ reconnects }) => {
+                    if (!opts.quiet)
+                        console.log(`✅ stream ready${reconnects ? ` (after ${reconnects} reconnects)` : ""}`);
+                },
+                onError: (err, attempt) => {
+                    console.error(`(warning) stream error attempt ${attempt}: ${err.message ?? String(err)}`);
+                },
+            });
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || e.message || "Watch failed"}`);
+            process.exit(1);
+        }
+    });
+    // ─── local-only reads: thread / list / search / unread / status ───
+    mail
+        .command("thread <id>")
+        .description("Print full thread chronologically (local first, server fallback)")
+        .option("--remote", "Skip local cache and hit the server")
+        .option("--format <fmt>", "Output: json or markdown (default markdown)")
+        .action(async (id, opts) => {
+        const wsSlug = program.opts().workspace;
+        if (!opts.remote) {
+            const local = mailstore.readThread(id);
+            if (local && local.length > 0) {
+                if (opts.format === "json")
+                    printJson(local);
+                else
+                    for (const msg of local)
+                        printMessage(msg, opts);
+                return;
+            }
+        }
+        // Server fallback
+        try {
+            const client = createClient(wsSlug);
+            const res = await client.get(`/api/v1/opvs/threads/${id}`);
+            const data = await res.json();
+            const msgs = data.messages ?? [];
+            // Persist on fetch.
+            for (const m of msgs) {
+                try {
+                    mailstore.appendIncoming(m);
+                }
+                catch { /* non-fatal */ }
+            }
+            if (opts.format === "json")
+                printJson(msgs);
+            else
+                for (const m of msgs)
+                    printMessage(m, opts);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to read thread"}`);
+            process.exit(1);
+        }
+    });
+    mail
+        .command("list")
+        .description("List local inbox messages (use ``mail inbox`` for the remote view)")
+        .option("--limit <n>", "Max messages", "50")
+        .option("--unread", "Only unread (flags.viewed unset)")
+        .option("--late", "Only messages past their advisory SLA")
+        .option("--suffix <s>", "Filter by recipient +suffix (empty string = no suffix)")
+        .option("--tag <t>", "Filter by tag (repeat or comma-separated)")
+        .option("--from <addr>", "Filter by sender")
+        .option("--since <iso>", "Only messages newer than this ISO timestamp")
+        .option("--status <s>", "Filter by server status")
+        .option("--format <fmt>", "Output: json or markdown (default markdown)")
+        .action((opts) => {
+        const tags = opts.tag ? opts.tag.split(",").map((t) => t.trim()).filter(Boolean) : undefined;
+        const out = mailstore.readInbox({
+            limit: parseInt(opts.limit, 10),
+            unread: !!opts.unread,
+            suffix: opts.suffix,
+            tags,
+            since: opts.since,
+            status: opts.status,
+        });
+        // ``--from`` is a post-filter (cheap on already-hydrated messages).
+        let filtered = out;
+        if (opts.from) {
+            filtered = filtered.filter((m) => m.from_agent === opts.from);
+        }
+        if (opts.format === "json")
+            printJson(filtered);
+        else
+            for (const m of filtered)
+                printMessage(m, opts);
+    });
+    mail
+        .command("search <query>")
+        .description("Grep across all locally-stored messages (body / tags / addresses)")
+        .option("--limit <n>", "Max results", "50")
+        .option("--thread <id>", "Restrict to one thread")
+        .option("--suffix <s>", "Restrict to one sub-address")
+        .option("--format <fmt>", "Output: json or markdown (default markdown)")
+        .action((query, opts) => {
+        const hits = mailstore.searchLocal(query, {
+            limit: parseInt(opts.limit, 10),
+            thread_id: opts.thread,
+            suffix: opts.suffix,
+        });
+        if (opts.format === "json")
+            printJson(hits);
+        else
+            for (const m of hits)
+                printMessage(m, opts);
+    });
+    mail
+        .command("unread")
+        .description("Print unread count + a short summary")
+        .option("--count-only", "Print just the integer count")
+        .action((opts) => {
+        const all = mailstore.readInbox({ limit: 10000, unread: true });
+        if (opts.countOnly) {
+            console.log(String(all.length));
+            return;
+        }
+        console.log(`${all.length} unread`);
+        for (const m of all.slice(0, 20)) {
+            const subj = (m.body ?? "").split("\n")[0].slice(0, 100);
+            console.log(`  ${m.id.slice(0, 8)}  ${m.from_agent}${m.from_subaddress ? "+" + m.from_subaddress : ""}  ${subj}`);
+        }
+        if (all.length > 20)
+            console.log(`  … and ${all.length - 20} more`);
+    });
+    mail
+        .command("status [id]")
+        .description("Show full status state for one message, or counts across all")
+        .action((id) => {
+        if (id) {
+            const local = mailstore.readMessage(id);
+            const status = mailstore.getStatus(id);
+            printJson({
+                id,
+                local_status: status?.status ?? null,
+                updated_at: status?.updated_at ?? null,
+                message_status: local?.status ?? null,
+                flags: mailstore.getFlags(id),
+            });
+            return;
+        }
+        // Aggregate all statuses.
+        const all = mailstore.getAllStatus();
+        const counts = {};
+        for (const entry of Object.values(all)) {
+            counts[entry.status] = (counts[entry.status] ?? 0) + 1;
+        }
+        printJson(counts);
+    });
+    // ─── status mutations: ack / working / decline ─────────────────────
+    function statusCmd(name, description) {
+        mail
+            .command(`${name === "seen" ? "ack" : name} <id>`)
+            .description(description)
+            .action(async (id) => {
+            const wsSlug = program.opts().workspace;
+            try {
+                const client = createClient(wsSlug);
+                const result = await mailstore.patchMessageStatus({ get: (p, h) => client.get(p, h), patch: (p, b, h) => client.patch(p, b, h) }, id, name);
+                printJson(result);
+            }
+            catch (err) {
+                const e = err;
+                console.error(`Error: ${e.detail || e.message || `Failed to ${name}`}`);
+                process.exit(1);
+            }
+        });
+    }
+    statusCmd("seen", "Acknowledge receipt of a message — sets server status `seen` (no auto-seen)");
+    statusCmd("working", "Mark a message as in-progress — sets server status `working`");
+    statusCmd("declined", "Decline a message — sets server status `declined`");
+    statusCmd("failed", "Mark a message as failed — sets server status `failed`");
+    // ─── local-only flags ──────────────────────────────────────────────
+    mail
+        .command("flag <id>")
+        .description("Star a message locally (does not touch the server)")
+        .action((id) => {
+        mailstore.setFlag(id, "flagged", true);
+        console.log(`flagged ${id}`);
+    });
+    mail
+        .command("unflag <id>")
+        .description("Unstar a message locally")
+        .action((id) => {
+        mailstore.setFlag(id, "flagged", false);
+        console.log(`unflagged ${id}`);
+    });
+    mail
+        .command("mark-viewed <id>")
+        .description("Mark a message as viewed locally (UX only — server status untouched)")
+        .action((id) => {
+        mailstore.setFlag(id, "viewed", true);
+        console.log(`viewed ${id}`);
+    });
+    // ─── drafts ────────────────────────────────────────────────────────
+    const draft = mail.command("draft").description("Compose-and-park drafts (analog of git stash)");
+    draft
+        .command("save <to> <body>")
+        .description("Save a draft message (use ``--body-file`` for longer bodies)")
+        .option("--body-file <path>", "Read body from file instead of <body> arg")
+        .option("--type <t>", "Message type symbol or name", ".")
+        .option("--priority <p>", "Priority", "normal")
+        .option("--tags <tags>", "Comma-separated tags")
+        .action((to, body, opts) => {
+        const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean) : [];
+        const bodyText = opts.bodyFile ? readBodyFromFile(opts.bodyFile) : body;
+        const saved = mailstore.saveDraft({
+            to,
+            type: opts.type,
+            priority: opts.priority,
+            tags,
+            body: bodyText,
+        });
+        printJson(saved);
+    });
+    draft
+        .command("list")
+        .description("List drafts (newest first)")
+        .action(() => {
+        const all = mailstore.listDrafts();
+        printJson(all);
+    });
+    draft
+        .command("show <id>")
+        .description("Print one draft")
+        .action((id) => {
+        const d = mailstore.loadDraft(id);
+        if (!d) {
+            console.error(`Draft ${id} not found`);
+            process.exit(1);
+        }
+        printJson(d);
+    });
+    draft
+        .command("send <id>")
+        .description("Send a saved draft and remove it from drafts/")
+        .option("--no-mirror", "Skip writing to local store after send")
+        .action(async (id, opts) => {
+        const d = mailstore.loadDraft(id);
+        if (!d) {
+            console.error(`Draft ${id} not found`);
+            process.exit(1);
+        }
+        const wsSlug = program.opts().workspace;
+        const cfg = getEffectiveConfig(wsSlug);
+        try {
+            const typeSymbol = TYPE_SYMBOLS[d.type ?? "."] || ".";
+            const priority = PRIORITY_SYMBOLS[d.priority ?? "normal"] || "";
+            const tagsPart = (d.tags ?? []).map((t) => `#${t}`).join(" ");
+            let header = `@cli>${d.to} ${typeSymbol}`;
+            if (priority)
+                header += ` ${priority}`;
+            if (tagsPart)
+                header += ` ${tagsPart}`;
+            const wireFormat = `${header}\n\n${d.body}`;
+            const baseUrl = cfg.api_url.replace(/\/$/, "");
+            const headers = { "Content-Type": "text/opvs" };
+            if (cfg.token)
+                headers["Authorization"] = `Bearer ${cfg.token}`;
+            if (cfg.brand_id)
+                headers["X-Brand-ID"] = String(cfg.brand_id);
+            const res = await fetch(`${baseUrl}/api/v1/opvs/send`, { method: "POST", headers, body: wireFormat });
+            if (!res.ok) {
+                let detail;
+                try {
+                    detail = (await res.json()).detail ?? res.statusText;
+                }
+                catch {
+                    detail = res.statusText;
+                }
+                console.error(`Error: ${detail}`);
+                process.exit(1);
+            }
+            const data = await res.json();
+            printJson(data);
+            if (opts.mirror !== false && data.message_id) {
+                try {
+                    mailstore.appendOutgoing(synthesizeOutgoingMessage({
+                        message_id: data.message_id,
+                        from: "cli",
+                        to: d.to,
+                        type: typeSymbol,
+                        priority: d.priority,
+                        tags: d.tags,
+                        body: d.body,
+                    }));
+                }
+                catch { /* non-fatal */ }
+            }
+            mailstore.deleteDraft(id);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || e.message || "Failed to send draft"}`);
+            process.exit(1);
+        }
+    });
+    draft
+        .command("delete <id>")
+        .description("Delete a draft without sending")
+        .action((id) => {
+        const ok = mailstore.deleteDraft(id);
+        console.log(ok ? `deleted ${id}` : `not found ${id}`);
+    });
+    // ─── advisory SLA ──────────────────────────────────────────────────
+    mail
+        .command("awaiting")
+        .description("List sent messages still pre-resolved past their advisory SLA")
+        .option("--late-only", "Only those past $expected_seen_in / $expected_done_in")
+        .option("--limit <n>", "Max results", "100")
+        .option("--format <fmt>", "Output: json or markdown")
+        .action((opts) => {
+        const all = mailstore.listAwaiting({
+            late_only: !!opts.lateOnly,
+            limit: parseInt(opts.limit, 10),
+        });
+        if (opts.format === "markdown" || opts.format === "md") {
+            for (const e of all) {
+                const tag = e.is_late ? "⚠️ LATE" : "⏳";
+                console.log(`${tag}  ${e.id.slice(0, 8)}  → ${e.to}  status=${e.status}  sent=${e.sent_at}`);
+            }
+            return;
+        }
+        printJson(all);
+    });
+    mail
+        .command("tickle <id>")
+        .description("Send a polite follow-up ping in the same thread as <id>")
+        .option("--message <text>", "Custom ping message", "Just bumping this — any update?")
+        .action(async (id, opts) => {
+        const wsSlug = program.opts().workspace;
+        try {
+            const client = createClient(wsSlug);
+            const res = await client.post("/api/v1/opvs/reply", {
+                message_id: id,
+                body: opts.message,
+            });
+            const data = await res.json();
+            printJson(data);
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || "Failed to tickle"}`);
+            process.exit(1);
+        }
+    });
+    // ─── sub-addresses ─────────────────────────────────────────────────
+    const sub = mail.command("sub").description("Sub-address (+suffix) helpers");
+    sub
+        .command("list")
+        .description("List sub-addresses with message counts")
+        .action(() => {
+        printJson(mailstore.listSubAddresses());
+    });
+    sub
+        .command("watch <suffix>")
+        .description("Stream live events for messages addressed to ``+<suffix>``")
+        .action(async (suffix) => {
+        const wsSlug = program.opts().workspace;
+        const cfg = getEffectiveConfig(wsSlug);
+        const ctrl = new AbortController();
+        process.on("SIGINT", () => { ctrl.abort(); });
+        try {
+            await mailstore.watchLive({
+                apiUrl: cfg.api_url,
+                token: cfg.token,
+                brandId: cfg.brand_id ?? null,
+                filterSuffix: suffix,
+                signal: ctrl.signal,
+                onMessage: (m) => console.log(`📨 ${m.id}  ${m.body.split("\n")[0].slice(0, 80)}`),
+                onStatusChange: (e) => console.log(`🔁 ${e.message_id} → ${e.new_status}`),
+            });
+        }
+        catch (err) {
+            const e = err;
+            console.error(`Error: ${e.detail || e.message || "Watch failed"}`);
+            process.exit(1);
+        }
+    });
+    // ─── compact + log ──────────────────────────────────────────────────
+    mail
+        .command("compact")
+        .description("Archive + prune messages older than the cutoff (git gc analog)")
+        .option("--older-than <days>", "Age in days", "90")
+        .action((opts) => {
+        const result = mailstore.compact({ olderThanDays: parseInt(opts.olderThan, 10) });
+        printJson(result);
+    });
+    mail
+        .command("log")
+        .description("Print the local reflog (every action recorded)")
+        .option("--limit <n>", "Max entries", "100")
+        .option("--since <iso>", "Only entries newer than this ISO timestamp")
+        .option("--search <q>", "Substring search")
+        .action((opts) => {
+        const limit = parseInt(opts.limit, 10);
+        const entries = opts.search
+            ? mailstore.searchLog(opts.search, { limit })
+            : mailstore.tailLog({ limit, since: opts.since });
+        printJson(entries);
+    });
+    mail
+        .command("verify")
+        .description("Run integrity checks on the local store")
+        .action(() => {
+        const report = mailstore.verifyIntegrity();
+        printJson(report);
+    });
+    mail
+        .command("rebuild-index")
+        .description("Rebuild the message-id lookup index from objects/")
+        .action(() => {
+        const result = mailstore.rebuildIndex();
+        printJson(result);
+    });
+    // Phase E + F — slash commands installer + hooks installer + daemon control
+    registerInstallCommands(mail);
 }
 //# sourceMappingURL=mail.js.map