Agent loop decoupling: new lead → core loop → side effects

A generic core that answers a lead on any channel, with the channel it arrived on and the PMS it has to write back to both pushed out into adapters — so a crash in one adapter never blocks a reply, and a new channel or a new PMS is an adapter, not a rewrite.

2026-09-20 · Proposed — pending review (Fede, Gera, session 004) · owner: handoff to a fresh build session (plan and inspection by session 000-32; session 004 reviews against Option D) · new page (this is a multi-week program with its own buckets and tracker, like the portfolio-architecture pages; the Leasing Engine hub gets a one-line pointer later)

Why now

• Today, 2026-09-20, the AppFolio sync Lambda called Clara's compose-and-send inline on its 1-minute guest-card tick. One static AI-client import crashed the Lambda's cold start, and every Western Slope guest card that day went unanswered.
• Fixed for that failure mode tonight: PR #10317 makes the sync a producer onto a durable queue (lead.received) instead of a caller into Clara. A crash in the sync no longer touches the reply.
• But the reply path still does a PMS write inside itself: runSyndicatedGuestCardReply assigns the AppFolio card to Clara and adds a note as part of composing the reply, and the eligibility check that gates it reads raw AppFolio fields directly. A PMS write failure there can still take the reply down with it — the same shape of bug, one hop further in.
• Fede's ruling tonight: "the core agent lambda should just take all the context and then do the reply and then if there's side effects that need to happen like syncing to the PMS that should be a separate process … a generic core layer and then adapters for each configuration that knows what side effects it needs to deal with … not necessarily asynchronous, but decoupling."
• Four intake channels now (phone, text, email, PMS guest card) and a second PMS (Yardi) coming. Each channel can currently grow its own copy of "stamp engagement, write the card" — cheaper to fix the shape now than to multiply the same bug across channels and PMSs later.

Channels: one core, channel adapters at both edges

A shared per-turn hook already exists (conversation-manager.ts) and stamps engagement after a turn regardless of channel — that is the piece of "one core" Fede is describing, already built. The gap is that both edges around it still carry channel-specific one-offs instead of going through the same normalized event: voice re-does the engagement stamp and the PMS write on its own after the call ends; email's first-reply path skips the stamp entirely; nothing under one shared adapter decides "note vs. new card" once for every channel.

Target: side effects (create/update the guest card, note, assign, engagement stamp) are defined once, on outcome events, and fire the same way whether the lead arrived by phone, text, or email.

Target shape

Outbox key shapes: rows keyed OUTBOX#<type>#<eventId>, dedupe on OUTBOXKEY#<type>#<org>#<kind>#<id> written via transactWriteWithReasons, one drainer, with type generalized from today's lead.received-only constant — no second outbox.

What stays coupled, and why that's fine

• One conversation record, shared by every channel (Conversation.channel in src/lib/data/types.ts) — the record is the point of coupling on purpose; splitting it per channel would lose "one prospect, one thread."
• Temporal follow-up cadence reads that one record; it doesn't need to know which channel is answering it right now.
• The review hold (bake-gate.ts) sits inside the core loop's send step, not in an adapter — it gates the reply itself, before any channel or PMS sees it.
• Sync vs. async is an adapter's own choice, not a core rule: the AppFolio adapter can run in the same drain tick it does today; it just can never be able to fail the reply.

Buckets, dependencies, sequence

Sequence: B0 → B1 → B2 → B3 → {B4, B6} → B5. Lanes by directory ownership (Constitution IV-A). Steady burn: 2–3 Sonnet builders always on, one PR per row, each ≤300 lines, dependent chain on one integration branch; Opus review only where judgment gates a merge. Everything here ships dark — the only "turn on" step is B3 per org, and that is Fede's call.

Not breaking production

• Shadow before cutover (B2) — the dispatcher proves itself against the current inline behavior before it replaces it.
• Cutover is per org, Willows first, never all clients at once.
• The guest-card corpus replay (bin/guest-card-corpus, 170 Camellia cards, the no-side-effect regression set) runs on every PR in this chain.
• The shadow diff carries a mutation control: a planted mismatch must turn it red, or the check doesn't count.
• No env flags. The dispatcher keys off resolveProspectRecordOwner(orgId, propertyId) — the same org-default-with-property-override resolver the prospect list and detail loaders already use — and it already exists.
• Rollback is not "put the inline write-back back": the org flips back to shadow mode on the same setting plane, and because the outcome events are durable, the effects that were skipped replay once the fix lands, so nothing is lost. Kill criterion: any duplicate card or lost note at a real client stops the wave.

Decision (Fede, 2026-09-20 night)

Chosen: generic outbox + one dispatcher + per-PMS adapters. In plain terms: the core loop reads the context and replies. When it is done it drops a short "this happened" record on the queue tonight's lead signal already uses. A separate dispatcher picks those up once a minute and hands each one to the right connector (AppFolio today, Yardi later), which writes the note and assigns Clara. A slow or failing PMS never holds the reply. Voice works the same way: the call ends, drops a record, the connector writes the card. Fede on 2026-09-20: "this is fine."

Considered and rejected: a Temporal workflow per outcome (a second orchestration plane for the same guarantee) and keeping the effects inline behind an adapter (a PMS failure could still fail the reply, the exact shape of tonight's incident).

Small calls made under the finish rule, open to override:

• Shadow runs until 50 replied cards have a clean note and assignment, not a fixed number of days.
• The Yardi adapter is built now as a stub behind the interface; it proves the interface is not AppFolio-shaped.
• The review hold stays in the core send step. It decides whether a reply goes out at all, a core decision, not a per-PMS one.
• The property-level record-owner override stays as it is in code today.

Not this program's: the intake rule that a listing-site relay email (Zillow, Apartments.com, Rent. masked addresses) never mints a lead on its own under an AppFolio or Yardi owner, and attaches to the matching guest card instead. That rule lives in the intake adapter owned by session 004's lead-model program. This program starts after a lead exists and does not touch it.

Fit with the lead model (session 004)

• A config lookup for the PMS side effect already exists: resolveProspectRecordOwner(orgId, propertyId) (src/lib/domain/prospects/prospect-record-owner-fetch.ts:51-69) — the same resolver the prospect list and detail loaders use today. Org default with a property-level override that exists in code (pickProspectRecordOwner(propValue, orgValue), field declared on both org settings and property leasing settings, src/lib/data/types.ts:14009 and :15139), with an org-isolation check. The dispatcher never reads org settings directly.
• The adapter contract for it is paper-only today — no code implements it as an interface yet.
• No outcome event exists yet; this plan adds outcome types to the same outbox tonight's lead.received lives on, rather than a second queue.
• Constraints carried forward: AppFolio's note-not-second-card rule (a person already on a card gets a note, never a new card); the property-level record-owner override stays (see Decision).

This also lines up with Gera's org-as-the-wall model: the dispatcher resolves its adapter through the org boundary, with an org-isolation check, the same boundary his model draws everywhere else ; the property-level override on top of it stays for now.

Evidence

Audit: conversations are tied to a home, and should be tied to the person Proposed — pending Gera's decision (asked 2026-09-21; Fede: “this is for Gera”) · 2026-09-21 (owner: the person-first pattern is right; design next, no build yet)

What happened

At Western Slope, a prospect answered one of Clara's emails with "That works, thanks!" to accept a tour time. Our system read that reply, filed it under the company's shared catch-all mailbox record instead of her own thread, found no open conversation waiting there, judged five words too short to make sense of on its own, and skipped it — with no alert to anyone. Her real conversation, with the tour offer sitting right there waiting for a yes, lived under the specific house she had asked about.

Owner's rule (2026-09-21)

The home a person is asking about is a detail on their conversation, there so Clara can answer smartly — it must never be the thing that decides whether their message even joins the conversation.

So at a company with many single homes the conversation starts before any home is chosen. Clara helps the person find the right home, the inquiry and the application attach to that home, and the conversation stays one thread the whole way.

Two ways to route a reply

Example from Western Slope: her thread lived under 486 32 1/8 Road. Her reply arrived at the company's front-door mailbox. Result: no match, message skipped.

Why testing never caught it

At Camellia and the Willows, a property is a whole building with its own mailbox, so routing by "the exact property" and routing by "the person" happen to land in the same place. Western Slope is about 70 separate single houses that all share one company mailbox and one phone line, so every single reply arrives at the front door — the exact case the old pattern gets wrong.

Audit

What the written rules say today

• The planning note for this program quotes both founders asking for one conversation per person, but its own design decision says one conversation per person per property.
• An older architecture decision describes an inquiry as "person + property" — the property sits alongside the person, not underneath them.
• No written rule anywhere says "the home is a detail." The owner's 2026-09-21 rule above replaces both of these.

Proposed direction

1. One conversation per person per company, everywhere.Recommended; owner reacted “this is great” to the pattern on 2026-09-21, written go pending
   The property filter is removed from every lookup; the home travels as a label on each message and inquiry, never as part of the key. Steps: (1) today's stopgap — a reply at a company mailbox is routed by the person's open thread in progress; (2) every channel finds the person first and never discards a thread for being under another home; (3) merge the threads that were split per house and change how conversations are stored. The privacy wall stays the company, which matches Gera's portfolio design where the company is the wall.
2. Keep per-property threads for apartment buildings and use per-person threads only for scattered houses. Not recommended: two patterns to maintain side by side, and a person who moves from one building to another inside the same company still gets split in two.

Next: a design on this page covering how each channel finds the person first, how threads already split per home are merged, and how this fits the portfolio model where the company is the wall. Build waits for the design review.

In flight today

• Stopgap routing fix: a reply at a company mailbox is matched to the person's open thread — building.
• A net that catches a known prospect's reply even when the thread match fails — in review.
• Supervised watch of the Western Slope mailbox until the fix is live.
• The missed tour reply was fed back in with the owner's approval: the tour is on the calendar for Tuesday 4:00 PM and the prospect has her confirmation.

Design: person-first conversations Proposed — pending review · 2026-09-21

Goal

• Every person gets one conversation with a company, not one per home they happen to ask about.
• The home someone is asking about is a label on their conversation and their questions, there to help Clara answer well — it never decides whether a message counts as theirs.
• Every way someone can reach a company — email, text, phone, chat — finds the person first, and the company itself is the one line nothing ever crosses.

Western Slope's first live day surfaced a related set of assumptions worth reading alongside this design: docs.propflowai.co/a/one-code-base — what Western Slope's first live day taught us.

Lookup rule, every channel

The same four steps apply no matter how someone gets in touch. Step 1 always finds the company; step 4 is the only step that ever looks at a specific home, and only to label the answer, not to decide who the message belongs to.

The old catch-all "front door" record that every company-mailbox message used to be filed under stops being a place messages get routed to or looked up from. It becomes nothing more than the default home label a company-level conversation carries before a real home is chosen.

Worked case: a prospect who emailed about a home, then texted the company line

This happened today, in a smaller form: the same person's text landed at the company's shared line, found no thread waiting there, and forked into a second, disconnected thread under the front-door record instead of joining the conversation her email had already started.

Rollout in safe steps

The owner's rule (2026-09-21): the proof that counts runs at the scattered-site test company, because only that shape has a company mailbox, a company line and a front-door record; Willows alone proves nothing about this failure. Second rule (owner, 2026-09-21): single-building customers must not break. Every step ships as a company setting that is off, so those customers keep today's behaviour until the owner turns it on; the harness and the corpus replay include the one-building shape as a control, and a change that alters that path does not merge.

How this is built, day by day

This is built the same way the rest of this program is: a queue of small, one-concern changes, each one roughly the size of a single focused pull request, each one dark on its own (it can merge into production without changing what anyone sees). Two to four builders stay on it at all times; as soon as one change is done, the next one in the queue starts. Work is split into lanes by what each change touches — where messages get routed, the person and inquiry records themselves, and each channel's own sending logic — with a heads-up whenever one lane's work needs to cross into another's. Every change proves itself before it counts as done: a test that includes a planted failure to make sure the check actually catches something, a replay against real past messages, and a live run at the scattered-site test company (the lab should be shaped like it — one company mailbox, one company line, multiple homes — not the Willows' single-home shape), with the Willows as a regression check only. Only turning a step on for a real customer waits for the owner's word. Every merged change gets a row in the build log on this page.

Queue for step 3 (join instead of fork):

1. Build the four-step lookup rule as one shared piece of logic every channel calls, instead of each channel having its own version.
2. Add the company-level setting that turns "join instead of fork" on, off by default.
3. Add the control for that setting on the company's settings page, so the owner can turn it on per company.
4. Point email at the shared lookup rule.
5. Point text messages at the shared lookup rule.
6. Point phone calls at the shared lookup rule.

Constraints and conflicts

• Gera's portfolio design (the company is the wall). This design does not conflict with it. Person lookup happens entirely inside one company's wall — it never crosses from one company's records into another's. The one thing that changes is that the old catch-all "front door" record stops being used to route or look anything up; the attachments Gera's design defines (a line or mailbox belonging to a company or a home) stay exactly as he defines them. One real tension worth naming: a person known to two different companies stays two separate person records, one per company, because that is how the wall already works today — this design does not merge across that wall, on purpose.
• The lead model (the property-management system's record is the record). Untouched by this design. Inquiries, and the copy PropFlow keeps in step with the property-management system, stay exactly as they are. Only how a conversation is looked up changes.
• No manual merge or link screens. Matching people and merging split conversations is the engine's job, done automatically. A wrong merge gets fixed in the engine, using the real case that caused it — never by adding a button for a person to click.

Open questions for the owner

1. When a message could be about either of two open homes, what should Clara do?Recommended
   Answer the one the conversation was actually about, and mention the other in passing, rather than asking the person to clarify every time.
2. Should a tenant record and a prospect record for the same person at one company share the same conversation?Recommended: yes
   One person, one conversation; whether they're currently a prospect or a tenant is just a label on that conversation, not a reason to split it.
3. Should step 5's one-time merge run at every company, or only where conversations actually split by home?Recommended
   Only where it actually happened — and always with the preview report reviewed first, before anything merges.

Build log

Build started 2026-09-20 evening by a fresh session (handoff from the planning session). Tracking issue: #10344. Every pull request in the chain cites it.

Goal for the night of 2026-09-20 (set with Fede before he went to sleep): By 7 AM MT, a real guest card injected in production at the Willows (on-site team) and at the test organization (centralized team) each produces, with no human step: one new-lead event, one delivered first email, one “Clara replied” event, exactly one note and one assignment on the AppFolio card written by the new adapter, and the lead enrolled in the follow-up cadence. Every customer organization stays in shadow with zero writes and a clean shadow diff. Zero open pull requests from this lane. Evidence, before and after, recorded below.

Corpus replay: the guest-card corpus replay becomes a required check from B2 on, when the dispatcher first reads real events; B0 plumbing is proven by the harness and its mutation control instead.

Yardi adapter: not built in B0. Waits on the open question above.