@rubytech/create-maxy-code 0.1.457 → 0.1.459

package/payload/platform/lib/storage-broker/src/cf-exec.ts

@@ -14,14 +14,32 @@ export type RunFn = (
   env: Record<string, string>,
 ) => Promise<{ stdout: string }>;
 
-// The HTTP seam for the Cloudflare API. Injectable so r2List and d1Create are
+// The HTTP seam for the Cloudflare API. Injectable so the API-backed methods are
 // unit-testable without a network. Minimal subset of the global fetch: callers
 // read the body once via text() and branch on ok/status. `body` is set for the
-// POST paths (d1Create); GET paths (r2List) omit it.
+// POST/PUT paths (d1Create, r2ObjectPut); GET/DELETE paths omit it.
+//
+// Task 1691 widened both halves: `body` carries Uint8Array for the object-put
+// path, and `arrayBuffer` reads the raw object body for r2ObjectGet, which is
+// the one method whose response is not a JSON envelope. arrayBuffer is required
+// rather than optional: an optional member would force a fake-only fallback
+// branch in r2ObjectGet that never runs against a real fetch.
 export type FetchFn = (
   url: string,
-  init: { method: string; headers: Record<string, string>; body?: string },
-) => Promise<{ ok: boolean; status: number; text(): Promise<string> }>;
+  init: { method: string; headers: Record<string, string>; body?: string | Uint8Array },
+) => Promise<{
+  ok: boolean;
+  status: number;
+  text(): Promise<string>;
+  arrayBuffer(): Promise<ArrayBuffer>;
+}>;
+
+export interface R2Object {
+  key: string;
+  size: number;
+  etag: string;
+  lastModified: string;
+}
 
 export interface CfExec {
   d1List(): Promise<{ name: string; uuid: string }[]>;
@@ -29,9 +47,33 @@ export interface CfExec {
   d1Query(name: string, sql: string): Promise<unknown>;
   r2List(): Promise<{ name: string }[]>;
   r2Create(name: string): Promise<void>;
+  r2ObjectList(bucket: string, prefix?: string): Promise<R2Object[]>;
+  r2ObjectGet(bucket: string, key: string): Promise<Uint8Array>;
+  r2ObjectPut(bucket: string, key: string, body: Uint8Array): Promise<void>;
+  r2ObjectDelete(bucket: string, key: string): Promise<void>;
+}
+
+// An object key carries `/` as a real path separator (the data portal's
+// per-person prefixes), so it is encoded segment-wise rather than whole:
+// separators stay separators, and spaces and specials are escaped. This
+// encoding is not doc-confirmed; it is chosen so that a wrong guess surfaces as
+// a 404 carrying its body, never as a silently misfiled object.
+function encodeObjectKey(key: string): string {
+  return key.split("/").map(encodeURIComponent).join("/");
 }
 
-const defaultFetch: FetchFn = (url, init) => fetch(url, init);
+// The single-object endpoint, shared by get/put/delete so the three cannot drift
+// apart on encoding.
+function objectUrl(accountId: string, bucket: string, key: string): string {
+  return `https://api.cloudflare.com/client/v4/accounts/${accountId}/r2/buckets/${encodeURIComponent(bucket)}/objects/${encodeObjectKey(key)}`;
+}
+
+// The cast is confined to this adapter. A Uint8Array is a valid fetch body at
+// runtime, but the DOM lib's BodyInit does not admit TypeScript's generic
+// Uint8Array<ArrayBufferLike>, so consumers compiled against DOM typings (the
+// ui server) reject the call the Node typings accept. Casting here keeps the
+// seam's own type honest for every caller and test.
+const defaultFetch: FetchFn = (url, init) => fetch(url, init as RequestInit);
 
 const defaultRun: RunFn = (cmd, args, env) =>
   new Promise((resolve, reject) => {
@@ -52,6 +94,34 @@ function parseJson(raw: string, context: string): unknown {
   }
 }
 
+// The Cloudflare-API envelope, in one place. Both API-backed methods (r2List,
+// d1Create) share it: read the body exactly once, surface a non-2xx with its
+// body, parse, then require an explicit `success:true`. A 2xx whose body is not
+// a well-formed success envelope is an anomaly to surface with its body, never
+// a silently empty/uuid-less result. The raw `body` is returned alongside the
+// parsed value so callers can raise their own shaping errors on the original
+// bytes rather than a re-serialised copy.
+async function cfApiJson(
+  fetchFn: FetchFn,
+  url: string,
+  init: { method: string; headers: Record<string, string>; body?: string | Uint8Array },
+  context: string,
+): Promise<{ parsed: unknown; body: string }> {
+  const res = await fetchFn(url, init);
+  const body = await res.text();
+  if (!res.ok) {
+    throw new Error(`storage-broker: ${context} failed: ${res.status}\n${body}`);
+  }
+  // `null` is valid JSON and survives parseJson, so the guard is optional-
+  // chained: a null parsed value must surface its body like any other malformed
+  // 2xx shape, never a bare TypeError with the body dropped.
+  const parsed = parseJson(body, context) as { success?: boolean } | null;
+  if (parsed?.success !== true) {
+    throw new Error(`storage-broker: ${context} API error: ${body}`);
+  }
+  return { parsed, body };
+}
+
 export function makeCfExec(
   cred: HouseCredential,
   run: RunFn = defaultRun,
@@ -76,30 +146,26 @@ export function makeCfExec(
       // so shelling it with --json is always rejected. The D1 API creates the
       // database and returns its record — incl. the uuid — as JSON directly.
       const url = `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}/d1/database`;
-      const res = await fetchFn(url, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${cred.apiToken}`,
-          "Content-Type": "application/json",
+      const { parsed, body } = await cfApiJson(
+        fetchFn,
+        url,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${cred.apiToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({ name }),
         },
-        body: JSON.stringify({ name }),
-      });
-      const body = await res.text();
-      if (!res.ok) {
-        throw new Error(`storage-broker: d1 create failed: ${res.status}\n${body}`);
-      }
-      const parsed = parseJson(body, "d1 create") as {
-        success?: boolean;
-        errors?: unknown;
-        result?: { uuid?: string };
-      };
-      // Require an explicit success envelope with a uuid. A 2xx whose body is
-      // not a well-formed `success:true` response is an anomaly to surface with
-      // its body, never a silently uuid-less create.
-      if (parsed.success !== true || typeof parsed.result?.uuid !== "string") {
+        "d1 create",
+      );
+      // The envelope guard lives in cfApiJson; a uuid-less 2xx success envelope
+      // is still an anomaly to surface with its body, never a silent create.
+      const uuid = (parsed as { result?: { uuid?: string } }).result?.uuid;
+      if (typeof uuid !== "string") {
         throw new Error(`storage-broker: d1 create API error: ${body}`);
       }
-      return { uuid: parsed.result.uuid };
+      return { uuid };
     },
     async d1Query(name, sql) {
       const { stdout } = await run(
@@ -113,30 +179,150 @@ export function makeCfExec(
       // `wrangler r2 bucket list` has no --json flag and emits human prose, so
       // it can neither be parsed nor honour the "never grep a CLI's prose"
       // doctrine. The R2 API returns the bucket set as JSON directly.
-      const url = `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}/r2/buckets`;
-      const res = await fetchFn(url, {
+      //
+      // The endpoint paginates: a single request returns only the first page,
+      // and the audit reads the missing remainder as "absent", under-reporting
+      // strays. Follow result_info.cursor to exhaustion instead. per_page is
+      // deliberately never sent — its default and maximum are unconfirmed, and
+      // omitting it takes whatever page size Cloudflare serves, so the loop is
+      // complete without guessing a value that could 400 the request.
+      const base = `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}/r2/buckets`;
+      const buckets: { name: string }[] = [];
+      const seen = new Set<string>();
+      let cursor: string | undefined;
+      for (;;) {
+        const url = cursor === undefined ? base : `${base}?cursor=${encodeURIComponent(cursor)}`;
+        const { parsed } = await cfApiJson(
+          fetchFn,
+          url,
+          { method: "GET", headers: { Authorization: `Bearer ${cred.apiToken}` } },
+          "r2 bucket list",
+        );
+        const page = parsed as {
+          result?: { buckets?: { name: string }[] };
+          result_info?: { cursor?: string | null };
+        };
+        for (const b of page.result?.buckets ?? []) buckets.push({ name: b.name });
+        // A missing, null, or empty cursor all mean "last page" — accept every
+        // documented last-page signal rather than depend on which one is sent.
+        const next = page.result_info?.cursor;
+        if (!next) return buckets;
+        // Any cursor seen before means the API is cycling rather than advancing,
+        // which would loop forever and re-append the same buckets each pass.
+        // Tracking every cursor (not just the last) also catches a cycle of
+        // period >= 2, which never repeats consecutively. Surface it instead of
+        // hanging the broker on an unbounded wait.
+        if (seen.has(next)) {
+          throw new Error(
+            `storage-broker: r2 bucket list returned a repeated pagination cursor: ${next}`,
+          );
+        }
+        seen.add(next);
+        cursor = next;
+      }
+    },
+    async r2Create(name) {
+      await run("npx", ["wrangler", "r2", "bucket", "create", name], env);
+    },
+
+    // --- R2 objects (Task 1691) -------------------------------------------
+    //
+    // The v4 REST API exposes the object surface under
+    // /accounts/{id}/r2/buckets/{bucket}/objects and accepts the same Bearer
+    // token as the bucket endpoints (account-level Workers R2 Storage Write).
+    // The r2/api/tokens/ note that "Object Read & Write" is S3-only constrains
+    // the bucket-item-scoped *permission types*, not these endpoints.
+    //
+    // Doc-confirmed, never measured: no house Cloudflare credential exists on
+    // the dev machine. The design keeps the unmeasured facts unable to affect
+    // correctness — per_page is never sent, and nothing fails silently.
+    async r2ObjectList(bucket, prefix) {
+      // Mirrors r2List: follow the cursor to exhaustion, never send per_page.
+      // A truncated object listing reads as "those objects are absent" to the
+      // data portal's standing audit, producing false phantom rows and hiding
+      // real orphans — the same bug r2List had, one endpoint over.
+      const base = `https://api.cloudflare.com/client/v4/accounts/${cred.accountId}/r2/buckets/${encodeURIComponent(bucket)}/objects`;
+      const objects: R2Object[] = [];
+      const seen = new Set<string>();
+      let cursor: string | undefined;
+      for (;;) {
+        const params = new URLSearchParams();
+        if (prefix !== undefined) params.set("prefix", prefix);
+        if (cursor !== undefined) params.set("cursor", cursor);
+        const qs = params.toString();
+        const { parsed, body } = await cfApiJson(
+          fetchFn,
+          qs ? `${base}?${qs}` : base,
+          { method: "GET", headers: { Authorization: `Bearer ${cred.apiToken}` } },
+          "r2 object list",
+        );
+        const page = parsed as {
+          result?: Array<{ key: string; size: number; etag: string; last_modified: string }>;
+          result_info?: { cursor?: string | null; is_truncated?: boolean };
+        };
+        for (const o of page.result ?? []) {
+          objects.push({ key: o.key, size: o.size, etag: o.etag, lastModified: o.last_modified });
+        }
+        const truncated = page.result_info?.is_truncated;
+        const next = page.result_info?.cursor;
+        // is_truncated is authoritative *when present*: a last page may still
+        // carry a cursor, and following it would issue a pointless request or
+        // trip the cycle guard below on a healthy response.
+        if (truncated === false) return objects;
+        // The API says there is more but names no cursor: the response is not
+        // the shape we understand. Surface it rather than return a partial
+        // list, which is the failure this loop exists to prevent.
+        if (truncated === true && !next) {
+          throw new Error(
+            `storage-broker: r2 object list reported truncated but gave no pagination cursor: ${body}`,
+          );
+        }
+        // is_truncated absent: it is itself an unmeasured fact, so it must not
+        // be what decides correctness. Fall back to cursor presence — the rule
+        // r2List uses on the same envelope — so an envelope without the flag
+        // paginates rather than truncating silently.
+        if (!next) return objects;
+        // A cursor seen before means the API is cycling rather than advancing:
+        // it would loop forever, re-appending the same objects each pass.
+        if (seen.has(next)) {
+          throw new Error(
+            `storage-broker: r2 object list returned a repeated pagination cursor: ${next}`,
+          );
+        }
+        seen.add(next);
+        cursor = next;
+      }
+    },
+    async r2ObjectGet(bucket, key) {
+      // The one method cfApiJson cannot wrap: get returns the raw object body,
+      // not a success envelope, so there is nothing to parse or assert
+      // success:true on. The error body is still retained on a non-2xx.
+      const res = await fetchFn(objectUrl(cred.accountId, bucket, key), {
         method: "GET",
         headers: { Authorization: `Bearer ${cred.apiToken}` },
       });
-      const body = await res.text();
       if (!res.ok) {
-        throw new Error(`storage-broker: r2 bucket list failed: ${res.status}\n${body}`);
-      }
-      const parsed = parseJson(body, "r2 bucket list") as {
-        success?: boolean;
-        errors?: unknown;
-        result?: { buckets?: { name: string }[] };
-      };
-      // Require an explicit success envelope. A 2xx whose body is not a
-      // well-formed `success:true` response is an anomaly to surface with its
-      // body, never a silent empty bucket set.
-      if (parsed.success !== true) {
-        throw new Error(`storage-broker: r2 bucket list API error: ${body}`);
+        throw new Error(
+          `storage-broker: r2 object get failed: ${res.status}\n${await res.text()}`,
+        );
       }
-      return (parsed.result?.buckets ?? []).map((b) => ({ name: b.name }));
+      return new Uint8Array(await res.arrayBuffer());
     },
-    async r2Create(name) {
-      await run("npx", ["wrangler", "r2", "bucket", "create", name], env);
+    async r2ObjectPut(bucket, key, body) {
+      await cfApiJson(
+        fetchFn,
+        objectUrl(cred.accountId, bucket, key),
+        { method: "PUT", headers: { Authorization: `Bearer ${cred.apiToken}` }, body },
+        "r2 object put",
+      );
+    },
+    async r2ObjectDelete(bucket, key) {
+      await cfApiJson(
+        fetchFn,
+        objectUrl(cred.accountId, bucket, key),
+        { method: "DELETE", headers: { Authorization: `Bearer ${cred.apiToken}` } },
+        "r2 object delete",
+      );
     },
   };
 }

package/payload/platform/lib/storage-broker/src/house-credential.ts

@@ -1,7 +1,13 @@
 // Reads the single account-wide Cloudflare credential from the house-only
 // config directory. This file is the one place the account-wide capability
-// lives; sub-account spawns never source it. Parses KEY=value lines without
-// polluting process.env (same discipline as reconcile-bookings' readEnvFile).
+// lives. House-only is a location convention plus the cf-token.sh caller gate,
+// NOT an OS permission: every account's session runs as the same unix user, so
+// a sub-account agent holding Bash can read this path directly. That is a
+// permanent property, not a pending gap: OS user separation was costed and
+// declined as disproportionate (Task 1690, archived undone), so nothing tracks
+// it. Do not cite this file's location or mode as a boundary. Parses
+// KEY=value lines without polluting process.env (same discipline as
+// reconcile-bookings' readEnvFile).
 
 import { readFileSync } from "node:fs";
 import { join } from "node:path";

package/payload/platform/lib/storage-broker/src/index.ts

@@ -7,6 +7,7 @@
 // isolation and the isolation logic auditable in one place.
 
 export * from "./authorize.js";
+export * from "./object-limits.js";
 export * from "./registry.js";
 export * from "./house-credential.js";
 export * from "./cf-exec.js";

package/payload/platform/lib/storage-broker/src/object-limits.ts

@@ -0,0 +1,75 @@
+/**
+ * The byte cap on R2 object transfer, and the arithmetic the routes need to
+ * enforce it before they buffer anything.
+ *
+ * One number, one home (Task 1695). The storage-broker MCP tools and the house
+ * ui routes both read the cap from here, so the process that rejects a too-large
+ * file and the process that would otherwise buffer it cannot drift apart.
+ *
+ * Deliberately dependency-free: the MCP imports this module directly, without
+ * the rest of the lib (cf-exec, registry, audit, remediate), which it has no use
+ * for. The ui route reads it through the barrel.
+ */
+
+/**
+ * The maximum size, in bytes, of an object moved through storage-r2-object-get
+ * or storage-r2-object-put.
+ *
+ * Set independently of the email plugin's OUTBOUND_ATTACHMENT_MAX_BYTES (25 MiB)
+ * even though the payload class is the same. The two exist for different reasons
+ * and must be free to move for different reasons: email's tracks an SMTP-side
+ * rejection threshold, this one tracks house-process memory. Do not couple them.
+ *
+ * Not bounded by R2. A single-part upload may be up to 5 GiB (doc-confirmed:
+ * developers.cloudflare.com/r2/platform/limits/), roughly fifty times this, and
+ * the v4 REST API states no separate object-size limit. This cap is the only
+ * bound on either transfer.
+ *
+ * The bound is not small: at the cap a get still leaves the house process
+ * holding the object and its base64 form, roughly 2.4x the object. That cost was
+ * weighed and accepted when the number was chosen.
+ */
+export const R2_OBJECT_MAX_BYTES = 100 * 1024 * 1024;
+
+/** base64 emits 4 characters per 3 input bytes, padded up to the next quantum. */
+export function base64Ceiling(bytes: number): number {
+  return 4 * Math.ceil(bytes / 3);
+}
+
+/**
+ * Room for the put envelope's bucket, key and JSON punctuation, so a legal
+ * at-cap put is not rejected by its own key. Far above any realistic bucket+key
+ * length and far below the cap, so it cannot smuggle a meaningfully larger
+ * object.
+ */
+const PUT_ENVELOPE_ALLOWANCE_BYTES = 64 * 1024;
+
+/**
+ * The largest JSON body /r2/object/put can legitimately carry.
+ *
+ * This bounds house memory; it does not adjudicate the last kilobyte. The exact
+ * decoded-byte rule lives in the MCP, which knows the source's size exactly.
+ */
+export const R2_OBJECT_PUT_MAX_BODY_BYTES =
+  base64Ceiling(R2_OBJECT_MAX_BYTES) + PUT_ENVELOPE_ALLOWANCE_BYTES;
+
+function formatMiB(bytes: number): string {
+  return (bytes / 1024 / 1024).toFixed(1);
+}
+
+/**
+ * The over-cap message, worded once so the MCP and the routes agree. Names the
+ * offending object and the limit, which is what makes the failure actionable
+ * rather than an opaque out-of-memory kill.
+ *
+ * Exact bytes accompany the MiB figures because MiB alone rounds: an object one
+ * byte over the cap reads "100.0 MiB, which exceeds the 100.0 MiB limit", which
+ * is a message that appears to contradict itself and invites the reader to treat
+ * the rejection as a bug. The bytes are what make it legible; the MiB is what
+ * makes it quick.
+ */
+export function tooLargeMessage(what: string, actualBytes: number): string {
+  return `${what} is ${formatMiB(actualBytes)} MiB (${actualBytes} bytes), which exceeds the ${formatMiB(
+    R2_OBJECT_MAX_BYTES,
+  )} MiB (${R2_OBJECT_MAX_BYTES} bytes) R2 object limit.`;
+}

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:d31a178be753e371f5773e362173eb0090115ababe81563d2b5f38890098202c
+content-hash: sha256:15c9a9d54bd8898a18c541ce95b9f5dc869646faad096eefc60741bb405a062d
 brand: maxy-code
 product-name: Maxy
 ---
@@ -2071,9 +2071,9 @@ The `outlook` plugin gives the admin agent access to Microsoft 365 / Outlook.com
 | `outlook-contacts-list` | Top contacts. Default top=50. |
 | `outlook-mailbox-info` | Health probe for one mailbox — auth state, refresh-window, folder count. Name the mailbox with `mailbox` when several are attached. |
 | `outlook-mailbox-list` | Every connected mailbox with its email, scopes, and token health. Local only — no network — so it also flags a mailbox whose stored credentials cannot be read. |
-| `outlook-mail-send` | Send a message (`POST /me/sendMail`). to/cc/bcc arrays, subject, body, isHtml. Success asserted on Graph 202. Needs `Mail.Send`. |
-| `outlook-draft` | Create a draft in Drafts (`POST /me/messages`). Same body model. Returns the draft id. Needs `Mail.ReadWrite`. |
-| `outlook-draft-edit` | Update an existing draft in place (`PATCH /me/messages/{draftId}`). Graph drafts are mutable — pass draftId plus the fields to change (to/cc/bcc/subject/body/isHtml). Sent messages cannot be edited. Needs `Mail.ReadWrite`. |
+| `outlook-mail-send` | Send a message. No attachments → `POST /me/sendMail`; with attachments → draft, attach, send (`/me/sendMail` carries attachments inline and cannot fit a large file). to/cc/bcc arrays, subject, body, isHtml, attachments (account-dir paths, 25 MB/file). Success asserted on Graph 202; no message id on either route. Needs `Mail.Send` (+ `Mail.ReadWrite` to attach). |
+| `outlook-draft` | Create a draft in Drafts (`POST /me/messages`). Same body model, including attachments — files are attached before the id is returned, so the draft is ready to send. Returns the draft id. Needs `Mail.ReadWrite`. |
+| `outlook-draft-edit` | Update an existing draft in place (`PATCH /me/messages/{draftId}`) and/or add attachments. Graph drafts are mutable — pass draftId plus the fields to change (to/cc/bcc/subject/body/isHtml/attachments). Attachments are additive; removal is not supported. Sent messages cannot be edited. Needs `Mail.ReadWrite`. |
 | `outlook-draft-send` | Send an existing draft by id (`POST /me/messages/{id}/send`). Graph consumes the draft, returns 202. Needs `Mail.Send`. |
 
 ## Observability
@@ -2148,7 +2148,7 @@ Latency triage: `mail-list count=0 elapsedMs<200` consistent → permissions iss
 
 ## Out of scope
 
-Mail move to arbitrary folders / flag, hard (permanent) delete, ingesting reviewed mail into the business graph (the `email-ingest` analogue), contacts write, recurring-series occurrence editing, the `scheduling` Neo4j calendar and any auto-sync with it, OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`), public-agent exposure, multi-tenant federation. Mail read, full-body read, inbound attachment list/download, reply, delete (to Deleted Items), and compose are supported (`outlook-mail-fetch-body`, `outlook-mail-attachment`, `outlook-mail-reply`, `outlook-mail-delete`, `outlook-mail-otp-extract`, `outlook-mail-send`, `outlook-draft`, `outlook-draft-edit`, `outlook-draft-send`), and the calendar is read plus control. See `platform/plugins/outlook/PLUGIN.md` for the full out-of-scope list.
+Mail move to arbitrary folders / flag, hard (permanent) delete, removing or replacing an attachment already on a draft, ingesting reviewed mail into the business graph (the `email-ingest` analogue), contacts write, recurring-series occurrence editing, the `scheduling` Neo4j calendar and any auto-sync with it, OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`), public-agent exposure, multi-tenant federation. Mail read, full-body read, inbound attachment list/download, reply, delete (to Deleted Items), and compose — all four outbound paths carrying attachments — are supported (`outlook-mail-fetch-body`, `outlook-mail-attachment`, `outlook-mail-reply`, `outlook-mail-delete`, `outlook-mail-otp-extract`, `outlook-mail-send`, `outlook-draft`, `outlook-draft-edit`, `outlook-draft-send`), and the calendar is read plus control. See `platform/plugins/outlook/PLUGIN.md` for the full out-of-scope list.
 
 ---
 # QuickBooks Online

package/payload/platform/plugins/cloudflare/bin/__tests__/cf-token.test.sh

@@ -298,8 +298,12 @@ setup "cfat_master_abc"
 HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
 HOUSE_ENV="$HOUSE_DIR/cloudflare-house.env"
 ( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_ENV" )
+# The caller gate (cases 18-22) admits only the house account, so this case
+# spawns as the house account.
+mkdir -p "$SANDBOX/acme-code/data/accounts/acc123"
+printf '{"role":"house"}\n' > "$SANDBOX/acme-code/data/accounts/acc123/account.json"
 of=$(mktemp); ef=$(mktemp)
-PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
 RC=$?; OUT=$(cat "$of"); ERR=$(cat "$ef"); rm -f "$of" "$ef"
 [ "$RC" -eq 0 ] && ok "house fallback resolves (exit=0)" || { bad "house fallback (exit=$RC)"; echo "  stderr: $ERR" >&2; }
 [ "$OUT" = "CF_PAGES_D1_TOKEN" ] && ok "house fallback stdout is canonical key" || bad "house out='$OUT'"
@@ -327,8 +331,9 @@ teardown
 
 # 15. fail-closed: stripped per-account file and NO house env reachable (no
 #     PLATFORM_ROOT, no CF_HOUSE_ENV) -> non-zero, no mint, and a message that
-#     names the missing credential source. This is the sub-account posture: a
-#     sub-account spawn carries no PLATFORM_ROOT, so it can never self-resolve.
+#     names the missing credential source. Reaching this branch means no house
+#     credential was found at all; the caller gate (cases 18-22) is what decides
+#     whether a reachable house credential may actually be used.
 setup "cfat_master_abc"
 ( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
 of=$(mktemp); ef=$(mktemp)
@@ -345,8 +350,13 @@ setup "cfat_master_abc"
 ( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
 OVERRIDE="$SANDBOX/acme-code/override-house.env"
 ( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$OVERRIDE" )
+# The caller gate admits only the house account, and locates the accounts dir
+# from PLATFORM_ROOT. The PLATFORM_ROOT-derived house path does not exist here,
+# so a pass still proves CF_HOUSE_ENV won.
+mkdir -p "$SANDBOX/acme-code/data/accounts/acc123"
+printf '{"role":"house"}\n' > "$SANDBOX/acme-code/data/accounts/acc123/account.json"
 of=$(mktemp); ef=$(mktemp)
-CF_HOUSE_ENV="$OVERRIDE" CF_BACKOFF_SECONDS=0 bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_HOUSE_ENV="$OVERRIDE" CF_BACKOFF_SECONDS=0 bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
 RC=$?; ERR=$(cat "$ef"); rm -f "$of" "$ef"
 [ "$RC" -eq 0 ] && ok "CF_HOUSE_ENV override resolves (exit=0)" || bad "override (exit=$RC): $ERR"
 grep -q "^CF_PAGES_D1_TOKEN=" "$OVERRIDE" && ok "override env received the minted token" || bad "override not persisted"
@@ -377,5 +387,136 @@ grep -q "^CF_CALENDAR_D1_TOKEN=" "$SECRETS" && ok "calendar-d1 token persisted"
 no_leak "calendar-d1 mint"
 teardown
 
+# ---------------------------------------------------------------------------
+# Caller gate (Task 1646). The house env carries an account-wide master, so the
+# fallback must fire only for the house account. "House" mirrors
+# resolveHouseOrSoleAccountId: account.json role:"house", or the sole account.
+# The gate reads the caller's own account.json under
+# $(dirname $PLATFORM_ROOT)/data/accounts/$ACCOUNT_ID/, which the sandbox
+# layout already matches ($SANDBOX/acme-code/data/accounts/acc123).
+
+# 18. a sub-account caller must NOT resolve the house master: deny, non-zero,
+#     no mint, and nothing persisted to either file.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"
+mkdir -p "$ADIR/acc123" "$ADIR/house1"
+printf '{"role":"client"}\n' > "$ADIR/acc123/account.json"
+printf '{"role":"house"}\n'  > "$ADIR/house1/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+HOUSE_ENV="$HOUSE_DIR/cloudflare-house.env"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_ENV" )
+of=$(mktemp); ef=$(mktemp)
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+RC=$?; OUT=$(cat "$of"); ERR=$(cat "$ef"); rm -f "$of" "$ef"
+[ "$RC" -ne 0 ] && ok "sub-account denied the house master (exit=$RC)" || bad "sub-account NOT denied (exit=$RC)"
+grep -q -- "-X POST" "$SANDBOX/curl.log" && bad "minted for a sub-account" || ok "no mint for a sub-account"
+grep -q "^CF_PAGES_D1_TOKEN=" "$HOUSE_ENV" && bad "sub-account wrote a token to house env" || ok "house env untouched on deny"
+grep -q "^CF_PAGES_D1_TOKEN=" "$SECRETS" && bad "sub-account wrote a token to its own file" || ok "per-account file untouched on deny"
+echo "$ERR" | grep -q "action=deny" && ok "deny lifeline emitted" || bad "no deny lifeline: $ERR"
+echo "$ERR" | grep -q "reason=not-house" && ok "deny lifeline names the reason" || bad "no reason: $ERR"
+no_leak "sub-account deny"
+teardown
+
+# 19. the house account (role:"house") is allowed, preserving house-run hosting.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"; mkdir -p "$ADIR/acc123" "$ADIR/other1"
+printf '{"role":"house"}\n'  > "$ADIR/acc123/account.json"
+printf '{"role":"client"}\n' > "$ADIR/other1/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+HOUSE_ENV="$HOUSE_DIR/cloudflare-house.env"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_ENV" )
+of=$(mktemp); ef=$(mktemp)
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+RC=$?; OUT=$(cat "$of"); ERR=$(cat "$ef"); rm -f "$of" "$ef"
+[ "$RC" -eq 0 ] && ok "house caller allowed (exit=0)" || { bad "house caller denied (exit=$RC)"; echo "  stderr: $ERR" >&2; }
+[ "$OUT" = "CF_PAGES_D1_TOKEN" ] && ok "house caller stdout is canonical key" || bad "house caller out='$OUT'"
+grep -q "^CF_PAGES_D1_TOKEN=" "$HOUSE_ENV" && ok "house caller persisted to house env" || bad "house caller not persisted"
+teardown
+
+# 20. the sole unlabelled account IS the house account (resolveHouseOrSoleAccountId's
+#     second arm) -> allowed.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"; mkdir -p "$ADIR/acc123"
+printf '{"name":"only"}\n' > "$ADIR/acc123/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+HOUSE_ENV="$HOUSE_DIR/cloudflare-house.env"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_ENV" )
+of=$(mktemp); ef=$(mktemp)
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+RC=$?; ERR=$(cat "$ef"); rm -f "$of" "$ef"
+[ "$RC" -eq 0 ] && ok "sole unlabelled account allowed (exit=0)" || bad "sole account denied (exit=$RC): $ERR"
+teardown
+
+# 21. unset ACCOUNT_ID fails closed.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"; mkdir -p "$ADIR/acc123" "$ADIR/house1"
+printf '{"role":"client"}\n' > "$ADIR/acc123/account.json"
+printf '{"role":"house"}\n'  > "$ADIR/house1/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_DIR/cloudflare-house.env" )
+of=$(mktemp); ef=$(mktemp)
+env -u ACCOUNT_ID PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+RC=$?; ERR=$(cat "$ef"); rm -f "$of" "$ef"
+[ "$RC" -ne 0 ] && ok "unset ACCOUNT_ID fails closed (exit=$RC)" || bad "unset ACCOUNT_ID allowed (exit=$RC)"
+echo "$ERR" | grep -q "reason=no-account-id" && ok "no-account-id reason surfaced" || bad "reason: $ERR"
+teardown
+
+# 22. a caller whose account.json is absent fails closed.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"; mkdir -p "$ADIR/acc123" "$ADIR/house1"
+printf '{"role":"house"}\n' > "$ADIR/house1/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_DIR/cloudflare-house.env" )
+of=$(mktemp); ef=$(mktemp)
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+RC=$?; ERR=$(cat "$ef"); rm -f "$of" "$ef"
+[ "$RC" -ne 0 ] && ok "missing account.json fails closed (exit=$RC)" || bad "missing account.json allowed"
+echo "$ERR" | grep -q "reason=no-account-json" && ok "no-account-json reason surfaced" || bad "reason: $ERR"
+teardown
+
+# 23. two role:"house" accounts is corruption: resolveAccountDir returns null
+#     rather than picking one, so the gate denies rather than trusting a
+#     self-declared house.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"; mkdir -p "$ADIR/acc123" "$ADIR/house2"
+printf '{"role":"house"}\n' > "$ADIR/acc123/account.json"
+printf '{"role":"house"}\n' > "$ADIR/house2/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_DIR/cloudflare-house.env" )
+of=$(mktemp); ef=$(mktemp)
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" pages "$SECRETS" >"$of" 2>"$ef"
+RC=$?; ERR=$(cat "$ef"); rm -f "$of" "$ef"
+[ "$RC" -ne 0 ] && ok "two houses fails closed (exit=$RC)" || bad "two houses allowed (exit=$RC)"
+echo "$ERR" | grep -q "reason=multiple-house-accounts" && ok "multiple-house reason surfaced" || bad "reason: $ERR"
+teardown
+
+# 24. the deny message names the scope actually requested, not a fixed list.
+setup "cfat_master_abc"
+( umask 077; printf 'CLOUDFLARE_ACCOUNT_ID=%s\n' "acc123" > "$SECRETS" )
+ADIR="$SANDBOX/acme-code/data/accounts"; mkdir -p "$ADIR/acc123" "$ADIR/house1"
+printf '{"role":"client"}\n' > "$ADIR/acc123/account.json"
+printf '{"role":"house"}\n'  > "$ADIR/house1/account.json"
+HOUSE_DIR="$SANDBOX/acme-code/platform/config"; mkdir -p "$HOUSE_DIR"
+( umask 077; printf 'CLOUDFLARE_API_TOKEN=%s\nCLOUDFLARE_ACCOUNT_ID=%s\n' "cfat_master_abc" "acc123" > "$HOUSE_DIR/cloudflare-house.env" )
+of=$(mktemp); ef=$(mktemp)
+ACCOUNT_ID=acc123 PLATFORM_ROOT="$SANDBOX/acme-code/platform" CF_BACKOFF_SECONDS=0 \
+  bash "$HELPER" dns "$SECRETS" >"$of" 2>"$ef"
+RC=$?; ERR=$(cat "$ef"); rm -f "$of" "$ef"
+echo "$ERR" | grep -q "scope=dns" && ok "deny lifeline names scope=dns" || bad "lifeline scope: $ERR"
+echo "$ERR" | grep -qF "'dns' scope" && ok "deny message names the dns scope" || bad "deny message scope: $ERR"
+teardown
+
 echo "----"; echo "PASS=$PASS FAIL=$FAIL"
 [ "$FAIL" -eq 0 ]