@mondaydotcomorg/z2h-cli 0.33.0 → 0.33.1

package/dist/backend/__tests__/format-sandbox-run.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format-sandbox-run.test.d.ts.map

package/dist/backend/__tests__/format-sandbox-run.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-sandbox-run.test.d.ts","sourceRoot":"","sources":["../../../src/backend/__tests__/format-sandbox-run.test.ts"],"names":[],"mappings":""}

package/dist/backend/client.d.ts

@@ -1,10 +1,40 @@
 /** `Z2H_BACKEND_URL` overrides for staging or a locally-run runner. */
 export declare function backendBaseUrl(): string;
-export interface InvokeResponse {
+export interface SandboxRunRequest {
+    code: string;
+    input: unknown;
+    handlerName?: string;
+}
+/** One channel call the handler made, as the runner traced it. */
+export interface SandboxCall {
+    method: string;
+    args: unknown[];
+    durationMs: number;
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    result?: unknown;
+}
+export interface SandboxRunResponse {
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    calls: SandboxCall[];
     result: unknown;
     durationMs: number;
 }
-export declare function invokeBackend(appName: string, handlerName: string, input: unknown): Promise<InvokeResponse>;
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+export declare function runSandbox(appName: string, body: SandboxRunRequest): Promise<SandboxRunResponse>;
 export interface AppIntegrationsResponse {
     integrations: string[];
 }

package/dist/backend/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAEhG;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}

package/dist/backend/client.js

@@ -56,10 +56,13 @@ async function request(method, baseUrl, path, body) {
     }
     return (parsed ?? {});
 }
-function invokeBackend(appName, handlerName, input) {
-    // The runner resolves the caller from the request or 401s, so an anonymous
-    // invoke can never reach a handler.
-    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/invoke/${encodeURIComponent(handlerName)}`, { input });
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+function runSandbox(appName, body) {
+    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/sandbox/run`, body);
 }
 function listAppIntegrations(appName) {
     return request('GET', constants.brokerBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/integrations`);
@@ -73,6 +76,6 @@ function removeIntegration(appName, integration) {
 
 exports.backendBaseUrl = backendBaseUrl;
 exports.declareIntegration = declareIntegration;
-exports.invokeBackend = invokeBackend;
 exports.listAppIntegrations = listAppIntegrations;
 exports.removeIntegration = removeIntegration;
+exports.runSandbox = runSandbox;

package/dist/backend/format-sandbox-run.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxRunResponse } from './client';
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+export declare function formatSandboxRun(res: SandboxRunResponse): string;
+//# sourceMappingURL=format-sandbox-run.d.ts.map

package/dist/backend/format-sandbox-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-sandbox-run.d.ts","sourceRoot":"","sources":["../../src/backend/format-sandbox-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAmChE,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAchE"}

package/dist/backend/format-sandbox-run.js

@@ -0,0 +1,49 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const MAX_SQL_CHARS = 400;
+const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text);
+/** The first arg is the SQL / GraphQL text for query channels — shown on its own line so it can be read. */
+function describeArgs(args) {
+    const [first, ...rest] = args;
+    const lines = [];
+    if (typeof first === 'string') {
+        lines.push(clip(oneLine(first), MAX_SQL_CHARS));
+    }
+    else if (first !== undefined) {
+        lines.push(clip(JSON.stringify(first), MAX_SQL_CHARS));
+    }
+    const params = rest.filter(arg => arg !== undefined && arg !== null);
+    if (params.length > 0) {
+        lines.push(`params: ${clip(params.map(p => JSON.stringify(p)).join(', '), MAX_SQL_CHARS)}`);
+    }
+    return lines;
+}
+function describeCall(call) {
+    const rows = Array.isArray(call.result) ? `  ${call.result.length} rows` : '';
+    const head = `  ${call.ok ? '✓' : '✗'} ${call.method}  ${Math.round(call.durationMs)}ms${rows}`;
+    const detail = describeArgs(call.args);
+    if (call.error) {
+        const code = call.error.code ? ` ${call.error.code}` : '';
+        detail.push(`${call.error.status}${code}: ${call.error.message}`);
+    }
+    return [head, ...detail.map(line => `      ${line}`)];
+}
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+function formatSandboxRun(res) {
+    const lines = [`[z2h-cli] sandbox run ${res.ok ? '✓' : '✗'} ${seconds(res.durationMs)}`, ''];
+    lines.push(res.calls.length > 0 ? 'calls:' : 'calls: none');
+    res.calls.forEach(call => lines.push(...describeCall(call)));
+    lines.push('');
+    if (res.ok) {
+        lines.push('result:', JSON.stringify(res.result, null, 2));
+    }
+    else if (res.error) {
+        const code = res.error.code ? ` ${res.error.code}` : '';
+        lines.push(`error: ${res.error.status}${code} — ${res.error.message}`);
+    }
+    return lines.join('\n');
+}
+
+exports.formatSandboxRun = formatSandboxRun;

package/dist/commands/__tests__/backend-invoke.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backend-invoke.test.d.ts.map

package/dist/commands/__tests__/backend-invoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-invoke.test.d.ts","sourceRoot":"","sources":["../../../src/commands/__tests__/backend-invoke.test.ts"],"names":[],"mappings":""}

package/dist/commands/backend.d.ts

@@ -23,7 +23,12 @@ export declare function deployBackend(opts: {
  * local `usage.json` — no upload to S3. Throws on the first invalid handler.
  */
 export declare function backendValidateCommand(appDir?: string): Promise<void>;
+/**
+ * Runs a handler from the working tree (or `--code`) on the runner's sandbox and
+ * prints the trace. Validated locally first, like deploy; exits 1 when the handler fails.
+ */
 export declare function backendInvokeCommand(handlerName: string, opts?: {
     input?: string;
-}): Promise<void>;
+    code?: string;
+}, appDir?: string): Promise<void>;
 //# sourceMappingURL=backend.d.ts.map

package/dist/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAsBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqDD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAyBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqDD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAsBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,EAC5C,MAAM,GAAE,MAAsB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/commands/backend.js

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 const path = require('node:path');
 const fs = require('node:fs');
+const promises = require('node:fs/promises');
 const fs$1 = require('fs-extra');
 const clientS3 = require('@aws-sdk/client-s3');
 const util_logger = require('../util/logger.js');
@@ -12,6 +13,8 @@ const backend_detectIntegrations = require('../backend/detect-integrations.js');
 const util_s3_client = require('../util/s3/client.js');
 const constants = require('../constants.js');
 const backend_client = require('../backend/client.js');
+const backend_formatSandboxRun = require('../backend/format-sandbox-run.js');
+const backend_validate = require('../backend/validate.js');
 const util_errors = require('../util/errors.js');
 
 const _interopDefault = e => e && e.__esModule ? e : { default: e };
@@ -111,7 +114,29 @@ async function backendValidateCommand(appDir = process.cwd()) {
         integrations,
     });
 }
-async function backendInvokeCommand(handlerName, opts = {}) {
+async function readHandlerSource(appDir, handlerName) {
+    const dir = path__default.default.join(appDir, 'backend', 'handlers');
+    try {
+        return await promises.readFile(path__default.default.join(dir, `${handlerName}.js`), 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        const files = hasHandlers(appDir) ? await promises.readdir(dir) : [];
+        const available = files
+            .filter(f => f.endsWith('.js'))
+            .map(f => path__default.default.parse(f).name)
+            .sort();
+        throw new Error(`no handler "${handlerName}" in backend/handlers/` +
+            (available.length ? ` (available: ${available.join(', ')})` : ' (no handlers found)'));
+    }
+}
+/**
+ * Runs a handler from the working tree (or `--code`) on the runner's sandbox and
+ * prints the trace. Validated locally first, like deploy; exits 1 when the handler fails.
+ */
+async function backendInvokeCommand(handlerName, opts = {}, appDir = process.cwd()) {
     const appName = currentAppName();
     let input = null;
     if (opts.input) {
@@ -122,8 +147,15 @@ async function backendInvokeCommand(handlerName, opts = {}) {
             throw new Error(`--input must be valid JSON (got: ${opts.input})`);
         }
     }
-    const res = await backend_client.invokeBackend(appName, handlerName, input);
-    util_logger.output(`[z2h-cli] result (${Math.round(res.durationMs)}ms):\n${JSON.stringify(res.result, null, 2)}`, res);
+    const file = `${handlerName}.js`;
+    const code = opts.code ?? (await readHandlerSource(appDir, handlerName));
+    backend_validate.validateHandlerSource(file, code);
+    util_logger.info(`validated ${opts.code ? '--code' : file}`);
+    const res = await backend_client.runSandbox(appName, { code, input, handlerName });
+    util_logger.output(backend_formatSandboxRun.formatSandboxRun(res), res);
+    if (!res.ok) {
+        process.exitCode = 1;
+    }
 }
 
 exports.backendInvokeCommand = backendInvokeCommand;

package/dist/esm/backend/__tests__/format-sandbox-run.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=format-sandbox-run.test.d.ts.map

package/dist/esm/backend/__tests__/format-sandbox-run.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-sandbox-run.test.d.ts","sourceRoot":"","sources":["../../../../src/backend/__tests__/format-sandbox-run.test.ts"],"names":[],"mappings":""}

package/dist/esm/backend/client.d.ts

@@ -1,10 +1,40 @@
 /** `Z2H_BACKEND_URL` overrides for staging or a locally-run runner. */
 export declare function backendBaseUrl(): string;
-export interface InvokeResponse {
+export interface SandboxRunRequest {
+    code: string;
+    input: unknown;
+    handlerName?: string;
+}
+/** One channel call the handler made, as the runner traced it. */
+export interface SandboxCall {
+    method: string;
+    args: unknown[];
+    durationMs: number;
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    result?: unknown;
+}
+export interface SandboxRunResponse {
+    ok: boolean;
+    error?: {
+        status: number;
+        code?: string;
+        message: string;
+    };
+    calls: SandboxCall[];
     result: unknown;
     durationMs: number;
 }
-export declare function invokeBackend(appName: string, handlerName: string, input: unknown): Promise<InvokeResponse>;
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+export declare function runSandbox(appName: string, body: SandboxRunRequest): Promise<SandboxRunResponse>;
 export interface AppIntegrationsResponse {
     integrations: string[];
 }

package/dist/esm/backend/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAS3G;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/backend/client.ts"],"names":[],"mappings":"AAWA,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AA+CD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,kEAAkE;AAClE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAEhG;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAErF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEtF;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}

package/dist/esm/backend/client.mjs

@@ -54,10 +54,13 @@ async function request(method, baseUrl, path, body) {
     }
     return (parsed ?? {});
 }
-function invokeBackend(appName, handlerName, input) {
-    // The runner resolves the caller from the request or 401s, so an anonymous
-    // invoke can never reach a handler.
-    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/invoke/${encodeURIComponent(handlerName)}`, { input });
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+function runSandbox(appName, body) {
+    return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/sandbox/run`, body);
 }
 function listAppIntegrations(appName) {
     return request('GET', brokerBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/integrations`);
@@ -69,4 +72,4 @@ function removeIntegration(appName, integration) {
     return request('DELETE', brokerBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/integrations/${encodeURIComponent(integration)}`);
 }
 
-export { backendBaseUrl, declareIntegration, invokeBackend, listAppIntegrations, removeIntegration };
+export { backendBaseUrl, declareIntegration, listAppIntegrations, removeIntegration, runSandbox };

package/dist/esm/backend/format-sandbox-run.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxRunResponse } from './client';
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+export declare function formatSandboxRun(res: SandboxRunResponse): string;
+//# sourceMappingURL=format-sandbox-run.d.ts.map

package/dist/esm/backend/format-sandbox-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-sandbox-run.d.ts","sourceRoot":"","sources":["../../../src/backend/format-sandbox-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAmChE,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAchE"}

package/dist/esm/backend/format-sandbox-run.mjs

@@ -0,0 +1,47 @@
+const MAX_SQL_CHARS = 400;
+const seconds = (ms) => `${(ms / 1000).toFixed(1)}s`;
+const oneLine = (text) => text.replace(/\s+/g, ' ').trim();
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text);
+/** The first arg is the SQL / GraphQL text for query channels — shown on its own line so it can be read. */
+function describeArgs(args) {
+    const [first, ...rest] = args;
+    const lines = [];
+    if (typeof first === 'string') {
+        lines.push(clip(oneLine(first), MAX_SQL_CHARS));
+    }
+    else if (first !== undefined) {
+        lines.push(clip(JSON.stringify(first), MAX_SQL_CHARS));
+    }
+    const params = rest.filter(arg => arg !== undefined && arg !== null);
+    if (params.length > 0) {
+        lines.push(`params: ${clip(params.map(p => JSON.stringify(p)).join(', '), MAX_SQL_CHARS)}`);
+    }
+    return lines;
+}
+function describeCall(call) {
+    const rows = Array.isArray(call.result) ? `  ${call.result.length} rows` : '';
+    const head = `  ${call.ok ? '✓' : '✗'} ${call.method}  ${Math.round(call.durationMs)}ms${rows}`;
+    const detail = describeArgs(call.args);
+    if (call.error) {
+        const code = call.error.code ? ` ${call.error.code}` : '';
+        detail.push(`${call.error.status}${code}: ${call.error.message}`);
+    }
+    return [head, ...detail.map(line => `      ${line}`)];
+}
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+function formatSandboxRun(res) {
+    const lines = [`[z2h-cli] sandbox run ${res.ok ? '✓' : '✗'} ${seconds(res.durationMs)}`, ''];
+    lines.push(res.calls.length > 0 ? 'calls:' : 'calls: none');
+    res.calls.forEach(call => lines.push(...describeCall(call)));
+    lines.push('');
+    if (res.ok) {
+        lines.push('result:', JSON.stringify(res.result, null, 2));
+    }
+    else if (res.error) {
+        const code = res.error.code ? ` ${res.error.code}` : '';
+        lines.push(`error: ${res.error.status}${code} — ${res.error.message}`);
+    }
+    return lines.join('\n');
+}
+
+export { formatSandboxRun };

package/dist/esm/commands/__tests__/backend-invoke.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backend-invoke.test.d.ts.map

package/dist/esm/commands/__tests__/backend-invoke.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend-invoke.test.d.ts","sourceRoot":"","sources":["../../../../src/commands/__tests__/backend-invoke.test.ts"],"names":[],"mappings":""}

package/dist/esm/commands/backend.d.ts

@@ -23,7 +23,12 @@ export declare function deployBackend(opts: {
  * local `usage.json` — no upload to S3. Throws on the first invalid handler.
  */
 export declare function backendValidateCommand(appDir?: string): Promise<void>;
+/**
+ * Runs a handler from the working tree (or `--code`) on the runner's sandbox and
+ * prints the trace. Validated locally first, like deploy; exits 1 when the handler fails.
+ */
 export declare function backendInvokeCommand(handlerName: string, opts?: {
     input?: string;
-}): Promise<void>;
+    code?: string;
+}, appDir?: string): Promise<void>;
 //# sourceMappingURL=backend.d.ts.map

package/dist/esm/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAsBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqDD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAED,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAa5G"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/commands/backend.ts"],"names":[],"mappings":"AAyBA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAqDD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe1F;AAsBD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,EAC5C,MAAM,GAAE,MAAsB,GAC7B,OAAO,CAAC,IAAI,CAAC,CAqBf"}

package/dist/esm/commands/backend.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
 import { readJson, writeJson } from 'fs-extra';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { output, info } from '../util/logger.mjs';
@@ -9,7 +10,9 @@ import { readHandlers } from '../backend/handlers.mjs';
 import { detectIntegrations } from '../backend/detect-integrations.mjs';
 import { getS3Client } from '../util/s3/client.mjs';
 import { BUCKET_WRITE_NAME } from '../constants.mjs';
-import { invokeBackend } from '../backend/client.mjs';
+import { runSandbox } from '../backend/client.mjs';
+import { formatSandboxRun } from '../backend/format-sandbox-run.mjs';
+import { validateHandlerSource } from '../backend/validate.mjs';
 import { tagDeployError } from '../util/errors.mjs';
 
 function currentAppName() {
@@ -105,7 +108,29 @@ async function backendValidateCommand(appDir = process.cwd()) {
         integrations,
     });
 }
-async function backendInvokeCommand(handlerName, opts = {}) {
+async function readHandlerSource(appDir, handlerName) {
+    const dir = path.join(appDir, 'backend', 'handlers');
+    try {
+        return await readFile(path.join(dir, `${handlerName}.js`), 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+        const files = hasHandlers(appDir) ? await readdir(dir) : [];
+        const available = files
+            .filter(f => f.endsWith('.js'))
+            .map(f => path.parse(f).name)
+            .sort();
+        throw new Error(`no handler "${handlerName}" in backend/handlers/` +
+            (available.length ? ` (available: ${available.join(', ')})` : ' (no handlers found)'));
+    }
+}
+/**
+ * Runs a handler from the working tree (or `--code`) on the runner's sandbox and
+ * prints the trace. Validated locally first, like deploy; exits 1 when the handler fails.
+ */
+async function backendInvokeCommand(handlerName, opts = {}, appDir = process.cwd()) {
     const appName = currentAppName();
     let input = null;
     if (opts.input) {
@@ -116,8 +141,15 @@ async function backendInvokeCommand(handlerName, opts = {}) {
             throw new Error(`--input must be valid JSON (got: ${opts.input})`);
         }
     }
-    const res = await invokeBackend(appName, handlerName, input);
-    output(`[z2h-cli] result (${Math.round(res.durationMs)}ms):\n${JSON.stringify(res.result, null, 2)}`, res);
+    const file = `${handlerName}.js`;
+    const code = opts.code ?? (await readHandlerSource(appDir, handlerName));
+    validateHandlerSource(file, code);
+    info(`validated ${opts.code ? '--code' : file}`);
+    const res = await runSandbox(appName, { code, input, handlerName });
+    output(formatSandboxRun(res), res);
+    if (!res.ok) {
+        process.exitCode = 1;
+    }
 }
 
 export { backendInvokeCommand, backendValidateCommand, deployBackend, hasHandlers };

package/dist/esm/index.mjs

@@ -180,15 +180,18 @@ async function main() {
         .action(runCommand({ data: cwdApp }, (opts) => deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
     backend
         .command('validate')
         .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
         .action(runCommand({ data: cwdApp }, () => backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
-        .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')
-        .option('--input <json>', 'JSON payload passed as ctx.input')
+        .description("Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.')
+        .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+        .option('--code <source>', 'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label')
         .action(runCommand({
         data: ([handlerName]) => ({ app_name: getCwdAppName(), handler: handlerName }),
     }, (handlerName, opts) => backendInvokeCommand(handlerName, opts)));
@@ -215,7 +218,9 @@ void main()
     if (getOutputMode() === 'human') {
         selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
 })
     .catch(async (err) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

package/dist/index.js

@@ -186,15 +186,18 @@ async function main() {
         .action(util_runCommand.runCommand({ data: cwdApp }, (opts) => commands_delete.deleteCommand(opts)));
     const backend = program
         .command('backend')
-        .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+        .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
     backend
         .command('validate')
         .description('Validate backend/handlers/*.js exactly as deploy would (syntax, isolate rules, integrations) without uploading')
         .action(util_runCommand.runCommand({ data: cwdApp }, () => commands_backend.backendValidateCommand()));
     backend
         .command('invoke <handlerName>')
-        .description('Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend')
-        .option('--input <json>', 'JSON payload passed as ctx.input')
+        .description("Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.')
+        .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+        .option('--code <source>', 'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label')
         .action(util_runCommand.runCommand({
         data: ([handlerName]) => ({ app_name: util_appName.getCwdAppName(), handler: handlerName }),
     }, (handlerName, opts) => commands_backend.backendInvokeCommand(handlerName, opts)));
@@ -221,7 +224,9 @@ void main()
     if (util_logger.getOutputMode() === 'human') {
         selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
 })
     .catch(async (err) => {
     const errorMsg = err instanceof Error ? err.message : String(err);

package/handler-api/backend-runner/backend-runner.errors.ts

@@ -54,3 +54,15 @@ export class ChannelError extends BackendRunnerError {
     this.name = 'ChannelError';
   }
 }
+
+/**
+ * A sandbox run request the runner refuses before any code runs — the code is
+ * unusable or the app doesn't exist. Carries a `code` so
+ * the CLI can say exactly which, the same way a channel error does.
+ */
+export class SandboxRequestError extends BackendRunnerError {
+  constructor(statusCode: number, message: string, public readonly code: string) {
+    super(statusCode, message);
+    this.name = 'SandboxRequestError';
+  }
+}

package/handler-api/backend-runner/backend-runner.types.ts

@@ -34,6 +34,9 @@ export type ChannelHandler = (args: unknown[]) => Promise<unknown> | unknown;
  */
 export type ChannelMap = Record<string, ChannelHandler>;
 
+/** Which path built the channels — a deployed handler (`invoke`) or source sent to the sandbox. Tags channel telemetry. */
+export type RunMode = 'invoke' | 'sandbox';
+
 /**
  * A breakdown of where the isolate wall-clock went, in ms. Lets us see whether a
  * slow invoke is the V8 setup (create + compile) or the guest's own work + its

package/handler-api/backend-runner/channels/channel-map.ts

@@ -6,13 +6,19 @@ import { makeDbChannel } from './db-channel/db.channel';
 import { makeLlmChannel } from './llm-channel/llm.channel';
 import { makeMondayChannel } from './monday-channel/monday.channel';
 import { makeSnowflakeChannel } from './snowflake-channel/snowflake.channel';
-import type { Caller, ChannelMap } from '../backend-runner.types';
+import type { Caller, ChannelMap, RunMode } from '../backend-runner.types';
 import type { RunnerCustomIntegration } from '../runner-data.store';
 
 const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
   monday: (caller) => makeMondayChannel(caller),
 };
 
+/**
+ * Every integration with a registered channel. Sandbox runs build all of them —
+ * safe because each fetches the caller's token only when a method is called.
+ */
+export const OAUTH_INTEGRATIONS = Object.keys(OAUTH_CHANNELS);
+
 /**
  * Builds the complete channel surface for one invocation — the only way out of
  * the isolate.
@@ -63,7 +69,7 @@ const OAUTH_CHANNELS: Record<string, (caller: Caller) => ChannelMap> = {
  * setup) is wrong and retrying won't help; `502` means the upstream failed.
  *
  * Each key emits a unified call counter, duration distribution, and BI event tagged
- * by app, channel, method, and outcome. Uncaught failures also reach BI at the
+ * by app, mode (`invoke` or `sandbox`), channel, method, and outcome. Uncaught failures also reach BI at the
  * invocation level — see `runner.service.ts`.
  */
 export function buildChannels(
@@ -71,6 +77,7 @@ export function buildChannels(
   caller: Caller,
   declaredIntegrations: string[],
   customIntegrations: RunnerCustomIntegration[],
+  mode: RunMode,
 ): ChannelMap {
   const channels: ChannelMap = {
     ...makeDbChannel(appName),
@@ -91,5 +98,7 @@ export function buildChannels(
     }
   }
 
-  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, key, fn)]));
+  return Object.fromEntries(
+    Object.entries(channels).map(([key, fn]) => [key, withChannelTelemetry(appName, mode, key, fn)]),
+  );
 }

package/handler-api/backend-runner/channels/channel-telemetry.ts

@@ -4,7 +4,7 @@ import { trackEvent } from '@mondaydotcomorg/z2h-shared-utils/observability/trid
 
 import { ChannelError } from '../backend-runner.errors';
 import { BI_SOURCE } from '../constants';
-import type { ChannelHandler } from '../backend-runner.types';
+import type { ChannelHandler, RunMode } from '../backend-runner.types';
 
 type ChannelOutcome = 'success' | 'failure';
 
@@ -26,6 +26,7 @@ function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
 
 function recordChannelCall(
   appName: string,
+  mode: RunMode,
   channel: string,
   method: string,
   outcome: ChannelOutcome,
@@ -33,7 +34,7 @@ function recordChannelCall(
   error?: unknown,
 ): void {
   const durationMs = performance.now() - startedAt;
-  const dimensions = { appName, channel, method };
+  const dimensions = { appName, mode, channel, method };
 
   metric.increment(BackendRunnerEvents.channel.callMetric, { ...dimensions, outcome });
   metric.distribution(BackendRunnerEvents.channel.durationMetric, durationMs, dimensions);
@@ -49,7 +50,12 @@ function recordChannelCall(
   );
 }
 
-export function withChannelTelemetry(appName: string, key: string, handler: ChannelHandler): ChannelHandler {
+export function withChannelTelemetry(
+  appName: string,
+  mode: RunMode,
+  key: string,
+  handler: ChannelHandler,
+): ChannelHandler {
   const { channel, method } = parseChannelKey(key);
 
   return (args) => {
@@ -59,20 +65,20 @@ export function withChannelTelemetry(appName: string, key: string, handler: Chan
       if (isPromiseLike(result)) {
         return Promise.resolve(result).then(
           (value) => {
-            recordChannelCall(appName, channel, method, 'success', startedAt);
+            recordChannelCall(appName, mode, channel, method, 'success', startedAt);
             return value;
           },
           (error: unknown) => {
-            recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+            recordChannelCall(appName, mode, channel, method, 'failure', startedAt, error);
             throw error;
           },
         );
       }
 
-      recordChannelCall(appName, channel, method, 'success', startedAt);
+      recordChannelCall(appName, mode, channel, method, 'success', startedAt);
       return result;
     } catch (error) {
-      recordChannelCall(appName, channel, method, 'failure', startedAt, error);
+      recordChannelCall(appName, mode, channel, method, 'failure', startedAt, error);
       throw error;
     }
   };

package/handler-api/backend-runner/channels/channel-trace.ts

@@ -0,0 +1,52 @@
+import { ChannelError } from '../backend-runner.errors';
+import type { ChannelHandler, ChannelMap } from '../backend-runner.types';
+
+/**
+ * One channel call as the sandbox reports it back to the author. Raw args are
+ * recorded — for `snowflake.query` that is the SQL text and its params, not the
+ * bound SQL the channel builds from them.
+ */
+export interface ChannelCallTrace {
+  method: string;
+  args: unknown[];
+  durationMs: number;
+  ok: boolean;
+  /** Why the call failed — same shape as the run's `error`. A non-`ChannelError` is a 500 with no code. */
+  error?: { status: number; code?: string; message: string };
+  /** What the channel returned to the handler, as-is — e.g. Snowflake rows or monday's GraphQL `data`. */
+  result?: unknown;
+}
+
+type CallOutcome = Pick<ChannelCallTrace, 'ok' | 'error' | 'result'>;
+
+function withChannelTrace(calls: ChannelCallTrace[], method: string, handler: ChannelHandler): ChannelHandler {
+  return async (args) => {
+    const startedAt = performance.now();
+    const record = (outcome: CallOutcome): void => {
+      calls.push({ method, args, durationMs: performance.now() - startedAt, ...outcome });
+    };
+
+    try {
+      const result = await handler(args);
+      record({ ok: true, result });
+      return result;
+    } catch (err) {
+      record({
+        ok: false,
+        error:
+          err instanceof ChannelError
+            ? { status: err.statusCode, code: err.code, message: err.message }
+            : { status: 500, message: err instanceof Error ? err.message : String(err) },
+      });
+      throw err;
+    }
+  };
+}
+
+/**
+ * Wraps every channel so each call is appended to `calls` in the order it
+ * finished. Sandbox-only: the deployed invoke path never records a trace.
+ */
+export function traceChannels(channels: ChannelMap, calls: ChannelCallTrace[]): ChannelMap {
+  return Object.fromEntries(Object.entries(channels).map(([key, fn]) => [key, withChannelTrace(calls, key, fn)]));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.33.0",
+  "version": "0.33.1",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -52,7 +52,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.706.0",
     "@mondaydotcomorg/z2h-dashboard-templates": "^0.4.0",
-    "@mondaydotcomorg/z2h-shared-utils": "^0.7.0",
+    "@mondaydotcomorg/z2h-shared-utils": "^0.7.1",
     "acorn": "^8.14.0",
     "acorn-walk": "^8.3.4",
     "chokidar": "^3.6.0",

package/src/backend/__tests__/client.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from 'vitest';
 
-import { backendBaseUrl, declareIntegration, invokeBackend, listAppIntegrations, removeIntegration } from '../client';
+import { backendBaseUrl, declareIntegration, listAppIntegrations, removeIntegration, runSandbox } from '../client';
 
 vi.mock('../../util/auth/auth-store', () => ({
   readZthAuth: vi.fn().mockResolvedValue({ token: 'jwt-token' }),
@@ -21,6 +21,8 @@ const respond = (init: { ok?: boolean; status?: number; statusText?: string; bod
 
 const lastCall = () => (fetch as Mock).mock.calls[0];
 
+const SANDBOX_BODY = { code: 'function handler() {}', input: null };
+
 beforeEach(() => {
   vi.stubGlobal('fetch', respond({ body: '{"result":1,"durationMs":5}' }));
 });
@@ -42,13 +44,15 @@ describe('backendBaseUrl', () => {
 });
 
 describe('where each call goes', () => {
-  it('sends an invoke to the runner, authenticated', async () => {
-    await invokeBackend('mf-reports', 'get_items', { n: 1 });
+  it('sends a sandbox run to the runner, authenticated, with the code in the body', async () => {
+    const body = { code: 'function handler() {}', input: { n: 1 }, handlerName: 'get_items' };
+    await runSandbox('mf-reports', body);
 
     const [url, opts] = lastCall();
-    expect(url).toBe('https://zth-backend-runner.bigbrain.me/z2h-apps/mf-reports/invoke/get_items');
+    expect(url).toBe('https://zth-backend-runner.bigbrain.me/z2h-apps/mf-reports/sandbox/run');
+    expect(opts.method).toBe('POST');
     expect(opts.headers).toMatchObject({ Authorization: 'Bearer jwt-token', 'x-route': 'prod' });
-    expect(JSON.parse(opts.body)).toEqual({ input: { n: 1 } });
+    expect(JSON.parse(opts.body)).toEqual(body);
   });
 
   // Integrations live in the platform's registry, which the broker owns — not the runner.
@@ -72,9 +76,9 @@ describe('where each call goes', () => {
   });
 
   it('escapes an app name rather than letting it alter the path', async () => {
-    await invokeBackend('mf-a/../b', 'get_items', null);
+    await runSandbox('mf-a/../b', SANDBOX_BODY);
 
-    expect(lastCall()[0]).toContain('/z2h-apps/mf-a%2F..%2Fb/invoke/get_items');
+    expect(lastCall()[0]).toContain('/z2h-apps/mf-a%2F..%2Fb/sandbox/run');
   });
 });
 
@@ -85,27 +89,27 @@ describe('where each call goes', () => {
  */
 describe('what the author is told when it fails', () => {
   it('uses the server’s own message when there is one', async () => {
-    vi.stubGlobal('fetch', respond({ ok: false, status: 404, body: '{"message":"No backend deployed for \\"x\\""}' }));
+    vi.stubGlobal('fetch', respond({ ok: false, status: 404, body: '{"message":"app \\"x\\" is not registered"}' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow('No backend deployed for "x"');
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow('app "x" is not registered');
   });
 
   it('falls back to the status plus a snippet when the body is HTML', async () => {
     vi.stubGlobal('fetch', respond({ ok: false, status: 502, statusText: 'Bad Gateway', body: '<html>nginx</html>' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(/502 Bad Gateway.*nginx/s);
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(/502 Bad Gateway.*nginx/s);
   });
 
   it('collapses whitespace in that snippet so the message stays one line', async () => {
     vi.stubGlobal('fetch', respond({ ok: false, status: 500, body: '<html>\n  a\n\n  b\n</html>' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(/<html> a b <\/html>/);
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(/<html> a b <\/html>/);
   });
 
   it('names the URL it could not reach when the request never lands', async () => {
     vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('ECONNREFUSED')));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(
       /cannot reach https:\/\/zth-backend-runner.*ECONNREFUSED/
     );
   });
@@ -113,7 +117,7 @@ describe('what the author is told when it fails', () => {
   it('reports a 200 whose body is not JSON rather than returning nothing', async () => {
     vi.stubGlobal('fetch', respond({ body: '<html>login</html>' }));
 
-    await expect(invokeBackend('mf-x', 'get_items', null)).rejects.toThrow(/non-JSON response/);
+    await expect(runSandbox('mf-x', SANDBOX_BODY)).rejects.toThrow(/non-JSON response/);
   });
 
   // DELETE returns 204 with no body, which is success, not a parse failure.

package/src/backend/__tests__/format-sandbox-run.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import { formatSandboxRun } from '../format-sandbox-run';
+
+describe('formatSandboxRun', () => {
+  it('shows each call with its SQL on one line, params, and row count, then the result', () => {
+    const text = formatSandboxRun({
+      ok: true,
+      calls: [
+        {
+          method: 'snowflake.query',
+          args: ['SELECT region\n   FROM accounts\n  WHERE d >= :since', { since: '2026-01-01' }],
+          durationMs: 812.4,
+          ok: true,
+          result: [{ r: 1 }, { r: 2 }, { r: 3 }, { r: 4 }],
+        },
+      ],
+      result: { regions: [] },
+      durationMs: 1200,
+    });
+
+    expect(text).toContain('sandbox run ✓ 1.2s');
+    expect(text).toContain('✓ snowflake.query  812ms  4 rows');
+    expect(text).toContain('SELECT region FROM accounts WHERE d >= :since');
+    expect(text).toContain('params: {"since":"2026-01-01"}');
+    expect(text).toContain('result:\n{\n  "regions": []\n}');
+  });
+
+  it('ends with the error instead of a result on failure', () => {
+    const text = formatSandboxRun({
+      ok: false,
+      error: { status: 504, code: 'isolate_timeout', message: 'Script execution timed out.' },
+      calls: [],
+      result: null,
+      durationMs: 5000,
+    });
+
+    expect(text).toContain('sandbox run ✗ 5.0s');
+    expect(text).toContain('error: 504 isolate_timeout — Script execution timed out.');
+    expect(text).not.toContain('result:');
+  });
+});

package/src/backend/client.ts

@@ -59,20 +59,37 @@ async function request<T>(method: string, baseUrl: string, path: string, body?:
   return (parsed ?? ({} as T)) as T;
 }
 
-export interface InvokeResponse {
+export interface SandboxRunRequest {
+  code: string;
+  input: unknown;
+  handlerName?: string;
+}
+
+/** One channel call the handler made, as the runner traced it. */
+export interface SandboxCall {
+  method: string;
+  args: unknown[];
+  durationMs: number;
+  ok: boolean;
+  error?: { status: number; code?: string; message: string };
+  result?: unknown;
+}
+
+export interface SandboxRunResponse {
+  ok: boolean;
+  error?: { status: number; code?: string; message: string };
+  calls: SandboxCall[];
   result: unknown;
   durationMs: number;
 }
 
-export function invokeBackend(appName: string, handlerName: string, input: unknown): Promise<InvokeResponse> {
-  // The runner resolves the caller from the request or 401s, so an anonymous
-  // invoke can never reach a handler.
-  return request(
-    'POST',
-    backendBaseUrl(),
-    `/z2h-apps/${encodeURIComponent(appName)}/invoke/${encodeURIComponent(handlerName)}`,
-    { input }
-  );
+/**
+ * Runs handler source from the working tree on the runner's sandbox route —
+ * against the app's real channels, without deploying it. A handler failure
+ * comes back as `ok: false` with the trace; only a refused request throws.
+ */
+export function runSandbox(appName: string, body: SandboxRunRequest): Promise<SandboxRunResponse> {
+  return request('POST', backendBaseUrl(), `/z2h-apps/${encodeURIComponent(appName)}/sandbox/run`, body);
 }
 
 export interface AppIntegrationsResponse {

package/src/backend/format-sandbox-run.ts

@@ -0,0 +1,51 @@
+import type { SandboxCall, SandboxRunResponse } from './client';
+
+const MAX_SQL_CHARS = 400;
+
+const seconds = (ms: number): string => `${(ms / 1000).toFixed(1)}s`;
+const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
+const clip = (text: string, max: number): string => (text.length > max ? `${text.slice(0, max)}…` : text);
+
+/** The first arg is the SQL / GraphQL text for query channels — shown on its own line so it can be read. */
+function describeArgs(args: unknown[]): string[] {
+  const [first, ...rest] = args;
+  const lines: string[] = [];
+  if (typeof first === 'string') {
+    lines.push(clip(oneLine(first), MAX_SQL_CHARS));
+  } else if (first !== undefined) {
+    lines.push(clip(JSON.stringify(first), MAX_SQL_CHARS));
+  }
+  const params = rest.filter(arg => arg !== undefined && arg !== null);
+  if (params.length > 0) {
+    lines.push(`params: ${clip(params.map(p => JSON.stringify(p)).join(', '), MAX_SQL_CHARS)}`);
+  }
+  return lines;
+}
+
+function describeCall(call: SandboxCall): string[] {
+  const rows = Array.isArray(call.result) ? `  ${call.result.length} rows` : '';
+  const head = `  ${call.ok ? '✓' : '✗'} ${call.method}  ${Math.round(call.durationMs)}ms${rows}`;
+  const detail = describeArgs(call.args);
+  if (call.error) {
+    const code = call.error.code ? ` ${call.error.code}` : '';
+    detail.push(`${call.error.status}${code}: ${call.error.message}`);
+  }
+  return [head, ...detail.map(line => `      ${line}`)];
+}
+
+/** Human-readable trace of a sandbox run; `--json` prints the raw response instead. */
+export function formatSandboxRun(res: SandboxRunResponse): string {
+  const lines = [`[z2h-cli] sandbox run ${res.ok ? '✓' : '✗'} ${seconds(res.durationMs)}`, ''];
+
+  lines.push(res.calls.length > 0 ? 'calls:' : 'calls: none');
+  res.calls.forEach(call => lines.push(...describeCall(call)));
+
+  lines.push('');
+  if (res.ok) {
+    lines.push('result:', JSON.stringify(res.result, null, 2));
+  } else if (res.error) {
+    const code = res.error.code ? ` ${res.error.code}` : '';
+    lines.push(`error: ${res.error.status}${code} — ${res.error.message}`);
+  }
+  return lines.join('\n');
+}

package/src/commands/__tests__/backend-invoke.test.ts

@@ -0,0 +1,125 @@
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtemp, rm, ensureDir, writeFile } from 'fs-extra';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { backendInvokeCommand } from '../backend';
+import { runSandbox } from '../../backend/client';
+import { output } from '../../util/logger';
+
+vi.mock('../../util/logger', () => ({
+  info: vi.fn(),
+  warn: vi.fn(),
+  output: vi.fn(),
+}));
+vi.mock('../../util/tracker', () => ({
+  trackEvent: vi.fn().mockResolvedValue(undefined),
+  trackDuration: vi.fn(),
+}));
+vi.mock('../../util/s3/client', () => ({ getS3Client: vi.fn() }));
+vi.mock('../../backend/client', () => ({ runSandbox: vi.fn() }));
+vi.mock('../../util/app-name', async importOriginal => ({
+  ...(await importOriginal<typeof import('../../util/app-name')>()),
+  getCwdAppName: () => 'sales-kpis',
+}));
+
+const runSandboxMock = vi.mocked(runSandbox);
+const outputMock = vi.mocked(output);
+
+const OK = { ok: true, calls: [], result: { n: 1 }, durationMs: 12 };
+
+describe('backendInvokeCommand', () => {
+  let tmp: string;
+
+  const writeHandler = async (name: string, source: string) => {
+    const dir = path.join(tmp, 'backend', 'handlers');
+    await ensureDir(dir);
+    await writeFile(path.join(dir, `${name}.js`), source);
+  };
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(path.join(os.tmpdir(), 'z2h-backend-invoke-'));
+    runSandboxMock.mockReset();
+    runSandboxMock.mockResolvedValue(OK);
+    outputMock.mockClear();
+    process.exitCode = undefined;
+  });
+
+  afterEach(async () => {
+    process.exitCode = undefined;
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  it('sends the handler file from the working tree', async () => {
+    const source = 'async function handler(ctx) { return ctx.api.v1.monday.query("query { me { id } }"); }';
+    await writeHandler('get_kpis', source);
+
+    await backendInvokeCommand('get_kpis', { input: '{"since":"2026-01-01"}' }, tmp);
+
+    expect(runSandboxMock).toHaveBeenCalledWith('mf-sales-kpis', {
+      code: source,
+      input: { since: '2026-01-01' },
+      handlerName: 'get_kpis',
+    });
+    expect(outputMock).toHaveBeenCalledWith(expect.stringContaining('sandbox run ✓'), OK);
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('runs --code instead of the file', async () => {
+    await backendInvokeCommand('scratch', { code: 'function handler() { return 1; }' }, tmp);
+
+    expect(runSandboxMock.mock.calls[0][1]).toMatchObject({ code: 'function handler() { return 1; }', input: null });
+  });
+
+  it('fails locally, without a request, when the source breaks an isolate rule', async () => {
+    await writeHandler('get_kpis', "import x from 'y';\nfunction handler() {}");
+
+    await expect(backendInvokeCommand('get_kpis', {}, tmp)).rejects.toThrow();
+    expect(runSandboxMock).not.toHaveBeenCalled();
+  });
+
+  it('names the available handlers when the one asked for does not exist', async () => {
+    await writeHandler('get_kpis', 'function handler() {}');
+    await writeHandler('list_items', 'function handler() {}');
+
+    await expect(backendInvokeCommand('get_kpi', {}, tmp)).rejects.toThrow(
+      'no handler "get_kpi" in backend/handlers/ (available: get_kpis, list_items)'
+    );
+  });
+
+  it('rejects --input that is not JSON', async () => {
+    await expect(backendInvokeCommand('get_kpis', { input: '{bad' }, tmp)).rejects.toThrow(
+      /--input must be valid JSON/
+    );
+  });
+
+  it('prints the trace and exits 1 when the handler fails', async () => {
+    await writeHandler('get_kpis', 'async function handler(ctx) { return ctx.api.v1.snowflake.query("SELECT ar"); }');
+    const failed = {
+      ok: false,
+      error: { status: 400, code: 'snowflake_query_error', message: "invalid identifier 'AR'" },
+      calls: [
+        {
+          method: 'snowflake.query',
+          args: ['SELECT ar'],
+          durationMs: 640,
+          ok: false,
+          error: { status: 400, code: 'snowflake_query_error', message: "invalid identifier 'AR'" },
+        },
+      ],
+      result: null,
+      durationMs: 900,
+    };
+    runSandboxMock.mockResolvedValue(failed);
+
+    await backendInvokeCommand('get_kpis', {}, tmp);
+
+    const [human, data] = outputMock.mock.calls[0];
+    expect(data).toBe(failed);
+    expect(human).toContain('✗ snowflake.query  640ms');
+    expect(human).toContain('SELECT ar');
+    expect(human).toContain("400 snowflake_query_error: invalid identifier 'AR'");
+    expect(human).toContain("error: 400 snowflake_query_error — invalid identifier 'AR'");
+    expect(process.exitCode).toBe(1);
+  });
+});

package/src/commands/backend.ts

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
 import { readJson, writeJson } from 'fs-extra';
 import { PutObjectCommand } from '@aws-sdk/client-s3';
 import { info, output } from '../util/logger';
@@ -9,7 +10,9 @@ import { readHandlers } from '../backend/handlers';
 import { detectIntegrations } from '../backend/detect-integrations';
 import { getS3Client } from '../util/s3/client';
 import { BUCKET_WRITE_NAME } from '../constants';
-import { invokeBackend } from '../backend/client';
+import { runSandbox } from '../backend/client';
+import { formatSandboxRun } from '../backend/format-sandbox-run';
+import { validateHandlerSource } from '../backend/validate';
 import { tagDeployError } from '../util/errors';
 
 function currentAppName(): string {
@@ -125,7 +128,35 @@ export async function backendValidateCommand(appDir: string = process.cwd()): Pr
   });
 }
 
-export async function backendInvokeCommand(handlerName: string, opts: { input?: string } = {}): Promise<void> {
+async function readHandlerSource(appDir: string, handlerName: string): Promise<string> {
+  const dir = path.join(appDir, 'backend', 'handlers');
+  try {
+    return await readFile(path.join(dir, `${handlerName}.js`), 'utf8');
+  } catch (err) {
+    if ((err as { code?: string }).code !== 'ENOENT') {
+      throw err;
+    }
+    const files = hasHandlers(appDir) ? await readdir(dir) : [];
+    const available = files
+      .filter(f => f.endsWith('.js'))
+      .map(f => path.parse(f).name)
+      .sort();
+    throw new Error(
+      `no handler "${handlerName}" in backend/handlers/` +
+        (available.length ? ` (available: ${available.join(', ')})` : ' (no handlers found)')
+    );
+  }
+}
+
+/**
+ * Runs a handler from the working tree (or `--code`) on the runner's sandbox and
+ * prints the trace. Validated locally first, like deploy; exits 1 when the handler fails.
+ */
+export async function backendInvokeCommand(
+  handlerName: string,
+  opts: { input?: string; code?: string } = {},
+  appDir: string = process.cwd()
+): Promise<void> {
   const appName = currentAppName();
   let input: unknown = null;
   if (opts.input) {
@@ -136,6 +167,14 @@ export async function backendInvokeCommand(handlerName: string, opts: { input?:
     }
   }
 
-  const res = await invokeBackend(appName, handlerName, input);
-  output(`[z2h-cli] result (${Math.round(res.durationMs)}ms):\n${JSON.stringify(res.result, null, 2)}`, res);
+  const file = `${handlerName}.js`;
+  const code = opts.code ?? (await readHandlerSource(appDir, handlerName));
+  validateHandlerSource(file, code);
+  info(`validated ${opts.code ? '--code' : file}`);
+
+  const res = await runSandbox(appName, { code, input, handlerName });
+  output(formatSandboxRun(res), res);
+  if (!res.ok) {
+    process.exitCode = 1;
+  }
 }

package/src/index.ts

@@ -279,7 +279,7 @@ async function main(): Promise<void> {
 
   const backend = program
     .command('backend')
-    .description("Inspect the app's backend: validate handler sources or invoke a deployed handler by name");
+    .description("Inspect the app's backend: validate handler sources or run a handler from the working tree");
 
   backend
     .command('validate')
@@ -291,15 +291,21 @@ async function main(): Promise<void> {
   backend
     .command('invoke <handlerName>')
     .description(
-      'Invoke a deployed backend handler by name (the filename without .ts) — mainly for testing a handler without going through the frontend'
+      "Run backend/handlers/<handlerName>.js from the working tree — not the deployed handler — against the app's real " +
+        'channels (real db data, real monday calls), and print a trace of every channel call and the ' +
+        'result. Nothing is deployed. Exits 1 when the handler fails.'
+    )
+    .option('--input <json>', 'JSON passed to the handler as ctx.input (what the frontend would send)')
+    .option(
+      '--code <source>',
+      'run this source instead of backend/handlers/<handlerName>.js — <handlerName> is then just a label'
     )
-    .option('--input <json>', 'JSON payload passed as ctx.input')
     .action(
       runCommand(
         {
           data: ([handlerName]: [string, unknown]) => ({ app_name: getCwdAppName(), handler: handlerName }),
         },
-        (handlerName: string, opts: { input?: string }) => backendInvokeCommand(handlerName, opts)
+        (handlerName: string, opts: { input?: string; code?: string }) => backendInvokeCommand(handlerName, opts)
       )
     );
 
@@ -330,7 +336,9 @@ void main()
     if (getOutputMode() === 'human') {
       selfUpdate();
     }
-    process.exit(0);
+    // A command can finish normally and still report a non-zero code (e.g.
+    // `backend invoke` when the handler failed) via process.exitCode.
+    process.exit(process.exitCode ?? 0);
   })
   .catch(async (err: unknown) => {
     const errorMsg = err instanceof Error ? err.message : String(err);