@cohortapp/agent-sdk 2.3.0

package/scripts/restore-from-backup.sh

@@ -0,0 +1,248 @@
+#!/bin/bash
+# restore-from-backup.sh — executable dead-Mac-mini restore runbook (G16).
+#
+# Rebuilds a Maestro agent's durable state onto replacement hardware from a single
+# backup archive produced by scripts/maintenance/backup-to-cloud.sh. This is the
+# runbook in docs/runbooks/backup-restore.md made EXECUTABLE: instead of a human
+# hand-copying state/, logs/, and config/ from a tarball and trying to remember
+# the re-pair + secret-recovery steps, this script does the mechanical parts and
+# PRINTS the irreducibly-manual ones (secret recovery, Cohort re-pair approval).
+#
+# What it does:
+#   1. Validates the archive (and client-side decrypts it if it is encrypted —
+#      .gpg / .age — using a passphrase from $RESTORE_PASSPHRASE).
+#   2. Unpacks into a scratch dir and shows what the archive contains.
+#   3. Restores config/, state/, and logs/ into the agent repo (existing dirs are
+#      backed up to <dir>.pre-restore.<ts> first, so a re-run never destroys what
+#      it already placed — idempotent).
+#   4. Re-pairs with Cohort (prints the operator-station approval command; mints
+#      a FRESH device token rather than restoring the dead one — never restore an
+#      identity credential).
+#   5. Prints the remaining manual steps: secret recovery via `maestro secrets
+#      sync`, .env lockdown, doctor, resume.
+#
+# Idempotent: safe to re-run. --dry-run lists every step WITHOUT touching the
+# filesystem, decrypting, or pairing. bash -n clean; shellcheck-friendly.
+#
+# Usage:
+#   scripts/restore-from-backup.sh --archive <path> [--agent-dir <dir>] [--dry-run]
+#   scripts/restore-from-backup.sh --archive backup.tar.gz.gpg --dry-run
+#
+# Env:
+#   RESTORE_PASSPHRASE   passphrase for an encrypted (.gpg/.age) archive
+#   AGENT_DIR            override the target agent repo (default: repo root)
+#   COHORT_AGENT_ID     agent id used in the printed re-pair command
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# Defaults + arg parsing
+# ---------------------------------------------------------------------------
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_AGENT_DIR="$(dirname "$SCRIPT_DIR")"
+
+ARCHIVE=""
+AGENT_DIR="${AGENT_DIR:-$DEFAULT_AGENT_DIR}"
+DRY_RUN=0
+TS="$(date -u +"%Y%m%dT%H%M%SZ")"
+
+usage() {
+    cat <<'USAGE'
+restore-from-backup.sh — dead-Mac-mini restore from a backup archive.
+
+  --archive <path>     backup archive to restore (.tar.gz, .tgz, .tar.gz.gpg, .age)
+  --agent-dir <dir>    target agent repo (default: this repo's root)
+  --dry-run            print the plan; touch nothing, decrypt nothing, pair nothing
+  -h, --help           this help
+
+Encrypted archives (.gpg/.age) need RESTORE_PASSPHRASE in the environment.
+USAGE
+}
+
+while [ "$#" -gt 0 ]; do
+    case "$1" in
+        --archive)
+            ARCHIVE="${2:-}"
+            shift 2
+            ;;
+        --agent-dir)
+            AGENT_DIR="${2:-}"
+            shift 2
+            ;;
+        --dry-run)
+            DRY_RUN=1
+            shift
+            ;;
+        -h|--help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "ERROR: unknown argument: $1" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+# ---------------------------------------------------------------------------
+# Output helpers
+# ---------------------------------------------------------------------------
+
+step() { echo "[restore] $1"; }
+note() { echo "    $1"; }
+run_or_echo() {
+    # In dry-run, print the command prefixed with DRY-RUN and do nothing.
+    # Otherwise execute it.
+    if [ "$DRY_RUN" -eq 1 ]; then
+        echo "    DRY-RUN: $*"
+    else
+        "$@"
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# Validate inputs
+# ---------------------------------------------------------------------------
+
+if [ -z "$ARCHIVE" ]; then
+    echo "ERROR: --archive is required." >&2
+    usage >&2
+    exit 2
+fi
+
+# In a real run the archive must exist; in --dry-run we tolerate a missing path
+# so the operator can rehearse the plan before the archive is downloaded.
+if [ ! -f "$ARCHIVE" ] && [ "$DRY_RUN" -eq 0 ]; then
+    echo "ERROR: archive not found: $ARCHIVE" >&2
+    exit 1
+fi
+
+# Determine whether the archive is encrypted from its extension.
+ENCRYPTED=0
+case "$ARCHIVE" in
+    *.gpg|*.age) ENCRYPTED=1 ;;
+    *) ENCRYPTED=0 ;;
+esac
+
+step "Restore plan for agent dir: $AGENT_DIR"
+note "archive: $ARCHIVE"
+note "encrypted: $([ "$ENCRYPTED" -eq 1 ] && echo yes || echo no)"
+note "mode: $([ "$DRY_RUN" -eq 1 ] && echo DRY-RUN || echo APPLY)"
+
+# ---------------------------------------------------------------------------
+# 1. Decrypt (if encrypted)
+# ---------------------------------------------------------------------------
+
+SCRATCH=""
+TARBALL="$ARCHIVE"
+
+step "Step 1/5: validate + decrypt archive"
+if [ "$ENCRYPTED" -eq 1 ]; then
+    note "archive is encrypted — client-side decrypt required"
+    if [ "$DRY_RUN" -eq 0 ] && [ -z "${RESTORE_PASSPHRASE:-}" ]; then
+        echo "ERROR: encrypted archive but RESTORE_PASSPHRASE is unset." >&2
+        exit 1
+    fi
+    SCRATCH="$(mktemp -d "${TMPDIR:-/tmp}/maestro-restore.${TS}.XXXXXX")"
+    TARBALL="$SCRATCH/decrypted.tar.gz"
+    case "$ARCHIVE" in
+        *.gpg)
+            run_or_echo gpg --batch --yes --passphrase "${RESTORE_PASSPHRASE:-}" \
+                --decrypt --output "$TARBALL" "$ARCHIVE"
+            ;;
+        *.age)
+            run_or_echo age --decrypt --output "$TARBALL" "$ARCHIVE"
+            ;;
+    esac
+else
+    note "archive is plaintext — no decrypt step"
+fi
+
+# ---------------------------------------------------------------------------
+# 2. Unpack into scratch + inspect
+# ---------------------------------------------------------------------------
+
+step "Step 2/5: unpack archive into a scratch dir and inspect"
+if [ -z "$SCRATCH" ]; then
+    SCRATCH="$(mktemp -d "${TMPDIR:-/tmp}/maestro-restore.${TS}.XXXXXX" 2>/dev/null || echo "/tmp/maestro-restore.${TS}")"
+fi
+UNPACK="$SCRATCH/unpacked"
+run_or_echo mkdir -p "$UNPACK"
+run_or_echo tar -xzf "$TARBALL" -C "$UNPACK"
+note "inspect before overwriting: ls $UNPACK"
+if [ "$DRY_RUN" -eq 0 ] && [ -d "$UNPACK" ]; then
+    ls "$UNPACK" | sed 's/^/    contains: /' || true
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Restore config/, state/, logs/ — idempotent (back up existing first)
+# ---------------------------------------------------------------------------
+
+step "Step 3/5: restore config/, state/, logs/ into $AGENT_DIR"
+for dir in config state logs; do
+    SRC="$UNPACK/$dir"
+    DEST="$AGENT_DIR/$dir"
+    if [ "$DRY_RUN" -eq 1 ]; then
+        note "DRY-RUN: would restore $dir/ (existing $DEST → $DEST.pre-restore.$TS, then copy from archive)"
+        continue
+    fi
+    if [ ! -d "$SRC" ]; then
+        note "skip $dir/ — not present in archive"
+        continue
+    fi
+    # Idempotent: move any existing dir aside (timestamped) so a re-run never
+    # clobbers a prior restore and the operator can diff/rollback.
+    if [ -e "$DEST" ]; then
+        run_or_echo mv "$DEST" "$DEST.pre-restore.$TS"
+        note "preserved existing $dir/ → $dir.pre-restore.$TS"
+    fi
+    run_or_echo mkdir -p "$AGENT_DIR"
+    run_or_echo cp -R "$SRC" "$DEST"
+    note "restored $dir/"
+done
+
+# Lock down secret-bearing files if they came back in the archive.
+if [ "$DRY_RUN" -eq 1 ]; then
+    note "DRY-RUN: would chmod 600 $AGENT_DIR/.env if present"
+elif [ -f "$AGENT_DIR/.env" ]; then
+    run_or_echo chmod 600 "$AGENT_DIR/.env"
+    note "locked down .env (0600)"
+fi
+
+# ---------------------------------------------------------------------------
+# 4. Re-pair with Cohort (fresh device token — never restore the old one)
+# ---------------------------------------------------------------------------
+
+step "Step 4/5: re-establish org-server (Cohort) identity"
+AGENT_ID="${COHORT_AGENT_ID:-<agentId>}"
+note "Do NOT restore the dead device token. Mint a fresh one on the operator station:"
+note "  cohort --db \"\$COHORT_DB\" pair approve $AGENT_ID --scopes <scopes>"
+note "Then write the printed token into $AGENT_DIR/.env and chmod 600 .env."
+if [ "$DRY_RUN" -eq 1 ]; then
+    note "DRY-RUN: pairing is a manual operator-station action; nothing executed here."
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Remaining manual steps
+# ---------------------------------------------------------------------------
+
+step "Step 5/5: remaining MANUAL steps (this script cannot do these for you)"
+note "1. Recover secrets:  maestro secrets sync"
+note "   (re-issue anything unrecoverable at its source; treat theft as full rotation)"
+note "2. Confirm .env:     chmod 600 $AGENT_DIR/.env && stat -f '%Sp' $AGENT_DIR/.env  (expect -rw-------)"
+note "3. Verify posture:   maestro doctor   (green before going live; backup freshness should clear)"
+note "4. Resume ops:       $AGENT_DIR/scripts/resume-operations.sh"
+note "5. Re-arm backup:    maestro init backup-replication --apply   (a rebuilt box with no backup is the next dead box)"
+
+# ---------------------------------------------------------------------------
+# Cleanup (real runs only; leave scratch for inspection in dry-run is moot —
+# nothing was created)
+# ---------------------------------------------------------------------------
+
+if [ "$DRY_RUN" -eq 0 ] && [ -n "$SCRATCH" ] && [ -d "$SCRATCH" ]; then
+    rm -rf "$SCRATCH" 2>/dev/null || true
+fi
+
+step "Restore $([ "$DRY_RUN" -eq 1 ] && echo "plan complete (dry-run — nothing changed)" || echo "complete — finish the manual steps above")"

package/scripts/restore-from-backup.test.mjs

@@ -0,0 +1,178 @@
+/**
+ * restore-from-backup.test.mjs — coverage for scripts/restore-from-backup.sh.
+ *
+ * Drives the script with --dry-run over a tmp fixture (a real .tar.gz of a fake
+ * config/state/logs tree) and asserts:
+ *   - `bash -n` is clean (no syntax errors)
+ *   - --dry-run lists every restore step and the manual follow-ups
+ *   - --dry-run touches NOTHING on disk (no dirs moved/created in the agent dir)
+ *   - the required-arg + unknown-arg + help paths exit with the right codes
+ *   - an encrypted (.gpg) archive surfaces the decrypt step in the plan
+ *
+ * No live decrypt / pairing happens — --dry-run prints the plan only.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  readdirSync,
+  rmSync,
+  existsSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = resolve(__dirname, "restore-from-backup.sh");
+
+/** Build a tmp dir + a real .tar.gz containing config/, state/, logs/. */
+function makeArchive() {
+  const root = mkdtempSync(join(tmpdir(), "restore-test-"));
+  const src = join(root, "src");
+  for (const d of ["config", "state", "logs"]) {
+    mkdirSync(join(src, d), { recursive: true });
+    writeFileSync(join(src, d, "marker.txt"), `restored-${d}\n`);
+  }
+  const archive = join(root, "backup.tar.gz");
+  const tar = spawnSync("tar", ["-czf", archive, "-C", src, "config", "state", "logs"], {
+    encoding: "utf-8",
+  });
+  assert.equal(tar.status, 0, `tar failed: ${tar.stderr}`);
+  return { root, archive };
+}
+
+function run(args, opts = {}) {
+  return spawnSync("bash", [SCRIPT, ...args], { encoding: "utf-8", ...opts });
+}
+
+function cleanup(p) {
+  rmSync(p, { recursive: true, force: true });
+}
+
+test("bash -n: the script has no syntax errors", () => {
+  const r = spawnSync("bash", ["-n", SCRIPT], { encoding: "utf-8" });
+  assert.equal(r.status, 0, `bash -n failed: ${r.stderr}`);
+});
+
+test("--dry-run lists every restore step and the manual follow-ups", () => {
+  const { root, archive } = makeArchive();
+  const agentDir = join(root, "agent");
+  mkdirSync(agentDir, { recursive: true });
+  try {
+    const r = run(["--archive", archive, "--agent-dir", agentDir, "--dry-run"]);
+    assert.equal(r.status, 0, `nonzero exit: ${r.stderr}`);
+    const out = r.stdout;
+
+    // The five numbered steps are all present.
+    assert.match(out, /Step 1\/5: validate \+ decrypt/);
+    assert.match(out, /Step 2\/5: unpack/);
+    assert.match(out, /Step 3\/5: restore config\/, state\/, logs\//);
+    assert.match(out, /Step 4\/5: re-establish org-server \(Cohort\) identity/);
+    assert.match(out, /Step 5\/5: remaining MANUAL steps/);
+
+    // Each of the three dirs is named in the plan.
+    assert.match(out, /would restore config\//);
+    assert.match(out, /would restore state\//);
+    assert.match(out, /would restore logs\//);
+
+    // The irreducibly-manual follow-ups: secret recovery + cohort re-pair.
+    assert.match(out, /maestro secrets sync/);
+    assert.match(out, /cohort .* pair approve/);
+    assert.match(out, /resume-operations\.sh/);
+    assert.match(out, /init backup-replication/);
+
+    // Dry-run banner.
+    assert.match(out, /dry-run — nothing changed/);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("--dry-run touches NOTHING in the agent dir", () => {
+  const { root, archive } = makeArchive();
+  const agentDir = join(root, "agent");
+  mkdirSync(agentDir, { recursive: true });
+  // Seed an existing state/ to prove dry-run does not move it aside.
+  mkdirSync(join(agentDir, "state"), { recursive: true });
+  writeFileSync(join(agentDir, "state", "pre-existing.txt"), "keep me\n");
+  const before = readdirSync(agentDir).sort();
+  try {
+    const r = run(["--archive", archive, "--agent-dir", agentDir, "--dry-run"]);
+    assert.equal(r.status, 0);
+    const after = readdirSync(agentDir).sort();
+    assert.deepEqual(after, before, "dry-run must not create/move any dir");
+    // No .pre-restore.* backup was created.
+    assert.ok(
+      !after.some((n) => n.includes("pre-restore")),
+      "dry-run must not produce a pre-restore backup"
+    );
+    assert.ok(existsSync(join(agentDir, "state", "pre-existing.txt")), "pre-existing state untouched");
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("encrypted (.gpg) archive surfaces the decrypt step in the dry-run plan", () => {
+  const root = mkdtempSync(join(tmpdir(), "restore-enc-"));
+  const agentDir = join(root, "agent");
+  mkdirSync(agentDir, { recursive: true });
+  try {
+    // A .gpg path need not exist for a dry-run rehearsal.
+    const r = run(["--archive", join(root, "backup.tar.gz.gpg"), "--agent-dir", agentDir, "--dry-run"]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /encrypted: yes/);
+    assert.match(r.stdout, /client-side decrypt required/);
+    assert.match(r.stdout, /DRY-RUN: gpg .*--decrypt/);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test("missing --archive exits 2 with usage", () => {
+  const r = run(["--dry-run"]);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /--archive is required/);
+});
+
+test("unknown argument exits 2", () => {
+  const r = run(["--archive", "x", "--bogus"]);
+  assert.equal(r.status, 2);
+  assert.match(r.stderr, /unknown argument/);
+});
+
+test("--help exits 0 and prints usage", () => {
+  const r = run(["--help"]);
+  assert.equal(r.status, 0);
+  assert.match(r.stdout, /dead-Mac-mini restore/);
+});
+
+test("a real (non-dry) restore is idempotent: re-run preserves the prior restore", () => {
+  const { root, archive } = makeArchive();
+  const agentDir = join(root, "agent");
+  mkdirSync(agentDir, { recursive: true });
+  try {
+    // First restore.
+    const r1 = run(["--archive", archive, "--agent-dir", agentDir]);
+    assert.equal(r1.status, 0, `first restore failed: ${r1.stderr}`);
+    assert.ok(existsSync(join(agentDir, "state", "marker.txt")), "state restored");
+    assert.ok(existsSync(join(agentDir, "config", "marker.txt")), "config restored");
+    assert.ok(existsSync(join(agentDir, "logs", "marker.txt")), "logs restored");
+
+    // Second restore must not fail and must preserve the prior dirs aside.
+    const r2 = run(["--archive", archive, "--agent-dir", agentDir]);
+    assert.equal(r2.status, 0, `second restore failed: ${r2.stderr}`);
+    const after = readdirSync(agentDir);
+    assert.ok(
+      after.some((n) => n.startsWith("state.pre-restore.")),
+      "re-run preserved the prior state/ as a timestamped backup"
+    );
+    assert.ok(existsSync(join(agentDir, "state", "marker.txt")), "state restored again");
+  } finally {
+    cleanup(root);
+  }
+});

package/scripts/resume-operations.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Resume Operations — Restarts Maestro agent after an emergency stop.
+# Usage: ./scripts/resume-operations.sh
+#
+# Reverses emergency-stop.sh:
+#   1. Verifies health check passes.
+#   2. Removes the .emergency-stop flag.
+#   3. Reloads every installed `ai.maestro.<agent>-*` (and legacy
+#      `ai.adaptic.<agent>-*`) launchd job.
+#
+# Agent first-name slug resolved from config/agent.json (SOT).
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_DIR="$(dirname "$SCRIPT_DIR")"
+LOG_FILE="$AGENT_DIR/logs/operations.log"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+
+# Resolve agent first-name slug.
+AGENT_FIRST=""
+if [ -f "$AGENT_DIR/config/agent.json" ]; then
+    if command -v jq >/dev/null 2>&1; then
+        AGENT_FIRST=$(jq -r '.firstName // empty' "$AGENT_DIR/config/agent.json" | tr '[:upper:]' '[:lower:]')
+    else
+        AGENT_FIRST=$(awk -F'"' '/"firstName"[[:space:]]*:/ { print tolower($4); exit }' "$AGENT_DIR/config/agent.json")
+    fi
+fi
+[ -z "$AGENT_FIRST" ] && AGENT_FIRST=$(basename "$AGENT_DIR" | sed 's/-ai$//')
+
+LAUNCH_AGENTS_DIR="$HOME/Library/LaunchAgents"
+# Match the current ai.maestro.* namespace AND the legacy ai.adaptic.* one
+# (deployed agents whose plists predate the rename). The loops guard with [ -f ].
+PLIST_GLOB="$LAUNCH_AGENTS_DIR/ai.maestro.${AGENT_FIRST}-*.plist $LAUNCH_AGENTS_DIR/ai.adaptic.${AGENT_FIRST}-*.plist"
+
+# Check if stop flag exists.
+if [ ! -f "$AGENT_DIR/.emergency-stop" ]; then
+    echo "No emergency stop flag found — system is already running."
+    # Still verify launchd jobs are loaded; if not, load them.
+    loaded=0
+    for plist in $PLIST_GLOB; do
+        [ -f "$plist" ] || continue
+        label=$(basename "$plist" .plist)
+        if ! launchctl list | grep -q "$label"; then
+            launchctl load "$plist" 2>/dev/null && loaded=$((loaded + 1))
+        fi
+    done
+    [ "$loaded" -gt 0 ] && echo "Loaded $loaded missing launchd job(s)"
+    exit 0
+fi
+
+echo "[$TIMESTAMP] RESUMING OPERATIONS (agent=$AGENT_FIRST)" | tee -a "$LOG_FILE"
+
+# 1. Run health check first.
+echo "Running health check..."
+if ! "$SCRIPT_DIR/healthcheck.sh"; then
+    echo "ERROR: Health check failed. Fix issues before resuming."
+    exit 1
+fi
+
+# 2. Remove stop flag.
+rm "$AGENT_DIR/.emergency-stop"
+echo "[$TIMESTAMP] Stop flag removed" >> "$LOG_FILE"
+
+# 3. Reload installed launchd jobs.
+echo "Reloading installed launchd jobs ($PLIST_GLOB)..."
+loaded=0
+for plist in $PLIST_GLOB; do
+    if [ -f "$plist" ]; then
+        # Unload first in case it was left in a half-loaded state.
+        launchctl unload "$plist" 2>/dev/null || true
+        launchctl load "$plist" 2>/dev/null || true
+        echo "[$TIMESTAMP] Loaded: $(basename "$plist")" >> "$LOG_FILE"
+        loaded=$((loaded + 1))
+    fi
+done
+echo "[$TIMESTAMP] Loaded $loaded launchd job(s)" >> "$LOG_FILE"
+
+echo "[$TIMESTAMP] OPERATIONS RESUMED" | tee -a "$LOG_FILE"

package/scripts/search-secondary-inbox.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Search Alex's Gmail inbox via IMAP for correspondence matching a query.
+
+Usage: python3 search-secondary-inbox.py "<search_query>" [--max N] [--full]
+  --max N   : Maximum messages to return (default: 20)
+  --full    : Include full message bodies (default: headers + snippet)
+
+Examples:
+  python3 search-secondary-inbox.py "from:difc.ae"
+  python3 search-secondary-inbox.py "difc fitout" --max 50 --full
+"""
+import sys
+import os
+import imaplib
+import email
+from email.header import decode_header
+import json
+from datetime import datetime
+
+PRINCIPAL_EMAIL = "alex@example.com"
+MEHRAN_PASSWORD = os.environ.get("MEHRAN_GMAIL_APP_PASSWORD", "")
+
+# Load from .env if not in environment
+if not MEHRAN_PASSWORD:
+    env_path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), ".env")
+    if os.path.exists(env_path):
+        with open(env_path) as f:
+            for line in f:
+                if line.startswith("MEHRAN_GMAIL_APP_PASSWORD="):
+                    MEHRAN_PASSWORD = line.strip().split("=", 1)[1].strip()
+                    break
+
+if not MEHRAN_PASSWORD:
+    print("ERROR: MEHRAN_GMAIL_APP_PASSWORD not set", file=sys.stderr)
+    sys.exit(1)
+
+
+def decode_header_value(value):
+    """Decode email header value handling various encodings."""
+    if not value:
+        return ""
+    decoded_parts = decode_header(value)
+    result = []
+    for part, encoding in decoded_parts:
+        if isinstance(part, bytes):
+            result.append(part.decode(encoding or "utf-8", errors="replace"))
+        else:
+            result.append(str(part))
+    return " ".join(result)
+
+
+def get_body(msg):
+    """Extract text body from email message."""
+    body = ""
+    if msg.is_multipart():
+        for part in msg.walk():
+            content_type = part.get_content_type()
+            content_disposition = str(part.get("Content-Disposition", ""))
+            if content_type == "text/plain" and "attachment" not in content_disposition:
+                try:
+                    payload = part.get_payload(decode=True)
+                    if payload:
+                        charset = part.get_content_charset() or "utf-8"
+                        body += payload.decode(charset, errors="replace")
+                except Exception:
+                    pass
+            elif content_type == "text/html" and not body and "attachment" not in content_disposition:
+                try:
+                    payload = part.get_payload(decode=True)
+                    if payload:
+                        charset = part.get_content_charset() or "utf-8"
+                        body += payload.decode(charset, errors="replace")
+                except Exception:
+                    pass
+    else:
+        try:
+            payload = msg.get_payload(decode=True)
+            if payload:
+                charset = msg.get_content_charset() or "utf-8"
+                body = payload.decode(charset, errors="replace")
+        except Exception:
+            pass
+    return body
+
+
+def get_attachments(msg):
+    """List attachment filenames and sizes."""
+    attachments = []
+    if msg.is_multipart():
+        for part in msg.walk():
+            content_disposition = str(part.get("Content-Disposition", ""))
+            if "attachment" in content_disposition or (
+                part.get_filename() and part.get_content_type() != "text/plain"
+            ):
+                filename = decode_header_value(part.get_filename() or "unnamed")
+                size = len(part.get_payload(decode=True) or b"")
+                attachments.append({"filename": filename, "size": size, "content_type": part.get_content_type()})
+    return attachments
+
+
+def search_inbox(query, max_results=20, full_body=False):
+    """Search Alex's Gmail via IMAP."""
+    mail = imaplib.IMAP4_SSL("imap.gmail.com")
+    mail.login(PRINCIPAL_EMAIL, MEHRAN_PASSWORD)
+
+    # Use All Mail to search everything
+    mail.select('"[Gmail]/All Mail"')
+
+    # Build IMAP search criteria
+    # Gmail supports X-GM-RAW for full Gmail search syntax
+    status, message_ids = mail.search(None, f'X-GM-RAW "{query}"')
+
+    if status != "OK" or not message_ids[0]:
+        print(json.dumps({"query": query, "results": [], "total": 0}, indent=2))
+        mail.logout()
+        return
+
+    ids = message_ids[0].split()
+    total = len(ids)
+    # Get most recent N messages (IMAP returns oldest first)
+    ids = ids[-max_results:] if len(ids) > max_results else ids
+    ids.reverse()  # newest first
+
+    results = []
+    for msg_id in ids:
+        try:
+            if full_body:
+                status, data = mail.fetch(msg_id, "(RFC822)")
+            else:
+                status, data = mail.fetch(msg_id, "(RFC822)")
+
+            if status != "OK" or not data[0]:
+                continue
+
+            raw_email = data[0][1]
+            msg = email.message_from_bytes(raw_email)
+
+            result = {
+                "from": decode_header_value(msg.get("From", "")),
+                "to": decode_header_value(msg.get("To", "")),
+                "cc": decode_header_value(msg.get("Cc", "")),
+                "subject": decode_header_value(msg.get("Subject", "")),
+                "date": msg.get("Date", ""),
+                "message_id": msg.get("Message-ID", ""),
+                "in_reply_to": msg.get("In-Reply-To", ""),
+            }
+
+            body = get_body(msg)
+            if full_body:
+                result["body"] = body
+            else:
+                result["snippet"] = body[:500] + ("..." if len(body) > 500 else "")
+
+            attachments = get_attachments(msg)
+            if attachments:
+                result["attachments"] = attachments
+
+            results.append(result)
+        except Exception as e:
+            results.append({"error": str(e), "msg_id": msg_id.decode()})
+
+    mail.logout()
+
+    output = {
+        "query": query,
+        "total_matches": total,
+        "returned": len(results),
+        "results": results
+    }
+    print(json.dumps(output, indent=2, ensure_ascii=False, default=str))
+
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(description="Search Alex's Gmail inbox via IMAP")
+    parser.add_argument("query", help="Gmail search query")
+    parser.add_argument("--max", type=int, default=20, help="Maximum results (default: 20)")
+    parser.add_argument("--full", action="store_true", help="Include full message bodies")
+    args = parser.parse_args()
+
+    search_inbox(args.query, max_results=args.max, full_body=args.full)