@sendbird/cli 0.0.0-stage → 0.4.0

package/skills/sendbird/scripts/client-plugin-bridge.mjs

@@ -0,0 +1,703 @@
+#!/usr/bin/env node
+// The client plugin owns SDK code. This helper only verifies its release,
+// starts a bounded Claude session, and checks the noninteractive handoff result.
+import {
+  constants,
+  openSync,
+  fstatSync,
+  readSync,
+  closeSync,
+  mkdtempSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve, join } from "node:path";
+import { createHash } from "node:crypto";
+import { execFileSync, spawn } from "node:child_process";
+import { pathToFileURL } from "node:url";
+// Publisher's first-run notice, v0.1.74 (f2b12967d65f652c411baa8f3611e98557abf9ad).
+// Do not infer a person's acknowledgement from a successful stderr write.
+export const clientPluginNotice =
+  "Sendbird Client plugin: this plugin runs shell scripts on your computer with your user account's permissions, at session start, before file writes and shell commands, after an agent finishes, and when an answer ends. In Claude Code it also runs one JavaScript file that only shows this notice. They read your project files and parts of this conversation, can block an action or ask Claude to revise its answer, and fetch public pages from sendbird.com/docs and github.com/sendbird. Nothing from your project or conversation is sent to Sendbird. A plugin update replaces these scripts; auto-update is off unless you turn it on. Details: https://github.com/sendbird/sendbird-client-plugin#what-runs-on-your-machine (shown once, and again if this notice changes)";
+// Reviewed publisher release. New releases require an explicit, independently reviewed digest.
+export const reviewedClientRelease = {
+  tag: "v0.1.74",
+  sha256: "0cf95c1fb1cafa202272e5b6e6ecd832f698dd2a818c3624808a19c2aaa000e9",
+};
+export function verifyArchive(zip) {
+  const entries = command("unzip", ["-Z1", zip]).split("\n");
+  if (entries.at(-1) === "") entries.pop();
+  if (!entries.length) throw Error("Release ZIP is empty");
+  const roots = new Set([
+    ".claude-plugin",
+    ".codex-plugin",
+    "agents",
+    "codex",
+    "config",
+    "core",
+    "docs",
+    "hooks",
+    "knowledge",
+    "skills",
+    "templates",
+    "tools",
+    "LICENSE",
+    "NOTICE.md",
+    "README.md",
+  ]);
+  const seen = new Set();
+  for (const entry of entries) {
+    const path = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+    if (
+      !path ||
+      /[\\\x00-\x1f\x7f]/.test(path) ||
+      path
+        .split("/")
+        .some(
+          (part) => !part || part === "." || part === ".." || part === "bin",
+        ) ||
+      !roots.has(path.split("/")[0]) ||
+      /(?:^|\/)\.?(?:mcp|lsp)(?:\.json|\/|$)/i.test(path) ||
+      (path.startsWith(".claude-plugin/") &&
+        path !== ".claude-plugin/plugin.json") ||
+      (path.startsWith(".codex-plugin/") &&
+        path !== ".codex-plugin/plugin.json") ||
+      seen.has(path)
+    )
+      throw Error("Release ZIP contains an unreviewed or unsafe entry");
+    seen.add(path);
+  }
+  const modes = command("unzip", ["-Zl", zip])
+    .split("\n")
+    .filter((line) => /^[^\s]\S{9}\s+\d+\.\d+\s/.test(line));
+  if (
+    modes.length !== entries.length ||
+    modes.some((line) => !/^[-d][rwx-]{9}\s+/.test(line))
+  )
+    throw Error(
+      "Release ZIP must contain only regular files and directories; links and special entries are forbidden",
+    );
+}
+export async function printExecutionNotice(
+  write = process.stderr.write.bind(process.stderr),
+) {
+  await new Promise((resolve, reject) =>
+    write(
+      "Publisher notice (full plugin behavior):\n" +
+        clientPluginNotice +
+        "\nThis ZIP run is edit-only: non-managed hooks, shell tools, Skill shell execution, agents and MCP are disabled. Managed policy still applies. The parent Agent must review/build/test. This notice is emitted on every run; no seen/consent marker is written.\n",
+      (error) => (error ? reject(error) : resolve()),
+    ),
+  );
+}
+// Read text from the verified ZIP without extracting or executing publisher code.
+// Fail closed when the publisher changes the notice/manifest contract.
+export function verifyPublisherNotice(zip, release) {
+  const manifest = JSON.parse(
+    command("unzip", ["-p", zip, ".claude-plugin/plugin.json"], {
+      maxBuffer: 64 * 1024,
+    }),
+  );
+  const keys = new Set([
+    "name",
+    "displayName",
+    "version",
+    "description",
+    "author",
+    "homepage",
+    "repository",
+    "license",
+    "keywords",
+  ]);
+  if (Object.keys(manifest).some((key) => !keys.has(key)))
+    throw Error("Publisher manifest contains an unreviewed capability");
+  const script = command("unzip", ["-p", zip, "hooks/first-run-notice.sh"], {
+    maxBuffer: 64 * 1024,
+  });
+  const matches = [...script.matchAll(/^msg="([^"\r\n]*)"$/gm)];
+  if (
+    manifest.name !== "sendbird-client" ||
+    manifest.version !== release.slice(1) ||
+    matches.length !== 1
+  )
+    throw Error(
+      "Publisher notice metadata changed; update the CLI bridge before execution",
+    );
+  const message = matches[0][1]
+    .replace("${display:-$name}", manifest.displayName || manifest.name)
+    .replace("${repo}", manifest.repository);
+  if (message !== clientPluginNotice)
+    throw Error(
+      "Publisher notice changed; review and update the CLI bridge before execution",
+    );
+}
+// Keep this helper standalone: skills can be copied outside the npm package.
+// Mirrors schema-v1's fields and conditional rules; do not silently accept a
+// different plugin contract after an upgrade.
+function validateSummary(value) {
+  const fail = () => {
+    throw Error("Invalid client plugin schema-v1 run summary");
+  };
+  const str = (v) => typeof v === "string";
+  const text = (v) => str(v) && v.length > 0;
+  const array = (v, check) => Array.isArray(v) && v.every(check);
+  const object = (v, required, optional = {}) => {
+    if (!v || typeof v !== "object" || Array.isArray(v)) return false;
+    const fields = { ...required, ...optional };
+    return (
+      Object.keys(v).every((k) => Object.hasOwn(fields, k)) &&
+      Object.entries(required).every(
+        ([k, f]) => Object.hasOwn(v, k) && f(v[k]),
+      ) &&
+      Object.entries(optional).every(
+        ([k, f]) => !Object.hasOwn(v, k) || f(v[k]),
+      )
+    );
+  };
+  const status = (v) =>
+    ["completed", "needs_input", "failed", "declined"].includes(v);
+  const changes = (v) =>
+    array(v, (x) =>
+      object(
+        x,
+        {
+          path: (p) =>
+            text(p) &&
+            !p.includes("\\") &&
+            !/^[a-z]:/i.test(p) &&
+            p.split("/").every((part) => part && part !== "." && part !== ".."),
+          action: (a) => ["created", "modified", "deleted"].includes(a),
+        },
+        { summary: str },
+      ),
+    );
+  const questions = (v) =>
+    array(v, (x) =>
+      object(
+        x,
+        {
+          id: (id) => str(id) && /^[a-z][a-z0-9-]*$/.test(id),
+          question: text,
+        },
+        {
+          options: (a) => array(a, str) && a.length > 0,
+          labels: (a) => array(a, str),
+          type: (v) => ["single", "multi", "text"].includes(v),
+          when: (v) =>
+            v !== null &&
+            typeof v === "object" &&
+            !Array.isArray(v) &&
+            Object.values(v).every((a) => array(a, str)),
+        },
+      ),
+    );
+  if (
+    !object(
+      value,
+      {
+        schemaVersion: (v) => v === "1",
+        skill: (v) => str(v) && /^[a-z][a-z0-9-]*$/.test(v),
+        status,
+        changes,
+        manualSteps: (v) => array(v, text),
+      },
+      {
+        project: (v) =>
+          object(
+            v,
+            {},
+            {
+              platform: (p) => ["ios", "android", "js", "unknown"].includes(p),
+              host: str,
+              products: (p) => array(p, str) && new Set(p).size === p.length,
+            },
+          ),
+        steps: (v) =>
+          array(v, (x) =>
+            object(
+              x,
+              {
+                description: text,
+                status: (s) => ["done", "skipped", "failed"].includes(s),
+              },
+              { detail: str },
+            ),
+          ),
+        apis: (v) => array(v, (x) => object(x, { symbol: text, source: text })),
+        questions,
+        reason: text,
+      },
+    )
+  )
+    fail();
+  if (
+    value.status === "needs_input" &&
+    (!value.questions?.length || value.changes.length)
+  )
+    fail();
+  if (["failed", "declined"].includes(value.status) && !value.reason) fail();
+  return value;
+}
+
+// Preserve report structure while removing credential-shaped text and known
+// inherited secrets. This is output protection, not a filesystem sandbox.
+export function redactReport(value, sensitiveValues) {
+  if (typeof value === "string") {
+    let safe = value
+      .replace(
+        /-----BEGIN (?:[A-Z0-9]+ )?PRIVATE KEY-----[\s\S]*?-----END (?:[A-Z0-9]+ )?PRIVATE KEY-----/g,
+        "[REDACTED]",
+      )
+      .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 [REDACTED]")
+      .replace(/(https?:\/\/)[^\s/@:]+:[^\s/@]+@/gi, "$1[REDACTED]@")
+      .replace(
+        /\b((?:access[_-]?token|refresh[_-]?token|session[_-]?token|oauth[_-]?token|api[_-]?(?:token|key)|client[_-]?secret|password)["']?\s*[:=]\s*)(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s,;&]+)/gi,
+        "$1[REDACTED]",
+      );
+    for (const secret of sensitiveValues)
+      safe = safe.replaceAll(secret, "[REDACTED]");
+    return safe;
+  }
+  if (Array.isArray(value))
+    return value.map((v) => redactReport(v, sensitiveValues));
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [
+        k,
+        redactReport(v, sensitiveValues),
+      ]),
+    );
+  return value;
+}
+
+export function parseRun(events, { sensitiveValues = [] } = {}) {
+  // Terminal result.result can contain only the final text fragment. Assemble
+  // every top-level assistant text block before finding the final JSON fence.
+  const init = events.find((e) => e.type === "system" && e.subtype === "init");
+  if (
+    !init?.plugins?.some(
+      (p) => (typeof p === "string" ? p : p.name) === "sendbird-client",
+    )
+  )
+    throw Error("Sendbird client plugin was not loaded");
+  const body = events
+    .filter((e) => e.type === "assistant" && !e.parent_tool_use_id)
+    .flatMap((e) => e.message?.content ?? [])
+    .filter((b) => b.type === "text")
+    .map((b) => b.text)
+    .join("");
+  const fences = [...body.matchAll(/```json\s*([\s\S]*?)```/g)];
+  if (!fences.length) throw Error("Plugin returned no JSON run summary");
+  const summary = validateSummary(JSON.parse(fences.at(-1)[1]));
+  const result = events.findLast((e) => e.type === "result");
+  if (!result || result.is_error || result.subtype !== "success")
+    throw Error(
+      "Claude did not finish successfully; partial changes may exist",
+    );
+  const metric = (value) => {
+    if (value == null) return null;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
+      throw Error("Invalid Claude result metric");
+    return value;
+  };
+  return {
+    summary: redactReport(
+      summary,
+      sensitiveValues
+        .filter((s) => typeof s === "string" && s.length >= 4)
+        .sort((a, b) => b.length - a.length),
+    ),
+    cost_usd: metric(result.total_cost_usd),
+    duration_ms: metric(result.duration_ms),
+    verification:
+      "Plugin report only; parent must independently verify build and runtime",
+  };
+}
+
+export function childEnvironment(parent, appId) {
+  // Only Claude authentication and necessary runtime settings are inherited.
+  // GitHub/cloud/Sendbird credentials are used by neither the child nor its tools.
+  const allowed = new Set([
+    "PATH",
+    "HOME",
+    "USER",
+    "LOGNAME",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "SystemRoot",
+    "WINDIR",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+    "LANG",
+    "LC_ALL",
+    "LC_CTYPE",
+    "TZ",
+    "TERM",
+    "NO_COLOR",
+    "CLAUDE_CONFIG_DIR",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+    "CLAUDE_CODE_OAUTH_TOKEN",
+  ]);
+  const env = Object.fromEntries(
+    Object.entries(parent).filter(([key]) => allowed.has(key)),
+  );
+  return { ...env, SENDBIRD_APP_ID: appId, SENDBIRD_NONINTERACTIVE: "1" };
+}
+
+function command(bin, args, options = {}) {
+  return execFileSync(bin, args, {
+    encoding: "utf8",
+    timeout: 60000,
+    maxBuffer: 4 * 1024 * 1024,
+    env: bin === "gh" ? { ...process.env, GH_HOST: "github.com" } : process.env,
+    ...options,
+  });
+}
+
+// Bound the read itself, not just the decoded string: a generated brief may
+// accidentally be huge, a device or a FIFO. Never launch external tools for it.
+function readBounded(file, limit) {
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > limit)
+      throw Error("Expected a bounded regular file");
+    const bytes = Buffer.alloc(limit + 1);
+    let size = 0;
+    while (size < bytes.length) {
+      const count = readSync(fd, bytes, size, bytes.length - size, null);
+      if (!count) break;
+      size += count;
+    }
+    if (size > limit) throw Error("File exceeds the byte limit");
+    return bytes.subarray(0, size);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+let stage = "input";
+async function run() {
+  if (process.argv.length === 3 && ["--help", "-h"].includes(process.argv[2])) {
+    process.stdout.write(
+      "Run the Sendbird client plugin from a checksum-verified release ZIP.\n" +
+        "Usage: node client-plugin-bridge.mjs --project DIR --app-id ID --prompt-file FILE\n" +
+        "Options: --release TAG --sha256 REVIEWED_DIGEST --budget USD --timeout-seconds N --model MODEL; default: reviewed v0.1.74, never latest\n" +
+        "Requires macOS/Linux, unzip, authenticated Claude Code 2.1.304+ and GitHub release access. Brief must contain no credentials and be at most 64 KiB.\n" +
+        "Exit codes: 0 plugin completed (independent verification required); 2 needs_input/failed/declined; 1 handoff error.\n",
+    );
+    return;
+  }
+  const options = {};
+  for (let i = 2; i < process.argv.length; i += 2) {
+    const key = process.argv[i];
+    if (
+      ![
+        "--project",
+        "--app-id",
+        "--prompt-file",
+        "--release",
+        "--sha256",
+        "--budget",
+        "--timeout-seconds",
+        "--model",
+      ].includes(key) ||
+      !process.argv[i + 1]
+    )
+      throw Error(
+        "Use --project DIR --app-id ID --prompt-file FILE [--release TAG] [--budget USD] [--timeout-seconds N] [--model MODEL]",
+      );
+    if (options[key]) throw Error(`Duplicate option ${key}`);
+    options[key] = process.argv[i + 1];
+  }
+  if (!["darwin", "linux"].includes(process.platform))
+    throw Error(
+      "ZIP execution currently requires macOS/Linux; use the native plugin or explicitly choose guide-only work on Windows",
+    );
+  const project = resolve(options["--project"] ?? "");
+  if (
+    !options["--project"] ||
+    !statSync(project).isDirectory() ||
+    !/^[a-zA-Z0-9_-]{1,128}$/.test(options["--app-id"] ?? "") ||
+    !options["--prompt-file"]
+  )
+    throw Error("Project, App ID, and non-secret prompt file are required");
+  const budget = Number(options["--budget"] ?? "3");
+  const timeout = Number(options["--timeout-seconds"] ?? "600") * 1000;
+  if (
+    !Number.isFinite(budget) ||
+    budget <= 0 ||
+    !Number.isFinite(timeout) ||
+    timeout <= 0 ||
+    timeout > 2_147_483_647
+  )
+    throw Error("Budget and timeout must be positive numbers");
+  // Validate the brief before network access or launching a paid session.
+  const prompt = new TextDecoder("utf-8", { fatal: true }).decode(
+    readBounded(resolve(options["--prompt-file"]), 64 * 1024),
+  );
+  if (
+    !prompt.trim() ||
+    prompt.includes("\0") ||
+    Buffer.byteLength(prompt) > 64 * 1024
+  )
+    throw Error("Brief must contain 1–64 KiB of non-secret text");
+  stage = "prerequisites";
+  // Older hosts can silently ignore unknown settings. Require the first host
+  // version verified for this edit-only policy rather than weakening it.
+  const version = command("claude", ["--version"])
+    .trim()
+    .match(/^(\d+)\.(\d+)\.(\d+)\b/);
+  const minimum = [2, 1, 304];
+  if (
+    !version ||
+    minimum.reduce(
+      (order, value, i) => order || Number(version[i + 1]) - value,
+      0,
+    ) < 0
+  )
+    throw Error(
+      "Edit-only handoff requires Claude Code 2.1.304 or later; update Claude before retrying",
+    );
+  const auth = JSON.parse(
+    command("claude", ["auth", "status"], {
+      env: childEnvironment(process.env, options["--app-id"]),
+    }),
+  );
+  if (!auth.loggedIn) throw Error("Claude CLI login is required");
+  stage = "release";
+  const release = options["--release"] ?? reviewedClientRelease.tag;
+  if (!/^v\d+\.\d+\.\d+(?:[-.][a-zA-Z0-9.-]+)?$/.test(release))
+    throw Error("Unsupported release tag; latest is not an audited release");
+  const expectedDigest =
+    options["--sha256"] ??
+    (release === reviewedClientRelease.tag ? reviewedClientRelease.sha256 : "");
+  if (
+    !/^[a-fA-F0-9]{64}$/.test(expectedDigest) ||
+    (options["--sha256"] && !options["--release"])
+  )
+    throw Error(
+      "An explicit release and independently reviewed SHA-256 are required for an unpinned release",
+    );
+  const dir = mkdtempSync(join(tmpdir(), "sendbird-client-"));
+  try {
+    command("gh", [
+      "release",
+      "download",
+      release,
+      "-R",
+      "sendbird/sendbird-client-plugin",
+      "-p",
+      "sendbird-client-*.zip*",
+      "-D",
+      dir,
+    ]);
+    const names = readdirSync(dir).filter((n) => n.endsWith(".zip"));
+    if (names.length !== 1) throw Error("Expected exactly one release ZIP");
+    const zip = names[0];
+    const checksum = readBounded(join(dir, `${zip}.sha256`), 4096)
+      .toString("utf8")
+      .trim();
+    const match = checksum.match(/^([a-fA-F0-9]{64})\s+\*?(.+)$/);
+    if (!match || match[2] !== zip)
+      throw Error("Checksum manifest does not identify the release ZIP");
+    const zipFile = join(dir, zip);
+    if (
+      zip !== `sendbird-client-${release.slice(1)}.zip` ||
+      statSync(zipFile).size > 16 * 1024 * 1024
+    )
+      throw Error("Unexpected or oversized release ZIP");
+    const digest = createHash("sha256")
+      .update(readBounded(zipFile, 16 * 1024 * 1024))
+      .digest("hex");
+    if (digest !== match[1].toLowerCase())
+      throw Error("Release checksum mismatch");
+    if (digest !== expectedDigest.toLowerCase())
+      throw Error("Release differs from the independently reviewed SHA-256");
+    verifyArchive(zipFile);
+    process.stderr.write(
+      `Client plugin ${release}: matches reviewed SHA-256 and release checksum (not a publisher signature); edit-only handoff; parent must install/build/test\n`,
+    );
+    stage = "execution";
+    const args = [
+      "-p",
+      "--append-system-prompt",
+      "This is an edit-only handoff. Read and edit customer source files using the loaded client plugin. Do not run commands, delegate agents, install packages, build, test, access a browser, or modify tool configuration. Report installation/build/runtime checks as skipped steps for the parent agent. Reserve manualSteps for missing external prerequisites under the plugin schema. Never claim these checks were executed. Finish with the schema-v1 JSON summary.",
+      "--restricted",
+      "--plugin-dir",
+      join(dir, zip),
+      "--setting-sources",
+      "",
+      "--settings",
+      '{"disableAllHooks":true,"disableSkillShellExecution":true}',
+      "--strict-mcp-config",
+      "--mcp-config",
+      '{"mcpServers":{}}',
+      "--permission-mode",
+      "acceptEdits",
+      // Keep tool availability and explicit denials: a Skill must not grant
+      // shell/agent execution through its own allowed-tools declaration.
+      "--tools",
+      "Read,Grep,Glob,Edit,Write,MultiEdit,Skill",
+      "--allowedTools",
+      "Read,Grep,Glob,Edit,Write,MultiEdit,Skill",
+      "--disallowedTools",
+      "Bash,PowerShell,Agent,Task,WebFetch,WebSearch,mcp__*",
+      "--output-format",
+      "stream-json",
+      "--verbose",
+      "--no-session-persistence",
+      "--max-budget-usd",
+      String(budget),
+    ];
+    if (options["--model"]) args.push("--model", options["--model"]);
+    // Flush the caller-visible notice before starting any plugin/model execution.
+    stage = "notice";
+    verifyPublisherNotice(zipFile, release);
+    await printExecutionNotice();
+    stage = "execution";
+    const child = spawn("claude", args, {
+      cwd: project,
+      env: childEnvironment(process.env, options["--app-id"]),
+      stdio: ["pipe", "pipe", "pipe"],
+      detached: true,
+    });
+    const events = [];
+    let pending = "",
+      bytes = 0,
+      stopReason,
+      killTimer,
+      stopped;
+    const stop = (reason) => {
+      if (stopReason) return;
+      stopReason = reason;
+      try {
+        process.kill(-child.pid, "SIGTERM");
+      } catch {}
+      stopped = new Promise((done) => {
+        killTimer = setTimeout(() => {
+          try {
+            process.kill(-child.pid, "SIGKILL");
+          } catch {}
+          done();
+        }, 3000);
+      });
+    };
+    const interrupted = (signal) => {
+      interruptionExitCode = signal === "SIGINT" ? 130 : 143;
+      stop("Client handoff interrupted; inspect project edits before retrying");
+    };
+    const onInterrupt = () => interrupted("SIGINT");
+    const onTerminate = () => interrupted("SIGTERM");
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    const timer = setTimeout(
+      () => stop("Claude timed out; inspect changes before retrying"),
+      timeout,
+    );
+    child.stdout.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      bytes += Buffer.byteLength(chunk, "utf8");
+      if (bytes > 16 * 1024 * 1024) {
+        stop("Claude output limit exceeded");
+        return;
+      }
+      pending += chunk.toString();
+      const lines = pending.split("\n");
+      pending = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          events.push(JSON.parse(line));
+        } catch {
+          stop("Invalid Claude JSON stream");
+        }
+      }
+    });
+    // Raw model logs can include customer data; do not echo or persist them.
+    child.stderr.on("data", () => {});
+    child.stdin.on("error", () =>
+      stop("Cannot send the brief; inspect project edits before retrying"),
+    );
+    child.stdin.end(prompt);
+    let code;
+    try {
+      code = await new Promise((res, rej) => {
+        child.once("error", rej);
+        child.once("close", res);
+      });
+    } finally {
+      clearTimeout(timer);
+      // The direct child may close while a descendant ignores SIGTERM and
+      // closes its pipes. Still finish process-group escalation before cleanup.
+      if (stopped) await stopped;
+      clearTimeout(killTimer);
+      process.removeListener("SIGINT", onInterrupt);
+      process.removeListener("SIGTERM", onTerminate);
+    }
+    if (stopReason) throw Error(stopReason);
+    if (pending.trim()) events.push(JSON.parse(pending));
+    if (code !== 0)
+      throw Error(
+        "Claude exited unsuccessfully; inspect project changes before retrying",
+      );
+    stage = "contract";
+    const sensitiveValues = Object.entries(process.env)
+      .filter(([key]) =>
+        /(?:^|_)(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|PRIVATE_KEY|COOKIE|CREDENTIAL)(?:$|_)/i.test(
+          key,
+        ),
+      )
+      .map(([, value]) => value);
+    const result = {
+      release,
+      checksum_sha256: digest,
+      ...parseRun(events, { sensitiveValues }),
+    };
+    process.stdout.write(JSON.stringify(result) + "\n");
+    if (result.summary.status !== "completed") process.exitCode = 2;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+let interruptionExitCode;
+
+export async function main() {
+  stage = "input";
+  interruptionExitCode = undefined;
+  await run().catch(() => {
+    // Model and SDK errors can contain secrets. Emit a fixed diagnostic instead.
+    const hints = {
+      input: "Check macOS/Linux, required paths, App ID, budget, and timeout.",
+      notice:
+        "Cannot verify or emit the publisher notice. Check unzip, the release notice/metadata and stderr; update the bridge if the publisher notice changed. No plugin process was started.",
+      prerequisites:
+        "Update to Claude Code 2.1.304 or later and check Claude login.",
+      release: "Check GitHub access, selected release, and checksum.",
+      execution:
+        "Process failed, timed out, or exceeded limits; inspect project edits.",
+      contract:
+        "Plugin loading, summary schema, or terminal success check failed; inspect project edits.",
+    };
+    process.stderr.write(
+      interruptionExitCode
+        ? "Client handoff interrupted (E_CLIENT_INTERRUPTED): child stopped; inspect project edits before retrying.\n"
+        : `Client handoff failed (E_CLIENT_${stage.toUpperCase()}): ${hints[stage]} Do not blindly retry.\n`,
+    );
+    process.exitCode = interruptionExitCode ?? 1;
+  });
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
+) {
+  await main();
+}