Bot Process Control

Manage the Gmail Commander bot daemon and scheduled digest via launchd.

Mandatory Preflight

Step 1: Check Current Process Status

echo "=== Gmail Commander Processes ==="
pgrep -fl "gmail-commander" 2>/dev/null || echo "No processes found"

echo ""
echo "=== launchd Status ==="
launchctl list | grep gmail-commander 2>/dev/null || echo "No launchd jobs"

echo ""
echo "=== PID Files ==="
cat /tmp/gmail-commander-bot.pid 2>/dev/null && echo " (bot)" || echo "No bot PID file"
cat /tmp/gmail-digest.pid 2>/dev/null && echo " (digest)" || echo "No digest PID file"

Two Services

Service	Type	Trigger	PID File
Bot Daemon	KeepAlive	Always-on (grammY polling)	/tmp/gmail-commander-bot.pid
Digest	StartInterval	Every 6 hours (21600s)	/tmp/gmail-digest.pid

launchd Plist Templates

Bot Daemon — com.terryli.gmail-commander-bot.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.terryli.gmail-commander-bot</string>
    <key>ProgramArguments</key>
    <array>
        <string>{{HOME}}/own/amonic/bin/gmail-commander-bot</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <dict>
        <key>NetworkState</key>
        <true/>
    </dict>
    <key>StandardOutPath</key>
    <string>{{HOME}}/.local/state/launchd-logs/gmail-commander-bot/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>{{HOME}}/.local/state/launchd-logs/gmail-commander-bot/stderr.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>{{HOME}}/.local/share/mise/shims:/usr/local/bin:/usr/bin:/bin</string>
    </dict>
    <key>ThrottleInterval</key>
    <integer>10</integer>
</dict>
</plist>

Scheduled Digest — com.terryli.gmail-commander-digest.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.terryli.gmail-commander-digest</string>
    <key>ProgramArguments</key>
    <array>
        <string>{{HOME}}/own/amonic/bin/gmail-commander-digest</string>
    </array>
    <key>StartInterval</key>
    <integer>21600</integer>
    <key>StandardOutPath</key>
    <string>{{HOME}}/.local/state/launchd-logs/gmail-commander-digest/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>{{HOME}}/.local/state/launchd-logs/gmail-commander-digest/stderr.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>{{HOME}}/.local/share/mise/shims:/usr/local/bin:/usr/bin:/bin</string>
    </dict>
</dict>
</plist>

Quick Operations

Start Bot

launchctl load ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist

Stop Bot

launchctl unload ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist

Restart Bot

launchctl unload ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist
launchctl load ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist

Force Kill (Emergency)

pkill -f "gmail-commander.*bot.ts"
rm -f /tmp/gmail-commander-bot.pid

View Logs

# Recent bot output (centralized launchd logs)
tail -50 ~/.local/state/launchd-logs/gmail-commander-bot/stderr.log

# Recent digest output
tail -50 ~/.local/state/launchd-logs/gmail-commander-digest/stderr.log

# Audit log (NDJSON, app-managed)
cat $PROJECT_DIR/logs/audit/$(date +%Y-%m-%d).ndjson | jq .

# OAuth token refresher log
tail -20 ~/.local/state/launchd-logs/gmail-oauth-refresher/stderr.log

System Resources (Expected)

• Memory: ~20-30 MB RSS (Bun runtime + grammY)
• CPU: Negligible (idle polling, wakes on message)
• Network: Minimal (single long-poll connection to Telegram API)
• Disk: ~1 MB/day audit logs (14-day rotation)

Telegram Commands

Command	Description
/inbox	Show recent inbox emails
/search	Search emails (Gmail query syntax)
/read	Read email by ID
/compose	Compose a new email
/reply	Reply to an email
/abort	Cancel current compose/reply action
/drafts	List draft emails
/digest	Run email digest now
/status	Bot status and stats
/help	Show all commands

Note: /abort cancels any in-progress compose or reply session. Works at any step in the flow.

OAuth Token Management

Two-Layer Token Architecture

Browser Auth (one-time, interactive)
  → Google issues: access_token (1h TTL) + refresh_token (7d TTL in Testing mode)
  → Saved to: ~/.claude/tools/gmail-tokens/<GMAIL_OP_UUID>.json

Silent Refresh (automatic, no browser)
  → Uses refresh_token to get new access_token
  → Fails with invalid_grant when refresh_token itself expires

Hourly Token Refresher (launchd)

A compiled Swift binary runs hourly to proactively refresh the access token:

File	Path
Source	~/.claude/automation/gmail-token-refresher/main.swift
Binary	~/.claude/automation/gmail-token-refresher/gmail-oauth-token-hourly-refresher
Plist	~/Library/LaunchAgents/com.terryli.gmail-oauth-token-hourly-refresher.plist
Log	$PROJECT_DIR/logs/token-refresher.log

Why hourly: Access tokens expire every 1 hour. Refreshing hourly keeps the token perpetually valid. Frequent refresh also increases the chance Google issues a new refresh_token, resetting its 7-day clock.

Verify it's running:

launchctl list | grep gmail-oauth-token
tail -5 $PROJECT_DIR/logs/token-refresher.log

Credentials source: GMAIL_OP_UUID item in 1Password Claude Automation vault (fields: client_id, client_secret). Accessed via service account token — no biometric prompt required.

Diagnosing invalid_grant

invalid_grant means the refresh token itself expired (not just the access token):

# Symptom in audit log:
cat $PROJECT_DIR/logs/audit/$(date +%Y-%m-%d).ndjson | jq 'select(.event == "gmail.error")'
# → "Token expired, refreshing...\nError: invalid_grant\n"

# Check token file age:
ls -la ~/.claude/tools/gmail-tokens/<GMAIL_OP_UUID>.json

Fix:

# 1. Delete expired token
rm ~/.claude/tools/gmail-tokens/<GMAIL_OP_UUID>.json

# 2. Trigger browser re-auth (opens Google consent page)
source $PROJECT_DIR/.env.launchd
$PLUGIN_DIR/scripts/gmail-cli/gmail list -n 1

# 3. Restart bot
launchctl unload ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist
launchctl load ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist

Root cause: Google OAuth apps in Testing mode issue refresh tokens with 7-day TTL. Permanent fix: publish the Google Cloud OAuth app (Google Cloud Console → OAuth consent screen → Publish app).

Diagnosing Stale PID Lock

If the bot exits uncleanly, the PID file may block restart:

# Symptom: launchctl shows bot loaded but PID is dead
kill -0 $(cat /tmp/gmail-commander-bot.pid) 2>&1
# → "No such process"

# Fix: restart via launchctl (acquireLock handles stale PIDs automatically)
launchctl unload ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist
launchctl load ~/Library/LaunchAgents/com.terryli.gmail-commander-bot.plist

Post-Change Checklist

• YAML frontmatter valid (no colons in description)
• Trigger keywords current
• Path patterns use $HOME not hardcoded paths
• launchd plist templates match actual launcher scripts
• OAuth token refresher launchd service loaded and running