@open-everywhere/core 0.1.0

package/dist/agent/channels/delegated-provenance.js

@@ -0,0 +1,418 @@
+// DELEGATED PROVENANCE (OPE-1849) — A WORKER'S CONNECTOR READS, CARRIED ONTO THE DELEGATING REPLY.
+//
+// `channels/reply-provenance.ts` names the connectors a TURN read. Its ledger is a `defineState`
+// slot, and `defineState` is scoped to ONE eve session and stamped with ONE turn. A delegated read
+// satisfies neither half: the read runs inside a WORKER's session and the seat answers from its own
+// turn, so the posting turn reads an EMPTY ledger, writes no `reply.provenance` row and renders no
+// footer. That module's header used to list a DELEGATED read among the boundaries it cannot see past.
+// This module IS the route past it, which is why that list no longer carries it.
+//
+// 🔴 IT IS THE MEMBER'S PROBLEM, NOT A BOOKKEEPING ONE. Every conversational seat is WORKER-ONLY for
+// the connector ops (`access/worker-capability-index.generated.ts` — `connection_search` and
+// `connector` are in both worker-only sets), so a member who asks the DM seat a question that needs
+// a connector gets an answer the seat DELEGATED. Before this module that answer carried no footer at
+// all, which is the class of "no footer" that is a defect rather than a bound.
+//
+// ── THE SHAPE, AND WHY IT MIRRORS THE TAINT PLANE ───────────────────────────────────────────────
+// The same cross-session problem is already solved once in this repository, for the same reason and
+// at the same two edges: `access/subagent-taint.ts` has the CHILD write a durable, call-keyed row and
+// the PARENT read it at settlement. This module is that shape applied to provenance:
+//
+//   • THE WORKER WRITES. {@link noteDelegatedRead} is called from the same two sites that fill the
+//     turn-local ledger — `hooks/connector-audit.ts` for a connector op, `channels/read-reach.ts` for
+//     an authored read tool — and it no-ops outside a subagent child, so a seat's own read never
+//     reaches this store.
+//   • THE SEAT CARRIES AT SETTLEMENT. {@link settleDelegatedReads} runs inside `applyTaskSettlement`
+//     (`hooks/spawn-taint.ts`), the ONE settle path both settlement edges share, and writes each read
+//     into the PARENT turn's ledger through `noteConnectorRead`. From that instant the seat's reply
+//     is indistinguishable from a seat-turn read: the same ledger, the same reach rule, the same
+//     footer render, the same durable row. There is no per-surface arm anywhere on this road.
+//
+// ── IDS AND VERBS, PLUS ONE HOST-AUTHORED LABEL ONE DOOR PROVES ────────────────────────────────
+// A row here carries the CONNECTION and the OP. Two more things are deliberately left behind, and
+// each absence is a decision rather than an omission. The third — the RECORD — crosses through ONE
+// door only, and that door's licence is stated with it:
+//
+//   1. 🔴 THE TAINT MARK NEVER TRAVELS AS PROVENANCE. A worker's taint is adopted by
+//      `adoptTaskTaint` on its own row, under its own fail-CLOSED rules, and it says something about
+//      what the worker READ — not about which system a reply drew on. Folding the two would make a
+//      taint verdict readable as a source list and a source list readable as a verdict. The two
+//      planes settle on the same edge and share nothing.
+//   2. THE REACH PROOF. A worker's own surface key and wake id describe the WORKER's context, and
+//      naming a source is a disclosure that must be proved against the room the SEAT replies into.
+//      So the proof is stamped fresh at the settle, by the seat, with `stampReadReach` — the same
+//      one expression a seat-turn read is stamped with (`channels/read-reach.ts`). One road.
+//      🔴 ON THE WAKE ARM THAT STAMP NEEDS BOTH OF THE CONVERSATION'S IDS (OPE-1869). The settling
+//      turn has just adopted the task's OWN minted wake, so `stampReadReach` reads that id — and the
+//      seat then replies under the stamp the turn was DELIVERED with, which `installTaskWake` records
+//      as `inheritedWakeId`. One conversation, two ids, and a reach rule that matched only the first
+//      of them named nothing: ship #213 carried four reads on six replies and footed zero
+//      (`reply.provenance … reads:4 named:0 withheld:1`). `hooks/spawn-taint.ts` now passes the
+//      inherited stamp as `alsoWakeId` beside the minted one, and it passes it only where the turn
+//      really adopted this task's wake — the same condition that makes the carriage provable at all.
+//   3. THE RECORD, AND THE ANSWER DEPENDS ON THE DOOR. Naming a record needs BOTH halves of the
+//      disclosure rule. The two doors answer the second half — "this room is entitled to the name" —
+//      from different facts, so they cross this boundary differently.
+//      · THE CONNECTOR DOOR CARRIES NO RECORD (OPE-1714). `channels/read-reach.ts` answers that half
+//        from the turn's own ARRIVAL STAMP, and the stamp it reads inside a worker is the WORKER's.
+//        A worker's wake stamps describe no room the seat replies into, so the proof does not cross,
+//        and a carried connector read renders as the connection name alone. That is the
+//        under-reporting direction `reply-provenance.ts` errs in everywhere else.
+//      · THE BORROW DOOR CARRIES ONE, WITH ITS LABEL (OPE-2026). A borrowed read never used the
+//        arrival stamp. Its record is the GRANT ROW, and its label is that row's PINNED TARGET — the
+//        requester's own words, which the owner approved on their card, admitted by
+//        `grantTargetIsPinned`. `access/credential-grant-scope.ts` then spends the row only in the
+//        session it was minted for, or in the domain its owner tapped, so every room this label can
+//        reach is a room whose WORKERS may spend this grant — a lent tool mounts on the workers and
+//        never on the seat (`tools/grant_tools.ts`, OPE-2023), which is the very asymmetry this
+//        carriage exists to cross. The room question is answered for THIS door, on the grant rather
+//        than on any wake, which is why the ground above does not reach it.
+//      🔴 THE LABEL IS THE ONLY DISPLAY TEXT THIS ROW HOLDS, AND IT IS NOT OP OUTPUT. The ledger
+//      keeps titles out of durable storage because a title is the op's OUTPUT, and a stored one
+//      outlives the turn that read it. A pinned target label is neither: it is model-authored at ASK
+//      time and never an op response, the owner approved that exact wording, and this row expires in
+//      six hours. It is capped at
+//      {@link MAX_DELEGATED_RECORD_NAME_CHARS} all the same, so one grant cannot grow the row
+//      without bound. The durable `reply.provenance` audit row is UNCHANGED and still carries no
+//      record at all — the label reaches the reader through the footer alone.
+//
+// ── THE BOUNDS, STATED ──────────────────────────────────────────────────────────────────────────
+// Three under-report, and one — the last — can OVER-report. It is stated rather than papered over,
+// on the same terms `reply-provenance.ts` states its own coalesced-turn residual.
+//
+// 1. THE JOIN IS THE TAINT PLANE'S. The carriage joins WORKER to SEAT through the dispatch row
+//    `access/subagent-taint.ts` writes (`taskCallLink`), and that row is written only when the taint
+//    plane is on. On a `taint.mode: "off"` deployment there is no join, so a delegated read is not
+//    carried and the reply renders as it did before this module. A missing footer after a delegation
+//    is a defect wherever the taint plane is ON, and a bound where it is off.
+// 2. THE CARRIAGE LANDS ON THE SETTLING TURN, AND THE LEDGER IS STILL TURN-KEYED. A seat that waits
+//    and answers on a LATER turn reads an empty ledger again. That is not the ordinary shape — the
+//    settlement installs the task's own wake and arms the follow-through duty precisely so the seat
+//    answers on the turn it was woken by (`channels/task-wake.ts`,
+//    `access/pending-delegation-signal.ts`) — but it is a real bound.
+// 3. A DELEGATION THE SEAT CANNOT PROVE A ROOM FOR IS SPENT, NOT CARRIED. `hooks/spawn-taint.ts`
+//    withholds a settlement whose wake proof names ANOTHER conversation, and one that did not
+//    complete. Those reads reach no reply at all, which is the fail-closed floor.
+// 4. 🔴 TWO BRIEFS TO ONE PERSISTENT WORKER SHARE ONE ROW, AND THAT WINDOW CAN OVER-REPORT. The key
+//    is the child's continuation token, and `rememberTaskAgent` pins the FIRST dispatch's call for a
+//    persistent `agentId`, so every continuation brief to that worker writes into one row. The spend
+//    below closes the ordinary sequence — brief one settles, the row empties, brief two starts clean
+//    — but not two edges of it: a read that lands AFTER the settlement read the row survives to the
+//    next brief's answer, and a second brief that starts reading before the first settles has its
+//    reads carried by the first. A ONE-SHOT delegation is unaffected: it mints a new call, so it
+//    mints a new row. Closing it needs a per-brief key, which eve gives the worker no way to derive
+//    (the task id is `sha256(parentSessionId, parentTurnId, callId)`, and a worker holds no parent
+//    turn id). What bounds it today is that the disclosure is a CONNECTION NAME — or, for a borrowed
+//    read, that name and the grant's PINNED TARGET — inside ONE seat's own conversation, between two
+//    briefs that seat itself commissioned. The grant bounds its own label further: the row is
+//    spendable only in the conversation or the domain its owner approved, so the label reaches no
+//    room the owner does not already lend the credential to.
+// Every bound is countable: the settle records what it found and what it carried.
+//
+// FAIL-SOFT, ALWAYS, on both edges. A store that is down costs a footer and never a read, a
+// settlement or a reply.
+import { getOperationalStore } from "../operational/provider.js";
+import { deploymentOrg, isSubagentChildContext } from "../identity/binding.js";
+import { noteConnectorRead, rememberRecordName } from "./reply-provenance.js";
+import { resolveUnifiedWakeTarget, sameUnifiedConversation } from "./unified-window.js";
+/** Key prefix. Its OWN namespace, so a provenance row can never be confused with the taint plane's
+ *  `oe-subagent-taint:` / `oe-task-call:` rows or the wake plane's `oe-task-wake:` rows in the same
+ *  task-result slice. */
+const DELEGATED_PROVENANCE_PREFIX = "oe-delegated-provenance:";
+/** The same six hours every other per-delegation row keeps. The bound is the CHILD's lifetime, not
+ *  the seat's turn: a background settlement reads this row a whole turn — or several — later. */
+const DELEGATED_PROVENANCE_TTL_MS = 6 * 60 * 60 * 1000;
+/** How many distinct reads ONE delegation carries. The same cap the turn-local ledger keeps
+ *  (`MAX_READS`), for the same reason: past it the row stops growing, so the footer UNDERSTATES
+ *  rather than letting a looping worker grow a stored container without bound. */
+const MAX_DELEGATED_READS = 32;
+/** How long one carried record's display label may be. The same 120 the turn-local name map caps at
+ *  (`reply-provenance.ts` MAX_RECORD_NAME_CHARS), so a label that survives this row is a label the
+ *  render can still show whole. The cut is by CODE POINT, never by UTF-16 unit, so it can never
+ *  leave a lone surrogate in a stored string. */
+const MAX_DELEGATED_RECORD_NAME_CHARS = 120;
+/**
+ * The delegating parent of THIS context, from eve's continuation token first and its typed session
+ * linkage second.
+ *
+ * 🔴 CONSERVATIVE ON BOTH ARMS, AND THE TOKEN PARSE IS COLON-FREE BY CONSTRUCTION. eve mints the
+ * token as `subagent:<parentSessionId>:<callId>`, and a greedy parse of an id that itself contains a
+ * colon yields a pair naming no session — which would key a store row nothing ever reads, or worse,
+ * one another delegation reads. Anything ambiguous is declined, and a declined link means no
+ * carriage: the fail-soft direction on both edges.
+ *
+ * `hooks/spawn-taint.ts` reads the SAME answer for the taint plane's own call-keyed marker, so the
+ * two planes cannot disagree about which delegation a worker belongs to.
+ */
+export function delegatingParentLink(ctx) {
+    try {
+        const token = ctx.channel?.continuationToken;
+        if (typeof token === "string") {
+            const m = /^subagent:([^:]+):([^:]+)$/.exec(token);
+            if (m !== null)
+                return { sessionId: m[1], callId: m[2] };
+        }
+        const parent = ctx.session?.parent;
+        const sessionId = parent?.sessionId;
+        const callId = parent?.callId;
+        if (typeof sessionId === "string" && sessionId.length > 0 && typeof callId === "string" && callId.length > 0) {
+            return { sessionId, callId };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** eve's own spelling of the child's continuation token, which is what BOTH ends key on: the worker
+ *  derives it from its own context, and the seat reads it straight off the dispatch join row
+ *  (`TaskCallLink.childToken`). Deriving it twice from the same two ids is what lets a settlement
+ *  find the row a worker wrote without either end guessing. */
+function childContinuationToken(link) {
+    return `subagent:${link.sessionId}:${link.callId}`;
+}
+/** The store key for one delegation's read list. */
+export function delegatedProvenanceKey(childToken) {
+    return `${DELEGATED_PROVENANCE_PREFIX}${childToken}`;
+}
+/** Bound one carried label, by CODE POINT. It bounds the STORED ROW and nothing else: the render's
+ *  own guard — `rememberRecordName`'s flatten, which collapses whitespace and refuses a label
+ *  spelling the footer marker — still runs at the settle, so this function is a size bound and never
+ *  a content one. */
+function capRecordName(name) {
+    const chars = Array.from(name);
+    return chars.length <= MAX_DELEGATED_RECORD_NAME_CHARS ? name : chars.slice(0, MAX_DELEGATED_RECORD_NAME_CHARS).join("");
+}
+/** Read one row defensively — a row written by an earlier deployment can hold anything, and anything
+ *  unrecognised reads as "nothing was read", which renders no footer. */
+function parseDelegatedReads(raw) {
+    if (raw === null)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        const reads = parsed?.reads;
+        if (!Array.isArray(reads))
+            return [];
+        return reads.flatMap((r) => {
+            const row = r;
+            if (typeof row?.connection !== "string" || row.connection.length === 0)
+                return [];
+            if (typeof row.op !== "string" || row.op.length === 0)
+                return [];
+            // The record is read back with the SAME all-or-nothing rule it is written under: a row whose
+            // record is half-shaped carries no record at all, so a name can never be attributed to a
+            // record the row does not identify. An earlier deployment wrote no record and reads clean.
+            const rec = row.record;
+            const record = typeof rec?.kind === "string" &&
+                rec.kind.length > 0 &&
+                typeof rec.id === "string" &&
+                rec.id.length > 0 &&
+                typeof rec.name === "string" &&
+                rec.name.length > 0
+                ? { kind: rec.kind, id: rec.id, name: capRecordName(rec.name) }
+                : undefined;
+            return [{ connection: row.connection, op: row.op, ...(record === undefined ? {} : { record }) }];
+        });
+    }
+    catch {
+        return [];
+    }
+}
+async function readDelegatedReads(org, childToken) {
+    try {
+        if (childToken.length === 0)
+            return [];
+        return parseDelegatedReads(await getOperationalStore().getTaskResult(org, delegatedProvenanceKey(childToken)));
+    }
+    catch {
+        return [];
+    }
+}
+async function writeDelegatedReads(org, childToken, reads) {
+    await getOperationalStore().putTaskResult(org, delegatedProvenanceKey(childToken), JSON.stringify({ reads: [...reads] }), new Date().toISOString(), DELEGATED_PROVENANCE_TTL_MS);
+}
+/** Every write to one delegation's row is chained here, for the same reason
+ *  `hooks/spawn-taint.ts` chains its call-keyed marker: the append is a READ-MODIFY-WRITE, and two
+ *  reads landing on one tick would otherwise each write the row they read and lose one entry. One
+ *  worker session runs in one process, so one queue serialises every writer of that session's
+ *  rows. */
+let appendQueue = Promise.resolve();
+/** Append one read to a delegation's row, deduplicated on the WHOLE entry so a worker that pages a
+ *  list twenty times contributes one source. Past {@link MAX_DELEGATED_READS} the row stops growing.
+ *
+ *  🔴 THE RECORD IS PART OF THE IDENTITY, the same rule `noteConnectorRead` keeps for the ledger. A
+ *  borrowed read's op is the HOST-AUTHORED constant `credential_grant_borrow`, so two grants read in
+ *  one brief agree on connection AND op and differ only here. WHAT THE KEY BUYS: a LABELLED read no
+ *  longer folds into an unlabelled one on the same connection, so a pinned target survives a brief
+ *  that also made a label-less borrowed call; and the durable `reply.provenance` counts two grants as
+ *  two sources rather than one.
+ *  🔴 WHAT IT DOES NOT CLOSE, so nobody reads more into it. `provenanceForReply` names ONE record per
+ *  connection — the FIRST visible read's — so a second grant on one connection is carried and
+ *  counted, never named. Widening that is the ledger's ruling to revisit, not this key's.
+ *  The label is left out of the key on purpose: one grant row has one id, so two entries that agree
+ *  on kind and id are one record whatever the label spells. */
+async function appendDelegatedRead(org, childToken, read) {
+    const cur = await readDelegatedReads(org, childToken);
+    if (cur.length >= MAX_DELEGATED_READS)
+        return;
+    if (cur.some((r) => r.connection === read.connection && r.op === read.op && r.record?.kind === read.record?.kind && r.record?.id === read.record?.id))
+        return;
+    await writeDelegatedReads(org, childToken, [...cur, read]);
+}
+/**
+ * Record that a WORKER read something through a connector, for the delegating seat's reply footer.
+ *
+ * Called beside every `noteConnectorRead` — `hooks/connector-audit.ts` for a connector op and
+ * `channels/read-reach.ts` for an authored read tool — so a read reaches the seat by whichever door
+ * it was made through. A NO-OP outside a subagent child, which is what keeps a seat's own read off
+ * this store entirely: the turn-local ledger already holds it, and a seat has no parent to carry it
+ * to.
+ *
+ * 🔴 `record` IS THE BORROW DOOR'S ALONE (OPE-2026). The caller passes one only where it has proved
+ * the delegating room may be told the name — which today is the borrow door, off the grant row's own
+ * pinned target. Every other caller omits it, and the carried read then renders as the connection
+ * name alone. A half-shaped record (an empty kind, id or label) is dropped rather than stored, so
+ * the row can never name a record it cannot identify.
+ *
+ * Fire-and-forget and never throws: a read that cannot be recorded is still a read that happened.
+ */
+export function noteDelegatedRead(bind, connection, op, record) {
+    try {
+        if (connection.length === 0 || op.length === 0)
+            return;
+        if (!isSubagentChildContext(bind))
+            return;
+        const link = delegatingParentLink(bind);
+        if (link === null)
+            return;
+        const org = deploymentOrg();
+        const childToken = childContinuationToken(link);
+        const carried = record !== undefined && record.kind.length > 0 && record.id.length > 0 && record.name.length > 0
+            ? { kind: record.kind, id: record.id, name: capRecordName(record.name) }
+            : undefined;
+        const read = { connection, op, ...(carried === undefined ? {} : { record: carried }) };
+        appendQueue = appendQueue.then(() => appendDelegatedRead(org, childToken, read)).catch(() => undefined);
+    }
+    catch {
+        /* no deployment identity, no readable context — never a reason to disturb the read */
+    }
+}
+/**
+ * SETTLE EDGE — SPEND one delegation's recorded reads, attributing them to the PARENT TURN's
+ * provenance ledger when the seat can prove a room for them.
+ *
+ * Called from `applyTaskSettlement`, which is the one path both settlement edges — the task VIEW and
+ * the task NOTIFICATION — already share, so neither can settle without spending. Where the reads are
+ * attributed they become ordinary ledger entries: the seat's reply applies the reach rule to them,
+ * renders the footer and writes `reply.provenance` exactly as it does for a read the seat made
+ * itself.
+ *
+ * 🔴 `reach: undefined` SPENDS WITHOUT ATTRIBUTING, and that is a first-class outcome rather than an
+ * error path. The caller withholds a settlement it cannot place in a room — a wake proof naming
+ * ANOTHER conversation, a delegation that did not complete — and those reads must then reach NO
+ * reply: leaving them in the row would simply move the wrong attribution onto the next brief.
+ *
+ * 🔴 THE ROW IS ALWAYS SPENT, AND THE ORDER IS LOAD-BEARING. A persistent worker takes a SECOND
+ * brief on the SAME continuation token (`rememberTaskAgent` pins the first dispatch's call), so a row
+ * left in place would foot brief one's sources onto brief two's answer. Attributing BEFORE clearing
+ * means a store failure on the clear costs a repeat, which `noteConnectorRead`'s whole-entry dedupe
+ * absorbs inside one turn; clearing first would cost the attribution itself. The spend does not close
+ * the shared-token residual — see bound 4 in this file's header for the two edges it leaves open.
+ *
+ * 🔴 A SECOND DELEGATION ATTRIBUTED IN THE SAME TURN APPENDS. The ledger keys on the TURN and appends
+ * within it, and each delegation owns its own store row, so two workers' reads both reach one reply
+ * and neither overwrites the other.
+ *
+ * Never throws: a lost row, an unreadable store and an unusable token all answer `{found: 0,
+ * carried: 0}`, which renders the reply exactly as it rendered before this module.
+ */
+/**
+ * THE SECOND ADDRESS OF ONE CONVERSATION (OPE-1869) — is `inherited` the same conversation as the
+ * task's own minted `taskWake`, proved against the wake map rather than assumed?
+ *
+ * 🔴 WHY THE PROOF IS REQUIRED AND AN `installed` OUTCOME IS NOT ENOUGH. `installTaskWake` adopts
+ * only on an UNINGRESSED turn, and OPE-585 named exactly what such a turn's inherited stamp is: eve
+ * wakes the delegating parent with NO auth, so the turn keeps the PREVIOUS delivery's `oe_wake_id` —
+ * "whichever conversation happened to run last". On a unified seat that is routinely a SIBLING
+ * conversation. Naming this task's reads under it would tell conversation A what conversation B
+ * consulted, which is the OPE-1713 disclosure `settleDelegatedReads`'s wake arm exists to close. So
+ * the two ids are compared by ORIGIN: `openTaskWake` copies the task wake's origin from the
+ * dispatching turn's own wake, so two rows that agree under {@link sameUnifiedConversation} are one
+ * room and the disclosure is to the room that asked.
+ *
+ * FAIL-CLOSED AND NEVER THROWS. A missing row, an unreadable store, an unregistered origin: every one
+ * answers `false`, which withholds the second address and leaves the read named under the task wake
+ * alone — today's behaviour, which under-reports rather than over-discloses.
+ */
+async function sameConversationAsTaskWake(org, taskWake, inherited) {
+    if (taskWake === inherited)
+        return false; // Nothing to widen: one id is already the whole address.
+    try {
+        const store = getOperationalStore();
+        // `resolveUnifiedWakeTarget` is the road `openTaskWake` itself reads origins through — it
+        // re-validates the stored JSON rather than trusting it, and answers `null` on every unreadable
+        // shape, so a corrupt row withholds instead of comparing two half-parsed objects.
+        const [a, b] = await Promise.all([resolveUnifiedWakeTarget(store, org, taskWake), resolveUnifiedWakeTarget(store, org, inherited)]);
+        if (a === null || b === null)
+            return false;
+        return sameUnifiedConversation(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The inherited stamp, admitted as a read's SECOND address or withheld (OPE-1869). Exported so the
+ * settlement edge states the rule in one call AND so the suite can drive the rule directly —
+ * `delegated-provenance-test.ts` §10 asserts each of the four refusal arms below against it, because
+ * one settlement drive can only ever exercise one of them.
+ *
+ * `undefined` in, `undefined` out — a settlement with no inherited stamp, or one the wake map cannot
+ * place in the task's own conversation, carries the task wake alone.
+ */
+export async function delegatedSecondAddress(input) {
+    const { taskWakeId, inheritedWakeId } = input;
+    if (input.outcome !== "installed")
+        return undefined;
+    if (taskWakeId === null || taskWakeId.length === 0)
+        return undefined;
+    if (inheritedWakeId === undefined || inheritedWakeId.length === 0)
+        return undefined;
+    return (await sameConversationAsTaskWake(input.org, taskWakeId, inheritedWakeId)) ? inheritedWakeId : undefined;
+}
+export async function settleDelegatedReads(input) {
+    const none = { found: 0, carried: 0 };
+    try {
+        if (input.childToken.length === 0)
+            return none;
+        const reads = await readDelegatedReads(input.org, input.childToken);
+        if (reads.length === 0)
+            return none;
+        const reach = input.reach;
+        if (reach !== undefined) {
+            for (const read of reads) {
+                noteConnectorRead(input.turnId, {
+                    ...reach,
+                    connection: read.connection,
+                    op: read.op,
+                    ...(read.record === undefined ? {} : { record: { kind: read.record.kind, id: read.record.id } }),
+                });
+                // AND THE LABEL, UNDER THE SEAT'S OWN SESSION AND TURN (OPE-2026). The worker stored its copy
+                // under the WORKER's session and turn, which this process may not even hold any more, so the
+                // carriage re-states it here — the one place that knows both the label and the room the
+                // reply will go out in. It runs ONLY on the attributing arm: a withheld settlement must
+                // reach no reply, and a name left behind for a read that was never attributed would sit in
+                // the map until it aged out.
+                if (read.record !== undefined) {
+                    rememberRecordName(input.sessionId, input.turnId, read.record.kind, read.record.id, read.record.name);
+                }
+            }
+        }
+        await writeDelegatedReads(input.org, input.childToken, []).catch(() => undefined);
+        return { found: reads.length, carried: reach === undefined ? 0 : reads.length };
+    }
+    catch {
+        return none;
+    }
+}
+//# sourceMappingURL=delegated-provenance.js.map

package/dist/agent/channels/delegated-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegated-provenance.js","sourceRoot":"","sources":["../../../agent/channels/delegated-provenance.ts"],"names":[],"mappings":"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"}

package/dist/agent/channels/dm-audience.d.ts

@@ -0,0 +1,157 @@
+import { type DirectMessageAction, type DirectMessageDelivery } from "./post-arms.js";
+import type { DmAudienceRow } from "../operational/store.js";
+import { type ProactiveDmPlane } from "./proactive-dm-manifest.js";
+/** The resource type a PERSON is addressed as — the `<type>` rung of `slack:person/U0123ABC`. One
+ *  word for one thing: it is also the word the closed table in access/resource-grant.ts implements. */
+export declare const PERSON_RESOURCE_TYPE = "person";
+/**
+ * The canonical person address for a (platform, member id) pair — the ONE spelling the grant, the card, the audit row and the `dm_audience` key all quote, byte for byte.
+ * The id is carried in its SURFACE-KEY spelling: a no-op for a platform whose member ids are already safe, and load-bearing for one whose ids are not. Without it an operator's grant address and the RECIPIENT's own stop would key on two different strings, and a stop that keys on a string no grant can name is a stop that does not work.
+ */
+export declare function personAddress(platform: string, principalId: string): string;
+/** The audit action a recipient's STOP writes. One greppable string, shared with its test — and
+ *  named for what happened rather than for the verb, so it survives a rename. */
+export declare const DM_STOP_ACTION = "dm.audience.stopped";
+/** The audit action a recipient's RESUME writes. */
+export declare const DM_RESUME_ACTION = "dm.audience.resumed";
+/** What {@link readDmAudience} answers. Deliberately NOT the raw row: the questions a caller actually
+ *  asks are booleans, and a caller that reads timestamps has to re-derive them. */
+export interface DmAudienceState {
+    /** The recipient has stopped proactive DMs. A live grant does not override this. */
+    readonly stopped: boolean;
+    /** A proactive DM has already landed under this grant, so a later one FLOWS rather than cards. */
+    readonly delivered: boolean;
+    /**
+     * The store answered. FALSE means it did not, and `stopped` is then a fail-closed GUESS rather than a fact about this person.
+     * A CALLER MUST NOT REPORT AN UNREADABLE STORE AS A PERSON'S DECISION. Suppressing is right; telling the model "they asked you to stop" when nobody asked is a fabrication.
+     */
+    readonly readable: boolean;
+    /** The raw row, for a caller that renders the trail (an operator read, an audit detail). */
+    readonly row: DmAudienceRow | null;
+}
+/**
+ * This person's DM-audience state. A STORE FAILURE READS AS STOPPED — the fail-closed direction, and the opposite of most fail-softs in this tree, on purpose: of the two ways to be wrong here, only "we sent a message to somebody who told us not to" is unrecoverable.
+ * It also reads as NOT delivered, so the first message after the store recovers takes the card again, which is the same direction. It sets `readable: false` in that branch, and the distinction is not cosmetic — see the field's own doc.
+ */
+export declare function readDmAudience(org: string, address: string): Promise<DmAudienceState>;
+/**
+ * Record that a proactive DM landed. Best-effort: the message is already delivered, so a failed bookkeeping write must not turn a successful send into an error the model reports as a failure.
+ * The COST of that failure is bounded and in the safe direction — the next delivery takes the card again — and it never re-opens a stop, because the store's upsert does not touch the stopped field at all.
+ */
+export declare function noteDmAudienceDelivery(org: string, address: string, at: string): Promise<void>;
+/** What a stop/resume call did. `changed` is false when the state was already what was asked for —
+ *  which the caller must report honestly rather than claiming an act that did not happen. */
+export interface DmAudienceChange {
+    readonly changed: boolean;
+}
+/**
+ * The recipient STOPS proactive DMs.
+ * THIS THROWS ON A STORE FAILURE, and it is the one place in this module that does: a stop the person believes landed and did not would have the seat say "I have stopped" while the next delivery arrives anyway. A failed stop must read as a failed stop.
+ */
+export declare function stopDmAudience(input: {
+    readonly org: string;
+    readonly address: string;
+    readonly at: string;
+    /** The person's own platform/workspace, for the audit row's subject columns. */
+    readonly platform: string;
+    readonly workspace: string;
+    readonly principalId: string;
+}): Promise<DmAudienceChange>;
+/**
+ * The recipient RESUMES proactive DMs — the other half of a first-class stop.
+ * ONLY THE RECIPIENT LIFTS THEIR OWN STOP, and no config act does: removing the grant and adding it back writes the same address, so the row is still found and the person is still stopped. It throws on a store failure for {@link stopDmAudience}'s reason in the other direction.
+ */
+export declare function resumeDmAudience(input: {
+    readonly org: string;
+    readonly address: string;
+    readonly platform: string;
+    readonly workspace: string;
+    readonly principalId: string;
+}): Promise<DmAudienceChange>;
+/** Where an audit row's subject columns come from. The two delivery paths resolve them differently —
+ *  one from a frozen scope key, one from a live partition — so the caller supplies them and
+ *  {@link deliverProactiveDm} never has to know which path it is on. */
+export interface DmDeliveryWhere {
+    readonly org: string;
+    readonly platform: string;
+    readonly workspace: string;
+    /** Optional, because `whereFromScope` cannot always name a surface from a frozen scope key. An
+     *  absent surface is left OFF the row rather than filled with a placeholder — a fabricated value
+     *  in a queryable audit column is worse than a missing one. */
+    readonly surface?: string;
+}
+/** The audit action every refused proactive DM writes — one greppable string for every plane and every boundary, so a reviewer counts refusals once rather than per call site. */
+export declare const DM_REFUSED_ACTION = "dm.refused";
+/**
+ * Thrown by {@link assertProactiveDmAllowed}, and therefore by {@link deliverProactiveDm}: this person may not be sent an agent-started direct message right now.
+ * `unreadable` is NEVER folded into `stopped`. Reporting an outage as a person's decision states a fact about them that nobody established — the same split {@link DmAudienceState.readable} draws, for the same reason.
+ */
+export declare class ProactiveDmRefusedError extends Error {
+    readonly plane: ProactiveDmPlane;
+    readonly platform: string;
+    /** The RECIPIENT's bare platform member id. */
+    readonly recipientId: string;
+    /** The address the stop is keyed on — what the audit row names. */
+    readonly address: string;
+    readonly boundary: "stopped" | "unreadable";
+    constructor(plane: ProactiveDmPlane, platform: string, 
+    /** The RECIPIENT's bare platform member id. */
+    recipientId: string, 
+    /** The address the stop is keyed on — what the audit row names. */
+    address: string, boundary: "stopped" | "unreadable", message: string);
+}
+/** What a caller is told when the RECIPIENT refused. ONE sentence, spelled once and shared by the road and by `access/chat-dm-grant.ts`'s propose-time fence: two planes that describe one boundary in two ways is how a person's stop starts meaning two different things. */
+export declare function dmStoppedRefusalMessage(platform: string, recipientId: string): string;
+/** What a caller is told when the stop could NOT BE READ. Never folded into {@link dmStoppedRefusalMessage}: reporting an outage as a person's decision states a fact about them that nobody established. */
+export declare function dmUnreadableRefusalMessage(platform: string, recipientId: string): string;
+/**
+ * THE GATE ON THE ROAD: may this deployment start a direct message with this person, on this plane, right now? It reads the recipient's own stop and REFUSES ahead of the send, and it writes the refusal row itself, so every plane files one shape under one action name.
+ * It is exported for the one caller that must ask BEFORE it spends something it cannot give back — `deliverGrantOwnerNotice` claims a once-per-grant notice, and a claim burnt on a delivery that was never allowed is a notice the owner can never receive. {@link deliverProactiveDm} calls it again at the send, which is the control; an early call is an optimisation, never a substitute.
+ */
+export declare function assertProactiveDmAllowed(input: {
+    readonly where: DmDeliveryWhere;
+    readonly plane: ProactiveDmPlane;
+    readonly platform: string;
+    readonly recipientId: string;
+    readonly address: string;
+    /** Who the refused message would have been sent FOR. Carried onto the row when the caller can name
+     *  one, left off when it cannot — the same positive-only rule `access/chat-dm-grant.ts` follows. */
+    readonly attributedTo?: string;
+}): Promise<void>;
+/**
+ * SEND one proactive DM, record it, and audit it — the ONE path EVERY plane takes. It exists because the planes must not DRIFT: the carded first delivery, the flowing later ones and the credential-grant cards are different code paths by necessity, but they must obey the SAME stop, append the SAME footer, write the SAME delivery record and file the SAME audit shape.
+ * 🔴 THE STOP IS READ HERE, CLOSEST TO THE SEND, AND IT OUTRANKS THE PLANE (OPE-1855). A caller's own earlier fence is not enough: a person can stop between a card being proposed and a human approving it, and a plane that reads no stop at all is the defect this road closes. A refusal THROWS {@link ProactiveDmRefusedError}; a caller that owes its own answer catches it.
+ * ORDER IS LOAD-BEARING, and each step fails in its own direction. The GATE runs before anything is sent. The SEND throws when it did not land, because the DM IS the work. The RECORD comes after it, since writing it first would flow the NEXT message even if this one never landed, and a lost write only cards once more. The AUDIT is best-effort, because losing the row must not report a delivered message as a failure.
+ */
+export declare function deliverProactiveDm(input: {
+    readonly where: DmDeliveryWhere;
+    /** WHICH PLANE asks. Declared in `proactive-dm-manifest.ts`, and named on every audit row. */
+    readonly plane: ProactiveDmPlane;
+    readonly platform: string;
+    /** The RECIPIENT's bare platform member id. */
+    readonly recipientId: string;
+    /** The grant's ARN-like address — the row's "which config line allowed this", and the record key. */
+    readonly address: string;
+    /** The model's message. */
+    readonly text: string;
+    /** The host-authored footer, appended to what the recipient sees. */
+    readonly footer: string;
+    /** Who asked for the message. */
+    readonly requestedBy: string;
+    /** Who the row is attributed to — the APPROVER on the carded path, the ASKER on the flowing one. */
+    readonly attributedTo: string;
+    /** TRUE on the carded first delivery. The fact a reviewer reads to tell the `chat.dm` plane's two paths apart, and meaningless on a plane with no such split — those omit it and the row reads false. */
+    readonly first?: boolean;
+    /** Tappable shortcuts. An arm with no component plane ignores them, so the text still stands alone. */
+    readonly actions?: readonly DirectMessageAction[];
+    readonly tainted?: boolean;
+}): Promise<DirectMessageDelivery>;
+/**
+ * The HOST-AUTHORED footer every proactive DM carries. The model authors none of it, the same rule as every other host signal, and it is appended by the delivery path rather than by the card.
+ * It says three things, each load-bearing for a person who did not ask for this message: WHO asked, WHERE the ask came from, and HOW to stop it. A stop the recipient cannot find is not a first-class stop, and this line is where they find it.
+ */
+export declare function dmDeliveryFooter(input: {
+    readonly requestedBy: string;
+    readonly fromContainer: string;
+}): string;
+//# sourceMappingURL=dm-audience.d.ts.map

package/dist/agent/channels/dm-audience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dm-audience.d.ts","sourceRoot":"","sources":["../../../agent/channels/dm-audience.ts"],"names":[],"mappings":"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"}