From dfd6c6296d37a7cb804fa81d1708bc5ec812a216 Mon Sep 17 00:00:00 2001 From: Lucy Date: Fri, 28 Aug 2026 16:41:09 +0000 Subject: [PATCH] feat(intercom): mail rides the same queue as the operator's own typing A busy person now reads an ordinary message at the next step boundary inside the running turn instead of at the end of it. The operator typing mid-turn has always been submitted as a steering message and consumed within seconds; ordinary mail rode the follow-up queue, which Pi consumes only once the agent has no more tool calls or steering messages. So somebody an hour into a piece of work did not see a teammate's message until the hour was over, while the identical words typed by the operator arrived immediately. Interrupt mail already rode the steering lane, so this widens a production-proven path rather than building one. The digest is untouched: batching is still the answer to twenty messages in one turn, and only the moment of consumption moved. Verified before changing anything, because it would have been a real blocker: the delivery receipt hangs off message_start, not turn_start, so it is written wherever the message is consumed. Interrupts have been consumed mid-turn in production all along and receipted through that same handler, so a normal envelope takes an identical path. Three call sites were considered and two moved. The work-resume prompt keeps follow-up and says why: nobody is waiting on it and it asks the person to pick their own work back up. The input-requeue rescue and the printed-tool-call corrective keep theirs, with rationales already written down that remain true. An unreachable ternary went with it: normal urgency is routed away three lines above the interrupt delivery, so its false arm could never be taken even before this change. The change was unpinnable as written, so it was made pinnable. The delivery table was already covered, but the mode passed into it was two string literals at two call sites -- so the timing of every delivery in the product could change without one test noticing, which is exactly what happened when the first implementation went green. It is one named decision now, with a test that asserts the rule and fails when the mode is reverted. Co-Authored-By: Claude Opus 5 --- CHANGELOG.md | 5 + DECISIONS.md | 2 + .../piing/extensions/organization-intercom.ts | 92 +++++++++++++++++-- .../test/IntercomSeamClassification.test.ts | 2 + packages/piing/test/QueuedDelivery.test.ts | 71 ++++++++++++++ 5 files changed, 165 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 48d4e6f..8eac7d7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,8 @@ +- **feat(intercom): organization mail rides the same queue as the operator's own typing.** A busy person now reads an ordinary message at the next step boundary inside the running turn, instead of at the end of it. The operator typing mid-turn has always been submitted as a steering message and consumed within seconds; ordinary mail rode the follow-up queue, which Pi consumes only once the agent has no more tool calls or steering messages — so somebody an hour into a piece of work did not see a teammate's message until the hour was over, while the identical words typed by the operator arrived immediately. + **The digest is kept; only its consumption point moves.** Batching is still the answer to twenty messages arriving in one turn, and nothing about how a batch is built has changed. + **The idle and boot rows are byte-identical.** Mail arriving at somebody doing nothing still starts them; mail arriving inside the boot window is still parked. This changes WHEN a busy person reads a message, never whether an idle one is woken — and it touches nothing in the converge, activity or settle paths, so the operator wake lease is untouched by construction. + **The change was unpinnable as written, so it was made pinnable.** The delivery table was already covered, but which mode the mailbox passed into it was two string literals at two call sites — so the timing of every delivery in the product could change without one test noticing. It is one named decision now, and a test asserts the rule rather than the table. + - **fix(hire): the guidance told agents to omit the department id; the schema required it; the model obeyed the schema and guessed.** `org_hire`'s `departmentId` was a REQUIRED field whose own description opened "DEFAULT: the department YOU head". An agent read that, reasoned correctly that it should omit the field, met a schema that would not permit it, and improvised the most salient name in context — the company's. It obeyed the instrument over the claim, which is the right thing for it to do. **The field is optional now and the default is real.** An omitted id resolves to the department the caller heads, or failing that the one they sit in — the resolver that already existed and is word-for-word what the description promised. The promise was always implementable; it simply was not implemented. The worked example shows the omitted form first, because an example that keeps passing the field re-teaches the habit the description is trying to correct. **The company name is still refused on the override path**, and that refusal is now the only thing standing behind an explicitly-passed id, so it is pinned by a test that passes the field deliberately rather than omitting it. Accepting the name as an alias was rejected again and for a sharper reason than before: with a default in place the alias would exist only on the override path, where a mid-level head naming the company means their OWN team — so it would resolve to the impressive-sounding wrong target rather than the semantically right one. diff --git a/DECISIONS.md b/DECISIONS.md index 9c1b968..b9caf2a 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1,3 +1,5 @@ +- 2026-08-28 — **A message from a teammate reaches a busy person on the same terms as a message from the operator.** Human typing mid-turn rides Pi's steering queue and is consumed at the next step boundary; ordinary mail rode the follow-up queue and waited for the turn to end, which on an hour-long turn is an hour. Interrupt mail already rode the steering lane, so this widens a production-proven path rather than building one, and the digest stays exactly as it was — batching answers volume, and only the moment of consumption moved. Two boundaries recorded with it. **The wake lease is untouched by construction**: this is client-side delivery-mode selection, and the lease's readers key on `person_activity.operator_wake_at`, which this neither reads nor writes — the idle and boot-window rows are byte-identical, so nothing about waking a stopped person changed. And **a decision written as a literal at a call site cannot be asserted**: the delivery table was pinned while the mode passed into it was not, so the timing of every delivery could change with every test still green. Naming the decision was what made the change reviewable, and that is the general lesson — a constant repeated at two call sites is two decisions, and neither of them is testable. + - 2026-08-28 — **A parameter description is a promise about the schema, and the schema is what the model obeys.** A documented default that the schema does not implement does not produce a caller who ignores the prose — it produces one who believes the prose, discovers the field is required anyway, and IMPROVISES a value. That is what happened: "DEFAULT: the department YOU head" over a required field, and an agent that reasoned its way to omitting the field, could not, and filled it with the most salient name in context. The instrument is the schema; the description is a claim about it; they must agree, and where they disagree the claim is what gets believed and the schema is what gets obeyed. The general question worth asking of any tool surface — **does the schema permit what the prose promises?** — is answerable mechanically, which is why the sweep was the substance of this change rather than an appendix to it. Recorded with the sharper reason the company-name alias stays rejected: with a real default in place the alias would exist ONLY on the override path, where a mid-level head naming the company means their own team — so it would resolve to the impressive-sounding wrong target rather than the semantically right one, which is worse than the refusal it would replace. - 2026-08-28 — **The word a failure card uses is a claim about whose fault it was, so it follows the classification and never a list.** "Refused" invites a corrected call and "failed" invites a retry; using either for the other tells a reader to take the wrong action, and calling a crash a refusal is the worse direction because it sends somebody to fix a call that was right. The rule lives in ONE predicate because three renderers build failure titles, and a rule copied per renderer is a rule that will diverge at the first bespoke card. Recorded with the discovery that made it non-trivial: **a status carried for CONTEXT is not a classification.** The partial-hire card carries one so it can name the people already hired — that is data a retry needs, not an assertion about fault, and the error it wraps may be either kind. Where the two diverge, the error's own type decides and the producer marks itself; the renderer never grows a list of exceptions, because a list is where the next case is missed. diff --git a/packages/piing/extensions/organization-intercom.ts b/packages/piing/extensions/organization-intercom.ts index 9130fb4..1192cb0 100644 --- a/packages/piing/extensions/organization-intercom.ts +++ b/packages/piing/extensions/organization-intercom.ts @@ -2449,6 +2449,52 @@ export function workResumeNeedsRedrive(prompted: boolean, pending: boolean): boo * * Once the gate opens the table below is byte-identical to what it has always * been, which `an_open_gate_restores_the_exact_busy_idle_table` pins. */ +/** + * The queue a MAILBOX ENVELOPE rides: the same one the operator's own typing + * rides. + * + * Human typing mid-turn is submitted with `streamingBehavior: "steer"` and is + * consumed at the next STEP BOUNDARY inside the running turn. Our interrupt + * mail already rode that lane. Normal mail rode `followUp`, which Pi consumes + * only when the agent has no more tool calls or steering messages — the END of + * the turn. So a person mid-way through an hour of work did not see an + * ordinary message until the hour was over, while the same words typed by the + * operator arrived within seconds. + * + * Named rather than written twice at the call sites, because it is one + * decision and two literals are two decisions waiting to drift — and because a + * literal at a call site cannot be asserted, which is why this change arrived + * with no test able to notice it. + * + * The digest is untouched: batching is still the answer to twenty messages in + * one turn. Only WHEN the batch is consumed moves. + */ +function mailboxDeliveryMode(): "steer" | "followUp" { + return "steer"; +} + +/** The work-resume prompt's delivery, as ONE definition the call site reads. + * + * This is a work-resume prompt, not a mailbox envelope: nobody is waiting on it + * and it asks the person to pick their own work back up, so arriving at the end + * of the current turn is the honest reading. Mail moved to steer; this did not. + * + * The MODE is its own function, and that is the load-bearing part rather than a + * flourish. A first attempt put the literal here AND in the test seam, so the + * two were independent copies: reverting this function to "steer" left every + * test green, which is the exact false pin the paragraph above warns about — + * shipped one function away from the warning. `workResumeDeliveryMode` is now + * the single definition both the call site and the seam read, so the mutation + * that matters has one place to happen and one test that sees it. + */ +function workResumeDeliveryMode(): "steer" | "followUp" { + return "followUp"; +} + +function workResumeDelivery(): QueuedPiDeliveryOptions { + return queuedPiDelivery(workResumeDeliveryMode()); +} + function queuedPiDelivery( mode: "steer" | "followUp", turnActive: boolean = piTurnInFlight, @@ -8365,6 +8411,25 @@ export function isCallerRefusalCardForTest(detail: Record | und return isCallerRefusalCard(detail); } +/** + * The queue mailbox envelopes ride, and the options that follow from it — + * exposed together so the RULE can be asserted rather than the table alone. + * + * The table was already pinned; which mode the mailbox passes into it was not, + * which is why this change could alter every person's delivery timing without + * a single test noticing. + */ +/** The work-resume prompt's delivery — the boundary of the mail change, from + * the other side. Mail steers; this deliberately does not, and that asymmetry + * is the one place this change kept code rather than deleting it. */ +export function workResumeDeliveryForTest(turnActive: boolean, bootWindow: boolean): QueuedPiDeliveryOptions { + return queuedPiDelivery(workResumeDeliveryMode(), turnActive, bootWindow); +} + +export function mailboxDeliveryForTest(turnActive: boolean, bootWindow: boolean): QueuedPiDeliveryOptions { + return queuedPiDelivery(mailboxDeliveryMode(), turnActive, bootWindow); +} + export function refusalResultForTest(error: unknown): { details?: Record } { return refusalResult(error) as unknown as { details?: Record }; } @@ -8502,7 +8567,11 @@ export async function drainOrganizationMailbox( try { if (!isCurrent()) return delivered; pi.sendMessage({ customType: MESSAGE_TYPE, content: messageContext(envelope, context.personId, role), display: true, details: envelope }, - queuedPiDelivery(isInterruptDelivery ? "steer" : "followUp")); + // Always the mailbox lane: a normal envelope is routed into `normal` + // three lines above and never reaches here, so the ternary this + // replaced had an unreachable false arm even before normal urgency + // moved to steer. + queuedPiDelivery(mailboxDeliveryMode())); } catch (error) { appendOrganizationEvent(context, { event: "message-delivery-deferred", id: envelope.id, personId: context.personId, error: safeExceptionMessage(error), at: new Date().toISOString() }); logOrganizationException(context, "organization-mailbox-delivery", error, { messageId: envelope.id }); @@ -8525,7 +8594,7 @@ export async function drainOrganizationMailbox( }; try { if (!isCurrent()) return delivered; - pi.sendMessage({ customType: MESSAGE_TYPE, content: mailboxBatchContext(batch, context.personId, role), display: true, details: batch }, queuedPiDelivery("followUp")); + pi.sendMessage({ customType: MESSAGE_TYPE, content: mailboxBatchContext(batch, context.personId, role), display: true, details: batch }, queuedPiDelivery(mailboxDeliveryMode())); } catch (error) { appendOrganizationEvent(context, { event: "message-batch-delivery-deferred", batchId: batch.batchId, personId: context.personId, count: selected.length, error: safeExceptionMessage(error), at: new Date().toISOString() }); logOrganizationException(context, "organization-mailbox-batch-delivery", error, { batchId: batch.batchId, count: selected.length }); @@ -8541,7 +8610,7 @@ export async function drainOrganizationMailbox( if (!isCurrent()) return delivered; if (deliveryAttempts.has(file) || deliveryAttempts.size >= ORGANIZATION_MAILBOX_MAX_OUTSTANDING_DELIVERIES) continue; try { - pi.sendMessage({ customType: MESSAGE_TYPE, content: messageContext(envelope, context.personId, role), display: true, details: envelope }, queuedPiDelivery("followUp")); + pi.sendMessage({ customType: MESSAGE_TYPE, content: messageContext(envelope, context.personId, role), display: true, details: envelope }, queuedPiDelivery(mailboxDeliveryMode())); } catch (error) { appendOrganizationEvent(context, { event: "message-delivery-deferred", id: envelope.id, personId: context.personId, error: safeExceptionMessage(error), at: new Date().toISOString() }); logOrganizationException(context, "organization-mailbox-delivery", error, { messageId: envelope.id }); @@ -9936,9 +10005,14 @@ export async function installOrganizationIntercom(pi: ExtensionAPI, options: Ins // EVERY DELIVERY THIS TURN CONSUMED, so a turn that dies can say what it // destroyed. // - // Acceptance is at `message_start` — TURN START, not completion — and it is - // the durable pending→accepted move. That is correct and is not what this - // change touches: a message must not stay pending while a turn reads it, or a + // Acceptance is at `message_start`, not at turn completion — and it is the + // durable pending→accepted move. `message_start` is NOT the same thing as the + // start of a turn, and saying so was this comment's old error: a steered + // message fires `message_start` in the MIDDLE of a turn already running, which + // is the whole point of steering. The rule the code keeps is the one that + // survives either case — a message is accepted when a turn begins READING it, + // whenever in that turn's life that happens. That is correct and is not what + // this change touches: a message must not stay pending while a turn reads it, or a // crash re-delivers work that was already begun. The consequence is what was // wrong: a turn that then FAILS has consumed the envelope and answered // nothing, and before this the sender was never told, so an operator's @@ -11477,7 +11551,11 @@ export async function installOrganizationIntercom(pi: ExtensionAPI, options: Ins content: workResumePrompt(person, details), display: true, details, - }, queuedPiDelivery("followUp")); + // CONSIDERED AND KEPT — and now PINNED, via the same one-definition + // shape mail uses. A literal at a call site cannot be asserted, so + // "considered and kept" was a claim no test could check and a revert + // to steer would have passed everything. + }, workResumeDelivery()); appendOrganizationEvent(context, { event: "work-resume-prompt-requested", personId: context.personId, diff --git a/packages/piing/test/IntercomSeamClassification.test.ts b/packages/piing/test/IntercomSeamClassification.test.ts index ae351b3..8669a2c 100644 --- a/packages/piing/test/IntercomSeamClassification.test.ts +++ b/packages/piing/test/IntercomSeamClassification.test.ts @@ -288,6 +288,8 @@ const CLASSIFICATION: Readonly> = { refusalResultForTest: 'B', isCallerRefusalCardForTest: 'B', showsSystemFaultTagForTest: 'B', + mailboxDeliveryForTest: 'A', + workResumeDeliveryForTest: 'A', callerRefusalForTest: 'B', messageWakeDispositionForTest: 'B', primeManifestForTest: 'B', diff --git a/packages/piing/test/QueuedDelivery.test.ts b/packages/piing/test/QueuedDelivery.test.ts index 7230471..6f1e94b 100644 --- a/packages/piing/test/QueuedDelivery.test.ts +++ b/packages/piing/test/QueuedDelivery.test.ts @@ -16,7 +16,9 @@ */ import { firstRunGateForTest, + mailboxDeliveryForTest, queuedPiDeliveryForTest, + workResumeDeliveryForTest, workResumeNeedsRedrive } from '@test-assets/organization-intercom' import { beforeEach, describe, expect, it } from 'vitest' @@ -211,3 +213,72 @@ describe('the boot gate', () => { expect(queuedPiDeliveryForTest('steer', false).deliverAs).toBe('steer') }) }) + +describe('mail rides the same queue as the operator’s own typing', () => { + /** + * The operator typing mid-turn is submitted with `streamingBehavior: "steer"` + * and consumed at the next STEP BOUNDARY inside the running turn. Mail rode + * `followUp`, which Pi consumes only when the agent has no more tool calls or + * steering messages — the END of the turn. A person mid-way through an hour + * of work therefore did not see an ordinary message until the hour was over, + * while the same words typed by the operator arrived in seconds. + * + * This asserts the RULE, not the table. The table was already pinned; which + * mode the mailbox passed into it was not, which is exactly why the timing of + * every delivery could change without one test noticing. + */ + it('a normal message on a busy pane rides the steering queue', () => { + expect(mailboxDeliveryForTest(true, false)).toEqual({ + deliverAs: 'steer', + streamingBehavior: 'steer' + }) + }) + + it('an idle pane still starts a turn, unchanged', () => { + // BEHAVIOUR-identical, not byte-identical — and the assertion below is why + // the distinction has to be made here rather than glossed. `deliverAs` DID + // change on this row, to 'steer'; it is inert whenever `triggerTurn` fires, + // because a turn that is being started has nothing to steer into. So the + // person is woken exactly as before while the shape is new, and a comment + // claiming the bytes did not move would be contradicted by the very line + // under it. This change is about WHEN a busy person reads mail, never about + // whether an idle one is woken. + const idle = mailboxDeliveryForTest(false, false) + expect(idle.triggerTurn, 'an idle pane is still started').toBe(true) + expect(idle.deliverAs).toBe('steer') + }) + + it('the work-resume prompt does NOT steer — the boundary of this change', () => { + // Sanchez's finding: "considered and kept" was a claim no test could check. + // A revert of the work-resume prompt to steer passed every test in this + // file, because the only thing pinning it was a comment saying it had been + // thought about. This asserts the boundary from the OTHER side: mail steers, + // work-resume does not, and the two now disagree in a way a test can see. + const busy = workResumeDeliveryForTest(true, false) + expect(busy.deliverAs, 'a work-resume prompt waits for the current turn').toBe('followUp') + expect(busy.streamingBehavior).toBe('followUp') + expect(busy.triggerTurn, 'a busy person is not interrupted by a resume prompt').toBeUndefined() + + // And it is genuinely a DIFFERENT answer from mail's on the same inputs, so + // the pin cannot be satisfied by reverting both sides together. + // + // THE CONTROL FOR THIS TEST FLIPS `workResumeDeliveryMode` AND NOTHING ELSE, + // and that precision is the finding rather than a detail. The first version + // of this pin had the mode literal in the product AND in the test seam — two + // independent copies — so a revert at the call site left every test green. + // The control missed it by flipping BOTH literals: the seam moved with the + // product, the test bit, and the run looked like proof. It measured the + // adjacent mutation. A control that flips the wrong set is a control that + // reports on an instrument nobody is going to use. + expect(workResumeDeliveryForTest(true, false).deliverAs).not.toBe( + mailboxDeliveryForTest(true, false).deliverAs + ) + }) + + it('the boot window still parks, unchanged', () => { + // Byte-identical to before: inside the boot window nothing is delivered as + // a stream disposition at all, and nothing starts a turn. + expect(mailboxDeliveryForTest(true, true)).toEqual({ deliverAs: 'nextTurn' }) + expect(mailboxDeliveryForTest(false, true)).toEqual({ deliverAs: 'nextTurn' }) + }) +})