@the-open-engine/zeroshot 6.28.0 → 6.29.0

package/lib/target/hosted-run/input.js

@@ -0,0 +1,200 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveHostedInput = resolveHostedInput;
+exports.githubToken = githubToken;
+exports.providerKey = providerKey;
+exports.validateHostedOptions = validateHostedOptions;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const SUBMISSION_KEY = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{12}$/i;
+const CAPSULE_SIZES = new Set(['tiny', 'small', 'standard', 'large']);
+function validRepository(value) {
+    if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value))
+        return false;
+    return value.split('/').every((segment) => segment !== '.' && segment !== '..');
+}
+function validModel(value) {
+    return (value.length <= 256 && /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value));
+}
+function repositoryFromRemote(cwd = process.cwd()) {
+    let remote;
+    try {
+        remote = (0, node_child_process_1.execFileSync)('git', ['remote', 'get-url', 'origin'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+    const match = remote.match(/^(?:git@github\.com:|ssh:\/\/git@github\.com\/|https?:\/\/github\.com\/)([^/]+\/[^/]+?)(?:\.git)?$/);
+    const repository = match?.[1];
+    return repository && validRepository(repository) ? repository : null;
+}
+function isolationProfile(options) {
+    return options.pr ? 'isolation.pr@1' : 'isolation.worktree@1';
+}
+function providerProfile(options) {
+    return options.pr ? 'provider.codex-openrouter-pr@1' : 'provider.codex-openrouter@1';
+}
+function promptRequest(prompt, options) {
+    return {
+        source: 'prompt',
+        prompt,
+        artifacts: [],
+        isolationProfile: isolationProfile(options),
+        providerProfile: providerProfile(options),
+    };
+}
+function issueRequest(issue, options) {
+    return {
+        source: 'issue',
+        issue,
+        artifacts: [],
+        isolationProfile: isolationProfile(options),
+        providerProfile: providerProfile(options),
+    };
+}
+function issueInput(value, options) {
+    const shorthand = value.match(/^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)#([1-9][0-9]*)$/);
+    if (shorthand?.[1] && shorthand[2] && validRepository(shorthand[1])) {
+        const issue = `https://github.com/${shorthand[1]}/issues/${shorthand[2]}`;
+        return { repository: shorthand[1], request: issueRequest(issue, options) };
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    const match = url.pathname.match(/^\/([^/]+)\/([^/]+)\/issues\/([1-9][0-9]*)\/?$/);
+    const repository = match?.[1] && match[2] ? `${match[1]}/${match[2]}` : '';
+    if (url.hostname !== 'github.com' || !match || !validRepository(repository))
+        return null;
+    return { repository, request: issueRequest(url.href, options) };
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        throw new Error('zeroshot run - requires piped input');
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += value.length;
+        if (bytes > 1024 * 1024)
+            throw new Error('hosted task input exceeds 1 MiB');
+        chunks.push(value);
+    }
+    const value = Buffer.concat(chunks).toString('utf8').trim();
+    if (!value)
+        throw new Error('hosted task input is empty');
+    return value;
+}
+function readTaskFile(filename) {
+    const flags = node_fs_1.default.constants.O_RDONLY | (node_fs_1.default.constants.O_NOFOLLOW ?? 0) | (node_fs_1.default.constants.O_NONBLOCK ?? 0);
+    let descriptor;
+    try {
+        descriptor = node_fs_1.default.openSync(filename, flags);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR' || code === 'EISDIR')
+            return null;
+        if (code === 'ELOOP')
+            throw new Error(`hosted task file must not be a symlink: ${filename}`);
+        throw error;
+    }
+    try {
+        if (!node_fs_1.default.fstatSync(descriptor).isFile())
+            return null;
+        return node_fs_1.default.readFileSync(descriptor, 'utf8');
+    }
+    finally {
+        node_fs_1.default.closeSync(descriptor);
+    }
+}
+async function resolveHostedInput(input, options, environment = process.env) {
+    const explicitIssue = issueInput(input, options);
+    if (explicitIssue)
+        return explicitIssue;
+    const repository = options.repository ?? environment['ZEROSHOT_REPOSITORY'] ?? repositoryFromRemote();
+    if (!validRepository(repository ?? '')) {
+        throw new Error('hosted runs need a GitHub repository; use org/repo#123, --repository owner/name, ' +
+            'ZEROSHOT_REPOSITORY, or run inside a GitHub checkout');
+    }
+    if (/^[1-9][0-9]*$/.test(input)) {
+        return { repository: repository, request: issueRequest(input, options) };
+    }
+    const prompt = input === '-' ? await readStdin() : (readTaskFile(node_path_1.default.resolve(input)) ?? input);
+    if (!prompt.trim())
+        throw new Error('hosted task input is empty');
+    return { repository: repository, request: promptRequest(prompt.trim(), options) };
+}
+function githubToken(environment) {
+    const configured = environment['GH_TOKEN'] ?? environment['GITHUB_TOKEN'];
+    if (configured?.trim())
+        return configured.trim();
+    try {
+        const token = (0, node_child_process_1.execFileSync)('gh', ['auth', 'token'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (token)
+            return token;
+    }
+    catch {
+        // The actionable error below covers missing and unauthenticated gh alike.
+    }
+    throw new Error('hosted runs require GH_TOKEN/GITHUB_TOKEN or an authenticated gh CLI');
+}
+function providerKey(environment) {
+    const key = environment['OPENROUTER_API_KEY'];
+    if (!key?.trim())
+        throw new Error('hosted Codex runs require OPENROUTER_API_KEY');
+    return key.trim();
+}
+function validateHostedOptions(options) {
+    const unsupported = [
+        ['config', '--config'],
+        ['docker', '--docker'],
+        ['worktree', '--worktree'],
+        ['dockerImage', '--docker-image'],
+        ['strictSchema', '--strict-schema'],
+        ['ship', '--ship'],
+        ['prBase', '--pr-base'],
+        ['mergeQueue', '--merge-queue'],
+        ['closeIssue', '--close-issue'],
+        ['workers', '--workers'],
+        ['gitlab', '--gitlab'],
+        ['jira', '--jira'],
+        ['devops', '--devops'],
+        ['linear', '--linear'],
+        ['mount', '--mount'],
+        ['noMounts', '--no-mounts'],
+        ['containerHome', '--container-home'],
+    ];
+    const selected = unsupported
+        .filter(([name]) => options[name] !== undefined && options[name] !== false)
+        .map(([, flag]) => flag);
+    if (options.provider && options.provider !== 'codex')
+        selected.push('--provider');
+    if (selected.length)
+        throw new Error(`hosted runs do not support ${selected.join(', ')}`);
+    if (!options.target)
+        throw new Error('hosted runs require --target');
+    if (options.model !== undefined && !validModel(options.model)) {
+        throw new Error('hosted runs require an exact provider/model slug');
+    }
+    if (!CAPSULE_SIZES.has(options.size ?? 'standard')) {
+        throw new Error('hosted runs require --size tiny, small, standard, or large');
+    }
+    if (options.submissionKey !== undefined && !SUBMISSION_KEY.test(options.submissionKey)) {
+        throw new Error('hosted runs require --submission-key to be a random UUID');
+    }
+}

package/lib/target/hosted-run.d.ts

@@ -0,0 +1,4 @@
+export { HostedRunHttpError } from './hosted-run/client.ts';
+export { cancelHostedRun, runHosted, statusHostedRun } from './hosted-run/commands.ts';
+export { resolveHostedInput, validateHostedOptions } from './hosted-run/input.ts';
+export type { HostedOptions, HostedRunDependencies, HostedRunIntent, } from './hosted-run/contracts.ts';

package/lib/target/hosted-run.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateHostedOptions = exports.resolveHostedInput = exports.statusHostedRun = exports.runHosted = exports.cancelHostedRun = exports.HostedRunHttpError = void 0;
+var client_ts_1 = require("./hosted-run/client.js");
+Object.defineProperty(exports, "HostedRunHttpError", { enumerable: true, get: function () { return client_ts_1.HostedRunHttpError; } });
+var commands_ts_1 = require("./hosted-run/commands.js");
+Object.defineProperty(exports, "cancelHostedRun", { enumerable: true, get: function () { return commands_ts_1.cancelHostedRun; } });
+Object.defineProperty(exports, "runHosted", { enumerable: true, get: function () { return commands_ts_1.runHosted; } });
+Object.defineProperty(exports, "statusHostedRun", { enumerable: true, get: function () { return commands_ts_1.statusHostedRun; } });
+var input_ts_1 = require("./hosted-run/input.js");
+Object.defineProperty(exports, "resolveHostedInput", { enumerable: true, get: function () { return input_ts_1.resolveHostedInput; } });
+Object.defineProperty(exports, "validateHostedOptions", { enumerable: true, get: function () { return input_ts_1.validateHostedOptions; } });

package/lib/target/target-session.d.ts

@@ -20,6 +20,7 @@ export interface TargetSessionDeps {
         readonly tokenEndpoint: string;
         readonly revocationEndpoint?: string;
         readonly clientId: string;
+        readonly capsuleApiBaseUrl: string;
     };
 }
 export declare function targetLogin(targetName: string, target: TargetRecord, credentialStore: TargetCredentialStore, acquireLock: () => Promise<() => Promise<void>>, settings: SettingsPort, deps: TargetSessionDeps): Promise<{

package/lib/target/target-session.js

@@ -30,7 +30,7 @@ async function targetLogin(targetName, target, credentialStore, acquireLock, set
             // Browser open is best-effort
         }
     }
-    const tokenResponse = await (0, device_flow_ts_1.pollForToken)(tokenEndpoint, clientId, codeResponse.device_code, codeResponse.interval, codeResponse.expires_in, http, clock);
+    const tokenResponse = await (0, device_flow_ts_1.pollForToken)(tokenEndpoint, clientId, codeResponse.device_code, codeResponse.interval, codeResponse.expires_in, http, clock, undefined, { token: target.deviceToken, label: 'Zeroshot CLI' });
     if (!tokenResponse.organization) {
         throw new device_flow_ts_1.UnboundSessionError(codeResponse.verification_uri);
     }
@@ -59,6 +59,7 @@ async function refreshAccessToken(targetName, target, credentialStore, acquireLo
             grant_type: 'refresh_token',
             refresh_token: currentRefreshToken,
             client_id: clientId,
+            audience: 'capsule',
         });
         let tokenResponse;
         const response = await http.fetch(tokenEndpoint, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.28.0",
+  "version": "6.29.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -60,6 +60,15 @@
     "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js tests/hosted-session/coordinator.test.js",
     "test:cluster-package": "npm run build:agent-cli-provider && npm run build:cluster && npm run build:target && node --test tests/cluster/package.test.js",
     "dev:link": "npm link",
+    "opcore:status": "opcore status --repo . --json",
+    "opcore:scan": "opcore --repo . --json",
+    "opcore:check": "node scripts/opcore-introduced-check.js",
+    "opcore:check:staged": "node scripts/opcore-introduced-check.js --staged",
+    "opcore:install:rust-metrics": "cargo install rust-code-analysis-cli --version 0.0.25 --locked",
+    "opcore:graph:build": "opcore graph build --repo . --json",
+    "opcore:graph:update": "opcore graph update --repo . --json",
+    "opcore:measure": "opcore measure --repo . --json",
+    "audit:production": "node scripts/audit-production-dependencies.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "validate:templates": "node scripts/validate-templates.js",
@@ -122,7 +131,7 @@
     "url": "https://github.com/the-open-engine/zeroshot/issues"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   },
   "publishConfig": {
     "access": "public",
@@ -148,6 +157,9 @@
   "files": [
     "src/",
     "lib/",
+    "!src/target/register-hosted-commands.ts",
+    "!lib/target/register-hosted-commands.js",
+    "!lib/target/register-hosted-commands.d.ts",
     "bin/",
     "cli/",
     "task-lib/",
@@ -169,8 +181,8 @@
     "commander": "^14.0.2",
     "node-pty": "^1.1.0",
     "omelette": "^0.4.17",
-    "pidusage": "^4.0.1",
     "open": "^10.1.0",
+    "pidusage": "^4.0.1",
     "proper-lockfile": "^4.1.2"
   },
   "optionalDependencies": {
@@ -196,6 +208,7 @@
     "jscpd": "^3.5.10",
     "lint-staged": "^16.2.7",
     "mocha": "^11.7.5",
+    "opcore": "0.2.1",
     "prettier": "^3.7.4",
     "semantic-release": "^25.0.2",
     "sinon": "^21.0.0",

package/scripts/audit-production-dependencies.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+
+const severityRank = new Map([
+  ['info', 0],
+  ['low', 1],
+  ['moderate', 2],
+  ['high', 3],
+  ['critical', 4],
+]);
+const approvedLeafAdvisories = new Map([
+  ['brace-expansion', new Set(['1123898', '1130591'])],
+  ['smol-toml', new Set(['1115393'])],
+]);
+const approvedLeafPaths = new Map([
+  ['brace-expansion', 'node_modules/opcore/node_modules/brace-expansion'],
+  ['smol-toml', 'node_modules/opcore/node_modules/smol-toml'],
+]);
+const approvedVersions = new Map([
+  ['node_modules/opcore', '0.2.1'],
+  ['node_modules/opcore/node_modules/brace-expansion', '5.0.6'],
+  ['node_modules/opcore/node_modules/smol-toml', '1.6.0'],
+]);
+
+function isRelevant(vulnerability) {
+  return (severityRank.get(vulnerability.severity) ?? Number.POSITIVE_INFINITY) >= 2;
+}
+
+function hasExpectedNodes(name, vulnerability) {
+  const nodes = vulnerability.nodes;
+  if (!Array.isArray(nodes) || nodes.length === 0) return false;
+  const leafPath = approvedLeafPaths.get(name);
+  if (leafPath !== undefined) return nodes.length === 1 && nodes[0] === leafPath;
+  if (name === 'opcore') return nodes.length === 1 && nodes[0] === 'node_modules/opcore';
+  return nodes.every((node) => node.startsWith('node_modules/opcore/node_modules/'));
+}
+
+function isApprovedLeaf(name, vulnerability) {
+  const approvedSources = approvedLeafAdvisories.get(name);
+  if (approvedSources === undefined || !hasExpectedNodes(name, vulnerability)) return false;
+  if (!Array.isArray(vulnerability.via) || vulnerability.via.length === 0) return false;
+  return vulnerability.via.every(
+    (advisory) =>
+      advisory !== null &&
+      typeof advisory === 'object' &&
+      approvedSources.has(String(advisory.source))
+  );
+}
+
+function isApprovedVulnerability(name, vulnerabilities, memo, active) {
+  if (memo.has(name)) return memo.get(name);
+  if (active.has(name)) return false;
+  const vulnerability = vulnerabilities[name];
+  if (vulnerability === undefined || !hasExpectedNodes(name, vulnerability)) return false;
+  if (isApprovedLeaf(name, vulnerability)) {
+    memo.set(name, true);
+    return true;
+  }
+  if (!Array.isArray(vulnerability.via) || vulnerability.via.length === 0) return false;
+  if (!vulnerability.via.every((dependency) => typeof dependency === 'string')) return false;
+
+  active.add(name);
+  const approved = vulnerability.via.every((dependency) =>
+    isApprovedVulnerability(dependency, vulnerabilities, memo, active)
+  );
+  active.delete(name);
+  memo.set(name, approved);
+  return approved;
+}
+
+function exceptionVersionsMatch(lock) {
+  if (lock?.packages?.['']?.dependencies?.opcore !== '0.2.1') return false;
+  return Array.from(approvedVersions).every(
+    ([packagePath, version]) => lock?.packages?.[packagePath]?.version === version
+  );
+}
+
+function evaluateAudit(payload, lock) {
+  if (payload === null || typeof payload !== 'object' || payload.error !== undefined) {
+    throw new Error('npm audit did not return a valid vulnerability report');
+  }
+  const vulnerabilities = payload.vulnerabilities;
+  if (vulnerabilities === null || typeof vulnerabilities !== 'object') {
+    throw new Error('npm audit report is missing vulnerabilities');
+  }
+
+  const relevant = Object.entries(vulnerabilities).filter(([, vulnerability]) =>
+    isRelevant(vulnerability)
+  );
+  const memo = new Map();
+  const allowed = relevant.filter(([name]) =>
+    isApprovedVulnerability(name, vulnerabilities, memo, new Set())
+  );
+  if (allowed.length > 0 && !exceptionVersionsMatch(lock)) {
+    return { allowed: [], blocked: relevant, versionMismatch: true };
+  }
+  const allowedNames = new Set(allowed.map(([name]) => name));
+  return {
+    allowed,
+    blocked: relevant.filter(([name]) => !allowedNames.has(name)),
+    versionMismatch: false,
+  };
+}
+
+function runAudit() {
+  const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+  const result = spawnSync(npm, ['audit', '--audit-level=moderate', '--omit=dev', '--json'], {
+    encoding: 'utf8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.error) throw result.error;
+
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch {
+    throw new Error(
+      result.stderr || result.stdout || `npm audit exited with status ${result.status}`
+    );
+  }
+  const lock = require('../package-lock.json');
+  return evaluateAudit(payload, lock);
+}
+
+function main() {
+  const result = runAudit();
+  if (result.blocked.length > 0) {
+    const suffix = result.versionMismatch ? ' (Opcore exception version mismatch)' : '';
+    console.error(
+      `Production dependency audit failed${suffix}: ${result.blocked.map(([name]) => name).join(', ')}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (result.allowed.length > 0) {
+    console.warn(
+      `Production dependency audit passed with pinned Opcore advisories: ${result.allowed
+        .map(([name]) => name)
+        .join(', ')}`
+    );
+    return;
+  }
+  console.log('Production dependency audit passed');
+}
+
+if (require.main === module) main();
+
+module.exports = { evaluateAudit };

package/scripts/opcore-agent-gate.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { extractToolRequest, isRecord, overlaysForTool } = require('./opcore-agent-tool-overlays');
+
+const validationTimeoutMs = 120_000;
+const maxFeedbackChars = 4000;
+const preWriteChecks = [
+  'typescript.syntax',
+  'typescript.types',
+  'typescript.lint',
+  'typescript.function-metrics',
+  'typescript.file-length',
+  'rust.source-hygiene',
+  'rust.fmt',
+  'rust.file-length',
+  'rust.function-metrics',
+  'docs.staleness',
+  'docs.freshness',
+  'docs.length',
+  'docs.dry',
+  'docs.content-quality',
+  'docs.code-blocks',
+  'docs.rules-why',
+];
+
+function parseArgs(argv) {
+  const args = { harness: 'unknown' };
+  let index = 0;
+  while (index < argv.length) {
+    const arg = argv[index];
+    const next = argv[index + 1];
+    if (arg === '--harness') args.harness = next || 'unknown';
+    else if (arg.startsWith('--harness=')) args.harness = arg.slice('--harness='.length);
+    else if (arg === '--repo') args.repo = next;
+    else if (arg.startsWith('--repo=')) args.repo = arg.slice('--repo='.length);
+    index += arg === '--harness' || arg === '--repo' ? 2 : 1;
+  }
+  return args;
+}
+
+function resolveRepoRoot(explicitRepo, cwd) {
+  if (explicitRepo) return path.resolve(explicitRepo);
+  const start = path.resolve(cwd || process.cwd());
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+    cwd: start,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  return result.status === 0 && result.stdout.trim() ? path.resolve(result.stdout.trim()) : start;
+}
+
+function runValidation(request) {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'zeroshot-opcore-prewrite-'));
+  const requestPath = path.join(tempDir, 'validation-request.json');
+  try {
+    fs.writeFileSync(requestPath, `${JSON.stringify(request)}\n`);
+    const opcoreEntrypoint = require.resolve('opcore');
+    const result = spawnSync(
+      process.execPath,
+      [
+        opcoreEntrypoint,
+        'validate',
+        'pre-write',
+        '--request-file',
+        requestPath,
+        '--timeout-ms',
+        String(validationTimeoutMs),
+        '--json',
+      ],
+      {
+        cwd: request.repo.repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }
+    );
+    if (result.error) throw result.error;
+    const payload = JSON.parse((result.stdout || '').trim());
+    if (!payload.receipt) {
+      throw new Error(result.stderr || result.stdout || `Opcore exited ${result.status}`);
+    }
+    return payload.receipt;
+  } finally {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function feedback(toolName, receipt) {
+  const summary = receipt.failureSummary?.message || 'Pre-write validation failed';
+  const checks = receipt.checks?.length ? ` checks=${receipt.checks.join(',')}` : '';
+  const paths = receipt.overlays?.paths?.length ? ` paths=${receipt.overlays.paths.join(',')}` : '';
+  const message = `Opcore write gate blocked ${toolName}: ${summary} status=${receipt.validationStatus}${checks}${paths}\n`;
+  return message.length <= maxFeedbackChars
+    ? message
+    : `${message.slice(0, maxFeedbackChars - 15).trimEnd()} [truncated]\n`;
+}
+
+async function readStdin() {
+  let input = '';
+  for await (const chunk of process.stdin) input += chunk.toString();
+  return input;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  let mapped;
+  try {
+    const raw = await readStdin();
+    if (!raw.trim()) return 0;
+    const envelope = JSON.parse(raw);
+    if (!isRecord(envelope)) throw new Error('hook payload must be a JSON object');
+    const tool = extractToolRequest(envelope);
+    if (!tool) return 0;
+    const repoRoot = resolveRepoRoot(args.repo, tool.cwd);
+    const overlays = await overlaysForTool(repoRoot, tool);
+    if (overlays.length === 0) return 0;
+    mapped = {
+      toolName: tool.toolName,
+      request: {
+        requestId: `zeroshot-opcore-agent-gate-${Date.now()}`,
+        repo: { repoRoot },
+        scope: { kind: 'files', files: overlays.map((overlay) => overlay.path) },
+        graph: { mode: 'optional', provider: 'opcore-graph' },
+        overlays,
+        checks: preWriteChecks,
+        reportMode: 'introduced',
+      },
+    };
+  } catch (error) {
+    process.stderr.write(
+      `Opcore write gate skipped: ${error instanceof Error ? error.message : String(error)}\n`
+    );
+    return 0;
+  }
+
+  try {
+    const receipt = runValidation(mapped.request);
+    if (receipt.ok) return 0;
+    process.stderr.write(feedback(mapped.toolName, receipt));
+    return 2;
+  } catch (error) {
+    process.stderr.write(
+      `Opcore write gate blocked ${mapped.toolName}: validation command failed: ${error instanceof Error ? error.message : String(error)}\n`
+    );
+    return 2;
+  }
+}
+
+main()
+  .then((exitCode) => {
+    process.exitCode = exitCode;
+  })
+  .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+  });