@nelsonlongxiang/dsh-open-a2a-net 0.6.30 → 0.6.32

package/lib/faces/admin.js

@@ -30,7 +30,7 @@ import { MAX_LAYOUT_BODY_BYTES } from "../transport-caps.js";
  * @param d - the captures listed on {@link AdminFaceDeps}.
  */
 export function registerAdminFaces(webServer, d) {
-    const { ctx, config, logger, home, session, lanIp, PLUGIN_VERSION, indexUrl, controlRoute, controlTrustedWithoutKey, readJsonBody, peerStore, peerLinkState, originClaimHeaders, refreshRemoteRows, joinedSessions, exposureStore, teamMemberships, cliDeposits, groupStore, canvasStore, layoutStore, taskLedger, idempotencyStore, inFlightRoutes, recentActivity, teamAuditRing, reportRing, sessionNodes, liveRoots, mountSessionNode, coldJoinedIds, prewarmStatus, reconcileStatus, id8, sessionLabelOf, sessionTeamOf, nodeMetadataOf, canvasTeamOf, archivedSessionFilter, pruneArchivedJoins, pruneCanvasMemberships, } = d;
+    const { ctx, config, logger, home, session, lanIp, PLUGIN_VERSION, indexUrl, controlRoute, controlTrustedWithoutKey, readJsonBody, peerStore, peerLinkState, originClaimHeaders, refreshRemoteRows, joinedSessions, exposureStore, teamMemberships, cliDeposits, groupStore, canvasStore, layoutStore, taskLedger, authorizationView, idempotencyStore, inFlightRoutes, recentActivity, teamAuditRing, reportRing, sessionNodes, liveRoots, mountSessionNode, coldJoinedIds, prewarmStatus, reconcileStatus, id8, sessionLabelOf, sessionTeamOf, ownCanvasHandleOf, localSessionOfHandle, canvasTeamsOfSession, nodeMetadataOf, canvasTeamOf, archivedSessionFilter, pruneArchivedJoins, pruneCanvasMemberships, } = d;
     ctx.effect(() => webServer.register({
         kind: 'exact',
         path: '/__dsh_a2a/state',
@@ -56,20 +56,25 @@ export function registerAdminFaces(webServer, d) {
                 const tFacts0 = Date.now();
                 const sessions = [...liveRoots.values()]
                     .filter(agent => isArchived?.(String(agent.id)) !== true)
-                    .map(agent => ({
-                    id: String(agent.id),
-                    label: sessionLabelOf(agent),
-                    team: sessionTeamOf(agent),
-                    ...nodeMetadataOf(agent),
-                    joined: sessionNodes.has(String(agent.id)),
-                    live: true,
-                    teams: [...teamMemberships.teamsOf(String(agent.id))],
-                    // #19 D3: the session's exposure tier (linked floor /
-                    // fleet opt-up) — readable on the state face.
-                    exposure: exposureStore.tierOf(String(agent.id)),
-                    ...(canvasStore.teamsOf(String(agent.id)).length > 0 ? { canvasTeams: [...canvasStore.teamsOf(String(agent.id))] } : {}),
-                    ...(groupOf(String(agent.id)) !== undefined ? { group: groupOf(String(agent.id)) } : {}),
-                }));
+                    .map(agent => {
+                    // gh#152: canvas teams through the local lens — a handle-stored
+                    // membership (gh#131) shows here exactly as routing reads it.
+                    const canvasTeams = canvasTeamsOfSession(String(agent.id));
+                    return {
+                        id: String(agent.id),
+                        label: sessionLabelOf(agent),
+                        team: sessionTeamOf(agent),
+                        ...nodeMetadataOf(agent),
+                        joined: sessionNodes.has(String(agent.id)),
+                        live: true,
+                        teams: [...teamMemberships.teamsOf(String(agent.id))],
+                        // #19 D3: the session's exposure tier (linked floor /
+                        // fleet opt-up) — readable on the state face.
+                        exposure: exposureStore.tierOf(String(agent.id)),
+                        ...(canvasTeams.length > 0 ? { canvasTeams } : {}),
+                        ...(groupOf(String(agent.id)) !== undefined ? { group: groupOf(String(agent.id)) } : {}),
+                    };
+                });
                 // Cold joined sessions: a remembered intent whose Agent is not
                 // back yet (host restarted, session not opened). The row carries
                 // no facts — the Web client merges the session title from its
@@ -96,34 +101,51 @@ export function registerAdminFaces(webServer, d) {
                         joined: true,
                         live: false,
                         teams: [...teamMemberships.teamsOf(id)],
-                        ...(canvasStore.teamsOf(id).length > 0 ? { canvasTeams: [...canvasStore.teamsOf(id)] } : {}),
+                        // gh#152: same local lens as the live rows (handle-stored counts).
+                        ...(canvasTeamsOfSession(id).length > 0 ? { canvasTeams: canvasTeamsOfSession(id) } : {}),
                         ...(groupOf(id) !== undefined ? { group: groupOf(id) } : {}),
                     });
                 }
                 const body = JSON.stringify({
                     nodes: true,
                     version: PLUGIN_VERSION,
+                    // gh#193: a dark host says so — an empty remote list is not an outage.
+                    ...(config.isolated ? { isolated: true } : {}),
                     sessions,
                     groups: groupStore.list(),
                     canvas: {
                         teams: canvasStore.list().map(name => ({
                             name,
                             team: canvasTeamOf(name),
-                            members: canvasStore.membersOf(name).map(id => {
-                                // Dual shape: local members report this zone's join/live
-                                // facts; remote refs are opaque team handles — the state
-                                // face passes them through with remote:true for the
-                                // workbench's member chips and pickers.
-                                if (isRemoteMemberRef(id)) {
-                                    return { id, team: id, remote: true };
+                            // gh#152: members as the local tiers read them (gh#131). One
+                            // of this host's own handles renders as the local session it
+                            // names — join/live facts instead of an opaque remote chip — and
+                            // the two stored shapes of one session collapse to ONE row (the
+                            // store keeps both). Genuinely remote refs pass through with
+                            // remote:true for the workbench's member chips and pickers.
+                            members: (() => {
+                                const rows = [];
+                                const seenLocal = new Set();
+                                for (const id of canvasStore.membersOf(name)) {
+                                    if (isRemoteMemberRef(id)) {
+                                        const localId = localSessionOfHandle(id);
+                                        if (localId !== undefined) {
+                                            if (seenLocal.has(localId))
+                                                continue;
+                                            seenLocal.add(localId);
+                                            rows.push({ id: localId, team: `${config.team}/${id8(localId)}`, joined: sessionNodes.has(localId) || joinedSessions.has(localId), live: sessionNodes.has(localId) });
+                                            continue;
+                                        }
+                                        rows.push({ id, team: id, remote: true });
+                                        continue;
+                                    }
+                                    if (seenLocal.has(id))
+                                        continue;
+                                    seenLocal.add(id);
+                                    rows.push({ id, team: `${config.team}/${id8(id)}`, joined: sessionNodes.has(id) || joinedSessions.has(id), live: sessionNodes.has(id) });
                                 }
-                                return {
-                                    id,
-                                    team: `${config.team}/${id8(id)}`,
-                                    joined: sessionNodes.has(id) || joinedSessions.has(id),
-                                    live: sessionNodes.has(id),
-                                };
-                            }),
+                                return rows;
+                            })(),
                         })),
                     },
                     host: lanIp === '' ? {} : { lanIp },
@@ -168,6 +190,10 @@ export function registerAdminFaces(webServer, d) {
                         // say nothing about WHAT is owed — supervision cannot tell
                         // a nudge from an abandon without it.
                         ...(task.brief !== undefined ? { brief: task.brief } : {}),
+                        // #114 S3: the real sender, so supervision buckets by seat, not "home".
+                        ...(task.sender !== undefined ? { sender: task.sender } : {}),
+                        // #114 S2: the authority an inbound row was born with; a pre-S2 inbound row says so (S4).
+                        ...(task.auth !== undefined ? { auth: task.auth } : task.direction === 'inbound' ? { authLegacy: true } : {}),
                         // C-ruling bucket split: a pending row is settleable while
                         // it is young, expected, and answerable; past the stale
                         // hour it is conversational noise waiting on the dead TTL.
@@ -178,13 +204,18 @@ export function registerAdminFaces(webServer, d) {
                     tasksStaleCount: taskLedger.list().filter(task => task.status === 'pending' && (task.receiptExpected === false || Date.now() - task.startedAt >= 60 * 60_000)).length,
                     tasksDead: taskLedger.list()
                         .filter(task => task.status === 'dead')
-                        .map(task => ({ taskId: task.taskId, team: task.team, peer: task.peer, startedAt: task.startedAt, deadAt: task.deadAt ?? task.startedAt, reason: task.reason ?? 'unspecified', ...(task.brief !== undefined ? { brief: task.brief } : {}), ...(task.direction !== undefined ? { direction: task.direction } : {}) })),
+                        .map(task => ({ taskId: task.taskId, team: task.team, peer: task.peer, startedAt: task.startedAt, deadAt: task.deadAt ?? task.startedAt, reason: task.reason ?? 'unspecified', ...(task.brief !== undefined ? { brief: task.brief } : {}), ...(task.direction !== undefined ? { direction: task.direction } : {}), ...(task.sender !== undefined ? { sender: task.sender } : {}), ...(task.auth !== undefined ? { auth: task.auth } : task.direction === 'inbound' ? { authLegacy: true } : {}) })),
                     // gh#31: per-task outcomes for rows that LEFT the ledger — the
                     // chat drawer used to guess (settled, abandoned or cancelled).
                     // Bounded to the archive (≤64), newest first, with the
                     // controlled-vocabulary verdict each row settled by.
                     // gh#31 follow-up: archive() is already newest first (settles
                     // prepend), so the projection keeps that order — the earlier
+                    // gh#154: the conservation verdict rides the state face — lifetime
+                    // counters (restart-safe), duplicates checked before the count
+                    // identity, delta naming any gap. L8 can read this directly instead
+                    // of cross-round bookkeeping.
+                    conservation: taskLedger.conservation(),
                     // .reverse() served it oldest first. Each row also says HOW it
                     // ended (endedBy: abandon and cancel both record outcome
                     // 'abandoned', and so does a peer's own 'abandoned' receipt),
@@ -204,8 +235,33 @@ export function registerAdminFaces(webServer, d) {
                         ...(row.lateReceiptAt !== undefined ? { late: true } : {}),
                         ...(row.brief !== undefined ? { brief: row.brief } : {}),
                         ...(row.summary !== undefined && row.summary !== '' ? { summary: row.summary.slice(0, 160) } : {}),
+                        ...(row.sender !== undefined ? { sender: row.sender } : {}),
+                        ...(row.auth !== undefined ? { auth: row.auth } : {}),
+                        // #114 S4: who settled it and how they stood on the chain.
+                        ...(row.settledBy !== undefined ? { settledBy: row.settledBy } : {}),
                     })),
                     archivedCount: taskLedger.archive().length,
+                    // #114 S4: settlement authorization. The team verifier holds
+                    // `refusalsTotal` (monotonic) to zero; `offChain`, `legacy` and
+                    // `compat` count the bounded archive window (ARCHIVE_CAP rows), so
+                    // they are a window, not a lifetime total.
+                    settlement: (() => {
+                        const archive = taskLedger.archive();
+                        const roles = archive.flatMap(row => (row.settledBy !== undefined ? [row.settledBy.chain_role] : []));
+                        return {
+                            mode: config.settlementAuth,
+                            offChain: roles.filter(r => r === 'off-chain').length,
+                            legacy: roles.filter(r => r === 'legacy').length,
+                            compat: roles.filter(r => r === 'compat').length,
+                            refusals: taskLedger.settlementRefusals(),
+                            // Monotonic: every refusal noted, including repeats folded into one ring entry.
+                            refusalsTotal: taskLedger.settlementRefusalsTotal(),
+                        };
+                    })(),
+                    // #114 S6: allowlist version history and the affected-task entries
+                    // (observe mode: a record of what an allowlist change put on another
+                    // footing — nothing was cancelled).
+                    authorization: authorizationView(),
                     // Ledger density face: the settled archive split by verdict, so
                     // the workbench can say WHICH way those rows settled instead of
                     // just how many. Additive and bounded (outcome vocabulary is a
@@ -230,18 +286,31 @@ export function registerAdminFaces(webServer, d) {
                     // board renders REMOTE team frames from this. Absent until a
                     // linked fetch warmed the card.
                     peerOrg: peerStore.list().map(url => {
-                        const card = d.cardCache.get(url)?.card;
+                        const entry = d.cardCache.get(url);
+                        const card = entry?.card;
                         const org = card?.canvasOrg;
+                        // gh#106: a kept card's org is the peer's last known plan, not a live one.
+                        const unreachable = card !== undefined && entry?.missAt !== undefined ? { unreachable: true } : {};
                         return Array.isArray(org)
-                            ? { url, org: org.filter((e) => e !== null && typeof e === 'object')
+                            ? { url, ...unreachable, org: org.filter((e) => e !== null && typeof e === 'object')
                                     .map(e => ({ name: typeof e.name === 'string' ? e.name : '', team: typeof e.team === 'string' ? e.team : '', members: Array.isArray(e.members) ? e.members.filter((m) => typeof m === 'string') : [] }))
                                     .filter(e => e.team !== '') }
-                            : { url, org: [] };
+                            : { url, ...unreachable, org: [] };
                     }),
                     // gh#9+gh#10 M1: envelope-absent deliveries during the
                     // OriginClaim window — the operator watches this drain to
                     // zero before closing the window.
                     legacyInbound: d.legacyInboundCount,
+                    // Accepted unbound (no-audience) OriginClaim envelopes — the
+                    // drain gauge for closing originClaimUnboundWindow.
+                    unboundInbound: d.unboundInboundCount,
+                    // Of those, envelopes whose bound form missed here: the sender
+                    // dials an origin missing from originClaimAudiences.
+                    boundMissInbound: d.boundMissInboundCount,
+                    // gh#113: CLI mailbox loss, all handles — mail the 64-row cap
+                    // pushed out, and mail cut at 4000 chars. The team verifier
+                    // holds `dropped` to zero.
+                    cliMailbox: cliDeposits.mailStats(),
                     // F-observability: the boot prewarm's lifecycle — a dead or
                     // skipped prewarm is the root shape behind "cold rows pile up
                     // after restart" and must be readable, not a console rumor.
@@ -276,6 +345,7 @@ export function registerAdminFaces(webServer, d) {
                                 host: String(row.origin ?? ''),
                                 ...(row.workspace !== undefined && row.workspace !== '' ? { workspace: row.workspace } : {}),
                                 ...(row.legacy === true ? { legacy: true } : {}),
+                                ...(row.unreachable === true ? { unreachable: true } : {}),
                                 teams: [...(row.teams ?? [])],
                                 remote: true,
                             })),
@@ -341,13 +411,18 @@ export function registerAdminFaces(webServer, d) {
         handler: controlRoute((req, res) => {
             readJsonBody(req, res, (body) => {
                 const id = typeof body.id === 'string' ? body.id : '';
+                // gh#131: read while the session is still joined — its own handle reads as it only then.
+                const ownHandle = id !== '' ? ownCanvasHandleOf(id) : undefined;
                 if (id !== '')
                     sessionNodes.delete(id);
                 joinedSessions.remove(id);
                 // Leaving the network leaves every canvas team too: membership
                 // without join consent would be a routing backdoor. Team
-                // roster declarations die the same way (S2 consistency).
+                // roster declarations die the same way (S2 consistency) — and so
+                // does a membership a fleet edit stored by the session's handle.
                 canvasStore.dropMember(id);
+                if (ownHandle !== undefined)
+                    canvasStore.dropMember(ownHandle);
                 teamMemberships.dropSession(id);
                 const payload = JSON.stringify({ id });
                 res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
@@ -367,7 +442,16 @@ export function registerAdminFaces(webServer, d) {
                 let payload;
                 if (action === 'publish') {
                     const card = typeof body.card === 'string' ? body.card : '';
-                    const out = cliDeposits.deposit(card);
+                    // Review of PR #135: a CLI may not be named after this host's zone —
+                    // its handle would read as one of the zone's own faces.
+                    const name = (() => { try {
+                        const team = JSON.parse(card).team;
+                        return typeof team === 'string' ? team.split('/')[0] : '';
+                    }
+                    catch {
+                        return '';
+                    } })();
+                    const out = name === config.team ? { ok: false, error: `a CLI identity may not be named after this host's zone "${config.team}" — choose another agent name` } : cliDeposits.deposit(card);
                     payload = JSON.stringify(out.ok
                         ? { ok: true, handle: out.handle, expiresAt: out.expiresAt, cardUrl: `${d.ownCardUrl}/a2a/cli/${encodeURIComponent(out.handle)}` }
                         : { ok: false, error: out.error });
@@ -377,7 +461,10 @@ export function registerAdminFaces(webServer, d) {
                 }
                 else if (action === 'inbox') {
                     const handle = typeof body.handle === 'string' ? body.handle : '';
-                    payload = JSON.stringify({ ok: true, mail: cliDeposits.readMail(handle) });
+                    // gh#113: seq bounds and the loss counter ride beside the rows; after_seq trims to newer rows.
+                    const after = body.after_seq;
+                    const box = cliDeposits.readMailbox(handle, typeof after === 'number' && Number.isInteger(after) && after >= 0 ? after : undefined);
+                    payload = JSON.stringify({ ok: true, ...box });
                 }
                 else {
                     payload = JSON.stringify({ ok: true, deposits: cliDeposits.list().map(row => ({ handle: row.handle, name: row.name, depositedAt: row.depositedAt, expiresAt: row.expiresAt })) });
@@ -405,8 +492,8 @@ export function registerAdminFaces(webServer, d) {
                     res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
                     res.end(payload);
                 };
-                if (peerUrl === '' || !/^https?:\/\//.test(peerUrl) || !['create', 'add-member', 'remove-member'].includes(opV) || (opV !== 'create' && nameV === '')) {
-                    send(JSON.stringify({ ok: false, error: 'peer (http url), op (create | add-member | remove-member), and name are required' }));
+                if (peerUrl === '' || !/^https?:\/\//.test(peerUrl) || !['create', 'add-member', 'remove-member', 'remove'].includes(opV) || (opV !== 'create' && nameV === '')) {
+                    send(JSON.stringify({ ok: false, error: 'peer (http url), op (create | add-member | remove-member | remove), and name are required' }));
                     return;
                 }
                 if (!peerStore.list().includes(peerUrl)) {
@@ -415,12 +502,12 @@ export function registerAdminFaces(webServer, d) {
                 }
                 try {
                     const target = peerUrl.replace(/\/$/, '') + '/a2a/canvas-op';
-                    const reply = await globalThis.fetch(target, {
+                    const reply = await d.peerFetch(target, {
                         method: 'POST',
-                        headers: { 'Content-Type': 'application/json', ...originClaimHeaders() },
+                        headers: { 'Content-Type': 'application/json', ...originClaimHeaders({ url: target, method: 'POST' }) },
                         // A local session id means nothing on the peer: send its zone/id8 handle (the workbench
                         // drops a local card into a remote frame with its raw session id, which the peer refused).
-                        body: JSON.stringify({ op: opV, name: nameV, ...(opV !== 'create' ? { id: idV !== '' && !isRemoteMemberRef(idV) && (sessionNodes.has(idV) || joinedSessions.has(idV)) ? `${config.team}/${id8(idV)}` : idV } : {}) }),
+                        body: JSON.stringify({ op: opV, name: nameV, ...(opV === 'add-member' || opV === 'remove-member' ? { id: idV !== '' && !isRemoteMemberRef(idV) && (sessionNodes.has(idV) || joinedSessions.has(idV)) ? `${config.team}/${id8(idV)}` : idV } : {}) }),
                         signal: AbortSignal.timeout(15_000),
                     });
                     const raw = await reply.text();
@@ -602,7 +689,10 @@ export function registerAdminFaces(webServer, d) {
                         payload = JSON.stringify({ ok: false, error: 'name and id are required' });
                     }
                     else {
-                        payload = JSON.stringify({ ok: canvasStore.removeMember(name, id), teams: canvasStore.list(), members: canvasStore.membersOf(name) });
+                        // gh#131: removing a local session removes its handle-stored slot too.
+                        const ownHandle = isRemoteMemberRef(id) ? undefined : ownCanvasHandleOf(id);
+                        const removed = [id, ...(ownHandle !== undefined ? [ownHandle] : [])].map(each => canvasStore.removeMember(name, each)).some(Boolean);
+                        payload = JSON.stringify({ ok: removed, teams: canvasStore.list(), members: canvasStore.membersOf(name) });
                     }
                 }
                 else {

package/lib/faces/canvas-notify.js

@@ -36,12 +36,21 @@ export function registerCanvasNotify(webServer, d) {
         // signs it): only a peer that is served the full card ever sees canvasOrg.
         return card !== undefined && callerLinkedToThisHost(card.team, url, card);
     });
+    // Who was linked at the last flush. A change can end a link (dissolving
+    // the only team that names a peer's handle), and that peer must still
+    // hear about it — its next card read is what drops the mirror.
+    let lastRecipients = [];
     const flush = () => {
         timer = undefined;
-        for (const url of recipients()) {
-            void globalThis.fetch(url.replace(/\/$/, '') + '/a2a/canvas-changed', {
+        const now = recipients();
+        const tracked = new Set(peerStore.list()); // an untracked peer gets no more envelopes
+        const targets = new Set([...now, ...lastRecipients.filter(url => tracked.has(url))]);
+        lastRecipients = now;
+        for (const url of targets) {
+            const target = url.replace(/\/$/, '') + '/a2a/canvas-changed';
+            void d.peerFetch(target, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json', ...originClaimHeaders() },
+                headers: { 'Content-Type': 'application/json', ...originClaimHeaders({ url: target, method: 'POST' }) },
                 body: '{}',
                 signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
             }).then(async (reply) => {

package/lib/faces/files.js

@@ -0,0 +1,155 @@
+import { BLOB_FILE_MAX } from "../blob-store.js";
+import { isRootOriginUrl } from "../origin-claim.js";
+import { claimCovers } from "../task-auth.js";
+/** Pulls per proven signer (host zone or CLI handle) in a sliding minute (design §8; the FloodGuard figure). */
+export const BLOB_PULLS_PER_MINUTE = 16;
+/** Distinct signers the pull limiter remembers; a full table refuses new signers rather than forgetting live ones. */
+const PULL_CALLERS_MAX = 1024;
+/**
+ * Whether a grant's target lets this proven caller pull (design §3.2). For a HOST signer: the
+ * caller's own label; the signer host itself (a grant to the whole zone); one of the signer host's
+ * canvas teams (`<signer>/canvas/<name>` — that host answers for its own membership); or a canvas
+ * team of THIS host (`<zone>/canvas/<name>`; another host's same-named team is a different team) of
+ * which the caller ITSELF is a member. A grant to one session is not another session's, even on the
+ * same host (#91 F2: the honest host's tool names the pulling session, so a mistake cannot cross
+ * sessions). A CLI handle is an identity, never a zone (review of PR #208 R1): only its own grant.
+ * `caller` is already proven by `signer`.
+ */
+export function grantAdmits(to, caller, signer, zone, localCanvasMembers, cli = false) {
+    if (to === caller)
+        return true;
+    if (cli)
+        return false;
+    if (to === signer)
+        return true;
+    const own = `${signer}/canvas/`;
+    if (to.startsWith(own) && to.length > own.length)
+        return true;
+    const prefix = `${zone}/canvas/`;
+    return to.startsWith(prefix) && to.length > prefix.length && localCanvasMembers(to.slice(prefix.length)).includes(caller);
+}
+/**
+ * Register the pull face and the stage face on the shared web server.
+ * @param d - the captures listed on {@link FileFaceDeps}.
+ */
+export function registerFileFaces(webServer, d) {
+    const { ctx, config, blobStore, canvasStore, verifyOriginClaim, secretEqual, controlRoute, recordActivity } = d;
+    const now = d.now ?? (() => Date.now());
+    const pulls = new Map();
+    const json = (res, status, body) => {
+        const payload = JSON.stringify(body);
+        res.writeHead(status, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) });
+        res.end(payload);
+    };
+    /** One more pull for a proven signer inside the minute, or false when it is over budget (or the table is full). */
+    const takePull = (signer) => {
+        const at = now();
+        for (const [key, times] of pulls)
+            if (times.every(t => at - t >= 60_000))
+                pulls.delete(key);
+        const recent = (pulls.get(signer) ?? []).filter(t => at - t < 60_000);
+        if (recent.length >= BLOB_PULLS_PER_MINUTE)
+            return false;
+        if (!pulls.has(signer) && pulls.size >= PULL_CALLERS_MAX)
+            return false;
+        pulls.set(signer, [...recent, at]);
+        return true;
+    };
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/a2a/blob',
+        handler: async (req, res) => {
+            if (req.method !== 'GET') {
+                json(res, 405, { ok: false, error: 'GET is the only method on this face' });
+                return;
+            }
+            if (config.apiKey !== '' && !secretEqual(String(req.headers['x-api-key'] ?? ''), config.apiKey)) {
+                json(res, 401, { ok: false, error: 'unauthorized: X-API-Key required (apiKey is configured)' });
+                return;
+            }
+            const url = new URL(req.url ?? '/', 'http://x');
+            const sha256 = url.searchParams.get('sha256') ?? '';
+            const caller = url.searchParams.get('caller_session') ?? '';
+            const refuse = (status, code, error) => {
+                recordActivity('in', 'blob', caller === '' ? 'anonymous' : caller, false);
+                json(res, status, { ok: false, code, error });
+            };
+            if (caller === '') {
+                refuse(403, 'untrusted-origin', 'caller_session is required');
+                return;
+            }
+            const claim = await verifyOriginClaim(req, { cli: true });
+            if (!claim.ok) {
+                refuse(403, 'untrusted-origin', `OriginClaim verification failed (${claim.reason}) — a file is pulled only with a signed envelope`);
+                return;
+            }
+            // A deposited CLI handle proves exactly itself (R1: `H/child` is not H); a host proves its zone.
+            const proven = claim.cli === true
+                ? caller === claim.caller
+                : claim.bound === true && isRootOriginUrl(claim.callerUrl) && claimCovers(caller, claim.caller);
+            if (!proven) {
+                refuse(403, 'untrusted-origin', 'the envelope does not prove this caller (it must be the audience-bound form, signed from a root card URL whose zone covers caller_session)');
+                return;
+            }
+            const grant = blobStore.list().find(g => g.sha256 === sha256 && grantAdmits(g.to, caller, claim.caller, config.team, name => canvasStore.membersOf(name), claim.cli === true));
+            // One answer for "no such blob", "expired" and "not yours": a refusal is no existence oracle.
+            if (grant === undefined) {
+                refuse(403, 'not-granted', 'no live grant lets this caller pull that file');
+                return;
+            }
+            // Budgeted by the PROVEN signer (a host zone or a CLI handle), never the self-described label (R1).
+            if (!takePull(claim.caller)) {
+                refuse(429, 'rate-limited', `at most ${String(BLOB_PULLS_PER_MINUTE)} pulls per signer per minute`);
+                return;
+            }
+            const bytes = blobStore.read(grant);
+            if (bytes === undefined) {
+                refuse(410, 'gone', 'the file is no longer stored on this host');
+                return;
+            }
+            recordActivity('in', 'blob', caller, true);
+            res.writeHead(200, { 'Content-Type': 'application/octet-stream', 'Content-Length': bytes.byteLength, 'X-A2A-Blob-Sha256': grant.sha256, 'X-A2A-Blob-Name': encodeURIComponent(grant.name) });
+            res.end(bytes);
+        },
+    }), 'a2a: file-channel pull face');
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/__dsh_a2a/blob',
+        handler: controlRoute((req, res) => {
+            if (req.method !== 'POST') {
+                json(res, 405, { ok: false, error: 'POST raw bytes with ?to=<team>&name=<file>' });
+                return;
+            }
+            const url = new URL(req.url ?? '/', 'http://x');
+            const to = url.searchParams.get('to') ?? '';
+            const name = url.searchParams.get('name') ?? 'file';
+            const by = url.searchParams.get('by') ?? 'control';
+            const declared = Number(req.headers['content-length'] ?? NaN);
+            if (Number.isFinite(declared) && declared > BLOB_FILE_MAX) {
+                json(res, 413, { ok: false, code: 'too-large', error: `the file channel takes at most ${String(BLOB_FILE_MAX)} bytes` });
+                req.resume();
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            let over = false;
+            req.on('data', (chunk) => {
+                size += chunk.byteLength;
+                if (size > BLOB_FILE_MAX) {
+                    over = true;
+                    return;
+                }
+                if (!over)
+                    chunks.push(chunk);
+            });
+            req.on('end', () => {
+                if (over) {
+                    json(res, 413, { ok: false, code: 'too-large', error: `the file channel takes at most ${String(BLOB_FILE_MAX)} bytes` });
+                    return;
+                }
+                const staged = blobStore.stage(Buffer.concat(chunks), { name, to, by });
+                json(res, staged.ok ? 200 : staged.code === 'too-large' ? 413 : staged.code === 'full' ? 507 : 400, { ...staged });
+            });
+        }),
+    }), 'a2a: file-channel stage face');
+}