Skip to content

Commit 38c136a

Browse files
mayoalexanderclaude
andcommitted
fix(comms): a send the log never heard about, and the 61% of a relationship it could not see
Two defects, same consequence: the comms log reports success while missing real correspondence, and it misses it in the direction that looks like silence rather than like an error. 1. `iris mail send` with --from/--cc/--attachment sent the email and recorded NOTHING. Those flags have no router path, which is a reason the send cannot be ROUTED — it is not a reason it cannot be LOGGED. The CLI printed "not logged to comms" and moved on, quietly reintroducing the failure CR-8 existed to remove. Transport and bookkeeping are separate concerns: the bridge still carries those sends, and `recordDirectSend` now puts them on the ledger afterwards. A draft is excluded — it has not gone anywhere, and logging one would put a message on someone's record that they never received. When the record fails it says SENT BUT NOT LOGGED with the reason and the command to fix it, because the one thing this must never do again is look fine. 2. The ingest only ever searched `lead.email`. A lead has one primary address and any number of alternates in contact_info.emails, and everything written from an alternate was invisible. Measured on lead anomalyco#10394 today: 27 messages on the primary the ingest reads, 43 on the two it did not — 61% of the correspondence absent from a log that returned "1 new, 0 skipped" and called it done. He is Apple-native and writes from iCloud; the address we filed him under was his work one. That is not an edge case, it is the common case for anyone with a work and a personal address. `leadEmails()` is now the single answer to "what addresses is this person reachable at", and both the Apple Mail and iMessage paths use it. The bridge filters on one `from` per call, so it is one search per address; the server dedups on external_message_id, so an overlapping address costs a round trip rather than a duplicate row. Not fixed here: the bridge search is capped at days=90, so a backfill cannot reach further back than that no matter how many addresses it knows about. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01FEVuQjtBdw2Mq3EpE56GFY
1 parent 7a0c281 commit 38c136a

14 files changed

Lines changed: 1157 additions & 57 deletions

‎.husky/pre-push‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,47 @@ fi
7878
exit 1
7979
}
8080

81+
# Playbooks must not validate clean and then misbehave.
82+
#
83+
# `iris playbook test` answers "does this parse and match the schema". On 2026-09-04 three
84+
# defects passed that and shipped to the public marketplace anyway, because none of them are
85+
# schema questions:
86+
#
87+
# - work-the-epic defaulted to `bloq: 297` — the authors' own bug board. Every stranger who
88+
# installed it would file their planning document into someone else's project. A default
89+
# on a shared artifact is a default for every tenant.
90+
# - Its publish step read /tmp/epic-draft.md, which NO step ever wrote: the draft step is
91+
# `mode: ai`, and an AI step returns text, it cannot write a file. So it published
92+
# whatever a previous run had left in /tmp. Five epics shipped green carrying stale
93+
# content; a clean /tmp gives an honest error and a dirty one gives a confident lie.
94+
# - console-shape carried the same impossible write-a-file instruction.
95+
#
96+
# scaffold/playbooks is compiled into the binary, so everyone who installs the CLI gets it —
97+
# a tenant default there is always an error. The workspace set is linted too when present,
98+
# with tenancy downgraded to a warning: a private playbook named after one tenant is allowed
99+
# to hardcode that tenant, and flagging it would teach people to ignore the hook.
100+
#
101+
# No network, no auth, no fixtures — same constraint as the routes check above.
102+
(cd packages/opencode && bun run playbooks:check) || {
103+
echo ""
104+
echo " A shipped playbook has a defect the schema validator cannot see."
105+
echo " Fix it above — do not publish; 'iris playbook test' will still call it valid."
106+
exit 1
107+
}
108+
109+
PROJECT_ROOT="${IRIS_PROJECT_ROOT:-$HOME/sites/freelabel}"
110+
if [ -d "$PROJECT_ROOT/.iris/playbooks" ]; then
111+
# bun, not node: the script imports the rules from src/skill/playbook-lint.ts so there is
112+
# only one copy of them, and node cannot load a .ts file
113+
# (ERR_UNKNOWN_FILE_EXTENSION). This hook caught that itself, on the push that introduced it.
114+
bun packages/opencode/script/check-playbooks.mjs "$PROJECT_ROOT/.iris/playbooks" --tenancy=warn || {
115+
echo ""
116+
echo " A workspace playbook has a defect that survives 'iris playbook test'."
117+
echo " These are the ones published to the marketplace — fix before publishing."
118+
exit 1
119+
}
120+
fi
121+
81122
# Every how-to in scaffold/ must be in scaffold/manifest.json.
82123
#
83124
# The installer fetches the MANIFEST and downloads what it lists — adding a recipe file

‎packages/opencode/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
"capabilities": "bun run script/build-capabilities.ts",
2222
"capabilities:check": "bun run script/build-capabilities.ts --check",
2323
"routes:check": "bun run script/check-routes.ts",
24+
"playbooks:check": "bun run script/check-playbooks.mjs",
2425
"routes:refresh": "sh script/refresh-routes.sh"
2526
},
2627
"bin": {
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
#!/usr/bin/env bun
2+
/**
3+
* CLI wrapper around the playbook linter. THE RULES ARE NOT HERE.
4+
*
5+
* They live in src/skill/playbook-lint.ts, imported below, because the publish command needs
6+
* them at runtime and `bun build --compile` bundles static imports rather than files read
7+
* from disk — a rules copy in script/ would simply be absent from the installed binary.
8+
*
9+
* This file had its own copy for exactly one commit. That copy contained `\Z`, which
10+
* JavaScript does not support (it matches a literal "Z"), so it silently skipped the last
11+
* declared arg of every playbook it scanned and reported the corpus clean. One set of rules,
12+
* one place — the same reason `aiPromptFrom` exists.
13+
*
14+
* Usage: check-playbooks.mjs [dir ...] [--tenancy=error|warn]
15+
* Default: <repo>/scaffold/playbooks — the set compiled into the binary, installed by
16+
* everyone, so a tenant default there is always an error.
17+
*/
18+
import { readdirSync, readFileSync, existsSync } from "node:fs"
19+
import { join, resolve, dirname } from "node:path"
20+
import { fileURLToPath } from "node:url"
21+
import { lintPlaybook, blockingFindings, PLAYBOOK_RULES } from "../src/skill/playbook-lint.ts"
22+
23+
const args = process.argv.slice(2)
24+
const tenancy = (args.find((a) => a.startsWith("--tenancy=")) || "--tenancy=error").split("=")[1]
25+
const dirs = args.filter((a) => !a.startsWith("--"))
26+
27+
// Resolve the default target from THIS FILE, not from cwd. It was cwd-relative, and the npm
28+
// target runs from packages/opencode while the corpus sits at the repo root — so the check
29+
// printed "clean" and exited 0 having scanned ZERO playbooks. A gate that cannot see its own
30+
// corpus must not report the same success as one that checked it.
31+
const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..")
32+
if (!dirs.length) dirs.push(join(REPO_ROOT, "scaffold/playbooks"))
33+
34+
const findings = []
35+
let scanned = 0
36+
37+
for (const dir of dirs) {
38+
// A missing target is a BROKEN GATE, not a clean one. The caller decides whether a
39+
// directory is worth checking; once it has asked, "not present" must never read as "fine".
40+
if (!existsSync(dir)) {
41+
console.error(`check-playbooks: cannot read ${dir} — refusing to report a corpus it never saw.`)
42+
process.exit(2)
43+
}
44+
for (const name of readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name)) {
45+
const file = join(dir, name, "PLAYBOOK.md")
46+
if (!existsSync(file)) continue
47+
scanned++
48+
for (const f of lintPlaybook(readFileSync(file, "utf8"))) findings.push({ ...f, name })
49+
}
50+
}
51+
52+
// `--tenancy=warn` mirrors blockingFindings(..., "private"): a playbook only you can install
53+
// may hardcode your own ids. Everything else is a defect at any scope.
54+
const errors = tenancy === "warn" ? findings.filter((f) => blockingFindings([f], "private").length) : findings
55+
for (const f of findings) f.warn = !errors.includes(f)
56+
57+
console.log(`check-playbooks — ${scanned} playbook(s) in ${dirs.join(", ")}`)
58+
if (scanned === 0) {
59+
console.error("check-playbooks: scanned 0 playbooks — the gate measured nothing. Treating as failure.")
60+
process.exit(2)
61+
}
62+
if (!findings.length) console.log(" clean")
63+
64+
const byRule = {}
65+
for (const f of findings) (byRule[f.rule] ||= []).push(f)
66+
for (const [rule, list] of Object.entries(byRule)) {
67+
console.log(`\n${rule} (${list.length})`)
68+
console.log(` ${PLAYBOOK_RULES[rule]}`)
69+
for (const f of list) console.log(` ${f.warn ? "warn " : "ERROR"} ${f.name.padEnd(24)} ${f.detail}`)
70+
}
71+
if (findings.length) console.log(`\n${errors.length} error(s), ${findings.length - errors.length} warning(s)`)
72+
process.exit(errors.length ? 1 : 0)

‎packages/opencode/src/cli/cmd/comms-send.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,3 +121,81 @@ export function describeSend(r: RouterSendResult): string {
121121
const step = r.stepAdvanced ? `, completed step #${r.stepAdvanced}` : ""
122122
return `Sent via ${r.channel} — ${logged}${step}`
123123
}
124+
125+
export interface RecordSendInput {
126+
/** Recipient handle — an email address for apple_mail. Resolved to a lead to find the ledger row. */
127+
toHandle: string
128+
channel: string
129+
subject?: string
130+
message: string
131+
/** Where it went out from, for the record. */
132+
origin?: string
133+
}
134+
135+
export interface RecordSendResult {
136+
ok: boolean
137+
leadId?: number
138+
commId?: number | null
139+
/** Why nothing was written. Always set when ok is false — "it didn't log" is not an answer. */
140+
error?: string
141+
}
142+
143+
/**
144+
* Put a message that has ALREADY been sent onto the record.
145+
*
146+
* routerSend sends and books in one call, but it cannot carry attachments, cc, or a raw --from,
147+
* so those sends go out through the bridge instead. That was treated as a reason not to log them
148+
* — the CLI printed "not logged to comms" and wrote nothing — which quietly reintroduced the
149+
* exact failure CR-8 existed to remove. A send the log does not know about makes every "have we
150+
* contacted them?" answer wrong, and it is wrong in the dangerous direction: it looks like
151+
* silence.
152+
*
153+
* Transport and bookkeeping are separate concerns. The bridge can own the first without taking
154+
* the second with it.
155+
*/
156+
export async function recordDirectSend(input: RecordSendInput): Promise<RecordSendResult> {
157+
let leadId: number | undefined
158+
159+
try {
160+
const res = await irisFetch(`/api/v1/leads?search=${encodeURIComponent(input.toHandle)}&per_page=1`)
161+
if (res.ok) {
162+
const payload = (await res.json().catch(() => null)) as any
163+
const rows = payload?.data?.data ?? payload?.data ?? []
164+
const first = Array.isArray(rows) ? rows[0] : null
165+
if (first?.id) leadId = Number(first.id)
166+
}
167+
} catch (err: any) {
168+
return { ok: false, error: `could not reach the leads API: ${err?.message ?? err}` }
169+
}
170+
171+
// No lead means no ledger row to attach to. Say so plainly — the operator can create the lead
172+
// and re-log. Reporting "recorded" here would be the same lie in a different place.
173+
if (!leadId) {
174+
return { ok: false, error: `no lead matches ${input.toHandle}` }
175+
}
176+
177+
try {
178+
const res = await irisFetch("/api/v1/atlas/comms/log", {
179+
method: "POST",
180+
body: JSON.stringify({
181+
lead_id: leadId,
182+
channel: input.channel,
183+
direction: "outbound",
184+
body: input.message,
185+
subject: input.subject ?? null,
186+
sent_at: new Date().toISOString(),
187+
}),
188+
})
189+
190+
if (!res.ok) {
191+
return { ok: false, leadId, error: `comms/log returned ${res.status}` }
192+
}
193+
194+
const payload = (await res.json().catch(() => null)) as any
195+
const record = payload?.data?.record ?? payload?.data ?? null
196+
197+
return { ok: true, leadId, commId: record?.id ?? null }
198+
} catch (err: any) {
199+
return { ok: false, leadId, error: `could not reach the comms API: ${err?.message ?? err}` }
200+
}
201+
}

‎packages/opencode/src/cli/cmd/platform-atlas-comms.ts‎

Lines changed: 60 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -53,13 +53,41 @@ async function resolveLead(idOrQuery: string): Promise<{ id: number; lead: any }
5353
return { id: leadId, lead: data?.data ?? data }
5454
}
5555

56+
/**
57+
* Every email address this lead is reachable at — not just the one in the `email` column.
58+
*
59+
* A lead has ONE primary email and any number of alternates in contact_info.emails, and the
60+
* ingest only ever searched the primary. For anyone who writes from a different address than
61+
* the one we filed them under, most of the relationship was invisible to the comms log, and
62+
* invisible in the direction that looks like silence rather than like an error.
63+
*
64+
* Measured on lead #10394 (2026-09-12): 27 messages on the primary address the ingest reads,
65+
* 43 on the two alternates it did not — 61% of the correspondence missing from a log that
66+
* reported success. He is Apple-native and writes from iCloud; the address we had on file was
67+
* his work one.
68+
*/
69+
function leadEmails(lead: any): string[] {
70+
const ci = lead?.contact_info ?? {}
71+
const raw = [lead?.email, ci?.email, ...(Array.isArray(ci?.emails) ? ci.emails : [])]
72+
73+
const seen = new Set<string>()
74+
const out: string[] = []
75+
for (const e of raw) {
76+
const addr = String(e ?? "").trim().toLowerCase()
77+
if (!addr || !addr.includes("@") || seen.has(addr)) continue
78+
seen.add(addr)
79+
out.push(addr)
80+
}
81+
return out
82+
}
83+
5684
// ── iMessage ingestion (via shared lib) ──
5785

5886
function ingestImessage(lead: any): any[] {
5987
const { searchByHandle, normalizeHandle } = require("../lib/imessage")
6088
const identifiers: string[] = []
6189
if (lead.phone) identifiers.push(normalizeHandle(lead.phone))
62-
if (lead.email) identifiers.push(lead.email)
90+
for (const addr of leadEmails(lead)) identifiers.push(addr)
6391
if (lead.instagram) identifiers.push(lead.instagram.replace("@", ""))
6492

6593
if (identifiers.length === 0) return []
@@ -206,28 +234,42 @@ function ingestWhatsapp(lead: any): any[] {
206234
// ── Gmail ingestion (via bridge or integration) ──
207235

208236
async function ingestGmail(lead: any): Promise<any[]> {
209-
const email = lead.email
210-
if (!email) return []
237+
const emails = leadEmails(lead)
238+
if (emails.length === 0) return []
239+
const email = emails[0]
211240

212241
try {
213-
// Try bridge first (has full body)
214-
const res = await fetch(`${BRIDGE_URL}/api/mail/search?from=${encodeURIComponent(email)}&days=90&limit=50&include_body=1`, {
215-
signal: AbortSignal.timeout(5000),
216-
})
217-
if (res.ok) {
242+
// One search PER ADDRESS. The bridge filters on a single `from`, so a lead with alternates
243+
// needs one call each — searching only the primary is what left 61% of #10394's mail out of
244+
// the log while the command reported success. The server dedups on external_message_id, so
245+
// an address that overlaps another costs a round trip, not a duplicate row.
246+
const collected: any[] = []
247+
let anyOk = false
248+
249+
for (const addr of emails) {
250+
const res = await fetch(`${BRIDGE_URL}/api/mail/search?from=${encodeURIComponent(addr)}&days=90&limit=50&include_body=1`, {
251+
signal: AbortSignal.timeout(5000),
252+
})
253+
if (!res.ok) continue
254+
anyOk = true
255+
218256
const data = (await res.json()) as any
219257
const messages = data?.messages ?? []
220-
return messages.map((m: any) => ({
221-
direction: "inbound" as const,
222-
from_identifier: m.sender || m.from || email,
223-
subject: m.subject,
224-
body: m.body || m.snippet,
225-
sent_at: m.date,
226-
external_message_id: m.messageId || m.id || `mail_${m.date}_${m.subject}`,
227-
metadata: { source: "apple_mail" },
228-
channel: "apple_mail", // override — this is Apple Mail, not Gmail API
229-
}))
258+
for (const m of messages) {
259+
collected.push({
260+
direction: "inbound" as const,
261+
from_identifier: m.sender || m.from || addr,
262+
subject: m.subject,
263+
body: m.body || m.snippet,
264+
sent_at: m.date,
265+
external_message_id: m.messageId || m.id || `mail_${m.date}_${m.subject}`,
266+
metadata: { source: "apple_mail", matched_address: addr },
267+
channel: "apple_mail", // override — this is Apple Mail, not Gmail API
268+
})
269+
}
230270
}
271+
272+
if (anyOk) return collected
231273
} catch { /* bridge not running */ }
232274

233275
// Fallback: Gmail API via fl-api integration

0 commit comments

Comments
 (0)