greprag 5.22.2 → 5.23.0

package/dist/index.js

@@ -55,6 +55,7 @@ const checkpoint_1 = require("./commands/checkpoint");
 const identity_1 = require("./commands/identity");
 const skill_1 = require("./commands/skill");
 const project_1 = require("./commands/project");
+const email_1 = require("./commands/email");
 const codex_1 = require("./commands/codex");
 const inbox_retract_1 = require("./commands/inbox-retract");
 const inbox_watch_1 = require("./commands/inbox-watch");
@@ -179,19 +180,30 @@ async function apiDelete(url, apiKey) {
 }
 const INBOX_HELP = `greprag inbox — read + manage your async message inbox.
 
-  greprag inbox                     List unread messages (marks them read).
-  greprag inbox --all               Include already-read messages.
+  greprag inbox                     List unread for THIS session: its own lines
+                                    (sender or recipient) + the front desk
+                                    (tenant catch-all) + project broadcasts.
+                                    Other sessions' private lines are hidden.
+  greprag inbox --all               Audit peek: drop the per-session scope (every
+                                    session's lines) AND include already-read.
   greprag inbox --peek              List WITHOUT marking read (non-mutating).
-  greprag inbox --session <8hex>    Filter to messages targeting one session.
+  greprag inbox --session <8hex>    Scope to one specific session's view.
   greprag inbox --project <name>    Filter to one project's inbox.
   greprag inbox watch [...]         Long-lived SSE stream (run under Monitor).
+    [--receptionist]                Attend the front desk — wake live on a cold
+                                    open / inbound email (else only manual check).
   greprag inbox watchers [--json]   List live armed watchers under your tenant.
+  greprag inbox claim <id>          Receptionist: claim a front-desk record so a
+                                    co-armed receptionist stands down (no dup reply).
   greprag inbox keep <id>           Extend a message's TTL.
   greprag inbox delete <id>         Delete a message.
 
 To SEND or REPLY (top-level command, NOT an inbox subcommand):
   greprag send --to discord:<snowflake> "reply"            Reply to a Discord DM.
-  greprag send "msg" --to <handle>@greprag.com/<target>    Message a session/project.`;
+  greprag send "msg" --to <handle>@greprag.com              Cold open (tenant catch-all).
+  greprag send "msg" --to <handle>@greprag.com/<target>    Message a session/project.
+  greprag send "msg" --to <h>@greprag.com/<session> --in-reply-to <front-desk-id>
+                                                           Reply that threads a cold open.`;
 /** greprag inbox [--all] [--session <id>] | inbox keep <id> | inbox delete <id> | inbox watch */
 async function inbox(args) {
     const cfg = getConfig();
@@ -207,7 +219,7 @@ async function inbox(args) {
     // A non-flag first arg that isn't a known subcommand is a typo — do NOT fall
     // through to list mode (which auto-marks every message read). The classic
     // slip is `inbox send` (the real reply command is top-level `greprag send`).
-    if (sub && !sub.startsWith('-') && !['watch', 'watchers', 'keep', 'delete'].includes(sub)) {
+    if (sub && !sub.startsWith('-') && !['watch', 'watchers', 'keep', 'delete', 'claim'].includes(sub)) {
         if (sub === 'send') {
             console.error('`greprag inbox send` is not a command. To reply (e.g. to a Discord DM):');
             console.error('  greprag send --to discord:<snowflake> "your message"');
@@ -225,6 +237,9 @@ async function inbox(args) {
             session: getFlag(subArgs, '--session'),
             since: getFlag(subArgs, '--since'),
             json: subArgs.includes('--json'),
+            // --receptionist: attend the front desk — wake live on tenant catch-all
+            // (cold open / inbound email). adr: adr/address-grammar.md
+            receptionist: subArgs.includes('--receptionist'),
         });
         return;
     }
@@ -271,12 +286,47 @@ async function inbox(args) {
         }
         return;
     }
+    if (sub === 'claim') {
+        // Receptionist claims a front-desk record (cold open / inbound email).
+        // First claimant wins; a loser stands down — no double-reply when more
+        // than one receptionist is armed. adr: adr/address-grammar.md
+        const id = args[1];
+        if (!id) {
+            console.error('Usage: greprag inbox claim <front-desk-id>  [--session <8-hex>]');
+            process.exit(1);
+        }
+        const claimant = getFlag(args, '--session')
+            || process.env.CLAUDE_SESSION_ID || process.env.GREPRAG_SESSION_ID;
+        if (!claimant) {
+            console.error('No session id to claim as. Pass --session <8-hex>, or run inside a Claude Code session.');
+            process.exit(1);
+        }
+        const r = await apiCall(`${cfg.apiUrl}/v1/inbox/handle/${id}`, cfg.apiKey, { session_id: claimant });
+        if (r.claimed) {
+            console.log(`Claimed ${id.slice(0, 8)} as receptionist (session ${(0, session_id_1.truncateSessionId)(claimant) ?? claimant}).`);
+            console.log(`  Reply with: greprag send "..." --to <sender>@greprag.com/<their-session> --in-reply-to ${id.slice(0, 8)} --from-session ${(0, session_id_1.truncateSessionId)(claimant) ?? claimant}`);
+        }
+        else {
+            const handledBy = r.handled_by ?? null;
+            const holder = handledBy ? ((0, session_id_1.truncateSessionId)(handledBy) ?? handledBy) : 'another session';
+            console.log(`Already handled by ${holder} — standing down (no double-reply).`);
+        }
+        return;
+    }
     const includeAll = args.includes('--all');
-    const sessionId = getFlag(args, '--session');
+    const explicitSession = getFlag(args, '--session');
     const projectFlag = getFlag(args, '--project');
     // --peek: non-mutating inspection. Orchestrator-mode uses this to survey
     // other sessions' inboxes without burning unread state for them.
     const peek = args.includes('--peek');
+    // Default view auto-scopes to THIS session — its own lines (sender OR
+    // recipient) + the front desk (tenant catch-all) + project broadcasts. Other
+    // sessions' private session↔session lines are hidden. `--all` drops the scope
+    // for a tenant-wide audit peek across every session. An explicit `--session`
+    // always scopes to that id. adr: adr/address-grammar.md
+    const autoSession = process.env.CLAUDE_SESSION_ID || process.env.GREPRAG_SESSION_ID || null;
+    const sessionId = explicitSession || (includeAll ? null : autoSession);
+    const scopedToSelf = !explicitSession && !includeAll && !!autoSession;
     const params = new URLSearchParams();
     if (includeAll)
         params.set('include', 'all');
@@ -299,8 +349,15 @@ async function inbox(args) {
     const url = `${cfg.apiUrl}/v1/inbox${qs ? '?' + qs : ''}`;
     const result = await apiGet(url, cfg.apiKey);
     const messages = (result.messages || []);
+    // Faint reminder that the default view is scoped to this session — other
+    // sessions' private lines (and the rest) are one `--all` away.
+    const scopeHint = scopedToSelf
+        ? `(scoped to session ${(0, session_id_1.truncateSessionId)(autoSession) ?? autoSession} — \`greprag inbox --all\` shows every session)`
+        : '';
     if (messages.length === 0) {
         console.log(includeAll ? 'No messages.' : 'No unread messages.');
+        if (scopeHint)
+            console.log(scopeHint);
         return;
     }
     const unreadCount = messages.filter(m => m.was_unread).length;
@@ -310,10 +367,18 @@ async function inbox(args) {
     else {
         console.log(`${messages.length} message(s):\n`);
     }
+    if (scopeHint)
+        console.log(`${scopeHint}\n`);
     for (const msg of messages) {
         const date = new Date(msg.created_at).toLocaleString();
         const sender = msg.from.handle || msg.from.tenant + '@greprag.com';
-        const status = msg.was_unread ? '· new' : '';
+        // Cold open = a bare-handle catch-all from a sender who doesn't know your
+        // session. Reply to from.session_id (shown below) to establish the line.
+        const coldOpen = msg.to_scope === 'tenant' ? '· cold open' : '';
+        // Internal self-desk rows (lore_smell, …) only surface under `--all` — tag
+        // them so the audit view shows they're queue items, not mail.
+        const internalTag = isInternalMessageType(msg.message_type) ? `· internal:${msg.message_type}` : '';
+        const status = [msg.was_unread ? '· new' : '', coldOpen, internalTag].filter(Boolean).join(' ');
         console.log(`[${sender}] ${date}  ${msg.id.slice(0, 8)} ${status}`);
         // Session ids in 8-hex when set on either side.
         // adr: adr/session-id-awareness.md
@@ -327,6 +392,24 @@ async function inbox(args) {
                 sessionParts.push(`to session ${toShort}`);
             console.log(`  · ${sessionParts.join(' → ')}`);
         }
+        // Front-desk envelope line (cold opens / inbound email). The receptionist
+        // gates on trust.verdict: 'verified' → may auto-route live; everything else
+        // parks for human sign-off. handled_by = already claimed (stand down).
+        // adr: adr/address-grammar.md
+        if (msg.to_scope === 'tenant') {
+            const fd = [];
+            if (msg.subject)
+                fd.push(`subj: ${msg.subject}`);
+            if (msg.ingress === 'email' || msg.trust) {
+                const verdict = msg.trust?.verdict ?? 'unevaluated';
+                const gate = verdict === 'verified' ? 'auto-route ok' : 'park for sign-off';
+                fd.push(`trust: ${verdict} → ${gate}`);
+            }
+            if (msg.handled_by)
+                fd.push(`handled by ${(0, session_id_1.truncateSessionId)(msg.handled_by) ?? msg.handled_by}`);
+            if (fd.length)
+                console.log(`  · ${fd.join('  ·  ')}`);
+        }
         // Indent each body line so multi-line markdown stays visually grouped
         for (const line of msg.body.split('\n'))
             console.log(`  ${line}`);
@@ -389,13 +472,14 @@ function parseFileFlag(raw) {
  *  look like UUIDs are rejected at registration time so this is unambiguous.
  *  adr: adr/session-id-awareness.md, adr/address-grammar.md */
 const SESSION_ID_PATTERN = /^([0-9a-f]{8}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
-/** Parse a send address under the v0.11 grammar:
- *    <handle>@greprag.com/<target>
+/** Parse a send address under the v0.12 grammar:
+ *    <handle>@greprag.com[/<target>]
  *  where <target> is exactly one segment — a session UUID (or 8-hex short
  *  form) for a session-targeted send, or a project name for a project
- *  broadcast. The bare form <handle>@greprag.com is identity-only and
- *  cannot be sent to — recipients share it as their contact form, senders
- *  must supply a target.
+ *  broadcast. The bare form <handle>@greprag.com (no target) is the tenant
+ *  catch-all / cold open — a first-contact channel for a sender who does not
+ *  know the recipient's session. The message lands in the recipient's inbox
+ *  for a manual check; it does not wake their session watchers.
  *
  *  Returns a discriminated result so the caller can print the helpful
  *  migration hint on failure. */
@@ -411,14 +495,9 @@ function parseSendAddress(addr) {
         return { ok: true, targetKind: 'discord', target: snowflake };
     }
     const segments = addr.split('/');
-    if (segments.length === 1) {
-        return { ok: false, error: `address "${addr}" has no target — the bare handle form is receive-only.\n` +
-                `  Add /<session-uuid> for the normal session-to-session send, or\n` +
-                `  add /<project-name> for an intentional project-wide broadcast.` };
-    }
     if (segments.length > 2) {
-        return { ok: false, error: `address "${addr}" has too many segments. The v0.11 grammar is\n` +
-                `  <handle>@greprag.com/<target>\n` +
+        return { ok: false, error: `address "${addr}" has too many segments. The v0.12 grammar is\n` +
+                `  <handle>@greprag.com[/<target>]\n` +
                 `where <target> is exactly one of: a session UUID OR a project name.\n` +
                 `Legacy <email>/<project>/<session> form is no longer accepted —\n` +
                 `pick the session you actually meant.` };
@@ -427,12 +506,158 @@ function parseSendAddress(addr) {
     if (!emailPart.includes('@')) {
         return { ok: false, error: `address "${addr}" missing @greprag.com handle.` };
     }
+    // Bare handle (no target segment) — the tenant catch-all (cold open).
+    if (segments.length === 1) {
+        return { ok: true, targetKind: 'catchall', target: '' };
+    }
     if (!target) {
         return { ok: false, error: `address "${addr}" has an empty target segment.` };
     }
     const kind = SESSION_ID_PATTERN.test(target) ? 'session' : 'project';
     return { ok: true, targetKind: kind, target };
 }
+/** Internal (self-desk) message types — KEEP IN SYNC with
+ *  packages/core/src/inbox-types.ts INTERNAL_MESSAGE_TYPES. The CLI is a thin
+ *  HTTP client and does not import @greprag/core (see turn-provenance.ts for the
+ *  same pattern), so the set is duplicated here for the `--type` fast-fail gate
+ *  and the `--all` audit-view tag. The server is the authority.
+ *  adr: adr/address-grammar.md */
+const INTERNAL_MESSAGE_TYPES = ['lore_smell'];
+function isInternalMessageType(t) {
+    return !!t && INTERNAL_MESSAGE_TYPES.includes(t);
+}
+/** Flags whose following arg is a value (not the message body). Shared by the
+ *  `--to` and `--to-desk` send paths so the body-finder skips flag values. */
+const SEND_FLAGS_TAKING_VALUE = new Set([
+    '--to', '--memory', '--artifact', '--file', '--ref-json',
+    '--from-session', '--in-reply-to', '--type', '--body-file',
+]);
+/** First positional arg that isn't a flag or a flag's value → the message body. */
+function extractBody(args) {
+    // --body-file <path>: read a long/multiline body from a file.
+    const bodyFile = getFlag(args, '--body-file');
+    if (bodyFile) {
+        try {
+            return fs.readFileSync(bodyFile, 'utf-8');
+        }
+        catch (e) {
+            console.error(`Error: --body-file could not be read: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    // --stdin: read the body from stdin.
+    if (args.includes('--stdin')) {
+        try {
+            return fs.readFileSync(0, 'utf-8');
+        }
+        catch (e) {
+            console.error(`Error: failed reading body from stdin: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    // Otherwise the first positional arg that isn't a flag value.
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith('--'))
+            continue;
+        if (i > 0 && SEND_FLAGS_TAKING_VALUE.has(args[i - 1]))
+            continue;
+        return args[i];
+    }
+    return undefined;
+}
+/** Build the references object from --memory/--artifact/--file/--ref-json/
+ *  --in-reply-to flags. Shared by both send paths. Exits on invalid --ref-json. */
+function buildReferences(args) {
+    let references;
+    const refJsonRaw = getFlag(args, '--ref-json');
+    if (refJsonRaw) {
+        try {
+            references = JSON.parse(refJsonRaw);
+        }
+        catch (e) {
+            console.error(`--ref-json: invalid JSON (${e.message})`);
+            process.exit(1);
+        }
+    }
+    else {
+        const memoryIds = getFlags(args, '--memory');
+        const artifacts = getFlags(args, '--artifact')
+            .map(parseArtifactFlag)
+            .filter((a) => a !== null);
+        const files = getFlags(args, '--file').map(parseFileFlag);
+        if (memoryIds.length || artifacts.length || files.length) {
+            references = {};
+            if (memoryIds.length)
+                references.memory_ids = memoryIds;
+            if (artifacts.length)
+                references.artifacts = artifacts;
+            if (files.length)
+                references.files = files;
+        }
+    }
+    // --in-reply-to <front-desk-id>: thread the reply back to a cold open /
+    // inbound-email record so the ensuing private line continues that
+    // conversation (front-desk invariant 5). adr: adr/address-grammar.md
+    const inReplyTo = getFlag(args, '--in-reply-to');
+    if (inReplyTo) {
+        references = { ...(references ?? {}), in_reply_to: inReplyTo };
+    }
+    return references;
+}
+/** greprag send "<text>" --to-desk --type <internal-type>
+ *
+ *  Self-addressed internal mail: posts to THIS project's own desk (no external
+ *  recipient) carrying a known internal messageType. Trusted by construction
+ *  (from.tenant === to.tenant) — bypasses the trust gate, the receptionist
+ *  wake, and sign-off; never wakes a live watcher. Accrues silently and is
+ *  drained later by its typed consumer (e.g. lore_smell → /lore-advisor).
+ *  The generic primitive `greprag lore smell` wraps. adr: adr/address-grammar.md */
+async function sendToDesk(args, cfg, to) {
+    if (to) {
+        console.error('--to-desk is self-addressed (your own project desk) — drop --to.');
+        process.exit(1);
+    }
+    const type = getFlag(args, '--type');
+    const known = INTERNAL_MESSAGE_TYPES.join(', ');
+    if (!type) {
+        console.error(`--to-desk requires --type <internal-type>.\n  Known internal types: ${known}.`);
+        process.exit(1);
+    }
+    if (!isInternalMessageType(type)) {
+        console.error(`--type "${type}" is not a known internal type.\n  Known internal types: ${known}.`);
+        process.exit(1);
+    }
+    // The desk = the caller's anchor project (same resolver lore/memory use).
+    const anchor = (0, project_anchor_1.readAnchor)(process.cwd());
+    if (!anchor.projectId) {
+        console.error('No project anchor in current directory. Run: greprag init (the desk is this project).');
+        process.exit(1);
+    }
+    const body = extractBody(args);
+    if (!body) {
+        console.error('Usage: greprag send "<text>" --to-desk --type <internal-type>');
+        process.exit(1);
+    }
+    const payload = {
+        to_desk: true,
+        type,
+        body,
+        from_project_id: anchor.projectId,
+    };
+    const references = buildReferences(args);
+    if (references)
+        payload.references = references;
+    const fromSessionId = getFlag(args, '--from-session');
+    if (fromSessionId)
+        payload.from_session_id = fromSessionId;
+    const result = await apiCall(`${cfg.apiUrl}/v1/inbox/send`, cfg.apiKey, payload);
+    const idShort = typeof result.id === 'string' ? result.id.slice(0, 8) : '????????';
+    console.log(`Queued to desk (type=${type}, project=${anchor.projectName})  (${idShort})`);
+    console.log(`  (internal queue item — not inbox mail; drained by its consumer, no live ping. Audit: greprag inbox --all)`);
+    const retractCode = result.retract_code;
+    if (retractCode)
+        console.log(`Retract: greprag retract ${retractCode}`);
+}
 /** greprag send "body" --to <handle>@greprag.com/<target>
  *                      [--from-session <id>]      sender's own session — denormalized
  *                                                 onto the message so the recipient can
@@ -444,8 +669,10 @@ function parseSendAddress(addr) {
  *
  *  <target> is exactly one segment — a session UUID (normal case) or a
  *  project name (intentional broadcast). The bare <handle>@greprag.com form
- *  is receive-only; sending to it errors. --session and --project flags
- *  were removed in v0.11 — the address carries the target.
+ *  (no target) is the tenant catch-all / cold open — sendable, no --broadcast
+ *  needed, lands quietly in the recipient's inbox for a manual check.
+ *  --session and --project flags were removed in v0.11 — the address carries
+ *  the target. adr: adr/address-grammar.md
  */
 async function send(args) {
     const cfg = getConfig();
@@ -454,10 +681,15 @@ async function send(args) {
         process.exit(1);
     }
     const to = getFlag(args, '--to');
+    // Self-addressed internal mail: `greprag send "<text>" --to-desk --type <t>`.
+    // No external recipient — lands on this project's own desk and is drained by
+    // its typed consumer. Branch out before the --to-dependent path below.
+    // adr: adr/address-grammar.md
+    if (args.includes('--to-desk')) {
+        return sendToDesk(args, cfg, to);
+    }
     if (!to) {
-        console.error('Error: --to is required.');
-        console.error('Usage: greprag send "body" --to <handle>@greprag.com/<target>');
-        console.error('       greprag send --body-file report.md --to <handle>@greprag.com/<target>');
+        console.error('Usage: greprag send "body" --to <handle>@greprag.com[/<target>] [--from-session <id>] [--memory <uuid>] [--artifact <type:id>] [--file <path[:lines]>] [--broadcast]\n  bare handle: tenant catch-all (cold open). <target>: session UUID (normal) or project name (broadcast — requires --broadcast).\n  self-desk: --to-desk --type <internal-type> (internal queue item, no recipient).');
         process.exit(1);
     }
     // Early validation — fail before the round-trip so the operator sees the
@@ -489,42 +721,9 @@ async function send(args) {
             process.exit(1);
         }
     }
-    // Find the body — first positional arg that isn't a flag value. We need to
-    // skip both the flag itself and the value of any preceding flag.
-    const flagsTakingValue = new Set([
-        '--to', '--memory', '--artifact', '--file', '--ref-json',
-        '--from-session', '--body-file',
-    ]);
-    let body;
-    const bodyFile = getFlag(args, '--body-file');
-    if (bodyFile) {
-        try {
-            body = fs.readFileSync(bodyFile, 'utf-8');
-        }
-        catch (e) {
-            console.error(`Error: --body-file could not be read: ${e.message}`);
-            process.exit(1);
-        }
-    }
-    else if (args.includes('--stdin')) {
-        try {
-            body = fs.readFileSync(0, 'utf-8');
-        }
-        catch (e) {
-            console.error(`Error: failed reading message body from stdin: ${e.message}`);
-            process.exit(1);
-        }
-    }
-    for (let i = 0; i < args.length; i++) {
-        if (body)
-            break;
-        if (args[i].startsWith('--'))
-            continue;
-        if (i > 0 && flagsTakingValue.has(args[i - 1]))
-            continue;
-        body = args[i];
-        break;
-    }
+    // Body + references via the shared helpers (also used by the --to-desk path).
+    // extractBody handles --body-file / --stdin / positional.
+    const body = extractBody(args);
     if (!body || body.trim().length === 0) {
         console.error('Error: message body is missing.');
         console.error('Use one of:');
@@ -533,34 +732,7 @@ async function send(args) {
         console.error('  type report.md | greprag send --stdin --to <handle>@greprag.com/<target>');
         process.exit(1);
     }
-    // Build references from flags (or take the explicit --ref-json if provided).
-    let references;
-    const refJsonRaw = getFlag(args, '--ref-json');
-    if (refJsonRaw) {
-        try {
-            references = JSON.parse(refJsonRaw);
-        }
-        catch (e) {
-            console.error(`--ref-json: invalid JSON (${e.message})`);
-            process.exit(1);
-        }
-    }
-    else {
-        const memoryIds = getFlags(args, '--memory');
-        const artifacts = getFlags(args, '--artifact')
-            .map(parseArtifactFlag)
-            .filter((a) => a !== null);
-        const files = getFlags(args, '--file').map(parseFileFlag);
-        if (memoryIds.length || artifacts.length || files.length) {
-            references = {};
-            if (memoryIds.length)
-                references.memory_ids = memoryIds;
-            if (artifacts.length)
-                references.artifacts = artifacts;
-            if (files.length)
-                references.files = files;
-        }
-    }
+    const references = buildReferences(args);
     const payload = { to, body };
     if (references)
         payload.references = references;
@@ -588,6 +760,11 @@ async function send(args) {
         : (delivered.project ? '/' + delivered.project : '');
     const idShort = typeof result.id === 'string' ? result.id.slice(0, 8) : '????????';
     console.log(`Sent to ${base}${targetSegment}  (${idShort})`);
+    // Cold-open hint: a catch-all drop waits for a manual `greprag inbox` check
+    // on the recipient's side; it does not wake their live session watcher.
+    if (parsed.ok && parsed.targetKind === 'catchall') {
+        console.log(`  (tenant catch-all — lands in their inbox for a manual check, no live ping)`);
+    }
     const retractCode = result.retract_code;
     if (retractCode)
         console.log(`Retract: greprag retract ${retractCode}`);
@@ -807,39 +984,40 @@ async function retract(args) {
     console.log((0, inbox_retract_1.formatRetractResult)(result.status));
 }
 // -- Main ------------------------------------------------------------------
-const INIT_HELP = `greprag init — configure GrepRAG for an agent client.
-
-  greprag init
-  greprag init --codex [--tenant-id <handle>|--api-key <key>] [--install-watcher]
-  greprag init --claude [--tenant-id <handle>|--api-key <key>]
-  greprag init --opencode [--tenant-id <handle>|--api-key <key>]
-  greprag init --all [--root <path>]
-  greprag init --global [--name <name>]
-
-Options:
-  --tenant-id <handle>     Provision/use public handle <handle>@greprag.com.
-                           Example: --tenant-id tanya -> tanya@greprag.com
-  --api-key <key>          Use an existing GrepRAG API key instead of provisioning.
-  --codex                  Configure Codex hooks + /greprag skill.
-  --install-watcher        With --codex, install the live inbox watcher at login.
-  --claude                 Configure Claude Code hooks + /greprag skill.
-  --opencode               Configure OpenCode plugin.
-
-Codex Desktop trust step:
-  After init, open Settings -> Settings -> Hooks and trust the 6 GrepRAG hooks.`;
-const HELP = `
-greprag — agent memory for Claude Code, Codex, and OpenCode
-
-Commands:
-  init [--api-key <key>] [--tenant-id <handle>]
-                                  Auto-detect/ask for Codex, Claude Code, or OpenCode
-  init --claude [--api-key <key>] [--tenant-id <handle>]
-                                  Configure hooks + API key for Claude Code
-  init --global [--name <name>]    Create ~/.greprag/project.json (global anchor)
-  init --opencode [--api-key <key>] [--tenant-id <handle>]
-                                  Configure plugin + anchor for OpenCode
-  init --codex [--api-key <key>] [--tenant-id <handle>] [--install-watcher]
-                                  Configure lifecycle hooks + anchor for Codex
+const INIT_HELP = `greprag init — configure GrepRAG for an agent client.
+
+  greprag init
+  greprag init --codex [--tenant-id <handle>|--api-key <key>] [--install-watcher]
+  greprag init --claude [--tenant-id <handle>|--api-key <key>]
+  greprag init --opencode [--tenant-id <handle>|--api-key <key>]
+  greprag init --all [--root <path>]
+  greprag init --global [--name <name>]
+
+Options:
+  --tenant-id <handle>     Provision/use public handle <handle>@greprag.com.
+                           Example: --tenant-id tanya -> tanya@greprag.com
+  --api-key <key>          Use an existing GrepRAG API key instead of provisioning.
+  --codex                  Configure Codex hooks + /greprag skill.
+  --install-watcher        With --codex, install the live inbox watcher at login.
+  --claude                 Configure Claude Code hooks + /greprag skill.
+  --opencode               Configure OpenCode plugin.
+
+Codex Desktop trust step:
+  After init, start a fresh Codex session, then open Settings -> Settings -> Hooks
+  and trust the 6 GrepRAG hooks.`;
+const HELP = `
+greprag — agent memory for Claude Code, Codex, and OpenCode
+
+Commands:
+  init [--api-key <key>] [--tenant-id <handle>]
+                                  Auto-detect/ask for Codex, Claude Code, or OpenCode
+  init --claude [--api-key <key>] [--tenant-id <handle>]
+                                  Configure hooks + API key for Claude Code
+  init --global [--name <name>]    Create ~/.greprag/project.json (global anchor)
+  init --opencode [--api-key <key>] [--tenant-id <handle>]
+                                  Configure plugin + anchor for OpenCode
+  init --codex [--api-key <key>] [--tenant-id <handle>] [--install-watcher]
+                                  Configure lifecycle hooks + anchor for Codex
   init --all [--root <path>]       Standard init for cwd, then bulk-register every
                                    other git repo at depth 1 under <path> (default:
                                    parent of repo root). Each becomes inbox-addressable.
@@ -849,20 +1027,22 @@ Commands:
   codex startup install          Start the Codex live-push sidecar at login.
   project-id                       Print the current project_id
   session-id [--full]              Print this session's id (8-hex, or full UUID with --full).
-  discover [--json]                Tenant-wide structure: every project, per-shape row counts,
-                                   activity ranges. For cross-project advisors.
-  doctor [--inspect] [--yes]       Diagnose + repair orphan project_ids and identity drift
-  smell "<text>"                   Shortcut for \`greprag lore smell "<text>"\`.
-
-Inbox (email-style messaging across tenants):
+  discover [--json]                Tenant-wide structure: every project, per-shape row counts,
+                                   activity ranges. For cross-project advisors.
+  doctor [--inspect] [--yes]       Diagnose + repair orphan project_ids and identity drift
+  smell "<text>"                   Shortcut for \`greprag lore smell "<text>"\`.
+
+Inbox (email-style messaging across tenants):
   inbox [--all] [--session <id>] [--project <name>] [--peek]
-                                List unread (auto-marks read). --all for history.
-                                --session filters to messages targeting this session
-                                (plus untargeted broadcasts).
+                                List unread, auto-scoped to THIS session: its own
+                                lines (sender OR recipient) + the front desk
+                                (tenant catch-all) + project broadcasts. Other
+                                sessions' private lines are hidden by default.
+                                --all = audit peek: drop the per-session scope
+                                (every session's lines) AND include read history.
+                                --session scopes to one specific session's view.
                                 --project filters by project name.
                                 --peek: NON-MUTATING — does not mark any message read.
-                                Used by orchestrator-mode sessions to inspect other
-                                sessions' inboxes without burning their unread state.
   inbox watchers [--json]       List currently-attached live watchers under this
                                 tenant. Each row: project · title (session_id) —
                                 project + nano title resolved from session memory.
@@ -874,24 +1054,39 @@ Inbox (email-style messaging across tenants):
     [--project <name>]          Filter to one project inbox (default: tenant-wide).
     [--session <id>]            Filter to messages targeting this session
                                 (plus untargeted broadcasts).
+    [--receptionist]            Attend the front desk — wake live on a tenant
+                                catch-all (cold open / inbound email). Without it,
+                                cold opens surface only on a manual inbox check.
     [--since <id|iso>]          Resume after a message id or timestamp.
     [--json]                    Emit raw JSON per line (for piping to Monitor).
+  inbox claim <id>              Receptionist: claim a front-desk record (cold open /
+                                inbound email). First claimant wins; a co-armed
+                                receptionist stands down — no double-reply.
   inbox keep <id>               Extend a read message's TTL (default delete after 14 days)
   inbox delete <id>             Permanently delete a message
-  send "body" --to <addr>       Send a message. Body is markdown.
-  send --body-file <path> --to <addr>
-                                Send a long/multiline body from a file.
-  send --stdin --to <addr>      Read message body from stdin.
-                                <addr> must include a target segment — see Addresses below.
+  send "body" --to <addr>       Send a message. Body is markdown.
+                                <addr> is a bare handle (tenant catch-all) or
+                                handle/<target> — see Addresses below.
+  send --body-file <path> --to <addr>
+                                Send a long/multiline body from a file.
+  send --stdin --to <addr>      Read message body from stdin.
     --from-session <id>         Sender's session — denormalized so the recipient can
                                 reply by session without re-discovery.
     --memory <uuid>             (repeatable) back-pointer to a memory row
     --artifact <type:id>        (repeatable) e.g. commit:abc123, pr:#42, deploy:def
     --file <path[:lines]>       (repeatable) e.g. src/auth.ts, src/auth.ts:42, src/x.ts:10-15
     --ref-json '<json>'         escape hatch — full references object
+    --in-reply-to <id>          Thread a reply back to a front-desk record (cold open /
+                                inbound email) — sets references.in_reply_to so the
+                                ensuing private line continues that conversation.
     --broadcast                 Required when <addr> targets a project — every watcher in
                                 that project receives the message. Default behavior is
                                 session-scoped delivery; this flag is the explicit opt-in.
+    --to-desk                   Self-addressed internal mail — posts to THIS project's own
+                                desk (no recipient; omit --to). Requires --type.
+    --type <internal-type>      Internal messageType for --to-desk (e.g. lore_smell). Queue
+                                item drained by its consumer — never wakes a watcher and is
+                                hidden from the default inbox (audit via 'inbox --all').
   retract <code>                Pull back a previously-sent message (code is printed on send).
   discord pair                  Pair Discord DMs to this project — generates a code to DM the bot.
   discord unpair                Remove the Discord pairing.
@@ -904,13 +1099,30 @@ Inbox (email-style messaging across tenants):
                                 Unread → hard delete. Read → body replaced with a retracted notice.
                                 Idempotent: double-retract is a no-op.
 
-  Addresses (v0.11+):
-    Share:  <handle>@greprag.com                   identity-only, receive form
-    Send:   <handle>@greprag.com/<session-uuid>    session-to-session (normal)
-            <handle>@greprag.com/<project-name>    project broadcast — requires --broadcast
-    The bare share form cannot be sent to — operators must pick a target.
+  Addresses (v0.12+):
+    Cold open: <handle>@greprag.com                 tenant catch-all — first contact when
+                                                    you don't know their session. Lands in
+                                                    their inbox for a manual check; no live
+                                                    ping. No --broadcast needed.
+    Session:   <handle>@greprag.com/<session-uuid>  session-to-session (normal, live)
+    Project:   <handle>@greprag.com/<project-name>  project broadcast — requires --broadcast
+    Self-desk: --to-desk --type <internal-type>     internal queue item on your own project
+                                                    desk — no recipient, no wake; drained by
+                                                    its typed consumer (e.g. lore_smell).
     --session and --project flags were removed; the address carries the target.
 
+Email (agent-email front desk — drain inbound attachments to local disk):
+  email [pending]               List pending front-desk email (envelope only).
+  email pull --id <record>      Pull ONE record's attachments to local disk.
+  email pull --all-pending      Pull EVERY pending record's attachments.
+    [--to <dir>]                Save dir. Default: --to > $GREPRAG_EMAIL_DIR >
+                               anchor email_dir > ~/.greprag/email/<project>.
+    [--quiet]                  Only print the one-line summary.
+                               Saved as <subject-slug>-<index>.<ext>; re-pulls
+                               are idempotent. Auto-save: set email_autosave=true
+                               in .greprag/project.json so the mail hook pulls
+                               new attachments each turn.
+
 Memory (episodic project memory — turn/hourly/daily/weekly/ship-event):
   memory search "<query>"        Lexical retrieval over the project's memory.
                                 Same v5 RRF + adjacency pipeline as 'corpus
@@ -1040,6 +1252,7 @@ Examples:
  *  test flags any dispatched command that never appears in a help surface.) */
 const HELP_ALL_GROUPS = [
     ['inbox', inbox],
+    ['email', email_1.runEmail],
     ['memory', memory_1.runMemory],
     ['corpus', corpus_1.runCorpus],
     ['lore', lore_1.runLore],
@@ -1128,6 +1341,7 @@ async function main() {
             return;
         }
         case 'inbox': return inbox(subArgs);
+        case 'email': return (0, email_1.runEmail)(subArgs);
         case 'send': return send(subArgs);
         case 'retract': return retract(subArgs);
         case 'discord': return discord(subArgs);