external-subagent 0.1.0

package/schema/external-subagent-public-api.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://external-subagent.invalid/schema/public-api.json",
+  "title": "external-subagent MCP public API",
+  "description": "The intentionally small external_subagent_* wire catalog.",
+  "type": "object",
+  "required": ["tools"],
+  "properties": {
+    "tools": {
+      "type": "array",
+      "const": ["external_subagent_cancel", "external_subagent_close", "external_subagent_list", "external_subagent_observe", "external_subagent_wait", "external_subagent_respond", "external_subagent_result", "external_subagent_send", "external_subagent_spawn", "external_subagent_status"]
+    },
+    "permission_mode": { "enum": ["build", "edit", "plan", "yolo"], "default": "build" },
+    "subagent_status": {
+      "type": "object",
+      "required": ["subagent", "configured", "enabled", "spawn_supported", "permission_modes", "model_selection", "effort_selection", "local", "auth", "hi"],
+      "properties": {
+        "subagent": { "enum": ["zcode", "dsh", "codex"] },
+        "configured": { "type": "boolean" },
+        "enabled": { "type": "boolean" },
+        "spawn_supported": { "type": "boolean" },
+        "permission_modes": {
+          "type": "array",
+          "items": { "enum": ["build", "edit", "plan", "yolo"] },
+          "uniqueItems": true
+        },
+        "model_selection": {
+          "type": "object",
+          "required": ["supported", "mode"],
+          "properties": {
+            "supported": { "type": "boolean" },
+            "mode": { "enum": ["native_only", "catalog_token"] }
+          },
+          "additionalProperties": false
+        },
+        "effort_selection": {
+          "type": "object",
+          "description": "Reasoning-effort steering capability. codex admits only its closed set; zcode and dsh pass a bounded [a-z0-9_] token through to the runtime.",
+          "required": ["supported", "mode"],
+          "properties": {
+            "supported": { "type": "boolean" },
+            "mode": { "enum": ["closed_set", "passthrough_token"] }
+          },
+          "additionalProperties": false
+        },
+        "local": { "$ref": "#/properties/subagent_scope_status" },
+        "auth": { "$ref": "#/properties/subagent_scope_status" },
+        "hi": { "$ref": "#/properties/subagent_scope_status" }
+      },
+      "additionalProperties": false
+    },
+    "subagent_scope_status": {
+      "type": "object",
+      "description": "Readiness conclusion only. Probe evidence (scope paths, version, checked_at_ms, reason) stays on the daemon RPC view for the CLI diagnose owner.",
+      "required": ["state"],
+      "properties": {
+        "state": { "enum": ["READY", "DEGRADED", "UNAVAILABLE", "UNKNOWN"] }
+      },
+      "additionalProperties": false
+    },
+    "spawn": {
+      "type": "object",
+      "required": ["repository", "prompt"],
+      "properties": {
+        "subagent": { "type": "string", "minLength": 1, "description": "Subagent route key; omission uses configured default_subagent or returns subagent_required. Null is invalid; dsh production spawn remains gated." },
+        "repository": { "type": "string", "minLength": 1 },
+        "permission_mode": { "$ref": "#/properties/permission_mode" },
+        "prompt": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 },
+        "effort": { "type": "string", "minLength": 1, "maxLength": 24, "pattern": "^[a-z0-9_]+$", "description": "Reasoning-effort token: 1..24 bytes of [a-z0-9_]. codex admits only low, medium, high or xhigh; zcode and dsh pass the bounded token through. Omission keeps the runtime default." },
+        "write_manifest": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "allOf": [
+        { "if": { "required": ["permission_mode"], "properties": { "permission_mode": { "const": "plan" } } },
+          "then": { "properties": { "write_manifest": { "maxItems": 0 } } } }
+      ],
+      "additionalProperties": false
+    },
+    "list": {
+      "type": "object",
+      "required": ["repository"],
+      "properties": {
+        "subagent": { "type": "string", "minLength": 1 },
+        "repository": { "type": "string", "minLength": 1 },
+        "phase": { "type": ["string", "null"], "default": null },
+        "outcome": { "type": ["string", "null"], "default": null },
+        "cursor": { "type": ["string", "null"], "default": null },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }
+      },
+      "additionalProperties": false
+    },
+    "wait": {
+      "type": "object",
+      "description": "Wait returns early only for an actionable pending request (permission requests need allow/deny; user-input requests carry the full embedded question and need answer with non-empty content) or a terminal result; ordinary progress, message receipts, already-responded and unsupported requests never wake it. The pending_requests output projection is capped at 100 actionable records, while the wake decision scans the full pending set. activity carries the latest text tail, a 200-char verified reasoning tail, tool calls started in the last 60 seconds, and telemetry status.",
+      "required": ["agent_id"],
+      "properties": {
+        "agent_id": { "type": "integer", "minimum": 10000000, "maximum": 99999999 },
+        "wait_time": { "type": "integer", "minimum": 0, "maximum": 299, "default": 290 }
+        ,"message_id": { "type": ["string", "null"] }
+      },
+      "additionalProperties": false
+    },
+    "observe": {
+      "type": "object",
+      "required": ["agent_id"],
+      "properties": {
+        "agent_id": { "type": "integer", "minimum": 10000000, "maximum": 99999999 }
+      },
+      "additionalProperties": false
+    },
+    "result": {
+      "type": "object",
+      "description": "Pages bounded terminal task-owned text with the offset and limit continuation contract. Questions from user-input requests are embedded in full in wait projections, not paged here.",
+      "required": ["agent_id"],
+      "properties": {
+        "agent_id": { "type": "integer", "minimum": 10000000, "maximum": 99999999 },
+        "offset": { "type": "integer", "minimum": 0, "default": 0 },
+        "limit": { "type": "integer", "minimum": 1, "maximum": 262144, "default": 262144 }
+      },
+      "additionalProperties": false
+    },
+    "result_projection": {
+      "type": "object",
+      "required": ["outcome", "final_text", "partial", "offset", "total_bytes", "next_offset", "complete"],
+      "properties": {
+        "outcome": { "enum": ["COMPLETED", "FAILED", "CANCELLED", "TIMED_OUT", "RUNTIME_LOST", "RESULT_INVALID"] },
+        "final_text": { "type": "string" },
+        "partial": { "type": "boolean" },
+        "offset": { "type": "integer", "minimum": 0 },
+        "total_bytes": { "type": "integer", "minimum": 0 },
+        "next_offset": { "type": ["integer", "null"], "minimum": 0 },
+        "complete": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "question_projection": {
+      "type": "object",
+      "description": "Embedded question of an answerable user-input request in the wait projection's pending_requests entries; wait is the only retrieval surface, so a question beyond the embed cap is marked truncated instead of paged.",
+      "required": ["text", "truncated"],
+      "properties": {
+        "text": { "type": "string" },
+        "truncated": { "type": "boolean" }
+      },
+      "additionalProperties": false
+    },
+    "error_projection": {
+      "type": "object",
+      "required": ["error"],
+      "properties": {
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "properties": {
+            "code": { "type": "string", "minLength": 1 },
+            "message": { "type": "string", "minLength": 1 },
+            "component": { "type": "string", "minLength": 1 },
+            "operation": { "type": "string", "minLength": 1 },
+            "request_id": { "type": "string", "minLength": 1 },
+            "agent_id": { "type": "integer", "minimum": 10000000, "maximum": 99999999 },
+            "prompt_count": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "contracts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "external_subagent_status": { "input": [], "output": ["mcp_version", "components", "capabilities", "subagents"] },
+        "external_subagent_spawn": { "input": ["subagent", "repository", "permission_mode", "prompt", "model", "effort", "write_manifest"], "output": ["agent_id", "status"], "idempotent": false },
+        "external_subagent_wait": { "input": ["agent_id", "wait_time", "message_id"], "output": ["task", "pending_requests", "result_available", "activity", "result", "instruction", "timed_out", "message_receipt"] },
+        "external_subagent_observe": { "input": ["agent_id"], "output": ["tools", "reasoning", "coverage"], "idempotent": true },
+        "external_subagent_list": { "input": ["subagent", "repository", "phase", "outcome", "cursor", "limit"], "output": ["tasks", "next_cursor"] },
+        "external_subagent_send": { "input": ["agent_id", "message_id", "content"], "output": ["message_id", "disposition"] },
+        "external_subagent_respond": { "input": ["agent_id", "request_id", "decision", "content"], "output": ["disposition", "requested_decision", "effective_decision", "policy_overrode", "policy_reason_code"] },
+        "external_subagent_cancel": { "input": ["agent_id"], "output": ["task"] },
+        "external_subagent_result": { "input": ["agent_id", "offset", "limit"], "output": ["task", "result"] },
+        "external_subagent_close": { "input": ["agent_id"], "output": ["task"] }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/schema/zas-observation-v1.1.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "external-subagent suspicion-only observation",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["tools", "reasoning", "coverage"],
+  "properties": {
+    "tools": {
+      "type": "array",
+      "maxItems": 3,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["tool_name", "call_count", "recent_calls"],
+        "properties": {
+          "tool_name": { "type": "string", "minLength": 1 },
+          "call_count": { "type": "integer", "minimum": 1 },
+          "recent_calls": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 5,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["seq", "tool_call_id", "arguments", "arguments_truncated", "redacted_fields"],
+              "properties": {
+                "seq": { "type": "integer", "minimum": 1 },
+                "tool_call_id": { "type": "string", "minLength": 1 },
+                "arguments": { "type": "object" },
+                "arguments_truncated": { "type": "boolean" },
+                "redacted_fields": { "type": "integer", "minimum": 0 }
+              }
+            }
+          }
+        }
+      }
+    },
+    "reasoning": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text", "truncated"],
+      "properties": {
+        "text": { "type": "string", "maxLength": 200 },
+        "truncated": { "type": "boolean" }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tool_history_complete", "reasoning_complete", "dropped_events"],
+      "properties": {
+        "tool_history_complete": { "type": "boolean" },
+        "reasoning_complete": { "type": "boolean" },
+        "dropped_events": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schema/zas-public-reasoning-source.json

@@ -0,0 +1,14 @@
+{
+  "schema": "zas-public-reasoning-source/1",
+  "status": "VERIFIED_RUNTIME_PUBLIC",
+  "runtime_path": "/Applications/ZCode.app/Contents/Resources/glm/zcode.cjs",
+  "runtime_version": "3.11.2",
+  "runtime_sha256": "e9f1868c0fdb863537ed910ee3828b9be96b8c2fd805473f63b439e1113266b8",
+  "wire_method": "session/event",
+  "event_type_pointer": "/params/type",
+  "event_type": "model.streaming",
+  "event_discriminator_pointer": "/params/payload/kind",
+  "event_discriminator_value": "reasoning_delta",
+  "delta_pointer": "/params/payload/delta",
+  "explicitly_excluded_key": "encrypted_content"
+}

package/scripts/release/build-native-payload.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Build the versioned native payload for the npm package: release binaries
+// for external-subagentd and external-subagent-mcp are copied into
+// npm/native/darwin-arm64 together with a deterministic payload.json manifest
+// (version, platform, per-file bytes/sha256/mode).  Installed-package code
+// verifies against this manifest, so it must never contain volatile fields.
+//
+// `--variant debug` stages the parallel development payload instead: the same
+// cargo artifacts are copied under debug names into npm/native-debug/darwin-arm64
+// (manifest product external-subagent-debug), and the debug plugin source is
+// staged at plugins/codex/external-subagent-debug.  The debug payload is a
+// development checkout product and is rejected from release tarballs by
+// scripts/release/check-native-tarball.mjs.
+//
+// --if-stale skips the cargo build when the staged binaries are newer than
+// every source input and the manifest already matches the package version.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { stageDebugPlugin } from './stage-debug-plugin.mjs';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const variantIndex = process.argv.indexOf('--variant');
+const variant = variantIndex === -1 ? '' : (process.argv[variantIndex + 1] ?? '');
+if (variant !== '' && variant !== 'debug') {
+  process.stderr.write(`unknown variant: ${variant} (supported: debug)\n`);
+  process.exit(2);
+}
+const isDebug = variant === 'debug';
+const nativeDirName = isDebug ? 'native-debug' : 'native';
+const productName = isDebug ? 'external-subagent-debug' : 'external-subagent';
+const binaries = isDebug
+  ? [['external-subagentd', 'external-subagent-debugd'], ['external-subagent-mcp', 'external-subagent-debug-mcp']]
+  : [['external-subagentd', 'external-subagentd'], ['external-subagent-mcp', 'external-subagent-mcp']];
+const platformDir = path.join(packageRoot, 'npm', nativeDirName, 'darwin-arm64');
+const manifestPath = path.join(platformDir, 'payload.json');
+const sourceRoots = ['crates', 'profiles'].map((dir) => path.join(packageRoot, dir))
+  .concat([path.join(packageRoot, 'Cargo.toml'), path.join(packageRoot, 'Cargo.lock')]);
+
+function packageVersion() {
+  return JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
+}
+
+function sha256(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function newestInputMs() {
+  let newest = 0;
+  const walk = (entry) => {
+    const stat = fs.statSync(entry);
+    if (stat.isFile()) { newest = Math.max(newest, stat.mtimeMs); return; }
+    for (const child of fs.readdirSync(entry)) {
+      if (child === 'target' || child.startsWith('.')) continue;
+      walk(path.join(entry, child));
+    }
+  };
+  for (const root of sourceRoots) if (fs.existsSync(root)) walk(root);
+  return newest;
+}
+
+function stagedIsCurrent(version) {
+  if (!fs.existsSync(manifestPath)) return false;
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch { return false; }
+  if (manifest.version !== version || manifest.platform !== 'darwin-arm64' || manifest.product !== productName) return false;
+  const inputs = newestInputMs();
+  for (const file of manifest.files) {
+    const target = path.join(platformDir, file.name);
+    if (!fs.existsSync(target)) return false;
+    const stat = fs.statSync(target);
+    if (stat.mtimeMs < inputs) return false;
+    if (stat.size !== file.bytes || sha256(fs.readFileSync(target)) !== file.sha256) return false;
+  }
+  return true;
+}
+
+const version = packageVersion();
+// Under an npm lifecycle (prepack) stdout belongs to npm's `--json` protocol;
+// diagnostics go to stderr there so pack output stays machine-parseable.
+const note = (text) => (process.env.npm_lifecycle_event ? process.stderr : process.stdout).write(text);
+if (process.argv.includes('--if-stale') && stagedIsCurrent(version)) {
+  note(`native payload already current at ${version}${isDebug ? ' (debug)' : ''}\n`);
+  process.exit(0);
+}
+
+const build = spawnSync('cargo', ['build', '--release', '-p', 'external-daemon', '-p', 'external-mcp'], {
+  cwd: packageRoot, stdio: 'inherit',
+});
+if (build.status !== 0) {
+  process.stderr.write('cargo release build failed\n');
+  process.exit(build.status ?? 1);
+}
+
+fs.mkdirSync(platformDir, { recursive: true });
+const files = [];
+for (const [source, name] of binaries) {
+  const sourcePath = path.join(packageRoot, 'target', 'release', source);
+  if (!fs.existsSync(sourcePath)) {
+    process.stderr.write(`release binary missing: ${sourcePath}\n`);
+    process.exit(1);
+  }
+  const target = path.join(platformDir, name);
+  fs.copyFileSync(sourcePath, target);
+  fs.chmodSync(target, 0o755);
+  const bytes = fs.readFileSync(target);
+  files.push({ name, bytes: bytes.length, mode: '755', sha256: sha256(bytes) });
+}
+
+const manifest = { schema_version: 1, product: productName, version, platform: 'darwin-arm64', files };
+fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o644 });
+if (isDebug) {
+  const stagedPlugin = stageDebugPlugin(packageRoot);
+  note(`native payload ${version} (debug) staged: ${files.map((file) => file.name).join(', ')}\nplugin source staged: ${stagedPlugin}\n`);
+} else {
+  note(`native payload ${version} staged: ${files.map((file) => file.name).join(', ')}\n`);
+}

package/scripts/release/check-native-tarball.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// Release pack static checks.  Two modes:
+//   check-native-tarball.mjs [package.tgz]   verify a packed tarball (entries,
+//                                             payload manifest consistency,
+//                                             forbidden development material)
+//   check-native-tarball.mjs --staged        verify only the staged payload
+//                                             (npm/native/darwin-arm64) against
+//                                             the package version — the publish
+//                                             gate, since `npm publish` packs
+//                                             into a private temp directory no
+//                                             lifecycle script can inspect.
+// Without --staged the tarball is resolved from: the explicit argument, the
+// npm --pack-destination directory (set during `npm pack` lifecycles), or the
+// newest matching tgz in the working directory.  A dry run (npm pack --dry-run)
+// or a publish (no local tarball) skips the tarball checks and still runs the
+// staged payload checks.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const stagedOnly = process.argv.includes('--staged');
+const explicit = process.argv[2] && !process.argv[2].startsWith('--') ? process.argv[2] : null;
+const dryRun = process.env.npm_config_dry_run === 'true';
+
+function findTarball() {
+  if (explicit) return explicit;
+  const candidates = [];
+  const packDestination = process.env.npm_config_pack_destination;
+  if (packDestination) candidates.push(packDestination);
+  candidates.push(process.cwd());
+  for (const dir of candidates) {
+    const staged = fs.readdirSync(dir).filter((name) => /^external-subagent-\d+\.\d+\.\d+\.tgz$/.test(name)).sort();
+    if (staged.length > 0) return path.join(dir, staged[staged.length - 1]);
+  }
+  return null;
+}
+
+let failed = false;
+let tgz = null;
+// Under an npm lifecycle (postpack/prepublishOnly) stdout belongs to npm's
+// `--json` protocol; diagnostics go to stderr there.
+const note = (text) => (process.env.npm_lifecycle_event ? process.stderr : process.stdout).write(text);
+if (!stagedOnly) {
+  tgz = findTarball();
+  if (tgz === null && !dryRun && explicit === null) {
+    // `npm publish` packs into a private temp directory: no tarball to check
+    // here.  The prepublishOnly staged gate covers the payload; the tarball
+    // entry checks run on every `npm pack`.
+    note('no local packed tarball to check (publish or explicit run without one); running staged payload checks only\n');
+  }
+  if (tgz !== null) {
+    const required = [
+      'package/package.json',
+      'package/bin/external-subagent.mjs',
+      'package/bin/external-subagent-mcp.mjs',
+      'package/bin/external-subagent-debug.mjs',
+      'package/bin/external-subagent-debug-mcp.mjs',
+      'package/cli/main.mjs',
+      'package/npm/native/darwin-arm64/external-subagentd',
+      'package/npm/native/darwin-arm64/external-subagent-mcp',
+      'package/npm/native/darwin-arm64/payload.json',
+      'package/plugins/codex/external-subagent/.codex-plugin/plugin.json',
+      'package/plugins/codex/external-subagent/.mcp.json',
+      'package/launchd/com.external-subagent.daemon.plist.template',
+      'package/LICENSE',
+    ];
+
+    const listing = spawnSync('tar', ['-tzf', tgz], { encoding: 'utf8' });
+    if (listing.status !== 0) {
+      process.stderr.write(`cannot list tarball: ${listing.stderr}\n`);
+      process.exit(1);
+    }
+    const entries = listing.stdout.split('\n').filter(Boolean);
+
+    for (const entry of required) {
+      if (!entries.includes(entry)) { process.stderr.write(`missing release entry: ${entry}\n`); failed = true; }
+    }
+    // The debug payload and debug plugin source are development-checkout build
+    // artifacts; a tarball carrying them would ship ~10 MB of bytes no
+    // installed release consumer can verify.
+    const forbidden = /(^|\/)(\.agent-work|\.git|target|tests|node_modules|\.npm|workspace)(\/|$)|(^|\/)npm\/native-debug(\/|$)|(^|\/)plugins\/codex\/external-subagent-debug(\/|$)|\.sqlite3$|\.log$|credentials|\.DS_Store$/u;
+    for (const entry of entries) {
+      if (forbidden.test(entry)) { process.stderr.write(`forbidden release material: ${entry}\n`); failed = true; }
+    }
+
+    const packedPackage = JSON.parse(spawnSync('tar', ['-xzf', tgz, '-O', 'package/package.json'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }).stdout);
+    const manifestText = spawnSync('tar', ['-xzf', tgz, '-O', 'package/npm/native/darwin-arm64/payload.json'], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }).stdout;
+    const manifest = JSON.parse(manifestText);
+    if (manifest.version !== packedPackage.version) {
+      process.stderr.write(`payload version ${manifest.version} does not match package version ${packedPackage.version}\n`);
+      failed = true;
+    }
+  }
+}
+
+// Staged payload checks run in every mode (pack, publish, dry run): the
+// package version and the staged native binaries must agree right where the
+// tarball is built from.
+const repoPackage = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+const stagedManifest = JSON.parse(fs.readFileSync(path.join(process.cwd(), 'npm', 'native', 'darwin-arm64', 'payload.json'), 'utf8'));
+if (stagedManifest.version !== repoPackage.version) {
+  process.stderr.write(`staged payload version ${stagedManifest.version} does not match package version ${repoPackage.version}\n`);
+  failed = true;
+}
+if (stagedManifest.product !== 'external-subagent') {
+  process.stderr.write(`staged payload product ${stagedManifest.product} is not the release payload\n`);
+  failed = true;
+}
+
+for (const name of ['external-subagentd', 'external-subagent-mcp']) {
+  const local = path.join(process.cwd(), 'npm', 'native', 'darwin-arm64', name);
+  const file = spawnSync('file', ['-b', local], { encoding: 'utf8' });
+  if (!/Mach-O 64-bit executable arm64/u.test(file.stdout)) {
+    process.stderr.write(`${name} is not a Mach-O arm64 executable: ${file.stdout.trim()}\n`);
+    failed = true;
+  }
+  const mode = spawnSync('stat', ['-f', '%Lp', local], { encoding: 'utf8' }).stdout.trim();
+  if (mode !== '755') { process.stderr.write(`${name} has release mode ${mode}, expected 755\n`); failed = true; }
+}
+
+if (failed) process.exit(1);
+note(stagedOnly
+  ? `staged release payload checks passed (${repoPackage.version})\n`
+  : `release tarball static checks passed: ${tgz ? path.basename(tgz) : 'staged payload only'}\n`);

package/scripts/release/stage-debug-plugin.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// Stage the debug-variant plugin source at plugins/codex/external-subagent-debug
+// from the release source at plugins/codex/external-subagent: a byte-level copy
+// with the plugin identity renamed (plugin.json name/displayName, the skill
+// directory and its frontmatter name).  The .mcp.json placeholder and the
+// hooks/scripts/lib payloads stay identical — the host bindings rewrite the
+// placeholder at staging time, and tool names are the daemon's, not the
+// plugin's.  The generated tree is a build artifact (gitignored) owned by
+// build-native-payload.mjs --variant debug.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEBUG_PLUGIN_NAME = 'external-subagent-debug';
+const SOURCE_PLUGIN_NAME = 'external-subagent';
+
+export function stageDebugPlugin(packageRoot) {
+  const source = path.join(packageRoot, 'plugins', 'codex', SOURCE_PLUGIN_NAME);
+  const target = path.join(packageRoot, 'plugins', 'codex', DEBUG_PLUGIN_NAME);
+  if (!fs.existsSync(path.join(source, '.codex-plugin', 'plugin.json'))) {
+    throw new Error(`release plugin source is missing: ${source}`);
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+  fs.cpSync(source, target, { recursive: true });
+  const rmJunk = (dir) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const child = path.join(dir, entry.name);
+      if (entry.isDirectory()) rmJunk(child);
+      else if (entry.name === '.DS_Store') fs.rmSync(child);
+    }
+  };
+  rmJunk(target);
+
+  const manifestPath = path.join(target, '.codex-plugin', 'plugin.json');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  manifest.name = DEBUG_PLUGIN_NAME;
+  manifest.interface = {
+    ...manifest.interface,
+    displayName: `${manifest.interface?.displayName ?? SOURCE_PLUGIN_NAME} Debug`,
+    shortDescription: `Debug instance: ${manifest.interface?.shortDescription ?? ''}`.trim(),
+  };
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  fs.renameSync(path.join(target, 'skills', SOURCE_PLUGIN_NAME), path.join(target, 'skills', DEBUG_PLUGIN_NAME));
+  const skillPath = path.join(target, 'skills', DEBUG_PLUGIN_NAME, 'SKILL.md');
+  const skill = fs.readFileSync(skillPath, 'utf8');
+  const rewritten = skill.replace(`name: ${SOURCE_PLUGIN_NAME}\n`, `name: ${DEBUG_PLUGIN_NAME}\n`, 1);
+  fs.writeFileSync(skillPath, rewritten);
+  return target;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const packageRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', '..');
+  try {
+    const target = stageDebugPlugin(packageRoot);
+    process.stdout.write(`debug plugin source staged: ${target}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  }
+}

package/scripts/release/test-installed-tarball.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Controlled-prefix install check for the packed artifact: install the tgz
+// into a throwaway npm prefix with an isolated HOME and npm cache, then verify
+// the staged bin entries, install-only HOME purity, an explicit init (with
+// launchd neutralized), and the resulting LaunchAgent/binding/registry files.
+// This never touches the real user HOME, the real ~/.codex, or launchd.
+// Usage: test-installed-tarball.mjs [package.tgz]
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: 'utf8', ...options });
+  if (result.status !== 0) {
+    process.stderr.write(`command failed: ${command} ${args.join(' ')}\n${result.stderr || result.stdout}\n`);
+    process.exit(result.status ?? 1);
+  }
+  return result;
+}
+
+const tgzArgument = process.argv[2] || path.join(process.cwd(), (fs.readdirSync(process.cwd()).filter((name) => /^external-subagent-\d+\.\d+\.\d+\.tgz$/.test(name)).sort().slice(-1)[0] || ''));
+const tgz = tgzArgument ? path.resolve(tgzArgument) : '';
+if (!tgz || !fs.existsSync(tgz)) {
+  process.stderr.write('no packed tarball found; run npm pack first or pass the tgz path\n');
+  process.exit(2);
+}
+
+const work = fs.mkdtempSync(path.join(os.tmpdir(), 'external-subagent-prefix-'));
+const prefix = path.join(work, 'prefix');
+const home = path.join(work, 'home');
+fs.mkdirSync(home, { recursive: true });
+const cache = path.join(work, 'npm-cache');
+const env = { ...process.env, HOME: home, CODEX_HOME: path.join(home, '.codex'), EXTERNAL_SUBAGENT_TEST_NO_LAUNCHCTL: '1', npm_config_cache: cache };
+
+try {
+  run('npm', ['install', '--global', `--prefix=${prefix}`, '--no-audit', '--no-fund', tgz], { cwd: work, env });
+  const cli = path.join(prefix, 'bin', 'external-subagent');
+  const packageRoot = path.join(prefix, 'lib', 'node_modules', 'external-subagent');
+  for (const target of [cli, path.join(prefix, 'bin', 'external-subagent-mcp'), path.join(packageRoot, 'npm', 'native', 'darwin-arm64', 'external-subagentd')]) {
+    fs.accessSync(target, fs.constants.X_OK);
+  }
+  run(cli, ['version'], { env });
+  const homeEntries = fs.readdirSync(home).filter((entry) => entry !== '.npm' && entry !== '.cache');
+  if (homeEntries.length !== 0) {
+    process.stderr.write(`install-only must not write the home; found: ${homeEntries.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  // Use the real codex CLI when present (it only ever sees the throwaway
+  // CODEX_HOME); otherwise fall back to an explicit skip so the check still
+  // verifies the install/service layer without pretending Codex ran.
+  const codexAvailable = spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0;
+  const initArgs = ['init', '--skip-runtime-probe'];
+  if (!codexAvailable) initArgs.push('--skip-codex-plugin');
+  const init = JSON.parse(run(cli, initArgs, { env }).stdout);
+  if (!init.ok || !init.installed) {
+    process.stderr.write(`init did not complete: ${JSON.stringify(init)}\n`);
+    process.exit(1);
+  }
+  const expectedArtifacts = [
+    path.join(home, 'Library', 'LaunchAgents', 'com.external-subagent.daemon.plist'),
+    path.join(home, 'Library', 'Application Support', 'external-subagent', 'config.json'),
+    path.join(home, 'plugins', 'external-subagent', '.mcp.json'),
+  ];
+  if (codexAvailable) expectedArtifacts.push(path.join(home, '.agents', 'plugins', 'marketplace.json'));
+  for (const target of expectedArtifacts) {
+    if (!fs.existsSync(target)) { process.stderr.write(`init artifact missing: ${target}\n`); process.exit(1); }
+  }
+  process.stdout.write(`${JSON.stringify({ installed: true, codex_cli: codexAvailable ? 'real' : 'skipped', prefix: `${prefix} (removed)`, payload: init.payload, service: init.service }, null, 2)}\n`);
+} finally {
+  fs.rmSync(work, { recursive: true, force: true });
+}