Backed by: state/bin/email-send-tick.ts, state/lib/email.ts (read-side: queue + sendEmailDraft).

email-send-tick

The consumer half of snappy-os's scheduled-send pipeline. Producers append rows to state/log/email-send-queue.ndjson via scheduleSendDraft({...}). This skill (LaunchAgent-driven, every 60 s) reads the queue, finds rows where status == "scheduled" AND sendAt <= now, and sends them via sendEmailDraft(draftId, account). Atomic queue rewrite (temp + rename); idempotent on a per-tick basis.

Producers today: meeting-followup. Future: any skill that needs deferred client-comm send. The contract is the queue row shape, not the producing skill - adding new producers requires no change here.

Steps

1. Read the queue

const lines = readFileSync("state/log/email-send-queue.ndjson", "utf8").split("\n").filter(Boolean);
const rows = lines.map(l => JSON.parse(l));
const now = new Date();
const ready = rows.filter(r => r.status === "scheduled" && new Date(r.sendAt) <= now);

2. Honour the global kill switch

if (process.env.SNAPPY_EMAIL_AUTO_SEND_DISABLED === "1") {
  // log a no-op tick + exit cleanly
  score("email-send-tick", run_id, { score: 1.0, primary_issue: "kill-switch-active", sent: 0, ready: ready.length });
  process.exit(0);
}

3. For each ready row - send, veto, or retry

for (const row of ready) {
  try {
    const sent = await sendEmailDraft(row.draftId, row.account || "work");
    row.status = "sent";
    row.sent_message_id = sent.id;
    appendNdjson("state/log/email-sent.ndjson", { ts: now.toISOString(), ...row, sent_message_id: sent.id });
  } catch (err) {
    if (is404(err)) {
      // Veto: Robert deleted the draft in Gmail before the window expired.
      // Not an error — the user explicitly declined.
      row.status = "vetoed";
      row.error = "draft not found (Gmail 404 — likely deleted or already sent)";
    } else if (isTransient(err) && (row.retry_count ?? 0) < 3) {
      // Network blip / 5xx / rate-limit. Bump retry count, leave status="scheduled" — next tick retries.
      row.retry_count = (row.retry_count ?? 0) + 1;
      appendNdjson("state/log/email-send-errors.ndjson", { ts: now.toISOString(), draftId: row.draftId, error: errMsg(err), retry_count: row.retry_count });
    } else {
      // Permanent failure OR retry cap reached.
      row.status = "failed";
      row.error = errMsg(err);
    }
  }
}

4. Atomic queue rewrite

const tmp = `state/log/email-send-queue.ndjson.tmp.${process.pid}`;
writeFileSync(tmp, rows.map(r => JSON.stringify(r)).join("\n") + (rows.length ? "\n" : ""));
renameSync(tmp, "state/log/email-send-queue.ndjson");

Never leave a half-written queue - partial writes corrupt the next tick's read. If the rename fails, the original file is intact.

5. Score

const score = (sent_count > 0 || ready.length === 0) ? 1.0 : 0.0;
const primary_issue = failed_count > 0 ? `failed:${failed_count}` : transient_errors > 0 ? `transient:${transient_errors}` : null;
score("email-send-tick", run_id, { score, primary_issue, sent: sent_count, vetoed: vetoed_count, failed: failed_count, ready: ready.length, transient_errors, queue_size: rows.length });

Eval

Actor: the queue-read + send loop (run_id-bound process). Auditor: independent re-read of the queue file from disk after the rewrite, confirming each row that the actor claimed to send has status: "sent" and a sent_message_id. Auditor uses a different session id (<actor_session>-auditor-<pid>-<ts>).

Gotchas

• Atomic write or nothing. A non-atomic rewrite (write directly to email-send-queue.ndjson) corrupts the queue if the process is killed mid-write. Always temp + rename.
• Veto path is NOT an error. Gmail 404 on drafts.send means the user (or another process) deleted the draft. Mark status: "vetoed", no retry, no friction. The veto window is the whole point of the design.
• Retry cap = 3. Beyond that, status: "failed" and stop. Don't loop forever - failed rows surface in the queue file for human review.
• Don't send rows where apply: true is missing on the producer side. The queue contract assumes the producer already gated. This consumer is just executing scheduled work; it does not re-validate.
• Per-account credentials. Default account: "work" (service-account JWT for robert@snappy.ai). For account: "personal", the OAuth refresh token in .env.cache resolves the token - same auth path as createEmailDraft.
• The kill switch is belt-and-suspenders. SNAPPY_EMAIL_AUTO_SEND_DISABLED=1 halts sends but the LaunchAgent still ticks (so the audit trail keeps flowing - easier to verify the switch is honoured).

Install (LaunchAgent)

cp state/launchd/com.snappy.email-send-tick.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.snappy.email-send-tick.plist
launchctl list | grep email-send-tick   # confirm loaded; second column is exit status of last run

To pause without uninstalling:

launchctl unload ~/Library/LaunchAgents/com.snappy.email-send-tick.plist

Or set the kill switch globally:

launchctl setenv SNAPPY_EMAIL_AUTO_SEND_DISABLED 1

To resume: unset (launchctl unsetenv SNAPPY_EMAIL_AUTO_SEND_DISABLED) or launchctl load.

Rubric

criteria:
  - name: queue_atomic_rewrite
    kind: deterministic
    check: "After every tick, state/log/email-send-queue.ndjson is either the original file or the new file — never partially-written. Verified by file size monotonicity within a tick."
  - name: ready_rows_processed
    kind: deterministic
    check: "Every row that satisfied (status=scheduled AND sendAt<=now) at tick start has status != scheduled at tick end."
  - name: sent_rows_have_message_id
    kind: deterministic
    check: "Every row with status=sent has a non-empty sent_message_id field; every such id appears in state/log/email-sent.ndjson with matching draftId."
  - name: vetoed_marked_not_failed
    kind: deterministic
    check: "Gmail 404 responses are recorded as status=vetoed, NOT status=failed. Verified by inspecting error strings on vetoed rows."
  - name: kill_switch_honoured
    kind: deterministic
    check: "When SNAPPY_EMAIL_AUTO_SEND_DISABLED=1, no row's status changes from scheduled to sent in that tick."
  - name: actor_auditor_distinct
    kind: deterministic
    check: "actor_session_id and auditor_session_id on the eval row are non-empty and differ — proves actor != auditor."

email-send-tick - loader

Per-turn rules for the email-send-tick skill. The minute-cron consumer of state/log/email-send-queue.ndjson - sends drafts whose veto window expired, marks vetoed / failed / transient, retries transient errors up to 3x. Atomic queue rewrite (temp + rename); idempotent per tick. Backed by state/bin/email-send-tick.ts + state/lib/email.ts (read-side: queue + sendEmailDraft). Full reference: state/skills/email-send-tick/SKILL.md. Do not skip these.

Critical Rules

1. HONOUR THE KILL SWITCH FIRST. Check process.env.SNAPPY_EMAIL_AUTO_SEND_DISABLED === "1" at the top of every tick. If set, log a no-op eval row with primary_issue: "kill-switch-active" and exit. No reads, no sends.
2. ATOMIC QUEUE REWRITE OR NOTHING. Always write to a temp path (state/log/email-send-queue.ndjson.tmp.<pid>) then rename. Direct writes corrupt the queue if the process is killed mid-write.
3. GMAIL 404 IS A VETO, NOT A FAILURE. When sendEmailDraft throws a 404, the user (or another process) deleted the draft before the window expired. That is the whole point of the design. Mark status: "vetoed", no retry, no friction row.
4. RETRY CAP = 3. Transient errors (network, 5xx, rate-limit) bump retry_count and leave status: "scheduled". Past 3 retries → status: "failed", stop.
5. DON'T VALIDATE PRODUCER GATING. This consumer assumes apply: true was already gated on the producer side (e.g. meeting-followup only schedules on eval=1.0). The consumer is execution, not policy.
6. ACTOR ≠ AUDITOR. The actor session id is email-send-tick-<run_id>; the auditor session id includes pid + ms timestamp. Both must appear on the eval row, distinct.
7. NEVER REORDER ROWS IN THE QUEUE. Mutate row fields in place; preserve insertion order so tail -n always shows the most recent activity at the end.

Commands

| ui dashboard | state/skills/email-send-tick/resources/ui.openui | |invoke (manual): npx tsx state/bin/email-send-tick.ts |sidecar: state/bin/email-send-tick.ts |launchd plist: state/launchd/com.snappy.email-send-tick.plist |install: cp state/launchd/com.snappy.email-send-tick.plist ~/Library/LaunchAgents/ && launchctl load ~/Library/LaunchAgents/com.snappy.email-send-tick.plist |kill switch (global): launchctl setenv SNAPPY_EMAIL_AUTO_SEND_DISABLED 1 - unset to resume |pause without uninstall: launchctl unload ~/Library/LaunchAgents/com.snappy.email-send-tick.plist |queue: state/log/email-send-queue.ndjson (in-flight rows, all statuses) |sent log: state/log/email-sent.ndjson (append-only, every successful send) |error log: state/log/email-send-errors.ndjson (append-only, every transient/failed) |eval log: state/log/evals.ndjson (skill: "email-send-tick")

Producers (who writes to the queue)

To add a new producer: import scheduleSendDraft({draftId, sendAt, recipient, subject, account, meta}) from state/lib/email.ts, gate on the producer's own eval, append. The queue contract is the row shape, not the producer name.

Score Table

Self-Test

An agent reading this should correctly:

1. [ ] Honour SNAPPY_EMAIL_AUTO_SEND_DISABLED=1 before any queue read?
2. [ ] Distinguish Gmail-404 (veto) from other 4xx (failure) on send error?
3. [ ] Atomic-rewrite the queue file (temp + rename), never direct-write?
4. [ ] Cap retries at 3 then mark status: "failed"?
5. [ ] Emit a distinct actor_session_id and auditor_session_id on the eval row?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] email-send-tick: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] email-send-tick: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/email-send-tick/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.