@rubytech/create-realagent-code 0.1.579 → 0.1.580

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.579",
+  "version": "0.1.580",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/lib/telegram-media/dist/index.d.ts

@@ -0,0 +1,45 @@
+/** Telegram's own reason when it gives one, else a description of the HTTP
+ *  outcome. Never a limit this code restates: `getFile` refuses above 20 MB and
+ *  says so, and a size pre-check here would be a second authority for that. */
+export declare function refusalReason(body: unknown, status: number): string;
+/** Extension from Telegram's own `file_path`, else the mimetype's subtype, else
+ *  `bin`. Telegram's path already carries the real extension for every type that
+ *  has one, so it leads. */
+export declare function extensionFor(filePath: string, mimetype: string | undefined): string;
+/** An identifier is not a path component: a value carrying `../` escapes the
+ *  media directory, and the agent is then told to Read whatever came back.
+ *  Escape here rather than reason about who can reach the endpoint. */
+export declare function pathSafe(s: string): string;
+export type FileResolution = {
+    ok: true;
+    filePath: string;
+} | {
+    ok: false;
+    failure: string;
+};
+/** Hop one. Exchanges a `file_id` for Telegram's server-side `file_path`.
+ *  Never throws: a rejected fetch becomes a failure reason, because both
+ *  callers treat a missing file as a fact to report, not an exception. */
+export declare function resolveTelegramFile(input: {
+    token: string;
+    fileId: string;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<FileResolution>;
+export type FileDownload = {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    failure: string;
+};
+/** Hop two. Fetches the bytes from the file host and writes them to `destPath`,
+ *  creating its directory. Never throws, for the same reason as hop one. */
+export declare function downloadTelegramFile(input: {
+    token: string;
+    filePath: string;
+    destPath: string;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<FileDownload>;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/telegram-media/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA;;+EAE+E;AAC/E,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAInE;AAED;;4BAE4B;AAC5B,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAMnF;AAED;;uEAEuE;AACvE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1C;AAED,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F;;0EAE0E;AAC1E,wBAAsB,mBAAmB,CAAC,KAAK,EAAE;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,cAAc,CAAC,CAgB1B;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF;4EAC4E;AAC5E,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,YAAY,CAAC,CAexB"}

package/payload/platform/lib/telegram-media/dist/index.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refusalReason = refusalReason;
+exports.extensionFor = extensionFor;
+exports.pathSafe = pathSafe;
+exports.resolveTelegramFile = resolveTelegramFile;
+exports.downloadTelegramFile = downloadTelegramFile;
+/**
+ * The two HTTPS hops Telegram requires to fetch a file, extracted from Task
+ * 2489's inbound downloader so both trees run one implementation.
+ *
+ * `platform/plugins/telegram/mcp/src/lib/account-write.ts:21-24` records that
+ * the plugin cannot import from `platform/ui/app`, and that the standing
+ * workaround is deliberate duplication plus an agreement test. `platform/lib/`
+ * is the surface both sides already import, so a shared module removes the need
+ * for a third duplicate.
+ *
+ * This module holds NO item types, NO loop and NO logging. The channel layer
+ * and the MCP tool name their files differently and log differently; only the
+ * transfer is common.
+ *
+ * NEVER log a token. Both functions take one and neither returns it.
+ */
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const TELEGRAM_API = "https://api.telegram.org";
+/** Telegram's own reason when it gives one, else a description of the HTTP
+ *  outcome. Never a limit this code restates: `getFile` refuses above 20 MB and
+ *  says so, and a size pre-check here would be a second authority for that. */
+function refusalReason(body, status) {
+    const b = body;
+    if (typeof b?.description === "string" && b.description.length > 0)
+        return b.description;
+    return `telegram returned ${status}`;
+}
+/** Extension from Telegram's own `file_path`, else the mimetype's subtype, else
+ *  `bin`. Telegram's path already carries the real extension for every type that
+ *  has one, so it leads. */
+function extensionFor(filePath, mimetype) {
+    const fromPath = filePath.split("/").pop()?.split(".").slice(1).pop();
+    if (fromPath && /^[a-z0-9]+$/i.test(fromPath))
+        return fromPath;
+    const sub = mimetype?.split("/").pop()?.split(";")[0]?.trim();
+    if (sub && /^[a-z0-9]+$/i.test(sub))
+        return sub;
+    return "bin";
+}
+/** An identifier is not a path component: a value carrying `../` escapes the
+ *  media directory, and the agent is then told to Read whatever came back.
+ *  Escape here rather than reason about who can reach the endpoint. */
+function pathSafe(s) {
+    return s.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+/** Hop one. Exchanges a `file_id` for Telegram's server-side `file_path`.
+ *  Never throws: a rejected fetch becomes a failure reason, because both
+ *  callers treat a missing file as a fact to report, not an exception. */
+async function resolveTelegramFile(input) {
+    const doFetch = input.fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(`${TELEGRAM_API}/bot${input.token}/getFile?file_id=${encodeURIComponent(input.fileId)}`, input.signal ? { signal: input.signal } : {});
+        const body = (await res.json());
+        const filePath = body?.result?.file_path;
+        if (!res.ok || body?.ok !== true || typeof filePath !== "string" || filePath.length === 0) {
+            return { ok: false, failure: refusalReason(body, res.status) };
+        }
+        return { ok: true, filePath };
+    }
+    catch (err) {
+        return { ok: false, failure: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** Hop two. Fetches the bytes from the file host and writes them to `destPath`,
+ *  creating its directory. Never throws, for the same reason as hop one. */
+async function downloadTelegramFile(input) {
+    const doFetch = input.fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(`${TELEGRAM_API}/file/bot${input.token}/${input.filePath}`, input.signal ? { signal: input.signal } : {});
+        if (!res.ok)
+            return { ok: false, failure: `telegram returned ${res.status}` };
+        const body = Buffer.from(await res.arrayBuffer());
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(input.destPath), { recursive: true });
+        await (0, promises_1.writeFile)(input.destPath, body);
+        return { ok: true, bytes: body.length };
+    }
+    catch (err) {
+        return { ok: false, failure: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/telegram-media/dist/index.js.map

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

package/payload/platform/lib/telegram-media/src/__tests__/telegram-media.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  resolveTelegramFile,
+  downloadTelegramFile,
+  extensionFor,
+  pathSafe,
+  refusalReason,
+} from "../index.js";
+
+function jsonFetch(status: number, body: unknown): typeof fetch {
+  return (async () =>
+    new Response(JSON.stringify(body), { status })) as unknown as typeof fetch;
+}
+
+describe("resolveTelegramFile", () => {
+  it("returns Telegram's file_path on success", async () => {
+    const out = await resolveTelegramFile({
+      token: "T",
+      fileId: "F",
+      fetchImpl: jsonFetch(200, { ok: true, result: { file_path: "photos/f.jpg" } }),
+    });
+    expect(out).toEqual({ ok: true, filePath: "photos/f.jpg" });
+  });
+
+  it("returns Telegram's own description when it refuses", async () => {
+    const out = await resolveTelegramFile({
+      token: "T",
+      fileId: "F",
+      fetchImpl: jsonFetch(400, { ok: false, description: "file is too big" }),
+    });
+    expect(out).toEqual({ ok: false, failure: "file is too big" });
+  });
+
+  it("describes the HTTP outcome when Telegram gives no description", async () => {
+    const out = await resolveTelegramFile({
+      token: "T",
+      fileId: "F",
+      fetchImpl: jsonFetch(502, {}),
+    });
+    expect(out).toEqual({ ok: false, failure: "telegram returned 502" });
+  });
+
+  it("puts the file_id in the query, never the token in the result", async () => {
+    let seen = "";
+    const spy = (async (url: string) => {
+      seen = url;
+      return new Response(JSON.stringify({ ok: true, result: { file_path: "p/f.jpg" } }));
+    }) as unknown as typeof fetch;
+    await resolveTelegramFile({ token: "SECRET", fileId: "a b/c", fetchImpl: spy });
+    expect(seen).toContain("file_id=a%20b%2Fc");
+  });
+});
+
+describe("downloadTelegramFile", () => {
+  it("writes the bytes and reports the count", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "tgm-"));
+    const dest = join(dir, "out.jpg");
+    const fetchImpl = (async () =>
+      new Response(new Uint8Array([1, 2, 3, 4]))) as unknown as typeof fetch;
+    const out = await downloadTelegramFile({
+      token: "T",
+      filePath: "p/f.jpg",
+      destPath: dest,
+      fetchImpl,
+    });
+    expect(out).toEqual({ ok: true, bytes: 4 });
+    expect(readFileSync(dest).length).toBe(4);
+  });
+
+  it("reports the status when the file host refuses", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "tgm-"));
+    const fetchImpl = (async () => new Response("", { status: 404 })) as unknown as typeof fetch;
+    const out = await downloadTelegramFile({
+      token: "T",
+      filePath: "p/f.jpg",
+      destPath: join(dir, "out.jpg"),
+      fetchImpl,
+    });
+    expect(out).toEqual({ ok: false, failure: "telegram returned 404" });
+  });
+});
+
+describe("helpers", () => {
+  it("prefers the extension Telegram's own path carries", () => {
+    expect(extensionFor("photos/file_1.jpg", "image/png")).toBe("jpg");
+  });
+
+  it("falls back to the mimetype subtype, then to bin", () => {
+    expect(extensionFor("photos/file_1", "image/png")).toBe("png");
+    expect(extensionFor("photos/file_1", undefined)).toBe("bin");
+  });
+
+  it("strips every character that is not a safe path component", () => {
+    expect(pathSafe("../../etc/passwd")).toBe("______etc_passwd");
+  });
+
+  it("prefers Telegram's description over the status", () => {
+    expect(refusalReason({ description: "nope" }, 400)).toBe("nope");
+    expect(refusalReason(null, 500)).toBe("telegram returned 500");
+  });
+});

package/payload/platform/lib/telegram-media/src/index.ts

@@ -0,0 +1,102 @@
+/**
+ * The two HTTPS hops Telegram requires to fetch a file, extracted from Task
+ * 2489's inbound downloader so both trees run one implementation.
+ *
+ * `platform/plugins/telegram/mcp/src/lib/account-write.ts:21-24` records that
+ * the plugin cannot import from `platform/ui/app`, and that the standing
+ * workaround is deliberate duplication plus an agreement test. `platform/lib/`
+ * is the surface both sides already import, so a shared module removes the need
+ * for a third duplicate.
+ *
+ * This module holds NO item types, NO loop and NO logging. The channel layer
+ * and the MCP tool name their files differently and log differently; only the
+ * transfer is common.
+ *
+ * NEVER log a token. Both functions take one and neither returns it.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+const TELEGRAM_API = "https://api.telegram.org";
+
+/** Telegram's own reason when it gives one, else a description of the HTTP
+ *  outcome. Never a limit this code restates: `getFile` refuses above 20 MB and
+ *  says so, and a size pre-check here would be a second authority for that. */
+export function refusalReason(body: unknown, status: number): string {
+  const b = body as { description?: unknown } | null;
+  if (typeof b?.description === "string" && b.description.length > 0) return b.description;
+  return `telegram returned ${status}`;
+}
+
+/** Extension from Telegram's own `file_path`, else the mimetype's subtype, else
+ *  `bin`. Telegram's path already carries the real extension for every type that
+ *  has one, so it leads. */
+export function extensionFor(filePath: string, mimetype: string | undefined): string {
+  const fromPath = filePath.split("/").pop()?.split(".").slice(1).pop();
+  if (fromPath && /^[a-z0-9]+$/i.test(fromPath)) return fromPath;
+  const sub = mimetype?.split("/").pop()?.split(";")[0]?.trim();
+  if (sub && /^[a-z0-9]+$/i.test(sub)) return sub;
+  return "bin";
+}
+
+/** An identifier is not a path component: a value carrying `../` escapes the
+ *  media directory, and the agent is then told to Read whatever came back.
+ *  Escape here rather than reason about who can reach the endpoint. */
+export function pathSafe(s: string): string {
+  return s.replace(/[^A-Za-z0-9_-]/g, "_");
+}
+
+export type FileResolution = { ok: true; filePath: string } | { ok: false; failure: string };
+
+/** Hop one. Exchanges a `file_id` for Telegram's server-side `file_path`.
+ *  Never throws: a rejected fetch becomes a failure reason, because both
+ *  callers treat a missing file as a fact to report, not an exception. */
+export async function resolveTelegramFile(input: {
+  token: string;
+  fileId: string;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+}): Promise<FileResolution> {
+  const doFetch = input.fetchImpl ?? fetch;
+  try {
+    const res = await doFetch(
+      `${TELEGRAM_API}/bot${input.token}/getFile?file_id=${encodeURIComponent(input.fileId)}`,
+      input.signal ? { signal: input.signal } : {},
+    );
+    const body = (await res.json()) as { ok?: boolean; result?: { file_path?: string } };
+    const filePath = body?.result?.file_path;
+    if (!res.ok || body?.ok !== true || typeof filePath !== "string" || filePath.length === 0) {
+      return { ok: false, failure: refusalReason(body, res.status) };
+    }
+    return { ok: true, filePath };
+  } catch (err) {
+    return { ok: false, failure: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export type FileDownload = { ok: true; bytes: number } | { ok: false; failure: string };
+
+/** Hop two. Fetches the bytes from the file host and writes them to `destPath`,
+ *  creating its directory. Never throws, for the same reason as hop one. */
+export async function downloadTelegramFile(input: {
+  token: string;
+  filePath: string;
+  destPath: string;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+}): Promise<FileDownload> {
+  const doFetch = input.fetchImpl ?? fetch;
+  try {
+    const res = await doFetch(
+      `${TELEGRAM_API}/file/bot${input.token}/${input.filePath}`,
+      input.signal ? { signal: input.signal } : {},
+    );
+    if (!res.ok) return { ok: false, failure: `telegram returned ${res.status}` };
+    const body = Buffer.from(await res.arrayBuffer());
+    await mkdir(dirname(input.destPath), { recursive: true });
+    await writeFile(input.destPath, body);
+    return { ok: true, bytes: body.length };
+  } catch (err) {
+    return { ok: false, failure: err instanceof Error ? err.message : String(err) };
+  }
+}

package/payload/platform/lib/telegram-media/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/telegram-media/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    globals: false,
+    include: ["src/__tests__/**/*.test.ts"],
+  },
+});

package/payload/platform/package.json

@@ -10,8 +10,8 @@
     "pdf-lib": "^1.17.1"
   },
   "scripts": {
-    "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
-    "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json",
+    "build": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/learning-constants/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && tsc -p services/telegram-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/account-schema-regions/tsconfig.json && tsc -p lib/account-ingest-token/tsconfig.json && tsc -p lib/models/tsconfig.json && tsc -p lib/agent-slug/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/account-scope/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/ledger-core/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/active-rules/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p lib/storage-broker/tsconfig.json && tsc -p lib/routine-templates/tsconfig.json && tsc -p lib/agent-dispatch-rule/tsconfig.json && tsc -p lib/shared-folder/tsconfig.json && tsc -p lib/canonical-instant/tsconfig.json && tsc -p lib/dispatch-read/tsconfig.json && tsc -p lib/dispatch-write/tsconfig.json && tsc -p lib/telegram-media/tsconfig.json",
     "gen:canonical-tools": "node scripts/generate-canonical-tool-names.mjs",
     "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
     "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",

package/payload/platform/plugins/admin/PLUGIN.md

@@ -275,9 +275,9 @@ Tools are available via the `admin` MCP server.
 - `hooks/quote-render-gate.sh` — **PreToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** Makes the deterministic quote-render path the only route a client-facing quote PDF can reach a customer. **Scope** is three path shapes, all resolved against the account dir: `memory/users/<phone>/documents/quote-<jobId>[-breakdown].pdf`, `jobs/<jobId>/quote/<anything>.pdf`, and `jobs/<jobId>/Quotations/<anything>.pdf`. `jobs/<jobId>/pricing/` is excluded — it holds the internal priced breakdown, excluded with the admin-scope internal view. **Decision** is receipt *identity*, not receipt existence: the gate resolves the PDF's sibling HTML (`.pdf`→`.html`), sha256s it, and requires a match against the sha256 of a file named by `filed.quote` or `filed.breakdown` in `quoting/jobs/<jobId>/render-receipt.json`. `filed.internal` is not client-facing and never matches. Comparing content rather than paths keeps an operator copy of a rendered document passing while hand-authored content fails. A missing sibling HTML blocks: the pipeline files the PDF beside the HTML it printed from, so no local source is no proof of renderer origin. Existence alone was not enough — on the 2026-08-05 bypass the job's figures were rewritten after the render and the delivered document was written later still, so a stale receipt would have authorised the print. **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=<not-receipt-filed|no-source-html|bad-jobid>`. Every non-quote PDF — brochures, works orders, invoices, the admin-scope internal view — passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `browser-pdf-save` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated PDFs.
 - `hooks/quote-engine-gate.sh` — **PreToolUse matcher=`Bash`** (a third command on the same `Bash` matcher as `archive-ingest-surface-gate` and `fs-schema-guard-bash-pre`, any exit 2 blocks). Makes the deterministic `quote-engine-run` / `quote-render` tools the only route the account's persisted quoting scripts can run. Blocks (exit 2) a `Bash` `command` that executes `quoting/engine.mjs` or `quoting/render.mjs` directly — the pricing and render scripts must run through their MCP tools, which apply the reconcile / margin-leak / link-liveness gates and write the figures and render receipts. A hand-run `node quoting/engine.mjs` (the SiteDesk 2026-07-25 bypass: a repricing dispatched to content-producer that ran the engine by hand and re-rendered off the deterministic path) skips all of that, so it is refused. It fires only on an execution (a JS runtime invoking the script, or the script run at command position); a read or inspect of the file (`cat`/`grep`/`git diff quoting/engine.mjs`) and every unrelated `Bash` command pass at exit 0. A `mode=verify` reproduction is gated too — it must also run through `quote-engine-run`, so a hand-run `node quoting/engine.mjs mode=verify` is refused. Known fail-open gap (accepted, consistent with the soft posture): a `cd quoting && node engine.mjs` drops the `quoting/` prefix and is not matched. **Block message:** `Blocked: the quoting engine and render scripts must run through their tools, not directly. Use the quote-engine-run tool to price a job (it files the figures) and the quote-render tool to produce the documents (it files them behind the reconcile, margin-leak and link-liveness gates). Running quoting/engine.mjs or quoting/render.mjs by hand skips those gates and files no receipt.` **Log line** (stderr, on a block): `[quote-engine] op=bypass reason=direct-script-exec`. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `Bash` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated commands.
 - `hooks/quote-pdf-bash-gate.sh` — **PreToolUse matcher=`Bash`.** Closes the Bash route to a client quote PDF. `quote-render-gate` refuses a hand-authored quote at `browser-pdf-save`, but an agent holding `Bash` reaches the same outcome with any HTML-to-PDF converter and meets no control at all (`content-producer` holds `Bash`, `Write`, `Edit` and `browser-pdf-save`; `quote-engine-gate` refuses only execution of the two persisted quoting scripts). Blocks (exit 2) a command that names both an `.html` under a gated quote path — `memory/users/<phone>/documents/`, `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` — and a `.pdf`. The match is structural on the paths, never on the converter's name, so `wkhtmltopdf`, `chromium --print-to-pdf` and `weasyprint` are covered by the same rule. A read that names no PDF (`cat q.html`) passes, and `jobs/<jobId>/pricing/` is never gated. **Block message:** `Blocked: a client quote PDF must come from the quote-render tool, not from a converter run by hand. Run quote-render for this job — it files the document and its render receipt — then print the client HTML path it returns.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=bash-pdf-production`. **Fail-open** on an uninspectable call.
-- `hooks/quote-path-write-gate.sh` — **PreToolUse matcher=`Write` / `Edit` / `MultiEdit` / `NotebookEdit`.** The roster safeguard expressed as a capability rather than a removal. Blocks (exit 2) a write whose target is under `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` or `quoting/templates/` when the calling agent's card does not grant `quote-render`. `jobs/<jobId>/pricing/` is excluded — the internal priced breakdown is not a client quote artefact — and every other deliverable the agent owns (works orders, heritage statements, survey sheets, drawing registers, trial-pit records, invoice stamps) is untouched. **Caller identity is `agent_type` from the hook envelope**, which Claude Code sets when a hook fires inside a subagent; `MAXY_SPECIALIST` is not usable, since it is stamped only when a specialist is spawned as its own PTY process and reads empty for the native Agent-tool subagents this gate exists to stop. **Card lookup spans both registration families** — the per-account registry (`<accountDir>/.claude/agents/`, `<accountDir>/specialists/agents/`), `$CLAUDE_CONFIG_DIR/agents/`, and the plugin roots (`$(dirname $PLATFORM_ROOT)/premium-plugins/*/agents/`, `$PLATFORM_ROOT/plugins/*/agents/`) — matching on frontmatter `name:` as well as filename, because the quoter's card is filed as `sitedesk--quoter.md` and declares `name: quoter`. Omitting the premium root would block the quoter itself. A write from the main conversation carries no `agent_type` and the admin seat holds no `quote-render`, so it is refused too: no part of a client quote document is another agent's work, the admin's included. **Block message:** `Blocked: quote documents and quote templates are the quoter's work. Dispatch the quoter for this change; it produces the document through the quote-render tool, which files it with its render receipt.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=<quote-path-write-without-render-tool|quote-path-write-unresolved-agent>`. **Fail-open** on an uninspectable envelope.
+- `hooks/quote-path-write-gate.sh` — **PreToolUse matcher=`Write` / `Edit` / `MultiEdit` / `NotebookEdit`, and it acts on all four.** A notebook edit is read from `notebook_path`; every other write tool from `file_path`. The roster safeguard expressed as a capability rather than a removal. Blocks (exit 2) a write whose target is under `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` or `quoting/templates/` when the calling agent's card does not grant `quote-render`. `jobs/<jobId>/pricing/` is excluded — the internal priced breakdown is not a client quote artefact — and every other deliverable the agent owns (works orders, heritage statements, survey sheets, drawing registers, trial-pit records, invoice stamps) is untouched. **Caller identity is `agent_type` from the hook envelope**, which Claude Code sets when a hook fires inside a subagent; `MAXY_SPECIALIST` is not usable, since it is stamped only when a specialist is spawned as its own PTY process and reads empty for the native Agent-tool subagents this gate exists to stop. **Card lookup spans both registration families** — the per-account registry (`<accountDir>/.claude/agents/`, `<accountDir>/specialists/agents/`), `$CLAUDE_CONFIG_DIR/agents/`, and the plugin roots (`$(dirname $PLATFORM_ROOT)/premium-plugins/*/agents/`, `$PLATFORM_ROOT/plugins/*/agents/`) — matching on frontmatter `name:` as well as filename, because the quoter's card is filed as `sitedesk--quoter.md` and declares `name: quoter`. Omitting the premium root would block the quoter itself. A write from the main conversation carries no `agent_type` and the admin seat holds no `quote-render`, so it is refused too: no part of a client quote document is another agent's work, the admin's included. **Block message:** `Blocked: quote documents and quote templates are the quoter's work. Dispatch the quoter for this change; it produces the document through the quote-render tool, which files it with its render receipt.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=<quote-path-write-without-render-tool|quote-path-write-unresolved-agent>`. **Fail-open** on an uninspectable envelope.
 - `hooks/html-structure-gate.sh` — **PreToolUse matcher=`Write` / `Edit` / `MultiEdit`.** Refuses a write that would produce an HTML document with a `<style>` element opened inside another one, or with more openers than closers. The fault is not cosmetic: HTML parses style content as raw text, so the **first** `</style>` closes the outer element — everything after it becomes body content and renders as visible text, and the rule immediately after the stray opener is eaten as part of an invalid selector. One fault, two symptoms, both seen on a client quotation that went out on 2026-07-24 and was noticed on 2026-08-07. **Detector, three rules:** HTML comments are stripped first, each replaced by its own newlines, so a `<style>` inside `<!-- … -->` is not scanned and line numbers do not shift (two account templates carry one and are clean; a comment-blind detector reports both); `<style…>`/`</style…>` are then walked case-insensitively tracking depth, and an opener seen at depth > 0 is the fault; a CSS comment protects an **opener** but never a **closer**, because style content is raw text to the HTML parser so `</style>` terminates the element wherever it appears, while an opener is never a parse event inside a stylesheet — it is text the CSS parser reads as an invalid selector, and inside `/* … */` it is discarded (the shipped property-brochure `template.html` and `index.html` document their brand-token override slot exactly that way and are correct); at end of input openers must equal closers, and an unmatched opener is reported at its own line. The same three rules are implemented in the session manager's `html-structure-census`, which walks what is already on disk. **It walks the document the call would produce, not the fragment** — for `Write` that is `content`; for `Edit`/`MultiEdit` the on-disk file is read and the replacements applied in memory first, because the balance rule would otherwise refuse every partial edit and a nested opener whose outer `<style>` is already on disk would pass. **Scope is the whole account with an exclusion list, never a bucket list**: every `.html`/`.htm` resolving inside the account dir (this hook's cwd, as in `fs-schema-guard.sh`) except under `node_modules/`, `.wrangler/`, `.tool/`, `.trash/`. A bucket list is what let the live document through — it sat under `sites/<project>/public/`, which no quote bucket covers. `NotebookEdit` is deliberately not registered: a notebook is not a client document. **Block message:** `Blocked: this document opens a <style> element inside another one (line N). The browser closes the outer element at the first </style>, so the rest of the stylesheet renders as visible text on the page and the rule after the stray opener is discarded. Put the block in the body as its own <style> element, or merge its rules into the one already open.` **Log line:** `[html-structure-gate] op=refuse account=<id8> file=<json-quoted-path> line=<n>`, a direct append to `<logDir>/server.log` resolved by the `LOG_DIR` → `CLAUDE_SESSION_MANAGER_PERSIST_DIR/logs` → `<cwd>/logs` ladder, not a stderr echo. There is deliberately **no hard-coded brand fallback**: four brands are co-resident on the laptop, each with its own `~/.<brand>/logs`, so a literal would file this account's path in a sibling brand's `server.log`; when no rung resolves the line is dropped and the refusal still blocks. The path is JSON-quoted because these filenames carry spaces and a bare `key=value` line truncates at the first space. **Fail-open** on an uninspectable envelope (tty / empty stdin / unreadable target / unparseable edit).
-- `hooks/fs-schema-guard.sh` — **PreToolUse, registered on `Write` / `Edit` / `MultiEdit` / `NotebookEdit`; acts on `Write`, `Edit` and `NotebookEdit` only** — its tool dispatch has no `MultiEdit` arm, so a `MultiEdit` exits 0 unread and reaches every path this hook otherwise fences (verified by direct invocation, 2026-08-07; `archive-ingest-surface-gate.sh` has the same registered-but-unhandled gap and is tracked with it). The account-dir path guard. It enforces the seeded file schema (`<accountDir>/SCHEMA.md`) on this account's own layout — allowed top-level set, the account-machinery and declared-file deny fences, bucket depth, and the lowercase name convention — and, before any of that, refuses a target that resolves inside a **sibling account** under the same accounts root, for every session including a house-scoped one. Containment is decided on the resolved path, so a symlink planted under this account that points into a sibling is refused rather than read as an own-account path, and a sibling counts as an account only when it carries `account.json`. **Log line** (stderr, on a block): `[fs-guard] blocked path=<path> reason=<top-level|account-machinery|declared-file|over-deep|bad-name|cross-account>`, with `target=<acct8>` added on the cross-account reason. A cross-account block **also records the refused absolute path** in a per-session ledger under the tmpdir (`maxy-fsguard-refused-<sessionId>.txt`), which `fs-schema-guard-bash-post.sh` reads; recording is best-effort and never changes the verdict, and a call carrying no `session_id` records nothing. **Fail-closed** on an uninspectable call (tty / empty stdin); **fail-open** on a missing or empty schema, which governs this account's own layout only and never opens the cross-account path.
+- `hooks/fs-schema-guard.sh` — **PreToolUse, registered on and acting on `Write` / `Edit` / `MultiEdit` / `NotebookEdit`.** A notebook edit is read from `notebook_path`; every other write tool from `file_path`. The account-dir path guard. It enforces the seeded file schema (`<accountDir>/SCHEMA.md`) on this account's own layout — allowed top-level set, the account-machinery and declared-file deny fences, bucket depth, and the lowercase name convention — and, before any of that, refuses a target that resolves inside a **sibling account** under the same accounts root, for every session including a house-scoped one. Containment is decided on the resolved path, so a symlink planted under this account that points into a sibling is refused rather than read as an own-account path, and a sibling counts as an account only when it carries `account.json`. **Log line** (stderr, on a block): `[fs-guard] blocked path=<path> reason=<top-level|account-machinery|declared-file|over-deep|bad-name|cross-account>`, with `target=<acct8>` added on the cross-account reason. A cross-account block **also records the refused absolute path** in a per-session ledger under the tmpdir (`maxy-fsguard-refused-<sessionId>.txt`), which `fs-schema-guard-bash-post.sh` reads; recording is best-effort and never changes the verdict, and a call carrying no `session_id` records nothing. **Fail-closed** on an uninspectable call (tty / empty stdin); **fail-open** on a missing or empty schema, which governs this account's own layout only and never opens the cross-account path.
 - `hooks/fs-schema-guard-bash-pre.sh` — **PreToolUse matcher=`Bash`.** Records the account root's immediate top-level entry names before the command runs, into `maxy-fsguard-snapshot-<sessionId>.txt` under the tmpdir, so the PostToolUse twin can flag only the entries **this** command created rather than the legacy backlog. It inspects account-root state and never the command string. Always exits 0 — a snapshot that cannot be taken must not block a command, and blocking is the post hook's job.
 - `hooks/fs-schema-guard-bash-post.sh` — **PostToolUse matcher=`Bash`.** Two independent checks under one exit. **Strays:** diffing the account root against the pre-snapshot, an entry that appeared this command and is not in the allowed set is `[fs-guard-bash] stray path=<name> reason=top-level`, and a badly-named new child of a bucket created this command is `reason=bad-name`. **Evasion:** every path `fs-schema-guard.sh` refused as cross-account in this session that now **exists on disk** was written by some other route after the refusal, and is reported as `[fs-guard-bash] evaded path=<path> reason=cross-account target=<acct8>` — the pair to the guard's own `blocked` line on the same path and target, so a bypass is two grep-able lines rather than a transcript to read. A reported path is dropped from the ledger, so one evasion reports once. The path was refused in this session by this session's own hook, so existence afterwards is attribution: no sibling directory is walked and no mtime is read. The stray fail-opens (missing snapshot, empty allowed set) govern the stray check alone and do not gate the evasion check, because the path guard refuses a sibling target before it parses any schema — an account with no `SCHEMA.md`, and a session whose pre-hook failed open, can each still hold a recorded refusal. A missing or unreadable ledger reports nothing. **No filesystem mutation:** PostToolUse runs after the command, so it reports and never repairs; the standing account-dir reconcile is the net for anything the agent ignores.
 - `hooks/preference-consult-gate.sh` — **PreToolUse gate on customer-facing document deliverables.** Registered against `mcp__plugin_browser_browser__browser-pdf-save` (a second command on the same matcher as `quote-render-gate`, either exit 2 blocks) and against the email/Outlook send tools plus `SendUserFile`. It fires only in the document-deliverable shape: a `browser-pdf-save` or `SendUserFile` whose path is under `memory/users/<phone>/documents/` (or a `SendUserFile` of a `.pdf`/`.html`/`.docx`), and `email-send`/`email-reply`/`email-draft-send`/`outlook-mail-send`/`outlook-mail-reply`/`outlook-draft-send` carrying a non-empty `attachments`. For a gated call it reads the session transcript (`transcript_path`) and blocks (exit 2) when no `profile-read` tool call ran after the last user message, because the account's layer-2 `Preference` records (signature policy, header, naming, styling) were not consulted this turn, the exact miss that dropped a customer signature on a delivered document. **Block message:** `Blocked: this customer document is about to go out without the account's saved preferences being checked this turn. Those records hold the signature, header, naming and styling rules. Run profile-read for this account, apply anything relevant, then send again.` **Log line** (stderr): `[preference-gate] op=bypass tool=<name> detail=no profile-read this turn` on a block, `op=allow tool=<name> consulted=true` on an allowed document deliverable. Every non-document tool/shape, and every casual channel reply or plain-text email, passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / transcript missing or unreadable). Scope decision: the gate fires on document deliverables only, not on every send, so it never blocks routine chat. The standing reconcile counterpart for stranded `output/` deliverables is filed as a follow-up task.

package/payload/platform/plugins/admin/hooks/__tests__/archive-ingest-surface-gate.test.sh

@@ -18,6 +18,8 @@
 #     D. PreToolUse mcp__memory__memory-archive-write w/ archiveType=linkedin-connections → ALLOWED
 #     E. PreToolUse Bash invoking conversation-archive-ingest.sh → ALLOWED
 #     F. Default-allow emits a [archive-ingest-gate] decision=allow log line
+#     G. PreToolUse MultiEdit on a plugin lib/ path → BLOCKED
+#     H. PreToolUse NotebookEdit on a plugin lib/ path → BLOCKED (notebook_path)
 
 set -u
 
@@ -112,6 +114,26 @@ run_case "BYPASS: nested file_path in old_string + top-level file_path in lib/*
   '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/repo/platform/plugins/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts","old_string":"file_path:/safe/path","new_string":"x"}}' \
   2
 
+# The gate is registered on the MultiEdit matcher, so the plugin-source fence
+# must reach it. Until this arm existed a MultiEdit exited 0 unread.
+run_case "MultiEdit on platform/plugins/*/lib/* → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"MultiEdit","tool_input":{"file_path":"/Users/x/repo/platform/plugins/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts","edits":[{"old_string":"a","new_string":"b"}]}}' \
+  2
+
+run_case "MultiEdit on README.md → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"MultiEdit","tool_input":{"file_path":"/Users/x/repo/README.md","edits":[{"old_string":"a","new_string":"b"}]}}' \
+  0
+
+# A notebook edit carries notebook_path, not file_path. The arm named the tool
+# and read the wrong field, so the fence never reached a single one of them.
+run_case "NotebookEdit on platform/plugins/*/lib/* → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"NotebookEdit","tool_input":{"notebook_path":"/Users/x/repo/platform/plugins/memory/mcp/src/lib/probe.ipynb","new_source":"x"}}' \
+  2
+
+run_case "NotebookEdit on a benign path → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"NotebookEdit","tool_input":{"notebook_path":"/Users/x/repo/notes/scratch.ipynb","new_source":"x"}}' \
+  0
+
 run_case "PreToolUse Bash invoking conversation-archive-ingest.sh → ALLOWED" \
   '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bash platform/plugins/memory/bin/conversation-archive-ingest.sh /tmp/chat.zip --source whatsapp --owner-element-id 4:abc:1 --participant-person-ids 4:abc:2 --scope admin"}}' \
   0

package/payload/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh

@@ -18,6 +18,7 @@
 #  14. Same, from an account with no SCHEMA.md             -> BLOCK cross-account
 #  15. Write into a sibling dir with no account.json       -> ALLOW (not an account)
 #  16. Symlink under this account resolving into a sibling -> BLOCK cross-account
+#  17. MultiEdit reaches every fence and the refusal ledger -> BLOCK / record
 set -u
 
 HOOK="$(cd "$(dirname "$0")/.." && pwd)/fs-schema-guard.sh"
@@ -253,6 +254,29 @@ run_case "symlink into a sibling blocked" \
   "$(mkenv Edit file_path "$ACCT_OWN/documents/escape/index.html")" \
   2 'reason=cross-account target=5e99bba5' "$ACCT_OWN"
 
+# A MultiEdit carries file_path exactly as an Edit does, and the hook is
+# registered on that matcher, so every fence above must reach it. Until this arm
+# existed a MultiEdit exited 0 unread and every one of them did not.
+run_case "xacct multiedit blocked" \
+  "$(mkenv MultiEdit file_path "$ACCT_SIB/sites/public/index.html")" \
+  2 'reason=cross-account target=5e99bba5' "$ACCT_OWN"
+
+run_case "own account multiedit allowed" \
+  "$(mkenv MultiEdit file_path "$ACCT_OWN/documents/a.pdf")" \
+  0 "" "$ACCT_OWN"
+
+run_case "declared multiedit blocks" \
+  "$(mkenv MultiEdit file_path 'wa-channel-bindings.json')" \
+  2 "reason=declared-file" "$ACCT_F"
+
+run_case "machinery multiedit blocks" \
+  "$(mkenv MultiEdit file_path 'account.json')" \
+  2 "reason=account-machinery"
+
+run_case "over-deep multiedit blocks" \
+  "$(mkenv MultiEdit file_path 'projects/acme/deploy/sources/a.txt')" \
+  2 "reason=over-deep"
+
 # Refusal ledger: a refused cross-account path is recorded so the Bash post-hook
 # can report it if a later shell command lands it anyway. Isolated tmp so the run
 # never collides with a live session's ledger.
@@ -311,6 +335,16 @@ run_case_ledger "ledger own-account allowed" \
   0 "" "$ACCT_OWN"
 assert_no_ledger "ledger own-account writes nothing"
 
+# The refusal ledger is what the evasion report reads. A MultiEdit refusal that
+# blocks but records nothing leaves that report blind to this route.
+rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
+run_case_ledger "ledger multiedit refusal blocks" \
+  "$(mkenv_sid MultiEdit "$LSID" file_path "$XTARGET")" \
+  2 'reason=cross-account target=5e99bba5' "$ACCT_OWN"
+if [ -f "$LEDGER" ] && grep -qxF "$(realpath_of "$XTARGET")" "$LEDGER"; then
+  echo "PASS: ledger holds the multiedit refusal"; PASS=$((PASS+1));
+else echo "FAIL: multiedit refusal not recorded at $LEDGER" >&2; FAIL=$((FAIL+1)); fi
+
 # A path outside the accounts root is allowed here, so it records nothing.
 rm -f "$LEDGER_TMP"/maxy-fsguard-refused-*
 run_case_ledger "ledger out-of-tree allowed" \

package/payload/platform/plugins/admin/hooks/__tests__/quote-path-write-gate.test.sh

@@ -32,6 +32,9 @@
 #   K. a read of a gated path                       → ALLOWED
 #   L. MultiEdit is gated like Write and Edit       → BLOCKED
 #   M. a block emits the op=bypass fault line
+#   N. NotebookEdit is gated like Write and Edit    → BLOCKED
+#   O. the quoter with a NotebookEdit               → ALLOWED
+#   P. NotebookEdit outside a gated bucket          → ALLOWED
 
 set -u
 
@@ -82,6 +85,17 @@ if sys.argv[3]:
 print(json.dumps(d))' "$1" "$2" "$3"
 }
 
+envelope_nb() { # tool_name, notebook_path, agent_type ("" = absent)
+  python3 -c '
+import json, sys
+d = {"hook_event_name": "PreToolUse", "tool_name": sys.argv[1],
+     "tool_input": {"notebook_path": sys.argv[2]}}
+if sys.argv[3]:
+    d["agent_type"] = sys.argv[3]
+    d["agent_id"] = "agent_01"
+print(json.dumps(d))' "$1" "$2" "$3"
+}
+
 run_case() {
   local name="$1" stdin="$2" expected_exit="$3"
   local actual_exit
@@ -133,6 +147,17 @@ run_case "K: a read of a gated path → ALLOWED" \
 run_case "L: MultiEdit is gated like Write and Edit → BLOCKED" \
   "$(envelope MultiEdit "$QUOTE" content-producer)" 2
 
+# The gate is registered on the NotebookEdit matcher and a notebook edit carries
+# notebook_path. Until this arm existed every one of them exited 0 unread.
+run_case "N: NotebookEdit is gated like Write and Edit → BLOCKED" \
+  "$(envelope_nb NotebookEdit 'jobs/job-1/quote/Q 1879 - Client.ipynb' content-producer)" 2
+
+run_case "O: the quoter with a NotebookEdit → ALLOWED" \
+  "$(envelope_nb NotebookEdit 'jobs/job-1/quote/Q 1879 - Client.ipynb' sitedesk:quoter)" 0
+
+run_case "P: NotebookEdit outside a gated bucket → ALLOWED" \
+  "$(envelope_nb NotebookEdit 'output/works-order.ipynb' content-producer)" 0
+
 check_reason() { # name, agent_type, expected reason
   local out
   out=$( cd "$ACCT" && export PLATFORM_ROOT="$FAKE/platform" && printf '%s' "$(envelope Write "$QUOTE" "$2")" | bash "$HOOK" 2>&1 >/dev/null )

package/payload/platform/plugins/admin/hooks/archive-ingest-surface-gate.sh

@@ -30,7 +30,7 @@
 #                                                      and other archiveTypes pass
 #                                                      through unchanged.)
 #
-# 2. PreToolUse Edit/Write/NotebookEdit: deny writes under
+# 2. PreToolUse Edit/Write/MultiEdit/NotebookEdit: deny writes under
 #    `*platform/plugins/*/lib/*` (parser/CSV-shape source for any *-import or
 #    *-export plugin). Preserved — defence in depth even though
 #    the database-operator template no longer lists Edit/Write tools.
@@ -189,10 +189,17 @@ if [ "$TOOL_NAME" = "mcp__memory__memory-archive-write" ]; then
   fi
 fi
 
-# --- Block 4: plugin-source path block (Edit/Write/NotebookEdit) -----------
+# --- Block 4: plugin-source path block (Edit/Write/MultiEdit/NotebookEdit) --
 case "$TOOL_NAME" in
-  Edit|Write|NotebookEdit)
-    FILE_PATH=$(extract_tool_input_field file_path)
+  Edit|Write|MultiEdit|NotebookEdit)
+    # MultiEdit carries file_path exactly as Edit does. A notebook edit carries
+    # notebook_path instead, so reading only file_path left every NotebookEdit
+    # unfenced even though the arm already named it.
+    if [ "$TOOL_NAME" = "NotebookEdit" ]; then
+      FILE_PATH=$(extract_tool_input_field notebook_path)
+    else
+      FILE_PATH=$(extract_tool_input_field file_path)
+    fi
     case "$FILE_PATH" in
       */platform/plugins/*/lib/*|platform/plugins/*/lib/*)
         emit_decision "block" "plugin-source-edit path=${FILE_PATH}" \